Preface and Legal Notices
*************************

This is the Reference Manual for the MySQL Database System, version 5.7,
through release 5.7.23.  Differences between minor versions of MySQL 5.7
are noted in the present text with reference to release numbers (5.7.X).
For license information, see the Legal Notices.

This manual is not intended for use with older versions of the MySQL
software due to the many functional and other differences between MySQL
5.7 and previous versions.  If you are using an earlier release of the
MySQL software, please refer to the appropriate manual.  For example,
'MySQL 5.6 Reference Manual' (http://dev.mysql.com/doc/refman/5.6/en/)
covers the 5.6 series of MySQL software releases.

Licensing information--MySQL 5.7

This product may include third-party software, used under license.  If
you are using a _Commercial_ release of MySQL 5.7, see the MySQL 5.7
Commercial Release License Information User Manual
(http://downloads.mysql.com/docs/licenses/mysqld-5.7-com-en.pdf) for
licensing information, including licensing information relating to
third-party software that may be included in this Commercial release.
If you are using a _Community_ release of MySQL 5.7, see the MySQL 5.7
Community Release License Information User Manual
(http://downloads.mysql.com/docs/licenses/mysqld-5.7-gpl-en.pdf) for
licensing information, including licensing information relating to
third-party software that may be included in this Community release.

Licensing information--MySQL NDB Cluster 7.5

This product may include third-party software, used under license.  If
you are using a _Commercial_ release of NDB Cluster 7.5, see the MySQL
NDB Cluster 7.5 Commercial Release License Information User Manual
(http://downloads.mysql.com/docs/licenses/cluster-7.5-com-en.pdf) for
licensing information relating to third-party software that may be
included in this Commercial release.  If you are using a _Community_
release of NDB Cluster 7.5, see the MySQL NDB Cluster 7.5 Community
Release License Information User Manual
(http://downloads.mysql.com/docs/licenses/cluster-7.5-gpl-en.pdf) for
licensing information relating to third-party software that may be
included in this Community release.

Licensing information--MySQL NDB Cluster 7.6

If you are using a Developer Preview release of NDB Cluster 7.6, see the
MySQL NDB Cluster 7.6 Community Release License Information User Manual
(http://downloads.mysql.com/docs/licenses/cluster-7.6-gpl-en.pdf) for
licensing information relating to third-party software that may be
included in this Community release.

*Legal Notices*

Copyright (C) 1997, 2018, Oracle and/or its affiliates.  All rights
reserved.

This software and related documentation are provided under a license
agreement containing restrictions on use and disclosure and are
protected by intellectual property laws.  Except as expressly permitted
in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute,
exhibit, perform, publish, or display any part, in any form, or by any
means.  Reverse engineering, disassembly, or decompilation of this
software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and
is not warranted to be error-free.  If you find any errors, please
report them to us in writing.

If this is software or related documentation that is delivered to the
U.S. Government or anyone licensing it on behalf of the U.S. Government,
then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating
system, integrated software, any programs installed on the hardware,
and/or documentation, delivered to U.S. Government end users are
"commercial computer software" pursuant to the applicable Federal
Acquisition Regulation and agency-specific supplemental regulations.  As
such, use, duplication, disclosure, modification, and adaptation of the
programs, including any operating system, integrated software, any
programs installed on the hardware, and/or documentation, shall be
subject to license terms and license restrictions applicable to the
programs.  No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of
information management applications.  It is not developed or intended
for use in any inherently dangerous applications, including applications
that may create a risk of personal injury.  If you use this software or
hardware in dangerous applications, then you shall be responsible to
take all appropriate fail-safe, backup, redundancy, and other measures
to ensure its safe use.  Oracle Corporation and its affiliates disclaim
any liability for any damages caused by use of this software or hardware
in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its
affiliates.  Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel
Corporation.  All SPARC trademarks are used under license and are
trademarks or registered trademarks of SPARC International, Inc.  AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices.  UNIX is a registered
trademark of The Open Group.

This software or hardware and documentation may provide access to or
information about content, products, and services from third parties.
Oracle Corporation and its affiliates are not responsible for and
expressly disclaim all warranties of any kind with respect to
third-party content, products, and services unless otherwise set forth
in an applicable agreement between you and Oracle.  Oracle Corporation
and its affiliates will not be responsible for any loss, costs, or
damages incurred due to your access to or use of third-party content,
products, or services, except as set forth in an applicable agreement
between you and Oracle.

This documentation is NOT distributed under a GPL license.  Use of this
documentation is subject to the following terms:

You may create a printed copy of this documentation solely for your own
personal use.  Conversion to other formats is allowed as long as the
actual content is not altered or edited in any way.  You shall not
publish or distribute this documentation in any form or on any media,
except if you distribute the documentation in a manner similar to how
Oracle disseminates it (that is, electronically for download on a Web
site with the software) or on a CD-ROM or similar medium, provided
however that the documentation is disseminated together with the
software on the same medium.  Any other use, such as any dissemination
of printed copies or use of this documentation, in whole or in part, in
another publication, requires the prior written consent from an
authorized representative of Oracle.  Oracle and/or its affiliates
reserve any and all rights to this documentation not expressly granted
above.

*Documentation Accessibility*

For information about Oracle's commitment to accessibility, visit the
Oracle Accessibility Program website at

<http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc>.

*Access to Oracle Support*

Oracle customers that have purchased support have access to electronic
support through My Oracle Support.  For information, visit

<http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info> or visit
<http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs> if you are
hearing impaired.

1 General Information
*********************

The MySQL(tm) software delivers a very fast, multi-threaded, multi-user,
and robust SQL (Structured Query Language) database server.  MySQL
Server is intended for mission-critical, heavy-load production systems
as well as for embedding into mass-deployed software.  Oracle is a
registered trademark of Oracle Corporation and/or its affiliates.  MySQL
is a trademark of Oracle Corporation and/or its affiliates, and shall
not be used by Customer without Oracle's express written authorization.
Other names may be trademarks of their respective owners.

The MySQL software is Dual Licensed.  Users can choose to use the MySQL
software as an Open Source product under the terms of the GNU General
Public License (<http://www.fsf.org/licenses/>) or can purchase a
standard commercial license from Oracle.  See
<http://www.mysql.com/company/legal/licensing/> for more information on
our licensing policies.

The following list describes some sections of particular interest in
this manual:

   * For a discussion of MySQL Database Server capabilities, see
     features.

   * For an overview of new MySQL features, see mysql-nutshell.
     For information about the changes in each version, see the Release
     Notes (http://dev.mysql.com/doc/relnotes/mysql/5.7/en/).

   * For installation instructions, see installing.  For
     information about upgrading MySQL, see upgrading.

   * For a tutorial introduction to the MySQL Database Server, see
     tutorial.

   * For information about configuring and administering MySQL Server,
     see server-administration.

   * For information about security in MySQL, see security.

   * For information about setting up replication servers, see
     replication.

   * For information about MySQL Enterprise, the commercial MySQL
     release with advanced features and management tools, see
     mysql-enterprise.

   * For answers to a number of questions that are often asked
     concerning the MySQL Database Server and its capabilities, see
     faqs.

   * For a history of new features and bug fixes, see the Release Notes
     (http://dev.mysql.com/doc/relnotes/mysql/5.7/en/).

*Important*:

To report problems or bugs, please use the instructions at
bug-reports.  If you find a sensitive security bug in MySQL Server,
please let us know immediately by sending an email message to
<secalert_us@oracle.com>.  Exception: Support customers should report
all problems, including security bugs, to Oracle Support.

1.1 About This Manual
=====================

This is the Reference Manual for the MySQL Database System, version 5.7,
through release 5.7.23.  Differences between minor versions of MySQL 5.7
are noted in the present text with reference to release numbers (5.7.X).

This manual is not intended for use with older versions of the MySQL
software due to the many functional and other differences between MySQL
5.7 and previous versions.  If you are using an earlier release of the
MySQL software, please refer to the appropriate manual.  For example,
'MySQL 5.6 Reference Manual' (http://dev.mysql.com/doc/refman/5.6/en/)
covers the 5.6 series of MySQL software releases.

Because this manual serves as a reference, it does not provide general
instruction on SQL or relational database concepts.  It also does not
teach you how to use your operating system or command-line interpreter.

The MySQL Database Software is under constant development, and the
Reference Manual is updated frequently as well.  The most recent version
of the manual is available online in searchable form at
<http://dev.mysql.com/doc/>.  Other formats also are available there,
including HTML, PDF, and EPUB versions.

The Reference Manual source files are written in DocBook XML format.
The HTML version and other formats are produced automatically, primarily
using the DocBook XSL stylesheets.  For information about DocBook, see
<http://docbook.org/>

If you have questions about using MySQL, you can ask them using our
mailing lists or forums.  See mailing-lists, and forums.
If you have suggestions concerning additions or corrections to the
manual itself, please send them to the
<http://www.mysql.com/company/contact/>.

This manual was originally written by David Axmark and Michael 'Monty'
Widenius.  It is maintained by the MySQL Documentation Team, consisting
of Chris Cole, Paul DuBois, Margaret Fisher, Edward Gilmore, Stefan
Hinz, David Moss, Philip Olson, Daniel Price, Daniel So, and Jon
Stephens.

1.2 Typographical and Syntax Conventions
========================================

This manual uses certain typographical conventions:

   * 'Text in this style' is used for SQL statements; database, table,
     and column names; program listings and source code; and environment
     variables.  Example: 'To reload the grant tables, use the 'FLUSH
     PRIVILEGES' statement.'

   * Text in this style indicates input that you type in examples.

   * 'Text in this style' indicates the names of executable programs and
     scripts, examples being 'mysql'. (the MySQL
     command-line client program) and 'mysqld'. (the MySQL
     server executable).

   * TEXT IN THIS STYLE is used for variable input for which you should
     substitute a value of your own choosing.

   * _Text in this style_ is used for emphasis.

   * *Text in this style* is used in table headings and to convey
     especially strong emphasis.

   * 'Text in this style' is used to indicate a program option that
     affects how the program is executed, or that supplies information
     that is needed for the program to function in a certain way.
     _Example_: 'The '--host' option (short form '-h') tells the
     'mysql' client program the hostname or IP address of the
     MySQL server that it should connect to'.

   * File names and directory names are written like this: 'The global
     'my.cnf' file is located in the '/etc' directory.'

   * Character sequences are written like this: 'To specify a wildcard,
     use the ''%'' character.'

When commands are shown that are meant to be executed from within a
particular program, the prompt shown preceding the command indicates
which command to use.  For example, 'shell>' indicates a command that
you execute from your login shell, 'root-shell>' is similar but should
be executed as 'root', and 'mysql>' indicates a statement that you
execute from the 'mysql' client program:

     shell> type a shell command here
     root-shell> type a shell command as ROOT here
     mysql> type a mysql statement here

In some areas different systems may be distinguished from each other to
show that commands should be executed in two different environments.
For example, while working with replication the commands might be
prefixed with 'master' and 'slave':

     master> type a mysql command on the replication master here
     slave> type a mysql command on the replication slave here

The 'shell' is your command interpreter.  On Unix, this is typically a
program such as 'sh', 'csh', or 'bash'.  On Windows, the equivalent
program is 'command.com' or 'cmd.exe', typically run in a console
window.

When you enter a command or statement shown in an example, do not type
the prompt shown in the example.

Database, table, and column names must often be substituted into
statements.  To indicate that such substitution is necessary, this
manual uses DB_NAME, TBL_NAME, and COL_NAME.  For example, you might see
a statement like this:

     mysql> SELECT COL_NAME FROM DB_NAME.TBL_NAME;

This means that if you were to enter a similar statement, you would
supply your own database, table, and column names, perhaps like this:

     mysql> SELECT author_name FROM biblio_db.author_list;

SQL keywords are not case-sensitive and may be written in any
lettercase.  This manual uses uppercase.

In syntax descriptions, square brackets (''['' and '']'') indicate
optional words or clauses.  For example, in the following statement, 'IF
EXISTS' is optional:

     DROP TABLE [IF EXISTS] TBL_NAME

When a syntax element consists of a number of alternatives, the
alternatives are separated by vertical bars (''|'').  When one member
from a set of choices _may_ be chosen, the alternatives are listed
within square brackets (''['' and '']''):

     TRIM([[BOTH | LEADING | TRAILING] [REMSTR] FROM] STR)

When one member from a set of choices _must_ be chosen, the alternatives
are listed within braces (''{'' and ''}''):

     {DESCRIBE | DESC} TBL_NAME [COL_NAME | WILD]

An ellipsis ('...') indicates the omission of a section of a statement,
typically to provide a shorter version of more complex syntax.  For
example, see 'SELECT ... INTO OUTFILE' is shorthand for the
form of 'SELECT' statement that has an 'INTO OUTFILE'
clause following other parts of the statement.

An ellipsis can also indicate that the preceding syntax element of a
statement may be repeated.  In the following example, multiple
RESET_OPTION values may be given, with each of those after the first
preceded by commas:

     RESET RESET_OPTION [,RESET_OPTION] ...

Commands for setting shell variables are shown using Bourne shell
syntax.  For example, the sequence to set the 'CC' environment variable
and run the 'configure' command looks like this in Bourne shell syntax:

     shell> CC=gcc ./configure

If you are using 'csh' or 'tcsh', you must issue commands somewhat
differently:

     shell> setenv CC gcc
     shell> ./configure

1.3 Overview of the MySQL Database Management System
====================================================

1.3.1 What is MySQL?
--------------------

MySQL, the most popular Open Source SQL database management system, is
developed, distributed, and supported by Oracle Corporation.

The MySQL website (<http://www.mysql.com/>) provides the latest
information about MySQL software.

   * *MySQL is a database management system.*

     A database is a structured collection of data.  It may be anything
     from a simple shopping list to a picture gallery or the vast
     amounts of information in a corporate network.  To add, access, and
     process data stored in a computer database, you need a database
     management system such as MySQL Server.  Since computers are very
     good at handling large amounts of data, database management systems
     play a central role in computing, as standalone utilities, or as
     parts of other applications.

   * *MySQL databases are relational.*

     A relational database stores data in separate tables rather than
     putting all the data in one big storeroom.  The database structures
     are organized into physical files optimized for speed.  The logical
     model, with objects such as databases, tables, views, rows, and
     columns, offers a flexible programming environment.  You set up
     rules governing the relationships between different data fields,
     such as one-to-one, one-to-many, unique, required or optional, and
     'pointers' between different tables.  The database enforces these
     rules, so that with a well-designed database, your application
     never sees inconsistent, duplicate, orphan, out-of-date, or missing
     data.

     The SQL part of 'MySQL' stands for 'Structured Query Language'.
     SQL is the most common standardized language used to access
     databases.  Depending on your programming environment, you might
     enter SQL directly (for example, to generate reports), embed SQL
     statements into code written in another language, or use a
     language-specific API that hides the SQL syntax.

     SQL is defined by the ANSI/ISO SQL Standard.  The SQL standard has
     been evolving since 1986 and several versions exist.  In this
     manual, 'SQL-92' refers to the standard released in 1992,
     'SQL:1999' refers to the standard released in 1999, and 'SQL:2003'
     refers to the current version of the standard.  We use the phrase
     'the SQL standard' to mean the current version of the SQL Standard
     at any time.

   * *MySQL software is Open Source.*

     Open Source means that it is possible for anyone to use and modify
     the software.  Anybody can download the MySQL software from the
     Internet and use it without paying anything.  If you wish, you may
     study the source code and change it to suit your needs.  The MySQL
     software uses the GPL (GNU General Public License),
     <http://www.fsf.org/licenses/>, to define what you may and may not
     do with the software in different situations.  If you feel
     uncomfortable with the GPL or need to embed MySQL code into a
     commercial application, you can buy a commercially licensed version
     from us.  See the MySQL Licensing Overview for more information
     (<http://www.mysql.com/company/legal/licensing/>).

   * *The MySQL Database Server is very fast, reliable, scalable, and
     easy to use.*

     If that is what you are looking for, you should give it a try.
     MySQL Server can run comfortably on a desktop or laptop, alongside
     your other applications, web servers, and so on, requiring little
     or no attention.  If you dedicate an entire machine to MySQL, you
     can adjust the settings to take advantage of all the memory, CPU
     power, and I/O capacity available.  MySQL can also scale up to
     clusters of machines, networked together.

     MySQL Server was originally developed to handle large databases
     much faster than existing solutions and has been successfully used
     in highly demanding production environments for several years.
     Although under constant development, MySQL Server today offers a
     rich and useful set of functions.  Its connectivity, speed, and
     security make MySQL Server highly suited for accessing databases on
     the Internet.

   * *MySQL Server works in client/server or embedded systems.*

     The MySQL Database Software is a client/server system that consists
     of a multi-threaded SQL server that supports different back ends,
     several different client programs and libraries, administrative
     tools, and a wide range of application programming interfaces
     (APIs).

     We also provide MySQL Server as an embedded multi-threaded library
     that you can link into your application to get a smaller, faster,
     easier-to-manage standalone product.

   * *A large amount of contributed MySQL software is available.*

     MySQL Server has a practical set of features developed in close
     cooperation with our users.  It is very likely that your favorite
     application or language supports the MySQL Database Server.

The official way to pronounce 'MySQL' is 'My Ess Que Ell' (not 'my
sequel'), but we do not mind if you pronounce it as 'my sequel' or in
some other localized way.

1.3.2 The Main Features of MySQL
--------------------------------

This section describes some of the important characteristics of the
MySQL Database Software.  In most respects, the roadmap applies to all
versions of MySQL. For information about features as they are introduced
into MySQL on a series-specific basis, see the 'In a Nutshell' section
of the appropriate Manual:

   * MySQL 8.0: What Is New in MySQL 8.0
     (http://dev.mysql.com/doc/refman/8.0/en/mysql-nutshell.html)

   * MySQL 5.7: mysql-nutshell

   * MySQL 5.6: What Is New in MySQL 5.6
     (http://dev.mysql.com/doc/refman/5.6/en/mysql-nutshell.html)

   * MySQL 5.5: What Is New in MySQL 5.5
     (http://dev.mysql.com/doc/refman/5.5/en/mysql-nutshell.html)

*Internals and Portability*

   * Written in C and C++.

   * Tested with a broad range of different compilers.

   * Works on many different platforms.  See
     <http://www.mysql.com/support/supportedplatforms/database.html>.

   * For portability, uses 'CMake' in MySQL 5.5 and up.  Previous series
     use GNU Automake, Autoconf, and Libtool.

   * Tested with Purify (a commercial memory leakage detector) as well
     as with Valgrind, a GPL tool
     (<http://developer.kde.org/~sewardj/>).

   * Uses multi-layered server design with independent modules.

   * Designed to be fully multi-threaded using kernel threads, to easily
     use multiple CPUs if they are available.

   * Provides transactional and nontransactional storage engines.

   * Uses very fast B-tree disk tables ('MyISAM') with index
     compression.

   * Designed to make it relatively easy to add other storage engines.
     This is useful if you want to provide an SQL interface for an
     in-house database.

   * Uses a very fast thread-based memory allocation system.

   * Executes very fast joins using an optimized nested-loop join.

   * Implements in-memory hash tables, which are used as temporary
     tables.

   * Implements SQL functions using a highly optimized class library
     that should be as fast as possible.  Usually there is no memory
     allocation at all after query initialization.

   * Provides the server as a separate program for use in a
     client/server networked environment, and as a library that can be
     embedded (linked) into standalone applications.  Such applications
     can be used in isolation or in environments where no network is
     available.

*Data Types*

   * Many data types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes
     long, see 'FLOAT', 'DOUBLE',
     see 'CHAR', 'VARCHAR',
     'BINARY', 'VARBINARY',
     see 'TEXT', 'BLOB',
     'DATE', 'TIME', 'DATETIME',
     'TIMESTAMP', 'YEAR', 'SET',
     'ENUM', and OpenGIS spatial types.  See
     data-types.

   * Fixed-length and variable-length string types.

*Statements and Functions*

   * Full operator and function support in the 'SELECT'.
     list and 'WHERE' clause of queries.  For example:

          mysql> SELECT CONCAT(first_name, ' ', last_name)
              -> FROM citizen
              -> WHERE income/dependents > 10000 AND age > 30;

   * Full support for SQL 'GROUP BY' and 'ORDER BY' clauses.  Support
     for group functions ('COUNT()', 'AVG()', 'STD()', 'SUM()', 'MAX()',
     'MIN()', and 'GROUP_CONCAT()').

   * Support for 'LEFT OUTER JOIN' and 'RIGHT OUTER JOIN' with both
     standard SQL and ODBC syntax.

   * Support for aliases on tables and columns as required by standard
     SQL.

   * Support for 'DELETE', 'INSERT',
     'REPLACE', and 'UPDATE' to return the
     number of rows that were changed (affected), or to return the
     number of rows matched instead by setting a flag when connecting to
     the server.

   * Support for MySQL-specific 'SHOW' statements that
     retrieve information about databases, storage engines, tables, and
     indexes.  Support for the 'INFORMATION_SCHEMA' database,
     implemented according to standard SQL.

   * An 'EXPLAIN' statement to show how the optimizer
     resolves a query.

   * Independence of function names from table or column names.  For
     example, 'ABS' is a valid column name.  The only restriction is
     that for a function call, no spaces are permitted between the
     function name and the ''('' that follows it.  See keywords.

   * You can refer to tables from different databases in the same
     statement.

*Security*

   * A privilege and password system that is very flexible and secure,
     and that enables host-based verification.

   * Password security by encryption of all password traffic when you
     connect to a server.

*Scalability and Limits*

   * Support for large databases.  We use MySQL Server with databases
     that contain 50 million records.  We also know of users who use
     MySQL Server with 200,000 tables and about 5,000,000,000 rows.

   * Support for up to 64 indexes per table.  Each index may consist of
     1 to 16 columns or parts of columns.  The maximum index width for
     'InnoDB' tables is either 767 bytes
     or 3072 bytes.  See innodb-restrictions.  The maximum index
     width for 'MyISAM' tables is 1000
     bytes.  See myisam-storage-engine.  An index may use a
     prefix of a column for 'CHAR', 'VARCHAR',
     'BLOB', or 'TEXT' column types.

*Connectivity*

   * Clients can connect to MySQL Server using several protocols:

        * Clients can connect using TCP/IP sockets on any platform.

        * On Windows systems, clients can connect using named pipes if
          the server is started with the '--enable-named-pipe' option.
          Windows servers also support shared-memory connections if
          started with the '--shared-memory' option.  Clients can
          connect through shared memory by using the '--protocol=memory'
          option.

        * On Unix systems, clients can connect using Unix domain socket
          files.

   * MySQL client programs can be written in many languages.  A client
     library written in C is available for clients written in C or C++,
     or for any language that provides C bindings.

   * APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and Tcl are
     available, enabling MySQL clients to be written in many languages.
     See connectors-apis.

   * The Connector/ODBC (MyODBC) interface provides MySQL support for
     client programs that use ODBC (Open Database Connectivity)
     connections.  For example, you can use MS Access to connect to your
     MySQL server.  Clients can be run on Windows or Unix.
     Connector/ODBC source is available.  All ODBC 2.5 functions are
     supported, as are many others.  See MySQL Connector/ODBC Developer
     Guide (http://dev.mysql.com/doc/connector-odbc/en/).

   * The Connector/J interface provides MySQL support for Java client
     programs that use JDBC connections.  Clients can be run on Windows
     or Unix.  Connector/J source is available.  See MySQL Connector/J
     5.1 Developer Guide (http://dev.mysql.com/doc/connector-j/5.1/en/).

   * MySQL Connector/Net enables developers to easily create .NET
     applications that require secure, high-performance data
     connectivity with MySQL. It implements the required ADO.NET
     interfaces and integrates into ADO.NET aware tools.  Developers can
     build applications using their choice of .NET languages.  MySQL
     Connector/Net is a fully managed ADO.NET driver written in 100%
     pure C#.  See MySQL Connector/Net Developer Guide
     (http://dev.mysql.com/doc/connector-net/en/).

*Localization*

   * The server can provide error messages to clients in many languages.
     See error-message-language.

   * Full support for several different character sets, including
     'latin1' (cp1252), 'german', 'big5', 'ujis', several Unicode
     character sets, and more.  For example, the Scandinavian characters
     ''aa'', ''a"'' and ''o"'' are permitted in table and column names.

   * All data is saved in the chosen character set.

   * Sorting and comparisons are done according to the default character
     set and collation.  is possible to change this when the MySQL
     server is started (see charset-server).  To see an example
     of very advanced sorting, look at the Czech sorting code.  MySQL
     Server supports many different character sets that can be specified
     at compile time and runtime.

   * The server time zone can be changed dynamically, and individual
     clients can specify their own time zone.  See
     time-zone-support.

*Clients and Tools*

   * MySQL includes several client and utility programs.  These include
     both command-line programs such as 'mysqldump'.
     and 'mysqladmin', and graphical programs such as
     MySQL Workbench.

   * MySQL Server has built-in support for SQL statements to check,
     optimize, and repair tables.  These statements are available from
     the command line through the 'mysqlcheck'.
     client.  MySQL also includes 'myisamchk', a very
     fast command-line utility for performing these operations on
     'MyISAM' tables.  See programs.

   * MySQL programs can be invoked with the '--help' or '-?' option to
     obtain online assistance.

1.3.3 History of MySQL
----------------------

We started out with the intention of using the 'mSQL' database system to
connect to our tables using our own fast low-level (ISAM) routines.
However, after some testing, we came to the conclusion that 'mSQL' was
not fast enough or flexible enough for our needs.  This resulted in a
new SQL interface to our database but with almost the same API interface
as 'mSQL'.  This API was designed to enable third-party code that was
written for use with 'mSQL' to be ported easily for use with MySQL.

MySQL is named after co-founder Monty Widenius's daughter, My.

The name of the MySQL Dolphin (our logo) is 'Sakila,' which was chosen
from a huge list of names suggested by users in our 'Name the Dolphin'
contest.  The winning name was submitted by Ambrose Twebaze, an Open
Source software developer from Swaziland, Africa.  According to Ambrose,
the feminine name Sakila has its roots in SiSwati, the local language of
Swaziland.  Sakila is also the name of a town in Arusha, Tanzania, near
Ambrose's country of origin, Uganda.

1.4 What Is New in MySQL 5.7
============================

This section summarizes what has been added to, deprecated in, and
removed from MySQL 5.7.  A companion section lists MySQL server options
and variables that have been added, deprecated, or removed in MySQL 5.7.
See added-deprecated-removed.

   * mysql-nutshell-additions

   * mysql-nutshell-deprecations

   * mysql-nutshell-removals

*Features Added in MySQL 5.7*

The following features have been added to MySQL 5.7:

   * Security improvements

     These security enhancements were added:

        * The server now requires account rows in the 'mysql.user' table
          to have a nonempty 'plugin' column value and disables accounts
          with an empty value.  For server upgrade instructions, see
          upgrading-from-previous-series.  DBAs are advised to
          also convert accounts that use the 'mysql_old_password'
          authentication plugin to use 'mysql_native_password' instead,
          because support for 'mysql_old_password' has been removed.
          For account upgrade instructions, see
          account-upgrades.

        * MySQL now enables database administrators to establish a
          policy for automatic password expiration: Any user who
          connects to the server using an account for which the password
          is past its permitted lifetime must change the password.  For
          more information, see password-management.

        * Administrators can lock and unlock accounts for better control
          over who can log in.  For more information, see
          account-locking.

        * To make it easier to support secure connections, MySQL servers
          compiled using OpenSSL can automatically generate missing SSL
          and RSA certificate and key files at startup.  See
          creating-ssl-rsa-files-using-mysql.

          All servers (whether compiled using OpenSSL or yaSSL), if not
          configured for SSL explicitly, attempt to enable SSL
          automatically at startup if they find the requisite SSL files
          in the data directory.  See
          using-encrypted-connections.

          In addition, MySQL distributions include a
          'mysql_ssl_rsa_setup' utility that can
          be invoked manually to create SSL and RSA key and certificate
          files.  For more information, see mysql-ssl-rsa-setup.

        * MySQL deployments installed using 'mysqld --initialize'
          are secure by default.  The following changes have
          been implemented as the default deployment characteristics:

             * The installation process creates only a single 'root'
               account, ''root'@'localhost'', automatically generates a
               random password for this account, and marks the password
               expired.  The MySQL administrator must connect as 'root'
               using the random password and assign a new password.
               (The server writes the random password to the error log.)

             * Installation creates no anonymous-user accounts.

             * Installation creates no 'test' database.

          For more information, see
          data-directory-initialization-mysqld.

   * SQL mode changes

     Strict SQL mode for transactional storage engines
     ('STRICT_TRANS_TABLES') is now enabled by default.

     Implementation for the 'ONLY_FULL_GROUP_BY' SQL mode has been made
     more sophisticated, to no longer reject deterministic queries that
     previously were rejected.  In consequence, this mode is now enabled
     by default, to prohibit only nondeterministic queries containing
     expressions not guaranteed to be uniquely determined within a
     group.

     The 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and
     'NO_ZERO_IN_DATE' SQL modes are now deprecated but enabled by
     default.  The long term plan is to have them included in strict SQL
     mode and to remove them as explicit modes in a future MySQL
     release.  See sql-mode-changes.

     The changes to the default SQL mode result in a default 'sql_mode'
     system variable value with these modes enabled:
     'ONLY_FULL_GROUP_BY', 'STRICT_TRANS_TABLES', 'NO_ZERO_IN_DATE',
     'NO_ZERO_DATE', 'ERROR_FOR_DIVISION_BY_ZERO',
     'NO_AUTO_CREATE_USER', and 'NO_ENGINE_SUBSTITUTION'.

   * Online ALTER TABLE

     'ALTER TABLE' now supports a 'RENAME INDEX' clause that renames an
     index.  The change is made in place without a table-copy operation.
     It works for all storage engines.  See alter-table.

   * ngram and MeCab full-text parser plugins

     MySQL provides a built-in full-text ngram parser plugin that
     supports Chinese, Japanese, and Korean (CJK), and an installable
     MeCab full-text parser plugin for Japanese.

     For more information, see fulltext-search-ngram, and
     fulltext-search-mecab.

   * InnoDB enhancements

     These 'InnoDB' enhancements were added:

        * 'VARCHAR' size may be increased using an in-place
          'ALTER TABLE', as in this example:

               ALTER TABLE t1 ALGORITHM=INPLACE, CHANGE COLUMN c1 c1 VARCHAR(255);

          This is true as long as the number of length bytes required by
          a 'VARCHAR' column remains the same.  For
          'VARCHAR' values of 0 to 255, one length byte is
          required to encode the value.  For 'VARCHAR'.
          values of 256 bytes or more, two length bytes are required.
          As a result, in-place 'ALTER TABLE' only
          supports increasing 'VARCHAR' size from 0 to 255
          bytes or increasing 'VARCHAR' size from a value
          equal to or greater than 256 bytes.

          In-place 'ALTER TABLE' does not support
          increasing 'VARCHAR' size from less than 256
          bytes to a value equal to or greater than 256 bytes.  In this
          case, the number of required length bytes would change from 1
          to 2, which is only supported by a table copy
          ('ALGORITHM=COPY').  For example, attempting to change
          'VARCHAR' column size from 255 to 256 using in-place
          'ALTER TABLE' would return an error:

               ALTER TABLE t1 ALGORITHM=INPLACE, CHANGE COLUMN c1 c1 VARCHAR(256);
               ERROR 0A000: ALGORITHM=INPLACE is not supported. Reason: Cannot change
               column type INPLACE. Try ALGORITHM=COPY.

          Decreasing 'VARCHAR' size using in-place
          'ALTER TABLE' is not supported.  Decreasing
          'VARCHAR' size requires a table copy
          ('ALGORITHM=COPY').

        * DDL performance for 'InnoDB' temporary tables is improved
          through optimization of 'CREATE TABLE',
          'DROP TABLE', 'TRUNCATE TABLE',
          and 'ALTER TABLE'.
          statements.

        * 'InnoDB' temporary table metadata is no longer stored to
          'InnoDB' system tables.  Instead, a new table,
          'INNODB_TEMP_TABLE_INFO', provides users with a snapshot of
          active temporary tables.  The table contains metadata and
          reports on all user and system-created temporary tables that
          are active within a given 'InnoDB' instance.  The table is
          created when the first 'SELECT' statement is run against it.

        * 'InnoDB' now supports MySQL-supported spatial data types.
          Prior to this release, 'InnoDB' would store spatial data as
          binary 'BLOB' data.  'BLOB' remains the
          underlying data type but spatial data types are now mapped to
          a new 'InnoDB' internal data type, 'DATA_GEOMETRY'.

        * There is now a separate tablespace for all non-compressed
          'InnoDB' temporary tables.  The new tablespace is always
          recreated on server startup and is located in 'DATADIR' by
          default.  A newly added configuration file option,
          'innodb_temp_data_file_path', allows for a user-defined
          temporary data file path.

        * 'innochecksum' functionality is enhanced
          with several new options and extended capabilities.  See
          innochecksum.

        * A new type of non-redo undo log for both normal and compressed
          temporary tables and related objects now resides in the
          temporary tablespace.  For more information, see
          innodb-temporary-table-undo-logs.

        * 'InnoDB' buffer pool dump and load operations are enhanced.  A
          new system variable, 'innodb_buffer_pool_dump_pct', allows you
          to specify the percentage of most recently used pages in each
          buffer pool to read out and dump.  When there is other I/O
          activity being performed by 'InnoDB' background tasks,
          'InnoDB' attempts to limit the number of buffer pool load
          operations per second using the 'innodb_io_capacity' setting.

        * Support is added to 'InnoDB' for full-text parser plugins.
          For information about full-text parser plugins, see
          full-text-plugin-type and writing-full-text-plugins.

        * 'InnoDB' supports multiple page cleaner threads for flushing
          dirty pages from buffer pool instances.  A new system
          variable, 'innodb_page_cleaners', is used to specify the
          number of page cleaner threads.  The default value of '1'
          maintains the previous configuration in which there is a
          single page cleaner thread.  This enhancement builds on work
          completed in MySQL 5.6, which introduced a single page cleaner
          thread to offload buffer pool flushing work from the 'InnoDB'
          master thread.

        * Online DDL support is extended to
          the following operations for regular and partitioned 'InnoDB'
          tables:

             * 'OPTIMIZE TABLE'.

             * 'ALTER TABLE ... FORCE'.

             * 'ALTER TABLE ... ENGINE=INNODB'. (when
               run on an 'InnoDB' table)

               Online DDL support reduces
               table rebuild time and permits concurrent DML. See
               innodb-create-index-overview.

        * The Fusion-io Non-Volatile Memory (NVM) file system on Linux
          provides atomic write capability, which makes the 'InnoDB'
          doublewrite buffer redundant.  The 'InnoDB' doublewrite buffer
          is automatically disabled for system tablespace files (ibdata
          files) located on Fusion-io devices that support atomic
          writes.

        * 'InnoDB' supports the Transportable Tablespace feature for
          partitioned 'InnoDB' tables and individual 'InnoDB' table
          partitions.  This enhancement eases backup procedures for
          partitioned tables and enables copying of partitioned tables
          and individual table partitions between MySQL instances.  For
          additional information, see tablespace-copying.

        * The 'innodb_buffer_pool_size' parameter is dynamic, allowing
          you to resize the buffer pool without restarting the server.
          The resizing operation, which involves moving pages to a new
          location in memory, is performed in chunks.  Chunk size is
          configurable using the new 'innodb_buffer_pool_chunk_size'
          configuration option.  You can monitor resizing progress using
          the new 'Innodb_buffer_pool_resize_status' status variable.
          For more information, see
          innodb-buffer-pool-online-resize.

        * Multi-threaded page cleaner support ('innodb_page_cleaners')
          is extended to shutdown and recovery phases.

        * 'InnoDB' supports indexing of spatial data types using
          'SPATIAL' indexes, including use of 'ALTER TABLE ... ALGORITHM=INPLACE'
          for online operations ('ADD
          SPATIAL INDEX').

        * 'InnoDB' performs a bulk load when creating or rebuilding
          indexes.  This method of index creation is known as a 'sorted
          index build'.  This enhancement, which improves the efficiency
          of index creation, also applies to full-text indexes.  A new
          global configuration option, 'innodb_fill_factor', defines the
          percentage of space on each page that is filled with data
          during a sorted index build, with the remaining space reserved
          for future index growth.  For more information, see
          sorted-index-builds.

        * A new log record type ('MLOG_FILE_NAME') is used to identify
          tablespaces that have been modified since the last checkpoint.
          This enhancement simplifies tablespace discovery during crash
          recovery and eliminates scans on the file system prior to redo
          log application.  For more information about the benefits of
          this enhancement, see
          innodb-recovery-tablespace-discovery.

          This enhancement changes the redo log format, requiring that
          MySQL be shut down cleanly before upgrading to or downgrading
          from MySQL 5.7.5.

        * You can truncate undo logs that reside in undo tablespaces.
          This feature is enabled using the 'innodb_undo_log_truncate'
          configuration option.  For more information, see
          truncate-undo-tablespace.

        * 'InnoDB' supports native partitioning.  Previously, 'InnoDB'
          relied on the 'ha_partition' handler, which creates a handler
          object for each partition.  With native partitioning, a
          partitioned 'InnoDB' table uses a single partition-aware
          handler object.  This enhancement reduces the amount of memory
          required for partitioned 'InnoDB' tables.

          As of MySQL 5.7.9, see 'mysql_upgrade' looks
          for and attempts to upgrade partitioned 'InnoDB' tables that
          were created using the 'ha_partition' handler.  Also in MySQL
          5.7.9 and later, you can upgrade such tables by name in the
          'mysql' client using 'ALTER TABLE ... UPGRADE PARTITIONING'.

        * 'InnoDB' supports the creation of general tablespaces using
          'CREATE TABLESPACE' syntax.

               CREATE TABLESPACE `tablespace_name`
                 ADD DATAFILE 'file_name.ibd'
                 [FILE_BLOCK_SIZE = n]

          General tablespaces can be created outside of the MySQL data
          directory, are capable of holding multiple tables, and support
          tables of all row formats.

          Tables are added to a general tablespace using 'CREATE TABLE TBL_NAME ... TABLESPACE [=] TABLESPACE_NAME'
          or 'ALTER TABLE TBL_NAME TABLESPACE [=] TABLESPACE_NAME'
          syntax.

          For more information, see general-tablespaces.

        * 'DYNAMIC' replaces 'COMPACT' as the implicit default row
          format for 'InnoDB' tables.  A new configuration option,
          'innodb_default_row_format', specifies the default 'InnoDB'
          row format.  For more information, see
          innodb-row-format-specification.

        * As of MySQL 5.7.11, 'InnoDB' supports data-at-rest encryption
          for file-per-table tablespaces.  Encryption is enabled by
          specifying the 'ENCRYPTION' option when creating or altering
          an 'InnoDB' table.  This feature, referred to as 'InnoDB'
          tablespace encryption, relies on a 'keyring' plugin for
          encryption key management.  For more information, see
          keyring, and innodb-tablespace-encryption.

   * JSON support

     Beginning with MySQL 5.7.8, MySQL supports a native 'JSON'
     type.  JSON values are not stored as strings, instead using
     an internal binary format that permits quick read access to
     document elements.  JSON documents stored in 'JSON' columns are
     automatically validated whenever they are inserted or updated, with
     an invalid document producing an error.  JSON documents are
     normalized on creation, and can be compared using most comparison
     operators such as '=', '<', '<=', '>', '>=', '<>', '!=', and '<=>';
     for information about supported operators as well as precedence and
     other rules that MySQL follows when comparing 'JSON' values, see
     json-comparison.

     MySQL 5.7.8 also introduces a number of functions for working with
     'JSON' values.  These functions include those listed
     here:

        * Functions that create 'JSON' values: 'JSON_ARRAY()',
          'JSON_MERGE()', and 'JSON_OBJECT()'.  See
          json-creation-functions.

        * Functions that search 'JSON' values: 'JSON_CONTAINS()',
          'JSON_CONTAINS_PATH()', 'JSON_EXTRACT()', 'JSON_KEYS()', and
          'JSON_SEARCH()'.  See json-search-functions.

        * Functions that modify 'JSON' values: 'JSON_APPEND()',
          'JSON_ARRAY_APPEND()', 'JSON_ARRAY_INSERT()', 'JSON_INSERT()',
          'JSON_QUOTE()', 'JSON_REMOVE()', 'JSON_REPLACE()',
          'JSON_SET()', and 'JSON_UNQUOTE()'.  See
          json-modification-functions.

        * Functions that provide information about 'JSON' values:
          'JSON_DEPTH()', 'JSON_LENGTH()', 'JSON_TYPE()', and
          'JSON_VALID()'.  See json-attribute-functions.

     In MySQL 5.7.9 and later, you can use 'COLUMN->PATH' as shorthand
     for 'JSON_EXTRACT(COLUMN, PATH)'.  This works as an alias for a
     column wherever a column identifier can occur in an SQL statement,
     including 'WHERE', 'ORDER BY', and 'GROUP BY' clauses.  This
     includes 'SELECT', 'UPDATE',
     'DELETE', 'CREATE TABLE', and other SQL
     statements.  The left hand side must be a 'JSON'.
     column identifier (and not an alias).  The right hand side is a
     quoted JSON path expression which is evaluated against the JSON
     document returned as the column value.

     MySQL 5.7.22 adds the following JSON functions:

        * Two JSON aggregation functions 'JSON_ARRAYAGG()' and
          'JSON_OBJECTAGG()'.  'JSON_ARRAYAGG()' takes a column or
          expression as its argument, and aggregates the result as a
          single 'JSON' array.  The expression can evaluate
          to any MySQL data type; this does not have to be a 'JSON'
          value.  'JSON_OBJECTAGG()' takes two columns or expressions
          which it interprets as a key and a value; it returns the
          result as a single 'JSON' object.  For more information and
          examples, see group-by-functions-and-modifiers.

        * The JSON utility function 'JSON_PRETTY()', which outputs an
          existing 'JSON' value in an easy-to-read format;
          each JSON object member or array value is printed on a
          separate line, and a child object or array is intended 2
          spaces with respect to its parent.

          This function also works with a string that can be parsed as a
          JSON value.

          See also json-utility-functions.

        * The JSON utility function 'JSON_STORAGE_SIZE()', which returns
          the storage space in bytes used for the binary representation
          of a JSON document prior to any partial update (see previous
          item).

          This function also accepts a valid string representation of a
          JSON document.  For such a value, 'JSON_STORAGE_SIZE()'
          returns the space used by its binary representation following
          its conversion to a JSON document.  For a variable containing
          the string representation of a JSON document,
          'JSON_STORAGE_FREE()' returns zero.  Either function produces
          an error if its (non-null) argument cannot be parsed as a
          valid JSON document, and 'NULL' if the argument is 'NULL'.

          For more information and examples, see
          json-utility-functions.

        * A JSON merge function intended to conform to RFC 7396
          (https://tools.ietf.org/html/rfc7396).  'JSON_MERGE_PATCH()',
          when used on 2 JSON objects, merges them into a single JSON
          object that has as members a union of the following sets:

             * Each member of the first object for which there is no
               member with the same key in the second object.

             * Each member of the second object for which there is no
               member having the same key in the first object, and whose
               value is not the JSON 'null' literal.

             * Each member having a key that exists in both objects, and
               whose value in the second object is not the JSON 'null'
               literal.

          As part of this work, the 'JSON_MERGE()' function has been
          renamed 'JSON_MERGE_PRESERVE()'.  'JSON_MERGE()' continues to
          be recognized as an alias for 'JSON_MERGE_PRESERVE()' in MySQL
          5.7, but is now deprecated and is subject to removal in a
          future version of MySQL.

          For more information and examples, see
          json-modification-functions.

     See json-search-functions, for more information about '->'
     and 'JSON_EXTRACT()'.  For information about JSON path support in
     MySQL 5.7, see json-paths.  See also
     json-column-indirect-index.

   * System and status variables

     System and status variable information is now available in
     Performance Schema tables, in preference to use of
     'INFORMATION_SCHEMA' tables to obtain these variable.  This also
     affects the operation of the 'SHOW VARIABLES'
     and 'SHOW STATUS' statements.
     The value of the 'show_compatibility_56' system variable affects
     the output produced from and privileges required for system and
     status variable statements and tables.  For details, see the
     description of that variable in server-system-variables.

     *Note*:

     The default for 'show_compatibility_56' is 'OFF'.  Applications
     that require 5.6 behavior should set this variable to 'ON' until
     such time as they have been migrated to the new behavior for system
     variables and status variables.  See
     performance-schema-variable-table-migration

   * sys schema

     MySQL distributions now include the 'sys'.
     schema, which is a set of objects that help DBAs and developers
     interpret data collected by the Performance Schema.  'sys'
     schema objects can be used for typical tuning and
     diagnosis use cases.  For more information, see sys-schema.

   * Condition handling

     MySQL now supports stacked diagnostics areas.  When the diagnostics
     area stack is pushed, the first (current) diagnostics area becomes
     the second (stacked) diagnostics area and a new current diagnostics
     area is created as a copy of it.  Within a condition handler,
     executed statements modify the new current diagnostics area, but
     'GET STACKED DIAGNOSTICS' can be used to
     inspect the stacked diagnostics area to obtain information about
     the condition that caused the handler to activate, independent of
     current conditions within the handler itself.  (Previously, there
     was a single diagnostics area.  To inspect handler-activating
     conditions within a handler, it was necessary to check this
     diagnostics area before executing any statements that could change
     it.)  See get-diagnostics, and diagnostics-area.

   * Optimizer

     These optimizer enhancements were added:

        * 'EXPLAIN' can be used to obtain the execution
          plan for an explainable statement executing in a named
          connection:

               EXPLAIN [OPTIONS] FOR CONNECTION CONNECTION_ID;

          For more information, see explain-for-connection.

        * It is possible to provide hints to the optimizer within
          individual SQL statements, which enables finer control over
          statement execution plans than can be achieved using the
          'optimizer_switch' system variable.  Hints are also permitted
          in statements used with 'EXPLAIN', enabling you
          to see how hints affect execution plans.  For more
          information, see optimizer-hints.

   * Triggers

     Previously, a table could have at most one trigger for each
     combination of trigger event (see 'INSERT',
     'UPDATE', 'DELETE') and action time
     ('BEFORE', 'AFTER').  This limitation has been lifted and multiple
     triggers are permitted.  For more information, see
     triggers.

   * Logging

     These logging enhancements were added:

        * Previously, on Unix and Unix-like systems, MySQL support for
          sending the server error log to 'syslog' was implemented by
          having 'mysqld_safe' capture server error
          output and pass it to 'syslog'.  The server now includes
          native 'syslog' support, which has been extended to include
          Windows.  For more information about sending server error
          output to 'syslog', see error-log.

        * The 'mysql' client now has a '--syslog' option
          that causes interactive statements to be sent to the system
          'syslog' facility.  Logging is suppressed for statements that
          match the default 'ignore' pattern list
          ('"*IDENTIFIED*:*PASSWORD*"'), as well as statements that
          match any patterns specified using the '--histignore' option.
          See mysql-logging.

   * Generated Columns

     MySQL now supports the specification of generated columns in
     'CREATE TABLE' and 'ALTER TABLE'.
     statements.  Values of a generated column are computed from an
     expression specified at column creation time.  Generated columns
     can be virtual (computed 'on the fly' when rows are read) or stored
     (computed when rows are inserted or updated).  For more
     information, see create-table-generated-columns.

   * mysql client

     Previously, 'Control+C' in mysql interrupted the current statement
     if there was one, or exited mysql if not.  Now 'Control+C'
     interrupts the current statement if there was one, or cancels any
     partial input line otherwise, but does not exit.

   * Database name rewriting with mysqlbinlog

     Renaming of databases by 'mysqlbinlog' when
     reading from binary logs written using the row-based format is now
     supported using the '--rewrite-db' option added in MySQL 5.7.1.

     This option uses the format '--rewrite-db='DBOLDNAME->DBNEWNAME''.
     You can implement multiple rewrite rules, by specifying the option
     multiple times.

   * HANDLER with partitioned tables

     The 'HANDLER' statement may now be used with
     user-partitioned tables.  Such tables may use any of the available
     partitioning types (see partitioning-types).

   * Index condition pushdown support for partitioned tables

     Queries on partitioned tables using the 'InnoDB'
     or 'MyISAM'.
     storage engine may employ the index condition pushdown optimization
     that was introduced in MySQL 5.6.  See
     index-condition-pushdown-optimization, for more information.

   * WITHOUT VALIDATION support for ALTER TABLE ...  EXCHANGE PARTITION

     As of MySQL 5.7.5, see 'ALTER TABLE ... EXCHANGE PARTITION'
     syntax includes an optional '{WITH|WITHOUT}
     VALIDATION' clause.  When 'WITHOUT VALIDATION' is specified, see
     'ALTER TABLE ... EXCHANGE PARTITION' does not perform
     row-by-row validation when exchanging a populated table with the
     partition, permitting database administrators to assume
     responsibility for ensuring that rows are within the boundaries of
     the partition definition.  'WITH VALIDATION' is the default
     behavior and need not be specified explicitly.  For more
     information, see partitioning-management-exchange.

   * Master dump thread improvements

     The master dump thread was refactored to reduce lock contention and
     improve master throughput.  Previous to MySQL 5.7.2, the dump
     thread took a lock on the binary log whenever reading an event; in
     MySQL 5.7.2 and later, this lock is held only while reading the
     position at the end of the last successfully written event.  This
     means both that multiple dump threads are now able to read
     concurrently from the binary log file, and that dump threads are
     now able to read while clients are writing to the binary log.

   * Globalization improvements

     MySQL 5.7.4 includes a 'gb18030' character set that supports the
     China National Standard GB18030 character set.  For more
     information about MySQL character set support, see charset.

   * Changing the replication master without STOP SLAVE

     In MySQL 5.7.4 and later, the strict requirement to execute
     'STOP SLAVE' prior to issuing any 'CHANGE MASTER TO'
     statement is removed.  Instead of depending
     on whether the slave is stopped, the behavior of 'CHANGE MASTER TO'
     now depends on the states of the slave SQL thread and slave I/O
     threads; which of these threads is stopped or running now
     determines the options that can or cannot be used with a 'CHANGE
     MASTER TO' statement at a given point in time.  The rules for
     making this determination are listed here:

        * If the SQL thread is stopped, you can execute 'CHANGE MASTER
          TO' using any combination of 'RELAY_LOG_FILE',
          'RELAY_LOG_POS', and 'MASTER_DELAY' options, even if the slave
          I/O thread is running.  No other options may be used with this
          statement when the I/O thread is running.

        * If the I/O thread is stopped, you can execute 'CHANGE MASTER
          TO' using any of the options for this statement (in any
          allowed combination) _except_ 'RELAY_LOG_FILE',
          'RELAY_LOG_POS', or 'MASTER_DELAY', even when the SQL thread
          is running.  These three options may not be used when the I/O
          thread is running.

        * Both the SQL thread and the I/O thread must be stopped before
          issuing 'CHANGE MASTER TO ... MASTER_AUTO_POSITION = 1'.

     You can check the current state of the slave SQL and I/O threads
     using 'SHOW SLAVE STATUS'.

     If you are using statement-based replication and temporary tables,
     it is possible for a 'CHANGE MASTER TO' statement following a 'STOP
     SLAVE' statement to leave behind temporary tables on the slave.  As
     part of this set of improvements, a warning is now issued whenever
     'CHANGE MASTER TO' is issued following 'STOP SLAVE' when
     statement-based replication is in use and 'Slave_open_temp_tables'
     remains greater than 0.

     For more information, see change-master-to, and
     replication-solutions-switch.

   * Test suite

     The MySQL test suite now uses 'InnoDB' as the default storage
     engine.

   * Multi-source replication is now possible

     MySQL Multi-Source Replication adds the ability to replicate from
     multiple masters to a slave.  MySQL Multi-Source Replication
     topologies can be used to back up multiple servers to a single
     server, to merge table shards, and consolidate data from multiple
     servers to a single server.  See replication-multi-source.

     As part of MySQL Multi-Source Replication, replication channels
     have been added.  Replication channels enable a slave to open
     multiple connections to replicate from, with each channel being a
     connection to a master.  See replication-channels.

   * Group Replication Performance Schema tables

     MySQL 5.7 adds a number of new tables to the Performance Schema to
     provide information about replication groups and channels.  These
     include the following tables:

        * 'replication_applier_configuration'.

        * 'replication_applier_status'.

        * 'replication_applier_status_by_coordinator'.

        * 'replication_applier_status_by_worker'.

        * 'replication_connection_configuration'.

        * 'replication_connection_status'.

        * 'replication_group_members'.

        * 'replication_group_member_stats'.

     All of these tables were added in MySQL 5.7.2, except for
     'replication_group_members' and 'replication_group_member_stats',
     which were added in MySQL 5.7.6.  For more information, see
     performance-schema-replication-tables.

   * Group Replication SQL

     The following statements were added in MySQL 5.7.6 for controlling
     Group Replication:

        * 'START GROUP_REPLICATION'.

        * 'STOP GROUP_REPLICATION'.

     For more information, see replication-group-sql.

*Features Deprecated in MySQL 5.7*

The following features are deprecated in MySQL 5.7 and may be or will be
removed in a future series.  Where alternatives are shown, applications
should be updated to use them.

For applications that use features deprecated in MySQL 5.7 that have
been removed in a higher MySQL series, statements may fail when
replicated from a MySQL 5.7 master to a higher-series slave, or may have
different effects on master and slave.  To avoid such problems,
applications that use features deprecated in 5.7 should be revised to
avoid them and use alternatives when possible.

   * The 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and
     'NO_ZERO_IN_DATE' SQL modes are now deprecated but enabled by
     default.  The long term plan is to have them included in strict SQL
     mode and to remove them as explicit modes in a future MySQL
     release.

     The deprecated 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and
     'NO_ZERO_IN_DATE' SQL modes are still recognized so that statements
     that name them do not produce an error, but will be removed in a
     future version of MySQL. To make advance preparation for versions
     of MySQL in which these mode names do not exist, applications
     should be modified to not refer to them.  See
     sql-mode-changes.

   * These SQL modes are now deprecated and will be removed in a future
     version of MySQL: 'DB2', 'MAXDB', 'MSSQL', 'MYSQL323', 'MYSQL40',
     'ORACLE', 'POSTGRESQL', 'NO_FIELD_OPTIONS', 'NO_KEY_OPTIONS',
     'NO_TABLE_OPTIONS'.  These deprecations have two implications:

        * Assigning a deprecated mode to the 'sql_mode' system variable
          produces a warning.

        * With the 'MAXDB' SQL mode enabled, using 'CREATE TABLE'
          or 'ALTER TABLE' to add a
          'TIMESTAMP' column to a table produces a
          warning.

   * Changes to account-management statements make the following
     features obsolete.  They are now deprecated:

        * Using 'GRANT' to create users.  Instead, use
          'CREATE USER'.  Following this practice
          makes the 'NO_AUTO_CREATE_USER' SQL mode immaterial for
          'GRANT' statements, so it too is deprecated.

        * Using 'GRANT' to modify account properties other
          than privilege assignments.  This includes authentication,
          SSL, and resource-limit properties.  Instead, establish such
          properties at account-creation time with 'CREATE USER'
          or modify them afterward with 'ALTER USER'.

        * 'IDENTIFIED BY PASSWORD 'HASH_STRING'' syntax for
          'CREATE USER' and 'GRANT'.
          Instead, use 'IDENTIFIED WITH AUTH_PLUGIN AS 'HASH_STRING''
          for 'CREATE USER' and 'ALTER USER',
          where the ''HASH_STRING'' value is in a format
          compatible with the named plugin.

        * The 'PASSWORD()' function is deprecated and should be avoided
          in any context.  Thus, see 'SET PASSWORD ... = PASSWORD('AUTH_STRING')'
          syntax is also
          deprecated.  'SET PASSWORD ... = 'AUTH_STRING''
          syntax is not deprecated; nevertheless, see
          'ALTER USER' is now the preferred statement for
          assigning passwords.

        * The 'old_passwords' system variable.  Account authentication
          plugins can no longer be left unspecified in the 'mysql.user'
          table, so any statement that assigns a password from a
          cleartext string can unambiguously determine the hashing
          method to use on the string before storing it in the
          'mysql.user' table.  This renders 'old_passwords' superflous.

   * The query cache is deprecated.  Deprecation includes these items:

        * The 'FLUSH QUERY CACHE' and 'RESET QUERY CACHE'.
          statements.

        * The 'SQL_CACHE' and 'SQL_NO_CACHE' 'SELECT'.
          modifiers.

        * These system variables: 'have_query_cache',
          'ndb_cache_check_time', 'query_cache_limit',
          'query_cache_min_res_unit', 'query_cache_size',
          'query_cache_type', 'query_cache_wlock_invalidate'.

        * These status variables: 'Qcache_free_blocks',
          'Qcache_free_memory', 'Qcache_hits', 'Qcache_inserts',
          'Qcache_lowmem_prunes', 'Qcache_not_cached',
          'Qcache_queries_in_cache', 'Qcache_total_blocks'.

   * Previously, the '--transaction-isolation' and
     '--transaction-read-only' server startup options corresponded to
     the 'tx_isolation' and 'tx_read_only' system variables.  For better
     name correspondence between startup option and system variable
     names, 'transaction_isolation' and 'transaction_read_only' have
     been created as aliases for 'tx_isolation' and 'tx_read_only'.  The
     'tx_isolation' and 'tx_read_only' variables are now deprecated and
     will be removed in MySQL 8.0.  Applications should be adjusted to
     use 'transaction_isolation' and 'transaction_read_only' instead.

   * The '--skip-innodb' option and its synonyms ('--innodb=OFF',
     '--disable-innodb', and so forth) are deprecated.  These options
     have no effect as of MySQL 5.7.  because 'InnoDB' cannot be
     disabled.

   * The client-side '--ssl' and '--ssl-verify-server-cert' options are
     deprecated.  Use '--ssl-mode=REQUIRED' instead of '--ssl=1' or
     '--enable-ssl'.  Use '--ssl-mode=DISABLED' instead of '--ssl=0',
     '--skip-ssl', or '--disable-ssl'.  Use '--ssl-mode=VERIFY_IDENTITY'
     instead of '--ssl-verify-server-cert' options.  (The server-side
     '--ssl' option is _not_ deprecated.)

     For the C API, 'MYSQL_OPT_SSL_ENFORCE' and
     'MYSQL_OPT_SSL_VERIFY_SERVER_CERT' options for
     'mysql_options()' correspond to the client-side
     '--ssl' and '--ssl-verify-server-cert' options and are deprecated.
     Use 'MYSQL_OPT_SSL_MODE' with an option value of
     'SSL_MODE_REQUIRED' or 'SSL_MODE_VERIFY_IDENTITY' instead.

   * The 'log_warnings' system variable and '--log-warnings' server
     option are deprecated.  Use the 'log_error_verbosity' system
     variable instead.

   * The '--temp-pool' server option is deprecated.

   * The 'binlog_max_flush_queue_time' system variable does nothing in
     MySQL 5.7, and is deprecated as of MySQL 5.7.9.

   * The 'innodb_support_xa' system variable, which enables 'InnoDB'
     support for two-phase commit in XA transactions, is deprecated as
     of MySQL 5.7.10.  'InnoDB' support for two-phase commit in XA
     transactions is always enabled as of MySQL 5.7.10.

   * The 'metadata_locks_cache_size' and 'metadata_locks_hash_instances'
     system variables are deprecated.  These do nothing as of MySQL
     5.7.4.

   * The 'sync_frm' system variable is deprecated.

   * The global 'character_set_database' and 'collation_database' system
     variables are deprecated and will be removed in a future version of
     MySQL.

     Assigning a value to the session 'character_set_database' and
     'collation_database' system variables is deprecated and assignments
     produce a warning.  The session variables will become read only in
     a future version of MySQL and assignments will produce an error.
     It will remain possible to access the session variables to
     determine the database character set and collation for the default
     database.

   * The global scope for the 'sql_log_bin' system variable has been
     deprecated, and this variable can now be set with session scope
     only.  The statement 'SET GLOBAL SQL_LOG_BIN'.
     now produces an error.  It remains possible to read the global
     value of 'sql_log_bin', but doing so produces a warning.  You
     should act now to remove from your applications any dependencies on
     reading this value; the global scope 'sql_log_bin' is removed in
     MySQL 8.0.

   * With the introduction of the data dictionary in MySQL 8.0, the
     '--ignore-db-dir' option and 'ignore_db_dirs' system variable
     became superfluous and were removed in that version.  Consequently,
     they are deprecated in MySQL 5.7.

   * 'GROUP BY' implicitly sorts by default (that is, in the absence of
     'ASC' or 'DESC' designators), but relying on implicit 'GROUP BY'
     sorting in MySQL 5.7 is deprecated.  To achieve a specific sort
     order of grouped results, it is preferable to use To produce a
     given sort order, use explicit 'ASC' or 'DESC' designators for
     'GROUP BY' columns or provide an 'ORDER BY' clause.  'GROUP BY'
     sorting is a MySQL extension that may change in a future release;
     for example, to make it possible for the optimizer to order
     groupings in whatever manner it deems most efficient and to avoid
     the sorting overhead.

   * The 'EXTENDED' and 'PARTITIONS' keywords for the 'EXPLAIN'
     statement are deprecated.  These keywords are still
     recognized but are now unnecessary because their effect is always
     enabled.

   * The 'ENCRYPT()', 'ENCODE()', 'DECODE()', 'DES_ENCRYPT()', and
     'DES_DECRYPT()' encryption functions are deprecated.  For
     'ENCRYPT()', consider using 'SHA2()' instead for one-way hashing.
     For the others, consider using 'AES_ENCRYPT()' and 'AES_DECRYPT()'
     instead.  The '--des-key-file' option, the 'have_crypt' system
     variable, the 'DES_KEY_FILE' option for the 'FLUSH'.
     statement, and the 'HAVE_CRYPT' 'CMake' option also are deprecated.

   * The 'MBREqual()' spatial function is deprecated.  Use 'MBREquals()'
     instead.

   * The functions described in gis-wkb-functions previously
     accepted either WKB strings or geometry arguments.  Use of geometry
     arguments is deprecated.  See that section for guidelines for
     migrating queries away from using geometry arguments.

   * The 'INFORMATION_SCHEMA' 'PROFILING' table
     is deprecated.  Use the Performance Schema instead; see
     performance-schema.

   * The 'INFORMATION_SCHEMA' 'INNODB_LOCKS'.
     and 'INNODB_LOCK_WAITS' tables are
     deprecated, to be removed in MySQL 8.0, which provides replacement
     Performance Schema tables.

   * The Performance Schema 'setup_timers'.
     table is deprecated and is removed in MySQL 8.0, as is the 'TICK'
     row in the 'performance_timers'.
     table.

   * Treatment of '\N' as a synonym for 'NULL' in SQL statements is
     deprecated and is removed in MySQL 8.0; use 'NULL' instead.

     This change does not affect text file import or export operations
     performed with 'LOAD DATA INFILE' or
     'SELECT ... INTO OUTFILE', for which 'NULL' continues
     to be represented by '\N'.  See load-data.

   * 'PROCEDURE ANALYSE()' syntax is deprecated.

   * Comment stripping by the 'mysql' client and the
     options to control it ('--skip-comments', '--comments') are
     deprecated.

   * 'mysqld_safe' support for 'syslog' output is
     deprecated.  Use the native server 'syslog' support used instead.
     See error-log.

   * Conversion of pre-MySQL 5.1 database names containing special
     characters to 5.1 format with the addition of a '#mysql50#' prefix
     is deprecated.  Because of this, the '--fix-db-names' and
     '--fix-table-names' options for 'mysqlcheck' and
     the 'UPGRADE DATA DIRECTORY NAME' clause for the 'ALTER DATABASE'
     statement are also deprecated.

     Upgrades are supported only from one release series to another (for
     example, 5.0 to 5.1, or 5.1 to 5.5), so there should be little
     remaining need for conversion of older 5.0 database names to
     current versions of MySQL. As a workaround, upgrade a MySQL 5.0
     installation to MySQL 5.1 before upgrading to a more recent
     release.

   * 'mysql_install_db' functionality has been
     integrated into the MySQL server, see 'mysqld'.  To use
     this capability to initialize a MySQL installation, if you
     previously invoked 'mysql_install_db'.
     manually, invoke 'mysqld' with the '--initialize' or
     '--initialize-insecure' option, depending on whether you want the
     server to generate a random password for the initial
     ''root'@'localhost'' account.

     'mysql_install_db' is now deprecated, as
     is the special '--bootstrap' option that 'mysql_install_db'
     passes to 'mysqld'.

   * The 'mysql_plugin' utility is deprecated.
     Alternatives include loading plugins at server startup using the
     '--plugin-load' or '--plugin-load-add' option, or at runtime using
     the 'INSTALL PLUGIN' statement.

   * The 'mysql_kill()', 'mysql_list_fields()',
     see 'mysql_list_processes()',
     and 'mysql_refresh()'. C
     API functions are deprecated.  The same is true of the
     corresponding 'COM_PROCESS_KILL', 'COM_FIELD_LIST',
     'COM_PROCESS_INFO', and 'COM_REFRESH' client/server protocol
     commands.  Instead, use 'mysql_query()' to
     execute a 'KILL', 'SHOW COLUMNS',
     'SHOW PROCESSLIST', or 'FLUSH'
     statement, respectively.

   * The 'mysql_shutdown()' C API function is deprecated.  Instead, use
     'mysql_query()' to execute a 'SHUTDOWN'
     statement.

   * The 'libmysqld' embedded server library is deprecated as of MySQL
     5.7.19.  These are also deprecated:

        * The 'mysql_config'. '--libmysqld-libs',
          '--embedded-libs', and '--embedded' options

        * The 'CMake' 'WITH_EMBEDDED_SERVER',
          'WITH_EMBEDDED_SHARED_LIBRARY', and
          'INSTALL_SECURE_FILE_PRIV_EMBEDDEDDIR' options

        * The (undocumented) 'mysql'. '--server-arg' option

        * The 'mysqltest' '--embedded-server', '--server-arg', and
          '--server-file' options

        * The 'mysqltest_embedded' and 'mysql_client_test_embedded' test
          programs

     Because 'libmysqld' uses an API comparable to that of
     'libmysqlclient', the migration path away from 'libmysqld' is
     straightforward:

       1. Bring up a standalone MySQL server (see 'mysqld').

       2. Modify application code to remove API calls that are specific
          to 'libmysqld'.

       3. Modify application code to connect to the standalone MySQL
          server.

       4. Modify build scripts to use 'libmysqlclient' rather than
          'libmysqld'.  For example, if you use 'mysql_config',
          invoke it with the '--libs' option rather than
          '--libmysqld-libs'.

   * The 'replace' utility is deprecated.

   * Support for DTrace is deprecated.

   * The 'JSON_MERGE()' function is deprecated as of MySQL 5.7.22.  Use
     'JSON_MERGE_PRESERVE()' instead.

*Features Removed in MySQL 5.7*

The following items are obsolete and have been removed in MySQL 5.7.
Where alternatives are shown, applications should be updated to use
them.

For MySQL 5.6 applications that use features removed in MySQL 5.7,
statements may fail when replicated from a MySQL 5.6 master to a MySQL
5.7 slave, or may have different effects on master and slave.  To avoid
such problems, applications that use features removed in MySQL 5.7
should be revised to avoid them and use alternatives when possible.

   * Support for passwords that use the older pre-4.1 password hashing
     format is removed, which involves the following changes.
     Applications that use any feature no longer supported must be
     modified.

        * The 'mysql_old_password' authentication plugin is removed.
          Accounts that use this plugin are disabled at startup and the
          server writes an 'unknown plugin' message to the error log.
          For instructions on upgrading accounts that use this plugin,
          see account-upgrades.

        * The '--secure-auth' option to the server and client programs
          is the default, but is now a no-op.  It is deprecated and will
          be removed in a future MySQL release.

        * The '--skip-secure-auth' option to the server and client
          programs is no longer supported and using it produces an
          error.

        * The 'secure_auth' system variable permits only a value of 1; a
          value of 0 is no longer permitted.

        * For the 'old_passwords' system variable, a value of 1 (produce
          pre-4.1 hashes) is no longer permitted.

        * The 'OLD_PASSWORD()' function is removed.

   * In MySQL 5.6.6, the 'YEAR(2)' data type was
     deprecated.  Support for 'YEAR(2)' is now removed.
     Once you upgrade to MySQL 5.7.5 or higher, any remaining
     'YEAR(2)' columns must be converted to 'YEAR(4)'
     to become usable again.  For conversion strategies, see
     migrating-to-year4.  For example, run 'mysql_upgrade'
     after upgrading.

   * The 'innodb_mirrored_log_groups' system variable.  The only
     supported value was 1, so it had no purpose.

   * The 'storage_engine' system variable.  Use 'default_storage_engine'
     instead.

   * The 'thread_concurrency' system variable.

   * The 'timed_mutexes' system variable.  It does nothing and has no
     effect.

   * The 'IGNORE' clause for 'ALTER TABLE'.

   * 'INSERT DELAYED' is no longer supported.  The server
     recognizes but ignores the 'DELAYED' keyword, handles the insert as
     a nondelayed insert, and generates an
     'ER_WARN_LEGACY_SYNTAX_CONVERTED' warning.  ('INSERT DELAYED is no
     longer supported. The statement was converted to INSERT.')
     Similarly, see 'REPLACE DELAYED' is handled as a
     nondelayed replace.  The 'DELAYED' keyword will be removed in a
     future release.

     In addition, several 'DELAYED'-related options or features were
     removed:

        * The '--delayed-insert' option for 'mysqldump'.

        * The 'COUNT_WRITE_DELAYED', 'SUM_TIMER_WRITE_DELAYED',
          'MIN_TIMER_WRITE_DELAYED', 'AVG_TIMER_WRITE_DELAYED', and
          'MAX_TIMER_WRITE_DELAYED' columns of the Performance Schema
          'table_lock_waits_summary_by_table'
          table.

        * 'mysqlbinlog' no longer writes comments
          mentioning 'INSERT DELAYED'.

   * Database symlinking on Windows using for '.sym' files has been
     removed because it is redundant with native symlink support
     available using 'mklink'.  Any '.sym' file symbolic links will be
     ignored and should be replaced with symlinks created using
     'mklink'.  See windows-symbolic-links.

   * The unused '--basedir', '--datadir', and '--tmpdir' options for
     'mysql_upgrade' were removed.

   * Previously, program options could be specified in full or as any
     unambiguous prefix.  For example, the '--compress' option could be
     given to 'mysqldump' as '--compr', but not as
     '--comp' because the latter is ambiguous.  Option prefixes are no
     longer supported; only full options are accepted.  This is because
     prefixes can cause problems when new options are implemented for
     programs and a prefix that is currently unambiguous might become
     ambiguous in the future.  Some implications of this change:

        * The '--key-buffer' option must now be specified as
          '--key-buffer-size'.

        * The '--skip-grant' option must now be specified as
          '--skip-grant-tables'.

   * 'SHOW ENGINE INNODB MUTEX' output is removed.
     Comparable information can be generated by creating views on
     Performance Schema tables.

   * The 'InnoDB' Tablespace Monitor and 'InnoDB' Table Monitor are
     removed.  For the Table Monitor, equivalent information can be
     obtained from 'InnoDB' 'INFORMATION_SCHEMA' tables.

   * The specially named tables used to enable and disable the standard
     'InnoDB' Monitor and 'InnoDB' Lock Monitor ('innodb_monitor' and
     'innodb_lock_monitor') are removed and replaced by two dynamic
     system variables: 'innodb_status_output' and
     'innodb_status_output_locks'.  For additional information, see
     innodb-monitors.

   * The 'innodb_use_sys_malloc' and 'innodb_additional_mem_pool_size'
     system variables, which were deprecated in MySQL 5.6.3, were
     removed.

   * The 'msql2mysql', 'mysql_convert_table_format', 'mysql_find_rows',
     'mysql_fix_extensions', 'mysql_setpermission', 'mysql_waitpid',
     'mysql_zap', 'mysqlaccess', and 'mysqlbug' utilities.

   * The 'mysqlhotcopy' utility.  Alternatives include
     'mysqldump' and MySQL Enterprise Backup.

   * The 'binary-configure.sh' script.

   * The 'INNODB_PAGE_ATOMIC_REF_COUNT' 'CMake' option is removed.

   * The 'innodb_create_intrinsic' option is removed.

   * The 'innodb_optimize_point_storage' option and related internal
     data types ('DATA_POINT' and 'DATA_VAR_POINT') were removed.

   * The 'innodb_log_checksum_algorithm' option is removed.

1.5 Server and Status Variables and Options Added, Deprecated, or Removed in MySQL 5.7
======================================================================================

This section lists server variables, status variables, and options that
were added for the first time, have been deprecated, or have been
removed in MySQL 5.7.

   * optvars-added

   * optvars-deprecated

   * optvars-removed

*Options and Variables Introduced in MySQL 5.7*

The following system variables, status variables, and options are new in
MySQL 5.7, and have not been included in any previous release series.

   * 'group_replication_group_name': Added in MySQL 5.7.17.

   * 'group_replication_start_on_boot': Added in MySQL 5.7.17.

   * 'group_replication_local_address': Added in MySQL 5.7.17.

   * 'group_replication_member_weight': Added in MySQL 5.7.20.

   * 'group_replication_group_seeds': Added in MySQL 5.7.17.

   * 'group_replication_force_members': Added in MySQL 5.7.17.

   * 'group_replication_bootstrap_group': Added in MySQL 5.7.17.

   * 'group_replication_poll_spin_loops': Added in MySQL 5.7.17.

   * 'group_replication_recovery_retry_count': Added in MySQL 5.7.17.

   * 'group_replication_recovery_reconnect_interval': Added in MySQL
     5.7.17.

   * 'group_replication_recovery_use_ssl': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_ca': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_capath': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_cert': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_key': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_cipher': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_crl': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_crlpath': Added in MySQL 5.7.17.

   * 'group_replication_recovery_ssl_verify_server_cert': Added in MySQL
     5.7.17.

   * 'group_replication_recovery_complete_at': Added in MySQL 5.7.17.

   * 'group_replication_components_stop_timeout': Added in MySQL 5.7.17.

   * 'group_replication_allow_local_lower_version_join': Added in MySQL
     5.7.17.

   * 'group_replication_allow_local_disjoint_gtids_join': Added in MySQL
     5.7.17.

   * 'group_replication_auto_increment_increment': Added in MySQL
     5.7.17.

   * 'group_replication_compression_threshold': Added in MySQL 5.7.17.

   * 'group_replication_gtid_assignment_block_size': Added in MySQL
     5.7.17.

   * 'group_replication_ssl_mode': Added in MySQL 5.7.17.

   * 'group_replication_single_primary_mode': Added in MySQL 5.7.17.

   * 'group_replication_transaction_size_limit': Added in MySQL 5.7.19.

   * 'group_replication_unreachable_majority_timeout': Added in MySQL
     5.7.19.

   * 'group_replication_enforce_update_everywhere_checks': Added in
     MySQL 5.7.17.

   * 'group_replication_flow_control_mode': Added in MySQL 5.7.17.

   * 'group_replication_flow_control_certifier_threshold': Added in
     MySQL 5.7.17.

   * 'group_replication_flow_control_applier_threshold': Added in MySQL
     5.7.17.

   * 'group_replication_ip_whitelist': Added in MySQL 5.7.17.

   * 'mysqlx-bind-address': Added in MySQL 5.7.17.

   * 'mysqlx-min-worker-threads': Added in MySQL 5.7.12.

   * 'mysqlx-port-open-timeout': Added in MySQL 5.7.17.

   * 'mysqlx-socket': Added in MySQL 5.7.15.

   * 'mysqlx_max_allowed_packet': Added in MySQL 5.7.12.

   * 'mysqlx_port': Added in MySQL 5.7.12.

   * 'mysqlx_port_open_timeout': Added in MySQL 5.7.12.

   * 'mysqlx_socket': Added in MySQL 5.7.15.

   * 'audit-log': Added in MySQL 5.7.9.

   * 'audit_log_buffer_size': Added in MySQL 5.7.9.

   * 'audit_log_compression': Added in MySQL 5.7.21.

   * 'audit_log_connection_policy': Added in MySQL 5.7.9.

   * 'audit_log_current_session': Added in MySQL 5.7.9.

   * 'Audit_log_current_size': Added in MySQL 5.7.9.

   * 'Audit_log_event_max_drop_size': Added in MySQL 5.7.9.

   * 'Audit_log_events': Added in MySQL 5.7.9.

   * 'Audit_log_events_filtered': Added in MySQL 5.7.9.

   * 'Audit_log_events_lost': Added in MySQL 5.7.9.

   * 'Audit_log_events_written': Added in MySQL 5.7.9.

   * 'audit_log_encryption': Added in MySQL 5.7.21.

   * 'audit_log_exclude_accounts': Added in MySQL 5.7.9.

   * 'audit_log_file': Added in MySQL 5.7.9.

   * 'audit_log_filter_id': Added in MySQL 5.7.13.

   * 'audit_log_flush': Added in MySQL 5.7.9.

   * 'audit_log_format': Added in MySQL 5.7.9.

   * 'audit_log_include_accounts': Added in MySQL 5.7.9.

   * 'audit_log_policy': Added in MySQL 5.7.9.

   * 'audit_log_read_buffer_size': Added in MySQL 5.7.21.

   * 'audit_log_rotate_on_size': Added in MySQL 5.7.9.

   * 'audit_log_statement_policy': Added in MySQL 5.7.9.

   * 'audit_log_strategy': Added in MySQL 5.7.9.

   * 'Audit_log_total_size': Added in MySQL 5.7.9.

   * 'Audit_log_write_waits': Added in MySQL 5.7.9.

   * 'authentication_windows_log_level': Added in MySQL 5.7.9.

   * 'authentication_windows_use_principal_name': Added in MySQL 5.7.9.

   * 'auto_generate_certs': Added in MySQL 5.7.5.

   * 'avoid_temporal_upgrade': Added in MySQL 5.7.6.

   * 'binlog_error_action': Added in MySQL 5.7.6.

   * 'binlog_group_commit_sync_delay': Added in MySQL 5.7.5.

   * 'binlog_group_commit_sync_no_delay_count': Added in MySQL 5.7.5.

   * 'binlog_gtid_simple_recovery': Added in MySQL 5.7.6.

   * 'binlog_transaction_dependency_tracking': Added in MySQL 5.7.22.

   * 'binlog_transaction_dependency_history_size': Added in MySQL
     5.7.22.

   * 'binlogging_impossible_mode': Added in MySQL 5.7.5.

   * 'block_encryption_mode': Added in MySQL 5.7.4.

   * 'check_proxy_users': Added in MySQL 5.7.7.

   * 'Com_change_repl_filter': Added in MySQL 5.7.3.

   * 'Com_explain_other': Added in MySQL 5.7.2.

   * 'Com_group_replication_start': Added in MySQL 5.7.6.

   * 'Com_group_replication_stop': Added in MySQL 5.7.6.

   * 'Com_show_create_user': Added in MySQL 5.7.6.

   * 'Com_show_slave_status_nonblocking': Added in MySQL 5.7.2.

   * 'Com_show_slave_status_nonblocking': Added in MySQL 5.7.6.

   * 'Com_signal': Added in MySQL 5.7.9.

   * 'Connection_control_delay_generated': Added in MySQL 5.7.17.

   * 'connection_control_failed_connections_threshold': Added in MySQL
     5.7.17.

   * 'connection_control_max_connection_delay': Added in MySQL 5.7.17.

   * 'connection_control_min_connection_delay': Added in MySQL 5.7.17.

   * 'daemonize': Added in MySQL 5.7.6.

   * 'default_authentication_plugin': Added in MySQL 5.7.2.

   * 'default_password_lifetime': Added in MySQL 5.7.4.

   * 'disable-partition-engine-check': Added in MySQL 5.7.17.

   * 'disabled_storage_engines': Added in MySQL 5.7.8.

   * 'disconnect_on_expired_password': Added in MySQL 5.7.1.

   * 'early-plugin-load': Added in MySQL 5.7.11.

   * 'executed-gtids-compression-period': Added in MySQL 5.7.5.

   * 'executed_gtids_compression_period': Added in MySQL 5.7.5.

   * 'Firewall_access_denied': Added in MySQL 5.7.9.

   * 'Firewall_access_granted': Added in MySQL 5.7.9.

   * 'Firewall_cached_entries': Added in MySQL 5.7.9.

   * 'gtid-executed-compression-period': Added in MySQL 5.7.6.

   * 'gtid_executed_compression_period': Added in MySQL 5.7.6.

   * 'have_statement_timeout': Added in MySQL 5.7.4.

   * 'initialize': Added in MySQL 5.7.6.

   * 'initialize-insecure': Added in MySQL 5.7.6.

   * 'innodb_adaptive_hash_index_parts': Added in MySQL 5.7.8.

   * 'innodb_background_drop_list_empty': Added in MySQL 5.7.10.

   * 'innodb_buffer_pool_chunk_size': Added in MySQL 5.7.5.

   * 'innodb_buffer_pool_dump_pct': Added in MySQL 5.7.2.

   * 'Innodb_buffer_pool_resize_status': Added in MySQL 5.7.5.

   * 'innodb_compress_debug': Added in MySQL 5.7.8.

   * 'innodb_deadlock_detect': Added in MySQL 5.7.15.

   * 'innodb_default_row_format': Added in MySQL 5.7.9.

   * 'innodb_disable_resize_buffer_pool_debug': Added in MySQL 5.7.6.

   * 'innodb_fill_factor': Added in MySQL 5.7.5.

   * 'innodb_flush_sync': Added in MySQL 5.7.8.

   * 'innodb_ft_result_cache_limit': Added in MySQL 5.7.2.

   * 'innodb_ft_total_cache_size': Added in MySQL 5.7.2.

   * 'innodb_log_checksum_algorithm': Added in MySQL 5.7.8.

   * 'innodb_log_checksums': Added in MySQL 5.7.9.

   * 'innodb_log_write_ahead_size': Added in MySQL 5.7.4.

   * 'innodb_max_undo_log_size': Added in MySQL 5.7.5.

   * 'innodb_merge_threshold_set_all_debug': Added in MySQL 5.7.6.

   * 'innodb_numa_interleave': Added in MySQL 5.7.9.

   * 'innodb_optimize_point_storage': Added in MySQL 5.7.5.

   * 'innodb_page_cleaners': Added in MySQL 5.7.4.

   * 'innodb_purge_rseg_truncate_frequency': Added in MySQL 5.7.5.

   * 'innodb_stats_include_delete_marked': Added in MySQL 5.7.17.

   * 'innodb_status_output': Added in MySQL 5.7.4.

   * 'innodb_status_output_locks': Added in MySQL 5.7.4.

   * 'innodb_sync_debug': Added in MySQL 5.7.8.

   * 'innodb_temp_data_file_path': Added in MySQL 5.7.1.

   * 'innodb_tmpdir': Added in MySQL 5.7.11.

   * 'innodb_undo_log_truncate': Added in MySQL 5.7.5.

   * 'internal_tmp_disk_storage_engine': Added in MySQL 5.7.5.

   * 'keyring_aws_cmk_id': Added in MySQL 5.7.19.

   * 'keyring_aws_conf_file': Added in MySQL 5.7.19.

   * 'keyring_aws_data_file': Added in MySQL 5.7.19.

   * 'keyring_aws_region': Added in MySQL 5.7.19.

   * 'keyring_encrypted_file_data': Added in MySQL 5.7.21.

   * 'keyring_encrypted_file_password': Added in MySQL 5.7.21.

   * 'keyring_file_data': Added in MySQL 5.7.11.

   * 'keyring-migration-destination': Added in MySQL 5.7.21.

   * 'keyring-migration-host': Added in MySQL 5.7.21.

   * 'keyring-migration-password': Added in MySQL 5.7.21.

   * 'keyring-migration-port': Added in MySQL 5.7.21.

   * 'keyring-migration-socket': Added in MySQL 5.7.21.

   * 'keyring-migration-source': Added in MySQL 5.7.21.

   * 'keyring-migration-user': Added in MySQL 5.7.21.

   * 'keyring_okv_conf_dir': Added in MySQL 5.7.12.

   * 'keyring_operations': Added in MySQL 5.7.21.

   * 'authentication_ldap_sasl_auth_method_name': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_bind_base_dn': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_bind_root_dn': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_bind_root_pwd': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_ca_path': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_group_search_attr': Added in MySQL
     5.7.19.

   * 'authentication_ldap_sasl_group_search_filter': Added in MySQL
     5.7.21.

   * 'authentication_ldap_sasl_init_pool_size': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_log_status': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_max_pool_size': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_server_host': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_server_port': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_tls': Added in MySQL 5.7.19.

   * 'authentication_ldap_sasl_user_search_attr': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_auth_method_name': Added in MySQL
     5.7.19.

   * 'authentication_ldap_simple_bind_base_dn': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_bind_root_dn': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_bind_root_pwd': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_ca_path': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_group_search_attr': Added in MySQL
     5.7.19.

   * 'authentication_ldap_simple_group_search_filter': Added in MySQL
     5.7.21.

   * 'authentication_ldap_simple_init_pool_size': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_log_status': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_max_pool_size': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_server_host': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_server_port': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_tls': Added in MySQL 5.7.19.

   * 'authentication_ldap_simple_user_search_attr': Added in MySQL
     5.7.19.

   * 'Locked_connects': Added in MySQL 5.7.6.

   * 'log_backward_compatible_user_definitions': Added in MySQL 5.7.6.

   * 'log_builtin_as_identified_by_password': Added in MySQL 5.7.9.

   * 'log_error_verbosity': Added in MySQL 5.7.2.

   * 'log_slow_admin_statements': Added in MySQL 5.7.1.

   * 'log_slow_slave_statements': Added in MySQL 5.7.1.

   * 'log_statements_unsafe_for_binlog': Added in MySQL 5.7.11.

   * 'log_syslog': Added in MySQL 5.7.5.

   * 'log_syslog_facility': Added in MySQL 5.7.5.

   * 'log_syslog_include_pid': Added in MySQL 5.7.5.

   * 'log_syslog_tag': Added in MySQL 5.7.5.

   * 'log_timestamps': Added in MySQL 5.7.2.

   * 'max_digest_length': Added in MySQL 5.7.6.

   * 'max_execution_time': Added in MySQL 5.7.8.

   * 'Max_execution_time_exceeded': Added in MySQL 5.7.8.

   * 'Max_execution_time_set': Added in MySQL 5.7.8.

   * 'Max_execution_time_set_failed': Added in MySQL 5.7.8.

   * 'max_points_in_geometry': Added in MySQL 5.7.8.

   * 'max_statement_time': Added in MySQL 5.7.4.

   * 'Max_statement_time_exceeded': Added in MySQL 5.7.4.

   * 'Max_statement_time_set': Added in MySQL 5.7.4.

   * 'Max_statement_time_set_failed': Added in MySQL 5.7.4.

   * 'Max_used_connections_time': Added in MySQL 5.7.5.

   * 'mecab_charset': Added in MySQL 5.7.6.

   * 'mecab_rc_file': Added in MySQL 5.7.6.

   * 'mysql_native_password_proxy_users': Added in MySQL 5.7.7.

   * 'mysql_firewall_mode': Added in MySQL 5.7.9.

   * 'mysql_firewall_trace': Added in MySQL 5.7.9.

   * 'ngram_token_size': Added in MySQL 5.7.6.

   * 'offline_mode': Added in MySQL 5.7.5.

   * 'parser_max_mem_size': Added in MySQL 5.7.12.

   * 'performance-schema-consumer-events-transactions-current': Added in
     MySQL 5.7.3.

   * 'performance-schema-consumer-events-transactions-history': Added in
     MySQL 5.7.3.

   * 'performance-schema-consumer-events-transactions-history-long':
     Added in MySQL 5.7.3.

   * 'performance_schema_events_transactions_history_long_size': Added
     in MySQL 5.7.3.

   * 'performance_schema_events_transactions_history_size': Added in
     MySQL 5.7.3.

   * 'Performance_schema_index_stat_lost': Added in MySQL 5.7.6.

   * 'performance_schema_max_digest_length': Added in MySQL 5.7.8.

   * 'performance_schema_max_index_stat': Added in MySQL 5.7.6.

   * 'performance_schema_max_memory_classes': Added in MySQL 5.7.2.

   * 'performance_schema_max_metadata_locks': Added in MySQL 5.7.3.

   * 'performance_schema_max_prepared_statements_instances': Added in
     MySQL 5.7.4.

   * 'performance_schema_max_program_instances': Added in MySQL 5.7.2.

   * 'performance_schema_max_sql_text_length': Added in MySQL 5.7.6.

   * 'performance_schema_max_statement_stack': Added in MySQL 5.7.2.

   * 'performance_schema_max_table_lock_stat': Added in MySQL 5.7.6.

   * 'Performance_schema_memory_classes_lost': Added in MySQL 5.7.2.

   * 'Performance_schema_metadata_lock_lost': Added in MySQL 5.7.3.

   * 'Performance_schema_nested_statement_lost': Added in MySQL 5.7.2.

   * 'Performance_schema_prepared_statements_lost': Added in MySQL
     5.7.4.

   * 'Performance_schema_program_lost': Added in MySQL 5.7.2.

   * 'Performance_schema_table_lock_stat_lost': Added in MySQL 5.7.6.

   * 'range_optimizer_max_mem_size': Added in MySQL 5.7.9.

   * 'rbr_exec_mode': Added in MySQL 5.7.1.

   * 'require_secure_transport': Added in MySQL 5.7.8.

   * 'rewriter_enabled': Added in MySQL 5.7.6.

   * 'rewriter_verbose': Added in MySQL 5.7.6.

   * 'Rewriter_number_loaded_rules': Added in MySQL 5.7.6.

   * 'Rewriter_number_reloads': Added in MySQL 5.7.6.

   * 'Rewriter_number_rewritten_queries': Added in MySQL 5.7.6.

   * 'Rewriter_reload_error': Added in MySQL 5.7.6.

   * 'rpl_semi_sync_master_wait_for_slave_count': Added in MySQL 5.7.3.

   * 'rpl_semi_sync_master_wait_point': Added in MySQL 5.7.2.

   * 'rpl_stop_slave_timeout': Added in MySQL 5.7.2.

   * 'session_track_gtids': Added in MySQL 5.7.6.

   * 'session_track_schema': Added in MySQL 5.7.4.

   * 'session_track_state_change': Added in MySQL 5.7.4.

   * 'session_track_system_variables': Added in MySQL 5.7.4.

   * 'sha256_password_auto_generate_rsa_keys': Added in MySQL 5.7.5.

   * 'sha256_password_proxy_users': Added in MySQL 5.7.7.

   * 'show_compatibility_56': Added in MySQL 5.7.6.

   * 'show_create_table_verbosity': Added in MySQL 5.7.22.

   * 'show_old_temporals': Added in MySQL 5.7.6.

   * 'simplified_binlog_gtid_recovery': Added in MySQL 5.7.5.

   * 'slave-parallel-type': Added in MySQL 5.7.2.

   * 'slave_parallel_type': Added in MySQL 5.7.2.

   * 'slave_preserve_commit_order': Added in MySQL 5.7.5.

   * 'super_read_only': Added in MySQL 5.7.8.

   * 'thread_pool_algorithm': Added in MySQL 5.7.9.

   * 'thread_pool_high_priority_connection': Added in MySQL 5.7.9.

   * 'thread_pool_max_unused_threads': Added in MySQL 5.7.9.

   * 'thread_pool_prio_kickup_timer': Added in MySQL 5.7.9.

   * 'thread_pool_size': Added in MySQL 5.7.9.

   * 'thread_pool_stall_limit': Added in MySQL 5.7.9.

   * 'tls_version': Added in MySQL 5.7.10.

   * 'transaction_write_set_extraction': Added in MySQL 5.7.6.

   * 'validate_password_check_user_name': Added in MySQL 5.7.15.

   * 'validate_password_dictionary_file_last_parsed': Added in MySQL
     5.7.8.

   * 'validate_password_dictionary_file_words_count': Added in MySQL
     5.7.8.

   * 'version_tokens_session': Added in MySQL 5.7.8.

   * 'version_tokens_session_number': Added in MySQL 5.7.8.

*Options and Variables Deprecated in MySQL 5.7*

The following system variables, status variables, and options have been
deprecated in MySQL 5.7.

   * 'group_replication_allow_local_disjoint_gtids_join': Allow the
     current server to join the group even if it has transactions not
     present in the group.  Deprecated as of MySQL 5.7.21.

   * 'avoid_temporal_upgrade': Whether ALTER TABLE should upgrade
     pre-5.6.4 temporal columns.  Deprecated as of MySQL 5.7.6.

   * 'binlog_max_flush_queue_time': How long to read transactions before
     flushing to binary log.  Deprecated as of MySQL 5.7.9.

   * 'bootstrap': Used by mysql installation scripts.  Deprecated as of
     MySQL 5.7.6.

   * 'des-key-file': Load keys for des_encrypt() and des_encrypt from
     given file.  Deprecated as of MySQL 5.7.6.

   * 'disable-partition-engine-check': Whether to disable the startup
     check for tables with nonnative partitioning.  Deprecated as of
     MySQL 5.7.17.

   * 'executed-gtids-compression-period': Deprecated and will be removed
     in a future version; use the renamed
     gtid-executed-compression-period instead.  Deprecated as of MySQL
     5.7.6.

   * 'executed_gtids_compression_period': Deprecated and will be removed
     in a future version; use the renamed
     gtid_executed_compression_period instead.  Deprecated as of MySQL
     5.7.6.

   * 'have_crypt': Availability of the crypt() system call.  Deprecated
     as of MySQL 5.7.6.

   * 'have_query_cache': Whether mysqld supports query cache.
     Deprecated as of MySQL 5.7.20.

   * 'ignore-db-dir': Treat directory as nondatabase directory.
     Deprecated as of MySQL 5.7.16.

   * 'ignore_db_dirs': Directories treated as nondatabase directories.
     Deprecated as of MySQL 5.7.16.

   * 'innodb': Enable InnoDB (if this version of MySQL supports it).
     Deprecated as of MySQL 5.7.5.

   * 'Innodb_available_undo_logs': Display the total number of InnoDB
     rollback segments; different from innodb_rollback_segments, which
     displays the number of active rollback segments.  Deprecated as of
     MySQL 5.7.19.

   * 'innodb_file_format': The format for new InnoDB tables.  Deprecated
     as of MySQL 5.7.7.

   * 'innodb_file_format_check': Whether InnoDB performs file format
     compatibility checking.  Deprecated as of MySQL 5.7.7.

   * 'innodb_file_format_max': The file format tag in the shared
     tablespace.  Deprecated as of MySQL 5.7.7.

   * 'innodb_large_prefix': Enables longer keys for column prefix
     indexes.  Deprecated as of MySQL 5.7.7.

   * 'innodb_support_xa': Enable InnoDB support for the XA two-phase
     commit.  Deprecated as of MySQL 5.7.10.

   * 'innodb_undo_logs': Defines the number of undo logs (rollback
     segments) used by InnoDB; an alias for innodb_rollback_segments.
     Deprecated as of MySQL 5.7.19.

   * 'innodb_undo_tablespaces': The number of tablespace files that
     rollback segments are divided between.  Deprecated as of MySQL
     5.7.21.

   * 'log-warnings': Log some noncritical warnings to the log file.
     Deprecated as of MySQL 5.7.2.

   * 'metadata_locks_cache_size': Size of the metadata locks cache.
     Deprecated as of MySQL 5.7.4.

   * 'metadata_locks_hash_instances': Number of metadata lock hashes.
     Deprecated as of MySQL 5.7.4.

   * 'old_passwords': Selects password hashing method for PASSWORD().
     Deprecated as of MySQL 5.7.6.

   * 'partition': Enable (or disable) partitioning support.  Deprecated
     as of MySQL 5.7.16.

   * 'Qcache_free_blocks': Number of free memory blocks in the query
     cache.  Deprecated as of MySQL 5.7.20.

   * 'Qcache_free_memory': The amount of free memory for the query
     cache.  Deprecated as of MySQL 5.7.20.

   * 'Qcache_hits': Number of query cache hits.  Deprecated as of MySQL
     5.7.20.

   * 'Qcache_inserts': Number of query cache inserts.  Deprecated as of
     MySQL 5.7.20.

   * 'Qcache_lowmem_prunes': Number of queries that were deleted from
     the query cache due to lack of free memory in the cache.
     Deprecated as of MySQL 5.7.20.

   * 'Qcache_not_cached': Number of noncached queries (not cacheable, or
     not cached due to the query_cache_type setting).  Deprecated as of
     MySQL 5.7.20.

   * 'Qcache_queries_in_cache': Number of queries registered in the
     query cache.  Deprecated as of MySQL 5.7.20.

   * 'Qcache_total_blocks': The total number of blocks in the query
     cache.  Deprecated as of MySQL 5.7.20.

   * 'query_cache_limit': Do not cache results that are bigger than
     this.  Deprecated as of MySQL 5.7.20.

   * 'query_cache_min_res_unit': Minimal size of unit in which space for
     results is allocated (last unit will be trimmed after writing all
     result data).  Deprecated as of MySQL 5.7.20.

   * 'query_cache_size': The memory allocated to store results from old
     queries.  Deprecated as of MySQL 5.7.20.

   * 'query_cache_type': Query cache type.  Deprecated as of MySQL
     5.7.20.

   * 'query_cache_wlock_invalidate': Invalidate queries in query cache
     on LOCK for write.  Deprecated as of MySQL 5.7.20.

   * 'secure-auth': Disallow authentication for accounts that have old
     (pre-4.1) passwords.  Deprecated as of MySQL 5.7.5.

   * 'show_compatibility_56': Compatibility for SHOW STATUS/VARIABLES.
     Deprecated as of MySQL 5.7.6.

   * 'show_old_temporals': Whether SHOW CREATE TABLE should indicate
     pre-5.6.4 temporal columns.  Deprecated as of MySQL 5.7.6.

   * 'simplified_binlog_gtid_recovery': Controls how binary logs are
     iterated during GTID recovery.  Deprecated as of MySQL 5.7.6.

   * 'skip-partition': Do not enable user-defined partitioning.
     Deprecated as of MySQL 5.7.16.

   * 'Slave_heartbeat_period': The slave's replication heartbeat
     interval, in seconds.  Deprecated as of MySQL 5.7.6.

   * 'Slave_last_heartbeat': Shows when the latest heartbeat signal was
     received, in TIMESTAMP format.  Deprecated as of MySQL 5.7.6.

   * 'Slave_received_heartbeats': Number of heartbeats received by a
     replication slave since previous reset.  Deprecated as of MySQL
     5.7.6.

   * 'Slave_retried_transactions': The total number of times since
     startup that the replication slave SQL thread has retried
     transactions.  Deprecated as of MySQL 5.7.6.

   * 'Slave_running': The state of this server as a replication slave
     (slave I/O thread status).  Deprecated as of MySQL 5.7.6.

   * 'sync_frm': Sync .frm to disk on create.  Enabled by default.
     Deprecated as of MySQL 5.7.6.

   * 'temp-pool': Using this option will cause most temporary files
     created to use a small set of names, rather than a unique name for
     each new file.  Deprecated as of MySQL 5.7.18.

   * 'tx_isolation': The default transaction isolation level.
     Deprecated as of MySQL 5.7.20.

   * 'tx_read_only': Default transaction access mode.  Deprecated as of
     MySQL 5.7.20.

*Options and Variables Removed in MySQL 5.7*

The following system variables, status variables, and options have been
removed in MySQL 5.7.

   * 'binlogging_impossible_mode': Deprecated and will be removed in a
     future version.  Use the renamed binlog_error_action instead..
     Removed in MySQL 5.7.6.

   * 'default-authentication-plugin': The default authentication plugin.
     Removed in MySQL 5.7.2.

   * 'enable-pstack
     (http://dev.mysql.com/doc/refman/5.5/en/server-options.html#option_mysqld_enable-pstack)':
     Print a symbolic stack trace on failure.  Removed in MySQL 5.5.7.

   * 'innodb_log_checksum_algorithm': Specifies how to generate and
     verify the checksum stored in each redo log disk block.  Removed in
     MySQL 5.7.9.

   * 'innodb_additional_mem_pool_size': Size of a memory pool InnoDB
     uses to store data dictionary information and other internal data
     structures.  Removed in MySQL 5.7.4.

   * 'innodb_optimize_point_storage': Enable this option to store POINT
     data as fixed-length data rather than a variable-length data.
     Removed in MySQL 5.7.6.

   * 'innodb_use_sys_malloc': Whether InnoDB uses the OS or its own
     memory allocator.  Removed in MySQL 5.7.4.

   * 'log-slow-admin-statements': Log slow OPTIMIZE, ANALYZE, ALTER and
     other administrative statements to the slow query log if it is
     open.  Removed in MySQL 5.7.1.

   * 'log-slow-slave-statements': Cause slow statements as executed by
     the slave to be written to the slow query log.  Removed in MySQL
     5.7.1.

   * 'log_backward_compatible_user_definitions': Whether to log
     CREATE/ALTER USER, GRANT in backward-compatible fashion.  Removed
     in MySQL 5.7.9.

   * 'max_statement_time': Statement execution timeout value.  Removed
     in MySQL 5.7.8.

   * 'Max_statement_time_exceeded': Number of statements that exceeded
     the execution timeout value.  Removed in MySQL 5.7.8.

   * 'Max_statement_time_set': Number of statements for which execution
     timeout was set.  Removed in MySQL 5.7.8.

   * 'Max_statement_time_set_failed': Number of statements for which
     execution timeout setting failed.  Removed in MySQL 5.7.8.

   * 'storage_engine': The default storage engine.  Removed in MySQL
     5.7.5.

   * 'thread_concurrency': Permits the application to give the threads
     system a hint for the desired number of threads that should be run
     at the same time.  Removed in MySQL 5.7.2.

   * 'timed_mutexes': Specify whether to time mutexes (only InnoDB
     mutexes are currently supported).  Removed in MySQL 5.7.5.

1.6 MySQL Information Sources
=============================

This section lists sources of additional information that you may find
helpful, such as MySQL websites, mailing lists, user forums, and
Internet Relay Chat.

1.6.1 MySQL Websites
--------------------

The primary website for MySQL documentation is
<http://dev.mysql.com/doc/>.  Online and downloadable documentation
formats are available for the MySQL Reference Manual, MySQL Connectors,
and more.

The MySQL developers provide information about new and upcoming features
as the MySQL Server Blog (http://mysqlserverteam.com/).

1.6.2 MySQL Mailing Lists
-------------------------

This section introduces the MySQL mailing lists and provides guidelines
as to how the lists should be used.  When you subscribe to a mailing
list, you receive all postings to the list as email messages.  You can
also send your own questions and answers to the list.

To subscribe to or unsubscribe from any of the mailing lists described
in this section, visit <http://lists.mysql.com/>.  For most of them, you
can select the regular version of the list where you get individual
messages, or a digest version where you get one large message per day.

Please _do not_ send messages about subscribing or unsubscribing to any
of the mailing lists, because such messages are distributed
automatically to thousands of other users.

Your local site may have many subscribers to a MySQL mailing list.  If
so, the site may have a local mailing list, so that messages sent from
'lists.mysql.com' to your site are propagated to the local list.  In
such cases, please contact your system administrator to be added to or
dropped from the local MySQL list.

To have traffic for a mailing list go to a separate mailbox in your mail
program, set up a filter based on the message headers.  You can use
either the 'List-ID:' or 'Delivered-To:' headers to identify list
messages.

The MySQL mailing lists are as follows:

   * 'announce'

     The list for announcements of new versions of MySQL and related
     programs.  This is a low-volume list to which all MySQL users
     should subscribe.

   * 'mysql'

     The main list for general MySQL discussion.  Please note that some
     topics are better discussed on the more-specialized lists.  If you
     post to the wrong list, you may not get an answer.

   * 'bugs'

     The list for people who want to stay informed about issues reported
     since the last release of MySQL or who want to be actively involved
     in the process of bug hunting and fixing.  See bug-reports.

   * 'internals'

     The list for people who work on the MySQL code.  This is also the
     forum for discussions on MySQL development and for posting patches.

   * 'mysqldoc'

     The list for people who work on the MySQL documentation.

   * 'benchmarks'

     The list for anyone interested in performance issues.  Discussions
     concentrate on database performance (not limited to MySQL), but
     also include broader categories such as performance of the kernel,
     file system, disk system, and so on.

   * 'packagers'

     The list for discussions on packaging and distributing MySQL. This
     is the forum used by distribution maintainers to exchange ideas on
     packaging MySQL and on ensuring that MySQL looks and feels as
     similar as possible on all supported platforms and operating
     systems.

   * 'java'

     The list for discussions about the MySQL server and Java.  It is
     mostly used to discuss JDBC drivers such as MySQL Connector/J.

   * 'win32'

     The list for all topics concerning the MySQL software on Microsoft
     operating systems, such as Windows 9x, Me, NT, 2000, XP, and 2003.

   * 'myodbc'

     The list for all topics concerning connecting to the MySQL server
     with ODBC.

   * 'gui-tools'

     The list for all topics concerning MySQL graphical user interface
     tools such as MySQL Workbench.

   * 'cluster'

     The list for discussion of MySQL Cluster.

   * 'dotnet'

     The list for discussion of the MySQL server and the .NET platform.
     It is mostly related to MySQL Connector/Net.

   * 'plusplus'

     The list for all topics concerning programming with the C++ API for
     MySQL.

   * 'perl'

     The list for all topics concerning Perl support for MySQL with
     'DBD::mysql'.

If you're unable to get an answer to your questions from a MySQL mailing
list or forum, one option is to purchase support from Oracle.  This puts
you in direct contact with MySQL developers.

The following MySQL mailing lists are in languages other than English.
These lists are not operated by Oracle.

   * '<mysql-france-subscribe@yahoogroups.com>'

     A French mailing list.

   * '<list@tinc.net>'

     A Korean mailing list.  To subscribe, email 'subscribe mysql
     your@email.address' to this list.

   * '<mysql-de-request@lists.4t2.com>'

     A German mailing list.  To subscribe, email 'subscribe mysql-de
     your@email.address' to this list.  You can find information about
     this mailing list at <http://www.4t2.com/mysql/>.

   * '<mysql-br-request@listas.linkway.com.br>'

     A Portuguese mailing list.  To subscribe, email 'subscribe mysql-br
     your@email.address' to this list.

   * '<mysql-alta@elistas.net>'

     A Spanish mailing list.  To subscribe, email 'subscribe mysql
     your@email.address' to this list.

1.6.2.1 Guidelines for Using the Mailing Lists
..............................................

Please do not post mail messages from your browser with HTML mode turned
on.  Many users do not read mail with a browser.

When you answer a question sent to a mailing list, if you consider your
answer to have broad interest, you may want to post it to the list
instead of replying directly to the individual who asked.  Try to make
your answer general enough that people other than the original poster
may benefit from it.  When you post to the list, please make sure that
your answer is not a duplication of a previous answer.

Try to summarize the essential part of the question in your reply.  Do
not feel obliged to quote the entire original message.

When answers are sent to you individually and not to the mailing list,
it is considered good etiquette to summarize the answers and send the
summary to the mailing list so that others may have the benefit of
responses you received that helped you solve your problem.

1.6.3 MySQL Community Support at the MySQL Forums
-------------------------------------------------

The forums at <http://forums.mysql.com> are an important community
resource.  Many forums are available, grouped into these general
categories:

   * Migration

   * MySQL Usage

   * MySQL Connectors

   * Programming Languages

   * Tools

   * 3rd-Party Applications

   * Storage Engines

   * MySQL Technology

   * SQL Standards

   * Business

1.6.4 MySQL Community Support on Internet Relay Chat (IRC)
----------------------------------------------------------

In addition to the various MySQL mailing lists and forums, you can find
experienced community people on Internet Relay Chat (IRC). These are the
best networks/channels currently known to us:

*freenode* (see <http://www.freenode.net/> for servers)

   * '#mysql' is primarily for MySQL questions, but other database and
     general SQL questions are welcome.  Questions about PHP, Perl, or C
     in combination with MySQL are also common.

   * '#workbench' is primarily for MySQL Workbench related questions and
     thoughts, and it is also a good place to meet the MySQL Workbench
     developers.

1.6.5 MySQL Enterprise
----------------------

Oracle offers technical support in the form of MySQL Enterprise.  For
organizations that rely on the MySQL DBMS for business-critical
production applications, MySQL Enterprise is a commercial subscription
offering which includes:

   * MySQL Enterprise Server

   * MySQL Enterprise Monitor

   * Monthly Rapid Updates and Quarterly Service Packs

   * MySQL Knowledge Base

   * 24x7 Technical and Consultative Support

MySQL Enterprise is available in multiple tiers, giving you the
flexibility to choose the level of service that best matches your needs.
For more information, see MySQL Enterprise
(http://www.mysql.com/products/enterprise/).

1.7 How to Report Bugs or Problems
==================================

Before posting a bug report about a problem, please try to verify that
it is a bug and that it has not been reported already:

   * Start by searching the MySQL online manual at
     <http://dev.mysql.com/doc/>.  We try to keep the manual up to date
     by updating it frequently with solutions to newly found problems.
     In addition, the release notes accompanying the manual can be
     particularly useful since it is quite possible that a newer version
     contains a solution to your problem.  The release notes are
     available at the location just given for the manual.

   * If you get a parse error for an SQL statement, please check your
     syntax closely.  If you cannot find something wrong with it, it is
     extremely likely that your current version of MySQL Server doesn't
     support the syntax you are using.  If you are using the current
     version and the manual doesn't cover the syntax that you are using,
     MySQL Server doesn't support your statement.

     If the manual covers the syntax you are using, but you have an
     older version of MySQL Server, you should check the MySQL change
     history to see when the syntax was implemented.  In this case, you
     have the option of upgrading to a newer version of MySQL Server.

   * For solutions to some common problems, see problems.

   * Search the bugs database at <http://bugs.mysql.com/> to see whether
     the bug has been reported and fixed.

   * Search the MySQL mailing list archives at
     <http://lists.mysql.com/>.  See mailing-lists.

   * You can also use <http://www.mysql.com/search/> to search all the
     Web pages (including the manual) that are located at the MySQL
     website.

If you cannot find an answer in the manual, the bugs database, or the
mailing list archives, check with your local MySQL expert.  If you still
cannot find an answer to your question, please use the following
guidelines for reporting the bug.

The normal way to report bugs is to visit <http://bugs.mysql.com/>,
which is the address for our bugs database.  This database is public and
can be browsed and searched by anyone.  If you log in to the system, you
can enter new reports.

Bugs posted in the bugs database at <http://bugs.mysql.com/> that are
corrected for a given release are noted in the release notes.

If you find a sensitive security bug in MySQL Server, please let us know
immediately by sending an email message to <secalert_us@oracle.com>.
Exception: Support customers should report all problems, including
security bugs, to Oracle Support at <http://support.oracle.com/>.

To discuss problems with other users, you can use one of the MySQL
mailing lists.  See mailing-lists.

Writing a good bug report takes patience, but doing it right the first
time saves time both for us and for yourself.  A good bug report,
containing a full test case for the bug, makes it very likely that we
will fix the bug in the next release.  This section helps you write your
report correctly so that you do not waste your time doing things that
may not help us much or at all.  Please read this section carefully and
make sure that all the information described here is included in your
report.

Preferably, you should test the problem using the latest production or
development version of MySQL Server before posting.  Anyone should be
able to repeat the bug by just using 'mysql test < script_file' on your
test case or by running the shell or Perl script that you include in the
bug report.  Any bug that we are able to repeat has a high chance of
being fixed in the next MySQL release.

It is most helpful when a good description of the problem is included in
the bug report.  That is, give a good example of everything you did that
led to the problem and describe, in exact detail, the problem itself.
The best reports are those that include a full example showing how to
reproduce the bug or problem.  See porting.

Remember that it is possible for us to respond to a report containing
too much information, but not to one containing too little.  People
often omit facts because they think they know the cause of a problem and
assume that some details do not matter.  A good principle to follow is
that if you are in doubt about stating something, state it.  It is
faster and less troublesome to write a couple more lines in your report
than to wait longer for the answer if we must ask you to provide
information that was missing from the initial report.

The most common errors made in bug reports are (a) not including the
version number of the MySQL distribution that you use, and (b) not fully
describing the platform on which the MySQL server is installed
(including the platform type and version number).  These are highly
relevant pieces of information, and in 99 cases out of 100, the bug
report is useless without them.  Very often we get questions like, 'Why
doesn't this work for me?' Then we find that the feature requested
wasn't implemented in that MySQL version, or that a bug described in a
report has been fixed in newer MySQL versions.  Errors often are
platform-dependent.  In such cases, it is next to impossible for us to
fix anything without knowing the operating system and the version number
of the platform.

If you compiled MySQL from source, remember also to provide information
about your compiler if it is related to the problem.  Often people find
bugs in compilers and think the problem is MySQL-related.  Most
compilers are under development all the time and become better version
by version.  To determine whether your problem depends on your compiler,
we need to know what compiler you used.  Note that every compiling
problem should be regarded as a bug and reported accordingly.

If a program produces an error message, it is very important to include
the message in your report.  If we try to search for something from the
archives, it is better that the error message reported exactly matches
the one that the program produces.  (Even the lettercase should be
observed.)  It is best to copy and paste the entire error message into
your report.  You should never try to reproduce the message from memory.

If you have a problem with Connector/ODBC (MyODBC), please try to
generate a trace file and send it with your report.  See How to Report
Connector/ODBC Problems or Bugs
(http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-support-bug-report.html).

If your report includes long query output lines from test cases that you
run with the 'mysql' command-line tool, you can make the
output more readable by using the '--vertical' option or the '\G'
statement terminator.  The 'EXPLAIN SELECT' example
later in this section demonstrates the use of '\G'.

Please include the following information in your report:

   * The version number of the MySQL distribution you are using (for
     example, MySQL 5.7.10).  You can find out which version you are
     running by executing 'mysqladmin version'.  The
     'mysqladmin' program can be found in the 'bin'
     directory under your MySQL installation directory.

   * The manufacturer and model of the machine on which you experience
     the problem.

   * The operating system name and version.  If you work with Windows,
     you can usually get the name and version number by double-clicking
     your My Computer icon and pulling down the 'Help/About Windows'
     menu.  For most Unix-like operating systems, you can get this
     information by executing the command 'uname -a'.

   * Sometimes the amount of memory (real and virtual) is relevant.  If
     in doubt, include these values.

   * The contents of the 'docs/INFO_BIN' file from your MySQL
     installation.  This file contains information about how MySQL was
     configured and compiled.

   * If you are using a source distribution of the MySQL software,
     include the name and version number of the compiler that you used.
     If you have a binary distribution, include the distribution name.

   * If the problem occurs during compilation, include the exact error
     messages and also a few lines of context around the offending code
     in the file where the error occurs.

   * If 'mysqld' died, you should also report the
     statement that crashed 'mysqld'.  You can usually get
     this information by running 'mysqld' with query
     logging enabled, and then looking in the log after 'mysqld'
     crashes.  See porting.

   * If a database table is related to the problem, include the output
     from the 'SHOW CREATE TABLE DB_NAME.TBL_NAME' statement in the bug
     report.  This is a very easy way to get the definition of any table
     in a database.  The information helps us create a situation
     matching the one that you have experienced.

   * The SQL mode in effect when the problem occurred can be
     significant, so please report the value of the 'sql_mode' system
     variable.  For stored procedure, stored function, and trigger
     objects, the relevant 'sql_mode' value is the one in effect when
     the object was created.  For a stored procedure or function, the
     'SHOW CREATE PROCEDURE' or
     'SHOW CREATE FUNCTION' statement shows the
     relevant SQL mode, or you can query 'INFORMATION_SCHEMA' for the
     information:

          SELECT ROUTINE_SCHEMA, ROUTINE_NAME, SQL_MODE
          FROM INFORMATION_SCHEMA.ROUTINES;

     For triggers, you can use this statement:

          SELECT EVENT_OBJECT_SCHEMA, EVENT_OBJECT_TABLE, TRIGGER_NAME, SQL_MODE
          FROM INFORMATION_SCHEMA.TRIGGERS;

   * For performance-related bugs or problems with 'SELECT'
     statements, you should always include the output of
     'EXPLAIN SELECT ...', and at least the number of rows that the
     'SELECT' statement produces.  You should also
     include the output from 'SHOW CREATE TABLE TBL_NAME' for each table
     that is involved.  The more information you provide about your
     situation, the more likely it is that someone can help you.

     The following is an example of a very good bug report.  The
     statements are run using the 'mysql' command-line
     tool.  Note the use of the '\G' statement terminator for statements
     that would otherwise provide very long output lines that are
     difficult to read.

          mysql> SHOW VARIABLES;
          mysql> SHOW COLUMNS FROM ...\G
                 <OUTPUT FROM SHOW COLUMNS>
          mysql> EXPLAIN SELECT ...\G
                 <OUTPUT FROM EXPLAIN>
          mysql> FLUSH STATUS;
          mysql> SELECT ...;
                 <A SHORT VERSION OF THE OUTPUT FROM SELECT,
                 INCLUDING THE TIME TAKEN TO RUN THE QUERY>
          mysql> SHOW STATUS;
                 <OUTPUT FROM SHOW STATUS>

   * If a bug or problem occurs while running 'mysqld',
     try to provide an input script that reproduces the anomaly.  This
     script should include any necessary source files.  The more closely
     the script can reproduce your situation, the better.  If you can
     make a reproducible test case, you should upload it to be attached
     to the bug report.

     If you cannot provide a script, you should at least include the
     output from 'mysqladmin variables extended-status processlist'
     in your report to provide some
     information on how your system is performing.

   * If you cannot produce a test case with only a few rows, or if the
     test table is too big to be included in the bug report (more than
     10 rows), you should dump your tables using 'mysqldump'
     and create a 'README' file that describes your problem.
     Create a compressed archive of your files using 'tar' and 'gzip' or
     'zip'.  After you initiate a bug report for our bugs database at
     <http://bugs.mysql.com/>, click the Files tab in the bug report for
     instructions on uploading the archive to the bugs database.

   * If you believe that the MySQL server produces a strange result from
     a statement, include not only the result, but also your opinion of
     what the result should be, and an explanation describing the basis
     for your opinion.

   * When you provide an example of the problem, it is better to use the
     table names, variable names, and so forth that exist in your actual
     situation than to come up with new names.  The problem could be
     related to the name of a table or variable.  These cases are rare,
     perhaps, but it is better to be safe than sorry.  After all, it
     should be easier for you to provide an example that uses your
     actual situation, and it is by all means better for us.  If you
     have data that you do not want to be visible to others in the bug
     report, you can upload it using the Files tab as previously
     described.  If the information is really top secret and you do not
     want to show it even to us, go ahead and provide an example using
     other names, but please regard this as the last choice.

   * Include all the options given to the relevant programs, if
     possible.  For example, indicate the options that you use when you
     start the 'mysqld' server, as well as the options
     that you use to run any MySQL client programs.  The options to
     programs such as 'mysqld' and 'mysql',
     and to the 'configure' script, are often key to resolving problems
     and are very relevant.  It is never a bad idea to include them.  If
     your problem involves a program written in a language such as Perl
     or PHP, please include the language processor's version number, as
     well as the version for any modules that the program uses.  For
     example, if you have a Perl script that uses the 'DBI' and
     'DBD::mysql' modules, include the version numbers for Perl, 'DBI',
     and 'DBD::mysql'.

   * If your question is related to the privilege system, please include
     the output of 'mysqladmin reload', and all the
     error messages you get when trying to connect.  When you test your
     privileges, you should execute 'mysqladmin reload version'
     and try to connect with the program that gives you
     trouble.

   * If you have a patch for a bug, do include it.  But do not assume
     that the patch is all we need, or that we can use it, if you do not
     provide some necessary information such as test cases showing the
     bug that your patch fixes.  We might find problems with your patch
     or we might not understand it at all.  If so, we cannot use it.

     If we cannot verify the exact purpose of the patch, we will not use
     it.  Test cases help us here.  Show that the patch handles all the
     situations that may occur.  If we find a borderline case (even a
     rare one) where the patch will not work, it may be useless.

   * Guesses about what the bug is, why it occurs, or what it depends on
     are usually wrong.  Even the MySQL team cannot guess such things
     without first using a debugger to determine the real cause of a
     bug.

   * Indicate in your bug report that you have checked the reference
     manual and mail archive so that others know you have tried to solve
     the problem yourself.

   * If your data appears corrupt or you get errors when you access a
     particular table, first check your tables with 'CHECK TABLE'.
     If that statement reports any errors:

        * The 'InnoDB' crash recovery mechanism handles cleanup when the
          server is restarted after being killed, so in typical
          operation there is no need to 'repair' tables.  If you
          encounter an error with 'InnoDB' tables, restart the server
          and see whether the problem persists, or whether the error
          affected only cached data in memory.  If data is corrupted on
          disk, consider restarting with the 'innodb_force_recovery'
          option enabled so that you can dump the affected tables.

        * For non-transactional tables, try to repair them with
          'REPAIR TABLE' or with 'myisamchk'.
          See server-administration.

     If you are running Windows, please verify the value of
     'lower_case_table_names' using the 'SHOW VARIABLES LIKE
     'lower_case_table_names'' statement.  This variable affects how the
     server handles lettercase of database and table names.  Its effect
     for a given value should be as described in
     identifier-case-sensitivity.

   * If you often get corrupted tables, you should try to find out when
     and why this happens.  In this case, the error log in the MySQL
     data directory may contain some information about what happened.
     (This is the file with the '.err' suffix in the name.)  See
     error-log.  Please include any relevant information from this
     file in your bug report.  Normally 'mysqld' should
     _never_ crash a table if nothing killed it in the middle of an
     update.  If you can find the cause of 'mysqld'.
     dying, it is much easier for us to provide you with a fix for the
     problem.  See what-is-crashing.

   * If possible, download and install the most recent version of MySQL
     Server and check whether it solves your problem.  All versions of
     the MySQL software are thoroughly tested and should work without
     problems.  We believe in making everything as backward-compatible
     as possible, and you should be able to switch MySQL versions
     without difficulty.  See which-version.

1.8 MySQL Standards Compliance
==============================

This section describes how MySQL relates to the ANSI/ISO SQL standards.
MySQL Server has many extensions to the SQL standard, and here you can
find out what they are and how to use them.  You can also find
information about functionality missing from MySQL Server, and how to
work around some of the differences.

The SQL standard has been evolving since 1986 and several versions
exist.  In this manual, 'SQL-92' refers to the standard released in
1992, 'SQL:1999' refers to the standard released in 1999, 'SQL:2003'
refers to the standard released in 2003, and 'SQL:2008' refers to the
most recent version of the standard, released in 2008.  We use the
phrase 'the SQL standard' or 'standard SQL' to mean the current version
of the SQL Standard at any time.

One of our main goals with the product is to continue to work toward
compliance with the SQL standard, but without sacrificing speed or
reliability.  We are not afraid to add extensions to SQL or support for
non-SQL features if this greatly increases the usability of MySQL Server
for a large segment of our user base.  The 'HANDLER'.
interface is an example of this strategy.  See handler.

We continue to support transactional and nontransactional databases to
satisfy both mission-critical 24/7 usage and heavy Web or logging usage.

MySQL Server was originally designed to work with medium-sized databases
(10-100 million rows, or about 100MB per table) on small computer
systems.  Today MySQL Server handles terabyte-sized databases, but the
code can also be compiled in a reduced version suitable for hand-held
and embedded devices.  The compact design of the MySQL server makes
development in both directions possible without any conflicts in the
source tree.

We are not targeting real-time support, although MySQL replication
capabilities offer significant functionality.

MySQL supports ODBC levels 0 to 3.51.

MySQL supports high-availability database clustering using the
'NDBCLUSTER' storage engine.  See mysql-cluster.

We implement XML functionality which supports most of the W3C XPath
standard.  See xml-functions.

MySQL (5.7.8 and later) supports a native JSON data type as defined by
RFC 7159, and based on the ECMAScript standard (ECMA-262).  See
json.  MySQL also implements a subset of the SQL/JSON functions
specified by a pre-publication draft of the SQL:2016 standard; see
json-functions, for more information.

*Selecting SQL Modes*

The MySQL server can operate in different SQL modes, and can apply these
modes differently for different clients, depending on the value of the
'sql_mode' system variable.  DBAs can set the global SQL mode to match
site server operating requirements, and each application can set its
session SQL mode to its own requirements.

Modes affect the SQL syntax MySQL supports and the data validation
checks it performs.  This makes it easier to use MySQL in different
environments and to use MySQL together with other database servers.

For more information on setting the SQL mode, see sql-mode.

*Running MySQL in ANSI Mode*

To run MySQL Server in ANSI mode, start 'mysqld' with the
'--ansi' option.  Running the server in ANSI mode is the same as
starting it with the following options:

     --transaction-isolation=SERIALIZABLE --sql-mode=ANSI

To achieve the same effect at runtime, execute these two statements:

     SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE;
     SET GLOBAL sql_mode = 'ANSI';

You can see that setting the 'sql_mode' system variable to ''ANSI''
enables all SQL mode options that are relevant for ANSI mode as follows:

     mysql> SET GLOBAL sql_mode='ANSI';
     mysql> SELECT @@global.sql_mode;
             -> 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ANSI'

Running the server in ANSI mode with '--ansi' is not quite the same as
setting the SQL mode to ''ANSI'' because the '--ansi' option also sets
the transaction isolation level.

See server-options.

1.8.1 MySQL Extensions to Standard SQL
--------------------------------------

MySQL Server supports some extensions that you probably will not find in
other SQL DBMSs.  Be warned that if you use them, your code will not be
portable to other SQL servers.  In some cases, you can write code that
includes MySQL extensions, but is still portable, by using comments of
the following form:

     /*! MYSQL-SPECIFIC CODE */

In this case, MySQL Server parses and executes the code within the
comment as it would any other SQL statement, but other SQL servers will
ignore the extensions.  For example, MySQL Server recognizes the
'STRAIGHT_JOIN' keyword in the following statement, but other servers
will not:

     SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...

If you add a version number after the '!' character, the syntax within
the comment is executed only if the MySQL version is greater than or
equal to the specified version number.  The 'KEY_BLOCK_SIZE' clause in
the following comment is executed only by servers from MySQL 5.1.10 or
higher:

     CREATE TABLE t1(a INT, KEY (a)) /*!50110 KEY_BLOCK_SIZE=1024 */;

The following descriptions list MySQL extensions, organized by category.

   * Organization of data on disk

     MySQL Server maps each database to a directory under the MySQL data
     directory, and maps tables within a database to file names in the
     database directory.  This has a few implications:

        *
          Database and table names are case-sensitive in MySQL Server on
          operating systems that have case-sensitive file names (such as
          most Unix systems).  See identifier-case-sensitivity.

        * You can use standard system commands to back up, rename, move,
          delete, and copy tables that are managed by the 'MyISAM'
          storage engine.  For example, it is possible to rename a
          'MyISAM' table by renaming the '.MYD', '.MYI', and '.frm'
          files to which the table corresponds.  (Nevertheless, it is
          preferable to use 'RENAME TABLE' or
          'ALTER TABLE ... RENAME' and let the server rename the files.)

   * General language syntax

        * By default, strings can be enclosed by '"' as well as '''.  If
          the 'ANSI_QUOTES' SQL mode is enabled, strings can be enclosed
          only by ''' and the server interprets strings enclosed by '"'
          as identifiers.

        * '\' is the escape character in strings.

        * In SQL statements, you can access tables from different
          databases with the DB_NAME.TBL_NAME syntax.  Some SQL servers
          provide the same functionality but call this 'User space'.
          MySQL Server doesn't support tablespaces such as used in
          statements like this: 'CREATE TABLE ralph.my_table ... IN
          my_tablespace'.

   * SQL statement syntax

        * The 'ANALYZE TABLE', 'CHECK TABLE',
          see 'OPTIMIZE TABLE', and
          'REPAIR TABLE' statements.

        * The 'CREATE DATABASE', 'DROP DATABASE',
          and 'ALTER DATABASE'
          statements.  See create-database,
          drop-database, and alter-database.

        * The 'DO' statement.

        * 'EXPLAIN SELECT' to obtain a description of
          how tables are processed by the query optimizer.

        * The 'FLUSH' and 'RESET'.
          statements.

        * The 'SET' statement.  See
          set-variable.

        * The 'SHOW' statement.  See show.  The
          information produced by many of the MySQL-specific
          'SHOW' statements can be obtained in more standard
          fashion by using 'SELECT' to query
          'INFORMATION_SCHEMA'.  See information-schema.

        *
          Use of 'LOAD DATA INFILE'.  In many cases,
          this syntax is compatible with Oracle's 'LOAD DATA INFILE'.
          See load-data.

        * Use of 'RENAME TABLE'.  See
          rename-table.

        * Use of 'REPLACE' instead of 'DELETE'
          plus 'INSERT'.  See replace.

        * Use of 'CHANGE COL_NAME', 'DROP COL_NAME', or 'DROP INDEX',
          'IGNORE' or 'RENAME' in 'ALTER TABLE'
          statements.  Use of multiple 'ADD',
          'ALTER', 'DROP', or 'CHANGE' clauses in an 'ALTER TABLE'
          statement.  See alter-table.

        * Use of index names, indexes on a prefix of a column, and use
          of 'INDEX' or 'KEY' in 'CREATE TABLE'.
          statements.  See create-table.

        * Use of 'TEMPORARY' or 'IF NOT EXISTS' with 'CREATE TABLE'.

        * Use of 'IF EXISTS' with 'DROP TABLE' and
          'DROP DATABASE'.

        * The capability of dropping multiple tables with a single
          'DROP TABLE' statement.

        * The 'ORDER BY' and 'LIMIT' clauses of the 'UPDATE'
          and 'DELETE' statements.

        * 'INSERT INTO TBL_NAME SET COL_NAME = ...' syntax.

        * The 'DELAYED' clause of the 'INSERT' and
          'REPLACE' statements.

        * The 'LOW_PRIORITY' clause of the 'INSERT',
          'REPLACE', 'DELETE', and
          'UPDATE' statements.

        * Use of 'INTO OUTFILE' or 'INTO DUMPFILE' in 'SELECT'
          statements.  See select.

        * Options such as 'STRAIGHT_JOIN' or 'SQL_SMALL_RESULT' in
          'SELECT' statements.

        * You don't need to name all selected columns in the 'GROUP BY'
          clause.  This gives better performance for some very specific,
          but quite normal queries.  See
          group-by-functions-and-modifiers.

        * You can specify 'ASC' and 'DESC' with 'GROUP BY', not just
          with 'ORDER BY'.

        * The ability to set variables in a statement with the ':='
          assignment operator.  See user-variables.

   * Data types

        * The 'MEDIUMINT', 'SET', and
          'ENUM' data types, and the various 'BLOB'
          and 'TEXT' data types.

        * The 'AUTO_INCREMENT', 'BINARY', 'NULL', 'UNSIGNED', and
          'ZEROFILL' data type attributes.

   * Functions and operators

        * To make it easier for users who migrate from other SQL
          environments, MySQL Server supports aliases for many
          functions.  For example, all string functions support both
          standard SQL syntax and ODBC syntax.

        * MySQL Server understands the '||' and '&&' operators to mean
          logical OR and AND, as in the C programming language.  In
          MySQL Server, '||' and 'OR' are synonyms, as are '&&' and
          'AND'.  Because of this nice syntax, MySQL Server doesn't
          support the standard SQL '||' operator for string
          concatenation; use 'CONCAT()' instead.  Because 'CONCAT()'
          takes any number of arguments, it is easy to convert use of
          the '||' operator to MySQL Server.

        * Use of 'COUNT(DISTINCT VALUE_LIST)' where VALUE_LIST has more
          than one element.

        * String comparisons are case insensitive by default, with sort
          ordering determined by the collation of the current character
          set, which is 'latin1' (cp1252 West European) by default.  To
          perform case-sensitive comparisons instead, you should declare
          your columns with the 'BINARY' attribute or use the 'BINARY'
          cast, which causes comparisons to be done using the underlying
          character code values rather than a lexical ordering.

        *
          The '%' operator is a synonym for 'MOD()'.  That is, 'N % M'
          is equivalent to 'MOD(N,M)'.  '%' is supported for C
          programmers and for compatibility with PostgreSQL.

        * The '=', '<>', '<=', '<', '>=', '>', '<<', '>>', '<=>', 'AND',
          'OR', or 'LIKE' operators may be used in expressions in the
          output column list (to the left of the 'FROM') in
          'SELECT' statements.  For example:

               mysql> SELECT col1=1 AND col2=2 FROM my_table;

        * The 'LAST_INSERT_ID()' function returns the most recent
          'AUTO_INCREMENT' value.  See information-functions.

        * 'LIKE' is permitted on numeric values.

        * The 'REGEXP' and 'NOT REGEXP' extended regular expression
          operators.

        * 'CONCAT()' or 'CHAR()' with one argument or more than two
          arguments.  (In MySQL Server, these functions can take a
          variable number of arguments.)

        * The 'BIT_COUNT()', 'CASE', 'ELT()', 'FROM_DAYS()', 'FORMAT()',
          'IF()', 'PASSWORD()', 'ENCRYPT()', 'MD5()', 'ENCODE()',
          'DECODE()', 'PERIOD_ADD()', 'PERIOD_DIFF()', 'TO_DAYS()', and
          'WEEKDAY()' functions.

        * Use of 'TRIM()' to trim substrings.  Standard SQL supports
          removal of single characters only.

        * The 'GROUP BY' functions 'STD()', 'BIT_OR()', 'BIT_AND()',
          'BIT_XOR()', and 'GROUP_CONCAT()'.  See
          group-by-functions-and-modifiers.

1.8.2 MySQL Differences from Standard SQL
-----------------------------------------

We try to make MySQL Server follow the ANSI SQL standard and the ODBC
SQL standard, but MySQL Server performs operations differently in some
cases:

   * There are several differences between the MySQL and standard SQL
     privilege systems.  For example, in MySQL, privileges for a table
     are not automatically revoked when you delete a table.  You must
     explicitly issue a 'REVOKE' statement to revoke
     privileges for a table.  For more information, see revoke.

   * The 'CAST()' function does not support cast to 'REAL'
     or 'BIGINT'.  See
     cast-functions.

1.8.2.1 SELECT INTO TABLE Differences
.....................................

MySQL Server doesn't support the 'SELECT ... INTO TABLE' Sybase SQL
extension.  Instead, MySQL Server supports the 'INSERT INTO ... SELECT'
standard SQL syntax, which is basically the same
thing.  See insert-select.  For example:

     INSERT INTO tbl_temp2 (fld_id)
         SELECT tbl_temp1.fld_order_id
         FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;

Alternatively, you can use 'SELECT ... INTO OUTFILE'.
or 'CREATE TABLE ... SELECT'.

You can use 'SELECT ... INTO' with user-defined
variables.  The same syntax can also be used inside stored routines
using cursors and local variables.  See select-into.

1.8.2.2 UPDATE Differences
..........................

If you access a column from the table to be updated in an expression,
see 'UPDATE' uses the current value of the column.  The
second assignment in the following statement sets 'col2' to the current
(updated) 'col1' value, not the original 'col1' value.  The result is
that 'col1' and 'col2' have the same value.  This behavior differs from
standard SQL.

     UPDATE t1 SET col1 = col1 + 1, col2 = col1;

1.8.2.3 Foreign Key Differences
...............................

The MySQL implementation of foreign keys differs from the SQL standard
in the following key respects:

   * If there are several rows in the parent table that have the same
     referenced key value, see 'InnoDB' acts
     in foreign key checks as if the other parent rows with the same key
     value do not exist.  For example, if you have defined a 'RESTRICT'
     type constraint, and there is a child row with several parent rows,
     'InnoDB' does not permit the deletion of any of those parent rows.

     'InnoDB' performs cascading operations through a depth-first
     algorithm, based on records in the indexes corresponding to the
     foreign key constraints.

   * A 'FOREIGN KEY' constraint that references a non-'UNIQUE' key is
     not standard SQL but rather an 'InnoDB'
     extension.

   * If 'ON UPDATE CASCADE' or 'ON UPDATE SET NULL' recurses to update
     the _same table_ it has previously updated during the same cascade,
     it acts like 'RESTRICT'.  This means that you cannot use
     self-referential 'ON UPDATE CASCADE' or 'ON UPDATE SET NULL'
     operations.  This is to prevent infinite loops resulting from
     cascaded updates.  A self-referential 'ON DELETE SET NULL', on the
     other hand, is possible, as is a self-referential 'ON DELETE
     CASCADE'.  Cascading operations may not be nested more than 15
     levels deep.

   * In an SQL statement that inserts, deletes, or updates many rows,
     foreign key constraints (like unique constraints) are checked
     row-by-row.  When performing foreign key checks, see 'InnoDB'
     sets shared row-level locks on child or
     parent records that it must examine.  MySQL checks foreign key
     constraints immediately; the check is not deferred to transaction
     commit.  According to the SQL standard, the default behavior should
     be deferred checking.  That is, constraints are only checked after
     the _entire SQL statement_ has been processed.  This means that it
     is not possible to delete a row that refers to itself using a
     foreign key.

For information about how the 'InnoDB'.
storage engine handles foreign keys, see
innodb-foreign-key-constraints.

1.8.2.4 '-' as the Start of a Comment
.....................................

Standard SQL uses the C syntax '/* this is a comment */' for comments,
and MySQL Server supports this syntax as well.  MySQL also support
extensions to this syntax that enable MySQL-specific SQL to be embedded
in the comment, as described in comments.

Standard SQL uses ''--'' as a start-comment sequence.  MySQL Server uses
'#' as the start comment character.  MySQL Server also supports a
variant of the '--' comment style.  That is, the '--' start-comment
sequence must be followed by a space (or by a control character such as
a newline).  The space is required to prevent problems with
automatically generated SQL queries that use constructs such as the
following, where we automatically insert the value of the payment for
'payment':

     UPDATE account SET credit=credit-payment

Consider about what happens if 'payment' has a negative value such as
'-1':

     UPDATE account SET credit=credit--1

'credit--1' is a valid expression in SQL, but '--' is interpreted as the
start of a comment, part of the expression is discarded.  The result is
a statement that has a completely different meaning than intended:

     UPDATE account SET credit=credit

The statement produces no change in value at all.  This illustrates that
permitting comments to start with '--' can have serious consequences.

Using our implementation requires a space following the '--' for it to
be recognized as a start-comment sequence in MySQL Server.  Therefore,
'credit--1' is safe to use.

Another safe feature is that the 'mysql' command-line
client ignores lines that start with '--'.

1.8.3 How MySQL Deals with Constraints
--------------------------------------

MySQL enables you to work both with transactional tables that permit
rollback and with nontransactional tables that do not.  Because of this,
constraint handling is a bit different in MySQL than in other DBMSs.  We
must handle the case when you have inserted or updated a lot of rows in
a nontransactional table for which changes cannot be rolled back when an
error occurs.

The basic philosophy is that MySQL Server tries to produce an error for
anything that it can detect while parsing a statement to be executed,
and tries to recover from any errors that occur while executing the
statement.  We do this in most cases, but not yet for all.

The options MySQL has when an error occurs are to stop the statement in
the middle or to recover as well as possible from the problem and
continue.  By default, the server follows the latter course.  This
means, for example, that the server may coerce invalid values to the
closest valid values.

Several SQL mode options are available to provide greater control over
handling of bad data values and whether to continue statement execution
or abort when errors occur.  Using these options, you can configure
MySQL Server to act in a more traditional fashion that is like other
DBMSs that reject improper input.  The SQL mode can be set globally at
server startup to affect all clients.  Individual clients can set the
SQL mode at runtime, which enables each client to select the behavior
most appropriate for its requirements.  See sql-mode.

The following sections describe how MySQL Server handles different types
of constraints.

1.8.3.1 PRIMARY KEY and UNIQUE Index Constraints
................................................

Normally, errors occur for data-change statements (such as
'INSERT' or 'UPDATE') that would violate
primary-key, unique-key, or foreign-key constraints.  If you are using a
transactional storage engine such as 'InnoDB', MySQL automatically rolls
back the statement.  If you are using a nontransactional storage engine,
MySQL stops processing the statement at the row for which the error
occurred and leaves any remaining rows unprocessed.

MySQL supports an 'IGNORE' keyword for 'INSERT',
'UPDATE', and so forth.  If you use it, MySQL ignores
primary-key or unique-key violations and continues processing with the
next row.  See the section for the statement that you are using (see
insert, update, and so forth).

You can get information about the number of rows actually inserted or
updated with the 'mysql_info()'. C API function.  You
can also use the 'SHOW WARNINGS' statement.  See
mysql-info, and show-warnings.

'InnoDB' and 'NDB' tables support foreign keys.  See
constraint-foreign-key.

1.8.3.2 FOREIGN KEY Constraints
...............................

Foreign keys let you cross-reference related data across tables, and
foreign key constraints help keep this spread-out data consistent.

MySQL supports 'ON UPDATE' and 'ON DELETE' foreign key references in
'CREATE TABLE' and 'ALTER TABLE'
statements.  The available referential actions are
'RESTRICT' (the default), 'CASCADE', 'SET NULL', and 'NO ACTION'.

'SET DEFAULT' is also supported by the MySQL Server but is currently
rejected as invalid by 'InnoDB'.  Since
MySQL does not support deferred constraint checking, 'NO ACTION' is
treated as 'RESTRICT'.  For the exact syntax supported by MySQL for
foreign keys, see create-table-foreign-keys.

'MATCH FULL', 'MATCH PARTIAL', and 'MATCH SIMPLE' are allowed, but their
use should be avoided, as they cause the MySQL Server to ignore any 'ON
DELETE' or 'ON UPDATE' clause used in the same statement.  'MATCH'
options do not have any other effect in MySQL, which in effect enforces
'MATCH SIMPLE' semantics full-time.

MySQL requires that foreign key columns be indexed; if you create a
table with a foreign key constraint but no index on a given column, an
index is created.

You can obtain information about foreign keys from the
'INFORMATION_SCHEMA.KEY_COLUMN_USAGE' table.
An example of a query against this table is shown here:

     mysql> SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, CONSTRAINT_NAME
          > FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
          > WHERE REFERENCED_TABLE_SCHEMA IS NOT NULL;
     +--------------+---------------+-------------+-----------------+
     | TABLE_SCHEMA | TABLE_NAME    | COLUMN_NAME | CONSTRAINT_NAME |
     +--------------+---------------+-------------+-----------------+
     | fk1          | myuser        | myuser_id   | f               |
     | fk1          | product_order | customer_id | f2              |
     | fk1          | product_order | product_id  | f1              |
     +--------------+---------------+-------------+-----------------+
     3 rows in set (0.01 sec)

Information about foreign keys on 'InnoDB' tables can also be found in
the 'INNODB_SYS_FOREIGN' and
'INNODB_SYS_FOREIGN_COLS' tables, in the
'INFORMATION_SCHEMA' database.

'InnoDB' and 'NDB' tables support foreign keys.  See
innodb-foreign-key-constraints, for information specific to foreign
key support in 'InnoDB'.

1.8.3.3 Constraints on Invalid Data
...................................

By default, MySQL is forgiving of invalid or improper data values and
coerces them to valid values for data entry.  However, you can enable
strict SQL mode to select more traditional treatment of bad values such
that the server rejects them and aborts the statement in which they
occur.  See sql-mode.

This section describes the default (forgiving) behavior of MySQL, as
well as the strict SQL mode and how it differs.

If you are not using strict mode, then whenever you insert an
'incorrect' value into a column, such as a 'NULL' into a 'NOT NULL'
column or a too-large numeric value into a numeric column, MySQL sets
the column to the 'best possible value' instead of producing an error:
The following rules describe in more detail how this works:

   * If you try to store an out of range value into a numeric column,
     MySQL Server instead stores zero, the smallest possible value, or
     the largest possible value, whichever is closest to the invalid
     value.

   * For strings, MySQL stores either the empty string or as much of the
     string as can be stored in the column.

   * If you try to store a string that does not start with a number into
     a numeric column, MySQL Server stores 0.

   * Invalid values for 'ENUM' and 'SET'.
     columns are handled as described in constraint-enum.

   * MySQL permits you to store certain incorrect date values into
     'DATE' and 'DATETIME' columns (such as
     ''2000-02-31'' or ''2000-02-00'').  In this case, when an
     application has not enabled strict SQL mode, it up to the
     application to validate the dates before storing them.  If MySQL
     can store a date value and retrieve exactly the same value, MySQL
     stores it as given.  If the date is totally wrong (outside the
     server's ability to store it), the special 'zero' date value
     ''0000-00-00'' is stored in the column instead.

   * If you try to store 'NULL' into a column that doesn't take 'NULL'
     values, an error occurs for single-row 'INSERT'.
     statements.  For multiple-row 'INSERT' statements or
     for 'INSERT INTO ... SELECT' statements,
     MySQL Server stores the implicit default value for the column data
     type.  In general, this is '0' for numeric types, the empty string
     ('''') for string types, and the 'zero' value for date and time
     types.  Implicit default values are discussed in
     data-type-defaults.

   * If an 'INSERT' statement specifies no value for a
     column, MySQL inserts its default value if the column definition
     includes an explicit 'DEFAULT' clause.  If the definition has no
     such 'DEFAULT' clause, MySQL inserts the implicit default value for
     the column data type.

The reason for using the preceding rules in nonstrict mode is that we
can't check these conditions until the statement has begun executing.
We can't just roll back if we encounter a problem after updating a few
rows, because the storage engine may not support rollback.  The option
of terminating the statement is not that good; in this case, the update
would be 'half done,' which is probably the worst possible scenario.  In
this case, it is better to 'do the best you can' and then continue as if
nothing happened.

You can select stricter treatment of input values by using the
'STRICT_TRANS_TABLES' or 'STRICT_ALL_TABLES' SQL modes:

     SET sql_mode = 'STRICT_TRANS_TABLES';
     SET sql_mode = 'STRICT_ALL_TABLES';

'STRICT_TRANS_TABLES' enables strict mode for transactional storage
engines, and also to some extent for nontransactional engines.  It works
like this:

   * For transactional storage engines, bad data values occurring
     anywhere in a statement cause the statement to abort and roll back.

   * For nontransactional storage engines, a statement aborts if the
     error occurs in the first row to be inserted or updated.  (When the
     error occurs in the first row, the statement can be aborted to
     leave the table unchanged, just as for a transactional table.)
     Errors in rows after the first do not abort the statement, because
     the table has already been changed by the first row.  Instead, bad
     data values are adjusted and result in warnings rather than errors.
     In other words, with 'STRICT_TRANS_TABLES', a wrong value causes
     MySQL to roll back all updates done so far, if that can be done
     without changing the table.  But once the table has been changed,
     further errors result in adjustments and warnings.

For even stricter checking, enable 'STRICT_ALL_TABLES'.  This is the
same as 'STRICT_TRANS_TABLES' except that for nontransactional storage
engines, errors abort the statement even for bad data in rows following
the first row.  This means that if an error occurs partway through a
multiple-row insert or update for a nontransactional table, a partial
update results.  Earlier rows are inserted or updated, but those from
the point of the error on are not.  To avoid this for nontransactional
tables, either use single-row statements or else use
'STRICT_TRANS_TABLES' if conversion warnings rather than errors are
acceptable.  To avoid problems in the first place, do not use MySQL to
check column content.  It is safest (and often faster) to let the
application ensure that it passes only valid values to the database.

With either of the strict mode options, you can cause errors to be
treated as warnings by using 'INSERT IGNORE' or 'UPDATE
IGNORE' rather than 'INSERT' or 'UPDATE'.
without 'IGNORE'.

1.8.3.4 ENUM and SET Constraints
................................

'ENUM' and 'SET' columns provide an efficient
way to define columns that can contain only a given set of values.  See
enum, and set.

With strict mode enabled (see sql-mode), the definition of a
'ENUM' or 'SET' column acts as a constraint on
values entered into the column.  An error occurs for values that do not
satisfy these conditions:

   * An 'ENUM' value must be one of those listed in the
     column definition, or the internal numeric equivalent thereof.  The
     value cannot be the error value (that is, 0 or the empty string).
     For a column defined as 'ENUM('a','b','c')', values
     such as '''', ''d'', or ''ax'' are invalid and are rejected.

   * A 'SET' value must be the empty string or a value
     consisting only of the values listed in the column definition
     separated by commas.  For a column defined as
     'SET('a','b','c')', values such as ''d'' or ''a,b,c,d'' are
     invalid and are rejected.

Errors for invalid values can be suppressed in strict mode if you use
'INSERT IGNORE' or 'UPDATE IGNORE'.  In this case, a
warning is generated rather than an error.  For 'ENUM', the
value is inserted as the error member ('0').  For 'SET', the
value is inserted as given except that any invalid substrings are
deleted.  For example, ''a,x,b,y'' results in a value of ''a,b''.

1.9 Credits
===========

The following sections list developers, contributors, and supporters
that have helped to make MySQL what it is today.

1.9.1 Contributors to MySQL
---------------------------

Although Oracle Corporation and/or its affiliates own all copyrights in
the 'MySQL server' and the 'MySQL manual', we wish to recognize those
who have made contributions of one kind or another to the 'MySQL
distribution'.  Contributors are listed here, in somewhat random order:

   * Gianmassimo Vigazzola <qwerg@mbox.vol.it> or <qwerg@tin.it>

     The initial port to Win32/NT.

   * Per Eric Olsson

     For constructive criticism and real testing of the dynamic record
     format.

   * Irena Pancirov <irena@mail.yacc.it>

     Win32 port with Borland compiler.  'mysqlshutdown.exe' and
     'mysqlwatch.exe'.

   * David J. Hughes

     For the effort to make a shareware SQL database.  At TcX, the
     predecessor of MySQL AB, we started with 'mSQL', but found that it
     couldn't satisfy our purposes so instead we wrote an SQL interface
     to our application builder Unireg.  See 'mysqladmin'.
     and 'mysql' client are programs that were largely
     influenced by their 'mSQL' counterparts.  We have put a lot of
     effort into making the MySQL syntax a superset of 'mSQL'.  Many of
     the API's ideas are borrowed from 'mSQL' to make it easy to port
     free 'mSQL' programs to the MySQL API. The MySQL software doesn't
     contain any code from 'mSQL'.  Two files in the distribution
     ('client/insert_test.c' and 'client/select_test.c') are based on
     the corresponding (noncopyrighted) files in the 'mSQL'
     distribution, but are modified as examples showing the changes
     necessary to convert code from 'mSQL' to MySQL Server.  ('mSQL' is
     copyrighted David J. Hughes.)

   * Patrick Lynch

     For helping us acquire <http://www.mysql.com/>.

   * Fred Lindberg

     For setting up qmail to handle the MySQL mailing list and for the
     incredible help we got in managing the MySQL mailing lists.

   * Igor Romanenko <igor@frog.kiev.ua>

     See 'mysqldump'. (previously 'msqldump', but ported
     and enhanced by Monty).

   * Yuri Dario

     For keeping up and extending the MySQL OS/2 port.

   * Tim Bunce

     Author of 'mysqlhotcopy'.

   * Zarko Mocnik <zarko.mocnik@dem.si>

     Sorting for Slovenian language.

   * "TAMITO" <tommy@valley.ne.jp>

     The '_MB' character set macros and the ujis and sjis character
     sets.

   * Joshua Chamas <joshua@chamas.com>

     Base for concurrent insert, extended date syntax, debugging on NT,
     and answering on the MySQL mailing list.

   * Yves Carlier <Yves.Carlier@rug.ac.be>

     'mysqlaccess', a program to show the access rights for a user.

   * Rhys Jones <rhys@wales.com> (And GWE Technologies Limited)

     For one of the early JDBC drivers.

   * Dr Xiaokun Kelvin ZHU <X.Zhu@brad.ac.uk>

     Further development of one of the early JDBC drivers and other
     MySQL-related Java tools.

   * James Cooper <pixel@organic.com>

     For setting up a searchable mailing list archive at his site.

   * Rick Mehalick <Rick_Mehalick@i-o.com>

     For 'xmysql', a graphical X client for MySQL Server.

   * Doug Sisk <sisk@wix.com>

     For providing RPM packages of MySQL for Red Hat Linux.

   * Diemand Alexander V. <axeld@vial.ethz.ch>

     For providing RPM packages of MySQL for Red Hat Linux-Alpha.

   * Antoni Pamies Olive <toni@readysoft.es>

     For providing RPM versions of a lot of MySQL clients for Intel and
     SPARC.

   * Jay Bloodworth <jay@pathways.sde.state.sc.us>

     For providing RPM versions for MySQL 3.21.

   * David Sacerdote <davids@secnet.com>

     Ideas for secure checking of DNS host names.

   * Wei-Jou Chen <jou@nematic.ieo.nctu.edu.tw>

     Some support for Chinese(BIG5) characters.

   * Wei He <hewei@mail.ied.ac.cn>

     A lot of functionality for the Chinese(GBK) character set.

   * Jan Pazdziora <adelton@fi.muni.cz>

     Czech sorting order.

   * Zeev Suraski <bourbon@netvision.net.il>

     'FROM_UNIXTIME()' time formatting, 'ENCRYPT()' functions, and
     'bison' advisor.  Active mailing list member.

   * Luuk de Boer <luuk@wxs.nl>

     Ported (and extended) the benchmark suite to 'DBI'/'DBD'.  Have
     been of great help with 'crash-me' and running benchmarks.  Some
     new date functions.  The 'mysql_setpermission' script.

   * Alexis Mikhailov <root@medinf.chuvashia.su>

     User-defined functions (UDFs); see 'CREATE FUNCTION'
     and 'DROP FUNCTION'.

   * Andreas F. Bobak <bobak@relog.ch>

     The 'AGGREGATE' extension to user-defined functions.

   * Ross Wakelin <R.Wakelin@march.co.uk>

     Help to set up InstallShield for MySQL-Win32.

   * Jethro Wright III <jetman@li.net>

     The 'libmysql.dll' library.

   * James Pereria <jpereira@iafrica.com>

     Mysqlmanager, a Win32 GUI tool for administering MySQL Servers.

   * Curt Sampson <cjs@portal.ca>

     Porting of MIT-pthreads to NetBSD/Alpha and NetBSD 1.3/i386.

   * Martin Ramsch <m.ramsch@computer.org>

     Examples in the MySQL Tutorial.

   * Steve Harvey

     For making 'mysqlaccess' more secure.

   * Konark IA-64 Centre of Persistent Systems Private Limited

     Help with the Win64 port of the MySQL server.

   * Albert Chin-A-Young.

     Configure updates for Tru64, large file support and better TCP
     wrappers support.

   * John Birrell

     Emulation of 'pthread_mutex()' for OS/2.

   * Benjamin Pflugmann

     Extended 'MERGE' tables to handle 'INSERTS'.  Active member on the
     MySQL mailing lists.

   * Jocelyn Fournier

     Excellent spotting and reporting innumerable bugs (especially in
     the MySQL 4.1 subquery code).

   * Marc Liyanage

     Maintaining the OS X packages and providing invaluable feedback on
     how to create OS X packages.

   * Robert Rutherford

     Providing invaluable information and feedback about the QNX port.

   * Previous developers of NDB Cluster

     Lots of people were involved in various ways summer students,
     master thesis students, employees.  In total more than 100 people
     so too many to mention here.  Notable name is Ataullah Dabaghi who
     up until 1999 contributed around a third of the code base.  A
     special thanks also to developers of the AXE system which provided
     much of the architectural foundations for NDB Cluster with blocks,
     signals and crash tracing functionality.  Also credit should be
     given to those who believed in the ideas enough to allocate of
     their budgets for its development from 1992 to present time.

   * Google Inc.

     We wish to recognize Google Inc.  for contributions to the MySQL
     distribution: Mark Callaghan's SMP Performance patches and other
     patches.

Other contributors, bugfinders, and testers: James H. Thompson, Maurizio
Menghini, Wojciech Tryc, Luca Berra, Zarko Mocnik, Wim Bonis, Elmar
Haneke, <jehamby@lightside>, <psmith@BayNetworks.com>,
<duane@connect.com.au>, Ted Deppner <ted@psyber.com>, Mike Simons,
Jaakko Hyvatti.

And lots of bug report/patches from the folks on the mailing list.

A big tribute goes to those that help us answer questions on the MySQL
mailing lists:

   * Daniel Koch <dkoch@amcity.com>

     Irix setup.

   * Luuk de Boer <luuk@wxs.nl>

     Benchmark questions.

   * Tim Sailer <tps@users.buoy.com>

     'DBD::mysql' questions.

   * Boyd Lynn Gerber <gerberb@zenez.com>

     SCO-related questions.

   * Richard Mehalick <RM186061@shellus.com>

     'xmysql'-related questions and basic installation questions.

   * Zeev Suraski <bourbon@netvision.net.il>

     Apache module configuration questions (log & auth), PHP-related
     questions, SQL syntax-related questions and other general
     questions.

   * Francesc Guasch <frankie@citel.upc.es>

     General questions.

   * Jonathan J Smith <jsmith@wtp.net>

     Questions pertaining to OS-specifics with Linux, SQL syntax, and
     other things that might need some work.

   * David Sklar <sklar@student.net>

     Using MySQL from PHP and Perl.

   * Alistair MacDonald <A.MacDonald@uel.ac.uk>

     Is flexible and can handle Linux and perhaps HP-UX.

   * John Lyon <jlyon@imag.net>

     Questions about installing MySQL on Linux systems, using either
     '.rpm' files or compiling from source.

   * Lorvid Ltd.  <lorvid@WOLFENET.com>

     Simple billing/license/support/copyright issues.

   * Patrick Sherrill <patrick@coconet.com>

     ODBC and VisualC++ interface questions.

   * Randy Harmon <rjharmon@uptimecomputers.com>

     'DBD', Linux, some SQL syntax questions.

1.9.2 Documenters and translators
---------------------------------

The following people have helped us with writing the MySQL documentation
and translating the documentation or error messages in MySQL.

   * Paul DuBois

     Ongoing help with making this manual correct and understandable.
     That includes rewriting Monty's and David's attempts at English
     into English as other people know it.

   * Kim Aldale

     Helped to rewrite Monty's and David's early attempts at English
     into English.

   * Michael J. Miller Jr.  <mke@terrapin.turbolift.com>

     For the first MySQL manual.  And a lot of spelling/language fixes
     for the FAQ (that turned into the MySQL manual a long time ago).

   * Yan Cailin

     First translator of the MySQL Reference Manual into simplified
     Chinese in early 2000 on which the Big5 and HK coded versions were
     based.

   * Jay Flaherty <fty@mediapulse.com>

     Big parts of the Perl 'DBI'/'DBD' section in the manual.

   * Paul Southworth <pauls@etext.org>, Ray Loyzaga <yar@cs.su.oz.au>

     Proof-reading of the Reference Manual.

   * Therrien Gilbert <gilbert@ican.net>, Jean-Marc Pouyot
     <jmp@scalaire.fr>

     French error messages.

   * Petr Snajdr, <snajdr@pvt.net>

     Czech error messages.

   * Jaroslaw Lewandowski <jotel@itnet.com.pl>

     Polish error messages.

   * Miguel Angel Fernandez Roiz

     Spanish error messages.

   * Roy-Magne Mo <rmo@www.hivolda.no>

     Norwegian error messages and testing of MySQL 3.21.xx.

   * Timur I. Bakeyev <root@timur.tatarstan.ru>

     Russian error messages.

   * <brenno@dewinter.com> & Filippo Grassilli <phil@hyppo.com>

     Italian error messages.

   * Dirk Munzinger <dirk@trinity.saar.de>

     German error messages.

   * Billik Stefan <billik@sun.uniag.sk>

     Slovak error messages.

   * Stefan Saroiu <tzoompy@cs.washington.edu>

     Romanian error messages.

   * Peter Feher

     Hungarian error messages.

   * Roberto M. Serqueira

     Portuguese error messages.

   * Carsten H. Pedersen

     Danish error messages.

   * Arjen Lentz

     Dutch error messages, completing earlier partial translation (also
     work on consistency and spelling).

1.9.3 Packages that support MySQL
---------------------------------

The following is a list of creators/maintainers of some of the most
important API/packages/applications that a lot of people use with MySQL.

We cannot list every possible package here because the list would then
be way to hard to maintain.  For other packages, please refer to the
software portal at <http://solutions.mysql.com/software/>.

   * Tim Bunce, Alligator Descartes

     For the 'DBD' (Perl) interface.

   * Andreas Koenig <a.koenig@mind.de>

     For the Perl interface for MySQL Server.

   * Jochen Wiedmann <wiedmann@neckar-alb.de>

     For maintaining the Perl 'DBD::mysql' module.

   * Eugene Chan <eugene@acenet.com.sg>

     For porting PHP for MySQL Server.

   * Georg Richter

     MySQL 4.1 testing and bug hunting.  New PHP 5.0 'mysqli' extension
     (API) for use with MySQL 4.1 and up.

   * Giovanni Maruzzelli <maruzz@matrice.it>

     For porting iODBC (Unix ODBC).

   * Xavier Leroy <Xavier.Leroy@inria.fr>

     The author of LinuxThreads (used by the MySQL Server on Linux).

1.9.4 Tools that were used to create MySQL
------------------------------------------

The following is a list of some of the tools we have used to create
MySQL. We use this to express our thanks to those that has created them
as without these we could not have made MySQL what it is today.

   * Free Software Foundation

     From whom we got an excellent compiler ('gcc'), an excellent
     debugger ('gdb' and the 'libc' library (from which we have borrowed
     'strto.c' to get some code working in Linux).

   * Free Software Foundation & The XEmacs development team

     For a really great editor/environment.

   * Julian Seward

     Author of 'valgrind', an excellent memory checker tool that has
     helped us find a lot of otherwise hard to find bugs in MySQL.

   * Dorothea Lu"tkehaus and Andreas Zeller

     For 'DDD' (The Data Display Debugger) which is an excellent
     graphical front end to 'gdb').

1.9.5 Supporters of MySQL
-------------------------

Although Oracle Corporation and/or its affiliates own all copyrights in
the 'MySQL server' and the 'MySQL manual', we wish to recognize the
following companies, which helped us finance the development of the
'MySQL server', such as by paying us for developing a new feature or
giving us hardware for development of the 'MySQL server'.

   * VA Linux / Andover.net

     Funded replication.

   * NuSphere

     Editing of the MySQL manual.

   * Stork Design studio

     The MySQL website in use between 1998-2000.

   * Intel

     Contributed to development on Windows and Linux platforms.

   * Compaq

     Contributed to Development on Linux/Alpha.

   * SWSoft

     Development on the embedded 'mysqld' version.

   * FutureQuest

     The '--skip-show-database' option.

2 Installing and Upgrading MySQL
********************************

This chapter describes how to obtain and install MySQL. A summary of the
procedure follows and later sections provide the details.  If you plan
to upgrade an existing version of MySQL to a newer version rather than
install MySQL for the first time, see upgrading, for information
about upgrade procedures and about issues that you should consider
before upgrading.

If you are interested in migrating to MySQL from another database
system, see faqs-migration, which contains answers to some
common questions concerning migration issues.

Installation of MySQL generally follows the steps outlined here:

  1. *Determine whether MySQL runs and is supported on your platform.*

     Please note that not all platforms are equally suitable for running
     MySQL, and that not all platforms on which MySQL is known to run
     are officially supported by Oracle Corporation.  For information
     about those platforms that are officially supported, see
     <http://www.mysql.com/support/supportedplatforms/database.html> on
     the MySQL website.

  2. *Choose which distribution to install.*

     Several versions of MySQL are available, and most are available in
     several distribution formats.  You can choose from pre-packaged
     distributions containing binary (precompiled) programs or source
     code.  When in doubt, use a binary distribution.  Oracle also
     provides access to the MySQL source code for those who want to see
     recent developments and test new code.  To determine which version
     and type of distribution you should use, see which-version.

  3. *Download the distribution that you want to install.*

     For instructions, see getting-mysql.  To verify the
     integrity of the distribution, use the instructions in
     verifying-package-integrity.

  4. *Install the distribution.*

     To install MySQL from a binary distribution, use the instructions
     in binary-installation.

     To install MySQL from a source distribution or from the current
     development source tree, use the instructions in
     source-installation.

  5. *Perform any necessary postinstallation setup.*

     After installing MySQL, see postinstallation for
     information about making sure the MySQL server is working properly.
     Also refer to the information provided in
     default-privileges.  This section describes how to secure the
     initial MySQL 'root' user account, _which has no password_ until
     you assign one.  The section applies whether you install MySQL
     using a binary or source distribution.

  6. If you want to run the MySQL benchmark scripts, Perl support for
     MySQL must be available.  See perl-support.

Instructions for installing MySQL on different platforms and
environments is available on a platform by platform basis:

   * *Unix, Linux, FreeBSD*

     For instructions on installing MySQL on most Linux and Unix
     platforms using a generic binary (for example, a '.tar.gz'
     package), see binary-installation.

     For information on building MySQL entirely from the source code
     distributions or the source code repositories, see
     source-installation

     For specific platform help on installation, configuration, and
     building from source see the corresponding platform section:

        * Linux, including notes on distribution specific methods, see
          linux-installation.

        * Solaris, including PKG and IPS formats, see
          solaris-installation.

        * IBM AIX, see solaris-installation.

        * FreeBSD, see freebsd-installation.

   * *Microsoft Windows*

     For instructions on installing MySQL on Microsoft Windows, using
     either the MySQL Installer or Zipped binary, see
     windows-installation.

     For information about managing MySQL instances, see
     windows-notifier.

     For details and instructions on building MySQL from source code
     using Microsoft Visual Studio, see source-installation.

   * *OS X*

     For installation on OS X, including using both the binary package
     and native PKG formats, see osx-installation.

     For information on making use of an OS X Launch Daemon to
     automatically start and stop MySQL, see
     osx-installation-launchd.

     For information on the MySQL Preference Pane, see
     osx-installation-prefpane.

2.1 General Installation Guidance
=================================

The immediately following sections contain the information necessary to
choose, download, and verify your distribution.  The instructions in
later sections of the chapter describe how to install the distribution
that you choose.  For binary distributions, see the instructions at
binary-installation or the corresponding section for your
platform if available.  To build MySQL from source, use the instructions
in source-installation.

2.1.1 Which MySQL Version and Distribution to Install
-----------------------------------------------------

MySQL is available on a number of operating systems and platforms.  For
information about those platforms that are officially supported, see
<http://www.mysql.com/support/supportedplatforms/database.html> on the
MySQL website.

MySQL is available on many operating systems and platforms.  For
information about platforms supported by GA releases
(http://dev.mysql.com/doc/mysql-development-cycle/en/ga-releases.html)
of MySQL, see
<http://www.mysql.com/support/supportedplatforms/database.html>.  For
development versions of MySQL, builds are available for a number of
platforms at <http://dev.mysql.com/downloads/mysql/5.7.html>.  To learn
more about MySQL Support, see <http://www.mysql.com/support/>.

When preparing to install MySQL, decide which version and distribution
format (binary or source) to use.

First, decide whether to install a development release or a General
Availability (GA) release.  Development releases have the newest
features, but are not recommended for production use.  GA releases, also
called production or stable releases, are meant for production use.  We
recommend using the most recent GA release.

The naming scheme in MySQL 5.7 uses release names that consist of three
numbers and an optional suffix; for example, *mysql-5.7.1-m1*.  The
numbers within the release name are interpreted as follows:

   * The first number (*5*) is the major version number.

   * The second number (*7*) is the minor version number.  Taken
     together, the major and minor numbers constitute the release series
     number.  The series number describes the stable feature set.

   * The third number (*1*) is the version number within the release
     series.  This is incremented for each new bugfix release.  In most
     cases, the most recent version within a series is the best choice.

Release names can also include a suffix to indicate the stability level
of the release.  Releases within a series progress through a set of
suffixes to indicate how the stability level improves.  The possible
suffixes are:

   * *m_N_* (for example, *m1*, *m2*, *m3*, ...)  indicates a milestone
     number.  MySQL development uses a milestone model, in which each
     milestone introduces a small subset of thoroughly tested features.
     From one milestone to the next, feature interfaces may change or
     features may even be removed, based on feedback provided by
     community members who try these earily releases.  Features within
     milestone releases may be considered to be of pre-production
     quality.

   * *rc* indicates a Release Candidate (RC). Release candidates are
     believed to be stable, having passed all of MySQL's internal
     testing.  New features may still be introduced in RC releases, but
     the focus shifts to fixing bugs to stabilize features introduced
     earlier within the series.

   * Absence of a suffix indicates a General Availability (GA) or
     Production release.  GA releases are stable, having successfully
     passed through the earlier release stages, and are believed to be
     reliable, free of serious bugs, and suitable for use in production
     systems.

Development within a series begins with milestone releases, followed by
RC releases, and finally reaches GA status releases.

After choosing which MySQL version to install, decide which distribution
format to install for your operating system.  For most use cases, a
binary distribution is the right choice.  Binary distributions are
available in native format for many platforms, such as RPM packages for
Linux or DMG packages for OS X. Distributions are also available in more
generic formats such as Zip archives or compressed 'tar' files.  On
Windows, you can use the MySQL Installer to
install a binary distribution.

Under some circumstances, it may be preferable to install MySQL from a
source distribution:

   * You want to install MySQL at some explicit location.  The standard
     binary distributions are ready to run at any installation location,
     but you might require even more flexibility to place MySQL
     components where you want.

   * You want to configure 'mysqld' with features that
     might not be included in the standard binary distributions.  Here
     is a list of the most common extra options used to ensure feature
     availability:

        * '-DWITH_LIBWRAP=1' for TCP wrappers support.

        * '-DWITH_ZLIB={system|bundled}' for features that depend on
          compression

        * '-DWITH_DEBUG=1' for debugging support

     For additional information, see
     source-configuration-options.

   * You want to configure 'mysqld' without some features
     that are included in the standard binary distributions.  For
     example, distributions normally are compiled with support for all
     character sets.  If you want a smaller MySQL server, you can
     recompile it with support for only the character sets you need.

   * You want to read or modify the C and C++ code that makes up MySQL.
     For this purpose, obtain a source distribution.

   * Source distributions contain more tests and examples than binary
     distributions.

2.1.2 How to Get MySQL
----------------------

Check our downloads page at <http://dev.mysql.com/downloads/> for
information about the current version of MySQL and for downloading
instructions.  For a complete up-to-date list of MySQL download mirror
sites, see <http://dev.mysql.com/downloads/mirrors.html>.  You can also
find information there about becoming a MySQL mirror site and how to
report a bad or out-of-date mirror.

For RPM-based Linux platforms that use Yum as their package management
system, MySQL can be installed using the MySQL Yum Repository
(http://dev.mysql.com/downloads/repo/yum/).  See
linux-installation-yum-repo for details.

For Debian-based Linux platforms, MySQL can be installed using the MySQL
APT Repository (http://dev.mysql.com/downloads/repo/apt/).  See
linux-installation-apt-repo for details.

For SUSE Linux Enterprise Server (SLES) platforms, MySQL can be
installed using the MySQL SLES Repository
(http://dev.mysql.com/downloads/repo/suse/).  See
linux-installation-sles-repo for details.

To obtain the latest development source, see
installing-development-tree.

2.1.3 Verifying Package Integrity Using MD5 Checksums or GnuPG
--------------------------------------------------------------

After downloading the MySQL package that suits your needs and before
attempting to install it, make sure that it is intact and has not been
tampered with.  There are three means of integrity checking:

   * MD5 checksums

   * Cryptographic signatures using 'GnuPG', the GNU Privacy Guard

   * For RPM packages, the built-in RPM integrity verification mechanism

The following sections describe how to use these methods.

If you notice that the MD5 checksum or GPG signatures do not match,
first try to download the respective package one more time, perhaps from
another mirror site.

2.1.3.1 Verifying the MD5 Checksum
..................................

After you have downloaded a MySQL package, you should make sure that its
MD5 checksum matches the one provided on the MySQL download pages.  Each
package has an individual checksum that you can verify against the
package that you downloaded.  The correct MD5 checksum is listed on the
downloads page for each MySQL product, and you will compare it against
the MD5 checksum of the file (product) that you download.

Each operating system and setup offers its own version of tools for
checking the MD5 checksum.  Typically the command is named 'md5sum', or
it may be named 'md5', and some operating systems do not ship it at all.
On Linux, it is part of the *GNU Text Utilities* package, which is
available for a wide range of platforms.  You can also download the
source code from <http://www.gnu.org/software/textutils/>.  If you have
OpenSSL installed, you can use the command 'openssl md5 PACKAGE_NAME'
instead.  A Windows implementation of the 'md5' command line utility is
available from <http://www.fourmilab.ch/md5/>.  'winMd5Sum' is a
graphical MD5 checking tool that can be obtained from
<http://www.nullriver.com/index/products/winmd5sum>.  Our Microsoft
Windows examples will assume the name 'md5.exe'.

Linux and Microsoft Windows examples:

     shell> md5sum mysql-standard-5.7.23-linux-i686.tar.gz
     aaab65abbec64d5e907dcd41b8699945  mysql-standard-5.7.23-linux-i686.tar.gz

     shell> md5.exe mysql-installer-community-5.7.23.msi
     aaab65abbec64d5e907dcd41b8699945  mysql-installer-community-5.7.23.msi

You should verify that the resulting checksum (the string of hexadecimal
digits) matches the one displayed on the download page immediately below
the respective package.

*Note*:

Make sure to verify the checksum of the _archive file_ (for example, the
'.zip', '.tar.gz', or '.msi' file) and not of the files that are
contained inside of the archive.  In other words, verify the file before
extracting its contents.

2.1.3.2 Signature Checking Using GnuPG
......................................

Another method of verifying the integrity and authenticity of a package
is to use cryptographic signatures.  This is more reliable than using
MD5 checksums, but requires more work.

We sign MySQL downloadable packages with 'GnuPG' (GNU Privacy Guard).
'GnuPG' is an Open Source alternative to the well-known Pretty Good
Privacy ('PGP') by Phil Zimmermann.  Most Linux distributions ship with
'GnuPG' installed by default.  Otherwise, see <http://www.gnupg.org/>
for more information about 'GnuPG' and how to obtain and install it.

To verify the signature for a specific package, you first need to obtain
a copy of our public GPG build key, which you can download from
<http://pgp.mit.edu/>.  The key that you want to obtain is named
'mysql-build@oss.oracle.com'.  Alternatively, you can copy and paste the
key directly from the following text:

     -----BEGIN PGP PUBLIC KEY BLOCK-----
     Version: GnuPG v1.4.5 (GNU/Linux)

     mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
     RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
     fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
     BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
     hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
     K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
     kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
     QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
     rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q2TXlTUUwgUmVs
     ZWFzZSBFbmdpbmVlcmluZyA8bXlzcWwtYnVpbGRAb3NzLm9yYWNsZS5jb20+iGwE
     ExECACwCGyMCHgECF4ACGQEGCwkIBwMCBhUKCQgCAwUWAgMBAAUCWKcFIAUJHirJ
     FAAKCRCMcY07UHLh9VcFAJ46pUyVd8BZ2r5CppMC1tmyQ3ceRgCfVPwuVsiS0VER
     5WUqtAQDt+DoetCIaQQTEQIAKQIbIwYLCQgHAwIEFQIIAwQWAgMBAh4BAheAAhkB
     BQJTAdRmBQkaZsvLAAoJEIxxjTtQcuH1X4MAoKNLWAbCBUj96637kv6Xa/fJuX5m
     AJwPtmgDfjUe2iuhXdTrFEPT19SB6ohmBBMRAgAmAhsjBgsJCAcDAgQVAggDBBYC
     AwECHgECF4AFAk53PioFCRP7AhUACgkQjHGNO1By4fUmzACeJdfqgc9gWTUhgmcM
     AOmG4RjwuxcAoKfM+U8yMOGELi+TRif7MtKEms6piGkEExECACkCGyMGCwkIBwMC
     BBUCCAMEFgIDAQIeAQIXgAIZAQUCUZSROgUJFTchqgAKCRCMcY07UHLh9YtAAJ9X
     rA/ymlmozPZn+A9ls8/uwMcTsQCfaQMNq1dNkhH2kyByc3Rx9/W2xfqJARwEEAEC
     AAYFAlAS6+UACgkQ8aIC+GoXHivrWwf/dtLk/x+NC2VMDlg+vOeM0qgG1IlhXZfi
     NsEisvvGaz4m8fSFRGe+1bvvfDoKRhxiGXU48RusjixzvBb6KTMuY6JpOVfz9Dj3
     H9spYriHa+i6rYySXZIpOhfLiMnTy7NH2OvYCyNzSS/ciIUACIfH/2NH8zNT5CNF
     1uPNRs7HsHzzz7pOlTjtTWiF4cq/Ij6Z6CNrmdj+SiMvjYN9u6sdEKGtoNtpycgD
     5HGKR+I7Nd/7v56yhaUe4FpuvsNXig86K9tI6MUFS8CUyy7Hj3kVBZOUWVBM053k
     nGdALSygQr50DA3jMGKVl4ZnHje2RVWRmFTr5YWoRTMxUSQPMLpBNIkBHAQQAQIA
     BgUCU1B+vQAKCRAohbcD0zcc8dWwCACWXXWDXIcAWRUw+j3ph8dr9u3SItljn3wB
     c7clpclKWPuLvTz7lGgzlVB0s8hH4xgkSA+zLzl6u56mpUzskFl7f1I3Ac9GGpM4
     0M5vmmR9hwlD1HdZtGfbD+wkjlqgitNLoRcGdRf/+U7x09GhSS7Bf339sunIX6sM
     gXSC4L32D3zDjF5icGdb0kj+3lCrRmp853dGyA3ff9yUiBkxcKNawpi7Vz3D2ddU
     pOF3BP+8NKPg4P2+srKgkFbd4HidcISQCt3rY4vaTkEkLKg0nNA6U4r0YgOa7wIT
     SsxFlntMMzaRg53QtK0+YkH0KuZR3GY8B7pi+tlgycyVR7mIFo7riQEcBBABCAAG
     BQJWgVd0AAoJEEZu4b/gk4UKk9MH/Rnt7EccPjSJC5CrB2AU5LY2Dsr+PePI2ubP
     WsEdG82qSjjGpbhIH8LSg/PzQoGHiFWMmmZWJktRT+dcgLbs3b2VwCNAwCE8jOHd
     UkQhEowgomdNvHiBHKHjP4/lF68KOPiO/2mxYYkmpM7BWf3kB57DJ5CTi3/JLoN7
     zF40qIs/p09ePvnwStpglbbtUn7XPO+1/Ee8VHzimABom52PkQIuxNiVUzLVn3bS
     Wqrd5ecuqLk6yzjPXd2XhDHWC9Twpl68GePru6EzQtusi0m6S/sHgEXqh/IxrFZV
     JlljF75JvosZq5zeulr0i6kOij+Y1p6MFffihITZ1gTmk+CLvK2JASIEEAECAAwF
     Ak53QS4FAwASdQAACgkQlxC4m8pXrXwJ8Qf/be/UO9mqfoc2sMyhwMpN4/fdBWwf
     LkA12FXQDOQMvwH9HsmEjnfUgYKXschZRi+DuHXe1P7l8G2aQLubhBsQf9ejKvRF
     TzuWMQkdIq+6Koulxv6ofkCcv3d1xtO2W7nb5yxcpVBPrRfGFGebJvZa58DymCNg
     yGtAU6AOz4veavNmI2+GIDQsY66+tYDvZ+CxwzdYu+HDV9HmrJfc6deM0mnBn7SR
     jqzxJPgoTQhihTav6q/R5/2p5NvQ/H84OgS6GjosfGc2duUDzCP/kheMRKfzuyKC
     OHQPtJuIj8++gfpHtEU7IDUX1So3c9n0PdpeBvclsDbpRnCNxQWU4mBot4kBIgQQ
     AQIADAUCToi2GQUDABJ1AAAKCRCXELibyletfLZAB/9oRqx+NC98UQD/wlxCRytz
     vi/MuPnbgQUPLHEap10tvEi33S/H/xDR/tcGofY4cjAvo5skZXXeWq93Av7PACUb
     zkg0X0eSr2oL6wy66xfov72AwSuX+iUK68qtKaLqRLitM02y8aNRV/ggKvt7UMvG
     mOvs5yLaYlobyvGaFC2ClfkNOt2MlVnQZCmnYBCwOktPGkExiu2yZMifcYGxQcpH
     KVFG59KeF2cM2d4xYM8HJqkSGGW306LFVSyeRwG+wbttgLpD5bM/T2b3fF/J35ra
     CSMLZearRTq8aygPl+XM7MM2eR946aw6jmOsgNBErbvvIdQj6LudAZj+8imcXV2K
     iQEiBBABAgAMBQJOmdnRBQMAEnUAAAoJEJcQuJvKV618AvIIAIEF1ZJ+Ry7WOdKF
     5oeQ/ynaYUigzN92fW/9zB8yuQlngkFJGidYMbci1tR1siziIVJFusR3ZonqAPGK
     /SUta9Y6KWLhmc7c5UnEHklq/NfdMZ2WVSIykXlctqw0sbb+z1ecEd4G8u9j5ill
     MO1B36rQayYAPoeXLX8dY4VyFLVGaQ00rWQBYFZrpw16ATWbWGJP332NSfCk4zZq
     6kXEW07q0st3YBgAAGdNQyEeZCa4d4pBRSX6189Kjg6GDnIcaiOF6HO6PLr9fRlL
     r5ObCgU+G9gEhfiVwDEV9E+7/Bq2pYZ9whhkBqWQzdpXTNTM24uaEhE01EPO5zeC
     O214q6mJASIEEAECAAwFAk6rpgEFAwASdQAACgkQlxC4m8pXrXzAhwf/f9O99z16
     3Y5FZVIxexyqXQ/Mct9uKHuXEVnRFYbA49dQLD4S73N+zN7gn9jFeQcBo4w8qVUV
     94U/ta/VbLkdtNREyplPM4XY8YE5Wfd9bfyg3q1PbEiVjk995sBF+2+To99YYKst
     gXPqjlH0jUfEyDmexOj+hsp8Rc63kvkIx36VBa4ONRYFefGAhKDMigL2YAhc1UkG
     tkGTuLmlCGwIV6lviDZD3RJf5375VFnaHv7eXfwQxCwE+BxG3CURrjfxjaxMTmMP
     yAG2rhDp5oTUEvqDYNbko5UxYOmrSjvF4FzXwqerElXJUkUzSh0pp7RxHB/1lCxD
     s7D1F1hlgFQuNIkBIgQQAQIADAUCTrzZHAUDABJ1AAAKCRCXELibyletfMUpB/4s
     07dREULIBnA1D6qr3fHsQJNZqbAuyDlvgGGLWzoyEDs+1JMFFlaa+EeLIo1386GU
     2DammDC23p3IB79uQhJeD2Z1TcVg4cA64SfF/CHca5coeRSrdAiudzU/cgLGtXIP
     /OaFamXgdMxAhloLFbSHPCZkyb00phVa8+xeIVDrK1HByZsNIXy/SSK8U26S2PVZ
     2o14fWvKbJ1Aga8N6DuWY/D8P2mi3RAbiuZgfzkmKL5idH/wSKfnFKdTgJzssdCc
     1jZEGVk5rFYcWOrJARHeP/tsnb/UxKBEsNtO7e3N2e/rLVnEykVIO066hz7xZK/V
     NBSpx3k3qj4XPK41IHy2iQEiBBABAgAMBQJOzqO8BQMAEnUAAAoJEJcQuJvKV618
     2twH/0IzjXLxN45nvIfEjC75a+i9ZSLlqR8lsHL4GpEScFKI0a0lT4IVAIY2RKG+
     MAs2eHm0UfKuwGs5jluRZ9RqKrc61sY0XQV9/7znY9Db16ghX04JjknOKs/fPi87
     rvKkB/QxJWS8qbb/erRmW+cPNjbRxTFPS5JIwFWHA16ieFEpvdAgKV6nfvJVTq1r
     jPDcnIA9CJN2SmUFx9Qx3SRc6ITbam1hjFnY6sCh6AUhxLI2f1mq1xH9PqEy42Um
     68prRqTyJ7Iox1g/UDDkeeUcAg7T1viTz7uXpS3Wrq4zzo4yOpaJfLDR3pI5g2Zk
     SNGTMo6aySE4OABt8i1Pc1Pm6AmJASIEEAECAAwFAk7yPFYFAwASdQAACgkQlxC4
     m8pXrXzXiAf9FrXe0lgcPM+tYOWMLhv5gXJi2VUBaLxpyRXm/kJcmxInKq1GCd3y
     D4/FLHNu3ZcCz/uklPAbZXWI0O6ewq0LWsRtklmJjWiedH+hGyaTv95VklojRIBd
     8nBaJ6M98rljMBHTFwWvjQFVf4FLRJQZqHlvjcCkq2Dd9BWJpGXvr/gpKkmMJYNK
     /ftfZRcChb35NI19WRpOhj9u808OPcqKVvZBcPwFGV5cEBzmAC94J7JcD8+S8Ik8
     iUJMQGGL3QcmZOBozovh86hj7KTSEBHlLXl832z89H1hLeuLbnXoGLv3zeUFSxkv
     1h35LhZLqIMDQRXLuUzxGHMBpLhPyGWRJ4kBIgQQAQIADAUCTwQJFwUDABJ1AAAK
     CRCXELibyletfABvB/9Cy69cjOqLGywITs3Cpg//40jmdhSAVxilJivP6J5bubFH
     DJlVTx541Dv5h4hTG2BQuueQ4q1VCpSGW+rHcdhPyvmZGRz1rxdQQGh1Dv0Bod2c
     3PJVSYPSrRSwCZJkJHOtVRBdjK4mkZb5aFTza+Tor9kxzj4FcXVd4KAS+hHQHYHc
     Ar8tt2eOLzqdEFTULeGiSoNn+PVzvzdfhndphK+8F2jfQ2UKuc01O7k0Yn9xZVx0
     OG6fE1gStzLv7C5amWLRd8+xh+MN0G8MgNglpBoExsEMMlPBYSUHa6lxpdMNMuib
     rIyVncE9X8QOhImt8K0sNn/EdbuldJNGYbDLt7O4iQEiBBABAgAMBQJPFdTcBQMA
     EnUAAAoJEJcQuJvKV6184owH+wZ/uLpezXnSxigeH1sig72QEXMrNd5DVHCJdig3
     bo+K5YmmN710/m5z+63XKUEWpd6/knajObgckThzWftNeK1SSFQGPmoYZP9EZnSU
     7L+/dSUpExbj842G5LYagrCyMGtlxRywWEmbi72TKS/JOK0jLiOdvVy+PHrZSu0D
     TVQ7cJh1BmPsbz7zzxjmcI5l+7B7K7RHZHq45nDLoIabwDacj7BXvBK0Ajqz4QyJ
     GQUjXC7q+88I+ptPvOXlE5nI/NbiCJOMI6d/bWN1KwYrC80fZuFaznfQFcPyUaDw
     yRaun+K3kEji2wXecq+yMmLUEp01TKsUeOL50HD6hHH07W+JASIEEAECAAwFAk85
     bQsFAwASdQAACgkQlxC4m8pXrXwKPQgAlkbUsTr7nkq+haOk0jKpaHWEbRMEGMrB
     I3F7E+RDO6V/8y4Jtn04EYDc8GgZMBah+mOgeINq3y8jRMYV5jVtZXv2MWYFUcjM
     kVBKeqhi/pGEjmUdmdt3DlPv3Z+fMTMRmAocI981iY/go8PVPg/+nrR6cFK2xxnO
     R8TacikJBFeSfkkORg1tDzjjYv1B5ZIEkpplepl5ahJBBq7cpYhTdY6Yk0Sz0J8w
     EdffLSaNxrRuWLrRhWzZU7p9bFzfb/7OHc21dJnB7wKv5VvtgE+jiQw9tOKaf5hc
     SgRYuF6heu+B25gc5Uu88lo409mZ7oxQ6hDCn7JHvzh0rhmSN+Kid4kBIgQQAQIA
     DAUCT0qQrQUDABJ1AAAKCRCXELibyletfC9UB/4o2ggJYM0CLxEpP0GU8UKOh3+/
     zm1DN7Qe4kY2iCtF1plKHQaTgt5FlgRCFaiXcVv7WzGz/FnmxonR1leLl+kfRlwy
     PPnoI/AWPCy/NO4Cl5KnjsSmsdDUpObwZ4KYsdilZR7ViJu2swdAIgnXBUwrlRJR
     7CK4TAKrTeonRgVSrVx8Vt//8/cYj73CLq8oY/KK0iHiQrSwo44uyhdiFIAssjyX
     n6/2E+w0zgvPexNSNNROHQ8pjbq+NTY6GwKIGsaej3UTRwQ7psvKXz8y7xdzmOAr
     /khGvxB5gjkx02pimjeia8v66aH6rbnojJMAovNUS4EHdHnulv4rovC8Kf9iiQEi
     BBABAgAMBQJPVdsaBQMAEnUAAAoJEJcQuJvKV618vVEIALFXPBzcAO1SnQarBLzy
     YMVZZumPvSXKnUHAO+6kjApXPJ+qFRdUaSNshZxVKY9Zryblu4ol/fLUTt0CliSD
     IxD6L4GXEm4VYYCl4lPO3bVsJnGITLFwQGHM27EmjVoTiD8Ch7kPq2EXr3dMRgzj
     pdz+6aHGSUfOdLTPXufDvW83bEWGaRVuTJKw+wIrcuRqQ+ucWJgJGwcE4zeHjZad
     Jx1XUm1X+BbI73uiQussyjhhQVVNU7QEdrjyuscaZ/H38wjUwNbylxDPB4I8quC1
     knQ0wSHr7gKpM+E9nhiS14poRqU18u78/sJ2MUPXnQA6533IC238/LP8JgqB+BiQ
     BTSJASIEEAECAAwFAk9ng3cFAwASdQAACgkQlxC4m8pXrXxQRAf/UZlkkpFJj1om
     9hIRz7gS+l7YvTaKSzpo+TBcx3C7aqKJpir6TlMK9cb9HGTHo2Xp1N3FtQL72NvO
     6CcJpBURbvSyb4i0hrm/YcbUC4Y3eajWhkRS3iVfGNFbc/rHthViz0r6Y5lhXX16
     aVkDv5CIFWaF3BiUK0FnHrZiy4FPacUXCwEjv3uf8MpxV5oEmo8Vs1h4TL3obyUz
     qrImFrEMYE/12lkE8iR5KWCaF8eFyl56HL3PPl90JMQBXzhwsFoWCPuwjfM5w6sW
     Ll//zynwxtlJ9CRz9c2vK6aJ8DRu3OfBKN1iiEcNEynksDnNXErn5xXKz3p5pYdq
     e9BLzUQCDYkBIgQQAQIADAUCT3inRgUDABJ1AAAKCRCXELibyletfGMKCADJ97qk
     geBntQ+tZtKSFyXznAugYQmbzJld8U6eGSQnQkM40Vd62UZLdA8MjlWKS8y4A4L2
     0cI14zs5tKG9Q72BxQOw5xkxlLASw1/8WeYEbw7ZA+sPG//q9v3kIkru3sv64mMA
     enZtxsykexRGyCumxLjzlAcL1drWJGUYE2Kl6uzQS7jb+3PNBloQvz6nb3YRZ+Cg
     Ly9D41SIK+fpnV8r4iqhu7r4LmAQ7Q1DF9aoGaYvn2+xLGyWHxJAUet4xkMNOLp6
     k9RF1nbNe4I/sqeCB25CZhCTEvHdjSGTD2yJR5jfoWkwO9w8DZG1Q9WrWqki4hSB
     l0cmcvO34pC1SJYziQEiBBABAgAMBQJPinQFBQMAEnUAAAoJEJcQuJvKV618CFEI
     AJp5BbcV7+JBMRSvkoUcAWDoJSP2ug9zGw5FB8J90PDefKWCKs5Tjayf2TvM5ntq
     5DE9SGaXbloIwa74FoZlgqlhMZ4AtY9Br+oyPJ5S844wpAmWMFc6NnEPFaHQkQ+b
     dJYpRVNd9lzagJP261P3S+S9T2UeHVdOJBgWIq9Mbs4lnZzWsnZfQ4Lsz0aPqe48
     tkU8hw+nflby994qIwNOlk/u+I/lJbNz5zDY91oscXTRl2jV1qBgKYwwCXxyB3j9
     fyVpRl+7QnqbTWcCICVFL+uuYpP0HjdoKNqhzEguAUQQLOB9msPTXfa2hG+32ZYg
     5pzI5V7GCHq0KO6u5Ctj3TGJASIEEAECAAwFAk+cQEEFAwASdQAACgkQlxC4m8pX
     rXzi7AgAx8wJzNdD7UlgdKmrAK//YqH7arSssb33Xf45sVHDpUVA454DXeBrZpi+
     zEuo03o5BhAuf38cwfbkV6jN1mC2N0FZfpy4v7RxHKLYr7tr6r+DRn1L1giX5ybx
     CgY0fLAxkwscWUKGKABWxkz9b/beEXaO2rMt+7DBUdpAOP5FNRQ8WLRWBcMGQiaT
     S4YcNDAiNkrSP8CMLQP+04hQjahxwCgBnksylciqz3Y5/MreybNnTOrdjVDsF0Oe
     t0uLOiWXUZV1FfaGIdb/oBQLg+e1B74p5+q3aF8YI97qAZpPa1qiQzWIDX8LX9QX
     EFyZ3mvqzGrxkFoocXleNPgWT8fRuokBIgQQAQIADAUCT64N/QUDABJ1AAAKCRCX
     ELibyletfDOGCACKfcjQlSxrWlEUrYYZpoBP7DE+YdlIGumt5l6vBmxmt/5OEhqr
     +dWwuoiyC5tm9CvJbuZup8anWfFzTTJmPRPsmE4z7Ek+3CNMVM2wIynsLOt1pRFK
     4/5RNjRLbwI6EtoCQfpLcZJ//SB56sK4DoFKH28Ok4cplESPnoMqA3QafdSEA/FL
     qvZV/iPgtTz7vjQkMgrXAIUM4fvKe3iXkAExGXtmgdXHVFoKmHrxJ2DTSvM7/19z
     jGJeu2MhIKHyqEmCk6hLjxyCE5pAH59KlbAQOP1bS28xlRskBApm2wN+LOZWzC62
     HhEReQ50inCGuuubK0PqUQnyYc+lUFxrFpcliQEiBBABAgAMBQJPv9lVBQMAEnUA
     AAoJEJcQuJvKV618AzgH/iRFFCi4qjvoqji1fi7yNPZVOMMO2H13Ks+AfcjRtHuV
     aa30u50ND7TH+XQe6yerTapLh3aAm/sNP99aTxIuwRSlyKEoDs93+XVSgRqPBgbF
     /vxv0ykok3p6L9DxFO/w5cL8JrBhMZoJrEkIBFkwN8tWlcXPRFQvcdBYv3M3DTZU
     qY+UHnOxHvSzsl+LJ0S9Xcd9C5bvYfabmYJvG5eRS3pj1L/y3a6yw6hvY+JtnQAk
     t05TdeHMIgQH/zb8V9wxDzmE0un8LyoC2Jx5TpikQsJSejwK6b3coxVBlngku6+C
     qDAimObZLw6H9xYYIK0FoJs7j5bQZEwUO7OLBgjcMOqJASIEEAECAAwFAk/Rpc8F
     AwASdQAACgkQlxC4m8pXrXw49Qf/TdNbun2htQ+cRWarszOx8BLEiW/x6PVyUQpZ
     nV/0qvhKzlJUjM9hQPcA0AsOjhqtCN6Cy8KXbK/TvPm9D/Nk6HWwD1PomzrJVFk2
     ywGFIuTR+lluKSp7mzm5ym0wJs5cPq731Im31RUQU8ndjLrq9YOf5FVL8NqmcOAU
     4E8d68BbmVCQC5MMr0901FKwKznShfpy7VYN25/BASj8dhnynBYQErqToOJB6Cnd
     JhdTlbfR4SirqAYZZg3XeqGhByytEHE1x7FMWWFYhdNtsnAVhYBbWqAzBs8lF9Jd
     Mhaf0VQU/4z10gVrRtXLR/ixrCi+P4cM/fOQkqd6pwqWkaXt6okBIgQQAQIADAUC
     T+NxIAUDABJ1AAAKCRCXELibyletfFBBCAC6+0TUJDcNaqOxOG1KViY6KYg9NCL8
     pwNK+RKNK/N1V+WGJQH7qDMwRoOn3yogrHax4xIeOWiILrvHK0O6drS1DjsymIhR
     Sm2XbE/8pYmEbuJ9vHh3b/FTChmSAO7dDjSKdWD3dvaY8lSsuDDqPdTX8FzOfrXC
     M22C/YPg7oUG2A5svE1b+yismP4KmVNWAepEuPZcnEMPFgop3haHg9X2+mj/btDB
     Yr6p9kAgIY17nigtNTNjtI0dMLu43aIzedCYHqOlNHiB049jkJs54fMGBjF9qPtc
     m0k44xyKd1/JXWMdNUmtwKsChAXJS3YOciMgIx6tqYUTndrP4I6q1rfriQEiBBAB
     AgAMBQJP9T1VBQMAEnUAAAoJEJcQuJvKV618J9wIAI1lId9SMbEHF6PKXRe154lE
     pap5imMU/lGTj+9ZcXmlf8o2PoMMmb3/E1k+EZUaeSBoOmjS8C2gwd5XFwRrlwAD
     RlK/pG5XsL4h5wmN2fj1ororrJXvqH427PLRQK9yzdwG4+9HTBOxjoS8qZT9plyK
     AJZzAydAMqyseRHgNo0vMwlgrs4ojo+GcFGQHrF3IaUjvVfUPOmIj7afopFdIZmI
     GaSF0TXBzqcZ1chFv/eTBcIuIKRvlaDee5FgV7+nLH2nKOARCLvV/+8uDi2zbr83
     Ip5x2tD3XuUZ0ZWxD0AQWcrLdmGb4lkxbGxvCtsaJHaLXWQ2m760RjIUcwVMEBKJ
     ASIEEAECAAwFAlAGYWsFAwASdQAACgkQlxC4m8pXrXwyVAgAvuvEl6yuGkniWOlv
     uHEusUv/+2GCBg6qV+IEpVtbTCCgiFjYR5GasSp1gpZ5r4BocOlbGdjdJGHTpyK8
     xD1i+6qZWUYhNRg2POXUVzcNEl2hhouwPLOifcmTwAKU76TEv3L5STviL3hWgUR2
     yEUZ3Ut0IGVV6uPER9jpR3qd6O3PeuFkwf+NaGTye4jioLAy3aYwtZCUXzvYmNLP
     90K4y+5yauZteLmNeq26miKC/NQu4snNFClPbGRjHD1ex9KDiAMttOgN4WEq7srT
     rYgtT531WY4deHpNgoPlHPuAfC0H+S6YWuMbgfcb6dV+Rrd8Ij6zM3B/PcjmsYUf
     OPdPtIkBIgQQAQIADAUCUBgtfQUDABJ1AAAKCRCXELibyletfAm3CACQlw21Lfeg
     d8RmIITsfnFG/sfM3MvZcjVfEAtsY3fTK9NiyU0B3yX0PU3ei37qEW+50BzqiStf
     5VhNvLfbZR+yPou7o2MAP31mq3Uc6grpTV64BRIkCmRWg40WMjNI1hv7AN/0atgj
     ATYQXgnEw7mfFb0XZtMTD6cmrz/A9nTPVgZDxzopOMgCCC1ZK4Vpq9FKdCYUaHpX
     3sqnDf+gpVIHkTCMgWLYQOeX5Nl+fgnq6JppaQ3ySZRUDr+uFUs0uvDRvI/cn+ur
     ri92wdDnczjFumKvz/cLJAg5TG2Jv1Jx3wecALsVqQ3gL7f7vr1OMaqhI5FEBqdN
     29L9cZe/ZmkriQEiBBIBCgAMBQJVoNxyBYMHhh+AAAoJEEoz7NUmyPxLD1EH/2eh
     7a4+8A1lPLy2L9xcNt2bifLfFP2pEjcG6ulBoMKpHvuTCgtX6ZPdHpM7uUOje/F1
     CCN0IPB533U1NIoWIKndwNUJjughtoRM+caMUdYyc4kQm29Se6hMPDfyswXE5Bwe
     PmoOm4xWPVOH/cVN04zyLuxdlQZNQF/nJg6PMsz4w5z+K6NGGm24NEPcc72iv+6R
     Uc/ry/7v5cVu4hO5+r104mmNV5yLecQF13cHy2JlngIHXPSlxTZbeJX7qqxE7TQh
     5nviSPgdk89oB5jFSx4g1efXiwtLlP7lbDlxHduomyQuH9yqmPZMbkJt9uZDc8Zz
     MYsDDwlc7BIe5bGKfjqJAhwEEAECAAYFAlSanFIACgkQdzHqU52lcqLdvg//cAEP
     qdN5VTKWEoDFjDS4I6t8+0KzdDWDacVFwKJ8RAo1M2SklDxnIvnzysZd2VHp5Pq7
     i4LYCZo5lDkertQ6LwaQxc4X6myKY4LTA652ObFqsSfgh9kW+aJBBAyeahPQ8CDD
     +Yl23+MY5wTsj4qt7KffNzy78vLbYnVnvRQ3/CboVix0SRzg0I3Oi7n3B0lihvXy
     5goy9ikjzZevejMEfjfeRCgoryy9j5RvHH9PF3fJVtUtHCS4f+kxLmbQJ1XqNDVD
     hlFzjz8oUzz/8YXy3im5MY7Zuq4P4wWiI7rkIFMjTYSpz/evxkVlkR74qOngT2pY
     VHLyJkqwh56i0aXcjMZiuu2cymUt2LB9IsaMyWBNJjXr2doRGMAfjuR5ZaittmML
     yZwix9mWVk7tkwlIxmT/IW6Np0qMhDZcWYqPRpf7+MqY3ZYMK4552b8aDMjhXrnO
     OwLsz+UI4bZa1r9dguIWIt2C2b5C1RQ9AsQBPwg7h5P+HhRuFAuDKK+vgV8FRuzR
     JeKkFqwB4y0Nv7BzKbFKmP+V+/krRv+/Dyz9Bz/jyAQgw02u1tPupH9BGhlRyluN
     yCJFTSNj7G+OLU0/l4XNph5OOC7sy+AMZcsL/gsT/TXCizRcCuApNTPDaenACpbv
     g8OoIzmNWhh4LXbAUHCKmY//hEw9PvTZA1xKHgyJAhwEEgECAAYFAlJYsKQACgkQ
     oirk60MpxUV2XQ//b2/uvThkkbeOegusDC4AZfjnL/V3mgk4iYy4AC9hum0R9oNl
     XDR51P1TEw9mC1btHj+7m7Iq1a5ke5wIC7ENZiilr0yPqeWgL5+LC98dz/L85hqA
     wIoGeOfMhrlaVbAZEj4yQTAJDA35vZHVsQmp87il0m+fZX04OBLXBzw86EoAAZ7Q
     EoH4qFcT9k1T363tvNnIm3mEvkQ5WjE1R9uchJa1g7hdlNQlVkjFmPZrJK9fl4z5
     6Dto89Po4Sge48jDH0pias4HATYHsxW819nz5jZzGcxLnFRRR5iITVZi9qzsHP7N
     bUh3qxuWCHS9xziXpOcSZY848xXw63Y5jDJfpzupzu/KHj6CzXYJUEEqp9MluoGb
     /BCCEPzdZ0ovyxFutM/BRcc6DvE6sTDF/UES21ROqfuwtJ6qJYWX+lBIgyCJvj4o
     RdbzxUleePuzqCzmwrIXtoOKW0Rlj4SCeF9yCwUMBTGW5/nCLmN4dwf1KW2RP2Eg
     4ERbuUy7QnwRP5UCl+0ISZJyYUISfg8fmPIdQsetUK9Cj+Q5jpB2GXwELXWnIK6h
     K/6jXp+EGEXSqdIE53vAFe7LwfHiP/D5M71D2h62sdIOmUm3lm7xMOnM5tKlBiV+
     4jJSUmriCT62zo710+6iLGqmUUYlEll6Ppvo8yuanXkYRCFJpSSP7VP0bBqIZgQT
     EQIAJgUCTnc9dgIbIwUJEPPzpwYLCQgHAwIEFQIIAwQWAgMBAh4BAheAAAoJEIxx
     jTtQcuH1Ut4AoIKjhdf70899d+7JFq3LD7zeeyI0AJ9Z+YyE1HZSnzYi73brScil
     bIV6sbQ7TXlTUUwgUGFja2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkg
     PGJ1aWxkQG15c3FsLmNvbT6IbwQwEQIALwUCTnc9rSgdIGJ1aWxkQG15c3FsLmNv
     bSB3aWxsIHN0b3Agd29ya2luZyBzb29uAAoJEIxxjTtQcuH1tT0An3EMrSjEkUv2
     9OX05JkLiVfQr0DPAJwKtL1ycnLPv15pGMvSzav8JyWN3IhlBBMRAgAdBQJHrJS0
     BQkNMFioBQsHCgMEAxUDAgMWAgECF4AAEgkQjHGNO1By4fUHZUdQRwABAa6SAJ9/
     PgZQSPNeQ6LvVVzCALEBJOBt7QCffgs+vWP18JutdZc7XiawgAN9vmmITAQTEQIA
     DAUCPj6j0QWDCWYAuwAKCRBJUOEqsnKR8iThAJ9ZsR4o37dNGyl77nEqP6RAlJqa
     YgCeNTPTEVY+VXHR/yjfyo0bVurRxT2ITAQTEQIADAUCPkKCAwWDCWIiiQAKCRC2
     9c1NxrokP5aRAKCIaaegaMyiPKenmmm8xeTJSR+fKQCgrv0TqHyvCRINmi6LPucx
     GKwfy7KIRgQQEQIABgUCP6zjrwAKCRCvxSNIeIN0D/aWAKDbUiEgwwAFNh2n8gGJ
     Sw/8lAuISgCdHMzLAS26NDP8T2iejsfUOR5sNriIRgQQEQIABgUCP7RDdwAKCRCF
     lq+rMHNOZsbDAJ0WoPV+tWILtZG3wYqg5LuHM03faQCeKuVvCmdPtro06xDzeeTX
     VrZ14+GIRgQQEQIABgUCQ1uz6gAKCRCL2C5vMLlLXH90AJ0QsqhdAqTAk3SBnO2w
     zuSOwiDIUwCdFExsdDtXf1cL3Q4ilo+OTdrTW2CIRgQTEQIABgUCRPEzJgAKCRD2
     ScT0YJNTDApxAKCJtqT9LCHFYfWKNGGBgKjka0zi9wCcCG3MvnvBzDUqDVebudUZ
     61Sont+ITAQQEQIADAUCQYHLAQWDBiLZiwAKCRAYWdAfZ3uh7EKNAJwPywk0Nz+Z
     Lybw4YNQ7H1UxZycaQCePVhY4P5CHGjeYj9SX2gQCE2SNx+ITAQQEQIADAUCQYHL
     NAWDBiLZWAAKCRCBwvfr4hO2kiIjAJ0VU1VQHzF7yYVeg+bh31nng9OOkwCeJI8D
     9mx8neg4wspqvgXRA8+t2saITAQQEQIADAUCQYHLYgWDBiLZKgAKCRBrcOzZXcP0
     cwmqAJsFjOvkY9c5eA/zyMrOZ1uPB6pd4QCdGyzgbYb/eoPu6FMvVI9PVIeNZReI
     TAQQEQIADAUCQdCTJAWDBdQRaAAKCRB9JcoKwSmnwmJVAKCG9a+Q+qjCzDzDtZKx
     5NzDW1+W+QCeL68seX8OoiXLQuRlifmPMrV2m9+ITAQQEQIADAUCQitbugWDBXlI
     0gAKCRDmG6SJFeu5q/MTAKCTMvlCQtLKlzD0sYdwVLHXJrRUvgCffmdeS6aDpwIn
     U0/yvYjg1xlYiuqITAQSEQIADAUCQCpZOgWDB3pLUgAKCRA8oR80lPr4YSZcAJwP
     4DncDk4YzvDvnRbXW6SriJn1yQCdEy+d0CqfdhM7HGUs+PZQ9mJKBKqITAQSEQIA
     DAUCQD36ugWDB2ap0gAKCRDy11xj45xlnLLfAKC0NzCVqrbTDRw25cUss14RRoUV
     PACeLpEc3zSahJUB0NNGTNlpwlTczlCITAQSEQIADAUCQQ4KhAWDBpaaCAAKCRA5
     yiv0PWqKX/zdAJ4hNn3AijtcAyMLrLhlZQvib551mwCgw6FEhGLjZ+as0W681luc
     wZ6PzW+ITAQSEQIADAUCQoClNAWDBSP/WAAKCRAEDcCFfIOfqOMkAJwPUDhS1eTz
     gnXclDKgf353LbjvXgCeLCWyyj/2d0gIk6SqzaPl2UcWrqiITAQTEQIADAUCPk1N
     hAWDCVdXCAAKCRAtu3a/rdTJMwUMAKCVPkbk1Up/kyPrlsVKU/Nv3bOTZACfW5za
     HX38jDCuxsjIr/084n4kw/uITAQTEQIADAUCQdeAdgWDBc0kFgAKCRBm79vIzYL9
     Pj+8AJ9d7rvGJIcHzTCSYVnaStv6jP+AEACeNHa5yltqieRBCCcLcacGqYK81omI
     TAQTEQIADAUCQhiBDgWDBYwjfgAKCRB2wQMcojFuoaDuAJ9CLYdysef7IsW42UfW
     hI6HjxkzSgCfeEpXS4hEmmGicdpRiJQ/W21aB0GIZQQTEQIAHQULBwoDBAMVAwID
     FgIBAheABQJLcC/KBQkQ8/OnABIHZUdQRwABAQkQjHGNO1By4fWw2wCeJilgEarL
     8eEyfDdYTyRdqE45HkoAnjFSZY8Zg/iXeErHI0r04BRukNVgiHsEMBECADsFAkJ3
     NfU0HQBPb3BzLi4uIHNob3VsZCBoYXZlIGJlZW4gbG9jYWwhIEknbSAqc28qIHN0
     dXBpZC4uLgAKCRA5yiv0PWqKX+9HAJ0WjTx/rqgouK4QCrOV/2IOU+jMQQCfYSC8
     JgsIIeN8aiyuStTdYrk0VWCIjwQwEQIATwUCRW8Av0gdAFNob3VsZCBoYXZlIGJl
     ZW4gYSBsb2NhbCBzaWduYXR1cmUsIG9yIHNvbWV0aGluZyAtIFdURiB3YXMgSSB0
     aGlua2luZz8ACgkQOcor9D1qil+g+wCfcFWoo5qUl4XTE9K8tH3Q+xGWeYYAnjii
     KxjtOXc0ls+BlqXxbfZ9uqBsiQIiBBABAgAMBQJBgcuFBYMGItkHAAoJEKrj5s5m
     oURoqC8QAIISudocbJRhrTAROOPoMsReyp46Jdp3iL1oFDGcPfkZSBwWh8L+cJjh
     dycIwwSeZ1D2h9S5Tc4EnoE0khsS6wBpuAuih5s//coRqIIiLKEdhTmNqulkCH5m
     imCzc5zXWZDW0hpLr2InGsZMuh2QCwAkB4RTBM+r18cUXMLV4YHKyjIVaDhsiPP/
     MKUj6rJNsUDmDq1GiJdOjySjtCFjYADlQYSD7zcd1vpqQLThnZBESvEoCqumEfOP
     xemNU6xAB0CL+pUpB40pE6Un6Krr5h6yZxYZ/N5vzt0Y3B5UUMkgYDSpjbulNvaU
     TFiOxEU3gJvXc1+h0BsxM7FwBZnuMA8LEA+UdQb76YcyuFBcROhmcEUTiducLu84
     E2BZ2NSBdymRQKSinhvXsEWlH6Txm1gtJLynYsvPi4B4JxKbb+awnFPusL8W+gfz
     jbygeKdyqzYgKj3M79R3geaY7Q75Kxl1UogiOKcbI5VZvg47OQCWeeERnejqEAdx
     EQiwGA/ARhVOP/1l0LQA7jg2P1xTtrBqqC2ufDB+v+jhXaCXxstKSW1lTbv/b0d6
     454UaOUV7RisN39pE2zFvJvY7bwfiwbUJVmYLm4rWJAEOJLIDtDRtt2h8JahDObm
     3CWkpadjw57S5v1c/mn+xV9yTgVx5YUfC/788L1HNKXfeVDq8zbAiQIiBBMBAgAM
     BQJCnwocBYMFBZpwAAoJENjCCglaJFfPIT4P/25zvPp8ixqV85igs3rRqMBtBsj+
     5EoEW6DJnlGhoi26yf1nasC2frVasWG7i4JIm0U3WfLZERGDjR/nqlOCEqsP5gS3
     43N7r4UpDkBsYh0WxH/ZtST5llFK3zd7XgtxvqKL98l/OSgijH2W2SJ9DGpjtO+T
     iegq7igtJzw7Vax9z/LQH2xhRQKZR9yernwMSYaJ72i9SyWbK3k0+e95fGnlR5pF
     zlGq320rYHgD7v9yoQ2t1klsAxK6e3b7Z+RiJG6cAU8o8F0kGxjWzF4v8D1op7S+
     IoRdB0Bap01ko0KLyt3+g4/33/2UxsW50BtfqcvYNJvU4bZns1YSqAgDOOanBhg8
     Ip5XPlDxH6J/3997n5JNj/nk5ojfd8nYfe/5TjflWNiput6tZ7frEki1wl6pTNbv
     V9C1eLUJMSXfDZyHtUXmiP9DKNpsucCUeBKWRKLqnsHLkLYydsIeUJ8+ciKc+EWh
     FxEY+Ml72cXAaz5BuW9L8KHNzZZfez/ZJabiARQpFfjOwAnmhzJ9r++TEKRLEr96
     taUI9/8nVPvT6LnBpcM38Td6dJ639YvuH3ilAqmPPw50YvglIEe4BUYD5r52Seqc
     8XQowouGOuBX4vs7zgWFuYA/s9ebfGaIw+uJd/56Xl9ll6q5CghqB/yt1EceFEnF
     CAjQc2SeRo6qzx22iEYEEBECAAYFAkSAbycACgkQCywYeUxD5vWDcACfQsVk/XGi
     ITFyFVQ3IR/3Wt7zqBMAoNhso/cX8VUfs2BzxPvvGS3y+5Q9iEYEEBECAAYFAkUw
     ntcACgkQOI4l6LNBlYkyFgCbBcw5gIii0RTDJsdNiuJDcu/NPqEAniSq9iTaLjgF
     HZbaizUU8arsVCB5iEYEEBECAAYFAkWho2sACgkQu9u2hBuwKr6bjwCfa7ZK6O+X
     mT08Sysg4DEoZnK4L9UAoLWgHuYg35wbZYx+ZUTh98diGU/miF0EExECAB0FAj4+
     owwFCQlmAYAFCwcKAwQDFQMCAxYCAQIXgAAKCRCMcY07UHLh9XGOAJ4pVME15/DG
     rUDohtGv2z8a7yv4AgCeKIp0jWUWE525QocBWms7ezxd6syIXQQTEQIAHQUCR6yU
     zwUJDTBYqAULBwoDBAMVAwIDFgIBAheAAAoJEIxxjTtQcuH1dCoAoLC6RtsD9K3N
     7NOxcp3PYOzH2oqzAKCFHn0jSqxk7E8by3sh+Ay8yVv0BYhdBBMRAgAdBQsHCgME
     AxUDAgMWAgECF4AFAkequSEFCQ0ufRUACgkQjHGNO1By4fUdtwCfRNcueXikBMy7
     tE2BbfwEyTLBTFAAnifQGbkmcARVS7nqauGhe1ED/vdgiF0EExECAB0FCwcKAwQD
     FQMCAxYCAQIXgAUCS3AuZQUJEPPyWQAKCRCMcY07UHLh9aA+AKCHDkOBKBrGb8tO
     g9BIub3LFhMvHQCeIOOot1hHHUlsTIXAUrD8+ubIeZaJARwEEgECAAYFAkvCIgMA
     CgkQ3PTrHsNvDi8eQgf/dSx0R9Klozz8iK79w00NOsdoJY0Na0NTFmTbqHg30XJo
     G62cXYgc3+TJnd+pYhYi5gyBixF/L8k/kPVPzX9W0YfwChZDsfTw0iDVmGxOswiN
     jzSo0lhWq86/nEL30Khl9AhCC1XFNRw8WZYq9Z1qUXHHJ2rDARaedvpKHOjzRY0N
     dx6R2zNyHDx2mlfCQ9wDchWEuJdAv0uHrQ0HV9+xq7lW/Q3L/V5AuU0tiowyAbBL
     PPYrB6x9vt2ZcXS7BOy8SfQ1i8W2QDQ/Toork4YwBiv6WCW/ociy7paAoPOWV/Nf
     2S6hDispeecbk7wqpbUj5klDmwrlgB/jmoAXWEnbsYkBIgQQAQIADAUCSSpooAUD
     ABJ1AAAKCRCXELibyletfFOMCACpP+OVZ7lH/cNY+373c4FnSI0/S5PXS0ABgdd4
     BFWRFWKrWBeXBGc8sZfHOzVEwkzV96iyHbpddeAOAkEA4OVPW1MMFCmlHxi2s9/N
     JrSrTPVfQOH5fR9hn7Hbpq/ETw0IoX1FKo7vndMnHZnFEnI+PDXLcdMYQgljYzhT
     xER4vYY0UKu8ekSshUy4zOX7XSJxwqPUvps8qs/TvojIF+vDJvgFYHVkgvS+shp8
     Oh/exg9vKETBlgU87Jgsqn/SN2LrR/Jhl0aLd0G0iQ+/wHmVYdQUMFaCZwk/BKNa
     XPzmGZEUZ3RNbYa19Mo7hcE3js76nh5YMxFvxbTggVu4kdFkiQEiBBABAgAMBQJK
     M06IBQMAEnUAAAoJEJcQuJvKV618F4gH/innejIHffGMk8jYix4ZZT7pW6ApyoI+
     N9Iy85H4L+8rVQrtcTHyq0VkcN3wPSwtfZszUF/0qP6P8sLJNJ1BtrHxLORYjJPm
     gveeyHPzA2oJl6imqWUTiW822fyjY/azwhvZFzxmvbFJ+r5N/Z57+Ia4t9LTSqTN
     HzMUYaXKDaAqzZeK7P0E6XUaaeygbjWjBLQ1O0ezozAy+Kk/gXApmDCGFuHSFe7Z
     mgtFcbXLM2XFQpMUooETD2R8MUsd+xnQsff/k6pQOLxi+jUEsWSr/iqmvlk6gZ4D
     pemBjuhcXYlxJYjUaX9Zmn5s+ofF4GFxRqXoY7l9Z+tCM9AX37lm6S+JASIEEAEC
     AAwFAkpEcgoFAwASdQAACgkQlxC4m8pXrXz2mgf/RQkpmMM+5r8znx2TpRAGHi5w
     ktvdFxlvPaOBWE28NDwTrpcoMqo9kzAiuvEQjVNihbP21wR3kvnQ84rTAH0mlC2I
     uyybggpqwzOUl+Wi0o+vk8ZA0A0dStWRN8uqneCsd1XnqDe1rvqC4/9yY223tLmA
     kPvz54ka2vX9GdJ3kxMWewhrVQSLCktQpygU0dujGTDqJtnk0WcBhVF9T87lv3W2
     eGdPielzHU5trXezmGFj21d56G5ZFK8co7RrTt4qdznt80glh1BTGmhLlzjMPLTe
     dcMusm3D1QB9ITogcG94ghSf9tEKmmRJ6OnnWM5Kn9KcL63E5oj2/lY9H54wSYkB
     IgQQAQIADAUCSlY+RwUDABJ1AAAKCRCXELibyletfOOQB/0dyJBiBjgf+8d3yNID
     pDktLhZYw8crIjPBVdOgX12xaUYBTGcQITRVHSggzffDA5BQXeUuWhpL4QB0uz1c
     EPPwSMiWiXlBtwF5q6RVf3PZGJ9fmFuTkPRO7SruZeVDo9WP8HjbQtOLukYf566e
     grzAYR9p74UgWftpDtmrqrRTobiuvsFBxosbeRCvEQCrN0n+p5D9hCVB88tUPHnO
     WA4mlduAFZDxQWTApKQ92frHiBqy+M1JFezz2OM3fYN+Dqo/Cb7ZwOAA/2dbwS7o
     y4sXEHbfWonjskgPQwFYB23tsFUuM4uZwVEbJg+bveglDsDStbDlfgArXSL/0+ak
     lFcHiQEiBBABAgAMBQJKaAqEBQMAEnUAAAoJEJcQuJvKV618rH0H/iCciD4U6YZN
     JBj0GN7/Xt851t9FWocmcaC+qtuXnkFhplXkxZVOCU4VBMs4GBoqfIvagbBTyfV4
     Di+W8Uxr+/1jiu3l/HvoFxwdwNkGG6zNBhWSjdwQpGwPvh5ryV1OfLX/mgQgdDmx
     vqz5+kFDUj4m7uLaeuU2j1T0lR4zU0yAsbt7J3hwfqJCXHOc9bm5nvJwMrSm+sdC
     TP5HjUlwHr9mTe8xuZvj6sO/w0P4AqIMxjC9W7pT9q0ofG2KSTwt7wFbh05sbG4U
     QYOJe4+Soh3+KjAa1c0cvmIh4cKX9qfCWwhhdeNfh1A9VTHhnl5zTv/UjvnQtjhl
     H/Fq1eBSKcSJASIEEAECAAwFAkp5LgoFAwASdQAACgkQlxC4m8pXrXwY6wgAg3f8
     76L3qDZTYlFAWs3pXBl8GsUr1DEkTlEDZMZKDM3wPmhaWBR1hMA3y6p3aaCUyJIJ
     BEneXzgyU9uqCxXpC78d5qc3xs/Jd/SswzNYuvuzLYOw5wN5L31SLmQTQ8KqE0uo
     RynBmtDCQ4M2UKifSnv+0+3mPh85LVAS481GNpL+VVfCYtKesWNu40+98Yg6L9NG
     WwRTfsQbcdokZo44Jz7Y7f81ObC4r/X1DgPj2+d4AU/plzDcdrbINOyprs+7340e
     cnaGO4Lsgd19b1CvcgJgltRquu3kRvd+Ero2RYpDv6GVK8Ea0Lto4+b/Ae8cLXAh
     QnaWQCEWmw+AU4Jbz4kBIgQQAQIADAUCSo5fvQUDABJ1AAAKCRCXELibyletfA08
     B/9w8yJdc8K+k07U30wR/RUg3Yb2lBDygmy091mVsyB0RGixBDXEPOXBqGKAXiV1
     QSMAXM2VKRsuKahY2HFkPbyhZtjbdTa7Pr/bSnPvRhAh9GNWvvRg2Kp3qXDdjv9x
     ywEghKVxcEIVXtNRvpbqRoKmHzIExvUQck5DM1VwfREeYIoxgs4035WADhVMdngQ
     S2Gt8P2WaU/p8EZhFGg6X8KtOlD68zGboaJe0hj2VDc+Jc+KdjRfE3fW5IToid/o
     DkUaIW6tB3WkXb0g6D/2hrEJbX3headChHKSB8eQdOR9bcCJDhhU8csd501qmrhC
     ctmvlpeWQZdIQdk6sABPWeeCiQEiBBABAgAMBQJKoBJHBQMAEnUAAAoJEJcQuJvK
     V618Ml8H/1D88/g/p9fSVor4Wu5WlMbg8zEAik3BIxQruEFWda6nART6M9E7e+P1
     ++UHZsWYs6l9ROpWxRLG1Yy9jLec2Y3nUtb20m65p+IVeKR2a9PHW35WZDV9dOYP
     GZabKkO1clLeWLVgp9LRjZ+AeRG+ljHqsULXro1dwewLTB/gg9I2vgNv6dKxyKak
     nM/GrqZLATAq2KoaE/u/6lzRFZIzZnLtjZh8X7+nS+V8v9IiY4ntrpkrbvFk30U6
     WJp79oBIWwnW/84RbxutRoEwSar/TLwVRkcZyRXeJTapbnLGnQ/lDO1o1d7+Vbjd
     q/Sg/cKHHf7NthCwkQNsCnHL0f51gZCJASIEEAECAAwFAkqoEAAFAwASdQAACgkQ
     lxC4m8pXrXwE/Af/XD4R/A5R6Ir/nCvKwCTKJmalajssuAcLEa2pMnFZYO/8rzLO
     +Gp8p0qFH9C4LFwA0NvR5q6X/swuROf4zxljSvNcdlQVaAfJ2ZDEgJ5GXzsPplrv
     SAI9jS3LL7fSWDZgKuUe0a4qx7A0NgyGMUYGhP+QlRFa8vWEBI9fANd/0mMqAeBV
     qQyOH0X1FiW1Ca2Jn4NKfuMy9GEvRddVIbB1LvoNVtXPNzeeKMyNb9Jdx1MFWssy
     COBP2DayJKTmjvqPEc/YOjOowoN5sJ/jn4mVSTvvlTooLiReSs6GSCAjMVxN7eYS
     /Oyq6Iu1JDcJvmB8N2WixAZtAVgF8OA7CWXKVYkBIgQQAQIADAUCSrnHiQUDABJ1
     AAAKCRCXELibyletfPChB/9uECti1dZeNuFsd0/RuGyRUVlrrhJE6WCcOrLO9par
     rPbewbKBmjSzB0MygJXGvcC06mPNuquJ7/WpxKsFmfg4vJBPlADFKtgRUy9BLzjC
     eotWchPHFBVW9ftPbaQViSUu7d89NLjDDM5xrh80puDIApxoQLDoIrh3T1kpZx56
     jSWv0gelFUMbXAzmqkJSyL4Xdh1aqzgUbREd7Xf2ICzuh0sV6V7c/AwWtjWEGEsA
     HZaiQDywZwbC18GwrMLiAzGWb/AScFDQRCZKJDjL+Ql8YT6z+ZMVr8gb7CIU5PKY
     dhiIf2UVTQwLAoW7lNRCQQAqcGjK3IMIz7SO/yk4HmVUiQEiBBABAgAMBQJK3gjG
     BQMAEnUAAAoJEJcQuJvKV618jkEH+wb0Zv9z7xQgpLMowVuBFQVu8/z7P5ASumyB
     PUO3+0JVxSHBhlCKQK7n11m1fhuGt2fCxXhSU6LzXj36rsKRY53lGZ9QhvqFUtQH
     3Xb2IQLIJC4UKjG2jSSCdcuA/x98bwp2v7O03rn7ndCS16CwXnRV3geQoNipRKMS
     DajKPpZv1RiZm8pMKqEb8WSw352xWoOcxuffjlsOEwvJ85SEGCAZ9tmIlkZOc7Ai
     QONDvii9b8AYhQ60RIQC0HP2ASSmK0V92VeFPxHmAygdDQgZNVtbVxgnnt7oTNEu
     VRXNY+z4OfBArp7R+cTsvijDRZY4kML1n22hUybwoxUEvjqZV2+JASIEEAECAAwF
     AkrvOlQFAwASdQAACgkQlxC4m8pXrXxrPAgArXiNgZirNuBhfNCXlkzkCHLx5wnV
     e4SmTpbWzTwWw7+qk7d4l9hlWtdImISORINzo7f4ShSUzJX2GciNaXhaHRo7+y5O
     Zbu82jQb09aQQj/nibKYuqxqUrobTEm+DuYz3JUQZm2PsPcHLS8mX9cxvrJUncPG
     nXEV0DRaq71SGWDprtkvBbp6i38aY3sIhYgz8wM5m1szKDtjywmBYcFehIdozt9z
     hm7wZshzRWQX1+Rf/pIsnk+OzBIa34crSemTnacbV/B7278z2XAyziPNFuqz0xu+
     iltOmYmayfNWAmumuw9NcuwWMlth6Mc2HLrpo0ZBheJ6iuDMPsHnwqdB/4kBIgQQ
     AQIADAUCSwBd2gUDABJ1AAAKCRCXELibyletfP6tB/4m1w0BtlkJgtS6E+B/ns14
     z4A4PGors+n+MYm05qzvi+EnDF/sytCmVcKeimrtvDcfoDtKAFFvJjcYXfnJdGWm
     Pu0SJMRL5KKCirAKwZmU/saxOgoB5QLNw+DHPteJ3w9GmWlGxIqG1r15WC5duzBC
     y3FsnjJYG3jaLnHOO9yXXb5h0kUTORfUKdvAr1gxF2KoatZWqGoaPPnHoqb88rjt
     zk8I7gDqoXnzh8wLxa0ZYvfTC/McxdWTrwXLft+krmMQ18iIZEne2hvVLNJVuluU
     oiWLeHA8iNCQ4W4WTdLc1mCnCjGTMX/MN41uLH0C9Ka4R6wEaqj4lPDk1B/1TV+Q
     iQEiBBABAgAMBQJLEYGrBQMAEnUAAAoJEJcQuJvKV618naIH/2t9aH5mBTKBN6fU
     qhrf79vIsjtI/QNS5qisBISZMX3/1/0Gu6WnxkPSfdCUJMWCjMcnVj7KU2wxTHHG
     VpAStd9r2afUNxRyqZwzwyytktuZok0XngAEDYDDBS3ssu2R4uWLCsC2ysXEqO/5
     tI5YrTWJZrfeIphTaYP5hxrMujvqy3kEwKKbiMz91cDeiLS+YCBcalj5n/1dMYf7
     8U8C6ieurxAg/L8h6x25VM4Ilx4MmG2T8QGtkkUXd+Fd/KYWmf0LE5LLPknf0Hhw
     oVslPXeinp4FsHK/5wzviv4YZpzuTqs9NlKcMsa4IuuPOB0FDf0pn+OFQbEg9QwY
     2gCozK+JASIEEAECAAwFAksjTdQFAwASdQAACgkQlxC4m8pXrXwlogf/XBGbXRVX
     LMaRN4SczOjwT3/tUCriTkb3v+zKjRG90zFhYAccjn7w+7jKQicjq6quQG1EH2X4
     /Su6ps1lDLqGHHhiJW3ZhxQScLZmhdAYsh2qG4GP/UW3QjXG7c61t+H3olvWg2cr
     wqCxxFZAgkAAkr9xcHWFZJEQeXoob6cCZObaUnHSANdmC6s5lUxXYa2bmL7Q3UB4
     4KCzDvAfbPZKJOw9k0qb3lc11zx+vGdyZFbm4R0+3LPp/vT0b3GlSbbF9lU1GOXh
     VaphrgFFa76dmjfHCkPplXAkK1VSIU/aPGAefduTFMdlSZpdMtJ5AULjGcszBDlR
     pLlPxvqVa0ZpgIkBIgQQAQIADAUCSycmkgUDABJ1AAAKCRCXELibyletfHlNCACp
     1YespiHfQt2alcscE5zgfETEHHic8Ai6pNkU9HT4TeWcFHEDe5QqfYcpjLrQvBXS
     kSvxEittbyRdv+e+j5Z+HyHjiG8nAQBL6qy9eHqQE4+d7gYs6DTk7sG9ZMYphREb
     ltzD+F4hVCQdLT8LNr0eVFN7ehqECScDaCG8/Qyti+l/0M902/Yn+mz0ilOiUdWJ
     9x6LPaIINtb1gsYDEylLjwGIZmI0r5Kh9wYoV4vnNezFbxO1uRiW0B7iaPjIEsbt
     OOKp7wx2aX+DM3N9F3BtaIY8XnzcnomNm83SNsgmgrZljpQltUnNqIhNM8DupQ+I
     WOV5gtl6pTC7CgeVTVyRiQEiBBABAgAMBQJLOGXuBQMAEnUAAAoJEJcQuJvKV618
     ll4IAKJ9mm4jb0c8fe9+uDI8eCJRbzNbVXm8zWzpA8GUtQAakwxoKv332QP1Wa1P
     odni/e3EMhsSREOZJJv79YqGxGRBTE9Kb/VjM34nas4XSnXKW28XWhKyIw+XwQAi
     nY2swFHh+83Htr/mwTdJfS2aEYl2zboBvd/JZCdhOGU2GH737S/3uEczoKkfVQ/w
     OTM8X1xWwlYWqx23k/DsGcuDs9lA2g7Mx7DSqBtVjaTkn9h0zATzXLDkmP4SAUVj
     cZ83WDpFre5WnizZjdXlBMM5OCexp5WpmzyHLTnaBFK4jEmnsk5C2Rnoyp8Ivz6g
     Ecg1tRbEXijRw++d2TFYlJwLKtiJASIEEAECAAwFAktKMicFAwASdQAACgkQlxC4
     m8pXrXxqHQgAuYY5scKrh0m/GS9EYnyC9494lOlO6iytU0CpE6oBC31M3hfX/Dbj
     UbcS5szZNU+2CPYo4ujQLZ7suN7+tTjG6pZFfMevajT9+jsL+NPMF8RLdLOVYmbl
     TmSQGNO+XGEYaKYH5oZIeIW5AKCgi2ozkdFlBBLAx7Kqo/FyybhkURFEcvEyVmgf
     3KLV7IIiX/fYLfoCMCJ/Lcm9/llSFB1n8Nvg66Xd533DKoHjueD3jyaNAVlo2mq/
     sIAv++kntvOiB3GDK5pfwHZ78WWiCpsWZpE5gzAnzJ1Y0WEigRo0PVLu3cLO0jLG
     23d+H/CbfZ8rkajHJeCDQF7YVmP0t0nYpYkBIgQQAQIADAUCS1v+ZgUDABJ1AAAK
     CRCXELibyletfNS/CACqt2TkB86mjqM+cJ74+dWBvJ2aFuURuxzm95i9Q/W/hU08
     2iMbC3+0k2oD8CrTOe61P+3oRyLjv/UEDUNzLncNe2YsA9JeV+4hvPwH5Vp3Om13
     089fCKZUbqslXNKkHiWYU+zAaZJXEuGRmRz0HbQIeAMOWF4oa226uo1e4ws1Jhc+
     F3E/ApCRyFBqBUdL05hapQLditYpsBjIdiBGpjzidMLE2wX2W4ZpAdN0U6BIyIqR
     mTPjbSkvzS9kSWFmfhQgnBDKEYJpVZgE1sN52rYC1sDeGeiuKxlzjVov9MMhYMWa
     Zo3R5o3F2iIM/BK6FbC252lf/Mhu3ICuXujNBZNYiQEiBBABAgAMBQJLbSH4BQMA
     EnUAAAoJEJcQuJvKV618kd0IAJLLwDH6gvgAlBFklQJXqQxUdcSOOVMAWtlHgWOy
     ozjgomZZBkRL8dtCDr9YBMcj5czcQ3qpmLJdppXhKB+kJV2iUXfDMSFXwJ4wLfIs
     8FNnXw8H5U01oBkGH/Ku6ngL9Vwt+MjYHtCWkw9QueUKZnDudX9qIzLAIt+mwSTu
     A6+fY4VWIg40AA0v3exaQM55YR/UhlKunpGG9o8Qkq77dMEbTMpOmBoLbOMRB3Dd
     MAvVU6G2l6Pcb7KobVCuOBnb6batXARV/G8sw+nzfJ16fr/KobZT2A6m+Jrqk4dl
     F14ljLbz16O5JGUPAryN2G2ddBdSAy7dtFSVhWWiWC9n88q5Ag0EPj6jHRAIAO/h
     iX8WzHWOMLJT54x/axeDdqn1rBDf5cWmaCWHN2ujNNlgpx5emoU9v7QStsNUCOGB
     bXkeO4Ar7YG+jtSR33zqNh3y5kQ0YkY3dQ0wh6nsl+wh4XIIY/3TUZVtmdJeUBRH
     JlfVNFYad2hX1guFI37Ny1PoZAFsxO82g+XB/Se8r/+sbmVcONdcdIeFKrE3FjLt
     IjNQcxC6l9Q2Oy8KDxG/zvUZG3+H5i3tdRMyGgmuD6gEV0GXOHYUopzLeit1+Aa0
     bCk36Mwbu+BeOw/CJW3+b0mB27hOaf9aCA855IP6fJFvtxcblq8nHIqhU3Dc9tec
     sl9/S1xZ5S8ylG/xeRsAAwUH/i8KqmvAhq0X7DgCcYputwh37cuZlHOa1Ep07JRm
     BCDgkdQXkGrsj2Wzw7Aw/TGdWWkmn2pxb8BRui5cfcZFO7c6vryi6FpJuLucX975
     +eVY50ndWkPXkJ1HF4i+HJwRqE2zliN/RHMs4LJcwXQvvjD43EE3AO6eiVFbD+qA
     AdxUFoOeLblKNBHPG7DPG9xL+Ni5rkE+TXShxsB7F0z7ZdJJZOG0JODmox7IstQT
     GoaU9u41oyZTIiXPiFidJoIZCh7fdurP8pn3X+R5HUNXMr7M+ba8lSNxce/F3kmH
     0L7rsKqdh9d/aVxhJINJ+inVDnrXWVoXu9GBjT8Nco1iU9SIVAQYEQIADAUCTnc9
     7QUJE/sBuAASB2VHUEcAAQEJEIxxjTtQcuH1FJsAmwWK9vmwRJ/y9gTnJ8PWf0BV
     roUTAKClYAhZuX2nUNwH4vlEJQHDqYa5yQ==
     =HfUN
     -----END PGP PUBLIC KEY BLOCK-----

To import the build key into your personal public GPG keyring, use 'gpg
--import'.  For example, if you have saved the key in a file named
'mysql_pubkey.asc', the import command looks like this:

     shell> gpg --import mysql_pubkey.asc
     gpg: key 5072E1F5: public key "MySQL Release Engineering
     <mysql-build@oss.oracle.com>" imported
     gpg: Total number processed: 1
     gpg:               imported: 1
     gpg: no ultimately trusted keys found

You can also download the key from the public keyserver using the public
key id, '5072E1F5':

     shell> gpg --recv-keys 5072E1F5
     gpg: requesting key 5072E1F5 from hkp server keys.gnupg.net
     gpg: key 5072E1F5: "MySQL Release Engineering <mysql-build@oss.oracle.com>"
     1 new user ID
     gpg: key 5072E1F5: "MySQL Release Engineering <mysql-build@oss.oracle.com>"
     53 new signatures
     gpg: no ultimately trusted keys found
     gpg: Total number processed: 1
     gpg:           new user IDs: 1
     gpg:         new signatures: 53

If you want to import the key into your RPM configuration to validate
RPM install packages, you should be able to import the key directly:

     shell> rpm --import mysql_pubkey.asc

If you experience problems or require RPM specific information, see
checking-rpm-signature.

After you have downloaded and imported the public build key, download
your desired MySQL package and the corresponding signature, which also
is available from the download page.  The signature file has the same
name as the distribution file with an '.asc' extension, as shown by the
examples in the following table.

*MySQL Package and Signature Files for Source files*

File Type          File Name

Distribution       'mysql-standard-5.7.23-linux-i686.tar.gz'
file

Signature file     'mysql-standard-5.7.23-linux-i686.tar.gz.asc'

Make sure that both files are stored in the same directory and then run
the following command to verify the signature for the distribution file:

     shell> gpg --verify PACKAGE_NAME.asc

If the downloaded package is valid, you will see a "Good signature"
similar to:

     shell> gpg --verify mysql-standard-5.7.23-linux-i686.tar.gz.asc
     gpg: Signature made Tue 01 Feb 2011 02:38:30 AM CST using DSA key ID 5072E1F5
     gpg: Good signature from "MySQL Release Engineering <mysql-build@oss.oracle.com>"

The 'Good signature' message indicates that the file signature is valid,
when compared to the signature listed on our site.  But you might also
see warnings, like so:

     shell> gpg --verify mysql-standard-5.7.23-linux-i686.tar.gz.asc
     gpg: Signature made Wed 23 Jan 2013 02:25:45 AM PST using DSA key ID 5072E1F5
     gpg: checking the trustdb
     gpg: no ultimately trusted keys found
     gpg: Good signature from "MySQL Release Engineering <mysql-build@oss.oracle.com>"
     gpg: WARNING: This key is not certified with a trusted signature!
     gpg:          There is no indication that the signature belongs to the owner.
     Primary key fingerprint: A4A9 4068 76FC BD3C 4567  70C8 8C71 8D3B 5072 E1F5

That is normal, as they depend on your setup and configuration.  Here
are explanations for these warnings:

   * _gpg: no ultimately trusted keys found_: This means that the
     specific key is not "ultimately trusted" by you or your web of
     trust, which is okay for the purposes of verifying file signatures.

   * _WARNING: This key is not certified with a trusted signature!
     There is no indication that the signature belongs to the owner._:
     This refers to your level of trust in your belief that you possess
     our real public key.  This is a personal decision.  Ideally, a
     MySQL developer would hand you the key in person, but more
     commonly, you downloaded it.  Was the download tampered with?
     Probably not, but this decision is up to you.  Setting up a web of
     trust is one method for trusting them.

See the GPG documentation for more information on how to work with
public keys.

2.1.3.3 Signature Checking Using Gpg4win for Windows
....................................................

The checking-gpg-signature section describes how to verify MySQL
downloads using GPG. That guide also applies to Microsoft Windows, but
another option is to use a GUI tool like Gpg4win
(http://www.gpg4win.org/).  You may use a different tool but our
examples are based on Gpg4win, and utilize its bundled 'Kleopatra' GUI.

Download and install Gpg4win, and then load Kleopatra.  The dialog
should look similar to:

FIGURE GOES HERE: Kleopatra: Initial Screen

Next, add the MySQL Release Engineering certificate.  Do this by
clicking 'File', 'Lookup Certificates on Server'.  Type "Mysql Release
Engineering" into the search box and press 'Search'.

FIGURE GOES HERE: Kleopatra: Lookup Certificates on Server Wizard:
Finding a Certificate

Select the "MySQL Release Engineering" certificate.  The Fingerprint and
Key-ID must be "5072E1F5", or choose 'Details...' to confirm the
certificate is valid.  Now, import it by clicking 'Import'.  An import
dialog will be displayed, choose 'Okay', and this certificate will now
be listed under the 'Imported Certificates' tab.

Next, configure the trust level for our certificate.  Select our
certificate, then from the main menu select 'Certificates', 'Change
Owner Trust...'.  We suggest choosing 'I believe checks are very
accurate' for our certificate, as otherwise you might not be able to
verify our signature.  Select 'I believe checks are very accurate' to
enable "full trust" and then press 'OK'.

FIGURE GOES HERE: Kleopatra: Change Trust level for MySQL Release
Engineering

Next, verify the downloaded MySQL package file.  This requires files for
both the packaged file, and the signature.  The signature file must have
the same name as the packaged file but with an appended '.asc'
extension, as shown by the example in the following table.  The
signature is linked to on the downloads page for each MySQL product.
You must create the '.asc' file with this signature.

*MySQL Package and Signature Files for MySQL Installer for Microsoft
Windows*

File Type          File Name

Distribution       'mysql-installer-community-5.7.23.msi'
file

Signature file     'mysql-installer-community-5.7.23.msi.asc'

Make sure that both files are stored in the same directory and then run
the following command to verify the signature for the distribution file.
Either drag and drop the signature ('.asc') file into Kleopatra, or load
the dialog from 'File', 'Decrypt/Verify Files...', and then choose
either the '.msi' or '.asc' file.

FIGURE GOES HERE: Kleopatra: The Decrypt and Verify Files Dialog

Click 'Decrypt/Verify' to check the file.  The two most common results
will look like the following, and although the yellow warning looks
problematic, the following means that the file check passed with
success.  You may now run this installer.

FIGURE GOES HERE: Kleopatra: the Decrypt and Verify Results Dialog: All
operations completed

Seeing a red "The signature is bad" error means the file is invalid.  Do
not execute the MSI file if you see this error.

FIGURE GOES HERE: Kleopatra: the Decrypt and Verify Results Dialog: Bad

The checking-gpg-signature section explains why you probably
don't see a green 'Good signature' result.

2.1.3.4 Signature Checking Using RPM
....................................

For RPM packages, there is no separate signature.  RPM packages have a
built-in GPG signature and MD5 checksum.  You can verify a package by
running the following command:

     shell> rpm --checksig PACKAGE_NAME.rpm

Example:

     shell> rpm --checksig MySQL-server-5.7.23-0.linux_glibc2.5.i386.rpm
     MySQL-server-5.7.23-0.linux_glibc2.5.i386.rpm: md5 gpg OK

*Note*:

If you are using RPM 4.1 and it complains about '(GPG) NOT OK (MISSING
KEYS: GPG#5072e1f5)', even though you have imported the MySQL public
build key into your own GPG keyring, you need to import the key into the
RPM keyring first.  RPM 4.1 no longer uses your personal GPG keyring (or
GPG itself).  Rather, RPM maintains a separate keyring because it is a
system-wide application and a user's GPG public keyring is a
user-specific file.  To import the MySQL public key into the RPM
keyring, first obtain the key, then use 'rpm --import' to import the
key.  For example:

     shell> gpg --export -a 5072e1f5 > 5072e1f5.asc
     shell> rpm --import 5072e1f5.asc

Alternatively, 'rpm' also supports loading the key directly from a URL,
and you can use this manual page:

     shell> rpm --import http://dev.mysql.com/doc/refman/5.7/en/checking-gpg-signature.html

If you need to obtain the MySQL public key, see
checking-gpg-signature.

2.1.4 Installation Layouts
--------------------------

The installation layout differs for different installation types (for
example, native packages, binary tarballs, and source tarballs), which
can lead to confusion when managing different systems or using different
installation sources.  The individual layouts are given in the
corresponding installation type or platform chapter, as described
following.  Note that the layout of installations from vendors other
than Oracle may differ from these layouts.

   * windows-installation-layout

   * source-installation-layout

   * binary-installation-layout

   * mysql-installation-layout-linuxrpm

   * mysql-installation-layout-osx

2.1.5 Compiler-Specific Build Characteristics
---------------------------------------------

In some cases, the compiler used to build MySQL affects the features
available for use.  The notes in this section apply for binary
distributions provided by Oracle Corporation or that you compile
yourself from source.

*'icc' (Intel C++ Compiler) Builds*

A server built with 'icc' has these characteristics:

   * SSL support is not included.

2.2 Installing MySQL on Unix/Linux Using Generic Binaries
=========================================================

Oracle provides a set of binary distributions of MySQL. These include
generic binary distributions in the form of compressed 'tar' files
(files with a '.tar.gz' extension) for a number of platforms, and
binaries in platform-specific package formats for selected platforms.

This section covers the installation of MySQL from a compressed 'tar'
file binary distribution on Unix/Linux platforms.  For other
platform-specific binary package formats, see the other
platform-specific sections in this manual.  For example, for Windows
distributions, see windows-installation.  See
getting-mysql on how to obtain MySQL in different distribution
formats.

MySQL compressed 'tar' file binary distributions have names of the form
'mysql-VERSION-OS.tar.gz', where 'VERSION' is a number (for example,
'5.7.23'), and OS indicates the type of operating system for which the
distribution is intended (for example, 'pc-linux-i686' or 'winx64').

*Warning*:

If you have previously installed MySQL using your operating system
native package management system, such as Yum or APT, you may experience
problems installing using a native binary.  Make sure your previous
MySQL installation has been removed entirely (using your package
management system), and that any additional files, such as old versions
of your data files, have also been removed.  You should also check for
configuration files such as '/etc/my.cnf' or the '/etc/mysql' directory
and delete them.

For information about replacing third-party packages with official MySQL
packages, see the related APT guide
(http://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/) or Yum guide.

*Important*:

   * MySQL has a dependency on the 'libaio' library.  Data directory
     initialization and subsequent server startup steps will fail if
     this library is not installed locally.  If necessary, install it
     using the appropriate package manager.  For example, on Yum-based
     systems:

          shell> YUM SEARCH LIBAIO  # search for info
          shell> YUM INSTALL LIBAIO # install library

     Or, on APT-based systems:

          shell> APT-CACHE SEARCH LIBAIO # search for info
          shell> APT-GET INSTALL LIBAIO1 # install library

   * _For MySQL 5.7.19 and later:_ Support for Non-Uniform Memory Access
     (NUMA) has been added to the generic Linux build, which has a
     dependency now on the 'libnuma' library; if the library has not
     been installed on your system, use you system's package manager to
     search for and install it (see the last bullet for some sample
     commands).

To install a compressed 'tar' file binary distribution, unpack it at the
installation location you choose (typically '/usr/local/mysql').  This
creates the directories shown in the following table.

*MySQL Installation Layout for Generic Unix/Linux Binary Package*

Directory                        Contents of Directory

'bin'                            'mysqld' server, client
                                 and utility programs

'docs'                           MySQL manual in Info format

'man'                            Unix manual pages

'include'                        Include (header) files

'lib'                            Libraries

'share'                          Error messages, dictionary, and SQL
                                 for database installation

'support-files'                  Miscellaneous support files

*Note*:

*SLES 11*: as of MySQL 5.7.19, the Linux Generic tarball package format
is EL6 instead of EL5.  As a side effect, the MySQL client bin/mysql
needs libtinfo.so.5.

A workaround is to create a symlink, such as _ln -s libncurses.so.5.6
/lib64/libtinfo.so.5_ on 64-bit systems or _ln -s libncurses.so.5.6
/lib/libtinfo.so.5_ on 32-bit systems.

Debug versions of the 'mysqld' binary are available as
'mysqld-debug'.  To compile your own debug version of
MySQL from a source distribution, use the appropriate configuration
options to enable debugging support.  See source-installation.

To install and use a MySQL binary distribution, the command sequence
looks like this:

     shell> groupadd mysql
     shell> useradd -r -g mysql -s /bin/false mysql
     shell> cd /usr/local
     shell> tar zxvf /PATH/TO/MYSQL-VERSION-OS.tar.gz
     shell> ln -s FULL-PATH-TO-MYSQL-VERSION-OS mysql
     shell> cd mysql
     shell> mkdir mysql-files
     shell> chown mysql:mysql mysql-files
     shell> chmod 750 mysql-files
     shell> bin/mysqld --initialize --user=mysql
     shell> bin/mysql_ssl_rsa_setup
     shell> bin/mysqld_safe --user=mysql &
     # Next command is optional
     shell> cp support-files/mysql.server /etc/init.d/mysql.server

*Note*:

This procedure assumes that you have 'root' (administrator) access to
your system.  Alternatively, you can prefix each command using the
'sudo' (Linux) or 'pfexec' (Solaris) command.

The 'mysql-files' directory provides a convenient location to use as the
value for the 'secure_file_priv' system variable, which limits import
and export operations to a specific directory.  See
server-system-variables.

A more detailed version of the preceding description for installing a
binary distribution follows.

*Create a mysql User and Group*

If your system does not already have a user and group to use for running
'mysqld', you may need to create them.  The following
commands add the 'mysql' group and the 'mysql' user.  You might want to
call the user and group something else instead of 'mysql'.  If so,
substitute the appropriate name in the following instructions.  The
syntax for 'useradd' and 'groupadd' may differ slightly on different
versions of Unix/Linux, or they may have different names such as
'adduser' and 'addgroup'.

     shell> groupadd mysql
     shell> useradd -r -g mysql -s /bin/false mysql

*Note*:

Because the user is required only for ownership purposes, not login
purposes, the 'useradd' command uses the '-r' and '-s /bin/false'
options to create a user that does not have login permissions to your
server host.  Omit these options if your 'useradd' does not support
them.

*Obtain and Unpack the Distribution*

Pick the directory under which you want to unpack the distribution and
change location into it.  The example here unpacks the distribution
under '/usr/local'.  The instructions, therefore, assume that you have
permission to create files and directories in '/usr/local'.  If that
directory is protected, you must perform the installation as 'root'.

     shell> cd /usr/local

Obtain a distribution file using the instructions in
getting-mysql.  For a given release, binary distributions for all
platforms are built from the same MySQL source distribution.

Unpack the distribution, which creates the installation directory.
'tar' can uncompress and unpack the distribution if it has 'z' option
support:

     shell> tar zxvf /PATH/TO/MYSQL-VERSION-OS.tar.gz

The 'tar' command creates a directory named 'mysql-VERSION-OS'.

To install MySQL from a compressed 'tar' file binary distribution, your
system must have GNU 'gunzip' to uncompress the distribution and a
reasonable 'tar' to unpack it.  If your 'tar' program supports the 'z'
option, it can both uncompress and unpack the file.

GNU 'tar' is known to work.  The standard 'tar' provided with some
operating systems is not able to unpack the long file names in the MySQL
distribution.  You should download and install GNU 'tar', or if
available, use a preinstalled version of GNU tar.  Usually this is
available as 'gnutar', 'gtar', or as 'tar' within a GNU or Free Software
directory, such as '/usr/sfw/bin' or '/usr/local/bin'.  GNU 'tar' is
available from <http://www.gnu.org/software/tar/>.

If your 'tar' does not have 'z' option support, use 'gunzip' to unpack
the distribution and 'tar' to unpack it.  Replace the preceding 'tar'
command with the following alternative command to uncompress and extract
the distribution:

     shell> gunzip < /PATH/TO/MYSQL-VERSION-OS.tar.gz | tar xvf -

Next, create a symbolic link to the installation directory created by
'tar':

     shell> ln -s FULL-PATH-TO-MYSQL-VERSION-OS mysql

The 'ln' command makes a symbolic link to the installation directory.
This enables you to refer more easily to it as '/usr/local/mysql'.  To
avoid having to type the path name of client programs always when you
are working with MySQL, you can add the '/usr/local/mysql/bin' directory
to your 'PATH' variable:

     shell> export PATH=$PATH:/usr/local/mysql/bin

*Perform Postinstallation Setup*

The remainder of the installation process involves setting distribution
ownership and access permissions, initializing the data directory,
starting the MySQL server, and setting up the configuration file.  For
instructions, see postinstallation.

2.3 Installing MySQL on Microsoft Windows
=========================================

*Important*:

MySQL Community 5.7 Server requires the Microsoft Visual C++ 2013
Redistributable Package to run on Windows platforms.  Users should make
sure the package has been installed on the system before installing the
server.  The package is available at the Microsoft Download Center
(http://www.microsoft.com/en-us/download/default.aspx).

MySQL is available for Microsoft Windows, for both 32-bit and 64-bit
versions.  For supported Windows platform information, see
<http://www.mysql.com/support/supportedplatforms/database.html>.

*Important*:

If your operating system is Windows 2008 R2 or Windows 7 and you do not
have Service Pack 1 (SP1) installed, MySQL 5.7 will regularly restart
and in the MySQL server error log file you will see this message:

     mysqld got exception 0xc000001d

This error message occurs because you are also using a CPU that does not
support the VPSRLQ instruction and indicates that the CPU instruction
that was attempted is not supported.

To fix this error, you _must_ install SP1.  This adds the required
operating system support for the CPU capability detection and disables
that support when the CPU does not have the required instructions.

Alternatively, install an older version of MySQL, such as 5.6.

There are different methods to install MySQL on Microsoft Windows.

*MySQL Installer Method*

The simplest and recommended method is to download MySQL Installer (for
Windows) and let it install and configure all of the MySQL products on
your system.  Here is how:

  1. Download MySQL Installer from
     <http://dev.mysql.com/downloads/installer/> and execute it.

     *Note*:

     Unlike the standard MySQL Installer, the smaller "web-community"
     version does not bundle any MySQL applications but it will download
     the MySQL products you choose to install.

  2. Choose the appropriate 'Setup Type' for your system.  Typically you
     will choose 'Developer Default' to install MySQL server and other
     MySQL tools related to MySQL development, helpful tools like MySQL
     Workbench.  Or, choose the 'Custom' setup type to manually select
     your desired MySQL products.

     *Note*:

     Multiple versions of MySQL server can exist on a single system.
     You can choose one or multiple versions.

  3. Complete the installation process by following the instructions.
     This will install several MySQL products and start the MySQL
     server.

MySQL is now installed.  If you configured MySQL as a service, then
Windows will automatically start MySQL server every time you restart
your system.

*Note*:

You probably also installed other helpful MySQL products like MySQL
Workbench and MySQL Notifier on your system.  Consider loading
workbench to check your new MySQL server connection, and
windows-notifier to view the connection's status.  By default, these
two programs automatically start after installing MySQL.

This process also installs the MySQL Installer application on your
system, and later you can use MySQL Installer to upgrade or reconfigure
your MySQL products.

*Additional Installation Information*

It is possible to run MySQL as a standard application or as a Windows
service.  By using a service, you can monitor and control the operation
of the server through the standard Windows service management tools.
For more information, see windows-start-service.

Generally, you should install MySQL on Windows using an account that has
administrator rights.  Otherwise, you may encounter problems with
certain operations such as editing the 'PATH' environment variable or
accessing the 'Service Control Manager'.  When installed, MySQL does not
need to be executed using a user with Administrator privileges.

For a list of limitations on the use of MySQL on the Windows platform,
see limits-windows.

In addition to the MySQL Server package, you may need or want additional
components to use MySQL with your application or development
environment.  These include, but are not limited to:

   * To connect to the MySQL server using ODBC, you must have a
     Connector/ODBC driver.  For more information, including
     installation and configuration instructions, see MySQL
     Connector/ODBC Developer Guide
     (http://dev.mysql.com/doc/connector-odbc/en/).

     *Note*:

     MySQL Installer will install and configure Connector/ODBC for you.

   * To use MySQL server with .NET applications, you must have the
     Connector/Net driver.  For more information, including installation
     and configuration instructions, see MySQL Connector/Net Developer
     Guide (http://dev.mysql.com/doc/connector-net/en/).

     *Note*:

     MySQL Installer will install and configure MySQL Connector/Net for
     you.

MySQL distributions for Windows can be downloaded from
<http://dev.mysql.com/downloads/>.  See getting-mysql.

MySQL for Windows is available in several distribution formats, detailed
here.  Generally speaking, you should use MySQL Installer.  It contains
more features and MySQL products than the older MSI, is simpler to use
than the compressed file, and you need no additional tools to get MySQL
up and running.  MySQL Installer automatically installs MySQL Server and
additional MySQL products, creates an options file, starts the server,
and enables you to create default user accounts.  For more information
on choosing a package, see windows-choosing-package.

   * A MySQL Installer distribution includes MySQL Server and additional
     MySQL products including MySQL Workbench, MySQL Notifier, and MySQL
     for Excel.  MySQL Installer can also be used to upgrade these
     products in the future.

     For instructions on installing MySQL using MySQL Installer, see
     mysql-installer.

   * The standard binary distribution (packaged as a compressed file)
     contains all of the necessary files that you unpack into your
     chosen location.  This package contains all of the files in the
     full Windows MSI Installer package, but does not include an
     installation program.

     For instructions on installing MySQL using the compressed file, see
     windows-install-archive.

   * The source distribution format contains all the code and support
     files for building the executables using the Visual Studio compiler
     system.

     For instructions on building MySQL from source on Windows, see
     source-installation.

*MySQL on Windows Considerations*

   * *Large Table Support*

     If you need tables with a size larger than 4GB, install MySQL on an
     NTFS or newer file system.  Do not forget to use 'MAX_ROWS' and
     'AVG_ROW_LENGTH' when you create tables.  See create-table.

   * *MySQL and Virus Checking Software*

     Virus-scanning software such as Norton/Symantec Anti-Virus on
     directories containing MySQL data and temporary tables can cause
     issues, both in terms of the performance of MySQL and the
     virus-scanning software misidentifying the contents of the files as
     containing spam.  This is due to the fingerprinting mechanism used
     by the virus-scanning software, and the way in which MySQL rapidly
     updates different files, which may be identified as a potential
     security risk.

     After installing MySQL Server, it is recommended that you disable
     virus scanning on the main directory ('datadir') used to store your
     MySQL table data.  There is usually a system built into the
     virus-scanning software to enable specific directories to be
     ignored.

     In addition, by default, MySQL creates temporary files in the
     standard Windows temporary directory.  To prevent the temporary
     files also being scanned, configure a separate temporary directory
     for MySQL temporary files and add this directory to the virus
     scanning exclusion list.  To do this, add a configuration option
     for the 'tmpdir' parameter to your 'my.ini' configuration file.
     For more information, see windows-create-option-file.

   * *Running MySQL on a 4K Sector Hard Drive*

     Running the MySQL server on a 4K sector hard drive on Windows is
     not supported with 'innodb_flush_method=async_unbuffered', which is
     the default setting.  The workaround is to use
     'innodb_flush_method=normal'.

2.3.1 MySQL Installation Layout on Microsoft Windows
----------------------------------------------------

For MySQL 5.7 on Windows, the default installation directory is
'C:\Program Files\MySQL\MySQL Server 5.7' for installations performed
with MySQL Installer.  If you use the ZIP archive method to install
MySQL, you may prefer to install in 'C:\mysql'.  However, the layout of
the subdirectories remains the same.

All of the files are located within this parent directory, using the
structure shown in the following table.

*Default MySQL Installation Layout for Microsoft Windows*

Directory              Contents of Directory         Notes

'bin'                  'mysqld'.
                       server, client and utility
                       programs

'%PROGRAMDATA%\MySQL\MySQLLog files, databases       The Windows system
Server 5.7\'                                         variable
                                                     %PROGRAMDATA%
                                                     defaults to
                                                     'C:\ProgramData'.

'docs'                 Release documentation         With MySQL
                                                     Installer, use the
                                                     'Modify' operation
                                                     to select this
                                                     optional folder.

'include'              Include (header) files

'lib'                  Libraries

'share'                Miscellaneous support
                       files, including error
                       messages, character set
                       files, sample configuration
                       files, SQL for database
                       installation

2.3.2 Choosing an Installation Package
--------------------------------------

For MySQL 5.7, there are multiple installation package formats to choose
from when installing MySQL on Windows.

*Note*:

Program Database (PDB) files (with file name extension 'pdb') provide
information for debugging your MySQL installation in the event of a
problem.  These files are included in ZIP Archive distributions (but not
MSI distributions) of MySQL.

   * *MySQL Installer*: This package has a file name similar to
     'mysql-installer-community-5.7.23.0.msi' or
     'mysql-installer-commercial-5.7.23.0.msi', and utilizes MSIs to
     automatically install MySQL server and other products.  It will
     download and apply updates to itself, and for each of the installed
     products.  It also configures the installed MySQL server (including
     InnoDB Cluster Sandbox test setups) and MySQL Router.

     MySQL Installer can install and manage (add, modify, upgrade, and
     remove) many other MySQL products, including:

        * Applications - MySQL Workbench, MySQL for Visual Studio, MySQL
          Notifier, MySQL for Excel, MySQL Utilities, MySQL Shell, MySQL
          Router

        * Connectors - MySQL Connector/C, MySQL Connector/C++, MySQL
          Connector/Net, Connector/ODBC, MySQL Connector/Python, MySQL
          Connector/J, MySQL Connector/Node.js

        * Documentation - MySQL Manual (PDF format), samples and
          examples

     *Note*:

     As of MySQL 5.7.8, MySQL Installer no longer includes debugging
     binaries/information components (including PDB files).  These are
     available in a separate ZIP archive named
     'mysql-VERSION-winx64-debug-test.zip' for 64-bit and
     'mysql-VERSION-win32-debug-test.zip' for 32-bit.

     MySQL Installer operates on all MySQL supported versions of Windows
     (see
     <http://www.mysql.com/support/supportedplatforms/database.html>).

     *Note*:

     Because MySQL Installer is not a native component of Microsoft
     Windows and depends on .NET, it will not work on minimal
     installation options like the "Server Core" version of Windows
     Server 2008.

     For instructions on installing MySQL using MySQL Installer, see
     mysql-installer.

   * *The 'noinstall' ZIP Archives*: These packages contain the files
     found in the complete installation package, with the exception of
     the GUI. This format does not include an automated installer, and
     must be manually installed and configured.

     *Note*:

     As of MySQL 5.7.6, 'noinstall' ZIP archives are split into two
     separate compressed files.  The main package is named
     'mysql-VERSION-winx64.zip' for 64-bit and 'mysql-VERSION-win32.zip'
     for 32-bit.  This contains the components needed to use MySQL on
     your system.  The optional MySQL test suite, MySQL benchmark suite,
     and debugging binaries/information components (including PDB files)
     are in a separate compressed file named
     'mysql-VERSION-winx64-debug-test.zip' for 64-bit and
     'mysql-VERSION-win32-debug-test.zip' for 32-bit.

     Before MySQL 5.7.6, a single 'noinstall' ZIP archive contained both
     the main and debugging files.

MySQL Installer is recommended for most users.

Your choice of install package affects the installation process you must
follow.  If you choose to use MySQL Installer, see
mysql-installer.  If you choose to install a 'noinstall' ZIP archive,
see windows-install-archive.

2.3.3 MySQL Installer for Windows
---------------------------------

MySQL Installer is a standalone application designed to ease the
complexity of installing and managing MySQL products that run on
Microsoft Windows.  It supports the following MySQL products:

   * MySQL Servers

     MySQL Installer can install and manage multiple, separate MySQL
     server instances on the same host at the same time.  For example,
     MySQL Installer can install, configure, and upgrade a separate
     instance of MySQL 5.6, MySQL 5.7, and MySQL 8.0 on the same host.
     MySQL Installer does not permit server upgrades between major and
     minor version numbers, but does permit upgrades within a release
     series (such as 5.7.18 to 5.7.19).

     A host _cannot_ have both community and commercial editions of
     MySQL server installed.

   * MySQL Applications

     MySQL Workbench, MySQL Shell, MySQL Router, MySQL for Visual
     Studio, MySQL for Excel, MySQL Notifier, and MySQL Utilities.

   * MySQL Connectors

     MySQL Connector/Net, MySQL Connector/Python, MySQL
     Connector/Node.js MySQL Connector/ODBC, MySQL Connector/J, MySQL
     Connector/C, and MySQL Connector/C++.

   * Documentation and Samples

     MySQL Reference Manuals (by version) in PDF format and MySQL
     database samples (by version).

*Installation Requirements*

MySQL Installer requires Microsoft .NET Framework 4.5.2 or later.  If
this version is not installed on the host computer, you can download it
by visiting the Microsoft web site
(https://www.microsoft.com/en-us/download/details.aspx?id=42643).

*MySQL Installer Community Edition*

Download this edition from <http://dev.mysql.com/downloads/installer/>
to install the community version of all MySQL products for Windows.
Select one of the following MySQL Installer package options:

   * _Web:_ Contains MySQL Installer and configuration files only.  The
     web package downloads only the MySQL products you select to
     install, but it requires an internet connection for each download.
     The size of this file is approximately 2 MB; the name of the file
     has the form 'mysql-installer-community-web-VERSION.N.msi' where
     'VERSION' is the MySQL server version number such as 8.0 and 'N' is
     the package number, which begins at 0.

   * _Full:_ Bundles all of the MySQL products for Windows (including
     the MySQL server).  The file size is over 300 MB, and its name has
     the form 'mysql-installer-community-VERSION.N.msi' where 'VERSION'
     is the MySQL Server version number such as 8.0 and 'N' is the
     package number, which begins at 0.

*MySQL Installer Commercial Edition*

Download this edition from <https://edelivery.oracle.com/> to install
the commercial edition of all MySQL products for Windows.  The
Commercial Edition includes all of the products in the Community Edition
and also includes the following products:

   * Workbench SE/EE

   * MySQL Enterprise Backup

   * MySQL Enterprise Firewall

This edition integrates with your My Oracle Support (MOS) account.  For
knowledge-base content and patches, see My Oracle Support
(https://support.oracle.com/).

2.3.3.1 MySQL Installer Initial Setup
.....................................

   * setup-license

   * setup-type

   * setup-conflicts

   * setup-requirements

   * setup-layout

When you download MySQL Installer for the first time, a setup wizard
guides you through the initial installation of MySQL products.  As the
following figure shows, the initial setup is a one-time activity in the
overall process.  MySQL Installer detects existing MySQL products
installed on the host during its initial setup and adds them to the list
of products to be managed.

FIGURE GOES HERE: MySQL Installer Process Overview

MySQL Installer extracts configuration files (described later) to the
hard drive of the host during the initial setup.  Although MySQL
Installer is a 32-bit application, it can install both 32-bit and 64-bit
binaries.

The initial setup adds a link to the Start menu under the 'MySQL' group.
Click 'Start', 'All Programs', 'MySQL', 'MySQL Installer' to open MySQL
Installer.

*MySQL Installer Licensing and Support Authentication*

MySQL Installer requires you to accept the license agreement before it
will install new MySQL packages.  After you accept the terms of the
agreement, you can add, update, reconfigure, and remove all of the
products and features provided by the MySQL Installer edition you
downloaded.

For the commercial edition, entering your My Oracle Support (MOS)
credentials is optional when installing bundled MySQL products, but your
credentials are required when choosing unbundled MySQL products that
MySQL Installer must download.  An unbundled product is any MSI file
that you download using MySQL Installer after the initial setup.  Your
credentials must match the user name and password that you have
registered with Oracle for access to the support site.

*Choosing a Setup Type*

During the initial setup, you are prompted to select the MySQL products
to be installed on the host.  One alternative is to use a predetermined
setup type that matches your setup requirements.  By default, both GA
and pre-release products are included in the download and installation
with the 'Developer Default', 'Client only', and 'Full' setup types.
Select the 'Only install GA products' option to restrict the product set
to include GA products only when using these setup types.

Choosing one of the following setup types determines the initial
installation only and does not limit your ability to install or update
MySQL products for Windows later:

   * 'Developer Default': Install the following products that compliment
     application development with MySQL:

        * MySQL Server (http://dev.mysql.com/doc/) (Installs the version
          that you selected when you downloaded MySQL Installer.)

        * MySQL Shell.

        * MySQL Router (http://dev.mysql.com/doc/mysql-router/2.1/en/)

        * MySQL Workbench.

        * MySQL for Visual Studio
          (http://dev.mysql.com/doc/visual-studio/en/)

        * MySQL for Excel (http://dev.mysql.com/doc/mysql-for-excel/en/)

        * MySQL Notifier.

        * MySQL Connectors
          (http://dev.mysql.com/doc/index-connectors.html) (.NET /
          Python / ODBC / Java / C / C++)

        * MySQL Utilities
          (http://dev.mysql.com/doc/mysql-utilities/1.5/en/)

        * MySQL Documentation

        * MySQL Samples and Examples

   * *Server only*: Only install the MySQL server.  This setup type
     installs the general availability (GA) or development release
     server that you selected when you downloaded MySQL Installer.  It
     uses the default installation and data paths.

   * *Client only*: Only install the most recent MySQL applications and
     MySQL connectors.  This setup type is similar to the 'Developer
     Default' type, except that it does not include MySQL server or the
     client programs typically bundled with the server, such as
     'mysql' or 'mysqladmin'.

   * *Full*: Install all available MySQL products.

   * *Custom* The custom setup type enables you to filter and select
     individual MySQL products from the MySQL Installer catalog.

     Use the 'Custom' setup type to install:

        * A product or product version that is not available from the
          usual download locations.  The catalog contains all product
          releases, including the other releases between pre-release (or
          development) and GA.

        * An instance of MySQL server using an alternative installation
          path, data path, or both.  For instructions on how to adjust
          the paths, see mysql-installer-change-path-proc.

        * Two or more MySQL server versions on the same host at the same
          time (for example, 5.6, 5.7, and 8.0).

        * A specific combination of products and features not offered as
          a predetermine setup type.  For example, you can install a
          single product, such as MySQL Workbench, instead of installing
          all client applications for Windows.

*Path Conflicts*

When the default installation or data folder (required by MySQL server)
for a product to be installed already exists on the host, the wizard
displays the 'Path Conflict' step to identify each conflict and enable
you to take action to avoid having files in the existing folder
overwritten by the new installation.  You see this step in the initial
setup only when MySQL Installer detects a conflict.

To resolve the path conflict, do one of the following:

   * Select a product from the list to display the conflict options.  A
     warning symbol indicates which path is in conflict.  Use the browse
     button to choose a new path and then click 'Next'.

   * Click 'Back' to choose a different setup type or product version,
     if applicable.  The 'Custom' setup type enables you to select
     individual product versions.

   * Click 'Next' to ignore the conflict and overwrite files in the
     existing folder.

   * Delete the existing product.  Click 'Cancel' to stop the initial
     setup and close MySQL Installer.  Open MySQL Installer again from
     the Start menu and delete the installed product from the host using
     the Delete operation from the dashboard.

*Check Requirements*

MySQL Installer uses entries in the 'package-rules.xml' file to
determine whether the prerequisite software for each product is
installed on the host.  When the requirements check fails, MySQL
Installer displays the 'Check Requirements' step to help you update the
host.  The following figure identifies and describes the key areas of
this step.

FIGURE GOES HERE: Check Requirements

*Description of Check Requirements Elements*

  1. Shows the current step in the initial setup.  Steps in this list
     may change slightly depending on the products already installed on
     the host, the availability of prerequisite software, and the
     products to be installed on the host.

  2. Lists all pending installation requirements by product and
     indicates the status as follows:

        * A blank space in the 'Status' column means that MySQL
          Installer can attempt to download and install the required
          software for you.

        * The word _Manual_ in the 'Status' column means that you must
          satisfy the requirement manually.  Select each product in the
          list to see its requirement details.

  3. Describes the requirement in detail to assist you with each manual
     resolution.  When possible, a download URL is provided.  After you
     download and install the required software, click 'Check' to verify
     that the requirement has been met.

  4. Provides the following set operations to proceed:

        * 'Back' - Return to the previous step.  This action enables you
          to select a different the setup type.

        * 'Execute' - Have MySQL Installer attempt to download and
          install the required software for all items without a manual
          status.  Manual requirements are resolved by you and verified
          by clicking 'Check'.

        * 'Next' - Do not execute the request to apply the requirements
          automatically and proceed to the installation without
          including the products that fail the check requirements step.

        * 'Cancel' - Stop the installation of MySQL products.  Because
          MySQL Installer is already installed, the initial setup begins
          again when you open MySQL Installer from the Start menu and
          click 'Add' from the dashboard.  For a description of the
          available management operations, see
          windows-product-catalog.

*MySQL Installer Configuration Files*

All MySQL Installer files are located within the 'C:\Program Files
(x86)' and 'C:\ProgramData' folders.  The following table describes the
files and folders that define MySQL Installer as a standalone
application.

*Note*:

Installed MySQL products are neither altered nor removed when you update
or uninstall MySQL Installer.

*MySQL Installer Configuration Files*

File or Folder         Description                   Folder Hierarchy

'MySQL Installer for   This folder contains all of   'C:\Program Files
Windows'               the files needed to run       (x86)'
                       MySQL Installer and
                       MySQLInstallerConsole.exe,
                       a
                       command-line program with
                       similar functionality.

'Templates'            The 'Templates' folder has    'C:\ProgramData\MySQL\MySQL
                       one file for each version     Installer for
                       of MySQL server.  Template    Windows\Manifest'
                       files contain keys and
                       formulas to calculate some
                       values dynamically.

'package-rules.xml'                                  'C:\ProgramData\MySQL\MySQL
                       This file contains the        Installer for
                       prerequisites for every       Windows\Manifest'
                       product to be installed.

'produts.xml'                                        'C:\ProgramData\MySQL\MySQL
                       The 'products' file (or       Installer for
                       product catalog) contains a   Windows\Manifest'
                       list of all products
                       available for download.

'Product Cache'                                      'C:\ProgramData\MySQL\MySQL
                       The 'Product Cache' folder    Installer for
                       contains all standalone MSI   Windows'
                       files bundled with the full
                       package or downloaded
                       afterward.

2.3.3.2 Installation Workflow with MySQL Installer
..................................................

MySQL Installer provides a wizard-like tool to install and configure new
MySQL products for Windows.  Unlike the initial setup, which runs only
once, MySQL Installer invokes the wizard each time you download or
install a new product.  For first-time installations, the steps of the
initial setup proceed directly into the steps of the installation.

*Note*:

Full permissions are granted to the user executing MySQL Installer to
all generated files, such as 'my.ini'.  This does not apply to files and
directories for specific products, such as the MySQL server data
directory in '%ProgramData%' that is owned by 'SYSTEM'.

Products installed and configured on a host follow a general pattern
that might require your input during the various steps.  MySQL Installer
loads all selected products together using the following workflow:

   * Product download.  If you installed the full (not web) MySQL
     Installer package, all MSI files were loaded to the 'Product Cache'
     folder during the initial setup and are not downloaded again.
     Otherwise, the status of each product changes from 'Downloading' to
     'Downloaded'.

   * Product installation.  The status of each product in the list
     changes from 'Ready to Install' to 'Installing' to 'Complete'.
     During the process, click 'Show Details' to view the installation
     actions.

     If you cancel the installation at this point, the products are
     installed, but the server (if installed) is not yet configured.  To
     restart the server configuration, open MySQL Installer from the
     Start menu and click the 'Reconfigure' link next to the appropriate
     server in the dashboard.

   * Product configuration.  This step applies to MySQL server and
     samples in most cases.  The status for each item in the list should
     indicate, 'Ready to Configure'.  Click 'Next' to begin the
     step-by-step configuration of all items in the list.

     The configuration options presented during this step depend on
     which version of the database you selected to install.  After the
     installation completes, you can reconfigure MySQL server from the
     MySQL Installer dashboard.

   * Installation compete.  This step finalizes the installation and
     enables you to start some applications when the installation
     finishes.

2.3.3.3 Group Replication
.........................

You have two options to implement a high-availability solution when you
install MySQL 5.7.17 or higher (64-bit) using MySQL Installer:

   * Standalone MySQL Server / Classic MySQL Replication (default)

     Select this option to begin the initial configuration of a
     standalone MySQL server.  You can configure multiple servers with
     classic MySQL Replication manually or use MySQL Shell 1.0.9 or
     higher to configure a production InnoDB cluster.

     *Note*:

     Existing instance ports (3310 to 3390) set for a sandbox InnoDB
     cluster that was created manually using MySQL Shell, will be
     deleted by MySQL Installer if you later run the sandbox InnoDB
     cluster test setup.

     For a description of the server configuration options that apply to
     a standalone MySQL server on Windows, see
     mysql-installer-workflow-server.

   * Sandbox InnoDB Cluster Test Setup (for testing only)

     Select this option to create and configure sandbox InnoDB cluster
     instances locally for testing.  You can configure a sandbox InnoDB
     cluster to have three, five, seven, or nine MySQL server instances.
     Use the 'Reconfigure' quick action in the MySQL Installer toolbar
     to adjust the number of instances in the InnoDB cluster after the
     configuration has finished.

     As the following figure shows, this step requires that you enter a
     password for the MySQL root account.  The password strength is
     evaluated when you retype it.

     FIGURE GOES HERE: Sandbox InnoDB cluster Test Setup

The sandbox InnoDB cluster, named 'sandboxCluster' by default, is
available on selected ports.  After the configuration executes, click
the 'Summary' tab to view the specific ports that apply to your cluster.
Sandbox InnoDB cluster configuration entries are stored in the
'installer_config.xml' file.

You can use MySQL Installer to install MySQL Shell 1.0.9 or later, if it
is not installed.  MySQL Shell enables you to manage the sandbox
instances.  To connect with the MySQL Shell on port 3310, execute the
following command:

     shell> mysqlsh root@localhost:3310

MySQL Installer also provides a wizard for configuring MySQL Router to
connect to the test InnoDB cluster that was created in this step.  For
configuration details, see windows-applications-router.  To
learn more about MySQL Router operations, see Routing for MySQL InnoDB
cluster
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-innodb-cluster.html).

2.3.3.4 Server Configuration with MySQL Installer
.................................................

MySQL Installer handles the initial configuration of the MySQL server.
For example:

   * It creates the configuration file ('my.ini') that is used to
     configure the MySQL server.  The values written to this file are
     influenced by choices you make during the installation process.
     Some definitions are host dependent.  For example, query_cache is
     enabled if the host has fewer than three cores.

     *Note*:

     Query cache was deprecated in MySQL 5.7 and removed in MySQL 8.0
     (and later).

   * By default, a Windows service for the MySQL server is added.

   * Provides default installation and data paths for MySQL server.  For
     instructions on how to change the default paths, see
     mysql-installer-change-path-proc.

   * It can optionally create MySQL server user accounts with
     configurable permissions based on general roles, such as DB
     Administrator, DB Designer, and Backup Admin.  It optionally
     creates a Windows user named 'MysqlSys' with limited privileges,
     which would then run the MySQL Server.

     User accounts may also be added and configured in MySQL Workbench.

   * Checking 'Show Advanced Options' allows additional 'Logging
     Options' to be set.  This includes defining custom file paths for
     the error log, general log, slow query log (including the
     configuration of seconds it requires to execute a query), and the
     binary log.

During the configuration process, click 'Next' to proceed to the next
step or 'Back' to return to the previous step.  Click 'Execute' at the
final step to apply the server configuration.

The sections that follow describe the server configuration options that
apply to MySQL server on Windows.  The server version you installed will
determine which steps and options you can configure.  Configuring MySQL
server may include some or all of the following steps:

   * server-type-network

   * server-authentication-method

   * server-accounts-roles

   * server-windows-service

   * server-plugins-and-extensions

   * server-advanced-options

   * server-apply-config

*Type and Networking*

   * Server Configuration Type

     Choose the MySQL server configuration type that describes your
     setup.  This setting defines the amount of system resources
     (memory) that will be assigned to your MySQL server instance.

        * *Development*: A machine that will host many other
          applications, and typically this is your personal workstation.
          This option configures MySQL to use the least amount of
          memory.

        * *Server*: Several other applications will be running on this
          machine, such as a web server.  This option configures MySQL
          to use a medium amount of memory.

        * *Dedicated*: A machine that is dedicated to running the MySQL
          server.  Because no other major applications will run on this
          server, such as a web server, this option configures MySQL to
          use the majority of available memory.

   * Connectivity

     Connectivity options control how the connection to MySQL is made.
     Options include:

        * 'TCP/IP': You may enable TCP/IP Networking here as otherwise
          only local host connections are allowed.  Also define the
          'Port Number' and whether to open the firewall port for
          network access.  If the port number is in use already, you
          will see the information icon (

          ) next to the default value and 'Next' is disabled until you
          provide a new port number.

        * 'Named Pipe': Enable and define the pipe name, similar to
          using the '--enable-named-pipe' option.

        * 'Shared Memory': Enable and then define the memory name,
          similar to using the '--shared-memory' option.

   * Advanced Configuration

     Check 'Show Advanced Options' to set additional logging options in
     a later step.  This includes defining custom file paths for the
     error log, general log, slow query log (including the configuration
     of seconds it requires to execute a query), and the binary log.

   * MySQL Enterprise Firewall (Commercial Edition only)

     The 'Enable Enterprise Firewall' check box is selected by default.
     For post-installation instructions, see firewall.

*Authentication Method*

The 'Authentication Method' step is visible only during the installation
or upgrade of MySQL 8.0.4 or higher.  It introduces a choice between two
server-side authentication options.  The MySQL user accounts that you
create in the next step will use the authentication method that you
select in this step.

MySQL 8.0 connectors and community drivers that use 'libmysqlclient' 8.0
now support the 'mysql_native_password' default authentication plugin.
However, if you are unable to update your clients and applications to
support this new authentication method, you can configure the MySQL
server to use 'mysql_native_password' for legacy authentication.  For
more information about the implications of this change, see
caching_sha2_password as the Preferred Authentication Plugin
(http://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password).

If you are installing or upgrading to MySQL 8.0.4 or higher, select one
of the following authentication methods:

   * Use Strong Password Encryption for Authentication (RECOMMENDED)

     MySQL 8.0 supports a new authentication based on improved, stronger
     SHA256-based password methods.  It is recommended that all new
     MySQL server installations use this method going forward.

     *Important*:

     The 'caching_sha2_password' authentication plugin on the server
     requires new versions of connectors and clients, which add support
     for the new MySQL 8.0 default authentication.

   * Use Legacy Authentication Method (Retain MySQL 5.x Compatibility)

     Using the old MySQL 5.x legacy authentication method should be
     considered only in the following cases:

        * Applications cannot be updated to use MySQL 8.0 connectors and
          drivers.

        * Recompilation of an existing application is not feasible.

        * An updated, language-specific connector or driver is not
          available yet.

*Accounts and Roles*

   * Root Account Password

     Assigning a root password is required and you will be asked for it
     when performing other MySQL Installer operations.  Password
     strength is evaluated when you repeat the password in the box
     provided.  For descriptive information regarding password
     requirements or status, move your mouse pointer over the
     information icon (

     ) when it appears.

   * MySQL User Accounts

     Optionally, you can create additional MySQL user accounts with
     predefined user roles.  Each predefined role, such as DB Admin, are
     configured with their own set of privileges.  For example, the DB
     Admin role has more privileges than the DB Designer role.  Click
     the 'Role' drop-down list for a description of each role.

     *Note*:

     If the MySQL server is installed, then you must also enter the
     current root password.

*Windows Service*

On the Windows platform, MySQL server can run as a named service managed
by the operating system and be configured to start up automatically when
Windows starts.  Alternatively, you can configure MySQL server to run as
an executable program that requires manual configuration.

   * 'Configure MySQL server as a Windows service' (Selected by
     default.)

     When the default configuration option is selected, you can also
     select the following:

        * 'Start the MySQL Server at System Startup'

          When selected (default), the service startup type is set to
          Automatic; otherwise, the startup type is set to Manual.

        * 'Run Windows Service as'

          When 'Standard System Account' is selected (default), the
          service logs on as Network Service.

          The 'Custom User' option must have privileges to log on to
          Microsoft Windows as a service.  The 'Next' button will be
          disabled until this user is configured with the required
          privileges.

          A custom user is configured in Windows by searching for "local
          security policy" in the Start menu.  In the Local Security
          Policy window, select 'Local Policies', 'User Rights
          Assignment', and then 'Log On As A Service' to open the
          property dialog.  Click 'Add User or Group' to add the custom
          user and then click 'OK' in each dialog to save the changes.

   * Deselect the Windows Service option

*Plugins and Extensions*

The 'Plugins and Extensions' step is visible during a new installation
of MySQL 5.7.12 (or higher) only.  If you are upgrading from a previous
MySQL version, then you need to open MySQL Installer again and select
the 'Reconfigure' MySQL server option.

   * 'Enable X Protocol / MySQL as a Document Store' (Selected by
     default.)

     When the X Protocol option is selected, MySQL Installer loads and
     starts the X Plugin.  Without the X Plugin running, X Protocol
     clients cannot connect to the server.

        * 'Port Number:' 33060

          Requires an unused port.  The default port number is 33060.

        * 'Open Firewall port for network access'

          Open by default when the X Protocol is selected.

     For more information about using MySQL as a document store and the
     X Plugin, see document-store-concepts and x-plugin.

*Advanced Options*

This step is available if the 'Show Advanced Configuration' check box
was selected during the 'Type and Networking' step.  To enable this step
now, click 'Back' to return to the 'Type and Networking' step and select
the check box.

Advanced configuration options are related to the following MySQL log
files:

   * Error log.

   * General log.

   * Slow query log.

   * Bin log.

*Apply Server Configuration*

All configuration settings are applied to the MySQL server when you
click 'Execute'.  Use the 'Configuration Steps' tab to follow the
progress of each action; the icon for each toggles from white to green
(with a check mark) on success.  Otherwise, the process stops and
displays an error message if an individual action times out.  Click the
'Log' tab to view the log.

When the installation is done and you click 'Finish', MySQL Installer
and the installed MySQL products are added to the Microsoft Windows
Start menu under the 'MySQL' group.  Opening MySQL Installer loads the
dashboard where installed MySQL products are listed and other MySQL
Installer operations are available.

2.3.3.5 Setting Alternative Server Paths with MySQL Installer
.............................................................

You can change the default installation path, the data path, or both
when you install MySQL server.  After you have installed the server, the
paths cannot be altered without removing and reinstalling the server
instance.

*To change paths for MySQL server*

Identify the MySQL server to change and display the 'Advanced Options'
link.

Navigate to the 'Select Products and Features' step by doing one of the
following:

If this is an initial setup, select the
'Custom' setup type and click 'Next'.

If MySQL Installer is installed already, launch it from the Start menu
and then click 'Add' from the dashboard.

Click 'Edit' to filter the list of products, locate the server instance
to be installed in the 'Available Products' list.

With the server instance selected, use the arrow to move the selected
server to the 'Products/Features To Be Installed' list.

Click the server to select it.  When you select the server, the
'Advanced Options' link appears.  For details, see the figure that
follows.

Click 'Advanced Options' to open a dialog window with the path-setting
options.  After setting the path, click 'Next' to continue with the
configuration steps.

FIGURE GOES HERE: Change MySQL Server Path

2.3.3.6 MySQL Applications, Connectors, and Documentation
.........................................................

MySQL Installer provides you with a suite of tools for developing and
managing business-critical applications on Windows.  The suite consist
of applications, connectors, documentation, and samples.

During the initial setup, choose any
predetermined setup type, except 'Server only', to install the latest GA
version of the tools.  Use the 'Custom' setup type to install an
individual tool or specific version.  If MySQL Installer is installed on
the host already, use the 'Add' operation to select and install tools
from the MySQL Installer dashboard.

*MySQL Router Configuration*

MySQL Installer provides a configuration wizard that can bootstrap an
installed instance of MySQL Router 2.1.3 or later to route traffic
between MySQL applications and an InnoDB cluster.  When configured,
MySQL Router runs as a local Windows service.  For detailed information
about using MySQL Router with an InnoDB cluster, see Routing for MySQL
InnoDB cluster
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-innodb-cluster.html).

To configure MySQL Router, do the following:

  1. Set up InnoDB cluster.  For instructions on how to configure a
     sandbox InnoDB cluster on the local host using MySQL Installer, see
     mysql-installer-workflow-innodb-cluster.  InnoDB cluster
     requires MySQL Server 5.7.17 or higher.

     For general InnoDB cluster information, see
     mysql-innodb-cluster-userguide.

  2. Using MySQL Installer, download and install the MySQL Router
     application.  After the installation finishes, the configuration
     wizard prompts you for information.  Select the 'Configure MySQL
     Router for InnoDB cluster' check box to begin the configuration and
     provide the following configuration values:

        * 'Hostname:' localhost by default.

        * 'Port:' The port number of the primary server in the InnoDB
          cluster.  The default is 3310.

        * 'Management User:' An administrative user with root-level
          privileges.

        * 'Password:' The password for the management user.

        * 'Classic MySQL protocol connections to InnoDB cluster'

          'Read/Write:' Set the first base port number to one that is
          unused (between 80 and 65532) and the wizard will select the
          remaining ports for you.

          The figure that follows shows an example of the MySQL Router
          configuration screen, with the first base port number
          specified as 6446 and the remaining ports set by the wizard as
          6447, 6448, and 6449.

     FIGURE GOES HERE: MySQL Router Configuration

  3. Click 'Next' and then 'Execute' to apply the configuration.  Click
     'Finish' to close MySQL Installer or return to the MySQL Installer
     dashboard.

2.3.3.7 MySQL Installer Product Catalog and Dashboard
.....................................................

   * windows-product-catalog

   * windows-product-dashboard

   * locate-products

This section describes the MySQL Installer product catalog and the
dashboard.

*Product Catalog*

The product catalog stores the complete list of released MySQL products
for Microsoft Windows that are available to download from MySQL
Downloads (http://dev.mysql.com/downloads/).  By default, and when an
Internet connection is present, MySQL Installer updates the catalog
daily.  You can also update the catalog manually from the dashboard
(described later).

An up-to-date catalog performs the following actions:

   * Populates the 'Available Products' pane of the Select Products and
     Features step.  This step appears when you select:

        * The 'Custom' setup type during the initial setup.

        * The 'Add' operation from the dashboard.

   * Identifies when product updates are available for the installed
     products listed in the dashboard.

The catalog includes all development releases (Pre-Release), general
releases (Current GA), and minor releases (Other Releases).  Products in
the catalog will vary somewhat, depending on the MySQL Installer edition
that you download.

*MySQL Installer Dashboard*

The MySQL Installer dashboard is the default screen that you see when
you start MySQL Installer after the initial setup
finishes.  If you closed MySQL Installer before
the setup was finished, MySQL Installer resumes the initial setup before
it displays the dashboard.

FIGURE GOES HERE: MySQL Installer Dashboard Elements

*Description of MySQL Installer Dashboard Elements*

  1. The MySQL Installer-About icon (

     ) shows the current version of MySQL Installer and general
     information about MySQL. The version number is located above the
     'Back' button.

     Always include this version number when reporting a problem with
     MySQL Installer.

  2. The MySQL Installer Options icon (

     ) enables you to schedule daily automatic catalog updates.  By
     default, catalog updates are scheduled at the hour when MySQL
     Installer was first installed.  When new products or product
     versions are available, MySQL Installer adds them to the catalog
     and then displays an arrow icon (

     ) next to the version number of installed products listed in the
     dashboard.

     Use this option to enable or disable automatic catalog updates and
     to reset the time of day when the MySQL Installer updates the
     catalog automatically.  For specific settings, see the task named
     'ManifestUpdate' in the Windows Task Scheduler.

  3. MySQL Installer dashboard operations provide a variety of actions
     that apply to installed products or products listed in the catalog.
     To initiate the following operations, first click the operation
     link and then select the product or products to manage:

        * 'Add': This operation opens the Select Products and Features
          screen.  From there, you can filter the product in the product
          catalog, select one or more products to download (as needed),
          and begin the installation.  For hints about using the filter,
          see locate-products.

        * 'Modify': Use this operation to add or remove the features
          associated with installed products.  Features that you can
          modify vary in complexity by product.  When the 'Program
          Shortcut' check box is selected, the product appears in the
          Start menu under the 'MySQL' group.

        * 'Upgrade': This operation loads the Select Products to Upgrade
          screen and populates it with all the upgrade candidates.  An
          installed product can have more than one upgrade version and
          requires a current product catalog.

          * Important server upgrade conditions:*

             * MySQL Installer does not permit server upgrades between
               major release versions or minor release versions, but
               does permit upgrades within a release series, such as an
               upgrade from 5.7.18 to 5.7.19.

             * Upgrades between milestone releases (or from a milestone
               release to a GA release) are not supported.  Significant
               development changes take place in milestone releases and
               you may encounter compatibility issues or problems
               starting the server.

          To choose a new product version:

            1. Click 'Upgrade'.  Confirm that the check box next to
               product name in the 'Upgradeable Products' pane has a
               check mark.  Deselect the products that you do not intend
               to upgrade at this time.

               *Note*:

               For server milestone releases in the same release series,
               MySQL Installer deselects the server upgrade and displays
               a warning to indicate that the upgrade is not supported,
               identifies the risks of continuing, and provides a
               summary of the steps to perform a logical upgrade
               manually.  You can reselect server upgrade at your own
               risk.  For instructions on how to perform a logical
               upgrade with a milestone release, see
               upgrade-procedure-logical.

            2. Click a product in the list to highlight it.  This action
               populates the 'Upgradeable Versions' pane with the
               details of each available version for the selected
               product: version number, published date, and a 'Changes'
               link to open the release notes for that version.

          MySQL Installer upgrades all of the selected products in one
          action.  Click 'Show Details' to view the actions performed by
          MySQL Installer.

        * 'Remove' This operation opens the Remove Products screen and
          populates it with the MySQL products installed on the host.
          Select the MySQL products you want to remove (uninstall) and
          then click 'Execute' to begin the removal process.

          To select products to remove, do one of the following:

             * Select the check box for one or more products.

             * Select the 'Product' check box to select all products.

  4. The 'Reconfigure' link in the Quick Action column next to each
     installed server loads the current configuration values for the
     server and then cycles through all configuration steps enabling you
     to change the options and values.  On completion, MySQL Installer
     stops the server, applies the configuration changes, and restarts
     the server for you.  For a description of each configuration
     option, see mysql-installer-workflow-server.

     Installed 'Samples and Examples' associated with a specific MySQL
     server version can be also be reconfigured to apply
     feature-configuration changes, if any.  You must provide
     credentials with root privileges to reconfigure these items.

  5. The 'Catalog' link enables you to download the latest catalog of
     MySQL products manually and then to integrate those product changes
     with MySQL Installer.  The catalog-download action does not perform
     an upgrade of the products already installed on the host.  Instead,
     it returns to the dashboard and displays an arrow icon in the
     Version column for each installed product that has a newer version.
     Use the 'Upgrade' operation to install the newer product version.

     You can also use the 'Catalog' link to display the current change
     history of each product without downloading the new catalog.
     Select the 'Do not update at this time' check box to view the
     change history only.

*Locating Products to Install*

MySQL products in the catalog are listed by category: MySQL Servers,
Applications, MySQL Connectors, and Documentation.  Only the latest GA
versions appear in the 'Available Products' pane by default.  If you are
looking for a pre-release or older version of a product, it may not be
visible in the default list.

To change the default product list, click 'Add' on the dashboard to open
the Select Products and Features screen, and then click 'Edit'.  Modify
the product values and then click 'Filter'.

FIGURE GOES HERE: Filter Available Products

Reset one or more of the following values to filter the list of
available products:

   * Text: Filter by text.

   * Category: All Software (default), MySQL Servers, Applications,
     MySQL Connectors, or Documentation (for samples and documentation).

   * Age: Pre-Release, Current GA (default), or Other Releases.

   * Already Downloaded (the check box is deselected by default).

   * Architecture: Any (default), 32-bit, or 64-bit.

2.3.3.8 MySQLInstallerConsole Reference
.......................................

'MySQLInstallerConsole.exe' provides
command-line functionality that is similar to MySQL Installer.  It is
installed when MySQL Installer is initially executed and then available
within the 'MySQL Installer' directory.  Typically, that is in
'C:\Program Files (x86)\MySQL\MySQL Installer\', and the console must be
executed with administrative privileges.

To use, invoke the command prompt with administrative privileges by
choosing 'Start', 'Accessories', then right-click on 'Command Prompt'
and choose 'Run as administrator'.  And from the command line,
optionally change the directory to where
'MySQLInstallerConsole.exe' is located:

     C:\> cd Program Files (x86)\MySQL\MySQL Installer for Windows
     C:\Program Files (x86)\MySQL\MySQL Installer for Windows> MySQLInstallerConsole.exe help
     =================== Start Initialization ===================
     MySQL Installer is running in Community mode

     Attempting to update manifest.
     Initializing product requirements
     Loading product catalog
     Checking for product catalog snippets
     Checking for product packages in the bundle
     Categorizing product catalog
     Finding all installed packages.
     Your product catalog was last updated at 11/1/2016 4:10:38 PM
     =================== End Initialization ===================

     The following commands are available:

     Configure - Configures one or more of your installed programs.
     Help      - Provides list of available commands.
     Install   - Install and configure one or more available MySQL programs.
     List      - Provides an interactive way to list all products available.
     Modify    - Modifies the features of installed products.
     Remove    - Removes one or more products from your system.
     Status    - Shows the status of all installed products.
     Update    - Update the current product catalog.
     Upgrade   - Upgrades one or more of your installed programs.

'MySQLInstallerConsole.exe' supports the
following commands:

*Note*:

Configuration block values that contain a colon (":") must be wrapped in
double quotes.  For example, installdir="C:\MySQL\MySQL Server 8.0".

   *
     'configure [PRODUCT1]:[SETTING]=[VALUE];
     [PRODUCT2]:[SETTING]=[VALUE]; [...]'

     Configure one or more MySQL products on your system.  Multiple
     setting=value pairs can be configured for each product.

     Switches include:

        * '-showsettings' : Displays the available options for the
          selected product, by passing in the product name after
          '-showsettings'.

        * '-silent' : Disable confirmation prompts.

          C:\> MySQLInstallerConsole configure -showsettings server
          C:\> MySQLInstallerConsole configure server:port=3307

   *
     'help [COMMAND]'

     Displays a help message with usage examples, and then exits.  Pass
     in an additional command to receive help specific to that command.

          C:\> MySQLInstallerConsole help
          C:\> MySQLInstallerConsole help install

   *
     'install [PRODUCT]:[FEATURES]:[CONFIG BLOCK]:[CONFIG BLOCK]:[CONFIG
     BLOCK]; [...]'

     Install one or more MySQL products on your system.  If pre-release
     products are available, both GA and pre-release products are
     installed when the value of the '-type' switch is 'Developer',
     'Client', or 'Full'.  Use the '-only_ga_products' switch to
     restrict the product set to GA products only when using these setup
     types.

     Switches and syntax options include:

        * '-only_ga_products' : Restricts the product set to include GA
          products only.

        * '-type=[SetupType]' : Installs a predefined set of software.
          The "SetupType" can be one of the following:

          *Note*:

          Non-custom setup types can only be chosen if no other MySQL
          products are installed.

             * *Developer*: Installs a complete development environment.

             * *Server*: Installs a single MySQL server

             * *Client*: Installs client programs and libraries

             * *Full*: Installs everything

             * *Custom*: Installs user selected products.  This is the
               default option.

        * '-showsettings' : Displays the available options for the
          selected product, by passing in the product name after
          '-showsettings'.

        * '-silent' : Disable confirmation prompts.

        * [CONFIG BLOCK]: One or more configuration blocks can be
          specified.  Each configuration block is a semicolon separated
          list of key value pairs.  A block can include either a
          "config" or "user" type key, where "config" is the default
          type if one is not defined.

          Configuration block values that contain a colon character
          (':') must be wrapped in double quotes.  For example,
          'installdir="C:\MySQL\MySQL Server 8.0"'.

          Only one "config" type block can be defined per product.  A
          "user" block should be defined for each user that should be
          created during the product's installation.

          *Note*:

          Adding users is not supported when a product is being
          reconfigured.

        * [FEATURE]: The feature block is a semicolon separated list of
          features, or an asterisk character ('*') to select all
          features.

          C:\> MySQLInstallerConsole install server;5.6.25:*:port=3307;serverid=2:type=user;username=foo;password=bar;role=DBManager
          C:\> MySQLInstallerConsole install server;5.6.25;x64 -silent

     An example that passes in additional configuration blocks, broken
     up by '^' to fit this screen:

          C:\> MySQLInstallerConsole install server;5.6.25;x64:*:type=config;openfirewall=true; ^
                    generallog=true;binlog=true;serverid=3306;enable_tcpip=true;port=3306;rootpasswd=pass; ^
                    installdir="C:\MySQL\MySQL Server 5.6":type=user;datadir="C:\MySQL\data";username=foo;password=bar;role=DBManager

   *
     'list'

     Lists an interactive console where all of the available MySQL
     products can be searched.  Execute 'MySQLInstallerConsole list' to
     launch the console, and enter in a substring to search.

          C:\> MySQLInstallerConsole list

   *
     'modify [PRODUCT1:-REMOVELIST|+ADDLIST]
     [PRODUCT2:-REMOVELIST|+ADDLIST] [...]'

     Modifies or displays features of a previously installed MySQL
     product.

        * '-silent' : Disable confirmation prompts.

          C:\> MySQLInstallerConsole modify server
          C:\> MySQLInstallerConsole modify server:+documentation
          C:\> MySQLInstallerConsole modify server:-debug

   *
     'remove [PRODUCT1] [PRODUCT2] [...]'

     Removes one ore more products from your system.

        * '*' : Pass in '*' to remove all of the MySQL products.

        * '-continue' : Continue the operation even if an error occurs.

        * '-silent' : Disable confirmation prompts.

          C:\> MySQLInstallerConsole remove *
          C:\> MySQLInstallerConsole remove server

   *
     'status'

     Provides a quick overview of the MySQL products that are installed
     on the system.  Information includes product name and version,
     architecture, date installed, and install location.

          C:\> MySQLInstallerConsole status

   *
     'update'

     Downloads the latest MySQL product catalog to your system.  On
     success, the download catalog will be applied the next time either
     MySQLInstaller or MySQLInstallerConsole is executed.

          C:\> MySQLInstallerConsole UPDATE

     *Note*:

     The 'Automatic Catalog Update' GUI option executes this command
     from the Windows Task Scheduler.

   *
     'upgrade [PRODUCT1:VERSION] [PRODUCT2:VERSION] [...]'

     Upgrades one or more products on your system.  Syntax options
     include:

        * '*' : Pass in '*' to upgrade all products to the latest
          version, or pass in specific products.

        * '!' : Pass in '!' as a version number to upgrade the MySQL
          product to its latest version.

        * '-silent' : Disable confirmation prompts.

          C:\> MySQLInstallerConsole upgrade *
          C:\> MySQLInstallerConsole upgrade workbench:6.3.5
          C:\> MySQLInstallerConsole upgrade workbench:!
          C:\> MySQLInstallerConsole upgrade workbench:6.3.5 excel:1.3.2

2.3.4 MySQL Notifier
--------------------

MySQL Notifier is a tool that enables you to monitor and adjust the
status of your local and remote MySQL server instances through an
indicator that resides in the Microsoft Windows taskbar.  MySQL Notifier
also gives quick access to MySQL Workbench through its context menu.

MySQL Notifier is installed by using MySQL Installer.  It can be loaded
automatically when Microsoft Windows is started.

To install, download and execute the MySQL Installer
(http://dev.mysql.com/downloads/installer/).  With MySQL Notifier
selected from Applications, proceed with the installation.  See the
MySQL Installer manual for additional details.

For notes detailing the changes in each release of MySQL Notifier, see
the MySQL Notifier Release Notes
(http://dev.mysql.com/doc/relnotes/mysql-notifier/en/).

Visit the MySQL Notifier forum (http://forums.mysql.com/list.php?173)
for additional MySQL Notifier help and support.

*Features include:*

   * Start, stop, and restart instances of the MySQL server.

   * Automatically detects (and adds) new MySQL server services.  These
     are listed under 'Manage Monitored Items', and may also be
     configured.

   * The Tray icon changes, depending on the status.  It is a
     ﻿right-pointing green triangle if all monitored MySQL server
     instances are running or a red square if at least one service is
     stopped.  The 'Update MySQL Notifier tray icon based on service
     status' option, which dictates this behavior, is enabled by default
     for each service.

   * Links to other applications like MySQL Workbench, MySQL Installer,
     and the MySQL Utilities.  For example, choosing 'Manage Instance'
     will load the MySQL Workbench Server Administration window for that
     particular instance.

   * If MySQL Workbench is also installed, then the 'Manage Instance'
     and 'SQL Editor' options are available for local (but not remote)
     MySQL instances.

   * Monitors both local and remote MySQL instances.

2.3.4.1 MySQL Notifier Usage
............................

MySQL Notifier provides visual status information for the MySQL servers
that are monitored on both local or remote computers.  The MySQL
Notifier icon in the taskbar changes color to indicate the current
status: Running or Stopped.

MySQL Notifier automatically adds discovered MySQL services on the local
computer.  By default, the 'Automatically add new services whose name
contains' option is enabled and set to 'mysql'.  Related notification
options include being notified when new services are either discovered
or experience status changes, and are also enabled by default.
Uninstalling a service removes the service from MySQL Notifier.

Clicking the MySQL Notifier icon from the Windows taskbar reveals the
MySQL Notifier main menu, which lists each MySQL server separately and
displays its current status.  You can start, stop, or restart each MySQL
server from the menu as the following figure shows.  When MySQL
Workbench is installed locally, the 'Manage Instance' and 'SQL Editor'
menu items start the application.

FIGURE GOES HERE: MySQL Notifier Service Instance Menu

The 'Actions' menu includes the following items:

   * 'Manage Monitored Items'

   * 'Launch MySQL Installer' (Only when the product is installed.)

   * 'Check for Updates' (Only when MySQL Installer is installed.)

   * 'MySQL Utilities Shell' (Only when the product is installed.)

   * 'Refresh Status'

   * 'Options'

   * 'About'

   * 'Close MySQL Notifier'

The main menu does not show the 'Actions' menu when there are no
services being monitored by MySQL Notifier.

*MySQL Notifier Options*

The 'Actions', 'Options' menu provides a set of options that configure
MySQL Notifier operations.  Options are grouped into the following
categories: 'General Options', 'Notification Options', and 'MySQL Server
Connections Options'.

Click 'Accept' to enable the selected options or 'Cancel' to ignore all
changes.  Click 'Reset to Defaults' and then 'Accept' to apply default
option values.

General Options

This group includes:

   * 'Use colorful status icons': Enables a colorful style of icons for
     the tray of MySQL Notifier.  Selected by default.

   * 'Run at Windows Startup': Allows the application to be loaded when
     Microsoft Windows starts.  Deselected by default.

   * 'Automatically Check For Updates Every' # 'Weeks': Checks for a new
     version of MySQL Notifier, and runs this check every # weeks.
     Selected by default with the updates every four weeks.

   * 'Automatically add new services whose name contains:' The text used
     to filter services and add them automatically to the monitored list
     of the local computer running MySQL Notifier and on remote
     computers already monitoring Windows services.  Selected by default
     for names containing 'mysql'.

   * 'Ping monitored MySQL Server instances every' # 'seconds': The
     interval (in seconds) to ping monitored MySQL Server instances for
     status changes.  Longer intervals might be necessary if the list of
     monitored remote instances is large.  30 seconds by default.

Notification Options

This group includes:

   * 'Notify me when a service is automatically added': Display a
     balloon notification from the taskbar when a newly discovered
     service is added to the monitored services list.  Selected by
     default.

   * 'Notify me when a service changes status': Displays a balloon
     notification from the taskbar when a monitored service changes its
     status.  Selected by default.

MySQL Server Connections Options

This group includes:

   * 'Automatic connections migration delayed until:' When there are
     connections to migrate to MySQL Workbench (if installed), this
     option postpones the migration by one hour, one day, one week, one
     month, or indefinitely.

*Managing Monitored Items*

The 'Actions', 'Manage Monitored Items' menu enables you to add,
configure, and delete the services and MySQL instances you intend to
monitor.  The 'Manage Items' window has two tabs: 'Services' and
'Instances'.

Services Tab

When MySQL is configured as a local service, MySQL Notifier adds the
service to the 'Services' tab automatically.  With the 'Services' tab
open, you can select the following options that apply to all services
being monitored:

   * 'Notify me when status changes'

   * 'Update MySQL Notifier tray icon based on service status'

The next figure shows the 'Services' tab open and both options selected.
This tab shows the service name, the computer where the service is
hosted, and the current status of the service.

FIGURE GOES HERE: MySQL Notifier: Manage Services

To stop monitoring a service, select it from the list of monitored
services and click 'Delete'.

Click 'Add' and then 'Windows Service' to open the 'Add Service' window.
To add a new service, select a computer from the drop-down list, choose
a service from the list, and then click 'OK' to accept.  Use the
'Filter' field to reduce the set of services in the list or select 'Only
show services that match auto-add filter?' to reuse the general-options
filter from the 'Options' menu.

A variety of Windows services (including MySQL) may be selected as the
following figure shows.  In addition to the service name, the list shows
the current status of each Windows services for the selected computer.

FIGURE GOES HERE: MySQL Notifier: Adding New Services

Instances Tab

When MySQL is configured as a MySQL instance, MySQL Notifier adds the
instance to the 'Instances' tab automatically.  With the 'Instances' tab
open, you can select the following options that apply to each instance
being monitored:

   * 'Notify me when status changes'

   * 'Update MySQL Notifier tray icon based on service status'

   * 'Monitor MySQL Instance status every' [ # ] [ seconds | minutes |
     hours | days ]

The next figure shows the 'Instances' tab open and both options
selected.  Monitoring the instance status is set to every two minutes in
this example.  This tab shows the instance name, the database driver,
and the current status of the instance.

FIGURE GOES HERE: MySQL Notifier: Manage MySQL Instances

To stop monitoring an instance, select it from the list of monitored
MySQL instances and click 'Delete'.

Click 'Add' and then 'MySQL Instances' to open the 'Monitor MySQL Server
Instance' window.  Use the 'Filter' field to reduce the set of instances
in the list or select 'Show MySQL instances already being monitored?' to
show monitored items only.

Optionally, you can select a connection from MySQL Workbench to monitor.
Click 'Add New Connection', shown in the next figure, to create a new
connection.

FIGURE GOES HERE: MySQL Notifier: Adding New Instances

*Troubleshooting*

For issues that are not documented here, visit the MySQL Notifier
Support Forum (http://forums.mysql.com/list.php?173) for MySQL Notifier
help and support.

   * _Problem_: attempting to start/stop/restart a MySQL service might
     generate an error similar to "The Service *MySQLVERSION* failed the
     most recent status change request with the message "The service
     *mysqlVERSION* was not found in the Windows Services".

     _Explanation_: this is a case-sensitivity issue, in that the
     service name is *MySQLVERSION* compared to having *mysqlVERSION* in
     the configuration file.

     _Solution_: either update your MySQL Notifier configuration file
     with the correct information, or stop MySQL Notifier and delete
     this configuration file.  The MySQL Notifier configuration file is
     located at '%APPDATA%\Oracle\MySQL Notifier\settings.config' where
     '%APPDATA%' is a variable and depends on your system.  A typical
     location is "C:\Users\YOURUSERNAME\AppData\Running\Oracle\MySQL
     Notifier\settings.config" where YOURUSERNAME is your system's user
     name.  In this file, and within the ServerList section, change the
     ServerName values from lowercase to the actual service names.  For
     example, change *mysqlVERSION* to *MySQLVERSION*, save, and then
     restart MySQL Notifier.  Alternatively, stop MySQL Notifier, delete
     this file, then restart MySQL Notifier.

   * _Problem_: when connecting to a remote computer for the purpose of
     monitoring a remote Windows service, the 'Add Service' dialog does
     not always show all the services shown in the Windows Services
     console.

     _Explanation_: this behavior is governed by the operating system
     and the outcome is expected when working with nondomain user
     accounts.  For a complete description of the behavior, see the User
     Account Control and WMI
     (https://msdn.microsoft.com/en-us/library/aa826699(VS.85).aspx)
     article from Microsoft.

     _Solution_: when the remote computer is in a compatible domain, it
     is recommended that domain user accounts are used to connect
     through WMI to a remote computer.  For detailed setup instructions
     using WMI, see windows-notifier-installation.

     Alternatively, when domain user accounts are not available,
     Microsoft provides a less secure workaround that should only be
     implemented with caution.  For more information, see the
     Description of User Account Control and remote restrictions in
     Windows Vista (https://support.microsoft.com/en-us/kb/951016) KB
     article from Microsoft.

2.3.4.2 Setting Up Remote Monitoring in MySQL Notifier
......................................................

MySQL Notifier uses Windows Management Instrumentation (WMI) to manage
and monitor services on remote computers.  This section explains how it
works and how to set up your system to monitor remote MySQL instances.

In order to configure WMI, it is important to understand that the
underlying Distributed Component Object Model (DCOM) architecture is
doing the WMI work.  Specifically, MySQL Notifier is using asynchronous
notification queries on remote Microsoft Windows hosts as .NET events.
These events send an asynchronous callback to the computer running MySQL
Notifier so it knows when a service status has changed on the remote
computer.  Asynchronous notifications offer the best performance
compared to semisynchronous notifications or synchronous notifications
that use timers.

As the following figure shows, asynchronous notification requires the
remote computer to send a callback to the client computer (thus opening
a reverse connection), so the Windows Firewall and DCOM settings must be
properly configured for the communication to function properly.  The
client (Computer A), which includes an unsecured application
('unsecapp.exe' in this example), makes an asynchronous call to a remote
computer (Computer B) and receives a call back with data.

FIGURE GOES HERE: MySQL Notifier Distributed Component Object Model
(DCOM)

Most of the common errors thrown by asynchronous WMI notifications are
related to Windows Firewall blocking the communication, or to DCOM / WMI
settings not being set up properly.  For a list of common errors with
solutions, see windows-notifier-installation-errors.

The following steps are required to make WMI function.  These steps are
divided between two machines.  A single host computer that runs MySQL
Notifier (Computer A), and multiple remote machines that are being
monitored (Computer B).

*Computer running MySQL Notifier (Computer A)*

  1. Enable remote administration by either editing the 'Group Policy
     Editor', or using 'NETSH':

     Using the 'Group Policy Editor':

       1. Click 'Start', click 'Run', type 'GPEDIT.MSC', and then click
          'OK'.

       2. Under the 'Local Computer Policy' heading, expand 'Computer
          Configuration'.

       3. Expand 'Administrative Templates', then 'Network', 'Network
          Connections', and then 'Windows Firewall'.

       4. If the computer is in the domain, then double-click 'Domain
          Profile'; otherwise, double-click 'Standard Profile'.

       5. Double-click 'Windows Firewall: Allow inbound remote
          administration exception' to open a configuration window.

       6. Check the 'Enabled' option button and then click 'OK'.

     Using the 'NETSH' command:

     *Note*:

     The "netsh firewall" command is deprecated as of Microsoft Server
     2008 and Vista, and replaced with "netsh advfirewall firewall".

       1. Open a command prompt window with Administrative rights (you
          can right-click the Command Prompt icon and select 'Run as
          Administrator').

       2. Execute the following command:

               NETSH advfirewall firewall set service RemoteAdmin enable

  2. Open the DCOM port TCP 135:

       1. Open a command prompt window with Administrative rights (you
          can right-click the Command Prompt icon and select 'Run as
          Administrator').

       2. Execute the following command:

               NETSH advfirewall firewall add rule name=DCOM_TCP135 protocol=TCP localport=135 dir=in action=allow

  3. Add the client application that contains the sink for the callback
     ('MySqlNotifier.exe') to the Windows Firewall Exceptions List (use
     either the Windows Firewall configuration or 'NETSH'):

     Using the Windows Firewall configuration:

       1. In the Control Panel, double-click 'Windows Firewall'.

       2. In the Windows Firewall window, click 'Allow a program or
          feature through Windows Firewall'.

       3. In the Allowed Programs window, click 'Change Settings' and do
          one of the following:

             * If 'MySqlNotifier.exe' is in the Allowed programs and
               features list, make sure it is checked for the type of
               networks the computer connects to (Private, Public or
               both).

             * If 'MySqlNotifier.exe' is not in the list, click 'Allow
               another program'.

                 1. In the 'Add a Program' window, select the
                    'MySqlNotifier.exe' if it exists in the Programs
                    list, otherwise click 'Browse' and go to the
                    directory where 'MySqlNotifier.exe' was installed to
                    select it, then click 'Add'.

                 2. Make sure 'MySqlNotifier.exe' is checked for the
                    type of networks the computer connects to (Private,
                    Public or both).

     Using the 'NETSH' command:

       1. Open a command prompt window with Administrative rights (you
          can right-click the Command Prompt icon and click 'Run as
          Administrator').

       2. Execute the following command, where you change
          "[YOUR_INSTALL_DIRECTORY]":

               NETSH advfirewall firewall add rule name=MySqlNotifier program=[YOUR_INSTALL_DIRECTORY]\MySqlNotifier.exe action=allow dir=in

  4. If Computer B is either a member of 'WORKGROUP' or is in a
     different domain that is untrusted by Computer A, then the callback
     connection (Connection 2) is created as an Anonymous connection.
     To grant Anonymous connections DCOM Remote Access permissions:

       1. Click 'Start', click 'Run', type 'DCOMCNFG', and then click
          'OK'.

       2. In the Component Services dialog box, expand Component
          Services, expand Computers, and then right-click 'My Computer'
          and click 'Properties'.

       3. In the My Computer Properties dialog box, click the 'COM
          Security' tab.

       4. Under Access Permissions, click 'Edit Limits'.

       5. In the Access Permission dialog box, select 'ANONYMOUS LOGON
          name' in the Group or user names box.  In the Allow column
          under Permissions for User, select 'Remote Access', and then
          click 'OK'.

*Monitored Remote Computer (Computer B)*

If the user account that is logged on to the computer running the MySQL
Notifier (Computer A) is a local administrator on the remote computer
(Computer B), such that the same account is an administrator on Computer
B, you can skip to the "Allow for remote administration" step.

Setting DCOM security to allow a non-administrator user to access a
computer remotely:

  1. Grant "DCOM remote launch" and activation permissions for a user or
     group:

       1. Click 'Start', click 'Run', type 'DCOMCNFG', and then click
          'OK'.

       2. In the Component Services dialog box, expand Component
          Services, expand Computers, and then right-click 'My Computer'
          and click 'Properties'.

       3. In the My Computer Properties dialog box, click the 'COM
          Security' tab.

       4. Under Launch and Activation Permission, click 'Edit Limits'.

       5. In the 'Launch and Activation Permission' dialog box, follow
          these steps if your name or your group does not appear in the
          Groups or user names list:

            1. In the 'Launch and Activation Permission' dialog box,
               click 'Add'.

            2. In the Select Users or Groups dialog box, add your name
               and the group in the 'Enter the object names to select'
               box, and then click 'OK'.

       6. In the 'Launch and Activation Permission' dialog box, select
          your user and group in the Group or user names box.  In the
          Allow column under Permissions for User, select 'Remote
          Launch', select 'Remote Activation', and then click 'OK'.

     Grant DCOM remote access permissions:

       1. Click 'Start', click 'Run', type 'DCOMCNFG', and then click
          'OK'.

       2. In the Component Services dialog box, expand Component
          Services, expand Computers, and then right-click 'My Computer'
          and click 'Properties'.

       3. In the My Computer Properties dialog box, click the 'COM
          Security' tab.

       4. Under Access Permissions, click 'Edit Limits'.

       5. In the Access Permission dialog box, select 'ANONYMOUS LOGON
          name' in the Group or user names box.  In the Allow column
          under Permissions for User, select 'Remote Access', and then
          click 'OK'.

  2. Allowing non-administrator users access to a specific WMI
     namespace:

       1. In the Control Panel, double-click 'Administrative Tools'.

       2. In the Administrative Tools window, double-click 'Computer
          Management'.

       3. In the Computer Management window, expand the 'Services and
          Applications' tree.

       4. Right-click the WMI Control icon and select 'Properties'.

       5. In the WMI Control Properties window, click the 'Security'
          tab.

       6. In the Security tab, select the namespace and click
          'Security'.  Root/CIMV2 is a commonly used namespace.

       7. Locate the appropriate account and check 'Remote Enable' in
          the Permissions list.

  3. Allow for remote administration by either editing the 'Group Policy
     Editor' or using 'NETSH':

     Using the 'Group Policy Editor':

       1. Click 'Start', click 'Run', type 'GPEDIT.MSC', and then click
          'OK'.

       2. Under the Local Computer Policy heading, double-click
          'Computer Configuration'.

       3. Double-click 'Administrative Templates', then 'Network',
          'Network Connections', and then 'Windows Firewall'.

       4. If the computer is in the domain, then double-click 'Domain
          Profile'; otherwise, double-click 'Standard Profile'.

       5. Click 'Windows Firewall: Allow inbound remote administration
          exception'.

       6. On the Action menu either select 'Edit', or double-click the
          selection from the previous step.

       7. Check the 'Enabled' radio button, and then click 'OK'.

     Using the 'NETSH' command:

       1. Open a command prompt window with Administrative rights (you
          can right-click the Command Prompt icon and click 'Run as
          Administrator').

       2. Execute the following command:

               NETSH advfirewall firewall set service RemoteAdmin enable

  4. Confirm that the user account you are logging in with uses the
     'Name' value and not the 'Full Name' value:

       1. In the 'Control Panel', double-click 'Administrative Tools'.

       2. In the 'Administrative Tools' window, double-click 'Computer
          Management'.

       3. In the 'Computer Management' window, expand the 'System Tools'
          then 'Local Users and Groups'.

       4. Click the 'Users' node, and on the right side panel locate
          your user and make sure it uses the 'Name' value to connect,
          and not the 'Full Name' value.

*Common Errors*

   * '0x80070005'

        * DCOM Security was not configured properly (see Computer B, the
          'Setting DCOM security...' step).

        * The remote computer (Computer B) is a member of WORKGROUP or
          is in a domain that is untrusted by the client computer
          (Computer A) (see Computer A, the 'Grant Anonymous connections
          DCOM Remote Access permissions' step).

   * '0x8007000E'

        * The remote computer (Computer B) is a member of WORKGROUP or
          is in a domain that is untrusted by the client computer
          (Computer A) (see Computer A, the 'Grant Anonymous connections
          DCOM Remote Access permissions' step).

   * '0x80041003'

        * Access to the remote WMI namespace was not configured properly
          (see Computer B, the 'Allowing non-administrator users access
          to a specific WMI namespace' step).

   * '0x800706BA'

        * The DCOM port is not open on the client computers (Computer A)
          firewall.  See the 'Open the DCOM port TCP 135' step for
          Computer A.

        * The remote computer (Computer B) is inaccessible because its
          network location is set to Public.  Make sure you can access
          it through the Windows Explorer.

2.3.5 Installing MySQL on Microsoft Windows Using a 'noinstall' ZIP Archive
---------------------------------------------------------------------------

Users who are installing from the 'noinstall' package can use the
instructions in this section to manually install MySQL. The process for
installing MySQL from a ZIP Archive package is as follows:

  1. Extract the main archive to the desired install directory

     _Optional_: also extract the debug-test archive if you plan to
     execute the MySQL benchmark and test suite

  2. Create an option file

  3. Choose a MySQL server type

  4. Initialize MySQL

  5. Start the MySQL server

  6. Secure the default user accounts

This process is described in the sections that follow.

2.3.5.1 Extracting the Install Archive
......................................

To install MySQL manually, do the following:

  1. If you are upgrading from a previous version please refer to
     windows-upgrading, before beginning the upgrade process.

  2. Make sure that you are logged in as a user with administrator
     privileges.

  3. Choose an installation location.  Traditionally, the MySQL server
     is installed in 'C:\mysql'.  If you do not install MySQL at
     'C:\mysql', you must specify the path to the install directory
     during startup or in an option file.  See
     windows-create-option-file.

     *Note*:

     The MySQL Installer installs MySQL under 'C:\Program Files\MySQL'.

  4. Extract the install archive to the chosen installation location
     using your preferred file-compression tool.  Some tools may extract
     the archive to a folder within your chosen installation location.
     If this occurs, you can move the contents of the subfolder into the
     chosen installation location.

2.3.5.2 Creating an Option File
...............................

If you need to specify startup options when you run the server, you can
indicate them on the command line or place them in an option file.  For
options that are used every time the server starts, you may find it most
convenient to use an option file to specify your MySQL configuration.
This is particularly true under the following circumstances:

   * The installation or data directory locations are different from the
     default locations ('C:\Program Files\MySQL\MySQL Server 5.7' and
     'C:\Program Files\MySQL\MySQL Server 5.7\data').

   * You need to tune the server settings, such as memory, cache, or
     InnoDB configuration information.

When the MySQL server starts on Windows, it looks for option files in
several locations, such as the Windows directory, 'C:\', and the MySQL
installation directory (for the full list of locations, see
option-files).  The Windows directory typically is named something
like 'C:\WINDOWS'.  You can determine its exact location from the value
of the 'WINDIR' environment variable using the following command:

     C:\> echo %WINDIR%

MySQL looks for options in each location first in the 'my.ini' file, and
then in the 'my.cnf' file.  However, to avoid confusion, it is best if
you use only one file.  If your PC uses a boot loader where 'C:' is not
the boot drive, your only option is to use the 'my.ini' file.  Whichever
option file you use, it must be a plain text file.

*Note*:

When using the MySQL Installer to install MySQL Server, it will create
the 'my.ini' at the default location, and the user executing MySQL
Installer is granted full permissions to this new 'my.ini' file.

In other words, be sure that the MySQL Server user has permission to
read the 'my.ini' file.

You can also make use of the example option files included with your
MySQL distribution; see server-configuration-defaults.

An option file can be created and modified with any text editor, such as
Notepad.  For example, if MySQL is installed in 'E:\mysql' and the data
directory is in 'E:\mydata\data', you can create an option file
containing a '[mysqld]' section to specify values for the 'basedir' and
'datadir' options:

     [mysqld]
     # set basedir to your installation path
     basedir=E:/mysql
     # set datadir to the location of your data directory
     datadir=E:/mydata/data

Microsoft Windows path names are specified in option files using
(forward) slashes rather than backslashes.  If you do use backslashes,
double them:

     [mysqld]
     # set basedir to your installation path
     basedir=E:\\mysql
     # set datadir to the location of your data directory
     datadir=E:\\mydata\\data

The rules for use of backslash in option file values are given in
option-files.

As of MySQL 5.7.6, the ZIP archive no longer includes a 'data'
directory.  To initialize a MySQL installation by creating the data
directory and populating the tables in the mysql system database,
initialize MySQL using either '--initialize' or '--initialize-insecure'.
For additional information, see
data-directory-initialization-mysqld.

If you would like to use a data directory in a different location, you
should copy the entire contents of the 'data' directory to the new
location.  For example, if you want to use 'E:\mydata' as the data
directory instead, you must do two things:

  1. Move the entire 'data' directory and all of its contents from the
     default location (for example 'C:\Program Files\MySQL\MySQL Server
     5.7\data') to 'E:\mydata'.

  2. Use a '--datadir' option to specify the new data directory location
     each time you start the server.

2.3.5.3 Selecting a MySQL Server Type
.....................................

The following table shows the available servers for Windows in MySQL
5.7.

Binary         Description

See Optimized binary with named-pipe support 'mysqld'.

See Like *note 'mysqld', but compiled with full
'mysqld-debug':debugging and automatic memory allocation checking
mysqld.

All of the preceding binaries are optimized for modern Intel processors,
but should work on any Intel i386-class or higher processor.

Each of the servers in a distribution support the same set of storage
engines.  The 'SHOW ENGINES' statement displays
which engines a given server supports.

All Windows MySQL 5.7 servers have support for symbolic linking of
database directories.

MySQL supports TCP/IP on all Windows platforms.  MySQL servers on
Windows also support named pipes, if you start the server with the
'--enable-named-pipe' option.  It is necessary to use this option
explicitly because some users have experienced problems with shutting
down the MySQL server when named pipes were used.  The default is to use
TCP/IP regardless of platform because named pipes are slower than TCP/IP
in many Windows configurations.

2.3.5.4 Initializing the Data Directory
.......................................

If you installed MySQL using the 'noinstall' package, you may need to
initialize the data directory:

   * Windows distributions prior to MySQL 5.7.7 include a data directory
     with a set of preinitialized accounts in the 'mysql' database.

   * As of 5.7.7, Windows installation operations performed using the
     'noinstall' package do not include a data directory.  To initialize
     the data directory, use the instructions at
     data-directory-initialization-mysqld.

2.3.5.5 Starting the Server for the First Time
..............................................

This section gives a general overview of starting the MySQL server.  The
following sections provide more specific information for starting the
MySQL server from the command line or as a Windows service.

The information here applies primarily if you installed MySQL using the
'noinstall' version, or if you wish to configure and test MySQL manually
rather than with the GUI tools.

*Note*:

The MySQL server will automatically start after using MySQL Installer,
and MySQL Notifier can be used to
start/stop/restart at any time.

The examples in these sections assume that MySQL is installed under the
default location of 'C:\Program Files\MySQL\MySQL Server 5.7'.  Adjust
the path names shown in the examples if you have MySQL installed in a
different location.

Clients have two options.  They can use TCP/IP, or they can use a named
pipe if the server supports named-pipe connections.

MySQL for Windows also supports shared-memory connections if the server
is started with the '--shared-memory' option.  Clients can connect
through shared memory by using the '--protocol=MEMORY' option.

For information about which server binary to run, see
windows-select-server.

Testing is best done from a command prompt in a console window (or 'DOS
window').  In this way you can have the server display status messages
in the window where they are easy to see.  If something is wrong with
your configuration, these messages make it easier for you to identify
and fix any problems.

*Note*:

The database must be initialized before MySQL can be started.  For
additional information about the initialization process, see
data-directory-initialization-mysqld.

To start the server, enter this command:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld" --console

For a server that includes 'InnoDB' support, you should see the messages
similar to those following as it starts (the path names and sizes may
differ):

     InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist:
     InnoDB: a new database to be created!
     InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200
     InnoDB: Database physically writes the file full: wait...
     InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280
     InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
     InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
     InnoDB: Doublewrite buffer not found: creating new
     InnoDB: Doublewrite buffer created
     InnoDB: creating foreign key constraint system tables
     InnoDB: foreign key constraint system tables created
     011024 10:58:25  InnoDB: Started

When the server finishes its startup sequence, you should see something
like this, which indicates that the server is ready to service client
connections:

     mysqld: ready for connections
     Version: '5.7.23'  socket: ''  port: 3306

The server continues to write to the console any further diagnostic
output it produces.  You can open a new console window in which to run
client programs.

If you omit the '--console' option, the server writes diagnostic output
to the error log in the data directory ('C:\Program Files\MySQL\MySQL
Server 5.7\data' by default).  The error log is the file with the '.err'
extension, and may be set using the '--log-error' option.

*Note*:

The initial 'root' account in the MySQL grant tables has no password.
After starting the server, you should set up a password for it using the
instructions in default-privileges.

2.3.5.6 Starting MySQL from the Windows Command Line
....................................................

The MySQL server can be started manually from the command line.  This
can be done on any version of Windows.

*Note*:

MySQL Notifier can also be used to
start/stop/restart the MySQL server.

To start the 'mysqld' server from the command line, you
should start a console window (or 'DOS window') and enter this command:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld"

The path to 'mysqld' may vary depending on the install
location of MySQL on your system.

You can stop the MySQL server by executing this command:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqladmin" -u root shutdown

*Note*:

If the MySQL 'root' user account has a password, you need to invoke
'mysqladmin' with the '-p' option and supply the
password when prompted.

This command invokes the MySQL administrative utility
'mysqladmin' to connect to the server and tell it to shut
down.  The command connects as the MySQL 'root' user, which is the
default administrative account in the MySQL grant system.

*Note*:

Users in the MySQL grant system are wholly independent from any login
users under Microsoft Windows.

If 'mysqld' doesn't start, check the error log to see
whether the server wrote any messages there to indicate the cause of the
problem.  By default, the error log is located in the 'C:\Program
Files\MySQL\MySQL Server 5.7\data' directory.  It is the file with a
suffix of '.err', or may be specified by passing in the '--log-error'
option.  Alternatively, you can try to start the server with the
'--console' option; in this case, the server may display some useful
information on the screen that will help solve the problem.

The last option is to start 'mysqld' with the
'--standalone' and '--debug' options.  In this case, see 'mysqld'
writes a log file 'C:\mysqld.trace' that should contain the
reason why 'mysqld' doesn't start.  See
dbug-package.

Use 'mysqld --verbose --help' to display all the options
that 'mysqld' supports.

2.3.5.7 Customizing the PATH for MySQL Tools
............................................

*Warning*:

You must exercise great care when editing your system 'PATH' by hand;
accidental deletion or modification of any portion of the existing
'PATH' value can leave you with a malfunctioning or even unusable
system.

To make it easier to invoke MySQL programs, you can add the path name of
the MySQL 'bin' directory to your Windows system 'PATH' environment
variable:

   * On the Windows desktop, right-click the 'My Computer' icon, and
     select 'Properties'.

   * Next select the 'Advanced' tab from the 'System Properties' menu
     that appears, and click the 'Environment Variables' button.

   * Under 'System Variables', select 'Path', and then click the 'Edit'
     button.  The 'Edit System Variable' dialogue should appear.

   * Place your cursor at the end of the text appearing in the space
     marked 'Variable Value'.  (Use the 'End' key to ensure that your
     cursor is positioned at the very end of the text in this space.)
     Then enter the complete path name of your MySQL 'bin' directory
     (for example, 'C:\Program Files\MySQL\MySQL Server 5.7\bin')

     *Note*:

     There must be a semicolon separating this path from any values
     present in this field.

     Dismiss this dialogue, and each dialogue in turn, by clicking 'OK'
     until all of the dialogues that were opened have been dismissed.
     The new 'PATH' value should now be available to any new command
     shell you open, allowing you to invoke any MySQL executable program
     by typing its name at the DOS prompt from any directory on the
     system, without having to supply the path.  This includes the
     servers, the 'mysql' client, and all MySQL
     command-line utilities such as 'mysqladmin' and
     'mysqldump'.

You should not add the MySQL 'bin' directory to your Windows 'PATH' if
you are running multiple MySQL servers on the same machine.

2.3.5.8 Starting MySQL as a Windows Service
...........................................

On Windows, the recommended way to run MySQL is to install it as a
Windows service, so that MySQL starts and stops automatically when
Windows starts and stops.  A MySQL server installed as a service can
also be controlled from the command line using 'NET' commands, or with
the graphical 'Services' utility.  Generally, to install MySQL as a
Windows service you should be logged in using an account that has
administrator rights.

*Note*:

MySQL Notifier can also be used to monitor the
status of the MySQL service.

The 'Services' utility (the Windows 'Service Control Manager') can be
found in the Windows Control Panel (under 'Administrative Tools' on
Windows Vista, and Server 2003).  To avoid conflicts, it is advisable to
close the 'Services' utility while performing server installation or
removal operations from the command line.

*Installing the service*

Before installing MySQL as a Windows service, you should first stop the
current server if it is running by using the following command:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqladmin"
               -u root shutdown

*Note*:

If the MySQL 'root' user account has a password, you need to invoke
'mysqladmin' with the '-p' option and supply the
password when prompted.

This command invokes the MySQL administrative utility
'mysqladmin' to connect to the server and tell it to shut
down.  The command connects as the MySQL 'root' user, which is the
default administrative account in the MySQL grant system.

*Note*:

Users in the MySQL grant system are wholly independent from any login
users under Windows.

Install the server as a service using this command:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld" --install

The service-installation command does not start the server.
Instructions for that are given later in this section.

To make it easier to invoke MySQL programs, you can add the path name of
the MySQL 'bin' directory to your Windows system 'PATH' environment
variable:

   * On the Windows desktop, right-click the 'My Computer' icon, and
     select 'Properties'.

   * Next select the 'Advanced' tab from the 'System Properties' menu
     that appears, and click the 'Environment Variables' button.

   * Under 'System Variables', select 'Path', and then click the 'Edit'
     button.  The 'Edit System Variable' dialogue should appear.

   * Place your cursor at the end of the text appearing in the space
     marked 'Variable Value'.  (Use the 'End' key to ensure that your
     cursor is positioned at the very end of the text in this space.)
     Then enter the complete path name of your MySQL 'bin' directory
     (for example, 'C:\Program Files\MySQL\MySQL Server 5.7\bin'), and
     there should be a semicolon separating this path from any values
     present in this field.  Dismiss this dialogue, and each dialogue in
     turn, by clicking 'OK' until all of the dialogues that were opened
     have been dismissed.  You should now be able to invoke any MySQL
     executable program by typing its name at the DOS prompt from any
     directory on the system, without having to supply the path.  This
     includes the servers, the 'mysql' client, and all
     MySQL command-line utilities such as 'mysqladmin'
     and 'mysqldump'.

     You should not add the MySQL 'bin' directory to your Windows 'PATH'
     if you are running multiple MySQL servers on the same machine.

*Warning*:

You must exercise great care when editing your system 'PATH' by hand;
accidental deletion or modification of any portion of the existing
'PATH' value can leave you with a malfunctioning or even unusable
system.

The following additional arguments can be used when installing the
service:

   * You can specify a service name immediately following the
     '--install' option.  The default service name is 'MySQL'.

   * If a service name is given, it can be followed by a single option.
     By convention, this should be '--defaults-file=FILE_NAME' to
     specify the name of an option file from which the server should
     read options when it starts.

     The use of a single option other than '--defaults-file' is possible
     but discouraged.  '--defaults-file' is more flexible because it
     enables you to specify multiple startup options for the server by
     placing them in the named option file.

   * You can also specify a '--local-service' option following the
     service name.  This causes the server to run using the
     'LocalService' Windows account that has limited system privileges.
     If both '--defaults-file' and '--local-service' are given following
     the service name, they can be in any order.

For a MySQL server that is installed as a Windows service, the following
rules determine the service name and option files that the server uses:

   * If the service-installation command specifies no service name or
     the default service name ('MySQL') following the '--install'
     option, the server uses the service name of 'MySQL' and reads
     options from the '[mysqld]' group in the standard option files.

   * If the service-installation command specifies a service name other
     than 'MySQL' following the '--install' option, the server uses that
     service name.  It reads options from the '[mysqld]' group and the
     group that has the same name as the service in the standard option
     files.  This enables you to use the '[mysqld]' group for options
     that should be used by all MySQL services, and an option group with
     the service name for use by the server installed with that service
     name.

   * If the service-installation command specifies a '--defaults-file'
     option after the service name, the server reads options the same
     way as described in the previous item, except that it reads options
     only from the named file and ignores the standard option files.

As a more complex example, consider the following command:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld"
               --install MySQL --defaults-file=C:\my-opts.cnf

Here, the default service name ('MySQL') is given after the '--install'
option.  If no '--defaults-file' option had been given, this command
would have the effect of causing the server to read the '[mysqld]' group
from the standard option files.  However, because the '--defaults-file'
option is present, the server reads options from the '[mysqld]' option
group, and only from the named file.

*Note*:

On Windows, if the server is started with the '--defaults-file' and
'--install' options, '--install' must be first.  Otherwise, 'mysqld.exe'
will attempt to start the MySQL server.

You can also specify options as Start parameters in the Windows
'Services' utility before you start the MySQL service.

Finally, before trying to start the MySQL service, make sure the user
variables '%TEMP%' and '%TMP%' (and also '%TMPDIR%', if it has ever been
set) for the system user who is to run the service are pointing to a
folder to which the user has write access.  The default user for running
the MySQL service is 'LocalSystem', and the default value for its
'%TEMP%' and '%TMP%' is 'C:\Windows\Temp', a directory 'LocalSystem' has
write access to by default.  However, if there are any changes to that
default setup (for example, changes to the user who runs the service or
to the mentioned user variables, or the '--tmpdir' option has been used
to put the temporary directory somewhere else), the MySQL service might
fail to run because write access to the temporary directory has not been
granted to the proper user.

*Starting the service*

After a MySQL server instance has been installed as a service, Windows
starts the service automatically whenever Windows starts.  The service
also can be started immediately from the 'Services' utility, or by using
a 'NET START MySQL' command.  The 'NET' command is not case-sensitive.

When run as a service, see 'mysqld' has no access to a
console window, so no messages can be seen there.  If 'mysqld'
does not start, check the error log to see whether the server
wrote any messages there to indicate the cause of the problem.  The
error log is located in the MySQL data directory (for example,
'C:\Program Files\MySQL\MySQL Server 5.7\data').  It is the file with a
suffix of '.err'.

When a MySQL server has been installed as a service, and the service is
running, Windows stops the service automatically when Windows shuts
down.  The server also can be stopped manually by using the 'Services'
utility, the 'NET STOP MySQL' command, or the 'mysqladmin shutdown'
command.

You also have the choice of installing the server as a manual service if
you do not wish for the service to be started automatically during the
boot process.  To do this, use the '--install-manual' option rather than
the '--install' option:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld" --install-manual

*Removing the service*

To remove a server that is installed as a service, first stop it if it
is running by executing 'NET STOP MySQL'.  Then use the '--remove'
option to remove it:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld" --remove

If 'mysqld' is not running as a service, you can start it
from the command line.  For instructions, see
windows-start-command-line.

If you encounter difficulties during installation, see
windows-troubleshooting.

For more information about stopping or removing a MySQL Windows service,
see multiple-windows-services.

2.3.5.9 Testing The MySQL Installation
......................................

You can test whether the MySQL server is working by executing any of the
following commands:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqlshow"
     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqlshow" -u root mysql
     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqladmin" version status proc
     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysql" test

If 'mysqld' is slow to respond to TCP/IP connections from
client programs, there is probably a problem with your DNS. In this
case, start 'mysqld' with the '--skip-name-resolve'
option and use only 'localhost' and IP addresses in the 'Host' column of
the MySQL grant tables.  (Be sure that an account exists that specifies
an IP address or you may not be able to connect.)

You can force a MySQL client to use a named-pipe connection rather than
TCP/IP by specifying the '--pipe' or '--protocol=PIPE' option, or by
specifying '.' (period) as the host name.  Use the '--socket' option to
specify the name of the pipe if you do not want to use the default pipe
name.

If you have set a password for the 'root' account, deleted the anonymous
account, or created a new user account, then to connect to the MySQL
server you must use the appropriate '-u' and '-p' options with the
commands shown previously.  See connecting.

For more information about 'mysqlshow', see
mysqlshow.

2.3.6 Troubleshooting a Microsoft Windows MySQL Server Installation
-------------------------------------------------------------------

When installing and running MySQL for the first time, you may encounter
certain errors that prevent the MySQL server from starting.  This
section helps you diagnose and correct some of these errors.

Your first resource when troubleshooting server issues is the error log.
The MySQL server uses the error log to record information relevant to
the error that prevents the server from starting.  The error log is
located in the data directory specified in your 'my.ini' file.  The
default data directory location is 'C:\Program Files\MySQL\MySQL Server
5.7\data', or 'C:\ProgramData\Mysql' on Windows 7 and Windows Server
2008.  The 'C:\ProgramData' directory is hidden by default.  You need to
change your folder options to see the directory and contents.  For more
information on the error log and understanding the content, see
error-log.

For information regarding possible errors, also consult the console
messages displayed when the MySQL service is starting.  Use the 'NET
START MySQL' command from the command line after installing
'mysqld' as a service to see any error messages regarding the
starting of the MySQL server as a service.  See
windows-start-service.

The following examples show other common error messages you might
encounter when installing MySQL and starting the server for the first
time:

   * If the MySQL server cannot find the 'mysql' privileges database or
     other critical files, it displays these messages:

          System error 1067 has occurred.
          Fatal error: Can't open and lock privilege tables:
          Table 'mysql.user' doesn't exist

     These messages often occur when the MySQL base or data directories
     are installed in different locations than the default locations
     ('C:\Program Files\MySQL\MySQL Server 5.7' and 'C:\Program
     Files\MySQL\MySQL Server 5.7\data', respectively).

     This situation can occur when MySQL is upgraded and installed to a
     new location, but the configuration file is not updated to reflect
     the new location.  In addition, old and new configuration files
     might conflict.  Be sure to delete or rename any old configuration
     files when upgrading MySQL.

     If you have installed MySQL to a directory other than 'C:\Program
     Files\MySQL\MySQL Server 5.7', ensure that the MySQL server is
     aware of this through the use of a configuration ('my.ini') file.
     Put the 'my.ini' file in your Windows directory, typically
     'C:\WINDOWS'.  To determine its exact location from the value of
     the 'WINDIR' environment variable, issue the following command from
     the command prompt:

          C:\> echo %WINDIR%

     You can create or modify an option file with any text editor, such
     as Notepad.  For example, if MySQL is installed in 'E:\mysql' and
     the data directory is 'D:\MySQLdata', you can create the option
     file and set up a '[mysqld]' section to specify values for the
     'basedir' and 'datadir' options:

          [mysqld]
          # set basedir to your installation path
          basedir=E:/mysql
          # set datadir to the location of your data directory
          datadir=D:/MySQLdata

     Microsoft Windows path names are specified in option files using
     (forward) slashes rather than backslashes.  If you do use
     backslashes, double them:

          [mysqld]
          # set basedir to your installation path
          basedir=C:\\Program Files\\MySQL\\MySQL Server 5.7
          # set datadir to the location of your data directory
          datadir=D:\\MySQLdata

     The rules for use of backslash in option file values are given in
     option-files.

     If you change the 'datadir' value in your MySQL configuration file,
     you must move the contents of the existing MySQL data directory
     before restarting the MySQL server.

     See windows-create-option-file.

   * If you reinstall or upgrade MySQL without first stopping and
     removing the existing MySQL service and install MySQL using the
     MySQL Installer, you might see this error:

          Error: Cannot create Windows service for MySql. Error: 0

     This occurs when the Configuration Wizard tries to install the
     service and finds an existing service with the same name.

     One solution to this problem is to choose a service name other than
     'mysql' when using the configuration wizard.  This enables the new
     service to be installed correctly, but leaves the outdated service
     in place.  Although this is harmless, it is best to remove old
     services that are no longer in use.

     To permanently remove the old 'mysql' service, execute the
     following command as a user with administrative privileges, on the
     command line:

          C:\> sc delete mysql
          [SC] DeleteService SUCCESS

     If the 'sc' utility is not available for your version of Windows,
     download the 'delsrv' utility from
     <http://www.microsoft.com/windows2000/techinfo/reskit/tools/existing/delsrv-o.asp>
     and use the 'delsrv mysql' syntax.

2.3.7 Windows Postinstallation Procedures
-----------------------------------------

GUI tools exist that perform most of the tasks described in this
section, including:

   * MySQL Installer.: Used to install and
     upgrade MySQL products.

   * MySQL Workbench.: Manages the MySQL server and
     edits SQL statements.

   * MySQL Notifier.: Starts, stops, or restarts
     the MySQL server, and monitors its status.

   * MySQL for Excel (http://dev.mysql.com/doc/mysql-for-excel/en/):
     Edits MySQL data with Microsoft Excel.

If necessary, initialize the data directory and create the MySQL grant
tables.  Windows distributions prior to MySQL 5.7.7 include a data
directory with a set of preinitialized accounts in the 'mysql' database.
As of 5.7.7, Windows installation operations performed by MySQL
Installer initialize the data directory automatically.  For installation
from a ZIP Archive package, you can initialize the data directory as
described at data-directory-initialization-mysqld.

Regarding passwords, if you installed MySQL using the MySQL Installer,
you may have already assigned a passwords to the initial 'root' account.
(See mysql-installer.)  Otherwise, use the password-assignment
procedure given in default-privileges.

Before assigning passwords, you might want to try running some client
programs to make sure that you can connect to the server and that it is
operating properly.  Make sure that the server is running (see
windows-server-first-start).  You can also set up a MySQL service that
runs automatically when Windows starts (see
windows-start-service).

These instructions assume that your current location is the MySQL
installation directory and that it has a 'bin' subdirectory containing
the MySQL programs used here.  If that is not true, adjust the command
path names accordingly.

If you installed MySQL using MySQL Installer (see
mysql-installer), the default installation directory is 'C:\Program
Files\MySQL\MySQL Server 5.7':

     C:\> cd "C:\Program Files\MySQL\MySQL Server 5.7"

A common installation location for installation from a ZIP archive is
'C:\mysql':

     C:\> cd C:\mysql

Alternatively, add the 'bin' directory to your 'PATH' environment
variable setting.  That enables your command interpreter to find MySQL
programs properly, so that you can run a program by typing only its
name, not its path name.  See mysql-installation-windows-path.

With the server running, issue the following commands to verify that you
can retrieve information from the server.  The output should be similar
to that shown here.

Use 'mysqlshow' to see what databases exist:

     C:\> bin\mysqlshow
     +--------------------+
     |     Databases      |
     +--------------------+
     | information_schema |
     | mysql              |
     | performance_schema |
     | sys                |
     +--------------------+

The list of installed databases may vary, but will always include the
minimum of 'mysql' and 'information_schema'.  Before MySQL 5.7.7, a
'test' database may also be created automatically.

The preceding command (and commands for other MySQL programs such as
'mysql') may not work if the correct MySQL account does
not exist.  For example, the program may fail with an error, or you may
not be able to view all databases.  If you installed MySQL using MySQL
Installer, the 'root' user will have been created automatically with the
password you supplied.  In this case, you should use the '-u root' and
'-p' options.  (You must use those options if you have already secured
the initial MySQL accounts.)  With '-p', the client program prompts for
the 'root' password.  For example:

     C:\> bin\mysqlshow -u root -p
     Enter password: (ENTER ROOT PASSWORD HERE)
     +--------------------+
     |     Databases      |
     +--------------------+
     | information_schema |
     | mysql              |
     | performance_schema |
     | sys                |
     +--------------------+

If you specify a database name, see 'mysqlshow' displays a
list of the tables within the database:

     C:\> bin\mysqlshow mysql
     Database: mysql
     +---------------------------+
     |          Tables           |
     +---------------------------+
     | columns_priv              |
     | db                        |
     | engine_cost               |
     | event                     |
     | func                      |
     | general_log               |
     | gtid_executed             |
     | help_category             |
     | help_keyword              |
     | help_relation             |
     | help_topic                |
     | innodb_index_stats        |
     | innodb_table_stats        |
     | ndb_binlog_index          |
     | plugin                    |
     | proc                      |
     | procs_priv                |
     | proxies_priv              |
     | server_cost               |
     | servers                   |
     | slave_master_info         |
     | slave_relay_log_info      |
     | slave_worker_info         |
     | slow_log                  |
     | tables_priv               |
     | time_zone                 |
     | time_zone_leap_second     |
     | time_zone_name            |
     | time_zone_transition      |
     | time_zone_transition_type |
     | user                      |
     +---------------------------+

Use the 'mysql' program to select information from a table
in the 'mysql' database:

     C:\> bin\mysql -e "SELECT User, Host, plugin FROM mysql.user" mysql
     +------+-----------+-----------------------+
     | User | Host      | plugin                |
     +------+-----------+-----------------------+
     | root | localhost | mysql_native_password |
     +------+-----------+-----------------------+

For more information about 'mysql' and 'mysqlshow',
see mysql, and mysqlshow.

2.3.8 Upgrading MySQL on Windows
--------------------------------

There are two approaches for upgrading MySQL on Windows:

   * Using MySQL Installer

   * Using the Windows ZIP archive distribution

The approach you select depends on how the existing installation was
performed.  Before proceeding, review upgrading for additional
information on upgrading MySQL that is not specific to Windows.

Upgrades between milestone releases (or from a milestone release to a GA
release) are not supported.  Significant development changes take place
in milestone releases and you may encounter compatibility issues or
problems starting the server.  For instructions on how to perform a
logical upgrade with a milestone release, see
upgrade-procedure-logical.

*Upgrading MySQL with MySQL Installer*

Performing an upgrade with MySQL Installer is the best approach when the
current server installation was performed with it and the upgrade is
within the current release series.  MySQL Installer does not support
upgrades between release series, such as from 5.6 to 5.7, and it does
not provide an upgrade indicator to prompt you to upgrade.  For
instruction on upgrading between release series, see
windows-upgrading-zip-distribution.

To perform an upgrade using MySQL Installer:

  1. Start MySQL Installer.

  2. From the dashboard, click 'Catalog' to download the latest changes
     to the catalog.  The installed server can be upgraded only if the
     dashboard displays an arrow next to the version number of the
     server.

  3. Click 'Upgrade'.  All products that have newer versions will appear
     in a list.

     *Note*:

     For server milestone releases in the same release series, MySQL
     Installer deselects the server upgrade and displays a warning to
     indicate that the upgrade is not supported, identifies the risks of
     continuing, and provides a summary of the steps to perform a
     logical upgrade manually.  You can reselect server upgrade and
     proceed at your own risk.

  4. Deselect all but the MySQL server product, unless you intend to
     upgrade other products at this time, and click 'Next'.

  5. Click 'Execute' to start the download.  When the download finishes,
     click 'Next' to apply the updates.

  6. Configure the server.

*Upgrading MySQL Using the Windows ZIP Distribution*

To perform an upgrade using the Windows ZIP archive distribution:

  1. Always back up your current MySQL installation before performing an
     upgrade.  See backup-methods.

  2. Download the latest Windows ZIP Archive distribution of MySQL from
     <http://dev.mysql.com/downloads/>.

  3. Before upgrading MySQL, stop the server.  If the server is
     installed as a service, stop the service with the following command
     from the command prompt:

          C:\> NET STOP MySQL

     If you are not running the MySQL server as a service, use
     'mysqladmin' to stop it.  For example, before
     upgrading from MySQL 5.6 to 5.7, use 'mysqladmin'
     from MySQL 5.6 as follows:

          C:\> "C:\Program Files\MySQL\MySQL Server 5.6\bin\mysqladmin" -u root shutdown

     *Note*:

     If the MySQL 'root' user account has a password, invoke
     'mysqladmin' with the '-p' option and enter the
     password when prompted.

  4. Extract the ZIP archive.  You may either overwrite your existing
     MySQL installation (usually located at 'C:\mysql'), or install it
     into a different directory, such as 'C:\mysql5'.  Overwriting the
     existing installation is recommended.

  5. If you were running MySQL as a Windows service and you had to
     remove the service earlier in this procedure, reinstall the
     service.  (See windows-start-service.)

  6. Restart the server.  For example, use 'NET START MySQL' if you run
     MySQL as a service, or invoke 'mysqld' directly
     otherwise.

  7. As Administrator, run 'mysql_upgrade' to
     check your tables, attempt to repair them if necessary, and update
     your grant tables if they have changed so that you can take
     advantage of any new capabilities.  See mysql-upgrade.

  8. If you encounter errors, see windows-troubleshooting.

2.3.9 Deploying MySQL on Windows and Other Non-Linux Platforms
--------------------------------------------------------------

*Warning*:

The MySQL Docker images provided by Oracle are built specifically for
Linux platforms.  Other platforms are not supported, and users running
the MySQL Docker images from Oracle on them are doing so at their own
risk.  This section discusses some known issues for the images when used
on non-Linux platforms.

Known Issues for using the MySQL Server Docker images from Oracle on
Windows include:

   * If you are bind-mounting on the container's MySQL data directory
     (see docker-persisting-data-configuration for details), you
     have to set the location of the server socket file with the
     '--socket' option to somewhere outside of the MySQL data directory;
     otherwise, the server will fail to start.  This is because the way
     Docker for Windows handles file mounting does not allow a host file
     from being bind-mounted on the socket file.

2.4 Installing MySQL on macOS
=============================

For a list of macOS versions that the MySQL server supports, see
<http://www.mysql.com/support/supportedplatforms/database.html>.

MySQL for macOS is available in a number of different forms:

   * Native Package Installer, which uses the native macOS installer
     (DMG) to walk you through the installation of MySQL. For more
     information, see osx-installation-pkg.  You can use the
     package installer with macOS. The user you use to perform the
     installation must have administrator privileges.

   * Compressed TAR archive, which uses a file packaged using the Unix
     'tar' and 'gzip' commands.  To use this method, you will need to
     open a 'Terminal' window.  You do not need administrator privileges
     using this method, as you can install the MySQL server anywhere
     using this method.  For more information on using this method, you
     can use the generic instructions for using a tarball, see
     binary-installation.

     In addition to the core installation, the Package Installer also
     includes osx-installation-launchd and
     osx-installation-prefpane, both of which simplify the management
     of your installation.

For additional information on using MySQL on macOS, see
osx-installation-notes.

2.4.1 General Notes on Installing MySQL on macOS
------------------------------------------------

You should keep the following issues and notes in mind:

   * A launchd daemon is installed, and it includes MySQL configuration
     options.  Consider editing it if needed, see the documentation
     below for additional information.  Also, macOS 10.10 removed
     startup item support in favor of launchd daemons.  The optional
     MySQL preference pane under macOS 'System Preferences' uses the
     launchd daemon.

   * You may need (or want) to create a specific 'mysql' user to own the
     MySQL directory and data.  You can do this through the 'Directory
     Utility', and the 'mysql' user should already exist.  For use in
     single user mode, an entry for '_mysql' (note the underscore
     prefix) should already exist within the system '/etc/passwd' file.

   * Because the MySQL package installer installs the MySQL contents
     into a version and platform specific directory, you can use this to
     upgrade and migrate your database between versions.  You will need
     to either copy the 'data' directory from the old version to the new
     version, or alternatively specify an alternative 'datadir' value to
     set location of the data directory.  By default, the MySQL
     directories are installed under '/usr/local/'.

   * You might want to add aliases to your shell's resource file to make
     it easier to access commonly used programs such as 'mysql'
     and 'mysqladmin' from the command line.
     The syntax for 'bash' is:

          alias mysql=/usr/local/mysql/bin/mysql
          alias mysqladmin=/usr/local/mysql/bin/mysqladmin

     For 'tcsh', use:

          alias mysql /usr/local/mysql/bin/mysql
          alias mysqladmin /usr/local/mysql/bin/mysqladmin

     Even better, add '/usr/local/mysql/bin' to your 'PATH' environment
     variable.  You can do this by modifying the appropriate startup
     file for your shell.  For more information, see
     invoking-programs.

   * After you have copied over the MySQL database files from the
     previous installation and have successfully started the new server,
     you should consider removing the old installation files to save
     disk space.  Additionally, you should also remove older versions of
     the Package Receipt directories located in
     '/Library/Receipts/mysql-VERSION.pkg'.

   * Prior to OS X 10.7, MySQL server was bundled with OS X Server.

2.4.2 Installing MySQL on macOS Using Native Packages
-----------------------------------------------------

The package is located inside a disk image ('.dmg') file that you first
need to mount by double-clicking its icon in the Finder.  It should then
mount the image and display its contents.

*Note*:

Before proceeding with the installation, be sure to stop all running
MySQL server instances by using either the MySQL Manager Application (on
macOS Server), the preference pane, or 'mysqladmin shutdown'
on the command line.

To install MySQL using the package installer:

  1. Download the disk image ('.dmg') file (the community version is
     available here (http://dev.mysql.com/downloads/mysql/)) that
     contains the MySQL package installer.  Double-click the file to
     mount the disk image and see its contents.

     FIGURE GOES HERE: MySQL Package Installer: DMG Contents

  2. Double-click the MySQL installer package from the disk.  It is
     named according to the version of MySQL you have downloaded.  For
     example, for MySQL server 5.7.23 it might be named
     'mysql-5.7.23-osx-10.13-X86_64.pkg'.

  3. The initial wizard introduction screen references the MySQL server
     version to install.  Click 'Continue' to begin the installation.

     FIGURE GOES HERE: MySQL Package Installer Wizard: Introduction

  4. The MySQL community edition shows a copy of the relevant GNU
     General Public License.  Click 'Continue' and then 'Agree' to
     continue.

  5. From the 'Installation Type' page you can either click 'Install' to
     execute the installation wizard using all defaults, click
     'Customize' to alter which components to install (MySQL server,
     Preference Pane, Launchd Support - all enabled by default).

     *Note*:

     Although the 'Change Install Location' option is visible, the
     installation location cannot be changed.

     FIGURE GOES HERE: MySQL Package Installer Wizard: Installation Type

     FIGURE GOES HERE: MySQL Package Installer Wizard: Customize

  6. Click 'Install' to begin the installation process.

  7. After a successful installation, the installer displays a window
     with your temporary root password.  This cannot be recovered so you
     must save this password for the initial login to MySQL. For
     example:

     FIGURE GOES HERE: MySQL Package Installer Wizard: Temporary Root
     Password

     *Note*:

     MySQL expires this temporary root password after the initial login
     and requires you to create a new password.

  8. 'Summary' is the final step and references a successful and
     complete MySQL Server installation.  'Close' the wizard.

     FIGURE GOES HERE: MySQL Package Installer Wizard: Summary

MySQL server is now installed, but it is not loaded (or started) by
default.  Use either launchctl from the command line, or start MySQL by
clicking "Start" using the MySQL preference pane.  For additional
information, see osx-installation-launchd, and
osx-installation-prefpane.  Use the MySQL Preference Pane or launchd
to configure MySQL to automatically start at bootup.

When installing using the package installer, the files are installed
into a directory within '/usr/local' matching the name of the
installation version and platform.  For example, the installer file
'mysql-5.7.23-OSX10.13-X86_64.DMG' installs MySQL into
'/usr/local/mysql-5.7.23-osx10.13-x86_64/ '.  The following table shows
the layout of the installation directory.

*MySQL Installation Layout on macOS*

Directory                        Contents of Directory

'bin'                            'mysqld' server, client
                                 and utility programs

'data'                           Log files, databases

'docs'                           Helper documents, like the Release
                                 Notes and build information

'include'                        Include (header) files

'lib'                            Libraries

'man'                            Unix manual pages

'mysql-test'                     MySQL test suite

'share'                          Miscellaneous support files, including
                                 error messages, sample configuration
                                 files, SQL for database installation

'support-files'                  Scripts and sample configuration files

'/tmp/mysql.sock'                Location of the MySQL Unix socket

During the package installer process, a symbolic link from
'/usr/local/mysql' to the version/platform specific directory created
during installation will be created automatically.

2.4.3 Installing a MySQL Launch Daemon
--------------------------------------

macOS uses launch daemons to automatically start, stop, and manage
processes and applications such as MySQL.

By default, the installation package (DMG) on macOS installs a launchd
file named '/Library/LaunchDaemons/com.oracle.oss.mysql.mysqld.plist'
that contains a plist definition similar to:

     <?xml version="1.0" encoding="utf-8"?>
     <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
     <plist version="1.0">
     <dict>
         <key>Label</key>             <string>com.oracle.oss.mysql.mysqld</string>
         <key>ProcessType</key>       <string>Interactive</string>
         <key>Disabled</key>          <false/>
         <key>RunAtLoad</key>         <true/>
         <key>KeepAlive</key>         <true/>
         <key>SessionCreate</key>     <true/>
         <key>LaunchOnlyOnce</key>    <false/>
         <key>UserName</key>          <string>_mysql</string>
         <key>GroupName</key>         <string>_mysql</string>
         <key>ExitTimeOut</key>       <integer>600</integer>
         <key>Program</key>           <string>/usr/local/mysql/bin/mysqld</string>
         <key>ProgramArguments</key>
             <array>
                 <string>/usr/local/mysql/bin/mysqld</string>
                 <string>--user=_mysql</string>
                 <string>--basedir=/usr/local/mysql</string>
                 <string>--datadir=/usr/local/mysql/data</string>
                 <string>--plugin-dir=/usr/local/mysql/lib/plugin</string>
                 <string>--log-error=/usr/local/mysql/data/mysqld.local.err</string>
                 <string>--pid-file=/usr/local/mysql/data/mysqld.local.pid</string>
             </array>
         <key>WorkingDirectory</key>  <string>/usr/local/mysql</string>
     </dict>
     </plist>

*Note*:

Some users report that adding a plist DOCTYPE declaration causes the
launchd operation to fail, despite it passing the lint check.  We
suspect it's a copy-n-paste error.  The md5 checksum of a file
containing the above snippet is _24710a27dc7a28fb7ee6d825129cd3cf_.

To enable the launchd service, you can either:

   * Click 'Start MySQL Server' from the MySQL preference pane.

     FIGURE GOES HERE: MySQL Preference Pane: Location

     FIGURE GOES HERE: MySQL Preference Pane: Usage

   * Or, manually load the launchd file.

          shell> cd /Library/LaunchDaemons
          shell> sudo launchctl load -F com.oracle.oss.mysql.mysqld.plist

   * To configure MySQL to automatically start at bootup, you can:

          shell> sudo launchctl load -w com.oracle.oss.mysql.mysqld.plist

*Note*:

When upgrading MySQL server, the launchd installation process will
remove the old startup items that were installed with MySQL server 5.7.7
and below.

Also, upgrading will replace your existing launchd file of the same
name.

Additional launchd related information:

   * The plist entries override 'my.cnf' entries, because they are
     passed in as command line arguments.  For additional information
     about passing in program options, see program-options.

   * The *ProgramArguments* section defines the command line options
     that are passed into the program, which is the 'mysqld' binary in
     this case.

   * The default plist definition is written with less sophisticated use
     cases in mind.  For more complicated setups, you may want to remove
     some of the arguments and instead rely on a MySQL configuration
     file, such as 'my.cnf'.

   * If you edit the plist file, then uncheck the installer option when
     reinstalling or upgrading MySQL. Otherwise, your edited plist file
     will be overwritten, and all edits will be lost.

Because the default plist definition defines several *ProgramArguments*,
you might remove most of these arguments and instead rely upon your
'my.cnf' MySQL configuration file to define them.  For example:

     <?xml version="1.0" encoding="utf-8"?>
     <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
     <plist version="1.0">
     <dict>
         <key>Label</key>             <string>com.oracle.oss.mysql.mysqld</string>
         <key>ProcessType</key>       <string>Interactive</string>
         <key>Disabled</key>          <false/>
         <key>RunAtLoad</key>         <true/>
         <key>KeepAlive</key>         <true/>
         <key>SessionCreate</key>     <true/>
         <key>LaunchOnlyOnce</key>    <false/>
         <key>UserName</key>          <string>_mysql</string>
         <key>GroupName</key>         <string>_mysql</string>
         <key>ExitTimeOut</key>       <integer>600</integer>
         <key>Program</key>           <string>/usr/local/mysql/bin/mysqld</string>
         <key>WorkingDirectory</key>  <string>/usr/local/mysql</string>
         <key>ProgramArguments</key>
             <array>
                 <string>/usr/local/mysql/bin/mysqld</string>
                 <string>--user=_mysql</string>
             </array>
     </dict>
     </plist>

In this case, the 'basedir', 'datadir', 'plugin_dir', 'log_error', and
'pid_file' options were removed from the plist definition, and then you
you might define them in 'my.cnf'.

2.4.4 Installing and Using the MySQL Preference Pane
----------------------------------------------------

The MySQL Installation Package includes a MySQL preference pane that
enables you to start, stop, and control automated startup during boot of
your MySQL installation.

This preference pane is installed by default, and is listed under your
system's _System Preferences_ window.

FIGURE GOES HERE: MySQL Preference Pane: Location

To install the MySQL Preference Pane:

  1. Download the disk image ('.dmg') file (the community version is
     available here (http://dev.mysql.com/downloads/mysql/)) that
     contains the MySQL package installer.  Double-click the file to
     mount the disk image and see its contents.

     FIGURE GOES HERE: MySQL Package Installer: DMG Contents

  2. Go through the process of installing the MySQL server, as described
     in the documentation at osx-installation-pkg.

  3. Click 'Customize' at the 'Installation Type' step.  The "Preference
     Pane" option is listed there and enabled by default; make sure it
     is not deselected.

     FIGURE GOES HERE: MySQL Installer on macOS: Customize

  4. Complete the MySQL server installation process.

*Note*:

The MySQL preference pane only starts and stops MySQL installation
installed from the MySQL package installation that have been installed
in the default location.

Once the MySQL preference pane has been installed, you can control your
MySQL server instance using the preference pane.  To use the preference
pane, open the 'System Preferences...' from the Apple menu.  Select the
MySQL preference pane by clicking the MySQL logo within the 'bottom'
section of the preference panes list.

FIGURE GOES HERE: MySQL Preference Pane: Location

FIGURE GOES HERE: MySQL Preference Pane: Usage

The MySQL Preference Pane shows the current status of the MySQL server,
showing 'stopped' (in red) if the server is not running and 'running'
(in green) if the server has already been started.  The preference pane
also shows the current setting for whether the MySQL server has been set
to start automatically.

   * *To start the MySQL server using the preference pane: *

     Click 'Start MySQL Server'.  You may be prompted for the username
     and password of a user with administrator privileges to start the
     MySQL server.

   * *To stop the MySQL server using the preference pane: *

     Click 'Stop MySQL Server'.  You may be prompted for the username
     and password of a user with administrator privileges to stop the
     MySQL server.

   * *To automatically start the MySQL server when the system boots:*

     Check the check box next to 'Automatically Start MySQL Server on
     Startup'.

   * *To disable automatic MySQL server startup when the system boots:*

     Uncheck the check box next to 'Automatically Start MySQL Server on
     Startup'.

You can close the 'System Preferences...' window once you have completed
your settings.

2.5 Installing MySQL on Linux
=============================

Linux supports a number of different solutions for installing MySQL. We
recommend that you use one of the distributions from Oracle, for which
several methods for installation are available:

*Linux Installation Methods and Information*

Type                   Setup Method           Additional Information

Apt                    Enable the MySQL Apt   Documentation.
                       (http://dev.mysql.com/downloads/repo/apt/)

Yum                    Enable the MySQL Yum   Documentation.
                       (http://dev.mysql.com/downloads/repo/yum/)

Zypper                 Enable the MySQL       Documentation.
                       (http://dev.mysql.com/downloads/repo/suse/)

RPM                    Download               Documentation (http://dev.mysql.com/downloads/mysql/).
                       a specific package

DEB                    Download               Documentation (http://dev.mysql.com/downloads/mysql/).
                       a specific package

Generic                Download               Documentation (http://dev.mysql.com/downloads/mysql/).
                       a generic package

Source                 Compile from source    Documentation (http://dev.mysql.com/downloads/mysql/).

Docker                 Use Docker Hub         Documentation.

Oracle Unbreakable     Use ULN channels       Documentation.

As an alternative, you can use the package manager on your system to
automatically download and install MySQL with packages from the native
software repositories of your Linux distribution.  These native packages
are often several versions behind the currently available release.  You
will also normally be unable to install development milestone releases
(DMRs), as these are not usually made available in the native
repositories.  For more information on using the native package
installers, see linux-installation-native.

*Note*:

For many Linux installations, you will want to set up MySQL to be
started automatically when your machine starts.  Many of the native
package installations perform this operation for you, but for source,
binary and RPM solutions you may need to set this up separately.  The
required script, see 'mysql.server', can be found in the
'support-files' directory under the MySQL installation directory or in a
MySQL source tree.  You can install it as '/etc/init.d/mysql' for
automatic MySQL startup and shutdown.  See mysql-server.

2.5.1 Installing MySQL on Linux Using the MySQL Yum Repository
--------------------------------------------------------------

The MySQL Yum repository (http://dev.mysql.com/downloads/repo/yum/) for
Oracle Linux, Red Hat Enterprise Linux, CentOS, and Fedora provides RPM
packages for installing the MySQL server, client, MySQL Workbench, MySQL
Utilities, MySQL Router, MySQL Shell, Connector/ODBC, Connector/Python
and so on (not all packages are available for all the distributions; see
yum-install-components for details).

*Before You Start*

As a popular, open-source software, MySQL, in its original or
re-packaged form, is widely installed on many systems from various
sources, including different software download sites, software
repositories, and so on.  The following instructions assume that MySQL
is not already installed on your system using a third-party-distributed
RPM package; if that is not the case, follow the instructions given in
updating-yum-repo or replace-third-party-yum.

*Steps for a Fresh Installation of MySQL*

Follow the steps below to install the latest GA version of MySQL with
the MySQL Yum repository:

  1. *Adding the MySQL Yum Repository*

     First, add the MySQL Yum repository to your system's repository
     list.  This is a one-time operation, which can be performed by
     installing an RPM provided by MySQL. Follow these steps:

       1. Go to the Download MySQL Yum Repository page
          (http://dev.mysql.com/downloads/repo/yum/
          (http://dev.mysql.com/downloads/repo/yum/)) in the MySQL
          Developer Zone.

       2. Select and download the release package for your platform.

       3. Install the downloaded release package with the following
          command, replacing PLATFORM-AND-VERSION-SPECIFIC-PACKAGE-NAME
          with the name of the downloaded RPM package:

               shell> sudo yum localinstall PLATFORM-AND-VERSION-SPECIFIC-PACKAGE-NAME.rpm

          For an EL6-based system, the command is in the form of:

               shell> sudo yum localinstall mysql57-community-release-el6-{VERSION-NUMBER}.noarch.rpm

          For an EL7-based system:

               shell> sudo yum localinstall mysql57-community-release-el7-{VERSION-NUMBER}.noarch.rpm

          For Fedora 26:

               shell> sudo dnf install mysql57-community-release-fc26-{VERSION-NUMBER}.noarch.rpm

          For Fedora 27:

               shell> sudo dnf install mysql57-community-release-fc27-{VERSION-NUMBER}.noarch.rpm

          The installation command adds the MySQL Yum repository to your
          system's repository list and downloads the GnuPG key to check
          the integrity of the software packages.  See
          checking-gpg-signature for details on GnuPG key checking.

          You can check that the MySQL Yum repository has been
          successfully added by the following command (for Fedora,
          replace 'yum' in the command with 'dnf'):

               shell> yum repolist enabled | grep "mysql.*-community.*"

     *Note*:

     Once the MySQL Yum repository is enabled on your system, any
     system-wide update by the 'yum update' command (or 'dnf upgrade'
     for Fedora) will upgrade MySQL packages on your system and also
     replace any native third-party packages, if Yum finds replacements
     for them in the MySQL Yum repository; see updating-yum-repo
     and, for a discussion on some possible effects of that on your
     system, see updating-yum-repo-client-lib.

  2. *Selecting a Release Series*

     When using the MySQL Yum repository, the latest GA series
     (currently MySQL 5.7) is selected for installation by default.  If
     this is what you want, you can skip to the next step, see
     yum-repo-installing-mysql.

     Within the MySQL Yum repository, different release series of the
     MySQL Community Server are hosted in different subrepositories.
     The subrepository for the latest GA series (currently MySQL 5.7) is
     enabled by default, and the subrepositories for all other series
     (for example, the MySQL 5.6 series) are disabled by default.  Use
     this command to see all the subrepositories in the MySQL Yum
     repository, and see which of them are enabled or disabled (for
     Fedora, replace 'yum' in the command with 'dnf'):

          shell> yum repolist all | grep mysql

     To install the latest release from the latest GA series, no
     configuration is needed.  To install the latest release from a
     specific series other than the latest GA series, disable the
     subrepository for the latest GA series and enable the subrepository
     for the specific series before running the installation command.
     If your platform supports 'yum-config-manager', you can do that by
     issuing these commands, which disable the subrepository for the 5.7
     series and enable the one for the 5.6 series:

          shell> sudo yum-config-manager --disable mysql57-community
          shell> sudo yum-config-manager --enable mysql56-community

     For Fedora platforms:

          shell> sudo dnf config-manager --disable mysql57-community
          shell> sudo dnf config-manager --enable mysql56-community

     Besides using 'yum-config-manager' or the 'dnf config-manager'
     command, you can also select a release series by editing manually
     the '/etc/yum.repos.d/mysql-community.repo' file.  This is a
     typical entry for a release series' subrepository in the file:

          [mysql57-community]
          name=MySQL 5.7 Community Server
          baseurl=http://repo.mysql.com/yum/mysql-5.7-community/el/6/$basearch/
          enabled=1
          gpgcheck=1
          gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-mysql

     Find the entry for the subrepository you want to configure, and
     edit the 'enabled' option.  Specify 'enabled=0' to disable a
     subrepository, or 'enabled=1' to enable a subrepository.  For
     example, to install MySQL 5.6, make sure you have 'enabled=0' for
     the above subrepository entry for MySQL 5.7, and have 'enabled=1'
     for the entry for the 5.6 series:

          # Enable to use MySQL 5.6
          [mysql56-community]
          name=MySQL 5.6 Community Server
          baseurl=http://repo.mysql.com/yum/mysql-5.6-community/el/6/$basearch/
          enabled=1
          gpgcheck=1
          gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-mysql

     You should only enable subrepository for one release series at any
     time.  When subrepositories for more than one release series are
     enabled, the latest series will be used by Yum.

     Verify that the correct subrepositories have been enabled and
     disabled by running the following command and checking its output
     (for Fedora, replace 'yum' in the command with 'dnf'):

          shell> yum repolist enabled | grep mysql

  3. *Installing MySQL*

     Install MySQL by the following command (for Fedora, replace 'yum'
     in the command with 'dnf'):

          shell> sudo yum install mysql-community-server

     This installs the package for MySQL server
     ('mysql-community-server') and also packages for the components
     required to run the server, including packages for the client
     ('mysql-community-client'), the common error messages and character
     sets for client and server ('mysql-community-common'), and the
     shared client libraries ('mysql-community-libs').

  4. *Starting the MySQL Server*

     Start the MySQL server with the following command:

          shell> sudo service mysqld start
          Starting mysqld:[ OK ]

     You can check the status of the MySQL server with the following
     command:

          shell> sudo service mysqld status
          mysqld (pid 3066) is running.

At the initial start up of the server, the following happens, given that
the data directory of the server is empty:

   * The server is initialized.

   * SSL certificate and key files are generated in the data directory.

   * 'validate_password' is installed and
     enabled.

   * A superuser account ''root'@'localhost' is created.  A password for
     the superuser is set and stored in the error log file.  To reveal
     it, use the following command:

          shell> sudo grep 'temporary password' /var/log/mysqld.log

     Change the root password as soon as possible by logging in with the
     generated, temporary password and set a custom password for the
     superuser account:

          shell> mysql -uroot -p

          mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass4!';

     *Note*:

     'validate_password' is installed by
     default.  The default password policy implemented by
     'validate_password' requires that passwords contain at least one
     upper case letter, one lower case letter, one digit, and one
     special character, and that the total password length is at least 8
     characters.

For more information on the postinstallation procedures, see
postinstallation.

*Note*:

_Compatibility Information for EL7-based platforms:_ The following RPM
packages from the native software repositories of the platforms are
incompatible with the package from the MySQL Yum repository that
installs the MySQL server.  Once you have installed MySQL using the
MySQL Yum repository, you will not be able to install these packages
(and vice versa).

   * akonadi-mysql

*Installing Additional MySQL Products and Components with Yum*

You can use Yum to install and manage individual components of MySQL.
Some of these components are hosted in sub-repositories of the MySQL Yum
repository: for example, the MySQL Connectors are to be found in the
MySQL Connectors Community sub-repository, and the MySQL Workbench in
MySQL Tools Community.  You can use the following command to list the
packages for all the MySQL components available for your platform from
the MySQL Yum repository (for Fedora, replace 'yum' in the command with
'dnf'):

     shell> sudo yum --disablerepo=\* --enablerepo='mysql*-community*' list available

Install any packages of your choice with the following command,
replacing PACKAGE-NAME with name of the package (for Fedora, replace
'yum' in the command with 'dnf'):

     shell> sudo yum install PACKAGE-NAME

For example, to install MySQL Workbench on Fedora:

     shell> sudo dnf install mysql-workbench-community

To install the shared client libraries (for Fedora, replace 'yum' in the
command with 'dnf'):

     shell> sudo yum install mysql-community-libs

*Updating MySQL with Yum*

Besides installation, you can also perform updates for MySQL products
and components using the MySQL Yum repository.  See
updating-yum-repo for details.

2.5.2 Replacing a Third-Party Distribution of MySQL Using the MySQL Yum Repository
----------------------------------------------------------------------------------

For supported Yum-based platforms (see
linux-installation-yum-repo, for a list), you can replace a
third-party distribution of MySQL with the latest GA release (from the
MySQL 5.7 series currently)

from the MySQL Yum repository.  According to how your third-party
distribution of MySQL was installed, there are different steps to
follow:

*Replacing a Native Third-Party Distribution of MySQL*

If you have installed a third-party distribution of MySQL from a native
software repository (that is, a software repository provided by your own
Linux distribution), follow these steps:

  1. *Backing Up Your Database*

     To avoid loss of data, always back up your database before trying
     to replace your MySQL installation using the MySQL Yum repository.
     See backup-and-recovery, on how to back up your database.

  2. *Adding the MySQL Yum Repository*

     Add the MySQL Yum repository to your system's repository list by
     following the instructions given in yum-repo-setup.

  3. *Replacing the Native Third-Party Distribution by a Yum Update or a
     DNF Upgrade*

     By design, the MySQL Yum repository will replace your native,
     third-party MySQL with the latest GA release (from the MySQL 5.7
     series currently) from the MySQL Yum repository when you perform a
     'yum update' command (or 'dnf upgrade' for Fedora) on the system,
     or a 'yum update mysql-server' (or 'dnf upgrade mysql-server' for
     Fedora).

After updating MySQL using the Yum repository, applications compiled
with older versions of the shared client libraries should continue to
work.  However, _if you want to recompile applications and dynamically
link them with the updated libraries_, see
updating-yum-repo-client-lib, for some special considerations.

*Replacing a Nonnative Third-Party Distribution of MySQL*

If you have installed a third-party distribution of MySQL from a
nonnative software repository (that is, a software repository not
provided by your own Linux distribution), follow these steps:

  1. *Backing Up Your Database*

     To avoid loss of data, always back up your database before trying
     to replace your MySQL installation using the MySQL Yum repository.
     See backup-and-recovery, on how to back up your database.

  2. *Stopping Yum from Receiving MySQL Packages from Third-Party,
     Nonnative Repositories*

     Before you can use the MySQL Yum repository for installing MySQL,
     you must stop your system from receiving MySQL packages from any
     third-party, nonnative Yum repositories.

     For example, if you have installed MariaDB using their own software
     repository, get a list of the installed MariaDB packages using the
     following command (for Fedora, replace 'yum' in the command with
     'dnf'):

          shell> yum list installed mariadb\*
          MariaDB-common.i686                      10.0.4-1                       @mariadb
          MariaDB-compat.i686                      10.0.4-1                       @mariadb
          MariaDB-server.i686                      10.0.4-1                       @mariadb

     From the command output, we can identify the installed packages
     ('MariaDB-common', 'MariaDB-compat', and 'MariaDB-server') and the
     source of them (a nonnative software repository named 'mariadb').

     As another example, if you have installed Percona using their own
     software repository, get a list of the installed Percona packages
     using the following command (for Fedora, replace 'yum' in the
     command with 'dnf'):

          shell> yum list installed Percona\*
          Percona-Server-client-55.i686     5.5.39-rel36.0.el6          @percona-release-i386
          Percona-Server-server-55.i686     5.5.39-rel36.0.el6          @percona-release-i386
          Percona-Server-shared-55.i686     5.5.39-rel36.0.el6          @percona-release-i386
          percona-release.noarch            0.1-3                       @/percona-release-0.1-3.noarch

     From the command output, we can identify the installed packages
     ('Percona-Server-client', 'Percona-Server-server',
     'Percona-Server-shared', and 'percona-release.noarch') and the
     source of them (a nonnative software repository named
     'percona-release').

     If you are not sure which third-party MySQL fork you have
     installed, this command should reveal it and list the RPM packages
     installed for it, as well as the third-party repository that
     supplies the packages (for Fedora, replace 'yum' in the command
     with 'dnf'):

          shell> yum --disablerepo=\* provides mysql\*

     The next step is to stop Yum from receiving packages from the
     nonnative repository.  If the 'yum-config-manager' utility is
     supported on your platform, you can, for example, use this command
     for stopping delivery from MariaDB (on Fedora, use the 'dnf
     config-manager' command instead of 'yum-config-manager'):

          shell> sudo yum-config-manager --disable mariadb

     Use this command for stopping delivery from Percona (on Fedora, use
     the 'dnf config-manager' command instead of 'yum-config-manager'):

          shell> sudo yum-config-manager --disable percona-release

     You can perform the same task by removing the entry for the
     software repository existing in one of the repository files under
     the '/etc/yum.repos.d/' directory.  This is how the entry typically
     looks for MariaDB:

          [mariadb] name = MariaDB
           baseurl = [BASE URL FOR REPOSITORY]
           gpgkey = [URL FOR GPG KEY]
           gpgcheck =1

     The entry is usually found in the file
     '/etc/yum.repos.d/MariaDB.repo' for MariaDB--delete the file, or
     remove entry from it (or from the file in which you find the
     entry).

     *Note*:

     This step is not necessary for an installation that was configured
     with a Yum repository release package (like Percona) if you are
     going to remove the release package ('percona-release.noarch' for
     Percona), as shown in the uninstall command for Percona in Step 3
     below.

  3. *Uninstalling the Nonnative Third-Party MySQL Distribution of
     MySQL*

     The nonnative third-party MySQL distribution must first be
     uninstalled before you can use the MySQL Yum repository to install
     MySQL. For the MariaDB packages found in Step 2 above, uninstall
     them with the following command (for Fedora, replace 'yum' in the
     command with 'dnf'):

          shell> sudo yum remove MariaDB-common MariaDB-compat MariaDB-server

     For the Percona packages we found in Step 2 above (for Fedora,
     replace 'yum' in the command with 'dnf'):

          shell> sudo yum remove Percona-Server-client-55 Percona-Server-server-55 \
            Percona-Server-shared-55.i686 percona-release

  4. *Installing MySQL with the MySQL Yum Repository*

     Then, install MySQL with the MySQL Yum repository by following the
     instructions given in linux-installation-yum-repo: .

     *Important*:

     If you have chosen to replace your third-party MySQL distribution
     with a newer version of MySQL from the MySQL Yum repository,
     remember to run 'mysql_upgrade' after the
     server starts, to check and possibly resolve any incompatibilities
     between the old data and the upgraded software.
     'mysql_upgrade' also performs other functions; see
     mysql-upgrade for details.

     _For EL7-based platforms:_ See
     yum-install-compatibility-el7.

2.5.3 Installing MySQL on Linux Using the MySQL APT Repository
--------------------------------------------------------------

The MySQL APT repository provides 'deb' packages for installing and
managing the MySQL server, client, and other components on Debian and
Ubuntu platforms.

Instructions for using the MySQL APT Repository are available in A Quick
Guide to Using the MySQL APT Repository
(http://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/).

2.5.4 Installing MySQL on Linux Using the MySQL SLES Repository
---------------------------------------------------------------

The MySQL SLES repository provides RPM packages for installing and
managing the MySQL server, client, and other components on SUSE
Enterprise Linux Server.

Instructions for using the MySQL SLES repository are available in A
Quick Guide to Using the MySQL SLES Repository
(http://dev.mysql.com/doc/mysql-sles-repo-quick-guide/en/).

*Note*:

The MySQL SLES repository is now in development release.  We encourage
you to try it and provide us with feedback.  Please report any bugs or
inconsistencies you observe to our Bugs Database
(http://bugs.mysql.com).

2.5.5 Installing MySQL on Linux Using RPM Packages from Oracle
--------------------------------------------------------------

The recommended way to install MySQL on RPM-based Linux distributions is
by using the RPM packages provided by Oracle.  There are two sources for
obtaining them, for the Community Edition of MySQL:

   * From the MySQL software repositories:

        * The MySQL Yum repository (see
          linux-installation-yum-repo for details).

        * The MySQL SLES repository (see
          linux-installation-sles-repo for details).

   * From the Download MySQL Community Server
     (http://dev.mysql.com/downloads/mysql/) page in the MySQL Developer
     Zone (http://dev.mysql.com/).

*Note*:

RPM distributions of MySQL are also provided by other vendors.  Be aware
that they may differ from those built by Oracle in features,
capabilities, and conventions (including communication setup), and that
the installation instructions in this manual do not necessarily apply to
them.  The vendor's instructions should be consulted instead.

If you have such a third-party distribution of MySQL running on your
system and now want to migrate to Oracle's distribution using the RPM
packages downloaded from the MySQL Developer Zone, see
linux-installing-rpm-compat below.  The preferred method of migration,
however, is to use the MySQL Yum repository
or MySQL SLES repository.

RPM packages for MySQL are listed in the following tables:

*RPM Packages for MySQL Community Edition*

Package Name              Summary

'mysql-community-server'  Database server
                          and related
                          tools

'mysql-community-client'  MySQL client
                          applications and
                          tools

'mysql-community-common'  Common files for
                          server and
                          client libraries

'mysql-community-server-minimal'Minimal
                          installation of
                          the database
                          server and
                          related tools

'mysql-community-devel    Development
'                         header files and
                          libraries for
                          MySQL database
                          client
                          applications

'mysql-community-libs '   Shared libraries
                          for MySQL
                          database client
                          applications

'mysql-community-libs-compat'Shared
                          compatibility
                          libraries for
                          previous MySQL
                          installations

'mysql-community-embedded'MySQL embedded
                          library

'mysql-community-embedded-devel'Development
                          header files and
                          libraries for
                          MySQL as an
                          embeddable
                          library

'mysql-community-test '   Test suite for
                          the MySQL server

*RPM Packages for the MySQL Enterprise Edition*

Package Name              Summary

'mysql-commercial-server' Database server
                          and related
                          tools

'mysql-commercial-client' MySQL client
                          applications and
                          tools

'mysql-commercial-common' Common files for
                          server and
                          client libraries

'mysql-commercial-server-minimal'Minimal
                          installation of
                          the database
                          server and
                          related tools

'mysql-commercial-devel   Development
'                         header files and
                          libraries for
                          MySQL database
                          client
                          applications

'mysql-commercial-libs    Shared libraries
'                         for MySQL
                          database client
                          applications

'mysql-commercial-libs-compat'Shared
                          compatibility
                          libraries for
                          previous MySQL
                          installations

'mysql-commercial-embedded'MySQL embedded
                          library

'mysql-commercial-embedded-devel'Development
                          header files and
                          libraries for
                          MySQL as an
                          embeddable
                          library

'mysql-commercial-test    Test suite for
'                         the MySQL server

The full names for the RPMs have the following syntax:

     PACKAGENAME-VERSION-DISTRIBUTION-ARCH.rpm

The DISTRIBUTION and ARCH values indicate the Linux distribution and the
processor type for which the package was built.  See the table below for
lists of the distribution identifiers:

*MySQL Linux RPM Package Distribution Identifiers*

distribution       Intended Use
Value

'el6', 'el7'       Red Hat Enterprise Linux/Oracle Linux/CentOS 6, or 7

'fc26', 'fc27'     Fedora 26 and 27

'sles12'           SUSE Linux Enterprise Server 12

To see all files in an RPM package (for example,
'mysql-community-server'), use the following command:

     shell> rpm -qpl mysql-community-server-VERSION-DISTRIBUTION-ARCH.rpm

_The discussion in the rest of this section applies only to an
installation process using the RPM packages directly downloaded from
Oracle, instead of through a MySQL repository._

Dependency relationships exist among some of the packages.  If you plan
to install many of the packages, you may wish to download the RPM bundle
'tar' file instead, which contains all the RPM packages listed above, so
that you need not download them separately.

In most cases, you need to install the 'mysql-community-server',
'mysql-community-client', 'mysql-community-libs',
'mysql-community-common', and 'mysql-community-libs-compat' packages to
get a functional, standard MySQL installation.  To perform such a
standard, basic installation, go to the folder that contains all those
packages (and, preferably, no other RPM packages with similar names),
and issue the following command for platforms _other than_ Red Hat
Enterprise Linux/Oracle Linux/CentOS 5:

     shell> sudo yum install mysql-community-{server,client,common,libs}-*

Replace 'yum' with 'zypper' for SLES, and with 'dnf' for Fedora.

While it is much preferable to use a high-level package management tool
like 'yum' to install the packages, users who prefer direct 'rpm'
commands can replace the 'yum install' command with the 'rpm -Uvh'
command; however, using 'rpm -Uvh' instead makes the installation
process more prone to failure, due to potential dependency issues the
installation process might run into.

To install only the client programs, you can skip
'mysql-community-server' in your list of packages to install; issue the
following command for platforms _other than_ Red Hat Enterprise
Linux/Oracle Linux/CentOS 5:

     shell> sudo yum install mysql-community-{client,common,libs}-*

Replace 'yum' with 'zypper' for SLES, and with 'dnf' for Fedora.

For Red Hat Enterprise Linux/Oracle Linux/CentOS 5 systems:

     shell> sudo yum install mysql-community-{client,common,libs}-* mysql-5.*

A standard installation of MySQL using the RPM packages result in files
and resources created under the system directories, shown in the
following table.

*MySQL Installation Layout for Linux RPM Packages from the MySQL
Developer Zone*

Files or Resources                       Location

Client programs and scripts              '/usr/bin'

'mysqld' server           '/usr/sbin'

Configuration file                       '/etc/my.cnf'

Data directory                           '/var/lib/mysql'

Error log file
                                         For RHEL, Oracle Linux, CentOS
                                         or Fedora platforms:
                                         '/var/log/mysqld.log'

                                         For SLES:
                                         '/var/log/mysql/mysqld.log'

Value of 'secure_file_priv'              '/var/lib/mysql-files'

System V init script
                                         For RHEL, Oracle Linux, CentOS
                                         or Fedora platforms:
                                         '/etc/init.d/mysqld'

                                         For SLES: '/etc/init.d/mysql'

Systemd service
                                         For RHEL, Oracle Linux, CentOS
                                         or Fedora platforms: 'mysqld'

                                         For SLES: 'mysql'

Pid file                                 ' /var/run/mysql/mysqld.pid'

Socket                                   '/var/lib/mysql/mysql.sock'

Keyring directory                        '/var/lib/mysql-keyring'

Unix manual pages                        '/usr/share/man'

Include (header) files                   '/usr/include/mysql'

Libraries                                '/usr/lib/mysql'

Miscellaneous support files (for         '/usr/share/mysql'
example, error messages, and character
set files)

The installation also creates a user named 'mysql' and a group named
'mysql' on the system.

*Note*:

Installation of previous versions of MySQL using older packages might
have created a configuration file named '/usr/my.cnf'.  It is highly
recommended that you examine the contents of the file and migrate the
desired settings inside to the file '/etc/my.cnf' file, then remove
'/usr/my.cnf'.

MySQL is not automatically started at the end of the installation
process.  For Red Hat Enterprise Linux, Oracle Linux, CentOS, and Fedora
systems, use the following command to start MySQL:

     shell> sudo service mysqld start

For SLES systems, the command is the same, but the service name is
different:

     shell> sudo service mysql start

If the operating system is systemd enabled, standard 'service' commands
such as 'stop', 'start', 'status' and 'restart' should be used to manage
the MySQL server service.  The 'mysqld' service is enabled by default,
and it starts at system reboot.  Notice that certain things might work
differently on systemd platforms: for example, changing the location of
the data directory might cause issues.  See using-systemd for
additional information.

During an upgrade installation using RPM packages, if the MySQL server
is running when the upgrade occurs then the MySQL server is stopped, the
upgrade occurs, and the MySQL server is restarted.  One exception: if
the edition also changes during an upgrade (such as community to
commercial, or vice-versa), then MySQL server is not restarted.

At the initial start up of the server, the following happens, given that
the data directory of the server is empty:

   * The server is initialized.

   * An SSL certificate and key files are generated in the data
     directory.

   * 'validate_password' is installed and
     enabled.

   * A superuser account ''root'@'localhost'' is created.  A password
     for the superuser is set and stored in the error log file.  To
     reveal it, use the following command for RHEL, Oracle Linux,
     CentOS, and Fedora systems:

          shell> sudo grep 'temporary password' /var/log/mysqld.log

     Use the following command for SLES systems:

          shell> sudo grep 'temporary password' /var/log/mysql/mysqld.log

     The next step is to log in with the generated, temporary password
     and set a custom password for the superuser account:

     shell> mysql -uroot -p

     mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass4!';

*Note*:

'validate_password' is installed by default.
The default password policy implemented by 'validate_password' requires
that passwords contain at least one upper case letter, one lower case
letter, one digit, and one special character, and that the total
password length is at least 8 characters.

If something goes wrong during installation, you might find debug
information in the error log file '/var/log/mysqld.log'.

For some Linux distributions, it might be necessary to increase the
limit on number of file descriptors available to 'mysqld'.
See not-enough-file-handles

Compatibility with RPM Packages from Other Vendors

If you have installed packages for MySQL from your Linux distribution's
local software repository, it is much preferable to install the new,
directly-downloaded packages from Oracle using the package management
system of your platform ('yum', 'dnf', or 'zypper'), as described above.
The command replaces old packages with new ones to ensure compatibility
of old applications with the new installation; for example, the old
'mysql-libs' package is replaced with the 'mysql-community-libs-compat'
package, which provides a replacement-compatible client library for
applications that were using your older MySQL installation.  If there
was an older version of 'mysql-community-libs-compat' on the system, it
also gets replaced.

If you have installed third-party packages for MySQL that are NOT from
your Linux distribution's local software repository (for example,
packages directly downloaded from a vendor other than Oracle), you
should uninstall all those packages before installing the new,
directly-downloaded packages from Oracle.  This is because conflicts may
arise between those vendor's RPM packages and Oracle's: for example, a
vendor's convention about which files belong with the server and which
belong with the client library may differ from that used for Oracle
packages.  Attempts to install an Oracle RPM may then result in messages
saying that files in the RPM to be installed conflict with files from an
installed package.

Installing Client Libraries from Multiple MySQL Versions

It is possible to install multiple client library versions, such as for
the case that you want to maintain compatibility with older applications
linked against previous libraries.  To install an older client library,
use the '--oldpackage' option with 'rpm'.  For example, to install
'mysql-community-libs-5.5' on an EL6 system that has 'libmysqlclient.20'
from MySQL 5.7, use a command like this:

     shell> rpm --oldpackage -ivh mysql-community-libs-5.5.50-2.el6.x86_64.rpm

Debug Package

A special variant of MySQL Server compiled with the debug package
has been included in the server RPM packages.  It performs
debugging and memory allocation checks and produces a trace file when
the server is running.  To use that debug version, start MySQL with
'/usr/sbin/mysqld-debug', instead of starting it as a service or with
'/usr/sbin/mysqld'.  See dbug-package for the debug options you
can use.

*Note*:

The default plugin directory for debug builds changed from
'/usr/lib64/mysql/plugin' to '/usr/lib64/mysql/plugin/debug' in 5.7.21.
Previously, manually changing 'plugin_dir' was required.

Rebuilding RPMs from source SRPMs

Source code SRPM packages for MySQL are available for download.  They
can be used as-is to rebuild the MySQL RPMs with the standard 'rpmbuild'
tool chain.

'root' passwords for pre-GA releases

For MySQL 5.7.4 and 5.7.5, the initial random 'root' password is written
to the '.mysql_secret' file in the directory named by the 'HOME'
environment variable.  When trying to access the file, bear in mind that
depending on operating system, using a command such as 'sudo' may cause
the value of 'HOME' to refer to the home directory of the 'root' system
user

.  '.mysql_secret' is created with mode 600 to be accessible only to the
system user for whom it is created.  Before MySQL 5.7.4, the accounts
(including 'root') created in the MySQL grant tables for an RPM
installation initially have no passwords; after starting the server, you
should assign passwords to them using the instructions in
postinstallation."

2.5.6 Installing MySQL on Linux Using Debian Packages from Oracle
-----------------------------------------------------------------

Oracle provides Debian packages for installing MySQL on Debian or
Debian-like Linux systems.  The packages are available through two
different channels:

   * The MySQL APT Repository
     (http://dev.mysql.com/downloads/repo/apt/).  This is the preferred
     method for installing MySQL on Debian-like systems, as it provides
     a simple and convenient way to install and update MySQL products.
     For details, see linux-installation-apt-repo.

   * The MySQL Developer Zone's Download Area
     (http://dev.mysql.com/downloads/).  For details, see
     getting-mysql.  The following are some information on the Debian
     packages available there and the instructions for installing them:

        * Various Debian packages are provided in the MySQL Developer
          Zone for installing different components of MySQL on different
          Debian or Ubuntu platforms.  The preferred method is to use
          the tarball bundle, which contains the packages needed for a
          basic setup of MySQL. The tarball bundles have names in the
          format of 'mysql-server_MVER-DVER_CPU.deb-bundle.tar'.  MVER
          is the MySQL version and DVER is the Linux distribution
          version.  The CPU value indicates the processor type or family
          for which the package is built, as shown in the following
          table:

          *MySQL Debian and Ubuntu Installation Packages CPU
          Identifiers*

          CPU Value          Intended Processor Type or Family

          'i386'             Pentium processor or better, 32 bit

          'amd64'            64-bit x86 processor

        * After downloading the tarball, unpack it with the following
          command:

               shell> tar -xvf mysql-server_MVER-DVER_CPU.deb-bundle.tar

        *
          You may need to install the 'libaio' library if it is not
          already present on your system:

               shell> sudo apt-get install libaio1

        * Preconfigure the MySQL server package with the following
          command:

               shell> sudo dpkg-preconfigure mysql-community-server_*.deb

          You will be asked to provide a password for the root user for
          your MySQL installation.  You might also be asked other
          questions regarding the installation.

          *Important*:

          Make sure you remember the root password you set.  Users who
          want to set a password later can leave the 'password' field
          blank in the dialogue box and just press 'OK'; in that case,
          root access to the server is authenticated using the
          MySQL Socket Peer-Credential Authentication Plugin
          for connections using a Unix
          socket file.  You can set the root password later using
          'mysql_secure_installation'.

        * For a basic installation of the MySQL server, install the
          database common files package, the client package, the client
          metapackage, the server package, and the server metapackage
          (in that order); you can do that with a single command:

               shell> sudo dpkg -i mysql-{common,community-client,client,community-server,server}_*.deb

          If you are being warned of unmet dependencies by 'dpkg', you
          can fix them using 'apt-get':

               sudo apt-get -f install

          Here are where the files are installed on the system:

             * All configuration files (like 'my.cnf') are under
               '/etc/mysql'

             * All binaries, libraries, headers, etc., are under
               '/usr/bin' and '/usr/sbin'

             * The data directory is '/var/lib/mysql'

*Note*:

Debian distributions of MySQL are also provided by other vendors.  Be
aware that they may differ from those built by Oracle in features,
capabilities, and conventions (including communication setup), and that
the instructions in this manual do not necessarily apply to installing
them.  The vendor's instructions should be consulted instead.

2.5.7 Deploying MySQL on Linux with Docker
------------------------------------------

The Docker deployment framework supports easy installation and
configuration of MySQL Server.  This section explains how to use a MySQL
Server Docker image.

You need to have Docker installed on your system before you can use a
MySQL Server Docker image.  See Install Docker
(https://docs.docker.com/engine/installation/) for instructions.

*Important*:

You need to either run 'docker' commands with 'sudo', or create a
'docker' usergroup, and then add to it any users who want to run
'docker' commands.  See details here
(https://docs.docker.com/engine/installation/linux/linux-postinstall/).
Because Docker containers are always run with root privileges, you
should understand the Docker daemon attack surface
(https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface)
and properly mitigate the related risks.

The instructions for using the MySQL Docker container are divided into
two sections.

2.5.7.1 Basic Steps for MySQL Server Deployment with Docker
...........................................................

   * docker-download-image

   * docker-starting-mysql-server

   * docker-connecting-within-container

   * docker-shell-access

   * docker-stopping-deleting

   * docker-more-topics

*Note*:

_Using the MySQL Enterprise Server container:_ A subscription is
required to use the Docker images for MySQL Enterprise Server.
Subscriptions work by a Bring Your Own License model; see How to Buy
MySQL Products and Services (https://www.mysql.com/buy-mysql/) for
details.  To obtain authorized access to the MySQL Enterprise Server
image, go to the MySQL Server Enterprise Edition
(https://store.docker.com/images/mysql-enterprise-server) page in the
Docker Store, click on 'Proceed to Checkout', and provide the required
information.  Authorized access to the container is then associated with
your Docker ID.

*Downloading a MySQL Server Docker Image*

Downloading the server image in a separate step is not strictly
necessary; however, performing this step before you create your Docker
container ensures your local image is up to date.  To download the MySQL
Community Edition image, run this command:

     docker pull mysql/mysql-server:TAG

The TAG is the label for the image version you want to pull (for
example, '5.5', '5.6', '5.7', '8.0', or 'latest').  If :TAG is omitted,
the 'latest' label is used, and the image for the latest GA version of
MySQL Community Server is downloaded.  Refer to the list of tags for
available versions on the mysql/mysql-server page in the Docker Hub
(https://hub.docker.com/r/mysql/mysql-server/tags/).

To download the MySQL Enterprise Edition image, run this command:

     docker pull  store/oracle/mysql-enterprise-server:5.7

'5.7' is the label for the image version you want to pull.  The MySQL
Enterprise Edition container only provides the latest GA version (5.7)
of the MySQL Enterprise Server.

You can list downloaded Docker images with this command:

     shell> docker images
     REPOSITORY           TAG                 IMAGE ID            CREATED             SIZE
     mysql/mysql-server   latest              3157d7f55f8d        4 weeks ago         241MB

(The 'REPOSITORY' column of the output reads 'mysql/mysql-server' for
the MySQL Community Server and 'store/oracle/mysql-enterprise-server'
for the MySQL Enterprise Server.)

*Starting a MySQL Server Instance*

Start a new Docker container for the MySQL Community Server with this
command:

     docker run --name=mysql1 -d mysql/mysql-server:TAG

Start a new Docker container for the MySQL Enterprise Server with this
command:

     docker run --name=mysql1 -d store/oracle/mysql-enterprise-server:TAG

The '--name' option, for supplying a custom name for your server
container ('mysql1' in the example), is optional; if no container name
is supplied, a random one is generated.  If the Docker image of the
specified name and tag has not been downloaded by an earlier 'docker
pull' or 'docker run' command, the image is now downloaded.  After
download completes, initialization for the container begins, and the
container appears in the list of running containers when you run the
'docker ps' command; for example:

     shell> docker ps
     CONTAINER ID   IMAGE                COMMAND                  CREATED             STATUS                              PORTS                NAMES
     a24888f0d6f4   mysql/mysql-server   "/entrypoint.sh my..."   14 seconds ago      Up 13 seconds (health: starting)    3306/tcp, 33060/tcp  mysql1

(The 'IMAGE' column of the output reads 'mysql/mysql-server' for the
MySQL Community Server and 'store/oracle/mysql-enterprise-server' for
the MySQL Enterprise Server.)

The container initialization might take some time.  When the server is
ready for use, the 'STATUS' of the container in the output of the
'docker ps' command changes from '(health: starting)' to '(healthy)'.

The '-d' option used in the 'docker run' command above makes the
container run in the background.  Use this command to monitor the output
from the container:

     docker logs mysql1

Once initialization is finished, the command's output is going to
contain the random password generated for the root user; check the
password with, for example, this command:

     shell> docker logs mysql1 2>&1 | grep GENERATED
     GENERATED ROOT PASSWORD: Axegh3kAJyDLaRuBemecis&EShOs

*Connecting to MySQL Server from within the Container*

Once the server is ready, you can run the 'mysql' client
within the MySQL Server container you just started, and connect it to
the MySQL Server.  Use the 'docker exec -it' command to start a
'mysql' client inside the Docker container you have started,
like the following:

     docker exec -it mysql1 mysql -uroot -p

When asked, enter the generated root password (see the last step in
docker-starting-mysql-server above on how to find the password).
Because the 'MYSQL_ONETIME_PASSWORD' option is true by default, after
you have connected a 'mysql' client to the server, you
must reset the server root password by issuing this statement:

     mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'NEWPASSWORD';

Substitute NEWPASSWORD with the password of your choice.  Once the
password is reset, the server is ready for use.

*Container Shell Access*

To have shell access to your MySQL Server container, use the 'docker
exec -it' command to start a bash shell inside the container:

     shell> docker exec -it mysql1 bash
     bash-4.2#

You can then run Linux commands inside the container.  For example, to
view contents in the server's data directory inside the container, use
this command:

     bash-4.2# ls /var/lib/mysql
     auto.cnf    ca.pem	     client-key.pem  ib_logfile0  ibdata1  mysql       mysql.sock.lock	   private_key.pem  server-cert.pem  sys
     ca-key.pem  client-cert.pem  ib_buffer_pool  ib_logfile1  ibtmp1   mysql.sock  performance_schema  public_key.pem   server-key.pem

*Stopping and Deleting a MySQL Container*

To stop the MySQL Server container we have created, use this command:

     docker stop mysql1

'docker stop' sends a SIGTERM signal to the 'mysqld'.
process, so that the server is shut down gracefully.

Also notice that when the main process of a container (see 'mysqld'
in the case of a MySQL Server container) is stopped, the Docker
container stops automatically.

To start the MySQL Server container again:

     docker start mysql1

To stop and start again the MySQL Server container with a single
command:

     docker restart mysql1

To delete the MySQL container, stop it first, and then use the 'docker
rm' command:

     docker stop mysql1

     docker rm mysql1

If you want the Docker volume for the server's data directory to be
deleted at the same time, add the '-v' option to the 'docker rm'
command.

*More Topics on Deploying MySQL Server with Docker*

For more topics on deploying MySQL Server with Docker like server
configuration, persisting data and configuration, server error log, and
container environment variables, see docker-mysql-more-topics.

2.5.7.2 More Topics on Deploying MySQL Server with Docker
.........................................................

   * docker-optimized-installation

   * docker-configuring-server

   * docker-persisting-data-configuration

   * docker-additional-init

   * docker-app-in-another-container

   * docker-server-error-log

   * docker-environment-variables

*The Optimized MySQL Installation for Docker*

Docker images for MySQL are optimized for code size, which means they
only include crucial components that are expected to be relevant for the
majority of users who run MySQL instances in Docker containers.  A MySQL
Docker installation is different from a common, non-Docker installation
in the following aspects:

   * Included binaries are limited to:

        * /usr/bin/my_print_defaults

        * /usr/bin/mysql

        * /usr/bin/mysql_config

        * /usr/bin/mysql_install_db

        * /usr/bin/mysql_tzinfo_to_sql

        * /usr/bin/mysql_upgrade

        * /usr/bin/mysqladmin

        * /usr/bin/mysqlcheck

        * /usr/bin/mysqldump

        * /usr/bin/mysqlpump

        * /usr/sbin/mysqld

   * All binaries are stripped; they contain no debug information.

*Configuring the MySQL Server*

When you start the MySQL Docker container, you can pass configuration
options to the server through the 'docker run' command; for example, for
the MySQL Community Server:

     docker run --name mysql1 -d mysql/mysql-server --character-set-server=utf8mb4 --collation-server=utf8mb4_col

For the MySQL Enterprise Server:

     docker run --name mysql1 -d store/oracle/mysql-enterprise-server --character-set-server=utf8mb4 --collation-server=utf8mb4_col

The command starts your MySQL Server with 'utf8mb4' as the default
character set and 'utf8mb4_col' as the default collation for your
databases.

Another way to configure the MySQL Server is to prepare a configuration
file and mount it at the location of the server configuration file
inside the container.  See docker-persisting-data-configuration
for details.

*Persisting Data and Configuration Changes*

Docker containers are in principle ephemeral, and any data or
configuration are expected to be lost if the container is deleted or
corrupted (see discussions here
(https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)).
Docker volumes (https://docs.docker.com/engine/admin/volumes/volumes/),
however, provides a mechanism to persist data created inside a Docker
container.  At its initialization, the MySQL Server container creates a
Docker volume for the server data directory.  The JSON output for
running the 'docker inspect' command on the container has a 'Mount' key,
whose value provides information on the data directory volume:

     shell> docker inspect mysql1
     ...
      "Mounts": [
                 {
                     "Type": "volume",
                     "Name": "4f2d463cfc4bdd4baebcb098c97d7da3337195ed2c6572bc0b89f7e845d27652",
                     "Source": "/var/lib/docker/volumes/4f2d463cfc4bdd4baebcb098c97d7da3337195ed2c6572bc0b89f7e845d27652/_data",
                     "Destination": "/var/lib/mysql",
                     "Driver": "local",
                     "Mode": "",
                     "RW": true,
                     "Propagation": ""
                 }
             ],
     ...

The output shows that the source folder'
/var/lib/docker/volumes/4f2d463cfc4bdd4baebcb098c97d7da3337195ed2c6572bc0b89f7e845d27652/_data',
in which data is persisted on the host, has been mounted at
'/var/lib/mysql', the server data directory inside the container.

Another way to preserve data is to bind-mount
(https://docs.docker.com/engine/reference/commandline/service_create/#add-bind-mounts-or-volumes)
a host directory using the '--mount' option when creating the container.
The same technique can be used to persist the configuration of the
server.  The following command creates a MySQL Community Server
container and bind-mounts both the data directory and the server
configuration file:

     docker run --name=mysql1 \
     --mount type=bind,src=/PATH-ON-HOST-MACHINE/MY.CNF,dst=/etc/my.cnf \
     --mount type=bind,src=/PATH-ON-HOST-MACHINE/DATADIR,dst=/var/lib/mysql \
     -d mysql/mysql-server:TAG

The following command creates a MySQL Enterprise Server container and
bind-mounts both the data directory and the server configuration file:

     docker run --name=mysql1 \
     --mount type=bind,src=/PATH-ON-HOST-MACHINE/MY.CNF,dst=/etc/my.cnf \
     --mount type=bind,src=/PATH-ON-HOST-MACHINE/DATADIR,dst=/var/lib/mysql \
     -d store/oracle/mysql-enterprise-server:TAG

The command mounts 'PATH-ON-HOST-MACHINE/MY.CNF' at '/etc/my.cnf' (the
server configuration file inside the container), and
'PATH-ON-HOST-MACHINE/DATADIR' at '/var/lib/mysql' (the data directory
inside the container).  The following conditions must be met for the
bind-mounting to work:

   * The configuration file 'PATH-ON-HOST-MACHINE/MY.CNF' must already
     exist, and it must contain the specification for starting the
     server using the user 'mysql':

          [mysqld]
          user=mysql

     You can also include other server configuration options in the
     file.

   * The data directory 'PATH-ON-HOST-MACHINE/DATADIR' must already
     exist.  For server initialization to happen, the directory must be
     empty.  You can also mount a directory prepopulated with data and
     start the server with it; however, you must make sure you start the
     Docker container with the same configuration as the server that
     created the data, and any host files or directories required are
     mounted when starting the container.

*Running Additional Initialization Scripts*

If there are any '.sh' or '.sql' scripts you want to run on the database
immediately after it has been created, you can put them into a host
directory and then mount the directory at '/docker-entrypoint-initdb.d/'
inside the container.  For example, for a MySQL Community Server
container:

     docker run --name=mysql1 \
     --mount type=bind,src=/PATH-ON-HOST-MACHINE/SCRIPTS/,dst=/docker-entrypoint-initdb.d/ \
     -d mysql/mysql-server:TAG

For a MySQL Enterprise Server container:

     docker run --name=mysql1 \
     --mount type=bind,src=/PATH-ON-HOST-MACHINE/SCRIPTS/,dst=/docker-entrypoint-initdb.d/ \
     -d store/oracle/mysql-enterprise-server:TAG

*Connect to MySQL from an Application in Another Docker Container*

By setting up a Docker network, you can allow multiple Docker containers
to communicate with each other, so that a client application in another
Docker container can access the MySQL Server in the server container.
First, create a Docker network:

     docker network create MY-CUSTOM-NET

Then, when you are creating and starting the server and the client
containers, use the '--network' option to put them on network you
created.  When using a MySQL Community Server container:

     docker run --name=mysql1 --network=MY-CUSTOM-NET -d mysql/mysql-server

     docker run --name=myapp1 --network=MY-CUSTOM-NET -d myapp

When using a MySQL Enterprise Server container:

     docker run --name=mysql1 --network=MY-CUSTOM-NET -d store/oracle/mysql-enterprise-server

     docker run --name=myapp1 --network=MY-CUSTOM-NET -d myapp

The 'myapp1' container can then connect to the 'mysql1' container with
the 'mysql1' hostname and vice versa, as Docker automatically sets up a
DNS for the given container names.  In the following example, we run the
'mysql' client from inside the 'myapp1' container to
connect to host 'mysql1' in its own container:

     docker exec -it myapp1 mysql --host=mysql1 --user=myuser --password

For other networking techniques for containers, see the Docker container
networking (https://docs.docker.com/engine/userguide/networking/)
section in the Docker Documentation.

*Server Error Log*

When the MySQL Server is first started with your server container, a
server error log is NOT generated if either of the
following conditions is true:

   * A server configuration file from the host has been mounted, but the
     file does not contain the system variable 'log_error' (see
     docker-persisting-data-configuration on bind-mounting a server
     configuration file).

   * A server configuration file from the host has not been mounted, but
     the Docker environment variable 'MYSQL_LOG_CONSOLE' is 'true' (the
     variable's default state for MySQL 5.7 server containers is
     'false').  The MySQL Server's error log is then redirected to
     'stderr', so that the error log goes into the Docker container's
     log and is viewable using the 'docker logs MYSQLD-CONTAINER'
     command.

To make MySQL Server generate an error log when either of the two
conditions is true, use the '--log-error' option to configure the server
to generate the error log at a specific location inside the container.
To persist the error log, mount a host file at the location of the error
log inside the container as explained in
docker-persisting-data-configuration.  However, you must make sure
your MySQL Server inside its container has write access to the mounted
host file.

*Docker Environment Variables*

When you create a MySQL Server container, you can configure the MySQL
instance by using the '--env' option ('-e' in short) and specifying one
or more of the following environment variables.

*Notes*:

   * None of the variables below has any effect if the data directory
     you mount is not empty, as no server initialization is going to be
     attempted then (see docker-persisting-data-configuration
     for more details).  Any pre-existing contents in the folder,
     including any old server settings, are not modified during the
     container startup.

   * The boolean variables including 'MYSQL_RANDOM_ROOT_PASSWORD',
     'MYSQL_ONETIME_PASSWORD', 'MYSQL_ALLOW_EMPTY_PASSWORD', and
     'MYSQL_LOG_CONSOLE' are made true by setting them with any strings
     of nonzero lengths.

     Therefore, setting them to, for example, '0', 'false', or 'no' does
     not make them false, but actually makes them true.  This is a known
     issue of the MySQL Server containers.

   * 'MYSQL_RANDOM_ROOT_PASSWORD': When this variable is true (which is
     its default state, unless 'MYSQL_ROOT_PASSWORD' is set or
     'MYSQL_ALLOW_EMPTY_PASSWORD' is set to true), a random password for
     the server's root user is generated when the Docker container is
     started.  The password is printed to 'stdout' of the container and
     can be found by looking at the container's log (see
     docker-starting-mysql-server).

   * 'MYSQL_ONETIME_PASSWORD': When the variable is true (which is its
     default state, unless 'MYSQL_ROOT_PASSWORD' is set or
     'MYSQL_ALLOW_EMPTY_PASSWORD' is set to true), the root user's
     password is set as expired and must be changed before MySQL can be
     used normally.

   * 'MYSQL_DATABASE': This variable allows you to specify the name of a
     database to be created on image startup.  If a user name and a
     password are supplied with 'MYSQL_USER' and 'MYSQL_PASSWORD', the
     user is created and granted superuser access to this database
     (corresponding to 'GRANT ALL').  The specified database is created
     by a CREATE DATABASE IF NOT EXIST.
     statement, so that the variable has no effect if the database
     already exists.

   * 'MYSQL_USER', 'MYSQL_PASSWORD': These variables are used in
     conjunction to create a user and set that user's password, and the
     user is granted superuser permissions for the database specified by
     the 'MYSQL_DATABASE' variable.  Both 'MYSQL_USER' and
     'MYSQL_PASSWORD' are required for a user to be created--if any of
     the two variables is not set, the other is ignored.  If both
     variables are set but 'MYSQL_DATABASE' is not, the user is created
     without any privileges.

     *Note*:

     There is no need to use this mechanism to create the root
     superuser, which is created by default with the password set by
     either one of the mechanisms discussed in the descriptions for
     'MYSQL_ROOT_PASSWORD' and 'MYSQL_RANDOM_ROOT_PASSWORD', unless
     'MYSQL_ALLOW_EMPTY_PASSWORD' is true.

   * 'MYSQL_ROOT_HOST': By default, MySQL creates the
     ''root'@'localhost'' account.  This account can only be connected
     to from inside the container as described in
     docker-connecting-within-container.  To allow root connections
     from other hosts, set this environment variable.  For example, the
     value '172.17.0.1', which is the default Docker gateway IP, allows
     connections from the host machine that runs the container.  The
     option accepts only one entry, but wildcards are allowed (for
     example, 'MYSQL_ROOT_HOST=172.*.*.*' or 'MYSQL_ROOT_HOST=%').

   * 'MYSQL_LOG_CONSOLE': When the variable is true (the variable's
     default state for MySQL 5.7 server containers is 'false'), the
     MySQL Server's error log is redirected to 'stderr', so that the
     error log goes into the Docker container's log and is viewable
     using the 'docker logs MYSQLD-CONTAINER' command.

     *Note*:

     The variable has no effect if a server configuration file from the
     host has been mounted (see
     docker-persisting-data-configuration on bind-mounting a
     configuration file).

   * 'MYSQL_ROOT_PASSWORD': This variable specifies a password that is
     set for the MySQL root account.

     *Warning*:

     Setting the MySQL root user password on the command line is
     insecure.  As an alternative to specifying the password explicitly,
     you can set the variable with a container file path for a password
     file, and then mount a file from your host that contains the
     password at the container file path.  This is still not very
     secure, as the location of the password file is still exposed.  It
     is preferable to use the default settings of
     'MYSQL_RANDOM_ROOT_PASSWORD' and 'MYSQL_ONETIME_PASSWORD' both
     being true.

   * 'MYSQL_ALLOW_EMPTY_PASSWORD'.  Set it to true to allow the
     container to be started with a blank password for the root user.

     *Warning*:

     Setting this variable to true is insecure, because it is going to
     leave your MySQL instance completely unprotected, allowing anyone
     to gain complete superuser access.  It is preferable to use the
     default settings of 'MYSQL_RANDOM_ROOT_PASSWORD' and
     'MYSQL_ONETIME_PASSWORD' both being true.

2.5.8 Installing MySQL on Linux from the Native Software Repositories
---------------------------------------------------------------------

Many Linux distributions include a version of the MySQL server, client
tools, and development components in their native software repositories
and can be installed with the platforms' standard package management
systems.  This section provides basic instructions for installing MySQL
using those package management systems.

*Important*:

Native packages are often several versions behind the currently
available release.  You will also normally be unable to install
development milestone releases (DMRs), as these are not usually made
available in the native repositories.  Before proceeding, we recommend
that you check out the other installation options described in
linux-installation.

Distribution specific instructions are shown below:

   * *Red Hat Linux, Fedora, CentOS*

     *Note*:

     For a number of Linux distributions, you can install MySQL using
     the MySQL Yum repository instead of the platform's native software
     repository.  See linux-installation-yum-repo for details.

     For Red Hat and similar distributions, the MySQL distribution is
     divided into a number of separate packages, 'mysql' for the client
     tools, 'mysql-server' for the server and associated tools, and
     'mysql-libs' for the libraries.  The libraries are required if you
     want to provide connectivity from different languages and
     environments such as Perl, Python and others.

     To install, use the 'yum' command to specify the packages that you
     want to install.  For example:

          root-shell> yum install mysql mysql-server mysql-libs mysql-server
          Loaded plugins: presto, refresh-packagekit
          Setting up Install Process
          Resolving Dependencies
          --> Running transaction check
          ---> Package mysql.x86_64 0:5.1.48-2.fc13 set to be updated
          ---> Package mysql-libs.x86_64 0:5.1.48-2.fc13 set to be updated
          ---> Package mysql-server.x86_64 0:5.1.48-2.fc13 set to be updated
          --> Processing Dependency: perl-DBD-MySQL for package: mysql-server-5.1.48-2.fc13.x86_64
          --> Running transaction check
          ---> Package perl-DBD-MySQL.x86_64 0:4.017-1.fc13 set to be updated
          --> Finished Dependency Resolution

          Dependencies Resolved

          ================================================================================
           Package               Arch          Version               Repository      Size
          ================================================================================
          Installing:
           mysql                 x86_64        5.1.48-2.fc13         updates        889 k
           mysql-libs            x86_64        5.1.48-2.fc13         updates        1.2 M
           mysql-server          x86_64        5.1.48-2.fc13         updates        8.1 M
          Installing for dependencies:
           perl-DBD-MySQL        x86_64        4.017-1.fc13          updates        136 k

          Transaction Summary
          ================================================================================
          Install       4 Package(s)
          Upgrade       0 Package(s)

          Total download size: 10 M
          Installed size: 30 M
          Is this ok [y/N]: y
          Downloading Packages:
          Setting up and reading Presto delta metadata
          Processing delta metadata
          Package(s) data still to download: 10 M
          (1/4): mysql-5.1.48-2.fc13.x86_64.rpm                    | 889 kB     00:04
          (2/4): mysql-libs-5.1.48-2.fc13.x86_64.rpm               | 1.2 MB     00:06
          (3/4): mysql-server-5.1.48-2.fc13.x86_64.rpm             | 8.1 MB     00:40
          (4/4): perl-DBD-MySQL-4.017-1.fc13.x86_64.rpm            | 136 kB     00:00
          --------------------------------------------------------------------------------
          Total                                           201 kB/s |  10 MB     00:52
          Running rpm_check_debug
          Running Transaction Test
          Transaction Test Succeeded
          Running Transaction
            Installing     : mysql-libs-5.1.48-2.fc13.x86_64                          1/4
            Installing     : mysql-5.1.48-2.fc13.x86_64                               2/4
            Installing     : perl-DBD-MySQL-4.017-1.fc13.x86_64                       3/4
            Installing     : mysql-server-5.1.48-2.fc13.x86_64                        4/4

          Installed:
            mysql.x86_64 0:5.1.48-2.fc13            mysql-libs.x86_64 0:5.1.48-2.fc13
            mysql-server.x86_64 0:5.1.48-2.fc13

          Dependency Installed:
            perl-DBD-MySQL.x86_64 0:4.017-1.fc13

          Complete!

     MySQL and the MySQL server should now be installed.  A sample
     configuration file is installed into '/etc/my.cnf'.  An init
     script, to start and stop the server, will have been installed into
     '/etc/init.d/mysqld'.  To start the MySQL server use 'service':

          root-shell> service mysqld start

     To enable the server to be started and stopped automatically during
     boot, use 'chkconfig':

          root-shell> chkconfig --levels 235 mysqld on

     Which enables the MySQL server to be started (and stopped)
     automatically at the specified the run levels.

     The database tables will have been automatically created for you,
     if they do not already exist.  You should, however, run
     'mysql_secure_installation' to set the
     root passwords on your server.

   * *Debian, Ubuntu, Kubuntu*

     *Note*:

     On Debian, Ubuntu, and Kubuntu, MySQL can be installed using the
     MySQL APT Repository (http://dev.mysql.com/downloads/repo/apt/)
     instead of the platform's native software repository.  See
     linux-installation-apt-repo for details.

     On Debian and related distributions, there are two packages for
     MySQL in their software repositories, 'mysql-client' and
     'mysql-server', for the client and server components respectively.
     You should specify an explicit version, for example
     'mysql-client-5.1', to ensure that you install the version of MySQL
     that you want.

     To download and install, including any dependencies, use the
     'apt-get' command, specifying the packages that you want to
     install.

     *Note*:

     Before installing, make sure that you update your 'apt-get' index
     files to ensure you are downloading the latest available version.

     A sample installation of the MySQL packages might look like this
     (some sections trimmed for clarity):

          root-shell> apt-get install mysql-client-5.1 mysql-server-5.1
          Reading package lists... Done
          Building dependency tree
          Reading state information... Done
          The following packages were automatically installed and are no longer required:
            linux-headers-2.6.28-11 linux-headers-2.6.28-11-generic
          Use 'apt-get autoremove' to remove them.
          The following extra packages will be installed:
            bsd-mailx libdbd-mysql-perl libdbi-perl libhtml-template-perl
            libmysqlclient15off libmysqlclient16 libnet-daemon-perl libplrpc-perl mailx
            mysql-common postfix
          Suggested packages:
            dbishell libipc-sharedcache-perl tinyca procmail postfix-mysql postfix-pgsql
            postfix-ldap postfix-pcre sasl2-bin resolvconf postfix-cdb
          The following NEW packages will be installed
            bsd-mailx libdbd-mysql-perl libdbi-perl libhtml-template-perl
            libmysqlclient15off libmysqlclient16 libnet-daemon-perl libplrpc-perl mailx
            mysql-client-5.1 mysql-common mysql-server-5.1 postfix
          0 upgraded, 13 newly installed, 0 to remove and 182 not upgraded.
          Need to get 1907kB/25.3MB of archives.
          After this operation, 59.5MB of additional disk space will be used.
          Do you want to continue [Y/n]? Y
          Get: 1 http://gb.archive.ubuntu.com jaunty-updates/main mysql-common 5.1.30really5.0.75-0ubuntu10.5 [63.6kB]
          Get: 2 http://gb.archive.ubuntu.com jaunty-updates/main libmysqlclient15off 5.1.30really5.0.75-0ubuntu10.5 [1843kB]
          Fetched 1907kB in 9s (205kB/s)
          Preconfiguring packages ...
          Selecting previously deselected package mysql-common.
          (Reading database ... 121260 files and directories currently installed.)
          ...
          Processing 1 added doc-base file(s)...
          Registering documents with scrollkeeper...
          Setting up libnet-daemon-perl (0.43-1) ...
          Setting up libplrpc-perl (0.2020-1) ...
          Setting up libdbi-perl (1.607-1) ...
          Setting up libmysqlclient15off (5.1.30really5.0.75-0ubuntu10.5) ...

          Setting up libdbd-mysql-perl (4.008-1) ...
          Setting up libmysqlclient16 (5.1.31-1ubuntu2) ...

          Setting up mysql-client-5.1 (5.1.31-1ubuntu2) ...

          Setting up mysql-server-5.1 (5.1.31-1ubuntu2) ...
           * Stopping MySQL database server mysqld
             ...done.
          2013-09-24T13:03:09.048353Z 0 [Note] InnoDB: 5.7.23 started; log sequence number 1566036
          2013-09-24T13:03:10.057269Z 0 [Note] InnoDB: Starting shutdown...
          2013-09-24T13:03:10.857032Z 0 [Note] InnoDB: Shutdown completed; log sequence number 1566036
           * Starting MySQL database server mysqld
             ...done.
           * Checking for corrupt, not cleanly closed and upgrade needing tables.
          ...
          Processing triggers for libc6 ...
          ldconfig deferred processing now taking place

     *Note*:

     The 'apt-get' command will install a number of packages, including
     the MySQL server, in order to provide the typical tools and
     application environment.  This can mean that you install a large
     number of packages in addition to the main MySQL package.

     During installation, the initial database will be created, and you
     will be prompted for the MySQL root password (and confirmation).  A
     configuration file will have been created in '/etc/mysql/my.cnf'.
     An init script will have been created in '/etc/init.d/mysql'.

     The server will already be started.  You can manually start and
     stop the server using:

          root-shell> service mysql [start|stop]

     The service will automatically be added to the 2, 3 and 4 run
     levels, with stop scripts in the single, shutdown and restart
     levels.

2.5.9 Installing MySQL on Linux with Juju
-----------------------------------------

The Juju deployment framework supports easy installation and
configuration of MySQL servers.  For instructions, see
<https://jujucharms.com/mysql/>.

2.5.10 Managing MySQL Server with systemd
-----------------------------------------

If you install MySQL using an RPM or Debian package on the following
Linux platforms, server startup and shutdown is managed by systemd:

   * RPM package platforms:

        * Red Hat Enterprise Linux 7; Oracle Linux 7; CentOS 7

        * SUSE Linux Enterprise Server 12

        * Fedora 26 and 27

   * Debian package platforms:

        * Debian 8 or higher

        * Ubuntu 16 or higher

If you install MySQL from a source distribution on a platform that uses
systemd, obtain systemd support for MySQL by configuring the
distribution using the '-DWITH_SYSTEMD=1' 'CMake' option.  See
source-configuration-options.

The following discussion covers these topics:

   * systemd-overview

   * systemd-mysql-configuration

   * systemd-multiple-mysql-instances

   * mysqld-safe-to-systemd-migration

*Note*:

On platforms for which systemd support for MySQL is installed, scripts
such as 'mysqld_safe' and the System V
initialization script are unnecessary and are not installed.  For
example, see 'mysqld_safe' can handle server restarts,
but systemd provides the same capability, and does so in a manner
consistent with management of other services rather than by using an
application-specific program.

Because systemd has the capability of managing multiple MySQL instances
on platforms for which systemd support for MySQL is installed, see
'mysqld_multi' and 'mysqld_multi.server' are unnecessary
and are not installed.

*Overview of systemd*

systemd provides automatic MySQL server startup and shutdown.  It also
enables manual server management using the 'systemctl' command.  For
example:

     systemctl {start|stop|restart|status} mysqld

Alternatively, use the 'service' command (with the arguments reversed),
which is compatible with System V systems:

     service mysqld {start|stop|restart|status}

*Note*:

For the 'systemctl' or 'service' commands, if the MySQL service name is
not 'mysqld', use the appropriate name.  For example, use 'mysql' rather
than 'mysqld' on Debian-based and SLES systems.

Support for systemd includes these files:

   * 'mysqld.service' (RPM platforms), 'mysql.service' (Debian
     platforms): systemd service unit configuration file, with details
     about the MySQL service.

   * 'mysqld@.service' (RPM platforms), 'mysql@.service' (Debian
     platforms): Like 'mysqld.service' or 'mysql.service', but used for
     managing multiple MySQL instances.

   * 'mysqld.tmpfiles.d': File containing information to support the
     'tmpfiles' feature.  This file is installed under the name
     'mysql.conf'.

   * 'mysqld_pre_systemd' (RPM platforms), 'mysql-system-start' (Debian
     platforms): Support script for the unit file.  This script assists
     in creating the error log file only if the log location matches a
     pattern ('/var/log/mysql*.log' for RPM platforms,
     '/var/log/mysql/*.log' for Debian platforms).  In other cases, the
     error log directory must be writable or the error log must be
     present and writable for the user running the 'mysqld'
     process.

*Configuring systemd for MySQL*

To add or change systemd options for MySQL, these methods are available:

   * Use a localized systemd configuration file.

   * Arrange for systemd to set environment variables for the MySQL
     server process.

   * Set the 'MYSQLD_OPTS' systemd variable.

To use a localized systemd configuration file, create the
'/etc/systemd/system/mysqld.service.d' directory if it does not exist.
In that directory, create a file that contains a '[Service]' section
listing the desired settings.  For example:

     [Service]
     LimitNOFILE=MAX_OPEN_FILES
     PIDFile=/PATH/TO/PID/FILE
     Nice=NICE_LEVEL
     LimitCore=CORE_FILE_LIMIT
     Environment="LD_PRELOAD=/PATH/TO/MALLOC/LIBRARY"
     Environment="TZ=TIME_ZONE_SETTING"

The discussion here uses 'override.conf' as the name of this file.
Newer versions of systemd support the following command, which opens an
editor and permits you to edit the file:

     systemctl edit mysqld  # RPM platforms
     systemctl edit mysql   # Debian platforms

Whenever you create or change 'override.conf', reload the systemd
configuration, then tell systemd to restart the MySQL service:

     systemctl daemon-reload
     systemctl restart mysqld  # RPM platforms
     systemctl restart mysql   # Debian platforms

With systemd, the 'override.conf' configuration method must be used for
certain parameters, rather than settings in a '[mysqld]' or
'[mysqld_safe]' group in a MySQL option file:

   * For some parameters, 'override.conf' must be used because systemd
     itself must know their values and it cannot read MySQL option files
     to get them.

   * Parameters that specify values otherwise settable only using
     options known to 'mysqld_safe' must be
     specified using systemd because there is no corresponding
     'mysqld' parameter.

For additional information about using systemd rather than
'mysqld_safe', see
mysqld-safe-to-systemd-migration.

You can set the following parameters in 'override.conf':

   * To specify the process ID file:

        * As of MySQL 5.7.10: Use 'override.conf' and change both
          'PIDFile' and 'ExecStart' to name the PID file path name.  Any
          setting of the process ID file in MySQL option files is
          ignored.  To modify 'ExecStart', it must first be cleared.
          For example:

               [Service]
               PIDFile=/var/run/mysqld/mysqld-custom.pid
               ExecStart=
               ExecStart=/usr/sbin/mysqld --daemonize --pid-file=/var/run/mysqld/mysqld-custom.pid $MYSQLD_OPTS

        * Before MySQL 5.7.10: Use 'PIDFile' in 'override.conf' rather
          than the '--pid-file' option for 'mysqld' or
          'mysqld_safe'.  systemd must know the PID
          file location so that it can restart or stop the server.  If
          the PID file value is specified in a MySQL option file, the
          value must match the 'PIDFile' value or MySQL startup may
          fail.

   * To set the number of file descriptors available to the MySQL
     server, use 'LimitNOFILE' in 'override.conf' rather than the
     '--open-files-limit' option for 'mysqld' or
     'mysqld_safe'.

   * To set the maximum core file size, use 'LimitCore' in
     'override.conf' rather than the '--core-file-size' option for
     'mysqld_safe'.

   * To set the scheduling priority for the MySQL server, use 'Nice' in
     'override.conf' rather than the '--nice' option for
     'mysqld_safe'.

Some MySQL parameters are configured using environment variables:

   * 'LD_PRELOAD': Set this variable if the MySQL server should use a
     specific memory-allocation library.

   * 'TZ': Set this variable to specify the default time zone for the
     server.

There are multiple ways to specify environment variable values for use
by the MySQL server process managed by systemd:

   * Use 'Environment' lines in the 'override.conf' file.  For the
     syntax, see the example in the preceding discussion that describes
     how to use this file.

   * Specify the values in the '/etc/sysconfig/mysql' file (create the
     file if it does not exist).  Assign values using the following
     syntax:

          LD_PRELOAD=/PATH/TO/MALLOC/LIBRARY
          TZ=TIME_ZONE_SETTING

     After modifying '/etc/sysconfig/mysql', restart the server to make
     the changes effective:

          systemctl restart mysqld  # RPM platforms
          systemctl restart mysql   # Debian platforms

To specify options for 'mysqld' without modifying systemd
configuration files directly, set or unset the 'MYSQLD_OPTS' systemd
variable.  For example:

     systemctl set-environment MYSQLD_OPTS="--general_log=1"
     systemctl unset-environment MYSQLD_OPTS

'MYSQLD_OPTS' can also be set in the '/etc/sysconfig/mysql' file.

After modifying the systemd environment, restart the server to make the
changes effective:

     systemctl restart mysqld  # RPM platforms
     systemctl restart mysql   # Debian platforms

For platforms that use systemd, the data directory is initialized if
empty at server startup.  This might be a problem if the data directory
is a remote mount that has temporarily disappeared: The mount point
would appear to be an empty data directory, which then would be
initialized as a new data directory.  As of MySQL 5.7.20, to suppress
this automatic initialization behavior, specify the following line in
the '/etc/sysconfig/mysql' file (create the file if it does not exist):

     NO_INIT=true

*Configuring Multiple MySQL Instances Using systemd*

This section describes how to configure systemd for multiple instances
of MySQL.

*Note*:

Because systemd has the capability of managing multiple MySQL instances
on platforms for which systemd support is installed, see
'mysqld_multi' and 'mysqld_multi.server' are unnecessary
and are not installed.  This is true as of MySQL 5.7.13 for RPM
platforms, 5.7.19 for Debian platforms.

To use multiple-instance capability, modify the 'my.cnf' option file to
include configuration of key options for each instance.  These file
locations are typical:

   * '/etc/my.cnf' or '/etc/mysql/my.cnf' (RPM platforms)

   * '/etc/mysql/mysql.conf.d/mysqld.cnf' (Debian platforms)

For example, to manage two instances named 'replica01' and 'replica02',
add something like this to the option file:

RPM platforms:

     [mysqld@replica01]
     datadir=/var/lib/mysql-replica01
     socket=/var/lib/mysql-replica01/mysql.sock
     port=3307
     log-error=/var/log/mysqld-replica01.log

     [mysqld@replica02]
     datadir=/var/lib/mysql-replica02
     socket=/var/lib/mysql-replica02/mysql.sock
     port=3308
     log-error=/var/log/mysqld-replica02.log

Debian platforms:

     [mysqld@replica01]
     datadir=/var/lib/mysql-replica01
     socket=/var/lib/mysql-replica01/mysql.sock
     port=3307
     log-error=/var/log/mysql/replica01.log

     [mysqld@replica02]
     datadir=/var/lib/mysql-replica02
     socket=/var/lib/mysql-replica02/mysql.sock
     port=3308
     log-error=/var/log/mysql/replica02.log

The replica names shown here use '@' as the delimiter because that is
the only delimiter supported by systemd.

Instances then are managed by normal systemd commands, such as:

     systemctl start mysqld@replica01
     systemctl start mysqld@replica02

To enable instances to run at boot time, do this:

     systemctl enable mysqld@replica01
     systemctl enable mysqld@replica02

Use of wildcards is also supported.  For example, this command displays
the status of all replica instances:

     systemctl status 'mysqld@replica*'

For management of multiple MySQL instances on the same machine, systemd
automatically uses a different unit file:

   * 'mysqld@.service' rather than 'mysqld.service' (RPM platforms)

   * 'mysql@.service' rather than 'mysql.service' (Debian platforms)

In the unit file, '%I' and '%i' reference the parameter passed in after
the '@' marker and are used to manage the specific instance.  For a
command such as this:

     systemctl start mysqld@replica01

systemd starts the server using a command such as this:

     mysqld --defaults-group-suffix=@%I ...

The result is that the '[server]', '[mysqld]', and '[mysqld@replica01]'
option groups are read and used for that instance of the service.

*Note*:

On Debian platforms, AppArmor prevents the server from reading or
writing '/var/lib/mysql-replica*', or anything other than the default
locations.  To address this, you must customize or disable the profile
in '/etc/apparmor.d/usr.sbin.mysqld'.

*Note*:

On Debian platforms, the packaging scripts for MySQL uninstallation
cannot currently handle 'mysqld@' instances.  Before removing or
upgrading the package, you must stop any extra instances manually first.

*Migrating from mysqld_safe to systemd*

Because 'mysqld_safe' is not installed on platforms
that use systemd to manage MySQL, options previously specified for that
program (for example, in an '[mysqld_safe]' option group) must be
specified another way:

   * Some 'mysqld_safe' options are also understood
     by 'mysqld' and can be moved from the
     '[mysqld_safe]' option group to the '[mysqld]' group.  This does
     _not_ include '--pid-file', '--open-files-limit', or '--nice'.  To
     specify those options, use the 'override.conf' systemd file,
     described previously.

   * For some 'mysqld_safe' options, there are
     similar 'mysqld' options.  For example, the
     'mysqld_safe' option for enabling 'syslog' logging is
     '--syslog', which is deprecated.  For 'mysqld',
     enable the 'log_syslog' system variable instead.  For details, see
     error-log.

   * 'mysqld_safe' options not understood by
     'mysqld' can be specified in 'override.conf' or
     environment variables.  For example, with 'mysqld_safe',
     if the server should use a specific memory allocation
     library, this is specified using the '--malloc-lib' option.  For
     installations that manage the server with systemd, arrange to set
     the 'LD_PRELOAD' environment variable instead, as described
     previously.

2.6 Installing MySQL Using Unbreakable Linux Network (ULN)
==========================================================

Linux supports a number of different solutions for installing MySQL,
covered in linux-installation.  One of the methods, covered in
this section, is installing from Oracle's Unbreakable Linux Network
(ULN). You can find information about Oracle Linux and ULN under
<http://linux.oracle.com/>.

To use ULN, you need to obtain a ULN login and register the machine used
for installation with ULN. This is described in detail in the ULN FAQ
(https://linux.oracle.com/uln_faq.html).  The page also describes how to
install and update packages.The MySQL packages are in the 'MySQL for
Oracle Linux 6' and 'MySQL for Oracle Linux 7' channels for your system
architecture on ULN.

*Note*:

At the time of this writing, ULN provides MySQL 5.7 for Oracle Linux 6
and Oracle Linux 7.

Once MySQL has been installed using ULN, you can find information on
starting and stopping the server, and more, in this section,
particularly under
linux-installation-rpm.

If you're updating an existing MySQL installation to an installation
using ULN, the recommended procedure is to export your data using
'mysqldump', remove the existing installation, install MySQL
from ULN, and load the exported data into your freshly installed MySQL.

If the existing MySQL installation you're upgrading from is from a
previous release series (prior to MySQL 5.7), make sure to read the
section on upgrading MySQL, see upgrading.

2.7 Installing MySQL on Solaris
===============================

*Note*:

MySQL 5.7 supports Solaris 11 (Update 3 and later).

MySQL on Solaris is available in a number of different formats.

   * For information on installing using the native Solaris PKG format,
     see solaris-installation-pkg.

   * To use a standard 'tar' binary installation, use the notes provided
     in binary-installation.  Check the notes and hints at the
     end of this section for Solaris specific notes that you may need
     before or after installation.

*Important*:

The installation packages have a dependency on the Oracle Developer
Studio 12.5 Runtime Libraries, which must be installed before you run
the MySQL installation package.  See the download options for Oracle
Developer Studio here
(http://www.oracle.com/technetwork/server-storage/developerstudio/downloads/index.html).
The installation package enables you to install the runtime libraries
only instead of the full Oracle Developer Studio; see instructions in
Installing Only the Runtime Libraries on Oracle Solaris 11
(https://docs.oracle.com/cd/E60778_01/html/E60743/gozsu.html#scrolltoc).

To obtain a binary MySQL distribution for Solaris in tarball or PKG
format, <http://dev.mysql.com/downloads/mysql/5.7.html>.

Additional notes to be aware of when installing and using MySQL on
Solaris:

   * If you want to use MySQL with the 'mysql' user and group, use the
     'groupadd' and 'useradd' commands:

          groupadd mysql
          useradd -g mysql -s /bin/false mysql

   * If you install MySQL using a binary tarball distribution on
     Solaris, because the Solaris 'tar' cannot handle long file names,
     use GNU 'tar' ('gtar') to unpack the distribution.  If you do not
     have GNU 'tar' on your system, install it with the following
     command:

          pkg install archiver/gnu-tar

   * You should mount any file systems on which you intend to store
     'InnoDB' files with the 'forcedirectio' option.  (By default
     mounting is done without this option.)  Failing to do so will cause
     a significant drop in performance when using the 'InnoDB' storage
     engine on this platform.

   * If you would like MySQL to start automatically, you can copy
     'support-files/mysql.server' to '/etc/init.d' and create a symbolic
     link to it named '/etc/rc3.d/S99mysql.server'.

   * If too many processes try to connect very rapidly to
     'mysqld', you should see this error in the MySQL log:

          Error in accept: Protocol error

     You might try starting the server with the '--back_log=50' option
     as a workaround for this.

   * To configure the generation of core files on Solaris you should use
     the 'coreadm' command.  Because of the security implications of
     generating a core on a 'setuid()' application, by default, Solaris
     does not support core files on 'setuid()' programs.  However, you
     can modify this behavior using 'coreadm'.  If you enable 'setuid()'
     core files for the current user, they will be generated using the
     mode 600 and owned by the superuser.

2.7.1 Installing MySQL on Solaris Using a Solaris PKG
-----------------------------------------------------

You can install MySQL on Solaris using a binary package of the native
Solaris PKG format instead of the binary tarball distribution.

*Important*:

The installation package has a dependency on the Oracle Developer Studio
12.5 Runtime Libraries, which must be installed before you run the MySQL
installation package.  See the download options for Oracle Developer
Studio here
(http://www.oracle.com/technetwork/server-storage/developerstudio/downloads/index.html).
The installation package enables you to install the runtime libraries
only instead of the full Oracle Developer Studio; see instructions in
Installing Only the Runtime Libraries on Oracle Solaris 11
(https://docs.oracle.com/cd/E60778_01/html/E60743/gozsu.html#scrolltoc).

To use this package, download the corresponding
'mysql-VERSION-solaris11-PLATFORM.pkg.gz' file, then uncompress it.  For
example:

     shell> gunzip mysql-5.7.23-solaris11-x86_64.pkg.gz

To install a new package, use 'pkgadd' and follow the onscreen prompts.
You must have root privileges to perform this operation:

     shell> pkgadd -d mysql-5.7.23-solaris11-x86_64.pkg

     The following packages are available:
       1  mysql     MySQL Community Server (GPL)
                    (i86pc) 5.7.23

     Select package(s) you wish to process (or 'all' to process
     all packages). (default: all) [?,??,q]:

The PKG installer installs all of the files and tools needed, and then
initializes your database if one does not exist.  To complete the
installation, you should set the root password for MySQL as provided in
the instructions at the end of the installation.  Alternatively, you can
run the 'mysql_secure_installation'.
script that comes with the installation.

By default, the PKG package installs MySQL under the root path
'/opt/mysql'.  You can change only the installation root path when using
'pkgadd', which can be used to install MySQL in a different Solaris
zone.  If you need to install in a specific directory, use a binary
'tar' file distribution.

The 'pkg' installer copies a suitable startup script for MySQL into
'/etc/init.d/mysql'.  To enable MySQL to startup and shutdown
automatically, you should create a link between this file and the init
script directories.  For example, to ensure safe startup and shutdown of
MySQL you could use the following commands to add the right links:

     shell> ln /etc/init.d/mysql /etc/rc3.d/S91mysql
     shell> ln /etc/init.d/mysql /etc/rc0.d/K02mysql

To remove MySQL, the installed package name is 'mysql'.  You can use
this in combination with the 'pkgrm' command to remove the installation.

To upgrade when using the Solaris package file format, you must remove
the existing installation before installing the updated package.
Removal of the package does not delete the existing database
information, only the server, binaries and support files.  The typical
upgrade sequence is therefore:

     shell> mysqladmin shutdown
     shell> pkgrm mysql
     shell> pkgadd -d mysql-5.7.23-solaris11-x86_64.pkg
     shell> mysqld_safe &
     shell> mysql_upgrade

You should check the notes in upgrading-downgrading before
performing any upgrade.

2.8 Installing MySQL on FreeBSD
===============================

This section provides information about installing MySQL on variants of
FreeBSD Unix.

You can install MySQL on FreeBSD by using the binary distribution
provided by Oracle.  For more information, see
binary-installation.

The easiest (and preferred) way to install MySQL is to use the
'mysql-server' and 'mysql-client' ports available at
<http://www.freebsd.org/>.  Using these ports gives you the following
benefits:

   * A working MySQL with all optimizations enabled that are known to
     work on your version of FreeBSD.

   * Automatic configuration and build.

   * Startup scripts installed in '/usr/local/etc/rc.d'.

   * The ability to use 'pkg_info -L' to see which files are installed.

   * The ability to use 'pkg_delete' to remove MySQL if you no longer
     want it on your machine.

The MySQL build process requires GNU make ('gmake') to work.  If GNU
'make' is not available, you must install it first before compiling
MySQL.

To install using the ports system:

     # cd /usr/ports/databases/mysql57-server
     # make
     ...
     # cd /usr/ports/databases/mysql57-client
     # make
     ...

The standard port installation places the server into
'/usr/local/libexec/mysqld', with the startup script for the MySQL
server placed in '/usr/local/etc/rc.d/mysql-server'.

Some additional notes on the BSD implementation:

   * To remove MySQL after installation using the ports system:

          # cd /usr/ports/databases/mysql57-server
          # make deinstall
          ...
          # cd /usr/ports/databases/mysql57-client
          # make deinstall
          ...

   * If you get problems with the current date in MySQL, setting the
     'TZ' variable should help.  See environment-variables.

2.9 Installing MySQL from Source
================================

Building MySQL from the source code enables you to customize build
parameters, compiler optimizations, and installation location.  For a
list of systems on which MySQL is known to run, see
<http://www.mysql.com/support/supportedplatforms/database.html>.

Before you proceed with an installation from source, check whether
Oracle produces a precompiled binary distribution for your platform and
whether it works for you.  We put a great deal of effort into ensuring
that our binaries are built with the best possible options for optimal
performance.  Instructions for installing binary distributions are
available in binary-installation.

*Warning*:

Building MySQL with nonstandard options may lead to reduced
functionality, performance, or security.

*Source Installation Methods*

There are two methods for installing MySQL from source:

   * Use a standard MySQL source distribution.  To obtain a standard
     distribution, see getting-mysql.  For instructions on
     building from a standard distribution, see
     installing-source-distribution.

     Standard distributions are available as compressed 'tar' files, Zip
     archives, or RPM packages.  Distribution files have names of the
     form 'mysql-VERSION.tar.gz', 'mysql-VERSION.zip', or
     'mysql-VERSION.rpm', where VERSION is a number like '5.7.23'.  File
     names for source distributions can be distinguished from those for
     precompiled binary distributions in that source distribution names
     are generic and include no platform name, whereas binary
     distribution names include a platform name indicating the type of
     system for which the distribution is intended (for example,
     'pc-linux-i686' or 'winx64').

   * Use a MySQL development tree.  For information on building from one
     of the development trees, see installing-development-tree.

*Source Installation System Requirements*

Installation of MySQL from source requires several development tools.
Some of these tools are needed no matter whether you use a standard
source distribution or a development source tree.  Other tool
requirements depend on which installation method you use.

To install MySQL from source, the following system requirements must be
satisfied, regardless of installation method:

   * 'CMake', which is used as the build framework on all platforms.
     'CMake' can be downloaded from <http://www.cmake.org>.

   * A good 'make' program.  Although some platforms come with their own
     'make' implementations, it is highly recommended that you use GNU
     'make' 3.75 or higher.  It may already be available on your system
     as 'gmake'.  GNU 'make' is available from
     <http://www.gnu.org/software/make/>.

   * A working ANSI C++ compiler.  See the description of the
     'FORCE_UNSUPPORTED_COMPILER'.  option for some guidelines.

   * The Boost C++ libraries are required to build MySQL (but not to use
     it).  Boost 1.59.0 must be installed.  To obtain Boost and its
     installation instructions, visit the official site
     (http://www.boost.org).  After Boost is installed, tell the build
     system where the Boost files are located by defining the
     'WITH_BOOST' option when you invoke 'CMake'.  For example:

          shell> cmake . -DWITH_BOOST=/usr/local/boost_1_59_0

     Adjust the path as necessary to match your installation.

   * The ncurses (https://www.gnu.org/software/ncurses/ncurses.html)
     library.

   * Sufficient free memory.  If you encounter problems such as
     'internal compiler error' when compiling large source files, it may
     be that you have too little memory.  If compiling on a virtual
     machine, try increasing the memory allocation.

   * Perl is needed if you intend to run test scripts.  Most Unix-like
     systems include Perl.  On Windows, you can use a version such as
     ActiveState Perl.

To install MySQL from a standard source distribution, one of the
following tools is required to unpack the distribution file:

   * For a '.tar.gz' compressed 'tar' file: GNU 'gunzip' to uncompress
     the distribution and a reasonable 'tar' to unpack it.  If your
     'tar' program supports the 'z' option, it can both uncompress and
     unpack the file.

     GNU 'tar' is known to work.  The standard 'tar' provided with some
     operating systems is not able to unpack the long file names in the
     MySQL distribution.  You should download and install GNU 'tar', or
     if available, use a preinstalled version of GNU tar.  Usually this
     is available as 'gnutar', 'gtar', or as 'tar' within a GNU or Free
     Software directory, such as '/usr/sfw/bin' or '/usr/local/bin'.
     GNU 'tar' is available from <http://www.gnu.org/software/tar/>.

   * For a '.zip' Zip archive: 'WinZip' or another tool that can read
     '.zip' files.

   * For an '.rpm' RPM package: The 'rpmbuild' program used to build the
     distribution unpacks it.

To install MySQL from a development source tree, the following
additional tools are required:

   * The Git revision control system is required to obtain the
     development source code.  The GitHub Help
     (https://help.github.com/) provides instructions for downloading
     and installing Git on different platforms.  MySQL officially joined
     GitHub in September, 2014.  For more information about MySQL's move
     to GitHub, refer to the announcement on the MySQL Release
     Engineering blog: MySQL on GitHub
     (http://mysqlrelease.com/2014/09/mysql-on-github/)

   * 'bison' 2.1 or higher, available from
     <http://www.gnu.org/software/bison/>.  (Version 1 is no longer
     supported.)  Use the latest version of 'bison' where possible; if
     you experience problems, upgrade to a later version, rather than
     revert to an earlier one.

     'bison' is available from <http://www.gnu.org/software/bison/>.
     'bison' for Windows can be downloaded from
     <http://gnuwin32.sourceforge.net/packages/bison.htm>.  Download the
     package labeled 'Complete package, excluding sources'.  On Windows,
     the default location for 'bison' is the 'C:\Program Files\GnuWin32'
     directory.  Some utilities may fail to find 'bison' because of the
     space in the directory name.  Also, Visual Studio may simply hang
     if there are spaces in the path.  You can resolve these problems by
     installing into a directory that does not contain a space; for
     example 'C:\GnuWin32'.

   * On Solaris Express, 'm4' must be installed in addition to 'bison'.
     'm4' is available from <http://www.gnu.org/software/m4/>.

*Note*:

If you have to install any programs, modify your 'PATH' environment
variable to include any directories in which the programs are located.
See setting-environment-variables.

If you run into problems and need to file a bug report, please use the
instructions in bug-reports.

2.9.1 MySQL Layout for Source Installation
------------------------------------------

By default, when you install MySQL after compiling it from source, the
installation step installs files under '/usr/local/mysql'.  The
component locations under the installation directory are the same as for
binary distributions.  See binary-installation-layout, and
windows-installation-layout.  To configure installation locations
different from the defaults, use the options described at
source-configuration-options.

2.9.2 Installing MySQL Using a Standard Source Distribution
-----------------------------------------------------------

To install MySQL from a standard source distribution:

  1. Verify that your system satisfies the tool requirements listed at
     source-installation.

  2. Obtain a distribution file using the instructions in
     getting-mysql.

  3. Configure, build, and install the distribution using the
     instructions in this section.

  4. Perform postinstallation procedures using the instructions in
     postinstallation.

In MySQL 5.7, 'CMake' is used as the build framework on all platforms.
The instructions given here should enable you to produce a working
installation.  For additional information on using 'CMake' to build
MySQL, see How to Build MySQL Server with CMake
(http://dev.mysql.com/doc/internals/en/cmake.html).

If you start from a source RPM, use the following command to make a
binary RPM that you can install.  If you do not have 'rpmbuild', use
'rpm' instead.

     shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm

The result is one or more binary RPM packages that you install as
indicated in linux-installation-rpm.

The sequence for installation from a compressed 'tar' file or Zip
archive source distribution is similar to the process for installing
from a generic binary distribution (see binary-installation),
except that it is used on all platforms and includes steps to configure
and compile the distribution.  For example, with a compressed 'tar' file
source distribution on Unix, the basic installation command sequence
looks like this:

     # Preconfiguration setup
     shell> groupadd mysql
     shell> useradd -r -g mysql -s /bin/false mysql
     # Beginning of source-build specific instructions
     shell> tar zxvf mysql-VERSION.tar.gz
     shell> cd mysql-VERSION
     shell> mkdir bld
     shell> cd bld
     shell> cmake ..
     shell> make
     shell> make install
     # End of source-build specific instructions
     # Postinstallation setup
     shell> cd /usr/local/mysql
     shell> mkdir mysql-files
     shell> chown mysql:mysql mysql-files
     shell> chmod 750 mysql-files
     shell> bin/mysqld --initialize --user=mysql
     shell> bin/mysql_ssl_rsa_setup
     shell> bin/mysqld_safe --user=mysql &
     # Next command is optional
     shell> cp support-files/mysql.server /etc/init.d/mysql.server

A more detailed version of the source-build specific instructions is
shown following.

*Note*:

The procedure shown here does not set up any passwords for MySQL
accounts.  After following the procedure, proceed to
postinstallation, for postinstallation setup and testing.

*Perform Preconfiguration Setup*

On Unix, set up the 'mysql' user and group that will be used to run and
execute the MySQL server and own the database directory.  For details,
see Creating a 'mysql' System User and Group, in
binary-installation.  Then perform the following steps as the 'mysql'
user, except as noted.

*Obtain and Unpack the Distribution*

Pick the directory under which you want to unpack the distribution and
change location into it.

Obtain a distribution file using the instructions in
getting-mysql.

Unpack the distribution into the current directory:

   * To unpack a compressed 'tar' file, 'tar' can uncompress and unpack
     the distribution if it has 'z' option support:

          shell> tar zxvf mysql-VERSION.tar.gz

     If your 'tar' does not have 'z' option support, use 'gunzip' to
     unpack the distribution and 'tar' to unpack it:

          shell> gunzip < mysql-VERSION.tar.gz | tar xvf -

     Alternatively, 'CMake' can uncompress and unpack the distribution:

          shell> cmake -E tar zxvf mysql-VERSION.tar.gz

   * To unpack a Zip archive, use 'WinZip' or another tool that can read
     '.zip' files.

Unpacking the distribution file creates a directory named
'mysql-VERSION'.

*Configure the Distribution*

Change location into the top-level directory of the unpacked
distribution:

     shell> cd mysql-VERSION

Build outside of the source tree to keep the tree clean.  If the
top-level source directory is named 'mysql-src' under your current
working directory, you can build in a directory named 'bld' at the same
level.  Create the directory and go there:

     shell> mkdir bld
     shell> cd bld

Configure the build directory.  The minimum configuration command
includes no options to override configuration defaults:

     shell> cmake ../mysql-src

The build directory needs not be outside the source tree.

For example, you can build in a directory named 'bld' under the
top-level source tree.  To do this, starting with 'mysql-src' as your
current working directory, create the directory 'bld' and then go there:

     shell> mkdir bld
     shell> cd bld

Configure the build directory.  The minimum configuration command
includes no options to override configuration defaults:

     shell> cmake ..

If you have multiple source trees at the same level (for example, to
build multiple versions of MySQL), the second strategy can be
advantageous.  The first strategy places all build directories at the
same level, which requires that you choose a unique name for each.  With
the second strategy, you can use the same name for the build directory
within each source tree.  The following instructions assume this second
strategy.

On Windows, specify the development environment.  For example, the
following commands configure MySQL for 32-bit or 64-bit builds,
respectively:

     shell> cmake .. -G "Visual Studio 12 2013"
     shell> cmake .. -G "Visual Studio 12 2013 Win64"

On macOS, to use the Xcode IDE:

     shell> cmake .. -G Xcode

When you run 'cmake', you might want to add options to the command line.
Here are some examples:

   * '-DBUILD_CONFIG=mysql_release': Configure the source with the same
     build options used by Oracle to produce binary distributions for
     official MySQL releases.

   * '-DCMAKE_INSTALL_PREFIX=DIR_NAME': Configure the distribution for
     installation under a particular location.

   * '-DCPACK_MONOLITHIC_INSTALL=1': Cause 'make package' to generate a
     single installation file rather than multiple files.

   * '-DWITH_DEBUG=1': Build the distribution with debugging support.

For a more extensive list of options, see
source-configuration-options.

To list the configuration options, use one of the following commands:

     shell> cmake .. -L   # overview
     shell> cmake .. -LH  # overview with help text
     shell> cmake .. -LAH # all params with help text
     shell> ccmake ..     # interactive display

If 'CMake' fails, you might need to reconfigure by running it again with
different options.  If you do reconfigure, take note of the following:

   * If 'CMake' is run after it has previously been run, it may use
     information that was gathered during its previous invocation.  This
     information is stored in 'CMakeCache.txt'.  When 'CMake' starts up,
     it looks for that file and reads its contents if it exists, on the
     assumption that the information is still correct.  That assumption
     is invalid when you reconfigure.

   * Each time you run 'CMake', you must run 'make' again to recompile.
     However, you may want to remove old object files from previous
     builds first because they were compiled using different
     configuration options.

To prevent old object files or configuration information from being
used, run these commands in the build direcotry on Unix before
re-running 'CMake':

     shell> make clean
     shell> rm CMakeCache.txt

Or, on Windows:

     shell> devenv MySQL.sln /clean
     shell> del CMakeCache.txt

If you are going to send mail to a MySQL mailing list to ask for
configuration assistance, first check the files in the 'CMakeFiles'
directory for useful information about the failure.  To file a bug
report, please use the instructions in bug-reports.

*Build the Distribution*

On Unix:

     shell> make
     shell> make VERBOSE=1

The second command sets 'VERBOSE' to show the commands for each compiled
source.

Use 'gmake' instead on systems where you are using GNU 'make' and it has
been installed as 'gmake'.

On Windows:

     shell> devenv MySQL.sln /build RelWithDebInfo

If you have gotten to the compilation stage, but the distribution does
not build, see compilation-problems, for help.  If that does not
solve the problem, please enter it into our bugs database using the
instructions given in bug-reports.  If you have installed the
latest versions of the required tools, and they crash trying to process
our configuration files, please report that also.  However, if you get a
'command not found' error or a similar problem for required tools, do
not report it.  Instead, make sure that all the required tools are
installed and that your 'PATH' variable is set correctly so that your
shell can find them.

*Install the Distribution*

On Unix:

     shell> make install

This installs the files under the configured installation directory (by
default, '/usr/local/mysql').  You might need to run the command as
'root'.

To install in a specific directory, add a 'DESTDIR' parameter to the
command line:

     shell> make install DESTDIR="/opt/mysql"

Alternatively, generate installation package files that you can install
where you like:

     shell> make package

This operation produces one or more '.tar.gz' files that can be
installed like generic binary distribution packages.  See
binary-installation.  If you run 'CMake' with
'-DCPACK_MONOLITHIC_INSTALL=1', the operation produces a single file.
Otherwise, it produces multiple files.

On Windows, generate the data directory, then create a '.zip' archive
installation package:

     shell> devenv MySQL.sln /build RelWithDebInfo /project initial_database
     shell> devenv MySQL.sln /build RelWithDebInfo /project package

You can install the resulting '.zip' archive where you like.  See
windows-install-archive.

*Perform Postinstallation Setup*

The remainder of the installation process involves setting up the
configuration file, creating the core databases, and starting the MySQL
server.  For instructions, see postinstallation.

*Note*:

The accounts that are listed in the MySQL grant tables initially have no
passwords.  After starting the server, you should set up passwords for
them using the instructions in postinstallation.

2.9.3 Installing MySQL Using a Development Source Tree
------------------------------------------------------

This section describes how to install MySQL from the latest development
source code, which is hosted on GitHub (https://github.com/).  To obtain
the MySQL Server source code from this repository hosting service, you
can set up a local MySQL Git repository.

On GitHub (https://github.com/), MySQL Server and other MySQL projects
are found on the MySQL (https://github.com/mysql) page.  The MySQL
Server project is a single repository that contains branches for several
MySQL series.

MySQL officially joined GitHub in September, 2014.  For more information
about MySQL's move to GitHub, refer to the announcement on the MySQL
Release Engineering blog: MySQL on GitHub
(http://mysqlrelease.com/2014/09/mysql-on-github/)

*Prerequisites for Installing from Development Source*

To install MySQL from a development source tree, your system must
satisfy the tool requirements outlined in source-installation.

*Setting Up a MySQL Git Repository*

To set up a MySQL Git repository on your machine, use this procedure:

  1. Clone the MySQL Git repository to your machine.  The following
     command clones the MySQL Git repository to a directory named
     'mysql-server'.  The initial download will take some time to
     complete, depending on the speed of your connection.

          ~$ git clone https://github.com/mysql/mysql-server.git
          Cloning into 'mysql-server'...
          remote: Counting objects: 1035465, done.
          remote: Total 1035465 (delta 0), reused 0 (delta 0)
          Receiving objects: 100% (1035465/1035465), 437.48 MiB | 5.10 MiB/s, done.
          Resolving deltas: 100% (855607/855607), done.
          Checking connectivity... done.
          Checking out files: 100% (21902/21902), done.

  2. When the clone operation completes, the contents of your local
     MySQL Git repository appear similar to the following:

          ~$ cd mysql-server

          ~/mysql-server$ ls
          BUILD            COPYING             libmysqld    regex          unittest
          BUILD-CMAKE      dbug                libservices  scripts        VERSION
          client           Docs                man          sql            vio
          cmake            extra               mysql-test   sql-common     win
          CMakeLists.txt   include             mysys        storage        zlib
          cmd-line-utils   INSTALL-SOURCE      packaging    strings
          config.h.cmake   INSTALL-WIN-SOURCE  plugin       support-files
          configure.cmake  libmysql            README       tests

  3. Use the 'git branch -r' command to view the remote tracking
     branches for the MySQL repository.

          ~/mysql-server$ git branch -r
            origin/5.5
            origin/5.6
            origin/5.7
            origin/HEAD -> origin/5.7
            origin/cluster-7.2
            origin/cluster-7.3
            origin/cluster-7.4

  4. To view the branches that are checked out in your local repository,
     issue the 'git branch' command.  When you cloned the MySQL Git
     repository, the MySQL 5.7 branch was checked out automatically.
     The asterisk identifies the 5.7 branch as the active branch.

          ~/mysql-server$ git branch
          * 5.7

  5. To check out a different MySQL branch, run the 'git checkout'
     command, specifying the branch name.  For example, to check out the
     MySQL 5.5 branch:

          ~/mysql-server$ git checkout 5.5
          Branch 5.5 set up to track remote branch 5.5 from origin.
          Switched to a new branch '5.5'

  6. Run 'git branch' to verify that the MySQL 5.5 branch is present.
     MySQL 5.5, which is the last branch you checked out, is marked by
     an asterisk indicating that it is the active branch.

          ~/mysql-server$ git branch
          * 5.5
            5.7

  7. Use the 'git checkout' command to switch between branches.  For
     example:

          ~/mysql-server$ git checkout 5.7

  8. To obtain changes made after your initial setup of the MySQL Git
     repository, switch to the branch you want to update and issue the
     'git pull' command:

          ~/mysql-server$ git checkout 5.7
          ~/mysql-server$ git pull

     To examine the commit history, use the 'git log' option:

          ~/mysql-server$ git log

     You can also browse commit history and source code on the GitHub
     MySQL (https://github.com/mysql) site.

     If you see changes or code that you have a question about, send an
     email to the MySQL 'internals' mailing list.  See
     mailing-lists.  For information about contributing a patch, see
     Contributing to MySQL Server
     (http://mysqlserverteam.com/contributing-to-mysql-server/).

  9. After you have cloned the MySQL Git repository and have checked out
     the branch you want to build, you can build MySQL Server from the
     source code.  Instructions are provided in
     installing-source-distribution, except that you skip the part
     about obtaining and unpacking the distribution.

     Be careful about installing a build from a distribution source tree
     on a production machine.  The installation command may overwrite
     your live release installation.  If you already have MySQL
     installed and do not want to overwrite it, run 'CMake' with values
     for the 'CMAKE_INSTALL_PREFIX', 'MYSQL_TCP_PORT', and
     'MYSQL_UNIX_ADDR' options different from those used by your
     production server.  For additional information about preventing
     multiple servers from interfering with each other, see
     multiple-servers.

     Play hard with your new installation.  For example, try to make new
     features crash.  Start by running 'make test'.  See
     mysql-test-suite.

2.9.4 MySQL Source-Configuration Options
----------------------------------------

The 'CMake' program provides a great deal of control over how you
configure a MySQL source distribution.  Typically, you do this using
options on the 'CMake' command line.  For information about options
supported by 'CMake', run either of these commands in the top-level
source directory:

     shell> cmake . -LH
     shell> ccmake .

You can also affect 'CMake' using certain environment variables.  See
environment-variables.

The following table shows the available 'CMake' options.  In the
'Default' column, 'PREFIX' stands for the value of the
'CMAKE_INSTALL_PREFIX' option, which specifies the installation base
directory.  This value is used as the parent location for several of the
installation subdirectories.

*MySQL Source-Configuration Option Reference (CMake)*

Formats                Description            Default        IntroducedRemoved

'BUILD_CONFIG'         Use same build
                       options as official
                       releases

'CMAKE_BUILD_TYPE'     Type of build to       'RelWithDebInfo'
                       produce

'CMAKE_CXX_FLAGS'      Flags for C++
                       Compiler

'CMAKE_C_FLAGS'        Flags for C Compiler

'CMAKE_INSTALL_PREFIX' Installation base      '/usr/local/mysql'
                       directory

'COMPILATION_COMMENT'  Comment about
                       compilation
                       environment

'CPACK_MONOLITHIC_INSTALL'Whether package     'OFF'
                       build produces
                       single file

'DEFAULT_CHARSET'      The default server     'latin1'
                       character set

'DEFAULT_COLLATION'    The default server     'latin1_swedish_ci'
                       collation

'DISABLE_PSI_COND'     Exclude Performance    'OFF'          5.7.3
                       Schema condition
                       instrumentation

'DISABLE_PSI_FILE'     Exclude Performance    'OFF'          5.7.3
                       Schema file
                       instrumentation

'DISABLE_PSI_IDLE'     Exclude Performance    'OFF'          5.7.3
                       Schema idle
                       instrumentation

'DISABLE_PSI_MEMORY'   Exclude Performance    'OFF'          5.7.3
                       Schema memory
                       instrumentation

'DISABLE_PSI_METADATA' Exclude Performance    'OFF'          5.7.3
                       Schema metadata
                       instrumentation

'DISABLE_PSI_MUTEX'    Exclude Performance    'OFF'          5.7.3
                       Schema mutex
                       instrumentation

'DISABLE_PSI_PS'       Exclude the            'OFF'          5.7.3
                       performance schema
                       prepared statements

'DISABLE_PSI_RWLOCK'   Exclude Performance    'OFF'          5.7.3
                       Schema rwlock
                       instrumentation

'DISABLE_PSI_SOCKET'   Exclude Performance    'OFF'          5.7.3
                       Schema socket
                       instrumentation

'DISABLE_PSI_SP'       Exclude Performance    'OFF'          5.7.3
                       Schema stored
                       program
                       instrumentation

'DISABLE_PSI_STAGE'    Exclude Performance    'OFF'          5.7.3
                       Schema stage
                       instrumentation

'DISABLE_PSI_STATEMENT'Exclude Performance    'OFF'          5.7.3
                       Schema statement
                       instrumentation

'DISABLE_PSI_STATEMENT_DIGEST'Exclude Performance'OFF'       5.7.3
                       Schema
                       statements_digest
                       instrumentation

'DISABLE_PSI_TABLE'    Exclude Performance    'OFF'          5.7.3
                       Schema table
                       instrumentation

'DISABLE_PSI_THREAD'   Exclude the            'OFF'          5.7.3
                       performance schema
                       thread
                       instrumentation

'DISABLE_PSI_TRANSACTION'Exclude the          'OFF'          5.7.3
                       performance schema
                       transaction
                       instrumentation

'DOWNLOAD_BOOST'       Whether to download    'OFF'          5.7.5
                       the Boost library

'DOWNLOAD_BOOST_TIMEOUT'Timeout in seconds    '600'          5.7.6
                       for downloading the
                       Boost library

'ENABLED_LOCAL_INFILE' Whether to enable      'OFF'
                       LOCAL for LOAD DATA
                       INFILE

'ENABLED_PROFILING'    Whether to enable      'ON'
                       query profiling code

'ENABLE_DEBUG_SYNC'    Whether to enable      'ON'                   5.7.1
                       Debug Sync support

'ENABLE_DOWNLOADS'     Whether to download    'OFF'
                       optional files

'ENABLE_DTRACE'        Whether to include
                       DTrace support

'ENABLE_GCOV'          Whether to include
                       gcov support

'ENABLE_GPROF'         Enable gprof           'OFF'
                       (optimized Linux
                       builds only)

'FORCE_UNSUPPORTED_COMPILER'Whether to permit 'OFF'          5.7.5
                       unsupported compiler

'IGNORE_AIO_CHECK'     With                   'OFF'
                       -DBUILD_CONFIG=mysql_release,
                       ignore libaio check

'INNODB_PAGE_ATOMIC_REF_COUNT'Enable or disable'ON'          5.7.4   5.7.5
                       atomic page
                       reference counting

'INSTALL_BINDIR'       User executables       'PREFIX/bin'
                       directory

'INSTALL_DOCDIR'       Documentation          'PREFIX/docs'
                       directory

'INSTALL_DOCREADMEDIR' README file            'PREFIX'
                       directory

'INSTALL_INCLUDEDIR'   Header file            'PREFIX/include'
                       directory

'INSTALL_INFODIR'      Info file directory    'PREFIX/docs'

'INSTALL_LAYOUT'       Select predefined      'STANDALONE'
                       installation layout

'INSTALL_LIBDIR'       Library file           'PREFIX/lib'
                       directory

'INSTALL_MANDIR'       Manual page            'PREFIX/man'
                       directory

'INSTALL_MYSQLKEYRINGDIR'Directory for        'platform      5.7.11
                       keyring_file plugin    specific'
                       data file

'INSTALL_MYSQLSHAREDIR'Shared data            'PREFIX/share'
                       directory

'INSTALL_MYSQLTESTDIR' mysql-test directory   'PREFIX/mysql-test'

'INSTALL_PKGCONFIGDIR' Directory for          'INSTALL_LIBDIR/pkgconfig'5.7.9
                       mysqlclient.pc
                       pkg-config file

'INSTALL_PLUGINDIR'    Plugin directory       'PREFIX/lib/plugin'

'INSTALL_SBINDIR'      Server executable      'PREFIX/bin'
                       directory

'INSTALL_SCRIPTDIR'    Scripts directory      'PREFIX/scripts'

'INSTALL_SECURE_FILE_PRIVDIR'secure_file_priv 'platform      5.7.6
                       default value          specific'

'INSTALL_SECURE_FILE_PRIV_EMBEDDEDDIR'secure_file_priv       5.7.8
                       default value for
                       libmysqld

'INSTALL_SHAREDIR'     aclocal/mysql.m4       'PREFIX/share'
                       installation
                       directory

'INSTALL_SQLBENCHDIR'  sql-bench directory    'PREFIX'               5.7.8

'INSTALL_SUPPORTFILESDIR'Extra support files  'PREFIX/support-files'
                       directory

'MAX_INDEXES'          Maximum indexes per    '64'           5.7.1
                       table

'MUTEX_TYPE'           InnoDB mutex type      'event'        5.7.2

'MYSQLX_TCP_PORT'      TCP/IP port number     '33060'        5.7.17
                       used by X Plugin

'MYSQLX_UNIX_ADDR'     Unix socket file       '/tmp/mysqlx.sock'5.7.15
                       used by X Plugin

'MYSQL_DATADIR'        Data directory

'MYSQL_MAINTAINER_MODE'Whether to enable      'OFF'
                       MySQL
                       maintainer-specific
                       development
                       environment

'MYSQL_PROJECT_NAME'   Windows/OS X project   'MySQL'
                       name

'MYSQL_TCP_PORT'       TCP/IP port number     '3306'

'MYSQL_UNIX_ADDR'      Unix socket file       '/tmp/mysql.sock'

'ODBC_INCLUDES'        ODBC includes
                       directory

'ODBC_LIB_DIR'         ODBC library
                       directory

'OPTIMIZER_TRACE'      Whether to support
                       optimizer tracing

'REPRODUCIBLE_BUILD'   Take extra care to                    5.7.19
                       create a build
                       result independent
                       of build location
                       and time

'SUNPRO_CXX_LIBRARY'   Client link library                   5.7.5
                       on Solaris 10+

'SYSCONFDIR'           Option file
                       directory

'SYSTEMD_PID_DIR'      Directory for PID      '/var/run/mysqld'5.7.6
                       file under systemd

'SYSTEMD_SERVICE_NAME' Name of MySQL          'mysqld'       5.7.6
                       service under
                       systemd

'TMPDIR'               tmpdir default value                  5.7.4

'WIN_DEBUG_NO_INLINE'  Whether to disable     'OFF'          5.7.6
                       function inlining

'WITHOUT_SERVER'       Do not build the       'OFF'
                       server

'WITHOUT_xxx_STORAGE_ENGINE'Exclude storage
                       engine xxx from
                       build

'WITH_ASAN'            Enable                 'OFF'          5.7.3
                       AddressSanitizer

'WITH_ASAN_SCOPE'      Enable                 'OFF'          5.7.21
                       AddressSanitizer
                       -fsanitize-address-use-after-scope
                       Clang flag

'WITH_AUTHENTICATION_LDAP'Whether to report   'OFF'          5.7.19
                       error if LDAP
                       authentication
                       plugins cannot be
                       built

'WITH_AUTHENTICATION_PAM'Build PAM            'OFF'
                       authentication
                       plugin

'WITH_AWS_SDK'         Location of Amazon                    5.7.19
                       Web Services
                       software development
                       kit

'WITH_BOOST'           The location of the                   5.7.5
                       Boost library
                       sources

'WITH_CLIENT_PROTOCOL_TRACING'Build client-side'ON'          5.7.2
                       protocol tracing
                       framework

'WITH_CURL'            Location of curl                      5.7.19
                       library

'WITH_DEBUG'           Whether to include     'OFF'
                       debugging support

'WITH_DEFAULT_COMPILER_OPTIONS'Whether to use 'ON'
                       default compiler
                       options

'WITH_DEFAULT_FEATURE_SET'Whether to use      'ON'
                       default feature set

'WITH_EDITLINE'        Which                  'bundled'      5.7.2
                       libedit/editline
                       library to use

'WITH_EMBEDDED_SERVER' Whether to build       'OFF'
                       embedded server

'WITH_EMBEDDED_SHARED_LIBRARY'Whether to build a'OFF'        5.7.4
                       shared embedded
                       server library

'WITH_EXTRA_CHARSETS'  Which extra            'all'
                       character sets to
                       include

'WITH_INNODB_EXTRA_DEBUG'Whether to include   'OFF'          5.7.2
                       extra debugging
                       support for InnoDB.

'WITH_INNODB_MEMCACHED'Whether to generate    'OFF'
                       memcached shared
                       libraries.

'WITH_KEYRING_TEST'    Build the keyring      'OFF'          5.7.11
                       test program

'WITH_LIBEVENT'        Which libevent         'bundled'
                       library to use

'WITH_LIBWRAP'         Whether to include     'OFF'
                       libwrap (TCP
                       wrappers) support

'WITH_LZ4'             Type of LZ4 library    'bundled'      5.7.14
                       support

'WITH_MECAB'           Compiles MeCab                        5.7.6

'WITH_MSAN'            Enable                 'OFF'          5.7.4
                       MemorySanitizer

'WITH_MSCRT_DEBUG'     Enable Visual Studio   'OFF'          5.7.6
                       CRT memory leak
                       tracing

'WITH_NDBCLUSTER'      Build the NDB          'ON'
                       storage engine;
                       alias for
                       WITH_NDBCLUSTER_STORAGE_ENGINE

'WITH_NDBCLUSTER_STORAGE_ENGINE'Build the NDB 'ON'
                       storage engine

'WITH_NDB_TEST'        Include NDB API test   'OFF'
                       programs.

'WITH_NUMA'            Set NUMA memory                       5.7.17
                       allocation policy

'WITH_PROTOBUF'        Which Protocol         'bundled'      5.7.12
                       Buffers package to
                       use

'WITH_RAPID'           Whether to build       'ON'           5.7.12
                       rapid development
                       cycle plugins

'WITH_SSL'             Type of SSL support    'bundled'

'WITH_SYSTEMD'         Enable installation    'OFF'          5.7.6
                       of systemd support
                       files

'WITH_TEST_TRACE_PLUGIN'Build test protocol   'OFF'          5.7.2
                       trace plugin

'WITH_UBSAN'           Enable Undefined       'OFF'          5.7.6
                       Behavior Sanitizer

'WITH_UNIT_TESTS'      Compile MySQL with     'ON'
                       unit tests

'WITH_UNIXODBC'        Enable unixODBC        'OFF'
                       support

'WITH_VALGRIND'        Whether to compile     'OFF'
                       in Valgrind header
                       files

'WITH_ZLIB'            Type of zlib support   'bundled'

'WITH_xxx_STORAGE_ENGINE'Compile storage
                       engine xxx
                       statically into
                       server

The following sections provide more information about 'CMake' options.

   * cmake-general-options

   * cmake-installation-layout-options

   * option_cmake_storage_engine_options

   * cmake-feature-options

   * cmake-compiler-flags

   * cmake-mysql-cluster-options

For boolean options, the value may be specified as 1 or 'ON' to enable
the option, or as 0 or 'OFF' to disable the option.

Many options configure compile-time defaults that can be overridden at
server startup.  For example, the 'CMAKE_INSTALL_PREFIX',
'MYSQL_TCP_PORT', and 'MYSQL_UNIX_ADDR' options that configure the
default installation base directory location, TCP/IP port number, and
Unix socket file can be changed at server startup with the '--basedir',
'--port', and '--socket' options for 'mysqld'.  Where
applicable, configuration option descriptions indicate the corresponding
'mysqld' startup option.

*General Options*

   *
     '-DBUILD_CONFIG=mysql_release'

     This option configures a source distribution with the same build
     options used by Oracle to produce binary distributions for official
     MySQL releases.

   *
     '-DCMAKE_BUILD_TYPE=TYPE'

     The type of build to produce:

        * 'RelWithDebInfo': Enable optimizations and generate debugging
          information.  This is the default MySQL build type.

        * 'Debug': Disable optimizations and generate debugging
          information.  This build type is also used if the 'WITH_DEBUG'
          option is enabled.  That is, '-DWITH_DEBUG=1' has the same
          effect as '-DCMAKE_BUILD_TYPE=Debug'.

   *
     '-DCPACK_MONOLITHIC_INSTALL=BOOL'

     This option affects whether the 'make package' operation produces
     multiple installation package files or a single file.  If disabled,
     the operation produces multiple installation package files, which
     may be useful if you want to install only a subset of a full MySQL
     installation.  If enabled, it produces a single file for installing
     everything.

*Installation Layout Options*

The 'CMAKE_INSTALL_PREFIX' option indicates the base installation
directory.  Other options with names of the form 'INSTALL_XXX' that
indicate component locations are interpreted relative to the prefix and
their values are relative pathnames.  Their values should not include
the prefix.

   *
     '-DCMAKE_INSTALL_PREFIX=DIR_NAME'

     The installation base directory.

     This value can be set at server startup with the '--basedir'
     option.

   *
     '-DINSTALL_BINDIR=DIR_NAME'

     Where to install user programs.

   *
     '-DINSTALL_DOCDIR=DIR_NAME'

     Where to install documentation.

   *
     '-DINSTALL_DOCREADMEDIR=DIR_NAME'

     Where to install 'README' files.

   *
     '-DINSTALL_INCLUDEDIR=DIR_NAME'

     Where to install header files.

   *
     '-DINSTALL_INFODIR=DIR_NAME'

     Where to install Info files.

   *
     '-DINSTALL_LAYOUT=NAME'

     Select a predefined installation layout:

        * 'STANDALONE': Same layout as used for '.tar.gz' and '.zip'
          packages.  This is the default.

        * 'RPM': Layout similar to RPM packages.

        * 'SVR4': Solaris package layout.

        * 'DEB': DEB package layout (experimental).

     You can select a predefined layout but modify individual component
     installation locations by specifying other options.  For example:

          shell> cmake . -DINSTALL_LAYOUT=SVR4 -DMYSQL_DATADIR=/var/mysql/data

     The 'INSTALL_LAYOUT' value determines the default value of the
     'secure_file_priv', 'keyring_encrypted_file_data', and
     'keyring_file_data' system variables.  See the descriptions of
     those variables in server-system-variables, and
     keyring-system-variables.

   *
     '-DINSTALL_LIBDIR=DIR_NAME'

     Where to install library files.

   *
     '-DINSTALL_MANDIR=DIR_NAME'

     Where to install manual pages.

   *
     '-DINSTALL_MYSQLKEYRINGDIR=DIR_PATH'

     The default directory to use as the location of the 'keyring_file'
     plugin data file.  The default value is platform specific and
     depends on the value of the 'INSTALL_LAYOUT' 'CMake' option; see
     the description of the 'keyring_file_data' system variable in
     server-system-variables.

     This option was added in MySQL 5.7.11.

   *
     '-DINSTALL_MYSQLSHAREDIR=DIR_NAME'

     Where to install shared data files.

   *
     '-DINSTALL_MYSQLTESTDIR=DIR_NAME'

     Where to install the 'mysql-test' directory.  To suppress
     installation of this directory, explicitly set the option to the
     empty value ('-DINSTALL_MYSQLTESTDIR=').

   *
     '-DINSTALL_PKGCONFIGDIR=DIR_NAME'

     The directory in which to install the 'mysqlclient.pc' file for use
     by 'pkg-config'.  The default value is 'INSTALL_LIBDIR/pkgconfig',
     unless 'INSTALL_LIBDIR' ends with '/mysql', in which case that is
     removed first.

   *
     '-DINSTALL_PLUGINDIR=DIR_NAME'

     The location of the plugin directory.

     This value can be set at server startup with the '--plugin_dir'
     option.

   *
     '-DINSTALL_SBINDIR=DIR_NAME'

     Where to install the 'mysqld' server.

   *
     '-DINSTALL_SCRIPTDIR=DIR_NAME'

     Where to install 'mysql_install_db'.

   *
     '-DINSTALL_SECURE_FILE_PRIVDIR=DIR_NAME'

     The default value for the 'secure_file_priv' system variable.  The
     default value is platform specific and depends on the value of the
     'INSTALL_LAYOUT' 'CMake' option; see the description of the
     'secure_file_priv' system variable in
     server-system-variables.

     To set the value for the 'libmysqld' embedded server, use
     'INSTALL_SECURE_FILE_PRIV_EMBEDDEDDIR'.

   *
     '-DINSTALL_SECURE_FILE_PRIV_EMBEDDEDDIR=DIR_NAME'

     The default value for the 'secure_file_priv' system variable, for
     the 'libmysqld' embedded server.

     *Note*:

     The 'libmysqld' embedded server library is deprecated as of MySQL
     5.7.19 and will be removed in MySQL 8.0.

   *
     '-DINSTALL_SHAREDIR=DIR_NAME'

     Where to install 'aclocal/mysql.m4'.

   *
     '-DINSTALL_SQLBENCHDIR=DIR_NAME'

     Where to install the 'sql-bench' directory.  To suppress
     installation of this directory, explicitly set the option to the
     empty value ('-DINSTALL_SQLBENCHDIR=').

     The 'sql-bench' directory is no longer included in MYSQL
     distributions, so the 'INSTALL_SQLBENCHDIR=' option is removed as
     well.

   *
     '-DINSTALL_SUPPORTFILESDIR=DIR_NAME'

     Where to install extra support files.

   *
     '-DMYSQL_DATADIR=DIR_NAME'

     The location of the MySQL data directory.

     This value can be set at server startup with the '--datadir'
     option.

   *
     '-DODBC_INCLUDES=DIR_NAME'

     The location of the ODBC includes directory, and may be used while
     configuring Connector/ODBC.

   *
     '-DODBC_LIB_DIR=DIR_NAME'

     The location of the ODBC library directory, and may be used while
     configuring Connector/ODBC.

   *
     '-DSYSCONFDIR=DIR_NAME'

     The default 'my.cnf' option file directory.

     This location cannot be set at server startup, but you can start
     the server with a given option file using the
     '--defaults-file=FILE_NAME' option, where FILE_NAME is the full
     path name to the file.

   *
     '-DSYSTEMD_PID_DIR=DIR_NAME'

     The name of the directory in which to create the PID file when
     MySQL is managed by systemd.  The default is '/var/run/mysqld';
     this might be changed implicitly according to the 'INSTALL_LAYOUT'
     value.

     This option is ignored unless 'WITH_SYSTEMD' is enabled.

   *
     '-DSYSTEMD_SERVICE_NAME=NAME'

     The name of the MySQL service to use when MySQL is managed by
     systemd.  The default is 'mysqld'; this might be changed implicitly
     according to the 'INSTALL_LAYOUT' value.

     This option is ignored unless 'WITH_SYSTEMD' is enabled.

   *
     '-DTMPDIR=DIR_NAME'

     The default location to use for the 'tmpdir' system variable.  If
     unspecified, the value defaults to 'P_tmpdir' in '<stdio.h>'.

*Storage Engine Options*

Storage engines are built as plugins.  You can build a plugin as a
static module (compiled into the server) or a dynamic module (built as a
dynamic library that must be installed into the server using the
'INSTALL PLUGIN' statement or the '--plugin-load'
option before it can be used).  Some plugins might not support static or
dynamic building.

The 'InnoDB', 'MyISAM',
see 'MERGE',
'MEMORY', and 'CSV'.
engines are mandatory (always compiled into the server) and need not be
installed explicitly.

To compile a storage engine statically into the server, use
'-DWITH_ENGINE_STORAGE_ENGINE=1'.  Some permissible ENGINE values are
'ARCHIVE', 'BLACKHOLE', 'EXAMPLE', 'FEDERATED', 'NDB' or 'NDBCLUSTER'
(see 'NDB'), and 'PARTITION' (partitioning support).
Examples:

     -DWITH_ARCHIVE_STORAGE_ENGINE=1
     -DWITH_BLACKHOLE_STORAGE_ENGINE=1

*Note*:

'WITH_NDBCLUSTER_STORAGE_ENGINE' is supported only when building NDB
Cluster using the NDB Cluster sources.  It cannot be used to enable
clustering support in other MySQL source trees or distributions.  In NDB
Cluster source distributions, it is enabled by default.  See
mysql-cluster-install-linux-source, and
mysql-cluster-install-windows-source, for more information.

*Note*:

It is not possible to compile without Performance Schema support.  If it
is desired to compile without particular types of instrumentation, that
can be done with the following 'CMake' options:

     DISABLE_PSI_COND
     DISABLE_PSI_FILE
     DISABLE_PSI_IDLE
     DISABLE_PSI_MEMORY
     DISABLE_PSI_METADATA
     DISABLE_PSI_MUTEX
     DISABLE_PSI_PS
     DISABLE_PSI_RWLOCK
     DISABLE_PSI_SOCKET
     DISABLE_PSI_SP
     DISABLE_PSI_STAGE
     DISABLE_PSI_STATEMENT
     DISABLE_PSI_STATEMENT_DIGEST
     DISABLE_PSI_TABLE
     DISABLE_PSI_THREAD
     DISABLE_PSI_TRANSACTION

For example, to compile without mutex instrumentation, configure MySQL
using the '-DDISABLE_PSI_MUTEX=1' option.

To exclude a storage engine from the build, use
'-DWITH_ENGINE_STORAGE_ENGINE=0'.  Examples:

     -DWITH_EXAMPLE_STORAGE_ENGINE=0
     -DWITH_FEDERATED_STORAGE_ENGINE=0
     -DWITH_PARTITION_STORAGE_ENGINE=0

It is also possible to exclude a storage engine from the build using
'-DWITHOUT_ENGINE_STORAGE_ENGINE=1' (but
'-DWITH_ENGINE_STORAGE_ENGINE=0' is preferred).  Examples:

     -DWITHOUT_EXAMPLE_STORAGE_ENGINE=1
     -DWITHOUT_FEDERATED_STORAGE_ENGINE=1
     -DWITHOUT_PARTITION_STORAGE_ENGINE=1

If neither '-DWITH_ENGINE_STORAGE_ENGINE' nor
'-DWITHOUT_ENGINE_STORAGE_ENGINE' are specified for a given storage
engine, the engine is built as a shared module, or excluded if it cannot
be built as a shared module.

*Feature Options*

   *
     '-DCOMPILATION_COMMENT=STRING'

     A descriptive comment about the compilation environment.

   *
     '-DDEFAULT_CHARSET=CHARSET_NAME'

     The server character set.  By default, MySQL uses the 'latin1'
     (cp1252 West European) character set.

     CHARSET_NAME may be one of 'binary', 'armscii8', 'ascii', 'big5',
     'cp1250', 'cp1251', 'cp1256', 'cp1257', 'cp850', 'cp852', 'cp866',
     'cp932', 'dec8', 'eucjpms', 'euckr', 'gb2312', 'gbk', 'geostd8',
     'greek', 'hebrew', 'hp8', 'keybcs2', 'koi8r', 'koi8u', 'latin1',
     'latin2', 'latin5', 'latin7', 'macce', 'macroman', 'sjis', 'swe7',
     'tis620', 'ucs2', 'ujis', 'utf8', 'utf8mb4', 'utf16', 'utf16le',
     'utf32'.  The permissible character sets are listed in the
     'cmake/character_sets.cmake' file as the value of
     'CHARSETS_AVAILABLE'.

     This value can be set at server startup with the
     '--character_set_server' option.

   *
     '-DDEFAULT_COLLATION=COLLATION_NAME'

     The server collation.  By default, MySQL uses 'latin1_swedish_ci'.
     Use the 'SHOW COLLATION' statement to
     determine which collations are available for each character set.

     This value can be set at server startup with the
     '--collation_server' option.

   *
     '-DDISABLE_PSI_COND=BOOL'

     Whether to exclude the Performance Schema condition
     instrumentation.  The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_FILE=BOOL'

     Whether to exclude the Performance Schema file instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_IDLE=BOOL'

     Whether to exclude the Performance Schema idle instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_MEMORY=BOOL'

     Whether to exclude the Performance Schema memory instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_METADATA=BOOL'

     Whether to exclude the Performance Schema metadata instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_MUTEX=BOOL'

     Whether to exclude the Performance Schema mutex instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_RWLOCK=BOOL'

     Whether to exclude the Performance Schema rwlock instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_SOCKET=BOOL'

     Whether to exclude the Performance Schema socket instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_SP=BOOL'

     Whether to exclude the Performance Schema stored program
     instrumentation.  The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_STAGE=BOOL'

     Whether to exclude the Performance Schema stage instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_STATEMENT=BOOL'

     Whether to exclude the Performance Schema statement
     instrumentation.  The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_STATEMENT_DIGEST=BOOL'

     Whether to exclude the Performance Schema statement_digest
     instrumentation.  The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_TABLE=BOOL'

     Whether to exclude the Performance Schema table instrumentation.
     The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_PS=BOOL'

     Exclude the performance schema prepared statements instances
     instrumentation.  The default is 'OFF' (include).

   *
     '-DDISABLE_PSI_THREAD=BOOL'

     Exclude the performance schema thread instrumentation.  The default
     is 'OFF' (include).

     Only disable threads when building without any instrumentation,
     because other instrumentations have a dependency on threads.

   *
     '-DDISABLE_PSI_TRANSACTION=BOOL'

     Exclude the performance schema transaction instrumentation.  The
     default is 'OFF' (include).

   *
     '-DDOWNLOAD_BOOST=BOOL'

     Whether to download the Boost library.  The default is 'OFF'.

     See the 'WITH_BOOST' option for additional discussion about using
     Boost.

   *
     '-DDOWNLOAD_BOOST_TIMEOUT=SECONDS'

     The timeout in seconds for downloading the Boost library.  The
     default is 600 seconds.

     See the 'WITH_BOOST' option for additional discussion about using
     Boost.

   *
     '-DENABLE_DEBUG_SYNC=BOOL'

     *Note*:

     As of MySQL 5.7.18, 'ENABLE_DEBUG_SYNC' is removed and enabling
     'WITH_DEBUG' enables Debug Sync.

     Whether to compile the Debug Sync facility into the server.  This
     facility is used for testing and debugging.  This option is enabled
     by default, but has no effect unless MySQL is configured with
     debugging enabled.  If debugging is enabled and you want to disable
     Debug Sync, use '-DENABLE_DEBUG_SYNC=0'.

     When compiled in, Debug Sync is disabled by default at runtime.  To
     enable it, start 'mysqld' with the
     '--debug-sync-timeout=N' option, where N is a timeout value greater
     than 0.  (The default value is 0, which disables Debug Sync.)  N
     becomes the default timeout for individual synchronization points.

     Sync debug checking for the 'InnoDB' storage engine is available
     when debugging support is compiled in using the 'WITH_DEBUG'
     option.

     For a description of the Debug Sync facility and how to use
     synchronization points, see MySQL Internals: Test Synchronization
     (http://dev.mysql.com/doc/internals/en/test-synchronization.html).

   *
     '-DENABLE_DOWNLOADS=BOOL'

     Whether to download optional files.  For example, with this option
     enabled, 'CMake' downloads the Google Test distribution that is
     used by the test suite to run unit tests.

   *
     '-DENABLE_DTRACE=BOOL'

     Whether to include support for DTrace probes.  For information
     about DTrace, wee dba-dtrace-server

     This option is deprecated because support for DTrace is deprecated
     in MySQL 5.7 and is removed in MySQL 8.0.

   *
     '-DENABLE_GCOV=BOOL'

     Whether to include gcov support (Linux only).

   *
     '-DENABLE_GPROF=BOOL'

     Whether to enable 'gprof' (optimized Linux builds only).

   *
     '-DENABLED_LOCAL_INFILE=BOOL'

     This option controls the compiled-in default 'LOCAL' capability for
     the MySQL client library.  Clients that make no explicit
     arrangements therefore have 'LOCAL' capability disabled or enabled
     according to the 'ENABLED_LOCAL_INFILE' setting specified at MySQL
     build time.

     By default, the client library in MySQL binary distributions is
     compiled with 'ENABLED_LOCAL_INFILE' enabled.  If you compile MySQL
     from source, configure it with 'ENABLED_LOCAL_INFILE' disabled or
     enabled based on whether clients that make no explicit arrangements
     should have 'LOCAL' capability disabled or enabled, respectively.

     'ENABLED_LOCAL_INFILE' controls the default for client-side 'LOCAL'
     capability.  For the server, the 'local_infile' system variable
     controls server-side 'LOCAL' capability.  To explicitly cause the
     server to refuse or permit 'LOAD DATA LOCAL'.
     statements (regardless of how client programs and libraries are
     configured at build time or runtime), start 'mysqld'.
     with 'local_infile' disabled or enabled, respectively.
     'local_infile' can also be set at runtime.  See
     load-data-local.

   *
     '-DENABLED_PROFILING=BOOL'

     Whether to enable query profiling code (for the 'SHOW PROFILE'
     and 'SHOW PROFILES'.
     statements).

   *
     '-DFORCE_UNSUPPORTED_COMPILER=BOOL'

     By default, 'CMake' checks for minimum versions of supported
     compilers: Visual Studio 2013 (Windows); GCC 4.4 or Clang 3.3
     (Linux); Developer Studio 12.5 (Solaris server); Developer Studio
     12.2 or GCC 4.4 (Solaris client library); Clang 3.3 (macOS), Clang
     3.3 (FreeBSD). To disable this check, use
     '-DFORCE_UNSUPPORTED_COMPILER=ON'.

   *
     '-DIGNORE_AIO_CHECK=BOOL'

     If the '-DBUILD_CONFIG=mysql_release' option is given on Linux, the
     'libaio' library must be linked in by default.  If you do not have
     'libaio' or do not want to install it, you can suppress the check
     for it by specifying '-DIGNORE_AIO_CHECK=1'.

   *
     '-DINNODB_PAGE_ATOMIC_REF_COUNT=BOOL'

     This option is obsolete.

   *
     '-DMAX_INDEXES=NUM'

     The maximum number of indexes per table.  The default is 64.  The
     maximum is 255.  Values smaller than 64 are ignored and the default
     of 64 is used.

   *
     '-DMYSQL_MAINTAINER_MODE=BOOL'

     Whether to enable a MySQL maintainer-specific development
     environment.  If enabled, this option causes compiler warnings to
     become errors.

   *
     '-DMUTEX_TYPE=TYPE'

     The mutex type used by 'InnoDB'.  Options include:

        * 'event': Use event mutexes.  This is the default value and the
          original 'InnoDB' mutex implementation.

        * 'sys': Use POSIX mutexes on UNIX systems.  Use
          'CRITICAL_SECTION' onjects on Windows, if available.

        * 'futex': Use Linux futexes instead of condition variables to
          schedule waiting threads.

   *
     '-DMYSQLX_TCP_PORT=PORT_NUM'

     The port number on which X Plugin listens for TCP/IP connections.
     The default is 33060.

     This value can be set at server startup with the '--mysqlx-port'
     option.

   *
     '-DMYSQLX_UNIX_ADDR=FILE_NAME'

     The Unix socket file path on which the server listens for X Plugin
     socket connections.  This must be an absolute path name.  The
     default is '/tmp/mysqlx.sock'.

     This value can be set at server startup with the '--mysqlx-socket'
     option.

   *
     '-DMYSQL_PROJECT_NAME=NAME'

     For Windows or macOS, the project name to incorporate into the
     project file name.

   *
     '-DMYSQL_TCP_PORT=PORT_NUM'

     The port number on which the server listens for TCP/IP connections.
     The default is 3306.

     This value can be set at server startup with the '--port' option.

   *
     '-DMYSQL_UNIX_ADDR=FILE_NAME'

     The Unix socket file path on which the server listens for socket
     connections.  This must be an absolute path name.  The default is
     '/tmp/mysql.sock'.

     This value can be set at server startup with the '--socket' option.

   *
     '-DOPTIMIZER_TRACE=BOOL'

     Whether to support optimizer tracing.  See MySQL Internals: Tracing
     the Optimizer
     (http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

   * '-DREPRODUCIBLE_BUILD=BOOL'

     For builds on Linux systems, this option controls whether to take
     extra care to create a build result independent of build location
     and time.

     This option was added in MySQL 5.7.19.

   *
     '-DWIN_DEBUG_NO_INLINE=BOOL'

     Whether to disable function inlining on Windows.  The default is
     off (inlining enabled).

   *
     '-DWITH_ASAN=BOOL'

     Whether to enable the AddressSanitizer, for compilers that support
     it.  The default is off.

   *
     '-DWITH_ASAN_SCOPE=BOOL'

     Whether to enable the AddressSanitizer
     '-fsanitize-address-use-after-scope' Clang flag for use-after-scope
     detection.  The default is off.  To use this option, '-DWITH_ASAN'
     must also be enabled.

   * '-DWITH_AUTHENTICATION_LDAP=BOOL'

     Whether to report an error if the LDAP authentication plugins
     cannot be built:

        * If this option is disabled (the default), the LDAP plugins are
          built if the required header files and libraries are found.
          If they are not, 'CMake' displays a note about it.

        * If this option is enabled, a failure to find the required
          header file andlibraries causes 'CMake' to produce an error,
          preventing the server from being built.

     For information about LDAP authentication, see
     ldap-pluggable-authentication.  This option was added in MySQL
     5.7.19.

   *
     '-DWITH_AUTHENTICATION_PAM=BOOL'

     Whether to build the PAM authentication plugin, for source trees
     that include this plugin.  (See
     pam-pluggable-authentication.)  If this option is specified and
     the plugin cannot be compiled, the build fails.

   * '-DWITH_AWS_SDK=PATH_NAME'

     The location of the Amazon Web Services software development kit.

     This option was added in MySQL 5.7.19.

   *
     '-DWITH_BOOST=PATH_NAME'

     The Boost library is required to build MySQL. These 'CMake' options
     enable control over the library source location, and whether to
     download it automatically:

        * '-DWITH_BOOST=PATH_NAME' specifies the Boost library directory
          location.  It is also possible to specify the Boost location
          by setting the 'BOOST_ROOT' or 'WITH_BOOST' environment
          variable.

          As of MySQL 5.7.11, '-DWITH_BOOST=system' is permitted and
          indicates that the correct version of Boost is installed on
          the compilation host in the standard location.  In this case,
          the installed version of Boost is used rather than any version
          included with a MySQL source distribution.

        * '-DDOWNLOAD_BOOST=BOOL' specifies whether to download the
          Boost source if it is not present in the specified location.
          The default is 'OFF'.

        * '-DDOWNLOAD_BOOST_TIMEOUT=SECONDS' the timeout in seconds for
          downloading the Boost library.  The default is 600 seconds.

     For example, if you normally build MySQL placing the object output
     in the 'bld' subdirectory of your MySQL source tree, you can build
     with Boost like this:

          mkdir bld
          cd bld
          cmake .. -DDOWNLOAD_BOOST=ON -DWITH_BOOST=$HOME/my_boost

     This causes Boost to be downloaded into the 'my_boost' directory
     under your home directory.  If the required Boost version is
     already there, no download is done.  If the required Boost version
     changes, the newer version is downloaded.

     If Boost is already installed locally and your compiler finds the
     Boost header files on its own, it may not be necessary to specify
     the preceding 'CMake' options.  However, if the version of Boost
     required by MySQL changes and the locally installed version has not
     been upgraded, you may have build problems.  Using the 'CMake'
     options should give you a successful build.

     With the above settings that allow Boost download into a specified
     location, when the required Boost version changes, you need to
     remove the 'bld' folder, recreate it, and perform the 'cmake' step
     again.  Otherwise, the new Boost version might not get downloaded,
     and compilation might fail.

   *
     '-DWITH_CLIENT_PROTOCOL_TRACING=BOOL'

     Whether to build the client-side protocol tracing framework into
     the client library.  By default, this option is enabled.

     For information about writing protocol trace client plugins, see
     writing-protocol-trace-plugins.

     See also the 'WITH_TEST_TRACE_PLUGIN' option.

   * '-DWITH_CURL=CURL_TYPE'

     The location of the 'curl' library.  CURL_TYPE can be 'system' (use
     the system 'curl' library) or a path name to the 'curl' library.

     This option was added in MySQL 5.7.19.

   *
     '-DWITH_DEBUG=BOOL'

     Whether to include debugging support.

     Configuring MySQL with debugging support enables you to use the
     '--debug="d,parser_debug"' option when you start the server.  This
     causes the Bison parser that is used to process SQL statements to
     dump a parser trace to the server's standard error output.
     Typically, this output is written to the error log.

     Sync debug checking for the 'InnoDB' storage engine is defined
     under 'UNIV_DEBUG' and is available when debugging support is
     compiled in using the 'WITH_DEBUG' option.  When debugging support
     is compiled in, the 'innodb_sync_debug' configuration option can be
     used to enable or disable 'InnoDB' sync debug checking.

     As of MySQL 5.7.18, enabling 'WITH_DEBUG' also enables Debug Sync.
     For a description of the Debug Sync facility and how to use
     synchronization points, see MySQL Internals: Test Synchronization
     (http://dev.mysql.com/doc/internals/en/test-synchronization.html).

   *
     '-DWITH_DEFAULT_FEATURE_SET=BOOL'

     Whether to use the flags from
     'cmake/build_configurations/feature_set.cmake'.

   *
     '-DWITH_EDITLINE=VALUE'

     Which 'libedit'/'editline' library to use.  The permitted values
     are 'bundled' (the default) and 'system'.

     'WITH_EDITLINE' replaces 'WITH_LIBEDIT', which has been removed.

   *
     '-DWITH_EMBEDDED_SERVER=BOOL'

     Whether to build the 'libmysqld' embedded server library.

     *Note*:

     The 'libmysqld' embedded server library is deprecated as of MySQL
     5.7.17 and will be removed in MySQL 8.0.

   *
     '-DWITH_EMBEDDED_SHARED_LIBRARY=BOOL'

     Whether to build a shared 'libmysqld' embedded server library.

     *Note*:

     The 'libmysqld' embedded server library is deprecated as of MySQL
     5.7.17 and will be removed in MySQL 8.0.

   *
     '-DWITH_EXTRA_CHARSETS=NAME'

     Which extra character sets to include:

        * 'all': All character sets.  This is the default.

        * 'complex': Complex character sets.

        * 'none': No extra character sets.

   *
     '-DWITH_INNODB_EXTRA_DEBUG=BOOL'

     Whether to include extra InnoDB debugging support.

     Enabling 'WITH_INNODB_EXTRA_DEBUG' turns on extra InnoDB debug
     checks.  This option can only be enabled when 'WITH_DEBUG' is
     enabled.

   *
     '-DWITH_INNODB_MEMCACHED=BOOL'

     Whether to generate memcached shared libraries ('libmemcached.so'
     and 'innodb_engine.so').

   *
     '-DWITH_KEYRING_TEST=BOOL'

     Whether to build the test program that accompanies the
     'keyring_file' plugin.  The default is 'OFF'.  Test file source
     code is located in the 'plugin/keyring/keyring-test' directory.

     This option was added in MySQL 5.7.11.

   *
     '-DWITH_LIBEVENT=STRING'

     Which 'libevent' library to use.  Permitted values are 'bundled'
     (default), 'system', and 'yes'.  If you specify 'system' or 'yes',
     the system 'libevent' library is used if present.  If the system
     library is not found, the bundled 'libevent' library is used.  The
     'libevent' library is required by 'InnoDB' memcached.

   *
     '-DWITH_LIBWRAP=BOOL'

     Whether to include 'libwrap' (TCP wrappers) support.

   *
     '-DWITH_LZ4=LZ4_TYPE'

     The 'WITH_LZ4' indicates the source of 'zlib' support:

        * 'bundled': Use the 'LZ4' library bundled with the
          distribution.  This is the default.

        * 'system': Use the system 'LZ4' library.  If 'WITH_LZ4' is set
          to this value, the 'lz4_decompress'.
          utility is not built.  In this case, the system 'lz4' command
          can be used instead.

   *
     '-DWITH_MSAN=BOOL'

     Whether to enable MemorySanitizer, for compilers that support it.
     The default is off.

     For this option to have an effect if enabled, all libraries linked
     to MySQL must also have been compiled with the option enabled.

   *
     '-DWITH_MECAB={disabled|system|PATH_NAME}'

     Use this option to compile the MeCab parser.  If you have installed
     MeCab to its default installation directory, set
     '-DWITH_MECAB=system'.  The 'system' option applies to MeCab
     installations performed from source or from binaries using a native
     package management utility.  If you installed MeCab to a custom
     installation directory, specify the path to the MeCab installation.
     For example, '-DWITH_MECAB=/opt/mecab'.  If the 'system' option
     does not work, specifying the MeCab installation path should work
     in all cases.

     For related information, see fulltext-search-mecab.

   *
     '-DWITH_MSCRT_DEBUG=BOOL'

     Whether to enable Visual Studio CRT memory leak tracing.  The
     default is 'OFF'.

   *
     '-DWITH_NUMA=BOOL'

     Explicitly set the NUMA memory allocation policy.  'CMake' sets the
     default 'WITH_NUMA' value based on whether the current platform has
     'NUMA' support.  For platforms without NUMA support, 'CMake'
     behaves as follows:

        * With no NUMA option (the normal case), 'CMake' continues
          normally, producing only this warning: NUMA library missing or
          required version not available

        * With '-DWITH_NUMA=ON', 'CMake' aborts with this error: NUMA
          library missing or required version not available

     This option was added in MySQL 5.7.17.

   *
     '-DWITH_PROTOBUF=PROTOBUF_TYPE'

     Which Protocol Buffers package to use.  PROTOBUF_TYPE can be one of
     the following values:

        * 'bundled': Use the package bundled with the distribution.
          This is the default.

        * 'system': Use the package installed on the system.

     Other values are ignored, with a fallback to 'bundled'.

     This option was added in MySQL 5.7.12.

   *
     '-DWITH_RAPID=BOOL'

     Whether to build the rapid development cycle plugins.  When
     enabled, a 'rapid' directory is created in the build tree
     containing these plugins.  When disabled, no 'rapid' directory is
     created in the build tree.  The default is 'ON', unless the 'rapid'
     directory is removed from the source tree, in which case the
     default becomes 'OFF'.  This option was added in MySQL 5.7.12.

   *
     '-DWITH_SSL={SSL_TYPE'|PATH_NAME}

     The type of SSL support to include or the path name to the OpenSSL
     installation to use.

        * SSL_TYPE can be one of the following values:

             * 'yes': Use the system SSL library if present, else the
               library bundled with the distribution.

             * 'bundled': Use the SSL library bundled with the
               distribution.  This is the default.

             * 'system': Use the system SSL library.

        * PATH_NAME is the path name to the OpenSSL installation to use.
          This can be preferable to using the SSL_TYPE value of 'system'
          because it can prevent CMake from detecting and using an older
          or incorrect OpenSSL version installed on the system.
          (Another permitted way to do the same thing is to set
          'WITH_SSL' to 'system' and set the 'CMAKE_PREFIX_PATH' option
          to PATH_NAME.)

     For information about using SSL support, see
     encrypted-connections.

   *
     '-DWITH_SYSTEMD=BOOL'

     Whether to enable installation of systemd support files.  By
     default, this option is disabled.  When enabled, systemd support
     files are installed, and scripts such as 'mysqld_safe'
     and the System V initialization script are not
     installed.  On platforms where systemd is not available, enabling
     'WITH_SYSTEMD' results in an error from 'CMake'.

     For more information about using systemd, see
     using-systemd.  That section also includes information about
     specifying options previously specified in '[mysqld_safe]' option
     groups.  Because 'mysqld_safe' is not installed
     when systemd is used, such options must be specified another way.

   *
     '-DWITH_TEST_TRACE_PLUGIN=BOOL'

     Whether to build the test protocol trace client plugin (see
     test-protocol-trace-plugin).  By default, this option is
     disabled.  Enabling this option has no effect unless the
     'WITH_CLIENT_PROTOCOL_TRACING' option is enabled.  If MySQL is
     configured with both options enabled, the 'libmysqlclient' client
     library is built with the test protocol trace plugin built in, and
     all the standard MySQL clients load the plugin.  However, even when
     the test plugin is enabled, it has no effect by default.  Control
     over the plugin is afforded using environment variables; see
     test-protocol-trace-plugin.

     *Note*:

     Do _not_ enable the 'WITH_TEST_TRACE_PLUGIN' option if you want to
     use your own protocol trace plugins because only one such plugin
     can be loaded at a time and an error occurs for attempts to load a
     second one.  If you have already built MySQL with the test protocol
     trace plugin enabled to see how it works, you must rebuild MySQL
     without it before you can use your own plugins.

     For information about writing trace plugins, see
     writing-protocol-trace-plugins.

   *
     '-DWITH_UBSAN=BOOL'

     Whether to enable the Undefined Behavior Sanitizer, for compilers
     that support it.  The default is off.

   *
     '-DWITH_UNIT_TESTS={ON|OFF}'

     If enabled, compile MySQL with unit tests.  The default is ON
     unless the server is not being compiled.

   *
     '-DWITH_UNIXODBC=1'

     Enables unixODBC support, for Connector/ODBC.

   *
     '-DWITH_VALGRIND=BOOL'

     Whether to compile in the Valgrind header files, which exposes the
     Valgrind API to MySQL code.  The default is 'OFF'.

     To generate a Valgrind-aware debug build, '-DWITH_VALGRIND=1'
     normally is combined with '-DWITH_DEBUG=1'.  See Building Debug
     Configurations
     (http://dev.mysql.com/doc/internals/en/debug-configurations.html).

   *
     '-DWITH_ZLIB=ZLIB_TYPE'

     Some features require that the server be built with compression
     library support, such as the 'COMPRESS()' and 'UNCOMPRESS()'
     functions, and compression of the client/server protocol.  The
     'WITH_ZLIB' indicates the source of 'zlib' support:

        * 'bundled': Use the 'zlib' library bundled with the
          distribution.  This is the default.

        * 'system': Use the system 'zlib' library.

   *
     '-DWITHOUT_SERVER=BOOL'

     Whether to build without the MySQL server.  The default is 'OFF',
     which does build the server.

*Compiler Flags*

   *
     '-DCMAKE_C_FLAGS="FLAGS'"

     Flags for the C Compiler.

   *
     '-DCMAKE_CXX_FLAGS="FLAGS'"

     Flags for the C++ Compiler.

   *
     '-DWITH_DEFAULT_COMPILER_OPTIONS=BOOL'

     Whether to use the flags from
     'cmake/build_configurations/compiler_options.cmake'.

     *Note*:

     All optimization flags were carefully chosen and tested by the
     MySQL build team.  Overriding them can lead to unexpected results
     and is done at your own risk.

   *
     '-DSUNPRO_CXX_LIBRARY="LIB_NAME'"

     Enable linking against 'libCstd' instead of 'stlport4' on Solaris
     10 or later.  This works only for client code because the server
     depends on C++98.  Example usage:

          cmake -DWITHOUT_SERVER=1 -DSUNPRO_CXX_LIBRARY=Cstd

To specify your own C and C++ compiler flags, for flags that do not
affect optimization, use the 'CMAKE_C_FLAGS' and 'CMAKE_CXX_FLAGS' CMake
options.

When providing your own compiler flags, you might want to specify
'CMAKE_BUILD_TYPE' as well.

For example, to create a 32-bit release build on a 64-bit Linux machine,
do this:

     shell> mkdir bld
     shell> cd bld
     shell> cmake .. -DCMAKE_C_FLAGS=-m32 \
              -DCMAKE_CXX_FLAGS=-m32 \
              -DCMAKE_BUILD_TYPE=RelWithDebInfo

If you set flags that affect optimization ('-ONUMBER'), you must set the
'CMAKE_C_FLAGS_BUILD_TYPE' and/or 'CMAKE_CXX_FLAGS_BUILD_TYPE' options,
where BUILD_TYPE corresponds to the 'CMAKE_BUILD_TYPE' value.  To
specify a different optimization for the default build type
('RelWithDebInfo') set the 'CMAKE_C_FLAGS_RELWITHDEBINFO' and
'CMAKE_CXX_FLAGS_RELWITHDEBINFO' options.  For example, to compile on
Linux with '-O3' and with debug symbols, do this:

     shell> cmake .. -DCMAKE_C_FLAGS_RELWITHDEBINFO="-O3 -g" \
              -DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O3 -g"

*CMake Options for Compiling NDB Cluster*

The following options are for use when building NDB Cluster with the NDB
Cluster sources; they are not currently supported when using sources
from the MySQL 5.6 Server tree.

   *
     '-DMEMCACHED_HOME=DIR_NAME'

     Perform the build using the memcached (version 1.6 or later)
     installed in the system directory indicated by DIR_NAME.  Files
     from this installation that are used in the build include the
     memcached binary, header files, and libraries, as well as the
     'memcached_utilities' library and the header file
     'engine_testapp.h'.

     You must leave this option unset when building 'ndbmemcache' using
     the bundled memcached sources ('WITH_BUNDLED_MEMCACHED' option); in
     other words, the bundled sources are used by default).

     While additional 'CMake' options--such as for SASL authorization
     and for providing 'dtrace' support--are available for use when
     compiling 'memcached' from external sources, these options are
     currently not enabled for the 'memcached' sources bundled with NDB
     Cluster.

   *
     '-DWITH_BUNDLED_LIBEVENT={ON|OFF}'

     Use the 'libevent' included in the NDB Cluster sources when
     building NDB Cluster with 'ndbmemcached' support.  Enabled by
     default.  'OFF' causes the system's 'libevent' to be used instead.

   *
     '-DWITH_BUNDLED_MEMCACHED={ON|OFF}'

     Build the memcached sources included in the NDB Cluster source
     tree, then use the resulting memcached server when building the
     'ndbmemcache' engine.  In this case, 'make install' places the
     'memcached' binary in the installation 'bin' directory, and the
     'ndbmemcache' engine shared library file 'ndb_engine.so' in the
     installation 'lib' directory.

     This option is ON by default.

   *
     '-DWITH_CLASSPATH=PATH'

     Sets the classpath for building NDB Cluster Connector for Java.
     The default is empty.  This option is ignored if
     '-DWITH_NDB_JAVA=OFF' is used.

   *
     '-DWITH_ERROR_INSERT={ON|OFF}'

     Enables error injection in the 'NDB' kernel.
     For testing only; not intended for use in building production
     binaries.  The default is 'OFF'.

   *
     '-DWITH_NDBCLUSTER_STORAGE_ENGINE={ON|OFF}'

     Build and link in support for the 'NDB'.
     (see 'NDBCLUSTER') storage engine in
     'mysqld'.  The default is 'ON'.

   *
     '-DWITH_NDBCLUSTER={ON|OFF}'

     This is an alias for 'WITH_NDBCLUSTER_STORAGE_ENGINE'.

   *
     '-DWITH_NDBMTD={ON|OFF}'

     Build the multi-threaded data node executable 'ndbmtd'.
     The default is 'ON'.

   *
     '-DWITH_NDB_BINLOG={ON|OFF}'

     Enable binary logging by default in the 'mysqld'.
     built using this option.  ON by default.

   *
     '-DWITH_NDB_DEBUG={ON|OFF}'

     Enable building the debug versions of the NDB Cluster binaries.
     OFF by default.

   *
     '-DWITH_NDB_JAVA={ON|OFF}'

     Enable building NDB Cluster with Java support, including
     'ClusterJ'.

     This option is ON by default.  If you do not wish to compile NDB
     Cluster with Java support, you must disable it explicitly by
     specifying '-DWITH_NDB_JAVA=OFF' when running 'CMake'.  Otherwise,
     if Java cannot be found, configuration of the build fails.

   *
     '-DWITH_NDB_PORT=PORT'

     Causes the NDB Cluster management server (see 'ndb_mgmd')
     that is built to use this PORT by
     default.  If this option is unset, the resulting management server
     tries to use port 1186 by default.

   *
     '-DWITH_NDB_TEST={ON|OFF}'

     If enabled, include a set of NDB API test programs.  The default is
     OFF.

2.9.5 Dealing with Problems Compiling MySQL
-------------------------------------------

The solution to many problems involves reconfiguring.  If you do
reconfigure, take note of the following:

   * If 'CMake' is run after it has previously been run, it may use
     information that was gathered during its previous invocation.  This
     information is stored in 'CMakeCache.txt'.  When 'CMake' starts up,
     it looks for that file and reads its contents if it exists, on the
     assumption that the information is still correct.  That assumption
     is invalid when you reconfigure.

   * Each time you run 'CMake', you must run 'make' again to recompile.
     However, you may want to remove old object files from previous
     builds first because they were compiled using different
     configuration options.

To prevent old object files or configuration information from being
used, run the following commands before re-running 'CMake':

On Unix:

     shell> make clean
     shell> rm CMakeCache.txt

On Windows:

     shell> devenv MySQL.sln /clean
     shell> del CMakeCache.txt

If you build outside of the source tree, remove and recreate your build
directory before re-running 'CMake'.  For instructions on building
outside of the source tree, see How to Build MySQL Server with CMake
(http://dev.mysql.com/doc/internals/en/cmake.html).

On some systems, warnings may occur due to differences in system include
files.  The following list describes other problems that have been found
to occur most often when compiling MySQL:

   *
     To define which C and C++ compilers to use, you can define the 'CC'
     and 'CXX' environment variables.  For example:

          shell> CC=gcc
          shell> CXX=g++
          shell> export CC CXX

     To specify your own C and C++ compiler flags, use the
     'CMAKE_C_FLAGS' and 'CMAKE_CXX_FLAGS' CMake options.  See
     cmake-compiler-flags.

     To see what flags you might need to specify, invoke
     'mysql_config' with the '--cflags' and '--cxxflags'
     options.

   * To see what commands are executed during the compile stage, after
     using 'CMake' to configure MySQL, run 'make VERBOSE=1' rather than
     just 'make'.

   * If compilation fails, check whether the 'MYSQL_MAINTAINER_MODE'
     option is enabled.  This mode causes compiler warnings to become
     errors, so disabling it may enable compilation to proceed.

   * If your compile fails with errors such as any of the following, you
     must upgrade your version of 'make' to GNU 'make':

          make: Fatal error in reader: Makefile, line 18:
          Badly formed macro assignment

     Or:

          make: file `Makefile' line 18: Must be a separator (:

     Or:

          pthread.h: No such file or directory

     Solaris and FreeBSD are known to have troublesome 'make' programs.

     GNU 'make' 3.75 is known to work.

   * The 'sql_yacc.cc' file is generated from 'sql_yacc.yy'.  Normally,
     the build process does not need to create 'sql_yacc.cc' because
     MySQL comes with a pregenerated copy.  However, if you do need to
     re-create it, you might encounter this error:

          "sql_yacc.yy", line XXX fatal: default action causes potential...

     This is a sign that your version of 'yacc' is deficient.  You
     probably need to install a recent version of 'bison' (the GNU
     version of 'yacc') and use that instead.

     Versions of 'bison' older than 1.75 may report this error:

          sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded

     The maximum table size is not actually exceeded; the error is
     caused by bugs in older versions of 'bison'.

For information about acquiring or updating tools, see the system
requirements in source-installation.

2.9.6 MySQL Configuration and Third-Party Tools
-----------------------------------------------

Third-party tools that need to determine the MySQL version from the
MySQL source can read the 'VERSION' file in the top-level source
directory.  The file lists the pieces of the version separately.  For
example, if the version is MySQL 5.7.4-m14, the file looks like this:

     MYSQL_VERSION_MAJOR=5
     MYSQL_VERSION_MINOR=7
     MYSQL_VERSION_PATCH=4
     MYSQL_VERSION_EXTRA=-m14

If the source is not for a General Availablility (GA) release, the
'MYSQL_VERSION_EXTRA' value will be nonempty.  For the example, the
value corresponds to Milestone 14.

To construct a five-digit number from the version components, use this
formula:

     MYSQL_VERSION_MAJOR*10000 + MYSQL_VERSION_MINOR*100 + MYSQL_VERSION_PATCH

2.10 Postinstallation Setup and Testing
=======================================

This section discusses tasks that you should perform after installing
MySQL:

   * If necessary, initialize the data directory and create the MySQL
     grant tables.  For some MySQL installation methods, data directory
     initialization may be done for you automatically:

        * Windows installation operations performed by MySQL Installer.

        * Installation on Linux using a server RPM or Debian
          distribution from Oracle.

        * Installation using the native packaging system on many
          platforms, including Debian Linux, Ubuntu Linux, Gentoo Linux,
          and others.

        * Installation on OS X using a DMG distribution.

     For other platforms and installation types, including installation
     from generic binary and source distributions, you must initialize
     the data directory yourself.  For instructions, see
     data-directory-initialization.

   * Start the server and make sure that it can be accessed.  For
     instructions, see starting-server, and
     testing-server.

   * Assign passwords to the initial 'root' account in the grant tables,
     if that was not already done during data directory initialization.
     Passwords prevent unauthorized access to the MySQL server.  For
     instructions, see default-privileges.

   * Optionally, arrange for the server to start and stop automatically
     when your system starts and stops.  For instructions, see
     automatic-start.

   * Optionally, populate time zone tables to enable recognition of
     named time zones.  For instructions, see time-zone-support.

When you are ready to create additional user accounts, you can find
information on the MySQL access control system and account management in
privilege-system, and user-account-management.

2.10.1 Initializing the Data Directory
--------------------------------------

After installing MySQL, the data directory, including the tables in the
'mysql' system database, must be initialized.  For some MySQL
installation methods, data directory initialization can be done
automatically, as described in postinstallation.  For other
installation methods, including installation from generic binary and
source distributions, you must initialize the data directory yourself.

This section describes how to initialize the data directory on Unix and
Unix-like systems.  (For Windows, see windows-postinstallation.)
For some suggested commands that you can use to test whether the server
is accessible and working properly, see testing-server.

In the examples shown here, the server is going to run under the user ID
of the 'mysql' login account.  This assumes that such an account exists.
Either create the account if it does not exist, or substitute the name
of a different existing login account that you plan to use for running
the server.  For information about creating the account, see Creating a
'mysql' System User and Group, in binary-installation.

  1. Change location into the top-level directory of your MySQL
     installation directory, which is typically '/usr/local/mysql':

          shell> cd /usr/local/mysql

     You will find several files and subdirectories inside the folder,
     including the 'bin' subdirectory, which contains the server as well
     as the client and utility programs.

  2. Create a directory whose location can be provided to the
     'secure_file_priv' system variable, which limits import/export
     operations to that specific directory:

          shell> mkdir mysql-files

     Grant ownership of the directory to the 'mysql' user and group
     ownership to the 'mysql' group, and set the right permissions for
     the directory:

          shell> chown mysql:mysql mysql-files
          shell> chmod 750 mysql-files

  3. Initialize the data directory, including the 'mysql' database
     containing the initial MySQL grant tables that determine how users
     are permitted to connect to the server.

     Typically, data directory initialization need be done only after
     you first installed MySQL. If you are upgrading an existing
     installation, you should run 'mysql_upgrade'.
     instead (see mysql-upgrade).  However, the command that
     initializes the data directory does not overwrite any existing
     privilege tables, so it should be safe to run in any circumstances.
     Use the server to initialize the data directory; for example:

          shell> bin/mysqld --initialize --user=mysql

     See data-directory-initialization-mysqld for some important
     information on the command, especially on the command options you
     might use.

     *Note*:

     Initialization of the data directory might fail because some
     required software libraries are missing from your system.  For
     example:

          shell> bin/mysqld --initialize --user=mysql
          bin/mysqld: error while loading shared libraries: libnuma.so.1: cannot
          open shared object file: No such file or directory

     When this happens, you have to install the missing libraries
     manually or with your system's package manager before retrying the
     data directory initialization.

  4. If you want the server to be able to deploy with automatic support
     for secure connections, use the 'mysql_ssl_rsa_setup'
     utility to create default SSL and RSA files:

          shell> bin/mysql_ssl_rsa_setup

     For more information, see mysql-ssl-rsa-setup.

  5. If the plugin directory (the directory named by the 'plugin_dir'
     system variable) is writable by the server, it may be possible for
     a user to write executable code to a file in the directory using
     'SELECT ... INTO DUMPFILE'.  This can be
     prevented by making the plugin directory read only to the server or
     by setting the 'secure_file_priv' system variable at server startup
     to a directory where 'SELECT' writes can be
     performed safely.  (For example, set it to the 'mysql-files'
     directory created earlier.)

  6. To specify options that the MySQL server should use at startup, put
     them in a '/etc/my.cnf' or '/etc/mysql/my.cnf' file.  You can use
     such a file to set, for example, the 'secure_file_priv' system
     variable.  See server-configuration-defaults.  If you do
     not do this, the server starts with its default settings.

  7. If you want MySQL to start automatically when you boot your
     machine, see automatic-start.

Data directory initialization creates time zone tables in the 'mysql'
database but does not populate them.  To do so, use the instructions in
time-zone-support.

2.10.1.1 Initializing the Data Directory Manually Using mysqld
..............................................................

This section describes how to initialize the data directory using
'mysqld', the MySQL server.

The following instructions assume that your current location is the
MySQL installation directory, represented here by BASEDIR:

     shell> cd BASEDIR

To initialize the data directory, invoke 'mysqld' with
the '--initialize' or '--initialize-insecure' option, depending on
whether you want the server to generate a random initial password for
the ''root'@'localhost'' account.

On Windows, use one of these commands:

     C:\> bin\mysqld --initialize
     C:\> bin\mysqld --initialize-insecure

On Unix and Unix-like systems, it is important to make sure that the
database directories and files are owned by the 'mysql' login account so
that the server has read and write access to them when you run it later.
To ensure this, start 'mysqld' from the system 'root'
account and include the '--user' option as shown here:

     shell> bin/mysqld --initialize --user=mysql
     shell> bin/mysqld --initialize-insecure --user=mysql

Otherwise, execute the program while logged in as 'mysql', in which case
you can omit the '--user' option from the command.

Regardless of platform, use '--initialize' for 'secure by default'
installation (that is, including generation of a random initial 'root'
password).  In this case, the password is marked as expired and you will
need to choose a new one.  With the '--initialize-insecure' option, no
'root' password is generated; it is assumed that you will assign a
password to the account in timely fashion before putting the server into
production use.

It might be necessary to specify other options such as '--basedir' or
'--datadir' if 'mysqld' cannot identify the correct
locations for the installation directory or data directory.  For example
(enter the command on one line):

     shell> bin/mysqld --initialize --user=mysql
              --basedir=/opt/mysql/mysql
              --datadir=/opt/mysql/mysql/data

Alternatively, put the relevant option settings in an option file and
pass the name of that file to 'mysqld'.  For Unix and
Unix-like systems, suppose that the option file name is
'/opt/mysql/mysql/etc/my.cnf'.  Put these lines in the file:

     [mysqld]
     basedir=/opt/mysql/mysql
     datadir=/opt/mysql/mysql/data

Then invoke 'mysqld' as follows (enter the command on a
single line with the '--defaults-file' option first):

     shell> bin/mysqld --defaults-file=/opt/mysql/mysql/etc/my.cnf
              --initialize --user=mysql

On Windows, suppose that 'C:\my.ini' contains these lines:

     [mysqld]
     basedir=C:\\Program Files\\MySQL\\MySQL Server 5.7
     datadir=D:\\MySQLdata

Then invoke 'mysqld' as follows (the '--defaults-file'
option must be first):

     C:\> bin/mysqld --defaults-file=C:\my.ini --initialize

When invoked with the '--initialize' or '--initialize-insecure' option,
see 'mysqld' performs the following initialization sequence.

*Note*:

The server writes any messages to its standard error output.  This may
be redirected to the error log, so look there if you do not see the
messages on your screen.  For information about the error log, including
where it is located, see error-log.

On Windows, use the '--console' option to direct messages to the
console.

  1. The server checks for the existence of the data directory as
     follows:

        * If no data directory exists, the server creates it.

        * If a data directory exists but is not empty (that is, it
          contains files or subdirectories), the server exits after
          producing an error message:

               [ERROR] --initialize specified but the data directory exists. Aborting.

          In this case, remove or rename the data directory and try
          again.

          As of MySQL 5.7.11, an existing data directory is permitted to
          be nonempty if every entry either has a name that begins with
          a period ('.') or is named using an '--ignore-db-dir' option.

          *Note*:

          Avoid the use of the '--ignore-db-dir' option, which has been
          deprecated since MySQL 5.7.16.

  2. Within the data directory, the server creates the 'mysql' system
     database and its tables, including the grant tables, server-side
     help tables, and time zone tables.  For a complete listing and
     description of the grant tables, see privilege-system.

  3. The server initializes the system tablespace and related data
     structures needed to manage 'InnoDB'.
     tables.

     *Note*:

     After 'mysqld' sets up the 'InnoDB' system
     tablespace, changes to some tablespace characteristics require
     setting up a whole new instance.  This includes the file name of
     the first file in the system tablespace and the number of undo
     logs.  If you do not want to use the default values, make sure that
     the settings for the 'innodb_data_file_path' and
     'innodb_log_file_size' configuration parameters are in place in the
     MySQL configuration file before running 'mysqld'.
     Also make sure to specify as necessary other parameters that affect
     the creation and location of 'InnoDB' files, such as
     'innodb_data_home_dir' and 'innodb_log_group_home_dir'.

     If those options are in your configuration file but that file is
     not in a location that MySQL reads by default, specify the file
     location using the '--defaults-extra-file' option when you run
     'mysqld'.

  4. The server creates a ''root'@'localhost'' superuser account and
     other reserved accounts (see reserved-users).  Some
     reserved accounts are locked and cannot be used by clients, but
     ''root'@'localhost'' is intended for administrative use and you
     should assign it a password.

     The server's action with respect to a password for the
     ''root'@'localhost'' account depends on how you invoke it:

        * With '--initialize' but not '--initialize-insecure', the
          server generates a random password, marks it as expired, and
          writes a message displaying the password:

               [Warning] A temporary password is generated for root@localhost:
               iTag*AfrH5ej

        * With '--initialize-insecure', (either with or without
          '--initialize' because '--initialize-insecure' implies
          '--initialize'), the server does not generate a password or
          mark it expired, and writes a warning message:

               Warning] root@localhost is created with an empty password ! Please
               consider switching off the --initialize-insecure option.

     See later in this section for instructions on assigning a new
     ''root'@'localhost'' password.

  5. The server populates the server-side help tables if content is
     available (in the 'fill_help_tables.sql' file).  The server does
     not populate the time zone tables; to do so, see
     time-zone-support.

  6. If the '--init-file' option was given to name a file of SQL
     statements, the server executes the statements in the file.  This
     option enables you to perform custom bootstrapping sequences.

     When the server operates in bootstrap mode, some functionality is
     unavailable that limits the statements permitted in the file.
     These include statements that relate to account management (such as
     'CREATE USER' or 'GRANT'),
     replication, and global transaction identifiers.

  7. The server exits.

After you initialize the data directory by starting the server with
'--initialize' or '--initialize-insecure', start the server normally
(that is, without either of those options) and assign the
''root'@'localhost'' account a new password:

  1. Start the server.  For instructions, see starting-server.

  2. Connect to the server:

        * If you used '--initialize' but not '--initialize-insecure' to
          initialize the data directory, connect to the server as 'root'
          using the random password that the server generated during the
          initialization sequence:

               shell> mysql -u root -p
               Enter password: (ENTER THE RANDOM ROOT PASSWORD HERE)

          Look in the server error log if you do not know this password.

        * If you used '--initialize-insecure' to initialize the data
          directory, connect to the server as 'root' without a password:

               shell> mysql -u root --skip-password

  3. After connecting, assign a new 'root' password:

          mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'NEW_PASSWORD';

*Note*:

The data directory initialization sequence performed by the server does
not substitute for the actions performed by
'mysql_secure_installation' or
'mysql_ssl_rsa_setup'.  See
mysql-secure-installation, and mysql-ssl-rsa-setup.

2.10.1.2 Initializing the Data Directory Manually Using mysql_install_db
........................................................................

This section describes how to initialize the data directory using
'mysql_install_db'.

*Note*:

The procedure described here is used on Unix and Unix-like systems prior
to MySQL 5.7.6.  (For Windows, MySQL distributions include a data
directory with prebuilt tables in the 'mysql' database.)  As of MySQL
5.7.6, see 'mysql_install_db' is deprecated.  To
initialize the data directory, use the procedure described at
data-directory-initialization-mysqld.

The following instructions assume that your current location is the
MySQL installation directory, represented here by BASEDIR:

     shell> cd BASEDIR

To initialize the data directory, invoke 'mysql_install_db'.
This program is located under the base directory in
either 'bin' or 'scripts', depending on your version of MySQL. If it is
in 'scripts', adjust the following commands appropriately.

     shell> bin/mysql_install_db --user=mysql

It is important to make sure that the database directories and files are
owned by the 'mysql' login account so that the server has read and write
access to them when you run it later.  To ensure this, run
'mysql_install_db' as 'root' and include the '--user'
option as shown.  Otherwise, execute the program while logged in as
'mysql', in which case you can omit the '--user' option from the
command.

The 'mysql_install_db' command creates the
server's data directory.  Under the data directory, it creates
directories for the 'mysql' database that holds the grant tables and
(prior to MySQL 5.7.4) a 'test' database that you can use to test MySQL.
The program also creates privilege table entries for the initial account
or accounts.  For a complete listing and description of the grant
tables, see privilege-system.

It might be necessary to specify other options such as '--basedir' or
'--datadir' if 'mysql_install_db' does not
identify the correct locations for the installation directory or data
directory.  For example:

     shell> bin/mysql_install_db --user=mysql \
              --basedir=/opt/mysql/mysql \
              --datadir=/opt/mysql/mysql/data

If 'mysql_install_db' generates a random
password for the 'root' account, start the server and assign a new
password:

  1. Start the server (use the first command if your installation
     includes 'mysqld_safe', the second it if
     includes systemd support):

          shell> bin/mysqld_safe --user=mysql &
          shell> systemctl start mysqld

     Substitute the appropriate service name if it differs from
     'mysqld'; for example, 'mysql' on SLES systems.

  2. Look in the '$HOME/.mysql_secret' file to find the random password
     that 'mysql_install_db' wrote there.  Then
     connect to the server as 'root' using that password:

          shell> mysql -u root -h 127.0.0.1 -p
          Enter password: (ENTER THE RANDOM PASSWORD HERE)

  3. After connecting, assign a new 'root' password:

          mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('NEW_PASSWORD');

     After resetting the password, remove the '.mysql_secret' file;
     otherwise, if you run 'mysql_secure_installation',
     that command may see the file and expire
     the 'root' password again as part of ensuring secure deployment.

If 'mysql_install_db' did not generate a random
password, you should still assign one.  For instructions, see
default-privileges.  That section also describes how to remove the
'test' database, if 'mysql_install_db' created
one and you do not want it.

If you have trouble with 'mysql_install_db' at
this point, see mysql-install-db-problems.

2.10.1.3 Problems Running mysql_install_db
..........................................

The purpose of the 'mysql_install_db' program
is to initialize the data directory, including the tables in the 'mysql'
system database.  It does not overwrite existing MySQL privilege tables,
and it does not affect any other data.

To re-create your privilege tables, first stop the 'mysqld'
server if it is running.  Then rename the 'mysql' directory
under the data directory to save it, and run 'mysql_install_db'.
Suppose that your current directory is the MySQL
installation directory and that 'mysql_install_db'
is located in the 'bin' directory and the data
directory is named 'data'.  To rename the 'mysql' database and re-run
'mysql_install_db', use these commands.

     shell> mv data/mysql data/mysql.old
     shell> bin/mysql_install_db --user=mysql

When you run 'mysql_install_db', you might
encounter the following problems:

   * *'mysql_install_db' fails to install the
     grant tables*

     You may find that 'mysql_install_db' fails
     to install the grant tables and terminates after displaying the
     following messages:

          Starting mysqld daemon with databases from XXXXXX
          mysqld ended

     In this case, you should examine the error log file very carefully.
     The log should be located in the directory 'XXXXXX' named by the
     error message and should indicate why 'mysqld' did
     not start.  If you do not understand what happened, include the log
     when you post a bug report.  See bug-reports.

   * *There is a 'mysqld' process running*

     This indicates that the server is running, in which case the grant
     tables have probably been created already.  If so, there is no need
     to run 'mysql_install_db' at all because
     it needs to be run only once, when you first install MySQL.

   * *Installing a second 'mysqld' server does not work
     when one server is running*

     This can happen when you have an existing MySQL installation, but
     want to put a new installation in a different location.  For
     example, you might have a production installation, but you want to
     create a second installation for testing purposes.  Generally the
     problem that occurs when you try to run a second server is that it
     tries to use a network interface that is in use by the first
     server.  In this case, you should see one of the following error
     messages:

          Can't start server: Bind on TCP/IP port:
          Address already in use
          Can't start server: Bind on unix socket...

     For instructions on setting up multiple servers, see
     multiple-servers.

   *
     *You do not have write access to the '/tmp' directory*

     If you do not have write access to create temporary files or a Unix
     socket file in the default location (the '/tmp' directory) or the
     'TMPDIR' environment variable, if it has been set, an error occurs
     when you run 'mysql_install_db' or the
     'mysqld' server.

     You can specify different locations for the temporary directory and
     Unix socket file by executing these commands prior to starting
     'mysql_install_db' or 'mysqld',
     where SOME_TMP_DIR is the full path name to some directory
     for which you have write permission:

          shell> TMPDIR=/SOME_TMP_DIR/
          shell> MYSQL_UNIX_PORT=/SOME_TMP_DIR/mysql.sock
          shell> export TMPDIR MYSQL_UNIX_PORT

     Then you should be able to run 'mysql_install_db'
     and start the server with these commands:

          shell> bin/mysql_install_db --user=mysql
          shell> bin/mysqld_safe --user=mysql &

     See problems-with-mysql-sock, and
     environment-variables.

There are some alternatives to running the 'mysql_install_db'
program provided in the MySQL distribution:

   * If you want the initial privileges to be different from the
     standard defaults, use account-management statements such as
     'CREATE USER', 'GRANT', and
     'REVOKE' to change the privileges _after_ the grant tables
     have been set up.  In other words, run 'mysql_install_db',
     and then use 'mysql -u root mysql' to connect to
     the server as the MySQL 'root' user so that you can issue the
     necessary statements.  (See account-management-sql.)

     To install MySQL on several machines with the same privileges, put
     the 'CREATE USER', 'GRANT', and
     'REVOKE' statements in a file and execute the file
     as a script using 'mysql' after running 'mysql_install_db'.
     For example:

          shell> bin/mysql_install_db --user=mysql
          shell> bin/mysql -u root < your_script_file

     This enables you to avoid issuing the statements manually on each
     machine.

   * It is possible to re-create the grant tables completely after they
     have previously been created.  You might want to do this if you are
     just learning how to use 'CREATE USER',
     'GRANT', and 'REVOKE' and have made so many
     modifications after running 'mysql_install_db'
     that you want to wipe out the tables and start
     over.

     To re-create the grant tables, stop the server if it is running and
     remove the 'mysql' database directory.  Then run
     'mysql_install_db' again.

2.10.2 Starting the Server
--------------------------

This section describes how start the server on Unix and Unix-like
systems.  (For Windows, see windows-server-first-start.)  For
some suggested commands that you can use to test whether the server is
accessible and working properly, see testing-server.

Start the MySQL server like this if your installation includes
'mysqld_safe'.:

     shell> bin/mysqld_safe --user=mysql &

*Note*:

For Linux systems on which MySQL is installed using RPM packages, server
startup and shutdown is managed using systemd rather than
'mysqld_safe', and 'mysqld_safe' is not
installed.  See using-systemd.

Start the server like this if your installation includes systemd
support:

     shell> systemctl start mysqld

Substitute the appropriate service name if it differs from 'mysqld'; for
example, 'mysql' on SLES systems.

It is important that the MySQL server be run using an unprivileged
(non-'root') login account.  To ensure this, run 'mysqld_safe'
as 'root' and include the '--user' option as shown.
Otherwise, you should execute the program while logged in as 'mysql', in
which case you can omit the '--user' option from the command.

For further instructions for running MySQL as an unprivileged user, see
changing-mysql-user.

If the command fails immediately and prints 'mysqld ended', look for
information in the error log (which by default is the 'HOST_NAME.err'
file in the data directory).

If the server is unable to access the data directory it starts or read
the grant tables in the 'mysql' database, it writes a message to its
error log.  Such problems can occur if you neglected to create the grant
tables by initializing the data directory before proceeding to this
step, or if you ran the command that initializes the data directory
without the '--user' option.  Remove the 'data' directory and run the
command with the '--user' option.

If you have other problems starting the server, see
starting-server-troubleshooting.  For more information about
'mysqld_safe', see mysqld-safe.  For more
information about systemd support, see using-systemd.

2.10.2.1 Troubleshooting Problems Starting the MySQL Server
...........................................................

This section provides troubleshooting suggestions for problems starting
the server.  For additional suggestions for Windows systems, see
windows-troubleshooting.

If you have problems starting the server, here are some things to try:

   * Check the error log to see why the server does not start.  Log
     files are located in the data directory (typically 'C:\Program
     Files\MySQL\MySQL Server 5.7\data' on Windows,
     '/usr/local/mysql/data' for a Unix/Linux binary distribution, and
     '/usr/local/var' for a Unix/Linux source distribution).  Look in
     the data directory for files with names of the form 'HOST_NAME.err'
     and 'HOST_NAME.log', where HOST_NAME is the name of your server
     host.  Then examine the last few lines of these files.  Use 'tail'
     to display them:

          shell> tail HOST_NAME.err
          shell> tail HOST_NAME.log

   * Specify any special options needed by the storage engines you are
     using.  You can create a 'my.cnf' file and specify startup options
     for the engines that you plan to use.  If you are going to use
     storage engines that support transactional tables ('InnoDB', see
     'NDB'), be sure that you have them configured the
     way you want before starting the server.  If you are using 'InnoDB'
     tables, see innodb-configuration for guidelines and
     innodb-parameters for option syntax.

     Although storage engines use default values for options that you
     omit, Oracle recommends that you review the available options and
     specify explicit values for any options whose defaults are not
     appropriate for your installation.

   * Make sure that the server knows where to find the data directory.
     The 'mysqld' server uses this directory as its
     current directory.  This is where it expects to find databases and
     where it expects to write log files.  The server also writes the
     pid (process ID) file in the data directory.

     The default data directory location is hardcoded when the server is
     compiled.  To determine what the default path settings are, invoke
     'mysqld' with the '--verbose' and '--help' options.
     If the data directory is located somewhere else on your system,
     specify that location with the '--datadir' option to
     'mysqld' or 'mysqld_safe', on the
     command line or in an option file.  Otherwise, the server will not
     work properly.  As an alternative to the '--datadir' option, you
     can specify 'mysqld' the location of the base
     directory under which MySQL is installed with the '--basedir', and
     'mysqld' looks for the 'data' directory there.

     To check the effect of specifying path options, invoke
     'mysqld' with those options followed by the '--verbose'
     and '--help' options.  For example, if you change location into the
     directory where 'mysqld' is installed and then run
     the following command, it shows the effect of starting the server
     with a base directory of '/usr/local':

          shell> ./mysqld --basedir=/usr/local --verbose --help

     You can specify other options such as '--datadir' as well, but
     '--verbose' and '--help' must be the last options.

     Once you determine the path settings you want, start the server
     without '--verbose' and '--help'.

     If 'mysqld' is currently running, you can find out
     what path settings it is using by executing this command:

          shell> mysqladmin variables

     Or:

          shell> mysqladmin -h HOST_NAME variables

     HOST_NAME is the name of the MySQL server host.

   * Make sure that the server can access the data directory.  The
     ownership and permissions of the data directory and its contents
     must allow the server to read and modify them.

     If you get 'Errcode 13' (which means 'Permission denied') when
     starting 'mysqld', this means that the privileges of
     the data directory or its contents do not permit server access.  In
     this case, you change the permissions for the involved files and
     directories so that the server has the right to use them.  You can
     also start the server as 'root', but this raises security issues
     and should be avoided.

     Change location into the data directory and check the ownership of
     the data directory and its contents to make sure the server has
     access.  For example, if the data directory is
     '/usr/local/mysql/var', use this command:

          shell> ls -la /usr/local/mysql/var

     If the data directory or its files or subdirectories are not owned
     by the login account that you use for running the server, change
     their ownership to that account.  If the account is named 'mysql',
     use these commands:

          shell> chown -R mysql /usr/local/mysql/var
          shell> chgrp -R mysql /usr/local/mysql/var

     Even with correct ownership, MySQL might fail to start up if there
     is other security software running on your system that manages
     application access to various parts of the file system.  In this
     case, reconfigure that software to enable 'mysqld'.
     to access the directories it uses during normal operation.

   * Verify that the network interfaces the server wants to use are
     available.

     If either of the following errors occur, it means that some other
     program (perhaps another 'mysqld' server) is using
     the TCP/IP port or Unix socket file that 'mysqld' is
     trying to use:

          Can't start server: Bind on TCP/IP port: Address already in use
          Can't start server: Bind on unix socket...

     Use 'ps' to determine whether you have another 'mysqld'
     server running.  If so, shut down the server before
     starting 'mysqld' again.  (If another server is
     running, and you really want to run multiple servers, you can find
     information about how to do so in multiple-servers.)

     If no other server is running, execute the command 'telnet
     YOUR_HOST_NAME TCP_IP_PORT_NUMBER'.  (The default MySQL port number
     is 3306.)  Then press Enter a couple of times.  If you do not get
     an error message like 'telnet: Unable to connect to remote host:
     Connection refused', some other program is using the TCP/IP port
     that 'mysqld' is trying to use.  Track down what
     program this is and disable it, or tell 'mysqld' to
     listen to a different port with the '--port' option.  In this case,
     specify the same non-default port number for client programs when
     connecting to the server using TCP/IP.

     Another reason the port might be inaccessible is that you have a
     firewall running that blocks connections to it.  If so, modify the
     firewall settings to permit access to the port.

     If the server starts but you cannot connect to it, make sure that
     you have an entry in '/etc/hosts' that looks like this:

          127.0.0.1       localhost

   * If you cannot get 'mysqld' to start, try to make a
     trace file to find the problem by using the '--debug' option.  See
     dbug-package.

2.10.3 Testing the Server
-------------------------

After the data directory is initialized and you have started the server,
perform some simple tests to make sure that it works satisfactorily.
This section assumes that your current location is the MySQL
installation directory and that it has a 'bin' subdirectory containing
the MySQL programs used here.  If that is not true, adjust the command
path names accordingly.

Alternatively, add the 'bin' directory to your 'PATH' environment
variable setting.  That enables your shell (command interpreter) to find
MySQL programs properly, so that you can run a program by typing only
its name, not its path name.  See setting-environment-variables.

Use 'mysqladmin' to verify that the server is
running.  The following commands provide simple tests to check whether
the server is up and responding to connections:

     shell> bin/mysqladmin version
     shell> bin/mysqladmin variables

If you cannot connect to the server, specify a '-u root' option to
connect as 'root'.  If you have assigned a password for the 'root'
account already, you'll also need to specify '-p' on the command line
and enter the password when prompted.  For example:

     shell> bin/mysqladmin -u root -p version
     Enter password: (ENTER ROOT PASSWORD HERE)

The output from 'mysqladmin version' varies slightly
depending on your platform and version of MySQL, but should be similar
to that shown here:

     shell> bin/mysqladmin version
     mysqladmin  Ver 14.12 Distrib 5.7.23, for pc-linux-gnu on i686
     ...

     Server version          5.7.23
     Protocol version        10
     Connection              Localhost via UNIX socket
     UNIX socket             /var/lib/mysql/mysql.sock
     Uptime:                 14 days 5 hours 5 min 21 sec

     Threads: 1  Questions: 366  Slow queries: 0
     Opens: 0  Flush tables: 1  Open tables: 19
     Queries per second avg: 0.000

To see what else you can do with 'mysqladmin', invoke
it with the '--help' option.

Verify that you can shut down the server (include a '-p' option if the
'root' account has a password already):

     shell> bin/mysqladmin -u root shutdown

Verify that you can start the server again.  Do this by using
'mysqld_safe' or by invoking 'mysqld'.
directly.  For example:

     shell> bin/mysqld_safe --user=mysql &

If 'mysqld_safe' fails, see
starting-server-troubleshooting.

Run some simple tests to verify that you can retrieve information from
the server.  The output should be similar to that shown here.

Use 'mysqlshow' to see what databases exist:

     shell> bin/mysqlshow
     +--------------------+
     |     Databases      |
     +--------------------+
     | information_schema |
     | mysql              |
     | performance_schema |
     | sys                |
     +--------------------+

The list of installed databases may vary, but will always include the
minimum of 'mysql' and 'information_schema'.

If you specify a database name, see 'mysqlshow' displays a
list of the tables within the database:

     shell> bin/mysqlshow mysql
     Database: mysql
     +---------------------------+
     |          Tables           |
     +---------------------------+
     | columns_priv              |
     | db                        |
     | engine_cost               |
     | event                     |
     | func                      |
     | general_log               |
     | gtid_executed             |
     | help_category             |
     | help_keyword              |
     | help_relation             |
     | help_topic                |
     | innodb_index_stats        |
     | innodb_table_stats        |
     | ndb_binlog_index          |
     | plugin                    |
     | proc                      |
     | procs_priv                |
     | proxies_priv              |
     | server_cost               |
     | servers                   |
     | slave_master_info         |
     | slave_relay_log_info      |
     | slave_worker_info         |
     | slow_log                  |
     | tables_priv               |
     | time_zone                 |
     | time_zone_leap_second     |
     | time_zone_name            |
     | time_zone_transition      |
     | time_zone_transition_type |
     | user                      |
     +---------------------------+

Use the 'mysql' program to select information from a table
in the 'mysql' database:

     shell> bin/mysql -e "SELECT User, Host, plugin FROM mysql.user" mysql
     +------+-----------+-----------------------+
     | User | Host      | plugin                |
     +------+-----------+-----------------------+
     | root | localhost | mysql_native_password |
     +------+-----------+-----------------------+

At this point, your server is running and you can access it.  To tighten
security if you have not yet assigned a password to the initial account,
follow the instructions in default-privileges.

For more information about 'mysql', 'mysqladmin',
and 'mysqlshow', see mysql,
mysqladmin, and mysqlshow.

2.10.4 Securing the Initial MySQL Accounts
------------------------------------------

The MySQL installation process involves initializing the data directory,
including the 'mysql' database containing the grant tables that define
MySQL accounts.  For details, see postinstallation.

This section describes how to assign passwords to the initial accounts
created during the MySQL installation procedure, if you have not already
done so.

*Note*:

On Windows, you can also perform the process described in this section
during installation with MySQL Installer (see mysql-installer).
On all platforms, the MySQL distribution includes
'mysql_secure_installation', a command-line
utility that automates much of the process of securing a MySQL
installation.  MySQL Workbench is available on all platforms, and also
offers the ability to manage user accounts (see workbench ).

Passwords may have already been assigned under these circumstances:

   * Installation On Windows performed using MySQL Installer give you
     the option of assigning passwords.

   * Installation on Linux using a server RPM or Debian distribution
     from Oracle.  See instructions given in
     linux-installation-rpm, linux-installation-yum-repo,
     linux-installation-debian, or
     linux-installation-apt-repo for how to find the
     randomly-generated password (for RPM installations) or how to set
     the password (for Debian installations).

   * As of MySQL 5.7.6, if you initialized the data directory manually
     using 'mysqld --initialize', a random password should
     have been generated for the initial account; see
     data-directory-initialization-mysqld for details.

The 'mysql.user' grant table defines the initial MySQL user accounts and
their access privileges.  Current versions of MySQL 5.7 create only a
''root'@'localhost'' account, but for earlier versions, there might be
multiple accounts such as described here:

   * Some accounts have the user name 'root'.  These are superuser
     accounts that have all privileges and can do anything.  If these
     'root' accounts have empty passwords, anyone can connect to the
     MySQL server as 'root' _without a password_ and be granted all
     privileges.

        * On Windows, 'root' accounts are created that permit
          connections from the local host only.  Connections can be made
          by specifying the host name 'localhost', the IP address
          '127.0.0.1', or the IPv6 address '::1'.  If the user selects
          the 'Enable root access from remote machines' option during
          installation, the Windows installer creates another 'root'
          account that permits connections from any host.

        * On Unix, each 'root' account permits connections from the
          local host.  Connections can be made by specifying the host
          name 'localhost', the IP address '127.0.0.1', the IPv6 address
          '::1', or the actual host name or IP address.

        * The ''root'@'localhost'' account also has a row in the
          'mysql.proxies_priv' table that enables granting the 'PROXY'
          privilege for '''@''', that is, for all users and all hosts.
          This enables 'root' to set up proxy users, as well as to
          delegate to other accounts the authority to set up proxy
          users.  See proxy-users.

   *
     If accounts for anonymous users were created, these have an empty
     user name.  The anonymous accounts have no password, so anyone can
     use them to connect to the MySQL server.

        * On Windows, there is one anonymous account that permits
          connections from the local host.  Connections can be made by
          specifying a host name of 'localhost'.

        * On Unix, each anonymous account permits connections from the
          local host.  Connections can be made by specifying a host name
          of 'localhost' for one of the accounts, or the actual host
          name or IP address for the other.

*Checking Which Accounts Exist*

Start the server if it is not running.  For instructions, see
starting-server.

Assuming that no 'root' password has been assigned, you should be able
to connect to the server as 'root' without one:

     shell> mysql -u root

Once connected, determine which accounts exist in the 'mysql.user' table
and whether their passwords are empty:

   * As of MySQL 5.7.6, use this statement:

          mysql> SELECT User, Host, HEX(authentication_string) FROM mysql.user;

     The statement uses 'HEX()' because passwords stored in the
     'authentication_string' column might contain binary data that does
     not display well.

   * Before MySQL 5.7.6, use this statement:

          mysql> SELECT User, Host, Password FROM mysql.user;

The 'SELECT' statement results can vary depending on your
version of MySQL and installation method.  The following example output
includes several 'root' and anonymous-user accounts, none of which have
passwords:

     +------+--------------------+----------+
     | User | Host               | Password |
     +------+--------------------+----------+
     | root | localhost          |          |
     | root | myhost.example.com |          |
     | root | 127.0.0.1          |          |
     | root | ::1                |          |
     |      | localhost          |          |
     |      | myhost.example.com |          |
     +------+--------------------+----------+

If the output on your system shows any accounts with empty passwords,
your MySQL installation is unprotected until you do something about it:

   * Assign a password to each MySQL 'root' account that does not have
     one.

   * To prevent clients from connecting as anonymous users without a
     password, either assign a password to each anonymous account or
     remove the accounts.

In addition, some installation methods create a 'test' database and add
rows to the 'mysql.db' table that permit all accounts to access that
database and other databases with names that start with 'test_'.  This
is true even for accounts that otherwise have no special privileges such
as the default anonymous accounts.  This is convenient for testing but
inadvisable on production servers.  Administrators who want database
access restricted only to accounts that have permissions granted
explicitly for that purpose should remove these 'mysql.db' table rows.

The following instructions describe how to set up passwords for the
initial MySQL accounts, first for any 'root' accounts, then for
anonymous accounts.  The instructions also cover how to remove anonymous
accounts, should you prefer not to permit anonymous access at all, and
describe how to remove permissive access to test databases.

Replace NEW_PASSWORD in the examples with the password that you want to
use.  Replace HOST_NAME with the name of the server host.  You can
determine this name from the output of the 'SELECT'.
statement shown earlier.  For the output shown, HOST_NAME is
'myhost.example.com'.

*Note*:

For additional information about setting passwords, see
assigning-passwords.  If you forget your 'root' password after setting
it, see resetting-permissions.

To set up additional accounts, see adding-users.

You might want to defer setting the passwords until later, to avoid the
need to specify them while you perform additional setup or testing.
However, be sure to set them before using your installation for
production purposes.

*Assigning root Account Passwords*

To assign a password to an account, connect to the server as 'root'
using the 'mysql' client and issue the appropriate SQL
statement:

   * As of MySQL 5.7.6, use 'ALTER USER'.:

          mysql> ALTER USER USER IDENTIFIED BY 'NEW_PASSWORD';

   * Before 5.7.6, use 'SET PASSWORD'.:

          mysql> SET PASSWORD FOR USER = PASSWORD('NEW_PASSWORD');

The following instructions use 'ALTER USER'.  If your
version of MySQL is older than 5.7.6, substitute equivalent 'SET PASSWORD'
statements.

To assign the ''root'@'localhost'' account a password, connect to the
server as 'root':

     shell> mysql -u root

Then issue an 'ALTER USER' statement:

     mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'NEW_PASSWORD';

Issue a similar 'ALTER USER' statement for any other
'root' account present in your 'mysql.user' table that has no password.
(Vary the host name appropriately.)

After an account has been assigned a password, you must supply that
password whenever you connect to the server using the account.  For
example, to shut down the server with 'mysqladmin',
use this command:

     shell> mysqladmin -u root -p shutdown
     Enter password: (ENTER ROOT PASSWORD HERE)

The 'mysql' commands in the following instructions include
a '-p' option based on the assumption that you have assigned the 'root'
account password using the preceding instructions and must specify that
password when connecting to the server.

*Assigning Anonymous Account Passwords*

In MySQL 5.7, installation methods that create anonymous accounts tend
to be for early versions for which 'ALTER USER'.
cannot be used to assign passwords.  Consequently, the instructions in
this section use 'SET PASSWORD'.

To assign the '''@'localhost'' anonymous account a password, connect to
the server as 'root':

     shell> mysql -u root -p
     Enter password: (ENTER ROOT PASSWORD HERE)

Then issue a 'SET PASSWORD' statement:

     mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('NEW_PASSWORD');

Issue a similar 'SET PASSWORD' statement for any
other anonymous account present in your 'mysql.user' table that has no
password.  (Vary the host name appropriately.)

*Removing Anonymous Accounts*

If you prefer to remove any anonymous accounts rather than assigning
them passwords, use 'DROP USER'.  To drop the
'''@'localhost'' account, connect to the server as 'root':

     shell> mysql -u root -p
     Enter password: (ENTER ROOT PASSWORD HERE)

Then issue a 'DROP USER' statement:

     mysql> DROP USER ''@'localhost';

Issue a similar 'DROP USER' statement for any other
anonymous account that you want to drop.  (Vary the host name
appropriately.)

*Securing Test Databases*

Some installation methods create a 'test' database and set up privileges
for accessing it.  If that is true on your system, the 'mysql.db' table
will contain rows that permit access by any user to the 'test' database
and other databases with names that start with 'test_'.  (These rows
have an empty 'User' column value, which for access-checking purposes
matches any user name.)  This means that such databases can be used even
by accounts that otherwise possess no privileges.  If you want to remove
any-user access to test databases, do so as follows:

     shell> mysql -u root -p
     Enter password: (ENTER ROOT PASSWORD HERE)
     mysql> DELETE FROM mysql.db WHERE Db LIKE 'test%';
     mysql> FLUSH PRIVILEGES;

The 'FLUSH' statement causes the server to reread the
grant tables.  Without it, the privilege change remains unnoticed by the
server until you restart it.

With the preceding change, only users who have global database
privileges or privileges granted explicitly for the 'test' database can
use it.  However, if you prefer that the database not exist at all, drop
it:

     mysql> DROP DATABASE test;

2.10.5 Starting and Stopping MySQL Automatically
------------------------------------------------

This section discusses methods for starting and stopping the MySQL
server.

Generally, you start the 'mysqld' server in one of these
ways:

   * Invoke 'mysqld' directly.  This works on any
     platform.

   * On Windows, you can set up a MySQL service that runs automatically
     when Windows starts.  See windows-start-service.

   * On Unix and Unix-like systems, you can invoke 'mysqld_safe',
     which tries to determine the proper options for
     'mysqld' and then runs it with those options.  See
     mysqld-safe.

   * On Linux systems that support systemd, you can use it to control
     the server.  See using-systemd.

   * On systems that use System V-style run directories (that is,
     '/etc/init.d' and run-level specific directories), invoke
     'mysql.server'.  This script is used primarily at
     system startup and shutdown.  It usually is installed under the
     name 'mysql'.  The 'mysql.server' script
     starts the server by invoking 'mysqld_safe'.
     See mysql-server.

   * On OS X, install a launchd daemon to enable automatic MySQL startup
     at system startup.  The daemon starts the server by invoking
     'mysqld_safe'.  For details, see
     osx-installation-launchd.  A MySQL Preference Pane also provides
     control for starting and stopping MySQL through the System
     Preferences.  See osx-installation-prefpane.

   * On Solaris, use the service management framework (SMF) system to
     initiate and control MySQL startup.

systemd, the 'mysqld_safe' and 'mysql.server'
scripts, Solaris SMF, and the OS X Startup Item (or MySQL
Preference Pane) can be used to start the server manually, or
automatically at system startup time.  systemd, see 'mysql.server',
and the Startup Item also can be used to stop the server.

The following table shows which option groups the server and startup
scripts read from option files.

*MySQL Startup Scripts and Supported Server Option Groups*

Script         Option Groups

See '[mysqld]', '[server]', '[mysqld-MAJOR_VERSION]' 'mysqld'.

See '[mysqld]', '[server]', '[mysqld_safe]' 'mysqld_safe'.

See '[mysqld]', '[mysql.server]', '[server]' 'mysql.server'.

'[mysqld-MAJOR_VERSION]' means that groups with names like
'[mysqld-5.6]' and '[mysqld-5.7]' are read by servers having versions
5.6.x, 5.7.x, and so forth.  This feature can be used to specify options
that can be read only by servers within a given release series.

For backward compatibility, see 'mysql.server' also
reads the '[mysql_server]' group and 'mysqld_safe'.
also reads the '[safe_mysqld]' group.  To be current, you should update
your option files to use the '[mysql.server]' and '[mysqld_safe]' groups
instead.

For more information on MySQL configuration files and their structure
and contents, see option-files.

2.11 Upgrading or Downgrading MySQL
===================================

This section describes the steps to upgrade or downgrade a MySQL
installation.

Upgrading is a common procedure, as you pick up bug fixes within the
same MySQL release series or significant features between major MySQL
releases.  You perform this procedure first on some test systems to make
sure everything works smoothly, and then on the production systems.

Downgrading is less common.  Typically, you undo an upgrade because of
some compatibility or performance issue that occurs on a production
system, and was not uncovered during initial upgrade verification on the
test systems.  As with the upgrade procedure, perform and verify the
downgrade procedure on some test systems first, before using it on a
production system.

2.11.1 Upgrading MySQL
----------------------

This section describes how to upgrade to a new MySQL version.

2.11.1.1 MySQL Upgrade Strategies
.................................

   * upgrade-methods

   * upgrade-paths

   * upgrade-before-you-begin

   * upgrade-procedure-inplace

   * upgrade-procedure-logical

   * upgrade-troubleshooting

*Note*:

In the following discussion, MySQL commands that must be run using a
MySQL account with administrative privileges include '-u root' on the
command line to specify the MySQL 'root' user.  Commands that require a
password for 'root' also include a '-p' option.  Because '-p' is
followed by no option value, such commands prompt for the password.
Type the password when prompted and press Enter.

SQL statements can be executed using the 'mysql'.
command-line client (connect as 'root' to ensure that you have the
necessary privileges).

*Upgrade Methods*

Upgrade methods include:

   * _In-Place Upgrade_: Involves shutting down the old MySQL version,
     replacing the old MySQL binaries or packages with the new ones,
     restarting MySQL on the existing data directory, and running
     'mysql_upgrade'.

   * _Logical Upgrade_: Involves exporting existing data from the old
     MySQL version using 'mysqldump', installing the
     new MySQL version, loading the dump file into the new MySQL
     version, and running 'mysql_upgrade'.

For in-place and logical upgrade procedures, see
upgrade-procedure-inplace, and upgrade-procedure-logical.

If you run MySQL Server on Windows, refer to the upgrade procedure
described in windows-upgrading.

If your current MySQL installation was installed on an Enterprise Linux
platform or Fedora using the MySQL Yum Repository, see
updating-yum-repo.

If your current MySQL installation was installed on Ubuntu using the
MySQL APT repository, see updating-apt-repo.

*Upgrade Paths*

   * Upgrade is only supported between General Availability (GA)
     releases.

   * Upgrade from MySQL 5.6 to 5.7 is supported.  Upgrading to the
     latest release is recommended before upgrading to the next version.
     For example, upgrade to the latest MySQL 5.6 release before
     upgrading to MySQL 5.7.

   * Upgrade that skips versions is not supported.  For example,
     upgrading directly from MySQL 5.5 to 5.7 is not supported.

   * Upgrade within a release series is supported.  For example,
     upgrading from MySQL 5.7.X to 5.7.Y is supported.  Skipping a
     release is also supported.  For example, upgrading from MySQL 5.7.X
     to 5.7.Z is supported.

*Before You Begin*

Before upgrading, review the following information and perform the
recommended steps:

   * Before upgrading, protect your data by creating a backup of your
     current databases and log files.  The backup should include the
     'mysql' system database, which contains the MySQL system tables.
     See backup-methods.

   * Review the Release Notes
     (http://dev.mysql.com/doc/relnotes/mysql/5.7/en/) which provide
     information about features that are new in the MySQL 5.7 or differ
     from those found in earlier MySQL releases.  Some of these changes
     may result in incompatibilities.

     For a description of MySQL server features that have been removed
     in MySQL 5.7, see mysql-nutshell-removals.  An upgrade
     requires changes with respect to those features if you use any of
     them.

     For listings of MySQL server variables and options that have been
     added, deprecated, or removed in MySQL 5.7, see
     added-deprecated-removed.  If you use any of these items, an
     upgrade requires configuration changes.

   * Review upgrading-from-previous-series.  This section
     describes changes that may require action before or after
     upgrading.

   * If you use replication, review replication-upgrade.

   * If you use XA transactions with 'InnoDB', run 'XA RECOVER'
     before upgrading to check for uncommitted XA
     transactions.  If results are returned, either commit or rollback
     the XA transactions by issuing an 'XA COMMIT'.
     or 'XA ROLLBACK' statement.

   * If your MySQL installation contains a large amount of data that
     might take a long time to convert after an in-place upgrade, you
     might find it useful to create a 'dummy' database instance for
     assessing what conversions might be needed and the work involved to
     perform them.  Make a copy of your MySQL instance that contains a
     full copy of the 'mysql' database, plus all other databases without
     data.  Run your upgrade procedure on this dummy instance to see
     what actions might be needed so that you can better evaluate the
     work involved when performing actual data conversion on your
     original database instance.

   * Rebuilding and reinstalling MySQL language interfaces is
     recommended whenever you install or upgrade to a new release of
     MySQL. This applies to MySQL interfaces such as PHP 'mysql'
     extensions, the Perl 'DBD::mysql' module, and the Python 'MySQLdb'
     module.

*In-Place Upgrade*

This section describes how to perform an in-place upgrade.  Review
Before you Begin before proceeding.

*Note*:

If you upgrade an installation originally produced by installing
multiple RPM packages, upgrade all the packages, not just some.  For
example, if you previously installed the server and client RPMs, do not
upgrade just the server RPM.

For some Linux platforms, MySQL installation from RPM or Debian packages
includes systemd support for managing MySQL server startup and shutdown.
On these platforms, see 'mysqld_safe' is not installed.
In such cases, use systemd for server startup and shutdown instead of
the methods used in the following instructions.  See
using-systemd.

To perform an in-place upgrade:

  1. Review the changes described in
     upgrading-from-previous-series for steps to be performed before
     upgrading.

  2. Configure MySQL to perform a slow shutdown by setting
     'innodb_fast_shutdown' to '0'.  For example:

          mysql -u root -p --execute="SET GLOBAL innodb_fast_shutdown=0"

     With a slow shutdown, 'InnoDB' performs a full purge and change
     buffer merge before shutting down, which ensures that data files
     are fully prepared in case of file format differences between
     releases.

  3. Shut down the old MySQL server.  For example:

          mysqladmin -u root -p shutdown

  4. Upgrade the MySQL binary installation or packages.  If upgrading a
     binary installation, unpack the new MySQL binary distribution
     package.  See binary-installation-unpack.  For
     package-based installations, replace the old packages with the new
     ones.

     *Note*:

     For supported Linux distributions, the preferred method for
     replacing the MySQL packages is to use the MySQL software
     repositories; see updating-yum-repo,
     updating-apt-repo, or Upgrading MySQL with the MySQL SLES
     Repository
     (http://dev.mysql.com/doc/mysql-sles-repo-quick-guide/en/#repo-qg-sles-upgrading)
     for instructions.

  5. Start the MySQL 5.7 server, using the existing data directory.  For
     example:

          mysqld_safe --user=mysql --datadir=/PATH/TO/EXISTING-DATADIR

  6. Run 'mysql_upgrade'.  For example:

          mysql_upgrade -u root -p

     'mysql_upgrade' examines all tables in all
     databases for incompatibilities with the current version of MySQL.
     'mysql_upgrade' also upgrades the 'mysql'
     system database so that you can take advantage of new privileges or
     capabilities.

     *Note*:

     'mysql_upgrade' does not upgrade the contents
     of the help tables.  For upgrade instructions, see
     server-side-help-support.

  7. Shut down and restart the MySQL server to ensure that any changes
     made to the system tables take effect.  For example:

          mysqladmin -u root -p shutdown
          mysqld_safe --user=mysql --datadir=/PATH/TO/EXISTING-DATADIR

*Logical Upgrade*

This section describes how to perform a logical upgrade.  Review Before
you Begin before proceeding.

*Note*:

For some Linux platforms, MySQL installation from RPM or Debian packages
includes systemd support for managing MySQL server startup and shutdown.
On these platforms, see 'mysqld_safe' is not installed.
In such cases, use systemd for server startup and shutdown instead of
the methods used in the following instructions.  See
using-systemd.

To perform a logical upgrade:

  1. Review the changes described in
     upgrading-from-previous-series for steps to be performed before
     upgrading.

  2. Export your existing data from the previous MySQL version:

          mysqldump -u root -p
            --add-drop-table --routines --events
            --all-databases --force > data-for-upgrade.sql

     *Note*:

     Use the '--routines' and '--events' options with 'mysqldump'.
     (as shown above) if your databases include stored
     programs.  The '--all-databases' option includes all databases in
     the dump, including the 'mysql' database that holds the system
     tables.

     *Important*:

     If you have tables that contain generated columns, use the
     'mysqldump' utility provided with MySQL 5.7.9 or higher
     to create your dump files.  The 'mysqldump'.
     utility provided in earlier releases uses incorrect syntax for
     generated column definitions (Bug #20769542).  You can use the
     'INFORMATION_SCHEMA.COLUMNS' table to
     identify tables with generated columns.

  3. Shut down the old MySQL server.  For example:

          mysqladmin -u root -p shutdown

  4. Install MySQL 5.7.  For installation instructions, see
     installing.

  5. Initialize a new data directory, as described at
     data-directory-initialization.  For example:

          mysqld --initialize --datadir=/PATH/TO/5.7-DATADIR

     Copy the temporary ''root'@'localhost'' password displayed to your
     screen or written to your error log for later use.

  6. Start the MySQL 5.7 server, using the new data directory.  For
     example:

          mysqld_safe --user=mysql --datadir=/PATH/TO/5.7-DATADIR

  7. Reset the 'root' password:

          shell> mysql -u root -p
          Enter password: ****  <- enter temporary root password

          mysql> ALTER USER USER() IDENTIFIED BY 'YOUR NEW PASSWORD';

  8. Load the previously created dump file into the new MySQL server.
     For example:

          mysql -u root -p --force < data-for-upgrade.sql

     *Note*:

     It is not recommended to load a dump file when GTIDs are enabled on
     the server ('gtid_mode=ON'), if your dump file includes system
     tables.  'mysqldump' issues DML instructions for
     the system tables which use the non-transactional MyISAM storage
     engine, and this combination is not permitted when GTIDs are
     enabled.  Also be aware that loading a dump file from a server with
     GTIDs enabled, into another server with GTIDs enabled, causes
     different transaction identifiers to be generated.

  9. Run 'mysql_upgrade'.  For example:

          mysql_upgrade -u root -p

     'mysql_upgrade' examines all tables in all
     databases for incompatibilities with the current version of MySQL.
     'mysql_upgrade' also upgrades the 'mysql'
     system database so that you can take advantage of new privileges or
     capabilities.

     *Note*:

     'mysql_upgrade' does not upgrade the contents
     of the help tables.  For upgrade instructions, see
     server-side-help-support.

  10. Shut down and restart the MySQL server to ensure that any changes
     made to the system tables take effect.  For example:

          mysqladmin -u root -p shutdown
          mysqld_safe --user=mysql --datadir=/PATH/TO/5.7-DATADIR

*Upgrade Troubleshooting*

   * If problems occur, such as that the new 'mysqld'.
     server does not start, verify that you do not have an old 'my.cnf'
     file from your previous installation.  You can check this with the
     '--print-defaults' option (for example, see 'mysqld --print-defaults').
     If this command displays anything
     other than the program name, you have an active 'my.cnf' file that
     affects server or client operation.

   * If, after an upgrade, you experience problems with compiled client
     programs, such as 'Commands out of sync' or unexpected core dumps,
     you probably have used old header or library files when compiling
     your programs.  In this case, check the date for your 'mysql.h'
     file and 'libmysqlclient.a' library to verify that they are from
     the new MySQL distribution.  If not, recompile your programs with
     the new headers and libraries.  Recompilation might also be
     necessary for programs compiled against the shared client library
     if the library major version number has changed (for example, from
     'libmysqlclient.so.15' to 'libmysqlclient.so.16').

   * If you have created a user-defined function (UDF) with a given name
     and upgrade MySQL to a version that implements a new built-in
     function with the same name, the UDF becomes inaccessible.  To
     correct this, use 'DROP FUNCTION' to drop the
     UDF, and then use 'CREATE FUNCTION' to
     re-create the UDF with a different nonconflicting name.  The same
     is true if the new version of MySQL implements a built-in function
     with the same name as an existing stored function.  See
     function-resolution, for the rules describing how the server
     interprets references to different kinds of functions.

2.11.1.2 Changes Affecting Upgrades to MySQL 5.7
................................................

Before upgrading to MySQL 5.7, review the changes described in this
section to identify upgrade issues that apply to your current MySQL
installation and applications.

*Note*:

In addition to the changes outlined in this section, review the Release
Notes (http://dev.mysql.com/doc/relnotes/mysql/5.7/en/) and other
important information outlined in upgrade-before-you-begin.

Changes marked as either *Known issue* or *Incompatible change* are
incompatibilities with earlier versions of MySQL, and may require your
attention _before you upgrade_.  Our aim is to avoid these changes, but
occasionally they are necessary to correct problems that would be worse
than an incompatibility between releases.  If any upgrade issue
applicable to your installation involves an incompatibility that
requires special handling, follow the instructions given in the
incompatibility description.  Sometimes this involves dumping and
reloading tables, or use of a statement such as 'CHECK TABLE'
or 'REPAIR TABLE'.

For dump and reload instructions, see rebuilding-tables.  Any
procedure that involves 'REPAIR TABLE' with the
'USE_FRM' option _must_ be done before upgrading.  Use of this statement
with a version of MySQL different from the one used to create the table
(that is, using it after upgrading) may damage the table.  See
repair-table.

   * upgrade-configuration-changes

   * upgrade-system-table-changes

   * upgrade-server-changes

   * upgrade-innodb-changes

   * upgrade-sql-changes

*Configuration Changes*

   * *Incompatible change*: As of MySQL 5.7.12, the default
     '--early-plugin-load' value is empty.  To load the 'keyring_file'
     plugin, you must use an explicit '--early-plugin-load' option with
     a nonempty value.

     In MySQL 5.7.11, the default '--early-plugin-load' value was the
     name of the 'keyring_file' plugin library file, so that plugin was
     loaded by default.  'InnoDB' tablespace encryption requires the
     'keyring_file' plugin to be loaded prior to 'InnoDB'
     initialization, so this change of default '--early-plugin-load'
     value introduces an incompatibility for upgrades from 5.7.11 to
     5.7.12 or higher.  Administrators who have encrypted 'InnoDB'
     tablespaces must take explicit action to ensure continued loading
     of the 'keyring_file' plugin: Start the server with an
     '--early-plugin-load' option that names the plugin library file.
     For additional information, see keyring-installation.

   * *Incompatible change*: The 'INFORMATION_SCHEMA' has tables that
     contain system and status variable information (see
     variables-table, and status-table).  As of MySQL 5.7.6,
     the Performance Schema also contains system and status variable
     tables (see performance-schema-system-variable-tables, and
     performance-schema-status-variable-tables).  The
     Performance Schema tables are intended to replace the
     'INFORMATION_SCHEMA' tables, which are deprecated as of MySQL 5.7.6
     and will be removed in a future MySQL release.

     For advice on migrating away from the 'INFORMATION_SCHEMA' tables
     to the Performance Schema tables, see
     performance-schema-variable-table-migration.  To assist in the
     migration, you can use the 'show_compatibility_56' system variable,
     which affects how system and status variable information is
     provided by the 'INFORMATION_SCHEMA' and Performance Schema tables,
     and also by the 'SHOW VARIABLES' and
     'SHOW STATUS' statements.  'show_compatibility_56' is
     enabled by default in 5.7.6 and 5.7.7, and disabled by default in
     MySQL 5.7.8.

     For details about the effects of 'show_compatibility_56', see
     server-system-variables For better understanding, it is strongly
     recommended that you read also these sections:

        * performance-schema-system-variable-tables

        * performance-schema-status-variable-tables

        * performance-schema-status-variable-summary-tables

   * *Incompatible change*: As of MySQL 5.7.6, for some Linux platforms,
     when MySQL is installed using RPM and Debian packages, server
     startup and shutdown now is managed using systemd rather than
     'mysqld_safe', and 'mysqld_safe'.
     is not installed.  This may require some adjustment to the manner
     in which you specify server options.  For details, see
     using-systemd.

   * *Incompatible change*: In MySQL 5.7.5, the executable binary
     version of 'mysql_install_db' is located
     in the 'bin' installation directory, whereas the Perl version was
     located in the 'scripts' installation directory.  For upgrades from
     an older version of MySQL, you may find a version in both
     directories.  To avoid confusion, remove the version in the
     'scripts' directory.  For fresh installations of MySQL 5.7.5 or
     later, see 'mysql_install_db' is only found in
     the 'bin' directory, and the 'scripts' directory is no longer
     present.  Applications that expect to find
     'mysql_install_db' in the 'scripts' directory
     should be updated to look in the 'bin' directory instead.

     The location of 'mysql_install_db' becomes
     less material as of MySQL 5.7.6 because as of that version it is
     deprecated in favor of 'mysqld --initialize'. (or
     'mysqld --initialize-insecure').  See
     data-directory-initialization-mysqld

   * *Incompatible change*: In MySQL 5.7.5, these SQL mode changes were
     made:

        * Strict SQL mode for transactional storage engines
          ('STRICT_TRANS_TABLES') is now enabled by default.

        * Implementation of the 'ONLY_FULL_GROUP_BY' SQL mode has been
          made more sophisticated, to no longer reject deterministic
          queries that previously were rejected.  In consequence,
          'ONLY_FULL_GROUP_BY' is now enabled by default, to prohibit
          nondeterministic queries containing expressions not guaranteed
          to be uniquely determined within a group.

        * The changes to the default SQL mode result in a default
          'sql_mode' system variable value with these modes enabled:
          'ONLY_FULL_GROUP_BY', 'STRICT_TRANS_TABLES',
          'NO_ENGINE_SUBSTITUTION'.

        * The 'ONLY_FULL_GROUP_BY' mode is also now included in the
          modes comprised by the 'ANSI' SQL mode.

     If you find that having 'ONLY_FULL_GROUP_BY' enabled causes queries
     for existing applications to be rejected, either of these actions
     should restore operation:

        * If it is possible to modify an offending query, do so, either
          so that nondeterministic nonaggregated columns are
          functionally dependent on 'GROUP BY' columns, or by referring
          to nonaggregated columns using 'ANY_VALUE()'.

        * If it is not possible to modify an offending query (for
          example, if it is generated by a third-party application), set
          the 'sql_mode' system variable at server startup to not enable
          'ONLY_FULL_GROUP_BY'.

     For more information about SQL modes and 'GROUP BY' queries, see
     sql-mode, and group-by-handling.

*System Table Changes*

   * *Incompatible change*: The 'Password' column of the 'mysql.user'
     table was removed in MySQL 5.7.6.  All credentials are stored in
     the 'authentication_string' column, including those formerly stored
     in the 'Password' column.  If performing an in-place upgrade to
     MySQL 5.7.6 or later, run 'mysql_upgrade' as
     directed by the in-place upgrade procedure to migrate the
     'Password' column contents to the 'authentication_string' column.

     If performing a logical upgrade using a 'mysqldump'
     dump file from a pre-5.7.6 MySQL installation, you must
     observe these conditions for the 'mysqldump'.
     command used to generate the dump file:

        * You must include the '--add-drop-table' option

        * You must not include the '--flush-privileges' option

     As outlined in the logical upgrade procedure, load the pre-5.7.6
     dump file into the 5.7.6 (or later) server before running
     'mysql_upgrade'.

*Server Changes*

   * *Incompatible change*: As of MySQL 5.7.5, support for passwords
     that use the older pre-4.1 password hashing format is removed,
     which involves the following changes.  Applications that use any
     feature no longer supported must be modified.

        * The 'mysql_old_password' authentication plugin that used
          pre-4.1 password hash values is removed.  Accounts that use
          this plugin are disabled at startup and the server writes an
          'unknown plugin' message to the error log.  For instructions
          on upgrading accounts that use this plugin, see
          account-upgrades.

        * For the 'old_passwords' system variable, a value of 1 (produce
          pre-4.1 hash values) is no longer permitted.

        * The '--secure-auth' option to the server and client programs
          is the default, but is now a no-op.  It is deprecated and will
          be removed in a future MySQL release.

        * The '--skip-secure-auth' option to the server and client
          programs is no longer supported and using it produces an
          error.

        * The 'secure_auth' system variable permits only a value of 1; a
          value of 0 is no longer permitted.

        * The 'OLD_PASSWORD()' function is removed.

   * *Incompatible change*: In MySQL 5.6.6, the 'YEAR(2)'.
     data type was deprecated.  In MySQL 5.7.5, support for
     'YEAR(2)' is removed.  Once you upgrade to MySQL 5.7.5 or
     higher, any remaining 'YEAR(2)' columns must be
     converted to 'YEAR(4)' to become usable again.  For
     conversion strategies, see migrating-to-year4.  Running
     'mysql_upgrade' after upgrading is one of the
     possible conversion strategies.

   * As of MySQL 5.7.7, see 'CHECK TABLE ... FOR UPGRADE'
     reports a table as needing a rebuild if it contains
     old temporal columns in pre-5.6.4 format (see 'TIME',
     'DATETIME', and 'TIMESTAMP' columns
     without support for fractional seconds precision) and the
     'avoid_temporal_upgrade' system variable is disabled.  This helps
     'mysql_upgrade' to detect and upgrade tables
     containing old temporal columns.  If 'avoid_temporal_upgrade' is
     enabled, 'FOR UPGRADE' ignores the old temporal columns present in
     the table; consequently, see 'mysql_upgrade' does
     not upgrade them.

     As of MySQL 5.7.7, see 'REPAIR TABLE' upgrades a
     table if it contains old temporal columns in pre-5.6.4 format and
     the 'avoid_temporal_upgrade' system variable is disabled.  If
     'avoid_temporal_upgrade' is enabled, see 'REPAIR TABLE'
     ignores the old temporal columns present in the table
     and does not upgrade them.

     To check for tables that contain such temporal columns and need a
     rebuild, disable 'avoid_temporal_upgrade' before executing
     'CHECK TABLE ... FOR UPGRADE'.

     To upgrade tables that contain such temporal columns, disable
     'avoid_temporal_upgrade' before executing 'REPAIR TABLE'
     or 'mysql_upgrade'.

   * *Incompatible change*: As of MySQL 5.7.2, the server requires
     account rows in the 'mysql.user' table to have a nonempty 'plugin'
     column value and disables accounts with an empty value.  This
     requires that you upgrade your 'mysql.user' table to fill in all
     'plugin' values.  As of MySQL 5.7.6, use this procedure:

     If you plan to upgrade using the data directory from your existing
     MySQL installation:

       1. Stop the old (MySQL 5.6) server

       2. Upgrade the MySQL binaries in place by replacing the old
          binaries with the new ones

       3. Start the MySQL 5.7 server normally (no special options)

       4. Run 'mysql_upgrade' to upgrade the
          system tables

       5. Restart the MySQL 5.7 server

     If you plan to upgrade by reloading a dump file generated from your
     existing MySQL installation:

       1. To generate the dump file, run 'mysqldump'.
          with the '--add-drop-table' option and without the
          '--flush-privileges' option

       2. Stop the old (MySQL 5.6) server

       3. Upgrade the MySQL binaries in place (replace the old binaries
          with the new ones)

       4. Start the MySQL 5.7 server normally (no special options)

       5. Reload the dump file (see 'mysql < DUMP_FILE')

       6. Run 'mysql_upgrade' to upgrade the
          system tables

       7. Restart the MySQL 5.7 server

     Before MySQL 5.7.6, the procedure is more involved:

     If you plan to upgrade using the data directory from your existing
     MySQL installation:

       1. Stop the old (MySQL 5.6) server

       2. Upgrade the MySQL binaries in place (replace the old binaries
          with the new ones)

       3. Restart the server with the '--skip-grant-tables' option to
          disable privilege checking

       4. Run 'mysql_upgrade' to upgrade the
          system tables

       5. Restart the server normally (without '--skip-grant-tables')

     If you plan to upgrade by reloading a dump file generated from your
     existing MySQL installation:

       1. To generate the dump file, run 'mysqldump'.
          without the '--flush-privileges' option

       2. Stop the old (MySQL 5.6) server

       3. Upgrade the MySQL binaries in place (replace the old binaries
          with the new ones)

       4. Restart the server with the '--skip-grant-tables' option to
          disable privilege checking

       5. Reload the dump file (see 'mysql < DUMP_FILE')

       6. Run 'mysql_upgrade' to upgrade the
          system tables

       7. Restart the server normally (without '--skip-grant-tables')

     'mysql_upgrade' runs by default as the MySQL
     'root' user.  For the preceding procedures, if the 'root' password
     is expired when you run 'mysql_upgrade', you
     will see a message that your password is expired and that
     'mysql_upgrade' failed as a result.  To correct
     this, reset the 'root' password to unexpire it and run
     'mysql_upgrade' again:

          shell> mysql -u root -p
          Enter password: ****  <- enter root password here
          mysql> ALTER USER USER() IDENTIFIED BY 'root-password'; # MySQL 5.7.6 and up
          mysql> SET PASSWORD = PASSWORD('root-password');        # Before MySQL 5.7.6
          mysql> quit

          shell> mysql_upgrade -p
          Enter password: ****  <- enter root password here

     The password-resetting statement normally does not work if the
     server is started with '--skip-grant-tables', but the first
     invocation of 'mysql_upgrade' flushes the
     privileges, so when you run 'mysql', the statement is
     accepted.

     If 'mysql_upgrade' itself expires the 'root'
     password, you will need to reset the password again in the same
     manner.

     After following the preceding instructions, DBAs are advised also
     to convert accounts that use the 'mysql_old_password'
     authentication plugin to use 'mysql_native_password' instead,
     because support for 'mysql_old_password' has been removed.  For
     account upgrade instructions, see account-upgrades.

   * *Incompatible change*: It is possible for a column 'DEFAULT' value
     to be valid for the 'sql_mode' value at table-creation time but
     invalid for the 'sql_mode' value when rows are inserted or updated.
     Example:

          SET sql_mode = '';
          CREATE TABLE t (d DATE DEFAULT 0);
          SET sql_mode = 'NO_ZERO_DATE,STRICT_ALL_TABLES';
          INSERT INTO t (d) VALUES(DEFAULT);

     In this case, 0 should be accepted for the 'CREATE TABLE'
     but rejected for the 'INSERT'.
     However, previously the server did not evaluate 'DEFAULT' values
     used for inserts or updates against the current 'sql_mode'.  In the
     example, the 'INSERT' succeeds and inserts
     ''0000-00-00'' into the 'DATE' column.

     As of MySQL 5.7.2, the server applies the proper 'sql_mode' checks
     to generate a warning or error at insert or update time.

     A resulting incompatibility for replication if you use
     statement-based logging ('binlog_format=STATEMENT') is that if a
     slave is upgraded, a nonupgraded master will execute the preceding
     example without error, whereas the 'INSERT' will
     fail on the slave and replication will stop.

     To deal with this, stop all new statements on the master and wait
     until the slaves catch up.  Then upgrade the slaves followed by the
     master.  Alternatively, if you cannot stop new statements,
     temporarily change to row-based logging on the master
     ('binlog_format=ROW') and wait until all slaves have processed all
     binary logs produced up to the point of this change.  Then upgrade
     the slaves followed by the master and change the master back to
     statement-based logging.

   * *Incompatible change*: Several changes were made to the audit log
     plugin for better compatibility with Oracle Audit Vault.  For
     upgrading purpose, the main issue is that the default format of the
     audit log file has changed: Information within '<AUDIT_RECORD>'
     elements previously written using attributes now is written using
     subelements.

     Example of old '<AUDIT_RECORD>' format:

          <AUDIT_RECORD
           TIMESTAMP="2013-04-15T15:27:27"
           NAME="Query"
           CONNECTION_ID="3"
           STATUS="0"
           SQLTEXT="SELECT 1"
          />

     Example of new format:

          <AUDIT_RECORD>
           <TIMESTAMP>2013-04-15T15:27:27 UTC</TIMESTAMP>
           <RECORD_ID>3998_2013-04-15T15:27:27</RECORD_ID>
           <NAME>Query</NAME>
           <CONNECTION_ID>3</CONNECTION_ID>
           <STATUS>0</STATUS>
           <STATUS_CODE>0</STATUS_CODE>
           <USER>root[root] @ localhost [127.0.0.1]</USER>
           <OS_LOGIN></OS_LOGIN>
           <HOST>localhost</HOST>
           <IP>127.0.0.1</IP>
           <COMMAND_CLASS>select</COMMAND_CLASS>
           <SQLTEXT>SELECT 1</SQLTEXT>
          </AUDIT_RECORD>

     If you previously used an older version of the audit log plugin,
     use this procedure to avoid writing new-format log entries to an
     existing log file that contains old-format entries:

       1. Stop the server.

       2. Rename the current audit log file manually.  This file will
          contain only old-format log entries.

       3. Update the server and restart it.  The audit log plugin will
          create a new log file, which will contain only new-format log
          entries.

     For information about the audit log plugin, see audit-log.

*InnoDB Changes*

   * *Incompatible change*: To simplify 'InnoDB' tablespace discovery
     during crash recovery, new redo log record types were introduced in
     MySQL 5.7.5.  This enhancement changes the redo log format.  Before
     performing an in-place upgrade, perform a clean shutdown using an
     'innodb_fast_shutdown' setting of '0' or '1'.  A slow shutdown
     using 'innodb_fast_shutdown=0' is a recommended step in
     upgrade-procedure-inplace.

   * *Incompatible change*: MySQL 5.7.8 and 5.7.9 undo logs may contain
     insufficient information about spatial columns, which could result
     in a upgrade failure (Bug #21508582).  Before performing an
     in-place upgrade from MySQL 5.7.8 or 5.7.9 to 5.7.10 or higher,
     perform a slow shutdown using 'innodb_fast_shutdown=0' to clear the
     undo logs.  A slow shutdown using 'innodb_fast_shutdown=0' is a
     recommended step in upgrade-procedure-inplace.

   * *Incompatible change*: MySQL 5.7.8 undo logs may contain
     insufficient information about virtual columns and virtual column
     indexes, which could result in a upgrade failure (Bug #21869656).
     Before performing an in-place upgrade from MySQL 5.7.8 to MySQL
     5.7.9 or higher, perform a slow shutdown using
     'innodb_fast_shutdown=0' to clear the undo logs.  A slow shutdown
     using 'innodb_fast_shutdown=0' is a recommended step in
     upgrade-procedure-inplace.

   * *Incompatible change*: As of MySQL 5.7.9, the redo log header of
     the first redo log file ('ib_logfile0') includes a format version
     identifier and a text string that identifies the MySQL version that
     created the redo log files.  This enhancement changes the redo log
     format, requiring that MySQL be shutdown cleanly using an
     'innodb_fast_shutdown' setting of '0' or '1' before performing an
     in-place upgrade to MySQL 5.7.9 or higher.  A slow shutdown using
     'innodb_fast_shutdown=0' is a recommended step in
     upgrade-procedure-inplace.

   * In MySQL 5.7.9, 'DYNAMIC' replaces 'COMPACT' as the implicit
     default row format for 'InnoDB' tables.  A new configuration
     option, 'innodb_default_row_format', specifies the default 'InnoDB'
     row format.  Permitted values include 'DYNAMIC' (the default),
     'COMPACT', and 'REDUNDANT'.

     After upgrading to 5.7.9, any new tables that you create use the
     row format defined by 'innodb_default_row_format' unless you
     explicitly define a row format ('ROW_FORMAT').

     For existing tables that do not explicitly define a 'ROW_FORMAT'
     option or that use 'ROW_FORMAT=DEFAULT', any operation that
     rebuilds a table also silently changes the row format of the table
     to the format defined by 'innodb_default_row_format'.  Otherwise,
     existing tables retain their current row format setting.  For more
     information, see innodb-row-format-specification.

   * Beginning with MySQL 5.7.6, the 'InnoDB' storage engine uses its
     own built-in ('native') partitioning handler for any new
     partitioned tables created using 'InnoDB'.  Partitioned 'InnoDB'
     tables created in previous versions of MySQL are not automatically
     upgraded.  You can easily upgrade such tables to use 'InnoDB'
     native partitioning in MySQL 5.7.9 or later using either of the
     following methods:

        * To upgrade an individual table from the generic partitioning
          handler to INNODB native partitioning, execute the statement
          'ALTER TABLE TABLE_NAME UPGRADE PARTITIONING'.

        * To upgrade all 'InnoDB' tables that use the generic
          partitioning handler to use the native partitioning handler
          instead, run 'mysql_upgrade'.

*SQL Changes*

   * *Incompatible change*: The 'GET_LOCK()' function was reimplemented
     in MySQL 5.7.5 using the metadata locking (MDL) subsystem and its
     capabilities have been extended:

        * Previously, 'GET_LOCK()' permitted acquisition of only one
          named lock at a time, and a second 'GET_LOCK()' call released
          any existing lock.  Now 'GET_LOCK()' permits acquisition of
          more than one simultaneous named lock and does not release
          existing locks.

          Applications that rely on the behavior of 'GET_LOCK()'
          releasing any previous lock must be modified for the new
          behavior.

        * The capability of acquiring multiple locks introduces the
          possibility of deadlock among clients.  The MDL subsystem
          detects deadlock and returns an 'ER_USER_LOCK_DEADLOCK' error
          when this occurs.

        * The MDL subsystem imposes a limit of 64 characters on lock
          names, so this limit now also applies to named locks.
          Previously, no length limit was enforced.

        * Locks acquired with 'GET_LOCK()' now appear in the Performance
          Schema 'metadata_locks' table.
          The 'OBJECT_TYPE' column says 'USER LEVEL LOCK' and the
          'OBJECT_NAME' column indicates the lock name.

        * A new function, 'RELEASE_ALL_LOCKS()' permits release of all
          acquired named locks at once.

     For more information, see miscellaneous-functions.

   * The optimizer now handles derived tables and views in the 'FROM'
     clause in consistent fashion to better avoid unnecessary
     materialization and to enable use of pushed-down conditions that
     produce more efficient execution plans.  However, for statements
     such as 'DELETE' or 'UPDATE' that
     modify tables, using the merge strategy for a derived table that
     previously was materialized can result in an 'ER_UPDATE_TABLE_USED'
     error:

          mysql> DELETE FROM t1
              -> WHERE id IN (SELECT id
              ->              FROM (SELECT t1.id
              ->                    FROM t1 INNER JOIN t2 USING (id)
              ->                    WHERE t2.status = 0) AS t);
          ERROR 1093 (HY000): You can't specify target table 't1'
          for update in FROM clause

     The error occurs when merging a derived table into the outer query
     block results in a statement that both selects from and modifies a
     table.  (Materialization does not cause the problem because, in
     effect, it converts the derived table to a separate table.)  To
     avoid this error, disable the 'derived_merge' flag of the
     'optimizer_switch' system variable before executing the statement:

          SET optimizer_switch = 'derived_merge=off';

     The 'derived_merge' flag controls whether the optimizer attempts to
     merge subqueries and views in the 'FROM' clause into the outer
     query block, assuming that no other rule prevents merging.  By
     default, the flag is 'on' to enable merging.  Setting the flag to
     'off' prevents merging and avoids the error just described.  For
     more information, see derived-table-optimization.

   * Some keywords may be reserved in MySQL 5.7 that were not reserved
     in MySQL 5.6.  See keywords.  This can cause words
     previously used as identifiers to become illegal.  To fix affected
     statements, use identifier quoting.  See identifiers.

   * After upgrading, it is recommended that you test optimizer hints
     specified in application code to ensure that the hints are still
     required to achieve the desired optimization strategy.  Optimizer
     enhancements can sometimes render certain optimizer hints
     unnecessary.  In some cases, an unnecessary optimizer hint may even
     be counterproductive.

   * In 'UNION' statements, to apply 'ORDER BY' or 'LIMIT'
     to an individual 'SELECT', place the clause inside
     the parentheses that enclose the 'SELECT'.:

          (SELECT a FROM t1 WHERE a=10 AND B=1 ORDER BY a LIMIT 10)
          UNION
          (SELECT a FROM t2 WHERE a=11 AND B=2 ORDER BY a LIMIT 10);

     Previous versions of MySQL may permit such statements without
     parentheses.  In MySQL 5.7, the requirement for parentheses is
     enforced.

2.11.1.3 Upgrading MySQL with the MySQL Yum Repository
......................................................

For supported Yum-based platforms (see
linux-installation-yum-repo, for a list), you can perform an in-place
upgrade for MySQL (that is, replacing the old version and then running
the new version off the old data files) with the MySQL Yum repository.

*Notes*:

   * Before performing any update to MySQL, follow carefully the
     instructions in upgrading.  Among other instructions
     discussed there, it is especially important to back up your
     database before the update.

   * The following instructions assume you have installed MySQL with the
     MySQL Yum repository or with an RPM package directly downloaded
     from MySQL Developer Zone's MySQL Download page
     (http://dev.mysql.com/downloads/); if that is not the case,
     following the instructions in replace-third-party-yum.

  1. *Selecting a Target Series*

     By default, the MySQL Yum repository updates MySQL to the latest
     version in the release series you have chosen during installation
     (see yum-repo-select-series for details), which means, for
     example, a 5.6.x installation will NOT be updated to a 5.7.x
     release automatically.  To update to another release series, you
     need to first disable the subrepository for the series that has
     been selected (by default, or by yourself) and enable the
     subrepository for your target series.  To do that, see the general
     instructions given in yum-repo-select-series.  For
     upgrading from MySQL 5.6 to 5.7, perform the _reverse_ of the steps
     illustrated in yum-repo-select-series, disabling the
     subrepository for the MySQL 5.6 series and enabling that for the
     MySQL 5.7 series.

     As a general rule, to upgrade from one release series to another,
     go to the next series rather than skipping a series.  For example,
     if you are currently running MySQL 5.5 and wish to upgrade to 5.7,
     upgrade to MySQL 5.6 first before upgrading to 5.7.

     *Important*:

     For important information about upgrading from MySQL 5.6 to 5.7,
     see Upgrading from MySQL 5.6 to 5.7.

  2. *Upgrading MySQL*

     Upgrade MySQL and its components by the following command, for
     platforms that are not dnf-enabled:

          sudo yum update mysql-server

     For platforms that are dnf-enabled:

          sudo dnf upgrade mysql-server

     Alternatively, you can update MySQL by telling Yum to update
     everything on your system, which might take considerably more time;
     for platforms that are not dnf-enabled:

          sudo yum update

     For platforms that are dnf-enabled:

          sudo dnf upgrade

  3. *Restarting MySQL*

     The MySQL server always restarts after an update by Yum.  Once the
     server restarts, run 'mysql_upgrade' to check
     and possibly resolve any incompatibilities between the old data and
     the upgraded software.  'mysql_upgrade' also
     performs other functions; see mysql-upgrade for details.

You can also update only a specific component.  Use the following
command to list all the installed packages for the MySQL components (for
dnf-enabled systems, replace 'yum' in the command with 'dnf'):

     sudo yum list installed | grep "^mysql"

After identifying the package name of the component of your choice, for
platforms that are not dnf-enabled, update the package with the
following command, replacing PACKAGE-NAME with the name of the package:

     sudo yum update PACKAGE-NAME

For dnf-enabled platforms:

     sudo dnf upgrade PACKAGE-NAME

*Upgrading the Shared Client Libraries*

After updating MySQL using the Yum repository, applications compiled
with older versions of the shared client libraries should continue to
work.

_If you recompile applications and dynamically link them with the
updated libraries: _ As typical with new versions of shared libraries
where there are differences or additions in symbol versioning between
the newer and older libraries (for example, between the newer, standard
5.7 shared client libraries and some older--prior or variant--versions
of the shared libraries shipped natively by the Linux distributions'
software repositories, or from some other sources), any applications
compiled using the updated, newer shared libraries will require those
updated libraries on systems where the applications are deployed.  And,
as expected, if those libraries are not in place, the applications
requiring the shared libraries will fail.  So, be sure to deploy the
packages for the shared libraries from MySQL on those systems.  You can
do this by adding the MySQL Yum repository to the systems (see
yum-repo-setup) and install the latest shared libraries using the
instructions given in yum-install-components.

2.11.1.4 Upgrading MySQL with the MySQL APT Repository
......................................................

On Debian and Ubuntu platforms, you can perform an in-place upgrade of
MySQL and its components with the MySQL APT repository.  See Upgrading
MySQL with the MySQL APT Repository
(http://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/index.html#repo-qg-apt-upgrading)
in A Quick Guide to Using the MySQL APT Repository
(http://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/).

2.11.1.5 Upgrading MySQL with Directly-Downloaded RPM Packages
..............................................................

It is preferable to use the MySQL Yum repository
or MySQL SLES Repository
(http://dev.mysql.com/downloads/repo/suse/) to upgrade MySQL on
RPM-based platforms.  However, if you have to upgrade MySQL using the
RPM packages downloaded directly from the MySQL Developer Zone
(http://dev.mysql.com/) (see linux-installation-rpm for
information on the packages), go to the folder that contains all the
downloaded packages (and, preferably, no other RPM packages with similar
names), and issue the following command:

     yum install mysql-community-{server,client,common,libs}-*

Replace 'yum' with 'zypper' for SLES systems, and with 'dnf' for
dnf-enabled systems.

While it is much preferable to use a high-level package management tool
like 'yum' to install the packages, users who preferred direct 'rpm'
commands can replace the 'yum install' command with the 'rpm -Uvh'
command; however, using 'rpm -Uvh' instead makes the installation
process more prone to failure, due to potential dependency issues the
installation process might run into.

For an upgrade installation using RPM packages, the MySQL server is
automatically restarted at the end of the installation if it was running
when the upgrade installation began.  If the server was not running when
the upgrade installation began, you have to restart the server yourself
after the upgrade installation is completed; do that with, for example,
the follow command:

     service mysqld start

Once the server restarts, run 'mysql_upgrade' to
check and possibly resolve any incompatibilities between the old data
and the upgraded software.  'mysql_upgrade' also
performs other functions; see mysql-upgrade for details.

*Note*:

Because of the dependency relationships among the RPM packages, all of
the installed packages must be of the same version.  Therefore, always
update all your installed packages for MySQL. For example, do not just
update the server without also upgrading the client, the common files
for server and client libraries, and so on.

Migration and Upgrade from installations by older RPM packages

Some older versions of MySQL Server RPM packages have names in the form
of MySQL-* (for example, MySQL-server-* and MySQL-client-*).  The latest
versions of RPMs, when installed using the standard package management
tool ('yum', 'dnf', or 'zypper'), seamlessly upgrade those older
installations, making it unnecessary to uninstall those old packages
before installing the new ones.  Here are some differences in behavior
between the older and the current RPM packages:

*Differences Between the Previous and the Current RPM Packages for
Installing MySQL*

Feature                       Behavior of Previous   Behavior of Current
                              Packages               Packages

Service starts after          Yes                    No, unless it is an
installation is finished                             upgrade
                                                     installation, and
                                                     the server was
                                                     running when the
                                                     upgrade began.

Service name                  mysql
                                                     For RHEL, Oracle
                                                     Linux, CentOS, and
                                                     Fedora:
                                                     'mysqld'.

                                                     For SLES:
                                                     'mysql'.

Error log file                At
                              '/var/lib/mysql/HOSTNAME.err'For RHEL, Oracle
                                                     Linux, CentOS, and
                                                     Fedora: at
                                                     '/var/log/mysqld.log'

                                                     For SLES: at
                                                     '/var/log/mysql/mysqld.log'

Shipped with the              No                     Yes
'/etc/my.cnf' file

Multilib support              No                     Yes

*Note*:

Installation of previous versions of MySQL using older packages might
have created a configuration file named '/usr/my.cnf'.  It is highly
recommended that you examine the contents of the file and migrate the
desired settings inside to the file '/etc/my.cnf' file, then remove
'/usr/my.cnf'.

Upgrading to MySQL Enterprise Server

Upgrading from a community version to a commercial version of MySQL
requires that you first uninstall the community version and then install
the commercial version.  In this case, you must restart the server
manually after the upgrade.

Interoperability with operating system native MySQL packages

Many Linux distributions ship MySQL as an integrated part of the
operating system.  The latest versions of RPMs from Oracle, when
installed using the standard package management tool ('yum', 'dnf', or
'zypper'), will seamlessly upgrade and replace the MySQL version that
comes with the operating system, and the package manager will
automatically replace system compatibility packages such as
'mysql-community-libs-compat' with relevant new versions.

Upgrading from non-native MySQL packages

If you have installed MySQL with third-party packages NOT from your
Linux distribution's native software repository (for example, packages
directly downloaded from the vendor), you will need to uninstall all
those packages before you can upgrade using the packages from Oracle.

2.11.2 Downgrading MySQL
------------------------

This section describes how to downgrade to an older MySQL version.

   * downgrade-methods

   * downgrade-paths

   * downgrade-before-you-begin

   * downgrade-procedure-inplace

   * downgrade-procedure-logical

   * downgrade-troubleshooting

*Note*:

In the following discussion, MySQL commands that must be run using a
MySQL account with administrative privileges include '-u root' on the
command line to specify the MySQL 'root' user.  Commands that require a
password for 'root' also include a '-p' option.  Because '-p' is
followed by no option value, such commands prompt for the password.
Type the password when prompted and press Enter.

SQL statements can be executed using the 'mysql'.
command-line client (connect as 'root' to ensure that you have the
necessary privileges).

*Downgrade Methods*

Downgrade methods include:

   * _In-Place Downgrade_: Involves shutting down the new MySQL version,
     replacing the new MySQL binaries or packages with the old ones, and
     restarting the old MySQL version on the existing data directory.
     In-place downgrade is supported for downgrades between GA versions
     within the same release series.  For example, in-place downgrade is
     supported for downgrades from 5.7.10 to 5.7.9.

   * _Logical Downgrade_: Involves using 'mysqldump'.
     to dump all tables from the new MySQL version, and then loading the
     dump file into the old MySQL version.  Logical downgrades are
     supported for downgrades between GA versions within the same
     release series and for downgrades between release levels.  For
     example, logical downgrades are supported for downgrades from
     5.7.10 to 5.7.9 and for downgrades from 5.7 to 5.6.

*Note*:

In-place downgrade is not supported for MySQL APT, SLES, and Yum
repository installations.

For procedures, see downgrade-procedure-inplace, and
downgrade-procedure-logical.

*Downgrade Paths*

   * Downgrade is only supported between General Availability (GA)
     releases.

   * Downgrade from MySQL 5.7 to 5.6 is supported using the _logical
     downgrade_ method.

   * Downgrade that skips versions is not supported.  For example,
     downgrading directly from MySQL 5.7 to 5.5 is not supported.

   * Downgrade within a release series is supported.  For example,
     downgrading from MySQL 5.7.Z to 5.7.Y is supported.  Skipping a
     release is also supported.  For example, downgrading from MySQL
     5.7.Z to 5.7.X is supported.

*Before You Begin*

Before downgrading, the following steps are recommended:

   * Review the Release Notes
     (http://dev.mysql.com/doc/relnotes/mysql/5.7/en/) for the MySQL
     version you are downgrading from to ensure that there are no
     features or fixes that you really need.

   * Review downgrading-to-previous-series.  This section
     describes changes that may require action before or after
     downgrading.

     *Note*:

     The downgrade procedures described in the following sections assume
     you are downgrading with data files created or modified by the
     newer MySQL version.  However, if you did not modify your data
     after upgrading, downgrading using backups taken _before_ upgrading
     to the new MySQL version is recommended.  Many of the changes
     described in downgrading-to-previous-series that require
     action before or after downgrading are not applicable when
     downgrading using backups taken _before_ upgrading to the new MySQL
     version.

   * Always back up your current databases and log files before
     downgrading.  The backup should include the 'mysql' database, which
     contains the MySQL system tables.  See backup-methods.

   * Use of new features, new configuration options, or new
     configuration option values that are not supported by a previous
     release may cause downgrade errors or failures.  Before
     downgrading, it is recommended that you reverse changes resulting
     from the use of new features and remove configuration settings that
     are not supported by the release you are downgrading to.

   * If you use XA transactions with 'InnoDB', run 'XA RECOVER'
     before downgrading to check for uncommitted XA
     transactions.  If results are returned, either commit or rollback
     the XA transactions by issuing an 'XA COMMIT'.
     or 'XA ROLLBACK' statement.

*In-Place Downgrade*

In-place downgrade is supported for downgrades between GA releases
within the same release series.  Before proceeding, review
downgrade-before-you-begin.

*Note*:

For some Linux platforms, MySQL installation from RPM or Debian packages
includes systemd support for managing MySQL server startup and shutdown.
On these platforms, see 'mysqld_safe' is not installed.
In such cases, use systemd for server startup and shutdown instead of
the methods used in the following instructions.  See
using-systemd.

To perform an in-place downgrade:

  1. Review the changes described in
     downgrading-to-previous-series for steps to be performed before
     downgrading.

  2. Configure MySQL to perform a slow shutdown by setting
     'innodb_fast_shutdown' to '0'.  For example:

          mysql -u root -p --execute="SET GLOBAL innodb_fast_shutdown=0"

     With a slow shutdown, 'InnoDB' performs a full purge and change
     buffer merge before shutting down, which ensures that data files
     are fully prepared in case of file format differences between
     releases.

  3. Shut down the newer MySQL server.  For example:

          mysqladmin -u root -p shutdown

  4. After the slow shutdown, remove the 'InnoDB' redo log files (the
     'ib_logfile*' files) from the 'data' directory to avoid downgrade
     issues related to redo log file format changes that may have
     occurred between releases.

          rm ib_logfile*

  5. Downgrade the MySQL binaries or packages in-place by replacing the
     newer binaries or packages with the older ones.

  6. Start the older (downgraded) MySQL server, using the existing data
     directory.  For example:

          mysqld_safe --user=mysql --datadir=/PATH/TO/EXISTING-DATADIR

  7. Run 'mysql_upgrade'.  For example:

          mysql_upgrade -u root -p

     'mysql_upgrade' examines all tables in all
     databases for incompatibilities with the current version of MySQL,
     and attempts to repair the tables if problems are found.

  8. Shut down and restart the MySQL server to ensure that any changes
     made to the system tables take effect.  For example:

          mysqladmin -u root -p shutdown
          mysqld_safe --user=mysql --datadir=/PATH/TO/EXISTING-DATADIR

*Logical Downgrade*

Logical downgrades are supported for downgrades between releases within
the same release series and for downgrades to the previous release
level.  Only downgrades between General Availability (GA) releases are
supported.  Before proceeding, review
downgrade-before-you-begin.

*Note*:

For some Linux platforms, MySQL installation from RPM or Debian packages
includes systemd support for managing MySQL server startup and shutdown.
On these platforms, see 'mysqld_safe' is not installed.
In such cases, use systemd for server startup and shutdown instead of
the methods used in the following instructions.  See
using-systemd.

For MySQL APT, SLES, and Yum repository installations, only downgrades
to the previous release level are supported.  Where the instructions
call for initializing an older instance, use the package management
utility to remove MySQL 5.7 packages and install MySQL 5.6 packages.

To perform a logical downgrade:

  1. Review the changes described in
     downgrading-to-previous-series for steps to be performed before
     downgrading.

  2. Dump all databases.  For example:

          mysqldump -u root -p
            --add-drop-table --routines --events
            --all-databases --force > data-for-downgrade.sql

  3. Shut down the newer MySQL server.  For example:

          mysqladmin -u root -p shutdown

  4. Initialize an older MySQL instance, with a new data directory.  For
     example, to initialize a MySQL 5.6 instance, use
     'mysql_install_db'.:

          scripts/mysql_install_db --user=mysql

     *Note*:

     'mysql_install_db' is deprecated as of
     MySQL 5.7.6 because its functionality has been integrated into
     'mysqld'.

     To initialize a MySQL 5.7 instance, use 'mysqld'.
     with the '--initialize' or '--initialize-insecure' option.

          mysqld --initialize --user=mysql

  5. Start the older MySQL server, using the new data directory.  For
     example:

          mysqld_safe --user=mysql --datadir=/PATH/TO/NEW-DATADIR

  6. Load the dump file into the older MySQL server.  For example:

          mysql -u root -p --force < data-for-upgrade.sql

  7. Run 'mysql_upgrade'.  For example:

          mysql_upgrade -u root -p

     'mysql_upgrade' examines all tables in all
     databases for incompatibilities with the current version of MySQL,
     and attempts to repair the tables if problems are found.

  8. Shut down and restart the MySQL server to ensure that any changes
     made to the system tables take effect.  For example:

          mysqladmin -u root -p shutdown
          mysqld_safe --user=mysql --datadir=/PATH/TO/NEW-DATADIR

*Downgrade Troubleshooting*

If you downgrade from one release series to another, there may be
incompatibilities in table storage formats.  In this case, use
'mysqldump' to dump your tables before downgrading.  After
downgrading, reload the dump file using 'mysql' or
'mysqlimport' to re-create your tables.  For examples, see
copying-databases.

A typical symptom of a downward-incompatible table format change when
you downgrade is that you cannot open tables.  In that case, use the
following procedure:

  1. Stop the older MySQL server that you are downgrading to.

  2. Restart the newer MySQL server you are downgrading from.

  3. Dump any tables that were inaccessible to the older server by using
     'mysqldump' to create a dump file.

  4. Stop the newer MySQL server and restart the older one.

  5. Reload the dump file into the older server.  Your tables should be
     accessible.

2.11.2.1 Changes Affecting Downgrades from MySQL 5.7
....................................................

Before downgrading from MySQL 5.7, review the changes described in this
section.  Some changes may require action before or after downgrading.

   * downgrade-system-table-changes

   * downgrade-innodb-changes

   * downgrade-logging-changes

   * downgrade-sql-changes

*System Table Changes*

   * In MySQL 5.7.13, system table columns that store user@host string
     values were increased in length.  Before downgrading to a previous
     release, ensure that there are no user@host values that exceed the
     previous 77 character length limit, and perform the following
     'mysql' system table alterations:

          ALTER TABLE mysql.proc MODIFY definer char(77) CHARACTER SET utf8 COLLATE utf8_bin NOT NULL DEFAULT '';
          ALTER TABLE mysql.event MODIFY definer char(77) CHARACTER SET utf8 COLLATE utf8_bin NOT NULL DEFAULT '';
          ALTER TABLE mysql.tables_priv MODIFY Grantor char(77) COLLATE utf8_bin NOT NULL DEFAULT '';
          ALTER TABLE mysql.procs_priv MODIFY Grantor char(77) COLLATE utf8_bin NOT NULL DEFAULT '';

   * The maximum length of MySQL user names was increased from 16
     characters to 32 characters in MySQL 5.7.8.  Before downgrading to
     a previous release, ensure that there are no user names greater
     than 16 characters in length, and perform the following 'mysql'
     system table alterations:

          ALTER TABLE mysql.tables_priv MODIFY User char(16) NOT NULL default '';
          ALTER TABLE mysql.columns_priv MODIFY User char(16) NOT NULL default '';
          ALTER TABLE mysql.user MODIFY User char(16) NOT NULL default '';
          ALTER TABLE mysql.db MODIFY User char(16) NOT NULL default '';
          ALTER TABLE mysql.procs_priv MODIFY User char(16) binary DEFAULT '' NOT NULL;

   * The 'Password' column of the 'mysql.user' table was removed in
     MySQL 5.7.6.  All credentials are stored in the
     'authentication_string' column, including those formerly stored in
     the 'Password' column.  To make the 'mysql.user' table compatible
     with previous releases, perform the following alterations before
     downgrading:

          ALTER TABLE mysql.user ADD Password char(41) character set latin1
            collate latin1_bin NOT NULL default '' AFTER user;
          UPDATE mysql.user SET password = authentication_string WHERE
            LENGTH(authentication_string) = 41 AND plugin = 'mysql_native_password';
          UPDATE mysql.user SET authentication_string = '' WHERE
            LENGTH(authentication_string) = 41 AND plugin = 'mysql_native_password';

   * The 'help_*' and 'time_zone*' system tables changed from 'MyISAM'
     to 'InnoDB' in MySQL 5.7.5.  Before downgrading to a previous
     release, change each affected table back to 'MyISAM' by running the
     following statements:

          ALTER TABLE mysql.help_category ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.help_keyword ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.help_relation ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.help_topic ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.time_zone ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.time_zone_leap_second ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.time_zone_name ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.time_zone_transition  ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.time_zone_transition_type ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;

   * The 'plugin' and 'servers' system tables changed from 'MyISAM' to
     'InnoDB' in MySQL 5.7.6.  Before downgrading to a previous release,
     change each affected table back to 'MyISAM' by running the
     following statements:

          ALTER TABLE mysql.plugin ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;
          ALTER TABLE mysql.servers ENGINE='MyISAM' STATS_PERSISTENT=DEFAULT;

   * The definition of the 'plugin' column in the 'mysql.user' table
     differs in MySQL 5.7.  Before downgrading to a MySQL 5.6 server for
     versions 5.6.23 and higher, alter the 'plugin' column definition
     using this statement:

          ALTER TABLE mysql.user MODIFY plugin CHAR(64) COLLATE utf8_bin
            DEFAULT 'mysql_native_password';

     Before downgrading to a MySQL 5.6.22 server or older, alter the
     'plugin' column definition using this statement:

          ALTER TABLE mysql.user MODIFY plugin CHAR(64) COLLATE utf8_bin DEFAULT '';

   * As of MySQL 5.7.7, the 'sys' schema is installed by default during
     data directory installation.  Before downgrading to a previous
     version, it is recommended that you drop the 'sys' schema:

          DROP DATABASE sys;

     If you are downgrading to a release that includes the 'sys' schema,
     see 'mysql_upgrade' recreates the 'sys' schema in
     a compatible form.  The 'sys' schema is not included in MySQL 5.6.

*InnoDB Changes*

   * As of MySQL 5.7.5, the 'FIL_PAGE_FLUSH_LSN' field, written to the
     first page of each 'InnoDB' system tablespace file and to 'InnoDB'
     undo tablespace files, is only written to the first file of the
     'InnoDB' system tablespace (page number 0:0).  As a result, if you
     have a multiple-file system tablespace and decide to downgrade from
     MySQL 5.7 to MySQL 5.6, you may encounter an invalid message on
     MySQL 5.6 startup stating that 'the log sequence numbers X and Y in
     ibdata files do not match the log sequence number Y in the
     ib_logfiles'.  If you encounter this message, restart MySQL 5.6.
     The invalid message should no longer appear.

   * To simplify 'InnoDB' tablespace discovery during crash recovery,
     new redo log record types were introduced in MySQL 5.7.5.  This
     enhancement changes the redo log format.  Before performing an
     in-place downgrade from MySQL 5.7.5 or later, perform a clean
     shutdown using an 'innodb_fast_shutdown' setting of '0' or '1'.  A
     slow shutdown using 'innodb_fast_shutdown=0' is a recommended step
     in downgrade-procedure-inplace.

   * MySQL 5.7.8 and 5.7.9 undo logs could contain insufficient
     information about spatial columns (Bug #21508582).  Before
     performing an in-place downgrade from MySQL 5.7.10 or higher to
     MySQL 5.7.9 or earlier, perform a slow shutdown using
     'innodb_fast_shutdown=0' to clear the undo logs.  A slow shutdown
     using 'innodb_fast_shutdown=0' is a recommended step in
     downgrade-procedure-inplace.

   * MySQL 5.7.8 undo logs could contain insufficient information about
     virtual columns and virtual column indexes (Bug #21869656).  Before
     performing an in-place downgrade from MySQL 5.7.9 or later to MySQL
     5.7.8 or earlier, perform a slow shutdown using
     'innodb_fast_shutdown=0' to clear the undo logs.  A slow shutdown
     using 'innodb_fast_shutdown=0' is a recommended step in
     downgrade-procedure-inplace.

   * As of MySQL 5.7.9, the redo log header of the first redo log file
     ('ib_logfile0') includes a format version identifier and a text
     string that identifies the MySQL version that created the redo log
     files.  This enhancement changes the redo log format.  To prevent
     older versions of MySQL from starting on redo log files created in
     MySQL 5.7.9 or later, the checksum for redo log checkpoint pages
     was changed.  As a result, you must perform a slow shutdown of
     MySQL (using innodb_fast_shutdown=0) and remove the redo log files
     (the 'ib_logfile*' files) before performing an in-place downgrade.
     A slow shutdown using 'innodb_fast_shutdown=0' and removing the
     redo log files are recommended steps in
     downgrade-procedure-inplace.

*Logging Changes*

   * Support for sending the server error log to 'syslog' in MySQL 5.7.5
     and up differs from older versions.  If you use 'syslog' and
     downgrade to a version older than 5.7.5, you must stop using the
     relevant 'mysqld' system variables and use the
     corresponding 'mysqld_safe' command options
     instead.  Suppose that you use 'syslog' by setting these system
     variables in the '[mysqld]' group of an option file:

          [mysqld]
          log_syslog=ON
          log_syslog_tag=mytag

     To downgrade, remove those settings and add option settings in the
     '[mysqld_safe]' option file group:

          [mysqld_safe]
          syslog
          syslog-tag=mytag

     'syslog'-related system variables that have no corresponding
     'mysqld_safe' option cannot be used after a
     downgrade.

*SQL Changes*

   * A trigger can have triggers for different combinations of trigger
     event (see 'INSERT', 'UPDATE',
     'DELETE') and action time ('BEFORE', 'AFTER'), but before
     MySQL 5.7.2 cannot have multiple triggers that have the same
     trigger event and action time.  MySQL 5.7.2 lifts this limitation
     and multiple triggers are permitted.  This change has implications
     for downgrades.

     If you downgrade a server that supports multiple triggers to an
     older version that does not, the downgrade has these effects:

        * For each table that has triggers, all trigger definitions
          remain in the '.TRG' file for the table.  However, if there
          are multiple triggers with the same trigger event and action
          time, the server executes only one of them when the trigger
          event occurs.  For information about '.TRG' files, see Table
          Trigger Storage
          (http://dev.mysql.com/doc/internals/en/sp-storage.html#sp-storage-trigger).

        * If triggers for the table are added or dropped subsequent to
          the downgrade, the server rewrites the table's '.TRG' file.
          The rewritten file retains only one trigger per combination of
          trigger event and action time; the others are lost.

     To avoid these problems, modify your triggers before downgrading.
     For each table that has multiple triggers per combination of
     trigger event and action time, convert each such set of triggers to
     a single trigger as follows:

       1. For each trigger, create a stored routine that contains all
          the code in the trigger.  Values accessed using 'NEW' and
          'OLD' can be passed to the routine using parameters.  If the
          trigger needs a single result value from the code, you can put
          the code in a stored function and have the function return the
          value.  If the trigger needs multiple result values from the
          code, you can put the code in a stored procedure and return
          the values using 'OUT' parameters.

       2. Drop all triggers for the table.

       3. Create one new trigger for the table that invokes the stored
          routines just created.  The effect for this trigger is thus
          the same as the multiple triggers it replaces.

2.11.3 Rebuilding or Repairing Tables or Indexes
------------------------------------------------

This section describes how to rebuild or repair tables or indexes, which
may be necessitated by:

   * Changes to how MySQL handles data types or character sets.  For
     example, an error in a collation might have been corrected,
     necessitating a table rebuild to update the indexes for character
     columns that use the collation.

   * Required table repairs or upgrades reported by 'CHECK TABLE',
     see 'mysqlcheck', or
     'mysql_upgrade'.

Methods for rebuilding a table include:

   * rebuilding-tables-dump-reload

   * rebuilding-tables-alter-table

   * rebuilding-tables-repair-table

*Dump and Reload Method*

If you are rebuilding tables because a different version of MySQL will
not handle them after a binary (in-place) upgrade or downgrade, you must
use the dump-and-reload method.  Dump the tables _before_ upgrading or
downgrading using your original version of MySQL. Then reload the tables
_after_ upgrading or downgrading.

If you use the dump-and-reload method of rebuilding tables only for the
purpose of rebuilding indexes, you can perform the dump either before or
after upgrading or downgrading.  Reloading still must be done afterward.

If you need to rebuild an 'InnoDB' table because a 'CHECK TABLE'
operation indicates that a table upgrade is required, use
'mysqldump' to create a dump file and 'mysql'
to reload the file.  If the 'CHECK TABLE'.
operation indicates that there is a corruption or causes 'InnoDB' to
fail, refer to forcing-innodb-recovery for information about
using the 'innodb_force_recovery' option to restart 'InnoDB'.  To
understand the type of problem that 'CHECK TABLE'.
may be encountering, refer to the 'InnoDB' notes in check-table.

To rebuild a table by dumping and reloading it, use 'mysqldump'
to create a dump file and 'mysql' to reload the
file:

     mysqldump DB_NAME t1 > dump.sql
     mysql DB_NAME < dump.sql

To rebuild all the tables in a single database, specify the database
name without any following table name:

     mysqldump DB_NAME > dump.sql
     mysql DB_NAME < dump.sql

To rebuild all tables in all databases, use the '--all-databases'
option:

     mysqldump --all-databases > dump.sql
     mysql < dump.sql

*ALTER TABLE Method*

To rebuild a table with 'ALTER TABLE', use a 'null'
alteration; that is, an 'ALTER TABLE' statement that
'changes' the table to use the storage engine that it already has.  For
example, if 't1' is an 'InnoDB' table, use this statement:

     ALTER TABLE t1 ENGINE = InnoDB;

If you are not sure which storage engine to specify in the 'ALTER TABLE'
statement, use 'SHOW CREATE TABLE'
to display the table definition.

*REPAIR TABLE Method*

The 'REPAIR TABLE' method is only applicable to
'MyISAM', 'ARCHIVE', and 'CSV' tables.

You can use 'REPAIR TABLE' if the table checking
operation indicates that there is a corruption or that an upgrade is
required.  For example, to repair a 'MyISAM' table, use this statement:

     REPAIR TABLE t1;

'mysqlcheck --repair' provides command-line access to
the 'REPAIR TABLE' statement.  This can be a more
convenient means of repairing tables because you can use the
'--databases' or '--all-databases' option to repair all tables in
specific databases or all databases, respectively:

     mysqlcheck --repair --databases DB_NAME ...
     mysqlcheck --repair --all-databases

2.11.4 Copying MySQL Databases to Another Machine
-------------------------------------------------

In cases where you need to transfer databases between different
architectures, you can use 'mysqldump' to create a
file containing SQL statements.  You can then transfer the file to the
other machine and feed it as input to the 'mysql' client.

Use 'mysqldump --help' to see what options are
available.

The easiest (although not the fastest) way to move a database between
two machines is to run the following commands on the machine on which
the database is located:

     mysqladmin -h 'OTHER_HOSTNAME' create DB_NAME
     mysqldump DB_NAME | mysql -h 'OTHER_HOSTNAME' DB_NAME

If you want to copy a database from a remote machine over a slow
network, you can use these commands:

     mysqladmin create DB_NAME
     mysqldump -h 'OTHER_HOSTNAME' --compress DB_NAME | mysql DB_NAME

You can also store the dump in a file, transfer the file to the target
machine, and then load the file into the database there.  For example,
you can dump a database to a compressed file on the source machine like
this:

     mysqldump --quick DB_NAME | gzip > DB_NAME.gz

Transfer the file containing the database contents to the target machine
and run these commands there:

     mysqladmin create DB_NAME
     gunzip < DB_NAME.gz | mysql DB_NAME

You can also use 'mysqldump' and 'mysqlimport'
to transfer the database.  For large tables, this is much
faster than simply using 'mysqldump'.  In the following
commands, DUMPDIR represents the full path name of the directory you use
to store the output from 'mysqldump'.

First, create the directory for the output files and dump the database:

     mkdir DUMPDIR
     mysqldump --tab=DUMPDIR DB_NAME

Then transfer the files in the DUMPDIR directory to some corresponding
directory on the target machine and load the files into MySQL there:

     mysqladmin create DB_NAME           # create database
     cat DUMPDIR/*.sql | mysql DB_NAME   # create tables in database
     mysqlimport DB_NAME DUMPDIR/*.txt   # load data into tables

Do not forget to copy the 'mysql' database because that is where the
grant tables are stored.  You might have to run commands as the MySQL
'root' user on the new machine until you have the 'mysql' database in
place.

After you import the 'mysql' database on the new machine, execute
'mysqladmin flush-privileges' so that the server reloads
the grant table information.

*Note*:

You can copy the '.frm', '.MYI', and '.MYD' files for 'MyISAM' tables
between different architectures that support the same floating-point
format.  (MySQL takes care of any byte-swapping issues.)  See
myisam-storage-engine.

2.12 Perl Installation Notes
============================

The Perl 'DBI' module provides a generic interface for database access.
You can write a 'DBI' script that works with many different database
engines without change.  To use 'DBI', you must install the 'DBI'
module, as well as a DataBase Driver (DBD) module for each type of
database server you want to access.  For MySQL, this driver is the
'DBD::mysql' module.

*Note*:

Perl support is not included with MySQL distributions.  You can obtain
the necessary modules from <http://search.cpan.org> for Unix, or by
using the ActiveState 'ppm' program on Windows.  The following sections
describe how to do this.

The 'DBI'/'DBD' interface requires Perl 5.6.0, and 5.6.1 or later is
preferred.  DBI _does not work_ if you have an older version of Perl.
You should use 'DBD::mysql' 4.009 or higher.  Although earlier versions
are available, they do not support the full functionality of MySQL 5.7.

2.12.1 Installing Perl on Unix
------------------------------

MySQL Perl support requires that you have installed MySQL client
programming support (libraries and header files).  Most installation
methods install the necessary files.  If you install MySQL from RPM
files on Linux, be sure to install the developer RPM as well.  The
client programs are in the client RPM, but client programming support is
in the developer RPM.

The files you need for Perl support can be obtained from the CPAN
(Comprehensive Perl Archive Network) at <http://search.cpan.org>.

The easiest way to install Perl modules on Unix is to use the 'CPAN'
module.  For example:

     shell> perl -MCPAN -e shell
     cpan> install DBI
     cpan> install DBD::mysql

The 'DBD::mysql' installation runs a number of tests.  These tests
attempt to connect to the local MySQL server using the default user name
and password.  (The default user name is your login name on Unix, and
'ODBC' on Windows.  The default password is 'no password.') If you
cannot connect to the server with those values (for example, if your
account has a password), the tests fail.  You can use 'force install
DBD::mysql' to ignore the failed tests.

'DBI' requires the 'Data::Dumper' module.  It may be installed; if not,
you should install it before installing 'DBI'.

It is also possible to download the module distributions in the form of
compressed 'tar' archives and build the modules manually.  For example,
to unpack and build a DBI distribution, use a procedure such as this:

  1. Unpack the distribution into the current directory:

          shell> gunzip < DBI-VERSION.tar.gz | tar xvf -

     This command creates a directory named 'DBI-VERSION'.

  2. Change location into the top-level directory of the unpacked
     distribution:

          shell> cd DBI-VERSION

  3. Build the distribution and compile everything:

          shell> perl Makefile.PL
          shell> make
          shell> make test
          shell> make install

The 'make test' command is important because it verifies that the module
is working.  Note that when you run that command during the 'DBD::mysql'
installation to exercise the interface code, the MySQL server must be
running or the test fails.

It is a good idea to rebuild and reinstall the 'DBD::mysql' distribution
whenever you install a new release of MySQL. This ensures that the
latest versions of the MySQL client libraries are installed correctly.

If you do not have access rights to install Perl modules in the system
directory or if you want to install local Perl modules, the following
reference may be useful:
<http://learn.perl.org/faq/perlfaq8.html#How-do-I-keep-my-own-module-library-directory->

2.12.2 Installing ActiveState Perl on Windows
---------------------------------------------

On Windows, you should do the following to install the MySQL 'DBD'
module with ActiveState Perl:

  1. Get ActiveState Perl from
     <http://www.activestate.com/Products/ActivePerl/> and install it.

  2. Open a console window.

  3. If necessary, set the 'HTTP_proxy' variable.  For example, you
     might try a setting like this:

          C:\> set HTTP_proxy=my.proxy.com:3128

  4. Start the PPM program:

          C:\> C:\perl\bin\ppm.pl

  5. If you have not previously done so, install 'DBI':

          ppm> install DBI

  6. If this succeeds, run the following command:

          ppm> install DBD-mysql

This procedure should work with ActiveState Perl 5.6 or higher.

If you cannot get the procedure to work, you should install the ODBC
driver instead and connect to the MySQL server through ODBC:

     use DBI;
     $dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
       die "Got error $DBI::errstr when connecting to $dsn\n";

2.12.3 Problems Using the Perl DBI/DBD Interface
------------------------------------------------

If Perl reports that it cannot find the '../mysql/mysql.so' module, the
problem is probably that Perl cannot locate the 'libmysqlclient.so'
shared library.  You should be able to fix this problem by one of the
following methods:

   * Copy 'libmysqlclient.so' to the directory where your other shared
     libraries are located (probably '/usr/lib' or '/lib').

   * Modify the '-L' options used to compile 'DBD::mysql' to reflect the
     actual location of 'libmysqlclient.so'.

   * On Linux, you can add the path name of the directory where
     'libmysqlclient.so' is located to the '/etc/ld.so.conf' file.

   *
     Add the path name of the directory where 'libmysqlclient.so' is
     located to the 'LD_RUN_PATH' environment variable.  Some systems
     use 'LD_LIBRARY_PATH' instead.

Note that you may also need to modify the '-L' options if there are
other libraries that the linker fails to find.  For example, if the
linker cannot find 'libc' because it is in '/lib' and the link command
specifies '-L/usr/lib', change the '-L' option to '-L/lib' or add
'-L/lib' to the existing link command.

If you get the following errors from 'DBD::mysql', you are probably
using 'gcc' (or using an old binary compiled with 'gcc'):

     /usr/bin/perl: can't resolve symbol '__moddi3'
     /usr/bin/perl: can't resolve symbol '__divdi3'

Add '-L/usr/lib/gcc-lib/... -lgcc' to the link command when the
'mysql.so' library gets built (check the output from 'make' for
'mysql.so' when you compile the Perl client).  The '-L' option should
specify the path name of the directory where 'libgcc.a' is located on
your system.

Another cause of this problem may be that Perl and MySQL are not both
compiled with 'gcc'.  In this case, you can solve the mismatch by
compiling both with 'gcc'.

3 Tutorial
**********

This chapter provides a tutorial introduction to MySQL by showing how to
use the 'mysql' client program to create and use a simple
database.  See 'mysql'. (sometimes referred to as the 'terminal
monitor' or just 'monitor') is an interactive program that enables you
to connect to a MySQL server, run queries, and view the results.
'mysql' may also be used in batch mode: you place your queries
in a file beforehand, then tell 'mysql' to execute the
contents of the file.  Both ways of using 'mysql' are
covered here.

To see a list of options provided by 'mysql', invoke it
with the '--help' option:

     shell> mysql --help

This chapter assumes that 'mysql' is installed on your
machine and that a MySQL server is available to which you can connect.
If this is not true, contact your MySQL administrator.  (If _you_ are
the administrator, you need to consult the relevant portions of this
manual, such as server-administration.)

This chapter describes the entire process of setting up and using a
database.  If you are interested only in accessing an existing database,
you may want to skip over the sections that describe how to create the
database and the tables it contains.

Because this chapter is tutorial in nature, many details are necessarily
omitted.  Consult the relevant sections of the manual for more
information on the topics covered here.

3.1 Connecting to and Disconnecting from the Server
===================================================

To connect to the server, you will usually need to provide a MySQL user
name when you invoke 'mysql' and, most likely, a password.
If the server runs on a machine other than the one where you log in, you
will also need to specify a host name.  Contact your administrator to
find out what connection parameters you should use to connect (that is,
what host, user name, and password to use).  Once you know the proper
parameters, you should be able to connect like this:

     shell> mysql -h HOST -u USER -p
     Enter password: ********

HOST and USER represent the host name where your MySQL server is running
and the user name of your MySQL account.  Substitute appropriate values
for your setup.  The '********' represents your password; enter it when
'mysql' displays the 'Enter password:' prompt.

If that works, you should see some introductory information followed by
a 'mysql>' prompt:

     shell> mysql -h HOST -u USER -p
     Enter password: ********
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 25338 to server version: 5.7.23-standard

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql>

The 'mysql>' prompt tells you that 'mysql' is ready for
you to enter SQL statements.

If you are logging in on the same machine that MySQL is running on, you
can omit the host, and simply use the following:

     shell> mysql -u USER -p

If, when you attempt to log in, you get an error message such as 'ERROR
2002 (HY000): Can't connect to local MySQL server through socket
'/tmp/mysql.sock' (2)', it means that the MySQL server daemon (Unix) or
service (Windows) is not running.  Consult the administrator or see the
section of installing that is appropriate to your operating
system.

For help with other problems often encountered when trying to log in,
see common-errors.

Some MySQL installations permit users to connect as the anonymous
(unnamed) user to the server running on the local host.  If this is the
case on your machine, you should be able to connect to that server by
invoking 'mysql' without any options:

     shell> mysql

After you have connected successfully, you can disconnect any time by
typing 'QUIT' (or '\q') at the 'mysql>' prompt:

     mysql> QUIT
     Bye

On Unix, you can also disconnect by pressing Control+D.

Most examples in the following sections assume that you are connected to
the server.  They indicate this by the 'mysql>' prompt.

3.2 Entering Queries
====================

Make sure that you are connected to the server, as discussed in the
previous section.  Doing so does not in itself select any database to
work with, but that is okay.  At this point, it is more important to
find out a little about how to issue queries than to jump right in
creating tables, loading data into them, and retrieving data from them.
This section describes the basic principles of entering queries, using
several queries you can try out to familiarize yourself with how
'mysql' works.

Here is a simple query that asks the server to tell you its version
number and the current date.  Type it in as shown here following the
'mysql>' prompt and press Enter:

     mysql> SELECT VERSION(), CURRENT_DATE;
     +--------------+--------------+
     | VERSION()    | CURRENT_DATE |
     +--------------+--------------+
     | 5.7.1-m4-log | 2012-12-25   |
     +--------------+--------------+
     1 row in set (0.01 sec)
     mysql>

This query illustrates several things about 'mysql'.:

   * A query normally consists of an SQL statement followed by a
     semicolon.  (There are some exceptions where a semicolon may be
     omitted.  'QUIT', mentioned earlier, is one of them.  We'll get to
     others later.)

   * When you issue a query, see 'mysql' sends it to the
     server for execution and displays the results, then prints another
     'mysql>' prompt to indicate that it is ready for another query.

   * 'mysql' displays query output in tabular form (rows
     and columns).  The first row contains labels for the columns.  The
     rows following are the query results.  Normally, column labels are
     the names of the columns you fetch from database tables.  If you're
     retrieving the value of an expression rather than a table column
     (as in the example just shown), see 'mysql' labels the
     column using the expression itself.

   * 'mysql' shows how many rows were returned and how
     long the query took to execute, which gives you a rough idea of
     server performance.  These values are imprecise because they
     represent wall clock time (not CPU or machine time), and because
     they are affected by factors such as server load and network
     latency.  (For brevity, the 'rows in set' line is sometimes not
     shown in the remaining examples in this chapter.)

Keywords may be entered in any lettercase.  The following queries are
equivalent:

     mysql> SELECT VERSION(), CURRENT_DATE;
     mysql> select version(), current_date;
     mysql> SeLeCt vErSiOn(), current_DATE;

Here is another query.  It demonstrates that you can use 'mysql'
as a simple calculator:

     mysql> SELECT SIN(PI()/4), (4+1)*5;
     +------------------+---------+
     | SIN(PI()/4)      | (4+1)*5 |
     +------------------+---------+
     | 0.70710678118655 |      25 |
     +------------------+---------+
     1 row in set (0.02 sec)

The queries shown thus far have been relatively short, single-line
statements.  You can even enter multiple statements on a single line.
Just end each one with a semicolon:

     mysql> SELECT VERSION(); SELECT NOW();
     +------------------+
     | VERSION()        |
     +------------------+
     | 5.7.10-ndb-7.5.1 |
     +------------------+
     1 row in set (0.00 sec)

     +---------------------+
     | NOW()               |
     +---------------------+
     | 2016-01-29 18:02:55 |
     +---------------------+
     1 row in set (0.00 sec)

A query need not be given all on a single line, so lengthy queries that
require several lines are not a problem.  See 'mysql'.
determines where your statement ends by looking for the terminating
semicolon, not by looking for the end of the input line.  (In other
words, see 'mysql' accepts free-format input: it collects
input lines but does not execute them until it sees the semicolon.)

Here is a simple multiple-line statement:

     mysql> SELECT
         -> USER()
         -> ,
         -> CURRENT_DATE;
     +---------------+--------------+
     | USER()        | CURRENT_DATE |
     +---------------+--------------+
     | jon@localhost | 2010-08-06   |
     +---------------+--------------+

In this example, notice how the prompt changes from 'mysql>' to '->'
after you enter the first line of a multiple-line query.  This is how
'mysql' indicates that it has not yet seen a complete
statement and is waiting for the rest.  The prompt is your friend,
because it provides valuable feedback.  If you use that feedback, you
can always be aware of what 'mysql' is waiting for.

If you decide you do not want to execute a query that you are in the
process of entering, cancel it by typing '\c':

     mysql> SELECT
         -> USER()
         -> \c
     mysql>

Here, too, notice the prompt.  It switches back to 'mysql>' after you
type '\c', providing feedback to indicate that 'mysql' is
ready for a new query.

The following table shows each of the prompts you may see and summarizes
what they mean about the state that 'mysql' is in.

Prompt  Meaning

'mysql>'Ready for new query

'->'    Waiting for next line of multiple-line query

''>'    Waiting for next line, waiting for completion of a
        string that began with a single quote (''')

'">'    Waiting for next line, waiting for completion of a
        string that began with a double quote ('"')

'`>'    Waiting for next line, waiting for completion of an
        identifier that began with a backtick ('`')

'/*>'   Waiting for next line, waiting for completion of a
        comment that began with '/*'

Multiple-line statements commonly occur by accident when you intend to
issue a query on a single line, but forget the terminating semicolon.
In this case, see 'mysql' waits for more input:

     mysql> SELECT USER()
         ->

If this happens to you (you think you've entered a statement but the
only response is a '->' prompt), most likely 'mysql' is
waiting for the semicolon.  If you don't notice what the prompt is
telling you, you might sit there for a while before realizing what you
need to do.  Enter a semicolon to complete the statement, and
'mysql' executes it:

     mysql> SELECT USER()
         -> ;
     +---------------+
     | USER()        |
     +---------------+
     | jon@localhost |
     +---------------+

The ''>' and '">' prompts occur during string collection (another way of
saying that MySQL is waiting for completion of a string).  In MySQL, you
can write strings surrounded by either ''' or '"' characters (for
example, ''hello'' or '"goodbye"'), and 'mysql' lets you
enter strings that span multiple lines.  When you see a ''>' or '">'
prompt, it means that you have entered a line containing a string that
begins with a ''' or '"' quote character, but have not yet entered the
matching quote that terminates the string.  This often indicates that
you have inadvertently left out a quote character.  For example:

     mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
         '>

If you enter this 'SELECT' statement, then press 'Enter'
and wait for the result, nothing happens.  Instead of wondering why this
query takes so long, notice the clue provided by the ''>' prompt.  It
tells you that 'mysql' expects to see the rest of an
unterminated string.  (Do you see the error in the statement?  The
string ''Smith' is missing the second single quotation mark.)

At this point, what do you do?  The simplest thing is to cancel the
query.  However, you cannot just type '\c' in this case, because
'mysql' interprets it as part of the string that it is
collecting.  Instead, enter the closing quote character (so
'mysql' knows you've finished the string), then type '\c':

     mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
         '> '\c
     mysql>

The prompt changes back to 'mysql>', indicating that 'mysql'
is ready for a new query.

The '`>' prompt is similar to the ''>' and '">' prompts, but indicates
that you have begun but not completed a backtick-quoted identifier.

It is important to know what the ''>', '">', and '`>' prompts signify,
because if you mistakenly enter an unterminated string, any further
lines you type appear to be ignored by 'mysql'.--including
a line containing 'QUIT'.  This can be quite confusing, especially if
you do not know that you need to supply the terminating quote before you
can cancel the current query.

3.3 Creating and Using a Database
=================================

Once you know how to enter SQL statements, you are ready to access a
database.

Suppose that you have several pets in your home (your menagerie) and you
would like to keep track of various types of information about them.
You can do so by creating tables to hold your data and loading them with
the desired information.  Then you can answer different sorts of
questions about your animals by retrieving data from the tables.  This
section shows you how to perform the following operations:

   * Create a database

   * Create a table

   * Load data into the table

   * Retrieve data from the table in various ways

   * Use multiple tables

The menagerie database is simple (deliberately), but it is not difficult
to think of real-world situations in which a similar type of database
might be used.  For example, a database like this could be used by a
farmer to keep track of livestock, or by a veterinarian to keep track of
patient records.  A menagerie distribution containing some of the
queries and sample data used in the following sections can be obtained
from the MySQL website.  It is available in both compressed 'tar' file
and Zip formats at <http://dev.mysql.com/doc/>.

Use the 'SHOW' statement to find out what databases
currently exist on the server:

     mysql> SHOW DATABASES;
     +----------+
     | Database |
     +----------+
     | mysql    |
     | test     |
     | tmp      |
     +----------+

The 'mysql' database describes user access privileges.  The 'test'
database often is available as a workspace for users to try things out.

The list of databases displayed by the statement may be different on
your machine; see 'SHOW DATABASES' does not show
databases that you have no privileges for if you do not have the
'SHOW DATABASES' privilege.  See
show-databases.

If the 'test' database exists, try to access it:

     mysql> USE test
     Database changed

See 'USE', like 'QUIT', does not require a semicolon.  (You can
terminate such statements with a semicolon if you like; it does no
harm.)  The 'USE' statement is special in another way, too:
it must be given on a single line.

You can use the 'test' database (if you have access to it) for the
examples that follow, but anything you create in that database can be
removed by anyone else with access to it.  For this reason, you should
probably ask your MySQL administrator for permission to use a database
of your own.  Suppose that you want to call yours 'menagerie'.  The
administrator needs to execute a statement like this:

     mysql> GRANT ALL ON menagerie.* TO 'your_mysql_name'@'your_client_host';

where 'your_mysql_name' is the MySQL user name assigned to you and
'your_client_host' is the host from which you connect to the server.

3.3.1 Creating and Selecting a Database
---------------------------------------

If the administrator creates your database for you when setting up your
permissions, you can begin using it.  Otherwise, you need to create it
yourself:

     mysql> CREATE DATABASE menagerie;

Under Unix, database names are case-sensitive (unlike SQL keywords), so
you must always refer to your database as 'menagerie', not as
'Menagerie', 'MENAGERIE', or some other variant.  This is also true for
table names.  (Under Windows, this restriction does not apply, although
you must refer to databases and tables using the same lettercase
throughout a given query.  However, for a variety of reasons, the
recommended best practice is always to use the same lettercase that was
used when the database was created.)

*Note*:

If you get an error such as 'ERROR 1044 (42000): Access denied for user
'micah'@'localhost' to database 'menagerie'' when attempting to create a
database, this means that your user account does not have the necessary
privileges to do so.  Discuss this with the administrator or see
privilege-system.

Creating a database does not select it for use; you must do that
explicitly.  To make 'menagerie' the current database, use this
statement:

     mysql> USE menagerie
     Database changed

Your database needs to be created only once, but you must select it for
use each time you begin a 'mysql' session.  You can do
this by issuing a 'USE' statement as shown in the example.
Alternatively, you can select the database on the command line when you
invoke 'mysql'.  Just specify its name after any connection
parameters that you might need to provide.  For example:

     shell> mysql -h HOST -u USER -p menagerie
     Enter password: ********

*Important*:

'menagerie' in the command just shown is *not* your password.  If you
want to supply your password on the command line after the '-p' option,
you must do so with no intervening space (for example, as '-pPASSWORD',
not as '-p PASSWORD').  However, putting your password on the command
line is not recommended, because doing so exposes it to snooping by
other users logged in on your machine.

*Note*:

You can see at any time which database is currently selected using
'SELECT'. 'DATABASE()'.

3.3.2 Creating a Table
----------------------

Creating the database is the easy part, but at this point it is empty,
as 'SHOW TABLES' tells you:

     mysql> SHOW TABLES;
     Empty set (0.00 sec)

The harder part is deciding what the structure of your database should
be: what tables you need and what columns should be in each of them.

You want a table that contains a record for each of your pets.  This can
be called the 'pet' table, and it should contain, as a bare minimum,
each animal's name.  Because the name by itself is not very interesting,
the table should contain other information.  For example, if more than
one person in your family keeps pets, you might want to list each
animal's owner.  You might also want to record some basic descriptive
information such as species and sex.

How about age?  That might be of interest, but it is not a good thing to
store in a database.  Age changes as time passes, which means you'd have
to update your records often.  Instead, it is better to store a fixed
value such as date of birth.  Then, whenever you need age, you can
calculate it as the difference between the current date and the birth
date.  MySQL provides functions for doing date arithmetic, so this is
not difficult.  Storing birth date rather than age has other advantages,
too:

   * You can use the database for tasks such as generating reminders for
     upcoming pet birthdays.  (If you think this type of query is
     somewhat silly, note that it is the same question you might ask in
     the context of a business database to identify clients to whom you
     need to send out birthday greetings in the current week or month,
     for that computer-assisted personal touch.)

   * You can calculate age in relation to dates other than the current
     date.  For example, if you store death date in the database, you
     can easily calculate how old a pet was when it died.

You can probably think of other types of information that would be
useful in the 'pet' table, but the ones identified so far are
sufficient: name, owner, species, sex, birth, and death.

Use a 'CREATE TABLE' statement to specify the
layout of your table:

     mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
         -> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);

'VARCHAR' is a good choice for the 'name', 'owner', and
'species' columns because the column values vary in length.  The lengths
in those column definitions need not all be the same, and need not be
'20'.  You can normally pick any length from '1' to '65535', whatever
seems most reasonable to you.  If you make a poor choice and it turns
out later that you need a longer field, MySQL provides an 'ALTER TABLE'
statement.

Several types of values can be chosen to represent sex in animal
records, such as ''m'' and ''f'', or perhaps ''male'' and ''female''.
It is simplest to use the single characters ''m'' and ''f''.

The use of the 'DATE' data type for the 'birth' and
'death' columns is a fairly obvious choice.

Once you have created a table, see 'SHOW TABLES' should
produce some output:

     mysql> SHOW TABLES;
     +---------------------+
     | Tables in menagerie |
     +---------------------+
     | pet                 |
     +---------------------+

To verify that your table was created the way you expected, use a
'DESCRIBE' statement:

     mysql> DESCRIBE pet;
     +---------+-------------+------+-----+---------+-------+
     | Field   | Type        | Null | Key | Default | Extra |
     +---------+-------------+------+-----+---------+-------+
     | name    | varchar(20) | YES  |     | NULL    |       |
     | owner   | varchar(20) | YES  |     | NULL    |       |
     | species | varchar(20) | YES  |     | NULL    |       |
     | sex     | char(1)     | YES  |     | NULL    |       |
     | birth   | date        | YES  |     | NULL    |       |
     | death   | date        | YES  |     | NULL    |       |
     +---------+-------------+------+-----+---------+-------+

You can use 'DESCRIBE' any time, for example, if you
forget the names of the columns in your table or what types they have.

For more information about MySQL data types, see data-types.

3.3.3 Loading Data into a Table
-------------------------------

After creating your table, you need to populate it.  The 'LOAD DATA'
and 'INSERT' statements are useful for
this.

Suppose that your pet records can be described as shown here.  (Observe
that MySQL expects dates in ''YYYY-MM-DD'' format; this may be different
from what you are used to.)

name    owner   species sex  birth          death

Fluffy  Harold  cat     f    1993-02-04

Claws   Gwen    cat     m    1994-03-17

Buffy   Harold  dog     f    1989-05-13

Fang    Benny   dog     m    1990-08-27

Bowser  Diane   dog     m    1979-08-31     1995-07-29

Chirpy  Gwen    bird    f    1998-09-11

WhistlerGwen    bird         1997-12-09

Slim    Benny   snake   m    1996-04-29

Because you are beginning with an empty table, an easy way to populate
it is to create a text file containing a row for each of your animals,
then load the contents of the file into the table with a single
statement.

You could create a text file 'pet.txt' containing one record per line,
with values separated by tabs, and given in the order in which the
columns were listed in the 'CREATE TABLE'.
statement.  For missing values (such as unknown sexes or death dates for
animals that are still living), you can use 'NULL' values.  To represent
these in your text file, use '\N' (backslash, capital-N). For example,
the record for Whistler the bird would look like this (where the
whitespace between values is a single tab character):

     Whistler        Gwen    bird    \N      1997-12-09      \N

To load the text file 'pet.txt' into the 'pet' table, use this
statement:

     mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet;

If you created the file on Windows with an editor that uses '\r\n' as a
line terminator, you should use this statement instead:

     mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet
         -> LINES TERMINATED BY '\r\n';

(On an Apple machine running OS X, you would likely want to use 'LINES
TERMINATED BY '\r''.)

You can specify the column value separator and end of line marker
explicitly in the 'LOAD DATA' statement if you wish,
but the defaults are tab and linefeed.  These are sufficient for the
statement to read the file 'pet.txt' properly.

If the statement fails, it is likely that your MySQL installation does
not have local file capability enabled by default.  See
load-data-local, for information on how to change this.

When you want to add new records one at a time, the 'INSERT'
statement is useful.  In its simplest form, you supply values
for each column, in the order in which the columns were listed in the
'CREATE TABLE' statement.  Suppose that Diane gets
a new hamster named 'Puffball.' You could add a new record using an
'INSERT' statement like this:

     mysql> INSERT INTO pet
         -> VALUES ('Puffball','Diane','hamster','f','1999-03-30',NULL);

String and date values are specified as quoted strings here.  Also, with
'INSERT', you can insert 'NULL' directly to represent a
missing value.  You do not use '\N' like you do with 'LOAD DATA'.

From this example, you should be able to see that there would be a lot
more typing involved to load your records initially using several
'INSERT' statements rather than a single 'LOAD DATA'
statement.

3.3.4 Retrieving Information from a Table
-----------------------------------------

The 'SELECT' statement is used to pull information from a
table.  The general form of the statement is:

     SELECT WHAT_TO_SELECT
     FROM WHICH_TABLE
     WHERE CONDITIONS_TO_SATISFY;

WHAT_TO_SELECT indicates what you want to see.  This can be a list of
columns, or '*' to indicate 'all columns.'  WHICH_TABLE indicates the
table from which you want to retrieve data.  The 'WHERE' clause is
optional.  If it is present, CONDITIONS_TO_SATISFY specifies one or more
conditions that rows must satisfy to qualify for retrieval.

3.3.4.1 Selecting All Data
..........................

The simplest form of 'SELECT' retrieves everything from a
table:

     mysql> SELECT * FROM pet;
     +----------+--------+---------+------+------------+------------+
     | name     | owner  | species | sex  | birth      | death      |
     +----------+--------+---------+------+------------+------------+
     | Fluffy   | Harold | cat     | f    | 1993-02-04 | NULL       |
     | Claws    | Gwen   | cat     | m    | 1994-03-17 | NULL       |
     | Buffy    | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Fang     | Benny  | dog     | m    | 1990-08-27 | NULL       |
     | Bowser   | Diane  | dog     | m    | 1979-08-31 | 1995-07-29 |
     | Chirpy   | Gwen   | bird    | f    | 1998-09-11 | NULL       |
     | Whistler | Gwen   | bird    | NULL | 1997-12-09 | NULL       |
     | Slim     | Benny  | snake   | m    | 1996-04-29 | NULL       |
     | Puffball | Diane  | hamster | f    | 1999-03-30 | NULL       |
     +----------+--------+---------+------+------------+------------+

This form of 'SELECT' is useful if you want to review
your entire table, for example, after you've just loaded it with your
initial data set.  For example, you may happen to think that the birth
date for Bowser doesn't seem quite right.  Consulting your original
pedigree papers, you find that the correct birth year should be 1989,
not 1979.

There are at least two ways to fix this:

   * Edit the file 'pet.txt' to correct the error, then empty the table
     and reload it using 'DELETE' and 'LOAD DATA'.:

          mysql> DELETE FROM pet;
          mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet;

     However, if you do this, you must also re-enter the record for
     Puffball.

   * Fix only the erroneous record with an 'UPDATE'.
     statement:

          mysql> UPDATE pet SET birth = '1989-08-31' WHERE name = 'Bowser';

     The 'UPDATE' changes only the record in question and
     does not require you to reload the table.

3.3.4.2 Selecting Particular Rows
.................................

As shown in the preceding section, it is easy to retrieve an entire
table.  Just omit the 'WHERE' clause from the 'SELECT'.
statement.  But typically you don't want to see the entire table,
particularly when it becomes large.  Instead, you're usually more
interested in answering a particular question, in which case you specify
some constraints on the information you want.  Let's look at some
selection queries in terms of questions about your pets that they
answer.

You can select only particular rows from your table.  For example, if
you want to verify the change that you made to Bowser's birth date,
select Bowser's record like this:

     mysql> SELECT * FROM pet WHERE name = 'Bowser';
     +--------+-------+---------+------+------------+------------+
     | name   | owner | species | sex  | birth      | death      |
     +--------+-------+---------+------+------------+------------+
     | Bowser | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+-------+---------+------+------------+------------+

The output confirms that the year is correctly recorded as 1989, not
1979.

String comparisons normally are case-insensitive, so you can specify the
name as ''bowser'', ''BOWSER'', and so forth.  The query result is the
same.

You can specify conditions on any column, not just 'name'.  For example,
if you want to know which animals were born during or after 1998, test
the 'birth' column:

     mysql> SELECT * FROM pet WHERE birth >= '1998-1-1';
     +----------+-------+---------+------+------------+-------+
     | name     | owner | species | sex  | birth      | death |
     +----------+-------+---------+------+------------+-------+
     | Chirpy   | Gwen  | bird    | f    | 1998-09-11 | NULL  |
     | Puffball | Diane | hamster | f    | 1999-03-30 | NULL  |
     +----------+-------+---------+------+------------+-------+

You can combine conditions, for example, to locate female dogs:

     mysql> SELECT * FROM pet WHERE species = 'dog' AND sex = 'f';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

The preceding query uses the 'AND' logical operator.  There is also an
'OR' operator:

     mysql> SELECT * FROM pet WHERE species = 'snake' OR species = 'bird';
     +----------+-------+---------+------+------------+-------+
     | name     | owner | species | sex  | birth      | death |
     +----------+-------+---------+------+------------+-------+
     | Chirpy   | Gwen  | bird    | f    | 1998-09-11 | NULL  |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL  |
     | Slim     | Benny | snake   | m    | 1996-04-29 | NULL  |
     +----------+-------+---------+------+------------+-------+

'AND' and 'OR' may be intermixed, although 'AND' has higher precedence
than 'OR'.  If you use both operators, it is a good idea to use
parentheses to indicate explicitly how conditions should be grouped:

     mysql> SELECT * FROM pet WHERE (species = 'cat' AND sex = 'm')
         -> OR (species = 'dog' AND sex = 'f');
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

3.3.4.3 Selecting Particular Columns
....................................

If you do not want to see entire rows from your table, just name the
columns in which you are interested, separated by commas.  For example,
if you want to know when your animals were born, select the 'name' and
'birth' columns:

     mysql> SELECT name, birth FROM pet;
     +----------+------------+
     | name     | birth      |
     +----------+------------+
     | Fluffy   | 1993-02-04 |
     | Claws    | 1994-03-17 |
     | Buffy    | 1989-05-13 |
     | Fang     | 1990-08-27 |
     | Bowser   | 1989-08-31 |
     | Chirpy   | 1998-09-11 |
     | Whistler | 1997-12-09 |
     | Slim     | 1996-04-29 |
     | Puffball | 1999-03-30 |
     +----------+------------+

To find out who owns pets, use this query:

     mysql> SELECT owner FROM pet;
     +--------+
     | owner  |
     +--------+
     | Harold |
     | Gwen   |
     | Harold |
     | Benny  |
     | Diane  |
     | Gwen   |
     | Gwen   |
     | Benny  |
     | Diane  |
     +--------+

Notice that the query simply retrieves the 'owner' column from each
record, and some of them appear more than once.  To minimize the output,
retrieve each unique output record just once by adding the keyword
'DISTINCT':

     mysql> SELECT DISTINCT owner FROM pet;
     +--------+
     | owner  |
     +--------+
     | Benny  |
     | Diane  |
     | Gwen   |
     | Harold |
     +--------+

You can use a 'WHERE' clause to combine row selection with column
selection.  For example, to get birth dates for dogs and cats only, use
this query:

     mysql> SELECT name, species, birth FROM pet
         -> WHERE species = 'dog' OR species = 'cat';
     +--------+---------+------------+
     | name   | species | birth      |
     +--------+---------+------------+
     | Fluffy | cat     | 1993-02-04 |
     | Claws  | cat     | 1994-03-17 |
     | Buffy  | dog     | 1989-05-13 |
     | Fang   | dog     | 1990-08-27 |
     | Bowser | dog     | 1989-08-31 |
     +--------+---------+------------+

3.3.4.4 Sorting Rows
....................

You may have noticed in the preceding examples that the result rows are
displayed in no particular order.  It is often easier to examine query
output when the rows are sorted in some meaningful way.  To sort a
result, use an 'ORDER BY' clause.

Here are animal birthdays, sorted by date:

     mysql> SELECT name, birth FROM pet ORDER BY birth;
     +----------+------------+
     | name     | birth      |
     +----------+------------+
     | Buffy    | 1989-05-13 |
     | Bowser   | 1989-08-31 |
     | Fang     | 1990-08-27 |
     | Fluffy   | 1993-02-04 |
     | Claws    | 1994-03-17 |
     | Slim     | 1996-04-29 |
     | Whistler | 1997-12-09 |
     | Chirpy   | 1998-09-11 |
     | Puffball | 1999-03-30 |
     +----------+------------+

On character type columns, sorting--like all other comparison
operations--is normally performed in a case-insensitive fashion.  This
means that the order is undefined for columns that are identical except
for their case.  You can force a case-sensitive sort for a column by
using 'BINARY' like so: 'ORDER BY BINARY COL_NAME'.

The default sort order is ascending, with smallest values first.  To
sort in reverse (descending) order, add the 'DESC' keyword to the name
of the column you are sorting by:

     mysql> SELECT name, birth FROM pet ORDER BY birth DESC;
     +----------+------------+
     | name     | birth      |
     +----------+------------+
     | Puffball | 1999-03-30 |
     | Chirpy   | 1998-09-11 |
     | Whistler | 1997-12-09 |
     | Slim     | 1996-04-29 |
     | Claws    | 1994-03-17 |
     | Fluffy   | 1993-02-04 |
     | Fang     | 1990-08-27 |
     | Bowser   | 1989-08-31 |
     | Buffy    | 1989-05-13 |
     +----------+------------+

You can sort on multiple columns, and you can sort different columns in
different directions.  For example, to sort by type of animal in
ascending order, then by birth date within animal type in descending
order (youngest animals first), use the following query:

     mysql> SELECT name, species, birth FROM pet
         -> ORDER BY species, birth DESC;
     +----------+---------+------------+
     | name     | species | birth      |
     +----------+---------+------------+
     | Chirpy   | bird    | 1998-09-11 |
     | Whistler | bird    | 1997-12-09 |
     | Claws    | cat     | 1994-03-17 |
     | Fluffy   | cat     | 1993-02-04 |
     | Fang     | dog     | 1990-08-27 |
     | Bowser   | dog     | 1989-08-31 |
     | Buffy    | dog     | 1989-05-13 |
     | Puffball | hamster | 1999-03-30 |
     | Slim     | snake   | 1996-04-29 |
     +----------+---------+------------+

The 'DESC' keyword applies only to the column name immediately preceding
it ('birth'); it does not affect the 'species' column sort order.

3.3.4.5 Date Calculations
.........................

MySQL provides several functions that you can use to perform
calculations on dates, for example, to calculate ages or extract parts
of dates.

To determine how many years old each of your pets is, use the
'TIMESTAMPDIFF()' function.  Its arguments are the unit in which you
want the result expressed, and the two date for which to take the
difference.  The following query shows, for each pet, the birth date,
the current date, and the age in years.  An _alias_ ('age') is used to
make the final output column label more meaningful.

     mysql> SELECT name, birth, CURDATE(),
         -> TIMESTAMPDIFF(YEAR,birth,CURDATE()) AS age
         -> FROM pet;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     +----------+------------+------------+------+

The query works, but the result could be scanned more easily if the rows
were presented in some order.  This can be done by adding an 'ORDER BY
name' clause to sort the output by name:

     mysql> SELECT name, birth, CURDATE(),
         -> TIMESTAMPDIFF(YEAR,birth,CURDATE()) AS age
         -> FROM pet ORDER BY name;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     +----------+------------+------------+------+

To sort the output by 'age' rather than 'name', just use a different
'ORDER BY' clause:

     mysql> SELECT name, birth, CURDATE(),
         -> TIMESTAMPDIFF(YEAR,birth,CURDATE()) AS age
         -> FROM pet ORDER BY age;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     +----------+------------+------------+------+

A similar query can be used to determine age at death for animals that
have died.  You determine which animals these are by checking whether
the 'death' value is 'NULL'.  Then, for those with non-'NULL' values,
compute the difference between the 'death' and 'birth' values:

     mysql> SELECT name, birth, death,
         -> TIMESTAMPDIFF(YEAR,birth,death) AS age
         -> FROM pet WHERE death IS NOT NULL ORDER BY age;
     +--------+------------+------------+------+
     | name   | birth      | death      | age  |
     +--------+------------+------------+------+
     | Bowser | 1989-08-31 | 1995-07-29 |    5 |
     +--------+------------+------------+------+

The query uses 'death IS NOT NULL' rather than 'death <> NULL' because
'NULL' is a special value that cannot be compared using the usual
comparison operators.  This is discussed later.  See
working-with-null.

What if you want to know which animals have birthdays next month?  For
this type of calculation, year and day are irrelevant; you simply want
to extract the month part of the 'birth' column.  MySQL provides several
functions for extracting parts of dates, such as 'YEAR()', 'MONTH()',
and 'DAYOFMONTH()'.  'MONTH()' is the appropriate function here.  To see
how it works, run a simple query that displays the value of both 'birth'
and 'MONTH(birth)':

     mysql> SELECT name, birth, MONTH(birth) FROM pet;
     +----------+------------+--------------+
     | name     | birth      | MONTH(birth) |
     +----------+------------+--------------+
     | Fluffy   | 1993-02-04 |            2 |
     | Claws    | 1994-03-17 |            3 |
     | Buffy    | 1989-05-13 |            5 |
     | Fang     | 1990-08-27 |            8 |
     | Bowser   | 1989-08-31 |            8 |
     | Chirpy   | 1998-09-11 |            9 |
     | Whistler | 1997-12-09 |           12 |
     | Slim     | 1996-04-29 |            4 |
     | Puffball | 1999-03-30 |            3 |
     +----------+------------+--------------+

Finding animals with birthdays in the upcoming month is also simple.
Suppose that the current month is April.  Then the month value is '4'
and you can look for animals born in May (month '5') like this:

     mysql> SELECT name, birth FROM pet WHERE MONTH(birth) = 5;
     +-------+------------+
     | name  | birth      |
     +-------+------------+
     | Buffy | 1989-05-13 |
     +-------+------------+

There is a small complication if the current month is December.  You
cannot merely add one to the month number ('12') and look for animals
born in month '13', because there is no such month.  Instead, you look
for animals born in January (month '1').

You can write the query so that it works no matter what the current
month is, so that you do not have to use the number for a particular
month.  'DATE_ADD()' enables you to add a time interval to a given date.
If you add a month to the value of 'CURDATE()', then extract the month
part with 'MONTH()', the result produces the month in which to look for
birthdays:

     mysql> SELECT name, birth FROM pet
         -> WHERE MONTH(birth) = MONTH(DATE_ADD(CURDATE(),INTERVAL 1 MONTH));

A different way to accomplish the same task is to add '1' to get the
next month after the current one after using the modulo function ('MOD')
to wrap the month value to '0' if it is currently '12':

     mysql> SELECT name, birth FROM pet
         -> WHERE MONTH(birth) = MOD(MONTH(CURDATE()), 12) + 1;

'MONTH()' returns a number between '1' and '12'.  And
'MOD(something,12)' returns a number between '0' and '11'.  So the
addition has to be after the 'MOD()', otherwise we would go from
November ('11') to January ('1').

3.3.4.6 Working with NULL Values
................................

The 'NULL' value can be surprising until you get used to it.
Conceptually, 'NULL' means 'a missing unknown value' and it is treated
somewhat differently from other values.

To test for 'NULL', use the 'IS NULL' and 'IS NOT NULL' operators, as
shown here:

     mysql> SELECT 1 IS NULL, 1 IS NOT NULL;
     +-----------+---------------+
     | 1 IS NULL | 1 IS NOT NULL |
     +-----------+---------------+
     |         0 |             1 |
     +-----------+---------------+

You cannot use arithmetic comparison operators such as '=', '<', or '<>'
to test for 'NULL'.  To demonstrate this for yourself, try the following
query:

     mysql> SELECT 1 = NULL, 1 <> NULL, 1 < NULL, 1 > NULL;
     +----------+-----------+----------+----------+
     | 1 = NULL | 1 <> NULL | 1 < NULL | 1 > NULL |
     +----------+-----------+----------+----------+
     |     NULL |      NULL |     NULL |     NULL |
     +----------+-----------+----------+----------+

Because the result of any arithmetic comparison with 'NULL' is also
'NULL', you cannot obtain any meaningful results from such comparisons.

In MySQL, '0' or 'NULL' means false and anything else means true.  The
default truth value from a boolean operation is '1'.

This special treatment of 'NULL' is why, in the previous section, it was
necessary to determine which animals are no longer alive using 'death IS
NOT NULL' instead of 'death <> NULL'.

Two 'NULL' values are regarded as equal in a 'GROUP BY'.

When doing an 'ORDER BY', 'NULL' values are presented first if you do
'ORDER BY ... ASC' and last if you do 'ORDER BY ... DESC'.

A common error when working with 'NULL' is to assume that it is not
possible to insert a zero or an empty string into a column defined as
'NOT NULL', but this is not the case.  These are in fact values, whereas
'NULL' means 'not having a value.' You can test this easily enough by
using 'IS [NOT] NULL' as shown:

     mysql> SELECT 0 IS NULL, 0 IS NOT NULL, '' IS NULL, '' IS NOT NULL;
     +-----------+---------------+------------+----------------+
     | 0 IS NULL | 0 IS NOT NULL | '' IS NULL | '' IS NOT NULL |
     +-----------+---------------+------------+----------------+
     |         0 |             1 |          0 |              1 |
     +-----------+---------------+------------+----------------+

Thus it is entirely possible to insert a zero or empty string into a
'NOT NULL' column, as these are in fact 'NOT NULL'.  See
problems-with-null.

3.3.4.7 Pattern Matching
........................

MySQL provides standard SQL pattern matching as well as a form of
pattern matching based on extended regular expressions similar to those
used by Unix utilities such as 'vi', 'grep', and 'sed'.

SQL pattern matching enables you to use '_' to match any single
character and '%' to match an arbitrary number of characters (including
zero characters).  In MySQL, SQL patterns are case-insensitive by
default.  Some examples are shown here.  Do not use '=' or '<>' when you
use SQL patterns.  Use the 'LIKE' or 'NOT LIKE' comparison operators
instead.

To find names beginning with 'b':

     mysql> SELECT * FROM pet WHERE name LIKE 'b%';
     +--------+--------+---------+------+------------+------------+
     | name   | owner  | species | sex  | birth      | death      |
     +--------+--------+---------+------+------------+------------+
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Bowser | Diane  | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+--------+---------+------+------------+------------+

To find names ending with 'fy':

     mysql> SELECT * FROM pet WHERE name LIKE '%fy';
     +--------+--------+---------+------+------------+-------+
     | name   | owner  | species | sex  | birth      | death |
     +--------+--------+---------+------+------------+-------+
     | Fluffy | Harold | cat     | f    | 1993-02-04 | NULL  |
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL  |
     +--------+--------+---------+------+------------+-------+

To find names containing a 'w':

     mysql> SELECT * FROM pet WHERE name LIKE '%w%';
     +----------+-------+---------+------+------------+------------+
     | name     | owner | species | sex  | birth      | death      |
     +----------+-------+---------+------+------------+------------+
     | Claws    | Gwen  | cat     | m    | 1994-03-17 | NULL       |
     | Bowser   | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL       |
     +----------+-------+---------+------+------------+------------+

To find names containing exactly five characters, use five instances of
the '_' pattern character:

     mysql> SELECT * FROM pet WHERE name LIKE '_____';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

The other type of pattern matching provided by MySQL uses extended
regular expressions.  When you test for a match for this type of
pattern, use the 'REGEXP' and 'NOT REGEXP' operators (or 'RLIKE' and
'NOT RLIKE', which are synonyms).

The following list describes some characteristics of extended regular
expressions:

   * '.' matches any single character.

   * A character class '[...]' matches any character within the
     brackets.  For example, '[abc]' matches 'a', 'b', or 'c'.  To name
     a range of characters, use a dash.  '[a-z]' matches any letter,
     whereas '[0-9]' matches any digit.

   * '*' matches zero or more instances of the thing preceding it.  For
     example, 'x*' matches any number of 'x' characters, '[0-9]*'
     matches any number of digits, and '.*' matches any number of
     anything.

   * A regular expression pattern match succeeds if the pattern matches
     anywhere in the value being tested.  (This differs from a 'LIKE'
     pattern match, which succeeds only if the pattern matches the
     entire value.)

   * To anchor a pattern so that it must match the beginning or end of
     the value being tested, use '^' at the beginning or '$' at the end
     of the pattern.

To demonstrate how extended regular expressions work, the 'LIKE' queries
shown previously are rewritten here to use 'REGEXP'.

To find names beginning with 'b', use '^' to match the beginning of the
name:

     mysql> SELECT * FROM pet WHERE name REGEXP '^b';
     +--------+--------+---------+------+------------+------------+
     | name   | owner  | species | sex  | birth      | death      |
     +--------+--------+---------+------+------------+------------+
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Bowser | Diane  | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+--------+---------+------+------------+------------+

To force a 'REGEXP' comparison to be case-sensitive, use the 'BINARY'
keyword to make one of the strings a binary string.  This query matches
only lowercase 'b' at the beginning of a name:

     SELECT * FROM pet WHERE name REGEXP BINARY '^b';

To find names ending with 'fy', use '$' to match the end of the name:

     mysql> SELECT * FROM pet WHERE name REGEXP 'fy$';
     +--------+--------+---------+------+------------+-------+
     | name   | owner  | species | sex  | birth      | death |
     +--------+--------+---------+------+------------+-------+
     | Fluffy | Harold | cat     | f    | 1993-02-04 | NULL  |
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL  |
     +--------+--------+---------+------+------------+-------+

To find names containing a 'w', use this query:

     mysql> SELECT * FROM pet WHERE name REGEXP 'w';
     +----------+-------+---------+------+------------+------------+
     | name     | owner | species | sex  | birth      | death      |
     +----------+-------+---------+------+------------+------------+
     | Claws    | Gwen  | cat     | m    | 1994-03-17 | NULL       |
     | Bowser   | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL       |
     +----------+-------+---------+------+------------+------------+

Because a regular expression pattern matches if it occurs anywhere in
the value, it is not necessary in the previous query to put a wildcard
on either side of the pattern to get it to match the entire value as
would be true with an SQL pattern.

To find names containing exactly five characters, use '^' and '$' to
match the beginning and end of the name, and five instances of '.' in
between:

     mysql> SELECT * FROM pet WHERE name REGEXP '^.....$';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

You could also write the previous query using the '{N}'
('repeat-N-times') operator:

     mysql> SELECT * FROM pet WHERE name REGEXP '^.{5}$';
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

For more information about the syntax for regular expressions, see
regexp.

3.3.4.8 Counting Rows
.....................

Databases are often used to answer the question, 'How often does a
certain type of data occur in a table?' For example, you might want to
know how many pets you have, or how many pets each owner has, or you
might want to perform various kinds of census operations on your
animals.

Counting the total number of animals you have is the same question as
'How many rows are in the 'pet' table?' because there is one record per
pet.  'COUNT(*)' counts the number of rows, so the query to count your
animals looks like this:

     mysql> SELECT COUNT(*) FROM pet;
     +----------+
     | COUNT(*) |
     +----------+
     |        9 |
     +----------+

Earlier, you retrieved the names of the people who owned pets.  You can
use 'COUNT()' if you want to find out how many pets each owner has:

     mysql> SELECT owner, COUNT(*) FROM pet GROUP BY owner;
     +--------+----------+
     | owner  | COUNT(*) |
     +--------+----------+
     | Benny  |        2 |
     | Diane  |        2 |
     | Gwen   |        3 |
     | Harold |        2 |
     +--------+----------+

The preceding query uses 'GROUP BY' to group all records for each
'owner'.  The use of 'COUNT()' in conjunction with 'GROUP BY' is useful
for characterizing your data under various groupings.  The following
examples show different ways to perform animal census operations.

Number of animals per species:

     mysql> SELECT species, COUNT(*) FROM pet GROUP BY species;
     +---------+----------+
     | species | COUNT(*) |
     +---------+----------+
     | bird    |        2 |
     | cat     |        2 |
     | dog     |        3 |
     | hamster |        1 |
     | snake   |        1 |
     +---------+----------+

Number of animals per sex:

     mysql> SELECT sex, COUNT(*) FROM pet GROUP BY sex;
     +------+----------+
     | sex  | COUNT(*) |
     +------+----------+
     | NULL |        1 |
     | f    |        4 |
     | m    |        4 |
     +------+----------+

(In this output, 'NULL' indicates that the sex is unknown.)

Number of animals per combination of species and sex:

     mysql> SELECT species, sex, COUNT(*) FROM pet GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | bird    | NULL |        1 |
     | bird    | f    |        1 |
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     | hamster | f    |        1 |
     | snake   | m    |        1 |
     +---------+------+----------+

You need not retrieve an entire table when you use 'COUNT()'.  For
example, the previous query, when performed just on dogs and cats, looks
like this:

     mysql> SELECT species, sex, COUNT(*) FROM pet
         -> WHERE species = 'dog' OR species = 'cat'
         -> GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     +---------+------+----------+

Or, if you wanted the number of animals per sex only for animals whose
sex is known:

     mysql> SELECT species, sex, COUNT(*) FROM pet
         -> WHERE sex IS NOT NULL
         -> GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | bird    | f    |        1 |
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     | hamster | f    |        1 |
     | snake   | m    |        1 |
     +---------+------+----------+

If you name columns to select in addition to the 'COUNT()' value, a
'GROUP BY' clause should be present that names those same columns.
Otherwise, the following occurs:

   * If the 'ONLY_FULL_GROUP_BY' SQL mode is enabled, an error occurs:

          mysql> SET sql_mode = 'ONLY_FULL_GROUP_BY';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT owner, COUNT(*) FROM pet;
          ERROR 1140 (42000): In aggregated query without GROUP BY, expression
          #1 of SELECT list contains nonaggregated column 'menagerie.pet.owner';
          this is incompatible with sql_mode=only_full_group_by

   * If 'ONLY_FULL_GROUP_BY' is not enabled, the query is processed by
     treating all rows as a single group, but the value selected for
     each named column is nondeterministic.  The server is free to
     select the value from any row:

          mysql> SET sql_mode = '';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT owner, COUNT(*) FROM pet;
          +--------+----------+
          | owner  | COUNT(*) |
          +--------+----------+
          | Harold |        8 |
          +--------+----------+
          1 row in set (0.00 sec)

See also group-by-handling.  See group-by-functions for
information about 'COUNT(EXPR)' behavior and related optimizations.

3.3.4.9 Using More Than one Table
.................................

The 'pet' table keeps track of which pets you have.  If you want to
record other information about them, such as events in their lives like
visits to the vet or when litters are born, you need another table.
What should this table look like?  It needs to contain the following
information:

   * The pet name so that you know which animal each event pertains to.

   * A date so that you know when the event occurred.

   * A field to describe the event.

   * An event type field, if you want to be able to categorize events.

Given these considerations, the 'CREATE TABLE'.
statement for the 'event' table might look like this:

     mysql> CREATE TABLE event (name VARCHAR(20), date DATE,
         -> type VARCHAR(15), remark VARCHAR(255));

As with the 'pet' table, it is easiest to load the initial records by
creating a tab-delimited text file containing the following information.

name        date        type        remark

Fluffy      1995-05-15  litter      4 kittens, 3 female, 1
                                    male

Buffy       1993-06-23  litter      5 puppies, 2 female, 3
                                    male

Buffy       1994-06-19  litter      3 puppies, 3 female

Chirpy      1999-03-21  vet         needed beak
                                    straightened

Slim        1997-08-03  vet         broken rib

Bowser      1991-10-12  kennel

Fang        1991-10-12  kennel

Fang        1998-08-28  birthday    Gave him a new chew toy

Claws       1998-03-17  birthday    Gave him a new flea
                                    collar

Whistler    1998-12-09  birthday    First birthday

Load the records like this:

     mysql> LOAD DATA LOCAL INFILE 'event.txt' INTO TABLE event;

Based on what you have learned from the queries that you have run on the
'pet' table, you should be able to perform retrievals on the records in
the 'event' table; the principles are the same.  But when is the 'event'
table by itself insufficient to answer questions you might ask?

Suppose that you want to find out the ages at which each pet had its
litters.  We saw earlier how to calculate ages from two dates.  The
litter date of the mother is in the 'event' table, but to calculate her
age on that date you need her birth date, which is stored in the 'pet'
table.  This means the query requires both tables:

     mysql> SELECT pet.name,
         -> TIMESTAMPDIFF(YEAR,birth,date) AS age,
         -> remark
         -> FROM pet INNER JOIN event
         ->   ON pet.name = event.name
         -> WHERE event.type = 'litter';
     +--------+------+-----------------------------+
     | name   | age  | remark                      |
     +--------+------+-----------------------------+
     | Fluffy |    2 | 4 kittens, 3 female, 1 male |
     | Buffy  |    4 | 5 puppies, 2 female, 3 male |
     | Buffy  |    5 | 3 puppies, 3 female         |
     +--------+------+-----------------------------+

There are several things to note about this query:

   * The 'FROM' clause joins two tables because the query needs to pull
     information from both of them.

   * When combining (joining) information from multiple tables, you need
     to specify how records in one table can be matched to records in
     the other.  This is easy because they both have a 'name' column.
     The query uses an 'ON' clause to match up records in the two tables
     based on the 'name' values.

     The query uses an 'INNER JOIN' to combine the tables.  An 'INNER
     JOIN' permits rows from either table to appear in the result if and
     only if both tables meet the conditions specified in the 'ON'
     clause.  In this example, the 'ON' clause specifies that the 'name'
     column in the 'pet' table must match the 'name' column in the
     'event' table.  If a name appears in one table but not the other,
     the row will not appear in the result because the condition in the
     'ON' clause fails.

   * Because the 'name' column occurs in both tables, you must be
     specific about which table you mean when referring to the column.
     This is done by prepending the table name to the column name.

You need not have two different tables to perform a join.  Sometimes it
is useful to join a table to itself, if you want to compare records in a
table to other records in that same table.  For example, to find
breeding pairs among your pets, you can join the 'pet' table with itself
to produce candidate pairs of males and females of like species:

     mysql> SELECT p1.name, p1.sex, p2.name, p2.sex, p1.species
         -> FROM pet AS p1 INNER JOIN pet AS p2
         ->   ON p1.species = p2.species AND p1.sex = 'f' AND p2.sex = 'm';
     +--------+------+--------+------+---------+
     | name   | sex  | name   | sex  | species |
     +--------+------+--------+------+---------+
     | Fluffy | f    | Claws  | m    | cat     |
     | Buffy  | f    | Fang   | m    | dog     |
     | Buffy  | f    | Bowser | m    | dog     |
     +--------+------+--------+------+---------+

In this query, we specify aliases for the table name to refer to the
columns and keep straight which instance of the table each column
reference is associated with.

3.4 Getting Information About Databases and Tables
==================================================

What if you forget the name of a database or table, or what the
structure of a given table is (for example, what its columns are
called)?  MySQL addresses this problem through several statements that
provide information about the databases and tables it supports.

You have previously seen 'SHOW DATABASES', which
lists the databases managed by the server.  To find out which database
is currently selected, use the 'DATABASE()' function:

     mysql> SELECT DATABASE();
     +------------+
     | DATABASE() |
     +------------+
     | menagerie  |
     +------------+

If you have not yet selected any database, the result is 'NULL'.

To find out what tables the default database contains (for example, when
you are not sure about the name of a table), use this statement:

     mysql> SHOW TABLES;
     +---------------------+
     | Tables_in_menagerie |
     +---------------------+
     | event               |
     | pet                 |
     +---------------------+

The name of the column in the output produced by this statement is
always 'Tables_in_DB_NAME', where DB_NAME is the name of the database.
See show-tables, for more information.

If you want to find out about the structure of a table, the
'DESCRIBE' statement is useful; it displays information about
each of a table's columns:

     mysql> DESCRIBE pet;
     +---------+-------------+------+-----+---------+-------+
     | Field   | Type        | Null | Key | Default | Extra |
     +---------+-------------+------+-----+---------+-------+
     | name    | varchar(20) | YES  |     | NULL    |       |
     | owner   | varchar(20) | YES  |     | NULL    |       |
     | species | varchar(20) | YES  |     | NULL    |       |
     | sex     | char(1)     | YES  |     | NULL    |       |
     | birth   | date        | YES  |     | NULL    |       |
     | death   | date        | YES  |     | NULL    |       |
     +---------+-------------+------+-----+---------+-------+

'Field' indicates the column name, 'Type' is the data type for the
column, 'NULL' indicates whether the column can contain 'NULL' values,
'Key' indicates whether the column is indexed, and 'Default' specifies
the column's default value.  'Extra' displays special information about
columns: If a column was created with the 'AUTO_INCREMENT' option, the
value will be 'auto_increment' rather than empty.

'DESC' is a short form of 'DESCRIBE'.  See
describe, for more information.

You can obtain the 'CREATE TABLE' statement
necessary to create an existing table using the 'SHOW CREATE TABLE'
statement.  See show-create-table.

If you have indexes on a table, 'SHOW INDEX FROM TBL_NAME' produces
information about them.  See show-index, for more about this
statement.

3.5 Using mysql in Batch Mode
=============================

In the previous sections, you used 'mysql' interactively
to enter statements and view the results.  You can also run
'mysql' in batch mode.  To do this, put the statements you want
to run in a file, then tell 'mysql' to read its input from
the file:

     shell> mysql < BATCH-FILE

If you are running 'mysql' under Windows and have some
special characters in the file that cause problems, you can do this:

     C:\> mysql -e "source BATCH-FILE"

If you need to specify connection parameters on the command line, the
command might look like this:

     shell> mysql -h HOST -u USER -p < BATCH-FILE
     Enter password: ********

When you use 'mysql' this way, you are creating a script
file, then executing the script.

If you want the script to continue even if some of the statements in it
produce errors, you should use the '--force' command-line option.

Why use a script?  Here are a few reasons:

   * If you run a query repeatedly (say, every day or every week),
     making it a script enables you to avoid retyping it each time you
     execute it.

   * You can generate new queries from existing ones that are similar by
     copying and editing script files.

   * Batch mode can also be useful while you are developing a query,
     particularly for multiple-line statements or multiple-statement
     sequences.  If you make a mistake, you do not have to retype
     everything.  Just edit your script to correct the error, then tell
     'mysql' to execute it again.

   * If you have a query that produces a lot of output, you can run the
     output through a pager rather than watching it scroll off the top
     of your screen:

          shell> mysql < BATCH-FILE | more

   * You can catch the output in a file for further processing:

          shell> mysql < BATCH-FILE > mysql.out

   * You can distribute your script to other people so that they can
     also run the statements.

   * Some situations do not allow for interactive use, for example, when
     you run a query from a 'cron' job.  In this case, you must use
     batch mode.

The default output format is different (more concise) when you run
'mysql' in batch mode than when you use it interactively.  For
example, the output of 'SELECT DISTINCT species FROM pet' looks like
this when 'mysql' is run interactively:

     +---------+
     | species |
     +---------+
     | bird    |
     | cat     |
     | dog     |
     | hamster |
     | snake   |
     +---------+

In batch mode, the output looks like this instead:

     species
     bird
     cat
     dog
     hamster
     snake

If you want to get the interactive output format in batch mode, use
'mysql -t'.  To echo to the output the statements that are
executed, use 'mysql -v'.

You can also use scripts from the 'mysql' prompt by using
the 'source' command or '\.' command:

     mysql> source FILENAME;
     mysql> \. FILENAME

See mysql-batch-commands, for more information.

3.6 Examples of Common Queries
==============================

Here are examples of how to solve some common problems with MySQL.

Some of the examples use the table 'shop' to hold the price of each
article (item number) for certain traders (dealers).  Supposing that
each trader has a single fixed price per article, then ('article',
'dealer') is a primary key for the records.

Start the command-line tool 'mysql' and select a database:

     shell> mysql YOUR-DATABASE-NAME

(In most MySQL installations, you can use the database named 'test').

You can create and populate the example table with these statements:

     CREATE TABLE shop (
         article INT(4) UNSIGNED ZEROFILL DEFAULT '0000' NOT NULL,
         dealer  CHAR(20)                 DEFAULT ''     NOT NULL,
         price   DOUBLE(16,2)             DEFAULT '0.00' NOT NULL,
         PRIMARY KEY(article, dealer));
     INSERT INTO shop VALUES
         (1,'A',3.45),(1,'B',3.99),(2,'A',10.99),(3,'B',1.45),
         (3,'C',1.69),(3,'D',1.25),(4,'D',19.95);

After issuing the statements, the table should have the following
contents:

     SELECT * FROM shop;

     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0001 | A      |  3.45 |
     |    0001 | B      |  3.99 |
     |    0002 | A      | 10.99 |
     |    0003 | B      |  1.45 |
     |    0003 | C      |  1.69 |
     |    0003 | D      |  1.25 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

3.6.1 The Maximum Value for a Column
------------------------------------

'What is the highest item number?'

     SELECT MAX(article) AS article FROM shop;

     +---------+
     | article |
     +---------+
     |       4 |
     +---------+

3.6.2 The Row Holding the Maximum of a Certain Column
-----------------------------------------------------

_Task: Find the number, dealer, and price of the most expensive
article._

This is easily done with a subquery:

     SELECT article, dealer, price
     FROM   shop
     WHERE  price=(SELECT MAX(price) FROM shop);

     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

Other solutions are to use a 'LEFT JOIN' or to sort all rows descending
by price and get only the first row using the MySQL-specific 'LIMIT'
clause:

     SELECT s1.article, s1.dealer, s1.price
     FROM shop s1
     LEFT JOIN shop s2 ON s1.price < s2.price
     WHERE s2.article IS NULL;

     SELECT article, dealer, price
     FROM shop
     ORDER BY price DESC
     LIMIT 1;

*Note*:

If there were several most expensive articles, each with a price of
19.95, the 'LIMIT' solution would show only one of them.

3.6.3 Maximum of Column per Group
---------------------------------

_Task: Find the highest price per article._

     SELECT article, MAX(price) AS price
     FROM   shop
     GROUP BY article;

     +---------+-------+
     | article | price |
     +---------+-------+
     |    0001 |  3.99 |
     |    0002 | 10.99 |
     |    0003 |  1.69 |
     |    0004 | 19.95 |
     +---------+-------+

3.6.4 The Rows Holding the Group-wise Maximum of a Certain Column
-----------------------------------------------------------------

_Task: For each article, find the dealer or dealers with the most
expensive price._

This problem can be solved with a subquery like this one:

     SELECT article, dealer, price
     FROM   shop s1
     WHERE  price=(SELECT MAX(s2.price)
                   FROM shop s2
                   WHERE s1.article = s2.article);

     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0001 | B      |  3.99 |
     |    0002 | A      | 10.99 |
     |    0003 | C      |  1.69 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

The preceding example uses a correlated subquery, which can be
inefficient (see correlated-subqueries).  Other possibilities
for solving the problem are to use an uncorrelated subquery in the
'FROM' clause or a 'LEFT JOIN'.

Uncorrelated subquery:

     SELECT s1.article, dealer, s1.price
     FROM shop s1
     JOIN (
       SELECT article, MAX(price) AS price
       FROM shop
       GROUP BY article) AS s2
       ON s1.article = s2.article AND s1.price = s2.price;

'LEFT JOIN':

     SELECT s1.article, s1.dealer, s1.price
     FROM shop s1
     LEFT JOIN shop s2 ON s1.article = s2.article AND s1.price < s2.price
     WHERE s2.article IS NULL;

The 'LEFT JOIN' works on the basis that when 's1.price' is at its
maximum value, there is no 's2.price' with a greater value and the 's2'
rows values will be 'NULL'.  See join.

3.6.5 Using User-Defined Variables
----------------------------------

You can employ MySQL user variables to remember results without having
to store them in temporary variables in the client.  (See
user-variables.)

For example, to find the articles with the highest and lowest price you
can do this:

     mysql> SELECT @min_price:=MIN(price),@max_price:=MAX(price) FROM shop;
     mysql> SELECT * FROM shop WHERE price=@min_price OR price=@max_price;
     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0003 | D      |  1.25 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

*Note*:

It is also possible to store the name of a database object such as a
table or a column in a user variable and then to use this variable in an
SQL statement; however, this requires the use of a prepared statement.
See sql-syntax-prepared-statements, for more information.

3.6.6 Using Foreign Keys
------------------------

In MySQL, 'InnoDB' tables support checking of foreign key constraints.
See innodb-storage-engine, and ansi-diff-foreign-keys.

A foreign key constraint is not required merely to join two tables.  For
storage engines other than 'InnoDB', it is possible when defining a
column to use a 'REFERENCES TBL_NAME(COL_NAME)' clause, which has no
actual effect, and _serves only as a memo or comment to you that the
column which you are currently defining is intended to refer to a column
in another table_.  It is extremely important to realize when using this
syntax that:

   * MySQL does not perform any sort of 'CHECK' to make sure that
     COL_NAME actually exists in TBL_NAME (or even that TBL_NAME itself
     exists).

   * MySQL does not perform any sort of action on TBL_NAME such as
     deleting rows in response to actions taken on rows in the table
     which you are defining; in other words, this syntax induces no 'ON
     DELETE' or 'ON UPDATE' behavior whatsoever.  (Although you can
     write an 'ON DELETE' or 'ON UPDATE' clause as part of the
     'REFERENCES' clause, it is also ignored.)

   * This syntax creates a _column_; it does *not* create any sort of
     index or key.

You can use a column so created as a join column, as shown here:

     CREATE TABLE person (
         id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
         name CHAR(60) NOT NULL,
         PRIMARY KEY (id)
     );

     CREATE TABLE shirt (
         id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
         style ENUM('t-shirt', 'polo', 'dress') NOT NULL,
         color ENUM('red', 'blue', 'orange', 'white', 'black') NOT NULL,
         owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
         PRIMARY KEY (id)
     );

     INSERT INTO person VALUES (NULL, 'Antonio Paz');

     SELECT @last := LAST_INSERT_ID();

     INSERT INTO shirt VALUES
     (NULL, 'polo', 'blue', @last),
     (NULL, 'dress', 'white', @last),
     (NULL, 't-shirt', 'blue', @last);

     INSERT INTO person VALUES (NULL, 'Lilliana Angelovska');

     SELECT @last := LAST_INSERT_ID();

     INSERT INTO shirt VALUES
     (NULL, 'dress', 'orange', @last),
     (NULL, 'polo', 'red', @last),
     (NULL, 'dress', 'blue', @last),
     (NULL, 't-shirt', 'white', @last);

     SELECT * FROM person;
     +----+---------------------+
     | id | name                |
     +----+---------------------+
     |  1 | Antonio Paz         |
     |  2 | Lilliana Angelovska |
     +----+---------------------+

     SELECT * FROM shirt;
     +----+---------+--------+-------+
     | id | style   | color  | owner |
     +----+---------+--------+-------+
     |  1 | polo    | blue   |     1 |
     |  2 | dress   | white  |     1 |
     |  3 | t-shirt | blue   |     1 |
     |  4 | dress   | orange |     2 |
     |  5 | polo    | red    |     2 |
     |  6 | dress   | blue   |     2 |
     |  7 | t-shirt | white  |     2 |
     +----+---------+--------+-------+

     SELECT s.* FROM person p INNER JOIN shirt s
        ON s.owner = p.id
      WHERE p.name LIKE 'Lilliana%'
        AND s.color <> 'white';

     +----+-------+--------+-------+
     | id | style | color  | owner |
     +----+-------+--------+-------+
     |  4 | dress | orange |     2 |
     |  5 | polo  | red    |     2 |
     |  6 | dress | blue   |     2 |
     +----+-------+--------+-------+

When used in this fashion, the 'REFERENCES' clause is not displayed in
the output of 'SHOW CREATE TABLE' or
'DESCRIBE'.:

     SHOW CREATE TABLE shirt\G
     *************************** 1. row ***************************
     Table: shirt
     Create Table: CREATE TABLE `shirt` (
     `id` smallint(5) unsigned NOT NULL auto_increment,
     `style` enum('t-shirt','polo','dress') NOT NULL,
     `color` enum('red','blue','orange','white','black') NOT NULL,
     `owner` smallint(5) unsigned NOT NULL,
     PRIMARY KEY  (`id`)
     ) ENGINE=MyISAM DEFAULT CHARSET=latin1

The use of 'REFERENCES' in this way as a comment or 'reminder' in a
column definition works with 'MyISAM' tables.

3.6.7 Searching on Two Keys
---------------------------

An 'OR' using a single key is well optimized, as is the handling of
'AND'.

The one tricky case is that of searching on two different keys combined
with 'OR':

     SELECT field1_index, field2_index FROM test_table
     WHERE field1_index = '1' OR  field2_index = '1'

This case is optimized.  See index-merge-optimization.

You can also solve the problem efficiently by using a 'UNION'
that combines the output of two separate 'SELECT'.
statements.  See union.

Each 'SELECT' searches only one key and can be optimized:

     SELECT field1_index, field2_index
         FROM test_table WHERE field1_index = '1'
     UNION
     SELECT field1_index, field2_index
         FROM test_table WHERE field2_index = '1';

3.6.8 Calculating Visits Per Day
--------------------------------

The following example shows how you can use the bit group functions to
calculate the number of days per month a user has visited a Web page.

     CREATE TABLE t1 (year YEAR(4), month INT(2) UNSIGNED ZEROFILL,
                  day INT(2) UNSIGNED ZEROFILL);
     INSERT INTO t1 VALUES(2000,1,1),(2000,1,20),(2000,1,30),(2000,2,2),
                 (2000,2,23),(2000,2,23);

The example table contains year-month-day values representing visits by
users to the page.  To determine how many different days in each month
these visits occur, use this query:

     SELECT year,month,BIT_COUNT(BIT_OR(1<<day)) AS days FROM t1
            GROUP BY year,month;

Which returns:

     +------+-------+------+
     | year | month | days |
     +------+-------+------+
     | 2000 |    01 |    3 |
     | 2000 |    02 |    2 |
     +------+-------+------+

The query calculates how many different days appear in the table for
each year/month combination, with automatic removal of duplicate
entries.

3.6.9 Using AUTO_INCREMENT
--------------------------

The 'AUTO_INCREMENT' attribute can be used to generate a unique identity
for new rows:

     CREATE TABLE animals (
          id MEDIUMINT NOT NULL AUTO_INCREMENT,
          name CHAR(30) NOT NULL,
          PRIMARY KEY (id)
     );

     INSERT INTO animals (name) VALUES
         ('dog'),('cat'),('penguin'),
         ('lax'),('whale'),('ostrich');

     SELECT * FROM animals;

Which returns:

     +----+---------+
     | id | name    |
     +----+---------+
     |  1 | dog     |
     |  2 | cat     |
     |  3 | penguin |
     |  4 | lax     |
     |  5 | whale   |
     |  6 | ostrich |
     +----+---------+

No value was specified for the 'AUTO_INCREMENT' column, so MySQL
assigned sequence numbers automatically.  You can also explicitly assign
0 to the column to generate sequence numbers, unless the
'NO_AUTO_VALUE_ON_ZERO' SQL mode is enabled.  If the column is declared
'NOT NULL', it is also possible to assign 'NULL' to the column to
generate sequence numbers.  When you insert any other value into an
'AUTO_INCREMENT' column, the column is set to that value and the
sequence is reset so that the next automatically generated value follows
sequentially from the largest column value.

You can retrieve the most recent automatically generated
'AUTO_INCREMENT' value with the 'LAST_INSERT_ID()' SQL function or the
'mysql_insert_id()'. C API function.  These
functions are connection-specific, so their return values are not
affected by another connection which is also performing inserts.

Use the smallest integer data type for the 'AUTO_INCREMENT' column that
is large enough to hold the maximum sequence value you will need.  When
the column reaches the upper limit of the data type, the next attempt to
generate a sequence number fails.  Use the 'UNSIGNED' attribute if
possible to allow a greater range.  For example, if you use
'TINYINT', the maximum permissible sequence number is
127.  For 'TINYINT UNSIGNED', the maximum is 255.
See integer-types for the ranges of all the integer types.

*Note*:

For a multiple-row insert, 'LAST_INSERT_ID()' and
'mysql_insert_id()' actually return the
'AUTO_INCREMENT' key from the _first_ of the inserted rows.  This
enables multiple-row inserts to be reproduced correctly on other servers
in a replication setup.

To start with an 'AUTO_INCREMENT' value other than 1, set that value
with 'CREATE TABLE' or 'ALTER TABLE',
like this:

     mysql> ALTER TABLE tbl AUTO_INCREMENT = 100;

*InnoDB Notes*

For information about 'AUTO_INCREMENT' usage specific to 'InnoDB', see
innodb-auto-increment-handling.

*MyISAM Notes*

   * For 'MyISAM' tables, you can specify 'AUTO_INCREMENT' on a
     secondary column in a multiple-column index.  In this case, the
     generated value for the 'AUTO_INCREMENT' column is calculated as
     'MAX(AUTO_INCREMENT_COLUMN) + 1 WHERE prefix=GIVEN-PREFIX'.  This
     is useful when you want to put data into ordered groups.

          CREATE TABLE animals (
              grp ENUM('fish','mammal','bird') NOT NULL,
              id MEDIUMINT NOT NULL AUTO_INCREMENT,
              name CHAR(30) NOT NULL,
              PRIMARY KEY (grp,id)
          ) ENGINE=MyISAM;

          INSERT INTO animals (grp,name) VALUES
              ('mammal','dog'),('mammal','cat'),
              ('bird','penguin'),('fish','lax'),('mammal','whale'),
              ('bird','ostrich');

          SELECT * FROM animals ORDER BY grp,id;

     Which returns:

          +--------+----+---------+
          | grp    | id | name    |
          +--------+----+---------+
          | fish   |  1 | lax     |
          | mammal |  1 | dog     |
          | mammal |  2 | cat     |
          | mammal |  3 | whale   |
          | bird   |  1 | penguin |
          | bird   |  2 | ostrich |
          +--------+----+---------+

     In this case (when the 'AUTO_INCREMENT' column is part of a
     multiple-column index), 'AUTO_INCREMENT' values are reused if you
     delete the row with the biggest 'AUTO_INCREMENT' value in any
     group.  This happens even for 'MyISAM' tables, for which
     'AUTO_INCREMENT' values normally are not reused.

   * If the 'AUTO_INCREMENT' column is part of multiple indexes, MySQL
     generates sequence values using the index that begins with the
     'AUTO_INCREMENT' column, if there is one.  For example, if the
     'animals' table contained indexes 'PRIMARY KEY (grp, id)' and
     'INDEX (id)', MySQL would ignore the 'PRIMARY KEY' for generating
     sequence values.  As a result, the table would contain a single
     sequence, not a sequence per 'grp' value.

*Further Reading*

More information about 'AUTO_INCREMENT' is available here:

   * How to assign the 'AUTO_INCREMENT' attribute to a column:
     create-table, and alter-table.

   * How 'AUTO_INCREMENT' behaves depending on the
     'NO_AUTO_VALUE_ON_ZERO' SQL mode: sql-mode.

   * How to use the 'LAST_INSERT_ID()' function to find the row that
     contains the most recent 'AUTO_INCREMENT' value:
     information-functions.

   * Setting the 'AUTO_INCREMENT' value to be used:
     server-system-variables.

   * innodb-auto-increment-handling

   * 'AUTO_INCREMENT' and replication:
     replication-features-auto-increment.

   * Server-system variables related to 'AUTO_INCREMENT'
     ('auto_increment_increment' and 'auto_increment_offset') that can
     be used for replication: server-system-variables.

3.7 Using MySQL with Apache
===========================

There are programs that let you authenticate your users from a MySQL
database and also let you write your log files into a MySQL table.

You can change the Apache logging format to be easily readable by MySQL
by putting the following into the Apache configuration file:

     LogFormat \
             "\"%h\",%{%Y%m%d%H%M%S}t,%>s,\"%b\",\"%{Content-Type}o\",  \
             \"%U\",\"%{Referer}i\",\"%{User-Agent}i\""

To load a log file in that format into MySQL, you can use a statement
something like this:

     LOAD DATA INFILE '/LOCAL/ACCESS_LOG' INTO TABLE TBL_NAME
     FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\\'

The named table should be created to have columns that correspond to
those that the 'LogFormat' line writes to the log file.

4 MySQL Programs
****************

This chapter provides a brief overview of the MySQL command-line
programs provided by Oracle Corporation.  It also discusses the general
syntax for specifying options when you run these programs.  Most
programs have options that are specific to their own operation, but the
option syntax is similar for all of them.  Finally, the chapter provides
more detailed descriptions of individual programs, including which
options they recognize.

4.1 Overview of MySQL Programs
==============================

There are many different programs in a MySQL installation.  This section
provides a brief overview of them.  Later sections provide a more
detailed description of each one, with the exception of NDB Cluster
programs.  Each program's description indicates its invocation syntax
and the options that it supports.  See mysql-cluster-programs,
describes programs specific to NDB Cluster.

Most MySQL distributions include all of these programs, except for those
programs that are platform-specific.  (For example, the server startup
scripts are not used on Windows.)  The exception is that RPM
distributions are more specialized.  There is one RPM for the server,
another for client programs, and so forth.  If you appear to be missing
one or more programs, see installing, for information on types
of distributions and what they contain.  It may be that you have a
distribution that does not include all programs and you need to install
an additional package.

Each MySQL program takes many different options.  Most programs provide
a '--help' option that you can use to get a description of the program's
different options.  For example, try 'mysql --help'.

You can override default option values for MySQL programs by specifying
options on the command line or in an option file.  See
programs-using, for general information on invoking programs and
specifying program options.

The MySQL server, see 'mysqld', is the main program that does
most of the work in a MySQL installation.  The server is accompanied by
several related scripts that assist you in starting and stopping the
server:

   *
     'mysqld'.

     The SQL daemon (that is, the MySQL server).  To use client
     programs, see 'mysqld' must be running, because clients
     gain access to databases by connecting to the server.  See
     mysqld.

   *
     'mysqld_safe'.

     A server startup script.  See 'mysqld_safe'.
     attempts to start 'mysqld'.  See mysqld-safe.

   *
     'mysql.server'.

     A server startup script.  This script is used on systems that use
     System V-style run directories containing scripts that start system
     services for particular run levels.  It invokes
     'mysqld_safe' to start the MySQL server.  See
     mysql-server.

   *
     'mysqld_multi'.

     A server startup script that can start or stop multiple servers
     installed on the system.  See mysqld-multi.

Several programs perform setup operations during MySQL installation or
upgrading:

   *
     'comp_err'.

     This program is used during the MySQL build/installation process.
     It compiles error message files from the error source files.  See
     comp-err.

   *
     'mysql_install_db'.

     This program initializes the MySQL data directory, creates the
     'mysql' database and initializes its grant tables with default
     privileges, and sets up the 'InnoDB' system tablespace.  It is
     usually executed only once, when first installing MySQL on a
     system.  See mysql-install-db, and
     postinstallation.

   *
     'mysql_plugin'.

     This program configures MySQL server plugins.  See
     mysql-plugin.

   *
     'mysql_secure_installation'.

     This program enables you to improve the security of your MySQL
     installation.  See mysql-secure-installation.

   *
     'mysql_ssl_rsa_setup'.

     This program creates the SSL certificate and key files and RSA
     key-pair files required to support secure connections, if those
     files are missing.  Files created by 'mysql_ssl_rsa_setup'
     can be used for secure connections using SSL
     or RSA. See mysql-ssl-rsa-setup.

   *
     'mysql_tzinfo_to_sql'.

     This program loads the time zone tables in the 'mysql' database
     using the contents of the host system _zoneinfo_ database (the set
     of files describing time zones).  See mysql-tzinfo-to-sql.

   *
     'mysql_upgrade'.

     This program is used after a MySQL upgrade operation.  It checks
     tables for incompatibilities and repairs them if necessary, and
     updates the grant tables with any changes that have been made in
     newer versions of MySQL. See mysql-upgrade.

MySQL client programs that connect to the MySQL server:

   *
     'mysql'.

     The command-line tool for interactively entering SQL statements or
     executing them from a file in batch mode.  See mysql.

   *
     'mysqladmin'.

     A client that performs administrative operations, such as creating
     or dropping databases, reloading the grant tables, flushing tables
     to disk, and reopening log files.  See 'mysqladmin'.
     can also be used to retrieve version, process, and status
     information from the server.  See mysqladmin.

   *
     'mysqlcheck'.

     A table-maintenance client that checks, repairs, analyzes, and
     optimizes tables.  See mysqlcheck.

   *
     'mysqldump'.

     A client that dumps a MySQL database into a file as SQL, text, or
     XML. See mysqldump.

   *
     'mysqlimport'.

     A client that imports text files into their respective tables using
     'LOAD DATA INFILE'.  See mysqlimport.

   *
     'mysqlpump'.

     A client that dumps a MySQL database into a file as SQL. See
     mysqlpump.

   *
     'mysqlsh'.

     An advanced command-line client and code editor for the MySQL
     Server.  In addition to SQL, MySQL Shell also offers scripting
     capabilities for JavaScript and Python.  When MySQL Shell is
     connected to the MySQL Server through the X Protocol, the X DevAPI
     can be used to work with both relational and document data.  See
     mysqlsh.

   *
     'mysqlshow'.

     A client that displays information about databases, tables,
     columns, and indexes.  See mysqlshow.

   *
     'mysqlslap'.

     A client that is designed to emulate client load for a MySQL server
     and report the timing of each stage.  It works as if multiple
     clients are accessing the server.  See mysqlslap.

MySQL administrative and utility programs:

   *
     'innochecksum'.

     An offline 'InnoDB' offline file checksum utility.  See
     innochecksum.

   *
     'myisam_ftdump'.

     A utility that displays information about full-text indexes in
     'MyISAM' tables.  See myisam-ftdump.

   *
     'myisamchk'.

     A utility to describe, check, optimize, and repair 'MyISAM' tables.
     See myisamchk.

   *
     'myisamlog'.

     A utility that processes the contents of a 'MyISAM' log file.  See
     myisamlog.

   *
     'myisampack'.

     A utility that compresses 'MyISAM' tables to produce smaller
     read-only tables.  See myisampack.

   *
     'mysql_config_editor'.

     A utility that enables you to store authentication credentials in a
     secure, encrypted login path file named '.mylogin.cnf'.  See
     mysql-config-editor.

   *
     'mysqlbinlog'.

     A utility for reading statements from a binary log.  The log of
     executed statements contained in the binary log files can be used
     to help recover from a crash.  See mysqlbinlog.

   *
     'mysqldumpslow'.

     A utility to read and summarize the contents of a slow query log.
     See mysqldumpslow.

MySQL program-development utilities:

   * 'mysql_config'.

     A shell script that produces the option values needed when
     compiling MySQL programs.  See mysql-config.

   *
     'my_print_defaults'.

     A utility that shows which options are present in option groups of
     option files.  See my-print-defaults.

   *
     'resolve_stack_dump'.

     A utility program that resolves a numeric stack trace dump to
     symbols.  See resolve-stack-dump.

Miscellaneous utilities:

   *
     'lz4_decompress'.

     A utility that decompresses 'mysqlpump' output
     that was created using LZ4 compression.  See
     lz4-decompress.

   *
     'perror'.

     A utility that displays the meaning of system or MySQL error codes.
     See perror.

   *
     'replace'.

     A utility program that performs string replacement in the input
     text.  See replace-utility.

   *
     'resolveip'.

     A utility program that resolves a host name to an IP address or
     vice versa.  See resolveip.

   *
     'zlib_decompress'.

     A utility that decompresses 'mysqlpump' output
     that was created using ZLIB compression.  See
     zlib-decompress.

Oracle Corporation also provides the MySQL Workbench.
GUI tool, which is used to administer MySQL servers and databases, to
create, execute, and evaluate queries, and to migrate schemas and data
from other relational database management systems for use with MySQL.
Additional GUI tools include MySQL Notifier and
MySQL for Excel (http://dev.mysql.com/doc/mysql-for-excel/en/).

MySQL client programs that communicate with the server using the MySQL
client/server library use the following environment variables.

Environment        Meaning
Variable

'MYSQL_UNIX_PORT'  The default Unix socket file; used for connections
                   to 'localhost'

'MYSQL_TCP_PORT'   The default port number; used for TCP/IP connections

'MYSQL_PWD'        The default password

'MYSQL_DEBUG'      Debug trace options when debugging

'TMPDIR'           The directory where temporary tables and files are
                   created

For a full list of environment variables used by MySQL programs, see
environment-variables.

Use of 'MYSQL_PWD' is insecure.  See password-security-user.

4.2 Using MySQL Programs
========================

4.2.1 Invoking MySQL Programs
-----------------------------

To invoke a MySQL program from the command line (that is, from your
shell or command prompt), enter the program name followed by any options
or other arguments needed to instruct the program what you want it to
do.  The following commands show some sample program invocations.
'shell>' represents the prompt for your command interpreter; it is not
part of what you type.  The particular prompt you see depends on your
command interpreter.  Typical prompts are '$' for 'sh', 'ksh', or
'bash', '%' for 'csh' or 'tcsh', and 'C:\>' for the Windows
'command.com' or 'cmd.exe' command interpreters.

     shell> mysql --user=root test
     shell> mysqladmin extended-status variables
     shell> mysqlshow --help
     shell> mysqldump -u root personnel

Arguments that begin with a single or double dash ('-', '--') specify
program options.  Options typically indicate the type of connection a
program should make to the server or affect its operational mode.
Option syntax is described in program-options.

Nonoption arguments (arguments with no leading dash) provide additional
information to the program.  For example, the 'mysql'.
program interprets the first nonoption argument as a database name, so
the command 'mysql --user=root test' indicates that you want to use the
'test' database.

Later sections that describe individual programs indicate which options
a program supports and describe the meaning of any additional nonoption
arguments.

Some options are common to a number of programs.  The most frequently
used of these are the '--host' (or '-h'), '--user' (or '-u'), and
'--password' (or '-p') options that specify connection parameters.  They
indicate the host where the MySQL server is running, and the user name
and password of your MySQL account.  All MySQL client programs
understand these options; they enable you to specify which server to
connect to and the account to use on that server.  Other connection
options are '--port' (or '-P') to specify a TCP/IP port number and
'--socket' (or '-S') to specify a Unix socket file on Unix (or named
pipe name on Windows).  For more information on options that specify
connection options, see connecting.

You may find it necessary to invoke MySQL programs using the path name
to the 'bin' directory in which they are installed.  This is likely to
be the case if you get a 'program not found' error whenever you attempt
to run a MySQL program from any directory other than the 'bin'
directory.  To make it more convenient to use MySQL, you can add the
path name of the 'bin' directory to your 'PATH' environment variable
setting.  That enables you to run a program by typing only its name, not
its entire path name.  For example, if 'mysql' is
installed in '/usr/local/mysql/bin', you can run the program by invoking
it as 'mysql', and it is not necessary to invoke it as
'/usr/local/mysql/bin/mysql'.

Consult the documentation for your command interpreter for instructions
on setting your 'PATH' variable.  The syntax for setting environment
variables is interpreter-specific.  (Some information is given in
setting-environment-variables.)  After modifying your 'PATH' setting,
open a new console window on Windows or log in again on Unix so that the
setting goes into effect.

4.2.2 Connecting to the MySQL Server
------------------------------------

This section describes how to establish a connection to the MySQL
server.  For additional information if you are unable to connect, see
problems-connecting.

For a client program to be able to connect to the MySQL server, it must
use the proper connection parameters, such as the name of the host where
the server is running and the user name and password of your MySQL
account.  Each connection parameter has a default value, but you can
override them as necessary using program options specified either on the
command line or in an option file.

The examples here use the 'mysql' client program, but the
principles apply to other clients such as 'mysqldump',
'mysqladmin', or 'mysqlshow'.

This command invokes 'mysql' without specifying any
connection parameters explicitly:

     shell> mysql

Because there are no parameter options, the default values apply:

   * The default host name is 'localhost'.  On Unix, this has a special
     meaning, as described later.

   * The default user name is 'ODBC' on Windows or your Unix login name
     on Unix.

   * No password is sent if neither '-p' nor '--password' is given.

   * For 'mysql', the first nonoption argument is taken as
     the name of the default database.  If there is no such option,
     see 'mysql' does not select a default database.

To specify the host name and user name explicitly, as well as a
password, supply appropriate options on the command line:

     shell> mysql --host=localhost --user=myname --password=PASSWORD mydb
     shell> mysql -h localhost -u myname -pPASSWORD mydb

For password options, the password value is optional:

   * If you use a '-p' or '--password' option and specify the password
     value, there must be _no space_ between '-p' or '--password=' and
     the password following it.

   * If you use a '-p' or '--password' option but do not specify the
     password value, the client program prompts you to enter the
     password.  The password is not displayed as you enter it.  This is
     more secure than giving the password on the command line.  Other
     users on your system may be able to see a password specified on the
     command line by executing a command such as 'ps auxw'.  See
     password-security-user.

As just mentioned, including the password value on the command line can
be a security risk.  To avoid this problem, specify the '--password' or
'-p' option without any following password value:

     shell> mysql --host=localhost --user=myname --password mydb
     shell> mysql -h localhost -u myname -p mydb

When the password option has no password value, the client program
prints a prompt and waits for you to enter the password.  (In these
examples, 'mydb' is _not_ interpreted as a password because it is
separated from the preceding password option by a space.)

On some systems, the library routine that MySQL uses to prompt for a
password automatically limits the password to eight characters.  That is
a problem with the system library, not with MySQL. Internally, MySQL
does not have any limit for the length of the password.  To work around
the problem, change your MySQL password to a value that is eight or
fewer characters long, or put your password in an option file.

On Unix, MySQL programs treat the host name 'localhost' specially, in a
way that is likely different from what you expect compared to other
network-based programs.  For connections to 'localhost', MySQL programs
attempt to connect to the local server by using a Unix socket file.
This occurs even if a '--port' or '-P' option is given to specify a port
number.  To ensure that the client makes a TCP/IP connection to the
local server, use '--host' or '-h' to specify a host name value of
'127.0.0.1', or the IP address or name of the local server.  You can
also specify the connection protocol explicitly, even for 'localhost',
by using the '--protocol=TCP' option.  For example:

     shell> mysql --host=127.0.0.1
     shell> mysql --protocol=TCP

The '--protocol' option enables you to establish a particular type of
connection even when the other options would normally default to some
other protocol.

If the server is configured to accept IPv6 connections, clients can
connect over IPv6 using '--host=::1'.  See ipv6-support.

On Windows, you can force a MySQL client to use a named-pipe connection
by specifying the '--pipe' or '--protocol=PIPE' option, or by specifying
'.' (period) as the host name.  If named-pipe connections are not
enabled, an error occurs.  Use the '--socket' option to specify the name
of the pipe if you do not want to use the default pipe name.

Connections to remote servers always use TCP/IP. This command connects
to the server running on 'remote.example.com' using the default port
number (3306):

     shell> mysql --host=remote.example.com

To specify a port number explicitly, use the '--port' or '-P' option:

     shell> mysql --host=remote.example.com --port=13306

You can specify a port number for connections to a local server, too.
However, as indicated previously, connections to 'localhost' on Unix
will use a socket file by default.  You will need to force a TCP/IP
connection as already described or any option that specifies a port
number will be ignored.

For this command, the program uses a socket file on Unix and the
'--port' option is ignored:

     shell> mysql --port=13306 --host=localhost

To cause the port number to be used, invoke the program in either of
these ways:

     shell> mysql --port=13306 --host=127.0.0.1
     shell> mysql --port=13306 --protocol=TCP

The following list summarizes the options that can be used to control
how client programs connect to the server:

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     The host where the server is running.  The default value is
     'localhost'.

   *
     '--password[=PASS_VAL]', '-p[PASS_VAL]'

     The password of the MySQL account.  As described earlier, the
     password value is optional, but if given, there must be _no space_
     between '-p' or '--password=' and the password following it.  The
     default is to send no password.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  The server
     must be started with the '--enable-named-pipe' option to enable
     named-pipe connections.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The port number to use for the connection, for connections made
     using TCP/IP. The default port number is 3306.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     This option explicitly specifies a protocol to use for connecting
     to the server.  It is useful when the other connection parameters
     normally would cause a protocol to be used other than the one you
     want.  For example, connections on Unix to 'localhost' are made
     using a Unix socket file by default:

          shell> mysql --host=localhost

     To force a TCP/IP connection to be used instead, specify a
     '--protocol' option:

          shell> mysql --host=localhost --protocol=TCP

     The following table shows the permissible '--protocol' option
     values and indicates the platforms on which each value may be used.
     The values are not case-sensitive.

     '--protocol'   Connection Protocol                  Permissible
     Value                                               Operating Systems

     'TCP'          TCP/IP connection to local or        All
                    remote server

     'SOCKET'       Unix socket file connection to       Unix only
                    local server

     'PIPE'         Named-pipe connection to local or    Windows only
                    remote server

     'MEMORY'       Shared-memory connection to local    Windows only
                    server

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--socket=FILE_NAME', '-S FILE_NAME'

     On Unix, the name of the Unix socket file to use, for connections
     made using a named pipe to a local server.  The default Unix socket
     file name is '/tmp/mysql.sock'.

     On Windows, the name of the named pipe to use, for connections to a
     local server.  The default Windows pipe name is 'MySQL'.  The pipe
     name is not case-sensitive.

     The server must be started with the '--enable-named-pipe' option to
     enable named-pipe connections.

   *
     '--ssl*'

     Options that begin with '--ssl' are used for establishing a secure
     connection to the server using SSL, if the server is configured
     with SSL support.  For details, see
     encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The user name of the MySQL account you want to use.  The default
     user name is 'ODBC' on Windows or your Unix login name on Unix.

It is possible to specify different default values to be used when you
make a connection so that you need not enter them on the command line
each time you invoke a client program.  This can be done in a couple of
ways:

   *
     You can specify connection parameters in the '[client]' section of
     an option file.  The relevant section of the file might look like
     this:

          [client]
          host=HOST_NAME
          user=USER_NAME
          password=YOUR_PASS

     See option-files, discusses option files further.

   *
     You can specify some connection parameters using environment
     variables.  The host can be specified for 'mysql'.
     using 'MYSQL_HOST'.  The MySQL user name can be specified using
     'USER' (this is for Windows only).  The password can be specified
     using 'MYSQL_PWD', although this is insecure; see
     password-security-user.  For a list of variables, see
     environment-variables.

4.2.3 Specifying Program Options
--------------------------------

There are several ways to specify options for MySQL programs:

   * List the options on the command line following the program name.
     This is common for options that apply to a specific invocation of
     the program.

   * List the options in an option file that the program reads when it
     starts.  This is common for options that you want the program to
     use each time it runs.

   * List the options in environment variables (see
     setting-environment-variables).  This method is useful for
     options that you want to apply each time the program runs.  In
     practice, option files are used more commonly for this purpose, but
     multiple-unix-servers, discusses one situation in which
     environment variables can be very helpful.  It describes a handy
     technique that uses such variables to specify the TCP/IP port
     number and Unix socket file for the server and for client programs.

Options are processed in order, so if an option is specified multiple
times, the last occurrence takes precedence.  The following command
causes 'mysql' to connect to the server running on
'localhost':

     shell> mysql -h example.com -h localhost

If conflicting or related options are given, later options take
precedence over earlier options.  The following command runs
'mysql' in 'no column names' mode:

     shell> mysql --column-names --skip-column-names

MySQL programs determine which options are given first by examining
environment variables, then by processing option files, and then by
checking the command line.  This means that environment variables have
the lowest precedence and command-line options the highest.

You can take advantage of the way that MySQL programs process options by
specifying default option values for a program in an option file.  That
enables you to avoid typing them each time you run the program while
enabling you to override the defaults if necessary by using command-line
options.

*Note*:

In older versions of MySQL, program options could be specified in full
or as any unambiguous prefix.  For example, the '--compress' option
could be given to 'mysqldump' as '--compr', but not as
'--comp' because the latter is ambiguous.  In MySQL 5.7, option prefixes
are no longer supported; only full options are accepted.  This is
because prefixes can cause problems when new options are implemented for
programs and a prefix that is currently unambiguous might become
ambiguous in the future.  Some implications of this change:

   * The '--key-buffer' option must now be specified as
     '--key-buffer-size'.

   * The '--skip-grant' option must now be specified as
     '--skip-grant-tables'.

4.2.4 Using Options on the Command Line
---------------------------------------

Program options specified on the command line follow these rules:

   * Options are given after the command name.

   * An option argument begins with one dash or two dashes, depending on
     whether it is a short form or long form of the option name.  Many
     options have both short and long forms.  For example, '-?' and
     '--help' are the short and long forms of the option that instructs
     a MySQL program to display its help message.

   * Option names are case-sensitive.  '-v' and '-V' are both legal and
     have different meanings.  (They are the corresponding short forms
     of the '--verbose' and '--version' options.)

   * Some options take a value following the option name.  For example,
     '-h localhost' or '--host=localhost' indicate the MySQL server host
     to a client program.  The option value tells the program the name
     of the host where the MySQL server is running.

   * For a long option that takes a value, separate the option name and
     the value by an '=' sign.  For a short option that takes a value,
     the option value can immediately follow the option letter, or there
     can be a space between: '-hlocalhost' and '-h localhost' are
     equivalent.  An exception to this rule is the option for specifying
     your MySQL password.  This option can be given in long form as
     '--password=PASS_VAL' or as '--password'.  In the latter case (with
     no password value given), the program prompts you for the password.
     The password option also may be given in short form as '-pPASS_VAL'
     or as '-p'.  However, for the short form, if the password value is
     given, it must follow the option letter with _no intervening
     space_.  The reason for this is that if a space follows the option
     letter, the program has no way to tell whether a following argument
     is supposed to be the password value or some other kind of
     argument.  Consequently, the following two commands have two
     completely different meanings:

          shell> mysql -ptest
          shell> mysql -p test

     The first command instructs 'mysql' to use a password
     value of 'test', but specifies no default database.  The second
     instructs 'mysql' to prompt for the password value
     and to use 'test' as the default database.

   * Within option names, dash ('-') and underscore ('_') may be used
     interchangeably.  For example, '--skip-grant-tables' and
     '--skip_grant_tables' are equivalent.  (However, the leading dashes
     cannot be given as underscores.)

   * For options that take a numeric value, the value can be given with
     a suffix of 'K', 'M', or 'G' (either uppercase or lowercase) to
     indicate a multiplier of 1024, 1024^2 or 1024^3.  For example, the
     following command tells 'mysqladmin' to ping the
     server 1024 times, sleeping 10 seconds between each ping:

          shell> mysqladmin --count=1K --sleep=10 ping

   * When specifying file names as option values, avoid the use of the
     '~' shell metacharacter because it might not be interpreted as you
     expect.

Option values that contain spaces must be quoted when given on the
command line.  For example, the '--execute' (or '-e') option can be used
with 'mysql' to pass SQL statements to the server.  When
this option is used, see 'mysql' executes the statements in
the option value and exits.  The statements must be enclosed by
quotation marks.  For example, you can use the following command to
obtain a list of user accounts:

     shell> mysql -u root -p --execute="SELECT User, Host FROM mysql.user"
     Enter password: ******
     +------+-----------+
     | User | Host      |
     +------+-----------+
     |      | gigan     |
     | root | gigan     |
     |      | localhost |
     | jon  | localhost |
     | root | localhost |
     +------+-----------+
     shell>

*Note*:

The long form ('--execute') is followed by an equals sign ('=').

If you wish to use quoted values within a statement, you will either
need to escape the inner quotation marks, or use a different type of
quotation marks within the statement from those used to quote the
statement itself.  The capabilities of your command processor dictate
your choices for whether you can use single or double quotation marks
and the syntax for escaping quote characters.  For example, if your
command processor supports quoting with single or double quotation
marks, you can use double quotation marks around the statement, and
single quotation marks for any quoted values within the statement.

Multiple SQL statements may be passed in the option value on the command
line, separated by semicolons:

     shell> mysql -u root -p -e "SELECT VERSION();SELECT NOW()"
     Enter password: ******
     +------------------+
     | VERSION()        |
     +------------------+
     | 5.7.10-debug-log |
     +------------------+
     +---------------------+
     | NOW()               |
     +---------------------+
     | 2015-11-05 20:01:02 |
     +---------------------+

4.2.5 Program Option Modifiers
------------------------------

Some options are 'boolean' and control behavior that can be turned on or
off.  For example, the 'mysql' client supports a
'--column-names' option that determines whether or not to display a row
of column names at the beginning of query results.  By default, this
option is enabled.  However, you may want to disable it in some
instances, such as when sending the output of 'mysql' into
another program that expects to see only data and not an initial header
line.

To disable column names, you can specify the option using any of these
forms:

     --disable-column-names
     --skip-column-names
     --column-names=0

The '--disable' and '--skip' prefixes and the '=0' suffix all have the
same effect: They turn the option off.

The 'enabled' form of the option may be specified in any of these ways:

     --column-names
     --enable-column-names
     --column-names=1

The values 'ON', 'TRUE', 'OFF', and 'FALSE' are also recognized for
boolean options (not case-sensitive).

If an option is prefixed by '--loose', a program does not exit with an
error if it does not recognize the option, but instead issues only a
warning:

     shell> mysql --loose-no-such-option
     mysql: WARNING: unknown option '--loose-no-such-option'

The '--loose' prefix can be useful when you run programs from multiple
installations of MySQL on the same machine and list options in an option
file.  An option that may not be recognized by all versions of a program
can be given using the '--loose' prefix (or 'loose' in an option file).
Versions of the program that recognize the option process it normally,
and versions that do not recognize it issue a warning and ignore it.

The '--maximum' prefix is available for 'mysqld' only and
permits a limit to be placed on how large client programs can set
session system variables.  To do this, use a '--maximum' prefix with the
variable name.  For example, '--maximum-max_heap_table_size=32M'
prevents any client from making the heap table size limit larger than
32M.

The '--maximum' prefix is intended for use with system variables that
have a session value.  If applied to a system variable that has only a
global value, an error occurs.  For example, with
'--maximum-back_log=200', the server produces this error:

     Maximum value of 'back_log' cannot be set

4.2.6 Using Option Files
------------------------

Most MySQL programs can read startup options from option files
(sometimes called configuration files).  Option files provide a
convenient way to specify commonly used options so that they need not be
entered on the command line each time you run a program.

To determine whether a program reads option files, invoke it with the
'--help' option.  (For 'mysqld', use '--verbose' and
'--help'.)  If the program reads option files, the help message
indicates which files it looks for and which option groups it
recognizes.

*Note*:

A MySQL program started with the '--no-defaults' option reads no option
files other than '.mylogin.cnf'.

Many option files are plain text files, created using any text editor.
The exception is the '.mylogin.cnf' file that contains login path
options.  This is an encrypted file created by the
'mysql_config_editor' utility.  See
mysql-config-editor.  A 'login path' is an option group that permits
only certain options: 'host', 'user', 'password', 'port' and 'socket'.
Client programs specify which login path to read from '.mylogin.cnf'
using the '--login-path' option.

To specify an alternative login path file name, set the
'MYSQL_TEST_LOGIN_FILE' environment variable.  This variable is used by
the 'mysql-test-run.pl' testing utility, but also is recognized by
'mysql_config_editor' and by MySQL clients such as
'mysql', 'mysqladmin', and so forth.

MySQL looks for option files in the order described in the following
discussion and reads any that exist.  If an option file you want to use
does not exist, create it using the appropriate method, as just
discussed.

*Note*:

Option files used with NDB Cluster programs are covered in
mysql-cluster-configuration.

On Windows, MySQL programs read startup options from the files shown in
the following table, in the specified order (files listed first are read
first, files read later take precedence).

*Option Files Read on Windows Systems*

File Name              Purpose

'%PROGRAMDATA%\MySQL\MySQLGlobal options
Server 5.7\my.ini',
'%PROGRAMDATA%\MySQL\MySQL
Server 5.7\my.cnf'

'%WINDIR%\my.ini',     Global options
'%WINDIR%\my.cnf'

'C:\my.ini',           Global options
'C:\my.cnf'

'BASEDIR\my.ini',      Global options
'BASEDIR\my.cnf'

'defaults-extra-file'  The file specified with '--defaults-extra-file',
                       if any

'%APPDATA%\MySQL\.mylogin.cnf'Login path options (clients only)

In the preceding table, '%PROGRAMDATA%' represents the file system
directory that contains application data for all users on the host.
This path defaults to 'C:\ProgramData' on Microsoft Windows Vista and
greater, and 'C:\Documents and Settings\All Users\Application Data' on
older versions of Microsoft Windows.

'%WINDIR%' represents the location of your Windows directory.  This is
commonly 'C:\WINDOWS'.  Use the following command to determine its exact
location from the value of the 'WINDIR' environment variable:

     C:\> echo %WINDIR%

'%APPDATA%' represents the value of the Windows application data
directory.  Use the following command to determine its exact location
from the value of the 'APPDATA' environment variable:

     C:\> echo %APPDATA%

BASEDIR represents the MySQL base installation directory.  When MySQL
5.7 has been installed using MySQL Installer, this is typically
'C:\PROGRAMDIR\MySQL\MySQL 5.7 Server' where PROGRAMDIR represents the
programs directory (usually 'Program Files' on English-language versions
of Windows), See mysql-installer.

On Unix and Unix-like systems, MySQL programs read startup options from
the files shown in the following table, in the specified order (files
listed first are read first, files read later take precedence).

*Note*:

On Unix platforms, MySQL ignores configuration files that are
world-writable.  This is intentional as a security measure.

*Option Files Read on Unix and Unix-Like Systems*

File Name              Purpose

'/etc/my.cnf'          Global options

'/etc/mysql/my.cnf'    Global options

'SYSCONFDIR/my.cnf'    Global options

'$MYSQL_HOME/my.cnf'   Server-specific options (server only)

'defaults-extra-file'  The file specified with '--defaults-extra-file',
                       if any

'~/.my.cnf'            User-specific options

'~/.mylogin.cnf'       User-specific login path options (clients only)

In the preceding table, '~' represents the current user's home directory
(the value of '$HOME').

SYSCONFDIR represents the directory specified with the 'SYSCONFDIR'
option to 'CMake' when MySQL was built.  By default, this is the 'etc'
directory located under the compiled-in installation directory.

'MYSQL_HOME' is an environment variable containing the path to the
directory in which the server-specific 'my.cnf' file resides.  If
'MYSQL_HOME' is not set and you start the server using the
'mysqld_safe' program, see 'mysqld_safe'.
sets it to BASEDIR, the MySQL base installation directory.

DATADIR is commonly '/usr/local/mysql/data', although this can vary per
platform or installation method.  The value is the data directory
location built in when MySQL was compiled, not the location specified
with the '--datadir' option when 'mysqld' starts.  Use of
'--datadir' at runtime has no effect on where the server looks for
option files that it reads before processing any options.

If multiple instances of a given option are found, the last instance
takes precedence, with one exception: For 'mysqld', the
_first_ instance of the '--user' option is used as a security
precaution, to prevent a user specified in an option file from being
overridden on the command line.

The following description of option file syntax applies to files that
you edit manually.  This excludes '.mylogin.cnf', which is created using
'mysql_config_editor' and is encrypted.

Any long option that may be given on the command line when running a
MySQL program can be given in an option file as well.  To get the list
of available options for a program, run it with the '--help' option.
(For 'mysqld', use '--verbose' and '--help'.)

The syntax for specifying options in an option file is similar to
command-line syntax (see command-line-options).  However, in an
option file, you omit the leading two dashes from the option name and
you specify only one option per line.  For example, '--quick' and
'--host=localhost' on the command line should be specified as 'quick'
and 'host=localhost' on separate lines in an option file.  To specify an
option of the form '--loose-OPT_NAME' in an option file, write it as
'loose-OPT_NAME'.

Empty lines in option files are ignored.  Nonempty lines can take any of
the following forms:

   * '#COMMENT', ';COMMENT'

     Comment lines start with '#' or ';'.  A '#' comment can start in
     the middle of a line as well.

   * '[GROUP]'

     GROUP is the name of the program or group for which you want to set
     options.  After a group line, any option-setting lines apply to the
     named group until the end of the option file or another group line
     is given.  Option group names are not case-sensitive.

   * 'OPT_NAME'

     This is equivalent to '--OPT_NAME' on the command line.

   * 'OPT_NAME=VALUE'

     This is equivalent to '--OPT_NAME=VALUE' on the command line.  In
     an option file, you can have spaces around the '=' character,
     something that is not true on the command line.  The value
     optionally can be enclosed within single quotation marks or double
     quotation marks, which is useful if the value contains a '#'
     comment character.

Leading and trailing spaces are automatically deleted from option names
and values.

You can use the escape sequences '\b', '\t', '\n', '\r', '\\', and '\s'
in option values to represent the backspace, tab, newline, carriage
return, backslash, and space characters.  In option files, these
escaping rules apply:

   * A backslash followed by a valid escape sequence character is
     converted to the character represented by the sequence.  For
     example, '\s' is converted to a space.

   * A backslash not followed by a valid escape sequence character
     remains unchanged.  For example, '\S' is retained as is.

The preceding rules mean that a literal backslash can be given as '\\',
or as '\' if it is not followed by a valid escape sequence character.

The rules for escape sequences in option files differ slightly from the
rules for escape sequences in string literals in SQL statements.  In the
latter context, if 'X' is not a valid escape sequence character, '\X'
becomes 'X' rather than '\X'.  See string-literals.

The escaping rules for option file values are especially pertinent for
Windows path names, which use '\' as a path name separator.  A separator
in a Windows path name must be written as '\\' if it is followed by an
escape sequence character.  It can be written as '\\' or '\' if it is
not.  Alternatively, '/' may be used in Windows path names and will be
treated as '\'.  Suppose that you want to specify a base directory of
'C:\Program Files\MySQL\MySQL Server 5.7' in an option file.  This can
be done several ways.  Some examples:

     basedir="C:\Program Files\MySQL\MySQL Server 5.7"
     basedir="C:\\Program Files\\MySQL\\MySQL Server 5.7"
     basedir="C:/Program Files/MySQL/MySQL Server 5.7"
     basedir=C:\\Program\sFiles\\MySQL\\MySQL\sServer\s5.7

If an option group name is the same as a program name, options in the
group apply specifically to that program.  For example, the '[mysqld]'
and '[mysql]' groups apply to the 'mysqld' server and the
'mysql' client program, respectively.

The '[client]' option group is read by all client programs provided in
MySQL distributions (but _not_ by 'mysqld').  To
understand how third-party client programs that use the C API can use
option files, see the C API documentation at mysql-options.

The '[client]' group enables you to specify options that apply to all
clients.  For example, '[client]' is the appropriate group to use to
specify the password for connecting to the server.  (But make sure that
the option file is accessible only by yourself, so that other people
cannot discover your password.)  Be sure not to put an option in the
'[client]' group unless it is recognized by _all_ client programs that
you use.  Programs that do not understand the option quit after
displaying an error message if you try to run them.

List more general option groups first and more specific groups later.
For example, a '[client]' group is more general because it is read by
all client programs, whereas a '[mysqldump]' group is read only by
'mysqldump'.  Options specified later override options
specified earlier, so putting the option groups in the order '[client]',
'[mysqldump]' enables 'mysqldump'.-specific options to
override '[client]' options.

Here is a typical global option file:

     [client]
     port=3306
     socket=/tmp/mysql.sock

     [mysqld]
     port=3306
     socket=/tmp/mysql.sock
     key_buffer_size=16M
     max_allowed_packet=8M

     [mysqldump]
     quick

Here is a typical user option file:

     [client]
     # The following password will be sent to all standard MySQL clients
     password="my password"

     [mysql]
     no-auto-rehash
     connect_timeout=2

To create option groups to be read only by 'mysqld'.
servers from specific MySQL release series, use groups with names of
'[mysqld-5.6]', '[mysqld-5.7]', and so forth.  The following group
indicates that the 'sql_mode' setting should be used only by MySQL
servers with 5.7.x version numbers:

     [mysqld-5.7]
     sql_mode=TRADITIONAL

It is possible to use '!include' directives in option files to include
other option files and '!includedir' to search specific directories for
option files.  For example, to include the '/home/mydir/myopt.cnf' file,
use the following directive:

     !include /home/mydir/myopt.cnf

To search the '/home/mydir' directory and read option files found there,
use this directive:

     !includedir /home/mydir

MySQL makes no guarantee about the order in which option files in the
directory will be read.

*Note*:

Any files to be found and included using the '!includedir' directive on
Unix operating systems _must_ have file names ending in '.cnf'.  On
Windows, this directive checks for files with the '.ini' or '.cnf'
extension.

Write the contents of an included option file like any other option
file.  That is, it should contain groups of options, each preceded by a
'[GROUP]' line that indicates the program to which the options apply.

While an included file is being processed, only those options in groups
that the current program is looking for are used.  Other groups are
ignored.  Suppose that a 'my.cnf' file contains this line:

     !include /home/mydir/myopt.cnf

And suppose that '/home/mydir/myopt.cnf' looks like this:

     [mysqladmin]
     force

     [mysqld]
     key_buffer_size=16M

If 'my.cnf' is processed by 'mysqld', only the '[mysqld]'
group in '/home/mydir/myopt.cnf' is used.  If the file is processed by
'mysqladmin', only the '[mysqladmin]' group is used.
If the file is processed by any other program, no options in
'/home/mydir/myopt.cnf' are used.

The '!includedir' directive is processed similarly except that all
option files in the named directory are read.

If an option file contains '!include' or '!includedir' directives, files
named by those directives are processed whenever the option file is
processed, no matter where they appear in the file.

4.2.7 Command-Line Options that Affect Option-File Handling
-----------------------------------------------------------

Most MySQL programs that support option files handle the following
options.  Because these options affect option-file handling, they must
be given on the command line and not in an option file.  To work
properly, each of these options must be given before other options, with
these exceptions:

   * '--print-defaults' may be used immediately after '--defaults-file',
     '--defaults-extra-file', or '--login-path'.

   * On Windows, if the server is started with the '--defaults-file' and
     '--install' options, '--install' must be first.  See
     windows-start-service.

When specifying file names as option values, avoid the use of the '~'
shell metacharacter because it might not be interpreted as you expect.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file and (on all platforms) before the login
     path file.  (For information about the order in which option files
     are used, see option-files.)  If the file does not exist or
     is otherwise inaccessible, an error occurs.  FILE_NAME is
     interpreted relative to the current directory if given as a
     relative path name rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Read only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, the 'mysql'
     client normally reads the '[client]' and '[mysql]' groups.
     If the '--defaults-group-suffix=_other' option is given, see
     'mysql' also reads the '[client_other]' and '[mysql_other]'
     groups.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

     A client program reads the option group corresponding to the named
     login path, in addition to option groups that the program reads by
     default.  Consider this command:

          shell> mysql --login-path=mypath

     By default, the 'mysql' client reads the '[client]'
     and '[mysql]' option groups.  So for the command shown, see
     'mysql' reads '[client]' and '[mysql]' from other option
     files, and '[client]', '[mysql]', and '[mypath]' from the login
     path file.

     Client programs read the login path file even when the
     '--no-defaults' option is used.

     To specify an alternate login path file name, set the
     'MYSQL_TEST_LOGIN_FILE' environment variable.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that client programs read the '.mylogin.cnf' login
     path file, if it exists, even when '--no-defaults' is used.  This
     permits passwords to be specified in a safer way than on the
     command line even if '--no-defaults' is present.  ('.mylogin.cnf'
     is created by the 'mysql_config_editor'.
     utility.  See mysql-config-editor.)

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.  Password values are masked.

4.2.8 Using Options to Set Program Variables
--------------------------------------------

Many MySQL programs have internal variables that can be set at runtime
using the 'SET' statement.  See
set-variable, and using-system-variables.

Most of these program variables also can be set at server startup by
using the same syntax that applies to specifying program options.  For
example, see 'mysql' has a 'max_allowed_packet' variable that
controls the maximum size of its communication buffer.  To set the
'max_allowed_packet' variable for 'mysql' to a value of
16MB, use either of the following commands:

     shell> mysql --max_allowed_packet=16777216
     shell> mysql --max_allowed_packet=16M

The first command specifies the value in bytes.  The second specifies
the value in megabytes.  For variables that take a numeric value, the
value can be given with a suffix of 'K', 'M', or 'G' (either uppercase
or lowercase) to indicate a multiplier of 1024, 1024^2 or 1024^3.  (For
example, when used to set 'max_allowed_packet', the suffixes indicate
units of kilobytes, megabytes, or gigabytes.)

In an option file, variable settings are given without the leading
dashes:

     [mysql]
     max_allowed_packet=16777216

Or:

     [mysql]
     max_allowed_packet=16M

If you like, underscores in a variable name can be specified as dashes.
The following option groups are equivalent.  Both set the size of the
server's key buffer to 512MB:

     [mysqld]
     key_buffer_size=512M

     [mysqld]
     key-buffer-size=512M

A variable can be specified by writing it in full or as any unambiguous
prefix.  For example, the 'max_allowed_packet' variable can be set for
'mysql' as '--max_a', but not as '--max' because the
latter is ambiguous:

     shell> mysql --max=1000000
     mysql: ambiguous option '--max=1000000' (max_allowed_packet, max_join_size)

Be aware that the use of variable prefixes can cause problems in the
event that new variables are implemented for a program.  A prefix that
is unambiguous now might become ambiguous in the future.

Suffixes for specifying a value multiplier can be used when setting a
variable at server startup, but not to set the value with 'SET'
at runtime.  On the other hand, with 'SET',
you can assign a variable's value using an expression,
which is not true when you set a variable at server startup.  For
example, the first of the following lines is legal at server startup,
but the second is not:

     shell> mysql --max_allowed_packet=16M
     shell> mysql --max_allowed_packet=16*1024*1024

Conversely, the second of the following lines is legal at runtime, but
the first is not:

     mysql> SET GLOBAL max_allowed_packet=16M;
     mysql> SET GLOBAL max_allowed_packet=16*1024*1024;

4.2.9 Option Defaults, Options Expecting Values, and the = Sign
---------------------------------------------------------------

By convention, long forms of options that assign a value are written
with an equals ('=') sign, like this:

     shell> mysql --host=tonfisk --user=jon

For options that require a value (that is, not having a default value),
the equals sign is not required, and so the following is also valid:

     shell> mysql --host tonfisk --user jon

In both cases, the 'mysql' client attempts to connect to a
MySQL server running on the host named 'tonfisk' using an account with
the user name 'jon'.

Due to this behavior, problems can occasionally arise when no value is
provided for an option that expects one.  Consider the following
example, where a user connects to a MySQL server running on host
'tonfisk' as user 'jon':

     shell> mysql --host 85.224.35.45 --user jon
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 3
     Server version: 5.7.23 Source distribution

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql> SELECT CURRENT_USER();
     +----------------+
     | CURRENT_USER() |
     +----------------+
     | jon@%          |
     +----------------+
     1 row in set (0.00 sec)

Omitting the required value for one of these option yields an error,
such as the one shown here:

     shell> mysql --host 85.224.35.45 --user
     mysql: option '--user' requires an argument

In this case, see 'mysql' was unable to find a value following
the '--user' option because nothing came after it on the command line.
However, if you omit the value for an option that is _not_ the last
option to be used, you obtain a different error that you may not be
expecting:

     shell> mysql --host --user jon
     ERROR 2005 (HY000): Unknown MySQL server host '--user' (1)

Because 'mysql' assumes that any string following '--host'
on the command line is a host name, '--host' '--user' is interpreted as
'--host=--user', and the client attempts to connect to a MySQL server
running on a host named '--user'.

Options having default values always require an equals sign when
assigning a value; failing to do so causes an error.  For example, the
MySQL server '--log-error' option has the default value 'HOST_NAME.err',
where HOST_NAME is the name of the host on which MySQL is running.
Assume that you are running MySQL on a computer whose host name is
'tonfisk', and consider the following invocation of 'mysqld_safe'.:

     shell> mysqld_safe &
     [1] 11699
     shell> 080112 12:53:40 mysqld_safe Logging to '/usr/local/mysql/var/tonfisk.err'.
     080112 12:53:40 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var
     shell>

After shutting down the server, restart it as follows:

     shell> mysqld_safe --log-error &
     [1] 11699
     shell> 080112 12:53:40 mysqld_safe Logging to '/usr/local/mysql/var/tonfisk.err'.
     080112 12:53:40 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var
     shell>

The result is the same, since '--log-error' is not followed by anything
else on the command line, and it supplies its own default value.  (The
'&' character tells the operating system to run MySQL in the background;
it is ignored by MySQL itself.)  Now suppose that you wish to log errors
to a file named 'my-errors.err'.  You might try starting the server with
'--log-error my-errors', but this does not have the intended effect, as
shown here:

     shell> mysqld_safe --log-error my-errors &
     [1] 31357
     shell> 080111 22:53:31 mysqld_safe Logging to '/usr/local/mysql/var/tonfisk.err'.
     080111 22:53:32 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var
     080111 22:53:34 mysqld_safe mysqld from pid file /usr/local/mysql/var/tonfisk.pid ended

     [1]+  Done                    ./mysqld_safe --log-error my-errors

The server attempted to start using '/usr/local/mysql/var/tonfisk.err'
as the error log, but then shut down.  Examining the last few lines of
this file shows the reason:

     shell> tail /usr/local/mysql/var/tonfisk.err
     2013-09-24T15:36:22.278034Z 0 [ERROR] Too many arguments (first extra is 'my-errors').
     2013-09-24T15:36:22.278059Z 0 [Note] Use --verbose --help to get a list of available options!
     2013-09-24T15:36:22.278076Z 0 [ERROR] Aborting
     2013-09-24T15:36:22.279704Z 0 [Note] InnoDB: Starting shutdown...
     2013-09-24T15:36:23.777471Z 0 [Note] InnoDB: Shutdown completed; log sequence number 2319086
     2013-09-24T15:36:23.780134Z 0 [Note] mysqld: Shutdown complete

Because the '--log-error' option supplies a default value, you must use
an equals sign to assign a different value to it, as shown here:

     shell> mysqld_safe --log-error=my-errors &
     [1] 31437
     shell> 080111 22:54:15 mysqld_safe Logging to '/usr/local/mysql/var/my-errors.err'.
     080111 22:54:15 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var

     shell>

Now the server has been started successfully, and is logging errors to
the file '/usr/local/mysql/var/my-errors.err'.

Similar issues can arise when specifying option values in option files.
For example, consider a 'my.cnf' file that contains the following:

     [mysql]

     host
     user

When the 'mysql' client reads this file, these entries are
parsed as '--host' '--user' or '--host=--user', with the result shown
here:

     shell> mysql
     ERROR 2005 (HY000): Unknown MySQL server host '--user' (1)

However, in option files, an equals sign is not assumed.  Suppose the
'my.cnf' file is as shown here:

     [mysql]

     user jon

Trying to start 'mysql' in this case causes a different
error:

     shell> mysql
     mysql: unknown option '--user jon'

A similar error would occur if you were to write 'host tonfisk' in the
option file rather than 'host=tonfisk'.  Instead, you must use the
equals sign:

     [mysql]

     user=jon

Now the login attempt succeeds:

     shell> mysql
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 5
     Server version: 5.7.23 Source distribution

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql> SELECT USER();
     +---------------+
     | USER()        |
     +---------------+
     | jon@localhost |
     +---------------+
     1 row in set (0.00 sec)

This is not the same behavior as with the command line, where the equals
sign is not required:

     shell> mysql --user jon --host tonfisk
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 6
     Server version: 5.7.23 Source distribution

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql> SELECT USER();
     +---------------+
     | USER()        |
     +---------------+
     | jon@tonfisk   |
     +---------------+
     1 row in set (0.00 sec)

Specifying an option requiring a value without a value in an option file
causes the server to abort with an error.  Suppose that 'my.cnf'
contains the following:

     [mysqld]
     log_error
     relay_log
     relay_log_index

This causes the server to fail on startup, as shown here:

     shell> mysqld_safe &

     130924 10:41:46 mysqld_safe Logging to '/home/jon/bin/mysql/var/tonfisk.err'.
     130924 10:41:46 mysqld_safe Starting mysqld daemon with databases from /home/jon/bin/mysql/var
     130924 10:41:47 mysqld_safe mysqld from pid file /home/jon/bin/mysql/var/tonfisk.pid ended

The '--log-error' option does not require an argument; however, the
'--relay-log' option requires one, as shown in the error log (which in
the absence of a specified value, defaults to 'DATADIR/HOSTNAME.err'):

     shell> tail -n 3 ../var/tonfisk.err

     130924 10:41:46 mysqld_safe Starting mysqld daemon with databases from /home/jon/bin/mysql/var
     2013-09-24T15:41:47.217180Z 0 [ERROR] /home/jon/bin/mysql/libexec/mysqld: option '--relay-log' requires an argument
     2013-09-24T15:41:47.217479Z 0 [ERROR] Aborting

This is a change from previous behavior, where the server would have
interpreted the last two lines in the example 'my.cnf' file as
'--relay-log=relay_log_index' and created a relay log file using
'relay_log_index' as the base name.  (Bug #25192)

4.2.10 Setting Environment Variables
------------------------------------

Environment variables can be set at the command prompt to affect the
current invocation of your command processor, or set permanently to
affect future invocations.  To set a variable permanently, you can set
it in a startup file or by using the interface provided by your system
for this purpose.  Consult the documentation for your command
interpreter for specific details.  See environment-variables, lists
all environment variables that affect MySQL program operation.

To specify a value for an environment variable, use the syntax
appropriate for your command processor.  For example, on Windows, you
can set the 'USER' variable to specify your MySQL account name.  To do
so, use this syntax:

     SET USER=YOUR_NAME

The syntax on Unix depends on your shell.  Suppose that you want to
specify the TCP/IP port number using the 'MYSQL_TCP_PORT' variable.
Typical syntax (such as for 'sh', 'ksh', 'bash', 'zsh', and so on) is as
follows:

     MYSQL_TCP_PORT=3306
     export MYSQL_TCP_PORT

The first command sets the variable, and the 'export' command exports
the variable to the shell environment so that its value becomes
accessible to MySQL and other processes.

For 'csh' and 'tcsh', use 'setenv' to make the shell variable available
to the environment:

     setenv MYSQL_TCP_PORT 3306

The commands to set environment variables can be executed at your
command prompt to take effect immediately, but the settings persist only
until you log out.  To have the settings take effect each time you log
in, use the interface provided by your system or place the appropriate
command or commands in a startup file that your command interpreter
reads each time it starts.

On Windows, you can set environment variables using the System Control
Panel (under Advanced).

On Unix, typical shell startup files are '.bashrc' or '.bash_profile'
for 'bash', or '.tcshrc' for 'tcsh'.

Suppose that your MySQL programs are installed in '/usr/local/mysql/bin'
and that you want to make it easy to invoke these programs.  To do this,
set the value of the 'PATH' environment variable to include that
directory.  For example, if your shell is 'bash', add the following line
to your '.bashrc' file:

     PATH=${PATH}:/usr/local/mysql/bin

'bash' uses different startup files for login and nonlogin shells, so
you might want to add the setting to '.bashrc' for login shells and to
'.bash_profile' for nonlogin shells to make sure that 'PATH' is set
regardless.

If your shell is 'tcsh', add the following line to your '.tcshrc' file:

     setenv PATH ${PATH}:/usr/local/mysql/bin

If the appropriate startup file does not exist in your home directory,
create it with a text editor.

After modifying your 'PATH' setting, open a new console window on
Windows or log in again on Unix so that the setting goes into effect.

4.3 MySQL Server and Server-Startup Programs
============================================

This section describes 'mysqld', the MySQL server, and
several programs that are used to start the server.

4.3.1 'mysqld' -- The MySQL Server
----------------------------------

See 'mysqld', also known as MySQL Server, is the main program
that does most of the work in a MySQL installation.  MySQL Server
manages access to the MySQL data directory that contains databases and
tables.  The data directory is also the default location for other
information such as log files and status files.

*Note*:

Some installation packages contain a debugging version of the server
named 'mysqld-debug'.  Invoke this version instead of
'mysqld' for debugging support, memory allocation
checking, and trace file support (see making-trace-files).

When MySQL server starts, it listens for network connections from client
programs and manages access to databases on behalf of those clients.

The 'mysqld' program has many options that can be
specified at startup.  For a complete list of options, run this command:

     shell> mysqld --verbose --help

MySQL Server also has a set of system variables that affect its
operation as it runs.  System variables can be set at server startup,
and many of them can be changed at runtime to effect dynamic server
reconfiguration.  MySQL Server also has a set of status variables that
provide information about its operation.  You can monitor these status
variables to access runtime performance characteristics.

For a full description of MySQL Server command options, system
variables, and status variables, see mysqld-server.  For
information about installing MySQL and setting up the initial
configuration, see installing.

4.3.2 'mysqld_safe' -- MySQL Server Startup Script
--------------------------------------------------

'mysqld_safe' is the recommended way to start a
'mysqld' server on Unix.  'mysqld_safe'
adds some safety features such as restarting the server
when an error occurs and logging runtime information to an error log.  A
description of error logging is given later in this section.

*Note*:

For some Linux platforms, MySQL installation from RPM or Debian packages
includes systemd support for managing MySQL server startup and shutdown.
On these platforms, see 'mysqld_safe' is not installed
because it is unnecessary.  For more information, see
using-systemd.

'mysqld_safe' tries to start an executable named
'mysqld'.  To override the default behavior and specify
explicitly the name of the server you want to run, specify a '--mysqld'
or '--mysqld-version' option to 'mysqld_safe'.  You
can also use '--ledir' to indicate the directory where
'mysqld_safe' should look for the server.

Many of the options to 'mysqld_safe' are the same as
the options to 'mysqld'.  See server-options.

Options unknown to 'mysqld_safe' are passed to
'mysqld' if they are specified on the command line, but ignored
if they are specified in the '[mysqld_safe]' group of an option file.
See option-files.

'mysqld_safe' reads all options from the '[mysqld]',
'[server]', and '[mysqld_safe]' sections in option files.  For example,
if you specify a '[mysqld]' section like this, see 'mysqld_safe'
will find and use the '--log-error' option:

     [mysqld]
     log-error=error.log

For backward compatibility, see 'mysqld_safe' also reads
'[safe_mysqld]' sections, but to be current you should rename such
sections to '[mysqld_safe]'.

'mysqld_safe' accepts options on the command line
and in option files, as described in the following table.  For
information about option files used by MySQL programs, see
option-files.

*mysqld_safe Options*

Format                 Description                              Introduced

-basedir               Path to MySQL installation directory

-core-file-size        Size of core file that mysqld should
                       be able to create

-datadir               Path to data directory

-defaults-extra-file   Read named option file in addition to
                       usual option files

-defaults-file         Read only named option file

-help                  Display help message and exit

-ledir                 Path to directory where server is
                       located

-log-error             Write error log to named file

-malloc-lib            Alternative malloc library to use for
                       mysqld

-mysqld                Name of server program to start (in
                       ledir directory)

-mysqld-safe-log-timestampsTimestamp format for logging         5.7.11

-mysqld-version        Suffix for server program name

-nice                  Use nice program to set server
                       scheduling priority

-no-defaults           Read no option files

-open-files-limit      Number of files that mysqld should be
                       able to open

-pid-file              Path name of server process ID file

-plugin-dir            Directory where plugins are installed

-port                  Port number on which to listen for
                       TCP/IP connections

-skip-kill-mysqld      Do not try to kill stray mysqld
                       processes

-skip-syslog           Do not write error messages to syslog;
                       use error log file

-socket                Socket file on which to listen for
                       Unix socket connections

-syslog                Write error messages to syslog

-syslog-tag            Tag suffix for messages written to
                       syslog

-timezone              Set TZ time zone environment variable
                       to named value

-user                  Run mysqld as user having name
                       user_name or numeric user ID user_id

   *
     '--help'

     Display a help message and exit.

   *
     '--basedir=DIR_NAME'

     The path to the MySQL installation directory.

   *
     '--core-file-size=SIZE'

     The size of the core file that 'mysqld' should be
     able to create.  The option value is passed to 'ulimit -c'.

   *
     '--datadir=DIR_NAME'

     The path to the data directory.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file in addition to the usual option files.  If
     the file does not exist or is otherwise inaccessible, the server
     will exit with an error.  FILE_NAME is interpreted relative to the
     current directory if given as a relative path name rather than a
     full path name.  This must be the first option on the command line
     if it is used.

     For additional information about this option, see
     option-file-options.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, the server will exit with an error.
     FILE_NAME is interpreted relative to the current directory if given
     as a relative path name rather than a full path name.  This must be
     the first option on the command line if it is used.

     For additional information about this option, see
     option-file-options.

   *
     '--ledir=DIR_NAME'

     If 'mysqld_safe' cannot find the server, use
     this option to indicate the path name to the directory where the
     server is located.

     As of MySQL 5.7.17, this option is accepted only on the command
     line, not in option files.  On platforms that use systemd, the
     value can be specified in the value of 'MYSQLD_OPTS'.  See
     using-systemd.

   *
     '--log-error=FILE_NAME'

     Write the error log to the given file.  See error-log.

   *
     '--mysqld-safe-log-timestamps'

     This option controls the format for timestamps in log output
     produced by 'mysqld_safe'.  The following list
     describes the permitted values.  For any other value, see
     'mysqld_safe' logs a warning and uses 'UTC' format.

        * 'UTC', 'utc'

          ISO 8601 UTC format (same as '--log_timestamps=UTC' for the
          server).  This is the default.

        * 'SYSTEM', 'system'

          ISO 8601 local time format (same as '--log_timestamps=SYSTEM'
          for the server).

        * 'HYPHEN', 'hyphen'

          'YY-MM-DD h:mm:ss' format, as in 'mysqld_safe'
          for MySQL 5.6.

        * 'LEGACY', 'legacy'

          'YYMMDD hh:mm:ss' format, as in 'mysqld_safe'
          prior to MySQL 5.6.

     This option was added in MySQL 5.7.11.

   *
     '--malloc-lib=[LIB_NAME]'

     The name of the library to use for memory allocation instead of the
     system 'malloc()' library.  As of MySQL 5.7.15, the option value
     must be one of the directories '/usr/lib', '/usr/lib64',
     '/usr/lib/i386-linux-gnu', or '/usr/lib/x86_64-linux-gnu'.  Prior
     to MySQL 5.7.15, any library can be used by specifying its path
     name, but there is a shortcut form to enable use of the 'tcmalloc'
     library that is shipped with binary MySQL distributions for Linux
     in MySQL 5.7.  It is possible that the shortcut form will not work
     under certain configurations, in which case you should specify a
     path name instead.

     *Note*:

     As of MySQL 5.7.13, MySQL distributions no longer include a
     'tcmalloc' library.

     The '--malloc-lib' option works by modifying the 'LD_PRELOAD'
     environment value to affect dynamic linking to enable the loader to
     find the memory-allocation library when 'mysqld'.
     runs:

        * If the option is not given, or is given without a value
          ('--malloc-lib='), 'LD_PRELOAD' is not modified and no attempt
          is made to use 'tcmalloc'.

        * If the option is given as '--malloc-lib=tcmalloc', see
          'mysqld_safe' looks for a 'tcmalloc' library in
          '/usr/lib' and then in the MySQL 'pkglibdir' location (for
          example, '/usr/local/mysql/lib' or whatever is appropriate).
          If 'tmalloc' is found, its path name is added to the beginning
          of the 'LD_PRELOAD' value for 'mysqld'.  If
          'tcmalloc' is not found, see 'mysqld_safe'.
          aborts with an error.

        * If the option is given as
          '--malloc-lib=/PATH/TO/SOME/LIBRARY', that full path is added
          to the beginning of the 'LD_PRELOAD' value.  If the full path
          points to a nonexistent or unreadable file, see
          'mysqld_safe' aborts with an error.

        * For cases where 'mysqld_safe' adds a path
          name to 'LD_PRELOAD', it adds the path to the beginning of any
          existing value the variable already has.

     *Note*:

     On systems that manage the server using systemd, see
     'mysqld_safe' is not available.  Instead, specify the
     allocation library by setting 'LD_PRELOAD' in
     '/etc/sysconfig/mysql'.

     Linux users can use the 'libtcmalloc_minimal.so' included in binary
     packages by adding these lines to the 'my.cnf' file:

          [mysqld_safe]
          malloc-lib=tcmalloc

     Those lines also suffice for users on any platform who have
     installed a 'tcmalloc' package in '/usr/lib'.  To use a specific
     'tcmalloc' library, specify its full path name.  Example:

          [mysqld_safe]
          malloc-lib=/opt/lib/libtcmalloc_minimal.so

   *
     '--mysqld=PROG_NAME'

     The name of the server program (in the 'ledir' directory) that you
     want to start.  This option is needed if you use the MySQL binary
     distribution but have the data directory outside of the binary
     distribution.  If 'mysqld_safe' cannot find the
     server, use the '--ledir' option to indicate the path name to the
     directory where the server is located.

     As of MySQL 5.7.15, this option is accepted only on the command
     line, not in option files.  On platforms that use systemd, the
     value can be specified in the value of 'MYSQLD_OPTS'.  See
     using-systemd.

   *
     '--mysqld-version=SUFFIX'

     This option is similar to the '--mysqld' option, but you specify
     only the suffix for the server program name.  The base name is
     assumed to be 'mysqld'.  For example, if you use
     '--mysqld-version=debug', see 'mysqld_safe' starts
     the 'mysqld-debug' program in the 'ledir' directory.
     If the argument to '--mysqld-version' is empty, see
     'mysqld_safe' uses 'mysqld' in the
     'ledir' directory.

     As of MySQL 5.7.15, this option is accepted only on the command
     line, not in option files.  On platforms that use systemd, the
     value can be specified in the value of 'MYSQLD_OPTS'.  See
     using-systemd.

   *
     '--nice=PRIORITY'

     Use the 'nice' program to set the server's scheduling priority to
     the given value.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.  This must be the first
     option on the command line if it is used.

     For additional information about this option, see
     option-file-options.

   *
     '--open-files-limit=COUNT'

     The number of files that 'mysqld' should be able to
     open.  The option value is passed to 'ulimit -n'.

     *Note*:

     You must start 'mysqld_safe' as 'root' for this
     to function properly.

   *
     '--pid-file=FILE_NAME'

     The path name that 'mysqld' should use for its
     process ID file.

     From MySQL 5.7.2 to 5.7.17, see 'mysqld_safe' has
     its own process ID file, which is always named 'mysqld_safe.pid'
     and located in the MySQL data directory.

   *
     '--plugin-dir=DIR_NAME'

     The path name of the plugin directory.

   *
     '--port=PORT_NUM'

     The port number that the server should use when listening for
     TCP/IP connections.  The port number must be 1024 or higher unless
     the server is started by the 'root' system user.

   *
     '--skip-kill-mysqld'

     Do not try to kill stray 'mysqld' processes at
     startup.  This option works only on Linux.

   *
     '--socket=PATH'

     The Unix socket file that the server should use when listening for
     local connections.

   *
     '--syslog', '--skip-syslog'

     '--syslog' causes error messages to be sent to 'syslog' on systems
     that support the 'logger' program.  '--skip-syslog' suppresses the
     use of 'syslog'; messages are written to an error log file.

     When 'syslog' is used, the 'daemon.err' facility/severity is used
     for all log messages.

     Using these options to control 'mysqld' logging is
     deprecated as of MySQL 5.7.5.  Use the server 'log_syslog' system
     variable instead.  To control the facility, use the server
     'log_syslog_facility' system variable.  See error-log.

   *
     '--syslog-tag=TAG'

     For logging to 'syslog', messages from 'mysqld_safe'
     and 'mysqld' are written with
     identifiers of 'mysqld_safe' and 'mysqld', respectively.  To
     specify a suffix for the identifiers, use '--syslog-tag=TAG', which
     modifies the identifiers to be 'mysqld_safe-TAG' and 'mysqld-TAG'.

     Using this option to control 'mysqld' logging is
     deprecated as of MySQL 5.7.5.  Use the server 'log_syslog_tag'
     system variable instead.  See error-log.

   *
     '--timezone=TIMEZONE'

     Set the 'TZ' time zone environment variable to the given option
     value.  Consult your operating system documentation for legal time
     zone specification formats.

   *
     '--user={USER_NAME|USER_ID}'

     Run the 'mysqld' server as the user having the name
     USER_NAME or the numeric user ID USER_ID.  ('User' in this context
     refers to a system login account, not a MySQL user listed in the
     grant tables.)

If you execute 'mysqld_safe' with the
'--defaults-file' or '--defaults-extra-file' option to name an option
file, the option must be the first one given on the command line or the
option file will not be used.  For example, this command will not use
the named option file:

     mysql> mysqld_safe --port=PORT_NUM --defaults-file=FILE_NAME

Instead, use the following command:

     mysql> mysqld_safe --defaults-file=FILE_NAME --port=PORT_NUM

The 'mysqld_safe' script is written so that it
normally can start a server that was installed from either a source or a
binary distribution of MySQL, even though these types of distributions
typically install the server in slightly different locations.  (See
installation-layouts.)  See 'mysqld_safe'.
expects one of the following conditions to be true:

   * The server and databases can be found relative to the working
     directory (the directory from which 'mysqld_safe'
     is invoked).  For binary distributions, see
     'mysqld_safe' looks under its working directory for
     'bin' and 'data' directories.  For source distributions, it looks
     for 'libexec' and 'var' directories.  This condition should be met
     if you execute 'mysqld_safe' from your MySQL
     installation directory (for example, '/usr/local/mysql' for a
     binary distribution).

   * If the server and databases cannot be found relative to the working
     directory, see 'mysqld_safe' attempts to locate
     them by absolute path names.  Typical locations are
     '/usr/local/libexec' and '/usr/local/var'.  The actual locations
     are determined from the values configured into the distribution at
     the time it was built.  They should be correct if MySQL is
     installed in the location specified at configuration time.

Because 'mysqld_safe' tries to find the server and
databases relative to its own working directory, you can install a
binary distribution of MySQL anywhere, as long as you run
'mysqld_safe' from the MySQL installation directory:

     shell> cd MYSQL_INSTALLATION_DIRECTORY
     shell> bin/mysqld_safe &

If 'mysqld_safe' fails, even when invoked from the
MySQL installation directory, specify the '--ledir' and '--datadir'
options to indicate the directories in which the server and databases
are located on your system.

'mysqld_safe' tries to use the 'sleep' and 'date'
system utilities to determine how many times per second it has attempted
to start.  If these utilities are present and the attempted starts per
second is greater than 5, see 'mysqld_safe' waits 1 full
second before starting again.  This is intended to prevent excessive CPU
usage in the event of repeated failures.  (Bug #11761530, Bug #54035)

When you use 'mysqld_safe' to start 'mysqld',
see 'mysqld_safe' arranges for error (and
notice) messages from itself and from 'mysqld' to go to
the same destination.

There are several 'mysqld_safe' options for
controlling the destination of these messages:

   * '--log-error=FILE_NAME': Write error messages to the named error
     file.

   * '--syslog': Write error messages to 'syslog' on systems that
     support the 'logger' program.

   * '--skip-syslog': Do not write error messages to 'syslog'.  Messages
     are written to the default error log file ('HOST_NAME.err' in the
     data directory), or to a named file if the '--log-error' option is
     given.

If none of these options is given, the default is '--skip-syslog'.

When 'mysqld_safe' writes a message, notices go to
the logging destination ('syslog' or the error log file) and 'stdout'.
Errors go to the logging destination and 'stderr'.

*Note*:

Controlling 'mysqld' logging from 'mysqld_safe'
is deprecated as of MySQL 5.7.5.  Use the server's native
'syslog' support instead.  For more information, see error-log.

4.3.3 'mysql.server' -- MySQL Server Startup Script
---------------------------------------------------

MySQL distributions on Unix and Unix-like system include a script named
'mysql.server', which starts the MySQL server using
'mysqld_safe'.  It can be used on systems such as
Linux and Solaris that use System V-style run directories to start and
stop system services.  It is also used by the macOS Startup Item for
MySQL.

'mysql.server' is the script name as used within
the MySQL source tree.  The installed name might be different; for
example, see 'mysqld' or 'mysql'.  In the
following discussion, adjust the name 'mysql.server'
as appropriate for your system.

*Note*:

For some Linux platforms, MySQL installation from RPM or Debian packages
includes systemd support for managing MySQL server startup and shutdown.
On these platforms, see 'mysql.server' and
'mysqld_safe' are not installed because they are
unnecessary.  For more information, see using-systemd.

To start or stop the server manually using the 'mysql.server'
script, invoke it from the command line with 'start' or
'stop' arguments:

     shell> mysql.server start
     shell> mysql.server stop

'mysql.server' changes location to the MySQL
installation directory, then invokes 'mysqld_safe'.
To run the server as some specific user, add an appropriate 'user'
option to the '[mysqld]' group of the global '/etc/my.cnf' option file,
as shown later in this section.  (It is possible that you must edit
'mysql.server' if you've installed a binary
distribution of MySQL in a nonstandard location.  Modify it to change
location into the proper directory before it runs 'mysqld_safe'.
If you do this, your modified version of
'mysql.server' may be overwritten if you upgrade MySQL in
the future; make a copy of your edited version that you can reinstall.)

'mysql.server stop' stops the server by sending a
signal to it.  You can also stop the server manually by executing
'mysqladmin shutdown'.

To start and stop MySQL automatically on your server, you must add start
and stop commands to the appropriate places in your '/etc/rc*' files:

   * If you use the Linux server RPM package
     ('MySQL-server-VERSION.rpm'), or a native Linux package
     installation, the 'mysql.server' script may be
     installed in the '/etc/init.d' directory with the name 'mysqld' or
     'mysql'.  See linux-installation-rpm, for more information
     on the Linux RPM packages.

   * If you install MySQL from a source distribution or using a binary
     distribution format that does not install 'mysql.server'
     automatically, you can install the script manually.
     It can be found in the 'support-files' directory under the MySQL
     installation directory or in a MySQL source tree.  Copy the script
     to the '/etc/init.d' directory with the name 'mysql'.
     and make it executable:

          shell> cp mysql.server /etc/init.d/mysql
          shell> chmod +x /etc/init.d/mysql

     After installing the script, the commands needed to activate it to
     run at system startup depend on your operating system.  On Linux,
     you can use 'chkconfig':

          shell> chkconfig --add mysql

     On some Linux systems, the following command also seems to be
     necessary to fully enable the 'mysql' script:

          shell> chkconfig --level 345 mysql on

   * On FreeBSD, startup scripts generally should go in
     '/usr/local/etc/rc.d/'.  Install the 'mysql.server' script as
     '/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup.
     The 'rc(8)' manual page states that scripts in this directory are
     executed only if their base name matches the '*.sh' shell file name
     pattern.  Any other files or directories present within the
     directory are silently ignored.

   * As an alternative to the preceding setup, some operating systems
     also use '/etc/rc.local' or '/etc/init.d/boot.local' to start
     additional services on startup.  To start up MySQL using this
     method, append a command like the one following to the appropriate
     startup file:

          /bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'

   * For other systems, consult your operating system documentation to
     see how to install startup scripts.

'mysql.server' reads options from the
'[mysql.server]' and '[mysqld]' sections of option files.  For backward
compatibility, it also reads '[mysql_server]' sections, but to be
current you should rename such sections to '[mysql.server]'.

You can add options for 'mysql.server' in a global
'/etc/my.cnf' file.  A typical 'my.cnf' file might look like this:

     [mysqld]
     datadir=/usr/local/mysql/var
     socket=/var/tmp/mysql.sock
     port=3306
     user=mysql

     [mysql.server]
     basedir=/usr/local/mysql

The 'mysql.server' script supports the options
shown in the following table.  If specified, they _must_ be placed in an
option file, not on the command line.  'mysql.server'
supports only 'start' and 'stop' as command-line
arguments.

*mysql.server Option-File Options*

Option Name    Description                                        Type

'basedir'      Path to MySQL installation directory               directory
                                                                  name

'datadir'      Path to MySQL data directory                       directory
                                                                  name

'pid-file'     File in which server should write its process ID   file
                                                                  name

'service-startup-timeout'How long to wait for server startup      integer

   *
     'basedir=DIR_NAME'

     The path to the MySQL installation directory.

   *
     'datadir=DIR_NAME'

     The path to the MySQL data directory.

   *
     'pid-file=FILE_NAME'

     The path name of the file in which the server should write its
     process ID.

     If this option is not given, see 'mysql.server'.
     uses a default value of 'HOST_NAME.pid'.  The PID file value passed
     to 'mysqld_safe' overrides any value specified
     in the '[mysqld_safe]' option file group.  Because
     'mysql.server' reads the '[mysqld]' option file
     group but not the '[mysqld_safe]' group, you can ensure that
     'mysqld_safe' gets the same value when invoked from
     'mysql.server' as when invoked manually by
     putting the same 'pid-file' setting in both the '[mysqld_safe]' and
     '[mysqld]' groups.

   *
     'service-startup-timeout=SECONDS'

     How long in seconds to wait for confirmation of server startup.  If
     the server does not start within this time, see 'mysql.server'
     exits with an error.  The default value is 900.  A
     value of 0 means not to wait at all for startup.  Negative values
     mean to wait forever (no timeout).

4.3.4 'mysqld_multi' -- Manage Multiple MySQL Servers
-----------------------------------------------------

'mysqld_multi' is designed to manage several
'mysqld' processes that listen for connections on different
Unix socket files and TCP/IP ports.  It can start or stop servers, or
report their current status.

*Note*:

For some Linux platforms, MySQL installation from RPM or Debian packages
includes systemd support for managing MySQL server startup and shutdown.
On these platforms, see 'mysqld_multi' is not installed
because it is unnecessary.  For information about using systemd to
handle multiple MySQL instances, see using-systemd.

'mysqld_multi' searches for groups named
'[mysqldN]' in 'my.cnf' (or in the file named by the '--defaults-file'
option).  N can be any positive integer.  This number is referred to in
the following discussion as the option group number, or GNR.  Group
numbers distinguish option groups from one another and are used as
arguments to 'mysqld_multi' to specify which
servers you want to start, stop, or obtain a status report for.  Options
listed in these groups are the same that you would use in the '[mysqld]'
group used for starting 'mysqld'.  (See, for example,
see automatic-start.)  However, when using multiple servers, it is
necessary that each one use its own value for options such as the Unix
socket file and TCP/IP port number.  For more information on which
options must be unique per server in a multiple-server environment, see
multiple-servers.

To invoke 'mysqld_multi', use the following syntax:

     shell> mysqld_multi [OPTIONS] {start|stop|reload|report} [GNR[,GNR] ...]

'start', 'stop', 'reload' (stop and restart), and 'report' indicate
which operation to perform.  You can perform the designated operation
for a single server or multiple servers, depending on the GNR list that
follows the option name.  If there is no list, see 'mysqld_multi'
performs the operation for all servers in the option file.

Each GNR value represents an option group number or range of group
numbers.  The value should be the number at the end of the group name in
the option file.  For example, the GNR for a group named '[mysqld17]' is
'17'.  To specify a range of numbers, separate the first and last
numbers by a dash.  The GNR value '10-13' represents groups '[mysqld10]'
through '[mysqld13]'.  Multiple groups or group ranges can be specified
on the command line, separated by commas.  There must be no whitespace
characters (spaces or tabs) in the GNR list; anything after a whitespace
character is ignored.

This command starts a single server using option group '[mysqld17]':

     shell> mysqld_multi start 17

This command stops several servers, using option groups '[mysqld8]' and
'[mysqld10]' through '[mysqld13]':

     shell> mysqld_multi stop 8,10-13

For an example of how you might set up an option file, use this command:

     shell> mysqld_multi --example

'mysqld_multi' searches for option files as
follows:

   *
     With '--no-defaults', no option files are read.

   *
     With '--defaults-file=FILE_NAME', only the named file is read.

   *
     Otherwise, option files in the standard list of locations are read,
     including any file named by the '--defaults-extra-file=FILE_NAME'
     option, if one is given.  (If the option is given multiple times,
     the last value is used.)

Option files read are searched for '[mysqld_multi]' and '[mysqldN]'
option groups.  The '[mysqld_multi]' group can be used for options to
'mysqld_multi' itself.  '[mysqldN]' groups can be
used for options passed to specific 'mysqld' instances.

The '[mysqld]' or '[mysqld_safe]' groups can be used for common options
read by all instances of 'mysqld' or 'mysqld_safe'.
You can specify a '--defaults-file=FILE_NAME' option to
use a different configuration file for that instance, in which case the
'[mysqld]' or '[mysqld_safe]' groups from that file will be used for
that instance.

'mysqld_multi' supports the following options.

   *
     '--help'

     Display a help message and exit.

   *
     '--example'

     Display a sample option file.

   *
     '--log=FILE_NAME'

     Specify the name of the log file.  If the file exists, log output
     is appended to it.

   *
     '--mysqladmin=PROG_NAME'

     The 'mysqladmin' binary to be used to stop
     servers.

   *
     '--mysqld=PROG_NAME'

     The 'mysqld' binary to be used.  Note that you can
     specify 'mysqld_safe' as the value for this
     option also.  If you use 'mysqld_safe' to start
     the server, you can include the 'mysqld' or 'ledir' options in the
     corresponding '[mysqldN]' option group.  These options indicate the
     name of the server that 'mysqld_safe' should
     start and the path name of the directory where the server is
     located.  (See the descriptions for these options in
     mysqld-safe.)  Example:

          [mysqld38]
          mysqld = mysqld-debug
          ledir  = /opt/local/mysql/libexec

   *
     '--no-log'

     Print log information to 'stdout' rather than to the log file.  By
     default, output goes to the log file.

   *
     '--password=PASSWORD'

     The password of the MySQL account to use when invoking
     'mysqladmin'.  Note that the password value is not
     optional for this option, unlike for other MySQL programs.

   *
     '--silent'

     Silent mode; disable warnings.

   *
     '--tcp-ip'

     Connect to each MySQL server through the TCP/IP port instead of the
     Unix socket file.  (If a socket file is missing, the server might
     still be running, but accessible only through the TCP/IP port.)  By
     default, connections are made using the Unix socket file.  This
     option affects 'stop' and 'report' operations.

   *
     '--user=USER_NAME'

     The user name of the MySQL account to use when invoking
     'mysqladmin'.

   *
     '--verbose'

     Be more verbose.

   *
     '--version'

     Display version information and exit.

Some notes about 'mysqld_multi'.:

   * *Most important*: Before using 'mysqld_multi'.
     be sure that you understand the meanings of the options that are
     passed to the 'mysqld' servers and _why_ you would
     want to have separate 'mysqld' processes.  Beware of
     the dangers of using multiple 'mysqld' servers with
     the same data directory.  Use separate data directories, unless you
     _know_ what you are doing.  Starting multiple servers with the same
     data directory does _not_ give you extra performance in a threaded
     system.  See multiple-servers.

     *Important*:

     Make sure that the data directory for each server is fully
     accessible to the Unix account that the specific 'mysqld'
     process is started as.  _Do not_ use the Unix ROOT account
     for this, unless you _know_ what you are doing.  See
     changing-mysql-user.

   * Make sure that the MySQL account used for stopping the
     'mysqld' servers (with the 'mysqladmin'.
     program) has the same user name and password for each server.
     Also, make sure that the account has the 'SHUTDOWN' privilege.  If
     the servers that you want to manage have different user names or
     passwords for the administrative accounts, you might want to create
     an account on each server that has the same user name and password.
     For example, you might set up a common 'multi_admin' account by
     executing the following commands for each server:

          shell> mysql -u root -S /tmp/mysql.sock -p
          Enter password:
          mysql> CREATE USER 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';
          mysql> GRANT SHUTDOWN ON *.* TO 'multi_admin'@'localhost';

     See privilege-system.  You have to do this for each
     'mysqld' server.  Change the connection parameters
     appropriately when connecting to each one.  Note that the host name
     part of the account name must permit you to connect as
     'multi_admin' from the host where you want to run
     'mysqld_multi'.

   * The Unix socket file and the TCP/IP port number must be different
     for every 'mysqld'.  (Alternatively, if the host has
     multiple network addresses, you can use '--bind-address' to cause
     different servers to listen to different interfaces.)

   * The '--pid-file' option is very important if you are using
     'mysqld_safe' to start 'mysqld'. (for
     example, '--mysqld=mysqld_safe') Every 'mysqld'.
     should have its own process ID file.  The advantage of using
     'mysqld_safe' instead of 'mysqld' is
     that 'mysqld_safe' monitors its 'mysqld'
     process and restarts it if the process terminates due to a
     signal sent using 'kill -9' or for other reasons, such as a
     segmentation fault.

   * You might want to use the '--user' option for 'mysqld',
     but to do this you need to run the 'mysqld_multi'
     script as the Unix superuser ('root').  Having the
     option in the option file doesn't matter; you just get a warning if
     you are not the superuser and the 'mysqld' processes
     are started under your own Unix account.

The following example shows how you might set up an option file for use
with 'mysqld_multi'.  The order in which the
'mysqld' programs are started or stopped depends on the order
in which they appear in the option file.  Group numbers need not form an
unbroken sequence.  The first and fifth '[mysqldN]' groups were
intentionally omitted from the example to illustrate that you can have
'gaps' in the option file.  This gives you more flexibility.

     # This is an example of a my.cnf file for mysqld_multi.
     # Usually this file is located in home dir ~/.my.cnf or /etc/my.cnf

     [mysqld_multi]
     mysqld     = /usr/local/mysql/bin/mysqld_safe
     mysqladmin = /usr/local/mysql/bin/mysqladmin
     user       = multi_admin
     password   = my_password

     [mysqld2]
     socket     = /tmp/mysql.sock2
     port       = 3307
     pid-file   = /usr/local/mysql/data2/hostname.pid2
     datadir    = /usr/local/mysql/data2
     language   = /usr/local/mysql/share/mysql/english
     user       = unix_user1

     [mysqld3]
     mysqld     = /path/to/mysqld_safe
     ledir      = /path/to/mysqld-binary/
     mysqladmin = /path/to/mysqladmin
     socket     = /tmp/mysql.sock3
     port       = 3308
     pid-file   = /usr/local/mysql/data3/hostname.pid3
     datadir    = /usr/local/mysql/data3
     language   = /usr/local/mysql/share/mysql/swedish
     user       = unix_user2

     [mysqld4]
     socket     = /tmp/mysql.sock4
     port       = 3309
     pid-file   = /usr/local/mysql/data4/hostname.pid4
     datadir    = /usr/local/mysql/data4
     language   = /usr/local/mysql/share/mysql/estonia
     user       = unix_user3

     [mysqld6]
     socket     = /tmp/mysql.sock6
     port       = 3311
     pid-file   = /usr/local/mysql/data6/hostname.pid6
     datadir    = /usr/local/mysql/data6
     language   = /usr/local/mysql/share/mysql/japanese
     user       = unix_user4

See option-files.

4.4 MySQL Installation-Related Programs
=======================================

The programs in this section are used when installing or upgrading
MySQL.

4.4.1 'comp_err' -- Compile MySQL Error Message File
----------------------------------------------------

'comp_err' creates the 'errmsg.sys' file that is used
by 'mysqld' to determine the error messages to display
for different error codes.  'comp_err' normally is run
automatically when MySQL is built.  It compiles the 'errmsg.sys' file
from the text file located at 'sql/share/errmsg-utf8.txt' in MySQL
source distributions.

'comp_err' also generates 'mysqld_error.h',
'mysqld_ername.h', and 'sql_state.h' header files.

For more information about how error messages are defined, see the MySQL
Internals Manual (http://dev.mysql.com/doc/internals/en).

Invoke 'comp_err' like this:

     shell> comp_err [OPTIONS]

'comp_err' supports the following options.

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--charset=DIR_NAME', '-C DIR_NAME'

     The character set directory.  The default is
     '../sql/share/charsets'.

   *
     '--debug=DEBUG_OPTIONS', '-# DEBUG_OPTIONS'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:O,FILE_NAME'.  The default is 'd:t:O,/tmp/comp_err.trace'.

   *
     '--debug-info', '-T'

     Print some debugging information when the program exits.

   *
     '--header_file=FILE_NAME', '-H FILE_NAME'

     The name of the error header file.  The default is
     'mysqld_error.h'.

   *
     '--in_file=FILE_NAME', '-F FILE_NAME'

     The name of the input file.  The default is
     '../sql/share/errmsg-utf8.txt'.

   *
     '--name_file=FILE_NAME', '-N FILE_NAME'

     The name of the error name file.  The default is 'mysqld_ername.h'.

   *
     '--out_dir=DIR_NAME', '-D DIR_NAME'

     The name of the output base directory.  The default is
     '../sql/share/'.

   *
     '--out_file=FILE_NAME', '-O FILE_NAME'

     The name of the output file.  The default is 'errmsg.sys'.

   *
     '--statefile=FILE_NAME', '-S FILE_NAME'

     The name for the SQLSTATE header file.  The default is
     'sql_state.h'.

   *
     '--version', '-V'

     Display version information and exit.

4.4.2 'mysql_install_db' -- Initialize MySQL Data Directory
-----------------------------------------------------------

*Note*:

'mysql_install_db' is deprecated as of MySQL
5.7.6 because its functionality has been integrated into 'mysqld',
the MySQL server.  To initialize a MySQL installation, invoke
'mysqld' with the '--initialize' or
'--initialize-insecure' option.  For more information, see
data-directory-initialization-mysqld.  'mysql_install_db'
will be removed in a future MySQL release.

'mysql_install_db' handles initialization tasks
that must be performed before the MySQL server, see 'mysqld',
is ready to use:

   * It initializes the MySQL data directory and creates the system
     tables that it contains.

   * It initializes the system tablespace and related data structures
     needed to manage 'InnoDB' tables.

   * It loads the server-side help tables.

   * It installs the 'sys' schema.

   * It creates an administrative account.  Older versions of
     'mysql_install_db' may create anonymous-user
     accounts.

Before MySQL 5.7.5, see 'mysql_install_db' is a
Perl script and requires that Perl be installed.  As of 5.7.5, see
'mysql_install_db' is written in C++ and supplied in
binary distributions as an executable binary.  In addition, a number of
new options were added and old options removed.  If you find that an
option does not work as you expect, be sure to check which options apply
in your version of 'mysql_install_db'. (invoke
it with the '--help' option).

*Secure-by-Default Deployment*

Current versions of 'mysql_install_db' produce
a MySQL deployment that is secure by default.  It is recommended that
you use 'mysql_install_db' from MySQL 5.7.5 or
up for best security, but version-dependent information about security
characteristics is included here for completeness (secure-by-default
deployment was introduced in stages in MySQL 5.7).

MySQL 5.7.5 and up is secure by default, with these characteristics:

   * A single administrative account named ''root'@'localhost'' is
     created with a randomly generated password, which is marked
     expired.

   * No anonymous-user accounts are created.

   * No 'test' database accessible by all users is created.

   * '--admin-XXX' options are available to control characteristics of
     the administrative account.

   * The '--random-password-file' option is available to control where
     the random password is written.

   * The '--insecure' option is available to suppress random password
     generation.

MySQL 5.7.4 is secure by default, with these characteristics:

   * A single administrative account named ''root'@'localhost'' is
     created with a randomly generated password, which is marked
     expired.

   * No anonymous-user accounts are created.

   * No 'test' database accessible by all users is created.

   * The '--skip-random-passwords' option is available to suppress
     random password generation, and to create a 'test' database.

MySQL 5.7.3 and earlier are not secure by default, with these
characteristics:

   * Multiple administrative 'root' accounts are created with no
     password.

   * Anonymous-user accounts are created.

   * A 'test' database accessible by all users is created.

   * The '--random-passwords' option is available to generate random
     passwords for administrative accounts and mark them expired, and to
     not create anonymous-user accounts.

If 'mysql_install_db' generates a random
administative password, it writes the password to a file and displays
the file name.  The password entry includes a timestamp to indicate when
it was written.  By default, the file is '.mysql_secret' in the home
directory of the effective user running the script.  '.mysql_secret' is
created with mode 600 to be accessible only to the system user for whom
it is created.

*Important*:

When 'mysql_install_db' generates a random
password for the administrative account, it is necessary after
'mysql_install_db' has been run to start the server,
connect using the administrative account with the password written to
the '.mysql_secret' file, and specify a new administrative password.
Until this is done, the administrative account cannot be used for
anything else.  To change the password, you can use the 'SET PASSWORD'
statement (for example, with the 'mysql'
or 'mysqladmin' client).  After resetting the
password, remove the '.mysql_secret' file; otherwise, if you run
'mysql_secure_installation', that command may
see the file and expire the 'root' password again as part of ensuring
secure deployment.

*Invocation Syntax*

Several changes to 'mysql_install_db' were made
in MySQL 5.7.5 that affect the invocation syntax.  Change location to
the MySQL installation directory and use the command appropriate to your
version of MySQL:

   * Invocation syntax for MySQL 5.7.5 and up:

          shell> bin/mysql_install_db --datadir=PATH/TO/DATADIR [OTHER_OPTIONS]

     The '--datadir' option is mandatory.  'mysql_install_db'
     creates the data directory, which must not
     already exist:

        * If the data directory does already exist, you are performing
          an upgrade operation (not an install operation) and should run
          'mysql_upgrade', not
          'mysql_install_db'.  See
          mysql-upgrade.

        * If the data directory does not exist but
          'mysql_install_db' fails, you must remove
          any partially created data directory before running
          'mysql_install_db' again.

   * Invocation syntax before MySQL 5.7.5:

          shell> scripts/mysql_install_db [OPTIONS]

Because the MySQL server, see 'mysqld', must access the data
directory when it runs later, you should either run
'mysql_install_db' from the same system account that
will be used for running 'mysqld', or run it as 'root' and
specify the '--user' option to indicate the user name that
'mysqld' will run as.  It might be necessary to specify other
options such as '--basedir' if 'mysql_install_db'
does not use the correct location for the installation
directory.  For example:

     shell> bin/mysql_install_db --user=mysql \
              --basedir=/opt/mysql/mysql \
              --datadir=/opt/mysql/mysql/data

*Note*:

After 'mysql_install_db' sets up the 'InnoDB'
system tablespace, changes to some tablespace characteristics require
setting up a whole new instance.  This includes the file name of the
first file in the system tablespace and the number of undo logs.  If you
do not want to use the default values, make sure that the settings for
the 'innodb_data_file_path' and 'innodb_log_file_size' configuration
parameters are in place in the MySQL configuration file before running
'mysql_install_db'.  Also make sure to specify
as necessary other parameters that affect the creation and location of
'InnoDB' files, such as 'innodb_data_home_dir' and
'innodb_log_group_home_dir'.

If those options are in your configuration file but that file is not in
a location that MySQL reads by default, specify the file location using
the '--defaults-extra-file' option when you run
'mysql_install_db'.

*Note*:

If you have set a custom 'TMPDIR' environment variable when performing
the installation, and the specified directory is not accessible, see
'mysql_install_db' may fail.  If so, unset 'TMPDIR'
or set 'TMPDIR' to point to the system temporary directory (usually
'/tmp').

*Administrative Account Creation*

'mysql_install_db' creates an administrative
account named ''root'@'localhost'' by default.  (Before MySQL 5.7.4,
see 'mysql_install_db' creates additional 'root'
accounts, such as ''root'@'127.0.0.1''.  This is no longer done.)

As of MySQL 5.7.5, see 'mysql_install_db' provides
options that enable you to control several aspects of the administrative
account:

   * To change the user or host parts of the account name, use
     '--login-path', or '--admin-user' and '--admin-host'.

   * '--insecure' suppresses generation of a random password.

   * '--admin-auth-plugin' specifies the authentication plugin.

   * '--admin-require-ssl' specifies whether the account must use SSL
     connections.

For more information, see the descriptions of those options.

'mysql_install_db' assigns 'user' table rows a
nonempty 'plugin' column value to set the authentication plugin.  The
default value is 'mysql_native_password'.  The value can be changed
using the '--admin-auth-plugin' option in MySQL 5.7.5 and up (as noted
previously), or by setting the 'default_authentication_plugin' system
variable in MySQL 5.7.2 to 5.7.4.

*Default my.cnf File*

As of MySQL 5.7.5, see 'mysql_install_db' creates
no default 'my.cnf' file.

Before MySQL 5.7.5, see 'mysql_install_db' creates
a default option file named 'my.cnf' in the base installation directory.
This file is created from a template included in the distribution
package named 'my-default.cnf'.  You can find the template in or under
the base installation directory.  When started using
'mysqld_safe', the server uses 'my.cnf' file by default.
If 'my.cnf' already exists, see 'mysql_install_db'.
assumes it to be in use and writes a new file named 'my-new.cnf'
instead.

*Note*:

As of MySQL 5.7.18, 'my-default.cnf' is no longer included in or
installed by distribution packages.

With one exception, the settings in the default option file are
commented and have no effect.  The exception is that the file sets the
'sql_mode' system variable to
'NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES'.  This setting produces a
server configuration that results in errors rather than warnings for bad
data in operations that modify transactional tables.  See
sql-mode.

*Command Options*

'mysql_install_db' supports the following
options, which can be specified on the command line or in the
'[mysql_install_db]' group of an option file.  For information about
option files used by MySQL programs, see option-files.

Before MySQL 5.7.5, see 'mysql_install_db' passes
unrecognized options to 'mysqld'.

*mysql_install_db Options*

Format              Description                          IntroducedRemoved

-admin-auth-plugin  Administrative account               5.7.5
                    authentication plugin

-admin-host         Administrative account name host     5.7.5
                    part

-admin-require-ssl  Require SSL for administrative       5.7.5
                    account

-admin-user         Administrative account name user     5.7.5
                    part

-basedir            Path to base directory

-builddir           Path to build directory (for
                    out-of-source builds)

-cross-bootstrap    For internal use                              5.7.5

-datadir            Path to data directory

-defaults           Read default option files            5.7.5

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-extra-sql-file     Optional SQL file to execute         5.7.5
                    during bootstrap

-force              Run even if DNS does not work                 5.7.5

-help               Display help message and exit

-insecure           Do not generate administrative       5.7.5
                    account random password

-keep-my-cnf        Keep existing my.cnf file, do not    5.7.4    5.7.5
                    create new one

-lc-messages        Locale for error messages            5.7.5

-lc-messages-dir    Directory where error messages are   5.7.5
                    installed

-ldata              Synonym for -datadir                          5.7.5

-login-file         File to read for login path          5.7.5
                    information

-login-path         Read login path options from         5.7.5
                    .mylogin.cnf

-mysqld-file        Path to mysqld binary                5.7.5

-no-defaults        Read no option files

-random-password-fileFile in which to write              5.7.5
                    administrative account random
                    password

-random-passwords   Generate administrative account               5.7.4
                    random password

-rpm                For internal use                              5.7.5

-skip-name-resolve  Use IP addresses rather than host             5.7.5
                    names in grant tables

-skip-random-passwordsDo not generate administrative     5.7.4    5.7.5
                    account random password

-skip-sys-schema    Do not install or upgrade the sys    5.7.7
                    schema

-srcdir             For internal use

-user               System login user under which to
                    execute mysqld

-verbose            Verbose mode

-version            Display version information and      5.7.5
                    exit

-windows            For internal use                              5.7.5

   *
     '--help', '-?'

     Display a help message and exit.

     The '-?' form of this option was added in MySQL 5.7.5.

   *
     '--admin-auth-plugin=PLUGIN_NAME'

     The authentication plugin to use for the administrative account.
     The default is 'mysql_native_password'.

     This option was added in MySQL 5.7.5.

   *
     '--admin-host=HOST_NAME'

     The host part to use for the adminstrative account name.  The
     default is 'localhost'.  This option is ignored if '--login-path'
     is also specified.

     This option was added in MySQL 5.7.5.

   *
     '--admin-require-ssl'

     Whether to require SSL for the administrative account.  The default
     is not to require it.  With this option enabled, the statement that
     'mysql_install_db' uses to create the
     account includes a 'REQUIRE SSL' clause.  As a result, the
     administrative account must use secure connections when connecting
     to the server.

     This option was added in MySQL 5.7.5.

   *
     '--admin-user=USER_NAME'

     The user part to use for the adminstrative account name.  The
     default is 'root'.  This option is ignored if '--login-path' is
     also specified.

     This option was added in MySQL 5.7.5.

   *
     '--basedir=DIR_NAME'

     The path to the MySQL installation directory.

   *
     '--builddir=DIR_NAME'

     For use with '--srcdir' and out-of-source builds.  Set this to the
     location of the directory where the built files reside.

   *
     '--cross-bootstrap'

     For internal use.  This option is used for building system tables
     on one host intended for another.

     This option was removed in MySQL 5.7.5.

   *
     '--datadir=DIR_NAME'

     The path to the MySQL data directory.  Only the last component of
     the path name is created if it does not exist; the parent directory
     must already exist or an error occurs.

     *Note*:

     As of MySQL 5.7.5, the '--datadir' option is mandatory and the data
     directory must not already exist.  (It remains true that the parent
     directory must exist.)

   *
     '--defaults'

     This option causes 'mysql_install_db' to
     invoke 'mysqld' in such a way that it reads option
     files from the default locations.  If given as '--no-defaults', and
     '--defaults-file' or '--defaults-extra-file' is not also specified,
     see 'mysql_install_db' passes '--no-defaults'
     to 'mysqld', to prevent option files from being read.
     This may help if program startup fails due to reading unknown
     options from an option file.

     This option was added in MySQL 5.7.5.  (Before 5.7.5, only the
     '--no-defaults' variant was supported.)

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     This option is passed by 'mysql_install_db'
     to 'mysqld'.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     This option is passed by 'mysql_install_db'
     to 'mysqld'.

   *
     '--extra-sql-file=FILE_NAME', '-f FILE_NAME'

     This option names a file containing additional SQL statements to be
     executed after the standard bootstrapping statements.  Accepted
     statement syntax in the file is like that of the 'mysql'
     command-line client, including support for multiple-line
     C-style comments and delimiter handling to enable definition of
     stored programs.

     This option was added in MySQL 5.7.5.

   *
     '--force'

     Cause 'mysql_install_db' to run even if
     DNS does not work.  Grant table entries normally created using host
     names will use IP addresses instead.

     This option was removed in MySQL 5.7.5.

   *
     '--insecure'

     Do not generate a random password for the adminstrative account.

     *Note*:

     The '--insecure' option was added in MySQL 5.7.5, replacing the
     '--skip-random-passwords' option.

     If '--insecure' is _not_ given, it is necessary after
     'mysql_install_db' has been run to start the
     server, connect using the administrative account with the password
     written to the '.mysql_secret' file, and specify a new
     administrative password.  Until this is done, the administrative
     account cannot be used for anything else.  To change the password,
     you can use the 'SET PASSWORD' statement (for
     example, with the 'mysql' or 'mysqladmin'
     client).  After resetting the password, remove the
     '.mysql_secret' file; otherwise, if you run
     'mysql_secure_installation', that
     command may see the file and expire the 'root' password again as
     part of ensuring secure deployment.

   *
     '--keep-my-cnf'

     Tell 'mysql_install_db' to preserve any
     existing 'my.cnf' file and not create a new default 'my.cnf' file.

     This option was added in MySQL 5.7.4 and removed in 5.7.5.  As of
     5.7.5, see 'mysql_install_db' does not create
     a default 'my.cnf' file.

   *
     '--lc-messages=name'

     The locale to use for error messages.  The default is 'en_US'.  The
     argument is converted to a language name and combined with the
     value of '--lc-messages-dir' to produce the location for the error
     message file.  See error-message-language.

     This option was added in MySQL 5.7.5.

   *
     '--lc-messages-dir=DIR_NAME'

     The directory where error messages are located.  The value is used
     together with the value of '--lc-messages' to produce the location
     for the error message file.  See error-message-language.

     This option was added in MySQL 5.7.5.

   *
     '--ldata=DIR_NAME'

     A synonym for '--datadir'.

     This option was removed in MySQL 5.7.5.

   *
     '--login-file=FILE_NAME'

     The file from which to read the login path if the
     '--login-path=FILE_NAME' option is specified.  The default file is
     '.mylogin.cnf'.

     This option was added in MySQL 5.7.5.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  The default login path is 'client'.  (To read a
     different file, use the '--login-file=NAME' option.)  A 'login
     path' is an option group containing options that specify which
     MySQL server to connect to and which account to authenticate as.
     To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

     If the '--login-path' option is specified, the user, host, and
     password values are taken from the login path and used to create
     the administrative account.  The password must be defined in the
     login path or an error occurs, unless the '--insecure' option is
     also specified.  In addition, with '--login-path', any
     '--admin-host' and '--admin-user' options are ignored.

     This option was added in MySQL 5.7.5.

   *
     '--mysqld-file=FILE_NAME'

     The path name of the 'mysqld' binary to execute.
     The option value must be an absolute path name or an error occurs.

     If this option is not given, see 'mysql_install_db'
     searches for 'mysqld' in these
     locations:

        * In the 'bin' directory under the '--basedir' option value, if
          that option was given.

        * In the 'bin' directory under the '--srcdir' option value, if
          that option was given.

        * In the 'bin' directory under the '--builddir' option value, if
          that option was given.

        * In the local directory and in the 'bin' and 'sbin' directories
          under the local directory.

        * In '/usr/bin', '/usr/sbin', '/usr/local/bin',
          '/usr/local/sbin', '/opt/local/bin', '/opt/local/sbin'.

     This option was added in MySQL 5.7.5.

   *
     '--no-defaults'

     Before MySQL 5.7.5, do not read any option files.  If program
     startup fails due to reading unknown options from an option file,
     '--no-defaults' can be used to prevent them from being read.  For
     behavior of this option as of MySQL 5.7.5, see the description of
     '--defaults'.

   *
     '--random-password-file=FILE_NAME'

     The path name of the file in which to write the randomly generated
     password for the administrative account.  The option value must be
     an absolute path name or an error occurs.  The default is
     '$HOME/.mysql_secret'.

     This option was added in MySQL 5.7.5.

   *
     '--random-passwords'

     *Note*:

     This option was removed in MySQL 5.7.4 and replaced with
     '--skip-random-passwords', which was in turn removed in MySQL 5.7.5
     and replaced with '--insecure'.

     On Unix platforms, this option provides for more secure MySQL
     installation.  Invoking 'mysql_install_db'.
     with '--random-passwords' causes it to perform the following
     actions in addition to its normal operation:

        * The installation process creates a random password, assigns it
          to the initial MySQL 'root' accounts, and marks the password
          expired for those accounts.

        *
          The initial random 'root' password is written to the
          '.mysql_secret' file in the directory named by the 'HOME'
          environment variable.  Depending on operating system, using a
          command such as 'sudo' may cause the value of 'HOME' to refer
          to the home directory of the 'root' system user.
          '.mysql_secret' is created with mode 600 to be accessible only
          to the system user for whom it is created.

          If '.mysql_secret' already exists, the new password
          information is appended to it.  Each password entry includes a
          timestamp to indicate when it was written.

        * No anonymous-user MySQL accounts are created.

     As a result of these actions, it is necessary after installation to
     start the server, connect as 'root' using the password written to
     the '.mysql_secret' file, and specify a new 'root' password.  Until
     this is done, 'root' cannot do anything else.  This must be done
     for each 'root' account you intend to use.  To change the password,
     you can use the 'SET PASSWORD' statement (for
     example, with the 'mysql' client).  You can also use
     'mysqladmin' or
     'mysql_secure_installation'.

     New install operations (not upgrades) using RPM packages and
     Solaris PKG packages invoke 'mysql_install_db'
     with the '--random-passwords' option.  (Install
     operations using RPMs for Unbreakable Linux Network are unaffected
     because they do not use 'mysql_install_db')

     For install operations using a binary '.tar.gz' distribution or a
     source distribution, you can invoke 'mysql_install_db'
     with the '--random-passwords' option manually to
     make your MySQL installation more secure.  This is recommended,
     particularly for sites with sensitive data.

   *
     '--rpm'

     For internal use.  This option is used during the MySQL
     installation process for install operations performed using RPM
     packages.

     This option was removed in MySQL 5.7.5.

   *
     '--skip-name-resolve'

     Use IP addresses rather than host names when creating grant table
     entries.  This option can be useful if your DNS does not work.

     This option was removed in MySQL 5.7.5.

   *
     '--skip-random-passwords'

     *Note*:

     The '--skip-random-passwords' option was added in MySQL 5.7.4,
     replacing the '--random-passwords' option.
     '--skip-random-passwords' was in turn removed in MySQL 5.7.5 and
     replaced with '--insecure'.

     As of MySQL 5.7.4, MySQL deployments produced using
     'mysql_install_db' are secure by default.  When
     invoked _without_ the '--skip-random-passwords' option, see
     'mysql_install_db' uses these default deployment
     characteristics:

        * The installation process creates a single 'root' account,
          ''root'@'localhost'', automatically generates a random
          password for this account, and marks the password expired.

        *
          The initial random 'root' password is written to the
          '.mysql_secret' file in the home directory of the effective
          user running the script.  '.mysql_secret' is created with mode
          600 to be accessible only to the system user for whom it is
          created.

          If '.mysql_secret' already exists, the new password
          information is appended to it.  Each password entry includes a
          timestamp to indicate when it was written.

        * No anonymous-user MySQL accounts are created.

        * No 'test' database is created.

     As a result of these actions, it is necessary after installation to
     start the server, connect as 'root' using the password written to
     the '.mysql_secret' file, and specify a new 'root' password.  Until
     this is done, the administrative account cannot be used for
     anything else.  To change the password, you can use the 'SET PASSWORD'
     statement (for example, with the
     'mysql' client).  You can also use 'mysqladmin'
     or 'mysql_secure_installation'.

     To produce a MySQL deployment that is not secure by default, you
     must explicitly specify the '--skip-random-passwords' option when
     you invoke 'mysql_install_db'.  With this
     option, see 'mysql_install_db' performs the
     following actions:

        * No random password is generated for the ''root'@'localhost''
          account.

        * A 'test' database is created that is accessible by any user.

   *
     '--skip-sys-schema'

     As of MySQL 5.7.7, see 'mysql_install_db'.
     installs the 'sys' schema.  The '--skip-sys-schema' option
     suppresses this behavior.  This option was added in MySQL 5.7.7.

   *
     '--srcdir=DIR_NAME'

     For internal use.  This option specifies the directory under which
     'mysql_install_db' looks for support files
     such as the error message file and the file for populating the help
     tables.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The system (login) user name to use for running 'mysqld'.
     Files and directories created by 'mysqld'.
     will be owned by this user.  You must be the system 'root' user to
     use this option.  By default, see 'mysqld' runs using
     your current login name and files and directories that it creates
     will be owned by you.

     The '-u' form of this option was added in MySQL 5.7.5.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.
     You can use this option to see the 'mysqld' command
     that 'mysql_install_db' invokes to start
     the server in bootstrap mode.

     The '-v' form of this option was added in MySQL 5.7.5.

   *
     '--version', '-V'

     Display version information and exit.

     This option was added in MySQL 5.7.5.

   *
     '--windows'

     For internal use.  This option is used for creating Windows
     distributions.  It is a deprecated alias for '--cross-bootstrap'

     This option was removed in MySQL 5.7.5.

4.4.3 'mysql_plugin' -- Configure MySQL Server Plugins
------------------------------------------------------

*Note*:

'mysql_plugin' is deprecated as of MySQL 5.7.11 and
removed in MySQL 8.0.  Alternatives include loading plugins at server
startup using the '--plugin-load' or '--plugin-load-add' option, or at
runtime using the 'INSTALL PLUGIN' statement.

The 'mysql_plugin' utility enables MySQL
administrators to manage which plugins a MySQL server loads.  It
provides an alternative to manually specifying the '--plugin-load'
option at server startup or using the 'INSTALL PLUGIN'
and 'UNINSTALL PLUGIN'.
statements at runtime.

Depending on whether 'mysql_plugin' is invoked to
enable or disable plugins, it inserts or deletes rows in the
'mysql.plugin' table that serves as a plugin registry.  (To perform this
operation, see 'mysql_plugin' invokes the MySQL server
in bootstrap mode.  This means that the server must not already be
running.)  For normal server startups, the server loads and enables
plugins listed in 'mysql.plugin' automatically.  For additional control
over plugin activation, use '--PLUGIN_NAME' options named for specific
plugins, as described in server-plugin-loading.

Each invocation of 'mysql_plugin' reads a
configuration file to determine how to configure the plugins contained
in a single plugin library file.  To invoke 'mysql_plugin',
use this syntax:

     mysql_plugin [OPTIONS] PLUGIN {ENABLE|DISABLE}

PLUGIN is the name of the plugin to configure.  'ENABLE' or 'DISABLE'
(not case-sensitive) specify whether to enable or disable components of
the plugin library named in the configuration file.  The order of the
PLUGIN and 'ENABLE' or 'DISABLE' arguments does not matter.

For example, to configure components of a plugin library file named
'myplugins.so' on Linux or 'myplugins.dll' on Windows, specify a PLUGIN
value of 'myplugins'.  Suppose that this plugin library contains three
plugins, 'plugin1', 'plugin2', and 'plugin3', all of which should be
configured under 'mysql_plugin' control.  By
convention, configuration files have a suffix of '.ini' and the same
base name as the plugin library, so the default configuration file name
for this plugin library is 'myplugins.ini'.  The configuration file
contents look like this:

     myplugins
     plugin1
     plugin2
     plugin3

The first line in the 'myplugins.ini' file is the name of the library
file, without any extension such as '.so' or '.dll'.  The remaining
lines are the names of the components to be enabled or disabled.  Each
value in the file should be on a separate line.  Lines on which the
first character is ''#'' are taken as comments and ignored.

To enable the plugins listed in the configuration file, invoke
'mysql_plugin' this way:

     shell> mysql_plugin myplugins ENABLE

To disable the plugins, use 'DISABLE' rather than 'ENABLE'.

An error occurs if 'mysql_plugin' cannot find the
configuration file or plugin library file, or if 'mysql_plugin'
cannot start the MySQL server.

'mysql_plugin' supports the following options,
which can be specified on the command line or in the '[mysqld]' group of
any option file.  For options specified in a '[mysqld]' group, see
'mysql_plugin' recognizes the '--basedir', '--datadir',
and '--plugin-dir' options and ignores others.  For information about
option files used by MySQL programs, see option-files.

*mysql_plugin Options*

Format                    Description

-basedir                  The server base directory

-datadir                  The server data directory

-help                     Display help message and exit

-my-print-defaults        Path to my_print_defaults

-mysqld                   Path to server

-no-defaults              Do not read configuration file

-plugin-dir               Directory where plugins are installed

-plugin-ini               The plugin configuration file

-print-defaults           Show configuration file defaults

-verbose                  Verbose mode

-version                  Display version information and exit

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--basedir=DIR_NAME', '-b DIR_NAME'

     The server base directory.

   *
     '--datadir=DIR_NAME', '-d DIR_NAME'

     The server data directory.

   *
     '--my-print-defaults=FILE_NAME', '-b FILE_NAME'

     The path to the 'my_print_defaults'.
     program.

   *
     '--mysqld=FILE_NAME', '-b FILE_NAME'

     The path to the 'mysqld' server.

   *
     '--no-defaults', '-p'

     Do not read values from the configuration file.  This option
     enables an administrator to skip reading defaults from the
     configuration file.

     With 'mysql_plugin', this option need not be
     given first on the command line, unlike most other MySQL programs
     that support '--no-defaults'.

   *
     '--plugin-dir=DIR_NAME', '-p DIR_NAME'

     The server plugin directory.

   *
     '--plugin-ini=FILE_NAME', '-i FILE_NAME'

     The 'mysql_plugin' configuration file.
     Relative path names are interpreted relative to the current
     directory.  If this option is not given, the default is
     'PLUGIN.ini' in the plugin directory, where PLUGIN is the PLUGIN
     argument on the command line.

   *
     '--print-defaults', '-P'

     Display the default values from the configuration file.  This
     option causes 'mysql_plugin' to print the
     defaults for '--basedir', '--datadir', and '--plugin-dir' if they
     are found in the configuration file.  If no value for a variable is
     found, nothing is shown.

     With 'mysql_plugin', this option need not be
     given first on the command line, unlike most other MySQL programs
     that support '--print-defaults'.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.
     This option can be used multiple times to increase the amount of
     information.

   *
     '--version', '-V'

     Display version information and exit.

4.4.4 'mysql_secure_installation' -- Improve MySQL Installation Security
------------------------------------------------------------------------

This program enables you to improve the security of your MySQL
installation in the following ways:

   * You can set a password for 'root' accounts.

   * You can remove 'root' accounts that are accessible from outside the
     local host.

   * You can remove anonymous-user accounts.

   * You can remove the 'test' database (which by default can be
     accessed by all users, even anonymous users), and privileges that
     permit anyone to access databases with names that start with
     'test_'.

'mysql_secure_installation' helps you
implement security recommendations similar to those described at
default-privileges.

As of MySQL 5.7.2, see 'mysql_secure_installation'
is an executable binary available on all
platforms.  Before 5.7.2, it was a script available for Unix and
Unix-like systems.

Normal usage is to connect to the local MySQL server; invoke
'mysql_secure_installation' without
arguments:

     shell> mysql_secure_installation

When executed, see 'mysql_secure_installation'
prompts you to determine which actions to
perform.

As of MySQL 5.7.2, see 'mysql_secure_installation'
supports these additional features:

   * The 'validate_password' plugin can be used for password strength
     checking.  If the plugin is not installed, see
     'mysql_secure_installation' prompts the
     user whether to install it.  Any passwords entered later are
     checked using the plugin if it is enabled.

   * Most of the usual MySQL client options such as '--host' and
     '--port' can be used on the command line and in option files.  For
     example, to connect to the local server over IPv6 using port 3307,
     use this command:

          shell> mysql_secure_installation --host=::1 --port=3307

'mysql_secure_installation' supports
the following options, which can be specified on the command line or in
the '[mysql_secure_installation]' and '[client]' groups of an option
file.  For information about option files used by MySQL programs, see
option-files.

*mysql_secure_installation Options*

Format                 Description                              Introduced

-defaults-extra-file   Read named option file in addition to    5.7.2
                       usual option files

-defaults-file         Read only named option file              5.7.2

-defaults-group-suffix Option group suffix value                5.7.2

-help                  Display help message and exit            5.7.2

-host                  Host to connect to (IP address or host   5.7.2
                       name)

-no-defaults           Read no option files                     5.7.2

-password              Accepted but always ignored.  Whenever   5.7.2
                       mysql_secure_installation is invoked,
                       the user is prompted for a password,
                       regardless.

-port                  TCP/IP port number for connection        5.7.2

-print-defaults        Print default options                    5.7.2

-protocol              Connection protocol to use               5.7.2

-socket                For connections to localhost, the Unix   5.7.2
                       socket file to use

-ssl                   Enable encrypted connection              5.7.2

-ssl-ca                File that contains list of trusted SSL   5.7.2
                       Certificate Authorities

-ssl-capath            Directory that contains trusted SSL      5.7.2
                       Certificate Authority certificate
                       files

-ssl-cert              File that contains X509 certificate      5.7.2

-ssl-cipher            List of permitted ciphers for            5.7.2
                       connection encryption

-ssl-crl               File that contains certificate           5.7.2
                       revocation lists

-ssl-crlpath           Directory that contains certificate      5.7.2
                       revocation list files

-ssl-key               File that contains X509 key              5.7.2

-ssl-verify-server-certVerify host name against server          5.7.2
                       certificate Common Name identity

-tls-version           Protocols permitted for encrypted        5.7.10
                       connections

-use-default           Execute with no user interactivity       5.7.4

-user                  MySQL user name to use when connecting   5.7.2
                       to server

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see
     'mysql_secure_installation' normally
     reads the '[client]' and '[mysql_secure_installation]' groups.  If
     the '--defaults-group-suffix=_other' option is given, see
     'mysql_secure_installation' also reads
     the '[client_other]' and '[mysql_secure_installation_other]'
     groups.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--password=PASSWORD', '-p PASSWORD'

     This option is accepted but ignored.  Whether or not this option is
     used, see 'mysql_secure_installation'.
     always prompts the user for a password.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--use-default'

     Execute noninteractively.  This option can be used for unattended
     installation operations.  This option was added in MySQL 5.7.4.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

4.4.5 'mysql_ssl_rsa_setup' -- Create SSL/RSA Files
---------------------------------------------------

This program creates the SSL certificate and key files and RSA key-pair
files required to support secure connections using SSL and secure
password exchange using RSA over unencrypted connections, if those files
are missing.  'mysql_ssl_rsa_setup' can also
be used to create new SSL files if the existing ones have expired.

*Note*:

'mysql_ssl_rsa_setup' uses the 'openssl'
command, so its use is contingent on having OpenSSL installed on your
machine.

Another way to generate SSL and RSA files, for MySQL distributions
compiled using OpenSSL, is to have the server generate them
automatically.  See creating-ssl-rsa-files-using-mysql.

*Important*:

'mysql_ssl_rsa_setup' helps lower the
barrier to using SSL by making it easier to generate the required files.
However, certificates generated by 'mysql_ssl_rsa_setup'
are self-signed, which is not very secure.  After
you gain experience using the files created by
'mysql_ssl_rsa_setup', consider obtaining a CA
certificate from a registered certificate authority.

Invoke 'mysql_ssl_rsa_setup' like this:

     shell> mysql_ssl_rsa_setup [OPTIONS]

Typical options are '--datadir' to specify where to create the files,
and '--verbose' to see the 'openssl' commands that
'mysql_ssl_rsa_setup' executes.

'mysql_ssl_rsa_setup' attempts to create SSL
and RSA files using a default set of file names.  It works as follows:

  1. 'mysql_ssl_rsa_setup' checks for the
     'openssl' binary at the locations specified by the 'PATH'
     environment variable.  If 'openssl' is not found, see
     'mysql_ssl_rsa_setup' does nothing.  If
     'openssl' is present, see 'mysql_ssl_rsa_setup'
     looks for default SSL and RSA files in the
     MySQL data directory specified by the '--datadir' option, or the
     compiled-in data directory if the '--datadir' option is not given.

  2. 'mysql_ssl_rsa_setup' checks the data
     directory for SSL files with the following names:

          ca.pem
          server-cert.pem
          server-key.pem

  3. If any of those files are present, see 'mysql_ssl_rsa_setup'
     creates no SSL files.  Otherwise, it invokes
     'openssl' to create them, plus some additional files:

          ca.pem               Self-signed CA certificate
          ca-key.pem           CA private key
          server-cert.pem      Server certificate
          server-key.pem       Server private key
          client-cert.pem      Client certificate
          client-key.pem       Client private key

     These files enable secure client connections using SSL; see
     using-encrypted-connections.

  4. 'mysql_ssl_rsa_setup' checks the data
     directory for RSA files with the following names:

          private_key.pem      Private member of private/public key pair
          public_key.pem       Public member of private/public key pair

  5. If any of these files are present, see 'mysql_ssl_rsa_setup'
     creates no RSA files.  Otherwise, it invokes
     'openssl' to create them.  These files enable secure password
     exchange using RSA over unencrypted connections for accounts
     authenticated by the 'sha256_password' plugin; see
     sha256-pluggable-authentication.

For information about the characteristics of files created by
'mysql_ssl_rsa_setup', see
creating-ssl-rsa-files-using-mysql.

At startup, the MySQL server automatically uses the SSL files created by
'mysql_ssl_rsa_setup' to enable SSL if no
explicit SSL options are given other than '--ssl' (possibly along with
'--ssl-cipher').  If you prefer to designate the files explicitly,
invoke clients with the '--ssl-ca', '--ssl-cert', and '--ssl-key'
options at startup to name the 'ca.pem', 'server-cert.pem', and
'server-key.pem' files, respectively.

The server also automatically uses the RSA files created by
'mysql_ssl_rsa_setup' to enable RSA if no explicit
RSA options are given.

If the server is SSL-enabled, clients use SSL by default for the
connection.  To specify certificate and key files explicitly, use the
'--ssl-ca', '--ssl-cert', and '--ssl-key' options to name the 'ca.pem',
'client-cert.pem', and 'client-key.pem' files, respectively.  However,
some additional client setup may be required first because
'mysql_ssl_rsa_setup' by default creates those
files in the data directory.  The permissions for the data directory
normally enable access only to the system account that runs the MySQL
server, so client programs cannot use files located there.  To make the
files available, copy them to a directory that is readable (but _not_
writable) by clients:

   * For local clients, the MySQL installation directory can be used.
     For example, if the data directory is a subdirectory of the
     installation directory and your current location is the data
     directory, you can copy the files like this:

          cp ca.pem client-cert.pem client-key.pem ..

   * For remote clients, distribute the files using a secure channel to
     ensure they are not tampered with during transit.

If the SSL files used for a MySQL installation have expired, you can use
'mysql_ssl_rsa_setup' to create new ones:

  1. Stop the server.

  2. Rename or remove the existing SSL files.  You may wish to make a
     backup of them first.  (The RSA files do not expire, so you need
     not remove them.  See 'mysql_ssl_rsa_setup'.
     will see that they exist and not overwrite them.)

  3. Run 'mysql_ssl_rsa_setup' with the
     '--datadir' option to specify where to create the new files.

  4. Restart the server.

'mysql_ssl_rsa_setup' supports the following
command-line options, which can be specified on the command line or in
the '[mysql_ssl_rsa_setup]', '[mysql_install_db]', and '[mysqld]' groups
of an option file.  For information about option files used by MySQL
programs, see option-files.

*mysql_ssl_rsa_setup Options*

Format                 Description                              Introduced

-datadir               Path to data directory

-help                  Display help message and exit

-suffix                Suffix for X509 certificate Common
                       Name attribute

-uid                   Name of effective user to use for file   5.7.8
                       permissions

-verbose               Verbose mode

-version               Display version information and exit

   *
     '--help', '?'

     Display a help message and exit.

   *
     '--datadir=DIR_NAME'

     The path to the directory that 'mysql_ssl_rsa_setup'
     should check for default SSL and RSA files and
     in which it should create files if they are missing.  The default
     is the compiled-in data directory.

   *
     '--suffix=STR'

     The suffix for the Common Name attribute in X509 certificates.  The
     suffix value is limited to 17 characters.  The default is based on
     the MySQL version number.

   *
     '--uid=name', '-v'

     The name of the user who should be the owner of any created files.
     The value is a user name, not a numeric user ID. In the absence of
     this option, files created by 'mysql_ssl_rsa_setup'
     are owned by the user who executes it.  This
     option is valid only if you execute the program as 'root' on a
     system that supports the 'chown()' system call.

   *
     '--verbose', '-v'

     Verbose mode.  Produce more output about what the program does.
     For example, the program shows the 'openssl' commands it runs, and
     produces output to indicate whether it skips SSL or RSA file
     creation because some default file already exists.

   *
     '--version', '-V'

     Display version information and exit.

4.4.6 'mysql_tzinfo_to_sql' -- Load the Time Zone Tables
--------------------------------------------------------

The 'mysql_tzinfo_to_sql' program loads the
time zone tables in the 'mysql' database.  It is used on systems that
have a _zoneinfo_ database (the set of files describing time zones).
Examples of such systems are Linux, FreeBSD, Solaris, and OS X. One
likely location for these files is the '/usr/share/zoneinfo' directory
('/usr/share/lib/zoneinfo' on Solaris).  If your system does not have a
zoneinfo database, you can use the downloadable package described in
time-zone-support.

'mysql_tzinfo_to_sql' can be invoked several
ways:

     shell> mysql_tzinfo_to_sql TZ_DIR
     shell> mysql_tzinfo_to_sql TZ_FILE TZ_NAME
     shell> mysql_tzinfo_to_sql --leap TZ_FILE

For the first invocation syntax, pass the zoneinfo directory path name
to 'mysql_tzinfo_to_sql' and send the output
into the 'mysql' program.  For example:

     shell> mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

'mysql_tzinfo_to_sql' reads your system's
time zone files and generates SQL statements from them.  'mysql'
processes those statements to load the time zone tables.

The second syntax causes 'mysql_tzinfo_to_sql'
to load a single time zone file TZ_FILE that
corresponds to a time zone name TZ_NAME:

     shell> mysql_tzinfo_to_sql TZ_FILE TZ_NAME | mysql -u root mysql

If your time zone needs to account for leap seconds, invoke
'mysql_tzinfo_to_sql' using the third syntax,
which initializes the leap second information.  TZ_FILE is the name of
your time zone file:

     shell> mysql_tzinfo_to_sql --leap TZ_FILE | mysql -u root mysql

After running 'mysql_tzinfo_to_sql', it is
best to restart the server so that it does not continue to use any
previously cached time zone data.

4.4.7 'mysql_upgrade' -- Check and Upgrade MySQL Tables
-------------------------------------------------------

'mysql_upgrade' examines all tables in all
databases for incompatibilities with the current version of MySQL
Server.  'mysql_upgrade' also upgrades the system
tables so that you can take advantage of new privileges or capabilities
that might have been added.

If 'mysql_upgrade' finds that a table has a
possible incompatibility, it performs a table check and, if problems are
found, attempts a table repair.  If the table cannot be repaired, see
rebuilding-tables for manual table repair strategies.

You should execute 'mysql_upgrade' each time you
upgrade MySQL.

As of MySQL 5.7.5, see 'mysql_upgrade' communicates
directly with the MySQL server, sending it the SQL statements required
to perform an upgrade.  Before 5.7.5, see 'mysql_upgrade'
invokes the 'mysql' and 'mysqlcheck'
client programs to perform the required operations.  For the
older implementation, if you install MySQL from RPM packages on Linux,
you must install the server and client RPMs.  'mysql_upgrade'
is included in the server RPM but requires the client RPM
because the latter includes 'mysqlcheck'.  (See
linux-installation-rpm.)

*Important*:

As of MySQL 5.7.12, the default '--early-plugin-load' value is empty.
To load the 'keyring_file' plugin, you must use an explicit
'--early-plugin-load' option with a nonempty value.

In MySQL 5.7.11, the default '--early-plugin-load' value was the name of
the 'keyring_file' plugin library file, so that plugin was loaded by
default.  'InnoDB' tablespace encryption requires the 'keyring_file'
plugin to be loaded prior to 'InnoDB' initialization, so this change of
default value introduces an incompatibility for upgrades from 5.7.11 to
5.7.12 or higher.  Administrators who have encrypted 'InnoDB'
tablespaces must take explicit action to ensure continued loading of the
'keyring_file' plugin: Start the server with an '--early-plugin-load'
option that names the plugin library file.  For additional information,
see keyring.

*Important*:

If you upgrade to MySQL 5.7.2 or later from a version older than 5.7.2,
a change to the 'mysql.user' table requires a special sequence of steps
to perform an upgrade using 'mysql_upgrade'.  For
details, see upgrading-from-previous-series.

*Note*:

On Windows Server 2008, Vista, and newer, you must run
'mysql_upgrade' with administrator privileges.  You can
do this by running a Command Prompt as Administrator and running the
command.  Failure to do so may result in the upgrade failing to execute
correctly.

*Caution*:

You should always back up your current MySQL installation _before_
performing an upgrade.  See backup-methods.

Some upgrade incompatibilities may require special handling before you
upgrade your MySQL installation and run 'mysql_upgrade'.
See upgrading, for instructions on determining
whether any such incompatibilities apply to your installation and how to
handle them.

To use 'mysql_upgrade', make sure that the server
is running.  Then invoke it like this to check and repair tables and to
upgrade the system tables:

     shell> mysql_upgrade [OPTIONS]

After running 'mysql_upgrade', stop the server and
restart it so that any changes made to the system tables take effect.

If you have multiple MySQL server instances running, invoke
'mysql_upgrade' with connection parameters appropriate
for connecting to the desired server.  For example, with servers running
on the local host on parts 3306 through 3308, upgrade each of them by
connecting to the appropriate port:

     shell> mysql_upgrade --protocol=tcp -P 3306 [OTHER_OPTIONS]
     shell> mysql_upgrade --protocol=tcp -P 3307 [OTHER_OPTIONS]
     shell> mysql_upgrade --protocol=tcp -P 3308 [OTHER_OPTIONS]

For local host connections on Unix, the '--protocol=tcp' option forces a
connection using TCP/IP rather than the Unix socket file.

'mysql_upgrade' processes all tables in all
databases, which might take a long time to complete.  Each table is
locked and therefore unavailable to other sessions while it is being
processed.  Check and repair operations can be time-consuming,
particularly for large tables.

For details about what table-checking operations entail, see the
description of the 'FOR UPGRADE' option of the 'CHECK TABLE'
statement (see check-table).

All checked and repaired tables are marked with the current MySQL
version number.  This ensures that next time you run
'mysql_upgrade' with the same version of the server, it
can tell whether there is any need to check or repair the table again.

'mysql_upgrade' also saves the MySQL version
number in a file named 'mysql_upgrade_info' in the data directory.  This
is used to quickly check whether all tables have been checked for this
release so that table-checking can be skipped.  To ignore this file and
perform the check regardless, use the '--force' option.

As of MySQL 5.7.2, see 'mysql_upgrade' checks 'user'
table rows and, for any row with an empty 'plugin' column, sets that
column to ''mysql_native_password'' or ''mysql_old_password'' depending
on the hash format of the 'Password' column value.  As of MySQL 5.7.5,
support for pre-4.1 password hashing and 'mysql_old_password' was
removed, so 'mysql_upgrade' sets empty 'plugin'
values to ''mysql_native_password'' if the credentials use a hash format
compatible with that plugin.  Rows with a pre-4.1 password hash must be
upgraded manually.  For account upgrade instructions, see
account-upgrades.

'mysql_upgrade' does not upgrade the contents of
the help tables.  For upgrade instructions, see
server-side-help-support.

As of MySQL 5.7.7, unless invoked with the '--skip-sys-schema' option,
see 'mysql_upgrade' installs the 'sys' schema if it is
not installed, and upgrades it to the current version otherwise.
'mysql_upgrade' returns an error if a 'sys' schema
exists but has no 'version' view, on the assumption that its absence
indicates a user-created schema:

     Error occurred: A sys schema exists with no sys.version view. If
     you have a user created sys schema, this must be renamed for the
     upgrade to succeed.

To upgrade in this case, remove or rename the existing 'sys' schema
first.

In MySQL 5.7.9 and later, see 'mysql_upgrade' checks
for partitioned 'InnoDB' tables that were created using the generic
partitioning handler and attempts to upgrade them to 'InnoDB' native
partitioning (used in MySQL 5.7.6 and later).  (Bug #76734, Bug
#20727344) Also beginning with MySQL 5.7.9, you can upgrade such tables
individually in the 'mysql' client using the 'ALTER TABLE ... UPGRADE PARTITIONING'.
SQL statement.

By default, see 'mysql_upgrade' runs as the MySQL
'root' user.  If the 'root' password is expired when you run
'mysql_upgrade', you will see a message that your
password is expired and that 'mysql_upgrade'.
failed as a result.  To correct this, reset the 'root' password to
unexpire it and run 'mysql_upgrade' again.  First,
connect to the server as 'root':

     shell> mysql -u root -p
     Enter password: ****  <- enter root password here

Reset the password using the appropriate SQL statement.  As of MySQL
5.7.6, use 'ALTER USER'.:

     mysql> ALTER USER USER() IDENTIFIED BY 'ROOT-PASSWORD';

Before 5.7.6, use 'SET PASSWORD'.:

     mysql> SET PASSWORD = PASSWORD('root-password');

Then exit 'mysql' and run 'mysql_upgrade'
again:

     shell> mysql_upgrade [OPTIONS]

'mysql_upgrade' supports the following options,
which can be specified on the command line or in the '[mysql_upgrade]'
and '[client]' groups of an option file.  For information about option
files used by MySQL programs, see option-files.

*mysql_upgrade Options*

Format              Description                          IntroducedRemoved

-basedir            Not used                                      5.7.2

-bind-address       Use specified network interface to   5.7.5
                    connect to MySQL Server

-character-sets-dir Directory where character sets are
                    installed

-compress           Compress all information sent
                    between client and server

-datadir            Not used                                      5.7.2

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-default-character-setSpecify default character set

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-force              Force execution even if
                    mysql_upgrade has already been
                    executed for current version of
                    MySQL

-help               Display help message and exit

-host               Connect to MySQL server on given
                    host

-login-path         Read login path options from
                    .mylogin.cnf

-max-allowed-packet Maximum packet length to send to     5.7.5
                    or receive from server

-net-buffer-length  Buffer size for TCP/IP and socket    5.7.5
                    communication

-no-defaults        Read no option files

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-protocol           Connection protocol to use

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-skip-sys-schema    Do not install or upgrade the sys    5.7.7
                    schema

-socket             For connections to localhost, the
                    Unix socket file to use

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-tmpdir             Directory for temporary files                 5.7.5

-upgrade-system-tablesUpdate only system tables, not
                    data

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version-check      Check for proper server version      5.7.2

-write-binlog       Write all statements to binary log

   *
     '--help'

     Display a short help message and exit.

   *
     '--basedir=DIR_NAME'

     The path to the MySQL installation directory.  This option was
     removed in MySQL 5.7.2.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.  This option was added in MySQL 5.7.5.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.  The '-C' form of this option was added
     in MySQL 5.7.5.

   *
     '--datadir=DIR_NAME'

     The path to the data directory.  This option was removed in MySQL
     5.7.2.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is
     'd:t:O,/tmp/mysql_upgrade.trace'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info', '-T'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set.  See
     charset-configuration.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see
     'mysql_upgrade' normally reads the '[client]' and
     '[mysql_upgrade]' groups.  If the '--defaults-group-suffix=_other'
     option is given, see 'mysql_upgrade' also reads
     the '[client_other]' and '[mysql_upgrade_other]' groups.

   *
     '--force'

     Ignore the 'mysql_upgrade_info' file and force execution even if
     'mysql_upgrade' has already been executed for
     the current version of MySQL.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--max-allowed-packet=VALUE'

     The maximum size of the buffer for client/server communication.
     The default value is 24MB. The minimum and maximum values are 4KB
     and 2GB. This option was added in MySQL 5.7.5.

   *
     '--net-buffer-length=VALUE'

     The initial size of the buffer for client/server communication.
     The default value is 1MB − 1KB. The minimum and maximum values
     are 4KB and 16MB. This option was added in MySQL 5.7.5.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysql_upgrade' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysql_upgrade' does not find it.
     See pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--skip-sys-schema'

     As of MySQL 5.7.7, see 'mysql_upgrade' installs
     the 'sys' schema if it is not installed, and upgrades it to the
     current version otherwise.  The '--skip-sys-schema' option
     suppresses this behavior.  This option was added in MySQL 5.7.7.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--tmpdir=DIR_NAME', '-t DIR_NAME'

     The path name of the directory to use for creating temporary files.
     This option was removed in MySQL 5.7.5 due to a reimplementation
     that no longer uses temporary files.

   *
     '--upgrade-system-tables', '-s'

     Upgrade only the system tables, do not upgrade data.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.  The
     default user name is 'root'.

   *
     '--verbose'

     Verbose mode.  Print more information about what the program does.

   *
     '--version-check', '-k'

     Check the version of the server to which 'mysql_upgrade'
     is connecting to verify that it is the same as the
     version for which 'mysql_upgrade' was built.
     If not, see 'mysql_upgrade' exits.  This option
     is enabled by default; to disable the check, use
     '--skip-version-check'.  This option was added in MySQL 5.7.2.

   *
     '--write-binlog'

     By default, binary logging by 'mysql_upgrade'.
     is disabled.  Invoke the program with '--write-binlog' if you want
     its actions to be written to the binary log.

     When the server is running with global transaction identifiers
     (GTIDs) enabled ('gtid_mode=ON'), do not enable binary logging by
     'mysql_upgrade'.

4.5 MySQL Client Programs
=========================

This section describes client programs that connect to the MySQL server.

4.5.1 'mysql' -- The MySQL Command-Line Tool
--------------------------------------------

'mysql' is a simple SQL shell with input line editing
capabilities.  It supports interactive and noninteractive use.  When
used interactively, query results are presented in an ASCII-table
format.  When used noninteractively (for example, as a filter), the
result is presented in tab-separated format.  The output format can be
changed using command options.

If you have problems due to insufficient memory for large result sets,
use the '--quick' option.  This forces 'mysql' to retrieve
results from the server a row at a time rather than retrieving the
entire result set and buffering it in memory before displaying it.  This
is done by returning the result set using the
'mysql_use_result()'. C API function in the
client/server library rather than 'mysql_store_result()'.

*Note*:

Alternatively, MySQL Shell offers access to the X DevAPI. For details,
see mysql-shell.

Using 'mysql' is very easy.  Invoke it from the prompt of
your command interpreter as follows:

     shell> mysql DB_NAME

Or:

     shell> mysql --user=USER_NAME --password DB_NAME
     Enter password: YOUR_PASSWORD

Then type an SQL statement, end it with ';', '\g', or '\G' and press
Enter.

Typing 'Control+C' interrupts the current statement if there is one, or
cancels any partial input line otherwise.

You can execute SQL statements in a script file (batch file) like this:

     shell> mysql DB_NAME < SCRIPT.SQL > OUTPUT.TAB

On Unix, the 'mysql' client logs statements executed
interactively to a history file.  See mysql-logging.

4.5.1.1 mysql Options
.....................

'mysql' supports the following options, which can be
specified on the command line or in the '[mysql]' and '[client]' groups
of an option file.  For information about option files used by MySQL
programs, see option-files.

*mysql Options*

Format              Description                          IntroducedDeprecated

-auto-rehash        Enable automatic rehashing

-auto-vertical-outputEnable automatic vertical result
                    set display

-batch              Do not use history file

-binary-as-hex      Display binary values in             5.7.19
                    hexadecimal notation

-binary-mode        Disable \r\n - to - \n translation
                    and treatment of \0 as
                    end-of-query

-bind-address       Use specified network interface to
                    connect to MySQL Server

-character-sets-dir Directory where character sets are
                    installed

-column-names       Write column names in results

-column-type-info   Display result set metadata

-comments           Whether to retain or strip
                    comments in statements sent to the
                    server

-compress           Compress all information sent
                    between client and server

-connect-expired-passwordIndicate to server that client can5.7.2
                    handle expired-password sandbox
                    mode.

-connect_timeout    Number of seconds before
                    connection timeout

-database           The database to use

-debug              Write debugging log; supported
                    only if MySQL was built with
                    debugging support

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-default-character-setSpecify default character set

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-delimiter          Set the statement delimiter

-enable-cleartext-pluginEnable cleartext authentication
                    plugin

-execute            Execute the statement and quit

-force              Continue even if an SQL error
                    occurs

-help               Display help message and exit

-histignore         Patterns specifying which
                    statements to ignore for logging

-host               Connect to MySQL server on given
                    host

-html               Produce HTML output

-ignore-spaces      Ignore spaces after function names

-init-command       SQL statement to execute after
                    connecting

-line-numbers       Write line numbers for errors

-local-infile       Enable or disable for LOCAL
                    capability for LOAD DATA INFILE

-login-path         Read login path options from
                    .mylogin.cnf

-max_allowed_packet Maximum packet length to send to
                    or receive from server

-max_join_size      The automatic limit for rows in a
                    join when using -safe-updates

-named-commands     Enable named mysql commands

-net_buffer_length  Buffer size for TCP/IP and socket
                    communication

-no-auto-rehash     Disable automatic rehashing

-no-beep            Do not beep when errors occur

-no-defaults        Read no option files

-one-database       Ignore statements except those for
                    the default database named on the
                    command line

-pager              Use the given command for paging
                    query output

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-prompt             Set the prompt to the specified
                    format

-protocol           Connection protocol to use

-quick              Do not cache each query result

-raw                Write column values without escape
                    conversion

-reconnect          If the connection to the server is
                    lost, automatically try to
                    reconnect

-i-am-a-dummy,      Allow only UPDATE and DELETE
-safe-updates       statements that specify key values

-secure-auth        Do not send passwords to server in            5.7.5
                    old (pre-4.1) format

-select_limit       The automatic limit for SELECT
                    statements when using
                    -safe-updates

-server-public-key-pathPath name to file containing RSA
                    public key

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-show-warnings      Show warnings after each statement
                    if there are any

-sigint-ignore      Ignore SIGINT signals (typically
                    the result of typing Control+C)

-silent             Silent mode

-skip-auto-rehash   Disable automatic rehashing

-skip-column-names  Do not write column names in
                    results

-skip-line-numbers  Skip line numbers for errors

-skip-named-commandsDisable named mysql commands

-skip-pager         Disable paging

-skip-reconnect     Disable reconnecting

-socket             For connections to localhost, the
                    Unix socket file or Windows named
                    pipe to use

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-syslog             Log interactive statements to        5.7.1
                    syslog

-table              Display output in tabular format

-tee                Append a copy of output to named
                    file

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-unbuffered         Flush the buffer after each query

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version            Display version information and
                    exit

-vertical           Print query output rows vertically
                    (one line per column value)

-wait               If the connection cannot be
                    established, wait and retry
                    instead of aborting

-xml                Produce XML output

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--auto-rehash'

     Enable automatic rehashing.  This option is on by default, which
     enables database, table, and column name completion.  Use
     '--disable-auto-rehash' to disable rehashing.  That causes
     'mysql' to start faster, but you must issue the 'rehash'
     command or its '\#' shortcut if you want to use name completion.

     To complete a name, enter the first part and press Tab.  If the
     name is unambiguous, see 'mysql' completes it.
     Otherwise, you can press Tab again to see the possible names that
     begin with what you have typed so far.  Completion does not occur
     if there is no default database.

     *Note*:

     This feature requires a MySQL client that is compiled with the
     *readline* library.  Typically, the *readline* library is not
     available on Windows.

   *
     '--auto-vertical-output'

     Cause result sets to be displayed vertically if they are too wide
     for the current window, and using normal tabular format otherwise.
     (This applies to statements terminated by ';' or '\G'.)

   *
     '--batch', '-B'

     Print results using tab as the column separator, with each row on a
     new line.  With this option, see 'mysql' does not use the
     history file.

     Batch mode results in nontabular output format and escaping of
     special characters.  Escaping may be disabled by using raw mode;
     see the description for the '--raw' option.

   *
     '--binary-as-hex', '-b'

     When this option is given, see 'mysql' displays binary
     data using hexadecimal notation ('0xVALUE').  This occurs whether
     the overall output dislay format is tabular, vertical, HTML, or
     XML.

     This option was added in MySQL 5.7.19.

   *
     '--binary-mode'

     This option helps when processing 'mysqlbinlog'.
     output that may contain 'BLOB' values.  By default,
     see 'mysql' translates '\r\n' in statement strings to
     '\n' and interprets '\0' as the statement terminator.
     '--binary-mode' disables both features.  It also disables all
     'mysql' commands except 'charset' and 'delimiter' in
     non-interactive mode (for input piped to 'mysql' or
     loaded using the 'source' command).

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--column-names'

     Write column names in results.

   *
     '--column-type-info'

     Display result set metadata.

   *
     '--comments', '-c'

     Whether to strip or preserve comments in statements sent to the
     server.  The default is '--skip-comments' (strip comments), enable
     with '--comments' (preserve comments).

     *Note*:

     As of MySQL 5.7.7, the 'mysql' client always passes
     optimizer hints to the server, regardless of whether this option is
     given.  To ensure that optimizer hints are not stripped if you are
     using an older version of the 'mysql' client with a
     version of the server that understands optimizer hints, invoke
     'mysql' with the '--comments' option.

     Comment stripping is deprecated as of MySQL 5.7.20.  This feature
     and the options to control it will be removed in a future MySQL
     release.

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--connect-expired-password'

     Indicate to the server that the client can handle sandbox mode if
     the account used to connect has an expired password.  This can be
     useful for noninteractive invocations of 'mysql'.
     because normally the server disconnects noninteractive clients that
     attempt to connect using an account with an expired password.  (See
     expired-password-handling.)  This option was added in MySQL
     5.7.2.

   *
     '--database=DB_NAME', '-D DB_NAME'

     The database to use.  This is useful primarily in an option file.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o,/tmp/mysql.trace'.

     This option is available only if MySQL was built using
     'WITH_DEBUG'.  MySQL release binaries provided by Oracle are _not_
     built using this option.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info', '-T'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set for the client and
     connection.

     This option can be useful if the operating system uses one
     character set and the 'mysql' client by default uses
     another.  In this case, output may be formatted incorrectly.  You
     can usually fix such issues by using this option to force the
     client to use the system character set instead.

     For more information, see charset-connection, and
     charset-configuration.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysql'
     normally reads the '[client]' and '[mysql]' groups.  If the
     '--defaults-group-suffix=_other' option is given, see 'mysql'
     also reads the '[client_other]' and '[mysql_other]' groups.

   *
     '--delimiter=STR'

     Set the statement delimiter.  The default is the semicolon
     character (';').

   *
     '--disable-named-commands'

     Disable named commands.  Use the '\*' form only, or use named
     commands only at the beginning of a line ending with a semicolon
     (';').  'mysql' starts with this option _enabled_ by
     default.  However, even with this option, long-format commands
     still work from the first line.  See mysql-commands.

   *
     '--enable-cleartext-plugin'

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     (See cleartext-pluggable-authentication.)

   *
     '--execute=STATEMENT', '-e STATEMENT'

     Execute the statement and quit.  The default output format is like
     that produced with '--batch'.  See command-line-options,
     for some examples.  With this option, see 'mysql' does
     not use the history file.

   *
     '--force', '-f'

     Continue even if an SQL error occurs.

   *
     '--histignore'

     A colon-separated list of one or more patterns specifying
     statements to ignore for logging purposes.  These patterns are
     added to the default pattern list ('"*IDENTIFIED*:*PASSWORD*"').
     The value specified for this option affects logging of statements
     written to the history file, and to 'syslog' if the '--syslog'
     option is given.  For more information, see mysql-logging.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--html', '-H'

     Produce HTML output.

   *
     '--ignore-spaces', '-i'

     Ignore spaces after function names.  The effect of this is
     described in the discussion for the 'IGNORE_SPACE' SQL mode (see
     sql-mode).

   *
     '--init-command=str'

     SQL statement to execute after connecting to the server.  If
     auto-reconnect is enabled, the statement is executed again after
     reconnection occurs.

   *
     '--line-numbers'

     Write line numbers for errors.  Disable this with
     '--skip-line-numbers'.

   *
     '--local-infile[={0|1}]'

     Enable or disable 'LOCAL' capability for 'LOAD DATA INFILE'.
     For 'mysql', this capability is disabled
     by default.  With no value, the option enables 'LOCAL'.  The option
     may be given as '--local-infile=0' or '--local-infile=1' to
     explicitly disable or enable 'LOCAL'.  Enabling local data loading
     also requires that the server permits it; see
     load-data-local

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--named-commands', '-G'

     Enable named 'mysql' commands.  Long-format commands
     are permitted, not just short-format commands.  For example, 'quit'
     and '\q' both are recognized.  Use '--skip-named-commands' to
     disable named commands.  See mysql-commands.

   *
     '--no-auto-rehash', '-A'

     This has the same effect as '--skip-auto-rehash'.  See the
     description for '--auto-rehash'.

   *
     '--no-beep', '-b'

     Do not beep when errors occur.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--one-database', '-o'

     Ignore statements except those that occur while the default
     database is the one named on the command line.  This option is
     rudimentary and should be used with care.  Statement filtering is
     based only on 'USE' statements.

     Initially, see 'mysql' executes statements in the input
     because specifying a database DB_NAME on the command line is
     equivalent to inserting 'USE DB_NAME' at the beginning
     of the input.  Then, for each 'USE' statement
     encountered, see 'mysql' accepts or rejects following
     statements depending on whether the database named is the one on
     the command line.  The content of the statements is immaterial.

     Suppose that 'mysql' is invoked to process this set
     of statements:

          DELETE FROM db2.t2;
          USE db2;
          DROP TABLE db1.t1;
          CREATE TABLE db1.t1 (i INT);
          USE db1;
          INSERT INTO t1 (i) VALUES(1);
          CREATE TABLE db2.t1 (j INT);

     If the command line is 'mysql --force --one-database db1',
     see 'mysql' handles the input as follows:

        * The 'DELETE' statement is executed because the
          default database is 'db1', even though the statement names a
          table in a different database.

        * The 'DROP TABLE' and 'CREATE TABLE'
          statements are not executed because the default
          database is not 'db1', even though the statements name a table
          in 'db1'.

        * The 'INSERT' and 'CREATE TABLE'
          statements are executed because the default
          database is 'db1', even though the 'CREATE TABLE'
          statement names a table in a different database.

   *
     '--pager[=COMMAND]'

     Use the given command for paging query output.  If the command is
     omitted, the default pager is the value of your 'PAGER' environment
     variable.  Valid pagers are 'less', 'more', 'cat [> filename]', and
     so forth.  This option works only on Unix and only in interactive
     mode.  To disable paging, use '--skip-pager'.  See
     mysql-commands, discusses output paging further.

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see 'mysql'
     prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysql' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--prompt=FORMAT_STR'

     Set the prompt to the specified format.  The default is 'mysql>'.
     The special sequences that the prompt can contain are described in
     mysql-commands.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--quick', '-q'

     Do not cache each query result, print each row as it is received.
     This may slow down the server if the output is suspended.  With
     this option, see 'mysql' does not use the history file.

   *
     '--raw', '-r'

     For tabular output, the 'boxing' around columns enables one column
     value to be distinguished from another.  For nontabular output
     (such as is produced in batch mode or when the '--batch' or
     '--silent' option is given), special characters are escaped in the
     output so they can be identified easily.  Newline, tab, 'NUL', and
     backslash are written as '\n', '\t', '\0', and '\\'.  The '--raw'
     option disables this character escaping.

     The following example demonstrates tabular versus nontabular output
     and the use of raw mode to disable escaping:

          % mysql
          mysql> SELECT CHAR(92);
          +----------+
          | CHAR(92) |
          +----------+
          | \        |
          +----------+

          % mysql -s
          mysql> SELECT CHAR(92);
          CHAR(92)
          \\

          % mysql -s -r
          mysql> SELECT CHAR(92);
          CHAR(92)
          \

   *
     '--reconnect'

     If the connection to the server is lost, automatically try to
     reconnect.  A single reconnect attempt is made each time the
     connection is lost.  To suppress reconnection behavior, use
     '--skip-reconnect'.

   *
     '--safe-updates', '--i-am-a-dummy', '-U'

     Permit only those 'UPDATE' and 'DELETE'
     statements that specify which rows to modify by using key
     values.  If you have set this option in an option file, you can
     override it by using '--safe-updates' on the command line.  See
     mysql-tips, for more information about this option.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--server-public-key-path=FILE_NAME'

     The path name to a file containing a client-side copy of the public
     key required by the server for RSA key pair-based password
     exchange.  The file must be in PEM format.  This option applies to
     clients that authenticate with the 'sha256_password' authentication
     plugin.  This option is ignored for accounts that do not
     authenticate with one of those plugins.  It is also ignored if
     RSA-based password exchange is not used, as is the case when the
     client connects to the server using a secure connection.

     This option is available only if MySQL was built using OpenSSL.

     For information about the 'sha256_password' plugin, see
     sha256-pluggable-authentication.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--show-warnings'

     Cause warnings to be shown after each statement if there are any.
     This option applies to interactive and batch mode.

   *
     '--sigint-ignore'

     Ignore 'SIGINT' signals (typically the result of typing
     'Control+C').

   *
     '--silent', '-s'

     Silent mode.  Produce less output.  This option can be given
     multiple times to produce less and less output.

     This option results in nontabular output format and escaping of
     special characters.  Escaping may be disabled by using raw mode;
     see the description for the '--raw' option.

   *
     '--skip-column-names', '-N'

     Do not write column names in results.

   *
     '--skip-line-numbers', '-L'

     Do not write line numbers for errors.  Useful when you want to
     compare result files that include error messages.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--syslog', '-j'

     This option causes 'mysql' to send interactive
     statements to the system logging facility.  On Unix, this is
     'syslog'; on Windows, it is the Windows Event Log.  The destination
     where logged messages appear is system dependent.  On Linux, the
     destination is often the '/var/log/messages' file.

     Here is a sample of output generated on Linux by using '--syslog'.
     This output is formatted for readability; each logged message
     actually takes a single line.

          Mar  7 12:39:25 myhost MysqlClient[20824]:
            SYSTEM_USER:'oscar', MYSQL_USER:'my_oscar', CONNECTION_ID:23,
            DB_SERVER:'127.0.0.1', DB:'--', QUERY:'USE test;'
          Mar  7 12:39:28 myhost MysqlClient[20824]:
            SYSTEM_USER:'oscar', MYSQL_USER:'my_oscar', CONNECTION_ID:23,
            DB_SERVER:'127.0.0.1', DB:'test', QUERY:'SHOW TABLES;'

     For more information, see mysql-logging.

     The '--syslog' option was added in MySQL 5.7.1.

   *
     '--table', '-t'

     Display output in table format.  This is the default for
     interactive use, but can be used to produce table output in batch
     mode.

   *
     '--tee=FILE_NAME'

     Append a copy of output to the given file.  This option works only
     in interactive mode.  See mysql-commands, discusses tee files
     further.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--unbuffered', '-n'

     Flush the buffer after each query.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--verbose', '-v'

     Verbose mode.  Produce more output about what the program does.
     This option can be given multiple times to produce more and more
     output.  (For example, '-v -v -v' produces table output format even
     in batch mode.)

   *
     '--version', '-V'

     Display version information and exit.

   *
     '--vertical', '-E'

     Print query output rows vertically (one line per column value).
     Without this option, you can specify vertical output for individual
     statements by terminating them with '\G'.

   *
     '--wait', '-w'

     If the connection cannot be established, wait and retry instead of
     aborting.

   *
     '--xml', '-X'

     Produce XML output.

          <field name="COLUMN_NAME">NULL</field>

     The output when '--xml' is used with 'mysql' matches
     that of 'mysqldump'. '--xml'.  See
     mysqldump, for details.

     The XML output also uses an XML namespace, as shown here:

          shell> mysql --xml -uroot -e "SHOW VARIABLES LIKE 'version%'"
          <?xml version="1.0"?>

          <resultset statement="SHOW VARIABLES LIKE 'version%'" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <row>
          <field name="Variable_name">version</field>
          <field name="Value">5.0.40-debug</field>
          </row>

          <row>
          <field name="Variable_name">version_comment</field>
          <field name="Value">Source distribution</field>
          </row>

          <row>
          <field name="Variable_name">version_compile_machine</field>
          <field name="Value">i686</field>
          </row>

          <row>
          <field name="Variable_name">version_compile_os</field>
          <field name="Value">suse-linux-gnu</field>
          </row>
          </resultset>

     (See Bug #25946.)

You can also set the following variables by using '--VAR_NAME=VALUE'.

   *
     'connect_timeout'

     The number of seconds before connection timeout.  (Default value is
     '0'.)

   *
     'max_allowed_packet'

     The maximum size of the buffer for client/server communication.
     The default is 16MB, the maximum is 1GB.

   *
     'max_join_size'

     The automatic limit for rows in a join when using '--safe-updates'.
     (Default value is 1,000,000.)

   *
     'net_buffer_length'

     The buffer size for TCP/IP and socket communication.  (Default
     value is 16KB.)

   *
     'select_limit'

     The automatic limit for 'SELECT' statements when
     using '--safe-updates'.  (Default value is 1,000.)

4.5.1.2 mysql Commands
......................

'mysql' sends each SQL statement that you issue to the
server to be executed.  There is also a set of commands that
'mysql' itself interprets.  For a list of these commands, type
'help' or '\h' at the 'mysql>' prompt:

     mysql> help

     List of all MySQL commands:
     Note that all text commands must be first on line and end with ';'
     ?         (\?) Synonym for `help'.
     clear     (\c) Clear the current input statement.
     connect   (\r) Reconnect to the server. Optional arguments are db and host.
     delimiter (\d) Set statement delimiter.
     edit      (\e) Edit command with $EDITOR.
     ego       (\G) Send command to mysql server, display result vertically.
     exit      (\q) Exit mysql. Same as quit.
     go        (\g) Send command to mysql server.
     help      (\h) Display this help.
     nopager   (\n) Disable pager, print to stdout.
     notee     (\t) Don't write into outfile.
     pager     (\P) Set PAGER [to_pager]. Print the query results via PAGER.
     print     (\p) Print current command.
     prompt    (\R) Change your mysql prompt.
     quit      (\q) Quit mysql.
     rehash    (\#) Rebuild completion hash.
     source    (\.) Execute an SQL script file. Takes a file name as an argument.
     status    (\s) Get status information from the server.
     system    (\!) Execute a system shell command.
     tee       (\T) Set outfile [to_outfile]. Append everything into given
                    outfile.
     use       (\u) Use another database. Takes database name as argument.
     charset   (\C) Switch to another charset. Might be needed for processing
                    binlog with multi-byte charsets.
     warnings  (\W) Show warnings after every statement.
     nowarning (\w) Don't show warnings after every statement.
     resetconnection(\x) Clean session context.

     For server side help, type 'help contents'

If 'mysql' is invoked with the '--binary-mode' option, all
'mysql' commands are disabled except 'charset' and
'delimiter' in non-interactive mode (for input piped to 'mysql'
or loaded using the 'source' command).

Each command has both a long and short form.  The long form is not
case-sensitive; the short form is.  The long form can be followed by an
optional semicolon terminator, but the short form should not.

The use of short-form commands within multiple-line '/* ... */' comments
is not supported.

   *
     'help [ARG]', '\h [ARG]', '\? [ARG]', '? [ARG]'

     Display a help message listing the available 'mysql'.
     commands.

     If you provide an argument to the 'help' command, see 'mysql'
     uses it as a search string to access server-side help from
     the contents of the MySQL Reference Manual.  For more information,
     see mysql-server-side-help.

   *
     'charset CHARSET_NAME', '\C CHARSET_NAME'

     Change the default character set and issue a 'SET NAMES'
     statement.  This enables the character set to remain
     synchronized on the client and server if 'mysql' is
     run with auto-reconnect enabled (which is not recommended), because
     the specified character set is used for reconnects.

   *
     'clear', '\c'

     Clear the current input.  Use this if you change your mind about
     executing the statement that you are entering.

   *
     'connect [DB_NAME HOST_NAME]]', '\r [DB_NAME HOST_NAME]]'

     Reconnect to the server.  The optional database name and host name
     arguments may be given to specify the default database or the host
     where the server is running.  If omitted, the current values are
     used.

   *
     'delimiter STR', '\d STR'

     Change the string that 'mysql' interprets as the
     separator between SQL statements.  The default is the semicolon
     character (';').

     The delimiter string can be specified as an unquoted or quoted
     argument on the 'delimiter' command line.  Quoting can be done with
     either single quote ('''), double quote ('"'), or backtick ('`')
     characters.  To include a quote within a quoted string, either
     quote the string with a different quote character or escape the
     quote with a backslash ('\') character.  Backslash should be
     avoided outside of quoted strings because it is the escape
     character for MySQL. For an unquoted argument, the delimiter is
     read up to the first space or end of line.  For a quoted argument,
     the delimiter is read up to the matching quote on the line.

     'mysql' interprets instances of the delimiter string
     as a statement delimiter anywhere it occurs, except within quoted
     strings.  Be careful about defining a delimiter that might occur
     within other words.  For example, if you define the delimiter as
     'X', you will be unable to use the word 'INDEX' in statements.
     'mysql' interprets this as 'INDE' followed by the
     delimiter 'X'.

     When the delimiter recognized by 'mysql' is set to
     something other than the default of ';', instances of that
     character are sent to the server without interpretation.  However,
     the server itself still interprets ';' as a statement delimiter and
     processes statements accordingly.  This behavior on the server side
     comes into play for multiple-statement execution (see
     c-api-multiple-queries), and for parsing the body of stored
     procedures and functions, triggers, and events (see
     stored-programs-defining).

   *
     'edit', '\e'

     Edit the current input statement.  'mysql' checks the
     values of the 'EDITOR' and 'VISUAL' environment variables to
     determine which editor to use.  The default editor is 'vi' if
     neither variable is set.

     The 'edit' command works only in Unix.

   *
     'ego', '\G'

     Send the current statement to the server to be executed and display
     the result using vertical format.

   *
     'exit', '\q'

     Exit 'mysql'.

   *
     'go', '\g'

     Send the current statement to the server to be executed.

   *
     'nopager', '\n'

     Disable output paging.  See the description for 'pager'.

     The 'nopager' command works only in Unix.

   *
     'notee', '\t'

     Disable output copying to the tee file.  See the description for
     'tee'.

   *
     'nowarning', '\w'

     Disable display of warnings after each statement.

   *
     'pager [COMMAND]', '\P [COMMAND]'

     Enable output paging.  By using the '--pager' option when you
     invoke 'mysql', it is possible to browse or search
     query results in interactive mode with Unix programs such as
     'less', 'more', or any other similar program.  If you specify no
     value for the option, see 'mysql' checks the value of the
     'PAGER' environment variable and sets the pager to that.  Pager
     functionality works only in interactive mode.

     Output paging can be enabled interactively with the 'pager' command
     and disabled with 'nopager'.  The command takes an optional
     argument; if given, the paging program is set to that.  With no
     argument, the pager is set to the pager that was set on the command
     line, or 'stdout' if no pager was specified.

     Output paging works only in Unix because it uses the 'popen()'
     function, which does not exist on Windows.  For Windows, the 'tee'
     option can be used instead to save query output, although it is not
     as convenient as 'pager' for browsing output in some situations.

   *
     'print', '\p'

     Print the current input statement without executing it.

   *
     'prompt [STR]', '\R [STR]'

     Reconfigure the 'mysql' prompt to the given string.
     The special character sequences that can be used in the prompt are
     described later in this section.

     If you specify the 'prompt' command with no argument, see
     'mysql' resets the prompt to the default of 'mysql>'.

   *
     'quit', '\q'

     Exit 'mysql'.

   *
     'rehash', '\#'

     Rebuild the completion hash that enables database, table, and
     column name completion while you are entering statements.  (See the
     description for the '--auto-rehash' option.)

   *
     'resetconnection', '\x'

     Reset the connection to clear the session state.  This command was
     added in MySQL 5.7.3.

     Resetting a connection has effects similar to
     'mysql_change_user()' or an auto-reconnect
     except that the connection is not closed and reopened, and
     re-authentication is not done.  See mysql-change-user) and
     see c-api-auto-reconnect).

     This example shows how 'resetconnection' clears a value maintained
     in the session state:

          mysql> SELECT LAST_INSERT_ID(3);
          +-------------------+
          | LAST_INSERT_ID(3) |
          +-------------------+
          |                 3 |
          +-------------------+

          mysql> SELECT LAST_INSERT_ID();
          +------------------+
          | LAST_INSERT_ID() |
          +------------------+
          |                3 |
          +------------------+

          mysql> resetconnection;

          mysql> SELECT LAST_INSERT_ID();
          +------------------+
          | LAST_INSERT_ID() |
          +------------------+
          |                0 |
          +------------------+

   *
     'source FILE_NAME', '\. FILE_NAME'

     Read the named file and executes the statements contained therein.
     On Windows, you can specify path name separators as '/' or '\\'.

   *
     'status', '\s'

     Provide status information about the connection and the server you
     are using.  If you are running in '--safe-updates' mode, 'status'
     also prints the values for the 'mysql' variables that
     affect your queries.

   *
     'system COMMAND', '\! COMMAND'

     Execute the given command using your default command interpreter.

     The 'system' command works only in Unix.

   *
     'tee [FILE_NAME]', '\T [FILE_NAME]'

     By using the '--tee' option when you invoke 'mysql',
     you can log statements and their output.  All the data displayed on
     the screen is appended into a given file.  This can be very useful
     for debugging purposes also.  'mysql' flushes results
     to the file after each statement, just before it prints its next
     prompt.  Tee functionality works only in interactive mode.

     You can enable this feature interactively with the 'tee' command.
     Without a parameter, the previous file is used.  The 'tee' file can
     be disabled with the 'notee' command.  Executing 'tee' again
     re-enables logging.

   *
     'use DB_NAME', '\u DB_NAME'

     Use DB_NAME as the default database.

   *
     'warnings', '\W'

     Enable display of warnings after each statement (if there are any).

Here are a few tips about the 'pager' command:

   * You can use it to write to a file and the results go only to the
     file:

          mysql> pager cat > /tmp/log.txt

     You can also pass any options for the program that you want to use
     as your pager:

          mysql> pager less -n -i -S

   * In the preceding example, note the '-S' option.  You may find it
     very useful for browsing wide query results.  Sometimes a very wide
     result set is difficult to read on the screen.  The '-S' option to
     'less' can make the result set much more readable because you can
     scroll it horizontally using the left-arrow and right-arrow keys.
     You can also use '-S' interactively within 'less' to switch the
     horizontal-browse mode on and off.  For more information, read the
     'less' manual page:

          shell> man less

   * The '-F' and '-X' options may be used with 'less' to cause it to
     exit if output fits on one screen, which is convenient when no
     scrolling is necessary:

          mysql> pager less -n -i -S -F -X

   * You can specify very complex pager commands for handling query
     output:

          mysql> pager cat | tee /dr1/tmp/res.txt \
                    | tee /dr2/tmp/res2.txt | less -n -i -S

     In this example, the command would send query results to two files
     in two different directories on two different file systems mounted
     on '/dr1' and '/dr2', yet still display the results onscreen using
     'less'.

You can also combine the 'tee' and 'pager' functions.  Have a 'tee' file
enabled and 'pager' set to 'less', and you are able to browse the
results using the 'less' program and still have everything appended into
a file the same time.  The difference between the Unix 'tee' used with
the 'pager' command and the 'mysql' built-in 'tee' command
is that the built-in 'tee' works even if you do not have the Unix 'tee'
available.  The built-in 'tee' also logs everything that is printed on
the screen, whereas the Unix 'tee' used with 'pager' does not log quite
that much.  Additionally, 'tee' file logging can be turned on and off
interactively from within 'mysql'.  This is useful when you
want to log some queries to a file, but not others.

The 'prompt' command reconfigures the default 'mysql>' prompt.  The
string for defining the prompt can contain the following special
sequences.

Option      Description

'\C'        The current connection identifier (MySQL 5.7.6 and
            up)

'\c'        A counter that increments for each statement you
            issue

'\D'        The full current date

'\d'        The default database

'\h'        The server host

'\l'        The current delimiter

'\m'        Minutes of the current time

'\n'        A newline character

'\O'        The current month in three-letter format (Jan, Feb,
            ...)

'\o'        The current month in numeric format

'\P'        am/pm

'\p'        The current TCP/IP port or socket file

'\R'        The current time, in 24-hour military time (0-23)

'\r'        The current time, standard 12-hour time (1-12)

'\S'        Semicolon

'\s'        Seconds of the current time

'\t'        A tab character

'\U'
            Your full 'USER_NAME@HOST_NAME' account name

'\u'        Your user name

'\v'        The server version

'\w'        The current day of the week in three-letter format
            (Mon, Tue, ...)

'\Y'        The current year, four digits

'\y'        The current year, two digits

'\_'        A space

'\ '        A space (a space follows the backslash)

'\''        Single quote

'\"'        Double quote

'\\'        A literal '\' backslash character

'\X'
            X, for any 'X' not listed above

You can set the prompt in several ways:

   * _Use an environment variable._  You can set the 'MYSQL_PS1'
     environment variable to a prompt string.  For example:

          shell> export MYSQL_PS1="(\u@\h) [\d]> "

   * _Use a command-line option._  You can set the '--prompt' option on
     the command line to 'mysql'.  For example:

          shell> mysql --prompt="(\u@\h) [\d]> "
          (user@host) [database]>

   * _Use an option file._  You can set the 'prompt' option in the
     '[mysql]' group of any MySQL option file, such as '/etc/my.cnf' or
     the '.my.cnf' file in your home directory.  For example:

          [mysql]
          prompt=(\\u@\\h) [\\d]>\\_

     In this example, note that the backslashes are doubled.  If you set
     the prompt using the 'prompt' option in an option file, it is
     advisable to double the backslashes when using the special prompt
     options.  There is some overlap in the set of permissible prompt
     options and the set of special escape sequences that are recognized
     in option files.  (The rules for escape sequences in option files
     are listed in option-files.)  The overlap may cause you
     problems if you use single backslashes.  For example, '\s' is
     interpreted as a space rather than as the current seconds value.
     The following example shows how to define a prompt within an option
     file to include the current time in 'HH:MM:SS>' format:

          [mysql]
          prompt="\\r:\\m:\\s> "

   * _Set the prompt interactively._  You can change your prompt
     interactively by using the 'prompt' (or '\R') command.  For
     example:

          mysql> prompt (\u@\h) [\d]>\_
          PROMPT set to '(\u@\h) [\d]>\_'
          (USER@HOST) [DATABASE]>
          (USER@HOST) [DATABASE]> prompt
          Returning to default PROMPT of mysql>
          mysql>

4.5.1.3 mysql Logging
.....................

The 'mysql' client can do these types of logging for
statements executed interactively:

   * On Unix, see 'mysql' writes the statements to a history
     file.  By default, this file is named '.mysql_history' in your home
     directory.  To specify a different file, set the value of the
     'MYSQL_HISTFILE' environment variable.

   * On all platforms, if the '--syslog' option is given, see 'mysql'
     writes the statements to the system logging facility.  On
     Unix, this is 'syslog'; on Windows, it is the Windows Event Log.
     The destination where logged messages appear is system dependent.
     On Linux, the destination is often the '/var/log/messages' file.

The following discussion describes characteristics that apply to all
logging types and provides information specific to each logging type.

*How Logging Occurs*

For each enabled logging destination, statement logging occurs as
follows:

   * Statements are logged only when executed interactively.  Statements
     are noninteractive, for example, when read from a file or a pipe.
     It is also possible to suppress statement logging by using the
     '--batch' or '--execute' option.

   * Statements are ignored and not logged if they match any pattern in
     the 'ignore' list.  This list is described later.

   * 'mysql' logs each nonignored, nonempty statement line
     individually.

   * If a nonignored statement spans multiple lines (not including the
     terminating delimiter), see 'mysql' concatenates the
     lines to form the complete statement, maps newlines to spaces, and
     logs the result, plus a delimiter.

Consequently, an input statement that spans multiple lines can be logged
twice.  Consider this input:

     mysql> SELECT
         -> 'Today is'
         -> ,
         -> CURDATE()
         -> ;

In this case, see 'mysql' logs the 'SELECT', ''Today is'',
',', 'CURDATE()', and ';' lines as it reads them.  It also logs the
complete statement, after mapping 'SELECT\n'Today is'\n,\nCURDATE()' to
'SELECT 'Today is' , CURDATE()', plus a delimiter.  Thus, these lines
appear in logged output:

     SELECT
     'Today is'
     ,
     CURDATE()
     ;
     SELECT 'Today is' , CURDATE();

'mysql' ignores for logging purposes statements that match
any pattern in the 'ignore' list.  By default, the pattern list is
'"*IDENTIFIED*:*PASSWORD*"', to ignore statements that refer to
passwords.  Pattern matching is not case sensitive.  Within patterns,
two characters are special:

   * '?' matches any single character.

   * '*' matches any sequence of zero or more characters.

To specify additional patterns, use the '--histignore' option or set the
'MYSQL_HISTIGNORE' environment variable.  (If both are specified, the
option value takes precedence.)  The value should be a colon-separated
list of one or more patterns, which are appended to the default pattern
list.

Patterns specified on the command line might need to be quoted or
escaped to prevent your command interpreter from treating them
specially.  For example, to suppress logging for 'UPDATE' and 'DELETE'
statements in addition to statements that refer to passwords, invoke
'mysql' like this:

     shell> mysql --histignore="*UPDATE*:*DELETE*"

*Controlling the History File*

The '.mysql_history' file should be protected with a restrictive access
mode because sensitive information might be written to it, such as the
text of SQL statements that contain passwords.  See
password-security-user.

If you do not want to maintain a history file, first remove
'.mysql_history' if it exists.  Then use either of the following
techniques to prevent it from being created again:

   * Set the 'MYSQL_HISTFILE' environment variable to '/dev/null'.  To
     cause this setting to take effect each time you log in, put it in
     one of your shell's startup files.

   * Create '.mysql_history' as a symbolic link to '/dev/null'; this
     need be done only once:

          shell> ln -s /dev/null $HOME/.mysql_history

*syslog Logging Characteristics*

If the '--syslog' option is given, see 'mysql' writes
interactive statements to the system logging facility.  Message logging
has the following characteristics.

Logging occurs at the 'information' level.  This corresponds to the
'LOG_INFO' priority for 'syslog' on Unix/Linux 'syslog' capability and
to 'EVENTLOG_INFORMATION_TYPE' for the Windows Event Log.  Consult your
system documentation for configuration of your logging capability.

Message size is limited to 1024 bytes.

Messages consist of the identifier 'MysqlClient' followed by these
values:

   * 'SYSTEM_USER'

     The system user name (login name) or '--' if the user is unknown.

   * 'MYSQL_USER'

     The MySQL user name (specified with the '--user' option) or '--' if
     the user is unknown.

   * 'CONNECTION_ID':

     The client connection identifier.  This is the same as the
     'CONNECTION_ID()' function value within the session.

   * 'DB_SERVER'

     The server host or '--' if the host is unknown.

   * 'DB'

     The default database or '--' if no database has been selected.

   * 'QUERY'

     The text of the logged statement.

Here is a sample of output generated on Linux by using '--syslog'.  This
output is formatted for readability; each logged message actually takes
a single line.

     Mar  7 12:39:25 myhost MysqlClient[20824]:
       SYSTEM_USER:'oscar', MYSQL_USER:'my_oscar', CONNECTION_ID:23,
       DB_SERVER:'127.0.0.1', DB:'--', QUERY:'USE test;'
     Mar  7 12:39:28 myhost MysqlClient[20824]:
       SYSTEM_USER:'oscar', MYSQL_USER:'my_oscar', CONNECTION_ID:23,
       DB_SERVER:'127.0.0.1', DB:'test', QUERY:'SHOW TABLES;'

4.5.1.4 mysql Server-Side Help
..............................

     mysql> help SEARCH_STRING

If you provide an argument to the 'help' command, see 'mysql'.
uses it as a search string to access server-side help from the contents
of the MySQL Reference Manual.  The proper operation of this command
requires that the help tables in the 'mysql' database be initialized
with help topic information (see server-side-help-support).

If there is no match for the search string, the search fails:

     mysql> help me

     Nothing found
     Please try to run 'help contents' for a list of all accessible topics

Use 'help contents' to see a list of the help categories:

     mysql> help contents
     You asked for help about help category: "Contents"
     For more information, type 'help <item>', where <item> is one of the
     following categories:
        Account Management
        Administration
        Data Definition
        Data Manipulation
        Data Types
        Functions
        Functions and Modifiers for Use with GROUP BY
        Geographic Features
        Language Structure
        Plugins
        Storage Engines
        Stored Routines
        Table Maintenance
        Transactions
        Triggers

If the search string matches multiple items, see 'mysql' shows
a list of matching topics:

     mysql> help logs
     Many help items for your request exist.
     To make a more specific request, please type 'help <item>',
     where <item> is one of the following topics:
        SHOW
        SHOW BINARY LOGS
        SHOW ENGINE
        SHOW LOGS

Use a topic as the search string to see the help entry for that topic:

     mysql> help show binary logs
     Name: 'SHOW BINARY LOGS'
     Description:
     Syntax:
     SHOW BINARY LOGS
     SHOW MASTER LOGS

     Lists the binary log files on the server. This statement is used as
     part of the procedure described in [purge-binary-logs], that shows how
     to determine which logs can be purged.

     mysql> SHOW BINARY LOGS;
     +---------------+-----------+
     | Log_name      | File_size |
     +---------------+-----------+
     | binlog.000015 |    724935 |
     | binlog.000016 |    733481 |
     +---------------+-----------+

The search string can contain the wildcard characters '%' and '_'.
These have the same meaning as for pattern-matching operations performed
with the 'LIKE' operator.  For example, 'HELP rep%' returns a list of
topics that begin with 'rep':

     mysql> HELP rep%
     Many help items for your request exist.
     To make a more specific request, please type 'help <item>',
     where <item> is one of the following
     topics:
        REPAIR TABLE
        REPEAT FUNCTION
        REPEAT LOOP
        REPLACE
        REPLACE FUNCTION

4.5.1.5 Executing SQL Statements from a Text File
.................................................

The 'mysql' client typically is used interactively, like
this:

     shell> mysql DB_NAME

However, it is also possible to put your SQL statements in a file and
then tell 'mysql' to read its input from that file.  To do
so, create a text file TEXT_FILE that contains the statements you wish
to execute.  Then invoke 'mysql' as shown here:

     shell> mysql DB_NAME < TEXT_FILE

If you place a 'USE DB_NAME' statement as the first statement in the
file, it is unnecessary to specify the database name on the command
line:

     shell> mysql < text_file

If you are already running 'mysql', you can execute an SQL
script file using the 'source' command or '\.' command:

     mysql> source FILE_NAME
     mysql> \. FILE_NAME

Sometimes you may want your script to display progress information to
the user.  For this you can insert statements like this:

     SELECT '<info_to_display>' AS ' ';

The statement shown outputs '<info_to_display>'.

You can also invoke 'mysql' with the '--verbose' option,
which causes each statement to be displayed before the result that it
produces.

'mysql' ignores Unicode byte order mark (BOM) characters
at the beginning of input files.  Previously, it read them and sent them
to the server, resulting in a syntax error.  Presence of a BOM does not
cause 'mysql' to change its default character set.  To do
that, invoke 'mysql' with an option such as
'--default-character-set=utf8'.

For more information about batch mode, see batch-mode.

4.5.1.6 mysql Tips
..................

This section describes some techniques that can help you use
'mysql' more effectively.

4.5.1.7 Input-Line Editing
..........................

'mysql' supports input-line editing, which enables you to
modify the current input line in place or recall previous input lines.
For example, the 'left-arrow' and 'right-arrow' keys move horizontally
within the current input line, and the 'up-arrow' and 'down-arrow' keys
move up and down through the set of previously entered lines.
'Backspace' deletes the character before the cursor and typing new
characters enters them at the cursor position.  To enter the line, press
'Enter'.

On Windows, the editing key sequences are the same as supported for
command editing in console windows.  On Unix, the key sequences depend
on the input library used to build 'mysql'. (for example,
the 'libedit' or 'readline' library).

Documentation for the 'libedit' and 'readline' libraries is available
online.  To change the set of key sequences permitted by a given input
library, define key bindings in the library startup file.  This is a
file in your home directory: '.editrc' for 'libedit' and '.inputrc' for
'readline'.

For example, in 'libedit', 'Control+W' deletes everything before the
current cursor position and 'Control+U' deletes the entire line.  In
'readline', 'Control+W' deletes the word before the cursor and
'Control+U' deletes everything before the current cursor position.  If
'mysql' was built using 'libedit', a user who prefers the
'readline' behavior for these two keys can put the following lines in
the '.editrc' file (creating the file if necessary):

     bind "^W" ed-delete-prev-word
     bind "^U" vi-kill-line-prev

To see the current set of key bindings, temporarily put a line that says
only 'bind' at the end of '.editrc'.  'mysql' will show
the bindings when it starts.

4.5.1.8 Unicode Support on Windows
..................................

Windows provides APIs based on UTF-16LE for reading from and writing to
the console; the 'mysql' client for Windows is able to use
these APIs.  The Windows installer creates an item in the MySQL menu
named 'MySQL command line client - Unicode'.  This item invokes the
'mysql' client with properties set to communicate through
the console to the MySQL server using Unicode.

To take advantage of this support manually, run 'mysql'.
within a console that uses a compatible Unicode font and set the default
character set to a Unicode character set that is supported for
communication with the server:

  1. Open a console window.

  2. Go to the console window properties, select the font tab, and
     choose Lucida Console or some other compatible Unicode font.  This
     is necessary because console windows start by default using a DOS
     raster font that is inadequate for Unicode.

  3. Execute 'mysql.exe' with the
     '--default-character-set=utf8' (or 'utf8mb4') option.  This option
     is necessary because 'utf16le' is not supported as a connection
     character set.

With those changes, see 'mysql' will use the Windows APIs to
communicate with the console using UTF-16LE, and communicate with the
server using UTF-8.  (The menu item mentioned previously sets the font
and character set as just described.)

To avoid those steps each time you run 'mysql', you can
create a shortcut that invokes 'mysql.exe'.  The shortcut
should set the console font to Lucida Console or some other compatible
Unicode font, and pass the '--default-character-set=utf8' (or 'utf8mb4')
option to 'mysql.exe'.

Alternatively, create a shortcut that only sets the console font, and
set the character set in the '[mysql]' group of your 'my.ini' file:

     [mysql]
     default-character-set=utf8

4.5.1.9 Displaying Query Results Vertically
...........................................

Some query results are much more readable when displayed vertically,
instead of in the usual horizontal table format.  Queries can be
displayed vertically by terminating the query with \G instead of a
semicolon.  For example, longer text values that include newlines often
are much easier to read with vertical output:

     mysql> SELECT * FROM mails WHERE LENGTH(txt) < 300 LIMIT 300,1\G
     *************************** 1. row ***************************
       msg_nro: 3068
          date: 2000-03-01 23:29:50
     time_zone: +0200
     mail_from: Monty
         reply: monty@no.spam.com
       mail_to: "Thimble Smith" <tim@no.spam.com>
           sbj: UTF-8
           txt: >>>>> "Thimble" == Thimble Smith writes:

     Thimble> Hi.  I think this is a good idea.  Is anyone familiar
     Thimble> with UTF-8 or Unicode? Otherwise, I'll put this on my
     Thimble> TODO list and see what happens.

     Yes, please do that.

     Regards,
     Monty
          file: inbox-jani-1
          hash: 190402944
     1 row in set (0.09 sec)

4.5.1.10 Using the -safe-updates Option
.......................................

For beginners, a useful startup option is '--safe-updates' (or
'--i-am-a-dummy', which has the same effect).  It is helpful for cases
when you might have issued a 'DELETE FROM TBL_NAME' statement but
forgotten the 'WHERE' clause.  Normally, such a statement deletes all
rows from the table.  With '--safe-updates', you can delete rows only by
specifying the key values that identify them.  This helps prevent
accidents.

When you use the '--safe-updates' option, see 'mysql' issues
the following statement when it connects to the MySQL server:

     SET sql_safe_updates=1, sql_select_limit=1000, max_join_size=1000000;

See server-system-variables.

The 'SET' statement has the following effects:

   * You are not permitted to execute an 'UPDATE' or
     'DELETE' statement unless you specify a key
     constraint in the 'WHERE' clause or provide a 'LIMIT' clause (or
     both).  For example:

          UPDATE TBL_NAME SET NOT_KEY_COLUMN=VAL WHERE KEY_COLUMN=VAL;

          UPDATE TBL_NAME SET NOT_KEY_COLUMN=VAL LIMIT 1;

   * The server limits all large 'SELECT' results to
     1,000 rows unless the statement includes a 'LIMIT' clause.

   * The server aborts multiple-table 'SELECT' statements
     that probably need to examine more than 1,000,000 row combinations.

To specify limits different from 1,000 and 1,000,000, you can override
the defaults by using the '--select_limit' and '--max_join_size'
options:

     shell> mysql --safe-updates --select_limit=500 --max_join_size=10000

4.5.1.11 Disabling mysql Auto-Reconnect
.......................................

If the 'mysql' client loses its connection to the server
while sending a statement, it immediately and automatically tries to
reconnect once to the server and send the statement again.  However,
even if 'mysql' succeeds in reconnecting, your first
connection has ended and all your previous session objects and settings
are lost: temporary tables, the autocommit mode, and user-defined and
session variables.  Also, any current transaction rolls back.  This
behavior may be dangerous for you, as in the following example where the
server was shut down and restarted between the first and second
statements without you knowing it:

     mysql> SET @a=1;
     Query OK, 0 rows affected (0.05 sec)

     mysql> INSERT INTO t VALUES(@a);
     ERROR 2006: MySQL server has gone away
     No connection. Trying to reconnect...
     Connection id:    1
     Current database: test

     Query OK, 1 row affected (1.30 sec)

     mysql> SELECT * FROM t;
     +------+
     | a    |
     +------+
     | NULL |
     +------+
     1 row in set (0.05 sec)

The '@a' user variable has been lost with the connection, and after the
reconnection it is undefined.  If it is important to have 'mysql'
terminate with an error if the connection has been lost, you can
start the 'mysql' client with the '--skip-reconnect'
option.

For more information about auto-reconnect and its effect on state
information when a reconnection occurs, see
c-api-auto-reconnect.

4.5.2 'mysqladmin' -- Client for Administering a MySQL Server
-------------------------------------------------------------

'mysqladmin' is a client for performing
administrative operations.  You can use it to check the server's
configuration and current status, to create and drop databases, and
more.

Invoke 'mysqladmin' like this:

     shell> mysqladmin [OPTIONS] COMMAND [COMMAND-ARG] [COMMAND [COMMAND-ARG]] ...

'mysqladmin' supports the following commands.  Some
of the commands take an argument following the command name.

   * 'create DB_NAME'

     Create a new database named DB_NAME.

   * 'debug'

     Tell the server to write debug information to the error log.  The
     connected user must have the 'SUPER' privilege.  Format and content
     of this information is subject to change.

     This includes information about the Event Scheduler.  See
     events-status-info.

   * 'drop DB_NAME'

     Delete the database named DB_NAME and all its tables.

   * 'extended-status'

     Display the server status variables and their values.

   * 'flush-hosts'

     Flush all information in the host cache.

   * 'flush-logs [LOG_TYPE ...]'

     Flush all logs.

     As of MySQL 5.7.5, the 'mysqladmin flush-logs'.
     command permits optional log types to be given, to specify which
     logs to flush.  Following the 'flush-logs' command, you can provide
     a space-separated list of one or more of the following log types:
     'binary', 'engine', 'error', 'general', 'relay', 'slow'.  These
     correspond to the log types that can be specified for the 'FLUSH
     LOGS' SQL statement.

   * 'flush-privileges'

     Reload the grant tables (same as 'reload').

   * 'flush-status'

     Clear status variables.

   * 'flush-tables'

     Flush all tables.

   * 'flush-threads'

     Flush the thread cache.

   * 'kill ID,ID,...'

     Kill server threads.  If multiple thread ID values are given, there
     must be no spaces in the list.

     To kill threads belonging to other users, the connected user must
     have the 'SUPER' privilege.

   * 'old-password NEW_PASSWORD'

     This is like the 'password' command but stores the password using
     the old (pre-4.1) password-hashing format.  (See
     password-hashing.)

     This command was removed in MySQL 5.7.5.

   * 'password NEW_PASSWORD'

     Set a new password.  This changes the password to NEW_PASSWORD for
     the account that you use with 'mysqladmin' for
     connecting to the server.  Thus, the next time you invoke
     'mysqladmin'. (or any other client program) using the
     same account, you will need to specify the new password.

     *Warning*:

     Setting a password using 'mysqladmin' should be
     considered _insecure_.  On some systems, your password becomes
     visible to system status programs such as 'ps' that may be invoked
     by other users to display command lines.  MySQL clients typically
     overwrite the command-line password argument with zeros during
     their initialization sequence.  However, there is still a brief
     interval during which the value is visible.  Also, on some systems
     this overwriting strategy is ineffective and the password remains
     visible to 'ps'.  (SystemV Unix systems and perhaps others are
     subject to this problem.)

     If the NEW_PASSWORD value contains spaces or other characters that
     are special to your command interpreter, you need to enclose it
     within quotation marks.  On Windows, be sure to use double
     quotation marks rather than single quotation marks; single
     quotation marks are not stripped from the password, but rather are
     interpreted as part of the password.  For example:

          shell> mysqladmin password "my new password"

     In MySQL 5.7, the new password can be omitted following the
     'password' command.  In this case, see 'mysqladmin'.
     prompts for the password value, which enables you to avoid
     specifying the password on the command line.  Omitting the password
     value should be done only if 'password' is the final command on the
     'mysqladmin' command line.  Otherwise, the next
     argument is taken as the password.

     *Caution*:

     Do not use this command used if the server was started with the
     '--skip-grant-tables' option.  No password change will be applied.
     This is true even if you precede the 'password' command with
     'flush-privileges' on the same command line to re-enable the grant
     tables because the flush operation occurs after you connect.
     However, you can use 'mysqladmin flush-privileges'
     to re-enable the grant table and then use a separate
     'mysqladmin password' command to change the
     password.

   * 'ping'

     Check whether the server is available.  The return status from
     'mysqladmin' is 0 if the server is running, 1 if
     it is not.  This is 0 even in case of an error such as 'Access
     denied', because this means that the server is running but refused
     the connection, which is different from the server not running.

   * 'processlist'

     Show a list of active server threads.  This is like the output of
     the 'SHOW PROCESSLIST' statement.  If the
     '--verbose' option is given, the output is like that of 'SHOW FULL PROCESSLIST'.
     (See
     show-processlist.)

   * 'reload'

     Reload the grant tables.

   * 'refresh'

     Flush all tables and close and open log files.

   * 'shutdown'

     Stop the server.

   * 'start-slave'

     Start replication on a slave server.

   * 'status'

     Display a short server status message.

   * 'stop-slave'

     Stop replication on a slave server.

   * 'variables'

     Display the server system variables and their values.

   * 'version'

     Display version information from the server.

All commands can be shortened to any unique prefix.  For example:

     shell> mysqladmin proc stat
     +----+-------+-----------+----+---------+------+-------+------------------+
     | Id | User  | Host      | db | Command | Time | State | Info             |
     +----+-------+-----------+----+---------+------+-------+------------------+
     | 51 | monty | localhost |    | Query   | 0    |       | show processlist |
     +----+-------+-----------+----+---------+------+-------+------------------+
     Uptime: 1473624  Threads: 1  Questions: 39487
     Slow queries: 0  Opens: 541  Flush tables: 1
     Open tables: 19  Queries per second avg: 0.0268

The 'mysqladmin status' command result displays the
following values:

   *
     'Uptime'

     The number of seconds the MySQL server has been running.

   *
     'Threads'

     The number of active threads (clients).

   *
     'Questions'

     The number of questions (queries) from clients since the server was
     started.

   *
     'Slow queries'

     The number of queries that have taken more than 'long_query_time'
     seconds.  See slow-query-log.

   *
     'Opens'

     The number of tables the server has opened.

   *
     'Flush tables'

     The number of 'flush-*', 'refresh', and 'reload' commands the
     server has executed.

   *
     'Open tables'

     The number of tables that currently are open.

If you execute 'mysqladmin shutdown' when connecting
to a local server using a Unix socket file, see 'mysqladmin'
waits until the server's process ID file has been removed,
to ensure that the server has stopped properly.

'mysqladmin' supports the following options, which
can be specified on the command line or in the '[mysqladmin]' and
'[client]' groups of an option file.  For information about option files
used by MySQL programs, see option-files.

*mysqladmin Options*

Format              Description                          IntroducedDeprecated

-bind-address       Use specified network interface to
                    connect to MySQL Server

-compress           Compress all information sent
                    between client and server

-connect_timeout    Number of seconds before
                    connection timeout

-count              Number of iterations to make for
                    repeated command execution

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-default-character-setSpecify default character set

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-enable-cleartext-pluginEnable cleartext authentication
                    plugin

-force              Continue even if an SQL error
                    occurs

-help               Display help message and exit

-host               Connect to MySQL server on given
                    host

-login-path         Read login path options from
                    .mylogin.cnf

-no-beep            Do not beep when errors occur

-no-defaults        Read no option files

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-protocol           Connection protocol to use

-relative           Show the difference between the
                    current and previous values when
                    used with the -sleep option

-secure-auth        Do not send passwords to server in   5.7.4    5.7.5
                    old (pre-4.1) format

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-show-warnings      Show warnings after statement        5.7.2
                    execution

-shutdown_timeout   The maximum number of seconds to
                    wait for server shutdown

-silent             Silent mode

-sleep              Execute commands repeatedly,
                    sleeping for delay seconds in
                    between

-socket             For connections to localhost, the
                    Unix socket file to use

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version            Display version information and
                    exit

-vertical           Print query output rows vertically
                    (one line per column value)

-wait               If the connection cannot be
                    established, wait and retry
                    instead of aborting

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--count=N', '-c N'

     The number of iterations to make for repeated command execution if
     the '--sleep' option is given.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o,/tmp/mysqladmin.trace'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set.  See
     charset-configuration.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqladmin'
     normally reads the '[client]' and '[mysqladmin]'
     groups.  If the '--defaults-group-suffix=_other' option is given,
     see 'mysqladmin' also reads the '[client_other]' and
     '[mysqladmin_other]' groups.

   *
     '--enable-cleartext-plugin'

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     (See cleartext-pluggable-authentication.)

   *
     '--force', '-f'

     Do not ask for confirmation for the 'drop DB_NAME' command.  With
     multiple commands, continue even if an error occurs.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--no-beep', '-b'

     Suppress the warning beep that is emitted by default for errors
     such as a failure to connect to the server.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqladmin' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqladmin' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--relative', '-r'

     Show the difference between the current and previous values when
     used with the '--sleep' option.  This option works only with the
     'extended-status' command.

   *
     '--show-warnings'

     Show warnings resulting from execution of statements sent to the
     server.  This option was added in MySQL 5.7.2.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.  This option was added in MySQL 5.7.4.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--silent', '-s'

     Exit silently if a connection to the server cannot be established.

   *
     '--sleep=DELAY', '-i DELAY'

     Execute commands repeatedly, sleeping for DELAY seconds in between.
     The '--count' option determines the number of iterations.  If
     '--count' is not given, see 'mysqladmin' executes
     commands indefinitely until interrupted.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.

   *
     '--version', '-V'

     Display version information and exit.

   *
     '--vertical', '-E'

     Print output vertically.  This is similar to '--relative', but
     prints output vertically.

   *
     '--wait[=COUNT]', '-w[COUNT]'

     If the connection cannot be established, wait and retry instead of
     aborting.  If a COUNT value is given, it indicates the number of
     times to retry.  The default is one time.

You can also set the following variables by using '--VAR_NAME=VALUE'.

   *
     'connect_timeout'

     The maximum number of seconds before connection timeout.  The
     default value is 43200 (12 hours).

   *
     'shutdown_timeout'

     The maximum number of seconds to wait for server shutdown.  The
     default value is 3600 (1 hour).

4.5.3 'mysqlcheck' -- A Table Maintenance Program
-------------------------------------------------

The 'mysqlcheck' client performs table maintenance:
It checks, repairs, optimizes, or analyzes tables.

Each table is locked and therefore unavailable to other sessions while
it is being processed, although for check operations, the table is
locked with a 'READ' lock only (see lock-tables, for more
information about 'READ' and 'WRITE' locks).  Table maintenance
operations can be time-consuming, particularly for large tables.  If you
use the '--databases' or '--all-databases' option to process all tables
in one or more databases, an invocation of 'mysqlcheck'
might take a long time.  (This is also true for
'mysql_upgrade' because that program invokes
'mysqlcheck' to check all tables and repair them if
necessary.)

'mysqlcheck' must be used when the 'mysqld'
server is running, which means that you do not have to stop the
server to perform table maintenance.

'mysqlcheck' uses the SQL statements 'CHECK TABLE',
see 'REPAIR TABLE', 'ANALYZE TABLE',
and 'OPTIMIZE TABLE' in a
convenient way for the user.  It determines which statements to use for
the operation you want to perform, and then sends the statements to the
server to be executed.  For details about which storage engines each
statement works with, see the descriptions for those statements in
table-maintenance-sql.

All storage engines do not necessarily support all four maintenance
operations.  In such cases, an error message is displayed.  For example,
if 'test.t' is an 'MEMORY' table, an attempt to check it produces this
result:

     shell> mysqlcheck test t
     test.t
     note     : The storage engine for the table doesn't support check

If 'mysqlcheck' is unable to repair a table, see
rebuilding-tables for manual table repair strategies.  This will
be the case, for example, for 'InnoDB' tables, which can be checked with
'CHECK TABLE', but not repaired with 'REPAIR TABLE'.

*Caution*:

It is best to make a backup of a table before performing a table repair
operation; under some circumstances the operation might cause data loss.
Possible causes include but are not limited to file system errors.

There are three general ways to invoke 'mysqlcheck'.:

     shell> mysqlcheck [OPTIONS] DB_NAME [TBL_NAME ...]
     shell> mysqlcheck [OPTIONS] --databases DB_NAME ...
     shell> mysqlcheck [OPTIONS] --all-databases

If you do not name any tables following DB_NAME or if you use the
'--databases' or '--all-databases' option, entire databases are checked.

'mysqlcheck' has a special feature compared to other
client programs.  The default behavior of checking tables ('--check')
can be changed by renaming the binary.  If you want to have a tool that
repairs tables by default, you should just make a copy of
'mysqlcheck' named 'mysqlrepair', or make a symbolic link
to 'mysqlcheck' named 'mysqlrepair'.  If you invoke
'mysqlrepair', it repairs tables.

The names shown in the following table can be used to change
'mysqlcheck' default behavior.

Command            Meaning

'mysqlrepair'      The default option is '--repair'

'mysqlanalyze'     The default option is '--analyze'

'mysqloptimize'    The default option is '--optimize'

'mysqlcheck' supports the following options, which
can be specified on the command line or in the '[mysqlcheck]' and
'[client]' groups of an option file.  For information about option files
used by MySQL programs, see option-files.

*mysqlcheck Options*

Format              Description                          IntroducedDeprecated

-all-databases      Check all tables in all databases

-all-in-1           Execute a single statement for
                    each database that names all the
                    tables from that database

-analyze            Analyze the tables

-auto-repair        If a checked table is corrupted,
                    automatically fix it

-bind-address       Use specified network interface to
                    connect to MySQL Server

-character-sets-dir Directory where character sets are
                    installed

-check              Check the tables for errors

-check-only-changed Check only tables that have
                    changed since the last check

-check-upgrade      Invoke CHECK TABLE with the FOR
                    UPGRADE option

-compress           Compress all information sent
                    between client and server

-databases          Interpret all arguments as
                    database names

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-default-character-setSpecify default character set

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-enable-cleartext-pluginEnable cleartext authentication  5.7.10
                    plugin

-extended           Check and repair tables

-fast               Check only tables that have not
                    been closed properly

-fix-db-names       Convert database names to 5.1                 5.7.6
                    format

-fix-table-names    Convert table names to 5.1 format             5.7.6

-force              Continue even if an SQL error
                    occurs

-help               Display help message and exit

-host               Connect to MySQL server on given
                    host

-login-path         Read login path options from
                    .mylogin.cnf

-medium-check       Do a check that is faster than an
                    -extended operation

-no-defaults        Read no option files

-optimize           Optimize the tables

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-protocol           Connection protocol to use

-quick              The fastest method of checking

-repair             Perform a repair that can fix
                    almost anything except unique keys
                    that are not unique

-secure-auth        Do not send passwords to server in   5.7.4    5.7.5
                    old (pre-4.1) format

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-silent             Silent mode

-skip-database      Omit this database from performed    5.7.1
                    operations

-socket             For connections to localhost, the
                    Unix socket file to use

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-tables             Overrides the -databases or -B
                    option

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-use-frm            For repair operations on MyISAM
                    tables

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version            Display version information and
                    exit

-write-binlog       Log ANALYZE, OPTIMIZE, REPAIR
                    statements to binary log.
                    -skip-write-binlog adds
                    NO_WRITE_TO_BINLOG to these
                    statements.

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--all-databases', '-A'

     Check all tables in all databases.  This is the same as using the
     '--databases' option and naming all the databases on the command
     line, except that the 'INFORMATION_SCHEMA' and 'performace_schema'
     databases are not checked.  They can be checked by explicitly
     naming them with the '--databases' option.

   *
     '--all-in-1', '-1'

     Instead of issuing a statement for each table, execute a single
     statement for each database that names all the tables from that
     database to be processed.

   *
     '--analyze', '-a'

     Analyze the tables.

   *
     '--auto-repair'

     If a checked table is corrupted, automatically fix it.  Any
     necessary repairs are done after all tables have been checked.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--check', '-c'

     Check the tables for errors.  This is the default operation.

   *
     '--check-only-changed', '-C'

     Check only tables that have changed since the last check or that
     have not been closed properly.

   *
     '--check-upgrade', '-g'

     Invoke 'CHECK TABLE' with the 'FOR UPGRADE'
     option to check tables for incompatibilities with the current
     version of the server.  This option automatically enables the
     '--fix-db-names' and '--fix-table-names' options.

   *
     '--compress'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--databases', '-B'

     Process all tables in the named databases.  Normally, see
     'mysqlcheck' treats the first name argument on the
     command line as a database name and any following names as table
     names.  With this option, it treats all name arguments as database
     names.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set.  See
     charset-configuration.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqlcheck'
     normally reads the '[client]' and '[mysqlcheck]'
     groups.  If the '--defaults-group-suffix=_other' option is given,
     see 'mysqlcheck' also reads the '[client_other]' and
     '[mysqlcheck_other]' groups.

   *
     '--extended', '-e'

     If you are using this option to check tables, it ensures that they
     are 100% consistent but takes a long time.

     If you are using this option to repair tables, it runs an extended
     repair that may not only take a long time to execute, but may
     produce a lot of garbage rows also!

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--enable-cleartext-plugin'

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     (See cleartext-pluggable-authentication.)

     This option was added in MySQL 5.7.10.

   *
     '--fast', '-F'

     Check only tables that have not been closed properly.

   *
     '--fix-db-names'

     Convert database names to 5.1 format.  Only database names that
     contain special characters are affected.

     This option is deprecated in MySQL 5.7.6 and will be removed in a
     future version of MySQL. If it is necessary to convert MySQL 5.0
     database or table names, a workaround is to upgrade a MySQL 5.0
     installation to MySQL 5.1 before upgrading to a more recent
     release.

   *
     '--fix-table-names'

     Convert table names to 5.1 format.  Only table names that contain
     special characters are affected.  This option also applies to
     views.

     This option is deprecated in MySQL 5.7.6 and will be removed in a
     future version of MySQL. If it is necessary to convert MySQL 5.0
     database or table names, a workaround is to upgrade a MySQL 5.0
     installation to MySQL 5.1 before upgrading to a more recent
     release.

   *
     '--force', '-f'

     Continue even if an SQL error occurs.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--medium-check', '-m'

     Do a check that is faster than an '--extended' operation.  This
     finds only 99.99% of all errors, which should be good enough in
     most cases.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--optimize', '-o'

     Optimize the tables.

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqlcheck' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqlcheck' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--quick', '-q'

     If you are using this option to check tables, it prevents the check
     from scanning the rows to check for incorrect links.  This is the
     fastest check method.

     If you are using this option to repair tables, it tries to repair
     only the index tree.  This is the fastest repair method.

   *
     '--repair', '-r'

     Perform a repair that can fix almost anything except unique keys
     that are not unique.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.  This option was added in MySQL 5.7.4.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--silent', '-s'

     Silent mode.  Print only error messages.

   *
     '--skip-database=DB_NAME'

     Do not include the named database (case-sensitive) in the
     operations performed by 'mysqlcheck'.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tables'

     Override the '--databases' or '-B' option.  All name arguments
     following the option are regarded as table names.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--use-frm'

     For repair operations on 'MyISAM' tables, get the table structure
     from the '.frm' file so that the table can be repaired even if the
     '.MYI' header is corrupted.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--verbose', '-v'

     Verbose mode.  Print information about the various stages of
     program operation.

   *
     '--version', '-V'

     Display version information and exit.

   *
     '--write-binlog'

     This option is enabled by default, so that 'ANALYZE TABLE',
     see 'OPTIMIZE TABLE', and
     'REPAIR TABLE' statements generated by
     'mysqlcheck' are written to the binary log.  Use
     '--skip-write-binlog' to cause 'NO_WRITE_TO_BINLOG' to be added to
     the statements so that they are not logged.  Use the
     '--skip-write-binlog' when these statements should not be sent to
     replication slaves or run when using the binary logs for recovery
     from backup.

4.5.4 'mysqldump' -- A Database Backup Program
----------------------------------------------

The 'mysqldump' client utility performs logical
backups, producing a set of SQL statements that can be executed to
reproduce the original database object definitions and table data.  It
dumps one or more MySQL databases for backup or transfer to another SQL
server.  The 'mysqldump' command can also generate
output in CSV, other delimited text, or XML format.

   * mysqldump-performance

   * mysqldump-syntax

   * mysqldump-option-summary

   * mysqldump-connection-options

   * mysqldump-option-file-options

   * mysqldump-ddl-options

   * mysqldump-debug-options

   * mysqldump-help-options

   * mysqldump-i18n-options

   * mysqldump-replication-options

   * mysqldump-format-options

   * mysqldump-filter-options

   * mysqldump-performance-options

   * mysqldump-transaction-options

   * mysqldump-option-groups

   * mysqldump-option-examples

   * mysqldump-restrictions

*Note*:

If you have tables that contain generated columns, use the
'mysqldump' utility provided with MySQL 5.7.9 or higher to
create your dump files.  The 'mysqldump' utility
provided in earlier releases uses incorrect syntax for generated column
definitions (Bug #20769542).  You can use the
'INFORMATION_SCHEMA.COLUMNS' table to identify tables
with generated columns.

'mysqldump' requires at least the 'SELECT' privilege
for dumped tables, 'SHOW VIEW' for dumped views, 'TRIGGER' for dumped
triggers, and 'LOCK TABLES' if the '--single-transaction' option is not
used.  Certain options might require other privileges as noted in the
option descriptions.

To reload a dump file, you must have the privileges required to execute
the statements that it contains, such as the appropriate 'CREATE'
privileges for objects created by those statements.

'mysqldump' output can include 'ALTER DATABASE'
statements that change the database collation.  These
may be used when dumping stored programs to preserve their character
encodings.  To reload a dump file containing such statements, the
'ALTER' privilege for the affected database is required.

*Note*:

A dump made using PowerShell on Windows with output redirection creates
a file that has UTF-16 encoding:

     shell> mysqldump [options] > dump.sql

However, UTF-16 is not permitted as a connection character set (see
charset-connection), so the dump file will not load correctly.
To work around this issue, use the '--result-file' option, which creates
the output in ASCII format:

     shell> mysqldump [options] --result-file=dump.sql

*Performance and Scalability Considerations*

'mysqldump' advantages include the convenience and flexibility of
viewing or even editing the output before restoring.  You can clone
databases for development and DBA work, or produce slight variations of
an existing database for testing.  It is not intended as a fast or
scalable solution for backing up substantial amounts of data.  With
large data sizes, even if the backup step takes a reasonable time,
restoring the data can be very slow because replaying the SQL statements
involves disk I/O for insertion, index creation, and so on.

For large-scale backup and restore, a physical backup is more
appropriate, to copy the data files in their original format that can be
restored quickly:

   * If your tables are primarily 'InnoDB' tables, or if you have a mix
     of 'InnoDB' and 'MyISAM' tables, consider using the 'mysqlbackup'
     command of the MySQL Enterprise Backup product.  (Available as part
     of the Enterprise subscription.)  It provides the best performance
     for 'InnoDB' backups with minimal disruption; it can also back up
     tables from 'MyISAM' and other storage engines; and it provides a
     number of convenient options to accommodate different backup
     scenarios.  See mysql-enterprise-backup.

'mysqldump' can retrieve and dump table contents row
by row, or it can retrieve the entire content from a table and buffer it
in memory before dumping it.  Buffering in memory can be a problem if
you are dumping large tables.  To dump tables row by row, use the
'--quick' option (or '--opt', which enables '--quick').  The '--opt'
option (and hence '--quick') is enabled by default, so to enable memory
buffering, use '--skip-quick'.

If you are using a recent version of 'mysqldump' to
generate a dump to be reloaded into a very old MySQL server, use the
'--skip-opt' option instead of the '--opt' or '--extended-insert'
option.

For additional information about 'mysqldump', see
using-mysqldump.

*Invocation Syntax*

There are in general three ways to use 'mysqldump'.--in
order to dump a set of one or more tables, a set of one or more complete
databases, or an entire MySQL server--as shown here:

     shell> mysqldump [OPTIONS] DB_NAME [TBL_NAME ...]
     shell> mysqldump [OPTIONS] --databases DB_NAME ...
     shell> mysqldump [OPTIONS] --all-databases

To dump entire databases, do not name any tables following DB_NAME, or
use the '--databases' or '--all-databases' option.

To see a list of the options your version of 'mysqldump'
supports, issue the command 'mysqldump --help'.

*Option Syntax - Alphabetical Summary*

'mysqldump' supports the following options, which can
be specified on the command line or in the '[mysqldump]' and '[client]'
groups of an option file.  For information about option files used by
MySQL programs, see option-files.

*mysqldump Options*

Format              Description                          IntroducedDeprecated

-add-drop-database  Add DROP DATABASE statement before
                    each CREATE DATABASE statement

-add-drop-table     Add DROP TABLE statement before
                    each CREATE TABLE statement

-add-drop-trigger   Add DROP TRIGGER statement before
                    each CREATE TRIGGER statement

-add-locks          Surround each table dump with LOCK
                    TABLES and UNLOCK TABLES
                    statements

-all-databases      Dump all tables in all databases

-allow-keywords     Allow creation of column names
                    that are keywords

-apply-slave-statementsInclude STOP SLAVE prior to CHANGE
                    MASTER statement and START SLAVE
                    at end of output

-bind-address       Use specified network interface to
                    connect to MySQL Server

-character-sets-dir Directory where character sets are
                    installed

-comments           Add comments to dump file

-compact            Produce more compact output

-compatible         Produce output that is more
                    compatible with other database
                    systems or with older MySQL
                    servers

-complete-insert    Use complete INSERT statements
                    that include column names

-compress           Compress all information sent
                    between client and server

-create-options     Include all MySQL-specific table
                    options in CREATE TABLE statements

-databases          Interpret all name arguments as
                    database names

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-default-character-setSpecify default character set

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-delete-master-logs On a master replication server,
                    delete the binary logs after
                    performing the dump operation

-disable-keys       For each table, surround INSERT
                    statements with statements to
                    disable and enable keys

-dump-date          Include dump date as "Dump
                    completed on" comment if -comments
                    is given

-dump-slave         Include CHANGE MASTER statement
                    that lists binary log coordinates
                    of slave's master

-enable-cleartext-pluginEnable cleartext authentication  5.7.10
                    plugin

-events             Dump events from dumped databases

-extended-insert    Use multiple-row INSERT syntax

-fields-enclosed-by This option is used with the -tab
                    option and has the same meaning as
                    the corresponding clause for LOAD
                    DATA INFILE

-fields-escaped-by  This option is used with the -tab
                    option and has the same meaning as
                    the corresponding clause for LOAD
                    DATA INFILE

-fields-optionally-enclosed-byThis option is used with the -tab
                    option and has the same meaning as
                    the corresponding clause for LOAD
                    DATA INFILE

-fields-terminated-byThis option is used with the -tab
                    option and has the same meaning as
                    the corresponding clause for LOAD
                    DATA INFILE

-flush-logs         Flush MySQL server log files
                    before starting dump

-flush-privileges   Emit a FLUSH PRIVILEGES statement
                    after dumping mysql database

-force              Continue even if an SQL error
                    occurs during a table dump

-help               Display help message and exit

-hex-blob           Dump binary columns using
                    hexadecimal notation

-host               Host to connect to (IP address or
                    hostname)

-ignore-error       Ignore specified errors              5.7.1

-ignore-table       Do not dump given table

-include-master-host-portInclude MASTER_HOST/MASTER_PORT
                    options in CHANGE MASTER statement
                    produced with -dump-slave

-insert-ignore      Write INSERT IGNORE rather than
                    INSERT statements

-lines-terminated-byThis option is used with the -tab
                    option and has the same meaning as
                    the corresponding clause for LOAD
                    DATA INFILE

-lock-all-tables    Lock all tables across all
                    databases

-lock-tables        Lock all tables before dumping
                    them

-log-error          Append warnings and errors to
                    named file

-login-path         Read login path options from
                    .mylogin.cnf

-master-data        Write the binary log file name and
                    position to the output

-max_allowed_packet Maximum packet length to send to
                    or receive from server

-net_buffer_length  Buffer size for TCP/IP and socket
                    communication

-no-autocommit      Enclose the INSERT statements for
                    each dumped table within SET
                    autocommit = 0 and COMMIT
                    statements

-no-create-db       Do not write CREATE DATABASE
                    statements

-no-create-info     Do not write CREATE TABLE
                    statements that re-create each
                    dumped table

-no-data            Do not dump table contents

-no-defaults        Read no option files

-no-set-names       Same as -skip-set-charset

-no-tablespaces     Do not write any CREATE LOGFILE
                    GROUP or CREATE TABLESPACE
                    statements in output

-opt                Shorthand for -add-drop-table
                    -add-locks -create-options
                    -disable-keys -extended-insert
                    -lock-tables -quick -set-charset.

-order-by-primary   Dump each table's rows sorted by
                    its primary key, or by its first
                    unique index

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-protocol           Connection protocol to use

-quick              Retrieve rows for a table from the
                    server a row at a time

-quote-names        Quote identifiers within backtick
                    characters

-replace            Write REPLACE statements rather
                    than INSERT statements

-result-file        Direct output to a given file

-routines           Dump stored routines (procedures
                    and functions) from dumped
                    databases

-secure-auth        Do not send passwords to server in   5.7.4    5.7.5
                    old (pre-4.1) format

-set-charset        Add SET NAMES
                    default_character_set to output

-set-gtid-purged    Whether to add SET
                    @@GLOBAL.GTID_PURGED to output

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-single-transaction Issue a BEGIN SQL statement before
                    dumping data from server

-skip-add-drop-tableDo not add a DROP TABLE statement
                    before each CREATE TABLE statement

-skip-add-locks     Do not add locks

-skip-comments      Do not add comments to dump file

-skip-compact       Do not produce more compact output

-skip-disable-keys  Do not disable keys

-skip-extended-insertTurn off extended-insert

-skip-opt           Turn off options set by -opt

-skip-quick         Do not retrieve rows for a table
                    from the server a row at a time

-skip-quote-names   Do not quote identifiers

-skip-set-charset   Do not write SET NAMES statement

-skip-triggers      Do not dump triggers

-skip-tz-utc        Turn off tz-utc

-socket             For connections to localhost, the
                    Unix socket file to use

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-tab                Produce tab-separated data files

-tables             Override -databases or -B option

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-triggers           Dump triggers for each dumped
                    table

-tz-utc             Add SET TIME_ZONE='+00:00' to dump
                    file

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version            Display version information and
                    exit

-where              Dump only rows selected by given
                    WHERE condition

-xml                Produce XML output

*Connection Options*

The 'mysqldump' command logs into a MySQL server to
extract information.  The following options specify how to connect to
the MySQL server, either on the same machine or a remote system.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--enable-cleartext-plugin'

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     (See cleartext-pluggable-authentication.)

     This option was added in MySQL 5.7.10.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Dump data from the MySQL server on the given host.  The default
     host is 'localhost'.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqldump' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqldump' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.  This option was added in MySQL 5.7.4.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

You can also set the following variables by using '--VAR_NAME=VALUE'
syntax:

   * 'max_allowed_packet'

     The maximum size of the buffer for client/server communication.
     The default is 24MB, the maximum is 1GB.

   * 'net_buffer_length'

     The initial size of the buffer for client/server communication.
     When creating multiple-row 'INSERT' statements (as
     with the '--extended-insert' or '--opt' option), see 'mysqldump'
     creates rows up to 'net_buffer_length' bytes long.  If
     you increase this variable, ensure that the MySQL server
     'net_buffer_length' system variable has a value at least this
     large.

*Option-File Options*

These options are used to control which option files to read.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqldump'
     normally reads the '[client]' and '[mysqldump]' groups.
     If the '--defaults-group-suffix=_other' option is given, see
     'mysqldump' also reads the '[client_other]' and
     '[mysqldump_other]' groups.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

*DDL Options*

Usage scenarios for 'mysqldump' include setting up an
entire new MySQL instance (including database tables), and replacing
data inside an existing instance with existing databases and tables.
The following options let you specify which things to tear down and set
up when restoring a dump, by encoding various DDL statements within the
dump file.

   *
     '--add-drop-database'

     Write a 'DROP DATABASE' statement before each
     'CREATE DATABASE' statement.  This option
     is typically used in conjunction with the '--all-databases' or
     '--databases' option because no 'CREATE DATABASE'
     statements are written unless one of those options
     is specified.

   *
     '--add-drop-table'

     Write a 'DROP TABLE' statement before each
     'CREATE TABLE' statement.

   *
     '--add-drop-trigger'

     Write a 'DROP TRIGGER' statement before each
     'CREATE TRIGGER' statement.

   *
     '--all-tablespaces', '-Y'

     Adds to a table dump all SQL statements needed to create any
     tablespaces used by an 'NDB' table.  This
     information is not otherwise included in the output from
     'mysqldump'.  This option is currently relevant only to
     NDB Cluster tables, which are not supported in MySQL 5.7.

   *
     '--no-create-db', '-n'

     Suppress the 'CREATE DATABASE' statements
     that are otherwise included in the output if the '--databases' or
     '--all-databases' option is given.

   *
     '--no-create-info', '-t'

     Do not write 'CREATE TABLE' statements that
     create each dumped table.

     *Note*:

     This option does _not_ exclude statements creating log file groups
     or tablespaces from 'mysqldump' output; however,
     you can use the '--no-tablespaces' option for this purpose.

   *
     '--no-tablespaces', '-y'

     This option suppresses all 'CREATE LOGFILE GROUP'
     and 'CREATE TABLESPACE'
     statements in the output of 'mysqldump'.

   *
     '--replace'

     Write 'REPLACE' statements rather than
     'INSERT' statements.

*Debug Options*

The following options print debugging information, encode debugging
information in the dump file, or let the dump operation proceed
regardless of potential problems.

   *
     '--allow-keywords'

     Permit creation of column names that are keywords.  This works by
     prefixing each column name with the table name.

   *
     '--comments', '-i'

     Write additional information in the dump file such as program
     version, server version, and host.  This option is enabled by
     default.  To suppress this additional information, use
     '--skip-comments'.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default value is
     'd:t:o,/tmp/mysqldump.trace'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--dump-date'

     If the '--comments' option is given, see 'mysqldump'.
     produces a comment at the end of the dump of the following form:

          -- Dump completed on DATE

     However, the date causes dump files taken at different times to
     appear to be different, even if the data are otherwise identical.
     '--dump-date' and '--skip-dump-date' control whether the date is
     added to the comment.  The default is '--dump-date' (include the
     date in the comment).  '--skip-dump-date' suppresses date printing.

   *
     '--force', '-f'

     Ignore all errors; continue even if an SQL error occurs during a
     table dump.

     One use for this option is to cause 'mysqldump'.
     to continue executing even when it encounters a view that has
     become invalid because the definition refers to a table that has
     been dropped.  Without '--force', see 'mysqldump'.
     exits with an error message.  With '--force', see 'mysqldump'
     prints the error message, but it also writes an SQL
     comment containing the view definition to the dump output and
     continues executing.

     If the '--ignore-error' option is also given to ignore specific
     errors, '--force' takes precedence.

   *
     '--log-error=FILE_NAME'

     Log warnings and errors by appending them to the named file.  The
     default is to do no logging.

   *
     '--skip-comments'

     See the description for the '--comments' option.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.

*Help Options*

The following options display information about the 'mysqldump'
command itself.

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--version', '-V'

     Display version information and exit.

*Internationalization Options*

The following options change how the 'mysqldump'.
command represents character data with national language settings.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set.  See
     charset-configuration.  If no character set is specified, see
     'mysqldump' uses 'utf8'.

   *
     '--no-set-names', '-N'

     Turns off the '--set-charset' setting, the same as specifying
     '--skip-set-charset'.

   *
     '--set-charset'

     Write 'SET NAMES DEFAULT_CHARACTER_SET' to the
     output.  This option is enabled by default.  To suppress the
     'SET NAMES' statement, use '--skip-set-charset'.

*Replication Options*

The 'mysqldump' command is frequently used to create
an empty instance, or an instance including data, on a slave server in a
replication configuration.  The following options apply to dumping and
restoring data on replication master and slave servers.

   *
     '--apply-slave-statements'

     For a slave dump produced with the '--dump-slave' option, add a
     'STOP SLAVE' statement before the 'CHANGE MASTER TO'
     statement and a 'START SLAVE'
     statement at the end of the output.

   *
     '--delete-master-logs'

     On a master replication server, delete the binary logs by sending a
     'PURGE BINARY LOGS' statement to the
     server after performing the dump operation.  This option
     automatically enables '--master-data'.

   *
     '--dump-slave[=VALUE]'

     This option is similar to '--master-data' except that it is used to
     dump a replication slave server to produce a dump file that can be
     used to set up another server as a slave that has the same master
     as the dumped server.  It causes the dump output to include a
     'CHANGE MASTER TO' statement that indicates the
     binary log coordinates (file name and position) of the dumped
     slave's master.  The 'CHANGE MASTER TO'.
     statement reads the values of 'Relay_Master_Log_File' and
     'Exec_Master_Log_Pos' from the 'SHOW SLAVE STATUS'
     output and uses them for 'MASTER_LOG_FILE' and
     'MASTER_LOG_POS' respectively.  These are the master server
     coordinates from which the slave should start replicating.

     *Note*:

     Inconsistencies in the sequence of transactions from the relay log
     which have been executed can cause the wrong position to be used.
     See replication-features-transaction-inconsistencies for
     more information.

     '--dump-slave' causes the coordinates from the master to be used
     rather than those of the dumped server, as is done by the
     '--master-data' option.  In addition, specfiying this option causes
     the '--master-data' option to be overridden, if used, and
     effectively ignored.

     *Warning*:

     This option should not be used if the server where the dump is
     going to be applied uses 'gtid_mode=ON' and
     'MASTER_AUTOPOSITION=1'.

     The option value is handled the same way as for '--master-data'
     (setting no value or 1 causes a 'CHANGE MASTER TO' statement to be
     written to the dump, setting 2 causes the statement to be written
     but encased in SQL comments) and has the same effect as
     '--master-data' in terms of enabling or disabling other options and
     in how locking is handled.

     This option causes 'mysqldump' to stop the slave
     SQL thread before the dump and restart it again after.

     In conjunction with '--dump-slave', the '--apply-slave-statements'
     and '--include-master-host-port' options can also be used.

   *
     '--include-master-host-port'

     For the 'CHANGE MASTER TO' statement in a
     slave dump produced with the '--dump-slave' option, add
     'MASTER_HOST' and 'MASTER_PORT' options for the host name and
     TCP/IP port number of the slave's master.

   *
     '--master-data[=VALUE]'

     Use this option to dump a master replication server to produce a
     dump file that can be used to set up another server as a slave of
     the master.  It causes the dump output to include a 'CHANGE MASTER TO'
     statement that indicates the binary
     log coordinates (file name and position) of the dumped server.
     These are the master server coordinates from which the slave should
     start replicating after you load the dump file into the slave.

     If the option value is 2, the 'CHANGE MASTER TO'
     statement is written as an SQL comment, and thus
     is informative only; it has no effect when the dump file is
     reloaded.  If the option value is 1, the statement is not written
     as a comment and takes effect when the dump file is reloaded.  If
     no option value is specified, the default value is 1.

     This option requires the 'RELOAD' privilege and the binary log must
     be enabled.

     The '--master-data' option automatically turns off '--lock-tables'.
     It also turns on '--lock-all-tables', unless '--single-transaction'
     also is specified, in which case, a global read lock is acquired
     only for a short time at the beginning of the dump (see the
     description for '--single-transaction').  In all cases, any action
     on logs happens at the exact moment of the dump.

     It is also possible to set up a slave by dumping an existing slave
     of the master, using the '--dump-slave' option, which overrides
     '--master-data' and causes it to be ignored if both options are
     used.

   *
     '--set-gtid-purged=VALUE'

     This option enables control over global transaction ID (GTID)
     information written to the dump file, by indicating whether to add
     a 'SET @@global.gtid_purged' statement to the
     output.  This option may also cause a statement to be written to
     the output that disables binary logging while the dump file is
     being reloaded.

     The following table shows the permitted option values.  The default
     value is 'AUTO'.

     Value   Meaning

     'OFF'   Add no 'SET' statement to the output.

     'ON'    Add a 'SET' statement to the output.  An error occurs if GTIDs
             are not enabled on the server.

     'AUTO'  Add a 'SET' statement to the output if GTIDs are enabled on the
             server.

     A partial dump from a server that is using GTID-based replication
     requires the '--set-gtid-purged={ON|OFF}' option to be specified.
     Use 'ON' if the intention is to deploy a new replication slave
     using only some of the data from the dumped server.  Use 'OFF' if
     the intention is to repair a table by copying it within a topology.
     Use 'OFF' if the intention is to copy a table between replication
     topologies that are disjoint and will remain so.

     The '--set-gtid-purged' option has the following effect on binary
     logging when the dump file is reloaded:

        * '--set-gtid-purged=OFF': 'SET @@SESSION.SQL_LOG_BIN=0;' is not
          added to the output.

        * '--set-gtid-purged=ON': 'SET @@SESSION.SQL_LOG_BIN=0;' is
          added to the output.

        * '--set-gtid-purged=AUTO': 'SET @@SESSION.SQL_LOG_BIN=0;' is
          added to the output if GTIDs are enabled on the server you are
          backing up (that is, if 'AUTO' evaluates to 'ON').

     *Note*:

     It is not recommended to load a dump file when GTIDs are enabled on
     the server ('gtid_mode=ON'), if your dump file includes system
     tables.  'mysqldump' issues DML instructions for
     the system tables which use the non-transactional MyISAM storage
     engine, and this combination is not permitted when GTIDs are
     enabled.  Also be aware that loading a dump file from a server with
     GTIDs enabled, into another server with GTIDs enabled, causes
     different transaction identifiers to be generated.

*Format Options*

The following options specify how to represent the entire dump file or
certain kinds of data in the dump file.  They also control whether
certain optional information is written to the dump file.

   *
     '--compact'

     Produce more compact output.  This option enables the
     '--skip-add-drop-table', '--skip-add-locks', '--skip-comments',
     '--skip-disable-keys', and '--skip-set-charset' options.

   *
     '--compatible=NAME'

     Produce output that is more compatible with other database systems
     or with older MySQL servers.  The value of NAME can be 'ansi',
     'mysql323', 'mysql40', 'postgresql', 'oracle', 'mssql', 'db2',
     'maxdb', 'no_key_options', 'no_table_options', or
     'no_field_options'.  To use several values, separate them by
     commas.  These values have the same meaning as the corresponding
     options for setting the server SQL mode.  See sql-mode.

     This option does not guarantee compatibility with other servers.
     It only enables those SQL mode values that are currently available
     for making dump output more compatible.  For example,
     '--compatible=oracle' does not map data types to Oracle types or
     use Oracle comment syntax.

   *
     '--complete-insert', '-c'

     Use complete 'INSERT' statements that include column
     names.

   *
     '--create-options'

     Include all MySQL-specific table options in the 'CREATE TABLE'
     statements.

   *
     '--fields-terminated-by=...',

     '--fields-enclosed-by=...',

     '--fields-optionally-enclosed-by=...',

     '--fields-escaped-by=...'

     These options are used with the '--tab' option and have the same
     meaning as the corresponding 'FIELDS' clauses for 'LOAD DATA INFILE'.
     See load-data.

   *
     '--hex-blob'

     Dump binary columns using hexadecimal notation (for example,
     ''abc'' becomes '0x616263').  The affected data types are
     'BINARY', 'VARBINARY',
     the 'BLOB' types, and 'BIT'.

   *
     '--lines-terminated-by=...'

     This option is used with the '--tab' option and has the same
     meaning as the corresponding 'LINES' clause for 'LOAD DATA INFILE'.
     See load-data.

   *
     '--quote-names', '-Q'

     Quote identifiers (such as database, table, and column names)
     within '`' characters.  If the 'ANSI_QUOTES' SQL mode is enabled,
     identifiers are quoted within '"' characters.  This option is
     enabled by default.  It can be disabled with '--skip-quote-names',
     but this option should be given after any option such as
     '--compatible' that may enable '--quote-names'.

   *
     '--result-file=FILE_NAME', '-r FILE_NAME'

     Direct output to the named file.  The result file is created and
     its previous contents overwritten, even if an error occurs while
     generating the dump.

     This option should be used on Windows to prevent newline '\n'
     characters from being converted to '\r\n' carriage return/newline
     sequences.

   *
     '--tab=DIR_NAME', '-T DIR_NAME'

     Produce tab-separated text-format data files.  For each dumped
     table, see 'mysqldump' creates a 'TBL_NAME.sql' file
     that contains the 'CREATE TABLE' statement
     that creates the table, and the server writes a 'TBL_NAME.txt' file
     that contains its data.  The option value is the directory in which
     to write the files.

     *Note*:

     This option should be used only when 'mysqldump'.
     is run on the same machine as the 'mysqld' server.
     Because the server creates '*.txt' files in the directory that you
     specify, the directory must be writable by the server and the MySQL
     account that you use must have the 'FILE' privilege.  Because
     'mysqldump' creates '*.sql' in the same directory, it
     must be writable by your system login account.

     By default, the '.txt' data files are formatted using tab
     characters between column values and a newline at the end of each
     line.  The format can be specified explicitly using the
     '--fields-XXX' and '--lines-terminated-by' options.

     Column values are converted to the character set specified by the
     '--default-character-set' option.

   *
     '--tz-utc'

     This option enables 'TIMESTAMP' columns to be
     dumped and reloaded between servers in different time zones.
     'mysqldump' sets its connection time zone to UTC and
     adds 'SET TIME_ZONE='+00:00'' to the dump file.  Without this
     option, see 'TIMESTAMP' columns are dumped and
     reloaded in the time zones local to the source and destination
     servers, which can cause the values to change if the servers are in
     different time zones.  '--tz-utc' also protects against changes due
     to daylight saving time.  '--tz-utc' is enabled by default.  To
     disable it, use '--skip-tz-utc'.

   *
     '--xml', '-X'

     Write dump output as well-formed XML.

     *'NULL', ''NULL'', and Empty Values*: For a column named
     COLUMN_NAME, the 'NULL' value, an empty string, and the string
     value ''NULL'' are distinguished from one another in the output
     generated by this option as follows.

     Value:                               XML Representation:

     'NULL' (_unknown value_)
                                          '<field name="COLUMN_NAME"
                                          xsi:nil="true" />'

     '''' (_empty string_)
                                          '<field
                                          name="COLUMN_NAME"></field>'

     ''NULL'' (_string value_)
                                          '<field
                                          name="COLUMN_NAME">NULL</field>'

     The output from the 'mysql' client when run using the
     '--xml' option also follows the preceding rules.  (See
     mysql-command-options.)

     XML output from 'mysqldump' includes the XML
     namespace, as shown here:

          shell> mysqldump --xml -u root world City
          <?xml version="1.0"?>
          <mysqldump xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <database name="world">
          <table_structure name="City">
          <field Field="ID" Type="int(11)" Null="NO" Key="PRI" Extra="auto_increment" />
          <field Field="Name" Type="char(35)" Null="NO" Key="" Default="" Extra="" />
          <field Field="CountryCode" Type="char(3)" Null="NO" Key="" Default="" Extra="" />
          <field Field="District" Type="char(20)" Null="NO" Key="" Default="" Extra="" />
          <field Field="Population" Type="int(11)" Null="NO" Key="" Default="0" Extra="" />
          <key Table="City" Non_unique="0" Key_name="PRIMARY" Seq_in_index="1" Column_name="ID"
          Collation="A" Cardinality="4079" Null="" Index_type="BTREE" Comment="" />
          <options Name="City" Engine="MyISAM" Version="10" Row_format="Fixed" Rows="4079"
          Avg_row_length="67" Data_length="273293" Max_data_length="18858823439613951"
          Index_length="43008" Data_free="0" Auto_increment="4080"
          Create_time="2007-03-31 01:47:01" Update_time="2007-03-31 01:47:02"
          Collation="latin1_swedish_ci" Create_options="" Comment="" />
          </table_structure>
          <table_data name="City">
          <row>
          <field name="ID">1</field>
          <field name="Name">Kabul</field>
          <field name="CountryCode">AFG</field>
          <field name="District">Kabol</field>
          <field name="Population">1780000</field>
          </row>

          ...

          <row>
          <field name="ID">4079</field>
          <field name="Name">Rafah</field>
          <field name="CountryCode">PSE</field>
          <field name="District">Rafah</field>
          <field name="Population">92020</field>
          </row>
          </table_data>
          </database>
          </mysqldump>

*Filtering Options*

The following options control which kinds of schema objects are written
to the dump file: by category, such as triggers or events; by name, for
example, choosing which databases and tables to dump; or even filtering
rows from the table data using a 'WHERE' clause.

   *
     '--all-databases', '-A'

     Dump all tables in all databases.  This is the same as using the
     '--databases' option and naming all the databases on the command
     line.

   *
     '--databases', '-B'

     Dump several databases.  Normally, see 'mysqldump'.
     treats the first name argument on the command line as a database
     name and following names as table names.  With this option, it
     treats all name arguments as database names.  'CREATE DATABASE'
     and 'USE' statements are
     included in the output before each new database.

     This option may be used to dump the 'INFORMATION_SCHEMA' and
     'performace_schema' databases, which normally are not dumped even
     with the '--all-databases' option.  (Also use the
     '--skip-lock-tables' option.)

   *
     '--events', '-E'

     Include Event Scheduler events for the dumped databases in the
     output.  This option requires the 'EVENT' privileges for those
     databases.

     The output generated by using '--events' contains 'CREATE EVENT'
     statements to create the events.  However,
     these statements do not include attributes such as the event
     creation and modification timestamps, so when the events are
     reloaded, they are created with timestamps equal to the reload
     time.

     If you require events to be created with their original timestamp
     attributes, do not use '--events'.  Instead, dump and reload the
     contents of the 'mysql.event' table directly, using a MySQL account
     that has appropriate privileges for the 'mysql' database.

   *
     '--ignore-error=ERROR[,ERROR]...'

     Ignore the specified errors.  The option value is a comma-separated
     list of error numbers specifying the errors to ignore during
     'mysqldump' execution.  If the '--force' option is also
     given to ignore all errors, '--force' takes precedence.

     This option was added in MySQL 5.7.1.

   *
     '--ignore-table=DB_NAME.TBL_NAME'

     Do not dump the given table, which must be specified using both the
     database and table names.  To ignore multiple tables, use this
     option multiple times.  This option also can be used to ignore
     views.

   *
     '--no-data', '-d'

     Do not write any table row information (that is, do not dump table
     contents).  This is useful if you want to dump only the
     'CREATE TABLE' statement for the table (for example,
     to create an empty copy of the table by loading the dump file).

   *
     '--routines', '-R'

     Include stored routines (procedures and functions) for the dumped
     databases in the output.  This option requires the 'SELECT'
     privilege for the 'mysql.proc' table.

     The output generated by using '--routines' contains 'CREATE PROCEDURE'
     and 'CREATE FUNCTION'
     statements to create the routines.  However, these
     statements do not include attributes such as the routine creation
     and modification timestamps, so when the routines are reloaded,
     they are created with timestamps equal to the reload time.

     If you require routines to be created with their original timestamp
     attributes, do not use '--routines'.  Instead, dump and reload the
     contents of the 'mysql.proc' table directly, using a MySQL account
     that has appropriate privileges for the 'mysql' database.

   *
     '--tables'

     Override the '--databases' or '-B' option.  'mysqldump'
     regards all name arguments following the option as table
     names.

   *
     '--triggers'

     Include triggers for each dumped table in the output.  This option
     is enabled by default; disable it with '--skip-triggers'.

     To be able to dump a table's triggers, you must have the 'TRIGGER'
     privilege for the table.

     Before MySQL 5.7.2, a table cannot have multiple triggers that have
     the same combination of trigger event (see 'INSERT',
     'UPDATE', 'DELETE') and action time
     ('BEFORE', 'AFTER').  MySQL 5.7.2 lifts this limitation and
     multiple triggers are permitted.  See 'mysqldump'.
     dumps triggers in activation order so that when the dump file is
     reloaded, triggers are created in the same activation order.
     However, if a 'mysqldump' dump file contains
     multiple triggers for a table that have the same trigger event and
     action time, an error occurs for attempts to load the dump file
     into an older server that does not support multiple triggers.  (For
     a workaround, see downgrading-to-previous-series; you can
     convert triggers to be compatible with older servers.)

   *
     '--where='WHERE_CONDITION'', '-w 'WHERE_CONDITION''

     Dump only rows selected by the given 'WHERE' condition.  Quotes
     around the condition are mandatory if it contains spaces or other
     characters that are special to your command interpreter.

     Examples:

          --where="user='jimf'"
          -w"userid>1"
          -w"userid<1"

*Performance Options*

The following options are the most relevant for the performance
particularly of the restore operations.  For large data sets, restore
operation (processing the 'INSERT' statements in the dump file) is the
most time-consuming part.  When it is urgent to restore data quickly,
plan and test the performance of this stage in advance.  For restore
times measured in hours, you might prefer an alternative backup and
restore solution, such as MySQL Enterprise Backup
for 'InnoDB'-only and mixed-use databases.

Performance is also affected by the transactional options, primarily for
the dump operation.

   *
     '--disable-keys', '-K'

     For each table, surround the 'INSERT' statements
     with '/*!40000 ALTER TABLE TBL_NAME DISABLE KEYS */;' and '/*!40000
     ALTER TABLE TBL_NAME ENABLE KEYS */;' statements.  This makes
     loading the dump file faster because the indexes are created after
     all rows are inserted.  This option is effective only for nonunique
     indexes of 'MyISAM' tables.

   *
     '--extended-insert', '-e'

     Write 'INSERT' statements using multiple-row syntax
     that includes several 'VALUES' lists.  This results in a smaller
     dump file and speeds up inserts when the file is reloaded.

   *
     '--insert-ignore'

     Write 'INSERT IGNORE' statements rather than
     'INSERT' statements.

   *
     '--opt'

     This option, enabled by default, is shorthand for the combination
     of '--add-drop-table' '--add-locks' '--create-options'
     '--disable-keys' '--extended-insert' '--lock-tables' '--quick'
     '--set-charset'.  It gives a fast dump operation and produces a
     dump file that can be reloaded into a MySQL server quickly.

     Because the '--opt' option is enabled by default, you only specify
     its converse, the '--skip-opt' to turn off several default
     settings.  See the discussion of 'mysqldump' option groups for
     information about selectively enabling or disabling a subset of the
     options affected by '--opt'.

   *
     '--quick', '-q'

     This option is useful for dumping large tables.  It forces
     'mysqldump' to retrieve rows for a table from the
     server a row at a time rather than retrieving the entire row set
     and buffering it in memory before writing it out.

   *
     '--skip-opt'

     See the description for the '--opt' option.

*Transactional Options*

The following options trade off the performance of the dump operation,
against the reliability and consistency of the exported data.

   *
     '--add-locks'

     Surround each table dump with 'LOCK TABLES' and
     'UNLOCK TABLES' statements.  This results in
     faster inserts when the dump file is reloaded.  See
     insert-optimization.

   *
     '--flush-logs', '-F'

     Flush the MySQL server log files before starting the dump.  This
     option requires the 'RELOAD' privilege.  If you use this option in
     combination with the '--all-databases' option, the logs are flushed
     _for each database dumped_.  The exception is when using
     '--lock-all-tables', '--master-data', or '--single-transaction': In
     this case, the logs are flushed only once, corresponding to the
     moment that all tables are locked by 'FLUSH TABLES WITH READ LOCK'.
     If you want your dump and the log flush to happen at exactly the
     same moment, you should use '--flush-logs' together with
     '--lock-all-tables', '--master-data', or '--single-transaction'.

   *
     '--flush-privileges'

     Add a 'FLUSH PRIVILEGES' statement to the dump output after dumping
     the 'mysql' database.  This option should be used any time the dump
     contains the 'mysql' database and any other database that depends
     on the data in the 'mysql' database for proper restoration.

     *Note*:

     For upgrades to MySQL 5.7.2 or higher from older versions, do not
     use '--flush-privileges'.  For upgrade instructions in this case,
     see upgrading-from-previous-series.

   *
     '--lock-all-tables', '-x'

     Lock all tables across all databases.  This is achieved by
     acquiring a global read lock for the duration of the whole dump.
     This option automatically turns off '--single-transaction' and
     '--lock-tables'.

   *
     '--lock-tables', '-l'

     For each dumped database, lock all tables to be dumped before
     dumping them.  The tables are locked with 'READ LOCAL' to permit
     concurrent inserts in the case of 'MyISAM' tables.  For
     transactional tables such as 'InnoDB', '--single-transaction' is a
     much better option than '--lock-tables' because it does not need to
     lock the tables at all.

     Because '--lock-tables' locks tables for each database separately,
     this option does not guarantee that the tables in the dump file are
     logically consistent between databases.  Tables in different
     databases may be dumped in completely different states.

     Some options, such as '--opt', automatically enable
     '--lock-tables'.  If you want to override this, use
     '--skip-lock-tables' at the end of the option list.

   *
     '--no-autocommit'

     Enclose the 'INSERT' statements for each dumped
     table within 'SET autocommit = 0' and 'COMMIT'.
     statements.

   *
     '--order-by-primary'

     Dump each table's rows sorted by its primary key, or by its first
     unique index, if such an index exists.  This is useful when dumping
     a 'MyISAM' table to be loaded into an 'InnoDB' table, but makes the
     dump operation take considerably longer.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--single-transaction'

     This option sets the transaction isolation mode to 'REPEATABLE
     READ' and sends a 'START TRANSACTION'. SQL statement
     to the server before dumping data.  It is useful only with
     transactional tables such as 'InnoDB', because then it dumps the
     consistent state of the database at the time when 'START TRANSACTION'
     was issued without blocking any applications.

     When using this option, you should keep in mind that only 'InnoDB'
     tables are dumped in a consistent state.  For example, any 'MyISAM'
     or 'MEMORY' tables dumped while using this option may still change
     state.

     While a '--single-transaction' dump is in process, to ensure a
     valid dump file (correct table contents and binary log
     coordinates), no other connection should use the following
     statements: 'ALTER TABLE', 'CREATE TABLE',
     see 'DROP TABLE', 'RENAME TABLE',
     see 'TRUNCATE TABLE'.  A consistent
     read is not isolated from those statements, so use of them on a
     table to be dumped can cause the 'SELECT' that is
     performed by 'mysqldump' to retrieve the table
     contents to obtain incorrect contents or fail.

     The '--single-transaction' option and the '--lock-tables' option
     are mutually exclusive because 'LOCK TABLES'.
     causes any pending transactions to be committed implicitly.

     To dump large tables, combine the '--single-transaction' option
     with the '--quick' option.

*Option Groups*

   * The '--opt' option turns on several settings that work together to
     perform a fast dump operation.  All of these settings are on by
     default, because '--opt' is on by default.  Thus you rarely if ever
     specify '--opt'.  Instead, you can turn these settings off as a
     group by specifying '--skip-opt', the optionally re-enable certain
     settings by specifying the associated options later on the command
     line.

   * The '--compact' option turns off several settings that control
     whether optional statements and comments appear in the output.
     Again, you can follow this option with other options that re-enable
     certain settings, or turn all the settings on by using the
     '--skip-compact' form.

When you selectively enable or disable the effect of a group option,
order is important because options are processed first to last.  For
example, '--disable-keys' '--lock-tables' '--skip-opt' would not have
the intended effect; it is the same as '--skip-opt' by itself.

*Examples*

To make a backup of an entire database:

     shell> mysqldump DB_NAME > BACKUP-FILE.SQL

To load the dump file back into the server:

     shell> mysql DB_NAME < BACKUP-FILE.SQL

Another way to reload the dump file:

     shell> mysql -e "source /PATH-TO-BACKUP/BACKUP-FILE.SQL" DB_NAME

'mysqldump' is also very useful for populating
databases by copying data from one MySQL server to another:

     shell> mysqldump --opt DB_NAME | mysql --host=REMOTE_HOST -C DB_NAME

You can dump several databases with one command:

     shell> mysqldump --databases DB_NAME1 [DB_NAME2 ...] > my_databases.sql

To dump all databases, use the '--all-databases' option:

     shell> mysqldump --all-databases > all_databases.sql

For 'InnoDB' tables, see 'mysqldump' provides a way of
making an online backup:

     shell> mysqldump --all-databases --master-data --single-transaction > all_databases.sql

This backup acquires a global read lock on all tables (using 'FLUSH
TABLES WITH READ LOCK') at the beginning of the dump.  As soon as this
lock has been acquired, the binary log coordinates are read and the lock
is released.  If long updating statements are running when the
'FLUSH' statement is issued, the MySQL server may get stalled
until those statements finish.  After that, the dump becomes lock free
and does not disturb reads and writes on the tables.  If the update
statements that the MySQL server receives are short (in terms of
execution time), the initial lock period should not be noticeable, even
with many updates.

For point-in-time recovery (also known as 'roll-forward,' when you need
to restore an old backup and replay the changes that happened since that
backup), it is often useful to rotate the binary log (see
binary-log) or at least know the binary log coordinates to which the
dump corresponds:

     shell> mysqldump --all-databases --master-data=2 > all_databases.sql

Or:

     shell> mysqldump --all-databases --flush-logs --master-data=2
                   > all_databases.sql

The '--master-data' and '--single-transaction' options can be used
simultaneously, which provides a convenient way to make an online backup
suitable for use prior to point-in-time recovery if tables are stored
using the 'InnoDB' storage engine.

For more information on making backups, see backup-methods, and
backup-strategy-example.

   * To select the effect of '--opt' except for some features, use the
     '--skip' option for each feature.  To disable extended inserts and
     memory buffering, use '--opt' '--skip-extended-insert'
     '--skip-quick'.  (Actually, '--skip-extended-insert' '--skip-quick'
     is sufficient because '--opt' is on by default.)

   * To reverse '--opt' for all features except index disabling and
     table locking, use '--skip-opt' '--disable-keys' '--lock-tables'.

*Restrictions*

'mysqldump' does not dump the 'INFORMATION_SCHEMA',
'performance_schema', or (as of MySQL 5.7.8) 'sys' schema by default.
To dump any of these, name them explicitly on the command line.  You can
also name them with the '--databases' option.  For 'INFORMATION_SCHEMA'
and 'performance_schema', also use the '--skip-lock-tables' option.

'mysqldump' does not dump the NDB Cluster
'ndbinfo' information database.

It is not recommended to restore from a dump made using
'mysqldump' to a MySQL 5.6.9 or earlier server that has
GTIDs enabled.  See replication-gtids-restrictions.

'mysqldump' includes statements to recreate the
'general_log' and 'slow_query_log' tables for dumps of the 'mysql'
database.  Log table contents are not dumped.

If you encounter problems backing up views due to insufficient
privileges, see view-restrictions for a workaround.

4.5.5 'mysqlimport' -- A Data Import Program
--------------------------------------------

The 'mysqlimport' client provides a command-line
interface to the 'LOAD DATA INFILE'. SQL statement.
Most options to 'mysqlimport' correspond directly to
clauses of 'LOAD DATA INFILE' syntax.  See
load-data.

Invoke 'mysqlimport' like this:

     shell> mysqlimport [OPTIONS] DB_NAME TEXTFILE1 [TEXTFILE2 ...]

For each text file named on the command line, see 'mysqlimport'
strips any extension from the file name and uses the result
to determine the name of the table into which to import the file's
contents.  For example, files named 'patient.txt', 'patient.text', and
'patient' all would be imported into a table named 'patient'.

'mysqlimport' supports the following options, which
can be specified on the command line or in the '[mysqlimport]' and
'[client]' groups of an option file.  For information about option files
used by MySQL programs, see option-files.

*mysqlimport Options*

Format              Description                          IntroducedDeprecated

-bind-address       Use specified network interface to
                    connect to MySQL Server

-columns            This option takes a
                    comma-separated list of column
                    names as its value

-compress           Compress all information sent
                    between client and server

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-default-character-setSpecify default character set

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-delete             Empty the table before importing
                    the text file

-enable-cleartext-pluginEnable cleartext authentication  5.7.10
                    plugin

-fields-enclosed-by This option has the same meaning
                    as the corresponding clause for
                    LOAD DATA INFILE

-fields-escaped-by  This option has the same meaning
                    as the corresponding clause for
                    LOAD DATA INFILE

-fields-optionally-enclosed-byThis option has the same meaning
                    as the corresponding clause for
                    LOAD DATA INFILE

-fields-terminated-byThis option has the same meaning
                    as the corresponding clause for
                    LOAD DATA INFILE

-force              Continue even if an SQL error
                    occurs

-help               Display help message and exit

-host               Connect to MySQL server on given
                    host

-ignore             See the description for the
                    -replace option

-ignore-lines       Ignore the first N lines of the
                    data file

-lines-terminated-byThis option has the same meaning
                    as the corresponding clause for
                    LOAD DATA INFILE

-local              Read input files locally from the
                    client host

-lock-tables        Lock all tables for writing before
                    processing any text files

-login-path         Read login path options from
                    .mylogin.cnf

-low-priority       Use LOW_PRIORITY when loading the
                    table.

-no-defaults        Read no option files

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-protocol           Connection protocol to use

-replace            The -replace and -ignore options
                    control handling of input rows
                    that duplicate existing rows on
                    unique key values

-secure-auth        Do not send passwords to server in   5.7.4    5.7.5
                    old (pre-4.1) format

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-silent             Produce output only when errors
                    occur

-socket             For connections to localhost, the
                    Unix socket file to use

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-use-threads        Number of threads for parallel
                    file-loading

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version            Display version information and
                    exit

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--columns=COLUMN_LIST', '-c COLUMN_LIST'

     This option takes a comma-separated list of column names as its
     value.  The order of the column names indicates how to match data
     file columns with table columns.

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set.  See
     charset-configuration.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqlimport'
     normally reads the '[client]' and '[mysqlimport]'
     groups.  If the '--defaults-group-suffix=_other' option is given,
     see 'mysqlimport' also reads the '[client_other]'
     and '[mysqlimport_other]' groups.

   *
     '--delete', '-D'

     Empty the table before importing the text file.

   *
     '--enable-cleartext-plugin'

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     (See cleartext-pluggable-authentication.)

     This option was added in MySQL 5.7.10.

   *
     '--fields-terminated-by=...',

     '--fields-enclosed-by=...',

     '--fields-optionally-enclosed-by=...',

     '--fields-escaped-by=...'

     These options have the same meaning as the corresponding clauses
     for 'LOAD DATA INFILE'.  See load-data.

   *
     '--force', '-f'

     Ignore errors.  For example, if a table for a text file does not
     exist, continue processing any remaining files.  Without '--force',
     see 'mysqlimport' exits if a table does not exist.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Import data to the MySQL server on the given host.  The default
     host is 'localhost'.

   *
     '--ignore', '-i'

     See the description for the '--replace' option.

   *
     '--ignore-lines=N'

     Ignore the first N lines of the data file.

   *
     '--lines-terminated-by=...'

     This option has the same meaning as the corresponding clause for
     'LOAD DATA INFILE'.  For example, to import
     Windows files that have lines terminated with carriage
     return/linefeed pairs, use '--lines-terminated-by="\r\n"'.  (You
     might have to double the backslashes, depending on the escaping
     conventions of your command interpreter.)  See load-data.

   *
     '--local', '-L'

     By default, files are read by the server on the server host.  With
     this option, see 'mysqlimport' reads input files
     locally on the client host.  Enabling local data loading also
     requires that the server permits it; see load-data-local

   *
     '--lock-tables', '-l'

     Lock _all_ tables for writing before processing any text files.
     This ensures that all tables are synchronized on the server.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--low-priority'

     Use 'LOW_PRIORITY' when loading the table.  This affects only
     storage engines that use only table-level locking (such as
     'MyISAM', 'MEMORY', and 'MERGE').

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqlimport' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqlimport' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--replace', '-r'

     The '--replace' and '--ignore' options control handling of input
     rows that duplicate existing rows on unique key values.  If you
     specify '--replace', new rows replace existing rows that have the
     same unique key value.  If you specify '--ignore', input rows that
     duplicate an existing row on a unique key value are skipped.  If
     you do not specify either option, an error occurs when a duplicate
     key value is found, and the rest of the text file is ignored.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.  This option was added in MySQL 5.7.4.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--silent', '-s'

     Silent mode.  Produce output only when errors occur.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--use-threads=N'

     Load files in parallel using N threads.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.

   *
     '--version', '-V'

     Display version information and exit.

Here is a sample session that demonstrates use of 'mysqlimport'.:

     shell> mysql -e 'CREATE TABLE imptest(id INT, n VARCHAR(30))' test
     shell> ed
     a
     100     Max Sydow
     101     Count Dracula
     .
     w imptest.txt
     32
     q
     shell> od -c imptest.txt
     0000000   1   0   0  \t   M   a   x       S   y   d   o   w  \n   1   0
     0000020   1  \t   C   o   u   n   t       D   r   a   c   u   l   a  \n
     0000040
     shell> mysqlimport --local test imptest.txt
     test.imptest: Records: 2  Deleted: 0  Skipped: 0  Warnings: 0
     shell> mysql -e 'SELECT * FROM imptest' test
     +------+---------------+
     | id   | n             |
     +------+---------------+
     |  100 | Max Sydow     |
     |  101 | Count Dracula |
     +------+---------------+

4.5.6 'mysqlpump' -- A Database Backup Program
----------------------------------------------

   * mysqlpump-syntax

   * mysqlpump-option-summary

   * mysqlpump-options

   * mysqlpump-filtering

   * mysqlpump-parallelism

   * mysqlpump-restrictions

The 'mysqlpump' client utility performs logical
backups, producing a set of SQL statements that can be executed to
reproduce the original database object definitions and table data.  It
dumps one or more MySQL databases for backup or transfer to another SQL
server.

'mysqlpump' features include:

   * Parallel processing of databases, and of objects within databases,
     to speed up the dump process

   * Better control over which databases and database objects (tables,
     stored programs, user accounts) to dump

   * Dumping of user accounts as account-management statements (see
     'CREATE USER', 'GRANT') rather than as
     inserts into the 'mysql' system database

   * Capability of creating compressed output

   * Progress indicator (the values are estimates)

   * For dump file reloading, faster secondary index creation for
     'InnoDB' tables by adding indexes after rows are inserted

*Note*:

'mysqlpump' was added in MySQL 5.7.8.  It uses recent
MySQL features and thus assumes use with a server at least as recent as
'mysqlpump' itself.

'mysqlpump' requires at least the 'SELECT' privilege
for dumped tables, 'SHOW VIEW' for dumped views, 'TRIGGER' for dumped
triggers, and 'LOCK TABLES' if the '--single-transaction' option is not
used.  The 'SELECT' privilege on the 'mysql' system database is required
to dump user definitions.  Certain options might require other
privileges as noted in the option descriptions.

To reload a dump file, you must have the privileges required to execute
the statements that it contains, such as the appropriate 'CREATE'
privileges for objects created by those statements.

*Note*:

A dump made using PowerShell on Windows with output redirection creates
a file that has UTF-16 encoding:

     shell> mysqlpump [options] > dump.sql

However, UTF-16 is not permitted as a connection character set (see
charset-connection), so the dump file will not load correctly.
To work around this issue, use the '--result-file' option, which creates
the output in ASCII format:

     shell> mysqlpump [options] --result-file=dump.sql

*mysqlpump Invocation Syntax*

By default, see 'mysqlpump' dumps all databases (with
certain exceptions noted in mysqlpump-restrictions).  To specify
this behavior explicitly, use the '--all-databases' option:

     shell> mysqlpump --all-databases

To dump a single database, or certain tables within that database, name
the database on the command line, optionally followed by table names:

     shell> mysqlpump DB_NAME
     shell> mysqlpump DB_NAME TBL_NAME1 TBL_NAME2 ...

To treat all name arguments as database names, use the '--databases'
option:

     shell> mysqlpump --databases DB_NAME1 DB_NAME2 ...

By default, see 'mysqlpump' does not dump user account
definitions, even if you dump the 'mysql' system database that contains
the grant tables.  To dump grant table contents as logical definitions
in the form of 'CREATE USER' and 'GRANT'
statements, use the '--users' option and suppress all database
dumping:

     shell> mysqlpump --exclude-databases=% --users

In the preceding command, '%' is a wildcard that matches all database
names for the '--exclude-databases' option.

'mysqlpump' supports several options for including or
excluding databases, tables, stored programs, and user definitions.  See
mysqlpump-filtering.

To reload a dump file, execute the statements that it contains.  For
example, use the 'mysql' client:

     shell> mysqlpump [options] > dump.sql
     shell> mysql < dump.sql

The following discussion provides additional 'mysqlpump'
usage examples.

To see a list of the options 'mysqlpump' supports,
issue the command 'mysqlpump --help'.

*mysqlpump Option Summary*

'mysqlpump' supports the following options, which can
be specified on the command line or in the '[mysqlpump]' and '[client]'
groups of an option file.  For information about option files used by
MySQL programs, see option-files.

*mysqlpump Options*

Format                 Description                              Introduced

-add-drop-database     Add DROP DATABASE statement before
                       each CREATE DATABASE statement

-add-drop-table        Add DROP TABLE statement before each
                       CREATE TABLE statement

-add-drop-user         Add DROP USER statement before each
                       CREATE USER statement

-add-locks             Surround each table dump with LOCK
                       TABLES and UNLOCK TABLES statements

-all-databases         Dump all databases

-bind-address          Use specified network interface to
                       connect to MySQL Server

-character-sets-dir    Directory where character sets are
                       installed

-complete-insert       Use complete INSERT statements that
                       include column names

-compress              Compress all information sent between
                       client and server

-compress-output       Output compression algorithm

-databases             Interpret all name arguments as
                       database names

-debug                 Write debugging log

-debug-check           Print debugging information when
                       program exits

-debug-info            Print debugging information, memory,
                       and CPU statistics when program exits

-default-auth          Authentication plugin to use

-default-character-set Specify default character set

-default-parallelism   Default number of threads for parallel
                       processing

-defaults-extra-file   Read named option file in addition to
                       usual option files

-defaults-file         Read only named option file

-defaults-group-suffix Option group suffix value

-defer-table-indexes   For reloading, defer index creation
                       until after loading table rows

-events                Dump events from dumped databases

-exclude-databases     Databases to exclude from dump

-exclude-events        Events to exclude from dump

-exclude-routines      Routines to exclude from dump

-exclude-tables        Tables to exclude from dump

-exclude-triggers      Triggers to exclude from dump

-exclude-users         Users to exclude from dump

-extended-insert       Use multiple-row INSERT syntax

-help                  Display help message and exit

-hex-blob              Dump binary columns using hexadecimal
                       notation

-host                  Host to connect to (IP address or
                       hostname)

-include-databases     Databases to include in dump

-include-events        Events to include in dump

-include-routines      Routines to include in dump

-include-tables        Tables to include in dump

-include-triggers      Triggers to include in dump

-include-users         Users to include in dump

-insert-ignore         Write INSERT IGNORE rather than INSERT
                       statements

-log-error-file        Append warnings and errors to named
                       file

-login-path            Read login path options from
                       .mylogin.cnf

-max-allowed-packet    Maximum packet length to send to or
                       receive from server

-net-buffer-length     Buffer size for TCP/IP and socket
                       communication

-no-create-db          Do not write CREATE DATABASE
                       statements

-no-create-info        Do not write CREATE TABLE statements
                       that re-create each dumped table

-no-defaults           Read no option files

-parallel-schemas      Specify schema-processing parallelism

-password              Password to use when connecting to
                       server

-plugin-dir            Directory where plugins are installed

-port                  TCP/IP port number for connection

-print-defaults        Print default options

-protocol              Connection protocol to use

-replace               Write REPLACE statements rather than
                       INSERT statements

-result-file           Direct output to a given file

-routines              Dump stored routines (procedures and
                       functions) from dumped databases

-secure-auth           Do not send passwords to server in old
                       (pre-4.1) format

-set-charset           Add SET NAMES default_character_set to
                       output

-set-gtid-purged       Whether to add SET                       5.7.18
                       @@GLOBAL.GTID_PURGED to output

-single-transaction    Dump tables within single transaction

-skip-definer          Omit DEFINER and SQL SECURITY clauses
                       from view and stored program CREATE
                       statements

-skip-dump-rows        Do not dump table rows

-socket                For connections to localhost, the Unix
                       socket file to use

-ssl                   Enable encrypted connection

-ssl-ca                File that contains list of trusted SSL
                       Certificate Authorities

-ssl-capath            Directory that contains trusted SSL
                       Certificate Authority certificate
                       files

-ssl-cert              File that contains X509 certificate

-ssl-cipher            List of permitted ciphers for
                       connection encryption

-ssl-crl               File that contains certificate
                       revocation lists

-ssl-crlpath           Directory that contains certificate
                       revocation list files

-ssl-key               File that contains X509 key

-ssl-mode              Security state of connection to server   5.7.11

-ssl-verify-server-certVerify host name against server
                       certificate Common Name identity

-tls-version           Protocols permitted for encrypted        5.7.10
                       connections

-triggers              Dump triggers for each dumped table

-tz-utc                Add SET TIME_ZONE='+00:00' to dump
                       file

-user                  MySQL user name to use when connecting
                       to server

-users                 Dump user accounts

-version               Display version information and exit     5.7.9

-watch-progress        Display progress indicator

*mysqlpump Option Descriptions*

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--add-drop-database'

     Write a 'DROP DATABASE' statement before each
     'CREATE DATABASE' statement.

   *
     '--add-drop-table'

     Write a 'DROP TABLE' statement before each
     'CREATE TABLE' statement.

   *
     '--add-drop-user'

     Write a 'DROP USER' statement before each
     'CREATE USER' statement.

   *
     '--add-locks'

     Surround each table dump with 'LOCK TABLES' and
     'UNLOCK TABLES' statements.  This results in
     faster inserts when the dump file is reloaded.  See
     insert-optimization.

     This option does not work with parallelism because 'INSERT'
     statements from different tables can be interleaved and
     'UNLOCK TABLES' following the end of the
     inserts for one table could release locks on tables for which
     inserts remain.

     '--add-locks' and '--single-transaction' are mutually exclusive.

   *
     '--all-databases', '-A'

     Dump all databases (with certain exceptions noted in
     mysqlpump-restrictions).  This is the default behavior if no
     other is specified explicitly.

     '--all-databases' and '--databases' are mutually exclusive.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--character-sets-dir=PATH'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--complete-insert'

     Write complete 'INSERT' statements that include
     column names.

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--compress-output=ALGORITHM'

     By default, see 'mysqlpump' does not compress output.
     This option specifies output compression using the specified
     algorithm.  Permitted algorithms are 'LZ4' and 'ZLIB'.

     To uncompress compressed output, you must have an appropriate
     utility.  If the system commands 'lz4' and 'openssl zlib' are not
     available, as of MySQL 5.7.10, MySQL distributions include
     'lz4_decompress' and 'zlib_decompress'
     utilities that can be used to decompress
     'mysqlpump' output that was compressed using the
     '--compress-output=LZ4' and '--compress-output=ZLIB' options.  For
     more information, see lz4-decompress, and
     zlib-decompress.

     Alternatives include the 'lz4' and 'openssl' commands, if they are
     installed on your system.  For example, 'lz4' can uncompress 'LZ4'
     output:

          shell> lz4 -d INPUT_FILE OUTPUT_FILE

     'ZLIB' output can be uncompresed like this:

          shell> openssl zlib -d < INPUT_FILE > OUTPUT_FILE

   *
     '--databases', '-B'

     Normally, see 'mysqlpump' treats the first name
     argument on the command line as a database name and any following
     names as table names.  With this option, it treats all name
     arguments as database names.  'CREATE DATABASE'
     statements are included in the output before each
     new database.

     '--all-databases' and '--databases' are mutually exclusive.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:O,/tmp/mysqlpump.trace'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info', '-T'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set.  See
     charset-configuration.  If no character set is specified, see
     'mysqlpump' uses 'utf8'.

   *
     '--default-parallelism=N'

     The default number of threads for each parallel processing queue.
     The default is 2.

     The '--parallel-schemas' option also affects parallelism and can be
     used to override the default number of threads.  For more
     information, see mysqlpump-parallelism.

     With '--default-parallelism=0' and no '--parallel-schemas' options,
     see 'mysqlpump' runs as a single-threaded process and
     creates no queues.

     With parallelism enabled, it is possible for output from different
     databases to be interleaved.

     *Note*:

     Before MySQL 5.7.11, use of the '--single-transaction' option is
     mutually exclusive with parallelism.  To use
     '--single-transaction', disable parallelism by setting
     '--default-parallelism' to 0 and not using any instances of
     '--parallel-schemas':

          shell> mysqlpump --single-transaction --default-parallelism=0

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqlpump'
     normally reads the '[client]' and '[mysqlpump]' groups.
     If the '--defaults-group-suffix=_other' option is given, see
     'mysqlpump' also reads the '[client_other]' and
     '[mysqlpump_other]' groups.

   *
     '--defer-table-indexes'

     In the dump output, defer index creation for each table until after
     its rows have been loaded.  This works for all storage engines, but
     for 'InnoDB' applies only for secondary indexes.

     This option is enabled by default; use '--skip-defer-table-indexes'
     to disable it.

   *
     '--events'

     Include Event Scheduler events for the dumped databases in the
     output.  Event dumping requires the 'EVENT' privileges for those
     databases.

     The output generated by using '--events' contains 'CREATE EVENT'
     statements to create the events.  However,
     these statements do not include attributes such as the event
     creation and modification timestamps, so when the events are
     reloaded, they are created with timestamps equal to the reload
     time.

     If you require events to be created with their original timestamp
     attributes, do not use '--events'.  Instead, dump and reload the
     contents of the 'mysql.event' table directly, using a MySQL account
     that has appropriate privileges for the 'mysql' database.

     This option is enabled by default; use '--skip-events' to disable
     it.

   *
     '--exclude-databases=DB_LIST'

     Do not dump the databases in DB_LIST, which is a comma-separated
     list of one or more database names.  Multiple instances of this
     option are additive.  For more information, see
     mysqlpump-filtering.

   *
     '--exclude-events=EVENT_LIST'

     Do not dump the databases in EVENT_LIST, which is a comma-separated
     list of one or more event names.  Multiple instances of this option
     are additive.  For more information, see
     mysqlpump-filtering.

   *
     '--exclude-routines=ROUTINE_LIST'

     Do not dump the events in ROUTINE_LIST, which is a comma-separated
     list of one or more routine (stored procedure or function) names.
     Multiple instances of this option are additive.  For more
     information, see mysqlpump-filtering.

   *
     '--exclude-tables=TABLE_LIST'

     Do not dump the tables in TABLE_LIST, which is a comma-separated
     list of one or more table names.  Multiple instances of this option
     are additive.  For more information, see
     mysqlpump-filtering.

   *
     '--exclude-triggers=TRIGGER_LIST'

     Do not dump the triggers in TRIGGER_LIST, which is a
     comma-separated list of one or more trigger names.  Multiple
     instances of this option are additive.  For more information, see
     mysqlpump-filtering.

   *
     '--exclude-users=USER_LIST'

     Do not dump the user accounts in USER_LIST, which is a
     comma-separated list of one or more account names.  Multiple
     instances of this option are additive.  For more information, see
     mysqlpump-filtering.

   *
     '--extended-insert=N'

     Write 'INSERT' statements using multiple-row syntax
     that includes several 'VALUES' lists.  This results in a smaller
     dump file and speeds up inserts when the file is reloaded.

     The option value indicates the number of rows to include in each
     'INSERT' statement.  The default is 250.  A value of
     1 produces one 'INSERT' statement per table row.

   *
     '--hex-blob'

     Dump binary columns using hexadecimal notation (for example,
     ''abc'' becomes '0x616263').  The affected data types are
     'BINARY', 'VARBINARY',
     the 'BLOB' types, and 'BIT'.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Dump data from the MySQL server on the given host.

   *
     '--include-databases=DB_LIST'

     Dump the databases in DB_LIST, which is a comma-separated list of
     one or more database names.  The dump includes all objects in the
     named databases.  Multiple instances of this option are additive.
     For more information, see mysqlpump-filtering.

   *
     '--include-events=EVENT_LIST'

     Dump the events in EVENT_LIST, which is a comma-separated list of
     one or more event names.  Multiple instances of this option are
     additive.  For more information, see mysqlpump-filtering.

   *
     '--include-routines=ROUTINE_LIST'

     Dump the routines in ROUTINE_LIST, which is a comma-separated list
     of one or more routine (stored procedure or function) names.
     Multiple instances of this option are additive.  For more
     information, see mysqlpump-filtering.

   *
     '--include-tables=TABLE_LIST'

     Dump the tables in TABLE_LIST, which is a comma-separated list of
     one or more table names.  Multiple instances of this option are
     additive.  For more information, see mysqlpump-filtering.

   *
     '--include-triggers=TRIGGER_LIST'

     Dump the triggers in TRIGGER_LIST, which is a comma-separated list
     of one or more trigger names.  Multiple instances of this option
     are additive.  For more information, see
     mysqlpump-filtering.

   *
     '--include-users=USER_LIST'

     Dump the user accounts in USER_LIST, which is a comma-separated
     list of one or more user names.  Multiple instances of this option
     are additive.  For more information, see
     mysqlpump-filtering.

   *
     '--insert-ignore'

     Write 'INSERT IGNORE' statements rather than
     'INSERT' statements.

   *
     '--log-error-file=FILE_NAME'

     Log warnings and errors by appending them to the named file.  If
     this option is not given, see 'mysqlpump' writes
     warnings and errors to the standard error output.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--max-allowed-packet=N'

     The maximum size of the buffer for client/server communication.
     The default is 24MB, the maximum is 1GB.

   *
     '--net-buffer-length=N'

     The initial size of the buffer for client/server communication.
     When creating multiple-row 'INSERT' statements (as
     with the '--extended-insert' option), see 'mysqlpump'.
     creates rows up to N bytes long.  If you use this option to
     increase the value, ensure that the MySQL server
     'net_buffer_length' system variable has a value at least this
     large.

   *
     '--no-create-db'

     Suppress any 'CREATE DATABASE' statements
     that might otherwise be included in the output.

   *
     '--no-create-info', '-t'

     Do not write 'CREATE TABLE' statements that
     create each dumped table.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--parallel-schemas=[N:]DB_LIST'

     Create a queue for processing the databases in DB_LIST, which is a
     comma-separated list of one or more database names.  If N is given,
     the queue uses N threads.  If N is not given, the
     '--default-parallelism' option determines the number of queue
     threads.

     Multiple instances of this option create multiple queues.
     'mysqlpump' also creates a default queue to use for
     databases not named in any '--parallel-schemas' option, and for
     dumping user definitions if command options select them.  For more
     information, see mysqlpump-parallelism.

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqlpump' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqlpump' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--replace'

     Write 'REPLACE' statements rather than
     'INSERT' statements.

   *
     '--result-file=FILE_NAME'

     Direct output to the named file.  The result file is created and
     its previous contents overwritten, even if an error occurs while
     generating the dump.

     This option should be used on Windows to prevent newline '\n'
     characters from being converted to '\r\n' carriage return/newline
     sequences.

   *
     '--routines'

     Include stored routines (procedures and functions) for the dumped
     databases in the output.  This option requires the 'SELECT'
     privilege for the 'mysql.proc' table.

     The output generated by using '--routines' contains 'CREATE PROCEDURE'
     and 'CREATE FUNCTION'
     statements to create the routines.  However, these
     statements do not include attributes such as the routine creation
     and modification timestamps, so when the routines are reloaded,
     they are created with timestamps equal to the reload time.

     If you require routines to be created with their original timestamp
     attributes, do not use '--routines'.  Instead, dump and reload the
     contents of the 'mysql.proc' table directly, using a MySQL account
     that has appropriate privileges for the 'mysql' database.

     This option is enabled by default; use '--skip-routines' to disable
     it.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.

     This option is deprecated and will be removed in a future MySQL
     release.  It is always enabled and attempting to disable it
     ('--skip-secure-auth', '--secure-auth=0') produces an error.

   *
     '--set-charset'

     Write 'SET NAMES DEFAULT_CHARACTER_SET' to the
     output.

     This option is enabled by default.  To disable it and suppress the
     'SET NAMES' statement, use '--skip-set-charset'.

   *
     '--set-gtid-purged=VALUE'

     This option enables control over global transaction ID (GTID)
     information written to the dump file, by indicating whether to add
     a 'SET @@global.gtid_purged' statement to the
     output.  This option may also cause a statement to be written to
     the output that disables binary logging while the dump file is
     being reloaded.

     The following table shows the permitted option values.  The default
     value is 'AUTO'.

     Value   Meaning

     'OFF'   Add no 'SET' statement to the output.

     'ON'    Add a 'SET' statement to the output.  An error occurs if GTIDs
             are not enabled on the server.

     'AUTO'  Add a 'SET' statement to the output if GTIDs are enabled on the
             server.

     The '--set-gtid-purged' option has the following effect on binary
     logging when the dump file is reloaded:

        * '--set-gtid-purged=OFF': 'SET @@SESSION.SQL_LOG_BIN=0;' is not
          added to the output.

        * '--set-gtid-purged=ON': 'SET @@SESSION.SQL_LOG_BIN=0;' is
          added to the output.

        * '--set-gtid-purged=AUTO': 'SET @@SESSION.SQL_LOG_BIN=0;' is
          added to the output if GTIDs are enabled on the server you are
          backing up (that is, if 'AUTO' evaluates to 'ON').

     This option was added in MySQL 5.7.18.

   *
     '--single-transaction'

     This option sets the transaction isolation mode to 'REPEATABLE
     READ' and sends a 'START TRANSACTION'. SQL statement
     to the server before dumping data.  It is useful only with
     transactional tables such as 'InnoDB', because then it dumps the
     consistent state of the database at the time when 'START TRANSACTION'
     was issued without blocking any applications.

     When using this option, you should keep in mind that only 'InnoDB'
     tables are dumped in a consistent state.  For example, any 'MyISAM'
     or 'MEMORY' tables dumped while using this option may still change
     state.

     While a '--single-transaction' dump is in process, to ensure a
     valid dump file (correct table contents and binary log
     coordinates), no other connection should use the following
     statements: 'ALTER TABLE', 'CREATE TABLE',
     see 'DROP TABLE', 'RENAME TABLE',
     see 'TRUNCATE TABLE'.  A consistent
     read is not isolated from those statements, so use of them on a
     table to be dumped can cause the 'SELECT' that is
     performed by 'mysqlpump' to retrieve the table
     contents to obtain incorrect contents or fail.

     '--add-locks' and '--single-transaction' are mutually exclusive.

     *Note*:

     Before MySQL 5.7.11, use of the '--single-transaction' option is
     mutually exclusive with parallelism.  To use
     '--single-transaction', disable parallelism by setting
     '--default-parallelism' to 0 and not using any instances of
     '--parallel-schemas':

          shell> mysqlpump --single-transaction --default-parallelism=0

   *
     '--skip-definer'

     Omit 'DEFINER' and 'SQL SECURITY' clauses from the 'CREATE'
     statements for views and stored programs.  The dump file, when
     reloaded, creates objects that use the default 'DEFINER' and 'SQL
     SECURITY' values.  See stored-programs-security.

   *
     '--skip-dump-rows', '-d'

     Do not dump table rows.

   *
     '--socket={FILE_NAME|PIPE_NAME}', '-S {FILE_NAME|PIPE_NAME}'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--triggers'

     Include triggers for each dumped table in the output.

     This option is enabled by default; use '--skip-triggers' to disable
     it.

   *
     '--tz-utc'

     This option enables 'TIMESTAMP' columns to be
     dumped and reloaded between servers in different time zones.
     'mysqlpump' sets its connection time zone to UTC and
     adds 'SET TIME_ZONE='+00:00'' to the dump file.  Without this
     option, see 'TIMESTAMP' columns are dumped and
     reloaded in the time zones local to the source and destination
     servers, which can cause the values to change if the servers are in
     different time zones.  '--tz-utc' also protects against changes due
     to daylight saving time.

     This option is enabled by default; use '--skip-tz-utc' to disable
     it.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--users'

     Dump user accounts as logical definitions in the form of
     'CREATE USER' and 'GRANT' statements.

     User definitions are stored in the grant tables in the 'mysql'
     system database.  By default, see 'mysqlpump' does
     not include the grant tables in 'mysql' database dumps.  To dump
     the contents of the grant tables as logical definitions, use the
     '--users' option and suppress all database dumping:

          shell> mysqlpump --exclude-databases=% --users

   *
     '--version', '-V'

     Display version information and exit.

     This option was added in MySQL 5.7.9.

   *
     '--watch-progress'

     Periodically display a progress indicator that provides information
     about the completed and total number of tables, rows, and other
     objects.

     This option is enabled by default; use '--skip-watch-progress' to
     disable it.

*mysqlpump Object Selection*

'mysqlpump' has a set of inclusion and exclusion
options that enable filtering of several object types and provide
flexible control over which objects to dump:

   * '--include-databases' and '--exclude-databases' apply to databases
     and all objects within them.

   * '--include-tables' and '--exclude-tables' apply to tables.  These
     options also affect triggers associated with tables unless the
     trigger-specific options are given.

   * '--include-triggers' and '--exclude-triggers' apply to triggers.

   * '--include-routines' and '--exclude-routines' apply to stored
     procedures and functions.  If a routine option matches a stored
     procedure name, it also matches a stored function of the same name.

   * '--include-events' and '--exclude-events' apply to Event Scheduler
     events.

   * '--include-users' and '--exclude-users' apply to user accounts.

Any inclusion or exclusion option may be given multiple times.  The
effect is additive.  Order of these options does not matter.

The value of each inclusion and exclusion option is a comma-separated
list of names of the appropriate object type.  For example:

     --exclude-databases=test,world
     --include-tables=customer,invoice

Wildcard characters are permitted in the object names:

   * '%' matches any sequence of zero or more characters.

   * '_' matches any single character.

For example, '--include-tables=t%,__tmp' matches all table names that
begin with 't' and all five-character table names that end with 'tmp'.

For users, a name specified without a host part is interpreted with an
implied host of '%'.  For example, 'u1' and 'u1@%' are equivalent.  This
is the same equivalence that applies in MySQL generally (see
account-names).

Inclusion and exclusion options interact as follows:

   * By default, with no inclusion or exclusion options, see
     'mysqlpump' dumps all databases (with certain
     exceptions noted in mysqlpump-restrictions).

   * If inclusion options are given in the absence of exclusion options,
     only the objects named as included are dumped.

   * If exclusion options are given in the absence of inclusion options,
     all objects are dumped except those named as excluded.

   * If inclusion and exclusion options are given, all objects named as
     excluded and not named as included are not dumped.  All other
     objects are dumped.

If multiple databases are being dumped, it is possible to name tables,
triggers, and routines in a specific database by qualifying the object
names with the database name.  The following command dumps databases
'db1' and 'db2', but excludes tables 'db1.t1' and 'db2.t2':

     shell> mysqlpump --include-databases=db1,db2 --exclude-tables=db1.t1,db2.t2

The following options provide alternative ways to specify which
databases to dump:

   * The '--all-databases' option dumps all databases (with certain
     exceptions noted in mysqlpump-restrictions).  It is
     equivalent to specifying no object options at all (the default
     'mysqlpump' action is to dump everything).

     '--include-databases=%' is similar to '--all-databases', but
     selects all databases for dumping, even those that are exceptions
     for '--all-databases'.

   * The '--databases' option causes 'mysqlpump' to
     treat all name arguments as names of databases to dump.  It is
     equivalent to an '--include-databases' option that names the same
     databases.

*mysqlpump Parallel Processing*

'mysqlpump' can use parallelism to achieve concurrent
processing.  You can select concurrency between databases (to dump
multiple databases simultaneously) and within databases (to dump
multiple objects from a given database simultaneously).

By default, see 'mysqlpump' sets up one queue with two
threads.  You can create additional queues and control the number of
threads assigned to each one, including the default queue:

   * '--default-parallelism=N' specifies the default number of threads
     used for each queue.  In the absence of this option, N is 2.

     The default queue always uses the default number of threads.
     Additional queues use the default number of threads unless you
     specify otherwise.

   * '--parallel-schemas=[N:]DB_LIST' sets up a processing queue for
     dumping the databases named in DB_LIST and optionally specifies how
     many threads the queue uses.  DB_LIST is a comma-separated list of
     database names.  If the option argument begins with 'N:', the queue
     uses N threads.  Otherwise, the '--default-parallelism' option
     determines the number of queue threads.

     Multiple instances of the '--parallel-schemas' option create
     multiple queues.

     Names in the database list are permitted to contain the same '%'
     and '_' wildcard characters supported for filtering options (see
     mysqlpump-filtering).

'mysqlpump' uses the default queue for processing any
databases not named explicitly with a '--parallel-schemas' option, and
for dumping user definitions if command options select them.

In general, with multiple queues, see 'mysqlpump' uses
parallelism between the sets of databases processed by the queues, to
dump multiple databases simultaneously.  For a queue that uses multiple
threads, see 'mysqlpump' uses parallelism within
databases, to dump multiple objects from a given database
simultaneously.  Exceptions can occur; for example, see 'mysqlpump'
may block queues while it obtains from the server lists of
objects in databases.

With parallelism enabled, it is possible for output from different
databases to be interleaved.  For example, see 'INSERT'.
statements from multiple tables dumped in parallel can be interleaved;
the statements are not written in any particular order.  This does not
affect reloading because output statements qualify object names with
database names or are preceded by 'USE' statements as
required.

The granularity for parallelism is a single database object.  For
example, a single table cannot be dumped in parallel using multiple
threads.

Examples:

     shell> mysqlpump --parallel-schemas=db1,db2 --parallel-schemas=db3

'mysqlpump' sets up a queue to process 'db1' and
'db2', another queue to process 'db3', and a default queue to process
all other databases.  All queues use two threads.

     shell> mysqlpump --parallel-schemas=db1,db2 --parallel-schemas=db3
              --default-parallelism=4

This is the same as the previous example except that all queues use four
threads.

     shell> mysqlpump --parallel-schemas=5:db1,db2 --parallel-schemas=3:db3

The queue for 'db1' and 'db2' uses five threads, the queue for 'db3'
uses three threads, and the default queue uses the default of two
threads.

As a special case, with '--default-parallelism=0' and no
'--parallel-schemas' options, see 'mysqlpump' runs as a
single-threaded process and creates no queues.

*Note*:

Before MySQL 5.7.11, use of the '--single-transaction' option is
mutually exclusive with parallelism.  To use '--single-transaction',
disable parallelism by setting '--default-parallelism' to 0 and not
using any instances of '--parallel-schemas':

     shell> mysqlpump --single-transaction --default-parallelism=0

*mysqlpump Restrictions*

'mysqlpump' does not dump the 'INFORMATION_SCHEMA',
'performance_schema', 'ndbinfo', or 'sys' schema by default.  To dump
any of these, name them explicitly on the command line.  You can also
name them with the '--databases' or '--include-databases' option.

'mysqlpump' dumps user accounts in logical form using
'CREATE USER' and 'GRANT' statements
(for example, when you use the '--include-users' or '--users' option).
For this reason, dumps of the 'mysql' system database do not by default
include the grant tables that contain user definitions: 'user', 'db',
'tables_priv', 'columns_priv', 'procs_priv', or 'proxies_priv'.  To dump
any of the grant tables, name the 'mysql' database followed by the table
names:

     shell> mysqlpump mysql user db ...

4.5.7 'mysqlsh' -- The MySQL Shell
----------------------------------

MySQL Shell is an advanced command-line client and code editor for
MySQL. In addition to SQL, MySQL Shell also offers scripting
capabilities for JavaScript and Python.  For information about using
MySQL Shell, see mysql-shell.  When MySQL Shell is connected to
the MySQL Server through the X Protocol, the X DevAPI can be used to
work with both relational and document data, see document-store.
MySQL Shell includes the AdminAPI that enables you to work with InnoDB
cluster, see mysql-innodb-cluster-userguide.

'mysqlsh' supports the following command-line options.

*mysqlsh Options*

Format                    Description

-auth-method              Authentication method to use

-classic                  Deprecated in version 8.0.3.  Create a
                          ClassicSession

-database                 The schema to use (alias for -schema)

-dba                      Enable X Protocol on connection with server

-dbpassword               Password to use when connecting to server

-dbuser                   MySQL user name to use when connecting to
                          server

-execute                  Execute the command and quit

-file                     File to process in Batch mode

-force                    Continue in SQL and Batch modes even if
                          errors occur

-help                     Display help message and exit

-host                     Connect to MySQL server on given host

-interactive              Emulate Interactive mode in Batch mode

-javascript, -js          Start in JavaScript mode

-json                     Print output in JSON format

-log-level                Specify logging level

-no-wizard, -nw           Disable the connection wizard

-node                     Deprecated in version 8.0.3.  Create a
                          NodeSession

-password                 Password to use when connecting to server
                          (alias for -dbpassword)

-passwords-from-stdin     Read the password from stdin

-port                     TCP/IP port number for connection

-py, -python              Start in Python mode

-recreate-schema          Drop and recreate schema

-schema                   The schema to use

-show-warnings            Show warnings after each statement if there
                          are any (in SQL mode)

-socket                   For connections to localhost, the Unix
                          socket file to use, or pipe name on Windows
                          (ClassicSessions only)

-sql                      Start in SQL mode

-sqlc                     Start in SQL mode using a ClassicSession

-sqln                     Deprecated in version 8.0.3.  Start in SQL
                          mode using a NodeSession

-ssl                      Enable an SSL connection.  Deprecated in
                          version 1.0.10; use -ssl-mode instead.

-ssl-ca                   File that contains list of trusted SSL
                          Certificate Authorities

-ssl-capath               Directory that contains trusted SSL
                          Certificate Authority certificate files

-ssl-cert                 File that contains X509 certificate

-ssl-cipher               Name of the SSL cipher to use

-ssl-crl                  File that contains certificate revocation
                          lists

-ssl-crlpath              Directory that contains certificate
                          revocation list files

-ssl-key                  File that contains X509 key

-ssl-mode                 Security state of connection to server

-table                    Display output in tabular format

-tls-version              Protocols permitted for encrypted
                          connections

-uri                      Session information in URI format

-user                     MySQL user name to use when connecting to
                          server (alias for -dbuser)

-version                  Display version information and exit

-vertical                 Display all SQL results vertically

   *
     '--help'

     Display a help message and exit.

   *
     '--auth-method=METHOD'

     Authentication method to use.

   *
     '--classic'

     Creates a Classic session, to connect using MySQL Protocol.

   *
     '--database=NAME'

     The default schema to use.  This is an alias for '--schema'.

   *
     '--dba=enableXProtocol'

     Enable X Protocol on connection with server.  Requires Classic
     session.

   *
     '--dbpassword[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--dbpassword' or '-p' option on the command line, see
     'mysql' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--dbuser=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--execute=COMMAND', '-e COMMAND'

     Execute the command using the currently active language and quit.

   *
     '--file=FILE_NAME'

     Specify file to process in Batch mode.

   *
     '--force'

     Continue processing in SQL and Batch modes even if errors occur.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--interactive[=full]'

     Emulate Interactive mode in Batch mode.

   *
     '--js'

     Start in JavaScript mode.

   *
     '--json[={pretty|raw}]'

     Print output in JSON format.  With an option value of 'pretty',
     output is pretty-printed.  With no option value or a value of
     'raw', output is in raw JSON format.

   *
     '--log-level=N'

     Specify the logging level.  The value can be either an integer in
     the range from 1 to 8, or one of 'none', 'internal', 'error',
     'warning', 'info', 'debug', 'debug2', or 'debug3'.  See
     mysql-shell-application-log.

   *
     '--node'

     Creates a Node session connected using X Protocol to a single
     server.

   *
     '--no-wizard'

     Disables the connection wizard which provides help when creating
     connections.

   *
     '--passwords-from-stdin'

     Read the password from stdin.

   *
     '--password[=PASSWORD]'

     The password to use when connecting to the server.  This is an
     alias for '--dbpassword'.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.  The default is
     port 33060.

   *
     '--py'

     Start in Python mode.

   *
     '--recreate-schema'

     Drop and recreate schema.

   *
     '--schema=NAME', '-D NAME'

     The default schema to use.

   *
     '--show-warnings'

     Cause warnings to be shown after each statement if there are any.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.  This option applies to
     Classic sessions only.

   *
     '--sql'

     Start in SQL mode.

   *
     '--sqlc'

     Start in SQL mode using a ClassicSession.

   *
     '--sqln'

     Start in SQL mode using a NodeSession.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  The 'mysqlsh'. SSL options function
     in the same way as the SSL options for MySQL Server, see
     encrypted-connection-options for more information.

     'mysqlsh' accepts these SSL options: '--ssl-mode',
     '--ssl-ca', '--ssl-capath', '--ssl-cert', '--ssl-cipher',
     '--ssl-crl', '--ssl-crlpath', '--ssl-key'.  '--tls-version'.

   *
     '--table'

     Display output in table format in Batch mode.

   *
     '--uri=STR'

     Create a connection upon startup, specifying the connection options
     in a URI string format, see
     mysql-shell-connection-using-uri.

   *
     '--user=USER_NAME'

     The MySQL user name to use when connecting to the server.  This is
     an alias for '--dbuser'.

   *
     '--version', '-V'

     Display version information and exit.

   *
     '--vertical', '-E'

     Display results of SQL queries vertically.

4.5.8 'mysqlshow' -- Display Database, Table, and Column Information
--------------------------------------------------------------------

The 'mysqlshow' client can be used to quickly see
which databases exist, their tables, or a table's columns or indexes.

'mysqlshow' provides a command-line interface to
several SQL 'SHOW' statements.  See show.  The same
information can be obtained by using those statements directly.  For
example, you can issue them from the 'mysql' client
program.

Invoke 'mysqlshow' like this:

     shell> mysqlshow [OPTIONS] [DB_NAME [TBL_NAME [COL_NAME]]]

   * If no database is given, a list of database names is shown.

   * If no table is given, all matching tables in the database are
     shown.

   * If no column is given, all matching columns and column types in the
     table are shown.

The output displays only the names of those databases, tables, or
columns for which you have some privileges.

If the last argument contains shell or SQL wildcard characters ('*',
'?', '%', or '_'), only those names that are matched by the wildcard are
shown.  If a database name contains any underscores, those should be
escaped with a backslash (some Unix shells require two) to get a list of
the proper tables or columns.  '*' and '?' characters are converted into
SQL '%' and '_' wildcard characters.  This might cause some confusion
when you try to display the columns for a table with a '_' in the name,
because in this case, see 'mysqlshow' shows you only the
table names that match the pattern.  This is easily fixed by adding an
extra '%' last on the command line as a separate argument.

'mysqlshow' supports the following options, which can
be specified on the command line or in the '[mysqlshow]' and '[client]'
groups of an option file.  For information about option files used by
MySQL programs, see option-files.

*mysqlshow Options*

Format              Description                          IntroducedDeprecated

-bind-address       Use specified network interface to
                    connect to MySQL Server

-compress           Compress all information sent
                    between client and server

-count              Show the number of rows per table

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-default-character-setSpecify default character set

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-enable-cleartext-pluginEnable cleartext authentication  5.7.10
                    plugin

-help               Display help message and exit

-host               Connect to MySQL server on given
                    host

-keys               Show table indexes

-login-path         Read login path options from
                    .mylogin.cnf

-no-defaults        Read no option files

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-protocol           Connection protocol to use

-secure-auth        Do not send passwords to server in   5.7.4    5.7.5
                    old (pre-4.1) format

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-show-table-type    Show a column indicating the table
                    type

-socket             For connections to localhost, the
                    Unix socket file to use

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-status             Display extra information about
                    each table

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version            Display version information and
                    exit

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--count'

     Show the number of rows per table.  This can be slow for
     non-'MyISAM' tables.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-character-set=CHARSET_NAME'

     Use CHARSET_NAME as the default character set.  See
     charset-configuration.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqlshow'
     normally reads the '[client]' and '[mysqlshow]' groups.
     If the '--defaults-group-suffix=_other' option is given, see
     'mysqlshow' also reads the '[client_other]' and
     '[mysqlshow_other]' groups.

   *
     '--enable-cleartext-plugin'

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     (See cleartext-pluggable-authentication.)

     This option was added in MySQL 5.7.10.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--keys', '-k'

     Show table indexes.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqlshow' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqlshow' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.  This option was added in MySQL 5.7.4.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--show-table-type', '-t'

     Show a column indicating the table type, as in 'SHOW FULL TABLES'.
     The type is 'BASE TABLE' or 'VIEW'.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--status', '-i'

     Display extra information about each table.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.
     This option can be used multiple times to increase the amount of
     information.

   *
     '--version', '-V'

     Display version information and exit.

4.5.9 'mysqlslap' -- Load Emulation Client
------------------------------------------

'mysqlslap' is a diagnostic program designed to
emulate client load for a MySQL server and to report the timing of each
stage.  It works as if multiple clients are accessing the server.

Invoke 'mysqlslap' like this:

     shell> mysqlslap [OPTIONS]

Some options such as '--create' or '--query' enable you to specify a
string containing an SQL statement or a file containing statements.  If
you specify a file, by default it must contain one statement per line.
(That is, the implicit statement delimiter is the newline character.)
Use the '--delimiter' option to specify a different delimiter, which
enables you to specify statements that span multiple lines or place
multiple statements on a single line.  You cannot include comments in a
file; see 'mysqlslap' does not understand them.

'mysqlslap' runs in three stages:

  1. Create schema, table, and optionally any stored programs or data to
     use for the test.  This stage uses a single client connection.

  2. Run the load test.  This stage can use many client connections.

  3. Clean up (disconnect, drop table if specified).  This stage uses a
     single client connection.

Examples:

Supply your own create and query SQL statements, with 50 clients
querying and 200 selects for each (enter the command on a single line):

     mysqlslap --delimiter=";"
       --create="CREATE TABLE a (b int);INSERT INTO a VALUES (23)"
       --query="SELECT * FROM a" --concurrency=50 --iterations=200

Let 'mysqlslap' build the query SQL statement with a
table of two 'INT' columns and three
'VARCHAR' columns.  Use five clients querying 20 times each.  Do
not create the table or insert the data (that is, use the previous
test's schema and data):

     mysqlslap --concurrency=5 --iterations=20
       --number-int-cols=2 --number-char-cols=3
       --auto-generate-sql

Tell the program to load the create, insert, and query SQL statements
from the specified files, where the 'create.sql' file has multiple table
creation statements delimited by '';'' and multiple insert statements
delimited by '';''.  The '--query' file will have multiple queries
delimited by '';''.  Run all the load statements, then run all the
queries in the query file with five clients (five times each):

     mysqlslap --concurrency=5
       --iterations=5 --query=query.sql --create=create.sql
       --delimiter=";"

'mysqlslap' supports the following options, which can
be specified on the command line or in the '[mysqlslap]' and '[client]'
groups of an option file.  For information about option files used by
MySQL programs, see option-files.

*mysqlslap Options*

Format              Description                          IntroducedDeprecated

-auto-generate-sql  Generate SQL statements
                    automatically when they are not
                    supplied in files or using command
                    options

-auto-generate-sql-add-autoincrementAdd AUTO_INCREMENT column to
                    automatically generated tables

-auto-generate-sql-execute-numberSpecify how many queries to
                    generate automatically

-auto-generate-sql-guid-primaryAdd a GUID-based primary key to
                    automatically generated tables

-auto-generate-sql-load-typeSpecify the test load type

-auto-generate-sql-secondary-indexesSpecify how many secondary indexes
                    to add to automatically generated
                    tables

-auto-generate-sql-unique-query-numberHow many different queries to
                    generate for automatic tests.

-auto-generate-sql-unique-write-numberHow many different queries to
                    generate for
                    -auto-generate-sql-write-number

-auto-generate-sql-write-numberHow many row inserts to perform on
                    each thread

-commit             How many statements to execute
                    before committing.

-compress           Compress all information sent
                    between client and server

-concurrency        Number of clients to simulate when
                    issuing the SELECT statement

-create             File or string containing the
                    statement to use for creating the
                    table

-create-schema      Schema in which to run the tests

-csv                Generate output in comma-separated
                    values format

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-delimiter          Delimiter to use in SQL statements

-detach             Detach (close and reopen) each
                    connection after each N statements

-enable-cleartext-pluginEnable cleartext authentication
                    plugin

-engine             Storage engine to use for creating
                    the table

-help               Display help message and exit

-host               Connect to MySQL server on given
                    host

-iterations         Number of times to run the tests

-login-path         Read login path options from
                    .mylogin.cnf

-no-defaults        Read no option files

-no-drop            Do not drop any schema created
                    during the test run

-number-char-cols   Number of VARCHAR columns to use
                    if -auto-generate-sql is specified

-number-int-cols    Number of INT columns to use if
                    -auto-generate-sql is specified

-number-of-queries  Limit each client to approximately
                    this number of queries

-only-print         Do not connect to databases.
                    mysqlslap only prints what it
                    would have done

-password           Password to use when connecting to
                    server

-pipe               On Windows, connect to server
                    using named pipe

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-post-query         File or string containing the
                    statement to execute after the
                    tests have completed

-post-system        String to execute using system()
                    after the tests have completed

-pre-query          File or string containing the
                    statement to execute before
                    running the tests

-pre-system         String to execute using system()
                    before running the tests

-print-defaults     Print default options

-protocol           Connection protocol to use

-query              File or string containing the
                    SELECT statement to use for
                    retrieving data

-secure-auth        Do not send passwords to server in   5.7.4    5.7.5
                    old (pre-4.1) format

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-silent             Silent mode

-socket             For connections to localhost, the
                    Unix socket file to use

-sql-mode           Set SQL mode for client session      5.7.5

-ssl                Enable encrypted connection

-ssl-ca             File that contains list of trusted
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509
                    certificate

-ssl-cipher         List of permitted ciphers for
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server
                    certificate Common Name identity

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-user               MySQL user name to use when
                    connecting to server

-verbose            Verbose mode

-version            Display version information and
                    exit

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--auto-generate-sql', '-a'

     Generate SQL statements automatically when they are not supplied in
     files or using command options.

   *
     '--auto-generate-sql-add-autoincrement'

     Add an 'AUTO_INCREMENT' column to automatically generated tables.

   *
     '--auto-generate-sql-execute-number=N'

     Specify how many queries to generate automatically.

   *
     '--auto-generate-sql-guid-primary'

     Add a GUID-based primary key to automatically generated tables.

   *
     '--auto-generate-sql-load-type=TYPE'

     Specify the test load type.  The permissible values are 'read'
     (scan tables), 'write' (insert into tables), 'key' (read primary
     keys), 'update' (update primary keys), or 'mixed' (half inserts,
     half scanning selects).  The default is 'mixed'.

   *
     '--auto-generate-sql-secondary-indexes=N'

     Specify how many secondary indexes to add to automatically
     generated tables.  By default, none are added.

   *
     '--auto-generate-sql-unique-query-number=N'

     How many different queries to generate for automatic tests.  For
     example, if you run a 'key' test that performs 1000 selects, you
     can use this option with a value of 1000 to run 1000 unique
     queries, or with a value of 50 to perform 50 different selects.
     The default is 10.

   *
     '--auto-generate-sql-unique-write-number=N'

     How many different queries to generate for
     '--auto-generate-sql-write-number'.  The default is 10.

   *
     '--auto-generate-sql-write-number=N'

     How many row inserts to perform.  The default is 100.

   *
     '--commit=N'

     How many statements to execute before committing.  The default is 0
     (no commits are done).

   *
     '--compress', '-C'

     Compress all information sent between the client and the server if
     both support compression.

   *
     '--concurrency=N', '-c N'

     The number of parallel clients to simulate.

   *
     '--create=VALUE'

     The file or string containing the statement to use for creating the
     table.

   *
     '--create-schema=VALUE'

     The schema in which to run the tests.

     *Note*:

     If the '--auto-generate-sql' option is also given, see
     'mysqlslap' drops the schema at the end of the test
     run.  To avoid this, use the '--no-drop' option as well.

   *
     '--csv[=FILE_NAME]'

     Generate output in comma-separated values format.  The output goes
     to the named file, or to the standard output if no file is given.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o,/tmp/mysqlslap.trace'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info', '-T'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqlslap'
     normally reads the '[client]' and '[mysqlslap]' groups.
     If the '--defaults-group-suffix=_other' option is given, see
     'mysqlslap' also reads the '[client_other]' and
     '[mysqlslap_other]' groups.

   *
     '--delimiter=STR', '-F STR'

     The delimiter to use in SQL statements supplied in files or using
     command options.

   *
     '--detach=N'

     Detach (close and reopen) each connection after each N statements.
     The default is 0 (connections are not detached).

   *
     '--enable-cleartext-plugin'

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     (See cleartext-pluggable-authentication.)

   *
     '--engine=ENGINE_NAME', '-e ENGINE_NAME'

     The storage engine to use for creating tables.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Connect to the MySQL server on the given host.

   *
     '--iterations=N', '-i N'

     The number of times to run the tests.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--no-drop'

     Prevent 'mysqlslap' from dropping any schema it
     creates during the test run.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--number-char-cols=N', '-x N'

     The number of 'VARCHAR' columns to use if
     '--auto-generate-sql' is specified.

   *
     '--number-int-cols=N', '-y N'

     The number of 'INT' columns to use if
     '--auto-generate-sql' is specified.

   *
     '--number-of-queries=N'

     Limit each client to approximately this many queries.  Query
     counting takes into account the statement delimiter.  For example,
     if you invoke 'mysqlslap' as follows, the ';'
     delimiter is recognized so that each instance of the query string
     counts as two queries.  As a result, 5 rows (not 10) are inserted.

          shell> mysqlslap --delimiter=";" --number-of-queries=10
                   --query="use test;insert into t values(null)"

   *
     '--only-print'

     Do not connect to databases.  'mysqlslap' only
     prints what it would have done.

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqlslap' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--pipe', '-W'

     On Windows, connect to the server using a named pipe.  This option
     applies only if the server supports named-pipe connections.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqlslap' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for the connection.

   *
     '--post-query=VALUE'

     The file or string containing the statement to execute after the
     tests have completed.  This execution is not counted for timing
     purposes.

   *
     '--post-system=STR'

     The string to execute using 'system()' after the tests have
     completed.  This execution is not counted for timing purposes.

   *
     '--pre-query=VALUE'

     The file or string containing the statement to execute before
     running the tests.  This execution is not counted for timing
     purposes.

   *
     '--pre-system=STR'

     The string to execute using 'system()' before running the tests.
     This execution is not counted for timing purposes.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--query=VALUE', '-q VALUE'

     The file or string containing the 'SELECT' statement
     to use for retrieving data.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.  This option was added in MySQL 5.7.4.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  This option applies only if
     the server supports shared-memory connections.

   *
     '--silent', '-s'

     Silent mode.  No output.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--sql-mode=MODE'

     Set the SQL mode for the client session.  This option was added in
     MySQL 5.7.5.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to the server.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.
     This option can be used multiple times to increase the amount of
     information.

   *
     '--version', '-V'

     Display version information and exit.

4.6 MySQL Administrative and Utility Programs
=============================================

This section describes administrative programs and programs that perform
miscellaneous utility operations.

4.6.1 'innochecksum' -- Offline InnoDB File Checksum Utility
------------------------------------------------------------

'innochecksum' prints checksums for 'InnoDB' files.
This tool reads an 'InnoDB' tablespace file, calculates the checksum for
each page, compares the calculated checksum to the stored checksum, and
reports mismatches, which indicate damaged pages.  It was originally
developed to speed up verifying the integrity of tablespace files after
power outages but can also be used after file copies.  Because checksum
mismatches cause 'InnoDB' to deliberately shut down a running server, it
may be preferable to use this tool rather than waiting for an
in-production server to encounter the damaged pages.  As of MySQL 5.7.2,
see 'innochecksum' supports files greater than 2GB in
size.  Previously, see 'innochecksum' only supported
files up to 2GB in size.

As of MySQL 5.7.2, see 'innochecksum' supports
tablespaces that contain compressed pages.

'innochecksum' cannot be used on tablespace files
that the server already has open.  For such files, you should use
'CHECK TABLE' to check tables within the tablespace.
Attempting to run 'innochecksum' on a tablespace
that the server already has open will result in an ''Unable to lock
file'' error.

If checksum mismatches are found, you would normally restore the
tablespace from backup or start the server and attempt to use
'mysqldump' to make a backup of the tables within the
tablespace.

Invoke 'innochecksum' like this:

     shell> innochecksum [OPTIONS] FILE_NAME

*innochecksum Options*

'innochecksum' supports the following options.  For
options that refer to page numbers, the numbers are zero-based.

   *
     '--help', '-?'

     Displays command line help.  Example usage:

          shell> innochecksum --help

   *
     '--info', '-I'

     Synonym for '--help'.  Displays command line help.  Example usage:

          shell> innochecksum --info

   *
     '--version', '-V'

     Displays version information.  Example usage:

          shell> innochecksum --version

   *
     '--verbose', '-v'

     Verbose mode; prints a progress indicator to the log file every
     five seconds.  In order for the progress indicator to be printed,
     the log file must be specified using the '--log option'.  To turn
     on 'verbose' mode, run:

          shell> innochecksum --verbose

     To turn off verbose mode, run:

          shell> innochecksum --verbose=FALSE

     The '--verbose' option and '--log' option can be specified at the
     same time.  For example:

          shell> innochecksum --verbose --log=/var/lib/mysql/test/logtest.txt

     To locate the progress indicator information in the log file, you
     can perform the following search:

          shell> cat ./logtest.txt | grep -i "okay"

     The progress indicator information in the log file appears similar
     to the following:

          page 1663 okay: 2.863% done
          page 8447 okay: 14.537% done
          page 13695 okay: 23.568% done
          page 18815 okay: 32.379% done
          page 23039 okay: 39.648% done
          page 28351 okay: 48.789% done
          page 33023 okay: 56.828% done
          page 37951 okay: 65.308% done
          page 44095 okay: 75.881% done
          page 49407 okay: 85.022% done
          page 54463 okay: 93.722% done
          ...

   *
     '--count', '-c'

     Print a count of the number of pages in the file and exit.  Example
     usage:

          shell> innochecksum --count ../data/test/tab1.ibd

   *
     '--start-page=NUM', '-s NUM'

     Start at this page number.  Example usage:

          shell> innochecksum --start-page=600 ../data/test/tab1.ibd

     or:

          shell> innochecksum -s 600 ../data/test/tab1.ibd

   *
     '--end-page=NUM', '-e NUM'

     End at this page number.  Example usage:

          shell> innochecksum --end-page=700 ../data/test/tab1.ibd

     or:

          shell> innochecksum --p 700 ../data/test/tab1.ibd

   *
     '--page=NUM', '-p NUM'

     Check only this page number.  Example usage:

          shell> innochecksum --page=701 ../data/test/tab1.ibd

   *
     '--strict-check', '-C'

     Specify a strict checksum algorithm.  Options include 'innodb',
     'crc32', and 'none'.

     In this example, the 'innodb' checksum algorithm is specified:

          shell> innochecksum --strict-check=innodb ../data/test/tab1.ibd

     In this example, the 'crc32' checksum algorithm is specified:

          shell> innochecksum -C crc32 ../data/test/tab1.ibd

     The following conditions apply:

        * If you do not specify the '--strict-check' option, see
          'innochecksum' validates against 'innodb',
          'crc32' and 'none'.

        * If you specify the 'none' option, only checksums generated by
          'none' are allowed.

        * If you specify the 'innodb' option, only checksums generated
          by 'innodb' are allowed.

        * If you specify the 'crc32' option, only checksums generated by
          'crc32' are allowed.

   *
     '--no-check', '-n'

     Ignore the checksum verification when rewriting a checksum.  This
     option may only be used with the 'innochecksum'.
     '--write' option.  If the '--write' option is not
     specified, see 'innochecksum' will terminate.

     In this example, an 'innodb' checksum is rewritten to replace an
     invalid checksum:

          shell> innochecksum --no-check --write innodb ../data/test/tab1.ibd

   *
     '--allow-mismatches', '-a'

     The maximum number of checksum mismatches allowed before
     'innochecksum' terminates.  The default setting is
     0.  If '--allow-mismatches='N, where 'N>=0', N mismatches are
     permitted and 'innochecksum' terminates at
     'N+1'.  When '--allow-mismatches' is set to 0, see
     'innochecksum' terminates on the first checksum
     mismatch.

     In this example, an existing 'innodb' checksum is rewritten to set
     '--allow-mismatches' to 1.

          shell> innochecksum --allow-mismatches=1 --write innodb ../data/test/tab1.ibd

     With '--allow-mismatches' set to 1, if there is a mismatch at page
     600 and another at page 700 on a file with 1000 pages, the checksum
     is updated for pages 0-599 and 601-699.  Because
     '--allow-mismatches' is set to 1, the checksum tolerates the first
     mismatch and terminates on the second mismatch, leaving page 600
     and pages 700-999 unchanged.

   *
     '--write=NAME', '-w NUM'

     Rewrite a checksum.  When rewriting an invalid checksum, the
     '--no-check' option must be used together with the '--write'
     option.  The '--no-check' option tells 'innochecksum'
     to ignore verification of the invalid checksum.  You
     do not have to specify the '--no-check' option if the current
     checksum is valid.

     An algorithm must be specified when using the '--write' option.
     Possible values for the '--write' option are:

        * 'innodb': A checksum calculated in software, using the
          original algorithm from 'InnoDB'.

        * 'crc32': A checksum calculated using the 'crc32' algorithm,
          possibly done with a hardware assist.

        * 'none': A constant number.

     The '--write' option rewrites entire pages to disk.  If the new
     checksum is identical to the existing checksum, the new checksum is
     not written to disk in order to minimize I/O.

     'innochecksum' obtains an exclusive lock when
     the '--write' option is used.

     In this example, a 'crc32' checksum is written for 'tab1.ibd':

          shell> innochecksum -w crc32 ../data/test/tab1.ibd

     In this example, a 'crc32' checksum is rewritten to replace an
     invalid 'crc32' checksum:

          shell> innochecksum --no-check --write crc32 ../data/test/tab1.ibd

   *
     '--page-type-summary', '-S'

     Display a count of each page type in a tablespace.  Example usage:

          shell> innochecksum --page-type-summary ../data/test/tab1.ibd

     Sample output for '--page-type-summary':

          File::../data/test/tab1.ibd
          ================PAGE TYPE SUMMARY==============
          #PAGE_COUNT PAGE_TYPE
          ===============================================
                 2        Index page
                 0        Undo log page
                 1        Inode page
                 0        Insert buffer free list page
                 2        Freshly allocated page
                 1        Insert buffer bitmap
                 0        System page
                 0        Transaction system page
                 1        File Space Header
                 0        Extent descriptor page
                 0        BLOB page
                 0        Compressed BLOB page
                 0        Other type of page
          ===============================================
          Additional information:
          Undo page type: 0 insert, 0 update, 0 other
          Undo page state: 0 active, 0 cached, 0 to_free, 0 to_purge, 0 prepared, 0 other

   *
     '--page-type-dump', '-D'

     Dump the page type information for each page in a tablespace to
     'stderr' or 'stdout'.  Example usage:

          shell> innochecksum --page-type-dump=/tmp/a.txt ../data/test/tab1.ibd

   *
     '--log', '-l'

     Log output for the 'innochecksum' tool.  A log
     file name must be provided.  Log output contains checksum values
     for each tablespace page.  For uncompressed tables, LSN values are
     also provided.  The '--log' replaces the '--debug' option, which
     was available in earlier releases.  Example usage:

          shell> innochecksum --log=/tmp/log.txt ../data/test/tab1.ibd

     or:

          shell> innochecksum -l /tmp/log.txt ../data/test/tab1.ibd

   *
     '-' option.

     Specify the '-' option to read from standard input.  If the '-'
     option is missing when 'read from standard in' is expected, see
     'innochecksum' will output 'innochecksum'
     usage information indicating that the '-' option was
     omitted.  Example usages:

          shell> cat t1.ibd | innochecksum -

     In this example, see 'innochecksum' writes the
     'crc32' checksum algorithm to 'a.ibd' without changing the original
     't1.ibd' file.

          shell> cat t1.ibd | innochecksum --write=crc32 - > a.ibd

*Running innochecksum on Multiple User-defined Tablespace Files*

The following examples demonstrate how to run 'innochecksum'
on multiple user-defined tablespace files ('.ibd' files).

Run 'innochecksum' for all tablespace ('.ibd')
files in the 'test' database:

     shell> innochecksum ./data/test/*.ibd

Run 'innochecksum' for all tablespace files ('.ibd'
files) that have a file name starting with 't':

     shell> innochecksum ./data/test/t*.ibd

Run 'innochecksum' for all tablespace files ('.ibd'
files) in the 'data' directory:

     shell> innochecksum ./data/*/*.ibd

*Note*:

Running 'innochecksum' on multiple user-defined
tablespace files is not supported on Windows operating systems, as
Windows shells such as 'cmd.exe' do not support glob pattern expansion.
On Windows systems, see 'innochecksum' must be run
separately for each user-defined tablespace file.  For example:

     cmd> innochecksum.exe t1.ibd
     cmd> innochecksum.exe t2.ibd
     cmd> innochecksum.exe t3.ibd

*Running innochecksum on Multiple System Tablespace Files*

By default, there is only one 'InnoDB' system tablespace file
('ibdata1') but multiple files for the system tablespace can be defined
using the 'innodb_data_file_path' option.  In the following example,
three files for the system tablespace are defined using the
'innodb_data_file_path' option: 'ibdata1', 'ibdata2', and 'ibdata3'.

     shell> ./bin/mysqld --no-defaults --innodb-data-file-path="ibdata1:10M;ibdata2:10M;ibdata3:10M:autoextend"

The three files ('ibdata1', 'ibdata2', and 'ibdata3') form one logical
system tablespace.  To run 'innochecksum' on
multiple files that form one logical system tablespace, see
'innochecksum' requires the '-' option to read tablespace
files in from standard input, which is equivalent to concatenating
multiple files to create one single file.  For the example provided
above, the following 'innochecksum' command would
be used:

     shell> cat ibdata* | innochecksum -

Refer to the 'innochecksum' options information for
more information about the '-' option.

*Note*:

Running 'innochecksum' on multiple files in the
same tablespace is not supported on Windows operating systems, as
Windows shells such as 'cmd.exe' do not support glob pattern expansion.
On Windows systems, see 'innochecksum' must be run
separately for each system tablespace file.  For example:

     cmd> innochecksum.exe ibdata1
     cmd> innochecksum.exe ibdata2
     cmd> innochecksum.exe ibdata3

4.6.2 'myisam_ftdump' -- Display Full-Text Index information
------------------------------------------------------------

'myisam_ftdump' displays information about
'FULLTEXT' indexes in 'MyISAM' tables.  It reads the 'MyISAM' index file
directly, so it must be run on the server host where the table is
located.  Before using 'myisam_ftdump', be sure to
issue a 'FLUSH TABLES' statement first if the server is running.

'myisam_ftdump' scans and dumps the entire index,
which is not particularly fast.  On the other hand, the distribution of
words changes infrequently, so it need not be run often.

Invoke 'myisam_ftdump' like this:

     shell> myisam_ftdump [OPTIONS] TBL_NAME INDEX_NUM

The TBL_NAME argument should be the name of a 'MyISAM' table.  You can
also specify a table by naming its index file (the file with the '.MYI'
suffix).  If you do not invoke 'myisam_ftdump' in
the directory where the table files are located, the table or index file
name must be preceded by the path name to the table's database
directory.  Index numbers begin with 0.

Example: Suppose that the 'test' database contains a table named
'mytexttable' that has the following definition:

     CREATE TABLE mytexttable
     (
       id   INT NOT NULL,
       txt  TEXT NOT NULL,
       PRIMARY KEY (id),
       FULLTEXT (txt)
     ) ENGINE=MyISAM;

The index on 'id' is index 0 and the 'FULLTEXT' index on 'txt' is index
1.  If your working directory is the 'test' database directory, invoke
'myisam_ftdump' as follows:

     shell> myisam_ftdump mytexttable 1

If the path name to the 'test' database directory is
'/usr/local/mysql/data/test', you can also specify the table name
argument using that path name.  This is useful if you do not invoke
'myisam_ftdump' in the database directory:

     shell> myisam_ftdump /usr/local/mysql/data/test/mytexttable 1

You can use 'myisam_ftdump' to generate a list of
index entries in order of frequency of occurrence like this on Unix-like
systems:

     shell> myisam_ftdump -c mytexttable 1 | sort -r

On Windows, use:

     shell> myisam_ftdump -c mytexttable 1 | sort /R

'myisam_ftdump' supports the following options:

   *
     '--help', '-h' '-?'

     Display a help message and exit.

   *
     '--count', '-c'

     Calculate per-word statistics (counts and global weights).

   *
     '--dump', '-d'

     Dump the index, including data offsets and word weights.

   *
     '--length', '-l'

     Report the length distribution.

   *
     '--stats', '-s'

     Report global index statistics.  This is the default operation if
     no other operation is specified.

   *
     '--verbose', '-v'

     Verbose mode.  Print more output about what the program does.

4.6.3 'myisamchk' -- MyISAM Table-Maintenance Utility
-----------------------------------------------------

The 'myisamchk' utility gets information about your
database tables or checks, repairs, or optimizes them.
'myisamchk' works with 'MyISAM' tables (tables that have
'.MYD' and '.MYI' files for storing data and indexes).

You can also use the 'CHECK TABLE' and 'REPAIR TABLE'
statements to check and repair 'MyISAM' tables.
See check-table, and repair-table.

The use of 'myisamchk' with partitioned tables is not
supported.

*Caution*:

It is best to make a backup of a table before performing a table repair
operation; under some circumstances the operation might cause data loss.
Possible causes include but are not limited to file system errors.

Invoke 'myisamchk' like this:

     shell> myisamchk [OPTIONS] TBL_NAME ...

The OPTIONS specify what you want 'myisamchk' to do.
They are described in the following sections.  You can also get a list
of options by invoking 'myisamchk --help'.

With no options, see 'myisamchk' simply checks your table
as the default operation.  To get more information or to tell
'myisamchk' to take corrective action, specify options as
described in the following discussion.

TBL_NAME is the database table you want to check or repair.  If you run
'myisamchk' somewhere other than in the database
directory, you must specify the path to the database directory, because
'myisamchk' has no idea where the database is located.
In fact, see 'myisamchk' does not actually care whether
the files you are working on are located in a database directory.  You
can copy the files that correspond to a database table into some other
location and perform recovery operations on them there.

You can name several tables on the 'myisamchk' command
line if you wish.  You can also specify a table by naming its index file
(the file with the '.MYI' suffix).  This enables you to specify all
tables in a directory by using the pattern '*.MYI'.  For example, if you
are in a database directory, you can check all the 'MyISAM' tables in
that directory like this:

     shell> myisamchk *.MYI

If you are not in the database directory, you can check all the tables
there by specifying the path to the directory:

     shell> myisamchk /PATH/TO/DATABASE_DIR/*.MYI

You can even check all tables in all databases by specifying a wildcard
with the path to the MySQL data directory:

     shell> myisamchk /PATH/TO/DATADIR/*/*.MYI

The recommended way to quickly check all 'MyISAM' tables is:

     shell> myisamchk --silent --fast /PATH/TO/DATADIR/*/*.MYI

If you want to check all 'MyISAM' tables and repair any that are
corrupted, you can use the following command:

     shell> myisamchk --silent --force --fast --update-state \
               --key_buffer_size=64M --myisam_sort_buffer_size=64M \
               --read_buffer_size=1M --write_buffer_size=1M \
               /PATH/TO/DATADIR/*/*.MYI

This command assumes that you have more than 64MB free.  For more
information about memory allocation with 'myisamchk',
see myisamchk-memory.

For additional information about using 'myisamchk', see
myisam-table-maintenance.

*Important*:

_You must ensure that no other program is using the tables while you are
running 'myisamchk'._.  The most effective means of
doing so is to shut down the MySQL server while running
'myisamchk', or to lock all tables that 'myisamchk'
is being used on.

Otherwise, when you run 'myisamchk', it may display the
following error message:

     warning: clients are using or haven't closed the table properly

This means that you are trying to check a table that has been updated by
another program (such as the 'mysqld' server) that hasn't
yet closed the file or that has died without closing the file properly,
which can sometimes lead to the corruption of one or more 'MyISAM'
tables.

If 'mysqld' is running, you must force it to flush any
table modifications that are still buffered in memory by using 'FLUSH
TABLES'.  You should then ensure that no one is using the tables while
you are running 'myisamchk'.

However, the easiest way to avoid this problem is to use 'CHECK TABLE'
instead of 'myisamchk' to check
tables.  See check-table.

'myisamchk' supports the following options, which can
be specified on the command line or in the '[myisamchk]' group of an
option file.  For information about option files used by MySQL programs,
see option-files.

*myisamchk Options*

Format                    Description

-analyze                  Analyze the distribution of key values

-backup                   Make a backup of the .MYD file as
                          file_name-time.BAK

-block-search             Find the record that a block at the given
                          offset belongs to

-check                    Check the table for errors

-check-only-changed       Check only tables that have changed since
                          the last check

-correct-checksum         Correct the checksum information for the
                          table

-data-file-length         Maximum length of the data file (when
                          re-creating data file when it is full)

-debug                    Write debugging log

-decode_bits              Decode_bits

-defaults-extra-file      Read named option file in addition to usual
                          option files

-defaults-file            Read only named option file

-defaults-group-suffix    Option group suffix value

-description              Print some descriptive information about the
                          table

-extend-check             Do very thorough table check or repair that
                          tries to recover every possible row from the
                          data file

-fast                     Check only tables that haven't been closed
                          properly

-force                    Do a repair operation automatically if
                          myisamchk finds any errors in the table

-force                    Overwrite old temporary files.  For use with
                          the -r or -o option

-ft_max_word_len          Maximum word length for FULLTEXT indexes

-ft_min_word_len          Minimum word length for FULLTEXT indexes

-ft_stopword_file         Use stopwords from this file instead of
                          built-in list

-HELP                     Display help message and exit

-help                     Display help message and exit

-information              Print informational statistics about the
                          table that is checked

-key_buffer_size          Size of buffer used for index blocks for
                          MyISAM tables

-keys-used                A bit-value that indicates which indexes to
                          update

-max-record-length        Skip rows larger than the given length if
                          myisamchk cannot allocate memory to hold
                          them

-medium-check             Do a check that is faster than an
                          -extend-check operation

-myisam_block_size        Block size to be used for MyISAM index pages

-myisam_sort_buffer_size  The buffer that is allocated when sorting
                          the index when doing a REPAIR or when
                          creating indexes with CREATE INDEX or ALTER
                          TABLE

-no-defaults              Read no option files

-parallel-recover         Uses the same technique as -r and -n, but
                          creates all the keys in parallel, using
                          different threads (beta)

-print-defaults           Print default options

-quick                    Achieve a faster repair by not modifying the
                          data file.

-read_buffer_size         Each thread that does a sequential scan
                          allocates a buffer of this size for each
                          table it scans

-read-only                Do not mark the table as checked

-recover                  Do a repair that can fix almost any problem
                          except unique keys that aren't unique

-safe-recover             Do a repair using an old recovery method
                          that reads through all rows in order and
                          updates all index trees based on the rows
                          found

-set-auto-increment       Force AUTO_INCREMENT numbering for new
                          records to start at the given value

-set-collation            Specify the collation to use for sorting
                          table indexes

-silent                   Silent mode

-sort_buffer_size         The buffer that is allocated when sorting
                          the index when doing a REPAIR or when
                          creating indexes with CREATE INDEX or ALTER
                          TABLE

-sort-index               Sort the index tree blocks in high-low order

-sort_key_blocks          sort_key_blocks

-sort-records             Sort records according to a particular index

-sort-recover             Force myisamchk to use sorting to resolve
                          the keys even if the temporary files would
                          be very large

-stats_method             Specifies how MyISAM index statistics
                          collection code should treat NULLs

-tmpdir                   Directory to be used for storing temporary
                          files

-unpack                   Unpack a table that was packed with
                          myisampack

-update-state             Store information in the .MYI file to
                          indicate when the table was checked and
                          whether the table crashed

-verbose                  Verbose mode

-version                  Display version information and exit

-write_buffer_size        Write buffer size

4.6.3.1 myisamchk General Options
.................................

The options described in this section can be used for any type of table
maintenance operation performed by 'myisamchk'.  The
sections following this one describe options that pertain only to
specific operations, such as table checking or repairing.

   *
     '--help', '-?'

     Display a help message and exit.  Options are grouped by type of
     operation.

   *
     '--HELP', '-H'

     Display a help message and exit.  Options are presented in a single
     list.

   *
     '--debug=DEBUG_OPTIONS', '-# DEBUG_OPTIONS'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o,/tmp/myisamchk.trace'.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'myisamchk'
     normally reads the '[myisamchk]' group.  If the
     '--defaults-group-suffix=_other' option is given, see
     'myisamchk' also reads the '[myisamchk_other]' group.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--silent', '-s'

     Silent mode.  Write output only when errors occur.  You can use
     '-s' twice ('-ss') to make 'myisamchk' very
     silent.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.
     This can be used with '-d' and '-e'.  Use '-v' multiple times
     ('-vv', '-vvv') for even more output.

   *
     '--version', '-V'

     Display version information and exit.

   *
     '--wait', '-w'

     Instead of terminating with an error if the table is locked, wait
     until the table is unlocked before continuing.  If you are running
     'mysqld' with external locking disabled, the table
     can be locked only by another 'myisamchk'.
     command.

You can also set the following variables by using '--VAR_NAME=VALUE'
syntax:

Variable                  Default Value

'decode_bits'             9

'ft_max_word_len'         version-dependent

'ft_min_word_len'         4

'ft_stopword_file'        built-in list

'key_buffer_size'         523264

'myisam_block_size'       1024

'myisam_sort_key_blocks'  16

'read_buffer_size'        262136

'sort_buffer_size'        2097144

'sort_key_blocks'         16

'stats_method'            nulls_unequal

'write_buffer_size'       262136

The possible 'myisamchk' variables and their default
values can be examined with 'myisamchk --help'.:

'myisam_sort_buffer_size' is used when the keys are repaired by sorting
keys, which is the normal case when you use '--recover'.
'sort_buffer_size' is a deprecated synonym for
'myisam_sort_buffer_size'.

'key_buffer_size' is used when you are checking the table with
'--extend-check' or when the keys are repaired by inserting keys row by
row into the table (like when doing normal inserts).  Repairing through
the key buffer is used in the following cases:

   * You use '--safe-recover'.

   * The temporary files needed to sort the keys would be more than
     twice as big as when creating the key file directly.  This is often
     the case when you have large key values for 'CHAR',
     'VARCHAR', or 'TEXT' columns, because the
     sort operation needs to store the complete key values as it
     proceeds.  If you have lots of temporary space and you can force
     'myisamchk' to repair by sorting, you can use the
     '--sort-recover' option.

Repairing through the key buffer takes much less disk space than using
sorting, but is also much slower.

If you want a faster repair, set the 'key_buffer_size' and
'myisam_sort_buffer_size' variables to about 25% of your available
memory.  You can set both variables to large values, because only one of
them is used at a time.

'myisam_block_size' is the size used for index blocks.

'stats_method' influences how 'NULL' values are treated for index
statistics collection when the '--analyze' option is given.  It acts
like the 'myisam_stats_method' system variable.  For more information,
see the description of 'myisam_stats_method' in
server-system-variables, and index-statistics.

'ft_min_word_len' and 'ft_max_word_len' indicate the minimum and maximum
word length for 'FULLTEXT' indexes on 'MyISAM' tables.
'ft_stopword_file' names the stopword file.  These need to be set under
the following circumstances.

If you use 'myisamchk' to perform an operation that
modifies table indexes (such as repair or analyze), the 'FULLTEXT'
indexes are rebuilt using the default full-text parameter values for
minimum and maximum word length and the stopword file unless you specify
otherwise.  This can result in queries failing.

The problem occurs because these parameters are known only by the
server.  They are not stored in 'MyISAM' index files.  To avoid the
problem if you have modified the minimum or maximum word length or the
stopword file in the server, specify the same 'ft_min_word_len',
'ft_max_word_len', and 'ft_stopword_file' values to 'myisamchk'
that you use for 'mysqld'.  For example, if you
have set the minimum word length to 3, you can repair a table with
'myisamchk' like this:

     shell> myisamchk --recover --ft_min_word_len=3 TBL_NAME.MYI

To ensure that 'myisamchk' and the server use the same
values for full-text parameters, you can place each one in both the
'[mysqld]' and '[myisamchk]' sections of an option file:

     [mysqld]
     ft_min_word_len=3

     [myisamchk]
     ft_min_word_len=3

An alternative to using 'myisamchk' is to use the
'REPAIR TABLE', 'ANALYZE TABLE',
see 'OPTIMIZE TABLE', or 'ALTER TABLE'.
These statements are performed by the server,
which knows the proper full-text parameter values to use.

4.6.3.2 myisamchk Check Options
...............................

'myisamchk' supports the following options for table
checking operations:

   *
     '--check', '-c'

     Check the table for errors.  This is the default operation if you
     specify no option that selects an operation type explicitly.

   *
     '--check-only-changed', '-C'

     Check only tables that have changed since the last check.

   *
     '--extend-check', '-e'

     Check the table very thoroughly.  This is quite slow if the table
     has many indexes.  This option should only be used in extreme
     cases.  Normally, see 'myisamchk' or 'myisamchk --medium-check'
     should be able to determine whether
     there are any errors in the table.

     If you are using '--extend-check' and have plenty of memory,
     setting the 'key_buffer_size' variable to a large value helps the
     repair operation run faster.

     See also the description of this option under table repair options.

     For a description of the output format, see
     myisamchk-table-info.

   *
     '--fast', '-F'

     Check only tables that haven't been closed properly.

   *
     '--force', '-f'

     Do a repair operation automatically if 'myisamchk'
     finds any errors in the table.  The repair type is the
     same as that specified with the '--recover' or '-r' option.

   *
     '--information', '-i'

     Print informational statistics about the table that is checked.

   *
     '--medium-check', '-m'

     Do a check that is faster than an '--extend-check' operation.  This
     finds only 99.99% of all errors, which should be good enough in
     most cases.

   *
     '--read-only', '-T'

     Do not mark the table as checked.  This is useful if you use
     'myisamchk' to check a table that is in use by some
     other application that does not use locking, such as
     'mysqld' when run with external locking disabled.

   *
     '--update-state', '-U'

     Store information in the '.MYI' file to indicate when the table was
     checked and whether the table crashed.  This should be used to get
     full benefit of the '--check-only-changed' option, but you
     shouldn't use this option if the 'mysqld' server is
     using the table and you are running it with external locking
     disabled.

4.6.3.3 myisamchk Repair Options
................................

'myisamchk' supports the following options for table
repair operations (operations performed when an option such as
'--recover' or '--safe-recover' is given):

   *
     '--backup', '-B'

     Make a backup of the '.MYD' file as 'FILE_NAME-TIME.BAK'

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--correct-checksum'

     Correct the checksum information for the table.

   *
     '--data-file-length=LEN', '-D LEN'

     The maximum length of the data file (when re-creating data file
     when it is 'full').

   *
     '--extend-check', '-e'

     Do a repair that tries to recover every possible row from the data
     file.  Normally, this also finds a lot of garbage rows.  Do not use
     this option unless you are desperate.

     See also the description of this option under table checking
     options.

     For a description of the output format, see
     myisamchk-table-info.

   *
     '--force', '-f'

     Overwrite old intermediate files (files with names like
     'TBL_NAME.TMD') instead of aborting.

   *
     '--keys-used=VAL', '-k VAL'

     For 'myisamchk', the option value is a bit value
     that indicates which indexes to update.  Each binary bit of the
     option value corresponds to a table index, where the first index is
     bit 0.  An option value of 0 disables updates to all indexes, which
     can be used to get faster inserts.  Deactivated indexes can be
     reactivated by using 'myisamchk -r'.

   *
     '--no-symlinks', '-l'

     Do not follow symbolic links.  Normally 'myisamchk'
     repairs the table that a symlink points to.  This option
     does not exist as of MySQL 4.0 because versions from 4.0 on do not
     remove symlinks during repair operations.

   *
     '--max-record-length=LEN'

     Skip rows larger than the given length if 'myisamchk'
     cannot allocate memory to hold them.

   *
     '--parallel-recover', '-p'

     Use the same technique as '-r' and '-n', but create all the keys in
     parallel, using different threads.  _This is beta-quality code.
     Use at your own risk!_

   *
     '--quick', '-q'

     Achieve a faster repair by modifying only the index file, not the
     data file.  You can specify this option twice to force
     'myisamchk' to modify the original data file in case of
     duplicate keys.

   *
     '--recover', '-r'

     Do a repair that can fix almost any problem except unique keys that
     are not unique (which is an extremely unlikely error with 'MyISAM'
     tables).  If you want to recover a table, this is the option to try
     first.  You should try '--safe-recover' only if 'myisamchk'
     reports that the table cannot be recovered using
     '--recover'.  (In the unlikely case that '--recover' fails, the
     data file remains intact.)

     If you have lots of memory, you should increase the value of
     'myisam_sort_buffer_size'.

   *
     '--safe-recover', '-o'

     Do a repair using an old recovery method that reads through all
     rows in order and updates all index trees based on the rows found.
     This is an order of magnitude slower than '--recover', but can
     handle a couple of very unlikely cases that '--recover' cannot.
     This recovery method also uses much less disk space than
     '--recover'.  Normally, you should repair first using '--recover',
     and then with '--safe-recover' only if '--recover' fails.

     If you have lots of memory, you should increase the value of
     'key_buffer_size'.

   *
     '--set-collation=NAME'

     Specify the collation to use for sorting table indexes.  The
     character set name is implied by the first part of the collation
     name.

   *
     '--sort-recover', '-n'

     Force 'myisamchk' to use sorting to resolve the
     keys even if the temporary files would be very large.

   *
     '--tmpdir=DIR_NAME', '-t DIR_NAME'

     The path of the directory to be used for storing temporary files.
     If this is not set, see 'myisamchk' uses the value of
     the 'TMPDIR' environment variable.  '--tmpdir' can be set to a list
     of directory paths that are used successively in round-robin
     fashion for creating temporary files.  The separator character
     between directory names is the colon (':') on Unix and the
     semicolon (';') on Windows.

   *
     '--unpack', '-u'

     Unpack a table that was packed with 'myisampack'.

4.6.3.4 Other myisamchk Options
...............................

'myisamchk' supports the following options for actions
other than table checks and repairs:

   *
     '--analyze', '-a'

     Analyze the distribution of key values.  This improves join
     performance by enabling the join optimizer to better choose the
     order in which to join the tables and which indexes it should use.
     To obtain information about the key distribution, use a
     'myisamchk --description --verbose TBL_NAME' command or
     the 'SHOW INDEX FROM TBL_NAME' statement.

   *
     '--block-search=OFFSET', '-b OFFSET'

     Find the record that a block at the given offset belongs to.

   *
     '--description', '-d'

     Print some descriptive information about the table.  Specifying the
     '--verbose' option once or twice produces additional information.
     See myisamchk-table-info.

   *
     '--set-auto-increment[=VALUE]', '-A[VALUE]'

     Force 'AUTO_INCREMENT' numbering for new records to start at the
     given value (or higher, if there are existing records with
     'AUTO_INCREMENT' values this large).  If VALUE is not specified,
     'AUTO_INCREMENT' numbers for new records begin with the largest
     value currently in the table, plus one.

   *
     '--sort-index', '-S'

     Sort the index tree blocks in high-low order.  This optimizes seeks
     and makes table scans that use indexes faster.

   *
     '--sort-records=N', '-R N'

     Sort records according to a particular index.  This makes your data
     much more localized and may speed up range-based 'SELECT'
     and 'ORDER BY' operations that use this index.  (The first
     time you use this option to sort a table, it may be very slow.)  To
     determine a table's index numbers, use 'SHOW INDEX',
     which displays a table's indexes in the same order that
     'myisamchk' sees them.  Indexes are numbered
     beginning with 1.

     If keys are not packed ('PACK_KEYS=0'), they have the same length,
     so when 'myisamchk' sorts and moves records, it
     just overwrites record offsets in the index.  If keys are packed
     ('PACK_KEYS=1'), see 'myisamchk' must unpack key
     blocks first, then re-create indexes and pack the key blocks again.
     (In this case, re-creating indexes is faster than updating offsets
     for each index.)

4.6.3.5 Obtaining Table Information with myisamchk
..................................................

To obtain a description of a 'MyISAM' table or statistics about it, use
the commands shown here.  The output from these commands is explained
later in this section.

   * 'myisamchk -d TBL_NAME'.

     Runs 'myisamchk' in 'describe mode' to produce a
     description of your table.  If you start the MySQL server with
     external locking disabled, see 'myisamchk' may report
     an error for a table that is updated while it runs.  However,
     because 'myisamchk' does not change the table in
     describe mode, there is no risk of destroying data.

   * 'myisamchk -dv TBL_NAME'.

     Adding '-v' runs 'myisamchk' in verbose mode so
     that it produces more information about the table.  Adding '-v' a
     second time produces even more information.

   * 'myisamchk -eis TBL_NAME'.

     Shows only the most important information from a table.  This
     operation is slow because it must read the entire table.

   * 'myisamchk -eiv TBL_NAME'.

     This is like '-eis', but tells you what is being done.

The TBL_NAME argument can be either the name of a 'MyISAM' table or the
name of its index file, as described in myisamchk.  Multiple
TBL_NAME arguments can be given.

Suppose that a table named 'person' has the following structure.  (The
'MAX_ROWS' table option is included so that in the example output from
'myisamchk' shown later, some values are smaller and
fit the output format more easily.)

     CREATE TABLE person
     (
       id         INT NOT NULL AUTO_INCREMENT,
       last_name  VARCHAR(20) NOT NULL,
       first_name VARCHAR(20) NOT NULL,
       birth      DATE,
       death      DATE,
       PRIMARY KEY (id),
       INDEX (last_name, first_name),
       INDEX (birth)
     ) MAX_ROWS = 1000000 ENGINE=MYISAM;

Suppose also that the table has these data and index file sizes:

     -rw-rw----  1 mysql  mysql  9347072 Aug 19 11:47 person.MYD
     -rw-rw----  1 mysql  mysql  6066176 Aug 19 11:47 person.MYI

Example of 'myisamchk -dvv' output:

     MyISAM file:         person
     Record format:       Packed
     Character set:       latin1_swedish_ci (8)
     File-version:        1
     Creation time:       2009-08-19 16:47:41
     Recover time:        2009-08-19 16:47:56
     Status:              checked,analyzed,optimized keys
     Auto increment key:              1  Last value:                306688
     Data records:               306688  Deleted blocks:                 0
     Datafile parts:             306688  Deleted data:                   0
     Datafile pointer (bytes):        4  Keyfile pointer (bytes):        3
     Datafile length:           9347072  Keyfile length:           6066176
     Max datafile length:    4294967294  Max keyfile length:   17179868159
     Recordlength:                   54

     table description:
     Key Start Len Index   Type                 Rec/key         Root  Blocksize
     1   2     4   unique  long                       1        99328       1024
     2   6     20  multip. varchar prefix           512      3563520       1024
         27    20          varchar                  512
     3   48    3   multip. uint24 NULL           306688      6065152       1024

     Field Start Length Nullpos Nullbit Type
     1     1     1
     2     2     4                      no zeros
     3     6     21                     varchar
     4     27    21                     varchar
     5     48    3      1       1       no zeros
     6     51    3      1       2       no zeros

Explanations for the types of information 'myisamchk'.
produces are given here.  'Keyfile' refers to the index file.  'Record'
and 'row' are synonymous, as are 'field' and 'column.'

The initial part of the table description contains these values:

   * 'MyISAM file'

     Name of the 'MyISAM' (index) file.

   * 'Record format'

     The format used to store table rows.  The preceding examples use
     'Fixed length'.  Other possible values are 'Compressed' and
     'Packed'.  ('Packed' corresponds to what 'SHOW TABLE STATUS'
     reports as 'Dynamic'.)

   * 'Chararacter set'

     The table default character set.

   * 'File-version'

     Version of 'MyISAM' format.  Always 1.

   * 'Creation time'

     When the data file was created.

   * 'Recover time'

     When the index/data file was last reconstructed.

   * 'Status'

     Table status flags.  Possible values are 'crashed', 'open',
     'changed', 'analyzed', 'optimized keys', and 'sorted index pages'.

   * 'Auto increment key', 'Last value'

     The key number associated the table's 'AUTO_INCREMENT' column, and
     the most recently generated value for this column.  These fields do
     not appear if there is no such column.

   * 'Data records'

     The number of rows in the table.

   * 'Deleted blocks'

     How many deleted blocks still have reserved space.  You can
     optimize your table to minimize this space.  See
     myisam-optimization.

   * 'Datafile parts'

     For dynamic-row format, this indicates how many data blocks there
     are.  For an optimized table without fragmented rows, this is the
     same as 'Data records'.

   * 'Deleted data'

     How many bytes of unreclaimed deleted data there are.  You can
     optimize your table to minimize this space.  See
     myisam-optimization.

   * 'Datafile pointer'

     The size of the data file pointer, in bytes.  It is usually 2, 3,
     4, or 5 bytes.  Most tables manage with 2 bytes, but this cannot be
     controlled from MySQL yet.  For fixed tables, this is a row
     address.  For dynamic tables, this is a byte address.

   * 'Keyfile pointer'

     The size of the index file pointer, in bytes.  It is usually 1, 2,
     or 3 bytes.  Most tables manage with 2 bytes, but this is
     calculated automatically by MySQL. It is always a block address.

   * 'Max datafile length'

     How long the table data file can become, in bytes.

   * 'Max keyfile length'

     How long the table index file can become, in bytes.

   * 'Recordlength'

     How much space each row takes, in bytes.

The 'table description' part of the output includes a list of all keys
in the table.  For each key, see 'myisamchk' displays some
low-level information:

   * 'Key'

     This key's number.  This value is shown only for the first column
     of the key.  If this value is missing, the line corresponds to the
     second or later column of a multiple-column key.  For the table
     shown in the example, there are two 'table description' lines for
     the second index.  This indicates that it is a multiple-part index
     with two parts.

   * 'Start'

     Where in the row this portion of the index starts.

   * 'Len'

     How long this portion of the index is.  For packed numbers, this
     should always be the full length of the column.  For strings, it
     may be shorter than the full length of the indexed column, because
     you can index a prefix of a string column.  The total length of a
     multiple-part key is the sum of the 'Len' values for all key parts.

   * 'Index'

     Whether a key value can exist multiple times in the index.
     Possible values are 'unique' or 'multip.' (multiple).

   * 'Type'

     What data type this portion of the index has.  This is a 'MyISAM'
     data type with the possible values 'packed', 'stripped', or
     'empty'.

   * 'Root'

     Address of the root index block.

   * 'Blocksize'

     The size of each index block.  By default this is 1024, but the
     value may be changed at compile time when MySQL is built from
     source.

   * 'Rec/key'

     This is a statistical value used by the optimizer.  It tells how
     many rows there are per value for this index.  A unique index
     always has a value of 1.  This may be updated after a table is
     loaded (or greatly changed) with 'myisamchk -a'.
     If this is not updated at all, a default value of 30 is given.

The last part of the output provides information about each column:

   * 'Field'

     The column number.

   * 'Start'

     The byte position of the column within table rows.

   * 'Length'

     The length of the column in bytes.

   * 'Nullpos', 'Nullbit'

     For columns that can be 'NULL', 'MyISAM' stores 'NULL' values as a
     flag in a byte.  Depending on how many nullable columns there are,
     there can be one or more bytes used for this purpose.  The
     'Nullpos' and 'Nullbit' values, if nonempty, indicate which byte
     and bit contains that flag indicating whether the column is 'NULL'.

     The position and number of bytes used to store 'NULL' flags is
     shown in the line for field 1.  This is why there are six 'Field'
     lines for the 'person' table even though it has only five columns.

   * 'Type'

     The data type.  The value may contain any of the following
     descriptors:

        * 'constant'

          All rows have the same value.

        * 'no endspace'

          Do not store endspace.

        * 'no endspace, not_always'

          Do not store endspace and do not do endspace compression for
          all values.

        * 'no endspace, no empty'

          Do not store endspace.  Do not store empty values.

        * 'table-lookup'

          The column was converted to an 'ENUM'.

        * 'zerofill(N)'

          The most significant N bytes in the value are always 0 and are
          not stored.

        * 'no zeros'

          Do not store zeros.

        * 'always zero'

          Zero values are stored using one bit.

   * 'Huff tree'

     The number of the Huffman tree associated with the column.

   * 'Bits'

     The number of bits used in the Huffman tree.

The 'Huff tree' and 'Bits' fields are displayed if the table has been
compressed with 'myisampack'.  See myisampack,
for an example of this information.

Example of 'myisamchk -eiv' output:

     Checking MyISAM file: person
     Data records:  306688   Deleted blocks:       0
     - check file-size
     - check record delete-chain
     No recordlinks
     - check key delete-chain
     block_size 1024:
     - check index reference
     - check data record references index: 1
     Key:  1:  Keyblocks used:  98%  Packed:    0%  Max levels:  3
     - check data record references index: 2
     Key:  2:  Keyblocks used:  99%  Packed:   97%  Max levels:  3
     - check data record references index: 3
     Key:  3:  Keyblocks used:  98%  Packed:  -14%  Max levels:  3
     Total:    Keyblocks used:  98%  Packed:   89%

     - check records and index references
     *** LOTS OF ROW NUMBERS DELETED ***

     Records:            306688  M.recordlength:       25  Packed:            83%
     Recordspace used:       97% Empty space:           2% Blocks/Record:   1.00
     Record blocks:      306688  Delete blocks:         0
     Record data:       7934464  Deleted data:          0
     Lost space:         256512  Linkdata:        1156096

     User time 43.08, System time 1.68
     Maximum resident set size 0, Integral resident set size 0
     Non-physical pagefaults 0, Physical pagefaults 0, Swaps 0
     Blocks in 0 out 7, Messages in 0 out 0, Signals 0
     Voluntary context switches 0, Involuntary context switches 0
     Maximum memory usage: 1046926 bytes (1023k)

'myisamchk -eiv' output includes the following
information:

   * 'Data records'

     The number of rows in the table.

   * 'Deleted blocks'

     How many deleted blocks still have reserved space.  You can
     optimize your table to minimize this space.  See
     myisam-optimization.

   * 'Key'

     The key number.

   * 'Keyblocks used'

     What percentage of the keyblocks are used.  When a table has just
     been reorganized with 'myisamchk', the values are
     very high (very near theoretical maximum).

   * 'Packed'

     MySQL tries to pack key values that have a common suffix.  This can
     only be used for indexes on 'CHAR' and
     'VARCHAR' columns.  For long indexed strings that have
     similar leftmost parts, this can significantly reduce the space
     used.  In the preceding example, the second key is 40 bytes long
     and a 97% reduction in space is achieved.

   * 'Max levels'

     How deep the B-tree for this key is.  Large tables with long key
     values get high values.

   * 'Records'

     How many rows are in the table.

   * 'M.recordlength'

     The average row length.  This is the exact row length for tables
     with fixed-length rows, because all rows have the same length.

   * 'Packed'

     MySQL strips spaces from the end of strings.  The 'Packed' value
     indicates the percentage of savings achieved by doing this.

   * 'Recordspace used'

     What percentage of the data file is used.

   * 'Empty space'

     What percentage of the data file is unused.

   * 'Blocks/Record'

     Average number of blocks per row (that is, how many links a
     fragmented row is composed of).  This is always 1.0 for
     fixed-format tables.  This value should stay as close to 1.0 as
     possible.  If it gets too large, you can reorganize the table.  See
     myisam-optimization.

   * 'Recordblocks'

     How many blocks (links) are used.  For fixed-format tables, this is
     the same as the number of rows.

   * 'Deleteblocks'

     How many blocks (links) are deleted.

   * 'Recorddata'

     How many bytes in the data file are used.

   * 'Deleted data'

     How many bytes in the data file are deleted (unused).

   * 'Lost space'

     If a row is updated to a shorter length, some space is lost.  This
     is the sum of all such losses, in bytes.

   * 'Linkdata'

     When the dynamic table format is used, row fragments are linked
     with pointers (4 to 7 bytes each).  'Linkdata' is the sum of the
     amount of storage used by all such pointers.

4.6.3.6 myisamchk Memory Usage
..............................

Memory allocation is important when you run 'myisamchk'.
'myisamchk' uses no more memory than its
memory-related variables are set to.  If you are going to use
'myisamchk' on very large tables, you should first decide
how much memory you want it to use.  The default is to use only about
3MB to perform repairs.  By using larger values, you can get
'myisamchk' to operate faster.  For example, if you have
more than 512MB RAM available, you could use options such as these (in
addition to any other options you might specify):

     shell> myisamchk --myisam_sort_buffer_size=256M \
                --key_buffer_size=512M \
                --read_buffer_size=64M \
                --write_buffer_size=64M ...

Using '--myisam_sort_buffer_size=16M' is probably enough for most cases.

Be aware that 'myisamchk' uses temporary files in
'TMPDIR'.  If 'TMPDIR' points to a memory file system, out of memory
errors can easily occur.  If this happens, run 'myisamchk'
with the '--tmpdir=DIR_NAME' option to specify a directory
located on a file system that has more space.

When performing repair operations, see 'myisamchk' also
needs a lot of disk space:

   * Twice the size of the data file (the original file and a copy).
     This space is not needed if you do a repair with '--quick'; in this
     case, only the index file is re-created.  _This space must be
     available on the same file system as the original data file_, as
     the copy is created in the same directory as the original.

   * Space for the new index file that replaces the old one.  The old
     index file is truncated at the start of the repair operation, so
     you usually ignore this space.  This space must be available on the
     same file system as the original data file.

   * When using '--recover' or '--sort-recover' (but not when using
     '--safe-recover'), you need space on disk for sorting.  This space
     is allocated in the temporary directory (specified by 'TMPDIR' or
     '--tmpdir=DIR_NAME').  The following formula yields the amount of
     space required:

          (LARGEST_KEY + ROW_POINTER_LENGTH) * NUMBER_OF_ROWS * 2

     You can check the length of the keys and the ROW_POINTER_LENGTH
     with 'myisamchk -dv TBL_NAME'. (see
     myisamchk-table-info).  The ROW_POINTER_LENGTH and NUMBER_OF_ROWS
     values are the 'Datafile pointer' and 'Data records' values in the
     table description.  To determine the LARGEST_KEY value, check the
     'Key' lines in the table description.  The 'Len' column indicates
     the number of bytes for each key part.  For a multiple-column
     index, the key size is the sum of the 'Len' values for all key
     parts.

If you have a problem with disk space during repair, you can try
'--safe-recover' instead of '--recover'.

4.6.4 'myisamlog' -- Display MyISAM Log File Contents
-----------------------------------------------------

'myisamlog' processes the contents of a 'MyISAM' log
file.  To create such a file, start the server with a
'--log-isam=log_file' option.

Invoke 'myisamlog' like this:

     shell> myisamlog [OPTIONS] [FILE_NAME [TBL_NAME] ...]

The default operation is update ('-u').  If a recovery is done ('-r'),
all writes and possibly updates and deletes are done and errors are only
counted.  The default log file name is 'myisam.log' if no LOG_FILE
argument is given.  If tables are named on the command line, only those
tables are updated.

'myisamlog' supports the following options:

   * '-?', '-I'

     Display a help message and exit.

   * '-c N'

     Execute only N commands.

   * '-f N'

     Specify the maximum number of open files.

   * '-F FILEPATH/'

     Specify the file path with a trailing slash.

   * '-i'

     Display extra information before exiting.

   * '-o OFFSET'

     Specify the starting offset.

   * '-p N'

     Remove N components from path.

   * '-r'

     Perform a recovery operation.

   * '-R RECORD_POS_FILE RECORD_POS'

     Specify record position file and record position.

   * '-u'

     Perform an update operation.

   * '-v'

     Verbose mode.  Print more output about what the program does.  This
     option can be given multiple times to produce more and more output.

   * '-w WRITE_FILE'

     Specify the write file.

   * '-V'

     Display version information.

4.6.5 'myisampack' -- Generate Compressed, Read-Only MyISAM Tables
------------------------------------------------------------------

The 'myisampack' utility compresses 'MyISAM' tables.
'myisampack' works by compressing each column in the
table separately.  Usually, see 'myisampack' packs the
data file 40% to 70%.

When the table is used later, the server reads into memory the
information needed to decompress columns.  This results in much better
performance when accessing individual rows, because you only have to
uncompress exactly one row.

MySQL uses 'mmap()' when possible to perform memory mapping on
compressed tables.  If 'mmap()' does not work, MySQL falls back to
normal read/write file operations.

Please note the following:

   * If the 'mysqld' server was invoked with external
     locking disabled, it is not a good idea to invoke
     'myisampack' if the table might be updated by the
     server during the packing process.  It is safest to compress tables
     with the server stopped.

   * After packing a table, it becomes read only.  This is generally
     intended (such as when accessing packed tables on a CD).

   * 'myisampack' does not support partitioned
     tables.

Invoke 'myisampack' like this:

     shell> myisampack [OPTIONS] FILE_NAME ...

Each file name argument should be the name of an index ('.MYI') file.
If you are not in the database directory, you should specify the path
name to the file.  It is permissible to omit the '.MYI' extension.

After you compress a table with 'myisampack', use
'myisamchk -rq' to rebuild its indexes.  See
myisamchk.

'myisampack' supports the following options.  It also
reads option files and supports the options for processing them
described at option-file-options.

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--backup', '-b'

     Make a backup of each table's data file using the name
     'TBL_NAME.OLD'.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o'.

   *
     '--force', '-f'

     Produce a packed table even if it becomes larger than the original
     or if the intermediate file from an earlier invocation of
     'myisampack' exists.  (see 'myisampack'.
     creates an intermediate file named 'TBL_NAME.TMD' in the database
     directory while it compresses the table.  If you kill
     'myisampack', the '.TMD' file might not be deleted.)
     Normally, see 'myisampack' exits with an error if it
     finds that 'TBL_NAME.TMD' exists.  With '--force', see
     'myisampack' packs the table anyway.

   *
     '--join=BIG_TBL_NAME', '-j BIG_TBL_NAME'

     Join all tables named on the command line into a single packed
     table BIG_TBL_NAME.  All tables that are to be combined _must_ have
     identical structure (same column names and types, same indexes, and
     so forth).

     BIG_TBL_NAME must not exist prior to the join operation.  All
     source tables named on the command line to be merged into
     BIG_TBL_NAME must exist.  The source tables are read for the join
     operation but not modified.

   *
     '--silent', '-s'

     Silent mode.  Write output only when errors occur.

   *
     '--test', '-t'

     Do not actually pack the table, just test packing it.

   *
     '--tmpdir=DIR_NAME', '-T DIR_NAME'

     Use the named directory as the location where 'myisampack'
     creates temporary files.

   *
     '--verbose', '-v'

     Verbose mode.  Write information about the progress of the packing
     operation and its result.

   *
     '--version', '-V'

     Display version information and exit.

   *
     '--wait', '-w'

     Wait and retry if the table is in use.  If the 'mysqld'
     server was invoked with external locking disabled, it is
     not a good idea to invoke 'myisampack' if the
     table might be updated by the server during the packing process.

The following sequence of commands illustrates a typical table
compression session:

     shell> ls -l station.*
     -rw-rw-r--   1 monty    my         994128 Apr 17 19:00 station.MYD
     -rw-rw-r--   1 monty    my          53248 Apr 17 19:00 station.MYI
     -rw-rw-r--   1 monty    my           5767 Apr 17 19:00 station.frm

     shell> myisamchk -dvv station

     MyISAM file:     station
     Isam-version:  2
     Creation time: 1996-03-13 10:08:58
     Recover time:  1997-02-02  3:06:43
     Data records:              1192  Deleted blocks:              0
     Datafile parts:            1192  Deleted data:                0
     Datafile pointer (bytes):     2  Keyfile pointer (bytes):     2
     Max datafile length:   54657023  Max keyfile length:   33554431
     Recordlength:               834
     Record format: Fixed length

     table description:
     Key Start Len Index   Type                 Root  Blocksize    Rec/key
     1   2     4   unique  unsigned long        1024       1024          1
     2   32    30  multip. text                10240       1024          1

     Field Start Length Type
     1     1     1
     2     2     4
     3     6     4
     4     10    1
     5     11    20
     6     31    1
     7     32    30
     8     62    35
     9     97    35
     10    132   35
     11    167   4
     12    171   16
     13    187   35
     14    222   4
     15    226   16
     16    242   20
     17    262   20
     18    282   20
     19    302   30
     20    332   4
     21    336   4
     22    340   1
     23    341   8
     24    349   8
     25    357   8
     26    365   2
     27    367   2
     28    369   4
     29    373   4
     30    377   1
     31    378   2
     32    380   8
     33    388   4
     34    392   4
     35    396   4
     36    400   4
     37    404   1
     38    405   4
     39    409   4
     40    413   4
     41    417   4
     42    421   4
     43    425   4
     44    429   20
     45    449   30
     46    479   1
     47    480   1
     48    481   79
     49    560   79
     50    639   79
     51    718   79
     52    797   8
     53    805   1
     54    806   1
     55    807   20
     56    827   4
     57    831   4

     shell> myisampack station.MYI
     Compressing station.MYI: (1192 records)
     - Calculating statistics

     normal:     20  empty-space:   16  empty-zero:     12  empty-fill:  11
     pre-space:   0  end-space:     12  table-lookups:   5  zero:         7
     Original trees:  57  After join: 17
     - Compressing file
     87.14%
     Remember to run myisamchk -rq on compressed tables

     shell> myisamchk -rq station
     - check record delete-chain
     - recovering (with sort) MyISAM-table 'station'
     Data records: 1192
     - Fixing index 1
     - Fixing index 2

     shell> mysqladmin -uroot flush-tables

     shell> ls -l station.*
     -rw-rw-r--   1 monty    my         127874 Apr 17 19:00 station.MYD
     -rw-rw-r--   1 monty    my          55296 Apr 17 19:04 station.MYI
     -rw-rw-r--   1 monty    my           5767 Apr 17 19:00 station.frm

     shell> myisamchk -dvv station

     MyISAM file:     station
     Isam-version:  2
     Creation time: 1996-03-13 10:08:58
     Recover time:  1997-04-17 19:04:26
     Data records:               1192  Deleted blocks:              0
     Datafile parts:             1192  Deleted data:                0
     Datafile pointer (bytes):      3  Keyfile pointer (bytes):     1
     Max datafile length:    16777215  Max keyfile length:     131071
     Recordlength:                834
     Record format: Compressed

     table description:
     Key Start Len Index   Type                 Root  Blocksize    Rec/key
     1   2     4   unique  unsigned long       10240       1024          1
     2   32    30  multip. text                54272       1024          1

     Field Start Length Type                         Huff tree  Bits
     1     1     1      constant                             1     0
     2     2     4      zerofill(1)                          2     9
     3     6     4      no zeros, zerofill(1)                2     9
     4     10    1                                           3     9
     5     11    20     table-lookup                         4     0
     6     31    1                                           3     9
     7     32    30     no endspace, not_always              5     9
     8     62    35     no endspace, not_always, no empty    6     9
     9     97    35     no empty                             7     9
     10    132   35     no endspace, not_always, no empty    6     9
     11    167   4      zerofill(1)                          2     9
     12    171   16     no endspace, not_always, no empty    5     9
     13    187   35     no endspace, not_always, no empty    6     9
     14    222   4      zerofill(1)                          2     9
     15    226   16     no endspace, not_always, no empty    5     9
     16    242   20     no endspace, not_always              8     9
     17    262   20     no endspace, no empty                8     9
     18    282   20     no endspace, no empty                5     9
     19    302   30     no endspace, no empty                6     9
     20    332   4      always zero                          2     9
     21    336   4      always zero                          2     9
     22    340   1                                           3     9
     23    341   8      table-lookup                         9     0
     24    349   8      table-lookup                        10     0
     25    357   8      always zero                          2     9
     26    365   2                                           2     9
     27    367   2      no zeros, zerofill(1)                2     9
     28    369   4      no zeros, zerofill(1)                2     9
     29    373   4      table-lookup                        11     0
     30    377   1                                           3     9
     31    378   2      no zeros, zerofill(1)                2     9
     32    380   8      no zeros                             2     9
     33    388   4      always zero                          2     9
     34    392   4      table-lookup                        12     0
     35    396   4      no zeros, zerofill(1)               13     9
     36    400   4      no zeros, zerofill(1)                2     9
     37    404   1                                           2     9
     38    405   4      no zeros                             2     9
     39    409   4      always zero                          2     9
     40    413   4      no zeros                             2     9
     41    417   4      always zero                          2     9
     42    421   4      no zeros                             2     9
     43    425   4      always zero                          2     9
     44    429   20     no empty                             3     9
     45    449   30     no empty                             3     9
     46    479   1                                          14     4
     47    480   1                                          14     4
     48    481   79     no endspace, no empty               15     9
     49    560   79     no empty                             2     9
     50    639   79     no empty                             2     9
     51    718   79     no endspace                         16     9
     52    797   8      no empty                             2     9
     53    805   1                                          17     1
     54    806   1                                           3     9
     55    807   20     no empty                             3     9
     56    827   4      no zeros, zerofill(2)                2     9
     57    831   4      no zeros, zerofill(1)                2     9

'myisampack' displays the following kinds of
information:

   * 'normal'

     The number of columns for which no extra packing is used.

   * 'empty-space'

     The number of columns containing values that are only spaces.
     These occupy one bit.

   * 'empty-zero'

     The number of columns containing values that are only binary zeros.
     These occupy one bit.

   * 'empty-fill'

     The number of integer columns that do not occupy the full byte
     range of their type.  These are changed to a smaller type.  For
     example, a 'BIGINT' column (eight bytes) can
     be stored as a 'TINYINT' column (one byte) if
     all its values are in the range from '-128' to '127'.

   * 'pre-space'

     The number of decimal columns that are stored with leading spaces.
     In this case, each value contains a count for the number of leading
     spaces.

   * 'end-space'

     The number of columns that have a lot of trailing spaces.  In this
     case, each value contains a count for the number of trailing
     spaces.

   * 'table-lookup'

     The column had only a small number of different values, which were
     converted to an 'ENUM' before Huffman compression.

   * 'zero'

     The number of columns for which all values are zero.

   * 'Original trees'

     The initial number of Huffman trees.

   * 'After join'

     The number of distinct Huffman trees left after joining trees to
     save some header space.

After a table has been compressed, the 'Field' lines displayed by
'myisamchk -dvv' include additional information about each
column:

   * 'Type'

     The data type.  The value may contain any of the following
     descriptors:

        * 'constant'

          All rows have the same value.

        * 'no endspace'

          Do not store endspace.

        * 'no endspace, not_always'

          Do not store endspace and do not do endspace compression for
          all values.

        * 'no endspace, no empty'

          Do not store endspace.  Do not store empty values.

        * 'table-lookup'

          The column was converted to an 'ENUM'.

        * 'zerofill(N)'

          The most significant N bytes in the value are always 0 and are
          not stored.

        * 'no zeros'

          Do not store zeros.

        * 'always zero'

          Zero values are stored using one bit.

   * 'Huff tree'

     The number of the Huffman tree associated with the column.

   * 'Bits'

     The number of bits used in the Huffman tree.

After you run 'myisampack', use 'myisamchk'
to re-create any indexes.  At this time, you can also sort
the index blocks and create statistics needed for the MySQL optimizer to
work more efficiently:

     shell> myisamchk -rq --sort-index --analyze TBL_NAME.MYI

After you have installed the packed table into the MySQL database
directory, you should execute 'mysqladmin flush-tables'
to force 'mysqld' to start using the new
table.

To unpack a packed table, use the '--unpack' option to
'myisamchk'.

4.6.6 'mysql_config_editor' -- MySQL Configuration Utility
----------------------------------------------------------

The 'mysql_config_editor' utility enables
you to store authentication credentials in an encrypted login path file
named '.mylogin.cnf'.  The file location is the '%APPDATA%\MySQL'
directory on Windows and the current user's home directory on
non-Windows systems.  The file can be read later by MySQL client
programs to obtain authentication credentials for connecting to MySQL
Server.

The unencrypted format of the '.mylogin.cnf' login path file consists of
option groups, similar to other option files.  Each option group in
'.mylogin.cnf' is called a 'login path,' which is a group that permits
only certain options: 'host', 'user', 'password', 'port' and 'socket'.
Think of a login path option group as a set of options that specify
which MySQL server to connect to and which account to authenticate as.
Here is an unencrypted example:

     [client]
     user = mydefaultname
     password = mydefaultpass
     host = 127.0.0.1
     [mypath]
     user = myothername
     password = myotherpass
     host = localhost

When you invoke a client program to connect to the server, the client
uses '.mylogin.cnf' in conjunction with other option files.  Its
precedence is higher than other option files, but less than options
specified explicitly on the client command line.  For information about
the order in which option files are used, see option-files.

To specify an alternate login path file name, set the
'MYSQL_TEST_LOGIN_FILE' environment variable.  This variable is
recognized by 'mysql_config_editor', by
standard MySQL clients (see 'mysql', 'mysqladmin',
and so forth), and by the 'mysql-test-run.pl' testing
utility.

Programs use groups in the login path file as follows:

   * 'mysql_config_editor' operates on the
     'client' login path by default if you specify no
     '--login-path=NAME' option to indicate explicitly which login path
     to use.

   * Without a '--login-path' option, client programs read the same
     option groups from the login path file that they read from other
     option files.  Consider this command:

          shell> mysql

     By default, the 'mysql' client reads the '[client]'
     and '[mysql]' groups from other option files, so it reads them from
     the login path file as well.

   * With a '--login-path' option, client programs additionally read the
     named login path from the login path file.  The option groups read
     from other option files remain the same.  Consider this command:

          shell> mysql --login-path=mypath

     The 'mysql' client reads '[client]' and '[mysql]'
     from other option files, and '[client]', '[mysql]', and '[mypath]'
     from the login path file.

   * Client programs read the login path file even when the
     '--no-defaults' option is used.  This permits passwords to be
     specified in a safer way than on the command line even if
     '--no-defaults' is present.

'mysql_config_editor' encrypts the
'.mylogin.cnf' file so it cannot be read as cleartext, and its contents
when decrypted by client programs are used only in memory.  In this way,
passwords can be stored in a file in non-cleartext format and used later
without ever needing to be exposed on the command line or in an
environment variable.  See 'mysql_config_editor'.
provides a 'print' command for displaying the login path file contents,
but even in this case, password values are masked so as never to appear
in a way that other users can see them.

The encryption used by 'mysql_config_editor'.
prevents passwords from appearing in '.mylogin.cnf' as cleartext and
provides a measure of security by preventing inadvertent password
exposure.  For example, if you display a regular unencrypted 'my.cnf'
option file on the screen, any passwords it contains are visible for
anyone to see.  With '.mylogin.cnf', that is not true.  But the
encryption used will not deter a determined attacker and you should not
consider it unbreakable.  A user who can gain system administration
privileges on your machine to access your files could decrypt the
'.mylogin.cnf' file with some effort.

The login path file must be readable and writable to the current user,
and inaccessible to other users.  Otherwise, see
'mysql_config_editor' ignores it, and client
programs do not use it, either.

Invoke 'mysql_config_editor' like this:

     shell> mysql_config_editor [PROGRAM_OPTIONS] COMMAND [COMMAND_OPTIONS]

If the login path file does not exist, see 'mysql_config_editor'
creates it.

Command arguments are given as follows:

   * PROGRAM_OPTIONS consists of general 'mysql_config_editor'
     options.

   * 'command' indicates what action to perform on the '.mylogin.cnf'
     login path file.  For example, 'set' writes a login path to the
     file, 'remove' removes a login path, and 'print' displays login
     path contents.

   * COMMAND_OPTIONS indicates any additional options specific to the
     command, such as the login path name and the values to use in the
     login path.

The position of the command name within the set of program arguments is
significant.  For example, these command lines have the same arguments,
but produce different results:

     shell> mysql_config_editor --help set
     shell> mysql_config_editor set --help

The first command line displays a general 'mysql_config_editor'
help message, and ignores the 'set' command.  The
second command line displays a help message specific to the 'set'
command.

Suppose that you want to establish a 'client' login path that defines
your default connection parameters, and an additional login path named
'remote' for connecting to the MySQL server the host
'remote.example.com'.  You want to log in as follows:

   * By default, to the local server with a user name and password of
     'localuser' and 'localpass'

   * To the remote server with a user name and password of 'remoteuser'
     and 'remotepass'

To set up the login paths in the '.mylogin.cnf' file, use the following
'set' commands.  Enter each command on a single line, and enter the
appropriate passwords when prompted:

     shell> mysql_config_editor set --login-path=client
              --host=localhost --user=localuser --password
     Enter password: ENTER PASSWORD "LOCALPASS" HERE
     shell> mysql_config_editor set --login-path=remote
              --host=remote.example.com --user=remoteuser --password
     Enter password: ENTER PASSWORD "REMOTEPASS" HERE

'mysql_config_editor' uses the 'client'
login path by default, so the '--login-path=client' option can be
omitted from the first command without changing its effect.

To see what 'mysql_config_editor' writes to
the '.mylogin.cnf' file, use the 'print' command:

     shell> mysql_config_editor print --all
     [client]
     user = localuser
     password = *****
     host = localhost
     [remote]
     user = remoteuser
     password = *****
     host = remote.example.com

The 'print' command displays each login path as a set of lines beginning
with a group header indicating the login path name in square brackets,
followed by the option values for the login path.  Password values are
masked and do not appear as cleartext.

If you do not specify '--all' to display all login paths or
'--login-path=NAME' to display a named login path, the 'print' command
displays the 'client' login path by default, if there is one.

As shown by the preceding example, the login path file can contain
multiple login paths.  In this way, see 'mysql_config_editor'
makes it easy to set up multiple 'personalities'
for connecting to different MySQL servers, or for connecting to a given
server using different accounts.  Any of these can be selected by name
later using the '--login-path' option when you invoke a client program.
For example, to connect to the remote server, use this command:

     shell> mysql --login-path=remote

Here, see 'mysql' reads the '[client]' and '[mysql]' option
groups from other option files, and the '[client]', '[mysql]', and
'[remote]' groups from the login path file.

To connect to the local server, use this command:

     shell> mysql --login-path=client

Because 'mysql' reads the 'client' and 'mysql' login paths
by default, the '--login-path' option does not add anything in this
case.  That command is equivalent to this one:

     shell> mysql

Options read from the login path file take precedence over options read
from other option files.  Options read from login path groups appearing
later in the login path file take precedence over options read from
groups appearing earlier in the file.

'mysql_config_editor' adds login paths to
the login path file in the order you create them, so you should create
more general login paths first and more specific paths later.  If you
need to move a login path within the file, you can remove it, then
recreate it to add it to the end.  For example, a 'client' login path is
more general because it is read by all client programs, whereas a
'mysqldump' login path is read only by 'mysqldump'.
Options specified later override options specified earlier, so putting
the login paths in the order 'client', 'mysqldump' enables
'mysqldump'.-specific options to override 'client' options.

When you use the 'set' command with 'mysql_config_editor'
to create a login path, you need not specify all
possible option values (host name, user name, password, port, socket).
Only those values given are written to the path.  Any missing values
required later can be specified when you invoke a client path to connect
to the MySQL server, either in other option files or on the command
line.  Any options specified on the command line override those
specified in the login path file or other option files.  For example, if
the credentials in the 'remote' login path also apply for the host
'remote2.example.com', connect to the server on that host like this:

     shell> mysql --login-path=remote --host=remote2.example.com

*mysql_config_editor General Options*

'mysql_config_editor' supports the following
general options, which may be used preceding any command named on the
command line.  For descriptions of command-specific options, see
mysql-config-editor-commands.

*mysql_config_editor General Options*

Format                    Description

-debug                    Write debugging log

-help                     Display help message and exit

-verbose                  Verbose mode

-version                  Display version information and exit

   *
     '--help', '-?'

     Display a general help message and exit.

     To see a command-specific help message, invoke
     'mysql_config_editor' as follows, where
     COMMAND is a command other than 'help':

          shell> mysql_config_editor COMMAND --help

   *
     '--debug[=DEBUG_OPTIONS]', '-# DEBUG_OPTIONS'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is
     'd:t:o,/tmp/mysql_config_editor.trace'.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.
     This option may be helpful in diagnosing problems if an operation
     does not have the effect you expect.

   *
     '--version', '-V'

     Display version information and exit.

*mysql_config_editor Commands and Command-Specific Options*

This section describes the permitted 'mysql_config_editor'
commands, and, for each one, the command-specific
options permitted following the command name on the command line.

In addition, see 'mysql_config_editor' supports
general options that can be used preceding any command.  For
descriptions of these options, see
mysql-config-editor-command-options.

'mysql_config_editor' supports these
commands:

   * 'help'

     Display a general help message and exit.  This command takes no
     following options.

     To see a command-specific help message, invoke
     'mysql_config_editor' as follows, where
     COMMAND is a command other than 'help':

          shell> mysql_config_editor COMMAND --help

   * 'print [OPTIONS]'

     Print the contents of the login path file in unencrypted form, with
     the exception that passwords are displayed as '*****'.

     The default login path name is 'client' if no login path is named.
     If both '--all' and '--login-path' are given, '--all' takes
     precedence.

     The 'print' command permits these options following the command
     name:

        * '--help', '-?'

          Display a help message for the 'print' command and exit.

          To see a general help message, use 'mysql_config_editor --help'.

        * '--all'

          Print the contents of all login paths in the login path file.

        * '--login-path=NAME', '-G NAME'

          Print the contents of the named login path.

   * 'remove [OPTIONS]'

     Remove a login path from the login path file, or modify a login
     path by removing options from it.

     This command removes from the login path only such options as are
     specified with the '--host', '--password', '--port', '--socket',
     and '--user' options.  If none of those options are given, 'remove'
     removes the entire login path.  For example, this command removes
     only the 'user' option from the 'mypath' login path rather than the
     entire 'mypath' login path:

          shell> mysql_config_editor remove --login-path=mypath --user

     This command removes the entire 'mypath' login path:

          shell> mysql_config_editor remove --login-path=mypath

     The 'remove' command permits these options following the command
     name:

        * '--help', '-?'

          Display a help message for the 'remove' command and exit.

          To see a general help message, use 'mysql_config_editor --help'.

        * '--host', '-h'

          Remove the host name from the login path.

        * '--login-path=NAME', '-G NAME'

          The login path to remove or modify.  The default login path
          name is 'client' if this option is not given.

        * '--password', '-p'

          Remove the password from the login path.

        * '--port', '-P'

          Remove the TCP/IP port number from the login path.  This
          option was added in MySQL 5.7.1.

        * '--socket', '-S'

          Remove the Unix socket file name from the login path.  This
          option was added in MySQL 5.7.1.

        * '--user', '-u'

          Remove the user name from the login path.

        * '--warn', '-w'

          Warn and prompt the user for confirmation if the command
          attempts to remove the default login path ('client') and
          '--login-path=client' was not specified.  This option is
          enabled by default; use '--skip-warn' to disable it.

   * 'reset [OPTIONS]'

     Empty the contents of the login path file.

     The 'reset' command permits these options following the command
     name:

        * '--help', '-?'

          Display a help message for the 'reset' command and exit.

          To see a general help message, use 'mysql_config_editor --help'.

   * 'set [OPTIONS]'

     Write a login path to the login path file.

     This command writes to the login path only such options as are
     specified with the '--host', '--password', '--port', '--socket',
     and '--user' options.  If none of those options are given, see
     'mysql_config_editor' writes the login path
     as an empty group.

     The 'set' command permits these options following the command name:

        * '--help', '-?'

          Display a help message for the 'set' command and exit.

          To see a general help message, use 'mysql_config_editor --help'.

        * '--host=HOST_NAME', '-h HOST_NAME'

          The host name to write to the login path.

        * '--login-path=NAME', '-G NAME'

          The login path to create.  The default login path name is
          'client' if this option is not given.

        * '--password', '-p'

          Prompt for a password to write to the login path.  After
          'mysql_config_editor' displays the
          prompt, type the password and press Enter.  To prevent other
          users from seeing the password, see 'mysql_config_editor'
          does not echo it.

          To specify an empty password, press Enter at the password
          prompt.  The resulting login path written to the login path
          file will include a line like this:

               password =

        * '--port=PORT_NUM', '-P PORT_NUM'

          The TCP/IP port number to write to the login path.  This
          option was added in MySQL 5.7.1.

        * '--socket=FILE_NAME', '-S FILE_NAME'

          The Unix socket file name to write to the login path.  This
          option was added in MySQL 5.7.1.

        * '--user=USER_NAME', '-u USER_NAME'

          The user name to write to the login path.

        * '--warn', '-w'

          Warn and prompt the user for confirmation if the command
          attempts to overwrite an existing login path.  This option is
          enabled by default; use '--skip-warn' to disable it.

4.6.7 'mysqlbinlog' -- Utility for Processing Binary Log Files
--------------------------------------------------------------

The server's binary log consists of files containing 'events' that
describe modifications to database contents.  The server writes these
files in binary format.  To display their contents in text format, use
the 'mysqlbinlog' utility.  You can also use
'mysqlbinlog' to display the contents of relay log files
written by a slave server in a replication setup because relay logs have
the same format as binary logs.  The binary log and relay log are
discussed further in binary-log, and slave-logs.

Invoke 'mysqlbinlog' like this:

     shell> mysqlbinlog [OPTIONS] LOG_FILE ...

For example, to display the contents of the binary log file named
'binlog.000003', use this command:

     shell> mysqlbinlog binlog.0000003

The output includes events contained in 'binlog.000003'.  For
statement-based logging, event information includes the SQL statement,
the ID of the server on which it was executed, the timestamp when the
statement was executed, how much time it took, and so forth.  For
row-based logging, the event indicates a row change rather than an SQL
statement.  See replication-formats, for information about
logging modes.

Events are preceded by header comments that provide additional
information.  For example:

     # at 141
     #100309  9:28:36 server id 123  end_log_pos 245
       Query thread_id=3350  exec_time=11  error_code=0

In the first line, the number following 'at' indicates the file offset,
or starting position, of the event in the binary log file.

The second line starts with a date and time indicating when the
statement started on the server where the event originated.  For
replication, this timestamp is propagated to slave servers.  'server id'
is the 'server_id' value of the server where the event originated.
'end_log_pos' indicates where the next event starts (that is, it is the
end position of the current event + 1).  'thread_id' indicates which
thread executed the event.  'exec_time' is the time spent executing the
event, on a master server.  On a slave, it is the difference of the end
execution time on the slave minus the beginning execution time on the
master.  The difference serves as an indicator of how much replication
lags behind the master.  'error_code' indicates the result from
executing the event.  Zero means that no error occurred.

*Note*:

When using event groups, the file offsets of events may be grouped
together and the comments of events may be grouped together.  Do not
mistake these grouped events for blank file offsets.

The output from 'mysqlbinlog' can be re-executed
(for example, by using it as input to 'mysql') to redo the
statements in the log.  This is useful for recovery operations after a
server crash.  For other usage examples, see the discussion later in
this section and in point-in-time-recovery.

Normally, you use 'mysqlbinlog' to read binary log
files directly and apply them to the local MySQL server.  It is also
possible to read binary logs from a remote server by using the
'--read-from-remote-server' option.  To read remote binary logs, the
connection parameter options can be given to indicate how to connect to
the server.  These options are '--host', '--password', '--port',
'--protocol', '--socket', and '--user'; they are ignored except when you
also use the '--read-from-remote-server' option.

When running 'mysqlbinlog' against a large binary
log, be careful that the filesystem has enough space for the resulting
files.  To configure the directory that 'mysqlbinlog'
uses for temporary files, use the 'TMPDIR' environment
variable.

'mysqlbinlog' supports the following options, which
can be specified on the command line or in the '[mysqlbinlog]' and
'[client]' groups of an option file.  For information about option files
used by MySQL programs, see option-files.

*mysqlbinlog Options*

Format              Description                          IntroducedDeprecated

-base64-output      Print binary log entries using
                    base-64 encoding

-bind-address       Use specified network interface to
                    connect to MySQL Server

-binlog-row-event-max-sizeBinary log max event size

-character-sets-dir Directory where character sets are
                    installed

-connection-server-idUsed for testing and debugging.     5.7.5
                    See text for applicable default
                    values and other particulars.

-database           List entries for just this
                    database

-debug              Write debugging log

-debug-check        Print debugging information when
                    program exits

-debug-info         Print debugging information,
                    memory, and CPU statistics when
                    program exits

-default-auth       Authentication plugin to use

-defaults-extra-fileRead named option file in addition
                    to usual option files

-defaults-file      Read only named option file

-defaults-group-suffixOption group suffix value

-disable-log-bin    Disable binary logging

-exclude-gtids      Do not show any of the groups in
                    the GTID set provided

-force-if-open      Read binary log files even if open
                    or not closed properly

-force-read         If mysqlbinlog reads a binary log
                    event that it does not recognize,
                    it prints a warning

-help               Display help message and exit

-hexdump            Display a hex dump of the log in
                    comments

-host               Connect to MySQL server on given
                    host

-idempotent         Cause the server to use idempotent   5.7.0
                    mode while processing binary log
                    updates from this session only

-include-gtids      Show only the groups in the GTID
                    set provided

-local-load         Prepare local temporary files for
                    LOAD DATA INFILE in the specified
                    directory

-login-path         Read login path options from
                    .mylogin.cnf

-no-defaults        Read no option files

-offset             Skip the first N entries in the
                    log

-password           Password to use when connecting to
                    server

-plugin-dir         Directory where plugins are
                    installed

-port               TCP/IP port number for connection

-print-defaults     Print default options

-protocol           Connection protocol to use

-raw                Write events in raw (binary)
                    format to output files

-read-from-remote-masterRead the binary log from a MySQL
                    master rather than reading a local
                    log file

-read-from-remote-serverRead binary log from MySQL server
                    rather than local log file

-result-file        Direct output to named file

-rewrite-db         Create rewrite rules for databases   5.7.1
                    when playing back from logs
                    written in row-based format.  Can
                    be used multiple times.

-secure-auth        Do not send passwords to server in   5.7.4    5.7.5
                    old (pre-4.1) format

-server-id          Extract only those events created
                    by the server having the given
                    server ID

-server-id-bits     Tell mysqlbinlog how to interpret
                    server IDs in binary log when log
                    was written by a mysqld having its
                    server-id-bits set to less than
                    the maximum; supported only by
                    MySQL Cluster version of
                    mysqlbinlog

-set-charset        Add a SET NAMES charset_name
                    statement to the output

-shared-memory-base-nameThe name of shared memory to use
                    for shared-memory connections

-short-form         Display only the statements
                    contained in the log

-skip-gtids         Do not print any GTIDs; use this
                    when writing a dump file from
                    binary logs containing GTIDs.

-socket             For connections to localhost, the
                    Unix socket file to use

-ssl                Enable encrypted connection          5.7.3

-ssl-ca             File that contains list of trusted   5.7.3
                    SSL Certificate Authorities

-ssl-capath         Directory that contains trusted      5.7.3
                    SSL Certificate Authority
                    certificate files

-ssl-cert           File that contains X509              5.7.3
                    certificate

-ssl-cipher         List of permitted ciphers for        5.7.3
                    connection encryption

-ssl-crl            File that contains certificate
                    revocation lists

-ssl-crlpath        Directory that contains
                    certificate revocation list files

-ssl-key            File that contains X509 key          5.7.3

-ssl-mode           Security state of connection to      5.7.11
                    server

-ssl-verify-server-certVerify host name against server   5.7.3
                    certificate Common Name identity

-start-datetime     Read binary log from first event
                    with timestamp equal to or later
                    than datetime argument

-start-position     Read binary log from first event
                    with position equal to or greater
                    than argument

-stop-datetime      Stop reading binary log at first
                    event with timestamp equal to or
                    greater than datetime argument

-stop-never         Stay connected to server after
                    reading last binary log file

-stop-never-slave-server-idSlave server ID to report when
                    connecting to server

-stop-position      Stop reading binary log at first
                    event with position equal to or
                    greater than argument

-tls-version        Protocols permitted for encrypted    5.7.10
                    connections

-to-last-log        Do not stop at the end of
                    requested binary log from a MySQL
                    server, but rather continue
                    printing to end of last binary log

-user               MySQL user name to use when
                    connecting to server

-verbose            Reconstruct row events as SQL
                    statements

-verify-binlog-checksumVerify checksums in binary log

-version            Display version information and
                    exit

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--base64-output=VALUE'

     This option determines when events should be displayed encoded as
     base-64 strings using 'BINLOG' statements.  The
     option has these permissible values (not case-sensitive):

        * 'AUTO' ("automatic") or 'UNSPEC' ("unspecified") displays
          'BINLOG' statements automatically when
          necessary (that is, for format description events and row
          events).  If no '--base64-output' option is given, the effect
          is the same as '--base64-output=AUTO'.

          *Note*:

          Automatic 'BINLOG' display is the only safe
          behavior if you intend to use the output of
          'mysqlbinlog' to re-execute binary log file
          contents.  The other option values are intended only for
          debugging or testing purposes because they may produce output
          that does not include all events in executable form.

        * 'NEVER' causes 'BINLOG' statements not to be
          displayed.  'mysqlbinlog' exits with an
          error if a row event is found that must be displayed using
          'BINLOG'.

        * 'DECODE-ROWS' specifies to 'mysqlbinlog'.
          that you intend for row events to be decoded and displayed as
          commented SQL statements by also specifying the '--verbose'
          option.  Like 'NEVER', 'DECODE-ROWS' suppresses display of
          'BINLOG' statements, but unlike 'NEVER', it
          does not exit with an error if a row event is found.

     For examples that show the effect of '--base64-output' and
     '--verbose' on row event output, see
     mysqlbinlog-row-events.

   *
     '--bind-address=IP_ADDRESS'

     On a computer having multiple network interfaces, use this option
     to select which interface to use for connecting to the MySQL
     server.

   *
     '--binlog-row-event-max-size=N'

     Property                             Value

     *Command-Line Format*                '--binlog-row-event-max-size=#'

     *Type* (64-bit platforms)            numeric

     *Default Value* (64-bit platforms)   '4294967040'

     *Minimum Value* (64-bit platforms)   '256'

     *Maximum Value* (64-bit platforms)   '18446744073709547520'

     Specify the maximum size of a row-based binary log event, in bytes.
     Rows are grouped into events smaller than this size if possible.
     The value should be a multiple of 256.  The default is 4GB.

   *
     '--character-sets-dir=DIR_NAME'

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--connection-server-id=SERVER_ID'

     This option is used to test a MySQL server for support of the
     'BINLOG_DUMP_NON_BLOCK' connection flag, which was inadvertently
     removed in MySQL 5.6.5, and restored in MySQL 5.7.5 (Bug #18000079,
     Bug #71178).  It is not required for normal operations.

     The effective default and minimum values for this option depend on
     whether 'mysqlbinlog' is run in blocking mode
     or non-blocking mode.  When 'mysqlbinlog' is
     run in blocking mode, the default (and minimum) value is 1; when
     run in non-blocking mode, the default (and minimum) value is 0.

     This option was added in MySQL 5.7.5

   *
     '--database=DB_NAME', '-d DB_NAME'

     This option causes 'mysqlbinlog' to output
     entries from the binary log (local log only) that occur while
     DB_NAME is been selected as the default database by 'USE'.

     The '--database' option for 'mysqlbinlog' is
     similar to the '--binlog-do-db' option for 'mysqld',
     but can be used to specify only one database.  If '--database' is
     given multiple times, only the last instance is used.

     The effects of this option depend on whether the statement-based or
     row-based logging format is in use, in the same way that the
     effects of '--binlog-do-db' depend on whether statement-based or
     row-based logging is in use.

     Statement-based logging

     The '--database' option works as follows:

        * While DB_NAME is the default database, statements are output
          whether they modify tables in DB_NAME or a different database.

        * Unless DB_NAME is selected as the default database, statements
          are not output, even if they modify tables in DB_NAME.

        * There is an exception for 'CREATE DATABASE',
          see 'ALTER DATABASE', and
          'DROP DATABASE'.  The database being
          _created, altered, or dropped_ is considered to be the default
          database when determining whether to output the statement.

     Suppose that the binary log was created by executing these
     statements using statement-based-logging:

          INSERT INTO test.t1 (i) VALUES(100);
          INSERT INTO db2.t2 (j)  VALUES(200);
          USE test;
          INSERT INTO test.t1 (i) VALUES(101);
          INSERT INTO t1 (i)      VALUES(102);
          INSERT INTO db2.t2 (j)  VALUES(201);
          USE db2;
          INSERT INTO test.t1 (i) VALUES(103);
          INSERT INTO db2.t2 (j)  VALUES(202);
          INSERT INTO t2 (j)      VALUES(203);

     'mysqlbinlog --database=test' does not output
     the first two 'INSERT' statements because there is
     no default database.  It outputs the three 'INSERT'.
     statements following 'USE test', but not the three
     'INSERT' statements following 'USE db2'.

     'mysqlbinlog --database=db2' does not output
     the first two 'INSERT' statements because there is
     no default database.  It does not output the three 'INSERT'
     statements following 'USE test', but does output
     the three 'INSERT' statements following 'USE db2'.

     Row-based logging

     'mysqlbinlog' outputs only entries that change
     tables belonging to DB_NAME.  The default database has no effect on
     this.  Suppose that the binary log just described was created using
     row-based logging rather than statement-based logging.
     'mysqlbinlog --database=test' outputs only those
     entries that modify 't1' in the test database, regardless of
     whether 'USE' was issued or what the default database
     is.

     If a server is running with 'binlog_format' set to 'MIXED' and you
     want it to be possible to use 'mysqlbinlog'.
     with the '--database' option, you must ensure that tables that are
     modified are in the database selected by 'USE'.  (In
     particular, no cross-database updates should be used.)

     Prior to MySQL 5.7.1, the '--database' option did not work
     correctly with a log written by a GTID-enabled MySQL server.  (Bug
     #15912728)

     When used together with the '--rewrite-db' option (available in
     MySQL 5.7.1 and later), the '--rewrite-db' option is applied first;
     then the '--database' option is applied, using the rewritten
     database name.  The order in which the options are provided makes
     no difference in this regard.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:o,/tmp/mysqlbinlog.trace'.

   *
     '--debug-check'

     Print some debugging information when the program exits.

   *
     '--debug-info'

     Print debugging information and memory and CPU usage statistics
     when the program exits.

   *
     '--default-auth=PLUGIN'

     A hint about the client-side authentication plugin to use.  See
     pluggable-authentication.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

   *
     '--defaults-file=FILE_NAME'

     Use only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     Exception: Even with '--defaults-file', client programs read
     '.mylogin.cnf'.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqlbinlog'
     normally reads the '[client]' and '[mysqlbinlog]'
     groups.  If the '--defaults-group-suffix=_other' option is given,
     see 'mysqlbinlog' also reads the '[client_other]'
     and '[mysqlbinlog_other]' groups.

   *
     '--disable-log-bin', '-D'

     Disable binary logging.  This is useful for avoiding an endless
     loop if you use the '--to-last-log' option and are sending the
     output to the same MySQL server.  This option also is useful when
     restoring after a crash to avoid duplication of the statements you
     have logged.

     This option requires that you have the 'SUPER' privilege.  It
     causes 'mysqlbinlog' to include a 'SET
     sql_log_bin = 0' statement in its output to disable binary logging
     of the remaining output.  The 'SET' statement
     is ineffective unless you have the 'SUPER' privilege.

   *
     '--exclude-gtids=GTID_SET'

     Do not display any of the groups listed in the GTID_SET.

   *
     '--force-if-open', '-F'

     Read binary log files even if they are open or were not closed
     properly.

   *
     '--force-read', '-f'

     With this option, if 'mysqlbinlog' reads a
     binary log event that it does not recognize, it prints a warning,
     ignores the event, and continues.  Without this option, see
     'mysqlbinlog' stops if it reads such an event.

   *
     '--hexdump', '-H'

     Display a hex dump of the log in comments, as described in
     mysqlbinlog-hexdump.  The hex output can be helpful for
     replication debugging.

   *
     '--host=HOST_NAME', '-h HOST_NAME'

     Get the binary log from the MySQL server on the given host.

   *
     '--idempotent'

     Tell the MySQL Server to use idempotent mode while processing
     updates; this causes suppression of any duplicate-key or
     key-not-found errors that the server encounters in the current
     session while processing updates.  This option may prove useful
     whenever it is desirable or necessary to replay one or more binary
     logs to a MySQL Server which may not contain all of the data to
     which the logs refer.

     The scope of effect for this option includes the current
     'mysqlbinlog' client and session only.

     The '--idempotent' option was introduced in MySQL 5.7.0.

   *
     '--include-gtids=GTID_SET'

     Display only the groups listed in the GTID_SET.

   *
     '--local-load=DIR_NAME', '-l DIR_NAME'

     Prepare local temporary files for 'LOAD DATA INFILE'
     in the specified directory.

     *Important*:

     These temporary files are not automatically removed by
     'mysqlbinlog' or any other MySQL program.

   *
     '--login-path=NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.

     The exception is that the '.mylogin.cnf' file, if it exists, is
     read in all cases.  This permits passwords to be specified in a
     safer way than on the command line even when '--no-defaults' is
     used.  ('.mylogin.cnf' is created by the
     'mysql_config_editor' utility.  See
     mysql-config-editor.)

   *
     '--offset=N', '-o N'

     Skip the first N entries in the log.

   *
     '--password[=PASSWORD]', '-p[PASSWORD]'

     The password to use when connecting to the server.  If you use the
     short option form ('-p'), you _cannot_ have a space between the
     option and the password.  If you omit the PASSWORD value following
     the '--password' or '-p' option on the command line, see
     'mysqlbinlog' prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.

   *
     '--plugin-dir=DIR_NAME'

     The directory in which to look for plugins.  Specify this option if
     the '--default-auth' option is used to specify an authentication
     plugin but 'mysqlbinlog' does not find it.  See
     pluggable-authentication.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     The TCP/IP port number to use for connecting to a remote server.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.

   *
     '--protocol={TCP|SOCKET|PIPE|MEMORY}'

     The connection protocol to use for connecting to the server.  It is
     useful when the other connection parameters normally would cause a
     protocol to be used other than the one you want.  For details on
     the permissible values, see connecting.

   *
     '--raw'

     By default, see 'mysqlbinlog' reads binary log
     files and writes events in text format.  The '--raw' option tells
     'mysqlbinlog' to write them in their original
     binary format.  Its use requires that '--read-from-remote-server'
     also be used because the files are requested from a server.
     'mysqlbinlog' writes one output file for each file
     read from the server.  The '--raw' option can be used to make a
     backup of a server's binary log.  With the '--stop-never' option,
     the backup is 'live' because 'mysqlbinlog'.
     stays connected to the server.  By default, output files are
     written in the current directory with the same names as the
     original log files.  Output file names can be modified using the
     '--result-file' option.  For more information, see
     mysqlbinlog-backup.

   *
     '--read-from-remote-master=TYPE'

     Read binary logs from a MySQL server with the 'COM_BINLOG_DUMP' or
     'COM_BINLOG_DUMP_GTID' commands by setting the option value to
     either 'BINLOG-DUMP-NON-GTIDS' or 'BINLOG-DUMP-GTIDS',
     respectively.  If '--read-from-remote-master=BINLOG-DUMP-GTIDS' is
     combined with '--exclude-gtids', transactions can be filtered out
     on the master, avoiding unnecessary network traffic.

     See also the description for '--read-from-remote-server'.

   *
     '--read-from-remote-server', '-R'

     Read the binary log from a MySQL server rather than reading a local
     log file.  Any connection parameter options are ignored unless this
     option is given as well.  These options are '--host', '--password',
     '--port', '--protocol', '--socket', and '--user'.

     This option requires that the remote server be running.  It works
     only for binary log files on the remote server, not relay log
     files.

     This option is like
     '--read-from-remote-master=BINLOG-DUMP-NON-GTIDS'.

   *
     '--result-file=NAME', '-r NAME'

     Without the '--raw' option, this option indicates the file to which
     'mysqlbinlog' writes text output.  With
     '--raw', see 'mysqlbinlog' writes one binary output
     file for each log file transferred from the server, writing them by
     default in the current directory using the same names as the
     original log file.  In this case, the '--result-file' option value
     is treated as a prefix that modifies output file names.

   *
     '--rewrite-db='FROM_NAME->TO_NAME''

     In MySQL 5.7.8 and later, when reading from a row-based or
     statement-based log, rewrite all occurrences of FROM_NAME to
     TO_NAME.  Rewriting is done on the rows, for row-based logs, as
     well as on the 'USE' clauses, for statement-based logs.
     In MySQL versions prior to 5.7.8, this option was only for use when
     restoring tables logged using the row-based format.

     *Warning*:

     Statements in which table names are qualified with database names
     are not rewritten to use the new name when using this option.

     The rewrite rule employed as a value for this option is a string
     having the form ''FROM_NAME->TO_NAME'', as shown previously, and
     for this reason must be enclosed by quotation marks.

     To employ multiple rewrite rules, specify the option multiple
     times, as shown here:

          shell> mysqlbinlog --rewrite-db='dbcurrent->dbold' --rewrite-db='dbtest->dbcurrent' \
                               binlog.00001 > /tmp/statements.sql

     When used together with the '--database' option, the '--rewrite-db'
     option is applied first; then '--database' option is applied, using
     the rewritten database name.  The order in which the options are
     provided makes no difference in this regard.

     This means that, for example, if 'mysqlbinlog'.
     is started with '--rewrite-db='mydb->yourdb' --database=yourdb',
     then all updates to any tables in databases 'mydb' and 'yourdb' are
     included in the output.  On the other hand, if it is started with
     '--rewrite-db='mydb->yourdb' --database=mydb', then
     'mysqlbinlog' outputs no statements at all: since all
     updates to 'mydb' are first rewritten as updates to 'yourdb' before
     applying the '--database' option, there remain no updates that
     match '--database=mydb'.

     This option was added in MySQL 5.7.1.

   *
     '--secure-auth'

     Do not send passwords to the server in old (pre-4.1) format.  This
     prevents connections except for servers that use the newer password
     format.  This option was added in MySQL 5.7.4.

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--server-id=ID'

     Display only those events created by the server having the given
     server ID.

   *
     '--server-id-bits=N'

     Use only the first N bits of the 'server_id' to identify the
     server.  If the binary log was written by a 'mysqld'.
     with server-id-bits set to less than 32 and user data stored in the
     most significant bit, running 'mysqlbinlog'.
     with '--server-id-bits' set to 32 enables this data to be seen.

     This option is supported only by the versions of
     'mysqlbinlog' supplied with the NDB Cluster
     distribution, or built from the NDB Cluster sources.

   *
     '--set-charset=CHARSET_NAME'

     Add a 'SET NAMES CHARSET_NAME' statement to the
     output to specify the character set to be used for processing log
     files.

   *
     '--shared-memory-base-name=NAME'

     On Windows, the shared-memory name to use, for connections made
     using shared memory to a local server.  The default value is
     'MYSQL'.  The shared-memory name is case-sensitive.

     The server must be started with the '--shared-memory' option to
     enable shared-memory connections.

   *
     '--short-form', '-s'

     Display only the statements contained in the log, without any extra
     information or row-based events.  This is for testing only, and
     should not be used in production systems.

   *
     '--skip-gtids[=(true|false)]'

     Do not display any GTIDs in the output.  This is needed when
     writing to a dump file from one or more binary logs containing
     GTIDs, as shown in this example:

          shell> mysqlbinlog --skip-gtids binlog.000001 >  /tmp/dump.sql
          shell> mysqlbinlog --skip-gtids binlog.000002 >> /tmp/dump.sql
          shell> mysql -u root -p -e "source /tmp/dump.sql"

     The use of this option is otherwise not normally recommended in
     production.

   *
     '--socket=PATH', '-S PATH'

     For connections to 'localhost', the Unix socket file to use, or, on
     Windows, the name of the named pipe to use.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to connect to the
     server using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--start-datetime=DATETIME'

     Start reading the binary log at the first event having a timestamp
     equal to or later than the DATETIME argument.  The DATETIME value
     is relative to the local time zone on the machine where you run
     'mysqlbinlog'.  The value should be in a format
     accepted for the 'DATETIME' or 'TIMESTAMP'
     data types.  For example:

          shell> mysqlbinlog --start-datetime="2005-12-25 11:25:56" binlog.000003

     This option is useful for point-in-time recovery.  See
     backup-strategy-example.

   *
     '--start-position=N', '-j N'

     Start reading the binary log at the first event having a position
     equal to or greater than N.  This option applies to the first log
     file named on the command line.

     This option is useful for point-in-time recovery.  See
     backup-strategy-example.

   *
     '--stop-datetime=DATETIME'

     Stop reading the binary log at the first event having a timestamp
     equal to or later than the DATETIME argument.  This option is
     useful for point-in-time recovery.  See the description of the
     '--start-datetime' option for information about the DATETIME value.

     This option is useful for point-in-time recovery.  See
     backup-strategy-example.

   *
     '--stop-never'

     This option is used with '--read-from-remote-server'.  It tells
     'mysqlbinlog' to remain connected to the
     server.  Otherwise 'mysqlbinlog' exits when the
     last log file has been transferred from the server.  '--stop-never'
     implies '--to-last-log', so only the first log file to transfer
     need be named on the command line.

     '--stop-never' is commonly used with '--raw' to make a live binary
     log backup, but also can be used without '--raw' to maintain a
     continuous text display of log events as the server generates them.

   *
     '--stop-never-slave-server-id=ID'

     With '--stop-never', see 'mysqlbinlog' reports a
     server ID of 65535 when it connects to the server.
     '--stop-never-slave-server-id' explicitly specifies the server ID
     to report.  It can be used to avoid a conflict with the ID of a
     slave server or another 'mysqlbinlog' process.
     See mysqlbinlog-server-id.

   *
     '--stop-position=N'

     Stop reading the binary log at the first event having a position
     equal to or greater than N.  This option applies to the last log
     file named on the command line.

     This option is useful for point-in-time recovery.  See
     backup-strategy-example.

   *
     '--tls-version=PROTOCOL_LIST'

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   *
     '--to-last-log', '-t'

     Do not stop at the end of the requested binary log from a MySQL
     server, but rather continue printing until the end of the last
     binary log.  If you send the output to the same MySQL server, this
     may lead to an endless loop.  This option requires
     '--read-from-remote-server'.

   *
     '--user=USER_NAME', '-u USER_NAME'

     The MySQL user name to use when connecting to a remote server.

   *
     '--verbose', '-v'

     Reconstruct row events and display them as commented SQL
     statements.  If this option is given twice (by passing in either
     "-vv" or "-verbose -verbose"), the output includes comments to
     indicate column data types and some metadata, and row query log
     events if so configured.

     For examples that show the effect of '--base64-output' and
     '--verbose' on row event output, see
     mysqlbinlog-row-events.

   *
     '--verify-binlog-checksum', '-c'

     Verify checksums in binary log files.

   *
     '--version', '-V'

     Display version information and exit.

     In MySQL 5.7, the 'mysqlbinlog' version number
     is 3.4.

You can also set the following variable by using '--VAR_NAME=VALUE'
syntax:

   *
     'open_files_limit'

     Specify the number of open file descriptors to reserve.

You can pipe the output of 'mysqlbinlog' into the
'mysql' client to execute the events contained in the
binary log.  This technique is used to recover from a crash when you
have an old backup (see point-in-time-recovery).  For example:

     shell> mysqlbinlog binlog.000001 | mysql -u root -p

Or:

     shell> mysqlbinlog binlog.[0-9]* | mysql -u root -p

If the statements produced by 'mysqlbinlog' may
contain 'BLOB' values, these may cause problems when
'mysql' processes them.  In this case, invoke 'mysql'
with the '--binary-mode' option.

You can also redirect the output of 'mysqlbinlog' to
a text file instead, if you need to modify the statement log first (for
example, to remove statements that you do not want to execute for some
reason).  After editing the file, execute the statements that it
contains by using it as input to the 'mysql' program:

     shell> mysqlbinlog binlog.000001 > tmpfile
     shell> ... EDIT TMPFILE ...
     shell> mysql -u root -p < tmpfile

When 'mysqlbinlog' is invoked with the
'--start-position' option, it displays only those events with an offset
in the binary log greater than or equal to a given position (the given
position must match the start of one event).  It also has options to
stop and start when it sees an event with a given date and time.  This
enables you to perform point-in-time recovery using the
'--stop-datetime' option (to be able to say, for example, 'roll forward
my databases to how they were today at 10:30 a.m.').

If you have more than one binary log to execute on the MySQL server, the
safe method is to process them all using a single connection to the
server.  Here is an example that demonstrates what may be _unsafe_:

     shell> mysqlbinlog binlog.000001 | mysql -u root -p # DANGER!!
     shell> mysqlbinlog binlog.000002 | mysql -u root -p # DANGER!!

Processing binary logs this way using multiple connections to the server
causes problems if the first log file contains a 'CREATE TEMPORARY TABLE'
statement and the second log contains a statement
that uses the temporary table.  When the first 'mysql'.
process terminates, the server drops the temporary table.  When the
second 'mysql' process attempts to use the table, the
server reports 'unknown table.'

To avoid problems like this, use a _single_ See 'mysql'.
process to execute the contents of all binary logs that you want to
process.  Here is one way to do so:

     shell> mysqlbinlog binlog.000001 binlog.000002 | mysql -u root -p

Another approach is to write all the logs to a single file and then
process the file:

     shell> mysqlbinlog binlog.000001 >  /tmp/statements.sql
     shell> mysqlbinlog binlog.000002 >> /tmp/statements.sql
     shell> mysql -u root -p -e "source /tmp/statements.sql"

'mysqlbinlog' can produce output that reproduces a
'LOAD DATA INFILE' operation without the original data
file.  'mysqlbinlog' copies the data to a temporary
file and writes a 'LOAD DATA LOCAL INFILE' statement
that refers to the file.  The default location of the directory where
these files are written is system-specific.  To specify a directory
explicitly, use the '--local-load' option.

Because 'mysqlbinlog' converts 'LOAD DATA INFILE'
statements to 'LOAD DATA LOCAL INFILE'
statements (that is, it adds 'LOCAL'), both the client and
the server that you use to process the statements must be configured
with the 'LOCAL' capability enabled.  See load-data-local.

*Warning*:

The temporary files created for 'LOAD DATA LOCAL'.
statements are _not_ automatically deleted because they are needed until
you actually execute those statements.  You should delete the temporary
files yourself after you no longer need the statement log.  The files
can be found in the temporary file directory and have names like
ORIGINAL_FILE_NAME-#-#.

4.6.7.1 mysqlbinlog Hex Dump Format
...................................

The '--hexdump' option causes 'mysqlbinlog' to
produce a hex dump of the binary log contents:

     shell> mysqlbinlog --hexdump master-bin.000001

The hex output consists of comment lines beginning with '#', so the
output might look like this for the preceding command:

     /*!40019 SET @@session.max_insert_delayed_threads=0*/;
     /*!50003 SET @OLD_COMPLETION_TYPE=@@COMPLETION_TYPE,COMPLETION_TYPE=0*/;
     # at 4
     #051024 17:24:13 server id 1  end_log_pos 98
     # Position  Timestamp   Type   Master ID        Size      Master Pos    Flags
     # 00000004 9d fc 5c 43   0f   01 00 00 00   5e 00 00 00   62 00 00 00   00 00
     # 00000017 04 00 35 2e 30 2e 31 35  2d 64 65 62 75 67 2d 6c |..5.0.15.debug.l|
     # 00000027 6f 67 00 00 00 00 00 00  00 00 00 00 00 00 00 00 |og..............|
     # 00000037 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 |................|
     # 00000047 00 00 00 00 9d fc 5c 43  13 38 0d 00 08 00 12 00 |.......C.8......|
     # 00000057 04 04 04 04 12 00 00 4b  00 04 1a                |.......K...|
     #       Start: binlog v 4, server v 5.0.15-debug-log created 051024 17:24:13
     #       at startup
     ROLLBACK;

Hex dump output currently contains the elements in the following list.
This format is subject to change.  (For more information about binary
log format, see MySQL Internals: The Binary Log
(http://dev.mysql.com/doc/internals/en/binary-log.html).

   * 'Position': The byte position within the log file.

   * 'Timestamp': The event timestamp.  In the example shown, ''9d fc 5c
     43'' is the representation of ''051024 17:24:13'' in hexadecimal.

   * 'Type': The event type code.  In the example shown, ''0f''
     indicates a 'FORMAT_DESCRIPTION_EVENT'.  The following table lists
     the possible type codes.

     Type                                 Name                      Meaning

     '00'                                 'UNKNOWN_EVENT'           This event should never be present in the
                                                                    log.

     '01'                                 'START_EVENT_V3'          This indicates the start of a log file
                                                                    written by MySQL 4 or earlier.

     '02'                                 'QUERY_EVENT'             The most common type of events.  These
                                                                    contain statements executed on the
                                                                    master.

     '03'                                 'STOP_EVENT'              Indicates that master has stopped.

     '04'                                 'ROTATE_EVENT'            Written when the master switches to a new
                                                                    log file.

     '05'                                 'INTVAR_EVENT'            Used for 'AUTO_INCREMENT' values or when
                                                                    the 'LAST_INSERT_ID()' function is used
                                                                    in the statement.

     '06'                                 'LOAD_EVENT'              Used for 'LOAD DATA INFILE'
                                        in MySQL 3.23.

     '07'                                 'SLAVE_EVENT'             Reserved for future use.

     '08'                                 'CREATE_FILE_EVENT'       Used for 'LOAD DATA INFILE'
                                        statements.  This indicates
                                                                    the start of execution of such a
                                                                    statement.  A temporary file is created
                                                                    on the slave.  Used in MySQL 4 only.

     '09'                                 'APPEND_BLOCK_EVENT'      Contains data for use in a 'LOAD DATA INFILE'
                                        statement.  The
                                                                    data is stored in the temporary file on
                                                                    the slave.

     '0a'                                 'EXEC_LOAD_EVENT'         Used for 'LOAD DATA INFILE'
                                        statements.  The contents of
                                                                    the temporary file is stored in the table
                                                                    on the slave.  Used in MySQL 4 only.

     '0b'                                 'DELETE_FILE_EVENT'       Rollback of a 'LOAD DATA INFILE'
                                        statement.  The temporary file
                                                                    should be deleted on the slave.

     '0c'                                 'NEW_LOAD_EVENT'          Used for 'LOAD DATA INFILE'
                                        in MySQL 4 and earlier.

     '0d'                                 'RAND_EVENT'              Used to send information about random
                                                                    values if the 'RAND()' function is used
                                                                    in the statement.

     '0e'                                 'USER_VAR_EVENT'          Used to replicate user variables.

     '0f'                                 'FORMAT_DESCRIPTION_EVENT'This indicates the start of a log file
                                                                    written by MySQL 5 or later.

     '10'                                 'XID_EVENT'               Event indicating commit of an XA
                                                                    transaction.

     '11'                                 'BEGIN_LOAD_QUERY_EVENT'  Used for 'LOAD DATA INFILE'
                                        statements in MySQL 5 and
                                                                    later.

     '12'                                 'EXECUTE_LOAD_QUERY_EVENT'Used for 'LOAD DATA INFILE'
                                        statements in MySQL 5 and
                                                                    later.

     '13'                                 'TABLE_MAP_EVENT'         Information about a table definition.
                                                                    Used in MySQL 5.1.5 and later.

     '14'                                 'PRE_GA_WRITE_ROWS_EVENT' Row data for a single table that should
                                                                    be created.  Used in MySQL 5.1.5 to
                                                                    5.1.17.

     '15'                                 'PRE_GA_UPDATE_ROWS_EVENT'Row data for a single table that needs to
                                                                    be updated.  Used in MySQL 5.1.5 to
                                                                    5.1.17.

     '16'                                 'PRE_GA_DELETE_ROWS_EVENT'Row data for a single table that should
                                                                    be deleted.  Used in MySQL 5.1.5 to
                                                                    5.1.17.

     '17'                                 'WRITE_ROWS_EVENT'        Row data for a single table that should
                                                                    be created.  Used in MySQL 5.1.18 and
                                                                    later.

     '18'                                 'UPDATE_ROWS_EVENT'       Row data for a single table that needs to
                                                                    be updated.  Used in MySQL 5.1.18 and
                                                                    later.

     '19'                                 'DELETE_ROWS_EVENT'       Row data for a single table that should
                                                                    be deleted.  Used in MySQL 5.1.18 and
                                                                    later.

     '1a'                                 'INCIDENT_EVENT'          Something out of the ordinary happened.
                                                                    Added in MySQL 5.1.18.

   * 'Master ID': The server ID of the master that created the event.

   * 'Size': The size in bytes of the event.

   * 'Master Pos': The position of the next event in the original master
     log file.

   * 'Flags': 16 flags.  The following flags are used.  The others are
     reserved for future use.

     Flag                                 Name                      Meaning

     '01'                                 'LOG_EVENT_BINLOG_IN_USE_F'Log file correctly closed.  (Used only in
                                                                    'FORMAT_DESCRIPTION_EVENT'.)  If this
                                                                    flag is set (if the flags are, for
                                                                    example, ''01 00'') in a
                                                                    'FORMAT_DESCRIPTION_EVENT', the log file
                                                                    has not been properly closed.  Most
                                                                    probably this is because of a master
                                                                    crash (for example, due to power
                                                                    failure).

     '02'                                                           Reserved for future use.

     '04'                                 'LOG_EVENT_THREAD_SPECIFIC_F'Set if the event is dependent on the
                                                                    connection it was executed in (for
                                                                    example, ''04 00''), for example, if the
                                                                    event uses temporary tables.

     '08'                                 'LOG_EVENT_SUPPRESS_USE_F'Set in some circumstances when the event
                                                                    is not dependent on the default database.

4.6.7.2 mysqlbinlog Row Event Display
.....................................

The following examples illustrate how 'mysqlbinlog'.
displays row events that specify data modifications.  These correspond
to events with the 'WRITE_ROWS_EVENT', 'UPDATE_ROWS_EVENT', and
'DELETE_ROWS_EVENT' type codes.  The '--base64-output=DECODE-ROWS' and
'--verbose' options may be used to affect row event output.

Suppose that the server is using row-based binary logging and that you
execute the following sequence of statements:

     CREATE TABLE t
     (
       id   INT NOT NULL,
       name VARCHAR(20) NOT NULL,
       date DATE NULL
     ) ENGINE = InnoDB;

     START TRANSACTION;
     INSERT INTO t VALUES(1, 'apple', NULL);
     UPDATE t SET name = 'pear', date = '2009-01-01' WHERE id = 1;
     DELETE FROM t WHERE id = 1;
     COMMIT;

By default, see 'mysqlbinlog' displays row events
encoded as base-64 strings using 'BINLOG' statements.
Omitting extraneous lines, the output for the row events produced by the
preceding statement sequence looks like this:

     shell> mysqlbinlog LOG_FILE
     ...
     # at 218
     #080828 15:03:08 server id 1  end_log_pos 258   Write_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAANoAAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBcBAAAAKAAAAAIBAAAQABEAAAAAAAEAA//8AQAAAAVhcHBsZQ==
     '/*!*/;
     ...
     # at 302
     #080828 15:03:08 server id 1  end_log_pos 356   Update_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAAC4BAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBgBAAAANgAAAGQBAAAQABEAAAAAAAEAA////AEAAAAFYXBwbGX4AQAAAARwZWFyIbIP
     '/*!*/;
     ...
     # at 400
     #080828 15:03:08 server id 1  end_log_pos 442   Delete_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAAJABAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBkBAAAAKgAAALoBAAAQABEAAAAAAAEAA//4AQAAAARwZWFyIbIP
     '/*!*/;

To see the row events as comments in the form of 'pseudo-SQL'
statements, run 'mysqlbinlog' with the '--verbose'
or '-v' option.  The output will contain lines beginning with '###':

     shell> mysqlbinlog -v LOG_FILE
     ...
     # at 218
     #080828 15:03:08 server id 1  end_log_pos 258   Write_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAANoAAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBcBAAAAKAAAAAIBAAAQABEAAAAAAAEAA//8AQAAAAVhcHBsZQ==
     '/*!*/;
     ### INSERT INTO test.t
     ### SET
     ###   @1=1
     ###   @2='apple'
     ###   @3=NULL
     ...
     # at 302
     #080828 15:03:08 server id 1  end_log_pos 356   Update_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAAC4BAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBgBAAAANgAAAGQBAAAQABEAAAAAAAEAA////AEAAAAFYXBwbGX4AQAAAARwZWFyIbIP
     '/*!*/;
     ### UPDATE test.t
     ### WHERE
     ###   @1=1
     ###   @2='apple'
     ###   @3=NULL
     ### SET
     ###   @1=1
     ###   @2='pear'
     ###   @3='2009:01:01'
     ...
     # at 400
     #080828 15:03:08 server id 1  end_log_pos 442   Delete_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAAJABAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBkBAAAAKgAAALoBAAAQABEAAAAAAAEAA//4AQAAAARwZWFyIbIP
     '/*!*/;
     ### DELETE FROM test.t
     ### WHERE
     ###   @1=1
     ###   @2='pear'
     ###   @3='2009:01:01'

Specify '--verbose' or '-v' twice to also display data types and some
metadata for each column.  The output will contain an additional comment
following each column change:

     shell> mysqlbinlog -vv LOG_FILE
     ...
     # at 218
     #080828 15:03:08 server id 1  end_log_pos 258   Write_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAANoAAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBcBAAAAKAAAAAIBAAAQABEAAAAAAAEAA//8AQAAAAVhcHBsZQ==
     '/*!*/;
     ### INSERT INTO test.t
     ### SET
     ###   @1=1 /* INT meta=0 nullable=0 is_null=0 */
     ###   @2='apple' /* VARSTRING(20) meta=20 nullable=0 is_null=0 */
     ###   @3=NULL /* VARSTRING(20) meta=0 nullable=1 is_null=1 */
     ...
     # at 302
     #080828 15:03:08 server id 1  end_log_pos 356   Update_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAAC4BAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBgBAAAANgAAAGQBAAAQABEAAAAAAAEAA////AEAAAAFYXBwbGX4AQAAAARwZWFyIbIP
     '/*!*/;
     ### UPDATE test.t
     ### WHERE
     ###   @1=1 /* INT meta=0 nullable=0 is_null=0 */
     ###   @2='apple' /* VARSTRING(20) meta=20 nullable=0 is_null=0 */
     ###   @3=NULL /* VARSTRING(20) meta=0 nullable=1 is_null=1 */
     ### SET
     ###   @1=1 /* INT meta=0 nullable=0 is_null=0 */
     ###   @2='pear' /* VARSTRING(20) meta=20 nullable=0 is_null=0 */
     ###   @3='2009:01:01' /* DATE meta=0 nullable=1 is_null=0 */
     ...
     # at 400
     #080828 15:03:08 server id 1  end_log_pos 442   Delete_rows: table id 17 flags: STMT_END_F

     BINLOG '
     fAS3SBMBAAAALAAAAJABAAAAABEAAAAAAAAABHRlc3QAAXQAAwMPCgIUAAQ=
     fAS3SBkBAAAAKgAAALoBAAAQABEAAAAAAAEAA//4AQAAAARwZWFyIbIP
     '/*!*/;
     ### DELETE FROM test.t
     ### WHERE
     ###   @1=1 /* INT meta=0 nullable=0 is_null=0 */
     ###   @2='pear' /* VARSTRING(20) meta=20 nullable=0 is_null=0 */
     ###   @3='2009:01:01' /* DATE meta=0 nullable=1 is_null=0 */

You can tell 'mysqlbinlog' to suppress the
'BINLOG' statements for row events by using the
'--base64-output=DECODE-ROWS' option.  This is similar to
'--base64-output=NEVER' but does not exit with an error if a row event
is found.  The combination of '--base64-output=DECODE-ROWS' and
'--verbose' provides a convenient way to see row events only as SQL
statements:

     shell> mysqlbinlog -v --base64-output=DECODE-ROWS LOG_FILE
     ...
     # at 218
     #080828 15:03:08 server id 1  end_log_pos 258   Write_rows: table id 17 flags: STMT_END_F
     ### INSERT INTO test.t
     ### SET
     ###   @1=1
     ###   @2='apple'
     ###   @3=NULL
     ...
     # at 302
     #080828 15:03:08 server id 1  end_log_pos 356   Update_rows: table id 17 flags: STMT_END_F
     ### UPDATE test.t
     ### WHERE
     ###   @1=1
     ###   @2='apple'
     ###   @3=NULL
     ### SET
     ###   @1=1
     ###   @2='pear'
     ###   @3='2009:01:01'
     ...
     # at 400
     #080828 15:03:08 server id 1  end_log_pos 442   Delete_rows: table id 17 flags: STMT_END_F
     ### DELETE FROM test.t
     ### WHERE
     ###   @1=1
     ###   @2='pear'
     ###   @3='2009:01:01'

*Note*:

You should not suppress 'BINLOG' statements if you intend
to re-execute 'mysqlbinlog' output.

The SQL statements produced by '--verbose' for row events are much more
readable than the corresponding 'BINLOG' statements.
However, they do not correspond exactly to the original SQL statements
that generated the events.  The following limitations apply:

   * The original column names are lost and replaced by '@N', where N is
     a column number.

   * Character set information is not available in the binary log, which
     affects string column display:

        * There is no distinction made between corresponding binary and
          nonbinary string types (see 'BINARY' and
          'CHAR', 'VARBINARY' and
          'VARCHAR', 'BLOB' and 'TEXT').
          The output uses a data type of 'STRING' for
          fixed-length strings and 'VARSTRING' for variable-length
          strings.

        * For multibyte character sets, the maximum number of bytes per
          character is not present in the binary log, so the length for
          string types is displayed in bytes rather than in characters.
          For example, 'STRING(4)' will be used as the data type for
          values from either of these column types:

               CHAR(4) CHARACTER SET latin1
               CHAR(2) CHARACTER SET ucs2

        * Due to the storage format for events of type
          'UPDATE_ROWS_EVENT', see 'UPDATE' statements are
          displayed with the 'WHERE' clause preceding the 'SET' clause.

Proper interpretation of row events requires the information from the
format description event at the beginning of the binary log.  Because
'mysqlbinlog' does not know in advance whether the
rest of the log contains row events, by default it displays the format
description event using a 'BINLOG' statement in the
initial part of the output.

If the binary log is known not to contain any events requiring a
'BINLOG' statement (that is, no row events), the
'--base64-output=NEVER' option can be used to prevent this header from
being written.

4.6.7.3 Using mysqlbinlog to Back Up Binary Log Files
.....................................................

By default, see 'mysqlbinlog' reads binary log files and
displays their contents in text format.  This enables you to examine
events within the files more easily and to re-execute them (for example,
by using the output as input to 'mysql').
'mysqlbinlog' can read log files directly from the local
file system, or, with the '--read-from-remote-server' option, it can
connect to a server and request binary log contents from that server.
'mysqlbinlog' writes text output to its standard
output, or to the file named as the value of the
'--result-file=FILE_NAME' option if that option is given.

'mysqlbinlog' can read binary log files and write
new files containing the same content--that is, in binary format rather
than text format.  This capability enables you to easily back up a
binary log in its original format.  See 'mysqlbinlog'.
can make a static backup, backing up a set of log files and stopping
when the end of the last file is reached.  It can also make a continuous
('live') backup, staying connected to the server when it reaches the end
of the last log file and continuing to copy new events as they are
generated.  In continuous-backup operation, see 'mysqlbinlog'
runs until the connection ends (for example, when the
server exits) or 'mysqlbinlog' is forcibly
terminated.  When the connection ends, see 'mysqlbinlog'.
does not wait and retry the connection, unlike a slave replication
server.  To continue a live backup after the server has been restarted,
you must also restart 'mysqlbinlog'.

Binary log backup requires that you invoke 'mysqlbinlog'
with two options at minimum:

   * The '--read-from-remote-server' (or '-R') option tells
     'mysqlbinlog' to connect to a server and request its
     binary log.  (This is similar to a slave replication server
     connecting to its master server.)

   * The '--raw' option tells 'mysqlbinlog' to write
     raw (binary) output, not text output.

Along with '--read-from-remote-server', it is common to specify other
options: '--host' indicates where the server is running, and you may
also need to specify connection options such as '--user' and
'--password'.

Several other options are useful in conjunction with '--raw':

   * '--stop-never': Stay connected to the server after reaching the end
     of the last log file and continue to read new events.

   * '--stop-never-slave-server-id=ID': The server ID that
     'mysqlbinlog' reports to the server when
     '--stop-never' is used.  The default is 65535.  This can be used to
     avoid a conflict with the ID of a slave server or another
     'mysqlbinlog' process.  See
     mysqlbinlog-server-id.

   * '--result-file': A prefix for output file names, as described
     later.

To back up a server's binary log files with 'mysqlbinlog',
you must specify file names that actually exist on the
server.  If you do not know the names, connect to the server and use the
'SHOW BINARY LOGS' statement to see the current
names.  Suppose that the statement produces this output:

     mysql> SHOW BINARY LOGS;
     +---------------+-----------+
     | Log_name      | File_size |
     +---------------+-----------+
     | binlog.000130 |     27459 |
     | binlog.000131 |     13719 |
     | binlog.000132 |     43268 |
     +---------------+-----------+

With that information, you can use 'mysqlbinlog' to
back up the binary log to the current directory as follows (enter each
command on a single line):

   * To make a static backup of 'binlog.000130' through 'binlog.000132',
     use either of these commands:

          mysqlbinlog --read-from-remote-server --host=HOST_NAME --raw
            binlog.000130 binlog.000131 binlog.000132

          mysqlbinlog --read-from-remote-server --host=HOST_NAME --raw
            --to-last-log binlog.000130

     The first command specifies every file name explicitly.  The second
     names only the first file and uses '--to-last-log' to read through
     the last.  A difference between these commands is that if the
     server happens to open 'binlog.000133' before 'mysqlbinlog'
     reaches the end of 'binlog.000132', the first command
     will not read it, but the second command will.

   * To make a live backup in which 'mysqlbinlog'.
     starts with 'binlog.000130' to copy existing log files, then stays
     connected to copy new events as the server generates them:

          mysqlbinlog --read-from-remote-server --host=HOST_NAME --raw
            --stop-never binlog.000130

     With '--stop-never', it is not necessary to specify '--to-last-log'
     to read to the last log file because that option is implied.

*Output File Naming*

Without '--raw', see 'mysqlbinlog' produces text output
and the '--result-file' option, if given, specifies the name of the
single file to which all output is written.  With '--raw', see
'mysqlbinlog' writes one binary output file for each log
file transferred from the server.  By default, see 'mysqlbinlog'
writes the files in the current directory with the same
names as the original log files.  To modify the output file names, use
the '--result-file' option.  In conjunction with '--raw', the
'--result-file' option value is treated as a prefix that modifies the
output file names.

Suppose that a server currently has binary log files named
'binlog.000999' and up.  If you use 'mysqlbinlog --raw'
to back up the files, the '--result-file' option produces
output file names as shown in the following table.  You can write the
files to a specific directory by beginning the '--result-file' value
with the directory path.  If the '--result-file' value consists only of
a directory name, the value must end with the pathname separator
character.  Output files are overwritten if they exist.

'--result-file' Option               Output File Names

'--result-file=x'                    'xbinlog.000999' and up

'--result-file=/tmp/'                '/tmp/binlog.000999' and up

'--result-file=/tmp/x'               '/tmp/xbinlog.000999' and up

*Example: mysqldump + mysqlbinlog for Backup and Restore*

The following example describes a simple scenario that shows how to use
'mysqldump' and 'mysqlbinlog'.
together to back up a server's data and binary log, and how to use the
backup to restore the server if data loss occurs.  The example assumes
that the server is running on host HOST_NAME and its first binary log
file is named 'binlog.000999'.  Enter each command on a single line.

Use 'mysqlbinlog' to make a continuous backup of the
binary log:

     mysqlbinlog --read-from-remote-server --host=HOST_NAME --raw
       --stop-never binlog.000999

Use 'mysqldump' to create a dump file as a snapshot of
the server's data.  Use '--all-databases', '--events', and '--routines'
to back up all data, and '--master-data=2' to include the current binary
log coordinates in the dump file.

     mysqldump --host=HOST_NAME --all-databases --events --routines --master-data=2> DUMP_FILE

Execute the 'mysqldump' command periodically to create
newer snapshots as desired.

If data loss occurs (for example, if the server crashes), use the most
recent dump file to restore the data:

     mysql --host=HOST_NAME -u root -p < DUMP_FILE

Then use the binary log backup to re-execute events that were written
after the coordinates listed in the dump file.  Suppose that the
coordinates in the file look like this:

     -- CHANGE MASTER TO MASTER_LOG_FILE='binlog.001002', MASTER_LOG_POS=27284;

If the most recent backed-up log file is named 'binlog.001004',
re-execute the log events like this:

     mysqlbinlog --start-position=27284 binlog.001002 binlog.001003 binlog.001004
       | mysql --host=HOST_NAME -u root -p

You might find it easier to copy the backup files (dump file and binary
log files) to the server host to make it easier to perform the restore
operation, or if MySQL does not allow remote 'root' access.

4.6.7.4 Specifying the mysqlbinlog Server ID
............................................

When invoked with the '--read-from-remote-server' option, see
'mysqlbinlog' connects to a MySQL server, specifies a
server ID to identify itself, and requests binary log files from the
server.  You can use 'mysqlbinlog' to request log
files from a server in several ways:

   * Specify an explicitly named set of files: For each file, see
     'mysqlbinlog' connects and issues a 'Binlog dump'
     command.  The server sends the file and disconnects.  There is one
     connection per file.

   * Specify the beginning file and '--to-last-log':
     'mysqlbinlog' connects and issues a 'Binlog dump'
     command for all files.  The server sends all files and disconnects.

   * Specify the beginning file and '--stop-never' (which implies
     '--to-last-log'): 'mysqlbinlog' connects and
     issues a 'Binlog dump' command for all files.  The server sends all
     files, but does not disconnect after sending the last one.

With '--read-from-remote-server' only, see 'mysqlbinlog'.
connects using a server ID of 0, which tells the server to disconnect
after sending the last requested log file.

With '--read-from-remote-server' and '--stop-never', see
'mysqlbinlog' connects using a nonzero server ID, so the
server does not disconnect after sending the last log file.  The server
ID is 65535 by default, but this can be changed with
'--stop-never-slave-server-id'.

Thus, for the first two ways of requesting files, the server disconnects
because 'mysqlbinlog' specifies a server ID of 0.
It does not disconnect if '--stop-never' is given because
'mysqlbinlog' specifies a nonzero server ID.

4.6.8 'mysqldumpslow' -- Summarize Slow Query Log Files
-------------------------------------------------------

The MySQL slow query log contains information about queries that take a
long time to execute (see slow-query-log).
'mysqldumpslow' parses MySQL slow query log files and
prints a summary of their contents.

Normally, see 'mysqldumpslow' groups queries that are
similar except for the particular values of number and string data
values.  It 'abstracts' these values to 'N' and ''S'' when displaying
summary output.  The '-a' and '-n' options can be used to modify value
abstracting behavior.

Invoke 'mysqldumpslow' like this:

     shell> mysqldumpslow [OPTIONS] [LOG_FILE ...]

'mysqldumpslow' supports the following options.

*mysqldumpslow Options*

Format                    Description

-a                        Do not abstract all numbers to N and strings
                          to S

-n                        Abstract numbers with at least the specified
                          digits

-debug                    Write debugging information

-g                        Only consider statements that match the
                          pattern

-help                     Display help message and exit

-h                        Host name of the server in the log file name

-i                        Name of the server instance

-l                        Do not subtract lock time from total time

-r                        Reverse the sort order

-s                        How to sort output

-t                        Display only first num queries

-verbose                  Verbose mode

   *
     '--help'

     Display a help message and exit.

   * '-a'

     Do not abstract all numbers to 'N' and strings to ''S''.

   *
     '--debug', '-d'

     Run in debug mode.

   * '-g PATTERN'

     Consider only queries that match the ('grep'-style) pattern.

   * '-h HOST_NAME'

     Host name of MySQL server for '*-slow.log' file name.  The value
     can contain a wildcard.  The default is '*' (match all).

   * '-i NAME'

     Name of server instance (if using 'mysql.server'
     startup script).

   * '-l'

     Do not subtract lock time from total time.

   * '-n N'

     Abstract numbers with at least N digits within names.

   * '-r'

     Reverse the sort order.

   * '-s SORT_TYPE'

     How to sort the output.  The value of SORT_TYPE should be chosen
     from the following list:

        * 't', 'at': Sort by query time or average query time

        * 'l', 'al': Sort by lock time or average lock time

        * 'r', 'ar': Sort by rows sent or average rows sent

        * 'c': Sort by count

     By default, see 'mysqldumpslow' sorts by average
     query time (equivalent to '-s at').

   * '-t N'

     Display only the first N queries in the output.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.

Example of usage:

     shell> mysqldumpslow

     Reading mysql slow query log from /usr/local/mysql/data/mysqld51-apple-slow.log
     Count: 1  Time=4.32s (4s)  Lock=0.00s (0s)  Rows=0.0 (0), root[root]@localhost
      insert into t2 select * from t1

     Count: 3  Time=2.53s (7s)  Lock=0.00s (0s)  Rows=0.0 (0), root[root]@localhost
      insert into t2 select * from t1 limit N

     Count: 3  Time=2.13s (6s)  Lock=0.00s (0s)  Rows=0.0 (0), root[root]@localhost
      insert into t1 select * from t1

4.7 MySQL Program Development Utilities
=======================================

This section describes some utilities that you may find useful when
developing MySQL programs.

In shell scripts, you can use the 'my_print_defaults'
program to parse option files and see what options
would be used by a given program.  The following example shows the
output that 'my_print_defaults' might produce
when asked to show the options found in the '[client]' and '[mysql]'
groups:

     shell> my_print_defaults client mysql
     --port=3306
     --socket=/tmp/mysql.sock
     --no-auto-rehash

Note for developers: Option file handling is implemented in the C client
library simply by processing all options in the appropriate group or
groups before any command-line arguments.  This works well for programs
that use the last instance of an option that is specified multiple
times.  If you have a C or C++ program that handles multiply specified
options this way but that doesn't read option files, you need add only
two lines to give it that capability.  Check the source code of any of
the standard MySQL clients to see how to do this.

Several other language interfaces to MySQL are based on the C client
library, and some of them provide a way to access option file contents.
These include Perl and Python.  For details, see the documentation for
your preferred interface.

4.7.1 'mysql_config' -- Display Options for Compiling Clients
-------------------------------------------------------------

'mysql_config' provides you with useful information
for compiling your MySQL client and connecting it to MySQL. It is a
shell script, so it is available only on Unix and Unix-like systems.

*Note*:

As of MySQL 5.7.9, 'pkg-config' can be used as an alternative to
'mysql_config' for obtaining information such as compiler
flags or link libraries required to compile MySQL applications.  For
more information, see c-api-building-clients-pkg-config.

*Note*:

As of MySQL 5.7.4, for binary distributions for Solaris, see
'mysql_config' does not provide arguments for linking
with the embedded library.  To get linking arguments for the embedded
library, use the 'mysql_server_config' script instead.

'mysql_config' supports the following options.

   *
     '--cflags'

     C Compiler flags to find include files and critical compiler flags
     and defines used when compiling the 'libmysqlclient' library.  The
     options returned are tied to the specific compiler that was used
     when the library was created and might clash with the settings for
     your own compiler.  Use '--include' for more portable options that
     contain only include paths.

   *
     '--cxxflags'

     Like '--cflags', but for C++ compiler flags.

   *
     '--include'

     Compiler options to find MySQL include files.

   *
     '--libmysqld-libs', '--embedded-libs', '--embedded'

     Libraries and options required to link with 'libmysqld', the MySQL
     embedded server.

     *Note*:

     The 'libmysqld' embedded server library is deprecated as of MySQL
     5.7.19 and will be removed in MySQL 8.0.

   *
     '--libs'

     Libraries and options required to link with the MySQL client
     library.

   *
     '--libs_r'

     Libraries and options required to link with the thread-safe MySQL
     client library.  In MySQL 5.7, all client libraries are
     thread-safe, so this option need not be used.  The '--libs' option
     can be used in all cases.

   *
     '--plugindir'

     The default plugin directory path name, defined when configuring
     MySQL.

   *
     '--port'

     The default TCP/IP port number, defined when configuring MySQL.

   *
     '--socket'

     The default Unix socket file, defined when configuring MySQL.

   *
     '--variable=VAR_NAME'

     Display the value of the named configuration variable.  Permitted
     VAR_NAME values are 'pkgincludedir' (the header file directory),
     'pkglibdir' (the library directory), and 'plugindir' (the plugin
     directory).

   *
     '--version'

     Version number for the MySQL distribution.

If you invoke 'mysql_config' with no options, it
displays a list of all options that it supports, and their values:

     shell> mysql_config
     Usage: /usr/local/mysql/bin/mysql_config [options]
     Options:
       --cflags         [-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]
       --cxxflags       [-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]
       --include        [-I/usr/local/mysql/include/mysql]
       --libs           [-L/usr/local/mysql/lib/mysql -lmysqlclient
                         -lpthread -lm -lrt -lssl -lcrypto -ldl]
       --libs_r         [-L/usr/local/mysql/lib/mysql -lmysqlclient_r
                         -lpthread -lm -lrt -lssl -lcrypto -ldl]
       --plugindir      [/usr/local/mysql/lib/plugin]
       --socket         [/tmp/mysql.sock]
       --port           [3306]
       --version        [5.7.9]
       --libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld
                         -lpthread -lm -lrt -lssl -lcrypto -ldl -lcrypt]
       --variable=VAR   VAR is one of:
               pkgincludedir [/usr/local/mysql/include]
               pkglibdir     [/usr/local/mysql/lib]
               plugindir     [/usr/local/mysql/lib/plugin]

You can use 'mysql_config' within a command line
using backticks to include the output that it produces for particular
options.  For example, to compile and link a MySQL client program, use
'mysql_config' as follows:

     gcc -c `mysql_config --cflags` progname.c
     gcc -o progname progname.o `mysql_config --libs`

4.7.2 'my_print_defaults' -- Display Options from Option Files
--------------------------------------------------------------

'my_print_defaults' displays the options that
are present in option groups of option files.  The output indicates what
options will be used by programs that read the specified option groups.
For example, the 'mysqlcheck' program reads the
'[mysqlcheck]' and '[client]' option groups.  To see what options are
present in those groups in the standard option files, invoke
'my_print_defaults' like this:

     shell> my_print_defaults mysqlcheck client
     --user=myusername
     --password=PASSWORD
     --host=localhost

The output consists of options, one per line, in the form that they
would be specified on the command line.

'my_print_defaults' supports the following
options.

   *
     '--help', '-?'

     Display a help message and exit.

   *
     '--config-file=FILE_NAME',

     '--defaults-file=FILE_NAME', '-c FILE_NAME'

     Read only the given option file.

   *
     '--debug=DEBUG_OPTIONS', '-# DEBUG_OPTIONS'

     Write a debugging log.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is
     'd:t:o,/tmp/my_print_defaults.trace'.

   *
     '--defaults-extra-file=FILE_NAME',

     '--extra-file=FILE_NAME', '-e FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.

   *
     '--defaults-group-suffix=SUFFIX', '-g SUFFIX'

     In addition to the groups named on the command line, read groups
     that have the given suffix.

   *
     '--login-path=NAME', '-l NAME'

     Read options from the named login path in the '.mylogin.cnf' login
     path file.  A 'login path' is an option group containing options
     that specify which MySQL server to connect to and which account to
     authenticate as.  To create or modify a login path file, use the
     'mysql_config_editor' utility.  See
     mysql-config-editor.

   *
     '--no-defaults', '-n'

     Return an empty string.

   *
     '--show', '-s'

     As of MySQL 5.7.8, see 'my_print_defaults'.
     masks passwords by default.  Use this option to display passwords
     in cleartext.

   *
     '--verbose', '-v'

     Verbose mode.  Print more information about what the program does.

   *
     '--version', '-V'

     Display version information and exit.

4.7.3 'resolve_stack_dump' -- Resolve Numeric Stack Trace Dump to Symbols
-------------------------------------------------------------------------

'resolve_stack_dump' resolves a numeric stack
dump to symbols.

Invoke 'resolve_stack_dump' like this:

     shell> resolve_stack_dump [OPTIONS] SYMBOLS_FILE [NUMERIC_DUMP_FILE]

The symbols file should include the output from the 'nm --numeric-sort
mysqld' command.  The numeric dump file should contain a numeric stack
track from 'mysqld'.  If no numeric dump file is named on
the command line, the stack trace is read from the standard input.

'resolve_stack_dump' supports the following
options.

   *
     '--help', '-h'

     Display a help message and exit.

   *
     '--numeric-dump-file=FILE_NAME', '-n FILE_NAME'

     Read the stack trace from the given file.

   *
     '--symbols-file=FILE_NAME', '-s FILE_NAME'

     Use the given symbols file.

   *
     '--version', '-V'

     Display version information and exit.

For more information, see using-stack-trace.

4.8 Miscellaneous Programs
==========================

4.8.1 'lz4_decompress' -- Decompress mysqlpump LZ4-Compressed Output
--------------------------------------------------------------------

The 'lz4_decompress' utility decompresses
'mysqlpump' output that was created using LZ4 compression.
'lz4_decompress' was added in MySQL 5.7.10.

Invoke 'lz4_decompress' like this:

     shell> lz4_decompress INPUT_FILE OUTPUT_FILE

Example:

     shell> mysqlpump --compress-output=LZ4 > dump.lz4
     shell> lz4_decompress dump.lz4 dump.txt

To see a help message, invoke 'lz4_decompress'.
with no arguments.

To decompress 'mysqlpump'. ZLIB-compressed output, use
'zlib_decompress'.  See zlib-decompress.

4.8.2 'perror' -- Explain Error Codes
-------------------------------------

For most system errors, MySQL displays, in addition to an internal text
message, the system error code in one of the following styles:

     message ... (errno: #)
     message ... (Errcode: #)

You can find out what the error code means by examining the
documentation for your system or by using the 'perror'.
utility.

'perror' prints a description for a system error code or
for a storage engine (table handler) error code.

Invoke 'perror' like this:

     shell> perror [OPTIONS] ERRORCODE ...

Example:

     shell> perror 13 64
     OS error code  13:  Permission denied
     OS error code  64:  Machine is not on the network

The meaning of system error messages may be dependent on your operating
system.  A given error code may mean different things on different
operating systems.

'perror' supports the following options.

   *
     '--help', '--info', '-I', '-?'

     Display a help message and exit.

   *
     '--ndb'

     Print the error message for an NDB Cluster error code.

     This option is deprecated in NDB 7.6.4 and later, where
     'perror' prints a warning if it is used, and subject to
     removal in a future NDB Cluster release series.  Use the
     'ndb_perror' utility instead.

   *
     '--silent', '-s'

     Silent mode.  Print only the error message.

   *
     '--verbose', '-v'

     Verbose mode.  Print error code and message.  This is the default
     behavior.

   *
     '--version', '-V'

     Display version information and exit.

4.8.3 'replace' -- A String-Replacement Utility
-----------------------------------------------

The 'replace' utility program changes strings in
place in files or on the standard input.

*Note*:

The 'replace' utility is deprecated as of MySQL
5.7.18 and is removed in MySQL 8.0.

Invoke 'replace' in one of the following ways:

     shell> replace FROM TO [FROM TO] ... -- FILE_NAME [FILE_NAME] ...
     shell> replace FROM TO [FROM TO] ... < FILE_NAME

FROM represents a string to look for and TO represents its replacement.
There can be one or more pairs of strings.

Use the '--' option to indicate where the string-replacement list ends
and the file names begin.  In this case, any file named on the command
line is modified in place, so you may want to make a copy of the
original before converting it.  REPLACE prints a message indicating
which of the input files it actually modifies.

If the '--' option is not given, see 'replace' reads
the standard input and writes to the standard output.

'replace' uses a finite state machine to match
longer strings first.  It can be used to swap strings.  For example, the
following command swaps 'a' and 'b' in the given files, 'file1' and
'file2':

     shell> replace a b b a -- file1 file2 ...

'replace' supports the following options.

   * '-?', '-I'

     Display a help message and exit.

   * '-#DEBUG_OPTIONS'

     Enable debugging.

   * '-s'

     Silent mode.  Print less information what the program does.

   * '-v'

     Verbose mode.  Print more information about what the program does.

   * '-V'

     Display version information and exit.

4.8.4 'resolveip' -- Resolve Host name to IP Address or Vice Versa
------------------------------------------------------------------

The 'resolveip' utility resolves host names to IP
addresses and vice versa.

Invoke 'resolveip' like this:

     shell> resolveip [OPTIONS] {HOST_NAME|IP-ADDR} ...

'resolveip' supports the following options.

   *
     '--help', '--info', '-?', '-I'

     Display a help message and exit.

   *
     '--silent', '-s'

     Silent mode.  Produce less output.

   *
     '--version', '-V'

     Display version information and exit.

4.8.5 'zlib_decompress' -- Decompress mysqlpump ZLIB-Compressed Output
----------------------------------------------------------------------

The 'zlib_decompress' utility decompresses
'mysqlpump' output that was created using ZLIB compression.
'zlib_decompress' was added in MySQL 5.7.10.

Invoke 'zlib_decompress' like this:

     shell> zlib_decompress INPUT_FILE OUTPUT_FILE

Example:

     shell> mysqlpump --compress-output=ZLIB > dump.zlib
     shell> zlib_decompress dump.zlib dump.txt

To see a help message, invoke 'zlib_decompress'.
with no arguments.

To decompress 'mysqlpump'. LZ4-compressed output, use
'lz4_decompress'.  See lz4-decompress.

4.9 MySQL Program Environment Variables
=======================================

This section lists environment variables that are used directly or
indirectly by MySQL. Most of these can also be found in other places in
this manual.

Options on the command line take precedence over values specified in
option files and environment variables, and values in option files take
precedence over values in environment variables.  In many cases, it is
preferable to use an option file instead of environment variables to
modify the behavior of MySQL. See option-files.

Variable                      Description

'AUTHENTICATION_LDAP_CLIENT_LOG'Client-side LDAP authentication logging
                              level.

'AUTHENTICATION_PAM_LOG'      PAM authentication plugin debug logging
                              settings.

'CC'                          The name of your C compiler (for running
                              'CMake').

'CXX'                         The name of your C++ compiler (for
                              running 'CMake').

'CC'                          The name of your C compiler (for running
                              'CMake').

'DBI_USER'                    The default user name for Perl DBI.

'DBI_TRACE'                   Trace options for Perl DBI.

'HOME'                        The default path for the 'mysql'
                              history file is
                              '$HOME/.mysql_history'.

'LD_RUN_PATH'                 Used to specify the location of
                              'libmysqlclient.so'.

'LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN'Enable 'mysql_clear_password'
                              authentication plugin; see
                              cleartext-pluggable-authentication.

'LIBMYSQL_PLUGIN_DIR'         Directory in which to look for client
                              plugins.

'LIBMYSQL_PLUGINS'            Client plugins to preload.

'MYSQL_DEBUG'                 Debug trace options when debugging.

'MYSQL_GROUP_SUFFIX'          Option group suffix value (like
                              specifying '--defaults-group-suffix').

'MYSQL_HISTFILE'              The path to the 'mysql'.
                              history file.  If this variable is set,
                              its value overrides the default for
                              '$HOME/.mysql_history'.

'MYSQL_HISTIGNORE'            Patterns specifying statements that
                              'mysql' should not log to
                              '$HOME/.mysql_history', or 'syslog' if
                              '--syslog' is given.

'MYSQL_HOME'                  The path to the directory in which the
                              server-specific 'my.cnf' file resides.

'MYSQL_HOST'                  The default host name used by the
                              'mysql' command-line client.

'MYSQL_OPENSSL_UDF_DH_BITS_THRESHOLD'Maximum key length for
                              'CREATE_DH_PARAMETERS()'.  See
                              enterprise-encryption-usage.

'MYSQL_OPENSSL_UDF_DSA_BITS_THRESHOLD'Maximum DSA key length for
                              'CREATE_ASYMMETRIC_PRIV_KEY()'.  See
                              enterprise-encryption-usage.

'MYSQL_OPENSSL_UDF_RSA_BITS_THRESHOLD'Maximum RSA key length for
                              'CREATE_ASYMMETRIC_PRIV_KEY()'.  See
                              enterprise-encryption-usage.

'MYSQL_PS1'                   The command prompt to use in the
                              'mysql' command-line client.

'MYSQL_PWD'                   The default password when connecting to
                              See 'mysqld'.  Using this is
                              insecure.  See
                              password-security-user.

'MYSQL_TCP_PORT'              The default TCP/IP port number.

'MYSQL_TEST_LOGIN_FILE'       The name of the '.mylogin.cnf' login path
                              file.

'MYSQL_TEST_TRACE_CRASH'      Whether the test protocol trace plugin
                              crashes clients.  See note following
                              table.

'MYSQL_TEST_TRACE_DEBUG'      Whether the test protocol trace plugin
                              produces output.  See note following
                              table.

'MYSQL_UNIX_PORT'             The default Unix socket file name; used
                              for connections to 'localhost'.

'MYSQLX_TCP_PORT'             The X Plugin default TCP/IP port number.

'MYSQLX_UNIX_PORT'            The X Plugin default Unix socket file
                              name; used for connections to
                              'localhost'.

'PATH'                        Used by the shell to find MySQL programs.

'PKG_CONFIG_PATH'             Location of 'mysqlclient.pc' 'pkg-config'
                              file.  See note following table.

'TMPDIR'                      The directory in which temporary files
                              are created.

'TZ'                          This should be set to your local time
                              zone.  See timezone-problems.

'UMASK'                       The user-file creation mode when creating
                              files.  See note following table.

'UMASK_DIR'                   The user-directory creation mode when
                              creating directories.  See note following
                              table.

'USER'                        The default user name on Windows when
                              connecting to 'mysqld'.

For information about the 'mysql' history file, see
mysql-logging.

'MYSQL_TEST_LOGIN_FILE' is the path name of the login path file (the
file created by 'mysql_config_editor').  If
not set, the default value is '%APPDATA%\MySQL\.mylogin.cnf' directory
on Windows and '$HOME/.mylogin.cnf' on non-Windows systems.  See
mysql-config-editor.

The 'MYSQL_TEST_TRACE_DEBUG' and 'MYSQL_TEST_TRACE_CRASH' variables
control the test protocol trace client plugin, if MySQL is built with
that plugin enabled.  For more information, see
test-protocol-trace-plugin.

The default 'UMASK' and 'UMASK_DIR' values are '0640' and '0750',
respectively ('0660' and '0700' prior to MySQL 5.7.6).  MySQL assumes
that the value for 'UMASK' or 'UMASK_DIR' is in octal if it starts with
a zero.  For example, setting 'UMASK=0600' is equivalent to 'UMASK=384'
because 0600 octal is 384 decimal.

The 'UMASK' and 'UMASK_DIR' variables, despite their names, are used as
modes, not masks:

   * If 'UMASK' is set, see 'mysqld' uses '($UMASK | 0600)'
     as the mode for file creation, so that newly created files have a
     mode in the range from 0600 to 0666 (all values octal).

   * If 'UMASK_DIR' is set, see 'mysqld' uses '($UMASK_DIR |
     0700)' as the base mode for directory creation, which then is
     AND-ed with '~(~$UMASK & 0666)', so that newly created directories
     have a mode in the range from 0700 to 0777 (all values octal).  The
     AND operation may remove read and write permissions from the
     directory mode, but not execute permissions.

It may be necessary to set 'PKG_CONFIG_PATH' if you use 'pkg-config' for
building MySQL programs.  See c-api-building-clients-pkg-config.

5 MySQL Server Administration
*****************************

MySQL Server (see 'mysqld') is the main program that does
most of the work in a MySQL installation.  This chapter provides an
overview of MySQL Server and covers general server administration:

   * Server configuration

   * The data directory, particularly the 'mysql' system database

   * The server log files

   * Management of multiple servers on a single machine

For additional information on administrative topics, see also:

   * security

   * backup-and-recovery

   * replication

5.1 The MySQL Server
====================

'mysqld' is the MySQL server.  The following discussion
covers these MySQL server configuration topics:

   * Startup options that the server supports.  You can specify these
     options on the command line, through configuration files, or both.

   * Server system variables.  These variables reflect the current state
     and values of the startup options, some of which can be modified
     while the server is running.

   * Server status variables.  These variables contain counters and
     statistics about runtime operation.

   * How to set the server SQL mode.  This setting modifies certain
     aspects of SQL syntax and semantics, for example for compatibility
     with code from other database systems, or to control the error
     handling for particular situations.

   * Configuring and using IPv6 support.

   * Configuring and using time zone support.

   * Server-side help capabilities.

   * The server shutdown process.  There are performance and reliability
     considerations depending on the type of table (transactional or
     nontransactional) and whether you use replication.

For listings of MySQL server variables and options that have been added,
deprecated, or removed in MySQL 5.7, see
added-deprecated-removed.

*Note*:

Not all storage engines are supported by all MySQL server binaries and
configurations.  To find out how to determine which storage engines your
MySQL server installation supports, see show-engines.

5.1.1 Configuring the Server
----------------------------

The MySQL server, see 'mysqld', has many command options and
system variables that can be set at startup to configure its operation.
To determine the command option and system variable values used by the
server, execute this command:

     shell> mysqld --verbose --help

The command produces a list of all 'mysqld' options and
configurable system variables.  Its output includes the default option
and variable values and looks something like this:

     abort-slave-event-count           0
     allow-suspicious-udfs             FALSE
     archive                           ON
     auto-increment-increment          1
     auto-increment-offset             1
     autocommit                        TRUE
     automatic-sp-privileges           TRUE
     avoid-temporal-upgrade            FALSE
     back-log                          80
     basedir                           /home/jon/bin/mysql-5.7/
     ...
     tmpdir                            /tmp
     transaction-alloc-block-size      8192
     transaction-isolation             REPEATABLE-READ
     transaction-prealloc-size         4096
     transaction-read-only             FALSE
     transaction-write-set-extraction  OFF
     updatable-views-with-limit        YES
     validate-user-plugins             TRUE
     verbose                           TRUE
     wait-timeout                      28800

To see the current system variable values used by the server as it runs,
connect to it and execute this statement:

     mysql> SHOW VARIABLES;

To see some statistical and status indicators for a running server,
execute this statement:

     mysql> SHOW STATUS;

System variable and status information also is available using the
'mysqladmin' command:

     shell> mysqladmin variables
     shell> mysqladmin extended-status

For a full description of all command options, system variables, and
status variables, see these sections:

   * server-options

   * server-system-variables

   * server-status-variables

More detailed monitoring information is available from the Performance
Schema; see performance-schema.

MySQL uses algorithms that are very scalable, so you can usually run
with very little memory.  However, normally better performance results
from giving MySQL more memory.

When tuning a MySQL server, the two most important variables to
configure are 'key_buffer_size' and 'table_open_cache'.  You should
first feel confident that you have these set appropriately before trying
to change any other variables.

The following examples indicate some typical variable values for
different runtime configurations.

   * If you have at least 1-2GB of memory and many tables and want
     maximum performance with a moderate number of clients, use
     something like this:

          shell> mysqld_safe --key_buffer_size=384M --table_open_cache=4000 \
                     --sort_buffer_size=4M --read_buffer_size=1M &

   * If you have only 256MB of memory and only a few tables, but you
     still do a lot of sorting, you can use something like this:

          shell> mysqld_safe --key_buffer_size=64M --sort_buffer_size=1M

     If there are very many simultaneous connections, swapping problems
     may occur unless 'mysqld' has been configured to use
     very little memory for each connection.  See 'mysqld'.
     performs better if you have enough memory for all connections.

   * With little memory and lots of connections, use something like
     this:

          shell> mysqld_safe --key_buffer_size=512K --sort_buffer_size=100K \
                     --read_buffer_size=100K &

     Or even this:

          shell> mysqld_safe --key_buffer_size=512K --sort_buffer_size=16K \
                     --table_open_cache=32 --read_buffer_size=8K \
                     --net_buffer_length=1K &

If you are performing 'GROUP BY' or 'ORDER BY' operations on tables that
are much larger than your available memory, increase the value of
'read_rnd_buffer_size' to speed up the reading of rows following sorting
operations.

If you specify an option on the command line for 'mysqld'.
or 'mysqld_safe', it remains in effect only for that
invocation of the server.  To use the option every time the server runs,
put it in an option file.  See option-files.

5.1.2 Server Configuration Defaults
-----------------------------------

The MySQL server has many operating parameters, which you can change at
server startup using command-line options or configuration files (option
files).  It is also possible to change many parameters at runtime.  For
general instructions on setting parameters at startup or runtime, see
server-options, and server-system-variables.

On Windows, MySQL Installer interacts with the user and creates a file
named 'my.ini' in the base installation directory as the default option
file.  If you install on Windows from a Zip archive, you can copy the
'my-default.ini' template file in the base installation directory to
'my.ini' and use the latter as the default option file.

*Note*:

As of MySQL 5.7.18, 'my-default.ini' is no longer included in or
installed by distribution packages.

*Note*:

On Windows, the '.ini' or '.cnf' option file extension might not be
displayed.

After completing the installation process, you can edit the default
option file at any time to modify the parameters used by the server.
For example, to use a parameter setting in the file that is commented
with a '#' character at the beginning of the line, remove the '#', and
modify the parameter value if necessary.  To disable a setting, either
add a '#' to the beginning of the line or remove it.

For non-Windows platforms, no default option file is created during
either the server installation or the data directory initialization
process.  Create your option file by following the instructions given in
option-files.  Without an option file, the server just starts
with its default settings--see server-configuration-defaults on
how to check those settings.

For additional information about option file format and syntax, see
option-files.

5.1.3 Server Option and Variable Reference
------------------------------------------

The following table provides a list of all the command line options,
server and status variables applicable within 'mysqld'.

The table lists command-line options (Cmd-line), options valid in
configuration files (Option file), server system variables (System Var),
and status variables (Status var) in one unified list, with notification
of where each option/variable is valid.  If a server option set on the
command line or in an option file differs from the name of the
corresponding server system or status variable, the variable name is
noted immediately below the corresponding option.  For status variables,
the scope of the variable is shown (Scope) as either global, session, or
both.  Please see the corresponding sections for details on setting and
using the options and variables.  Where appropriate, a direct link to
further information on the item as available.

For a version of this table that is specific to NDB Cluster, see
mysql-cluster-option-tables.

*Option and Variable Summary*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

abort-slave-event-countYes Yes

Aborted_clients                                    Yes         Global      No

Aborted_connects                                   Yes         Global      No

allow-suspicious-udfsYes   Yes

ansi           Yes         Yes

audit-log      Yes         Yes

audit_log_buffer_sizeYes   Yes         Yes                     Global      No

audit_log_compressionYes   Yes         Yes                     Global      No

audit_log_connection_policyYesYes      Yes                     Global      Yes

audit_log_current_session              Yes                     Both        No

Audit_log_current_size                             Yes         Global      No

audit_log_encryptionYes    Yes         Yes                     Global      No

Audit_log_event_max_drop_size                      Yes         Global      No

Audit_log_events                                   Yes         Global      No

Audit_log_events_filtered                          Yes         Global      No

Audit_log_events_lost                              Yes         Global      No

Audit_log_events_written                           Yes         Global      No

audit_log_exclude_accountsYesYes       Yes                     Global      Yes

audit_log_file Yes         Yes         Yes                     Global      No

audit_log_filter_id                    Yes                     Both        No

audit_log_flush                        Yes                     Global      Yes

audit_log_formatYes        Yes         Yes                     Global      No

audit_log_include_accountsYesYes       Yes                     Global      Yes

audit_log_policyYes        Yes         Yes                     Global      No

audit_log_read_buffer_sizeYesYes       Yes                     Global      No

audit_log_rotate_on_sizeYesYes         Yes                     Global      Yes

audit_log_statement_policyYesYes       Yes                     Global      Yes

audit_log_strategyYes      Yes         Yes                     Global      No

Audit_log_total_size                               Yes         Global      No

Audit_log_write_waits                              Yes         Global      No

authentication_ldap_sasl_auth_method_nameYesYesYes             Global      Yes

authentication_ldap_sasl_bind_base_dnYesYesYes                 Global      Yes

authentication_ldap_sasl_bind_root_dnYesYesYes                 Global      Yes

authentication_ldap_sasl_bind_root_pwdYesYesYes                Global      Yes

authentication_ldap_sasl_ca_pathYesYes Yes                     Global      Yes

authentication_ldap_sasl_group_search_attrYesYesYes            Global      Yes

authentication_ldap_sasl_group_search_filterYesYesYes          Global      Yes

authentication_ldap_sasl_init_pool_sizeYesYesYes               Global      Yes

authentication_ldap_sasl_log_statusYesYesYes                   Global      Yes

authentication_ldap_sasl_max_pool_sizeYesYesYes                Global      Yes

authentication_ldap_sasl_server_hostYesYesYes                  Global      Yes

authentication_ldap_sasl_server_portYesYesYes                  Global      Yes

authentication_ldap_sasl_tlsYesYes     Yes                     Global      Yes

authentication_ldap_sasl_user_search_attrYesYesYes             Global      Yes

authentication_ldap_simple_auth_method_nameYesYesYes           Global      Yes

authentication_ldap_simple_bind_base_dnYesYesYes               Global      Yes

authentication_ldap_simple_bind_root_dnYesYesYes               Global      Yes

authentication_ldap_simple_bind_root_pwdYesYesYes              Global      Yes

authentication_ldap_simple_ca_pathYesYesYes                    Global      Yes

authentication_ldap_simple_group_search_attrYesYesYes          Global      Yes

authentication_ldap_simple_group_search_filterYesYesYes        Global      Yes

authentication_ldap_simple_init_pool_sizeYesYesYes             Global      Yes

authentication_ldap_simple_log_statusYesYesYes                 Global      Yes

authentication_ldap_simple_max_pool_sizeYesYesYes              Global      Yes

authentication_ldap_simple_server_hostYesYesYes                Global      Yes

authentication_ldap_simple_server_portYesYesYes                Global      Yes

authentication_ldap_simple_tlsYesYes   Yes                     Global      Yes

authentication_ldap_simple_user_search_attrYesYesYes           Global      Yes

authentication_windows_log_levelYesYes

authentication_windows_use_principal_nameYesYes

auto_generate_certsYes     Yes         Yes                     Global      No

auto_increment_increment               Yes                     Both        Yes

auto_increment_offset                  Yes                     Both        Yes

autocommit     Yes         Yes         Yes                     Both        Yes

automatic_sp_privileges                Yes                     Global      Yes

avoid_temporal_upgradeYes  Yes         Yes                     Global      Yes

back_log                               Yes                     Global      No

basedir        Yes         Yes         Yes                     Global      No

big-tables     Yes         Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
big_tables

bind-address   Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
bind_address

Binlog_cache_disk_use                              Yes         Global      No

binlog_cache_sizeYes       Yes         Yes                     Global      Yes

Binlog_cache_use                                   Yes         Global      No

binlog-checksumYes         Yes

binlog_checksum                        Yes                     Global      Yes

binlog_direct_non_transactional_updatesYesYesYes               Both        Yes

binlog-do-db   Yes         Yes

binlog_error_actionYes     Yes         Yes                     Global      Yes

binlog-format  Yes         Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
binlog_format

binlog_group_commit_sync_delayYesYes   Yes                     Global      Yes

binlog_group_commit_sync_no_delay_countYesYesYes               Global      Yes

binlog_gtid_simple_recoveryYesYes      Yes                     Global      No

binlog-ignore-dbYes        Yes

binlog_max_flush_queue_time            Yes                     Global      Yes

binlog_order_commits                   Yes                     Global      Yes

binlog-row-event-max-sizeYesYes

binlog_row_imageYes        Yes         Yes                     Both        Yes

binlog-rows-query-log-eventsYesYes

-
_Variable_:
binlog_rows_query_log_events

binlog_rows_query_log_eventsYesYes     Yes                     Both        Yes

Binlog_stmt_cache_disk_use                         Yes         Global      No

binlog_stmt_cache_sizeYes  Yes         Yes                     Global      Yes

Binlog_stmt_cache_use                              Yes         Global      No

binlog_transaction_dependency_history_sizeYesYesYes            Global      Yes

binlog_transaction_dependency_trackingYesYesYes                Global      Yes

binlogging_impossible_modeYesYes       Yes                     Both        Yes

block_encryption_modeYes   Yes         Yes                     Both        Yes

bootstrap      Yes         Yes

bulk_insert_buffer_sizeYes Yes         Yes                     Both        Yes

Bytes_received                                     Yes         Both        No

Bytes_sent                                         Yes         Both        No

character_set_client                   Yes                     Both        Yes

character-set-client-handshakeYesYes

character_set_connection               Yes                     Both        Yes

character_set_database                 Yes                     Both        Yes
(note 1)

character-set-filesystemYesYes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
character_set_filesystem

character_set_results                  Yes                     Both        Yes

character-set-serverYes    Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
character_set_server

character_set_system                   Yes                     Global      No

character-sets-dirYes      Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
character_sets_dir

check_proxy_usersYes       Yes         Yes                     Global      Yes

chroot         Yes         Yes

collation_connection                   Yes                     Both        Yes

collation_database                     Yes                     Both        Yes
(note 1)

collation-serverYes        Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
collation_server

Com_admin_commands                                 Yes         Both        No

Com_alter_db                                       Yes         Both        No

Com_alter_db_upgrade                               Yes         Both        No

Com_alter_event                                    Yes         Both        No

Com_alter_function                                 Yes         Both        No

Com_alter_procedure                                Yes         Both        No

Com_alter_server                                   Yes         Both        No

Com_alter_table                                    Yes         Both        No

Com_alter_tablespace                               Yes         Both        No

Com_alter_user                                     Yes         Both        No

Com_analyze                                        Yes         Both        No

Com_assign_to_keycache                             Yes         Both        No

Com_begin                                          Yes         Both        No

Com_binlog                                         Yes         Both        No

Com_call_procedure                                 Yes         Both        No

Com_change_db                                      Yes         Both        No

Com_change_master                                  Yes         Both        No

Com_change_repl_filter                             Yes         Both        No

Com_check                                          Yes         Both        No

Com_checksum                                       Yes         Both        No

Com_commit                                         Yes         Both        No

Com_create_db                                      Yes         Both        No

Com_create_event                                   Yes         Both        No

Com_create_function                                Yes         Both        No

Com_create_index                                   Yes         Both        No

Com_create_procedure                               Yes         Both        No

Com_create_server                                  Yes         Both        No

Com_create_table                                   Yes         Both        No

Com_create_trigger                                 Yes         Both        No

Com_create_udf                                     Yes         Both        No

Com_create_user                                    Yes         Both        No

Com_create_view                                    Yes         Both        No

Com_dealloc_sql                                    Yes         Both        No

Com_delete                                         Yes         Both        No

Com_delete_multi                                   Yes         Both        No

Com_do                                             Yes         Both        No

Com_drop_db                                        Yes         Both        No

Com_drop_event                                     Yes         Both        No

Com_drop_function                                  Yes         Both        No

Com_drop_index                                     Yes         Both        No

Com_drop_procedure                                 Yes         Both        No

Com_drop_server                                    Yes         Both        No

Com_drop_table                                     Yes         Both        No

Com_drop_trigger                                   Yes         Both        No

Com_drop_user                                      Yes         Both        No

Com_drop_view                                      Yes         Both        No

Com_empty_query                                    Yes         Both        No

Com_execute_sql                                    Yes         Both        No

Com_explain_other                                  Yes         Both        No

Com_flush                                          Yes         Both        No

Com_get_diagnostics                                Yes         Both        No

Com_grant                                          Yes         Both        No

Com_group_replication_start                        Yes         Global      No

Com_group_replication_stop                         Yes         Global      No

Com_ha_close                                       Yes         Both        No

Com_ha_open                                        Yes         Both        No

Com_ha_read                                        Yes         Both        No

Com_help                                           Yes         Both        No

Com_insert                                         Yes         Both        No

Com_insert_select                                  Yes         Both        No

Com_install_plugin                                 Yes         Both        No

Com_kill                                           Yes         Both        No

Com_load                                           Yes         Both        No

Com_lock_tables                                    Yes         Both        No

Com_optimize                                       Yes         Both        No

Com_preload_keys                                   Yes         Both        No

Com_prepare_sql                                    Yes         Both        No

Com_purge                                          Yes         Both        No

Com_purge_before_date                              Yes         Both        No

Com_release_savepoint                              Yes         Both        No

Com_rename_table                                   Yes         Both        No

Com_rename_user                                    Yes         Both        No

Com_repair                                         Yes         Both        No

Com_replace                                        Yes         Both        No

Com_replace_select                                 Yes         Both        No

Com_reset                                          Yes         Both        No

Com_resignal                                       Yes         Both        No

Com_revoke                                         Yes         Both        No

Com_revoke_all                                     Yes         Both        No

Com_rollback                                       Yes         Both        No

Com_rollback_to_savepoint                          Yes         Both        No

Com_savepoint                                      Yes         Both        No

Com_select                                         Yes         Both        No

Com_set_option                                     Yes         Both        No

Com_show_authors                                   Yes         Both        No

Com_show_binlog_events                             Yes         Both        No

Com_show_binlogs                                   Yes         Both        No

Com_show_charsets                                  Yes         Both        No

Com_show_collations                                Yes         Both        No

Com_show_contributors                              Yes         Both        No

Com_show_create_db                                 Yes         Both        No

Com_show_create_event                              Yes         Both        No

Com_show_create_func                               Yes         Both        No

Com_show_create_proc                               Yes         Both        No

Com_show_create_table                              Yes         Both        No

Com_show_create_trigger                            Yes         Both        No

Com_show_create_user                               Yes         Both        No

Com_show_databases                                 Yes         Both        No

Com_show_engine_logs                               Yes         Both        No

Com_show_engine_mutex                              Yes         Both        No

Com_show_engine_status                             Yes         Both        No

Com_show_errors                                    Yes         Both        No

Com_show_events                                    Yes         Both        No

Com_show_fields                                    Yes         Both        No

Com_show_function_code                             Yes         Both        No

Com_show_function_status                           Yes         Both        No

Com_show_grants                                    Yes         Both        No

Com_show_keys                                      Yes         Both        No

Com_show_master_status                             Yes         Both        No

Com_show_ndb_status                                Yes         Both        No

Com_show_new_master                                Yes         Both        No

Com_show_open_tables                               Yes         Both        No

Com_show_plugins                                   Yes         Both        No

Com_show_privileges                                Yes         Both        No

Com_show_procedure_code                            Yes         Both        No

Com_show_procedure_status                          Yes         Both        No

Com_show_processlist                               Yes         Both        No

Com_show_profile                                   Yes         Both        No

Com_show_profiles                                  Yes         Both        No

Com_show_relaylog_events                           Yes         Both        No

Com_show_slave_hosts                               Yes         Both        No

Com_show_slave_status                              Yes         Both        No

Com_show_slave_status_nonblocking                  Yes         Both        No

Com_show_status                                    Yes         Both        No

Com_show_storage_engines                           Yes         Both        No

Com_show_table_status                              Yes         Both        No

Com_show_tables                                    Yes         Both        No

Com_show_triggers                                  Yes         Both        No

Com_show_variables                                 Yes         Both        No

Com_show_warnings                                  Yes         Both        No

Com_shutdown                                       Yes         Both        No

Com_signal                                         Yes         Both        No

Com_slave_start                                    Yes         Both        No

Com_slave_stop                                     Yes         Both        No

Com_stmt_close                                     Yes         Both        No

Com_stmt_execute                                   Yes         Both        No

Com_stmt_fetch                                     Yes         Both        No

Com_stmt_prepare                                   Yes         Both        No

Com_stmt_reprepare                                 Yes         Both        No

Com_stmt_reset                                     Yes         Both        No

Com_stmt_send_long_data                            Yes         Both        No

Com_truncate                                       Yes         Both        No

Com_uninstall_plugin                               Yes         Both        No

Com_unlock_tables                                  Yes         Both        No

Com_update                                         Yes         Both        No

Com_update_multi                                   Yes         Both        No

Com_xa_commit                                      Yes         Both        No

Com_xa_end                                         Yes         Both        No

Com_xa_prepare                                     Yes         Both        No

Com_xa_recover                                     Yes         Both        No

Com_xa_rollback                                    Yes         Both        No

Com_xa_start                                       Yes         Both        No

completion_typeYes         Yes         Yes                     Both        Yes

Compression                                        Yes         Session     No

concurrent_insertYes       Yes         Yes                     Global      Yes

connect_timeoutYes         Yes         Yes                     Global      Yes

Connection_control_delay_generated                 Yes         Global      No

connection_control_failed_connections_thresholdYesYesYes       Global      Yes

connection_control_max_connection_delayYesYesYes               Global      Yes

connection_control_min_connection_delayYesYesYes               Global      Yes

Connection_errors_accept                           Yes         Global      No

Connection_errors_internal                         Yes         Global      No

Connection_errors_max_connections                  Yes         Global      No

Connection_errors_peer_address                     Yes         Global      No

Connection_errors_select                           Yes         Global      No

Connection_errors_tcpwrap                          Yes         Global      No

Connections                                        Yes         Global      No

console        Yes         Yes

core-file      Yes         Yes

core_file                              Yes                     Global      No

Created_tmp_disk_tables                            Yes         Both        No

Created_tmp_files                                  Yes         Global      No

Created_tmp_tables                                 Yes         Both        No

daemon_memcached_enable_binlogYesYes   Yes                     Global      No

daemon_memcached_engine_lib_nameYesYes Yes                     Global      No

daemon_memcached_engine_lib_pathYesYes Yes                     Global      No

daemon_memcached_optionYes Yes         Yes                     Global      No

daemon_memcached_r_batch_sizeYesYes    Yes                     Global      No

daemon_memcached_w_batch_sizeYesYes    Yes                     Global      No

daemonize      Yes         Yes

datadir        Yes         Yes         Yes                     Global      No

date_format                            Yes                     Global      No

datetime_format                        Yes                     Global      No

debug          Yes         Yes         Yes                     Both        Yes

debug_sync                             Yes                     Session     Yes

debug-sync-timeoutYes      Yes

default-authentication-pluginYesYes

default_authentication_pluginYesYes    Yes                     Global      No

default_password_lifetimeYesYes        Yes                     Global      Yes

default-storage-engineYes  Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
default_storage_engine

default-time-zoneYes       Yes

default_tmp_storage_engineYesYes       Yes                     Both        Yes

default_week_formatYes     Yes         Yes                     Both        Yes

defaults-extra-fileYes

defaults-file  Yes

defaults-group-suffixYes

delay-key-writeYes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
delay_key_write

Delayed_errors                                     Yes         Global      No

delayed_insert_limitYes    Yes         Yes                     Global      Yes

Delayed_insert_threads                             Yes         Global      No

delayed_insert_timeoutYes  Yes         Yes                     Global      Yes

delayed_queue_sizeYes      Yes         Yes                     Global      Yes

Delayed_writes                                     Yes         Global      No

des-key-file   Yes         Yes

disable-partition-engine-checkYesYes

disabled_storage_enginesYesYes         Yes                     Global      No

disconnect_on_expired_passwordYesYes   Yes                     Session     No

disconnect-slave-event-countYesYes

div_precision_incrementYes Yes         Yes                     Both        Yes

early-plugin-loadYes       Yes

enable-named-pipeYes       Yes

-
_Variable_:
named_pipe

end_markers_in_json                    Yes                     Both        Yes

enforce-gtid-consistencyYesYes         Yes                     Global      Varies

enforce_gtid_consistencyYesYes         Yes                     Global      Varies

eq_range_index_dive_limit              Yes                     Both        Yes

error_count                            Yes                     Session     No

event-schedulerYes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
event_scheduler

executed-gtids-compression-periodYesYes

-
_Variable_:
executed_gtids_compression_period

executed_gtids_compression_period      Yes                     Global      Yes

exit-info      Yes         Yes

expire_logs_daysYes        Yes         Yes                     Global      Yes

explicit_defaults_for_timestampYesYes  Yes                     Both        Yes

external-lockingYes        Yes

-
_Variable_:
skip_external_locking

external_user                          Yes                     Session     No

See Yes Yes federated.

Firewall_access_denied                             Yes         Global      No

Firewall_access_granted                            Yes         Global      No

Firewall_cached_entries                            Yes         Global      No

flush          Yes         Yes         Yes                     Global      Yes

Flush_commands                                     Yes         Global      No

flush_time     Yes         Yes         Yes                     Global      Yes

foreign_key_checks                     Yes                     Both        Yes

ft_boolean_syntaxYes       Yes         Yes                     Global      Yes

ft_max_word_lenYes         Yes         Yes                     Global      No

ft_min_word_lenYes         Yes         Yes                     Global      No

ft_query_expansion_limitYesYes         Yes                     Global      No

ft_stopword_fileYes        Yes         Yes                     Global      No

gdb            Yes         Yes

general-log    Yes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
general_log

general_log_fileYes        Yes         Yes                     Global      Yes

group_concat_max_lenYes    Yes         Yes                     Both        Yes

group_replication_allow_local_disjoint_gtids_joinYesYesYes     Global      Yes

group_replication_allow_local_lower_version_joinYesYesYes      Global      Yes

group_replication_auto_increment_incrementYesYesYes            Global      Yes

group_replication_bootstrap_groupYesYesYes                     Global      Yes

group_replication_components_stop_timeoutYesYesYes             Global      Yes

group_replication_compression_thresholdYesYesYes               Global      Yes

group_replication_enforce_update_everywhere_checksYesYesYes    Global      Yes

group_replication_flow_control_applier_thresholdYesYesYes      Global      Yes

group_replication_flow_control_certifier_thresholdYesYesYes    Global      Yes

group_replication_flow_control_modeYesYesYes                   Global      Yes

group_replication_force_membersYesYes  Yes                     Global      Yes

group_replication_group_nameYesYes     Yes                     Global      Yes

group_replication_group_seedsYesYes    Yes                     Global      Yes

group_replication_gtid_assignment_block_sizeYesYesYes          Global      Yes

group_replication_ip_whitelistYesYes   Yes                     Global      Yes

group_replication_local_addressYesYes  Yes                     Global      Yes

group_replication_member_weightYesYes  Yes                     Global      Yes

group_replication_poll_spin_loopsYesYesYes                     Global      Yes

group_replication_recovery_complete_atYesYesYes                Global      Yes

group_replication_recovery_reconnect_intervalYesYesYes         Global      Yes

group_replication_recovery_retry_countYesYesYes                Global      Yes

group_replication_recovery_ssl_caYesYesYes                     Global      Yes

group_replication_recovery_ssl_capathYesYesYes                 Global      Yes

group_replication_recovery_ssl_certYesYesYes                   Global      Yes

group_replication_recovery_ssl_cipherYesYesYes                 Global      Yes

group_replication_recovery_ssl_crlYesYesYes                    Global      Yes

group_replication_recovery_ssl_crlpathYesYesYes                Global      Yes

group_replication_recovery_ssl_keyYesYesYes                    Global      Yes

group_replication_recovery_ssl_verify_server_certYesYesYes     Global      Yes

group_replication_recovery_use_sslYesYesYes                    Global      Yes

group_replication_single_primary_modeYesYesYes                 Global      Yes

group_replication_ssl_modeYesYes       Yes                     Global      Yes

group_replication_start_on_bootYesYes  Yes                     Global      Yes

group_replication_transaction_size_limitYesYesYes              Global      Yes

group_replication_unreachable_majority_timeoutYesYesYes        Global      Yes

gtid_executed                          Yes                     Varies      No

gtid-executed-compression-periodYesYes

-
_Variable_:
gtid_executed_compression_period

gtid_executed_compression_period       Yes                     Global      Yes

gtid-mode      Yes         Yes                                 Global      Varies

-                                      Yes                     Global      Varies
_Variable_:
gtid_mode

gtid_mode                              Yes                     Global      Varies

gtid_next                              Yes                     Session     Yes

gtid_owned                             Yes                     Both        No

gtid_purged                            Yes                     Global      Yes

Handler_commit                                     Yes         Both        No

Handler_delete                                     Yes         Both        No

Handler_discover                                   Yes         Both        No

Handler_external_lock                              Yes         Both        No

Handler_mrr_init                                   Yes         Both        No

Handler_prepare                                    Yes         Both        No

Handler_read_first                                 Yes         Both        No

Handler_read_key                                   Yes         Both        No

Handler_read_last                                  Yes         Both        No

Handler_read_next                                  Yes         Both        No

Handler_read_prev                                  Yes         Both        No

Handler_read_rnd                                   Yes         Both        No

Handler_read_rnd_next                              Yes         Both        No

Handler_rollback                                   Yes         Both        No

Handler_savepoint                                  Yes         Both        No

Handler_savepoint_rollback                         Yes         Both        No

Handler_update                                     Yes         Both        No

Handler_write                                      Yes         Both        No

have_compress                          Yes                     Global      No

have_crypt                             Yes                     Global      No

have_dynamic_loading                   Yes                     Global      No

have_geometry                          Yes                     Global      No

have_openssl                           Yes                     Global      No

have_profiling                         Yes                     Global      No

have_query_cache                       Yes                     Global      No

have_rtree_keys                        Yes                     Global      No

have_ssl                               Yes                     Global      No

have_statement_timeout                 Yes                     Global      No

have_symlink                           Yes                     Global      No

help           Yes         Yes

host_cache_size                        Yes                     Global      Yes

hostname                               Yes                     Global      No

identity                               Yes                     Session     Yes

ignore-builtin-innodbYes   Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ignore_builtin_innodb

ignore-db-dir  Yes         Yes

ignore_db_dirs                         Yes                     Global      No

init_connect   Yes         Yes         Yes                     Global      Yes

init-file      Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
init_file

init_slave     Yes         Yes         Yes                     Global      Yes

initialize     Yes         Yes

initialize-insecureYes     Yes

innodb         Yes         Yes

innodb_adaptive_flushingYesYes         Yes                     Global      Yes

innodb_adaptive_flushing_lwmYesYes     Yes                     Global      Yes

innodb_adaptive_hash_indexYesYes       Yes                     Global      Yes

innodb_adaptive_hash_index_partsYesYes Yes                     Global      No

innodb_adaptive_max_sleep_delayYesYes  Yes                     Global      Yes

innodb_additional_mem_pool_sizeYesYes  Yes                     Global      No

innodb_api_bk_commit_intervalYesYes    Yes                     Global      Yes

innodb_api_disable_rowlockYesYes       Yes                     Global      No

innodb_api_enable_binlogYesYes         Yes                     Global      No

innodb_api_enable_mdlYes   Yes         Yes                     Global      No

innodb_api_trx_levelYes    Yes         Yes                     Global      Yes

innodb_autoextend_incrementYesYes      Yes                     Global      Yes

innodb_autoinc_lock_modeYesYes         Yes                     Global      No

Innodb_available_undo_logs                         Yes         Global      No

innodb_background_drop_list_emptyYesYesYes                     Global      Yes

Innodb_buffer_pool_bytes_data                      Yes         Global      No

Innodb_buffer_pool_bytes_dirty                     Yes         Global      No

innodb_buffer_pool_chunk_sizeYesYes    Yes                     Global      No

innodb_buffer_pool_dump_at_shutdownYesYesYes                   Global      Yes

innodb_buffer_pool_dump_nowYesYes      Yes                     Global      Yes

innodb_buffer_pool_dump_pctYesYes      Yes                     Global      Yes

Innodb_buffer_pool_dump_status                     Yes         Global      No

innodb_buffer_pool_filenameYesYes      Yes                     Global      Yes

innodb_buffer_pool_instancesYesYes     Yes                     Global      No

innodb_buffer_pool_load_abortYesYes    Yes                     Global      Yes

innodb_buffer_pool_load_at_startupYesYesYes                    Global      No

innodb_buffer_pool_load_nowYesYes      Yes                     Global      Yes

Innodb_buffer_pool_load_status                     Yes         Global      No

Innodb_buffer_pool_pages_data                      Yes         Global      No

Innodb_buffer_pool_pages_dirty                     Yes         Global      No

Innodb_buffer_pool_pages_flushed                   Yes         Global      No

Innodb_buffer_pool_pages_free                      Yes         Global      No

Innodb_buffer_pool_pages_latched                   Yes         Global      No

Innodb_buffer_pool_pages_misc                      Yes         Global      No

Innodb_buffer_pool_pages_total                     Yes         Global      No

Innodb_buffer_pool_read_ahead                      Yes         Global      No

Innodb_buffer_pool_read_ahead_evicted              Yes         Global      No

Innodb_buffer_pool_read_ahead_rnd                  Yes         Global      No

Innodb_buffer_pool_read_requests                   Yes         Global      No

Innodb_buffer_pool_reads                           Yes         Global      No

Innodb_buffer_pool_resize_status                   Yes         Global      No

innodb_buffer_pool_sizeYes Yes         Yes                     Global      Varies

Innodb_buffer_pool_wait_free                       Yes         Global      No

Innodb_buffer_pool_write_requests                  Yes         Global      No

innodb_change_buffer_max_sizeYesYes    Yes                     Global      Yes

innodb_change_bufferingYes Yes         Yes                     Global      Yes

innodb_change_buffering_debugYesYes    Yes                     Global      Yes

innodb_checksum_algorithmYesYes        Yes                     Global      Yes

innodb_checksumsYes        Yes         Yes                     Global      No

innodb_cmp_per_index_enabledYesYes     Yes                     Global      Yes

innodb_commit_concurrencyYesYes        Yes                     Global      Yes

innodb_compress_debugYes   Yes         Yes                     Global      Yes

innodb_compression_failure_threshold_pctYesYesYes              Global      Yes

innodb_compression_levelYesYes         Yes                     Global      Yes

innodb_compression_pad_pct_maxYesYes   Yes                     Global      Yes

innodb_concurrency_ticketsYesYes       Yes                     Global      Yes

innodb_data_file_pathYes   Yes         Yes                     Global      No

Innodb_data_fsyncs                                 Yes         Global      No

innodb_data_home_dirYes    Yes         Yes                     Global      No

Innodb_data_pending_fsyncs                         Yes         Global      No

Innodb_data_pending_reads                          Yes         Global      No

Innodb_data_pending_writes                         Yes         Global      No

Innodb_data_read                                   Yes         Global      No

Innodb_data_reads                                  Yes         Global      No

Innodb_data_writes                                 Yes         Global      No

Innodb_data_written                                Yes         Global      No

Innodb_dblwr_pages_written                         Yes         Global      No

Innodb_dblwr_writes                                Yes         Global      No

innodb_deadlock_detectYes  Yes         Yes                     Global      Yes

innodb_default_row_formatYesYes        Yes                     Global      Yes

innodb_disable_resize_buffer_pool_debugYesYesYes               Global      Yes

innodb_disable_sort_file_cacheYesYes   Yes                     Global      Yes

innodb_doublewriteYes      Yes         Yes                     Global      No

innodb_fast_shutdownYes    Yes         Yes                     Global      Yes

innodb_fil_make_page_dirty_debugYesYes Yes                     Global      Yes

innodb_file_formatYes      Yes         Yes                     Global      Yes

innodb_file_format_checkYesYes         Yes                     Global      No

innodb_file_format_maxYes  Yes         Yes                     Global      Yes

innodb_file_per_tableYes   Yes         Yes                     Global      Yes

innodb_fill_factorYes      Yes         Yes                     Global      Yes

innodb_flush_log_at_timeout            Yes                     Global      Yes

innodb_flush_log_at_trx_commitYesYes   Yes                     Global      Yes

innodb_flush_methodYes     Yes         Yes                     Global      No

innodb_flush_neighborsYes  Yes         Yes                     Global      Yes

innodb_flush_syncYes       Yes         Yes                     Global      Yes

innodb_flushing_avg_loopsYesYes        Yes                     Global      Yes

innodb_force_load_corruptedYesYes      Yes                     Global      No

innodb_force_recoveryYes   Yes         Yes                     Global      No

innodb_ft_aux_tableYes     Yes         Yes                     Global      Yes

innodb_ft_cache_sizeYes    Yes         Yes                     Global      No

innodb_ft_enable_diag_printYesYes      Yes                     Global      Yes

innodb_ft_enable_stopwordYesYes        Yes                     Global      Yes

innodb_ft_max_token_sizeYesYes         Yes                     Global      No

innodb_ft_min_token_sizeYesYes         Yes                     Global      No

innodb_ft_num_word_optimizeYesYes      Yes                     Global      Yes

innodb_ft_result_cache_limitYesYes     Yes                     Global      Yes

innodb_ft_server_stopword_tableYesYes  Yes                     Global      Yes

innodb_ft_sort_pll_degreeYesYes        Yes                     Global      No

innodb_ft_total_cache_sizeYesYes       Yes                     Global      No

innodb_ft_user_stopword_tableYesYes    Yes                     Both        Yes

Innodb_have_atomic_builtins                        Yes         Global      No

innodb_io_capacityYes      Yes         Yes                     Global      Yes

innodb_io_capacity_maxYes  Yes         Yes                     Global      Yes

innodb_large_prefixYes     Yes         Yes                     Global      Yes

innodb_limit_optimistic_insert_debugYesYesYes                  Global      Yes

innodb_lock_wait_timeoutYesYes         Yes                     Both        Yes

innodb_locks_unsafe_for_binlogYesYes   Yes                     Global      No

innodb_log_buffer_sizeYes  Yes         Yes                     Global      No

innodb_log_checksum_algorithmYesYes    Yes                     Global      Yes

innodb_log_checksumsYes    Yes         Yes                     Global      Yes

innodb_log_compressed_pagesYesYes      Yes                     Global      Yes

innodb_log_file_sizeYes    Yes         Yes                     Global      No

innodb_log_files_in_groupYesYes        Yes                     Global      No

innodb_log_group_home_dirYesYes        Yes                     Global      No

Innodb_log_waits                                   Yes         Global      No

innodb_log_write_ahead_sizeYesYes      Yes                     Global      Yes

Innodb_log_write_requests                          Yes         Global      No

Innodb_log_writes                                  Yes         Global      No

innodb_lru_scan_depthYes   Yes         Yes                     Global      Yes

innodb_max_dirty_pages_pctYesYes       Yes                     Global      Yes

innodb_max_dirty_pages_pct_lwmYesYes   Yes                     Global      Yes

innodb_max_purge_lagYes    Yes         Yes                     Global      Yes

innodb_max_purge_lag_delayYesYes       Yes                     Global      Yes

innodb_max_undo_log_sizeYesYes         Yes                     Global      Yes

innodb_merge_threshold_set_all_debugYesYesYes                  Global      Yes

innodb_monitor_disableYes  Yes         Yes                     Global      Yes

innodb_monitor_enableYes   Yes         Yes                     Global      Yes

innodb_monitor_resetYes    Yes         Yes                     Global      Yes

innodb_monitor_reset_allYesYes         Yes                     Global      Yes

Innodb_num_open_files                              Yes         Global      No

innodb_numa_interleaveYes  Yes         Yes                     Global      No

innodb_old_blocks_pctYes   Yes         Yes                     Global      Yes

innodb_old_blocks_timeYes  Yes         Yes                     Global      Yes

innodb_online_alter_log_max_sizeYesYes Yes                     Global      Yes

innodb_open_filesYes       Yes         Yes                     Global      No

innodb_optimize_fulltext_onlyYesYes    Yes                     Global      Yes

innodb_optimize_point_storageYesYes    Yes                     Session     Yes

Innodb_os_log_fsyncs                               Yes         Global      No

Innodb_os_log_pending_fsyncs                       Yes         Global      No

Innodb_os_log_pending_writes                       Yes         Global      No

Innodb_os_log_written                              Yes         Global      No

innodb_page_cleanersYes    Yes         Yes                     Global      No

Innodb_page_size                                   Yes         Global      No

innodb_page_sizeYes        Yes         Yes                     Global      No

Innodb_pages_created                               Yes         Global      No

Innodb_pages_read                                  Yes         Global      No

Innodb_pages_written                               Yes         Global      No

innodb_print_all_deadlocksYesYes       Yes                     Global      Yes

innodb_purge_batch_sizeYes Yes         Yes                     Global      Yes

innodb_purge_rseg_truncate_frequencyYesYesYes                  Global      Yes

innodb_purge_threadsYes    Yes         Yes                     Global      No

innodb_random_read_aheadYesYes         Yes                     Global      Yes

innodb_read_ahead_thresholdYesYes      Yes                     Global      Yes

innodb_read_io_threadsYes  Yes         Yes                     Global      No

innodb_read_onlyYes        Yes         Yes                     Global      No

innodb_replication_delayYesYes         Yes                     Global      Yes

innodb_rollback_on_timeoutYesYes       Yes                     Global      No

innodb_rollback_segmentsYesYes         Yes                     Global      Yes

Innodb_row_lock_current_waits                      Yes         Global      No

Innodb_row_lock_time                               Yes         Global      No

Innodb_row_lock_time_avg                           Yes         Global      No

Innodb_row_lock_time_max                           Yes         Global      No

Innodb_row_lock_waits                              Yes         Global      No

Innodb_rows_deleted                                Yes         Global      No

Innodb_rows_inserted                               Yes         Global      No

Innodb_rows_read                                   Yes         Global      No

Innodb_rows_updated                                Yes         Global      No

innodb_saved_page_number_debugYesYes   Yes                     Global      Yes

innodb_sort_buffer_sizeYes Yes         Yes                     Global      No

innodb_spin_wait_delayYes  Yes         Yes                     Global      Yes

innodb_stats_auto_recalcYesYes         Yes                     Global      Yes

innodb_stats_include_delete_markedYesYesYes                    Global      Yes

innodb_stats_methodYes     Yes         Yes                     Global      Yes

innodb_stats_on_metadataYesYes         Yes                     Global      Yes

innodb_stats_persistentYes Yes         Yes                     Global      Yes

innodb_stats_persistent_sample_pagesYesYesYes                  Global      Yes

innodb_stats_sample_pagesYesYes        Yes                     Global      Yes

innodb_stats_transient_sample_pagesYesYesYes                   Global      Yes

innodb-status-fileYes      Yes

innodb_status_outputYes    Yes         Yes                     Global      Yes

innodb_status_output_locksYesYes       Yes                     Global      Yes

innodb_strict_modeYes      Yes         Yes                     Both        Yes

innodb_support_xaYes       Yes         Yes                     Both        Yes

innodb_sync_array_sizeYes  Yes         Yes                     Global      No

innodb_sync_debugYes       Yes         Yes                     Global      No

innodb_sync_spin_loopsYes  Yes         Yes                     Global      Yes

innodb_table_locksYes      Yes         Yes                     Both        Yes

innodb_temp_data_file_pathYesYes       Yes                     Global      No

innodb_thread_concurrencyYesYes        Yes                     Global      Yes

innodb_thread_sleep_delayYesYes        Yes                     Global      Yes

innodb_tmpdir  Yes         Yes         Yes                     Both        Yes

Innodb_truncated_status_writes                     Yes         Global      No

innodb_trx_purge_view_update_only_debugYesYesYes               Global      Yes

innodb_trx_rseg_n_slots_debugYesYes    Yes                     Global      Yes

innodb_undo_directoryYes   Yes         Yes                     Global      No

innodb_undo_log_truncateYesYes         Yes                     Global      Yes

innodb_undo_logsYes        Yes         Yes                     Global      Yes

innodb_undo_tablespacesYes Yes         Yes                     Global      No

innodb_use_native_aioYes   Yes         Yes                     Global      No

innodb_use_sys_mallocYes   Yes         Yes                     Global      No

innodb_version                         Yes                     Global      No

innodb_write_io_threadsYes Yes         Yes                     Global      No

insert_id                              Yes                     Session     Yes

install        Yes

install-manual Yes

interactive_timeoutYes     Yes         Yes                     Both        Yes

internal_tmp_disk_storage_engineYesYes Yes                     Global      Yes

join_buffer_sizeYes        Yes         Yes                     Both        Yes

keep_files_on_createYes    Yes         Yes                     Both        Yes

Key_blocks_not_flushed                             Yes         Global      No

Key_blocks_unused                                  Yes         Global      No

Key_blocks_used                                    Yes         Global      No

key_buffer_sizeYes         Yes         Yes                     Global      Yes

key_cache_age_thresholdYes Yes         Yes                     Global      Yes

key_cache_block_sizeYes    Yes         Yes                     Global      Yes

key_cache_division_limitYesYes         Yes                     Global      Yes

Key_read_requests                                  Yes         Global      No

Key_reads                                          Yes         Global      No

Key_write_requests                                 Yes         Global      No

Key_writes                                         Yes         Global      No

keyring_aws_cmk_idYes      Yes         Yes                     Global      Yes

keyring_aws_conf_fileYes   Yes         Yes                     Global      No

keyring_aws_data_fileYes   Yes         Yes                     Global      No

keyring_aws_regionYes      Yes         Yes                     Global      Yes

keyring_encrypted_file_dataYesYes      Yes                     Global      Yes

keyring_encrypted_file_passwordYesYes  Yes                     Global      Yes

keyring_file_dataYes       Yes         Yes                     Global      Yes

keyring-migration-destinationYesYes

keyring-migration-hostYes  Yes

keyring-migration-passwordYesYes

keyring-migration-portYes  Yes

keyring-migration-socketYesYes

keyring-migration-sourceYesYes

keyring-migration-userYes  Yes

keyring_okv_conf_dirYes    Yes         Yes                     Global      Yes

keyring_operations                     Yes                     Global      Yes

language       Yes         Yes         Yes                     Global      No

large_files_support                    Yes                     Global      No

large_page_size                        Yes                     Global      No

large-pages    Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
large_pages

last_insert_id                         Yes                     Session     Yes

Last_query_cost                                    Yes         Session     No

Last_query_partial_plans                           Yes         Session     No

lc-messages    Yes         Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
lc_messages

lc-messages-dirYes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
lc_messages_dir

lc_time_names                          Yes                     Both        Yes

license                                Yes                     Global      No

local_infile                           Yes                     Global      Yes

local-service  Yes

lock_wait_timeoutYes       Yes         Yes                     Both        Yes

Locked_connects                                    Yes         Global      No

locked_in_memory                       Yes                     Global      No

log_backward_compatible_user_definitionsYesYesYes              Global      Yes

log-bin        Yes         Yes         Yes                     Global      No

log_bin                                Yes                     Global      No

log_bin_basename                       Yes                     Global      No

log-bin-index  Yes         Yes

log_bin_index                          Yes                     Global      No

log-bin-trust-function-creatorsYesYes                          Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
log_bin_trust_function_creators

log-bin-use-v1-row-eventsYesYes                                Global      No

-                                      Yes                     Global      No
_Variable_:
log_bin_use_v1_row_events

log_bin_use_v1_row_eventsYesYes        Yes                     Global      No

log_builtin_as_identified_by_passwordYesYesYes                 Global      Yes

log-error      Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
log_error

log_error_verbosityYes     Yes         Yes                     Global      Yes

log-isam       Yes         Yes

log-output     Yes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
log_output

log-queries-not-using-indexesYesYes                            Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
log_queries_not_using_indexes

log-raw        Yes         Yes

log-short-formatYes        Yes

log-slave-updatesYes       Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
log_slave_updates

log_slave_updatesYes       Yes         Yes                     Global      No

log-slow-admin-statementsYesYes

log_slow_admin_statements              Yes                     Global      Yes

log-slow-slave-statementsYesYes

log_slow_slave_statements              Yes                     Global      Yes

log_statements_unsafe_for_binlog       Yes                     Global      Yes

log_syslog     Yes         Yes         Yes                     Global      Yes

log_syslog_facilityYes     Yes         Yes                     Global      Yes

log_syslog_include_pidYes  Yes         Yes                     Global      Yes

log_syslog_tag Yes         Yes         Yes                     Global      Yes

log-tc         Yes         Yes

log-tc-size    Yes         Yes

log_throttle_queries_not_using_indexes Yes                     Global      Yes

log_timestamps Yes         Yes         Yes                     Global      Yes

log-warnings   Yes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
log_warnings

long_query_timeYes         Yes         Yes                     Both        Yes

low-priority-updatesYes    Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
low_priority_updates

lower_case_file_system                 Yes                     Global      No

lower_case_table_namesYes  Yes         Yes                     Global      No

master-info-fileYes        Yes

master-info-repositoryYes  Yes

-
_Variable_:
master_info_repository

master_info_repositoryYes  Yes         Yes                     Global      Yes

master-retry-countYes      Yes

master-verify-checksumYes  Yes

-
_Variable_:
master_verify_checksum

master_verify_checksum                 Yes                     Global      Yes

max_allowed_packetYes      Yes         Yes                     Both        Yes

max_binlog_cache_sizeYes   Yes         Yes                     Global      Yes

max-binlog-dump-eventsYes  Yes

max_binlog_sizeYes         Yes         Yes                     Global      Yes

max_binlog_stmt_cache_sizeYesYes       Yes                     Global      Yes

max_connect_errorsYes      Yes         Yes                     Global      Yes

max_connectionsYes         Yes         Yes                     Global      Yes

max_delayed_threadsYes     Yes         Yes                     Both        Yes

max_digest_lengthYes       Yes         Yes                     Global      No

max_error_countYes         Yes         Yes                     Both        Yes

max_execution_timeYes      Yes         Yes                     Both        Yes

Max_execution_time_exceeded                        Yes         Both        No

Max_execution_time_set                             Yes         Both        No

Max_execution_time_set_failed                      Yes         Both        No

max_heap_table_sizeYes     Yes         Yes                     Both        Yes

max_insert_delayed_threads             Yes                     Both        Yes

max_join_size  Yes         Yes         Yes                     Both        Yes

max_length_for_sort_dataYesYes         Yes                     Both        Yes

max_points_in_geometryYes  Yes         Yes                     Both        Yes

max_prepared_stmt_countYes Yes         Yes                     Global      Yes

max_relay_log_sizeYes      Yes         Yes                     Global      Yes

max_seeks_for_keyYes       Yes         Yes                     Both        Yes

max_sort_lengthYes         Yes         Yes                     Both        Yes

max_sp_recursion_depthYes  Yes         Yes                     Both        Yes

max_statement_time                     Yes                     Both        Yes

Max_statement_time_exceeded                        Yes         Both        No

Max_statement_time_set                             Yes         Both        No

Max_statement_time_set_failed                      Yes         Both        No

max_tmp_tables                         Yes                     Both        Yes

Max_used_connections                               Yes         Global      No

Max_used_connections_time                          Yes         Global      No

max_user_connectionsYes    Yes         Yes                     Both        Yes

max_write_lock_countYes    Yes         Yes                     Global      Yes

mecab_charset                                      Yes         Global      No

mecab_rc_file  Yes         Yes         Yes                     Global      No

memlock        Yes         Yes

-
_Variable_:
locked_in_memory

metadata_locks_cache_size              Yes                     Global      No

metadata_locks_hash_instances          Yes                     Global      No

min-examined-row-limitYes  Yes         Yes                     Both        Yes

multi_range_countYes       Yes         Yes                     Both        Yes

myisam-block-sizeYes       Yes

myisam_data_pointer_sizeYesYes         Yes                     Global      Yes

myisam_max_sort_file_sizeYesYes        Yes                     Global      Yes

myisam_mmap_sizeYes        Yes         Yes                     Global      No

myisam-recover-optionsYes  Yes

-
_Variable_:
myisam_recover_options

myisam_recover_options                 Yes                     Global      No

myisam_repair_threadsYes   Yes         Yes                     Both        Yes

myisam_sort_buffer_sizeYes Yes         Yes                     Both        Yes

myisam_stats_methodYes     Yes         Yes                     Both        Yes

myisam_use_mmapYes         Yes         Yes                     Global      Yes

mysql_firewall_modeYes     Yes         Yes                     Global      Yes

mysql_firewall_traceYes    Yes         Yes                     Global      Yes

mysql_native_password_proxy_usersYesYesYes                     Global      Yes

Mysqlx_aborted_clients                             Yes         Global      No

Mysqlx_address                                     Yes         Global      No

mysqlx-bind-addressYes     Yes         Yes                     Global      No

mysqlx_bind_addressYes     Yes         Yes                     Global      No

Mysqlx_bytes_received                              Yes         Both        No

Mysqlx_bytes_sent                                  Yes         Both        No

mysqlx-connect-timeoutYes  Yes         Yes                     Global      Yes

mysqlx_connect_timeoutYes  Yes         Yes                     Global      Yes

Mysqlx_connection_accept_errors                    Yes         Both        No

Mysqlx_connection_errors                           Yes         Both        No

Mysqlx_connections_accepted                        Yes         Global      No

Mysqlx_connections_closed                          Yes         Global      No

Mysqlx_connections_rejected                        Yes         Global      No

Mysqlx_crud_create_view                            Yes         Both        No

Mysqlx_crud_delete                                 Yes         Both        No

Mysqlx_crud_drop_view                              Yes         Both        No

Mysqlx_crud_find                                   Yes         Both        No

Mysqlx_crud_insert                                 Yes         Both        No

Mysqlx_crud_modify_view                            Yes         Both        No

Mysqlx_crud_update                                 Yes         Both        No

Mysqlx_errors_sent                                 Yes         Both        No

Mysqlx_errors_unknown_message_type                 Yes         Both        No

Mysqlx_expect_close                                Yes         Both        No

Mysqlx_expect_open                                 Yes         Both        No

mysqlx-idle-worker-thread-timeoutYesYesYes                     Global      Yes

mysqlx_idle_worker_thread_timeoutYesYesYes                     Global      Yes

Mysqlx_init_error                                  Yes         Both        No

mysqlx-max-allowed-packetYesYes        Yes                     Global      Yes

mysqlx_max_allowed_packetYesYes        Yes                     Global      Yes

mysqlx-max-connectionsYes  Yes         Yes                     Global      Yes

mysqlx_max_connectionsYes  Yes         Yes                     Global      Yes

mysqlx-min-worker-threadsYesYes        Yes                     Global      Yes

mysqlx_min_worker_threadsYesYes        Yes                     Global      Yes

Mysqlx_notice_other_sent                           Yes         Both        No

Mysqlx_notice_warning_sent                         Yes         Both        No

Mysqlx_port                                        Yes         Global      No

mysqlx-port    Yes         Yes         Yes                     Global      No

mysqlx_port    Yes         Yes         Yes                     Global      No

mysqlx-port-open-timeoutYesYes         Yes                     Global      No

mysqlx_port_open_timeoutYesYes         Yes                     Global      No

Mysqlx_rows_sent                                   Yes         Both        No

Mysqlx_sessions                                    Yes         Global      No

Mysqlx_sessions_accepted                           Yes         Global      No

Mysqlx_sessions_closed                             Yes         Global      No

Mysqlx_sessions_fatal_error                        Yes         Global      No

Mysqlx_sessions_killed                             Yes         Global      No

Mysqlx_sessions_rejected                           Yes         Global      No

Mysqlx_socket                                      Yes         Global      No

mysqlx-socket  Yes         Yes         Yes                     Global      No

mysqlx_socket  Yes         Yes         Yes                     Global      No

mysqlx-ssl     Yes         Yes         Yes                     Global      No

Mysqlx_ssl_accept_renegotiates                     Yes         Global      No

Mysqlx_ssl_accepts                                 Yes         Global      No

Mysqlx_ssl_active                                  Yes         Both        No

mysqlx-ssl-ca  Yes         Yes         Yes                     Global      No

mysqlx-ssl-capathYes       Yes         Yes                     Global      No

mysqlx-ssl-certYes         Yes         Yes                     Global      No

Mysqlx_ssl_cipher                                  Yes         Both        No

mysqlx-ssl-cipherYes       Yes

Mysqlx_ssl_cipher_list                             Yes         Both        No

mysqlx-ssl-crl Yes         Yes         Yes                     Global      No

mysqlx-ssl-crlpathYes      Yes         Yes                     Global      No

Mysqlx_ssl_ctx_verify_depth                        Yes         Both        No

Mysqlx_ssl_ctx_verify_mode                         Yes         Both        No

Mysqlx_ssl_finished_accepts                        Yes         Global      No

mysqlx-ssl-key Yes         Yes         Yes                     Global      No

Mysqlx_ssl_server_not_after                        Yes         Global      No

Mysqlx_ssl_server_not_before                       Yes         Global      No

Mysqlx_ssl_verify_depth                            Yes         Global      No

Mysqlx_ssl_verify_mode                             Yes         Global      No

Mysqlx_ssl_version                                 Yes         Both        No

Mysqlx_stmt_create_collection                      Yes         Both        No

Mysqlx_stmt_create_collection_index                Yes         Both        No

Mysqlx_stmt_disable_notices                        Yes         Both        No

Mysqlx_stmt_drop_collection                        Yes         Both        No

Mysqlx_stmt_drop_collection_index                  Yes         Both        No

Mysqlx_stmt_enable_notices                         Yes         Both        No

Mysqlx_stmt_ensure_collection                      Yes         Both        No

Mysqlx_stmt_execute_mysqlx                         Yes         Both        No

Mysqlx_stmt_execute_sql                            Yes         Both        No

Mysqlx_stmt_execute_xplugin                        Yes         Both        No

Mysqlx_stmt_kill_client                            Yes         Both        No

Mysqlx_stmt_list_clients                           Yes         Both        No

Mysqlx_stmt_list_notices                           Yes         Both        No

Mysqlx_stmt_list_objects                           Yes         Both        No

Mysqlx_stmt_ping                                   Yes         Both        No

Mysqlx_worker_threads                              Yes         Global      No

Mysqlx_worker_threads_active                       Yes         Global      No

named_pipe                             Yes                     Global      No

ndb-allow-copying-alter-tableYesYes    Yes                     Both        Yes

Ndb_api_bytes_received_count                       Yes         Global      No

Ndb_api_bytes_received_count_session               Yes         Session     No

Ndb_api_bytes_received_count_slave                 Yes         Global      No

Ndb_api_bytes_sent_count                           Yes         Global      No

Ndb_api_bytes_sent_count_slave                     Yes         Global      No

Ndb_api_event_bytes_count_injector                 Yes         Global      No

Ndb_api_event_data_count_injector                  Yes         Global      No

Ndb_api_event_nondata_count_injector               Yes         Global      No

Ndb_api_pk_op_count                                Yes         Global      No

Ndb_api_pk_op_count_session                        Yes         Session     No

Ndb_api_pk_op_count_slave                          Yes         Global      No

Ndb_api_pruned_scan_count                          Yes         Global      No

Ndb_api_pruned_scan_count_session                  Yes         Session     No

Ndb_api_range_scan_count_slave                     Yes         Global      No

Ndb_api_read_row_count                             Yes         Global      No

Ndb_api_read_row_count_session                     Yes         Session     No

Ndb_api_scan_batch_count_slave                     Yes         Global      No

Ndb_api_table_scan_count                           Yes         Global      No

Ndb_api_table_scan_count_session                   Yes         Session     No

Ndb_api_trans_abort_count                          Yes         Global      No

Ndb_api_trans_abort_count_session                  Yes         Session     No

Ndb_api_trans_abort_count_slave                    Yes         Global      No

Ndb_api_trans_close_count                          Yes         Global      No

Ndb_api_trans_close_count_session                  Yes         Session     No

Ndb_api_trans_close_count_slave                    Yes         Global      No

Ndb_api_trans_commit_count                         Yes         Global      No

Ndb_api_trans_commit_count_session                 Yes         Session     No

Ndb_api_trans_commit_count_slave                   Yes         Global      No

Ndb_api_trans_local_read_row_count_slave           Yes         Global      No

Ndb_api_trans_start_count                          Yes         Global      No

Ndb_api_trans_start_count_session                  Yes         Session     No

Ndb_api_trans_start_count_slave                    Yes         Global      No

Ndb_api_uk_op_count                                Yes         Global      No

Ndb_api_uk_op_count_slave                          Yes         Global      No

Ndb_api_wait_exec_complete_count                   Yes         Global      No

Ndb_api_wait_exec_complete_count_session           Yes         Session     No

Ndb_api_wait_exec_complete_count_slave             Yes         Global      No

Ndb_api_wait_meta_request_count                    Yes         Global      No

Ndb_api_wait_meta_request_count_session            Yes         Session     No

Ndb_api_wait_nanos_count                           Yes         Global      No

Ndb_api_wait_nanos_count_session                   Yes         Session     No

Ndb_api_wait_nanos_count_slave                     Yes         Global      No

Ndb_api_wait_scan_result_count                     Yes         Global      No

Ndb_api_wait_scan_result_count_session             Yes         Session     No

Ndb_api_wait_scan_result_count_slave               Yes         Global      No

ndb_autoincrement_prefetch_szYesYes    Yes                     Both        Yes

ndb-batch-size Yes         Yes         Yes                     Global      No

ndb-blob-read-batch-bytesYesYes        Yes                     Both        Yes

ndb-blob-write-batch-bytesYesYes       Yes                     Both        Yes

ndb_cache_check_timeYes    Yes         Yes                     Global      Yes

ndb_clear_apply_statusYes              Yes                     Global      Yes

ndb-cluster-connection-poolYesYes      Yes                     Global      No

ndb-cluster-connection-pool-nodeidsYesYesYes                   Global      No

Ndb_cluster_node_id                                Yes         Both        No

Ndb_config_from_host                               Yes         Both        No

Ndb_config_from_port                               Yes         Both        No

Ndb_conflict_fn_epoch_trans                        Yes         Global      No

Ndb_conflict_fn_max                                Yes         Global      No

Ndb_conflict_fn_old                                Yes         Global      No

Ndb_conflict_trans_detect_iter_count               Yes         Global      No

Ndb_conflict_trans_row_reject_count                Yes         Global      No

ndb-connectstringYes       Yes

ndb_data_node_neighbourYes Yes         Yes                     Global      Yes

ndb-default-column-formatYesYes                                Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
ndb_default_column_format

ndb_default_column_formatYesYes        Yes                     Global      Yes

ndb-deferred-constraintsYesYes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
ndb_deferred_constraints

ndb_deferred_constraintsYesYes         Yes                     Both        Yes

ndb-distributionYes        Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
ndb_distribution

ndb_distributionYes        Yes         Yes                     Global      Yes

ndb_eventbuffer_free_percentYesYes     Yes                     Global      Yes

ndb_eventbuffer_max_allocYesYes        Yes                     Global      Yes

ndb_extra_loggingYes       Yes         Yes                     Global      Yes

ndb_force_send Yes         Yes         Yes                     Both        Yes

ndb_fully_replicatedYes    Yes         Yes                     Both        Yes

ndb_index_stat_enableYes   Yes         Yes                     Both        Yes

ndb_index_stat_optionYes   Yes         Yes                     Both        Yes

ndb_join_pushdown                      Yes                     Both        Yes

Ndb_last_commit_epoch_server                       Yes         Global      No

Ndb_last_commit_epoch_session                      Yes         Session     No

ndb-log-apply-statusYes    Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ndb_log_apply_status

ndb_log_apply_statusYes    Yes         Yes                     Global      No

ndb_log_bin    Yes                     Yes                     Both        Yes

ndb_log_binlog_indexYes                Yes                     Global      Yes

ndb-log-empty-epochsYes    Yes         Yes                     Global      Yes

ndb_log_empty_epochsYes    Yes         Yes                     Global      Yes

ndb-log-empty-updateYes    Yes         Yes                     Global      Yes

ndb_log_empty_updateYes    Yes         Yes                     Global      Yes

ndb-log-exclusive-readsYes Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
ndb_log_exclusive_reads

ndb_log_exclusive_readsYes Yes         Yes                     Both        Yes

ndb-log-orig   Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ndb_log_orig

ndb_log_orig   Yes         Yes         Yes                     Global      No

ndb-log-transaction-idYes  Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ndb_log_transaction_id

ndb_log_transaction_id                 Yes                     Global      No

ndb-log-update-minimalYes  Yes         Yes                     Global      Yes

ndb_log_updated_onlyYes    Yes         Yes                     Global      Yes

ndb-mgmd-host  Yes         Yes

ndb-nodeid     Yes         Yes                     Yes         Global      No

Ndb_number_of_data_nodes                           Yes         Global      No

ndb_optimization_delay                 Yes                     Global      Yes

ndb_optimized_node_selectionYesYes     Yes                     Global      No

Ndb_pushed_queries_defined                         Yes         Global      No

Ndb_pushed_queries_executed                        Yes         Global      No

ndb_read_backupYes         Yes         Yes                     Global      Yes

ndb-recv-thread-activation-thresholdYesYes

-
_Variable_:
ndb_recv_thread_activation_threshold

ndb_recv_thread_activation_threshold

ndb-recv-thread-cpu-maskYesYes

-
_Variable_:
ndb_recv_thread_cpu_mask

ndb_recv_thread_cpu_mask               Yes                     Global      Yes

ndb_report_thresh_binlog_epoch_slipYesYesYes                   Global      Yes

ndb_report_thresh_binlog_mem_usageYesYesYes                    Global      Yes

Ndb_scan_count                                     Yes         Global      No

ndb_show_foreign_key_mock_tablesYesYes Yes                     Global      Yes

ndb_slave_conflict_roleYes Yes         Yes                     Global      Yes

Ndb_slave_max_replicated_epoch         Yes                     Global      No

Ndb_system_name                        Yes                     Global      No

ndb_table_no_logging                   Yes                     Session     Yes

ndb_table_temporary                    Yes                     Session     Yes

ndb-transid-mysql-connection-mapYes

ndb_use_copying_alter_table            Yes                     Both        No

ndb_use_exact_count                    Yes                     Both        Yes

ndb_use_transactionsYes    Yes         Yes                     Both        Yes

ndb_version                            Yes                     Global      No

ndb_version_string                     Yes                     Global      No

ndb-wait-connectedYes      Yes         Yes                     Global      No

ndb-wait-setup Yes         Yes         Yes                     Global      No

ndbcluster     Yes         Yes

ndbinfo_database                       Yes                     Global      No

ndbinfo_max_bytesYes                   Yes                     Both        Yes

ndbinfo_max_rowsYes                    Yes                     Both        Yes

ndbinfo_offline                        Yes                     Global      Yes

ndbinfo_show_hiddenYes                 Yes                     Both        Yes

ndbinfo_table_prefixYes                Yes                     Both        Yes

ndbinfo_version                        Yes                     Global      No

net_buffer_lengthYes       Yes         Yes                     Both        Yes

net_read_timeoutYes        Yes         Yes                     Both        Yes

net_retry_countYes         Yes         Yes                     Both        Yes

net_write_timeoutYes       Yes         Yes                     Both        Yes

new            Yes         Yes         Yes                     Both        Yes

ngram_token_sizeYes        Yes         Yes                     Global      No

no-defaults    Yes

Not_flushed_delayed_rows                           Yes         Global      No

offline_mode   Yes         Yes         Yes                     Global      Yes

old            Yes         Yes         Yes                     Global      No

old-alter-tableYes         Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
old_alter_table

old_passwords                          Yes                     Both        Yes

old-style-user-limitsYes   Yes

Ongoing_anonymous_gtid_violating_transaction_count Yes         Global      No

Ongoing_anonymous_transaction_count                Yes         Global      No

Ongoing_automatic_gtid_violating_transaction_count Yes         Global      No

Open_files                                         Yes         Global      No

open-files-limitYes        Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
open_files_limit

Open_streams                                       Yes         Global      No

Open_table_definitions                             Yes         Global      No

Open_tables                                        Yes         Both        No

Opened_files                                       Yes         Global      No

Opened_table_definitions                           Yes         Both        No

Opened_tables                                      Yes         Both        No

optimizer_prune_levelYes   Yes         Yes                     Both        Yes

optimizer_search_depthYes  Yes         Yes                     Both        Yes

optimizer_switchYes        Yes         Yes                     Both        Yes

optimizer_trace                        Yes                     Both        Yes

optimizer_trace_features               Yes                     Both        Yes

optimizer_trace_limit                  Yes                     Both        Yes

optimizer_trace_max_mem_size           Yes                     Both        Yes

optimizer_trace_offset                 Yes                     Both        Yes

parser_max_mem_sizeYes     Yes         Yes                     Both        Yes

partition      Yes         Yes

performance_schemaYes      Yes         Yes                     Global      No

Performance_schema_accounts_lost                   Yes         Global      No

performance_schema_accounts_sizeYesYes Yes                     Global      No

Performance_schema_cond_classes_lost               Yes         Global      No

Performance_schema_cond_instances_lost             Yes         Global      No

performance-schema-consumer-events-stages-currentYesYes

performance-schema-consumer-events-stages-historyYesYes

performance-schema-consumer-events-stages-history-longYesYes

performance-schema-consumer-events-statements-currentYesYes

performance-schema-consumer-events-statements-historyYesYes

performance-schema-consumer-events-statements-history-longYesYes

performance-schema-consumer-events-transactions-currentYesYes

performance-schema-consumer-events-transactions-historyYesYes

performance-schema-consumer-events-transactions-history-longYesYes

performance-schema-consumer-events-waits-currentYesYes

performance-schema-consumer-events-waits-historyYesYes

performance-schema-consumer-events-waits-history-longYesYes

performance-schema-consumer-global-instrumentationYesYes

performance-schema-consumer-statements-digestYesYes

performance-schema-consumer-thread-instrumentationYesYes

Performance_schema_digest_lost                     Yes         Global      No

performance_schema_digests_sizeYesYes  Yes                     Global      No

performance_schema_events_stages_history_long_sizeYesYesYes    Global      No

performance_schema_events_stages_history_sizeYesYesYes         Global      No

performance_schema_events_statements_history_long_sizeYesYesYesGlobal      No

performance_schema_events_statements_history_sizeYesYesYes     Global      No

performance_schema_events_transactions_history_long_sizeYesYesYesGlobal    No

performance_schema_events_transactions_history_sizeYesYesYes   Global      No

performance_schema_events_waits_history_long_sizeYesYesYes     Global      No

performance_schema_events_waits_history_sizeYesYesYes          Global      No

Performance_schema_file_classes_lost               Yes         Global      No

Performance_schema_file_handles_lost               Yes         Global      No

Performance_schema_file_instances_lost             Yes         Global      No

Performance_schema_hosts_lost                      Yes         Global      No

performance_schema_hosts_sizeYesYes    Yes                     Global      No

Performance_schema_index_stat_lost                 Yes         Global      No

performance-schema-instrumentYesYes

Performance_schema_locker_lost                     Yes         Global      No

performance_schema_max_cond_classesYesYesYes                   Global      No

performance_schema_max_cond_instancesYesYesYes                 Global      No

performance_schema_max_digest_lengthYesYesYes                  Global      No

performance_schema_max_file_classesYesYesYes                   Global      No

performance_schema_max_file_handlesYesYesYes                   Global      No

performance_schema_max_file_instancesYesYesYes                 Global      No

performance_schema_max_index_statYesYesYes                     Global      No

performance_schema_max_memory_classesYesYesYes                 Global      No

performance_schema_max_metadata_locksYesYesYes                 Global      No

performance_schema_max_mutex_classesYesYesYes                  Global      No

performance_schema_max_mutex_instancesYesYesYes                Global      No

performance_schema_max_prepared_statements_instancesYesYesYes  Global      No

performance_schema_max_program_instancesYesYesYes              Global      No

performance_schema_max_rwlock_classesYesYesYes                 Global      No

performance_schema_max_rwlock_instancesYesYesYes               Global      No

performance_schema_max_socket_classesYesYesYes                 Global      No

performance_schema_max_socket_instancesYesYesYes               Global      No

performance_schema_max_sql_text_lengthYesYesYes                Global      No

performance_schema_max_stage_classesYesYesYes                  Global      No

performance_schema_max_statement_classesYesYesYes              Global      No

performance_schema_max_statement_stackYesYesYes                Global      No

performance_schema_max_table_handlesYesYesYes                  Global      No

performance_schema_max_table_instancesYesYesYes                Global      No

performance_schema_max_table_lock_statYesYesYes                Global      No

performance_schema_max_thread_classesYesYesYes                 Global      No

performance_schema_max_thread_instancesYesYesYes               Global      No

Performance_schema_memory_classes_lost             Yes         Global      No

Performance_schema_metadata_lock_lost              Yes         Global      No

Performance_schema_mutex_classes_lost              Yes         Global      No

Performance_schema_mutex_instances_lost            Yes         Global      No

Performance_schema_nested_statement_lost           Yes         Global      No

Performance_schema_prepared_statements_lost        Yes         Global      No

Performance_schema_program_lost                    Yes         Global      No

Performance_schema_rwlock_classes_lost             Yes         Global      No

Performance_schema_rwlock_instances_lost           Yes         Global      No

Performance_schema_session_connect_attrs_lost      Yes         Global      No

performance_schema_session_connect_attrs_sizeYesYesYes         Global      No

performance_schema_setup_actors_sizeYesYesYes                  Global      No

performance_schema_setup_objects_sizeYesYesYes                 Global      No

Performance_schema_socket_classes_lost             Yes         Global      No

Performance_schema_socket_instances_lost           Yes         Global      No

Performance_schema_stage_classes_lost              Yes         Global      No

Performance_schema_statement_classes_lost          Yes         Global      No

Performance_schema_table_handles_lost              Yes         Global      No

Performance_schema_table_instances_lost            Yes         Global      No

Performance_schema_table_lock_stat_lost            Yes         Global      No

Performance_schema_thread_classes_lost             Yes         Global      No

Performance_schema_thread_instances_lost           Yes         Global      No

Performance_schema_users_lost                      Yes         Global      No

performance_schema_users_sizeYesYes    Yes                     Global      No

pid-file       Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
pid_file

plugin         Yes         Yes

plugin_dir     Yes         Yes         Yes                     Global      No

plugin-load    Yes         Yes

plugin-load-addYes         Yes

port           Yes         Yes         Yes                     Global      No

port-open-timeoutYes       Yes

preload_buffer_sizeYes     Yes         Yes                     Both        Yes

Prepared_stmt_count                                Yes         Global      No

print-defaults Yes

profiling                              Yes                     Both        Yes

profiling_history_sizeYes  Yes         Yes                     Both        Yes

protocol_version                       Yes                     Global      No

proxy_user                             Yes                     Session     No

pseudo_slave_mode                      Yes                     Session     Yes

pseudo_thread_id                       Yes                     Session     Yes

Qcache_free_blocks                                 Yes         Global      No

Qcache_free_memory                                 Yes         Global      No

Qcache_hits                                        Yes         Global      No

Qcache_inserts                                     Yes         Global      No

Qcache_lowmem_prunes                               Yes         Global      No

Qcache_not_cached                                  Yes         Global      No

Qcache_queries_in_cache                            Yes         Global      No

Qcache_total_blocks                                Yes         Global      No

Queries                                            Yes         Both        No

query_alloc_block_sizeYes  Yes         Yes                     Both        Yes

query_cache_limitYes       Yes         Yes                     Global      Yes

query_cache_min_res_unitYesYes         Yes                     Global      Yes

query_cache_sizeYes        Yes         Yes                     Global      Yes

query_cache_typeYes        Yes         Yes                     Both        Yes

query_cache_wlock_invalidateYesYes     Yes                     Both        Yes

query_prealloc_sizeYes     Yes         Yes                     Both        Yes

Questions                                          Yes         Both        No

rand_seed1                             Yes                     Session     Yes

rand_seed2                             Yes                     Session     Yes

range_alloc_block_sizeYes  Yes         Yes                     Both        Yes

range_optimizer_max_mem_sizeYesYes     Yes                     Both        Yes

rbr_exec_mode                          Yes                     Session     Yes

read_buffer_sizeYes        Yes         Yes                     Both        Yes

read_only      Yes         Yes         Yes                     Global      Yes

read_rnd_buffer_sizeYes    Yes         Yes                     Both        Yes

relay-log      Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
relay_log

relay_log_basename                     Yes                     Global      No

relay-log-indexYes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
relay_log_index

relay_log_indexYes         Yes         Yes                     Global      No

relay-log-info-fileYes     Yes

-
_Variable_:
relay_log_info_file

relay_log_info_fileYes     Yes         Yes                     Global      No

relay-log-info-repositoryYesYes

-
_Variable_:
relay_log_info_repository

relay_log_info_repository              Yes                     Global      Yes

relay_log_purgeYes         Yes         Yes                     Global      Yes

relay-log-recoveryYes      Yes

-
_Variable_:
relay_log_recovery

relay_log_recoveryYes      Yes         Yes                     Global      No

relay_log_space_limitYes   Yes         Yes                     Global      No

remove         Yes

replicate-do-dbYes         Yes

replicate-do-tableYes      Yes

replicate-ignore-dbYes     Yes

replicate-ignore-tableYes  Yes

replicate-rewrite-dbYes    Yes

replicate-same-server-idYesYes

replicate-wild-do-tableYes Yes

replicate-wild-ignore-tableYesYes

report-host    Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
report_host

report-passwordYes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
report_password

report-port    Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
report_port

report-user    Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
report_user

require_secure_transportYesYes         Yes                     Global      Yes

rewriter_enabled                       Yes                     Global      Yes

Rewriter_number_loaded_rules                       Yes         Global      No

Rewriter_number_reloads                            Yes         Global      No

Rewriter_number_rewritten_queries                  Yes         Global      No

Rewriter_reload_error                              Yes         Global      No

rewriter_verbose                       Yes                     Global      Yes

Rpl_semi_sync_master_clients                       Yes         Global      No

rpl_semi_sync_master_enabled           Yes                     Global      Yes

Rpl_semi_sync_master_net_avg_wait_time             Yes         Global      No

Rpl_semi_sync_master_net_wait_time                 Yes         Global      No

Rpl_semi_sync_master_net_waits                     Yes         Global      No

Rpl_semi_sync_master_no_times                      Yes         Global      No

Rpl_semi_sync_master_no_tx                         Yes         Global      No

Rpl_semi_sync_master_status                        Yes         Global      No

Rpl_semi_sync_master_timefunc_failures             Yes         Global      No

rpl_semi_sync_master_timeout           Yes                     Global      Yes

rpl_semi_sync_master_trace_level       Yes                     Global      Yes

Rpl_semi_sync_master_tx_avg_wait_time              Yes         Global      No

Rpl_semi_sync_master_tx_wait_time                  Yes         Global      No

Rpl_semi_sync_master_tx_waits                      Yes         Global      No

rpl_semi_sync_master_wait_for_slave_countYes                   Global      Yes

rpl_semi_sync_master_wait_no_slave     Yes                     Global      Yes

rpl_semi_sync_master_wait_point        Yes                     Global      Yes

Rpl_semi_sync_master_wait_pos_backtraverse         Yes         Global      No

Rpl_semi_sync_master_wait_sessions                 Yes         Global      No

Rpl_semi_sync_master_yes_tx                        Yes         Global      No

rpl_semi_sync_slave_enabled            Yes                     Global      Yes

Rpl_semi_sync_slave_status                         Yes         Global      No

rpl_semi_sync_slave_trace_level        Yes                     Global      Yes

rpl_stop_slave_timeoutYes  Yes         Yes                     Global      Yes

Rsa_public_key                                     Yes         Global      No

safe-user-createYes        Yes

secure-auth    Yes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
secure_auth

secure-file-privYes        Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
secure_file_priv

Select_full_join                                   Yes         Both        No

Select_full_range_join                             Yes         Both        No

Select_range                                       Yes         Both        No

Select_range_check                                 Yes         Both        No

Select_scan                                        Yes         Both        No

server-id      Yes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
server_id

server-id-bits Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
server_id_bits

server_id_bits Yes         Yes         Yes                     Global      No

server_uuid                            Yes                     Global      No

session_track_gtidsYes     Yes         Yes                     Both        Yes

session_track_schemaYes    Yes         Yes                     Both        Yes

session_track_state_changeYesYes       Yes                     Both        Yes

session_track_system_variablesYesYes   Yes                     Both        Yes

sha256_password_auto_generate_rsa_keysYesYesYes                Global      No

sha256_password_private_key_pathYesYes Yes                     Global      No

sha256_password_proxy_usersYesYes      Yes                     Global      Yes

sha256_password_public_key_pathYesYes  Yes                     Global      No

shared_memory  Yes         Yes         Yes                     Global      No

shared_memory_base_nameYes Yes         Yes                     Global      No

show_compatibility_56Yes   Yes         Yes                     Global      Yes

show_create_table_verbosityYesYes      Yes                     Both        Yes

show_old_temporalsYes      Yes         Yes                     Both        Yes

show-slave-auth-infoYes    Yes

simplified_binlog_gtid_recoveryYesYes  Yes                     Global      No

skip-character-set-client-handshakeYesYes

skip-concurrent-insertYes  Yes

-
_Variable_:
concurrent_insert

skip-event-schedulerYes    Yes

skip_external_lockingYes   Yes         Yes                     Global      No

skip-grant-tablesYes       Yes

skip-host-cacheYes         Yes

skip-name-resolveYes       Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
skip_name_resolve

skip-ndbclusterYes         Yes

skip-networkingYes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
skip_networking

skip-new       Yes         Yes

skip-partition Yes         Yes

skip-show-databaseYes      Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
skip_show_database

skip-slave-startYes        Yes

skip-ssl       Yes         Yes

skip-stack-traceYes        Yes

slave_allow_batchingYes    Yes         Yes                     Global      Yes

slave-checkpoint-groupYes  Yes

-
_Variable_:
slave_checkpoint_group

slave_checkpoint_groupYes  Yes         Yes                     Global      Yes

slave-checkpoint-periodYes Yes

-
_Variable_:
slave_checkpoint_period

slave_checkpoint_periodYes Yes         Yes                     Global      Yes

slave_compressed_protocolYesYes        Yes                     Global      Yes

slave_exec_modeYes         Yes         Yes                     Global      Yes

Slave_heartbeat_period                             Yes         Global      No

Slave_last_heartbeat                               Yes         Global      No

slave-load-tmpdirYes       Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
slave_load_tmpdir

slave-max-allowed-packetYesYes

-
_Variable_:
slave_max_allowed_packet

slave_max_allowed_packet               Yes                     Global      Yes

slave-net-timeoutYes       Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
slave_net_timeout

Slave_open_temp_tables                             Yes         Global      No

slave-parallel-typeYes     Yes

-
_Variable_:
slave_parallel_type

slave_parallel_type                    Yes                     Global      Yes

slave-parallel-workersYes  Yes

-
_Variable_:
slave_parallel_workers

slave_parallel_workersYes              Yes                     Global      Yes

slave-pending-jobs-size-maxYes

-
_Variable_:
slave_pending_jobs_size_max

slave_pending_jobs_size_max            Yes                     Global      Yes

slave_preserve_commit_orderYes         Yes                     Global      Yes

Slave_received_heartbeats                          Yes         Global      No

Slave_retried_transactions                         Yes         Global      No

Slave_rows_last_search_algorithm_used              Yes         Global      No

slave-rows-search-algorithmsYesYes

-
_Variable_:
slave_rows_search_algorithms

slave_rows_search_algorithms           Yes                     Global      Yes

Slave_running                                      Yes         Global      No

slave-skip-errorsYes       Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
slave_skip_errors

slave-sql-verify-checksumYesYes

slave_sql_verify_checksum              Yes                     Global      Yes

slave_transaction_retriesYesYes        Yes                     Global      Yes

slave_type_conversionsYes  Yes         Yes                     Global      No

Slow_launch_threads                                Yes         Both        No

slow_launch_timeYes        Yes         Yes                     Global      Yes

Slow_queries                                       Yes         Both        No

slow-query-log Yes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
slow_query_log

slow_query_log_fileYes     Yes         Yes                     Global      Yes

slow-start-timeoutYes      Yes

socket         Yes         Yes         Yes                     Global      No

sort_buffer_sizeYes        Yes         Yes                     Both        Yes

Sort_merge_passes                                  Yes         Both        No

Sort_range                                         Yes         Both        No

Sort_rows                                          Yes         Both        No

Sort_scan                                          Yes         Both        No

sporadic-binlog-dump-failYesYes

sql_auto_is_null                       Yes                     Both        Yes

sql_big_selects                        Yes                     Both        Yes

sql_buffer_result                      Yes                     Both        Yes

sql_log_bin                            Yes                     Session     Yes

sql_log_off                            Yes                     Both        Yes

sql-mode       Yes         Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
sql_mode

sql_notes                              Yes                     Both        Yes

sql_quote_show_create                  Yes                     Both        Yes

sql_safe_updates                       Yes                     Both        Yes

sql_select_limit                       Yes                     Both        Yes

sql_slave_skip_counter                 Yes                     Global      Yes

sql_warnings                           Yes                     Both        Yes

ssl            Yes         Yes

Ssl_accept_renegotiates                            Yes         Global      No

Ssl_accepts                                        Yes         Global      No

ssl-ca         Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ssl_ca

Ssl_callback_cache_hits                            Yes         Global      No

ssl-capath     Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ssl_capath

ssl-cert       Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ssl_cert

Ssl_cipher                                         Yes         Both        No

ssl-cipher     Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ssl_cipher

Ssl_cipher_list                                    Yes         Both        No

Ssl_client_connects                                Yes         Global      No

Ssl_connect_renegotiates                           Yes         Global      No

ssl-crl        Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ssl_crl

ssl-crlpath    Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ssl_crlpath

Ssl_ctx_verify_depth                               Yes         Global      No

Ssl_ctx_verify_mode                                Yes         Global      No

Ssl_default_timeout                                Yes         Both        No

Ssl_finished_accepts                               Yes         Global      No

Ssl_finished_connects                              Yes         Global      No

ssl-key        Yes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ssl_key

Ssl_server_not_after                               Yes         Both        No

Ssl_server_not_before                              Yes         Both        No

Ssl_session_cache_hits                             Yes         Global      No

Ssl_session_cache_misses                           Yes         Global      No

Ssl_session_cache_mode                             Yes         Global      No

Ssl_session_cache_overflows                        Yes         Global      No

Ssl_session_cache_size                             Yes         Global      No

Ssl_session_cache_timeouts                         Yes         Global      No

Ssl_sessions_reused                                Yes         Both        No

Ssl_used_session_cache_entries                     Yes         Global      No

Ssl_verify_depth                                   Yes         Both        No

Ssl_verify_mode                                    Yes         Both        No

Ssl_version                                        Yes         Both        No

standalone     Yes         Yes

storage_engine                         Yes                     Both        Yes

stored_program_cacheYes    Yes         Yes                     Global      Yes

super-large-pagesYes       Yes

super_read_onlyYes         Yes         Yes                     Global      Yes

symbolic-links Yes         Yes

sync_binlog    Yes         Yes         Yes                     Global      Yes

sync_frm       Yes         Yes         Yes                     Global      Yes

sync_master_infoYes        Yes         Yes                     Global      Yes

sync_relay_log Yes         Yes         Yes                     Global      Yes

sync_relay_log_infoYes     Yes         Yes                     Global      Yes

sysdate-is-now Yes         Yes

system_time_zone                       Yes                     Global      No

table_definition_cache                 Yes                     Global      Yes

Table_locks_immediate                              Yes         Global      No

Table_locks_waited                                 Yes         Global      No

table_open_cache                       Yes                     Global      Yes

Table_open_cache_hits                              Yes         Both        No

table_open_cache_instances             Yes                     Global      No

Table_open_cache_misses                            Yes         Both        No

Table_open_cache_overflows                         Yes         Both        No

tc-heuristic-recoverYes    Yes

Tc_log_max_pages_used                              Yes         Global      No

Tc_log_page_size                                   Yes         Global      No

Tc_log_page_waits                                  Yes         Global      No

temp-pool      Yes         Yes

thread_cache_sizeYes       Yes         Yes                     Global      Yes

thread_concurrencyYes      Yes         Yes                     Global      No

thread_handlingYes         Yes         Yes                     Global      No

thread_pool_algorithmYes   Yes         Yes                     Global      No

thread_pool_high_priority_connectionYesYesYes                  Both        Yes

thread_pool_max_unused_threadsYesYes   Yes                     Global      Yes

thread_pool_prio_kickup_timerYesYes    Yes                     Both        Yes

thread_pool_sizeYes        Yes         Yes                     Global      No

thread_pool_stall_limitYes Yes         Yes                     Global      Yes

thread_stack   Yes         Yes         Yes                     Global      No

Threads_cached                                     Yes         Global      No

Threads_connected                                  Yes         Global      No

Threads_created                                    Yes         Global      No

Threads_running                                    Yes         Global      No

time_format                            Yes                     Global      No

time_zone                              Yes                     Both        Yes

timed_mutexes  Yes         Yes         Yes                     Global      Yes

timestamp                              Yes                     Session     Yes

tls_version    Yes         Yes         Yes                     Global      No

tmp_table_size Yes         Yes         Yes                     Both        Yes

tmpdir         Yes         Yes         Yes                     Global      No

transaction_alloc_block_sizeYesYes     Yes                     Both        Yes

transaction_allow_batching             Yes                     Session     Yes

transaction-isolationYes   Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
tx_isolation

transaction_prealloc_sizeYesYes        Yes                     Both        Yes

transaction-read-onlyYes   Yes                                 Both        Yes

-                                      Yes                     Both        Yes
_Variable_:
tx_read_only

transaction_write_set_extractionYes    Yes                     Both        Yes

tx_isolation                           Yes                     Both        Yes

tx_read_only                           Yes                     Both        Yes

unique_checks                          Yes                     Both        Yes

updatable_views_with_limitYesYes       Yes                     Both        Yes

Uptime                                             Yes         Global      No

Uptime_since_flush_status                          Yes         Global      No

user           Yes         Yes

validate-passwordYes       Yes

validate_password_check_user_nameYesYesYes                     Global      Yes

validate_password_dictionary_file      Yes                     Global      Varies

validate_password_dictionary_file_last_parsed      Yes         Global      No

validate_password_dictionary_file_words_count      Yes         Global      No

validate_password_length               Yes                     Global      Yes

validate_password_mixed_case_count     Yes                     Global      Yes

validate_password_number_count         Yes                     Global      Yes

validate_password_policy               Yes                     Global      Yes

validate_password_special_char_count   Yes                     Global      Yes

validate_user_plugins                  Yes                     Global      No

verbose        Yes         Yes

version                                Yes                     Global      No

version_comment                        Yes                     Global      No

version_compile_machine                Yes                     Global      No

version_compile_os                     Yes                     Global      No

version_tokens_sessionYes  Yes         Yes                     Both        Yes

version_tokens_session_numberYesYes    Yes                     Both        No

wait_timeout   Yes         Yes         Yes                     Both        Yes

warning_count                          Yes                     Session     No

*Notes:* 1.  This option is dynamic, but only the server should set this
information.  You should not set the value of this variable manually.

5.1.4 Server Command Options
----------------------------

When you start the 'mysqld' server, you can specify
program options using any of the methods described in
program-options.  The most common methods are to provide options in an
option file or on the command line.  However, in most cases it is
desirable to make sure that the server uses the same options each time
it runs.  The best way to ensure this is to list them in an option file.
See option-files.  That section also describes option file
format and syntax.

'mysqld' reads options from the '[mysqld]' and '[server]'
groups.  'mysqld_safe' reads options from the
'[mysqld]', '[server]', '[mysqld_safe]', and '[safe_mysqld]' groups.
'mysql.server' reads options from the '[mysqld]'
and '[mysql.server]' groups.

An embedded MySQL server usually reads options from the '[server]',
'[embedded]', and '[XXXXX_SERVER]' groups, where XXXXX is the name of
the application into which the server is embedded.

'mysqld' accepts many command options.  For a brief
summary, execute this command:

     mysqld --help

To see the full list, use this command:

     mysqld --verbose --help

Some of the items in the list are actually system variables that can be
set at server startup.  These can be displayed at runtime using the
'SHOW VARIABLES' statement.  Some items displayed
by the preceding 'mysqld' command do not appear in
'SHOW VARIABLES' output; this is because they are
options only and not system variables.

The following list shows some of the most common server options.
Additional options are described in other sections:

   * Options that affect security: See security-options.

   * SSL-related options: See encrypted-connection-options.

   * Binary log control options: See binary-log.

   * Replication-related options: See replication-options.

   * Options for loading plugins such as pluggable storage engines: See
     server-plugin-loading.

   * Options specific to particular storage engines: See
     innodb-parameters and myisam-start.

Some options control the size of buffers or caches.  For a given buffer,
the server might need to allocate internal data structures.  These
structures typically are allocated from the total memory allocated to
the buffer, and the amount of space required might be platform
dependent.  This means that when you assign a value to an option that
controls a buffer size, the amount of space actually available might
differ from the value assigned.  In some cases, the amount might be less
than the value assigned.  It is also possible that the server will
adjust a value upward.  For example, if you assign a value of 0 to an
option for which the minimal value is 1024, the server will set the
value to 1024.

Values for buffer sizes, lengths, and stack sizes are given in bytes
unless otherwise specified.

Some options take file name values.  Unless otherwise specified, the
default file location is the data directory if the value is a relative
path name.  To specify the location explicitly, use an absolute path
name.  Suppose that the data directory is '/var/mysql/data'.  If a
file-valued option is given as a relative path name, it will be located
under '/var/mysql/data'.  If the value is an absolute path name, its
location is as given by the path name.

You can also set the values of server system variables at server startup
by using variable names as options.  To assign a value to a server
system variable, use an option of the form '--VAR_NAME=VALUE'.  For
example, '--sort_buffer_size=384M' sets the 'sort_buffer_size' variable
to a value of 384MB.

When you assign a value to a variable, MySQL might automatically correct
the value to stay within a given range, or adjust the value to the
closest permissible value if only certain values are permitted.

To restrict the maximum value to which a system variable can be set at
runtime with the 'SET' statement, specify this
maximum by using an option of the form '--maximum-VAR_NAME=VALUE' at
server startup.

You can change the values of most system variables at runtime with the
'SET' statement.  See set-variable.

See server-system-variables, provides a full description for all
variables, and additional information for setting them at server startup
and runtime.  For information on changing system variables, see
server-configuration.

   *
     '--help', '-?'

     Property                             Value

     *Command-Line Format*                '--help'

     Display a short help message and exit.  Use both the '--verbose'
     and '--help' options to see the full message.

   *
     '--allow-suspicious-udfs'

     Property                             Value

     *Command-Line Format*                '--allow-suspicious-udfs'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option controls whether user-defined functions that have only
     an 'xxx' symbol for the main function can be loaded.  By default,
     the option is off and only UDFs that have at least one auxiliary
     symbol can be loaded; this prevents attempts at loading functions
     from shared object files other than those containing legitimate
     UDFs.  See udf-security.

   *
     '--ansi'

     Property                             Value

     *Command-Line Format*                '--ansi'

     Use standard (ANSI) SQL syntax instead of MySQL syntax.  For more
     precise control over the server SQL mode, use the '--sql-mode'
     option instead.  See compatibility, and sql-mode.

   *
     '--basedir=DIR_NAME', '-b DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--basedir=dir_name'

     *System Variable*                    'basedir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The path to the MySQL installation directory.  This option sets the
     'basedir' system variable.

   *
     '--big-tables'

     Property                             Value

     *Command-Line Format*                '--big-tables'

     *System Variable*                    'big_tables'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enable large result sets by saving all temporary sets in files.
     This option prevents most 'table full' errors, but also slows down
     queries for which in-memory tables would suffice.  The server is
     able to handle large result sets automatically by using memory for
     small temporary tables and switching to disk tables where
     necessary.

   *
     '--bind-address=ADDR'

     Property                             Value

     *Command-Line Format*                '--bind-address=addr'

     *System Variable*                    'bind_address'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      '*'

     The MySQL server listens on a single network socket for TCP/IP
     connections.  This socket is bound to a single address, but it is
     possible for an address to map onto multiple network interfaces.
     To specify an address, use the '--bind-address=ADDR' option at
     server startup, where ADDR is an IPv4 or IPv6 address or a host
     name.  If ADDR is a host name, the server resolves the name to an
     IP address and binds to that address.

     The server treats different types of addresses as follows:

        * If the address is '*', the server accepts TCP/IP connections
          on all server host IPv6 and IPv4 interfaces if the server host
          supports IPv6, or accepts TCP/IP connections on all IPv4
          addresses otherwise.  Use this address to permit both IPv4 and
          IPv6 connections on all server interfaces.  This value is the
          default.

        * If the address is '0.0.0.0', the server accepts TCP/IP
          connections on all server host IPv4 interfaces.

        * If the address is '::', the server accepts TCP/IP connections
          on all server host IPv4 and IPv6 interfaces.

        * If the address is an IPv4-mapped address, the server accepts
          TCP/IP connections for that address, in either IPv4 or IPv6
          format.  For example, if the server is bound to
          '::ffff:127.0.0.1', clients can connect using
          '--host=127.0.0.1' or '--host=::ffff:127.0.0.1'.

        * If the address is a 'regular' IPv4 or IPv6 address (such as
          '127.0.0.1' or '::1'), the server accepts TCP/IP connections
          only for that IPv4 or IPv6 address.

     If you intend to bind the server to a specific address, be sure
     that the 'mysql.user' grant table contains an account with
     administrative privileges that you can use to connect to that
     address.  Otherwise, you will not be able to shut down the server.
     For example, if you bind the server to '*', you can connect to it
     using all existing accounts.  But if you bind the server to '::1',
     it accepts connections only on that address.  In that case, first
     make sure that the ''root'@'::1'' account is present in the
     'mysql.user' table so you can still connect to the server to shut
     it down.

   *
     '--binlog-format={ROW|STATEMENT|MIXED}'

     Property                             Value

     *Command-Line Format*                '--binlog-format=format'

     *System Variable*                    'binlog_format'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value* (>= 5.7.7)           'ROW'

     *Default Value* (<= 5.7.6)           'STATEMENT'

     *Valid Values*                       'ROW' 'STATEMENT' 'MIXED'

     Specify whether to use row-based, statement-based, or mixed
     replication.  Statement-based is the default in MySQL 5.7.  See
     replication-formats.

     Under some conditions, changing this variable at runtime is not
     possible, or causes replication to fail.  See
     binary-log-setting, for more information.

     Setting the binary logging format without enabling binary logging
     sets the 'binlog_format' global system variable and logs a warning.

   *
     '--bootstrap'

     Property                             Value

     *Command-Line Format*                '--bootstrap'

     *Deprecated*                         5.7.6

     This option is used by the 'mysql_install_db'
     program to create the MySQL privilege tables
     without having to start a full MySQL server.

     *Note*:

     'mysql_install_db' is deprecated because
     its functionality has been integrated into 'mysqld',
     the MySQL server.  Consequently, the '--bootstrap' server option
     that 'mysql_install_db' passes to
     'mysqld' is also deprecated.  To initialize a MySQL
     installation, invoke 'mysqld' with the
     '--initialize' or '--initialize-insecure' option.  For more
     information, see data-directory-initialization-mysqld.
     'mysql_install_db' and the '--bootstrap'
     server option will be removed in a future MySQL release.

     '--bootstrap' is mutually exclusive with '--daemonize',
     '--initialize', and '--initialize-insecure'.

     Global transaction identifiers (GTIDs) are not disabled when
     '--bootstrap' is used.  '--bootstrap' was used (Bug #20980271).
     See replication-gtids.

     When the server operates in bootstap mode, some functionality is
     unavailable that limits the statements permitted in any file named
     by the '--init-file' option.  For more information, see the
     description of that option.  In addition, the
     'disabled_storage_engines' system variable has no effect.

   *
     '--character-sets-dir=DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--character-sets-dir=dir_name'

     *System Variable*                    'character_sets_dir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The directory where character sets are installed.  See
     charset-configuration.

   *
     '--character-set-client-handshake'

     Property                             Value

     *Command-Line Format*                '--character-set-client-handshake'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Do not ignore character set information sent by the client.  To
     ignore client information and use the default server character set,
     use '--skip-character-set-client-handshake'; this makes MySQL
     behave like MySQL 4.0.

   *
     '--character-set-filesystem=CHARSET_NAME'

     Property                             Value

     *Command-Line Format*                '--character-set-filesystem=name'

     *System Variable*                    'character_set_filesystem'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'binary'

     The file system character set.  This option sets the
     'character_set_filesystem' system variable.

   *
     '--character-set-server=CHARSET_NAME', '-C CHARSET_NAME'

     Property                             Value

     *Command-Line Format*                '--character-set-server'

     *System Variable*                    'character_set_server'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'latin1'

     Use CHARSET_NAME as the default server character set.  See
     charset-configuration.  If you use this option to specify a
     nondefault character set, you should also use '--collation-server'
     to specify the collation.

   *
     '--chroot=DIR_NAME', '-r DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--chroot=dir_name'

     *Type*                               directory name

     Put the 'mysqld' server in a closed environment
     during startup by using the 'chroot()' system call.  This is a
     recommended security measure.  Use of this option somewhat limits
     'LOAD DATA INFILE' and 'SELECT ... INTO OUTFILE'.

   *
     '--collation-server=COLLATION_NAME'

     Property                             Value

     *Command-Line Format*                '--collation-server'

     *System Variable*                    'collation_server'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'latin1_swedish_ci'

     Use COLLATION_NAME as the default server collation.  See
     charset-configuration.

   *
     '--console'

     Property                             Value

     *Command-Line Format*                '--console'

     *Platform Specific*                  Windows

     (Windows only.)  Write the error log to 'stderr' and 'stdout' (the
     console).  'mysqld' does not close the console
     window if this option is used.

     '--console' takes precedence over '--log-error' if both are given.
     (In MySQL 5.5 and 5.6, this is reversed: '--log-error' takes
     precedence over '--console' if both are given.)

   *
     '--core-file'

     Property                             Value

     *Command-Line Format*                '--core-file'

     *Type*                               boolean

     *Default Value*                      'OFF'

     Write a core file if 'mysqld' dies.  The name and
     location of the core file is system dependent.  On Linux, a core
     file named 'core.PID' is written to the current working directory
     of the process, which for 'mysqld' is the data
     directory.  PID represents the process ID of the server process.
     On OS X, a core file named 'core.PID' is written to the '/cores'
     directory.  On Solaris, use the 'coreadm' command to specify where
     to write the core file and how to name it.

     For some systems, to get a core file you must also specify the
     '--core-file-size' option to 'mysqld_safe'.  See
     mysqld-safe.  On some systems, such as Solaris, you do not
     get a core file if you are also using the '--user' option.  There
     might be additional restrictions or limitations.  For example, it
     might be necessary to execute 'ulimit -c unlimited' before starting
     the server.  Consult your system documentation.

   *
     '--daemonize'

     Property                             Value

     *Command-Line Format*                '--daemonize[={OFF|ON}]'

     *Introduced*                         5.7.6

     *Type*                               boolean

     *Default Value*                      'OFF'

     This option causes the server to run as a traditional, forking
     daemon, permitting it to work with operating systems that use
     systemd for process control.  For more information, see
     using-systemd.

     '--daemonize' is mutually exclusive with '--bootstrap',
     '--initialize', and '--initialize-insecure'.

   *
     '--datadir=DIR_NAME', '-h DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--datadir=dir_name'

     *System Variable*                    'datadir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The path to the MySQL server data directory.  This option sets the
     'datadir' system variable.  See the description of that variable.

   *
     '--debug[=DEBUG_OPTIONS]', '-# [DEBUG_OPTIONS]'

     Property                             Value

     *Command-Line Format*                '--debug[=debug_options]'

     *System Variable*                    'debug'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (Windows)                     string

     *Type* (Unix)                        string

     *Default Value* (Windows)            'd:t:i:O,\mysqld.trace'

     *Default Value* (Unix)               'd:t:i:o,/tmp/mysqld.trace'

     If MySQL is configured with the '-DWITH_DEBUG=1' 'CMake' option,
     you can use this option to get a trace file of what 'mysqld'
     is doing.  A typical DEBUG_OPTIONS string is
     'd:t:o,FILE_NAME'.  The default is 'd:t:i:o,/tmp/mysqld.trace' on
     Unix and 'd:t:i:O,\mysqld.trace' on Windows.

     Using '-DWITH_DEBUG=1' to configure MySQL with debugging support
     enables you to use the '--debug="d,parser_debug"' option when you
     start the server.  This causes the Bison parser that is used to
     process SQL statements to dump a parser trace to the server's
     standard error output.  Typically, this output is written to the
     error log.

     This option may be given multiple times.  Values that begin with
     '+' or '-' are added to or subtracted from the previous value.  For
     example, '--debug=T' '--debug=+P' sets the value to 'P:T'.

     For more information, see dbug-package.

   *
     '--debug-sync-timeout[=N]'

     Property                             Value

     *Command-Line Format*                '--debug-sync-timeout[=#]'

     *Type*                               integer

     Controls whether the Debug Sync facility for testing and debugging
     is enabled.  Use of Debug Sync requires that MySQL be configured
     with the '-DENABLE_DEBUG_SYNC=1' 'CMake' option (see
     source-configuration-options).  If Debug Sync is not compiled in,
     this option is not available.  The option value is a timeout in
     seconds.  The default value is 0, which disables Debug Sync.  To
     enable it, specify a value greater than 0; this value also becomes
     the default timeout for individual synchronization points.  If the
     option is given without a value, the timeout is set to 300 seconds.

     For a description of the Debug Sync facility and how to use
     synchronization points, see MySQL Internals: Test Synchronization
     (http://dev.mysql.com/doc/internals/en/test-synchronization.html).

   *
     '--default-authentication-plugin=PLUGIN_NAME'

     Property                             Value

     *Command-Line Format*                '--default-authentication-plugin=plugin_name'

     *Removed*                            5.7.2

     *Type*                               enumeration

     *Default Value*                      'mysql_native_password'

     *Valid Values*                       'mysql_native_password'
                                          'sha256_password'

     This option sets the default authentication plugin.  It was removed
     in MySQL 5.7.2 and replaced by the 'default_authentication_plugin'
     system variable.  The variable is used the same way as the option
     at server startup, but also enables the default plugin value to be
     inspected as runtime.  For usage details, see the description of
     'default_authentication_plugin'.

   *
     '--default-storage-engine=TYPE'

     Property                             Value

     *Command-Line Format*                '--default-storage-engine=name'

     *System Variable*                    'default_storage_engine'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'InnoDB'

     Set the default storage engine for tables.  See
     storage-engines.  This option sets the storage engine for
     permanent tables only.  To set the storage engine for 'TEMPORARY'
     tables, set the 'default_tmp_storage_engine' system variable.

     If you disable the default storage engine at server startup, you
     must set the default engine for both permanent and 'TEMPORARY'
     tables to a different engine or the server will not start.

   *
     '--default-time-zone=TIMEZONE'

     Property                             Value

     *Command-Line Format*                '--default-time-zone=name'

     *Type*                               string

     Set the default server time zone.  This option sets the global
     'time_zone' system variable.  If this option is not given, the
     default time zone is the same as the system time zone (given by the
     value of the 'system_time_zone' system variable.

   *
     '--defaults-extra-file=FILE_NAME'

     Read this option file after the global option file but (on Unix)
     before the user option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.  This must be the first option on the
     command line if it is used.

     For additional information about this option, see
     option-file-options.

   *
     '--defaults-file=FILE_NAME'

     Read only the given option file.  If the file does not exist or is
     otherwise inaccessible, an error occurs.  FILE_NAME is interpreted
     relative to the current directory if given as a relative path name
     rather than a full path name.

     *Note*:

     This must be the first option on the command line if it is used,
     except that if the server is started with the '--defaults-file' and
     '--install' (or '--install-manual') options, '--install' (or
     '--install-manual') must be first.

     For additional information about this option, see
     option-file-options.

   *
     '--defaults-group-suffix=STR'

     Read not only the usual option groups, but also groups with the
     usual names and a suffix of STR.  For example, see 'mysqld'
     normally reads the '[mysqld]' group.  If the
     '--defaults-group-suffix=_other' option is given, see 'mysqld'
     also reads the '[mysqld_other]' group.

     For additional information about this option, see
     option-file-options.

   *
     '--delay-key-write[={OFF|ON|ALL}]'

     Property                             Value

     *Command-Line Format*                '--delay-key-write[=name]'

     *System Variable*                    'delay_key_write'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'ON'

     *Valid Values*                       'ON' 'OFF' 'ALL'

     Specify how to use delayed key writes.  Delayed key writing causes
     key buffers not to be flushed between writes for 'MyISAM' tables.
     'OFF' disables delayed key writes.  'ON' enables delayed key writes
     for those tables that were created with the 'DELAY_KEY_WRITE'
     option.  'ALL' delays key writes for all 'MyISAM' tables.  See
     server-configuration, and myisam-start.

     *Note*:

     If you set this variable to 'ALL', you should not use 'MyISAM'
     tables from within another program (such as another MySQL server or
     'myisamchk') when the tables are in use.  Doing
     so leads to index corruption.

   *
     '--des-key-file=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--des-key-file=file_name'

     *Deprecated*                         5.7.6

     Read the default DES keys from this file.  These keys are used by
     the 'DES_ENCRYPT()' and 'DES_DECRYPT()' functions.

     *Note*:

     The 'DES_ENCRYPT()' and 'DES_DECRYPT()' functions are deprecated as
     of MySQL 5.7.6, will be removed in a future MySQL release, and
     should no longer be used.  Consequently, '--des-key-file' also is
     deprecated and will be removed.

   *
     '--disable-partition-engine-check'

     Property                             Value

     *Command-Line Format*                '--disable-partition-engine-check'

     *Introduced*                         5.7.17

     *Deprecated*                         5.7.17

     *Type* (>= 5.7.17)                   boolean

     *Default Value* (>= 5.7.21)          'true'

     *Default Value* (>= 5.7.17, <=       'false'
     5.7.20)

     Whether to disable the startup check for tables with nonnative
     partitioning.

     As of MySQL 5.7.17, the generic partitioning handler in the MySQL
     server is deprecated, and is removed in MySQL 8.0, when the storage
     engine used for a given table is expected to provide its own
     ('native') partitioning handler.  Currently, only the
     'InnoDB' and 'NDB'.
     storage engines do this.

     Use of tables with nonnative partitioning results in an
     'ER_WARN_DEPRECATED_SYNTAX' warning.  In MySQL 5.7.17 through
     5.1.20, the server automatically performs a check at startup to
     identify tables that use nonnative partitioning; for any that are
     found, the server writes a message to its error log.  To disable
     this check, use the '--disable-partition-engine-check' option.  In
     MySQL 5.7.21 and later, this check is _not_ performed; in these
     versions, you must start the server with
     '--disable-partition-engine-check=false', if you wish for the
     server to check for tables using the generic partitioning handler
     (Bug #85830, Bug #25846957).

     Use of tables with nonnative partitioning results in an
     'ER_WARN_DEPRECATED_SYNTAX' warning.  Also, the server performs a
     check at startup to identify tables that use nonnative
     partitioning; for any found, the server writes a message to its
     error log.  To disable this check, use the
     '--disable-partition-engine-check' option.

     To prepare for migration to MySQL 8.0, any table with nonnative
     partitioning should be changed to use an engine that provides
     native partitioning, or be made nonpartitioned.  For example, to
     change a table to 'InnoDB', execute this statement:

          ALTER TABLE TABLE_NAME ENGINE = INNODB;

   *
     '--early-plugin-load=PLUGIN_LIST'

     Property                             Value

     *Command-Line Format*                '--early-plugin-load=plugin_list'

     *Introduced*                         5.7.11

     *Type* (>= 5.7.11)                   string

     *Default Value* (>= 5.7.12)          'empty string'

     *Default Value* (5.7.11)             'keyring_file plugin library file
                                          name'

     This option tells the server which plugins to load before loading
     mandatory built-in plugins and before storage engine
     initialization.  If multiple '--early-plugin-load' options are
     given, only the last one is used.

     The option value is a semicolon-separated list of
     NAME'='PLUGIN_LIBRARY and PLUGIN_LIBRARY values.  Each NAME is the
     name of a plugin to load, and PLUGIN_LIBRARY is the name of the
     library file that contains the plugin code.  If a plugin library is
     named without any preceding plugin name, the server loads all
     plugins in the library.  The server looks for plugin library files
     in the directory named by the 'plugin_dir' system variable.

     For example, if plugins named 'myplug1' and 'myplug2' have library
     files 'myplug1.so' and 'myplug2.so', use this option to perform an
     early plugin load:

          shell> mysqld --early-plugin-load="myplug1=myplug1.so;myplug2=myplug2.so"

     Quotes are used around the argument value because otherwise a
     semicolon (';') is interpreted as a special character by some
     command interpreters.  (Unix shells treat it as a command
     terminator, for example.)

     Each named plugin is loaded early for a single invocation of
     'mysqld' only.  After a restart, the plugin is not loaded
     early unless '--early-plugin-load' is used again.

     If the server is started using '--initialize' or
     '--initialize-insecure', plugins specified by '--early-plugin-load'
     are not loaded.

     If the server is run with '--help', plugins specified by
     '--early-plugin-load' are loaded but not initialized.  This
     behavior ensures that plugin options are displayed in the help
     message.

     As of MySQL 5.7.12, the default '--early-plugin-load' value is
     empty.  To load your chosen keyring plugin, you must use an
     explicit '--early-plugin-load' option with a nonempty value.

     *Important*:

     In MySQL 5.7.11, the default '--early-plugin-load' value was the
     name of the 'keyring_file' plugin library file, so that plugin was
     loaded by default.  'InnoDB' tablespace encryption requires the
     'keyring_file' plugin to be loaded prior to 'InnoDB'
     initialization, so this change of default '--early-plugin-load'
     value introduces an incompatibility for upgrades from 5.7.11 to
     5.7.12 or higher.  Administrators who have encrypted 'InnoDB'
     tablespaces must take explicit action to ensure continued loading
     of the 'keyring_file' plugin: Start the server with an
     '--early-plugin-load' option that names the plugin library file.
     For additional information, see keyring-installation.

     The 'InnoDB' tablespace encryption feature relies on the
     'keyring_file' plugin for encryption key management, and the
     'keyring_file' plugin must be loaded prior to storage engine
     initialization to facilitate 'InnoDB' recovery for encrypted
     tables.  In MySQL 5.7.11, if you do not want to load the
     'keyring_file' plugin at server startup, specify an empty string
     ('--early-plugin-load=""').

     For information about 'InnoDB' tablespace encryption, see
     innodb-tablespace-encryption.  For general information about
     plugin loading, see server-plugin-loading.

   *
     '--enable-named-pipe'

     Property                             Value

     *Command-Line Format*                '--enable-named-pipe'

     *Platform Specific*                  Windows

     Enable support for named pipes.  This option applies only on
     Windows.

   *
     '--event-scheduler[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--event-scheduler[=value]'

     *System Variable*                    'event_scheduler'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'OFF'

     *Valid Values*                       'ON' 'OFF' 'DISABLED'

     Enable or disable, and start or stop, the event scheduler.

     For detailed information, see The '--event-scheduler' Option.

   *
     '--exit-info[=FLAGS]', '-T [FLAGS]'

     Property                             Value

     *Command-Line Format*                '--exit-info[=flags]'

     *Type*                               integer

     This is a bitmask of different flags that you can use for debugging
     the 'mysqld' server.  Do not use this option unless
     you know _exactly_ what it does!

   *
     '--external-locking'

     Property                             Value

     *Command-Line Format*                '--external-locking'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Enable external locking (system locking), which is disabled by
     default.  If you use this option on a system on which 'lockd' does
     not fully work (such as Linux), it is easy for 'mysqld'
     to deadlock.

     To disable external locking explicitly, use
     '--skip-external-locking'.

     External locking affects only 'MyISAM'
     table access.  For more information,
     including conditions under which it can and cannot be used, see
     external-locking.

   *
     '--flush'

     Property                             Value

     *Command-Line Format*                '--flush'

     *System Variable*                    'flush'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Flush (synchronize) all changes to disk after each SQL statement.
     Normally, MySQL does a write of all changes to disk only after each
     SQL statement and lets the operating system handle the
     synchronizing to disk.  See crashing.

     *Note*:

     If '--flush' is specified, the value of 'flush_time' does not
     matter and changes to 'flush_time' have no effect on flush
     behavior.

   *
     '--gdb'

     Property                             Value

     *Command-Line Format*                '--gdb'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Install an interrupt handler for 'SIGINT' (needed to stop
     'mysqld' with '^C' to set breakpoints) and disable stack
     tracing and core file handling.  See porting.

   *
     '--general-log[={0|1}]'

     Property                             Value

     *Command-Line Format*                '--general-log'

     *System Variable*                    'general_log'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Specify the initial general query log state.  With no argument or
     an argument of 1, the '--general-log' option enables the log.  If
     omitted or given with an argument of 0, the option disables the
     log.

   *
     '--ignore-db-dir=DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--ignore-db-dir'

     *Deprecated*                         5.7.16

     *Type*                               directory name

     This option tells the server to ignore the given directory name for
     purposes of the 'SHOW DATABASES' statement
     or 'INFORMATION_SCHEMA' tables.  For example, if a MySQL
     configuration locates the data directory at the root of a file
     system on Unix, the system might create a 'lost+found' directory
     there that the server should ignore.  Starting the server with
     '--ignore-db-dir=lost+found' causes that name not to be listed as a
     database.

     To specify more than one name, use this option multiple times, once
     for each name.  Specifying the option with an empty value (that is,
     as '--ignore-db-dir=') resets the directory list to the empty list.

     Instances of this option given at server startup are used to set
     the 'ignore_db_dirs' system variable.

     This option is deprecated in MySQL 5.7.  With the introduction of
     the data dictionary in MySQL 8.0, it became superfluous and was
     removed in that version.

   *
     '--initialize'

     Property                             Value

     *Command-Line Format*                '--initialize'

     *Introduced*                         5.7.6

     *Type*                               boolean

     *Default Value*                      'OFF'

     This option is used to initialize a MySQL installation by creating
     the data directory and populating the tables in the 'mysql' system
     database.  For more information, see
     data-directory-initialization-mysqld.

     When the server is started with '--initialize', some functionality
     is unavailable that limits the statements permitted in any file
     named by the '--init-file' option.  For more information, see the
     description of that option.  In addition, the
     'disabled_storage_engines' system variable has no effect.

     In MySQL NDB Cluster 7.5.4 and later, the '--ndbcluster' option is
     ignored when used together with '--initialize'.  (Bug #81689, Bug
     #23518923)

     In MySQL 5.7.7 and earlier, global transaction identifiers (GTIDs)
     were automatically disabled whenever '--initialize' was enabled.
     In MySQL 5.7.8 and later GTIDs are not disabled when '--initialize'
     is enabled.

     '--initialize' is mutually exclusive with '--bootstrap' and
     '--daemonize'.

   *
     '--initialize-insecure'

     Property                             Value

     *Command-Line Format*                '--initialize-insecure'

     *Introduced*                         5.7.6

     *Type*                               boolean

     *Default Value*                      'OFF'

     This option is used to initialize a MySQL installation by creating
     the data directory and populating the tables in the 'mysql' system
     database.  This option implies '--initialize'.  For more
     information, see the description of that option, and
     data-directory-initialization-mysqld.

     '--initialize-insecure' is mutually exclusive with '--bootstrap'
     and '--daemonize'.

   *
     '--init-file=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--init-file=file_name'

     *System Variable*                    'init_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     Read SQL statements from this file at startup.  Each statement must
     be on a single line and should not include comments.

     If the server is started with any of the '--bootstrap',
     '--initialize', or '--initialize-insecure' options, it operates in
     bootstap mode and some functionality is unavailable that limits the
     statements permitted in the file.  These include statements that
     relate to account management (such as 'CREATE USER'
     or 'GRANT'), replication, and global
     transaction identifiers.  See replication-gtids.

   * '--innodb-XXX'

     Set an option for the 'InnoDB' storage engine.  The 'InnoDB'
     options are listed in innodb-parameters.

   *
     '--install [SERVICE_NAME]'

     Property                             Value

     *Command-Line Format*                '--install [service_name]'

     *Platform Specific*                  Windows

     (Windows only) Install the server as a Windows service that starts
     automatically during Windows startup.  The default service name is
     'MySQL' if no SERVICE_NAME value is given.  For more information,
     see windows-start-service.

     *Note*:

     If the server is started with the '--defaults-file' and '--install'
     options, '--install' must be first.

   *
     '--install-manual [SERVICE_NAME]'

     Property                             Value

     *Command-Line Format*                '--install-manual [service_name]'

     *Platform Specific*                  Windows

     (Windows only) Install the server as a Windows service that must be
     started manually.  It does not start automatically during Windows
     startup.  The default service name is 'MySQL' if no SERVICE_NAME
     value is given.  For more information, see
     windows-start-service.

     *Note*:

     If the server is started with the '--defaults-file' and
     '--install-manual' options, '--install-manual' must be first.

   *
     '--language=LANG_NAME, -L LANG_NAME'

     Property                             Value

     *Command-Line Format*                '--language=name'

     *Deprecated*                         Yes; use 'lc-messages-dir'

     *System Variable*                    'language'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     *Default Value*                      '/usr/local/mysql/share/mysql/english/'

     The language to use for error messages.  LANG_NAME can be given as
     the language name or as the full path name to the directory where
     the language files are installed.  See
     error-message-language.

     '--lc-messages-dir' and '--lc-messages' should be used rather than
     '--language', which is deprecated (and handled as an alias for
     '--lc-messages-dir').  The '--language' option will be removed in a
     future MySQL release.

   *
     '--large-pages'

     Property                             Value

     *Command-Line Format*                '--large-pages'

     *System Variable*                    'large_pages'

     *Scope*                              Global

     *Dynamic*                            No

     *Platform Specific*                  Linux

     *Type* (Linux)                       boolean

     *Default Value* (Linux)              'FALSE'

     Some hardware/operating system architectures support memory pages
     greater than the default (usually 4KB). The actual implementation
     of this support depends on the underlying hardware and operating
     system.  Applications that perform a lot of memory accesses may
     obtain performance improvements by using large pages due to reduced
     Translation Lookaside Buffer (TLB) misses.

     MySQL supports the Linux implementation of large page support
     (which is called HugeTLB in Linux).  See
     large-page-support.  For Solaris support of large pages, see the
     description of the '--super-large-pages' option.

     '--large-pages' is disabled by default.

   *
     '--lc-messages=LOCALE_NAME'

     Property                             Value

     *Command-Line Format*                '--lc-messages=name'

     *System Variable*                    'lc_messages'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'en_US'

     The locale to use for error messages.  The default is 'en_US'.  The
     server converts the argument to a language name and combines it
     with the value of '--lc-messages-dir' to produce the location for
     the error message file.  See error-message-language.

   *
     '--lc-messages-dir=DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--lc-messages-dir=dir_name'

     *System Variable*                    'lc_messages_dir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The directory where error messages are located.  The server uses
     the value together with the value of '--lc-messages' to produce the
     location for the error message file.  See
     error-message-language.

   *
     '--local-service'

     Property                             Value

     *Command-Line Format*                '--local-service'

     (Windows only) A '--local-service' option following the service
     name causes the server to run using the 'LocalService' Windows
     account that has limited system privileges.  If both
     '--defaults-file' and '--local-service' are given following the
     service name, they can be in any order.  See
     windows-start-service.

   *
     '--log-error[=FILE_NAME]'

     Property                             Value

     *Command-Line Format*                '--log-error[=file_name]'

     *System Variable*                    'log_error'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     Write the error log and startup messages to this file.  See
     error-log.

     If the option names no file, the error log file name on Unix and
     Unix-like systems is 'HOST_NAME.err' in the data directory.  The
     file name on Windows is the same, unless the '--pid-file' option is
     specified.  In that case, the file name is the PID file base name
     with a suffix of '.err' in the data directory.

     If the option names a file, the error log file has that name (with
     an '.err' suffix added if the name has no suffix), located under
     the data directory unless an absolute path name is given to specify
     a different location.

     On Windows, '--console' takes precedence over '--log-error' if both
     are given.  In this case, the server writes the error log to the
     console rather than to a file.  (In MySQL 5.5 and 5.6, this is
     reversed: '--log-error' takes precedence over '--console' if both
     are given.)

   *
     '--log-isam[=FILE_NAME]'

     Property                             Value

     *Command-Line Format*                '--log-isam[=file_name]'

     *Type*                               file name

     Log all 'MyISAM' changes to this file (used only when debugging
     'MyISAM').

   *
     '--log-output=VALUE,...'

     Property                             Value

     *Command-Line Format*                '--log-output=name'

     *System Variable*                    'log_output'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               set

     *Default Value*                      'FILE'

     *Valid Values*                       'TABLE' 'FILE' 'NONE'

     This option determines the destination for general query log and
     slow query log output.  The option value can be given as one or
     more of the words 'TABLE', 'FILE', or 'NONE'.  'TABLE' select
     logging to the 'general_log' and 'slow_log' tables in the 'mysql'
     database as a destination.  'FILE' selects logging to log files as
     a destination.  'NONE' disables logging.  If 'NONE' is present in
     the option value, it takes precedence over any other words that are
     present.  'TABLE' and 'FILE' can both be given to select to both
     log output destinations.

     This option selects log output destinations, but does not enable
     log output.  To do that, use the '--general_log' and
     '--slow_query_log' options.  For 'FILE' logging, the
     '--general_log_file' and '-slow_query_log_file' options determine
     the log file location.  For more information, see
     log-destinations.

   *
     '--log-queries-not-using-indexes'

     Property                             Value

     *Command-Line Format*                '--log-queries-not-using-indexes'

     *System Variable*                    'log_queries_not_using_indexes'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     If you are using this option with the slow query log enabled,
     queries that are expected to retrieve all rows are logged.  See
     slow-query-log.  This option does not necessarily mean that
     no index is used.  For example, a query that uses a full index scan
     uses an index but would be logged because the index would not limit
     the number of rows.

   *
     '--log-raw'

     Property                             Value

     *Command-Line Format*                '--log-raw[=value]'

     *Type*                               boolean

     *Default Value*                      'OFF'

     Passwords in certain statements written to the general query log,
     slow query log, and binary log are rewritten by the server not to
     occur literally in plain text.  Password rewriting can be
     suppressed for the general query log by starting the server with
     the '--log-raw' option.  This option may be useful for diagnostic
     purposes, to see the exact text of statements as received by the
     server, but for security reasons is not recommended for production
     use.

     If a query rewrite plugin is installed, the '--log-raw' option
     affects statement logging as follows:

        * Without '--log-raw', the server logs the statement returned by
          the query rewrite plugin.  This may differ from the statement
          as received.

        * With '--log-raw', the server logs the original statement as
          received.

     For more information, see password-logging.

   *
     '--log-short-format'

     Property                             Value

     *Command-Line Format*                '--log-short-format'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Log less information to the slow query log, if it has been
     activated.

   *
     '--log-slow-admin-statements'

     Property                             Value

     *Command-Line Format*                '--log-slow-admin-statements'
                                          (5.7.0)

     *Removed*                            5.7.1

     *Type*                               boolean

     *Default Value*                      'OFF'

     Include slow administrative statements in the statements written to
     the slow query log.  Administrative statements include 'ALTER TABLE',
     see 'ANALYZE TABLE',
     'CHECK TABLE', 'CREATE INDEX',
     'DROP INDEX', 'OPTIMIZE TABLE',
     and 'REPAIR TABLE'.

     This command-line option was removed in MySQL 5.7.1 and replaced by
     the 'log_slow_admin_statements' system variable.  The system
     variable can be set on the command line or in option files the same
     way as the option, so there is no need for any changes at server
     startup, but the system variable also makes it possible to examine
     or set the value at runtime.

   *
     '--log-tc=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--log-tc=file_name'

     *Type*                               file name

     *Default Value*                      'tc.log'

     The name of the memory-mapped transaction coordinator log file (for
     XA transactions that affect multiple storage engines when the
     binary log is disabled).  The default name is 'tc.log'.  The file
     is created under the data directory if not given as a full path
     name.  This option is unused.

   *
     '--log-tc-size=SIZE'

     Property                             Value

     *Command-Line Format*                '--log-tc-size=#'

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms,   '6 * page size'
     >= 5.7.21)

     *Default Value* (64-bit platforms,   '24576'
     <= 5.7.20)

     *Default Value* (32-bit platforms,   '6 * page size'
     >= 5.7.21)

     *Default Value* (32-bit platforms,   '24576'
     <= 5.7.20)

     *Minimum Value* (64-bit platforms,   '6 * page size'
     >= 5.7.21)

     *Minimum Value* (32-bit platforms,   '6 * page size'
     >= 5.7.21)

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The size in bytes of the memory-mapped transaction coordinator log.
     The default and minimum values are 6 times the page size, and the
     value must be a multiple of the page size.  (Before MySQL 5.7.21,
     the default size is 24KB.)

   *
     '--log-warnings[=LEVEL]', '-W [LEVEL]'

     Property                             Value

     *Command-Line Format*                '--log-warnings[=#]'

     *Deprecated*                         5.7.2

     *System Variable*                    'log_warnings'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms,   '2'
     >= 5.7.2)

     *Default Value* (64-bit platforms,   '1'
     <= 5.7.1)

     *Default Value* (32-bit platforms,   '2'
     >= 5.7.2)

     *Default Value* (32-bit platforms,   '1'
     <= 5.7.1)

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     *Note*:

     As of MySQL 5.7.2, the 'log_error_verbosity' system variable is
     preferred over, and should be used instead of, the '--log-warnings'
     option or 'log_warnings' system variable.  For more information,
     see the descriptions of 'log_error_verbosity' and 'log_warnings'.
     The '--log-warnings' command-line option and 'log_warnings' system
     variable are deprecated and will be removed in a future MySQL
     release.

     Whether to produce additional warning messages to the error log.
     This option is enabled by default (the default is 1 before MySQL
     5.7.2, 2 as of 5.7.2).  To disable it, use '--log-warnings=0'.
     Specifying the option without a LEVEL value increments the current
     value by 1.  The server logs messages about statements that are
     unsafe for statement-based logging if the value is greater than 0.
     Aborted connections and access-denied errors for new connection
     attempts are logged if the value is greater than 1.  See
     communication-errors.

   *
     '--low-priority-updates'

     Property                             Value

     *Command-Line Format*                '--low-priority-updates'

     *System Variable*                    'low_priority_updates'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Give table-modifying operations (see 'INSERT',
     'REPLACE', 'DELETE', 'UPDATE')
     lower priority than selects.  This can also be done using
     '{INSERT | REPLACE | DELETE | UPDATE} LOW_PRIORITY ...' to lower
     the priority of only one query, or by 'SET LOW_PRIORITY_UPDATES=1'
     to change the priority in one thread.  This affects only storage
     engines that use only table-level locking ('MyISAM', 'MEMORY',
     'MERGE').  See table-locking.

   *
     '--min-examined-row-limit=NUMBER'

     Property                             Value

     *Command-Line Format*                '--min-examined-row-limit=#'

     *System Variable*                    'min_examined_row_limit'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '0'

     *Default Value* (32-bit platforms)   '0'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     When this option is set, queries which examine fewer than NUMBER
     rows are not written to the slow query log.  The default is 0.

   *
     '--memlock'

     Property                             Value

     *Command-Line Format*                '--memlock'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Lock the 'mysqld' process in memory.  This option
     might help if you have a problem where the operating system is
     causing 'mysqld' to swap to disk.

     '--memlock' works on systems that support the 'mlockall()' system
     call; this includes Solaris, most Linux distributions that use a
     2.4 or higher kernel, and perhaps other Unix systems.  On Linux
     systems, you can tell whether or not 'mlockall()' (and thus this
     option) is supported by checking to see whether or not it is
     defined in the system 'mman.h' file, like this:

          shell> grep mlockall /usr/include/sys/mman.h

     If 'mlockall()' is supported, you should see in the output of the
     previous command something like the following:

          extern int mlockall (int __flags) __THROW;

     *Important*:

     Use of this option may require you to run the server as 'root',
     which, for reasons of security, is normally not a good idea.  See
     changing-mysql-user.

     On Linux and perhaps other systems, you can avoid the need to run
     the server as 'root' by changing the 'limits.conf' file.  See the
     notes regarding the memlock limit in large-page-support.

     You must not try to use this option on a system that does not
     support the 'mlockall()' system call; if you do so, see 'mysqld'
     will very likely crash as soon as you try to start it.

   *
     '--myisam-block-size=N'

     Property                             Value

     *Command-Line Format*                '--myisam-block-size=#'

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '16384'

     The block size to be used for 'MyISAM' index pages.

   *
     '--myisam-recover-options[=OPTION[,OPTION]...]]'

     Property                             Value

     *Command-Line Format*                '--myisam-recover-options[=name]'

     *Type*                               enumeration

     *Default Value*                      'OFF'

     *Valid Values*                       'OFF' 'DEFAULT' 'BACKUP' 'FORCE'
                                          'QUICK'

     Set the 'MyISAM' storage engine recovery mode.  The option value is
     any combination of the values of 'OFF', 'DEFAULT', 'BACKUP',
     'FORCE', or 'QUICK'.  If you specify multiple values, separate them
     by commas.  Specifying the option with no argument is the same as
     specifying 'DEFAULT', and specifying with an explicit value of '""'
     disables recovery (same as a value of 'OFF').  If recovery is
     enabled, each time 'mysqld' opens a 'MyISAM' table,
     it checks whether the table is marked as crashed or was not closed
     properly.  (The last option works only if you are running with
     external locking disabled.)  If this is the case, see 'mysqld'
     runs a check on the table.  If the table was corrupted,
     see 'mysqld' attempts to repair it.

     The following options affect how the repair works.

     Option      Description

     'OFF'       No recovery.

     'DEFAULT'   Recovery without backup, forcing, or quick
                 checking.

     'BACKUP'    If the data file was changed during recovery,
                 save a backup of the 'TBL_NAME.MYD' file as
                 'TBL_NAME-DATETIME.BAK'.

     'FORCE'     Run recovery even if we would lose more than one
                 row from the '.MYD' file.

     'QUICK'     Do not check the rows in the table if there are
                 not any delete blocks.

     Before the server automatically repairs a table, it writes a note
     about the repair to the error log.  If you want to be able to
     recover from most problems without user intervention, you should
     use the options 'BACKUP,FORCE'.  This forces a repair of a table
     even if some rows would be deleted, but it keeps the old data file
     as a backup so that you can later examine what happened.

     See myisam-start.

   *
     '--no-defaults'

     Do not read any option files.  If program startup fails due to
     reading unknown options from an option file, '--no-defaults' can be
     used to prevent them from being read.  This must be the first
     option on the command line if it is used.

     For additional information about this option, see
     option-file-options.

   *
     '--old-alter-table'

     Property                             Value

     *Command-Line Format*                '--old-alter-table'

     *System Variable*                    'old_alter_table'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     When this option is given, the server does not use the optimized
     method of processing an 'ALTER TABLE'.
     operation.  It reverts to using a temporary table, copying over the
     data, and then renaming the temporary table to the original, as
     used by MySQL 5.0 and earlier.  For more information on the
     operation of 'ALTER TABLE', see
     alter-table.

   *
     '--old-style-user-limits'

     Property                             Value

     *Command-Line Format*                '--old-style-user-limits'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Enable old-style user limits.  (Before MySQL 5.0.3, account
     resource limits were counted separately for each host from which a
     user connected rather than per account row in the 'user' table.)
     See user-resources.

   *
     '--open-files-limit=COUNT'

     Property                             Value

     *Command-Line Format*                '--open-files-limit=#'

     *System Variable*                    'open_files_limit'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '5000, with possible adjustment'

     *Minimum Value*                      '0'

     *Maximum Value*                      'platform dependent'

     Changes the number of file descriptors available to 'mysqld'.
     You should try increasing the value of this option if
     'mysqld' gives you the error 'Too many open files'.
     'mysqld' uses the option value to reserve
     descriptors with 'setrlimit()'.  Internally, the maximum value for
     this option is the maximum unsigned integer value, but the actual
     maximum is platform dependent.  If the requested number of file
     descriptors cannot be allocated, see 'mysqld' writes a
     warning to the error log.

     'mysqld' may attempt to allocate more than the
     requested number of descriptors (if they are available), using the
     values of 'max_connections' and 'table_open_cache' to estimate
     whether more descriptors will be needed.

     On Unix, the value cannot be set greater than 'ulimit -n'.

   *
     '--partition[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--partition'

     *Deprecated*                         5.7.16

     *Disabled by*                        'skip-partition'

     *Type*                               boolean

     *Default Value*                      'ON'

     Enables or disables user-defined partitioning support in the MySQL
     Server.

     This option is deprecated in MySQL 5.7.16, and is removed from
     MySQL 8.0 because in MySQL 8.0, the partitioning engine is replaced
     by native partitioning, which cannot be disabled.

   * '--performance-schema-xxx'

     Configure a Performance Schema option.  For details, see
     performance-schema-options.

   *
     '--pid-file=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--pid-file=file_name'

     *System Variable*                    'pid_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The path name of the process ID file.  The server creates the file
     in the data directory unless an absolute path name is given to
     specify a different directory.  If you specify this option, you
     must specify a value.  If you do not specify this option, MySQL
     uses a default value of 'HOST_NAME.pid', where HOST_NAME is the
     name of the host machine.

     The process ID file is used by other programs such as
     'mysqld_safe' to determine the server's process ID.
     On Windows, this variable also affects the default error log file
     name.  See error-log.

   *
     '--plugin-XXX'

     Specifies an option that pertains to a server plugin.  For example,
     many storage engines can be built as plugins, and for such engines,
     options for them can be specified with a '--plugin' prefix.  Thus,
     the '--innodb_file_per_table' option for 'InnoDB' can be specified
     as '--plugin-innodb_file_per_table'.

     For boolean options that can be enabled or disabled, the '--skip'
     prefix and other alternative formats are supported as well (see
     option-modifiers).  For example,
     '--skip-plugin-innodb_file_per_table' disables
     'innodb_file_per_table'.

     The rationale for the '--plugin' prefix is that it enables plugin
     options to be specified unambiguously if there is a name conflict
     with a built-in server option.  For example, were a plugin writer
     to name a plugin 'sql' and implement a 'mode' option, the option
     name might be '--sql-mode', which would conflict with the built-in
     option of the same name.  In such cases, references to the
     conflicting name are resolved in favor of the built-in option.  To
     avoid the ambiguity, users can specify the plugin option as
     '--plugin-sql-mode'.  Use of the '--plugin' prefix for plugin
     options is recommended to avoid any question of ambiguity.

   *
     '--plugin-load=PLUGIN_LIST'

     Property                             Value

     *Command-Line Format*                '--plugin-load=plugin_list'

     *Type*                               string

     This option tells the server to load the named plugins at startup.
     If multiple '--plugin-load' options are given, only the last one is
     used.  Additional plugins to load may be specified using
     '--plugin-load-add' options.

     The option value is a semicolon-separated list of
     NAME'='PLUGIN_LIBRARY and PLUGIN_LIBRARY values.  Each NAME is the
     name of a plugin to load, and PLUGIN_LIBRARY is the name of the
     library file that contains the plugin code.  If a plugin library is
     named without any preceding plugin name, the server loads all
     plugins in the library.  The server looks for plugin library files
     in the directory named by the 'plugin_dir' system variable.

     For example, if plugins named 'myplug1' and 'myplug2' have library
     files 'myplug1.so' and 'myplug2.so', use this option to perform an
     early plugin load:

          shell> mysqld --plugin-load="myplug1=myplug1.so;myplug2=myplug2.so"

     Quotes are used around the argument value here because otherwise
     semicolon (';') is interpreted as a special character by some
     command interpreters.  (Unix shells treat it as a command
     terminator, for example.)

     Each named plugin is loaded for a single invocation of
     'mysqld' only.  After a restart, the plugin is not loaded
     unless '--plugin-load' is used again.  This is in contrast to
     'INSTALL PLUGIN', which adds an entry to the
     'mysql.plugins' table to cause the plugin to be loaded for every
     normal server startup.

     Under normal startup, the server determines which plugins to load
     by reading the 'mysql.plugins' system table.  If the server is
     started with the '--skip-grant-tables' option, it does not consult
     the 'mysql.plugins' table and does not load plugins listed there.
     '--plugin-load' enables plugins to be loaded even when
     '--skip-grant-tables' is given.  '--plugin-load' also enables
     plugins to be loaded at startup that cannot be loaded at runtime.

     For additional information about plugin loading, see
     server-plugin-loading.

   *
     '--plugin-load-add=PLUGIN_LIST'

     Property                             Value

     *Command-Line Format*                '--plugin-load-add=plugin_list'

     *Type*                               string

     This option complements the '--plugin-load' option.
     '--plugin-load-add' adds a plugin or plugins to the set of plugins
     to be loaded at startup.  The argument format is the same as for
     '--plugin-load'.  '--plugin-load-add' can be used to avoid
     specifying a large set of plugins as a single long unwieldy
     '--plugin-load' argument.

     '--plugin-load-add' can be given in the absence of '--plugin-load',
     but any instance of '--plugin-load-add' that appears before
     '--plugin-load'.  has no effect because '--plugin-load' resets the
     set of plugins to load.  In other words, these options:

          --plugin-load=x --plugin-load-add=y

     are equivalent to this option:

          --plugin-load="x;y"

     But these options:

          --plugin-load-add=y --plugin-load=x

     are equivalent to this option:

          --plugin-load=x

     For additional information about plugin loading, see
     server-plugin-loading.

   *
     '--port=PORT_NUM', '-P PORT_NUM'

     Property                             Value

     *Command-Line Format*                '--port=#'

     *System Variable*                    'port'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '3306'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     The port number to use when listening for TCP/IP connections.  On
     Unix and Unix-like systems, the port number must be 1024 or higher
     unless the server is started by the 'root' system user.

   *
     '--port-open-timeout=NUM'

     Property                             Value

     *Command-Line Format*                '--port-open-timeout=#'

     *Type*                               integer

     *Default Value*                      '0'

     On some systems, when the server is stopped, the TCP/IP port might
     not become available immediately.  If the server is restarted
     quickly afterward, its attempt to reopen the port can fail.  This
     option indicates how many seconds the server should wait for the
     TCP/IP port to become free if it cannot be opened.  The default is
     not to wait.

   *
     '--print-defaults'

     Print the program name and all options that it gets from option
     files.  Password values are masked.  This must be the first option
     on the command line if it is used, except that it may be used
     immediately after '--defaults-file' or '--defaults-extra-file'.

     For additional information about this option, see
     option-file-options.

   *
     '--remove [SERVICE_NAME]'

     Property                             Value

     *Command-Line Format*                '--remove [service_name]'

     *Platform Specific*                  Windows

     (Windows only) Remove a MySQL Windows service.  The default service
     name is 'MySQL' if no SERVICE_NAME value is given.  For more
     information, see windows-start-service.

   *
     '--safe-user-create'

     Property                             Value

     *Command-Line Format*                '--safe-user-create'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     If this option is enabled, a user cannot create new MySQL users by
     using the 'GRANT' statement unless the user has the
     'INSERT' privilege for the 'mysql.user' table or any column in the
     table.  If you want a user to have the ability to create new users
     that have those privileges that the user has the right to grant,
     you should grant the user the following privilege:

          GRANT INSERT(user) ON mysql.user TO 'USER_NAME'@'HOST_NAME';

     This ensures that the user cannot change any privilege columns
     directly, but has to use the 'GRANT' statement to
     give privileges to other users.

   *
     '--secure-auth'

     Property                             Value

     *Command-Line Format*                '--secure-auth'

     *Deprecated*                         5.7.5

     *System Variable*                    'secure_auth'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     *Valid Values* (>= 5.7.5)            'ON'

     *Valid Values* (<= 5.7.4)            'OFF' 'ON'

     This option causes the server to block connections by clients that
     attempt to use accounts that have passwords stored in the old
     (pre-4.1) format.  Use it to prevent all use of passwords employing
     the old format (and hence insecure communication over the network).

     As of MySQL 5.7.5, this option is deprecated and will be removed in
     a future MySQL release.  It is always enabled and attempting to
     disable it ('--skip-secure-auth', '--secure-auth=0') produces an
     error.  Before MySQL 5.7.5, this option is enabled by default but
     can be disabled.

     Server startup fails with an error if this option is enabled and
     the privilege tables are in pre-4.1 format.  See
     account-upgrades.

     The 'mysql' client also has a '--secure-auth' option,
     which prevents connections to a server if the server requires a
     password in old format for the client account.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them is
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     '--secure-file-priv=DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--secure-file-priv=dir_name'

     *System Variable*                    'secure_file_priv'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value* (>= 5.7.6)           'platform specific'

     *Default Value* (<= 5.7.5)           'empty string'

     *Valid Values* (>= 5.7.6)            'empty string' 'dirname' 'NULL'

     *Valid Values* (<= 5.7.5)            'empty string' 'dirname'

     This option sets the 'secure_file_priv' system variable, which is
     used to limit the effect of data import and export operations, such
     as those performed by the 'LOAD DATA' and
     'SELECT ... INTO OUTFILE' statements and the
     'LOAD_FILE()' function.  For more information, see the description
     of 'secure_file_priv'.

   *
     '--shared-memory'

     Property                             Value

     *Command-Line Format*                '--shared-memory[={0,1}]'

     *System Variable*                    'shared_memory'

     *Scope*                              Global

     *Dynamic*                            No

     *Platform Specific*                  Windows

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Enable shared-memory connections by local clients.  This option is
     available only on Windows.

   *
     '--shared-memory-base-name=NAME'

     Property                             Value

     *Command-Line Format*                '--shared-memory-base-name=name'

     *System Variable*                    'shared_memory_base_name'

     *Scope*                              Global

     *Dynamic*                            No

     *Platform Specific*                  Windows

     *Type*                               string

     *Default Value*                      'MYSQL'

     The name of shared memory to use for shared-memory connections.
     This option is available only on Windows.  The default name is
     'MYSQL'.  The name is case sensitive.

   *
     '--skip-concurrent-insert'

     Turn off the ability to select and insert at the same time on
     'MyISAM' tables.  (This is to be used only if you think you have
     found a bug in this feature.)  See concurrent-inserts.

   *
     '--skip-event-scheduler'

     Property                             Value

     *Command-Line Format*                '--skip-event-scheduler'
                                          '--disable-event-scheduler'

     Turns the Event Scheduler 'OFF'.  This is not the same as disabling
     the Event Scheduler, which requires setting
     '--event-scheduler=DISABLED'; see The '--event-scheduler' Option,
     for more information.

   *
     '--skip-grant-tables'

     This option causes the server to start without using the privilege
     system at all, which gives anyone with access to the server
     _unrestricted access to all databases_.  You can cause a running
     server to start using the grant tables again by executing
     'mysqladmin flush-privileges' or 'mysqladmin reload'
     command from a system shell, or by issuing a
     MySQL 'FLUSH PRIVILEGES' statement after connecting to the server.

     This option also causes the server to suppress during its startup
     sequence the loading of user-defined functions (UDFs), scheduled
     events, and plugins that were installed with the 'INSTALL PLUGIN'
     statement.  To cause plugins to be loaded
     anyway, use the '--plugin-load' option.  '--skip-grant-tables' also
     causes the 'disabled_storage_engines' system variable to have no
     effect.

     'FLUSH PRIVILEGES' might be executed implicitly by other actions
     performed after startup.  For example, see 'mysql_upgrade'
     flushes the privileges during the upgrade procedure.

   *
     '--skip-host-cache'

     Disable use of the internal host cache for faster name-to-IP
     resolution.  In this case, the server performs a DNS lookup every
     time a client connects.  See host-cache.

     Use of '--skip-host-cache' is similar to setting the
     'host_cache_size' system variable to 0, but 'host_cache_size' is
     more flexible because it can also be used to resize, enable, or
     disable the host cache at runtime, not just at server startup.

     If you start the server with '--skip-host-cache', that does not
     prevent changes to the value of 'host_cache_size', but such changes
     have no effect and the cache is not re-enabled even if
     'host_cache_size' is set larger than 0.

   *
     '--skip-innodb'

     Disable the 'InnoDB' storage engine.  In this case, because the
     default storage engine is 'InnoDB',
     the server will not start unless you also use
     '--default-storage-engine' and '--default-tmp-storage-engine' to
     set the default to some other engine for both permanent and
     'TEMPORARY' tables.

     As of MySQL 5.7.5, the 'InnoDB' storage engine can no longer be
     disabled, and the '--skip-innodb' option is deprecated and has no
     effect.  Its use results in a warning.  This option will be removed
     in a future MySQL release.

   *
     '--skip-name-resolve'

     Do not resolve host names when checking client connections.  Use
     only IP addresses.  If you use this option, all 'Host' column
     values in the grant tables must be IP addresses.  See
     host-cache.

     Depending on the network configuration of your system and the
     'Host' values for your accounts, clients may need to connect using
     an explicit '--host' option, such as '--host=127.0.0.1' or
     '--host=::1'.

     An attempt to connect to the host '127.0.0.1' normally resolves to
     the 'localhost' account.  However, this fails if the server is run
     with the '--skip-name-resolve' option, so make sure that an account
     exists that can accept a connection.  For example, to be able to
     connect as 'root' using '--host=127.0.0.1' or '--host=::1', create
     these accounts:

          CREATE USER 'root'@'127.0.0.1' IDENTIFIED BY 'ROOT-PASSWORD';
          CREATE USER 'root'@'::1' IDENTIFIED BY 'ROOT-PASSWORD';

   *
     '--skip-networking'

     Do not listen for TCP/IP connections at all.  All interaction with
     'mysqld' must be made using named pipes or shared
     memory (on Windows) or Unix socket files (on Unix).  This option is
     highly recommended for systems where only local clients are
     permitted.  See host-cache.

   *
     '--skip-partition'

     Property                             Value

     *Command-Line Format*                '--skip-partition'
                                          '--disable-partition'

     *Deprecated*                         5.7.16

     Disables user-defined partitioning.  Partitioned tables can be seen
     using 'SHOW TABLES' or by querying the
     'INFORMATION_SCHEMA.TABLES' table, but cannot be
     created or modified, nor can data in such tables be accessed.  All
     partition-specific columns in the
     'INFORMATION_SCHEMA.PARTITIONS' table display
     'NULL'.

     Since 'DROP TABLE' removes table definition
     ('.frm') files, this statement works on partitioned tables even
     when partitioning is disabled using the option.  The statement,
     however, does not remove partition definitions associated with
     partitioned tables in such cases.  For this reason, you should
     avoid dropping partitioned tables with partitioning disabled, or
     take action to remove orphaned '.par' files manually (if present).

     *Note*:

     As of MySQL 5.7.6, partition definition ('.par') files are no
     longer created for partitioned 'InnoDB' tables.  Instead, partition
     definitions are stored in the 'InnoDB' internal data dictionary.
     Partition definition ('.par') files continue to be used for
     partitioned 'MyISAM' tables.

     This option is deprecated in MySQL 5.7.16, and is removed from
     MySQL 8.0 because in MySQL 8.0, the partitioning engine is replaced
     by native partitioning, which cannot be disabled.

   *
     '--ssl*'

     Options that begin with '--ssl' specify whether to permit clients
     to connect using SSL and indicate where to find SSL keys and
     certificates.  See encrypted-connection-options.

   *
     '--standalone'

     Property                             Value

     *Command-Line Format*                '--standalone'

     *Platform Specific*                  Windows

     Available on Windows only; instructs the MySQL server not to run as
     a service.

   *
     '--super-large-pages'

     Property                             Value

     *Command-Line Format*                '--super-large-pages'

     *Platform Specific*                  Solaris

     *Type* (Solaris)                     boolean

     *Default Value* (Solaris)            'FALSE'

     Standard use of large pages in MySQL attempts to use the largest
     size supported, up to 4MB. Under Solaris, a 'super large pages'
     feature enables uses of pages up to 256MB. This feature is
     available for recent SPARC platforms.  It can be enabled or
     disabled by using the '--super-large-pages' or
     '--skip-super-large-pages' option.

   *
     '--symbolic-links', '--skip-symbolic-links'

     Property                             Value

     *Command-Line Format*                '--symbolic-links'

     *Type*                               boolean

     *Default Value*                      'ON'

     Enable or disable symbolic link support.  On Unix, enabling
     symbolic links means that you can link a 'MyISAM' index file or
     data file to another directory with the 'INDEX DIRECTORY' or 'DATA
     DIRECTORY' options of the 'CREATE TABLE'.
     statement.  If you delete or rename the table, the files that its
     symbolic links point to also are deleted or renamed.  See
     symbolic-links-to-tables.

     This option has no meaning on Windows.

   *
     '--skip-show-database'

     Property                             Value

     *Command-Line Format*                '--skip-show-database'

     *System Variable*                    'skip_show_database'

     *Scope*                              Global

     *Dynamic*                            No

     This option sets the 'skip_show_database' system variable that
     controls who is permitted to use the 'SHOW DATABASES'
     statement.  See server-system-variables.

   *
     '--skip-stack-trace'

     Property                             Value

     *Command-Line Format*                '--skip-stack-trace'

     Do not write stack traces.  This option is useful when you are
     running 'mysqld' under a debugger.  On some systems,
     you also must use this option to get a core file.  See
     porting.

   *
     '--slow-query-log[={0|1}]'

     Property                             Value

     *Command-Line Format*                '--slow-query-log'

     *System Variable*                    'slow_query_log'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Specify the initial slow query log state.  With no argument or an
     argument of 1, the '--slow-query-log' option enables the log.  If
     omitted or given with an argument of 0, the option disables the
     log.

   *
     '--slow-start-timeout=TIMEOUT'

     Property                             Value

     *Command-Line Format*                '--slow-start-timeout=#'

     *Type* (Windows)                     integer

     *Default Value* (Windows)            '15000'

     This option controls the Windows service control manager's service
     start timeout.  The value is the maximum number of milliseconds
     that the service control manager waits before trying to kill the
     windows service during startup.  The default value is 15000 (15
     seconds).  If the MySQL service takes too long to start, you may
     need to increase this value.  A value of 0 means there is no
     timeout.

   *
     '--socket=PATH'

     Property                             Value

     *Command-Line Format*                '--socket={file_name|pipe_name}'

     *System Variable*                    'socket'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (Other)                       string

     *Type* (Windows)                     string

     *Default Value* (Other)              '/tmp/mysql.sock'

     *Default Value* (Windows)            'MySQL'

     On Unix, this option specifies the Unix socket file to use when
     listening for local connections.  The default value is
     '/tmp/mysql.sock'.  If this option is given, the server creates the
     file in the data directory unless an absolute path name is given to
     specify a different directory.  On Windows, the option specifies
     the pipe name to use when listening for local connections that use
     a named pipe.  The default value is 'MySQL' (not case sensitive).

   *
     '--sql-mode=VALUE[,VALUE[,VALUE...]]'

     Property                             Value

     *Command-Line Format*                '--sql-mode=name'

     *System Variable*                    'sql_mode'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               set

     *Default Value* (>= 5.7.8)           'ONLY_FULL_GROUP_BY
                                          STRICT_TRANS_TABLES
                                          NO_ZERO_IN_DATE NO_ZERO_DATE
                                          ERROR_FOR_DIVISION_BY_ZERO
                                          NO_AUTO_CREATE_USER
                                          NO_ENGINE_SUBSTITUTION'

     *Default Value* (5.7.7)              'ONLY_FULL_GROUP_BY
                                          STRICT_TRANS_TABLES
                                          NO_AUTO_CREATE_USER
                                          NO_ENGINE_SUBSTITUTION'

     *Default Value* (>= 5.7.5, <=        'ONLY_FULL_GROUP_BY
     5.7.6)                               STRICT_TRANS_TABLES
                                          NO_ENGINE_SUBSTITUTION'

     *Default Value* (<= 5.7.4)           'NO_ENGINE_SUBSTITUTION'

     *Valid Values*                       'ALLOW_INVALID_DATES'
                                          'ANSI_QUOTES'
                                          'ERROR_FOR_DIVISION_BY_ZERO'
                                          'HIGH_NOT_PRECEDENCE'
                                          'IGNORE_SPACE'
                                          'NO_AUTO_CREATE_USER'
                                          'NO_AUTO_VALUE_ON_ZERO'
                                          'NO_BACKSLASH_ESCAPES'
                                          'NO_DIR_IN_CREATE'
                                          'NO_ENGINE_SUBSTITUTION'
                                          'NO_FIELD_OPTIONS'
                                          'NO_KEY_OPTIONS'
                                          'NO_TABLE_OPTIONS'
                                          'NO_UNSIGNED_SUBTRACTION'
                                          'NO_ZERO_DATE' 'NO_ZERO_IN_DATE'
                                          'ONLY_FULL_GROUP_BY'
                                          'PAD_CHAR_TO_FULL_LENGTH'
                                          'PIPES_AS_CONCAT' 'REAL_AS_FLOAT'
                                          'STRICT_ALL_TABLES'
                                          'STRICT_TRANS_TABLES'

     Set the SQL mode.  See sql-mode.

     *Note*:

     MySQL installation programs may configure the SQL mode during the
     installation process.  For example, see 'mysql_install_db'
     creates a default option file named 'my.cnf' in
     the base installation directory.  This file contains a line that
     sets the SQL mode; see mysql-install-db.

     If the SQL mode differs from the default or from what you expect,
     check for a setting in an option file that the server reads at
     startup.

   *
     '--sysdate-is-now'

     Property                             Value

     *Command-Line Format*                '--sysdate-is-now'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     'SYSDATE()' by default returns the time at which it executes, not
     the time at which the statement in which it occurs begins
     executing.  This differs from the behavior of 'NOW()'.  This option
     causes 'SYSDATE()' to be an alias for 'NOW()'.  For information
     about the implications for binary logging and replication, see the
     description for 'SYSDATE()' in date-and-time-functions and
     for 'SET TIMESTAMP' in server-system-variables.

   *
     '--tc-heuristic-recover={COMMIT|ROLLBACK}'

     Property                             Value

     *Command-Line Format*                '--tc-heuristic-recover=name'

     *Type*                               enumeration

     *Default Value*                      'COMMIT'

     *Valid Values*                       'COMMIT' 'ROLLBACK'

     The type of decision to use in the heuristic recovery process.  To
     use this option, two or more storage engines that support XA
     transactions must be installed.

     Prior to MySQL 5.7.8, the server interprets
     '--tc-heuristic-recover' option values incorrectly due to an
     off-by-one error (Bug #70860).

   *
     '--temp-pool'

     Property                             Value

     *Command-Line Format*                '--temp-pool'

     *Deprecated*                         5.7.18

     *Type* (Other)                       boolean

     *Type* (Linux)                       boolean

     *Default Value* (Other)              'FALSE'

     *Default Value* (Linux)              'TRUE'

     This option is ignored except on Linux.  On Linux, it causes most
     temporary files created by the server to use a small set of names,
     rather than a unique name for each new file.  This works around a
     problem in the Linux kernel dealing with creating many new files
     with different names.  With the old behavior, Linux seems to 'leak'
     memory, because it is being allocated to the directory entry cache
     rather than to the disk cache.

     As of MySQL 5.7.18, this option is deprecated and is removed in
     MySQL 8.0.

   *
     '--transaction-isolation=LEVEL'

     Property                             Value

     *Command-Line Format*                '--transaction-isolation=name'

     *System Variable* (>= 5.7.20)        'transaction_isolation'

     *Scope* (>= 5.7.20)                  Global, Session

     *Dynamic* (>= 5.7.20)                Yes

     *Type*                               enumeration

     *Default Value*                      'REPEATABLE-READ'

     *Valid Values*                       'READ-UNCOMMITTED'
                                          'READ-COMMITTED' 'REPEATABLE-READ'
                                          'SERIALIZABLE'

     Sets the default transaction isolation level.  The 'level' value
     can be 'READ-UNCOMMITTED', 'READ-COMMITTED', 'REPEATABLE-READ', or
     'SERIALIZABLE'.  See set-transaction.

     The default transaction isolation level can also be set at runtime
     using the 'SET TRANSACTION' statement or by
     setting the 'tx_isolation' (or, as of MySQL 5.7.20,
     'transaction_isolation') system variable.

   *
     '--transaction-read-only'

     Property                             Value

     *Command-Line Format*                '--transaction-read-only'

     *System Variable* (>= 5.7.20)        'transaction_read_only'

     *Scope* (>= 5.7.20)                  Global, Session

     *Dynamic* (>= 5.7.20)                Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Sets the default transaction access mode.  By default, read-only
     mode is disabled, so the mode is read/write.

     To set the default transaction access mode at runtime, use the
     'SET TRANSACTION' statement or set the
     'tx_read_only' (or, as of MySQL 5.7.20, 'transaction_read_only')
     system variable.  See set-transaction.

   *
     '--tmpdir=DIR_NAME', '-t DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--tmpdir=dir_name'

     *System Variable*                    'tmpdir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The path of the directory to use for creating temporary files.  It
     might be useful if your default '/tmp' directory resides on a
     partition that is too small to hold temporary tables.  This option
     accepts several paths that are used in round-robin fashion.  Paths
     should be separated by colon characters (':') on Unix and semicolon
     characters (';') on Windows.  If the MySQL server is acting as a
     replication slave, you should not set '--tmpdir' to point to a
     directory on a memory-based file system or to a directory that is
     cleared when the server host restarts.  For more information about
     the storage location of temporary files, see
     temporary-files.  A replication slave needs some of its temporary
     files to survive a machine restart so that it can replicate
     temporary tables or 'LOAD DATA INFILE'.
     operations.  If files in the temporary file directory are lost when
     the server restarts, replication fails.

   *
     '--user={USER_NAME|USER_ID}', '-u {USER_NAME|USER_ID}'

     Property                             Value

     *Command-Line Format*                '--user=name'

     *Type*                               string

     Run the 'mysqld' server as the user having the name
     USER_NAME or the numeric user ID USER_ID.  ('User' in this context
     refers to a system login account, not a MySQL user listed in the
     grant tables.)

     This option is _mandatory_ when starting 'mysqld' as
     'root'.  The server changes its user ID during its startup
     sequence, causing it to run as that particular user rather than as
     'root'.  See security-guidelines.

     To avoid a possible security hole where a user adds a '--user=root'
     option to a 'my.cnf' file (thus causing the server to run as
     'root'), see 'mysqld' uses only the first '--user'
     option specified and produces a warning if there are multiple
     '--user' options.  Options in '/etc/my.cnf' and
     '$MYSQL_HOME/my.cnf' are processed before command-line options, so
     it is recommended that you put a '--user' option in '/etc/my.cnf'
     and specify a value other than 'root'.  The option in '/etc/my.cnf'
     is found before any other '--user' options, which ensures that the
     server runs as a user other than 'root', and that a warning results
     if any other '--user' option is found.

   *
     '--verbose', '-v'

     Use this option with the '--help' option for detailed help.

   *
     '--version', '-V'

     Display version information and exit.

5.1.5 Server System Variables
-----------------------------

The MySQL server maintains many system variables that indicate how it is
configured.  Each system variable has a default value.  System variables
can be set at server startup using options on the command line or in an
option file.  Most of them can be changed dynamically at runtime using
the 'SET' statement, which enables you to modify
operation of the server without having to stop and restart it.  You can
also use system variable values in expressions.

At runtime, setting the global value of a system variable normally
requires the 'SUPER' privilege, with exceptions as noted in individual
variable descriptions.  For some system variables, setting the session
value also requires the 'SUPER' privilege; again, with exceptions as
noted in individual variable descriptions.

There are several ways to see the names and values of system variables:

   * To see the values that a server will use based on its compiled-in
     defaults and any option files that it reads, use this command:

          mysqld --verbose --help

   * To see the values that a server will use based on its compiled-in
     defaults, ignoring the settings in any option files, use this
     command:

          mysqld --no-defaults --verbose --help

   * To see the current values used by a running server, use the
     'SHOW VARIABLES' statement or the Performance
     Schema system variable tables.  See
     performance-schema-system-variable-tables.

This section includes a table that lists all system variables and
following the table provides a description of each one.  Variables with
no version indicated are present in all MySQL 5.7 releases.  For more
information about manipulation of system variables, see
using-system-variables.

*System Variable Summary*

Name           Cmd-Line    Option      System      Var Scope   Dynamic
                           File        Var

audit_log_buffer_sizeYes   Yes         Yes         Global      No

audit_log_compressionYes   Yes         Yes         Global      No

audit_log_connection_policyYesYes      Yes         Global      Yes

audit_log_current_session              Yes         Both        No

audit_log_encryptionYes    Yes         Yes         Global      No

audit_log_exclude_accountsYesYes       Yes         Global      Yes

audit_log_file Yes         Yes         Yes         Global      No

audit_log_filter_id                    Yes         Both        No

audit_log_flush                        Yes         Global      Yes

audit_log_formatYes        Yes         Yes         Global      No

audit_log_include_accountsYesYes       Yes         Global      Yes

audit_log_policyYes        Yes         Yes         Global      No

audit_log_read_buffer_sizeYesYes       Yes         Global      No

audit_log_rotate_on_sizeYesYes         Yes         Global      Yes

audit_log_statement_policyYesYes       Yes         Global      Yes

audit_log_strategyYes      Yes         Yes         Global      No

authentication_ldap_sasl_auth_method_nameYesYesYes Global      Yes

authentication_ldap_sasl_bind_base_dnYesYesYes     Global      Yes

authentication_ldap_sasl_bind_root_dnYesYesYes     Global      Yes

authentication_ldap_sasl_bind_root_pwdYesYesYes    Global      Yes

authentication_ldap_sasl_ca_pathYesYes Yes         Global      Yes

authentication_ldap_sasl_group_search_attrYesYesYesGlobal      Yes

authentication_ldap_sasl_group_search_filterYesYesYesGlobal    Yes

authentication_ldap_sasl_init_pool_sizeYesYesYes   Global      Yes

authentication_ldap_sasl_log_statusYesYesYes       Global      Yes

authentication_ldap_sasl_max_pool_sizeYesYesYes    Global      Yes

authentication_ldap_sasl_server_hostYesYesYes      Global      Yes

authentication_ldap_sasl_server_portYesYesYes      Global      Yes

authentication_ldap_sasl_tlsYesYes     Yes         Global      Yes

authentication_ldap_sasl_user_search_attrYesYesYes Global      Yes

authentication_ldap_simple_auth_method_nameYesYesYesGlobal     Yes

authentication_ldap_simple_bind_base_dnYesYesYes   Global      Yes

authentication_ldap_simple_bind_root_dnYesYesYes   Global      Yes

authentication_ldap_simple_bind_root_pwdYesYesYes  Global      Yes

authentication_ldap_simple_ca_pathYesYesYes        Global      Yes

authentication_ldap_simple_group_search_attrYesYesYesGlobal    Yes

authentication_ldap_simple_group_search_filterYesYesYesGlobal  Yes

authentication_ldap_simple_init_pool_sizeYesYesYes Global      Yes

authentication_ldap_simple_log_statusYesYesYes     Global      Yes

authentication_ldap_simple_max_pool_sizeYesYesYes  Global      Yes

authentication_ldap_simple_server_hostYesYesYes    Global      Yes

authentication_ldap_simple_server_portYesYesYes    Global      Yes

authentication_ldap_simple_tlsYesYes   Yes         Global      Yes

authentication_ldap_simple_user_search_attrYesYesYesGlobal     Yes

auto_generate_certsYes     Yes         Yes         Global      No

auto_increment_increment               Yes         Both        Yes

auto_increment_offset                  Yes         Both        Yes

autocommit     Yes         Yes         Yes         Both        Yes

automatic_sp_privileges                Yes         Global      Yes

avoid_temporal_upgradeYes  Yes         Yes         Global      Yes

back_log                               Yes         Global      No

basedir        Yes         Yes         Yes         Global      No

big-tables     Yes         Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
big_tables

bind-address   Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
bind_address

binlog_cache_sizeYes       Yes         Yes         Global      Yes

binlog_checksum                        Yes         Global      Yes

binlog_direct_non_transactional_updatesYesYesYes   Both        Yes

binlog_error_actionYes     Yes         Yes         Global      Yes

binlog-format  Yes         Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
binlog_format

binlog_group_commit_sync_delayYesYes   Yes         Global      Yes

binlog_group_commit_sync_no_delay_countYesYesYes   Global      Yes

binlog_gtid_simple_recoveryYesYes      Yes         Global      No

binlog_max_flush_queue_time            Yes         Global      Yes

binlog_order_commits                   Yes         Global      Yes

binlog_row_imageYes        Yes         Yes         Both        Yes

binlog_rows_query_log_eventsYesYes     Yes         Both        Yes

binlog_stmt_cache_sizeYes  Yes         Yes         Global      Yes

binlog_transaction_dependency_history_sizeYesYesYesGlobal      Yes

binlog_transaction_dependency_trackingYesYesYes    Global      Yes

binlogging_impossible_modeYesYes       Yes         Both        Yes

block_encryption_modeYes   Yes         Yes         Both        Yes

bulk_insert_buffer_sizeYes Yes         Yes         Both        Yes

character_set_client                   Yes         Both        Yes

character_set_connection               Yes         Both        Yes

character_set_database                 Yes         Both        Yes
(note 1)

character-set-filesystemYesYes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
character_set_filesystem

character_set_results                  Yes         Both        Yes

character-set-serverYes    Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
character_set_server

character_set_system                   Yes         Global      No

character-sets-dirYes      Yes                                 No

-                                      Yes         Global      No
_Variable_:
character_sets_dir

check_proxy_usersYes       Yes         Yes         Global      Yes

collation_connection                   Yes         Both        Yes

collation_database                     Yes         Both        Yes
(note 1)

collation-serverYes        Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
collation_server

completion_typeYes         Yes         Yes         Both        Yes

concurrent_insertYes       Yes         Yes         Global      Yes

connect_timeoutYes         Yes         Yes         Global      Yes

connection_control_failed_connections_thresholdYesYesYesGlobal Yes

connection_control_max_connection_delayYesYesYes   Global      Yes

connection_control_min_connection_delayYesYesYes   Global      Yes

core_file                              Yes         Global      No

daemon_memcached_enable_binlogYesYes   Yes         Global      No

daemon_memcached_engine_lib_nameYesYes Yes         Global      No

daemon_memcached_engine_lib_pathYesYes Yes         Global      No

daemon_memcached_optionYes Yes         Yes         Global      No

daemon_memcached_r_batch_sizeYesYes    Yes         Global      No

daemon_memcached_w_batch_sizeYesYes    Yes         Global      No

datadir        Yes         Yes         Yes         Global      No

date_format                            Yes         Global      No

datetime_format                        Yes         Global      No

debug          Yes         Yes         Yes         Both        Yes

debug_sync                             Yes         Session     Yes

default_authentication_pluginYesYes    Yes         Global      No

default_password_lifetimeYesYes        Yes         Global      Yes

default-storage-engineYes  Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
default_storage_engine

default_tmp_storage_engineYesYes       Yes         Both        Yes

default_week_formatYes     Yes         Yes         Both        Yes

delay-key-writeYes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
delay_key_write

delayed_insert_limitYes    Yes         Yes         Global      Yes

delayed_insert_timeoutYes  Yes         Yes         Global      Yes

delayed_queue_sizeYes      Yes         Yes         Global      Yes

disabled_storage_enginesYesYes         Yes         Global      No

disconnect_on_expired_passwordYesYes   Yes         Session     No

div_precision_incrementYes Yes         Yes         Both        Yes

end_markers_in_json                    Yes         Both        Yes

enforce-gtid-consistencyYesYes         Yes         Global      Varies

enforce_gtid_consistencyYesYes         Yes         Global      Varies

eq_range_index_dive_limit              Yes         Both        Yes

error_count                            Yes         Session     No

event-schedulerYes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
event_scheduler

executed_gtids_compression_period      Yes         Global      Yes

expire_logs_daysYes        Yes         Yes         Global      Yes

explicit_defaults_for_timestampYesYes  Yes         Both        Yes

external_user                          Yes         Session     No

flush          Yes         Yes         Yes         Global      Yes

flush_time     Yes         Yes         Yes         Global      Yes

foreign_key_checks                     Yes         Both        Yes

ft_boolean_syntaxYes       Yes         Yes         Global      Yes

ft_max_word_lenYes         Yes         Yes         Global      No

ft_min_word_lenYes         Yes         Yes         Global      No

ft_query_expansion_limitYesYes         Yes         Global      No

ft_stopword_fileYes        Yes         Yes         Global      No

general-log    Yes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
general_log

general_log_fileYes        Yes         Yes         Global      Yes

group_concat_max_lenYes    Yes         Yes         Both        Yes

group_replication_allow_local_disjoint_gtids_joinYesYesYesGlobalYes

group_replication_allow_local_lower_version_joinYesYesYesGlobalYes

group_replication_auto_increment_incrementYesYesYesGlobal      Yes

group_replication_bootstrap_groupYesYesYes         Global      Yes

group_replication_components_stop_timeoutYesYesYes Global      Yes

group_replication_compression_thresholdYesYesYes   Global      Yes

group_replication_enforce_update_everywhere_checksYesYesYesGlobalYes

group_replication_flow_control_applier_thresholdYesYesYesGlobalYes

group_replication_flow_control_certifier_thresholdYesYesYesGlobalYes

group_replication_flow_control_modeYesYesYes       Global      Yes

group_replication_force_membersYesYes  Yes         Global      Yes

group_replication_group_nameYesYes     Yes         Global      Yes

group_replication_group_seedsYesYes    Yes         Global      Yes

group_replication_gtid_assignment_block_sizeYesYesYesGlobal    Yes

group_replication_ip_whitelistYesYes   Yes         Global      Yes

group_replication_local_addressYesYes  Yes         Global      Yes

group_replication_member_weightYesYes  Yes         Global      Yes

group_replication_poll_spin_loopsYesYesYes         Global      Yes

group_replication_recovery_complete_atYesYesYes    Global      Yes

group_replication_recovery_reconnect_intervalYesYesYesGlobal   Yes

group_replication_recovery_retry_countYesYesYes    Global      Yes

group_replication_recovery_ssl_caYesYesYes         Global      Yes

group_replication_recovery_ssl_capathYesYesYes     Global      Yes

group_replication_recovery_ssl_certYesYesYes       Global      Yes

group_replication_recovery_ssl_cipherYesYesYes     Global      Yes

group_replication_recovery_ssl_crlYesYesYes        Global      Yes

group_replication_recovery_ssl_crlpathYesYesYes    Global      Yes

group_replication_recovery_ssl_keyYesYesYes        Global      Yes

group_replication_recovery_ssl_verify_server_certYesYesYesGlobalYes

group_replication_recovery_use_sslYesYesYes        Global      Yes

group_replication_single_primary_modeYesYesYes     Global      Yes

group_replication_ssl_modeYesYes       Yes         Global      Yes

group_replication_start_on_bootYesYes  Yes         Global      Yes

group_replication_transaction_size_limitYesYesYes  Global      Yes

group_replication_unreachable_majority_timeoutYesYesYesGlobal  Yes

gtid_executed                          Yes         Varies      No

gtid_executed_compression_period       Yes         Global      Yes

gtid-mode      Yes         Yes                                 Varies

-                                      Yes         Global      Varies
_Variable_:
gtid_mode

gtid_mode                              Yes         Global      Varies

gtid_next                              Yes         Session     Yes

gtid_owned                             Yes         Both        No

gtid_purged                            Yes         Global      Yes

have_compress                          Yes         Global      No

have_crypt                             Yes         Global      No

have_dynamic_loading                   Yes         Global      No

have_geometry                          Yes         Global      No

have_openssl                           Yes         Global      No

have_profiling                         Yes         Global      No

have_query_cache                       Yes         Global      No

have_rtree_keys                        Yes         Global      No

have_ssl                               Yes         Global      No

have_statement_timeout                 Yes         Global      No

have_symlink                           Yes         Global      No

host_cache_size                        Yes         Global      Yes

hostname                               Yes         Global      No

identity                               Yes         Session     Yes

ignore-builtin-innodbYes   Yes                                 No

-                                      Yes         Global      No
_Variable_:
ignore_builtin_innodb

ignore_db_dirs                         Yes         Global      No

init_connect   Yes         Yes         Yes         Global      Yes

init-file      Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
init_file

init_slave     Yes         Yes         Yes         Global      Yes

innodb_adaptive_flushingYesYes         Yes         Global      Yes

innodb_adaptive_flushing_lwmYesYes     Yes         Global      Yes

innodb_adaptive_hash_indexYesYes       Yes         Global      Yes

innodb_adaptive_hash_index_partsYesYes Yes         Global      No

innodb_adaptive_max_sleep_delayYesYes  Yes         Global      Yes

innodb_additional_mem_pool_sizeYesYes  Yes         Global      No

innodb_api_bk_commit_intervalYesYes    Yes         Global      Yes

innodb_api_disable_rowlockYesYes       Yes         Global      No

innodb_api_enable_binlogYesYes         Yes         Global      No

innodb_api_enable_mdlYes   Yes         Yes         Global      No

innodb_api_trx_levelYes    Yes         Yes         Global      Yes

innodb_autoextend_incrementYesYes      Yes         Global      Yes

innodb_autoinc_lock_modeYesYes         Yes         Global      No

innodb_background_drop_list_emptyYesYesYes         Global      Yes

innodb_buffer_pool_chunk_sizeYesYes    Yes         Global      No

innodb_buffer_pool_dump_at_shutdownYesYesYes       Global      Yes

innodb_buffer_pool_dump_nowYesYes      Yes         Global      Yes

innodb_buffer_pool_dump_pctYesYes      Yes         Global      Yes

innodb_buffer_pool_filenameYesYes      Yes         Global      Yes

innodb_buffer_pool_instancesYesYes     Yes         Global      No

innodb_buffer_pool_load_abortYesYes    Yes         Global      Yes

innodb_buffer_pool_load_at_startupYesYesYes        Global      No

innodb_buffer_pool_load_nowYesYes      Yes         Global      Yes

innodb_buffer_pool_sizeYes Yes         Yes         Global      Varies

innodb_change_buffer_max_sizeYesYes    Yes         Global      Yes

innodb_change_bufferingYes Yes         Yes         Global      Yes

innodb_change_buffering_debugYesYes    Yes         Global      Yes

innodb_checksum_algorithmYesYes        Yes         Global      Yes

innodb_checksumsYes        Yes         Yes         Global      No

innodb_cmp_per_index_enabledYesYes     Yes         Global      Yes

innodb_commit_concurrencyYesYes        Yes         Global      Yes

innodb_compress_debugYes   Yes         Yes         Global      Yes

innodb_compression_failure_threshold_pctYesYesYes  Global      Yes

innodb_compression_levelYesYes         Yes         Global      Yes

innodb_compression_pad_pct_maxYesYes   Yes         Global      Yes

innodb_concurrency_ticketsYesYes       Yes         Global      Yes

innodb_data_file_pathYes   Yes         Yes         Global      No

innodb_data_home_dirYes    Yes         Yes         Global      No

innodb_deadlock_detectYes  Yes         Yes         Global      Yes

innodb_default_row_formatYesYes        Yes         Global      Yes

innodb_disable_resize_buffer_pool_debugYesYesYes   Global      Yes

innodb_disable_sort_file_cacheYesYes   Yes         Global      Yes

innodb_doublewriteYes      Yes         Yes         Global      No

innodb_fast_shutdownYes    Yes         Yes         Global      Yes

innodb_fil_make_page_dirty_debugYesYes Yes         Global      Yes

innodb_file_formatYes      Yes         Yes         Global      Yes

innodb_file_format_checkYesYes         Yes         Global      No

innodb_file_format_maxYes  Yes         Yes         Global      Yes

innodb_file_per_tableYes   Yes         Yes         Global      Yes

innodb_fill_factorYes      Yes         Yes         Global      Yes

innodb_flush_log_at_timeout            Yes         Global      Yes

innodb_flush_log_at_trx_commitYesYes   Yes         Global      Yes

innodb_flush_methodYes     Yes         Yes         Global      No

innodb_flush_neighborsYes  Yes         Yes         Global      Yes

innodb_flush_syncYes       Yes         Yes         Global      Yes

innodb_flushing_avg_loopsYesYes        Yes         Global      Yes

innodb_force_load_corruptedYesYes      Yes         Global      No

innodb_force_recoveryYes   Yes         Yes         Global      No

innodb_ft_aux_tableYes     Yes         Yes         Global      Yes

innodb_ft_cache_sizeYes    Yes         Yes         Global      No

innodb_ft_enable_diag_printYesYes      Yes         Global      Yes

innodb_ft_enable_stopwordYesYes        Yes         Global      Yes

innodb_ft_max_token_sizeYesYes         Yes         Global      No

innodb_ft_min_token_sizeYesYes         Yes         Global      No

innodb_ft_num_word_optimizeYesYes      Yes         Global      Yes

innodb_ft_result_cache_limitYesYes     Yes         Global      Yes

innodb_ft_server_stopword_tableYesYes  Yes         Global      Yes

innodb_ft_sort_pll_degreeYesYes        Yes         Global      No

innodb_ft_total_cache_sizeYesYes       Yes         Global      No

innodb_ft_user_stopword_tableYesYes    Yes         Both        Yes

innodb_io_capacityYes      Yes         Yes         Global      Yes

innodb_io_capacity_maxYes  Yes         Yes         Global      Yes

innodb_large_prefixYes     Yes         Yes         Global      Yes

innodb_limit_optimistic_insert_debugYesYesYes      Global      Yes

innodb_lock_wait_timeoutYesYes         Yes         Both        Yes

innodb_locks_unsafe_for_binlogYesYes   Yes         Global      No

innodb_log_buffer_sizeYes  Yes         Yes         Global      No

innodb_log_checksum_algorithmYesYes    Yes         Global      Yes

innodb_log_checksumsYes    Yes         Yes         Global      Yes

innodb_log_compressed_pagesYesYes      Yes         Global      Yes

innodb_log_file_sizeYes    Yes         Yes         Global      No

innodb_log_files_in_groupYesYes        Yes         Global      No

innodb_log_group_home_dirYesYes        Yes         Global      No

innodb_log_write_ahead_sizeYesYes      Yes         Global      Yes

innodb_lru_scan_depthYes   Yes         Yes         Global      Yes

innodb_max_dirty_pages_pctYesYes       Yes         Global      Yes

innodb_max_dirty_pages_pct_lwmYesYes   Yes         Global      Yes

innodb_max_purge_lagYes    Yes         Yes         Global      Yes

innodb_max_purge_lag_delayYesYes       Yes         Global      Yes

innodb_max_undo_log_sizeYesYes         Yes         Global      Yes

innodb_merge_threshold_set_all_debugYesYesYes      Global      Yes

innodb_monitor_disableYes  Yes         Yes         Global      Yes

innodb_monitor_enableYes   Yes         Yes         Global      Yes

innodb_monitor_resetYes    Yes         Yes         Global      Yes

innodb_monitor_reset_allYesYes         Yes         Global      Yes

innodb_numa_interleaveYes  Yes         Yes         Global      No

innodb_old_blocks_pctYes   Yes         Yes         Global      Yes

innodb_old_blocks_timeYes  Yes         Yes         Global      Yes

innodb_online_alter_log_max_sizeYesYes Yes         Global      Yes

innodb_open_filesYes       Yes         Yes         Global      No

innodb_optimize_fulltext_onlyYesYes    Yes         Global      Yes

innodb_optimize_point_storageYesYes    Yes         Session     Yes

innodb_page_cleanersYes    Yes         Yes         Global      No

innodb_page_sizeYes        Yes         Yes         Global      No

innodb_print_all_deadlocksYesYes       Yes         Global      Yes

innodb_purge_batch_sizeYes Yes         Yes         Global      Yes

innodb_purge_rseg_truncate_frequencyYesYesYes      Global      Yes

innodb_purge_threadsYes    Yes         Yes         Global      No

innodb_random_read_aheadYesYes         Yes         Global      Yes

innodb_read_ahead_thresholdYesYes      Yes         Global      Yes

innodb_read_io_threadsYes  Yes         Yes         Global      No

innodb_read_onlyYes        Yes         Yes         Global      No

innodb_replication_delayYesYes         Yes         Global      Yes

innodb_rollback_on_timeoutYesYes       Yes         Global      No

innodb_rollback_segmentsYesYes         Yes         Global      Yes

innodb_saved_page_number_debugYesYes   Yes         Global      Yes

innodb_sort_buffer_sizeYes Yes         Yes         Global      No

innodb_spin_wait_delayYes  Yes         Yes         Global      Yes

innodb_stats_auto_recalcYesYes         Yes         Global      Yes

innodb_stats_include_delete_markedYesYesYes        Global      Yes

innodb_stats_methodYes     Yes         Yes         Global      Yes

innodb_stats_on_metadataYesYes         Yes         Global      Yes

innodb_stats_persistentYes Yes         Yes         Global      Yes

innodb_stats_persistent_sample_pagesYesYesYes      Global      Yes

innodb_stats_sample_pagesYesYes        Yes         Global      Yes

innodb_stats_transient_sample_pagesYesYesYes       Global      Yes

innodb_status_outputYes    Yes         Yes         Global      Yes

innodb_status_output_locksYesYes       Yes         Global      Yes

innodb_strict_modeYes      Yes         Yes         Both        Yes

innodb_support_xaYes       Yes         Yes         Both        Yes

innodb_sync_array_sizeYes  Yes         Yes         Global      No

innodb_sync_debugYes       Yes         Yes         Global      No

innodb_sync_spin_loopsYes  Yes         Yes         Global      Yes

innodb_table_locksYes      Yes         Yes         Both        Yes

innodb_temp_data_file_pathYesYes       Yes         Global      No

innodb_thread_concurrencyYesYes        Yes         Global      Yes

innodb_thread_sleep_delayYesYes        Yes         Global      Yes

innodb_tmpdir  Yes         Yes         Yes         Both        Yes

innodb_trx_purge_view_update_only_debugYesYesYes   Global      Yes

innodb_trx_rseg_n_slots_debugYesYes    Yes         Global      Yes

innodb_undo_directoryYes   Yes         Yes         Global      No

innodb_undo_log_truncateYesYes         Yes         Global      Yes

innodb_undo_logsYes        Yes         Yes         Global      Yes

innodb_undo_tablespacesYes Yes         Yes         Global      No

innodb_use_native_aioYes   Yes         Yes         Global      No

innodb_use_sys_mallocYes   Yes         Yes         Global      No

innodb_version                         Yes         Global      No

innodb_write_io_threadsYes Yes         Yes         Global      No

insert_id                              Yes         Session     Yes

interactive_timeoutYes     Yes         Yes         Both        Yes

internal_tmp_disk_storage_engineYesYes Yes         Global      Yes

join_buffer_sizeYes        Yes         Yes         Both        Yes

keep_files_on_createYes    Yes         Yes         Both        Yes

key_buffer_sizeYes         Yes         Yes         Global      Yes

key_cache_age_thresholdYes Yes         Yes         Global      Yes

key_cache_block_sizeYes    Yes         Yes         Global      Yes

key_cache_division_limitYesYes         Yes         Global      Yes

keyring_aws_cmk_idYes      Yes         Yes         Global      Yes

keyring_aws_conf_fileYes   Yes         Yes         Global      No

keyring_aws_data_fileYes   Yes         Yes         Global      No

keyring_aws_regionYes      Yes         Yes         Global      Yes

keyring_encrypted_file_dataYesYes      Yes         Global      Yes

keyring_encrypted_file_passwordYesYes  Yes         Global      Yes

keyring_file_dataYes       Yes         Yes         Global      Yes

keyring_okv_conf_dirYes    Yes         Yes         Global      Yes

keyring_operations                     Yes         Global      Yes

language       Yes         Yes         Yes         Global      No

large_files_support                    Yes         Global      No

large_page_size                        Yes         Global      No

large-pages    Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
large_pages

last_insert_id                         Yes         Session     Yes

lc-messages    Yes         Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
lc_messages

lc-messages-dirYes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
lc_messages_dir

lc_time_names                          Yes         Both        Yes

license                                Yes         Global      No

local_infile                           Yes         Global      Yes

lock_wait_timeoutYes       Yes         Yes         Both        Yes

locked_in_memory                       Yes         Global      No

log_backward_compatible_user_definitionsYesYesYes  Global      Yes

log-bin        Yes         Yes         Yes         Global      No

log_bin                                Yes         Global      No

log_bin_basename                       Yes         Global      No

log_bin_index                          Yes         Global      No

log-bin-trust-function-creatorsYesYes                          Yes

-                                      Yes         Global      Yes
_Variable_:
log_bin_trust_function_creators

log-bin-use-v1-row-eventsYesYes                                No

-                                      Yes         Global      No
_Variable_:
log_bin_use_v1_row_events

log_bin_use_v1_row_eventsYesYes        Yes         Global      No

log_builtin_as_identified_by_passwordYesYesYes     Global      Yes

log-error      Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
log_error

log_error_verbosityYes     Yes         Yes         Global      Yes

log-output     Yes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
log_output

log-queries-not-using-indexesYesYes                            Yes

-                                      Yes         Global      Yes
_Variable_:
log_queries_not_using_indexes

log-slave-updatesYes       Yes                                 No

-                                      Yes         Global      No
_Variable_:
log_slave_updates

log_slave_updatesYes       Yes         Yes         Global      No

log_slow_admin_statements              Yes         Global      Yes

log_slow_slave_statements              Yes         Global      Yes

log_statements_unsafe_for_binlog       Yes         Global      Yes

log_syslog     Yes         Yes         Yes         Global      Yes

log_syslog_facilityYes     Yes         Yes         Global      Yes

log_syslog_include_pidYes  Yes         Yes         Global      Yes

log_syslog_tag Yes         Yes         Yes         Global      Yes

log_throttle_queries_not_using_indexes Yes         Global      Yes

log_timestamps Yes         Yes         Yes         Global      Yes

log-warnings   Yes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
log_warnings

long_query_timeYes         Yes         Yes         Both        Yes

low-priority-updatesYes    Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
low_priority_updates

lower_case_file_system                 Yes         Global      No

lower_case_table_namesYes  Yes         Yes         Global      No

master_info_repositoryYes  Yes         Yes         Global      Yes

master_verify_checksum                 Yes         Global      Yes

max_allowed_packetYes      Yes         Yes         Both        Yes

max_binlog_cache_sizeYes   Yes         Yes         Global      Yes

max_binlog_sizeYes         Yes         Yes         Global      Yes

max_binlog_stmt_cache_sizeYesYes       Yes         Global      Yes

max_connect_errorsYes      Yes         Yes         Global      Yes

max_connectionsYes         Yes         Yes         Global      Yes

max_delayed_threadsYes     Yes         Yes         Both        Yes

max_digest_lengthYes       Yes         Yes         Global      No

max_error_countYes         Yes         Yes         Both        Yes

max_execution_timeYes      Yes         Yes         Both        Yes

max_heap_table_sizeYes     Yes         Yes         Both        Yes

max_insert_delayed_threads             Yes         Both        Yes

max_join_size  Yes         Yes         Yes         Both        Yes

max_length_for_sort_dataYesYes         Yes         Both        Yes

max_points_in_geometryYes  Yes         Yes         Both        Yes

max_prepared_stmt_countYes Yes         Yes         Global      Yes

max_relay_log_sizeYes      Yes         Yes         Global      Yes

max_seeks_for_keyYes       Yes         Yes         Both        Yes

max_sort_lengthYes         Yes         Yes         Both        Yes

max_sp_recursion_depthYes  Yes         Yes         Both        Yes

max_statement_time                     Yes         Both        Yes

max_tmp_tables                         Yes         Both        Yes

max_user_connectionsYes    Yes         Yes         Both        Yes

max_write_lock_countYes    Yes         Yes         Global      Yes

mecab_rc_file  Yes         Yes         Yes         Global      No

metadata_locks_cache_size              Yes         Global      No

metadata_locks_hash_instances          Yes         Global      No

min-examined-row-limitYes  Yes         Yes         Both        Yes

multi_range_countYes       Yes         Yes         Both        Yes

myisam_data_pointer_sizeYesYes         Yes         Global      Yes

myisam_max_sort_file_sizeYesYes        Yes         Global      Yes

myisam_mmap_sizeYes        Yes         Yes         Global      No

myisam_recover_options                 Yes         Global      No

myisam_repair_threadsYes   Yes         Yes         Both        Yes

myisam_sort_buffer_sizeYes Yes         Yes         Both        Yes

myisam_stats_methodYes     Yes         Yes         Both        Yes

myisam_use_mmapYes         Yes         Yes         Global      Yes

mysql_firewall_modeYes     Yes         Yes         Global      Yes

mysql_firewall_traceYes    Yes         Yes         Global      Yes

mysql_native_password_proxy_usersYesYesYes         Global      Yes

mysqlx-bind-addressYes     Yes         Yes         Global      No

mysqlx_bind_addressYes     Yes         Yes         Global      No

mysqlx-connect-timeoutYes  Yes         Yes         Global      Yes

mysqlx_connect_timeoutYes  Yes         Yes         Global      Yes

mysqlx-idle-worker-thread-timeoutYesYesYes         Global      Yes

mysqlx_idle_worker_thread_timeoutYesYesYes         Global      Yes

mysqlx-max-allowed-packetYesYes        Yes         Global      Yes

mysqlx_max_allowed_packetYesYes        Yes         Global      Yes

mysqlx-max-connectionsYes  Yes         Yes         Global      Yes

mysqlx_max_connectionsYes  Yes         Yes         Global      Yes

mysqlx-min-worker-threadsYesYes        Yes         Global      Yes

mysqlx_min_worker_threadsYesYes        Yes         Global      Yes

mysqlx-port    Yes         Yes         Yes         Global      No

mysqlx_port    Yes         Yes         Yes         Global      No

mysqlx-port-open-timeoutYesYes         Yes         Global      No

mysqlx_port_open_timeoutYesYes         Yes         Global      No

mysqlx-socket  Yes         Yes         Yes         Global      No

mysqlx_socket  Yes         Yes         Yes         Global      No

mysqlx-ssl     Yes         Yes         Yes         Global      No

mysqlx-ssl-ca  Yes         Yes         Yes         Global      No

mysqlx-ssl-capathYes       Yes         Yes         Global      No

mysqlx-ssl-certYes         Yes         Yes         Global      No

mysqlx-ssl-crl Yes         Yes         Yes         Global      No

mysqlx-ssl-crlpathYes      Yes         Yes         Global      No

mysqlx-ssl-key Yes         Yes         Yes         Global      No

named_pipe                             Yes         Global      No

ndb-allow-copying-alter-tableYesYes    Yes         Both        Yes

ndb_autoincrement_prefetch_szYesYes    Yes         Both        Yes

ndb-batch-size Yes         Yes         Yes         Global      No

ndb-blob-read-batch-bytesYesYes        Yes         Both        Yes

ndb-blob-write-batch-bytesYesYes       Yes         Both        Yes

ndb_cache_check_timeYes    Yes         Yes         Global      Yes

ndb_clear_apply_statusYes              Yes         Global      Yes

ndb-cluster-connection-poolYesYes      Yes         Global      No

ndb-cluster-connection-pool-nodeidsYesYesYes       Global      No

ndb_data_node_neighbourYes Yes         Yes         Global      Yes

ndb-default-column-formatYesYes                                Yes

-                                      Yes         Global      Yes
_Variable_:
ndb_default_column_format

ndb_default_column_formatYesYes        Yes         Global      Yes

ndb-deferred-constraintsYesYes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
ndb_deferred_constraints

ndb_deferred_constraintsYesYes         Yes         Both        Yes

ndb-distributionYes        Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
ndb_distribution

ndb_distributionYes        Yes         Yes         Global      Yes

ndb_eventbuffer_free_percentYesYes     Yes         Global      Yes

ndb_eventbuffer_max_allocYesYes        Yes         Global      Yes

ndb_extra_loggingYes       Yes         Yes         Global      Yes

ndb_force_send Yes         Yes         Yes         Both        Yes

ndb_fully_replicatedYes    Yes         Yes         Both        Yes

ndb_index_stat_enableYes   Yes         Yes         Both        Yes

ndb_index_stat_optionYes   Yes         Yes         Both        Yes

ndb_join_pushdown                      Yes         Both        Yes

ndb-log-apply-statusYes    Yes                                 No

-                                      Yes         Global      No
_Variable_:
ndb_log_apply_status

ndb_log_apply_statusYes    Yes         Yes         Global      No

ndb_log_bin    Yes                     Yes         Both        Yes

ndb_log_binlog_indexYes                Yes         Global      Yes

ndb-log-empty-epochsYes    Yes         Yes         Global      Yes

ndb_log_empty_epochsYes    Yes         Yes         Global      Yes

ndb-log-empty-updateYes    Yes         Yes         Global      Yes

ndb_log_empty_updateYes    Yes         Yes         Global      Yes

ndb-log-exclusive-readsYes Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
ndb_log_exclusive_reads

ndb_log_exclusive_readsYes Yes         Yes         Both        Yes

ndb-log-orig   Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ndb_log_orig

ndb_log_orig   Yes         Yes         Yes         Global      No

ndb-log-transaction-idYes  Yes                                 No

-                                      Yes         Global      No
_Variable_:
ndb_log_transaction_id

ndb_log_transaction_id                 Yes         Global      No

ndb-log-update-minimalYes  Yes         Yes         Global      Yes

ndb_log_updated_onlyYes    Yes         Yes         Global      Yes

ndb_optimization_delay                 Yes         Global      Yes

ndb_optimized_node_selectionYesYes     Yes         Global      No

ndb_read_backupYes         Yes         Yes         Global      Yes

ndb_recv_thread_cpu_mask               Yes         Global      Yes

ndb_report_thresh_binlog_epoch_slipYesYesYes       Global      Yes

ndb_report_thresh_binlog_mem_usageYesYesYes        Global      Yes

ndb_show_foreign_key_mock_tablesYesYes Yes         Global      Yes

ndb_slave_conflict_roleYes Yes         Yes         Global      Yes

Ndb_slave_max_replicated_epoch         Yes         Global      No

Ndb_system_name                        Yes         Global      No

ndb_table_no_logging                   Yes         Session     Yes

ndb_table_temporary                    Yes         Session     Yes

ndb_use_copying_alter_table            Yes         Both        No

ndb_use_exact_count                    Yes         Both        Yes

ndb_use_transactionsYes    Yes         Yes         Both        Yes

ndb_version                            Yes         Global      No

ndb_version_string                     Yes         Global      No

ndb-wait-connectedYes      Yes         Yes         Global      No

ndb-wait-setup Yes         Yes         Yes         Global      No

ndbinfo_database                       Yes         Global      No

ndbinfo_max_bytesYes                   Yes         Both        Yes

ndbinfo_max_rowsYes                    Yes         Both        Yes

ndbinfo_offline                        Yes         Global      Yes

ndbinfo_show_hiddenYes                 Yes         Both        Yes

ndbinfo_table_prefixYes                Yes         Both        Yes

ndbinfo_version                        Yes         Global      No

net_buffer_lengthYes       Yes         Yes         Both        Yes

net_read_timeoutYes        Yes         Yes         Both        Yes

net_retry_countYes         Yes         Yes         Both        Yes

net_write_timeoutYes       Yes         Yes         Both        Yes

new            Yes         Yes         Yes         Both        Yes

ngram_token_sizeYes        Yes         Yes         Global      No

offline_mode   Yes         Yes         Yes         Global      Yes

old            Yes         Yes         Yes         Global      No

old-alter-tableYes         Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
old_alter_table

old_passwords                          Yes         Both        Yes

open-files-limitYes        Yes                                 No

-                                      Yes         Global      No
_Variable_:
open_files_limit

optimizer_prune_levelYes   Yes         Yes         Both        Yes

optimizer_search_depthYes  Yes         Yes         Both        Yes

optimizer_switchYes        Yes         Yes         Both        Yes

optimizer_trace                        Yes         Both        Yes

optimizer_trace_features               Yes         Both        Yes

optimizer_trace_limit                  Yes         Both        Yes

optimizer_trace_max_mem_size           Yes         Both        Yes

optimizer_trace_offset                 Yes         Both        Yes

parser_max_mem_sizeYes     Yes         Yes         Both        Yes

performance_schemaYes      Yes         Yes         Global      No

performance_schema_accounts_sizeYesYes Yes         Global      No

performance_schema_digests_sizeYesYes  Yes         Global      No

performance_schema_events_stages_history_long_sizeYesYesYesGlobalNo

performance_schema_events_stages_history_sizeYesYesYesGlobal   No

performance_schema_events_statements_history_long_sizeYesYesYesGlobalNo

performance_schema_events_statements_history_sizeYesYesYesGlobalNo

performance_schema_events_transactions_history_long_sizeYesYesYesGlobalNo

performance_schema_events_transactions_history_sizeYesYesYesGlobalNo

performance_schema_events_waits_history_long_sizeYesYesYesGlobalNo

performance_schema_events_waits_history_sizeYesYesYesGlobal    No

performance_schema_hosts_sizeYesYes    Yes         Global      No

performance_schema_max_cond_classesYesYesYes       Global      No

performance_schema_max_cond_instancesYesYesYes     Global      No

performance_schema_max_digest_lengthYesYesYes      Global      No

performance_schema_max_file_classesYesYesYes       Global      No

performance_schema_max_file_handlesYesYesYes       Global      No

performance_schema_max_file_instancesYesYesYes     Global      No

performance_schema_max_index_statYesYesYes         Global      No

performance_schema_max_memory_classesYesYesYes     Global      No

performance_schema_max_metadata_locksYesYesYes     Global      No

performance_schema_max_mutex_classesYesYesYes      Global      No

performance_schema_max_mutex_instancesYesYesYes    Global      No

performance_schema_max_prepared_statements_instancesYesYesYesGlobalNo

performance_schema_max_program_instancesYesYesYes  Global      No

performance_schema_max_rwlock_classesYesYesYes     Global      No

performance_schema_max_rwlock_instancesYesYesYes   Global      No

performance_schema_max_socket_classesYesYesYes     Global      No

performance_schema_max_socket_instancesYesYesYes   Global      No

performance_schema_max_sql_text_lengthYesYesYes    Global      No

performance_schema_max_stage_classesYesYesYes      Global      No

performance_schema_max_statement_classesYesYesYes  Global      No

performance_schema_max_statement_stackYesYesYes    Global      No

performance_schema_max_table_handlesYesYesYes      Global      No

performance_schema_max_table_instancesYesYesYes    Global      No

performance_schema_max_table_lock_statYesYesYes    Global      No

performance_schema_max_thread_classesYesYesYes     Global      No

performance_schema_max_thread_instancesYesYesYes   Global      No

performance_schema_session_connect_attrs_sizeYesYesYesGlobal   No

performance_schema_setup_actors_sizeYesYesYes      Global      No

performance_schema_setup_objects_sizeYesYesYes     Global      No

performance_schema_users_sizeYesYes    Yes         Global      No

pid-file       Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
pid_file

plugin_dir     Yes         Yes         Yes         Global      No

port           Yes         Yes         Yes         Global      No

preload_buffer_sizeYes     Yes         Yes         Both        Yes

profiling                              Yes         Both        Yes

profiling_history_sizeYes  Yes         Yes         Both        Yes

protocol_version                       Yes         Global      No

proxy_user                             Yes         Session     No

pseudo_slave_mode                      Yes         Session     Yes

pseudo_thread_id                       Yes         Session     Yes

query_alloc_block_sizeYes  Yes         Yes         Both        Yes

query_cache_limitYes       Yes         Yes         Global      Yes

query_cache_min_res_unitYesYes         Yes         Global      Yes

query_cache_sizeYes        Yes         Yes         Global      Yes

query_cache_typeYes        Yes         Yes         Both        Yes

query_cache_wlock_invalidateYesYes     Yes         Both        Yes

query_prealloc_sizeYes     Yes         Yes         Both        Yes

rand_seed1                             Yes         Session     Yes

rand_seed2                             Yes         Session     Yes

range_alloc_block_sizeYes  Yes         Yes         Both        Yes

range_optimizer_max_mem_sizeYesYes     Yes         Both        Yes

rbr_exec_mode                          Yes         Session     Yes

read_buffer_sizeYes        Yes         Yes         Both        Yes

read_only      Yes         Yes         Yes         Global      Yes

read_rnd_buffer_sizeYes    Yes         Yes         Both        Yes

relay-log      Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
relay_log

relay_log_basename                     Yes         Global      No

relay-log-indexYes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
relay_log_index

relay_log_indexYes         Yes         Yes         Global      No

relay_log_info_fileYes     Yes         Yes         Global      No

relay_log_info_repository              Yes         Global      Yes

relay_log_purgeYes         Yes         Yes         Global      Yes

relay_log_recoveryYes      Yes         Yes         Global      No

relay_log_space_limitYes   Yes         Yes         Global      No

report-host    Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
report_host

report-passwordYes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
report_password

report-port    Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
report_port

report-user    Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
report_user

require_secure_transportYesYes         Yes         Global      Yes

rewriter_enabled                       Yes         Global      Yes

rewriter_verbose                       Yes         Global      Yes

rpl_semi_sync_master_enabled           Yes         Global      Yes

rpl_semi_sync_master_timeout           Yes         Global      Yes

rpl_semi_sync_master_trace_level       Yes         Global      Yes

rpl_semi_sync_master_wait_for_slave_countYes       Global      Yes

rpl_semi_sync_master_wait_no_slave     Yes         Global      Yes

rpl_semi_sync_master_wait_point        Yes         Global      Yes

rpl_semi_sync_slave_enabled            Yes         Global      Yes

rpl_semi_sync_slave_trace_level        Yes         Global      Yes

rpl_stop_slave_timeoutYes  Yes         Yes         Global      Yes

secure-auth    Yes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
secure_auth

secure-file-privYes        Yes                                 No

-                                      Yes         Global      No
_Variable_:
secure_file_priv

server-id      Yes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
server_id

server-id-bits Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
server_id_bits

server_id_bits Yes         Yes         Yes         Global      No

server_uuid                            Yes         Global      No

session_track_gtidsYes     Yes         Yes         Both        Yes

session_track_schemaYes    Yes         Yes         Both        Yes

session_track_state_changeYesYes       Yes         Both        Yes

session_track_system_variablesYesYes   Yes         Both        Yes

sha256_password_auto_generate_rsa_keysYesYesYes    Global      No

sha256_password_private_key_pathYesYes Yes         Global      No

sha256_password_proxy_usersYesYes      Yes         Global      Yes

sha256_password_public_key_pathYesYes  Yes         Global      No

shared_memory  Yes         Yes         Yes         Global      No

shared_memory_base_nameYes Yes         Yes         Global      No

show_compatibility_56Yes   Yes         Yes         Global      Yes

show_create_table_verbosityYesYes      Yes         Both        Yes

show_old_temporalsYes      Yes         Yes         Both        Yes

simplified_binlog_gtid_recoveryYesYes  Yes         Global      No

skip_external_lockingYes   Yes         Yes         Global      No

skip-name-resolveYes       Yes                                 No

-                                      Yes         Global      No
_Variable_:
skip_name_resolve

skip-networkingYes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
skip_networking

skip-show-databaseYes      Yes                                 No

-                                      Yes         Global      No
_Variable_:
skip_show_database

slave_allow_batchingYes    Yes         Yes         Global      Yes

slave_checkpoint_groupYes  Yes         Yes         Global      Yes

slave_checkpoint_periodYes Yes         Yes         Global      Yes

slave_compressed_protocolYesYes        Yes         Global      Yes

slave_exec_modeYes         Yes         Yes         Global      Yes

slave-load-tmpdirYes       Yes                                 No

-                                      Yes         Global      No
_Variable_:
slave_load_tmpdir

slave_max_allowed_packet               Yes         Global      Yes

slave-net-timeoutYes       Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
slave_net_timeout

slave_parallel_type                    Yes         Global      Yes

slave_parallel_workersYes              Yes         Global      Yes

slave_pending_jobs_size_max            Yes         Global      Yes

slave_preserve_commit_orderYes         Yes         Global      Yes

slave_rows_search_algorithms           Yes         Global      Yes

slave-skip-errorsYes       Yes                                 No

-                                      Yes         Global      No
_Variable_:
slave_skip_errors

slave_sql_verify_checksum              Yes         Global      Yes

slave_transaction_retriesYesYes        Yes         Global      Yes

slave_type_conversionsYes  Yes         Yes         Global      No

slow_launch_timeYes        Yes         Yes         Global      Yes

slow-query-log Yes         Yes                                 Yes

-                                      Yes         Global      Yes
_Variable_:
slow_query_log

slow_query_log_fileYes     Yes         Yes         Global      Yes

socket         Yes         Yes         Yes         Global      No

sort_buffer_sizeYes        Yes         Yes         Both        Yes

sql_auto_is_null                       Yes         Both        Yes

sql_big_selects                        Yes         Both        Yes

sql_buffer_result                      Yes         Both        Yes

sql_log_bin                            Yes         Session     Yes

sql_log_off                            Yes         Both        Yes

sql-mode       Yes         Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
sql_mode

sql_notes                              Yes         Both        Yes

sql_quote_show_create                  Yes         Both        Yes

sql_safe_updates                       Yes         Both        Yes

sql_select_limit                       Yes         Both        Yes

sql_slave_skip_counter                 Yes         Global      Yes

sql_warnings                           Yes         Both        Yes

ssl-ca         Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ssl_ca

ssl-capath     Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ssl_capath

ssl-cert       Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ssl_cert

ssl-cipher     Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ssl_cipher

ssl-crl        Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ssl_crl

ssl-crlpath    Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ssl_crlpath

ssl-key        Yes         Yes                                 No

-                                      Yes         Global      No
_Variable_:
ssl_key

storage_engine                         Yes         Both        Yes

stored_program_cacheYes    Yes         Yes         Global      Yes

super_read_onlyYes         Yes         Yes         Global      Yes

sync_binlog    Yes         Yes         Yes         Global      Yes

sync_frm       Yes         Yes         Yes         Global      Yes

sync_master_infoYes        Yes         Yes         Global      Yes

sync_relay_log Yes         Yes         Yes         Global      Yes

sync_relay_log_infoYes     Yes         Yes         Global      Yes

system_time_zone                       Yes         Global      No

table_definition_cache                 Yes         Global      Yes

table_open_cache                       Yes         Global      Yes

table_open_cache_instances             Yes         Global      No

thread_cache_sizeYes       Yes         Yes         Global      Yes

thread_concurrencyYes      Yes         Yes         Global      No

thread_handlingYes         Yes         Yes         Global      No

thread_pool_algorithmYes   Yes         Yes         Global      No

thread_pool_high_priority_connectionYesYesYes      Both        Yes

thread_pool_max_unused_threadsYesYes   Yes         Global      Yes

thread_pool_prio_kickup_timerYesYes    Yes         Both        Yes

thread_pool_sizeYes        Yes         Yes         Global      No

thread_pool_stall_limitYes Yes         Yes         Global      Yes

thread_stack   Yes         Yes         Yes         Global      No

time_format                            Yes         Global      No

time_zone                              Yes         Both        Yes

timed_mutexes  Yes         Yes         Yes         Global      Yes

timestamp                              Yes         Session     Yes

tls_version    Yes         Yes         Yes         Global      No

tmp_table_size Yes         Yes         Yes         Both        Yes

tmpdir         Yes         Yes         Yes         Global      No

transaction_alloc_block_sizeYesYes     Yes         Both        Yes

transaction_allow_batching             Yes         Session     Yes

transaction-isolationYes   Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
tx_isolation

transaction_prealloc_sizeYesYes        Yes         Both        Yes

transaction-read-onlyYes   Yes                                 Yes

-                                      Yes         Both        Yes
_Variable_:
tx_read_only

transaction_write_set_extractionYes    Yes         Both        Yes

tx_isolation                           Yes         Both        Yes

tx_read_only                           Yes         Both        Yes

unique_checks                          Yes         Both        Yes

updatable_views_with_limitYesYes       Yes         Both        Yes

validate_password_check_user_nameYesYesYes         Global      Yes

validate_password_dictionary_file      Yes         Global      Varies

validate_password_length               Yes         Global      Yes

validate_password_mixed_case_count     Yes         Global      Yes

validate_password_number_count         Yes         Global      Yes

validate_password_policy               Yes         Global      Yes

validate_password_special_char_count   Yes         Global      Yes

validate_user_plugins                  Yes         Global      No

version                                Yes         Global      No

version_comment                        Yes         Global      No

version_compile_machine                Yes         Global      No

version_compile_os                     Yes         Global      No

version_tokens_sessionYes  Yes         Yes         Both        Yes

version_tokens_session_numberYesYes    Yes         Both        No

wait_timeout   Yes         Yes         Yes         Both        Yes

warning_count                          Yes         Session     No

*Notes:* 1.  This option is dynamic, but only the server should set this
information.  You should not set the value of this variable manually.

For additional system variable information, see these sections:

   * using-system-variables, discusses the syntax for setting
     and displaying system variable values.

   * dynamic-system-variables, lists the variables that can be
     set at runtime.

   * Information on tuning system variables can be found in
     server-configuration.

   * innodb-parameters, lists 'InnoDB' system variables.

   * mysql-cluster-system-variables, lists system variables
     which are specific to NDB Cluster.

   * For information on server system variables specific to replication,
     see replication-options.

*Note*:

Some of the following variable descriptions refer to 'enabling' or
'disabling' a variable.  These variables can be enabled with the
'SET' statement by setting them to 'ON' or '1', or
disabled by setting them to 'OFF' or '0'.  Boolean variables can be set
at startup to the values 'ON', 'TRUE', 'OFF', and 'FALSE' (not case
sensitive), as well as '1' and '0'.  See option-modifiers.

Some system variables control the size of buffers or caches.  For a
given buffer, the server might need to allocate internal data
structures.  These structures typically are allocated from the total
memory allocated to the buffer, and the amount of space required might
be platform dependent.  This means that when you assign a value to a
system variable that controls a buffer size, the amount of space
actually available might differ from the value assigned.  In some cases,
the amount might be less than the value assigned.  It is also possible
that the server will adjust a value upward.  For example, if you assign
a value of 0 to a variable for which the minimal value is 1024, the
server will set the value to 1024.

Values for buffer sizes, lengths, and stack sizes are given in bytes
unless otherwise specified.

Some system variables take file name values.  Unless otherwise
specified, the default file location is the data directory if the value
is a relative path name.  To specify the location explicitly, use an
absolute path name.  Suppose that the data directory is
'/var/mysql/data'.  If a file-valued variable is given as a relative
path name, it will be located under '/var/mysql/data'.  If the value is
an absolute path name, its location is as given by the path name.

   *
     'authentication_windows_log_level'

     Property                             Value

     *Command-Line Format*                '--authentication-windows-log-level'

     *Introduced*                         5.7.9

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4'

     This variable is available only if the 'authentication_windows'
     Windows authentication plugin is enabled and debugging code is
     enabled.  See windows-pluggable-authentication.

     This variable sets the logging level for the Windows authentication
     plugin.  The following table shows the permitted values.

     Value   Description

     0       No logging

     1       Log only error messages

     2       Log level 1 messages and warning messages

     3       Log level 2 messages and information notes

     4       Log level 3 messages and debug messages

   *
     'authentication_windows_use_principal_name'

     Property                             Value

     *Command-Line Format*                '--authentication-windows-use-principal-name'

     *Introduced*                         5.7.9

     *Type*                               boolean

     *Default Value*                      'ON'

     This variable is available only if the 'authentication_windows'
     Windows authentication plugin is enabled.  See
     windows-pluggable-authentication.

     A client that authenticates using the 'InitSecurityContext()'
     function should provide a string identifying the service to which
     it connects (TARGETNAME).  MySQL uses the principal name (UPN) of
     the account under which the server is running.  The UPN has the
     form 'USER_ID@COMPUTER_NAME' and need not be registered anywhere to
     be used.  This UPN is sent by the server at the beginning of
     authentication handshake.

     This variable controls whether the server sends the UPN in the
     initial challenge.  By default, the variable is enabled.  For
     security reasons, it can be disabled to avoid sending the server's
     account name to a client in clear text.  If the variable is
     disabled, the server always sends a '0x00' byte in the first
     challenge, the client does not specify TARGETNAME, and as a result,
     NTLM authentication is used.

     If the server fails to obtain its UPN (which will happen primarily
     in environments that do not support Kerberos authentication), the
     UPN is not sent by the server and NTLM authentication is used.

   *
     'autocommit'

     Property                             Value

     *Command-Line Format*                '--autocommit[=#]'

     *System Variable*                    'autocommit'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     The autocommit mode.  If set to 1, all changes to a table take
     effect immediately.  If set to 0, you must use 'COMMIT'
     to accept a transaction or 'ROLLBACK' to
     cancel it.  If 'autocommit' is 0 and you change it to 1, MySQL
     performs an automatic 'COMMIT' of any open
     transaction.  Another way to begin a transaction is to use a
     'START TRANSACTION' or 'BEGIN' statement.
     See commit.

     By default, client connections begin with 'autocommit' set to 1.
     To cause clients to begin with a default of 0, set the global
     'autocommit' value by starting the server with the '--autocommit=0'
     option.  To set the variable using an option file, include these
     lines:

          [mysqld]
          autocommit=0

   *
     'automatic_sp_privileges'

     Property                             Value

     *System Variable*                    'automatic_sp_privileges'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'TRUE'

     When this variable has a value of 1 (the default), the server
     automatically grants the 'EXECUTE' and 'ALTER ROUTINE' privileges
     to the creator of a stored routine, if the user cannot already
     execute and alter or drop the routine.  (The 'ALTER ROUTINE'
     privilege is required to drop the routine.)  The server also
     automatically drops those privileges from the creator when the
     routine is dropped.  If 'automatic_sp_privileges' is 0, the server
     does not automatically add or drop these privileges.

     The creator of a routine is the account used to execute the
     'CREATE' statement for it.  This might not be the same as the
     account named as the 'DEFINER' in the routine definition.

     See also stored-routines-privileges.

   *
     'auto_generate_certs'

     Property                             Value

     *Command-Line Format*                '--auto-generate-certs[={OFF|ON}]'

     *Introduced*                         5.7.5

     *System Variable*                    'auto_generate_certs'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     This variable is available if the server was compiled using OpenSSL
     (see ssl-libraries).  It controls whether the server
     autogenerates SSL key and certificate files in the data directory,
     if they do not already exist.

     At startup, the server automatically generates server-side and
     client-side SSL certificate and key files in the data directory if
     the 'auto_generate_certs' system variable is enabled, no SSL
     options other than '--ssl' are specified, and the server-side SSL
     files are missing from the data directory.  These files enable
     secure client connections using SSL; see
     using-encrypted-connections.

     For more information about SSL file autogeneration, including file
     names and characteristics, see
     creating-ssl-rsa-files-using-mysql

     The 'sha256_password_auto_generate_rsa_keys' system variable is
     related but controls autogeneration of RSA key-pair files needed
     for secure password exchange using RSA over unencypted connections.

   *
     'avoid_temporal_upgrade'

     Property                             Value

     *Command-Line Format*                '--avoid-temporal-upgrade={OFF|ON}'

     *Introduced*                         5.7.6

     *Deprecated*                         5.7.6

     *System Variable*                    'avoid_temporal_upgrade'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This variable controls whether 'ALTER TABLE'.
     implicitly upgrades temporal columns found to be in pre-5.6.4
     format (see 'TIME', 'DATETIME', and
     'TIMESTAMP' columns without support for fractional
     seconds precision).  Upgrading such columns requires a table
     rebuild, which prevents any use of fast alterations that might
     otherwise apply to the operation to be performed.

     This variable is disabled by default.  Enabling it causes
     'ALTER TABLE' not to rebuild temporal columns and
     thereby be able to take advantage of possible fast alterations.

     This variable is deprecated and will be removed in a future MySQL
     release.

   *
     'back_log'

     Property                             Value

     *System Variable*                    'back_log'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     The number of outstanding connection requests MySQL can have.  This
     comes into play when the main MySQL thread gets very many
     connection requests in a very short time.  It then takes some time
     (although very little) for the main thread to check the connection
     and start a new thread.  The 'back_log' value indicates how many
     requests can be stacked during this short time before MySQL
     momentarily stops answering new requests.  You need to increase
     this only if you expect a large number of connections in a short
     period of time.

     In other words, this value is the size of the listen queue for
     incoming TCP/IP connections.  Your operating system has its own
     limit on the size of this queue.  The manual page for the Unix
     'listen()' system call should have more details.  Check your OS
     documentation for the maximum value for this variable.  'back_log'
     cannot be set higher than your operating system limit.

     The default value is based on the following formula, capped to a
     limit of 900:

          50 + (max_connections / 5)

   *
     'basedir'

     Property                             Value

     *Command-Line Format*                '--basedir=dir_name'

     *System Variable*                    'basedir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The path to the MySQL installation base directory.

   *
     'big_tables'

     Property                             Value

     *Command-Line Format*                '--big-tables'

     *System Variable*                    'big_tables'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     If set to 1, all temporary tables are stored on disk rather than in
     memory.  This is a little slower, but the error 'The table TBL_NAME
     is full' does not occur for 'SELECT' operations that
     require a large temporary table.  The default value for a new
     connection is 0 (use in-memory temporary tables).  Normally, you
     should never need to set this variable, because in-memory tables
     are automatically converted to disk-based tables as required.

   *
     'bind_address'

     Property                             Value

     *Command-Line Format*                '--bind-address=addr'

     *System Variable*                    'bind_address'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      '*'

     The value of the '--bind-address' option.

     This variable has no effect for the embedded server ('libmysqld')
     and as of MySQL 5.7.2 is no longer visible within the embedded
     server.

   *
     'block_encryption_mode'

     Property                             Value

     *Command-Line Format*                '--block-encryption-mode=#'

     *Introduced*                         5.7.4

     *System Variable*                    'block_encryption_mode'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'aes-128-ecb'

     This variable controls the block encryption mode for block-based
     algorithms such as AES. It affects encryption for 'AES_ENCRYPT()'
     and 'AES_DECRYPT()'.

     'block_encryption_mode' takes a value in 'aes-KEYLEN-MODE' format,
     where KEYLEN is the key length in bits and MODE is the encryption
     mode.  The value is not case-sensitive.  Permitted KEYLEN values
     are 128, 192, and 256.  Permitted encryption modes depend on
     whether MySQL was compiled using OpenSSL or yaSSL:

        * For OpenSSL, permitted MODE values are: 'ECB', 'CBC', 'CFB1',
          'CFB8', 'CFB128', 'OFB'

        * For yaSSL, permitted MODE values are: 'ECB', 'CBC'

     For example, this statement causes the AES encryption functions to
     use a key length of 256 bits and the CBC mode:

          SET block_encryption_mode = 'aes-256-cbc';

     An error occurs for attempts to set 'block_encryption_mode' to a
     value containing an unsupported key length or a mode that the SSL
     library does not support.

   *
     'bulk_insert_buffer_size'

     Property                             Value

     *Command-Line Format*                '--bulk-insert-buffer-size=#'

     *System Variable*                    'bulk_insert_buffer_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '8388608'

     *Default Value* (32-bit platforms)   '8388608'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     'MyISAM' uses a special tree-like cache to make bulk inserts faster
     for 'INSERT ... SELECT', 'INSERT ... VALUES
     (...), (...), ...', and 'LOAD DATA INFILE' when
     adding data to nonempty tables.  This variable limits the size of
     the cache tree in bytes per thread.  Setting it to 0 disables this
     optimization.  The default value is 8MB.

   *
     'character_set_client'

     Property                             Value

     *System Variable*                    'character_set_client'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     The character set for statements that arrive from the client.  The
     session value of this variable is set using the character set
     requested by the client when the client connects to the server.
     (Many clients support a '--default-character-set' option to enable
     this character set to be specified explicitly.  See also
     charset-connection.)  The global value of the variable is used to
     set the session value in cases when the client-requested value is
     unknown or not available, or the server is configured to ignore
     client requests:

        * The client is from a version of MySQL older than MySQL 4.1,
          and thus does not request a character set.

        * The client requests a character set not known to the server.
          For example, a Japanese-enabled client requests 'sjis' when
          connecting to a server not configured with 'sjis' support.

        * 'mysqld' was started with the
          '--skip-character-set-client-handshake' option, which causes
          it to ignore client character set configuration.  This
          reproduces MySQL 4.0 behavior and is useful should you wish to
          upgrade the server without upgrading all the clients.

     'ucs2', 'utf16', 'utf16le', and 'utf32' cannot be used as a client
     character set, which means that they also do not work for
     'SET NAMES' or 'SET CHARACTER SET'.

   *
     'character_set_connection'

     Property                             Value

     *System Variable*                    'character_set_connection'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     The character set used for literals that do not have a character
     set introducer and for number-to-string conversion.  For
     information about introducers, see charset-introducer.

   *
     'character_set_database'

     Property                             Value

     *System Variable*                    'character_set_database'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'latin1'

     *Footnote*                           This option is dynamic, but only
                                          the server should set this
                                          information.  You should not set
                                          the value of this variable
                                          manually.

     The character set used by the default database.  The server sets
     this variable whenever the default database changes.  If there is
     no default database, the variable has the same value as
     'character_set_server'.

     The global 'character_set_database' and 'collation_database' system
     variables are deprecated as of MySQL 5.7.6 and will be removed in a
     future version of MySQL.

     Assigning a value to the session 'character_set_database' and
     'collation_database' system variables is deprecated as of MySQL
     5.7.6 and assignments produce a warning.  The session variables
     will become read only in a future version of MySQL and assignments
     will produce an error.  It will remain possible to access the
     session variables to determine the database character set and
     collation for the default database.

   *
     'character_set_filesystem'

     Property                             Value

     *Command-Line Format*                '--character-set-filesystem=name'

     *System Variable*                    'character_set_filesystem'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'binary'

     The file system character set.  This variable is used to interpret
     string literals that refer to file names, such as in the
     'LOAD DATA INFILE' and 'SELECT ... INTO OUTFILE'
     statements and the 'LOAD_FILE()' function.  Such file
     names are converted from 'character_set_client' to
     'character_set_filesystem' before the file opening attempt occurs.
     The default value is 'binary', which means that no conversion
     occurs.  For systems on which multibyte file names are permitted, a
     different value may be more appropriate.  For example, if the
     system represents file names using UTF-8, set
     'character_set_filesystem' to ''utf8''.

   *
     'character_set_results'

     Property                             Value

     *System Variable*                    'character_set_results'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     The character set used for returning query results such as result
     sets or error messages to the client.

   *
     'character_set_server'

     Property                             Value

     *Command-Line Format*                '--character-set-server'

     *System Variable*                    'character_set_server'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'latin1'

     The server's default character set.

   *
     'character_set_system'

     Property                             Value

     *System Variable*                    'character_set_system'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'utf8'

     The character set used by the server for storing identifiers.  The
     value is always 'utf8'.

   *
     'character_sets_dir'

     Property                             Value

     *Command-Line Format*                '--character-sets-dir=dir_name'

     *System Variable*                    'character_sets_dir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The directory where character sets are installed.

   *
     'check_proxy_users'

     Property                             Value

     *Command-Line Format*                '--check-proxy-users=[={OFF|ON}]'

     *Introduced*                         5.7.7

     *System Variable*                    'check_proxy_users'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This variable controls whether the server performs proxy user
     mapping for authentication plugins that request it.  With
     'check_proxy_users' enabled, it may also be necessary to enable
     plugin-specific system variables to take advantage of server proxy
     user mapping support:

        * For the 'mysql_native_password' plugin, enable
          'mysql_native_password_proxy_users'.

        * For the 'sha256_password' plugin, enable
          'sha256_password_proxy_users'.

     For information about user proxying, see proxy-users.

     This variable was added in MySQL 5.7.7.  Before 5.7.7, proxy user
     mapping is available only for plugins that implement it for
     themselves.

   *
     'collation_connection'

     Property                             Value

     *System Variable*                    'collation_connection'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     The collation of the connection character set.

   *
     'collation_database'

     Property                             Value

     *System Variable*                    'collation_database'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'latin1_swedish_ci'

     *Footnote*                           This option is dynamic, but only
                                          the server should set this
                                          information.  You should not set
                                          the value of this variable
                                          manually.

     The collation used by the default database.  The server sets this
     variable whenever the default database changes.  If there is no
     default database, the variable has the same value as
     'collation_server'.

     The global 'character_set_database' and 'collation_database' system
     variables are deprecated as of MySQL 5.7.6 and will be removed in a
     future version of MySQL.

     Assigning a value to the session 'character_set_database' and
     'collation_database' system variables is deprecated as of MySQL
     5.7.6 and assignments produce a warning.  The session variables
     will become read only in a future version of MySQL and assignments
     will produce an error.  It will remain possible to access the
     session variables to determine the database character set and
     collation for the default database.

   *
     'collation_server'

     Property                             Value

     *Command-Line Format*                '--collation-server'

     *System Variable*                    'collation_server'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'latin1_swedish_ci'

     The server's default collation.

   *
     'completion_type'

     Property                             Value

     *Command-Line Format*                '--completion-type=#'

     *System Variable*                    'completion_type'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'NO_CHAIN'

     *Valid Values*                       'NO_CHAIN' 'CHAIN' 'RELEASE' '0'
                                          '1' '2'

     The transaction completion type.  This variable can take the values
     shown in the following table.  The variable can be assigned using
     either the name values or corresponding integer values.

     Value   Description

     'NO_CHAIN''COMMIT' and 'ROLLBACK'
     and 'ROLLBACK',
     respectively.  (A new
             transaction starts immediately with the same
             isolation level as the just-terminated transaction.)

     'RELEASE''COMMIT' and 'ROLLBACK',
     respectively.  (The server
             disconnects after terminating the transaction.)

     'completion_type' affects transactions that begin with 'START TRANSACTION'
     or 'BEGIN' and end with
     'COMMIT' or 'ROLLBACK'.  It does not apply
     to implicit commits resulting from execution of the statements
     listed in implicit-commit.  It also does not apply for
     'XA COMMIT', 'XA ROLLBACK',
     or when 'autocommit=1'.

   *
     'concurrent_insert'

     Property                             Value

     *Command-Line Format*                '--concurrent-insert[=#]'

     *System Variable*                    'concurrent_insert'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'AUTO'

     *Valid Values*                       'NEVER' 'AUTO' 'ALWAYS' '0' '1'
                                          '2'

     If 'AUTO' (the default), MySQL permits 'INSERT' and
     'SELECT' statements to run concurrently for 'MyISAM'
     tables that have no free blocks in the middle of the data file.  If
     you start 'mysqld' with '--skip-new', this variable
     is set to 'NEVER'.

     This variable can take the values shown in the following table.
     The variable can be assigned using either the name values or
     corresponding integer values.

     Value   Description

     'NEVER' Disables concurrent inserts
     (or
     0)

     'AUTO'  (Default) Enables concurrent insert for 'MyISAM'
     (or     tables that do not have holes
     1)

     'ALWAYS'Enables concurrent inserts for all 'MyISAM' tables,
     (or     even those that have holes.  For a table with a
     2)      hole, new rows are inserted at the end of the table
             if it is in use by another thread.  Otherwise, MySQL
             acquires a normal write lock and inserts the row
             into the hole.

     See also concurrent-inserts.

   *
     'connect_timeout'

     Property                             Value

     *Command-Line Format*                '--connect-timeout=#'

     *System Variable*                    'connect_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '10'

     *Minimum Value*                      '2'

     *Maximum Value*                      '31536000'

     The number of seconds that the 'mysqld' server waits
     for a connect packet before responding with 'Bad handshake'.  The
     default value is 10 seconds.

     Increasing the 'connect_timeout' value might help if clients
     frequently encounter errors of the form 'Lost connection to MySQL
     server at 'XXX', system error: ERRNO'.

   *
     'core_file'

     Property                             Value

     *System Variable*                    'core_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether to write a core file if the server crashes.  This variable
     is set by the '--core-file' option.

   *
     'datadir'

     Property                             Value

     *Command-Line Format*                '--datadir=dir_name'

     *System Variable*                    'datadir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The path to the MySQL server data directory.  Relative paths are
     resolved with respect to the current directory.  If the server will
     be started automatically (that is, in contexts for which you cannot
     assume what the current directory will be), it is best to specify
     the 'datadir' value as an absolute path.

   *
     'date_format'

     This variable is unused.  It is deprecated and is removed in MySQL
     8.0.

   *
     'datetime_format'

     This variable is unused.  It is deprecated and is removed in MySQL
     8.0.

   *
     'debug'

     Property                             Value

     *Command-Line Format*                '--debug[=debug_options]'

     *System Variable*                    'debug'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (Windows)                     string

     *Type* (Unix)                        string

     *Default Value* (Windows)            'd:t:i:O,\mysqld.trace'

     *Default Value* (Unix)               'd:t:i:o,/tmp/mysqld.trace'

     This variable indicates the current debugging settings.  It is
     available only for servers built with debugging support.  The
     initial value comes from the value of instances of the '--debug'
     option given at server startup.  The global and session values may
     be set at runtime; the 'SUPER' privilege is required, even for the
     session value.

     Assigning a value that begins with '+' or '-' cause the value to
     added to or subtracted from the current value:

          mysql> SET debug = 'T';
          mysql> SELECT @@debug;
          +---------+
          | @@debug |
          +---------+
          | T       |
          +---------+

          mysql> SET debug = '+P';
          mysql> SELECT @@debug;
          +---------+
          | @@debug |
          +---------+
          | P:T     |
          +---------+

          mysql> SET debug = '-P';
          mysql> SELECT @@debug;
          +---------+
          | @@debug |
          +---------+
          | T       |
          +---------+

     For more information, see dbug-package.

   *
     'debug_sync'

     Property                             Value

     *System Variable*                    'debug_sync'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               string

     This variable is the user interface to the Debug Sync facility.
     Use of Debug Sync requires that MySQL be configured with the
     '-DENABLE_DEBUG_SYNC=1' 'CMake' option (see
     source-configuration-options).  If Debug Sync is not compiled in,
     this system variable is not available.

     The global variable value is read only and indicates whether the
     facility is enabled.  By default, Debug Sync is disabled and the
     value of 'debug_sync' is 'OFF'.  If the server is started with
     '--debug-sync-timeout=N', where N is a timeout value greater than
     0, Debug Sync is enabled and the value of 'debug_sync' is 'ON -
     current signal' followed by the signal name.  Also, N becomes the
     default timeout for individual synchronization points.

     The session value can be read by any user and will have the same
     value as the global variable.  The session value can be set by
     users that have the 'SUPER' privilege to control synchronization
     points.

     For a description of the Debug Sync facility and how to use
     synchronization points, see MySQL Internals: Test Synchronization
     (http://dev.mysql.com/doc/internals/en/test-synchronization.html).

   *
     'default_authentication_plugin'

     Property                             Value

     *Command-Line Format*                '--default-authentication-plugin=plugin_name'

     *Introduced*                         5.7.2

     *System Variable*                    'default_authentication_plugin'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               enumeration

     *Default Value*                      'mysql_native_password'

     *Valid Values*                       'mysql_native_password'
                                          'sha256_password'

     The default authentication plugin.  These values are permitted:

        * 'mysql_native_password': Use MySQL native passwords; see
          native-pluggable-authentication.

        * 'sha256_password': Use SHA-256 passwords; see
          sha256-pluggable-authentication.

     *Note*:

     If this variable has a value other than 'mysql_native_password',
     clients older than MySQL 5.5.7 cannot connect because, of the
     permitted default authentication plugins, they understand only the
     'mysql_native_password' authentication protocol.

     The 'default_authentication_plugin' value affects these aspects of
     server operation:

        * It determines which authentication plugin the server assigns
          to new accounts created by 'CREATE USER'.
          and 'GRANT' statements that do not explicitly
          specify an authentication plugin.

        * The 'old_passwords' system variable affects password hashing
          for accounts that use the 'mysql_native_password' or
          'sha256_password' authentication plugin.  If the default
          authentication plugin is one of those plugins, the server sets
          'old_passwords' at startup to the value required by the plugin
          password hashing method.

        * For an account created with either of the following
          statements, the server associates the account with the default
          authentication plugin and assigns the account the given
          password, hashed as required by that plugin:

               CREATE USER ... IDENTIFIED BY 'CLEARTEXT PASSWORD';
               GRANT ...  IDENTIFIED BY 'CLEARTEXT PASSWORD';

        * For an account created with either of the following
          statements, the server associates the account with the default
          authentication plugin and assigns the account the given
          password hash, if the password hash has the format required by
          the plugin:

               CREATE USER ... IDENTIFIED BY PASSWORD 'ENCRYPTED PASSWORD';
               GRANT ...  IDENTIFIED BY PASSWORD 'ENCRYPTED PASSWORD';

          If the password hash is not in the format required by the
          default authentication plugin, the statement fails.

     This variable was added in MySQL 5.7.2.  Earlier in MySQL 5.7, use
     the '--default-authentication-plugin' command-line option instead,
     which is used the same way at server startup, but cannot be
     accessed at runtime.

   *
     'default_password_lifetime'

     Property                             Value

     *Command-Line Format*                '--default-password-lifetime=#'

     *Introduced*                         5.7.4

     *System Variable*                    'default_password_lifetime'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value* (>= 5.7.11)          '0'

     *Default Value* (<= 5.7.10)          '360'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     This variable defines the global automatic password expiration
     policy.  It applies to accounts that use MySQL built-in
     authentication methods (accounts that use an authentication plugin
     of 'mysql_native_password' or 'sha256_password').

     The default 'default_password_lifetime' value is 0, which disables
     automatic password expiration.  If the value of
     'default_password_lifetime' is a positive integer N, it indicates
     the permitted password lifetime; passwords must be changed every N
     days.

     The global password expiration policy can be overridden as desired
     for individual accounts using the password expiration options of
     the 'ALTER USER' statement.  See
     password-management.

     *Note*:

     From MySQL 5.7.4 to 5.7.10, the default 'default_password_lifetime'
     value is 360 (passwords must be changed approximately once per
     year).  For those versions, be aware that, if you make no changes
     to the 'default_password_lifetime' variable or to individual user
     accounts, all user passwords will expire after 360 days, and all
     user accounts will start running in restricted mode when this
     happens.  Clients (which are effectively users) connecting to the
     server will then get an error indicating that the password must be
     changed: 'ERROR 1820 (HY000): You must reset your password using
     ALTER USER statement before executing this statement.'

     However, this is easy to miss for clients that automatically
     connect to the server, such as connections made from scripts.  To
     avoid having such clients suddenly stop working due to a password
     expiring, make sure to change the password expiration settings for
     those clients, like this:

          ALTER USER 'script'@'localhost' PASSWORD EXPIRE NEVER

     Alternatively, set the 'default_password_lifetime' variable to '0',
     thus disabling automatic password expiration for all users.

   *
     'default_storage_engine'

     Property                             Value

     *Command-Line Format*                '--default-storage-engine=name'

     *System Variable*                    'default_storage_engine'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'InnoDB'

     The default storage engine.  This variable sets the storage engine
     for permanent tables only.  To set the storage engine for
     'TEMPORARY' tables, set the 'default_tmp_storage_engine' system
     variable.

     To see which storage engines are available and enabled, use the
     'SHOW ENGINES' statement or query the
     'INFORMATION_SCHEMA' 'ENGINES' table.

     'default_storage_engine' should be used in preference to
     'storage_engine', which is deprecated and was removed in MySQL
     5.7.5.

     If you disable the default storage engine at server startup, you
     must set the default engine for both permanent and 'TEMPORARY'
     tables to a different engine or the server will not start.

   *
     'default_tmp_storage_engine'

     Property                             Value

     *Command-Line Format*                '--default-tmp-storage-engine=name'

     *System Variable*                    'default_tmp_storage_engine'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'InnoDB'

     The default storage engine for 'TEMPORARY' tables (created with
     'CREATE TEMPORARY TABLE').  To set the storage
     engine for permanent tables, set the 'default_storage_engine'
     system variable.  Also see the discussion of that variable
     regarding possible values.

     If you disable the default storage engine at server startup, you
     must set the default engine for both permanent and 'TEMPORARY'
     tables to a different engine or the server will not start.

   *
     'default_week_format'

     Property                             Value

     *Command-Line Format*                '--default-week-format=#'

     *System Variable*                    'default_week_format'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '7'

     The default mode value to use for the 'WEEK()' function.  See
     date-and-time-functions.

   *
     'delay_key_write'

     Property                             Value

     *Command-Line Format*                '--delay-key-write[=name]'

     *System Variable*                    'delay_key_write'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'ON'

     *Valid Values*                       'ON' 'OFF' 'ALL'

     This option applies only to 'MyISAM' tables.  It can have one of
     the following values to affect handling of the 'DELAY_KEY_WRITE'
     table option that can be used in 'CREATE TABLE'
     statements.

     Option  Description

     'OFF'   'DELAY_KEY_WRITE' is ignored.

     'ON'    MySQL honors any 'DELAY_KEY_WRITE' option specified
             in 'CREATE TABLE' statements.
             This is the default value.

     'ALL'   All new opened tables are treated as if they were
             created with the 'DELAY_KEY_WRITE' option enabled.

     If 'DELAY_KEY_WRITE' is enabled for a table, the key buffer is not
     flushed for the table on every index update, but only when the
     table is closed.  This speeds up writes on keys a lot, but if you
     use this feature, you should add automatic checking of all 'MyISAM'
     tables by starting the server with the '--myisam-recover-options'
     option (for example, '--myisam-recover-options=BACKUP,FORCE').  See
     server-options, and myisam-start.

     *Warning*:

     If you enable external locking with '--external-locking', there is
     no protection against index corruption for tables that use delayed
     key writes.

   *
     'delayed_insert_limit'

     Property                             Value

     *Command-Line Format*                '--delayed-insert-limit=#'

     *Deprecated*                         Yes

     *System Variable*                    'delayed_insert_limit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '100'

     *Default Value* (32-bit platforms)   '100'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     This system variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   *
     'delayed_insert_timeout'

     Property                             Value

     *Command-Line Format*                '--delayed-insert-timeout=#'

     *Deprecated*                         Yes

     *System Variable*                    'delayed_insert_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '300'

     This system variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   *
     'delayed_queue_size'

     Property                             Value

     *Command-Line Format*                '--delayed-queue-size=#'

     *Deprecated*                         Yes

     *System Variable*                    'delayed_queue_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1000'

     *Default Value* (32-bit platforms)   '1000'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     This system variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   *
     'disabled_storage_engines'

     Property                             Value

     *Command-Line Format*                '--disabled-storage-engines=engine[,engine]...'

     *Introduced*                         5.7.8

     *System Variable*                    'disabled_storage_engines'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'empty string'

     This variable indicates which storage engines cannot be used to
     create tables or tablespaces.  For example, to prevent new 'MyISAM'
     or 'FEDERATED' tables from being created, start the server with
     these lines in the server option file:

          [mysqld]
          disabled_storage_engines="MyISAM,FEDERATED"

     By default, 'disabled_storage_engines' is empty (no engines
     disabled), but it can be set to a comma-separated list of one or
     more engines (not case sensitive).  Any engine named in the value
     cannot be used to create tables or tablespaces with 'CREATE TABLE'
     or 'CREATE TABLESPACE',
     and cannot be used with 'ALTER TABLE ... ENGINE'
     or 'ALTER TABLESPACE ... ENGINE'
     to change the storage engine of existing tables
     or tablespaces.  Attempts to do so result in an
     'ER_DISABLED_STORAGE_ENGINE' error.

     'disabled_storage_engines' does not restrict other DDL statements
     for existing tables, such as 'CREATE INDEX',
     'TRUNCATE TABLE', 'ANALYZE TABLE',
     see 'DROP TABLE', or 'DROP TABLESPACE'.
     This permits a smooth transition so
     that existing tables or tablespaces that use a disabled engine can
     be migrated to a permitted engine by means such as 'ALTER TABLE ... ENGINE PERMITTED_ENGINE'.

     It is permitted to set the 'default_storage_engine' or
     'default_tmp_storage_engine' system variable to a storage engine
     that is disabled.  This could cause applications to behave
     erratically or fail, although that might be a useful technique in a
     development environment for identifying applications that use
     disabled engines, so that they can be modified.

     'disabled_storage_engines' is disabled and has no effect if the
     server is started with any of these options: '--bootstrap',
     '--initialize', '--initialize-insecure', '--skip-grant-tables'.

   *
     'disconnect_on_expired_password'

     Property                             Value

     *Command-Line Format*                '--disconnect-on-expired-password[=#]'

     *Introduced*                         5.7.1

     *System Variable*                    'disconnect_on_expired_password'

     *Scope*                              Session

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     This variable controls how the server handles clients with expired
     passwords:

        * If the client indicates that it can handle expires passwords,
          the value of 'disconnect_on_expired_password' is irrelevant.
          The server permits the client to connect but puts it in
          sandbox mode.

        * If the client does not indicate that it can handle expires
          passwords, the server handles the client according to the
          value of 'disconnect_on_expired_password':

             * If 'disconnect_on_expired_password': is enabled, the
               server disconnects the client.

             * If 'disconnect_on_expired_password': is disabled, the
               server permits the client to connect but puts it in
               sandbox mode.

     For more information about the interaction of client and server
     settings relating to expired-password handling, see
     expired-password-handling.

   *
     'div_precision_increment'

     Property                             Value

     *Command-Line Format*                '--div-precision-increment=#'

     *System Variable*                    'div_precision_increment'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '4'

     *Minimum Value*                      '0'

     *Maximum Value*                      '30'

     This variable indicates the number of digits by which to increase
     the scale of the result of division operations performed with the
     '/' operator.  The default value is 4.  The minimum and maximum
     values are 0 and 30, respectively.  The following example
     illustrates the effect of increasing the default value.

          mysql> SELECT 1/7;
          +--------+
          | 1/7    |
          +--------+
          | 0.1429 |
          +--------+
          mysql> SET div_precision_increment = 12;
          mysql> SELECT 1/7;
          +----------------+
          | 1/7            |
          +----------------+
          | 0.142857142857 |
          +----------------+

   *
     'end_markers_in_json'

     Property                             Value

     *System Variable*                    'end_markers_in_json'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether optimizer JSON output should add end markers.  See MySQL
     Internals: The end_markers_in_json System Variable
     (http://dev.mysql.com/doc/internals/en/end-markers-in-json-system-variable.html).

   * 'eq_range_index_dive_limit'

     Property                             Value

     *System Variable*                    'eq_range_index_dive_limit'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value* (>= 5.7.4)           '200'

     *Default Value* (<= 5.7.3)           '10'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     This variable indicates the number of equality ranges in an
     equality comparison condition when the optimizer should switch from
     using index dives to index statistics in estimating the number of
     qualifying rows.  It applies to evaluation of expressions that have
     either of these equivalent forms, where the optimizer uses a
     nonunique index to look up COL_NAME values:

          COL_NAME IN(VAL1, ..., VALN)
          COL_NAME = VAL1 OR ... OR COL_NAME = VALN

     In both cases, the expression contains N equality ranges.  The
     optimizer can make row estimates using index dives or index
     statistics.  If 'eq_range_index_dive_limit' is greater than 0, the
     optimizer uses existing index statistics instead of index dives if
     there are 'eq_range_index_dive_limit' or more equality ranges.
     Thus, to permit use of index dives for up to N equality ranges, set
     'eq_range_index_dive_limit' to N + 1.  To disable use of index
     statistics and always use index dives regardless of N, set
     'eq_range_index_dive_limit' to 0.

     For more information, see equality-range-optimization.

     To update table index statistics for best estimates, use
     'ANALYZE TABLE'.

   *
     'error_count'

     The number of errors that resulted from the last statement that
     generated messages.  This variable is read only.  See
     show-errors.

   *
     'event_scheduler'

     Property                             Value

     *Command-Line Format*                '--event-scheduler[=value]'

     *System Variable*                    'event_scheduler'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'OFF'

     *Valid Values*                       'ON' 'OFF' 'DISABLED'

     This variable indicates the status of the Event Scheduler; possible
     values are 'ON', 'OFF', and 'DISABLED', with the default being
     'OFF'.  This variable and its effects on the Event Scheduler's
     operation are discussed in greater detail in the Overview section
     of the Events chapter.

   *
     'expire_logs_days'

     Property                             Value

     *Command-Line Format*                '--expire-logs-days=#'

     *System Variable*                    'expire_logs_days'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Type*                               integer

     *Default Value*                      '30'

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '99'

     *Maximum Value*                      '99'

     The number of days for automatic binary log file removal.  The
     default is 0, which means 'no automatic removal.' Possible removals
     happen at startup and when the binary log is flushed.  Log flushing
     occurs as indicated in server-logs.

     To remove binary log files manually, use the 'PURGE BINARY LOGS'
     statement.  See
     purge-binary-logs.

   *
     'explicit_defaults_for_timestamp'

     Property                             Value

     *Command-Line Format*                '--explicit-defaults-for-timestamp=#'

     *Deprecated*                         Yes

     *System Variable*                    'explicit_defaults_for_timestamp'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This system variable determines whether the server enables certain
     nonstandard behaviors for default values and 'NULL'-value handling
     in 'TIMESTAMP' columns.  By default,
     'explicit_defaults_for_timestamp' is disabled, which enables the
     nonstandard behaviors.

     If 'explicit_defaults_for_timestamp' is disabled, the server
     enables the nonstandard behaviors and handles 'TIMESTAMP'
     columns as follows:

        * 'TIMESTAMP' columns not explicitly declared
          with the 'NULL' attribute are automatically declared with the
          'NOT NULL' attribute.  Assigning such a column a value of
          'NULL' is permitted and sets the column to the current
          timestamp.

        * The first 'TIMESTAMP' column in a table, if
          not explicitly declared with the 'NULL' attribute or an
          explicit 'DEFAULT' or 'ON UPDATE' attribute, is automatically
          declared with the 'DEFAULT CURRENT_TIMESTAMP' and 'ON UPDATE
          CURRENT_TIMESTAMP' attributes.

        * 'TIMESTAMP' columns following the first one,
          if not explicitly declared with the 'NULL' attribute or an
          explicit 'DEFAULT' attribute, are automatically declared as
          'DEFAULT '0000-00-00 00:00:00'' (the 'zero' timestamp).  For
          inserted rows that specify no explicit value for such a
          column, the column is assigned ''0000-00-00 00:00:00'' and no
          warning occurs.

          Depending on whether strict SQL mode or the 'NO_ZERO_DATE' SQL
          mode is enabled, a default value of ''0000-00-00 00:00:00''
          may be invalid.  Be aware that the 'TRADITIONAL' SQL mode
          includes strict mode and 'NO_ZERO_DATE'.  See
          sql-mode.

     The nonstandard behaviors just described are deprecated and will be
     removed in a future MySQL release.

     If 'explicit_defaults_for_timestamp' is enabled, the server
     disables the nonstandard behaviors and handles 'TIMESTAMP'
     columns as follows:

        * It is not possible to assign a 'TIMESTAMP'.
          column a value of 'NULL' to set it to the current timestamp.
          To assign the current timestamp, set the column to
          'CURRENT_TIMESTAMP' or a synonym such as 'NOW()'.

        * 'TIMESTAMP' columns not explicitly declared
          with the 'NOT NULL' attribute are automatically declared with
          the 'NULL' attribute and permit 'NULL' values.  Assigning such
          a column a value of 'NULL' sets it to 'NULL', not the current
          timestamp.

        * 'TIMESTAMP' columns declared with the 'NOT
          NULL' attribute do not permit 'NULL' values.  For inserts that
          specify 'NULL' for such a column, the result is either an
          error for a single-row insert or if strict SQL mode is
          enabled, or ''0000-00-00 00:00:00'' is inserted for
          multiple-row inserts with strict SQL mode disabled.  In no
          case does assigning the column a value of 'NULL' set it to the
          current timestamp.

        * 'TIMESTAMP' columns explicitly declared with
          the 'NOT NULL' attribute and without an explicit 'DEFAULT'
          attribute are treated as having no default value.  For
          inserted rows that specify no explicit value for such a
          column, the result depends on the SQL mode.  If strict SQL
          mode is enabled, an error occurs.  If strict SQL mode is not
          enabled, the column is declared with the implicit default of
          ''0000-00-00 00:00:00'' and a warning occurs.  This is similar
          to how MySQL treats other temporal types such as
          'DATETIME'.

        * No 'TIMESTAMP' column is automatically
          declared with the 'DEFAULT CURRENT_TIMESTAMP' or 'ON UPDATE
          CURRENT_TIMESTAMP' attributes.  Those attributes must be
          explicitly specified.

        * The first 'TIMESTAMP' column in a table is
          not handled differently from 'TIMESTAMP'.
          columns following the first one.

     If 'explicit_defaults_for_timestamp' is disabled at server startup,
     this warning appears in the error log:

          [Warning] TIMESTAMP with implicit DEFAULT value is deprecated.
          Please use --explicit_defaults_for_timestamp server option (see
          documentation for more details).

     As indicated by the warning, to disable the deprecated nonstandard
     behaviors, enable the 'explicit_defaults_for_timestamp' system
     variable at server startup.

     *Note*:

     'explicit_defaults_for_timestamp' is itself deprecated because its
     only purpose is to permit control over deprecated
     'TIMESTAMP' behaviors that are to be removed in a future
     MySQL release.  When removal of those behaviors occurs,
     'explicit_defaults_for_timestamp' will have no purpose and will be
     removed as well.

     For additional information, see timestamp-initialization.

   *
     'external_user'

     Property                             Value

     *System Variable*                    'external_user'

     *Scope*                              Session

     *Dynamic*                            No

     *Type*                               string

     The external user name used during the authentication process, as
     set by the plugin used to authenticate the client.  With native
     (built-in) MySQL authentication, or if the plugin does not set the
     value, this variable is 'NULL'.  See proxy-users.

   *
     'flush'

     Property                             Value

     *Command-Line Format*                '--flush'

     *System Variable*                    'flush'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     If 'ON', the server flushes (synchronizes) all changes to disk
     after each SQL statement.  Normally, MySQL does a write of all
     changes to disk only after each SQL statement and lets the
     operating system handle the synchronizing to disk.  See
     crashing.  This variable is set to 'ON' if you start
     'mysqld' with the '--flush' option.

     *Note*:

     If 'flush' is enabled, the value of 'flush_time' does not matter
     and changes to 'flush_time' have no effect on flush behavior.

   *
     'flush_time'

     Property                             Value

     *Command-Line Format*                '--flush-time=#'

     *System Variable*                    'flush_time'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (Windows)                     integer

     *Type*                               integer

     *Default Value* (Windows)            '0'

     *Default Value*                      '0'

     *Minimum Value* (Windows)            '0'

     *Minimum Value*                      '0'

     If this is set to a nonzero value, all tables are closed every
     'flush_time' seconds to free up resources and synchronize unflushed
     data to disk.  This option is best used only on systems with
     minimal resources.

     *Note*:

     If 'flush' is enabled, the value of 'flush_time' does not matter
     and changes to 'flush_time' have no effect on flush behavior.

   *
     'foreign_key_checks'

     Property                             Value

     *System Variable*                    'foreign_key_checks'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '1'

     If set to 1 (the default), foreign key constraints for 'InnoDB'
     tables are checked.  If set to 0, foreign key constraints are
     ignored, with a couple of exceptions.  When re-creating a table
     that was dropped, an error is returned if the table definition does
     not conform to the foreign key constraints referencing the table.
     Likewise, an 'ALTER TABLE' operation returns an
     error if a foreign key definition is incorrectly formed.  For more
     information, see create-table-foreign-keys.

     Setting this variable has the same effect on 'NDB'
     tables as it does for 'InnoDB' tables.  Typically
     you leave this setting enabled during normal operation, to enforce
     referential integrity.  Disabling foreign key checking can be
     useful for reloading 'InnoDB' tables in an order different from
     that required by their parent/child relationships.  See
     innodb-foreign-key-constraints.

     Setting 'foreign_key_checks' to 0 also affects data definition
     statements: 'DROP SCHEMA' drops a schema even
     if it contains tables that have foreign keys that are referred to
     by tables outside the schema, and 'DROP TABLE'.
     drops tables that have foreign keys that are referred to by other
     tables.

     *Note*:

     Setting 'foreign_key_checks' to 1 does not trigger a scan of the
     existing table data.  Therefore, rows added to the table while
     'foreign_key_checks=0' will not be verified for consistency.

     As of MySQL 5.7.5, dropping an index required by a foreign key
     constraint is not permitted, even with 'foreign_key_checks=0'.  The
     foreign key constraint must be removed before dropping the index
     (Bug #70260).

   *
     'ft_boolean_syntax'

     Property                             Value

     *Command-Line Format*                '--ft-boolean-syntax=name'

     *System Variable*                    'ft_boolean_syntax'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      '+ -><()~*:""&|'

     The list of operators supported by boolean full-text searches
     performed using 'IN BOOLEAN MODE'.  See fulltext-boolean.

     The default variable value is ''+ -><()~*:""&|''.  The rules for
     changing the value are as follows:

        * Operator function is determined by position within the string.

        * The replacement value must be 14 characters.

        * Each character must be an ASCII nonalphanumeric character.

        * Either the first or second character must be a space.

        * No duplicates are permitted except the phrase quoting
          operators in positions 11 and 12.  These two characters are
          not required to be the same, but they are the only two that
          may be.

        * Positions 10, 13, and 14 (which by default are set to ':',
          '&', and '|') are reserved for future extensions.

   *
     'ft_max_word_len'

     Property                             Value

     *Command-Line Format*                '--ft-max-word-len=#'

     *System Variable*                    'ft_max_word_len'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Minimum Value*                      '10'

     The maximum length of the word to be included in a 'MyISAM'
     'FULLTEXT' index.

     *Note*:

     'FULLTEXT' indexes on 'MyISAM' tables must be rebuilt after
     changing this variable.  Use 'REPAIR TABLE TBL_NAME QUICK'.

   *
     'ft_min_word_len'

     Property                             Value

     *Command-Line Format*                '--ft-min-word-len=#'

     *System Variable*                    'ft_min_word_len'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '4'

     *Minimum Value*                      '1'

     The minimum length of the word to be included in a 'MyISAM'
     'FULLTEXT' index.

     *Note*:

     'FULLTEXT' indexes on 'MyISAM' tables must be rebuilt after
     changing this variable.  Use 'REPAIR TABLE TBL_NAME QUICK'.

   *
     'ft_query_expansion_limit'

     Property                             Value

     *Command-Line Format*                '--ft-query-expansion-limit=#'

     *System Variable*                    'ft_query_expansion_limit'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '20'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1000'

     The number of top matches to use for full-text searches performed
     using 'WITH QUERY EXPANSION'.

   *
     'ft_stopword_file'

     Property                             Value

     *Command-Line Format*                '--ft-stopword-file=file_name'

     *System Variable*                    'ft_stopword_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The file from which to read the list of stopwords for full-text
     searches on 'MyISAM' tables.  The server looks for the file in the
     data directory unless an absolute path name is given to specify a
     different directory.  All the words from the file are used;
     comments are _not_ honored.  By default, a built-in list of
     stopwords is used (as defined in the 'storage/myisam/ft_static.c'
     file).  Setting this variable to the empty string ('''') disables
     stopword filtering.  See also fulltext-stopwords.

     *Note*:

     'FULLTEXT' indexes on 'MyISAM' tables must be rebuilt after
     changing this variable or the contents of the stopword file.  Use
     'REPAIR TABLE TBL_NAME QUICK'.

   *
     'general_log'

     Property                             Value

     *Command-Line Format*                '--general-log'

     *System Variable*                    'general_log'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether the general query log is enabled.  The value can be 0 (or
     'OFF') to disable the log or 1 (or 'ON') to enable the log.  The
     default value depends on whether the '--general_log' option is
     given.  The destination for log output is controlled by the
     'log_output' system variable; if that value is 'NONE', no log
     entries are written even if the log is enabled.

   *
     'general_log_file'

     Property                             Value

     *Command-Line Format*                '--general-log-file=file_name'

     *System Variable*                    'general_log_file'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               file name

     *Default Value*                      'host_name.log'

     The name of the general query log file.  The default value is
     'HOST_NAME.log', but the initial value can be changed with the
     '--general_log_file' option.

   *
     'group_concat_max_len'

     Property                             Value

     *Command-Line Format*                '--group-concat-max-len=#'

     *System Variable*                    'group_concat_max_len'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1024'

     *Default Value* (32-bit platforms)   '1024'

     *Minimum Value* (64-bit platforms)   '4'

     *Minimum Value* (32-bit platforms)   '4'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The maximum permitted result length in bytes for the
     'GROUP_CONCAT()' function.  The default is 1024.

   *
     'have_compress'

     'YES' if the 'zlib' compression library is available to the server,
     'NO' if not.  If not, the 'COMPRESS()' and 'UNCOMPRESS()' functions
     cannot be used.

   *
     'have_crypt'

     'YES' if the 'crypt()' system call is available to the server, 'NO'
     if not.  If not, the 'ENCRYPT()' function cannot be used.

     *Note*:

     The 'ENCRYPT()' function is deprecated as of MySQL 5.7.6, will be
     removed in a future MySQL release, and should no longer be used.
     (For one-way hashing, consider using 'SHA2()' instead.)
     Consequently, 'have_crypt' also is deprecated and will be removed.

   *
     'have_dynamic_loading'

     'YES' if 'mysqld' supports dynamic loading of
     plugins, 'NO' if not.  If the value is 'NO', you cannot use options
     such as '--plugin-load' to load plugins at server startup, or the
     'INSTALL PLUGIN' statement to load plugins
     at runtime.

   *
     'have_geometry'

     'YES' if the server supports spatial data types, 'NO' if not.

   *
     'have_openssl'

     This variable is an alias for 'have_ssl'.

   *
     'have_profiling'

     'YES' if statement profiling capability is present, 'NO' if not.
     If present, the 'profiling' system variable controls whether this
     capability is enabled or disabled.  See show-profiles.

     This variable is deprecated and will be removed in a future MySQL
     release.

   *
     'have_query_cache'

     'YES' if 'mysqld' supports the query cache, 'NO' if
     not.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'have_query_cache'.

   *
     'have_rtree_keys'

     'YES' if 'RTREE' indexes are available, 'NO' if not.  (These are
     used for spatial indexes in 'MyISAM' tables.)

   *
     'have_ssl'

     'YES' if 'mysqld' supports SSL connections, 'NO' if
     not.  'DISABLED' indicates that the server was compiled with SSL
     support, but was not started with the appropriate '--ssl-XXX'
     options.  For more information, see
     building-with-encrypted-connection-support.

   *
     'have_statement_timeout'

     Property                             Value

     *Introduced*                         5.7.4

     *System Variable*                    'have_statement_timeout'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     Whether the statement execution timeout feature is available (see
     optimizer-hints-execution-time).  The value can be 'NO' if
     the background thread used by this feature could not be
     initialized.

   *
     'have_symlink'

     'YES' if symbolic link support is enabled, 'NO' if not.  This is
     required on Unix for support of the 'DATA DIRECTORY' and 'INDEX
     DIRECTORY' table options.  If the server is started with the
     '--skip-symbolic-links' option, the value is 'DISABLED'.

     This variable has no meaning on Windows.

   * 'host_cache_size'

     Property                             Value

     *System Variable*                    'host_cache_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65536'

     The size of the internal host cache (see host-cache).
     Setting the size to 0 disables the host cache.  Changing the cache
     size at runtime implicitly causes a 'FLUSH HOSTS' operation to
     clear the host cache and truncate the 'host_cache'
     table.

     The default value is 128, plus 1 for a value of 'max_connections'
     up to 500, plus 1 for every increment of 20 over 500 in the
     'max_connections' value, capped to a limit of 2000.

     Use of '--skip-host-cache' is similar to setting the
     'host_cache_size' system variable to 0, but 'host_cache_size' is
     more flexible because it can also be used to resize, enable, or
     disable the host cache at runtime, not just at server startup.

     If you start the server with '--skip-host-cache', that does not
     prevent changes to the value of 'host_cache_size', but such changes
     have no effect and the cache is not re-enabled even if
     'host_cache_size' is set larger than 0.

   *
     'hostname'

     Property                             Value

     *System Variable*                    'hostname'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The server sets this variable to the server host name at startup.

   *
     'identity'

     This variable is a synonym for the 'last_insert_id' variable.  It
     exists for compatibility with other database systems.  You can read
     its value with 'SELECT @@identity', and set it using 'SET
     identity'.

   *
     'ignore_db_dirs'

     Property                             Value

     *Deprecated*                         5.7.16

     *System Variable*                    'ignore_db_dirs'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     A comma-separated list of names that are not considered as database
     directories in the data directory.  The value is set from any
     instances of '--ignore-db-dir' given at server startup.

     As of MySQL 5.7.11, '--ignore-db-dir' can be used at data directory
     initialization time with 'mysqld --initialize' to
     specify directories that the server should ignore for purposes of
     assessing whether an existing data directory is considered empty.
     See data-directory-initialization-mysqld.

     This system variable is deprecated in MySQL 5.7.  With the
     introduction of the data dictionary in MySQL 8.0, it became
     superfluous and was removed in that version.

   *
     'init_connect'

     Property                             Value

     *Command-Line Format*                '--init-connect=name'

     *System Variable*                    'init_connect'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     A string to be executed by the server for each client that
     connects.  The string consists of one or more SQL statements,
     separated by semicolon characters.  For example, each client
     session begins by default with autocommit mode enabled.  For older
     servers (before MySQL 5.5.8), there is no global 'autocommit'
     system variable to specify that autocommit should be disabled by
     default, but as a workaround 'init_connect' can be used to achieve
     the same effect:

          SET GLOBAL init_connect='SET autocommit=0';

     The 'init_connect' variable can also be set on the command line or
     in an option file.  To set the variable as just shown using an
     option file, include these lines:

          [mysqld]
          init_connect='SET autocommit=0'

     For users that have the 'SUPER' privilege, the content of
     'init_connect' is not executed.  This is done so that an erroneous
     value for 'init_connect' does not prevent all clients from
     connecting.  For example, the value might contain a statement that
     has a syntax error, thus causing client connections to fail.  Not
     executing 'init_connect' for users that have the 'SUPER' privilege
     enables them to open a connection and fix the 'init_connect' value.

     As of MySQL 5.7.22, 'init_connect' execution is skipped for any
     client user with an expired password.  This is done because such a
     user cannot execute arbitrary statements, and thus 'init_connect'
     execution will fail, leaving the client unable to connect.
     Skipping 'init_connect' execution enables the user to connect and
     change password.

     The server discards any result sets produced by statements in the
     value of of 'init_connect'.

   *
     'init_file'

     Property                             Value

     *Command-Line Format*                '--init-file=file_name'

     *System Variable*                    'init_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The name of the file specified with the '--init-file' option when
     you start the server.  This should be a file containing SQL
     statements that you want the server to execute when it starts.
     Each statement must be on a single line and should not include
     comments.  For more information, see the description of
     '--init-file'.

   * 'innodb_XXX'

     'InnoDB' system variables are listed
     in innodb-parameters.  These variables control many aspects
     of storage, memory use, and I/O patterns for 'InnoDB' tables, and
     are especially important now that 'InnoDB' is the default storage
     engine.

   *
     'insert_id'

     The value to be used by the following 'INSERT' or
     'ALTER TABLE' statement when inserting an
     'AUTO_INCREMENT' value.  This is mainly used with the binary log.

   *
     'interactive_timeout'

     Property                             Value

     *Command-Line Format*                '--interactive-timeout=#'

     *System Variable*                    'interactive_timeout'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '28800'

     *Minimum Value*                      '1'

     The number of seconds the server waits for activity on an
     interactive connection before closing it.  An interactive client is
     defined as a client that uses the 'CLIENT_INTERACTIVE' option to
     'mysql_real_connect()'.  See also
     'wait_timeout'.

   *
     'internal_tmp_disk_storage_engine'

     Property                             Value

     *Command-Line Format*                '--internal-tmp-disk-storage-engine=#'

     *Introduced*                         5.7.5

     *System Variable*                    'internal_tmp_disk_storage_engine'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value* (>= 5.7.6)           'INNODB'

     *Default Value* (<= 5.7.5)           'MYISAM'

     *Valid Values*                       'MYISAM' 'INNODB'

     The storage engine for on-disk internal temporary tables (see
     internal-temporary-tables).  Permitted values are 'MYISAM' and
     'INNODB' (the default).

     This system variable was added in MySQL 5.7.5 with a default value
     of 'MYISAM'.  In MySQL 5.7.6, the default value changed to
     'INNODB'.  With this change, the optimizer uses the 'InnoDB'
     storage engine by default for on-disk internal temporary tables.

     When using 'internal_tmp_disk_storage_engine=INNODB' (the default),
     queries that generate on-disk internal temporary tables that exceed
     'InnoDB' row or column limits will
     return 'Row size too large' or 'Too many columns' errors.  The
     workaround is to set 'internal_tmp_disk_storage_engine' to
     'MYISAM'.

   *
     'join_buffer_size'

     Property                             Value

     *Command-Line Format*                '--join-buffer-size=#'

     *System Variable*                    'join_buffer_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (Other, 64-bit platforms)     integer

     *Type* (Other, 32-bit platforms)     integer

     *Type* (Windows)                     integer

     *Default Value* (Other, 64-bit       '262144'
     platforms)

     *Default Value* (Other, 32-bit       '262144'
     platforms)

     *Default Value* (Windows)            '262144'

     *Minimum Value* (Other, 64-bit       '128'
     platforms)

     *Minimum Value* (Other, 32-bit       '128'
     platforms)

     *Minimum Value* (Windows)            '128'

     *Maximum Value* (Other, 64-bit       '18446744073709547520'
     platforms)

     *Maximum Value* (Other, 32-bit       '4294967295'
     platforms)

     *Maximum Value* (Windows)            '4294967295'

     The minimum size of the buffer that is used for plain index scans,
     range index scans, and joins that do not use indexes and thus
     perform full table scans.  Normally, the best way to get fast joins
     is to add indexes.  Increase the value of 'join_buffer_size' to get
     a faster full join when adding indexes is not possible.  One join
     buffer is allocated for each full join between two tables.  For a
     complex join between several tables for which indexes are not used,
     multiple join buffers might be necessary.

     Unless Batched Key Access (BKA) is used, there is no gain from
     setting the buffer larger than required to hold each matching row,
     and all joins allocate at least the minimum size, so use caution in
     setting this variable to a large value globally.  It is better to
     keep the global setting small and change to a larger setting only
     in sessions that are doing large joins.  Memory allocation time can
     cause substantial performance drops if the global size is larger
     than needed by most queries that use it.

     When BKA is used, the value of 'join_buffer_size' defines how large
     the batch of keys is in each request to the storage engine.  The
     larger the buffer, the more sequential access will be to the right
     hand table of a join operation, which can significantly improve
     performance.

     The default is 256KB. The maximum permissible setting for
     'join_buffer_size' is 4GB−1.  Larger values are permitted for
     64-bit platforms (except 64-bit Windows, for which large values are
     truncated to 4GB−1 with a warning).

     For additional information about join buffering, see
     nested-loop-joins.  For information about Batched Key Access, see
     bnl-bka-optimization.

   *
     'keep_files_on_create'

     Property                             Value

     *Command-Line Format*                '--keep-files-on-create=#'

     *System Variable*                    'keep_files_on_create'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     If a 'MyISAM' table is created with no 'DATA DIRECTORY' option, the
     '.MYD' file is created in the database directory.  By default, if
     'MyISAM' finds an existing '.MYD' file in this case, it overwrites
     it.  The same applies to '.MYI' files for tables created with no
     'INDEX DIRECTORY' option.  To suppress this behavior, set the
     'keep_files_on_create' variable to 'ON' (1), in which case 'MyISAM'
     will not overwrite existing files and returns an error instead.
     The default value is 'OFF' (0).

     If a 'MyISAM' table is created with a 'DATA DIRECTORY' or 'INDEX
     DIRECTORY' option and an existing '.MYD' or '.MYI' file is found,
     MyISAM always returns an error.  It will not overwrite a file in
     the specified directory.

   *
     'key_buffer_size'

     Property                             Value

     *Command-Line Format*                '--key-buffer-size=#'

     *System Variable*                    'key_buffer_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '8388608'

     *Default Value* (32-bit platforms)   '8388608'

     *Minimum Value* (64-bit platforms)   '8'

     *Minimum Value* (32-bit platforms)   '8'

     *Maximum Value* (64-bit platforms)   'OS_PER_PROCESS_LIMIT'

     *Maximum Value* (32-bit platforms)   '4294967295'

     Index blocks for 'MyISAM' tables are buffered and are shared by all
     threads.  'key_buffer_size' is the size of the buffer used for
     index blocks.  The key buffer is also known as the key cache.

     The maximum permissible setting for 'key_buffer_size' is 4GB−1 on
     32-bit platforms.  Larger values are permitted for 64-bit
     platforms.  The effective maximum size might be less, depending on
     your available physical RAM and per-process RAM limits imposed by
     your operating system or hardware platform.  The value of this
     variable indicates the amount of memory requested.  Internally, the
     server allocates as much memory as possible up to this amount, but
     the actual allocation might be less.

     You can increase the value to get better index handling for all
     reads and multiple writes; on a system whose primary function is to
     run MySQL using the 'MyISAM' storage
     engine, 25% of the machine's total memory is an acceptable value
     for this variable.  However, you should be aware that, if you make
     the value too large (for example, more than 50% of the machine's
     total memory), your system might start to page and become extremely
     slow.  This is because MySQL relies on the operating system to
     perform file system caching for data reads, so you must leave some
     room for the file system cache.  You should also consider the
     memory requirements of any other storage engines that you may be
     using in addition to 'MyISAM'.

     For even more speed when writing many rows at the same time, use
     'LOCK TABLES'.  See insert-optimization.

     You can check the performance of the key buffer by issuing a
     'SHOW STATUS' statement and examining the
     'Key_read_requests', 'Key_reads', 'Key_write_requests', and
     'Key_writes' status variables.  (See show.)  The
     'Key_reads/Key_read_requests' ratio should normally be less than
     0.01.  The 'Key_writes/Key_write_requests' ratio is usually near 1
     if you are using mostly updates and deletes, but might be much
     smaller if you tend to do updates that affect many rows at the same
     time or if you are using the 'DELAY_KEY_WRITE' table option.

     The fraction of the key buffer in use can be determined using
     'key_buffer_size' in conjunction with the 'Key_blocks_unused'
     status variable and the buffer block size, which is available from
     the 'key_cache_block_size' system variable:

          1 - ((Key_blocks_unused * key_cache_block_size) / key_buffer_size)

     This value is an approximation because some space in the key buffer
     is allocated internally for administrative structures.  Factors
     that influence the amount of overhead for these structures include
     block size and pointer size.  As block size increases, the
     percentage of the key buffer lost to overhead tends to decrease.
     Larger blocks results in a smaller number of read operations
     (because more keys are obtained per read), but conversely an
     increase in reads of keys that are not examined (if not all keys in
     a block are relevant to a query).

     It is possible to create multiple 'MyISAM' key caches.  The size
     limit of 4GB applies to each cache individually, not as a group.
     See myisam-key-cache.

   *
     'key_cache_age_threshold'

     Property                             Value

     *Command-Line Format*                '--key-cache-age-threshold=#'

     *System Variable*                    'key_cache_age_threshold'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '300'

     *Default Value* (32-bit platforms)   '300'

     *Minimum Value* (64-bit platforms)   '100'

     *Minimum Value* (32-bit platforms)   '100'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     This value controls the demotion of buffers from the hot sublist of
     a key cache to the warm sublist.  Lower values cause demotion to
     happen more quickly.  The minimum value is 100.  The default value
     is 300.  See myisam-key-cache.

   *
     'key_cache_block_size'

     Property                             Value

     *Command-Line Format*                '--key-cache-block-size=#'

     *System Variable*                    'key_cache_block_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '512'

     *Maximum Value*                      '16384'

     The size in bytes of blocks in the key cache.  The default value is
     1024.  See myisam-key-cache.

   *
     'key_cache_division_limit'

     Property                             Value

     *Command-Line Format*                '--key-cache-division-limit=#'

     *System Variable*                    'key_cache_division_limit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '100'

     *Minimum Value*                      '1'

     *Maximum Value*                      '100'

     The division point between the hot and warm sublists of the key
     cache buffer list.  The value is the percentage of the buffer list
     to use for the warm sublist.  Permissible values range from 1 to
     100.  The default value is 100.  See myisam-key-cache.

   *
     'large_files_support'

     Property                             Value

     *System Variable*                    'large_files_support'

     *Scope*                              Global

     *Dynamic*                            No

     Whether 'mysqld' was compiled with options for large
     file support.

   *
     'large_pages'

     Property                             Value

     *Command-Line Format*                '--large-pages'

     *System Variable*                    'large_pages'

     *Scope*                              Global

     *Dynamic*                            No

     *Platform Specific*                  Linux

     *Type* (Linux)                       boolean

     *Default Value* (Linux)              'FALSE'

     Whether large page support is enabled (via the '--large-pages'
     option).  See large-page-support.

   *
     'large_page_size'

     Property                             Value

     *System Variable*                    'large_page_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (Linux)                       integer

     *Default Value* (Linux)              '0'

     If large page support is enabled, this shows the size of memory
     pages.  Large memory pages are supported only on Linux; on other
     platforms, the value of this variable is always 0.  See
     large-page-support.

   *
     'last_insert_id'

     The value to be returned from 'LAST_INSERT_ID()'.  This is stored
     in the binary log when you use 'LAST_INSERT_ID()' in a statement
     that updates a table.  Setting this variable does not update the
     value returned by the 'mysql_insert_id()'. C
     API function.

   *
     'lc_messages'

     Property                             Value

     *Command-Line Format*                '--lc-messages=name'

     *System Variable*                    'lc_messages'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'en_US'

     The locale to use for error messages.  The default is 'en_US'.  The
     server converts the argument to a language name and combines it
     with the value of 'lc_messages_dir' to produce the location for the
     error message file.  See error-message-language.

   *
     'lc_messages_dir'

     Property                             Value

     *Command-Line Format*                '--lc-messages-dir=dir_name'

     *System Variable*                    'lc_messages_dir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The directory where error messages are located.  The server uses
     the value together with the value of 'lc_messages' to produce the
     location for the error message file.  See
     error-message-language.

   *
     'lc_time_names'

     Property                             Value

     *System Variable*                    'lc_time_names'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     This variable specifies the locale that controls the language used
     to display day and month names and abbreviations.  This variable
     affects the output from the 'DATE_FORMAT()', 'DAYNAME()' and
     'MONTHNAME()' functions.  Locale names are POSIX-style values such
     as ''ja_JP'' or ''pt_BR''.  The default value is ''en_US''
     regardless of your system's locale setting.  For further
     information, see locale-support.

   *
     'license'

     Property                             Value

     *System Variable*                    'license'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'GPL'

     The type of license the server has.

   *
     'local_infile'

     Property                             Value

     *System Variable*                    'local_infile'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     This variable controls server-side 'LOCAL' capability for
     'LOAD DATA' statements.  Depending on the
     'local_infile' setting, the server refuses or permits local data
     loading by clients that have 'LOCAL' enabled on the client side.

     To explicitly cause the server to refuse or permit 'LOAD DATA LOCAL'
     statements (regardless of how client programs
     and libraries are configured at build time or runtime), start
     'mysqld' with 'local_infile' disabled or enabled,
     respectively.  'local_infile' can also be set at runtime.  For more
     information, see load-data-local.

   *
     'lock_wait_timeout'

     Property                             Value

     *Command-Line Format*                '--lock-wait-timeout=#'

     *System Variable*                    'lock_wait_timeout'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '31536000'

     *Minimum Value*                      '1'

     *Maximum Value*                      '31536000'

     This variable specifies the timeout in seconds for attempts to
     acquire metadata locks.  The permissible values range from 1 to
     31536000 (1 year).  The default is 31536000.

     This timeout applies to all statements that use metadata locks.
     These include DML and DDL operations on tables, views, stored
     procedures, and stored functions, as well as 'LOCK TABLES',
     'FLUSH TABLES WITH READ LOCK', and 'HANDLER'
     statements.

     This timeout does not apply to implicit accesses to system tables
     in the 'mysql' database, such as grant tables modified by
     'GRANT' or 'REVOKE' statements or table
     logging statements.  The timeout does apply to system tables
     accessed directly, such as with 'SELECT' or
     'UPDATE'.

     The timeout value applies separately for each metadata lock
     attempt.  A given statement can require more than one lock, so it
     is possible for the statement to block for longer than the
     'lock_wait_timeout' value before reporting a timeout error.  When
     lock timeout occurs, 'ER_LOCK_WAIT_TIMEOUT' is reported.

     'lock_wait_timeout' does not apply to delayed inserts, which always
     execute with a timeout of 1 year.  This is done to avoid
     unnecessary timeouts because a session that issues a delayed insert
     receives no notification of delayed insert timeouts.

   *
     'locked_in_memory'

     Property                             Value

     *System Variable*                    'locked_in_memory'

     *Scope*                              Global

     *Dynamic*                            No

     Whether 'mysqld' was locked in memory with
     '--memlock'.

   *
     'log_backward_compatible_user_definitions'

     Property                             Value

     *Command-Line Format*                '--log-backward-compatible-user-definitions[={OFF|ON}]'

     *Introduced*                         5.7.6

     *Removed*                            5.7.9

     *System Variable*                    'log_backward_compatible_user_definitions'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether to log the USER_SPECIFICATION part of 'CREATE USER',
     see 'ALTER USER', and 'GRANT'
     statements in backward-compatible (pre-5.7.6) fashion:

        * By default, this variable is disabled.  The server writes user
          specifications as 'USER IDENTIFIED WITH AUTH_PLUGIN AS
          'HASH_STRING''.

        * When enabled, the server writes user specifications as 'USER
          IDENTIFIED BY PASSWORD 'HASH_STRING''.  Enabling this variable
          ensures better compatibility for cross-version replication.

     This variable was removed in MySQL 5.7.9 and replaced by
     'log_builtin_as_identified_by_password'.

   *
     'log_bin_trust_function_creators'

     Property                             Value

     *Command-Line Format*                '--log-bin-trust-function-creators'

     *System Variable*                    'log_bin_trust_function_creators'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This variable applies when binary logging is enabled.  It controls
     whether stored function creators can be trusted not to create
     stored functions that will cause unsafe events to be written to the
     binary log.  If set to 0 (the default), users are not permitted to
     create or alter stored functions unless they have the 'SUPER'
     privilege in addition to the 'CREATE ROUTINE' or 'ALTER ROUTINE'
     privilege.  A setting of 0 also enforces the restriction that a
     function must be declared with the 'DETERMINISTIC' characteristic,
     or with the 'READS SQL DATA' or 'NO SQL' characteristic.  If the
     variable is set to 1, MySQL does not enforce these restrictions on
     stored function creation.  This variable also applies to trigger
     creation.  See stored-programs-logging.

   *
     'log_builtin_as_identified_by_password'

     Property                             Value

     *Command-Line Format*                '--log-builtin-as-identified-by-password[={OFF|ON}]'

     *Introduced*                         5.7.9

     *System Variable*                    'log_builtin_as_identified_by_password'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This variable affects binary logging of user-management statements.
     If enabled, binary logging for 'CREATE USER'.
     statements involving built-in authentication plugins rewrites the
     statements to include an 'IDENTIFIED BY PASSWORD' clause, and
     'SET PASSWORD' statements are logged as 'SET PASSWORD'
     statements, rather than being rewritten to
     'ALTER USER' statements.

     This variable was added in MySQL 5.7.9.  It replaces the
     'log_backward_compatible_user_definitions' variable.

   *
     'log_error'

     Property                             Value

     *Command-Line Format*                '--log-error[=file_name]'

     *System Variable*                    'log_error'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The error log output destination.  If the destination is the
     console, the value is 'stderr'.  Otherwise, the destination is a
     file and the 'log_error' value is the file name.  See
     error-log.

   *
     'log_error_verbosity'

     Property                             Value

     *Command-Line Format*                '--log-error-verbosity=#'

     *Introduced*                         5.7.2

     *System Variable*                    'log_error_verbosity'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '3'

     *Minimum Value*                      '1'

     *Maximum Value*                      '3'

     The verbosity of the server in writing error, warning, and note
     messages to the error log.  The following table shows the permitted
     values.  The default is 3.

     Desired Log Filtering         log_error_verbosity Value

     Error messages

     1

     Error and warning messages

     2

     Error, warning, and note
     messages

     3

     'log_error_verbosity' was added in MySQL 5.7.2.  It is preferred
     over, and should be used instead of, the older 'log_warnings'
     system variable.  See the description of 'log_warnings' for
     information about how that variable relates to
     'log_error_verbosity'.  In particular, assigning a value to
     'log_warnings' assigns a value to 'log_error_verbosity' and vice
     versa.

   *
     'log_output'

     Property                             Value

     *Command-Line Format*                '--log-output=name'

     *System Variable*                    'log_output'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               set

     *Default Value*                      'FILE'

     *Valid Values*                       'TABLE' 'FILE' 'NONE'

     The destination for general query log and slow query log output.
     The value can be a comma-separated list of one or more of the words
     'TABLE' (log to tables), 'FILE' (log to files), or 'NONE' (do not
     log to tables or files).  The default value is 'FILE'.  'NONE', if
     present, takes precedence over any other specifiers.  If the value
     is 'NONE' log entries are not written even if the logs are enabled.
     If the logs are not enabled, no logging occurs even if the value of
     'log_output' is not 'NONE'.  For more information, see
     log-destinations.

   *
     'log_queries_not_using_indexes'

     Property                             Value

     *Command-Line Format*                '--log-queries-not-using-indexes'

     *System Variable*                    'log_queries_not_using_indexes'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether queries that do not use indexes are logged to the slow
     query log.  See slow-query-log.

   *
     'log_syslog'

     Property                             Value

     *Command-Line Format*                '--log-syslog[={0|1}]'

     *Introduced*                         5.7.5

     *System Variable*                    'log_syslog'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (Windows)                     boolean

     *Type* (Unix)                        boolean

     *Default Value* (Windows)            'ON'

     *Default Value* (Unix)               'OFF'

     Whether to write error log output to the system log.  This is the
     Event Log on Windows, and 'syslog' on Unix and Unix-like systems.
     The default value is platform specific:

        * On Windows, Event Log output is enabled by default.

        * On Unix and Unix-like systems, 'syslog' output is disabled by
          default.

     Regardless of the default, 'log_syslog' can be set explicitly to
     control output on any supported platform.

     System log output control is distinct from sending error output to
     a file or the console.  Error output can be directed to a file or
     the console in addition to or instead of the system log as desired.
     See error-log.

   *
     'log_syslog_facility'

     Property                             Value

     *Command-Line Format*                '--log-syslog-facility=value'

     *Introduced*                         5.7.5

     *System Variable*                    'log_syslog_facility'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'daemon'

     The facility for error log output written to 'syslog' (what type of
     program is sending the message).  This variable has no effect
     unless the 'log_syslog' system variable is enabled.  See
     error-log.

     The permitted values can vary per operating system; consult your
     system 'syslog' documentation.

     This variable does not exist on Windows.

   *
     'log_syslog_include_pid'

     Property                             Value

     *Command-Line Format*                '--log-syslog-include-pid[={0|1}]'

     *Introduced*                         5.7.5

     *System Variable*                    'log_syslog_include_pid'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Whether to include the server process ID in each line of error log
     output written to 'syslog'.  This variable has no effect unless the
     'log_syslog' system variable is enabled.  See error-log.

     This variable does not exist on Windows.

   *
     'log_syslog_tag'

     Property                             Value

     *Command-Line Format*                '--log-syslog-tag=value'

     *Introduced*                         5.7.5

     *System Variable*                    'log_syslog_tag'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'empty string'

     The tag to be added to the server identifier in error log output
     written to 'syslog'.  This variable has no effect unless the
     'log_syslog' system variable is enabled.  See error-log.

     By default, the server identifier is 'mysqld' with no tag.  If a
     tag of TAG_VAL is specified, it is appended to the server
     identifier with a leading hyphen, resulting in an identifier of
     'mysqld-TAG_VAL'.

     On Windows, to use a tag that does not already exist, the server
     must be run from an account with Administrator privileges, to
     permit creation of a registry entry for the tag.  Elevated
     privileges are not required if the tag already exists.

   *
     'log_timestamps'

     Property                             Value

     *Command-Line Format*                '--log-timestamps=#'

     *Introduced*                         5.7.2

     *System Variable*                    'log_timestamps'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'UTC'

     *Valid Values*                       'UTC' 'SYSTEM'

     This variable controls the time zone of timestamps in messages
     written to the error log, and in general query log and slow query
     log messages written to files.  It does not affect the time zone of
     general query log and slow query log messages written to tables
     ('mysql.general_log', 'mysql.slow_log').  Rows retrieved from those
     tables can be converted from the local system time zone to any
     desired time zone with 'CONVERT_TZ()' or by setting the session
     'time_zone' system variable.

     Permitted 'log_timestamps' values are 'UTC' (the default) and
     'SYSTEM' (local system time zone).

     Timestamps are written using ISO 8601 / RFC 3339 format:
     'YYYY-MM-DDThh:mm:ss.uuuuuu' plus a tail value of 'Z' signifying
     Zulu time (UTC) or '±hh:mm' (an offset from UTC).

     This variable was added in MySQL 5.7.2.  Before 5.7.2, timestamps
     in log messages were written using the local system time zone by
     default, not 'UTC'.  If you want the previous log message time zone
     default, set 'log_timestamps=SYSTEM'.

   *
     'log_throttle_queries_not_using_indexes'

     Property                             Value

     *System Variable*                    'log_throttle_queries_not_using_indexes'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     If 'log_queries_not_using_indexes' is enabled, the
     'log_throttle_queries_not_using_indexes' variable limits the number
     of such queries per minute that can be written to the slow query
     log.  A value of 0 (the default) means 'no limit'.  For more
     information, see slow-query-log.

   *
     'log_slow_admin_statements'

     Property                             Value

     *Introduced*                         5.7.1

     *System Variable*                    'log_slow_admin_statements'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Include slow administrative statements in the statements written to
     the slow query log.  Administrative statements include 'ALTER TABLE',
     see 'ANALYZE TABLE',
     'CHECK TABLE', 'CREATE INDEX',
     'DROP INDEX', 'OPTIMIZE TABLE',
     and 'REPAIR TABLE'.

   *
     'log_warnings'

     Property                             Value

     *Command-Line Format*                '--log-warnings[=#]'

     *Deprecated*                         5.7.2

     *System Variable*                    'log_warnings'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms,   '2'
     >= 5.7.2)

     *Default Value* (64-bit platforms,   '1'
     <= 5.7.1)

     *Default Value* (32-bit platforms,   '2'
     >= 5.7.2)

     *Default Value* (32-bit platforms,   '1'
     <= 5.7.1)

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     Whether to produce additional warning messages to the error log.
     As of MySQL 5.7.2, information items previously governed by
     'log_warnings' are governed by 'log_error_verbosity', which is
     preferred over, and should be used instead of, the older
     'log_warnings' system variable.  (The 'log_warnings' system
     variable and '--log-warnings' command-line option are deprecated
     and will be removed in a future MySQL release.)

     'log_warnings' is enabled by default (the default is 1 before MySQL
     5.7.2, 2 as of 5.7.2).  To disable it, set it to 0.  If the value
     is greater than 0, the server logs messages about statements that
     are unsafe for statement-based logging.  If the value is greater
     than 1, the server logs aborted connections and access-denied
     errors for new connection attempts.  See
     communication-errors.

     If you use replication, enabling this variable by setting it
     greater than 0 is recommended, to get more information about what
     is happening, such as messages about network failures and
     reconnections.

     If a slave server is started with 'log_warnings' enabled, the slave
     prints messages to the error log to provide information about its
     status, such as the binary log and relay log coordinates where it
     starts its job, when it is switching to another relay log, when it
     reconnects after a disconnect, and so forth.

     Assigning a value to 'log_warnings' assigns a value to
     'log_error_verbosity' and vice versa.  The variables are related as
     follows:

        * Suppression of all 'log_warnings' items, achieved with
          'log_warnings=0', is achieved with 'log_error_verbosity=1'
          (errors only).

        * Items printed for 'log_warnings=1' or higher count as warnings
          and are printed for 'log_error_verbosity=2' or higher.

        * Items printed for 'log_warnings=2' count as notes and are
          printed for 'log_error_verbosity=3'.

     As of MySQL 5.7.2, the default log level is controlled by
     'log_error_verbosity', which has a default of 3.  In addition, the
     default for 'log_warnings' changes from 1 to 2, which corresponds
     to 'log_error_verbosity=3'.  To achieve a logging level similar to
     the previous default, set 'log_error_verbosity=2'.

     In MySQL 5.7.2 and higher, use of 'log_warnings' is still permitted
     but maps onto use of 'log_error_verbosity' as follows:

        * Setting 'log_warnings=0' is equivalent to
          'log_error_verbosity=1' (errors only).

        * Setting 'log_warnings=1' is equivalent to
          'log_error_verbosity=2' (errors, warnings).

        * Setting 'log_warnings=2' (or higher) is equivalent to
          'log_error_verbosity=3' (errors, warnings, notes), and the
          server sets 'log_warnings' to 2 if a larger value is
          specified.

   *
     'long_query_time'

     Property                             Value

     *Command-Line Format*                '--long-query-time=#'

     *System Variable*                    'long_query_time'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               numeric

     *Default Value*                      '10'

     *Minimum Value*                      '0'

     If a query takes longer than this many seconds, the server
     increments the 'Slow_queries' status variable.  If the slow query
     log is enabled, the query is logged to the slow query log file.
     This value is measured in real time, not CPU time, so a query that
     is under the threshold on a lightly loaded system might be above
     the threshold on a heavily loaded one.  The minimum and default
     values of 'long_query_time' are 0 and 10, respectively.  The value
     can be specified to a resolution of microseconds.  For logging to a
     file, times are written including the microseconds part.  For
     logging to tables, only integer times are written; the microseconds
     part is ignored.  See slow-query-log.

   *
     'low_priority_updates'

     Property                             Value

     *Command-Line Format*                '--low-priority-updates'

     *System Variable*                    'low_priority_updates'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'FALSE'

     If set to '1', all 'INSERT', 'UPDATE',
     'DELETE', and 'LOCK TABLE WRITE' statements wait
     until there is no pending 'SELECT' or 'LOCK TABLE
     READ' on the affected table.  This affects only storage engines
     that use only table-level locking (such as 'MyISAM', 'MEMORY', and
     'MERGE').

   *
     'lower_case_file_system'

     Property                             Value

     *System Variable*                    'lower_case_file_system'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     This variable describes the case sensitivity of file names on the
     file system where the data directory is located.  'OFF' means file
     names are case-sensitive, 'ON' means they are not case-sensitive.
     This variable is read only because it reflects a file system
     attribute and setting it would have no effect on the file system.

   *
     'lower_case_table_names'

     Property                             Value

     *Command-Line Format*                '--lower-case-table-names[=#]'

     *System Variable*                    'lower_case_table_names'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '2'

     If set to 0, table names are stored as specified and comparisons
     are case-sensitive.  If set to 1, table names are stored in
     lowercase on disk and comparisons are not case sensitive.  If set
     to 2, table names are stored as given but compared in lowercase.
     This option also applies to database names and table aliases.  For
     additional information, see identifier-case-sensitivity.

     On Windows the default value is 1.  On OS X, the default value is
     2.

     You should _not_ set 'lower_case_table_names' to 0 if you are
     running MySQL on a system where the data directory resides on a
     case-insensitive file system (such as on Windows or OS X). It is an
     unsupported combination that could result in a hang condition when
     running an 'INSERT INTO ... SELECT ... FROM TBL_NAME' operation
     with the wrong TBL_NAME letter case.  With 'MyISAM', accessing
     table names using different letter cases could cause index
     corruption.

     An error message is printed and the server exits if you attempt to
     start the server with '--lower_case_table_names=0' on a
     case-insensitive file system.

     If you are using 'InnoDB' tables, you should set this variable to 1
     on all platforms to force names to be converted to lowercase.

     The setting of this variable in MySQL 5.7 affects the behavior of
     replication filtering options with regard to case sensitivity.
     (Bug #51639) See replication-rules, for more information.

   *
     'max_allowed_packet'

     Property                             Value

     *Command-Line Format*                '--max-allowed-packet=#'

     *System Variable*                    'max_allowed_packet'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '4194304'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '1073741824'

     The maximum size of one packet or any generated/intermediate
     string, or any parameter sent by the
     'mysql_stmt_send_long_data()'. C API
     function.  The default is 4MB.

     The packet message buffer is initialized to 'net_buffer_length'
     bytes, but can grow up to 'max_allowed_packet' bytes when needed.
     This value by default is small, to catch large (possibly incorrect)
     packets.

     You must increase this value if you are using large 'BLOB'
     columns or long strings.  It should be as big as the largest
     'BLOB' you want to use.  The protocol limit for
     'max_allowed_packet' is 1GB. The value should be a multiple of
     1024; nonmultiples are rounded down to the nearest multiple.

     When you change the message buffer size by changing the value of
     the 'max_allowed_packet' variable, you should also change the
     buffer size on the client side if your client program permits it.
     The default 'max_allowed_packet' value built in to the client
     library is 1GB, but individual client programs might override this.
     For example, see 'mysql' and 'mysqldump'
     have defaults of 16MB and 24MB, respectively.  They also
     enable you to change the client-side value by setting
     'max_allowed_packet' on the command line or in an option file.

     The session value of this variable is read only.  The client can
     receive up to as many bytes as the session value.  However, the
     server will not send to the client more bytes than the current
     global 'max_allowed_packet' value.  (The global value could be less
     than the session value if the global value is changed after the
     client connects.)

   *
     'max_connect_errors'

     Property                             Value

     *Command-Line Format*                '--max-connect-errors=#'

     *System Variable*                    'max_connect_errors'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '100'

     *Default Value* (32-bit platforms)   '100'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     If more than this many successive connection requests from a host
     are interrupted without a successful connection, the server blocks
     that host from further connections.  You can unblock blocked hosts
     by flushing the host cache.  To do so, issue a 'FLUSH HOSTS'
     statement or execute a 'mysqladmin flush-hosts'.
     command.  If a connection is established successfully within fewer
     than 'max_connect_errors' attempts after a previous connection was
     interrupted, the error count for the host is cleared to zero.
     However, once a host is blocked, flushing the host cache is the
     only way to unblock it.  The default is 100.

   *
     'max_connections'

     Property                             Value

     *Command-Line Format*                '--max-connections=#'

     *System Variable*                    'max_connections'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '151'

     *Minimum Value*                      '1'

     *Maximum Value*                      '100000'

     The maximum permitted number of simultaneous client connections.
     By default, this is 151.  See too-many-connections, for
     more information.

     Increasing this value increases the number of file descriptors that
     'mysqld' requires.  If the required number of
     descriptors are not available, the server reduces the value of
     'max_connections'.  See table-cache, for comments on file
     descriptor limits.

     'mysqld' actually permits 'max_connections+1'
     clients to connect.  The extra connection is reserved for use by
     accounts that have the 'SUPER' privilege.  By granting the 'SUPER'
     privilege to administrators and not to normal users (who should not
     need it), an administrator can connect to the server and use
     'SHOW PROCESSLIST' to diagnose problems even if
     the maximum number of unprivileged clients are connected.  See
     show-processlist.

     Connections refused because the 'max_connections' limit is reached
     increment the 'Connection_errors_max_connections' status variable.

   *
     'max_delayed_threads'

     Property                             Value

     *Command-Line Format*                '--max-delayed-threads=#'

     *Deprecated*                         Yes

     *System Variable*                    'max_delayed_threads'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '20'

     *Minimum Value*                      '0'

     *Maximum Value*                      '16384'

     This system variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   *
     'max_digest_length'

     Property                             Value

     *Command-Line Format*                '--max-digest-length=#'

     *Introduced*                         5.7.6

     *System Variable*                    'max_digest_length'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1048576'

     The maximum number of bytes available for computing normalized
     statement digests.  Once that amount of space is used during digest
     computation, truncation occurs: no further tokens from a parsed
     statement are collected or figure into its digest value.
     Statements that differ only after that many bytes of parsed tokens
     produce the same normalized statement digest and are considered
     identical if compared or if aggregated for digest statistics.

     Decreasing the 'max_digest_length' value reduces memory use but
     causes the digest value of more statements to become
     indistinguishable if they differ only at the end.  Increasing the
     value permits longer statements to be distinguished but increases
     memory use, particularly for workloads that involve large numbers
     of simultaneous sessions (the server allocates 'max_digest_length'
     bytes per session).

     The parser uses this system variable as a limit on the maximum
     length of normalized statement digests that it computes.  The
     Performance Schema, if it tracks statement digests, makes a copy of
     the digest value, using the 'performance_schema_max_digest_length'.
     system variable as a limit on the maximum length of digests that it
     stores.  Consequently, if 'performance_schema_max_digest_length' is
     less than 'max_digest_length', digest values stored in the
     Performance Schema are truncated relative to the original digest
     values.

     For more information about statement digesting, see
     performance-schema-statement-digests.

   *
     'max_error_count'

     Property                             Value

     *Command-Line Format*                '--max-error-count=#'

     *System Variable*                    'max_error_count'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '64'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     The maximum number of error, warning, and note messages to be
     stored for display by the 'SHOW ERRORS' and
     'SHOW WARNINGS' statements.  This is the same
     as the number of condition areas in the diagnostics area, and thus
     the number of conditions that can be inspected by 'GET DIAGNOSTICS'.

   *
     'max_execution_time'

     Property                             Value

     *Command-Line Format*                '--max-execution-time=#'

     *Introduced*                         5.7.8

     *System Variable*                    'max_execution_time'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     The execution timeout for 'SELECT' statements, in
     milliseconds.  If the value is 0, timeouts are not enabled.

     'max_execution_time' applies as follows:

        * The global 'max_execution_time' value provides the default for
          the session value for new connections.  The session value
          applies to 'SELECT' executions executed within the session
          that include no 'MAX_EXECUTION_TIME(N)' optimizer hint or for
          which N is 0.

        * 'max_execution_time' applies to read-only 'SELECT'
          statements.  Statements that are not read only are
          those that invoke a stored function that modifies data as a
          side effect.

        * 'max_execution_time' is ignored for 'SELECT'.
          statements in stored programs.

   *
     'max_heap_table_size'

     Property                             Value

     *Command-Line Format*                '--max-heap-table-size=#'

     *System Variable*                    'max_heap_table_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '16777216'

     *Default Value* (32-bit platforms)   '16777216'

     *Minimum Value* (64-bit platforms)   '16384'

     *Minimum Value* (32-bit platforms)   '16384'

     *Maximum Value* (64-bit platforms)   '1844674407370954752'

     *Maximum Value* (32-bit platforms)   '4294967295'

     This variable sets the maximum size to which user-created 'MEMORY'
     tables are permitted to grow.  The value of the variable is used to
     calculate 'MEMORY' table 'MAX_ROWS' values.  Setting this variable
     has no effect on any existing 'MEMORY' table, unless the table is
     re-created with a statement such as 'CREATE TABLE'
     or altered with 'ALTER TABLE' or
     'TRUNCATE TABLE'.  A server restart also sets
     the maximum size of existing 'MEMORY' tables to the global
     'max_heap_table_size' value.

     This variable is also used in conjunction with 'tmp_table_size' to
     limit the size of internal in-memory tables.  See
     internal-temporary-tables.

     'max_heap_table_size' is not replicated.  See
     replication-features-memory, and
     replication-features-variables, for more information.

   *
     'max_insert_delayed_threads'

     Property                             Value

     *Deprecated*                         Yes

     *System Variable*                    'max_insert_delayed_threads'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     This variable is a synonym for 'max_delayed_threads'.

     This system variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   *
     'max_join_size'

     Property                             Value

     *Command-Line Format*                '--max-join-size=#'

     *System Variable*                    'max_join_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '18446744073709551615'

     *Minimum Value*                      '1'

     *Maximum Value*                      '18446744073709551615'

     Do not permit statements that probably need to examine more than
     'max_join_size' rows (for single-table statements) or row
     combinations (for multiple-table statements) or that are likely to
     do more than 'max_join_size' disk seeks.  By setting this value,
     you can catch statements where keys are not used properly and that
     would probably take a long time.  Set it if your users tend to
     perform joins that lack a 'WHERE' clause, that take a long time, or
     that return millions of rows.

     Setting this variable to a value other than 'DEFAULT' resets the
     value of 'sql_big_selects' to '0'.  If you set the
     'sql_big_selects' value again, the 'max_join_size' variable is
     ignored.

     If a query result is in the query cache, no result size check is
     performed, because the result has previously been computed and it
     does not burden the server to send it to the client.

   *
     'max_length_for_sort_data'

     Property                             Value

     *Command-Line Format*                '--max-length-for-sort-data=#'

     *System Variable*                    'max_length_for_sort_data'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '4'

     *Maximum Value*                      '8388608'

     The cutoff on the size of index values that determines which
     'filesort' algorithm to use.  See order-by-optimization.

   *
     'max_points_in_geometry'

     Property                             Value

     *Command-Line Format*                '--max-points-in-geometry=integer'

     *Introduced*                         5.7.8

     *System Variable*                    'max_points_in_geometry'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '65536'

     *Minimum Value*                      '3'

     *Maximum Value*                      '1048576'

     The maximum value of the POINTS_PER_CIRCLE argument to the
     'ST_Buffer_Strategy()' function.

   *
     'max_prepared_stmt_count'

     Property                             Value

     *Command-Line Format*                '--max-prepared-stmt-count=#'

     *System Variable*                    'max_prepared_stmt_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '16382'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1048576'

     This variable limits the total number of prepared statements in the
     server.  It can be used in environments where there is the
     potential for denial-of-service attacks based on running the server
     out of memory by preparing huge numbers of statements.  If the
     value is set lower than the current number of prepared statements,
     existing statements are not affected and can be used, but no new
     statements can be prepared until the current number drops below the
     limit.  The default value is 16,382.  The permissible range of
     values is from 0 to 1 million.  Setting the value to 0 disables
     prepared statements.

   *
     'max_relay_log_size'

     Property                             Value

     *Command-Line Format*                '--max-relay-log-size=#'

     *System Variable*                    'max_relay_log_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1073741824'

     If a write by a replication slave to its relay log causes the
     current log file size to exceed the value of this variable, the
     slave rotates the relay logs (closes the current file and opens the
     next one).  If 'max_relay_log_size' is 0, the server uses
     'max_binlog_size' for both the binary log and the relay log.  If
     'max_relay_log_size' is greater than 0, it constrains the size of
     the relay log, which enables you to have different sizes for the
     two logs.  You must set 'max_relay_log_size' to between 4096 bytes
     and 1GB (inclusive), or to 0.  The default value is 0.  See
     replication-implementation-details.

   *
     'max_seeks_for_key'

     Property                             Value

     *Command-Line Format*                '--max-seeks-for-key=#'

     *System Variable*                    'max_seeks_for_key'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '18446744073709551615'

     *Default Value* (32-bit platforms)   '4294967295'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     Limit the assumed maximum number of seeks when looking up rows
     based on a key.  The MySQL optimizer assumes that no more than this
     number of key seeks are required when searching for matching rows
     in a table by scanning an index, regardless of the actual
     cardinality of the index (see show-index).  By setting this
     to a low value (say, 100), you can force MySQL to prefer indexes
     instead of table scans.

   *
     'max_sort_length'

     Property                             Value

     *Command-Line Format*                '--max-sort-length=#'

     *System Variable*                    'max_sort_length'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '4'

     *Maximum Value*                      '8388608'

     The number of bytes to use when sorting data values.  The server
     uses only the first 'max_sort_length' bytes of each value and
     ignores the rest.  Consequently, values that differ only after the
     first 'max_sort_length' bytes compare as equal for 'GROUP BY',
     'ORDER BY', and 'DISTINCT' operations.

     Increasing the value of 'max_sort_length' may require increasing
     the value of 'sort_buffer_size' as well.  For details, see
     order-by-optimization

   *
     'max_sp_recursion_depth'

     Property                             Value

     *Command-Line Format*                '--max-sp-recursion-depth[=#]'

     *System Variable*                    'max_sp_recursion_depth'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Maximum Value*                      '255'

     The number of times that any given stored procedure may be called
     recursively.  The default value for this option is 0, which
     completely disables recursion in stored procedures.  The maximum
     value is 255.

     Stored procedure recursion increases the demand on thread stack
     space.  If you increase the value of 'max_sp_recursion_depth', it
     may be necessary to increase thread stack size by increasing the
     value of 'thread_stack' at server startup.

   *
     'max_statement_time'

     Property                             Value

     *Introduced*                         5.7.4

     *Removed*                            5.7.8

     *System Variable*                    'max_statement_time'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     This variable was added in MySQL 5.7.4 and renamed to
     'max_execution_time' in MySQL 5.7.8.

   *
     'max_tmp_tables'

     This variable is unused.  It is deprecated and is removed in MySQL
     8.0.

   *
     'max_user_connections'

     Property                             Value

     *Command-Line Format*                '--max-user-connections=#'

     *System Variable*                    'max_user_connections'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     The maximum number of simultaneous connections permitted to any
     given MySQL user account.  A value of 0 (the default) means 'no
     limit.'

     This variable has a global value that can be set at server startup
     or runtime.  It also has a read-only session value that indicates
     the effective simultaneous-connection limit that applies to the
     account associated with the current session.  The session value is
     initialized as follows:

        * If the user account has a nonzero 'MAX_USER_CONNECTIONS'
          resource limit, the session 'max_user_connections' value is
          set to that limit.

        * Otherwise, the session 'max_user_connections' value is set to
          the global value.

     Account resource limits are specified using the 'CREATE USER'
     or 'ALTER USER' statement.
     See user-resources.

   *
     'max_write_lock_count'

     Property                             Value

     *Command-Line Format*                '--max-write-lock-count=#'

     *System Variable*                    'max_write_lock_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '18446744073709551615'

     *Default Value* (32-bit platforms)   '4294967295'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     After this many write locks, permit some pending read lock requests
     to be processed in between.

   *
     'mecab_rc_file'

     Property                             Value

     *Command-Line Format*                '--mecab-rc-file'

     *Introduced*                         5.7.6

     *System Variable*                    'mecab_rc_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The 'mecab_rc_file' option is used when setting up the MeCab
     full-text parser.

     The 'mecab_rc_file' option defines the path to the 'mecabrc'
     configuration file, which is the configuration file for MeCab.  The
     option is read-only and can only be set at startup.  The 'mecabrc'
     configuration file is required to initialize MeCab.

     For information about the MeCab full-text parser, see
     fulltext-search-mecab.

     For information about options that can be specified in the MeCab
     'mecabrc' configuration file, refer to the MeCab Documentation
     (http://mecab.googlecode.com/svn/trunk/mecab/doc/index.html) on the
     Google Developers (https://code.google.com/) site.

   *
     'metadata_locks_cache_size'

     Property                             Value

     *Deprecated*                         5.7.4

     *System Variable*                    'metadata_locks_cache_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1048576'

     The size of the metadata locks cache.  The server uses this cache
     to avoid creation and destruction of synchronization objects.  This
     is particularly helpful on systems where such operations are
     expensive, such as Windows XP.

     In MySQL 5.7.4, metadata locking implementation changes make this
     variable unnecessary, so it is deprecated and will be removed in a
     future MySQL release.

   *
     'metadata_locks_hash_instances'

     Property                             Value

     *Deprecated*                         5.7.4

     *System Variable*                    'metadata_locks_hash_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '8'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1024'

     The set of metadata locks can be partitioned into separate hashes
     to permit connections accessing different objects to use different
     locking hashes and reduce contention.  The
     'metadata_locks_hash_instances' system variable specifies the
     number of hashes (default 8).

     In MySQL 5.7.4, metadata locking implementation changes make this
     variable unnecessary, so it is deprecated and will be removed in a
     future MySQL release.

   *
     'min_examined_row_limit'

     Property                             Value

     *Command-Line Format*                '--min-examined-row-limit=#'

     *System Variable*                    'min_examined_row_limit'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '0'

     *Default Value* (32-bit platforms)   '0'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     Queries that examine fewer than this number of rows are not logged
     to the slow query log.

   * 'multi_range_count'

     Property                             Value

     *Command-Line Format*                '--multi-range-count=#'

     *Deprecated*                         Yes

     *System Variable*                    'multi_range_count'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '256'

     *Minimum Value*                      '1'

     *Maximum Value*                      '4294967295'

     This variable has no effect.  It is deprecated and is removed in
     MySQL 8.0.

   *
     'myisam_data_pointer_size'

     Property                             Value

     *Command-Line Format*                '--myisam-data-pointer-size=#'

     *System Variable*                    'myisam_data_pointer_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '6'

     *Minimum Value*                      '2'

     *Maximum Value*                      '7'

     The default pointer size in bytes, to be used by 'CREATE TABLE'
     for 'MyISAM' tables when no 'MAX_ROWS' option
     is specified.  This variable cannot be less than 2 or larger than
     7.  The default value is 6.  See full-table.

   *
     'myisam_max_sort_file_size'

     Property                             Value

     *Command-Line Format*                '--myisam-max-sort-file-size=#'

     *System Variable*                    'myisam_max_sort_file_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '9223372036854775807'

     *Default Value* (32-bit platforms)   '2147483648'

     The maximum size of the temporary file that MySQL is permitted to
     use while re-creating a 'MyISAM' index (during 'REPAIR TABLE',
     see 'ALTER TABLE', or
     'LOAD DATA INFILE').  If the file size would be larger
     than this value, the index is created using the key cache instead,
     which is slower.  The value is given in bytes.

     If 'MyISAM' index files exceed this size and disk space is
     available, increasing the value may help performance.  The space
     must be available in the file system containing the directory where
     the original index file is located.

   *
     'myisam_mmap_size'

     Property                             Value

     *Command-Line Format*                '--myisam-mmap-size=#'

     *System Variable*                    'myisam_mmap_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '18446744073709551615'

     *Default Value* (32-bit platforms)   '4294967295'

     *Minimum Value* (64-bit platforms)   '7'

     *Minimum Value* (32-bit platforms)   '7'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The maximum amount of memory to use for memory mapping compressed
     'MyISAM' files.  If many compressed
     'MyISAM' tables are used, the value can be decreased to reduce the
     likelihood of memory-swapping problems.

   *
     'myisam_recover_options'

     Property                             Value

     *System Variable*                    'myisam_recover_options'

     *Scope*                              Global

     *Dynamic*                            No

     The value of the '--myisam-recover-options' option.  See
     server-options.

   *
     'myisam_repair_threads'

     Property                             Value

     *Command-Line Format*                '--myisam-repair-threads=#'

     *System Variable*                    'myisam_repair_threads'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1'

     *Default Value* (32-bit platforms)   '1'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     If this value is greater than 1, 'MyISAM' table indexes are created
     in parallel (each index in its own thread) during the 'Repair by
     sorting' process.  The default value is 1.

     *Note*:

     Multi-threaded repair is still _beta-quality_ code.

   *
     'myisam_sort_buffer_size'

     Property                             Value

     *Command-Line Format*                '--myisam-sort-buffer-size=#'

     *System Variable*                    'myisam_sort_buffer_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (Other, 64-bit platforms)     integer

     *Type* (Other, 32-bit platforms)     integer

     *Type* (Windows, 64-bit platforms)   integer

     *Type* (Windows, 32-bit platforms)   integer

     *Default Value* (Other, 64-bit       '8388608'
     platforms)

     *Default Value* (Other, 32-bit       '8388608'
     platforms)

     *Default Value* (Windows, 64-bit     '8388608'
     platforms)

     *Default Value* (Windows, 32-bit     '8388608'
     platforms)

     *Minimum Value* (Other, 64-bit       '4096'
     platforms)

     *Minimum Value* (Other, 32-bit       '4096'
     platforms)

     *Minimum Value* (Windows, 64-bit     '4096'
     platforms)

     *Minimum Value* (Windows, 32-bit     '4096'
     platforms)

     *Maximum Value* (Other, 64-bit       '18446744073709551615'
     platforms)

     *Maximum Value* (Other, 32-bit       '4294967295'
     platforms)

     *Maximum Value* (Windows, 64-bit     '18446744073709551615'
     platforms)

     *Maximum Value* (Windows, 32-bit     '4294967295'
     platforms)

     The size of the buffer that is allocated when sorting 'MyISAM'
     indexes during a 'REPAIR TABLE' or when
     creating indexes with 'CREATE INDEX' or
     'ALTER TABLE'.

     The maximum permissible setting for 'myisam_sort_buffer_size' is
     4GB−1.  Larger values are permitted for 64-bit platforms.

   *
     'myisam_stats_method'

     Property                             Value

     *Command-Line Format*                '--myisam-stats-method=name'

     *System Variable*                    'myisam_stats_method'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'nulls_unequal'

     *Valid Values*                       'nulls_equal' 'nulls_unequal'
                                          'nulls_ignored'

     How the server treats 'NULL' values when collecting statistics
     about the distribution of index values for 'MyISAM' tables.  This
     variable has three possible values, 'nulls_equal', 'nulls_unequal',
     and 'nulls_ignored'.  For 'nulls_equal', all 'NULL' index values
     are considered equal and form a single value group that has a size
     equal to the number of 'NULL' values.  For 'nulls_unequal', 'NULL'
     values are considered unequal, and each 'NULL' forms a distinct
     value group of size 1.  For 'nulls_ignored', 'NULL' values are
     ignored.

     The method that is used for generating table statistics influences
     how the optimizer chooses indexes for query execution, as described
     in index-statistics.

   *
     'myisam_use_mmap'

     Property                             Value

     *Command-Line Format*                '--myisam-use-mmap'

     *System Variable*                    'myisam_use_mmap'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Use memory mapping for reading and writing 'MyISAM' tables.

   *
     'mysql_native_password_proxy_users'

     Property                             Value

     *Command-Line Format*                '--mysql-native-password-proxy-users=[={OFF|ON}]'

     *Introduced*                         5.7.7

     *System Variable*                    'mysql_native_password_proxy_users'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This variable controls whether the 'mysql_native_password' built-in
     authentication plugin supports proxy users.  It has no effect
     unless the 'check_proxy_users' system variable is enabled.  For
     information about user proxying, see proxy-users.

     This variable was added in MySQL 5.7.7.  Before 5.7.7,
     'mysql_native_password' does not support proxy users.

   *
     'named_pipe'

     Property                             Value

     *System Variable*                    'named_pipe'

     *Scope*                              Global

     *Dynamic*                            No

     *Platform Specific*                  Windows

     *Type* (Windows)                     boolean

     *Default Value* (Windows)            'OFF'

     (Windows only.)  Indicates whether the server supports connections
     over named pipes.

   *
     'net_buffer_length'

     Property                             Value

     *Command-Line Format*                '--net-buffer-length=#'

     *System Variable*                    'net_buffer_length'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '16384'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '1048576'

     Each client thread is associated with a connection buffer and
     result buffer.  Both begin with a size given by 'net_buffer_length'
     but are dynamically enlarged up to 'max_allowed_packet' bytes as
     needed.  The result buffer shrinks to 'net_buffer_length' after
     each SQL statement.

     This variable should not normally be changed, but if you have very
     little memory, you can set it to the expected length of statements
     sent by clients.  If statements exceed this length, the connection
     buffer is automatically enlarged.  The maximum value to which
     'net_buffer_length' can be set is 1MB.

     The session value of this variable is read only.

   *
     'net_read_timeout'

     Property                             Value

     *Command-Line Format*                '--net-read-timeout=#'

     *System Variable*                    'net_read_timeout'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '30'

     *Minimum Value*                      '1'

     The number of seconds to wait for more data from a connection
     before aborting the read.  When the server is reading from the
     client, 'net_read_timeout' is the timeout value controlling when to
     abort.  When the server is writing to the client,
     'net_write_timeout' is the timeout value controlling when to abort.
     See also 'slave_net_timeout'.

   *
     'net_retry_count'

     Property                             Value

     *Command-Line Format*                '--net-retry-count=#'

     *System Variable*                    'net_retry_count'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '10'

     *Default Value* (32-bit platforms)   '10'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     If a read or write on a communication port is interrupted, retry
     this many times before giving up.  This value should be set quite
     high on FreeBSD because internal interrupts are sent to all
     threads.

   *
     'net_write_timeout'

     Property                             Value

     *Command-Line Format*                '--net-write-timeout=#'

     *System Variable*                    'net_write_timeout'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '60'

     *Minimum Value*                      '1'

     The number of seconds to wait for a block to be written to a
     connection before aborting the write.  See also 'net_read_timeout'.

   *
     'new'

     Property                             Value

     *Command-Line Format*                '--new'

     *System Variable*                    'new'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Disabled by*                        'skip-new'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This variable was used in MySQL 4.0 to turn on some 4.1 behaviors,
     and is retained for backward compatibility.  Its value is always
     'OFF'.

     In NDB Cluster, setting this variable to 'ON' makes it possible to
     employ partitioning types other than 'KEY' or 'LINEAR KEY' with
     'NDB' tables.  _This feature is experimental
     only, and not supported in production_.  For additional
     information, see partitioning-limitations-ndb.

   *
     'ngram_token_size'

     Property                             Value

     *Command-Line Format*                '--ngram-token-size'

     *Introduced*                         5.7.6

     *System Variable*                    'ngram_token_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '2'

     *Minimum Value*                      '1'

     *Maximum Value*                      '10'

     Defines the n-gram token size for the n-gram full-text parser.  The
     'ngram_token_size' option is read-only and can only be modified at
     startup.  The default value is 2 (bigram).  The maximum value is
     10.

     For more information about how to configure this variable, see
     fulltext-search-ngram.

   *
     'offline_mode'

     Property                             Value

     *Command-Line Format*                '--offline-mode=val'

     *Introduced*                         5.7.5

     *System Variable*                    'offline_mode'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether the server is in 'offline mode', which has these
     characteristics:

        * Connected client users who do not have the 'SUPER' privilege
          are disconnected on the next request, with an appropriate
          error.  Disconnection includes terminating running statements
          and releasing locks.  Such clients also cannot initiate new
          connections, and receive an appropriate error.

        * Connected client users who have the 'SUPER' privilege are not
          disconnected, and can initiate new connections to manage the
          server.

        * Replication slave threads are permitted to keep applying data
          to the server.

     Only users who have the 'SUPER' privilege can control offline mode.
     To put a server in offline mode, change the value of the
     'offline_mode' system variable from 'OFF' to 'ON'.  To resume
     normal operations, change 'offline_mode' from 'ON' to 'OFF'.  In
     offline mode, clients that are refused access receive an
     'ER_SERVER_OFFLINE_MODE' error.

   *
     'old'

     Property                             Value

     *Command-Line Format*                '--old'

     *System Variable*                    'old'

     *Scope*                              Global

     *Dynamic*                            No

     'old' is a compatibility variable.  It is disabled by default, but
     can be enabled at startup to revert the server to behaviors present
     in older versions.

     When 'old' is enabled, it changes the default scope of index hints
     to that used prior to MySQL 5.1.17.  That is, index hints with no
     'FOR' clause apply only to how indexes are used for row retrieval
     and not to resolution of 'ORDER BY' or 'GROUP BY' clauses.  (See
     index-hints.)  Take care about enabling this in a
     replication setup.  With statement-based binary logging, having
     different modes for the master and slaves might lead to replication
     errors.

   *
     'old_alter_table'

     Property                             Value

     *Command-Line Format*                '--old-alter-table'

     *System Variable*                    'old_alter_table'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     When this variable is enabled, the server does not use the
     optimized method of processing an 'ALTER TABLE'.
     operation.  It reverts to using a temporary table, copying over the
     data, and then renaming the temporary table to the original, as
     used by MySQL 5.0 and earlier.  For more information on the
     operation of 'ALTER TABLE', see
     alter-table.

   *
     'old_passwords'

     Property                             Value

     *Deprecated*                         5.7.6

     *System Variable*                    'old_passwords'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      '0'

     *Valid Values* (>= 5.7.5)            '0' '2'

     *Valid Values* (<= 5.7.4)            '0' '1' '2'

     *Note*:

     This system variable is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.

     This variable controls the password hashing method used by the
     'PASSWORD()' function.  It also influences password hashing
     performed by 'CREATE USER' and 'GRANT'
     statements that specify a password using an 'IDENTIFIED BY'
     clause.

     The following table shows, for each password hashing method, the
     permitted value of 'old_passwords' and which authentication plugins
     use the hashing method.

     Password Hashing Method       old_passwords  Associated Authentication
                                   Value          Plugin

     MySQL 4.1 native hashing      0              'mysql_native_password'

     SHA-256 hashing               2              'sha256_password'

     If you set 'old_passwords=2', follow the instructions for using the
     'sha256_password' plugin at
     sha256-pluggable-authentication.

     The server sets the global 'old_passwords' value during startup to
     be consistent with the password hashing method required by the
     authentication plugin indicated by the
     'default_authentication_plugin' system variable.

     When a client successfully connects to the server, the server sets
     the session 'old_passwords' value appropriately for the account
     authentication method.  For example, if the account uses the
     'sha256_password' authentication plugin, the server sets
     'old_passwords=2'.

     For additional information about authentication plugins and hashing
     formats, see pluggable-authentication, and
     password-hashing.

   *
     'open_files_limit'

     Property                             Value

     *Command-Line Format*                '--open-files-limit=#'

     *System Variable*                    'open_files_limit'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '5000, with possible adjustment'

     *Minimum Value*                      '0'

     *Maximum Value*                      'platform dependent'

     The number of files that the operating system permits
     'mysqld' to open.  The value of this variable at runtime
     is the real value permitted by the system and might be different
     from the value you specify at server startup.  The value is 0 on
     systems where MySQL cannot change the number of open files.

     The effective 'open_files_limit' value is based on the value
     specified at system startup (if any) and the values of
     'max_connections' and 'table_open_cache', using these formulas:

          1) 10 + max_connections + (table_open_cache * 2)
          2) max_connections * 5
          3) operating system limit if positive
          4) if operating system limit is Infinity:
             open_files_limit value specified at startup, 5000 if none

     The server attempts to obtain the number of file descriptors using
     the maximum of those three values.  If that many descriptors cannot
     be obtained, the server attempts to obtain as many as the system
     will permit.

   *
     'optimizer_prune_level'

     Property                             Value

     *Command-Line Format*                '--optimizer-prune-level[=#]'

     *System Variable*                    'optimizer_prune_level'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '1'

     Controls the heuristics applied during query optimization to prune
     less-promising partial plans from the optimizer search space.  A
     value of 0 disables heuristics so that the optimizer performs an
     exhaustive search.  A value of 1 causes the optimizer to prune
     plans based on the number of rows retrieved by intermediate plans.

   *
     'optimizer_search_depth'

     Property                             Value

     *Command-Line Format*                '--optimizer-search-depth[=#]'

     *System Variable*                    'optimizer_search_depth'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '62'

     *Minimum Value*                      '0'

     *Maximum Value*                      '62'

     The maximum depth of search performed by the query optimizer.
     Values larger than the number of relations in a query result in
     better query plans, but take longer to generate an execution plan
     for a query.  Values smaller than the number of relations in a
     query return an execution plan quicker, but the resulting plan may
     be far from being optimal.  If set to 0, the system automatically
     picks a reasonable value.

   *
     'optimizer_switch'

     Property                             Value

     *Command-Line Format*                '--optimizer-switch=value'

     *System Variable*                    'optimizer_switch'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               set

     *Valid Values* (>= 5.7.8)            'batched_key_access={on|off}'
                                          'block_nested_loop={on|off}'
                                          'condition_fanout_filter={on|off}'
                                          'derived_merge={on|off}'
                                          'duplicateweedout={on|off}'
                                          'engine_condition_pushdown={on|off}'
                                          'firstmatch={on|off}'
                                          'index_condition_pushdown={on|off}'
                                          'index_merge={on|off}'
                                          'index_merge_intersection={on|off}'
                                          'index_merge_sort_union={on|off}'
                                          'index_merge_union={on|off}'
                                          'loosescan={on|off}'
                                          'materialization={on|off}'
                                          'mrr={on|off}'
                                          'mrr_cost_based={on|off}'
                                          'semijoin={on|off}'
                                          'subquery_materialization_cost_based={on|off}'
                                          'use_index_extensions={on|off}'

     *Valid Values* (>= 5.7.6, <=         'batched_key_access={on|off}'
     5.7.7)                               'block_nested_loop={on|off}'
                                          'condition_fanout_filter={on|off}'
                                          'derived_merge={on|off}'
                                          'engine_condition_pushdown={on|off}'
                                          'firstmatch={on|off}'
                                          'index_condition_pushdown={on|off}'
                                          'index_merge={on|off}'
                                          'index_merge_intersection={on|off}'
                                          'index_merge_sort_union={on|off}'
                                          'index_merge_union={on|off}'
                                          'loosescan={on|off}'
                                          'materialization={on|off}'
                                          'mrr={on|off}'
                                          'mrr_cost_based={on|off}'
                                          'semijoin={on|off}'
                                          'subquery_materialization_cost_based={on|off}'
                                          'use_index_extensions={on|off}'

     *Valid Values* (5.7.5)               'batched_key_access={on|off}'
                                          'block_nested_loop={on|off}'
                                          'condition_fanout_filter={on|off}'
                                          'engine_condition_pushdown={on|off}'
                                          'firstmatch={on|off}'
                                          'index_condition_pushdown={on|off}'
                                          'index_merge={on|off}'
                                          'index_merge_intersection={on|off}'
                                          'index_merge_sort_union={on|off}'
                                          'index_merge_union={on|off}'
                                          'loosescan={on|off}'
                                          'materialization={on|off}'
                                          'mrr={on|off}'
                                          'mrr_cost_based={on|off}'
                                          'semijoin={on|off}'
                                          'subquery_materialization_cost_based={on|off}'
                                          'use_index_extensions={on|off}'

     *Valid Values* (<= 5.7.4)            'batched_key_access={on|off}'
                                          'block_nested_loop={on|off}'
                                          'engine_condition_pushdown={on|off}'
                                          'firstmatch={on|off}'
                                          'index_condition_pushdown={on|off}'
                                          'index_merge={on|off}'
                                          'index_merge_intersection={on|off}'
                                          'index_merge_sort_union={on|off}'
                                          'index_merge_union={on|off}'
                                          'loosescan={on|off}'
                                          'materialization={on|off}'
                                          'mrr={on|off}'
                                          'mrr_cost_based={on|off}'
                                          'semijoin={on|off}'
                                          'subquery_materialization_cost_based={on|off}'
                                          'use_index_extensions={on|off}'

     The 'optimizer_switch' system variable enables control over
     optimizer behavior.  The value of this variable is a set of flags,
     each of which has a value of 'on' or 'off' to indicate whether the
     corresponding optimizer behavior is enabled or disabled.  This
     variable has global and session values and can be changed at
     runtime.  The global default can be set at server startup.

     To see the current set of optimizer flags, select the variable
     value:

          mysql> SELECT @@optimizer_switch\G
          *************************** 1. row ***************************
          @@optimizer_switch: index_merge=on,index_merge_union=on,
                              index_merge_sort_union=on,
                              index_merge_intersection=on,
                              engine_condition_pushdown=on,
                              index_condition_pushdown=on,
                              mrr=on,mrr_cost_based=on,
                              block_nested_loop=on,batched_key_access=off,
                              materialization=on,semijoin=on,loosescan=on,
                              firstmatch=on,duplicateweedout=on,
                              subquery_materialization_cost_based=on,
                              use_index_extensions=on,
                              condition_fanout_filter=on,derived_merge=on

     For more information about the syntax of this variable and the
     optimizer behaviors that it controls, see
     switchable-optimizations.

   *
     'optimizer_trace'

     Property                             Value

     *System Variable*                    'optimizer_trace'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     This variable controls optimizer tracing.  For details, see MySQL
     Internals: Tracing the Optimizer
     (http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

   *
     'optimizer_trace_features'

     Property                             Value

     *System Variable*                    'optimizer_trace_features'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     This variable enables or disables selected optimizer tracing
     features.  For details, see MySQL Internals: Tracing the Optimizer
     (http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

   *
     'optimizer_trace_limit'

     Property                             Value

     *System Variable*                    'optimizer_trace_limit'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     The maximum number of optimizer traces to display.  For details,
     see MySQL Internals: Tracing the Optimizer
     (http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

   *
     'optimizer_trace_max_mem_size'

     Property                             Value

     *System Variable*                    'optimizer_trace_max_mem_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '16384'

     The maximum cumulative size of stored optimizer traces.  For
     details, see MySQL Internals: Tracing the Optimizer
     (http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

   *
     'optimizer_trace_offset'

     Property                             Value

     *System Variable*                    'optimizer_trace_offset'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '-1'

     The offset of optimizer traces to display.  For details, see MySQL
     Internals: Tracing the Optimizer
     (http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

   * 'performance_schema_XXX'

     Performance Schema system variables are listed in
     performance-schema-system-variables.  These variables may be used
     to configure Performance Schema operation.

   *
     'parser_max_mem_size'

     Property                             Value

     *Command-Line Format*                '--parser-max-mem-size=N'

     *Introduced*                         5.7.12

     *System Variable*                    'parser_max_mem_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '18446744073709551615'

     *Default Value* (32-bit platforms)   '4294967295'

     *Minimum Value* (64-bit platforms)   '10000000'

     *Minimum Value* (32-bit platforms)   '10000000'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The maximum amount of memory available to the parser.  The default
     value places no limit on memory available.  The value can be
     reduced to protect against out-of-memory situations caused by
     parsing long or complex SQL statements.

   *
     'pid_file'

     Property                             Value

     *Command-Line Format*                '--pid-file=file_name'

     *System Variable*                    'pid_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The path name of the process ID file.  This variable can be set
     with the '--pid-file' option.  The server creates the file in the
     data directory unless an absolute path name is given to specify a
     different directory.  If you specify the '--pid-file' option, you
     must specify a value.  If you do not specify the '--pid-file'
     option, MySQL uses a default value of 'HOST_NAME.pid', where
     HOST_NAME is the name of the host machine.

     The process ID file is used by other programs such as
     'mysqld_safe' to determine the server's process ID.
     On Windows, this variable also affects the default error log file
     name.  See error-log.

   *
     'plugin_dir'

     Property                             Value

     *Command-Line Format*                '--plugin-dir=dir_name'

     *System Variable*                    'plugin_dir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     *Default Value*                      'BASEDIR/lib/plugin'

     The path name of the plugin directory.

     If the plugin directory is writable by the server, it may be
     possible for a user to write executable code to a file in the
     directory using 'SELECT ... INTO DUMPFILE'.  This can
     be prevented by making 'plugin_dir' read only to the server or by
     setting '--secure-file-priv' to a directory where 'SELECT'
     writes can be made safely.

   *
     'port'

     Property                             Value

     *Command-Line Format*                '--port=#'

     *System Variable*                    'port'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '3306'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     The number of the port on which the server listens for TCP/IP
     connections.  This variable can be set with the '--port' option.

   *
     'preload_buffer_size'

     Property                             Value

     *Command-Line Format*                '--preload-buffer-size=#'

     *System Variable*                    'preload_buffer_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '32768'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '1073741824'

     The size of the buffer that is allocated when preloading indexes.

   *
     'profiling'

     If set to 0 or 'OFF' (the default), statement profiling is
     disabled.  If set to 1 or 'ON', statement profiling is enabled and
     the 'SHOW PROFILE' and 'SHOW PROFILES'
     statements provide access to profiling information.
     See show-profiles.

     This variable is deprecated and will be removed in a future MySQL
     release.

   *
     'profiling_history_size'

     The number of statements for which to maintain profiling
     information if 'profiling' is enabled.  The default value is 15.
     The maximum value is 100.  Setting the value to 0 effectively
     disables profiling.  See show-profiles.

     This variable is deprecated and will be removed in a future MySQL
     release.

   *
     'protocol_version'

     Property                             Value

     *System Variable*                    'protocol_version'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     The version of the client/server protocol used by the MySQL server.

   *
     'proxy_user'

     Property                             Value

     *System Variable*                    'proxy_user'

     *Scope*                              Session

     *Dynamic*                            No

     *Type*                               string

     If the current client is a proxy for another user, this variable is
     the proxy user account name.  Otherwise, this variable is 'NULL'.
     See proxy-users.

   *
     'pseudo_slave_mode'

     Property                             Value

     *System Variable*                    'pseudo_slave_mode'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               integer

     This variable is for internal server use.

   *
     'pseudo_thread_id'

     Property                             Value

     *System Variable*                    'pseudo_thread_id'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               integer

     This variable is for internal server use.

   *
     'query_alloc_block_size'

     Property                             Value

     *Command-Line Format*                '--query-alloc-block-size=#'

     *System Variable*                    'query_alloc_block_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms, <=         integer
     5.7.8)

     *Type* (32-bit platforms, <=         integer
     5.7.8)

     *Type* (>= 5.7.9)                    integer

     *Default Value* (64-bit platforms,   '8192'
     <= 5.7.8)

     *Default Value* (32-bit platforms,   '8192'
     <= 5.7.8)

     *Default Value* (>= 5.7.9)           '8192'

     *Minimum Value* (64-bit platforms,   '1024'
     <= 5.7.8)

     *Minimum Value* (32-bit platforms,   '1024'
     <= 5.7.8)

     *Minimum Value* (>= 5.7.9)           '1024'

     *Maximum Value* (64-bit platforms,   '18446744073709551615'
     <= 5.7.8)

     *Maximum Value* (32-bit platforms,   '4294967295'
     <= 5.7.8)

     *Maximum Value* (>= 5.7.9)           '4294967295'

     *Block Size* (64-bit platforms, <=   '1024'
     5.7.8)

     *Block Size* (32-bit platforms, <=   '1024'
     5.7.8)

     *Block Size* (>= 5.7.9)              '1024'

     The allocation size of memory blocks that are allocated for objects
     created during statement parsing and execution.  If you have
     problems with memory fragmentation, it might help to increase this
     parameter.

   *
     'query_cache_limit'

     Property                             Value

     *Command-Line Format*                '--query-cache-limit=#'

     *Deprecated*                         5.7.20

     *System Variable*                    'query_cache_limit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1048576'

     *Default Value* (32-bit platforms)   '1048576'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     Do not cache results that are larger than this number of bytes.
     The default value is 1MB.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'query_cache_limit'.

   *
     'query_cache_min_res_unit'

     Property                             Value

     *Command-Line Format*                '--query-cache-min-res-unit=#'

     *Deprecated*                         5.7.20

     *System Variable*                    'query_cache_min_res_unit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '4096'

     *Default Value* (32-bit platforms)   '4096'

     *Minimum Value* (64-bit platforms)   '512'

     *Minimum Value* (32-bit platforms)   '512'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The minimum size (in bytes) for blocks allocated by the query
     cache.  The default value is 4096 (4KB). Tuning information for
     this variable is given in query-cache-configuration.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'query_cache_min_res_unit'.

   *
     'query_cache_size'

     Property                             Value

     *Command-Line Format*                '--query-cache-size=#'

     *Deprecated*                         5.7.20

     *System Variable*                    'query_cache_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1048576'

     *Default Value* (32-bit platforms)   '1048576'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The amount of memory allocated for caching query results.  By
     default, the query cache is disabled.  This is achieved using a
     default value of 1M, with a default for 'query_cache_type' of 0.
     (To reduce overhead significantly if you set the size to 0, you
     should also start the server with 'query_cache_type=0'.

     The permissible values are multiples of 1024; other values are
     rounded down to the nearest multiple.  For nonzero values of
     'query_cache_size', that many bytes of memory are allocated even if
     'query_cache_type=0'.  See query-cache-configuration, for
     more information.

     The query cache needs a minimum size of about 40KB to allocate its
     structures.  (The exact size depends on system architecture.)  If
     you set the value of 'query_cache_size' too small, a warning will
     occur, as described in query-cache-configuration.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'query_cache_size'.

   *
     'query_cache_type'

     Property                             Value

     *Command-Line Format*                '--query-cache-type=#'

     *Deprecated*                         5.7.20

     *System Variable*                    'query_cache_type'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      '0'

     *Valid Values*                       '0' '1' '2'

     Set the query cache type.  Setting the 'GLOBAL' value sets the type
     for all clients that connect thereafter.  Individual clients can
     set the 'SESSION' value to affect their own use of the query cache.
     Possible values are shown in the following table.

     Option      Description

     '0' or      Do not cache results in or retrieve results from
     'OFF'       the query cache.  Note that this does not
                 deallocate the query cache buffer.  To do that,
                 you should set 'query_cache_size' to 0.

     '1' or      Cache all cacheable query results except for
     'ON'        those that begin with 'SELECT SQL_NO_CACHE'.

     '2' or      Cache results only for cacheable queries that
     'DEMAND'    begin with 'SELECT SQL_CACHE'.

     This variable defaults to 'OFF'.

     If the server is started with 'query_cache_type' set to 0, it does
     not acquire the query cache mutex at all, which means that the
     query cache cannot be enabled at runtime and there is reduced
     overhead in query execution.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'query_cache_type'.

   *
     'query_cache_wlock_invalidate'

     Property                             Value

     *Command-Line Format*                '--query-cache-wlock-invalidate'

     *Deprecated*                         5.7.20

     *System Variable*                    'query_cache_wlock_invalidate'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Normally, when one client acquires a 'WRITE' lock on a 'MyISAM'
     table, other clients are not blocked from issuing statements that
     read from the table if the query results are present in the query
     cache.  Setting this variable to 1 causes acquisition of a 'WRITE'
     lock for a table to invalidate any queries in the query cache that
     refer to the table.  This forces other clients that attempt to
     access the table to wait while the lock is in effect.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'query_cache_wlock_invalidate'.

   *
     'query_prealloc_size'

     Property                             Value

     *Command-Line Format*                '--query-prealloc-size=#'

     *System Variable*                    'query_prealloc_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '8192'

     *Default Value* (32-bit platforms)   '8192'

     *Minimum Value* (64-bit platforms)   '8192'

     *Minimum Value* (32-bit platforms)   '8192'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     *Block Size* (64-bit platforms)      '1024'

     *Block Size* (32-bit platforms)      '1024'

     The size of the persistent buffer used for statement parsing and
     execution.  This buffer is not freed between statements.  If you
     are running complex queries, a larger 'query_prealloc_size' value
     might be helpful in improving performance, because it can reduce
     the need for the server to perform memory allocation during query
     execution operations.

   *
     'rand_seed1'

     The 'rand_seed1' and 'rand_seed2' variables exist as session
     variables only, and can be set but not read.  The variables--but
     not their values--are shown in the output of 'SHOW VARIABLES'.

     The purpose of these variables is to support replication of the
     'RAND()' function.  For statements that invoke 'RAND()', the master
     passes two values to the slave, where they are used to seed the
     random number generator.  The slave uses these values to set the
     session variables 'rand_seed1' and 'rand_seed2' so that 'RAND()' on
     the slave generates the same value as on the master.

   *
     'rand_seed2'

     See the description for 'rand_seed1'.

   *
     'range_alloc_block_size'

     Property                             Value

     *Command-Line Format*                '--range-alloc-block-size=#'

     *System Variable*                    'range_alloc_block_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms, >=         integer
     5.7.8)

     *Type* (64-bit platforms, <=         integer
     5.7.8)

     *Type* (32-bit platforms, <=         integer
     5.7.8)

     *Type* (>= 5.7.9)                    integer

     *Default Value* (64-bit platforms,   '4096'
     >= 5.7.8)

     *Default Value* (64-bit platforms,   '4096'
     <= 5.7.8)

     *Default Value* (32-bit platforms,   '4096'
     <= 5.7.8)

     *Default Value* (>= 5.7.9)           '4096'

     *Minimum Value* (64-bit platforms,   '4096'
     >= 5.7.8)

     *Minimum Value* (64-bit platforms,   '4096'
     <= 5.7.8)

     *Minimum Value* (32-bit platforms,   '4096'
     <= 5.7.8)

     *Minimum Value* (>= 5.7.9)           '4096'

     *Maximum Value* (64-bit platforms,   '18446744073709547520'
     >= 5.7.8)

     *Maximum Value* (64-bit platforms,   '18446744073709551615'
     <= 5.7.8)

     *Maximum Value* (32-bit platforms,   '4294967295'
     <= 5.7.8)

     *Maximum Value* (>= 5.7.9)           '4294967295'

     *Block Size* (64-bit platforms, >=   '1024'
     5.7.8)

     *Block Size* (64-bit platforms, <=   '1024'
     5.7.8)

     *Block Size* (32-bit platforms, <=   '1024'
     5.7.8)

     *Block Size* (>= 5.7.9)              '1024'

     The size of blocks that are allocated when doing range
     optimization.

   *
     'range_optimizer_max_mem_size'

     Property                             Value

     *Command-Line Format*                '--range-optimizer-max-mem-size=N'

     *Introduced*                         5.7.9

     *System Variable*                    'range_optimizer_max_mem_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value* (>= 5.7.12)          '8388608'

     *Default Value* (<= 5.7.11)          '1536000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '18446744073709551615'

     The limit on memory consumption for the range optimizer.  A value
     of 0 means 'no limit.' If an execution plan considered by the
     optimizer uses the range access method but the optimizer estimates
     that the amount of memory needed for this method would exceed the
     limit, it abandons the plan and considers other plans.  For more
     information, see range-optimization-memory-use.

   *
     'rbr_exec_mode'

     Property                             Value

     *Introduced*                         5.7.1

     *System Variable*                    'rbr_exec_mode'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'STRICT'

     *Valid Values*                       'IDEMPOTENT' 'STRICT'

     This variable switches the server between 'IDEMPOTENT' mode and
     'STRICT' mode.  'IDEMPOTENT' mode causes suppression of
     duplicate-key and no-key-found errors.  This mode is useful when
     replaying a row-based binary log on a server that causes conflicts
     with existing data.  'mysqlbinlog' uses this
     mode when you set the '--idempotent' option by writing the
     following to the output:

          SET SESSION RBR_EXEC_MODE=IDEMPOTENT;

   *
     'read_buffer_size'

     Property                             Value

     *Command-Line Format*                '--read-buffer-size=#'

     *System Variable*                    'read_buffer_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '131072'

     *Minimum Value*                      '8200'

     *Maximum Value*                      '2147479552'

     Each thread that does a sequential scan for a 'MyISAM' table
     allocates a buffer of this size (in bytes) for each table it scans.
     If you do many sequential scans, you might want to increase this
     value, which defaults to 131072.  The value of this variable should
     be a multiple of 4KB. If it is set to a value that is not a
     multiple of 4KB, its value will be rounded down to the nearest
     multiple of 4KB.

     This option is also used in the following context for all storage
     engines:

        * For caching the indexes in a temporary file (not a temporary
          table), when sorting rows for 'ORDER BY'.

        * For bulk insert into partitions.

        * For caching results of nested queries.

     and in one other storage engine-specific way: to determine the
     memory block size for 'MEMORY'.
     tables.

     The maximum permissible setting for 'read_buffer_size' is 2GB.

     For more information about memory use during different operations,
     see memory-use.

   *
     'read_only'

     Property                             Value

     *Command-Line Format*                '--read-only'

     *System Variable*                    'read_only'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     When the 'read_only' system variable is enabled, the server permits
     no client updates except from users who have the 'SUPER' privilege.
     This variable is disabled by default.

     As of MySQL 5.7.8, the server also supports a 'super_read_only'
     system variable (disabled by default), which has these effects:

        * If 'super_read_only' is enabled, the server prohibits client
          updates, even from users who have the 'SUPER' privilege.

        * Setting 'super_read_only' to 'ON' implicitly forces
          'read_only' to 'ON'.

        * Setting 'read_only' to 'OFF' implicitly forces
          'super_read_only' to 'OFF'.

     Even with 'read_only' enabled, the server permits these operations:

        * Updates performed by slave threads, if the server is a
          replication slave.  In replication setups, it can be useful to
          enable 'read_only' on slave servers to ensure that slaves
          accept updates only from the master server and not from
          clients.

        * Use of 'ANALYZE TABLE' or
          'OPTIMIZE TABLE' statements.  The purpose of
          read-only mode is to prevent changes to table structure or
          contents.  Analysis and optimization do not qualify as such
          changes.  This means, for example, that consistency checks on
          read-only replication slaves can be performed with
          'mysqlcheck --all-databases --analyze'.

        * Operations on 'TEMPORARY' tables.

        * Inserts into the log tables ('mysql.general_log' and
          'mysql.slow_log'); see log-destinations.

        * As of MySQL 5.7.16, updates to Performance Schema tables, such
          as 'UPDATE' or 'TRUNCATE TABLE'
          operations.

     Changes to 'read_only' on a master server are not replicated to
     slave servers.  The value can be set on a slave server independent
     of the setting on the master.

     The following conditions apply to attempts to enable 'read_only'
     (including implicit attempts resulting from enabling
     'super_read_only'):

        * The attempt fails and an error occurs if you have any explicit
          locks (acquired with 'LOCK TABLES') or
          have a pending transaction.

        * The attempt blocks while other clients hold explicit table
          locks or have pending transactions, until the locks are
          released and the transactions end.  While the attempt to
          enable 'read_only' is pending, requests by other clients for
          table locks or to begin transactions also block until
          'read_only' has been set.

        * The attempt blocks if there are active transactions that hold
          metadata locks, until those transactions end.

        * 'read_only' can be enabled while you hold a global read lock
          (acquired with 'FLUSH TABLES WITH READ LOCK') because that
          does not involve table locks.

   *
     'read_rnd_buffer_size'

     Property                             Value

     *Command-Line Format*                '--read-rnd-buffer-size=#'

     *System Variable*                    'read_rnd_buffer_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '262144'

     *Minimum Value*                      '1'

     *Maximum Value*                      '2147483647'

     This variable is used for reads from 'MyISAM' tables, and, for any
     storage engine, for Multi-Range Read optimization.

     When reading rows from a 'MyISAM' table in sorted order following a
     key-sorting operation, the rows are read through this buffer to
     avoid disk seeks.  See order-by-optimization.  Setting the
     variable to a large value can improve 'ORDER BY' performance by a
     lot.  However, this is a buffer allocated for each client, so you
     should not set the global variable to a large value.  Instead,
     change the session variable only from within those clients that
     need to run large queries.

     The maximum permissible setting for 'read_rnd_buffer_size' is 2GB.

     For more information about memory use during different operations,
     see memory-use.  For information about Multi-Range Read
     optimization, see mrr-optimization.

   *
     'relay_log_purge'

     Property                             Value

     *Command-Line Format*                '--relay-log-purge'

     *System Variable*                    'relay_log_purge'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Disables or enables automatic purging of relay log files as soon as
     they are not needed any more.  The default value is 1 ('ON').

   *
     'relay_log_space_limit'

     Property                             Value

     *Command-Line Format*                '--relay-log-space-limit=#'

     *System Variable*                    'relay_log_space_limit'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '0'

     *Default Value* (32-bit platforms)   '0'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The maximum amount of space to use for all relay logs.

   *
     'report_host'

     Property                             Value

     *Command-Line Format*                '--report-host=host_name'

     *System Variable*                    'report_host'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The value of the '--report-host' option.

   *
     'report_password'

     Property                             Value

     *Command-Line Format*                '--report-password=name'

     *System Variable*                    'report_password'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The value of the '--report-password' option.  Not the same as the
     password used for the MySQL replication user account.

   *
     'report_port'

     Property                             Value

     *Command-Line Format*                '--report-port=#'

     *System Variable*                    'report_port'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '[slave_port]'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     The value of the '--report-port' option.

   *
     'report_user'

     Property                             Value

     *Command-Line Format*                '--report-user=name'

     *System Variable*                    'report_user'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The value of the '--report-user' option.  Not the same as the name
     for the MySQL replication user account.

   *
     'require_secure_transport'

     Property                             Value

     *Command-Line Format*                '--require-secure-transport[={OFF|ON}]'

     *Introduced*                         5.7.8

     *System Variable*                    'require_secure_transport'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether client connections to the server are required to use some
     form of secure transport.  When this variable is enabled, the
     server permits only TCP/IP connections that use SSL, or connections
     that use a socket file (on Unix) or shared memory (on Windows).
     The server rejects nonsecure connection attempts, which fail with
     an 'ER_SECURE_TRANSPORT_REQUIRED' error.

     This capability supplements per-account SSL requirements, which
     take precedence.  For example, if an account is defined with
     'REQUIRE SSL', enabling 'require_secure_transport' does not make it
     possible to use the account to connect using a Unix socket file.

     It is possible for a server to have no secure transports available.
     For example, a server on Windows supports no secure transports if
     started without specifying any SSL certificate or key files and
     with the 'shared_memory' system variable disabled.  Under these
     conditions, attempts to enable 'require_secure_transport' at
     startup cause the server to write a message to the error log and
     exit.  Attempts to enable the variable at runtime fail with an
     'ER_NO_SECURE_TRANSPORTS_CONFIGURED' error.

   *
     'rpl_semi_sync_master_enabled'

     Property                             Value

     *System Variable*                    'rpl_semi_sync_master_enabled'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Controls whether semisynchronous replication is enabled on the
     master.  To enable or disable the plugin, set this variable to 'ON'
     or 'OFF' (or 1 or 0), respectively.  The default is 'OFF'.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'rpl_semi_sync_master_timeout'

     Property                             Value

     *System Variable*                    'rpl_semi_sync_master_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '10000'

     A value in milliseconds that controls how long the master waits on
     a commit for acknowledgment from a slave before timing out and
     reverting to asynchronous replication.  The default value is 10000
     (10 seconds).

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'rpl_semi_sync_master_trace_level'

     Property                             Value

     *System Variable*                    'rpl_semi_sync_master_trace_level'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '32'

     The semisynchronous replication debug trace level on the master.
     Four levels are defined:

        * 1 = general level (for example, time function failures)

        * 16 = detail level (more verbose information)

        * 32 = net wait level (more information about network waits)

        * 64 = function level (information about function entry and
          exit)

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'rpl_semi_sync_master_wait_for_slave_count'

     Property                             Value

     *Introduced*                         5.7.3

     *System Variable*                    'rpl_semi_sync_master_wait_for_slave_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     The number of slave acknowledgments the master must receive per
     transaction before proceeding.  By default
     'rpl_semi_sync_master_wait_for_slave_count' is '1', meaning that
     semisynchronous replication proceeds after receiving a single slave
     acknowledgment.  Performance is best for small values of this
     variable.

     For example, if 'rpl_semi_sync_master_wait_for_slave_count' is '2',
     then 2 slaves must acknowledge receipt of the transaction before
     the timeout period configured by 'rpl_semi_sync_master_timeout' for
     semisynchronous replication to proceed.  If less slaves acknowledge
     receipt of the transaction during the timeout period, the master
     reverts to normal replication.

     *Note*:

     This behavior also depends on 'rpl_semi_sync_master_wait_no_slave'

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'rpl_semi_sync_master_wait_no_slave'

     Property                             Value

     *System Variable*                    'rpl_semi_sync_master_wait_no_slave'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Controls whether the master waits for the timeout period configured
     by 'rpl_semi_sync_master_timeout' to expire, even if the slave
     count drops to less than the number of slaves configured by
     'rpl_semi_sync_master_wait_for_slave_count' during the timeout
     period.

     When the value of 'rpl_semi_sync_master_wait_no_slave' is 'ON' (the
     default), it is permissible for the slave count to drop to less
     than 'rpl_semi_sync_master_wait_for_slave_count' during the timeout
     period.  As long as enough slaves acknowledge the transaction
     before the timeout period expires, semisynchronous replication
     continues.

     When the value of 'rpl_semi_sync_master_wait_no_slave' is 'OFF', if
     the slave count drops to less than the number configured in
     'rpl_semi_sync_master_wait_for_slave_count' at any time during the
     timeout period configured by 'rpl_semi_sync_master_timeout', the
     master reverts to normal replication.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'rpl_semi_sync_master_wait_point'

     Property                             Value

     *Introduced*                         5.7.2

     *System Variable*                    'rpl_semi_sync_master_wait_point'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'AFTER_SYNC'

     *Valid Values*                       'AFTER_SYNC' 'AFTER_COMMIT'

     This variable controls the point at which a semisynchronous
     replication master waits for slave acknowledgment of transaction
     receipt before returning a status to the client that committed the
     transaction.  These values are permitted:

        * 'AFTER_SYNC' (the default): The master writes each transaction
          to its binary log and the slave, and syncs the binary log to
          disk.  The master waits for slave acknowledgment of
          transaction receipt after the sync.  Upon receiving
          acknowledgment, the master commits the transaction to the
          storage engine and returns a result to the client, which then
          can proceed.

        * 'AFTER_COMMIT': The master writes each transaction to its
          binary log and the slave, syncs the binary log, and commits
          the transaction to the storage engine.  The master waits for
          slave acknowledgment of transaction receipt after the commit.
          Upon receiving acknowledgment, the master returns a result to
          the client, which then can proceed.

     The replication characteristics of these settings differ as
     follows:

        * With 'AFTER_SYNC', all clients see the committed transaction
          at the same time: After it has been acknowledged by the slave
          and committed to the storage engine on the master.  Thus, all
          clients see the same data on the master.

          In the event of master failure, all transactions committed on
          the master have been replicated to the slave (saved to its
          relay log).  A crash of the master and failover to the slave
          is lossless because the slave is up to date.  Note, however,
          that the master cannot be restarted in this scenario and must
          be discarded, because its binary log might contain uncommitted
          transactions that would cause a conflict with the slave when
          externalized after binary log recovery.

        * With 'AFTER_COMMIT', the client issuing the transaction gets a
          return status only after the server commits to the storage
          engine and receives slave acknowledgment.  After the commit
          and before slave acknowledgment, other clients can see the
          committed transaction before the committing client.

          If something goes wrong such that the slave does not process
          the transaction, then in the event of a master crash and
          failover to the slave, it is possible that such clients will
          see a loss of data relative to what they saw on the master.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

     'rpl_semi_sync_master_wait_point' was added in MySQL 5.7.2.  For
     older versions, semisynchronous master behavior is equivalent to a
     setting of 'AFTER_COMMIT'.

     This change introduces a version compatibility constraint because
     it increments the semisynchronous interface version: Servers for
     MySQL 5.7.2 and up do not work with semisynchronous replication
     plugins from older versions, nor do servers from older versions
     work with semisynchronous replication plugins for MySQL 5.7.2 and
     up.

   *
     'rpl_semi_sync_slave_enabled'

     Property                             Value

     *System Variable*                    'rpl_semi_sync_slave_enabled'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Controls whether semisynchronous replication is enabled on the
     slave.  To enable or disable the plugin, set this variable to 'ON'
     or 'OFF' (or 1 or 0), respectively.  The default is 'OFF'.

     This variable is available only if the slave-side semisynchronous
     replication plugin is installed.

   *
     'rpl_semi_sync_slave_trace_level'

     Property                             Value

     *System Variable*                    'rpl_semi_sync_slave_trace_level'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '32'

     The semisynchronous replication debug trace level on the slave.
     See 'rpl_semi_sync_master_trace_level' for the permissible values.

     This variable is available only if the slave-side semisynchronous
     replication plugin is installed.

   *
     'secure_auth'

     Property                             Value

     *Command-Line Format*                '--secure-auth'

     *Deprecated*                         5.7.5

     *System Variable*                    'secure_auth'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     *Valid Values* (>= 5.7.5)            'ON'

     *Valid Values* (<= 5.7.4)            'OFF' 'ON'

     If this variable is enabled, the server blocks connections by
     clients that attempt to use accounts that have passwords stored in
     the old (pre-4.1) format.

     Enable this variable to prevent all use of passwords employing the
     old format (and hence insecure communication over the network).

     This variable is deprecated and will be removed in a future MySQL
     release.  It is always enabled and attempting to disable it
     produces an error.

     Server startup fails with an error if this variable is enabled and
     the privilege tables are in pre-4.1 format.  See
     account-upgrades.

     *Note*:

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method and should be
     avoided.  Pre-4.1 passwords are deprecated and support for them was
     removed in MySQL 5.7.5.  For account upgrade instructions, see
     account-upgrades.

   *
     'secure_file_priv'

     Property                             Value

     *Command-Line Format*                '--secure-file-priv=dir_name'

     *System Variable*                    'secure_file_priv'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value* (>= 5.7.6)           'platform specific'

     *Default Value* (<= 5.7.5)           'empty string'

     *Valid Values* (>= 5.7.6)            'empty string' 'dirname' 'NULL'

     *Valid Values* (<= 5.7.5)            'empty string' 'dirname'

     This variable is used to limit the effect of data import and export
     operations, such as those performed by the 'LOAD DATA'
     and 'SELECT ... INTO OUTFILE'.
     statements and the 'LOAD_FILE()' function.  These operations are
     permitted only to users who have the 'FILE' privilege.

     'secure_file_priv' may be set as follows:

        * If empty, the variable has no effect.  This is not a secure
          setting.

        * If set to the name of a directory, the server limits import
          and export operations to work only with files in that
          directory.  The directory must exist; the server will not
          create it.

        * If set to 'NULL', the server disables import and export
          operations.  This value is permitted as of MySQL 5.7.6.

     The default value is platform specific and depends on the value of
     the 'INSTALL_LAYOUT' 'CMake' option, as shown in the following
     table.  To specify the default 'secure_file_priv' value explicitly
     if you are building from source, use the
     'INSTALL_SECURE_FILE_PRIVDIR' 'CMake' option.

     'INSTALL_LAYOUT' Value    Default 'secure_file_priv' Value

     'STANDALONE', 'WIN'       'NULL' (>= MySQL 5.7.16), empty (< MySQL
                               5.7.16)

     'DEB', 'RPM', 'SLES',     '/var/lib/mysql-files'
     'SVR4'

     Otherwise                 'mysql-files' under the
                               'CMAKE_INSTALL_PREFIX' value

     As of MySQL 5.7.8, to set the default 'secure_file_priv' value for
     the 'libmysqld' embedded server, use the
     'INSTALL_SECURE_FILE_PRIV_EMBEDDEDDIR' 'CMake' option.  The default
     value for this option is 'NULL'.

     As of MySQL 5.7.6, the server checks the value of
     'secure_file_priv' at startup and writes a warning to the error log
     if the value is insecure.  A non-'NULL' value is considered
     insecure if it is empty, or the value is the data directory or a
     subdirectory of it, or a directory that is accessible by all users.
     If 'secure_file_priv' is set to a nonexistent path, the server
     writes an error message to the error log and exits.

   *
     'server_id'

     Property                             Value

     *Command-Line Format*                '--server-id=#'

     *System Variable*                    'server_id'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     The server ID, used in replication to give each master and slave a
     unique identity.  This variable is set by the '--server-id' option.
     For each server participating in replication, you should pick a
     positive integer in the range from 1 to 2^32 − 1 to act as that
     server's ID.

   *
     'session_track_gtids'

     Property                             Value

     *Command-Line Format*                '--session-track-gtids=[value]'

     *Introduced*                         5.7.6

     *System Variable*                    'session_track_gtids'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'OFF'

     *Valid Values*                       'OFF' 'OWN_GTID' 'ALL_GTIDS'

     Controls a tracker for capturing GTIDs and returning them in the OK
     packet.  Depending on the value of this option, at the end of
     executing a transaction, the GTIDs specified are captured by the
     tracker and appended to the OK packet.  The possible sets of GTIDs
     to track are:

        * 'OFF' means that no GTIDs are included in the OK packet.  This
          is the same behavior as versions of MySQL prior to 5.7.6.

        * 'OWN_GTID' configures the tracker to collect GTIDs generated
          by successfully committed read/write transactions.

        * 'ALL_GTIDS' configures the tracker to collect all of the GTIDs
          in 'gtid_executed' at the time the current transaction
          commits, regardless of whether the transaction is read/write
          or read-only.

     For information about obtaining session state-change information
     within client programs, see mysql-session-track-get-first.

   *
     'session_track_schema'

     Property                             Value

     *Command-Line Format*                '--session-track-schema=#'

     *Introduced*                         5.7.4

     *System Variable*                    'session_track_schema'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Controls whether the server tracks changes to the default schema
     (database) name within the current session and makes this
     information available to the client when changes occur.

     If notification is enabled, any setting of the default schema is
     reported, even if the new schema name is the same as the old.

     For information about obtaining session state-change information
     within client programs, see mysql-session-track-get-first.

   *
     'session_track_state_change'

     Property                             Value

     *Command-Line Format*                '--session-track-state-change=#'

     *Introduced*                         5.7.4

     *System Variable*                    'session_track_state_change'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Controls whether the server tracks changes to the state of the
     current session and notifies the client when state changes occur.
     Session state consists of these values:

        * The default schema (database)

        * Session-specific values for system variables

        * User-defined variables

        * Temporary tables

        * Prepared statements

     If the session-state tracker is enabled, any assignments to session
     state values are reported, even if the new values are the same as
     the old.

     The 'session_track_state_change' variable controls only
     notification of when changes occur, not what the changes are.  To
     receive notification for changes to the default schema name and
     session system variable values, use the 'session_track_schema' and
     'session_track_system_variables' system variables.

     For information about obtaining session state-change information
     within client programs, see mysql-session-track-get-first.

   *
     'session_track_system_variables'

     Property                             Value

     *Command-Line Format*                '--session-track-system-variables=#'

     *Introduced*                         5.7.4

     *System Variable*                    'session_track_system_variables'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'time_zone, autocommit,
                                          character_set_client,
                                          character_set_results,
                                          character_set_connection'

     Controls whether the server tracks changes to the session system
     variables and makes this information available to the client when
     changes occur.  The variable value is a comma-separated list of
     variables for which to track changes.  By default, notification is
     enabled for 'time_zone', 'autocommit', 'character_set_client',
     'character_set_results', and 'character_set_connection'.  (The
     latter three variables are those affected by 'SET NAMES')

     The special value '*' causes the server to track changes to all
     session variables.  If given, this value must be specified by
     itself without specific system variable names.

     Notification occurs for all assignments to tracked session system
     variables, even if the new values are the same as the old.

     For information about obtaining session state-change information
     within client programs, see mysql-session-track-get-first.

   *
     'sha256_password_auto_generate_rsa_keys'

     Property                             Value

     *Command-Line Format*                '--sha256-password-auto-generate-rsa-keys[={OFF|ON}]'

     *Introduced*                         5.7.5

     *System Variable*                    'sha256_password_auto_generate_rsa_keys'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     This variable is available if the server was compiled using OpenSSL
     (see ssl-libraries).  It controls whether the server
     autogenerates RSA private/public key-pair files in the data
     directory, if they do not already exist.

     At startup, the server automatically generates RSA private/public
     key-pair files in the data directory if the
     'sha256_password_auto_generate_rsa_keys' system variable is
     enabled, no RSA options are specified, and the RSA files are
     missing from the data directory.  These files enable secure
     password exchange using RSA over unencrypted connections for
     accounts authenticated by the 'sha256_password' plugin; see
     sha256-pluggable-authentication.

     For more information about RSA file autogeneration, including file
     names and characteristics, see
     creating-ssl-rsa-files-using-mysql

     The 'auto_generate_certs' system variable is related but controls
     autogeneration of SSL certificate and key files needed for secure
     connections using SSL.

   *
     'sha256_password_private_key_path'

     Property                             Value

     *Command-Line Format*                '--sha256-password-private-key-path=file_name'

     *System Variable*                    'sha256_password_private_key_path'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'private_key.pem'

     This variable is available if MySQL was compiled using OpenSSL (see
     ssl-libraries).  Its value is the path name of the RSA
     private key file for the 'sha256_password' authentication plugin.
     If the file is named as a relative path, it is interpreted relative
     to the server data directory.  The file must be in PEM format.

     *Important*:

     Because this file stores a private key, its access mode should be
     restricted so that only the MySQL server can read it.

     For information about 'sha256_password', see
     sha256-pluggable-authentication.

   *
     'sha256_password_proxy_users'

     Property                             Value

     *Command-Line Format*                '--sha256-password-proxy-users=[={OFF|ON}]'

     *Introduced*                         5.7.7

     *System Variable*                    'sha256_password_proxy_users'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This variable controls whether the 'sha256_password' built-in
     authentication plugin supports proxy users.  It has no effect
     unless the 'check_proxy_users' system variable is enabled.  For
     information about user proxying, see proxy-users.

     This variable was added in MySQL 5.7.7.  Before 5.7.7,
     'sha256_password' does not support proxy users.

   *
     'sha256_password_public_key_path'

     Property                             Value

     *Command-Line Format*                '--sha256-password-public-key-path=file_name'

     *System Variable*                    'sha256_password_public_key_path'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'public_key.pem'

     This variable is available if MySQL was compiled using OpenSSL (see
     ssl-libraries).  Its value is the path name of the RSA
     public key file for the 'sha256_password' authentication plugin.
     If the file is named as a relative path, it is interpreted relative
     to the server data directory.  The file must be in PEM format.
     Because this file stores a public key, copies can be freely
     distributed to client users.  (Clients that explicitly specify a
     public key when connecting to the server using RSA password
     encryption must use the same public key as that used by the
     server.)

     For information about 'sha256_password', including information
     about how clients specify the RSA public key, see
     sha256-pluggable-authentication.

   *
     'shared_memory'

     Property                             Value

     *Command-Line Format*                '--shared-memory[={0,1}]'

     *System Variable*                    'shared_memory'

     *Scope*                              Global

     *Dynamic*                            No

     *Platform Specific*                  Windows

     *Type*                               boolean

     *Default Value*                      'FALSE'

     (Windows only.)  Whether the server permits shared-memory
     connections.

   *
     'shared_memory_base_name'

     Property                             Value

     *Command-Line Format*                '--shared-memory-base-name=name'

     *System Variable*                    'shared_memory_base_name'

     *Scope*                              Global

     *Dynamic*                            No

     *Platform Specific*                  Windows

     *Type*                               string

     *Default Value*                      'MYSQL'

     (Windows only.)  The name of shared memory to use for shared-memory
     connections.  This is useful when running multiple MySQL instances
     on a single physical machine.  The default name is 'MYSQL'.  The
     name is case sensitive.

   *
     'show_compatibility_56'

     Property                             Value

     *Command-Line Format*                '--show-compatibility-56[={OFF|ON}]'

     *Introduced*                         5.7.6

     *Deprecated*                         5.7.6

     *System Variable*                    'show_compatibility_56'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value* (>= 5.7.8)           'OFF'

     *Default Value* (<= 5.7.7)           'ON'

     The 'INFORMATION_SCHEMA' has tables that contain system and status
     variable information (see variables-table, and
     status-table).  As of MySQL 5.7.6, the Performance Schema also
     contains system and status variable tables (see
     performance-schema-system-variable-tables, and
     performance-schema-status-variable-tables).  The Performance
     Schema tables are intended to replace the 'INFORMATION_SCHEMA'
     tables, which are deprecated as of MySQL 5.7.6 and will be removed
     in a future MySQL release.

     For advice on migrating away from the 'INFORMATION_SCHEMA' tables
     to the Performance Schema tables, see
     performance-schema-variable-table-migration.  To assist in the
     migration, you can use the 'show_compatibility_56' system variable,
     which affects whether MySQL 5.6 compatibility is enabled with
     respect to how system and status variable information is provided
     by the 'INFORMATION_SCHEMA' and Performance Schema tables, and also
     by the 'SHOW VARIABLES' and 'SHOW STATUS'
     statements.

     *Note*:

     'show_compatibility_56' is deprecated because its only purpose is
     to permit control over deprecated system and status variable
     information sources that will be removed in a future MySQL release.
     When those sources are removed, 'show_compatibility_56' will have
     no purpose and will be removed as well.

     The following discussion describes the effects of
     'show_compatibility_56':

        * sysvar_show_compatibility_56_overview

        * sysvar_show_compatibility_56_show

        * sysvar_show_compatibility_56_information_schema

        * sysvar_show_compatibility_56_performance_schema

        * sysvar_show_compatibility_56_slave_status

        * sysvar_show_compatibility_56_flush

     For better understanding, it is strongly recommended that you also
     read these sections:

        * performance-schema-system-variable-tables

        * performance-schema-status-variable-tables

        * performance-schema-status-variable-summary-tables

     *Overview of show_compatibility_56 Effects*

     The 'show_compatibility_56' system variable affects these aspects
     of server operation regarding system and status variables:

        * Information available from the 'SHOW VARIABLES'
          and 'SHOW STATUS'.
          statements

        * Information available from the 'INFORMATION_SCHEMA' tables
          that provide system and status variable information

        * Information available from the Performance Schema tables that
          provide system and status variable information

        * The effect of the 'FLUSH STATUS' statement on status variables

     This list summarizes the effects of 'show_compatibility_56', with
     additional details given later:

        * When 'show_compatibility_56' is 'ON', compatibility with MySQL
          5.6 is enabled.  Older variable information sources ('SHOW'
          statements, 'INFORMATION_SCHEMA' tables) produce the same
          output as in MySQL 5.6.

        * When 'show_compatibility_56' is 'OFF', compatibility with
          MySQL 5.6 is disabled.  Selecting from the
          'INFORMATION_SCHEMA' tables produces an error because the
          Performance Schema tables are intended to replace them.  The
          'INFORMATION_SCHEMA' tables are deprecated as of MySQL 5.7.6
          and will be removed in a future MySQL release.

          To obtain system and status variable information When
          'show_compatibility_56=OFF', use the Performance Schema tables
          or the 'SHOW' statements.

          *Note*:

          When 'show_compatibility_56=OFF', the 'SHOW VARIABLES'
          and 'SHOW STATUS'.
          statements display rows from the Performance Schema
          'global_variables',
          'session_variables',
          see
          'global_status',
          and 'session_status'
          tables.

          As of MySQL 5.7.9, those tables are world readable and
          accessible without the 'SELECT' privilege, which means that
          'SELECT' is not needed to use the 'SHOW' statements, either.
          Before MySQL 5.7.9, the 'SELECT' privilege is required to
          access those Performance Schema tables, either directly, or
          indirectly through the 'SHOW' statements.

        * Several 'Slave_XXX' status variables are available from
          'SHOW STATUS' when 'show_compatibility_56' is
          'ON'.  When 'show_compatibility_56' is 'OFF', some of those
          variables are not exposed to 'SHOW STATUS'.
          The information they provide is available in
          replication-related Performance Schema tables, as described
          later.

        * 'show_compatibility_56' has no effect on system variable
          access using '@@' notation: '@@GLOBAL.VAR_NAME',
          '@@SESSION.VAR_NAME', '@@VAR_NAME'.

        * 'show_compatibility_56' has no effect for the embedded server,
          which produces 5.6-compatible output in all cases.

     The following descriptions detail the effect of setting
     'show_compatibility_56' to 'ON' or 'OFF' in the contexts in which
     this variable applies.

     *Effect of show_compatibility_56 on SHOW Statements*

     'SHOW GLOBAL VARIABLES' statement:

        * 'ON': MySQL 5.6 output.

        * 'OFF': Output displays rows from the Performance Schema
          'global_variables'.
          table.

     See 'SHOW [SESSION | LOCAL] VARIABLES'.
     statement:

        * 'ON': MySQL 5.6 output.

        * 'OFF': Output displays rows from the Performance Schema
          'session_variables'
          table.  (In MySQL
          5.7.6 and 5.7.7, 'OFF' output does not fully reflect all
          system variable values in effect for the current session; it
          includes no rows for global variables that have no session
          counterpart.  This is corrected in MySQL 5.7.8.)

     'SHOW GLOBAL STATUS' statement:

        * 'ON': MySQL 5.6 output.

        * 'OFF': Output displays rows from the Performance Schema
          'global_status'.
          table, plus the 'Com_XXX' statement execution counters.

          'OFF' output includes no rows for session variables that have
          no global counterpart, unlike 'ON' output.

     'SHOW [SESSION | LOCAL] STATUS' statement:

        * 'ON': MySQL 5.6 output.

        * 'OFF': Output displays rows from the Performance Schema
          'session_status'.
          table, plus the 'Com_XXX' statement execution counters.  (In
          MySQL 5.7.6 and 5.7.7, 'OFF' output does not fully reflect all
          status variable values in effect for the current session; it
          includes no rows for global variables that have no session
          counterpart.  This is corrected in MySQL 5.7.8.)

     In MySQL 5.7.6 and 5.7.7, for each of the 'SHOW' statements just
     described, use of a 'WHERE' clause produces a warning when
     'show_compatibility_56=ON' and an error when
     'show_compatibility_56=OFF'.  (This applies to 'WHERE' clauses that
     are not optimized away.  For example, 'WHERE 1' is trivially true,
     is optimized away, and thus produces no warning or error.)  This
     behavior does not occur as of MySQL 5.7.8; 'WHERE' is supported as
     before 5.7.6.

     *Effect of show_compatibility_56 on INFORMATION_SCHEMA Tables*

     'INFORMATION_SCHEMA' tables (see 'GLOBAL_VARIABLES',
     see 'SESSION_VARIABLES',
     'GLOBAL_STATUS', and 'SESSION_STATUS'):

        * 'ON': MySQL 5.6 output, with a deprecation warning.

        * 'OFF': Selecting from these tables produces an error.  (Before
          5.7.9, selecting from these tables produces no output, with a
          deprecation warning.)

     *Effect of show_compatibility_56 on Performance Schema Tables*

     Performance Schema system variable tables:

        * 'OFF':

             * 'global_variables'.:
               Global system
               variables only.

             * 'session_variables'.:
               System
               variables in effect for the current session: A row for
               each session variable, and a row for each global variable
               that has no session counterpart.

             * 'variables_by_thread'.:
               Session
               system variables only, for each active session.

        * 'ON': Same output as for 'OFF'.  (Before 5.7.8, these tables
          produce no output.)

     Performance Schema status variable tables:

        * 'OFF':

             * 'global_status'.:
               Global status
               variables only.

             * 'session_status'.:
               Status
               variables in effect the current session: A row for each
               session variable, and a row for each global variable that
               has no session counterpart.

             * 'status_by_account'.
               Session status variables only, aggregated per account.

             * 'status_by_host'.:
               Session status variables only, aggregated per host name.

             * 'status_by_thread'.:
               Session
               status variables only, for each active session.

             * 'status_by_user'.:
               Session status variables only, aggregated per user name.

          The Performance Schema does not collect statistics for
          'Com_XXX' status variables in the status variable tables.  To
          obtain global and per-session statement execution counts, use
          the 'events_statements_summary_global_by_event_name'
          and
          'events_statements_summary_by_thread_by_event_name'
          tables, respectively.

        * 'ON': Same output as for 'OFF'.  (Before 5.7.9, these tables
          produce no output.)

     *Effect of show_compatibility_56 on Slave Status Variables*

     Slave status variables:

        * 'ON': Several 'Slave_XXX' status variables are available from
          'SHOW STATUS'.

        * 'OFF': Some of those slave variables are not exposed to
          'SHOW STATUS' or the Performance Schema status
          variable tables.  The information they provide is available in
          replication-related Performance Schema tables.  The following
          table shows which 'Slave_XXX' status variables become
          unavailable in 'SHOW STATUS' and their
          locations in Performance Schema replication tables.

          Status Variable               Performance Schema Location

          'Slave_heartbeat_period'
                                        'replication_connection_configuration'.
                                        table, 'HEARTBEAT_INTERVAL' column

          'Slave_last_heartbeat'        'replication_connection_status'.
                                        table, 'LAST_HEARTBEAT_TIMESTAMP' column

          'Slave_received_heartbeats'   'replication_connection_status'.
                                        table, 'COUNT_RECEIVED_HEARTBEATS' column

          'Slave_retried_transactions'  'replication_applier_status'
                                        table,
                                        'COUNT_TRANSACTIONS_RETRIES' column

          'Slave_running'               'replication_connection_status'
                                        and
                                        'replication_applier_status'
                                        tables,
                                        'SERVICE_STATE' column

     *Effect of show_compatibility_56 on FLUSH STATUS*

     'FLUSH STATUS' statement:

        * 'ON': This statement produces MySQL 5.6 behavior.  It adds the
          current thread's session status variable values to the global
          values and resets the session values to zero.  Some global
          variables may be reset to zero as well.  It also resets the
          counters for key caches (default and named) to zero and sets
          'Max_used_connections' to the current number of open
          connections.

        * 'OFF': This statement adds the session status from all active
          sessions to the global status variables, resets the status of
          all active sessions, and resets account, host, and user status
          values aggregated from disconnected sessions.

   * 'show_create_table_verbosity'

     Property                             Value

     *Command-Line Format*                '--show-create-table-verbosity'

     *Introduced*                         5.7.22

     *System Variable*                    'show_create_table_verbosity'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     'SHOW CREATE TABLE' normally does not
     show the 'ROW_FORMAT' table option if the row format is the default
     format.  Enabling this variable causes 'SHOW CREATE TABLE'
     to display 'ROW_FORMAT' regardless of whether it
     is the default format.

   *
     'show_old_temporals'

     Property                             Value

     *Command-Line Format*                '--show-old-temporals={OFF|ON}'

     *Introduced*                         5.7.6

     *Deprecated*                         5.7.6

     *System Variable*                    'show_old_temporals'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether 'SHOW CREATE TABLE' output
     includes comments to flag temporal columns found to be in pre-5.6.4
     format (see 'TIME', 'DATETIME', and
     'TIMESTAMP' columns without support for fractional
     seconds precision).  This variable is disabled by default.  If
     enabled, see 'SHOW CREATE TABLE' output looks
     like this:

          CREATE TABLE `mytbl` (
            `ts` timestamp /* 5.5 binary format */ NOT NULL DEFAULT CURRENT_TIMESTAMP,
            `dt` datetime /* 5.5 binary format */ DEFAULT NULL,
            `t` time /* 5.5 binary format */ DEFAULT NULL
          ) DEFAULT CHARSET=latin1

     Output for the 'COLUMN_TYPE' column of the
     'INFORMATION_SCHEMA.COLUMNS' table is affected
     similarly.

     This variable is deprecated and will be removed in a future MySQL
     release.

   *
     'skip_external_locking'

     Property                             Value

     *Command-Line Format*                '--skip-external-locking'

     *System Variable*                    'skip_external_locking'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     This is 'OFF' if 'mysqld' uses external locking
     (system locking), 'ON' if external locking is disabled.  This
     affects only 'MyISAM' table access.

     This variable is set by the '--external-locking' or
     '--skip-external-locking' option.  External locking is disabled by
     default.

     External locking affects only 'MyISAM'
     table access.  For more information,
     including conditions under which it can and cannot be used, see
     external-locking.

   *
     'skip_name_resolve'

     Property                             Value

     *Command-Line Format*                '--skip-name-resolve'

     *System Variable*                    'skip_name_resolve'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     This variable is set from the value of the '--skip-name-resolve'
     option.  If it is 'OFF', see 'mysqld' resolves host
     names when checking client connections.  If it is 'ON', see
     'mysqld' uses only IP numbers; in this case, all 'Host'
     column values in the grant tables must be IP addresses or
     'localhost'.  See host-cache.

   *
     'skip_networking'

     Property                             Value

     *Command-Line Format*                '--skip-networking'

     *System Variable*                    'skip_networking'

     *Scope*                              Global

     *Dynamic*                            No

     This is 'ON' if the server permits only local (non-TCP/IP)
     connections.  On Unix, local connections use a Unix socket file.
     On Windows, local connections use a named pipe or shared memory.
     This variable can be set to 'ON' with the '--skip-networking'
     option.

   *
     'skip_show_database'

     Property                             Value

     *Command-Line Format*                '--skip-show-database'

     *System Variable*                    'skip_show_database'

     *Scope*                              Global

     *Dynamic*                            No

     This prevents people from using the 'SHOW DATABASES'
     statement if they do not have the 'SHOW DATABASES'
     privilege.  This can improve security if you have concerns about
     users being able to see databases belonging to other users.  Its
     effect depends on the 'SHOW DATABASES' privilege: If the variable
     value is 'ON', the 'SHOW DATABASES'.
     statement is permitted only to users who have the 'SHOW DATABASES'
     privilege, and the statement displays all database names.  If the
     value is 'OFF', see 'SHOW DATABASES' is
     permitted to all users, but displays the names of only those
     databases for which the user has the 'SHOW DATABASES' or other
     privilege.  (Note that _any_ global privilege is considered a
     privilege for the database.)

   *
     'slow_launch_time'

     Property                             Value

     *Command-Line Format*                '--slow-launch-time=#'

     *System Variable*                    'slow_launch_time'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '2'

     If creating a thread takes longer than this many seconds, the
     server increments the 'Slow_launch_threads' status variable.

   *
     'slow_query_log'

     Property                             Value

     *Command-Line Format*                '--slow-query-log'

     *System Variable*                    'slow_query_log'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether the slow query log is enabled.  The value can be 0 (or
     'OFF') to disable the log or 1 (or 'ON') to enable the log.  The
     default value depends on whether the '--slow_query_log' option is
     given.  The destination for log output is controlled by the
     'log_output' system variable; if that value is 'NONE', no log
     entries are written even if the log is enabled.

     'Slow' is determined by the value of the 'long_query_time'
     variable.  See slow-query-log.

   *
     'slow_query_log_file'

     Property                             Value

     *Command-Line Format*                '--slow-query-log-file=file_name'

     *System Variable*                    'slow_query_log_file'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               file name

     *Default Value*                      'host_name-slow.log'

     The name of the slow query log file.  The default value is
     'HOST_NAME-slow.log', but the initial value can be changed with the
     '--slow_query_log_file' option.

   *
     'socket'

     Property                             Value

     *Command-Line Format*                '--socket={file_name|pipe_name}'

     *System Variable*                    'socket'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (Other)                       string

     *Type* (Windows)                     string

     *Default Value* (Other)              '/tmp/mysql.sock'

     *Default Value* (Windows)            'MySQL'

     On Unix platforms, this variable is the name of the socket file
     that is used for local client connections.  The default is
     '/tmp/mysql.sock'.  (For some distribution formats, the directory
     might be different, such as '/var/lib/mysql' for RPMs.)

     On Windows, this variable is the name of the named pipe that is
     used for local client connections.  The default value is 'MySQL'
     (not case-sensitive).

   *
     'sort_buffer_size'

     Property                             Value

     *Command-Line Format*                '--sort-buffer-size=#'

     *System Variable*                    'sort_buffer_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (Other, 64-bit platforms)     integer

     *Type* (Other, 32-bit platforms)     integer

     *Type* (Windows)                     integer

     *Default Value* (Other, 64-bit       '262144'
     platforms)

     *Default Value* (Other, 32-bit       '262144'
     platforms)

     *Default Value* (Windows)            '262144'

     *Minimum Value* (Other, 64-bit       '32768'
     platforms)

     *Minimum Value* (Other, 32-bit       '32768'
     platforms)

     *Minimum Value* (Windows)            '32768'

     *Maximum Value* (Other, 64-bit       '18446744073709551615'
     platforms)

     *Maximum Value* (Other, 32-bit       '4294967295'
     platforms)

     *Maximum Value* (Windows)            '4294967295'

     Each session that must perform a sort allocates a buffer of this
     size.  'sort_buffer_size' is not specific to any storage engine and
     applies in a general manner for optimization.  At minimum the
     'sort_buffer_size' value must be large enough to accommodate
     fifteen tuples in the sort buffer.  Also, increasing the value of
     'max_sort_length' may require increasing the value of
     'sort_buffer_size'.  For more information, see
     order-by-optimization

     If you see many 'Sort_merge_passes' per second in 'SHOW GLOBAL STATUS'
     output, you can consider increasing
     the 'sort_buffer_size' value to speed up 'ORDER BY' or 'GROUP BY'
     operations that cannot be improved with query optimization or
     improved indexing.

     The optimizer tries to work out how much space is needed but can
     allocate more, up to the limit.  Setting it larger than required
     globally will slow down most queries that sort.  It is best to
     increase it as a session setting, and only for the sessions that
     need a larger size.  On Linux, there are thresholds of 256KB and
     2MB where larger values may significantly slow down memory
     allocation, so you should consider staying below one of those
     values.  Experiment to find the best value for your workload.  See
     temporary-files.

     The maximum permissible setting for 'sort_buffer_size' is 4GB−1.
     Larger values are permitted for 64-bit platforms (except 64-bit
     Windows, for which large values are truncated to 4GB−1 with a
     warning).

   *
     'sql_auto_is_null'

     Property                             Value

     *System Variable*                    'sql_auto_is_null'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '0'

     If this variable is set to 1, then after a statement that
     successfully inserts an automatically generated 'AUTO_INCREMENT'
     value, you can find that value by issuing a statement of the
     following form:

          SELECT * FROM TBL_NAME WHERE AUTO_COL IS NULL

     If the statement returns a row, the value returned is the same as
     if you invoked the 'LAST_INSERT_ID()' function.  For details,
     including the return value after a multiple-row insert, see
     information-functions.  If no 'AUTO_INCREMENT' value was
     successfully inserted, the 'SELECT' statement
     returns no row.

     The behavior of retrieving an 'AUTO_INCREMENT' value by using an
     'IS NULL' comparison is used by some ODBC programs, such as Access.
     See Obtaining Auto-Increment Values
     (http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-usagenotes-functionality-last-insert-id.html).
     This behavior can be disabled by setting 'sql_auto_is_null' to 0.

     The default value of 'sql_auto_is_null' is 0.

   *
     'sql_big_selects'

     Property                             Value

     *System Variable*                    'sql_big_selects'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '1'

     If set to 0, MySQL aborts 'SELECT' statements that
     are likely to take a very long time to execute (that is, statements
     for which the optimizer estimates that the number of examined rows
     exceeds the value of 'max_join_size').  This is useful when an
     inadvisable 'WHERE' statement has been issued.  The default value
     for a new connection is 1, which permits all 'SELECT'
     statements.

     If you set the 'max_join_size' system variable to a value other
     than 'DEFAULT', 'sql_big_selects' is set to 0.

   *
     'sql_buffer_result'

     Property                             Value

     *System Variable*                    'sql_buffer_result'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '0'

     If set to 1, 'sql_buffer_result' forces results from
     'SELECT' statements to be put into temporary tables.  This
     helps MySQL free the table locks early and can be beneficial in
     cases where it takes a long time to send results to the client.
     The default value is 0.

   *
     'sql_log_bin'

     Property                             Value

     *System Variable*                    'sql_log_bin'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               boolean

     This variable controls whether logging to the binary log is done.
     The default value is 1 (do logging).  To change logging for the
     current session, change the session value of this variable.  The
     session user must have the 'SUPER' privilege to set this variable.

     It is not possible to set '@@session.sql_log_bin' within a
     transaction or subquery.

     _Setting this variable to 0 prevents GTIDs from being assigned to
     transactions in the binary log_.  If you are using GTIDs for
     replication, this means that, even when binary logging is later
     enabled once again, the GTIDs written into the log from this point
     do not account for any transactions that occurred in the
     meantime--in effect, those transactions are lost.

     The global 'sql_log_bin' variable is read only and cannot be
     modified.  The global scope is deprecated and will be removed in a
     future MySQL release.

   *
     'sql_log_off'

     Property                             Value

     *System Variable*                    'sql_log_off'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '0'

     This variable controls whether logging to the general query log is
     done.  The default value is 0 (do logging).  To change logging for
     the current session, change the session value of this variable.
     The session user must have the 'SUPER' privilege to set this
     option.  The default value is 0.

   *
     'sql_mode'

     Property                             Value

     *Command-Line Format*                '--sql-mode=name'

     *System Variable*                    'sql_mode'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               set

     *Default Value* (>= 5.7.8)           'ONLY_FULL_GROUP_BY
                                          STRICT_TRANS_TABLES
                                          NO_ZERO_IN_DATE NO_ZERO_DATE
                                          ERROR_FOR_DIVISION_BY_ZERO
                                          NO_AUTO_CREATE_USER
                                          NO_ENGINE_SUBSTITUTION'

     *Default Value* (5.7.7)              'ONLY_FULL_GROUP_BY
                                          STRICT_TRANS_TABLES
                                          NO_AUTO_CREATE_USER
                                          NO_ENGINE_SUBSTITUTION'

     *Default Value* (>= 5.7.5, <=        'ONLY_FULL_GROUP_BY
     5.7.6)                               STRICT_TRANS_TABLES
                                          NO_ENGINE_SUBSTITUTION'

     *Default Value* (<= 5.7.4)           'NO_ENGINE_SUBSTITUTION'

     *Valid Values*                       'ALLOW_INVALID_DATES'
                                          'ANSI_QUOTES'
                                          'ERROR_FOR_DIVISION_BY_ZERO'
                                          'HIGH_NOT_PRECEDENCE'
                                          'IGNORE_SPACE'
                                          'NO_AUTO_CREATE_USER'
                                          'NO_AUTO_VALUE_ON_ZERO'
                                          'NO_BACKSLASH_ESCAPES'
                                          'NO_DIR_IN_CREATE'
                                          'NO_ENGINE_SUBSTITUTION'
                                          'NO_FIELD_OPTIONS'
                                          'NO_KEY_OPTIONS'
                                          'NO_TABLE_OPTIONS'
                                          'NO_UNSIGNED_SUBTRACTION'
                                          'NO_ZERO_DATE' 'NO_ZERO_IN_DATE'
                                          'ONLY_FULL_GROUP_BY'
                                          'PAD_CHAR_TO_FULL_LENGTH'
                                          'PIPES_AS_CONCAT' 'REAL_AS_FLOAT'
                                          'STRICT_ALL_TABLES'
                                          'STRICT_TRANS_TABLES'

     The current server SQL mode, which can be set dynamically.  For
     details, see sql-mode.

     *Note*:

     MySQL installation programs may configure the SQL mode during the
     installation process.  For example, see 'mysql_install_db'
     creates a default option file named 'my.cnf' in
     the base installation directory.  This file contains a line that
     sets the SQL mode; see mysql-install-db.

     If the SQL mode differs from the default or from what you expect,
     check for a setting in an option file that the server reads at
     startup.

   *
     'sql_notes'

     If set to 1 (the default), warnings of 'Note' level increment
     'warning_count' and the server records them.  If set to 0, 'Note'
     warnings do not increment 'warning_count' and the server does not
     record them.  'mysqldump' includes output to set
     this variable to 0 so that reloading the dump file does not produce
     warnings for events that do not affect the integrity of the reload
     operation.

   *
     'sql_quote_show_create'

     If set to 1 (the default), the server quotes identifiers for
     'SHOW CREATE TABLE' and 'SHOW CREATE DATABASE'
     statements.  If set to 0, quoting
     is disabled.  This option is enabled by default so that replication
     works for identifiers that require quoting.  See
     show-create-table, and show-create-database.

   *
     'sql_safe_updates'

     If set to 1, MySQL aborts 'UPDATE' or
     'DELETE' statements that do not use a key in the 'WHERE'
     clause or a 'LIMIT' clause.  (Specifically, see 'UPDATE'.
     statements must have a 'WHERE' clause that uses a key or a 'LIMIT'
     clause, or both.  'DELETE' statements must have
     both.)  This makes it possible to catch 'UPDATE' or
     'DELETE' statements where keys are not used properly
     and that would probably change or delete a large number of rows.
     The default value is 0.

   *
     'sql_select_limit'

     Property                             Value

     *System Variable*                    'sql_select_limit'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     The maximum number of rows to return from 'SELECT'.
     statements.  The default value for a new connection is the maximum
     number of rows that the server permits per table.  Typical default
     values are (2^32)−1 or (2^64)−1.  If you have changed the
     limit, the default value can be restored by assigning a value of
     'DEFAULT'.

     If a 'SELECT' has a 'LIMIT' clause, the 'LIMIT'
     takes precedence over the value of 'sql_select_limit'.

   *
     'sql_warnings'

     This variable controls whether single-row 'INSERT'.
     statements produce an information string if warnings occur.  The
     default is 0.  Set the value to 1 to produce an information string.

   *
     'ssl_ca'

     Property                             Value

     *Command-Line Format*                '--ssl-ca=file_name'

     *System Variable*                    'ssl_ca'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The path to a file with a list of trusted SSL Certificate
     Authorities.

   *
     'ssl_capath'

     Property                             Value

     *Command-Line Format*                '--ssl-capath=dir_name'

     *System Variable*                    'ssl_capath'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The path to a directory that contains trusted SSL CA certificates
     in PEM format.

   *
     'ssl_cert'

     Property                             Value

     *Command-Line Format*                '--ssl-cert=file_name'

     *System Variable*                    'ssl_cert'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The name of the SSL certificate file to use for establishing a
     secure connection.

   *
     'ssl_cipher'

     Property                             Value

     *Command-Line Format*                '--ssl-cipher=name'

     *System Variable*                    'ssl_cipher'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The list of permitted ciphers for SSL encryption.

   *
     'ssl_crl'

     Property                             Value

     *Command-Line Format*                '--ssl-crl=file_name'

     *System Variable*                    'ssl_crl'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The path to a file containing certificate revocation lists in PEM
     format.  Revocation lists work for MySQL distributions compiled
     using OpenSSL (but not yaSSL). See ssl-libraries.

   *
     'ssl_crlpath'

     Property                             Value

     *Command-Line Format*                '--ssl-crlpath=dir_name'

     *System Variable*                    'ssl_crlpath'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The path to a directory that contains files containing certificate
     revocation lists in PEM format.  Revocation lists work for MySQL
     distributions compiled using OpenSSL (but not yaSSL). See
     ssl-libraries.

   *
     'ssl_key'

     Property                             Value

     *Command-Line Format*                '--ssl-key=file_name'

     *System Variable*                    'ssl_key'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The name of the SSL key file to use for establishing a secure
     connection.

   *
     'storage_engine'

     Property                             Value

     *Removed*                            5.7.5

     *System Variable*                    'storage_engine'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'InnoDB'

     This variable is deprecated and was removed in MySQL 5.7.5.  Use
     'default_storage_engine' instead.

   *
     'stored_program_cache'

     Property                             Value

     *Command-Line Format*                '--stored-program-cache=#'

     *System Variable*                    'stored_program_cache'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '256'

     *Minimum Value* (>= 5.7.6)           '16'

     *Minimum Value* (<= 5.7.5)           '256'

     *Maximum Value*                      '524288'

     Sets a soft upper limit for the number of cached stored routines
     per connection.  The value of this variable is specified in terms
     of the number of stored routines held in each of the two caches
     maintained by the MySQL Server for, respectively, stored procedures
     and stored functions.

     Whenever a stored routine is executed this cache size is checked
     before the first or top-level statement in the routine is parsed;
     if the number of routines of the same type (stored procedures or
     stored functions according to which is being executed) exceeds the
     limit specified by this variable, the corresponding cache is
     flushed and memory previously allocated for cached objects is
     freed.  This allows the cache to be flushed safely, even when there
     are dependencies between stored routines.

   *
     'super_read_only'

     Property                             Value

     *Command-Line Format*                '--super-read-only[={OFF|ON}]'

     *Introduced*                         5.7.8

     *System Variable*                    'super_read_only'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     If the 'read_only' system variable is enabled, the server permits
     client updates only from users who have the 'SUPER' privilege.  If
     the 'super_read_only' system variable is also enabled, the server
     prohibits client updates even from users who have 'SUPER'.  See the
     description of the 'read_only' system variable for a description of
     read-only mode and information about how 'read_only' and
     'super_read_only' interact.

     Changes to 'super_read_only' on a master server are not replicated
     to slave servers.  The value can be set on a slave server
     independent of the setting on the master.

   *
     'sync_frm'

     Property                             Value

     *Command-Line Format*                '--sync-frm'

     *Deprecated*                         5.7.6

     *System Variable*                    'sync_frm'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'TRUE'

     If this variable is set to 1, when any nontemporary table is
     created its '.frm' file is synchronized to disk (using
     'fdatasync()').  This is slower but safer in case of a crash.  The
     default is 1.

     This variable is deprecated in MySQL 5.7.6 and will be removed in a
     future version of MySQL (when '.frm' files become obsolete).

   *
     'system_time_zone'

     Property                             Value

     *System Variable*                    'system_time_zone'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The server system time zone.  When the server begins executing, it
     inherits a time zone setting from the machine defaults, possibly
     modified by the environment of the account used for running the
     server or the startup script.  The value is used to set
     'system_time_zone'.  Typically the time zone is specified by the
     'TZ' environment variable.  It also can be specified using the
     '--timezone' option of the 'mysqld_safe'.
     script.

     The 'system_time_zone' variable differs from 'time_zone'.  Although
     they might have the same value, the latter variable is used to
     initialize the time zone for each client that connects.  See
     time-zone-support.

   *
     'table_definition_cache'

     Property                             Value

     *System Variable*                    'table_definition_cache'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     *Minimum Value*                      '400'

     *Maximum Value*                      '524288'

     The number of table definitions (from '.frm' files) that can be
     stored in the definition cache.  If you use a large number of
     tables, you can create a large table definition cache to speed up
     opening of tables.  The table definition cache takes less space and
     does not use file descriptors, unlike the normal table cache.  The
     minimum value is 400.  The default value is based on the following
     formula, capped to a limit of 2000:

          400 + (table_open_cache / 2)

     For 'InnoDB', 'table_definition_cache'
     acts as a soft limit for the number of open table instances in the
     'InnoDB' data dictionary cache.  If the number of open table
     instances exceeds the 'table_definition_cache' setting, the LRU
     mechanism begins to mark table instances for eviction and
     eventually removes them from the data dictionary cache.  The limit
     helps address situations in which significant amounts of memory
     would be used to cache rarely used table instances until the next
     server restart.  The number of table instances with cached metadata
     could be higher than the limit defined by 'table_definition_cache',
     because 'InnoDB' system table instances and parent and child table
     instances with foreign key relationships are not placed on the LRU
     list and are not subject to eviction from memory.

     Additionally, 'table_definition_cache' defines a soft limit for the
     number of 'InnoDB' file-per-table
     tablespaces that can be open at one time, which is also controlled
     by 'innodb_open_files'.  If both 'table_definition_cache' and
     'innodb_open_files' are set, the highest setting is used.  If
     neither variable is set, 'table_definition_cache', which has a
     higher default value, is used.  If the number of open tablespace
     file handles exceeds the limit defined by 'table_definition_cache'
     or 'innodb_open_files', the LRU mechanism searches the tablespace
     file LRU list for files that are fully flushed and are not
     currently being extended.  This process is performed each time a
     new tablespace is opened.  If there are no 'inactive' tablespaces,
     no tablespace files are closed.

   *
     'table_open_cache'

     Property                             Value

     *System Variable*                    'table_open_cache'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '2000'

     *Minimum Value*                      '1'

     *Maximum Value*                      '524288'

     The number of open tables for all threads.  Increasing this value
     increases the number of file descriptors that 'mysqld'
     requires.  You can check whether you need to increase the
     table cache by checking the 'Opened_tables' status variable.  See
     server-status-variables.  If the value of 'Opened_tables'
     is large and you do not use 'FLUSH TABLES' often (which just forces
     all tables to be closed and reopened), then you should increase the
     value of the 'table_open_cache' variable.  For more information
     about the table cache, see table-cache.

   *
     'table_open_cache_instances'

     Property                             Value

     *System Variable*                    'table_open_cache_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.8)           '16'

     *Default Value* (<= 5.7.7)           '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '64'

     The number of open tables cache instances.  To improve scalability
     by reducing contention among sessions, the open tables cache can be
     partitioned into several smaller cache instances of size
     'table_open_cache' / 'table_open_cache_instances' .  A session
     needs to lock only one instance to access it for DML statements.
     This segments cache access among instances, permitting higher
     performance for operations that use the cache when there are many
     sessions accessing tables.  (DDL statements still require a lock on
     the entire cache, but such statements are much less frequent than
     DML statements.)

     A value of 8 or 16 is recommended on systems that routinely use 16
     or more cores.

   *
     'thread_cache_size'

     Property                             Value

     *Command-Line Format*                '--thread-cache-size=#'

     *System Variable*                    'thread_cache_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     *Minimum Value*                      '0'

     *Maximum Value*                      '16384'

     How many threads the server should cache for reuse.  When a client
     disconnects, the client's threads are put in the cache if there are
     fewer than 'thread_cache_size' threads there.  Requests for threads
     are satisfied by reusing threads taken from the cache if possible,
     and only when the cache is empty is a new thread created.  This
     variable can be increased to improve performance if you have a lot
     of new connections.  Normally, this does not provide a notable
     performance improvement if you have a good thread implementation.
     However, if your server sees hundreds of connections per second you
     should normally set 'thread_cache_size' high enough so that most
     new connections use cached threads.  By examining the difference
     between the 'Connections' and 'Threads_created' status variables,
     you can see how efficient the thread cache is.  For details, see
     server-status-variables.

     The default value is based on the following formula, capped to a
     limit of 100:

          8 + (max_connections / 100)

     This variable has no effect for the embedded server ('libmysqld')
     and as of MySQL 5.7.2 is no longer visible within the embedded
     server.

   *
     'thread_concurrency'

     Property                             Value

     *Command-Line Format*                '--thread-concurrency=#'

     *Deprecated*                         Yes (removed in 5.7.2)

     *System Variable*                    'thread_concurrency'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '10'

     *Minimum Value*                      '1'

     *Maximum Value*                      '512'

     This variable is specific to Solaris 8 and earlier systems, for
     which 'mysqld' invokes the 'thr_setconcurrency()'
     function with the variable value.  This function enables
     applications to give the threads system a hint about the desired
     number of threads that should be run at the same time.  Current
     Solaris versions document this as having no effect.

     This variable was removed in MySQL 5.7.2.

   *
     'thread_handling'

     Property                             Value

     *Command-Line Format*                '--thread-handling=name'

     *System Variable*                    'thread_handling'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               enumeration

     *Default Value*                      'one-thread-per-connection'

     *Valid Values* (>= 5.7.9)            'no-threads'
                                          'one-thread-per-connection'
                                          'loaded-dynamically'

     *Valid Values* (<= 5.7.8)            'no-threads'
                                          'one-thread-per-connection'

     The thread-handling model used by the server for connection
     threads.  The permissible values are 'no-threads' (the server uses
     a single thread to handle one connection) and
     'one-thread-per-connection' (the server uses one thread to handle
     each client connection).  'no-threads' is useful for debugging
     under Linux; see porting.

     This variable has no effect for the embedded server ('libmysqld')
     and as of MySQL 5.7.2 is no longer visible within the embedded
     server.

   *
     'thread_pool_algorithm'

     Property                             Value

     *Command-Line Format*                '--thread-pool-algorithm=#'

     *Introduced*                         5.7.9

     *System Variable*                    'thread_pool_algorithm'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1'

     This variable controls which algorithm the thread pool plugin uses:

        * A value of 0 (the default) uses a conservative low-concurrency
          algorithm which is most well tested and is known to produce
          very good results.

        * A value of 1 increases the concurrency and uses a more
          aggressive algorithm which at times has been known to perform
          5-10% better on optimal thread counts, but has degrading
          performance as the number of connections increases.  Its use
          should be considered as experimental and not supported.

     This variable is available only if the thread pool plugin is
     enabled.  See thread-pool

   *
     'thread_pool_high_priority_connection'

     Property                             Value

     *Command-Line Format*                '--thread-pool-high-priority-connection=#'

     *Introduced*                         5.7.9

     *System Variable*                    'thread_pool_high_priority_connection'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1'

     This variable affects queuing of new statements prior to execution.
     If the value is 0 (false, the default), statement queuing uses both
     the low-priority and high-priority queues.  If the value is 1
     (true), queued statements always go to the high-priority queue.

     This variable is available only if the thread pool plugin is
     enabled.  See thread-pool

   *
     'thread_pool_max_unused_threads'

     Property                             Value

     *Command-Line Format*                '--thread-pool-max-unused-threads=#'

     *Introduced*                         5.7.9

     *System Variable*                    'thread_pool_max_unused_threads'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4096'

     The maximum permitted number of unused threads in the thread pool.
     This variable makes it possible to limit the amount of memory used
     by sleeping threads.

     A value of 0 (the default) means no limit on the number of sleeping
     threads.  A value of N where N is greater than 0 means 1 consumer
     thread and N−1 reserve threads.  In this case, if a thread is
     ready to sleep but the number of sleeping threads is already at the
     maximum, the thread exits rather than going to sleep.

     A sleeping thread is either sleeping as a consumer thread or a
     reserve thread.  The thread pool permits one thread to be the
     consumer thread when sleeping.  If a thread goes to sleep and there
     is no existing consumer thread, it will sleep as a consumer thread.
     When a thread must be woken up, a consumer thread is selected if
     there is one.  A reserve thread is selected only when there is no
     consumer thread to wake up.

     This variable is available only if the thread pool plugin is
     enabled.  See thread-pool

   *
     'thread_pool_prio_kickup_timer'

     Property                             Value

     *Command-Line Format*                '--thread-pool-prio-kickup-timer=#'

     *Introduced*                         5.7.9

     *System Variable*                    'thread_pool_prio_kickup_timer'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967294'

     This variable affects statements waiting for execution in the
     low-priority queue.  The value is the number of milliseconds before
     a waiting statement is moved to the high-priority queue.  The
     default is 1000 (1 second).  The range of values is 0 to 2^32 −
     2.

     This variable is available only if the thread pool plugin is
     enabled.  See thread-pool

   *
     'thread_pool_size'

     Property                             Value

     *Command-Line Format*                '--thread-pool-size=#'

     *Introduced*                         5.7.9

     *System Variable*                    'thread_pool_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '16'

     *Minimum Value*                      '1'

     *Maximum Value*                      '64'

     The number of thread groups in the thread pool.  This is the most
     important parameter controlling thread pool performance.  It
     affects how many statements can execute simultaneously.  The
     default value is 16, with a range from 1 to 64 of permissible
     values.  If a value outside this range is specified, the thread
     pool plugin does not load and the server writes a message to the
     error log.

     This variable is available only if the thread pool plugin is
     enabled.  See thread-pool

   *
     'thread_pool_stall_limit'

     Property                             Value

     *Command-Line Format*                '--thread-pool-stall-limit=#'

     *Introduced*                         5.7.9

     *System Variable*                    'thread_pool_stall_limit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '6'

     *Minimum Value*                      '4'

     *Maximum Value*                      '600'

     This variable affects executing statements.  The value is the
     amount of time a statement has to finish after starting to execute
     before it becomes defined as stalled, at which point the thread
     pool permits the thread group to begin executing another statement.
     The value is measured in 10 millisecond units, so a value of 6 (the
     default) means 60ms.  The range of values is 4 to 600 (40ms to 6s).
     Short wait values permit threads to start more quickly.  Short
     values are also better for avoiding deadlock situations.  Long wait
     values are useful for workloads that include long-running
     statements, to avoid starting too many new statements while the
     current ones execute.

     This variable is available only if the thread pool plugin is
     enabled.  See thread-pool

   *
     'thread_stack'

     Property                             Value

     *Command-Line Format*                '--thread-stack=#'

     *System Variable*                    'thread_stack'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '262144'

     *Default Value* (32-bit platforms)   '196608'

     *Minimum Value* (64-bit platforms)   '131072'

     *Minimum Value* (32-bit platforms)   '131072'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     *Block Size* (64-bit platforms)      '1024'

     *Block Size* (32-bit platforms)      '1024'

     The stack size for each thread.  The default of 192KB (256KB for
     64-bit systems) is large enough for normal operation.  If the
     thread stack size is too small, it limits the complexity of the SQL
     statements that the server can handle, the recursion depth of
     stored procedures, and other memory-consuming actions.

   *
     'time_format'

     This variable is unused.  It is deprecated and is removed in MySQL
     8.0.

   *
     'time_zone'

     Property                             Value

     *System Variable*                    'time_zone'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     The current time zone.  This variable is used to initialize the
     time zone for each client that connects.  By default, the initial
     value of this is ''SYSTEM'' (which means, 'use the value of
     'system_time_zone'').  The value can be specified explicitly at
     server startup with the '--default-time-zone' option.  See
     time-zone-support.

     *Note*:

     If set to 'SYSTEM', every MySQL function call that requires a
     timezone calculation makes a system library call to determine the
     current system timezone.  This call may be protected by a global
     mutex, resulting in contention.

   *
     'timed_mutexes'

     Property                             Value

     *Command-Line Format*                '--timed-mutexes'

     *Deprecated*                         Yes (removed in 5.7.5)

     *System Variable*                    'timed_mutexes'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This deprecated variable has no use and was removed in MySQL 5.7.5.

   *
     'timestamp'

     Property                             Value

     *System Variable*                    'timestamp'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               numeric

     Set the time for this client.  This is used to get the original
     timestamp if you use the binary log to restore rows.
     TIMESTAMP_VALUE should be a Unix epoch timestamp (a value like that
     returned by 'UNIX_TIMESTAMP()', not a value in ''YYYY-MM-DD
     hh:mm:ss'' format) or 'DEFAULT'.

     Setting 'timestamp' to a constant value causes it to retain that
     value until it is changed again.  Setting 'timestamp' to 'DEFAULT'
     causes its value to be the current date and time as of the time it
     is accessed.

     In MySQL 5.7, 'timestamp' is a 'DOUBLE' rather than 'BIGINT'
     because its value includes a microseconds part.

     'SET timestamp' affects the value returned by 'NOW()' but not by
     'SYSDATE()'.  This means that timestamp settings in the binary log
     have no effect on invocations of 'SYSDATE()'.  The server can be
     started with the '--sysdate-is-now' option to cause 'SYSDATE()' to
     be an alias for 'NOW()', in which case 'SET timestamp' affects both
     functions.

   *
     'tls_version'

     Property                             Value

     *Command-Line Format*                '--tls-version=protocol_list'

     *Introduced*                         5.7.10

     *System Variable*                    'tls_version'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'TLSv1,TLSv1.1,TLSv1.2' (OpenSSL)
                                          'TLSv1,TLSv1.1' (yaSSL)

     The protocols permitted by the server for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this variable depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

   *
     'tmp_table_size'

     Property                             Value

     *Command-Line Format*                '--tmp-table-size=#'

     *System Variable*                    'tmp_table_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '16777216'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '18446744073709551615'

     The maximum size of internal in-memory temporary tables.  This
     variable does not apply to user-created 'MEMORY' tables.

     The actual limit is determined from whichever of the values of
     'tmp_table_size' and 'max_heap_table_size' is smaller.  If an
     in-memory temporary table exceeds the limit, MySQL automatically
     converts it to an on-disk temporary table.  As of MySQL 5.7.5, the
     'internal_tmp_disk_storage_engine' option defines the storage
     engine used for on-disk temporary tables.  Prior to MySQL 5.7.5,
     the 'MyISAM' storage engine is used.

     Increase the value of 'tmp_table_size' (and 'max_heap_table_size'
     if necessary) if you do many advanced 'GROUP BY' queries and you
     have lots of memory.

     You can compare the number of internal on-disk temporary tables
     created to the total number of internal temporary tables created by
     comparing the values of the 'Created_tmp_disk_tables' and
     'Created_tmp_tables' variables.

     See also internal-temporary-tables.

   *
     'tmpdir'

     Property                             Value

     *Command-Line Format*                '--tmpdir=dir_name'

     *System Variable*                    'tmpdir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The directory used for temporary files and temporary tables.  This
     variable can be set to a list of several paths that are used in
     round-robin fashion.  Paths should be separated by colon characters
     (':') on Unix and semicolon characters (';') on Windows.

     The multiple-directory feature can be used to spread the load
     between several physical disks.  If the MySQL server is acting as a
     replication slave, you should not set 'tmpdir' to point to a
     directory on a memory-based file system or to a directory that is
     cleared when the server host restarts.  A replication slave needs
     some of its temporary files to survive a machine restart so that it
     can replicate temporary tables or 'LOAD DATA INFILE'
     operations.  If files in the temporary file directory
     are lost when the server restarts, replication fails.  You can set
     the slave's temporary directory using the 'slave_load_tmpdir'
     variable.  In that case, the slave will not use the general
     'tmpdir' value and you can set 'tmpdir' to a nonpermanent location.

   *
     'transaction_alloc_block_size'

     Property                             Value

     *Command-Line Format*                '--transaction-alloc-block-size=#'

     *System Variable*                    'transaction_alloc_block_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms, <=         integer
     5.7.5)

     *Type* (32-bit platforms, <=         integer
     5.7.5)

     *Type* (>= 5.7.6)                    integer

     *Default Value* (64-bit platforms,   '8192'
     <= 5.7.5)

     *Default Value* (32-bit platforms,   '8192'
     <= 5.7.5)

     *Default Value* (>= 5.7.6)           '8192'

     *Minimum Value* (64-bit platforms,   '1024'
     <= 5.7.5)

     *Minimum Value* (32-bit platforms,   '1024'
     <= 5.7.5)

     *Minimum Value* (>= 5.7.6)           '1024'

     *Maximum Value* (64-bit platforms,   '18446744073709551615'
     <= 5.7.5)

     *Maximum Value* (32-bit platforms,   '4294967295'
     <= 5.7.5)

     *Maximum Value* (>= 5.7.6)           '131072'

     *Block Size* (64-bit platforms, <=   '1024'
     5.7.5)

     *Block Size* (32-bit platforms, <=   '1024'
     5.7.5)

     *Block Size* (>= 5.7.6)              '1024'

     The amount in bytes by which to increase a per-transaction memory
     pool which needs memory.  See the description of
     'transaction_prealloc_size'.

   *
     'transaction_isolation'

     Property                             Value

     *Command-Line Format*                '--transaction-isolation=name'

     *System Variable* (>= 5.7.20)        'transaction_isolation'

     *Scope* (>= 5.7.20)                  Global, Session

     *Dynamic* (>= 5.7.20)                Yes

     *Type*                               enumeration

     *Default Value*                      'REPEATABLE-READ'

     *Valid Values*                       'READ-UNCOMMITTED'
                                          'READ-COMMITTED' 'REPEATABLE-READ'
                                          'SERIALIZABLE'

     The default transaction isolation level.  Defaults to
     'REPEATABLE-READ'.

     This variable can be set directly, or indirectly using the
     'SET TRANSACTION' statement.  See
     set-transaction.  If you set 'transaction_isolation' directly to
     an isolation level name that contains a space, the name should be
     enclosed within quotation marks, with the space replaced by a dash.
     For example:

          SET transaction_isolation = 'READ-COMMITTED';

     Any unique prefix of a valid value may be used to set the value of
     this variable.

     The default transaction isolation level can also be set at startup
     using the '--transaction-isolation' server option.

     *Note*:

     'transaction_isolation' was added in MySQL 5.7.20 as an alias for
     'tx_isolation', which is now deprecated and is removed in MySQL
     8.0.  Applications should be adjusted to use
     'transaction_isolation' in preference to 'tx_isolation'.

   *
     'transaction_prealloc_size'

     Property                             Value

     *Command-Line Format*                '--transaction-prealloc-size=#'

     *System Variable*                    'transaction_prealloc_size'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (64-bit platforms, <=         integer
     5.7.5)

     *Type* (32-bit platforms, <=         integer
     5.7.5)

     *Type* (>= 5.7.6)                    integer

     *Default Value* (64-bit platforms,   '4096'
     <= 5.7.5)

     *Default Value* (32-bit platforms,   '4096'
     <= 5.7.5)

     *Default Value* (>= 5.7.6)           '4096'

     *Minimum Value* (64-bit platforms,   '1024'
     <= 5.7.5)

     *Minimum Value* (32-bit platforms,   '1024'
     <= 5.7.5)

     *Minimum Value* (>= 5.7.6)           '1024'

     *Maximum Value* (64-bit platforms,   '18446744073709551615'
     <= 5.7.5)

     *Maximum Value* (32-bit platforms,   '4294967295'
     <= 5.7.5)

     *Maximum Value* (>= 5.7.6)           '131072'

     *Block Size* (64-bit platforms, <=   '1024'
     5.7.5)

     *Block Size* (32-bit platforms, <=   '1024'
     5.7.5)

     *Block Size* (>= 5.7.6)              '1024'

     There is a per-transaction memory pool from which various
     transaction-related allocations take memory.  The initial size of
     the pool in bytes is 'transaction_prealloc_size'.  For every
     allocation that cannot be satisfied from the pool because it has
     insufficient memory available, the pool is increased by
     'transaction_alloc_block_size' bytes.  When the transaction ends,
     the pool is truncated to 'transaction_prealloc_size' bytes.

     By making 'transaction_prealloc_size' sufficiently large to contain
     all statements within a single transaction, you can avoid many
     'malloc()' calls.

   *
     'transaction_read_only'

     Property                             Value

     *Command-Line Format*                '--transaction-read-only'

     *System Variable* (>= 5.7.20)        'transaction_read_only'

     *Scope* (>= 5.7.20)                  Global, Session

     *Dynamic* (>= 5.7.20)                Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     The default transaction access mode.  The value can be 'OFF'
     (read/write, the default) or 'ON' (read only).

     This variable can be set directly, or indirectly using the
     'SET TRANSACTION' statement.  See
     set-transaction.

     To set the default transaction access mode at startup, use the
     '--transaction-read-only' server option.

     *Note*:

     'transaction_read_only' was added in MySQL 5.7.20 as an alias for
     'tx_read_only', which is now deprecated and is removed in MySQL
     8.0.  Applications should be adjusted to use
     'transaction_read_only' in preference to 'tx_read_only'.

   *
     'transaction_write_set_extraction'

     Property                             Value

     *Command-Line Format*                '--transaction-write-set-extraction=[value]'

     *Introduced*                         5.7.6

     *System Variable*                    'transaction_write_set_extraction'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'OFF'

     *Valid Values* (>= 5.7.14)           'OFF' 'MURMUR32' 'XXHASH64'

     *Valid Values* (<= 5.7.13)           'OFF' 'MURMUR32'

     Defines the algorithm used to generate a hash identifying the
     writes associated with a transaction.  If you are using Group
     Replication, the hash value is used for distributed conflict
     detection and handling.  On 64-bit systems running Group
     Replication, we recommend setting this to 'XXHASH64' in order to
     avoid unnecessary hash collisions which result in certification
     failures and the roll back of user transactions.  See
     group-replication-requirements.

     *Note*:

     The value of this variable cannot be changed when
     'binlog_transaction_dependency_tracking' is set to either of
     'WRITESET' or 'WRITESET_SESSION'.

   *
     'tx_isolation'

     Property                             Value

     *Deprecated*                         5.7.20

     *System Variable*                    'tx_isolation'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'REPEATABLE-READ'

     *Valid Values*                       'READ-UNCOMMITTED'
                                          'READ-COMMITTED' 'REPEATABLE-READ'
                                          'SERIALIZABLE'

     The default transaction isolation level.  Defaults to
     'REPEATABLE-READ'.

     This variable can be set directly, or indirectly using the
     'SET TRANSACTION' statement.  See
     set-transaction.  If you set 'tx_isolation' directly to an
     isolation level name that contains a space, the name should be
     enclosed within quotation marks, with the space replaced by a dash.
     For example:

          SET tx_isolation = 'READ-COMMITTED';

     Any unique prefix of a valid value may be used to set the value of
     this variable.

     The default transaction isolation level can also be set at startup
     using the '--transaction-isolation' server option.

     *Note*:

     'transaction_isolation' was added in MySQL 5.7.20 as an alias for
     'tx_isolation', which is now deprecated and is removed in MySQL
     8.0.  Applications should be adjusted to use
     'transaction_isolation' in preference to 'tx_isolation'.

   *
     'tx_read_only'

     Property                             Value

     *Deprecated*                         5.7.20

     *System Variable*                    'tx_read_only'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     The default transaction access mode.  The value can be 'OFF'
     (read/write, the default) or 'ON' (read only).

     This variable can be set directly, or indirectly using the
     'SET TRANSACTION' statement.  See
     set-transaction.

     To set the default transaction access mode at startup, use the
     '--transaction-read-only' server option.

     *Note*:

     'transaction_read_only' was added in MySQL 5.7.20 as an alias for
     'tx_read_only', which is now deprecated and is removed in MySQL
     8.0.  Applications should be adjusted to use
     'transaction_read_only' in preference to 'tx_read_only'.

   *
     'unique_checks'

     Property                             Value

     *System Variable*                    'unique_checks'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '1'

     If set to 1 (the default), uniqueness checks for secondary indexes
     in 'InnoDB' tables are performed.  If set to 0, storage engines are
     permitted to assume that duplicate keys are not present in input
     data.  If you know for certain that your data does not contain
     uniqueness violations, you can set this to 0 to speed up large
     table imports to 'InnoDB'.

     Setting this variable to 0 does not _require_ storage engines to
     ignore duplicate keys.  An engine is still permitted to check for
     them and issue duplicate-key errors if it detects them.

   *
     'updatable_views_with_limit'

     Property                             Value

     *Command-Line Format*                '--updatable-views-with-limit=#'

     *System Variable*                    'updatable_views_with_limit'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '1'

     This variable controls whether updates to a view can be made when
     the view does not contain all columns of the primary key defined in
     the underlying table, if the update statement contains a 'LIMIT'
     clause.  (Such updates often are generated by GUI tools.)  An
     update is an 'UPDATE' or 'DELETE'.
     statement.  Primary key here means a 'PRIMARY KEY', or a 'UNIQUE'
     index in which no column can contain 'NULL'.

     The variable can have two values:

        * '1' or 'YES': Issue a warning only (not an error message).
          This is the default value.

        * '0' or 'NO': Prohibit the update.

   * 'validate_password_XXX'

     The 'validate_password' plugin implements a set of system variables
     having names of the form 'validate_password_XXX'.  These variables
     affect password testing by that plugin; see
     validate-password-options-variables.

   *
     'validate_user_plugins'

     Property                             Value

     *System Variable*                    'validate_user_plugins'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     If this variable is enabled (the default), the server checks each
     user account and produces a warning if conditions are found that
     would make the account unusable:

        * The account requires an authentication plugin that is not
          loaded.

        * The account requires the 'sha256_password' authentication
          plugin but the server was started with neither SSL nor RSA
          enabled as required by this plugin.

     Enabling 'validate_user_plugins' slows down server initialization
     and 'FLUSH PRIVILEGES'.  If you do not require the additional
     checking, you can disable this variable at startup to avoid the
     performance decrement.

   *
     'version'

     The version number for the server.  The value might also include a
     suffix indicating server build or configuration information.
     '-log' indicates that one or more of the general log, slow query
     log, or binary log are enabled.  '-debug' indicates that the server
     was built with debugging support enabled.

   *
     'version_comment'

     Property                             Value

     *System Variable*                    'version_comment'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The 'CMake' configuration program has a 'COMPILATION_COMMENT'
     option that permits a comment to be specified when building MySQL.
     This variable contains the value of that comment.  See
     source-configuration-options.

   *
     'version_compile_machine'

     Property                             Value

     *System Variable*                    'version_compile_machine'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The type of the server binary.

   *
     'version_compile_os'

     Property                             Value

     *System Variable*                    'version_compile_os'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The type of operating system on which MySQL was built.

   *
     'wait_timeout'

     Property                             Value

     *Command-Line Format*                '--wait-timeout=#'

     *System Variable*                    'wait_timeout'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type* (Other)                       integer

     *Type* (Windows)                     integer

     *Default Value* (Other)              '28800'

     *Default Value* (Windows)            '28800'

     *Minimum Value* (Other)              '1'

     *Minimum Value* (Windows)            '1'

     *Maximum Value* (Other)              '31536000'

     *Maximum Value* (Windows)            '2147483'

     The number of seconds the server waits for activity on a
     noninteractive connection before closing it.

     On thread startup, the session 'wait_timeout' value is initialized
     from the global 'wait_timeout' value or from the global
     'interactive_timeout' value, depending on the type of client (as
     defined by the 'CLIENT_INTERACTIVE' connect option to
     'mysql_real_connect()').  See also
     'interactive_timeout'.

   *
     'warning_count'

     The number of errors, warnings, and notes that resulted from the
     last statement that generated messages.  This variable is read
     only.  See show-warnings.

5.1.6 Using System Variables
----------------------------

The MySQL server maintains many system variables that indicate how it is
configured.  See server-system-variables, describes the meaning of
these variables.  Each system variable has a default value.  System
variables can be set at server startup using options on the command line
or in an option file.  Most of them can be changed dynamically while the
server is running by means of the 'SET' statement,
which enables you to modify operation of the server without having to
stop and restart it.  You can also use system variable values in
expressions.

There are two scopes in which system variables exist.  Global variables
affect the overall operation of the server.  Session variables affect
its operation for individual client connections.  A given system
variable can have both a global and a session value.  Global and session
system variables are related as follows:

   * When the server starts, it initializes each global variable to its
     default value.  These defaults can be changed by options specified
     on the command line or in an option file.  (See
     program-options.)

   * The server also maintains a set of session variables for each
     client that connects.  The client's session variables are
     initialized at connect time using the current values of the
     corresponding global variables.  For example, a client's SQL mode
     is controlled by the session 'sql_mode' value, which is initialized
     when the client connects to the value of the global 'sql_mode'
     value.

     For some system variables, the session value is not initialized
     from the corresponding global value; if so, that is indicated in
     the variable description.

System variable values can be set globally at server startup by using
options on the command line or in an option file.  When you use a
startup option to set a variable that takes a numeric value, the value
can be given with a suffix of 'K', 'M', or 'G' (either uppercase or
lowercase) to indicate a multiplier of 1024, 1024^2 or 1024^3; that is,
units of kilobytes, megabytes, or gigabytes, respectively.  Thus, the
following command starts the server with an 'InnoDB' log file size of 16
megabytes and a maximum packet size of one gigabyte:

     mysqld --innodb_log_file_size=16M --max_allowed_packet=1G

Within an option file, those variables are set like this:

     [mysqld]
     innodb_log_file_size=16M
     max_allowed_packet=1G

The lettercase of suffix letters does not matter; '16M' and '16m' are
equivalent, as are '1G' and '1g'.

To restrict the maximum value to which a system variable can be set at
runtime with the 'SET' statement, specify this
maximum by using an option of the form '--maximum-VAR_NAME=VALUE' at
server startup.  For example, to prevent the value of
'innodb_log_file_size' from being increased to more than 32MB at
runtime, use the option '--maximum-innodb_log_file_size=32M'.

Many system variables are dynamic and can be changed at runtime by using
the 'SET' statement.  For a list, see
dynamic-system-variables.  To change a system variable with
'SET', refer to it by name, optionally preceded by a
modifier:

   * To indicate that a variable is a global variable, precede its name
     by the 'GLOBAL' keyword or the '@@global.' qualifier:

          SET GLOBAL max_connections = 1000;
          SET @@global.max_connections = 1000;

     The 'SUPER' privilege is required to set global variables.

   * To indicate that a variable is a session variable, precede its name
     by the 'SESSION' keyword or either the '@@session.' or '@@'
     qualifier:

          SET SESSION sql_mode = 'TRADITIONAL';
          SET @@session.sql_mode = 'TRADITIONAL';
          SET @@sql_mode = 'TRADITIONAL';

     Setting a session variable normally requires no special privilege,
     although there are exceptions that require the 'SUPER' privilege
     (such as 'sql_log_bin').  A client can change its own session
     variables, but not those of any other client.

   * 'LOCAL' and '@@local.' are synonyms for 'SESSION' and '@@session.'.

   * If no modifier is present, see 'SET' changes the
     session variable.

   * An error occurs under these circumstances:

        * Use of 'SET GLOBAL'. (or '@@global.') when
          setting a variable that has only a session value:

               mysql> SET GLOBAL sql_log_bin = ON;
               ERROR 1231 (42000): Variable 'sql_log_bin' can't be
               set to the value of 'ON'

        * Omission of 'GLOBAL' (or '@@global.') when setting a variable
          that has only a global value:

               mysql> SET max_connections = 1000;
               ERROR 1229 (HY000): Variable 'max_connections' is a
               GLOBAL variable and should be set with SET GLOBAL

        * Use of 'SET SESSION'. (or '@@SESSION.')
          when setting a variable that has only a global value:

               mysql> SET SESSION max_connections = 1000;
               ERROR 1229 (HY000): Variable 'max_connections' is a
               GLOBAL variable and should be set with SET GLOBAL

The preceding modifiers apply only to system variables.  An error occurs
for attempts to apply them to user-defined variables, stored procedure
or function parameters, or stored program local variables.

A 'SET' statement can contain multiple variable
assignments, separated by commas.  This statement assigns values to a
user-defined variable and a system variable:

     SET @x = 1, SESSION sql_mode = '';

If you set multiple system variables, the most recent 'GLOBAL' or
'SESSION' modifier in the statement is used for following assignments
that have no modifier specified.

Examples of multiple-variable assignment:

     SET GLOBAL sort_buffer_size = 1000000, SESSION sort_buffer_size = 1000000;
     SET @@global.sort_buffer_size = 1000000, @@local.sort_buffer_size = 1000000;
     SET GLOBAL max_connections = 1000, sort_buffer_size = 1000000;

If any variable assignment in a 'SET' statement
fails, the entire statement fails and no variables are changed.

If you change a session system variable, the value remains in effect
within your session until you change the variable to a different value
or the session ends.  The change has no effect on other sessions.

If you change a global system variable, the value is remembered and used
for new sessions until you change the variable to a different value or
the server exits.  The change is visible to any client that accesses the
global variable.  However, the change affects the corresponding session
variable only for clients that connect after the change.  The global
variable change does not affect the session variable for any current
client sessions (not even the session within which the 'SET GLOBAL'
statement occurred).

To make a global system variable setting permanent so that it applies
across server restarts, you should also set it in an option file.

To set a 'GLOBAL' value to the compiled-in MySQL default value or a
'SESSION' variable to the current corresponding 'GLOBAL' value, set the
variable to the value 'DEFAULT'.  For example, the following two
statements are identical in setting the session value of 'max_join_size'
to the current global value:

     SET @@session.max_join_size=DEFAULT;
     SET @@session.max_join_size=@@global.max_join_size;

Not all system variables can be set to 'DEFAULT'.  In such cases,
assigning 'DEFAULT' results in an error.

An error occurs for attempts to assign 'DEFAULT' to user-defined
variables, stored procedure or function parameters, or stored program
local variables.

To refer to the value of a system variable in expressions, use one of
the '@@'-modifiers.  For example, you can retrieve values in a
'SELECT' statement like this:

     SELECT @@global.sql_mode, @@session.sql_mode, @@sql_mode;

For a reference to a system variable in an expression as '@@VAR_NAME'
(rather than with '@@global.' or '@@session.'), MySQL returns the
session value if it exists and the global value otherwise.  This differs
from 'SET @@VAR_NAME = EXPR', which always refers to the session value.

Suffixes for specifying a value multiplier can be used when setting a
variable at server startup, but not to set the value with 'SET'
at runtime.  On the other hand, with 'SET'
you can assign a variable's value using an expression,
which is not true when you set a variable at server startup.  For
example, the first of the following lines is legal at server startup,
but the second is not:

     shell> mysql --max_allowed_packet=16M
     shell> mysql --max_allowed_packet=16*1024*1024

Conversely, the second of the following lines is legal at runtime, but
the first is not:

     mysql> SET GLOBAL max_allowed_packet=16M;
     mysql> SET GLOBAL max_allowed_packet=16*1024*1024;

*Note*:

Some system variables can be enabled with the 'SET'.
statement by setting them to 'ON' or '1', or disabled by setting them to
'OFF' or '0'.  However, to set such a variable on the command line or in
an option file, you must set it to '1' or '0'; setting it to 'ON' or
'OFF' will not work.  For example, on the command line,
'--delay_key_write=1' works but '--delay_key_write=ON' does not.

To display system variable names and values, use the 'SHOW VARIABLES'
statement:

     mysql> SHOW VARIABLES;
     +---------------------------------+-----------------------------------+
     | Variable_name                   | Value                             |
     +---------------------------------+-----------------------------------+
     | auto_increment_increment        | 1                                 |
     | auto_increment_offset           | 1                                 |
     | automatic_sp_privileges         | ON                                |
     | back_log                        | 50                                |
     | basedir                         | /home/mysql/                      |
     | binlog_cache_size               | 32768                             |
     | bulk_insert_buffer_size         | 8388608                           |
     | character_set_client            | utf8                              |
     | character_set_connection        | utf8                              |
     | character_set_database          | latin1                            |
     | character_set_filesystem        | binary                            |
     | character_set_results           | utf8                              |
     | character_set_server            | latin1                            |
     | character_set_system            | utf8                              |
     | character_sets_dir              | /home/mysql/share/mysql/charsets/ |
     | collation_connection            | utf8_general_ci                   |
     | collation_database              | latin1_swedish_ci                 |
     | collation_server                | latin1_swedish_ci                 |
     ...
     | innodb_autoextend_increment     | 8                                 |
     | innodb_buffer_pool_size         | 8388608                           |
     | innodb_checksums                | ON                                |
     | innodb_commit_concurrency       | 0                                 |
     | innodb_concurrency_tickets      | 500                               |
     | innodb_data_file_path           | ibdata1:10M:autoextend            |
     | innodb_data_home_dir            |                                   |
     ...
     | version                         | 5.7.18-log                        |
     | version_comment                 | Source distribution               |
     | version_compile_machine         | i686                              |
     | version_compile_os              | suse-linux                        |
     | wait_timeout                    | 28800                             |
     +---------------------------------+-----------------------------------+

With a 'LIKE' clause, the statement displays only those variables that
match the pattern.  To obtain a specific variable name, use a 'LIKE'
clause as shown:

     SHOW VARIABLES LIKE 'max_join_size';
     SHOW SESSION VARIABLES LIKE 'max_join_size';

To get a list of variables whose name match a pattern, use the '%'
wildcard character in a 'LIKE' clause:

     SHOW VARIABLES LIKE '%size%';
     SHOW GLOBAL VARIABLES LIKE '%size%';

Wildcard characters can be used in any position within the pattern to be
matched.  Strictly speaking, because '_' is a wildcard that matches any
single character, you should escape it as '\_' to match it literally.
In practice, this is rarely necessary.

For 'SHOW VARIABLES', if you specify neither
'GLOBAL' nor 'SESSION', MySQL returns 'SESSION' values.

The reason for requiring the 'GLOBAL' keyword when setting 'GLOBAL'-only
variables but not when retrieving them is to prevent problems in the
future:

   * Were we to remove a 'SESSION' variable that has the same name as a
     'GLOBAL' variable, a client with the 'SUPER' privilege might
     accidentally change the 'GLOBAL' variable rather than just the
     'SESSION' variable for its own connection.

   * Were we to add a 'SESSION' variable with the same name as a
     'GLOBAL' variable, a client that intends to change the 'GLOBAL'
     variable might find only its own 'SESSION' variable changed.

5.1.6.1 Structured System Variables
...................................

A structured variable differs from a regular system variable in two
respects:

   * Its value is a structure with components that specify server
     parameters considered to be closely related.

   * There might be several instances of a given type of structured
     variable.  Each one has a different name and refers to a different
     resource maintained by the server.

MySQL supports one structured variable type, which specifies parameters
governing the operation of key caches.  A key cache structured variable
has these components:

   * 'key_buffer_size'

   * 'key_cache_block_size'

   * 'key_cache_division_limit'

   * 'key_cache_age_threshold'

This section describes the syntax for referring to structured variables.
Key cache variables are used for syntax examples, but specific details
about how key caches operate are found elsewhere, in
myisam-key-cache.

To refer to a component of a structured variable instance, you can use a
compound name in INSTANCE_NAME.COMPONENT_NAME format.  Examples:

     hot_cache.key_buffer_size
     hot_cache.key_cache_block_size
     cold_cache.key_cache_block_size

For each structured system variable, an instance with the name of
'default' is always predefined.  If you refer to a component of a
structured variable without any instance name, the 'default' instance is
used.  Thus, 'default.key_buffer_size' and 'key_buffer_size' both refer
to the same system variable.

Structured variable instances and components follow these naming rules:

   * For a given type of structured variable, each instance must have a
     name that is unique _within_ variables of that type.  However,
     instance names need not be unique _across_ structured variable
     types.  For example, each structured variable has an instance named
     'default', so 'default' is not unique across variable types.

   * The names of the components of each structured variable type must
     be unique across all system variable names.  If this were not true
     (that is, if two different types of structured variables could
     share component member names), it would not be clear which default
     structured variable to use for references to member names that are
     not qualified by an instance name.

   * If a structured variable instance name is not legal as an unquoted
     identifier, refer to it as a quoted identifier using backticks.
     For example, 'hot-cache' is not legal, but '`hot-cache`' is.

   * 'global', 'session', and 'local' are not legal instance names.
     This avoids a conflict with notation such as '@@global.VAR_NAME'
     for referring to nonstructured system variables.

Currently, the first two rules have no possibility of being violated
because the only structured variable type is the one for key caches.
These rules will assume greater significance if some other type of
structured variable is created in the future.

With one exception, you can refer to structured variable components
using compound names in any context where simple variable names can
occur.  For example, you can assign a value to a structured variable
using a command-line option:

     shell> mysqld --hot_cache.key_buffer_size=64K

In an option file, use this syntax:

     [mysqld]
     hot_cache.key_buffer_size=64K

If you start the server with this option, it creates a key cache named
'hot_cache' with a size of 64KB in addition to the default key cache
that has a default size of 8MB.

Suppose that you start the server as follows:

     shell> mysqld --key_buffer_size=256K \
              --extra_cache.key_buffer_size=128K \
              --extra_cache.key_cache_block_size=2048

In this case, the server sets the size of the default key cache to
256KB. (You could also have written '--default.key_buffer_size=256K'.)
In addition, the server creates a second key cache named 'extra_cache'
that has a size of 128KB, with the size of block buffers for caching
table index blocks set to 2048 bytes.

The following example starts the server with three different key caches
having sizes in a 3:1:1 ratio:

     shell> mysqld --key_buffer_size=6M \
              --hot_cache.key_buffer_size=2M \
              --cold_cache.key_buffer_size=2M

Structured variable values may be set and retrieved at runtime as well.
For example, to set a key cache named 'hot_cache' to a size of 10MB, use
either of these statements:

     mysql> SET GLOBAL hot_cache.key_buffer_size = 10*1024*1024;
     mysql> SET @@global.hot_cache.key_buffer_size = 10*1024*1024;

To retrieve the cache size, do this:

     mysql> SELECT @@global.hot_cache.key_buffer_size;

However, the following statement does not work.  The variable is not
interpreted as a compound name, but as a simple string for a 'LIKE'
pattern-matching operation:

     mysql> SHOW GLOBAL VARIABLES LIKE 'hot_cache.key_buffer_size';

This is the exception to being able to use structured variable names
anywhere a simple variable name may occur.

5.1.6.2 Dynamic System Variables
................................

Many server system variables are dynamic and can be set at runtime using
'SET GLOBAL' or 'SET SESSION'.
You can also obtain their values using 'SELECT'.  See
using-system-variables.

The following table shows the full list of all dynamic system variables.
The last column indicates for each variable whether 'GLOBAL' or
'SESSION' (or both) apply.  The table also lists session options that
can be set with the 'SET' statement.  See
server-system-variables, discusses these options.

Variables that have a type of 'string' take a string value.  Variables
that have a type of 'numeric' take a numeric value.  Variables that have
a type of 'boolean' can be set to 0, 1, 'ON' or 'OFF'.  Variables that
are marked as 'enumeration' normally should be set to one of the
available values for the variable, but can also be set to the number
that corresponds to the desired enumeration value.  For enumerated
system variables, the first enumeration value corresponds to 0.  This
differs from 'ENUM' columns, for which the first
enumeration value corresponds to 1.

*Dynamic Variable Summary*

Variable Name                 Variable       Variable
                              Type           Scope

'audit_log_connection_policy' enumeration    'GLOBAL'

'audit_log_exclude_accounts'  string         'GLOBAL'

'audit_log_flush'             boolean        'GLOBAL'

'audit_log_include_accounts'  string         'GLOBAL'

'audit_log_rotate_on_size'    integer        'GLOBAL'

'audit_log_statement_policy'  enumeration    'GLOBAL'

'authentication_ldap_sasl_auth_method_name'string'GLOBAL'

'authentication_ldap_sasl_bind_base_dn'string'GLOBAL'

'authentication_ldap_sasl_bind_root_dn'string'GLOBAL'

'authentication_ldap_sasl_bind_root_pwd'string'GLOBAL'

'authentication_ldap_sasl_ca_path'string     'GLOBAL'

'authentication_ldap_sasl_group_search_attr'string'GLOBAL'

'authentication_ldap_sasl_group_search_filter'string'GLOBAL'

'authentication_ldap_sasl_init_pool_size'integer'GLOBAL'

'authentication_ldap_sasl_log_status'integer 'GLOBAL'

'authentication_ldap_sasl_max_pool_size'integer'GLOBAL'

'authentication_ldap_sasl_server_host'string 'GLOBAL'

'authentication_ldap_sasl_server_port'integer'GLOBAL'

'authentication_ldap_sasl_tls'boolean        'GLOBAL'

'authentication_ldap_sasl_user_search_attr'string'GLOBAL'

'authentication_ldap_simple_auth_method_name'string'GLOBAL'

'authentication_ldap_simple_bind_base_dn'string'GLOBAL'

'authentication_ldap_simple_bind_root_dn'string'GLOBAL'

'authentication_ldap_simple_bind_root_pwd'string'GLOBAL'

'authentication_ldap_simple_ca_path'string   'GLOBAL'

'authentication_ldap_simple_group_search_attr'string'GLOBAL'

'authentication_ldap_simple_group_search_filter'string'GLOBAL'

'authentication_ldap_simple_init_pool_size'integer'GLOBAL'

'authentication_ldap_simple_log_status'integer'GLOBAL'

'authentication_ldap_simple_max_pool_size'integer'GLOBAL'

'authentication_ldap_simple_server_host'string'GLOBAL'

'authentication_ldap_simple_server_port'integer'GLOBAL'

'authentication_ldap_simple_tls'boolean      'GLOBAL'

'authentication_ldap_simple_user_search_attr'string'GLOBAL'

'auto_increment_increment'    integer        'GLOBAL' |
                                             'SESSION'

'auto_increment_offset'       integer        'GLOBAL' |
                                             'SESSION'

'autocommit'                  boolean        'GLOBAL' |
                                             'SESSION'

'automatic_sp_privileges'     boolean        'GLOBAL'

'avoid_temporal_upgrade'      boolean        'GLOBAL'

'big_tables'                  boolean        'GLOBAL' |
                                             'SESSION'

'binlog_cache_size'           integer        'GLOBAL'

'binlog_checksum'             string         'GLOBAL'

'binlog_direct_non_transactional_updates'boolean'GLOBAL' |
                                             'SESSION'

'binlog_error_action'         enumeration    'GLOBAL'

'binlog_format'               enumeration    'GLOBAL' |
                                             'SESSION'

'binlog_group_commit_sync_delay'integer      'GLOBAL'

'binlog_group_commit_sync_no_delay_count'integer'GLOBAL'

'binlog_max_flush_queue_time' integer        'GLOBAL'

'binlog_order_commits'        boolean        'GLOBAL'

'binlog_row_image=image_type' enumeration    'GLOBAL' |
                                             'SESSION'

'binlog_rows_query_log_events'boolean        'GLOBAL' |
                                             'SESSION'

'binlog_stmt_cache_size'      integer        'GLOBAL'

'binlog_transaction_dependency_history_size'integer'GLOBAL'

'binlog_transaction_dependency_tracking'enumeration'GLOBAL'

'binlogging_impossible_mode'  enumeration    'GLOBAL' |
                                             'SESSION'

'block_encryption_mode'       string         'GLOBAL' |
                                             'SESSION'

'bulk_insert_buffer_size'     integer        'GLOBAL' |
                                             'SESSION'

'character_set_client'        string         'GLOBAL' |
                                             'SESSION'

'character_set_connection'    string         'GLOBAL' |
                                             'SESSION'

'character_set_database'      string         'GLOBAL' |
                                             'SESSION'

'character_set_filesystem'    string         'GLOBAL' |
                                             'SESSION'

'character_set_results'       string         'GLOBAL' |
                                             'SESSION'

'character_set_server'        string         'GLOBAL' |
                                             'SESSION'

'check_proxy_users'           boolean        'GLOBAL'

'collation_connection'        string         'GLOBAL' |
                                             'SESSION'

'collation_database'          string         'GLOBAL' |
                                             'SESSION'

'collation_server'            string         'GLOBAL' |
                                             'SESSION'

'completion_type'             enumeration    'GLOBAL' |
                                             'SESSION'

'concurrent_insert'           enumeration    'GLOBAL'

'connect_timeout'             integer        'GLOBAL'

'connection_control_failed_connections_threshold'integer'GLOBAL'

'connection_control_max_connection_delay'integer'GLOBAL'

'connection_control_min_connection_delay'integer'GLOBAL'

'debug'                       string         'GLOBAL' |
                                             'SESSION'

'debug_sync'                  string         'SESSION'

'default_password_lifetime'   integer        'GLOBAL'

'default_storage_engine'      enumeration    'GLOBAL' |
                                             'SESSION'

'default_tmp_storage_engine'  enumeration    'GLOBAL' |
                                             'SESSION'

'default_week_format'         integer        'GLOBAL' |
                                             'SESSION'

'delay_key_write'             enumeration    'GLOBAL'

'delayed_insert_limit'        integer        'GLOBAL'

'delayed_insert_timeout'      integer        'GLOBAL'

'delayed_queue_size'          integer        'GLOBAL'

'div_precision_increment'     integer        'GLOBAL' |
                                             'SESSION'

'end_markers_in_json'         boolean        'GLOBAL' |
                                             'SESSION'

'enforce_gtid_consistency'    enumeration    'GLOBAL'

'enforce_gtid_consistency'    enumeration    'GLOBAL'

'eq_range_index_dive_limit'   integer        'GLOBAL' |
                                             'SESSION'

'event_scheduler'             enumeration    'GLOBAL'

'executed_gtids_compression_period'integer   'GLOBAL'

'expire_logs_days'            integer        'GLOBAL'

'explicit_defaults_for_timestamp'boolean     'GLOBAL' |
                                             'SESSION'

'flush'                       boolean        'GLOBAL'

'flush_time'                  integer        'GLOBAL'

'foreign_key_checks'          boolean        'GLOBAL' |
                                             'SESSION'

'ft_boolean_syntax'           string         'GLOBAL'

'general_log'                 boolean        'GLOBAL'

'general_log_file'            filename       'GLOBAL'

'group_concat_max_len'        integer        'GLOBAL' |
                                             'SESSION'

'group_replication_allow_local_disjoint_gtids_join'boolean'GLOBAL'

'group_replication_allow_local_lower_version_join'boolean'GLOBAL'

'group_replication_auto_increment_increment'integer'GLOBAL'

'group_replication_bootstrap_group'boolean   'GLOBAL'

'group_replication_components_stop_timeout'integer'GLOBAL'

'group_replication_compression_threshold'integer'GLOBAL'

'group_replication_enforce_update_everywhere_checks'boolean'GLOBAL'

'group_replication_flow_control_applier_threshold'integer'GLOBAL'

'group_replication_flow_control_certifier_threshold'integer'GLOBAL'

'group_replication_flow_control_mode'enumeration'GLOBAL'

'group_replication_force_members'string      'GLOBAL'

'group_replication_group_name'string         'GLOBAL'

'group_replication_group_seeds'string        'GLOBAL'

'group_replication_gtid_assignment_block_size'integer'GLOBAL'

'group_replication_ip_whitelist'string       'GLOBAL'

'group_replication_local_address'string      'GLOBAL'

'group_replication_member_weight'integer     'GLOBAL'

'group_replication_poll_spin_loops'integer   'GLOBAL'

'group_replication_recovery_complete_at'enumeration'GLOBAL'

'group_replication_recovery_reconnect_interval'integer'GLOBAL'

'group_replication_recovery_retry_count'integer'GLOBAL'

'group_replication_recovery_ssl_ca'string    'GLOBAL'

'group_replication_recovery_ssl_capath'string'GLOBAL'

'group_replication_recovery_ssl_cert'string  'GLOBAL'

'group_replication_recovery_ssl_cipher'string'GLOBAL'

'group_replication_recovery_ssl_crl'string   'GLOBAL'

'group_replication_recovery_ssl_crlpath'string'GLOBAL'

'group_replication_recovery_ssl_key'string   'GLOBAL'

'group_replication_recovery_ssl_verify_server_cert'boolean'GLOBAL'

'group_replication_recovery_use_ssl'boolean  'GLOBAL'

'group_replication_single_primary_mode'boolean'GLOBAL'

'group_replication_ssl_mode'  enumeration    'GLOBAL'

'group_replication_start_on_boot'boolean     'GLOBAL'

'group_replication_transaction_size_limit'integer'GLOBAL'

'group_replication_unreachable_majority_timeout'integer'GLOBAL'

'gtid_executed_compression_period'integer    'GLOBAL'

'gtid_mode'                   enumeration    'GLOBAL'

'gtid_mode'                   enumeration    'GLOBAL'

'gtid_next'                   enumeration    'SESSION'

'gtid_purged'                 string         'GLOBAL'

'host_cache_size'             integer        'GLOBAL'

'identity'                    integer        'SESSION'

'init_connect'                string         'GLOBAL'

'init_slave'                  string         'GLOBAL'

'innodb_adaptive_flushing'    boolean        'GLOBAL'

'innodb_adaptive_flushing_lwm'integer        'GLOBAL'

'innodb_adaptive_hash_index'  boolean        'GLOBAL'

'innodb_adaptive_max_sleep_delay'integer     'GLOBAL'

'innodb_api_bk_commit_interval'integer       'GLOBAL'

'innodb_api_trx_level'        integer        'GLOBAL'

'innodb_autoextend_increment' integer        'GLOBAL'

'innodb_background_drop_list_empty'boolean   'GLOBAL'

'innodb_buffer_pool_dump_at_shutdown'boolean 'GLOBAL'

'innodb_buffer_pool_dump_now' boolean        'GLOBAL'

'innodb_buffer_pool_dump_pct' integer        'GLOBAL'

'innodb_buffer_pool_filename' filename       'GLOBAL'

'innodb_buffer_pool_load_abort'boolean       'GLOBAL'

'innodb_buffer_pool_load_now' boolean        'GLOBAL'

'innodb_buffer_pool_size'     integer        'GLOBAL'

'innodb_change_buffer_max_size'integer       'GLOBAL'

'innodb_change_buffering'     enumeration    'GLOBAL'

'innodb_change_buffering_debug'integer       'GLOBAL'

'innodb_checksum_algorithm'   enumeration    'GLOBAL'

'innodb_cmp_per_index_enabled'boolean        'GLOBAL'

'innodb_commit_concurrency'   integer        'GLOBAL'

'innodb_compress_debug'       enumeration    'GLOBAL'

'innodb_compression_failure_threshold_pct'integer'GLOBAL'

'innodb_compression_level'    integer        'GLOBAL'

'innodb_compression_pad_pct_max'integer      'GLOBAL'

'innodb_concurrency_tickets'  integer        'GLOBAL'

'innodb_deadlock_detect'      boolean        'GLOBAL'

'innodb_default_row_format'   enumeration    'GLOBAL'

'innodb_disable_resize_buffer_pool_debug'boolean'GLOBAL'

'innodb_disable_sort_file_cache'boolean      'GLOBAL'

'innodb_fast_shutdown'        integer        'GLOBAL'

'innodb_fil_make_page_dirty_debug'integer    'GLOBAL'

'innodb_file_format'          string         'GLOBAL'

'innodb_file_format_max'      string         'GLOBAL'

'innodb_file_per_table'       boolean        'GLOBAL'

'innodb_fill_factor'          integer        'GLOBAL'

'innodb_flush_log_at_timeout' integer        'GLOBAL'

'innodb_flush_log_at_trx_commit'enumeration  'GLOBAL'

'innodb_flush_neighbors'      enumeration    'GLOBAL'

'innodb_flush_sync'           boolean        'GLOBAL'

'innodb_flushing_avg_loops'   integer        'GLOBAL'

'innodb_ft_aux_table'         string         'GLOBAL'

'innodb_ft_enable_diag_print' boolean        'GLOBAL'

'innodb_ft_enable_stopword'   boolean        'GLOBAL'

'innodb_ft_num_word_optimize' integer        'GLOBAL'

'innodb_ft_result_cache_limit'integer        'GLOBAL'

'innodb_ft_server_stopword_table'string      'GLOBAL'

'innodb_ft_user_stopword_table'string        'GLOBAL' |
                                             'SESSION'

'innodb_io_capacity'          integer        'GLOBAL'

'innodb_io_capacity_max'      integer        'GLOBAL'

'innodb_large_prefix'         boolean        'GLOBAL'

'innodb_limit_optimistic_insert_debug'integer'GLOBAL'

'innodb_lock_wait_timeout'    integer        'GLOBAL' |
                                             'SESSION'

'innodb_log_checksum_algorithm'enumeration   'GLOBAL'

'innodb_log_checksums'        boolean        'GLOBAL'

'innodb_log_compressed_pages' boolean        'GLOBAL'

'innodb_log_write_ahead_size' integer        'GLOBAL'

'innodb_lru_scan_depth'       integer        'GLOBAL'

'innodb_max_dirty_pages_pct'  numeric        'GLOBAL'

'innodb_max_dirty_pages_pct_lwm'numeric      'GLOBAL'

'innodb_max_purge_lag'        integer        'GLOBAL'

'innodb_max_purge_lag_delay'  integer        'GLOBAL'

'innodb_max_undo_log_size'    integer        'GLOBAL'

'innodb_merge_threshold_set_all_debug'integer'GLOBAL'

'innodb_monitor_disable'      string         'GLOBAL'

'innodb_monitor_enable'       string         'GLOBAL'

'innodb_monitor_reset'        string         'GLOBAL'

'innodb_monitor_reset_all'    string         'GLOBAL'

'innodb_old_blocks_pct'       integer        'GLOBAL'

'innodb_old_blocks_time'      integer        'GLOBAL'

'innodb_online_alter_log_max_size'integer    'GLOBAL'

'innodb_optimize_fulltext_only'boolean       'GLOBAL'

'innodb_optimize_point_storage'boolean       'SESSION'

'innodb_print_all_deadlocks'  boolean        'GLOBAL'

'innodb_purge_batch_size'     integer        'GLOBAL'

'innodb_purge_rseg_truncate_frequency'integer'GLOBAL'

'innodb_random_read_ahead'    boolean        'GLOBAL'

'innodb_read_ahead_threshold' integer        'GLOBAL'

'innodb_replication_delay'    integer        'GLOBAL'

'innodb_rollback_segments'    integer        'GLOBAL'

'innodb_saved_page_number_debug'integer      'GLOBAL'

'innodb_spin_wait_delay'      integer        'GLOBAL'

'innodb_stats_auto_recalc'    boolean        'GLOBAL'

'innodb_stats_include_delete_marked'boolean  'GLOBAL'

'innodb_stats_method'         enumeration    'GLOBAL'

'innodb_stats_on_metadata'    boolean        'GLOBAL'

'innodb_stats_persistent'     boolean        'GLOBAL'

'innodb_stats_persistent_sample_pages'integer'GLOBAL'

'innodb_stats_sample_pages'   integer        'GLOBAL'

'innodb_stats_transient_sample_pages'integer 'GLOBAL'

'innodb_status_output'        boolean        'GLOBAL'

'innodb_status_output_locks'  boolean        'GLOBAL'

'innodb_strict_mode'          boolean        'GLOBAL' |
                                             'SESSION'

'innodb_support_xa'           boolean        'GLOBAL' |
                                             'SESSION'

'innodb_sync_spin_loops'      integer        'GLOBAL'

'innodb_table_locks'          boolean        'GLOBAL' |
                                             'SESSION'

'innodb_thread_concurrency'   integer        'GLOBAL'

'innodb_thread_sleep_delay'   integer        'GLOBAL'

'innodb_tmpdir'               dirname        'GLOBAL' |
                                             'SESSION'

'innodb_trx_purge_view_update_only_debug'boolean'GLOBAL'

'innodb_trx_rseg_n_slots_debug'integer       'GLOBAL'

'innodb_undo_log_truncate'    boolean        'GLOBAL'

'innodb_undo_logs'            integer        'GLOBAL'

'insert_id'                   integer        'SESSION'

'interactive_timeout'         integer        'GLOBAL' |
                                             'SESSION'

'internal_tmp_disk_storage_engine'enumeration'GLOBAL'

'join_buffer_size'            integer        'GLOBAL' |
                                             'SESSION'

'keep_files_on_create'        boolean        'GLOBAL' |
                                             'SESSION'

'key_buffer_size'             integer        'GLOBAL'

'key_cache_age_threshold'     integer        'GLOBAL'

'key_cache_block_size'        integer        'GLOBAL'

'key_cache_division_limit'    integer        'GLOBAL'

'keyring_aws_cmk_id'          string         'GLOBAL'

'keyring_aws_region'          enumeration    'GLOBAL'

'keyring_encrypted_file_data' filename       'GLOBAL'

'keyring_encrypted_file_password'            'GLOBAL'

'keyring_file_data'           filename       'GLOBAL'

'keyring_okv_conf_dir'        dirname        'GLOBAL'

'keyring_operations'          boolean        'GLOBAL'

'last_insert_id'              integer        'SESSION'

'lc_messages'                 string         'GLOBAL' |
                                             'SESSION'

'lc_time_names'               string         'GLOBAL' |
                                             'SESSION'

'local_infile'                boolean        'GLOBAL'

'lock_wait_timeout'           integer        'GLOBAL' |
                                             'SESSION'

'log_backward_compatible_user_definitions'boolean'GLOBAL'

'log_bin_trust_function_creators'boolean     'GLOBAL'

'log_builtin_as_identified_by_password'boolean'GLOBAL'

'log_error_verbosity'         integer        'GLOBAL'

'log_output'                  set            'GLOBAL'

'log_queries_not_using_indexes'boolean       'GLOBAL'

'log_slow_admin_statements'   boolean        'GLOBAL'

'log_slow_slave_statements'   boolean        'GLOBAL'

'log_statements_unsafe_for_binlog'boolean    'GLOBAL'

'log_syslog'                  boolean        'GLOBAL'

'log_syslog_facility'         string         'GLOBAL'

'log_syslog_include_pid'      boolean        'GLOBAL'

'log_syslog_tag'              string         'GLOBAL'

'log_throttle_queries_not_using_indexes'integer'GLOBAL'

'log_timestamps'              enumeration    'GLOBAL'

'log_warnings'                integer        'GLOBAL'

'long_query_time'             numeric        'GLOBAL' |
                                             'SESSION'

'low_priority_updates'        boolean        'GLOBAL' |
                                             'SESSION'

'master_info_repository'      string         'GLOBAL'

'master_verify_checksum'      boolean        'GLOBAL'

'max_allowed_packet'          integer        'GLOBAL' |
                                             'SESSION'

'max_binlog_cache_size'       integer        'GLOBAL'

'max_binlog_size'             integer        'GLOBAL'

'max_binlog_stmt_cache_size'  integer        'GLOBAL'

'max_connect_errors'          integer        'GLOBAL'

'max_connections'             integer        'GLOBAL'

'max_delayed_threads'         integer        'GLOBAL' |
                                             'SESSION'

'max_error_count'             integer        'GLOBAL' |
                                             'SESSION'

'max_execution_time'          integer        'GLOBAL' |
                                             'SESSION'

'max_heap_table_size'         integer        'GLOBAL' |
                                             'SESSION'

'max_insert_delayed_threads'  integer        'GLOBAL' |
                                             'SESSION'

'max_join_size'               integer        'GLOBAL' |
                                             'SESSION'

'max_length_for_sort_data'    integer        'GLOBAL' |
                                             'SESSION'

'max_points_in_geometry'      integer        'GLOBAL' |
                                             'SESSION'

'max_prepared_stmt_count'     integer        'GLOBAL'

'max_relay_log_size'          integer        'GLOBAL'

'max_seeks_for_key'           integer        'GLOBAL' |
                                             'SESSION'

'max_sort_length'             integer        'GLOBAL' |
                                             'SESSION'

'max_sp_recursion_depth'      integer        'GLOBAL' |
                                             'SESSION'

'max_statement_time'          integer        'GLOBAL' |
                                             'SESSION'

'max_tmp_tables'              integer        'GLOBAL' |
                                             'SESSION'

'max_user_connections'        integer        'GLOBAL' |
                                             'SESSION'

'max_write_lock_count'        integer        'GLOBAL'

'min_examined_row_limit'      integer        'GLOBAL' |
                                             'SESSION'

'multi_range_count'           integer        'GLOBAL' |
                                             'SESSION'

'myisam_data_pointer_size'    integer        'GLOBAL'

'myisam_max_sort_file_size'   integer        'GLOBAL'

'myisam_repair_threads'       integer        'GLOBAL' |
                                             'SESSION'

'myisam_sort_buffer_size'     integer        'GLOBAL' |
                                             'SESSION'

'myisam_stats_method'         enumeration    'GLOBAL' |
                                             'SESSION'

'myisam_use_mmap'             boolean        'GLOBAL'

'mysql_firewall_mode'         boolean        'GLOBAL'

'mysql_firewall_trace'        boolean        'GLOBAL'

'mysql_native_password_proxy_users'boolean   'GLOBAL'

'mysqlx-connect-timeout'      integer        'GLOBAL'

'mysqlx_connect_timeout'      integer        'GLOBAL'

'mysqlx-idle-worker-thread-timeout'integer   'GLOBAL'

'mysqlx_idle_worker_thread_timeout'integer   'GLOBAL'

'mysqlx-max-allowed-packet'   integer        'GLOBAL'

'mysqlx_max_allowed_packet'   integer        'GLOBAL'

'mysqlx-max-connections'      integer        'GLOBAL'

'mysqlx_max_connections'      integer        'GLOBAL'

'mysqlx-min-worker-threads'   integer        'GLOBAL'

'mysqlx_min_worker_threads'   integer        'GLOBAL'

'ndb-allow-copying-alter-table'boolean       'GLOBAL' |
                                             'SESSION'

'ndb_autoincrement_prefetch_sz'integer       'GLOBAL' |
                                             'SESSION'

'ndb_blob_read_batch_bytes'   integer        'GLOBAL' |
                                             'SESSION'

'ndb_blob_write_batch_bytes'  integer        'GLOBAL' |
                                             'SESSION'

'ndb_cache_check_time'        integer        'GLOBAL'

'ndb_clear_apply_status'      boolean        'GLOBAL'

'ndb_data_node_neighbour'     integer        'GLOBAL'

'ndb_default_column_format'   enumeration    'GLOBAL'

'ndb_default_column_format'   enumeration    'GLOBAL'

'ndb_deferred_constraints'    integer        'GLOBAL' |
                                             'SESSION'

'ndb_deferred_constraints'    integer        'GLOBAL' |
                                             'SESSION'

'ndb_distribution'            enumeration    'GLOBAL'

'ndb_distribution={KEYHASH|LINHASH}'enumeration'GLOBAL'

'ndb_eventbuffer_free_percent'integer        'GLOBAL'

'ndb_eventbuffer_max_alloc'   integer        'GLOBAL'

'ndb_extra_logging'           integer        'GLOBAL'

'ndb_force_send'              boolean        'GLOBAL' |
                                             'SESSION'

'ndb_fully_replicated'        boolean        'GLOBAL' |
                                             'SESSION'

'ndb_index_stat_enable'       boolean        'GLOBAL' |
                                             'SESSION'

'ndb_index_stat_option'       string         'GLOBAL' |
                                             'SESSION'

'ndb_join_pushdown'           boolean        'GLOBAL' |
                                             'SESSION'

'ndb_log_bin'                 boolean        'GLOBAL' |
                                             'SESSION'

'ndb_log_binlog_index'        boolean        'GLOBAL'

'ndb_log_empty_epochs'        boolean        'GLOBAL'

'ndb_log_empty_epochs'        boolean        'GLOBAL'

'ndb_log_empty_update'        boolean        'GLOBAL'

'ndb_log_empty_update'        boolean        'GLOBAL'

'ndb_log_exclusive_reads'     boolean        'GLOBAL' |
                                             'SESSION'

'ndb_log_exclusive_reads'     boolean        'GLOBAL' |
                                             'SESSION'

'ndb_log_update_minimal'      boolean        'GLOBAL'

'ndb_log_updated_only'        boolean        'GLOBAL'

'ndb_optimization_delay'      integer        'GLOBAL'

'ndb_read_backup'             boolean        'GLOBAL'

'ndb_recv_thread_cpu_mask'    bitmap         'GLOBAL'

'ndb_report_thresh_binlog_epoch_slip'integer 'GLOBAL'

'ndb_report_thresh_binlog_mem_usage'integer  'GLOBAL'

'ndb_show_foreign_key_mock_tables'boolean    'GLOBAL'

'ndb_slave_last_conflict_epoch'enumeration   'GLOBAL'

'ndb_table_no_logging'        boolean        'SESSION'

'ndb_table_temporary'         boolean        'SESSION'

'ndb_use_exact_count'         boolean        'GLOBAL' |
                                             'SESSION'

'ndb_use_transactions'        boolean        'GLOBAL' |
                                             'SESSION'

'ndbinfo_max_bytes'           integer        'GLOBAL' |
                                             'SESSION'

'ndbinfo_max_rows'            integer        'GLOBAL' |
                                             'SESSION'

'ndbinfo_offline'             boolean        'GLOBAL'

'ndbinfo_show_hidden'         boolean        'GLOBAL' |
                                             'SESSION'

'ndbinfo_table_prefix'        string         'GLOBAL' |
                                             'SESSION'

'net_buffer_length'           integer        'GLOBAL' |
                                             'SESSION'

'net_read_timeout'            integer        'GLOBAL' |
                                             'SESSION'

'net_retry_count'             integer        'GLOBAL' |
                                             'SESSION'

'net_write_timeout'           integer        'GLOBAL' |
                                             'SESSION'

'new'                         boolean        'GLOBAL' |
                                             'SESSION'

'offline_mode'                boolean        'GLOBAL'

'old_alter_table'             boolean        'GLOBAL' |
                                             'SESSION'

'old_passwords'               enumeration    'GLOBAL' |
                                             'SESSION'

'optimizer_prune_level'       boolean        'GLOBAL' |
                                             'SESSION'

'optimizer_search_depth'      integer        'GLOBAL' |
                                             'SESSION'

'optimizer_switch'            set            'GLOBAL' |
                                             'SESSION'

'optimizer_trace'             string         'GLOBAL' |
                                             'SESSION'

'optimizer_trace_features'    string         'GLOBAL' |
                                             'SESSION'

'optimizer_trace_limit'       integer        'GLOBAL' |
                                             'SESSION'

'optimizer_trace_max_mem_size'integer        'GLOBAL' |
                                             'SESSION'

'optimizer_trace_offset'      integer        'GLOBAL' |
                                             'SESSION'

'parser_max_mem_size'         integer        'GLOBAL' |
                                             'SESSION'

'preload_buffer_size'         integer        'GLOBAL' |
                                             'SESSION'

'profiling'                   boolean        'GLOBAL' |
                                             'SESSION'

'profiling_history_size'      integer        'GLOBAL' |
                                             'SESSION'

'pseudo_slave_mode'           integer        'SESSION'

'pseudo_thread_id'            integer        'SESSION'

'query_alloc_block_size'      integer        'GLOBAL' |
                                             'SESSION'

'query_cache_limit'           integer        'GLOBAL'

'query_cache_min_res_unit'    integer        'GLOBAL'

'query_cache_size'            integer        'GLOBAL'

'query_cache_type'            enumeration    'GLOBAL' |
                                             'SESSION'

'query_cache_wlock_invalidate'boolean        'GLOBAL' |
                                             'SESSION'

'query_prealloc_size'         integer        'GLOBAL' |
                                             'SESSION'

'rand_seed1'                  integer        'SESSION'

'rand_seed2'                  integer        'SESSION'

'range_alloc_block_size'      integer        'GLOBAL' |
                                             'SESSION'

'range_optimizer_max_mem_size'integer        'GLOBAL' |
                                             'SESSION'

'rbr_exec_mode'               enumeration    'SESSION'

'read_buffer_size'            integer        'GLOBAL' |
                                             'SESSION'

'read_only'                   boolean        'GLOBAL'

'read_rnd_buffer_size'        integer        'GLOBAL' |
                                             'SESSION'

'relay_log_info_repository'   string         'GLOBAL'

'relay_log_purge'             boolean        'GLOBAL'

'require_secure_transport'    boolean        'GLOBAL'

'rewriter_enabled'            boolean        'GLOBAL'

'rewriter_verbose'            integer        'GLOBAL'

'rpl_semi_sync_master_enabled'boolean        'GLOBAL'

'rpl_semi_sync_master_timeout'integer        'GLOBAL'

'rpl_semi_sync_master_trace_level'integer    'GLOBAL'

'rpl_semi_sync_master_wait_for_slave_count'integer'GLOBAL'

'rpl_semi_sync_master_wait_no_slave'boolean  'GLOBAL'

'rpl_semi_sync_master_wait_point'enumeration 'GLOBAL'

'rpl_semi_sync_slave_enabled' boolean        'GLOBAL'

'rpl_semi_sync_slave_trace_level'integer     'GLOBAL'

'rpl_stop_slave_timeout'      integer        'GLOBAL'

'secure_auth'                 boolean        'GLOBAL'

'server_id'                   integer        'GLOBAL'

'session_track_gtids'         enumeration    'GLOBAL' |
                                             'SESSION'

'session_track_schema'        boolean        'GLOBAL' |
                                             'SESSION'

'session_track_state_change'  boolean        'GLOBAL' |
                                             'SESSION'

'session_track_system_variables'string       'GLOBAL' |
                                             'SESSION'

'sha256_password_proxy_users' boolean        'GLOBAL'

'show_compatibility_56'       boolean        'GLOBAL'

'show_create_table_verbosity'                'GLOBAL' |
                                             'SESSION'

'show_old_temporals'          boolean        'GLOBAL' |
                                             'SESSION'

'slave_allow_batching'        boolean        'GLOBAL'

'slave_checkpoint_group=#'    integer        'GLOBAL'

'slave_checkpoint_period=#'   integer        'GLOBAL'

'slave_compressed_protocol'   boolean        'GLOBAL'

'slave_exec_mode'             enumeration    'GLOBAL'

'slave_max_allowed_packet'    integer        'GLOBAL'

'slave_net_timeout'           integer        'GLOBAL'

'slave_parallel_type'         enumeration    'GLOBAL'

'slave_parallel_workers'      integer        'GLOBAL'

'slave_pending_jobs_size_max' integer        'GLOBAL'

'slave_preserve_commit_order' boolean        'GLOBAL'

'slave_rows_search_algorithms=list'set       'GLOBAL'

'slave_sql_verify_checksum'   boolean        'GLOBAL'

'slave_transaction_retries'   integer        'GLOBAL'

'slow_launch_time'            integer        'GLOBAL'

'slow_query_log'              boolean        'GLOBAL'

'slow_query_log_file'         filename       'GLOBAL'

'sort_buffer_size'            integer        'GLOBAL' |
                                             'SESSION'

'sql_auto_is_null'            boolean        'GLOBAL' |
                                             'SESSION'

'sql_big_selects'             boolean        'GLOBAL' |
                                             'SESSION'

'sql_buffer_result'           boolean        'GLOBAL' |
                                             'SESSION'

'sql_log_bin'                 boolean        'SESSION'

'sql_log_off'                 boolean        'GLOBAL' |
                                             'SESSION'

'sql_mode'                    set            'GLOBAL' |
                                             'SESSION'

'sql_notes'                   boolean        'GLOBAL' |
                                             'SESSION'

'sql_quote_show_create'       boolean        'GLOBAL' |
                                             'SESSION'

'sql_safe_updates'            boolean        'GLOBAL' |
                                             'SESSION'

'sql_select_limit'            integer        'GLOBAL' |
                                             'SESSION'

'sql_slave_skip_counter'      integer        'GLOBAL'

'sql_warnings'                boolean        'GLOBAL' |
                                             'SESSION'

'storage_engine'              enumeration    'GLOBAL' |
                                             'SESSION'

'stored_program_cache'        integer        'GLOBAL'

'super_read_only'             boolean        'GLOBAL'

'sync_binlog'                 integer        'GLOBAL'

'sync_frm'                    boolean        'GLOBAL'

'sync_master_info'            integer        'GLOBAL'

'sync_relay_log'              integer        'GLOBAL'

'sync_relay_log_info'         integer        'GLOBAL'

'table_definition_cache'      integer        'GLOBAL'

'table_open_cache'            integer        'GLOBAL'

'thread_cache_size'           integer        'GLOBAL'

'thread_pool_high_priority_connection'integer'GLOBAL' |
                                             'SESSION'

'thread_pool_max_unused_threads'integer      'GLOBAL'

'thread_pool_prio_kickup_timer'integer       'GLOBAL' |
                                             'SESSION'

'thread_pool_stall_limit'     integer        'GLOBAL'

'time_zone'                   string         'GLOBAL' |
                                             'SESSION'

'timed_mutexes'               boolean        'GLOBAL'

'timestamp'                   numeric        'SESSION'

'tmp_table_size'              integer        'GLOBAL' |
                                             'SESSION'

'transaction_alloc_block_size'integer        'GLOBAL' |
                                             'SESSION'

'transaction_allow_batching'  boolean        'SESSION'

'tx_isolation'                enumeration    'GLOBAL' |
                                             'SESSION'

'transaction_prealloc_size'   integer        'GLOBAL' |
                                             'SESSION'

'tx_read_only'                boolean        'GLOBAL' |
                                             'SESSION'

'transaction_write_set_extraction'enumeration'GLOBAL' |
                                             'SESSION'

'tx_isolation'                enumeration    'GLOBAL' |
                                             'SESSION'

'tx_read_only'                boolean        'GLOBAL' |
                                             'SESSION'

'unique_checks'               boolean        'GLOBAL' |
                                             'SESSION'

'updatable_views_with_limit'  boolean        'GLOBAL' |
                                             'SESSION'

'validate_password_check_user_name'boolean   'GLOBAL'

'validate_password_dictionary_file'filename  'GLOBAL'

'validate_password_length'    integer        'GLOBAL'

'validate_password_mixed_case_count'integer  'GLOBAL'

'validate_password_number_count'integer      'GLOBAL'

'validate_password_policy'    enumeration    'GLOBAL'

'validate_password_special_char_count'integer'GLOBAL'

'version_tokens_session'      string         'GLOBAL' |
                                             'SESSION'

'wait_timeout'                integer        'GLOBAL' |
                                             'SESSION'

5.1.7 Server Status Variables
-----------------------------

The MySQL server maintains many status variables that provide
information about its operation.  You can view these variables and their
values by using the 'SHOW [GLOBAL | SESSION] STATUS' statement (see
show-status).  The optional 'GLOBAL' keyword aggregates the
values over all connections, and 'SESSION' shows the values for the
current connection.

     mysql> SHOW GLOBAL STATUS;
     +-----------------------------------+------------+
     | Variable_name                     | Value      |
     +-----------------------------------+------------+
     | Aborted_clients                   | 0          |
     | Aborted_connects                  | 0          |
     | Bytes_received                    | 155372598  |
     | Bytes_sent                        | 1176560426 |
     ...
     | Connections                       | 30023      |
     | Created_tmp_disk_tables           | 0          |
     | Created_tmp_files                 | 3          |
     | Created_tmp_tables                | 2          |
     ...
     | Threads_created                   | 217        |
     | Threads_running                   | 88         |
     | Uptime                            | 1389872    |
     +-----------------------------------+------------+

Several status variables provide statement counts.  To determine the
number of statements executed, use these relationships:

       SUM(Com_xxx) + Qcache_hits
     = Questions + statements executed within stored programs
     = Queries

Many status variables are reset to 0 by the 'FLUSH STATUS' statement.

The following table lists all available server status variables:

*Status Variable Summary*

Variable Name                 Variable       Variable
                              Type           Scope

'Aborted_clients'             integer        'GLOBAL'

'Aborted_connects'            integer        'GLOBAL'

'Audit_log_current_size'      integer        'GLOBAL'

'Audit_log_event_max_drop_size'integer       'GLOBAL'

'Audit_log_events'            integer        'GLOBAL'

'Audit_log_events_filtered'   integer        'GLOBAL'

'Audit_log_events_lost'       integer        'GLOBAL'

'Audit_log_events_written'    integer        'GLOBAL'

'Audit_log_total_size'        integer        'GLOBAL'

'Audit_log_write_waits'       integer        'GLOBAL'

'Binlog_cache_disk_use'       integer        'GLOBAL'

'Binlog_cache_use'            integer        'GLOBAL'

'Binlog_stmt_cache_disk_use'  integer        'GLOBAL'

'Binlog_stmt_cache_use'       integer        'GLOBAL'

'Bytes_received'              integer        'GLOBAL' |
                                             'SESSION'

'Bytes_sent'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_admin_commands'          integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_db'                integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_db_upgrade'        integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_event'             integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_function'          integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_procedure'         integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_server'            integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_table'             integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_tablespace'        integer        'GLOBAL' |
                                             'SESSION'

'Com_alter_user'              integer        'GLOBAL' |
                                             'SESSION'

'Com_analyze'                 integer        'GLOBAL' |
                                             'SESSION'

'Com_assign_to_keycache'      integer        'GLOBAL' |
                                             'SESSION'

'Com_begin'                   integer        'GLOBAL' |
                                             'SESSION'

'Com_binlog'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_call_procedure'          integer        'GLOBAL' |
                                             'SESSION'

'Com_change_db'               integer        'GLOBAL' |
                                             'SESSION'

'Com_change_master'           integer        'GLOBAL' |
                                             'SESSION'

'Com_change_repl_filter'      integer        'GLOBAL' |
                                             'SESSION'

'Com_check'                   integer        'GLOBAL' |
                                             'SESSION'

'Com_checksum'                integer        'GLOBAL' |
                                             'SESSION'

'Com_commit'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_create_db'               integer        'GLOBAL' |
                                             'SESSION'

'Com_create_event'            integer        'GLOBAL' |
                                             'SESSION'

'Com_create_function'         integer        'GLOBAL' |
                                             'SESSION'

'Com_create_index'            integer        'GLOBAL' |
                                             'SESSION'

'Com_create_procedure'        integer        'GLOBAL' |
                                             'SESSION'

'Com_create_server'           integer        'GLOBAL' |
                                             'SESSION'

'Com_create_table'            integer        'GLOBAL' |
                                             'SESSION'

'Com_create_trigger'          integer        'GLOBAL' |
                                             'SESSION'

'Com_create_udf'              integer        'GLOBAL' |
                                             'SESSION'

'Com_create_user'             integer        'GLOBAL' |
                                             'SESSION'

'Com_create_view'             integer        'GLOBAL' |
                                             'SESSION'

'Com_dealloc_sql'             integer        'GLOBAL' |
                                             'SESSION'

'Com_delete'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_delete_multi'            integer        'GLOBAL' |
                                             'SESSION'

'Com_do'                      integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_db'                 integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_event'              integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_function'           integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_index'              integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_procedure'          integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_server'             integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_table'              integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_trigger'            integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_user'               integer        'GLOBAL' |
                                             'SESSION'

'Com_drop_view'               integer        'GLOBAL' |
                                             'SESSION'

'Com_empty_query'             integer        'GLOBAL' |
                                             'SESSION'

'Com_execute_sql'             integer        'GLOBAL' |
                                             'SESSION'

'Com_explain_other'           integer        'GLOBAL' |
                                             'SESSION'

'Com_flush'                   integer        'GLOBAL' |
                                             'SESSION'

'Com_get_diagnostics'         integer        'GLOBAL' |
                                             'SESSION'

'Com_grant'                   integer        'GLOBAL' |
                                             'SESSION'

'Com_group_replication_start'                'GLOBAL'

'Com_group_replication_stop'                 'GLOBAL'

'Com_ha_close'                integer        'GLOBAL' |
                                             'SESSION'

'Com_ha_open'                 integer        'GLOBAL' |
                                             'SESSION'

'Com_ha_read'                 integer        'GLOBAL' |
                                             'SESSION'

'Com_help'                    integer        'GLOBAL' |
                                             'SESSION'

'Com_insert'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_insert_select'           integer        'GLOBAL' |
                                             'SESSION'

'Com_install_plugin'          integer        'GLOBAL' |
                                             'SESSION'

'Com_kill'                    integer        'GLOBAL' |
                                             'SESSION'

'Com_load'                    integer        'GLOBAL' |
                                             'SESSION'

'Com_lock_tables'             integer        'GLOBAL' |
                                             'SESSION'

'Com_optimize'                integer        'GLOBAL' |
                                             'SESSION'

'Com_preload_keys'            integer        'GLOBAL' |
                                             'SESSION'

'Com_prepare_sql'             integer        'GLOBAL' |
                                             'SESSION'

'Com_purge'                   integer        'GLOBAL' |
                                             'SESSION'

'Com_purge_before_date'       integer        'GLOBAL' |
                                             'SESSION'

'Com_release_savepoint'       integer        'GLOBAL' |
                                             'SESSION'

'Com_rename_table'            integer        'GLOBAL' |
                                             'SESSION'

'Com_rename_user'             integer        'GLOBAL' |
                                             'SESSION'

'Com_repair'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_replace'                 integer        'GLOBAL' |
                                             'SESSION'

'Com_replace_select'          integer        'GLOBAL' |
                                             'SESSION'

'Com_reset'                   integer        'GLOBAL' |
                                             'SESSION'

'Com_resignal'                integer        'GLOBAL' |
                                             'SESSION'

'Com_revoke'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_revoke_all'              integer        'GLOBAL' |
                                             'SESSION'

'Com_rollback'                integer        'GLOBAL' |
                                             'SESSION'

'Com_rollback_to_savepoint'   integer        'GLOBAL' |
                                             'SESSION'

'Com_savepoint'               integer        'GLOBAL' |
                                             'SESSION'

'Com_select'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_set_option'              integer        'GLOBAL' |
                                             'SESSION'

'Com_show_authors'            integer        'GLOBAL' |
                                             'SESSION'

'Com_show_binlog_events'      integer        'GLOBAL' |
                                             'SESSION'

'Com_show_binlogs'            integer        'GLOBAL' |
                                             'SESSION'

'Com_show_charsets'           integer        'GLOBAL' |
                                             'SESSION'

'Com_show_collations'         integer        'GLOBAL' |
                                             'SESSION'

'Com_show_contributors'       integer        'GLOBAL' |
                                             'SESSION'

'Com_show_create_db'          integer        'GLOBAL' |
                                             'SESSION'

'Com_show_create_event'       integer        'GLOBAL' |
                                             'SESSION'

'Com_show_create_func'        integer        'GLOBAL' |
                                             'SESSION'

'Com_show_create_proc'        integer        'GLOBAL' |
                                             'SESSION'

'Com_show_create_table'       integer        'GLOBAL' |
                                             'SESSION'

'Com_show_create_trigger'     integer        'GLOBAL' |
                                             'SESSION'

'Com_show_create_user'        integer        'GLOBAL' |
                                             'SESSION'

'Com_show_databases'          integer        'GLOBAL' |
                                             'SESSION'

'Com_show_engine_logs'        integer        'GLOBAL' |
                                             'SESSION'

'Com_show_engine_mutex'       integer        'GLOBAL' |
                                             'SESSION'

'Com_show_engine_status'      integer        'GLOBAL' |
                                             'SESSION'

'Com_show_errors'             integer        'GLOBAL' |
                                             'SESSION'

'Com_show_events'             integer        'GLOBAL' |
                                             'SESSION'

'Com_show_fields'             integer        'GLOBAL' |
                                             'SESSION'

'Com_show_function_code'      integer        'GLOBAL' |
                                             'SESSION'

'Com_show_function_status'    integer        'GLOBAL' |
                                             'SESSION'

'Com_show_grants'             integer        'GLOBAL' |
                                             'SESSION'

'Com_show_keys'               integer        'GLOBAL' |
                                             'SESSION'

'Com_show_master_status'      integer        'GLOBAL' |
                                             'SESSION'

'Com_show_ndb_status'         integer        'GLOBAL' |
                                             'SESSION'

'Com_show_new_master'         integer        'GLOBAL' |
                                             'SESSION'

'Com_show_open_tables'        integer        'GLOBAL' |
                                             'SESSION'

'Com_show_plugins'            integer        'GLOBAL' |
                                             'SESSION'

'Com_show_privileges'         integer        'GLOBAL' |
                                             'SESSION'

'Com_show_procedure_code'     integer        'GLOBAL' |
                                             'SESSION'

'Com_show_procedure_status'   integer        'GLOBAL' |
                                             'SESSION'

'Com_show_processlist'        integer        'GLOBAL' |
                                             'SESSION'

'Com_show_profile'            integer        'GLOBAL' |
                                             'SESSION'

'Com_show_profiles'           integer        'GLOBAL' |
                                             'SESSION'

'Com_show_relaylog_events'    integer        'GLOBAL' |
                                             'SESSION'

'Com_show_slave_hosts'        integer        'GLOBAL' |
                                             'SESSION'

'Com_show_slave_status'       integer        'GLOBAL' |
                                             'SESSION'

'Com_show_slave_status_nonblocking'integer   'GLOBAL' |
                                             'SESSION'

'Com_show_status'             integer        'GLOBAL' |
                                             'SESSION'

'Com_show_storage_engines'    integer        'GLOBAL' |
                                             'SESSION'

'Com_show_table_status'       integer        'GLOBAL' |
                                             'SESSION'

'Com_show_tables'             integer        'GLOBAL' |
                                             'SESSION'

'Com_show_triggers'           integer        'GLOBAL' |
                                             'SESSION'

'Com_show_variables'          integer        'GLOBAL' |
                                             'SESSION'

'Com_show_warnings'           integer        'GLOBAL' |
                                             'SESSION'

'Com_shutdown'                integer        'GLOBAL' |
                                             'SESSION'

'Com_signal'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_slave_start'             integer        'GLOBAL' |
                                             'SESSION'

'Com_slave_stop'              integer        'GLOBAL' |
                                             'SESSION'

'Com_stmt_close'              integer        'GLOBAL' |
                                             'SESSION'

'Com_stmt_execute'            integer        'GLOBAL' |
                                             'SESSION'

'Com_stmt_fetch'              integer        'GLOBAL' |
                                             'SESSION'

'Com_stmt_prepare'            integer        'GLOBAL' |
                                             'SESSION'

'Com_stmt_reprepare'          integer        'GLOBAL' |
                                             'SESSION'

'Com_stmt_reset'              integer        'GLOBAL' |
                                             'SESSION'

'Com_stmt_send_long_data'     integer        'GLOBAL' |
                                             'SESSION'

'Com_truncate'                integer        'GLOBAL' |
                                             'SESSION'

'Com_uninstall_plugin'        integer        'GLOBAL' |
                                             'SESSION'

'Com_unlock_tables'           integer        'GLOBAL' |
                                             'SESSION'

'Com_update'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_update_multi'            integer        'GLOBAL' |
                                             'SESSION'

'Com_xa_commit'               integer        'GLOBAL' |
                                             'SESSION'

'Com_xa_end'                  integer        'GLOBAL' |
                                             'SESSION'

'Com_xa_prepare'              integer        'GLOBAL' |
                                             'SESSION'

'Com_xa_recover'              integer        'GLOBAL' |
                                             'SESSION'

'Com_xa_rollback'             integer        'GLOBAL' |
                                             'SESSION'

'Com_xa_start'                integer        'GLOBAL' |
                                             'SESSION'

'Compression'                 integer        'SESSION'

'Connection_control_delay_generated'         'GLOBAL'

'Connection_errors_accept'    integer        'GLOBAL'

'Connection_errors_internal'  integer        'GLOBAL'

'Connection_errors_max_connections'integer   'GLOBAL'

'Connection_errors_peer_address'integer      'GLOBAL'

'Connection_errors_select'    integer        'GLOBAL'

'Connection_errors_tcpwrap'   integer        'GLOBAL'

'Connections'                 integer        'GLOBAL'

'Created_tmp_disk_tables'     integer        'GLOBAL' |
                                             'SESSION'

'Created_tmp_files'           integer        'GLOBAL'

'Created_tmp_tables'          integer        'GLOBAL' |
                                             'SESSION'

'Delayed_errors'              integer        'GLOBAL'

'Delayed_insert_threads'      integer        'GLOBAL'

'Delayed_writes'              integer        'GLOBAL'

'Firewall_access_denied'      integer        'GLOBAL'

'Firewall_access_granted'     integer        'GLOBAL'

'Firewall_cached_entries'     integer        'GLOBAL'

'Flush_commands'              integer        'GLOBAL'

'Handler_commit'              integer        'GLOBAL' |
                                             'SESSION'

'Handler_delete'              integer        'GLOBAL' |
                                             'SESSION'

'Handler_discover'            integer        'GLOBAL' |
                                             'SESSION'

'Handler_external_lock'       integer        'GLOBAL' |
                                             'SESSION'

'Handler_mrr_init'            integer        'GLOBAL' |
                                             'SESSION'

'Handler_prepare'             integer        'GLOBAL' |
                                             'SESSION'

'Handler_read_first'          integer        'GLOBAL' |
                                             'SESSION'

'Handler_read_key'            integer        'GLOBAL' |
                                             'SESSION'

'Handler_read_last'           integer        'GLOBAL' |
                                             'SESSION'

'Handler_read_next'           integer        'GLOBAL' |
                                             'SESSION'

'Handler_read_prev'           integer        'GLOBAL' |
                                             'SESSION'

'Handler_read_rnd'            integer        'GLOBAL' |
                                             'SESSION'

'Handler_read_rnd_next'       integer        'GLOBAL' |
                                             'SESSION'

'Handler_rollback'            integer        'GLOBAL' |
                                             'SESSION'

'Handler_savepoint'           integer        'GLOBAL' |
                                             'SESSION'

'Handler_savepoint_rollback'  integer        'GLOBAL' |
                                             'SESSION'

'Handler_update'              integer        'GLOBAL' |
                                             'SESSION'

'Handler_write'               integer        'GLOBAL' |
                                             'SESSION'

'Innodb_available_undo_logs'  integer        'GLOBAL'

'Innodb_buffer_pool_bytes_data'integer       'GLOBAL'

'Innodb_buffer_pool_bytes_dirty'integer      'GLOBAL'

'Innodb_buffer_pool_dump_status'string       'GLOBAL'

'Innodb_buffer_pool_load_status'string       'GLOBAL'

'Innodb_buffer_pool_pages_data'integer       'GLOBAL'

'Innodb_buffer_pool_pages_dirty'integer      'GLOBAL'

'Innodb_buffer_pool_pages_flushed'integer    'GLOBAL'

'Innodb_buffer_pool_pages_free'integer       'GLOBAL'

'Innodb_buffer_pool_pages_latched'integer    'GLOBAL'

'Innodb_buffer_pool_pages_misc'integer       'GLOBAL'

'Innodb_buffer_pool_pages_total'integer      'GLOBAL'

'Innodb_buffer_pool_read_ahead'integer       'GLOBAL'

'Innodb_buffer_pool_read_ahead_evicted'integer'GLOBAL'

'Innodb_buffer_pool_read_ahead_rnd'integer   'GLOBAL'

'Innodb_buffer_pool_read_requests'integer    'GLOBAL'

'Innodb_buffer_pool_reads'    integer        'GLOBAL'

'Innodb_buffer_pool_resize_status'string     'GLOBAL'

'Innodb_buffer_pool_wait_free'integer        'GLOBAL'

'Innodb_buffer_pool_write_requests'integer   'GLOBAL'

'Innodb_data_fsyncs'          integer        'GLOBAL'

'Innodb_data_pending_fsyncs'  integer        'GLOBAL'

'Innodb_data_pending_reads'   integer        'GLOBAL'

'Innodb_data_pending_writes'  integer        'GLOBAL'

'Innodb_data_read'            integer        'GLOBAL'

'Innodb_data_reads'           integer        'GLOBAL'

'Innodb_data_writes'          integer        'GLOBAL'

'Innodb_data_written'         integer        'GLOBAL'

'Innodb_dblwr_pages_written'  integer        'GLOBAL'

'Innodb_dblwr_writes'         integer        'GLOBAL'

'Innodb_have_atomic_builtins' integer        'GLOBAL'

'Innodb_log_waits'            integer        'GLOBAL'

'Innodb_log_write_requests'   integer        'GLOBAL'

'Innodb_log_writes'           integer        'GLOBAL'

'Innodb_num_open_files'       integer        'GLOBAL'

'Innodb_os_log_fsyncs'        integer        'GLOBAL'

'Innodb_os_log_pending_fsyncs'integer        'GLOBAL'

'Innodb_os_log_pending_writes'integer        'GLOBAL'

'Innodb_os_log_written'       integer        'GLOBAL'

'Innodb_page_size'            integer        'GLOBAL'

'Innodb_pages_created'        integer        'GLOBAL'

'Innodb_pages_read'           integer        'GLOBAL'

'Innodb_pages_written'        integer        'GLOBAL'

'Innodb_row_lock_current_waits'integer       'GLOBAL'

'Innodb_row_lock_time'        integer        'GLOBAL'

'Innodb_row_lock_time_avg'    integer        'GLOBAL'

'Innodb_row_lock_time_max'    integer        'GLOBAL'

'Innodb_row_lock_waits'       integer        'GLOBAL'

'Innodb_rows_deleted'         integer        'GLOBAL'

'Innodb_rows_inserted'        integer        'GLOBAL'

'Innodb_rows_read'            integer        'GLOBAL'

'Innodb_rows_updated'         integer        'GLOBAL'

'Innodb_truncated_status_writes'integer      'GLOBAL'

'Key_blocks_not_flushed'      integer        'GLOBAL'

'Key_blocks_unused'           integer        'GLOBAL'

'Key_blocks_used'             integer        'GLOBAL'

'Key_read_requests'           integer        'GLOBAL'

'Key_reads'                   integer        'GLOBAL'

'Key_write_requests'          integer        'GLOBAL'

'Key_writes'                  integer        'GLOBAL'

'Last_query_cost'             numeric        'SESSION'

'Last_query_partial_plans'    integer        'SESSION'

'Locked_connects'             integer        'GLOBAL'

'Max_execution_time_exceeded' integer        'GLOBAL' |
                                             'SESSION'

'Max_execution_time_set'      integer        'GLOBAL' |
                                             'SESSION'

'Max_execution_time_set_failed'integer       'GLOBAL' |
                                             'SESSION'

'Max_statement_time_exceeded' integer        'GLOBAL' |
                                             'SESSION'

'Max_statement_time_set'      integer        'GLOBAL' |
                                             'SESSION'

'Max_statement_time_set_failed'integer       'GLOBAL' |
                                             'SESSION'

'Max_used_connections'        integer        'GLOBAL'

'Max_used_connections_time'   datetime       'GLOBAL'

'mecab_charset'               string         'GLOBAL'

'Mysqlx_aborted_clients'      integer        'GLOBAL'

'Mysqlx_address'              string         'GLOBAL'

'Mysqlx_bytes_received'       integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_bytes_sent'           integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_connection_accept_errors'integer     'GLOBAL' |
                                             'SESSION'

'Mysqlx_connection_errors'    integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_connections_accepted' integer        'GLOBAL'

'Mysqlx_connections_closed'   integer        'GLOBAL'

'Mysqlx_connections_rejected' integer        'GLOBAL'

'Mysqlx_crud_create_view'     integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_crud_delete'          integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_crud_drop_view'       integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_crud_find'            integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_crud_insert'          integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_crud_modify_view'     integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_crud_update'          integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_errors_sent'          integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_errors_unknown_message_type'integer  'GLOBAL' |
                                             'SESSION'

'Mysqlx_expect_close'         integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_expect_open'          integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_init_error'           integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_notice_other_sent'    integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_notice_warning_sent'  integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_port'                 string         'GLOBAL'

'Mysqlx_rows_sent'            integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_sessions'             integer        'GLOBAL'

'Mysqlx_sessions_accepted'    integer        'GLOBAL'

'Mysqlx_sessions_closed'      integer        'GLOBAL'

'Mysqlx_sessions_fatal_error' integer        'GLOBAL'

'Mysqlx_sessions_killed'      integer        'GLOBAL'

'Mysqlx_sessions_rejected'    integer        'GLOBAL'

'Mysqlx_socket'               string         'GLOBAL'

'Mysqlx_ssl_accept_renegotiates'integer      'GLOBAL'

'Mysqlx_ssl_accepts'          integer        'GLOBAL'

'Mysqlx_ssl_active'           integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_ssl_cipher'           integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_ssl_cipher_list'      integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_ssl_ctx_verify_depth' integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_ssl_ctx_verify_mode'  integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_ssl_finished_accepts' integer        'GLOBAL'

'Mysqlx_ssl_server_not_after' integer        'GLOBAL'

'Mysqlx_ssl_server_not_before'integer        'GLOBAL'

'Mysqlx_ssl_verify_depth'     integer        'GLOBAL'

'Mysqlx_ssl_verify_mode'      integer        'GLOBAL'

'Mysqlx_ssl_version'          integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_create_collection'integer       'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_create_collection_index'integer 'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_disable_notices' integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_drop_collection' integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_drop_collection_index'integer   'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_enable_notices'  integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_ensure_collection'string        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_execute_mysqlx'  integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_execute_sql'     integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_execute_xplugin' integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_kill_client'     integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_list_clients'    integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_list_notices'    integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_list_objects'    integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_stmt_ping'            integer        'GLOBAL' |
                                             'SESSION'

'Mysqlx_worker_threads'       integer        'GLOBAL'

'Mysqlx_worker_threads_active'integer        'GLOBAL'

'Ndb_api_bytes_received_count'integer        'GLOBAL'

'Ndb_api_bytes_received_count_session'integer'SESSION'

'Ndb_api_bytes_received_count_slave'integer  'GLOBAL'

'Ndb_api_bytes_sent_count'    integer        'GLOBAL'

'Ndb_api_bytes_sent_count_slave'integer      'GLOBAL'

'Ndb_api_event_bytes_count_injector'integer  'GLOBAL'

'Ndb_api_event_data_count_injector'integer   'GLOBAL'

'Ndb_api_event_nondata_count_injector'integer'GLOBAL'

'Ndb_api_pk_op_count'         integer        'GLOBAL'

'Ndb_api_pk_op_count_session' integer        'SESSION'

'Ndb_api_pk_op_count_slave'   integer        'GLOBAL'

'Ndb_api_pruned_scan_count'   integer        'GLOBAL'

'Ndb_api_pruned_scan_count_session'integer   'SESSION'

'Ndb_api_range_scan_count_slave'integer      'GLOBAL'

'Ndb_api_read_row_count'      integer        'GLOBAL'

'Ndb_api_read_row_count_session'integer      'SESSION'

'Ndb_api_scan_batch_count_slave'integer      'GLOBAL'

'Ndb_api_table_scan_count'    integer        'GLOBAL'

'Ndb_api_table_scan_count_session'integer    'SESSION'

'Ndb_api_trans_abort_count'   integer        'GLOBAL'

'Ndb_api_trans_abort_count_session'integer   'SESSION'

'Ndb_api_trans_abort_count_slave'integer     'GLOBAL'

'Ndb_api_trans_close_count'   integer        'GLOBAL'

'Ndb_api_trans_close_count_session'integer   'SESSION'

'Ndb_api_trans_close_count_slave'integer     'GLOBAL'

'Ndb_api_trans_commit_count'  integer        'GLOBAL'

'Ndb_api_trans_commit_count_session'integer  'SESSION'

'Ndb_api_trans_commit_count_slave'integer    'GLOBAL'

'Ndb_api_trans_local_read_row_count_slave'integer'GLOBAL'

'Ndb_api_trans_start_count'   integer        'GLOBAL'

'Ndb_api_trans_start_count_session'integer   'SESSION'

'Ndb_api_trans_start_count_slave'integer     'GLOBAL'

'Ndb_api_uk_op_count'         integer        'GLOBAL'

'Ndb_api_uk_op_count_slave'   integer        'GLOBAL'

'Ndb_api_wait_exec_complete_count'integer    'GLOBAL'

'Ndb_api_wait_exec_complete_count_session'integer'SESSION'

'Ndb_api_wait_exec_complete_count_slave'integer'GLOBAL'

'Ndb_api_wait_meta_request_count'integer     'GLOBAL'

'Ndb_api_wait_meta_request_count_session'integer'SESSION'

'Ndb_api_wait_nanos_count'    integer        'GLOBAL'

'Ndb_api_wait_nanos_count_session'integer    'SESSION'

'Ndb_api_wait_nanos_count_slave'integer      'GLOBAL'

'Ndb_api_wait_scan_result_count'integer      'GLOBAL'

'Ndb_api_wait_scan_result_count_session'integer'SESSION'

'Ndb_api_wait_scan_result_count_slave'integer'GLOBAL'

'Ndb_cluster_node_id'         integer        'GLOBAL' |
                                             'SESSION'

'Ndb_config_from_host'        integer        'GLOBAL' |
                                             'SESSION'

'Ndb_config_from_port'        integer        'GLOBAL' |
                                             'SESSION'

'Ndb_conflict_fn_epoch_trans' integer        'GLOBAL'

'Ndb_conflict_fn_max'         integer        'GLOBAL'

'Ndb_conflict_fn_old'         integer        'GLOBAL'

'Ndb_conflict_trans_detect_iter_count'integer'GLOBAL'

'Ndb_conflict_trans_row_reject_count'integer 'GLOBAL'

'Ndb_last_commit_epoch_server'integer        'GLOBAL'

'Ndb_last_commit_epoch_session'integer       'SESSION'

'Ndb_cluster_node_id'         integer        'GLOBAL'

'Ndb_number_of_data_nodes'    integer        'GLOBAL'

'Ndb_pushed_queries_defined'  integer        'GLOBAL'

'Ndb_pushed_queries_executed' integer        'GLOBAL'

'Ndb_scan_count'              integer        'GLOBAL'

'Not_flushed_delayed_rows'    integer        'GLOBAL'

'Ongoing_anonymous_gtid_violating_transaction_count'integer'GLOBAL'

'Ongoing_anonymous_transaction_count'integer 'GLOBAL'

'Ongoing_automatic_gtid_violating_transaction_count'integer'GLOBAL'

'Open_files'                  integer        'GLOBAL'

'Open_streams'                integer        'GLOBAL'

'Open_table_definitions'      integer        'GLOBAL'

'Open_tables'                 integer        'GLOBAL' |
                                             'SESSION'

'Opened_files'                integer        'GLOBAL'

'Opened_table_definitions'    integer        'GLOBAL' |
                                             'SESSION'

'Opened_tables'               integer        'GLOBAL' |
                                             'SESSION'

'Performance_schema_accounts_lost'integer    'GLOBAL'

'Performance_schema_cond_classes_lost'integer'GLOBAL'

'Performance_schema_cond_instances_lost'integer'GLOBAL'

'Performance_schema_digest_lost'integer      'GLOBAL'

'Performance_schema_file_classes_lost'integer'GLOBAL'

'Performance_schema_file_handles_lost'integer'GLOBAL'

'Performance_schema_file_instances_lost'integer'GLOBAL'

'Performance_schema_hosts_lost'integer       'GLOBAL'

'Performance_schema_index_stat_lost'integer  'GLOBAL'

'Performance_schema_locker_lost'integer      'GLOBAL'

'Performance_schema_memory_classes_lost'integer'GLOBAL'

'Performance_schema_metadata_lock_lost'integer'GLOBAL'

'Performance_schema_mutex_classes_lost'integer'GLOBAL'

'Performance_schema_mutex_instances_lost'integer'GLOBAL'

'Performance_schema_nested_statement_lost'integer'GLOBAL'

'Performance_schema_prepared_statements_lost'integer'GLOBAL'

'Performance_schema_program_lost'integer     'GLOBAL'

'Performance_schema_rwlock_classes_lost'integer'GLOBAL'

'Performance_schema_rwlock_instances_lost'integer'GLOBAL'

'Performance_schema_session_connect_attrs_lost'integer'GLOBAL'

'Performance_schema_socket_classes_lost'integer'GLOBAL'

'Performance_schema_socket_instances_lost'integer'GLOBAL'

'Performance_schema_stage_classes_lost'integer'GLOBAL'

'Performance_schema_statement_classes_lost'integer'GLOBAL'

'Performance_schema_table_handles_lost'integer'GLOBAL'

'Performance_schema_table_instances_lost'integer'GLOBAL'

'Performance_schema_table_lock_stat_lost'integer'GLOBAL'

'Performance_schema_thread_classes_lost'integer'GLOBAL'

'Performance_schema_thread_instances_lost'integer'GLOBAL'

'Performance_schema_users_lost'integer       'GLOBAL'

'Prepared_stmt_count'         integer        'GLOBAL'

'Qcache_free_blocks'          integer        'GLOBAL'

'Qcache_free_memory'          integer        'GLOBAL'

'Qcache_hits'                 integer        'GLOBAL'

'Qcache_inserts'              integer        'GLOBAL'

'Qcache_lowmem_prunes'        integer        'GLOBAL'

'Qcache_not_cached'           integer        'GLOBAL'

'Qcache_queries_in_cache'     integer        'GLOBAL'

'Qcache_total_blocks'         integer        'GLOBAL'

'Queries'                     integer        'GLOBAL' |
                                             'SESSION'

'Questions'                   integer        'GLOBAL' |
                                             'SESSION'

'Rewriter_number_loaded_rules'integer        'GLOBAL'

'Rewriter_number_reloads'     integer        'GLOBAL'

'Rewriter_number_rewritten_queries'integer   'GLOBAL'

'Rewriter_reload_error'       boolean        'GLOBAL'

'Rpl_semi_sync_master_clients'integer        'GLOBAL'

'Rpl_semi_sync_master_net_avg_wait_time'integer'GLOBAL'

'Rpl_semi_sync_master_net_wait_time'integer  'GLOBAL'

'Rpl_semi_sync_master_net_waits'integer      'GLOBAL'

'Rpl_semi_sync_master_no_times'integer       'GLOBAL'

'Rpl_semi_sync_master_no_tx'  integer        'GLOBAL'

'Rpl_semi_sync_master_status' boolean        'GLOBAL'

'Rpl_semi_sync_master_timefunc_failures'integer'GLOBAL'

'Rpl_semi_sync_master_tx_avg_wait_time'integer'GLOBAL'

'Rpl_semi_sync_master_tx_wait_time'integer   'GLOBAL'

'Rpl_semi_sync_master_tx_waits'integer       'GLOBAL'

'Rpl_semi_sync_master_wait_pos_backtraverse'integer'GLOBAL'

'Rpl_semi_sync_master_wait_sessions'integer  'GLOBAL'

'Rpl_semi_sync_master_yes_tx' integer        'GLOBAL'

'Rpl_semi_sync_slave_status'  boolean        'GLOBAL'

'Rsa_public_key'              string         'GLOBAL'

'Select_full_join'            integer        'GLOBAL' |
                                             'SESSION'

'Select_full_range_join'      integer        'GLOBAL' |
                                             'SESSION'

'Select_range'                integer        'GLOBAL' |
                                             'SESSION'

'Select_range_check'          integer        'GLOBAL' |
                                             'SESSION'

'Select_scan'                 integer        'GLOBAL' |
                                             'SESSION'

'Slave_heartbeat_period'      numeric        'GLOBAL'

'Slave_last_heartbeat'                       'GLOBAL'

'Slave_open_temp_tables'      integer        'GLOBAL'

'Slave_received_heartbeats'                  'GLOBAL'

'Slave_retried_transactions'  integer        'GLOBAL'

'Slave_rows_last_search_algorithm_used'string'GLOBAL'

'Slave_running'               boolean        'GLOBAL'

'Slow_launch_threads'         integer        'GLOBAL' |
                                             'SESSION'

'Slow_queries'                integer        'GLOBAL' |
                                             'SESSION'

'Sort_merge_passes'           integer        'GLOBAL' |
                                             'SESSION'

'Sort_range'                  integer        'GLOBAL' |
                                             'SESSION'

'Sort_rows'                   integer        'GLOBAL' |
                                             'SESSION'

'Sort_scan'                   integer        'GLOBAL' |
                                             'SESSION'

'Ssl_accept_renegotiates'     integer        'GLOBAL'

'Ssl_accepts'                 integer        'GLOBAL'

'Ssl_callback_cache_hits'     integer        'GLOBAL'

'Ssl_cipher'                  string         'GLOBAL' |
                                             'SESSION'

'Ssl_cipher_list'             string         'GLOBAL' |
                                             'SESSION'

'Ssl_client_connects'         integer        'GLOBAL'

'Ssl_connect_renegotiates'    integer        'GLOBAL'

'Ssl_ctx_verify_depth'        integer        'GLOBAL'

'Ssl_ctx_verify_mode'         integer        'GLOBAL'

'Ssl_default_timeout'         integer        'GLOBAL' |
                                             'SESSION'

'Ssl_finished_accepts'        integer        'GLOBAL'

'Ssl_finished_connects'       integer        'GLOBAL'

'Ssl_server_not_after'        integer        'GLOBAL' |
                                             'SESSION'

'Ssl_server_not_before'       integer        'GLOBAL' |
                                             'SESSION'

'Ssl_session_cache_hits'      integer        'GLOBAL'

'Ssl_session_cache_misses'    integer        'GLOBAL'

'Ssl_session_cache_mode'      string         'GLOBAL'

'Ssl_session_cache_overflows' integer        'GLOBAL'

'Ssl_session_cache_size'      integer        'GLOBAL'

'Ssl_session_cache_timeouts'  integer        'GLOBAL'

'Ssl_sessions_reused'         integer        'GLOBAL' |
                                             'SESSION'

'Ssl_used_session_cache_entries'integer      'GLOBAL'

'Ssl_verify_depth'            integer        'GLOBAL' |
                                             'SESSION'

'Ssl_verify_mode'             integer        'GLOBAL' |
                                             'SESSION'

'Ssl_version'                 string         'GLOBAL' |
                                             'SESSION'

'Table_locks_immediate'       integer        'GLOBAL'

'Table_locks_waited'          integer        'GLOBAL'

'Table_open_cache_hits'       integer        'GLOBAL' |
                                             'SESSION'

'Table_open_cache_misses'     integer        'GLOBAL' |
                                             'SESSION'

'Table_open_cache_overflows'  integer        'GLOBAL' |
                                             'SESSION'

'Tc_log_max_pages_used'       integer        'GLOBAL'

'Tc_log_page_size'            integer        'GLOBAL'

'Tc_log_page_waits'           integer        'GLOBAL'

'Threads_cached'              integer        'GLOBAL'

'Threads_connected'           integer        'GLOBAL'

'Threads_created'             integer        'GLOBAL'

'Threads_running'             integer        'GLOBAL'

'Uptime'                      integer        'GLOBAL'

'Uptime_since_flush_status'   integer        'GLOBAL'

'validate_password_dictionary_file_last_parsed'datetime'GLOBAL'

'validate_password_dictionary_file_words_count'integer'GLOBAL'

The status variables have the meanings shown in the following list.  For
meanings of status variables specific to NDB Cluster, see
mysql-cluster-status-variables.

   * 'Aborted_clients'

     The number of connections that were aborted because the client died
     without closing the connection properly.  See
     communication-errors.

   * 'Aborted_connects'

     The number of failed attempts to connect to the MySQL server.  See
     communication-errors.

     For additional connection-related information, check the
     'Connection_errors_XXX' status variables and the
     'host_cache' table.

     As of MySQL 5.7.3, 'Aborted_connects' is not visible in the
     embedded server because for that server it is not updated and is
     not meaningful.

   * 'Binlog_cache_disk_use'

     The number of transactions that used the temporary binary log cache
     but that exceeded the value of 'binlog_cache_size' and used a
     temporary file to store statements from the transaction.

     The number of nontransactional statements that caused the binary
     log transaction cache to be written to disk is tracked separately
     in the 'Binlog_stmt_cache_disk_use' status variable.

   * 'Binlog_cache_use'

     The number of transactions that used the binary log cache.

   * 'Binlog_stmt_cache_disk_use'

     The number of nontransaction statements that used the binary log
     statement cache but that exceeded the value of
     'binlog_stmt_cache_size' and used a temporary file to store those
     statements.

   * 'Binlog_stmt_cache_use'

     The number of nontransactional statements that used the binary log
     statement cache.

   * 'Bytes_received'

     The number of bytes received from all clients.

   * 'Bytes_sent'

     The number of bytes sent to all clients.

   * 'Com_XXX'

     The 'Com_XXX' statement counter variables indicate the number of
     times each XXX statement has been executed.  There is one status
     variable for each type of statement.  For example, 'Com_delete' and
     'Com_update' count 'DELETE' and 'UPDATE'
     statements, respectively.  'Com_delete_multi' and
     'Com_update_multi' are similar but apply to 'DELETE'.
     and 'UPDATE' statements that use multiple-table
     syntax.

     If a query result is returned from query cache, the server
     increments the 'Qcache_hits' status variable, not 'Com_select'.
     See query-cache-status-and-maintenance.

     The discussion at the beginning of this section indicates how to
     relate these statement-counting status variables to other such
     variables.

     All of the 'Com_stmt_XXX' variables are increased even if a
     prepared statement argument is unknown or an error occurred during
     execution.  In other words, their values correspond to the number
     of requests issued, not to the number of requests successfully
     completed.

     The 'Com_stmt_XXX' status variables are as follows:

        * 'Com_stmt_prepare'

        * 'Com_stmt_execute'

        * 'Com_stmt_fetch'

        * 'Com_stmt_send_long_data'

        * 'Com_stmt_reset'

        * 'Com_stmt_close'

     Those variables stand for prepared statement commands.  Their names
     refer to the 'COM_XXX' command set used in the network layer.  In
     other words, their values increase whenever prepared statement API
     calls such as 'mysql_stmt_prepare()', 'mysql_stmt_execute()', and
     so forth are executed.  However, 'Com_stmt_prepare',
     'Com_stmt_execute' and 'Com_stmt_close' also increase for
     'PREPARE', 'EXECUTE', or 'DEALLOCATE PREPARE',
     respectively.  Additionally, the
     values of the older statement counter variables 'Com_prepare_sql',
     'Com_execute_sql', and 'Com_dealloc_sql' increase for the
     'PREPARE', 'EXECUTE', and 'DEALLOCATE PREPARE'
     statements.  'Com_stmt_fetch' stands
     for the total number of network round-trips issued when fetching
     from cursors.

     'Com_stmt_reprepare' indicates the number of times statements were
     automatically reprepared by the server after metadata changes to
     tables or views referred to by the statement.  A reprepare
     operation increments 'Com_stmt_reprepare', and also
     'Com_stmt_prepare'.

     'Com_explain_other' indicates the number of 'EXPLAIN FOR CONNECTION'
     statements executed.  See
     explain-for-connection.  It was introduced in MySQL 5.7.2.

     'Com_change_repl_filter' indicates the number of 'CHANGE REPLICATION FILTER'
     statements
     executed.  It was introduced in MySQL 5.7.3.

   * 'Compression'

     Whether the client connection uses compression in the client/server
     protocol.

   * 'Connection_errors_XXX'

     These variables provide information about errors that occur during
     the client connection process.  They are global only and represent
     error counts aggregated across connections from all hosts.  These
     variables track errors not accounted for by the host cache (see
     host-cache), such as errors that are not associated with
     TCP connections, occur very early in the connection process (even
     before an IP address is known), or are not specific to any
     particular IP address (such as out-of-memory conditions).

     As of MySQL 5.7.3, the 'Connection_errors_XXX' status variables are
     not visible in the embedded server because for that server they are
     not updated and are not meaningful.

        * 'Connection_errors_accept'

          The number of errors that occurred during calls to 'accept()'
          on the listening port.

        * 'Connection_errors_internal'

          The number of connections refused due to internal errors in
          the server, such as failure to start a new thread or an
          out-of-memory condition.

        * 'Connection_errors_max_connections'

          The number of connections refused because the server
          'max_connections' limit was reached.

        * 'Connection_errors_peer_address'

          The number of errors that occurred while searching for
          connecting client IP addresses.

        * 'Connection_errors_select'

          The number of errors that occurred during calls to 'select()'
          or 'poll()' on the listening port.  (Failure of this operation
          does not necessarily means a client connection was rejected.)

        * 'Connection_errors_tcpwrap'

          The number of connections refused by the 'libwrap' library.

   * 'Connections'

     The number of connection attempts (successful or not) to the MySQL
     server.

   * 'Created_tmp_disk_tables'

     The number of internal on-disk temporary tables created by the
     server while executing statements.

     If an internal temporary table is created initially as an in-memory
     table but becomes too large, MySQL automatically converts it to an
     on-disk table.  The maximum size for in-memory temporary tables is
     the minimum of the 'tmp_table_size' and 'max_heap_table_size'
     values.  If 'Created_tmp_disk_tables' is large, you may want to
     increase the 'tmp_table_size' or 'max_heap_table_size' value to
     lessen the likelihood that internal temporary tables in memory will
     be converted to on-disk tables.

     You can compare the number of internal on-disk temporary tables
     created to the total number of internal temporary tables created by
     comparing the values of the 'Created_tmp_disk_tables' and
     'Created_tmp_tables' variables.

     See also internal-temporary-tables.

   * 'Created_tmp_files'

     How many temporary files 'mysqld' has created.

   * 'Created_tmp_tables'

     The number of internal temporary tables created by the server while
     executing statements.

     You can compare the number of internal on-disk temporary tables
     created to the total number of internal temporary tables created by
     comparing the values of the 'Created_tmp_disk_tables' and
     'Created_tmp_tables' variables.

     See also internal-temporary-tables.

     Each invocation of the 'SHOW STATUS' statement
     uses an internal temporary table and increments the global
     'Created_tmp_tables' value.

   * 'Delayed_errors'

     This status variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   * 'Delayed_insert_threads'

     This status variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   * 'Delayed_writes'

     This status variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   * 'Flush_commands'

     The number of times the server flushes tables, whether because a
     user executed a 'FLUSH TABLES' statement or due to internal server
     operation.  It is also incremented by receipt of a 'COM_REFRESH'
     packet.  This is in contrast to 'Com_flush', which indicates how
     many 'FLUSH' statements have been executed, whether 'FLUSH TABLES',
     'FLUSH LOGS', and so forth.

   * 'Handler_commit'

     The number of internal 'COMMIT' statements.

   * 'Handler_delete'

     The number of times that rows have been deleted from tables.

   * 'Handler_external_lock'

     The server increments this variable for each call to its
     'external_lock()' function, which generally occurs at the beginning
     and end of access to a table instance.  There might be differences
     among storage engines.  This variable can be used, for example, to
     discover for a statement that accesses a partitioned table how many
     partitions were pruned before locking occurred: Check how much the
     counter increased for the statement, subtract 2 (2 calls for the
     table itself), then divide by 2 to get the number of partitions
     locked.

   * 'Handler_mrr_init'

     The number of times the server uses a storage engine's own
     Multi-Range Read implementation for table access.

   * 'Handler_prepare'

     A counter for the prepare phase of two-phase commit operations.

   * 'Handler_read_first'

     The number of times the first entry in an index was read.  If this
     value is high, it suggests that the server is doing a lot of full
     index scans; for example, 'SELECT col1 FROM foo', assuming that
     'col1' is indexed.

   * 'Handler_read_key'

     The number of requests to read a row based on a key.  If this value
     is high, it is a good indication that your tables are properly
     indexed for your queries.

   * 'Handler_read_last'

     The number of requests to read the last key in an index.  With
     'ORDER BY', the server will issue a first-key request followed by
     several next-key requests, whereas with 'ORDER BY DESC', the server
     will issue a last-key request followed by several previous-key
     requests.

   * 'Handler_read_next'

     The number of requests to read the next row in key order.  This
     value is incremented if you are querying an index column with a
     range constraint or if you are doing an index scan.

   * 'Handler_read_prev'

     The number of requests to read the previous row in key order.  This
     read method is mainly used to optimize 'ORDER BY ... DESC'.

   * 'Handler_read_rnd'

     The number of requests to read a row based on a fixed position.
     This value is high if you are doing a lot of queries that require
     sorting of the result.  You probably have a lot of queries that
     require MySQL to scan entire tables or you have joins that do not
     use keys properly.

   * 'Handler_read_rnd_next'

     The number of requests to read the next row in the data file.  This
     value is high if you are doing a lot of table scans.  Generally
     this suggests that your tables are not properly indexed or that
     your queries are not written to take advantage of the indexes you
     have.

   * 'Handler_rollback'

     The number of requests for a storage engine to perform a rollback
     operation.

   * 'Handler_savepoint'

     The number of requests for a storage engine to place a savepoint.

   * 'Handler_savepoint_rollback'

     The number of requests for a storage engine to roll back to a
     savepoint.

   * 'Handler_update'

     The number of requests to update a row in a table.

   * 'Handler_write'

     The number of requests to insert a row in a table.

   * 'Innodb_available_undo_logs'

     *Note*:

     The 'Innodb_available_undo_logs' status variable is deprecated as
     of MySQL 5.7.19 and will be removed in a future release.

     The total number of available 'InnoDB' rollback segments.
     Supplements the 'innodb_rollback_segments' system variable, which
     defines the number of active rollback segments.

     One rollback segment always resides in the system tablespace, and
     32 rollback segments are reserved for use by temporary tables and
     are hosted in the temporary tablespace ('ibtmp1').  See
     innodb-temporary-table-undo-logs.

     If you initiate a MySQL instance with 32 or fewer rollback
     segments, 'InnoDB' still assigns one rollback segment to the system
     tablespace and 32 rollback segments to the temporary tablespace.
     In this case, 'Innodb_available_undo_logs' reports 33 available
     rollback segments even though the instance was initialized with a
     lesser 'innodb_rollback_segments' value.

   * 'Innodb_buffer_pool_dump_status'

     The progress of an operation to record the pages held in the
     'InnoDB' buffer pool, triggered by the setting of
     'innodb_buffer_pool_dump_at_shutdown' or
     'innodb_buffer_pool_dump_now'.

     For related information and examples, see
     innodb-preload-buffer-pool.

   * 'Innodb_buffer_pool_load_status'

     The progress of an operation to warm up the 'InnoDB' buffer pool by
     reading in a set of pages corresponding to an earlier point in
     time, triggered by the setting of
     'innodb_buffer_pool_load_at_startup' or
     'innodb_buffer_pool_load_now'.  If the operation introduces too
     much overhead, you can cancel it by setting
     'innodb_buffer_pool_load_abort'.

     For related information and examples, see
     innodb-preload-buffer-pool.

   * 'Innodb_buffer_pool_bytes_data'

     The total number of bytes in the 'InnoDB' buffer pool containing
     data.  The number includes both dirty and clean pages.  For more
     accurate memory usage calculations than with
     'Innodb_buffer_pool_pages_data', when compressed tables cause the
     buffer pool to hold pages of different sizes.

   * 'Innodb_buffer_pool_pages_data'

     The number of pages in the 'InnoDB' buffer pool containing data.
     The number includes both dirty and clean pages.  When using
     compressed tables, the reported 'Innodb_buffer_pool_pages_data'
     value may be larger than 'Innodb_buffer_pool_pages_total' (Bug
     #59550).

   * 'Innodb_buffer_pool_bytes_dirty'

     The total current number of bytes held in dirty pages in the
     'InnoDB' buffer pool.  For more accurate memory usage calculations
     than with 'Innodb_buffer_pool_pages_dirty', when compressed tables
     cause the buffer pool to hold pages of different sizes.

   * 'Innodb_buffer_pool_pages_dirty'

     The current number of dirty pages in the 'InnoDB' buffer pool.

   * 'Innodb_buffer_pool_pages_flushed'

     The number of requests to flush pages from the 'InnoDB' buffer
     pool.

   * 'Innodb_buffer_pool_pages_free'

     The number of free pages in the 'InnoDB' buffer pool.

   * 'Innodb_buffer_pool_pages_latched'

     The number of latched pages in the 'InnoDB' buffer pool.  These are
     pages currently being read or written, or that cannot be flushed or
     removed for some other reason.  Calculation of this variable is
     expensive, so it is available only when the 'UNIV_DEBUG' system is
     defined at server build time.

   * 'Innodb_buffer_pool_pages_misc'

     The number of pages in the 'InnoDB' buffer pool that are busy
     because they have been allocated for administrative overhead, such
     as row locks or the adaptive hash index.  This value can also be
     calculated as 'Innodb_buffer_pool_pages_total' −
     'Innodb_buffer_pool_pages_free' −
     'Innodb_buffer_pool_pages_data'.  When using compressed tables,
     'Innodb_buffer_pool_pages_misc' may report an out-of-bounds value
     (Bug #59550).

   * 'Innodb_buffer_pool_pages_total'

     The total size of the 'InnoDB' buffer pool, in pages.  When using
     compressed tables, the reported 'Innodb_buffer_pool_pages_data'
     value may be larger than 'Innodb_buffer_pool_pages_total' (Bug
     #59550)

   * 'Innodb_buffer_pool_read_ahead'

     The number of pages read into the 'InnoDB' buffer pool by the
     read-ahead background thread.

   * 'Innodb_buffer_pool_read_ahead_evicted'

     The number of pages read into the 'InnoDB' buffer pool by the
     read-ahead background thread that were subsequently evicted without
     having been accessed by queries.

   * 'Innodb_buffer_pool_read_ahead_rnd'

     The number of 'random' read-aheads initiated by 'InnoDB'.  This
     happens when a query scans a large portion of a table but in random
     order.

   * 'Innodb_buffer_pool_read_requests'

     The number of logical read requests.

   * 'Innodb_buffer_pool_reads'

     The number of logical reads that 'InnoDB' could not satisfy from
     the buffer pool, and had to read directly from disk.

   * 'Innodb_buffer_pool_resize_status'

     The status of an operation to resize the 'InnoDB' buffer pool
     dynamically, triggered by setting the 'innodb_buffer_pool_size'
     parameter dynamically.  As of MySQL 5.7.5, the
     'innodb_buffer_pool_size' parameter is dynamic, which allows you to
     resize the buffer pool without restarting the server.  See
     innodb-buffer-pool-online-resize for related information.

   * 'Innodb_buffer_pool_wait_free'

     Normally, writes to the 'InnoDB' buffer pool happen in the
     background.  When 'InnoDB' needs to read or create a page and no
     clean pages are available, 'InnoDB' flushes some dirty pages first
     and waits for that operation to finish.  This counter counts
     instances of these waits.  If 'innodb_buffer_pool_size' has been
     set properly, this value should be small.

   * 'Innodb_buffer_pool_write_requests'

     The number of writes done to the 'InnoDB' buffer pool.

   * 'Innodb_data_fsyncs'

     The number of 'fsync()' operations so far.  The frequency of
     'fsync()' calls is influenced by the setting of the
     'innodb_flush_method' configuration option.

   * 'Innodb_data_pending_fsyncs'

     The current number of pending 'fsync()' operations.  The frequency
     of 'fsync()' calls is influenced by the setting of the
     'innodb_flush_method' configuration option.

   * 'Innodb_data_pending_reads'

     The current number of pending reads.

   * 'Innodb_data_pending_writes'

     The current number of pending writes.

   * 'Innodb_data_read'

     The amount of data read since the server was started (in bytes).

   * 'Innodb_data_reads'

     The total number of data reads (OS file reads).

   * 'Innodb_data_writes'

     The total number of data writes.

   * 'Innodb_data_written'

     The amount of data written so far, in bytes.

   * 'Innodb_dblwr_pages_written'

     The number of pages that have been written to the doublewrite
     buffer.  See innodb-disk-io.

   * 'Innodb_dblwr_writes'

     The number of doublewrite operations that have been performed.  See
     innodb-disk-io.

   * 'Innodb_have_atomic_builtins'

     Indicates whether the server was built with atomic instructions.

   * 'Innodb_log_waits'

     The number of times that the log buffer was too small and a wait
     was required for it to be flushed before continuing.

   * 'Innodb_log_write_requests'

     The number of write requests for the 'InnoDB' redo log.

   * 'Innodb_log_writes'

     The number of physical writes to the 'InnoDB' redo log file.

   * 'Innodb_num_open_files'

     The number of files 'InnoDB' currently holds open.

   * 'Innodb_os_log_fsyncs'

     The number of 'fsync()' writes done to the 'InnoDB' redo log files.

   * 'Innodb_os_log_pending_fsyncs'

     The number of pending 'fsync()' operations for the 'InnoDB' redo
     log files.

   * 'Innodb_os_log_pending_writes'

     The number of pending writes to the 'InnoDB' redo log files.

   * 'Innodb_os_log_written'

     The number of bytes written to the 'InnoDB' redo log files.

   * 'Innodb_page_size'

     'InnoDB' page size (default 16KB). Many values are counted in
     pages; the page size enables them to be easily converted to bytes.

   * 'Innodb_pages_created'

     The number of pages created by operations on 'InnoDB' tables.

   * 'Innodb_pages_read'

     The number of pages read from the 'InnoDB' buffer pool by
     operations on 'InnoDB' tables.

   * 'Innodb_pages_written'

     The number of pages written by operations on 'InnoDB' tables.

   * 'Innodb_row_lock_current_waits'

     The number of row locks currently being waited for by operations on
     'InnoDB' tables.

   * 'Innodb_row_lock_time'

     The total time spent in acquiring row locks for 'InnoDB' tables, in
     milliseconds.

   * 'Innodb_row_lock_time_avg'

     The average time to acquire a row lock for 'InnoDB' tables, in
     milliseconds.

   * 'Innodb_row_lock_time_max'

     The maximum time to acquire a row lock for 'InnoDB' tables, in
     milliseconds.

   * 'Innodb_row_lock_waits'

     The number of times operations on 'InnoDB' tables had to wait for a
     row lock.

   * 'Innodb_rows_deleted'

     The number of rows deleted from 'InnoDB' tables.

   * 'Innodb_rows_inserted'

     The number of rows inserted into 'InnoDB' tables.

   * 'Innodb_rows_read'

     The number of rows read from 'InnoDB' tables.

   * 'Innodb_rows_updated'

     The number of rows updated in 'InnoDB' tables.

   * 'Innodb_truncated_status_writes'

     The number of times output from the 'SHOW ENGINE INNODB STATUS'
     statement has been truncated.

   * 'Key_blocks_not_flushed'

     The number of key blocks in the 'MyISAM' key cache that have
     changed but have not yet been flushed to disk.

   * 'Key_blocks_unused'

     The number of unused blocks in the 'MyISAM' key cache.  You can use
     this value to determine how much of the key cache is in use; see
     the discussion of 'key_buffer_size' in
     server-system-variables.

   * 'Key_blocks_used'

     The number of used blocks in the 'MyISAM' key cache.  This value is
     a high-water mark that indicates the maximum number of blocks that
     have ever been in use at one time.

   * 'Key_read_requests'

     The number of requests to read a key block from the 'MyISAM' key
     cache.

   * 'Key_reads'

     The number of physical reads of a key block from disk into the
     'MyISAM' key cache.  If 'Key_reads' is large, then your
     'key_buffer_size' value is probably too small.  The cache miss rate
     can be calculated as 'Key_reads'/'Key_read_requests'.

   * 'Key_write_requests'

     The number of requests to write a key block to the 'MyISAM' key
     cache.

   * 'Key_writes'

     The number of physical writes of a key block from the 'MyISAM' key
     cache to disk.

   * 'Last_query_cost'

     The total cost of the last compiled query as computed by the query
     optimizer.  This is useful for comparing the cost of different
     query plans for the same query.  The default value of 0 means that
     no query has been compiled yet.  The default value is 0.
     'Last_query_cost' has session scope.

     The 'Last_query_cost' value can be computed accurately only for
     simple 'flat' queries, not complex queries such as those with
     subqueries or 'UNION'.  For the latter, the value is
     set to 0.

   * 'Last_query_partial_plans'

     The number of iterations the query optimizer made in execution plan
     construction for the previous query.  'Last_query_cost' has session
     scope.

   *
     'Locked_connects'

     The number of attempts to connect to locked user accounts.  For
     information about account locking and unlocking, see
     account-locking.

     This variable was added in MySQL 5.7.6.

   *
     'Max_execution_time_exceeded'

     The number of 'SELECT' statements for which the
     execution timeout was exceeded.

   *
     'Max_execution_time_set'

     The number of 'SELECT' statements for which a
     nonzero execution timeout was set.  This includes statements that
     include a nonzero 'MAX_EXECUTION_TIME' optimizer hint, and
     statements that include no such hint but execute while the timeout
     indicated by the 'max_execution_time' system variable is nonzero.

   *
     'Max_execution_time_set_failed'

     The number of 'SELECT' statements for which the
     attempt to set an execution timeout failed.

   *
     'Max_statement_time_exceeded'

     This variable was renamed to 'Max_execution_time_exceeded' in MySQL
     5.7.8.

   *
     'Max_statement_time_set'

     This variable was renamed to 'Max_execution_time_set' in MySQL
     5.7.8.

   *
     'Max_statement_time_set_failed'

     This variable was renamed to 'Max_execution_time_set_failed' in
     MySQL 5.7.8.

   * 'Max_used_connections'

     The maximum number of connections that have been in use
     simultaneously since the server started.

   * 'Max_used_connections_time'

     The time at which 'Max_used_connections' reached its current value.
     This variable was added in MySQL 5.7.5.

   * 'Not_flushed_delayed_rows'

     This status variable is deprecated (because 'DELAYED' inserts are
     not supported), and will be removed in a future release.

   * 'mecab_charset'

     The character set currently used by the MeCab full-text parser
     plugin.  For related information, see
     fulltext-search-mecab.

   * 'Ongoing_anonymous_transaction_count'

     Shows the number of ongoing transactions which have been marked as
     anonymous.  This can be used to ensure that no further transactions
     are waiting to be processed.  This variable was added in MySQL
     5.7.6.

   * 'Ongoing_anonymous_gtid_violating_transaction_count'

     This status variable is only available in debug builds.  Shows the
     number of ongoing transactions which use 'gtid_next=ANONYMOUS' and
     that violate GTID consistency.

   * 'Ongoing_automatic_gtid_violating_transaction_count'

     This status variable is only available in debug builds.  Shows the
     number of ongoing transactions which use 'gtid_next=AUTOMATIC' and
     that violate GTID consistency.

   * 'Open_files'

     The number of files that are open.  This count includes regular
     files opened by the server.  It does not include other types of
     files such as sockets or pipes.  Also, the count does not include
     files that storage engines open using their own internal functions
     rather than asking the server level to do so.

   * 'Open_streams'

     The number of streams that are open (used mainly for logging).

   * 'Open_table_definitions'

     The number of cached '.frm' files.

   * 'Open_tables'

     The number of tables that are open.

   * 'Opened_files'

     The number of files that have been opened with 'my_open()' (a
     'mysys' library function).  Parts of the server that open files
     without using this function do not increment the count.

   * 'Opened_table_definitions'

     The number of '.frm' files that have been cached.

   * 'Opened_tables'

     The number of tables that have been opened.  If 'Opened_tables' is
     big, your 'table_open_cache' value is probably too small.

   * 'Performance_schema_XXX'

     Performance Schema status variables are listed in
     performance-schema-status-variables.  These variables provide
     information about instrumentation that could not be loaded or
     created due to memory constraints.

   * 'Prepared_stmt_count'

     The current number of prepared statements.  (The maximum number of
     statements is given by the 'max_prepared_stmt_count' system
     variable.)

   * 'Qcache_free_blocks'

     The number of free memory blocks in the query cache.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_free_blocks'.

   * 'Qcache_free_memory'

     The amount of free memory for the query cache.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_free_memory'.

   * 'Qcache_hits'

     The number of query cache hits.

     The discussion at the beginning of this section indicates how to
     relate this statement-counting status variable to other such
     variables.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_hits'.

   * 'Qcache_inserts'

     The number of queries added to the query cache.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_inserts'.

   * 'Qcache_lowmem_prunes'

     The number of queries that were deleted from the query cache
     because of low memory.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_lowmem_prunes'.

   * 'Qcache_not_cached'

     The number of noncached queries (not cacheable, or not cached due
     to the 'query_cache_type' setting).

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_not_cached'.

   * 'Qcache_queries_in_cache'

     The number of queries registered in the query cache.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_queries_in_cache'.

   * 'Qcache_total_blocks'

     The total number of blocks in the query cache.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'Qcache_total_blocks'.

   * 'Queries'

     The number of statements executed by the server.  This variable
     includes statements executed within stored programs, unlike the
     'Questions' variable.  It does not count 'COM_PING' or
     'COM_STATISTICS' commands.

     The discussion at the beginning of this section indicates how to
     relate this statement-counting status variable to other such
     variables.

   * 'Questions'

     The number of statements executed by the server.  This includes
     only statements sent to the server by clients and not statements
     executed within stored programs, unlike the 'Queries' variable.
     This variable does not count 'COM_PING', 'COM_STATISTICS',
     'COM_STMT_PREPARE', 'COM_STMT_CLOSE', or 'COM_STMT_RESET' commands.

     The discussion at the beginning of this section indicates how to
     relate this statement-counting status variable to other such
     variables.

   *
     'Rpl_semi_sync_master_clients'

     The number of semisynchronous slaves.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_net_avg_wait_time'

     The average time in microseconds the master waited for a slave
     reply.  This variable is deprecated, always '0', and will be
     removed in a future version.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_net_wait_time'

     The total time in microseconds the master waited for slave replies.
     This variable is deprecated, always '0', and will be removed in a
     future version.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_net_waits'

     The total number of times the master waited for slave replies.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_no_times'

     The number of times the master turned off semisynchronous
     replication.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_no_tx'

     The number of commits that were not acknowledged successfully by a
     slave.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_status'

     Whether semisynchronous replication currently is operational on the
     master.  The value is 'ON' if the plugin has been enabled and a
     commit acknowledgment has occurred.  It is 'OFF' if the plugin is
     not enabled or the master has fallen back to asynchronous
     replication due to commit acknowledgment timeout.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_timefunc_failures'

     The number of times the master failed when calling time functions
     such as 'gettimeofday()'.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_tx_avg_wait_time'

     The average time in microseconds the master waited for each
     transaction.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_tx_wait_time'

     The total time in microseconds the master waited for transactions.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_tx_waits'

     The total number of times the master waited for transactions.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_wait_pos_backtraverse'

     The total number of times the master waited for an event with
     binary coordinates lower than events waited for previously.  This
     can occur when the order in which transactions start waiting for a
     reply is different from the order in which their binary log events
     are written.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_wait_sessions'

     The number of sessions currently waiting for slave replies.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_master_yes_tx'

     The number of commits that were acknowledged successfully by a
     slave.

     This variable is available only if the master-side semisynchronous
     replication plugin is installed.

   *
     'Rpl_semi_sync_slave_status'

     Whether semisynchronous replication currently is operational on the
     slave.  This is 'ON' if the plugin has been enabled and the slave
     I/O thread is running, 'OFF' otherwise.

     This variable is available only if the slave-side semisynchronous
     replication plugin is installed.

   * 'Rsa_public_key'

     This variable is available if MySQL was compiled using OpenSSL (see
     ssl-libraries).  Its value is the public key used by the
     'sha256_password' authentication plugin for RSA key pair-based
     password exchange.  The value is nonempty only if the server
     successfully initializes the private and public keys in the files
     named by the 'sha256_password_private_key_path' and
     'sha256_password_public_key_path' system variables.  The value of
     'Rsa_public_key' comes from the latter file.

     For information about 'sha256_password', see
     sha256-pluggable-authentication.

   * 'Select_full_join'

     The number of joins that perform table scans because they do not
     use indexes.  If this value is not 0, you should carefully check
     the indexes of your tables.

   * 'Select_full_range_join'

     The number of joins that used a range search on a reference table.

   * 'Select_range'

     The number of joins that used ranges on the first table.  This is
     normally not a critical issue even if the value is quite large.

   * 'Select_range_check'

     The number of joins without keys that check for key usage after
     each row.  If this is not 0, you should carefully check the indexes
     of your tables.

   * 'Select_scan'

     The number of joins that did a full scan of the first table.

   * 'Slave_heartbeat_period'

     Shows the replication heartbeat interval (in seconds) on a
     replication slave.

     This variable is affected by the value of the
     'show_compatibility_56' system variable.  For details, see
     sysvar_show_compatibility_56_slave_status.

     *Note*:

     This variable only shows the status of the default replication
     channel.  To monitor any replication channel, use the
     'HEARTBEAT_INTERVAL' column in the
     'replication_connection_status'
     table for the replication
     channel.  'Slave_heartbeat_period' is deprecated and will be
     removed in a future MySQL release.

   * 'Slave_last_heartbeat'

     Shows when the most recent heartbeat signal was received by a
     replication slave, as a 'TIMESTAMP' value.

     This variable is affected by the value of the
     'show_compatibility_56' system variable.  For details, see
     sysvar_show_compatibility_56_slave_status.

     *Note*:

     This variable only shows the status of the default replication
     channel.  To monitor any replication channel, use the
     'LAST_HEARTBEAT_TIMESTAMP' column in the
     'replication_connection_status'
     table for the replication
     channel.  'Slave_last_heartbeat' is deprecated and will be removed
     in a future MySQL release.

   * 'Slave_open_temp_tables'

     The number of temporary tables that the slave SQL thread currently
     has open.  If the value is greater than zero, it is not safe to
     shut down the slave; see replication-features-temptables.
     This variable reports the total count of open temporary tables for
     _all_ replication channels.

   * 'Slave_received_heartbeats'

     This counter increments with each replication heartbeat received by
     a replication slave since the last time that the slave was
     restarted or reset, or a 'CHANGE MASTER TO'
     statement was issued.

     This variable is affected by the value of the
     'show_compatibility_56' system variable.  For details, see
     sysvar_show_compatibility_56_slave_status.

     *Note*:

     This variable only shows the status of the default replication
     channel.  To monitor any replication channel, use the
     'COUNT_RECEIVED_HEARTBEATS' column in the
     'replication_connection_status'
     table for the replication
     channel.  'Slave_received_heartbeats' is deprecated and will be
     removed in a future MySQL release.

   * 'Slave_retried_transactions'

     The total number of times since startup that the replication slave
     SQL thread has retried transactions.

     This variable is affected by the value of the
     'show_compatibility_56' system variable.  For details, see
     sysvar_show_compatibility_56_slave_status.

     *Note*:

     This variable only shows the status of the default replication
     channel.  To monitor any replication channel, use the
     'COUNT_TRANSACTIONS_RETRIES' column in the
     'replication_applier_status'.
     table for the replication channel.  'Slave_retried_transactions' is
     deprecated and will be removed in a future MySQL release.

   * 'Slave_rows_last_search_algorithm_used'

     The search algorithm that was most recently used by this slave to
     locate rows for row-based replication.  The result shows whether
     the slave used indexes, a table scan, or hashing as the search
     algorithm for the last transaction executed on any channel.

     The method used depends on the setting for the
     'slave_rows_search_algorithms' system variable, and the keys that
     are available on the relevant table.

   * 'Slave_running'

     This is 'ON' if this server is a replication slave that is
     connected to a replication master, and both the I/O and SQL threads
     are running; otherwise, it is 'OFF'.

     This variable is affected by the value of the
     'show_compatibility_56' system variable.  For details, see
     sysvar_show_compatibility_56_slave_status.

     *Note*:

     This variable only shows the status of the default replication
     channel.  To monitor any replication channel, use the
     'SERVICE_STATE' column in the 'replication_applier_status'
     or
     'replication_connection_status'
     tables of the replication
     channel.  'Slave_running' is deprecated and will be removed in a
     future MySQL release.

   * 'Slow_launch_threads'

     The number of threads that have taken more than 'slow_launch_time'
     seconds to create.

     This variable is not meaningful in the embedded server
     ('libmysqld') and as of MySQL 5.7.2 is no longer visible within the
     embedded server.

   * 'Slow_queries'

     The number of queries that have taken more than 'long_query_time'
     seconds.  This counter increments regardless of whether the slow
     query log is enabled.  For information about that log, see
     slow-query-log.

   * 'Sort_merge_passes'

     The number of merge passes that the sort algorithm has had to do.
     If this value is large, you should consider increasing the value of
     the 'sort_buffer_size' system variable.

   * 'Sort_range'

     The number of sorts that were done using ranges.

   * 'Sort_rows'

     The number of sorted rows.

   * 'Sort_scan'

     The number of sorts that were done by scanning the table.

   * 'Ssl_accept_renegotiates'

     The number of negotiates needed to establish the connection.

   * 'Ssl_accepts'

     The number of accepted SSL connections.

   * 'Ssl_callback_cache_hits'

     The number of callback cache hits.

   * 'Ssl_cipher'

     The current encryption cipher (empty for unencrypted connections).

   * 'Ssl_cipher_list'

     The list of possible SSL ciphers (empty for non-SSL connections).

   * 'Ssl_client_connects'

     The number of SSL connection attempts to an SSL-enabled master.

   * 'Ssl_connect_renegotiates'

     The number of negotiates needed to establish the connection to an
     SSL-enabled master.

   * 'Ssl_ctx_verify_depth'

     The SSL context verification depth (how many certificates in the
     chain are tested).

   * 'Ssl_ctx_verify_mode'

     The SSL context verification mode.

   * 'Ssl_default_timeout'

     The default SSL timeout.

   * 'Ssl_finished_accepts'

     The number of successful SSL connections to the server.

   * 'Ssl_finished_connects'

     The number of successful slave connections to an SSL-enabled
     master.

   * 'Ssl_server_not_after'

     The last date for which the SSL certificate is valid.  To check SSL
     certificate expiration information, use this statement:

          mysql> SHOW STATUS LIKE 'Ssl_server_not%';
          +-----------------------+--------------------------+
          | Variable_name         | Value                    |
          +-----------------------+--------------------------+
          | Ssl_server_not_after  | Apr 28 14:16:39 2025 GMT |
          | Ssl_server_not_before | May  1 14:16:39 2015 GMT |
          +-----------------------+--------------------------+

   * 'Ssl_server_not_before'

     The first date for which the SSL certificate is valid.

   * 'Ssl_session_cache_hits'

     The number of SSL session cache hits.

   * 'Ssl_session_cache_misses'

     The number of SSL session cache misses.

   * 'Ssl_session_cache_mode'

     The SSL session cache mode.

   * 'Ssl_session_cache_overflows'

     The number of SSL session cache overflows.

   * 'Ssl_session_cache_size'

     The SSL session cache size.

   * 'Ssl_session_cache_timeouts'

     The number of SSL session cache timeouts.

   * 'Ssl_sessions_reused'

     How many SSL connections were reused from the cache.

   * 'Ssl_used_session_cache_entries'

     How many SSL session cache entries were used.

   * 'Ssl_verify_depth'

     The verification depth for replication SSL connections.

   * 'Ssl_verify_mode'

     The verification mode used by the server for a connection that uses
     SSL. The value is a bitmask; bits are defined in the
     'openssl/ssl.h' header file:

          # define SSL_VERIFY_NONE                 0x00
          # define SSL_VERIFY_PEER                 0x01
          # define SSL_VERIFY_FAIL_IF_NO_PEER_CERT 0x02
          # define SSL_VERIFY_CLIENT_ONCE          0x04

     'SSL_VERIFY_PEER' indicates that the server asks for a client
     certificate.  If the client supplies one, the server performs
     verification and proceeds only if verification is successful.
     'SSL_VERIFY_CLIENT_ONCE' indicates that a request for the client
     certificate will be done only in the initial handshake.

   * 'Ssl_version'

     The SSL protocol version of the connection; for example, TLSv1.  If
     the connection is not encrypted, the value is empty.

   * 'Table_locks_immediate'

     The number of times that a request for a table lock could be
     granted immediately.

   * 'Table_locks_waited'

     The number of times that a request for a table lock could not be
     granted immediately and a wait was needed.  If this is high and you
     have performance problems, you should first optimize your queries,
     and then either split your table or tables or use replication.

   * 'Table_open_cache_hits'

     The number of hits for open tables cache lookups.

   * 'Table_open_cache_misses'

     The number of misses for open tables cache lookups.

   * 'Table_open_cache_overflows'

     The number of overflows for the open tables cache.  This is the
     number of times, after a table is opened or closed, a cache
     instance has an unused entry and the size of the instance is larger
     than 'table_open_cache' / 'table_open_cache_instances'.

   * 'Tc_log_max_pages_used'

     For the memory-mapped implementation of the log that is used by
     'mysqld' when it acts as the transaction coordinator
     for recovery of internal XA transactions, this variable indicates
     the largest number of pages used for the log since the server
     started.  If the product of 'Tc_log_max_pages_used' and
     'Tc_log_page_size' is always significantly less than the log size,
     the size is larger than necessary and can be reduced.  (The size is
     set by the '--log-tc-size' option.  This variable is unused: It is
     unneeded for binary log-based recovery, and the memory-mapped
     recovery log method is not used unless the number of storage
     engines that are capable of two-phase commit and that support XA
     transactions is greater than one.  ('InnoDB' is the only applicable
     engine.)

   * 'Tc_log_page_size'

     The page size used for the memory-mapped implementation of the XA
     recovery log.  The default value is determined using
     'getpagesize()'.  This variable is unused for the same reasons as
     described for 'Tc_log_max_pages_used'.

   * 'Tc_log_page_waits'

     For the memory-mapped implementation of the recovery log, this
     variable increments each time the server was not able to commit a
     transaction and had to wait for a free page in the log.  If this
     value is large, you might want to increase the log size (with the
     '--log-tc-size' option).  For binary log-based recovery, this
     variable increments each time the binary log cannot be closed
     because there are two-phase commits in progress.  (The close
     operation waits until all such transactions are finished.)

   * 'Threads_cached'

     The number of threads in the thread cache.

     This variable is not meaningful in the embedded server
     ('libmysqld') and as of MySQL 5.7.2 is no longer visible within the
     embedded server.

   * 'Threads_connected'

     The number of currently open connections.

   * 'Threads_created'

     The number of threads created to handle connections.  If
     'Threads_created' is big, you may want to increase the
     'thread_cache_size' value.  The cache miss rate can be calculated
     as 'Threads_created'/'Connections'.

   * 'Threads_running'

     The number of threads that are not sleeping.

   * 'Uptime'

     The number of seconds that the server has been up.

   * 'Uptime_since_flush_status'

     The number of seconds since the most recent 'FLUSH STATUS'
     statement.

5.1.8 Server SQL Modes
----------------------

The MySQL server can operate in different SQL modes, and can apply these
modes differently for different clients, depending on the value of the
'sql_mode' system variable.  DBAs can set the global SQL mode to match
site server operating requirements, and each application can set its
session SQL mode to its own requirements.

Modes affect the SQL syntax MySQL supports and the data validation
checks it performs.  This makes it easier to use MySQL in different
environments and to use MySQL together with other database servers.

   * sql-mode-setting

   * sql-mode-important

   * sql-mode-full

   * sql-mode-combo

   * sql-mode-strict

   * ignore-strict-comparison

   * sql-mode-changes

For answers to questions often asked about server SQL modes in MySQL,
see faqs-sql-modes.

When working with 'InnoDB' tables, consider also the
'innodb_strict_mode' system variable.  It enables additional error
checks for 'InnoDB' tables.

*Setting the SQL Mode*

The default SQL mode in MySQL 5.7 includes these modes:
'ONLY_FULL_GROUP_BY', 'STRICT_TRANS_TABLES', 'NO_ZERO_IN_DATE',
'NO_ZERO_DATE', 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_AUTO_CREATE_USER', and
'NO_ENGINE_SUBSTITUTION'.

These modes were added to the default SQL mode in MySQL 5.7: The
'ONLY_FULL_GROUP_BY' and 'STRICT_TRANS_TABLES' modes were added in MySQL
5.7.5.  The 'NO_AUTO_CREATE_USER' mode was added in MySQL 5.7.7.  The
'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and 'NO_ZERO_IN_DATE'
modes were added in MySQL 5.7.8.  For additional discussion regarding
these changes to the default SQL mode value, see
sql-mode-changes.

To set the SQL mode at server startup, use the '--sql-mode="MODES"'
option on the command line, or 'sql-mode="MODES"' in an option file such
as 'my.cnf' (Unix operating systems) or 'my.ini' (Windows).  MODES is a
list of different modes separated by commas.  To clear the SQL mode
explicitly, set it to an empty string using '--sql-mode=""' on the
command line, or 'sql-mode=""' in an option file.

*Note*:

MySQL installation programs may configure the SQL mode during the
installation process.  For example, see 'mysql_install_db'
creates a default option file named 'my.cnf' in the
base installation directory.  This file contains a line that sets the
SQL mode; see mysql-install-db.

If the SQL mode differs from the default or from what you expect, check
for a setting in an option file that the server reads at startup.

To change the SQL mode at runtime, set the global or session 'sql_mode'
system variable using a 'SET' statement:

     SET GLOBAL sql_mode = 'MODES';
     SET SESSION sql_mode = 'MODES';

Setting the 'GLOBAL' variable requires the 'SUPER' privilege and affects
the operation of all clients that connect from that time on.  Setting
the 'SESSION' variable affects only the current client.  Each client can
change its session 'sql_mode' value at any time.

To determine the current global or session 'sql_mode' setting, select
its value:

     SELECT @@GLOBAL.sql_mode;
     SELECT @@SESSION.sql_mode;

*Important*:

SQL mode and user-defined partitioning

Changing the server SQL mode after creating and inserting data into
partitioned tables can cause major changes in the behavior of such
tables, and could lead to loss or corruption of data.  It is strongly
recommended that you never change the SQL mode once you have created
tables employing user-defined partitioning.

When replicating partitioned tables, differing SQL modes on the master
and slave can also lead to problems.  For best results, you should
always use the same server SQL mode on the master and slave.

For more information, see partitioning-limitations.

*The Most Important SQL Modes*

The most important 'sql_mode' values are probably these:

   *
     'ANSI'

     This mode changes syntax and behavior to conform more closely to
     standard SQL. It is one of the special combination modes listed at
     the end of this section.

   *
     'STRICT_TRANS_TABLES'

     If a value could not be inserted as given into a transactional
     table, abort the statement.  For a nontransactional table, abort
     the statement if the value occurs in a single-row statement or the
     first row of a multiple-row statement.  More details are given
     later in this section.

     As of MySQL 5.7.5, the default SQL mode includes
     'STRICT_TRANS_TABLES'.

   *
     'TRADITIONAL'

     Make MySQL behave like a 'traditional' SQL database system.  A
     simple description of this mode is 'give an error instead of a
     warning' when inserting an incorrect value into a column.  It is
     one of the special combination modes listed at the end of this
     section.

     *Note*:

     With 'TRADITIONAL' mode enabled, an 'INSERT' or
     'UPDATE' aborts as soon as an error occurs.  If you
     are using a nontransactional storage engine, this may not be what
     you want because data changes made prior to the error may not be
     rolled back, resulting in a 'partially done' update.

When this manual refers to 'strict mode,' it means a mode with either or
both 'STRICT_TRANS_TABLES' or 'STRICT_ALL_TABLES' enabled.

*Full List of SQL Modes*

The following list describes all supported SQL modes:

   *
     'ALLOW_INVALID_DATES'

     Do not perform full checking of dates.  Check only that the month
     is in the range from 1 to 12 and the day is in the range from 1 to
     31.  This may be useful for Web applications that obtain year,
     month, and day in three different fields and store exactly what the
     user inserted, without date validation.  This mode applies to
     'DATE' and 'DATETIME' columns.  It does
     not apply 'TIMESTAMP' columns, which always
     require a valid date.

     With 'ALLOW_INVALID_DATES' enabled, the server requires that month
     and day values be legal, and not merely in the range 1 to 12 and 1
     to 31, respectively.  With strict mode disabled, invalid dates such
     as ''2004-04-31'' are converted to ''0000-00-00'' and a warning is
     generated.  With strict mode enabled, invalid dates generate an
     error.  To permit such dates, enable 'ALLOW_INVALID_DATES'.

   *
     'ANSI_QUOTES'

     Treat '"' as an identifier quote character (like the '`' quote
     character) and not as a string quote character.  You can still use
     '`' to quote identifiers with this mode enabled.  With
     'ANSI_QUOTES' enabled, you cannot use double quotation marks to
     quote literal strings because they are interpreted as identifiers.

   *
     'ERROR_FOR_DIVISION_BY_ZERO'

     The 'ERROR_FOR_DIVISION_BY_ZERO' mode affects handling of division
     by zero, which includes 'MOD(N,0)'.  For data-change operations
     (see 'INSERT', 'UPDATE'), its effect also
     depends on whether strict SQL mode is enabled.

        * If this mode is not enabled, division by zero inserts 'NULL'
          and produces no warning.

        * If this mode is enabled, division by zero inserts 'NULL' and
          produces a warning.

        * If this mode and strict mode are enabled, division by zero
          produces an error, unless 'IGNORE' is given as well.  For
          'INSERT IGNORE' and 'UPDATE IGNORE', division by zero inserts
          'NULL' and produces a warning.

     For 'SELECT', division by zero returns 'NULL'.
     Enabling 'ERROR_FOR_DIVISION_BY_ZERO' causes a warning to be
     produced as well, regardless of whether strict mode is enabled.

     'ERROR_FOR_DIVISION_BY_ZERO' is deprecated.
     'ERROR_FOR_DIVISION_BY_ZERO' is not part of strict mode, but should
     be used in conjunction with strict mode and is enabled by default.
     A warning occurs if 'ERROR_FOR_DIVISION_BY_ZERO' is enabled without
     also enabling strict mode or vice versa.  For additional
     discussion, see sql-mode-changes.

     Because 'ERROR_FOR_DIVISION_BY_ZERO' is deprecated, it will be
     removed in a future MySQL release as a separate mode name and its
     effect included in the effects of strict SQL mode.

   *
     'HIGH_NOT_PRECEDENCE'

     The precedence of the 'NOT' operator is such that expressions such
     as 'NOT a BETWEEN b AND c' are parsed as 'NOT (a BETWEEN b AND c)'.
     In some older versions of MySQL, the expression was parsed as '(NOT
     a) BETWEEN b AND c'.  The old higher-precedence behavior can be
     obtained by enabling the 'HIGH_NOT_PRECEDENCE' SQL mode.

          mysql> SET sql_mode = '';
          mysql> SELECT NOT 1 BETWEEN -5 AND 5;
                  -> 0
          mysql> SET sql_mode = 'HIGH_NOT_PRECEDENCE';
          mysql> SELECT NOT 1 BETWEEN -5 AND 5;
                  -> 1

   *
     'IGNORE_SPACE'

     Permit spaces between a function name and the '(' character.  This
     causes built-in function names to be treated as reserved words.  As
     a result, identifiers that are the same as function names must be
     quoted as described in identifiers.  For example, because
     there is a 'COUNT()' function, the use of 'count' as a table name
     in the following statement causes an error:

          mysql> CREATE TABLE count (i INT);
          ERROR 1064 (42000): You have an error in your SQL syntax

     The table name should be quoted:

          mysql> CREATE TABLE `count` (i INT);
          Query OK, 0 rows affected (0.00 sec)

     The 'IGNORE_SPACE' SQL mode applies to built-in functions, not to
     user-defined functions or stored functions.  It is always
     permissible to have spaces after a UDF or stored function name,
     regardless of whether 'IGNORE_SPACE' is enabled.

     For further discussion of 'IGNORE_SPACE', see
     function-resolution.

   *
     'NO_AUTO_CREATE_USER'

     Prevent the 'GRANT' statement from automatically
     creating new user accounts if it would otherwise do so, unless
     authentication information is specified.  The statement must
     specify a nonempty password using 'IDENTIFIED BY' or an
     authentication plugin using 'IDENTIFIED WITH'.

     It is preferable to create MySQL accounts with 'CREATE USER'
     rather than 'GRANT'.
     'NO_AUTO_CREATE_USER' is deprecated and the default SQL mode
     includes 'NO_AUTO_CREATE_USER'.  Assignments to 'sql_mode' that
     change the 'NO_AUTO_CREATE_USER' mode state produce a warning,
     except assignments that set 'sql_mode' to 'DEFAULT'.
     'NO_AUTO_CREATE_USER' will be removed in a future MySQL release, at
     which point its effect will be enabled at all times (see 'GRANT'
     will not create accounts).

     Previously, before 'NO_AUTO_CREATE_USER' was deprecated, one reason
     not to enable it was that it was not replication safe.  Now it can
     be enabled and replication-safe user management performed with
     'CREATE USER IF NOT EXISTS', 'DROP USER IF EXISTS', and 'ALTER USER
     IF EXISTS' rather than 'GRANT'.  These statements enable safe
     replication when slaves may have different grants than those on the
     master.  See create-user, drop-user, and
     alter-user.

   *
     'NO_AUTO_VALUE_ON_ZERO'

     'NO_AUTO_VALUE_ON_ZERO' affects handling of 'AUTO_INCREMENT'
     columns.  Normally, you generate the next sequence number for the
     column by inserting either 'NULL' or '0' into it.
     'NO_AUTO_VALUE_ON_ZERO' suppresses this behavior for '0' so that
     only 'NULL' generates the next sequence number.

     This mode can be useful if '0' has been stored in a table's
     'AUTO_INCREMENT' column.  (Storing '0' is not a recommended
     practice, by the way.)  For example, if you dump the table with
     'mysqldump' and then reload it, MySQL normally
     generates new sequence numbers when it encounters the '0' values,
     resulting in a table with contents different from the one that was
     dumped.  Enabling 'NO_AUTO_VALUE_ON_ZERO' before reloading the dump
     file solves this problem.  For this reason, see 'mysqldump'
     automatically includes in its output a statement that
     enables 'NO_AUTO_VALUE_ON_ZERO'.

   *
     'NO_BACKSLASH_ESCAPES'

     Disable the use of the backslash character ('\') as an escape
     character within strings.  With this mode enabled, backslash
     becomes an ordinary character like any other.

   *
     'NO_DIR_IN_CREATE'

     When creating a table, ignore all 'INDEX DIRECTORY' and 'DATA
     DIRECTORY' directives.  This option is useful on slave replication
     servers.

   *
     'NO_ENGINE_SUBSTITUTION'

     Control automatic substitution of the default storage engine when a
     statement such as 'CREATE TABLE' or
     'ALTER TABLE' specifies a storage engine that is
     disabled or not compiled in.

     By default, 'NO_ENGINE_SUBSTITUTION' is enabled.

     Because storage engines can be pluggable at runtime, unavailable
     engines are treated the same way:

     With 'NO_ENGINE_SUBSTITUTION' disabled, for 'CREATE TABLE'
     the default engine is used and a warning occurs if
     the desired engine is unavailable.  For 'ALTER TABLE',
     a warning occurs and the table is not altered.

     With 'NO_ENGINE_SUBSTITUTION' enabled, an error occurs and the
     table is not created or altered if the desired engine is
     unavailable.

   *
     'NO_FIELD_OPTIONS'

     Do not print MySQL-specific column options in the output of
     'SHOW CREATE TABLE'.  This mode is used by
     'mysqldump' in portability mode.

     *Note*:

     As of MySQL 5.7.22, 'NO_FIELD_OPTIONS' is deprecated.  It will be
     removed in a future version of MySQL.

   *
     'NO_KEY_OPTIONS'

     Do not print MySQL-specific index options in the output of
     'SHOW CREATE TABLE'.  This mode is used by
     'mysqldump' in portability mode.

     *Note*:

     As of MySQL 5.7.22, 'NO_KEY_OPTIONS' is deprecated.  It will be
     removed in a future version of MySQL.

   *
     'NO_TABLE_OPTIONS'

     Do not print MySQL-specific table options (such as 'ENGINE') in the
     output of 'SHOW CREATE TABLE'.  This mode
     is used by 'mysqldump' in portability mode.

     *Note*:

     As of MySQL 5.7.22, 'NO_TABLE_OPTIONS' is deprecated.  It will be
     removed in a future version of MySQL.

   *
     'NO_UNSIGNED_SUBTRACTION'

     Subtraction between integer values, where one is of type
     'UNSIGNED', produces an unsigned result by default.  If the result
     would otherwise have been negative, an error results:

          mysql> SET sql_mode = '';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT CAST(0 AS UNSIGNED) - 1;
          ERROR 1690 (22003): BIGINT UNSIGNED value is out of range in '(cast(0 as unsigned) - 1)'

     If the 'NO_UNSIGNED_SUBTRACTION' SQL mode is enabled, the result is
     negative:

          mysql> SET sql_mode = 'NO_UNSIGNED_SUBTRACTION';
          mysql> SELECT CAST(0 AS UNSIGNED) - 1;
          +-------------------------+
          | CAST(0 AS UNSIGNED) - 1 |
          +-------------------------+
          |                      -1 |
          +-------------------------+

     If the result of such an operation is used to update an 'UNSIGNED'
     integer column, the result is clipped to the maximum value for the
     column type, or clipped to 0 if 'NO_UNSIGNED_SUBTRACTION' is
     enabled.  With strict SQL mode enabled, an error occurs and the
     column remains unchanged.

     When 'NO_UNSIGNED_SUBTRACTION' is enabled, the subtraction result
     is signed, _even if any operand is unsigned_.  For example, compare
     the type of column 'c2' in table 't1' with that of column 'c2' in
     table 't2':

          mysql> SET sql_mode='';
          mysql> CREATE TABLE test (c1 BIGINT UNSIGNED NOT NULL);
          mysql> CREATE TABLE t1 SELECT c1 - 1 AS c2 FROM test;
          mysql> DESCRIBE t1;
          +-------+---------------------+------+-----+---------+-------+
          | Field | Type                | Null | Key | Default | Extra |
          +-------+---------------------+------+-----+---------+-------+
          | c2    | bigint(21) unsigned | NO   |     | 0       |       |
          +-------+---------------------+------+-----+---------+-------+

          mysql> SET sql_mode='NO_UNSIGNED_SUBTRACTION';
          mysql> CREATE TABLE t2 SELECT c1 - 1 AS c2 FROM test;
          mysql> DESCRIBE t2;
          +-------+------------+------+-----+---------+-------+
          | Field | Type       | Null | Key | Default | Extra |
          +-------+------------+------+-----+---------+-------+
          | c2    | bigint(21) | NO   |     | 0       |       |
          +-------+------------+------+-----+---------+-------+

     This means that 'BIGINT UNSIGNED' is not 100% usable in all
     contexts.  See cast-functions.

   *
     'NO_ZERO_DATE'

     The 'NO_ZERO_DATE' mode affects whether the server permits
     ''0000-00-00'' as a valid date.  Its effect also depends on whether
     strict SQL mode is enabled.

        * If this mode is not enabled, ''0000-00-00'' is permitted and
          inserts produce no warning.

        * If this mode is enabled, ''0000-00-00'' is permitted and
          inserts produce a warning.

        * If this mode and strict mode are enabled, ''0000-00-00'' is
          not permitted and inserts produce an error, unless 'IGNORE' is
          given as well.  For 'INSERT IGNORE' and 'UPDATE IGNORE',
          ''0000-00-00'' is permitted and inserts produce a warning.

     'NO_ZERO_DATE' is deprecated.  'NO_ZERO_DATE' is not part of strict
     mode, but should be used in conjunction with strict mode and is
     enabled by default.  A warning occurs if 'NO_ZERO_DATE' is enabled
     without also enabling strict mode or vice versa.  For additional
     discussion, see sql-mode-changes.

     Because 'NO_ZERO_DATE' is deprecated, it will be removed in a
     future MySQL release as a separate mode name and its effect
     included in the effects of strict SQL mode.

   *
     'NO_ZERO_IN_DATE'

     The 'NO_ZERO_IN_DATE' mode affects whether the server permits dates
     in which the year part is nonzero but the month or day part is 0.
     (This mode affects dates such as ''2010-00-01'' or ''2010-01-00'',
     but not ''0000-00-00''.  To control whether the server permits
     ''0000-00-00'', use the 'NO_ZERO_DATE' mode.)  The effect of
     'NO_ZERO_IN_DATE' also depends on whether strict SQL mode is
     enabled.

        * If this mode is not enabled, dates with zero parts are
          permitted and inserts produce no warning.

        * If this mode is enabled, dates with zero parts are inserted as
          ''0000-00-00'' and produce a warning.

        * If this mode and strict mode are enabled, dates with zero
          parts are not permitted and inserts produce an error, unless
          'IGNORE' is given as well.  For 'INSERT IGNORE' and 'UPDATE
          IGNORE', dates with zero parts are inserted as ''0000-00-00''
          and produce a warning.

     'NO_ZERO_IN_DATE' is deprecated.  'NO_ZERO_IN_DATE' is not part of
     strict mode, but should be used in conjunction with strict mode and
     is enabled by default.  A warning occurs if 'NO_ZERO_IN_DATE' is
     enabled without also enabling strict mode or vice versa.  For
     additional discussion, see sql-mode-changes.

     Because 'NO_ZERO_IN_DATE' is deprecated, it will be removed in a
     future MySQL release as a separate mode name and its effect
     included in the effects of strict SQL mode.

   *
     'ONLY_FULL_GROUP_BY'

     Reject queries for which the select list, 'HAVING' condition, or
     'ORDER BY' list refer to nonaggregated columns that are neither
     named in the 'GROUP BY' clause nor are functionally dependent on
     (uniquely determined by) 'GROUP BY' columns.

     As of MySQL 5.7.5, the default SQL mode includes
     'ONLY_FULL_GROUP_BY'.  (Before 5.7.5, MySQL does not detect
     functional dependency and 'ONLY_FULL_GROUP_BY' is not enabled by
     default.  For a description of pre-5.7.5 behavior, see the MySQL
     5.6 Reference Manual
     (http://dev.mysql.com/doc/refman/5.6/en/sql-mode.html).)

     A MySQL extension to standard SQL permits references in the
     'HAVING' clause to aliased expressions in the select list.  Before
     MySQL 5.7.5, enabling 'ONLY_FULL_GROUP_BY' disables this extension,
     thus requiring the 'HAVING' clause to be written using unaliased
     expressions.  As of MySQL 5.7.5, this restriction is lifted so that
     the 'HAVING' clause can refer to aliases regardless of whether
     'ONLY_FULL_GROUP_BY' is enabled.

     For additional discussion and examples, see
     group-by-handling.

   *
     'PAD_CHAR_TO_FULL_LENGTH'

     By default, trailing spaces are trimmed from 'CHAR'.
     column values on retrieval.  If 'PAD_CHAR_TO_FULL_LENGTH' is
     enabled, trimming does not occur and retrieved 'CHAR'.
     values are padded to their full length.  This mode does not apply
     to 'VARCHAR' columns, for which trailing spaces are
     retained on retrieval.

          mysql> CREATE TABLE t1 (c1 CHAR(10));
          Query OK, 0 rows affected (0.37 sec)

          mysql> INSERT INTO t1 (c1) VALUES('xy');
          Query OK, 1 row affected (0.01 sec)

          mysql> SET sql_mode = '';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT c1, CHAR_LENGTH(c1) FROM t1;
          +------+-----------------+
          | c1   | CHAR_LENGTH(c1) |
          +------+-----------------+
          | xy   |               2 |
          +------+-----------------+
          1 row in set (0.00 sec)

          mysql> SET sql_mode = 'PAD_CHAR_TO_FULL_LENGTH';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT c1, CHAR_LENGTH(c1) FROM t1;
          +------------+-----------------+
          | c1         | CHAR_LENGTH(c1) |
          +------------+-----------------+
          | xy         |              10 |
          +------------+-----------------+
          1 row in set (0.00 sec)

   *
     'PIPES_AS_CONCAT'

     Treat '||' as a string concatenation operator (same as 'CONCAT()')
     rather than as a synonym for 'OR'.

   *
     'REAL_AS_FLOAT'

     Treat 'REAL' as a synonym for
     'FLOAT'.  By default, MySQL treats
     'REAL' as a synonym for 'DOUBLE'.

   *
     'STRICT_ALL_TABLES'

     Enable strict SQL mode for all storage engines.  Invalid data
     values are rejected.  For details, see sql-mode-strict.

     From MySQL 5.7.4 through 5.7.7, 'STRICT_ALL_TABLES' includes the
     effect of the 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and
     'NO_ZERO_IN_DATE' modes.  For additional discussion, see
     sql-mode-changes.

   *
     'STRICT_TRANS_TABLES'

     Enable strict SQL mode for transactional storage engines, and when
     possible for nontransactional storage engines.  For details, see
     sql-mode-strict.

     From MySQL 5.7.4 through 5.7.7, 'STRICT_TRANS_TABLES' includes the
     effect of the 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and
     'NO_ZERO_IN_DATE' modes.  For additional discussion, see
     sql-mode-changes.

*Combination SQL Modes*

The following special modes are provided as shorthand for combinations
of mode values from the preceding list.

   *
     'ANSI'

     Equivalent to 'REAL_AS_FLOAT', 'PIPES_AS_CONCAT', 'ANSI_QUOTES',
     'IGNORE_SPACE', and (as of MySQL 5.7.5) 'ONLY_FULL_GROUP_BY'.

     'ANSI' mode also causes the server to return an error for queries
     where a set function S with an outer reference 'S(OUTER_REF)'
     cannot be aggregated in the outer query against which the outer
     reference has been resolved.  This is such a query:

          SELECT * FROM t1 WHERE t1.a IN (SELECT MAX(t1.b) FROM t2 WHERE ...);

     Here, 'MAX(t1.b)' cannot aggregated in the outer query because it
     appears in the 'WHERE' clause of that query.  Standard SQL requires
     an error in this situation.  If 'ANSI' mode is not enabled, the
     server treats 'S(OUTER_REF)' in such queries the same way that it
     would interpret 'S(CONST)'.

     See compatibility.

   *
     'DB2'

     Equivalent to 'PIPES_AS_CONCAT', 'ANSI_QUOTES', 'IGNORE_SPACE',
     'NO_KEY_OPTIONS', 'NO_TABLE_OPTIONS', 'NO_FIELD_OPTIONS'.

     *Note*:

     As of MySQL 5.7.22, 'DB2' is deprecated.  It will be removed in a
     future version of MySQL.

   *
     'MAXDB'

     Equivalent to 'PIPES_AS_CONCAT', 'ANSI_QUOTES', 'IGNORE_SPACE',
     'NO_KEY_OPTIONS', 'NO_TABLE_OPTIONS', 'NO_FIELD_OPTIONS',
     'NO_AUTO_CREATE_USER'.

     *Note*:

     As of MySQL 5.7.22, 'MAXDB' is deprecated.  It will be removed in a
     future version of MySQL.

   *
     'MSSQL'

     Equivalent to 'PIPES_AS_CONCAT', 'ANSI_QUOTES', 'IGNORE_SPACE',
     'NO_KEY_OPTIONS', 'NO_TABLE_OPTIONS', 'NO_FIELD_OPTIONS'.

     *Note*:

     As of MySQL 5.7.22, 'MSSQL' is deprecated.  It will be removed in a
     future version of MySQL.

   *
     'MYSQL323'

     Equivalent to 'MYSQL323', 'HIGH_NOT_PRECEDENCE'.  This means
     'HIGH_NOT_PRECEDENCE' plus some 'SHOW CREATE TABLE'
     behaviors specific to 'MYSQL323':

        * 'TIMESTAMP' column display does not include
          'DEFAULT' or 'ON UPDATE' attributes.

        * String column display does not include character set and
          collation attributes.  For 'CHAR' and
          'VARCHAR' columns, if the collation is binary, 'BINARY'
          is appended to the column type.

        * The 'ENGINE=ENGINE_NAME' table option displays as
          'TYPE=ENGINE_NAME'.

        * For 'MEMORY' tables, the storage
          engine is displayed as 'HEAP'.

     *Note*:

     As of MySQL 5.7.22, 'MYSQL323' is deprecated.  It will be removed
     in a future version of MySQL.

   *
     'MYSQL40'

     Equivalent to 'MYSQL40', 'HIGH_NOT_PRECEDENCE'.  This means
     'HIGH_NOT_PRECEDENCE' plus some behaviors specific to 'MYSQL40'.
     These are the same as for 'MYSQL323', except that 'SHOW CREATE TABLE'
     does not display 'HEAP' as the
     storage engine for 'MEMORY' tables.

     *Note*:

     As of MySQL 5.7.22, 'MYSQL40' is deprecated.  It will be removed in
     a future version of MySQL.

   *
     'ORACLE'

     Equivalent to 'PIPES_AS_CONCAT', 'ANSI_QUOTES', 'IGNORE_SPACE',
     'NO_KEY_OPTIONS', 'NO_TABLE_OPTIONS', 'NO_FIELD_OPTIONS',
     'NO_AUTO_CREATE_USER'.

     *Note*:

     As of MySQL 5.7.22, 'ORACLE' is deprecated.  It will be removed in
     a future version of MySQL.

   *
     'POSTGRESQL'

     Equivalent to 'PIPES_AS_CONCAT', 'ANSI_QUOTES', 'IGNORE_SPACE',
     'NO_KEY_OPTIONS', 'NO_TABLE_OPTIONS', 'NO_FIELD_OPTIONS'.

     *Note*:

     As of MySQL 5.7.22, 'POSTGRESQL' is deprecated.  It will be removed
     in a future version of MySQL.

   *
     'TRADITIONAL'

     Before MySQL 5.7.4, and in MySQL 5.7.8 and later, 'TRADITIONAL' is
     equivalent to 'STRICT_TRANS_TABLES', 'STRICT_ALL_TABLES',
     'NO_ZERO_IN_DATE', 'NO_ZERO_DATE', 'ERROR_FOR_DIVISION_BY_ZERO',
     'NO_AUTO_CREATE_USER', and 'NO_ENGINE_SUBSTITUTION'.

     From MySQL 5.7.4 though 5.7.7, 'TRADITIONAL' is equivalent to
     'STRICT_TRANS_TABLES', 'STRICT_ALL_TABLES', 'NO_AUTO_CREATE_USER',
     and 'NO_ENGINE_SUBSTITUTION'.  The 'NO_ZERO_IN_DATE',
     'NO_ZERO_DATE', and 'ERROR_FOR_DIVISION_BY_ZERO' modes are not
     named because in those versions their effects are included in the
     effects of strict SQL mode ('STRICT_ALL_TABLES' or
     'STRICT_TRANS_TABLES').  Thus, the effects of 'TRADITIONAL' are the
     same in all MySQL 5.7 versions (and the same as in MySQL 5.6).  For
     additional discussion, see sql-mode-changes.

*Strict SQL Mode*

Strict mode controls how MySQL handles invalid or missing values in
data-change statements such as 'INSERT' or
'UPDATE'.  A value can be invalid for several reasons.  For
example, it might have the wrong data type for the column, or it might
be out of range.  A value is missing when a new row to be inserted does
not contain a value for a non-'NULL' column that has no explicit
'DEFAULT' clause in its definition.  (For a 'NULL' column, 'NULL' is
inserted if the value is missing.)  Strict mode also affects DDL
statements such as 'CREATE TABLE'.

If strict mode is not in effect, MySQL inserts adjusted values for
invalid or missing values and produces warnings (see
show-warnings).  In strict mode, you can produce this behavior by
using 'INSERT IGNORE' or 'UPDATE IGNORE'.

For statements such as 'SELECT' that do not change data,
invalid values generate a warning in strict mode, not an error.

Strict mode produces an error for attempts to create a key that exceeds
the maximum key length.  When strict mode is not enabled, this results
in a warning and truncation of the key to the maximum key length.

Strict mode does not affect whether foreign key constraints are checked.
'foreign_key_checks' can be used for that.  (See
server-system-variables.)

Strict SQL mode is in effect if either 'STRICT_ALL_TABLES' or
'STRICT_TRANS_TABLES' is enabled, although the effects of these modes
differ somewhat:

   * For transactional tables, an error occurs for invalid or missing
     values in a data-change statement when either 'STRICT_ALL_TABLES'
     or 'STRICT_TRANS_TABLES' is enabled.  The statement is aborted and
     rolled back.

   * For nontransactional tables, the behavior is the same for either
     mode if the bad value occurs in the first row to be inserted or
     updated: The statement is aborted and the table remains unchanged.
     If the statement inserts or modifies multiple rows and the bad
     value occurs in the second or later row, the result depends on
     which strict mode is enabled:

        * For 'STRICT_ALL_TABLES', MySQL returns an error and ignores
          the rest of the rows.  However, because the earlier rows have
          been inserted or updated, the result is a partial update.  To
          avoid this, use single-row statements, which can be aborted
          without changing the table.

        * For 'STRICT_TRANS_TABLES', MySQL converts an invalid value to
          the closest valid value for the column and inserts the
          adjusted value.  If a value is missing, MySQL inserts the
          implicit default value for the column data type.  In either
          case, MySQL generates a warning rather than an error and
          continues processing the statement.  Implicit defaults are
          described in data-type-defaults.

Strict mode affects handling of division by zero, zero dates, and zeros
in dates as follows:

   * Strict mode affects handling of division by zero, which includes
     'MOD(N,0)':

     For data-change operations (see 'INSERT', 'UPDATE'):

        * If strict mode is not enabled, division by zero inserts 'NULL'
          and produces no warning.

        * If strict mode is enabled, division by zero produces an error,
          unless 'IGNORE' is given as well.  For 'INSERT IGNORE' and
          'UPDATE IGNORE', division by zero inserts 'NULL' and produces
          a warning.

     For 'SELECT', division by zero returns 'NULL'.
     Enabling strict mode causes a warning to be produced as well.

   * Strict mode affects whether the server permits ''0000-00-00'' as a
     valid date:

        * If strict mode is not enabled, ''0000-00-00'' is permitted and
          inserts produce no warning.

        * If strict mode is enabled, ''0000-00-00'' is not permitted and
          inserts produce an error, unless 'IGNORE' is given as well.
          For 'INSERT IGNORE' and 'UPDATE IGNORE', ''0000-00-00'' is
          permitted and inserts produce a warning.

   * Strict mode affects whether the server permits dates in which the
     year part is nonzero but the month or day part is 0 (dates such as
     ''2010-00-01'' or ''2010-01-00''):

        * If strict mode is not enabled, dates with zero parts are
          permitted and inserts produce no warning.

        * If strict mode is enabled, dates with zero parts are not
          permitted and inserts produce an error, unless 'IGNORE' is
          given as well.  For 'INSERT IGNORE' and 'UPDATE IGNORE', dates
          with zero parts are inserted as ''0000-00-00'' (which is
          considered valid with 'IGNORE') and produce a warning.

For more information about strict mode with respect to 'IGNORE', see
ignore-strict-comparison.

Before MySQL 5.7.4, and in MySQL 5.7.8 and later, strict mode affects
handling of division by zero, zero dates, and zeros in dates in
conjunction with the 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and
'NO_ZERO_IN_DATE' modes.  From MySQL 5.7.4 though 5.7.7, the
'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and 'NO_ZERO_IN_DATE'
modes do nothing when named explicitly and their effects are included in
the effects of strict mode.  For additional discussion, see
sql-mode-changes.

*Comparison of the IGNORE Keyword and Strict SQL Mode*

This section compares the effect on statement execution of the 'IGNORE'
keyword (which downgrades errors to warnings) and strict SQL mode (which
upgrades warnings to errors).  It describes which statements they
affect, and which errors they apply to.

The following table presents a summary comparison of statement behavior
when the default is to produce an error versus a warning.  An example of
when the default is to produce an error is inserting a 'NULL' into a
'NOT NULL' column.  An example of when the default is to produce a
warning is inserting a value of the wrong data type into a column (such
as inserting the string ''abc'' into an integer column).

Operational Mode         When Statement Default   When Statement Default
                         is Error                 is Warning

Without 'IGNORE' or      Error                    Warning
strict SQL mode

With 'IGNORE'            Warning                  Warning (same as
                                                  without 'IGNORE' or
                                                  strict SQL mode)

With strict SQL mode     Error (same as without   Error
                         'IGNORE' or strict SQL
                         mode)

With 'IGNORE' and        Warning                  Warning
strict SQL mode

One conclusion to draw from the table is that when the 'IGNORE' keyword
and strict SQL mode are both in effect, 'IGNORE' takes precedence.  This
means that, although 'IGNORE' and strict SQL mode can be considered to
have opposite effects on error handling, they do not cancel when used
together.

*The Effect of IGNORE on Statement Execution*

Several statements in MySQL support an optional 'IGNORE' keyword.  This
keyword causes the server to downgrade certain types of errors and
generate warnings instead.  For a multiple-row statement, 'IGNORE'
causes the statement to skip to the next row instead of aborting.

For example, if the table 't' has a primary key column 'i', attempting
to insert the same value of 'i' into multiple rows normally produces a
duplicate-key error:

     mysql> INSERT INTO t (i) VALUES(1),(1);
     ERROR 1062 (23000): Duplicate entry '1' for key 'PRIMARY'

With 'IGNORE', the row containing the duplicate key still is not
inserted, but a warning occurs instead of an error:

     mysql> INSERT IGNORE INTO t (i) VALUES(1),(1);
     Query OK, 1 row affected, 1 warning (0.01 sec)
     Records: 2  Duplicates: 1  Warnings: 1

     mysql> SHOW WARNINGS;
     +---------+------+---------------------------------------+
     | Level   | Code | Message                               |
     +---------+------+---------------------------------------+
     | Warning | 1062 | Duplicate entry '1' for key 'PRIMARY' |
     +---------+------+---------------------------------------+
     1 row in set (0.00 sec)

These statements support the 'IGNORE' keyword:

   * 'CREATE TABLE ... SELECT'.: 'IGNORE' does not
     apply to the 'CREATE TABLE' or 'SELECT'
     parts of the statement but to inserts into the table of
     rows produced by the 'SELECT'.  Rows that duplicate
     an existing row on a unique key value are discarded.

   * 'DELETE'.: 'IGNORE' causes MySQL to ignore errors
     during the process of deleting rows.

   * 'INSERT'.: With 'IGNORE', rows that duplicate an
     existing row on a unique key value are discarded.  Rows set to
     values that would cause data conversion errors are set to the
     closest valid values instead.

     For partitioned tables where no partition matching a given value is
     found, 'IGNORE' causes the insert operation to fail silently for
     rows containing the unmatched value.

   * 'LOAD DATA', 'LOAD XML'.: With
     'IGNORE', rows that duplicate an existing row on a unique key value
     are discarded.

   * 'UPDATE'.: With 'IGNORE', rows for which
     duplicate-key conflicts occur on a unique key value are not
     updated.  Rows updated to values that would cause data conversion
     errors are updated to the closest valid values instead.

The 'IGNORE' keyword applies to the following errors:

     ER_BAD_NULL_ERROR
     ER_DUP_ENTRY
     ER_DUP_ENTRY_WITH_KEY_NAME
     ER_DUP_KEY
     ER_NO_PARTITION_FOR_GIVEN_VALUE
     ER_NO_PARTITION_FOR_GIVEN_VALUE_SILENT
     ER_NO_REFERENCED_ROW_2
     ER_ROW_DOES_NOT_MATCH_GIVEN_PARTITION_SET
     ER_ROW_IS_REFERENCED_2
     ER_SUBQUERY_NO_1_ROW
     ER_VIEW_CHECK_FAILED

*The Effect of Strict SQL Mode on Statement Execution*

The MySQL server can operate in different SQL modes, and can apply these
modes differently for different clients, depending on the value of the
'sql_mode' system variable.  In 'strict' SQL mode, the server upgrades
certain warnings to errors.

For example, in non-strict SQL mode, inserting the string ''abc'' into
an integer column results in conversion of the value to 0 and a warning:

     mysql> SET sql_mode = '';
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t (i) VALUES('abc');
     Query OK, 1 row affected, 1 warning (0.01 sec)

     mysql> SHOW WARNINGS;
     +---------+------+--------------------------------------------------------+
     | Level   | Code | Message                                                |
     +---------+------+--------------------------------------------------------+
     | Warning | 1366 | Incorrect integer value: 'abc' for column 'i' at row 1 |
     +---------+------+--------------------------------------------------------+
     1 row in set (0.00 sec)

In strict SQL mode, the invalid value is rejected with an error:

     mysql> SET sql_mode = 'STRICT_ALL_TABLES';
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t (i) VALUES('abc');
     ERROR 1366 (HY000): Incorrect integer value: 'abc' for column 'i' at row 1

For more information about possible settings of the 'sql_mode' system
variable, see sql-mode.

Strict SQL mode applies to the following statements under conditions for
which some value might be out of range or an invalid row is inserted
into or deleted from a table:

   * 'ALTER TABLE'.

   * 'CREATE TABLE'.

   * 'CREATE TABLE ... SELECT'.

   * 'DELETE'. (both single table and multiple table)

   * 'INSERT'.

   * 'LOAD DATA'.

   * 'LOAD XML'.

   * 'SELECT SLEEP()'.

   * 'UPDATE'. (both single table and multiple table)

Within stored programs, individual statements of the types just listed
execute in strict SQL mode if the program was defined while strict mode
was in effect.

Strict SQL mode applies to the following errors, represent a class of
errors in which an input value is either invalid or missing.  A value is
invalid if it has the wrong data type for the column or might be out of
range.  A value is missing if a new row to be inserted does not contain
a value for a 'NOT NULL' column that has no explicit 'DEFAULT' clause in
its definition.

     ER_BAD_NULL_ERROR
     ER_CUT_VALUE_GROUP_CONCAT
     ER_DATA_TOO_LONG
     ER_DATETIME_FUNCTION_OVERFLOW
     ER_DIVISION_BY_ZERO
     ER_INVALID_ARGUMENT_FOR_LOGARITHM
     ER_NO_DEFAULT_FOR_FIELD
     ER_NO_DEFAULT_FOR_VIEW_FIELD
     ER_TOO_LONG_KEY
     ER_TRUNCATED_WRONG_VALUE
     ER_TRUNCATED_WRONG_VALUE_FOR_FIELD
     ER_WARN_DATA_OUT_OF_RANGE
     ER_WARN_NULL_TO_NOTNULL
     ER_WARN_TOO_FEW_RECORDS
     ER_WRONG_ARGUMENTS
     ER_WRONG_VALUE_FOR_TYPE
     WARN_DATA_TRUNCATED

*SQL Mode Changes in MySQL 5.7*

In MySQL 5.7.22, these SQL modes are deprecated and will be removed in a
future version of MySQL: 'DB2', 'MAXDB', 'MSSQL', 'MYSQL323', 'MYSQL40',
'ORACLE', 'POSTGRESQL', 'NO_FIELD_OPTIONS', 'NO_KEY_OPTIONS',
'NO_TABLE_OPTIONS'.

In MySQL 5.7, the 'ONLY_FULL_GROUP_BY' SQL mode is enabled by default
because 'GROUP BY' processing has become more sophisticated to include
detection of functional dependencies.  However, if you find that having
'ONLY_FULL_GROUP_BY' enabled causes queries for existing applications to
be rejected, either of these actions should restore operation:

   * If it is possible to modify an offending query, do so, either so
     that nonaggregated columns are functionally dependent on 'GROUP BY'
     columns, or by referring to nonaggregated columns using
     'ANY_VALUE()'.

   * If it is not possible to modify an offending query (for example, if
     it is generated by a third-party application), set the 'sql_mode'
     system variable at server startup to not enable
     'ONLY_FULL_GROUP_BY'.

In MySQL 5.7, the 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and
'NO_ZERO_IN_DATE' SQL modes are deprecated.  The long term plan is to
have the three modes be included in strict SQL mode and to remove them
as explicit modes in a future MySQL release.  For compatibility in MySQL
5.7 with MySQL 5.6 strict mode and to provide additional time for
affected applications to be modified, the following behaviors apply:

   * 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and 'NO_ZERO_IN_DATE'
     are not part of strict SQL mode, but it is intended that they be
     used together with strict mode.  As a reminder, a warning occurs if
     they are enabled without also enabling strict mode or vice versa.

   * 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_ZERO_DATE', and 'NO_ZERO_IN_DATE'
     are enabled by default.

With the preceding changes, stricter data checking is still enabled by
default, but the individual modes can be disabled in environments where
it is currently desirable or necessary to do so.

5.1.9 IPv6 Support
------------------

Support for IPv6 in MySQL includes these capabilities:

   * MySQL Server can accept TCP/IP connections from clients connecting
     over IPv6.  For example, this command connects over IPv6 to the
     MySQL server on the local host:

          shell> mysql -h ::1

     To use this capability, two things must be true:

        * Your system must be configured to support IPv6.  See
          ipv6-system-support.

        * The default MySQL server configuration permits IPv6
          connections in addition to IPv4 connections.  To change the
          default configuration, start the server with an appropriate
          '--bind-address' option.  See server-system-variables.

   * MySQL account names permit IPv6 addresses to enable DBAs to specify
     privileges for clients that connect to the server over IPv6.  See
     account-names.  IPv6 addresses can be specified in account
     names in statements such as 'CREATE USER',
     'GRANT', and 'REVOKE'.  For example:

          mysql> CREATE USER 'bill'@'::1' IDENTIFIED BY 'secret';
          mysql> GRANT SELECT ON mydb.* TO 'bill'@'::1';

   * IPv6 functions enable conversion between string and internal format
     IPv6 address formats, and checking whether values represent valid
     IPv6 addresses.  For example, 'INET6_ATON()' and 'INET6_NTOA()' are
     similar to 'INET_ATON()' and 'INET_NTOA()', but handle IPv6
     addresses in addition to IPv4 addresses.  See
     miscellaneous-functions.

The following sections describe how to set up MySQL so that clients can
connect to the server over IPv6.

5.1.9.1 Verifying System Support for IPv6
.........................................

Before MySQL Server can accept IPv6 connections, the operating system on
your server host must support IPv6.  As a simple test to determine
whether that is true, try this command:

     shell> ping6 ::1
     16 bytes from ::1, icmp_seq=0 hlim=64 time=0.171 ms
     16 bytes from ::1, icmp_seq=1 hlim=64 time=0.077 ms
     ...

To produce a description of your system's network interfaces, invoke
'ifconfig -a' and look for IPv6 addresses in the output.

If your host does not support IPv6, consult your system documentation
for instructions on enabling it.  It might be that you need only
reconfigure an existing network interface to add an IPv6 address.  Or a
more extensive change might be needed, such as rebuilding the kernel
with IPv6 options enabled.

These links may be helpful in setting up IPv6 on various platforms:

   * Windows (https://msdn.microsoft.com/en-us/library/dd163569.aspx)

   * Gentoo Linux (http://www.gentoo.org/doc/en/ipv6.xml)

   * Ubuntu Linux (https://wiki.ubuntu.com/IPv6)

   * Linux (Generic) (http://www.tldp.org/HOWTO/Linux+IPv6-HOWTO/)

   * OS X (https://support.apple.com/en-us/HT202237)

5.1.9.2 Configuring the MySQL Server to Permit IPv6 Connections
...............................................................

The MySQL server listens on a single network socket for TCP/IP
connections.  This socket is bound to a single address, but it is
possible for an address to map onto multiple network interfaces.  To
specify an address, use the '--bind-address=ADDR' option at server
startup, where ADDR is an IPv4 or IPv6 address or a host name.  (IPv6
addresses are not supported before MySQL 5.5.3.)  If ADDR is a host
name, the server resolves the name to an IP address and binds to that
address.

The server treats different types of addresses as follows:

   * If the address is '*', the server accepts TCP/IP connections on all
     server host IPv6 and IPv4 interfaces if the server host supports
     IPv6, or accepts TCP/IP connections on all IPv4 addresses
     otherwise.  Use this address to permit both IPv4 and IPv6
     connections on all server interfaces.  This value is the default.

   * If the address is '0.0.0.0', the server accepts TCP/IP connections
     on all server host IPv4 interfaces.

   * If the address is '::', the server accepts TCP/IP connections on
     all server host IPv4 and IPv6 interfaces.  Use this address to
     permit both IPv4 and IPv6 connections on all server interfaces.

   * If the address is an IPv4-mapped address, the server accepts TCP/IP
     connections for that address, in either IPv4 or IPv6 format.  For
     example, if the server is bound to '::ffff:127.0.0.1', clients can
     connect using '--host=127.0.0.1' or '--host=::ffff:127.0.0.1'.

   * If the address is a 'regular' IPv4 or IPv6 address (such as
     '127.0.0.1' or '::1'), the server accepts TCP/IP connections only
     for that IPv4 or IPv6 address.

If you intend to bind the server to a specific address, be sure that the
'mysql.user' grant table contains an account with administrative
privileges that you can use to connect to that address.  Otherwise, you
will not be able to shut down the server.  For example, if you bind the
server to '*', you can connect to it using all existing accounts.  But
if you bind the server to '::1', it accepts connections only on that
address.  In that case, first make sure that the ''root'@'::1'' account
is present in the 'mysql.user' table so you can still connect to the
server to shut it down.

5.1.9.3 Connecting Using the IPv6 Local Host Address
....................................................

The following procedure shows how to configure MySQL to permit IPv6
connections by clients that connect to the local server using the '::1'
local host address.  The instructions given here assume that your system
supports IPv6.

  1. Start the MySQL server with an appropriate '--bind-address' option
     to permit it to accept IPv6 connections.  For example, put the
     following lines in your server option file and restart the server:

          [mysqld]
          bind-address = *

     Alternatively, you can bind the server to '::1', but that makes the
     server more restrictive for TCP/IP connections.  It accepts only
     IPv6 connections for that single address and rejects IPv4
     connections.  For more information, see ipv6-server-config.

  2. As an administrator, connect to the server and create an account
     for a local user who will connect from the '::1' local IPv6 host
     address:

          mysql> CREATE USER 'ipv6user'@'::1' IDENTIFIED BY 'ipv6pass';

     For the permitted syntax of IPv6 addresses in account names, see
     account-names.  In addition to the 'CREATE USER'
     statement, you can issue 'GRANT'.
     statements that give specific privileges to the account, although
     that is not necessary for the remaining steps in this procedure.

  3. Invoke the 'mysql' client to connect to the server
     using the new account:

          shell> mysql -h ::1 -u ipv6user -pipv6pass

  4. Try some simple statements that show connection information:

          mysql> STATUS
          ...
          Connection:   ::1 via TCP/IP
          ...

          mysql> SELECT CURRENT_USER(), @@bind_address;
          +----------------+----------------+
          | CURRENT_USER() | @@bind_address |
          +----------------+----------------+
          | ipv6user@::1   | ::             |
          +----------------+----------------+

5.1.9.4 Connecting Using IPv6 Nonlocal Host Addresses
.....................................................

The following procedure shows how to configure MySQL to permit IPv6
connections by remote clients.  It is similar to the preceding procedure
for local clients, but the server and client hosts are distinct and each
has its own nonlocal IPv6 address.  The example uses these addresses:

     Server host: 2001:db8:0:f101::1
     Client host: 2001:db8:0:f101::2

These addresses are chosen from the nonroutable address range
recommended by IANA
(http://www.iana.org/assignments/ipv6-unicast-address-assignments/ipv6-unicast-address-assignments.xml)
for documentation purposes and suffice for testing on your local
network.  To accept IPv6 connections from clients outside the local
network, the server host must have a public address.  If your network
provider assigns you an IPv6 address, you can use that.  Otherwise,
another way to obtain an address is to use an IPv6 broker; see
ipv6-brokers.

  1. Start the MySQL server with an appropriate '--bind-address' option
     to permit it to accept IPv6 connections.  For example, put the
     following lines in your server option file and restart the server:

          [mysqld]
          bind-address = *

     Alternatively, you can bind the server to '2001:db8:0:f101::1', but
     that makes the server more restrictive for TCP/IP connections.  It
     accepts only IPv6 connections for that single address and rejects
     IPv4 connections.  For more information, see
     ipv6-server-config.

  2. On the server host ('2001:db8:0:f101::1'), create an account for a
     user who will connect from the client host ('2001:db8:0:f101::2'):

          mysql> CREATE USER 'remoteipv6user'@'2001:db8:0:f101::2' IDENTIFIED BY 'remoteipv6pass';

  3. On the client host ('2001:db8:0:f101::2'), invoke the
     'mysql' client to connect to the server using the new
     account:

          shell> mysql -h 2001:db8:0:f101::1 -u remoteipv6user -premoteipv6pass

  4. Try some simple statements that show connection information:

          mysql> STATUS
          ...
          Connection:   2001:db8:0:f101::1 via TCP/IP
          ...

          mysql> SELECT CURRENT_USER(), @@bind_address;
          +-----------------------------------+----------------+
          | CURRENT_USER()                    | @@bind_address |
          +-----------------------------------+----------------+
          | remoteipv6user@2001:db8:0:f101::2 | ::             |
          +-----------------------------------+----------------+

5.1.9.5 Obtaining an IPv6 Address from a Broker
...............................................

If you do not have a public IPv6 address that enables your system to
communicate over IPv6 outside your local network, you can obtain one
from an IPv6 broker.  The Wikipedia IPv6 Tunnel Broker page
(http://en.wikipedia.org/wiki/List_of_IPv6_tunnel_brokers) lists several
brokers and their features, such as whether they provide static
addresses and the supported routing protocols.

After configuring your server host to use a broker-supplied IPv6
address, start the MySQL server with an appropriate '--bind-address'
option to permit the server to accept IPv6 connections.  For example,
put the following lines in the server option file and restart the
server:

     [mysqld]
     bind-address = *

Alternatively, you can bind the server to the specific IPv6 address
provided by the broker, but that makes the server more restrictive for
TCP/IP connections.  It accepts only IPv6 connections for that single
address and rejects IPv4 connections.  For more information, see
ipv6-server-config.  In addition, if the broker allocates dynamic
addresses, the address provided for your system might change the next
time you connect to the broker.  If so, any accounts you create that
name the original address become invalid.  To bind to a specific address
but avoid this change-of-address problem, you may be able to arrange
with the broker for a static IPv6 address.

The following example shows how to use Freenet6 as the broker and the
'gogoc' IPv6 client package on Gentoo Linux.

  1. Create an account at Freenet6 by visiting this URL and signing up:

          <http://gogonet.gogo6.com>

  2. After creating the account, go to this URL, sign in, and create a
     user ID and password for the IPv6 broker:

          <http://gogonet.gogo6.com/page/freenet6-registration>

  3. As 'root', install 'gogoc':

          shell> emerge gogoc

  4. Edit '/etc/gogoc/gogoc.conf' to set the 'userid' and 'password'
     values.  For example:

          userid=gogouser
          passwd=gogopass

  5. Start 'gogoc':

          shell> /etc/init.d/gogoc start

     To start 'gogoc' each time your system boots, execute this command:

          shell> rc-update add gogoc default

  6. Use 'ping6' to try to ping a host:

          shell> ping6 ipv6.google.com

  7. To see your IPv6 address:

          shell> ifconfig tun

5.1.10 MySQL Server Time Zone Support
-------------------------------------

MySQL Server maintains several time zone settings:

   * The system time zone.  When the server starts, it attempts to
     determine the time zone of the host machine and uses it to set the
     'system_time_zone' system variable.  The value does not change
     thereafter.

     You can set the system time zone for MySQL Server at startup with
     the '--timezone=TIMEZONE_NAME' option to 'mysqld_safe'.
     You can also set it by setting the 'TZ' environment
     variable before you start 'mysqld'.  The permissible
     values for '--timezone' or 'TZ' are system dependent.  Consult your
     operating system documentation to see what values are acceptable.

   * The server's current time zone.  The global 'time_zone' system
     variable indicates the time zone the server currently is operating
     in.  The initial value for 'time_zone' is ''SYSTEM'', which
     indicates that the server time zone is the same as the system time
     zone.

     *Note*:

     If set to 'SYSTEM', every MySQL function call that requires a
     timezone calculation makes a system library call to determine the
     current system timezone.  This call may be protected by a global
     mutex, resulting in contention.

     The initial global server time zone value can be specified
     explicitly at startup with the '--default-time-zone=TIMEZONE'
     option on the command line, or you can use the following line in an
     option file:

          default-time-zone='TIMEZONE'

     If you have the 'SUPER' privilege, you can set the global server
     time zone value at runtime with this statement:

          mysql> SET GLOBAL time_zone = TIMEZONE;

   * Per-connection time zones.  Each client that connects has its own
     time zone setting, given by the session 'time_zone' variable.
     Initially, the session variable takes its value from the global
     'time_zone' variable, but the client can change its own time zone
     with this statement:

          mysql> SET time_zone = TIMEZONE;

The current session time zone setting affects display and storage of
time values that are zone-sensitive.  This includes the values displayed
by functions such as 'NOW()' or 'CURTIME()', and values stored in and
retrieved from 'TIMESTAMP' columns.  Values for
'TIMESTAMP' columns are converted from the current time zone
to UTC for storage, and from UTC to the current time zone for retrieval.

The current time zone setting does not affect values displayed by
functions such as 'UTC_TIMESTAMP()' or values in 'DATE',
'TIME', or 'DATETIME' columns.  Nor are
values in those data types stored in UTC; the time zone applies for them
only when converting from 'TIMESTAMP' values.  If you want
locale-specific arithmetic for 'DATE', 'TIME',
or 'DATETIME' values, convert them to UTC,
perform the arithmetic, and then convert back.

The current values of the global and client-specific time zones can be
retrieved like this:

     mysql> SELECT @@global.time_zone, @@session.time_zone;

TIMEZONE values can be given in several formats, none of which are
case-sensitive:

   * The value ''SYSTEM'' indicates that the time zone should be the
     same as the system time zone.

   * The value can be given as a string indicating an offset from UTC,
     such as ''+10:00'' or ''-6:00''.

   * The value can be given as a named time zone, such as
     ''Europe/Helsinki'', ''US/Eastern'', or ''MET''.  Named time zones
     can be used only if the time zone information tables in the 'mysql'
     database have been created and populated.

*Populating the Time Zone Tables*

Several tables in the 'mysql' system database exist to maintain time
zone information (see system-database).  The MySQL installation
procedure creates the time zone tables, but does not load them.  You
must do so manually using the following instructions.

*Note*:

Loading the time zone information is not necessarily a one-time
operation because the information changes occasionally.  When such
changes occur, applications that use the old rules become out of date
and you may find it necessary to reload the time zone tables to keep the
information used by your MySQL server current.  See the notes at the end
of this section.

If your system has its own _zoneinfo_ database (the set of files
describing time zones), you should use the 'mysql_tzinfo_to_sql'
program for filling the time zone tables.  Examples
of such systems are Linux, FreeBSD, Solaris, and OS X. One likely
location for these files is the '/usr/share/zoneinfo' directory.  If
your system does not have a zoneinfo database, you can use the
downloadable package described later in this section.

The 'mysql_tzinfo_to_sql' program is used to
load the time zone tables.  On the command line, pass the zoneinfo
directory path name to 'mysql_tzinfo_to_sql'.
and send the output into the 'mysql' program.  For
example:

     shell> mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

'mysql_tzinfo_to_sql' reads your system's
time zone files and generates SQL statements from them.  'mysql'
processes those statements to load the time zone tables.

'mysql_tzinfo_to_sql' also can be used to
load a single time zone file or to generate leap second information:

   * To load a single time zone file TZ_FILE that corresponds to a time
     zone name TZ_NAME, invoke 'mysql_tzinfo_to_sql'
     like this:

          shell> mysql_tzinfo_to_sql TZ_FILE TZ_NAME | mysql -u root mysql

     With this approach, you must execute a separate command to load the
     time zone file for each named zone that the server needs to know
     about.

   * If your time zone needs to account for leap seconds, initialize the
     leap second information like this, where TZ_FILE is the name of
     your time zone file:

          shell> mysql_tzinfo_to_sql --leap TZ_FILE | mysql -u root mysql

   * After running 'mysql_tzinfo_to_sql', it
     is best to restart the server so that it does not continue to use
     any previously cached time zone data.

If your system is one that has no zoneinfo database (for example,
Windows), you can use a package that is available for download at the
MySQL Developer Zone:

     <http://dev.mysql.com/downloads/timezones.html>

Download a time zone package that contains SQL statements and unpack it,
then load the package file contents into the time zone tables:

     shell> mysql -u root mysql < FILE_NAME

Then restart the server.

*Warning*:

Do _not_ use a downloadable package that contains 'MyISAM' tables.
MySQL 5.7 and up uses 'InnoDB' for the time zone tables.  Trying to
replace them with 'MyISAM' tables will cause problems.

*Warning*:

Do not use a downloadable package if your system has a zoneinfo
database.  Use the 'mysql_tzinfo_to_sql'.
utility instead.  Otherwise, you may cause a difference in datetime
handling between MySQL and other applications on your system.

For information about time zone settings in replication setup, please
see replication-features.

5.1.10.1 Staying Current with Time Zone Changes
...............................................

When time zone rules change, applications that use the old rules become
out of date.  To stay current, it is necessary to make sure that your
system uses current time zone information is used.  For MySQL, there are
two factors to consider in staying current:

   * The operating system time affects the value that the MySQL server
     uses for times if its time zone is set to 'SYSTEM'.  Make sure that
     your operating system is using the latest time zone information.
     For most operating systems, the latest update or service pack
     prepares your system for the time changes.  Check the website for
     your operating system vendor for an update that addresses the time
     changes.

   * If you replace the system's '/etc/localtime' timezone file with a
     version that uses rules differing from those in effect at
     'mysqld' startup, you should restart 'mysqld'
     so that it uses the updated rules.  Otherwise, see
     'mysqld' might not notice when the system changes its
     time.

   * If you use named time zones with MySQL, make sure that the time
     zone tables in the 'mysql' database are up to date.  If your system
     has its own zoneinfo database, you should reload the MySQL time
     zone tables whenever the zoneinfo database is updated.  For systems
     that do not have their own zoneinfo database, check the MySQL
     Developer Zone for updates.  When a new update is available,
     download it and use it to replace the content of your current time
     zone tables.  For instructions for both methods, see
     time-zone-installation.  'mysqld' caches time zone
     information that it looks up, so after updating the time zone
     tables, you should restart 'mysqld' to make sure
     that it does not continue to serve outdated time zone data.

If you are uncertain whether named time zones are available, for use
either as the server's time zone setting or by clients that set their
own time zone, check whether your time zone tables are empty.  The
following query determines whether the table that contains time zone
names has any rows:

     mysql> SELECT COUNT(*) FROM mysql.time_zone_name;
     +----------+
     | COUNT(*) |
     +----------+
     |        0 |
     +----------+

A count of zero indicates that the table is empty.  In this case, no one
can be using named time zones, and you don't need to update the tables.
A count greater than zero indicates that the table is not empty and that
its contents are available to be used for named time zone support.  In
this case, you should be sure to reload your time zone tables so that
anyone who uses named time zones will get correct query results.

To check whether your MySQL installation is updated properly for a
change in Daylight Saving Time rules, use a test like the one following.
The example uses values that are appropriate for the 2007 DST 1-hour
change that occurs in the United States on March 11 at 2 a.m.

The test uses these two queries:

     SELECT CONVERT_TZ('2007-03-11 2:00:00','US/Eastern','US/Central');
     SELECT CONVERT_TZ('2007-03-11 3:00:00','US/Eastern','US/Central');

The two time values indicate the times at which the DST change occurs,
and the use of named time zones requires that the time zone tables be
used.  The desired result is that both queries return the same result
(the input time, converted to the equivalent value in the 'US/Central'
time zone).

Before updating the time zone tables, you would see an incorrect result
like this:

     mysql> SELECT CONVERT_TZ('2007-03-11 2:00:00','US/Eastern','US/Central');
     +------------------------------------------------------------+
     | CONVERT_TZ('2007-03-11 2:00:00','US/Eastern','US/Central') |
     +------------------------------------------------------------+
     | 2007-03-11 01:00:00                                        |
     +------------------------------------------------------------+

     mysql> SELECT CONVERT_TZ('2007-03-11 3:00:00','US/Eastern','US/Central');
     +------------------------------------------------------------+
     | CONVERT_TZ('2007-03-11 3:00:00','US/Eastern','US/Central') |
     +------------------------------------------------------------+
     | 2007-03-11 02:00:00                                        |
     +------------------------------------------------------------+

After updating the tables, you should see the correct result:

     mysql> SELECT CONVERT_TZ('2007-03-11 2:00:00','US/Eastern','US/Central');
     +------------------------------------------------------------+
     | CONVERT_TZ('2007-03-11 2:00:00','US/Eastern','US/Central') |
     +------------------------------------------------------------+
     | 2007-03-11 01:00:00                                        |
     +------------------------------------------------------------+

     mysql> SELECT CONVERT_TZ('2007-03-11 3:00:00','US/Eastern','US/Central');
     +------------------------------------------------------------+
     | CONVERT_TZ('2007-03-11 3:00:00','US/Eastern','US/Central') |
     +------------------------------------------------------------+
     | 2007-03-11 01:00:00                                        |
     +------------------------------------------------------------+

5.1.10.2 Time Zone Leap Second Support
......................................

Leap second values are returned with a time part that ends with
':59:59'.  This means that a function such as 'NOW()' can return the
same value for two or three consecutive seconds during the leap second.
It remains true that literal temporal values having a time part that
ends with ':59:60' or ':59:61' are considered invalid.

If it is necessary to search for 'TIMESTAMP' values one
second before the leap second, anomalous results may be obtained if you
use a comparison with ''YYYY-MM-DD hh:mm:ss'' values.  The following
example demonstrates this.  It changes the local time zone to UTC so
there is no difference between internal values (which are in UTC) and
displayed values (which have time zone correction applied).

     mysql> CREATE TABLE t1 (
              a INT,
              ts TIMESTAMP DEFAULT NOW(),
              PRIMARY KEY (ts)
            );
     Query OK, 0 rows affected (0.01 sec)

     mysql> -- change to UTC
     mysql> SET time_zone = '+00:00';
     Query OK, 0 rows affected (0.00 sec)

     mysql> -- Simulate NOW() = '2008-12-31 23:59:59'
     mysql> SET timestamp = 1230767999;
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t1 (a) VALUES (1);
     Query OK, 1 row affected (0.00 sec)

     mysql> -- Simulate NOW() = '2008-12-31 23:59:60'
     mysql> SET timestamp = 1230768000;
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t1 (a) VALUES (2);
     Query OK, 1 row affected (0.00 sec)

     mysql> -- values differ internally but display the same
     mysql> SELECT a, ts, UNIX_TIMESTAMP(ts) FROM t1;
     +------+---------------------+--------------------+
     | a    | ts                  | UNIX_TIMESTAMP(ts) |
     +------+---------------------+--------------------+
     |    1 | 2008-12-31 23:59:59 |         1230767999 |
     |    2 | 2008-12-31 23:59:59 |         1230768000 |
     +------+---------------------+--------------------+
     2 rows in set (0.00 sec)

     mysql> -- only the non-leap value matches
     mysql> SELECT * FROM t1 WHERE ts = '2008-12-31 23:59:59';
     +------+---------------------+
     | a    | ts                  |
     +------+---------------------+
     |    1 | 2008-12-31 23:59:59 |
     +------+---------------------+
     1 row in set (0.00 sec)

     mysql> -- the leap value with seconds=60 is invalid
     mysql> SELECT * FROM t1 WHERE ts = '2008-12-31 23:59:60';
     Empty set, 2 warnings (0.00 sec)

To work around this, you can use a comparison based on the UTC value
actually stored in column, which has the leap second correction applied:

     mysql> -- selecting using UNIX_TIMESTAMP value return leap value
     mysql> SELECT * FROM t1 WHERE UNIX_TIMESTAMP(ts) = 1230768000;
     +------+---------------------+
     | a    | ts                  |
     +------+---------------------+
     |    2 | 2008-12-31 23:59:59 |
     +------+---------------------+
     1 row in set (0.00 sec)

5.1.11 Server-Side Help
-----------------------

MySQL Server supports a 'HELP' statement that returns
information from the MySQL Reference manual (see help).  Several
tables in the 'mysql' system database contain the information needed to
support this statement (see system-database).  The proper
operation of this statement requires that these help tables be
initialized, which is done by processing the contents of the
'fill_help_tables.sql' script.

If you install MySQL using a binary or source distribution on Unix, help
table content initialization occurs when you initialize the data
directory (see data-directory-initialization).  For an RPM
distribution on Linux or binary distribution on Windows, content
initialization occurs as part of the MySQL installation process.

If you upgrade MySQL using a binary distribution, help table content is
not upgraded automatically, but you can upgrade it manually.  Locate the
'fill_help_tables.sql' file in the 'share' or 'share/mysql' directory.
Change location into that directory and process the file with the
'mysql' client as follows:

     shell> mysql -u root mysql < fill_help_tables.sql

You can also obtain the latest 'fill_help_tables.sql' at any time to
upgrade your help tables.  Download the proper file for your version of
MySQL from <http://dev.mysql.com/doc/index-other.html>.  After
downloading and uncompressing the file, process it with 'mysql'
as described previously.

If you are working with Git and a MySQL development source tree, you
must use a downloaded copy of the 'fill_help_tables.sql' file because
the source tree contains only a 'stub' version.

*Note*:

For a server that participates in replication, the help table content
upgrade process involves multiple servers.  For details, see
replication-features-server-side-help.

5.1.12 Server Response to Signals
---------------------------------

On Unix, signals can be sent to processes.  See 'mysqld'.
responds to signals sent to it as follows:

   * 'SIGTERM' causes the server to shut down.

   * 'SIGHUP' causes the server to reload the grant tables and to flush
     tables, logs, the thread cache, and the host cache.  These actions
     are like various forms of the 'FLUSH' statement.  The
     server also writes a status report to the error log that has this
     format:

          Status information:

          Current dir: /var/mysql/data/
          Running threads: 0  Stack size: 196608
          Current locks:

          Key caches:
          default
          Buffer_size:       8388600
          Block_size:           1024
          Division_limit:        100
          Age_limit:             300
          blocks used:             0
          not flushed:             0
          w_requests:              0
          writes:                  0
          r_requests:              0
          reads:                   0

          handler status:
          read_key:            0
          read_next:           0
          read_rnd             0
          read_first:          1
          write:               0
          delete               0
          update:              0

          Table status:
          Opened tables:          5
          Open tables:            0
          Open files:             7
          Open streams:           0

          Alarm status:
          Active alarms:   1
          Max used alarms: 2
          Next alarm time: 67

5.1.13 The Server Shutdown Process
----------------------------------

The server shutdown process takes place as follows:

  1. The shutdown process is initiated.

     This can occur initiated several ways.  For example, a user with
     the 'SHUTDOWN' privilege can execute a 'mysqladmin shutdown'
     command.  'mysqladmin' can be used
     on any platform supported by MySQL. Other operating system-specific
     shutdown initiation methods are possible as well: The server shuts
     down on Unix when it receives a 'SIGTERM' signal.  A server running
     as a service on Windows shuts down when the services manager tells
     it to.

  2. The server creates a shutdown thread if necessary.

     Depending on how shutdown was initiated, the server might create a
     thread to handle the shutdown process.  If shutdown was requested
     by a client, a shutdown thread is created.  If shutdown is the
     result of receiving a 'SIGTERM' signal, the signal thread might
     handle shutdown itself, or it might create a separate thread to do
     so.  If the server tries to create a shutdown thread and cannot
     (for example, if memory is exhausted), it issues a diagnostic
     message that appears in the error log:

          Error: Can't create thread to kill server

  3. The server stops accepting new connections.

     To prevent new activity from being initiated during shutdown, the
     server stops accepting new client connections by closing the
     handlers for the network interfaces to which it normally listens
     for connections: the TCP/IP port, the Unix socket file, the Windows
     named pipe, and shared memory on Windows.

  4. The server terminates current activity.

     For each thread associated with a client connection, the server
     breaks the connection to the client and marks the thread as killed.
     Threads die when they notice that they are so marked.  Threads for
     idle connections die quickly.  Threads that currently are
     processing statements check their state periodically and take
     longer to die.  For additional information about thread
     termination, see kill, in particular for the instructions
     about killed 'REPAIR TABLE' or 'OPTIMIZE TABLE'
     operations on 'MyISAM' tables.

     For threads that have an open transaction, the transaction is
     rolled back.  If a thread is updating a nontransactional table, an
     operation such as a multiple-row 'UPDATE' or
     'INSERT' may leave the table partially updated because the
     operation can terminate before completion.

     If the server is a master replication server, it treats threads
     associated with currently connected slaves like other client
     threads.  That is, each one is marked as killed and exits when it
     next checks its state.

     If the server is a slave replication server, it stops the I/O and
     SQL threads, if they are active, before marking client threads as
     killed.  The SQL thread is permitted to finish its current
     statement (to avoid causing replication problems), and then stops.
     If the SQL thread is in the middle of a transaction at this point,
     the server waits until the current replication event group (if any)
     has finished executing, or until the user issues a 'KILL QUERY'
     or 'KILL CONNECTION' statement.  See
     also stop-slave.  Since nontransactional statements cannot
     be rolled back, in order to guarantee crash-safe replication, only
     transactional tables should be used.

     *Note*:

     To guarantee crash safety on the slave, you must run the slave with
     '--relay-log-recovery' enabled.

     See also slave-logs).

  5. The server shuts down or closes storage engines.

     At this stage, the server flushes the table cache and closes all
     open tables.

     Each storage engine performs any actions necessary for tables that
     it manages.

     'InnoDB' flushes its buffer pool to disk (unless
     'innodb_fast_shutdown' is 2), writes the current LSN to the
     tablespace, and terminates its own internal threads.  'MyISAM'
     flushes any pending index writes for a table.

  6. The server exits.

To provide information to management processes, the server returns one
of the exit codes described in the following list.  The phrase in
parentheses indicates the action taken by systemd in response to the
code, for platforms on which systemd is used to manage the server.

   * 0 = successful termination (no restart done)

   * 1 = unsuccessful termination (no restart done)

   * 2 = unsuccessful termination (restart done)

5.2 The MySQL Data Directory
============================

Information managed by the MySQL server is stored under a directory
known as the data directory.  The following list briefly describes the
items typically found in the data directory, with cross references for
additional information:

   * Data directory subdirectories.  Each subdirectory of the data
     directory is a database directory and corresponds to a database
     managed by the server.  All MySQL installations have certain
     standard databases:

        * The 'mysql' directory corresponds to the 'mysql' system
          database, which contains information required by the MySQL
          server as it runs.  See system-database.

        * The 'performance_schema' directory corresponds to the
          Performance Schema, which provides information used to inspect
          the internal execution of the server at runtime.  See
          performance-schema.

        * The 'sys' directory corresponds to the 'sys' schema, which
          provides a set of objects to help interpret Performance Schema
          information more easily.  See sys-schema.

        * The 'ndbinfo' directory corresponds to the 'ndbinfo' database
          that stores information specific to NDB Cluster (present only
          for installations built to include NDB Cluster).  See
          mysql-cluster-ndbinfo.

     Other subdirectories correspond to databases created by users or
     applications.

     *Note*:

     'INFORMATION_SCHEMA' is a standard
     database, but its implementation uses no corresponding database
     directory.

   * Log files written by the server.  See server-logs.

   * 'InnoDB' tablespace and log files.  See
     innodb-storage-engine.

   * Default/autogenerated SSL and RSA certificate and key files.  See
     creating-ssl-rsa-files.

   * The server process ID file (while the server is running).

Some items in the preceding list can be relocated elsewhere by
reconfiguring the server.  In addition, the '--datadir' option enables
the location of the data directory itself to be changed.  For a given
MySQL installation, check the server configuration to determine whether
items have been moved.

5.3 The mysql System Database
=============================

The 'mysql' database is the system database.  It contains tables that
store information required by the MySQL server as it runs.

Tables in the 'mysql' database fall into these categories:

   * system-database-grant-tables

   * system-database-object-tables

   * system-database-log-tables

   * system-database-help-tables

   * system-database-time-zone-tables

   * system-database-replication-tables

   * system-database-optimizer-tables

   * system-database-miscellaneous-tables

The remainder of this section enumerates the tables in each category,
with cross references for additional information.  System tables use the
'MyISAM' storage engine unless otherwise indicated.

*Grant System Tables*

These system tables contain grant information about user accounts and
the privileges held by them:

   * 'user': User accounts, global privileges, and other non-privilege
     columns.

   * 'db': Database-level privileges.

   * 'tables_priv': Table-level privileges.

   * 'columns_priv': Column-level privileges.

   * 'procs_priv': Stored procedure and function privileges.

   * 'proxies_priv': Proxy-user privileges.

For more information about the structure, contents, and purpose of the
grant tables, see grant-tables.

*Object Information System Tables*

These system tables contain information about stored programs,
user-defined functions, and server-side plugins:

   * 'event': Information about Event Scheduler events.  See
     event-scheduler.  The server loads events listed in this table
     during its startup sequence, unless started with the
     '--skip-grant-tables' option.

   * 'func': Information about user-defined functions (UDFs).  See
     adding-functions.  The server loads UDFs listed in this table
     during its startup sequence, unless started with the
     '--skip-grant-tables' option.

   * 'plugin': Information about server-side plugins.  See
     server-plugin-loading, and plugin-api.  The server loads
     plugins listed in this table during its startup sequence, unless
     started with the '--skip-grant-tables' option.

     The 'plugin' table uses the 'InnoDB' storage engine as of MySQL
     5.7.6, 'MyISAM' before that.

   * 'proc': Information about stored procedures and functions.  See
     stored-routines.

*Log System Tables*

The server uses these system tables for logging:

   *
     'general_log': The general query log table.

   *
     'slow_log': The slow query log table.

Log tables use the 'CSV' storage engine.

For more information, see server-logs.

*Server-Side Help System Tables*

These system tables contain server-side help information:

   *
     'help_category': Information about help categories.

   *
     'help_keyword': Keywords associated with help topics.

   *
     'help_relation': Mappings between help keywords and topics.

   *
     'help_topic': Help topic contents.

These tables use the 'InnoDB' storage engine as of MySQL 5.7.5, 'MyISAM'
before that.

For more information, see server-side-help-support.

*Time Zone System Tables*

These system tables contain time zone information:

   *
     'time_zone': Time zone IDs and whether they use leap seconds.

   *
     'time_zone_leap_second': When leap seconds occur.

   *
     'time_zone_name': Mappings between time zone IDs and names.

   *
     'time_zone_transition', 'time_zone_transition_type': Time zone
     descriptions.

These tables use the 'InnoDB' storage engine as of MySQL 5.7.5, 'MyISAM'
before that.

For more information, see time-zone-support.

*Replication System Tables*

The server uses these system tables to support replication:

   *
     'gtid_executed': Table for storing GTID values.  See
     replication-gtids-gtid-executed-table.

     The 'gtid_executed' table uses the 'InnoDB' storage engine.

   *
     'ndb_binlog_index': Binary log information for NDB Cluster
     replication.  See mysql-cluster-replication-schema.

   *
     'slave_master_info', 'slave_relay_log_info', 'slave_worker_info':
     Used to store replication information on slave servers.  See
     slave-logs.

     These tables use the 'InnoDB' storage engine.

*Optimizer System Tables*

These system tables are for use by the optimizer:

   *
     'innodb_index_stats', 'innodb_table_stats': Used for 'InnoDB'
     persistent optimizer statistics.  See
     innodb-persistent-stats.

   *
     'server_cost', 'engine_cost': The optimizer cost model uses tables
     that contain cost estimate information about operations that occur
     during query execution.  'server_cost' contains optimizer cost
     estimates for general server operations.  'engine_cost' contains
     estimates for operations specific to particular storage engines.
     See cost-model.

These tables use the 'InnoDB' storage engine.

*Miscellaneous System Tables*

Other system tables do not fall into the preceding categories:

   *
     'audit_log_filter', 'audit_log_user': If MySQL Enterprise Audit is
     installed, these tables provide persistent storage of audit log
     filter definitions and user accounts.  See
     audit-log-tables.

   *
     'firewall_users', 'firewall_whitelist': If MySQL Enterprise
     Firewall is installed, these tables provide persistent storage for
     information used by the firewall.  See firewall.

   *
     'servers': Used by the 'FEDERATED' storage engine.  See
     federated-create-server.

     The 'servers' table uses the 'InnoDB' storage engine as of MySQL
     5.7.6, 'MyISAM' before that.

5.4 MySQL Server Logs
=====================

MySQL Server has several logs that can help you find out what activity
is taking place.

Log Type               Information Written to Log

Error log              Problems encountered starting, running, or
                       stopping 'mysqld'.

General query log      Established client connections and statements
                       received from clients

Binary log             Statements that change data (also used for
                       replication)

Relay log              Data changes received from a replication master
                       server

Slow query log         Queries that took more than 'long_query_time'
                       seconds to execute

DDL log (metadata      Metadata operations performed by DDL statements
log)

By default, no logs are enabled, except the error log on Windows.  (The
DDL log is always created when required, and has no user-configurable
options; see ddl-log.)  The following log-specific sections
provide information about the server options that enable logging.

By default, the server writes files for all enabled logs in the data
directory.  You can force the server to close and reopen the log files
(or in some cases switch to a new log file) by flushing the logs.  Log
flushing occurs when you issue a 'FLUSH LOGS' statement; execute
'mysqladmin' with a 'flush-logs' or 'refresh' argument; or
execute 'mysqldump' with a '--flush-logs' or
'--master-data' option.  See flush, mysqladmin, and
mysqldump.  In addition, the binary log is flushed when its size
reaches the value of the 'max_binlog_size' system variable.

You can control the general query and slow query logs during runtime.
You can enable or disable logging, or change the log file name.  You can
tell the server to write general query and slow query entries to log
tables, log files, or both.  For details, see log-destinations,
query-log, and slow-query-log.

The relay log is used only on slave replication servers, to hold data
changes from the master server that must also be made on the slave.  For
discussion of relay log contents and configuration, see
slave-logs-relaylog.

For information about log maintenance operations such as expiration of
old log files, see log-file-maintenance.

For information about keeping logs secure, see password-logging.

5.4.1 Selecting General Query and Slow Query Log Output Destinations
--------------------------------------------------------------------

MySQL Server provides flexible control over the destination of output to
the general query log and the slow query log, if those logs are enabled.
Possible destinations for log entries are log files or the 'general_log'
and 'slow_log' tables in the 'mysql' database.  Either or both
destinations can be selected.

*Log control at server startup.*  The '--log-output' option specifies
the destination for log output.  This option does not in itself enable
the logs.  Its syntax is '--log-output[=VALUE,...]':

   * If '--log-output' is given with a value, the value should be a
     comma-separated list of one or more of the words 'TABLE' (log to
     tables), 'FILE' (log to files), or 'NONE' (do not log to tables or
     files).  'NONE', if present, takes precedence over any other
     specifiers.

   * If '--log-output' is omitted, the default logging destination is
     'FILE'.

The 'general_log' system variable controls logging to the general query
log for the selected log destinations.  If specified at server startup,
'general_log' takes an optional argument of 1 or 0 to enable or disable
the log.  To specify a file name other than the default for file
logging, set the 'general_log_file' variable.  Similarly, the
'slow_query_log' variable controls logging to the slow query log for the
selected destinations and setting 'slow_query_log_file' specifies a file
name for file logging.  If either log is enabled, the server opens the
corresponding log file and writes startup messages to it.  However,
further logging of queries to the file does not occur unless the 'FILE'
log destination is selected.

Examples:

   * To write general query log entries to the log table and the log
     file, use '--log-output=TABLE,FILE' to select both log destinations
     and '--general_log' to enable the general query log.

   * To write general and slow query log entries only to the log tables,
     use '--log-output=TABLE' to select tables as the log destination
     and '--general_log' and '--slow_query_log' to enable both logs.

   * To write slow query log entries only to the log file, use
     '--log-output=FILE' to select files as the log destination and
     '--slow_query_log' to enable the slow query log.  (In this case,
     because the default log destination is 'FILE', you could omit the
     '--log-output' option.)

*Log control at runtime.*  The system variables associated with log
tables and files enable runtime control over logging:

   * The global 'log_output' system variable indicates the current
     logging destination.  It can be modified at runtime to change the
     destination.

   * The global 'general_log' and 'slow_query_log' variables indicate
     whether the general query log and slow query log are enabled ('ON')
     or disabled ('OFF').  You can set these variables at runtime to
     control whether the logs are enabled.

   * The global 'general_log_file' and 'slow_query_log_file' variables
     indicate the names of the general query log and slow query log
     files.  You can set these variables at server startup or at runtime
     to change the names of the log files.

   * To disable or enable general query logging for the current
     connection, set the session 'sql_log_off' variable to 'ON' or
     'OFF'.

The use of tables for log output offers the following benefits:

   * Log entries have a standard format.  To display the current
     structure of the log tables, use these statements:

          SHOW CREATE TABLE mysql.general_log;
          SHOW CREATE TABLE mysql.slow_log;

   * Log contents are accessible through SQL statements.  This enables
     the use of queries that select only those log entries that satisfy
     specific criteria.  For example, to select log contents associated
     with a particular client (which can be useful for identifying
     problematic queries from that client), it is easier to do this
     using a log table than a log file.

   * Logs are accessible remotely through any client that can connect to
     the server and issue queries (if the client has the appropriate log
     table privileges).  It is not necessary to log in to the server
     host and directly access the file system.

The log table implementation has the following characteristics:

   * In general, the primary purpose of log tables is to provide an
     interface for users to observe the runtime execution of the server,
     not to interfere with its runtime execution.

   * 'CREATE TABLE', 'ALTER TABLE',
     and 'DROP TABLE' are valid
     operations on a log table.  For 'ALTER TABLE'.
     and 'DROP TABLE', the log table cannot be in use
     and must be disabled, as described later.

   * By default, the log tables use the 'CSV' storage engine that writes
     data in comma-separated values format.  For users who have access
     to the '.CSV' files that contain log table data, the files are easy
     to import into other programs such as spreadsheets that can process
     CSV input.

     The log tables can be altered to use the 'MyISAM' storage engine.
     You cannot use 'ALTER TABLE' to alter a log
     table that is in use.  The log must be disabled first.  No engines
     other than 'CSV' or 'MyISAM' are legal for the log tables.

   * To disable logging so that you can alter (or drop) a log table, you
     can use the following strategy.  The example uses the general query
     log; the procedure for the slow query log is similar but uses the
     'slow_log' table and 'slow_query_log' system variable.

          SET @old_log_state = @@global.general_log;
          SET GLOBAL general_log = 'OFF';
          ALTER TABLE mysql.general_log ENGINE = MyISAM;
          SET GLOBAL general_log = @old_log_state;

   * 'TRUNCATE TABLE' is a valid operation on a
     log table.  It can be used to expire log entries.

   * 'RENAME TABLE' is a valid operation on a log
     table.  You can atomically rename a log table (to perform log
     rotation, for example) using the following strategy:

          USE mysql;
          DROP TABLE IF EXISTS general_log2;
          CREATE TABLE general_log2 LIKE general_log;
          RENAME TABLE general_log TO general_log_backup, general_log2 TO general_log;

   * 'CHECK TABLE' is a valid operation on a log
     table.

   * 'LOCK TABLES' cannot be used on a log table.

   * 'INSERT', 'DELETE', and 'UPDATE'
     cannot be used on a log table.  These operations are
     permitted only internally to the server itself.

   * 'FLUSH TABLES WITH READ LOCK' and the state of the 'read_only'
     system variable have no effect on log tables.  The server can
     always write to the log tables.

   * Entries written to the log tables are not written to the binary log
     and thus are not replicated to slave servers.

   * To flush the log tables or log files, use 'FLUSH TABLES' or 'FLUSH
     LOGS', respectively.

   * Partitioning of log tables is not permitted.

   * A 'mysqldump' dump includes statements to
     recreate those tables so that they are not missing after reloading
     the dump file.  Log table contents are not dumped.

5.4.2 The Error Log
-------------------

This section discusses how to configure the MySQL server for logging of
diagnostic messages to the error log.  For information about selecting
the error message character set or language, see charset-errors,
or error-message-language.

The error log contains a record of 'mysqld' startup and
shutdown times.  It also contains diagnostic messages such as errors,
warnings, and notes that occur during server startup and shutdown, and
while the server is running.  For example, if 'mysqld'.
notices that a table needs to be automatically checked or repaired, it
writes a message to the error log.

On some operating systems, the error log contains a stack trace if
'mysqld' exits abnormally.  The trace can be used to determine
where 'mysqld' exited.  See porting.

If used to start 'mysqld', 'mysqld_safe'
may write messages to the error log.  For example, when
'mysqld_safe' notices abnormal 'mysqld'
exits, it restarts 'mysqld' and writes a 'mysqld
restarted' message to the error log.

The following sections discuss aspects of configuring error logging.  In
the discussion, 'console' means 'stderr', the standard error output.
This is your terminal or console window unless the standard error output
has been redirected to a different destination.

The server interprets options that determine where to write error
messages somewhat differently for Windows and Unix systems.  Be sure to
configure error logging using the information appropriate to your
platform.

5.4.2.1 Error Logging on Windows
................................

On Windows, see 'mysqld' uses the '--log-error',
'--pid-file', and '--console' options to determine whether
'mysqld' writes the error log to the console or a file, and, if
to a file, the file name:

   * If '--console' is given, see 'mysqld' writes the error
     log to the console.  ('--console' takes precedence over
     '--log-error' if both are given, and the following items regarding
     '--log-error' do not apply.  Prior to MySQL 5.7, this is reversed:
     '--log-error' takes precedence over '--console'.)

   * If '--log-error' is not given, or is given without naming a file,
     see 'mysqld' writes the error log to a file named
     'HOST_NAME.err' in the data directory, unless the '--pid-file'
     option is specified.  In that case, the file name is the PID file
     base name with a suffix of '.err' in the data directory.

   * If '--log-error' is given to name a file, see 'mysqld'.
     writes the error log to that file (with an '.err' suffix added if
     the name has no suffix), located under the data directory unless an
     absolute path name is given to specify a different location.

If the server writes the error log to the console, it sets the
'log_error' system variable to 'stderr'.  Otherwise, the server writes
the error log to a file and sets 'log_error' to the file name.

In addition, the server by default writes events and error messages to
the Windows Event Log within the Application log:

   * Entries marked as 'Error', 'Warning', and 'Note' are written to the
     Event Log, but not messages such as information statements from
     individual storage engines.

   * Event Log entries have a source of 'MySQL'.

   * Information written to the Event Log is controlled using the
     'log_syslog' system variable, which on Windows is enabled by
     default.  See error-log-syslog.

5.4.2.2 Error Logging on Unix and Unix-Like Systems
...................................................

On Unix and Unix-like systems, see 'mysqld' uses the
'--log-error' option to determine whether 'mysqld' writes
the error log to the console or a file, and, if to a file, the file
name:

   * If '--log-error' is not given, see 'mysqld' writes the
     error log to the console.

   * If '--log-error' is given without naming a file, see 'mysqld'
     writes the error log to a file named 'HOST_NAME.err' in the
     data directory.

   * If '--log-error' is given to name a file, see 'mysqld'.
     writes the error log to that file (with an '.err' suffix added if
     the name has no suffix), located under the data directory unless an
     absolute path name is given to specify a different location.

   * If '--log-error' is given in an option file in a '[mysqld]',
     '[server]', or '[mysqld_safe]' section, see 'mysqld_safe'
     finds and uses the option, and passes it to
     'mysqld'.

*Note*:

It is common for Yum or APT package installations to configure an error
log file location under '/var/log' with an option like
'log-error=/var/log/mysqld.log' in a server configuration file.
Removing the file name from the option causes the 'HOST_NAME.err' file
in the data directory to be used.

If the server writes the error log to the console, it sets the
'log_error' system variable to 'stderr'.  Otherwise, the server writes
the error log to a file and sets 'log_error' to the file name.

5.4.2.3 Error Logging to the System Log
.......................................

It is possible to have 'mysqld' write the error log to
the system log.  This is the Event Log on Windows, and 'syslog' on Unix
and Unix-like systems.  To do so, use these system variables:

   * 'log_syslog': Enable this variable to send the error log to the
     system log.  (On Windows, 'log_syslog' is enabled by default.)

     If 'log_syslog' is enabled, the following system variables can also
     be used for finer control.

   * 'log_syslog_facility': The default facility for 'syslog' messages
     is 'daemon'.  Set this variable to specify a different facility.

   * 'log_syslog_include_pid': Whether to include the server process ID
     in each line of 'syslog' output.

   * 'log_syslog_tag': This variable defines a tag to add to the server
     identifier ('mysqld') in 'syslog' messages.  If defined, the tag is
     appended to the identifier with a leading hyphen.

*Note*:

Logging to the system log may require additional system configuration.
Consult the system log documentation for your platform.

On Unix and Unix-like systems, control of output to 'syslog' is also
available using 'mysqld_safe', which can capture
server error output and pass it to 'syslog'.

*Note*:

Using 'mysqld_safe' for 'syslog' error logging is
deprecated; you should use the server system variables instead.

'mysqld_safe' has three error-logging options,
'--syslog', '--skip-syslog', and '--log-error'.  The default with no
logging options or with '--skip-syslog' is to use the default log file.
To explicitly specify use of an error log file, specify
'--log-error=FILE_NAME' to 'mysqld_safe', which then
arranges for 'mysqld' to write messages to a log file.
To use 'syslog', specify the '--syslog' option.  For 'syslog' output, a
tag can be specified with '--syslog-tag=TAG_VAL'; this is appended to
the 'mysqld' server identifier with a leading hyphen.

5.4.2.4 Error Log Filtering
...........................

The 'log_error_verbosity' system variable controls server verbosity for
writing error, warning, and note messages to the error log.  Permitted
values are 1 (errors only), 2 (errors and warnings), 3 (errors,
warnings, and notes), with a default of 3.  If the value is greater than
2, the server logs aborted connections and access-denied errors for new
connection attempts.  See communication-errors.

5.4.2.5 Error Log Message Format
................................

The ID included in error log messages is that of the thread within
'mysqld' responsible for writing the message.  This indicates
which part of the server produced the message, and is consistent with
general query log and slow query log messages, which include the
connection thread ID.

The 'log_timestamps' system variable controls the time zone of
timestamps in messages written to the error log (as well as to general
query log and slow query log files).  Permitted values are 'UTC' (the
default) and 'SYSTEM' (local system time zone).

5.4.2.6 Error Log File Flushing and Renaming
............................................

If you flush the logs using 'FLUSH ERROR LOGS', 'FLUSH LOGS', or
'mysqladmin flush-logs', the server closes and reopens any
error log file to which it is writing.  To rename an error log file, do
so manually before flushing.  Flushing the logs then opens a new file
with the original file name.  For example, assuming a log file name of
'HOST_NAME.err', to rename the file and create a new one, use the
following commands:

     mv HOST_NAME.err HOST_NAME.err-old
     mysqladmin flush-logs
     mv HOST_NAME.err-old BACKUP-DIRECTORY

On Windows, use 'rename' rather than 'mv'.

If the location of the error file is not writable by the server, the
log-flushing operation fails to create a new log file.  For example, on
Linux, the server might write the error log as '/var/log/mysqld.log',
where '/var/log' is owned by 'root' and not writable by 'mysqld'.
For information about handling this case, see
log-file-maintenance.

If the server is not writing to a named error log file, no error log
file renaming occurs when the logs are flushed.

5.4.3 The General Query Log
---------------------------

The general query log is a general record of what 'mysqld'
is doing.  The server writes information to this log when
clients connect or disconnect, and it logs each SQL statement received
from clients.  The general query log can be very useful when you suspect
an error in a client and want to know exactly what the client sent to
'mysqld'.

Each line that shows when a client connects also includes 'using
CONNECTION_TYPE' to indicate the protocol used to establish the
connection.  CONNECTION_TYPE is one of 'TCP/IP' (TCP/IP connection
established without SSL), 'SSL/TLS' (TCP/IP connection established with
SSL), 'Socket' (Unix socket file connection), 'Named Pipe' (Windows
named pipe connection), or 'Shared Memory' (Windows shared memory
connection).

'mysqld' writes statements to the query log in the order
that it receives them, which might differ from the order in which they
are executed.  This logging order is in contrast with that of the binary
log, for which statements are written after they are executed but before
any locks are released.  In addition, the query log may contain
statements that only select data while such statements are never written
to the binary log.

When using statement-based binary logging on a replication master
server, statements received by its slaves are written to the query log
of each slave.  Statements are written to the query log of the master
server if a client reads events with the 'mysqlbinlog'
utility and passes them to the server.

However, when using row-based binary logging, updates are sent as row
changes rather than SQL statements, and thus these statements are never
written to the query log when 'binlog_format' is 'ROW'.  A given update
also might not be written to the query log when this variable is set to
'MIXED', depending on the statement used.  See
replication-sbr-rbr, for more information.

By default, the general query log is disabled.  To specify the initial
general query log state explicitly, use '--general_log[={0|1}]'.  With
no argument or an argument of 1, '--general_log' enables the log.  With
an argument of 0, this option disables the log.  To specify a log file
name, use '--general_log_file=FILE_NAME'.  To specify the log
destination, use '--log-output' (as described in
log-destinations).

If you specify no name for the general query log file, the default name
is 'HOST_NAME.log'.  The server creates the file in the data directory
unless an absolute path name is given to specify a different directory.

To disable or enable the general query log or change the log file name
at runtime, use the global 'general_log' and 'general_log_file' system
variables.  Set 'general_log' to 0 (or 'OFF') to disable the log or to 1
(or 'ON') to enable it.  Set 'general_log_file' to specify the name of
the log file.  If a log file already is open, it is closed and the new
file is opened.

When the general query log is enabled, the server writes output to any
destinations specified by the '--log-output' option or 'log_output'
system variable.  If you enable the log, the server opens the log file
and writes startup messages to it.  However, further logging of queries
to the file does not occur unless the 'FILE' log destination is
selected.  If the destination is 'NONE', the server writes no queries
even if the general log is enabled.  Setting the log file name has no
effect on logging if the log destination value does not contain 'FILE'.

Server restarts and log flushing do not cause a new general query log
file to be generated (although flushing closes and reopens it).  To
rename the file and create a new one, use the following commands:

     shell> mv HOST_NAME.log HOST_NAME-old.log
     shell> mysqladmin flush-logs
     shell> mv HOST_NAME-old.log BACKUP-DIRECTORY

On Windows, use 'rename' rather than 'mv'.

You can also rename the general query log file at runtime by disabling
the log:

     SET GLOBAL general_log = 'OFF';

With the log disabled, rename the log file externally; for example, from
the command line.  Then enable the log again:

     SET GLOBAL general_log = 'ON';

This method works on any platform and does not require a server restart.

The session 'sql_log_off' variable can be set to 'ON' or 'OFF' to
disable or enable general query logging for the current connection.

Passwords in statements written to the general query log are rewritten
by the server not to occur literally in plain text.  Password rewriting
can be suppressed for the general query log by starting the server with
the '--log-raw' option.  This option may be useful for diagnostic
purposes, to see the exact text of statements as received by the server,
but for security reasons is not recommended for production use.  See
also password-logging.

An implication of password rewriting is that statements that cannot be
parsed (due, for example, to syntax errors) are not written to the
general query log because they cannot be known to be password free.  Use
cases that require logging of all statements including those with errors
should use the '--log-raw' option, bearing in mind that this also
bypasses password rewriting.

Password rewriting occurs only when plain text passwords are expected.
For statements with syntax that expect a password hash value, no
rewriting occurs.  If a plain text password is supplied erroneously for
such syntax, the password is logged as given, without rewriting.  For
example, the following statement is logged as shown because a password
hash value is expected:

     CREATE USER 'user1'@'localhost' IDENTIFIED BY PASSWORD 'not-so-secret';

The 'log_timestamps' system variable controls the time zone of
timestamps in messages written to the general query log file (as well as
to the slow query log file and the error log).  It does not affect the
time zone of general query log and slow query log messages written to
log tables, but rows retrieved from those tables can be converted from
the local system time zone to any desired time zone with 'CONVERT_TZ()'
or by setting the session 'time_zone' system variable.

5.4.4 The Binary Log
--------------------

The binary log contains 'events' that describe database changes such as
table creation operations or changes to table data.  It also contains
events for statements that potentially could have made changes (for
example, a 'DELETE' which matched no rows), unless
row-based logging is used.  The binary log also contains information
about how long each statement took that updated data.  The binary log
has two important purposes:

   * For replication, the binary log on a master replication server
     provides a record of the data changes to be sent to slave servers.
     The master server sends the events contained in its binary log to
     its slaves, which execute those events to make the same data
     changes that were made on the master.  See
     replication-implementation.

   * Certain data recovery operations require use of the binary log.
     After a backup has been restored, the events in the binary log that
     were recorded after the backup was made are re-executed.  These
     events bring databases up to date from the point of the backup.
     See point-in-time-recovery.

The binary log is not used for statements such as 'SELECT'
or 'SHOW' that do not modify data.  To log all
statements (for example, to identify a problem query), use the general
query log.  See query-log.

Running a server with binary logging enabled makes performance slightly
slower.  However, the benefits of the binary log in enabling you to set
up replication and for restore operations generally outweigh this minor
performance decrement.

The binary log is generally resilient to unexpected halts because only
complete transactions are logged or read back.  See
replication-solutions-unexpected-slave-halt for more information.

Passwords in statements written to the binary log are rewritten by the
server not to occur literally in plain text.  See also
password-logging.

The following discussion describes some of the server options and
variables that affect the operation of binary logging.  For a complete
list, see replication-options-binary-log.

To enable the binary log, start the server with the
'--log-bin[=BASE_NAME]' option.  If no BASE_NAME value is given, the
default name is the value of the 'pid-file' option (which by default is
the name of host machine) followed by '-bin'.  If the base name is
given, the server writes the file in the data directory unless the base
name is given with a leading absolute path name to specify a different
directory.  It is recommended that you specify a base name explicitly
rather than using the default of the host name; see bugs, for
the reason.

If you supply an extension in the log name (for example,
'--log-bin=BASE_NAME.EXTENSION'), the extension is silently removed and
ignored.

'mysqld' appends a numeric extension to the binary log
base name to generate binary log file names.  The number increases each
time the server creates a new log file, thus creating an ordered series
of files.  The server creates a new file in the series each time it
starts or flushes the logs.  The server also creates a new binary log
file automatically after the current log's size reaches
'max_binlog_size'.  A binary log file may become larger than
'max_binlog_size' if you are using large transactions because a
transaction is written to the file in one piece, never split between
files.

To keep track of which binary log files have been used, see 'mysqld'
also creates a binary log index file that contains the names of
all used binary log files.  By default, this has the same base name as
the binary log file, with the extension ''.index''.  You can change the
name of the binary log index file with the '--log-bin-index[=FILE_NAME]'
option.  You should not manually edit this file while 'mysqld'
is running; doing so would confuse 'mysqld'.

The term 'binary log file' generally denotes an individual numbered file
containing database events.  The term 'binary log' collectively denotes
the set of numbered binary log files plus the index file.

A client that has the 'SUPER' privilege can disable binary logging of
its own statements by using a 'SET sql_log_bin=0' statement.  See
server-system-variables.

By default, the server logs the length of the event as well as the event
itself and uses this to verify that the event was written correctly.
You can also cause the server to write checksums for the events by
setting the 'binlog_checksum' system variable.  When reading back from
the binary log, the master uses the event length by default, but can be
made to use checksums if available by enabling the
'master_verify_checksum' system variable.  The slave I/O thread also
verifies events received from the master.  You can cause the slave SQL
thread to use checksums if available when reading from the relay log by
enabling the 'slave_sql_verify_checksum' system variable.

The format of the events recorded in the binary log is dependent on the
binary logging format.  Three format types are supported, row-based
logging, statement-based logging and mixed-base logging.  The binary
logging format used depends on the MySQL version.  For general
descriptions of the logging formats, see binary-log-formats.
For detailed information about the format of the binary log, see MySQL
Internals: The Binary Log
(http://dev.mysql.com/doc/internals/en/binary-log.html).

The server evaluates the '--binlog-do-db' and '--binlog-ignore-db'
options in the same way as it does the '--replicate-do-db' and
'--replicate-ignore-db' options.  For information about how this is
done, see replication-rules-db-options.

A replication slave server by default does not write to its own binary
log any data modifications that are received from the replication
master.  To log these modifications, start the slave with the
'--log-slave-updates' option in addition to the '--log-bin' option (see
replication-options-slave).  This is done when a slave is also
to act as a master to other slaves in chained replication.

You can delete all binary log files with the 'RESET MASTER'
statement, or a subset of them with 'PURGE BINARY LOGS'.
See reset, and
purge-binary-logs.

If you are using replication, you should not delete old binary log files
on the master until you are sure that no slave still needs to use them.
For example, if your slaves never run more than three days behind, once
a day you can execute 'mysqladmin flush-logs' on the
master and then remove any logs that are more than three days old.  You
can remove the files manually, but it is preferable to use 'PURGE BINARY LOGS',
which also safely updates the binary
log index file for you (and which can take a date argument).  See
purge-binary-logs.

You can display the contents of binary log files with the
'mysqlbinlog' utility.  This can be useful when you want
to reprocess statements in the log for a recovery operation.  For
example, you can update a MySQL server from the binary log as follows:

     shell> mysqlbinlog LOG_FILE | mysql -h SERVER_NAME

'mysqlbinlog' also can be used to display
replication slave relay log file contents because they are written using
the same format as binary log files.  For more information on the
'mysqlbinlog' utility and how to use it, see
mysqlbinlog.  For more information about the binary log and recovery
operations, see point-in-time-recovery.

Binary logging is done immediately after a statement or transaction
completes but before any locks are released or any commit is done.  This
ensures that the log is logged in commit order.

Updates to nontransactional tables are stored in the binary log
immediately after execution.

Within an uncommitted transaction, all updates (see 'UPDATE',
'DELETE', or 'INSERT') that change
transactional tables such as 'InnoDB' tables are cached until a
'COMMIT' statement is received by the server.  At that point,
see 'mysqld' writes the entire transaction to the binary log
before the 'COMMIT' is executed.

Modifications to nontransactional tables cannot be rolled back.  If a
transaction that is rolled back includes modifications to
nontransactional tables, the entire transaction is logged with a
'ROLLBACK' statement at the end to ensure that the
modifications to those tables are replicated.

When a thread that handles the transaction starts, it allocates a buffer
of 'binlog_cache_size' to buffer statements.  If a statement is bigger
than this, the thread opens a temporary file to store the transaction.
The temporary file is deleted when the thread ends.

The 'Binlog_cache_use' status variable shows the number of transactions
that used this buffer (and possibly a temporary file) for storing
statements.  The 'Binlog_cache_disk_use' status variable shows how many
of those transactions actually had to use a temporary file.  These two
variables can be used for tuning 'binlog_cache_size' to a large enough
value that avoids the use of temporary files.

The 'max_binlog_cache_size' system variable (default 4GB, which is also
the maximum) can be used to restrict the total size used to cache a
multiple-statement transaction.  If a transaction is larger than this
many bytes, it fails and rolls back.  The minimum value is 4096.

If you are using the binary log and row based logging, concurrent
inserts are converted to normal inserts for 'CREATE ... SELECT' or
'INSERT ... SELECT' statements.  This is done to ensure
that you can re-create an exact copy of your tables by applying the log
during a backup operation.  If you are using statement-based logging,
the original statement is written to the log.

The binary log format has some known limitations that can affect
recovery from backups.  See replication-features.

Binary logging for stored programs is done as described in
stored-programs-logging.

Note that the binary log format differs in MySQL 5.7 from previous
versions of MySQL, due to enhancements in replication.  See
replication-compatibility.

Writes to the binary log file and binary log index file are handled in
the same way as writes to 'MyISAM' tables.  See full-disk.

By default, the binary log is synchronized to disk at each write
('sync_binlog=1').  If 'sync_binlog' was not enabled, and the operating
system or machine (not only the MySQL server) crashed, there is a chance
that the last statements of the binary log could be lost.  To prevent
this, enable the 'sync_binlog' system variable to synchronize the binary
log to disk after every N commit groups.  See
server-system-variables.  The safest value for 'sync_binlog' is 1 (the
default), but this is also the slowest.

For example, if you are using 'InnoDB' tables and the MySQL server
processes a 'COMMIT' statement, it writes many prepared
transactions to the binary log in sequence, synchronizes the binary log,
and then commits this transaction into 'InnoDB'.  If the server crashes
between those two operations, the transaction is rolled back by 'InnoDB'
at restart but still exists in the binary log.  Such an issue is
resolved assuming '--innodb_support_xa' is set to 1, the default.
Although this option is related to the support of XA transactions in
'InnoDB', it also ensures that the binary log and InnoDB data files are
synchronized.  For this option to provide a greater degree of safety,
the MySQL server should also be configured to synchronize the binary log
and the 'InnoDB' logs to disk before committing the transaction.  The
'InnoDB' logs are synchronized by default, and 'sync_binlog=1' can be
used to synchronize the binary log.  The effect of this option is that
at restart after a crash, after doing a rollback of transactions, the
MySQL server scans the latest binary log file to collect transaction XID
values and calculate the last valid position in the binary log file.
The MySQL server then tells 'InnoDB' to complete any prepared
transactions that were successfully written to the to the binary log,
and truncates the binary log to the last valid position.  This ensures
that the binary log reflects the exact data of 'InnoDB' tables, and
therefore the slave remains in synchrony with the master because it does
not receive a statement which has been rolled back.

*Note*:

'innodb_support_xa' is deprecated and will be removed in a future
release.  'InnoDB' support for two-phase commit in XA transactions is
always enabled as of MySQL 5.7.10.

If the MySQL server discovers at crash recovery that the binary log is
shorter than it should have been, it lacks at least one successfully
committed 'InnoDB' transaction.  This should not happen if
'sync_binlog=1' and the disk/file system do an actual sync when they are
requested to (some do not), so the server prints an error message 'The
binary log FILE_NAME is shorter than its expected size'.  In this case,
this binary log is not correct and replication should be restarted from
a fresh snapshot of the master's data.

The session values of the following system variables are written to the
binary log and honored by the replication slave when parsing the binary
log:

   * 'sql_mode' (except that the 'NO_DIR_IN_CREATE' mode is not
     replicated; see replication-features-variables)

   * 'foreign_key_checks'

   * 'unique_checks'

   * 'character_set_client'

   * 'collation_connection'

   * 'collation_database'

   * 'collation_server'

   * 'sql_auto_is_null'

5.4.4.1 Binary Logging Formats
..............................

The server uses several logging formats to record information in the
binary log.  The exact format employed depends on the version of MySQL
being used.  There are three logging formats:

   * Replication capabilities in MySQL originally were based on
     propagation of SQL statements from master to slave.  This is called
     _statement-based logging_.  You can cause this format to be used by
     starting the server with '--binlog-format=STATEMENT'.

   * In _row-based logging_, the master writes events to the binary log
     that indicate how individual table rows are affected.  It is
     important therefore that tables always use a primary key to ensure
     rows can be efficiently identified.  You can cause the server to
     use row-based logging by starting it with '--binlog-format=ROW'.

   * A third option is also available: _mixed logging_.  With mixed
     logging, statement-based logging is used by default, but the
     logging mode switches automatically to row-based in certain cases
     as described below.  You can cause MySQL to use mixed logging
     explicitly by starting 'mysqld' with the option
     '--binlog-format=MIXED'.

The logging format can also be set or limited by the storage engine
being used.  This helps to eliminate issues when replicating certain
statements between a master and slave which are using different storage
engines.

With statement-based replication, there may be issues with replicating
nondeterministic statements.  In deciding whether or not a given
statement is safe for statement-based replication, MySQL determines
whether it can guarantee that the statement can be replicated using
statement-based logging.  If MySQL cannot make this guarantee, it marks
the statement as potentially unreliable and issues the warning,
'Statement may not be safe to log in statement format'.

You can avoid these issues by using MySQL's row-based replication
instead.

5.4.4.2 Setting The Binary Log Format
.....................................

You can select the binary logging format explicitly by starting the
MySQL server with '--binlog-format=TYPE'.  The supported values for TYPE
are:

   * 'STATEMENT' causes logging to be statement based.

   * 'ROW' causes logging to be row based.

   * 'MIXED' causes logging to use mixed format.

The logging format also can be switched at runtime.  Set the global
value of the 'binlog_format' system variable to specify the format for
clients that connect subsequent to the change:

     mysql> SET GLOBAL binlog_format = 'STATEMENT';
     mysql> SET GLOBAL binlog_format = 'ROW';
     mysql> SET GLOBAL binlog_format = 'MIXED';

An individual client can control the logging format for its own
statements by setting the session value of 'binlog_format':

     mysql> SET SESSION binlog_format = 'STATEMENT';
     mysql> SET SESSION binlog_format = 'ROW';
     mysql> SET SESSION binlog_format = 'MIXED';

*Note*:

Each MySQL Server can set its own and only its own binary logging format
(true whether 'binlog_format' is set with global or session scope).
This means that changing the logging format on a replication master does
not cause a slave to change its logging format to match.  (When using
'STATEMENT' mode, the 'binlog_format' system variable is not replicated;
when using 'MIXED' or 'ROW' logging mode, it is replicated but is
ignored by the slave.)  Changing the binary logging format on the master
while replication is ongoing, or without also changing it on the slave
can cause replication to fail with errors such as 'Error executing row
event: 'Cannot execute statement: impossible to write to binary log
since statement is in row format and BINLOG_FORMAT = STATEMENT.''

To change the global or session 'binlog_format' value, you must have the
'SUPER' privilege.

There are several reasons why a client might want to set binary logging
on a per-session basis:

   * A session that makes many small changes to the database might want
     to use row-based logging.

   * A session that performs updates that match many rows in the 'WHERE'
     clause might want to use statement-based logging because it will be
     more efficient to log a few statements than many rows.

   * Some statements require a lot of execution time on the master, but
     result in just a few rows being modified.  It might therefore be
     beneficial to replicate them using row-based logging.

There are exceptions when you cannot switch the replication format at
runtime:

   * From within a stored function or a trigger

   * If the 'NDB' storage engine is enabled

   * If the session is currently in row-based replication mode and has
     open temporary tables

Trying to switch the format in any of these cases results in an error.

If you are using 'InnoDB' tables and the
transaction isolation level is 'READ COMMITTED' or 'READ UNCOMMITTED',
only row-based logging can be used.  It is _possible_ to change the
logging format to 'STATEMENT', but doing so at runtime leads very
rapidly to errors because 'InnoDB' can no longer perform inserts.

Switching the replication format at runtime is not recommended when any
temporary tables exist, because temporary tables are logged only when
using statement-based replication, whereas with row-based replication
they are not logged.  With mixed replication, temporary tables are
usually logged; exceptions happen with user-defined functions (UDFs) and
with the 'UUID()' function.

With the binary log format set to 'ROW', many changes are written to the
binary log using the row-based format.  Some changes, however, still use
the statement-based format.  Examples include all DDL (data definition
language) statements such as 'CREATE TABLE',
'ALTER TABLE', or 'DROP TABLE'.

The '--binlog-row-event-max-size' option is available for servers that
are capable of row-based replication.  Rows are stored into the binary
log in chunks having a size in bytes not exceeding the value of this
option.  The value must be a multiple of 256.  The default value is
8192.

*Warning*:

When using _statement-based logging_ for replication, it is possible for
the data on the master and slave to become different if a statement is
designed in such a way that the data modification is _nondeterministic_;
that is, it is left to the will of the query optimizer.  In general,
this is not a good practice even outside of replication.  For a detailed
explanation of this issue, see bugs.

For information about logs kept by replication slaves, see
slave-logs.

5.4.4.3 Mixed Binary Logging Format
...................................

When running in 'MIXED' logging format, the server automatically
switches from statement-based to row-based logging under the following
conditions:

   * When a function contains 'UUID()'.

   * When one or more tables with 'AUTO_INCREMENT' columns are updated
     and a trigger or stored function is invoked.  Like all other unsafe
     statements, this generates a warning if 'binlog_format =
     STATEMENT'.

     For more information, see
     replication-features-auto-increment.

   * When the body of a view requires row-based replication, the
     statement creating the view also uses it.  For example, this occurs
     when the statement creating a view uses the 'UUID()' function.

   * When a call to a UDF is involved.

   * If a statement is logged by row and the session that executed the
     statement has any temporary tables, logging by row is used for all
     subsequent statements (except for those accessing temporary tables)
     until all temporary tables in use by that session are dropped.

     This is true whether or not any temporary tables are actually
     logged.

     Temporary tables cannot be logged using row-based format; thus,
     once row-based logging is used, all subsequent statements using
     that table are unsafe.  The server approximates this condition by
     treating all statements executed during the session as unsafe until
     the session no longer holds any temporary tables.

   * When 'FOUND_ROWS()' or 'ROW_COUNT()' is used.  (Bug #12092, Bug
     #30244)

   * When 'USER()', 'CURRENT_USER()', or 'CURRENT_USER' is used.  (Bug
     #28086)

   * When a statement refers to one or more system variables.  (Bug
     #31168)

     Exception

     The following system variables, when used with session scope
     (only), do not cause the logging format to switch:

        * 'auto_increment_increment'

        * 'auto_increment_offset'

        * 'character_set_client'

        * 'character_set_connection'

        * 'character_set_database'

        * 'character_set_server'

        * 'collation_connection'

        * 'collation_database'

        * 'collation_server'

        * 'foreign_key_checks'

        * 'identity'

        * 'last_insert_id'

        * 'lc_time_names'

        * 'pseudo_thread_id'

        * 'sql_auto_is_null'

        * 'time_zone'

        * 'timestamp'

        * 'unique_checks'

     For information about determining system variable scope, see
     using-system-variables.

     For information about how replication treats 'sql_mode', see
     replication-features-variables.

   * When one of the tables involved is a log table in the 'mysql'
     database.

   * When the 'LOAD_FILE()' function is used.  (Bug #39701)

*Note*:

A warning is generated if you try to execute a statement using
statement-based logging that should be written using row-based logging.
The warning is shown both in the client (in the output of 'SHOW WARNINGS')
and through the 'mysqld' error
log.  A warning is added to the 'SHOW WARNINGS'.
table each time such a statement is executed.  However, only the first
statement that generated the warning for each client session is written
to the error log to prevent flooding the log.

In addition to the decisions above, individual engines can also
determine the logging format used when information in a table is
updated.  The logging capabilities of an individual engine can be
defined as follows:

   * If an engine supports row-based logging, the engine is said to be
     _row-logging capable_.

   * If an engine supports statement-based logging, the engine is said
     to be _statement-logging capable_.

A given storage engine can support either or both logging formats.  The
following table lists the formats supported by each engine.

Storage Engine                       Row Logging        Statement
                                     Supported          Logging
                                                        Supported

'ARCHIVE'                            Yes                Yes

'BLACKHOLE'                          Yes                Yes

'CSV'                                Yes                Yes

'EXAMPLE'                            Yes                No

'FEDERATED'                          Yes                Yes

'HEAP'                               Yes                Yes

'InnoDB'                             Yes                Yes when the
                                                        transaction
                                                        isolation level
                                                        is 'REPEATABLE
                                                        READ' or
                                                        'SERIALIZABLE';
                                                        No otherwise.

'MyISAM'                             Yes                Yes

'MERGE'                              Yes                Yes

See 'NDB'.          Yes                No

Whether a statement is to be logged and the logging mode to be used is
determined according to the type of statement (safe, unsafe, or binary
injected), the binary logging format ('STATEMENT', 'ROW', or 'MIXED'),
and the logging capabilities of the storage engine (statement capable,
row capable, both, or neither).  (Binary injection refers to logging a
change that must be logged using 'ROW' format.)

Statements may be logged with or without a warning; failed statements
are not logged, but generate errors in the log.  This is shown in the
following decision table.  *Type*, *binlog_format*, *SLC*, and *RLC*
columns outline the conditions, and *Error / Warning* and *Logged as*
columns represent the corresponding actions.  *SLC* stands for
'statement-logging capable', and *RLC* stands for 'row-logging capable'.

Type    'binlog_format'    SLC     RLC     Error /        Logged as
                                           Warning

*       '*'                No      No      'Error:        '-'
                                           Cannot
                                           execute
                                           statement':
                                           Binary
                                           logging is
                                           impossible
                                           since at
                                           least one
                                           engine is
                                           involved
                                           that is both
                                           row-incapable
                                           and
                                           statement-incapable.

Safe    'STATEMENT'        Yes     No      -              'STATEMENT'

Safe    'MIXED'            Yes     No      -              'STATEMENT'

Safe    'ROW'              Yes     No      'Error:        '-'
                                           Cannot
                                           execute
                                           statement':
                                           Binary
                                           logging is
                                           impossible
                                           since
                                           'BINLOG_FORMAT
                                           = ROW' and
                                           at least one
                                           table uses a
                                           storage
                                           engine that
                                           is not
                                           capable of
                                           row-based
                                           logging.

Unsafe  'STATEMENT'        Yes     No      'Warning:      'STATEMENT'
                                           Unsafe
                                           statement
                                           binlogged in
                                           statement
                                           format',
                                           since
                                           'BINLOG_FORMAT
                                           = STATEMENT'

Unsafe  'MIXED'            Yes     No      'Error:        '-'
                                           Cannot
                                           execute
                                           statement':
                                           Binary
                                           logging of
                                           an unsafe
                                           statement is
                                           impossible
                                           when the
                                           storage
                                           engine is
                                           limited to
                                           statement-based
                                           logging,
                                           even if
                                           'BINLOG_FORMAT
                                           = MIXED'.

Unsafe  'ROW'              Yes     No      'Error:        -
                                           Cannot
                                           execute
                                           statement':
                                           Binary
                                           logging is
                                           impossible
                                           since
                                           'BINLOG_FORMAT
                                           = ROW' and
                                           at least one
                                           table uses a
                                           storage
                                           engine that
                                           is not
                                           capable of
                                           row-based
                                           logging.

Row     'STATEMENT'        Yes     No      'Error:        -
Injection                                  Cannot
                                           execute row
                                           injection':
                                           Binary
                                           logging is
                                           not possible
                                           since at
                                           least one
                                           table uses a
                                           storage
                                           engine that
                                           is not
                                           capable of
                                           row-based
                                           logging.

Row     'MIXED'            Yes     No      'Error:        -
Injection                                  Cannot
                                           execute row
                                           injection':
                                           Binary
                                           logging is
                                           not possible
                                           since at
                                           least one
                                           table uses a
                                           storage
                                           engine that
                                           is not
                                           capable of
                                           row-based
                                           logging.

Row     'ROW'              Yes     No      'Error:        -
Injection                                  Cannot
                                           execute row
                                           injection':
                                           Binary
                                           logging is
                                           not possible
                                           since at
                                           least one
                                           table uses a
                                           storage
                                           engine that
                                           is not
                                           capable of
                                           row-based
                                           logging.

Safe    'STATEMENT'        No      Yes     'Error:        '-'
                                           Cannot
                                           execute
                                           statement':
                                           Binary
                                           logging is
                                           impossible
                                           since
                                           'BINLOG_FORMAT
                                           = STATEMENT'
                                           and at least
                                           one table
                                           uses a
                                           storage
                                           engine that
                                           is not
                                           capable of
                                           statement-based
                                           logging.

Safe    'MIXED'            No      Yes     -              'ROW'

Safe    'ROW'              No      Yes     -              'ROW'

Unsafe  'STATEMENT'        No      Yes     'Error:        -
                                           Cannot
                                           execute
                                           statement':
                                           Binary
                                           logging is
                                           impossible
                                           since
                                           'BINLOG_FORMAT
                                           = STATEMENT'
                                           and at least
                                           one table
                                           uses a
                                           storage
                                           engine that
                                           is not
                                           capable of
                                           statement-based
                                           logging.

Unsafe  'MIXED'            No      Yes     -              'ROW'

Unsafe  'ROW'              No      Yes     -              'ROW'

Row     'STATEMENT'        No      Yes     'Error:        '-'
Injection                                  Cannot
                                           execute row
                                           injection':
                                           Binary
                                           logging is
                                           not possible
                                           since
                                           'BINLOG_FORMAT
                                           =
                                           STATEMENT'.

Row     'MIXED'            No      Yes     -              'ROW'
Injection

Row     'ROW'              No      Yes     -              'ROW'
Injection

Safe    'STATEMENT'        Yes     Yes     -              'STATEMENT'

Safe    'MIXED'            Yes     Yes     -              'STATEMENT'

Safe    'ROW'              Yes     Yes     -              'ROW'

Unsafe  'STATEMENT'        Yes     Yes     'Warning:      'STATEMENT'
                                           Unsafe
                                           statement
                                           binlogged in
                                           statement
                                           format'
                                           since
                                           'BINLOG_FORMAT
                                           =
                                           STATEMENT'.

Unsafe  'MIXED'            Yes     Yes     -              'ROW'

Unsafe  'ROW'              Yes     Yes     -              'ROW'

Row     'STATEMENT'        Yes     Yes     'Error:        -
Injection                                  Cannot
                                           execute row
                                           injection':
                                           Binary
                                           logging is
                                           not possible
                                           because
                                           'BINLOG_FORMAT
                                           =
                                           STATEMENT'.

Row     'MIXED'            Yes     Yes     -              'ROW'
Injection

Row     'ROW'              Yes     Yes     -              'ROW'
Injection

When a warning is produced by the determination, a standard MySQL
warning is produced (and is available using 'SHOW WARNINGS').
The information is also written to the 'mysqld'
error log.  Only one error for each error instance per client
connection is logged to prevent flooding the log.  The log message
includes the SQL statement that was attempted.

If a slave server has 'log_error_verbosity' set to display warnings, the
slave prints messages to the error log to provide information about its
status, such as the binary log and relay log coordinates where it starts
its job, when it is switching to another relay log, when it reconnects
after a disconnect, statements that are unsafe for statement-based
logging, and so forth.

5.4.4.4 Logging Format for Changes to mysql Database Tables
...........................................................

The contents of the grant tables in the 'mysql' database can be modified
directly (for example, with 'INSERT' or 'DELETE')
or indirectly (for example, with 'GRANT' or
'CREATE USER').  Statements that affect 'mysql' database
tables are written to the binary log using the following rules:

   * Data manipulation statements that change data in 'mysql' database
     tables directly are logged according to the setting of the
     'binlog_format' system variable.  This pertains to statements such
     as 'INSERT', 'UPDATE', 'DELETE',
     see 'REPLACE', 'DO', 'LOAD DATA INFILE',
     see 'SELECT', and 'TRUNCATE TABLE'.

   * Statements that change the 'mysql' database indirectly are logged
     as statements regardless of the value of 'binlog_format'.  This
     pertains to statements such as 'GRANT',
     'REVOKE', 'SET PASSWORD', 'RENAME USER',
     'CREATE' (all forms except 'CREATE TABLE ... SELECT'),
     'ALTER' (all forms), and 'DROP' (all
     forms).

'CREATE TABLE ... SELECT' is a combination of data
definition and data manipulation.  The 'CREATE TABLE'
part is logged using statement format and the
'SELECT' part is logged according to the value of
'binlog_format'.

5.4.5 The Slow Query Log
------------------------

The slow query log consists of SQL statements that took more than
'long_query_time' seconds to execute and required at least
'min_examined_row_limit' rows to be examined.  The minimum and default
values of 'long_query_time' are 0 and 10, respectively.  The value can
be specified to a resolution of microseconds.  For logging to a file,
times are written including the microseconds part.  For logging to
tables, only integer times are written; the microseconds part is
ignored.

By default, administrative statements are not logged, nor are queries
that do not use indexes for lookups.  This behavior can be changed using
'log_slow_admin_statements' and 'log_queries_not_using_indexes', as
described later.

The time to acquire the initial locks is not counted as execution time.
'mysqld' writes a statement to the slow query log after
it has been executed and after all locks have been released, so log
order might differ from execution order.

By default, the slow query log is disabled.  To specify the initial slow
query log state explicitly, use '--slow_query_log[={0|1}]'.  With no
argument or an argument of 1, '--slow_query_log' enables the log.  With
an argument of 0, this option disables the log.  To specify a log file
name, use '--slow_query_log_file=FILE_NAME'.  To specify the log
destination, use '--log-output' (as described in
log-destinations).

If you specify no name for the slow query log file, the default name is
'HOST_NAME-slow.log'.  The server creates the file in the data directory
unless an absolute path name is given to specify a different directory.

To disable or enable the slow query log or change the log file name at
runtime, use the global 'slow_query_log' and 'slow_query_log_file'
system variables.  Set 'slow_query_log' to 0 (or 'OFF') to disable the
log or to 1 (or 'ON') to enable it.  Set 'slow_query_log_file' to
specify the name of the log file.  If a log file already is open, it is
closed and the new file is opened.

When the slow query log is enabled, the server writes output to any
destinations specified by the '--log-output' option or 'log_output'
system variable.  If you enable the log, the server opens the log file
and writes startup messages to it.  However, further logging of queries
to the file does not occur unless the 'FILE' log destination is
selected.  If the destination is 'NONE', the server writes no queries
even if the slow query log is enabled.  Setting the log file name has no
effect on logging if the log destination value does not contain 'FILE'.

The server writes less information to the slow query log if you use the
'--log-short-format' option.

To include slow administrative statements in the statements written to
the slow query log, use the 'log_slow_admin_statements' system variable.
Administrative statements include 'ALTER TABLE',
'ANALYZE TABLE', 'CHECK TABLE',
'CREATE INDEX', 'DROP INDEX',
'OPTIMIZE TABLE', and 'REPAIR TABLE'.

To include queries that do not use indexes for row lookups in the
statements written to the slow query log, enable the
'log_queries_not_using_indexes' system variable.  When such queries are
logged, the slow query log may grow quickly.  It is possible to put a
rate limit on these queries by setting the
'log_throttle_queries_not_using_indexes' system variable.  By default,
this variable is 0, which means there is no limit.  Positive values
impose a per-minute limit on logging of queries that do not use indexes.
The first such query opens a 60-second window within which the server
logs queries up to the given limit, then suppresses additional queries.
If there are suppressed queries when the window ends, the server logs a
summary that indicates how many there were and the aggregate time spent
in them.  The next 60-second window begins when the server logs the next
query that does not use indexes.

The server uses the controlling parameters in the following order to
determine whether to write a query to the slow query log:

  1. The query must either not be an administrative statement, or
     'log_slow_admin_statements' must be enabled.

  2. The query must have taken at least 'long_query_time' seconds, or
     'log_queries_not_using_indexes' must be enabled and the query used
     no indexes for row lookups.

  3. The query must have examined at least 'min_examined_row_limit'
     rows.

  4. The query must not be suppressed according to the
     'log_throttle_queries_not_using_indexes' setting.

The 'log_timestamps' system variable controls the time zone of
timestamps in messages written to the slow query log file (as well as to
the general query log file and the error log).  It does not affect the
time zone of general query log and slow query log messages written to
log tables, but rows retrieved from those tables can be converted from
the local system time zone to any desired time zone with 'CONVERT_TZ()'
or by setting the session 'time_zone' system variable.

All log lines contain a timestamp.

The server does not write queries handled by the query cache to the slow
query log, nor queries that would not benefit from the presence of an
index because the table has zero rows or one row.

By default, a replication slave does not write replicated queries to the
slow query log.  To change this, use the 'log_slow_slave_statements'
system variable.

Passwords in statements written to the slow query log are rewritten by
the server not to occur literally in plain text.  See also
password-logging.

The slow query log can be used to find queries that take a long time to
execute and are therefore candidates for optimization.  However,
examining a long slow query log can become a difficult task.  To make
this easier, you can process a slow query log file using the
'mysqldumpslow' command to summarize the queries that
appear in the log.  See mysqldumpslow.

5.4.6 The DDL Log
-----------------

The DDL log, or metadata log, records metadata operations generated by
data definition statements such as 'DROP TABLE' and
'ALTER TABLE'.  MySQL uses this log to recover from
crashes occurring in the middle of a metadata operation.  When executing
the statement 'DROP TABLE t1, t2', we need to ensure that both 't1' and
't2' are dropped, and that each table drop is complete.  Another example
of this type of SQL statement is 'ALTER TABLE t3 DROP PARTITION p2',
where we must make certain that
the partition is completely dropped and that its definition is removed
from the list of partitions for table 't3'.

A record of metadata operations such as those just described are written
to the file 'ddl_log.log', in the MySQL data directory.  This is a
binary file; it is not intended to be human-readable, and you should not
attempt to modify its contents in any way.

'ddl_log.log' is not created until it is actually needed for recording
metadata statements, and is removed following a successful start of
'mysqld'.  Thus, it is possible for this file not to be
present on a MySQL server that is functioning in a completely normal
manner.

Currently, 'ddl_log.log' can hold up to 1048573 entries, equivalent 4 GB
in size.  Once this limit is exceeded, you must rename or remove the
file before it is possible to execute any additional DDL statements.
This is a known issue which we are working to resolve (Bug #83708).

There are no user-configurable server options or variables associated
with this file.

5.4.7 Server Log Maintenance
----------------------------

As described in server-logs, MySQL Server can create several
different log files to help you see what activity is taking place.
However, you must clean up these files regularly to ensure that the logs
do not take up too much disk space.

When using MySQL with logging enabled, you may want to back up and
remove old log files from time to time and tell MySQL to start logging
to new files.  See backup-methods.

On a Linux (Red Hat) installation, you can use the 'mysql-log-rotate'
script for this.  If you installed MySQL from an RPM distribution, this
script should have been installed automatically.  Be careful with this
script if you are using the binary log for replication.  You should not
remove binary logs until you are certain that their contents have been
processed by all slaves.

On other systems, you must install a short script yourself that you
start from 'cron' (or its equivalent) for handling log files.

For the binary log, you can set the 'expire_logs_days' system variable
to expire binary log files automatically after a given number of days
(see server-system-variables).  If you are using replication,
you should set the variable no lower than the maximum number of days
your slaves might lag behind the master.  To remove binary logs on
demand, use the 'PURGE BINARY LOGS' statement
(see purge-binary-logs).

You can force MySQL to start using new log files by flushing the logs.
Log flushing occurs when you issue a 'FLUSH LOGS' statement or execute a
'mysqladmin flush-logs', 'mysqladmin refresh',
see 'mysqldump --flush-logs', or
'mysqldump --master-data' command.  See flush,
mysqladmin, and mysqldump.  In addition, the binary log is
flushed when its size reaches the value of the 'max_binlog_size' system
variable.

'FLUSH LOGS' supports optional modifiers to enable selective flushing of
individual logs (for example, 'FLUSH BINARY LOGS').

A log-flushing operation does the following:

   * If general query logging or slow query logging to a log file is
     enabled, the server closes and reopens the general query log file
     or slow query log file.

   * If binary logging is enabled, the server closes the current binary
     log file and opens a new log file with the next sequence number.

   * If the server was started with the '--log-error' option to cause
     the error log to be written to a file, the server closes and
     reopens the log file.

The server creates a new binary log file when you flush the logs.
However, it just closes and reopens the general and slow query log
files.  To cause new files to be created on Unix, rename the current log
files before flushing them.  At flush time, the server opens new log
files with the original names.  For example, if the general and slow
query log files are named 'mysql.log' and 'mysql-slow.log', you can use
a series of commands like this:

     shell> cd MYSQL-DATA-DIRECTORY
     shell> mv mysql.log mysql.old
     shell> mv mysql-slow.log mysql-slow.old
     shell> mysqladmin flush-logs

On Windows, use 'rename' rather than 'mv'.

At this point, you can make a backup of 'mysql.old' and 'mysql-slow.old'
and then remove them from disk.

A similar strategy can be used to back up the error log file, if there
is one.

You can rename the general query log or slow query log at runtime by
disabling the log:

     SET GLOBAL general_log = 'OFF';
     SET GLOBAL slow_query_log = 'OFF';

With the logs disabled, rename the log files externally; for example,
from the command line.  Then enable the logs again:

     SET GLOBAL general_log = 'ON';
     SET GLOBAL slow_query_log = 'ON';

This method works on any platform and does not require a server restart.

*Note*:

For the server to recreate a given log file after you have renamed the
file externally, the file location must be writable by the server.  This
may not always be the case.  For example, on Linux, the server might
write the error log as '/var/log/mysqld.log', where '/var/log' is owned
by 'root' and not writable by 'mysqld'.  In this case, the
log-flushing operation will fail to create a new log file.

To handle this situation, you must manually create the new log file with
the proper ownershiop after renaming the original log file.  For
example, execute these commands as 'root':

     shell> mv /var/log/mysqld.log /var/log/mysqld.log.old
     shell> install -omysql -gmysql -m0644 /dev/null /var/log/mysqld.log

5.5 MySQL Server Plugins
========================

MySQL supports a plugin API that enables creation of server components.
Plugins can be loaded at server startup, or loaded and unloaded at
runtime without restarting the server.  The components supported by this
interface include, but are not limited to, storage engines,
'INFORMATION_SCHEMA' tables, full-text parser plugins, partitioning
support, and server extensions.

MySQL distributions include several plugins that implement server
extensions:

   * Plugins for authenticating attempts by clients to connect to MySQL
     Server.  Plugins are available for several authentication
     protocols.  See pluggable-authentication.

   * A connection-control plugin that enables administrators to
     introduce an increasing delay after a certain number of consecutive
     failed client connection attempts.  See connection-control.

   * A password-validation plugin implements password strength policies
     and assesses the strength of potential passwords.  See
     validate-password.

   * Semisynchronous replication plugins implement an interface to
     replication capabilities that permit the master to proceed as long
     as at least one slave has responded to each transaction.  See
     replication-semisync.

   * Group Replication enables you to create a highly available
     distributed MySQL service across a group of MySQL server instances,
     with data consistency, conflict detection and resolution, and group
     membership services all built-in.  See group-replication.

   * MySQL Enterprise Edition includes a thread pool plugin that manages
     connection threads to increase server performance by efficiently
     managing statement execution threads for large numbers of client
     connections.  See thread-pool.

   * MySQL Enterprise Edition includes an audit plugin for monitoring
     and logging of connection and query activity.  See
     audit-log.

   * MySQL Enterprise Edition includes a firewall plugin that implements
     an application-level firewall to enable database administrators to
     permit or deny SQL statement execution based on matching against
     whitelists of accepted statement patterns.  See firewall.

   * A query rewrite plugin examines statements received by MySQL Server
     and possibly rewrites them before the server executes them.  See
     rewriter-query-rewrite-plugin

   * Version Tokens enables creation of and synchronization around
     server tokens that applications can use to prevent accessing
     incorrect or out-of-date data.  Version Tokens is based on a plugin
     library that implements a 'version_tokens' plugin and a set of
     user-defined functions.  See version-tokens.

   * Keyring plugins provide secure storage for sensitive information.
     See keyring.

   * X Plugin extends MySQL Server to be able to function as a document
     store.  Running X Plugin enables MySQL Server to communicate with
     clients using the X Protocol, which is designed to expose the ACID
     compliant storage abilities of MySQL as a document store.  See
     x-plugin.

   * Test framework plugins test server services.  For information about
     these plugins, see Plugins for Testing Plugin Services
     (http://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PLUGINS.html).

The following sections describe how to install and uninstall plugins,
and how to determine at runtime which plugins are installed and obtain
information about them.  For information about writing plugins, see
plugin-api.

5.5.1 Installing and Uninstalling Plugins
-----------------------------------------

Server plugins must be loaded into the server before they can be used.
MySQL supports plugin loading at server startup and runtime.  It is also
possible to control the activation state of loaded plugins at startup,
and to unload them at runtime.

   * Installing plugins

   * Controlling plugin activation state

   * Uninstalling plugins

While a plugin is loaded, information about it is available at runtime
from the 'INFORMATION_SCHEMA.PLUGINS' table and
the 'SHOW PLUGINS' statement.  See
obtaining-plugin-information.

   * server-plugin-installing

   * server-plugin-activating

   * server-plugin-uninstalling

*Installing Plugins*

Before a server plugin can be used, it must be installed using one of
the following methods.  In the descriptions, PLUGIN_NAME stands for a
plugin name such as 'innodb', 'csv', or 'validate_password'.

*Built-in plugins:*

A built-in plugin is known by the server automatically.  Normally, the
server enables the plugin at startup.  Some built-in plugins permit this
to be changed with the '--PLUGIN_NAME[=ACTIVATION_STATE]' option.

*Plugins registered in the 'mysql.plugin' system table:*

The 'mysql.plugin' table serves as a registry of plugins (other than
built-in plugins, which need not be registered).  At startup, the server
loads each plugin listed in the table.  Normally, for a plugin loaded
from the 'mysql.plugin' table, the server also enables the plugin.  This
can be changed with the '--PLUGIN_NAME[=ACTIVATION_STATE]' option.

If the server is started with the '--skip-grant-tables' option, it does
not consult the 'mysql.plugin' table and does not load the plugins
listed there.

*Plugins named with command-line options:*

A plugin located in a plugin library file can be loaded at server
startup with the '--plugin-load', '--plugin-load-add', or (as of MySQL
5.7.11) '--early-plugin-load' option.  Normally, for a plugin loaded at
startup, the server also enables the plugin.  This can be changed with
the '--PLUGIN_NAME[=ACTIVATION_STATE]' option.

The '--plugin-load' and '--plugin-load-add' options load plugins after
built-in plugins and storage engines have initialized during the server
startup sequence.  The '--early-plugin-load' option is used to load
plugins that must be available prior to initialization of built-in
plugins and storage engines.

The value of each plugin-loading option is a semicolon-separated list of
NAME'='PLUGIN_LIBRARY and PLUGIN_LIBRARY values.  Each NAME is the name
of a plugin to load, and PLUGIN_LIBRARY is the name of the library file
that contains the plugin code.  If a plugin library is named without any
preceding plugin name, the server loads all plugins in the library.  The
server looks for plugin library files in the directory named by the
'plugin_dir' system variable.

Plugin-loading options do not register any plugin in the 'mysql.plugin'
table.  For subsequent restarts, the server loads the plugin again only
if '--plugin-load', '--plugin-load-add', or '--early-plugin-load' is
given again.  That is, the option produces a one-time
plugin-installation operation that persists for a single server
invocation.

'--plugin-load', '--plugin-load-add', and '--early-plugin-load' enable
plugins to be loaded even when '--skip-grant-tables' is given (which
causes the server to ignore the 'mysql.plugin' table).  '--plugin-load',
'--plugin-load-add', and '--early-plugin-load' also enable plugins to be
loaded at startup that cannot be loaded at runtime.

The '--plugin-load-add' option complements the '--plugin-load' option:

   * Each instance of '--plugin-load' resets the set of plugins to load
     at startup, whereas '--plugin-load-add' adds a plugin or plugins to
     the set of plugins to be loaded without resetting the current set.
     Consequently, if multiple instances of '--plugin-load' are
     specified, only the last one takes effect.  With multiple instances
     of '--plugin-load-add', all of them take effect.

   * The argument format is the same as for '--plugin-load', but
     multiple instances of '--plugin-load-add' can be used to avoid
     specifying a large set of plugins as a single long unwieldy
     '--plugin-load' argument.

   * '--plugin-load-add' can be given in the absence of '--plugin-load',
     but any instance of '--plugin-load-add' that appears before
     '--plugin-load' has no effect because '--plugin-load' resets the
     set of plugins to load.

For example, these options:

     --plugin-load=x --plugin-load-add=y

are equivalent to this option:

     --plugin-load="x;y"

But these options:

     --plugin-load-add=y --plugin-load=x

are equivalent to this option:

     --plugin-load=x

*Plugins installed with the 'INSTALL PLUGIN'.
statement:*

A plugin located in a plugin library file can be loaded at runtime with
the 'INSTALL PLUGIN' statement.  The statement
also registers the plugin in the 'mysql.plugin' table to cause the
server to load it on subsequent restarts.  For this reason, see
'INSTALL PLUGIN' requires the 'INSERT' privilege for
the 'mysql.plugin' table.

The plugin library file base name depends on your platform.  Common
suffixes are '.so' for Unix and Unix-like systems, '.dll' for Windows.

Example: The '--plugin-load' option installs a plugin at server startup.
To install a plugin named 'myplugin' from a plugin library file named
'somepluglib.so', use these lines in a 'my.cnf' file:

     [mysqld]
     plugin-load=myplugin=somepluglib.so

In this case, the plugin is not registered in 'mysql.plugin'.
Restarting the server without the '--plugin-load' option causes the
plugin not to be loaded at startup.

Alternatively, the 'INSTALL PLUGIN' statement
causes the server to load the plugin code from the library file at
runtime:

     INSTALL PLUGIN myplugin SONAME 'somepluglib.so';

'INSTALL PLUGIN' also causes 'permanent' plugin
registration: The plugin is listed in the 'mysql.plugin' table to ensure
that the server loads it on subsequent restarts.

Many plugins can be loaded either at server startup or at runtime.
However, if a plugin is designed such that it must be loaded and
initialized during server startup, attempts to load it at runtime using
'INSTALL PLUGIN' produce an error:

     mysql> INSTALL PLUGIN myplugin SONAME 'somepluglib.so';
     ERROR 1721 (HY000): Plugin 'myplugin' is marked as not dynamically
     installable. You have to stop the server to install it.

In this case, you must use '--plugin-load', '--plugin-load-add', or
'--early-plugin-load'.

If a plugin is named both using a '--plugin-load', '--plugin-load-add',
or '--early-plugin-load' option and (as a result of an earlier
'INSTALL PLUGIN' statement) in the 'mysql.plugin'
table, the server starts but writes these messages to the error log:

     [ERROR] Function 'PLUGIN_NAME' already exists
     [Warning] Couldn't load plugin named 'PLUGIN_NAME'
     with soname 'PLUGIN_OBJECT_FILE'.

*Controlling Plugin Activation State*

If the server knows about a plugin when it starts (for example, because
the plugin is named using a '--plugin-load' option or is registered in
the 'mysql.plugin' table), the server loads and enables the plugin by
default.  It is possible to control activation state for such a plugin
using a '--PLUGIN_NAME[=ACTIVATION_STATE]' startup option, where
PLUGIN_NAME is the name of the plugin to affect, such as 'innodb',
'csv', or 'validate_password'.  As with other options, dashes and
underscores are interchangeable in option names.  Also, activation state
values are not case-sensitive.  For example, '--my_plugin=ON' and
'--my-plugin=on' are equivalent.

   * '--PLUGIN_NAME=OFF'

     Tells the server to disable the plugin.  This may not be possible
     for certain built-in plugins, such as 'mysql_native_password'.

   * '--PLUGIN_NAME[=ON]'

     Tells the server to enable the plugin.  (Specifying the option as
     '--PLUGIN_NAME' without a value has the same effect.)  If the
     plugin fails to initialize, the server runs with the plugin
     disabled.

   * '--PLUGIN_NAME=FORCE'

     Tells the server to enable the plugin, but if plugin initialization
     fails, the server does not start.  In other words, this option
     forces the server to run with the plugin enabled or not at all.

   * '--PLUGIN_NAME=FORCE_PLUS_PERMANENT'

     Like 'FORCE', but in addition prevents the plugin from being
     unloaded at runtime.  If a user attempts to do so with
     'UNINSTALL PLUGIN', an error occurs.

Plugin activation states are visible in the 'LOAD_OPTION' column of the
'INFORMATION_SCHEMA.PLUGINS' table.

Suppose that 'CSV', 'BLACKHOLE', and 'ARCHIVE' are built-in pluggable
storage engines and that you want the server to load them at startup,
subject to these conditions: The server is permitted to run if 'CSV'
initialization fails, must require that 'BLACKHOLE' initialization
succeeds, and should disable 'ARCHIVE'.  To accomplish that, use these
lines in an option file:

     [mysqld]
     csv=ON
     blackhole=FORCE
     archive=OFF

The '--enable-PLUGIN_NAME' option format is a synonym for
'--PLUGIN_NAME=ON'.  The '--disable-PLUGIN_NAME' and
'--skip-PLUGIN_NAME' option formats are synonyms for
'--PLUGIN_NAME=OFF'.

If a plugin is disabled, either explicitly with 'OFF' or implicitly
because it was enabled with 'ON' but failed to initialize, aspects of
server operation that require the plugin will change.  For example, if
the plugin implements a storage engine, existing tables for the storage
engine become inaccessible, and attempts to create new tables for the
storage engine result in tables that use the default storage engine
unless the 'NO_ENGINE_SUBSTITUTION' SQL mode is enabled to cause an
error to occur instead.

Disabling a plugin may require adjustment to other options.  For
example, if you start the server using '--skip-innodb' to disable
'InnoDB', other 'innodb_XXX' options likely will
need to be omitted at startup.  In addition, because 'InnoDB'
is the default storage engine, it will not start
unless you specify another available storage engine with
'--default_storage_engine'.  You must also set
'--default_tmp_storage_engine'.

*Uninstalling Plugins*

At runtime, the 'UNINSTALL PLUGIN' statement
disables and uninstalls a plugin known to the server.  The statement
unloads the plugin and removes it from the 'mysql.plugin' table, if it
is registered there.  For this reason, see 'UNINSTALL PLUGIN'
statement requires the 'DELETE' privilege for the
'mysql.plugin' table.  With the plugin no longer registered in the
table, the server will not load the plugin automatically for subsequent
restarts.

'UNINSTALL PLUGIN' can unload a plugin
regardless of whether it was loaded at runtime with 'INSTALL PLUGIN'
or at startup with a plugin-loading option,
subject to these conditions:

   * It cannot unload plugins that are built in to the server.  These
     can be identified as those that have a library name of 'NULL' in
     the output from 'INFORMATION_SCHEMA.PLUGINS'.
     or 'SHOW PLUGINS'.

   * It cannot unload plugins for which the server was started with
     '--PLUGIN_NAME=FORCE_PLUS_PERMANENT', which prevents plugin
     unloading at runtime.  These can be identified from the
     'LOAD_OPTION' column of the 'INFORMATION_SCHEMA.PLUGINS'
     table.

To uninstall a plugin that currently is loaded at server startup with a
plugin-loading option, use this procedure.

  1. Remove any options related to the plugin from the 'my.cnf' file.

  2. Restart the server.

  3. Plugins normally are installed using either a plugin-loading option
     at startup or with 'INSTALL PLUGIN' at
     runtime, but not both.  However, removing options for a plugin from
     the 'my.cnf' file may not be sufficient to uninstall it if at some
     point 'INSTALL PLUGIN' has also been used.
     If the plugin still appears in the output from
     'INFORMATION_SCHEMA.PLUGINS' or 'SHOW PLUGINS',
     use 'UNINSTALL PLUGIN'
     to remove it from the 'mysql.plugin' table.  Then
     restart the server again.

5.5.2 Obtaining Server Plugin Information
-----------------------------------------

There are several ways to determine which plugins are installed in the
server:

   * The 'INFORMATION_SCHEMA.PLUGINS' table
     contains a row for each loaded plugin.  Any that have a
     'PLUGIN_LIBRARY' value of 'NULL' are built in and cannot be
     unloaded.

          mysql> SELECT * FROM information_schema.PLUGINS\G
          *************************** 1. row ***************************
                     PLUGIN_NAME: binlog
                  PLUGIN_VERSION: 1.0
                   PLUGIN_STATUS: ACTIVE
                     PLUGIN_TYPE: STORAGE ENGINE
             PLUGIN_TYPE_VERSION: 50158.0
                  PLUGIN_LIBRARY: NULL
          PLUGIN_LIBRARY_VERSION: NULL
                   PLUGIN_AUTHOR: MySQL AB
              PLUGIN_DESCRIPTION: This is a pseudo storage engine to represent the binlog in a transaction
                  PLUGIN_LICENSE: GPL
                     LOAD_OPTION: FORCE
          ...
          *************************** 10. row ***************************
                     PLUGIN_NAME: InnoDB
                  PLUGIN_VERSION: 1.0
                   PLUGIN_STATUS: ACTIVE
                     PLUGIN_TYPE: STORAGE ENGINE
             PLUGIN_TYPE_VERSION: 50158.0
                  PLUGIN_LIBRARY: ha_innodb_plugin.so
          PLUGIN_LIBRARY_VERSION: 1.0
                   PLUGIN_AUTHOR: Innobase Oy
              PLUGIN_DESCRIPTION: Supports transactions, row-level locking,
                                  and foreign keys
                  PLUGIN_LICENSE: GPL
                     LOAD_OPTION: ON
          ...

   * The 'SHOW PLUGINS' statement displays a row
     for each loaded plugin.  Any that have a 'Library' value of 'NULL'
     are built in and cannot be unloaded.

          mysql> SHOW PLUGINS\G
          *************************** 1. row ***************************
             Name: binlog
           Status: ACTIVE
             Type: STORAGE ENGINE
          Library: NULL
          License: GPL
          ...
          *************************** 10. row ***************************
             Name: InnoDB
           Status: ACTIVE
             Type: STORAGE ENGINE
          Library: ha_innodb_plugin.so
          License: GPL
          ...

   * The 'mysql.plugin' table shows which plugins have been registered
     with 'INSTALL PLUGIN'.  The table contains
     only plugin names and library file names, so it does not provide as
     much information as the 'PLUGINS' table or
     the 'SHOW PLUGINS' statement.

5.5.3 MySQL Enterprise Thread Pool
----------------------------------

*Note*:

MySQL Enterprise Thread Pool is an extension included in MySQL
Enterprise Edition, a commercial product.  To learn more about
commercial products, <http://www.mysql.com/products/>.

MySQL Enterprise Edition includes MySQL Enterprise Thread Pool,
implemented using a server plugin.  The default thread-handling model in
MySQL Server executes statements using one thread per client connection.
As more clients connect to the server and execute statements, overall
performance degrades.  The thread pool plugin provides an alternative
thread-handling model designed to reduce overhead and improve
performance.  The plugin implements a thread pool that increases server
performance by efficiently managing statement execution threads for
large numbers of client connections.

The thread pool addresses several problems of the one thread per
connection model:

   * Too many thread stacks make CPU caches almost useless in highly
     parallel execution workloads.  The thread pool promotes thread
     stack reuse to minimize the CPU cache footprint.

   * With too many threads executing in parallel, context switching
     overhead is high.  This also presents a challenging task to the
     operating system scheduler.  The thread pool controls the number of
     active threads to keep the parallelism within the MySQL server at a
     level that it can handle and that is appropriate for the server
     host on which MySQL is executing.

   * Too many transactions executing in parallel increases resource
     contention.  In 'InnoDB', this
     increases the time spent holding central mutexes.  The thread pool
     controls when transactions start to ensure that not too many
     execute in parallel.

The thread pool plugin is included only in MySQL Enterprise Edition.  It
is not included in MySQL community distributions.

On Windows, the thread pool plugin requires Windows Vista or newer.  On
Linux, the plugin requires kernel 2.6.9 or higher.

*Additional Resources*

See faqs-thread-pool

5.5.3.1 Thread Pool Components
..............................

The thread pool feature comprises these components:

   * A plugin library file contains a plugin for the thread pool code
     and plugins for several 'INFORMATION_SCHEMA' tables.

     For a detailed description of how the thread pool works, see
     thread-pool-operation.

     The 'INFORMATION_SCHEMA' tables are named 'TP_THREAD_STATE',
     see 'TP_THREAD_GROUP_STATE',
     and 'TP_THREAD_GROUP_STATS'.
     These tables provide information
     about thread pool operation.  For more information, see
     thread-pool-i_s-tables.

   * Several system variables are related to the thread pool.  The
     'thread_handling' system variable has a value of
     'loaded-dynamically' when the server successfully loads the thread
     pool plugin.

     The other related variables are implemented by the thread pool
     plugin; they are not available unless it is enabled:

        * 'thread_pool_algorithm': The concurrency algorithm to use for
          scheduling.

        * 'thread_pool_high_priority_connection': How to schedule
          statement execution for a session.

        * 'thread_pool_prio_kickup_timer': How long before the thread
          pool moves a statement awaiting execution from the
          low-priority queue to the high-priority queue.

        * 'thread_pool_max_unused_threads': How many sleeping threads to
          permit.

        * 'thread_pool_size': The number of thread groups in the thread
          pool.  This is the most important parameter controlling thread
          pool performance.

        * 'thread_pool_stall_limit': The time before an executing
          statement is considered to be stalled.

     If any variable implemented by the plugin is set to an illegal
     value at startup, plugin initialization fails and the plugin does
     not load.

     For information about setting thread pool parameters, see
     thread-pool-tuning.

   * The Performance Schema exposes information about the thread pool
     and may be used to investigate operational performance.  For more
     information, see performance-schema.

5.5.3.2 Thread Pool Installation
................................

This section describes how to install MySQL Enterprise Thread Pool.  For
general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The plugin library file base name is 'thread_pool'.  The file name
suffix differs per platform (for example, '.so' for Unix and Unix-like
systems, '.dll' for Windows).

To enable thread pool capability, load the plugins to be used by
starting the server with the '--plugin-load-add' option.  For example,
if you name just the plugin library file, the server loads all plugins
that it contains (that is, the thread pool plugin and all the
'INFORMATION_SCHEMA' tables).  To do this, put these lines in your
'my.cnf' file (adjust the '.so' suffix for your platform as necessary):

     [mysqld]
     plugin-load-add=thread_pool.so

That is equivalent to loading all thread pool plugins by naming them
individually:

     [mysqld]
     plugin-load-add=thread_pool=thread_pool.so;tp_thread_state=thread_pool.so;tp_thread_group_state=thread_pool.so;tp_thread_group_stats=thread_pool.so

With '--plugin-load-add', all plugins need not be named on a single
line.  To make the option file easier to read, use multiple
'--plugin-load-add' options to name plugins individually:

     [mysqld]
     plugin-load-add=thread_pool=thread_pool.so
     plugin-load-add=tp_thread_state=thread_pool.so
     plugin-load-add=tp_thread_group_state=thread_pool.so
     plugin-load-add=tp_thread_group_stats=thread_pool.so

If desired, you can load individual plugins from the library file.  To
load the thread pool plugin but not the 'INFORMATION_SCHEMA' tables, use
an option like this:

     [mysqld]
     plugin-load-add=thread_pool=thread_pool.so

To load the thread pool plugin and only the 'TP_THREAD_STATE'.
'INFORMATION_SCHEMA' table, use an option like
this:

     [mysqld]
     plugin-load-add=thread_pool=thread_pool.so;tp_thread_state=thread_pool.so

*Note*:

If you do not load all the 'INFORMATION_SCHEMA' tables, some or all
MySQL Enterprise Monitor thread pool graphs will be empty.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE 'thread%' OR PLUGIN_NAME LIKE 'tp%';
     +-----------------------+---------------+
     | PLUGIN_NAME           | PLUGIN_STATUS |
     +-----------------------+---------------+
     | thread_pool           | ACTIVE        |
     | TP_THREAD_STATE       | ACTIVE        |
     | TP_THREAD_GROUP_STATE | ACTIVE        |
     | TP_THREAD_GROUP_STATS | ACTIVE        |
     +-----------------------+---------------+

If a plugin fails to initialize, check the server error log for
diagnostic messages.

If the server loads the thread pool plugin successfully, it sets the
'thread_handling' system variable to 'loaded-dynamically'.

5.5.3.3 Thread Pool Operation
.............................

The thread pool consists of a number of thread groups, each of which
manages a set of client connections.  As connections are established,
the thread pool assigns them to thread groups in round-robin fashion.

The number of thread groups is configurable using the 'thread_pool_size'
system variable.  The default number of groups is 16.  For guidelines on
setting this variable, see thread-pool-tuning.

The maximum number of threads per group is 4096 (or 4095 on some systems
where one thread is used internally).

The thread pool separates connections and threads, so there is no fixed
relationship between connections and the threads that execute statements
received from those connections.  This differs from the default
thread-handling model that associates one thread with one connection
such that the thread executes all statements from the connection.

The thread pool tries to ensure a maximum of one thread executing in
each group at any time, but sometimes permits more threads to execute
temporarily for best performance.  The algorithm works in the following
manner:

   * Each thread group has a listener thread that listens for incoming
     statements from the connections assigned to the group.  When a
     statement arrives, the thread group either begins executing it
     immediately or queues it for later execution:

        * Immediate execution occurs if the statement is the only one
          received and no statements are queued or currently executing.

        * Queuing occurs if the statement cannot begin executing
          immediately.

   * If immediate execution occurs, execution is performed by the
     listener thread.  (This means that temporarily no thread in the
     group is listening.)  If the statement finishes quickly, the
     executing thread returns to listening for statements.  Otherwise,
     the thread pool considers the statement stalled and starts another
     thread as a listener thread (creating it if necessary).  To ensure
     that no thread group becomes blocked by stalled statements, the
     thread pool has a background thread that regularly monitors thread
     group states.

     By using the listening thread to execute a statement that can begin
     immediately, there is no need to create an additional thread if the
     statement finishes quickly.  This ensures the most efficient
     execution possible in the case of a low number of concurrent
     threads.

     When the thread pool plugin starts, it creates one thread per group
     (the listener thread), plus the background thread.  Additional
     threads are created as necessary to execute statements.

   * The value of the 'thread_pool_stall_limit' system variable
     determines the meaning of 'finishes quickly' in the previous item.
     The default time before threads are considered stalled is 60ms but
     can be set to a maximum of 6s.  This parameter is configurable to
     enable you to strike a balance appropriate for the server work
     load.  Short wait values permit threads to start more quickly.
     Short values are also better for avoiding deadlock situations.
     Long wait values are useful for workloads that include long-running
     statements, to avoid starting too many new statements while the
     current ones execute.

   * The thread pool focuses on limiting the number of concurrent
     short-running statements.  Before an executing statement reaches
     the stall time, it prevents other statements from beginning to
     execute.  If the statement executes past the stall time, it is
     permitted to continue but no longer prevents other statements from
     starting.  In this way, the thread pool tries to ensure that in
     each thread group there is never more than one short-running
     statement, although there might be multiple long-running
     statements.  It is undesirable to let long-running statements
     prevent other statements from executing because there is no limit
     on the amount of waiting that might be necessary.  For example, on
     a replication master, a thread that is sending binary log events to
     a slave effectively runs forever.

   * A statement becomes blocked if it encounters a disk I/O operation
     or a user level lock (row lock or table lock).  The block would
     cause the thread group to become unused, so there are callbacks to
     the thread pool to ensure that the thread pool can immediately
     start a new thread in this group to execute another statement.
     When a blocked thread returns, the thread pool permits it to
     restart immediately.

   * There are two queues, a high-priority queue and a low-priority
     queue.  The first statement in a transaction goes to the
     low-priority queue.  Any following statements for the transaction
     go to the high-priority queue if the transaction is ongoing
     (statements for it have begun executing), or to the low-priority
     queue otherwise.  Queue assignment can be affected by enabling the
     'thread_pool_high_priority_connection' system variable, which
     causes all queued statements for a session to go into the
     high-priority queue.

     Statements for a nontransactional storage engine, or a
     transactional engine if 'autocommit' is enabled, are treated as
     low-priority statements because in this case each statement is a
     transaction.  Thus, given a mix of statements for 'InnoDB' and
     'MyISAM' tables, the thread pool prioritizes those for 'InnoDB'
     over those for 'MyISAM' unless 'autocommit' is enabled.  With
     'autocommit' enabled, all statements will be low priority.

   * When the thread group selects a queued statement for execution, it
     first looks in the high-priority queue, then in the low-priority
     queue.  If a statement is found, it is removed from its queue and
     begins to execute.

   * If a statement stays in the low-priority queue too long, the thread
     pool moves to the high-priority queue.  The value of the
     'thread_pool_prio_kickup_timer' system variable controls the time
     before movement.  For each thread group, a maximum of one statement
     per 10ms or 100 per second will be moved from the low-priority
     queue to the high-priority queue.

   * The thread pool reuses the most active threads to obtain a much
     better use of CPU caches.  This is a small adjustment that has a
     great impact on performance.

   * While a thread executes a statement from a user connection,
     Performance Schema instrumentation accounts thread activity to the
     user connection.  Otherwise, Performance Schema accounts activity
     to the thread pool.

Here are examples of conditions under which a thread group might have
multiple threads started to execute statements:

   * One thread begins executing a statement, but runs long enough to be
     considered stalled.  The thread group permits another thread to
     begin executing another statement even through the first thread is
     still executing.

   * One thread begins executing a statement, then becomes blocked and
     reports this back to the thread pool.  The thread group permits
     another thread to begin executing another statement.

   * One thread begins executing a statement, becomes blocked, but does
     not report back that it is blocked because the block does not occur
     in code that has been instrumented with thread pool callbacks.  In
     this case, the thread appears to the thread group to be still
     running.  If the block lasts long enough for the statement to be
     considered stalled, the group permits another thread to begin
     executing another statement.

The thread pool is designed to be scalable across an increasing number
of connections.  It is also designed to avoid deadlocks that can arise
from limiting the number of actively executing statements.  It is
important that threads that do not report back to the thread pool do not
prevent other statements from executing and thus cause the thread pool
to become deadlocked.  Examples of such statements follow:

   * Long-running statements.  These would lead to all resources used by
     only a few statements and they could prevent all others from
     accessing the server.

   * Binary log dump threads that read the binary log and send it to
     slaves.  This is a kind of long-running 'statement' that runs for a
     very long time, and that should not prevent other statements from
     executing.

   * Statements blocked on a row lock, table lock, sleep, or any other
     blocking activity that has not been reported back to the thread
     pool by MySQL Server or a storage engine.

In each case, to prevent deadlock, the statement is moved to the stalled
category when it does not complete quickly, so that the thread group can
permit another statement to begin executing.  With this design, when a
thread executes or becomes blocked for an extended time, the thread pool
moves the thread to the stalled category and for the rest of the
statement's execution, it does not prevent other statements from
executing.

The maximum number of threads that can occur is the sum of
'max_connections' and 'thread_pool_size'.  This can happen in a
situation where all connections are in execution mode and an extra
thread is created per group to listen for more statements.  This is not
necessarily a state that happens often, but it is theoretically
possible.

5.5.3.4 Thread Pool Tuning
..........................

This section provides guidelines on setting thread pool system variables
for best performance, measured using a metric such as transactions per
second.

'thread_pool_size' is the most important parameter controlling thread
pool performance.  It can be set only at server startup.  Our experience
in testing the thread pool indicates the following:

   * If the primary storage engine is 'InnoDB', the optimal
     'thread_pool_size' setting is likely to be between 16 and 36, with
     the most common optimal values tending to be from 24 to 36.  We
     have not seen any situation where the setting has been optimal
     beyond 36.  There may be special cases where a value smaller than
     16 is optimal.

     For workloads such as DBT2 and Sysbench, the optimum for
     'InnoDB' seems to be usually around 36.
     For very write-intensive workloads, the optimal setting can
     sometimes be lower.

   * If the primary storage engine is 'MyISAM',
     the 'thread_pool_size' setting should be
     fairly low.  We tend to get optimal performance for values from 4
     to 8.  Higher values tend to have a slightly negative but not
     dramatic impact on performance.

Another system variable, 'thread_pool_stall_limit', is important for
handling of blocked and long-running statements.  If all calls that
block the MySQL Server are reported to the thread pool, it would always
know when execution threads are blocked.  However, this may not always
be true.  For example, blocks could occur in code that has not been
instrumented with thread pool callbacks.  For such cases, the thread
pool must be able to identify threads that appear to be blocked.  This
is done by means of a timeout, the length of which can be tuned using
the 'thread_pool_stall_limit' system variable.  This parameter ensures
that the server does not become completely blocked.  The value of
'thread_pool_stall_limit' has an upper limit of 6 seconds to prevent the
risk of a deadlocked server.

'thread_pool_stall_limit' also enables the thread pool to handle
long-running statements.  If a long-running statement was permitted to
block a thread group, all other connections assigned to the group would
be blocked and unable to start execution until the long-running
statement completed.  In the worst case, this could take hours or even
days.

The value of 'thread_pool_stall_limit' should be chosen such that
statements that execute longer than its value are considered stalled.
Stalled statements generate a lot of extra overhead since they involve
extra context switches and in some cases even extra thread creations.
On the other hand, setting the 'thread_pool_stall_limit' parameter too
high means that long-running statements will block a number of
short-running statements for longer than necessary.  Short wait values
permit threads to start more quickly.  Short values are also better for
avoiding deadlock situations.  Long wait values are useful for workloads
that include long-running statements, to avoid starting too many new
statements while the current ones execute.

Suppose a server executes a workload where 99.9% of the statements
complete within 100ms even when the server is loaded, and the remaining
statements take between 100ms and 2 hours fairly evenly spread.  In this
case, it would make sense to set 'thread_pool_stall_limit' to 10
(meaning 100ms).  The default value of 60ms is okay for servers that
primarily execute very simple statements.

The 'thread_pool_stall_limit' parameter can be changed at runtime to
enable you to strike a balance appropriate for the server work load.
Assuming that the 'TP_THREAD_GROUP_STATS' table is enabled, you can use
the following query to determine the fraction of executed statements
that stalled:

     SELECT SUM(STALLED_QUERIES_EXECUTED) / SUM(QUERIES_EXECUTED)
     FROM information_schema.TP_THREAD_GROUP_STATS;

This number should be as low as possible.  To decrease the likelihood of
statements stalling, increase the value of 'thread_pool_stall_limit'.

When a statement arrives, what is the maximum time it can be delayed
before it actually starts executing?  Suppose that the following
conditions apply:

   * There are 200 statements queued in the low-priority queue.

   * There are 10 statements queued in the high-priority queue.

   * 'thread_pool_prio_kickup_timer' is set to 10000 (10 seconds).

   * 'thread_pool_stall_limit' is set to 100 (1 second).

In the worst case, the 10 high-priority statements represent 10
transactions that continue executing for a long time.  Thus, in the
worst case, no statements will be moved to the high-priority queue
because it will always already contain statements awaiting execution.
After 10 seconds, the new statement is eligible to be moved to the
high-priority queue.  However, before it can be moved, all the
statements before it must be moved as well.  This could take another 2
seconds because a maximum of 100 statements per second are moved to the
high-priority queue.  Now when the statement reaches the high-priority
queue, there could potentially be many long-running statements ahead of
it.  In the worst case, every one of those will become stalled and it
will take 1 second for each statement before the next statement is
retrieved from the high-priority queue.  Thus, in this scenario, it will
take 222 seconds before the new statement starts executing.

This example shows a worst case for an application.  How to handle it
depends on the application.  If the application has high requirements
for the response time, it should most likely throttle users at a higher
level itself.  Otherwise, it can use the thread pool configuration
parameters to set some kind of a maximum waiting time.

5.5.4 The Rewriter Query Rewrite Plugin
---------------------------------------

MySQL supports query rewrite plugins that can examine and possibly
modify SQL statements received by the server before the server executes
them.  See query-rewrite-plugin-type.

MySQL distributions include a postparse query rewrite plugin named
'Rewriter' and scripts for installing the plugin and its associated
components.  These components work together to provide 'SELECT'
rewriting capability:

   * A server-side plugin named 'Rewriter' examines 'SELECT'
     statements and may rewrite them, based on its in-memory
     cache of rewrite rules.  Standalone 'SELECT'.
     statements and 'SELECT' statements in prepared
     statements are subject to rewriting.  See 'SELECT'.
     statements occurring within view definitions or stored programs are
     not subject to rewriting.

   * The 'Rewriter' plugin uses a database named 'query_rewrite'
     containing a table named 'rewrite_rules'.  The table provides
     persistent storage for the rules that the plugin uses to decide
     whether to rewrite statements.  Users communicate with the plugin
     by modifying the set of rules stored in this table.  The plugin
     communicates with users by setting the 'message' column of table
     rows.

   * The 'query_rewrite' database contains a stored procedure named
     'flush_rewrite_rules()' that loads the contents of the rules table
     into the plugin.

   * A user-defined function named 'load_rewrite_rules()' is used by the
     'flush_rewrite_rules()' stored procedure.

   * The 'Rewriter' plugin exposes system variables that enable plugin
     configuration and status variables that provide runtime operational
     information.

The following sections describe how to install and use the 'Rewriter'
plugin, and provide reference information for its associated components.

5.5.4.1 Installing or Uninstalling the Rewriter Query Rewrite Plugin
....................................................................

*Note*:

If installed, the 'Rewriter' plugin involves some overhead even when
disabled.  To avoid this overhead, do not install the plugin unless you
plan to use it.

To install or uninstall the 'Rewriter' query rewrite plugin, choose the
approropriate script located in the 'share' directory of your MySQL
installation:

   * 'install_rewriter.sql': Choose this script to install the
     'Rewriter' plugin and its associated components.

   * 'uninstall_rewriter.sql': Choose this script to uninstall the
     'Rewriter' plugin and its associated components.

Run the chosen script as follows:

     shell> mysql -u root -p < install_rewriter.sql
     Enter password: (ENTER ROOT PASSWORD HERE)

The example here uses the 'install_rewriter.sql' installation script.
Make the appropriate substitution if you choose a different script.

Running an installation script should install and enable the plugin.  To
verify that, connect to the server and execute this statement:

     mysql> SHOW GLOBAL VARIABLES LIKE 'rewriter_enabled';
     +------------------+-------+
     | Variable_name    | Value |
     +------------------+-------+
     | rewriter_enabled | ON    |
     +------------------+-------+

For usage instructions, see rewriter-query-rewrite-plugin-usage.
For reference information, see
rewriter-query-rewrite-plugin-reference.

5.5.4.2 Using the Rewriter Query Rewrite Plugin
...............................................

To enable or disable the plugin, enable or disable the
'rewriter_enabled' system variable.  By default, the 'Rewriter' plugin
is enabled when you install it (see
rewriter-query-rewrite-plugin-installation).  To set the initial
plugin state explicitly, you can set the variable at server startup.
For example, to enable the plugin in an option file, use these lines:

     [mysqld]
     rewriter_enabled=ON

It is also possible to enable or disable the plugin at runtime:

     SET GLOBAL rewriter_enabled = ON;
     SET GLOBAL rewriter_enabled = OFF;

Assuming that the 'Rewriter' plugin is enabled, it examines and possibly
modifies each 'SELECT' statement received by the server.
The plugin determines whether to rewrite statements based on its
in-memory cache of rewriting rules, which are loaded from the
'rewrite_rules' table in the 'query_rewrite' database.

   * rewriter-query-rewrite-plugin-adding-rewrite-rules

   * rewriter-query-rewrite-plugin-how-statement-matching-works

   * rewriter-query-rewrite-plugin-rewriting-prepared-statements

   * rewriter-query-rewrite-plugin-operational-information

   * rewriter-query-rewrite-plugin-use-of-character-sets

*Adding Rewrite Rules*

To add rules for the 'Rewriter' plugin, add rows to the 'rewrite_rules'
table, then invoke the 'flush_rewrite_rules()' stored procedure to load
the rules from the table into the plugin.  The following example creates
a simple rule to match statements that select a single literal value:

     INSERT INTO query_rewrite.rewrite_rules (pattern, replacement)
     VALUES('SELECT ?', 'SELECT ? + 1');

The resulting table contents look like this:

     mysql> SELECT * FROM query_rewrite.rewrite_rules\G
     *************************** 1. row ***************************
                     id: 1
                pattern: SELECT ?
       pattern_database: NULL
            replacement: SELECT ? + 1
                enabled: YES
                message: NULL
         pattern_digest: NULL
     normalized_pattern: NULL

The rule specifies a pattern template indicating which 'SELECT'
statements to match, and a replacement template indicating how
to rewrite matching statements.  However, adding the rule to the
'rewrite_rules' table is not sufficient to cause the 'Rewriter' plugin
to use the rule.  You must invoke 'flush_rewrite_rules()' to load the
table contents into the plugin in-memory cache:

     mysql> CALL query_rewrite.flush_rewrite_rules();

*Tip*:

If your rewrite rules seem not to be working properly, make sure that
you have reloaded the rules table by calling 'flush_rewrite_rules()'.

When the plugin reads each rule from the rules table, it computes a
normalized (statement digest) form from the pattern and a digest hash
value, and uses them to update the 'normalized_pattern' and
'pattern_digest' columns:

     mysql> SELECT * FROM query_rewrite.rewrite_rules\G
     *************************** 1. row ***************************
                     id: 1
                pattern: SELECT ?
       pattern_database: NULL
            replacement: SELECT ? + 1
                enabled: YES
                message: NULL
         pattern_digest: 46b876e64cd5c41009d91c754921f1d4
     normalized_pattern: select ?

For information about statement digesting, normalized statements, and
digest hash values, see performance-schema-statement-digests.

If a rule cannot be loaded due to some error, calling
'flush_rewrite_rules()' produces an error:

     mysql> CALL query_rewrite.flush_rewrite_rules();
     ERROR 1644 (45000): Loading of some rule(s) failed.

When this occurs, the plugin writes an error message to the 'message'
column of the rule row to communicate the problem.  Check the
'rewrite_rules' table for rows with non-'NULL' 'message' column values
to see what problems exist.

Patterns use the same syntax as prepared statements (see
prepare).  Within a pattern template, '?' characters act as parameter
markers that match data values.  Parameter markers can be used only
where data values should appear, not for SQL keywords, identifiers, and
so forth.  The '?' characters should not be enclosed within quotation
marks.

Like the pattern, the replacement can contain '?' characters.  For a
statement that matches a pattern template, the plugin rewrites it,
replacing '?' parameter markers in the replacement using data values
matched by the corresponding markers in the pattern.  The result is a
complete statement string.  The plugin asks the server to parse it, and
returns the result to the server as the representation of the rewritten
statement.

After adding and loading the rule, check whether rewriting occurs
according to whether statements match the rule pattern:

     mysql> SELECT PI();
     +----------+
     | PI()     |
     +----------+
     | 3.141593 |
     +----------+
     1 row in set (0.01 sec)

     mysql> SELECT 10;
     +--------+
     | 10 + 1 |
     +--------+
     |     11 |
     +--------+
     1 row in set, 1 warning (0.00 sec)

No rewriting occurs for the first 'SELECT' statement, but
does for the second.  The second statement illustrates that when the
'Rewriter' plugin rewrites a statement, it produces a warning message.
To view the message, use 'SHOW WARNINGS'.:

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Note
        Code: 1105
     Message: Query 'SELECT 10' rewritten to 'SELECT 10 + 1' by a query rewrite plugin

To enable or disable an existing rule, modify its 'enabled' column and
reload the table into the plugin.  To disable rule 1:

     UPDATE query_rewrite.rewrite_rules SET enabled = 'NO' WHERE id = 1;
     CALL query_rewrite.flush_rewrite_rules();

This enables you to deactivate a rule without removing it from the
table.

To re-enable rule 1:

     UPDATE query_rewrite.rewrite_rules SET enabled = 'YES' WHERE id = 1;
     CALL query_rewrite.flush_rewrite_rules();

The 'rewrite_rules' table contains a 'pattern_database' column that
'Rewriter' uses for matching table names that are not qualified with a
database name:

   * Qualified table names in statements match qualified names in the
     pattern if corresponding database and table names are identical.

   * Unqualified table names in statements match unqualified names in
     the pattern only if the default database is the same as
     'pattern_database' and the table names are identical.

Suppose that a table named 'appdb.users' has a column named 'id' and
that applications are expected to select rows from the table using a
query of one of these forms, where the second can be used only if
'appdb' is the default database:

     SELECT * FROM users WHERE appdb.id = ID_VALUE;
     SELECT * FROM users WHERE id = ID_VALUE;

Suppose also that the 'id' column is renamed to 'user_id' (perhaps the
table must be modified to add another type of ID and it is necessary to
indicate more specifically what type of ID the 'id' column represents).

The change means that applications must refer to 'user_id' rather than
'id' in the 'WHERE' clause.  But if there are old applications that
cannot be written to change the 'SELECT' queries they generate, they
will no longer work properly.  The 'Rewriter' plugin can solve this
problem.  To match and rewrite statements whether or not they qualify
the table name, add the following two rules and reload the rules table:

     INSERT INTO query_rewrite.rewrite_rules
         (pattern, replacement) VALUES(
         'SELECT * FROM appdb.users WHERE id = ?',
         'SELECT * FROM appdb.users WHERE user_id = ?'
         );
     INSERT INTO query_rewrite.rewrite_rules
         (pattern, replacement, pattern_database) VALUES(
         'SELECT * FROM users WHERE id = ?',
         'SELECT * FROM users WHERE user_id = ?',
         'appdb'
         );
     CALL query_rewrite.flush_rewrite_rules();

'Rewriter' uses the first rule to match statements that use the
qualified table name.  It uses the second to match statements that used
the unqualified name, but only if the default database is 'appdb' (the
value in 'pattern_database').

*How Statement Matching Works*

The 'Rewriter' plugin uses statement digests and digest hash values to
match incoming statements against rewrite rules in stages.  The
'max_digest_length' system variable determines the size of the buffer
used for computing statement digests.  Larger values enable computation
of digests that distinguish longer statements.  Smaller values use less
memory but increase the likelihood of longer statements colliding with
the same digest value.

The plugin matches each statement to the rewrite rules as follows:

  1. Compute the statement digest hash value and compare it to the rule
     digest hash values.  This is subject to false positives, but serves
     as a quick rejection test.

  2. If the statement digest hash value matches any pattern digest hash
     values, match the normalized (statement digest) form of the
     statement to the normalized form of the matching rule patterns.

  3. If the normalized statement matches a rule, compare the literal
     values in the statement and the pattern.  A '?' character in the
     pattern matches any literal value in the statement.  If the
     statement prepares a 'SELECT' statement, '?' in the
     pattern also matches '?' in the statement.  Otherwise,
     corresponding literals must be the same.

If multiple rules match a statement, it is nondeterministic which one
the plugin uses to rewrite the statement.

If a pattern contains more markers than the replacement, the plugin
discards excess data values.  If a pattern contains fewer markers than
the replacement, it is an error.  The plugin notices this when the rules
table is loaded, writes an error message to the 'message' column of the
rule row to communicate the problem, and sets the
'Rewriter_reload_error' status variable to 'ON'.

*Rewriting Prepared Statements*

Prepared statements are rewritten at parse time (that is, when they are
prepared), not when they are executed later.

Prepared statements differ from nonprepared statements in that they may
contain '?' characters as parameter markers.  To match a '?' in a
prepared statement, a 'Rewriter' pattern must contain '?' in the same
location.  Suppose that a rewrite rule has this pattern:

     SELECT ?, 3

The following table shows several prepared 'SELECT'.
statements and whether the rule pattern matches them.

Prepared Statement                   Whether Pattern Matches Statement

'PREPARE s AS 'SELECT 3, 3''         Yes

'PREPARE s AS 'SELECT ?, 3''         Yes

'PREPARE s AS 'SELECT 3, ?''         No

'PREPARE s AS 'SELECT ?, ?''         No

*Rewriter Plugin Operational Information*

The 'Rewriter' plugin makes information available about its operation by
means of several status variables:

     mysql> SHOW GLOBAL STATUS LIKE 'Rewriter%';
     +-----------------------------------+-------+
     | Variable_name                     | Value |
     +-----------------------------------+-------+
     | Rewriter_number_loaded_rules      | 1     |
     | Rewriter_number_reloads           | 5     |
     | Rewriter_number_rewritten_queries | 1     |
     | Rewriter_reload_error             | ON    |
     +-----------------------------------+-------+

For descriptions of these variables, see
rewriter-query-rewrite-plugin-status-variables.

When you load the rules table by calling the 'flush_rewrite_rules()'
stored procedure, if an error occurs for some rule, the 'CALL' statement
produces an error, and the plugin sets the 'Rewriter_reload_error'
status variable to 'ON':

     mysql> CALL query_rewrite.flush_rewrite_rules();
     ERROR 1644 (45000): Loading of some rule(s) failed.

     mysql> SHOW GLOBAL STATUS LIKE 'Rewriter_reload_error';
     +-----------------------+-------+
     | Variable_name         | Value |
     +-----------------------+-------+
     | Rewriter_reload_error | ON    |
     +-----------------------+-------+

In this case, check the 'rewrite_rules' table for rows with non-'NULL'
'message' column values to see what problems exist.

*Rewriter Plugin Use of Character Sets*

When the 'rewrite_rules' table is loaded into the 'Rewriter' plugin, the
plugin interprets statements using the current global value of the
'character_set_client' system variable.  If the global
'character_set_client' value is changed subsequently, the rules table
must be reloaded.

A client must have a session 'character_set_client' value identical to
what the global value was when the rules table was loaded or rule
matching will not work for that client.

5.5.4.3 Rewriter Query Rewrite Plugin Reference
...............................................

The following discussion serves as a reference to these components
associated with the 'Rewriter' query rewrite plugin:

   * The 'Rewriter' rules table in the 'query_rewrite' database

   * 'Rewriter' procedures and functions

   * 'Rewriter' system and status variables

5.5.4.4 Rewriter Query Rewrite Plugin Rules Table
.................................................

The 'rewrite_rules' table in the 'query_rewrite' database provides
persistent storage for the rules that the 'Rewriter' plugin uses to
decide whether to rewrite statements.

Users communicate with the plugin by modifying the set of rules stored
in this table.  The plugin communicates information to users by setting
the table's 'message' column.

*Note*:

The rules table is loaded into the plugin by the 'flush_rewrite_rules'
stored procedure.  Unless that procedure has been called following the
most recent table modification, the table contents do not necessarily
correspond to the set of rules the plugin is using.

The 'rewrite_rules' table has these columns:

   * 'id'

     The rule ID. This column is the table primary key.  You can use the
     ID to uniquely identify any rule.

   * 'pattern'

     The template that indicates the pattern for statements that the
     rule matches.  Use '?' to represent parameter markers that match
     data values.

   * 'pattern_database'

     The database used to match unqualified table names in statements.
     Qualified table names in statements match qualified names in the
     pattern if corresponding database and table names are identical.
     Unqualified table names in statements match unqualified names in
     the pattern only if the default database is the same as
     'pattern_database' and the table names are identical.

   * 'replacement'

     The template that indicates how to rewrite statements matching the
     'pattern' column value.  Use '?' to represent parameter markers
     that match data values.  In rewritten statements, the plugin
     replaces '?' parameter markers in 'replacement' using data values
     matched by the corresponding markers in 'pattern'.

   * 'enabled'

     Whether the rule is enabled.  Load operations (performed by
     invoking the 'flush_rewrite_rules()' stored procedure) load the
     rule from the table into the 'Rewriter' in-memory cache only if
     this column is 'YES'.

     This column makes it possible to deactivate a rule without removing
     it: Set the column to a value other than 'YES' and reload the table
     into the plugin.

   * 'message'

     The plugin uses this column for communicating with users.  If no
     error occurs when the rules table is loaded into memory, the plugin
     sets the 'message' column to 'NULL'.  A non-'NULL' value indicates
     an error and the column contents are the error message.  Errors can
     occur under these circumstances:

        * Either the pattern or the replacement is an incorrect SQL
          statement that produces syntax errors.

        * The replacement contains more '?' parameter markers than the
          pattern.

     If a load error occurs, the plugin also sets the
     'Rewriter_reload_error' status variable to 'ON'.

   * 'pattern_digest'

     This column is used for debugging and diagnostics.  If the column
     exists when the rules table is loaded into memory, the plugin
     updates it with the pattern digest.  This column may be useful if
     you are trying to determine why some statement fails to be
     rewritten.

   * 'normalized_pattern'

     This column is used for debugging and diagnostics.  If the column
     exists when the rules table is loaded into memory, the plugin
     updates it with the normalized form of the pattern.  This column
     may be useful if you are trying to determine why some statement
     fails to be rewritten.

5.5.4.5 Rewriter Query Rewrite Plugin Procedures and Functions
..............................................................

'Rewriter' plugin operation uses a stored procedure that loads the rules
table into its in-memory cache, and a helper user-defined function
(UDF). Under normal operation, users invoke only the stored procedure.
The UDF is intended to be invoked by the stored procedure, not directly
by users.

   * 'flush_rewrite_rules()'

     This stored procedure uses the 'load_rewrite_rules()' UDF to load
     the contents of the 'rewrite_rules' table into the 'Rewriter'
     in-memory cache.  After loading the table, it also clears the query
     cache.

     Calling 'flush_rewrite_rules()' implies 'COMMIT'.

     Invoke this procedure after you modify the rules table to cause the
     plugin to update its cache from the new table contents.  If any
     errors occur, the plugin sets the 'message' column for the
     appropriate rule rows in the table and sets the
     'Rewriter_reload_error' status variable to 'ON'.

   * 'load_rewrite_rules()'

     This UDF is a helper routine used by the 'flush_rewrite_rules()'
     stored procedure.

5.5.4.6 Rewriter Query Rewrite Plugin System Variables
......................................................

The 'Rewriter' query rewrite plugin supports the following system
variables.  These variables are available only if the plugin is
installed (see rewriter-query-rewrite-plugin-installation).

   *
     'rewriter_enabled'

     Property                             Value

     *Introduced*                         5.7.6

     *System Variable*                    'rewriter_enabled'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Whether the 'Rewriter' query rewrite plugin is enabled.

   *
     'rewriter_verbose'

     Property                             Value

     *Introduced*                         5.7.6

     *System Variable*                    'rewriter_verbose'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     For internal use.

5.5.4.7 Rewriter Query Rewrite Plugin Status Variables
......................................................

The 'Rewriter' query rewrite plugin supports the following status
variables.  These variables are available only if the plugin is
installed (see rewriter-query-rewrite-plugin-installation).

   *
     'Rewriter_number_loaded_rules'

     The number of rewrite plugin rewrite rules successfully loaded from
     the 'rewrite_rules' table into memory for use by the 'Rewriter'
     plugin.

   *
     'Rewriter_number_reloads'

     The number of times the 'rewrite_rules' table has been loaded into
     the in-memory cache used by the 'Rewriter' plugin.

   *
     'Rewriter_number_rewritten_queries'

     The number of queries rewritten by the 'Rewriter' query rewrite
     plugin since it was loaded.

   *
     'Rewriter_reload_error'

     Whether an error occurred the most recent time that the
     'rewrite_rules' table was loaded into the in-memory cache used by
     the 'Rewriter' plugin.  If the value is 'OFF', no error occurred.
     If the value is 'ON', an error occurred; check the 'message' column
     of the 'rewriter_rules' table for error messages.

5.5.5 Version Tokens
--------------------

MySQL includes Version Tokens, a feature that enables creation of and
synchronization around server tokens that applications can use to
prevent accessing incorrect or out-of-date data.

The Version Tokens interface has these characteristics:

   * Version tokens are pairs consisting of a name that serves as a key
     or identifier, plus a value.

   * Version tokens can be locked.  An application can use token locks
     to indicate to other cooperating applications that tokens are in
     use and should not be modified.

   * Version token lists are established per server; for example, to
     specify the server assignment or operational state.  In addition,
     an application that communicates with a server can register its own
     list of tokens that indicate the state it requires the server to be
     in.  An SQL statement sent by the application to a server not in
     the required state produces an error.  This is a signal to the
     application that it should seek a different server in the required
     state to receive the SQL statement.

The following sections describe the components of Version Tokens,
discuss how to install and use it, and provide reference information for
its components.

5.5.5.1 Version Tokens Components
.................................

Version Tokens is based on a plugin library that implements these
components:

   * A server-side plugin named 'version_tokens' holds the list of
     version tokens associated with the server and subscribes to
     notifications for statement execution events.  The 'version_tokens'
     plugin uses the audit plugin API to monitor incoming statements
     from clients and matches each client's session-specific version
     token list against the server version token list.  If there is a
     match, the plugin lets the statement through and the server
     continues to process it.  Otherwise, the plugin returns an error to
     the client and the statement fails.

   * A set of user-defined functions (UDFs) provides an SQL-level API
     for manipulating and inspecting the list of server version tokens
     maintained by the plugin.  The 'SUPER' privilege is required to
     call any of the Version Token UDFs.

   * A system variable enables clients to specify the list of version
     tokens that register the required server state.  If the server has
     a different state when a client sends a statement, the client
     receives an error.

5.5.5.2 Installing or Uninstalling Version Tokens
.................................................

*Note*:

If installed, Version Tokens involves some overhead.  To avoid this
overhead, do not install it unless you plan to use it.

This section describes how to install or uninstall Version Tokens, which
is implemented in a plugin library file containing a plugin and
user-defined functions.  For general information about installing or
uninstalling plugins and UDFs, see server-plugin-loading, and
udf-compiling.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The plugin library file base name is 'version_tokens'.  The file name
suffix differs per platform (for example, '.so' for Unix and Unix-like
systems, '.dll' for Windows).

To install the Version Tokens plugin and UDFs, use the 'INSTALL PLUGIN'
and 'CREATE FUNCTION'.
statements (adjust the '.so' suffix for your platform as necessary):

     INSTALL PLUGIN version_tokens SONAME 'version_token.so';
     CREATE FUNCTION version_tokens_set RETURNS STRING SONAME 'version_token.so';
     CREATE FUNCTION version_tokens_show RETURNS STRING SONAME 'version_token.so';
     CREATE FUNCTION version_tokens_edit RETURNS STRING SONAME 'version_token.so';
     CREATE FUNCTION version_tokens_delete RETURNS STRING SONAME 'version_token.so';
     CREATE FUNCTION version_tokens_lock_shared RETURNS INT SONAME 'version_token.so';
     CREATE FUNCTION version_tokens_lock_exclusive RETURNS INT SONAME 'version_token.so';
     CREATE FUNCTION version_tokens_unlock RETURNS INT SONAME 'version_token.so';

You must install the UDFs to manage the server's version token list, but
you must also install the plugin because the UDFs will not work
correctly without it.

If the plugin and UDFs are used on a master replication server, install
them on all slave servers as well to avoid replication problems.

Once installed as just described, the Version Tokens plugin and UDFs
remain installed until uninstalled.  To remove them, use the
'UNINSTALL PLUGIN' and 'DROP FUNCTION'
statements:

     UNINSTALL PLUGIN version_tokens;
     DROP FUNCTION version_tokens_set;
     DROP FUNCTION version_tokens_show;
     DROP FUNCTION version_tokens_edit;
     DROP FUNCTION version_tokens_delete;
     DROP FUNCTION version_tokens_lock_shared;
     DROP FUNCTION version_tokens_lock_exclusive;
     DROP FUNCTION version_tokens_unlock;

5.5.5.3 Using Version Tokens
............................

Before using Version Tokens, install it according to the instructions
provided at version-tokens-installation.

A scenario in which Version Tokens can be useful is a system that
accesses a collection of MySQL servers but needs to manage them for load
balancing purposes by monitoring them and adjusting server assignments
according to load changes.  Such a system comprises these components:

   * The collection of MySQL servers to be managed.

   * An administrative or management application that communicates with
     the servers and organizes them into high-availability groups.
     Groups serve different purposes, and servers within each group may
     have different assignments.  Assignment of a server within a
     certain group can change at any time.

   * Client applications that access the servers to retrieve and update
     data, choosing servers according to the purposes assigned them.
     For example, a client should not send an update to a read-only
     server.

Version Tokens permit server access to be managed according to
assignment without requiring clients to repeatedly query the servers
about their assignments:

   * The management application performs server assignments and
     establishes version tokens on each server to reflect its
     assignment.  The application caches this information to provide a
     central access point to it.

     If at some point the management application needs to change a
     server assignment (for example, to change it from permitting writes
     to read only), it changes the server's version token list and
     updates its cache.

   * To improve performance, client applications obtain cache
     information from the management application, enabling them to avoid
     having to retrieve information about server assignments for each
     statement.  Based on the type of statements it will issue (for
     example, reads versus writes), a client selects an appropriate
     server and connects to it.

   * In addition, the client sends to the server its own client-specific
     version tokens to register the assignment it requires of the
     server.  For each statement sent by the client to the server, the
     server compares its own token list with the client token list.  If
     the server token list contains all tokens present in the client
     token list with the same values, there is a match and the server
     executes the statement.

     On the other hand, perhaps the management application has changed
     the server assignment and its version token list.  In this case,
     the new server assignment may now be incompatible with the client
     requirements.  A token mismatch between the server and client token
     lists occurs and the server returns an error in reply to the
     statement.  This is an indication to the client to refresh its
     version token information from the management application cache,
     and to select a new server to communicate with.

The client-side logic for detecting version token errors and selecting a
new server can be implemented different ways:

   * The client can handle all version token registration, mismatch
     detection, and connection switching itself.

   * The logic for those actions can be implemented in a connector that
     manages connections between clients and MySQL servers.  Such a
     connector might handle mismatch error detection and statement
     resending itself, or it might pass the error to the application and
     leave it to the application to resend the statement.

The following example illustrates the preceding discussion in more
concrete form.

When Version Tokens initializes on a given server, the server's version
token list is empty.  Token list maintenance is performed by calling
user-defined functions (UDFs).  The 'SUPER' privilege is required to
call any of the Version Token UDFs, so token list modification is
expected to be done by a management or administrative application that
has that privilege.

Suppose that a management application communicates with a set of servers
that are queried by clients to access employee and product databases
(named 'emp' and 'prod', respectively).  All servers are permitted to
process data retrieval statements, but only some of them are permitted
to make database updates.  To handle this on a database-specific basis,
the management application establishes a list of version tokens on each
server.  In the token list for a given server, token names represent
database names and token values are 'read' or 'write' depending on
whether the database must be used in read-only fashion or whether it can
take reads and writes.

Client applications register a list of version tokens they require the
server to match by setting a system variable.  Variable setting occurs
on a client-specific basis, so different clients can register different
requirements.  By default, the client token list is empty, which matches
any server token list.  When a client sets its token list to a nonempty
value, matching may succeed or fail, depending on the server version
token list.

To define the version token list for a server, the management
application calls the 'version_token_set()' UDF. (There are also UDFs
for modifying and displaying the token list, described later.)  For
example, the application might send these statements to a group of three
servers:

Server 1:

     mysql> SELECT version_tokens_set('emp=read;prod=read');
     +------------------------------------------+
     | version_tokens_set('emp=read;prod=read') |
     +------------------------------------------+
     | 2 version tokens set.                    |
     +------------------------------------------+

Server 2:

     mysql> SELECT version_tokens_set('emp=write;prod=read');
     +-------------------------------------------+
     | version_tokens_set('emp=write;prod=read') |
     +-------------------------------------------+
     | 2 version tokens set.                     |
     +-------------------------------------------+

Server 3:

     mysql> SELECT version_tokens_set('emp=read;prod=write');
     +-------------------------------------------+
     | version_tokens_set('emp=read;prod=write') |
     +-------------------------------------------+
     | 2 version tokens set.                     |
     +-------------------------------------------+

The token list in each case is specified as a semicolon-separated list
of 'NAME=VALUE' pairs.  The resulting token list values result in these
server assingments:

   * Any server accepts reads for either database.

   * Only server 2 accepts updates for the 'emp' database.

   * Only server 3 accepts updates for the 'prod' database.

In addition to assigning each server a version token list, the
management application also maintains a cache that reflects the server
assignments.

Before communicating with the servers, a client application contacts the
management application and retrieves information about server
assignments.  Then the client selects a server based on those
assignments.  Suppose that a client wants to perform both reads and
writes on the 'emp' database.  Based on the preceding assignments, only
server 2 qualifies.  The client connects to server 2 and registers its
server requirements there by setting its 'version_tokens_session' system
variable:

     mysql> SET @@session.version_tokens_session = 'emp=write';

For subsequent statements sent by the client to server 2, the server
compares its own version token list to the client list to check whether
they match.  If so, statements execute normally:

     mysql> UPDATE emp.employee SET salary = salary * 1.1 WHERE id = 4981;
     Query OK, 1 row affected (0.07 sec)
     Rows matched: 1  Changed: 1  Warnings: 0

     mysql> SELECT last_name, first_name FROM emp.employee WHERE id = 4981;
     +-----------+------------+
     | last_name | first_name |
     +-----------+------------+
     | Smith     | Abe        |
     +-----------+------------+
     1 row in set (0.01 sec)

Discrepancies between the server and client version token lists can
occur two ways:

   * A token name in the 'version_tokens_session' value is not present
     in the server token list.  In this case, an
     'ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND' error occurs.

   * A token value in the 'version_tokens_session' value differs from
     the value of the corresponding token in the server token list.  In
     this case, an 'ER_VTOKEN_PLUGIN_TOKEN_MISMATCH' error occurs.

As long as the assignment of server 2 does not change, the client
continues to use it for reads and writes.  But suppose that the
management application wants to change server assignments so that writes
for the 'emp' database must be sent to server 1 instead of server 2.  To
do this, it uses 'version_tokens_edit()' to modify the 'emp' token value
on the two servers (and updates its cache of server assignments):

Server 1:

     mysql> SELECT version_tokens_edit('emp=write');
     +----------------------------------+
     | version_tokens_edit('emp=write') |
     +----------------------------------+
     | 1 version tokens updated.        |
     +----------------------------------+

Server 2:

     mysql> SELECT version_tokens_edit('emp=read');
     +---------------------------------+
     | version_tokens_edit('emp=read') |
     +---------------------------------+
     | 1 version tokens updated.       |
     +---------------------------------+

'version_tokens_edit()' modifies the named tokens in the server token
list and leaves other tokens unchanged.

The next time the client sends a statement to server 2, its own token
list no longer matches the server token list and an error occurs:

     mysql> UPDATE emp.employee SET salary = salary * 1.1 WHERE id = 4982;
     ERROR 3136 (42000): Version token mismatch for emp. Correct value read

In this case, the client should contact the management application to
obtain updated information about server assignments, select a new
server, and send the failed statement to the new server.

*Note*:

Each client must cooperate with Version Tokens by sending only
statements in accordance with the token list that it registers with a
given server.  For example, if a client registers a token list of
''emp=read'', there is nothing in Version Tokens to prevent the client
from sending updates for the 'emp' database.  The client itself must
refrain from doing so.

For each statement received from a client, the server implicitly uses
locking, as follows:

   * Take a shared lock for each token named in the client token list
     (that is, in the 'version_tokens_session' value)

   * Perform the comparison between the server and client token lists

   * Execute the statement or produce an error depending on the
     comparison result

   * Release the locks

The server uses shared locks so that comparisons for multiple sessions
can occur without blocking, while preventing changes to the tokens for
any session that attempts to acquire an exclusive lock before it
manipulates tokens of the same names in the server token list.

The preceding example uses only a few of the user-defined included in
the Version Tokens plugin library, but there are others.  One set of
UDFs permits the server's list of version tokens to be manipulated and
inspected.  Another set of UDFs permits version tokens to be locked and
unlocked.

These UDFs permit the server's list of version tokens to be created,
changed, removed, and inspected:

   * 'version_tokens_set()' completely replaces the current list and
     assigns a new list.  The argument is a semicolon-separated list of
     'NAME=VALUE' pairs.

   * 'version_tokens_edit()' enables partial modifications to the
     current list.  It can add new tokens or change the values of
     existing tokens.  The argument is a semicolon-separated list of
     'NAME=VALUE' pairs.

   * 'version_tokens_delete()' deletes tokens from the current list.
     The argument is a semicolon-separated list of token names.

   * 'version_tokens_show()' displays the current token list.  It takes
     no argument.

Each of those functions, if successful, returns a binary string
indicating what action occurred.  The following example establishes the
server token list, modifies it by adding a new token, deletes some
tokens, and displays the resulting token list:

     mysql> SELECT version_tokens_set('tok1=a;tok2=b');
     +-------------------------------------+
     | version_tokens_set('tok1=a;tok2=b') |
     +-------------------------------------+
     | 2 version tokens set.               |
     +-------------------------------------+
     mysql> SELECT version_tokens_edit('tok3=c');
     +-------------------------------+
     | version_tokens_edit('tok3=c') |
     +-------------------------------+
     | 1 version tokens updated.     |
     +-------------------------------+
     mysql> SELECT version_tokens_delete('tok2;tok1');
     +------------------------------------+
     | version_tokens_delete('tok2;tok1') |
     +------------------------------------+
     | 2 version tokens deleted.          |
     +------------------------------------+
     mysql> SELECT version_tokens_show();
     +-----------------------+
     | version_tokens_show() |
     +-----------------------+
     | tok3=c;               |
     +-----------------------+

Warnings occur if a token list is malformed:

     mysql> SELECT version_tokens_set('tok1=a; =c');
     +----------------------------------+
     | version_tokens_set('tok1=a; =c') |
     +----------------------------------+
     | 1 version tokens set.            |
     +----------------------------------+
     1 row in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Warning
        Code: 42000
     Message: Invalid version token pair encountered. The list provided
              is only partially updated.
     1 row in set (0.00 sec)

As mentioned previously, version tokens are defined using a
semicolon-separated list of 'NAME=VALUE' pairs.  Consider this
invocation of 'version_tokens_set()':

     mysql> SELECT version_tokens_set('tok1=b;;; tok2= a = b ; tok1 = 1\'2 3"4')
     +---------------------------------------------------------------+
     | version_tokens_set('tok1=b;;; tok2= a = b ; tok1 = 1\'2 3"4') |
     +---------------------------------------------------------------+
     | 3 version tokens set.                                         |
     +---------------------------------------------------------------+

Version Tokens interprets the argument as follows:

   * Whitespace around names and values is ignored.  Whitespace within
     names and values is permitted.  (For 'version_tokens_delete()',
     which takes a list of names without values, whitespace around names
     is ignored.)

   * There is no quoting mechanism.

   * Order of tokens is not significant except that if a token list
     contains multiple instances of a given token name, the last value
     takes precedence over earlier values.

Given those rules, the preceding 'version_tokens_set()' call results in
a token list with two tokens: 'tok1' has the value '1'2 3"4', and 'tok2'
has the value 'a = b'.  To verify this, call 'version_tokens_show()':

     mysql> SELECT version_tokens_show();
     +--------------------------+
     | version_tokens_show()    |
     +--------------------------+
     | tok2=a = b;tok1=1'2 3"4; |
     +--------------------------+

If the token list contains two tokens, why did 'version_tokens_set()'
return the value '3 version tokens set'?  That occurred because the
original token list contained two definitions for 'tok1', and the second
definition replaced the first.

The Version Tokens token-manipulation UDFs place these constraints on
token names and values:

   * Token names cannot contain '=' or ';' characters and have a maximum
     length of 64 characters.

   * Token values cannot contain ';' characters.  Length of values is
     constrained by the value of the 'max_allowed_packet' system
     variable.

   * Version Tokens treats token names and values as binary strings, so
     comparisons are case-sensitive.

Version Tokens also includes a set of UDFs enabling tokens to be locked
and unlocked:

   * 'version_tokens_lock_exclusive()' acquires exclusive version token
     locks.  It takes a list of one or more lock names and a timeout
     value.

   * 'version_tokens_lock_shared()' acquires shared version token locks.
     It takes a list of one or more lock names and a timeout value.

   * 'version_tokens_unlock()' releases version token locks (exclusive
     and shared).  It takes no argument.

Each locking function returns nonzero for success.  Otherwise, an error
occurs:

     mysql> SELECT version_tokens_lock_shared('lock1', 'lock2', 0);
     +-------------------------------------------------+
     | version_tokens_lock_shared('lock1', 'lock2', 0) |
     +-------------------------------------------------+
     |                                               1 |
     +-------------------------------------------------+

     mysql> SELECT version_tokens_lock_shared(NULL, 0);
     ERROR 3131 (42000): Incorrect locking service lock name '(null)'.

Locking using Version Tokens locking functions is advisory; applications
must agree to cooperate.

It is possible to lock nonexisting token names.  This does not create
the tokens.

*Note*:

Version Tokens locking functions are based on the locking service
described at locking-service, and thus have the same semantics
for shared and exclusive locks.  (Version Tokens uses the locking
service routines built into the server, not the locking service UDF
interface, so those UDFs need not be installed to use Version Tokens.)
Locks acquired by Version Tokens use a locking service namespace of
'version_token_locks'.  Locking service locks can be monitored using the
Performance Schema, so this is also true for Version Tokens locks.  For
details, see locking-service-monitoring.

For the Version Tokens locking functions, token name arguments are used
exactly as specified.  Surrounding whitespace is not ignored and '=' and
';' characters are permitted.  This is because Version Tokens simply
passes the token names to be locked as is to the locking service.

5.5.5.4 Version Tokens Reference
................................

The following discussion serves as a reference to these Version Tokens
components:

   * version-tokens-routines

   * version-tokens-system-variables

*Version Tokens Functions*

The Version Tokens plugin library includes several user-defined
functions.  One set of UDFs permits the server's list of version tokens
to be manipulated and inspected.  Another set of UDFs permits version
tokens to be locked and unlocked.  The 'SUPER' privilege is required to
invoke any Version Tokens UDF.

The following UDFs permit the server's list of version tokens to be
created, changed, removed, and inspected.  Interpretation of NAME_LIST
and TOKEN_LIST arguments (including whitespace handling) occurs as
described in version-tokens-usage, which provides details about
the syntax for specifying tokens, as well as additional examples.

   * 'version_tokens_delete(NAME_LIST)'

     Deletes tokens from the server's list of version tokens using the
     NAME_LIST argument and returns a binary string that indicates the
     outcome of the operation.  NAME_LIST is a semicolon-separated list
     of version token names to delete.

          mysql> SELECT version_tokens_delete('tok1;tok3');
          +------------------------------------+
          | version_tokens_delete('tok1;tok3') |
          +------------------------------------+
          | 2 version tokens deleted.          |
          +------------------------------------+

     An argument of 'NULL' is treated as an empty string, which has no
     effect on the token list.

     'version_tokens_delete()' deletes the tokens named in its argument,
     if they exist.  (It is not an error to delete nonexisting tokens.)
     To clear the token list entirely without knowing which tokens are
     in the list, pass 'NULL' or a string containing no tokens to
     'version_tokens_set()':

          mysql> SELECT version_tokens_set(NULL);
          +------------------------------+
          | version_tokens_set(NULL)     |
          +------------------------------+
          | Version tokens list cleared. |
          +------------------------------+
          mysql> SELECT version_tokens_set('');
          +------------------------------+
          | version_tokens_set('')       |
          +------------------------------+
          | Version tokens list cleared. |
          +------------------------------+

   * 'version_tokens_edit(TOKEN_LIST)'

     Modifies the server's list of version tokens using the TOKEN_LIST
     argument and returns a binary string that indicates the outcome of
     the operation.  TOKEN_LIST is a semicolon-separated list of
     'NAME=VALUE' pairs specifying the name of each token to be defined
     and its value.  If a token exists, its value is updated with the
     given value.  If a token does not exist, it is created with the
     given value.  If the argument is 'NULL' or a string containing no
     tokens, the token list remains unchanged.

          mysql> SELECT version_tokens_set('tok1=value1;tok2=value2');
          +-----------------------------------------------+
          | version_tokens_set('tok1=value1;tok2=value2') |
          +-----------------------------------------------+
          | 2 version tokens set.                         |
          +-----------------------------------------------+
          mysql> SELECT version_tokens_edit('tok2=new_value2;tok3=new_value3');
          +--------------------------------------------------------+
          | version_tokens_edit('tok2=new_value2;tok3=new_value3') |
          +--------------------------------------------------------+
          | 2 version tokens updated.                              |
          +--------------------------------------------------------+

   * 'version_tokens_set(TOKEN_LIST)'

     Replaces the server's list of version tokens with the tokens
     defined in the TOKEN_LIST argument and returns a binary string that
     indicates the outcome of the operation.  TOKEN_LIST is a
     semicolon-separated list of 'NAME=VALUE' pairs specifying the name
     of each token to be defined and its value.  If the argument is
     'NULL' or a string containing no tokens, the token list is cleared.

          mysql> SELECT version_tokens_set('tok1=value1;tok2=value2');
          +-----------------------------------------------+
          | version_tokens_set('tok1=value1;tok2=value2') |
          +-----------------------------------------------+
          | 2 version tokens set.                         |
          +-----------------------------------------------+

   * 'version_tokens_show()'

     Returns the server's list of version tokens as a binary string
     containing a semicolon-separated list of 'NAME=VALUE' pairs.

          mysql> SELECT version_tokens_show();
          +--------------------------+
          | version_tokens_show()    |
          +--------------------------+
          | tok2=value2;tok1=value1; |
          +--------------------------+

The following UDFs permit version tokens to be locked and unlocked:

   * 'version_tokens_lock_exclusive(TOKEN_NAME[, TOKEN_NAME] ...,
     TIMEOUT)'

     Acquires exclusive locks on one or more version tokens, specified
     by name as strings, timing out with an error if the locks are not
     acquired within the given timeout value.

          mysql> SELECT version_tokens_lock_exclusive('lock1', 'lock2', 10);
          +-----------------------------------------------------+
          | version_tokens_lock_exclusive('lock1', 'lock2', 10) |
          +-----------------------------------------------------+
          |                                                   1 |
          +-----------------------------------------------------+

   * 'version_tokens_lock_shared(TOKEN_NAME[, TOKEN_NAME] ..., TIMEOUT)'

     Acquires shared locks on one or more version tokens, specified by
     name as strings, timing out with an error if the locks are not
     acquired within the given timeout value.

          mysql> SELECT version_tokens_lock_shared('lock1', 'lock2', 10);
          +--------------------------------------------------+
          | version_tokens_lock_shared('lock1', 'lock2', 10) |
          +--------------------------------------------------+
          |                                                1 |
          +--------------------------------------------------+

   * 'version_tokens_unlock()'

     Releases all locks that were acquired within the current session
     using 'version_tokens_lock_exclusive()' and
     'version_tokens_lock_shared()'.

          mysql> SELECT version_tokens_unlock();
          +-------------------------+
          | version_tokens_unlock() |
          +-------------------------+
          |                       1 |
          +-------------------------+

The locking functions share these characteristics:

   * The return value is nonzero for success.  Otherwise, an error
     occurs.

   * Token names are strings.

   * In contrast to argument handling for the UDFs that manipulate the
     server token list, whitespace surrounding token name arguments is
     not ignored and '=' and ';' characters are permitted.

   * It is possible to lock nonexisting token names.  This does not
     create the tokens.

   * Timeout values are nonnegative integers representing the time in
     seconds to wait to acquire locks before timing out with an error.
     If the timeout is 0, there is no waiting and the function produces
     an error if locks cannot be acquired immediately.

   * Version Tokens locking functions are based on the locking service
     described at locking-service.

*Version Tokens System Variables*

Version Tokens supports the following system variables.  These variables
are unavailable unless the Version Tokens plugin is installed (see
version-tokens-installation).

System variables:

   *
     'version_tokens_session'

     Property                             Value

     *Command-Line Format*                '--version-tokens-session=value'

     *Introduced*                         5.7.8

     *System Variable*                    'version_tokens_session'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     The session value of this variable specifies the client version
     token list and indicates the tokens that the client session
     requires the server version token list to have.

     If the 'version_tokens_session' variable is 'NULL' (the default) or
     has an empty value, any server version token list matches.  (In
     effect, an empty value disables matching requirements.)

     If the 'version_tokens_session' variable has a nonempty value, any
     mismatch between its value and the server version token list
     results in an error for any statement the session sends to the
     server.  A mismatch occurs under these conditions:

        * A token name in the 'version_tokens_session' value is not
          present in the server token list.  In this case, an
          'ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND' error occurs.

        * A token value in the 'version_tokens_session' value differs
          from the value of the corresponding token in the server token
          list.  In this case, an 'ER_VTOKEN_PLUGIN_TOKEN_MISMATCH'
          error occurs.

     It is not a mismatch for the server version token list to include a
     token not named in the 'version_tokens_session' value.

     Suppose that a management application has set the server token list
     as follows:

          mysql> SELECT version_tokens_set('tok1=a;tok2=b;tok3=c');
          +--------------------------------------------+
          | version_tokens_set('tok1=a;tok2=b;tok3=c') |
          +--------------------------------------------+
          | 3 version tokens set.                      |
          +--------------------------------------------+

     A client registers the tokens it requires the server to match by
     setting its 'version_tokens_session' value.  Then, for each
     subsequent statement sent by the client, the server checks its
     token list against the client 'version_tokens_session' value and
     produces an error if there is a mismatch:

          mysql> SET @@session.version_tokens_session = 'tok1=a;tok2=b';
          mysql> SELECT 1;
          +---+
          | 1 |
          +---+
          | 1 |
          +---+

          mysql> SET @@session.version_tokens_session = 'tok1=b';
          mysql> SELECT 1;
          ERROR 3136 (42000): Version token mismatch for tok1. Correct value a

     The first 'SELECT' succeeds because the client
     tokens 'tok1' and 'tok2' are present in the server token list and
     each token has the same value in the server list.  The second
     'SELECT' fails because, although 'tok1' is present in the
     server token list, it has a different value than specified by the
     client.

     At this point, any statement sent by the client fails, unless the
     server token list changes such that it matches again.  Suppose that
     the management application changes the server token list as
     follows:

          mysql> SELECT version_tokens_edit('tok1=b');
          +-------------------------------+
          | version_tokens_edit('tok1=b') |
          +-------------------------------+
          | 1 version tokens updated.     |
          +-------------------------------+
          mysql> SELECT version_tokens_show();
          +-----------------------+
          | version_tokens_show() |
          +-----------------------+
          | tok3=c;tok1=b;tok2=b; |
          +-----------------------+

     Now the client 'version_tokens_session' value matches the server
     token list and the client can once again successfully execute
     statements:

          mysql> SELECT 1;
          +---+
          | 1 |
          +---+
          | 1 |
          +---+

   *
     'version_tokens_session_number'

     Property                             Value

     *Command-Line Format*                '--version-tokens-session-number=N'

     *Introduced*                         5.7.8

     *System Variable*                    'version_tokens_session_number'

     *Scope*                              Global, Session

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '0'

     This variable is for internal use.

5.6 Running Multiple MySQL Instances on One Machine
===================================================

In some cases, you might want to run multiple instances of MySQL on a
single machine.  You might want to test a new MySQL release while
leaving an existing production setup undisturbed.  Or you might want to
give different users access to different 'mysqld' servers
that they manage themselves.  (For example, you might be an Internet
Service Provider that wants to provide independent MySQL installations
for different customers.)

It is possible to use a different MySQL server binary per instance, or
use the same binary for multiple instances, or any combination of the
two approaches.  For example, you might run a server from MySQL 5.6 and
one from MySQL 5.7, to see how different versions handle a given
workload.  Or you might run multiple instances of the current production
version, each managing a different set of databases.

Whether or not you use distinct server binaries, each instance that you
run must be configured with unique values for several operating
parameters.  This eliminates the potential for conflict between
instances.  Parameters can be set on the command line, in option files,
or by setting environment variables.  See program-options.  To
see the values used by a given instance, connect to it and execute a
'SHOW VARIABLES' statement.

The primary resource managed by a MySQL instance is the data directory.
Each instance should use a different data directory, the location of
which is specified using the '--datadir=DIR_NAME' option.  For methods
of configuring each instance with its own data directory, and warnings
about the dangers of failing to do so, see
multiple-data-directories.

In addition to using different data directories, several other options
must have different values for each server instance:

   * '--port=PORT_NUM'

     '--port' controls the port number for TCP/IP connections.
     Alternatively, if the host has multiple network addresses, you can
     use '--bind-address' to cause each server to listen to a different
     address.

   * '--socket={FILE_NAME|PIPE_NAME}'

     '--socket' controls the Unix socket file path on Unix or the named
     pipe name on Windows.  On Windows, it is necessary to specify
     distinct pipe names only for those servers configured to permit
     named-pipe connections.

   * '--shared-memory-base-name=NAME'

     This option is used only on Windows.  It designates the
     shared-memory name used by a Windows server to permit clients to
     connect using shared memory.  It is necessary to specify distinct
     shared-memory names only for those servers configured to permit
     shared-memory connections.

   * '--pid-file=FILE_NAME'

     This option indicates the path name of the file in which the server
     writes its process ID.

If you use the following log file options, their values must differ for
each server:

   * '--general_log_file=FILE_NAME'

   * '--log-bin[=FILE_NAME]'

   * '--slow_query_log_file=FILE_NAME'

   * '--log-error[=FILE_NAME]'

For further discussion of log file options, see server-logs.

To achieve better performance, you can specify the following option
differently for each server, to spread the load between several physical
disks:

   * '--tmpdir=DIR_NAME'

Having different temporary directories also makes it easier to determine
which MySQL server created any given temporary file.

If you have multiple MySQL installations in different locations, you can
specify the base directory for each installation with the
'--basedir=DIR_NAME' option.  This causes each instance to automatically
use a different data directory, log files, and PID file because the
default for each of those parameters is relative to the base directory.
In that case, the only other options you need to specify are the
'--socket' and '--port' options.  Suppose that you install different
versions of MySQL using 'tar' file binary distributions.  These install
in different locations, so you can start the server for each
installation using the command 'bin/mysqld_safe' under its corresponding
base directory.  'mysqld_safe' determines the proper
'--basedir' option to pass to 'mysqld', and you need
specify only the '--socket' and '--port' options to 'mysqld_safe'.

As discussed in the following sections, it is possible to start
additional servers by specifying appropriate command options or by
setting environment variables.  However, if you need to run multiple
servers on a more permanent basis, it is more convenient to use option
files to specify for each server those option values that must be unique
to it.  The '--defaults-file' option is useful for this purpose.

5.6.1 Setting Up Multiple Data Directories
------------------------------------------

Each MySQL Instance on a machine should have its own data directory.
The location is specified using the '--datadir=DIR_NAME' option.

There are different methods of setting up a data directory for a new
instance:

   * Create a new data directory.

   * Copy an existing data directory.

The following discussion provides more detail about each method.

*Warning*:

Normally, you should never have two servers that update data in the same
databases.  This may lead to unpleasant surprises if your operating
system does not support fault-free system locking.  If (despite this
warning) you run multiple servers using the same data directory and they
have logging enabled, you must use the appropriate options to specify
log file names that are unique to each server.  Otherwise, the servers
try to log to the same files.

Even when the preceding precautions are observed, this kind of setup
works only with 'MyISAM' and 'MERGE' tables, and not with any of the
other storage engines.  Also, this warning against sharing a data
directory among servers always applies in an NFS environment.
Permitting multiple MySQL servers to access a common data directory over
NFS is a _very bad idea_.  The primary problem is that NFS is the speed
bottleneck.  It is not meant for such use.  Another risk with NFS is
that you must devise a way to ensure that two or more servers do not
interfere with each other.  Usually NFS file locking is handled by the
'lockd' daemon, but at the moment there is no platform that performs
locking 100% reliably in every situation.

*Create a New Data Directory*

With this method, the data directory will be in the same state as when
you first install MySQL. It will have the default set of MySQL accounts
and no user data.

On Unix, initialize the data directory.  See postinstallation.

On Windows, the data directory is included in the MySQL distribution:

   * MySQL Zip archive distributions for Windows contain an unmodified
     data directory.  You can unpack such a distribution into a
     temporary location, then copy it 'data' directory to where you are
     setting up the new instance.

   * Windows MSI package installers create and set up the data directory
     that the installed server will use, but also create a pristine
     'template' data directory named 'data' under the installation
     directory.  After an installation has been performed using an MSI
     package, the template data directory can be copied to set up
     additional MySQL instances.

*Copy an Existing Data Directory*

With this method, any MySQL accounts or user data present in the data
directory are carried over to the new data directory.

  1. Stop the existing MySQL instance using the data directory.  This
     must be a clean shutdown so that the instance flushes any pending
     changes to disk.

  2. Copy the data directory to the location where the new data
     directory should be.

  3. Copy the 'my.cnf' or 'my.ini' option file used by the existing
     instance.  This serves as a basis for the new instance.

  4. Modify the new option file so that any pathnames referring to the
     original data directory refer to the new data directory.  Also,
     modify any other options that must be unique per instance, such as
     the TCP/IP port number and the log files.  For a list of parameters
     that must be unique per instance, see multiple-servers.

  5. Start the new instance, telling it to use the new option file.

5.6.2 Running Multiple MySQL Instances on Windows
-------------------------------------------------

You can run multiple servers on Windows by starting them manually from
the command line, each with appropriate operating parameters, or by
installing several servers as Windows services and running them that
way.  General instructions for running MySQL from the command line or as
a service are given in windows-installation.  The following
sections describe how to start each server with different values for
those options that must be unique per server, such as the data
directory.  These options are listed in multiple-servers.

5.6.2.1 Starting Multiple MySQL Instances at the Windows Command Line
.....................................................................

The procedure for starting a single MySQL server manually from the
command line is described in windows-start-command-line.  To
start multiple servers this way, you can specify the appropriate options
on the command line or in an option file.  It is more convenient to
place the options in an option file, but it is necessary to make sure
that each server gets its own set of options.  To do this, create an
option file for each server and tell the server the file name with a
'--defaults-file' option when you run it.

Suppose that you want to run one instance of 'mysqld' on
port 3307 with a data directory of 'C:\mydata1', and another instance on
port 3308 with a data directory of 'C:\mydata2'.  Use this procedure:

  1. Make sure that each data directory exists, including its own copy
     of the 'mysql' database that contains the grant tables.

  2. Create two option files.  For example, create one file named
     'C:\my-opts1.cnf' that looks like this:

          [mysqld]
          datadir = C:/mydata1
          port = 3307

     Create a second file named 'C:\my-opts2.cnf' that looks like this:

          [mysqld]
          datadir = C:/mydata2
          port = 3308

  3. Use the '--defaults-file' option to start each server with its own
     option file:

          C:\> C:\mysql\bin\mysqld --defaults-file=C:\my-opts1.cnf
          C:\> C:\mysql\bin\mysqld --defaults-file=C:\my-opts2.cnf

     Each server starts in the foreground (no new prompt appears until
     the server exits later), so you will need to issue those two
     commands in separate console windows.

To shut down the servers, connect to each using the appropriate port
number:

     C:\> C:\mysql\bin\mysqladmin --port=3307 --host=127.0.0.1 --user=root --password shutdown
     C:\> C:\mysql\bin\mysqladmin --port=3308 --host=127.0.0.1 --user=root --password shutdown

Servers configured as just described permit clients to connect over
TCP/IP. If your version of Windows supports named pipes and you also
want to permit named-pipe connections, specify options that enable the
named pipe and specify its name.  Each server that supports named-pipe
connections must use a unique pipe name.  For example, the
'C:\my-opts1.cnf' file might be written like this:

     [mysqld]
     datadir = C:/mydata1
     port = 3307
     enable-named-pipe
     socket = mypipe1

Modify 'C:\my-opts2.cnf' similarly for use by the second server.  Then
start the servers as described previously.

A similar procedure applies for servers that you want to permit
shared-memory connections.  Enable such connections with the
'--shared-memory' option and specify a unique shared-memory name for
each server with the '--shared-memory-base-name' option.

5.6.2.2 Starting Multiple MySQL Instances as Windows Services
.............................................................

On Windows, a MySQL server can run as a Windows service.  The procedures
for installing, controlling, and removing a single MySQL service are
described in windows-start-service.

To set up multiple MySQL services, you must make sure that each instance
uses a different service name in addition to the other parameters that
must be unique per instance.

For the following instructions, suppose that you want to run the
'mysqld' server from two different versions of MySQL that are
installed at 'C:\mysql-5.5.9' and 'C:\mysql-5.7.23', respectively.
(This might be the case if you are running 5.5.9 as your production
server, but also want to conduct tests using 5.7.23.)

To install MySQL as a Windows service, use the '--install' or
'--install-manual' option.  For information about these options, see
windows-start-service.

Based on the preceding information, you have several ways to set up
multiple services.  The following instructions describe some examples.
Before trying any of them, shut down and remove any existing MySQL
services.

   * *Approach 1:* Specify the options for all services in one of the
     standard option files.  To do this, use a different service name
     for each server.  Suppose that you want to run the 5.5.9
     'mysqld' using the service name of 'mysqld1' and the
     5.7.23 'mysqld' using the service name 'mysqld2'.
     In this case, you can use the '[mysqld1]' group for 5.5.9 and the
     '[mysqld2]' group for 5.7.23.  For example, you can set up
     'C:\my.cnf' like this:

          # options for mysqld1 service
          [mysqld1]
          basedir = C:/mysql-5.5.9
          port = 3307
          enable-named-pipe
          socket = mypipe1

          # options for mysqld2 service
          [mysqld2]
          basedir = C:/mysql-5.7.23
          port = 3308
          enable-named-pipe
          socket = mypipe2

     Install the services as follows, using the full server path names
     to ensure that Windows registers the correct executable program for
     each service:

          C:\> C:\mysql-5.5.9\bin\mysqld --install mysqld1
          C:\> C:\mysql-5.7.23\bin\mysqld --install mysqld2

     To start the services, use the services manager, or use 'NET START'
     with the appropriate service names:

          C:\> NET START mysqld1
          C:\> NET START mysqld2

     To stop the services, use the services manager, or use 'NET STOP'
     with the appropriate service names:

          C:\> NET STOP mysqld1
          C:\> NET STOP mysqld2

   * *Approach 2:* Specify options for each server in separate files and
     use '--defaults-file' when you install the services to tell each
     server what file to use.  In this case, each file should list
     options using a '[mysqld]' group.

     With this approach, to specify options for the 5.5.9
     'mysqld', create a file 'C:\my-opts1.cnf' that looks like
     this:

          [mysqld]
          basedir = C:/mysql-5.5.9
          port = 3307
          enable-named-pipe
          socket = mypipe1

     For the 5.7.23 'mysqld', create a file
     'C:\my-opts2.cnf' that looks like this:

          [mysqld]
          basedir = C:/mysql-5.7.23
          port = 3308
          enable-named-pipe
          socket = mypipe2

     Install the services as follows (enter each command on a single
     line):

          C:\> C:\mysql-5.5.9\bin\mysqld --install mysqld1
                     --defaults-file=C:\my-opts1.cnf
          C:\> C:\mysql-5.7.23\bin\mysqld --install mysqld2
                     --defaults-file=C:\my-opts2.cnf

     When you install a MySQL server as a service and use a
     '--defaults-file' option, the service name must precede the option.

     After installing the services, start and stop them the same way as
     in the preceding example.

To remove multiple services, use 'mysqld --remove' for
each one, specifying a service name following the '--remove' option.  If
the service name is the default ('MySQL'), you can omit it.

5.6.3 Running Multiple MySQL Instances on Unix
----------------------------------------------

*Note*:

The discussion here uses 'mysqld_safe' to launch
multiple instances of MySQL. For MySQL installation using an RPM
distribution, server startup and shutdown is managed by systemd on
several Linux platforms.  On these platforms, see 'mysqld_safe'
is not installed because it is unnecessary.  For
information about using systemd to handle multiple MySQL instances, see
using-systemd.

One way is to run multiple MySQL instances on Unix is to compile
different servers with different default TCP/IP ports and Unix socket
files so that each one listens on different network interfaces.
Compiling in different base directories for each installation also
results automatically in a separate, compiled-in data directory, log
file, and PID file location for each server.

Assume that an existing 5.6 server is configured for the default TCP/IP
port number (3306) and Unix socket file ('/tmp/mysql.sock').  To
configure a new 5.7.23 server to have different operating parameters,
use a 'CMake' command something like this:

     shell> cmake . -DMYSQL_TCP_PORT=PORT_NUMBER \
                  -DMYSQL_UNIX_ADDR=FILE_NAME \
                  -DCMAKE_INSTALL_PREFIX=/usr/local/mysql-5.7.23

Here, PORT_NUMBER and FILE_NAME must be different from the default
TCP/IP port number and Unix socket file path name, and the
'CMAKE_INSTALL_PREFIX' value should specify an installation directory
different from the one under which the existing MySQL installation is
located.

If you have a MySQL server listening on a given port number, you can use
the following command to find out what operating parameters it is using
for several important configurable variables, including the base
directory and Unix socket file name:

     shell> mysqladmin --host=HOST_NAME --port=PORT_NUMBER variables

With the information displayed by that command, you can tell what option
values _not_ to use when configuring an additional server.

If you specify 'localhost' as the host name, see 'mysqladmin'
defaults to using a Unix socket file connection rather than
TCP/IP. To explicitly specify the connection protocol, use the
'--protocol={TCP|SOCKET|PIPE|MEMORY}' option.

You need not compile a new MySQL server just to start with a different
Unix socket file and TCP/IP port number.  It is also possible to use the
same server binary and start each invocation of it with different
parameter values at runtime.  One way to do so is by using command-line
options:

     shell> mysqld_safe --socket=FILE_NAME --port=PORT_NUMBER

To start a second server, provide different '--socket' and '--port'
option values, and pass a '--datadir=DIR_NAME' option to
'mysqld_safe' so that the server uses a different data
directory.

Alternatively, put the options for each server in a different option
file, then start each server using a '--defaults-file' option that
specifies the path to the appropriate option file.  For example, if the
option files for two server instances are named
'/usr/local/mysql/my.cnf' and '/usr/local/mysql/my.cnf2', start the
servers like this: command:

     shell> mysqld_safe --defaults-file=/usr/local/mysql/my.cnf
     shell> mysqld_safe --defaults-file=/usr/local/mysql/my.cnf2

Another way to achieve a similar effect is to use environment variables
to set the Unix socket file name and TCP/IP port number:

     shell> MYSQL_UNIX_PORT=/tmp/mysqld-new.sock
     shell> MYSQL_TCP_PORT=3307
     shell> export MYSQL_UNIX_PORT MYSQL_TCP_PORT
     shell> mysql_install_db --user=mysql
     shell> mysqld_safe --datadir=/path/to/datadir &

This is a quick way of starting a second server to use for testing.  The
nice thing about this method is that the environment variable settings
apply to any client programs that you invoke from the same shell.  Thus,
connections for those clients are automatically directed to the second
server.

See environment-variables, includes a list of other environment
variables you can use to affect MySQL programs.

On Unix, the 'mysqld_multi' script provides another
way to start multiple servers.  See mysqld-multi.

5.6.4 Using Client Programs in a Multiple-Server Environment
------------------------------------------------------------

To connect with a client program to a MySQL server that is listening to
different network interfaces from those compiled into your client, you
can use one of the following methods:

   * Start the client with '--host=HOST_NAME' '--port=PORT_NUMBER' to
     connect using TCP/IP to a remote server, with '--host=127.0.0.1'
     '--port=PORT_NUMBER' to connect using TCP/IP to a local server, or
     with '--host=localhost' '--socket=FILE_NAME' to connect to a local
     server using a Unix socket file or a Windows named pipe.

   * Start the client with '--protocol=TCP' to connect using TCP/IP,
     '--protocol=SOCKET' to connect using a Unix socket file,
     '--protocol=PIPE' to connect using a named pipe, or
     '--protocol=MEMORY' to connect using shared memory.  For TCP/IP
     connections, you may also need to specify '--host' and '--port'
     options.  For the other types of connections, you may need to
     specify a '--socket' option to specify a Unix socket file or
     Windows named-pipe name, or a '--shared-memory-base-name' option to
     specify the shared-memory name.  Shared-memory connections are
     supported only on Windows.

   *
     On Unix, set the 'MYSQL_UNIX_PORT' and 'MYSQL_TCP_PORT' environment
     variables to point to the Unix socket file and TCP/IP port number
     before you start your clients.  If you normally use a specific
     socket file or port number, you can place commands to set these
     environment variables in your '.login' file so that they apply each
     time you log in.  See environment-variables.

   *
     Specify the default Unix socket file and TCP/IP port number in the
     '[client]' group of an option file.  For example, you can use
     'C:\my.cnf' on Windows, or the '.my.cnf' file in your home
     directory on Unix.  See option-files.

   * In a C program, you can specify the socket file or port number
     arguments in the 'mysql_real_connect()'.
     call.  You can also have the program read option files by calling
     'mysql_options()'.  See
     c-api-functions.

   * If you are using the Perl 'DBD::mysql' module, you can read options
     from MySQL option files.  For example:

          $dsn = "DBI:mysql:test;mysql_read_default_group=client;"
                  . "mysql_read_default_file=/usr/local/mysql/data/my.cnf";
          $dbh = DBI->connect($dsn, $user, $password);

     See apis-perl.

     Other programming interfaces may provide similar capabilities for
     reading option files.

5.7 Tracing mysqld Using DTrace
===============================

Support for DTrace is deprecated in MySQL 5.7 and is removed in MySQL
8.0.

The DTrace probes in the MySQL server are designed to provide
information about the execution of queries within MySQL and the
different areas of the system being utilized during that process.  The
organization and triggering of the probes means that the execution of an
entire query can be monitored with one level of probes ('query-start'
and 'query-done') but by monitoring other probes you can get
successively more detailed information about the execution of the query
in terms of the locks used, sort methods and even row-by-row and
storage-engine level execution information.

The DTrace probes are organized so that you can follow the entire query
process, from the point of connection from a client, through the query
execution, row-level operations, and back out again.  You can think of
the probes as being fired within a specific sequence during a typical
client connect/execute/disconnect sequence, as shown in the following
figure.

FIGURE GOES HERE: DTrace Probe Sequence

Global information is provided in the arguments to the DTrace probes at
various levels.  Global information, that is, the connection ID and
user/host and where relevant the query string, is provided at key levels
('connection-start', 'command-start', 'query-start', and
'query-exec-start').  As you go deeper into the probes, it is assumed
either you are only interested in the individual executions (row-level
probes provide information on the database and table name only), or that
you will combine the row-level probes with the notional parent probes to
provide the information about a specific query.  Examples of this will
be given as the format and arguments of each probe are provided.

MySQL includes support for DTrace probes on these platforms:

   * Solaris 10 Update 5 (Solaris 5/08) on SPARC, x86 and x86_64
     platforms

   * OS X 10.4 and higher

   * Oracle Linux 6 and higher with UEK kernel (as of MySQL 5.7.5)

Enabling the probes should be automatic on these platforms.  To
explicitly enable or disable the probes during building, use the
'-DENABLE_DTRACE=1' or '-DENABLE_DTRACE=0' option to 'CMake'.

If a non-Solaris platform includes DTrace support, building
'mysqld' on that platform will include DTrace support.

*Additional Resources*

   * For more information on DTrace and writing DTrace scripts, read the
     DTrace User Guide (http://docs.oracle.com/cd/E19253-01/819-5488/).

   * For an introduction to DTrace, see the MySQL Dev Zone article
     Getting started with DTracing MySQL
     (http://dev.mysql.com/tech-resources/articles/mysql-cluster-7.2.html).

5.7.1 mysqld DTrace Probe Reference
-----------------------------------

MySQL supports the following static probes, organized into groups of
functionality.

*MySQL DTrace Probes*

Group          Probes

See 'connection-start', 'connection-done' Connection.

See 'command-start', 'command-done' Command.

See Query, 'query-done'
dba-dtrace-ref-query.

See Query 'query-parse-start', 'query-parse-done' Parsing.

See Query 'query-cache-hit', 'query-cache-miss' Cache.

See Query 'query-exec-start', 'query-exec-done' Execution.

See Row 'insert-row-start', 'insert-row-done' Level.

               'update-row-start', 'update-row-done'

               'delete-row-start', 'delete-row-done'

See Row 'read-row-start', 'read-row-done' Reads.

See Index 'index-read-row-start', 'index-read-row-done' Reads.

See Lock, 'handler-rdlock-done'
dba-dtrace-ref-lock.

               'handler-wrlock-start', 'handler-wrlock-done'

               'handler-unlock-start', 'handler-unlock-done'

See 'filesort-start', 'filesort-done' Filesort.

See 'select-start', 'select-done' Statement.

               'insert-start', 'insert-done'

               'insert-select-start', 'insert-select-done'

               'update-start', 'update-done'

               'multi-update-start', 'multi-update-done'

               'delete-start', 'delete-done'

               'multi-delete-start', 'multi-delete-done'

See 'net-read-start', 'net-read-done', 'net-write-start', Network.

See 'keycache-read-start', 'keycache-read-block', Keycache,
'keycache-read-hit',
dba-dtrace-ref-keycache.'keycache-read-miss', 'keycache-write-start',
               'keycache-write-block', 'keycache-write-done'

*Note*:

When extracting the argument data from the probes, each argument is
available as 'argN', starting with 'arg0'.  To identify each argument
within the definitions they are provided with a descriptive name, but
you must access the information using the corresponding 'argN'
parameter.

5.7.1.1 Connection Probes
.........................

The 'connection-start' and 'connection-done' probes enclose a connection
from a client, regardless of whether the connection is through a socket
or network connection.

     connection-start(connectionid, user, host)
     connection-done(status, connectionid)

   * 'connection-start': Triggered after a connection and successful
     login/authentication have been completed by a client.  The
     arguments contain the connection information:

        * 'connectionid': An 'unsigned long' containing the connection
          ID. This is the same as the process ID shown as the 'Id' value
          in the output from 'SHOW PROCESSLIST'.

        * 'user': The username used when authenticating.  The value will
          be blank for the anonymous user.

        * 'host': The host of the client connection.  For a connection
          made using Unix sockets, the value will be blank.

   * 'connection-done': Triggered just as the connection to the client
     has been closed.  The arguments are:

        * 'status': The status of the connection when it was closed.  A
          logout operation will have a value of 0; any other termination
          of the connection has a nonzero value.

        * 'connectionid': The connection ID of the connection that was
          closed.

The following D script will quantify and summarize the average duration
of individual connections, and provide a count, dumping the information
every 60 seconds:

     #!/usr/sbin/dtrace -s

     mysql*:::connection-start
     {
       self->start = timestamp;
     }

     mysql*:::connection-done
     /self->start/
     {
       @ = quantize(((timestamp - self->start)/1000000));
       self->start = 0;
     }

     tick-60s
     {
       printa(@);
     }

When executed on a server with a large number of clients you might see
output similar to this:

       1  57413                        :tick-60s

                value  ------------- Distribution ------------- count
                   -1 |                                         0
                    0 |@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 30011
                    1 |                                         59
                    2 |                                         5
                    4 |                                         20
                    8 |                                         29
                   16 |                                         18
                   32 |                                         27
                   64 |                                         30
                  128 |                                         11
                  256 |                                         10
                  512 |                                         1
                 1024 |                                         6
                 2048 |                                         8
                 4096 |                                         9
                 8192 |                                         8
                16384 |                                         2
                32768 |                                         1
                65536 |                                         1
               131072 |                                         0
               262144 |                                         1
               524288 |                                         0

5.7.1.2 Command Probes
......................

The command probes are executed before and after a client command is
executed, including any SQL statement that might be executed during that
period.  Commands include operations such as the initialization of the
DB, use of the 'COM_CHANGE_USER' operation (supported by the MySQL
protocol), and manipulation of prepared statements.  Many of these
commands are used only by the MySQL client API from various connectors
such as PHP and Java.

     command-start(connectionid, command, user, host)
     command-done(status)

   * 'command-start': Triggered when a command is submitted to the
     server.

        * 'connectionid': The connection ID of the client executing the
          command.

        * 'command': An integer representing the command that was
          executed.  Possible values are shown in the following table.

          Value   Name           Description

          00      COM_SLEEP      Internal thread state

          01      COM_QUIT       Close connection

          02      COM_INIT_DB    Select database ('USE ...')

          03      COM_QUERY      Execute a query

          04      COM_FIELD_LIST Get a list of fields

          05      COM_CREATE_DB  Create a database (deprecated)

          06      COM_DROP_DB    Drop a database (deprecated)

          07      COM_REFRESH    Refresh connection

          08      COM_SHUTDOWN   Shutdown server

          09      COM_STATISTICS Get statistics

          10      COM_PROCESS_INFOGet processes (see 'SHOW PROCESSLIST')

          11      COM_CONNECT    Initialize connection

          12      COM_PROCESS_KILLKill process

          13      COM_DEBUG      Get debug information

          14      COM_PING       Ping

          15      COM_TIME       Internal thread state

          16      COM_DELAYED_INSERTInternal thread state

          17      COM_CHANGE_USERChange user

          18      COM_BINLOG_DUMPUsed by a replication slave or
                                 'mysqlbinlog' to initiate a binary
                                 log read

          19      COM_TABLE_DUMP Used by a replication slave to get the master
                                 table information

          20      COM_CONNECT_OUTUsed by a replication slave to log a connection
                                 to the server

          21      COM_REGISTER_SLAVEUsed by a replication slave during registration

          22      COM_STMT_PREPAREPrepare a statement

          23      COM_STMT_EXECUTEExecute a statement

          24      COM_STMT_SEND_LONG_DATAUsed by a client when requesting extended data

          25      COM_STMT_CLOSE Close a prepared statement

          26      COM_STMT_RESET Reset a prepared statement

          27      COM_SET_OPTION Set a server option

          28      COM_STMT_FETCH Fetch a prepared statement

        * 'user': The user executing the command.

        * 'host': The client host.

   * 'command-done': Triggered when the command execution completes.
     The 'status' argument contains 0 if the command executed
     successfully, or 1 if the statement was terminated before normal
     completion.

The 'command-start' and 'command-done' probes are best used when
combined with the statement probes to get an idea of overall execution
time.

5.7.1.3 Query Probes
....................

The 'query-start' and 'query-done' probes are triggered when a specific
query is received by the server and when the query has been completed
and the information has been successfully sent to the client.

     query-start(query, connectionid, database, user, host)
     query-done(status)

   * 'query-start': Triggered after the query string has been received
     from the client.  The arguments are:

        * 'query': The full text of the submitted query.

        * 'connectionid': The connection ID of the client that submitted
          the query.  The connection ID equals the connection ID
          returned when the client first connects and the 'Id' value in
          the output from 'SHOW PROCESSLIST'.

        * 'database': The database name on which the query is being
          executed.

        * 'user': The username used to connect to the server.

        * 'host': The hostname of the client.

   * 'query-done': Triggered once the query has been executed and the
     information has been returned to the client.  The probe includes a
     single argument, 'status', which returns 0 when the query is
     successfully executed and 1 if there was an error.

You can get a simple report of the execution time for each query using
the following D script:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     dtrace:::BEGIN
     {
        printf("%-20s %-20s %-40s %-9s\n", "Who", "Database", "Query", "Time(ms)");
     }

     mysql*:::query-start
     {
        self->query = copyinstr(arg0);
        self->connid = arg1;
        self->db    = copyinstr(arg2);
        self->who   = strjoin(copyinstr(arg3),strjoin("@",copyinstr(arg4)));
        self->querystart = timestamp;
     }

     mysql*:::query-done
     {
        printf("%-20s %-20s %-40s %-9d\n",self->who,self->db,self->query,
               (timestamp - self->querystart) / 1000000);
     }

When executing the above script you should get a basic idea of the
execution time of your queries:

     shell> ./query.d
     Who                  Database             Query                                    Time(ms)
     root@localhost       test                 select * from t1 order by i limit 10     0
     root@localhost       test                 set global query_cache_size=0            0
     root@localhost       test                 select * from t1 order by i limit 10     776
     root@localhost       test                 select * from t1 order by i limit 10     773
     root@localhost       test                 select * from t1 order by i desc limit 10 795

5.7.1.4 Query Parsing Probes
............................

The query parsing probes are triggered before the original SQL statement
is parsed and when the parsing of the statement and determination of the
execution model required to process the statement has been completed:

     query-parse-start(query)
     query-parse-done(status)

   * 'query-parse-start': Triggered just before the statement is parsed
     by the MySQL query parser.  The single argument, 'query', is a
     string containing the full text of the original query.

   * 'query-parse-done': Triggered when the parsing of the original
     statement has been completed.  The 'status' is an integer
     describing the status of the operation.  A '0' indicates that the
     query was successfully parsed.  A '1' indicates that the parsing of
     the query failed.

For example, you could monitor the execution time for parsing a given
query using the following D script:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     mysql*:::query-parse-start
     {
        self->parsestart = timestamp;
        self->parsequery = copyinstr(arg0);
     }

     mysql*:::query-parse-done
     /arg0 == 0/
     {
        printf("Parsing %s: %d microseconds\n", self->parsequery,((timestamp - self->parsestart)/1000));
     }

     mysql*:::query-parse-done
     /arg0 != 0/
     {
        printf("Error parsing %s: %d microseconds\n", self->parsequery,((timestamp - self->parsestart)/1000));
     }

In the above script a predicate is used on 'query-parse-done' so that
different output is generated based on the status value of the probe.

When running the script and monitoring the execution:

     shell> ./query-parsing.d
     Error parsing select from t1 join (t2) on (t1.i = t2.i) order by t1.s,t1.i limit 10: 36 ms
     Parsing select * from t1 join (t2) on (t1.i = t2.i) order by t1.s,t1.i limit 10: 176 ms

5.7.1.5 Query Cache Probes
..........................

The query cache probes are fired when executing any query.  The
'query-cache-hit' query is triggered when a query exists in the query
cache and can be used to return the query cache information.  The
arguments contain the original query text and the number of rows
returned from the query cache for the query.  If the query is not within
the query cache, or the query cache is not enabled, then the
'query-cache-miss' probe is triggered instead.

     query-cache-hit(query, rows)
     query-cache-miss(query)

   * 'query-cache-hit': Triggered when the query has been found within
     the query cache.  The first argument, 'query', contains the
     original text of the query.  The second argument, 'rows', is an
     integer containing the number of rows in the cached query.

   * 'query-cache-miss': Triggered when the query is not found within
     the query cache.  The first argument, 'query', contains the
     original text of the query.

The query cache probes are best combined with a probe on the main query
so that you can determine the differences in times between using or not
using the query cache for specified queries.  For example, in the
following D script, the query and query cache information are combined
into the information output during monitoring:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     dtrace:::BEGIN
     {
        printf("%-20s %-20s %-40s %2s %-9s\n", "Who", "Database", "Query", "QC", "Time(ms)");
     }

     mysql*:::query-start
     {
        self->query = copyinstr(arg0);
        self->connid = arg1;
        self->db    = copyinstr(arg2);
        self->who   = strjoin(copyinstr(arg3),strjoin("@",copyinstr(arg4)));
        self->querystart = timestamp;
        self->qc = 0;
     }

     mysql*:::query-cache-hit
     {
        self->qc = 1;
     }

     mysql*:::query-cache-miss
     {
        self->qc = 0;
     }

     mysql*:::query-done
     {
        printf("%-20s %-20s %-40s %-2s %-9d\n",self->who,self->db,self->query,(self->qc ? "Y" : "N"),
               (timestamp - self->querystart) / 1000000);
     }

When executing the script you can see the effects of the query cache.
Initially the query cache is disabled.  If you set the query cache size
and then execute the query multiple times you should see that the query
cache is being used to return the query data:

     shell> ./query-cache.d
     root@localhost       test                 select * from t1 order by i limit 10     N  1072
     root@localhost                            set global query_cache_size=262144       N  0
     root@localhost       test                 select * from t1 order by i limit 10     N  781
     root@localhost       test                 select * from t1 order by i limit 10     Y  0

5.7.1.6 Query Execution Probes
..............................

The query execution probe is triggered when the actual execution of the
query starts, after the parsing and checking the query cache but before
any privilege checks or optimization.  By comparing the difference
between the start and done probes you can monitor the time actually
spent servicing the query (instead of just handling the parsing and
other elements of the query).

     query-exec-start(query, connectionid, database, user, host, exec_type)
     query-exec-done(status)

*Note*:

The information provided in the arguments for 'query-start' and
'query-exec-start' are almost identical and designed so that you can
choose to monitor either the entire query process (using 'query-start')
or only the execution (using 'query-exec-start') while exposing the core
information about the user, client, and query being executed.

   * 'query-exec-start': Triggered when the execution of a individual
     query is started.  The arguments are:

        * 'query': The full text of the submitted query.

        * 'connectionid': The connection ID of the client that submitted
          the query.  The connection ID equals the connection ID
          returned when the client first connects and the 'Id' value in
          the output from 'SHOW PROCESSLIST'.

        * 'database': The database name on which the query is being
          executed.

        * 'user': The username used to connect to the server.

        * 'host': The hostname of the client.

        * 'exec_type': The type of execution.  Execution types are
          determined based on the contents of the query and where it was
          submitted.  The values for each type are shown in the
          following table.

          Value   Description

          0       Executed query from sql_parse, top-level query.

          1       Executed prepared statement

          2       Executed cursor statement

          3       Executed query in stored procedure

   * 'query-exec-done': Triggered when the execution of the query has
     completed.  The probe includes a single argument, 'status', which
     returns 0 when the query is successfully executed and 1 if there
     was an error.

5.7.1.7 Row-Level Probes
........................

The '*row-{start,done}' probes are triggered each time a row operation
is pushed down to a storage engine.  For example, if you execute an
'INSERT' statement with 100 rows of data, then the
'insert-row-start' and 'insert-row-done' probes will be triggered 100
times each, for each row insert.

     insert-row-start(database, table)
     insert-row-done(status)

     update-row-start(database, table)
     update-row-done(status)

     delete-row-start(database, table)
     delete-row-done(status)

   * 'insert-row-start': Triggered before a row is inserted into a
     table.

   * 'insert-row-done': Triggered after a row is inserted into a table.

   * 'update-row-start': Triggered before a row is updated in a table.

   * 'update-row-done': Triggered before a row is updated in a table.

   * 'delete-row-start': Triggered before a row is deleted from a table.

   * 'delete-row-done': Triggered before a row is deleted from a table.

The arguments supported by the probes are consistent for the
corresponding 'start' and 'done' probes in each case:

   * 'database': The database name.

   * 'table': The table name.

   * 'status': The status; 0 for success or 1 for failure.

Because the row-level probes are triggered for each individual row
access, these probes can be triggered many thousands of times each
second, which may have a detrimental effect on both the monitoring
script and MySQL. The DTrace environment should limit the triggering on
these probes to prevent the performance being adversely affected.
Either use the probes sparingly, or use counter or aggregation functions
to report on these probes and then provide a summary when the script
terminates or as part of a 'query-done' or 'query-exec-done' probes.

The following example script summarizes the duration of each row
operation within a larger query:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     dtrace:::BEGIN
     {
        printf("%-2s %-10s %-10s %9s %9s %-s \n",
               "St", "Who", "DB", "ConnID", "Dur ms", "Query");
     }

     mysql*:::query-start
     {
        self->query = copyinstr(arg0);
        self->who   = strjoin(copyinstr(arg3),strjoin("@",copyinstr(arg4)));
        self->db    = copyinstr(arg2);
        self->connid = arg1;
        self->querystart = timestamp;
        self->rowdur = 0;
     }

     mysql*:::query-done
     {
        this->elapsed = (timestamp - self->querystart) /1000000;
        printf("%2d %-10s %-10s %9d %9d %s\n",
               arg0, self->who, self->db,
               self->connid, this->elapsed, self->query);
     }

     mysql*:::query-done
     / self->rowdur /
     {
        printf("%34s %9d %s\n", "", (self->rowdur/1000000), "-> Row ops");
     }

     mysql*:::insert-row-start
     {
        self->rowstart = timestamp;
     }

     mysql*:::delete-row-start
     {
        self->rowstart = timestamp;
     }

     mysql*:::update-row-start
     {
        self->rowstart = timestamp;
     }

     mysql*:::insert-row-done
     {
        self->rowdur += (timestamp-self->rowstart);
     }

     mysql*:::delete-row-done
     {
        self->rowdur += (timestamp-self->rowstart);
     }

     mysql*:::update-row-done
     {
        self->rowdur += (timestamp-self->rowstart);
     }

Running the above script with a query that inserts data into a table,
you can monitor the exact time spent performing the raw row insertion:

     St Who        DB            ConnID    Dur ms Query
      0 @localhost test              13     20767 insert into t1(select * from t2)
                                             4827 -> Row ops

5.7.1.8 Read Row Probes
.......................

The read row probes are triggered at a storage engine level each time a
row read operation occurs.  These probes are specified within each
storage engine (as opposed to the '*row-start' probes which are in the
storage engine interface).  These probes can therefore be used to
monitor individual storage engine row-level operations and performance.
Because these probes are triggered around the storage engine row read
interface, they may be hit a significant number of times during a basic
query.

     read-row-start(database, table, scan_flag)
     read-row-done(status)

   * 'read-row-start': Triggered when a row is read by the storage
     engine from the specified 'database' and 'table'.  The 'scan_flag'
     is set to 1 (true) when the read is part of a table scan (that is,
     a sequential read), or 0 (false) when the read is of a specific
     record.

   * 'read-row-done': Triggered when a row read operation within a
     storage engine completes.  The 'status' returns 0 on success, or a
     positive value on failure.

5.7.1.9 Index Probes
....................

The index probes are triggered each time a row is read using one of the
indexes for the specified table.  The probe is triggered within the
corresponding storage engine for the table.

     index-read-row-start(database, table)
     index-read-row-done(status)

   * 'index-read-row-start': Triggered when a row is read by the storage
     engine from the specified 'database' and 'table'.

   * 'index-read-row-done': Triggered when an indexed row read operation
     within a storage engine completes.  The 'status' returns 0 on
     success, or a positive value on failure.

5.7.1.10 Lock Probes
....................

The lock probes are called whenever an external lock is requested by
MySQL for a table using the corresponding lock mechanism on the table as
defined by the table's engine type.  There are three different types of
lock, the read lock, write lock, and unlock operations.  Using the
probes you can determine the duration of the external locking routine
(that is, the time taken by the storage engine to implement the lock,
including any time waiting for another lock to become free) and the
total duration of the lock/unlock process.

     handler-rdlock-start(database, table)
     handler-rdlock-done(status)

     handler-wrlock-start(database, table)
     handler-wrlock-done(status)

     handler-unlock-start(database, table)
     handler-unlock-done(status)

   * 'handler-rdlock-start': Triggered when a read lock is requested on
     the specified 'database' and 'table'.

   * 'handler-wrlock-start': Triggered when a write lock is requested on
     the specified 'database' and 'table'.

   * 'handler-unlock-start': Triggered when an unlock request is made on
     the specified 'database' and 'table'.

   * 'handler-rdlock-done': Triggered when a read lock request
     completes.  The 'status' is 0 if the lock operation succeeded, or
     '>0' on failure.

   * 'handler-wrlock-done': Triggered when a write lock request
     completes.  The 'status' is 0 if the lock operation succeeded, or
     '>0' on failure.

   * 'handler-unlock-done': Triggered when an unlock request completes.
     The 'status' is 0 if the unlock operation succeeded, or '>0' on
     failure.

You can use arrays to monitor the locking and unlocking of individual
tables and then calculate the duration of the entire table lock using
the following script:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     mysql*:::handler-rdlock-start
     {
        self->rdlockstart = timestamp;
        this->lockref = strjoin(copyinstr(arg0),strjoin("@",copyinstr(arg1)));
        self->lockmap[this->lockref] = self->rdlockstart;
        printf("Start: Lock->Read   %s.%s\n",copyinstr(arg0),copyinstr(arg1));
     }

     mysql*:::handler-wrlock-start
     {
        self->wrlockstart = timestamp;
        this->lockref = strjoin(copyinstr(arg0),strjoin("@",copyinstr(arg1)));
        self->lockmap[this->lockref] = self->rdlockstart;
        printf("Start: Lock->Write  %s.%s\n",copyinstr(arg0),copyinstr(arg1));
     }

     mysql*:::handler-unlock-start
     {
        self->unlockstart = timestamp;
        this->lockref = strjoin(copyinstr(arg0),strjoin("@",copyinstr(arg1)));
        printf("Start: Lock->Unlock %s.%s (%d ms lock duration)\n",
               copyinstr(arg0),copyinstr(arg1),
               (timestamp - self->lockmap[this->lockref])/1000000);
     }

     mysql*:::handler-rdlock-done
     {
        printf("End:   Lock->Read   %d ms\n",
               (timestamp - self->rdlockstart)/1000000);
     }

     mysql*:::handler-wrlock-done
     {
        printf("End:   Lock->Write  %d ms\n",
               (timestamp - self->wrlockstart)/1000000);
     }

     mysql*:::handler-unlock-done
     {
        printf("End:   Lock->Unlock %d ms\n",
               (timestamp - self->unlockstart)/1000000);
     }

When executed, you should get information both about the duration of the
locking process itself, and of the locks on a specific table:

     Start: Lock->Read   test.t2
     End:   Lock->Read   0 ms
     Start: Lock->Unlock test.t2 (25743 ms lock duration)
     End:   Lock->Unlock 0 ms
     Start: Lock->Read   test.t2
     End:   Lock->Read   0 ms
     Start: Lock->Unlock test.t2 (1 ms lock duration)
     End:   Lock->Unlock 0 ms
     Start: Lock->Read   test.t2
     End:   Lock->Read   0 ms
     Start: Lock->Unlock test.t2 (1 ms lock duration)
     End:   Lock->Unlock 0 ms
     Start: Lock->Read   test.t2
     End:   Lock->Read   0 ms

5.7.1.11 Filesort Probes
........................

The filesort probes are triggered whenever a filesort operation is
applied to a table.  For more information on filesort and the conditions
under which it occurs, see order-by-optimization.

     filesort-start(database, table)
     filesort-done(status, rows)

   * 'filesort-start': Triggered when the filesort operation starts on a
     table.  The two arguments to the probe, 'database' and 'table',
     will identify the table being sorted.

   * 'filesort-done': Triggered when the filesort operation completes.
     Two arguments are supplied, the 'status' (0 for success, 1 for
     failure), and the number of rows sorted during the filesort
     process.

An example of this is in the following script, which tracks the duration
of the filesort process in addition to the duration of the main query:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     dtrace:::BEGIN
     {
        printf("%-2s %-10s %-10s %9s %18s %-s \n",
               "St", "Who", "DB", "ConnID", "Dur microsec", "Query");
     }

     mysql*:::query-start
     {
        self->query = copyinstr(arg0);
        self->who   = strjoin(copyinstr(arg3),strjoin("@",copyinstr(arg4)));
        self->db    = copyinstr(arg2);
        self->connid = arg1;
        self->querystart = timestamp;
        self->filesort = 0;
        self->fsdb = "";
        self->fstable = "";
     }

     mysql*:::filesort-start
     {
       self->filesort = timestamp;
       self->fsdb = copyinstr(arg0);
       self->fstable = copyinstr(arg1);
     }

     mysql*:::filesort-done
     {
        this->elapsed = (timestamp - self->filesort) /1000;
        printf("%2d %-10s %-10s %9d %18d Filesort on %s\n",
               arg0, self->who, self->fsdb,
               self->connid, this->elapsed, self->fstable);
     }

     mysql*:::query-done
     {
        this->elapsed = (timestamp - self->querystart) /1000;
        printf("%2d %-10s %-10s %9d %18d %s\n",
               arg0, self->who, self->db,
               self->connid, this->elapsed, self->query);
     }

Executing a query on a large table with an 'ORDER BY' clause that
triggers a filesort, and then creating an index on the table and then
repeating the same query, you can see the difference in execution speed:

     St Who        DB            ConnID       Dur microsec Query
      0 @localhost test              14           11335469 Filesort on t1
      0 @localhost test              14           11335787 select * from t1 order by i limit 100
      0 @localhost test              14          466734378 create index t1a on t1 (i)
      0 @localhost test              14              26472 select * from t1 order by i limit 100

5.7.1.12 Statement Probes
.........................

The individual statement probes are provided to give specific
information about different statement types.  For the start probes the
string of the query is provided as the only argument.  Depending on the
statement type, the information provided by the corresponding done probe
will differ.  For all done probes the status of the operation ('0' for
success, '>0' for failure) is provided.  For 'SELECT',
'INSERT', 'INSERT ... (SELECT FROM ...)',
'DELETE', and 'DELETE FROM t1,t2'.
operations the number of rows affected is returned.

For 'UPDATE' and 'UPDATE t1,t2 ...'.
statements the number of rows matched and the number of rows actually
changed is provided.  This is because the number of rows actually
matched by the corresponding 'WHERE' clause, and the number of rows
changed can differ.  MySQL does not update the value of a row if the
value already matches the new setting.

     select-start(query)
     select-done(status,rows)

     insert-start(query)
     insert-done(status,rows)

     insert-select-start(query)
     insert-select-done(status,rows)

     update-start(query)
     update-done(status,rowsmatched,rowschanged)

     multi-update-start(query)
     multi-update-done(status,rowsmatched,rowschanged)

     delete-start(query)
     delete-done(status,rows)

     multi-delete-start(query)
     multi-delete-done(status,rows)

   * 'select-start': Triggered before a 'SELECT'.
     statement.

   * 'select-done': Triggered at the end of a 'SELECT'.
     statement.

   * 'insert-start': Triggered before a 'INSERT'.
     statement.

   * 'insert-done': Triggered at the end of an 'INSERT'.
     statement.

   * 'insert-select-start': Triggered before an 'INSERT ... SELECT'
     statement.

   * 'insert-select-done': Triggered at the end of an 'INSERT ... SELECT'
     statement.

   * 'update-start': Triggered before an 'UPDATE'.
     statement.

   * 'update-done': Triggered at the end of an 'UPDATE'.
     statement.

   * 'multi-update-start': Triggered before an 'UPDATE'.
     statement involving multiple tables.

   * 'multi-update-done': Triggered at the end of an 'UPDATE'
     statement involving multiple tables.

   * 'delete-start': Triggered before a 'DELETE'.
     statement.

   * 'delete-done': Triggered at the end of a 'DELETE'.
     statement.

   * 'multi-delete-start': Triggered before a 'DELETE'.
     statement involving multiple tables.

   * 'multi-delete-done': Triggered at the end of a 'DELETE'
     statement involving multiple tables.

The arguments for the statement probes are:

   * 'query': The query string.

   * 'status': The status of the query.  '0' for success, and '>0' for
     failure.

   * 'rows': The number of rows affected by the statement.  This returns
     the number rows found for 'SELECT', the number of
     rows deleted for 'DELETE', and the number of rows
     successfully inserted for 'INSERT'.

   * 'rowsmatched': The number of rows matched by the 'WHERE' clause of
     an 'UPDATE' operation.

   * 'rowschanged': The number of rows actually changed during an
     'UPDATE' operation.

You use these probes to monitor the execution of these statement types
without having to monitor the user or client executing the statements.
A simple example of this is to track the execution times:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     dtrace:::BEGIN
     {
        printf("%-60s %-8s %-8s %-8s\n", "Query", "RowsU", "RowsM", "Dur (ms)");
     }

     mysql*:::update-start, mysql*:::insert-start,
     mysql*:::delete-start, mysql*:::multi-delete-start,
     mysql*:::multi-delete-done, mysql*:::select-start,
     mysql*:::insert-select-start, mysql*:::multi-update-start
     {
         self->query = copyinstr(arg0);
         self->querystart = timestamp;
     }

     mysql*:::insert-done, mysql*:::select-done,
     mysql*:::delete-done, mysql*:::multi-delete-done, mysql*:::insert-select-done
     / self->querystart /
     {
         this->elapsed = ((timestamp - self->querystart)/1000000);
         printf("%-60s %-8d %-8d %d\n",
                self->query,
                0,
                arg1,
                this->elapsed);
         self->querystart = 0;
     }

     mysql*:::update-done, mysql*:::multi-update-done
     / self->querystart /
     {
         this->elapsed = ((timestamp - self->querystart)/1000000);
         printf("%-60s %-8d %-8d %d\n",
                self->query,
                arg1,
                arg2,
                this->elapsed);
         self->querystart = 0;
     }

When executed you can see the basic execution times and rows matches:

     Query                                                        RowsU    RowsM    Dur (ms)
     select * from t2                                             0        275      0
     insert into t2 (select * from t2)                            0        275      9
     update t2 set i=5 where i > 75                               110      110      8
     update t2 set i=5 where i < 25                               254      134      12
     delete from t2 where i < 5                                   0        0        0

Another alternative is to use the aggregation functions in DTrace to
aggregate the execution time of individual statements together:

     #!/usr/sbin/dtrace -s

     #pragma D option quiet

     mysql*:::update-start, mysql*:::insert-start,
     mysql*:::delete-start, mysql*:::multi-delete-start,
     mysql*:::multi-delete-done, mysql*:::select-start,
     mysql*:::insert-select-start, mysql*:::multi-update-start
     {
         self->querystart = timestamp;
     }

     mysql*:::select-done
     {
             @statements["select"] = sum(((timestamp - self->querystart)/1000000));
     }

     mysql*:::insert-done, mysql*:::insert-select-done
     {
             @statements["insert"] = sum(((timestamp - self->querystart)/1000000));
     }

     mysql*:::update-done, mysql*:::multi-update-done
     {
             @statements["update"] = sum(((timestamp - self->querystart)/1000000));
     }

     mysql*:::delete-done, mysql*:::multi-delete-done
     {
             @statements["delete"] = sum(((timestamp - self->querystart)/1000000));
     }

     tick-30s
     {
             printa(@statements);
     }

The script just shown aggregates the times spent doing each operation,
which could be used to help benchmark a standard suite of tests.

      delete                                                            0
       update                                                            0
       insert                                                           23
       select                                                         2484

       delete                                                            0
       update                                                            0
       insert                                                           39
       select                                                        10744

       delete                                                            0
       update                                                           26
       insert                                                           56
       select                                                        10944

       delete                                                            0
       update                                                           26
       insert                                                         2287
       select                                                        15985

5.7.1.13 Network Probes
.......................

The network probes monitor the transfer of information from the MySQL
server and clients of all types over the network.  The probes are
defined as follows:

     net-read-start()
     net-read-done(status, bytes)
     net-write-start(bytes)
     net-write-done(status)

   * 'net-read-start': Triggered when a network read operation is
     started.

   * 'net-read-done': Triggered when the network read operation
     completes.  The 'status' is an 'integer' representing the return
     status for the operation, '0' for success and '1' for failure.  The
     'bytes' argument is an integer specifying the number of bytes read
     during the process.

   * 'net-start-bytes': Triggered when data is written to a network
     socket.  The single argument, 'bytes', specifies the number of
     bytes written to the network socket.

   * 'net-write-done': Triggered when the network write operation has
     completed.  The single argument, 'status', is an integer
     representing the return status for the operation, '0' for success
     and '1' for failure.

You can use the network probes to monitor the time spent reading from
and writing to network clients during execution.  The following D script
provides an example of this.  Both the cumulative time for the read or
write is calculated, and the number of bytes.  Note that the dynamic
variable size has been increased (using the 'dynvarsize' option) to cope
with the rapid firing of the individual probes for the network
reads/writes.

     #!/usr/sbin/dtrace -s

     #pragma D option quiet
     #pragma D option dynvarsize=4m

     dtrace:::BEGIN
     {
        printf("%-2s %-30s %-10s %9s %18s %-s \n",
               "St", "Who", "DB", "ConnID", "Dur microsec", "Query");
     }

     mysql*:::query-start
     {
        self->query = copyinstr(arg0);
        self->who   = strjoin(copyinstr(arg3),strjoin("@",copyinstr(arg4)));
        self->db    = copyinstr(arg2);
        self->connid = arg1;
        self->querystart = timestamp;
        self->netwrite = 0;
        self->netwritecum = 0;
        self->netwritebase = 0;
        self->netread = 0;
        self->netreadcum = 0;
        self->netreadbase = 0;
     }

     mysql*:::net-write-start
     {
        self->netwrite += arg0;
        self->netwritebase = timestamp;
     }

     mysql*:::net-write-done
     {
        self->netwritecum += (timestamp - self->netwritebase);
        self->netwritebase = 0;
     }

     mysql*:::net-read-start
     {
        self->netreadbase = timestamp;
     }

     mysql*:::net-read-done
     {
        self->netread += arg1;
        self->netreadcum += (timestamp - self->netreadbase);
        self->netreadbase = 0;
     }

     mysql*:::query-done
     {
        this->elapsed = (timestamp - self->querystart) /1000000;
        printf("%2d %-30s %-10s %9d %18d %s\n",
               arg0, self->who, self->db,
               self->connid, this->elapsed, self->query);
        printf("Net read: %d bytes (%d ms) write: %d bytes (%d ms)\n",
                    self->netread, (self->netreadcum/1000000),
                    self->netwrite, (self->netwritecum/1000000));
     }

When executing the above script on a machine with a remote client, you
can see that approximately a third of the time spent executing the query
is related to writing the query results back to the client.

     St Who                            DB            ConnID       Dur microsec Query
      0 root@::ffff:198.51.100.108      test              31               3495 select * from t1 limit 1000000
     Net read: 0 bytes (0 ms) write: 10000075 bytes (1220 ms)

5.7.1.14 Keycache Probes
........................

The keycache probes are triggered when using the index key cache used
with the MyISAM storage engine.  Probes exist to monitor when data is
read into the keycache, cached key data is written from the cache into a
cached file, or when accessing the keycache.

Keycache usage indicates when data is read or written from the index
files into the cache, and can be used to monitor how efficient the
memory allocated to the keycache is being used.  A high number of
keycache reads across a range of queries may indicate that the keycache
is too small for size of data being accessed.

     keycache-read-start(filepath, bytes, mem_used, mem_free)
     keycache-read-block(bytes)
     keycache-read-hit()
     keycache-read-miss()
     keycache-read-done(mem_used, mem_free)
     keycache-write-start(filepath, bytes, mem_used, mem_free)
     keycache-write-block(bytes)
     keycache-write-done(mem_used, mem_free)

When reading data from the index files into the keycache, the process
first initializes the read operation (indicated by
'keycache-read-start'), then loads blocks of data
('keycache-read-block'), and then the read block is either matches the
data being identified ('keycache-read-hit') or more data needs to be
read ('keycache-read-miss').  Once the read operation has completed,
reading stops with the 'keycache-read-done'.

Data will be read from the index file into the keycache only when the
specified key is not already within the keycache.

   * 'keycache-read-start': Triggered when the keycache read operation
     is started.  Data is read from the specified 'filepath', reading
     the specified number of 'bytes'.  The 'mem_used' and 'mem_avail'
     indicate memory currently used by the keycache and the amount of
     memory available within the keycache.

   * 'keycache-read-block': Triggered when the keycache reads a block of
     data, of the specified number of 'bytes', from the index file into
     the keycache.

   * 'keycache-read-hit': Triggered when the block of data read from the
     index file matches the key data requested.

   * 'keycache-read-miss': Triggered when the block of data read from
     the index file does not match the key data needed.

   * 'keycache-read-done': Triggered when the keycache read operation
     has completed.  The 'mem_used' and 'mem_avail' indicate memory
     currently used by the keycache and the amount of memory available
     within the keycache.

Keycache writes occur when the index information is updated during an
'INSERT', 'UPDATE', or 'DELETE' operation, and the cached key
information is flushed back to the index file.

   * 'keycache-write-start': Triggered when the keycache write operation
     is started.  Data is written to the specified 'filepath', reading
     the specified number of 'bytes'.  The 'mem_used' and 'mem_avail'
     indicate memory currently used by the keycache and the amount of
     memory available within the keycache.

   * 'keycache-write-block': Triggered when the keycache writes a block
     of data, of the specified number of 'bytes', to the index file from
     the keycache.

   * 'keycache-write-done': Triggered when the keycache write operation
     has completed.  The 'mem_used' and 'mem_avail' indicate memory
     currently used by the keycache and the amount of memory available
     within the keycache.

6 Security
**********

When thinking about security within a MySQL installation, you should
consider a wide range of possible topics and how they affect the
security of your MySQL server and related applications:

   * General factors that affect security.  These include choosing good
     passwords, not granting unnecessary privileges to users, ensuring
     application security by preventing SQL injections and data
     corruption, and others.  See general-security-issues.

   * Security of the installation itself.  The data files, log files,
     and the all the application files of your installation should be
     protected to ensure that they are not readable or writable by
     unauthorized parties.  For more information, see
     postinstallation.

   * Access control and security within the database system itself,
     including the users and databases granted with access to the
     databases, views and stored programs in use within the database.
     For more information, see privilege-system, and
     user-account-management.

   * The features offered by security-related plugins.  See
     security-plugins.

   * Network security of MySQL and your system.  The security is related
     to the grants for individual users, but you may also wish to
     restrict MySQL so that it is available only locally on the MySQL
     server host, or to a limited set of other hosts.

   * Ensure that you have adequate and appropriate backups of your
     database files, configuration and log files.  Also be sure that you
     have a recovery solution in place and test that you are able to
     successfully recover the information from your backups.  See
     backup-and-recovery.

6.1 General Security Issues
===========================

This section describes general security issues to be aware of and what
you can do to make your MySQL installation more secure against attack or
misuse.  For information specifically about the access control system
that MySQL uses for setting up user accounts and checking database
access, see postinstallation.

For answers to some questions that are often asked about MySQL Server
security issues, see faqs-security.

6.1.1 Security Guidelines
-------------------------

Anyone using MySQL on a computer connected to the Internet should read
this section to avoid the most common security mistakes.

In discussing security, it is necessary to consider fully protecting the
entire server host (not just the MySQL server) against all types of
applicable attacks: eavesdropping, altering, playback, and denial of
service.  We do not cover all aspects of availability and fault
tolerance here.

MySQL uses security based on Access Control Lists (ACLs) for all
connections, queries, and other operations that users can attempt to
perform.  There is also support for SSL-encrypted connections between
MySQL clients and servers.  Many of the concepts discussed here are not
specific to MySQL at all; the same general ideas apply to almost all
applications.

When running MySQL, follow these guidelines:

   * *Do not ever give anyone (except MySQL 'root' accounts) access to
     the 'user' table in the 'mysql' database!*  This is critical.

   * Learn how the MySQL access privilege system works (see
     privilege-system).  Use the 'GRANT' and
     'REVOKE' statements to control access to MySQL. Do not
     grant more privileges than necessary.  Never grant privileges to
     all hosts.

     Checklist:

        * Try 'mysql -u root'.  If you are able to connect successfully
          to the server without being asked for a password, anyone can
          connect to your MySQL server as the MySQL 'root' user with
          full privileges!  Review the MySQL installation instructions,
          paying particular attention to the information about setting a
          'root' password.  See default-privileges.

        * Use the 'SHOW GRANTS' statement to check
          which accounts have access to what.  Then use the
          'REVOKE' statement to remove those privileges that
          are not necessary.

   * Do not store cleartext passwords in your database.  If your
     computer becomes compromised, the intruder can take the full list
     of passwords and use them.  Instead, use 'SHA2()' or some other
     one-way hashing function and store the hash value.

     To prevent password recovery using rainbow tables, do not use these
     functions on a plain password; instead, choose some string to be
     used as a salt, and use hash(hash(password)+salt) values.

   * Do not choose passwords from dictionaries.  Special programs exist
     to break passwords.  Even passwords like 'xfish98' are very bad.
     Much better is 'duag98' which contains the same word 'fish' but
     typed one key to the left on a standard QWERTY keyboard.  Another
     method is to use a password that is taken from the first characters
     of each word in a sentence (for example, 'Four score and seven
     years ago' results in a password of 'Fsasya').  The password is
     easy to remember and type, but difficult to guess for someone who
     does not know the sentence.  In this case, you can additionally
     substitute digits for the number words to obtain the phrase '4
     score and 7 years ago', yielding the password '4sa7ya' which is
     even more difficult to guess.

   * Invest in a firewall.  This protects you from at least 50% of all
     types of exploits in any software.  Put MySQL behind the firewall
     or in a demilitarized zone (DMZ).

     Checklist:

        * Try to scan your ports from the Internet using a tool such as
          'nmap'.  MySQL uses port 3306 by default.  This port should
          not be accessible from untrusted hosts.  As a simple way to
          check whether your MySQL port is open, try the following
          command from some remote machine, where SERVER_HOST is the
          host name or IP address of the host on which your MySQL server
          runs:

               shell> telnet SERVER_HOST 3306

          If 'telnet' hangs or the connection is refused, the port is
          blocked, which is how you want it to be.  If you get a
          connection and some garbage characters, the port is open, and
          should be closed on your firewall or router, unless you really
          have a good reason to keep it open.

   * Applications that access MySQL should not trust any data entered by
     users, and should be written using proper defensive programming
     techniques.  See secure-client-programming.

   * Do not transmit plain (unencrypted) data over the Internet.  This
     information is accessible to everyone who has the time and ability
     to intercept it and use it for their own purposes.  Instead, use an
     encrypted protocol such as SSL or SSH. MySQL supports internal SSL
     connections.  Another technique is to use SSH port-forwarding to
     create an encrypted (and compressed) tunnel for the communication.

   * Learn to use the 'tcpdump' and 'strings' utilities.  In most cases,
     you can check whether MySQL data streams are unencrypted by issuing
     a command like the following:

          shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings

     This works under Linux and should work with small modifications
     under other systems.

     *Warning*:

     If you do not see cleartext data, this does not always mean that
     the information actually is encrypted.  If you need high security,
     consult with a security expert.

6.1.2 Keeping Passwords Secure
------------------------------

Passwords occur in several contexts within MySQL. The following sections
provide guidelines that enable end users and administrators to keep
these passwords secure and avoid exposing them.  There is also a
discussion of how MySQL uses password hashing internally and of a plugin
that you can use to enforce stricter passwords.

6.1.2.1 End-User Guidelines for Password Security
.................................................

MySQL users should use the following guidelines to keep passwords
secure.

When you run a client program to connect to the MySQL server, it is
inadvisable to specify your password in a way that exposes it to
discovery by other users.  The methods you can use to specify your
password when you run client programs are listed here, along with an
assessment of the risks of each method.  In short, the safest methods
are to have the client program prompt for the password or to specify the
password in a properly protected option file.

   * Use the 'mysql_config_editor' utility,
     which enables you to store authentication credentials in an
     encrypted login path file named '.mylogin.cnf'.  The file can be
     read later by MySQL client programs to obtain authentication
     credentials for connecting to MySQL Server.  See
     mysql-config-editor.

   *
     Use a '-pYOUR_PASS' or '--password=YOUR_PASS' option on the command
     line.  For example:

          shell> mysql -u francis -pfrank DB_NAME

     *Warning*:

     This is convenient _but insecure_.  On some systems, your password
     becomes visible to system status programs such as 'ps' that may be
     invoked by other users to display command lines.  MySQL clients
     typically overwrite the command-line password argument with zeros
     during their initialization sequence.  However, there is still a
     brief interval during which the value is visible.  Also, on some
     systems this overwriting strategy is ineffective and the password
     remains visible to 'ps'.  (SystemV Unix systems and perhaps others
     are subject to this problem.)

     If your operating environment is set up to display your current
     command in the title bar of your terminal window, the password
     remains visible as long as the command is running, even if the
     command has scrolled out of view in the window content area.

   * Use the '-p' or '--password' option on the command line with no
     password value specified.  In this case, the client program
     solicits the password interactively:

          shell> mysql -u francis -p DB_NAME
          Enter password: ********

     The '*' characters indicate where you enter your password.  The
     password is not displayed as you enter it.

     It is more secure to enter your password this way than to specify
     it on the command line because it is not visible to other users.
     However, this method of entering a password is suitable only for
     programs that you run interactively.  If you want to invoke a
     client from a script that runs noninteractively, there is no
     opportunity to enter the password from the keyboard.  On some
     systems, you may even find that the first line of your script is
     read and interpreted (incorrectly) as your password.

   *
     Store your password in an option file.  For example, on Unix, you
     can list your password in the '[client]' section of the '.my.cnf'
     file in your home directory:

          [client]
          password=your_pass

     To keep the password safe, the file should not be accessible to
     anyone but yourself.  To ensure this, set the file access mode to
     '400' or '600'.  For example:

          shell> chmod 600 .my.cnf

     To name from the command line a specific option file containing the
     password, use the '--defaults-file=FILE_NAME' option, where
     'file_name' is the full path name to the file.  For example:

          shell> mysql --defaults-file=/home/francis/mysql-opts

     See option-files, discusses option files in more detail.

   * Store your password in the 'MYSQL_PWD' environment variable.  See
     environment-variables.

     This method of specifying your MySQL password must be considered
     _extremely insecure_ and should not be used.  Some versions of 'ps'
     include an option to display the environment of running processes.
     On some systems, if you set 'MYSQL_PWD', your password is exposed
     to any other user who runs 'ps'.  Even on systems without such a
     version of 'ps', it is unwise to assume that there are no other
     methods by which users can examine process environments.

On Unix, the 'mysql' client writes a record of executed
statements to a history file (see mysql-logging).  By default,
this file is named '.mysql_history' and is created in your home
directory.  Passwords can be written as plain text in SQL statements
such as 'CREATE USER' and 'ALTER USER',
so if you use these statements, they are logged in the
history file.  To keep this file safe, use a restrictive access mode,
the same way as described earlier for the '.my.cnf' file.

If your command interpreter is configured to maintain a history, any
file in which the commands are saved will contain MySQL passwords
entered on the command line.  For example, 'bash' uses
'~/.bash_history'.  Any such file should have a restrictive access mode.

6.1.2.2 Administrator Guidelines for Password Security
......................................................

Database administrators should use the following guidelines to keep
passwords secure.

MySQL stores passwords for user accounts in the 'mysql.user' table.
Access to this table should never be granted to any nonadministrative
accounts.

Account passwords can be expired so that users must reset them.  See
password-management, and expired-password-handling.

The 'validate_password' plugin can be used to enforce a policy on
acceptable password.  See validate-password.

A user who has access to modify the plugin directory (the value of the
'plugin_dir' system variable) or the 'my.cnf' file that specifies the
plugin directory location can replace plugins and modify the
capabilities provided by plugins, including authentication plugins.

Files such as log files to which passwords might be written should be
protected.  See password-logging.

6.1.2.3 Passwords and Logging
.............................

Passwords can be written as plain text in SQL statements such as
'CREATE USER', 'GRANT', 'SET PASSWORD',
and statements that invoke the 'PASSWORD()' function.  If
such statements are logged by the MySQL server as written, passwords in
them become visible to anyone with access to the logs.

Statement logging avoids writing passwords in cleartext for the
following statements:

     CREATE USER ... IDENTIFIED BY ...
     ALTER USER ... IDENTIFIED BY ...
     GRANT ... IDENTIFIED BY ...
     SET PASSWORD ...
     SLAVE START ... PASSWORD = ...
     CREATE SERVER ... OPTIONS(... PASSWORD ...)
     ALTER SERVER ... OPTIONS(... PASSWORD ...)

Passwords in those statements are rewritten to not appear literally in
statement text written to the general query log, slow query log, and
binary log.  Rewriting does not apply to other statements.  In
particular, see 'INSERT' or 'UPDATE'.
statements for the 'mysql.user' table that refer to literal passwords
are logged as is, so you should avoid such statements.  (Direct
modification of grant tables is discouraged, anyway.)

For the general query log, password rewriting can be suppressed by
starting the server with the '--log-raw' option.  For security reasons,
this option is not recommended for production use.  For diagnostic
purposes, it may be useful to see the exact text of statements as
received by the server.

Contents of the audit log file produced by the audit log plugin are not
encrypted.  For security reasons, this file should be written to a
directory accessible only to the MySQL server and users with a
legitimate reason to view the log.  See audit-log-security.

Statements received by the server may be rewritten if a query rewrite
plugin is installed (see query-rewrite-plugin-type).  In this
case, the '--log-raw' option affects statement logging as follows:

   * Without '--log-raw', the server logs the statement returned by the
     query rewrite plugin.  This may differ from the statement as
     received.

   * With '--log-raw', the server logs the original statement as
     received.

An implication of password rewriting is that statements that cannot be
parsed (due, for example, to syntax errors) are not written to the
general query log because they cannot be known to be password free.  Use
cases that require logging of all statements including those with errors
should use the '--log-raw' option, bearing in mind that this also
bypasses password rewriting.

Password rewriting occurs only when plain text passwords are expected.
For statements with syntax that expect a password hash value, no
rewriting occurs.  If a plain text password is supplied erroneously for
such syntax, the password is logged as given, without rewriting.  For
example, the following statement is logged as shown because a password
hash value is expected:

     CREATE USER 'user1'@'localhost' IDENTIFIED BY PASSWORD 'not-so-secret';

To guard log files against unwarranted exposure, locate them in a
directory that restricts access to the server and the database
administrator.  If the server logs to tables in the 'mysql' database,
grant access to those tables only to the database administrator.

Replication slaves store the password for the replication master in the
master info repository, which can be either a file or a table (see
slave-logs).  Ensure that the repository can be accessed only by the
database administrator.  An alternative to storing the password in a
file is to use the 'START SLAVE' statement to
specify credentials for connecting to the master.

Use a restricted access mode to protect database backups that include
log tables or log files containing passwords.

6.1.2.4 Password Hashing in MySQL
.................................

*Note*:

The information in this section applies fully only before MySQL 5.7.5,
and only for accounts that use the 'mysql_native_password' or
'mysql_old_password' authentication plugins.  Support for pre-4.1
password hashes was removed in MySQL 5.7.5.  This includes removal of
the 'mysql_old_password' authentication plugin and the 'OLD_PASSWORD()'
function.  Also, 'secure_auth' cannot be disabled, and 'old_passwords'
cannot be set to 1.

As of MySQL 5.7.5, only the information about 4.1 password hashes and
the 'mysql_native_password' authentication plugin remains relevant.

MySQL lists user accounts in the 'user' table of the 'mysql' database.
Each MySQL account can be assigned a password, although the 'user' table
does not store the cleartext version of the password, but a hash value
computed from it.

MySQL uses passwords in two phases of client/server communication:

   * When a client attempts to connect to the server, there is an
     initial authentication step in which the client must present a
     password that has a hash value matching the hash value stored in
     the 'user' table for the account the client wants to use.

   * After the client connects, it can (if it has sufficient privileges)
     set or change the password hash for accounts listed in the 'user'
     table.  The client can do this by using the 'PASSWORD()' function
     to generate a password hash, or by using a password-generating
     statement (see 'CREATE USER', 'GRANT',
     or 'SET PASSWORD').

In other words, the server _checks_ hash values during authentication
when a client first attempts to connect.  The server _generates_ hash
values if a connected client invokes the 'PASSWORD()' function or uses a
password-generating statement to set or change a password.

Password hashing methods in MySQL have the history described following.
These changes are illustrated by changes in the result from the
'PASSWORD()' function that computes password hash values and in the
structure of the 'user' table where passwords are stored.

*The Original (Pre-4.1) Hashing Method*

The original hashing method produced a 16-byte string.  Such hashes look
like this:

     mysql> SELECT PASSWORD('mypass');
     +--------------------+
     | PASSWORD('mypass') |
     +--------------------+
     | 6f8c114b58f2ce9e   |
     +--------------------+

To store account passwords, the 'Password' column of the 'user' table
was at this point 16 bytes long.

*The 4.1 Hashing Method*

MySQL 4.1 introduced password hashing that provided better security and
reduced the risk of passwords being intercepted.  There were several
aspects to this change:

   * Different format of password values produced by the 'PASSWORD()'
     function

   * Widening of the 'Password' column

   * Control over the default hashing method

   * Control over the permitted hashing methods for clients attempting
     to connect to the server

The changes in MySQL 4.1 took place in two stages:

   * MySQL 4.1.0 used a preliminary version of the 4.1 hashing method.
     This method was short lived and the following discussion says
     nothing more about it.

   * In MySQL 4.1.1, the hashing method was modified to produce a longer
     41-byte hash value:

          mysql> SELECT PASSWORD('mypass');
          +-------------------------------------------+
          | PASSWORD('mypass')                        |
          +-------------------------------------------+
          | *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 |
          +-------------------------------------------+

     The longer password hash format has better cryptographic
     properties, and client authentication based on long hashes is more
     secure than that based on the older short hashes.

     To accommodate longer password hashes, the 'Password' column in the
     'user' table was changed at this point to be 41 bytes, its current
     length.

     A widened 'Password' column can store password hashes in both the
     pre-4.1 and 4.1 formats.  The format of any given hash value can be
     determined two ways:

        * The length: 4.1 and pre-4.1 hashes are 41 and 16 bytes,
          respectively.

        * Password hashes in the 4.1 format always begin with a '*'
          character, whereas passwords in the pre-4.1 format never do.

     To permit explicit generation of pre-4.1 password hashes, two
     additional changes were made:

        * The 'OLD_PASSWORD()' function was added, which returns hash
          values in the 16-byte format.

        * For compatibility purposes, the 'old_passwords' system
          variable was added, to enable DBAs and applications control
          over the hashing method.  The default 'old_passwords' value of
          0 causes hashing to use the 4.1 method (41-byte hash values),
          but setting 'old_passwords=1' causes hashing to use the
          pre-4.1 method.  In this case, 'PASSWORD()' produces 16-byte
          values and is equivalent to 'OLD_PASSWORD()'

     To permit DBAs control over how clients are permitted to connect,
     the 'secure_auth' system variable was added.  Starting the server
     with this variable disabled or enabled permits or prohibits clients
     to connect using the older pre-4.1 password hashing method.  Before
     MySQL 5.6.5, 'secure_auth' is disabled by default.  As of 5.6.5,
     'secure_auth' is enabled by default to promote a more secure
     default configuration DBAs can disable it at their discretion, but
     this is not recommended, and pre-4.1 password hashes are deprecated
     and should be avoided.  (For account upgrade instructions, see
     account-upgrades.)

     In addition, the 'mysql' client supports a
     '--secure-auth' option that is analogous to 'secure_auth', but from
     the client side.  It can be used to prevent connections to less
     secure accounts that use pre-4.1 password hashing.  This option is
     disabled by default before MySQL 5.6.7, enabled thereafter.

*Compatibility Issues Related to Hashing Methods*

The widening of the 'Password' column in MySQL 4.1 from 16 bytes to 41
bytes affects installation or upgrade operations as follows:

   * If you perform a new installation of MySQL, the 'Password' column
     is made 41 bytes long automatically.

   * Upgrades from MySQL 4.1 or later to current versions of MySQL
     should not give rise to any issues in regard to the 'Password'
     column because both versions use the same column length and
     password hashing method.

   * For upgrades from a pre-4.1 release to 4.1 or later, you must
     upgrade the system tables after upgrading.  (See
     mysql-upgrade.)

The 4.1 hashing method is understood only by MySQL 4.1 (and higher)
servers and clients, which can result in some compatibility problems.  A
4.1 or higher client can connect to a pre-4.1 server, because the client
understands both the pre-4.1 and 4.1 password hashing methods.  However,
a pre-4.1 client that attempts to connect to a 4.1 or higher server may
run into difficulties.  For example, a 4.0 'mysql' client
may fail with the following error message:

     shell> mysql -h localhost -u root
     Client does not support authentication protocol requested
     by server; consider upgrading MySQL client

This phenomenon also occurs for attempts to use the older PHP 'mysql'
extension after upgrading to MySQL 4.1 or higher.  (See Common Problems
with MySQL and PHP
(http://dev.mysql.com/doc/apis-php/en/apis-php-problems.html).)

The following discussion describes the differences between the pre-4.1
and 4.1 hashing methods, and what you should do if you upgrade your
server but need to maintain backward compatibility with pre-4.1 clients.
(However, permitting connections by old clients is not recommended and
should be avoided if possible.)  This information is of particular
importance to PHP programmers migrating MySQL databases from versions
older than 4.1 to 4.1 or higher.

The differences between short and long password hashes are relevant both
for how the server uses passwords during authentication and for how it
generates password hashes for connected clients that perform
password-changing operations.

The way in which the server uses password hashes during authentication
is affected by the width of the 'Password' column:

   * If the column is short, only short-hash authentication is used.

   * If the column is long, it can hold either short or long hashes, and
     the server can use either format:

        * Pre-4.1 clients can connect, but because they know only about
          the pre-4.1 hashing method, they can authenticate only using
          accounts that have short hashes.

        * 4.1 and later clients can authenticate using accounts that
          have short or long hashes.

Even for short-hash accounts, the authentication process is actually a
bit more secure for 4.1 and later clients than for older clients.  In
terms of security, the gradient from least to most secure is:

   * Pre-4.1 client authenticating with short password hash

   * 4.1 or later client authenticating with short password hash

   * 4.1 or later client authenticating with long password hash

The way in which the server generates password hashes for connected
clients is affected by the width of the 'Password' column and by the
'old_passwords' system variable.  A 4.1 or later server generates long
hashes only if certain conditions are met: The 'Password' column must be
wide enough to hold long values and 'old_passwords' must not be set to
1.

Those conditions apply as follows:

   * The 'Password' column must be wide enough to hold long hashes (41
     bytes).  If the column has not been updated and still has the
     pre-4.1 width of 16 bytes, the server notices that long hashes
     cannot fit into it and generates only short hashes when a client
     performs password-changing operations using the 'PASSWORD()'
     function or a password-generating statement.  This is the behavior
     that occurs if you have upgraded from a version of MySQL older than
     4.1 to 4.1 or later but have not yet run the 'mysql_upgrade'
     program to widen the 'Password' column.

   * If the 'Password' column is wide, it can store either short or long
     password hashes.  In this case, the 'PASSWORD()' function and
     password-generating statements generate long hashes unless the
     server was started with the 'old_passwords' system variable set to
     1 to force the server to generate short password hashes instead.

The purpose of the 'old_passwords' system variable is to permit backward
compatibility with pre-4.1 clients under circumstances where the server
would otherwise generate long password hashes.  The option does not
affect authentication (4.1 and later clients can still use accounts that
have long password hashes), but it does prevent creation of a long
password hash in the 'user' table as the result of a password-changing
operation.  Were that permitted to occur, the account could no longer be
used by pre-4.1 clients.  With 'old_passwords' disabled, the following
undesirable scenario is possible:

   * An old pre-4.1 client connects to an account that has a short
     password hash.

   * The client changes its own password.  With 'old_passwords'
     disabled, this results in the account having a long password hash.

   * The next time the old client attempts to connect to the account, it
     cannot, because the account has a long password hash that requires
     the 4.1 hashing method during authentication.  (Once an account has
     a long password hash in the user table, only 4.1 and later clients
     can authenticate for it because pre-4.1 clients do not understand
     long hashes.)

This scenario illustrates that, if you must support older pre-4.1
clients, it is problematic to run a 4.1 or higher server without
'old_passwords' set to 1.  By running the server with 'old_passwords=1',
password-changing operations do not generate long password hashes and
thus do not cause accounts to become inaccessible to older clients.
(Those clients cannot inadvertently lock themselves out by changing
their password and ending up with a long password hash.)

The downside of 'old_passwords=1' is that any passwords created or
changed use short hashes, even for 4.1 or later clients.  Thus, you lose
the additional security provided by long password hashes.  To create an
account that has a long hash (for example, for use by 4.1 clients) or to
change an existing account to use a long password hash, an administrator
can set the session value of 'old_passwords' set to 0 while leaving the
global value set to 1:

     mysql> SET @@session.old_passwords = 0;
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @@session.old_passwords, @@global.old_passwords;
     +-------------------------+------------------------+
     | @@session.old_passwords | @@global.old_passwords |
     +-------------------------+------------------------+
     |                       0 |                      1 |
     +-------------------------+------------------------+
     1 row in set (0.00 sec)

     mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'newpass';
     Query OK, 0 rows affected (0.03 sec)

     mysql> SET PASSWORD FOR 'existinguser'@'localhost' = PASSWORD('existingpass');
     Query OK, 0 rows affected (0.00 sec)

The following scenarios are possible in MySQL 4.1 or later.  The factors
are whether the 'Password' column is short or long, and, if long,
whether the server is started with 'old_passwords' enabled or disabled.

*Scenario 1:* Short 'Password' column in user table:

   * Only short hashes can be stored in the 'Password' column.

   * The server uses only short hashes during client authentication.

   * For connected clients, password hash-generating operations
     involving the 'PASSWORD()' function or password-generating
     statements use short hashes exclusively.  Any change to an
     account's password results in that account having a short password
     hash.

   * The value of 'old_passwords' is irrelevant because with a short
     'Password' column, the server generates only short password hashes
     anyway.

This scenario occurs when a pre-4.1 MySQL installation has been upgraded
to 4.1 or later but 'mysql_upgrade' has not been
run to upgrade the system tables in the 'mysql' database.  (This is not
a recommended configuration because it does not permit use of more
secure 4.1 password hashing.)

*Scenario 2:* Long 'Password' column; server started with
'old_passwords=1':

   * Short or long hashes can be stored in the 'Password' column.

   * 4.1 and later clients can authenticate for accounts that have short
     or long hashes.

   * Pre-4.1 clients can authenticate only for accounts that have short
     hashes.

   * For connected clients, password hash-generating operations
     involving the 'PASSWORD()' function or password-generating
     statements use short hashes exclusively.  Any change to an
     account's password results in that account having a short password
     hash.

In this scenario, newly created accounts have short password hashes
because 'old_passwords=1' prevents generation of long hashes.  Also, if
you create an account with a long hash before setting 'old_passwords' to
1, changing the account's password while 'old_passwords=1' results in
the account being given a short password, causing it to lose the
security benefits of a longer hash.

To create a new account that has a long password hash, or to change the
password of any existing account to use a long hash, first set the
session value of 'old_passwords' set to 0 while leaving the global value
set to 1, as described previously.

In this scenario, the server has an up to date 'Password' column, but is
running with the default password hashing method set to generate pre-4.1
hash values.  This is not a recommended configuration but may be useful
during a transitional period in which pre-4.1 clients and passwords are
upgraded to 4.1 or later.  When that has been done, it is preferable to
run the server with 'old_passwords=0' and 'secure_auth=1'.

*Scenario 3:* Long 'Password' column; server started with
'old_passwords=0':

   * Short or long hashes can be stored in the 'Password' column.

   * 4.1 and later clients can authenticate using accounts that have
     short or long hashes.

   * Pre-4.1 clients can authenticate only using accounts that have
     short hashes.

   * For connected clients, password hash-generating operations
     involving the 'PASSWORD()' function or password-generating
     statements use long hashes exclusively.  A change to an account's
     password results in that account having a long password hash.

As indicated earlier, a danger in this scenario is that it is possible
for accounts that have a short password hash to become inaccessible to
pre-4.1 clients.  A change to such an account's password made using the
'PASSWORD()' function or a password-generating statement results in the
account being given a long password hash.  From that point on, no
pre-4.1 client can connect to the server using that account.  The client
must upgrade to 4.1 or later.

If this is a problem, you can change a password in a special way.  For
example, normally you use 'SET PASSWORD' as follows
to change an account password:

     SET PASSWORD FOR 'SOME_USER'@'SOME_HOST' = PASSWORD('PASSWORD');

To change the password but create a short hash, use the 'OLD_PASSWORD()'
function instead:

     SET PASSWORD FOR 'SOME_USER'@'SOME_HOST' = OLD_PASSWORD('PASSWORD');

'OLD_PASSWORD()' is useful for situations in which you explicitly want
to generate a short hash.

The disadvantages for each of the preceding scenarios may be summarized
as follows:

In scenario 1, you cannot take advantage of longer hashes that provide
more secure authentication.

In scenario 2, 'old_passwords=1' prevents accounts with short hashes
from becoming inaccessible, but password-changing operations cause
accounts with long hashes to revert to short hashes unless you take care
to change the session value of 'old_passwords' to 0 first.

In scenario 3, accounts with short hashes become inaccessible to pre-4.1
clients if you change their passwords without explicitly using
'OLD_PASSWORD()'.

The best way to avoid compatibility problems related to short password
hashes is to not use them:

   * Upgrade all client programs to MySQL 4.1 or later.

   * Run the server with 'old_passwords=0'.

   * Reset the password for any account with a short password hash to
     use a long password hash.

   * For additional security, run the server with 'secure_auth=1'.

6.1.3 Making MySQL Secure Against Attackers
-------------------------------------------

When you connect to a MySQL server, you should use a password.  The
password is not transmitted in clear text over the connection.  Password
handling during the client connection sequence was upgraded in MySQL
4.1.1 to be very secure.  If you are still using pre-4.1.1-style
passwords, the encryption algorithm is not as strong as the newer
algorithm.  With some effort, a clever attacker who can sniff the
traffic between the client and the server can crack the password.  (See
password-hashing, for a discussion of the different password
handling methods.)

All other information is transferred as text, and can be read by anyone
who is able to watch the connection.  If the connection between the
client and the server goes through an untrusted network, and you are
concerned about this, you can use the compressed protocol to make
traffic much more difficult to decipher.  You can also use MySQL's
internal SSL support to make the connection even more secure.  See
encrypted-connections.  Alternatively, use SSH to get an encrypted
TCP/IP connection between a MySQL server and a MySQL client.  You can
find an Open Source SSH client at <http://www.openssh.org/>, and a
comparison of both Open Source and Commercial SSH clients at
<http://en.wikipedia.org/wiki/Comparison_of_SSH_clients>.

To make a MySQL system secure, you should strongly consider the
following suggestions:

   * Require all MySQL accounts to have a password.  A client program
     does not necessarily know the identity of the person running it.
     It is common for client/server applications that the user can
     specify any user name to the client program.  For example, anyone
     can use the 'mysql' program to connect as any other
     person simply by invoking it as 'mysql -u OTHER_USER DB_NAME' if
     OTHER_USER has no password.  If all accounts have a password,
     connecting using another user's account becomes much more
     difficult.

     For a discussion of methods for setting passwords, see
     assigning-passwords.

   * Make sure that the only Unix user account with read or write
     privileges in the database directories is the account that is used
     for running 'mysqld'.

   * Never run the MySQL server as the Unix 'root' user.  This is
     extremely dangerous, because any user with the 'FILE' privilege is
     able to cause the server to create files as 'root' (for example,
     '~root/.bashrc').  To prevent this, see 'mysqld' refuses
     to run as 'root' unless that is specified explicitly using the
     '--user=root' option.

     'mysqld' can (and should) be run as an ordinary,
     unprivileged user instead.  You can create a separate Unix account
     named 'mysql' to make everything even more secure.  Use this
     account only for administering MySQL. To start 'mysqld'
     as a different Unix user, add a 'user' option that
     specifies the user name in the '[mysqld]' group of the 'my.cnf'
     option file where you specify server options.  For example:

          [mysqld]
          user=mysql

     This causes the server to start as the designated user whether you
     start it manually or by using 'mysqld_safe' or
     'mysql.server'.  For more details, see
     changing-mysql-user.

     Running 'mysqld' as a Unix user other than 'root'
     does not mean that you need to change the 'root' user name in the
     'user' table.  _User names for MySQL accounts have nothing to do
     with user names for Unix accounts_.

   * Do not grant the 'FILE' privilege to nonadministrative users.  Any
     user that has this privilege can write a file anywhere in the file
     system with the privileges of the 'mysqld' daemon.
     This includes the server's data directory containing the files that
     implement the privilege tables.  To make 'FILE'-privilege
     operations a bit safer, files generated with 'SELECT ... INTO OUTFILE'
     do not overwrite existing files and are
     writable by everyone.

     The 'FILE' privilege may also be used to read any file that is
     world-readable or accessible to the Unix user that the server runs
     as.  With this privilege, you can read any file into a database
     table.  This could be abused, for example, by using 'LOAD DATA'
     to load '/etc/passwd' into a table, which then
     can be displayed with 'SELECT'.

     To limit the location in which files can be read and written, set
     the 'secure_file_priv' system to a specific directory.  See
     server-system-variables.

   * Do not grant the 'PROCESS' or 'SUPER' privilege to
     nonadministrative users.  The output of 'mysqladmin processlist'
     and 'SHOW PROCESSLIST'
     shows the text of any statements currently being
     executed, so any user who is permitted to see the server process
     list might be able to see statements issued by other users such as
     'UPDATE user SET password=PASSWORD('not_secure')'.

     'mysqld' reserves an extra connection for users who
     have the 'SUPER' privilege, so that a MySQL 'root' user can log in
     and check server activity even if all normal connections are in
     use.

     The 'SUPER' privilege can be used to terminate client connections,
     change server operation by changing the value of system variables,
     and control replication servers.

   * Do not permit the use of symlinks to tables.  (This capability can
     be disabled with the '--skip-symbolic-links' option.)  This is
     especially important if you run 'mysqld' as 'root',
     because anyone that has write access to the server's data directory
     then could delete any file in the system!  See
     symbolic-links-to-tables.

   * Stored programs and views should be written using the security
     guidelines discussed in stored-programs-security.

   * If you do not trust your DNS, you should use IP addresses rather
     than host names in the grant tables.  In any case, you should be
     very careful about creating grant table entries using host name
     values that contain wildcards.

   * If you want to restrict the number of connections permitted to a
     single account, you can do so by setting the 'max_user_connections'
     variable in 'mysqld'.  The 'CREATE USER'
     and 'ALTER USER' statements also
     support resource control options for limiting the extent of server
     use permitted to an account.  See create-user, and
     alter-user.

   * If the plugin directory is writable by the server, it may be
     possible for a user to write executable code to a file in the
     directory using 'SELECT ... INTO DUMPFILE'.  This can
     be prevented by making 'plugin_dir' read only to the server or by
     setting '--secure-file-priv' to a directory where 'SELECT'
     writes can be made safely.

6.1.4 Security-Related mysqld Options and Variables
---------------------------------------------------

The following table shows 'mysqld' options and system
variables that affect security.  For descriptions of each of these, see
server-options, and server-system-variables.

*Security Option and Variable Summary*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

allow-suspicious-udfsYes   Yes

automatic_sp_privileges                Yes                     Global      Yes

chroot         Yes         Yes

des-key-file   Yes         Yes

local_infile                           Yes                     Global      Yes

old_passwords                          Yes                     Both        Yes

safe-user-createYes        Yes

secure-auth    Yes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
secure_auth

secure-file-privYes        Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
secure_file_priv

skip-grant-tablesYes       Yes

skip-name-resolveYes       Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
skip_name_resolve

skip-networkingYes         Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
skip_networking

skip-show-databaseYes      Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
skip_show_database

6.1.5 How to Run MySQL as a Normal User
---------------------------------------

On Windows, you can run the server as a Windows service using a normal
user account.

On Linux, for installations performed using a MySQL repository, RPM
packages, or Debian packages, the MySQL server 'mysqld'.
should be started by the local 'mysql' operating system user.  Starting
by another operating system user is not supported by the init scripts
that are included as part of the installation.

On Unix (or Linux for installations performed using 'tar' or 'tar.gz'
packages) , the MySQL server 'mysqld' can be started and
run by any user.  However, you should avoid running the server as the
Unix 'root' user for security reasons.  To change 'mysqld'
to run as a normal unprivileged Unix user USER_NAME, you must do
the following:

  1. Stop the server if it is running (use 'mysqladmin shutdown').

  2. Change the database directories and files so that USER_NAME has
     privileges to read and write files in them (you might need to do
     this as the Unix 'root' user):

          shell> chown -R USER_NAME /PATH/TO/MYSQL/DATADIR

     If you do not do this, the server will not be able to access
     databases or tables when it runs as USER_NAME.

     If directories or files within the MySQL data directory are
     symbolic links, 'chown -R' might not follow symbolic links for you.
     If it does not, you will also need to follow those links and change
     the directories and files they point to.

  3. Start the server as user USER_NAME.  Another alternative is to
     start 'mysqld' as the Unix 'root' user and use the
     '--user=USER_NAME' option.  'mysqld' starts up, then
     switches to run as the Unix user USER_NAME before accepting any
     connections.

  4. To start the server as the given user automatically at system
     startup time, specify the user name by adding a 'user' option to
     the '[mysqld]' group of the '/etc/my.cnf' option file or the
     'my.cnf' option file in the server's data directory.  For example:

          [mysqld]
          user=USER_NAME

If your Unix machine itself is not secured, you should assign passwords
to the MySQL 'root' account in the grant tables.  Otherwise, any user
with a login account on that machine can run the 'mysql'.
client with a '--user=root' option and perform any operation.  (It is a
good idea to assign passwords to MySQL accounts in any case, but
especially so when other login accounts exist on the server host.)  See
default-privileges.

6.1.6 Security Issues with LOAD DATA LOCAL
------------------------------------------

The 'LOAD DATA' statement can load a file located on
the server host, or, if the 'LOCAL' keyword is specified, on the client
host.

There are two potential security issues with the 'LOCAL' version of
'LOAD DATA'.:

   * The transfer of the file from the client host to the server host is
     initiated by the MySQL server.  In theory, a patched server could
     be built that would tell the client program to transfer a file of
     the server's choosing rather than the file named by the client in
     the 'LOAD DATA' statement.  Such a server could
     access any file on the client host to which the client user has
     read access.  (A patched server could in fact reply with a
     file-transfer request to any statement, not just 'LOAD DATA LOCAL',
     so a more fundamental issue is that clients
     should not connect to untrusted servers.)

   * In a Web environment where the clients are connecting from a Web
     server, a user could use 'LOAD DATA LOCAL' to
     read any files that the Web server process has read access to
     (assuming that a user could run any statement against the SQL
     server).  In this environment, the client with respect to the MySQL
     server actually is the Web server, not a remote program being run
     by users who connect to the Web server.

To avoid 'LOAD DATA' issues, clients should avoid
using 'LOCAL'.  To avoid connecting to untrusted servers, clients can
establish a secure connection and verify the server identity by
connecting using the '--ssl-mode=VERIFY_IDENTITY' option and the
appropriate CA certificate.

To enable adminstrators and applications to manage the local data
loading capability, 'LOCAL' configuration works like this:

   * On the server side:

        * The 'local_infile' system variable controls server-side
          'LOCAL' capability.  Depending on the 'local_infile' setting,
          the server refuses or permits local data loading by clients
          that have 'LOCAL' enabled on the client side.  By default,
          'local_infile' is enabled.

        * To explicitly cause the server to refuse or permit 'LOAD DATA LOCAL'
          statements (regardless of how client
          programs and libraries are configured at build time or
          runtime), start 'mysqld' with 'local_infile'
          disabled or enabled, respectively.  'local_infile' can also be
          set at runtime.

   * On the client side:

        * The 'ENABLED_LOCAL_INFILE' 'CMake' option controls the
          compiled-in default 'LOCAL' capability for the MySQL client
          library.  Clients that make no explicit arrangements therefore
          have 'LOCAL' capability disabled or enabled according to the
          'ENABLED_LOCAL_INFILE' setting specified at MySQL build time.

          By default, the client library in MySQL binary distributions
          is compiled with 'ENABLED_LOCAL_INFILE' enabled.  If you
          compile MySQL from source, configure it with
          'ENABLED_LOCAL_INFILE' disabled or enabled based on whether
          clients that make no explicit arrangements should have 'LOCAL'
          capability disabled or enabled, respectively.

        * Client programs that use the C API can control load data
          loading explicitly by invoking 'mysql_options()'
          to disable or enable the
          'MYSQL_OPT_LOCAL_INFILE' option.  See mysql-options.

        * For the 'mysql' client, local data loading is
          disabled by default.  To disable or enable it explicitly, use
          the '--local-infile=0' or '--local-infile[=1]' option.

        * For the 'mysqlimport' client, local data
          loading is disabled by default.  To disable or enable it
          explicitly, use the '--local=0' or '--local[=1]' option.

        * If you use 'LOAD DATA LOCAL' in Perl scripts
          or other programs that read the '[client]' group from option
          files, you can add an 'local-infile' option setting to that
          group.  To prevent problems for programs that do not
          understand this option, specify it using the 'loose-'
          prefix:

               [client]
               loose-local-infile=0

          or:

               [client]
               loose-local-infile=1

        * In all cases, successful use of a 'LOCAL' load operation by a
          client also requires that the server permits it.

If 'LOCAL' capability is disabled, on either the server or client side,
a client that attempts to issue a 'LOAD DATA LOCAL'.
statement receives the following error message:

     ERROR 1148: The used command is not allowed with this MySQL version

6.1.7 Client Programming Security Guidelines
--------------------------------------------

Applications that access MySQL should not trust any data entered by
users, who can try to trick your code by entering special or escaped
character sequences in Web forms, URLs, or whatever application you have
built.  Be sure that your application remains secure if a user enters
something like '; DROP DATABASE mysql;'.  This is an extreme example,
but large security leaks and data loss might occur as a result of
hackers using similar techniques, if you do not prepare for them.

A common mistake is to protect only string data values.  Remember to
check numeric data as well.  If an application generates a query such as
'SELECT * FROM table WHERE ID=234' when a user enters the value '234',
the user can enter the value '234 OR 1=1' to cause the application to
generate the query 'SELECT * FROM table WHERE ID=234 OR 1=1'.  As a
result, the server retrieves every row in the table.  This exposes every
row and causes excessive server load.  The simplest way to protect from
this type of attack is to use single quotation marks around the numeric
constants: 'SELECT * FROM table WHERE ID='234''.  If the user enters
extra information, it all becomes part of the string.  In a numeric
context, MySQL automatically converts this string to a number and strips
any trailing nonnumeric characters from it.

Sometimes people think that if a database contains only publicly
available data, it need not be protected.  This is incorrect.  Even if
it is permissible to display any row in the database, you should still
protect against denial of service attacks (for example, those that are
based on the technique in the preceding paragraph that causes the server
to waste resources).  Otherwise, your server becomes unresponsive to
legitimate users.

Checklist:

   * Enable strict SQL mode to tell the server to be more restrictive of
     what data values it accepts.  See sql-mode.

   * Try to enter single and double quotation marks (''' and '"') in all
     of your Web forms.  If you get any kind of MySQL error, investigate
     the problem right away.

   * Try to modify dynamic URLs by adding '%22' ('"'), '%23' ('#'), and
     '%27' (''') to them.

   * Try to modify data types in dynamic URLs from numeric to character
     types using the characters shown in the previous examples.  Your
     application should be safe against these and similar attacks.

   * Try to enter characters, spaces, and special symbols rather than
     numbers in numeric fields.  Your application should remove them
     before passing them to MySQL or else generate an error.  Passing
     unchecked values to MySQL is very dangerous!

   * Check the size of data before passing it to MySQL.

   * Have your application connect to the database using a user name
     different from the one you use for administrative purposes.  Do not
     give your applications any access privileges they do not need.

Many application programming interfaces provide a means of escaping
special characters in data values.  Properly used, this prevents
application users from entering values that cause the application to
generate statements that have a different effect than you intend:

   * MySQL C API: Use the 'mysql_real_escape_string_quote()'.
     API call.

   * MySQL++: Use the 'escape' and 'quote' modifiers for query streams.

   * PHP: Use either the 'mysqli' or 'pdo_mysql' extensions, and not the
     older 'ext/mysql' extension.  The preferred API's support the
     improved MySQL authentication protocol and passwords, as well as
     prepared statements with placeholders.  See also Choosing an API
     (http://dev.mysql.com/doc/apis-php/en/apis-php-mysqlinfo.api.choosing.html).

     If the older 'ext/mysql' extension must be used, then for escaping
     use the 'mysql_real_escape_string_quote()'
     function and not
     'mysql_escape_string()' or 'addslashes()'
     because only 'mysql_real_escape_string_quote()'
     is character set-aware; the other
     functions can be 'bypassed' when using (invalid) multibyte
     character sets.

   * Perl DBI: Use placeholders or the 'quote()' method.

   * Ruby DBI: Use placeholders or the 'quote()' method.

   * Java JDBC: Use a 'PreparedStatement' object and placeholders.

Other programming interfaces might have similar capabilities.

6.2 The MySQL Access Privilege System
=====================================

The primary function of the MySQL privilege system is to authenticate a
user who connects from a given host and to associate that user with
privileges on a database such as 'SELECT', 'INSERT',
see 'UPDATE', and 'DELETE'.  Additional
functionality includes the ability to have anonymous users and to grant
privileges for MySQL-specific functions such as 'LOAD DATA INFILE'
and administrative operations.

There are some things that you cannot do with the MySQL privilege
system:

   * You cannot explicitly specify that a given user should be denied
     access.  That is, you cannot explicitly match a user and then
     refuse the connection.

   * You cannot specify that a user has privileges to create or drop
     tables in a database but not to create or drop the database itself.

   * A password applies globally to an account.  You cannot associate a
     password with a specific object such as a database, table, or
     routine.

The user interface to the MySQL privilege system consists of SQL
statements such as 'CREATE USER', 'GRANT',
and 'REVOKE'.  See account-management-sql.

Internally, the server stores privilege information in the grant tables
of the 'mysql' database (that is, in the database named 'mysql').  The
MySQL server reads the contents of these tables into memory when it
starts and bases access-control decisions on the in-memory copies of the
grant tables.

The MySQL privilege system ensures that all users may perform only the
operations permitted to them.  As a user, when you connect to a MySQL
server, your identity is determined by _the host from which you connect_
and _the user name you specify_.  When you issue requests after
connecting, the system grants privileges according to your identity and
_what you want to do_.

MySQL considers both your host name and user name in identifying you
because there is no reason to assume that a given user name belongs to
the same person on all hosts.  For example, the user 'joe' who connects
from 'office.example.com' need not be the same person as the user 'joe'
who connects from 'home.example.com'.  MySQL handles this by enabling
you to distinguish users on different hosts that happen to have the same
name: You can grant one set of privileges for connections by 'joe' from
'office.example.com', and a different set of privileges for connections
by 'joe' from 'home.example.com'.  To see what privileges a given
account has, use the 'SHOW GRANTS' statement.  For
example:

     SHOW GRANTS FOR 'joe'@'office.example.com';
     SHOW GRANTS FOR 'joe'@'home.example.com';

MySQL access control involves two stages when you run a client program
that connects to the server:

*Stage 1:* The server accepts or rejects the connection based on your
identity and whether you can verify your identity by supplying the
correct password.

*Stage 2:* Assuming that you can connect, the server checks each
statement you issue to determine whether you have sufficient privileges
to perform it.  For example, if you try to select rows from a table in a
database or drop a table from the database, the server verifies that you
have the 'SELECT' privilege for the table or the 'DROP' privilege for
the database.

For a more detailed description of what happens during each stage, see
connection-access, and request-access.

If your privileges are changed (either by yourself or someone else)
while you are connected, those changes do not necessarily take effect
immediately for the next statement that you issue.  For details about
the conditions under which the server reloads the grant tables, see
privilege-changes.

For general security-related advice, see
general-security-issues.  For help in diagnosing privilege-related
problems, see problems-connecting.

6.2.1 Privileges Provided by MySQL
----------------------------------

The privileges granted to a MySQL account determine which operations the
account can perform.  MySQL privileges differ in the contexts in which
they apply and at different levels of operation:

   * Administrative privileges enable users to manage operation of the
     MySQL server.  These privileges are global because they are not
     specific to a particular database.

   * Database privileges apply to a database and to all objects within
     it.  These privileges can be granted for specific databases, or
     globally so that they apply to all databases.

   * Privileges for database objects such as tables, indexes, views, and
     stored routines can be granted for specific objects within a
     database, for all objects of a given type within a database (for
     example, all tables in a database), or globally for all objects of
     a given type in all databases).

Information about account privileges is stored in the 'user', 'db',
'tables_priv', 'columns_priv', and 'procs_priv' tables in the 'mysql'
system database (see grant-tables).  The MySQL server reads the
contents of these tables into memory when it starts and reloads them
under the circumstances indicated in privilege-changes.
Access-control decisions are based on the in-memory copies of the grant
tables.

Some MySQL releases introduce changes to the structure of the grant
tables to add new privileges or features.  To make sure that you can
take advantage of any new capabilities, update your grant tables to have
the current structure whenever you upgrade MySQL. See
mysql-upgrade.

The following table shows the privilege names used in 'GRANT'
and 'REVOKE' statements, along with the column
name associated with each privilege in the grant tables and the context
in which the privilege applies.

*Permissible Privileges for GRANT and REVOKE*

Privilege              Column                   Context

'ALL [PRIVILEGES]'     Synonym for 'all         Server administration
                       privileges'

'ALTER'                'Alter_priv'             Tables

'ALTER ROUTINE'        'Alter_routine_priv'     Stored routines

'CREATE'               'Create_priv'            Databases, tables, or
                                                indexes

'CREATE ROUTINE'       'Create_routine_priv'    Stored routines

'CREATE TABLESPACE'    'Create_tablespace_priv' Server administration

'CREATE TEMPORARY      'Create_tmp_table_priv'  Tables
TABLES'

'CREATE USER'          'Create_user_priv'       Server administration

'CREATE VIEW'          'Create_view_priv'       Views

'DELETE'               'Delete_priv'            Tables

'DROP'                 'Drop_priv'              Databases, tables, or
                                                views

'EVENT'                'Event_priv'             Databases

'EXECUTE'              'Execute_priv'           Stored routines

'FILE'                 'File_priv'              File access on server
                                                host

'GRANT OPTION'         'Grant_priv'             Databases, tables, or
                                                stored routines

'INDEX'                'Index_priv'             Tables

'INSERT'               'Insert_priv'            Tables or columns

'LOCK TABLES'          'Lock_tables_priv'       Databases

'PROCESS'              'Process_priv'           Server administration

'PROXY'                See 'proxies_priv'       Server administration
                       table

'REFERENCES'           'References_priv'        Databases or tables

'RELOAD'               'Reload_priv'            Server administration

'REPLICATION CLIENT'   'Repl_client_priv'       Server administration

'REPLICATION SLAVE'    'Repl_slave_priv'        Server administration

'SELECT'               'Select_priv'            Tables or columns

'SHOW DATABASES'       'Show_db_priv'           Server administration

'SHOW VIEW'            'Show_view_priv'         Views

'SHUTDOWN'             'Shutdown_priv'          Server administration

'SUPER'                'Super_priv'             Server administration

'TRIGGER'              'Trigger_priv'           Tables

'UPDATE'               'Update_priv'            Tables or columns

'USAGE'                Synonym for 'no          Server administration
                       privileges'

The following list provides general descriptions of the privileges
available in MySQL. Particular SQL statements might have more specific
privilege requirements than indicated here.  If so, the description for
the statement in question provides the details.

   * The 'ALL' or 'ALL PRIVILEGES' privilege specifier is shorthand.  It
     stands for 'all privileges available at a given privilege level'
     (except 'GRANT OPTION').  For example, granting 'ALL' at the global
     or table level grants all global privileges or all table-level
     privileges.

   * The 'ALTER' privilege enables use of the 'ALTER TABLE'
     statement to change the structure of tables.
     'ALTER TABLE' also requires the 'CREATE' and 'INSERT'
     privileges.  Renaming a table requires 'ALTER' and 'DROP' on the
     old table, 'CREATE', and 'INSERT' on the new table.

   * The 'ALTER ROUTINE' privilege is needed to alter or drop stored
     routines (procedures and functions).

   * The 'CREATE' privilege enables creation of new databases and
     tables.

   * The 'CREATE ROUTINE' privilege is needed to create stored routines
     (procedures and functions).

   * The 'CREATE TABLESPACE' privilege is needed to create, alter, or
     drop tablespaces and log file groups.

   * The 'CREATE TEMPORARY TABLES' privilege enables the creation of
     temporary tables using the 'CREATE TEMPORARY TABLE'
     statement.

     After a session has created a temporary table, the server performs
     no further privilege checks on the table.  The creating session can
     perform any operation on the table, such as 'DROP TABLE',
     see 'INSERT', 'UPDATE', or
     'SELECT'.  For more information, see
     create-temporary-table.

   * The 'CREATE USER' privilege enables use of the 'ALTER USER',
     see 'CREATE USER', 'DROP USER',
     see 'RENAME USER', and 'REVOKE ALL PRIVILEGES'
     statements.

   * The 'CREATE VIEW' privilege enables use of the 'CREATE VIEW'
     statement.

   * The 'DELETE' privilege enables rows to be deleted from tables in a
     database.

   * The 'DROP' privilege enables you to drop (remove) existing
     databases, tables, and views.  The 'DROP' privilege is required in
     order to use the statement 'ALTER TABLE ... DROP PARTITION' on a
     partitioned table.  The 'DROP' privilege is also required for
     'TRUNCATE TABLE'.  _If you grant the 'DROP'
     privilege for the 'mysql' database to a user, that user can drop
     the database in which the MySQL access privileges are stored._

   * The 'EVENT' privilege is required to create, alter, drop, or see
     events for the Event Scheduler.

   * The 'EXECUTE' privilege is required to execute stored routines
     (procedures and functions).

   * The 'FILE' privilege gives you permission to read and write files
     on the server host using the 'LOAD DATA INFILE'.
     and 'SELECT ... INTO OUTFILE' statements and
     the 'LOAD_FILE()' function.  A user who has the 'FILE' privilege
     can read any file on the server host that is either world-readable
     or readable by the MySQL server.  (This implies the user can read
     any file in any database directory, because the server can access
     any of those files.)  The 'FILE' privilege also enables the user to
     create new files in any directory where the MySQL server has write
     access.  This includes the server's data directory containing the
     files that implement the privilege tables.  As a security measure,
     the server will not overwrite existing files.  As of MySQL 5.7.17,
     the 'FILE' privilege is required to use the 'DATA DIRECTORY' or
     'INDEX DIRECTORY' table option for the 'CREATE TABLE'
     statement.

     To limit the location in which files can be read and written, set
     the 'secure_file_priv' system to a specific directory.  See
     server-system-variables.

   * The 'GRANT OPTION' privilege enables you to give to other users or
     remove from other users those privileges that you yourself possess.

   * The 'INDEX' privilege enables you to create or drop (remove)
     indexes.  'INDEX' applies to existing tables.  If you have the
     'CREATE' privilege for a table, you can include index definitions
     in the 'CREATE TABLE' statement.

   * The 'INSERT' privilege enables rows to be inserted into tables in a
     database.  'INSERT' is also required for the 'ANALYZE TABLE',
     see 'OPTIMIZE TABLE', and
     'REPAIR TABLE' table-maintenance statements.

   * The 'LOCK TABLES' privilege enables the use of explicit 'LOCK TABLES'
     statements to lock tables for which you have
     the 'SELECT' privilege.  This includes the use of write locks,
     which prevents other sessions from reading the locked table.

   * The 'PROCESS' privilege pertains to display of information about
     the threads executing within the server (that is, information about
     the statements being executed by sessions).  The privilege enables
     use of 'SHOW PROCESSLIST' or
     'mysqladmin processlist' to see threads belonging to
     other accounts; you can always see your own threads.  The 'PROCESS'
     privilege also enables use of 'SHOW ENGINE'.

   * The 'PROXY' privilege enables a user to impersonate or become known
     as another user.  See proxy-users.

   * The creation of a foreign key constraint requires the 'REFERENCES'
     privilege for the parent table.

   * The 'RELOAD' privilege enables use of the 'FLUSH'.
     statement.  It also enables 'mysqladmin'.
     commands that are equivalent to 'FLUSH' operations:
     'flush-hosts', 'flush-logs', 'flush-privileges', 'flush-status',
     'flush-tables', 'flush-threads', 'refresh', and 'reload'.

     The 'reload' command tells the server to reload the grant tables
     into memory.  'flush-privileges' is a synonym for 'reload'.  The
     'refresh' command closes and reopens the log files and flushes all
     tables.  The other 'flush-XXX' commands perform functions similar
     to 'refresh', but are more specific and may be preferable in some
     instances.  For example, if you want to flush just the log files,
     'flush-logs' is a better choice than 'refresh'.

   * The 'REPLICATION CLIENT' privilege enables the use of the
     'SHOW MASTER STATUS', 'SHOW SLAVE STATUS',
     and 'SHOW BINARY LOGS'
     statements.

   * The 'REPLICATION SLAVE' privilege should be granted to accounts
     that are used by slave servers to connect to the current server as
     their master.  Without this privilege, the slave cannot request
     updates that have been made to databases on the master server.

   * The 'SELECT' privilege enables you to select rows from tables in a
     database.  'SELECT' statements require the 'SELECT'
     privilege only if they actually retrieve rows from a table.  Some
     'SELECT' statements do not access tables and can be
     executed without permission for any database.  For example, you can
     use 'SELECT' as a simple calculator to evaluate
     expressions that make no reference to tables:

          SELECT 1+1;
          SELECT PI()*2;

     The 'SELECT' privilege is also needed for other statements that
     read column values.  For example, 'SELECT' is needed for columns
     referenced on the right hand side of COL_NAME=EXPR assignment in
     'UPDATE' statements or for columns named in the
     'WHERE' clause of 'DELETE' or 'UPDATE'
     statements.

     The 'SELECT' privilege is also needed for tables or views being
     used with 'EXPLAIN', including any underlying tables
     of views.

   * The 'SHOW DATABASES' privilege enables the account to see database
     names by issuing the 'SHOW DATABASE' statement.  Accounts that do
     not have this privilege see only databases for which they have some
     privileges, and cannot use the statement at all if the server was
     started with the '--skip-show-database' option.  Note that _any_
     global privilege is a privilege for the database.

   * The 'SHOW VIEW' privilege enables use of the 'SHOW CREATE VIEW'
     statement.  This privilege is also needed
     for views being used with 'EXPLAIN'.

   * The 'SHUTDOWN' privilege enables use of the 'SHUTDOWN'
     statement, the 'mysqladmin shutdown'.
     command, and the 'mysql_shutdown()'. C API
     function.

   * The 'SUPER' privilege enables these operations and server
     behaviors:

        * Enables configuration changes by modifying global system
          variables.  For some system variables, setting the session
          value also requires the 'SUPER' privilege; if so, it is
          indicated in the variable description.  Examples include
          'binlog_format', 'sql_log_bin', and 'sql_log_off'.

        * Enables changes to global transaction characteristics (see
          set-transaction).

        * Enables starting and stopping replication on slave servers,
          including Group Replication.

        * Enables use of the 'CHANGE MASTER TO'.
          and 'CHANGE REPLICATION FILTER'
          statements.

        * Enables binary log control by means of the 'PURGE BINARY LOGS'
          and 'BINLOG'.
          statements.

        * Enables setting the effective authorization ID when executing
          a view or stored program.  A user with this privilege can
          specify any account in the 'DEFINER' attribute of a view or
          stored program.

        * Enables use of the 'CREATE SERVER',
          'ALTER SERVER', and 'DROP SERVER'
          statements.

        * Enables use of the 'mysqladmin debug'.
          command.

        * Enables 'InnoDB' key rotation.

        * Enables reading the DES key file by the 'DES_ENCRYPT()'
          function.

        * Enables execution of Version Tokens user-defined functions.

        * Enables control over client connections not permitted to
          non-'SUPER' accounts:

             * Enables use of the 'KILL' statement or
               'mysqladmin kill' command to kill threads
               belonging to other accounts.  (You can always kill your
               own threads.)

             * The server accepts one connection from a 'SUPER' client
               even if the connection limit controlled by the
               'max_connections' system variable is reached.

             * Updates can be performed even when the 'read_only' system
               variable is enabled.  This applies to table updates and
               use of account-management statements such as
               'GRANT' and 'REVOKE'.

             * The server does not execute 'init_connect' system
               variable content when 'SUPER' clients connect.

             * A server in offline mode ('offline_mode' enabled) does
               not terminate 'SUPER' client connections at the next
               client request, and accepts new connections from 'SUPER'
               clients.

     You may also need the 'SUPER' privilege to create or alter stored
     functions if binary logging is enabled, as described in
     stored-programs-logging.

   * The 'TRIGGER' privilege enables trigger operations.  You must have
     this privilege for a table to create, drop, execute, or display
     triggers for that table.

     When a trigger is activated (by a user who has privileges to
     execute 'INSERT', 'UPDATE', or
     'DELETE' statements for the table associated with the
     trigger), trigger execution requires that the user who defined the
     trigger still have the 'TRIGGER' privilege.

   * The 'UPDATE' privilege enables rows to be updated in tables in a
     database.

   * The 'USAGE' privilege specifier stands for 'no privileges.' It is
     used at the global level with 'GRANT' to modify
     account attributes such as resource limits or SSL characteristics
     without naming specific account privileges.  'SHOW GRANTS'
     displays 'USAGE' to indicate that an account has no
     privileges at a privilege level.

It is a good idea to grant to an account only those privileges that it
needs.  You should exercise particular caution in granting the 'FILE'
and administrative privileges:

   * The 'FILE' privilege can be abused to read into a database table
     any files that the MySQL server can read on the server host.  This
     includes all world-readable files and files in the server's data
     directory.  The table can then be accessed using 'SELECT'
     to transfer its contents to the client host.

   * The 'GRANT OPTION' privilege enables users to give their privileges
     to other users.  Two users that have different privileges and with
     the 'GRANT OPTION' privilege are able to combine privileges.

   * The 'ALTER' privilege may be used to subvert the privilege system
     by renaming tables.

   * The 'SHUTDOWN' privilege can be abused to deny service to other
     users entirely by terminating the server.

   * The 'PROCESS' privilege can be used to view the plain text of
     currently executing statements, including statements that set or
     change passwords.

   * The 'SUPER' privilege can be used to terminate other sessions or
     change how the server operates.

   * Privileges granted for the 'mysql' database itself can be used to
     change passwords and other access privilege information.  Passwords
     are stored encrypted, so a malicious user cannot simply read them
     to know the plain text password.  However, a user with write access
     to the 'user' table 'authentication_string' column can change an
     account's password, and then connect to the MySQL server using that
     account.

6.2.2 Grant Tables
------------------

The 'mysql' system database includes several grant tables that contain
information about user accounts and the privileges held by them.  This
section describes those tables.  For information about other tables in
the system database, see system-database.

To manipulate the contents of grant tables, modify them indirectly by
using account-management statements such as 'CREATE USER',
see 'GRANT', and 'REVOKE' to set up
accounts and control the privileges available to each one.  See
account-management-sql.  The discussion here describes the underlying
structure of the grant tables and how the server uses their contents
when interacting with clients.

*Note*:

Direct modification of grant tables using statements such as
'INSERT', 'UPDATE', or 'DELETE' is
discouraged and done at your own risk.  The server is free to ignore
rows that become malformed as a result of such modifications.

As of MySQL 5.7.18, for any operation that modifies a grant table, the
server checks whether the table has the expected structure and produces
an error if not.  'mysql_upgrade' must be run to
update the tables to the expected structure.

These 'mysql' database tables contain grant information:

   * 'user': User accounts, global privileges, and other non-privilege
     columns

   * 'db': Database-level privileges

   * 'tables_priv': Table-level privileges

   * 'columns_priv': Column-level privileges

   * 'procs_priv': Stored procedure and function privileges

   * 'proxies_priv': Proxy-user privileges

Each grant table contains scope columns and privilege columns:

   * Scope columns determine the scope of each row in the tables; that
     is, the context in which the row applies.  For example, a 'user'
     table row with 'Host' and 'User' values of ''h1.example.net'' and
     ''bob'' applies to authenticating connections made to the server
     from the host 'h1.example.net' by a client that specifies a user
     name of 'bob'.  Similarly, a 'db' table row with 'Host', 'User',
     and 'Db' column values of ''h1.example.net'', ''bob'' and
     ''reports'' applies when 'bob' connects from the host
     'h1.example.net' to access the 'reports' database.  The
     'tables_priv' and 'columns_priv' tables contain scope columns
     indicating tables or table/column combinations to which each row
     applies.  The 'procs_priv' scope columns indicate the stored
     routine to which each row applies.

   * Privilege columns indicate which privileges a table row grants;
     that is, which operations it permits to be performed.  The server
     combines the information in the various grant tables to form a
     complete description of a user's privileges.  See
     request-access, describes the rules for this.

The server uses the grant tables in the following manner:

   * The 'user' table scope columns determine whether to reject or
     permit incoming connections.  For permitted connections, any
     privileges granted in the 'user' table indicate the user's global
     privileges.  Any privileges granted in this table apply to _all_
     databases on the server.

     *Caution*:

     Because any global privilege is considered a privilege for all
     databases, any global privilege enables a user to see all database
     names with 'SHOW DATABASES' or by examining
     the 'SCHEMATA' table of
     'INFORMATION_SCHEMA'.

   * The 'db' table scope columns determine which users can access which
     databases from which hosts.  The privilege columns determine the
     permitted operations.  A privilege granted at the database level
     applies to the database and to all objects in the database, such as
     tables and stored programs.

   * The 'tables_priv' and 'columns_priv' tables are similar to the 'db'
     table, but are more fine-grained: They apply at the table and
     column levels rather than at the database level.  A privilege
     granted at the table level applies to the table and to all its
     columns.  A privilege granted at the column level applies only to a
     specific column.

   * The 'procs_priv' table applies to stored routines (procedures and
     functions).  A privilege granted at the routine level applies only
     to a single procedure or function.

   * The 'proxies_priv' table indicates which users can act as proxies
     for other users and whether a user can grant the 'PROXY' privilege
     to other users.

The server uses the 'user' and 'db' tables in the 'mysql' database at
both the first and second stages of access control (see
privilege-system).  The columns in the 'user' and 'db' tables are
shown here.

*user and db Table Columns*

Table Name                    'user'                 'db'

*Scope columns*               'Host'                 'Host'

                              'User'                 'Db'

                                                     'User'

*Privilege columns*           'Select_priv'          'Select_priv'

                              'Insert_priv'          'Insert_priv'

                              'Update_priv'          'Update_priv'

                              'Delete_priv'          'Delete_priv'

                              'Index_priv'           'Index_priv'

                              'Alter_priv'           'Alter_priv'

                              'Create_priv'          'Create_priv'

                              'Drop_priv'            'Drop_priv'

                              'Grant_priv'           'Grant_priv'

                              'Create_view_priv'     'Create_view_priv'

                              'Show_view_priv'       'Show_view_priv'

                              'Create_routine_priv'  'Create_routine_priv'

                              'Alter_routine_priv'   'Alter_routine_priv'

                              'Execute_priv'         'Execute_priv'

                              'Trigger_priv'         'Trigger_priv'

                              'Event_priv'           'Event_priv'

                              'Create_tmp_table_priv''Create_tmp_table_priv'

                              'Lock_tables_priv'     'Lock_tables_priv'

                              'References_priv'      'References_priv'

                              'Reload_priv'

                              'Shutdown_priv'

                              'Process_priv'

                              'File_priv'

                              'Show_db_priv'

                              'Super_priv'

                              'Repl_slave_priv'

                              'Repl_client_priv'

                              'Create_user_priv'

                              'Create_tablespace_priv'

*Security columns*            'ssl_type'

                              'ssl_cipher'

                              'x509_issuer'

                              'x509_subject'

                              'plugin'

                              'authentication_string'

                              'password_expired'

                              'password_last_changed'

                              'password_lifetime'

                              'account_locked'

*Resource control columns*    'max_questions'

                              'max_updates'

                              'max_connections'

                              'max_user_connections'

The 'user' table 'plugin' and 'authentication_string' columns store
authentication plugin and credential information.

The server uses the plugin named in the 'plugin' column of an account
row to authenticate connection attempts for the account.

The 'plugin' column must be nonempty.  At startup, and at runtime when
'FLUSH PRIVILEGES' is executed, the server checks 'user' table rows.
For any row with an empty 'plugin' column, the server writes a warning
to the error log of this form:

     [Warning] User entry 'USER_NAME'@'HOST_NAME' has an empty plugin
     value. The user will be ignored and no one can login with this user
     anymore.

To address this problem, see account-upgrades.

The 'password_expired' column permits DBAs to expire account passwords
and require users to reset their password.  The default
'password_expired' value is ''N'', but can be set to ''Y'' with the
'ALTER USER' statement.  After an account's password
has been expired, all operations performed by the account in subsequent
connections to the server result in an error until the user issues an
'ALTER USER' statement to establish a new account
password.

It is possible after password expiration to 'reset' a password by
setting it to its current value.  As a matter of good policy, it is
preferable to choose a different password.

'password_last_changed' is a 'TIMESTAMP' column indicating when the
password was last changed.  The value is non-'NULL' only for accounts
that use MySQL built-in authentication methods (accounts that use an
authentication plugin of 'mysql_native_password' or 'sha256_password').
The value is 'NULL' for other accounts, such as those authenticated
using an external authentication system.

'password_last_changed' is updated by the 'CREATE USER',
see 'ALTER USER', and 'SET PASSWORD'
statements, and by 'GRANT' statements that
create an account or change an account password.

'password_lifetime' indicates the account password lifetime, in days.
If the password is past its lifetime (assessed using the
'password_last_changed' column), the server considers the password
expired when clients connect using the account.  A value of N greater
than zero means that the password must be changed every N days.  A value
of 0 disables automatic password expiration.  If the value is 'NULL'
(the default), the global expiration policy applies, as defined by the
'default_password_lifetime' system variable.

'account_locked' indicates whether the account is locked (see
account-locking).

During the second stage of access control, the server performs request
verification to ensure that each client has sufficient privileges for
each request that it issues.  In addition to the 'user' and 'db' grant
tables, the server may also consult the 'tables_priv' and 'columns_priv'
tables for requests that involve tables.  The latter tables provide
finer privilege control at the table and column levels.  They have the
columns shown in the following table.

*tables_priv and columns_priv Table Columns*

Table Name     'tables_priv'  'columns_priv'

*Scope         'Host'         'Host'
columns*

               'Db'           'Db'

               'User'         'User'

               'Table_name'   'Table_name'

                              'Column_name'

*Privilege     'Table_priv'   'Column_priv'
columns*

               'Column_priv'

*Other         'Timestamp'    'Timestamp'
columns*

               'Grantor'

The 'Timestamp' and 'Grantor' columns are set to the current timestamp
and the 'CURRENT_USER' value, respectively, but are otherwise unused.

For verification of requests that involve stored routines, the server
may consult the 'procs_priv' table, which has the columns shown in the
following table.

*procs_priv Table Columns*

Table Name     'procs_priv'

*Scope         'Host'
columns*

               'Db'

               'User'

               'Routine_name'

               'Routine_type'

*Privilege     'Proc_priv'
columns*

*Other         'Timestamp'
columns*

               'Grantor'

The 'Routine_type' column is an 'ENUM' column with values
of ''FUNCTION'' or ''PROCEDURE'' to indicate the type of routine the row
refers to.  This column enables privileges to be granted separately for
a function and a procedure with the same name.

The 'Timestamp' and 'Grantor' columns are unused.

The 'proxies_priv' table records information about proxy accounts.  It
has these columns:

   * 'Host', 'User': The proxy account; that is, the account that has
     the 'PROXY' privilege for the proxied account.

   * 'Proxied_host', 'Proxied_user': The proxied account.

   * 'Grantor', 'Timestamp': Unused.

   * 'With_grant': Whether the proxy account can grant the 'PROXY'
     privilege to other accounts.

For an account to be able to grant the 'PROXY' privilege to other
accounts, it must have a row in the 'proxies_priv' table with
'With_grant' set to 1 and 'Proxied_host' and 'Proxied_user' set to
indicate the account or accounts for which the privilege can be granted.
For example, the ''root'@'localhost'' account created during MySQL
installation has a row in the 'proxies_priv' table that enables granting
the 'PROXY' privilege for '''@''', that is, for all users and all hosts.
This enables 'root' to set up proxy users, as well as to delegate to
other accounts the authority to set up proxy users.  See
proxy-users.

Scope columns in the grant tables contain strings.  The default value
for each is the empty string.  The following table shows the number of
characters permitted in each column.

*Grant Table Scope Column Lengths*

Column Name                          Maximum Permitted Characters

'Host', 'Proxied_host'               60

'User', 'Proxied_user'               32

'Password'                           41

'Db'                                 64

'Table_name'                         64

'Column_name'                        64

'Routine_name'                       64

For access-checking purposes, comparisons of 'User', 'Proxied_user',
'Password', 'authentication_string', 'Db', and 'Table_name' values are
case-sensitive.  Comparisons of 'Host', 'Proxied_host', 'Column_name',
and 'Routine_name' values are not case-sensitive.

The 'user' and 'db' tables list each privilege in a separate column that
is declared as 'ENUM('N','Y') DEFAULT 'N''.  In other words, each
privilege can be disabled or enabled, with the default being disabled.

The 'tables_priv', 'columns_priv', and 'procs_priv' tables declare the
privilege columns as 'SET' columns.  Values in these columns
can contain any combination of the privileges controlled by the table.
Only those privileges listed in the column value are enabled.

*Set-Type Privilege Column Values*

Table Name     Column Name        Possible Set Elements

'tables_priv'  'Table_priv'       ''Select', 'Insert', 'Update',
                                  'Delete', 'Create', 'Drop',
                                  'Grant', 'References',
                                  'Index', 'Alter', 'Create
                                  View', 'Show view', 'Trigger''

'tables_priv'  'Column_priv'      ''Select', 'Insert', 'Update',
                                  'References''

'columns_priv' 'Column_priv'      ''Select', 'Insert', 'Update',
                                  'References''

'procs_priv'   'Proc_priv'        ''Execute', 'Alter Routine',
                                  'Grant''

Only the 'user' table specifies administrative privileges, such as
'RELOAD' and 'SHUTDOWN'.  Administrative operations are operations on
the server itself and are not database-specific, so there is no reason
to list these privileges in the other grant tables.  Consequently, the
server need consult only the 'user' table to determine whether a user
can perform an administrative operation.

The 'FILE' privilege also is specified only in the 'user' table.  It is
not an administrative privilege as such, but a user's ability to read or
write files on the server host is independent of the database being
accessed.

The server reads the contents of the grant tables into memory when it
starts.  You can tell it to reload the tables by issuing a 'FLUSH
PRIVILEGES' statement or executing a 'mysqladmin flush-privileges'
or 'mysqladmin reload'.
command.  Changes to the grant tables take effect as indicated in
privilege-changes.

When you modify an account, it is a good idea to verify that your
changes have the intended effect.  To check the privileges for a given
account, use the 'SHOW GRANTS' statement.  For
example, to determine the privileges that are granted to an account with
user name and host name values of 'bob' and 'pc84.example.com', use this
statement:

     SHOW GRANTS FOR 'bob'@'pc84.example.com';

To display nonprivilege properties of an account, use 'SHOW CREATE USER'.:

     SHOW CREATE USER 'bob'@'pc84.example.com';

6.2.3 Specifying Account Names
------------------------------

MySQL account names consist of a user name and a host name.  This
enables creation of accounts for users with the same name who can
connect from different hosts.  This section describes how to write
account names, including special values and wildcard rules.

In SQL statements such as 'CREATE USER',
'GRANT', and 'SET PASSWORD', account names
follow these rules:

   * Account name syntax is ''USER_NAME'@'HOST_NAME''.

   * An account name consisting only of a user name is equivalent to
     ''USER_NAME'@'%''.  For example, ''me'' is equivalent to
     ''me'@'%''.

   * The user name and host name need not be quoted if they are legal as
     unquoted identifiers.  Quotes are necessary to specify a USER_NAME
     string containing special characters (such as space or '-'), or a
     HOST_NAME string containing special characters or wildcard
     characters (such as '.' or '%'); for example,
     ''test-user'@'%.com''.

   * Quote user names and host names as identifiers or as strings, using
     either backticks ('`'), single quotation marks ('''), or double
     quotation marks ('"').  For string-quoting and identifier-quoting
     guidelines, see string-literals, and identifiers.

   * The user name and host name parts, if quoted, must be quoted
     separately.  That is, write ''me'@'localhost'', not
     ''me@localhost''; the latter is actually equivalent to
     ''me@localhost'@'%''.

   * A reference to the 'CURRENT_USER' or 'CURRENT_USER()' function is
     equivalent to specifying the current client's user name and host
     name literally.

MySQL stores account names in grant tables in the 'mysql' system
database using separate columns for the user name and host name parts:

   * The 'user' table contains one row for each account.  The 'User' and
     'Host' columns store the user name and host name.  This table also
     indicates which global privileges the account has.

   * Other grant tables indicate privileges an account has for databases
     and objects within databases.  These tables have 'User' and 'Host'
     columns to store the account name.  Each row in these tables
     associates with the account in the 'user' table that has the same
     'User' and 'Host' values.

   * For access-checking purposes, comparisons of User values are
     case-sensitive.  Comparisons of Host values are not case sensitive.

For additional detail about grant table structure, see
grant-tables.

User names and host names have certain special values or wildcard
conventions, as described following.

The user name part of an account name is either a nonblank value that
literally matches the user name for incoming connection attempts, or a
blank value (empty string) that matches any user name.  An account with
a blank user name is an anonymous user.  To specify an anonymous user in
SQL statements, use a quoted empty user name part, such as
'''@'localhost''.

The host name part of an account name can take many forms, and wildcards
are permitted:

   * A host value can be a host name or an IP address (IPv4 or IPv6).
     The name ''localhost'' indicates the local host.  The IP address
     ''127.0.0.1'' indicates the IPv4 loopback interface.  The IP
     address ''::1'' indicates the IPv6 loopback interface.

   *
     The '%' and '_' wildcard characters are permitted in host name or
     IP address values.  These have the same meaning as for
     pattern-matching operations performed with the 'LIKE' operator.
     For example, a host value of ''%'' matches any host name, whereas a
     value of ''%.mysql.com'' matches any host in the 'mysql.com'
     domain.  ''198.51.100.%'' matches any host in the 198.51.100 class
     C network.

     Because IP wildcard values are permitted in host values (for
     example, ''198.51.100.%'' to match every host on a subnet), someone
     could try to exploit this capability by naming a host
     '198.51.100.somewhere.com'.  To foil such attempts, MySQL does not
     perform matching on host names that start with digits and a dot.
     For example, if a host is named '1.2.example.com', its name never
     matches the host part of account names.  An IP wildcard value can
     match only IP addresses, not host names.

   *
     For a host value specified as an IPv4 address, a netmask can be
     given to indicate how many address bits to use for the network
     number.  Netmask notation cannot be used for IPv6 addresses.

     The syntax is 'HOST_IP/NETMASK'.  For example:

          CREATE USER 'david'@'198.51.100.0/255.255.255.0';

     This enables 'david' to connect from any client host having an IP
     address CLIENT_IP for which the following condition is true:

          CLIENT_IP & NETMASK = HOST_IP

     That is, for the 'CREATE USER' statement just
     shown:

          CLIENT_IP & 255.255.255.0 = 198.51.100.0

     IP addresses that satisfy this condition range from '198.51.100.0'
     to '198.51.100.255'.

     A netmask typically begins with bits set to 1, followed by bits set
     to 0.  Examples:

        * '198.0.0.0/255.0.0.0': Any host on the 198 class A network

        * '198.51.100.0/255.255.0.0': Any host on the 198.51 class B
          network

        * '198.51.100.0/255.255.255.0': Any host on the 198.51.100 class
          C network

        * '198.51.100.1': Only the host with this specific IP address

The server performs matching of host values in account names against the
client host using the value returned by the system DNS resolver for the
client host name or IP address.  Except in the case that the account
host value is specified using netmask notation, the server performs this
comparison as a string match, even for an account host value given as an
IP address.  This means that you should specify account host values in
the same format used by DNS. Here are examples of problems to watch out
for:

   * Suppose that a host on the local network has a fully qualified name
     of 'host1.example.com'.  If DNS returns name lookups for this host
     as 'host1.example.com', use that name in account host values.  If
     DNS returns just 'host1', use 'host1' instead.

   * If DNS returns the IP address for a given host as '198.51.100.2',
     that will match an account host value of '198.51.100.2' but not
     '198.051.100.2'.  Similarly, it will match an account host pattern
     like '198.51.100.%' but not '198.051.100.%'.

To avoid problems like these, it is advisable to check the format in
which your DNS returns host names and addresses.  Use values in the same
format in MySQL account names.

6.2.4 Access Control, Stage 1: Connection Verification
------------------------------------------------------

When you attempt to connect to a MySQL server, the server accepts or
rejects the connection based on these conditions:

   * Your identity and whether you can verify your identity by supplying
     the correct password

   * Whether your account is locked or unlocked

The server checks credentials first, then account locking state.  A
failure for either step causes the server to deny access to you
completely.  Otherwise, the server accepts the connection, and then
enters Stage 2 and waits for requests.

Credential checking is performed using the three 'user' table scope
columns ('Host', 'User', and 'authentication_string').  Locking state is
recorded in the 'user' table 'account_locked' column.  The server
accepts the connection only if the 'Host' and 'User' columns in some
'user' table row match the client host name and user name, the client
supplies the password specified in that row, and the 'account_locked'
value is ''N''.  The rules for permissible 'Host' and 'User' values are
given in account-names.  Account locking can be changed with the
'ALTER USER' statement.

Your identity is based on two pieces of information:

   * The client host from which you connect

   * Your MySQL user name

If the 'User' column value is nonblank, the user name in an incoming
connection must match exactly.  If the 'User' value is blank, it matches
any user name.  If the 'user' table row that matches an incoming
connection has a blank user name, the user is considered to be an
anonymous user with no name, not a user with the name that the client
actually specified.  This means that a blank user name is used for all
further access checking for the duration of the connection (that is,
during Stage 2).

The 'authentication_string' column can be blank.  This is not a wildcard
and does not mean that any password matches.  It means that the user
must connect without specifying a password.  If the server authenticates
a client using a plugin, the authentication method that the plugin
implements may or may not use the password in the
'authentication_string' column.  In this case, it is possible that an
external password is also used to authenticate to the MySQL server.

Nonblank 'authentication_string' values in the 'user' table represent
encrypted passwords.  MySQL does not store passwords in cleartext form
for anyone to see.  Rather, the password supplied by a user who is
attempting to connect is encrypted (using the password hashing method
implemented by the account authentication plugin).  The encrypted
password then is used during the connection process when checking
whether the password is correct.  This is done without the encrypted
password ever traveling over the connection.  See user-names.

From MySQL's point of view, the encrypted password is the _real_
password, so you should never give anyone access to it.  In particular,
_do not give nonadministrative users read access to tables in the
'mysql' database_.

The following table shows how various combinations of 'User' and 'Host'
values in the 'user' table apply to incoming connections.

'User'      'Host' Value              Permissible Connections
Value

''fred''    ''h1.example.net''        'fred', connecting from
                                      'h1.example.net'

''''        ''h1.example.net''        Any user, connecting from
                                      'h1.example.net'

''fred''    ''%''                     'fred', connecting from any host

''''        ''%''                     Any user, connecting from any host

''fred''    ''%.example.net''         'fred', connecting from any host
                                      in the 'example.net' domain

''fred''    ''x.example.%''           'fred', connecting from
                                      'x.example.net', 'x.example.com',
                                      'x.example.edu', and so on; this
                                      is probably not useful

''fred''    ''198.51.100.177''        'fred', connecting from the host
                                      with IP address '198.51.100.177'

''fred''    ''198.51.100.%''          'fred', connecting from any host
                                      in the '198.51.100' class C subnet

''fred''    ''198.51.100.0/255.255.255.0''Same as previous example

It is possible for the client host name and user name of an incoming
connection to match more than one row in the 'user' table.  The
preceding set of examples demonstrates this: Several of the entries
shown match a connection from 'h1.example.net' by 'fred'.

When multiple matches are possible, the server must determine which of
them to use.  It resolves this issue as follows:

   * Whenever the server reads the 'user' table into memory, it sorts
     the rows.

   * When a client attempts to connect, the server looks through the
     rows in sorted order.

   * The server uses the first row that matches the client host name and
     user name.

The server uses sorting rules that order rows with the most-specific
'Host' values first.  Literal host names and IP addresses are the most
specific.  (The specificity of a literal IP address is not affected by
whether it has a netmask, so '198.51.100.13' and
'198.51.100.0/255.255.255.0' are considered equally specific.)  The
pattern ''%'' means 'any host' and is least specific.  The empty string
'''' also means 'any host' but sorts after ''%''.  Rows with the same
'Host' value are ordered with the most-specific 'User' values first (a
blank 'User' value means 'any user' and is least specific).  For rows
with equally-specific 'Host' and 'User' values, the order is
nondeterministic.

To see how this works, suppose that the 'user' table looks like this:

     +-----------+----------+-
     | Host      | User     | ...
     +-----------+----------+-
     | %         | root     | ...
     | %         | jeffrey  | ...
     | localhost | root     | ...
     | localhost |          | ...
     +-----------+----------+-

When the server reads the table into memory, it sorts the rows using the
rules just described.  The result after sorting looks like this:

     +-----------+----------+-
     | Host      | User     | ...
     +-----------+----------+-
     | localhost | root     | ...
     | localhost |          | ...
     | %         | jeffrey  | ...
     | %         | root     | ...
     +-----------+----------+-

When a client attempts to connect, the server looks through the sorted
rows and uses the first match found.  For a connection from 'localhost'
by 'jeffrey', two of the rows from the table match: the one with 'Host'
and 'User' values of ''localhost'' and '''', and the one with values of
''%'' and ''jeffrey''.  The ''localhost'' row appears first in sorted
order, so that is the one the server uses.

Here is another example.  Suppose that the 'user' table looks like this:

     +----------------+----------+-
     | Host           | User     | ...
     +----------------+----------+-
     | %              | jeffrey  | ...
     | h1.example.net |          | ...
     +----------------+----------+-

The sorted table looks like this:

     +----------------+----------+-
     | Host           | User     | ...
     +----------------+----------+-
     | h1.example.net |          | ...
     | %              | jeffrey  | ...
     +----------------+----------+-

A connection by 'jeffrey' from 'h1.example.net' is matched by the first
row, whereas a connection by 'jeffrey' from any host is matched by the
second.

*Note*:

It is a common misconception to think that, for a given user name, all
rows that explicitly name that user are used first when the server
attempts to find a match for the connection.  This is not true.  The
preceding example illustrates this, where a connection from
'h1.example.net' by 'jeffrey' is first matched not by the row containing
''jeffrey'' as the 'User' column value, but by the row with no user
name.  As a result, 'jeffrey' is authenticated as an anonymous user,
even though he specified a user name when connecting.

If you are able to connect to the server, but your privileges are not
what you expect, you probably are being authenticated as some other
account.  To find out what account the server used to authenticate you,
use the 'CURRENT_USER()' function.  (See information-functions.)
It returns a value in 'USER_NAME@HOST_NAME' format that indicates the
'User' and 'Host' values from the matching 'user' table row.  Suppose
that 'jeffrey' connects and issues the following query:

     mysql> SELECT CURRENT_USER();
     +----------------+
     | CURRENT_USER() |
     +----------------+
     | @localhost     |
     +----------------+

The result shown here indicates that the matching 'user' table row had a
blank 'User' column value.  In other words, the server is treating
'jeffrey' as an anonymous user.

Another way to diagnose authentication problems is to print out the
'user' table and sort it by hand to see where the first match is being
made.

6.2.5 Access Control, Stage 2: Request Verification
---------------------------------------------------

After you establish a connection, the server enters Stage 2 of access
control.  For each request that you issue through that connection, the
server determines what operation you want to perform, then checks
whether you have sufficient privileges to do so.  This is where the
privilege columns in the grant tables come into play.  These privileges
can come from any of the 'user', 'db', 'tables_priv', 'columns_priv', or
'procs_priv' tables.  (You may find it helpful to refer to
grant-tables, which lists the columns present in each of the grant
tables.)

The 'user' table grants privileges that are assigned to you on a global
basis and that apply no matter what the default database is.  For
example, if the 'user' table grants you the 'DELETE' privilege, you can
delete rows from any table in any database on the server host!  It is
wise to grant privileges in the 'user' table only to people who need
them, such as database administrators.  For other users, you should
leave all privileges in the 'user' table set to ''N'' and grant
privileges at more specific levels only.  You can grant privileges for
particular databases, tables, columns, or routines.

The 'db' table grants database-specific privileges.  Values in the scope
columns of this table can take the following forms:

   * A blank 'User' value matches the anonymous user.  A nonblank value
     matches literally; there are no wildcards in user names.

   * The wildcard characters '%' and '_' can be used in the 'Host' and
     'Db' columns.  These have the same meaning as for pattern-matching
     operations performed with the 'LIKE' operator.  If you want to use
     either character literally when granting privileges, you must
     escape it with a backslash.  For example, to include the underscore
     character ('_') as part of a database name, specify it as '\_' in
     the 'GRANT' statement.

   * A ''%'' or blank 'Host' value means 'any host.'

   * A ''%'' or blank 'Db' value means 'any database.'

The server reads the 'db' table into memory and sorts it at the same
time that it reads the 'user' table.  The server sorts the 'db' table
based on the 'Host', 'Db', and 'User' scope columns.  As with the 'user'
table, sorting puts the most-specific values first and least-specific
values last, and when the server looks for matching rows, it uses the
first match that it finds.

The 'tables_priv', 'columns_priv', and 'procs_priv' tables grant
table-specific, column-specific, and routine-specific privileges.
Values in the scope columns of these tables can take the following
forms:

   * The wildcard characters '%' and '_' can be used in the 'Host'
     column.  These have the same meaning as for pattern-matching
     operations performed with the 'LIKE' operator.

   * A ''%'' or blank 'Host' value means 'any host.'

   * The 'Db', 'Table_name', 'Column_name', and 'Routine_name' columns
     cannot contain wildcards or be blank.

The server sorts the 'tables_priv', 'columns_priv', and 'procs_priv'
tables based on the 'Host', 'Db', and 'User' columns.  This is similar
to 'db' table sorting, but simpler because only the 'Host' column can
contain wildcards.

The server uses the sorted tables to verify each request that it
receives.  For requests that require administrative privileges such as
'SHUTDOWN' or 'RELOAD', the server checks only the 'user' table row
because that is the only table that specifies administrative privileges.
The server grants access if the row permits the requested operation and
denies access otherwise.  For example, if you want to execute
'mysqladmin shutdown' but your 'user' table row does not
grant the 'SHUTDOWN' privilege to you, the server denies access without
even checking the 'db' table.  (It contains no 'Shutdown_priv' column,
so there is no need to do so.)

For database-related requests (see 'INSERT', 'UPDATE',
and so on), the server first checks the user's global privileges
by looking in the 'user' table row.  If the row permits the requested
operation, access is granted.  If the global privileges in the 'user'
table are insufficient, the server determines the user's
database-specific privileges by checking the 'db' table:

The server looks in the 'db' table for a match on the 'Host', 'Db', and
'User' columns.  The 'Host' and 'User' columns are matched to the
connecting user's host name and MySQL user name.  The 'Db' column is
matched to the database that the user wants to access.  If there is no
row for the 'Host' and 'User', access is denied.

After determining the database-specific privileges granted by the 'db'
table rows, the server adds them to the global privileges granted by the
'user' table.  If the result permits the requested operation, access is
granted.  Otherwise, the server successively checks the user's table and
column privileges in the 'tables_priv' and 'columns_priv' tables, adds
those to the user's privileges, and permits or denies access based on
the result.  For stored-routine operations, the server uses the
'procs_priv' table rather than 'tables_priv' and 'columns_priv'.

Expressed in boolean terms, the preceding description of how a user's
privileges are calculated may be summarized like this:

     global privileges
     OR (database privileges AND host privileges)
     OR table privileges
     OR column privileges
     OR routine privileges

It may not be apparent why, if the global 'user' row privileges are
initially found to be insufficient for the requested operation, the
server adds those privileges to the database, table, and column
privileges later.  The reason is that a request might require more than
one type of privilege.  For example, if you execute an 'INSERT INTO ... SELECT'
statement, you need both the 'INSERT'
and the 'SELECT' privileges.  Your privileges might be such that the
'user' table row grants one privilege and the 'db' table row grants the
other.  In this case, you have the necessary privileges to perform the
request, but the server cannot tell that from either table by itself;
the privileges granted by the rows in both tables must be combined.

6.2.6 When Privilege Changes Take Effect
----------------------------------------

When 'mysqld' starts, it reads all grant table contents
into memory.  The in-memory tables become effective for access control
at that point.

If you modify the grant tables indirectly using account-management
statements such as 'GRANT', 'REVOKE',
'SET PASSWORD', or 'RENAME USER', the
server notices these changes and loads the grant tables into memory
again immediately.

If you modify the grant tables directly using statements such as
'INSERT', 'UPDATE', or 'DELETE',
your changes have no effect on privilege checking until you either
restart the server or tell it to reload the tables.  If you change the
grant tables directly but forget to reload them, your changes have _no
effect_ until you restart the server.  This may leave you wondering why
your changes seem to make no difference!

To tell the server to reload the grant tables, perform a
flush-privileges operation.  This can be done by issuing a 'FLUSH
PRIVILEGES' statement or by executing a 'mysqladmin flush-privileges'
or 'mysqladmin reload'.
command.

A grant table reload affects privileges for each existing client
connection as follows:

   * Table and column privilege changes take effect with the client's
     next request.

   * Database privilege changes take effect the next time the client
     executes a 'USE DB_NAME' statement.

     *Note*:

     Client applications may cache the database name; thus, this effect
     may not be visible to them without actually changing to a different
     database.

   * Global privileges and passwords are unaffected for a connected
     client.  These changes take effect only for subsequent connections.

If the server is started with the '--skip-grant-tables' option, it does
not read the grant tables or implement any access control.  Anyone can
connect and do anything, _which is insecure._  To cause a server thus
started to read the tables and enable access checking, flush the
privileges.

6.2.7 Troubleshooting Problems Connecting to MySQL
--------------------------------------------------

If you encounter problems when you try to connect to the MySQL server,
the following items describe some courses of action you can take to
correct the problem.

   * Make sure that the server is running.  If it is not, clients cannot
     connect to it.  For example, if an attempt to connect to the server
     fails with a message such as one of those following, one cause
     might be that the server is not running:

          shell> mysql
          ERROR 2003: Can't connect to MySQL server on 'HOST_NAME' (111)
          shell> mysql
          ERROR 2002: Can't connect to local MySQL server through socket
          '/tmp/mysql.sock' (111)

   * It might be that the server is running, but you are trying to
     connect using a TCP/IP port, named pipe, or Unix socket file
     different from the one on which the server is listening.  To
     correct this when you invoke a client program, specify a '--port'
     option to indicate the proper port number, or a '--socket' option
     to indicate the proper named pipe or Unix socket file.  To find out
     where the socket file is, you can use this command:

          shell> netstat -ln | grep mysql

   * Make sure that the server has not been configured to ignore network
     connections or (if you are attempting to connect remotely) that it
     has not been configured to listen only locally on its network
     interfaces.  If the server was started with '--skip-networking', it
     will not accept TCP/IP connections at all.  If the server was
     started with '--bind-address=127.0.0.1', it will listen for TCP/IP
     connections only locally on the loopback interface and will not
     accept remote connections.

   * Check to make sure that there is no firewall blocking access to
     MySQL. Your firewall may be configured on the basis of the
     application being executed, or the port number used by MySQL for
     communication (3306 by default).  Under Linux or Unix, check your
     IP tables (or similar) configuration to ensure that the port has
     not been blocked.  Under Windows, applications such as ZoneAlarm or
     Windows Firewall may need to be configured not to block the MySQL
     port.

   * The grant tables must be properly set up so that the server can use
     them for access control.  For some distribution types (such as
     binary distributions on Windows, or RPM distributions on Linux),
     the installation process initializes the MySQL data directory,
     including the 'mysql' database containing the grant tables.  For
     distributions that do not do this, you must initialize the data
     directory manually.  For details, see postinstallation.

     To determine whether you need to initialize the grant tables, look
     for a 'mysql' directory under the data directory.  (The data
     directory normally is named 'data' or 'var' and is located under
     your MySQL installation directory.)  Make sure that you have a file
     named 'user.MYD' in the 'mysql' database directory.  If not, see
     initialize the data directory.
     After doing so and starting the server, you should be able to
     connect to the server.

   * After a fresh installation, if you try to log on to the server as
     'root' without using a password, you might get the following error
     message.

          shell> mysql -u root
          ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)

     It means a root password has already been assigned during
     installation and it has to be supplied.  See
     default-privileges on the different ways the password could have
     been assigned and, in some cases, how to find it.  If you need to
     reset the root password, see instructions in
     resetting-permissions.  After you have found or reset your
     password, log on again as 'root' using the '--password' (or '-p')
     option:

          shell> mysql -u root -p
          Enter password:

     However, the server is going to let you connect as 'root' without
     using a password if you have initialized MySQL using 'mysqld --initialize-insecure'.
     (see
     data-directory-initialization-mysqld for details).  That is a
     security risk, so you should set a password for the 'root' account;
     see default-privileges for instructions.

   *
     If you have updated an existing MySQL installation to a newer
     version, did you run the 'mysql_upgrade'.
     script?  If not, do so.  The structure of the grant tables changes
     occasionally when new capabilities are added, so after an upgrade
     you should always make sure that your tables have the current
     structure.  For instructions, see mysql-upgrade.

   * If a client program receives the following error message when it
     tries to connect, it means that the server expects passwords in a
     newer format than the client is capable of generating:

          shell> mysql
          Client does not support authentication protocol requested
          by server; consider upgrading MySQL client

     For information on how to deal with this, see
     account-upgrades.

   *
     Remember that client programs use connection parameters specified
     in option files or environment variables.  If a client program
     seems to be sending incorrect default connection parameters when
     you have not specified them on the command line, check any
     applicable option files and your environment.  For example, if you
     get 'Access denied' when you run a client without any options, make
     sure that you have not specified an old password in any of your
     option files!

     You can suppress the use of option files by a client program by
     invoking it with the '--no-defaults' option.  For example:

          shell> mysqladmin --no-defaults -u root version

     The option files that clients use are listed in
     option-files.  Environment variables are listed in
     environment-variables.

   * If you get the following error, it means that you are using an
     incorrect 'root' password:

          shell> mysqladmin -u root -pXXXX ver
          Access denied for user 'root'@'localhost' (using password: YES)

     If the preceding error occurs even when you have not specified a
     password, it means that you have an incorrect password listed in
     some option file.  Try the '--no-defaults' option as described in
     the previous item.

     For information on changing passwords, see
     assigning-passwords.

     If you have lost or forgotten the 'root' password, see
     resetting-permissions.

   * 'localhost' is a synonym for your local host name, and is also the
     default host to which clients try to connect if you specify no host
     explicitly.

     You can use a '--host=127.0.0.1' option to name the server host
     explicitly.  This will make a TCP/IP connection to the local
     'mysqld' server.  You can also use TCP/IP by specifying a
     '--host' option that uses the actual host name of the local host.
     In this case, the host name must be specified in a 'user' table row
     on the server host, even though you are running the client program
     on the same host as the server.

   * The 'Access denied' error message tells you who you are trying to
     log in as, the client host from which you are trying to connect,
     and whether you were using a password.  Normally, you should have
     one row in the 'user' table that exactly matches the host name and
     user name that were given in the error message.  For example, if
     you get an error message that contains 'using password: NO', it
     means that you tried to log in without a password.

   * If you get an 'Access denied' error when trying to connect to the
     database with 'mysql -u USER_NAME', you may have a problem with the
     'user' table.  Check this by executing 'mysql -u root mysql' and
     issuing this SQL statement:

          SELECT * FROM user;

     The result should include a row with the 'Host' and 'User' columns
     matching your client's host name and your MySQL user name.

   * If the following error occurs when you try to connect from a host
     other than the one on which the MySQL server is running, it means
     that there is no row in the 'user' table with a 'Host' value that
     matches the client host:

          Host ... is not allowed to connect to this MySQL server

     You can fix this by setting up an account for the combination of
     client host name and user name that you are using when trying to
     connect.

     If you do not know the IP address or host name of the machine from
     which you are connecting, you should put a row with ''%'' as the
     'Host' column value in the 'user' table.  After trying to connect
     from the client machine, use a 'SELECT USER()' query to see how you
     really did connect.  Then change the ''%'' in the 'user' table row
     to the actual host name that shows up in the log.  Otherwise, your
     system is left insecure because it permits connections from any
     host for the given user name.

     On Linux, another reason that this error might occur is that you
     are using a binary MySQL version that is compiled with a different
     version of the 'glibc' library than the one you are using.  In this
     case, you should either upgrade your operating system or 'glibc',
     or download a source distribution of MySQL version and compile it
     yourself.  A source RPM is normally trivial to compile and install,
     so this is not a big problem.

   * If you specify a host name when trying to connect, but get an error
     message where the host name is not shown or is an IP address, it
     means that the MySQL server got an error when trying to resolve the
     IP address of the client host to a name:

          shell> mysqladmin -u root -pXXXX -h SOME_HOSTNAME ver
          Access denied for user 'root'@'' (using password: YES)

     If you try to connect as 'root' and get the following error, it
     means that you do not have a row in the 'user' table with a 'User'
     column value of ''root'' and that 'mysqld' cannot
     resolve the host name for your client:

          Access denied for user ''@'unknown'

     These errors indicate a DNS problem.  To fix it, execute
     'mysqladmin flush-hosts' to reset the internal DNS
     host cache.  See host-cache.

     Some permanent solutions are:

        * Determine what is wrong with your DNS server and fix it.

        * Specify IP addresses rather than host names in the MySQL grant
          tables.

        * Put an entry for the client machine name in '/etc/hosts' on
          Unix or '\windows\hosts' on Windows.

        * Start 'mysqld' with the '--skip-name-resolve'
          option.

        * Start 'mysqld' with the '--skip-host-cache'
          option.

        * On Unix, if you are running the server and the client on the
          same machine, connect to 'localhost'.  For connections to
          'localhost', MySQL programs attempt to connect to the local
          server by using a Unix socket file, unless there are
          connection parameters specified to ensure that the client
          makes a TCP/IP connection.  For more information, see
          connecting.

        * On Windows, if you are running the server and the client on
          the same machine and the server supports named pipe
          connections, connect to the host name '.' (period).
          Connections to '.' use a named pipe rather than TCP/IP.

   * If 'mysql -u root' works but 'mysql -h YOUR_HOSTNAME -u root'
     results in 'Access denied' (where YOUR_HOSTNAME is the actual host
     name of the local host), you may not have the correct name for your
     host in the 'user' table.  A common problem here is that the 'Host'
     value in the 'user' table row specifies an unqualified host name,
     but your system's name resolution routines return a fully qualified
     domain name (or vice versa).  For example, if you have a row with
     host ''pluto'' in the 'user' table, but your DNS tells MySQL that
     your host name is ''pluto.example.com'', the row does not work.
     Try adding a row to the 'user' table that contains the IP address
     of your host as the 'Host' column value.  (Alternatively, you could
     add a row to the 'user' table with a 'Host' value that contains a
     wildcard; for example, ''pluto.%''.  However, use of 'Host' values
     ending with '%' is _insecure_ and is _not_ recommended!)

   * If 'mysql -u USER_NAME' works but 'mysql -u USER_NAME SOME_DB' does
     not, you have not granted access to the given user for the database
     named SOME_DB.

   * If 'mysql -u USER_NAME' works when executed on the server host, but
     'mysql -h HOST_NAME -u USER_NAME' does not work when executed on a
     remote client host, you have not enabled access to the server for
     the given user name from the remote host.

   * If you cannot figure out why you get 'Access denied', remove from
     the 'user' table all rows that have 'Host' values containing
     wildcards (rows that contain ''%'' or ''_'' characters).  A very
     common error is to insert a new row with 'Host'=''%'' and
     'User'=''SOME_USER'', thinking that this enables you to specify
     'localhost' to connect from the same machine.  The reason that this
     does not work is that the default privileges include a row with
     'Host'=''localhost'' and 'User'=''''.  Because that row has a
     'Host' value ''localhost'' that is more specific than ''%'', it is
     used in preference to the new row when connecting from 'localhost'!
     The correct procedure is to insert a second row with
     'Host'=''localhost'' and 'User'=''SOME_USER'', or to delete the row
     with 'Host'=''localhost'' and 'User'=''''.  After deleting the row,
     remember to issue a 'FLUSH PRIVILEGES' statement to reload the
     grant tables.  See also connection-access.

   * If you are able to connect to the MySQL server, but get an 'Access
     denied' message whenever you issue a 'SELECT ... INTO OUTFILE'
     or 'LOAD DATA INFILE'.
     statement, your row in the 'user' table does not have the 'FILE'
     privilege enabled.

   * If you change the grant tables directly (for example, by using
     'INSERT', 'UPDATE', or 'DELETE'
     statements) and your changes seem to be ignored, remember
     that you must execute a 'FLUSH PRIVILEGES' statement or a
     'mysqladmin flush-privileges' command to cause the
     server to reload the privilege tables.  Otherwise, your changes
     have no effect until the next time the server is restarted.
     Remember that after you change the 'root' password with an
     'UPDATE' statement, you will not need to specify the new
     password until after you flush the privileges, because the server
     will not know you've changed the password yet!

   * If your privileges seem to have changed in the middle of a session,
     it may be that a MySQL administrator has changed them.  Reloading
     the grant tables affects new client connections, but it also
     affects existing connections as indicated in
     privilege-changes.

   * If you have access problems with a Perl, PHP, Python, or ODBC
     program, try to connect to the server with 'mysql -u USER_NAME
     DB_NAME' or 'mysql -u USER_NAME -pYOUR_PASS DB_NAME'.  If you are
     able to connect using the 'mysql' client, the problem
     lies with your program, not with the access privileges.  (There is
     no space between '-p' and the password; you can also use the
     '--password=YOUR_PASS' syntax to specify the password.  If you use
     the '-p' or '--password' option with no password value, MySQL
     prompts you for the password.)

   * For testing purposes, start the 'mysqld' server with
     the '--skip-grant-tables' option.  Then you can change the MySQL
     grant tables and use the 'SHOW GRANTS'.
     statement to check whether your modifications have the desired
     effect.  When you are satisfied with your changes, execute
     'mysqladmin flush-privileges' to tell the
     'mysqld' server to reload the privileges.  This enables
     you to begin using the new grant table contents without stopping
     and restarting the server.

   * If everything else fails, start the 'mysqld' server
     with a debugging option (for example, '--debug=d,general,query').
     This prints host and user information about attempted connections,
     as well as information about each command issued.  See
     dbug-package.

   * If you have any other problems with the MySQL grant tables and feel
     you must post the problem to the mailing list, always provide a
     dump of the MySQL grant tables.  You can dump the tables with the
     'mysqldump mysql' command.  To file a bug report,
     see the instructions at bug-reports.  In some cases, you
     may need to restart 'mysqld' with
     '--skip-grant-tables' to run 'mysqldump'.

6.3 MySQL User Account Management
=================================

This section describes how to set up accounts for clients of your MySQL
server.  It discusses the following topics:

   * The meaning of account names and passwords as used in MySQL and how
     that compares to names and passwords used by your operating system

   * How to set up new accounts and remove existing accounts

   * How to change passwords

   * Guidelines for using passwords securely

See also account-management-sql, which describes the syntax and
use for all user-management SQL statements.

6.3.1 User Names and Passwords
------------------------------

MySQL stores accounts in the 'user' table of the 'mysql' system
database.  An account is defined in terms of a user name and the client
host or hosts from which the user can connect to the server.  For
information about account representation in the 'user' table, see
grant-tables.

The account may also have a password.  MySQL supports authentication
plugins, so it is possible that an account authenticates using some
external authentication method.  See pluggable-authentication.

There are several distinctions between the way user names and passwords
are used by MySQL and your operating system:

   * User names, as used by MySQL for authentication purposes, have
     nothing to do with user names (login names) as used by Windows or
     Unix.  On Unix, most MySQL clients by default try to log in using
     the current Unix user name as the MySQL user name, but that is for
     convenience only.  The default can be overridden easily, because
     client programs permit any user name to be specified with a '-u' or
     '--user' option.  This means that anyone can attempt to connect to
     the server using any user name, so you cannot make a database
     secure in any way unless all MySQL accounts have passwords.  Anyone
     who specifies a user name for an account that has no password is
     able to connect successfully to the server.

   * MySQL user names can be up to 32 characters long Operating system
     user names may be of a different maximum length.  For example, Unix
     user names typically are limited to eight characters.

     *Warning*:

     The limit on MySQL user name length is hardcoded in MySQL servers
     and clients, and trying to circumvent it by modifying the
     definitions of the tables in the 'mysql' database _does not work_.

     You should never alter the structure of tables in the 'mysql'
     database in any manner whatsoever except by means of the procedure
     that is described in mysql-upgrade.  Attempting to redefine
     MySQL's system tables in any other fashion results in undefined
     (and unsupported!)  behavior.  The server is free to ignore rows
     that become malformed as a result of such modifications.

   * To authenticate client connections for accounts that use MySQL
     native authentication (implemented by the 'mysql_native_password'
     authentication plugin), the server uses passwords stored in the
     'user' table.  These passwords are distinct from passwords for
     logging in to your operating system.  There is no necessary
     connection between the 'external' password you use to log in to a
     Windows or Unix machine and the password you use to access the
     MySQL server on that machine.

     If the server authenticates a client using some other plugin, the
     authentication method that the plugin implements may or may not use
     a password stored in the 'user' table.  In this case, it is
     possible that an external password is also used to authenticate to
     the MySQL server.

   * Passwords stored in the 'user' table are encrypted using
     plugin-specific algorithms.  For information about MySQL native
     password hashing, see password-hashing.

   * If the user name and password contain only ASCII characters, it is
     possible to connect to the server regardless of character set
     settings.  To connect when the user name or password contain
     non-ASCII characters, the client should call the
     'mysql_options()'. C API function with the
     'MYSQL_SET_CHARSET_NAME' option and appropriate character set name
     as arguments.  This causes authentication to take place using the
     specified character set.  Otherwise, authentication will fail
     unless the server default character set is the same as the encoding
     in the authentication defaults.

     Standard MySQL client programs support a '--default-character-set'
     option that causes 'mysql_options()' to be
     called as just described.  In addition, character set autodetection
     is supported as described in charset-connection.  For
     programs that use a connector that is not based on the C API, the
     connector may provide an equivalent to 'mysql_options()'
     that can be used instead.  Check the connector
     documentation.

     The preceding notes do not apply for 'ucs2', 'utf16', and 'utf32',
     which are not permitted as client character sets.

The MySQL installation process populates the grant tables with an
initial 'root' account, as described in default-privileges,
which also discusses how to assign passwords to it.  Thereafter, you
normally set up, modify, and remove MySQL accounts using statements such
as 'CREATE USER', 'DROP USER',
'GRANT', and 'REVOKE'.  See
account-management-sql.

To connect to a MySQL server with a command-line client, specify user
name and password options as necessary for the account that you want to
use:

     shell> mysql --user=finley --password DB_NAME

If you prefer short options, the command looks like this:

     shell> mysql -u finley -p DB_NAME

If you omit the password value following the '--password' or '-p' option
on the command line (as just shown), the client prompts for one.
Alternatively, the password can be specified on the command line:

     shell> mysql --user=finley --password=PASSWORD DB_NAME
     shell> mysql -u finley -pPASSWORD DB_NAME

If you use the '-p' option, there must be _no space_ between '-p' and
the following password value.

Specifying a password on the command line should be considered insecure.
See password-security-user.  You can use an option file or a
login path file to avoid giving the password on the command line.  See
option-files, and mysql-config-editor.

For additional information about specifying user names, passwords, and
other connection parameters, see connecting.

6.3.2 Adding User Accounts
--------------------------

You can create MySQL accounts two ways:

   * By using account-management statements intended for creating
     accounts and establishing their privileges, such as 'CREATE USER'
     and 'GRANT'.  These statements
     cause the server to make appropriate modifications to the
     underlying grant tables.

   * By manipulating the MySQL grant tables directly with statements
     such as 'INSERT', 'UPDATE', or
     'DELETE'.

The preferred method is to use account-management statements because
they are more concise and less error-prone than manipulating the grant
tables directly.  All such statements are described in
account-management-sql.  Direct grant table modification is
discouraged, and is not described here.  The server is free to ignore
rows that become malformed as a result of such modifications.

Another option for creating accounts is to use the GUI tool MySQL
Workbench.  Also, several third-party programs offer capabilities for
MySQL account administration.  'phpMyAdmin' is one such program.

The following examples show how to use the 'mysql' client
program to set up new accounts.  These examples assume that privileges
have been set up according to the defaults described in
default-privileges.  This means that to make changes, you must connect
to the MySQL server as the MySQL 'root' user, which has the 'CREATE
USER' privilege.

First, use the 'mysql' program to connect to the server as
the MySQL 'root' user:

     shell> mysql --user=root mysql

If you have assigned a password to the 'root' account, you must also
supply a '--password' or '-p' option.

After connecting to the server as 'root', you can add new accounts.  The
following example uses 'CREATE USER ' and
'GRANT' statements to set up four accounts:

     mysql> CREATE USER 'finley'@'localhost' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT ALL PRIVILEGES ON *.* TO 'finley'@'localhost'
         ->     WITH GRANT OPTION;
     mysql> CREATE USER 'finley'@'%' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT ALL PRIVILEGES ON *.* TO 'finley'@'%'
         ->     WITH GRANT OPTION;
     mysql> CREATE USER 'admin'@'localhost' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';
     mysql> CREATE USER 'dummy'@'localhost';

The accounts created by those statements have the following properties:

   * Two accounts have a user name of 'finley'.  Both are superuser
     accounts with full privileges to do anything.  The
     ''finley'@'localhost'' account can be used only when connecting
     from the local host.  The ''finley'@'%'' account uses the ''%''
     wildcard for the host part, so it can be used to connect from any
     host.

     The ''finley'@'localhost'' account is necessary if there is an
     anonymous-user account for 'localhost'.  Without the
     ''finley'@'localhost'' account, that anonymous-user account takes
     precedence when 'finley' connects from the local host and 'finley'
     is treated as an anonymous user.  The reason for this is that the
     anonymous-user account has a more specific 'Host' column value than
     the ''finley'@'%'' account and thus comes earlier in the 'user'
     table sort order.  ('user' table sorting is discussed in
     connection-access.)

   * The ''admin'@'localhost'' account can be used only by 'admin' to
     connect from the local host.  It is granted the 'RELOAD' and
     'PROCESS' administrative privileges.  These privileges enable the
     'admin' user to execute the 'mysqladmin reload',
     'mysqladmin refresh', and 'mysqladmin flush-XXX'
     commands, as well as 'mysqladmin processlist'.
     .  No privileges are granted for
     accessing any databases.  You could add such privileges using
     'GRANT' statements.

   * The ''dummy'@'localhost'' account has no password (which is
     insecure and not recommended).  This account can be used only to
     connect from the local host.  No privileges are granted.  It is
     assumed that you will grant specific privileges to the account
     using 'GRANT' statements.

To see the privileges for an account, use 'SHOW GRANTS'.:

     mysql> SHOW GRANTS FOR 'admin'@'localhost';
     +-----------------------------------------------------+
     | Grants for admin@localhost                          |
     +-----------------------------------------------------+
     | GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' |
     +-----------------------------------------------------+

To see nonprivilege properties for an account, use 'SHOW CREATE USER'.:

     mysql> SHOW CREATE USER 'admin'@'localhost'\G
     *************************** 1. row ***************************
     CREATE USER for admin@localhost: CREATE USER 'admin'@'localhost'
     IDENTIFIED WITH 'mysql_native_password'
     AS '*67ACDEBDAB923990001F0FFB017EB8ED41861105'
     REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK

The next examples create three accounts and grant them access to
specific databases.  Each of them has a user name of 'custom' and
password of PASSWORD:

     mysql> CREATE USER 'custom'@'localhost' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON bankaccount.*
         ->     TO 'custom'@'localhost';
     mysql> CREATE USER 'custom'@'host47.example.com' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON expenses.*
         ->     TO 'custom'@'host47.example.com';
     mysql> CREATE USER 'custom'@'%.example.com' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON customer.*
         ->     TO 'custom'@'%.example.com';

The three accounts can be used as follows:

   * The first account can access the 'bankaccount' database, but only
     from the local host.

   * The second account can access the 'expenses' database, but only
     from the host 'host47.example.com'.

   * The third account can access the 'customer' database, from any host
     in the 'example.com' domain.  This account has access from all
     machines in the domain due to use of the '%' wildcard character in
     the host part of the account name.

6.3.3 Removing User Accounts
----------------------------

To remove an account, use the 'DROP USER' statement,
which is described in drop-user.  For example:

     mysql> DROP USER 'jeffrey'@'localhost';

6.3.4 Reserved User Accounts
----------------------------

One part of the MySQL installation process is data directory
initialization (see data-directory-initialization-mysqld).
During data directory initialization, MySQL creates user accounts that
should be considered reserved:

   * ''root'@'localhost': Used for administrative purposes.  This
     account has all privileges and can perform any operation.

     Strictly speaking, this account name is not reserved, in the sense
     that some installations rename the 'root' account to something else
     to avoid exposing a highly privileged account with a well-known
     name.

   * ''mysql.sys'@'localhost'': Used as the 'DEFINER' for 'sys'
     schema objects.  Use of the 'mysql.sys' account avoids
     problems that occur if a DBA renames or removes the 'root' account.
     This account is locked so that it cannot be used for client
     connections.

   * ''mysql.session'@'localhost'': Used internally by plugins to access
     the server.  This account is locked so that it cannot be used for
     client connections.

6.3.5 Setting Account Resource Limits
-------------------------------------

One means of restricting client use of MySQL server resources is to set
the global 'max_user_connections' system variable to a nonzero value.
This limits the number of simultaneous connections that can be made by
any given account, but places no limits on what a client can do once
connected.  In addition, setting 'max_user_connections' does not enable
management of individual accounts.  Both types of control are of
interest to MySQL administrators.

To address such concerns, MySQL permits limits for individual accounts
on use of these server resources:

   * The number of queries an account can issue per hour

   * The number of updates an account can issue per hour

   * The number of times an account can connect to the server per hour

   * The number of simultaneous connections to the server by an account

Any statement that a client can issue counts against the query limit,
unless its results are served from the query cache.  Only statements
that modify databases or tables count against the update limit.

An 'account' in this context corresponds to a row in the 'mysql.user'
table.  That is, a connection is assessed against the 'User' and 'Host'
values in the 'user' table row that applies to the connection.  For
example, an account ''usera'@'%.example.com'' corresponds to a row in
the 'user' table that has 'User' and 'Host' values of 'usera' and
'%.example.com', to permit 'usera' to connect from any host in the
'example.com' domain.  In this case, the server applies resource limits
in this row collectively to all connections by 'usera' from any host in
the 'example.com' domain because all such connections use the same
account.

Before MySQL 5.0, an 'account' was assessed against the actual host from
which a user connects.  This older method of accounting may be selected
by starting the server with the '--old-style-user-limits' option.  In
this case, if 'usera' connects simultaneously from 'host1.example.com'
and 'host2.example.com', the server applies the account resource limits
separately to each connection.  If 'usera' connects again from
'host1.example.com', the server applies the limits for that connection
together with the existing connection from that host.

To establish resource limits for an account at account-creation time,
use the 'CREATE USER' statement.  To modify the
limits for an existing account, use 'ALTER USER'.
Provide a 'WITH' clause that names each resource to be limited.  The
default value for each limit is zero (no limit).  For example, to create
a new account that can access the 'customer' database, but only in a
limited fashion, issue these statements:

     mysql> CREATE USER 'francis'@'localhost' IDENTIFIED BY 'frank'
         ->     WITH MAX_QUERIES_PER_HOUR 20
         ->          MAX_UPDATES_PER_HOUR 10
         ->          MAX_CONNECTIONS_PER_HOUR 5
         ->          MAX_USER_CONNECTIONS 2;

The limit types need not all be named in the 'WITH' clause, but those
named can be present in any order.  The value for each per-hour limit
should be an integer representing a count per hour.  For
'MAX_USER_CONNECTIONS', the limit is an integer representing the maximum
number of simultaneous connections by the account.  If this limit is set
to zero, the global 'max_user_connections' system variable value
determines the number of simultaneous connections.  If
'max_user_connections' is also zero, there is no limit for the account.

To modify limits for an existing account, use an 'ALTER USER'
statement.  The following statement changes the query limit
for 'francis' to 100:

     mysql> ALTER USER 'francis'@'localhost' WITH MAX_QUERIES_PER_HOUR 100;

The statement modifies only the limit value specified and leaves the
account otherwise unchanged.

To remove a limit, set its value to zero.  For example, to remove the
limit on how many times per hour 'francis' can connect, use this
statement:

     mysql> ALTER USER 'francis'@'localhost' WITH MAX_CONNECTIONS_PER_HOUR 0;

As mentioned previously, the simultaneous-connection limit for an
account is determined from the 'MAX_USER_CONNECTIONS' limit and the
'max_user_connections' system variable.  Suppose that the global
'max_user_connections' value is 10 and three accounts have individual
resource limits specified as follows:

     ALTER USER 'user1'@'localhost' WITH MAX_USER_CONNECTIONS 0;
     ALTER USER 'user2'@'localhost' WITH MAX_USER_CONNECTIONS 5;
     ALTER USER 'user3'@'localhost' WITH MAX_USER_CONNECTIONS 20;

'user1' has a connection limit of 10 (the global 'max_user_connections'
value) because it has a 'MAX_USER_CONNECTIONS' limit of zero.  'user2'
and 'user3' have connection limits of 5 and 20, respectively, because
they have nonzero 'MAX_USER_CONNECTIONS' limits.

The server stores resource limits for an account in the 'user' table row
corresponding to the account.  The 'max_questions', 'max_updates', and
'max_connections' columns store the per-hour limits, and the
'max_user_connections' column stores the 'MAX_USER_CONNECTIONS' limit.
(See grant-tables.)

Resource-use counting takes place when any account has a nonzero limit
placed on its use of any of the resources.

As the server runs, it counts the number of times each account uses
resources.  If an account reaches its limit on number of connections
within the last hour, the server rejects further connections for the
account until that hour is up.  Similarly, if the account reaches its
limit on the number of queries or updates, the server rejects further
queries or updates until the hour is up.  In all such cases, the server
issues appropriate error messages.

Resource counting occurs per account, not per client.  For example, if
your account has a query limit of 50, you cannot increase your limit to
100 by making two simultaneous client connections to the server.
Queries issued on both connections are counted together.

The current per-hour resource-use counts can be reset globally for all
accounts, or individually for a given account:

   * To reset the current counts to zero for all accounts, issue a
     'FLUSH USER_RESOURCES' statement.  The counts also can be reset by
     reloading the grant tables (for example, with a 'FLUSH PRIVILEGES'
     statement or a 'mysqladmin reload' command).

   * The counts for an individual account can be reset to zero by
     setting any of its limits again.  Specify a limit value equal to
     the value currently assigned to the account.

Per-hour counter resets do not affect the 'MAX_USER_CONNECTIONS' limit.

All counts begin at zero when the server starts.  Counts do not carry
over through server restarts.

For the 'MAX_USER_CONNECTIONS' limit, an edge case can occur if the
account currently has open the maximum number of connections permitted
to it: A disconnect followed quickly by a connect can result in an error
('ER_TOO_MANY_USER_CONNECTIONS' or 'ER_USER_LIMIT_REACHED') if the
server has not fully processed the disconnect by the time the connect
occurs.  When the server finishes disconnect processing, another
connection will once more be permitted.

6.3.6 Assigning Account Passwords
---------------------------------

Required credentials for clients that connect to the MySQL server can
include a password.  This section describes how to assign passwords for
MySQL accounts.

MySQL stores credentials in the 'user' table in the 'mysql' system
database.  Operations that assign or modify passwords are permitted only
to users with the 'CREATE USER' privilege, or, alternatively, privileges
for the 'mysql' database ('INSERT' privilege to create new accounts,
'UPDATE' privilege to modify existing accounts).  If the 'read_only'
system variable is enabled, use of account-modification statements such
as 'CREATE USER' or 'ALTER USER'.
additionally requires the 'SUPER' privilege.

The discussion here summarizes syntax only for the most common
password-assignment statements.  For complete details on other
possibilities, see create-user, alter-user,
grant, and set-password.

MySQL uses plugins to perform client authentication; see
pluggable-authentication.  In password-assigning statements, the
authentication plugin associated with an account performs any hashing
required of a cleartext password specified.  This enables MySQL to
obfuscate passwords prior to storing them in the 'mysql.user' table.
For the statements described here, MySQL automatically hashes the
password specified.  There are also syntaxes for 'CREATE USER'
and 'ALTER USER' that permit hashed
values to be specified literally.  For details, see the descriptions of
those statements.

To assign a password when you create a new account, use 'CREATE USER'
and include an 'IDENTIFIED BY' clause:

     CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'PASSWORD';

'CREATE USER' also supports syntax for specifying
the account authentication plugin.  See create-user.

To assign or change a password for an existing account, use the
'ALTER USER' statement with an 'IDENTIFIED BY' clause:

     ALTER USER 'jeffrey'@'localhost' IDENTIFIED BY 'PASSWORD';

If you are not connected as an anonymous user, you can change your own
password without naming your own account literally:

     ALTER USER USER() IDENTIFIED BY 'PASSWORD';

To change an account password from the command line, use the
'mysqladmin' command:

     mysqladmin -u USER_NAME -h HOST_NAME password "PASSWORD"

The account for which this command sets the password is the one with a
'mysql.user' table row that matches USER_NAME in the 'User' column and
the client host _from which you connect_ in the 'Host' column.

*Warning*:

Setting a password using 'mysqladmin' should be
considered _insecure_.  On some systems, your password becomes visible
to system status programs such as 'ps' that may be invoked by other
users to display command lines.  MySQL clients typically overwrite the
command-line password argument with zeros during their initialization
sequence.  However, there is still a brief interval during which the
value is visible.  Also, on some systems this overwriting strategy is
ineffective and the password remains visible to 'ps'.  (SystemV Unix
systems and perhaps others are subject to this problem.)

If you are using MySQL Replication, be aware that, currently, a password
used by a replication slave as part of a 'CHANGE MASTER TO'
statement is effectively limited to 32 characters in
length; if the password is longer, any excess characters are truncated.
This is not due to any limit imposed by the MySQL Server generally, but
rather is an issue specific to MySQL Replication.  (For more
information, see Bug #43439.)

6.3.7 Password Management
-------------------------

MySQL enables database administrators to expire account passwords
manually, and to establish a policy for automatic password expiration.
It is possible to establish expiration policy globally, as well as on a
per-account basis.  These capabilities apply to accounts that use a
MySQL built-in authentication plugin ('mysql_native_password' or
'sha256_password').  For accounts that use plugins that perform
authentication against an external credential system, password
expiration must be handled externally as well.

To expire an account password manually, use the 'ALTER USER'
statement:

     ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE;

This operation marks the password expired in the corresponding
'mysql.user' table row.

Password expiration according to policy is automatic and is based on
password age, which for a given account is assessed from the date and
time of its most recent password change.  The 'mysql.user' table
indicates for each account when its password was last changed, and the
server automatically treats the password as expired at client connection
time if its age is greater than its permitted lifetime.  This works with
no explicit manual password expiration.

To establish automatic password-expiration policy globally, use the
'default_password_lifetime' system variable.  Its default value is 0,
which disables automatic password expiration.  If the value of
'default_password_lifetime' is a positive integer N, it indicates the
permitted password lifetime, such that passwords must be changed every N
days.

*Note*:

Prior to 5.7.11, the default 'default_password_lifetime' value is 360
(passwords must be changed approximately once per year).  For such
versions, be aware that, if you make no changes to the
'default_password_lifetime' variable or to individual user accounts,
each user password expires after 360 days and the account starts running
in restricted mode.  Clients that connect to the server using the
account then get an error indicating that the password must be changed:
'ERROR 1820 (HY000): You must reset your password using ALTER USER
statement before executing this statement.'

However, this is easy to miss for clients that automatically connect to
the server, such as connections made from scripts.  To avoid having such
clients suddenly stop working due to a password expiring, make sure to
change the password expiration settings for those clients, like this:

     ALTER USER 'script'@'localhost' PASSWORD EXPIRE NEVER

Alternatively, set the 'default_password_lifetime' variable to '0', thus
disabling automatic password expiration for all users.

Examples:

   * To establish a global policy that passwords have a lifetime of
     approximately six months, start the server with these lines in a
     server 'my.cnf' file:

          [mysqld]
          default_password_lifetime=180

   * To establish a global policy such that passwords never expire, set
     'default_password_lifetime' to 0:

          [mysqld]
          default_password_lifetime=0

   * 'default_password_lifetime' can also be changed at runtime:

          SET GLOBAL default_password_lifetime = 180;
          SET GLOBAL default_password_lifetime = 0;

To establish password-expiration policy for individual accounts, use the
'PASSWORD EXPIRE' options of the 'CREATE USER' and
'ALTER USER' statements.  See create-user,
and alter-user.

Example account-specific expiration statements:

   * Require the password to be changed every 90 days:

          CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE INTERVAL 90 DAY;
          ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE INTERVAL 90 DAY;

   * Disable password expiration:

          CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE NEVER;
          ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE NEVER;

   * Defer to the global expiration policy:

          CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE DEFAULT;
          ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE DEFAULT;

When a client successfully connects, the server determines whether the
account password has expired:

   * The server checks whether the password has been manually expired.

   * Otherwise, the server checks whether the password age is greater
     than its permitted lifetime according to the automatic password
     expiration policy.  If so, the server considers the password
     expired.

If the password is expired (whether manually or automatically), the
server either disconnects the client or restricts the operations
permitted to it (see expired-password-handling).  Operations
performed by a restricted client result in an error until the user
establishes a new account password:

     mysql> SELECT 1;
     ERROR 1820 (HY000): You must reset your password using ALTER USER
     statement before executing this statement.

     mysql> ALTER USER USER() IDENTIFIED BY 'PASSWORD';
     Query OK, 0 rows affected (0.01 sec)

     mysql> SELECT 1;
     +---+
     | 1 |
     +---+
     | 1 |
     +---+
     1 row in set (0.00 sec)

This restricted mode of operation permits 'SET'.
statements, which is useful before MySQL 5.7.6 if 'SET PASSWORD'
must be used instead of 'ALTER USER'.
and the account password has a hashing format that requires
'old_passwords' to be set to a value different from its default.

After the client resets the password, the server restores normal access
for the session, as well as for subsequent connections that use the
account.  It is also possible for an administrative user to reset the
account password, but any existing restricted sessions for that account
remain restricted.  A client using the account must disconnect and
reconnect before statements can be executed successfully.

*Note*:

It is possible to 'reset' a password by setting it to its current value.
As a matter of good policy, it is preferable to choose a different
password.

6.3.8 Password Expiration and Sandbox Mode
------------------------------------------

MySQL provides password-expiration capability, which enables database
administrators to require that users reset their password.  Passwords
can be expired manually, and on the basis of a policy for automatic
expiration (see password-management).

For each connection that uses an account with an expired password, the
server either disconnects the client or restricts the client to 'sandbox
mode,' in which the server permits to the client only those operations
necessary to reset the expired password.  Which action is taken by the
server depends on both client and server settings, as discussed later.

If the server disconnects the client, it returns an
'ER_MUST_CHANGE_PASSWORD_LOGIN' error:

     shell> mysql -u myuser -p
     Password: ******
     ERROR 1862 (HY000): Your password has expired. To log in you must
     change it using a client that supports expired passwords.

If the server restricts the client to sandbox mode, these operations are
permitted within the client session:

   * The client can reset the account password with 'ALTER USER'
     or 'SET PASSWORD'.  After the
     password has been reset, the server restores normal access for the
     session, as well as for subsequent connections that use the
     account.

     It is possible to 'reset' a password by setting it to its current
     value.  As a matter of good policy, it is preferable to choose a
     different password.

   * The client can use 'SET' statements, which is
     useful before MySQL 5.7.6 if 'SET PASSWORD'.
     must be used instead of 'ALTER USER' and the
     account password has a hashing format that requires 'old_passwords'
     to be set to a value different from its default.

For any operation not permitted within the session, the server returns
an 'ER_MUST_CHANGE_PASSWORD' error:

     mysql> USE performance_schema;
     ERROR 1820 (HY000): You must reset your password using ALTER USER
     statement before executing this statement.

     mysql> SELECT 1;
     ERROR 1820 (HY000): You must reset your password using ALTER USER
     statement before executing this statement.

That is what normally happens for interactive invocations of the
'mysql' client because by default such invocations are put in
sandbox mode.  To clear the error and resume normal functioning, select
a new password.

For noninteractive invocations of the 'mysql' client (for
example, in batch mode), the server normally disconnects the client if
the password is expired.  To permit noninteractive 'mysql'.
invocations to stay connected so that the password can be changed (using
the statements just described), add the '--connect-expired-password'
option to the 'mysql' command.

As mentioned previously, whether the server disconnects an
expired-password client or restricts it to sandbox mode depends on a
combination of client and server settings.  The following discussion
describes the relevant settings and how they interact.  The discussion
applies only for accounts with expired passwords.  If a client connects
using a nonexpired password, the server handles the client normally.

On the client side, a given client indicates whether it can handle
sandbox mode for expired passwords.  For clients that use the C client
library, there are two ways to do this:

   * Pass the 'MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS' flag to
     'mysql_options()' prior to connecting:

          arg = 1;
          result = mysql_options(mysql,
                                 MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS,
                                 &arg);

     The 'mysql' client enables
     'MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS' if invoked interactively
     or the '--connect-expired-password' option is given.

   * Pass the 'CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS' flag to
     'mysql_real_connect()' at connection time:

          mysql = mysql_real_connect(mysql,
                                     host, user, password, db,
                                     port, unix_socket,
                                     CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS);

Other MySQL Connectors have their own conventions for indicating
readiness to handle sandbox mode.  See the documentation for the
Connector in which you are interested.

On the server side, if a client indicates that it can handle expired
passwords, the server puts it in sandbox mode.

If a client does not indicate that it can handle expired passwords (or
uses an older version of the client library that cannot so indicate),
the server action depends on the value of the
'disconnect_on_expired_password' system variable:

   * If 'disconnect_on_expired_password' is enabled (the default), the
     server disconnects the client with an
     'ER_MUST_CHANGE_PASSWORD_LOGIN' error.

   * If 'disconnect_on_expired_password' is disabled, the server puts
     the client in sandbox mode.

6.3.9 Pluggable Authentication
------------------------------

When a client connects to the MySQL server, the server uses the user
name provided by the client and the client host to select the
appropriate account row from the 'mysql.user' system table.  The server
then authenticates the client, determining from the account row which
authentication plugin applies to the client:

   * If the server cannot find the plugin, an error occurs and the
     connection attempt is rejected.

   * Otherwise, the server invokes that plugin to authenticate the user,
     and the plugin returns a status to the server indicating whether
     the user provided the correct password and is permitted to connect.

Pluggable authentication enables these important capabilities:

   * Choice of authentication methods

     Pluggable authentication makes it easy for DBAs to choose and
     change the authentication method used for individual MySQL
     accounts.

   * External authentication

     Pluggable authentication makes it possible for clients to connect
     to the MySQL server with credentials appropriate for authentication
     methods that store credentials elsewhere than in the 'mysql.user'
     system table.  For example, plugins can be created to use external
     authentication methods such as PAM, Windows login IDs, LDAP, or
     Kerberos.

   * Proxy users:

     If a user is permitted to connect, an authentication plugin can
     return to the server a user name different from the name of the
     connecting user, to indicate that the connecting user is a proxy
     for another user (the proxied user).  While the connection lasts,
     the proxy user is treated, for purposes of access control, as
     having the privileges of the proxied user.  In effect, one user
     impersonates another.  For more information, see
     proxy-users.

*Note*:

If you start the server with the '--skip-grant-tables' option,
authentication plugins are not used even if loaded because the server
performs no client authentication and permits any client to connect.
Because this is insecure, you might want to use '--skip-grant-tables' in
conjunction with '--skip-networking' to prevent remote clients from
connecting.

   * pluggable-authentication-available-plugins

   * pluggable-authentication-usage

*Available Authentication Plugins*

MySQL 5.7 provides these authentication plugins:

   * Plugins that perform native authentication; that is, authentication
     based on the password hashing methods in use from before the
     introduction of pluggable authentication in MySQL. The
     'mysql_native_password' plugin implements authentication based on
     the native password hashing method.  The 'mysql_old_password'
     plugin implements native authentication based on the older
     (pre-4.1) password hashing method (and is deprecated and removed in
     MySQL 5.7.5).  See native-pluggable-authentication, and
     old-native-pluggable-authentication.

   * A plugin that performs authentication using SHA-256 password
     hashing.  This is stronger encryption than that available with
     native authentication.  See
     sha256-pluggable-authentication.

   * A client-side plugin that sends the password to the server without
     hashing or encryption.  This plugin is used in conjunction with
     server-side plugins that require access to the password exactly as
     provided by the client user.  See
     cleartext-pluggable-authentication.

   * A plugin that performs external authentication using PAM (Pluggable
     Authentication Modules), enabling MySQL Server to use PAM to
     authenticate MySQL users.  This plugin supports proxy users as
     well.  See pam-pluggable-authentication.

   * A plugin that performs external authentication on Windows, enabling
     MySQL Server to use native Windows services to authenticate client
     connections.  Users who have logged in to Windows can connect from
     MySQL client programs to the server based on the information in
     their environment without specifying an additional password.  This
     plugin supports proxy users as well.  See
     windows-pluggable-authentication.

   * Plugins that perform authentication using LDAP (Lightweight
     Directory Access Protocol) to authenticate MySQL users by accessing
     directory services such as X.500.  These plugins support proxy
     users as well.  See ldap-pluggable-authentication.

   * A plugin that prevents all client connections to any account that
     uses it.  Use cases for this plugin include proxied accounts that
     should never permit direct login but are accessed only through
     proxy accounts and accounts that must be able to execute stored
     programs and views with elevated privileges without exposing those
     privileges to ordinary users.  See
     no-login-pluggable-authentication.

   * A plugin that authenticates clients that connect from the local
     host through the Unix socket file.  See
     socket-pluggable-authentication.

   * A test plugin that checks account credentials and logs success or
     failure to the server error log.  This plugin is intended for
     testing and development purposes, and as an example of how to write
     an authentication plugin.  See
     test-pluggable-authentication.

*Note*:

For information about current restrictions on the use of pluggable
authentication, including which connectors support which plugins, see
pluggable-authentication-restrictions.

Third-party connector developers should read that section to determine
the extent to which a connector can take advantage of pluggable
authentication capabilities and what steps to take to become more
compliant.

If you are interested in writing your own authentication plugins, see
writing-authentication-plugins.

*Authentication Plugin Usage*

This section provides general instructions for installing and using
authentication plugins.  For instructions specific to a given plugin,
see the section that describes that plugin under
authentication-plugins.

In general, pluggable authentication uses a pair of corresponding
plugins on the server and client sides, so you use a given
authentication method like this:

   * If necessary, install the plugin library or libraries containing
     the appropriate plugins.  On the server host, install the library
     containing the server-side plugin, so that the server can use it to
     authenticate client connections.  Similarly, on each client host,
     install the library containing the client-side plugin for use by
     client programs.  Authentication plugins that are built in need not
     be installed.

   * For each MySQL account that you create, specify the appropriate
     server-side plugin to use for authentication.  If the account is to
     use the default authentication plugin, the account-creation
     statement need not specify the plugin explicitly.  The
     'default_authentication_plugin' system variable configures the
     default authentication plugin.

   * When a client connects, the server-side plugin tells the client
     program which client-side plugin to use for authentication.

In the case that an account uses an authentication method that is the
default for both the server and the client program, the server need not
communicate to the client which client-side plugin to use, and a round
trip in client/server negotiation can be avoided.  This is true for
accounts that use native MySQL authentication.

For standard MySQL clients such as 'mysql' and
'mysqladmin', the '--default-auth=PLUGIN_NAME' option can be
specified on the command line as a hint about which client-side plugin
the program can expect to use, although the server will override this if
the server-side plugin associated with the user account requires a
different client-side plugin.

If the client program does not find the client-side plugin library file,
specify a '--plugin-dir=DIR_NAME' option to indicate the plugin library
directory location.

6.3.10 Proxy Users
------------------

The MySQL server authenticates client connections using authentication
plugins.  The plugin that authenticates a given connection may request
that the connecting (external) user be treated as a different user for
privilege-checking purposes.  This enables the external user to be a
proxy for the second user; that is, to assume the privileges of the
second user:

   * The external user is a 'proxy user' (a user who can impersonate or
     become known as another user).

   * The second user is a 'proxied user' (a user whose identity and
     privileges can be assumed by a proxy user).

This section describes how the proxy user capability works.  For general
information about authentication plugins, see
pluggable-authentication.  For information about specific plugins, see
authentication-plugins.  For information about writing
authentication plugins that support proxy users, see
writing-authentication-plugins-proxy-users.

   * proxy-users-support-requirements

   * proxy-users-granting-proxy-privilege

   * default-proxy-users

   * proxy-users-conflicts

   * proxy-users-server-user-mapping

   * proxy-users-system-variables

*Requirements for Proxy User Support*

For proxying to occur for a given authentication plugin, these
conditions must be satisfied:

   * Proxying must be supported, either by the plugin itself, or by the
     MySQL server on behalf of the plugin.  In the latter case, server
     support may need to be enabled explicitly; see
     proxy-users-server-user-mapping.

   * The proxy user account must be set up to be authenticated by the
     plugin.  Use the 'CREATE USER' statement to
     associate an account with an authentication plugin, or 'ALTER USER'
     to change its plugin.

   * The proxied user account must be created and granted the privileges
     to be assumed by the proxy user.  Use the 'CREATE USER'
     and 'GRANT' statements for this.

   * The proxy user account must have the 'PROXY' privilege for the
     proxied account.  Use the 'GRANT' statement for this.

   * For a client connecting to the proxy account to be treated as a
     proxy user, the authentication plugin must return a user name
     different from the client user name, to indicate the user name of
     the proxied account that defines the privileges to be assumed by
     the proxy user.

     Alternatively, for plugins that are provided proxy mapping by the
     server, the proxied user is determined from the 'PROXY' privilege
     held by the proxy user.

The proxy mechanism permits mapping only the client user name to the
proxied user name.  There is no provision for mapping host names.  When
a connecting client matches a proxy account, the server attempts to find
a match for a proxied account using the user name returned by the
authentication plugin and the host name of the proxy account.

Consider the following account definitions:

     -- create proxy account
     CREATE USER 'employee_ext'@'localhost'
       IDENTIFIED WITH my_auth_plugin AS 'my_auth_string';

     -- create proxied account and grant its privileges
     CREATE USER 'employee'@'localhost'
       IDENTIFIED BY 'employee_pass';
     GRANT ALL ON employees.*
       TO 'employee'@'localhost';

     -- grant PROXY privilege to proxy account for proxied account
     GRANT PROXY
       ON 'employee'@'localhost'
       TO 'employee_ext'@'localhost';

When a client connects as 'employee_ext' from the local host, MySQL uses
the plugin named 'my_auth_plugin' to perform authentication.  Suppose
that 'my_auth_plugin' returns a user name of 'employee' to the server,
based on the content of ''my_auth_string'' and perhaps by consulting
some external authentication system.  The name 'employee' differs from
'employee_ext', so returning 'employee' serves as a request to the
server to treat the 'employee_ext' client, for purposes of privilege
checking, as the 'employee' local user.

In this case, 'employee_ext' is the proxy user and 'employee' is the
proxied user.

The server verifies that proxy authentication for 'employee' is possible
for the 'employee_ext' user by checking whether 'employee_ext' (the
proxy user) has the 'PROXY' privilege for 'employee' (the proxied user).
If this privilege has not been granted, an error occurs.  Otherwise,
'employee_ext' assumes the privileges of 'employee'.  The server checks
statements executed during the client session by 'employee_ext' against
the privileges granted to 'employee'.  In this case, 'employee_ext' can
access tables in the 'employees' database.

When proxying occurs, the 'USER()' and 'CURRENT_USER()' functions can be
used to see the difference between the connecting user (the proxy user)
and the account whose privileges apply during the current session (the
proxied user).  For the example just described, those functions return
these values:

     mysql> SELECT USER(), CURRENT_USER();
     +------------------------+--------------------+
     | USER()                 | CURRENT_USER()     |
     +------------------------+--------------------+
     | employee_ext@localhost | employee@localhost |
     +------------------------+--------------------+

In the 'CREATE USER' statement that creates the
proxy user account, the 'IDENTIFIED WITH' clause that names the
authentication plugin is optionally followed by an 'AS 'AUTH_STRING''
clause specifying a string that the server passes to the plugin when the
user connects.  If present, the string provides information that helps
the plugin determine how to map the external client user name to a
proxied user name.  It is up to each plugin whether it requires the 'AS'
clause.  If so, the format of the authentication string depends on how
the plugin intends to use it.  Consult the documentation for a given
plugin for information about the authentication string values it
accepts.

*Granting the Proxy Privilege*

The 'PROXY' privilege is needed to enable an external user to connect as
and have the privileges of another user.  To grant this privilege, use
the 'GRANT' statement.  For example:

     GRANT PROXY ON 'PROXIED_USER' TO 'PROXY_USER';

The statement creates a row in the 'mysql.proxies_priv' grant table.

At connection time, PROXY_USER must represent a valid externally
authenticated MySQL user, and PROXIED_USER must represent a valid
locally authenticated user.  Otherwise, the connection attempt fails.

The corresponding 'REVOKE' syntax is:

     REVOKE PROXY ON 'PROXIED_USER' FROM 'PROXY_USER';

MySQL 'GRANT' and 'REVOKE' syntax
extensions work as usual.  For example:

     GRANT PROXY ON 'a' TO 'b', 'c', 'd';
     GRANT PROXY ON 'a' TO 'd' WITH GRANT OPTION;
     GRANT PROXY ON 'a' TO ''@'';
     REVOKE PROXY ON 'a' FROM 'b', 'c', 'd';

The 'PROXY' privilege can be granted in these cases:

   * By a user that has 'GRANT PROXY ... WITH GRANT OPTION' for
     PROXIED_USER.

   * By PROXIED_USER for itself: The value of 'USER()' must exactly
     match 'CURRENT_USER()' and PROXIED_USER, for both the user name and
     host name parts of the account name.

The initial 'root' account created during MySQL installation has the
'PROXY ... WITH GRANT OPTION' privilege for '''@''', that is, for all
users and all hosts.  This enables 'root' to set up proxy users, as well
as to delegate to other accounts the authority to set up proxy users.
For example, 'root' can do this:

     CREATE USER 'admin'@'localhost' IDENTIFIED BY 'test';
     GRANT PROXY ON ''@'' TO 'admin'@'localhost' WITH GRANT OPTION;

Those statements create an 'admin' user that can manage all 'GRANT
PROXY' mappings.  For example, 'admin' can do this:

     GRANT PROXY ON sally TO joe;

*Default Proxy Users*

To specify that some or all users should connect using a given
authentication plugin, create a 'blank' MySQL account ('''@'''),
associate it with that plugin, and let the plugin return the real
authenticated user name (if different from the blank user).  For
example, suppose that there exists a plugin named 'ldap_auth' that
implements LDAP authentication and maps connecting users onto either a
developer or manager account.  To set up proxying of users onto these
accounts, use the following statements:

     -- create default proxy account
     CREATE USER ''@'' IDENTIFIED WITH ldap_auth AS 'O=Oracle, OU=MySQL';

     -- create proxied accounts
     CREATE USER 'developer'@'localhost' IDENTIFIED BY 'developer_pass';
     CREATE USER 'manager'@'localhost' IDENTIFIED BY 'manager_pass';

     -- grant PROXY privilege to default proxy account for proxied accounts
     GRANT PROXY ON 'manager'@'localhost' TO ''@'';
     GRANT PROXY ON 'developer'@'localhost' TO ''@'';

Now assume that a client connects as follows:

     shell> mysql --user=myuser --password ...
     Enter password: MYUSER_PASS

The server will not find 'myuser' defined as a MySQL user.  But because
there is a blank user account ('''@''') that matches the client user
name and host name, the server authenticates the client against that
account: The server invokes the 'ldap_auth' authentication plugin and
passes 'myuser' and 'myuser_pass' to it as the user name and password.

If the 'ldap_auth' plugin finds in the LDAP directory that 'myuser_pass'
is not the correct password for 'myuser', authentication fails and the
server rejects the connection.

If the password is correct and 'ldap_auth' finds that 'myuser' is a
developer, it returns the user name 'developer' to the MySQL server,
rather than 'myuser'.  Returning a user name different from the client
user name of 'myuser' signals to the server that it should treat
'myuser' as a proxy.  The server verifies that '''@''' can authenticate
as 'developer' (because that account has the 'PROXY' privilege to do so)
and accepts the connection.  The session proceeds with 'myuser' having
the privileges of 'developer', the proxied user.  (These privileges
should be set up by the DBA using 'GRANT' statements, not shown.)  The
'USER()' and 'CURRENT_USER()' functions return these values:

     mysql> SELECT USER(), CURRENT_USER();
     +------------------+---------------------+
     | USER()           | CURRENT_USER()      |
     +------------------+---------------------+
     | myuser@localhost | developer@localhost |
     +------------------+---------------------+

If the plugin instead finds in the LDAP directory that 'myuser' is a
manager, it returns 'manager' as the user name and the session proceeds
with 'myuser' having the privileges of 'manager'.

     mysql> SELECT USER(), CURRENT_USER();
     +------------------+-------------------+
     | USER()           | CURRENT_USER()    |
     +------------------+-------------------+
     | myuser@localhost | manager@localhost |
     +------------------+-------------------+

For simplicity, external authentication cannot be multilevel: Neither
the credentials for 'developer' nor those for 'manager' are taken into
account in the preceding example.  However, they are still used if a
client tries to connect and authenticate directly as the 'developer' or
'manager' account, which is why those accounts should be assigned
passwords.

*Default Proxy User and Anonymous User Conflicts*

If you intend to create a default proxy user, check for other existing
'match any user' accounts that take precedence over the default proxy
user because they can prevent that user from working as intended.

In the preceding discussion, the default proxy user account has '''' in
the host part, which matches any host.  If you set up a default proxy
user, take care to also check whether nonproxy accounts exist with the
same user part and ''%'' in the host part, because ''%'' also matches
any host, but has precedence over '''' by the rules that the server uses
to sort account rows internally (see connection-access).

Suppose that a MySQL installation includes these two accounts:

     -- create default proxy account
     CREATE USER ''@''
       IDENTIFIED WITH some_plugin AS 'some_auth_string';
     -- create anonymous account
     CREATE USER ''@'%'
       IDENTIFIED BY 'some_password';

The first account ('''@''') is intended as the default proxy user, used
to authenticate connections for users who do not otherwise match a
more-specific account.  The second account ('''@'%'') is an
anonymous-user account, which might have been created, for example, to
enable users without their own account to connect anonymously.

Both accounts have the same user part (''''), which matches any user.
And each account has a host part that matches any host.  Nevertheless,
there is a priority in account matching for connection attempts because
the matching rules sort a host of ''%'' ahead of ''''.  For accounts
that do not match any more-specific account, the server attempts to
authenticate them against '''@'%'' (the anonymous user) rather than
'''@''' (the default proxy user).  The result is that the default proxy
account is never used.

To avoid this problem, use one of the following strategies:

   * Remove the anonymous account so that it does not conflict with the
     default proxy user.  This might be a good idea anyway if you want
     to associate every connection with a named user.

   * Use a more-specific default proxy user that matches ahead of the
     anonymous user.  For example, to permit only 'localhost' proxy
     connections, use '''@'localhost'':

          CREATE USER ''@'localhost'
            IDENTIFIED WITH some_plugin AS 'some_auth_string';

     In addition, modify any 'GRANT PROXY' statements to name
     '''@'localhost'' rather than '''@''' as the proxy user.

     Be aware that this strategy prevents anonymous-user connections
     from 'localhost'.

   * Create multiple proxy users, one for local connections and one for
     'everything else' (remote connections).  This can be useful
     particularly when local users should have different privileges from
     remote users.

     Create the proxy users:

          -- create proxy user for local connections
          CREATE USER ''@'localhost'
            IDENTIFIED WITH some_plugin AS 'some_auth_string';
          -- create proxy user for remote connections
          CREATE USER ''@'%'
            IDENTIFIED WITH some_plugin AS 'some_auth_string';

     Create the proxied users:

          -- create proxied user for local connections
          CREATE USER 'developer'@'localhost'
            IDENTIFIED BY 'some_password';
          -- create proxied user for remote connections
          CREATE USER 'developer'@'%'
            IDENTIFIED BY 'some_password';

     Grant the proxy privilege to each proxy user for the corresponding
     proxied user:

          GRANT PROXY ON 'developer'@'localhost' TO ''@'localhost';
          GRANT PROXY ON 'developer'@'%' TO ''@'%';

     Finally, grant appropriate privileges to the local and remote
     proxied users (not shown).

     Assume that the 'some_plugin'/''some_auth_string'' combination
     causes 'some_plugin' to map the client user name to 'developer'.
     Local connections match the '''@'localhost'' proxy user, which maps
     to the ''developer'@'localhost'' proxied user.  Remote connections
     match the '''@'%'' proxy user, which maps to the ''developer'@'%''
     proxied user.

*Server Support for Proxy User Mapping*

Some authentication plugins implement proxy user mapping for themselves.
For certain others, the MySQL server itself can map proxy users
according to granted proxy privileges.  If the 'check_proxy_users'
system variable is enabled, the server performs proxy user mapping for
any authentication plugins that request it:

   * By default, 'check_proxy_users' is disabled, so the server performs
     no proxy user mapping even for authentication plugins that request
     it.

   * With 'check_proxy_users' enabled, it may also be necessary to
     enable plugin-specific system variables to take advantage of server
     proxy user mapping support:

        * For the 'mysql_native_password' plugin, enable
          'mysql_native_password_proxy_users'.

        * For the 'sha256_password' plugin, enable
          'sha256_password_proxy_users'.

Proxy user mapping performed by the server is subject to these
restrictions:

   * The server will not proxy to or from an anonymous user, even if the
     associated 'PROXY' privilege is granted.

   * When a single account has been granted proxy privileges for more
     than one proxied account, server proxy user mapping is
     nondeterministic.  Therefore, granting to a single account proxy
     privileges for multiple proxied accounts is discouraged.

*Proxy User System Variables*

Two system variables help trace the proxy login process:

   * 'proxy_user': This value is 'NULL' if proxying is not used.
     Otherwise, it indicates the proxy user account.  For example, if a
     client authenticates through the '''@''' proxy account, this
     variable is set as follows:

          mysql> SELECT @@proxy_user;
          +--------------+
          | @@proxy_user |
          +--------------+
          | ''@''        |
          +--------------+

   * 'external_user': Sometimes the authentication plugin may use an
     external user to authenticate to the MySQL server.  For example,
     when using Windows native authentication, a plugin that
     authenticates using the windows API does not need the login ID
     passed to it.  However, it still uses a Windows user ID to
     authenticate.  The plugin may return this external user ID (or the
     first 512 UTF-8 bytes of it) to the server using the
     'external_user' read-only session variable.  If the plugin does not
     set this variable, its value is 'NULL'.

6.3.11 User Account Locking
---------------------------

As of version 5.7.6, MySQL supports locking and unlocking user accounts
using the 'ACCOUNT LOCK' and 'ACCOUNT UNLOCK' clauses for the
'CREATE USER' and 'ALTER USER'.
statements:

   * When used with 'CREATE USER', these clauses
     specify the initial locking state for a new account.  In the
     absence of either clause, the account is created in an unlocked
     state.

   * When used with 'ALTER USER', these clauses
     specify the new locking state for an existing account.  In the
     absence of either clause, the account locking state remains
     unchanged.

Account locking state is recorded in the 'account_locked' column of the
'mysql.user' table.  The output from 'SHOW CREATE USER'
indicates whether an account is locked or unlocked.

If a client attempts to connect to a locked account, the attempt fails.
The server increments the 'Locked_connects' status variable that
indicates the number of attempts to connect to a locked account, returns
an 'ER_ACCOUNT_HAS_BEEN_LOCKED' error, and writes a message to the error
log:

     Access denied for user 'USER_NAME'@'HOST_NAME'.
     Account is locked.

Locking an account does not affect being able to connect using a proxy
user that assumes the identity of the locked account.  It also does not
affect the ability to execute stored programs or views that have a
'DEFINER' clause naming the locked account.  That is, the ability to use
a proxied account or stored programs or views is not affected by locking
the account.

The account-locking capability depends on the presence of the
'account_locked' column in the 'mysql.user' table.  For upgrades to
MySQL 5.7.6 and later from older versions, run 'mysql_upgrade'
to ensure that this column exists.  For nonupgraded
installations that have no 'account_locked' column, the server treats
all accounts as unlocked, and using the 'ACCOUNT LOCK' or 'ACCOUNT
UNLOCK' clauses produces an error.

6.3.12 SQL-Based MySQL Account Activity Auditing
------------------------------------------------

Applications can use the following guidelines to perform SQL-based
auditing that ties database activity to MySQL accounts.

MySQL accounts correspond to rows in the 'mysql.user' table.  When a
client connects successfully, the server authenticates the client to a
particular row in this table.  The 'User' and 'Host' column values in
this row uniquely identify the account and correspond to the
''USER_NAME'@'HOST_NAME'' format in which account names are written in
SQL statements.

The account used to authenticate a client determines which privileges
the client has.  Normally, the 'CURRENT_USER()' function can be invoked
to determine which account this is for the client user.  Its value is
constructed from the 'User' and 'Host' columns of the 'user' table row
for the account.

However, there are circumstances under which the 'CURRENT_USER()' value
corresponds not to the client user but to a different account.  This
occurs in contexts when privilege checking is not based the client's
account:

   * Stored routines (procedures and functions) defined with the 'SQL
     SECURITY DEFINER' characteristic

   * Views defined with the 'SQL SECURITY DEFINER' characteristic

   * Triggers and events

In those contexts, privilege checking is done against the 'DEFINER'
account and 'CURRENT_USER()' refers to that account, not to the account
for the client who invoked the stored routine or view or who caused the
trigger to activate.  To determine the invoking user, you can call the
'USER()' function, which returns a value indicating the actual user name
provided by the client and the host from which the client connected.
However, this value does not necessarily correspond directly to an
account in the 'user' table, because the 'USER()' value never contains
wildcards, whereas account values (as returned by 'CURRENT_USER()') may
contain user name and host name wildcards.

For example, a blank user name matches any user, so an account of
'''@'localhost'' enables clients to connect as an anonymous user from
the local host with any user name.  In this case, if a client connects
as 'user1' from the local host, 'USER()' and 'CURRENT_USER()' return
different values:

     mysql> SELECT USER(), CURRENT_USER();
     +-----------------+----------------+
     | USER()          | CURRENT_USER() |
     +-----------------+----------------+
     | user1@localhost | @localhost     |
     +-----------------+----------------+

The host name part of an account can contain wildcards, too.  If the
host name contains a ''%'' or ''_'' pattern character or uses netmask
notation, the account can be used for clients connecting from multiple
hosts and the 'CURRENT_USER()' value will not indicate which one.  For
example, the account ''user2'@'%.example.com'' can be used by 'user2' to
connect from any host in the 'example.com' domain.  If 'user2' connects
from 'remote.example.com', 'USER()' and 'CURRENT_USER()' return
different values:

     mysql> SELECT USER(), CURRENT_USER();
     +--------------------------+---------------------+
     | USER()                   | CURRENT_USER()      |
     +--------------------------+---------------------+
     | user2@remote.example.com | user2@%.example.com |
     +--------------------------+---------------------+

If an application must invoke 'USER()' for user auditing (for example,
if it does auditing from within triggers) but must also be able to
associate the 'USER()' value with an account in the 'user' table, it is
necessary to avoid accounts that contain wildcards in the 'User' or
'Host' column.  Specifically, do not permit 'User' to be empty (which
creates an anonymous-user account), and do not permit pattern characters
or netmask notation in 'Host' values.  All accounts must have a nonempty
'User' value and literal 'Host' value.

With respect to the previous examples, the '''@'localhost'' and
''user2'@'%.example.com'' accounts should be changed not to use
wildcards:

     RENAME USER ''@'localhost' TO 'user1'@'localhost';
     RENAME USER 'user2'@'%.example.com' TO 'user2'@'remote.example.com';

If 'user2' must be able to connect from several hosts in the
'example.com' domain, there should be a separate account for each host.

To extract the user name or host name part from a 'CURRENT_USER()' or
'USER()' value, use the 'SUBSTRING_INDEX()' function:

     mysql> SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',1);
     +---------------------------------------+
     | SUBSTRING_INDEX(CURRENT_USER(),'@',1) |
     +---------------------------------------+
     | user1                                 |
     +---------------------------------------+

     mysql> SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',-1);
     +----------------------------------------+
     | SUBSTRING_INDEX(CURRENT_USER(),'@',-1) |
     +----------------------------------------+
     | localhost                              |
     +----------------------------------------+

6.4 Using Encrypted Connections
===============================

With an unencrypted connection between the MySQL client and the server,
someone with access to the network could watch all your traffic and
inspect the data being sent or received between client and server.

When you must move information over a network in a secure fashion, an
unencrypted connection is unacceptable.  To make any kind of data
unreadable, use encryption.  Encryption algorithms must include security
elements to resist many kinds of known attacks such as changing the
order of encrypted messages or replaying data twice.

MySQL supports encrypted connections between clients and the server
using the TLS (Transport Layer Security) protocol.  TLS is sometimes
referred to as SSL (Secure Sockets Layer) but MySQL does not actually
use the SSL protocol for encrypted connections because its encryption is
weak (see encrypted-connection-protocols-ciphers).

TLS uses encryption algorithms to ensure that data received over a
public network can be trusted.  It has mechanisms to detect data change,
loss, or replay.  TLS also incorporates algorithms that provide identity
verification using the X509 standard.

X509 makes it possible to identify someone on the Internet.  In basic
terms, there should be some entity called a 'Certificate Authority' (or
CA) that assigns electronic certificates to anyone who needs them.
Certificates rely on asymmetric encryption algorithms that have two
encryption keys (a public key and a secret key).  A certificate owner
can present the certificate to another party as proof of identity.  A
certificate consists of its owner's public key.  Any data encrypted
using this public key can be decrypted only using the corresponding
secret key, which is held by the owner of the certificate.

MySQL can be compiled for encrypted-connection support using OpenSSL or
yaSSL. For a comparison of the two packages, see ssl-libraries
For information about the encryption protocols and ciphers each package
supports, see encrypted-connection-protocols-ciphers.

By default, MySQL programs attempt to connect using encryption if the
server supports encrypted connections, falling back to an unencrypted
connection if an encrypted connection cannot be established.  For
information about options that affect use of encrypted connections, see
using-encrypted-connections and
encrypted-connection-options.

MySQL performs encryption on a per-connection basis, and use of
encryption for a given user can be optional or mandatory.  This enables
you to choose an encrypted or unencrypted connection according to the
requirements of individual applications.  For information on how to
require users to use encrypted connections, see the discussion of the
'REQUIRE' clause of the 'CREATE USER' statement in
create-user.  See also the description of the
'require_secure_transport' system variable at
server-system-variables

Encrypted connections can be used between master and slave replication
servers.  See replication-solutions-encrypted-connections.

For information about using encrypted connections from the MySQL C API,
see c-api-encrypted-connections.

It is also possible to connect using encryption from within an SSH
connection to the MySQL server host.  For an example, see
windows-and-ssh.

Several improvements were made to encrypted-connection support in MySQL
5.7.  The following timeline summarizes the changes:

   * 5.7.3: On the client side, an explicit '--ssl' option is no longer
     advisory but prescriptive.  Given a server enabled to support
     encrypted connections, a client program can require an encrypted
     connection by specifying only the '--ssl' option.  (Previously, it
     was necessary for the client to specify either the '--ssl-ca'
     option, or all three of the '--ssl-ca', '--ssl-key', and
     '--ssl-cert' options.)  The connection attempt fails if an
     encrypted connection cannot be established.  Other '--ssl-XXX'
     options on the client side are advisory in the absence of '--ssl':
     The client attempts to connect using encryption but falls back to
     an unencrypted connection if an encrypted connection cannot be
     established.

   * 5.7.5: The server-side '--ssl' option value is enabled by default.

     For servers compiled using OpenSSL, the 'auto_generate_certs' and
     'sha256_password_auto_generate_rsa_keys' system variables are
     available to enable autogeneration and autodiscovery of SSL/RSA
     certificate and key files at startup.  For certificate and key
     autodiscovery, if '--ssl' is enabled and other '--ssl-XXX' options
     are _not_ given to configure encrypted connections explicitly, the
     server attempts to enable support for encrypted connections
     automatically at startup if it discovers the requisite certificate
     and key files in the data directory.

   * 5.7.6: The 'mysql_ssl_rsa_setup'.
     utility is available to make it easier to manually generate SSL/RSA
     certificate and key files.  Autodiscovery of SSL/RSA files at
     startup is expanded to apply to all servers, whether compiled using
     OpenSSL or yaSSL. (This means that 'auto_generate_certs' need not
     be enabled for autodiscovery to occur.)

     If the server discovers at startup that the CA certificate is
     self-signed, it writes a warning to the error log.  (The
     certificate is self-signed if created automatically by the server,
     or manually using 'mysql_ssl_rsa_setup')

   * 5.7.7: The C client library attempts to establish an encrypted
     connection by default if the server supports encrypted connections.
     This affects client programs as follows:

        * In the absence of an '--ssl' option, clients attempt to
          connect using encryption, falling back to an unencrypted
          connection if an encrypted connection cannot be established.

        * The presence of an explicit '--ssl' option or a synonym
          ('--ssl=1', '--enable-ssl') is prescriptive: Clients require
          an encrypted connection and fail if one cannot be established.

        * With an '--ssl=0' option or a synonym ('--skip-ssl',
          '--disable-ssl'), clients use an unencrypted connection.

     This change also affects subsequent releases of MySQL Connectors
     that are based on the C client library: Connector/C, Connector/C++,
     and Connector/ODBC.

   * 5.7.8: The 'require_secure_transport' system variable is available
     to control whether client connections to the server must use some
     form of secure transport.

   * 5.7.10: TLS protocol support is extended from TLSv1 to also include
     TLSv1.1 and TLSv1.2.  The 'tls_version' system variable on the
     server side and '--tls-version' option on the client side enable
     the level of support to be selected.  See
     encrypted-connection-protocols-ciphers.

   * 5.7.11: MySQL client programs support an '--ssl-mode' option that
     enables you to specify the security state of the connection to the
     server.  The '--ssl-mode' option comprises the capabilities of the
     client-side '--ssl' and '--ssl-verify-server-cert' options.
     Consequently, '--ssl' and '--ssl-verify-server-cert' are
     deprecated, and are removed in MySQL 8.0.

6.4.1 Configuring MySQL to Use Encrypted Connections
----------------------------------------------------

Several options are available to indicate whether to use encrypted
connections, and to specify the appropriate certificate and key files.
This section provides general guidance about configuring the server and
clients for encrypted connections:

   * using-encrypted-connections-server-side-configuration

   * using-encrypted-connections-client-side-configuration

For a complete list of options related to establishment of encrypted
connections, see encrypted-connection-options.  If you need to
create the required certificate and key files, see
creating-ssl-rsa-files.

Encrypted connections can be used between master and slave replication
servers.  See replication-solutions-encrypted-connections.

Encrypted connections are available through the MySQL C API. See
c-api-encrypted-connections.

*Server-Side Configuration for Encrypted Connections*

On the server side, the '--ssl' option specifies that the server permits
but does not require encrypted connections.  This option is enabled by
default.

These options on the server side identify the certificate and key files
the server uses when permitting clients to establish encrypted
connections:

   * '--ssl-ca': The path name of the Certificate Authority (CA)
     certificate file.  ('--ssl-capath' is similar but specifies the
     path name of a directory of CA certificate files.)

   * '--ssl-cert': The path name of the server public key certificate
     file.  This can be sent to the client and authenticated against the
     CA certificate that it has.

   * '--ssl-key': The path name of the server private key file.

For example, to enable the server for encrypted connections, start it
with these lines in the 'my.cnf' file, changing the file names as
necessary:

     [mysqld]
     ssl-ca=ca.pem
     ssl-cert=server-cert.pem
     ssl-key=server-key.pem

Each option names a file in PEM format.  If you need to create the
required certificate and key files, see creating-ssl-rsa-files.
Alternatively, if you have a MySQL source distribution, you can test
your setup using the demonstration certificate and key files in its
'mysql-test/std_data' directory.

MySQL servers compiled using OpenSSL can generate missing certificate
and key files automatically at startup.  See
creating-ssl-rsa-files-using-mysql.

The server performs certificate and key file autodiscovery.  If '--ssl'
is enabled (possibly along with '--ssl-cipher') and other '--ssl-XXX'
options are _not_ given to configure encrypted connections explicitly,
the server attempts to enable support for encrypted connections
automatically at startup:

   * If the server discovers valid certificate and key files named
     'ca.pem', 'server-cert.pem', and 'server-key.pem' in the data
     directory, it enables support for encrypted connections by clients.
     (The files need not have been generated automatically; what matters
     is that they have the indicated names and are valid.)

   * If the server does not find valid certificate and key files in the
     data directory, it continues executing but without support for
     encrypted connections.

If the server automatically enables support for encrypted connections,
it writes a note to the error log.  If the server discovers that the CA
certificate is self-signed, it writes a warning to the error log.  (The
certificate is self-signed if created automatically by the server, or
manually using 'mysql_ssl_rsa_setup')

The server uses the names of any automatically discovered and used
certificate and key files to set the corresponding system variables
('ssl_ca', 'ssl_cert', 'ssl_key').

For further control over whether clients must connect using encryption,
use the 'require_secure_transport' system variable; see
server-system-variables.  To specify permitted encryption protocols
explicitly, use the 'tls_version' system variable; see
encrypted-connection-protocols-ciphers.

*Client-Side Configuration for Encrypted Connections*

By default, MySQL client programs attempt to establish an encrypted
connection if the server supports encrypted connections, with further
control available through the '--ssl-mode' option:

   * In the absence of an '--ssl-mode' option, clients attempt to
     connect using encryption, falling back to an unencrypted connection
     if an encrypted connection cannot be established.  This is also the
     behavior with an explicit '--ssl-mode=PREFFERED' option.

   * With '--ssl-mode=REQUIRED', clients require an encrypted connection
     and fail if one cannot be established.

   * With '--ssl-mode=DISABLED', clients use an unencrypted connection.

   * With '--ssl-mode=VERIFY_CA' or '--ssl-mode=VERIFY_IDENTITY',
     clients require an encrypted connection, and also perform
     verification against the server CA certificate and (with
     'VERIFY_IDENTITY') against the server host name in its certificate.

The following options on the client side identify the certificate and
key files clients use when establishing encrypted connections to the
server.  They are similar to the options used on the server side, but
'--ssl-cert' and '--ssl-key' identify the client public and private key:

   * '--ssl-ca': The path name of the Certificate Authority (CA)
     certificate file.  This option, if used, must specify the same
     certificate used by the server.  ('--ssl-capath' is similar but
     specifies the path name of a directory of CA certificate files.)

   * '--ssl-cert': The path name of the client public key certificate
     file.

   * '--ssl-key': The path name of the client private key file.

For additional security relative to that provided by the default
encryption, clients can supply a CA certificate matching the one used by
the server and enable host name identity verification.  In this way, the
server and client place their trust in the same CA certificate and the
client verifies that the host to which it connected is the one intended:

   * To specify the CA certificate, use '--ssl-ca' (or '--ssl-capath'),
     and specify '--ssl-mode=VERIFY_CA'.

   * To enable host name identity verification as well, use
     '--ssl-mode=VERIFY_IDENTITY' rather than '--ssl-mode=VERIFY_CA'.

*Note*:

Host name identity verification does not work with self-signed
certificates created automatically by the server, or manually using
'mysql_ssl_rsa_setup'. (see
creating-ssl-rsa-files-using-mysql).  Such self-signed certificates do
not contain the server name as the Common Name value.

Depending on the encryption requirements of the MySQL account used by a
client, the client may be required to specify certain options to connect
using encryption to a MySQL server that supports encrypted connections.

Suppose that you want to connect using an account that has no special
encryption requirements or was created using a 'CREATE USER'
statement that includes the 'REQUIRE SSL' option.  Assuming
that the server supports encrypted connections, a client can connect
using encryption with no '--ssl-mode' option or with an explicit
'--ssl-mode=PREFFERED' option:

     mysql

Or:

     mysql --ssl-mode=PREFERRED

For an account with 'REQUIRE SSL', the connection attempt fails if an
encrypted connection cannot be established.  For an account with no
special encryption requirements, the attempt falls back to an
unencrypted connection if an encrypted connection cannot be established.
To prevent fallback and fail if an encrypted connection cannot be
obtained, connect like this:

     mysql --ssl-mode=REQUIRED

If the account has more stringent security requirements, other options
must be specified to establish an encrypted connection:

   * For accounts with 'REQUIRE X509', clients must specify at least
     '--ssl-cert' and '--ssl-key'.  In addition, '--ssl-ca' (or
     '--ssl-capath') is recommended so that the public certificate
     provided by the server can be verified.  For example:

          mysql --ssl-ca=ca.pem \
                --ssl-cert=client-cert.pem \
                --ssl-key=client-key.pem

   * For accounts that have 'REQUIRE ISSUER' or 'REQUIRE SUBJECT', the
     option requirements are the same as for 'REQUIRE X509', but the
     certificate must match the issue or subject, respectively,
     specified in the account definition.

For additional information about the 'REQUIRE' clause, see the
discussion in create-user.

To prevent use of encryption and override other '--ssl-XXX' options,
invoke the client program with '--ssl-mode=DISABLED':

     mysql --ssl-mode=DISABLED

To specify permitted encryption protocols explicitly, use the
'--tls-version' option; see
encrypted-connection-protocols-ciphers.

To determine whether the current connection with the server uses
encryption, check the value of the 'Ssl_cipher' status variable.  If the
value is empty, the connection is not encrypted.  Otherwise, the
connection is encrypted and the value indicates the encryption cipher.
For example:

     mysql> SHOW SESSION STATUS LIKE 'Ssl_cipher';
     +---------------+---------------------------+
     | Variable_name | Value                     |
     +---------------+---------------------------+
     | Ssl_cipher    | DHE-RSA-AES128-GCM-SHA256 |
     +---------------+---------------------------+

For the 'mysql' client, an alternative is to use the
'STATUS' or '\s' command and check the 'SSL' line:

     mysql> \s
     ...
     SSL: Not in use
     ...

Or:

     mysql> \s
     ...
     SSL: Cipher in use is DHE-RSA-AES128-GCM-SHA256
     ...

6.4.2 Command Options for Encrypted Connections
-----------------------------------------------

This section describes options that specify whether to use encrypted
connections, the names of certificate and key files, and other
parameters related to encrypted-connection support.  These options can
be given on the command line or in an option file.  For examples of
suggested use and how to check whether a connection is encrypted, see
using-encrypted-connections.

For information about using encrypted connections from the MySQL C API,
see c-api-encrypted-connections.

*Encrypted-Connection Option Summary*

Format                 Description                              Introduced

-skip-ssl              Do not use encrypted connection

-ssl                   Enable encrypted connection

-ssl-ca                File that contains list of trusted SSL
                       Certificate Authorities

-ssl-capath            Directory that contains trusted SSL
                       Certificate Authority certificate
                       files

-ssl-cert              File that contains X509 certificate

-ssl-cipher            List of permitted ciphers for
                       connection encryption

-ssl-crl               File that contains certificate
                       revocation lists

-ssl-crlpath           Directory that contains certificate
                       revocation list files

-ssl-key               File that contains X509 key

-ssl-mode              Security state of connection to server   5.7.11

-ssl-verify-server-certVerify host name against server
                       certificate Common Name identity

-tls-version           Protocols permitted for encrypted        5.7.10
                       connections

   *
     '--ssl'

     This option has different effects on the client and server sides.

     *Note*:

     The client-side '--ssl' option is deprecated as of MySQL 5.7.11 and
     is removed in MySQL 8.0.  For client programs, use '--ssl-mode'
     instead:

        * Use '--ssl-mode=REQUIRED' instead of '--ssl=1' or
          '--enable-ssl'.

        * Use '--ssl-mode=DISABLED' instead of '--ssl=0', '--skip-ssl',
          or '--disable-ssl'.

        * No explicit '--ssl-mode' option is equivalent to no explicit
          '--ssl' option.

     The server-side '--ssl' option is _not_ deprecated.

     By default, MySQL client programs attempt to establish an encrypted
     connection if the server supports encrypted connections, with
     further control available through the '--ssl' option: The
     client-side '--ssl' option works as follows:

        * In the absence of an '--ssl' option, clients attempt to
          connect using encryption, falling back to an unencrypted
          connection if an encrypted connection cannot be established.

        * The presence of an explicit '--ssl' option or a synonym
          ('--ssl=1', '--enable-ssl') is prescriptive: Clients require
          an encrypted connection and fail if one cannot be established.

        * With an '--ssl=0' option or a synonym ('--skip-ssl',
          '--disable-ssl'), clients use an unencrypted connection.

     To require use of encrypted connections by a MySQL account, use
     'CREATE USER' to create the account with a
     'REQUIRE SSL' clause, or use 'ALTER USER' for an
     existing account to add a 'REQUIRE SSL' clause.  Connection
     attempts by clients that use the account will be rejected unless
     MySQL supports encrypted connections and an encrypted connection
     can be established.

     The 'REQUIRE' clause permits other encryption-related options,
     which can be used to enforce security requirements stricter than
     'REQUIRE SSL'.  For additional details about which command options
     may or must be specified by clients that connect using accounts
     configured using the various 'REQUIRE' options, see the description
     of 'REQUIRE' in create-user.

     On the server side, the '--ssl' option specifies that the server
     permits but does not require encrypted connections.  The option is
     enabled on the server side by default.  '--ssl' is implied by other
     '--ssl-XXX' options, as indicated in the descriptions for those
     options.

     The '--ssl' option in negated form indicates that encryption should
     _not_ be used and overrides other '--ssl-XXX' options.  Specify the
     option as '--ssl=0' or a synonym ('--skip-ssl', '--disable-ssl').

     To specify additional parameters for encrypted connections, use at
     least '--ssl-cert' and '--ssl-key' on the server side and
     '--ssl-ca' on the client side.  See
     using-encrypted-connections.  That section also describes server
     capabilities for certificate and key file autogeneration and
     autodiscovery.

   *
     '--ssl-ca=FILE_NAME'

     The path name of the Certificate Authority (CA) certificate file in
     PEM format.  On the server side, this option implies '--ssl'.

     To tell the client not to authenticate the server certificate when
     establishing an encrypted connection to the server, specify neither
     '--ssl-ca' nor '--ssl-capath'.  The server still verifies the
     client according to any applicable requirements established for the
     client account, and it still uses any '--ssl-ca' or '--ssl-capath'
     option values specified on the server side.

   *
     '--ssl-capath=DIR_NAME'

     The path name of the directory that contains trusted SSL
     certificate authority (CA) certificate files in PEM format.  On the
     server side, this option implies '--ssl'.

     To tell the client not to authenticate the server certificate when
     establishing an encrypted connection to the server, specify neither
     '--ssl-ca' nor '--ssl-capath'.  The server still verifies the
     client according to any applicable requirements established for the
     client account, and it still uses any '--ssl-ca' or '--ssl-capath'
     option values specified on the server side.

     MySQL distributions compiled using OpenSSL support the
     '--ssl-capath' option (see ssl-libraries).  Distributions
     compiled using yaSSL do not because yaSSL does not look in any
     directory and does not follow a chained certificate tree.  yaSSL
     requires that all components of the CA certificate tree be
     contained within a single CA certificate tree and that each
     certificate in the file has a unique SubjectName value.  To work
     around this yaSSL limitation, concatenate the individual
     certificate files comprising the certificate tree into a new file
     and specify that file as the value of the '--ssl-ca' option.

   *
     '--ssl-cert=FILE_NAME'

     The path name of the SSL public key certificate file in PEM format.
     On the client side, this is the client public key certificate.  On
     the server side, this is the server public key certificate.  On the
     server side, this option implies '--ssl'.

   *
     '--ssl-cipher=CIPHER_LIST'

     The list of permitted ciphers for connection encryption.  If no
     cipher in the list is supported, encrypted connections will not
     work.  On the server side, this option implies '--ssl'.

     For greatest portability, CIPHER_LIST should be a list of one or
     more cipher names, separated by colons.  This format is understood
     both by OpenSSL and yaSSL. Examples:

          --ssl-cipher=AES128-SHA
          --ssl-cipher=DHE-RSA-AES128-GCM-SHA256:AES128-SHA

     OpenSSL supports a more flexible syntax for specifying ciphers, as
     described in the OpenSSL documentation at
     <https://www.openssl.org/docs/manmaster/man1/ciphers.html>.  yaSSL
     does not, so attempts to use that extended syntax fail for a MySQL
     distribution compiled using yaSSL.

     For information about which encryption ciphers MySQL supports, see
     encrypted-connection-protocols-ciphers.

   *
     '--ssl-crl=FILE_NAME'

     The path name of the file containing certificate revocation lists
     in PEM format.  On the server side, this option implies '--ssl'.

     If neither '--ssl-crl' nor '--ssl-crlpath' is given, no CRL checks
     are performed, even if the CA path contains certificate revocation
     lists.

     MySQL distributions compiled using OpenSSL support the '--ssl-crl'
     option (see ssl-libraries).  Distributions compiled using
     yaSSL do not because revocation lists do not work with yaSSL.

   *
     '--ssl-crlpath=DIR_NAME'

     The path name of the directory that contains certificate revocation
     list files in PEM format.  On the server side, this option implies
     '--ssl'.

     If neither '--ssl-crl' nor '--ssl-crlpath' is given, no CRL checks
     are performed, even if the CA path contains certificate revocation
     lists.

     MySQL distributions compiled using OpenSSL support the
     '--ssl-crlpath' option (see ssl-libraries).  Distributions
     compiled using yaSSL do not because revocation lists do not work
     with yaSSL.

   *
     '--ssl-key=FILE_NAME'

     The path name of the SSL private key file in PEM format.  On the
     client side, this is the client private key.  On the server side,
     this is the server private key.  On the server side, this option
     implies '--ssl'.

     If the key file is protected by a passphrase, the program prompts
     the user for the passphrase.  The password must be given
     interactively; it cannot be stored in a file.  If the passphrase is
     incorrect, the program continues as if it could not read the key.

     For better security, use a certificate with an RSA key size of at
     least 2048 bits.

   *
     '--ssl-mode=MODE'

     This option is available only for client programs, not the server.
     It specifies the security state of the connection to the server.
     These option values are permitted:

        * 'PREFERRED': Establish an encrypted connection if the server
          supports encrypted connections, falling back to an unencrypted
          connection if an encrypted connection cannot be established.
          This is the default if '--ssl-mode' is not specified.

        * 'REQUIRED': Establish an encrypted connection if the server
          supports encrypted connections.  The connection attempt fails
          if an encrypted connection cannot be established.

        * 'VERIFY_CA': Like 'REQUIRED', but additionally verify the
          server Certificate Authority (CA) certificate against the
          configured CA certificates.  The connection attempt fails if
          no valid matching CA certificates are found.

        * 'VERIFY_IDENTITY': Like 'VERIFY_CA', but additionally perform
          host name identify verification by checking the server's
          Common Name identity in the certificate that the server sends
          to the client.  The client verifies the Common Name against
          the host name the client uses for connecting to the server,
          and the connection fails if there is a mismatch.  For
          encrypted connections, this option helps prevent
          man-in-the-middle attacks.  This is like the legacy
          '--ssl-verify-server-cert' option.

          *Note*:

          Host name identity verification does not work with self-signed
          certificates created automatically by the server, or manually
          using 'mysql_ssl_rsa_setup'. (see
          creating-ssl-rsa-files-using-mysql).  Such self-signed
          certificates do not contain the server name as the Common Name
          value.

        * 'DISABLED': Establish an unencrypted connection.  This is like
          the legacy '--ssl=0' option or its synonyms ('--skip-ssl',
          '--disable-ssl').

     The '--ssl-mode' option interacts with CA certificate options as
     follows:

        * If '--ssl-mode' is not explicitly set otherwise, use of
          '--ssl-ca' or '--ssl-capath' implies '--ssl-mode=VERIFY_CA'.

        * For '--ssl-mode' values of 'VERIFY_CA' or 'VERIFY_IDENTITY',
          '--ssl-ca' or '--ssl-capath' is also required, to supply a CA
          certificate that matches the one used by the server.

        * An explicit '--ssl-mode' option with a value other than
          'VERIFY_CA' or 'VERIFY_IDENTITY', together with an explicit
          '--ssl-ca' or '--ssl-capath' option, produces a warning that
          no verification of the server certificate will be done,
          despite a CA certificate option being specified.

     The '--ssl-mode' option was added in MySQL 5.7.11.

     To require use of encrypted connections by a MySQL account, use
     'CREATE USER' to create the account with a
     'REQUIRE SSL' clause, or use 'ALTER USER' for an
     existing account to add a 'REQUIRE SSL' clause.  Connection
     attempts by clients that use the account will be rejected unless
     MySQL supports encrypted connections and an encrypted connection
     can be established.

     The 'REQUIRE' clause permits other encryption-related options,
     which can be used to enforce security requirements stricter than
     'REQUIRE SSL'.  For additional details about which command options
     may or must be specified by clients that connect using accounts
     configured using the various 'REQUIRE' options, see the description
     of 'REQUIRE' in create-user.

   *
     '--ssl-verify-server-cert'

     *Note*:

     The '--ssl-verify-server-cert' option is deprecated as of MySQL
     5.7.11 and is removed in MySQL 8.0.  Use
     '--ssl-mode=VERIFY_IDENTITY' instead.

     This option is available only for client programs, not the server.
     It causes the client to perform host name identify verification by
     checking the server's Common Name identity in the certificate that
     the server sends to the client.  The client verifies the Common
     Name against the host name the client uses for connecting to the
     server, and the connection fails if there is a mismatch.  For
     encrypted connections, this option helps prevent man-in-the-middle
     attacks.  Host name identity verification is disabled by default.

     *Note*:

     Host name identity verification does not work with self-signed
     certificates created automatically by the server, or manually using
     'mysql_ssl_rsa_setup'. (see
     creating-ssl-rsa-files-using-mysql).  Such self-signed
     certificates do not contain the server name as the Common Name
     value.

   *
     '--tls-version=PROTOCOL_LIST'

     For client programs, the protocols permitted by the client for
     encrypted connections.  The value is a comma-separated list
     containing one or more protocol names.  For example:

          mysql --tls-version="TLSv1.1,TLSv1.2"

     The protocols that can be named for this option depend on the SSL
     library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

     On the server side, use the 'tls_version' system variable instead.

6.4.3 Creating SSL and RSA Certificates and Keys
------------------------------------------------

The following discussion describes how to create the files required for
SSL and RSA support in MySQL. File creation can be performed using
facilities provided by MySQL itself, or by invoking the 'openssl'
command directly.

SSL certificate and key files enable MySQL to support sencrypted
connections using SSL. See using-encrypted-connections.

RSA key files enable MySQL to support secure password exchange over
unencrypted connections for accounts authenticated by the
'sha256_password' plugin.  See sha256-pluggable-authentication.

6.4.3.1 Creating SSL and RSA Certificates and Keys using MySQL
..............................................................

MySQL provides these ways to create the SSL certificate and key files
and RSA key-pair files required to support encrypted connections using
SSL and secure password exchange using RSA over unencrypted connections,
if those files are missing:

   * The server can autogenerate these files at startup, for MySQL
     distributions compiled using OpenSSL.

   * Users can invoke the 'mysql_ssl_rsa_setup'
     utility manually.

   * For some distribution types, such as RPM packages, see
     'mysql_ssl_rsa_setup' invocation occurs
     during data directory initialization.  In this case, the MySQL
     distribution need not have been compiled using OpenSSL as long as
     the 'openssl' command is available.

*Important*:

Server autogeneration and 'mysql_ssl_rsa_setup'
help lower the barrier to using SSL by making it
easier to generate the required files.  However, certificates generated
by these methods are self-signed, which may not be very secure.  After
you gain experience using such files, consider obtaining certificate/key
material from a registered certificate authority.

   * creating-ssl-rsa-files-using-mysql-automatic

   *
     creating-ssl-rsa-files-using-mysql-manual-using-mysql-ssl-rsa-setup

   *
     creating-ssl-rsa-files-using-mysql-ssl-and-rsa-file-characteristics

*Automatic SSL and RSA File Generation*

For MySQL distributions compiled using OpenSSL, the MySQL server has the
capability of automatically generating missing SSL and RSA files at
startup.  The 'auto_generate_certs' and
'sha256_password_auto_generate_rsa_keys' system variables control
automatic generation of these files.  Both variables are enabled by
default.  They can be enabled at startup and inspected but not set at
runtime.

At startup, the server automatically generates server-side and
client-side SSL certificate and key files in the data directory if the
'auto_generate_certs' system variable is enabled, no SSL options other
than '--ssl' are specified, and the server-side SSL files are missing
from the data directory.  These files enable encrypted client
connections using SSL; see using-encrypted-connections.

  1. The server checks the data directory for SSL files with the
     following names:

          ca.pem
          server-cert.pem
          server-key.pem

  2. If any of those files are present, the server creates no SSL files.
     Otherwise, it creates them, plus some additional files:

          ca.pem               Self-signed CA certificate
          ca-key.pem           CA private key
          server-cert.pem      Server certificate
          server-key.pem       Server private key
          client-cert.pem      Client certificate
          client-key.pem       Client private key

  3. If the server autogenerates SSL files, it uses the names of the
     'ca.pem', 'server-cert.pem', and 'server-key.pem' files to set the
     corresponding system variables ('ssl_ca', 'ssl_cert', 'ssl_key').

At startup, the server automatically generates RSA private/public
key-pair files in the data directory if all of these conditions are
true: The 'sha256_password_auto_generate_rsa_keys' system variable is
enabled; no RSA options are specified; the RSA files are missing from
the data directory.  These key-pair files enable secure password
exchange using RSA over unencrypted connections for accounts
authenticated by the 'sha256_password' plugin; see
sha256-pluggable-authentication.

  1. The server checks the data directory for RSA files with the
     following names:

          private_key.pem      Private member of private/public key pair
          public_key.pem       Public member of private/public key pair

  2. If any of these files are present, the server creates no RSA files.
     Otherwise, it creates them.

  3. If the server autogenerates the RSA files, it uses their names to
     set the corresponding system variables
     ('sha256_password_private_key_path',
     'sha256_password_public_key_path').

*Manual SSL and RSA File Generation Using mysql_ssl_rsa_setup*

MySQL distributions include a 'mysql_ssl_rsa_setup'
utility that can be invoked manually to generate
SSL and RSA files.  This utility is included with all MySQL
distributions (whether compiled using OpenSSL or yaSSL), but it does
require that the 'openssl' command be available.  For usage
instructions, see mysql-ssl-rsa-setup.

*SSL and RSA File Characteristics*

SSL and RSA files created automatically by the server or by invoking
'mysql_ssl_rsa_setup' have these
characteristics:

   * SSL and RSA keys are have a size of 2048 bits.

   * The SSL CA certificate is self signed.

   * The SSL server and client certificates are signed with the CA
     certificate and key, using the 'sha256WithRSAEncryption' signature
     algorithm.

   * SSL certificates use these Common Name (CN) values, with the
     appropriate certificate type (CA, Server, Client):

          ca.pem:         MySQL_Server_SUFFIX_Auto_Generated_CA_Certificate
          server-cert.pm: MySQL_Server_SUFFIX_Auto_Generated_Server_Certificate
          client-cert.pm: MySQL_Server_SUFFIX_Auto_Generated_Client_Certificate

     The SUFFIX value is based on the MySQL version number.  For files
     generated by 'mysql_ssl_rsa_setup', the
     suffix can be specified explicitly using the '--suffix' option.

     For files generated by the server, if the resulting CN values
     exceed 64 characters, the '_SUFFIX' portion of the name is omitted.

   * SSL files have blank values for Country (C), State or Province
     (ST), Organization (O), Organization Unit Name (OU) and email
     address.

   * SSL files created by the server or by 'mysql_ssl_rsa_setup'
     are valid for ten years from the time of
     generation.

   * RSA files do not expire.

   * SSL files have different serial numbers for each certificate/key
     pair (1 for CA, 2 for Server, 3 for Client).

   * Files created automatically by the server are owned by the account
     that runs the server.  Files created using
     'mysql_ssl_rsa_setup' are owned by the user
     who invoked that program.  This can be changed on systems that
     support the 'chown()' system call if the program is invoked by
     'root' and the '--uid' option is given to specify the user who
     should own the files.

   * On Unix and Unix-like systems, the file access mode is 644 for
     certificate files (that is, world readable) and 600 for key files
     (that is, accessible only by the account that runs the server).

To see the contents of an SSL certificate (for example, to check the
range of dates over which it is valid), invoke 'openssl' directly:

     openssl x509 -text -in ca.pem
     openssl x509 -text -in server-cert.pem
     openssl x509 -text -in client-cert.pem

It is also possible to check SSL certificate expiration information
using this SQL statement:

     mysql> SHOW STATUS LIKE 'Ssl_server_not%';
     +-----------------------+--------------------------+
     | Variable_name         | Value                    |
     +-----------------------+--------------------------+
     | Ssl_server_not_after  | Apr 28 14:16:39 2027 GMT |
     | Ssl_server_not_before | May  1 14:16:39 2017 GMT |
     +-----------------------+--------------------------+

6.4.3.2 Creating SSL Certificates and Keys Using openssl
........................................................

This section describes how to use the 'openssl' command to set up SSL
certificate and key files for use by MySQL servers and clients.  The
first example shows a simplified procedure such as you might use from
the command line.  The second shows a script that contains more detail.
The first two examples are intended for use on Unix and both use the
'openssl' command that is part of OpenSSL. The third example describes
how to set up SSL files on Windows.

*Note*:

There are easier alternatives to generating the files required for SSL
than the procedure described here: Let the server autogenerate them or
use the 'mysql_ssl_rsa_setup' program.  See
creating-ssl-rsa-files-using-mysql.

*Important*:

Whatever method you use to generate the certificate and key files, the
Common Name value used for the server and client certificates/keys must
each differ from the Common Name value used for the CA certificate.
Otherwise, the certificate and key files will not work for servers
compiled using OpenSSL. A typical error in this case is:

     ERROR 2026 (HY000): SSL connection error:
     error:00000001:lib(0):func(0):reason(1)

   * creating-ssl-files-using-openssl-unix-command-line

   * creating-ssl-files-using-openssl-unix-script

   * creating-ssl-files-using-openssl-windows

*Example 1: Creating SSL Files from the Command Line on Unix*

The following example shows a set of commands to create MySQL server and
client certificate and key files.  You will need to respond to several
prompts by the 'openssl' commands.  To generate test files, you can
press Enter to all prompts.  To generate files for production use, you
should provide nonempty responses.

     # Create clean environment
     rm -rf newcerts
     mkdir newcerts && cd newcerts

     # Create CA certificate
     openssl genrsa 2048 > ca-key.pem
     openssl req -new -x509 -nodes -days 3600 \
             -key ca-key.pem -out ca.pem

     # Create server certificate, remove passphrase, and sign it
     # server-cert.pem = public key, server-key.pem = private key
     openssl req -newkey rsa:2048 -days 3600 \
             -nodes -keyout server-key.pem -out server-req.pem
     openssl rsa -in server-key.pem -out server-key.pem
     openssl x509 -req -in server-req.pem -days 3600 \
             -CA ca.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem

     # Create client certificate, remove passphrase, and sign it
     # client-cert.pem = public key, client-key.pem = private key
     openssl req -newkey rsa:2048 -days 3600 \
             -nodes -keyout client-key.pem -out client-req.pem
     openssl rsa -in client-key.pem -out client-key.pem
     openssl x509 -req -in client-req.pem -days 3600 \
             -CA ca.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem

After generating the certificates, verify them:

     openssl verify -CAfile ca.pem server-cert.pem client-cert.pem

You should see a response like this:

     server-cert.pem: OK
     client-cert.pem: OK

To see the contents of a certificate (for example, to check the range of
dates over which a certificate is valid), invoke 'openssl' like this:

     openssl x509 -text -in ca.pem
     openssl x509 -text -in server-cert.pem
     openssl x509 -text -in client-cert.pem

Now you have a set of files that can be used as follows:

   * 'ca.pem': Use this as the argument to '--ssl-ca' on the server and
     client sides.  (The CA certificate, if used, must be the same on
     both sides.)

   * 'server-cert.pem', 'server-key.pem': Use these as the arguments to
     '--ssl-cert' and '--ssl-key' on the server side.

   * 'client-cert.pem', 'client-key.pem': Use these as the arguments to
     '--ssl-cert' and '--ssl-key' on the client side.

For additional usage instructions, see
using-encrypted-connections.

*Example 2: Creating SSL Files Using a Script on Unix*

Here is an example script that shows how to set up SSL certificate and
key files for MySQL. After executing the script, use the files for SSL
connections as described in using-encrypted-connections.

     DIR=`pwd`/openssl
     PRIV=$DIR/private

     mkdir $DIR $PRIV $DIR/newcerts
     cp /usr/share/ssl/openssl.cnf $DIR
     replace ./demoCA $DIR -- $DIR/openssl.cnf

     # Create necessary files: $database, $serial and $new_certs_dir
     # directory (optional)

     touch $DIR/index.txt
     echo "01" > $DIR/serial

     #
     # Generation of Certificate Authority(CA)
     #

     openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/ca.pem \
         -days 3600 -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/finley/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # ................++++++
     # .........++++++
     # writing new private key to '/home/finley/openssl/private/cakey.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be
     # incorporated into your certificate request.
     # What you are about to enter is what is called a Distinguished Name
     # or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL admin
     # Email Address []:

     #
     # Create server request and key
     #
     openssl req -new -keyout $DIR/server-key.pem -out \
         $DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/finley/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # ..++++++
     # ..........++++++
     # writing new private key to '/home/finley/openssl/server-key.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be
     # incorporated into your certificate request.
     # What you are about to enter is what is called a Distinguished Name
     # or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL server
     # Email Address []:
     #
     # Please enter the following 'extra' attributes
     # to be sent with your certificate request
     # A challenge password []:
     # An optional company name []:

     #
     # Remove the passphrase from the key
     #
     openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem

     #
     # Sign server cert
     #
     openssl ca -cert $DIR/ca.pem -policy policy_anything \
         -out $DIR/server-cert.pem -config $DIR/openssl.cnf \
         -infiles $DIR/server-req.pem

     # Sample output:
     # Using configuration from /home/finley/openssl/openssl.cnf
     # Enter PEM pass phrase:
     # Check that the request matches the signature
     # Signature ok
     # The Subjects Distinguished Name is as follows
     # countryName           :PRINTABLE:'FI'
     # organizationName      :PRINTABLE:'MySQL AB'
     # commonName            :PRINTABLE:'MySQL admin'
     # Certificate is to be certified until Sep 13 14:22:46 2003 GMT
     # (365 days)
     # Sign the certificate? [y/n]:y
     #
     #
     # 1 out of 1 certificate requests certified, commit? [y/n]y
     # Write out database with 1 new entries
     # Data Base Updated

     #
     # Create client request and key
     #
     openssl req -new -keyout $DIR/client-key.pem -out \
         $DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/finley/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # .....................................++++++
     # .............................................++++++
     # writing new private key to '/home/finley/openssl/client-key.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be
     # incorporated into your certificate request.
     # What you are about to enter is what is called a Distinguished Name
     # or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL user
     # Email Address []:
     #
     # Please enter the following 'extra' attributes
     # to be sent with your certificate request
     # A challenge password []:
     # An optional company name []:

     #
     # Remove the passphrase from the key
     #
     openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem

     #
     # Sign client cert
     #

     openssl ca -cert $DIR/ca.pem -policy policy_anything \
         -out $DIR/client-cert.pem -config $DIR/openssl.cnf \
         -infiles $DIR/client-req.pem

     # Sample output:
     # Using configuration from /home/finley/openssl/openssl.cnf
     # Enter PEM pass phrase:
     # Check that the request matches the signature
     # Signature ok
     # The Subjects Distinguished Name is as follows
     # countryName           :PRINTABLE:'FI'
     # organizationName      :PRINTABLE:'MySQL AB'
     # commonName            :PRINTABLE:'MySQL user'
     # Certificate is to be certified until Sep 13 16:45:17 2003 GMT
     # (365 days)
     # Sign the certificate? [y/n]:y
     #
     #
     # 1 out of 1 certificate requests certified, commit? [y/n]y
     # Write out database with 1 new entries
     # Data Base Updated

     #
     # Create a my.cnf file that you can use to test the certificates
     #

     cat <<EOF > $DIR/my.cnf
     [client]
     ssl-ca=$DIR/ca.pem
     ssl-cert=$DIR/client-cert.pem
     ssl-key=$DIR/client-key.pem
     [mysqld]
     ssl-ca=$DIR/ca.pem
     ssl-cert=$DIR/server-cert.pem
     ssl-key=$DIR/server-key.pem
     EOF

*Example 3: Creating SSL Files on Windows*

Download OpenSSL for Windows if it is not installed on your system.  An
overview of available packages can be seen here:

     <http://www.slproweb.com/products/Win32OpenSSL.html>

Choose the Win32 OpenSSL Light or Win64 OpenSSL Light package, depending
on your architecture (32-bit or 64-bit).  The default installation
location will be 'C:\OpenSSL-Win32' or 'C:\OpenSSL-Win64', depending on
which package you downloaded.  The following instructions assume a
default location of 'C:\OpenSSL-Win32'.  Modify this as necessary if you
are using the 64-bit package.

If a message occurs during setup indicating ''...critical component is
missing: Microsoft Visual C++ 2008 Redistributables'', cancel the setup
and download one of the following packages as well, again depending on
your architecture (32-bit or 64-bit):

   * Visual C++ 2008 Redistributables (x86), available at:

          <http://www.microsoft.com/downloads/details.aspx?familyid=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF>

   * Visual C++ 2008 Redistributables (x64), available at:

          <http://www.microsoft.com/downloads/details.aspx?familyid=bd2a6171-e2d6-4230-b809-9a8d7548c1b6>

After installing the additional package, restart the OpenSSL setup
procedure.

During installation, leave the default 'C:\OpenSSL-Win32' as the install
path, and also leave the default option ''Copy OpenSSL DLL files to the
Windows system directory'' selected.

When the installation has finished, add 'C:\OpenSSL-Win32\bin' to the
Windows System Path variable of your server (depending on your version
of Windows, the following path-setting instructions might differ
slightly):

  1. On the Windows desktop, right-click the 'My Computer' icon, and
     select 'Properties'.

  2. Select the 'Advanced' tab from the 'System Properties' menu that
     appears, and click the 'Environment Variables' button.

  3. Under 'System Variables', select 'Path', then click the 'Edit'
     button.  The 'Edit System Variable' dialogue should appear.

  4. Add '';C:\OpenSSL-Win32\bin'' to the end (notice the semicolon).

  5. Press OK 3 times.

  6. Check that OpenSSL was correctly integrated into the Path variable
     by opening a new command console ('Start>Run>cmd.exe') and
     verifying that OpenSSL is available:

          Microsoft Windows [Version ...]
          Copyright (c) 2006 Microsoft Corporation. All rights reserved.

          C:\Windows\system32>cd \

          C:\>openssl
          OpenSSL> exit <<< If you see the OpenSSL prompt, installation was successful.

          C:\>

After OpenSSL has been installed, use instructions similar to those from
Example 1 (shown earlier in this section), with the following changes:

   * Change the following Unix commands:

          # Create clean environment
          rm -rf newcerts
          mkdir newcerts && cd newcerts

     On Windows, use these commands instead:

          # Create clean environment
          md c:\newcerts
          cd c:\newcerts

   * When a ''\'' character is shown at the end of a command line, this
     ''\'' character must be removed and the command lines entered all
     on a single line.

After generating the certificate and key files, to use them for SSL
connections, see using-encrypted-connections.

6.4.3.3 Creating RSA Keys Using openssl
.......................................

This section describes how to use the 'openssl' command to set up the
RSA key files that enable MySQL to support secure password exchange over
unencrypted connections for accounts authenticated by the
'sha256_password' plugin.

*Note*:

There are easier alternatives to generating the files required for RSA
than the procedure described here: Let the server autogenerate them or
use the 'mysql_ssl_rsa_setup' program.  See
creating-ssl-rsa-files-using-mysql.

To create the RSA private and public key-pair files, run these commands
while logged into the system account used to run the MySQL server so the
files will be owned by that account:

     openssl genrsa -out private_key.pem 2048
     openssl rsa -in private_key.pem -pubout -out public_key.pem

Those commands create 2,048-bit keys.  To create stronger keys, use a
larger value.

Then set the access modes for the key files.  The private key should be
readable only by the server, whereas the public key can be freely
distributed to client users:

     chmod 400 private_key.pem
     chmod 444 public_key.pem

6.4.4 OpenSSL Versus yaSSL
--------------------------

MySQL can be compiled using OpenSSL or yaSSL, both of which enable
encrypted connections based on the OpenSSL API:

   * MySQL Enterprise Edition binary distributions are compiled using
     OpenSSL. It is not possible to use yaSSL with MySQL Enterprise
     Edition.

   * MySQL Community Edition binary distributions are compiled using
     yaSSL.

   * MySQL Community Edition source distributions can be compiled using
     either OpenSSL or yaSSL (see
     building-with-encrypted-connection-support).

OpenSSL and yaSSL offer the same basic functionality, but MySQL
distributions compiled using OpenSSL have additional features:

   * OpenSSL supports TLSv1, TLSv1.1, and TLSv1.2 protocols.  yaSSL
     supports only TLSv1 and TLSv1.1 protocols.

   * OpenSSL supports a wider range of encryption ciphers from which to
     choose for the '--ssl-cipher' option.  OpenSSL supports the
     '--ssl-capath', '--ssl-crl', and '--ssl-crlpath' options.  See
     encrypted-connection-options.

   * Accounts that authenticate using the 'sha256_password' plugin can
     use RSA key files for secure password exchange over unencrypted
     connections.  See sha256-pluggable-authentication.

   * The server can automatically generate missing SSL and RSA
     certificate and key files at startup.  See
     creating-ssl-rsa-files-using-mysql.

   * OpenSSL supports more encryption modes for the 'AES_ENCRYPT()' and
     'AES_DECRYPT()' functions.  See encryption-functions

Certain OpenSSL-related system and status variables are present only if
MySQL was compiled using OpenSSL:

   * 'auto_generate_certs'

   * 'sha256_password_auto_generate_rsa_keys'

   * 'sha256_password_private_key_path'

   * 'sha256_password_public_key_path'

   * 'Rsa_public_key'

To determine whether a server was compiled using OpenSSL, test the
existence of any of those variables.  For example, this statement
returns a row if OpenSSL was used and an empty result if yaSSL was used:

     SHOW STATUS LIKE 'Rsa_public_key';

6.4.5 Building MySQL with Support for Encrypted Connections
-----------------------------------------------------------

To use encrypted connections between the MySQL server and client
programs, your system must support either OpenSSL or yaSSL:

   * MySQL Enterprise Edition binary distributions are compiled using
     OpenSSL. It is not possible to use yaSSL with MySQL Enterprise
     Edition.

   * MySQL Community Edition binary distributions are compiled using
     yaSSL.

   * MySQL Community Edition source distributions can be compiled using
     either OpenSSL or yaSSL.

If you compile MySQL from a source distribution, 'CMake' configures the
distribution to use yaSSL by default.  To compile using OpenSSL instead,
use this procedure:

  1. Ensure that OpenSSL 1.0.1 or higher is installed on your system.
     If the installed OpenSSL version is lower than 1.0.1, 'CMake'
     produces an error at MySQL configuration time.  If it is necessary
     to obtain OpenSSL, visit <http://www.openssl.org>.

  2. The 'WITH_SSL' 'CMake' option determines which SSL library to use
     for compiling MySQL (see source-configuration-options).
     The default is '-DWITH_SSL=bundled', which uses yaSSL. To use
     OpenSSL, add the '-DWITH_SSL=system' option to the 'CMake' command
     you normally use to configure the MySQL source distribution.  For
     example:

          cmake . -DWITH_SSL=system

     That command configures the distribution to use the installed
     OpenSSL library.  Alternatively, to explicitly specify the path
     name to the OpenSSL installation, use the following syntax.  This
     can be useful if you have multiple versions of OpenSSL installed,
     to prevent 'CMake' from choosing the wrong one:

          cmake . -DWITH_SSL=PATH_NAME

  3. Compile and install the distribution.

To check whether a 'mysqld' server supports encrypted
connections, examine the value of the 'have_ssl' system variable:

     mysql> SHOW VARIABLES LIKE 'have_ssl';
     +---------------+-------+
     | Variable_name | Value |
     +---------------+-------+
     | have_ssl      | YES   |
     +---------------+-------+

If the value is 'YES', the server supports encrypted connections.  If
the value is 'DISABLED', the server is capable of supporting encrypted
connections but was not started with the appropriate '--ssl-XXX' options
to enable encrypted connections to be used; see
using-encrypted-connections.

To determine whether a server was compiled using OpenSSL or yaSSL, check
the existence of any of the system or status variables that are present
only for OpenSSL. See ssl-libraries

6.4.6 Encrypted Connection Protocols and Ciphers
------------------------------------------------

To determine which encryption protocol and cipher are in use for an
encrypted connection, use the following statements to check the values
of the 'Ssl_version' and 'Ssl_cipher' status variables:

     mysql> SHOW SESSION STATUS LIKE 'Ssl_version';
     +---------------+-------+
     | Variable_name | Value |
     +---------------+-------+
     | Ssl_version   | TLSv1 |
     +---------------+-------+
     mysql> SHOW SESSION STATUS LIKE 'Ssl_cipher';
     +---------------+---------------------------+
     | Variable_name | Value                     |
     +---------------+---------------------------+
     | Ssl_cipher    | DHE-RSA-AES128-GCM-SHA256 |
     +---------------+---------------------------+

If the connection is not encrypted, both variables have an empty value.

MySQL supports encrypted connections using TLS protocols:

   * When compiled using OpenSSL 1.0.1 or higher, MySQL supports the
     TLSv1, TLSv1.1, and TLSv1.2 protocols.

   * When compiled using the bundled version of yaSSL, MySQL supports
     the TLSv1 and TLSv1.1 protocols.

The value of the 'tls_version' system variable determines which
protocols the server is permitted to use from those that are available.
The 'tls_version' value is a comma-separated list containing one or more
of these protocols (not case-sensitive): TLSv1, TLSv1.1, TLSv1.2.  By
default, this variable lists all protocols supported by the SSL library
used to compile MySQL ('TLSv1,TLSv1.1,TLSv1.2' for OpenSSL,
'TLSv1,TLSv1.1' for yaSSL). To determine the value of 'tls_version' at
runtime, use this statement:

     mysql> SHOW GLOBAL VARIABLES LIKE 'tls_version';
     +---------------+-----------------------+
     | Variable_name | Value                 |
     +---------------+-----------------------+
     | tls_version   | TLSv1,TLSv1.1,TLSv1.2 |
     +---------------+-----------------------+

To change the value of 'tls_version', set it at server startup.  For
example, to prohibit connections that use the less-secure TLSv1
protocol, use these lines in the server 'my.cnf' file:

     [mysqld]
     tls_version=TLSv1.1,TLSv1.2

To be even more restrict and permit only TLSv1.2 connections, set
'tls_version' like this (assuming that your server is compiled using
OpenSSL because yaSSL does not support TLSv1.2):

     [mysqld]
     tls_version=TLSv1.2

For client programs, the '--tls-version' option enables specifying the
TLS protocols permitted per client invocation.  The value format is the
same as for 'tls_version'.

By default, MySQL attempts to use the highest TLS protocol version
available, depending on which SSL library was used to compile the server
and client, which key size is used, and whether the server or client are
restricted from using some protocols; for example, by means of
'tls_version'/'--tls-version':

   * If the server and client are compiled using OpenSSL, TLSv1.2 is
     used if possible.

   * If either or both the server and client are compiled using yaSSL,
     TLSv1.1 is used if possible.

   * TLSv1.2 does not work with all ciphers that have a key size of 512
     bits or less.  To use this protocol with such a key, use
     '--ssl-cipher' to specify the cipher name explicitly:

          AES128-SHA
          AES128-SHA256
          AES256-SHA
          AES256-SHA256
          CAMELLIA128-SHA
          CAMELLIA256-SHA
          DES-CBC3-SHA
          DHE-RSA-AES256-SHA
          RC4-MD5
          RC4-SHA
          SEED-SHA

   * For better security, use a certificate with an RSA key size of at
     least 2048 bits.

*Note*:

Prior to MySQL 5.7.10, MySQL supports only TLSv1, for both OpenSSL and
yaSSL, and no system variable or client option exist for specifying
which TLS protocols to permit.

If the server and client protocol capabilities have no protocol in
common, the server terminates the connection request.  For example, if
the server is configured with 'tls_version=TLSv1.1,TLSv1.2', connection
attempts will fail for clients invoked with '--tls-version=TLSv1', and
for older clients that do not support the '--tls-version' option and
implicitly support only TLSv1.

To determine which ciphers a given server supports, use the following
statement to check the value of the 'Ssl_cipher_list' status variable:

     SHOW SESSION STATUS LIKE 'Ssl_cipher_list';

The set of available ciphers depends on your MySQL version and whether
MySQL was compiled using OpenSSL or yaSSL, and (for OpenSSL) the library
version used to compile MySQL.

As of MySQL 5.7.10, order of ciphers passed by MySQL to the SSL library
is significant.  More secure ciphers are mentioned first in the list,
and the first cipher supported by the provided certificate is selected.

MySQL passes this cipher list to OpenSSL:

     ECDHE-ECDSA-AES128-GCM-SHA256
     ECDHE-ECDSA-AES256-GCM-SHA384
     ECDHE-RSA-AES128-GCM-SHA256
     ECDHE-RSA-AES256-GCM-SHA384
     ECDHE-ECDSA-AES128-SHA256
     ECDHE-RSA-AES128-SHA256
     ECDHE-ECDSA-AES256-SHA384
     ECDHE-RSA-AES256-SHA384
     DHE-RSA-AES128-GCM-SHA256
     DHE-DSS-AES128-GCM-SHA256
     DHE-RSA-AES128-SHA256
     DHE-DSS-AES128-SHA256
     DHE-DSS-AES256-GCM-SHA384
     DHE-RSA-AES256-SHA256
     DHE-DSS-AES256-SHA256
     ECDHE-RSA-AES128-SHA
     ECDHE-ECDSA-AES128-SHA
     ECDHE-RSA-AES256-SHA
     ECDHE-ECDSA-AES256-SHA
     DHE-DSS-AES128-SHA
     DHE-RSA-AES128-SHA
     TLS_DHE_DSS_WITH_AES_256_CBC_SHA
     DHE-RSA-AES256-SHA
     AES128-GCM-SHA256
     DH-DSS-AES128-GCM-SHA256
     ECDH-ECDSA-AES128-GCM-SHA256
     AES256-GCM-SHA384
     DH-DSS-AES256-GCM-SHA384
     ECDH-ECDSA-AES256-GCM-SHA384
     AES128-SHA256
     DH-DSS-AES128-SHA256
     ECDH-ECDSA-AES128-SHA256
     AES256-SHA256
     DH-DSS-AES256-SHA256
     ECDH-ECDSA-AES256-SHA384
     AES128-SHA
     DH-DSS-AES128-SHA
     ECDH-ECDSA-AES128-SHA
     AES256-SHA
     DH-DSS-AES256-SHA
     ECDH-ECDSA-AES256-SHA
     DHE-RSA-AES256-GCM-SHA384
     DH-RSA-AES128-GCM-SHA256
     ECDH-RSA-AES128-GCM-SHA256
     DH-RSA-AES256-GCM-SHA384
     ECDH-RSA-AES256-GCM-SHA384
     DH-RSA-AES128-SHA256
     ECDH-RSA-AES128-SHA256
     DH-RSA-AES256-SHA256
     ECDH-RSA-AES256-SHA384
     ECDHE-RSA-AES128-SHA
     ECDHE-ECDSA-AES128-SHA
     ECDHE-RSA-AES256-SHA
     ECDHE-ECDSA-AES256-SHA
     DHE-DSS-AES128-SHA
     DHE-RSA-AES128-SHA
     TLS_DHE_DSS_WITH_AES_256_CBC_SHA
     DHE-RSA-AES256-SHA
     AES128-SHA
     DH-DSS-AES128-SHA
     ECDH-ECDSA-AES128-SHA
     AES256-SHA
     DH-DSS-AES256-SHA
     ECDH-ECDSA-AES256-SHA
     DH-RSA-AES128-SHA
     ECDH-RSA-AES128-SHA
     DH-RSA-AES256-SHA
     ECDH-RSA-AES256-SHA
     DES-CBC3-SHA

MySQL passes this cipher list to yaSSL:

     DHE-RSA-AES256-SHA
     DHE-RSA-AES128-SHA
     AES128-RMD
     DES-CBC3-RMD
     DHE-RSA-AES256-RMD
     DHE-RSA-AES128-RMD
     DHE-RSA-DES-CBC3-RMD
     AES256-SHA
     RC4-SHA
     RC4-MD5
     DES-CBC3-SHA
     DES-CBC-SHA
     EDH-RSA-DES-CBC3-SHA
     EDH-RSA-DES-CBC-SHA
     AES128-SHA:AES256-RMD

As of MySQL 5.7.10, these cipher restrictions are in place:

   * The following ciphers are permanently restricted:

          !DHE-DSS-DES-CBC3-SHA
          !DHE-RSA-DES-CBC3-SHA
          !ECDH-RSA-DES-CBC3-SHA
          !ECDH-ECDSA-DES-CBC3-SHA
          !ECDHE-RSA-DES-CBC3-SHA
          !ECDHE-ECDSA-DES-CBC3-SHA

   * The following categories of ciphers are permanently restricted:

          !aNULL
          !eNULL
          !EXPORT
          !LOW
          !MD5
          !DES
          !RC2
          !RC4
          !PSK
          !SSLv3

If the server is started using a compatible certificate that uses any of
the preceding restricted ciphers or cipher categories, the server starts
with support for encrypted connections disabled.

6.4.7 Connecting to MySQL Remotely from Windows with SSH
--------------------------------------------------------

This section describes how to get an encrypted connection to a remote
MySQL server with SSH. The information was provided by David Carlson
<dcarlson@mplcomm.com>.

  1. Install an SSH client on your Windows machine.  For a comparison of
     SSH clients, see
     <http://en.wikipedia.org/wiki/Comparison_of_SSH_clients>.

  2. Start your Windows SSH client.  Set 'Host_Name =
     YOURMYSQLSERVER_URL_OR_IP'.  Set 'userid=YOUR_USERID' to log in to
     your server.  This 'userid' value might not be the same as the user
     name of your MySQL account.

  3. Set up port forwarding.  Either do a remote forward (Set
     'local_port: 3306', 'remote_host: YOURMYSQLSERVERNAME_OR_IP',
     'remote_port: 3306' ) or a local forward (Set 'port: 3306', 'host:
     localhost', 'remote port: 3306').

  4. Save everything, otherwise you will have to redo it the next time.

  5. Log in to your server with the SSH session you just created.

  6. On your Windows machine, start some ODBC application (such as
     Access).

  7. Create a new file in Windows and link to MySQL using the ODBC
     driver the same way you normally do, except type in 'localhost' for
     the MySQL host server, not YOURMYSQLSERVERNAME.

At this point, you should have an ODBC connection to MySQL, encrypted
using SSH.

6.5 Security Plugins
====================

MySQL includes several plugins that implement security features:

   * Plugins for authenticating attempts by clients to connect to MySQL
     Server.  Plugins are available for several authentication
     protocols.  For general discussion of the authentication process,
     see pluggable-authentication.  For characteristics of
     specific authentication plugins, see
     authentication-plugins.

   * A password-validation plugin for implementing password strength
     policies and assessing the strength of potential passwords.  See
     validate-password.

   * Keyring plugins that provide secure storage for sensitive
     information.  See keyring.

   * (MySQL Enterprise Edition only) MySQL Enterprise Audit, implemented
     using a server plugin, uses the open MySQL Audit API to enable
     standard, policy-based monitoring and logging of connection and
     query activity executed on specific MySQL servers.  Designed to
     meet the Oracle audit specification, MySQL Enterprise Audit
     provides an out of box, easy to use auditing and compliance
     solution for applications that are governed by both internal and
     external regulatory guidelines.

   * (MySQL Enterprise Edition only) MySQL Enterprise Firewall, an
     application-level firewall that enables database administrators to
     permit or deny SQL statement execution based on matching against
     whitelists of accepted statement patterns.  This helps harden MySQL
     Server against attacks such as SQL injection or attempts to exploit
     applications by using them outside of their legitimate query
     workload characteristics.

6.5.1 Authentication Plugins
----------------------------

The following sections describe pluggable authentication methods
available in MySQL and the plugins that implement these methods.  For
general discussion of the authentication process, see
pluggable-authentication.

The default plugin is indicated by the value of the
'default_authentication_plugin' system variable.

6.5.1.1 Native Pluggable Authentication
.......................................

MySQL includes two plugins that implement native authentication; that
is, authentication based on the password hashing methods in use from
before the introduction of pluggable authentication.  This section
describes 'mysql_native_password', which implements authentication
against the 'mysql.user' table using the native password hashing method.
For information about 'mysql_old_password', which implements
authentication using the older (pre-4.1) native password hashing method,
see old-native-pluggable-authentication.  For information about
these password hashing methods, see password-hashing.

The following table shows the plugin names on the server and client
sides.

*Plugin and Library Names for Native Password Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'mysql_native_password'

Client-side plugin     'mysql_native_password'

Library file           None (plugins are built in)

The following sections provide installation and usage information
specific to native pluggable authentication:

   * native-pluggable-authentication-installation

   * native-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.

*Installing Native Pluggable Authentication*

The 'mysql_native_password' plugin exists in server and client forms:

   * The server-side plugin is built into the server, need not be loaded
     explicitly, and cannot be disabled by unloading it.

   * The client-side plugin is built into the 'libmysqlclient' client
     library and is available to any program linked against
     'libmysqlclient'.

*Using Native Pluggable Authentication*

MySQL client programs use 'mysql_native_password' by default.  The
'--default-auth' option can be used as a hint about which client-side
plugin the program can expect to use:

     shell> mysql --default-auth=mysql_native_password ...

6.5.1.2 Old Native Pluggable Authentication
...........................................

MySQL includes two plugins that implement native authentication; that
is, authentication based on the password hashing methods in use from
before the introduction of pluggable authentication.  This section
describes 'mysql_old_password', which implements authentication against
the 'mysql.user' table using the older (pre-4.1) native password hashing
method.  For information about 'mysql_native_password', which implements
authentication using the native password hashing method, see
native-pluggable-authentication.  For information about these password
hashing methods, see password-hashing.

*Note*:

Passwords that use the pre-4.1 hashing method are less secure than
passwords that use the native password hashing method and should be
avoided.  Pre-4.1 passwords are deprecated and support for them
(including the 'mysql_old_password' plugin) was removed in MySQL 5.7.5.
For account upgrade instructions, see account-upgrades.

The following table shows the plugin names on the server and client
sides.

*Plugin and Library Names for Old Native Password Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'mysql_old_password'

Client-side plugin     'mysql_old_password'

Library file           None (plugins are built in)

The following sections provide installation and usage information
specific to old native pluggable authentication:

   * old-native-pluggable-authentication-installation

   * old-native-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.

*Installing Old Native Pluggable Authentication*

The 'mysql_old_password' plugin exists in server and client forms:

   * The server-side plugin is built into the server, need not be loaded
     explicitly, and cannot be disabled by unloading it.

   * The client-side plugin is built into the 'libmysqlclient' client
     library and is available to any program linked against
     'libmysqlclient'.

*Using Old Native Pluggable Authentication*

MySQL client programs can use the '--default-auth' option to specify the
'mysql_old_password' plugin as a hint about which client-side plugin the
program can expect to use:

     shell> mysql --default-auth=mysql_old_password ...

6.5.1.3 Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password Plugin
......................................................................................

The MySQL server authenticates connection attempts for each account
listed in the 'mysql.user' table using the authentication plugin named
in the 'plugin' column.  If the 'plugin' column is empty, the server
authenticates the account as follows:

   * Before MySQL 5.7, the server uses the 'mysql_native_password' or
     'mysql_old_password' plugin implicitly, depending on the format of
     the password hash in the 'Password' column.  If the 'Password'
     value is empty or a 4.1 password hash (41 characters), the server
     uses 'mysql_native_password'.  If the password value is a pre-4.1
     password hash (16 characters), the server uses
     'mysql_old_password'.  (For additional information about these hash
     formats, see password-hashing.)

   * As of MySQL 5.7, the server requires the 'plugin' column to be
     nonempty and disables accounts that have an empty 'plugin' value.

Pre-4.1 password hashes and the 'mysql_old_password' plugin are
deprecated in MySQL 5.6 and support for them is removed in MySQL 5.7.
They provide a level of security inferior to that offered by 4.1
password hashing and the 'mysql_native_password' plugin.

Given the requirement in MySQL 5.7 that the 'plugin' column must be
nonempty, coupled with removal of 'mysql_old_password' support, DBAs are
advised to upgrade accounts as follows:

   * Upgrade accounts that use 'mysql_native_password' implicitly to use
     it explicitly

   * Upgrade accounts that use 'mysql_old_password' (either implicitly
     or explicitly) to use 'mysql_native_password' explicitly

The instructions in this section describe how to perform those upgrades.
The result is that no account has an empty 'plugin' value and no account
uses pre-4.1 password hashing or the 'mysql_old_password' plugin.

As a variant on these instructions, DBAs might offer users the choice to
upgrade to the 'sha256_password' plugin, which authenticates using
SHA-256 password hashes.  For information about this plugin, see
sha256-pluggable-authentication.

The following table lists the types of 'mysql.user' accounts considered
in this discussion.

'plugin' Column        'Password'     Authentication         Upgrade
                       Column         Result                 Action

Empty                  Empty          Implicitly uses        Assign
                                      'mysql_native_password'plugin

Empty                  4.1 hash       Implicitly uses        Assign
                                      'mysql_native_password'plugin

Empty                  Pre-4.1 hash   Implicitly uses        Assign
                                      'mysql_old_password'   plugin,
                                                             rehash
                                                             password

'mysql_native_password'Empty          Explicitly uses        None
                                      'mysql_native_password'

'mysql_native_password'4.1 hash       Explicitly uses        None
                                      'mysql_native_password'

'mysql_old_password'   Empty          Explicitly uses        Upgrade
                                      'mysql_old_password'   plugin

'mysql_old_password'   Pre-4.1 hash   Explicitly uses        Upgrade
                                      'mysql_old_password'   plugin,
                                                             rehash
                                                             password

Accounts corresponding to lines for the 'mysql_native_password' plugin
require no upgrade action (because no change of plugin or hash format is
required).  For accounts corresponding to lines for which the password
is empty, consider asking the account owners to choose a password (or
require it by using 'ALTER USER' to expire empty
account passwords).

*Upgrading Accounts from Implicit to Explicit mysql_native_password Use*

Accounts that have an empty plugin and a 4.1 password hash use
'mysql_native_password' implicitly.  To upgrade these accounts to use
'mysql_native_password' explicitly, execute these statements:

     UPDATE mysql.user SET plugin = 'mysql_native_password'
     WHERE plugin = '' AND (Password = '' OR LENGTH(Password) = 41);
     FLUSH PRIVILEGES;

Before MySQL 5.7, you can execute those statements to uprade accounts
proactively.  As of MySQL 5.7, you can run 'mysql_upgrade',
which performs the same operation among its upgrade
actions.

Notes:

   * The upgrade operation just described is safe to execute at any time
     because it makes the 'mysql_native_password' plugin explicit only
     for accounts that already use it implicitly.

   * This operation requires no password changes, so it can be performed
     without affecting users or requiring their involvement in the
     upgrade process.

*Upgrading Accounts from mysql_old_password to mysql_native_password*

Accounts that use 'mysql_old_password' (either implicitly or explicitly)
should be upgraded to use 'mysql_native_password' explicitly.  This
requires changing the plugin _and_ changing the password from pre-4.1 to
4.1 hash format.

For the accounts covered in this step that must be upgraded, one of
these conditions is true:

   * The account uses 'mysql_old_password' implicitly because the
     'plugin' column is empty and the password has the pre-4.1 hash
     format (16 characters).

   * The account uses 'mysql_old_password' explicitly.

To identify such accounts, use this query:

     SELECT User, Host, Password FROM mysql.user
     WHERE (plugin = '' AND LENGTH(Password) = 16)
     OR plugin = 'mysql_old_password';

The following discussion provides two methods for updating that set of
accounts.  They have differing characteristics, so read both and decide
which is most suitable for a given MySQL installation.

*Method 1.*

Characteristics of this method:

   * It requires that server and clients be run with 'secure_auth=0'
     until all users have been upgraded to 'mysql_native_password'.
     (Otherwise, users cannot connect to the server using their
     old-format password hashes for the purpose of upgrading to a
     new-format hash.)

   * It works for MySQL 5.5 and 5.6.  In 5.7, it does not work because
     the server requires accounts to have a nonempty plugin and disables
     them otherwise.  Therefore, if you have already upgraded to 5.7,
     choose Method 2, described later.

You should ensure that the server is running with 'secure_auth=0'.

For all accounts that use 'mysql_old_password' explicitly, set them to
the empty plugin:

     UPDATE mysql.user SET plugin = ''
     WHERE plugin = 'mysql_old_password';
     FLUSH PRIVILEGES;

To also expire the password for affected accounts, use these statements
instead:

     UPDATE mysql.user SET plugin = '', password_expired = 'Y'
     WHERE plugin = 'mysql_old_password';
     FLUSH PRIVILEGES;

Now affected users can reset their password to use 4.1 hashing.  Ask
each user who now has an empty plugin to connect to the server and
execute these statements:

     SET old_passwords = 0;
     SET PASSWORD = PASSWORD('USER-CHOSEN-PASSWORD');

*Note*:

The client-side '--secure-auth' option is enabled by default, so remind
users to disable it or they will be unable to connect:

     shell> mysql -u USER_NAME -p --secure-auth=0

After an affected user has executed those statements, you can set the
corresponding account plugin to 'mysql_native_password' to make the
plugin explicit.  Or you can periodically run these statements to find
and fix any accounts for which affected users have reset their password:

     UPDATE mysql.user SET plugin = 'mysql_native_password'
     WHERE plugin = '' AND (Password = '' OR LENGTH(Password) = 41);
     FLUSH PRIVILEGES;

When there are no more accounts with an empty plugin, this query returns
an empty result:

     SELECT User, Host, Password FROM mysql.user
     WHERE plugin = '' AND LENGTH(Password) = 16;

At that point, all accounts have been migrated away from pre-4.1
password hashing and the server no longer need be run with
'secure_auth=0'.

*Method 2.*

Characteristics of this method:

   * It assigns each affected account a new password, so you must tell
     each such user the new password and ask the user to choose a new
     one.  Communication of passwords to users is outside the scope of
     MySQL, but should be done carefully.

   * It does not require server or clients to be run with
     'secure_auth=0'.

   * It works for any version of MySQL 5.5 or later (and for 5.7 has an
     easier variant).

With this method, you update each account separately due to the need to
set passwords individually.  _Choose a different password for each
account._

Suppose that ''user1'@'localhost'' is one of the accounts to be
upgraded.  Modify it as follows:

   * In MySQL 5.7, 'ALTER USER' provides the capability of modifying
     both the account password and its authentication plugin, so you
     need not modify the 'mysql.user' table directly:

          ALTER USER 'user1'@'localhost'
          IDENTIFIED WITH mysql_native_password BY 'DBA-CHOSEN-PASSWORD';

     To also expire the account password, use this statement instead:

          ALTER USER 'user1'@'localhost'
          IDENTIFIED WITH mysql_native_password BY 'DBA-CHOSEN-PASSWORD'
          PASSWORD EXPIRE;

     Then tell the user the new password and ask the user to connect to
     the server with that password and execute this statement to choose
     a new password:

          ALTER USER USER() IDENTIFIED BY 'USER-CHOSEN-PASSWORD';

   * Before MySQL 5.7, you must modify the 'mysql.user' table directly
     using these statements:

          SET old_passwords = 0;
          UPDATE mysql.user SET plugin = 'mysql_native_password',
          Password = PASSWORD('DBA-CHOSEN-PASSWORD')
          WHERE (User, Host) = ('user1', 'localhost');
          FLUSH PRIVILEGES;

     To also expire the account password, use these statements instead:

          SET old_passwords = 0;
          UPDATE mysql.user SET plugin = 'mysql_native_password',
          Password = PASSWORD('DBA-CHOSEN-PASSWORD'), password_expired = 'Y'
          WHERE (User, Host) = ('user1', 'localhost');
          FLUSH PRIVILEGES;

     Then tell the user the new password and ask the user to connect to
     the server with that password and execute these statements to
     choose a new password:

          SET old_passwords = 0;
          SET PASSWORD = PASSWORD('USER-CHOSEN-PASSWORD');

Repeat for each account to be upgraded.

6.5.1.4 SHA-256 Pluggable Authentication
........................................

MySQL provides an authentication plugin that implements SHA-256 hashing
for user account passwords.

*Important*:

To connect to the server using an account that authenticates with the
'sha256_password' plugin, you must use either a TLS connection or an
unencrypted connection that supports password exchange using an RSA key
pair, as described later in this section.  Either way, the
'sha256_password' plugin uses MySQL's encryption capabilities.  See
encrypted-connections.

The following table shows the plugin names on the server and client
sides.

*Plugin and Library Names for SHA-256 Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'sha256_password'

Client-side plugin     'sha256_password'

Library file           None (plugins are built in)

The following sections provide installation and usage information
specific to SHA-256 pluggable authentication:

   * sha256-pluggable-authentication-installation

   * sha256-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.

*Installing SHA-256 Pluggable Authentication*

The 'sha256_password' plugin exists in server and client forms:

   * The server-side plugin is built into the server, need not be loaded
     explicitly, and cannot be disabled by unloading it.

   * The client-side plugin is built into the 'libmysqlclient' client
     library and is available to any program linked against
     'libmysqlclient'.

*Using SHA-256 Pluggable Authentication*

To set up an account that uses the 'sha256_password' plugin for SHA-256
password hashing, use the following statement, where PASSWORD is the
desired account password:

     CREATE USER 'sha256user'@'localhost'
     IDENTIFIED WITH sha256_password BY 'PASSWORD';

The server assigns the 'sha256_password' plugin to the account and uses
it to encrypt the password using SHA-256, storing those values in the
'plugin' and 'authentication_string' columns of the 'mysql.user' system
table.

The preceding instructions do not assume that 'sha256_password' is the
default authentication plugin.  If 'sha256_password' is the default
authentication plugin, a simpler 'CREATE USER'.
syntax can be used.

To start the server with the default authentication plugin set to
'sha256_password', put these lines in the server option file:

     [mysqld]
     default_authentication_plugin=sha256_password

That causes the 'sha256_password' plugin to be used by default for new
accounts.  As a result, it is possible to create the account and set its
password without naming the plugin explicitly:

     CREATE USER 'sha256user'@'localhost' IDENTIFIED BY 'PASSWORD';

Another consequence of setting 'default_authentication_plugin' to
'sha256_password' is that, to use some other plugin for account
creation, you must specify that plugin explicitly.  For example, to use
the 'mysql_native_password' plugin, use this statement:

     CREATE USER 'nativeuser'@'localhost'
     IDENTIFIED WITH mysql_native_password BY 'PASSWORD';

MySQL can be compiled using either OpenSSL or yaSSL (see
ssl-libraries).  The 'sha256_password' plugin works with distributions
compiled using either package, but if MySQL is compiled using OpenSSL,
'sha256_password' supports the use of RSA encryption.  (To enable this
capability, you must follow the RSA configuration procedure given later
in this section.)  RSA support has these characteristics:

   * Two system variables name the RSA private and public key-pair
     files: 'sha256_password_private_key_path' and
     'sha256_password_public_key_path'.  The database administrator must
     set these variables at server startup if the key files to use have
     names that differ from the system variable default values.

   * The server uses the 'sha256_password_auto_generate_rsa_keys' system
     variable to determine whether to automatically generate the RSA
     key-pair files.  See creating-ssl-rsa-files.

   * The 'Rsa_public_key' status variable displays the RSA public key
     value used by the 'sha256_password' authentication plugin.

   * Clients that have the RSA public key can perform RSA key pair-based
     password exchange with the server during the connection process, as
     described later.

   * For connections by accounts that authenticate using
     'sha256_password' and RSA public key pair-based password exchange,
     the server sends the RSA public key to the client as needed.
     However, if a copy of the public key is available on the client
     host, the client can use it to save a round trip in the
     client/server protocol:

        * For these command-line clients, use the
          '--server-public-key-path' option to specify the RSA public
          key file: 'mysql', 'mysqltest'.

        * For programs that use the C API, call 'mysql_options()'
          to specify the RSA public key file by passing
          the 'MYSQL_SERVER_PUBLIC_KEY' option and the name of the file.

        * For replication slaves, RSA key pair-based password exchange
          cannot be used to connect to master servers for accounts that
          authenticate with the 'sha256_password' plugin.  For such
          accounts, only secure connections can be used.

For clients that use the 'sha256_password' plugin, passwords are never
exposed as cleartext when connecting to the server.  How password
transmission occurs depends on whether a secure connection or RSA
encryption is used:

   * If the connection is secure, an RSA key pair is unnecessary and is
     not used.  This applies to encrypted connections that use TLS. The
     password is sent as cleartext but cannot be snooped because the
     connection is secure.

   * If the connection is not secure, and an RSA key pair is available,
     the connection remains unencrypted.  This applies to unencrypted
     connections without TLS. RSA is used only for password exchange
     between client and server, to prevent password snooping.  When the
     server receives the encrypted password, it decrypts it.  A scramble
     is used in the encryption to prevent repeat attacks.

   * If a secure connection is not used and RSA encryption is not
     available, the connection attempt fails because the password cannot
     be sent without being exposed as cleartext.

As mentioned previously, RSA password encryption is available only if
MySQL was compiled using OpenSSL. The implication for MySQL
distributions compiled using yaSSL is that, to use SHA-256 passwords,
clients _must_ use an encrypted connection to access the server.  See
using-encrypted-connections.

*Note*:

To use RSA password encryption with 'sha256_password', the client and
server both must be compiled using OpenSSL, not just one of them.

Assuming that MySQL has been compiled using OpenSSL, use the following
procedure to enable use of an RSA key pair for password exchange during
the client connection process:

  1. Create the RSA private and public key-pair files using the
     instructions in creating-ssl-rsa-files.

  2. If the private and public key files are located in the data
     directory and are named 'private_key.pem' and 'public_key.pem' (the
     default values of the 'sha256_password_private_key_path' and
     'sha256_password_public_key_path' system variables), the server
     uses them automatically at startup.

     Otherwise, to name the key files explicitly, set the system
     variables to the key file names in the server option file.  If the
     files are located in the server data directory, you need not
     specify their full path names:

          [mysqld]
          sha256_password_private_key_path=myprivkey.pem
          sha256_password_public_key_path=mypubkey.pem

     If the key files are not located in the data directory, or to make
     their locations explicit in the system variable values, use full
     path names:

          [mysqld]
          sha256_password_private_key_path=/usr/local/mysql/myprivkey.pem
          sha256_password_public_key_path=/usr/local/mysql/mypubkey.pem

  3. Restart the server, then connect to it and check the
     'Rsa_public_key' status variable value.  The value will differ from
     that shown here, but should be nonempty:

          mysql> SHOW STATUS LIKE 'Rsa_public_key'\G
          *************************** 1. row ***************************
          Variable_name: Rsa_public_key
                  Value: -----BEGIN PUBLIC KEY-----
          MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDO9nRUDd+KvSZgY7cNBZMNpwX6
          MvE1PbJFXO7u18nJ9lwc99Du/E7lw6CVXw7VKrXPeHbVQUzGyUNkf45Nz/ckaaJa
          aLgJOBCIDmNVnyU54OT/1lcs2xiyfaDMe8fCJ64ZwTnKbY2gkt1IMjUAB5Ogd5kJ
          g8aV7EtKwyhHb0c30QIDAQAB
          -----END PUBLIC KEY-----

     If the value is empty, the server found some problem with the key
     files.  Check the error log for diagnostic information.

After the server has been configured with the RSA key files, accounts
that authenticate with the 'sha256_password' plugin have the option of
using those key files to connect to the server.  As mentioned
previously, such accounts can use either a secure connection (in which
case RSA is not used) or an unencrypted connection that performs
password exchange using RSA. Suppose that an unencrypted connection is
used.  For example:

     shell> mysql --ssl-mode=DISABLED -u sha256user -p
     Enter password: PASSWORD

For this connection attempt by 'sha256user', the server determines that
'sha256_password' is the appropriate authentication plugin and invokes
it (because that was the plugin specified at 'CREATE USER'
time).  The plugin finds that the connection is not
encrypted and thus requires the password to be transmitted using RSA
encryption.  In this case, the plugin sends the RSA public key to the
client, which uses it to encrypt the password and returns the result to
the server.  The plugin uses the RSA private key on the server side to
decrypt the password and accepts or rejects the connection based on
whether the password is correct.

The server sends the RSA public key to the client as needed.  However,
if the client has a file containing a local copy of the RSA public key
required by the server, it can specify the file using the
'--server-public-key-path' option:

     shell> mysql --ssl-mode=DISABLED -u sha256user -p --server-public-key-path=FILE_NAME
     Enter password: PASSWORD

The public key value in the file named by the '--server-public-key-path'
option should be the same as the key value in the server-side file named
by the 'sha256_password_public_key_path' system variable.  If the key
file contains a valid public key value but the value is incorrect, an
access-denied error occurs.  If the key file does not contain a valid
public key, the client program cannot use it.  In this case, the
'sha256_password' plugin sends the public key to the client as if no
'--server-public-key-path' option had been specified.

Client users can obtain the RSA public key two ways:

   * The database administrator can provide a copy of the public key
     file.

   * A client user who can connect to the server some other way can use
     a 'SHOW STATUS LIKE 'Rsa_public_key'' statement and save the
     returned key value in a file.

6.5.1.5 Client-Side Cleartext Pluggable Authentication
......................................................

A client-side authentication plugin is available that sends the password
to the server without hashing or encryption.  This plugin is built into
the MySQL client library.

The following table shows the plugin name.

*Plugin and Library Names for Cleartext Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     None, see discussion

Client-side plugin     'mysql_clear_password'

Library file           None (plugin is built in)

With many MySQL authentication methods, the client performs hashing or
encryption of the password before sending it to the server.  This
enables the client to avoid sending the password in clear text.

Hashing or encryption cannot be done for authentication schemes that
require the server to receive the password as entered on the client
side.  In such cases, the client-side 'mysql_clear_password' plugin is
used to send the password to the server in clear text.  There is no
corresponding server-side plugin.  Rather, the client-side plugin can be
used by any server-side plugin that needs a cleartext password.
(Examples are the PAM and simple LDAP authentication plugins; see
pam-pluggable-authentication, and
ldap-pluggable-authentication.)

The following discussion provides usage information specific to clear
text pluggable authentication.  For For general information about
pluggable authentication in MySQL, see pluggable-authentication.

*Note*:

Sending passwords in clear text may be a security problem in some
configurations.  To avoid problems if there is any possibility that the
password would be intercepted, clients should connect to MySQL Server
using a method that protects the password.  Possibilities include SSL
(see encrypted-connections), IPsec, or a private network.

To make inadvertent use of the 'mysql_clear_password' plugin less
likely, MySQL clients must explicitly enable it.  This can be done in
several ways:

   * Set the 'LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN' environment variable to
     a value that begins with '1', 'Y', or 'y'.  This enables the plugin
     for all client connections.

   * The 'mysql', 'mysqladmin', and
     'mysqlslap' client programs (also 'mysqlcheck',
     see 'mysqldump', and 'mysqlshow'
     for MySQL 5.7.10 and later) support an
     '--enable-cleartext-plugin' option that enables the plugin on a
     per-invocation basis.

   * The 'mysql_options()'. C API function supports
     a 'MYSQL_ENABLE_CLEARTEXT_PLUGIN' option that enables the plugin on
     a per-connection basis.  Also, any program that uses
     'libmysqlclient' and reads option files can enable the plugin by
     including an 'enable-cleartext-plugin' option in an option group
     read by the client library.

6.5.1.6 PAM Pluggable Authentication
....................................

*Note*:

PAM pluggable authentication is an extension included in MySQL
Enterprise Edition, a commercial product.  To learn more about
commercial products, see <http://www.mysql.com/products/>.

MySQL Enterprise Edition supports an authentication method that enables
MySQL Server to use PAM (Pluggable Authentication Modules) to
authenticate MySQL users.  PAM enables a system to use a standard
interface to access various kinds of authentication methods, such as
Unix passwords or an LDAP directory.

PAM pluggable authentication provides these capabilities:

   * External authentication: PAM authentication enables MySQL Server to
     accept connections from users defined outside the MySQL grant
     tables and that authenticate using methods supported by PAM.

   * Proxy user support: PAM authentication can return to MySQL a user
     name different from the login user, based on the groups the
     external user is in and the authentication string provided.  This
     means that the plugin can return the MySQL user that defines the
     privileges the external PAM-authenticated user should have.  For
     example, a user named 'joe' can connect and have the privileges of
     the user named 'developer'.

PAM pluggable authentication has been tested on Linux and macOS.

The PAM plugin uses the information passed to it by MySQL Server (such
as user name, host name, password, and authentication string), plus
whatever method is available for PAM lookup.  The plugin checks the user
credentials against PAM and returns ''Authentication succeeded, Username
is USER_NAME'' or ''Authentication failed''.

The following table shows the plugin and library file names.  The file
name suffix might differ on your system.  The file must be located in
the directory named by the 'plugin_dir' system variable.  For
installation information, see
pam-pluggable-authentication-installation.

*Plugin and Library Names for PAM Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'authentication_pam'

Client-side plugin     'mysql_clear_password'

Library file           'authentication_pam.so'

The client-side clear-text plugin that communicates with the server-side
PAM plugin is built into the 'libmysqlclient' client library and is
included in all distributions, including community distributions.
Inclusion of the client-side clear-text plugin in all MySQL
distributions enables clients from any distribution to connect to a
server that has the server-side plugin loaded.

The following sections provide installation and usage information
specific to PAM pluggable authentication:

   * pam-pluggable-authentication-installation

   * pam-pluggable-authentication-uninstallation

   * pam-pluggable-authentication-usage

   * pam-authentication-unix-without-proxy

   * pam-authentication-ldap-without-proxy

   * pam-authentication-unix-with-proxy

   * pam-pluggable-authentication-debugging

For general information about pluggable authentication in MySQL, see
pluggable-authentication.  For information about the
'mysql_clear_password' plugin, see
cleartext-pluggable-authentication.  For proxy user information, see
proxy-users.

*Installing PAM Pluggable Authentication*

This section describes how to install the PAM authentication plugin.
For general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The plugin library file base name is 'authentication_pam'.  The file
name suffix differs per platform (for example, '.so' for Unix and
Unix-like systems, '.dll' for Windows).

To load the plugin at server startup, use the '--plugin-load-add' option
to name the library file that contains it.  With this plugin-loading
method, the option must be given each time the server starts.  For
example, put these lines in your 'my.cnf' file (adjust the '.so' suffix
for your platform as necessary):

     [mysqld]
     plugin-load-add=authentication_pam.so

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugin at runtime, use this statement
(adjust the '.so' suffix as necessary):

     INSTALL PLUGIN authentication_pam SONAME 'authentication_pam.so';

'INSTALL PLUGIN' loads a plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE '%pam%';
     +--------------------+---------------+
     | PLUGIN_NAME        | PLUGIN_STATUS |
     +--------------------+---------------+
     | authentication_pam | ACTIVE        |
     +--------------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

To associate MySQL accounts with the PAM plugin, see
pam-pluggable-authentication-usage.

*Uninstalling PAM Pluggable Authentication*

The method used to uninstall the PAM authentication plugin depends on
how you installed it:

   * If you installed the plugin at server startup using a
     '--plugin-load-add' option, restart the server without the option.

   * If you installed the plugin at runtime using 'INSTALL PLUGIN',
     it remains installed across server
     restarts.  To uninstall it, use 'UNINSTALL PLUGIN'.:

          UNINSTALL PLUGIN authentication_pam;

*Using PAM Pluggable Authentication*

This section describes how to use the PAM authentication plugin to
connect from MySQL client programs to the server.  It is assumed that
the server is running with the server-side plugin enabled, as described
in pam-pluggable-authentication-installation.

To refer to the PAM authentication plugin in the 'IDENTIFIED WITH'
clause of a 'CREATE USER' statement, use the name
'authentication_pam'.  For example:

     CREATE USER USER
       IDENTIFIED WITH authentication_pam
       AS 'AUTHENTICATION_STRING';

The authentication string specifies the following types of information:

   * PAM supports the notion of 'service name,' which is a name that the
     system administrator can use to configure the authentication method
     for a particular application.  There can be several such
     'applications' associated with a single database server instance,
     so the choice of service name is left to the SQL application
     developer.  When you define an account that should authenticate
     using PAM, specify the service name in the authentication string.

   * PAM provides a way for a PAM module to return to the server a MySQL
     user name other than the login name supplied at login time.  Use
     the authentication string to control the mapping between login name
     and MySQL user name.  If you want to take advantage of proxy user
     capabilities, the authentication string must include this kind of
     mapping.

For example, if the service name is 'mysql' and users in the 'root' and
'users' PAM groups should be mapped to the 'developer' and 'data_entry'
MySQL users, respectively, use a statement like this:

     CREATE USER USER
       IDENTIFIED WITH authentication_pam
       AS 'mysql, root=developer, users=data_entry';

Authentication string syntax for the PAM authentication plugin follows
these rules:

   * The string consists of a PAM service name, optionally followed by a
     group mapping list consisting of one or more keyword/value pairs
     each specifying a group name and a MySQL user name:

          PAM_SERVICE_NAME[,GROUP_NAME=MYSQL_USER_NAME]...

     The plugin parses the authentication string on each login check.
     To minimize overhead, keep the string as short as possible.

   * Each 'GROUP_NAME=MYSQL_USER_NAME' pair must be preceded by a comma.

   * Leading and trailing spaces not inside double quotation marks are
     ignored.

   * Unquoted PAM_SERVICE_NAME, GROUP_NAME, and MYSQL_USER_NAME values
     can contain anything except equal sign, comma, or space.

   * If a PAM_SERVICE_NAME, GROUP_NAME, or MYSQL_USER_NAME value is
     quoted with double quotation marks, everything between the
     quotation marks is part of the value.  This is necessary, for
     example, if the value contains space characters.  All characters
     are legal except double quotation mark and backslash ('\').  To
     include either character, escape it with a backslash.

If the plugin successfully authenticates a login name, it looks for a
group mapping list in the authentication string and, if present, uses it
to return a different user name to the MySQL server based on the groups
the external user is a member of:

   * If the authentication string contains no group mapping list, the
     plugin returns the login name.

   * If the authentication string does contain a group mapping list, the
     plugin examines each 'GROUP_NAME=MYSQL_USER_NAME' pair in the list
     from left to right and tries to find a match for the GROUP_NAME
     value in a non-MySQL directory of the groups assigned to the
     authenticated user and returns MYSQL_USER_NAME for the first match
     it finds.  If the plugin finds no match for any group, it returns
     the login name.  If the plugin is not capable of looking up a group
     in a directory, it ignores the group mapping list and returns the
     login name.

The following sections describe how to set up several authentication
scenarios that use the PAM authentication plugin:

   * No proxy users.  This uses PAM only to check login names and
     passwords.  Every external user permitted to connect to MySQL
     Server should have a matching MySQL account that is defined to use
     external PAM authentication.  (For a MySQL account of
     'USER_NAME@HOST_NAME' to match the external user, USER_NAME must be
     the login name and HOST_NAME must match the host from which the
     client connects.)  Authentication can be performed by various
     PAM-supported methods.  The discussion shows how to use traditional
     Unix passwords and LDAP.

     PAM authentication, when not done through proxy users or groups,
     requires the MySQL account to have the same user name as the Unix
     account.  MySQL user names are limited to 32 characters (see
     grant-tables), which limits PAM nonproxy authentication to Unix
     accounts with names of at most 32 characters.

   * Proxy login only and group mapping.  For this scenario, create one
     or a few MySQL accounts that define different sets of privileges.
     (Ideally, nobody should connect using those accounts directly.)
     Then define a default user authenticating through PAM that uses
     some mapping scheme (usually by the external groups the users are
     in) to map all the external logins to the few MySQL accounts
     holding the privilege sets.  Any user that logs in is mapped to one
     of the MySQL accounts and uses its privileges.  The discussion
     shows how to set this up using Unix passwords, but other PAM
     methods such as LDAP could be used instead.

Variations on these scenarios are possible.  For example, you can permit
some users to log in directly (without proxying) but require others to
connect through proxy users.

The examples make the following assumptions.  You might need to make
some adjustments if your system is set up differently.

   * The PAM configuration directory is '/etc/pam.d'.

   * The PAM service name is 'mysql', which means that you must set up a
     PAM file named 'mysql' in the PAM configuration directory (creating
     the file if it does not exist).  If you use a service name
     different from 'mysql', the file name will differ and you must use
     a different name in the 'AS 'AUTH_STRING'' clause of 'CREATE USER'
     statements.

   * The examples use a login name of 'antonio' and password of
     'verysecret'.  Change these to correspond to the users you want to
     authenticate.

The PAM authentication plugin checks at initialization time whether the
'AUTHENTICATION_PAM_LOG' environment value is set in the server's
startup environment.  If so, the plugin enables logging of diagnostic
messages to the standard output.  Depending on how your server is
started, the message might appear on the console or in the error log.
These messages can be helpful for debugging PAM-related problems that
occur when the plugin performs authentication.  For more information,
see pam-pluggable-authentication-debugging.

*Unix Password Authentication without Proxy Users*

This authentication scenario uses PAM only to check Unix user login
names and passwords.  Every external user permitted to connect to MySQL
Server should have a matching MySQL account that is defined to use
external PAM authentication.

  1. Verify that Unix authentication in PAM permits you to log in as
     'antonio' with password 'verysecret'.

  2. Set up PAM to authenticate the 'mysql' service by creating a file
     named '/etc/pam.d/mysql'.  The file contents are system dependent,
     so check existing login-related files in the '/etc/pam.d' directory
     to see what they look like.  On Linux, the 'mysql' file might look
     like this:

          #%PAM-1.0
          auth            include         password-auth
          account         include         password-auth

     For Gentoo Linux, use 'system-login' rather than 'password-auth'.
     For macOS, use 'login' rather than 'password-auth'.

     The PAM file format might differ on some systems.  For example, on
     Ubuntu and other Debian-based systems, use these file contents
     instead:

          @include common-auth
          @include common-account
          @include common-session-noninteractive

  3. Create a MySQL account with the same user name as the Unix login
     name and define it to authenticate using the PAM plugin:

          CREATE USER 'antonio'@'localhost'
            IDENTIFIED WITH authentication_pam AS 'mysql';
          GRANT ALL PRIVILEGES ON mydb.* TO 'antonio'@'localhost';

  4. Connect to the MySQL server using the 'mysql'.
     command-line client.  For example:

          mysql --user=antonio --password --enable-cleartext-plugin mydb
          Enter password: verysecret

     The server should permit the connection and the following query
     should return output as shown:

          mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
          +-------------------+-------------------+--------------+
          | USER()            | CURRENT_USER()    | @@proxy_user |
          +-------------------+-------------------+--------------+
          | antonio@localhost | antonio@localhost | NULL         |
          +-------------------+-------------------+--------------+

     This demonstrates that 'antonio' uses the privileges granted to the
     'antonio' MySQL account, and that no proxying has occurred.

*Note*:

The client-side 'mysql_clear_password' plugin with which the server-side
PAM plugin communicates sends the password to the MySQL server in clear
text so it can be passed to PAM. This is necessary to use the
server-side PAM library, but may be a security problem in some
configurations.  These measures minimize the risk:

   * To make inadvertent use of the 'mysql_clear_password' plugin less
     likely, MySQL clients must explicitly enable it; for example, with
     the '--enable-cleartext-plugin' option.

   * To avoid password exposure with the 'mysql_clear_password' plugin
     enabled, MySQL clients should connect to the MySQL server using a
     secure connection.

For additinal information, see
cleartext-pluggable-authentication, and
using-encrypted-connections.

*Note*:

On some systems, Unix authentication uses '/etc/shadow', a file that
typically has restricted access permissions.  This can cause MySQL
PAM-based authentication to fail.  Unfortunately, the PAM implementation
does not permit distinguishing 'password could not be checked' (due, for
example, to inability to read '/etc/shadow') from 'password does not
match.' If your system uses '/etc/shadow', you may be able enable access
to it by MySQL using this method (assuming that the MySQL server is run
from the 'mysql' system account):

  1. Create a 'shadow' group in '/etc/group'.

  2. Add the 'mysql' user to the 'shadow' group in '/etc/group'.

  3. Assign '/etc/group' to the 'shadow' group and enable the group read
     permission:

          chgrp shadow /etc/shadow
          chmod g+r /etc/shadow

  4. Restart the MySQL server.

*LDAP Authentication without Proxy Users*

This authentication scenario uses PAM only to check LDAP user login
names and passwords.  Every external user permitted to connect to MySQL
Server should have a matching MySQL account that is defined to use
external PAM authentication.

  1. Verify that LDAP authentication in PAM permits you to log in as
     'antonio' with password 'verysecret'.

  2. Set up PAM to authenticate the 'mysql' service through LDAP by
     creating a file named '/etc/pam.d/mysql'.  The file contents are
     system dependent, so check existing login-related files in the
     '/etc/pam.d' directory to see what they look like.  On Linux, the
     'mysql' file might look like this:

          #%PAM-1.0
          auth        required    pam_ldap.so
          account     required    pam_ldap.so

     If PAM object files have a suffix different from '.so' on your
     system, substitute the correct suffix.

     The PAM file format might differ on some systems.

  3. MySQL account creation and connecting to the server is the same as
     described in pam-authentication-unix-without-proxy.

*Unix Password Authentication with Proxy Users and Group Mapping*

The authentication scheme described here uses proxying and group mapping
to map connecting MySQL users who authenticate using PAM onto other
MySQL accounts that define different sets of privileges.  Users do not
connect directly through the accounts that define the privileges.
Instead, they connect through a default proxy user authenticated using
PAM, such that all the external logins are mapped to the MySQL accounts
that hold the privileges.  Any user who connects is mapped to one of
those MySQL accounts, the privileges for which determine the database
operations permitted to the external user.

The procedure shown here uses Unix password authentication.  To use LDAP
instead, see the early steps of
pam-authentication-ldap-without-proxy.

*Note*:

For information regarding possible problems related to '/etc/shadow',
see pam-authentication-unix-without-proxy.

  1. Verify that Unix authentication in PAM permits you to log in as
     'antonio' with password 'verysecret' and that 'antonio' is a member
     of the 'root' or 'users' group.

  2. Set up PAM to authenticate the 'mysql' service.  Put the following
     in '/etc/pam.d/mysql':

          #%PAM-1.0
          auth            include         password-auth
          account         include         password-auth

     For Gentoo Linux, use 'system-login' rather than 'password-auth'.
     For macOS, use 'login' rather than 'password-auth'.

     The PAM file format might differ on some systems.  For example, on
     Ubuntu and other Debian-based systems, use these file contents
     instead:

          @include common-auth
          @include common-account
          @include common-session-noninteractive

  3. Create a default proxy user ('''@''') that maps the external PAM
     users to the proxied accounts.  It maps external users from the
     'root' PAM group to the 'developer' MySQL account and the external
     users from the 'users' PAM group to the 'data_entry' MySQL account:

          CREATE USER ''@''
            IDENTIFIED WITH authentication_pam
            AS 'mysql, root=developer, users=data_entry';

     The mapping list following the service name is required when you
     set up proxy users.  Otherwise, the plugin cannot tell how to map
     the name of PAM groups to the proper proxied user name.

     *Note*:

     If your MySQL installation has anonymous users, they might conflict
     with the default proxy user.  For more information about this
     problem, and ways of dealing with it, see
     proxy-users-conflicts.

  4. Create the proxied accounts that will be used to access the
     databases:

          CREATE USER 'developer'@'localhost' IDENTIFIED BY 'VERY SECRET PASSWORD';
          GRANT ALL PRIVILEGES ON mydevdb.* TO 'developer'@'localhost';
          CREATE USER 'data_entry'@'localhost' IDENTIFIED BY 'VERY SECRET PASSWORD';
          GRANT ALL PRIVILEGES ON mydb.* TO 'data_entry'@'localhost';

     If you do not let anyone know the passwords for these accounts,
     other users cannot use them to connect directly to the MySQL
     server.  Instead, it is expected that users will authenticate using
     PAM and that they will use the 'developer' or 'data_entry' account
     by proxy based on their PAM group.

  5. Grant the 'PROXY' privilege to the proxy account for the proxied
     accounts:

          GRANT PROXY ON 'developer'@'localhost' TO ''@'';
          GRANT PROXY ON 'data_entry'@'localhost' TO ''@'';

  6. Connect to the MySQL server using the 'mysql'.
     command-line client.  For example:

          mysql --user=antonio --password --enable-cleartext-plugin mydb
          Enter password: verysecret

     The server authenticates the connection using the '''@''' account.
     The privileges 'antonio' will have depends on what PAM groups he is
     a member of.  If 'antonio' is a member of the 'root' PAM group, the
     PAM plugin maps 'root' to the 'developer' MySQL user name and
     returns that name to the server.  The server verifies that '''@'''
     has the 'PROXY' privilege for 'developer' and permits the
     connection.  the following query should return output as shown:

          mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
          +-------------------+---------------------+--------------+
          | USER()            | CURRENT_USER()      | @@proxy_user |
          +-------------------+---------------------+--------------+
          | antonio@localhost | developer@localhost | ''@''        |
          +-------------------+---------------------+--------------+

     This demonstrates that 'antonio' uses the privileges granted to the
     'developer' MySQL account, and that proxying occurred through the
     default proxy user account.

     If 'antonio' is not a member of the 'root' PAM group but is a
     member of the 'users' group, a similar process occurs, but the
     plugin maps 'user' group membership to the 'data_entry' MySQL user
     name and returns that name to the server.  In this case, 'antonio'
     uses the privileges of the 'data_entry' MySQL account:

          mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
          +-------------------+----------------------+--------------+
          | USER()            | CURRENT_USER()       | @@proxy_user |
          +-------------------+----------------------+--------------+
          | antonio@localhost | data_entry@localhost | ''@''        |
          +-------------------+----------------------+--------------+

*Note*:

The client-side 'mysql_clear_password' plugin with which the server-side
PAM plugin communicates sends the password to the MySQL server in clear
text so it can be passed to PAM. This is necessary to use the
server-side PAM library, but may be a security problem in some
configurations.  These measures minimize the risk:

   * To make inadvertent use of the 'mysql_clear_password' plugin less
     likely, MySQL clients must explicitly enable it; for example, with
     the '--enable-cleartext-plugin' option.

   * To avoid password exposure with the 'mysql_clear_password' plugin
     enabled, MySQL clients should connect to the MySQL server using a
     secure connection.

For additinal information, see
cleartext-pluggable-authentication, and
using-encrypted-connections.

*PAM Pluggable Authentication Debugging*

The PAM authentication plugin checks at initialization time whether the
'AUTHENTICATION_PAM_LOG' environment value is set (the value does not
matter).  If so, the plugin enables logging of diagnostic messages to
the standard output.  These messages may be helpful for debugging
PAM-related problems that occur when the plugin performs authentication.

Some messages include reference to PAM plugin source files and line
numbers, which enables plugin actions to be tied more closely to the
location in the code where they occur.

6.5.1.7 Windows Pluggable Authentication
........................................

*Note*:

Windows pluggable authentication is an extension included in MySQL
Enterprise Edition, a commercial product.  To learn more about
commercial products, see <http://www.mysql.com/products/>.

MySQL Enterprise Edition for Windows supports an authentication method
that performs external authentication on Windows, enabling MySQL Server
to use native Windows services to authenticate client connections.
Users who have logged in to Windows can connect from MySQL client
programs to the server based on the information in their environment
without specifying an additional password.

The client and server exchange data packets in the authentication
handshake.  As a result of this exchange, the server creates a security
context object that represents the identity of the client in the Windows
OS. This identity includes the name of the client account.  Windows
pluggable authentication uses the identity of the client to check
whether it is a given account or a member of a group.  By default,
negotiation uses Kerberos to authenticate, then NTLM if Kerberos is
unavailable.

Windows pluggable authentication provides these capabilities:

   * External authentication: Windows authentication enables MySQL
     Server to accept connections from users defined outside the MySQL
     grant tables who have logged in to Windows.

   * Proxy user support: Windows authentication can return to MySQL a
     user name different from the client user.  This means that the
     plugin can return the MySQL user that defines the privileges the
     external Windows-authenticated user should have.  For example, a
     user named 'joe' can connect and have the privileges of the user
     named 'developer'.

The following table shows the plugin and library file names.  The file
must be located in the directory named by the 'plugin_dir' system
variable.

*Plugin and Library Names for Windows Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'authentication_windows'

Client-side plugin     'authentication_windows_client'

Library file           'authentication_windows.dll'

The library file includes only the server-side plugin.  The client-side
plugin is built into the 'libmysqlclient' client library.

The server-side Windows authentication plugin is included only in MySQL
Enterprise Edition.  It is not included in MySQL community
distributions.  The client-side plugin is included in all distributions,
including community distributions.  This permits clients from any
distribution to connect to a server that has the server-side plugin
loaded.

The Windows authentication plugin is supported on any version of Windows
supported by MySQL 5.7 (see
<http://www.mysql.com/support/supportedplatforms/database.html>).

The following sections provide installation and usage information
specific to Windows pluggable authentication:

   * windows-pluggable-authentication-installation

   * windows-pluggable-authentication-uninstallation

   * windows-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.  For proxy user information, see
proxy-users.

*Installing Windows Pluggable Authentication*

This section describes how to install the Windows authentication plugin.
For general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

To load the plugin at server startup, use the '--plugin-load-add' option
to name the library file that contains it.  With this plugin-loading
method, the option must be given each time the server starts.  For
example, put these lines in your 'my.cnf' file:

     [mysqld]
     plugin-load-add=authentication_windows.dll

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugin at runtime, use this statement:

     INSTALL PLUGIN authentication_windows SONAME 'authentication_windows.dll';

'INSTALL PLUGIN' loads a plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE '%windows%';
     +------------------------+---------------+
     | PLUGIN_NAME            | PLUGIN_STATUS |
     +------------------------+---------------+
     | authentication_windows | ACTIVE        |
     +------------------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

To associate MySQL accounts with the Windows authentication plugin, see
windows-pluggable-authentication-usage.

*Uninstalling Windows Pluggable Authentication*

The method used to uninstall the Windows authentication plugin depends
on how you installed it:

   * If you installed the plugin at server startup using a
     '--plugin-load-add' option, restart the server without the option.

   * If you installed the plugin at runtime using 'INSTALL PLUGIN',
     it remains installed across server
     restarts.  To uninstall it, use 'UNINSTALL PLUGIN'.:

          UNINSTALL PLUGIN authentication_windows;

In addition, remove any startup options that set Windows plugin-related
system variables.

*Using Windows Pluggable Authentication*

The Windows authentication plugin supports the use of MySQL accounts
such that users who have logged in to Windows can connect to the MySQL
server without having to specify an additional password.  It is assumed
that the server is running with the server-side plugin enabled, as
described in windows-pluggable-authentication-installation.
Once the DBA has enabled the server-side plugin and set up accounts to
use it, clients can connect using those accounts with no other setup
required on their part.

To refer to the Windows authentication plugin in the 'IDENTIFIED WITH'
clause of a 'CREATE USER' statement, use the name
'authentication_windows'.  Suppose that the Windows users 'Rafal' and
'Tasha' should be permitted to connect to MySQL, as well as any users in
the 'Administrators' or 'Power Users' group.  To set this up, create a
MySQL account named 'sql_admin' that uses the Windows plugin for
authentication:

     CREATE USER sql_admin
       IDENTIFIED WITH authentication_windows
       AS 'Rafal, Tasha, Administrators, "Power Users"';

The plugin name is 'authentication_windows'.  The string following the
'AS' keyword is the authentication string.  It specifies that the
Windows users named 'Rafal' or 'Tasha' are permitted to authenticate to
the server as the MySQL user 'sql_admin', as are any Windows users in
the 'Administrators' or 'Power Users' group.  The latter group name
contains a space, so it must be quoted with double quote characters.

After you create the 'sql_admin' account, a user who has logged in to
Windows can attempt to connect to the server using that account:

     C:\> mysql --user=sql_admin

No password is required here.  The 'authentication_windows' plugin uses
the Windows security API to check which Windows user is connecting.  If
that user is named 'Rafal' or 'Tasha', or is in the 'Administrators' or
'Power Users' group, the server grants access and the client is
authenticated as 'sql_admin' and has whatever privileges are granted to
the 'sql_admin' account.  Otherwise, the server denies access.

Authentication string syntax for the Windows authentication plugin
follows these rules:

   * The string consists of one or more user mappings separated by
     commas.

   * Each user mapping associates a Windows user or group name with a
     MySQL user name:

          WIN_USER_OR_GROUP_NAME=MYSQL_USER_NAME
          WIN_USER_OR_GROUP_NAME

     For the latter syntax, with no MYSQL_USER_NAME value given, the
     implicit value is the MySQL user created by the 'CREATE USER'
     statement.  Thus, these statements are
     equivalent:

          CREATE USER sql_admin
            IDENTIFIED WITH authentication_windows
            AS 'Rafal, Tasha, Administrators, "Power Users"';

          CREATE USER sql_admin
            IDENTIFIED WITH authentication_windows
            AS 'Rafal=sql_admin, Tasha=sql_admin, Administrators=sql_admin,
                "Power Users"=sql_admin';

   * Each backslash (''\'') in a value must be doubled because backslash
     is the escape character in MySQL strings.

   * Leading and trailing spaces not inside double quotation marks are
     ignored.

   * Unquoted WIN_USER_OR_GROUP_NAME and MYSQL_USER_NAME values can
     contain anything except equal sign, comma, or space.

   * If a WIN_USER_OR_GROUP_NAME and or MYSQL_USER_NAME value is quoted
     with double quotation marks, everything between the quotation marks
     is part of the value.  This is necessary, for example, if the name
     contains space characters.  All characters within double quotes are
     legal except double quotation mark and backslash.  To include
     either character, escape it with a backslash.

   * WIN_USER_OR_GROUP_NAME values use conventional syntax for Windows
     principals, either local or in a domain.  Examples (note the
     doubling of backslashes):

          domain\\user
          .\\user
          domain\\group
          .\\group
          BUILTIN\\WellKnownGroup

When invoked by the server to authenticate a client, the plugin scans
the authentication string left to right for a user or group match to the
Windows user.  If there is a match, the plugin returns the corresponding
MYSQL_USER_NAME to the MySQL server.  If there is no match,
authentication fails.

A user name match takes preference over a group name match.  Suppose
that the Windows user named 'win_user' is a member of 'win_group' and
the authentication string looks like this:

     'win_group = sql_user1, win_user = sql_user2'

When 'win_user' connects to the MySQL server, there is a match both to
'win_group' and to 'win_user'.  The plugin authenticates the user as
'sql_user2' because the more-specific user match takes precedence over
the group match, even though the group is listed first in the
authentication string.

Windows authentication always works for connections from the same
computer on which the server is running.  For cross-computer
connections, both computers must be registered with Windows Active
Directory.  If they are in the same Windows domain, it is unnecessary to
specify a domain name.  It is also possible to permit connections from a
different domain, as in this example:

     CREATE USER sql_accounting
       IDENTIFIED WITH authentication_windows
       AS 'SomeDomain\\Accounting';

Here 'SomeDomain' is the name of the other domain.  The backslash
character is doubled because it is the MySQL escape character within
strings.

MySQL supports the concept of proxy users whereby a client can connect
and authenticate to the MySQL server using one account but while
connected has the privileges of another account (see
proxy-users).  Suppose that you want Windows users to connect using a
single user name but be mapped based on their Windows user and group
names onto specific MySQL accounts as follows:

   * The 'local_user' and 'MyDomain\domain_user' local and domain
     Windows users should map to the 'local_wlad' MySQL account.

   * Users in the 'MyDomain\Developers' domain group should map to the
     'local_dev' MySQL account.

   * Local machine administrators should map to the 'local_admin' MySQL
     account.

To set this up, create a proxy account for Windows users to connect to,
and configure this account so that users and groups map to the
appropriate MySQL accounts ('local_wlad', 'local_dev', 'local_admin').
In addition, grant the MySQL accounts the privileges appropriate to the
operations they need to perform.  The following instructions use
'win_proxy' as the proxy account, and 'local_wlad', 'local_dev', and
'local_admin' as the proxied accounts.

  1. Create the proxy MySQL account:

          CREATE USER win_proxy
            IDENTIFIED WITH  authentication_windows
            AS 'local_user = local_wlad,
                MyDomain\\domain_user = local_wlad,
                MyDomain\\Developers = local_dev,
                BUILTIN\\Administrators = local_admin';

     *Note*:

     If your MySQL installation has anonymous users, they might conflict
     with the default proxy user.  For more information about this
     problem, and ways of dealing with it, see
     proxy-users-conflicts.

  2. For proxying to work, the proxied accounts must exist, so create
     them:

          CREATE USER local_wlad IDENTIFIED BY 'wlad_pass';
          CREATE USER local_dev IDENTIFIED BY 'dev_pass';
          CREATE USER local_admin IDENTIFIED BY  'admin_pass';

     If you do not let anyone know the passwords for these accounts,
     other users cannot use them to connect directly to the MySQL
     server.

     You should also issue 'GRANT' statements (not shown)
     that grant each proxied account the privileges it needs.

  3. The proxy account must have the 'PROXY' privilege for each of the
     proxied accounts:

          GRANT PROXY ON local_wlad TO win_proxy;
          GRANT PROXY ON local_dev TO win_proxy;
          GRANT PROXY ON local_admin TO win_proxy;

Now the Windows users 'local_user' and 'MyDomain\domain_user' can
connect to the MySQL server as 'win_proxy' and when authenticated have
the privileges of the account given in the authentication string--in
this case, 'local_wlad'.  A user in the 'MyDomain\Developers' group who
connects as 'win_proxy' has the privileges of the 'local_dev' account.
A user in the 'BUILTIN\Administrators' group has the privileges of the
'local_admin' account.

To configure authentication so that all Windows users who do not have
their own MySQL account go through a proxy account, substitute the
default proxy user ('''@''') for 'win_proxy' in the preceding
instructions.  For information about the default proxy user, see
proxy-users.

To use the Windows authentication plugin with Connector/Net connection
strings in Connection/Net 6.4.4 and higher, see Using the Windows Native
Authentication Plugin
(http://dev.mysql.com/doc/connector-net/en/connector-net-programming-authentication-windows-native.html).

Additional control over the Windows authentication plugin is provided by
the 'authentication_windows_use_principal_name' and
'authentication_windows_log_level' system variables.  See
server-system-variables.

6.5.1.8 LDAP Pluggable Authentication
.....................................

*Note*:

LDAP pluggable authentication is an extension included in MySQL
Enterprise Edition, a commercial product.  To learn more about
commercial products, see <http://www.mysql.com/products/>.

As of MySQL 5.7.19, MySQL Enterprise Edition supports an authentication
method that enables MySQL Server to use LDAP (Lightweight Directory
Access Protocol) to authenticate MySQL users by accessing directory
services such as X.500.  MySQL uses LDAP to fetch user, credential, and
group information.

LDAP pluggable authentication provides these capabilities:

   * External authentication: LDAP authentication enables MySQL Server
     to accept connections from users defined outside the MySQL grant
     tables in LDAP directories.

   * Proxy user support: LDAP authentication can return to MySQL a user
     name different from the login user, based on the LDAP group of the
     external user.  This means that an LDAP plugin can return the MySQL
     user that defines the privileges the external LDAP-authenticated
     user should have.  For example, an LDAP user named 'joe' can
     connect and have the privileges of the MySQL user named
     'developer', if the LDAP group for 'joe' is 'developer'.

   * Security: Using TLS, connections to the LDAP server can be secure.

The following table shows the plugin and library file names.  The file
name suffix might differ on your system.  The files must be located in
the directory named by the 'plugin_dir' system variable.

*Plugin and Library Names for LDAP Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'authentication_ldap_sasl',
names                  'authentication_ldap_simple'

Client-side plugin     'authentication_ldap_sasl_client',
names                  'mysql_clear_password'

Library file names     'authentication_ldap_sasl.so',
                       'authentication_ldap_sasl_client.so',
                       'authentication_ldap_simple.so'

The library files include only the 'authentication_ldap_XXX' plugins.
The client-side 'mysql_clear_password' plugin is built into the
'libmysqlclient' client library.

There are two server-side LDAP plugins, each of which works with a
specific client-side plugin:

   * The server-side 'authentication_ldap_simple' plugin performs simple
     LDAP authentication.  For connections by accounts that use this
     plugin, client programs use the client-side 'mysql_clear_password'
     plugin, which sends the password to the server in clear text.  No
     password hashing or encryption is used, so a secure connection
     between the MySQL client and server is recommended to prevent
     password exposure.

   * The server-side 'authentication_ldap_sasl' plugin performs
     SASL-based LDAP authentication.  For connections by accounts that
     use this plugin, client programs use the client-side
     'authentication_ldap_sasl_client' plugin.  The client-side and
     server-side SASL LDAP plugins use SASL messages for secure
     transmission of credentials within the LDAP protocol, to avoid
     sending the clear-text password between the MySQL client and
     server.

The following sections provide installation and usage information
specific to LDAP pluggable authentication:

   * ldap-pluggable-authentication-prerequisites

   * ldap-pluggable-authentication-how-it-works

   * ldap-pluggable-authentication-installation

   * ldap-pluggable-authentication-uninstallation

   * ldap-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.  For information about the
'mysql_clear_password' plugin, see
cleartext-pluggable-authentication.  For proxy user information, see
proxy-users.

*Note*:

If your system supports PAM and permits LDAP as a PAM authentication
method, another way to use LDAP for MySQL user authentication is to use
the server-side 'authentication_pam' plugin.  See
pam-pluggable-authentication.

*Prerequisites for LDAP Pluggable Authentication*

To use LDAP pluggable authentication for MySQL, these prerequisites must
be satisfied:

   * An LDAP server must be available for the LDAP authentication
     plugins to communicate with.

   * LDAP users to be authenticated by MySQL must be present in the
     directory managed by the LDAP server.

   * An LDAP client library must be available on systems where the
     server-side 'authentication_ldap_sasl' or
     'authentication_ldap_simple' plugin is used.  Currently, supported
     libraries are the Windows native LDAP library, or the OpenLDAP
     library on non-Windows systems.

   * To use SASL-based LDAP authentication:

        * The LDAP server must be configured to communicate with a SASL
          server.

        * A SASL client library must be is available on systems where
          the client-side 'authentication_ldap_sasl_client' plugin is
          used.  Currently, the only supported library is the Cyrus SASL
          library.

*How LDAP Authentication of MySQL Users Works*

This section provides a general overview of how MySQL and LDAP work
together to authenticate MySQL users.  For examples showing how to set
up MySQL accounts to use specific LDAP authentication plugins, see
ldap-pluggable-authentication-usage.

The client connects to the MySQL server, providing the MySQL client user
name and the LDAP password:

   * For simple LDAP authentication, the client-side and server-side
     plugins communicate the plugin in clear text.

   * For SASL-based LDAP authentication, the client-side and server-side
     plugins use SASL messages for secure transmission of credentials
     within the LDAP protocol, to avoid sending the clear-text password
     between the MySQL client and server.

If the client user name and host name match no MySQL account, the
connection is rejected.

If there is a matching MySQL account, authentication against LDAP
occurs.  The LDAP server looks for an entry matching the user and
authenticates the entry against the password:

   * If the MySQL account names an the LDAP user distinguished name
     (DN), LDAP authentication uses that value and the LDAP password
     provided by the client.  (To associate an LDAP user DN with a MySQL
     account, include a 'BY' clause in the 'CREATE USER'
     statement that creates the account.)

   * If the MySQL account names no LDAP user DN, LDAP authentication
     uses the user name and LDAP password provided by the client.  In
     this case, the authentication plugin first binds to the LDAP server
     using the root DN and password as credentials to find the user DN
     based on the client user name, then authenticates the user DN
     against the LDAP password.  This bind using the root credentials
     fails if the root DN and password are set but to incorrect values,
     or are empty (not set) and the LDAP server does not permit
     anonymous connections.

If the LDAP server finds no match or multiple matches, authentication
fails and the client connection is rejected.

If the LDAP server finds a single match, LDAP authentication succeeds
(assuming that the password is correct), the LDAP server returns the
LDAP entry, and the authentication plugin determines the name of the
authenticated user based on that entry:

   * If the LDAP entry has a group attribute (by default, the 'cn'
     attribute), the plugin returns its value as the authenticated user
     name.

   * If the LDAP entry has no group attribute, the authentication plugin
     returns the client user name as the authenticated user name.

The MySQL server compares the client user name with the authenticated
user name to determine whether proxying occurs for the client session:

   * If the names are the same, no proxying occurs: The MySQL account
     matching the client user name is used for privilege checking.

   * If the names differ, proxying occurs: MySQL looks for an account
     matching the authenticated user name.  That account becomes the
     proxied user, which is used for privilege checking.  The MySQL
     account that matched the client user name is treated as the
     external proxy user.

*Installing LDAP Pluggable Authentication*

This section describes how to install the LDAP authentication plugins.
For general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library files must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The server-side plugin library file base names are
'authentication_ldap_sasl' and 'authentication_ldap_simple'.  The file
name suffix differs per platform (for example, '.so' for Unix and
Unix-like systems, '.dll' for Windows).

To load the plugins at server startup, use '--plugin-load-add' options
to name the library files that contain them.  With this plugin-loading
method, the options must be given each time the server starts.  Also,
specify values for any plugin-provided system variables you wish to
configure.

Each server-side LDAP plugin exposes a set of system variables that
enable its operation to be configured.  Setting most of these is
optional, but you must set the variables that specify the LDAP server
host (so the plugin knows where to connect) and base distinguished name
for LDAP bind operations (to limit the scope of searches and obtain
faster searches).  For details about all LDAP system variables, see
pluggable-authentication-system-variables.

To load the plugins and set the LDAP server host and base distinguished
name for LDAP bind operations, put lines such as these in your 'my.cnf'
file (adjust the '.so' suffix for your platform as necessary):

     [mysqld]
     plugin-load-add=authentication_ldap_sasl.so
     authentication_ldap_sasl_server_host=127.0.0.1
     authentication_ldap_sasl_bind_base_dn="dc=example,dc=com"
     plugin-load-add=authentication_ldap_simple.so
     authentication_ldap_simple_server_host=127.0.0.1
     authentication_ldap_simple_bind_base_dn="dc=example,dc=com"

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugins at runtime, use these statements
(adjust the '.so' suffix as necessary):

     INSTALL PLUGIN authentication_ldap_sasl SONAME 'authentication_ldap_sasl.so';
     INSTALL PLUGIN authentication_ldap_simple SONAME 'authentication_ldap_simple.so';

'INSTALL PLUGIN' loads a plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

After installing the plugins at runtime, their system variables become
available and you can add settings for them to your 'my.cnf' file to
configure the plugins for subsequent restarts.  For example:

     [mysqld]
     authentication_ldap_sasl_server_host=127.0.0.1
     authentication_ldap_sasl_bind_base_dn="dc=example,dc=com"
     authentication_ldap_simple_server_host=127.0.0.1
     authentication_ldap_simple_bind_base_dn="dc=example,dc=com"

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE '%ldap%';
     +----------------------------+---------------+
     | PLUGIN_NAME                | PLUGIN_STATUS |
     +----------------------------+---------------+
     | authentication_ldap_sasl   | ACTIVE        |
     | authentication_ldap_simple | ACTIVE        |
     +----------------------------+---------------+

If a plugin fails to initialize, check the server error log for
diagnostic messages.

To associate MySQL accounts with an LDAP plugin, see
ldap-pluggable-authentication-usage.

*Uninstalling LDAP Pluggable Authentication*

The method used to uninstall the LDAP authentication plugins depends on
how you installed them:

   * If you installed the plugins at server startup using
     '--plugin-load-add' options, restart the server without those
     options.

   * If you installed the plugins at runtime using 'INSTALL PLUGIN',
     they remain installed across server
     restarts.  To uninstall them, use 'UNINSTALL PLUGIN'.:

          UNINSTALL PLUGIN authentication_ldap_sasl;
          UNINSTALL PLUGIN authentication_ldap_simple;

In addition, remove from your 'my.cnf' file any startup options that set
LDAP plugin-related system variables.

*Using LDAP Pluggable Authentication*

This section describes how to enable MySQL accounts to connect to the
MySQL server using LDAP pluggable authentication.  It is assumed that
the server is running with the appropriate server-side plugins enabled,
as described in ldap-pluggable-authentication-installation, and
that the appropriate client-side plugins are available on the client
host.

This section does not describe LDAP configuration or administration.  It
is assumed that you are familiar with those topics.

There are two server-side LDAP plugins, each of which works with a
specific client-side plugin:

   * The server-side 'authentication_ldap_simple' plugin performs simple
     LDAP authentication.  For connections by accounts that use this
     plugin, client programs use the client-side 'mysql_clear_password'
     plugin, which sends the password to the server in clear text.  No
     password hashing or encryption is used, so a secure connection
     between the MySQL client and server is recommended to prevent
     password exposure.

   * The server-side 'authentication_ldap_sasl' plugin performs
     SASL-based LDAP authentication.  For connections by accounts that
     use this plugin, client programs use the client-side
     'authentication_ldap_sasl_client' plugin.  The client-side and
     server-side SASL LDAP plugins use SASL messages for secure
     transmission of credentials within the LDAP protocol, to avoid
     sending the clear-text password between the MySQL client and
     server.

Overall requirements for LDAP authentication of MySQL users:

   * There must be an LDAP directory entry for each user to be
     authenticated.

   * There must be a MySQL user account that specifies a server-side
     LDAP authentication plugin and optionally names the associated LDAP
     user distinguished name (DN). (To associate an LDAP user DN with a
     MySQL account, include a 'BY' clause in the 'CREATE USER'
     statement that creates the account.)  If an account
     names no LDAP string, LDAP authentication uses the user name
     specified by the client to find the LDAP entry.

   * Client programs connect using the connection method appropriate for
     the server-side authentication plugin the MySQL account uses.  For
     LDAP authentication, connections require the MySQL user name and
     LDAP password.  In addition, for accounts that use the server-side
     'authentication_ldap_simple' plugin, invoke client programs with
     the '--enable-cleartext-plugin' option to enable the client-side
     'mysql_clear_password' plugin.

The instructions here assume the following scenario:

   * MySQL users 'betsy' and 'boris' authenticate to the LDAP entries
     for 'betsy_ldap' and 'boris_ldap', respectively.  (It is not
     necessary that the MySQL and LDAP user names differ, but using
     different names here helps clarify whether an operation context is
     MySQL or LDAP.)

   * LDAP entries use the 'uid' attribute to specify user names.  (This
     may vary depending on LDAP server.  Some LDAP servers use the 'cn'
     attribute for user names rather than 'uid'.)

   * These LDAP entries are available in the directory managed by the
     LDAP server, to provide distinguished name values that uniquely
     identify each user:

          uid=betsy_ldap,pwd=pwd1,ou=People,dc=example,dc=com
          uid=boris_ldap,pwd=pwd2,ou=People,dc=example,dc=com

   * 'CREATE USER' statements that create MySQL
     accounts name an LDAP user in the 'BY' clause, to indicate which
     LDAP entry the MySQL account authenticates against.

The instructions for setting up an account that uses LDAP authentication
depend on which server-side LDAP plugin is used.

   * ldap-pluggable-authentication-usage-simple

   * ldap-pluggable-authentication-usage-sasl

   * ldap-pluggable-authentication-usage-user-dn-suffix

   * ldap-pluggable-authentication-usage-proxying

*Simple LDAP Authentication*

To configure a MySQL account for simple LDAP authentication, the
'CREATE USER' statement should specify the
'authentication_ldap_simple' plugin, and optionally name the LDAP user
distinguished name (DN):

     CREATE USER USER
       IDENTIFIED WITH authentication_ldap_simple
       [BY 'LDAP USER DN'];

Suppose that a MySQL user 'betsy' has this entry in the LDAP directory:

     uid=betsy_ldap,pwd=pwd1,ou=People,dc=example,dc=com

Then the statement to create the MySQL account for 'betsy' looks like
this:

     CREATE USER 'betsy'@'localhost'
       IDENTIFIED WITH authentication_ldap_simple
       BY 'uid=betsy_ldap,ou=People,dc=example,dc=com';

The authentication string specified in the 'BY' clause does not include
the LDAP password.  That must be provided by the client user at connect
time.

Clients connect to the MySQL server by providing the MySQL user name and
LDAP password, and by enabling the client-side 'mysql_clear_password'
plugin:

     shell> mysql --user=betsy --password --enable-cleartext-plugin
     Enter password: pwd1 (BETSY_LDAP LDAP PASSWORD)

*Note*:

The client-side 'mysql_clear_password' plugin with which the server-side
'authentication_ldap_simple' plugin communicates sends the password to
the MySQL server in clear text so it can be passed as is to the LDAP
server.  This is necessary to use the server-side LDAP library without
SASL, but may be a security problem in some configurations.  These
measures minimize the risk:

   * To make inadvertent use of the 'mysql_clear_password' plugin less
     likely, MySQL clients must explicitly enable it; for example, with
     the '--enable-cleartext-plugin' option.

   * To avoid password exposure with the 'mysql_clear_password' plugin
     enabled, MySQL clients should connect to the MySQL server using a
     secure connection.

For additional information, see
cleartext-pluggable-authentication, and
using-encrypted-connections.

The authentication process occurs as follows:

  1. The client-side plugin sends 'betsy' and 'pwd1' as the client user
     name and LDAP password to the MySQL server.

  2. The connection attempt matches the ''betsy'@'localhost'' account.
     The server-side LDAP plugin finds that this account has an
     authentication string of
     ''uid=betsy_ldap,ou=People,dc=example,dc=com'' to name the LDAP
     user DN. The plugin sends this string and the LDAP password to the
     LDAP server.

  3. The LDAP server finds the LDAP entry for 'betsy_ldap' and the
     password matches, so LDAP authentication succeeds.

  4. The LDAP entry has no group attribute, so the server-side plugin
     returns the client user name ('betsy') as the authenticated user.
     This is the same user name supplied by the client, so no proxying
     occurs and the client session uses the ''betsy'@'localhost''
     account for privilege checking.

Had the matching LDAP entry contained a group attribute, that attribute
value would have been the authenticated user name and, if the value
differed from 'betsy', proxying would have occurred.  For examples that
use the group attribute, see
ldap-pluggable-authentication-usage-proxying.

Had the 'CREATE USER' statement contained no 'BY'
clause to specify the 'betsy_ldap' LDAP distinguished name,
authentication attempts would use the user name provided by the client
(in this case, 'betsy').  In the absence of an LDAP entry for 'betsy',
authentication would fail.

*SASL-Based LDAP Authentication*

To configure a MySQL account for SASL LDAP authentication, the
'CREATE USER' statement should specify the
'authentication_ldap_sasl' plugin, and optionally name the LDAP user
distinguished name (DN):

     CREATE USER USER
       IDENTIFIED WITH authentication_ldap_sasl
       [BY 'LDAP USER DN'];

Suppose that a MySQL user 'boris' has this entry in the LDAP directory:

     uid=boris_ldap,pwd=pwd2,ou=People,dc=example,dc=com

Then the statement to create the MySQL account for 'boris' looks like
this:

     CREATE USER 'boris'@'localhost'
       IDENTIFIED WITH authentication_ldap_sasl
       BY 'uid=boris_ldap,ou=People,dc=example,dc=com';

The authentication string specified in the 'BY' clause does not include
the LDAP password.  That must be provided by the client user at connect
time.

Clients connect to the MySQL server by providing the MySQL user name and
LDAP password:

     shell> mysql --user=boris --password
     Enter password: pwd2 (BORIS_LDAP LDAP PASSWORD)

For the server-side 'authentication_ldap_sasl' plugin, clients use the
client-side 'authentication_ldap_sasl_client' plugin.  If a client
program does not find the client-side plugin, specify a '--plugin-dir'
option that names the directory where the plugin library file is
installed.

The authentication process for 'boris' is similar to that previously
described for 'betsy' with simple LDAP authentication, except that The
client-side and server-side SASL LDAP plugins use SASL messages for
secure transmission of credentials within the LDAP protocol, to avoid
sending the clear-text password between the MySQL client and server.

*LDAP Authentication User DN Suffixes*

As of MySQL 5.7.21, LDAP authentication plugins permit the
authentication string that provides user DN information to begin with a
'+' character.  In the absence of this character, the authentication
string value is treated as is without modification, as it has been prior
to 5.7.21.  If the authentication string begins with '+', the plugin
constructs the full user DN value from the account user name as the 'cn'
attribute value, together with the authentication string (with the '+'
removed).  The authentication string is stored as given in the
'mysql.user' system table, with the full user DN constructed on the fly
before authentication.

This account authentication string does not have '+' at the beginning,
so it is taken as the full user DN:

     CREATE USER 'admin'
       IDENTIFIED WITH authentication_ldap_simple
       BY "cn=admin,ou=People,dc=example,dc=com";

This account authentication string does have '+' at the beginning, so it
is taken as just part of the full user DN:

     CREATE USER 'accounting'
       IDENTIFIED WITH authentication_ldap_simple
       BY "+ou=People,dc=example,dc=com";

In this case, the full user DN is constructed using 'accounting' as the
'cn' attribute together with the authentication string, to yield
'"cn=accounting,ou=People,dc=example,dc=com"'.

For account names that include a host name part, the user name is taken
from the user name sent by the client.  (Effectively, this is the user
name part of the account name, ignoring the host name part.)

*LDAP Authentication with Proxying*

The authentication scheme described here uses proxying based on LDAP
group attribute values to map connecting MySQL users who authenticate
using LDAP onto other MySQL accounts that define different sets of
privileges.  Users do not connect directly through the accounts that
define the privileges.  Instead, they connect through a default proxy
user authenticated with LDAP, such that all the external logins are
mapped to the MySQL accounts that hold the privileges.  Any user who
connects is mapped to one of those MySQL accounts, the privileges for
which determine the database operations permitted to the external user.

The instructions here assume the following scenario:

   * LDAP entries use the 'uid' and 'cn' attributes to specify user name
     and group values, respectively.  To use different user and group
     attribute names, set the appropriate system variables to configure
     the plugin:

        * For 'authentication_ldap_simple': Set
          'authentication_ldap_simple_user_search_attr' and
          'authentication_ldap_simple_group_search_attr'.

        * For 'authentication_ldap_sasl': Set
          'authentication_ldap_sasl_user_search_attr' and
          'authentication_ldap_sasl_group_search_attr'.

   * These LDAP entries are available in the directory managed by the
     LDAP server, to provide distinguished name values that uniquely
     identify each user:

          uid=basha,pwd=pwd3,ou=People,dc=example,dc=com,cn=accounting
          uid=basil,pwd=pwd4,ou=People,dc=example,dc=com,cn=front_office

     The group attribute values will become the authenticated user
     names, so they name the proxied accounts, 'accounting' and
     'front_office'.

   * The examples assume use of SASL LDAP authentication.  Make the
     appropriate adjustments for simple LDAP authentication.

Create the default proxy MySQL account:

     CREATE USER ''@'%'
       IDENTIFIED WITH authentication_ldap_sasl;

The proxy account definition has no 'BY 'AUTH_STRING'' clause to name an
LDAP user DN, so that when clients connect, the client user name is used
as the LDAP user name to search for.  The matching LDAP entry is
expected to include a group attribute naming the proxied MySQL account
that defines the privileges the client should have.

*Note*:

If your MySQL installation has anonymous users, they might conflict with
the default proxy user.  For more information about this problem, and
ways of dealing with it, see proxy-users-conflicts.

Create the proxied accounts and grant their privileges:

     CREATE USER 'accounting'@'localhost' ACCOUNT LOCK;
     CREATE USER 'front_office'@'localhost' ACCOUNT LOCK;

     GRANT ALL PRIVILEGES
       ON accountingdb.*
       TO 'accounting'@'localhost';
     GRANT ALL PRIVILEGES
       ON frontdb.*
       TO 'front_office'@'localhost';

Grant the 'PROXY' privilege to the proxy account for the proxied
accounts:

     GRANT PROXY
       ON 'accounting'@'localhost'
       TO ''@'%';
     GRANT PROXY
       ON 'front_office'@'localhost'
       TO ''@'%';

Connect to the MySQL server as 'basha' using the 'mysql'.
command-line client:

     shell> mysql --user=basha --password
     Enter password: pwd3 (BASHA LDAP PASSWORD)

The server authenticates the connection using the '''@'%'' account, for
client user 'basha'.  The matching LDAP entry has group attribute
'cn=accounting', so 'accounting' becomes the authenticated user.  This
differs from the client user name 'basha', with the result that 'basha'
is treated as a proxy for 'accounting' and 'basha' assumes the
privileges of the 'accounting' account.  The following query should
return output as shown:

     mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
     +-----------------+----------------------+--------------+
     | USER()          | CURRENT_USER()       | @@proxy_user |
     +-----------------+----------------------+--------------+
     | basha@localhost | accounting@localhost | ''@'%'       |
     +-----------------+----------------------+--------------+

This demonstrates that 'basha' uses the privileges granted to the
'accounting' MySQL account, and that proxying occurred through the
default proxy user account.

Now connect as 'basil' instead:

     shell> mysql --user=basil --password
     Enter password: pwd4 (BASIL LDAP PASSWORD)

The authentication process for 'basil' is similar to that previously
described for 'basha'.  In this case, the matching LDAP entry has group
attribute 'cn=front_office', so 'front_office' becomes the authenticated
user.  This differs from the client user name 'basil', with the result
that 'basil' is treated as a proxy for 'front_office' and 'basil'
assumes the privileges of the 'front_office' account.  The following
query should return output as shown:

     mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
     +-----------------+------------------------+--------------+
     | USER()          | CURRENT_USER()         | @@proxy_user |
     +-----------------+------------------------+--------------+
     | basil@localhost | front_office@localhost | ''@'%'       |
     +-----------------+------------------------+--------------+

This demonstrates that 'basil' uses the privileges granted to the
'front_office' MySQL account, and that proxying occurred through the
default proxy user account.

6.5.1.9 No-Login Pluggable Authentication
.........................................

The 'mysql_no_login' server-side authentication plugin prevents all
client connections to any account that uses it.  Use cases for such a
plugin include proxied accounts that should never permit direct login
but are accessed only through proxy accounts and accounts that must be
able to execute stored programs and views with elevated privileges
without exposing those privileges to ordinary users.

The following table shows the plugin and library file names.  The file
name suffix might differ on your system.  The file must be located in
the directory named by the 'plugin_dir' system variable.

*Plugin and Library Names for No-Login Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'mysql_no_login'

Client-side plugin     None

Library file           'mysql_no_login.so'

The following sections provide installation and usage information
specific to no-login pluggable authentication:

   * no-login-pluggable-authentication-installation

   * no-login-pluggable-authentication-uninstallation

   * no-login-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.  For proxy user information, see
proxy-users.

*Installing No-Login Pluggable Authentication*

This section describes how to install the no-login authentication
plugin.  For general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The plugin library file base name is 'mysql_no_login'.  The file name
suffix differs per platform (for example, '.so' for Unix and Unix-like
systems, '.dll' for Windows).

To load the plugin at server startup, use the '--plugin-load-add' option
to name the library file that contains it.  With this plugin-loading
method, the option must be given each time the server starts.  For
example, put these lines in your 'my.cnf' file (adjust the '.so' suffix
for your platform as necessary):

     [mysqld]
     plugin-load-add=mysql_no_login.so

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugin at runtime, use this statement
(adjust the '.so' suffix as necessary):

     INSTALL PLUGIN mysql_no_login SONAME 'mysql_no_login.so';

'INSTALL PLUGIN' loads a plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE '%login%';
     +----------------+---------------+
     | PLUGIN_NAME    | PLUGIN_STATUS |
     +----------------+---------------+
     | mysql_no_login | ACTIVE        |
     +----------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

To associate MySQL accounts with the no-login plugin, see
no-login-pluggable-authentication-usage.

*Uninstalling No-Login Pluggable Authentication*

The method used to uninstall the no-login authentication plugin depends
on how you installed it:

   * If you installed the plugin at server startup using a
     '--plugin-load-add' option, restart the server without the option.

   * If you installed the plugin at runtime using 'INSTALL PLUGIN',
     it remains installed across server
     restarts.  To uninstall it, use 'UNINSTALL PLUGIN'.:

          UNINSTALL PLUGIN mysql_no_login;

*Using No-Login Pluggable Authentication*

This section describes how to use the no-login authentication plugin to
prevent connections from MySQL client programs to the server.  It is
assumed that the server is running with the server-side plugin enabled,
as described in no-login-pluggable-authentication-installation.

To refer to the no-login authentication plugin in the 'IDENTIFIED WITH'
clause of a 'CREATE USER' statement, use the name
'mysql_no_login'.

An account that authenticates using 'mysql_no_login' may be used as the
'DEFINER' for stored program and view objects.  If such an object
definition also includes 'SQL SECURITY DEFINER', it executes with that
account's privileges.  DBAs can use this behavior to provide access to
confidential or sensitive data that is exposed only through
well-controlled interfaces.

The following example provides a simple illustration of these
principles.  It defines an account that does not permit client
connections, and associates with it a view that exposes only certain
columns of the 'mysql.user' table:

     CREATE DATABASE nologindb;
     CREATE USER 'nologin'@'localhost'
       IDENTIFIED WITH mysql_no_login;
     GRANT ALL ON nologindb.*
       TO 'nologin'@'localhost';
     GRANT SELECT ON mysql.user
       TO 'nologin'@'localhost';
     CREATE DEFINER = 'nologin'@'localhost'
       SQL SECURITY DEFINER
       VIEW nologindb.myview
       AS SELECT User, Host FROM mysql.user;

To provide protected access to the view to an ordinary user, do this:

     GRANT SELECT ON nologindb.myview
       TO 'ordinaryuser'@'localhost';

Now the ordinary user can use the view to access the limited information
it presents:

     SELECT * FROM nologindb.myview;

Attempts by the user to access columns other than those exposed by the
view result in an error, as do all attempts to select from the view by
users not granted access to it.

*Note*:

Because the 'nologin' account cannot be used directly, the operations
required to set up objects that it uses must be performed by 'root' or
similar account with the privileges required to create the objects and
set 'DEFINER' values.

An account that authenticates using 'mysql_no_login' may be used as a
proxied base user for proxy accounts:

     -- create proxied account
     CREATE USER 'proxy_base'@'localhost'
       IDENTIFIED WITH mysql_no_login;
     -- grant privileges to proxied account
     GRANT ...  TO 'proxy_base'@'localhost';
     -- permit real_user to be proxy for proxied account
     GRANT PROXY ON 'proxy_base'@'localhost'
       TO 'real_user'@'localhost';

This enables clients to access MySQL through the proxy account
('real_user') but not to bypass the proxy mechanism by connecting
directly as the proxied user ('proxy_base').

6.5.1.10 Socket Peer-Credential Pluggable Authentication
........................................................

The server-side 'auth_socket' authentication plugin authenticates
clients that connect from the local host through the Unix socket file.
The plugin uses the 'SO_PEERCRED' socket option to obtain information
about the user running the client program.  Thus, the plugin can be used
only on systems that support the 'SO_PEERCRED' option, such as Linux.

The source code for this plugin can be examined as a relatively simple
example demonstrating how to write a loadable authentication plugin.

The following table shows the plugin and library file names.  The file
must be located in the directory named by the 'plugin_dir' system
variable.

*Plugin and Library Names for Socket Peer-Credential Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'auth_socket'

Client-side plugin     None, see discussion

Library file           'auth_socket.so'

The following sections provide installation and usage information
specific to socket pluggable authentication:

   * socket-pluggable-authentication-installation

   * socket-pluggable-authentication-uninstallation

   * socket-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.

*Installing Socket Pluggable Authentication*

This section describes how to install the socket authentication plugin.
For general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

To load the plugin at server startup, use the '--plugin-load-add' option
to name the library file that contains it.  With this plugin-loading
method, the option must be given each time the server starts.  For
example, put these lines in your 'my.cnf' file:

     [mysqld]
     plugin-load-add=auth_socket.so

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugin at runtime, use this statement:

     INSTALL PLUGIN auth_socket SONAME 'auth_socket.so';

'INSTALL PLUGIN' loads a plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE '%socket%';
     +-------------+---------------+
     | PLUGIN_NAME | PLUGIN_STATUS |
     +-------------+---------------+
     | auth_socket | ACTIVE        |
     +-------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

To associate MySQL accounts with the socket plugin, see
socket-pluggable-authentication-usage.

*Uninstalling Socket Pluggable Authentication*

The method used to uninstall the socket authentication plugin depends on
how you installed it:

   * If you installed the plugin at server startup using a
     '--plugin-load-add' option, restart the server without the option.

   * If you installed the plugin at runtime using 'INSTALL PLUGIN',
     it remains installed across server
     restarts.  To uninstall it, use 'UNINSTALL PLUGIN'.:

          UNINSTALL PLUGIN auth_socket;

*Using Socket Pluggable Authentication*

The socket plugin checks whether the socket user name matches the MySQL
user name specified by the client program to the server.  If the names
do not match, the plugin also checks whether the socket user name
matches the name specified in the 'authentication_string' column of the
'mysql.user' table row.  If a match is found, the plugin permits the
connection.

Suppose that a MySQL account is created for a user named 'valerie' who
is to be authenticated by the 'auth_socket' plugin for connections from
the local host through the socket file:

     CREATE USER 'valerie'@'localhost' IDENTIFIED WITH auth_socket;

If a user on the local host with a login name of 'stefanie' invokes
'mysql' with the option '--user=valerie' to connect
through the socket file, the server uses 'auth_socket' to authenticate
the client.  The plugin determines that the '--user' option value
('valerie') differs from the client user's name ('stephanie') and
refuses the connection.  If a user named 'valerie' tries the same thing,
the plugin finds that the user name and the MySQL user name are both
'valerie' and permits the connection.  However, the plugin refuses the
connection even for 'valerie' if the connection is made using a
different protocol, such as TCP/IP.

6.5.1.11 Test Pluggable Authentication
......................................

MySQL includes a test plugin that checks account credentials and logs
success or failure to the server error log.  This is a loadable plugin
(not built in) and must be installed prior to use.

The test plugin source code is separate from the server source, unlike
the built-in native plugin, so it can be examined as a relatively simple
example demonstrating how to write a loadable authentication plugin.

*Note*:

This plugin is intended for testing and development purposes, and is not
for use in production environments or on servers that are exposed to
public networks.

The following table shows the plugin and library file names.  The file
name suffix might differ on your system.  The file must be located in
the directory named by the 'plugin_dir' system variable.

*Plugin and Library Names for Test Authentication*

Plugin or File         Plugin or File Name

Server-side plugin     'test_plugin_server'

Client-side plugin     'auth_test_plugin'

Library file           'auth_test_plugin.so'

The following sections provide installation and usage information
specific to test pluggable authentication:

   * test-pluggable-authentication-installation

   * test-pluggable-authentication-uninstallation

   * test-pluggable-authentication-usage

For general information about pluggable authentication in MySQL, see
pluggable-authentication.

*Installing Test Pluggable Authentication*

This section describes how to install the test authentication plugin.
For general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

To load the plugin at server startup, use the '--plugin-load-add' option
to name the library file that contains it.  With this plugin-loading
method, the option must be given each time the server starts.  For
example, put these lines in your 'my.cnf' file (adjust the '.so' suffix
for your platform as necessary):

     [mysqld]
     plugin-load-add=auth_test_plugin.so

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugin at runtime, use this statement
(adjust the '.so' suffix as necessary):

     INSTALL PLUGIN test_plugin_server SONAME 'auth_test_plugin.so';

'INSTALL PLUGIN' loads a plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE '%test_plugin%';
     +--------------------+---------------+
     | PLUGIN_NAME        | PLUGIN_STATUS |
     +--------------------+---------------+
     | test_plugin_server | ACTIVE        |
     +--------------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

To associate MySQL accounts with the test plugin, see
test-pluggable-authentication-usage.

*Uninstalling Test Pluggable Authentication*

The method used to uninstall the test authentication plugin depends on
how you installed it:

   * If you installed the plugin at server startup using a
     '--plugin-load-add' option, restart the server without the option.

   * If you installed the plugin at runtime using 'INSTALL PLUGIN',
     it remains installed across server
     restarts.  To uninstall it, use 'UNINSTALL PLUGIN'.:

          UNINSTALL PLUGIN test_plugin_server;

*Using Test Pluggable Authentication*

To use the test authentication plugin, create an account and name that
plugin in the 'IDENTIFIED WITH' clause:

     CREATE USER 'testuser'@'localhost'
     IDENTIFIED WITH test_plugin_server
     BY 'testpassword';

Then provide the '--user' and '--password' options for that account when
you connect to the server.  For example:

     shell> mysql --user=testuser --password
     Enter password: testpassword

The plugin fetches the password as received from the client and compares
it with the value stored in the 'authentication_string' column of the
account row in the 'mysql.user' table.  If the two values match, the
plugin returns the 'authentication_string' value as the new effective
user ID.

You can look in the server error log for a message indicating whether
authentication succeeded (notice that the password is reported as the
'user'):

     [Note] Plugin test_plugin_server reported:
     'successfully authenticated user testpassword'

6.5.1.12 Pluggable Authentication System Variables
..................................................

These variables are unavailable unless the appropriate server-side
plugin is installed:

   * 'authentication_ldap_sasl' for system variables with names of the
     form 'authentication_ldap_sasl_XXX'

   * 'authentication_ldap_simple' for system variables with names of the
     form 'authentication_ldap_simple_XXX'

*Authentication Plugin System Variable Summary*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

authentication_ldap_sasl_auth_method_nameYesYesYes             Global      Yes

authentication_ldap_sasl_bind_base_dnYesYesYes                 Global      Yes

authentication_ldap_sasl_bind_root_dnYesYesYes                 Global      Yes

authentication_ldap_sasl_bind_root_pwdYesYesYes                Global      Yes

authentication_ldap_sasl_ca_pathYesYes Yes                     Global      Yes

authentication_ldap_sasl_group_search_attrYesYesYes            Global      Yes

authentication_ldap_sasl_init_pool_sizeYesYesYes               Global      Yes

authentication_ldap_sasl_log_statusYesYesYes                   Global      Yes

authentication_ldap_sasl_max_pool_sizeYesYesYes                Global      Yes

authentication_ldap_sasl_server_hostYesYesYes                  Global      Yes

authentication_ldap_sasl_server_portYesYesYes                  Global      Yes

authentication_ldap_sasl_tlsYesYes     Yes                     Global      Yes

authentication_ldap_sasl_user_search_attrYesYesYes             Global      Yes

authentication_ldap_simple_auth_method_nameYesYesYes           Global      Yes

authentication_ldap_simple_bind_base_dnYesYesYes               Global      Yes

authentication_ldap_simple_bind_root_dnYesYesYes               Global      Yes

authentication_ldap_simple_bind_root_pwdYesYesYes              Global      Yes

authentication_ldap_simple_ca_pathYesYesYes                    Global      Yes

authentication_ldap_simple_group_search_attrYesYesYes          Global      Yes

authentication_ldap_simple_init_pool_sizeYesYesYes             Global      Yes

authentication_ldap_simple_log_statusYesYesYes                 Global      Yes

authentication_ldap_simple_max_pool_sizeYesYesYes              Global      Yes

authentication_ldap_simple_server_hostYesYesYes                Global      Yes

authentication_ldap_simple_server_portYesYesYes                Global      Yes

authentication_ldap_simple_tlsYesYes   Yes                     Global      Yes

authentication_ldap_simple_user_search_attrYesYesYes           Global      Yes

   * 'authentication_ldap_sasl_auth_method_name'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-auth-method-name=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_auth_method_name'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'SCRAM-SHA-1'

     For SASL LDAP authentication, the authentication method name.
     Communication between the authentication plugin and the LDAP server
     occurs according to this authentication method.  These
     authentication method values are permitted:

        * 'SCRAM-SHA-1': Authentication uses a SASL challenge-response
          mechanism to ensure password security.

          The client-side 'authentication_ldap_sasl_client' plugin
          communicates with the SASL server, using the password to
          create a challenge and obtain a SASL request buffer, then
          passes this buffer to the server-side
          'authentication_ldap_sasl' plugin.  The client-side and
          server-side SASL LDAP plugins use SASL messages for secure
          transmission of credentials within the LDAP protocol, to avoid
          sending the clear-text password between the MySQL client and
          server.

   * 'authentication_ldap_sasl_bind_base_dn'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-bind-base-dn=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_bind_base_dn'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For SASL LDAP authentication, the base distinguished name (DN).
     This variable can be used to limit the scope of searches by
     anchoring them at a certain location (the 'base') within the search
     tree.

     Suppose that members of one set of LDAP user entries each have this
     form:

          uid=USER_NAME,pwd=USER_PASSWORD,ou=People,dc=example,dc=com

     And that members of another set of LDAP user entries each have this
     form:

          uid=USER_NAME,pwd=USER_PASSWORD,ou=Admin,dc=example,dc=com

     Then searches work like this for different base DN values:

        * If the base DN is 'ou=People,dc=example,dc=com': Searches find
          user entries only in the first set.

        * If the base DN is 'ou=Admin,dc=example,dc=com': Searches find
          user entries only in the second set.

        * If the base DN is 'ou=dc=example,dc=com': Searches find user
          entries in the first or second set.

     In general, more specific base DN values result in faster searches
     because they limit the search scope more.

   * 'authentication_ldap_sasl_bind_root_dn'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-bind-root-dn=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_bind_root_dn'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For SASL LDAP authentication, the root distinguished name (DN).
     This variable is used in conjunction with
     'authentication_ldap_sasl_bind_root_pwd' as the credentials for
     authenticating to the LDAP server for the purpose of performing
     searches.  Authentication uses either one or two LDAP bind
     operations, depending on whether the the MySQL account names an
     LDAP user DN:

        * If the account does not name a user DN:
          'authentication_ldap_sasl' performs an initial LDAP binding
          using 'authentication_ldap_sasl_bind_root_dn' and
          'authentication_ldap_sasl_bind_root_pwd'.  (These are both
          empty by default, so if they are not set, the LDAP server must
          permit anonymous connections.)  The resulting bind LDAP handle
          is used to search for the user DN, based on the client user
          name.  'authentication_ldap_sasl' performs a second bind using
          the user DN and client-supplied password.

        * If the account does name a user DN: The first bind operation
          is unnecessary in this case.  'authentication_ldap_sasl'
          performs a single bind using the user DN and client-supplied
          password.  This is faster than if the MySQL account does not
          specify an LDAP user DN.

   * 'authentication_ldap_sasl_bind_root_pwd'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-bind-root-pwd=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_bind_root_pwd'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For SASL LDAP authentication, the password for the root
     distinguished name.  This variable is used in conjunction with
     'authentication_ldap_sasl_bind_root_dn'.  See the description of
     that variable.

   * 'authentication_ldap_sasl_ca_path'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-ca-path=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_ca_path'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For SASL LDAP authentication, the absolute path of the certificate
     authority file.  Specify this file if it is desired that the
     authentication plugin perform verification of the LDAP server
     certificate.

     *Note*:

     In addition to setting the 'authentication_ldap_sasl_ca_path'
     variable to the file name, you must add the appropriate certificate
     authority certificates to the file and enable the
     'authentication_ldap_sasl_tls' system variable.

   * 'authentication_ldap_sasl_group_search_attr'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-group-search-attr=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_group_search_attr'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'cn'

     For SASL LDAP authentication, the name of the attribute that
     specifies group names in LDAP directory entries.  If
     'authentication_ldap_sasl_group_search_attr' has its default value
     of 'cn', searches return the 'cn' value as the group name.  For
     example, if an LDAP entry with a 'uid' value of 'user1' has a 'cn'
     attribute of 'mygroup', searches for 'user1' return 'mygroup' as
     the group name.

     This variable should be the empty string if you want no group or
     proxy authentication.

     As of MySQL 5.7.21, if the group search attribute is 'isMemberOf',
     LDAP authentication directly retrieves the user attribute
     'isMemberOf' value and assigns it as group information.  If the
     group search attribute is not 'isMemberOf', LDAP authentication
     searches for all groups where the user is a member.  (The latter is
     the default behavior.)  This behavior is based on how LDAP group
     information can be stored two ways: 1) A group entry can have an
     attribute named 'memberUid' or 'member' with a value that is a user
     name; 2) A user entry can have an attribute named 'isMemberOf' with
     values that are group names.

   * 'authentication_ldap_sasl_group_search_filter'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-group-search-filter=value'

     *Introduced*                         5.7.21

     *System Variable*                    'authentication_ldap_sasl_group_search_filter'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      '(|(&(objectClass=posixGroup)(memberUid=%s))(&(objectClass=group)(member=%s)))'

     For SASL LDAP authentication, the custom group search filter.

     As of MySQL 5.7.22, the search filter value can contain '{UA}' and
     '{UD}' notation to represent the user name and the full user DN.
     For example, '{UA}' is replaced with a user name such as '"admin"',
     whereas '{UD}' is replaced with a use full DN such as
     '"uid=admin,ou=People,dc=example,dc=com"'.  The following value is
     the default, which supports both OpenLDAP and Active Directory:

          (|(&(objectClass=posixGroup)(memberUid={UA}))
            (&(objectClass=group)(member={UD})))

     Previously, if the group search attribute was 'isMemberOf' or
     'memberOf', it was treated as a user attribute that has group
     information.  However, in some cases for the user scenario,
     'memberOf' was a simple user attribute that held no group
     information.  For additional flexibility, an optional '{GA}' prefix
     now can be used with the group search attribute.  (Previously, it
     was assumed that if the group search attribute is 'isMemberOf', it
     will be treated differently.  Now any group attribute with a {GA}
     prefix is treated as a user attribute having group names.)  For
     example, with a value of '{GA}MemberOf', if the group value is the
     DN, the first attribute value from the group DN is returned as the
     group name.

     In MySQL 5.7.21, the search filter used '%s' notation, expanding it
     to the user name for OpenLDAP
     ('&(objectClass=posixGroup)(memberUid=%s)') and to the full user DN
     for Active Directory ('&(objectClass=group)(member=%s)').

   * 'authentication_ldap_sasl_init_pool_size'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-init-pool-size=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_init_pool_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '10'

     *Minimum Value*                      '0'

     *Maximum Value*                      '32767'

     For SASL LDAP authentication, the initial size of the pool of
     connections to the LDAP server.  Choose the value for this variable
     based on the average number of concurrent authentication requests
     to the LDAP server.

     The plugin uses 'authentication_ldap_sasl_init_pool_size' and
     'authentication_ldap_sasl_max_pool_size' together for
     connection-pool management:

        * When the authentication plugin initializes, it creates
          'authentication_ldap_sasl_init_pool_size' connections, unless
          'authentication_ldap_sasl_max_pool_size=0' to disable pooling.

        * If the plugin receives an anthentication request when there
          are no free connections in the current connection pool, the
          plugin can create a new connection, up to the maximum
          connection pool size given by
          'authentication_ldap_sasl_max_pool_size'.

        * If the plugin receives a request when the pool size is already
          at its maximum and there are no free connections,
          authentication fails.

        * When the plugin unloads, it closes all pooled connections.

     Changes to plugin system variable settings may have no effect on
     connections already in the pool.  For example, modifying the LDAP
     server host, port, or TLS settings does not affect existing
     connections.  However, if the original variable values were invalid
     and the connection pool could not be initialized, the plugin
     attempts to reinitialize the pool for the next LDAP request.  In
     this case, the new system variable values are used for the
     reinitialization attempt.

     If 'authentication_ldap_sasl_max_pool_size=0' to disable pooling,
     each LDAP connection opened by the plugin uses the values the
     system variables have at that time.

   * 'authentication_ldap_sasl_log_status'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-log-status=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_log_status'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '5'

     For SASL LDAP authentication, the logging level.  The following
     table shows the permitted level values and their meanings.

     *Log Levels for authentication_ldap_sasl_log_status*

     Option Value           Types of Messages Logged

     '1'                    No messages

     '2'                    Error messages

     '3'                    Error and warning messages

     '4'                    Error, warning, and information messages

     '5'                    All messages

     On the client side, messages can be logged to the standard output
     by setting the 'AUTHENTICATION_LDAP_CLIENT_LOG' environment
     variable.  The permitted and default values are the same as for
     'authentication_ldap_sasl_log_status'.

     The 'AUTHENTICATION_LDAP_CLIENT_LOG' environment variable applies
     only to SASL LDAP authentication.  It has no effect for simple LDAP
     authentication because the client plugin in that case is
     'mysql_clear_password', which knows nothing about LDAP operations.

   * 'authentication_ldap_sasl_max_pool_size'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-max-pool-size=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_max_pool_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '32767'

     For SASL LDAP authentication, the maximum size of the pool of
     connections to the LDAP server.  To disable connection pooling, set
     this variable to 0.

     This variable is used in conjunction with
     'authentication_ldap_sasl_init_pool_size'.  See the description of
     that variable.

   * 'authentication_ldap_sasl_server_host'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-server-host=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_server_host'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     For SASL LDAP authentication, the LDAP server host.  The permitted
     values for this variable depend on the authentication method:

        * For 'authentication_ldap_sasl_auth_method_name=SCRAM-SHA-1':
          The LDAP server host can be a host name or IP address.

   * 'authentication_ldap_sasl_server_port'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-server-port=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_server_port'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '389'

     *Minimum Value*                      '1'

     *Maximum Value*                      '32376'

     For SASL LDAP authentication, the LDAP server TCP/IP port number.

   * 'authentication_ldap_sasl_tls'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-tls=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_tls'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     For SASL LDAP authentication, whether connections by the plugin to
     the LDAP server are secure.  If this variable is enabled, the
     plugin uses TLS to connect securely to the LDAP server.  If you
     enable this variable, you may also wish to set the
     'authentication_ldap_sasl_ca_path' variable.

     MySQL LDAP plugins support the StartTLS method, which initializes
     TLS on top of a plain LDAP connection.  The 'ldaps' method is
     deprecated and MySQL does not support it.

   * 'authentication_ldap_sasl_user_search_attr'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-sasl-user-search-attr=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_sasl_user_search_attr'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'uid'

     For SASL LDAP authentication, the name of the attribute that
     specifies user names in LDAP directory entries.  If a user
     distinguished name is not provided, the authentication plugin
     searches for the name using this attribute.  For example, if the
     'authentication_ldap_sasl_user_search_attr' value is 'uid', a
     search for the user name 'user1' finds entries with a 'uid' value
     of 'user1'.

   * 'authentication_ldap_simple_auth_method_name'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-auth-method-name=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_auth_method_name'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'SIMPLE'

     For simple LDAP authentication, the authentication method name.
     Communication between the authentication plugin and the LDAP server
     occurs according to this authentication method.  These
     authentication method values are permitted:

        * 'SIMPLE': This authentication method uses either one or two
          LDAP bind operations, depending on whether the the MySQL
          account names an LDAP user distinguished name.  See the
          description of 'authentication_ldap_simple_bind_root_dn'.

        * 'AD-FOREST': 'authentication_ldap_simple' searches all the
          domains in the Active Directory forest, performing an LDAP
          bind to each Active Directory domain until the user is found
          in some domain.

     *Note*:

     For simple LDAP authentication, it is recommended to also set TLS
     parameters to require that communication with the LDAP server take
     place over secure connections.

   * 'authentication_ldap_simple_bind_base_dn'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-bind-base-dn=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_bind_base_dn'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For simple LDAP authentication, the base distinguished name (DN).
     This variable can be used to limit the scope of searches by
     anchoring them at a certain location (the 'base') within the search
     tree.

     Suppose that members of one set of LDAP user entries each have this
     form:

          uid=USER_NAME,pwd=USER_PASSWORD,ou=People,dc=example,dc=com

     And that members of another set of LDAP user entries each have this
     form:

          uid=USER_NAME,pwd=USER_PASSWORD,ou=Admin,dc=example,dc=com

     Then searches work like this for different base DN values:

        * If the base DN is 'ou=People,dc=example,dc=com': Searches find
          user entries only in the first set.

        * If the base DN is 'ou=Admin,dc=example,dc=com': Searches find
          user entries only in the second set.

        * If the base DN is 'ou=dc=example,dc=com': Searches find user
          entries in the first or second set.

     In general, more specific base DN values result in faster searches
     because they limit the search scope more.

   * 'authentication_ldap_simple_bind_root_dn'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-bind-root-dn=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_bind_root_dn'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For simple LDAP authentication, the root distinguished name (DN).
     This variable is used in conjunction with
     'authentication_ldap_simple_bind_root_pwd' as the credentials for
     authenticating to the LDAP server for the purpose of performing
     searches.  Authentication uses either one or two LDAP bind
     operations, depending on whether the the MySQL account names an
     LDAP user DN:

        * If the account does not name a user DN:
          'authentication_ldap_simple' performs an initial LDAP binding
          using 'authentication_ldap_simple_bind_root_dn' and
          'authentication_ldap_simple_bind_root_pwd'.  (These are both
          empty by default, so if they are not set, the LDAP server must
          permit anonymous connections.)  The resulting bind LDAP handle
          is used to search for the user DN, based on the client user
          name.  'authentication_ldap_simple' performs a second bind
          using the user DN and client-supplied password.

        * If the account does name a user DN: The first bind operation
          is unnecessary in this case.  'authentication_ldap_simple'
          performs a single bind using the user DN and client-supplied
          password.  This is faster than if the MySQL account does not
          specify an LDAP user DN.

   * 'authentication_ldap_simple_bind_root_pwd'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-bind-root-pwd=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_bind_root_pwd'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For simple LDAP authentication, the password for the root
     distinguished name.  This variable is used in conjunction with
     'authentication_ldap_simple_bind_root_dn'.  See the description of
     that variable.

   * 'authentication_ldap_simple_ca_path'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-ca-path=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_ca_path'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     For simple LDAP authentication, the absolute path of the
     certificate authority file.  Specify this file if it is desired
     that the authentication plugin perform verification of the LDAP
     server certificate.

     *Note*:

     In addition to setting the 'authentication_ldap_simple_ca_path'
     variable to the file name, you must add the appropriate certificate
     authority certificates to the file and enable the
     'authentication_ldap_simple_tls' system variable.

   * 'authentication_ldap_simple_group_search_attr'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-group-search-attr=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_group_search_attr'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'cn'

     For simple LDAP authentication, the name of the attribute that
     specifies group names in LDAP directory entries.  If
     'authentication_ldap_simple_group_search_attr' has its default
     value of 'cn', searches return the 'cn' value as the group name.
     For example, if an LDAP entry with a 'uid' value of 'user1' has a
     'cn' attribute of 'mygroup', searches for 'user1' return 'mygroup'
     as the group name.

     As of MySQL 5.7.21, if the group search attribute is 'isMemberOf',
     LDAP authentication directly retrieves the user attribute
     'isMemberOf' value and assigns it as group information.  If the
     group search attribute is not 'isMemberOf', LDAP authentication
     searches for all groups where the user is a member.  (The latter is
     the default behavior.)  This behavior is based on how LDAP group
     information can be stored two ways: 1) A group entry can have an
     attribute named 'memberUid' or 'member' with a value that is a user
     name; 2) A user entry can have an attribute named 'isMemberOf' with
     values that are group names.

   * 'authentication_ldap_simple_group_search_filter'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-group-search-filter=value'

     *Introduced*                         5.7.21

     *System Variable*                    'authentication_ldap_simple_group_search_filter'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      '(|(&(objectClass=posixGroup)(memberUid=%s))(&(objectClass=group)(member=%s)))'

     For simple LDAP authentication, the custom group search filter.

     As of MySQL 5.7.22, the search filter value can contain '{UA}' and
     '{UD}' notation to represent the user name and the full user DN.
     For example, '{UA}' is replaced with a user name such as '"admin"',
     whereas '{UD}' is replaced with a use full DN such as
     '"uid=admin,ou=People,dc=example,dc=com"'.  The following value is
     the default, which supports both OpenLDAP and Active Directory:

          (|(&(objectClass=posixGroup)(memberUid={UA}))
            (&(objectClass=group)(member={UD})))

     Previously, if the group search attribute was 'isMemberOf' or
     'memberOf', it was treated as a user attribute that has group
     information.  However, in some cases for the user scenario,
     'memberOf' was a simple user attribute that held no group
     information.  For additional flexibility, an optional '{GA}' prefix
     now can be used with the group search attribute.  (Previously, it
     was assumed that if the group search attribute is 'isMemberOf', it
     will be treated differently.  Now any group attribute with a {GA}
     prefix is treated as a user attribute having group names.)  For
     example, with a value of '{GA}MemberOf', if the group value is the
     DN, the first attribute value from the group DN is returned as the
     group name.

     In MySQL 5.7.21, the search filter used '%s' notation, expanding it
     to the user name for OpenLDAP
     ('&(objectClass=posixGroup)(memberUid=%s)') and to the full user DN
     for Active Directory ('&(objectClass=group)(member=%s)').

   * 'authentication_ldap_simple_init_pool_size'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-init-pool-size=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_init_pool_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '10'

     *Minimum Value*                      '0'

     *Maximum Value*                      '32767'

     For simple LDAP authentication, the initial size of the pool of
     connections to the LDAP server.  Choose the value for this variable
     based on the average number of concurrent authentication requests
     to the LDAP server.

     The plugin uses 'authentication_ldap_simple_init_pool_size' and
     'authentication_ldap_simple_max_pool_size' together for
     connection-pool management:

        * When the authentication plugin initializes, it creates
          'authentication_ldap_simple_init_pool_size' connections,
          unless 'authentication_ldap_simple_max_pool_size=0' to disable
          pooling.

        * If the plugin receives an anthentication request when there
          are no free connections in the current connection pool, the
          plugin can create a new connection, up to the maximum
          connection pool size given by
          'authentication_ldap_simple_max_pool_size'.

        * If the plugin receives a request when the pool size is already
          at its maximum and there are no free connections,
          authentication fails.

        * When the plugin unloads, it closes all pooled connections.

     Changes to plugin system variable settings may have no effect on
     connections already in the pool.  For example, modifying the LDAP
     server host, port, or TLS settings does not affect existing
     connections.  However, if the original variable values were invalid
     and the connection pool could not be initialized, the plugin
     attempts to reinitialize the pool for the next LDAP request.  In
     this case, the new system variable values are used for the
     reinitialization attempt.

     If 'authentication_ldap_simple_max_pool_size=0' to disable pooling,
     each LDAP connection opened by the plugin uses the values the
     system variables have at that time.

   * 'authentication_ldap_simple_log_status'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-log-status=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_log_status'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '5'

     For simple LDAP authentication, the logging level.  The following
     table shows the permitted level values and their meanings.

     *Log Levels for authentication_ldap_simple_log_status*

     Option Value           Types of Messages Logged

     '1'                    No messages

     '2'                    Error messages

     '3'                    Error and warning messages

     '4'                    Error, warning, and information messages

     '5'                    All messages

   * 'authentication_ldap_simple_max_pool_size'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-max-pool-size=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_max_pool_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '32767'

     For simple LDAP authentication, the maximum size of the pool of
     connections to the LDAP server.  To disable connection pooling, set
     this variable to 0.

     This variable is used in conjunction with
     'authentication_ldap_simple_init_pool_size'.  See the description
     of that variable.

   * 'authentication_ldap_simple_server_host'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-server-host=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_server_host'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     For simple LDAP authentication, the LDAP server host.  The
     permitted values for this variable depend on the authentication
     method:

        * For 'authentication_ldap_simple_auth_method_name=SIMPLE': The
          LDAP server host can be a host name or IP address.

        * For 'authentication_ldap_simple_auth_method_name=AD-FOREST'.
          The LDAP server host can be an Active Directory domain name.
          For example, for an LDAP server URL of
          'ldap://example.mem.local:389', the server name can be
          'mem.local'.

          An Active Directory forest setup can have multiple domains
          (LDAP server IPs), which can be discovered using DNS. On Unix
          and Unix-like systems, some additional setup may be required
          to configure your DNS server with SRV records that specify the
          LDAP servers for the Active Directory domain.  Suppose that
          your configuration has these properties:

             * The name server that provides information about Active
               Directory domains has IP address '10.172.166.100'.

             * The LDAP servers have names 'ldap1.mem.local' through
               'ldap3.mem.local' and IP addresses '10.172.166.101'
               through '10.172.166.103'.

          You want the LDAP servers to be discoverable using SRV
          searches.  For example, at the command line, a command like
          this should list the LDAP servers:

               host -t SRV _ldap._tcp.mem.local

          Perform the DNS configuration as follows:

            1. Add a line to '/etc/resolv.conf' to specify the name
               server that provides information about Active Directory
               domains:

                    nameserver 10.172.166.100

            2. Configure the appropriate zone file for the name server
               with SRV records for the LDAP servers:

                    _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap1.mem.local.
                    _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap2.mem.local.
                    _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap3.mem.local.

            3. It may also be necessary to specify the IP address for
               the LDAP servers in '/etc/hosts' if the server host
               cannot be resolved.  For example, add lines like this to
               the file:

                    10.172.166.101 ldap1.mem.local
                    10.172.166.102 ldap2.mem.local
                    10.172.166.103 ldap3.mem.local

          With the DNS configured as just described, the server-side
          LDAP plugin can discover the LDAP servers and will try to
          authenticate in all domains until authentication succeeds or
          there are no more servers.

          Windows needs no such settings as just described.  Given the
          LDAP server host in the
          'authentication_ldap_simple_server_host' value, the Windows
          LDAP library searches all domains and attempts to
          authenticate.

   * 'authentication_ldap_simple_server_port'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-server-port=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_server_port'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '389'

     *Minimum Value*                      '1'

     *Maximum Value*                      '32376'

     For simple LDAP authentication, the LDAP server TCP/IP port number.

   * 'authentication_ldap_simple_tls'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-tls=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_tls'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     For simple LDAP authentication, whether connections by the plugin
     to the LDAP server are secure.  If this variable is enabled, the
     plugin uses TLS to connect securely to the LDAP server.  If you
     enable this variable, you may also wish to set the
     'authentication_ldap_simple_ca_path' variable.

     MySQL LDAP plugins support the StartTLS method, which initializes
     TLS on top of a plain LDAP connection.  The 'ldaps' method is
     deprecated and MySQL does not support it.

   * 'authentication_ldap_simple_user_search_attr'

     Property                             Value

     *Command-Line Format*                '--authentication-ldap-simple-user-search-attr=value'

     *Introduced*                         5.7.19

     *System Variable*                    'authentication_ldap_simple_user_search_attr'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'uid'

     For simple LDAP authentication, the name of the attribute that
     specifies user names in LDAP directory entries.  If a user
     distinguished name is not provided, the authentication plugin
     searches for the name using this attribute.  For example, if the
     'authentication_ldap_simple_user_search_attr' value is 'uid', a
     search for the user name 'user1' finds entries with a 'uid' value
     of 'user1'.

6.5.2 The Connection-Control Plugins
------------------------------------

As of MySQL 5.7.17, MySQL Server includes a plugin library that enables
administrators to introduce an increasing delay in server response to
clients after a certain number of consecutive failed connection
attempts.  This capability provides a deterrent that slows down brute
force attacks that attempt to access MySQL user accounts.  The plugin
library contains two plugins:

   * 'CONNECTION_CONTROL' checks incoming connections and adds a delay
     to server responses as necessary.  This plugin also exposes system
     variables that enable its operation to be configured and a status
     variable that provides rudimentary monitoring information.

     The 'CONNECTION_CONTROL' plugin uses the audit plugin interface
     (see writing-audit-plugins).  To collect information, it
     subscribes to the 'MYSQL_AUDIT_CONNECTION_CLASSMASK' event class,
     and processes 'MYSQL_AUDIT_CONNECTION_CONNECT' and
     'MYSQL_AUDIT_CONNECTION_CHANGE_USER' subevents to check whether the
     server should introduce a delay before responding to client
     connection attempts.

   * 'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS' implements an
     'INFORMATION_SCHEMA' table that exposes more detailed monitoring
     information for failed connection attempts.

The following sections provide information about connection-control
plugin installation and configuration.  For information about the
'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS'
table, see
connection-control-failed-login-attempts-table.

6.5.2.1 Connection-Control Plugin Installation
..............................................

This section describes how to install the connection-control plugins,
'CONNECTION_CONTROL' and 'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS'.
For general information about installing plugins, see
server-plugin-loading.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The plugin library file base name is 'connection_control'.  The file
name suffix differs per platform (for example, '.so' for Unix and
Unix-like systems, '.dll' for Windows).

To load the plugins at server startup, use the '--plugin-load-add'
option to name the library file that contains them.  With this
plugin-loading method, the option must be given each time the server
starts.  For example, put these lines in your 'my.cnf' file (adjust the
'.so' suffix for your platform as necessary):

     [mysqld]
     plugin-load-add=connection_control.so

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugins at runtime, use these statements
(adjust the '.so' suffix as necessary):

     INSTALL PLUGIN CONNECTION_CONTROL SONAME 'connection_control.so';
     INSTALL PLUGIN CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS SONAME 'connection_control.so';

'INSTALL PLUGIN' loads a plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE 'connection%';
     +------------------------------------------+---------------+
     | PLUGIN_NAME                              | PLUGIN_STATUS |
     +------------------------------------------+---------------+
     | CONNECTION_CONTROL                       | ACTIVE        |
     | CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS | ACTIVE        |
     +------------------------------------------+---------------+

If a plugin fails to initialize, check the server error log for
diagnostic messages.

If the plugins have been previously registered with 'INSTALL PLUGIN'
or are loaded with '--plugin-load-add', you can
use the '--connection-control' and
'--connection-control-failed-login-attempts' options at server startup
to control plugin activation.  For example, to load the plugins at
startup and prevent them from being removed at runtime, use these
options:

     [mysqld]
     plugin-load-add=connection_control.so
     connection-control=FORCE_PLUS_PERMANENT
     connection-control-failed-login-attempts=FORCE_PLUS_PERMANENT

If it is desired to prevent the server from running without a given
connection-control plugin, use an option value of 'FORCE' or
'FORCE_PLUS_PERMANENT' to force server startup to fail if the plugin
does not initialize successfully.

*Note*:

It is possible to install one plugin without the other, but both must be
installed for full connection-control capability.  In particular,
installing only the 'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS' plugin is
of little use because without the 'CONNECTION_CONTROL' plugin to provide
the data that populates the
'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS'
table, retrievals from
the table will always be empty.

   * connection-control-plugin-delay-configuration

   * connection-control-plugin-failure-assessment

   * connection-control-plugin-failure-monitoring

*Connection Delay Configuration*

To enable you to configure its operation, the 'CONNECTION_CONTROL'
plugin exposes several system variables:

   * 'connection_control_failed_connections_threshold': The number of
     consecutive failed connection attempts permitted to clients before
     the server adds a delay for subsequent connection attempts.

   * 'connection_control_min_connection_delay': The amount of delay to
     add for each consecutive connection failure above the threshold.

   * 'connection_control_max_connection_delay': The maximum delay to
     add.

To entirely disable checking for failed connection attempts, set
'connection_control_failed_connections_threshold' to zero.  If
'connection_control_failed_connections_threshold' is nonzero, the amount
of delay is zero up through that many consecutive failed connection
attempts.  Thereafter, the amount of delay is the number of failed
attempts above the threshold, multiplied by
'connection_control_min_connection_delay' milliseconds.  For example,
with the default 'connection_control_failed_connections_threshold' and
'connection_control_min_connection_delay' values of 3 and 1000,
respectively, there is no delay for the first three consecutive failed
connection attempts by a client, a delay of 1000 milliseconds for the
fourth failed attempt, 2000 milliseconds for the fifth failed attempt,
and so on, up to the maximum delay permitted by
'connection_control_max_connection_delay'.

You can set the 'CONNECTION_CONTROL' system variables at server startup
or runtime.  Suppose that you want to permit four consecutive failed
connection attempts before the server starts delaying its responses, and
to increase the delay by 1500 milliseconds for each additional failure
after that.  To set the relevant variables at server startup, put these
lines in your 'my.cnf' file:

     [mysqld]
     plugin-load-add=connection_control.so
     connection_control_failed_connections_threshold=4
     connection_control_min_connection_delay=1500

To set the variables at runtime, use these statements:

     SET GLOBAL connection_control_failed_connections_threshold = 4;
     SET GLOBAL connection_control_min_connection_delay = 1500;

'SET GLOBAL' sets the value for the running MySQL
instance.  To make the change permanent, add a line in your 'my.cnf'
file, as shown previously.

The 'connection_control_min_connection_delay' and
'connection_control_max_connection_delay' system variables have fixed
minimum and maximum values of 1000 and 2147483647, respectively.  In
addition, the permitted range of values of each variable also depends on
the current value of the other:

   * 'connection_control_min_connection_delay' cannot be set greater
     than the current value of
     'connection_control_max_connection_delay'.

   * 'connection_control_max_connection_delay' cannot be set less than
     the current value of 'connection_control_min_connection_delay'.

Thus, to make the changes required for some configurations, you might
need to set the variables in a specific order.  Suppose that the current
minimum and maximum delays are 1000 and 2000, and that you want to set
them to 3000 and 5000.  You cannot first set
'connection_control_min_connection_delay' to 3000 because that is
greater than the current 'connection_control_max_connection_delay' value
of 2000.  Instead, set 'connection_control_max_connection_delay' to
5000, then set 'connection_control_min_connection_delay' to 3000.

*Connection Failure Assessment*

When the 'CONNECTION_CONTROL' plugin is installed, it checks connection
attempts and tracks whether they fail or succeed.  For this purpose, a
failed connection attempt is one for which the client user and host
match a known MySQL account but the provided credentials are incorrect,
or do not match any known account.

Failed-connection counting is based on the user/host combination for
each connection attempt.  Determination of the applicable user name and
host name takes proxying into account and occurs as follows:

   * If the client user proxies another user, the proxying user's
     information is used.  For example, if 'external_user@example.com'
     proxies 'proxy_user@example.com', connection counting uses the
     proxying user, 'external_user@example.com', rather than the proxied
     user, 'proxy_user@example.com'.  Both 'external_user@example.com'
     and 'proxy_user@example.com' must have valid entries in the
     'mysql.user' system table and a proxy relationship between them
     must be defined in the 'mysql.proxies_priv' system table (see
     proxy-users).

   * If the client user does not proxy another user, but does match a
     'mysql.user' entry, counting uses the 'CURRENT_USER()' value
     corresponding to that entry.  For example, if a user 'user1'
     connecting from a host 'host1.example.com' matches a
     'user1@host1.example.com' entry, counting uses
     'user1@host1.example.com'.  If the user matches a
     'user1@%.example.com', 'user1@%.com', or 'user1@%' entry instead,
     counting uses 'user1@%.example.com', 'user1@%.com', or 'user1@%',
     respectively.

For the cases just described, the connection attempt matches some
'mysql.user' entry, and whether the request succeeds or fails depends on
whether the client provides the correct authentication credentials.  For
example, if the client presents an incorrect password, the connection
attempt fails.

If the connection attempt matches no 'mysql.user' entry, the attempt
fails.  In this case, no 'CURRENT_USER()' value is available and
connection-failure counting uses the user name provided by the client
and the client host as determined by the server.  For example, if a
client attempts to connect as user 'user2' from host
'host2.example.com', the user name part is available in the client
request and the server determines the host information.  The user/host
combination used for counting is 'user2@host2.example.com'.

*Note*:

The server maintains information about which client hosts can possibly
connect to the server (essentially the union of host values for
'mysql.user' entries).  If a client attempts to connect from any other
host, the server rejects the attempt at an early stage of connection
setup:

     ERROR 1130 (HY000): Host 'HOST_NAME' is not
     allowed to connect to this MySQL server

Because this type of rejection occurs so early, 'CONNECTION_CONTROL'
does not see it, and does not count it.

*Connection Failure Monitoring*

To monitor failed connections, use these information sources:

   * The 'Connection_control_delay_generated' status variable indicates
     the number of times the server added a delay to its response to a
     failed connection attempt.  This does not count attempts that occur
     before reaching the threshold defined by the
     'connection_control_failed_connections_threshold' system variable.

   * The 'INFORMATION_SCHEMA'
     'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS'
     table provides
     information about the current number of consecutive failed
     connection attempts per client user/host combination.  This counts
     all failed attempts, regardless of whether they were delayed.

Assigning a value to 'connection_control_failed_connections_threshold'
at runtime resets all accumulated failed-connection counters to zero,
which has these visible effects:

   * The 'Connection_control_delay_generated' status variable is reset
     to zero.

   * The 'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS'
     table becomes
     empty.

6.5.2.2 Connection-Control System and Status Variables
......................................................

This section describes the system and status variables that the
'CONNECTION_CONTROL' plugin provides to enable its operation to be
configured and monitored.

   * connection-control-plugin-system-variables

   * connection-control-plugin-status-variables

*Connection-Control System Variables*

If the 'CONNECTION_CONTROL' plugin is installed, it exposes these system
variables:

   * 'connection_control_failed_connections_threshold'

     Property                             Value

     *Command-Line Format*                '--connection-control-failed-connections-threshold=#'

     *Introduced*                         5.7.17

     *System Variable*                    'connection_control_failed_connections_threshold'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '3'

     *Minimum Value*                      '0'

     *Maximum Value*                      '2147483647'

     The number of consecutive failed connection attempts permitted to
     clients before the server adds a delay for subsequent connection
     attempts:

        * If the variable has a nonzero value N, the server adds a delay
          beginning with consecutive failed attempt N+1.  If a client
          has reached the point where connection responses are delayed,
          the delay also occurs for the next subsequent successful
          connection.

        * Setting this variable to zero disables failed-connection
          counting.  In this case, the server never adds delays.

     For information about how
     'connection_control_failed_connections_threshold' interacts with
     other connection-control system and status variables, see
     connection-control-installation.

   * 'connection_control_max_connection_delay'

     Property                             Value

     *Command-Line Format*                '--connection-control-max-connection-delay=#'

     *Introduced*                         5.7.17

     *System Variable*                    'connection_control_max_connection_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '2147483647'

     *Minimum Value*                      '1000'

     *Maximum Value*                      '2147483647'

     The maximum delay in milliseconds for server response to failed
     connection attempts, if
     'connection_control_failed_connections_threshold' is greater than
     zero.

     For information about how 'connection_control_max_connection_delay'
     interacts with other connection-control system and status
     variables, see connection-control-installation.

   * 'connection_control_min_connection_delay'

     Property                             Value

     *Command-Line Format*                '--connection-control-min-connection-delay=#'

     *Introduced*                         5.7.17

     *System Variable*                    'connection_control_min_connection_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '1000'

     *Maximum Value*                      '2147483647'

     The minimum delay in milliseconds for server response to failed
     connection attempts, if
     'connection_control_failed_connections_threshold' is greater than
     zero.  This is also the amount by which the server increases the
     delay for additional successive failures once it begins delaying.

     For information about how 'connection_control_min_connection_delay'
     interacts with other connection-control system and status
     variables, see connection-control-installation.

*Connection-Control Status Variables*

If the 'CONNECTION_CONTROL' plugin is installed, it exposes this status
variable:

   * 'Connection_control_delay_generated'

     The number of times the server added a delay to its response to a
     failed connection attempt.  This does not count attempts that occur
     before reaching the threshold defined by the
     'connection_control_failed_connections_threshold' system variable.

     This variable provides a simple counter.  For more detailed
     connection-control monitoring information, examine the
     'INFORMATION_SCHEMA'
     'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS'
     table; see
     connection-control-failed-login-attempts-table.

     Assigning a value to
     'connection_control_failed_connections_threshold' at runtime resets
     'Connection_control_delay_generated' to zero.

     This variable was added in MySQL 5.7.17.

6.5.3 The Password Validation Plugin
------------------------------------

The 'validate_password' plugin serves to test passwords and improve
security.  The plugin exposes a set of system variables that enable you
to define password policy.

The 'validate_password' plugin implements these capabilities:

   * In SQL statements that assign a password supplied as a cleartext
     value, the plugin checks the password against the current password
     policy and rejects the password if it is weak (the statement
     returns an 'ER_NOT_VALID_PASSWORD' error).  This applies to the
     'ALTER USER', 'CREATE USER',
     'GRANT', and 'SET PASSWORD'.
     statements, and passwords given as arguments to the 'PASSWORD()'
     and 'OLD_PASSWORD()' functions.

   * The 'VALIDATE_PASSWORD_STRENGTH()' SQL function assesses the
     strength of potential passwords.  The function takes a password
     argument and returns an integer from 0 (weak) to 100 (strong).

For example, 'validate_password' checks the cleartext password in the
following statement.  Under the default password policy, which requires
passwords to be at least 8 characters long, the password is weak and the
statement produces an error:

     mysql> ALTER USER USER() IDENTIFIED BY 'abc';
     ERROR 1819 (HY000): Your password does not satisfy the current
     policy requirements

Passwords specified as hashed values are not checked because the
original password value is not available for checking:

     mysql> ALTER USER 'jeffrey'@'localhost'
            IDENTIFIED WITH mysql_native_password
            AS '*0D3CED9BEC10A777AEC23CCC353A8C08A633045E';
     Query OK, 0 rows affected (0.01 sec)

To configure password checking, modify the system variables having names
of the form 'validate_password_XXX'; these are the parameters that
control password policy.  See
validate-password-options-variables.

If 'validate_password' is not installed, the 'validate_password_XXX'
system variables are not available, passwords in statements are not
checked, and the 'VALIDATE_PASSWORD_STRENGTH()' function always returns
0.  For example, without the plugin installed, accounts can be assigned
passwords shorter than 8 characters.

Assuming that 'validate_password' is installed, it implements three
levels of password checking: 'LOW', 'MEDIUM', and 'STRONG'.  The default
is 'MEDIUM'; to change this, modify the value of
'validate_password_policy'.  The policies implement increasingly strict
password tests.  The following descriptions refer to default parameter
values, which can be modified by changing the appropriate system
variables.

   * 'LOW' policy tests password length only.  Passwords must be at
     least 8 characters long.  To change this length, modify
     'validate_password_length'.

   * 'MEDIUM' policy adds the conditions that passwords must contain at
     least 1 numeric character, 1 lowercase character, 1 uppercase
     character, and 1 special (nonalphanumeric) character.  To change
     these values, modify 'validate_password_number_count',
     'validate_password_mixed_case_count', and
     'validate_password_special_char_count'.

   * 'STRONG' policy adds the condition that password substrings of
     length 4 or longer must not match words in the dictionary file, if
     one has been specified.  To specify the dictionary file, modify
     'validate_password_dictionary_file'.

In addition, as of MySQL 5.7.15, 'validate_password' supports the
capability of rejecting passwords that match the user name part of the
effective user account for the current session, either forward or in
reverse.  To provide control over this capability, 'validate_password'
exposes a 'validate_password_check_user_name' system variable, which is
enabled by default.

6.5.3.1 Password Validation Plugin Installation
...............................................

This section describes how to install the 'validate_password'
password-validation plugin.  For general information about installing
plugins, see server-plugin-loading.

*Note*:

If you installed MySQL 5.7 using the MySQL Yum repository
(http://dev.mysql.com/downloads/repo/yum/), MySQL SLES Repository
(http://dev.mysql.com/downloads/repo/suse/), or RPM packages provided by Oracle,
'validate_password' is
enabled by default after you started your MySQL Server for the first
time.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The plugin library file base name is 'validate_password'.  The file name
suffix differs per platform (for example, '.so' for Unix and Unix-like
systems, '.dll' for Windows).

To load the plugin at server startup, use the '--plugin-load-add' option
to name the library file that contains it.  With this plugin-loading
method, the option must be given each time the server starts.  For
example, put these lines in your 'my.cnf' file (adjust the '.so' suffix
for your platform as necessary):

     [mysqld]
     plugin-load-add=validate_password.so

After modifying 'my.cnf', restart the server to cause the new settings
to take effect.

Alternatively, to register the plugin at runtime, use this statement
(adjust the '.so' suffix as necessary):

     INSTALL PLUGIN validate_password SONAME 'validate_password.so';

'INSTALL PLUGIN' loads the plugin, and also
registers it in the 'mysql.plugins' system table to cause the plugin to
be loaded for each subsequent normal server startup.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE 'validate%';
     +-------------------+---------------+
     | PLUGIN_NAME       | PLUGIN_STATUS |
     +-------------------+---------------+
     | validate_password | ACTIVE        |
     +-------------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

If the plugin has been previously registered with 'INSTALL PLUGIN'
or is loaded with '--plugin-load-add', you can
use the '--validate-password' option at server startup to control plugin
activation.  For example, to load the plugin at startup and prevent it
from being removed at runtime, use these options:

     [mysqld]
     plugin-load-add=validate_password.so
     validate-password=FORCE_PLUS_PERMANENT

If it is desired to prevent the server from running without the
password-validation plugin, use '--validate-password' with a value of
'FORCE' or 'FORCE_PLUS_PERMANENT' to force server startup to fail if the
plugin does not initialize successfully.

6.5.3.2 Password Validation Plugin Options and Variables
........................................................

This section describes the options, system variables, and status
variables that 'validate_password' provides to enable its operation to
be configured and monitored.

   * validate-password-options

   * validate-password-system-variables

   * validate-password-status-variables

*Password Validation Plugin Options*

To control the activation of the 'validate_password' plugin, use this
option:

   *
     '--validate-password[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--validate-password[=value]'

     *Type*                               enumeration

     *Default Value*                      'ON'

     *Valid Values*                       'ON' 'OFF' 'FORCE'
                                          'FORCE_PLUS_PERMANENT'

     This option controls how the server loads the 'validate_password'
     plugin at startup.  The value should be one of those available for
     plugin-loading options, as described in
     server-plugin-loading.  For example,
     '--validate-password=FORCE_PLUS_PERMANENT' tells the server to load
     the plugin at startup and prevents it from being removed while the
     server is running.

     This option is available only if the 'validate_password' plugin has
     been previously registered with 'INSTALL PLUGIN'
     or is loaded with '--plugin-load-add'.  See
     validate-password-installation.

*Password Validation Plugin System Variables*

If the 'validate_password' plugin is enabled, it exposes several system
variables that enable configuration of password checking:

     mysql> SHOW VARIABLES LIKE 'validate_password%';
     +--------------------------------------+--------+
     | Variable_name                        | Value  |
     +--------------------------------------+--------+
     | validate_password_check_user_name    | OFF    |
     | validate_password_dictionary_file    |        |
     | validate_password_length             | 8      |
     | validate_password_mixed_case_count   | 1      |
     | validate_password_number_count       | 1      |
     | validate_password_policy             | MEDIUM |
     | validate_password_special_char_count | 1      |
     +--------------------------------------+--------+

To change how passwords are checked, you can set these system variables
at server startup or at runtime.  The following list describes the
meaning of each variable.

   *
     'validate_password_check_user_name'

     Property                             Value

     *Command-Line Format*                '--validate-password-check-user-name'

     *Introduced*                         5.7.15

     *System Variable*                    'validate_password_check_user_name'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether 'validate_password' compares passwords to the user name
     part of the effective user account for the current session and
     rejects them if they match.  This variable is unavailable unless
     'validate_password' is installed.

     By default, 'validate_password_check_user_name' is disabled.  This
     variable controls user name matching independent of the value of
     'validate_password_policy'.

     When 'validate_password_check_user_name' is enabled, it has these
     effects:

        * Checking occurs in all contexts for which 'validate_password'
          is invoked, which includes use of statements such as
          'ALTER USER' or 'SET PASSWORD'
          to change the current user's password, and
          invocation of functions such as 'PASSWORD()' and
          'VALIDATE_PASSWORD_STRENGTH()'.

        * The user names used for comparison are taken from the values
          of the 'USER()' and 'CURRENT_USER()' functions for the current
          session.  An implication is that a user who has sufficient
          privileges to set another user's password can set the password
          to that user's name, and cannot set that user's password to
          the name of the user executing the statement.  For example,
          ''root'@'localhost'' can set the password for
          ''jeffrey'@'localhost'' to ''jeffrey'', but cannot set the
          password to ''root'.

        * Only the user name part of the 'USER()' and 'CURRENT_USER()'
          function values is used, not the host name part.  If a user
          name is empty, no comparison occurs.

        * If a password is the same as the user name or its reverse, a
          match occurs and the password is rejected.

        * User-name matching is case sensitive.  The password and user
          name values are compared as binary strings on a byte-by-byte
          basis.

        * If a password matches the user name,
          'VALIDATE_PASSWORD_STRENGTH()' returns 0 regardless of how
          other 'validate_password' system variables are set.

   *
     'validate_password_dictionary_file'

     Property                             Value

     *System Variable*                    'validate_password_dictionary_file'

     *Scope*                              Global

     *Dynamic* (>= 5.7.8)                 Yes

     *Dynamic* (<= 5.7.7)                 No

     *Type*                               file name

     The path name of the dictionary file that 'validate_password' uses
     for checking passwords.  This variable is unavailable unless
     'validate_password' is installed.

     By default, this variable has an empty value and dictionary checks
     are not performed.  For dictionary checks to occur, the variable
     value must be nonempty.  If the file is named as a relative path,
     it is interpreted relative to the server data directory.  File
     contents should be lowercase, one word per line.  Contents are
     treated as having a character set of 'utf8'.  The maximum permitted
     file size is 1MB.

     For the dictionary file to be used during password checking, the
     password policy must be set to 2 ('STRONG'); see the description of
     the 'validate_password_policy' system variable.  Assuming that is
     true, each substring of the password of length 4 up to 100 is
     compared to the words in the dictionary file.  Any match causes the
     password to be rejected.  Comparisons are not case sensitive.

     For 'VALIDATE_PASSWORD_STRENGTH()', the password is checked against
     all policies, including 'STRONG', so the strength assessment
     includes the dictionary check regardless of the
     'validate_password_policy' value.

     'validate_password_dictionary_file' can be set at runtime and
     assigning a value causes the named file to be read without a server
     restart.

   *
     'validate_password_length'

     Property                             Value

     *System Variable*                    'validate_password_length'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '8'

     *Minimum Value*                      '0'

     The minimum number of characters that 'validate_password' requires
     passwords to have.  This variable is unavailable unless
     'validate_password' is installed.

     The 'validate_password_length' minimum value is a function of
     several other related system variables.  The value cannot be set
     less than the value of this expression:

          validate_password_number_count
          + validate_password_special_char_count
          + (2 * validate_password_mixed_case_count)

     If 'validate_password' adjusts the value of
     'validate_password_length' due to the preceding constraint, it
     writes a message to the error log.

   *
     'validate_password_mixed_case_count'

     Property                             Value

     *System Variable*                    'validate_password_mixed_case_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '0'

     The minimum number of lowercase and uppercase characters that
     'validate_password' requires passwords to have if the password
     policy is 'MEDIUM' or stronger.  This variable is unavailable
     unless 'validate_password' is installed.

     For a given 'validate_password_mixed_case_count' value, the
     password must have that many lowercase characters, and that many
     uppercase characters.

   *
     'validate_password_number_count'

     Property                             Value

     *System Variable*                    'validate_password_number_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '0'

     The minimum number of numeric (digit) characters that
     'validate_password' requires passwords to have if the password
     policy is 'MEDIUM' or stronger.  This variable is unavailable
     unless 'validate_password' is installed.

   *
     'validate_password_policy'

     Property                             Value

     *System Variable*                    'validate_password_policy'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      '1'

     *Valid Values*                       '0' '1' '2'

     The password policy enforced by 'validate_password'.  This variable
     is unavailable unless 'validate_password' is installed.

     'validate_password_policy' affects how 'validate_password' uses its
     other policy-setting system variables, except for checking
     passwords against user names, which is controlled independently by
     'validate_password_check_user_name'.

     The 'validate_password_policy' value can be specified using numeric
     values 0, 1, 2, or the corresponding symbolic values 'LOW',
     'MEDIUM', 'STRONG'.  The following table describes the tests
     performed for each policy.  For the length test, the required
     length is the value of the 'validate_password_length' system
     variable.  Similarly, the required values for the other tests are
     given by other 'validate_password_XXX' variables.

     Policy         Tests Performed

     '0' or 'LOW'   Length

     '1' or         Length; numeric, lowercase/uppercase, and special
     'MEDIUM'       characters

     '2' or         Length; numeric, lowercase/uppercase, and special
     'STRONG'       characters; dictionary file

   *
     'validate_password_special_char_count'

     Property                             Value

     *System Variable*                    'validate_password_special_char_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '0'

     The minimum number of nonalphanumeric characters that
     'validate_password' requires passwords to have if the password
     policy is 'MEDIUM' or stronger.  This variable is unavailable
     unless 'validate_password' is installed.

*Password Validation Plugin Status Variables*

If the 'validate_password' plugin is enabled, it exposes status
variables that provide operational information:

     mysql> SHOW STATUS LIKE 'validate_password%';
     +-----------------------------------------------+---------------------+
     | Variable_name                                 | Value               |
     +-----------------------------------------------+---------------------+
     | validate_password_dictionary_file_last_parsed | 2015-06-29 11:08:51 |
     | validate_password_dictionary_file_words_count | 1902                |
     +-----------------------------------------------+---------------------+

The following list describes the meaning of each status variable.

   *
     'validate_password_dictionary_file_last_parsed'

     When the dictionary file was last parsed.

   *
     'validate_password_dictionary_file_words_count'

     The number of words read from the dictionary file.

6.5.4 The MySQL Keyring
-----------------------

MySQL Server supports a keyring service that enables internal server
components and plugins to securely store sensitive information for later
retrieval.  The implementation is plugin-based:

   * MySQL 5.7.11 and higher includes a keyring plugin, 'keyring_file',
     that stores keyring data in a file local to the server host.  This
     plugin is available in all MySQL distributions, Community Edition
     and Enterprise Edition included.  See keyring-file-plugin.

   * MySQL 5.7.21 and higher includes a keyring plugin,
     'keyring_encrypted_file', that stores keyring data in an encrypted
     file local to the server host.  This plugin is available in MySQL
     Enterprise Edition distributions.  See
     keyring-encrypted-file-plugin.

   * MySQL 5.7.12 and higher includes 'keyring_okv', a KMIP 1.1 plugin
     for use with KMIP-compatible back end keyring storage products such
     as Oracle Key Vault and Gemalto SafeNet KeySecure Appliance.  This
     plugin is available in MySQL Enterprise Edition distributions.  See
     keyring-okv-plugin.

   * MySQL 5.7.19 and higher includes 'keyring_aws', a plugin that
     communicates with the Amazon Web Services Key Management Service
     for key generation and uses a local file for key storage.  This
     plugin is available in MySQL Enterprise Edition distributions.  See
     keyring-aws-plugin.

   * MySQL 5.7.21 and higher supports a server operational mode that
     enables migration of keys between underlying keyring keystores.
     This enables DBAs to switch a MySQL installation from one keyring
     plugin to another.  See keyring-key-migration.

   * MySQL 5.7.13 and higher includes an SQL interface for keyring key
     management, implemented as a set of user-defined functions (UDFs).
     See keyring-udfs-general-purpose.

*Warning*:

The 'keyring_file' and 'keyring_encrypted_file' plugins for encryption
key management are not intended as a regulatory compliance solution.
Security standards such as PCI, FIPS, and others require use of key
management systems to secure, manage, and protect encryption keys in key
vaults or hardware security modules (HSMs).

Uses for the keyring within MySQL include:

   * The 'InnoDB' storage engine uses the keyring to store its key for
     tablespace encryption.  'InnoDB' can use any supported keyring
     plugin.

   * MySQL Enterprise Audit uses the keyring to store the audit log file
     encryption password.  The audit log plugin can use any supported
     keyring plugin.

For general keyring installation instructions, see
keyring-installation.  For information specific to a given keyring
plugin, see the section describing that plugin.

For information about using the keyring UDFs, see
keyring-udfs-general-purpose.

Keyring plugins and UDFs access a keyring service that provides the
interface for server components to the keyring.  For information about
accessing the keyring plugin service and writing keyring plugins, see
keyring-service, and writing-keyring-plugins.

6.5.4.1 Keyring Plugin Installation
...................................

Keyring service consumers require a keyring plugin to be installed.
MySQL provides these plugin choices:

   * 'keyring_file': A plugin that stores keyring data in a file local
     to the server host.  Available in all MySQL distributions as of
     MySQL 5.7.11.

   * 'keyring_encrypted_file': A plugin that stores keyring data in an
     encrypted file local to the server host.  Available in MySQL
     Enterprise Edition distributions as of MySQL 5.7.21.

   * 'keyring_okv': A plugin that uses KMIP-compatible back end keyring
     storage products such as Oracle Key Vault and Gemalto SafeNet
     KeySecure Appliance.  Available in MySQL Enterprise Edition
     distributions as of MySQL 5.7.12.

   * 'keyring_aws': A plugin that communicates with the Amazon Web
     Services Key Management Service as a back end for key generation
     and uses a local file for key storage.  Available in MySQL
     Enterprise Edition distributions as of MySQL 5.7.19.

This section describes how to install the keyring plugin of your
choosing.  For general information about installing plugins, see
server-plugin-loading.

If you intend to use keyring user-defined functions (UDFs) in
conjunction with the keyring plugin, install the UDFs following keyring
installation using the instructions in
keyring-udfs-general-purpose.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

Installation for each keyring plugin is similar.  The following
instructions use 'keyring_file'.  Users of a different keyring plugin
can substitute its name for 'keyring_file'.

The 'keyring_file' plugin library file base name is 'keyring_file'.  The
file name suffix differs per platform (for example, '.so' for Unix and
Unix-like systems, '.dll' for Windows).

*Note*:

Only one keyring plugin should be enabled at a time.  Enabling multiple
keyring plugins is unsupported and results may not be as anticipated.

The keyring plugin must be loaded early during the server startup
sequence so that server components can access it as necessary during
their own initialization.  For example, the 'InnoDB' storage engine uses
the keyring for tablespace encryption, so the keyring plugin must be
loaded and available prior to 'InnoDB' initialization.

To load the plugin, use the '--early-plugin-load' option to name the
plugin library file that contains it.  For example, on platforms where
the plugin library file suffix is '.so', use these lines in the server
'my.cnf' file (adjust the '.so' suffix for your platform as necessary):

     [mysqld]
     early-plugin-load=keyring_file.so

As of MySQL 5.7.12, the default '--early-plugin-load' value is empty.
To load a keyring plugin, you must use an explicit '--early-plugin-load'
option with a nonempty value.

*Important*:

In MySQL 5.7.11, the default '--early-plugin-load' value was the name of
the 'keyring_file' plugin library file, so that plugin was loaded by
default.  'InnoDB' tablespace encryption requires the 'keyring_file'
plugin to be loaded prior to 'InnoDB' initialization, so this change of
default '--early-plugin-load' value introduces an incompatibility for
upgrades from 5.7.11 to 5.7.12 or higher.  Administrators who have
encrypted 'InnoDB' tablespaces must take explicit action to ensure
continued loading of the 'keyring_file' plugin: Start the server with an
'--early-plugin-load' option that names the plugin library file.

Before starting the server, check the notes for your chosen keyring
plugin to see whether it permits or requires additional configuration:

   * For 'keyring_file': keyring-file-plugin.

   * For 'keyring_okv': keyring-okv-plugin.

   * For 'keyring_aws': keyring-aws-plugin

After performing any plugin-specific configuration, verify plugin
installation.  With the MySQL server running, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE 'keyring%';
     +--------------+---------------+
     | PLUGIN_NAME  | PLUGIN_STATUS |
     +--------------+---------------+
     | keyring_file | ACTIVE        |
     +--------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

If no keyring plugin is available when a server component tries to
access the keyring service, the service cannot be used by that
component.  As a result, the component may fail to initialize or may
initialize with limited functionality.  For example, if 'InnoDB' finds
that there are encrypted tablespaces when it initializes, it attempts to
access the keyring.  If the keyring is unavailable, 'InnoDB' can access
only unencrypted tablespaces.  To ensure that 'InnoDB' can access
encrypted tablespaces as well, use '--early-plugin-load' to load the
keyring plugin.

Plugins can be loaded by other methods, such as the '--plugin-load' or
'--plugin-load-add' option or the 'INSTALL PLUGIN'
statement.  However, keyring plugins loaded using those
methods may be available too late in the server startup sequence for
certain server components, such as 'InnoDB':

   * Plugin loading using '--plugin-load' or '--plugin-load-add' occurs
     after 'InnoDB' initialization.

   * Plugins installed using 'INSTALL PLUGIN' are
     registered in the 'mysql.plugin' system table and loaded
     automatically for subsequent server restarts.  However, because
     'mysql.plugin' is an 'InnoDB' table, any plugins named in it can be
     loaded during startup only after 'InnoDB' initialization.

6.5.4.2 Using the keyring_file File-Based Plugin
................................................

The 'keyring_file' plugin is a keyring plugin that stores keyring data
in a file local to the server host.

*Warning*:

The 'keyring_file' plugin for encryption key management is not intended
as a regulatory compliance solution.  Security standards such as PCI,
FIPS, and others require use of key management systems to secure,
manage, and protect encryption keys in key vaults or hardware security
modules (HSMs).

To install the 'keyring_file' plugin, use the general keyring
installation instructions found in keyring-installation,
together with the configuration information specific to 'keyring_file'
found here.

To be usable during the server startup process, 'keyring_file' must be
loaded using the '--early-plugin-load' option.  The 'keyring_file_data'
system variable optionally configures the location of the file used by
the 'keyring_file' plugin for data storage.  The default value is
platform specific.  To configure the file location explicitly, set the
variable value at startup.  For example, use these lines in the server
'my.cnf' file (adjust the '.so' suffix and file location for your
platform as necessary):

     [mysqld]
     early-plugin-load=keyring_file.so
     keyring_file_data=/usr/local/mysql/mysql-keyring/keyring

Keyring operations are transactional: The 'keyring_file' plugin uses a
backup file during write operations to ensure that it can roll back to
the original file if an operation fails.  The backup file has the same
name as the value of the 'keyring_file_data' system variable with a
suffix of '.backup'.

For additional information about 'keyring_file_data', see
keyring-system-variables.

As of MySQL 5.7.17, to ensure that keys are flushed only when the
correct keyring storage file exists, 'keyring_file' stores a SHA-256
checksum of the keyring in the file.  Before updating the file, the
plugin verifies that it contains the expected checksum.

The 'keyring_file' plugin supports the functions that comprise the
standard keyring service interface.  Keyring operations performed by
those functions are accessible at two levels:

   * SQL interface: In SQL statements, call the user-defined functions
     (UDFs) described in keyring-udfs-general-purpose.

   * C interface: In C-language code, call the keyring service functions
     described in keyring-service.

Example (using UDFs):

     SELECT keyring_key_generate('MyKey', 'AES', 32);
     SELECT keyring_key_remove('MyKey');

The key types permitted by 'keyring_file' are described in
keyring-key-types.

6.5.4.3 Using the keyring_encrypted_file Keyring Plugin
.......................................................

*Note*:

The 'keyring_encrypted_file' plugin is an extension included in MySQL
Enterprise Edition, a commercial product.  To learn more about
commercial products, see <http://www.mysql.com/products/>.

The 'keyring_encrypted_file' plugin is a keyring plugin that stores
keyring data in an encrypted file local to the server host.  This plugin
is available as of MySQL 5.7.21.

*Warning*:

The 'keyring_encrypted_file' plugin for encryption key management is not
intended as a regulatory compliance solution.  Security standards such
as PCI, FIPS, and others require use of key management systems to
secure, manage, and protect encryption keys in key vaults or hardware
security modules (HSMs).

To install the 'keyring_encrypted_file' plugin, use the general keyring
installation instructions found in keyring-installation,
together with the configuration information specific to
'keyring_encrypted_file' found here.

To be usable during the server startup process, 'keyring_encrypted_file'
must be loaded using the '--early-plugin-load' option.  To specify the
password for encrypting the keyring data file, set the
'keyring_encrypted_file_password' system variable.  (The password is
mandatory; if not specified at server startup, 'keyring_encrypted_file'
initialization fails.)  The 'keyring_encrypted_file_data' system
variable optionally configures the location of the file used by the
'keyring_encrypted_file' plugin for data storage.  The default value is
platform specific.  To configure the file location explicitly, set the
variable value at startup.  For example, use these lines in the server
'my.cnf' file (adjust the '.so' suffix and file location for your
platform as necessary and substitute your chosen password):

     [mysqld]
     early-plugin-load=keyring_encrypted_file.so
     keyring_encrypted_file_data=/usr/local/mysql/mysql-keyring/keyring-encrypted
     keyring_encrypted_file_password=PASSWORD

Because the 'my.cnf' file stores a password when written as shown, it
should have a restrictive mode and be accessible only to the account
used to run the MySQL server.

Keyring operations are transactional: The 'keyring_encrypted_file'
plugin uses a backup file during write operations to ensure that it can
roll back to the original file if an operation fails.  The backup file
has the same name as the value of the 'keyring_encrypted_file_data'
system variable with a suffix of '.backup'.

For additional information about the system variables used to configure
the 'keyring_encrypted_file' plugin, see
keyring-system-variables.

To ensure that keys are flushed only when the correct keyring storage
file exists, 'keyring_encrypted_file' stores a SHA-256 checksum of the
keyring in the file.  Before updating the file, the plugin verifies that
it contains the expected checksum.  In addition,
'keyring_encrypted_file' encrypts file contents using AES before writing
the file, and decrypts file contents after reading the file.

The 'keyring_encrypted_file' plugin supports the functions that comprise
the standard keyring service interface.  Keyring operations performed by
those functions are accessible at two levels:

   * SQL interface: In SQL statements, call the user-defined functions
     (UDFs) described in keyring-udfs-general-purpose.

   * C interface: In C-language code, call the keyring service functions
     described in keyring-service.

Example (using UDFs):

     SELECT keyring_key_generate('MyKey', 'AES', 32);
     SELECT keyring_key_remove('MyKey');

The key types permitted by 'keyring_encrypted_file' are described in
keyring-key-types.

6.5.4.4 Using the keyring_okv KMIP Plugin
.........................................

*Note*:

The 'keyring_okv' plugin is an extension included in MySQL Enterprise
Edition, a commercial product.  To learn more about commercial products,
see <http://www.mysql.com/products/>.

The Key Management Interoperability Protocol (KMIP) enables
communication of cryptographic keys between a key management server and
its clients.  The 'keyring_okv' keyring plugin uses the KMIP 1.1
protocol to communicate securely as a client of a KMIP back end.
Keyring material is generated exclusively by the back end, not by
'keyring_okv'.  The plugin works with these KMIP-compatible products:

   * Oracle Key Vault

   * Gemalto SafeNet KeySecure Appliance

The 'keyring_okv' plugin supports the functions that comprise the
standard keyring service interface.  Keyring operations performed by
those functions are accessible at two levels:

   * SQL interface: In SQL statements, call the user-defined functions
     (UDFs) described in keyring-udfs-general-purpose.

   * C interface: In C-language code, call the keyring service functions
     described in keyring-service.

Example (using UDFs):

     SELECT keyring_key_generate('MyKey', 'AES', 32);
     SELECT keyring_key_remove('MyKey');

The key types permitted by 'keyring_okv' are described in
keyring-key-types.

To install the 'keyring_okv' plugin, use the general keyring
installation instructions found in keyring-installation,
together with the configuration information specific to 'keyring_okv'
found here.

   * keyring-okv-configuration

   * keyring-okv-oracle-key-vault

   * keyring-okv-keysecure

   * keyring-okv-encrypt-key-file

*General keyring_okv Configuration*

Regardless of which KMIP back end the 'keyring_okv' plugin uses for
keyring storage, the 'keyring_okv_conf_dir' system variable configures
the location of the directory used by 'keyring_okv' for its support
files.  The default value is empty, so you must set the variable to name
a properly configured directory before the plugin can communicate with
the KMIP back end.  Unless you do so, 'keyring_okv' writes a message to
the error log during server startup that it cannot communicate:

     [Warning] Plugin keyring_okv reported: 'For keyring_okv to be
     initialized, please point the keyring_okv_conf_dir variable to a directory
     containing Oracle Key Vault configuration file and ssl materials'

The 'keyring_okv_conf_dir' variable must name a directory that that
contains the following items:

   * 'okvclient.ora': A file that contains details of the KMIP back end
     with which 'keyring_okv' will communicate.

   * 'ssl': A directory that contains the certificate and key files
     required to establish a secure connection with the KMIP back end:
     'CA.pem', 'cert.pem', and 'key.pem'.  As of MySQL 5.7.20, if the
     key file is password-protected, the 'ssl' directory can contain a
     single-line text file named 'password.txt' containing the password
     needed to decrypt the key file.

Both the 'okvclient.ora' file and 'ssl' directory with the certificate
and key files are required for 'keyring_okv' to work properly.  The
procedure used to populate the configuration directory with these files
depends on the KMIP back end used with 'keyring_okv', as described
elsewhere.

The configuration directory used by 'keyring_okv' as the location for
its support files should have a restrictive mode and be accessible only
to the account used to run the MySQL server.  For example, on Unix and
Unix-like systems, to use the '/usr/local/mysql/mysql-keyring-okv'
directory, the following commands (executed as 'root') create the
directory and set its mode and ownership:

     cd /usr/local/mysql
     mkdir mysql-keyring-okv
     chmod 750 mysql-keyring-okv
     chown mysql mysql-keyring-okv
     chgrp mysql mysql-keyring-okv

To be usable during the server startup process, 'keyring_okv' must be
loaded using the '--early-plugin-load' option.  Also, set the
'keyring_okv_conf_dir' system variable to tell 'keyring_okv' where to
find its configuration directory.  For example, use these lines in the
server 'my.cnf' file (adjust the '.so' suffix and directory location for
your platform as necessary):

     [mysqld]
     early-plugin-load=keyring_okv.so
     keyring_okv_conf_dir=/usr/local/mysql/mysql-keyring-okv

For additional information about 'keyring_okv_conf_dir', see
keyring-system-variables.

*Configuring keyring_okv for Oracle Key Vault*

The discussion here assumes that you are familiar with Oracle Key Vault.
Some pertinent information sources:

   * Oracle Key Vault site
     (http://www.oracle.com/technetwork/database/options/key-management/overview/index.html)

   * Oracle Key Vault documentation
     (http://www.oracle.com/technetwork/database/options/key-management/documentation/index.html)

In Oracle Key Vault terminology, clients that use Oracle Key Vault to
store and retrieve security objects are called endpoints.  To
communicate with Oracle Key Vault, it is necessary to register as an
endpoint and enroll by downloading and installing endpoint support
files.

The following procedure briefly summarizes the process of setting up
'keyring_okv' for use with Oracle Key Vault:

  1. Create the configuration directory for the 'keyring_okv' plugin to
     use.

  2. Register an endpoint with Oracle Key Vault to obtain an enrollment
     token.

  3. Use the enrollment token to obtain the 'okvclient.jar' client
     software download.

  4. Install the client software to populate the 'keyring_okv'
     configuration directory that contains the Oracle Key Vault support
     files.

Use the following procedure to configure 'keyring_okv' and Oracle Key
Vault to work together.  This description only summarizes how to
interact with Oracle Key Vault.  For details, visit the Oracle Key Vault
(http://www.oracle.com/technetwork/database/options/key-management/overview/index.html)
site and consult the Oracle Key Vault Administrator's Guide.

  1. Create the configuration directory that will contain the Oracle Key
     Vault support files, and make sure that the 'keyring_okv_conf_dir'
     system variable is set to name that directory (for details, see
     keyring-okv-configuration).

  2. Log in to the Oracle Key Vault management console as a user who has
     the System Administrator role.

  3. Select the Endpoints tab to arrive at the Endpoints page.  On the
     Endpoints page, click Add.

  4. Provide the required endpoint information and click Register.  The
     endpoint type should be Other.  Successful registration results in
     an enrollment token.

  5. Log out from the Oracle Key Vault server.

  6. Connect again to the Oracle Key Vault server, this time without
     logging in.  Use the endpoint enrollment token to enroll and
     request the 'okvclient.jar' software download.  Save this file to
     your system.

  7. Install the 'okvclient.jar' file using the following command (you
     must have JDK 1.4 or higher):

          java -jar okvclient.jar -d DIR_NAME [-v]

     The directory name following the '-d' option is the location in
     which to install extracted files.  The '-v' option, if given,
     causes log information to be produced that may be useful if the
     command fails.

     When the command asks for an Oracle Key Vault endpoint password, do
     not provide one.  Instead, press Enter.  (The result is that no
     password will be required when the endpoint connects to Oracle Key
     Vault.)

  8. The preceding command produces an 'okvclient.ora' file, which
     should be in this location under the directory named by the '-d'
     option in the preceding 'java -jar' command:

          install_dir/conf/okvclient.ora

     The file contents include lines that look something like this:

          SERVER=HOST_IP:PORT_NUM
          STANDBY_SERVER=HOST_IP:PORT_NUM

     The 'keyring_okv' plugin attempts to communicate with the server
     running on the host named by the 'SERVER' variable and falls back
     to 'STANDBY_SERVER' if that fails:

        * For the 'SERVER' variable, a setting in the 'okvclient.ora'
          file is mandatory.

        * For the 'STANDBY_SERVER' variable, a setting in the
          'okvclient.ora' file is optional, as of MySQL 5.7.19.  Prior
          to MySQL 5.7.19, a setting for 'STANDBY_SERVER' is mandatory;
          if 'okvclient.ora' is generated with no setting for
          'STANDBY_SERVER', 'keyring_okv' fails to initialize.  The
          workaround is to check 'oraclient.ora' and add a 'dummy'
          setting for 'STANDBY_SERVER', if one is missing.  For example:

               STANDBY_SERVER=127.0.0.1:5696

  9. Go to the Oracle Key Vault installer directory and test the setup
     by running this command:

          okvutil/bin/okvutil list

     The output should look something like this:

          Unique ID                               Type            Identifier
          255AB8DE-C97F-482C-E053-0100007F28B9	Symmetric Key	-
          264BF6E0-A20E-7C42-E053-0100007FB29C	Symmetric Key	-

     For a fresh Oracle Key Vault server (a server without any key in
     it), the output looks like this instead, to indicate that there are
     no keys in the vault:

          no objects found

  10. Use this command to extract the 'ssl' directory containing SSL
     materials from the 'okvclient.jar' file:

          jar xf okvclient.jar ssl

  11. Copy the Oracle Key Vault support files (the 'okvclient.ora' file
     and the 'ssl' directory) into the configuration directory.

  12. (Optional) If you wish to password-protect the key file, use the
     instructions in keyring-okv-encrypt-key-file.

After completing the preceding procedure, restart the MySQL server.  It
loads the 'keyring_okv' plugin and 'keyring_okv' uses the files in its
configuration directory to communicate with Oracle Key Vault.

*Configuring keyring_okv for Gemalto SafeNet KeySecure Appliance*

Gemalto SafeNet KeySecure Appliance uses the KMIP protocol (version 1.1
or 1.2).  As of MySQL 5.7.18, the 'keyring_okv' keyring plugin (which
supports KMIP 1.1) can use KeySecure as its KMIP back end for keyring
storage.

Use the following procedure to configure 'keyring_okv' and KeySecure to
work together.  The description only summarizes how to interact with
KeySecure.  For details, consult the section named Add a KMIP Server in
the KeySecure User Guide
(https://safenet.gemalto.com/uploadedFiles/Support_and_Downloads/AWS/007-012362-001-keysecure-appliance-user-guide-v7.1.0.pdf).

  1. Create the configuration directory that will contain the KeySecure
     support files, and make sure that the 'keyring_okv_conf_dir' system
     variable is set to name that directory (for details, see
     keyring-okv-configuration).

  2. In the configuration directory, create a subdirectory named 'ssl'
     to use for storing the required SSL certificate and key files.

  3. In the configuration directory, create a file named
     'okvclient.ora'.  It should have following format:

          SERVER=HOST_IP:PORT_NUM
          STANDBY_SERVER=HOST_IP:PORT_NUM

     For example, if KeySecure is running on host 198.51.100.20 and
     listening on port 9002, the 'okvclient.ora' file looks like this:

          SERVER=198.51.100.20:9002
          STANDBY_SERVER=198.51.100.20:9002

  4. Connect to the KeySecure Management Console as an administrator
     with credentials for Certificate Authorities access.

  5. Navigate to Security >> Local CAs and create a local certificate
     authority (CA).

  6. Go to Trusted CA Lists.  Select Default and click on Properties.
     Then select Edit for Trusted Certificate Authority List and add the
     CA just created.

  7. Download the CA and save it in the 'ssl' directory as a file named
     'CA.pem'.

  8. Navigate to Security >> Certificate Requests and create a
     certificate.  Then you will be able to download a compressed 'tar'
     file containing certificate PEM files.

  9. Extract the PEM files from in the downloaded file.  For example, if
     the file name is 'csr_w_pk_pkcs8.gz', decompress and unpack it
     using this command:

          tar zxvf csr_w_pk_pkcs8.gz

     Two files result from the extraction operation:
     'certificate_request.pem' and 'private_key_pkcs8.pem'.

  10. Use this 'openssl' command to decrypt the private key and create a
     file named 'key.pem':

          openssl pkcs8 -in private_key_pkcs8.pem -out key.pem

  11. Copy the 'key.pem' file into the 'ssl' directory.

  12. Copy the certificate request in 'certificate_request.pem' into the
     clipboard.

  13. Navigate to Security >> Local CAs.  Select the same CA that you
     created earlier (the one you downloaded to create the 'CA.pem'
     file), and click Sign Request.  Paste the Certificate Request from
     the clipboard, choose a certificate purpose of Client (the keyring
     is a client of KeySecure), and click Sign Request.  The result is a
     certificate signed with the selected CA in a new page.

  14. Copy the signed certificate to the clipboard, then save the
     clipboard contents as a file named 'cert.pem' in the 'ssl'
     directory.

  15. (Optional) If you wish to password-protect the key file, use the
     instructions in keyring-okv-encrypt-key-file.

After completing the preceding procedure, restart the MySQL server.  It
loads the 'keyring_okv' plugin and 'keyring_okv' uses the files in its
configuration directory to communicate with KeySecure.

*Password-Protecting the keyring_okv Key File*

As of MySQL 5.7.20, you can optionally protect the key file with a
password and supply a file containing the password to enable the key
file to be decrypted.  To so do, change location to the 'ssl' directory
and perform these steps:

  1. Encrypt the 'key.pem' key file.  For example, use a command like
     this, and enter the encryption password at the prompts:

          shell> openssl rsa -des3 -in key.pem -out key.pem.new
          Enter PEM pass phrase:
          Verifying - Enter PEM pass phrase:

  2. Save the encryption password in a single-line text file named
     'password.txt' in the 'ssl' directory.

  3. Verify that the encrypted key file can be decrypted using the
     following command.  The decrypted file should display on the
     console:

          shell> openssl rsa -in key.pem.new -passin file:password.txt

  4. Remove the original 'key.pem' file and rename 'key.pem.new' to
     'key.pem'.

  5. Change the ownership and access mode of new 'key.pem' file and
     'password.txt' file as necessary to ensure that they have the same
     restrictions as other files in the 'ssl' directory.

6.5.4.5 Using the keyring_aws Amazon Web Services Keyring Plugin
................................................................

*Note*:

The 'keyring_aws' plugin is an extension included in MySQL Enterprise
Edition, a commercial product.  To learn more about commercial products,
see <http://www.mysql.com/products/>.

The 'keyring_aws' plugin is a keyring plugin that communicates with the
Amazon Web Services Key Management Service (AWS KMS) as a back end for
key generation and uses a local file for key storage.  All keyring
material is generated exclusively by the AWS server, not by
'keyring_aws'.

'keyring_aws' is available on these platforms:

   * Debian 8

   * EL7

   * macOS 10.12

   * OS X 10.10 and 10.11

   * SLES 12

   * Ubuntu 14.04 and 16.04

   * Windows

The discussion here assumes that you are familiar with AWS in general
and KMS in particular.  Some pertinent information sources:

   * AWS site (https://aws.amazon.com/kms/)

   * KMS documentation (https://docs.aws.amazon.com/kms/)

The following sections provide configuration and usage information for
the 'keyring_aws' keyring plugin:

   * keyring-aws-plugin-configuration

   * keyring-aws-plugin-operation

   * keyring-aws-plugin-credential-changes

*keyring_aws Configuration*

To install the 'keyring_aws' plugin, use the general installation
instructions found in keyring-installation, together with the
plugin-specific configuration information found here.

The plugin library file contains the 'keyring_aws' plugin and two
user-defined functions (UDFs), 'keyring_aws_rotate_cmk()' and
'keyring_aws_rotate_keys()'.

To configure 'keyring_aws', you must obtain a secret access key that
provides credentials for communicating with AWS KMS and write it to a
configuration file:

  1. Create an AWS KMS account.

  2. Use AWS KMS to create a secret access key ID and secret access key.
     The access key serves to verify your identity and that of your
     applications.

  3. Use the AWS KMS account to create a customer master key (CMK) ID.
     At MySQL startup, set the 'keyring_aws_cmk_id' system variable to
     the CMK ID value.  This variable is mandatory and there is no
     default.  (Its value can be changed at runtime if desired using
     'SET GLOBAL')

  4. If necessary, create the directory in which the configuration file
     will be located.  The directory should have a restrictive mode and
     be accessible only to the account used to run the MySQL server.
     For example, on Unix and Unix-like systems, to use
     '/usr/local/mysql/mysql-keyring/keyring_aws_conf' as the file name,
     the following commands (executed as 'root') create its parent
     directory and set the directory mode and ownership:

          shell> cd /usr/local/mysql
          shell> mkdir mysql-keyring
          shell> chmod 750 mysql-keyring
          shell> chown mysql mysql-keyring
          shell> chgrp mysql mysql-keyring

     At MySQL startup, set the 'keyring_aws_conf_file' system variable
     to '/usr/local/mysql/mysql-keyring/keyring_aws_conf' to indicate
     the configuration file location to the server.

  5. Prepare the 'keyring_aws' configuration file, which should contain
     two lines:

        * Line 1: The secret access key ID

        * Line 2: The secret access key

     For example, if the key ID is 'wwwwwwwwwwwwwEXAMPLE' and the key is
     'xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY', the configuration file
     looks like this:

          wwwwwwwwwwwwwEXAMPLE
          xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY

To be usable during the server startup process, 'keyring_aws' must be
loaded using the '--early-plugin-load' option.  The 'keyring_aws_cmk_id'
system variable is mandatory and configures the customer master key
(CMK) ID obtained from the AWS KMS server.  The 'keyring_aws_conf_file'
and 'keyring_aws_data_file' system variables optionally configure the
locations of the files used by the 'keyring_aws' plugin for
configuration information and data storage.  The file location variable
default values are platform specific.  To configure the locations
explicitly, set the variable values at startup.  For example, use these
lines in the server 'my.cnf' file (adjust the '.so' suffix and file
locations for your platform as necessary):

     [mysqld]
     early-plugin-load=keyring_aws.so
     keyring_aws_cmk_id='arn:aws:kms:us-west-2:111122223333:key/abcd1234-ef56-ab12-cd34-ef56abcd1234'
     keyring_aws_conf_file=/usr/local/mysql/mysql-keyring/keyring_aws_conf
     keyring_aws_data_file=/usr/local/mysql/mysql-keyring/keyring_aws_data

For the 'keyring_aws' plugin to start successfully, the configuration
file must exist and contain valid secret access key information,
initialized as described previously.  The storage file need not exist.
If it does not, 'keyring_aws' attempts to create it (as well as its
parent directory, if necessary).

For additional information about the system variables used to configure
the 'keyring_aws' plugin, see keyring-system-variables.

Start the MySQL server and install the UDFs associated with the
'keyring_aws' plugin.  This is a one-time operation, performed by
executing the following statements (adjust the '.so' suffix for your
platform as necessary):

     CREATE FUNCTION keyring_aws_rotate_cmk RETURNS INTEGER SONAME 'keyring_aws.so';
     CREATE FUNCTION keyring_aws_rotate_keys RETURNS INTEGER SONAME 'keyring_aws.so';

*keyring_aws Operation*

At plugin startup, the 'keyring_aws' plugin reads the AWS secret access
key ID and key from its configuration file.  It also reads any encrypted
keys contained in its storage file into its in-memory cache.

During operation, 'keyring_aws' maintains encrypted keys in the
in-memory cache and uses the storage file as local persistent storage.
Each keyring operation is transactional: 'keyring_aws' either
successfully changes both the in-memory key cache and the keyring
storage file, or the operation fails and the keyring state remains
unchanged.

To ensure that keys are flushed only when the correct keyring storage
file exists, 'keyring_aws' stores a SHA-256 checksum of the keyring in
the file.  Before updating the file, the plugin verifies that it
contains the expected checksum.

The 'keyring_aws' plugin supports the functions that comprise the
standard keyring service interface.  Keyring operations performed by
these functions are accessible at two levels:

   * C interface: In C-language code, call the keyring service functions
     described in keyring-service.

   * SQL interface: In SQL statements, call the user-defined functions
     (UDFs) described in keyring-udfs-general-purpose.

Example (using UDFs):

     SELECT keyring_key_generate('MyKey', 'AES', 32);
     SELECT keyring_key_remove('MyKey');

In addition, the 'keyring_aws_rotate_cmk()' and
'keyring_aws_rotate_keys()' UDFs 'extend' the keyring plugin interface
to provide AWS-related capabilities not covered by the standard keyring
service interface.  These capabilities are accessible only by calling
the UDFs.  There are no corresponding C-languge key service functions.

The key types permitted by 'keyring_aws' are described in
keyring-key-types.

*keyring_aws Credential Changes*

Assuming that the 'keyring_aws' plugin has initialized properly at
server startup, it is possible to change the credentials used for
communicating with AWS KMS:

  1. Use AWS KMS to create a new secret access key ID and secret access
     key.

  2. Store the new credentials in the configuration file (the file named
     by the 'keyring_aws_conf_file' system variable).  The file format
     is as described previously.

  3. Reinitialize the 'keyring_aws' plugin so that it rereads the
     configuration file.  Assuming that the new credentials are valid,
     the plugin should initialize successfully.

     There are two ways to reinitialize the plugin:

        * Restart the server.  This is simpler and has has no side
          effects, but is not suitable for installations that require
          minimal server downtime with as few restarts as possible.

        * Reinitialize the plugin without restarting the server by
          executing the following statements (adjust the '.so' suffix
          for your platform as necessary):

               UNINSTALL PLUGIN keyring_aws;
               INSTALL PLUGIN keyring_aws SONAME 'keyring_aws.so';

          *Note*:

          In addition to loading a plugin at runtime, see 'INSTALL PLUGIN'
          has the side effect of registering
          the plugin it in the 'mysql.plugin' system table.  Because of
          this, if you decide to stop using 'keyring_aws', it is not
          sufficient to remove the '--early-plugin-load' option from the
          set of options used to start the server.  That stops the
          plugin from loading early, but the server still attempts to
          load it when it gets to the point in the startup sequence
          where it loads the plugins registered in 'mysql.plugin'.

          Consequently, if you execute the 'UNINSTALL PLUGIN'
          plus 'INSTALL PLUGIN'.
          sequence just described to change the AWS KMS credentials,
          then to stop using 'keyring_aws', it is necessary to execute
          'UNINSTALL PLUGIN' again to
          unregister the plugin in addition to removing the
          '--early-plugin-load' option.

6.5.4.6 Migrating Keys Between Keyring Keystores
................................................

As of MySQL 5.7.21, the MySQL server supports an operational mode that
enables migration of keys between underlying keyring keystores.  This
enables DBAs to switch a MySQL installation from one keyring plugin to
another.  A migration server (that is, a server started in key migration
mode) does not accept client connections.  Instead, it runs only long
enough to migrate keys, then exits.  A migration server reports errors
to the console (the standard error output).

It is possible to perform offline or online key migration:

   * If you are sure that no running server on the local host is using
     the source or destination keystore, an offline migration is
     possible.  In this case, the migration server can modify the
     keystores without possibility of a running server modifying
     keystore content during the migration.

   * If a running server on the local host is using the source or
     destination keystore, an online migration must be performed.  In
     this case, the migration server connects to the running server and
     instructs it to pause keyring operations while key migration is in
     progress.

The result of a key migration operation is that the destination keystore
contains the keys it had prior to the migration, plus the keys from the
source keystore.  The source keystore is the same before and after the
migration because keys are copied, not moved.  If a key to be copied
already exists in the destination keystore, an error occurs and the
destination keystore is restored to its premigration state.

To perform a key migration operation, determine which key migration
options are needed.  Migration options indicate which keyring plugins
are involved, and whether to perform an offline or online migration:

   * To indicate the source and destination keyring plugins, specify
     these options:

        * '--keyring-migration-source': The source keyring plugin that
          manages the keys to be migrated.

        * '--keyring-migration-destination': The destination keyring
          plugin to which the migrated keys are to be copied.

     These options tell the server to run in key migration mode.  Both
     options are mandatory for all key migration operations.  The source
     and destination plugins must differ, and the migration server must
     support both plugins.

   * For an offline migration, no additional key migration options are
     needed.

     *Warning*:

     Do not perform offline migration involving a keystore that is in
     use by a running server.

   * For an online migration, some running server currently is using the
     source or destination keystore.  Specify the key migration options
     that indicate how to connect to the running server.  This is
     necessary so that the migration server can connect to the running
     server and tell it to pause keyring use during the migration
     operation.

     Use of any of the following options signifies an online migration:

        * '--keyring-migration-host': The host where the running server
          is located.  This is always the local host.

        * '--keyring-migration-user', '--keyring-migration-password':
          The user name and password for the account to use to connect
          to the running server.

        * '--keyring-migration-port': For TCP/IP connections, the port
          number to connect to on the running server.

        * '--keyring-migration-socket': For Unix socket file or Windows
          named pipe connections, the socket file or named pipe to
          connect to on the running server.

For additional details about the key migration options, see
keyring-options.

Start the migration server with the key migration options determined as
just described, possibly with other options.  Keep the following
considerations in mind:

   * Other server options might be required, such as other configuration
     parameters for the two keyring plugins.  For example, if
     'keyring_file' is one of the plugins, you must set the
     'keyring_file_data' system variable if the keyring data file
     location is not the default location.  Other non-keyring options
     may be required as well.  One way to specify these options is by
     using '--defaults-file' to name an option file that contains the
     required options.

   * If you invoke the migration server from a system account different
     from that normally used to run MySQL, it might create keyring
     directories or files that are inaccessible to the server during
     normal operation.  Suppose that 'mysqld' normally
     runs as the 'mysql' system user, but you invoke the migration
     server while logged in as 'isabel'.  Any new directories or files
     created by the migration server will be owned by 'isabel'.
     Subsequent startup will fail when a server run as the 'mysql'
     system user attempts to access file system objects owned by
     'isabel'.

     To avoid this problem, start the migration server as the 'root'
     system user and provide a '--user=USER_NAME' option, where
     USER_NAME is the system account normally used to run MySQL.

   * The migration server expects path name option values to be full
     paths.  Relative path names may not be resolved as you expect.

Example command line for offline key migration:

     mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
       --key-migration-source=keyring_file.so
       --key-migration-destination=keyring_encrypted_file.so
       --keyring_encrypted_file_password=PASSWORD

Example command line for online key migration:

     mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
       --key-migration-source=keyring_file.so
       --key-migration-destination=keyring_encrypted_file.so
       --keyring_encrypted_file_password=PASSWORD
       --key-migration-host=localhost
       --key-migration-user=root
       --key-migration-password=ROOT_PASSWORD

The key migration server performs the migration operation as follows:

  1. (Online migration only) Connect to the running server using the
     connection options.  The account used to connect must have the
     'SUPER' privilege required to modify the global
     'keyring_operations' system variable.

  2. (Online migration only) Disable 'keyring_operations' on the running
     server.  (The running server must support 'keyring_operations',
     which means it must be from MySQL 5.7.21 or higher.)

  3. Load the source and destination keyring plugins.

  4. Copy keys from the source keyring to the destination keyring.

  5. Unload the keyring plugins.

  6. (Online migration only) Enable 'keyring_operations' on the running
     server.

  7. (Online migration only) Disconnect from the running server.

  8. Exit.

If an error occurs during key migration, any keys that were copied to
the destination plugin are removed, leaving the destination keystore
unchanged.

*Important*:

For an online migration operation, the migration server takes care of
enabling and disabling 'keyring_operations' on the running server.
However, if the migration server exits abnormally (for example, if
someone forcibly terminates it), it is possible that
'keyring_operations' will not have been re-enabled on the running
server, leaving it unable to perform keyring operations.  In this case,
it may be necessary to connect to the running server and enable
'keyring_operations' manually.

After a successful online key migration operation, the running server
might need to be restarted:

   * If the running server was using the source keystore, it need not be
     restarted after the migration.

   * If the running server was using the source keystore before the
     migration but should use the destination keystore after the
     migration, it must be reconfigured to use the destination keyring
     plugin and restarted.

   * If the running server was using the destination keystore and will
     continue to use it, it should be restarted after the migration to
     load all keys migrated into the destination keystore.

*Note*:

MySQL server key migration mode supports pausing a single running
server.  To perform a key migration if multiple key servers are using
the keystores involved, use this procedure:

  1. Connect to each running server manually and set
     'keyring_operations=OFF'.

  2. Use the migration server to perform an offline key migration.

  3. Connect to each running server manually and set
     'keyring_operations=ON'.

All running servers must support the 'keyring_operations=ON' system
variable.

6.5.4.7 Supported Keyring Key Types
...................................

MySQL Keyring supports generating keys of different types (encryption
algorithms) and lengths.  The available key types depend on which
keyring plugin is installed.  A given plugin may also impose constraints
on key lengths per key type.

keyring-key-types-table summarizes the permitted key types per
keyring plugin.  Lengths are in bytes.  For a key generated using one of
the keyring user-defined functions (UDFs) described in
keyring-udfs-general-purpose, the length can be no more than 2,048
bytes, due to limitations of the UDF interface.

*Keyring Plugin Key Types*

Plugin Name            Permitted      Permitted Key Lengths for Key Type
                       Key Type

'keyring_encrypted_file'
                       'AES'          No special restrictions

                       'DSA'          No special restrictions

                       'RSA'          No special restrictions

'keyring_file'
                       'AES'          No special restrictions

                       'DSA'          No special restrictions

                       'RSA'          No special restrictions

'keyring_okv'          'AES'          16, 24, 32

'keyring_aws'          'AES'          16, 24, 32

6.5.4.8 General-Purpose Keyring Key-Management Functions
........................................................

MySQL Server supports a keyring service that enables internal server
components and plugins to securely store sensitive information for later
retrieval.

As of MySQL 5.7.13, MySQL Server includes an SQL interface for keyring
key management, implemented as a set of general-purpose user-defined
functions (UDFs) that access the functions provided by the internal
keyring service.  The keyring UDFs are contained in a plugin library
file, which also contains a 'keyring_udf' plugin that must be enabled
prior to UDF invocation.  For these UDFs to be used, a keyring plugin
such as 'keyring_file' or 'keyring_okv' must be enabled.

The UDFs described here are general purpose and intended for use with
any keyring plugin.  A given keyring plugin might have UDFs of its own
that are intended for use only with that plugin; see
keyring-udfs-plugin-specific.

The following sections provide installation instructions for the keyring
UDFs and demonstrate how to use them.  For information about the keyring
service functions invoked by the UDFs, see keyring-service.  For
general keyring information, see keyring.

6.5.4.9 Installing or Uninstalling General-Purpose Keyring Functions
....................................................................

This section describes how to install or uninstall the keyring
user-defined functions (UDFs), which are implemented in a plugin library
file that also contains a 'keyring_udf' plugin.  For general information
about installing or uninstalling plugins and UDFs, see
server-plugin-loading, and udf-compiling.

The keyring UDFs enable keyring key management operations, but the
'keyring_udf' plugin must also be installed because the UDFs will not
work correctly without it.  Attempts to use the UDFs without the
'keyring_udf' plugin result in an error.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

The plugin library file base name is 'keyring_udf'.  The file name
suffix differs per platform (for example, '.so' for Unix and Unix-like
systems, '.dll' for Windows).

To install the 'keyring_udf' plugin and the UDFs, use the 'INSTALL PLUGIN'
and 'CREATE FUNCTION'.
statements (adjust the '.so' suffix for your platform as necessary):

     INSTALL PLUGIN keyring_udf SONAME 'keyring_udf.so';
     CREATE FUNCTION keyring_key_generate RETURNS INTEGER SONAME 'keyring_udf.so';
     CREATE FUNCTION keyring_key_fetch RETURNS STRING SONAME 'keyring_udf.so';
     CREATE FUNCTION keyring_key_length_fetch RETURNS INTEGER SONAME 'keyring_udf.so';
     CREATE FUNCTION keyring_key_type_fetch RETURNS STRING SONAME 'keyring_udf.so';
     CREATE FUNCTION keyring_key_store RETURNS INTEGER SONAME 'keyring_udf.so';
     CREATE FUNCTION keyring_key_remove RETURNS INTEGER SONAME 'keyring_udf.so';

If the plugin and the UDFs are used on a master replication server,
install them on all slave servers as well to avoid replication problems.

Once installed as just described, the 'keyring_udf' plugin and the UDFs
remain installed until uninstalled.  To remove them, use the
'UNINSTALL PLUGIN' and 'DROP FUNCTION'
statements:

     UNINSTALL PLUGIN keyring_udf;
     DROP FUNCTION keyring_key_generate;
     DROP FUNCTION keyring_key_fetch;
     DROP FUNCTION keyring_key_length_fetch;
     DROP FUNCTION keyring_key_type_fetch;
     DROP FUNCTION keyring_key_store;
     DROP FUNCTION keyring_key_remove;

6.5.4.10 Using General-Purpose Keyring Functions
................................................

Before using the keyring user-defined functions (UDFs), install them
according to the instructions provided in
keyring-udf-installation.

The keyring UDFs are subject to these constraints:

   * To use any keyring UDF, the 'keyring_udf' plugin must be enabled.
     Otherwise, an error occurs:

          ERROR 1123 (HY000): Can't initialize function 'keyring_key_generate';
          This function requires keyring_udf plugin which is not installed.
          Please install

     To install the 'keyring_udf' plugin, see
     keyring-udf-installation.

   * The keyring UDFs invoke keyring service functions (see
     keyring-service).  The service functions in turn use whatever
     keyring plugin is installed (for example, 'keyring_file' or
     'keyring_okv').  Therefore, to use any keyring UDF, some underlying
     keyring plugin must be enabled.  Otherwise, an error occurs:

          ERROR 3188 (HY000): Function 'keyring_key_generate' failed because
          underlying keyring service returned an error. Please check if a
          keyring plugin is installed and that provided arguments are valid
          for the keyring you are using.

     To install a keyring plugin, see keyring-installation.

   * To use any keyring UDF, a user must possess the global 'EXECUTE'
     privilege.  Otherwise, an error occurs:

          ERROR 1123 (HY000): Can't initialize function 'keyring_key_generate';
          The user is not privileged to execute this function. User needs to
          have EXECUTE

     To grant the global 'EXECUTE' privilege to a user, use this
     statement:

          GRANT EXECUTE ON *.* TO USER;

     Alternatively, should you prefer to avoid granting the global
     'EXECUTE' privilege while still permitting users to access specific
     key-management operations, 'wrapper' stored programs can be defined
     (a technique described later in this section).

   * A key stored in the keyring by a given user can be manipulated
     later only by the same user.  That is, the value of the
     'CURRENT_USER()' function at the time of key manipulation must have
     the same value as when the key was stored in the keyring.  (This
     constraint rules out the use of the keyring UDFs for manipulation
     of instance-wide keys, such as those created by 'InnoDB' to support
     tablespace encryption.)

     To enable multiple users to perform operations on the same key,
     'wrapper' stored programs can be defined (a technique described
     later in this section).

   * Keyring UDFs support the key types and lengths supported by the
     underlying keyring plugin, with the additional constraint that keys
     cannot be longer than 2,048 bytes (16,384 bits), due to limitations
     of the UDF interface.  See keyring-key-types.

To create a new random key and store it in the keyring, call
'keyring_key_generate()', passing to it an ID for the key, along with
the key type (encryption method) and its length in bytes.  The following
call creates a 2,048-bit DSA-encrypted key named 'MyKey':

     mysql> SELECT keyring_key_generate('MyKey', 'DSA', 256);
     +-------------------------------------------+
     | keyring_key_generate('MyKey', 'DSA', 256) |
     +-------------------------------------------+
     |                                         1 |
     +-------------------------------------------+

A return value of 1 indicates success.  If the key cannot be created,
the return value is 'NULL' and an error occurs.  One reason this might
be is that the underlying keyring plugin does not support the specified
combination of key type and key length; see keyring-key-types.

To be able to check the return type regardless of whether an error
occurs, use 'SELECT ... INTO @VAR_NAME' and test the variable value:

     mysql> SELECT keyring_key_generate('', '', -1) INTO @x;
     ERROR 3188 (HY000): Function 'keyring_key_generate' failed because
     underlying keyring service returned an error. Please check if a
     keyring plugin is installed and that provided arguments are valid
     for the keyring you are using.
     mysql> SELECT @x;
     +------+
     | @x   |
     +------+
     | NULL |
     +------+
     mysql> SELECT keyring_key_generate('x', 'AES', 16) INTO @x;
     mysql> SELECT @x;
     +------+
     | @x   |
     +------+
     |    1 |
     +------+

This technique also applies to other keyring UDFs that for failure
return a value and an error.

The ID passed to 'keyring_key_generate()' provides a means by which to
refer to the key in subsequent UDF calls.  For example, use the key ID
to retrieve its type as a string or its length in bytes as an integer:

     mysql> SELECT keyring_key_type_fetch('MyKey');
     +---------------------------------+
     | keyring_key_type_fetch('MyKey') |
     +---------------------------------+
     | DSA                             |
     +---------------------------------+
     mysql> SELECT keyring_key_length_fetch('MyKey');
     +-----------------------------------+
     | keyring_key_length_fetch('MyKey') |
     +-----------------------------------+
     |                               256 |
     +-----------------------------------+

To retrieve a key value, pass the key ID to 'keyring_key_fetch()'.  The
following example uses 'HEX()' to display the key value because it may
contain nonprintable characters.  The example also uses a short key for
brevity, but be aware that longer keys provide better security:

     mysql> SELECT keyring_key_generate('MyShortKey', 'DSA', 8);
     +----------------------------------------------+
     | keyring_key_generate('MyShortKey', 'DSA', 8) |
     +----------------------------------------------+
     |                                            1 |
     +----------------------------------------------+
     mysql> SELECT HEX(keyring_key_fetch('MyShortKey'));
     +--------------------------------------+
     | HEX(keyring_key_fetch('MyShortKey')) |
     +--------------------------------------+
     | 1DB3B0FC3328A24C                     |
     +--------------------------------------+

Keyring UDFs treat key IDs, types, and values as binary strings, so
comparisons are case-sensitive.  For example, IDs of 'MyKey' and 'mykey'
refer to different keys.

To remove a key, pass the key ID to 'keyring_key_remove()':

     mysql> SELECT keyring_key_remove('MyKey');
     +-----------------------------+
     | keyring_key_remove('MyKey') |
     +-----------------------------+
     |                           1 |
     +-----------------------------+

To obfuscate and store a key that you provide, pass the key ID, type,
and value to 'keyring_key_store()':

     mysql> SELECT keyring_key_store('AES_key', 'AES', 'Secret string');
     +------------------------------------------------------+
     | keyring_key_store('AES_key', 'AES', 'Secret string') |
     +------------------------------------------------------+
     |                                                    1 |
     +------------------------------------------------------+

As indicated previously, a user must have the global 'EXECUTE' privilege
to call keyring UDFs, and the user who stores a key in the keyring
initially must be the same user who performs subsequent operations on
the key later, as determined from the 'CURRENT_USER()' value in effect
for each UDF call.  To permit key operations to users who do not have
the global 'EXECUTE' privilege or who may not be the key 'owner,' use
this technique:

  1. Define 'wrapper' stored programs that encapsulate the required key
     operations and have a 'DEFINER' value equal to the key owner.

  2. Grant the 'EXECUTE' privilege for specific stored programs to the
     individual users who should be able to invoke them.

  3. If the operations implemented by the wrapper stored programs do not
     include key creation, create any necessary keys in advance, using
     the account named as the 'DEFINER' in the stored program
     definitions.

This technique enables keys to be shared among users and provides to
DBAs more fine-grained control over who can do what with keys, without
having to grant global privileges.

The following example shows how to set up a shared key named 'SharedKey'
that is owned by the DBA, and a 'get_shared_key()' stored function that
provides access to the current key value.  The value can be retrieved by
any user with the 'EXECUTE' privilege for that function, which is
created in the 'key_schema' schema.

From a MySQL administrative account (''root'@'localhost'' in this
example), create the administrative schema and the stored function to
access the key:

     mysql> CREATE SCHEMA key_schema;

     mysql> CREATE DEFINER = 'root'@'localhost'
            FUNCTION key_schema.get_shared_key()
            RETURNS BLOB READS SQL DATA
            RETURN keyring_key_fetch('SharedKey');

From the administrative account, ensure that the shared key exists:

     mysql> SELECT keyring_key_generate('SharedKey', 'DSA', 8);
     +---------------------------------------------+
     | keyring_key_generate('SharedKey', 'DSA', 8) |
     +---------------------------------------------+
     |                                           1 |
     +---------------------------------------------+

From the administrative account, create an ordinary user account to
which key access is to be granted:

     mysql> CREATE USER 'key_user'@'localhost'
            IDENTIFIED BY 'key_user_pwd';

From the 'key_user' account, verify that, without the proper 'EXECUTE'
privilege, the new account cannot access the shared key:

     mysql> SELECT HEX(key_schema.get_shared_key());
     ERROR 1370 (42000): execute command denied to user 'key_user'@'localhost'
     for routine 'key_schema.get_shared_key'

From the administrative account, grant 'EXECUTE' to 'key_user' for the
stored function:

     mysql> GRANT EXECUTE ON FUNCTION key_schema.get_shared_key
            TO 'key_user'@'localhost';

From the 'key_user' account, verify that the key is now accessible:

     mysql> SELECT HEX(key_schema.get_shared_key());
     +----------------------------------+
     | HEX(key_schema.get_shared_key()) |
     +----------------------------------+
     | 9BAFB9E75CEEB013                 |
     +----------------------------------+

6.5.4.11 General-Purpose Keyring Function Reference
...................................................

For each general-purpose keyring user-defined function (UDF), this
section describes its purpose, calling sequence, and return value.  For
information about the conditions under which these UDFs can be invoked,
see keyring-udf-usage.

   * 'keyring_key_fetch()'

     Given a key ID, deobfuscates and returns the key value.

     Syntax:

          STRING keyring_key_fetch(STRING key_id)

     Arguments:

        * 'key_id': The key ID as a string.

     Return values:

     Returns the key value for success, 'NULL' if the key does not
     exist, or 'NULL' and an error for failure.

     *Note*:

     Keyring values retrieved using 'keyring_key_fetch()' are limited to
     2,048 bytes, due to limitations of the UDF interface.  A keyring
     value longer than that length can be stored using a keyring service
     function (see keyring-service), but if retrieved using
     'keyring_key_fetch()', is truncated to 2,048 bytes.

     Example:

          mysql> SELECT keyring_key_generate('RSA_key', 'RSA', 16);
          +--------------------------------------------+
          | keyring_key_generate('RSA_key', 'RSA', 16) |
          +--------------------------------------------+
          |                                          1 |
          +--------------------------------------------+
          mysql> SELECT HEX(keyring_key_fetch('RSA_key'));
          +-----------------------------------+
          | HEX(keyring_key_fetch('RSA_key')) |
          +-----------------------------------+
          | 91C2253B696064D3556984B6630F891A  |
          +-----------------------------------+
          mysql> SELECT keyring_key_type_fetch('RSA_key');
          +-----------------------------------+
          | keyring_key_type_fetch('RSA_key') |
          +-----------------------------------+
          | RSA                               |
          +-----------------------------------+
          mysql> SELECT keyring_key_length_fetch('RSA_key');
          +-------------------------------------+
          | keyring_key_length_fetch('RSA_key') |
          +-------------------------------------+
          |                                  16 |
          +-------------------------------------+

     The example uses 'HEX()' to display the key value because it may
     contain nonprintable characters.  The example also uses a short key
     for brevity, but be aware that longer keys provide better security.

   * 'keyring_key_generate()'

     Generates a new random key with a given ID, type, and length, and
     stores it in the keyring.  The type and length values must be
     consistent with the values supported by the underlying keyring
     plugin, with the additional constraint that keys cannot be longer
     than 2,048 bytes (16,384 bits), due to limitations of the UDF
     interface.  For the permitted types per plugin, see
     keyring-service.

     Syntax:

          STRING keyring_key_generate(STRING key_id, STRING key_type, INTEGER key_length)

     Arguments:

        * 'key_id': The key ID as a string.

        * 'key_type': The key type as a string.

        * 'key_length': The key length in bytes as an integer.  The
          maximum length is 2,048.

     Return values:

     Returns 1 for success, or 'NULL' and an error for failure.

     Example:

          mysql> SELECT keyring_key_generate('RSA_key', 'RSA', 384);
          +---------------------------------------------+
          | keyring_key_generate('RSA_key', 'RSA', 384) |
          +---------------------------------------------+
          |                                           1 |
          +---------------------------------------------+

   * 'keyring_key_length_fetch()'

     Given a key ID, returns the key length.

     Syntax:

          INTEGER keyring_key_length_fetch(STRING key_id)

     Arguments:

        * 'key_id': The key ID as a string.

     Return values:

     Returns the key length in bytes as an integer for success, 'NULL'
     if the key does not exist, or 'NULL' and an error for failure.

     Example:

     See the description of 'keyring_key_fetch()'.

   * 'keyring_key_remove()'

     Removes the key with a given ID from the keyring.

     Syntax:

          INTEGER keyring_key_remove(STRING key_id)

     Arguments:

        * 'key_id': The key ID as a string.

     Return values:

     Returns 1 for success, or 'NULL' for failure.

     Example:

          mysql> SELECT keyring_key_remove('AES_key');
          +-------------------------------+
          | keyring_key_remove('AES_key') |
          +-------------------------------+
          |                             1 |
          +-------------------------------+

   * 'keyring_key_store()'

     Obfuscates and stores a key in the keyring.

     Syntax:

          INTEGER keyring_key_store(STRING key_id, STRING key_type, STRING key)

     Arguments:

        * 'key_id': The key ID as a string.

        * 'key_type': The key type as a string.

        * 'key': The key value as a string.

     Return values:

     Returns 1 for success, or 'NULL' and an error for failure.

     Example:

          mysql> SELECT keyring_key_store('new key', 'DSA', 'My key value');
          +-----------------------------------------------------+
          | keyring_key_store('new key', 'DSA', 'My key value') |
          +-----------------------------------------------------+
          |                                                   1 |
          +-----------------------------------------------------+

   * 'keyring_key_type_fetch()'

     Given a key ID, returns the key type.

     Syntax:

          STRING keyring_key_type_fetch(STRING key_id)

     Arguments:

        * 'key_id': The key ID as a string.

     Return values:

     Returns the key type as a string for success, 'NULL' if the key
     does not exist, or 'NULL' and an error for failure.

     Example:

     See the description of 'keyring_key_fetch()'.

6.5.4.12 Plugin-Specific Keyring Key-Management Functions
.........................................................

For each keyring plugin-specific user-defined function (UDF), this
section describes its purpose, calling sequence, and return value.  For
information about general-purpose keyring UDFs, see
keyring-udfs-general-purpose.

   * 'keyring_aws_rotate_cmk()'

     This UDF is associated with the 'keyring_aws' plugin.  Its use
     requires the 'SUPER' privilege.

     'keyring_aws_rotate_cmk()' rotates the customer master key (CMK).
     Rotation changes only the key that AWS KMS uses for subsequent data
     key-encryption operations.  AWS KMS maintains previous CMK
     versions, so keys generated using previous CMKs remain decryptable
     after rotation.

     Rotation changes the CMK value used inside AWS KMS but does not
     change the ID used to refer to it, so there is no need to change
     the 'keyring_aws_cmk_id' system variable after calling
     'keyring_aws_rotate_cmk()'.

     Syntax:

          INTEGER keyring_aws_rotate_cmk()

     Arguments:

     None.

     Return values:

     Returns 1 for success, or 'NULL' and an error for failure.

   * 'keyring_aws_rotate_keys()'

     This UDF is associated with the 'keyring_aws' plugin.  Its use
     requires the 'SUPER' privilege.

     'keyring_aws_rotate_keys()' rotates keys stored in the
     'keyring_aws' storage file named by the 'keyring_aws_data_file'
     system variable.  Rotation sends each key stored in the file to AWS
     KMS for re-encryption using the value of the 'keyring_aws_cmk_id'
     system variable as the CMK value, and stores the new encrypted keys
     in the file.

     'keyring_aws_rotate_keys()' is useful for key re-encryption under
     these circumstances:

        * After rotating the CMK; that is, after invoking the
          'keyring_aws_rotate_cmk()' UDF

        * After changing the 'keyring_aws_cmk_id' system variable to a
          different key value

     Syntax:

          INTEGER keyring_aws_rotate_keys()

     Arguments:

     None.

     Return values:

     Returns 1 for success, or 'NULL' and an error for failure.

6.5.4.13 Keyring Command Options
................................

MySQL supports the following keyring-related command-line options:

   * '--keyring-migration-destination=PLUGIN'

     Property                             Value

     *Command-Line Format*                '--keyring-migration-destination=plugin_name'

     *Introduced*                         5.7.21

     *Type*                               string

     The destination keyring plugin for key migration.  See
     keyring-key-migration.  The format and interpretation of the
     option value is the same as described for the
     '--keyring-migration-source' option.

     *Note*:

     '--keyring-migration-source' and '--keyring-migration-destination'
     are mandatory for all keyring migration operations.  The source and
     destination plugins must differ, and the migration server must
     support both plugins.

   * '--keyring-migration-host=HOST_NAME'

     Property                             Value

     *Command-Line Format*                '--keyring-migration-host=host_name'

     *Introduced*                         5.7.21

     *Type*                               string

     *Default Value*                      'localhost'

     The host location of the running server that is currently using one
     of the key migration keystores.  See keyring-key-migration.
     Migration always occurs on the local host, so the option always
     specifies a value for connecting to a local server, such as
     'localhost', '127.0.0.1', '::1', or the local host IP address or
     host name.

   * '--keyring-migration-password[=PASSWORD]'

     Property                             Value

     *Command-Line Format*                '--keyring-migration-password[=password]'

     *Introduced*                         5.7.21

     *Type*                               string

     The password for connecting to the running server that is currently
     using one of the key migration keystores.  See
     keyring-key-migration.  If you omit the PASSWORD value following
     the option name on the command line, the server prompts for one.

     Specifying a password on the command line should be considered
     insecure.  See password-security-user.  You can use an
     option file to avoid giving the password on the command line.  In
     this case, the file should have a restrictive mode and be
     accessible only to the account used to run the migration server.

   * '--keyring-migration-port=PORT_NUM'

     Property                             Value

     *Command-Line Format*                '--keyring-migration-port=port_num'

     *Introduced*                         5.7.21

     *Type*                               numeric

     *Default Value*                      '3306'

     For TCP/IP connections, the port number for connecting to the
     running server that is currently using one of the key migration
     keystores.  See keyring-key-migration.

   * '--keyring-migration-socket=PATH'

     Property                             Value

     *Command-Line Format*                '--keyring-migration-socket={file_name|pipe_name}'

     *Introduced*                         5.7.21

     *Type*                               string

     For Unix socket file or Windows named pipe connections, the socket
     file or named pipe for connecting to the running server that is
     currently using one of the key migration keystores.  See
     keyring-key-migration.

   * '--keyring-migration-source=PLUGIN'

     Property                             Value

     *Command-Line Format*                '--keyring-migration-source=plugin_name'

     *Introduced*                         5.7.21

     *Type*                               string

     The source keyring plugin for key migration.  See
     keyring-key-migration.

     The option value is similar to that for '--plugin-load', except
     that only one plugin library can be specified.  The value is given
     as NAME'='PLUGIN_LIBRARY or PLUGIN_LIBRARY.  The NAME is the name
     of a plugin to load, and PLUGIN_LIBRARY is the name of the library
     file that contains the plugin code.  If the plugin library is named
     without any preceding plugin name, the server loads all plugins in
     the library.  The server looks for plugin library files in the
     directory named by the 'plugin_dir' system variable.

     *Note*:

     '--keyring-migration-source' and '--keyring-migration-destination'
     are mandatory for all keyring migration operations.  The source and
     destination plugins must differ, and the migration server must
     support both plugins.

   * '--keyring-migration-user=USER_NAME'

     Property                             Value

     *Command-Line Format*                '--keyring-migration-user=user_name'

     *Introduced*                         5.7.21

     *Type*                               string

     The user name for connecting to the running server that is
     currently using one of the key migration keystores.  See
     keyring-key-migration.

6.5.4.14 Keyring System Variables
.................................

MySQL Keyring plugins support the following system variables.  Use them
to configure keyring plugin operation.  These variables are unavailable
unless the appropriate keyring plugin is installed (see
keyring-installation).

   *
     'keyring_aws_cmk_id'

     Property                             Value

     *Command-Line Format*                '--keyring-aws-cmk-id'

     *Introduced*                         5.7.19

     *System Variable*                    'keyring_aws_cmk_id'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The customer master key (CMK) ID obtained from the AWS KMS server
     and used by the 'keyring_aws' plugin.  This variable is unavailable
     unless that plugin is installed, but if it is installed, a value
     for this variable is mandatory.

   *
     'keyring_aws_conf_file'

     Property                             Value

     *Command-Line Format*                '--keyring-aws-conf-file'

     *Introduced*                         5.7.19

     *System Variable*                    'keyring_aws_conf_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'platform specific'

     The location of the configuration file for the 'keyring_aws'
     keyring plugin.  This variable is unavailable unless that plugin is
     installed.

     At plugin startup, 'keyring_aws' reads the AWS secret access key ID
     and key from the configuration file.  For the 'keyring_aws' plugin
     to start successfully, the configuration file must exist and
     contain valid secret access key information, initialized as
     described in keyring-aws-plugin.

     The default file name is 'keyring_aws_conf', located in the default
     keyring file directory.  The location of this default directory is
     the same as for the 'keyring_file_data' system variable.  See the
     description of that variable for details, as well as for
     considerations to take into account if you create the directory
     manually.

   *
     'keyring_aws_data_file'

     Property                             Value

     *Command-Line Format*                '--keyring-aws-data-file'

     *Introduced*                         5.7.19

     *System Variable*                    'keyring_aws_data_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'platform specific'

     The location of the storage file for the 'keyring_aws' keyring
     plugin.  This variable is unavailable unless that plugin is
     installed.

     At plugin startup, if the value assigned to 'keyring_aws_data_file'
     specifies a file that does not exist, the 'keyring_aws' plugin
     attempts to create it (as well as its parent directory, if
     necessary).  If the file does exist, 'keyring_aws' reads any
     encrypted keys contained in the file into its in-memory cache.
     'keyring_aws' does not cache unencrypted keys in memory.

     The default file name is 'keyring_aws_data', located in the default
     keyring file directory.  The location of this default directory is
     the same as for the 'keyring_file_data' system variable.  See the
     description of that variable for details, as well as for
     considerations to take into account if you create the directory
     manually.

   * 'keyring_aws_region'

     Property                             Value

     *Command-Line Format*                '--keyring-aws-region'

     *Introduced*                         5.7.19

     *System Variable*                    'keyring_aws_region'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'us-east-1'

     *Valid Values*                       'ap-northheast-1'
                                          'ap-northheast-2' 'ap-south-1'
                                          'ap-southeast-1' 'ap-southeast-2'
                                          'eu-central-1' 'eu-west-1'
                                          'sa-east-1' 'us-east-1'
                                          'us-west-1' 'us-west-2'

     The AWS region.

   * 'keyring_encrypted_file_data'

     Property                             Value

     *Command-Line Format*                '--keyring-encrypted-file-data=file_name'

     *Introduced*                         5.7.21

     *System Variable*                    'keyring_encrypted_file_data'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               file name

     *Default Value*                      'platform specific'

     The path name of the data file used for secure data storage by the
     'keyring_encrypted_file' plugin.  This variable is unavailable
     unless that plugin is installed.  The file location should be in a
     directory considered for use only by keyring plugins.  For example,
     do not locate the file under the data directory.

     Keyring operations are transactional: The 'keyring_encrypted_file'
     plugin uses a backup file during write operations to ensure that it
     can roll back to the original file if an operation fails.  The
     backup file has the same name as the value of the
     'keyring_encrypted_file_data' system variable with a suffix of
     '.backup'.

     Do not use the same 'keyring_encrypted_file' data file for multiple
     MySQL instances.  Each instance should have its own unique data
     file.

     The default file name is 'keyring_encrypted', located in a
     directory that is platform specific and depends on the value of the
     'INSTALL_LAYOUT' 'CMake' option, as shown in the following table.
     To specify the default directory for the file explicitly if you are
     building from source, use the 'INSTALL_MYSQLKEYRINGDIR' 'CMake'
     option.

     'INSTALL_LAYOUT' Value    Default 'keyring_encrypted_file_data' Value

     'DEB', 'RPM', 'SLES',     '/var/lib/mysql-keyring/keyring_encrypted'
     'SVR4'

     Otherwise                 'keyring/keyring_encrypted' under the
                               'CMAKE_INSTALL_PREFIX' value

     At plugin startup, if the value assigned to
     'keyring_encrypted_file_data' specifies a file that does not exist,
     the 'keyring_encrypted_file' plugin attempts to create it (as well
     as its parent directory, if necessary).

     If you create the directory manually, it should have a restrictive
     mode and be accessible only to the account used to run the MySQL
     server.  For example, on Unix and Unix-like systems, to use the
     '/usr/local/mysql/mysql-keyring' directory, the following commands
     (executed as 'root') create the directory and set its mode and
     ownership:

          cd /usr/local/mysql
          mkdir mysql-keyring
          chmod 750 mysql-keyring
          chown mysql mysql-keyring
          chgrp mysql mysql-keyring

     If the 'keyring_encrypted_file' plugin cannot create or access its
     data file, it writes an error message to the error log.  If an
     attempted runtime assignment to 'keyring_encrypted_file_data'
     results in an error, the variable value remains unchanged.

     *Important*:

     Once the 'keyring_encrypted_file' plugin has created its data file
     and started to use it, it is important not to remove the file.
     Loss of the file will cause data encrypted using its keys to become
     inaccessible.  (It is permissible to rename or move the file, as
     long as you change the value of 'keyring_encrypted_file_data' to
     match.)

   * 'keyring_encrypted_file_password'

     Property                             Value

     *Command-Line Format*                '--keyring-encrypted-file-password=password'

     *Introduced*                         5.7.21

     *System Variable*                    'keyring_encrypted_file_password'

     *Scope*                              Global

     *Dynamic*                            Yes

     The password used by the 'keyring_encrypted_file' plugin.  This
     variable is unavailable unless that plugin is installed.  The
     password is mandatory for plugin operation; if not specified at
     server startup, 'keyring_encrypted_file' initialization fails.

     If this variable is specified in an option file, the file should
     have a restrictive mode and be accessible only to the account used
     to run the MySQL server.

     The password value cannot be displayed at runtime with 'SHOW VARIABLES'
     or the Performance Schena
     'global_variables'.
     table because the display value is obfuscated.

   *
     'keyring_file_data'

     Property                             Value

     *Command-Line Format*                '--keyring-file-data=file_name'

     *Introduced*                         5.7.11

     *System Variable*                    'keyring_file_data'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               file name

     *Default Value*                      'platform specific'

     The path name of the data file used for secure data storage by the
     'keyring_file' plugin.  This variable is unavailable unless that
     plugin is installed.  The file location should be in a directory
     considered for use only by keyring plugins.  For example, do not
     locate the file under the data directory.

     Keyring operations are transactional: The 'keyring_file' plugin
     uses a backup file during write operations to ensure that it can
     roll back to the original file if an operation fails.  The backup
     file has the same name as the value of the 'keyring_file_data'
     system variable with a suffix of '.backup'.

     Do not use the same 'keyring_file' data file for multiple MySQL
     instances.  Each instance should have its own unique data file.

     The default file name is 'keyring', located in a directory that is
     platform specific and depends on the value of the 'INSTALL_LAYOUT'
     'CMake' option, as shown in the following table.  To specify the
     default directory for the file explicitly if you are building from
     source, use the 'INSTALL_MYSQLKEYRINGDIR' 'CMake' option.

     'INSTALL_LAYOUT' Value    Default 'keyring_file_data' Value

     'DEB', 'RPM', 'SLES',     '/var/lib/mysql-keyring/keyring'
     'SVR4'

     Otherwise                 'keyring/keyring' under the
                               'CMAKE_INSTALL_PREFIX' value

     At plugin startup, if the value assigned to 'keyring_file_data'
     specifies a file that does not exist, the 'keyring_file' plugin
     attempts to create it (as well as its parent directory, if
     necessary).

     If you create the directory manually, it should have a restrictive
     mode and be accessible only to the account used to run the MySQL
     server.  For example, on Unix and Unix-like systems, to use the
     '/usr/local/mysql/mysql-keyring' directory, the following commands
     (executed as 'root') create the directory and set its mode and
     ownership:

          cd /usr/local/mysql
          mkdir mysql-keyring
          chmod 750 mysql-keyring
          chown mysql mysql-keyring
          chgrp mysql mysql-keyring

     If the 'keyring_file' plugin cannot create or access its data file,
     it writes an error message to the error log.  If an attempted
     runtime assignment to 'keyring_file_data' results in an error, the
     variable value remains unchanged.

     *Important*:

     Once the 'keyring_file' plugin has created its data file and
     started to use it, it is important not to remove the file.  For
     example, 'InnoDB' uses the file to store the master key used to
     decrypt the data in tables that use 'InnoDB' tablespace encryption;
     see innodb-tablespace-encryption.  Loss of the file will
     cause data in such tables to become inaccessible.  (It is
     permissible to rename or move the file, as long as you change the
     value of 'keyring_file_data' to match.)  It is recommended that you
     create a separate backup of the keyring data file immediately after
     you create the first encrypted table and before and after master
     key rotation.

   *
     'keyring_okv_conf_dir'

     Property                             Value

     *Command-Line Format*                '--keyring-okv-conf-dir=dir_name'

     *Introduced*                         5.7.12

     *System Variable*                    'keyring_okv_conf_dir'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               directory name

     *Default Value*                      'empty string'

     The path name of the directory that stores configuration
     information used by the 'keyring_okv' plugin.  This variable is
     unavailable unless that plugin is installed.  The location should
     be a directory considered for use only by the 'keyring_okv' plugin.
     For example, do not locate the directory under the data directory.

     The default 'keyring_okv_conf_dir' value is empty.  For the
     'keyring_okv' plugin to be able to access Oracle Key Vault, the
     value must be set to a directory that contains Oracle Key Vault
     configuration and SSL materials.  For instructions on setting up
     this directory, see keyring-okv-plugin.

     The directory should have a restrictive mode and be accessible only
     to the account used to run the MySQL server.  For example, on Unix
     and Unix-like systems, to use the
     '/usr/local/mysql/mysql-keyring-okv' directory, the following
     commands (executed as 'root') create the directory and set its mode
     and ownership:

          cd /usr/local/mysql
          mkdir mysql-keyring-okv
          chmod 750 mysql-keyring-okv
          chown mysql mysql-keyring-okv
          chgrp mysql mysql-keyring-okv

     If the value assigned to 'keyring_okv_conf_dir' specifies a
     directory that does not exist, or that does not contain
     configuration information that enables a connection to Oracle Key
     Vault to be established, 'keyring_okv' writes an error message to
     the error log.  If an attempted runtime assignment to
     'keyring_okv_conf_dir' results in an error, the variable value and
     keyring operation remain unchanged.

   * 'keyring_operations'

     Property                             Value

     *Introduced*                         5.7.21

     *System Variable*                    'keyring_operations'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Whether keyring operations are enabled.  This variable is used
     during key migration operations.  See
     keyring-key-migration.

6.5.5 MySQL Enterprise Audit
----------------------------

*Note*:

MySQL Enterprise Audit is an extension included in MySQL Enterprise
Edition, a commercial product.  To learn more about commercial products,
see <http://www.mysql.com/products/>.

MySQL Enterprise Edition includes MySQL Enterprise Audit, implemented
using a server plugin named 'audit_log'.  MySQL Enterprise Audit uses
the open MySQL Audit API to enable standard, policy-based monitoring,
logging, and blocking of connection and query activity executed on
specific MySQL servers.  Designed to meet the Oracle audit
specification, MySQL Enterprise Audit provides an out of box, easy to
use auditing and compliance solution for applications that are governed
by both internal and external regulatory guidelines.

When installed, the audit plugin enables MySQL Server to produce a log
file containing an audit record of server activity.  The log contents
include when clients connect and disconnect, and what actions they
perform while connected, such as which databases and tables they access.

After you install the audit plugin (see audit-log-installation),
it writes an audit log file.  By default, the file is named 'audit.log'
in the server data directory.  To change the name of the file, set the
'audit_log_file' system variable at server startup.

By default, audit log file contents are written in new-style XML format,
without compression or encryption.  To select the file format, set the
'audit_log_format' system variable at server startup.  For details on
file format and contents, see audit-log-file-formats.

For more information about controlling how logging occurs, including
audit log file naming and format selection, see
audit-log-logging-control.  To perform filtering of audited events,
see audit-log-filtering.  For descriptions of the parameters
used to configure the audit log plugin, see
audit-log-options-variables.

If the audit log plugin is enabled, the Performance Schema (see
performance-schema) has instrumentation for it.  To identify the
relevant instruments, use this query:

     SELECT NAME FROM performance_schema.setup_instruments
     WHERE NAME LIKE '%/alog/%';

6.5.5.1 Audit Log Components
............................

MySQL Enterprise Audit is based on the audit log plugin and related
components:

   * A server-side plugin named 'audit_log' examines auditable events
     and determines whether to write them to the audit log.

   * User-defined functions enable manipulation of filtering definitions
     that control logging behavior, the encryption password, and log
     file reading.

   * Tables in the 'mysql' system database provide persistent storage of
     filter and user account data.

   * System variables enable audit log configuration and status
     variables provide runtime operational information.

*Note*:

Prior to MySQL 5.7.13, MySQL Enterprise Audit consists only of the
'audit_log' plugin and operates in legacy mode.  See
audit-log-legacy-filtering.

6.5.5.2 Installing or Uninstalling MySQL Enterprise Audit
.........................................................

This section describes how to install or uninstall MySQL Enterprise
Audit, which is implemented using the audit log plugin and related
components described in audit-log-components.  For general
information about installing plugins, see server-plugin-loading.

*Note*:

If installed, the 'audit_log' plugin involves some minimal overhead even
when disabled.  To avoid this overhead, do not install MySQL Enterprise
Audit unless you plan to use it.

To be usable by the server, the plugin library file must be located in
the MySQL plugin directory (the directory named by the 'plugin_dir'
system variable).  If necessary, set the value of 'plugin_dir' at server
startup to tell the server the plugin directory location.

*Note*:

The instructions here apply for MySQL 5.7.13 or higher.  For MySQL
versions prior to 5.7.13, see Installing MySQL Enterprise Audit
(http://dev.mysql.com/doc/refman/5.6/en/audit-log-installation.html) in
MySQL 5.6 Reference Manual (http://dev.mysql.com/doc/refman/5.6/en/).

Also, prior to MySQL 5.7.13, MySQL Enterprise Audit consists only of the
'audit_log' plugin and includes none of the other components described
in audit-log-components.  As of MySQL 5.7.13, if the 'audit_log'
plugin is already installed from a version of MySQL prior to 5.7.13,
uninstall it using the following statement and restart the server before
installing the current version:

     UNINSTALL PLUGIN audit_log;

To install MySQL Enterprise Audit, look in the 'share' directory of your
MySQL installation and choose the script that is appropriate for your
platform.  The available scripts differ in the suffix used to refer to
the plugin library file:

   * 'audit_log_filter_win_install.sql': Choose this script for Windows
     systems that use '.dll' as the file name suffix.

   * 'audit_log_filter_linux_install.sql': Choose this script for Linux
     and similar systems that use '.so' as the file name suffix.

Run the script as follows.  The example here uses the Linux installation
script.  Make the appropriate substitution for your system.

     shell> mysql -u root -p < audit_log_filter_linux_install.sql
     Enter password: (ENTER ROOT PASSWORD HERE)

*Note*:

As of MySQL 5.7.21, for a new installation of MySQL Enterprise Audit,
'InnoDB' is used instead of 'MyISAM' for the audit log tables.  For
upgrades to an installation for which MySQL Enterprise Audit is already
installed, it is recommended that you alter the audit log tables to use
'InnoDB':

     ALTER TABLE mysql.audit_log_user ENGINE=InnoDB;
     ALTER TABLE mysql.audit_log_filter ENGINE=InnoDB;

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE 'audit%';
     +-------------+---------------+
     | PLUGIN_NAME | PLUGIN_STATUS |
     +-------------+---------------+
     | audit_log   | ACTIVE        |
     +-------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

After MySQL Enterprise Audit is installed, you can use the '--audit-log'
option for subsequent server startups to control 'audit_log' plugin
activation.  For example, to prevent the plugin from being removed at
runtime, use this option:

     [mysqld]
     audit-log=FORCE_PLUS_PERMANENT

If it is desired to prevent the server from running without the audit
plugin, use '--audit-log' with a value of 'FORCE' or
'FORCE_PLUS_PERMANENT' to force server startup to fail if the plugin
does not initialize successfully.

*Important*:

By default, rule-based audit log filtering logs no auditable events for
any users.  This differs from legacy audit log behavior (prior to MySQL
5.7.13), which logs all auditable events for all users (see
audit-log-legacy-filtering).  Should you wish to produce
log-everything behavior with rule-based filtering, create a simple
filter to enable logging and assign it to the default account:

     SELECT audit_log_filter_set_filter('log_all', '{ "filter": { "log": true } }');
     SELECT audit_log_filter_set_user('%', 'log_all');

The filter assigned to '%' is used for connections from any account that
has no explicitly assigned filter (which initially is true for all
accounts).

Once installed as just described, MySQL Enterprise Audit remains
installed until uninstalled.  To remove it, execute the following
statements:

     DROP TABLE IF EXISTS mysql.audit_log_filter;
     DROP TABLE IF EXISTS mysql.audit_log_user;
     UNINSTALL PLUGIN audit_log;
     DROP FUNCTION audit_log_filter_set_filter;
     DROP FUNCTION audit_log_filter_remove_filter;
     DROP FUNCTION audit_log_filter_set_user;
     DROP FUNCTION audit_log_filter_remove_user;
     DROP FUNCTION audit_log_filter_flush;
     DROP FUNCTION audit_log_encryption_password_get;
     DROP FUNCTION audit_log_encryption_password_set;
     DROP FUNCTION audit_log_read;
     DROP FUNCTION audit_log_read_bookmark;

6.5.5.3 MySQL Enterprise Audit Security Considerations
......................................................

By default, contents of audit log files produced by the audit log plugin
are not encrypted and may contain sensitive information, such as the
text of SQL statements.  For security reasons, audit log files should be
written to a directory accessible only to the MySQL server and to users
with a legitimate reason to view the log.  The default file name is
'audit.log' in the data directory.  This can be changed by setting the
'audit_log_file' system variable at server startup.  Other audit log
files may exist due to log rotation.

For additional security, enable audit log file encryption.  See
audit-log-file-encryption.

6.5.5.4 Audit Log File Formats
..............................

The MySQL server calls the audit log plugin to write an audit record to
its log file whenever an auditable event occurs.  Typically the first
audit record written after plugin startup contains the server
description and startup options.  Elements following that one represent
events such as client connect and disconnect events, executed SQL
statements, and so forth.  Only top-level statements are logged, not
statements within stored programs such as triggers or stored procedures.
Contents of files referenced by statements such as 'LOAD DATA INFILE'
are not logged.

To select the logging format that the audit log plugin uses to write its
log file, set the 'audit_log_format' system variable at server startup.
These formats are available:

   * Old-style XML format ('audit_log_format=OLD'): The original audit
     logging format used by default in older MySQL series.

   * New-style XML format ('audit_log_format=NEW'): An XML format that
     has better compatibility with Oracle Audit Vault than old-style XML
     format.  MySQL 5.7 uses new-style XML format by default.

   * JSON format ('audit_log_format=JSON')

By default, audit log file contents are written in new-style XML format,
without compression or encryption.

*Note*:

For information about issues to consider when changing the log format,
see audit-log-file-format.

The following sections describe the available audit logging formats:

   * audit-log-file-old-style-xml-format

   * audit-log-file-new-style-xml-format

   * audit-log-file-json-format

*Old-Style XML Audit Log File Format*

Here is a sample log file in old-style XML format
('audit_log_format=OLD'), reformatted slightly for readability:

     <?xml version="1.0" encoding="utf-8"?>
     <AUDIT>
       <AUDIT_RECORD
         TIMESTAMP="2017-10-16T14:25:00 UTC"
         RECORD_ID="1_2017-10-16T14:25:00"
         NAME="Audit"
         SERVER_ID="1"
         VERSION="1"
         STARTUP_OPTIONS="--port=3306"
         OS_VERSION="i686-Linux"
         MYSQL_VERSION="5.7.21-log"/>
       <AUDIT_RECORD
         TIMESTAMP="2017-10-16T14:25:24 UTC"
         RECORD_ID="2_2017-10-16T14:25:00"
         NAME="Connect"
         CONNECTION_ID="4"
         STATUS="0"
         STATUS_CODE="0"
         USER="root"
         OS_LOGIN=""
         HOST="localhost"
         IP="127.0.0.1"
         COMMAND_CLASS="connect"
         CONNECTION_TYPE="SSL/TLS"
         PRIV_USER="root"
         PROXY_USER=""
         DB="test"/>

     ...

       <AUDIT_RECORD
         TIMESTAMP="2017-10-16T14:25:24 UTC"
         RECORD_ID="6_2017-10-16T14:25:00"
         NAME="Query"
         CONNECTION_ID="4"
         STATUS="0"
         STATUS_CODE="0"
         USER="root[root] @ localhost [127.0.0.1]"
         OS_LOGIN=""
         HOST="localhost"
         IP="127.0.0.1"
         COMMAND_CLASS="drop_table"
         SQLTEXT="DROP TABLE IF EXISTS t"/>

     ...

       <AUDIT_RECORD
         TIMESTAMP="2017-10-16T14:25:24 UTC"
         RECORD_ID="8_2017-10-16T14:25:00"
         NAME="Quit"
         CONNECTION_ID="4"
         STATUS="0"
         STATUS_CODE="0"
         USER="root"
         OS_LOGIN=""
         HOST="localhost"
         IP="127.0.0.1"
         COMMAND_CLASS="connect"
         CONNECTION_TYPE="SSL/TLS"/>
       <AUDIT_RECORD
         TIMESTAMP="2017-10-16T14:25:32 UTC"
         RECORD_ID="12_2017-10-16T14:25:00"
         NAME="NoAudit"
         SERVER_ID="1"/>
     </AUDIT>

The audit log file is written as XML, using UTF-8 (up to 4 bytes per
character).  The root element is '<AUDIT>'.  The root element contains
'<AUDIT_RECORD>' elements, each of which provides information about an
audited event.  When the audit log plugin begins writing a new log file,
it writes the XML declaration and opening '<AUDIT>' root element tag.
When the plugin closes a log file, it writes the closing '</AUDIT>' root
element tag.  The closing tag is not present while the file is open.

Attributes of '<AUDIT_RECORD>' elements have these characteristics:

   * Some attributes appear in every '<AUDIT_RECORD>' element.  Others
     are optional and may appear depending on the audit record type.

   * Order of attributes within an '<AUDIT_RECORD>' element is not
     guaranteed.

   * Attribute values are not fixed length.  Long values may be
     truncated as indicated in the attribute descriptions given later.

   * The '<', '>', '"', and '&' characters are encoded as '&lt;',
     '&gt;', '&quot;', and '&amp;', respectively.  NUL bytes (U+00) are
     encoded as the '?' character.

   * Characters not valid as XML characters are encoded using numeric
     character references.  Valid XML characters are:

          #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

The following attributes are mandatory in every '<AUDIT_RECORD>'
element:

   * 'NAME'

     A string representing the type of instruction that generated the
     audit event, such as a command that the server received from a
     client.

     Example: 'NAME="Query"'

     Some common 'NAME' values:

          Audit    When auditing starts, which may be server startup time
          Connect  When a client connects, also known as logging in
          Query    An SQL statement (executed directly)
          Prepare  Preparation of an SQL statement; usually followed by Execute
          Execute  Execution of an SQL statement; usually follows Prepare
          Shutdown Server shutdown
          Quit     When a client disconnects
          NoAudit  Auditing has been turned off

     The possible values are 'Audit', 'Binlog Dump', 'Change user',
     'Close stmt', 'Connect Out', 'Connect', 'Create DB', 'Daemon',
     'Debug', 'Delayed insert', 'Drop DB', 'Execute', 'Fetch', 'Field
     List', 'Init DB', 'Kill', 'Long Data', 'NoAudit', 'Ping',
     'Prepare', 'Processlist', 'Query', 'Quit', 'Refresh', 'Register
     Slave', 'Reset stmt', 'Set option', 'Shutdown', 'Sleep',
     'Statistics', 'Table Dump', 'Time'.

     With the exception of '"Audit"' and '"NoAudit"', these values
     correspond to the 'COM_XXX' command values listed in the
     'my_command.h' header file.  For example, '"Create DB"' and
     '"Change user"' correspond to 'COM_CREATE_DB' and
     'COM_CHANGE_USER', respectively.

   * 'RECORD_ID'

     A unique identifier for the audit record.  The value is composed
     from a sequence number and timestamp, in the format
     'SEQ_TIMESTAMP'.  When the audit log plugin opens the audit log
     file, it initializes the sequence number to the size of the audit
     log file, then increments the sequence by 1 for each record logged.
     The timestamp is a UTC value in 'YYYY-MM-DDTHH:MM:SS' format
     indicating the date and time when the audit log plugin opened the
     file.

     Example: 'RECORD_ID="12_2017-10-16T14:25:00"'

   * 'TIMESTAMP'

     A string representing a UTC value in 'YYYY-MM-DDTHH:MM:SS UTC'
     format indicating the date and time when the audit event was
     generated.  For example, the event corresponding to execution of an
     SQL statement received from a client has a 'TIMESTAMP' value
     occurring after the statement finishes, not when it was received.

     Example: 'TIMESTAMP="2017-10-16T14:25:32 UTC"'

The following attributes are optional in '<AUDIT_RECORD>' elements.
Many of them occur only for elements with specific values of the 'NAME'
attribute.

   * 'COMMAND_CLASS'

     A string that indicates the type of action performed.

     Example: 'COMMAND_CLASS="drop_table"'

     The values correspond to the 'statement/sql/XXX' command counters;
     for example, XXX is 'drop_table' and 'select' for 'DROP TABLE'
     and 'SELECT' statements,
     respectively.  The following statement displays the possible names:

          SELECT REPLACE(EVENT_NAME, 'statement/sql/', '') AS name
          FROM performance_schema.events_statements_summary_global_by_event_name
          WHERE EVENT_NAME LIKE 'statement/sql/%'
          ORDER BY name;

   * 'CONNECTION_ID'

     An unsigned integer representing the client connection identifier.
     This is the same as the value returned by the 'CONNECTION_ID()'
     function within the session.

     Example: 'CONNECTION_ID="127"'

   * 'CONNECTION_TYPE'

     The security state of the connection to the server.  Permitted
     values are 'TCP/IP' (TCP/IP connection established without
     encryption), 'SSL/TLS' (TCP/IP connection established with
     encryption), 'Socket' (Unix socket file connection), 'Named Pipe'
     (Windows named pipe connection), and 'Shared Memory' (Windows
     shared memory connection).

     Example: 'CONNECTION_TYPE="SSL/TLS"'

   * 'DB'

     A string representing the default database name.

     Example: 'DB="test"'

   * 'HOST'

     A string representing the client host name.

     Example: 'HOST="localhost"'

   * 'IP'

     A string representing the client IP address.

     Example: 'IP="127.0.0.1"'

   * 'MYSQL_VERSION'

     A string representing the MySQL server version.  This is the same
     as the value of the 'VERSION()' function or 'version' system
     variable.

     Example: 'MYSQL_VERSION="5.7.21-log"'

   * 'OS_LOGIN'

     A string representing the external user name used during the
     authentication process, as set by the plugin used to authenticate
     the client.  With native (built-in) MySQL authentication, or if the
     plugin does not set the value, this attribute is empty.  The value
     is the same as that of the 'external_user' system variable (see
     proxy-users).

     Example: 'OS_LOGIN="jeffrey"'

   * 'OS_VERSION'

     A string representing the operating system on which the server was
     built or is running.

     Example: 'OS_VERSION="x86_64-Linux"'

   * 'PRIV_USER'

     A string representing the user that the server authenticated the
     client as.  This is the user name that the server uses for
     privilege checking, and it may differ from the 'USER' value.

     Example: 'PRIV_USER="jeffrey"'

   * 'PROXY_USER'

     A string representing the proxy user (see proxy-users).
     The value is empty if user proxying is not in effect.

     Example: 'PROXY_USER="developer"'

   * 'SERVER_ID'

     An unsigned integer representing the server ID. This is the same as
     the value of the 'server_id' system variable.

     Example: 'SERVER_ID="1"'

   * 'SQLTEXT'

     A string representing the text of an SQL statement.  The value can
     be empty.  Long values may be truncated.  The string, like the
     audit log file itself, is written using UTF-8 (up to 4 bytes per
     character), so the value may be the result of conversion.  For
     example, the original statement might have been received from the
     client as an SJIS string.

     Example: 'SQLTEXT="DELETE FROM t1"'

   * 'STARTUP_OPTIONS'

     A string representing the options that were given on the command
     line or in option files when the MySQL server was started.

     Example: 'STARTUP_OPTIONS="--port=3306 --log-output=FILE"'

   * 'STATUS'

     An unsigned integer representing the command status: 0 for success,
     nonzero if an error occurred.  This is the same as the value of the
     'mysql_errno()'. C API function.  See the
     description for 'STATUS_CODE' for information about how it differs
     from 'STATUS'.

     The audit log does not contain the SQLSTATE value or error message.
     To see the associations between error codes, SQLSTATE values, and
     messages, see error-messages-server.

     Warnings are not logged.

     Example: 'STATUS="1051"'

   * 'STATUS_CODE'

     An unsigned integer representing the command status: 0 for success,
     1 if an error occurred.

     The 'STATUS_CODE' value differs from the 'STATUS' value:
     'STATUS_CODE' is 0 for success and 1 for error, which is compatible
     with the EZ_collector consumer for Audit Vault.  'STATUS' is the
     value of the 'mysql_errno()'. C API function.
     This is 0 for success and nonzero for error, and thus is not
     necessarily 1 for error.

     Example: 'STATUS_CODE="0"'

   * 'USER'

     A string representing the user name sent by the client.  This may
     differ from the 'PRIV_USER' value.

   * 'VERSION'

     An unsigned integer representing the version of the audit log file
     format.

     Example: 'VERSION="1"'

*New-Style XML Audit Log File Format*

Here is a sample log file in new-style XML format
('audit_log_format=NEW'), reformatted slightly for readability:

     <?xml version="1.0" encoding="utf-8"?>
     <AUDIT>
      <AUDIT_RECORD>
       <TIMESTAMP>2017-10-16T14:06:33 UTC</TIMESTAMP>
       <RECORD_ID>1_2017-10-16T14:06:33</RECORD_ID>
       <NAME>Audit</NAME>
       <SERVER_ID>1</SERVER_ID>
       <VERSION>1</VERSION>
       <STARTUP_OPTIONS>/usr/local/mysql/bin/mysqld
         --socket=/usr/local/mysql/mysql.sock
         --port=3306</STARTUP_OPTIONS>
       <OS_VERSION>i686-Linux</OS_VERSION>
       <MYSQL_VERSION>5.7.21-log</MYSQL_VERSION>
      </AUDIT_RECORD>
      <AUDIT_RECORD>
       <TIMESTAMP>2017-10-16T14:09:38 UTC</TIMESTAMP>
       <RECORD_ID>2_2017-10-16T14:06:33</RECORD_ID>
       <NAME>Connect</NAME>
       <CONNECTION_ID>5</CONNECTION_ID>
       <STATUS>0</STATUS>
       <STATUS_CODE>0</STATUS_CODE>
       <USER>root</USER>
       <OS_LOGIN/>
       <HOST>localhost</HOST>
       <IP>127.0.0.1</IP>
       <COMMAND_CLASS>connect</COMMAND_CLASS>
       <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>
       <PRIV_USER>root</PRIV_USER>
       <PROXY_USER/>
       <DB>test</DB>
      </AUDIT_RECORD>

     ...

      <AUDIT_RECORD>
       <TIMESTAMP>2017-10-16T14:09:38 UTC</TIMESTAMP>
       <RECORD_ID>6_2017-10-16T14:06:33</RECORD_ID>
       <NAME>Query</NAME>
       <CONNECTION_ID>5</CONNECTION_ID>
       <STATUS>0</STATUS>
       <STATUS_CODE>0</STATUS_CODE>
       <USER>root[root] @ localhost [127.0.0.1]</USER>
       <OS_LOGIN/>
       <HOST>localhost</HOST>
       <IP>127.0.0.1</IP>
       <COMMAND_CLASS>drop_table</COMMAND_CLASS>
       <SQLTEXT>DROP TABLE IF EXISTS t</SQLTEXT>
      </AUDIT_RECORD>

     ...

      <AUDIT_RECORD>
       <TIMESTAMP>2017-10-16T14:09:39 UTC</TIMESTAMP>
       <RECORD_ID>8_2017-10-16T14:06:33</RECORD_ID>
       <NAME>Quit</NAME>
       <CONNECTION_ID>5</CONNECTION_ID>
       <STATUS>0</STATUS>
       <STATUS_CODE>0</STATUS_CODE>
       <USER>root</USER>
       <OS_LOGIN/>
       <HOST>localhost</HOST>
       <IP>127.0.0.1</IP>
       <COMMAND_CLASS>connect</COMMAND_CLASS>
       <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>
      </AUDIT_RECORD>

     ...

      <AUDIT_RECORD>
       <TIMESTAMP>2017-10-16T14:09:43 UTC</TIMESTAMP>
       <RECORD_ID>11_2017-10-16T14:06:33</RECORD_ID>
       <NAME>Quit</NAME>
       <CONNECTION_ID>6</CONNECTION_ID>
       <STATUS>0</STATUS>
       <STATUS_CODE>0</STATUS_CODE>
       <USER>root</USER>
       <OS_LOGIN/>
       <HOST>localhost</HOST>
       <IP>127.0.0.1</IP>
       <COMMAND_CLASS>connect</COMMAND_CLASS>
       <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>
      </AUDIT_RECORD>
      <AUDIT_RECORD>
       <TIMESTAMP>2017-10-16T14:09:45 UTC</TIMESTAMP>
       <RECORD_ID>12_2017-10-16T14:06:33</RECORD_ID>
       <NAME>NoAudit</NAME>
       <SERVER_ID>1</SERVER_ID>
      </AUDIT_RECORD>
     </AUDIT>

The audit log file is written as XML, using UTF-8 (up to 4 bytes per
character).  The root element is '<AUDIT>'.  The root element contains
'<AUDIT_RECORD>' elements, each of which provides information about an
audited event.  When the audit log plugin begins writing a new log file,
it writes the XML declaration and opening '<AUDIT>' root element tag.
When the plugin closes a log file, it writes the closing '</AUDIT>' root
element tag.  The closing tag is not present while the file is open.

Elements within '<AUDIT_RECORD>' elements have these characteristics:

   * Some elements appear in every '<AUDIT_RECORD>' element.  Others are
     optional and may appear depending on the audit record type.

   * Order of elements within an '<AUDIT_RECORD>' element is not
     guaranteed.

   * Element values are not fixed length.  Long values may be truncated
     as indicated in the element descriptions given later.

   * The '<', '>', '"', and '&' characters are encoded as '&lt;',
     '&gt;', '&quot;', and '&amp;', respectively.  NUL bytes (U+00) are
     encoded as the '?' character.

   * Characters not valid as XML characters are encoded using numeric
     character references.  Valid XML characters are:

          #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

The following elements are mandatory in every '<AUDIT_RECORD>' element:

   * '<NAME>'

     A string representing the type of instruction that generated the
     audit event, such as a command that the server received from a
     client.

     Example:

          <NAME>Query</NAME>

     Some common '<NAME>' values:

          Audit    When auditing starts, which may be server startup time
          Connect  When a client connects, also known as logging in
          Query    An SQL statement (executed directly)
          Prepare  Preparation of an SQL statement; usually followed by Execute
          Execute  Execution of an SQL statement; usually follows Prepare
          Shutdown Server shutdown
          Quit     When a client disconnects
          NoAudit  Auditing has been turned off

     The possible values are 'Audit', 'Binlog Dump', 'Change user',
     'Close stmt', 'Connect Out', 'Connect', 'Create DB', 'Daemon',
     'Debug', 'Delayed insert', 'Drop DB', 'Execute', 'Fetch', 'Field
     List', 'Init DB', 'Kill', 'Long Data', 'NoAudit', 'Ping',
     'Prepare', 'Processlist', 'Query', 'Quit', 'Refresh', 'Register
     Slave', 'Reset stmt', 'Set option', 'Shutdown', 'Sleep',
     'Statistics', 'Table Dump', 'Time'.

     With the exception of 'Audit' and 'NoAudit', these values
     correspond to the 'COM_XXX' command values listed in the
     'my_command.h' header file.  For example, 'Create DB' and 'Change
     user' correspond to 'COM_CREATE_DB' and 'COM_CHANGE_USER',
     respectively.

   * '<RECORD_ID>'

     A unique identifier for the audit record.  The value is composed
     from a sequence number and timestamp, in the format
     'SEQ_TIMESTAMP'.  When the audit log plugin opens the audit log
     file, it initializes the sequence number to the size of the audit
     log file, then increments the sequence by 1 for each record logged.
     The timestamp is a UTC value in 'YYYY-MM-DDTHH:MM:SS' format
     indicating the date and time when the audit log plugin opened the
     file.

     Example:

          <RECORD_ID>12_2017-10-16T14:06:33</RECORD_ID>

   * '<TIMESTAMP>'

     A string representing a UTC value in 'YYYY-MM-DDTHH:MM:SS UTC'
     format indicating the date and time when the audit event was
     generated.  For example, the event corresponding to execution of an
     SQL statement received from a client has a '<TIMESTAMP>' value
     occurring after the statement finishes, not when it was received.

     Example:

          <TIMESTAMP>2017-10-16T14:09:45 UTC</TIMESTAMP>

The following elements are optional in '<AUDIT_RECORD>' elements.  Many
of them occur only with specific '<NAME>' element values.

   * '<COMMAND_CLASS>'

     A string that indicates the type of action performed.

     Example:

          <COMMAND_CLASS>drop_table</COMMAND_CLASS>

     The values correspond to the 'statement/sql/XXX' command counters;
     for example, XXX is 'drop_table' and 'select' for 'DROP TABLE'
     and 'SELECT' statements,
     respectively.  The following statement displays the possible names:

          SELECT REPLACE(EVENT_NAME, 'statement/sql/', '') AS name
          FROM performance_schema.events_statements_summary_global_by_event_name
          WHERE EVENT_NAME LIKE 'statement/sql/%'
          ORDER BY name;

   * '<CONNECTION_ID>'

     An unsigned integer representing the client connection identifier.
     This is the same as the value returned by the 'CONNECTION_ID()'
     function within the session.

     Example:

          <CONNECTION_ID>127</CONNECTION_ID>

   * '<CONNECTION_TYPE>'

     The security state of the connection to the server.  Permitted
     values are 'TCP/IP' (TCP/IP connection established without
     encryption), 'SSL/TLS' (TCP/IP connection established with
     encryption), 'Socket' (Unix socket file connection), 'Named Pipe'
     (Windows named pipe connection), and 'Shared Memory' (Windows
     shared memory connection).

     Example:

          <CONNECTION_TYPE>SSL/TLS</CONNECTION_TYPE>

   * '<DB>'

     A string representing the default database name.

     Example:

          <DB>test</DB>

   * '<HOST>'

     A string representing the client host name.

     Example:

          <HOST>localhost</HOST>

   * '<IP>'

     A string representing the client IP address.

     Example:

          <IP>127.0.0.1</IP>

   * '<MYSQL_VERSION>'

     A string representing the MySQL server version.  This is the same
     as the value of the 'VERSION()' function or 'version' system
     variable.

     Example:

          <MYSQL_VERSION>5.7.21-log</MYSQL_VERSION>

   * '<OS_LOGIN>'

     A string representing the external user name used during the
     authentication process, as set by the plugin used to authenticate
     the client.  With native (built-in) MySQL authentication, or if the
     plugin does not set the value, this element is empty.  The value is
     the same as that of the 'external_user' system variable (see
     proxy-users).

     Example:

          <OS_LOGIN>jeffrey</OS_LOGIN>

   * '<OS_VERSION>'

     A string representing the operating system on which the server was
     built or is running.

     Example:

          <OS_VERSION>x86_64-Linux</OS_VERSION>

   * '<PRIV_USER>'

     A string representing the user that the server authenticated the
     client as.  This is the user name that the server uses for
     privilege checking, and may differ from the '<USER>' value.

     Example:

          <PRIV_USER>jeffrey</PRIV_USER>

   * '<PROXY_USER>'

     A string representing the proxy user (see proxy-users).
     The value is empty if user proxying is not in effect.

     Example:

          <PROXY_USER>developer</PROXY_USER>

   * '<SERVER_ID>'

     An unsigned integer representing the server ID. This is the same as
     the value of the 'server_id' system variable.

     Example:

          <SERVER_ID>1</SERVER_ID>

   * '<SQLTEXT>'

     A string representing the text of an SQL statement.  The value can
     be empty.  Long values may be truncated.  The string, like the
     audit log file itself, is written using UTF-8 (up to 4 bytes per
     character), so the value may be the result of conversion.  For
     example, the original statement might have been received from the
     client as an SJIS string.

     Example:

          <SQLTEXT>DELETE FROM t1</SQLTEXT>

   * '<STARTUP_OPTIONS>'

     A string representing the options that were given on the command
     line or in option files when the MySQL server was started.  The
     first option is the path to the server executable.

     Example:

          <STARTUP_OPTIONS>/usr/local/mysql/bin/mysqld
            --port=3306 --log-output=FILE</STARTUP_OPTIONS>

   * '<STATUS>'

     An unsigned integer representing the command status: 0 for success,
     nonzero if an error occurred.  This is the same as the value of the
     'mysql_errno()'. C API function.  See the
     description for '<STATUS_CODE>' for information about how it
     differs from '<STATUS>'.

     The audit log does not contain the SQLSTATE value or error message.
     To see the associations between error codes, SQLSTATE values, and
     messages, see error-messages-server.

     Warnings are not logged.

     Example:

          <STATUS>1051</STATUS>

   * '<STATUS_CODE>'

     An unsigned integer representing the command status: 0 for success,
     1 if an error occurred.

     The 'STATUS_CODE' value differs from the 'STATUS' value:
     'STATUS_CODE' is 0 for success and 1 for error, which is compatible
     with the EZ_collector consumer for Audit Vault.  'STATUS' is the
     value of the 'mysql_errno()'. C API function.
     This is 0 for success and nonzero for error, and thus is not
     necessarily 1 for error.

     Example:

          <STATUS_CODE>0</STATUS_CODE>

   * '<USER>'

     A string representing the user name sent by the client.  This may
     differ from the '<PRIV_USER>' value.

     Example:

          <USER>root[root] @ localhost [127.0.0.1]</USER>

   * '<VERSION>'

     An unsigned integer representing the version of the audit log file
     format.

     Example:

          <VERSION>1</VERSION>

*JSON Audit Log File Format*

For JSON-format audit logging ('audit_log_format=JSON'), the log file
contents form a 'JSON' array with each array element
representing an audited event as a 'JSON' hash of key/value
pairs.  Examples of complete event records appear later in this section.
The following is an excerpt of partial events:

     [
       {
         "timestamp": "2018-01-15 13:50:01",
         "id": 0,
         "class": "audit",
         "event": "startup",
         ...
       },
       {
         "timestamp": "2018-01-15 15:02:32",
         "id": 0,
         "class": "connection",
         "event": "connect",
         ...
       },
       ...
       {
         "timestamp": "2018-01-15 17:37:26",
         "id": 0,
         "class": "table_access",
         "event": "insert",
           ...
       }
       ...
     ]

The audit log file is written using UTF-8 (up to 4 bytes per character).
When the audit log plugin begins writing a new log file, it writes the
opening '[' array marker.  When the plugin closes a log file, it writes
the closing ']' array marker.  The closing marker is not present while
the file is open.

Items within audit records have these characteristics:

   * Some items appear in every audit record.  Others are optional and
     may appear depending on the audit record type.

   * Order of items within an audit record is not guaranteed.

   * Item values are not fixed length.  Long values may be truncated as
     indicated in the item descriptions given later.

   * The '"' and '\' characters are encoded as '\"' and '\\',
     respectively.

The following examples show the JSON object formats for different event
types (as indicated by the 'class' and 'event' items), reformatted
slightly for readability:

Auditing startup event:

     { "timestamp": "2018-01-15 14:21:56",
       "id": 0,
       "class": "audit",
       "event": "startup",
       "connection_id": 0,
       "startup_data": { "server_id": 1,
                         "os_version": "i686-Linux",
                         "mysql_version": "5.7.21-log",
                         "args": ["/usr/local/mysql/bin/mysqld",
                                  "--loose-audit-log-format=JSON",
                                  "--log-error=log.err",
                                  "--pid-file=mysqld.pid",
                                  "--port=3306" ] } }

When the audit log plugin starts as a result of server startup (as
opposed to being enabled at runtime), 'connection_id' is set to 0, and
'account' and 'login' are not present.

Auditing shutdown event:

     { "timestamp": "2018-01-15 14:28:20",
       "id": 3,
       "class": "audit",
       "event": "shutdown",
       "connection_id": 0,
       "shutdown_data": { "server_id": 1 } }

When the audit log plugin is uninstalled as a result of server shutdown
(as opposed to being disabled at runtime), 'connection_id' is set to 0,
and 'account' and 'login' are not present.

Connect or change-user event:

     { "timestamp": "2018-01-15 14:23:18",
       "id": 1,
       "class": "connection",
       "event": "connect",
       "connection_id": 5,
       "account": { "user": "root", "host": "localhost" },
       "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" },
       "connection_data": { "connection_type": "ssl",
                            "status": 0,
                            "db": "test" } }

Disconnect event:

     { "timestamp": "2018-01-15 14:24:45",
       "id": 3,
       "class": "connection",
       "event": "disconnect",
       "connection_id": 5,
       "account": { "user": "root", "host": "localhost" },
       "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" },
       "connection_data": { "connection_type": "ssl" } }

Query event:

     { "timestamp": "2018-01-15 14:23:35",
       "id": 2,
       "class": "general",
       "event": "status",
       "connection_id": 5,
       "account": { "user": "root", "host": "localhost" },
       "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" },
       "general_data": { "command": "Query",
                         "sql_command": "show_variables",
                         "query": "SHOW VARIABLES",
                         "status": 0 } }

Table access event (read, delete, insert, update):

     { "timestamp": "2018-01-15 14:23:41",
       "id": 0,
       "class": "table_access",
       "event": "insert",
       "connection_id": 5,
       "account": { "user": "root", "host": "localhost" },
       "login": { "user": "root", "os": "", "ip": "127.0.0.1", "proxy": "" },
       "table_access_data": { "db": "test",
                              "table": "t1",
                              "query": "INSERT INTO t1 (i) VALUES(1),(2),(3)",
                              "sql_command": "insert" } }

The items in the following list appear at the top level of JSON-format
audit records: Each item value is either a scalar or a 'JSON'
hash.  For items that have a hash value, the description lists
only the item names within that hash.  For more complete descriptions of
second-level hash items, see later in this section.

   * 'account'

     The MySQL account associated with the event.  The value is a hash
     containing these items equivalent to the value of the
     'CURRENT_USER()' function within the section: 'user', 'host'.

     Example:

          "account": { "user": "root", "host": "localhost" }

   * 'class'

     A string representing the event class.  The class defines the type
     of event, when taken together with the 'event' item that specifies
     the event subclass.

     Example:

          "class": "connection"

     The following table shows the permitted combinations of 'class' and
     'event' values.

     *Audit Log Class and Event Combinations*

     Class Value            Permitted Event Values

     'audit'

     'startup',
     'shutdown'

     'connection'

     'connect',
     'change_user',
     'disconnect'

     'general'

     'status'

     'table_access_data'

     'read', 'delete',
     'insert', 'update'

   * 'connection_data'

     Information about a client connection.  The value is a hash
     containing these items: 'connection_type', 'status', 'db'.  This
     item occurs only for audit records with a 'class' value of
     'connection'.

     Example:

          "connection_data": { "connection_type": "ssl",
                               "status": 0,
                               "db": "test" }

   * 'connection_id'

     An unsigned integer representing the client connection identifier.
     This is the same as the value returned by the 'CONNECTION_ID()'
     function within the session.

     Example:

          "connection_id": 5

   * 'event'

     A string representing the subclass of the event class.  The
     subclass defines the type of event, when taken together with the
     'class' item that specifies the event class.  For more information,
     see the 'class' item description.

     Example:

          "event": "connect"

   * 'general_data'

     Information about an executed statement or command.  The value is a
     hash containing these items: 'command', 'sql_command', 'query',
     'status'.  This item occurs only for audit records with a 'class'
     value of 'general'.

     Example:

          "general_data": { "command": "Query",
                            "sql_command": "show_variables",
                            "query": "SHOW VARIABLES",
                            "status": 0 }

   * 'id'

     An unsigned integer representing an event ID.

     Example:

          "id": 2

     For audit records that have the same 'timestamp' value, their 'id'
     values distinguish them and form a sequence.  Within the audit log,
     'timestamp'/'id' pairs are unique.  These pairs are bookmarks that
     identify event locations within the log.

   * 'login'

     Information indicating how a client connected to the server.  The
     value is a hash containing these items: 'user', 'os', 'ip',
     'proxy'.

     Example:

          "login": { "user": "root", "os": "", "ip": "::1", "proxy": "" }

   * 'shutdown_data'

     Information pertaining to audit log plugin termination.  The value
     is a hash containing these items: 'server_id' This item occurs only
     for audit records with 'class' and 'event' values of 'audit' and
     'shutdown', respectively.

     Example:

          "shutdown_data": { "server_id": 1 }

   * 'startup_data'

     Information pertaining to audit log plugin initialization.  The
     value is a hash containing these items: 'server_id', 'os_version',
     'mysql_version', 'args'.  This item occurs only for audit records
     with 'class' and 'event' values of 'audit' and 'startup',
     respectively.

     Example:

          "startup_data": { "server_id": 1,
                            "os_version": "i686-Linux",
                            "mysql_version": "5.7.21-log",
                            "args": ["/usr/local/mysql/bin/mysqld",
                                     "--loose-audit-log-format=JSON",
                                     "--log-error=log.err",
                                     "--pid-file=mysqld.pid",
                                     "--port=3306" ] }

   * 'table_access_data'

     Information about an access to a table.  The value is a hash
     containing these items: 'db', 'table', 'query', 'sql_command', This
     item occurs only for audit records with a 'class' value of
     'table_access'.

     Example:

          "table_access_data": { "db": "test",
                                 "table": "t1",
                                 "query": "INSERT INTO t1 (i) VALUES(1),(2),(3)",
                                 "sql_command": "insert" }

   * 'timestamp'

     A string representing a UTC value in YYYY-MM-DD HH:MM:SS format
     indicating the date and time when the audit event was generated.
     For example, the event corresponding to execution of an SQL
     statement received from a client has a 'timestamp' value occurring
     after the statement finishes, not when it was received.

     Example:

          "timestamp": "2018-01-15 13:50:01"

     For audit records that have the same 'timestamp' value, their 'id'
     values distinguish them and form a sequence.  Within the audit log,
     'timestamp'/'id' pairs are unique.  These pairs are bookmarks that
     identify event locations within the log.

These items appear within hash values associated with top-level items of
JSON-format audit records:

   * 'args'

     An array of options that were given on the command line or in
     option files when the MySQL server was started.  The first option
     is the path to the server executable.

     Example:

          "args": ["/usr/local/mysql/bin/mysqld",
                   "--loose-audit-log-format=JSON",
                   "--log-error=log.err",
                   "--pid-file=mysqld.pid",
                   "--port=3306" ]

   * 'command'

     A string representing the type of instruction that generated the
     audit event, such as a command that the server received from a
     client.

     Example:

          "command": "Query"

   * 'connection_type'

     The security state of the connection to the server.  Permitted
     values are 'tcp/ip' (TCP/IP connection established without
     encryption), 'ssl' (TCP/IP connection established with encryption),
     'socket' (Unix socket file connection), 'named_pipe' (Windows named
     pipe connection), and 'shared_memory' (Windows shared memory
     connection).

     Example:

          "connection_type": "tcp/tcp"

   * 'db'

     A string representing a database name.  For 'connection_data', it
     is the default database.  For 'table_access_data', it is the table
     database.

     Example:

          "db": "test"

   * 'host'

     A string representing the client host name.

     Example:

          "host": "localhost"

   * 'ip'

     A string representing the client IP address.

     Example:

          "ip": "::1"

   * 'mysql_version'

     A string representing the MySQL server version.  This is the same
     as the value of the 'VERSION()' function or 'version' system
     variable.

     Example:

          "mysql_version": "5.7.21-log"

   * 'os'

     A string representing the external user name used during the
     authentication process, as set by the plugin used to authenticate
     the client.  With native (built-in) MySQL authentication, or if the
     plugin does not set the value, this attribute is empty.  The value
     is the same as that of the 'external_user' system variable.  See
     proxy-users.

     Example:

          "os": "jeffrey"

   * 'os_version'

     A string representing the operating system on which the server was
     built or is running.

     Example:

          "os_version": "i686-Linux"

   * 'proxy'

     A string representing the proxy user (see proxy-users).
     The value is empty if user proxying is not in effect.

     Example:

          "proxy": "developer"

   * 'query'

     A string representing the text of an SQL statement.  The value can
     be empty.  Long values may be truncated.  The string, like the
     audit log file itself, is written using UTF-8 (up to 4 bytes per
     character), so the value may be the result of conversion.  For
     example, the original statement might have been received from the
     client as an SJIS string.

     Example:

          "query": "DELETE FROM t1"

   * 'server_id'

     An unsigned integer representing the server ID. This is the same as
     the value of the 'server_id' system variable.

     Example:

          "server_id": 1

   * 'sql_command'

     A string that indicates the SQL statement type.

     Example:

          "sql_command": "insert"

     The values correspond to the 'statement/sql/XXX' command counters;
     for example, XXX is 'drop_table' and 'select' for 'DROP TABLE'
     and 'SELECT' statements,
     respectively.  The following statement displays the possible names:

          SELECT REPLACE(EVENT_NAME, 'statement/sql/', '') AS name
          FROM performance_schema.events_statements_summary_global_by_event_name
          WHERE EVENT_NAME LIKE 'statement/sql/%'
          ORDER BY name;

   * 'status'

     An unsigned integer representing the command status: 0 for success,
     nonzero if an error occurred.  This is the same as the value of the
     'mysql_errno()'. C API function.

     The audit log does not contain the SQLSTATE value or error message.
     To see the associations between error codes, SQLSTATE values, and
     messages, see error-messages-server.

     Warnings are not logged.

     Example:

          "status": 1051

   * 'table'

     A string representing a table name.

     Example:

          "table": "t1"

   * 'user'

     A string representing a user name.  The meaning differs depending
     on the item within which 'user' occurs:

        * Within 'account' items, 'user' is a string representing the
          user that the server authenticated the client as.  This is the
          user name that the server uses for privilege checking.

        * Within 'login' items, 'user' is a string representing the user
          name sent by the client.

     Example:

          "user": "root"

6.5.5.5 Audit Log Logging Control
.................................

This section describes how to control general characteristics of audit
logging, such as the file to which the audit log plugin writes events,
the format of written events, and whether compression and encryption are
enabled.

   * audit-log-file-name

   * audit-log-file-format

   * audit-log-file-compression

   * audit-log-file-encryption

   * audit-log-file-uncompression-decryption

   * audit-log-strategy

   * audit-log-space-management

   * audit-log-file-reading

For additional information about the user-defined functions and system
variables that affect audit logging, see audit-log-routines, and
audit-log-options-variables.

The audit log plugin can also control which audited events are written
to the audit log file, based on the account from which events originate
or event content.  See audit-log-filtering.

*Audit Log File Name*

To control the audit log file name, set the 'audit_log_file' system
variable at server startup.  By default, the name is 'audit.log' in the
server data directory.  For security reasons, the audit log file should
be written to a directory accessible only to the MySQL server and to
users with a legitimate reason to view the log.

As of MySQL 5.7.21, the plugin interprets the 'audit_log_file' value as
composed of a base name and an optional suffix.  If compression or
encryption are enabled, the effective file name (the name actually used
to create the log file) differs from the configured file name because it
has additional suffixes:

   * If compression is enabled, the plugin adds a suffix of '.gz'.

   * If encryption is enabled, the plugin adds a suffix of '.enc'.

The effective audit log file name is the resulting name after adding
possible compression and encryption suffixes to the configured file
name.  For example, if the configured 'audit_log_file' value is
'audit.log', the effective file name is one of these values:

     audit.log        Not compressed or encrypted
     audit.log.gz     Compressed
     audit.log.enc    Encrypted
     audit.log.gz.enc Compressed and encrypted

Prior to MySQL 5.7.21, the configured and effective log file names are
the same.  For example, if the configured 'audit_log_file' value is
'audit.log', the audit log plugin writes to 'audit.log'.

The audit log plugin performs certain actions at initialization and
termination time based on the audit log file name:

As of MySQL 5.7.21:

   * During initialization, the plugin checks whether a file with the
     audit log file name already exists and renames it if so.  (In this
     case, the plugin assumes that the previous server invocation exited
     unexpectedly with the audit log plugin running.)  The plugin then
     writes to a new empty audit log file.

   * At termination, the plugin renames the audit log file.

   * When renaming occurs (whether at plugin initialization or
     termination), the renamed file has a timestamp inserted after its
     base name and before its suffix.  For example, if the file name is
     'audit.log', the plugin renames it to a value such as
     'audit.20180115T140633.log'.  The timestamp is a UTC value in
     'YYYYMMDDTHHMMSS' format.

Prior to MySQL 5.7.21, only the XML log formats are available and the
plugin performs rudimentary integrity checking:

   * During initialization, the plugin checks whether the file ends with
     an '</AUDIT>' tag and truncates the tag before writing any
     '<AUDIT_RECORD>' elements.  If the log file exists but does not end
     with '</AUDIT>' or the '</AUDIT>' tag cannot be truncated, the
     plugin considers the file malformed and renames it.  (Such renaming
     can occur if the server exits unexpectedly with the audit log
     plugin running.)  The plugin then writes to a new empty audit log
     file.

   * At termination, no file renaming occurs.

   * When renaming occurs at plugin initialization, the renamed file has
     '.corrupted', a timestamp, and '.xml' added to the end.  For
     example, if the file name is 'audit.log', the plugin renames it to
     a value such as 'audit.log.corrupted.15081807937726520.xml'.  The
     timestamp value is similar to a Unix timestamp, with the last 7
     digits representing the fractional second part.  For information
     about interpreting the timestamp, see
     audit-log-space-management.

*Audit Log File Format*

To control the audit log file format, set the 'audit_log_format' system
variable at server startup.  By default, the format is 'NEW' (new-style
XML format).  For details about each format, see
audit-log-file-formats.

If you change 'audit_log_format', it is recommended that you also change
'audit_log_file'.  Otherwise, there will be two sets of log files with
the same base name but different formats.

*Note*:

Prior to MySQL 5.7.21, changing the value of 'audit_log_format' can
result in writing log entries in one format to an existing log file that
contains entries in a different format.  To avoid this issue, use the
following procedure:

  1. Stop the server.

  2. Either change the value of the 'audit_log_file' system variable so
     the plugin writes to a different file, or rename the current audit
     log file manually.

  3. Restart the server with the new value of 'audit_log_format'.  The
     audit log plugin creates a new log file and writes entries to it in
     the selected format.

*Audit Log File Compression*

Audit log file compression is available as of MySQL 5.7.21.  Compression
can be enabled for any logging format.

To control whether audit log file compression is enabled, set the
'audit_log_compression' system variable at server startup.  Permitted
values are 'NONE' (no compression; the default) and 'GZIP' (GNU Zip
compression).

If both compression and encryption are enabled, compression occurs
before encryption.  To recover the original file manually, first decrypt
it, then uncompress it.  See
audit-log-file-uncompression-decryption.

*Audit Log File Encryption*

Audit log file encryption is available as of MySQL 5.7.21.  Encryption
can be enabled for any logging format.  Encryption is based on a
user-defined password.  To use this feature, the MySQL keyring must be
enabled because audit logging uses it for password storage.  Any keyring
plugin can be used; for instructions, see keyring.

To control whether audit log file encryption is enabled, set the
'audit_log_encryption' system variable at server startup.  Permitted
values are 'NONE' (no encryption; the default) and 'AES' (AES-256-CBC
cipher encryption).

To set or get the encryption password, use these user-defined functions
(UDFs):

   * To set the encryption password, invoke
     'audit_log_encryption_password_set()', which stores the password in
     the keyring, renames the current log file, and begins a new log
     file encrypted with the new password.  The renamed file has a
     timestamp inserted after its base name and before its suffix.  For
     example, if the file name is 'audit.log.enc', the plugin renames it
     to a value such as 'audit.20180115T140633.log.enc'.  The timestamp
     is a UTC value in 'YYYYMMDDTHHMMSS' format.

     Previously written audit log files are not re-encrypted with the
     new password.  Remember the previous password should you need to
     decrypt those files.

   * To get the current encryption password, invoke
     'audit_log_encryption_password_get()', which retrieves the password
     from the keyring.

For the first server startup after audit log encryption is enabled, the
audit log plugin automatically generates the initial encryption password
and stores it in the keyring.  To discover this password, invoke
'audit_log_encryption_password_get()'.

For additional information about audit log encryption functions, see
audit-log-routines.

If both compression and encryption are enabled, compression occurs
before encryption.  To recover the original file manually, first decrypt
it, then uncompress it.  See
audit-log-file-uncompression-decryption.

*Audit Log File Manual Uncompression and Decryption*

Audit log files can be uncompressed and decrypted using standard tools.
This should be done only for log files that have been closed and are no
longer in use, not for the log file that the audit log plugin is
currently writing.  You can recognize closed log files because they will
have been renamed by the audit log plugin to include a timestamp in the
file name.

For this discussion, assume that 'audit_log_file' is set to 'audit.log'.
In that case, a closed audit log file has one of these names:

     audit.TIMESTAMP.log        Not compressed or encrypted
     audit.TIMESTAMP.log.gz     Compressed
     audit.TIMESTAMP.log.enc    Encrypted
     audit.TIMESTAMP.log.gz.enc Compressed and encrypted

To uncompress a compressed log file manually, use 'gunzip', 'gzip -d',
or equivalent command.  For example:

     gunzip -c audit.TIMESTAMP.log.gz > audit.TIMESTAMP.log

To decrypt an encrypted log file manually, use the 'openssl' command.
For example:

     openssl enc -d -aes-256-cbc -pass pass:PASSWORD -md sha256
         -in audit.TIMESTAMP.log.enc -out audit.TIMESTAMP.log

If both compression and encryption are enabled for audit logging,
compression occurs before encryption.  In this case, the file name has
'.gz' and '.enc' suffixes added, corresponding to the order in which
those operations occur.  To recover the original file manually, perform
the operations in reverse.  That is, first decrypt the file, then
uncompress it:

     openssl enc -d -aes-256-cbc -pass pass:PASSWORD -md sha256
         -in audit.TIMESTAMP.log.gz.enc -out audit.TIMESTAMP.log.gz
     gunzip -c audit.TIMESTAMP.log.gz > audit.TIMESTAMP.log

*Audit Logging Write Strategy*

The audit log plugin can use any of several strategies for log writes.
Regardless of strategy, logging occurs on a best-effort basis, with no
guarantee of consistency.

To specify a write strategy, set the 'audit_log_strategy' system
variable at server startup.  By default, the strategy value is
'ASYNCHRONOUS' and the plugin logs asynchronously to a buffer, waiting
if the buffer is full.  It's possible to tell the plugin not to wait
('PERFORMANCE') or to log synchronously, either using file system
caching ('SEMISYNCHRONOUS') or forcing output with a 'sync()' call after
each write request ('SYNCHRONOUS').

For asynchronous write strategy, the 'audit_log_buffer_size' system
variable is the buffer size in bytes.  Set this variable at server
startup to change the buffer size.  The plugin uses a single buffer,
which it allocates when it initializes and removes when it terminates.
The plugin does not allocate this buffer for nonasynchronous write
strategies.

Asynchronous logging strategy has these characteristics:

   * Minimal impact on server performance and scalability.

   * Blocking of threads that generate audit events for the shortest
     possible time; that is, time to allocate the buffer plus time to
     copy the event to the buffer.

   * Output goes to the buffer.  A separate thread handles writes from
     the buffer to the log file.

With asynchronous logging, the integrity of the log file may be
compromised if a problem occurs during a write to the file or if the
plugin does not shut down cleanly (for example, in the event that the
server host exits unexpectedly).  To reduce this risk, set
'audit_log_strategy' to use synchronous logging.

A disadvantage of 'PERFORMANCE' strategy is that it drops events when
the buffer is full.  For a heavily loaded server, the audit log may have
events missing.

*Audit Log File Space Management and Name Rotation*

The audit log file has the potential to grow very large and consume a
lot of disk space.  To enable management of the space used by its log
files, the audit log plugin provides the 'audit_log_rotate_on_size' and
'audit_log_flush' system variables, which control audit log file
rotation and flushing.  Rotation can be done manually, or automatically
based on file size.

Manual audit log file rotation

By default, 'audit_log_rotate_on_size=0' and there is no log rotation
except that which you perform manually.  In this case, the audit log
plugin closes and reopens the log file when the 'audit_log_flush' value
changes from disabled to enabled.  Log file renaming must be done
externally to the server.  Suppose that the log file name is 'audit.log'
and you want to maintain the three most recent log files, cycling
through the names 'audit.log.1.xml' through 'audit.log.3.xml'.  On Unix,
perform rotation manually like this:

  1. From the command line, rename the current log files:

          mv audit.log.2.xml audit.log.3.xml
          mv audit.log.1.xml audit.log.2.xml
          mv audit.log audit.log.1.xml

     At this point, the plugin is still writing to the current log file,
     which has been renamed to 'audit.log.1.xml'.

  2. Connect to the server and flush the log file so the plugin closes
     it and reopens a new 'audit.log' file:

          SET GLOBAL audit_log_flush = ON;

*Note*:

For JSON-format logging, renaming audit log files manually makes them
unavailable to the log-reading functions because the audit log plugin no
longer can determine that they are part of the log file sequence (see
audit-log-file-reading).  Consider setting
'audit_log_rotate_on_size' greater than 0 to use size-based rotation
instead.

Automatic size-based audit log file rotation

If 'audit_log_rotate_on_size' is greater than 0, setting
'audit_log_flush' has no effect.  Instead, whenever a write to the log
file causes its size to exceed the 'audit_log_rotate_on_size' value, the
audit log plugin closes the file, renames it, and opens a new log file.

The plugin renames the original file as follows:

   * As of MySQL 5.7.21, the renamed file has a timestamp inserted after
     its base name and before its suffix.  For example, if the file name
     is 'audit.log', the plugin renames it to a value such as
     'audit.20180115T140633.log'.  The timestamp is a UTC value in
     'YYYYMMDDTHHMMSS' format.

   * Prior to MySQL 5.7.21, the renamed file has a timestamp and '.xml'
     added to the end.  For example, if the file name is 'audit.log',
     the plugin renames it to a value such as
     'audit.log.15159344437726520.xml'.  The timestamp value is similar
     to a Unix timestamp, with the last 7 digits representing the
     fractional second part.  By inserting a decimal point, the value
     can be interpreted using the 'FROM_UNIXTIME()' function:

          mysql> SELECT FROM_UNIXTIME(1515934443.7726520);
          +-----------------------------------+
          | FROM_UNIXTIME(1515934443.7726520) |
          +-----------------------------------+
          | 2018-01-14 06:54:03.772652        |
          +-----------------------------------+

*Note*:

With size-based log file rotation, renamed log files do not rotate off
the end of the name sequence.  Instead, they have unique names and
accumulate indefinitely.  To avoid excessive space use, remove old files
periodically, backing them up first as necessary.

*Audit Log File Reading*

The audit log plugin enables bookmarking and reading of JSON-format
audit log files.  (These capabilities do not apply to files written in
other log formats.)

When the audit log plugin initializes and is configured for JSON
logging, it uses the directory containing the audit log file (determined
from the 'audit_log_file' value) as the location to search for readable
audit log files.  To do this, it uses the value of 'audit_log_file' to
determine the file base name and suffix values, then looks for files
with names that match the following pattern, where '[...]' indicates
optional file name parts:

     BASENAME[.TIMESTAMP].SUFFIX[.gz][.enc]

The plugin opens each matching file, checks that it really contains JSON
audit records, and sorts them using the timestamps from the first record
of each file to construct a list of log files that are subject to use
with the log-reading functions.

The plugin cannot include in the sequence files that were renamed
manually and do not match the preceding pattern, or that were encrypted
with a password different from the current password.

To read events from the audit log, use these user-defined functions
(UDFs):

   * 'audit_log_read_bookmark()' returns a 'JSON' string
     representing a bookmark for the most recently written audit log
     event.  This bookmark is suitable for passing to 'audit_log_read()'
     to indicate to that function where to begin reading.  Example
     bookmark:

          { "timestamp": "2018-01-15 21:03:44", "id": 0 }

   * 'audit_log_read()' reads events from the audit log and returns a
     'JSON' string containing an array of audit events.

Example 'audit_log_read()' invocation using the current bookmark:

     mysql> SELECT audit_log_read(audit_log_read_bookmark());
     +-----------------------------------------------------------------------+
     | audit_log_read(audit_log_read_bookmark())                             |
     +-----------------------------------------------------------------------+
     | [ {"timestamp":"2018-01-15 22:41:24","id":0,"class":"connection", ... |
     +-----------------------------------------------------------------------+

Each event in the 'audit_log_read()' return value is a 'JSON'
hash, except that the last array element may be a 'JSON'.
'null' value to indicate no following events are available to
read.  For example:

     [
       { "timestamp": "2018-01-15 22:08:08", "id": 10,
         "class": "general", "event": "status",
         ...
       },
       {
         "timestamp": "2018-01-15 22:08:08", "id": 11,
         "class": "connection", "event": "disconnect",
         ...
       },
       {
         "timestamp": "2018-01-15 13:39:33", "id": 0,
         "class": "connection", "event": "connect",
         ...
       },
       {
         "timestamp": "2018-01-15 13:39:33", "id": 1,
         "class": "general", "event": "status",
         ...
       },
       {
         "timestamp": "2018-01-15 13:39:33", "id": 2,
         "class": "connection", "event": "disconnect",
         ...
       },
       null
     ]

Use 'audit_log_read()' like this:

   * For the first call to 'audit_log_read()' within a session, pass a
     bookmark indicating where to begin reading.

   * If the final value of the returned array is not a 'JSON'.
     'null' value, there are more events following those just read
     and 'audit_log_read()' can be called without or with a bookmark
     argument.  Without an argument, reading continues with the next
     unread event.  With a bookmark argument, reading continues from the
     bookmark.

   * If the final value of the returned array is a 'JSON'.
     'null' value, there are no more events left to be read and the next
     call to 'audit_log_read()' must include a bookmark argument.

A bookmark is a 'JSON' hash that indicates where and how
much to read.  The following items are significant in the bookmark value
(other items are ignored):

   * 'timestamp', 'id': The location within the audit log of the first
     event to read.  Both items must be present to completely specify a
     position.

   * 'max_array_length': The maximum number of events to read from the
     log.  If omitted, the default is to read to the end of the log or
     until the read buffer is full, whichever comes first.

The result returned from either log-reading function is a binary string.
To use the string with functions that require a nonbinary string (such
as the functions that manipulate 'JSON' values), convert it to
'utf8mb4'.  Suppose that a bookmark has this value:

     mysql> SELECT @mark := audit_log_read_bookmark() AS mark;
     +-------------------------------------------------+
     | mark                                            |
     +-------------------------------------------------+
     | { "timestamp": "2018-01-15 16:10:28", "id": 2 } |
     +-------------------------------------------------+

Calling 'audit_log_read()' with that bookmark can return multiple
events.  To set a limit on the number of events read by
'audit_log_read()', convert the bookmark to 'utf8mb4', then add to it a
'max_array_length' item with a value of 1.  For example, using the
preceding bookmark, convert and modify it as follows:

     mysql> SET @mark = CONVERT(@mark USING utf8mb4);
     mysql> SET @mark := JSON_SET(@mark, '$.max_array_length', 1);
     mysql> SELECT @mark;
     +----------------------------------------------------------------------+
     | @mark                                                                |
     +----------------------------------------------------------------------+
     | {"id": 2, "timestamp": "2018-01-15 16:10:28", "max_array_length": 1} |
     +----------------------------------------------------------------------+

The modified bookmark, when passed to 'audit_log_read()', produces a
result of a single audit record.

To set a limit on the number of bytes that 'audit_log_read()' reads, set
the 'audit_log_read_buffer_size' system variable at server startup.

For additional information about audit log-reading functions, see
audit-log-routines.

6.5.5.6 Audit Log Filtering
...........................

*Note*:

This section describes how audit log filtering works as of MySQL 5.7.13
if the audit log plugin and the accompanying audit tables and UDFs are
installed.  If the plugin is installed but not the accompanying audit
tables and UDFs, the plugin operates in legacy filtering mode, described
in audit-log-legacy-filtering.  Legacy mode is filtering
behavior as it was prior to MySQL 5.7.13; that is, before the
introduction of rule-based filtering.

Prior to MySQL 5.7.13, the audit log plugin had the capability of
controlling logging of audited events by filtering them based on the
account from which events originate or event status.  As of MySQL
5.7.13, filtering capabilities are extended:

   * Audited events can be filtered using these characteristics:

        * User account

        * Audit event class

        * Audit event subclass

        * Value of event fields such as those that indicate operation
          status or SQL statement executed

   * Audit filtering is rule based:

        * A filter definition creates a set of auditing rules.
          Definitions can be configured to include or exclude events for
          logging based on the characteristics just described.

        * As of MySQL 5.7.20, filter rules have the capability of
          blocking (aborting) execution of qualifying events, in
          addition to existing capabilities for event logging.

        * Multiple filters can be defined, and any given filter can be
          assigned to any number of user accounts.

        * It is possible to define a default filter to use with any user
          account that has no explicitly assigned filter.

   * Audit filters can be defined, displayed, and modified using an SQL
     interface based on user-defined functions (UDFs).

   * Audit filter definitions are stored in the tables in the 'mysql'
     system database.

   * Within a given session, the value of the read-only
     'audit_log_filter_id' system variable indicates whether a filter
     has been assigned to the session.

*Note*:

By default, rule-based audit log filtering logs no auditable events for
any users.  To log all auditable events for all users, use the following
statements, which create a simple filter to enable logging and assign it
to the default account:

     SELECT audit_log_filter_set_filter('log_all', '{ "filter": { "log": true } }');
     SELECT audit_log_filter_set_user('%', 'log_all');

The filter assigned to '%' is used for connections from any account that
has no explicitly assigned filter (which initially is true for all
accounts).

The following list briefly summarizes the UDFs that implement the SQL
interface for audit filtering control:

   * 'audit_log_filter_set_filter()': Define a filter

   * 'audit_log_filter_remove_filter()': Remove a filter

   * 'audit_log_filter_set_user()': Start filtering a user account

   * 'audit_log_filter_remove_user()': Stop filtering a user account

   * 'audit_log_filter_flush()': Flush manual changes to the filter
     tables to affect ongoing filtering

For usage examples and complete details about the filtering functions,
see audit-log-filtering-functions, and
audit-log-routines.

Audit log filtering functions are subject to these constraints:

   * To use any filtering function, the 'audit_log' plugin must be
     enabled.  Otherwise, an error occurs:

          mysql> SELECT audit_log_filter_flush();
          +----------------------------------------------------------------------------+
          | audit_log_filter_flush()                                                   |
          +----------------------------------------------------------------------------+
          | ERROR: audit_log plugin has not been installed with INSTALL PLUGIN syntax. |
          +----------------------------------------------------------------------------+

     The audit tables must also exist or an error occurs:

          mysql> SELECT audit_log_filter_flush();
          +--------------------------------------------------+
          | audit_log_filter_flush()                         |
          +--------------------------------------------------+
          | ERROR: Could not reinitialize audit log filters. |
          +--------------------------------------------------+

     To install the 'audit_log' plugin, see
     audit-log-installation.

   * To use any filtering function, a user must possess the 'SUPER'
     privilege.  Otherwise, an error occurs:

          mysql> SELECT audit_log_filter_flush()\G
          *************************** 1. row ***************************
          audit_log_filter_flush(): ERROR: Request ignored for 'user1'@'localhost'.
                                    SUPER_ACL needed to perform operation

     To grant the 'SUPER' privilege to a user account, use this
     statement:

          GRANT SUPER ON *.* TO USER;

     Alternatively, should you prefer to avoid granting the 'SUPER'
     privilege while still permitting users to access specific filtering
     functions, 'wrapper' stored programs can be defined.  This
     technique is described in the context of keyring UDFs in
     keyring-udf-usage; it can be adapted for use with filtering UDFs.

   * The 'audit_log' plugin operates in legacy mode if it is installed
     but the accompanying audit tables and functions are not created.
     The plugin writes these messages to the error log at server
     startup:

          [Warning] Plugin audit_log reported: 'Failed to open the audit log filter tables.'
          [Warning] Plugin audit_log reported: 'Audit Log plugin supports a filtering,
          which has not been installed yet. Audit Log plugin will run in the legacy
          mode, which will be disabled in the next release.'

     In legacy mode, filtering can be done based only on event account
     or status.  For details, see audit-log-legacy-filtering.

6.5.5.7 Using Audit Log Filtering Functions
...........................................

Before using the audit log user-defined functions (UDFs), install them
according to the instructions provided in
audit-log-installation.  The 'SUPER' privilege is required to use any
of these functions.

The audit log filtering functions enable filtering control by providing
an interface to create, modify, and remove filter definitions and assign
filters to user accounts.

Filter definitions are 'JSON' values.  For information
about using 'JSON' data in MySQL, see json.  This
section shows some simple filter definitions.  For more information
about filter definitions, see audit-log-filter-definitions.

When a connection arrives, the audit log plugin determines which filter
to use for the new session by searching for the user account name in the
current filter assignments:

   * If a filter is assigned to the user, the audit log uses that
     filter.

   * Otherwise, if no user-specific filter assignment exists, but there
     is a filter assigned to the default account ('%'), the audit log
     uses the default filter.

   * Otherwise, the audit log selects no audit events from the session
     for processing.

If a change-user operation occurs during a session (see
mysql-change-user), filter assignment for the session is updated using
the same rules but for the new user.

By default, no accounts have a filter assigned, so no processing of
auditable events occurs for any account.

Suppose that instead you want the default to be to log only
connection-related activity (for example, to see connect, change-user,
and disconnect events, but not the SQL statements users execute while
connected).  To achieve this, define a filter (shown here named
'log_conn_events') that enables logging only of events in the
'connection' class, and assign that filter to the default account,
represented by the '%' account name:

     SET @f = '{ "filter": { "class": { "name": "connection" } } }';
     SELECT audit_log_filter_set_filter('log_conn_events', @f);
     SELECT audit_log_filter_set_user('%', 'log_conn_events');

Now the audit log uses this default account filter for connections from
any account that has no explicitly defined filter.

To assign a filter explicitly to a particular user account or accounts,
define the filter, then assign it to the relevant accounts:

     SELECT audit_log_filter_set_filter('log_all', '{ "filter": { "log": true } }');
     SELECT audit_log_filter_set_user('user1@localhost', 'log_all');
     SELECT audit_log_filter_set_user('user2@localhost', 'log_all');

Now full logging is enabled for 'user1@localhost' and 'user2@localhost'.
Connections from other accounts continue to be filtered using the
default account filter.

To disassociate a user account from its current filter, either unassign
the filter or assign a different filter:

   * Unassign the filter from the user account:

          SELECT audit_log_filter_remove_user('user1@localhost');

     Filtering of current sessions for the account remains unaffected.
     Subsequent connections from the account are filtered using the
     default account filter if there is one, and are not logged
     otherwise.

   * Assign a different filter to the user account:

          SELECT audit_log_filter_set_filter('log_nothing', '{ "filter": { "log": false } }');
          SELECT audit_log_filter_set_user('user1@localhost', 'log_nothing');

     Filtering of current sessions for the account remains unaffected.
     Subsequent connections from the account are filtered using the new
     filter.  For the filter shown here, that means no logging for new
     connections from 'user1@localhost'.

For audit log filtering, user name and host name comparisons are
case-sensitive.  This differs from comparisons for privilege checking,
for which host name comparisons are not case-sensitive.

To remove a filter, do this:

     SELECT audit_log_filter_remove_filter('log_nothing');

Removing a filter also unassigns it from any users to whom it has been
assigned, including any current sessions for those users.

The filtering UDFs just described affect audit filtering immediately and
update the audit log tables in the 'mysql' system database that store
filters and user accounts (see audit-log-tables).  It is also
possible to modify the audit log tables directly using statements such
as 'INSERT', 'UPDATE', and 'DELETE',
but such changes do not affect filtering immediately.  To flush
your changes and make them operational, call 'audit_log_filter_flush()':

     SELECT audit_log_filter_flush();

To determine whether a filter has been assigned to the current session,
check the session value of the read-only 'audit_log_filter_id' system
variable.  If the value is 0, no filter is assigned.  A nonzero value
indicates the internally maintained ID of the assigned filter:

     mysql> SELECT @@audit_log_filter_id;
     +-----------------------+
     | @@audit_log_filter_id |
     +-----------------------+
     |                     2 |
     +-----------------------+

6.5.5.8 Writing Audit Log Filter Definitions
............................................

Filter definitions are 'JSON' values.  For information
about using 'JSON' data in MySQL, see json.

Filter definitions have this form, where ACTIONS indicates how filtering
takes place:

     { "filter": ACTIONS }

The following discussion describes permitted constructs in filter
definitions.

   * audit-log-filtering-enabling-logging

   * audit-log-filtering-class-logging

   * audit-log-filtering-subclass-logging

   * audit-log-filtering-inclusive-exclusive

   * audit-log-filtering-event-fields

   * audit-log-filtering-blocking-events

   * audit-log-filtering-logical-operators

   * audit-log-filtering-predefined-variables

   * audit-log-filtering-predefined-functions

   * audit-log-filtering-filter-replacement

*Logging All Events*

To explicitly enable or disable logging of all events, use a 'log'
element in the filter:

     {
       "filter": { "log": true }
     }

The 'log' value can be either 'true' or 'false'.

The preceding filter enables logging of all events.  It is equivalent
to:

     {
       "filter": { }
     }

Logging behavior depends on the 'log' value and whether 'class' or
'event' items are specified:

   * With 'log' specified, its given value is used.

   * Without 'log' specified, logging is 'true' if no 'class' or 'event'
     item is specified, and 'false' otherwise (in which case, 'class' or
     'event' can include their own 'log' item).

*Logging Specific Event Classes*

To log events of a specific class, use a 'class' element in the filter,
with its 'name' field denoting the name of the class to log:

     {
       "filter": {
         "class": { "name": "connection" }
       }
     }

The 'name' value can be 'connection', 'general', or 'table_access' to
log connection, general, or table-access events, respectively.

The preceding filter enables logging of events in the 'connection'
class.  It is equivalent to the following filter with 'log' items made
explicit:

     {
       "filter": {
         "log": false,
         "class": { "log": true,
                    "name": "connection" }
       }
     }

To enable logging of multiple classes, define the 'class' value as a
'JSON' array element that names the classes:

     {
       "filter": {
         "class": [
           { "name": "connection" },
           { "name": "general" },
           { "name": "table_access" }
         ]
       }
     }

*Note*:

When multiple instances of a given item appear at the same level within
a filter definition, the item values can be combined into a single
instance of that item within an array value.  The preceding definition
can be written like this:

     {
       "filter": {
         "class": [
           { "name": [ "connection", "general", "table_access" ] }
         ]
       }
     }

*Logging Specific Event Subclasses*

To select specific event subclasses, use an 'event' item containing a
'name' item that names the subclasses.  The default action for events
selected by an 'event' item is to log them.  For example, this filter
enables logging for the named event subclasses:

     {
       "filter": {
         "class": [
           {
             "name": "connection",
             "event": [
               { "name": "connect" },
               { "name": "disconnect" }
             ]
           },
           { "name": "general" },
           {
             "name": "table_access",
             "event": [
               { "name": "insert" },
               { "name": "delete" },
               { "name": "update" }
             ]
           }
         ]
       }
     }

The 'event' item can also contain explicit 'log' items to indicate
whether to log qualifying events.  This 'event' item selects multiple
events and explicitly indicates logging behavior for them:

     "event": [
       { "name": "select", "log": false },
       { "name": "insert", "log": true },
       { "name": "delete", "log": true },
       { "name": "update", "log": true }
     ]

As of MySQL 5.7.20, the 'event' item can also indicate whether to block
qualifying events, if it contains an 'abort' item.  For details, see
audit-log-filtering-blocking-events.

audit-log-event-subclass-combinations describes the permitted
subclass values for each event class.

*Event Class and Subclass Combinations*

Event Class    Event          Description
               Subclass

'connection'   'connect'      Connection initiation (successful or
                              unsuccessful)

'connection'   'change_user'  User re-authentication with different
                              user/password during session

'connection'   'disconnect'   Connection termination

'general'      'status'       General operation information

'table_access' 'read'         Table read statements, such as
                              'SELECT' or 'INSERT INTO ... SELECT'.

'table_access' 'delete'       Table delete statements, such as
                              'DELETE' or 'TRUNCATE TABLE'.

'table_access' 'insert'       Table insert statements, such as
                              'INSERT' or 'REPLACE'.

'table_access' 'update'       Table update statements, such as
                              'UPDATE'.

audit-log-event-subclass-log-abort describes for each event
subclass whether it can be logged or aborted.

*Log and Abort Characteristics Per Event Class and Subclass Combination*

Event Class    Event          Can be Logged          Can be Aborted
               Subclass

'connection'   'connect'      Yes                    No

'connection'   'change_user'  Yes                    No

'connection'   'disconnect'   Yes                    No

'general'      'status'       Yes                    No

'table_access' 'read'         Yes                    Yes

'table_access' 'delete'       Yes                    Yes

'table_access' 'insert'       Yes                    Yes

'table_access' 'update'       Yes                    Yes

*Inclusive and Exclusive Logging*

A filter can be defined in inclusive or exclusive mode:

   * Inclusive mode logs only explicitly specified items.

   * Exclusive mode logs everything but explicitly specified items.

To perform inclusive logging, disable logging globally and enable
logging for specific classes.  This filter logs 'connect' and
'disconnect' events in the 'connection' class, and events in the
'general' class:

     {
       "filter": {
         "log": false,
         "class": [
           {
             "name": "connection",
             "event": [
               { "name": "connect", "log": true },
               { "name": "disconnect", "log": true }
             ]
           },
           { "name": "general", "log": true }
         ]
       }
     }

To perform exclusive logging, enable logging globally and disable
logging for specific classes.  This filter logs everything except events
in the 'general' class:

     {
       "filter": {
         "log": true,
         "class":
           { "name": "general", "log": false }
       }
     }

This filter logs 'change_user' events in the 'connection' class, and
'table_access' events:

     {
       "filter": {
         "log": true,
         "class": [
           {
             "name": "connection",
             "event": [
               { "name": "connect", "log": false },
               { "name": "disconnect", "log": false }
             ]
           },
           { "name": "general", "log": false }
         ]
       }
     }

*Testing Event Field Values*

To enable logging based on specific event field values, specify a
'field' item within the 'log' item that indicates the field name and its
expected value:

     {
       "filter": {
         "class": {
         "name": "general",
           "event": {
             "name": "status",
             "log": {
               "field": { "name": "general_command.str", "value": "Query" }
             }
           }
         }
       }
     }

Each event contains event class-specific fields that can be accessed
from within a filter to perform custom filtering.

A connection event indicates when a connection-related activity occurs
during a session, such as a user connecting to or disconnecting from the
server.  audit-log-connection-event-fields indicates the
permitted fields for connection events.

*Connection Event Fields*

Field Name                Field Type     Description

'status'                  integer
                                         Event status:

                                         0: OK

                                         Otherwise: Failed

'connection_id'           unsigned       Connection ID
                          integer

'user.str'                string         User name specified during
                                         authentication

'user.length'             unsigned       User name length
                          integer

'priv_user.str'           string         Authenticated user name
                                         (account user name)

'priv_user.length'        unsigned       Authenticated user name length
                          integer

'external_user.str'       string         External user name (provided
                                         by third-party authentication
                                         plugin)

'external_user.length'    unsigned       External user name length
                          integer

'proxy_user.str'          string         Proxy user name

'proxy_user.length'       unsigned       Proxy user name length
                          integer

'host.str'                string         Connected user host

'host.length'             unsigned       Connected user host length
                          integer

'ip.str'                  string         Connected user IP address

'ip.length'               unsigned       Connected user IP address
                          integer        length

'database.str'            string         Database name specified at
                                         connect time

'database.length'         unsigned       Database name length
                          integer

'connection_type'         integer
                                         Connection type:

                                         or '"::undefined"': Undefined

                                         or '"::tcp/ip"': TCP/IP

                                         or '"::socket"': Socket

                                         or '"::named_pipe"': Named
                                         pipe

                                         or '"::ssl"': TCP/IP with
                                         encryption

                                         or '"::shared_memory"': Shared
                                         memory

The '"::XXX"' values are symbolic pseudo-constants that may be given
instead of the literal numeric values.  They must be quoted as strings
and are case-sensitive.

A general event indicates the status code of an operation and its
details.  audit-log-general-event-fields indicates the permitted
fields for general events.

*General Event Fields*

Field Name                Field Type     Description

'general_error_code'      integer
                                         Event status:

                                         0: OK

                                         Otherwise: Failed

'general_thread_id'       unsigned       Connection/thread ID
                          integer

'general_user.str'        string         User name specified during
                                         authentication

'general_user.length'     unsigned       User name length
                          integer

'general_command.str'     string         Command name

'general_command.length'  unsigned       Command name length
                          integer

'general_query.str'       string         SQL statement text

'general_query.length'    unsigned       SQL statement text length
                          integer

'general_host.str'        string         Host name

'general_host.length'     unsigned       Host name length
                          integer

'general_sql_command.str' string         SQL command type name

'general_sql_command.length'unsigned     SQL command type name length
                          integer

'general_external_user.str'string        External user name (provided
                                         by third-party authentication
                                         plugin)

'general_external_user.length'unsigned   External user name length
                          integer

'general_ip.str'          string         Connected user IP address

'general_ip.length'       unsigned       Connection user IP address
                          integer        length

'general_command.str' indicates a command name: 'Query', 'Execute',
'Quit', or 'Change user'.

A general event with the 'general_command.str' field set to 'Query' or
'Execute' contains 'general_sql_command.str' set to a value that
specifies the type of SQL command: 'alter_db', 'alter_db_upgrade',
'admin_commands', and so forth.  These values can be seen as the last
components of the Performance Schema instruments displayed by this
statement:

     mysql> SELECT NAME FROM performance_schema.setup_instruments
            WHERE NAME LIKE 'statement/sql/%' ORDER BY NAME;
     +---------------------------------------+
     | NAME                                  |
     +---------------------------------------+
     | statement/sql/alter_db                |
     | statement/sql/alter_db_upgrade        |
     | statement/sql/alter_event             |
     | statement/sql/alter_function          |
     | statement/sql/alter_instance          |
     | statement/sql/alter_procedure         |
     | statement/sql/alter_server            |
     ...

A table-access event provides information about specific table accesses.
audit-log-table-access-event-fields indicates the permitted
fields for table-access events.

*Table-Access Event Fields*

Field Name                Field Type     Description

'connection_id'           unsigned       Event connection ID
                          integer

'sql_command_id'          integer        SQL command ID

'query.str'               string         SQL statement text

'query.length'            unsigned       SQL statement text length
                          integer

'table_database.str'      string         Database name associated with
                                         event

'table_database.length'   unsigned       Database name length
                          integer

'table_name.str'          string         Table name associated with
                                         event

'table_name.length'       unsigned       Table name length
                          integer

The following list shows which statements produce which table-access
events:

   * 'read' event:

        * 'SELECT'

        * 'INSERT ... SELECT' (for tables referenced in 'SELECT' clause)

        * 'REPLACE ... SELECT' (for tables referenced in 'SELECT'
          clause)

        * 'UPDATE ... WHERE' (for tables referenced in 'WHERE' clause)

        * 'HANDLER ... READ'

   * 'delete' event:

        * 'DELETE'

        * 'TRUNCATE TABLE'

   * 'insert' event:

        * 'INSERT'

        * 'INSERT ... SELECT' (for table referenced in 'INSERT' clause)

        * 'REPLACE'

        * 'REPLACE ... SELECT' (for table referenced in 'REPLACE' clause

        * 'LOAD DATA INFILE'

        * 'LOAD XML INFILE'

   * 'update' event:

        * 'UPDATE'

        * 'UPDATE ... WHERE' (for tables referenced in 'UPDATE' clause)

*Blocking Execution of Specific Events*

As of MySQL 5.7.20, 'event' items can include an 'abort' item that
indicates whether to prevent qualifying events from executing.  For
example, 'abort' enables rules to be written that block execution of
specific SQL statements.

The 'abort' item must appear within an 'event' item.  For example:

     "event": {
       "name": QUALIFYING EVENT SUBCLASS NAMES
       "abort": CONDITION
     }

For event subclasses selected by the 'name' item, the 'abort' action is
true or false, depending on CONDITION evaluation.  If the condition
evaluates to true, the event is blocked.  Otherwise, the event continues
executing.

The CONDITION specification can be as simple as 'true' or 'false', or it
can be more complex such that evaluation depends on event
characteristics.

This filter blocks 'INSERT', 'UPDATE', and
'DELETE' statements:

     {
       "filter": {
         "class": {
           "name": "table_access",
           "event": {
             "name": [ "insert", "update", "delete" ],
             "abort": true
           }
         }
       }
     }

This more complex filter blocks the same statements, but only for a
specific table ('finances.bank_account'):

     {
       "filter": {
         "class": {
           "name": "table_access",
           "event": {
             "name": [ "insert", "update", "delete" ],
             "abort": {
               "and": [
                 { "field": { "name": "table_database.str", "value": "finances" } },
                 { "field": { "name": "table_name.str", "value": "bank_account" } }
               ]
             }
           }
         }
       }
     }

Statements matched and blocked by the filter return an error to the
client:

     ERROR 1045 (28000): Statement was aborted by an audit log filter

Not all events can be blocked (see
audit-log-event-subclass-log-abort).  For an event that cannot, the
audit log writes a warning to the error log rather than blocking it.

For attempts to define a filter in which the 'abort' item appears
elsewhere than in an 'event' item, an error occurs.

*Logical Operators*

Logical operators ('and', 'or', 'not') can be used in 'log' items.  This
permits construction of more advanced filtering configurations:

     {
       "filter": {
         "class": {
           "name": "general",
           "event": {
             "name": "status",
             "log": {
               "or": [
                 {
                   "and": [
                     { "field": { "name": "general_command.str",    "value": "Query" } },
                     { "field": { "name": "general_command.length", "value": 5 } }
                   ]
                 },
                 {
                   "and": [
                     { "field": { "name": "general_command.str",    "value": "Execute" } },
                     { "field": { "name": "general_command.length", "value": 7 } }
                   ]
                 }
               ]
             }
           }
         }
       }
     }

*Referencing Predefined Variables*

To refer to a predefined variable in a 'log' condition, use a 'variable'
item, which tests equality against a given value:

     {
       "filter": {
         "class": {
           "name": "general",
           "event": {
             "name": "status",
             "log": {
               "variable": {
                 "name": "audit_log_connection_policy_value", "value": "::none"
               }
             }
           }
         }
       }
     }

Each predefined variable corresponds to a system variable.  By writing a
filter that tests a predefined variable, you can modify filter operation
by setting the corresponding system variable, without having to redefine
the filter.  For example, by writing a filter that tests the value of
the 'audit_log_connection_policy_value' predefined variable, you can
modify filter operation by changing the value of the
'audit_log_connection_policy' system variable.

The 'audit_log_XXX_policy' system variables are used for the legacy mode
audit log (see audit-log-legacy-filtering).  With rule-based
audit log filtering, those variables remain visible (for example, using
'SHOW VARIABLES'), but changes to them have no
effect unless you write filters containing constructs that refer to
them.

The following list describes the permitted predefined variables for
'variable' items:

   * 'audit_log_connection_policy_value'

     This variable corresponds to the value of the
     'audit_log_connection_policy' system variable.  The value is an
     unsigned integer.  See audit-log-connection-policy-value-values
     shows the permitted values and the corresponding
     'audit_log_connection_policy' values.

     *audit_log_connection_policy_value Values*

     Value          Corresponding audit_log_connection_policy Value

     '0' or         'NONE'
     '"::none"'

     '1' or         'ERRORS'
     '"::errors"'

     '2' or         'ALL'
     '"::all"'

     The '"::XXX"' values are symbolic pseudo-constants that may be
     given instead of the literal numeric values.  They must be quoted
     as strings and are case-sensitive.

   * 'audit_log_policy_value'

     This variable corresponds to the value of the 'audit_log_policy'
     system variable.  The value is an unsigned integer.
     audit-log-policy-value-values shows the permitted values and the
     corresponding 'audit_log_policy' values.

     *audit_log_policy_value Values*

     Value          Corresponding audit_log_policy Value

     '0' or         'NONE'
     '"::none"'

     '1' or         'LOGINS'
     '"::logins"'

     '2' or         'ALL'
     '"::all"'

     '3' or         'QUERIES'
     '"::queries"'

     The '"::XXX"' values are symbolic pseudo-constants that may be
     given instead of the literal numeric values.  They must be quoted
     as strings and are case-sensitive.

   * 'audit_log_statement_policy_value'

     This variable corresponds to the value of the
     'audit_log_statement_policy' system variable.  The value is an
     unsigned integer.  See audit-log-statement-policy-value-values
     shows the permitted values and the corresponding
     'audit_log_statement_policy' values.

     *audit_log_statement_policy_value Values*

     Value          Corresponding audit_log_statement_policy Value

     '0' or         'NONE'
     '"::none"'

     '1' or         'ERRORS'
     '"::errors"'

     '2' or         'ALL'
     '"::all"'

     The '"::XXX"' values are symbolic pseudo-constants that may be
     given instead of the literal numeric values.  They must be quoted
     as strings and are case-sensitive.

*Referencing Predefined Functions*

To refer to a predefined function in a 'log' condition, use a 'function'
item, which takes 'name' and 'args' values to specify the function name
and its arguments, respectively:

     {
       "filter": {
         "class": {
           "name": "general",
           "event": {
             "name": "status",
             "log": {
               "function": {
                 "name": "find_in_include_list",
                 "args": [ { "string": [ { "field": "user.str" },
                                         { "string": "@"},
                                         { "field": "host.str" } ] } ]
               }
             }
           }
         }
       }
     }

The function as specified in the 'name' item should be the function name
only, without parentheses or the argument list.  Arguments in the 'args'
item, if there is one, must be given in the order listed in the function
description.  Arguments can refer to predefined variables, event fields,
or string or numeric constants.

The preceding filter determines whether to log 'general' class 'status'
events depending on whether the current user is found in the
'audit_log_include_accounts' system variable.  That user is constructed
using fields in the event.

The following list describes the permitted predefined functions for
'function' items:

   * 'audit_log_exclude_accounts_is_null()'

     Checks whether the 'audit_log_exclude_accounts' system variable is
     'NULL'.  This function can be helpful when defining filters that
     correspond to the legacy audit log implementation.

     Arguments:

     None.

   * 'audit_log_include_accounts_is_null()'

     Checks whether the 'audit_log_include_accounts' system variable is
     'NULL'.  This function can be helpful when defining filters that
     correspond to the legacy audit log implementation.

     Arguments:

     None.

   * 'debug_sleep(millisec)'

     Sleeps for the given number of milliseconds.  This function is used
     during performance measurement.

     'debug_sleep()' is available for debug builds only.

     Arguments:

        * 'millisec': The number of milliseconds to sleep as an unsigned
          integer.

   * 'find_in_exclude_list(account)'

     Checks whether an account string exists in the audit log exclude
     list (the value of the 'audit_log_exclude_accounts' system
     variable).

     Arguments:

        * 'account': The user account name as a string.

   * 'find_in_include_list(account)'

     Checks whether an account string exists in the audit log include
     list (the value of the 'audit_log_include_accounts' system
     variable).

     Arguments:

        * 'account': The user account name as a string.

   * 'string_find(text, substr)'

     Checks whether the 'substr' value is contained in the 'text' value.
     This search is case-sensitive.

     Arguments:

        * 'text': The text string to search.

        * 'substr': The substring to search for in 'text'.

*Replacing a User Filter*

In some cases, the filter definition can be changed dynamically.  To do
this, define a 'filter' configuration within an existing 'filter'.  For
example:

     {
       "filter": {
         "id": "main",
         "class": {
           "name": "table_access",
           "event": {
             "name": [ "update", "delete" ],
             "log": false,
             "filter": {
               "class": {
                 "name": "general",
                 "event" : { "name": "status",
                             "filter": { "ref": "main" } }
               },
               "activate": {
                 "or": [
                   { "field": { "name": "table_name.str", "value": "temp_1" } },
                   { "field": { "name": "table_name.str", "value": "temp_2" } }
                 ]
               }
             }
           }
         }
       }
     }

A new filter is activated when the 'activate' element within a subfilter
evaluates to 'true'.  Using 'activate' in a top-level 'filter' is not
permitted.

A new filter can be replaced with the original one by using a 'ref' item
inside the subfilter to refer to the original filter 'id'.

The filter shown operates like this:

   * The 'main' filter waits for 'table_access' events, either 'update'
     or 'delete'.

   * If the 'update' or 'delete' 'table_access' event occurs on the
     'temp_1' or 'temp_2' table, the filter is replaced with the
     internal one (without an 'id', since there is no need to refer to
     it explicitly).

   * If the end of the command is signalled ('general' / 'status'
     event), an entry is written to the audit log file and the filter is
     replaced with the 'main' filter.

The filter is useful to log statements that update or delete anything
from the 'temp_1' or 'temp_2' tables, such as this one:

     UPDATE temp_1, temp_3 SET temp_1.a=21, temp_3.a=23;

The statement generates multiple 'table_access' events, but the audit
log file will contain only 'general' / 'status' entries.

*Note*:

Any 'id' values used in the definition are evaluated with respect only
to that definition.  They have nothing to do with the value of the
'audit_log_filter_id' system variable.

6.5.5.9 Legacy Mode Audit Log Filtering
.......................................

*Note*:

This section describes legacy audit log filtering, which applies under
either of these circumstances:

   * Before MySQL 5.7.13, that is, prior to the introduction of
     rule-based audit log filtering described in
     audit-log-filtering.

   * As of MySQL 5.7.13, if the 'audit_log' plugin is installed but not
     the accompanying audit tables and UDFs needed for rule-based
     filtering.

The audit log plugin can filter audited events.  This enables you to
control whether audited events are written to the audit log file based
on the account from which events originate or event status.  Status
filtering occurs separately for connection events and statement events.

   * audit-log-account-filtering

   * audit-log-status-filtering

*Event Filtering by Account*

To filter audited events based on the originating account, set one of
these system variables at server startup or runtime:

   * 'audit_log_include_accounts': The accounts to include in audit
     logging.  If this variable is set, only these accounts are audited.

   * 'audit_log_exclude_accounts': The accounts to exclude from audit
     logging.  If this variable is set, all but these accounts are
     audited.

The value for either variable can be 'NULL' or a string containing one
or more comma-separated account names, each in 'USER_NAME@HOST_NAME'
format.  By default, both variables are 'NULL', in which case, no
account filtering is done and auditing occurs for all accounts.

Modifications to 'audit_log_include_accounts' or
'audit_log_exclude_accounts' affect only connections created subsequent
to the modification, not existing connections.

Example: To enable audit logging only for the 'user1' and 'user2' local
host account accounts, set the 'audit_log_include_accounts' system
variable like this:

     SET GLOBAL audit_log_include_accounts = 'user1@localhost,user2@localhost';

Only one of 'audit_log_include_accounts' or 'audit_log_exclude_accounts'
can be non-'NULL' at a time:

   * If you set 'audit_log_include_accounts', the server sets
     'audit_log_exclude_accounts' to 'NULL'.

   * If you attempt to set 'audit_log_exclude_accounts', an error occurs
     unless 'audit_log_include_accounts' is 'NULL'.  In this case, you
     must first clear 'audit_log_include_accounts' by setting it to
     'NULL'.

     -- This sets audit_log_exclude_accounts to NULL
     SET GLOBAL audit_log_include_accounts = VALUE;

     -- This fails because audit_log_include_accounts is not NULL
     SET GLOBAL audit_log_exclude_accounts = VALUE;

     -- To set audit_log_exclude_accounts, first set
     -- audit_log_include_accounts to NULL
     SET GLOBAL audit_log_include_accounts = NULL;
     SET GLOBAL audit_log_exclude_accounts = VALUE;

If you inspect the value of either variable, be aware that 'SHOW VARIABLES'
displays 'NULL' as an empty string.  To
avoid this, use 'SELECT' instead:

     mysql> SHOW VARIABLES LIKE 'audit_log_include_accounts';
     +----------------------------+-------+
     | Variable_name              | Value |
     +----------------------------+-------+
     | audit_log_include_accounts |       |
     +----------------------------+-------+
     mysql> SELECT @@audit_log_include_accounts;
     +------------------------------+
     | @@audit_log_include_accounts |
     +------------------------------+
     | NULL                         |
     +------------------------------+

If a user name or host name requires quoting because it contains a
comma, space, or other special character, quote it using single quotes.
If the variable value itself is quoted with single quotes, double each
inner single quote or escape it with a backslash.  The following
statements each enable audit logging for the local 'root' account and
are equivalent, even though the quoting styles differ:

     SET GLOBAL audit_log_include_accounts = 'root@localhost';
     SET GLOBAL audit_log_include_accounts = '''root''@''localhost''';
     SET GLOBAL audit_log_include_accounts = '\'root\'@\'localhost\'';
     SET GLOBAL audit_log_include_accounts = "'root'@'localhost'";

The last statement will not work if the 'ANSI_QUOTES' SQL mode is
enabled because in that mode double quotes signify identifier quoting,
not string quoting.

*Event Filtering by Status*

To filter audited events based on status, set the following system
variables at server startup or runtime.  These variables apply only for
legacy audit log filtering.  For JSON audit log filtering, different
status variables apply; see audit-log-options-variables.

   * 'audit_log_connection_policy': Logging policy for connection events

   * 'audit_log_statement_policy': Logging policy for statement events

Each variable takes a value of 'ALL' (log all associated events; this is
the default), 'ERRORS' (log only failed events), or 'NONE' (do not log
events).  For example, to log all statement events but only failed
connection events, use these settings:

     SET GLOBAL audit_log_statement_policy = ALL;
     SET GLOBAL audit_log_connection_policy = ERRORS;

Another policy system variable, 'audit_log_policy', is available but
does not afford as much control as 'audit_log_connection_policy' and
'audit_log_statement_policy'.  It can be set only at server startup.  At
runtime, it is a read-only variable.  It takes a value of 'ALL' (log all
events; this is the default), 'LOGINS' (log connection events),
'QUERIES' (log statement events), or 'NONE' (do not log events).  For
any of those values, the audit log plugin logs all selected events
without distinction as to success or failure.  Use of 'audit_log_policy'
at startup works as follows:

   * If you do not set 'audit_log_policy' or set it to its default of
     'ALL', any explicit settings for 'audit_log_connection_policy' or
     'audit_log_statement_policy' apply as specified.  If not specified,
     they default to 'ALL'.

   * If you set 'audit_log_policy' to a non-'ALL' value, that value
     takes precedence over and is used to set
     'audit_log_connection_policy' and 'audit_log_statement_policy', as
     indicated in the following table.  If you also set either of those
     variables to a value other than their default of 'ALL', the server
     writes a message to the error log to indicate that their values are
     being overridden.

     Startup                  Resulting                Resulting
     audit_log_policy Value   audit_log_connection_policyaudit_log_statement_policy
                              Value                    Value

     'LOGINS'                 'ALL'                    'NONE'

     'QUERIES'                'NONE'                   'ALL'

     'NONE'                   'NONE'                   'NONE'

6.5.5.10 Audit Log Reference
............................

The following discussion serves as a reference to MySQL Enterprise Audit
components:

   * audit-log-tables

   * audit-log-routines

   * audit-log-option-variable-reference

   * audit-log-options-variables

   * audit-log-status-variables

To install the audit log tables and functions, use the instructions
provided in audit-log-installation.  Unless those components are
installed, the 'audit_log' plugin operates in legacy mode.  See
audit-log-legacy-filtering.

6.5.5.11 Audit Log Tables
.........................

MySQL Enterprise Audit uses tables in the 'mysql' system database for
persistent storage of filter and user account data.  The tables can be
accessed only by users with privileges for that database.  The tables
use the 'InnoDB' storage engine ('MyISAM' prior to MySQL 5.7.21).

If these tables are missing, the 'audit_log' plugin operates in legacy
mode.  See audit-log-legacy-filtering.

The 'audit_log_filter' table stores filter definitions.  The table has
these columns:

   * 'NAME'

     The filter name.

   * 'FILTER'

     The filter definition associated with the filter name.  Definitions
     are stored as 'JSON' values.

The 'audit_log_user' table stores user account information.  The table
has these columns:

   * 'USER'

     The user name part of an account.  For an account
     'user1@localhost', the 'USER' part is 'user1'.

   * 'HOST'

     The host name part of an account.  For an account
     'user1@localhost', the 'HOST' part is 'localhost'.

   * 'FILTERNAME'

     The name of the filter assigned to the account.  The filter name
     associates the account with a filter defined in the
     'audit_log_filter' table.

6.5.5.12 Audit Log Functions
............................

This section describes, for each audit log user-defined function (UDF),
its purpose, calling sequence, and return value.  For information about
the conditions under which these UDFs can be invoked, see
audit-log-filtering.

Each audit log UDF returns 'OK' for success, 'ERROR: MESSAGE' for
failure.

These audit log UDFs are available:

   * 'audit_log_encryption_password_get()'

     Retrieves the current audit log encryption password as a binary
     string.  The password is fetched from the MySQL keyring, which must
     be enabled or an error occurs.  Any keyring plugin can be used; for
     instructions, see keyring.

     For additional information about audit log encryption, see
     audit-log-file-encryption.

     Syntax:

          STRING audit_log_encryption_password_get()

     Arguments:

     None.

     Return values:

     Password string for success (up to 766 bytes), or 'NULL' and an
     error for failure.

     Example:

          mysql> SELECT audit_log_encryption_password_get();
          +-------------------------------------+
          | audit_log_encryption_password_get() |
          +-------------------------------------+
          | secret                              |
          +-------------------------------------+

   * 'audit_log_encryption_password_set()'

     Sets the audit log encryption password and stores it in the MySQL
     keyring, which must be enabled or an error occurs.  Any keyring
     plugin can be used; for instructions, see keyring.

     For additional information about audit log encryption, see
     audit-log-file-encryption.

     Syntax:

          INTEGER audit_log_encryption_password_set()

     Arguments:

     The password string.  The maximum permitted length is 766 bytes.

     Return values:

     1 for success, 0 for failure.

     Example:

          mysql> SELECT audit_log_encryption_password_set(PASSWORD);
          +---------------------------------------------+
          | audit_log_encryption_password_set(PASSWORD) |
          +---------------------------------------------+
          | 1                                           |
          +---------------------------------------------+

   * 'audit_log_filter_flush()'

     Calling any of the other filtering UDFs affects operational audit
     log filtering immediately and updates the audit log tables.  If
     instead you modify the contents of those tables directly using
     statements such as 'INSERT', 'UPDATE',
     and 'DELETE', the changes do not affect filtering
     immediately.  To flush your changes and make them operational, call
     'audit_log_filter_flush()'.

     'audit_log_filter_flush()' affects all current sessions and
     detaches them from their previous filters.  Current sessions are no
     longer logged unless they disconnect and reconnect, or execute a
     change-user operation.

     If this function fails, an error message is returned and the audit
     log is disabled until the next successful call to
     'audit_log_filter_flush()'.

     Syntax:

          STRING audit_log_filter_flush()

     Arguments:

     None.

     Return values:

     'OK' for success, 'ERROR: MESSAGE' for failure.

     Example:

          mysql> SELECT audit_log_filter_flush();
          +--------------------------+
          | audit_log_filter_flush() |
          +--------------------------+
          | OK                       |
          +--------------------------+

   * 'audit_log_filter_remove_filter()'

     Given a filter name, removes the filter from the current set of
     filters.  It is not an error for the filter not to exist.

     If a removed filter is assigned to any user accounts, those users
     stop being filtered (they are removed from the 'audit_log_user'
     table).  Termination of filtering includes any current sessions for
     those users: They are detached from the filter and no longer
     logged.

     Syntax:

          STRING audit_log_filter_remove_filter(STRING filter_name)

     Arguments:

        * 'filter_name': The filter name as a string.

     Return values:

     'OK' for success, 'ERROR: MESSAGE' for failure.

     Example:

          mysql> SELECT audit_log_filter_remove_filter('SomeFilter');
          +----------------------------------------------+
          | audit_log_filter_remove_filter('SomeFilter') |
          +----------------------------------------------+
          | OK                                           |
          +----------------------------------------------+

   * 'audit_log_filter_remove_user()'

     Given a user account name, cause the user to be no longer assigned
     to a filter.  It is not an error if the user has no filter
     assigned.  Filtering of current sessions for the user remains
     unaffected.  New connections for the user are filtered using the
     default account filter if there is one, and are not logged
     otherwise.

     If the name is '%', the function removes the default account filter
     that is used for any user account that has no explicitly assigned
     filter.

     Syntax:

          STRING audit_log_filter_remove_user(STRING user_name)

     Arguments:

        * 'user_name': The user account name as a string in
          'USER_NAME@HOST_NAME' format, or '%' to represent the default
          account.

     Return values:

     'OK' for success, 'ERROR: MESSAGE' for failure.

     Example:

          mysql> SELECT audit_log_filter_remove_user('user1@localhost');
          +-------------------------------------------------+
          | audit_log_filter_remove_user('user1@localhost') |
          +-------------------------------------------------+
          | OK                                              |
          +-------------------------------------------------+

   * 'audit_log_filter_set_filter()'

     Given a filter name and definition, adds the filter to the current
     set of filters.  If the filter already exists and is used by any
     current sessions, those sessions are detached from the filter and
     are no longer logged.  This occurs because the new filter
     definition has a new filter ID that differs from its previous ID.

     Syntax:

          STRING audit_log_filter_set_filter(STRING filter_name, STRING definition)

     Arguments:

        * 'filter_name': The filter name as a string.

        * 'definition': The filter definition as a 'JSON'.
          value.

     Return values:

     'OK' for success, 'ERROR: MESSAGE' for failure.

     Example:

          mysql> SET @f = '{ "filter": { "log": false } }';
          mysql> SELECT audit_log_filter_set_filter('SomeFilter', @f);
          +-----------------------------------------------+
          | audit_log_filter_set_filter('SomeFilter', @f) |
          +-----------------------------------------------+
          | OK                                            |
          +-----------------------------------------------+

   * 'audit_log_filter_set_user()'

     Given a user account name and a filter name, assigns the filter to
     the user.  A user can be assigned only one filter, so if the user
     was already assigned a filter, the assignment is replaced.
     Filtering of current sessions for the user remains unaffected.  New
     connections are filtered using the new filter.

     As a special case, the name '%' represents the default account.
     The filter is used for connections from any user account that has
     no explicitly assigned filter.

     Syntax:

          STRING audit_log_filter_set_user(STRING user_name, STRING filter_name)

     Arguments:

        * 'user_name': The user account name as a string in
          'USER_NAME@HOST_NAME' format, or '%' to represent the default
          account.

        * 'filter_name': The filter name as a string.

     Return values:

     'OK' for success, 'ERROR: MESSAGE' for failure.

     Example:

          mysql> SELECT audit_log_filter_set_user('user1@localhost', 'SomeFilter');
          +------------------------------------------------------------+
          | audit_log_filter_set_user('user1@localhost', 'SomeFilter') |
          +------------------------------------------------------------+
          | OK                                                         |
          +------------------------------------------------------------+

   * 'audit_log_read()'

     Reads events from the audit log and returns a binary 'JSON'
     string containing an array of audit events.  If the audit log
     format is not 'JSON', an error occurs.

     Each event in the return value is a 'JSON' hash,
     except that the last array element may be a 'JSON'.
     'null' value to indicate no following events are available to read.

     For the first call to 'audit_log_read()' within a session, pass a
     bookmark indicating where to begin reading.  If the final value of
     the returned array is not a 'JSON'. 'null' value, there
     are more events following those just read and 'audit_log_read()'
     can be called without or with a bookmark argument.  Without an
     argument, reading continues with the next unread event.  With a
     bookmark argument, reading continues from the bookmark.

     If the final value of the returned array is a 'JSON'.
     'null' value, there are no more events left to be read and the next
     call to 'audit_log_read()' must include a bookmark argument.

     To obtain a bookmark for the most recently written event, call
     'audit_log_read_bookmark()'.

     For additional information about audit log-reading functions, see
     audit-log-file-reading.

     Syntax:

          STRING audit_log_read([STRING arg])

     Arguments:

     'arg': An optional bookmark, represented as a string containing a
     'JSON' hash that indicates where and how much to read.
     The following items are significant in the 'arg' value (other items
     are ignored):

        * 'timestamp', 'id': The location within the audit log of the
          first event to read.  Both items must be present to completely
          specify a position.

        * 'max_array_length': The maximum number of events to read from
          the log.  If omitted, the default is to read to the end of the
          log or until the read buffer is full, whichever comes first.

     Return values:

     A binary 'JSON' string containing an array of audit
     events for success, or 'NULL' and an error for failure.

     Example:

          mysql> SELECT audit_log_read(audit_log_read_bookmark());
          +-----------------------------------------------------------------------+
          | audit_log_read(audit_log_read_bookmark())                             |
          +-----------------------------------------------------------------------+
          | [ {"timestamp":"2018-01-15 22:41:24","id":0,"class":"connection", ... |
          +-----------------------------------------------------------------------+

   * 'audit_log_read_bookmark()'

     Returns a binary 'JSON' string representing a bookmark
     for the most recently written audit log event.  If the audit log
     format is not 'JSON', an error occurs.

     The bookmark is a 'JSON' hash with 'timestamp' and
     'id' items indicating the event position within the audit log.  It
     is suitable for passing to 'audit_log_read()' to indicate to that
     function where to begin reading.

     For additional information about audit log-reading functions, see
     audit-log-file-reading.

     Syntax:

          STRING audit_log_read_bookmark()

     Arguments:

     None.

     Return values:

     A binary 'JSON' string containing a bookmark for
     success, or 'NULL' and an error for failure.

     Example:

          mysql> SELECT audit_log_read_bookmark();
          +-------------------------------------------------+
          | audit_log_read_bookmark()                       |
          +-------------------------------------------------+
          | { "timestamp": "2018-01-15 21:03:44", "id": 0 } |
          +-------------------------------------------------+

6.5.5.13 Audit Log Option and Variable Reference
................................................

*Audit Log Option and Variable Reference*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

audit-log      Yes         Yes

audit_log_buffer_sizeYes   Yes         Yes                     Global      No

audit_log_connection_policyYesYes      Yes                     Global      Yes

audit_log_current_session              Yes                     Both        No

Audit_log_current_size                             Yes         Global      No

Audit_log_event_max_drop_size                      Yes         Global      No

Audit_log_events                                   Yes         Global      No

Audit_log_events_filtered                          Yes         Global      No

Audit_log_events_lost                              Yes         Global      No

Audit_log_events_written                           Yes         Global      No

audit_log_exclude_accountsYesYes       Yes                     Global      Yes

audit_log_file Yes         Yes         Yes                     Global      No

audit_log_flush                        Yes                     Global      Yes

audit_log_formatYes        Yes         Yes                     Global      No

audit_log_include_accountsYesYes       Yes                     Global      Yes

audit_log_policyYes        Yes         Yes                     Global      No

audit_log_rotate_on_sizeYesYes         Yes                     Global      Yes

audit_log_statement_policyYesYes       Yes                     Global      Yes

audit_log_strategyYes      Yes         Yes                     Global      No

Audit_log_total_size                               Yes         Global      No

Audit_log_write_waits                              Yes         Global      No

6.5.5.14 Audit Log Options and Variables
........................................

This section describes the command options and system variables that
control operation of MySQL Enterprise Audit.  If values specified at
startup time are incorrect, the 'audit_log' plugin may fail to
initialize properly and the server does not load it.  In this case, the
server may also produce error messages for other audit log settings
because it will not recognize them.

To control the activation of the audit log plugin, use this option:

   *
     '--audit-log[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--audit-log[=value]'

     *Introduced*                         5.7.9

     *Type*                               enumeration

     *Default Value*                      'ON'

     *Valid Values*                       'ON' 'OFF' 'FORCE'
                                          'FORCE_PLUS_PERMANENT'

     This option controls how the server loads the 'audit_log' plugin at
     startup.  It is available only if the plugin has been previously
     registered with 'INSTALL PLUGIN' or is
     loaded with '--plugin-load' or '--plugin-load-add'.  See
     audit-log-installation.

     The option value should be one of those available for
     plugin-loading options, as described in
     server-plugin-loading.  For example,
     '--audit-log=FORCE_PLUS_PERMANENT' tells the server to load the
     plugin and prevent it from being removed while the server is
     running.

If the audit log plugin is enabled, it exposes several system variables
that permit control over logging:

     mysql> SHOW VARIABLES LIKE 'audit_log%';
     +-----------------------------+--------------+
     | Variable_name               | Value        |
     +-----------------------------+--------------+
     | audit_log_buffer_size       | 1048576      |
     | audit_log_connection_policy | ALL          |
     | audit_log_current_session   | OFF          |
     | audit_log_exclude_accounts  |              |
     | audit_log_file              | audit.log    |
     | audit_log_filter_id         | 0            |
     | audit_log_flush             | OFF          |
     | audit_log_format            | NEW          |
     | audit_log_include_accounts  |              |
     | audit_log_policy            | ALL          |
     | audit_log_rotate_on_size    | 0            |
     | audit_log_statement_policy  | ALL          |
     | audit_log_strategy          | ASYNCHRONOUS |
     +-----------------------------+--------------+

You can set any of these variables at server startup, and some of them
at runtime.  Those that are available only for legacy mode audit log
filtering are so noted.

   *
     'audit_log_buffer_size'

     Property                             Value

     *Command-Line Format*                '--audit-log-buffer-size=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_buffer_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1048576'

     *Default Value* (32-bit platforms)   '1048576'

     *Minimum Value* (64-bit platforms)   '4096'

     *Minimum Value* (32-bit platforms)   '4096'

     *Maximum Value* (64-bit platforms)   '18446744073709547520'

     *Maximum Value* (32-bit platforms)   '4294967295'

     When the audit log plugin writes events to the log asynchronously,
     it uses a buffer to store event contents prior to writing them.
     This variable controls the size of that buffer, in bytes.  The
     server adjusts the value to a multiple of 4096.  The plugin uses a
     single buffer, which it allocates when it initializes and removes
     when it terminates.  The plugin allocates this buffer only if
     logging is asynchronous.

   * 'audit_log_compression'

     Property                             Value

     *Command-Line Format*                '--audit-log-compression=value'

     *Introduced*                         5.7.21

     *System Variable*                    'audit_log_compression'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               enumeration

     *Default Value*                      'NONE'

     *Valid Values*                       'NONE' 'GZIP'

     The type of compression for the audit log file.  Permitted values
     are 'NONE' (no compression; the default) and 'GZIP' (GNU Zip
     compression).  For more information, see
     audit-log-file-compression.

   *
     'audit_log_connection_policy'

     Property                             Value

     *Command-Line Format*                '--audit-log-connection-policy=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_connection_policy'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'ALL'

     *Valid Values*                       'ALL' 'ERRORS' 'NONE'

     *Note*:

     This variable applies only to legacy mode audit log filtering (see
     audit-log-legacy-filtering).

     The policy controlling how the audit log plugin writes connection
     events to its log file.  The following table shows the permitted
     values.

     Value       Description

     'ALL'       Log all connection events

     'ERRORS'    Log only failed connection events

     'NONE'      Do not log connection events

     *Note*:

     At server startup, any explicit value given for
     'audit_log_connection_policy' may be overridden if
     'audit_log_policy' is also specified, as described in
     audit-log-logging-control.

   *
     'audit_log_current_session'

     Property                             Value

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_current_session'

     *Scope*                              Global, Session

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'depends on filtering policy'

     Whether audit logging is enabled for the current session.  The
     session value of this variable is read only.  It is set when the
     session begins based on the values of the
     'audit_log_include_accounts' and 'audit_log_exclude_accounts'
     system variables.  The audit log plugin uses the session value to
     determine whether to audit events for the session.  (There is a
     global value, but the plugin does not use it.)

   * 'audit_log_encryption'

     Property                             Value

     *Command-Line Format*                '--audit-log-encryption=value'

     *Introduced*                         5.7.21

     *System Variable*                    'audit_log_encryption'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               enumeration

     *Default Value*                      'NONE'

     *Valid Values*                       'NONE' 'AES'

     The type of encryption for the audit log file.  Permitted values
     are 'NONE' (no encryption; the default) and 'AES' (AES-256-CBC
     cipher encryption).  For more information, see
     audit-log-file-encryption.

   *
     'audit_log_exclude_accounts'

     Property                             Value

     *Command-Line Format*                '--audit-log-exclude-accounts=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_exclude_accounts'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     *Note*:

     This variable applies only to legacy mode audit log filtering (see
     audit-log-legacy-filtering).

     The accounts for which events should not be logged.  The value
     should be 'NULL' or a string containing a list of one or more
     comma-separated account names.  For more information, see
     audit-log-filtering.

     Modifications to 'audit_log_exclude_accounts' affect only
     connections created subsequent to the modification, not existing
     connections.

   *
     'audit_log_file'

     Property                             Value

     *Command-Line Format*                '--audit-log-file=file_name'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'audit.log'

     The base name and suffix of the file to which the audit log plugin
     writes events.  The default value is 'audit.log', regardless of
     logging format.  To have the name suffix correspond to the format,
     set the name explicitly, choosing a different suffix (for example,
     'audit.xml' for XML format, 'audit.json' for JSON format).

     If the value of 'audit_log_file' is a relative path name, the
     plugin interprets it relative to the data directory.  If the value
     is a full path name, the plugin uses the value as is.  A full path
     name may be useful if it is desirable to locate audit files on a
     separate file system or directory.  For security reasons, the audit
     log file should be written to a directory accessible only to the
     MySQL server and to users with a legitimate reason to view the log.

     For details about how the audit log plugin interprets the
     'audit_log_file' value and the rules for file renaming that occurs
     at plugin initialization and termination, see
     audit-log-file-name.

     As of MySQL 5.7.21, the audit log plugin uses the directory
     containing the audit log file (determined from the 'audit_log_file'
     value) as the location to search for readable audit log files.
     From these log files and the current file, the plugin constructs a
     list of the ones that are subject to use with the audit log
     bookmarking and reading functions.  See
     audit-log-file-reading.

   *
     'audit_log_filter_id'

     Property                             Value

     *Introduced*                         5.7.13

     *System Variable*                    'audit_log_filter_id'

     *Scope*                              Global, Session

     *Dynamic*                            No

     *Type*                               integer

     The session value of this variable indicates the internally
     maintained ID of the audit filter for the current session.  A value
     of 0 means that the session has no filter assigned.

   *
     'audit_log_flush'

     Property                             Value

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_flush'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     When this variable is set to enabled (1 or 'ON'), the audit log
     plugin closes and reopens its log file to flush it.  (The value
     remains 'OFF' so that you need not disable it explicitly before
     enabling it again to perform another flush.)  Enabling this
     variable has no effect unless 'audit_log_rotate_on_size' is 0.  For
     more information, see audit-log-logging-control.

   *
     'audit_log_format'

     Property                             Value

     *Command-Line Format*                '--audit-log-format=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_format'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (>= 5.7.9)                    enumeration

     *Default Value* (>= 5.7.9)           'NEW'

     *Valid Values* (>= 5.7.21)           'OLD' 'NEW' 'JSON'

     *Valid Values* (>= 5.7.9, <=         'OLD' 'NEW'
     5.7.20)

     The audit log file format.  Permitted values are 'OLD' (old-style
     XML), 'NEW' (new-style XML; the default), and (as of MySQL 5.7.21)
     'JSON'.  For details about each format, see
     audit-log-file-formats.

     *Note*:

     For information about issues to consider when changing the log
     format, see audit-log-file-format.

   *
     'audit_log_include_accounts'

     Property                             Value

     *Command-Line Format*                '--audit-log-include-accounts=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_include_accounts'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     *Note*:

     This variable applies only to legacy mode audit log filtering (see
     audit-log-legacy-filtering).

     The accounts for which events should be logged.  The value should
     be 'NULL' or a string containing a list of one or more
     comma-separated account names.  For more information, see
     audit-log-filtering.

     Modifications to 'audit_log_include_accounts' affect only
     connections created subsequent to the modification, not existing
     connections.

   *
     'audit_log_policy'

     Property                             Value

     *Command-Line Format*                '--audit-log-policy=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_policy'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               enumeration

     *Default Value*                      'ALL'

     *Valid Values*                       'ALL' 'LOGINS' 'QUERIES' 'NONE'

     *Note*:

     This variable applies only to legacy mode audit log filtering (see
     audit-log-legacy-filtering).

     The policy controlling how the audit log plugin writes events to
     its log file.  The following table shows the permitted values.

     Value       Description

     'ALL'       Log all events

     'LOGINS'    Log only login events

     'QUERIES'   Log only query events

     'NONE'      Log nothing (disable the audit stream)

     'audit_log_policy' can be set only at server startup.  At runtime,
     it is a read-only variable.  Two other system variables,
     'audit_log_connection_policy' and 'audit_log_statement_policy',
     provide finer control over logging policy and can be set either at
     startup or at runtime.  If you use 'audit_log_policy' at startup
     instead of the other two variables, the server uses its value to
     set those variables.  For more information about the policy
     variables and their interaction, see
     audit-log-logging-control.

   * 'audit_log_read_buffer_size'

     Property                             Value

     *Command-Line Format*                '--audit-log-read-buffer-size=#'

     *Introduced*                         5.7.21

     *System Variable*                    'audit_log_read_buffer_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1048576'

     *Default Value* (32-bit platforms)   '1048576'

     *Minimum Value* (64-bit platforms)   '524288'

     *Minimum Value* (32-bit platforms)   '524288'

     *Maximum Value* (64-bit platforms)   '18446744073709547520'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The buffer size for reading from the audit log file, in bytes.  The
     'audit_log_read()' function reads no more than this many bytes.
     Log file reading is supported only for JSON logging format.  For
     more information, see audit-log-file-reading.

   *
     'audit_log_rotate_on_size'

     Property                             Value

     *Command-Line Format*                '--audit-log-rotate-on-size=N'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_rotate_on_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     If the 'audit_log_rotate_on_size' value is 0, the audit log plugin
     does not perform automatic log file rotation.  Instead, use
     'audit_log_flush' to close and reopen the log on demand.  In this
     case, manually rename the file externally to the server before
     flushing it.

     If the 'audit_log_rotate_on_size' value is greater than 0,
     automatic size-based log file rotation occurs.  Whenever a write to
     the log file causes its size to exceed the
     'audit_log_rotate_on_size' value, the audit log plugin closes the
     current log file, renames it, and opens a new log file.

     For more information about audit log file rotation, see
     audit-log-space-management.

     If you set this variable to a value that is not a multiple of 4096,
     it is truncated to the nearest multiple.  (Thus, setting it to a
     value less than 4096 has the effect of setting it to 0 and no
     rotation occurs, except manually.)

   *
     'audit_log_statement_policy'

     Property                             Value

     *Command-Line Format*                '--audit-log-statement-policy=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_statement_policy'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'ALL'

     *Valid Values*                       'ALL' 'ERRORS' 'NONE'

     *Note*:

     This variable applies only to legacy mode audit log filtering (see
     audit-log-legacy-filtering).

     The policy controlling how the audit log plugin writes statement
     events to its log file.  The following table shows the permitted
     values.

     Value       Description

     'ALL'       Log all statement events

     'ERRORS'    Log only failed statement events

     'NONE'      Do not log statement events

     *Note*:

     At server startup, any explicit value given for
     'audit_log_statement_policy' may be overridden if
     'audit_log_policy' is also specified, as described in
     audit-log-logging-control.

   *
     'audit_log_strategy'

     Property                             Value

     *Command-Line Format*                '--audit-log-strategy=value'

     *Introduced*                         5.7.9

     *System Variable*                    'audit_log_strategy'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               enumeration

     *Default Value*                      'ASYNCHRONOUS'

     *Valid Values*                       'ASYNCHRONOUS' 'PERFORMANCE'
                                          'SEMISYNCHRONOUS' 'SYNCHRONOUS'

     The logging method used by the audit log plugin.  These strategy
     values are permitted:

        * 'ASYNCHRONOUS': Log asynchronously.  Wait for space in the
          output buffer.

        * 'PERFORMANCE': Log asynchronously.  Drop requests for which
          there is insufficient space in the output buffer.

        * 'SEMISYNCHRONOUS': Log synchronously.  Permit caching by the
          operating system.

        * 'SYNCHRONOUS': Log synchronously.  Call 'sync()' after each
          request.

6.5.5.15 Audit Log Status Variables
...................................

If the audit log plugin is enabled, it exposes several status variables
that provide operational information.  These variables are available for
for legacy mode audit filtering and JSON mode audit filtering.

   *
     'Audit_log_current_size'

     The size of the current audit log file.  The value increases when
     an event is written to the log and is reset to 0 when the log is
     rotated.

   *
     'Audit_log_event_max_drop_size'

     The size of the largest dropped event in performance logging mode.
     For a description of logging modes, see
     audit-log-logging-control.

   *
     'Audit_log_events'

     The number of events handled by the audit log plugin, whether or
     not they were written to the log based on filtering policy (see
     audit-log-logging-control).

   *
     'Audit_log_events_filtered'

     The number of events handled by the audit log plugin that were
     filtered (not written to the log) based on filtering policy (see
     audit-log-logging-control).

   *
     'Audit_log_events_lost'

     The number of events lost in performance logging mode because an
     event was larger than than the available audit log buffer space.
     This value may be useful for assessing how to set
     'audit_log_buffer_size' to size the buffer for performance mode.
     For a description of logging modes, see
     audit-log-logging-control.

   *
     'Audit_log_events_written'

     The number of events written to the audit log.

   *
     'Audit_log_total_size'

     The total size of events written to all audit log files.  Unlike
     'Audit_log_current_size', the value of 'Audit_log_total_size'
     increases even when the log is rotated.

   *
     'Audit_log_write_waits'

     The number of times an event had to wait for space in the audit log
     buffer in asynchronous logging mode.  For a description of logging
     modes, see audit-log-logging-control.

6.5.5.16 Audit Log Restrictions
...............................

MySQL Enterprise Audit is subject to these general restrictions:

   * Only SQL statements are logged.  Changes made by no-SQL APIs, such
     as memcached, Node.JS, and the NDB API, are not logged.

   * Only top-level statements are logged, not statements within stored
     programs such as triggers or stored procedures.

   * Contents of files referenced by statements such as 'LOAD DATA INFILE'
     are not logged.

   * Prior to MySQL 5.7.21, MySQL Enterprise Audit uses 'MyISAM' tables
     in the 'mysql' system database.  Group Replication does not support
     'MyISAM' tables.  Consequently, MySQL Enterprise Audit and Group
     Replication cannot be used together.

NDB Cluster

It is possible to use MySQL Enterprise Audit with MySQL NDB Cluster,
subject to the following conditions:

   * All changes to be logged must be done using the SQL interface.
     Changes using no-SQL interfaces, such as those provided by the NDB
     API, memcached, or ClusterJ, are not logged.

   * The plugin must be installed on each MySQL server that is used to
     execute SQL on the cluster.

   * Audit plugin data must be aggregated amongst all MySQL servers used
     with the cluster.  This aggregation is the responsibility of the
     application or user.

6.5.6 MySQL Enterprise Firewall
-------------------------------

*Note*:

MySQL Enterprise Firewall is an extension included in MySQL Enterprise
Edition, a commercial product.  To learn more about commercial products,
see <http://www.mysql.com/products/>.

MySQL Enterprise Edition includes MySQL Enterprise Firewall, an
application-level firewall that enables database administrators to
permit or deny SQL statement execution based on matching against
whitelists of accepted statement patterns.  This helps harden MySQL
Server against attacks such as SQL injection or attempts to exploit
applications by using them outside of their legitimate query workload
characteristics.

Each MySQL account registered with the firewall has its own statement
whitelist, enabling protection to be tailored per account.  For a given
account, the firewall can operate in recording, protecting, or detecting
mode, for training in the accepted statement patterns, active protection
against unacceptable statements, or passive detection of unacceptable
statements.  The diagram illustrates how the firewall processes incoming
statements in each mode.

FIGURE GOES HERE: MySQL Enterprise Firewall Operation

The following sections describe the components of MySQL Enterprise
Firewall, discuss how to install and use it, and provide reference
information for its components.

6.5.6.1 MySQL Enterprise Firewall Components
............................................

MySQL Enterprise Firewall is based on a plugin library that implements
these components:

   * A server-side plugin named 'MYSQL_FIREWALL' examines SQL statements
     before they execute and, based on its in-memory cache, renders a
     decision whether to execute or reject each statement.

   * Server-side plugins named 'MYSQL_FIREWALL_USERS' and
     'MYSQL_FIREWALL_WHITELIST' implement 'INFORMATION_SCHEMA' tables
     that provide views into the firewall data cache.

   * System tables named 'firewall_users' and 'firewall_whitelist' in
     the 'mysql' database provide persistent storage of firewall data.

   * Stored procedures named 'sp_set_firewall_mode()' and
     'sp_reload_firewall_rules()' perform tasks such as registering
     MySQL accounts with the firewall, establishing their operational
     mode, and managing transfer of firewall data between the cache and
     the underlying system tables.

   * A set of user-defined functions provides an SQL-level API for
     lower-level tasks such as synchronizing the cache with the
     underlying system tables.

   * System variables enable firewall configuration and status variables
     provide runtime operational information.

6.5.6.2 Installing or Uninstalling MySQL Enterprise Firewall
............................................................

MySQL Enterprise Firewall installation is a one-time operation that
installs the components described in firewall-components.
Installation can be performed using a graphical interface or manually:

   * On Windows, MySQL Installer includes an option to enable MySQL
     Enterprise Firewall for you.

   * MySQL Workbench 6.3.4 or higher can install MySQL Enterprise
     Firewall, enable or disable an installed firewall, or uninstall the
     firewall.

   * Manual MySQL Enterprise Firewall installation involves running a
     script located in the 'share' directory of your MySQL installation.

*Note*:

If installed, MySQL Enterprise Firewall involves some minimal overhead
even when disabled.  To avoid this overhead, do not install the firewall
unless you plan to use it.

*Note*:

MySQL Enterprise Firewall does not work together with the query cache.
If the query cache is enabled, disable it before installing the firewall
(see query-cache-configuration).

For usage instructions, see firewall-usage.  For reference
information, see firewall-reference.

   * firewall-install

   * firewall-uninstall

*Installing MySQL Enterprise Firewall*

If MySQL Enterprise Firewall is already installed from an older version
of MySQL, uninstall it using the instructions given later in this
section and then restart your server before installing the current
version.  In this case, it is also necessary to register your
configuration again.

On Windows, you can use MySQL Installer to install MySQL Enterprise
Firewall, as shown in firewall-installation-windows-installer.
Check the 'Enable Enterprise Firewall' checkbox.  ('Open Firewall port
for network access' has a different purpose.  It refers to Windows
Firewall and controls whether Windows blocks the TCP/IP port on which
the MySQL server listens for client connections.)

FIGURE GOES HERE: MySQL Enterprise Firewall Installation on Windows

To install MySQL Enterprise Firewall using MySQL Workbench 6.3.4 or
higher, see MySQL Enterprise Firewall Interface
(http://dev.mysql.com/doc/workbench/en/wb-mysql-firewall.html).

To install MySQL Enterprise Firewall manually, look in the 'share'
directory of your MySQL installation and choose the script that is
appropriate for your platform.  The available scripts differ in the
suffix used to refer to the plugin library file:

   * 'win_install_firewall.sql': Choose this script for Windows systems
     that use '.dll' as the file name suffix.

   * 'linux_install_firewall.sql': Choose this script for Linux and
     similar systems that use '.so' as the file name suffix.

The installation script creates stored procedures in the default
database, so choose a database to use.  Then run the script as follows,
naming the chosen database on the command line.  The example here uses
the 'mysql' database and the Linux installation script.  Make the
appropriate substitutions for your system.

     shell> mysql -u root -p mysql < linux_install_firewall.sql
     Enter password: (ENTER ROOT PASSWORD HERE)

*Note*:

As of MySQL 5.7.21, for a new installation of MySQL Enterprise Firewall,
'InnoDB' is used instead of 'MyISAM' for the firewall tables.  For
upgrades to an installation for which MySQL Enterprise Firewall is
already installed, it is recommended that you alter the firewall tables
to use 'InnoDB':

     ALTER TABLE mysql.firewall_users ENGINE=InnoDB;
     ALTER TABLE mysql.firewall_whitelist ENGINE=InnoDB;

Installing MySQL Enterprise Firewall either using a graphical interface
or manually should enable the firewall.  To verify that, connect to the
server and execute this statement:

     mysql> SHOW GLOBAL VARIABLES LIKE 'mysql_firewall_mode';
     +---------------------+-------+
     | Variable_name       | Value |
     +---------------------+-------+
     | mysql_firewall_mode | ON    |
     +---------------------+-------+

*Uninstalling MySQL Enterprise Firewall*

MySQL Enterprise Firewall can be uninstalled using MySQL Workbench or
manually.

To uninstall MySQL Enterprise Firewall using MySQL Workbench 6.3.4 or
higher, see MySQL Enterprise Firewall Interface
(http://dev.mysql.com/doc/workbench/en/wb-mysql-firewall.html).

To uninstall MySQL Enterprise Firewall manually, execute the following
statements.  It is assumed that the stored procedures were created in
the 'mysql' database.  Adjust the 'DROP PROCEDURE'
statements appropriately if the procedures were created
in a different database.

     DROP TABLE mysql.firewall_whitelist;
     DROP TABLE mysql.firewall_users;
     UNINSTALL PLUGIN mysql_firewall;
     UNINSTALL PLUGIN mysql_firewall_whitelist;
     UNINSTALL PLUGIN mysql_firewall_users;
     DROP FUNCTION set_firewall_mode;
     DROP FUNCTION normalize_statement;
     DROP FUNCTION read_firewall_whitelist;
     DROP FUNCTION read_firewall_users;
     DROP FUNCTION mysql_firewall_flush_status;
     DROP PROCEDURE mysql.sp_set_firewall_mode;
     DROP PROCEDURE mysql.sp_reload_firewall_rules;

6.5.6.3 Using MySQL Enterprise Firewall
.......................................

Before using MySQL Enterprise Firewall, install it according to the
instructions provided in firewall-installation.  Also, MySQL
Enterprise Firewall does not work together with the query cache; disable
the query cache if it is enabled (see
query-cache-configuration).

This section describes how to configure MySQL Enterprise Firewall using
SQL statements.  Alternatively, MySQL Workbench 6.3.4 or higher provides
a graphical interface for firewall control.  See MySQL Enterprise
Firewall Interface
(http://dev.mysql.com/doc/workbench/en/wb-mysql-firewall.html).

To enable or disable the firewall, set the 'mysql_firewall_mode' system
variable.  By default, this variable is enabled when the firewall is
installed.  To control the initial firewall state explicitly, you can
set the variable at server startup.  For example, to enable the firewall
in an option file, use these lines:

     [mysqld]
     mysql_firewall_mode=ON

It is also possible to disable or enable the firewall at runtime:

     mysql> SET GLOBAL mysql_firewall_mode = OFF;
     mysql> SET GLOBAL mysql_firewall_mode = ON;

In addition to the global on/off firewall mode, each account registered
with the firewall has its own operational mode.  For an account in
recording mode, the firewall learns an application's 'fingerprint,' that
is, the acceptable statement patterns that, taken together, form a
whitelist.  After training, switch the firewall to protecting mode to
harden MySQL against access by statements that deviate from the
fingerprint.  For additional training, switch the firewall back to
recording mode as necessary to update the whitelist with new statement
patterns.  An intrusion-detection mode is available that writes
suspicious statements to the error log but does not deny access.

The firewall maintains whitelist rules on a per-account basis, enabling
implementation of protection strategies such as these:

   * For an application that has unique protection requirements,
     configure it to use an account that is not used for any other
     purpose.

   * For applications that are related and share protection
     requirements, configure them as a group to use the same account.

Firewall operation is based on conversion of SQL statements to
normalized digest form.  Firewall digests are like the statement digests
used by the Performance Schema (see
performance-schema-statement-digests).  However, unlike the
Performance Schema, the relevant digest-related system variable is
'max_digest_length'.

For a connection from a registered account, the firewall converts each
incoming statement to normalized form and processes it according to the
account mode:

   * In recording mode, the firewall adds the normalized statement to
     the account whitelist rules.

   * In protecting mode, the firewall compares the normalized statement
     to the account whitelist rules.  If there is a match, the statement
     passes and the server continues to process it.  Otherwise, the
     server rejects the statement and returns an error to the client.
     The firewall also writes the rejected statement to the error log if
     the 'mysql_firewall_trace' system variable is enabled.

   * In detecting mode, the firewall matches statements as in protecting
     mode, but writes nonmatching statements to the error log without
     denying access.

Accounts that have a mode of 'OFF' or are not registered with the
firewall are ignored by it.

To protect an account using MySQL Enterprise Firewall, follow these
steps:

  1. Register the account and put it in recording mode.

  2. Connect to the MySQL server using the registered account and
     execute statements to be learned.  This establishes the account's
     whitelist of accepted statements.

  3. Switch the registered account to protecting mode.

The following example shows how to register an account with the
firewall, use the firewall to learn acceptable statements for that
account, and protect the account against execution of unacceptable
statements.  The example account, ''fwuser'@'localhost'', is for use by
an application that accesses tables in the 'sakila' database.  (This
database is available at <http://dev.mysql.com/doc/index-other.html>.)

*Note*:

The user and host parts of the account name are quoted separately for
statements such as 'CREATE USER' and 'GRANT',
whereas to specify an account for use with a firewall component,
name it as a single quoted string ''fwuser@localhost''.

The convention for naming accounts as a single quoted string for
firewall components means that you cannot use accounts that have
embedded '@' characters in the user name.

Perform the steps in the following procedure using an administrative
MySQL account, except those designated for execution by the account
registered with the firewall.  The default database should be 'sakila'
for statements executed using the registered account.

  1. If necessary, create the account to be protected (choose an
     appropriate password) and grant it privileges for the 'sakila'
     database:

          mysql> CREATE USER 'fwuser'@'localhost' IDENTIFIED BY 'fWp@3sw0rd';
          mysql> GRANT ALL ON sakila.* TO 'fwuser'@'localhost';

  2. Use the 'sp_set_firewall_mode()' stored procedure to register the
     account with the firewall and place it in recording mode (if the
     procedure is located in a database other than 'mysql', adjust the
     statement accordingly):

          mysql> CALL mysql.sp_set_firewall_mode('fwuser@localhost', 'RECORDING');

     During the course of its execution, the stored procedure invokes
     firewall user-defined functions, which may produce output of their
     own.

  3. Using the registered account, connect to the server, then execute
     some statements that are legitimate for it:

          mysql> SELECT first_name, last_name FROM customer WHERE customer_id = 1;
          mysql> UPDATE rental SET return_date = NOW() WHERE rental_id = 1;
          mysql> SELECT get_customer_balance(1, NOW());

     The firewall converts the statements to digest form and records
     them in the account whitelist.

     *Note*:

     Until the account executes statements in recording mode, its
     whitelist is empty, which is equivalent to 'deny all.' If switched
     to protecting mode, the account will be effectively prohibited from
     executing statements.

  4. At this point, the user and whitelist information is cached and can
     be seen in the firewall 'INFORMATION_SCHEMA' tables:

          mysql> SELECT MODE FROM INFORMATION_SCHEMA.MYSQL_FIREWALL_USERS
                 WHERE USERHOST = 'fwuser@localhost';
          +-----------+
          | MODE      |
          +-----------+
          | RECORDING |
          +-----------+
          mysql> SELECT RULE FROM INFORMATION_SCHEMA.MYSQL_FIREWALL_WHITELIST
                 WHERE USERHOST = 'fwuser@localhost';
          +----------------------------------------------------------------------------+
          | RULE                                                                       |
          +----------------------------------------------------------------------------+
          | SELECT `first_name` , `last_name` FROM `customer` WHERE `customer_id` = ?  |
          | SELECT `get_customer_balance` ( ? , NOW ( ) )                              |
          | UPDATE `rental` SET `return_date` = NOW ( ) WHERE `rental_id` = ?          |
          | SELECT @@`version_comment` LIMIT ?                                         |
          +----------------------------------------------------------------------------+

     *Note*:

     The '@@version_comment' rule comes from a statement sent
     automatically by the 'mysql' client when you connect
     to the server as the registered user.

     It is important to train the firewall under conditions matching
     application use.  For example, a given MySQL connector might send
     statements to the server at the beginning of a connection to
     determine server characteristics and capabilities.  If an
     application normally is used through that connector, train the
     firewall that way, too.  That enables those initial statements to
     become part of the whitelist for the account associated with the
     application.

  5. Use the stored procedure to switch the registered user to
     protecting mode:

          mysql> CALL mysql.sp_set_firewall_mode('fwuser@localhost', 'PROTECTING');

     *Important*:

     Switching the account out of 'RECORDING' mode synchronizes its
     firewall cache data to the underlying 'mysql' system database
     tables for persistent storage.  If you do not switch the mode for a
     user who is being recorded, the cached whitelist data is not
     written to the system tables and will be lost when the server is
     restarted.

  6. Using the registered account, execute some acceptable and
     unacceptable statements.  The firewall matches each one against the
     account whitelist and accepts or rejects it.

     This statement is not identical to a training statement but
     produces the same normalized statement as one of them, so the
     firewall accepts it:

          mysql> SELECT first_name, last_name FROM customer WHERE customer_id = '48';
          +------------+-----------+
          | first_name | last_name |
          +------------+-----------+
          | ANN        | EVANS     |
          +------------+-----------+

     These statements do not match anything in the whitelist and each
     results in an error:

          mysql> SELECT first_name, last_name FROM customer WHERE customer_id = 1 OR TRUE;
          ERROR 1045 (28000): Statement was blocked by Firewall
          mysql> SHOW TABLES LIKE 'customer%';
          ERROR 1045 (28000): Statement was blocked by Firewall
          mysql> TRUNCATE TABLE mysql.slow_log;
          ERROR 1045 (28000): Statement was blocked by Firewall

     The firewall also writes the rejected statements to the error log
     if the 'mysql_firewall_trace' system variable is enabled.  For
     example:

          [Note] Plugin MYSQL_FIREWALL reported:
          'ACCESS DENIED for fwuser@localhost. Reason: No match in whitelist.
          Statement: TRUNCATE TABLE `mysql` . `slow_log` '

     You can use these log messages in your efforts to identify the
     source of attacks.

  7. You can log nonmatching statements as suspicious without denying
     access.  To do this, put the account in intrusion-detecting mode:

          mysql> CALL mysql.sp_set_firewall_mode('fwuser@localhost', 'DETECTING');

  8. Using the registered account, connect to the server, then execute a
     statement that does not match the whitelist:

          mysql> SHOW TABLES LIKE 'customer%';
          +------------------------------+
          | Tables_in_sakila (customer%) |
          +------------------------------+
          | customer                     |
          | customer_list                |
          +------------------------------+

     In detecting mode, the firewall permits the nonmatching statement
     to execute but writes a message to the error log:

          [Note] Plugin MYSQL_FIREWALL reported:
          'SUSPICIOUS STATEMENT from 'fwuser@localhost'. Reason: No match in whitelist.
          Statement: SHOW TABLES LIKE ? '

  9. To assess firewall activity, examine its status variables:

          mysql> SHOW GLOBAL STATUS LIKE 'Firewall%';
          +----------------------------+-------+
          | Variable_name              | Value |
          +----------------------------+-------+
          | Firewall_access_denied     | 3     |
          | Firewall_access_granted    | 4     |
          | Firewall_access_suspicious | 1     |
          | Firewall_cached_entries    | 4     |
          +----------------------------+-------+

     The variables indicate the number of statements rejected, accepted,
     logged as suspicious, and added to the cache, respectively.  The
     'Firewall_access_granted' count is 4 because of the
     '@@version_comment' statement sent by the 'mysql'.
     client each of the three time you used it to connect as the
     registered user, plus the 'SHOW TABLES'.
     statement that was not blocked in 'DETECTING' mode.

Should additional training for an account be necessary, switch it to
recording mode again, then back to protecting mode after executing
statements to be added to the whitelist.

6.5.6.4 MySQL Enterprise Firewall Reference
...........................................

The following discussion serves as a reference to MySQL Enterprise
Firewall components:

   * firewall-tables

   * firewall-routines

   * firewall-system-variables

   * firewall-status-variables

6.5.6.5 MySQL Enterprise Firewall Tables
........................................

MySQL Enterprise Firewall maintains account and whitelist information.
It uses 'INFORMATION_SCHEMA' tables to provide views into cached data,
and tables in the 'mysql' system database to store this data in
persistent form.  When enabled, the firewall bases its operational
decisions on the cached data.

The 'INFORMATION_SCHEMA' tables are accessible by anyone.  The 'mysql'
tables can be accessed only by users with privileges for that database.

The 'INFORMATION_SCHEMA.MYSQL_FIREWALL_USERS' and 'mysql.firewall_users'
tables list registered firewall accounts and their operational modes.
The tables have these columns:

   * 'USERHOST'

     An account registered with the firewall.  Each account has the
     format 'USER_NAME@HOST_NAME' and represents actual user and host
     names as authenticated by the server.  Patterns and netmasks should
     not be used when registering users.

   * 'MODE'

     The current firewall operational mode for the account.  The
     permitted mode values are 'OFF', 'DETECTING', 'PROTECTING',
     'RECORDING', and 'RESET'.  For details about their meanings, see
     the description of 'sp_set_firewall_mode()' in
     firewall-routines.

The 'INFORMATION_SCHEMA.MYSQL_FIREWALL_WHITELIST' and
'mysql.firewall_whitelist' tables list registered firewall accounts and
their whitelists.  The tables have these columns:

   * 'USERHOST'

     An account registered with the firewall.  The format is the same as
     for the user account tables.

   * 'RULE'

     A normalized statement indicating an acceptable statement pattern
     for the account.  An account whitelist is the union of its rules.

   * 'ID'

     An integer column that is a primary key for the table.  This column
     was added in MySQL 5.7.23.

6.5.6.6 MySQL Enterprise Firewall Procedures and Functions
..........................................................

MySQL Enterprise Firewall has stored procedures that perform tasks such
as registering MySQL accounts with the firewall, establishing their
operational mode, and managing transfer of firewall data between the
cache and the underlying system tables.  It also has a set of
user-defined functions (UDFs) that provides an SQL-level API for
lower-level tasks such as synchronizing the cache with the underlying
system tables.

Under normal operation, the stored procedures implement the user
interface.  The UDFs are invoked by the stored procedures, not directly
by users.

To invoke a stored procedure when the default database is not the
database that contains the procedure, qualify the procedure name with
the database name.  For example:

     CALL mysql.sp_set_firewall_mode(USER, MODE);

The following list describes each firewall stored procedure and UDF:

   * 'sp_reload_firewall_rules(USER)'

     This stored procedure uses firewall UDFs to reset a registered
     account and reload the in-memory rules for it from the rules stored
     in the 'mysql.firewall_whitelist' table.  This procedure provides
     control over firewall operation for individual accounts.

     The USER argument names the affected account, as a string in
     'USER_NAME@HOST_NAME' format.

     Example:

          CALL mysql.sp_reload_firewall_rules('fwuser@localhost');

     *Warning*:

     This procedure sets the account mode to 'RESET', which clears the
     account whitelist and sets its mode to 'OFF'.  If the account mode
     was not 'OFF' prior to the 'sp_reload_firewall_rules()' call, use
     'sp_set_firewall_mode()' to restore its previous mode after
     reloading the rules.  For example, if the account was in
     'PROTECTING' mode, that is no longer true after calling
     'sp_reload_firewall_rules()' and you must set it to 'PROTECTING'
     again explicitly.

   * 'sp_set_firewall_mode(USER, MODE)'

     This stored procedure registers a MySQL account with the firewall
     and establishes its operational mode.  The procedure also invokes
     firewall UDFs as necessary to transfer firewall data between the
     cache and the underlying system tables.  This procedure may be
     called even if the 'mysql_firewall_mode' system variable is 'OFF',
     although setting the mode for an account has no operational effect
     while the firewall is disabled.

     The USER argument names the affected account, as a string in
     'USER_NAME@HOST_NAME' format.

     The MODE is the operational mode for the user, as a string.  These
     mode values are permitted:

        * 'OFF': Disable the firewall for the account.

        * 'DETECTING': Intrusion-detection mode: Write suspicious
          (nonmatching) statements to the error log but do not deny
          access.

        * 'PROTECTING': Protect the account by matching incoming
          statements against the account whitelist.

        * 'RECORDING': Training mode: Record acceptable statements for
          the account.  Incoming statements that do not immediately fail
          with a syntax error are recorded to become part of the account
          whitelist rules.

        * 'RESET': Clear the account whitelist and set the account mode
          to 'OFF'.

     Switching the mode for an account to any mode but 'RECORDING'
     synchronizes the firewall cache data to the underlying 'mysql'
     system database tables for persistent storage.  Switching the mode
     from 'OFF' to 'RECORDING' reloads the whitelist from the
     'mysql.firewall_whitelist' table into the cache.

     If an account has an empty whitelist, setting its mode to
     'PROTECTING' produces an error message that is returned in a result
     set, but not an SQL error:

          mysql> CALL mysql.sp_set_firewall_mode('a@b','PROTECTING');
          +----------------------------------------------------------------------+
          | set_firewall_mode(arg_userhost, arg_mode)                            |
          +----------------------------------------------------------------------+
          | ERROR: PROTECTING mode requested for a@b but the whitelist is empty. |
          +----------------------------------------------------------------------+
          1 row in set (0.02 sec)

          Query OK, 0 rows affected (0.02 sec)

   * 'mysql_firewall_flush_status()'

     This UDF resets several firewall status variables to 0:

          Firewall_access_denied
          Firewall_access_granted
          Firewall_access_suspicious

     Example:

          SELECT mysql_firewall_flush_status();

   * 'normalize_statement(STMT)'

     This UDF normalizes an SQL statement into the digest form used for
     whitelist rules.

     Example:

          SELECT normalize_statement('SELECT * FROM t1 WHERE c1 > 2');

   * 'read_firewall_users(USER, MODE)'

     This aggregate UDF updates the firewall user cache through a
     'SELECT' statement on the 'mysql.firewall_users' table.

     Example:

          SELECT read_firewall_users('fwuser@localhost', 'RECORDING')
          FROM mysql.firewall_users;

   * 'read_firewall_whitelist(USER, RULE)'

     This aggregate UDF updates the recorded statement cache through a
     'SELECT' statement on the 'mysql.firewall_whitelist' table.

     Example:

          SELECT read_firewall_whitelist('fwuser@localhost', 'RECORDING')
          FROM mysql.firewall_whitelist;

   * 'set_firewall_mode(USER, MODE)'

     This UDF manages the user cache and establishes the user
     operational mode.

     Example:

          SELECT set_firewall_mode('fwuser@localhost', 'RECORDING');

6.5.6.7 MySQL Enterprise Firewall System Variables
..................................................

MySQL Enterprise Firewall supports the following system variables.  Use
them to configure firewall operation.  These variables are unavailable
unless the firewall is installed (see firewall-installation).

   *
     'mysql_firewall_mode'

     Property                             Value

     *Command-Line Format*                '--mysql-firewall-mode={OFF|ON}'

     *Introduced*                         5.7.9

     *System Variable*                    'mysql_firewall_mode'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Whether MySQL Enterprise Firewall is enabled (the default) or
     disabled.

   *
     'mysql_firewall_trace'

     Property                             Value

     *Command-Line Format*                '--mysql-firewall-trace={OFF|ON}'

     *Introduced*                         5.7.9

     *System Variable*                    'mysql_firewall_trace'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether the MySQL Enterprise Firewall trace is enabled or disabled
     (the default).  When 'mysql_firewall_trace' is enabled, for
     'PROTECTING' mode, the firewall writes rejected statements to the
     error log.

6.5.6.8 MySQL Enterprise Firewall Status Variables
..................................................

MySQL Enterprise Firewall supports the following status variables.  Use
them to obtain information about firewall operational status.  These
variables are unavailable unless the firewall is installed (see
firewall-installation).  Firewall status variables are set to 0
whenever the 'MYSQL_FIREWALL' plugin is installed or the server is
started.  Many of them are reset to zero by the
'mysql_firewall_flush_status()' UDF (see firewall-routines).

   *
     'Firewall_access_denied'

     The number of statements rejected by MySQL Enterprise Firewall.

   *
     'Firewall_access_granted'

     The number of statements accepted by MySQL Enterprise Firewall.

   *
     'Firewall_access_suspicious'

     The number of statements logged by MySQL Enterprise Firewall as
     suspicious for users who are in 'DETECTING' mode.

   *
     'Firewall_cached_entries'

     The number of statements recorded by MySQL Enterprise Firewall,
     including duplicates.

7 Backup and Recovery
*********************

It is important to back up your databases so that you can recover your
data and be up and running again in case problems occur, such as system
crashes, hardware failures, or users deleting data by mistake.  Backups
are also essential as a safeguard before upgrading a MySQL installation,
and they can be used to transfer a MySQL installation to another system
or to set up replication slave servers.

MySQL offers a variety of backup strategies from which you can choose
the methods that best suit the requirements for your installation.  This
chapter discusses several backup and recovery topics with which you
should be familiar:

   * Types of backups: Logical versus physical, full versus incremental,
     and so forth.

   * Methods for creating backups.

   * Recovery methods, including point-in-time recovery.

   * Backup scheduling, compression, and encryption.

   * Table maintenance, to enable recovery of corrupt tables.

*Additional Resources*

Resources related to backup or to maintaining data availability include
the following:

   * Customers of MySQL Enterprise Edition can use the MySQL Enterprise
     Backup product for backups.  For an overview of the MySQL
     Enterprise Backup product, see mysql-enterprise-backup.

   * A forum dedicated to backup issues is available at
     <http://forums.mysql.com/list.php?28>.

   * Details for 'mysqldump' can be found in
     programs.

   * The syntax of the SQL statements described here is given in
     sql-syntax.

   * For additional information about 'InnoDB' backup procedures, see
     innodb-backup.

   * Replication enables you to maintain identical data on multiple
     servers.  This has several benefits, such as enabling client query
     load to be distributed over servers, availability of data even if a
     given server is taken offline or fails, and the ability to make
     backups with no impact on the master by using a slave server.  See
     replication.

   * MySQL InnoDB cluster is a collection of products that work together
     to provide a high availability solution.  A group of MySQL servers
     can be configured to create a cluster using MySQL Shell.  The
     cluster of servers has a single master, called the primary, which
     acts as the read-write master.  Multiple secondary servers are
     replicas of the master.  A minimum of three servers are required to
     create a high availability cluster.  A client application is
     connected to the primary via MySQL Router.  If the primary fails, a
     secondary is automatically promoted to the role of primary, and
     MySQL Router routes requests to the new primary.

   * NDB Cluster provides a high-availability, high-redundancy version
     of MySQL adapted for the distributed computing environment.  See
     mysql-cluster, which provides information about MySQL NDB
     Cluster 7.5 (based on MySQL 5.7 but containing the latest
     improvements and fixes for the 'NDB' storage
     engine).

7.1 Backup and Recovery Types
=============================

This section describes the characteristics of different types of
backups.

*Physical (Raw) Versus Logical Backups*

Physical backups consist of raw copies of the directories and files that
store database contents.  This type of backup is suitable for large,
important databases that need to be recovered quickly when problems
occur.

Logical backups save information represented as logical database
structure (see 'CREATE DATABASE', 'CREATE TABLE'
statements) and content (see 'INSERT'.
statements or delimited-text files).  This type of backup is suitable
for smaller amounts of data where you might edit the data values or
table structure, or recreate the data on a different machine
architecture.

Physical backup methods have these characteristics:

   * The backup consists of exact copies of database directories and
     files.  Typically this is a copy of all or part of the MySQL data
     directory.

   * Physical backup methods are faster than logical because they
     involve only file copying without conversion.

   * Output is more compact than for logical backup.

   * Because backup speed and compactness are important for busy,
     important databases, the MySQL Enterprise Backup product performs
     physical backups.  For an overview of the MySQL Enterprise Backup
     product, see mysql-enterprise-backup.

   * Backup and restore granularity ranges from the level of the entire
     data directory down to the level of individual files.  This may or
     may not provide for table-level granularity, depending on storage
     engine.  For example, 'InnoDB' tables can each be in a separate
     file, or share file storage with other 'InnoDB' tables; each
     'MyISAM' table corresponds uniquely to a set of files.

   * In addition to databases, the backup can include any related files
     such as log or configuration files.

   * Data from 'MEMORY' tables is tricky to back up this way because
     their contents are not stored on disk.  (The MySQL Enterprise
     Backup product has a feature where you can retrieve data from
     'MEMORY' tables during a backup.)

   * Backups are portable only to other machines that have identical or
     similar hardware characteristics.

   * Backups can be performed while the MySQL server is not running.  If
     the server is running, it is necessary to perform appropriate
     locking so that the server does not change database contents during
     the backup.  MySQL Enterprise Backup does this locking
     automatically for tables that require it.

   * Physical backup tools include the 'mysqlbackup' of MySQL Enterprise
     Backup for 'InnoDB' or any other tables, or file system-level
     commands (such as 'cp', 'scp', 'tar', 'rsync') for 'MyISAM' tables.

   * For restore:

        * MySQL Enterprise Backup restores 'InnoDB' and other tables
          that it backed up.

        * 'ndb_restore'.
          restores 'NDB' tables.

        * Files copied at the file system level can be copied back to
          their original locations with file system commands.

Logical backup methods have these characteristics:

   * The backup is done by querying the MySQL server to obtain database
     structure and content information.

   * Backup is slower than physical methods because the server must
     access database information and convert it to logical format.  If
     the output is written on the client side, the server must also send
     it to the backup program.

   * Output is larger than for physical backup, particularly when saved
     in text format.

   * Backup and restore granularity is available at the server level
     (all databases), database level (all tables in a particular
     database), or table level.  This is true regardless of storage
     engine.

   * The backup does not include log or configuration files, or other
     database-related files that are not part of databases.

   * Backups stored in logical format are machine independent and highly
     portable.

   * Logical backups are performed with the MySQL server running.  The
     server is not taken offline.

   * Logical backup tools include the 'mysqldump'.
     program and the 'SELECT ... INTO OUTFILE' statement.
     These work for any storage engine, even 'MEMORY'.

   * To restore logical backups, SQL-format dump files can be processed
     using the 'mysql' client.  To load delimited-text
     files, use the 'LOAD DATA INFILE' statement or
     the 'mysqlimport' client.

*Online Versus Offline Backups*

Online backups take place while the MySQL server is running so that the
database information can be obtained from the server.  Offline backups
take place while the server is stopped.  This distinction can also be
described as 'hot' versus 'cold' backups; a 'warm' backup is one where
the server remains running but locked against modifying data while you
access database files externally.

Online backup methods have these characteristics:

   * The backup is less intrusive to other clients, which can connect to
     the MySQL server during the backup and may be able to access data
     depending on what operations they need to perform.

   * Care must be taken to impose appropriate locking so that data
     modifications do not take place that would compromise backup
     integrity.  The MySQL Enterprise Backup product does such locking
     automatically.

Offline backup methods have these characteristics:

   * Clients can be affected adversely because the server is unavailable
     during backup.  For that reason, such backups are often taken from
     a replication slave server that can be taken offline without
     harming availability.

   * The backup procedure is simpler because there is no possibility of
     interference from client activity.

A similar distinction between online and offline applies for recovery
operations, and similar characteristics apply.  However, it is more
likely that clients will be affected for online recovery than for online
backup because recovery requires stronger locking.  During backup,
clients might be able to read data while it is being backed up.
Recovery modifies data and does not just read it, so clients must be
prevented from accessing data while it is being restored.

*Local Versus Remote Backups*

A local backup is performed on the same host where the MySQL server
runs, whereas a remote backup is done from a different host.  For some
types of backups, the backup can be initiated from a remote host even if
the output is written locally on the server.  host.

   * 'mysqldump' can connect to local or remote
     servers.  For SQL output ('CREATE' and 'INSERT'.
     statements), local or remote dumps can be done and generate output
     on the client.  For delimited-text output (with the '--tab'
     option), data files are created on the server host.

   * 'SELECT ... INTO OUTFILE' can be initiated from
     a local or remote client host, but the output file is created on
     the server host.

   * Physical backup methods typically are initiated locally on the
     MySQL server host so that the server can be taken offline, although
     the destination for copied files might be remote.

*Snapshot Backups*

Some file system implementations enable 'snapshots' to be taken.  These
provide logical copies of the file system at a given point in time,
without requiring a physical copy of the entire file system.  (For
example, the implementation may use copy-on-write techniques so that
only parts of the file system modified after the snapshot time need be
copied.)  MySQL itself does not provide the capability for taking file
system snapshots.  It is available through third-party solutions such as
Veritas, LVM, or ZFS.

*Full Versus Incremental Backups*

A full backup includes all data managed by a MySQL server at a given
point in time.  An incremental backup consists of the changes made to
the data during a given time span (from one point in time to another).
MySQL has different ways to perform full backups, such as those
described earlier in this section.  Incremental backups are made
possible by enabling the server's binary log, which the server uses to
record data changes.

*Full Versus Point-in-Time (Incremental) Recovery*

A full recovery restores all data from a full backup.  This restores the
server instance to the state that it had when the backup was made.  If
that state is not sufficiently current, a full recovery can be followed
by recovery of incremental backups made since the full backup, to bring
the server to a more up-to-date state.

Incremental recovery is recovery of changes made during a given time
span.  This is also called point-in-time recovery because it makes a
server's state current up to a given time.  Point-in-time recovery is
based on the binary log and typically follows a full recovery from the
backup files that restores the server to its state when the backup was
made.  Then the data changes written in the binary log files are applied
as incremental recovery to redo data modifications and bring the server
up to the desired point in time.

*Table Maintenance*

Data integrity can be compromised if tables become corrupt.  For
'InnoDB' tables, this is not a typical issue.
For programs to check 'MyISAM' tables and
repair them if problems are found, see myisam-table-maintenance.

*Backup Scheduling, Compression, and Encryption*

Backup scheduling is valuable for automating backup procedures.
Compression of backup output reduces space requirements, and encryption
of the output provides better security against unauthorized access of
backed-up data.  MySQL itself does not provide these capabilities.  The
MySQL Enterprise Backup product can compress 'InnoDB' backups, and
compression or encryption of backup output can be achieved using file
system utilities.  Other third-party solutions may be available.

7.2 Database Backup Methods
===========================

This section summarizes some general methods for making backups.

*Making a Hot Backup with MySQL Enterprise Backup*

Customers of MySQL Enterprise Edition can use the MySQL Enterprise
Backup product to do physical backups of entire instances or selected
databases, tables, or both.  This product includes features for
incremental and compressed backups.  Backing up the physical database
files makes restore much faster than logical techniques such as the
'mysqldump' command.  'InnoDB' tables are copied using a hot backup
mechanism.  (Ideally, the 'InnoDB' tables should represent a substantial
majority of the data.)  Tables from other storage engines are copied
using a warm backup mechanism.  For an overview of the MySQL Enterprise
Backup product, see mysql-enterprise-backup.

*Making Backups with mysqldump*

The 'mysqldump' program can make backups.  It can back
up all kinds of tables.  (See using-mysqldump.)

For 'InnoDB' tables, it is possible to perform an online backup that
takes no locks on tables using the '--single-transaction' option to
'mysqldump'.  See backup-policy.

*Making Backups by Copying Table Files*

For storage engines that represent each table using its own files,
tables can be backed up by copying those files.  For example, 'MyISAM'
tables are stored as files, so it is easy to do a backup by copying
files ('*.frm', '*.MYD', and '*.MYI' files).  To get a consistent
backup, stop the server or lock and flush the relevant tables:

     FLUSH TABLES TBL_LIST WITH READ LOCK;

You need only a read lock; this enables other clients to continue to
query the tables while you are making a copy of the files in the
database directory.  The flush is needed to ensure that the all active
index pages are written to disk before you start the backup.  See
lock-tables, and flush.

You can also create a binary backup simply by copying all table files,
as long as the server isn't updating anything.  (But note that table
file copying methods do not work if your database contains 'InnoDB'
tables.  Also, even if the server is not actively updating data,
'InnoDB' may still have modified data cached in memory and not flushed
to disk.)

*Making Delimited-Text File Backups*

To create a text file containing a table's data, you can use
'SELECT * INTO OUTFILE 'FILE_NAME' FROM TBL_NAME'.  The
file is created on the MySQL server host, not the client host.  For this
statement, the output file cannot already exist because permitting files
to be overwritten constitutes a security risk.  See select.
This method works for any kind of data file, but saves only table data,
not the table structure.

Another way to create text data files (along with files containing
'CREATE TABLE' statements for the backed up tables) is to
use 'mysqldump' with the '--tab' option.  See
mysqldump-delimited-text.

To reload a delimited-text data file, use 'LOAD DATA INFILE'
or 'mysqlimport'.

*Making Incremental Backups by Enabling the Binary Log*

MySQL supports incremental backups: You must start the server with the
'--log-bin' option to enable binary logging; see binary-log.
The binary log files provide you with the information you need to
replicate changes to the database that are made subsequent to the point
at which you performed a backup.  At the moment you want to make an
incremental backup (containing all changes that happened since the last
full or incremental backup), you should rotate the binary log by using
'FLUSH LOGS'.  This done, you need to copy to the backup location all
binary logs which range from the one of the moment of the last full or
incremental backup to the last but one.  These binary logs are the
incremental backup; at restore time, you apply them as explained in
point-in-time-recovery.  The next time you do a full backup, you
should also rotate the binary log using 'FLUSH LOGS' or 'mysqldump --flush-logs'.
See mysqldump.

*Making Backups Using Replication Slaves*

If you have performance problems with your master server while making
backups, one strategy that can help is to set up replication and perform
backups on the slave rather than on the master.  See
replication-solutions-backups.

If you are backing up a slave replication server, you should back up its
master info and relay log info repositories (see slave-logs)
when you back up the slave's databases, regardless of the backup method
you choose.  These information files are always needed to resume
replication after you restore the slave's data.  If your slave is
replicating 'LOAD DATA INFILE' statements, you should
also back up any 'SQL_LOAD-*' files that exist in the directory that the
slave uses for this purpose.  The slave needs these files to resume
replication of any interrupted 'LOAD DATA INFILE'.
operations.  The location of this directory is the value of the
'--slave-load-tmpdir' option.  If the server was not started with that
option, the directory location is the value of the 'tmpdir' system
variable.

*Recovering Corrupt Tables*

If you have to restore 'MyISAM' tables that have become corrupt, try to
recover them using 'REPAIR TABLE' or
'myisamchk -r' first.  That should work in 99.9% of all
cases.  If 'myisamchk' fails, see
myisam-table-maintenance.

*Making Backups Using a File System Snapshot*

If you are using a Veritas file system, you can make a backup like this:

  1. From a client program, execute 'FLUSH TABLES WITH READ LOCK'.

  2. From another shell, execute 'mount vxfs snapshot'.

  3. From the first client, execute 'UNLOCK TABLES'.

  4. Copy files from the snapshot.

  5. Unmount the snapshot.

Similar snapshot capabilities may be available in other file systems,
such as LVM or ZFS.

7.3 Example Backup and Recovery Strategy
========================================

This section discusses a procedure for performing backups that enables
you to recover data after several types of crashes:

   * Operating system crash

   * Power failure

   * File system crash

   * Hardware problem (hard drive, motherboard, and so forth)

The example commands do not include options such as '--user' and
'--password' for the 'mysqldump' and 'mysql'
client programs.  You should include such options as necessary to
enable client programs to connect to the MySQL server.

Assume that data is stored in the 'InnoDB' storage engine, which has
support for transactions and automatic crash recovery.  Assume also that
the MySQL server is under load at the time of the crash.  If it were
not, no recovery would ever be needed.

For cases of operating system crashes or power failures, we can assume
that MySQL's disk data is available after a restart.  The 'InnoDB' data
files might not contain consistent data due to the crash, but 'InnoDB'
reads its logs and finds in them the list of pending committed and
noncommitted transactions that have not been flushed to the data files.
'InnoDB' automatically rolls back those transactions that were not
committed, and flushes to its data files those that were committed.
Information about this recovery process is conveyed to the user through
the MySQL error log.  The following is an example log excerpt:

     InnoDB: Database was not shut down normally.
     InnoDB: Starting recovery from log files...
     InnoDB: Starting log scan based on checkpoint at
     InnoDB: log sequence number 0 13674004
     InnoDB: Doing recovery: scanned up to log sequence number 0 13739520
     InnoDB: Doing recovery: scanned up to log sequence number 0 13805056
     InnoDB: Doing recovery: scanned up to log sequence number 0 13870592
     InnoDB: Doing recovery: scanned up to log sequence number 0 13936128
     ...
     InnoDB: Doing recovery: scanned up to log sequence number 0 20555264
     InnoDB: Doing recovery: scanned up to log sequence number 0 20620800
     InnoDB: Doing recovery: scanned up to log sequence number 0 20664692
     InnoDB: 1 uncommitted transaction(s) which must be rolled back
     InnoDB: Starting rollback of uncommitted transactions
     InnoDB: Rolling back trx no 16745
     InnoDB: Rolling back of trx no 16745 completed
     InnoDB: Rollback of uncommitted transactions completed
     InnoDB: Starting an apply batch of log records to the database...
     InnoDB: Apply batch completed
     InnoDB: Started
     mysqld: ready for connections

For the cases of file system crashes or hardware problems, we can assume
that the MySQL disk data is _not_ available after a restart.  This means
that MySQL fails to start successfully because some blocks of disk data
are no longer readable.  In this case, it is necessary to reformat the
disk, install a new one, or otherwise correct the underlying problem.
Then it is necessary to recover our MySQL data from backups, which means
that backups must already have been made.  To make sure that is the
case, design and implement a backup policy.

7.3.1 Establishing a Backup Policy
----------------------------------

To be useful, backups must be scheduled regularly.  A full backup (a
snapshot of the data at a point in time) can be done in MySQL with
several tools.  For example, see MySQL Enterprise Backup
can perform a physical backup of an entire
instance, with optimizations to minimize overhead and avoid disruption
when backing up 'InnoDB' data files; see 'mysqldump'.
provides online logical backup.  This discussion uses 'mysqldump'.

Assume that we make a full backup of all our 'InnoDB' tables in all
databases using the following command on Sunday at 1 p.m., when load is
low:

     shell> mysqldump --all-databases --master-data --single-transaction > backup_sunday_1_PM.sql

The resulting '.sql' file produced by 'mysqldump'.
contains a set of SQL 'INSERT' statements that can be
used to reload the dumped tables at a later time.

This backup operation acquires a global read lock on all tables at the
beginning of the dump (using 'FLUSH TABLES WITH READ LOCK').  As soon as
this lock has been acquired, the binary log coordinates are read and the
lock is released.  If long updating statements are running when the
'FLUSH' statement is issued, the backup operation may
stall until those statements finish.  After that, the dump becomes
lock-free and does not disturb reads and writes on the tables.

It was assumed earlier that the tables to back up are 'InnoDB' tables,
so '--single-transaction' uses a consistent read and guarantees that
data seen by 'mysqldump' does not change.  (Changes
made by other clients to 'InnoDB' tables are not seen by the
'mysqldump' process.)  If the backup operation includes
nontransactional tables, consistency requires that they do not change
during the backup.  For example, for the 'MyISAM' tables in the 'mysql'
database, there must be no administrative changes to MySQL accounts
during the backup.

Full backups are necessary, but it is not always convenient to create
them.  They produce large backup files and take time to generate.  They
are not optimal in the sense that each successive full backup includes
all data, even that part that has not changed since the previous full
backup.  It is more efficient to make an initial full backup, and then
to make incremental backups.  The incremental backups are smaller and
take less time to produce.  The tradeoff is that, at recovery time, you
cannot restore your data just by reloading the full backup.  You must
also process the incremental backups to recover the incremental changes.

To make incremental backups, we need to save the incremental changes.
In MySQL, these changes are represented in the binary log, so the MySQL
server should always be started with the '--log-bin' option to enable
that log.  With binary logging enabled, the server writes each data
change into a file while it updates data.  Looking at the data directory
of a MySQL server that was started with the '--log-bin' option and that
has been running for some days, we find these MySQL binary log files:

     -rw-rw---- 1 guilhem  guilhem   1277324 Nov 10 23:59 gbichot2-bin.000001
     -rw-rw---- 1 guilhem  guilhem         4 Nov 10 23:59 gbichot2-bin.000002
     -rw-rw---- 1 guilhem  guilhem        79 Nov 11 11:06 gbichot2-bin.000003
     -rw-rw---- 1 guilhem  guilhem       508 Nov 11 11:08 gbichot2-bin.000004
     -rw-rw---- 1 guilhem  guilhem 220047446 Nov 12 16:47 gbichot2-bin.000005
     -rw-rw---- 1 guilhem  guilhem    998412 Nov 14 10:08 gbichot2-bin.000006
     -rw-rw---- 1 guilhem  guilhem       361 Nov 14 10:07 gbichot2-bin.index

Each time it restarts, the MySQL server creates a new binary log file
using the next number in the sequence.  While the server is running, you
can also tell it to close the current binary log file and begin a new
one manually by issuing a 'FLUSH LOGS' SQL statement or with a
'mysqladmin flush-logs' command.  'mysqldump'
also has an option to flush the logs.  The '.index' file in
the data directory contains the list of all MySQL binary logs in the
directory.

The MySQL binary logs are important for recovery because they form the
set of incremental backups.  If you make sure to flush the logs when you
make your full backup, the binary log files created afterward contain
all the data changes made since the backup.  Let's modify the previous
'mysqldump' command a bit so that it flushes the MySQL
binary logs at the moment of the full backup, and so that the dump file
contains the name of the new current binary log:

     shell> mysqldump --single-transaction --flush-logs --master-data=2 \
              --all-databases > backup_sunday_1_PM.sql

After executing this command, the data directory contains a new binary
log file, 'gbichot2-bin.000007', because the '--flush-logs' option
causes the server to flush its logs.  The '--master-data' option causes
'mysqldump' to write binary log information to its
output, so the resulting '.sql' dump file includes these lines:

     -- Position to start replication or point-in-time recovery from
     -- CHANGE MASTER TO MASTER_LOG_FILE='gbichot2-bin.000007',MASTER_LOG_POS=4;

Because the 'mysqldump' command made a full backup,
those lines mean two things:

   * The dump file contains all changes made before any changes written
     to the 'gbichot2-bin.000007' binary log file or higher.

   * All data changes logged after the backup are not present in the
     dump file, but are present in the 'gbichot2-bin.000007' binary log
     file or higher.

On Monday at 1 p.m., we can create an incremental backup by flushing the
logs to begin a new binary log file.  For example, executing a
'mysqladmin flush-logs' command creates
'gbichot2-bin.000008'.  All changes between the Sunday 1 p.m.  full
backup and Monday 1 p.m.  will be in the 'gbichot2-bin.000007' file.
This incremental backup is important, so it is a good idea to copy it to
a safe place.  (For example, back it up on tape or DVD, or copy it to
another machine.)  On Tuesday at 1 p.m., execute another
'mysqladmin flush-logs' command.  All changes between
Monday 1 p.m.  and Tuesday 1 p.m.  will be in the 'gbichot2-bin.000008'
file (which also should be copied somewhere safe).

The MySQL binary logs take up disk space.  To free up space, purge them
from time to time.  One way to do this is by deleting the binary logs
that are no longer needed, such as when we make a full backup:

     shell> mysqldump --single-transaction --flush-logs --master-data=2 \
              --all-databases --delete-master-logs > backup_sunday_1_PM.sql

*Note*:

Deleting the MySQL binary logs with 'mysqldump --delete-master-logs'
can be dangerous if your server is a
replication master server, because slave servers might not yet fully
have processed the contents of the binary log.  The description for the
'PURGE BINARY LOGS' statement explains what
should be verified before deleting the MySQL binary logs.  See
purge-binary-logs.

7.3.2 Using Backups for Recovery
--------------------------------

Now, suppose that we have a catastrophic crash on Wednesday at 8 a.m.
that requires recovery from backups.  To recover, first we restore the
last full backup we have (the one from Sunday 1 p.m.).  The full backup
file is just a set of SQL statements, so restoring it is very easy:

     shell> mysql < backup_sunday_1_PM.sql

At this point, the data is restored to its state as of Sunday 1 p.m..
To restore the changes made since then, we must use the incremental
backups; that is, the 'gbichot2-bin.000007' and 'gbichot2-bin.000008'
binary log files.  Fetch the files if necessary from where they were
backed up, and then process their contents like this:

     shell> mysqlbinlog gbichot2-bin.000007 gbichot2-bin.000008 | mysql

We now have recovered the data to its state as of Tuesday 1 p.m., but
still are missing the changes from that date to the date of the crash.
To not lose them, we would have needed to have the MySQL server store
its MySQL binary logs into a safe location (RAID disks, SAN, ...)
different from the place where it stores its data files, so that these
logs were not on the destroyed disk.  (That is, we can start the server
with a '--log-bin' option that specifies a location on a different
physical device from the one on which the data directory resides.  That
way, the logs are safe even if the device containing the directory is
lost.)  If we had done this, we would have the 'gbichot2-bin.000009'
file (and any subsequent files) at hand, and we could apply them using
'mysqlbinlog' and 'mysql' to restore
the most recent data changes with no loss up to the moment of the crash:

     shell> mysqlbinlog gbichot2-bin.000009 ... | mysql

For more information about using 'mysqlbinlog' to
process binary log files, see point-in-time-recovery.

7.3.3 Backup Strategy Summary
-----------------------------

In case of an operating system crash or power failure, 'InnoDB' itself
does all the job of recovering data.  But to make sure that you can
sleep well, observe the following guidelines:

   * Always run the MySQL server with the '--log-bin' option, or even
     '--log-bin=LOG_NAME', where the log file name is located on some
     safe media different from the drive on which the data directory is
     located.  If you have such safe media, this technique can also be
     good for disk load balancing (which results in a performance
     improvement).

   * Make periodic full backups, using the 'mysqldump'.
     command shown earlier in backup-policy, that makes an
     online, nonblocking backup.

   * Make periodic incremental backups by flushing the logs with 'FLUSH
     LOGS' or 'mysqladmin flush-logs'.

7.4 Using mysqldump for Backups
===============================

This section describes how to use 'mysqldump' to
produce dump files, and how to reload dump files.  A dump file can be
used in several ways:

   * As a backup to enable data recovery in case of data loss.

   * As a source of data for setting up replication slaves.

   * As a source of data for experimentation:

        * To make a copy of a database that you can use without changing
          the original data.

        * To test potential upgrade incompatibilities.

'mysqldump' produces two types of output, depending on
whether the '--tab' option is given:

   * Without '--tab', see 'mysqldump' writes SQL
     statements to the standard output.  This output consists of
     'CREATE' statements to create dumped objects (databases, tables,
     stored routines, and so forth), and 'INSERT' statements to load
     data into tables.  The output can be saved in a file and reloaded
     later using 'mysql' to recreate the dumped objects.
     Options are available to modify the format of the SQL statements,
     and to control which objects are dumped.

   * With '--tab', see 'mysqldump' produces two output
     files for each dumped table.  The server writes one file as
     tab-delimited text, one line per table row.  This file is named
     'TBL_NAME.txt' in the output directory.  The server also sends a
     'CREATE TABLE' statement for the table to
     'mysqldump', which writes it as a file named
     'TBL_NAME.sql' in the output directory.

7.4.1 Dumping Data in SQL Format with mysqldump
-----------------------------------------------

This section describes how to use 'mysqldump' to
create SQL-format dump files.  For information about reloading such dump
files, see reloading-sql-format-dumps.

By default, see 'mysqldump' writes information as SQL
statements to the standard output.  You can save the output in a file:

     shell> mysqldump [ARGUMENTS] > FILE_NAME

To dump all databases, invoke 'mysqldump' with the
'--all-databases' option:

     shell> mysqldump --all-databases > dump.sql

To dump only specific databases, name them on the command line and use
the '--databases' option:

     shell> mysqldump --databases db1 db2 db3 > dump.sql

The '--databases' option causes all names on the command line to be
treated as database names.  Without this option, see 'mysqldump'
treats the first name as a database name and those following
as table names.

With '--all-databases' or '--databases', see 'mysqldump'.
writes 'CREATE DATABASE' and 'USE'.
statements prior to the dump output for each database.  This ensures
that when the dump file is reloaded, it creates each database if it does
not exist and makes it the default database so database contents are
loaded into the same database from which they came.  If you want to
cause the dump file to force a drop of each database before recreating
it, use the '--add-drop-database' option as well.  In this case, see
'mysqldump' writes a 'DROP DATABASE'.
statement preceding each 'CREATE DATABASE'.
statement.

To dump a single database, name it on the command line:

     shell> mysqldump --databases test > dump.sql

In the single-database case, it is permissible to omit the '--databases'
option:

     shell> mysqldump test > dump.sql

The difference between the two preceding commands is that without
'--databases', the dump output contains no 'CREATE DATABASE'
or 'USE' statements.  This has several
implications:

   * When you reload the dump file, you must specify a default database
     name so that the server knows which database to reload.

   * For reloading, you can specify a database name different from the
     original name, which enables you to reload the data into a
     different database.

   * If the database to be reloaded does not exist, you must create it
     first.

   * Because the output will contain no 'CREATE DATABASE'
     statement, the '--add-drop-database' option has no
     effect.  If you use it, it produces no 'DROP DATABASE'
     statement.

To dump only specific tables from a database, name them on the command
line following the database name:

     shell> mysqldump test t1 t3 t7 > dump.sql

7.4.2 Reloading SQL-Format Backups
----------------------------------

To reload a dump file written by 'mysqldump' that
consists of SQL statements, use it as input to the 'mysql'.
client.  If the dump file was created by 'mysqldump'.
with the '--all-databases' or '--databases' option, it contains
'CREATE DATABASE' and 'USE' statements and
it is not necessary to specify a default database into which to load the
data:

     shell> mysql < dump.sql

Alternatively, from within 'mysql', use a 'source' command:

     mysql> source dump.sql

If the file is a single-database dump not containing 'CREATE DATABASE'
and 'USE' statements, create the
database first (if necessary):

     shell> mysqladmin create db1

Then specify the database name when you load the dump file:

     shell> mysql db1 < dump.sql

Alternatively, from within 'mysql', create the database,
select it as the default database, and load the dump file:

     mysql> CREATE DATABASE IF NOT EXISTS db1;
     mysql> USE db1;
     mysql> source dump.sql

*Note*:

For Windows PowerShell users: Because the "<" character is reserved for
future use in PowerShell, an alternative approach is required, such as
using quotes 'cmd.exe /c "mysql < dump.sql"'.

7.4.3 Dumping Data in Delimited-Text Format with mysqldump
----------------------------------------------------------

This section describes how to use 'mysqldump' to
create delimited-text dump files.  For information about reloading such
dump files, see reloading-delimited-text-dumps.

If you invoke 'mysqldump' with the '--tab=DIR_NAME'
option, it uses DIR_NAME as the output directory and dumps tables
individually in that directory using two files for each table.  The
table name is the base name for these files.  For a table named 't1',
the files are named 't1.sql' and 't1.txt'.  The '.sql' file contains a
'CREATE TABLE' statement for the table.  The '.txt'
file contains the table data, one line per table row.

The following command dumps the contents of the 'db1' database to files
in the '/tmp' database:

     shell> mysqldump --tab=/tmp db1

The '.txt' files containing table data are written by the server, so
they are owned by the system account used for running the server.  The
server uses 'SELECT ... INTO OUTFILE' to write the
files, so you must have the 'FILE' privilege to perform this operation,
and an error occurs if a given '.txt' file already exists.

The server sends the 'CREATE' definitions for dumped tables to
'mysqldump', which writes them to '.sql' files.  These files
therefore are owned by the user who executes 'mysqldump'.

It is best that '--tab' be used only for dumping a local server.  If you
use it with a remote server, the '--tab' directory must exist on both
the local and remote hosts, and the '.txt' files will be written by the
server in the remote directory (on the server host), whereas the '.sql'
files will be written by 'mysqldump' in the local
directory (on the client host).

For 'mysqldump --tab', the server by default writes
table data to '.txt' files one line per row with tabs between column
values, no quotation marks around column values, and newline as the line
terminator.  (These are the same defaults as for 'SELECT ... INTO OUTFILE')

To enable data files to be written using a different format, see
'mysqldump' supports these options:

   * '--fields-terminated-by=STR'

     The string for separating column values (default: tab).

   * '--fields-enclosed-by=CHAR'

     The character within which to enclose column values (default: no
     character).

   * '--fields-optionally-enclosed-by=CHAR'

     The character within which to enclose non-numeric column values
     (default: no character).

   * '--fields-escaped-by=CHAR'

     The character for escaping special characters (default: no
     escaping).

   * '--lines-terminated-by=STR'

     The line-termination string (default: newline).

Depending on the value you specify for any of these options, it might be
necessary on the command line to quote or escape the value appropriately
for your command interpreter.  Alternatively, specify the value using
hex notation.  Suppose that you want 'mysqldump' to
quote column values within double quotation marks.  To do so, specify
double quote as the value for the '--fields-enclosed-by' option.  But
this character is often special to command interpreters and must be
treated specially.  For example, on Unix, you can quote the double quote
like this:

     --fields-enclosed-by='"'

On any platform, you can specify the value in hex:

     --fields-enclosed-by=0x22

It is common to use several of the data-formatting options together.
For example, to dump tables in comma-separated values format with lines
terminated by carriage-return/newline pairs ('\r\n'), use this command
(enter it on a single line):

     shell> mysqldump --tab=/tmp --fields-terminated-by=,
              --fields-enclosed-by='"' --lines-terminated-by=0x0d0a db1

Should you use any of the data-formatting options to dump table data,
you will need to specify the same format when you reload data files
later, to ensure proper interpretation of the file contents.

7.4.4 Reloading Delimited-Text Format Backups
---------------------------------------------

For backups produced with 'mysqldump --tab', each table
is represented in the output directory by an '.sql' file containing the
'CREATE TABLE' statement for the table, and a
'.txt' file containing the table data.  To reload a table, first change
location into the output directory.  Then process the '.sql' file with
'mysql' to create an empty table and process the '.txt'
file to load the data into the table:

     shell> mysql db1 < t1.sql
     shell> mysqlimport db1 t1.txt

An alternative to using 'mysqlimport' to load the
data file is to use the 'LOAD DATA INFILE' statement
from within the 'mysql' client:

     mysql> USE db1;
     mysql> LOAD DATA INFILE 't1.txt' INTO TABLE t1;

If you used any data-formatting options with 'mysqldump'
when you initially dumped the table, you must use the same
options with 'mysqlimport' or 'LOAD DATA INFILE'
to ensure proper interpretation of the data file
contents:

     shell> mysqlimport --fields-terminated-by=,
              --fields-enclosed-by='"' --lines-terminated-by=0x0d0a db1 t1.txt

Or:

     mysql> USE db1;
     mysql> LOAD DATA INFILE 't1.txt' INTO TABLE t1
         -> FIELDS TERMINATED BY ',' FIELDS ENCLOSED BY '"'
         -> LINES TERMINATED BY '\r\n';

7.4.5 mysqldump Tips
--------------------

This section surveys techniques that enable you to use
'mysqldump' to solve specific problems:

   * How to make a copy a database

   * How to copy a database from one server to another

   * How to dump stored programs (stored procedures and functions,
     triggers, and events)

   * How to dump definitions and data separately

7.4.5.1 Making a Copy of a Database
...................................

     shell> mysqldump db1 > dump.sql
     shell> mysqladmin create db2
     shell> mysql db2 < dump.sql

Do not use '--databases' on the 'mysqldump' command
line because that causes 'USE db1' to be included in the dump file,
which overrides the effect of naming 'db2' on the 'mysql'.
command line.

7.4.5.2 Copy a Database from one Server to Another
..................................................

On Server 1:

     shell> mysqldump --databases db1 > dump.sql

Copy the dump file from Server 1 to Server 2.

On Server 2:

     shell> mysql < dump.sql

Use of '--databases' with the 'mysqldump' command line
causes the dump file to include 'CREATE DATABASE'
and 'USE' statements that create the
database if it does exist and make it the default database for the
reloaded data.

Alternatively, you can omit '--databases' from the 'mysqldump'
command.  Then you will need to create the database on Server
2 (if necessary) and specify it as the default database when you reload
the dump file.

On Server 1:

     shell> mysqldump db1 > dump.sql

On Server 2:

     shell> mysqladmin create db1
     shell> mysql db1 < dump.sql

You can specify a different database name in this case, so omitting
'--databases' from the 'mysqldump' command enables you
to dump data from one database and load it into another.

7.4.5.3 Dumping Stored Programs
...............................

Several options control how 'mysqldump' handles stored
programs (stored procedures and functions, triggers, and events):

   * '--events': Dump Event Scheduler events

   * '--routines': Dump stored procedures and functions

   * '--triggers': Dump triggers for tables

The '--triggers' option is enabled by default so that when tables are
dumped, they are accompanied by any triggers they have.  The other
options are disabled by default and must be specified explicitly to dump
the corresponding objects.  To disable any of these options explicitly,
use its skip form: '--skip-events', '--skip-routines', or
'--skip-triggers'.

7.4.5.4 Dumping Table Definitions and Content Separately
........................................................

The '--no-data' option tells 'mysqldump' not to dump
table data, resulting in the dump file containing only statements to
create the tables.  Conversely, the '--no-create-info' option tells
'mysqldump' to suppress 'CREATE' statements from the
output, so that the dump file contains only table data.

For example, to dump table definitions and data separately for the
'test' database, use these commands:

     shell> mysqldump --no-data test > dump-defs.sql
     shell> mysqldump --no-create-info test > dump-data.sql

For a definition-only dump, add the '--routines' and '--events' options
to also include stored routine and event definitions:

     shell> mysqldump --no-data --routines --events test > dump-defs.sql

7.4.5.5 Using mysqldump to Test for Upgrade Incompatibilities
.............................................................

When contemplating a MySQL upgrade, it is prudent to install the newer
version separately from your current production version.  Then you can
dump the database and database object definitions from the production
server and load them into the new server to verify that they are handled
properly.  (This is also useful for testing downgrades.)

On the production server:

     shell> mysqldump --all-databases --no-data --routines --events > dump-defs.sql

On the upgraded server:

     shell> mysql < dump-defs.sql

Because the dump file does not contain table data, it can be processed
quickly.  This enables you to spot potential incompatibilities without
waiting for lengthy data-loading operations.  Look for warnings or
errors while the dump file is being processed.

After you have verified that the definitions are handled properly, dump
the data and try to load it into the upgraded server.

On the production server:

     shell> mysqldump --all-databases --no-create-info > dump-data.sql

On the upgraded server:

     shell> mysql < dump-data.sql

Now check the table contents and run some test queries.

7.5 Point-in-Time (Incremental) Recovery Using the Binary Log
=============================================================

Point-in-time recovery refers to recovery of data changes made since a
given point in time.  Typically, this type of recovery is performed
after restoring a full backup that brings the server to its state as of
the time the backup was made.  (The full backup can be made in several
ways, such as those listed in backup-methods.)  Point-in-time
recovery then brings the server up to date incrementally from the time
of the full backup to a more recent time.

*Note*:

Many of the examples here use the 'mysql' client to
process binary log output produced by 'mysqlbinlog'.
If your binary log contains '\0' (null) characters, that output cannot
be parsed by 'mysql' unless you invoke it with the
'--binary-mode' option.

Point-in-time recovery is based on these principles:

   * The source of information for point-in-time recovery is the set of
     incremental backups represented by the binary log files generated
     subsequent to the full backup operation.  Therefore, the server
     must be started with the '--log-bin' option to enable binary
     logging (see binary-log).

     To restore data from the binary log, you must know the name and
     location of the current binary log files.  By default, the server
     creates binary log files in the data directory, but a path name can
     be specified with the '--log-bin' option to place the files in a
     different location.  See binary-log.

     To see a listing of all binary log files, use this statement:

          mysql> SHOW BINARY LOGS;

     To determine the name of the current binary log file, issue the
     following statement:

          mysql> SHOW MASTER STATUS;

   * The 'mysqlbinlog' utility converts the events
     in the binary log files from binary format to text so that they can
     be executed or viewed.  'mysqlbinlog' has
     options for selecting sections of the binary log based on event
     times or position of events within the log.  See
     mysqlbinlog.

   * Executing events from the binary log causes the data modifications
     they represent to be redone.  This enables recovery of data changes
     for a given span of time.  To execute events from the binary log,
     process 'mysqlbinlog' output using the
     'mysql' client:

          shell> mysqlbinlog BINLOG_FILES | mysql -u root -p

   * Viewing log contents can be useful when you need to determine event
     times or positions to select partial log contents prior to
     executing events.  To view events from the log, send
     'mysqlbinlog' output into a paging program:

          shell> mysqlbinlog BINLOG_FILES | more

     Alternatively, save the output in a file and view the file in a
     text editor:

          shell> mysqlbinlog BINLOG_FILES > tmpfile
          shell> ... EDIT TMPFILE ...

   * Saving the output in a file is useful as a preliminary to executing
     the log contents with certain events removed, such as an accidental
     'DROP DATABASE'.  You can delete from the file
     any statements not to be executed before executing its contents.
     After editing the file, execute the contents as follows:

          shell> mysql -u root -p < tmpfile

If you have more than one binary log to execute on the MySQL server, the
safe method is to process them all using a single connection to the
server.  Here is an example that demonstrates what may be _unsafe_:

     shell> mysqlbinlog binlog.000001 | mysql -u root -p # DANGER!!
     shell> mysqlbinlog binlog.000002 | mysql -u root -p # DANGER!!

Processing binary logs this way using different connections to the
server causes problems if the first log file contains a 'CREATE TEMPORARY TABLE'
statement and the second log contains a
statement that uses the temporary table.  When the first 'mysql'
process terminates, the server drops the temporary table.  When
the second 'mysql' process attempts to use the table, the
server reports 'unknown table.'

To avoid problems like this, use a _single_ connection to execute the
contents of all binary logs that you want to process.  Here is one way
to do so:

     shell> mysqlbinlog binlog.000001 binlog.000002 | mysql -u root -p

Another approach is to write all the logs to a single file and then
process the file:

     shell> mysqlbinlog binlog.000001 >  /tmp/statements.sql
     shell> mysqlbinlog binlog.000002 >> /tmp/statements.sql
     shell> mysql -u root -p -e "source /tmp/statements.sql"

When writing to a dump file while reading back from a binary log
containing GTIDs (see replication-gtids), use the '--skip-gtids'
option with 'mysqlbinlog', like this:

     shell> mysqlbinlog --skip-gtids binlog.000001 >  /tmp/dump.sql
     shell> mysqlbinlog --skip-gtids binlog.000002 >> /tmp/dump.sql
     shell> mysql -u root -p -e "source /tmp/dump.sql"

7.5.1 Point-in-Time Recovery Using Event Times
----------------------------------------------

To indicate the start and end times for recovery, specify the
'--start-datetime' and '--stop-datetime' options for
'mysqlbinlog', in 'DATETIME' format.  As
an example, suppose that exactly at 10:00 a.m.  on April 20, 2005 an SQL
statement was executed that deleted a large table.  To restore the table
and data, you could restore the previous night's backup, and then
execute the following command:

     shell> mysqlbinlog --stop-datetime="2005-04-20 9:59:59" \
              /var/log/mysql/bin.123456 | mysql -u root -p

This command recovers all of the data up until the date and time given
by the '--stop-datetime' option.  If you did not detect the erroneous
SQL statement that was entered until hours later, you will probably also
want to recover the activity that occurred afterward.  Based on this,
you could run 'mysqlbinlog' again with a start date
and time, like so:

     shell> mysqlbinlog --start-datetime="2005-04-20 10:01:00" \
              /var/log/mysql/bin.123456 | mysql -u root -p

In this command, the SQL statements logged from 10:01 a.m.  on will be
re-executed.  The combination of restoring of the previous night's dump
file and the two 'mysqlbinlog' commands restores
everything up until one second before 10:00 a.m.  and everything from
10:01 a.m.  on.

To use this method of point-in-time recovery, you should examine the log
to be sure of the exact times to specify for the commands.  To display
the log file contents without executing them, use this command:

     shell> mysqlbinlog /var/log/mysql/bin.123456 > /tmp/mysql_restore.sql

Then open the '/tmp/mysql_restore.sql' file with a text editor to
examine it.

Excluding specific changes by specifying times for 'mysqlbinlog'
does not work well if multiple statements executed at the
same time as the one to be excluded.

7.5.2 Point-in-Time Recovery Using Event Positions
--------------------------------------------------

Instead of specifying dates and times, the '--start-position' and
'--stop-position' options for 'mysqlbinlog' can be
used for specifying log positions.  They work the same as the start and
stop date options, except that you specify log position numbers rather
than dates.  Using positions may enable you to be more precise about
which part of the log to recover, especially if many transactions
occurred around the same time as a damaging SQL statement.  To determine
the position numbers, run 'mysqlbinlog' for a range
of times near the time when the unwanted transaction was executed, but
redirect the results to a text file for examination.  This can be done
like so:

     shell> mysqlbinlog --start-datetime="2005-04-20 9:55:00" \
              --stop-datetime="2005-04-20 10:05:00" \
              /var/log/mysql/bin.123456 > /tmp/mysql_restore.sql

This command creates a small text file in the '/tmp' directory that
contains the SQL statements around the time that the deleterious SQL
statement was executed.  Open this file with a text editor and look for
the statement that you do not want to repeat.  Determine the positions
in the binary log for stopping and resuming the recovery and make note
of them.  Positions are labeled as 'log_pos' followed by a number.
After restoring the previous backup file, use the position numbers to
process the binary log file.  For example, you would use commands
something like these:

     shell> mysqlbinlog --stop-position=368312 /var/log/mysql/bin.123456 \
              | mysql -u root -p

     shell> mysqlbinlog --start-position=368315 /var/log/mysql/bin.123456 \
              | mysql -u root -p

The first command recovers all the transactions up until the stop
position given.  The second command recovers all transactions from the
starting position given until the end of the binary log.  Because the
output of 'mysqlbinlog' includes 'SET TIMESTAMP'
statements before each SQL statement recorded, the recovered data and
related MySQL logs will reflect the original times at which the
transactions were executed.

7.6 MyISAM Table Maintenance and Crash Recovery
===============================================

This section discusses how to use 'myisamchk' to check
or repair 'MyISAM' tables (tables that have '.MYD' and '.MYI' files for
storing data and indexes).  For general 'myisamchk'.
background, see myisamchk.  Other table-repair information can
be found at rebuilding-tables.

You can use 'myisamchk' to check, repair, or optimize
database tables.  The following sections describe how to perform these
operations and how to set up a table maintenance schedule.  For
information about using 'myisamchk' to get information
about your tables, see myisamchk-table-info.

Even though table repair with 'myisamchk' is quite
secure, it is always a good idea to make a backup _before_ doing a
repair or any maintenance operation that could make a lot of changes to
a table.

'myisamchk' operations that affect indexes can cause
'MyISAM' 'FULLTEXT' indexes to be rebuilt with full-text parameters that
are incompatible with the values used by the MySQL server.  To avoid
this problem, follow the guidelines in
myisamchk-general-options.

'MyISAM' table maintenance can also be done using the SQL statements
that perform operations similar to what 'myisamchk'.
can do:

   * To check 'MyISAM' tables, use 'CHECK TABLE'.

   * To repair 'MyISAM' tables, use 'REPAIR TABLE'.

   * To optimize 'MyISAM' tables, use 'OPTIMIZE TABLE'.

   * To analyze 'MyISAM' tables, use 'ANALYZE TABLE'.

For additional information about these statements, see
table-maintenance-sql.

These statements can be used directly or by means of the
'mysqlcheck' client program.  One advantage of these
statements over 'myisamchk' is that the server does
all the work.  With 'myisamchk', you must make sure
that the server does not use the tables at the same time so that there
is no unwanted interaction between 'myisamchk' and the
server.

7.6.1 Using myisamchk for Crash Recovery
----------------------------------------

This section describes how to check for and deal with data corruption in
MySQL databases.  If your tables become corrupted frequently, you should
try to find the reason why.  See crashing.

For an explanation of how 'MyISAM' tables can become corrupted, see
myisam-table-problems.

If you run 'mysqld' with external locking disabled (which
is the default), you cannot reliably use 'myisamchk'.
to check a table when 'mysqld' is using the same table.
If you can be certain that no one will access the tables through
'mysqld' while you run 'myisamchk', you only
have to execute 'mysqladmin flush-tables' before you
start checking the tables.  If you cannot guarantee this, you must stop
'mysqld' while you check the tables.  If you run
'myisamchk' to check tables that 'mysqld' is
updating at the same time, you may get a warning that a table is corrupt
even when it is not.

If the server is run with external locking enabled, you can use
'myisamchk' to check tables at any time.  In this case, if
the server tries to update a table that 'myisamchk' is
using, the server will wait for 'myisamchk' to finish
before it continues.

If you use 'myisamchk' to repair or optimize tables,
you _must_ always ensure that the 'mysqld' server is not
using the table (this also applies if external locking is disabled).  If
you do not stop 'mysqld', you should at least do a
'mysqladmin flush-tables' before you run 'myisamchk'.
Your tables _may become corrupted_ if the server and
'myisamchk' access the tables simultaneously.

When performing crash recovery, it is important to understand that each
'MyISAM' table TBL_NAME in a database corresponds to the three files in
the database directory shown in the following table.

File           Purpose

'TBL_NAME.frm' Definition (format) file

'TBL_NAME.MYD' Data file

'TBL_NAME.MYI' Index file

Each of these three file types is subject to corruption in various ways,
but problems occur most often in data files and index files.

'myisamchk' works by creating a copy of the '.MYD'
data file row by row.  It ends the repair stage by removing the old
'.MYD' file and renaming the new file to the original file name.  If you
use '--quick', see 'myisamchk' does not create a temporary
'.MYD' file, but instead assumes that the '.MYD' file is correct and
generates only a new index file without touching the '.MYD' file.  This
is safe, because 'myisamchk' automatically detects
whether the '.MYD' file is corrupt and aborts the repair if it is.  You
can also specify the '--quick' option twice to 'myisamchk'.
In this case, see 'myisamchk' does not abort
on some errors (such as duplicate-key errors) but instead tries to
resolve them by modifying the '.MYD' file.  Normally the use of two
'--quick' options is useful only if you have too little free disk space
to perform a normal repair.  In this case, you should at least make a
backup of the table before running 'myisamchk'.

7.6.2 How to Check MyISAM Tables for Errors
-------------------------------------------

To check a 'MyISAM' table, use the following commands:

   * 'myisamchk TBL_NAME'.

     This finds 99.99% of all errors.  What it cannot find is corruption
     that involves _only_ the data file (which is very unusual).  If you
     want to check a table, you should normally run 'myisamchk'
     without options or with the '-s' (silent) option.

   * 'myisamchk -m TBL_NAME'.

     This finds 99.999% of all errors.  It first checks all index
     entries for errors and then reads through all rows.  It calculates
     a checksum for all key values in the rows and verifies that the
     checksum matches the checksum for the keys in the index tree.

   * 'myisamchk -e TBL_NAME'.

     This does a complete and thorough check of all data ('-e' means
     'extended check').  It does a check-read of every key for each row
     to verify that they indeed point to the correct row.  This may take
     a long time for a large table that has many indexes.  Normally,
     see 'myisamchk' stops after the first error it finds.
     If you want to obtain more information, you can add the '-v'
     (verbose) option.  This causes 'myisamchk' to
     keep going, up through a maximum of 20 errors.

   * 'myisamchk -e -i TBL_NAME'.

     This is like the previous command, but the '-i' option tells
     'myisamchk' to print additional statistical
     information.

In most cases, a simple 'myisamchk' command with no
arguments other than the table name is sufficient to check a table.

7.6.3 How to Repair MyISAM Tables
---------------------------------

The discussion in this section describes how to use 'myisamchk'
on 'MyISAM' tables (extensions '.MYI' and '.MYD').

You can also use the 'CHECK TABLE' and 'REPAIR TABLE'
statements to check and repair 'MyISAM' tables.
See check-table, and repair-table.

Symptoms of corrupted tables include queries that abort unexpectedly and
observable errors such as these:

   * 'TBL_NAME.frm' is locked against change

   * Can't find file 'TBL_NAME.MYI' (Errcode: NNN)

   * Unexpected end of file

   * Record file is crashed

   * Got error NNN from table handler

To get more information about the error, run 'perror'.
NNN, where NNN is the error number.  The following example shows how to
use 'perror' to find the meanings for the most common
error numbers that indicate a problem with a table:

     shell> perror 126 127 132 134 135 136 141 144 145
     MySQL error code 126 = Index file is crashed
     MySQL error code 127 = Record-file is crashed
     MySQL error code 132 = Old database file
     MySQL error code 134 = Record was already deleted (or record file crashed)
     MySQL error code 135 = No more room in record file
     MySQL error code 136 = No more room in index file
     MySQL error code 141 = Duplicate unique key or constraint on write or update
     MySQL error code 144 = Table is crashed and last repair failed
     MySQL error code 145 = Table was marked as crashed and should be repaired

Note that error 135 (no more room in record file) and error 136 (no more
room in index file) are not errors that can be fixed by a simple repair.
In this case, you must use 'ALTER TABLE' to increase
the 'MAX_ROWS' and 'AVG_ROW_LENGTH' table option values:

     ALTER TABLE TBL_NAME MAX_ROWS=XXX AVG_ROW_LENGTH=YYY;

If you do not know the current table option values, use 'SHOW CREATE TABLE'.

For the other errors, you must repair your tables.  'myisamchk'
can usually detect and fix most problems that occur.

The repair process involves up to four stages, described here.  Before
you begin, you should change location to the database directory and
check the permissions of the table files.  On Unix, make sure that they
are readable by the user that 'mysqld' runs as (and to
you, because you need to access the files you are checking).  If it
turns out you need to modify files, they must also be writable by you.

This section is for the cases where a table check fails (such as those
described in myisam-check), or you want to use the extended
features that 'myisamchk' provides.

The 'myisamchk' options used for table maintenance
with are described in myisamchk.  See 'myisamchk'.
also has variables that you can set to control memory allocation that
may improve performance.  See myisamchk-memory.

If you are going to repair a table from the command line, you must first
stop the 'mysqld' server.  Note that when you do
'mysqladmin shutdown' on a remote server, the
'mysqld' server is still available for a while after
'mysqladmin' returns, until all statement-processing has
stopped and all index changes have been flushed to disk.

*Stage 1: Checking your tables*

Run 'myisamchk *.MYI' or 'myisamchk -e *.MYI'
if you have more time.  Use the '-s' (silent) option to
suppress unnecessary information.

If the 'mysqld' server is stopped, you should use the
'--update-state' option to tell 'myisamchk' to mark
the table as 'checked.'

You have to repair only those tables for which 'myisamchk'
announces an error.  For such tables, proceed to Stage 2.

If you get unexpected errors when checking (such as 'out of memory'
errors), or if 'myisamchk' crashes, go to Stage 3.

*Stage 2: Easy safe repair*

First, try 'myisamchk -r -q TBL_NAME'. ('-r -q' means
'quick recovery mode').  This attempts to repair the index file without
touching the data file.  If the data file contains everything that it
should and the delete links point at the correct locations within the
data file, this should work, and the table is fixed.  Start repairing
the next table.  Otherwise, use the following procedure:

  1. Make a backup of the data file before continuing.

  2. Use 'myisamchk -r TBL_NAME'. ('-r' means 'recovery
     mode').  This removes incorrect rows and deleted rows from the data
     file and reconstructs the index file.

  3. If the preceding step fails, use 'myisamchk --safe-recover TBL_NAME'.
     Safe recovery mode uses an old recovery
     method that handles a few cases that regular recovery mode does not
     (but is slower).

*Note*:

If you want a repair operation to go much faster, you should set the
values of the 'sort_buffer_size' and 'key_buffer_size' variables each to
about 25% of your available memory when running 'myisamchk'.

If you get unexpected errors when repairing (such as 'out of memory'
errors), or if 'myisamchk' crashes, go to Stage 3.

*Stage 3: Difficult repair*

You should reach this stage only if the first 16KB block in the index
file is destroyed or contains incorrect information, or if the index
file is missing.  In this case, it is necessary to create a new index
file.  Do so as follows:

  1. Move the data file to a safe place.

  2. Use the table description file to create new (empty) data and index
     files:

          shell> mysql DB_NAME

          mysql> SET autocommit=1;
          mysql> TRUNCATE TABLE TBL_NAME;
          mysql> quit

  3. Copy the old data file back onto the newly created data file.  (Do
     not just move the old file back onto the new file.  You want to
     retain a copy in case something goes wrong.)

*Important*:

If you are using replication, you should stop it prior to performing the
above procedure, since it involves file system operations, and these are
not logged by MySQL.

Go back to Stage 2.  'myisamchk -r -q' should work.
(This should not be an endless loop.)

You can also use the 'REPAIR TABLE TBL_NAME USE_FRM' SQL statement,
which performs the whole procedure automatically.  There is also no
possibility of unwanted interaction between a utility and the server,
because the server does all the work when you use 'REPAIR TABLE'.
See repair-table.

*Stage 4: Very difficult repair*

You should reach this stage only if the '.frm' description file has also
crashed.  That should never happen, because the description file is not
changed after the table is created:

  1. Restore the description file from a backup and go back to Stage 3.
     You can also restore the index file and go back to Stage 2.  In the
     latter case, you should start with 'myisamchk -r'.

  2. If you do not have a backup but know exactly how the table was
     created, create a copy of the table in another database.  Remove
     the new data file, and then move the '.frm' description and '.MYI'
     index files from the other database to your crashed database.  This
     gives you new description and index files, but leaves the '.MYD'
     data file alone.  Go back to Stage 2 and attempt to reconstruct the
     index file.

7.6.4 MyISAM Table Optimization
-------------------------------

To coalesce fragmented rows and eliminate wasted space that results from
deleting or updating rows, run 'myisamchk' in recovery
mode:

     shell> myisamchk -r TBL_NAME

You can optimize a table in the same way by using the 'OPTIMIZE TABLE'.
SQL statement.  'OPTIMIZE TABLE'
does a table repair and a key analysis, and also sorts
the index tree so that key lookups are faster.  There is also no
possibility of unwanted interaction between a utility and the server,
because the server does all the work when you use 'OPTIMIZE TABLE'.
See optimize-table.

'myisamchk' has a number of other options that you can
use to improve the performance of a table:

   * '--analyze' or '-a': Perform key distribution analysis.  This
     improves join performance by enabling the join optimizer to better
     choose the order in which to join the tables and which indexes it
     should use.

   * '--sort-index' or '-S': Sort the index blocks.  This optimizes
     seeks and makes table scans that use indexes faster.

   * '--sort-records=INDEX_NUM' or '-R INDEX_NUM': Sort data rows
     according to a given index.  This makes your data much more
     localized and may speed up range-based 'SELECT' and
     'ORDER BY' operations that use this index.

For a full description of all available options, see myisamchk.

7.6.5 Setting Up a MyISAM Table Maintenance Schedule
----------------------------------------------------

It is a good idea to perform table checks on a regular basis rather than
waiting for problems to occur.  One way to check and repair 'MyISAM'
tables is with the 'CHECK TABLE' and 'REPAIR TABLE'
statements.  See table-maintenance-sql.

Another way to check tables is to use 'myisamchk'.  For
maintenance purposes, you can use 'myisamchk -s'.  The
'-s' option (short for '--silent') causes 'myisamchk'.
to run in silent mode, printing messages only when errors occur.

It is also a good idea to enable automatic 'MyISAM' table checking.  For
example, whenever the machine has done a restart in the middle of an
update, you usually need to check each table that could have been
affected before it is used further.  (These are 'expected crashed
tables.') To cause the server to check 'MyISAM' tables automatically,
start it with the '--myisam-recover-options' option.  See
server-options.

You should also check your tables regularly during normal system
operation.  For example, you can run a 'cron' job to check important
tables once a week, using a line like this in a 'crontab' file:

     35 0 * * 0 /PATH/TO/MYISAMCHK --fast --silent /PATH/TO/DATADIR/*/*.MYI

This prints out information about crashed tables so that you can examine
and repair them as necessary.

To start with, execute 'myisamchk -s' each night on
all tables that have been updated during the last 24 hours.  As you see
that problems occur infrequently, you can back off the checking
frequency to once a week or so.

Normally, MySQL tables need little maintenance.  If you are performing
many updates to 'MyISAM' tables with dynamic-sized rows (tables with
'VARCHAR', 'BLOB', or 'TEXT'.
columns) or have tables with many deleted rows you may want to
defragment/reclaim space from the tables from time to time.  You can do
this by using 'OPTIMIZE TABLE' on the tables in
question.  Alternatively, if you can stop the 'mysqld'.
server for a while, change location into the data directory and use this
command while the server is stopped:

     shell> myisamchk -r -s --sort-index --myisam_sort_buffer_size=16M */*.MYI

8 Optimization
**************

This chapter explains how to optimize MySQL performance and provides
examples.  Optimization involves configuring, tuning, and measuring
performance, at several levels.  Depending on your job role (developer,
DBA, or a combination of both), you might optimize at the level of
individual SQL statements, entire applications, a single database
server, or multiple networked database servers.  Sometimes you can be
proactive and plan in advance for performance, while other times you
might troubleshoot a configuration or code issue after a problem occurs.
Optimizing CPU and memory usage can also improve scalability, allowing
the database to handle more load without slowing down.

8.1 Optimization Overview
=========================

Database performance depends on several factors at the database level,
such as tables, queries, and configuration settings.  These software
constructs result in CPU and I/O operations at the hardware level, which
you must minimize and make as efficient as possible.  As you work on
database performance, you start by learning the high-level rules and
guidelines for the software side, and measuring performance using
wall-clock time.  As you become an expert, you learn more about what
happens internally, and start measuring things such as CPU cycles and
I/O operations.

Typical users aim to get the best database performance out of their
existing software and hardware configurations.  Advanced users look for
opportunities to improve the MySQL software itself, or develop their own
storage engines and hardware appliances to expand the MySQL ecosystem.

   * optimize-database-level

   * optimize-hardware-level

   * optimize-portability-performance

*Optimizing at the Database Level*

The most important factor in making a database application fast is its
basic design:

   * Are the tables structured properly?  In particular, do the columns
     have the right data types, and does each table have the appropriate
     columns for the type of work?  For example, applications that
     perform frequent updates often have many tables with few columns,
     while applications that analyze large amounts of data often have
     few tables with many columns.

   * Are the right indexes in place to make
     queries efficient?

   * Are you using the appropriate storage engine for each table, and
     taking advantage of the strengths and features of each storage
     engine you use?  In particular, the choice of a transactional
     storage engine such as 'InnoDB.' or a
     nontransactional one such as 'MyISAM.' can
     be very important for performance and scalability.

     *Note*:

     'InnoDB' is the default storage engine for new tables.  In
     practice, the advanced 'InnoDB' performance features mean that
     'InnoDB' tables often outperform the simpler 'MyISAM' tables,
     especially for a busy database.

   * Does each table use an appropriate row format?  This choice also
     depends on the storage engine used for the table.  In particular,
     compressed tables use less disk space and so require less disk I/O
     to read and write the data.  Compression is available for all kinds
     of workloads with 'InnoDB' tables, and for read-only 'MyISAM'
     tables.

   * Does the application use an appropriate locking strategy.
     ?  For example, by allowing shared access when
     possible so that database operations can run concurrently, and
     requesting exclusive access when appropriate so that critical
     operations get top priority.  Again, the choice of storage engine
     is significant.  The 'InnoDB' storage engine handles most locking
     issues without involvement from you, allowing for better
     concurrency in the database and reducing the amount of
     experimentation and tuning for your code.

   * Are all memory areas used for caching.
     sized correctly?  That is, large enough to hold frequently accessed
     data, but not so large that they overload physical memory and cause
     paging.  The main memory areas to configure are the 'InnoDB' buffer
     pool, the 'MyISAM' key cache, and the MySQL query cache.

*Optimizing at the Hardware Level*

Any database application eventually hits hardware limits as the database
becomes more and more busy.  A DBA must evaluate whether it is possible
to tune the application or reconfigure the server to avoid these
bottlenecks, or whether more hardware resources are required.  System
bottlenecks typically arise from these sources:

   * Disk seeks.  It takes time for the disk to find a piece of data.
     With modern disks, the mean time for this is usually lower than
     10ms, so we can in theory do about 100 seeks a second.  This time
     improves slowly with new disks and is very hard to optimize for a
     single table.  The way to optimize seek time is to distribute the
     data onto more than one disk.

   * Disk reading and writing.  When the disk is at the correct
     position, we need to read or write the data.  With modern disks,
     one disk delivers at least 10-20MB/s throughput.  This is easier to
     optimize than seeks because you can read in parallel from multiple
     disks.

   * CPU cycles.  When the data is in main memory, we must process it to
     get our result.  Having large tables compared to the amount of
     memory is the most common limiting factor.  But with small tables,
     speed is usually not the problem.

   * Memory bandwidth.  When the CPU needs more data than can fit in the
     CPU cache, main memory bandwidth becomes a bottleneck.  This is an
     uncommon bottleneck for most systems, but one to be aware of.

*Balancing Portability and Performance*

To use performance-oriented SQL extensions in a portable MySQL program,
you can wrap MySQL-specific keywords in a statement within '/*! */'
comment delimiters.  Other SQL servers ignore the commented keywords.
For information about writing comments, see comments.

8.2 Optimizing SQL Statements
=============================

The core logic of a database application is performed through SQL
statements, whether issued directly through an interpreter or submitted
behind the scenes through an API. The tuning guidelines in this section
help to speed up all kinds of MySQL applications.  The guidelines cover
SQL operations that read and write data, the behind-the-scenes overhead
for SQL operations in general, and operations used in specific scenarios
such as database monitoring.

8.2.1 Optimizing SELECT Statements
----------------------------------

Queries, in the form of 'SELECT' statements, perform all
the lookup operations in the database.  Tuning these statements is a top
priority, whether to achieve sub-second response times for dynamic web
pages, or to chop hours off the time to generate huge overnight reports.

Besides 'SELECT' statements, the tuning techniques for
queries also apply to constructs such as 'CREATE TABLE...AS SELECT',
see 'INSERT INTO...SELECT',
and 'WHERE' clauses in 'DELETE'.
statements.  Those statements have additional performance considerations
because they combine write operations with the read-oriented query
operations.

NDB Cluster supports a join pushdown optimization whereby a qualifying
join is sent in its entirety to NDB Cluster data nodes, where it can be
distributed among them and executed in parallel.  For more information
about this optimization, see ndb_join_pushdown-conditions,

The main considerations for optimizing queries are:

   * To make a slow 'SELECT ... WHERE' query faster, the first thing to
     check is whether you can add an index.  Set up indexes on columns
     used in the 'WHERE' clause, to speed up evaluation, filtering, and
     the final retrieval of results.  To avoid wasted disk space,
     construct a small set of indexes that speed up many related queries
     used in your application.

     Indexes are especially important for queries that reference
     different tables, using features such as joins and foreign keys.
     You can use the 'EXPLAIN' statement to determine
     which indexes are used for a 'SELECT'.  See
     mysql-indexes and using-explain.

   * Isolate and tune any part of the query, such as a function call,
     that takes excessive time.  Depending on how the query is
     structured, a function could be called once for every row in the
     result set, or even once for every row in the table, greatly
     magnifying any inefficiency.

   * Minimize the number of full table scans in your queries,
     particularly for big tables.

   * Keep table statistics up to date by using the 'ANALYZE TABLE'
     statement periodically, so the optimizer has
     the information needed to construct an efficient execution plan.

   * Learn the tuning techniques, indexing techniques, and configuration
     parameters that are specific to the storage engine for each table.
     Both 'InnoDB' and 'MyISAM' have sets of guidelines for enabling and
     sustaining high performance in queries.  For details, see
     optimizing-innodb-queries and optimizing-queries-myisam.

   * You can optimize single-query transactions for 'InnoDB' tables,
     using the technique in innodb-performance-ro-txn.

   * Avoid transforming the query in ways that make it hard to
     understand, especially if the optimizer does some of the same
     transformations automatically.

   * If a performance issue is not easily solved by one of the basic
     guidelines, investigate the internal details of the specific query
     by reading the 'EXPLAIN' plan and adjusting your
     indexes, 'WHERE' clauses, join clauses, and so on.  (When you reach
     a certain level of expertise, reading the 'EXPLAIN'.
     plan might be your first step for every query.)

   * Adjust the size and properties of the memory areas that MySQL uses
     for caching.  With efficient use of the 'InnoDB' buffer pool,
     'MyISAM' key cache, and the MySQL query cache, repeated queries run
     faster because the results are retrieved from memory the second and
     subsequent times.

   * Even for a query that runs fast using the cache memory areas, you
     might still optimize further so that they require less cache
     memory, making your application more scalable.  Scalability means
     that your application can handle more simultaneous users, larger
     requests, and so on without experiencing a big drop in performance.

   * Deal with locking issues, where the speed of your query might be
     affected by other sessions accessing the tables at the same time.

8.2.1.1 WHERE Clause Optimization
.................................

This section discusses optimizations that can be made for processing
'WHERE' clauses.  The examples use 'SELECT' statements,
but the same optimizations apply for 'WHERE' clauses in 'DELETE'
and 'UPDATE' statements.

*Note*:

Because work on the MySQL optimizer is ongoing, not all of the
optimizations that MySQL performs are documented here.

You might be tempted to rewrite your queries to make arithmetic
operations faster, while sacrificing readability.  Because MySQL does
similar optimizations automatically, you can often avoid this work, and
leave the query in a more understandable and maintainable form.  Some of
the optimizations performed by MySQL follow:

   * Removal of unnecessary parentheses:

             ((a AND b) AND c OR (((a AND b) AND (c AND d))))
          -> (a AND b AND c) OR (a AND b AND c AND d)

   * Constant folding:

             (a<b AND b=c) AND a=5
          -> b>5 AND b=c AND a=5

   * Constant condition removal (needed because of constant folding):

             (B>=5 AND B=5) OR (B=6 AND 5=5) OR (B=7 AND 5=6)
          -> B=5 OR B=6

   * Constant expressions used by indexes are evaluated only once.

   * 'COUNT(*)' on a single table without a 'WHERE' is retrieved
     directly from the table information for 'MyISAM' and 'MEMORY'
     tables.  This is also done for any 'NOT NULL' expression when used
     with only one table.

   * Early detection of invalid constant expressions.  MySQL quickly
     detects that some 'SELECT' statements are impossible
     and returns no rows.

   * 'HAVING' is merged with 'WHERE' if you do not use 'GROUP BY' or
     aggregate functions ('COUNT()', 'MIN()', and so on).

   * For each table in a join, a simpler 'WHERE' is constructed to get a
     fast 'WHERE' evaluation for the table and also to skip rows as soon
     as possible.

   *
     All constant tables are read first before any other tables in the
     query.  A constant table is any of the following:

        * An empty table or a table with one row.

        * A table that is used with a 'WHERE' clause on a 'PRIMARY KEY'
          or a 'UNIQUE' index, where all index parts are compared to
          constant expressions and are defined as 'NOT NULL'.

     All of the following tables are used as constant tables:

          SELECT * FROM t WHERE PRIMARY_KEY=1;
          SELECT * FROM t1,t2
            WHERE t1.PRIMARY_KEY=1 AND t2.PRIMARY_KEY=t1.id;

   * The best join combination for joining the tables is found by trying
     all possibilities.  If all columns in 'ORDER BY' and 'GROUP BY'
     clauses come from the same table, that table is preferred first
     when joining.

   * If there is an 'ORDER BY' clause and a different 'GROUP BY' clause,
     or if the 'ORDER BY' or 'GROUP BY' contains columns from tables
     other than the first table in the join queue, a temporary table is
     created.

   * If you use the 'SQL_SMALL_RESULT' modifier, MySQL uses an in-memory
     temporary table.

   * Each table index is queried, and the best index is used unless the
     optimizer believes that it is more efficient to use a table scan.
     At one time, a scan was used based on whether the best index
     spanned more than 30% of the table, but a fixed percentage no
     longer determines the choice between using an index or a scan.  The
     optimizer now is more complex and bases its estimate on additional
     factors such as table size, number of rows, and I/O block size.

   * In some cases, MySQL can read rows from the index without even
     consulting the data file.  If all columns used from the index are
     numeric, only the index tree is used to resolve the query.

   * Before each row is output, those that do not match the 'HAVING'
     clause are skipped.

Some examples of queries that are very fast:

     SELECT COUNT(*) FROM TBL_NAME;

     SELECT MIN(KEY_PART1),MAX(KEY_PART1) FROM TBL_NAME;

     SELECT MAX(KEY_PART2) FROM TBL_NAME
       WHERE KEY_PART1=CONSTANT;

     SELECT ... FROM TBL_NAME
       ORDER BY KEY_PART1,KEY_PART2,... LIMIT 10;

     SELECT ... FROM TBL_NAME
       ORDER BY KEY_PART1 DESC, KEY_PART2 DESC, ... LIMIT 10;

MySQL resolves the following queries using only the index tree, assuming
that the indexed columns are numeric:

     SELECT KEY_PART1,KEY_PART2 FROM TBL_NAME WHERE KEY_PART1=VAL;

     SELECT COUNT(*) FROM TBL_NAME
       WHERE KEY_PART1=VAL1 AND KEY_PART2=VAL2;

     SELECT KEY_PART2 FROM TBL_NAME GROUP BY KEY_PART1;

The following queries use indexing to retrieve the rows in sorted order
without a separate sorting pass:

     SELECT ... FROM TBL_NAME
       ORDER BY KEY_PART1,KEY_PART2,... ;

     SELECT ... FROM TBL_NAME
       ORDER BY KEY_PART1 DESC, KEY_PART2 DESC, ... ;

8.2.1.2 Range Optimization
..........................

The 'range' access method uses a single index to retrieve a subset of
table rows that are contained within one or several index value
intervals.  It can be used for a single-part or multiple-part index.
The following sections give descriptions of conditions under which the
optimizer uses range access.

   * range-access-single-part

   * range-access-multi-part

   * equality-range-optimization

   * range-optimization-memory-use

   * row-constructor-range-optimization

*The Range Access Method for Single-Part Indexes*

For a single-part index, index value intervals can be conveniently
represented by corresponding conditions in the 'WHERE' clause, denoted
as _range conditions_ rather than 'intervals.'

The definition of a range condition for a single-part index is as
follows:

   * For both 'BTREE' and 'HASH' indexes, comparison of a key part with
     a constant value is a range condition when using the '=', '<=>',
     'IN()', 'IS NULL', or 'IS NOT NULL' operators.

   * Additionally, for 'BTREE' indexes, comparison of a key part with a
     constant value is a range condition when using the '>', '<', '>=',
     '<=', 'BETWEEN', '!=', or '<>' operators, or 'LIKE' comparisons if
     the argument to 'LIKE' is a constant string that does not start
     with a wildcard character.

   * For all index types, multiple range conditions combined with 'OR'
     or 'AND' form a range condition.

'Constant value' in the preceding descriptions means one of the
following:

   * A constant from the query string

   * A column of a 'const' or 'system' table from the same join

   * The result of an uncorrelated subquery

   * Any expression composed entirely from subexpressions of the
     preceding types

Here are some examples of queries with range conditions in the 'WHERE'
clause:

     SELECT * FROM t1
       WHERE KEY_COL > 1
       AND KEY_COL < 10;

     SELECT * FROM t1
       WHERE KEY_COL = 1
       OR KEY_COL IN (15,18,20);

     SELECT * FROM t1
       WHERE KEY_COL LIKE 'ab%'
       OR KEY_COL BETWEEN 'bar' AND 'foo';

Some nonconstant values may be converted to constants during the
optimizer constant propagation phase.

MySQL tries to extract range conditions from the 'WHERE' clause for each
of the possible indexes.  During the extraction process, conditions that
cannot be used for constructing the range condition are dropped,
conditions that produce overlapping ranges are combined, and conditions
that produce empty ranges are removed.

Consider the following statement, where 'key1' is an indexed column and
'nonkey' is not indexed:

     SELECT * FROM t1 WHERE
       (key1 < 'abc' AND (key1 LIKE 'abcde%' OR key1 LIKE '%b')) OR
       (key1 < 'bar' AND nonkey = 4) OR
       (key1 < 'uux' AND key1 > 'z');

The extraction process for key 'key1' is as follows:

  1. Start with original 'WHERE' clause:

          (key1 < 'abc' AND (key1 LIKE 'abcde%' OR key1 LIKE '%b')) OR
          (key1 < 'bar' AND nonkey = 4) OR
          (key1 < 'uux' AND key1 > 'z')

  2. Remove 'nonkey = 4' and 'key1 LIKE '%b'' because they cannot be
     used for a range scan.  The correct way to remove them is to
     replace them with 'TRUE', so that we do not miss any matching rows
     when doing the range scan.  Replacing them with 'TRUE' yields:

          (key1 < 'abc' AND (key1 LIKE 'abcde%' OR TRUE)) OR
          (key1 < 'bar' AND TRUE) OR
          (key1 < 'uux' AND key1 > 'z')

  3. Collapse conditions that are always true or false:

        * '(key1 LIKE 'abcde%' OR TRUE)' is always true

        * '(key1 < 'uux' AND key1 > 'z')' is always false

     Replacing these conditions with constants yields:

          (key1 < 'abc' AND TRUE) OR (key1 < 'bar' AND TRUE) OR (FALSE)

     Removing unnecessary 'TRUE' and 'FALSE' constants yields:

          (key1 < 'abc') OR (key1 < 'bar')

  4. Combining overlapping intervals into one yields the final condition
     to be used for the range scan:

          (key1 < 'bar')

In general (and as demonstrated by the preceding example), the condition
used for a range scan is less restrictive than the 'WHERE' clause.
MySQL performs an additional check to filter out rows that satisfy the
range condition but not the full 'WHERE' clause.

The range condition extraction algorithm can handle nested 'AND'/'OR'
constructs of arbitrary depth, and its output does not depend on the
order in which conditions appear in 'WHERE' clause.

MySQL does not support merging multiple ranges for the 'range' access
method for spatial indexes.  To work around this limitation, you can use
a 'UNION' with identical 'SELECT'.
statements, except that you put each spatial predicate in a different
'SELECT'.

*The Range Access Method for Multiple-Part Indexes*

Range conditions on a multiple-part index are an extension of range
conditions for a single-part index.  A range condition on a
multiple-part index restricts index rows to lie within one or several
key tuple intervals.  Key tuple intervals are defined over a set of key
tuples, using ordering from the index.

For example, consider a multiple-part index defined as 'key1(KEY_PART1,
KEY_PART2, KEY_PART3)', and the following set of key tuples listed in
key order:

     KEY_PART1  KEY_PART2  KEY_PART3
       NULL       1          'abc'
       NULL       1          'xyz'
       NULL       2          'foo'
        1         1          'abc'
        1         1          'xyz'
        1         2          'abc'
        2         1          'aaa'

The condition 'KEY_PART1 = 1' defines this interval:

     (1,-inf,-inf) <= (KEY_PART1,KEY_PART2,KEY_PART3) < (1,+inf,+inf)

The interval covers the 4th, 5th, and 6th tuples in the preceding data
set and can be used by the range access method.

By contrast, the condition 'KEY_PART3 = 'abc'' does not define a single
interval and cannot be used by the range access method.

The following descriptions indicate how range conditions work for
multiple-part indexes in greater detail.

   * For 'HASH' indexes, each interval containing identical values can
     be used.  This means that the interval can be produced only for
     conditions in the following form:

              KEY_PART1 CMP CONST1
          AND KEY_PART2 CMP CONST2
          AND ...
          AND KEY_PARTN CMP CONSTN;

     Here, CONST1, CONST2, ... are constants, CMP is one of the '=',
     '<=>', or 'IS NULL' comparison operators, and the conditions cover
     all index parts.  (That is, there are N conditions, one for each
     part of an N-part index.)  For example, the following is a range
     condition for a three-part 'HASH' index:

          KEY_PART1 = 1 AND KEY_PART2 IS NULL AND KEY_PART3 = 'foo'

     For the definition of what is considered to be a constant, see
     range-access-single-part.

   * For a 'BTREE' index, an interval might be usable for conditions
     combined with 'AND', where each condition compares a key part with
     a constant value using '=', '<=>', 'IS NULL', '>', '<', '>=', '<=',
     '!=', '<>', 'BETWEEN', or 'LIKE 'PATTERN'' (where ''PATTERN'' does
     not start with a wildcard).  An interval can be used as long as it
     is possible to determine a single key tuple containing all rows
     that match the condition (or two intervals if '<>' or '!=' is
     used).

     The optimizer attempts to use additional key parts to determine the
     interval as long as the comparison operator is '=', '<=>', or 'IS
     NULL'.  If the operator is '>', '<', '>=', '<=', '!=', '<>',
     'BETWEEN', or 'LIKE', the optimizer uses it but considers no more
     key parts.  For the following expression, the optimizer uses '='
     from the first comparison.  It also uses '>=' from the second
     comparison but considers no further key parts and does not use the
     third comparison for interval construction:

          KEY_PART1 = 'foo' AND KEY_PART2 >= 10 AND KEY_PART3 > 10

     The single interval is:

          ('foo',10,-inf) < (KEY_PART1,KEY_PART2,KEY_PART3) < ('foo',+inf,+inf)

     It is possible that the created interval contains more rows than
     the initial condition.  For example, the preceding interval
     includes the value '('foo', 11, 0)', which does not satisfy the
     original condition.

   * If conditions that cover sets of rows contained within intervals
     are combined with 'OR', they form a condition that covers a set of
     rows contained within the union of their intervals.  If the
     conditions are combined with 'AND', they form a condition that
     covers a set of rows contained within the intersection of their
     intervals.  For example, for this condition on a two-part index:

          (KEY_PART1 = 1 AND KEY_PART2 < 2) OR (KEY_PART1 > 5)

     The intervals are:

          (1,-inf) < (KEY_PART1,KEY_PART2) < (1,2)
          (5,-inf) < (KEY_PART1,KEY_PART2)

     In this example, the interval on the first line uses one key part
     for the left bound and two key parts for the right bound.  The
     interval on the second line uses only one key part.  The 'key_len'
     column in the 'EXPLAIN' output indicates the
     maximum length of the key prefix used.

     In some cases, 'key_len' may indicate that a key part was used, but
     that might be not what you would expect.  Suppose that KEY_PART1
     and KEY_PART2 can be 'NULL'.  Then the 'key_len' column displays
     two key part lengths for the following condition:

          KEY_PART1 >= 1 AND KEY_PART2 < 2

     But, in fact, the condition is converted to this:

          KEY_PART1 >= 1 AND KEY_PART2 IS NOT NULL

See range-access-single-part, describes how optimizations are
performed to combine or eliminate intervals for range conditions on a
single-part index.  Analogous steps are performed for range conditions
on multiple-part indexes.

*Equality Range Optimization of Many-Valued Comparisons*

Consider these expressions, where COL_NAME is an indexed column:

     COL_NAME IN(VAL1, ..., VALN)
     COL_NAME = VAL1 OR ... OR COL_NAME = VALN

Each expression is true if COL_NAME is equal to any of several values.
These comparisons are equality range comparisons (where the 'range' is a
single value).  The optimizer estimates the cost of reading qualifying
rows for equality range comparisons as follows:

   * If there is a unique index on COL_NAME, the row estimate for each
     range is 1 because at most one row can have the given value.

   * Otherwise, any index on COL_NAME is nonunique and the optimizer can
     estimate the row count for each range using dives into the index or
     index statistics.

With index dives, the optimizer makes a dive at each end of a range and
uses the number of rows in the range as the estimate.  For example, the
expression 'COL_NAME IN (10, 20, 30)' has three equality ranges and the
optimizer makes two dives per range to generate a row estimate.  Each
pair of dives yields an estimate of the number of rows that have the
given value.

Index dives provide accurate row estimates, but as the number of
comparison values in the expression increases, the optimizer takes
longer to generate a row estimate.  Use of index statistics is less
accurate than index dives but permits faster row estimation for large
value lists.

The 'eq_range_index_dive_limit' system variable enables you to configure
the number of values at which the optimizer switches from one row
estimation strategy to the other.  To permit use of index dives for
comparisons of up to N equality ranges, set 'eq_range_index_dive_limit'
to N + 1.  To disable use of statistics and always use index dives
regardless of N, set 'eq_range_index_dive_limit' to 0.

To update table index statistics for best estimates, use 'ANALYZE TABLE'.

Even under conditions when index dives would otherwise be used, they are
skipped for queries that satisfy all these conditions:

   * A single-index 'FORCE INDEX' index hint is present.  The idea is
     that if index use is forced, there is nothing to be gained from the
     additional overhead of performing dives into the index.

   * The index is nonunique and not a 'FULLTEXT' index.

   * No subquery is present.

   * No 'DISTINCT', 'GROUP BY', or 'ORDER BY' clause is present.

Those dive-skipping conditions apply only for single-table queries.
Index dives are not skipped for multiple-table queries (joins).

*Limiting Memory Use for Range Optimization*

To control the memory available to the range optimizer, use the
'range_optimizer_max_mem_size' system variable:

   * A value of 0 means 'no limit.'

   * With a value greater than 0, the optimizer tracks the memory
     consumed when considering the range access method.  If the
     specified limit is about to be exceeded, the range access method is
     abandoned and other methods, including a full table scan, are
     considered instead.  This could be less optimal.  If this happens,
     the following warning occurs (where N is the current
     'range_optimizer_max_mem_size' value):

          Warning    3170    Memory capacity of N bytes for
                             'range_optimizer_max_mem_size' exceeded. Range
                             optimization was not done for this query.

For individual queries that exceed the available range optimization
memory and for which the optimizer falls back to less optimal plans,
increasing the 'range_optimizer_max_mem_size' value may improve
performance.

To estimate the amount of memory needed to process a range expression,
use these guidelines:

   * For a simple query such as the following, where there is one
     candidate key for the range access method, each predicate combined
     with 'OR' uses approximately 230 bytes:

          SELECT COUNT(*) FROM t
          WHERE a=1 OR a=2 OR a=3 OR .. . a=N;

   * Similarly for a query such as the following, each predicate
     combined with 'AND' uses approximately 125 bytes:

          SELECT COUNT(*) FROM t
          WHERE a=1 AND b=1 AND c=1 ... N;

   * For a query with 'IN()' predicates:

          SELECT COUNT(*) FROM t
          WHERE a IN (1,2, ..., M) AND b IN (1,2, ..., N);

     Each literal value in an 'IN()' list counts as a predicate combined
     with 'OR'.  If there are two 'IN()' lists, the number of predicates
     combined with 'OR' is the product of the number of literal values
     in each list.  Thus, the number of predicates combined with 'OR' in
     the preceding case is M x N.

Before 5.7.11, the number of bytes per predicate combined with 'OR' was
higher, approximately 700 bytes.

*Range Optimization of Row Constructor Expressions*

The optimizer is able to apply the range scan access method to queries
of this form:

     SELECT ... FROM t1 WHERE ( col_1, col_2 ) IN (( 'a', 'b' ), ( 'c', 'd' ));

Previously, for range scans to be used, it was necessary to write the
query as:

     SELECT ... FROM t1 WHERE ( col_1 = 'a' AND col_2 = 'b' )
     OR ( col_1 = 'c' AND col_2 = 'd' );

For the optimizer to use a range scan, queries must satisfy these
conditions:

   * Only 'IN()' predicates are used, not 'NOT IN()'.

   * On the left side of the 'IN()' predicate, the row constructor
     contains only column references.

   * On the right side of the 'IN()' predicate, row constructors contain
     only runtime constants, which are either literals or local column
     references that are bound to constants during execution.

   * On the right side of the 'IN()' predicate, there is more than one
     row constructor.

For more information about the optimizer and row constructors, see
row-constructor-optimization

8.2.1.3 Index Merge Optimization
................................

The _Index Merge_ access method retrieves rows with multiple 'range'
scans and merges their results into one.  This access method merges
index scans from a single table; it does not merge scans across multiple
tables.  The merge can produce unions, intersections, or
unions-of-intersections of its underlying scans.

Example queries for which Index Merge may be used:

     SELECT * FROM TBL_NAME WHERE KEY1 = 10 OR KEY2 = 20;

     SELECT * FROM TBL_NAME
       WHERE (KEY1 = 10 OR KEY2 = 20) AND NON_KEY = 30;

     SELECT * FROM t1, t2
       WHERE (t1.KEY1 IN (1,2) OR t1.KEY2 LIKE 'VALUE%')
       AND t2.KEY1 = t1.SOME_COL;

     SELECT * FROM t1, t2
       WHERE t1.KEY1 = 1
       AND (t2.KEY1 = t1.SOME_COL OR t2.KEY2 = t1.SOME_COL2);

In 'EXPLAIN' output, the Index Merge method appears as
'index_merge' in the 'type' column.  In this case, the 'key' column
contains a list of indexes used, and 'key_len' contains a list of the
longest key parts for those indexes.

*Note*:

The Index Merge optimization algorithm has the following known
deficiencies:

   * If your query has a complex 'WHERE' clause with deep 'AND'/'OR'
     nesting and MySQL does not choose the optimal plan, try
     distributing terms using the following identity transformations:

          (X AND Y) OR Z => (X OR Z) AND (Y OR Z)
          (X OR Y) AND Z => (X AND Z) OR (Y AND Z)

   * Index Merge is not applicable to full-text indexes.

The Index Merge access method has several algorithms, which are
displayed in the 'Extra' field of 'EXPLAIN' output:

   * 'Using intersect(...)'

   * 'Using union(...)'

   * 'Using sort_union(...)'

The following sections describe these algorithms in greater detail.  The
optimizer chooses between different possible Index Merge algorithms and
other access methods based on cost estimates of the various available
options.

Use of Index Merge is subject to the value of the 'index_merge',
'index_merge_intersection', 'index_merge_union', and
'index_merge_sort_union' flags of the 'optimizer_switch' system
variable.  See switchable-optimizations.  By default, all those
flags are 'on'.  To enable only certain algorithms, set 'index_merge' to
'off', and enable only such of the others as should be permitted.

   * index-merge-intersection

   * index-merge-union

   * index-merge-sort-union

*The Index Merge Intersection Access Algorithm*

This access algorithm is applicable when a 'WHERE' clause is converted
to several range conditions on different keys combined with 'AND', and
each condition is one of the following:

   * An N-part expression of this form, where the index has exactly N
     parts (that is, all index parts are covered):

          KEY_PART1 = CONST1 AND KEY_PART2 = CONST2 ... AND KEY_PARTN = CONSTN

   * Any range condition over a primary key of an 'InnoDB' table.

Examples:

     SELECT * FROM INNODB_TABLE
       WHERE PRIMARY_KEY < 10 AND KEY_COL1 = 20;

     SELECT * FROM TBL_NAME
       WHERE (KEY1_PART1 = 1 AND KEY1_PART2 = 2) AND KEY2 = 2;

The Index Merge intersection algorithm performs simultaneous scans on
all used indexes and produces the intersection of row sequences that it
receives from the merged index scans.

If all columns used in the query are covered by the used indexes, full
table rows are not retrieved (see 'EXPLAIN' output contains
'Using index' in 'Extra' field in this case).  Here is an example of
such a query:

     SELECT COUNT(*) FROM t1 WHERE key1 = 1 AND key2 = 1;

If the used indexes do not cover all columns used in the query, full
rows are retrieved only when the range conditions for all used keys are
satisfied.

If one of the merged conditions is a condition over a primary key of an
'InnoDB' table, it is not used for row retrieval, but is used to filter
out rows retrieved using other conditions.

*The Index Merge Union Access Algorithm*

The criteria for this algorithm are similar to those for the Index Merge
intersection algorithm.  The algorithm is applicable when the table's
'WHERE' clause is converted to several range conditions on different
keys combined with 'OR', and each condition is one of the following:

   * An N-part expression of this form, where the index has exactly N
     parts (that is, all index parts are covered):

          KEY_PART1 = CONST1 AND KEY_PART2 = CONST2 ... AND KEY_PARTN = CONSTN

   * Any range condition over a primary key of an 'InnoDB' table.

   * A condition for which the Index Merge intersection algorithm is
     applicable.

Examples:

     SELECT * FROM t1
       WHERE KEY1 = 1 OR KEY2 = 2 OR KEY3 = 3;

     SELECT * FROM INNODB_TABLE
       WHERE (KEY1 = 1 AND KEY2 = 2)
          OR (KEY3 = 'foo' AND KEY4 = 'bar') AND KEY5 = 5;

*The Index Merge Sort-Union Access Algorithm*

This access algorithm is applicable when the 'WHERE' clause is converted
to several range conditions combined by 'OR', but the Index Merge union
algorithm is not applicable.

Examples:

     SELECT * FROM TBL_NAME
       WHERE KEY_COL1 < 10 OR KEY_COL2 < 20;

     SELECT * FROM TBL_NAME
       WHERE (KEY_COL1 > 10 OR KEY_COL2 = 20) AND NONKEY_COL = 30;

The difference between the sort-union algorithm and the union algorithm
is that the sort-union algorithm must first fetch row IDs for all rows
and sort them before returning any rows.

8.2.1.4 Engine Condition Pushdown Optimization
..............................................

This optimization improves the efficiency of direct comparisons between
a nonindexed column and a constant.  In such cases, the condition is
'pushed down' to the storage engine for evaluation.  This optimization
can be used only by the 'NDB' storage engine.

For NDB Cluster, this optimization can eliminate the need to send
nonmatching rows over the network between the cluster's data nodes and
the MySQL server that issued the query, and can speed up queries where
it is used by a factor of 5 to 10 times over cases where condition
pushdown could be but is not used.

Suppose that an NDB Cluster table is defined as follows:

     CREATE TABLE t1 (
         a INT,
         b INT,
         KEY(a)
     ) ENGINE=NDB;

Condition pushdown can be used with queries such as the one shown here,
which includes a comparison between a nonindexed column and a constant:

     SELECT a, b FROM t1 WHERE b = 10;

The use of condition pushdown can be seen in the output of
'EXPLAIN'.:

     mysql> EXPLAIN SELECT a,b FROM t1 WHERE b = 10\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: t1
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: 10
             Extra: Using where with pushed condition

However, condition pushdown _cannot_ be used with either of these two
queries:

     SELECT a,b FROM t1 WHERE a = 10;
     SELECT a,b FROM t1 WHERE b + 1 = 10;

Condition pushdown is not applicable to the first query because an index
exists on column 'a'.  (An index access method would be more efficient
and so would be chosen in preference to condition pushdown.)  Condition
pushdown cannot be employed for the second query because the comparison
involving the nonindexed column 'b' is indirect.  (However, condition
pushdown could be applied if you were to reduce 'b + 1 = 10' to 'b = 9'
in the 'WHERE' clause.)

Condition pushdown may also be employed when an indexed column is
compared with a constant using a '>' or '<' operator:

     mysql> EXPLAIN SELECT a, b FROM t1 WHERE a < 2\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: t1
              type: range
     possible_keys: a
               key: a
           key_len: 5
               ref: NULL
              rows: 2
             Extra: Using where with pushed condition

Other supported comparisons for condition pushdown include the
following:

   * 'COLUMN [NOT] LIKE PATTERN'

     PATTERN must be a string literal containing the pattern to be
     matched; for syntax, see string-comparison-functions.

   * 'COLUMN IS [NOT] NULL'

   * 'COLUMN IN (VALUE_LIST)'

     Each item in the VALUE_LIST must be a constant, literal value.

   * 'COLUMN BETWEEN CONSTANT1 AND CONSTANT2'

     CONSTANT1 and CONSTANT2 must each be a constant, literal value.

In all of the cases in the preceding list, it is possible for the
condition to be converted into the form of one or more direct
comparisons between a column and a constant.

Engine condition pushdown is enabled by default.  To disable it at
server startup, set the 'optimizer_switch' system variable.  For
example, in a 'my.cnf' file, use these lines:

     [mysqld]
     optimizer_switch=engine_condition_pushdown=off

At runtime, disable condition pushdown like this:

     SET optimizer_switch='engine_condition_pushdown=off';

Limitations

Engine condition pushdown is subject to the following limitations:

   * Condition pushdown is supported only by the 'NDB'
     storage engine.

   * Columns may be compared with constants only; however, this includes
     expressions which evaluate to constant values.

   * Columns used in comparisons cannot be of any of the 'BLOB'
     or 'TEXT' types.

   * A string value to be compared with a column must use the same
     collation as the column.

   * Joins are not directly supported; conditions involving multiple
     tables are pushed separately where possible.  Use extended
     'EXPLAIN' output to determine which conditions are
     actually pushed down.  See explain-extended.

8.2.1.5 Index Condition Pushdown Optimization
.............................................

Index Condition Pushdown (ICP) is an optimization for the case where
MySQL retrieves rows from a table using an index.  Without ICP, the
storage engine traverses the index to locate rows in the base table and
returns them to the MySQL server which evaluates the 'WHERE' condition
for the rows.  With ICP enabled, and if parts of the 'WHERE' condition
can be evaluated by using only columns from the index, the MySQL server
pushes this part of the 'WHERE' condition down to the storage engine.
The storage engine then evaluates the pushed index condition by using
the index entry and only if this is satisfied is the row read from the
table.  ICP can reduce the number of times the storage engine must
access the base table and the number of times the MySQL server must
access the storage engine.

Applicability of the Index Condition Pushdown optimization is subject to
these conditions:

   * ICP is used for the 'range', 'ref', 'eq_ref', and 'ref_or_null'
     access methods when there is a need to access full table rows.

   * ICP can be used for 'InnoDB' and
     'MyISAM' tables, including
     partitioned 'InnoDB' and 'MyISAM' tables.

   * For 'InnoDB' tables, ICP is used only for secondary indexes.  The
     goal of ICP is to reduce the number of full-row reads and thereby
     reduce I/O operations.  For 'InnoDB' clustered indexes, the
     complete record is already read into the 'InnoDB' buffer.  Using
     ICP in this case does not reduce I/O.

   * ICP is not supported with secondary indexes created on virtual
     generated columns.  'InnoDB' supports secondary indexes on virtual
     generated columns.

   * Conditions that refer to subqueries cannot be pushed down.

   * Conditions that refer to stored functions cannot be pushed down.
     Storage engines cannot invoke stored functions.

   * Triggered conditions cannot be pushed down.  (For information about
     triggered conditions, see
     subquery-optimization-with-exists.)

To understand how this optimization works, first consider how an index
scan proceeds when Index Condition Pushdown is not used:

  1. Get the next row, first by reading the index tuple, and then by
     using the index tuple to locate and read the full table row.

  2. Test the part of the 'WHERE' condition that applies to this table.
     Accept or reject the row based on the test result.

Using Index Condition Pushdown, the scan proceeds like this instead:

  1. Get the next row's index tuple (but not the full table row).

  2. Test the part of the 'WHERE' condition that applies to this table
     and can be checked using only index columns.  If the condition is
     not satisfied, proceed to the index tuple for the next row.

  3. If the condition is satisfied, use the index tuple to locate and
     read the full table row.

  4. Test the remaining part of the 'WHERE' condition that applies to
     this table.  Accept or reject the row based on the test result.

'EXPLAIN' output shows 'Using index condition' in the
'Extra' column when Index Condition Pushdown is used.  It does not show
'Using index' because that does not apply when full table rows must be
read.

Suppose that a table contains information about people and their
addresses and that the table has an index defined as 'INDEX (zipcode,
lastname, firstname)'.  If we know a person's 'zipcode' value but are
not sure about the last name, we can search like this:

     SELECT * FROM people
       WHERE zipcode='95054'
       AND lastname LIKE '%etrunia%'
       AND address LIKE '%Main Street%';

MySQL can use the index to scan through people with 'zipcode='95054''.
The second part ('lastname LIKE '%etrunia%'') cannot be used to limit
the number of rows that must be scanned, so without Index Condition
Pushdown, this query must retrieve full table rows for all people who
have 'zipcode='95054''.

With Index Condition Pushdown, MySQL checks the 'lastname LIKE
'%etrunia%'' part before reading the full table row.  This avoids
reading full rows corresponding to index tuples that match the 'zipcode'
condition but not the 'lastname' condition.

Index Condition Pushdown is enabled by default.  It can be controlled
with the 'optimizer_switch' system variable by setting the
'index_condition_pushdown' flag:

     SET optimizer_switch = 'index_condition_pushdown=off';
     SET optimizer_switch = 'index_condition_pushdown=on';

See switchable-optimizations.

8.2.1.6 Nested-Loop Join Algorithms
...................................

MySQL executes joins between tables using a nested-loop algorithm or
variations on it.

   * nested-loop-join-algorithm

   * block-nested-loop-join-algorithm

*Nested-Loop Join Algorithm*

A simple nested-loop join (NLJ) algorithm reads rows from the first
table in a loop one at a time, passing each row to a nested loop that
processes the next table in the join.  This process is repeated as many
times as there remain tables to be joined.

Assume that a join between three tables 't1', 't2', and 't3' is to be
executed using the following join types:

     Table   Join Type
     t1      range
     t2      ref
     t3      ALL

If a simple NLJ algorithm is used, the join is processed like this:

     for each row in t1 matching range {
       for each row in t2 matching reference key {
         for each row in t3 {
           if row satisfies join conditions, send to client
         }
       }
     }

Because the NLJ algorithm passes rows one at a time from outer loops to
inner loops, it typically reads tables processed in the inner loops many
times.

*Block Nested-Loop Join Algorithm*

A Block Nested-Loop (BNL) join algorithm uses buffering of rows read in
outer loops to reduce the number of times that tables in inner loops
must be read.  For example, if 10 rows are read into a buffer and the
buffer is passed to the next inner loop, each row read in the inner loop
can be compared against all 10 rows in the buffer.  This reduces by an
order of magnitude the number of times the inner table must be read.

MySQL join buffering has these characteristics:

   * Join buffering can be used when the join is of type 'ALL' or
     'index' (in other words, when no possible keys can be used, and a
     full scan is done, of either the data or index rows, respectively),
     or 'range'.  Use of buffering is also applicable to outer joins, as
     described in bnl-bka-optimization.

   * A join buffer is never allocated for the first nonconstant table,
     even if it would be of type 'ALL' or 'index'.

   * Only columns of interest to a join are stored in its join buffer,
     not whole rows.

   * The 'join_buffer_size' system variable determines the size of each
     join buffer used to process a query.

   * One buffer is allocated for each join that can be buffered, so a
     given query might be processed using multiple join buffers.

   * A join buffer is allocated prior to executing the join and freed
     after the query is done.

For the example join described previously for the NLJ algorithm (without
buffering), the join is done as follows using join buffering:

     for each row in t1 matching range {
       for each row in t2 matching reference key {
         store used columns from t1, t2 in join buffer
         if buffer is full {
           for each row in t3 {
             for each t1, t2 combination in join buffer {
               if row satisfies join conditions, send to client
             }
           }
           empty join buffer
         }
       }
     }

     if buffer is not empty {
       for each row in t3 {
         for each t1, t2 combination in join buffer {
           if row satisfies join conditions, send to client
         }
       }
     }

If S is the size of each stored 't1', 't2' combination is the join
buffer and C is the number of combinations in the buffer, the number of
times table 't3' is scanned is:

     (S * C)/join_buffer_size + 1

The number of 't3' scans decreases as the value of 'join_buffer_size'
increases, up to the point when 'join_buffer_size' is large enough to
hold all previous row combinations.  At that point, no speed is gained
by making it larger.

8.2.1.7 Nested Join Optimization
................................

The syntax for expressing joins permits nested joins.  The following
discussion refers to the join syntax described in join.

The syntax of TABLE_FACTOR is extended in comparison with the SQL
Standard.  The latter accepts only TABLE_REFERENCE, not a list of them
inside a pair of parentheses.  This is a conservative extension if we
consider each comma in a list of TABLE_REFERENCE items as equivalent to
an inner join.  For example:

     SELECT * FROM t1 LEFT JOIN (t2, t3, t4)
                      ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c)

Is equivalent to:

     SELECT * FROM t1 LEFT JOIN (t2 CROSS JOIN t3 CROSS JOIN t4)
                      ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c)

In MySQL, 'CROSS JOIN' is syntactically equivalent to 'INNER JOIN'; they
can replace each other.  In standard SQL, they are not equivalent.
'INNER JOIN' is used with an 'ON' clause; 'CROSS JOIN' is used
otherwise.

In general, parentheses can be ignored in join expressions containing
only inner join operations.  Consider this join expression:

     t1 LEFT JOIN (t2 LEFT JOIN t3 ON t2.b=t3.b OR t2.b IS NULL)
        ON t1.a=t2.a

After removing parentheses and grouping operations to the left, that
join expression transforms into this expression:

     (t1 LEFT JOIN t2 ON t1.a=t2.a) LEFT JOIN t3
         ON t2.b=t3.b OR t2.b IS NULL

Yet, the two expressions are not equivalent.  To see this, suppose that
the tables 't1', 't2', and 't3' have the following state:

   * Table 't1' contains rows '(1)', '(2)'

   * Table 't2' contains row '(1,101)'

   * Table 't3' contains row '(101)'

In this case, the first expression returns a result set including the
rows '(1,1,101,101)', '(2,NULL,NULL,NULL)', whereas the second
expression returns the rows '(1,1,101,101)', '(2,NULL,NULL,101)':

     mysql> SELECT *
            FROM t1
                 LEFT JOIN
                 (t2 LEFT JOIN t3 ON t2.b=t3.b OR t2.b IS NULL)
                 ON t1.a=t2.a;
     +------+------+------+------+
     | a    | a    | b    | b    |
     +------+------+------+------+
     |    1 |    1 |  101 |  101 |
     |    2 | NULL | NULL | NULL |
     +------+------+------+------+

     mysql> SELECT *
            FROM (t1 LEFT JOIN t2 ON t1.a=t2.a)
                 LEFT JOIN t3
                 ON t2.b=t3.b OR t2.b IS NULL;
     +------+------+------+------+
     | a    | a    | b    | b    |
     +------+------+------+------+
     |    1 |    1 |  101 |  101 |
     |    2 | NULL | NULL |  101 |
     +------+------+------+------+

In the following example, an outer join operation is used together with
an inner join operation:

     t1 LEFT JOIN (t2, t3) ON t1.a=t2.a

That expression cannot be transformed into the following expression:

     t1 LEFT JOIN t2 ON t1.a=t2.a, t3

For the given table states, the two expressions return different sets of
rows:

     mysql> SELECT *
            FROM t1 LEFT JOIN (t2, t3) ON t1.a=t2.a;
     +------+------+------+------+
     | a    | a    | b    | b    |
     +------+------+------+------+
     |    1 |    1 |  101 |  101 |
     |    2 | NULL | NULL | NULL |
     +------+------+------+------+

     mysql> SELECT *
            FROM t1 LEFT JOIN t2 ON t1.a=t2.a, t3;
     +------+------+------+------+
     | a    | a    | b    | b    |
     +------+------+------+------+
     |    1 |    1 |  101 |  101 |
     |    2 | NULL | NULL |  101 |
     +------+------+------+------+

Therefore, if we omit parentheses in a join expression with outer join
operators, we might change the result set for the original expression.

More exactly, we cannot ignore parentheses in the right operand of the
left outer join operation and in the left operand of a right join
operation.  In other words, we cannot ignore parentheses for the inner
table expressions of outer join operations.  Parentheses for the other
operand (operand for the outer table) can be ignored.

The following expression:

     (t1,t2) LEFT JOIN t3 ON P(t2.b,t3.b)

Is equivalent to this expression for any tables 't1,t2,t3' and any
condition 'P' over attributes 't2.b' and 't3.b':

     t1, t2 LEFT JOIN t3 ON P(t2.b,t3.b)

Whenever the order of execution of join operations in a join expression
(JOIN_TABLE) is not from left to right, we talk about nested joins.
Consider the following queries:

     SELECT * FROM t1 LEFT JOIN (t2 LEFT JOIN t3 ON t2.b=t3.b) ON t1.a=t2.a
       WHERE t1.a > 1

     SELECT * FROM t1 LEFT JOIN (t2, t3) ON t1.a=t2.a
       WHERE (t2.b=t3.b OR t2.b IS NULL) AND t1.a > 1

Those queries are considered to contain these nested joins:

     t2 LEFT JOIN t3 ON t2.b=t3.b
     t2, t3

In the first query, the nested join is formed with a left join
operation.  In the second query, it is formed with an inner join
operation.

In the first query, the parentheses can be omitted: The grammatical
structure of the join expression will dictate the same order of
execution for join operations.  For the second query, the parentheses
cannot be omitted, although the join expression here can be interpreted
unambiguously without them.  In our extended syntax, the parentheses in
'(t2, t3)' of the second query are required, although theoretically the
query could be parsed without them: We still would have unambiguous
syntactical structure for the query because 'LEFT JOIN' and 'ON' play
the role of the left and right delimiters for the expression '(t2,t3)'.

The preceding examples demonstrate these points:

   * For join expressions involving only inner joins (and not outer
     joins), parentheses can be removed and joins evaluated left to
     right.  In fact, tables can be evaluated in any order.

   * The same is not true, in general, for outer joins or for outer
     joins mixed with inner joins.  Removal of parentheses may change
     the result.

Queries with nested outer joins are executed in the same pipeline manner
as queries with inner joins.  More exactly, a variation of the
nested-loop join algorithm is exploited.  Recall the algorithm by which
the nested-loop join executes a query (see nested-loop-joins).
Suppose that a join query over 3 tables 'T1,T2,T3' has this form:

     SELECT * FROM T1 INNER JOIN T2 ON P1(T1,T2)
                      INNER JOIN T3 ON P2(T2,T3)
       WHERE P(T1,T2,T3)

Here, 'P1(T1,T2)' and 'P2(T3,T3)' are some join conditions (on
expressions), whereas 'P(T1,T2,T3)' is a condition over columns of
tables 'T1,T2,T3'.

The nested-loop join algorithm would execute this query in the following
manner:

     FOR each row t1 in T1 {
       FOR each row t2 in T2 such that P1(t1,t2) {
         FOR each row t3 in T3 such that P2(t2,t3) {
           IF P(t1,t2,t3) {
              t:=t1||t2||t3; OUTPUT t;
           }
         }
       }
     }

The notation 't1||t2||t3' indicates a row constructed by concatenating
the columns of rows 't1', 't2', and 't3'.  In some of the following
examples, 'NULL' where a table name appears means a row in which 'NULL'
is used for each column of that table.  For example, 't1||t2||NULL'
indicates a row constructed by concatenating the columns of rows 't1'
and 't2', and 'NULL' for each column of 't3'.  Such a row is said to be
'NULL'-complemented.

Now consider a query with nested outer joins:

     SELECT * FROM T1 LEFT JOIN
                   (T2 LEFT JOIN T3 ON P2(T2,T3))
                   ON P1(T1,T2)
       WHERE P(T1,T2,T3)

For this query, modify the nested-loop pattern to obtain:

     FOR each row t1 in T1 {
       BOOL f1:=FALSE;
       FOR each row t2 in T2 such that P1(t1,t2) {
         BOOL f2:=FALSE;
         FOR each row t3 in T3 such that P2(t2,t3) {
           IF P(t1,t2,t3) {
             t:=t1||t2||t3; OUTPUT t;
           }
           f2=TRUE;
           f1=TRUE;
         }
         IF (!f2) {
           IF P(t1,t2,NULL) {
             t:=t1||t2||NULL; OUTPUT t;
           }
           f1=TRUE;
         }
       }
       IF (!f1) {
         IF P(t1,NULL,NULL) {
           t:=t1||NULL||NULL; OUTPUT t;
         }
       }
     }

In general, for any nested loop for the first inner table in an outer
join operation, a flag is introduced that is turned off before the loop
and is checked after the loop.  The flag is turned on when for the
current row from the outer table a match from the table representing the
inner operand is found.  If at the end of the loop cycle the flag is
still off, no match has been found for the current row of the outer
table.  In this case, the row is complemented by 'NULL' values for the
columns of the inner tables.  The result row is passed to the final
check for the output or into the next nested loop, but only if the row
satisfies the join condition of all embedded outer joins.

In the example, the outer join table expressed by the following
expression is embedded:

     (T2 LEFT JOIN T3 ON P2(T2,T3))

For the query with inner joins, the optimizer could choose a different
order of nested loops, such as this one:

     FOR each row t3 in T3 {
       FOR each row t2 in T2 such that P2(t2,t3) {
         FOR each row t1 in T1 such that P1(t1,t2) {
           IF P(t1,t2,t3) {
              t:=t1||t2||t3; OUTPUT t;
           }
         }
       }
     }

For queries with outer joins, the optimizer can choose only such an
order where loops for outer tables precede loops for inner tables.
Thus, for our query with outer joins, only one nesting order is
possible.  For the following query, the optimizer evaluates two
different nestings.  In both nestings, 'T1' must be processed in the
outer loop because it is used in an outer join.  'T2' and 'T3' are used
in an inner join, so that join must be processed in the inner loop.
However, because the join is an inner join, 'T2' and 'T3' can be
processed in either order.

     SELECT * T1 LEFT JOIN (T2,T3) ON P1(T1,T2) AND P2(T1,T3)
       WHERE P(T1,T2,T3)

One nesting evaluates 'T2', then 'T3':

     FOR each row t1 in T1 {
       BOOL f1:=FALSE;
       FOR each row t2 in T2 such that P1(t1,t2) {
         FOR each row t3 in T3 such that P2(t1,t3) {
           IF P(t1,t2,t3) {
             t:=t1||t2||t3; OUTPUT t;
           }
           f1:=TRUE
         }
       }
       IF (!f1) {
         IF P(t1,NULL,NULL) {
           t:=t1||NULL||NULL; OUTPUT t;
         }
       }
     }

The other nesting evaluates 'T3', then 'T2':

     FOR each row t1 in T1 {
       BOOL f1:=FALSE;
       FOR each row t3 in T3 such that P2(t1,t3) {
         FOR each row t2 in T2 such that P1(t1,t2) {
           IF P(t1,t2,t3) {
             t:=t1||t2||t3; OUTPUT t;
           }
           f1:=TRUE
         }
       }
       IF (!f1) {
         IF P(t1,NULL,NULL) {
           t:=t1||NULL||NULL; OUTPUT t;
         }
       }
     }

When discussing the nested-loop algorithm for inner joins, we omitted
some details whose impact on the performance of query execution may be
huge.  We did not mention so-called 'pushed-down' conditions.  Suppose
that our 'WHERE' condition 'P(T1,T2,T3)' can be represented by a
conjunctive formula:

     P(T1,T2,T2) = C1(T1) AND C2(T2) AND C3(T3).

In this case, MySQL actually uses the following nested-loop algorithm
for the execution of the query with inner joins:

     FOR each row t1 in T1 such that C1(t1) {
       FOR each row t2 in T2 such that P1(t1,t2) AND C2(t2)  {
         FOR each row t3 in T3 such that P2(t2,t3) AND C3(t3) {
           IF P(t1,t2,t3) {
              t:=t1||t2||t3; OUTPUT t;
           }
         }
       }
     }

You see that each of the conjuncts 'C1(T1)', 'C2(T2)', 'C3(T3)' are
pushed out of the most inner loop to the most outer loop where it can be
evaluated.  If 'C1(T1)' is a very restrictive condition, this condition
pushdown may greatly reduce the number of rows from table 'T1' passed to
the inner loops.  As a result, the execution time for the query may
improve immensely.

For a query with outer joins, the 'WHERE' condition is to be checked
only after it has been found that the current row from the outer table
has a match in the inner tables.  Thus, the optimization of pushing
conditions out of the inner nested loops cannot be applied directly to
queries with outer joins.  Here we must introduce conditional
pushed-down predicates guarded by the flags that are turned on when a
match has been encountered.

Recall this example with outer joins:

     P(T1,T2,T3)=C1(T1) AND C(T2) AND C3(T3)

For that example, the nested-loop algorithm using guarded pushed-down
conditions looks like this:

     FOR each row t1 in T1 such that C1(t1) {
       BOOL f1:=FALSE;
       FOR each row t2 in T2
           such that P1(t1,t2) AND (f1?C2(t2):TRUE) {
         BOOL f2:=FALSE;
         FOR each row t3 in T3
             such that P2(t2,t3) AND (f1&&f2?C3(t3):TRUE) {
           IF (f1&&f2?TRUE:(C2(t2) AND C3(t3))) {
             t:=t1||t2||t3; OUTPUT t;
           }
           f2=TRUE;
           f1=TRUE;
         }
         IF (!f2) {
           IF (f1?TRUE:C2(t2) && P(t1,t2,NULL)) {
             t:=t1||t2||NULL; OUTPUT t;
           }
           f1=TRUE;
         }
       }
       IF (!f1 && P(t1,NULL,NULL)) {
           t:=t1||NULL||NULL; OUTPUT t;
       }
     }

In general, pushed-down predicates can be extracted from join conditions
such as 'P1(T1,T2)' and 'P(T2,T3)'.  In this case, a pushed-down
predicate is guarded also by a flag that prevents checking the predicate
for the 'NULL'-complemented row generated by the corresponding outer
join operation.

Access by key from one inner table to another in the same nested join is
prohibited if it is induced by a predicate from the 'WHERE' condition.

8.2.1.8 Left Join and Right Join Optimization
.............................................

MySQL implements an 'A LEFT JOIN B join_condition' as follows:

   * Table B is set to depend on table A and all tables on which A
     depends.

   * Table A is set to depend on all tables (except B) that are used in
     the 'LEFT JOIN' condition.

   * The 'LEFT JOIN' condition is used to decide how to retrieve rows
     from table B.  (In other words, any condition in the 'WHERE' clause
     is not used.)

   * All standard join optimizations are performed, with the exception
     that a table is always read after all tables on which it depends.
     If there is a circular dependency, an error occurs.

   * All standard 'WHERE' optimizations are performed.

   * If there is a row in A that matches the 'WHERE' clause, but there
     is no row in B that matches the 'ON' condition, an extra B row is
     generated with all columns set to 'NULL'.

   * If you use 'LEFT JOIN' to find rows that do not exist in some table
     and you have the following test: 'COL_NAME IS NULL' in the 'WHERE'
     part, where COL_NAME is a column that is declared as 'NOT NULL',
     MySQL stops searching for more rows (for a particular key
     combination) after it has found one row that matches the 'LEFT
     JOIN' condition.

The 'RIGHT JOIN' implementation is analogous to that of 'LEFT JOIN' with
the table roles reversed.  Right joins are converted to equivalent left
joins, as described in outer-join-simplification.

The join optimizer calculates the order in which to join tables.  The
table read order forced by 'LEFT JOIN' or 'STRAIGHT_JOIN' helps the join
optimizer do its work much more quickly, because there are fewer table
permutations to check.  This means that if you execute a query of the
following type, MySQL does a full scan on 'b' because the 'LEFT JOIN'
forces it to be read before 'd':

     SELECT *
       FROM a JOIN b LEFT JOIN c ON (c.key=a.key)
       LEFT JOIN d ON (d.key=a.key)
       WHERE b.key=d.key;

The fix in this case is reverse the order in which 'a' and 'b' are
listed in the 'FROM' clause:

     SELECT *
       FROM b JOIN a LEFT JOIN c ON (c.key=a.key)
       LEFT JOIN d ON (d.key=a.key)
       WHERE b.key=d.key;

For a 'LEFT JOIN', if the 'WHERE' condition is always false for the
generated 'NULL' row, the 'LEFT JOIN' is changed to a normal join.  For
example, the 'WHERE' clause would be false in the following query if
't2.column1' were 'NULL':

     SELECT * FROM t1 LEFT JOIN t2 ON (column1) WHERE t2.column2=5;

Therefore, it is safe to convert the query to a normal join:

     SELECT * FROM t1, t2 WHERE t2.column2=5 AND t1.column1=t2.column1;

Now the optimizer can use table 't2' before table 't1' if doing so would
result in a better query plan.  To provide a hint about the table join
order, use 'STRAIGHT_JOIN'; see select.  However,
'STRAIGHT_JOIN' may prevent indexes from being used because it disables
semi-join transformations; see semi-joins.

8.2.1.9 Outer Join Simplification
.................................

Table expressions in the 'FROM' clause of a query are simplified in many
cases.

At the parser stage, queries with right outer join operations are
converted to equivalent queries containing only left join operations.
In the general case, the conversion is performed such that this right
join:

     (T1, ...) RIGHT JOIN (T2, ...) ON P(T1, ..., T2, ...)

Becomes this equivalent left join:

     (T2, ...) LEFT JOIN (T1, ...) ON P(T1, ..., T2, ...)

All inner join expressions of the form 'T1 INNER JOIN T2 ON P(T1,T2)'
are replaced by the list 'T1,T2', 'P(T1,T2)' being joined as a conjunct
to the 'WHERE' condition (or to the join condition of the embedding
join, if there is any).

When the optimizer evaluates plans for outer join operations, it takes
into consideration only plans where, for each such operation, the outer
tables are accessed before the inner tables.  The optimizer choices are
limited because only such plans enable outer joins to be executed using
the nested-loop algorithm.

Consider a query of this form, where 'R(T2)' greatly narrows the number
of matching rows from table 'T2':

     SELECT * T1 LEFT JOIN T2 ON P1(T1,T2)
       WHERE P(T1,T2) AND R(T2)

If the query is executed as written, the optimizer has no choice but to
access the less-restricted table 'T1' before the more-restricted table
'T2', which may produce a very inefficient execution plan.

Instead, MySQL converts the query to a query with no outer join
operation if the 'WHERE' condition is null-rejected.  (That is, it
converts the outer join to an inner join.)  A condition is said to be
null-rejected for an outer join operation if it evaluates to 'FALSE' or
'UNKNOWN' for any 'NULL'-complemented row generated for the operation.

Thus, for this outer join:

     T1 LEFT JOIN T2 ON T1.A=T2.A

Conditions such as these are null-rejected because they cannot be true
for any 'NULL'-complemented row (with 'T2' columns set to 'NULL'):

     T2.B IS NOT NULL
     T2.B > 3
     T2.C <= T1.C
     T2.B < 2 OR T2.C > 1

Conditions such as these are not null-rejected because they might be
true for a 'NULL'-complemented row:

     T2.B IS NULL
     T1.B < 3 OR T2.B IS NOT NULL
     T1.B < 3 OR T2.B > 3

The general rules for checking whether a condition is null-rejected for
an outer join operation are simple:

   * It is of the form 'A IS NOT NULL', where 'A' is an attribute of any
     of the inner tables

   * It is a predicate containing a reference to an inner table that
     evaluates to 'UNKNOWN' when one of its arguments is 'NULL'

   * It is a conjunction containing a null-rejected condition as a
     conjunct

   * It is a disjunction of null-rejected conditions

A condition can be null-rejected for one outer join operation in a query
and not null-rejected for another.  In this query, the 'WHERE' condition
is null-rejected for the second outer join operation but is not
null-rejected for the first one:

     SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
                      LEFT JOIN T3 ON T3.B=T1.B
       WHERE T3.C > 0

If the 'WHERE' condition is null-rejected for an outer join operation in
a query, the outer join operation is replaced by an inner join
operation.

For example, in the preceding query, the second outer join is
null-rejected and can be replaced by an inner join:

     SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
                      INNER JOIN T3 ON T3.B=T1.B
       WHERE T3.C > 0

For the original query, the optimizer evaluates only plans compatible
with the single table-access order 'T1,T2,T3'.  For the rewritten query,
it additionally considers the access order 'T3,T1,T2'.

A conversion of one outer join operation may trigger a conversion of
another.  Thus, the query:

     SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
                      LEFT JOIN T3 ON T3.B=T2.B
       WHERE T3.C > 0

Is first converted to the query:

     SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
                      INNER JOIN T3 ON T3.B=T2.B
       WHERE T3.C > 0

Which is equivalent to the query:

     SELECT * FROM (T1 LEFT JOIN T2 ON T2.A=T1.A), T3
       WHERE T3.C > 0 AND T3.B=T2.B

The remaining outer join operation can also be replaced by an inner join
because the condition 'T3.B=T2.B' is null-rejected.  This results in a
query with no outer joins at all:

     SELECT * FROM (T1 INNER JOIN T2 ON T2.A=T1.A), T3
       WHERE T3.C > 0 AND T3.B=T2.B

Sometimes the optimizer succeeds in replacing an embedded outer join
operation, but cannot convert the embedding outer join.  The following
query:

     SELECT * FROM T1 LEFT JOIN
                   (T2 LEFT JOIN T3 ON T3.B=T2.B)
                   ON T2.A=T1.A
       WHERE T3.C > 0

Is converted to:

     SELECT * FROM T1 LEFT JOIN
                   (T2 INNER JOIN T3 ON T3.B=T2.B)
                   ON T2.A=T1.A
       WHERE T3.C > 0

That can be rewritten only to the form still containing the embedding
outer join operation:

     SELECT * FROM T1 LEFT JOIN
                   (T2,T3)
                   ON (T2.A=T1.A AND T3.B=T2.B)
       WHERE T3.C > 0

Any attempt to convert an embedded outer join operation in a query must
take into account the join condition for the embedding outer join
together with the 'WHERE' condition.  In this query, the 'WHERE'
condition is not null-rejected for the embedded outer join, but the join
condition of the embedding outer join 'T2.A=T1.A AND T3.C=T1.C' is
null-rejected:

     SELECT * FROM T1 LEFT JOIN
                   (T2 LEFT JOIN T3 ON T3.B=T2.B)
                   ON T2.A=T1.A AND T3.C=T1.C
       WHERE T3.D > 0 OR T1.D > 0

Consequently, the query can be converted to:

     SELECT * FROM T1 LEFT JOIN
                   (T2, T3)
                   ON T2.A=T1.A AND T3.C=T1.C AND T3.B=T2.B
       WHERE T3.D > 0 OR T1.D > 0

8.2.1.10 Multi-Range Read Optimization
......................................

Reading rows using a range scan on a secondary index can result in many
random disk accesses to the base table when the table is large and not
stored in the storage engine's cache.  With the Disk-Sweep Multi-Range
Read (MRR) optimization, MySQL tries to reduce the number of random disk
access for range scans by first scanning the index only and collecting
the keys for the relevant rows.  Then the keys are sorted and finally
the rows are retrieved from the base table using the order of the
primary key.  The motivation for Disk-sweep MRR is to reduce the number
of random disk accesses and instead achieve a more sequential scan of
the base table data.

The Multi-Range Read optimization provides these benefits:

   * MRR enables data rows to be accessed sequentially rather than in
     random order, based on index tuples.  The server obtains a set of
     index tuples that satisfy the query conditions, sorts them
     according to data row ID order, and uses the sorted tuples to
     retrieve data rows in order.  This makes data access more efficient
     and less expensive.

   * MRR enables batch processing of requests for key access for
     operations that require access to data rows through index tuples,
     such as range index scans and equi-joins that use an index for the
     join attribute.  MRR iterates over a sequence of index ranges to
     obtain qualifying index tuples.  As these results accumulate, they
     are used to access the corresponding data rows.  It is not
     necessary to acquire all index tuples before starting to read data
     rows.

The MRR optimization is not supported with secondary indexes created on
virtual generated columns.  'InnoDB' supports secondary indexes on
virtual generated columns.

The following scenarios illustrate when MRR optimization can be
advantageous:

Scenario A: MRR can be used for 'InnoDB' and 'MyISAM' tables for index
range scans and equi-join operations.

  1. A portion of the index tuples are accumulated in a buffer.

  2. The tuples in the buffer are sorted by their data row ID.

  3. Data rows are accessed according to the sorted index tuple
     sequence.

Scenario B: MRR can be used for 'NDB' tables for
multiple-range index scans or when performing an equi-join by an
attribute.

  1. A portion of ranges, possibly single-key ranges, is accumulated in
     a buffer on the central node where the query is submitted.

  2. The ranges are sent to the execution nodes that access data rows.

  3. The accessed rows are packed into packages and sent back to the
     central node.

  4. The received packages with data rows are placed in a buffer.

  5. Data rows are read from the buffer.

When MRR is used, the 'Extra' column in 'EXPLAIN' output
shows 'Using MRR'.

'InnoDB' and 'MyISAM' do not use MRR if full table rows need not be
accessed to produce the query result.  This is the case if results can
be produced entirely on the basis on information in the index tuples
(through a covering index); MRR provides no benefit.

Example query for which MRR can be used, assuming that there is an index
on '(KEY_PART1, KEY_PART2)':

     SELECT * FROM t
       WHERE KEY_PART1 >= 1000 AND KEY_PART1 < 2000
       AND KEY_PART2 = 10000;

The index consists of tuples of '(KEY_PART1, KEY_PART2)' values, ordered
first by KEY_PART1 and then by KEY_PART2.

Without MRR, an index scan covers all index tuples for the KEY_PART1
range from 1000 up to 2000, regardless of the KEY_PART2 value in these
tuples.  The scan does extra work to the extent that tuples in the range
contain KEY_PART2 values other than 10000.

With MRR, the scan is broken up into multiple ranges, each for a single
value of KEY_PART1 (1000, 1001, ...  , 1999).  Each of these scans need
look only for tuples with KEY_PART2 = 10000.  If the index contains many
tuples for which KEY_PART2 is not 10000, MRR results in many fewer index
tuples being read.

To express this using interval notation, the non-MRR scan must examine
the index range '[{1000, 10000}, {2000, MIN_INT})', which may include
many tuples other than those for which KEY_PART2 = 10000.  The MRR scan
examines multiple single-point intervals '[{1000, 10000}]', ...,
'[{1999, 10000}]', which includes only tuples with KEY_PART2 = 10000.

Two 'optimizer_switch' system variable flags provide an interface to the
use of MRR optimization.  The 'mrr' flag controls whether MRR is
enabled.  If 'mrr' is enabled ('on'), the 'mrr_cost_based' flag controls
whether the optimizer attempts to make a cost-based choice between using
and not using MRR ('on') or uses MRR whenever possible ('off').  By
default, 'mrr' is 'on' and 'mrr_cost_based' is 'on'.  See
switchable-optimizations.

For MRR, a storage engine uses the value of the 'read_rnd_buffer_size'
system variable as a guideline for how much memory it can allocate for
its buffer.  The engine uses up to 'read_rnd_buffer_size' bytes and
determines the number of ranges to process in a single pass.

8.2.1.11 Block Nested-Loop and Batched Key Access Joins
.......................................................

In MySQL, a Batched Key Access (BKA) Join algorithm is available that
uses both index access to the joined table and a join buffer.  The BKA
algorithm supports inner join, outer join, and semi-join operations,
including nested outer joins.  Benefits of BKA include improved join
performance due to more efficient table scanning.  Also, the Block
Nested-Loop (BNL) Join algorithm previously used only for inner joins is
extended and can be employed for outer join and semi-join operations,
including nested outer joins.

The following sections discuss the join buffer management that underlies
the extension of the original BNL algorithm, the extended BNL algorithm,
and the BKA algorithm.  For information about semi-join strategies, see
semi-joins

   * join-buffer-management

   * bnl-optimization

   * bka-optimization

   * bnl-bka-optimizer-hints

*Join Buffer Management for Block Nested-Loop and Batched Key Access
Algorithms*

MySQL can employ join buffers to execute not only inner joins without
index access to the inner table, but also outer joins and semi-joins
that appear after subquery flattening.  Moreover, a join buffer can be
effectively used when there is an index access to the inner table.

The join buffer management code slightly more efficiently utilizes join
buffer space when storing the values of the interesting row columns: No
additional bytes are allocated in buffers for a row column if its value
is 'NULL', and the minimum number of bytes is allocated for any value of
the 'VARCHAR' type.

The code supports two types of buffers, regular and incremental.
Suppose that join buffer 'B1' is employed to join tables 't1' and 't2'
and the result of this operation is joined with table 't3' using join
buffer 'B2':

   * A regular join buffer contains columns from each join operand.  If
     'B2' is a regular join buffer, each row R put into 'B2' is composed
     of the columns of a row R1 from 'B1' and the interesting columns of
     a matching row R2 from table 't3'.

   * An incremental join buffer contains only columns from rows of the
     table produced by the second join operand.  That is, it is
     incremental to a row from the first operand buffer.  If 'B2' is an
     incremental join buffer, it contains the interesting columns of the
     row R2 together with a link to the row R1 from 'B1'.

Incremental join buffers are always incremental relative to a join
buffer from an earlier join operation, so the buffer from the first join
operation is always a regular buffer.  In the example just given, the
buffer 'B1' used to join tables 't1' and 't2' must be a regular buffer.

Each row of the incremental buffer used for a join operation contains
only the interesting columns of a row from the table to be joined.
These columns are augmented with a reference to the interesting columns
of the matched row from the table produced by the first join operand.
Several rows in the incremental buffer can refer to the same row R whose
columns are stored in the previous join buffers insofar as all these
rows match row R.

Incremental buffers enable less frequent copying of columns from buffers
used for previous join operations.  This provides a savings in buffer
space because in the general case a row produced by the first join
operand can be matched by several rows produced by the second join
operand.  It is unnecessary to make several copies of a row from the
first operand.  Incremental buffers also provide a savings in processing
time due to the reduction in copying time.

The 'block_nested_loop' and 'batched_key_access' flags of the
'optimizer_switch' system variable control how the optimizer uses the
Block Nested-Loop and Batched Key Access join algorithms.  By default,
'block_nested_loop' is 'on' and 'batched_key_access' is 'off'.  See
switchable-optimizations.  Optimizer hints may also be applied;
see bnl-bka-optimizer-hints.

For information about semi-join strategies, see semi-joins

*Block Nested-Loop Algorithm for Outer Joins and Semi-Joins*

The original implementation of the MySQL BNL algorithm is extended to
support outer join and semi-join operations.

When these operations are executed with a join buffer, each row put into
the buffer is supplied with a match flag.

If an outer join operation is executed using a join buffer, each row of
the table produced by the second operand is checked for a match against
each row in the join buffer.  When a match is found, a new extended row
is formed (the original row plus columns from the second operand) and
sent for further extensions by the remaining join operations.  In
addition, the match flag of the matched row in the buffer is enabled.
After all rows of the table to be joined have been examined, the join
buffer is scanned.  Each row from the buffer that does not have its
match flag enabled is extended by 'NULL' complements ('NULL' values for
each column in the second operand) and sent for further extensions by
the remaining join operations.

The 'block_nested_loop' flag of the 'optimizer_switch' system variable
controls how the optimizer uses the Block Nested-Loop algorithm.  By
default, 'block_nested_loop' is 'on'.  See
switchable-optimizations.  Optimizer hints may also be applied; see
bnl-bka-optimizer-hints.

In 'EXPLAIN' output, use of BNL for a table is signified
when the 'Extra' value contains 'Using join buffer (Block Nested Loop)'
and the 'type' value is 'ALL', 'index', or 'range'.

For information about semi-join strategies, see semi-joins

*Batched Key Access Joins*

MySQL implements a method of joining tables called the Batched Key
Access (BKA) join algorithm.  BKA can be applied when there is an index
access to the table produced by the second join operand.  Like the BNL
join algorithm, the BKA join algorithm employs a join buffer to
accumulate the interesting columns of the rows produced by the first
operand of the join operation.  Then the BKA algorithm builds keys to
access the table to be joined for all rows in the buffer and submits
these keys in a batch to the database engine for index lookups.  The
keys are submitted to the engine through the Multi-Range Read (MRR)
interface (see mrr-optimization).  After submission of the keys,
the MRR engine functions perform lookups in the index in an optimal way,
fetching the rows of the joined table found by these keys, and starts
feeding the BKA join algorithm with matching rows.  Each matching row is
coupled with a reference to a row in the join buffer.

When BKA is used, the value of 'join_buffer_size' defines how large the
batch of keys is in each request to the storage engine.  The larger the
buffer, the more sequential access will be to the right hand table of a
join operation, which can significantly improve performance.

For BKA to be used, the 'batched_key_access' flag of the
'optimizer_switch' system variable must be set to 'on'.  BKA uses MRR,
so the 'mrr' flag must also be 'on'.  Currently, the cost estimation for
MRR is too pessimistic.  Hence, it is also necessary for
'mrr_cost_based' to be 'off' for BKA to be used.  The following setting
enables BKA:

     mysql> SET optimizer_switch='mrr=on,mrr_cost_based=off,batched_key_access=on';

There are two scenarios by which MRR functions execute:

   * The first scenario is used for conventional disk-based storage
     engines such as 'InnoDB' and
     'MyISAM'.  For these engines, usually the
     keys for all rows from the join buffer are submitted to the MRR
     interface at once.  Engine-specific MRR functions perform index
     lookups for the submitted keys, get row IDs (or primary keys) from
     them, and then fetch rows for all these selected row IDs one by one
     by request from BKA algorithm.  Every row is returned with an
     association reference that enables access to the matched row in the
     join buffer.  The rows are fetched by the MRR functions in an
     optimal way: They are fetched in the row ID (primary key) order.
     This improves performance because reads are in disk order rather
     than random order.

   * The second scenario is used for remote storage engines such as
     'NDB'.  A package of keys for a portion of
     rows from the join buffer, together with their associations, is
     sent by a MySQL Server (SQL node) to NDB Cluster data nodes.  In
     return, the SQL node receives a package (or several packages) of
     matching rows coupled with corresponding associations.  The BKA
     join algorithm takes these rows and builds new joined rows.  Then a
     new set of keys is sent to the data nodes and the rows from the
     returned packages are used to build new joined rows.  The process
     continues until the last keys from the join buffer are sent to the
     data nodes, and the SQL node has received and joined all rows
     matching these keys.  This improves performance because fewer
     key-bearing packages sent by the SQL node to the data nodes means
     fewer round trips between it and the data nodes to perform the join
     operation.

With the first scenario, a portion of the join buffer is reserved to
store row IDs (primary keys) selected by index lookups and passed as a
parameter to the MRR functions.

There is no special buffer to store keys built for rows from the join
buffer.  Instead, a function that builds the key for the next row in the
buffer is passed as a parameter to the MRR functions.

In 'EXPLAIN' output, use of BKA for a table is signified
when the 'Extra' value contains 'Using join buffer (Batched Key Access)'
and the 'type' value is 'ref' or 'eq_ref'.

*Optimizer Hints for Block Nested-Loop and Batched Key Access
Algorithms*

In addition to using the 'optimizer_switch' system variable to control
optimizer use of the BNL and BKA algorithms session-wide, MySQL supports
optimizer hints to influence the optimizer on a per-statement basis.
See optimizer-hints.

To use a BNL or BKA hint to enable join buffering for any inner table of
an outer join, join buffering must be enabled for all inner tables of
the outer join.

8.2.1.12 IS NULL Optimization
.............................

MySQL can perform the same optimization on COL_NAME 'IS NULL' that it
can use for COL_NAME '=' CONSTANT_VALUE.  For example, MySQL can use
indexes and ranges to search for 'NULL' with 'IS NULL'.

Examples:

     SELECT * FROM TBL_NAME WHERE KEY_COL IS NULL;

     SELECT * FROM TBL_NAME WHERE KEY_COL <=> NULL;

     SELECT * FROM TBL_NAME
       WHERE KEY_COL=CONST1 OR KEY_COL=CONST2 OR KEY_COL IS NULL;

If a 'WHERE' clause includes a COL_NAME 'IS NULL' condition for a column
that is declared as 'NOT NULL', that expression is optimized away.  This
optimization does not occur in cases when the column might produce
'NULL' anyway; for example, if it comes from a table on the right side
of a 'LEFT JOIN'.

MySQL can also optimize the combination 'COL_NAME = EXPR OR COL_NAME IS
NULL', a form that is common in resolved subqueries.  'EXPLAIN'
shows 'ref_or_null' when this optimization is used.

This optimization can handle one 'IS NULL' for any key part.

Some examples of queries that are optimized, assuming that there is an
index on columns 'a' and 'b' of table 't2':

     SELECT * FROM t1 WHERE t1.a=EXPR OR t1.a IS NULL;

     SELECT * FROM t1, t2 WHERE t1.a=t2.a OR t2.a IS NULL;

     SELECT * FROM t1, t2
       WHERE (t1.a=t2.a OR t2.a IS NULL) AND t2.b=t1.b;

     SELECT * FROM t1, t2
       WHERE t1.a=t2.a AND (t2.b=t1.b OR t2.b IS NULL);

     SELECT * FROM t1, t2
       WHERE (t1.a=t2.a AND t2.a IS NULL AND ...)
       OR (t1.a=t2.a AND t2.a IS NULL AND ...);

'ref_or_null' works by first doing a read on the reference key, and then
a separate search for rows with a 'NULL' key value.

The optimization can handle only one 'IS NULL' level.  In the following
query, MySQL uses key lookups only on the expression '(t1.a=t2.a AND
t2.a IS NULL)' and is not able to use the key part on 'b':

     SELECT * FROM t1, t2
       WHERE (t1.a=t2.a AND t2.a IS NULL)
       OR (t1.b=t2.b AND t2.b IS NULL);

8.2.1.13 ORDER BY Optimization
..............................

This section describes when MySQL can use an index to satisfy an 'ORDER
BY' clause, the 'filesort' algorithms used when an index cannot be used,
and execution plan information available from the optimizer about 'ORDER
BY'.

   * order-by-index-use

   * order-by-filesort

   * order-by-filesort-original

   * order-by-filesort-modified

   * order-by-filesort-in-memory

   * order-by-filesort-algorithm-comparison

   * order-by-optimizer-control

   * order-by-diagnostic-information

*Use of Indexes to Satisfy ORDER BY*

In some cases, MySQL can use an index to satisfy an 'ORDER BY' clause
without doing extra sorting.

The index can also be used even if the 'ORDER BY' does not match the
index exactly, as long as all unused portions of the index and all extra
'ORDER BY' columns are constants in the 'WHERE' clause.  The following
queries use the index to resolve the 'ORDER BY' part:

     SELECT * FROM t1
       ORDER BY KEY_PART1, KEY_PART2;

     SELECT * FROM t1
       WHERE KEY_PART1 = CONSTANT
       ORDER BY KEY_PART2;

     SELECT * FROM t1
       ORDER BY KEY_PART1 DESC, KEY_PART2 DESC;

     SELECT * FROM t1
       WHERE KEY_PART1 = 1
       ORDER BY KEY_PART1 DESC, KEY_PART2 DESC;

     SELECT * FROM t1
       WHERE KEY_PART1 > CONSTANT
       ORDER BY KEY_PART1 ASC;

     SELECT * FROM t1
       WHERE KEY_PART1 < CONSTANT
       ORDER BY KEY_PART1 DESC;

     SELECT * FROM t1
       WHERE KEY_PART1 = CONSTANT1 AND KEY_PART2 > CONSTANT2
       ORDER BY KEY_PART2;

In some cases, MySQL _cannot_ use indexes to resolve the 'ORDER BY',
although it may still use indexes to find the rows that match the
'WHERE' clause.  Examples:

   * The query uses 'ORDER BY' on different indexes:

          SELECT * FROM t1 ORDER BY KEY1, KEY2;

   * The query uses 'ORDER BY' on nonconsecutive parts of an index:

          SELECT * FROM t1 WHERE KEY2=CONSTANT ORDER BY KEY_PART1, KEY_PART3;

   * The query mixes 'ASC' and 'DESC':

          SELECT * FROM t1 ORDER BY KEY_PART1 DESC, KEY_PART2 ASC;

   * The index used to fetch the rows differs from the one used in the
     'ORDER BY':

          SELECT * FROM t1 WHERE KEY2=CONSTANT ORDER BY KEY1;

   * The query uses 'ORDER BY' with an expression that includes terms
     other than the index column name:

          SELECT * FROM t1 ORDER BY ABS(KEY);
          SELECT * FROM t1 ORDER BY -KEY;

   * The query joins many tables, and the columns in the 'ORDER BY' are
     not all from the first nonconstant table that is used to retrieve
     rows.  (This is the first table in the 'EXPLAIN'.
     output that does not have a 'const' join type.)

   * The query has different 'ORDER BY' and 'GROUP BY' expressions.

   * There is an index on only a prefix of a column named in the 'ORDER
     BY' clause.  In this case, the index cannot be used to fully
     resolve the sort order.  For example, if only the first 10 bytes of
     a 'CHAR(20)' column are indexed, the index cannot
     distinguish values past the 10th byte and a 'filesort' is needed.

   * The index does not store rows in order.  For example, this is true
     for a 'HASH' index in a 'MEMORY' table.

Availability of an index for sorting may be affected by the use of
column aliases.  Suppose that the column 't1.a' is indexed.  In this
statement, the name of the column in the select list is 'a'.  It refers
to 't1.a', as does the reference to 'a' in the 'ORDER BY', so the index
on 't1.a' can be used:

     SELECT a FROM t1 ORDER BY a;

In this statement, the name of the column in the select list is also
'a', but it is the alias name.  It refers to 'ABS(a)', as does the
reference to 'a' in the 'ORDER BY', so the index on 't1.a' cannot be
used:

     SELECT ABS(a) AS a FROM t1 ORDER BY a;

In the following statement, the 'ORDER BY' refers to a name that is not
the name of a column in the select list.  But there is a column in 't1'
named 'a', so the 'ORDER BY' refers to 't1.a' and the index on 't1.a'
can be used.  (The resulting sort order may be completely different from
the order for 'ABS(a)', of course.)

     SELECT ABS(a) AS b FROM t1 ORDER BY a;

By default, MySQL sorts all 'GROUP BY COL1, COL2, ...' queries as if you
specified 'ORDER BY COL1, COL2, ...' in the query as well.  If you
include an explicit 'ORDER BY' clause that contains the same column
list, MySQL optimizes it away without any speed penalty, although the
sorting still occurs.

If a query includes 'GROUP BY' but you want to avoid the overhead of
sorting the result, you can suppress sorting by specifying 'ORDER BY
NULL'.  For example:

     INSERT INTO foo
     SELECT a, COUNT(*) FROM bar GROUP BY a ORDER BY NULL;

The optimizer may still choose to use sorting to implement grouping
operations.  'ORDER BY NULL' suppresses sorting of the result, not prior
sorting done by grouping operations to determine the result.

*Note*:

'GROUP BY' implicitly sorts by default (that is, in the absence of 'ASC'
or 'DESC' designators), but relying on implicit 'GROUP BY' sorting is
deprecated.  To produce a given sort order, use explicit 'ASC' or 'DESC'
designators for 'GROUP BY' columns or provide an 'ORDER BY' clause.
'GROUP BY' sorting is a MySQL extension that may change in a future
release; for example, to make it possible for the optimizer to order
groupings in whatever manner it deems most efficient and to avoid the
sorting overhead.

*Optimization Using filesort*

MySQL has multiple 'filesort' algorithms for sorting and retrieving
results.  The original algorithm uses only the 'ORDER BY' columns.  The
modified algorithm uses not just the 'ORDER BY' columns, but all columns
referenced by the query.  There is also an algorithm for small result
sets that sorts in memory using the sort buffer as a priority queue
without a merge file.

The optimizer selects which 'filesort' algorithm to use.  It normally
uses the modified algorithm except when 'BLOB' or
'TEXT' columns are involved, in which case it uses the original
algorithm.  For each algorithm, the sort buffer size is the
'sort_buffer_size' system variable value.

*The Original filesort Algorithm*

The original 'filesort' algorithm works as follows:

  1. Read all rows according to key or by table scanning.  Skip rows
     that do not match the 'WHERE' clause.

  2. For each row, store in the sort buffer a tuple consisting of a pair
     of values (the sort key value and the row ID).

  3. If all pairs fit into the sort buffer, no temporary file is
     created.  Otherwise, when the sort buffer becomes full, run a
     quicksort on it in memory and write it to a temporary file.  Save a
     pointer to the sorted block.

  4. Repeat the preceding steps until all rows have been read.

  5. Do a multi-merge of up to 'MERGEBUFF' (7) regions to one block in
     another temporary file.  Repeat until all blocks from the first
     file are in the second file.

  6. Repeat the following until there are fewer than 'MERGEBUFF2' (15)
     blocks left.

  7. On the last multi-merge, only the row ID (the last part of the
     value pair) is written to a result file.

  8. Read the rows in sorted order using the row IDs in the result file.
     To optimize this, read in a large block of row IDs, sort them, and
     use them to read the rows in sorted order into a row buffer.  The
     row buffer size is the 'read_rnd_buffer_size' system variable
     value.  The code for this step is in the 'sql/records.cc' source
     file.

One problem with this approach is that it reads rows twice: Once during
'WHERE' clause evaluation, and again after sorting the value pairs.  And
even if the rows were accessed successively the first time (for example,
if a table scan is done), the second time they are accessed randomly.
(The sort keys are ordered, but the row positions are not.)

*The Modified filesort Algorithm*

The modified 'filesort' algorithm incorporates an optimization to avoid
reading the rows twice: It records the sort key value, but instead of
the row ID, it records the columns referenced by the query.  The
modified 'filesort' algorithm works like this:

  1. Read the rows that match the 'WHERE' clause.

  2. For each row, store in the sort buffer a tuple consisting of the
     sort key value and the columns referenced by the query.

  3. When the sort buffer becomes full, sort the tuples by sort key
     value in memory and write it to a temporary file.

  4. After merge-sorting the temporary file, retrieve the rows in sorted
     order, but read the columns required by the query directly from the
     sorted tuples rather than by accessing the table a second time.

The tuples used by the modified 'filesort' algorithm are longer than the
pairs used by the original algorithm, and fewer of them fit in the sort
buffer.  As a result, it is possible for the extra I/O to make the
modified approach slower, not faster.  To avoid a slowdown, the
optimizer uses the modified algorithm only if the total size of the
extra columns in the sort tuple does not exceed the value of the
'max_length_for_sort_data' system variable.  (A symptom of setting the
value of this variable too high is a combination of high disk activity
and low CPU activity.)

The modified 'filesort' algorithm includes an additional optimization
designed to enable more tuples to fit into the sort buffer: For
additional columns of type 'CHAR' or 'VARCHAR', or any nullable
fixed-size data type, the values are packed.  For example, without
packing, a 'VARCHAR(255)' column value containing only 3 characters
takes 255 characters in the sort buffer.  With packing, the value
requires only 3 characters plus a two-byte length indicator.  'NULL'
values require only a bitmask.

For data containing packable strings shorter than the maximum column
length or many 'NULL' values, more records fit into the sort buffer.
This improves in-memory sorting of the sort buffer and performance of
disk-based temporary file merge sorting.

In edge cases, packing may be disadvantageous: If packable strings are
the maximum column length or there are few 'NULL' values, the space
required for the length indicators reduces the number of records that
fit into the sort buffer and sorting is slower in memory and on disk.

*The In-Memory filesort Algorithm*

For queries (and subqueries) of the following form, the optimizer can
use 'filesort' to efficiently handle the 'ORDER BY' operation in memory
without a merge file:

     SELECT ... FROM SINGLE_TABLE ... ORDER BY NON_INDEX_COLUMN [DESC] LIMIT [M,]N;

That type of query is common in web applications that display only a few
rows from a larger result set.  For example:

     SELECT col1, ... FROM t1 ... ORDER BY name LIMIT 10;
     SELECT col1, ... FROM t1 ... ORDER BY RAND() LIMIT 15;

The sort buffer has a size of 'sort_buffer_size'.  If the sort elements
for N rows are small enough to fit in the sort buffer (M+N rows if M was
specified), the server can avoid using a merge file and performs an
in-memory sort by treating the sort buffer as a priority queue:

  1. Scan the table, inserting the select list columns from each
     selected row in sorted order in the queue.  If the queue is full,
     bump out the last row in the sort order.

  2. Return the first N rows from the queue.  (If M was specified, skip
     the first M rows and return the next N rows.)

Absent that optimization, the server performs this operation by using a
merge file for the sort:

  1. Scan the table, repeating these steps through the end of the table:

        * Select rows until the sort buffer is filled.

        * Write the first N rows in the buffer (M+N rows if M was
          specified) to a merge file.

  2. Sort the merge file and return the first N rows.  (If M was
     specified, skip the first M rows and return the next N rows.)

The cost of the table-scan operation is the same for the queue and
merge-file methods, so the optimizer chooses between methods based on
other costs:

   * The queue method involves more CPU for inserting rows into the
     queue in order.

   * The merge-file method has I/O costs to write and read the file and
     CPU cost to sort it.

The optimizer considers the balance between these factors for particular
values of M, N, and the row size.

An 'ORDER BY' with and without 'LIMIT' may return rows in different
orders, as discussed in limit-optimization.

*Comparison of filesort Algorithms*

Suppose that a table 't1' has four 'VARCHAR' columns 'a', 'b', 'c', and
'd' and that the optimizer uses 'filesort' for this query:

     SELECT * FROM t1 ORDER BY a, b;

The query sorts by 'a' and 'b', but returns all columns, so the columns
referenced by the query are 'a', 'b', 'c', and 'd'.  Depending on which
'filesort' algorithm the optimizer chooses, the query executes as
follows:

For the original algorithm, sort buffer tuples have these contents:

     (fixed size a value, fixed size b value,
     row ID into t1)

The optimizer sorts on the fixed size values.  After sorting, the
optimizer reads the tuples in order and uses the row ID in each tuple to
read rows from 't1' to obtain the select list column values.

For the modified algorithm without packing, sort buffer tuples have
these contents:

     (fixed size a value, fixed size b value,
     a value, b value, c value, d value)

The optimizer sorts on the fixed size values.  After sorting, the
optimizer reads the tuples in order and uses the values for 'a', 'b',
'c', and 'd' to obtain the select list column values without reading
't1' again.

For the modified algorithm with packing, sort buffer tuples have these
contents:

     (fixed size a value, fixed size b value,
     a length, packed a value, b length, packed b value,
     c length, packed c value, d length, packed d value)

If any of 'a', 'b', 'c', or 'd' are 'NULL', they take no space in the
sort buffer other than in the bitmask.

The optimizer sorts on the fixed size values.  After sorting, the
optimizer reads the tuples in order and uses the values for 'a', 'b',
'c', and 'd' to obtain the select list column values without reading
't1' again.

*Influencing ORDER BY Optimization*

For slow 'ORDER BY' queries for which 'filesort' is not used, try
lowering 'max_length_for_sort_data' to a value that is appropriate to
trigger a 'filesort'.

To increase 'ORDER BY' speed, check whether you can get MySQL to use
indexes rather than an extra sorting phase.  If this is not possible,
you can try the following strategies:

   * Increase the 'sort_buffer_size' variable value.  Ideally, the value
     should be large enough for the entire result set to fit in the sort
     buffer (to avoid writes to disk and merge passes), but at minimum
     the value must be large enough to accommodate fifteen tuples.

     Take into account that the size of column values stored in the sort
     buffer is affected by the 'max_sort_length' system variable value.
     For example, if tuples store values of long string columns and you
     increase the value of 'max_sort_length', the size of sort buffer
     tuples increases as well and may require you to increase
     'sort_buffer_size'.  For column values calculated as a result of
     string expressions (such as those that invoke a string-valued
     function), the 'filesort' algorithm cannot tell the maximum length
     of expression values, so it must allocate 'max_sort_length' bytes
     for each tuple.

     To monitor the number of merge passes, check the
     'Sort_merge_passes' status variable.

   * Increase the 'read_rnd_buffer_size' variable value.

   * Use less RAM per row by declaring columns only as large as they
     need to be to hold the values stored in them.  For example,
     'CHAR(16)' is better than 'CHAR(200)' if values never exceed 16
     characters.

   * Change the 'tmpdir' system variable to point to a dedicated file
     system with large amounts of free space.  The variable value can
     list several paths that are used in round-robin fashion; you can
     use this feature to spread the load across several directories.
     Separate the paths by colon characters (':') on Unix and semicolon
     characters (';') on Windows.  The paths should name directories in
     file systems located on different _physical_ disks, not different
     partitions on the same disk.

*ORDER BY Execution Plan Information Available*

With 'EXPLAIN SELECT ... ORDER BY', you can check whether
MySQL can use indexes to resolve the query.  It cannot if you see 'Using
filesort' in the 'Extra' column.  See using-explain.  Filesort
uses a fixed-length row-storage format similar to that used by the
'MEMORY' storage engine.  Variable-length types
such as 'VARCHAR' are stored using a fixed length.

If a 'filesort' is done, see 'EXPLAIN' output includes
'Using filesort' in the 'Extra' column.  Also, optimizer trace output
includes a 'filesort_summary' block.  For example:

     "filesort_summary": {
       "rows": 100,
       "examined_rows": 100,
       "number_of_tmp_files": 0,
       "sort_buffer_size": 25192,
       "sort_mode": "<sort_key, packed_additional_fields>"
     }

The 'sort_mode' value provides information about the 'filesort'
algorithm used and the contents of tuples in the sort buffer:

   * '<sort_key, rowid>': This indicates use of the original algorithm.
     Sort buffer tuples are pairs that contain the sort key value and
     row ID of the original table row.  Tuples are sorted by sort key
     value and the row ID is used to read the row from the table.

   * '<sort_key, additional_fields>': This indicates use of the modified
     algorithm.  Sort buffer tuples contain the sort key value and
     columns referenced by the query.  Tuples are sorted by sort key
     value and column values are read directly from the tuple.

   * '<sort_key, packed_additional_fields>': This indicates use of the
     modified algorithm.  Sort buffer tuples contain the sort key value
     and packed columns referenced by the query.  Tuples are sorted by
     sort key value and column values are read directly from the tuple.

'EXPLAIN' does not distinguish between use of the
modified and in-memory (priority queue) algorithms.  Use of the
in-memory algorithm can be seen in optimizer trace output.  Look for
'filesort_priority_queue_optimization'.

For information about the optimizer trace, see MySQL Internals: Tracing
the Optimizer
(http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

8.2.1.14 GROUP BY Optimization
..............................

The most general way to satisfy a 'GROUP BY' clause is to scan the whole
table and create a new temporary table where all rows from each group
are consecutive, and then use this temporary table to discover groups
and apply aggregate functions (if any).  In some cases, MySQL is able to
do much better than that and to avoid creation of temporary tables by
using index access.

The most important preconditions for using indexes for 'GROUP BY' are
that all 'GROUP BY' columns reference attributes from the same index,
and that the index stores its keys in order (for example, this is a
'BTREE' index and not a 'HASH' index).  Whether use of temporary tables
can be replaced by index access also depends on which parts of an index
are used in a query, the conditions specified for these parts, and the
selected aggregate functions.

There are two ways to execute a 'GROUP BY' query through index access,
as detailed in the following sections.  In the first method, the
grouping operation is applied together with all range predicates (if
any).  The second method first performs a range scan, and then groups
the resulting tuples.

In MySQL, 'GROUP BY' is used for sorting, so the server may also apply
'ORDER BY' optimizations to grouping.  However, relying on implicit
'GROUP BY' sorting is deprecated.  See order-by-optimization.

   * loose-index-scan

   * tight-index-scan

*Loose Index Scan*

The most efficient way to process 'GROUP BY' is when an index is used to
directly retrieve the grouping columns.  With this access method, MySQL
uses the property of some index types that the keys are ordered (for
example, 'BTREE').  This property enables use of lookup groups in an
index without having to consider all keys in the index that satisfy all
'WHERE' conditions.  This access method considers only a fraction of the
keys in an index, so it is called a _loose index scan_.  When there is
no 'WHERE' clause, a loose index scan reads as many keys as the number
of groups, which may be a much smaller number than that of all keys.  If
the 'WHERE' clause contains range predicates (see the discussion of the
'range' join type in using-explain), a loose index scan looks up
the first key of each group that satisfies the range conditions, and
again reads the least possible number of keys.  This is possible under
the following conditions:

   * The query is over a single table.

   * The 'GROUP BY' names only columns that form a leftmost prefix of
     the index and no other columns.  (If, instead of 'GROUP BY', the
     query has a 'DISTINCT' clause, all distinct attributes refer to
     columns that form a leftmost prefix of the index.)  For example, if
     a table 't1' has an index on '(c1,c2,c3)', loose index scan is
     applicable if the query has 'GROUP BY c1, c2,'.  It is not
     applicable if the query has 'GROUP BY c2, c3' (the columns are not
     a leftmost prefix) or 'GROUP BY c1, c2, c4' ('c4' is not in the
     index).

   * The only aggregate functions used in the select list (if any) are
     'MIN()' and 'MAX()', and all of them refer to the same column.  The
     column must be in the index and must immediately follow the columns
     in the 'GROUP BY'.

   * Any other parts of the index than those from the 'GROUP BY'
     referenced in the query must be constants (that is, they must be
     referenced in equalities with constants), except for the argument
     of 'MIN()' or 'MAX()' functions.

   * For columns in the index, full column values must be indexed, not
     just a prefix.  For example, with 'c1 VARCHAR(20), INDEX (c1(10))',
     the index cannot be used for loose index scan.

If loose index scan is applicable to a query, the 'EXPLAIN'
output shows 'Using index for group-by' in the 'Extra' column.

Assume that there is an index 'idx(c1,c2,c3)' on table
't1(c1,c2,c3,c4)'.  The loose index scan access method can be used for
the following queries:

     SELECT c1, c2 FROM t1 GROUP BY c1, c2;
     SELECT DISTINCT c1, c2 FROM t1;
     SELECT c1, MIN(c2) FROM t1 GROUP BY c1;
     SELECT c1, c2 FROM t1 WHERE c1 < CONST GROUP BY c1, c2;
     SELECT MAX(c3), MIN(c3), c1, c2 FROM t1 WHERE c2 > CONST GROUP BY c1, c2;
     SELECT c2 FROM t1 WHERE c1 < CONST GROUP BY c1, c2;
     SELECT c1, c2 FROM t1 WHERE c3 = CONST GROUP BY c1, c2;

The following queries cannot be executed with this quick select method,
for the reasons given:

   * There are aggregate functions other than 'MIN()' or 'MAX()':

          SELECT c1, SUM(c2) FROM t1 GROUP BY c1;

   * The columns in the 'GROUP BY' clause do not form a leftmost prefix
     of the index:

          SELECT c1, c2 FROM t1 GROUP BY c2, c3;

   * The query refers to a part of a key that comes after the 'GROUP BY'
     part, and for which there is no equality with a constant:

          SELECT c1, c3 FROM t1 GROUP BY c1, c2;

     Were the query to include 'WHERE c3 = CONST', loose index scan
     could be used.

The loose index scan access method can be applied to other forms of
aggregate function references in the select list, in addition to the
'MIN()' and 'MAX()' references already supported:

   * 'AVG(DISTINCT)', 'SUM(DISTINCT)', and 'COUNT(DISTINCT)' are
     supported.  'AVG(DISTINCT)' and 'SUM(DISTINCT)' take a single
     argument.  'COUNT(DISTINCT)' can have more than one column
     argument.

   * There must be no 'GROUP BY' or 'DISTINCT' clause in the query.

   * The loose scan limitations described earlier still apply.

Assume that there is an index 'idx(c1,c2,c3)' on table
't1(c1,c2,c3,c4)'.  The loose index scan access method can be used for
the following queries:

     SELECT COUNT(DISTINCT c1), SUM(DISTINCT c1) FROM t1;

     SELECT COUNT(DISTINCT c1, c2), COUNT(DISTINCT c2, c1) FROM t1;

*Tight Index Scan*

A tight index scan may be either a full index scan or a range index
scan, depending on the query conditions.

When the conditions for a loose index scan are not met, it still may be
possible to avoid creation of temporary tables for 'GROUP BY' queries.
If there are range conditions in the 'WHERE' clause, this method reads
only the keys that satisfy these conditions.  Otherwise, it performs an
index scan.  Because this method reads all keys in each range defined by
the 'WHERE' clause, or scans the whole index if there are no range
conditions, we term it a _tight index scan_.  With a tight index scan,
the grouping operation is performed only after all keys that satisfy the
range conditions have been found.

For this method to work, it is sufficient that there is a constant
equality condition for all columns in a query referring to parts of the
key coming before or in between parts of the 'GROUP BY' key.  The
constants from the equality conditions fill in any 'gaps' in the search
keys so that it is possible to form complete prefixes of the index.
These index prefixes then can be used for index lookups.  If we require
sorting of the 'GROUP BY' result, and it is possible to form search keys
that are prefixes of the index, MySQL also avoids extra sorting
operations because searching with prefixes in an ordered index already
retrieves all the keys in order.

Assume that there is an index 'idx(c1,c2,c3)' on table
't1(c1,c2,c3,c4)'.  The following queries do not work with the loose
index scan access method described earlier, but still work with the
tight index scan access method.

   * There is a gap in the 'GROUP BY', but it is covered by the
     condition 'c2 = 'a'':

          SELECT c1, c2, c3 FROM t1 WHERE c2 = 'a' GROUP BY c1, c3;

   * The 'GROUP BY' does not begin with the first part of the key, but
     there is a condition that provides a constant for that part:

          SELECT c1, c2, c3 FROM t1 WHERE c1 = 'a' GROUP BY c2, c3;

8.2.1.15 DISTINCT Optimization
..............................

'DISTINCT' combined with 'ORDER BY' needs a temporary table in many
cases.

Because 'DISTINCT' may use 'GROUP BY', learn how MySQL works with
columns in 'ORDER BY' or 'HAVING' clauses that are not part of the
selected columns.  See group-by-handling.

In most cases, a 'DISTINCT' clause can be considered as a special case
of 'GROUP BY'.  For example, the following two queries are equivalent:

     SELECT DISTINCT c1, c2, c3 FROM t1
     WHERE c1 > CONST;

     SELECT c1, c2, c3 FROM t1
     WHERE c1 > CONST GROUP BY c1, c2, c3;

Due to this equivalence, the optimizations applicable to 'GROUP BY'
queries can be also applied to queries with a 'DISTINCT' clause.  Thus,
for more details on the optimization possibilities for 'DISTINCT'
queries, see group-by-optimization.

When combining 'LIMIT ROW_COUNT' with 'DISTINCT', MySQL stops as soon as
it finds ROW_COUNT unique rows.

If you do not use columns from all tables named in a query, MySQL stops
scanning any unused tables as soon as it finds the first match.  In the
following case, assuming that 't1' is used before 't2' (which you can
check with 'EXPLAIN'), MySQL stops reading from 't2'
(for any particular row in 't1') when it finds the first row in 't2':

     SELECT DISTINCT t1.a FROM t1, t2 where t1.a=t2.a;

8.2.1.16 LIMIT Query Optimization
.................................

If you need only a specified number of rows from a result set, use a
'LIMIT' clause in the query, rather than fetching the whole result set
and throwing away the extra data.

MySQL sometimes optimizes a query that has a 'LIMIT ROW_COUNT' clause
and no 'HAVING' clause:

   * If you select only a few rows with 'LIMIT', MySQL uses indexes in
     some cases when normally it would prefer to do a full table scan.

   * If you combine 'LIMIT ROW_COUNT' with 'ORDER BY', MySQL stops
     sorting as soon as it has found the first ROW_COUNT rows of the
     sorted result, rather than sorting the entire result.  If ordering
     is done by using an index, this is very fast.  If a filesort must
     be done, all rows that match the query without the 'LIMIT' clause
     are selected, and most or all of them are sorted, before the first
     ROW_COUNT are found.  After the initial rows have been found, MySQL
     does not sort any remainder of the result set.

     One manifestation of this behavior is that an 'ORDER BY' query with
     and without 'LIMIT' may return rows in different order, as
     described later in this section.

   * If you combine 'LIMIT ROW_COUNT' with 'DISTINCT', MySQL stops as
     soon as it finds ROW_COUNT unique rows.

   * In some cases, a 'GROUP BY' can be resolved by reading the index in
     order (or doing a sort on the index), then calculating summaries
     until the index value changes.  In this case, 'LIMIT ROW_COUNT'
     does not calculate any unnecessary 'GROUP BY' values.

   *
     As soon as MySQL has sent the required number of rows to the
     client, it aborts the query unless you are using
     'SQL_CALC_FOUND_ROWS'.  In that case, the number of rows can be
     retrieved with 'SELECT FOUND_ROWS()'.  See
     information-functions.

   * 'LIMIT 0' quickly returns an empty set.  This can be useful for
     checking the validity of a query.  It can also be employed to
     obtain the types of the result columns within applications that use
     a MySQL API that makes result set metadata available.  With the
     'mysql' client program, you can use the
     '--column-type-info' option to display result column types.

   * If the server uses temporary tables to resolve a query, it uses the
     'LIMIT ROW_COUNT' clause to calculate how much space is required.

   * If an index is not used for 'ORDER BY' but a 'LIMIT' clause is also
     present, the optimizer may be able to avoid using a merge file and
     sort the rows in memory using an in-memory 'filesort' operation.
     For details, see order-by-filesort-in-memory.

If multiple rows have identical values in the 'ORDER BY' columns, the
server is free to return those rows in any order, and may do so
differently depending on the overall execution plan.  In other words,
the sort order of those rows is nondeterministic with respect to the
nonordered columns.

One factor that affects the execution plan is 'LIMIT', so an 'ORDER BY'
query with and without 'LIMIT' may return rows in different orders.
Consider this query, which is sorted by the 'category' column but
nondeterministic with respect to the 'id' and 'rating' columns:

     mysql> SELECT * FROM ratings ORDER BY category;
     +----+----------+--------+
     | id | category | rating |
     +----+----------+--------+
     |  1 |        1 |    4.5 |
     |  5 |        1 |    3.2 |
     |  3 |        2 |    3.7 |
     |  4 |        2 |    3.5 |
     |  6 |        2 |    3.5 |
     |  2 |        3 |    5.0 |
     |  7 |        3 |    2.7 |
     +----+----------+--------+

Including 'LIMIT' may affect order of rows within each 'category' value.
For example, this is a valid query result:

     mysql> SELECT * FROM ratings ORDER BY category LIMIT 5;
     +----+----------+--------+
     | id | category | rating |
     +----+----------+--------+
     |  1 |        1 |    4.5 |
     |  5 |        1 |    3.2 |
     |  4 |        2 |    3.5 |
     |  3 |        2 |    3.7 |
     |  6 |        2 |    3.5 |
     +----+----------+--------+

In each case, the rows are sorted by the 'ORDER BY' column, which is all
that is required by the SQL standard.

If it is important to ensure the same row order with and without
'LIMIT', include additional columns in the 'ORDER BY' clause to make the
order deterministic.  For example, if 'id' values are unique, you can
make rows for a given 'category' value appear in 'id' order by sorting
like this:

     mysql> SELECT * FROM ratings ORDER BY category, id;
     +----+----------+--------+
     | id | category | rating |
     +----+----------+--------+
     |  1 |        1 |    4.5 |
     |  5 |        1 |    3.2 |
     |  3 |        2 |    3.7 |
     |  4 |        2 |    3.5 |
     |  6 |        2 |    3.5 |
     |  2 |        3 |    5.0 |
     |  7 |        3 |    2.7 |
     +----+----------+--------+

     mysql> SELECT * FROM ratings ORDER BY category, id LIMIT 5;
     +----+----------+--------+
     | id | category | rating |
     +----+----------+--------+
     |  1 |        1 |    4.5 |
     |  5 |        1 |    3.2 |
     |  3 |        2 |    3.7 |
     |  4 |        2 |    3.5 |
     |  6 |        2 |    3.5 |
     +----+----------+--------+

8.2.1.17 Function Call Optimization
...................................

MySQL functions are tagged internally as deterministic or
nondeterministic.  A function is nondeterministic if, given fixed values
for its arguments, it can return different results for different
invocations.  Examples of nondeterministic functions: 'RAND()',
'UUID()'.

If a function is tagged nondeterministic, a reference to it in a 'WHERE'
clause is evaluated for every row (when selecting from one table) or
combination of rows (when selecting from a multiple-table join).

MySQL also determines when to evaluate functions based on types of
arguments, whether the arguments are table columns or constant values.
A deterministic function that takes a table column as argument must be
evaluated whenever that column changes value.

Nondeterministic functions may affect query performance.  For example,
some optimizations may not be available, or more locking might be
required.  The following discussion uses 'RAND()' but applies to other
nondeterministic functions as well.

Suppose that a table 't' has this definition:

     CREATE TABLE t (id INT NOT NULL PRIMARY KEY, col_a VARCHAR(100));

Consider these two queries:

     SELECT * FROM t WHERE id = POW(1,2);
     SELECT * FROM t WHERE id = FLOOR(1 + RAND() * 49);

Both queries appear to use a primary key lookup because of the equality
comparison against the primary key, but that is true only for the first
of them:

   * The first query always produces a maximum of one row because
     'POW()' with constant arguments is a constant value and is used for
     index lookup.

   * The second query contains an expression that uses the
     nondeterministic function 'RAND()', which is not constant in the
     query but in fact has a new value for every row of table 't'.
     Consequently, the query reads every row of the table, evaluates the
     predicate for each row, and outputs all rows for which the primary
     key matches the random value.  This might be zero, one, or multiple
     rows, depending on the 'id' column values and the values in the
     'RAND()' sequence.

The effects of nondeterminism are not limited to 'SELECT'.
statements.  This 'UPDATE' statement uses a
nondeterministic function to select rows to be modified:

     UPDATE t SET col_a = SOME_EXPR WHERE id = FLOOR(1 + RAND() * 49);

Presumably the intent is to update at most a single row for which the
primary key matches the expression.  However, it might update zero, one,
or multiple rows, depending on the 'id' column values and the values in
the 'RAND()' sequence.

The behavior just described has implications for performance and
replication:

   * Because a nondeterministic function does not produce a constant
     value, the optimizer cannot use strategies that might otherwise be
     applicable, such as index lookups.  The result may be a table scan.

   * 'InnoDB' might escalate to a range-key lock rather than taking a
     single row lock for one matching row.

   * Updates that do not execute deterministically are unsafe for
     replication.

The difficulties stem from the fact that the 'RAND()' function is
evaluated once for every row of the table.  To avoid multiple function
evaluations, use one of these techniques:

   * Move the expression containing the nondeterministic function to a
     separate statement, saving the value in a variable.  In the
     original statement, replace the expression with a reference to the
     variable, which the optimizer can treat as a constant value:

          SET @keyval = FLOOR(1 + RAND() * 49);
          UPDATE t SET col_a = SOME_EXPR WHERE id = @keyval;

   * Assign the random value to a variable in a derived table.  This
     technique causes the variable to be assigned a value, once, prior
     to its use in the comparison in the 'WHERE' clause:

          SET optimizer_switch = 'derived_merge=off';
          UPDATE t, (SELECT @keyval := FLOOR(1 + RAND() * 49)) AS dt
          SET col_a = SOME_EXPR WHERE id = @keyval;

As mentioned previously, a nondeterministic expression in the 'WHERE'
clause might prevent optimizations and result in a table scan.  However,
it may be possible to partially optimize the 'WHERE' clause if other
expressions are deterministic.  For example:

     SELECT * FROM t WHERE partial_key=5 AND some_column=RAND();

If the optimizer can use 'partial_key' to reduce the set of rows
selected, 'RAND()' is executed fewer times, which diminishes the effect
of nondeterminism on optimization.

8.2.1.18 Row Constructor Expression Optimization
................................................

Row constructors permit simultaneous comparisons of multiple values.
For example, these two statements are semantically equivalent:

     SELECT * FROM t1 WHERE (column1,column2) = (1,1);
     SELECT * FROM t1 WHERE column1 = 1 AND column2 = 1;

In addition, the optimizer handles both expressions the same way.

The optimizer is less likely to use available indexes if the row
constructor columns do not cover the prefix of an index.  Consider the
following table, which has a primary key on '(c1, c2, c3)':

     CREATE TABLE t1 (
       c1 INT, c2 INT, c3 INT, c4 CHAR(100),
       PRIMARY KEY(c1,c2,c3)
     );

In this query, the 'WHERE' clause uses all columns in the index.
However, the row constructor itself does not cover an index prefix, with
the result that the optimizer uses only 'c1' ('key_len=4', the size of
'c1'):

     mysql> EXPLAIN SELECT * FROM t1
            WHERE c1=1 AND (c2,c3) > (1,1)\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: t1
        partitions: NULL
              type: ref
     possible_keys: PRIMARY
               key: PRIMARY
           key_len: 4
               ref: const
              rows: 3
          filtered: 100.00
             Extra: Using where

In such cases, rewriting the row constructor expression using an
equivalent nonconstructor expression may result in more complete index
use.  For the given query, the row constructor and equivalent
nonconstructor expressions are:

     (c2,c3) > (1,1)
     c2 > 1 OR ((c2 = 1) AND (c3 > 1))

Rewriting the query to use the nonconstructor expression results in the
optimizer using all three columns in the index ('key_len=12'):

     mysql> EXPLAIN SELECT * FROM t1
            WHERE c1 = 1 AND (c2 > 1 OR ((c2 = 1) AND (c3 > 1)))\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: t1
        partitions: NULL
              type: range
     possible_keys: PRIMARY
               key: PRIMARY
           key_len: 12
               ref: NULL
              rows: 3
          filtered: 100.00
             Extra: Using where

Thus, for better results, avoid mixing row constructors with 'AND'/'OR'
expressions.  Use one or the other.

Under certain conditions, the optimizer can apply the range access
method to 'IN()' expressions that have row constructor arguments.  See
row-constructor-range-optimization.

8.2.1.19 Avoiding Full Table Scans
..................................

The output from 'EXPLAIN' shows 'ALL' in the 'type'
column when MySQL uses a full table scan to resolve a query.  This
usually happens under the following conditions:

   * The table is so small that it is faster to perform a table scan
     than to bother with a key lookup.  This is common for tables with
     fewer than 10 rows and a short row length.

   * There are no usable restrictions in the 'ON' or 'WHERE' clause for
     indexed columns.

   * You are comparing indexed columns with constant values and MySQL
     has calculated (based on the index tree) that the constants cover
     too large a part of the table and that a table scan would be
     faster.  See where-optimization.

   * You are using a key with low cardinality (many rows match the key
     value) through another column.  In this case, MySQL assumes that by
     using the key it probably will do many key lookups and that a table
     scan would be faster.

For small tables, a table scan often is appropriate and the performance
impact is negligible.  For large tables, try the following techniques to
avoid having the optimizer incorrectly choose a table scan:

   * Use 'ANALYZE TABLE TBL_NAME' to update the key distributions for
     the scanned table.  See analyze-table.

   * Use 'FORCE INDEX' for the scanned table to tell MySQL that table
     scans are very expensive compared to using the given index:

          SELECT * FROM t1, t2 FORCE INDEX (INDEX_FOR_COLUMN)
            WHERE t1.COL_NAME=t2.COL_NAME;

     See index-hints.

   * Start 'mysqld' with the '--max-seeks-for-key=1000'
     option or use 'SET max_seeks_for_key=1000' to tell the optimizer to
     assume that no key scan causes more than 1,000 key seeks.  See
     server-system-variables.

8.2.2 Optimizing Subqueries, Derived Tables, and View References
----------------------------------------------------------------

The MySQL query optimizer has different strategies available to evaluate
subqueries.  For 'IN' (or '=ANY') subqueries, the optimizer has these
choices:

   * Semi-join

   * Materialization

   * 'EXISTS' strategy

For 'NOT IN' (or '<>ALL') subqueries, the optimizer has these choices:

   * Materialization

   * 'EXISTS' strategy

For derived tables (subqueries in the 'FROM' clause), the optimizer has
these choices:

   * Merge the derived table into the outer query block

   * Materialize the derived table to an internal temporary table

For view references, the optimizer has the same choices as for derived
tables.

The following discussion provides more information about the preceding
optimization strategies.

*Note*:

A limitation on 'UPDATE' and 'DELETE'.
statements that use a subquery to modify a single table is that the
optimizer does not use semi-join or materialization subquery
optimizations.  As a workaround, try rewriting them as multiple-table
'UPDATE' and 'DELETE' statements that use
a join rather than a subquery.

8.2.2.1 Optimizing Subqueries, Derived Tables, and View References with Semi-Join Transformations
.................................................................................................

The optimizer uses semi-join strategies to improve subquery execution,
as described in this section.

For an inner join between two tables, the join returns a row from one
table as many times as there are matches in the other table.  But for
some questions, the only information that matters is whether there is a
match, not the number of matches.  Suppose that there are tables named
'class' and 'roster' that list classes in a course curriculum and class
rosters (students enrolled in each class), respectively.  To list the
classes that actually have students enrolled, you could use this join:

     SELECT class.class_num, class.class_name
     FROM class INNER JOIN roster
     WHERE class.class_num = roster.class_num;

However, the result lists each class once for each enrolled student.
For the question being asked, this is unnecessary duplication of
information.

Assuming that 'class_num' is a primary key in the 'class' table,
duplicate suppression is possible by using 'SELECT DISTINCT',
but it is inefficient to generate all matching rows first only
to eliminate duplicates later.

The same duplicate-free result can be obtained by using a subquery:

     SELECT class_num, class_name
     FROM class
     WHERE class_num IN (SELECT class_num FROM roster);

Here, the optimizer can recognize that the 'IN' clause requires the
subquery to return only one instance of each class number from the
'roster' table.  In this case, the query can use a _semi-join_; that is,
an operation that returns only one instance of each row in 'class' that
is matched by rows in 'roster'.

Outer join and inner join syntax is permitted in the outer query
specification, and table references may be base tables, derived tables,
or view references.

In MySQL, a subquery must satisfy these criteria to be handled as a
semi-join:

   * It must be an 'IN' (or '=ANY') subquery that appears at the top
     level of the 'WHERE' or 'ON' clause, possibly as a term in an 'AND'
     expression.  For example:

          SELECT ...
          FROM ot1, ...
          WHERE (oe1, ...) IN (SELECT ie1, ... FROM it1, ... WHERE ...);

     Here, 'ot_I' and 'it_I' represent tables in the outer and inner
     parts of the query, and 'oe_I' and 'ie_I' represent expressions
     that refer to columns in the outer and inner tables.

   * It must be a single 'SELECT' without 'UNION'
     constructs.

   * It must not contain a 'GROUP BY' or 'HAVING' clause.

   * It must not be implicitly grouped (it must contain no aggregate
     functions).

   * It must not have 'ORDER BY' with 'LIMIT'.

   * The statement must not use the 'STRAIGHT_JOIN' join type in the
     outer query.

   * The 'STRAIGHT_JOIN' modifier must not be present.

   * The number of outer and inner tables together must be less than the
     maximum number of tables permitted in a join.

The subquery may be correlated or uncorrelated.  'DISTINCT' is
permitted, as is 'LIMIT' unless 'ORDER BY' is also used.

If a subquery meets the preceding criteria, MySQL converts it to a
semi-join and makes a cost-based choice from these strategies:

   * Convert the subquery to a join, or use table pullout and run the
     query as an inner join between subquery tables and outer tables.
     Table pullout pulls a table out from the subquery to the outer
     query.

   * Duplicate Weedout: Run the semi-join as if it was a join and remove
     duplicate records using a temporary table.

   * FirstMatch: When scanning the inner tables for row combinations and
     there are multiple instances of a given value group, choose one
     rather than returning them all.  This "shortcuts" scanning and
     eliminates production of unnecessary rows.

   * LooseScan: Scan a subquery table using an index that enables a
     single value to be chosen from each subquery's value group.

   * Materialize the subquery into an indexed temporary table that is
     used to perform a join, where the index is used to remove
     duplicates.  The index might also be used later for lookups when
     joining the temporary table with the outer tables; if not, the
     table is scanned.  For more information about materialization, see
     subquery-materialization.

Each of these strategies can be enabled or disabled using the following
'optimizer_switch' system variable flags:

   * The 'semijoin' flag controls whether semi-joins are used.

   * If 'semijoin' is enabled, the 'firstmatch', 'loosescan',
     'duplicateweedout', and 'materialization' flags enable finer
     control over the permitted semi-join strategies.

   * If the 'duplicateweedout' semi-join strategy is disabled, it is not
     used unless all other applicable strategies are also disabled.

   * If 'duplicateweedout' is disabled, on occasion the optimizer may
     generate a query plan that is far from optimal.  This occurs due to
     heuristic pruning during greedy search, which can be avoided by
     setting 'optimizer_prune_level=0'.

These flags are enabled by default.  See
switchable-optimizations.

The optimizer minimizes differences in handling of views and derived
tables (subqueries in the 'FROM' clause).  This affects queries that use
the 'STRAIGHT_JOIN' modifier and a view with an 'IN' subquery that can
be converted to a semi-join.  The following query illustrates this
because the change in processing causes a change in transformation, and
thus a different execution strategy:

     CREATE VIEW v AS
     SELECT *
     FROM t1
     WHERE a IN (SELECT b
                FROM t2);

     SELECT STRAIGHT_JOIN *
     FROM t3 JOIN v ON t3.x = v.a;

The optimizer first looks at the view and converts the 'IN' subquery to
a semi-join, then checks whether it is possible to merge the view into
the outer query.  Because the 'STRAIGHT_JOIN' modifier in the outer
query prevents semi-join, the optimizer refuses the merge, causing
derived table evaluation using a materialized table.

'EXPLAIN' output indicates the use of semi-join
strategies as follows:

   * Semi-joined tables show up in the outer select.  For extended
     'EXPLAIN' output, the text displayed by a following
     'SHOW WARNINGS' shows the rewritten query, which
     displays the semi-join structure.  (See explain-extended.)
     From this you can get an idea about which tables were pulled out of
     the semi-join.  If a subquery was converted to a semi-join, you
     will see that the subquery predicate is gone and its tables and
     'WHERE' clause were merged into the outer query join list and
     'WHERE' clause.

   * Temporary table use for Duplicate Weedout is indicated by 'Start
     temporary' and 'End temporary' in the 'Extra' column.  Tables that
     were not pulled out and are in the range of 'EXPLAIN'
     output rows covered by 'Start temporary' and 'End
     temporary' have their 'rowid' in the temporary table.

   * 'FirstMatch(TBL_NAME)' in the 'Extra' column indicates join
     shortcutting.

   * 'LooseScan(M..N)' in the 'Extra' column indicates use of the
     LooseScan strategy.  M and N are key part numbers.

   * Temporary table use for materialization is indicated by rows with a
     'select_type' value of 'MATERIALIZED' and rows with a 'table' value
     of '<subqueryN>'.

8.2.2.2 Optimizing Subqueries with Materialization
..................................................

The optimizer uses materialization to enable more efficient subquery
processing.  Materialization speeds up query execution by generating a
subquery result as a temporary table, normally in memory.  The first
time MySQL needs the subquery result, it materializes that result into a
temporary table.  Any subsequent time the result is needed, MySQL refers
again to the temporary table.  The optimizer may index the table with a
hash index to make lookups fast and inexpensive.  The index is unique,
which eliminates duplicates and makes the table smaller.

Subquery materialization uses an in-memory temporary table when
possible, falling back to on-disk storage if the table becomes too
large.  See internal-temporary-tables.

If materialization is not used, the optimizer sometimes rewrites a
noncorrelated subquery as a correlated subquery.  For example, the
following 'IN' subquery is noncorrelated (WHERE_CONDITION involves only
columns from 't2' and not 't1'):

     SELECT * FROM t1
     WHERE t1.a IN (SELECT t2.b FROM t2 WHERE WHERE_CONDITION);

The optimizer might rewrite this as an 'EXISTS' correlated subquery:

     SELECT * FROM t1
     WHERE EXISTS (SELECT t2.b FROM t2 WHERE WHERE_CONDITION AND t1.a=t2.b);

Subquery materialization using a temporary table avoids such rewrites
and makes it possible to execute the subquery only once rather than once
per row of the outer query.

For subquery materialization to be used in MySQL, the 'optimizer_switch'
system variable 'materialization' flag must be enabled.  (See
switchable-optimizations.)  With the 'materialization' flag enabled,
materialization applies to subquery predicates that appear anywhere (in
the select list, 'WHERE', 'ON', 'GROUP BY', 'HAVING', or 'ORDER BY'),
for predicates that fall into any of these use cases:

   * The predicate has this form, when no outer expression OE_I or inner
     expression IE_I is nullable.  N is 1 or larger.

          (OE_1, OE_2, ..., OE_N) [NOT] IN (SELECT IE_1, I_2, ..., IE_N ...)

   * The predicate has this form, when there is a single outer
     expression OE and inner expression IE.  The expressions can be
     nullable.

          OE [NOT] IN (SELECT IE ...)

   * The predicate is 'IN' or 'NOT IN' and a result of 'UNKNOWN'
     ('NULL') has the same meaning as a result of 'FALSE'.

The following examples illustrate how the requirement for equivalence of
'UNKNOWN' and 'FALSE' predicate evaluation affects whether subquery
materialization can be used.  Assume that WHERE_CONDITION involves
columns only from 't2' and not 't1' so that the subquery is
noncorrelated.

This query is subject to materialization:

     SELECT * FROM t1
     WHERE t1.a IN (SELECT t2.b FROM t2 WHERE WHERE_CONDITION);

Here, it does not matter whether the 'IN' predicate returns 'UNKNOWN' or
'FALSE'.  Either way, the row from 't1' is not included in the query
result.

An example where subquery materialization is not used is the following
query, where 't2.b' is a nullable column:

     SELECT * FROM t1
     WHERE (t1.a,t1.b) NOT IN (SELECT t2.a,t2.b FROM t2
                               WHERE WHERE_CONDITION);

The following restrictions apply to the use of subquery materialization:

   * The types of the inner and outer expressions must match.  For
     example, the optimizer might be able to use materialization if both
     expressions are integer or both are decimal, but cannot if one
     expression is integer and the other is decimal.

   * The inner expression cannot be a 'BLOB'.

Use of 'EXPLAIN' with a query provides some indication
of whether the optimizer uses subquery materialization.  Compared to
query execution that does not use materialization, 'select_type' may
change from 'DEPENDENT SUBQUERY' to 'SUBQUERY'.  This indicates that,
for a subquery that would be executed once per outer row,
materialization enables the subquery to be executed just once.  In
addition, for extended 'EXPLAIN' output, the text
displayed by a following 'SHOW WARNINGS' includes
'materialize' and 'materialized-subquery'.

8.2.2.3 Optimizing Derived Tables and View References
.....................................................

The optimizer can handle derived tables (subqueries in the 'FROM'
clause) references using two strategies:

   * Merge the derived table into the outer query block

   * Materialize the derived table to an internal temporary table

The optimizer uses the same strategies to handle view references.

Example 1:

     SELECT * FROM (SELECT * FROM t1) AS derived_t1;

With merging, that query is executed similar to:

     SELECT * FROM t1;

Example 2:

     SELECT *
       FROM t1 JOIN (SELECT t2.f1 FROM t2) AS derived_t2 ON t1.f2=derived_t2.f1
       WHERE t1.f1 > 0;

With merging, that query is executed similar to:

     SELECT t1.*, t2.f1
       FROM t1 JOIN t2 ON t1.f2=t2.f1
       WHERE t1.f1 > 0;

With materialization, 'derived_t1' and 'derived_t2' are treated as a
separate table within their respective queries.

The optimizer handles derived tables and view references the same way:
It avoids unnecessary materialization whenever possible, which enables
pushing down conditions from the outer query to derived tables and
produces more efficient execution plans.  (For an example, see
subquery-materialization.)

If merging would result in an outer query block that references more
than 61 base tables, the optimizer chooses materialization instead.

The optimizer propagates an 'ORDER BY' clause in a derived table or view
reference to the outer query block if these conditions are all true:

   * The outer query is not grouped or aggregated.

   * The outer query does not specify 'DISTINCT', 'HAVING', or 'ORDER
     BY'.

   * The outer query has this derived table or view reference as the
     only source in the 'FROM' clause.

Otherwise, the optimizer ignores the 'ORDER BY' clause.

The following means are available to influence whether the optimizer
attempts to merge derived tables and view references into the outer
query block:

   * The 'derived_merge' flag of the 'optimizer_switch' system variable
     can be used, assuming that no other rule prevents merging.  See
     switchable-optimizations.  By default, the flag is enabled
     to permit merging.  Disabling the flag prevents merging and avoids
     'ER_UPDATE_TABLE_USED' errors.

     The 'derived_merge' flag also applies to views that contain no
     'ALGORITHM' clause.  Thus, if an 'ER_UPDATE_TABLE_USED' error
     occurs for a view reference that uses an expression equivalent to
     the subquery, adding 'ALGORITHM=TEMPTABLE' to the view definition
     prevents merging and takes precedence over the 'derived_merge'
     value.

   * It is possible to disable merging by using in the subquery any
     constructs that prevent merging, although these are not as explicit
     in their effect on materialization.  Constructs that prevent
     merging are the same for derived tables and view references:

        * Aggregate functions ('SUM()', 'MIN()', 'MAX()', 'COUNT()', and
          so forth)

        * 'DISTINCT'

        * 'GROUP BY'

        * 'HAVING'

        * 'LIMIT'

        * 'UNION' or 'UNION ALL'.

        * Subqueries in the select list

        * Assignments to user variables

        * Refererences only to literal values (in this case, there is no
          underlying table)

The 'derived_merge' flag also applies to views that contain no
'ALGORITHM' clause.  Thus, if an 'ER_UPDATE_TABLE_USED' error occurs for
a view reference that uses an expression equivalent to the subquery,
adding 'ALGORITHM=TEMPTABLE' to the view definition prevents merging and
takes precedence over the current 'derived_merge' value.

If the optimizer chooses the materialization strategy rather than
merging for a derived table, it handles the query as follows:

   * The optimizer postpones derived table materialization until its
     contents are needed during query execution.  This improves
     performance because delaying materialization may result in not
     having to do it at all.  Consider a query that joins the result of
     a derived table to another table: If the optimizer processes that
     other table first and finds that it returns no rows, the join need
     not be carried out further and the optimizer can completely skip
     materializing the derived table.

   * During query execution, the optimizer may add an index to a derived
     table to speed up row retrieval from it.

Consider the following 'EXPLAIN' statement, for which a
subquery appears in the 'FROM' clause of a 'SELECT'.
query:

     EXPLAIN SELECT * FROM (SELECT * FROM t1) AS derived_t1;

The optimizer avoids materializing the subquery by delaying it until the
result is needed during 'SELECT' execution.  In this
case, the query is not executed (because it occurs in an
'EXPLAIN' statement), so the result is never needed.

Even for queries that are executed, delay of subquery materialization
may enable the optimizer to avoid materialization entirely.  When this
happens, query execution is quicker by the time needed to perform
materialization.  Consider the following query, which joins the result
of a subquery in the 'FROM' clause to another table:

     SELECT *
       FROM t1 JOIN (SELECT t2.f1 FROM t2) AS derived_t2
               ON t1.f2=derived_t2.f1
       WHERE t1.f1 > 0;

If the optimization processes 't1' first and the 'WHERE' clause produces
an empty result, the join must necessarily be empty and the subquery
need not be materialized.

For cases when a derived table requires materialization, the optimizer
may add an index to the materialized table to speed up access to it.  If
such an index enables 'ref' access to the table, it can greatly reduce
amount of data read during query execution.  Consider the following
query:

     SELECT *
      FROM t1 JOIN (SELECT DISTINCT f1 FROM t2) AS derived_t2
              ON t1.f1=derived_t2.f1;

The optimizer constructs an index over column 'f1' from 'derived_t2' if
doing so would enable use of 'ref' access for the lowest cost execution
plan.  After adding the index, the optimizer can treat the materialized
derived table the same as a regular table with an index, and it benefits
similarly from the generated index.  The overhead of index creation is
negligible compared to the cost of query execution without the index.
If 'ref' access would result in higher cost than some other access
method, the optimizer creates no index and loses nothing.

For optimizer trace output, a merged derived table or view reference is
not shown as a node.  Only its underlying tables appear in the top
query's plan.

8.2.2.4 Optimizing Subqueries with the EXISTS Strategy
......................................................

Certain optimizations are applicable to comparisons that use the 'IN'
(or '=ANY') operator to test subquery results.  This section discusses
these optimizations, particularly with regard to the challenges that
'NULL' values present.  The last part of the discussion suggests how you
can help the optimizer.

Consider the following subquery comparison:

     OUTER_EXPR IN (SELECT INNER_EXPR FROM ... WHERE SUBQUERY_WHERE)

MySQL evaluates queries 'from outside to inside.' That is, it first
obtains the value of the outer expression OUTER_EXPR, and then runs the
subquery and captures the rows that it produces.

A very useful optimization is to 'inform' the subquery that the only
rows of interest are those where the inner expression INNER_EXPR is
equal to OUTER_EXPR.  This is done by pushing down an appropriate
equality into the subquery's 'WHERE' clause to make it more restrictive.
The converted comparison looks like this:

     EXISTS (SELECT 1 FROM ... WHERE SUBQUERY_WHERE AND OUTER_EXPR=INNER_EXPR)

After the conversion, MySQL can use the pushed-down equality to limit
the number of rows it must examine to evaluate the subquery.

More generally, a comparison of N values to a subquery that returns
N-value rows is subject to the same conversion.  If OE_I and IE_I
represent corresponding outer and inner expression values, this subquery
comparison:

     (OE_1, ..., OE_N) IN
       (SELECT IE_1, ..., IE_N FROM ... WHERE SUBQUERY_WHERE)

Becomes:

     EXISTS (SELECT 1 FROM ... WHERE SUBQUERY_WHERE
                               AND OE_1 = IE_1
                               AND ...
                               AND OE_N = IE_N)

For simplicity, the following discussion assumes a single pair of outer
and inner expression values.

The conversion just described has its limitations.  It is valid only if
we ignore possible 'NULL' values.  That is, the 'pushdown' strategy
works as long as both of these conditions are true:

   * OUTER_EXPR and INNER_EXPR cannot be 'NULL'.

   * You need not distinguish 'NULL' from 'FALSE' subquery results.  If
     the subquery is a part of an 'OR' or 'AND' expression in the
     'WHERE' clause, MySQL assumes that you do not care.  Another
     instance where the optimizer notices that 'NULL' and 'FALSE'
     subquery results need not be distinguished is this construct:

          ... WHERE OUTER_EXPR IN (SUBQUERY)

     In this case, the 'WHERE' clause rejects the row whether 'IN
     (SUBQUERY)' returns 'NULL' or 'FALSE'.

When either or both of those conditions do not hold, optimization is
more complex.

Suppose that OUTER_EXPR is known to be a non-'NULL' value but the
subquery does not produce a row such that OUTER_EXPR = INNER_EXPR.  Then
'OUTER_EXPR IN (SELECT ...)' evaluates as follows:

   * 'NULL', if the 'SELECT' produces any row where
     INNER_EXPR is 'NULL'

   * 'FALSE', if the 'SELECT' produces only non-'NULL'
     values or produces nothing

In this situation, the approach of looking for rows with 'OUTER_EXPR =
INNER_EXPR' is no longer valid.  It is necessary to look for such rows,
but if none are found, also look for rows where INNER_EXPR is 'NULL'.
Roughly speaking, the subquery can be converted to something like this:

     EXISTS (SELECT 1 FROM ... WHERE SUBQUERY_WHERE AND
             (OUTER_EXPR=INNER_EXPR OR INNER_EXPR IS NULL))

The need to evaluate the extra 'IS NULL' condition is why MySQL has the
'ref_or_null' access method:

     mysql> EXPLAIN
            SELECT OUTER_EXPR IN (SELECT t2.maybe_null_key
                                  FROM t2, t3 WHERE ...)
            FROM t1;
     *************************** 1. row ***************************
                id: 1
       select_type: PRIMARY
             table: t1
     ...
     *************************** 2. row ***************************
                id: 2
       select_type: DEPENDENT SUBQUERY
             table: t2
              type: ref_or_null
     possible_keys: maybe_null_key
               key: maybe_null_key
           key_len: 5
               ref: func
              rows: 2
             Extra: Using where; Using index
     ...

The 'unique_subquery' and 'index_subquery' subquery-specific access
methods also have 'or 'NULL'' variants.

The additional 'OR ... IS NULL' condition makes query execution slightly
more complicated (and some optimizations within the subquery become
inapplicable), but generally this is tolerable.

The situation is much worse when OUTER_EXPR can be 'NULL'.  According to
the SQL interpretation of 'NULL' as 'unknown value,' 'NULL IN (SELECT
INNER_EXPR ...)' should evaluate to:

   * 'NULL', if the 'SELECT' produces any rows

   * 'FALSE', if the 'SELECT' produces no rows

For proper evaluation, it is necessary to be able to check whether the
'SELECT' has produced any rows at all, so 'OUTER_EXPR =
INNER_EXPR' cannot be pushed down into the subquery.  This is a problem
because many real world subqueries become very slow unless the equality
can be pushed down.

Essentially, there must be different ways to execute the subquery
depending on the value of OUTER_EXPR.

The optimizer chooses SQL compliance over speed, so it accounts for the
possibility that OUTER_EXPR might be 'NULL':

   * If OUTER_EXPR is 'NULL', to evaluate the following expression, it
     is necessary to execute the 'SELECT' to determine
     whether it produces any rows:

          NULL IN (SELECT INNER_EXPR FROM ... WHERE SUBQUERY_WHERE)

     It is necessary to execute the original 'SELECT'.
     here, without any pushed-down equalities of the kind mentioned
     earlier.

   * On the other hand, when OUTER_EXPR is not 'NULL', it is absolutely
     essential that this comparison:

          OUTER_EXPR IN (SELECT INNER_EXPR FROM ... WHERE SUBQUERY_WHERE)

     Be converted to this expression that uses a pushed-down condition:

          EXISTS (SELECT 1 FROM ... WHERE SUBQUERY_WHERE AND OUTER_EXPR=INNER_EXPR)

     Without this conversion, subqueries will be slow.

To solve the dilemma of whether or not to push down conditions into the
subquery, the conditions are wrapped within 'trigger' functions.  Thus,
an expression of the following form:

     OUTER_EXPR IN (SELECT INNER_EXPR FROM ... WHERE SUBQUERY_WHERE)

Is converted into:

     EXISTS (SELECT 1 FROM ... WHERE SUBQUERY_WHERE
                               AND trigcond(OUTER_EXPR=INNER_EXPR))

More generally, if the subquery comparison is based on several pairs of
outer and inner expressions, the conversion takes this comparison:

     (OE_1, ..., OE_N) IN (SELECT IE_1, ..., IE_N FROM ... WHERE SUBQUERY_WHERE)

And converts it to this expression:

     EXISTS (SELECT 1 FROM ... WHERE SUBQUERY_WHERE
                               AND trigcond(OE_1=IE_1)
                               AND ...
                               AND trigcond(OE_N=IE_N)
            )

Each 'trigcond(X)' is a special function that evaluates to the following
values:

   * X when the 'linked' outer expression OE_I is not 'NULL'

   * 'TRUE' when the 'linked' outer expression OE_I is 'NULL'

*Note*:

Trigger functions are _not_ triggers of the kind that you create with
'CREATE TRIGGER'.

Equalities that are wrapped within 'trigcond()' functions are not first
class predicates for the query optimizer.  Most optimizations cannot
deal with predicates that may be turned on and off at query execution
time, so they assume any 'trigcond(X)' to be an unknown function and
ignore it.  Triggered equalities can be used by those optimizations:

   * Reference optimizations: 'trigcond(X=Y [OR Y IS NULL])' can be used
     to construct 'ref', 'eq_ref', or 'ref_or_null' table accesses.

   * Index lookup-based subquery execution engines: 'trigcond(X=Y)' can
     be used to construct 'unique_subquery' or 'index_subquery'
     accesses.

   * Table-condition generator: If the subquery is a join of several
     tables, the triggered condition is checked as soon as possible.

When the optimizer uses a triggered condition to create some kind of
index lookup-based access (as for the first two items of the preceding
list), it must have a fallback strategy for the case when the condition
is turned off.  This fallback strategy is always the same: Do a full
table scan.  In 'EXPLAIN' output, the fallback shows up
as 'Full scan on NULL key' in the 'Extra' column:

     mysql> EXPLAIN SELECT t1.col1,
            t1.col1 IN (SELECT t2.key1 FROM t2 WHERE t2.col2=t1.col2) FROM t1\G
     *************************** 1. row ***************************
                id: 1
       select_type: PRIMARY
             table: t1
             ...
     *************************** 2. row ***************************
                id: 2
       select_type: DEPENDENT SUBQUERY
             table: t2
              type: index_subquery
     possible_keys: key1
               key: key1
           key_len: 5
               ref: func
              rows: 2
             Extra: Using where; Full scan on NULL key

If you run 'EXPLAIN' followed by 'SHOW WARNINGS',
you can see the triggered condition:

     *************************** 1. row ***************************
       Level: Note
        Code: 1003
     Message: select `test`.`t1`.`col1` AS `col1`,
              <in_optimizer>(`test`.`t1`.`col1`,
              <exists>(<index_lookup>(<cache>(`test`.`t1`.`col1`) in t2
              on key1 checking NULL
              where (`test`.`t2`.`col2` = `test`.`t1`.`col2`) having
              trigcond(<is_not_null_test>(`test`.`t2`.`key1`))))) AS
              `t1.col1 IN (select t2.key1 from t2 where t2.col2=t1.col2)`
              from `test`.`t1`

The use of triggered conditions has some performance implications.  A
'NULL IN (SELECT ...)' expression now may cause a full table scan (which
is slow) when it previously did not.  This is the price paid for correct
results (the goal of the trigger-condition strategy is to improve
compliance, not speed).

For multiple-table subqueries, execution of 'NULL IN (SELECT ...)' is
particularly slow because the join optimizer does not optimize for the
case where the outer expression is 'NULL'.  It assumes that subquery
evaluations with 'NULL' on the left side are very rare, even if there
are statistics that indicate otherwise.  On the other hand, if the outer
expression might be 'NULL' but never actually is, there is no
performance penalty.

To help the query optimizer better execute your queries, use these
suggestions:

   * Declare a column as 'NOT NULL' if it really is.  This also helps
     other aspects of the optimizer by simplifying condition testing for
     the column.

   * If you need not distinguish a 'NULL' from 'FALSE' subquery result,
     you can easily avoid the slow execution path.  Replace a comparison
     that looks like this:

          OUTER_EXPR IN (SELECT INNER_EXPR FROM ...)

     with this expression:

          (OUTER_EXPR IS NOT NULL) AND (OUTER_EXPR IN (SELECT INNER_EXPR FROM ...))

     Then 'NULL IN (SELECT ...)' is never evaluated because MySQL stops
     evaluating 'AND' parts as soon as the expression result is clear.

     Another possible rewrite:

          EXISTS (SELECT INNER_EXPR FROM ...
                  WHERE INNER_EXPR=OUTER_EXPR)

     This would apply when you need not distinguish 'NULL' from 'FALSE'
     subquery results, in which case you may actually want 'EXISTS'.

The 'subquery_materialization_cost_based' flag of the 'optimizer_switch'
system variable enables control over the choice between subquery
materialization and 'IN'-to-'EXISTS' subquery transformation.  See
switchable-optimizations.

8.2.3 Optimizing INFORMATION_SCHEMA Queries
-------------------------------------------

Applications that monitor databases may make frequent use of
'INFORMATION_SCHEMA' tables.  Certain types of queries for
'INFORMATION_SCHEMA' tables can be optimized to execute more quickly.
The goal is to minimize file operations (for example, scanning a
directory or opening a table file) to collect the information that makes
up these dynamic tables.

*Note*:

Comparison behavior for database and table names in 'INFORMATION_SCHEMA'
queries might differ from what you expect.  For details, see
charset-collation-information-schema.

*1) Try to use constant lookup values for database and table names in
the 'WHERE' clause*

You can take advantage of this principle as follows:

   * To look up databases or tables, use expressions that evaluate to a
     constant, such as literal values, functions that return a constant,
     or scalar subqueries.

   * Avoid queries that use a nonconstant database name lookup value (or
     no lookup value) because they require a scan of the data directory
     to find matching database directory names.

   * Within a database, avoid queries that use a nonconstant table name
     lookup value (or no lookup value) because they require a scan of
     the database directory to find matching table files.

This principle applies to the 'INFORMATION_SCHEMA' tables shown in the
following table, which shows the columns for which a constant lookup
value enables the server to avoid a directory scan.  For example, if you
are selecting from 'TABLES', using a constant lookup
value for 'TABLE_SCHEMA' in the 'WHERE' clause enables a data directory
scan to be avoided.

Table                    Column to specify to     Column to specify to
                         avoid data directory     avoid database
                         scan                     directory scan

See 'COLUMNS'.

See 'TABLE_SCHEMA' 'TABLE_NAME' 'KEY_COLUMN_USAGE'.

See 'PARTITIONS'.

See 'CONSTRAINT_SCHEMA' 'TABLE_NAME' 'REFERENTIAL_CONSTRAINTS'.

See 'STATISTICS'.

See 'TABLES'.

See 'TABLE_SCHEMA' 'TABLE_NAME' 'TABLE_CONSTRAINTS'.

See 'TRIGGERS'.

See 'VIEWS'.

The benefit of a query that is limited to a specific constant database
name is that checks need be made only for the named database directory.
Example:

     SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
     WHERE TABLE_SCHEMA = 'test';

Use of the literal database name 'test' enables the server to check only
the 'test' database directory, regardless of how many databases there
might be.  By contrast, the following query is less efficient because it
requires a scan of the data directory to determine which database names
match the pattern ''test%'':

     SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
     WHERE TABLE_SCHEMA LIKE 'test%';

For a query that is limited to a specific constant table name, checks
need be made only for the named table within the corresponding database
directory.  Example:

     SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
     WHERE TABLE_SCHEMA = 'test' AND TABLE_NAME = 't1';

Use of the literal table name 't1' enables the server to check only the
files for the 't1' table, regardless of how many tables there might be
in the 'test' database.  By contrast, the following query requires a
scan of the 'test' database directory to determine which table names
match the pattern ''t%'':

     SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
     WHERE TABLE_SCHEMA = 'test' AND TABLE_NAME LIKE 't%';

The following query requires a scan of the database directory to
determine matching database names for the pattern ''test%'', and for
each matching database, it requires a scan of the database directory to
determine matching table names for the pattern ''t%'':

     SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
     WHERE TABLE_SCHEMA = 'test%' AND TABLE_NAME LIKE 't%';

*2) Write queries that minimize the number of table files that must be
opened*

For queries that refer to certain 'INFORMATION_SCHEMA' table columns,
several optimizations are available that minimize the number of table
files that must be opened.  Example:

     SELECT TABLE_NAME, ENGINE FROM INFORMATION_SCHEMA.TABLES
     WHERE TABLE_SCHEMA = 'test';

In this case, after the server has scanned the database directory to
determine the names of the tables in the database, those names become
available with no further file system lookups.  Thus, 'TABLE_NAME'
requires no files to be opened.  The 'ENGINE' (storage engine) value can
be determined by opening the table's '.frm' file, without touching other
table files such as the '.MYD' or '.MYI' file.

Some values, such as 'INDEX_LENGTH' for 'MyISAM' tables, require opening
the '.MYD' or '.MYI' file as well.

The file-opening optimization types are denoted thus:

   * 'SKIP_OPEN_TABLE': Table files do not need to be opened.  The
     information has already become available within the query by
     scanning the database directory.

   * 'OPEN_FRM_ONLY': Only the table's '.frm' file need be opened.

   * 'OPEN_TRIGGER_ONLY': Only the table's '.TRG' file need be opened.

   * 'OPEN_FULL_TABLE': The unoptimized information lookup.  The '.frm',
     '.MYD', and '.MYI' files must be opened.

The following list indicates how the preceding optimization types apply
to 'INFORMATION_SCHEMA' table columns.  For tables and columns not
named, none of the optimizations apply.

   * 'COLUMNS'.: 'OPEN_FRM_ONLY' applies to all
     columns

   * 'KEY_COLUMN_USAGE'.:
     'OPEN_FULL_TABLE' applies to all columns

   * 'PARTITIONS'.: 'OPEN_FULL_TABLE' applies to
     all columns

   * 'REFERENTIAL_CONSTRAINTS'.:
     'OPEN_FULL_TABLE' applies to all columns

   * 'STATISTICS'.:

     Column                               Optimization type

     'TABLE_CATALOG'                      'OPEN_FRM_ONLY'

     'TABLE_SCHEMA'                       'OPEN_FRM_ONLY'

     'TABLE_NAME'                         'OPEN_FRM_ONLY'

     'NON_UNIQUE'                         'OPEN_FRM_ONLY'

     'INDEX_SCHEMA'                       'OPEN_FRM_ONLY'

     'INDEX_NAME'                         'OPEN_FRM_ONLY'

     'SEQ_IN_INDEX'                       'OPEN_FRM_ONLY'

     'COLUMN_NAME'                        'OPEN_FRM_ONLY'

     'COLLATION'                          'OPEN_FRM_ONLY'

     'CARDINALITY'                        'OPEN_FULL_TABLE'

     'SUB_PART'                           'OPEN_FRM_ONLY'

     'PACKED'                             'OPEN_FRM_ONLY'

     'NULLABLE'                           'OPEN_FRM_ONLY'

     'INDEX_TYPE'                         'OPEN_FULL_TABLE'

     'COMMENT'                            'OPEN_FRM_ONLY'

   * 'TABLES'.:

     Column                               Optimization type

     'TABLE_CATALOG'                      'SKIP_OPEN_TABLE'

     'TABLE_SCHEMA'                       'SKIP_OPEN_TABLE'

     'TABLE_NAME'                         'SKIP_OPEN_TABLE'

     'TABLE_TYPE'                         'OPEN_FRM_ONLY'

     'ENGINE'                             'OPEN_FRM_ONLY'

     'VERSION'                            'OPEN_FRM_ONLY'

     'ROW_FORMAT'                         'OPEN_FULL_TABLE'

     'TABLE_ROWS'                         'OPEN_FULL_TABLE'

     'AVG_ROW_LENGTH'                     'OPEN_FULL_TABLE'

     'DATA_LENGTH'                        'OPEN_FULL_TABLE'

     'MAX_DATA_LENGTH'                    'OPEN_FULL_TABLE'

     'INDEX_LENGTH'                       'OPEN_FULL_TABLE'

     'DATA_FREE'                          'OPEN_FULL_TABLE'

     'AUTO_INCREMENT'                     'OPEN_FULL_TABLE'

     'CREATE_TIME'                        'OPEN_FULL_TABLE'

     'UPDATE_TIME'                        'OPEN_FULL_TABLE'

     'CHECK_TIME'                         'OPEN_FULL_TABLE'

     'TABLE_COLLATION'                    'OPEN_FRM_ONLY'

     'CHECKSUM'                           'OPEN_FULL_TABLE'

     'CREATE_OPTIONS'                     'OPEN_FRM_ONLY'

     'TABLE_COMMENT'                      'OPEN_FRM_ONLY'

   * 'TABLE_CONSTRAINTS'.:
     'OPEN_FULL_TABLE' applies to all columns

   * 'TRIGGERS'.: 'OPEN_TRIGGER_ONLY' applies to
     all columns

   * 'VIEWS'.:

     Column                               Optimization type

     'TABLE_CATALOG'                      'OPEN_FRM_ONLY'

     'TABLE_SCHEMA'                       'OPEN_FRM_ONLY'

     'TABLE_NAME'                         'OPEN_FRM_ONLY'

     'VIEW_DEFINITION'                    'OPEN_FRM_ONLY'

     'CHECK_OPTION'                       'OPEN_FRM_ONLY'

     'IS_UPDATABLE'                       'OPEN_FULL_TABLE'

     'DEFINER'                            'OPEN_FRM_ONLY'

     'SECURITY_TYPE'                      'OPEN_FRM_ONLY'

     'CHARACTER_SET_CLIENT'               'OPEN_FRM_ONLY'

     'COLLATION_CONNECTION'               'OPEN_FRM_ONLY'

*3) Use 'EXPLAIN' to determine whether the server can
use 'INFORMATION_SCHEMA' optimizations for a query*

This applies particularly for 'INFORMATION_SCHEMA' queries that search
for information from more than one database, which might take a long
time and impact performance.  The 'Extra' value in 'EXPLAIN'
output indicates which, if any, of the optimizations described
earlier the server can use to evaluate 'INFORMATION_SCHEMA' queries.
The following examples demonstrate the kinds of information you can
expect to see in the 'Extra' value.

     mysql> EXPLAIN SELECT TABLE_NAME FROM INFORMATION_SCHEMA.VIEWS WHERE
            TABLE_SCHEMA = 'test' AND TABLE_NAME = 'v1'\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: VIEWS
              type: ALL
     possible_keys: NULL
               key: TABLE_SCHEMA,TABLE_NAME
           key_len: NULL
               ref: NULL
              rows: NULL
             Extra: Using where; Open_frm_only; Scanned 0 databases

Use of constant database and table lookup values enables the server to
avoid directory scans.  For references to 'VIEWS.TABLE_NAME', only the
'.frm' file need be opened.

     mysql> EXPLAIN SELECT TABLE_NAME, ROW_FORMAT FROM INFORMATION_SCHEMA.TABLES\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: TABLES
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: NULL
             Extra: Open_full_table; Scanned all databases

No lookup values are provided (there is no 'WHERE' clause), so the
server must scan the data directory and each database directory.  For
each table thus identified, the table name and row format are selected.
'TABLE_NAME' requires no further table files to be opened (the
'SKIP_OPEN_TABLE' optimization applies).  'ROW_FORMAT' requires all
table files to be opened ('OPEN_FULL_TABLE' applies).  'EXPLAIN'
reports 'OPEN_FULL_TABLE' because it is more expensive than
'SKIP_OPEN_TABLE'.

     mysql> EXPLAIN SELECT TABLE_NAME, TABLE_TYPE FROM INFORMATION_SCHEMA.TABLES
            WHERE TABLE_SCHEMA = 'test'\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: TABLES
              type: ALL
     possible_keys: NULL
               key: TABLE_SCHEMA
           key_len: NULL
               ref: NULL
              rows: NULL
             Extra: Using where; Open_frm_only; Scanned 1 database

No table name lookup value is provided, so the server must scan the
'test' database directory.  For the 'TABLE_NAME' and 'TABLE_TYPE'
columns, the 'SKIP_OPEN_TABLE' and 'OPEN_FRM_ONLY' optimizations apply,
respectively.  'EXPLAIN' reports 'OPEN_FRM_ONLY' because
it is more expensive.

     mysql> EXPLAIN SELECT B.TABLE_NAME
            FROM INFORMATION_SCHEMA.TABLES AS A, INFORMATION_SCHEMA.COLUMNS AS B
            WHERE A.TABLE_SCHEMA = 'test'
            AND A.TABLE_NAME = 't1'
            AND B.TABLE_NAME = A.TABLE_NAME\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: A
              type: ALL
     possible_keys: NULL
               key: TABLE_SCHEMA,TABLE_NAME
           key_len: NULL
               ref: NULL
              rows: NULL
             Extra: Using where; Skip_open_table; Scanned 0 databases
     *************************** 2. row ***************************
                id: 1
       select_type: SIMPLE
             table: B
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: NULL
             Extra: Using where; Open_frm_only; Scanned all databases;
                    Using join buffer

For the first 'EXPLAIN' output row: Constant database
and table lookup values enable the server to avoid directory scans for
'TABLES' values.  References to 'TABLES.TABLE_NAME' require no further
table files.

For the second 'EXPLAIN' output row: All
'COLUMNS' table values are 'OPEN_FRM_ONLY' lookups, so
'COLUMNS.TABLE_NAME' requires the '.frm' file to be opened.

     mysql> EXPLAIN SELECT * FROM INFORMATION_SCHEMA.COLLATIONS\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: COLLATIONS
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: NULL
             Extra:

In this case, no optimizations apply because 'COLLATIONS'
is not one of the 'INFORMATION_SCHEMA' tables for
which optimizations are available.

8.2.4 Optimizing Data Change Statements
---------------------------------------

This section explains how to speed up data change statements:
'INSERT', 'UPDATE', and 'DELETE'.
Traditional OLTP applications and modern web applications typically do
many small data change operations, where concurrency is vital.  Data
analysis and reporting applications typically run data change operations
that affect many rows at once, where the main considerations is the I/O
to write large amounts of data and keep indexes up-to-date.  For
inserting and updating large volumes of data (known in the industry as
ETL, for 'extract-transform-load'), sometimes you use other SQL
statements or external commands, that mimic the effects of
'INSERT', 'UPDATE', and 'DELETE'.
statements.

8.2.4.1 Optimizing INSERT Statements
....................................

To optimize insert speed, combine many small operations into a single
large operation.  Ideally, you make a single connection, send the data
for many new rows at once, and delay all index updates and consistency
checking until the very end.

The time required for inserting a row is determined by the following
factors, where the numbers indicate approximate proportions:

   * Connecting: (3)

   * Sending query to server: (2)

   * Parsing query: (2)

   * Inserting row: (1 x size of row)

   * Inserting indexes: (1 x number of indexes)

   * Closing: (1)

This does not take into consideration the initial overhead to open
tables, which is done once for each concurrently running query.

The size of the table slows down the insertion of indexes by log N,
assuming B-tree indexes.

You can use the following methods to speed up inserts:

   * If you are inserting many rows from the same client at the same
     time, use 'INSERT' statements with multiple 'VALUES'
     lists to insert several rows at a time.  This is considerably
     faster (many times faster in some cases) than using separate
     single-row 'INSERT' statements.  If you are adding
     data to a nonempty table, you can tune the
     'bulk_insert_buffer_size' variable to make data insertion even
     faster.  See server-system-variables.

   * When loading a table from a text file, use 'LOAD DATA INFILE'.
     This is usually 20 times faster than using
     'INSERT' statements.  See load-data.

   * Take advantage of the fact that columns have default values.
     Insert values explicitly only when the value to be inserted differs
     from the default.  This reduces the parsing that MySQL must do and
     improves the insert speed.

   * See optimizing-innodb-bulk-data-loading for tips specific
     to 'InnoDB' tables.

   * See optimizing-myisam-bulk-data-loading for tips specific
     to 'MyISAM' tables.

8.2.4.2 Optimizing UPDATE Statements
....................................

An update statement is optimized like a 'SELECT' query
with the additional overhead of a write.  The speed of the write depends
on the amount of data being updated and the number of indexes that are
updated.  Indexes that are not changed do not get updated.

Another way to get fast updates is to delay updates and then do many
updates in a row later.  Performing multiple updates together is much
quicker than doing one at a time if you lock the table.

For a 'MyISAM' table that uses dynamic row format, updating a row to a
longer total length may split the row.  If you do this often, it is very
important to use 'OPTIMIZE TABLE' occasionally.
See optimize-table.

8.2.4.3 Optimizing DELETE Statements
....................................

The time required to delete individual rows in a 'MyISAM' table is
exactly proportional to the number of indexes.  To delete rows more
quickly, you can increase the size of the key cache by increasing the
'key_buffer_size' system variable.  See server-configuration.

To delete all rows from a 'MyISAM' table, 'TRUNCATE TABLE TBL_NAME' is
faster than 'DELETE FROM TBL_NAME'.  Truncate operations are not
transaction-safe; an error occurs when attempting one in the course of
an active transaction or active table lock.  See truncate-table.

8.2.5 Optimizing Database Privileges
------------------------------------

The more complex your privilege setup, the more overhead applies to all
SQL statements.  Simplifying the privileges established by
'GRANT' statements enables MySQL to reduce permission-checking
overhead when clients execute statements.  For example, if you do not
grant any table-level or column-level privileges, the server need not
ever check the contents of the 'tables_priv' and 'columns_priv' tables.
Similarly, if you place no resource limits on any accounts, the server
does not have to perform resource counting.  If you have a very high
statement-processing load, consider using a simplified grant structure
to reduce permission-checking overhead.

8.2.6 Other Optimization Tips
-----------------------------

This section lists a number of miscellaneous tips for improving query
processing speed:

   * If your application makes several database requests to perform
     related updates, combining the statements into a stored routine can
     help performance.  Similarly, if your application computes a single
     result based on several column values or large volumes of data,
     combining the computation into a UDF (user-defined function) can
     help performance.  The resulting fast database operations are then
     available to be reused by other queries, applications, and even
     code written in different programming languages.  See
     stored-routines and adding-functions for more
     information.

   * To fix any compression issues that occur with 'ARCHIVE' tables, use
     'OPTIMIZE TABLE'.  See
     archive-storage-engine.

   * If possible, classify reports as 'live' or as 'statistical', where
     data needed for statistical reports is created only from summary
     tables that are generated periodically from the live data.

   * If you have data that does not conform well to a rows-and-columns
     table structure, you can pack and store data into a 'BLOB'
     column.  In this case, you must provide code in your
     application to pack and unpack information, but this might save I/O
     operations to read and write the sets of related values.

   * With Web servers, store images and other binary assets as files,
     with the path name stored in the database rather than the file
     itself.  Most Web servers are better at caching files than database
     contents, so using files is generally faster.  (Although you must
     handle backups and storage issues yourself in this case.)

   * If you need really high speed, look at the low-level MySQL
     interfaces.  For example, by accessing the MySQL 'InnoDB' or
     'MyISAM' storage engine directly, you could get a substantial speed
     increase compared to using the SQL interface.

   * Replication can provide a performance benefit for some operations.
     You can distribute client retrievals among replication servers to
     split up the load.  To avoid slowing down the master while making
     backups, you can make backups using a slave server.  See
     replication.

8.3 Optimization and Indexes
============================

The best way to improve the performance of 'SELECT'.
operations is to create indexes on one or more of the columns that are
tested in the query.  The index entries act like pointers to the table
rows, allowing the query to quickly determine which rows match a
condition in the 'WHERE' clause, and retrieve the other column values
for those rows.  All MySQL data types can be indexed.

Although it can be tempting to create an indexes for every possible
column used in a query, unnecessary indexes waste space and waste time
for MySQL to determine which indexes to use.  Indexes also add to the
cost of inserts, updates, and deletes because each index must be
updated.  You must find the right balance to achieve fast queries using
the optimal set of indexes.

8.3.1 How MySQL Uses Indexes
----------------------------

Indexes are used to find rows with specific column values quickly.
Without an index, MySQL must begin with the first row and then read
through the entire table to find the relevant rows.  The larger the
table, the more this costs.  If the table has an index for the columns
in question, MySQL can quickly determine the position to seek to in the
middle of the data file without having to look at all the data.  This is
much faster than reading every row sequentially.

Most MySQL indexes ('PRIMARY KEY', 'UNIQUE', 'INDEX', and 'FULLTEXT')
are stored in B-trees.  Exceptions: Indexes on spatial data types use
R-trees; 'MEMORY' tables also support hash indexes; 'InnoDB' uses
inverted lists for 'FULLTEXT' indexes.

In general, indexes are used as described in the following discussion.
Characteristics specific to hash indexes (as used in 'MEMORY' tables)
are described in index-btree-hash.

MySQL uses indexes for these operations:

   * To find the rows matching a 'WHERE' clause quickly.

   * To eliminate rows from consideration.  If there is a choice between
     multiple indexes, MySQL normally uses the index that finds the
     smallest number of rows (the most selective index).

   *
     If the table has a multiple-column index, any leftmost prefix of
     the index can be used by the optimizer to look up rows.  For
     example, if you have a three-column index on '(col1, col2, col3)',
     you have indexed search capabilities on '(col1)', '(col1, col2)',
     and '(col1, col2, col3)'.  For more information, see
     multiple-column-indexes.

   * To retrieve rows from other tables when performing joins.  MySQL
     can use indexes on columns more efficiently if they are declared as
     the same type and size.  In this context, see 'VARCHAR'.
     and 'CHAR' are considered the same if they are
     declared as the same size.  For example, 'VARCHAR(10)' and
     'CHAR(10)' are the same size, but 'VARCHAR(10)' and 'CHAR(15)' are
     not.

     For comparisons between nonbinary string columns, both columns
     should use the same character set.  For example, comparing a 'utf8'
     column with a 'latin1' column precludes use of an index.

     Comparison of dissimilar columns (comparing a string column to a
     temporal or numeric column, for example) may prevent use of indexes
     if values cannot be compared directly without conversion.  For a
     given value such as '1' in the numeric column, it might compare
     equal to any number of values in the string column such as ''1'',
     '' 1'', ''00001'', or ''01.e1''.  This rules out use of any indexes
     for the string column.

   * To find the 'MIN()' or 'MAX()' value for a specific indexed column
     KEY_COL.  This is optimized by a preprocessor that checks whether
     you are using 'WHERE KEY_PART_N = CONSTANT' on all key parts that
     occur before KEY_COL in the index.  In this case, MySQL does a
     single key lookup for each 'MIN()' or 'MAX()' expression and
     replaces it with a constant.  If all expressions are replaced with
     constants, the query returns at once.  For example:

          SELECT MIN(KEY_PART2),MAX(KEY_PART2)
            FROM TBL_NAME WHERE KEY_PART1=10;

   * To sort or group a table if the sorting or grouping is done on a
     leftmost prefix of a usable index (for example, 'ORDER BY
     KEY_PART1, KEY_PART2').  If all key parts are followed by 'DESC',
     the key is read in reverse order.  See
     order-by-optimization, and group-by-optimization.

   * In some cases, a query can be optimized to retrieve values without
     consulting the data rows.  (An index that provides all the
     necessary results for a query is called a covering index.)  If a
     query uses from a table only columns that are included in some
     index, the selected values can be retrieved from the index tree for
     greater speed:

          SELECT KEY_PART3 FROM TBL_NAME
            WHERE KEY_PART1=1

Indexes are less important for queries on small tables, or big tables
where report queries process most or all of the rows.  When a query
needs to access most of the rows, reading sequentially is faster than
working through an index.  Sequential reads minimize disk seeks, even if
not all the rows are needed for the query.  See
table-scan-avoidance for details.

8.3.2 Primary Key Optimization
------------------------------

The primary key for a table represents the column or set of columns that
you use in your most vital queries.  It has an associated index, for
fast query performance.  Query performance benefits from the 'NOT NULL'
optimization, because it cannot include any 'NULL' values.  With the
'InnoDB' storage engine, the table data is physically organized to do
ultra-fast lookups and sorts based on the primary key column or columns.

If your table is big and important, but does not have an obvious column
or set of columns to use as a primary key, you might create a separate
column with auto-increment values to use as the primary key.  These
unique IDs can serve as pointers to corresponding rows in other tables
when you join tables using foreign keys.

8.3.3 Foreign Key Optimization
------------------------------

If a table has many columns, and you query many different combinations
of columns, it might be efficient to split the less-frequently used data
into separate tables with a few columns each, and relate them back to
the main table by duplicating the numeric ID column from the main table.
That way, each small table can have a primary key for fast lookups of
its data, and you can query just the set of columns that you need using
a join operation.  Depending on how the data is distributed, the queries
might perform less I/O and take up less cache memory because the
relevant columns are packed together on disk.  (To maximize performance,
queries try to read as few data blocks as possible from disk; tables
with only a few columns can fit more rows in each data block.)

8.3.4 Column Indexes
--------------------

The most common type of index involves a single column, storing copies
of the values from that column in a data structure, allowing fast
lookups for the rows with the corresponding column values.  The B-tree
data structure lets the index quickly find a specific value, a set of
values, or a range of values, corresponding to operators such as '=',
'>', '<=', 'BETWEEN', 'IN', and so on, in a 'WHERE' clause.

The maximum number of indexes per table and the maximum index length is
defined per storage engine.  See innodb-storage-engine, and
storage-engines.  All storage engines support at least 16
indexes per table and a total index length of at least 256 bytes.  Most
storage engines have higher limits.

For additional information about column indexes, see
create-index.

   * column-indexes-prefix

   * column-indexes-fulltext

   * column-indexes-spatial

   * column-indexes-memory-storage-engine

*Index Prefixes*

With 'COL_NAME(N)' syntax in an index specification for a string column,
you can create an index that uses only the first N characters of the
column.  Indexing only a prefix of column values in this way can make
the index file much smaller.  When you index a 'BLOB' or
'TEXT' column, you _must_ specify a prefix length for the
index.  For example:

     CREATE TABLE test (blob_col BLOB, INDEX(blob_col(10)));

Prefixes can be up to 1000 bytes long (767 bytes for 'InnoDB' tables,
unless you have 'innodb_large_prefix' set).

*Note*:

Prefix limits are measured in bytes, whereas the prefix length in
'CREATE TABLE', 'ALTER TABLE', and
'CREATE INDEX' statements is interpreted as number
of characters for nonbinary string types (see 'CHAR',
'VARCHAR', 'TEXT') and number of bytes for binary
string types (see 'BINARY', 'VARBINARY',
see 'BLOB').  Take this into account when
specifying a prefix length for a nonbinary string column that uses a
multibyte character set.

For additional information about index prefixes, see
create-index.

*FULLTEXT Indexes*

'FULLTEXT' indexes are used for full-text searches.  Only the
'InnoDB' and 'MyISAM'
storage engines support 'FULLTEXT' indexes and
only for 'CHAR', 'VARCHAR', and 'TEXT'
columns.  Indexing always takes place over the entire column and
column prefix indexing is not supported.  For details, see
fulltext-search.

Optimizations are applied to certain kinds of 'FULLTEXT' queries against
single 'InnoDB' tables.  Queries with these characteristics are
particularly efficient:

   * 'FULLTEXT' queries that only return the document ID, or the
     document ID and the search rank.

   * 'FULLTEXT' queries that sort the matching rows in descending order
     of score and apply a 'LIMIT' clause to take the top N matching
     rows.  For this optimization to apply, there must be no 'WHERE'
     clauses and only a single 'ORDER BY' clause in descending order.

   * 'FULLTEXT' queries that retrieve only the 'COUNT(*)' value of rows
     matching a search term, with no additional 'WHERE' clauses.  Code
     the 'WHERE' clause as 'WHERE MATCH(TEXT) AGAINST ('OTHER_TEXT')',
     without any '> 0' comparison operator.

For queries that contain full-text expressions, MySQL evaluates those
expressions during the optimization phase of query execution.  The
optimizer does not just look at full-text expressions and make
estimates, it actually evaluates them in the process of developing an
execution plan.

An implication of this behavior is that 'EXPLAIN' for
full-text queries is typically slower than for non-full-text queries for
which no expression evaluation occurs during the optimization phase.

'EXPLAIN' for full-text queries may show 'Select tables
optimized away' in the 'Extra' column due to matching occurring during
optimization; in this case, no table access need occur during later
execution.

*Spatial Indexes*

You can create indexes on spatial data types.  'MyISAM' and 'InnoDB'
support R-tree indexes on spatial types.  Other storage engines use
B-trees for indexing spatial types (except for 'ARCHIVE', which does not
support spatial type indexing).

*Indexes in the MEMORY Storage Engine*

The 'MEMORY' storage engine uses 'HASH' indexes by default, but also
supports 'BTREE' indexes.

8.3.5 Multiple-Column Indexes
-----------------------------

MySQL can create composite indexes (that is, indexes on multiple
columns).  An index may consist of up to 16 columns.  For certain data
types, you can index a prefix of the column (see
column-indexes).

MySQL can use multiple-column indexes for queries that test all the
columns in the index, or queries that test just the first column, the
first two columns, the first three columns, and so on.  If you specify
the columns in the right order in the index definition, a single
composite index can speed up several kinds of queries on the same table.

A multiple-column index can be considered a sorted array, the rows of
which contain values that are created by concatenating the values of the
indexed columns.

*Note*:

As an alternative to a composite index, you can introduce a column that
is 'hashed' based on information from other columns.  If this column is
short, reasonably unique, and indexed, it might be faster than a 'wide'
index on many columns.  In MySQL, it is very easy to use this extra
column:

     SELECT * FROM TBL_NAME
       WHERE HASH_COL=MD5(CONCAT(VAL1,VAL2))
       AND COL1=VAL1 AND COL2=VAL2;

Suppose that a table has the following specification:

     CREATE TABLE test (
         id         INT NOT NULL,
         last_name  CHAR(30) NOT NULL,
         first_name CHAR(30) NOT NULL,
         PRIMARY KEY (id),
         INDEX name (last_name,first_name)
     );

The 'name' index is an index over the 'last_name' and 'first_name'
columns.  The index can be used for lookups in queries that specify
values in a known range for combinations of 'last_name' and 'first_name'
values.  It can also be used for queries that specify just a 'last_name'
value because that column is a leftmost prefix of the index (as
described later in this section).  Therefore, the 'name' index is used
for lookups in the following queries:

     SELECT * FROM test WHERE last_name='Widenius';

     SELECT * FROM test
       WHERE last_name='Widenius' AND first_name='Michael';

     SELECT * FROM test
       WHERE last_name='Widenius'
       AND (first_name='Michael' OR first_name='Monty');

     SELECT * FROM test
       WHERE last_name='Widenius'
       AND first_name >='M' AND first_name < 'N';

However, the 'name' index is _not_ used for lookups in the following
queries:

     SELECT * FROM test WHERE first_name='Michael';

     SELECT * FROM test
       WHERE last_name='Widenius' OR first_name='Michael';

Suppose that you issue the following 'SELECT' statement:

     SELECT * FROM TBL_NAME
       WHERE col1=VAL1 AND col2=VAL2;

If a multiple-column index exists on 'col1' and 'col2', the appropriate
rows can be fetched directly.  If separate single-column indexes exist
on 'col1' and 'col2', the optimizer attempts to use the Index Merge
optimization (see index-merge-optimization), or attempts to find
the most restrictive index by deciding which index excludes more rows
and using that index to fetch the rows.

If the table has a multiple-column index, any leftmost prefix of the
index can be used by the optimizer to look up rows.  For example, if you
have a three-column index on '(col1, col2, col3)', you have indexed
search capabilities on '(col1)', '(col1, col2)', and '(col1, col2,
col3)'.

MySQL cannot use the index to perform lookups if the columns do not form
a leftmost prefix of the index.  Suppose that you have the
'SELECT' statements shown here:

     SELECT * FROM TBL_NAME WHERE col1=VAL1;
     SELECT * FROM TBL_NAME WHERE col1=VAL1 AND col2=VAL2;

     SELECT * FROM TBL_NAME WHERE col2=VAL2;
     SELECT * FROM TBL_NAME WHERE col2=VAL2 AND col3=VAL3;

If an index exists on '(col1, col2, col3)', only the first two queries
use the index.  The third and fourth queries do involve indexed columns,
but do not use an index to perform lookups because '(col2)' and '(col2,
col3)' are not leftmost prefixes of '(col1, col2, col3)'.

8.3.6 Verifying Index Usage
---------------------------

Always check whether all your queries really use the indexes that you
have created in the tables.  Use the 'EXPLAIN'.
statement, as described in using-explain.

8.3.7 InnoDB and MyISAM Index Statistics Collection
---------------------------------------------------

Storage engines collect statistics about tables for use by the
optimizer.  Table statistics are based on value groups, where a value
group is a set of rows with the same key prefix value.  For optimizer
purposes, an important statistic is the average value group size.

MySQL uses the average value group size in the following ways:

   * To estimate how may rows must be read for each 'ref' access

   * To estimate how many row a partial join will produce; that is, the
     number of rows that an operation of this form will produce:

          (...) JOIN TBL_NAME ON TBL_NAME.KEY = EXPR

As the average value group size for an index increases, the index is
less useful for those two purposes because the average number of rows
per lookup increases: For the index to be good for optimization
purposes, it is best that each index value target a small number of rows
in the table.  When a given index value yields a large number of rows,
the index is less useful and MySQL is less likely to use it.

The average value group size is related to table cardinality, which is
the number of value groups.  The 'SHOW INDEX'.
statement displays a cardinality value based on N/S, where N is the
number of rows in the table and S is the average value group size.  That
ratio yields an approximate number of value groups in the table.

For a join based on the '<=>' comparison operator, 'NULL' is not treated
differently from any other value: 'NULL <=> NULL', just as 'N <=> N' for
any other N.

However, for a join based on the '=' operator, 'NULL' is different from
non-'NULL' values: 'EXPR1 = EXPR2' is not true when EXPR1 or EXPR2 (or
both) are 'NULL'.  This affects 'ref' accesses for comparisons of the
form 'TBL_NAME.KEY = EXPR': MySQL will not access the table if the
current value of EXPR is 'NULL', because the comparison cannot be true.

For '=' comparisons, it does not matter how many 'NULL' values are in
the table.  For optimization purposes, the relevant value is the average
size of the non-'NULL' value groups.  However, MySQL does not currently
enable that average size to be collected or used.

For 'InnoDB' and 'MyISAM' tables, you have some control over collection
of table statistics by means of the 'innodb_stats_method' and
'myisam_stats_method' system variables, respectively.  These variables
have three possible values, which differ as follows:

   * When the variable is set to 'nulls_equal', all 'NULL' values are
     treated as identical (that is, they all form a single value group).

     If the 'NULL' value group size is much higher than the average
     non-'NULL' value group size, this method skews the average value
     group size upward.  This makes index appear to the optimizer to be
     less useful than it really is for joins that look for non-'NULL'
     values.  Consequently, the 'nulls_equal' method may cause the
     optimizer not to use the index for 'ref' accesses when it should.

   * When the variable is set to 'nulls_unequal', 'NULL' values are not
     considered the same.  Instead, each 'NULL' value forms a separate
     value group of size 1.

     If you have many 'NULL' values, this method skews the average value
     group size downward.  If the average non-'NULL' value group size is
     large, counting 'NULL' values each as a group of size 1 causes the
     optimizer to overestimate the value of the index for joins that
     look for non-'NULL' values.  Consequently, the 'nulls_unequal'
     method may cause the optimizer to use this index for 'ref' lookups
     when other methods may be better.

   * When the variable is set to 'nulls_ignored', 'NULL' values are
     ignored.

If you tend to use many joins that use '<=>' rather than '=', 'NULL'
values are not special in comparisons and one 'NULL' is equal to
another.  In this case, 'nulls_equal' is the appropriate statistics
method.

The 'innodb_stats_method' system variable has a global value; the
'myisam_stats_method' system variable has both global and session
values.  Setting the global value affects statistics collection for
tables from the corresponding storage engine.  Setting the session value
affects statistics collection only for the current client connection.
This means that you can force a table's statistics to be regenerated
with a given method without affecting other clients by setting the
session value of 'myisam_stats_method'.

To regenerate 'MyISAM' table statistics, you can use any of the
following methods:

   * Execute 'myisamchk --stats_method=METHOD_NAME --analyze'.

   * Change the table to cause its statistics to go out of date (for
     example, insert a row and then delete it), and then set
     'myisam_stats_method' and issue an 'ANALYZE TABLE'
     statement

Some caveats regarding the use of 'innodb_stats_method' and
'myisam_stats_method':

   * You can force table statistics to be collected explicitly, as just
     described.  However, MySQL may also collect statistics
     automatically.  For example, if during the course of executing
     statements for a table, some of those statements modify the table,
     MySQL may collect statistics.  (This may occur for bulk inserts or
     deletes, or some 'ALTER TABLE' statements, for
     example.)  If this happens, the statistics are collected using
     whatever value 'innodb_stats_method' or 'myisam_stats_method' has
     at the time.  Thus, if you collect statistics using one method, but
     the system variable is set to the other method when a table's
     statistics are collected automatically later, the other method will
     be used.

   * There is no way to tell which method was used to generate
     statistics for a given table.

   * These variables apply only to 'InnoDB' and 'MyISAM' tables.  Other
     storage engines have only one method for collecting table
     statistics.  Usually it is closer to the 'nulls_equal' method.

8.3.8 Comparison of B-Tree and Hash Indexes
-------------------------------------------

Understanding the B-tree and hash data structures can help predict how
different queries perform on different storage engines that use these
data structures in their indexes, particularly for the 'MEMORY' storage
engine that lets you choose B-tree or hash indexes.

   * btree-index-characteristics

   * hash-index-characteristics

*B-Tree Index Characteristics*

A B-tree index can be used for column comparisons in expressions that
use the '=', '>', '>=', '<', '<=', or 'BETWEEN' operators.  The index
also can be used for 'LIKE' comparisons if the argument to 'LIKE' is a
constant string that does not start with a wildcard character.  For
example, the following 'SELECT' statements use indexes:

     SELECT * FROM TBL_NAME WHERE KEY_COL LIKE 'Patrick%';
     SELECT * FROM TBL_NAME WHERE KEY_COL LIKE 'Pat%_ck%';

In the first statement, only rows with ''Patrick' <= KEY_COL <
'Patricl'' are considered.  In the second statement, only rows with
''Pat' <= KEY_COL < 'Pau'' are considered.

The following 'SELECT' statements do not use indexes:

     SELECT * FROM TBL_NAME WHERE KEY_COL LIKE '%Patrick%';
     SELECT * FROM TBL_NAME WHERE KEY_COL LIKE OTHER_COL;

In the first statement, the 'LIKE' value begins with a wildcard
character.  In the second statement, the 'LIKE' value is not a constant.

If you use '... LIKE '%STRING%'' and STRING is longer than three
characters, MySQL uses the _Turbo Boyer-Moore algorithm_ to initialize
the pattern for the string and then uses this pattern to perform the
search more quickly.

A search using 'COL_NAME IS NULL' employs indexes if COL_NAME is
indexed.

Any index that does not span all 'AND' levels in the 'WHERE' clause is
not used to optimize the query.  In other words, to be able to use an
index, a prefix of the index must be used in every 'AND' group.

The following 'WHERE' clauses use indexes:

     ... WHERE INDEX_PART1=1 AND INDEX_PART2=2 AND OTHER_COLUMN=3

         /* INDEX = 1 OR INDEX = 2 */
     ... WHERE INDEX=1 OR A=10 AND INDEX=2

         /* optimized like "INDEX_PART1='hello'" */
     ... WHERE INDEX_PART1='hello' AND INDEX_PART3=5

         /* Can use index on INDEX1 but not on INDEX2 or INDEX3 */
     ... WHERE INDEX1=1 AND INDEX2=2 OR INDEX1=3 AND INDEX3=3;

These 'WHERE' clauses do _not_ use indexes:

         /* INDEX_PART1 is not used */
     ... WHERE INDEX_PART2=1 AND INDEX_PART3=2

         /*  Index is not used in both parts of the WHERE clause  */
     ... WHERE INDEX=1 OR A=10

         /* No index spans all rows  */
     ... WHERE INDEX_PART1=1 OR INDEX_PART2=10

Sometimes MySQL does not use an index, even if one is available.  One
circumstance under which this occurs is when the optimizer estimates
that using the index would require MySQL to access a very large
percentage of the rows in the table.  (In this case, a table scan is
likely to be much faster because it requires fewer seeks.)  However, if
such a query uses 'LIMIT' to retrieve only some of the rows, MySQL uses
an index anyway, because it can much more quickly find the few rows to
return in the result.

*Hash Index Characteristics*

Hash indexes have somewhat different characteristics from those just
discussed:

   * They are used only for equality comparisons that use the '=' or
     '<=>' operators (but are _very_ fast).  They are not used for
     comparison operators such as '<' that find a range of values.
     Systems that rely on this type of single-value lookup are known as
     'key-value stores'; to use MySQL for such applications, use hash
     indexes wherever possible.

   * The optimizer cannot use a hash index to speed up 'ORDER BY'
     operations.  (This type of index cannot be used to search for the
     next entry in order.)

   * MySQL cannot determine approximately how many rows there are
     between two values (this is used by the range optimizer to decide
     which index to use).  This may affect some queries if you change a
     'MyISAM' or 'InnoDB' table to a hash-indexed 'MEMORY' table.

   * Only whole keys can be used to search for a row.  (With a B-tree
     index, any leftmost prefix of the key can be used to find rows.)

8.3.9 Use of Index Extensions
-----------------------------

'InnoDB' automatically extends each
secondary index by appending the primary key columns to it.  Consider
this table definition:

     CREATE TABLE t1 (
       i1 INT NOT NULL DEFAULT 0,
       i2 INT NOT NULL DEFAULT 0,
       d DATE DEFAULT NULL,
       PRIMARY KEY (i1, i2),
       INDEX k_d (d)
     ) ENGINE = InnoDB;

This table defines the primary key on columns '(i1, i2)'.  It also
defines a secondary index 'k_d' on column '(d)', but internally 'InnoDB'
extends this index and treats it as columns '(d, i1, i2)'.

The optimizer takes into account the primary key columns of the extended
secondary index when determining how and whether to use that index.
This can result in more efficient query execution plans and better
performance.

The optimizer can use extended secondary indexes for 'ref', 'range', and
'index_merge' index access, for loose index scans, for join and sorting
optimization, and for 'MIN()'/'MAX()' optimization.

The following example shows how execution plans are affected by whether
the optimizer uses extended secondary indexes.  Suppose that 't1' is
populated with these rows:

     INSERT INTO t1 VALUES
     (1, 1, '1998-01-01'), (1, 2, '1999-01-01'),
     (1, 3, '2000-01-01'), (1, 4, '2001-01-01'),
     (1, 5, '2002-01-01'), (2, 1, '1998-01-01'),
     (2, 2, '1999-01-01'), (2, 3, '2000-01-01'),
     (2, 4, '2001-01-01'), (2, 5, '2002-01-01'),
     (3, 1, '1998-01-01'), (3, 2, '1999-01-01'),
     (3, 3, '2000-01-01'), (3, 4, '2001-01-01'),
     (3, 5, '2002-01-01'), (4, 1, '1998-01-01'),
     (4, 2, '1999-01-01'), (4, 3, '2000-01-01'),
     (4, 4, '2001-01-01'), (4, 5, '2002-01-01'),
     (5, 1, '1998-01-01'), (5, 2, '1999-01-01'),
     (5, 3, '2000-01-01'), (5, 4, '2001-01-01'),
     (5, 5, '2002-01-01');

Now consider this query:

     EXPLAIN SELECT COUNT(*) FROM t1 WHERE i1 = 3 AND d = '2000-01-01'

The optimizer cannot use the primary key in this case because that
comprises columns '(i1, i2)' and the query does not refer to 'i2'.
Instead, the optimizer can use the secondary index 'k_d' on '(d)', and
the execution plan depends on whether the extended index is used.

When the optimizer does not consider index extensions, it treats the
index 'k_d' as only '(d)'.  'EXPLAIN' for the query
produces this result:

     mysql> EXPLAIN SELECT COUNT(*) FROM t1 WHERE i1 = 3 AND d = '2000-01-01'\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: t1
              type: ref
     possible_keys: PRIMARY,k_d
               key: k_d
           key_len: 4
               ref: const
              rows: 5
             Extra: Using where; Using index

When the optimizer takes index extensions into account, it treats 'k_d'
as '(d, i1, i2)'.  In this case, it can use the leftmost index prefix
'(d, i1)' to produce a better execution plan:

     mysql> EXPLAIN SELECT COUNT(*) FROM t1 WHERE i1 = 3 AND d = '2000-01-01'\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: t1
              type: ref
     possible_keys: PRIMARY,k_d
               key: k_d
           key_len: 8
               ref: const,const
              rows: 1
             Extra: Using index

In both cases, 'key' indicates that the optimizer will use secondary
index 'k_d' but the 'EXPLAIN' output shows these
improvements from using the extended index:

   * 'key_len' goes from 4 bytes to 8 bytes, indicating that key lookups
     use columns 'd' and 'i1', not just 'd'.

   * The 'ref' value changes from 'const' to 'const,const' because the
     key lookup uses two key parts, not one.

   * The 'rows' count decreases from 5 to 1, indicating that 'InnoDB'
     should need to examine fewer rows to produce the result.

   * The 'Extra' value changes from 'Using where; Using index' to 'Using
     index'.  This means that rows can be read using only the index,
     without consulting columns in the data row.

Differences in optimizer behavior for use of extended indexes can also
be seen with 'SHOW STATUS'.:

     FLUSH TABLE t1;
     FLUSH STATUS;
     SELECT COUNT(*) FROM t1 WHERE i1 = 3 AND d = '2000-01-01';
     SHOW STATUS LIKE 'handler_read%'

The preceding statements include 'FLUSH TABLES' and 'FLUSH STATUS' to
flush the table cache and clear the status counters.

Without index extensions, see 'SHOW STATUS' produces
this result:

     +-----------------------+-------+
     | Variable_name         | Value |
     +-----------------------+-------+
     | Handler_read_first    | 0     |
     | Handler_read_key      | 1     |
     | Handler_read_last     | 0     |
     | Handler_read_next     | 5     |
     | Handler_read_prev     | 0     |
     | Handler_read_rnd      | 0     |
     | Handler_read_rnd_next | 0     |
     +-----------------------+-------+

With index extensions, see 'SHOW STATUS' produces this
result.  The 'Handler_read_next' value decreases from 5 to 1, indicating
more efficient use of the index:

     +-----------------------+-------+
     | Variable_name         | Value |
     +-----------------------+-------+
     | Handler_read_first    | 0     |
     | Handler_read_key      | 1     |
     | Handler_read_last     | 0     |
     | Handler_read_next     | 1     |
     | Handler_read_prev     | 0     |
     | Handler_read_rnd      | 0     |
     | Handler_read_rnd_next | 0     |
     +-----------------------+-------+

The 'use_index_extensions' flag of the 'optimizer_switch' system
variable permits control over whether the optimizer takes the primary
key columns into account when determining how to use an 'InnoDB' table's
secondary indexes.  By default, 'use_index_extensions' is enabled.  To
check whether disabling use of index extensions will improve
performance, use this statement:

     SET optimizer_switch = 'use_index_extensions=off';

Use of index extensions by the optimizer is subject to the usual limits
on the number of key parts in an index (16) and the maximum key length
(3072 bytes).

8.3.10 Optimizer Use of Generated Column Indexes
------------------------------------------------

MySQL supports indexes on generated columns.  For example:

     CREATE TABLE t1 (f1 INT, gc INT AS (f1 + 1) STORED, INDEX (gc));

The generated column, 'gc', is defined as the expression 'f1 + 1'.  The
column is also indexed and the optimizer can take that index into
account during execution plan construction.  In the following query, the
'WHERE' clause refers to 'gc' and the optimizer considers whether the
index on that column yields a more efficient plan:

     SELECT * FROM t1 WHERE gc > 9;

The optimizer can use indexes on generated columns to generate execution
plans, even in the absence of direct references in queries to those
columns by name.  This occurs if the 'WHERE', 'ORDER BY', or 'GROUP BY'
clause refers to an expression that matches the definition of some
indexed generated column.  The following query does not refer directly
to 'gc' but does use an expression that matches the definition of 'gc':

     SELECT * FROM t1 WHERE f1 + 1 > 9;

The optimizer recognizes that the expression 'f1 + 1' matches the
definition of 'gc' and that 'gc' is indexed, so it considers that index
during execution plan construction.  You can see this using
'EXPLAIN'.:

     mysql> EXPLAIN SELECT * FROM t1 WHERE f1 + 1 > 9\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: t1
        partitions: NULL
              type: range
     possible_keys: gc
               key: gc
           key_len: 5
               ref: NULL
              rows: 1
          filtered: 100.00
             Extra: Using index condition

In effect, the optimizer has replaced the expression 'f1 + 1' with the
name of the generated column that matches the expression.  That is also
apparent in the rewritten query available in the extended
'EXPLAIN' information displayed by 'SHOW WARNINGS'.:

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Note
        Code: 1003
     Message: /* select#1 */ select `test`.`t1`.`f1` AS `f1`,`test`.`t1`.`gc`
              AS `gc` from `test`.`t1` where (`test`.`t1`.`gc` > 9)

The following restrictions and conditions apply to the optimizer's use
of generated column indexes:

   * For a query expression to match a generated column definition, the
     expression must be identical and it must have the same result type.
     For example, if the generated column expression is 'f1 + 1', the
     optimizer will not recognize a match if the query uses '1 + f1', or
     if 'f1 + 1' (an integer expression) is compared with a string.

   * The optimization applies to these operators: '=', '<', '<=', '>',
     '>=', 'BETWEEN', and 'IN()'.

     For operators other than 'BETWEEN' and 'IN()', either operand can
     be replaced by a matching generated column.  For 'BETWEEN' and
     'IN()', only the first argument can be replaced by a matching
     generated column, and the other arguments must have the same result
     type.  'BETWEEN' and 'IN()' are not yet supported for comparisons
     involving JSON values.

   * The generated column must be defined as an expression that contains
     at least a function call or one of the operators mentioned in the
     preceding item.  The expression cannot consist of a simple
     reference to another column.  For example, 'gc INT AS (f1) STORED'
     consists only of a column reference, so indexes on 'gc' are not
     considered.

   * For comparisons of strings to indexed generated columns that
     compute a value from a JSON function that returns a quoted string,
     'JSON_UNQUOTE()' is needed in the column definition to remove the
     extra quotes from the function value.  (For direct comparison of a
     string to the function result, the JSON comparator handles quote
     removal, but this does not occur for index lookups.)  For example,
     instead of writing a column definition like this:

          doc_name TEXT AS (JSON_EXTRACT(jdoc, '$.name')) STORED

     Write it like this:

          doc_name TEXT AS (JSON_UNQUOTE(JSON_EXTRACT(jdoc, '$.name'))) STORED

     With the latter definition, the optimizer can detect a match for
     both of these comparisons:

          ... WHERE JSON_EXTRACT(jdoc, '$.name') = 'SOME_STRING' ...
          ... WHERE JSON_UNQUOTE(JSON_EXTRACT(jdoc, '$.name')) = 'SOME_STRING' ...

     Without 'JSON_UNQUOTE()' in the column definition, the optimizer
     detects a match only for the first of those comparisons.

   * If the optimizer fails to choose the desired index, an index hint
     can be used to force the optimizer to make a different choice.

8.4 Optimizing Database Structure
=================================

In your role as a database designer, look for the most efficient way to
organize your schemas, tables, and columns.  As when tuning application
code, you minimize I/O, keep related items together, and plan ahead so
that performance stays high as the data volume increases.  Starting with
an efficient database design makes it easier for team members to write
high-performing application code, and makes the database likely to
endure as applications evolve and are rewritten.

8.4.1 Optimizing Data Size
--------------------------

Design your tables to minimize their space on the disk.  This can result
in huge improvements by reducing the amount of data written to and read
from disk.  Smaller tables normally require less main memory while their
contents are being actively processed during query execution.  Any space
reduction for table data also results in smaller indexes that can be
processed faster.

MySQL supports many different storage engines (table types) and row
formats.  For each table, you can decide which storage and indexing
method to use.  Choosing the proper table format for your application
can give you a big performance gain.  See innodb-storage-engine,
and storage-engines.

You can get better performance for a table and minimize storage space by
using the techniques listed here:

   * data-size-table-columns

   * data-size-row-format

   * data-size-indexes

   * data-size-joins

   * data-size-normalization

*Table Columns*

   * Use the most efficient (smallest) data types possible.  MySQL has
     many specialized types that save disk space and memory.  For
     example, use the smaller integer types if possible to get smaller
     tables.  'MEDIUMINT' is often a better choice
     than 'INT' because a 'MEDIUMINT'
     column uses 25% less space.

   * Declare columns to be 'NOT NULL' if possible.  It makes SQL
     operations faster, by enabling better use of indexes and
     eliminating overhead for testing whether each value is 'NULL'.  You
     also save some storage space, one bit per column.  If you really
     need 'NULL' values in your tables, use them.  Just avoid the
     default setting that allows 'NULL' values in every column.

*Row Format*

   * 'InnoDB' tables are created using the 'DYNAMIC' row format by
     default.  To use a row format other than 'DYNAMIC', configure
     'innodb_default_row_format', or specify the 'ROW_FORMAT' option
     explicitly in a 'CREATE TABLE' or 'ALTER TABLE'
     statement.

     The compact family of row formats, which includes 'COMPACT',
     'DYNAMIC', and 'COMPRESSED', decreases row storage space at the
     cost of increasing CPU use for some operations.  If your workload
     is a typical one that is limited by cache hit rates and disk speed
     it is likely to be faster.  If it is a rare case that is limited by
     CPU speed, it might be slower.

     The compact family of row formats also optimizes 'CHAR'
     column storage when using a variable-length character set
     such as 'utf8mb3' or 'utf8mb4'.  With 'ROW_FORMAT=REDUNDANT',
     'CHAR(N)' occupies N x the maximum byte length of the character
     set.  Many languages can be written primarily using single-byte
     'utf8' characters, so a fixed storage length often wastes space.
     With the compact family of rows formats, 'InnoDB' allocates a
     variable amount of storage in the range of N to N x the maximum
     byte length of the character set for these columns by stripping
     trailing spaces.  The minimum storage length is N bytes to
     facilitate in-place updates in typical cases.  For more
     information, see innodb-physical-record.

   * To minimize space even further by storing table data in compressed
     form, specify 'ROW_FORMAT=COMPRESSED' when creating 'InnoDB'
     tables, or run the 'myisampack' command on an
     existing 'MyISAM' table.  ('InnoDB' compressed tables are readable
     and writable, while 'MyISAM' compressed tables are read-only.)

   * For 'MyISAM' tables, if you do not have any variable-length columns
     (see 'VARCHAR', 'TEXT', or 'BLOB'.
     columns), a fixed-size row format is used.  This is faster but may
     waste some space.  See myisam-table-formats.  You can hint
     that you want to have fixed length rows even if you have
     'VARCHAR' columns with the 'CREATE TABLE'
     option 'ROW_FORMAT=FIXED'.

*Indexes*

   * The primary index of a table should be as short as possible.  This
     makes identification of each row easy and efficient.  For 'InnoDB'
     tables, the primary key columns are duplicated in each secondary
     index entry, so a short primary key saves considerable space if you
     have many secondary indexes.

   * Create only the indexes that you need to improve query performance.
     Indexes are good for retrieval, but slow down insert and update
     operations.  If you access a table mostly by searching on a
     combination of columns, create a single composite index on them
     rather than a separate index for each column.  The first part of
     the index should be the column most used.  If you _always_ use many
     columns when selecting from the table, the first column in the
     index should be the one with the most duplicates, to obtain better
     compression of the index.

   * If it is very likely that a long string column has a unique prefix
     on the first number of characters, it is better to index only this
     prefix, using MySQL's support for creating an index on the leftmost
     part of the column (see create-index).  Shorter indexes are
     faster, not only because they require less disk space, but because
     they also give you more hits in the index cache, and thus fewer
     disk seeks.  See server-configuration.

*Joins*

   * In some circumstances, it can be beneficial to split into two a
     table that is scanned very often.  This is especially true if it is
     a dynamic-format table and it is possible to use a smaller static
     format table that can be used to find the relevant rows when
     scanning the table.

   * Declare columns with identical information in different tables with
     identical data types, to speed up joins based on the corresponding
     columns.

   * Keep column names simple, so that you can use the same name across
     different tables and simplify join queries.  For example, in a
     table named 'customer', use a column name of 'name' instead of
     'customer_name'.  To make your names portable to other SQL servers,
     consider keeping them shorter than 18 characters.

*Normalization*

   * Normally, try to keep all data nonredundant (observing what is
     referred to in database theory as _third normal form_).  Instead of
     repeating lengthy values such as names and addresses, assign them
     unique IDs, repeat these IDs as needed across multiple smaller
     tables, and join the tables in queries by referencing the IDs in
     the join clause.

   * If speed is more important than disk space and the maintenance
     costs of keeping multiple copies of data, for example in a business
     intelligence scenario where you analyze all the data from large
     tables, you can relax the normalization rules, duplicating
     information or creating summary tables to gain more speed.

8.4.2 Optimizing MySQL Data Types
---------------------------------

8.4.2.1 Optimizing for Numeric Data
...................................

   * For unique IDs or other values that can be represented as either
     strings or numbers, prefer numeric columns to string columns.
     Since large numeric values can be stored in fewer bytes than the
     corresponding strings, it is faster and takes less memory to
     transfer and compare them.

   * If you are using numeric data, it is faster in many cases to access
     information from a database (using a live connection) than to
     access a text file.  Information in the database is likely to be
     stored in a more compact format than in the text file, so accessing
     it involves fewer disk accesses.  You also save code in your
     application because you can avoid parsing the text file to find
     line and column boundaries.

8.4.2.2 Optimizing for Character and String Types
.................................................

For character and string columns, follow these guidelines:

   * Use binary collation order for fast comparison and sort operations,
     when you do not need language-specific collation features.  You can
     use the 'BINARY' operator to use binary collation within a
     particular query.

   * When comparing values from different columns, declare those columns
     with the same character set and collation wherever possible, to
     avoid string conversions while running the query.

   * For column values less than 8KB in size, use binary 'VARCHAR'
     instead of 'BLOB'.  The 'GROUP BY' and 'ORDER BY' clauses can
     generate temporary tables, and these temporary tables can use the
     'MEMORY' storage engine if the original table does not contain any
     'BLOB' columns.

   * If a table contains string columns such as name and address, but
     many queries do not retrieve those columns, consider splitting the
     string columns into a separate table and using join queries with a
     foreign key when necessary.  When MySQL retrieves any value from a
     row, it reads a data block containing all the columns of that row
     (and possibly other adjacent rows).  Keeping each row small, with
     only the most frequently used columns, allows more rows to fit in
     each data block.  Such compact tables reduce disk I/O and memory
     usage for common queries.

   * When you use a randomly generated value as a primary key in an
     'InnoDB' table, prefix it with an ascending value such as the
     current date and time if possible.  When consecutive primary values
     are physically stored near each other, 'InnoDB' can insert and
     retrieve them faster.

   * See optimize-numeric for reasons why a numeric column is
     usually preferable to an equivalent string column.

8.4.2.3 Optimizing for BLOB Types
.................................

   * When storing a large blob containing textual data, consider
     compressing it first.  Do not use this technique when the entire
     table is compressed by 'InnoDB' or 'MyISAM'.

   * For a table with several columns, to reduce memory requirements for
     queries that do not use the BLOB column, consider splitting the
     BLOB column into a separate table and referencing it with a join
     query when needed.

   * Since the performance requirements to retrieve and display a BLOB
     value might be very different from other data types, you could put
     the BLOB-specific table on a different storage device or even a
     separate database instance.  For example, to retrieve a BLOB might
     require a large sequential disk read that is better suited to a
     traditional hard drive than to an SSD device.

   * See optimize-character for reasons why a binary 'VARCHAR'
     column is sometimes preferable to an equivalent BLOB column.

   * Rather than testing for equality against a very long text string,
     you can store a hash of the column value in a separate column,
     index that column, and test the hashed value in queries.  (Use the
     'MD5()' or 'CRC32()' function to produce the hash value.)  Since
     hash functions can produce duplicate results for different inputs,
     you still include a clause 'AND BLOB_COLUMN = LONG_STRING_VALUE' in
     the query to guard against false matches; the performance benefit
     comes from the smaller, easily scanned index for the hashed values.

8.4.2.4 Using PROCEDURE ANALYSE
...............................

'ANALYSE([MAX_ELEMENTS[,MAX_MEMORY]])'

*Note*:

'PROCEDURE ANALYSE()' is deprecated as of MySQL 5.7.18, and is removed
in MySQL 8.0.

'ANALYSE()' examines the result from a query and returns an analysis of
the results that suggests optimal data types for each column that may
help reduce table sizes.  To obtain this analysis, append 'PROCEDURE
ANALYSE' to the end of a 'SELECT' statement:

     SELECT ... FROM ... WHERE ... PROCEDURE ANALYSE([MAX_ELEMENTS,[MAX_MEMORY]])

For example:

     SELECT col1, col2 FROM table1 PROCEDURE ANALYSE(10, 2000);

The results show some statistics for the values returned by the query,
and propose an optimal data type for the columns.  This can be helpful
for checking your existing tables, or after importing new data.  You may
need to try different settings for the arguments so that 'PROCEDURE
ANALYSE()' does not suggest the 'ENUM' data type when it is
not appropriate.

The arguments are optional and are used as follows:

   * MAX_ELEMENTS (default 256) is the maximum number of distinct values
     that 'ANALYSE()' notices per column.  This is used by 'ANALYSE()'
     to check whether the optimal data type should be of type
     'ENUM'.; if there are more than MAX_ELEMENTS distinct values,
     then 'ENUM' is not a suggested type.

   * MAX_MEMORY (default 8192) is the maximum amount of memory that
     'ANALYSE()' should allocate per column while trying to find all
     distinct values.

A 'PROCEDURE' clause is not permitted in a 'UNION'.
statement.

8.4.3 Optimizing for Many Tables
--------------------------------

Some techniques for keeping individual queries fast involve splitting
data across many tables.  When the number of tables runs into the
thousands or even millions, the overhead of dealing with all these
tables becomes a new performance consideration.

8.4.3.1 How MySQL Opens and Closes Tables
.........................................

When you execute a 'mysqladmin status' command, you
should see something like this:

     Uptime: 426 Running threads: 1 Questions: 11082
     Reloads: 1 Open tables: 12

The 'Open tables' value of 12 can be somewhat puzzling if you have only
six tables.

MySQL is multi-threaded, so there may be many clients issuing queries
for a given table simultaneously.  To minimize the problem with multiple
client sessions having different states on the same table, the table is
opened independently by each concurrent session.  This uses additional
memory but normally increases performance.  With 'MyISAM' tables, one
extra file descriptor is required for the data file for each client that
has the table open.  (By contrast, the index file descriptor is shared
between all sessions.)

The 'table_open_cache' and 'max_connections' system variables affect the
maximum number of files the server keeps open.  If you increase one or
both of these values, you may run up against a limit imposed by your
operating system on the per-process number of open file descriptors.
Many operating systems permit you to increase the open-files limit,
although the method varies widely from system to system.  Consult your
operating system documentation to determine whether it is possible to
increase the limit and how to do so.

'table_open_cache' is related to 'max_connections'.  For example, for
200 concurrent running connections, specify a table cache size of at
least '200 * N', where N is the maximum number of tables per join in any
of the queries which you execute.  You must also reserve some extra file
descriptors for temporary tables and files.

Make sure that your operating system can handle the number of open file
descriptors implied by the 'table_open_cache' setting.  If
'table_open_cache' is set too high, MySQL may run out of file
descriptors and refuse connections, fail to perform queries, and be very
unreliable.

You should also take into account the fact that the 'MyISAM' storage
engine needs two file descriptors for each unique open table.  For a
partitioned 'MyISAM' table, two file descriptors are required for each
partition of the opened table.  (Note further that when 'MyISAM' opens a
partitioned table, it opens every partition of this table, whether or
not a given partition is actually used.  See
partitioning-limitations-myisam-file-descriptors.)  You can increase
the number of file descriptors available to MySQL using the
'--open-files-limit' startup option to 'mysqld'.  See
not-enough-file-handles.

The cache of open tables is kept at a level of 'table_open_cache'
entries.  The server autosizes the cache size at startup.  To set the
size explicitly, set the 'table_open_cache' system variable at startup.
Note that MySQL may temporarily open more tables than this to execute
queries.

MySQL closes an unused table and removes it from the table cache under
the following circumstances:

   * When the cache is full and a thread tries to open a table that is
     not in the cache.

   * When the cache contains more than 'table_open_cache' entries and a
     table in the cache is no longer being used by any threads.

   * When a table flushing operation occurs.  This happens when someone
     issues a 'FLUSH TABLES' statement or executes a 'mysqladmin flush-tables'
     or 'mysqladmin refresh'
     command.

When the table cache fills up, the server uses the following procedure
to locate a cache entry to use:

   * Tables that are not currently in use are released, beginning with
     the table least recently used.

   * If a new table needs to be opened, but the cache is full and no
     tables can be released, the cache is temporarily extended as
     necessary.  When the cache is in a temporarily extended state and a
     table goes from a used to unused state, the table is closed and
     released from the cache.

A 'MyISAM' table is opened for each concurrent access.  This means the
table needs to be opened twice if two threads access the same table or
if a thread accesses the table twice in the same query (for example, by
joining the table to itself).  Each concurrent open requires an entry in
the table cache.  The first open of any 'MyISAM' table takes two file
descriptors: one for the data file and one for the index file.  Each
additional use of the table takes only one file descriptor for the data
file.  The index file descriptor is shared among all threads.

If you are opening a table with the 'HANDLER TBL_NAME OPEN' statement, a
dedicated table object is allocated for the thread.  This table object
is not shared by other threads and is not closed until the thread calls
'HANDLER TBL_NAME CLOSE' or the thread terminates.  When this happens,
the table is put back in the table cache (if the cache is not full).
See handler.

You can determine whether your table cache is too small by checking the
'mysqld' status variable 'Opened_tables', which indicates
the number of table-opening operations since the server started:

     mysql> SHOW GLOBAL STATUS LIKE 'Opened_tables';
     +---------------+-------+
     | Variable_name | Value |
     +---------------+-------+
     | Opened_tables | 2741  |
     +---------------+-------+

If the value is very large or increases rapidly, even when you have not
issued many 'FLUSH TABLES' statements, increase the table cache size.
See server-system-variables, and
server-status-variables.

8.4.3.2 Disadvantages of Creating Many Tables in the Same Database
..................................................................

If you have many 'MyISAM' tables in the same database directory, open,
close, and create operations are slow.  If you execute 'SELECT'
statements on many different tables, there is a little overhead
when the table cache is full, because for every table that has to be
opened, another must be closed.  You can reduce this overhead by
increasing the number of entries permitted in the table cache.

8.4.4 Internal Temporary Table Use in MySQL
-------------------------------------------

In some cases, the server creates internal temporary tables while
processing statements.  Users have no direct control over when this
occurs.

The server creates temporary tables under conditions such as these:

   * Evaluation of 'UNION' statements, with some
     exceptions described later.

   * Evaluation of some views, such those that use the 'TEMPTABLE'
     algorithm, see 'UNION', or aggregation.

   * Evaluation of derived tables (subqueries in the 'FROM' clause).

   * Tables created for subquery or semi-join materialization (see
     subquery-optimization).

   * Evaluation of statements that contain an 'ORDER BY' clause and a
     different 'GROUP BY' clause, or for which the 'ORDER BY' or 'GROUP
     BY' contains columns from tables other than the first table in the
     join queue.

   * Evaluation of 'DISTINCT' combined with 'ORDER BY' may require a
     temporary table.

   * For queries that use the 'SQL_SMALL_RESULT' modifier, MySQL uses an
     in-memory temporary table, unless the query also contains elements
     (described later) that require on-disk storage.

   * To evaluate 'INSERT ... SELECT' statements
     that select from and insert into the same table, MySQL creates an
     internal temporary table to hold the rows from the 'SELECT',
     then inserts those rows into the target table.  See
     insert-select.

   * Evaluation of multiple-table 'UPDATE' statements.

   * Evaluation of 'GROUP_CONCAT()' or 'COUNT(DISTINCT)' expressions.

To determine whether a statement requires a temporary table, use
'EXPLAIN' and check the 'Extra' column to see whether it says
'Using temporary' (see using-explain).  'EXPLAIN' will not
necessarily say 'Using temporary' for derived or materialized temporary
tables.

When the server creates an internal temporary table (either in memory or
on disk), it increments the 'Created_tmp_tables' status variable.  If
the server creates the table on disk (either initially or by converting
an in-memory table) it increments the 'Created_tmp_disk_tables' status
variable.

Some query conditions prevent the use of an in-memory temporary table,
in which case the server uses an on-disk table instead:

   * Presence of a 'BLOB' or 'TEXT' column in
     the table.  This includes user-defined variables having a string
     value because they are treated as 'BLOB' or
     'TEXT' columns, depending on whether their value is a binary
     or nonbinary string, respectively.

   * Presence of any string column with a maximum length larger than 512
     (bytes for binary strings, characters for nonbinary strings) in the
     'SELECT' list, if 'UNION' or
     'UNION ALL' is used.

   * The 'SHOW COLUMNS' and 'DESCRIBE'
     statements use 'BLOB' as the type for some columns, thus
     the temporary table used for the results is an on-disk table.

The server does not use a temporary table for 'UNION'.
statements that meet certain qualifications.  Instead, it retains from
temporary table creation only the data structures necessary to perform
result column typecasting.  The table is not fully instantiated and no
rows are written to or read from it; rows are sent directly to the
client.  The result is reduced memory and disk requirements, and smaller
delay before the first row is sent to the client because the server need
not wait until the last query block is executed.  'EXPLAIN'
and optimizer trace output reflects this execution strategy:
The 'UNION RESULT' query block is not present because that block
corresponds to the part that reads from the temporary table.

These conditions qualify a 'UNION' for evaluation without a temporary
table:

   * The union is 'UNION ALL', not 'UNION' or 'UNION DISTINCT'.

   * There is no global 'ORDER BY' clause.

   * The union is not the top-level query block of an '{INSERT |
     REPLACE} ... SELECT ...' statement.

*Internal Temporary Table Storage Engine*

An internal temporary table can be held in memory and processed by the
'MEMORY' storage engine, or stored on disk by the 'InnoDB' or 'MyISAM'
storage engine.

If an internal temporary table is created as an in-memory table but
becomes too large, MySQL automatically converts it to an on-disk table.
The maximum size for in-memory temporary tables is determined from
whichever of the values of 'tmp_table_size' and 'max_heap_table_size' is
smaller.  This differs from 'MEMORY' tables explicitly created with
'CREATE TABLE'.: For such tables, only the
'max_heap_table_size' system variable determines how large the table is
permitted to grow and there is no conversion to on-disk format.

The 'internal_tmp_disk_storage_engine' system variable determines which
storage engine the server uses to manage on-disk internal temporary
tables.  Permitted values are 'INNODB' (the default) and 'MYISAM'.

*Note*:

When using 'internal_tmp_disk_storage_engine=INNODB', queries that
generate on-disk internal temporary tables that exceed 'InnoDB' row or column limits
return 'Row size too large'
or 'Too many columns' errors.  The workaround is to set
'internal_tmp_disk_storage_engine' to 'MYISAM'.

*Internal Temporary Table Storage Format*

In-memory temporary tables are managed by the 'MEMORY' storage engine,
which uses fixed-length row format.  'VARCHAR' and 'VARBINARY' column
values are padded to the maximum column length, in effect storing them
as 'CHAR' and 'BINARY' columns.

On-disk temporary tables are managed by the 'InnoDB' or 'MyISAM' storage
engine (depending on the 'internal_tmp_disk_storage_engine' setting).
Both engines store temporary tables using dynamic-width row format.
Columns take only as much storage as needed, which reduces disk I/O and
space requirements, and processing time compared to on-disk tables that
use fixed-length rows.

For statements that initially create an internal temporary table in
memory, then convert it to an on-disk table, better performance might be
achieved by skipping the conversion step and creating the table on disk
to begin with.  The 'big_tables' system variable can be used to force
disk storage of internal temporary tables.

8.5 Optimizing for InnoDB Tables
================================

'InnoDB' is the storage engine that MySQL
customers typically use in production databases where reliability and
concurrency are important.  'InnoDB' is the default storage engine in
MySQL. This section explains how to optimize database operations for
'InnoDB' tables.

8.5.1 Optimizing Storage Layout for InnoDB Tables
-------------------------------------------------

   * Once your data reaches a stable size, or a growing table has
     increased by tens or some hundreds of megabytes, consider using the
     'OPTIMIZE TABLE' statement to reorganize the table and compact any
     wasted space.  The reorganized tables require less disk I/O to
     perform full table scans.  This is a straightforward technique that
     can improve performance when other techniques such as improving
     index usage or tuning application code are not practical.

     'OPTIMIZE TABLE' copies the data part of the table and rebuilds the
     indexes.  The benefits come from improved packing of data within
     indexes, and reduced fragmentation within the tablespaces and on
     disk.  The benefits vary depending on the data in each table.  You
     may find that there are significant gains for some and not for
     others, or that the gains decrease over time until you next
     optimize the table.  This operation can be slow if the table is
     large or if the indexes being rebuilt do not fit into the buffer
     pool.  The first run after adding a lot of data to a table is often
     much slower than later runs.

   * In 'InnoDB', having a long 'PRIMARY KEY' (either a single column
     with a lengthy value, or several columns that form a long composite
     value) wastes a lot of disk space.  The primary key value for a row
     is duplicated in all the secondary index records that point to the
     same row.  (See innodb-index-types.)  Create an
     'AUTO_INCREMENT' column as the primary key if your primary key is
     long, or index a prefix of a long 'VARCHAR' column instead of the
     entire column.

   * Use the 'VARCHAR' data type instead of 'CHAR'
     to store variable-length strings or for columns with many
     'NULL' values.  A 'CHAR(N)' column always takes N
     characters to store data, even if the string is shorter or its
     value is 'NULL'.  Smaller tables fit better in the buffer pool and
     reduce disk I/O.

     When using 'COMPACT' row format (the default 'InnoDB' format) and
     variable-length character sets, such as 'utf8' or 'sjis', see
     'CHAR(N)' columns occupy a variable amount of space, but
     still at least N bytes.

   * For tables that are big, or contain lots of repetitive text or
     numeric data, consider using 'COMPRESSED' row format.  Less disk
     I/O is required to bring data into the buffer pool, or to perform
     full table scans.  Before making a permanent decision, measure the
     amount of compression you can achieve by using 'COMPRESSED' versus
     'COMPACT' row format.

8.5.2 Optimizing InnoDB Transaction Management
----------------------------------------------

To optimize 'InnoDB' transaction processing, find the ideal balance
between the performance overhead of transactional features and the
workload of your server.  For example, an application might encounter
performance issues if it commits thousands of times per second, and
different performance issues if it commits only every 2-3 hours.

   * The default MySQL setting 'AUTOCOMMIT=1' can impose performance
     limitations on a busy database server.  Where practical, wrap
     several related data change operations into a single transaction,
     by issuing 'SET AUTOCOMMIT=0' or a 'START TRANSACTION' statement,
     followed by a 'COMMIT' statement after making all the changes.

     'InnoDB' must flush the log to disk at each transaction commit if
     that transaction made modifications to the database.  When each
     change is followed by a commit (as with the default autocommit
     setting), the I/O throughput of the storage device puts a cap on
     the number of potential operations per second.

   * Alternatively, for transactions that consist only of a single
     'SELECT' statement, turning on 'AUTOCOMMIT' helps 'InnoDB'
     to recognize read-only transactions and optimize them.  See
     innodb-performance-ro-txn for requirements.

   * Avoid performing rollbacks after inserting, updating, or deleting
     huge numbers of rows.  If a big transaction is slowing down server
     performance, rolling it back can make the problem worse,
     potentially taking several times as long to perform as the original
     data change operations.  Killing the database process does not
     help, because the rollback starts again on server startup.

     To minimize the chance of this issue occurring:

        * Increase the size of the buffer pool so that all the data
          change changes can be cached rather than immediately written
          to disk.

        * Set 'innodb_change_buffering=all' so that update and delete
          operations are buffered in addition to inserts.

        * Consider issuing 'COMMIT' statements periodically during the
          big data change operation, possibly breaking a single delete
          or update into multiple statements that operate on smaller
          numbers of rows.

     To get rid of a runaway rollback once it occurs, increase the
     buffer pool so that the rollback becomes CPU-bound and runs fast,
     or kill the server and restart with 'innodb_force_recovery=3', as
     explained in innodb-recovery.

     This issue is expected to be infrequent with the default setting
     'innodb_change_buffering=all', which allows update and delete
     operations to be cached in memory, making them faster to perform in
     the first place, and also faster to roll back if needed.  Make sure
     to use this parameter setting on servers that process long-running
     transactions with many inserts, updates, or deletes.

   * If you can afford the loss of some of the latest committed
     transactions if a crash occurs, you can set the
     'innodb_flush_log_at_trx_commit' parameter to 0.  'InnoDB' tries to
     flush the log once per second anyway, although the flush is not
     guaranteed.  Also, set the value of 'innodb_support_xa' to 0, which
     will reduce the number of disk flushes due to synchronizing on disk
     data and the binary log.

     *Note*:

     'innodb_support_xa' is deprecated and will be removed in a future
     release.  As of MySQL 5.7.10, 'InnoDB' support for two-phase commit
     in XA transactions is always enabled and disabling
     'innodb_support_xa' is no longer permitted.

   * When rows are modified or deleted, the rows and associated undo
     logs are not physically removed immediately, or even immediately
     after the transaction commits.  The old data is preserved until
     transactions that started earlier or concurrently are finished, so
     that those transactions can access the previous state of modified
     or deleted rows.  Thus, a long-running transaction can prevent
     'InnoDB' from purging data that was changed by a different
     transaction.

   * When rows are modified or deleted within a long-running
     transaction, other transactions using the 'READ COMMITTED' and
     'REPEATABLE READ' isolation levels have to do more work to
     reconstruct the older data if they read those same rows.

   * When a long-running transaction modifies a table, queries against
     that table from other transactions do not make use of the covering
     index technique.  Queries that normally could retrieve all the
     result columns from a secondary index, instead look up the
     appropriate values from the table data.

     If secondary index pages are found to have a 'PAGE_MAX_TRX_ID' that
     is too new, or if records in the secondary index are delete-marked,
     'InnoDB' may need to look up records using a clustered index.

8.5.3 Optimizing InnoDB Read-Only Transactions
----------------------------------------------

'InnoDB' can avoid the overhead associated with setting up the
transaction ID ('TRX_ID' field) for transactions that are known to be
read-only.  A transaction ID is only needed for a transaction that might
perform write operations or locking reads such as 'SELECT ... FOR
UPDATE'.  Eliminating unnecessary transaction IDs reduces the size of
internal data structures that are consulted each time a query or data
change statement constructs a read view.

'InnoDB' detects read-only transactions when:

   * The transaction is started with the 'START TRANSACTION READ ONLY'
     statement.  In this case, attempting to make changes
     to the database (for 'InnoDB', 'MyISAM', or other types of tables)
     causes an error, and the transaction continues in read-only state:

          ERROR 1792 (25006): Cannot execute statement in a READ ONLY transaction.

     You can still make changes to session-specific temporary tables in
     a read-only transaction, or issue locking queries for them, because
     those changes and locks are not visible to any other transaction.

   * The 'autocommit' setting is turned on, so that the transaction is
     guaranteed to be a single statement, and the single statement
     making up the transaction is a 'non-locking' 'SELECT'
     statement.  That is, a 'SELECT' that does not use a 'FOR
     UPDATE' or 'LOCK IN SHARED MODE' clause.

   * The transaction is started without the 'READ ONLY' option, but no
     updates or statements that explicitly lock rows have been executed
     yet.  Until updates or explicit locks are required, a transaction
     stays in read-only mode.

Thus, for a read-intensive application such as a report generator, you
can tune a sequence of 'InnoDB' queries by grouping them inside
'START TRANSACTION READ ONLY' and 'COMMIT', or by
turning on the 'autocommit' setting before running the 'SELECT'
statements, or simply by avoiding any data change statements
interspersed with the queries.

For information about 'START TRANSACTION' and
'autocommit', see commit.

*Note*:

Transactions that qualify as auto-commit, non-locking, and read-only
(AC-NL-RO) are kept out of certain internal 'InnoDB' data structures and
are therefore not listed in 'SHOW ENGINE INNODB STATUS'
output.

8.5.4 Optimizing InnoDB Redo Logging
------------------------------------

Consider the following guidelines for optimizing redo logging:

   * Make your redo log files big, even as big as the buffer pool.  When
     'InnoDB' has written the redo log files full, it must write the
     modified contents of the buffer pool to disk in a checkpoint.
     Small redo log files cause many unnecessary disk writes.  Although
     historically big redo log files caused lengthy recovery times,
     recovery is now much faster and you can confidently use large redo
     log files.

     The size and number of redo log files are configured using the
     'innodb_log_file_size' and 'innodb_log_files_in_group'
     configuration options.  For information about modifying an existing
     redo log file configuration, see
     innodb-data-log-reconfiguration.

   * Consider increasing the size of the log buffer.  A large log buffer
     enables large transactions to run without a need to write the log
     to disk before the transactions commit.  Thus, if you have
     transactions that update, insert, or delete many rows, making the
     log buffer larger saves disk I/O. Log buffer size is configured
     using the 'innodb_log_buffer_size' configuration option.

   * Configure the 'innodb_log_write_ahead_size' configuration option to
     avoid 'read-on-write'.  This option defines the write-ahead block
     size for the redo log.  Set 'innodb_log_write_ahead_size' to match
     the operating system or file system cache block size.
     Read-on-write occurs when redo log blocks are not entirely cached
     to the operating system or file system due to a mismatch between
     write-ahead block size for the redo log and operating system or
     file system cache block size.

     Valid values for 'innodb_log_write_ahead_size' are multiples of the
     'InnoDB' log file block size (2^n).  The minimum value is the
     'InnoDB' log file block size (512).  Write-ahead does not occur
     when the minimum value is specified.  The maximum value is equal to
     the 'innodb_page_size' value.  If you specify a value for
     'innodb_log_write_ahead_size' that is larger than the
     'innodb_page_size' value, the 'innodb_log_write_ahead_size' setting
     is truncated to the 'innodb_page_size' value.

     Setting the 'innodb_log_write_ahead_size' value too low in relation
     to the operating system or file system cache block size results in
     read-on-write.  Setting the value too high may have a slight impact
     on 'fsync' performance for log file writes due to several blocks
     being written at once.

8.5.5 Bulk Data Loading for InnoDB Tables
-----------------------------------------

These performance tips supplement the general guidelines for fast
inserts in insert-optimization.

   * When importing data into 'InnoDB', turn off autocommit mode,
     because it performs a log flush to disk for every insert.  To
     disable autocommit during your import operation, surround it with
     'SET autocommit' and 'COMMIT'.
     statements:

          SET autocommit=0;
          ... SQL IMPORT STATEMENTS ...
          COMMIT;

     The 'mysqldump' option '--opt' creates dump files
     that are fast to import into an 'InnoDB' table, even without
     wrapping them with the 'SET autocommit' and
     'COMMIT' statements.

   * If you have 'UNIQUE' constraints on secondary keys, you can speed
     up table imports by temporarily turning off the uniqueness checks
     during the import session:

          SET unique_checks=0;
          ... SQL IMPORT STATEMENTS ...
          SET unique_checks=1;

     For big tables, this saves a lot of disk I/O because 'InnoDB' can
     use its change buffer to write secondary index records in a batch.
     Be certain that the data contains no duplicate keys.

   * If you have 'FOREIGN KEY' constraints in your tables, you can speed
     up table imports by turning off the foreign key checks for the
     duration of the import session:

          SET foreign_key_checks=0;
          ... SQL IMPORT STATEMENTS ...
          SET foreign_key_checks=1;

     For big tables, this can save a lot of disk I/O.

   * Use the multiple-row 'INSERT' syntax to reduce
     communication overhead between the client and the server if you
     need to insert many rows:

          INSERT INTO yourtable VALUES (1,2), (5,5), ...;

     This tip is valid for inserts into any table, not just 'InnoDB'
     tables.

   * When doing bulk inserts into tables with auto-increment columns,
     set 'innodb_autoinc_lock_mode' to 2 instead of the default value 1.
     See innodb-auto-increment-handling for details.

   * When performing bulk inserts, it is faster to insert rows in
     'PRIMARY KEY' order.  'InnoDB' tables use a clustered index, which
     makes it relatively fast to use data in the order of the 'PRIMARY
     KEY'.  Performing bulk inserts in 'PRIMARY KEY' order is
     particularly important for tables that do not fit entirely within
     the buffer pool.

   * For optimal performance when loading data into an 'InnoDB'
     'FULLTEXT' index, follow this set of steps:

       1. Define a column 'FTS_DOC_ID' at table creation time, of type
          'BIGINT UNSIGNED NOT NULL', with a unique index named
          'FTS_DOC_ID_INDEX'.  For example:

               CREATE TABLE t1 (
               FTS_DOC_ID BIGINT unsigned NOT NULL AUTO_INCREMENT,
               title varchar(255) NOT NULL DEFAULT '',
               text mediumtext NOT NULL,
               PRIMARY KEY (`FTS_DOC_ID`)
               ) ENGINE=InnoDB DEFAULT CHARSET=latin1;
               CREATE UNIQUE INDEX FTS_DOC_ID_INDEX on t1(FTS_DOC_ID);

       2. Load the data into the table.

       3. Create the 'FULLTEXT' index after the data is loaded.

     *Note*:

     When adding 'FTS_DOC_ID' column at table creation time, ensure that
     the 'FTS_DOC_ID' column is updated when the 'FULLTEXT' indexed
     column is updated, as the 'FTS_DOC_ID' must increase monotonically
     with each 'INSERT' or 'UPDATE'.  If
     you choose not to add the 'FTS_DOC_ID' at table creation time and
     have 'InnoDB' manage DOC IDs for you, 'InnoDB' will add the
     'FTS_DOC_ID' as a hidden column with the next 'CREATE FULLTEXT INDEX'
     call.  This approach, however,
     requires a table rebuild which will impact performance.

8.5.6 Optimizing InnoDB Queries
-------------------------------

To tune queries for 'InnoDB' tables, create an appropriate set of
indexes on each table.  See mysql-indexes for details.  Follow
these guidelines for 'InnoDB' indexes:

   * Because each 'InnoDB' table has a primary key (whether you request
     one or not), specify a set of primary key columns for each table,
     columns that are used in the most important and time-critical
     queries.

   * Do not specify too many or too long columns in the primary key,
     because these column values are duplicated in each secondary index.
     When an index contains unnecessary data, the I/O to read this data
     and memory to cache it reduce the performance and scalability of
     the server.

   * Do not create a separate secondary index for each column, because
     each query can only make use of one index.  Indexes on rarely
     tested columns or columns with only a few different values might
     not be helpful for any queries.  If you have many queries for the
     same table, testing different combinations of columns, try to
     create a small number of concatenated indexes rather than a large
     number of single-column indexes.  If an index contains all the
     columns needed for the result set (known as a covering index), the
     query might be able to avoid reading the table data at all.

   * If an indexed column cannot contain any 'NULL' values, declare it
     as 'NOT NULL' when you create the table.  The optimizer can better
     determine which index is most effective to use for a query, when it
     knows whether each column contains 'NULL' values.

   * You can optimize single-query transactions for 'InnoDB' tables,
     using the technique in innodb-performance-ro-txn.

8.5.7 Optimizing InnoDB DDL Operations
--------------------------------------

   * For DDL operations on tables and indexes ('CREATE', 'ALTER', and
     'DROP' statements), the most significant aspect for 'InnoDB' tables
     is that creating and dropping secondary indexes is much faster in
     MySQL 5.5 and higher, than in earlier versions.  See
     innodb-create-index-overview for details.

   * 'Fast index creation' makes it faster in some cases to drop an
     index before loading data into a table, then re-create the index
     after loading the data.

   * Use 'TRUNCATE TABLE' to empty a table, not
     'DELETE FROM TBL_NAME'.  Foreign key constraints can make a
     'TRUNCATE' statement work like a regular 'DELETE' statement, in
     which case a sequence of commands like 'DROP TABLE'
     and 'CREATE TABLE' might be
     fastest.

   * Because the primary key is integral to the storage layout of each
     'InnoDB' table, and changing the definition of the primary key
     involves reorganizing the whole table, always set up the primary
     key as part of the 'CREATE TABLE' statement,
     and plan ahead so that you do not need to 'ALTER' or 'DROP' the
     primary key afterward.

8.5.8 Optimizing InnoDB Disk I/O
--------------------------------

If you follow best practices for database design and tuning techniques
for SQL operations, but your database is still slow due to heavy disk
I/O activity, consider these disk I/O optimizations.  If the Unix 'top'
tool or the Windows Task Manager shows that the CPU usage percentage
with your workload is less than 70%, your workload is probably
disk-bound.

   * Increase buffer pool size

     When table data is cached in the 'InnoDB' buffer pool, it can be
     accessed repeatedly by queries without requiring any disk I/O.
     Specify the size of the buffer pool with the
     'innodb_buffer_pool_size' option.  This memory area is important
     enough that it is typically recommended that
     'innodb_buffer_pool_size' is configured to 50 to 75 percent of
     system memory.  For more information see, see memory-use.

   * Adjust the flush method

     In some versions of GNU/Linux and Unix, flushing files to disk with
     the Unix 'fsync()' call (which 'InnoDB' uses by default) and
     similar methods is surprisingly slow.  If database write
     performance is an issue, conduct benchmarks with the
     'innodb_flush_method' parameter set to 'O_DSYNC'.

   * Use a noop or deadline I/O scheduler with native AIO on Linux

     'InnoDB' uses the asynchronous I/O subsystem (native AIO) on Linux
     to perform read-ahead and write requests for data file pages.  This
     behavior is controlled by the 'innodb_use_native_aio' configuration
     option, which is enabled by default.  With native AIO, the type of
     I/O scheduler has greater influence on I/O performance.  Generally,
     noop and deadline I/O schedulers are recommended.  Conduct
     benchmarks to determine which I/O scheduler provides the best
     results for your workload and environment.  For more information,
     see innodb-linux-native-aio.

   * Use direct I/O on Solaris 10 for x86_64 architecture

     When using the 'InnoDB' storage engine on Solaris 10 for x86_64
     architecture (AMD Opteron), use direct I/O for 'InnoDB'-related
     files to avoid degradation of 'InnoDB' performance.  To use direct
     I/O for an entire UFS file system used for storing 'InnoDB'-related
     files, mount it with the 'forcedirectio' option; see
     'mount_ufs(1M)'.  (The default on Solaris 10/x86_64 is _not_ to use
     this option.)  To apply direct I/O only to 'InnoDB' file operations
     rather than the whole file system, set 'innodb_flush_method =
     O_DIRECT'.  With this setting, 'InnoDB' calls 'directio()' instead
     of 'fcntl()' for I/O to data files (not for I/O to log files).

   * Use raw storage for data and log files with Solaris 2.6 or later

     When using the 'InnoDB' storage engine with a large
     'innodb_buffer_pool_size' value on any release of Solaris 2.6 and
     up and any platform (sparc/x86/x64/amd64), conduct benchmarks with
     'InnoDB' data files and log files on raw devices or on a separate
     direct I/O UFS file system, using the 'forcedirectio' mount option
     as described earlier.  (It is necessary to use the mount option
     rather than setting 'innodb_flush_method' if you want direct I/O
     for the log files.)  Users of the Veritas file system VxFS should
     use the 'convosync=direct' mount option.

     Do not place other MySQL data files, such as those for 'MyISAM'
     tables, on a direct I/O file system.  Executables or libraries
     _must not_ be placed on a direct I/O file system.

   * Use additional storage devices

     Additional storage devices could be used to set up a RAID
     configuration.  For related information, see disk-issues.

     Alternatively, 'InnoDB' tablespace data files and log files can be
     placed on different physical disks.  For more information, refer to
     the following sections:

        * innodb-init-startup-configuration

        * tablespace-placing

        * general-tablespaces-creating

        * innodb-migration

   * Consider non-rotational storage

     Non-rotational storage generally provides better performance for
     random I/O operations; and rotational storage for sequential I/O
     operations.  When distributing data and log files across rotational
     and non-rotational storage devices, consider the type of I/O
     operations that are predominantly performed on each file.

     Random I/O-oriented files typically include file-per-table and
     general tablespace data files, undo tablespace files, and temporary
     tablespace files.  Sequential I/O-oriented files include 'InnoDB'
     system tablespace files (due to doublewrite buffering and change
     buffering) and log files such as binary log files and redo log
     files.

     Review settings for the following configuration options when using
     non-rotational storage:

        * 'innodb_checksum_algorithm'

          The 'crc32' option uses a faster checksum algorithm and is
          recommended for fast storage systems.

        * 'innodb_flush_neighbors'

          This option optimizes I/O for rotational storage devices.
          Disable it for non-rotational storage or a mix of rotational
          and non-rotational storage.

        * 'innodb_io_capacity'

          The default setting of 200 is generally sufficient for a
          lower-end non-rotational storage device.  For higher-end,
          bus-attached devices, consider a higher setting such as 1000.

        * 'innodb_io_capacity_max'

          The default value of 2000 is intended for workloads that use
          non-rotational storage.  For a high-end, bus-attached
          non-rotational storage device, consider a higher setting such
          as 2500.

        * 'innodb_log_compressed_pages'

          If redo logs are on non-rotational storage, consider disabling
          this option to reduce logging.  See Disable logging of
          compressed pages.

        * 'innodb_log_file_size'

          If redo logs are on non-rotational storage, configure this
          option to maximize caching and write combining.

        * 'innodb_page_size'

          Consider using a page size that matches the internal sector
          size of the disk.  Early-generation SSD devices often have a
          4k sector size.  Some newer devices have a 16k sector size.
          The default 'InnoDB' page size is 16k.  Keeping the page size
          close to the storage device block size minimizes the amount of
          unchanged data that is rewritten to disk.

        * 'binlog_row_image'

          If binary logs are on non-rotational storage and all tables
          have primary keys, consider setting this option to 'minimal'
          to reduce logging.

     Ensure that TRIM support is enabled for your operating system.  It
     is typically enabled by default.

   * Increase I/O capacity to avoid backlogs

     If throughput drops periodically because of 'InnoDB' checkpoint
     operations, consider increasing the value of the
     'innodb_io_capacity' configuration option.  Higher values cause
     more frequent flushing, avoiding the backlog of work that can cause
     dips in throughput.

   * Lower I/O capacity if flushing does not fall behind

     If the system is not falling behind with 'InnoDB' flushing
     operations, consider lowering the value of the 'innodb_io_capacity'
     configuration option.  Typically, you keep this option value as low
     as practical, but not so low that it causes periodic drops in
     throughput as mentioned in the preceding bullet.  In a typical
     scenario where you could lower the option value, you might see a
     combination like this in the output from 'SHOW ENGINE INNODB STATUS'.:

        * History list length low, below a few thousand.

        * Insert buffer merges close to rows inserted.

        * Modified pages in buffer pool consistently well below
          'innodb_max_dirty_pages_pct' of the buffer pool.  (Measure at
          a time when the server is not doing bulk inserts; it is normal
          during bulk inserts for the modified pages percentage to rise
          significantly.)

        * 'Log sequence number - Last checkpoint' is at less than 7/8 or
          ideally less than 6/8 of the total size of the 'InnoDB' log
          files.

   * Store system tablespace files on Fusion-io devices

     You can take advantage of a doublewrite buffer-related I/O
     optimization by storing system tablespace files ('ibdata files') on
     Fusion-io devices that support atomic writes.  In this case,
     doublewrite buffering ('innodb_doublewrite') is automatically
     disabled and Fusion-io atomic writes are used for all data files.
     This feature is only supported on Fusion-io hardware and is only
     enabled for Fusion-io NVMFS on Linux.  To take full advantage of
     this feature, an 'innodb_flush_method' setting of 'O_DIRECT' is
     recommended.

     *Note*:

     Because the doublewrite buffer setting is global, doublewrite
     buffering is also disabled for data files residing on non-Fusion-io
     hardware.

   * Disable logging of compressed pages

     When using the 'InnoDB' table compression feature, images of
     re-compressed pages are written to the redo log when changes are
     made to compressed data.  This behavior is controlled by
     'innodb_log_compressed_pages', which is enabled by default to
     prevent corruption that can occur if a different version of the
     'zlib' compression algorithm is used during recovery.  If you are
     certain that the 'zlib' version will not change, disable
     'innodb_log_compressed_pages' to reduce redo log generation for
     workloads that modify compressed data.

8.5.9 Optimizing InnoDB Configuration Variables
-----------------------------------------------

Different settings work best for servers with light, predictable loads,
versus servers that are running near full capacity all the time, or that
experience spikes of high activity.

Because the 'InnoDB' storage engine performs many of its optimizations
automatically, many performance-tuning tasks involve monitoring to
ensure that the database is performing well, and changing configuration
options when performance drops.  See innodb-performance-schema
for information about detailed 'InnoDB' performance monitoring.

The main configuration steps you can perform include:

   * Enabling 'InnoDB' to use high-performance memory allocators on
     systems that include them.  See
     innodb-performance-use_sys_malloc.

   * Controlling the types of data change operations for which 'InnoDB'
     buffers the changed data, to avoid frequent small disk writes.  See
     innodb-performance-change_buffering.  Because the default
     is to buffer all types of data change operations, only change this
     setting if you need to reduce the amount of buffering.

   * Turning the adaptive hash indexing feature on and off using the
     'innodb_adaptive_hash_index' option.  See
     innodb-adaptive-hash for more information.  You might change this
     setting during periods of unusual activity, then restore it to its
     original setting.

   * Setting a limit on the number of concurrent threads that 'InnoDB'
     processes, if context switching is a bottleneck.  See
     innodb-performance-thread_concurrency.

   * Controlling the amount of prefetching that 'InnoDB' does with its
     read-ahead operations.  When the system has unused I/O capacity,
     more read-ahead can improve the performance of queries.  Too much
     read-ahead can cause periodic drops in performance on a heavily
     loaded system.  See innodb-performance-read_ahead.

   * Increasing the number of background threads for read or write
     operations, if you have a high-end I/O subsystem that is not fully
     utilized by the default values.  See
     innodb-performance-multiple_io_threads.

   * Controlling how much I/O 'InnoDB' performs in the background.  See
     innodb-performance-thread_io_rate.  You might scale back
     this setting if you observe periodic drops in performance.

   * Controlling the algorithm that determines when 'InnoDB' performs
     certain types of background writes.  See
     innodb-performance-adaptive_flushing.  The algorithm works for
     some types of workloads but not others, so might turn off this
     setting if you observe periodic drops in performance.

   * Taking advantage of multicore processors and their cache memory
     configuration, to minimize delays in context switching.  See
     innodb-performance-spin_lock_polling.

   * Preventing one-time operations such as table scans from interfering
     with the frequently accessed data stored in the 'InnoDB' buffer
     cache.  See innodb-performance-midpoint_insertion.

   * Adjusting log files to a size that makes sense for reliability and
     crash recovery.  'InnoDB' log files have often been kept small to
     avoid long startup times after a crash.  Optimizations introduced
     in MySQL 5.5 speed up certain steps of the crash recovery process.
     In particular, scanning the redo log and applying the redo log are
     faster due to improved algorithms for memory management.  If you
     have kept your log files artificially small to avoid long startup
     times, you can now consider increasing log file size to reduce the
     I/O that occurs due recycling of redo log records.

   * Configuring the size and number of instances for the 'InnoDB'
     buffer pool, especially important for systems with multi-gigabyte
     buffer pools.  See innodb-multiple-buffer-pools.

   * Increasing the maximum number of concurrent transactions, which
     dramatically improves scalability for the busiest databases.  See
     innodb-undo-logs.

   * Moving purge operations (a type of garbage collection) into a
     background thread.  See innodb-improved-purge-scheduling.
     To effectively measure the results of this setting, tune the other
     I/O-related and thread-related configuration settings first.

   * Reducing the amount of switching that 'InnoDB' does between
     concurrent threads, so that SQL operations on a busy server do not
     queue up and form a 'traffic jam'.  Set a value for the
     'innodb_thread_concurrency' option, up to approximately 32 for a
     high-powered modern system.  Increase the value for the
     'innodb_concurrency_tickets' option, typically to 5000 or so.  This
     combination of options sets a cap on the number of threads that
     'InnoDB' processes at any one time, and allows each thread to do
     substantial work before being swapped out, so that the number of
     waiting threads stays low and operations can complete without
     excessive context switching.

8.5.10 Optimizing InnoDB for Systems with Many Tables
-----------------------------------------------------

   * If you have configured non-persistent optimizer statistics.
     (a non-default configuration),
     'InnoDB' computes index cardinality values for a table the first
     time that table is accessed after startup, instead of storing such
     values in the table.  This step can take significant time on
     systems that partition the data into many tables.  Since this
     overhead only applies to the initial table open operation, to 'warm
     up' a table for later use, access it immediately after startup by
     issuing a statement such as 'SELECT 1 FROM TBL_NAME LIMIT 1'.

     Optimizer statistics are persisted to disk by default, enabled by
     the 'innodb_stats_persistent' configuration option.  For
     information about persistent optimizer statistics, see
     innodb-persistent-stats.

8.6 Optimizing for MyISAM Tables
================================

The 'MyISAM' storage engine performs best
with read-mostly data or with low-concurrency operations, because table
locks limit the ability to perform simultaneous updates.  In MySQL,
see 'InnoDB' is the default storage engine
rather than 'MyISAM'.

8.6.1 Optimizing MyISAM Queries
-------------------------------

Some general tips for speeding up queries on 'MyISAM' tables:

   * To help MySQL better optimize queries, use 'ANALYZE TABLE'
     or run 'myisamchk --analyze' on a
     table after it has been loaded with data.  This updates a value for
     each index part that indicates the average number of rows that have
     the same value.  (For unique indexes, this is always 1.)  MySQL
     uses this to decide which index to choose when you join two tables
     based on a nonconstant expression.  You can check the result from
     the table analysis by using 'SHOW INDEX FROM TBL_NAME' and
     examining the 'Cardinality' value.  'myisamchk --description --verbose'
     shows index distribution information.

   * To sort an index and data according to an index, use
     'myisamchk --sort-index --sort-records=1'. (assuming
     that you want to sort on index 1).  This is a good way to make
     queries faster if you have a unique index from which you want to
     read all rows in order according to the index.  The first time you
     sort a large table this way, it may take a long time.

   * Try to avoid complex 'SELECT' queries on 'MyISAM'
     tables that are updated frequently, to avoid problems with table
     locking that occur due to contention between readers and writers.

   * 'MyISAM' supports concurrent inserts: If a table has no free blocks
     in the middle of the data file, you can 'INSERT' new
     rows into it at the same time that other threads are reading from
     the table.  If it is important to be able to do this, consider
     using the table in ways that avoid deleting rows.  Another
     possibility is to run 'OPTIMIZE TABLE' to
     defragment the table after you have deleted a lot of rows from it.
     This behavior is altered by setting the 'concurrent_insert'
     variable.  You can force new rows to be appended (and therefore
     permit concurrent inserts), even in tables that have deleted rows.
     See concurrent-inserts.

   * For 'MyISAM' tables that change frequently, try to avoid all
     variable-length columns (see 'VARCHAR', 'BLOB',
     and 'TEXT').  The table uses dynamic row format if it
     includes even a single variable-length column.  See
     storage-engines.

   * It is normally not useful to split a table into different tables
     just because the rows become large.  In accessing a row, the
     biggest performance hit is the disk seek needed to find the first
     byte of the row.  After finding the data, most modern disks can
     read the entire row fast enough for most applications.  The only
     cases where splitting up a table makes an appreciable difference is
     if it is a 'MyISAM' table using dynamic row format that you can
     change to a fixed row size, or if you very often need to scan the
     table but do not need most of the columns.  See
     storage-engines.

   * Use 'ALTER TABLE ... ORDER BY EXPR1, EXPR2, ...' if you usually
     retrieve rows in 'EXPR1, EXPR2, ...' order.  By using this option
     after extensive changes to the table, you may be able to get higher
     performance.

   * If you often need to calculate results such as counts based on
     information from a lot of rows, it may be preferable to introduce a
     new table and update the counter in real time.  An update of the
     following form is very fast:

          UPDATE TBL_NAME SET COUNT_COL=COUNT_COL+1 WHERE KEY_COL=CONSTANT;

     This is very important when you use MySQL storage engines such as
     'MyISAM' that has only table-level locking (multiple readers with
     single writers).  This also gives better performance with most
     database systems, because the row locking manager in this case has
     less to do.

   * Use 'OPTIMIZE TABLE' periodically to avoid
     fragmentation with dynamic-format 'MyISAM' tables.  See
     myisam-table-formats.

   * Declaring a 'MyISAM' table with the 'DELAY_KEY_WRITE=1' table
     option makes index updates faster because they are not flushed to
     disk until the table is closed.  The downside is that if something
     kills the server while such a table is open, you must ensure that
     the table is okay by running the server with the
     '--myisam-recover-options' option, or by running 'myisamchk'
     before restarting the server.  (However, even in this
     case, you should not lose anything by using 'DELAY_KEY_WRITE',
     because the key information can always be generated from the data
     rows.)

   * Strings are automatically prefix- and end-space compressed in
     'MyISAM' indexes.  See create-index.

   * You can increase performance by caching queries or answers in your
     application and then executing many inserts or updates together.
     Locking the table during this operation ensures that the index
     cache is only flushed once after all updates.  You can also take
     advantage of MySQL's query cache to achieve similar results; see
     query-cache.

8.6.2 Bulk Data Loading for MyISAM Tables
-----------------------------------------

These performance tips supplement the general guidelines for fast
inserts in insert-optimization.

   * For a 'MyISAM' table, you can use concurrent inserts to add rows at
     the same time that 'SELECT' statements are running,
     if there are no deleted rows in middle of the data file.  See
     concurrent-inserts.

   * With some extra work, it is possible to make 'LOAD DATA INFILE'
     run even faster for a 'MyISAM' table when the
     table has many indexes.  Use the following procedure:

       1. Execute a 'FLUSH TABLES' statement or a 'mysqladmin flush-tables'
          command.

       2. Use 'myisamchk --keys-used=0 -rq /PATH/TO/DB/TBL_NAME'
          to remove all use of indexes for the table.

       3. Insert data into the table with 'LOAD DATA INFILE'.
          This does not update any indexes and therefore is
          very fast.

       4. If you intend only to read from the table in the future, use
          'myisampack' to compress it.  See
          compressed-format.

       5. Re-create the indexes with 'myisamchk -rq /PATH/TO/DB/TBL_NAME'.
          This creates the index tree
          in memory before writing it to disk, which is much faster than
          updating the index during 'LOAD DATA INFILE'.
          because it avoids lots of disk seeks.  The resulting index
          tree is also perfectly balanced.

       6. Execute a 'FLUSH TABLES' statement or a 'mysqladmin flush-tables'
          command.

     'LOAD DATA INFILE' performs the preceding
     optimization automatically if the 'MyISAM' table into which you
     insert data is empty.  The main difference between automatic
     optimization and using the procedure explicitly is that you can let
     'myisamchk' allocate much more temporary memory
     for the index creation than you might want the server to allocate
     for index re-creation when it executes the 'LOAD DATA INFILE'
     statement.

     You can also disable or enable the nonunique indexes for a 'MyISAM'
     table by using the following statements rather than
     'myisamchk'.  If you use these statements, you can skip
     the 'FLUSH TABLES' operations:

          ALTER TABLE TBL_NAME DISABLE KEYS;
          ALTER TABLE TBL_NAME ENABLE KEYS;

   * To speed up 'INSERT' operations that are performed
     with multiple statements for nontransactional tables, lock your
     tables:

          LOCK TABLES a WRITE;
          INSERT INTO a VALUES (1,23),(2,34),(4,33);
          INSERT INTO a VALUES (8,26),(6,29);
          ...
          UNLOCK TABLES;

     This benefits performance because the index buffer is flushed to
     disk only once, after all 'INSERT' statements have
     completed.  Normally, there would be as many index buffer flushes
     as there are 'INSERT' statements.  Explicit locking
     statements are not needed if you can insert all rows with a single
     'INSERT'.

     Locking also lowers the total time for multiple-connection tests,
     although the maximum wait time for individual connections might go
     up because they wait for locks.  Suppose that five clients attempt
     to perform inserts simultaneously as follows:

        * Connection 1 does 1000 inserts

        * Connections 2, 3, and 4 do 1 insert

        * Connection 5 does 1000 inserts

     If you do not use locking, connections 2, 3, and 4 finish before 1
     and 5.  If you use locking, connections 2, 3, and 4 probably do not
     finish before 1 or 5, but the total time should be about 40%
     faster.

     See 'INSERT', 'UPDATE', and 'DELETE'
     operations are very fast in MySQL, but you can obtain
     better overall performance by adding locks around everything that
     does more than about five successive inserts or updates.  If you do
     very many successive inserts, you could do a 'LOCK TABLES'
     followed by an 'UNLOCK TABLES'.
     once in a while (each 1,000 rows or so) to permit other threads to
     access table.  This would still result in a nice performance gain.

     'INSERT' is still much slower for loading data than
     'LOAD DATA INFILE', even when using the strategies
     just outlined.

   * To increase performance for 'MyISAM' tables, for both 'LOAD DATA INFILE'
     and 'INSERT', enlarge the
     key cache by increasing the 'key_buffer_size' system variable.  See
     server-configuration.

8.6.3 Optimizing REPAIR TABLE Statements
----------------------------------------

'REPAIR TABLE' for 'MyISAM' tables is similar to
using 'myisamchk' for repair operations, and some of
the same performance optimizations apply:

   * 'myisamchk' has variables that control memory
     allocation.  You may be able to its improve performance by setting
     these variables, as described in myisamchk-memory.

   * For 'REPAIR TABLE', the same principle applies,
     but because the repair is done by the server, you set server system
     variables instead of 'myisamchk' variables.
     Also, in addition to setting memory-allocation variables,
     increasing the 'myisam_max_sort_file_size' system variable
     increases the likelihood that the repair will use the faster
     filesort method and avoid the slower repair by key cache method.
     Set the variable to the maximum file size for your system, after
     checking to be sure that there is enough free space to hold a copy
     of the table files.  The free space must be available in the file
     system containing the original table files.

Suppose that a 'myisamchk' table-repair operation is
done using the following options to set its memory-allocation variables:

     --key_buffer_size=128M --myisam_sort_buffer_size=256M
     --read_buffer_size=64M --write_buffer_size=64M

Some of those 'myisamchk' variables correspond to
server system variables:

'myisamchk'.        System Variable
Variable

'key_buffer_size'                    'key_buffer_size'

'myisam_sort_buffer_size'            'myisam_sort_buffer_size'

'read_buffer_size'                   'read_buffer_size'

'write_buffer_size'                  none

Each of the server system variables can be set at runtime, and some of
them ('myisam_sort_buffer_size', 'read_buffer_size') have a session
value in addition to a global value.  Setting a session value limits the
effect of the change to your current session and does not affect other
users.  Changing a global-only variable ('key_buffer_size',
'myisam_max_sort_file_size') affects other users as well.  For
'key_buffer_size', you must take into account that the buffer is shared
with those users.  For example, if you set the 'myisamchk'.
'key_buffer_size' variable to 128MB, you could set the
corresponding 'key_buffer_size' system variable larger than that (if it
is not already set larger), to permit key buffer use by activity in
other sessions.  However, changing the global key buffer size
invalidates the buffer, causing increased disk I/O and slowdown for
other sessions.  An alternative that avoids this problem is to use a
separate key cache, assign to it the indexes from the table to be
repaired, and deallocate it when the repair is complete.  See
multiple-key-caches.

Based on the preceding remarks, a 'REPAIR TABLE'.
operation can be done as follows to use settings similar to the
'myisamchk' command.  Here a separate 128MB key buffer is
allocated and the file system is assumed to permit a file size of at
least 100GB.

     SET SESSION myisam_sort_buffer_size = 256*1024*1024;
     SET SESSION read_buffer_size = 64*1024*1024;
     SET GLOBAL myisam_max_sort_file_size = 100*1024*1024*1024;
     SET GLOBAL repair_cache.key_buffer_size = 128*1024*1024;
     CACHE INDEX TBL_NAME IN repair_cache;
     LOAD INDEX INTO CACHE TBL_NAME;
     REPAIR TABLE TBL_NAME ;
     SET GLOBAL repair_cache.key_buffer_size = 0;

If you intend to change a global variable but want to do so only for the
duration of a 'REPAIR TABLE' operation to minimally
affect other users, save its value in a user variable and restore it
afterward.  For example:

     SET @old_myisam_sort_buffer_size = @@global.myisam_max_sort_file_size;
     SET GLOBAL myisam_max_sort_file_size = 100*1024*1024*1024;
     REPAIR TABLE tbl_name ;
     SET GLOBAL myisam_max_sort_file_size = @old_myisam_max_sort_file_size;

The system variables that affect 'REPAIR TABLE' can
be set globally at server startup if you want the values to be in effect
by default.  For example, add these lines to the server 'my.cnf' file:

     [mysqld]
     myisam_sort_buffer_size=256M
     key_buffer_size=1G
     myisam_max_sort_file_size=100G

These settings do not include 'read_buffer_size'.  Setting
'read_buffer_size' globally to a large value does so for all sessions
and can cause performance to suffer due to excessive memory allocation
for a server with many simultaneous sessions.

8.7 Optimizing for MEMORY Tables
================================

Consider using 'MEMORY' tables for noncritical data that is accessed
often, and is read-only or rarely updated.  Benchmark your application
against equivalent 'InnoDB' or 'MyISAM' tables under a realistic
workload, to confirm that any additional performance is worth the risk
of losing data, or the overhead of copying data from a disk-based table
at application start.

For best performance with 'MEMORY' tables, examine the kinds of queries
against each table, and specify the type to use for each associated
index, either a B-tree index or a hash index.  On the 'CREATE INDEX'
statement, use the clause 'USING BTREE' or 'USING
HASH'.  B-tree indexes are fast for queries that do greater-than or
less-than comparisons through operators such as '>' or 'BETWEEN'.  Hash
indexes are only fast for queries that look up single values through the
'=' operator, or a restricted set of values through the 'IN' operator.
For why 'USING BTREE' is often a better choice than the default 'USING
HASH', see table-scan-avoidance.  For implementation details of
the different types of 'MEMORY' indexes, see index-btree-hash.

8.8 Understanding the Query Execution Plan
==========================================

Depending on the details of your tables, columns, indexes, and the
conditions in your 'WHERE' clause, the MySQL optimizer considers many
techniques to efficiently perform the lookups involved in an SQL query.
A query on a huge table can be performed without reading all the rows; a
join involving several tables can be performed without comparing every
combination of rows.  The set of operations that the optimizer chooses
to perform the most efficient query is called the 'query execution
plan', also known as the 'EXPLAIN' plan.  Your goals are
to recognize the aspects of the 'EXPLAIN' plan that
indicate a query is optimized well, and to learn the SQL syntax and
indexing techniques to improve the plan if you see some inefficient
operations.

8.8.1 Optimizing Queries with EXPLAIN
-------------------------------------

The 'EXPLAIN' statement provides information about how
MySQL executes statements:

   * 'EXPLAIN' works with 'SELECT',
     'DELETE', 'INSERT', 'REPLACE',
     and 'UPDATE' statements.

   * When 'EXPLAIN' is used with an explainable
     statement, MySQL displays information from the optimizer about the
     statement execution plan.  That is, MySQL explains how it would
     process the statement, including information about how tables are
     joined and in which order.  For information about using
     'EXPLAIN' to obtain execution plan information, see
     explain-output.

   * When 'EXPLAIN' is used with 'FOR CONNECTION
     CONNECTION_ID' rather than an explainable statement, it displays
     the execution plan for the statement executing in the named
     connection.  See explain-for-connection.

   * For 'SELECT' statements, see 'EXPLAIN'.
     produces additional execution plan information that can be
     displayed using 'SHOW WARNINGS'.  See
     explain-extended.

   * 'EXPLAIN' is useful for examining queries involving
     partitioned tables.  See partitioning-info.

   * The 'FORMAT' option can be used to select the output format.
     'TRADITIONAL' presents the output in tabular format.  This is the
     default if no 'FORMAT' option is present.  'JSON' format displays
     the information in JSON format.

With the help of 'EXPLAIN', you can see where you should
add indexes to tables so that the statement executes faster by using
indexes to find rows.  You can also use 'EXPLAIN' to
check whether the optimizer joins the tables in an optimal order.  To
give a hint to the optimizer to use a join order corresponding to the
order in which the tables are named in a 'SELECT'.
statement, begin the statement with 'SELECT STRAIGHT_JOIN' rather than
just 'SELECT'.  (See select.)  However,
'STRAIGHT_JOIN' may prevent indexes from being used because it disables
semi-join transformations.  See semi-joins.

The optimizer trace may sometimes provide information complementary to
that of 'EXPLAIN'.  However, the optimizer trace format
and content are subject to change between versions.  For details, see
MySQL Internals: Tracing the Optimizer
(http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

If you have a problem with indexes not being used when you believe that
they should be, run 'ANALYZE TABLE' to update
table statistics, such as cardinality of keys, that can affect the
choices the optimizer makes.  See analyze-table.

*Note*:

'EXPLAIN' can also be used to obtain information about
the columns in a table.  'EXPLAIN TBL_NAME' is
synonymous with 'DESCRIBE TBL_NAME' and 'SHOW COLUMNS FROM TBL_NAME'.
For more information, see describe, and show-columns.

8.8.2 EXPLAIN Output Format
---------------------------

The 'EXPLAIN' statement provides information about how
MySQL executes statements.  'EXPLAIN' works with
'SELECT', 'DELETE', 'INSERT',
'REPLACE', and 'UPDATE' statements.

'EXPLAIN' returns a row of information for each table
used in the 'SELECT' statement.  It lists the tables in
the output in the order that MySQL would read them while processing the
statement.  MySQL resolves all joins using a nested-loop join method.
This means that MySQL reads a row from the first table, and then finds a
matching row in the second table, the third table, and so on.  When all
tables are processed, MySQL outputs the selected columns and backtracks
through the table list until a table is found for which there are more
matching rows.  The next row is read from this table and the process
continues with the next table.

'EXPLAIN' output includes partition information.  Also,
for 'SELECT' statements, see 'EXPLAIN'.
generates extended information that can be displayed with 'SHOW WARNINGS'
following the 'EXPLAIN'. (see
explain-extended).

*Note*:

In older MySQL releases, partition and extended information was produced
using 'EXPLAIN PARTITIONS' and 'EXPLAIN EXTENDED'.
Those syntaxes are still recognized for backward compatibility
but partition and extended output is now enabled by default, so the
'PARTITIONS' and 'EXTENDED' keywords are superfluous and deprecated.
Their use results in a warning, and they will be removed from
'EXPLAIN' syntax in a future MySQL release.

You cannot use the deprecated 'PARTITIONS' and 'EXTENDED' keywords
together in the same 'EXPLAIN' statement.  In addition,
neither of these keywords can be used together with the 'FORMAT' option.

*Note*:

MySQL Workbench has a Visual Explain capability that provides a visual
representation of 'EXPLAIN' output.  See Tutorial: Using
Explain to Improve Query Performance
(http://dev.mysql.com/doc/workbench/en/wb-tutorial-visual-explain-dbt3.html).

   * explain-output-columns

   * explain-join-types

   * explain-extra-information

   * explain-output-interpretation

*EXPLAIN Output Columns*

This section describes the output columns produced by 'EXPLAIN'.
Later sections provide additional information about the 'type'
and 'Extra' columns.

Each output row from 'EXPLAIN' provides information
about one table.  Each row contains the values summarized in
explain-output-column-table, and described in more detail following
the table.  Column names are shown in the table's first column; the
second column provides the equivalent property name shown in the output
when 'FORMAT=JSON' is used.

*EXPLAIN Output Columns*

Column             JSON Name          Meaning

'id'               'select_id'        The 'SELECT' identifier

'select_type'      None               The 'SELECT' type

'table'            'table_name'       The table for the output row

'partitions'       'partitions'       The matching partitions

'type'             'access_type'      The join type

'possible_keys'    'possible_keys'    The possible indexes to choose

'key'              'key'              The index actually chosen

'key_len'          'key_length'       The length of the chosen key

'ref'              'ref'              The columns compared to the index

'rows'             'rows'             Estimate of rows to be examined

'filtered'         'filtered'         Percentage of rows filtered by
                                      table condition

'Extra'            None               Additional information

*Note*:

JSON properties which are 'NULL' are not displayed in JSON-formatted
'EXPLAIN' output.

   * 'id' (JSON name: 'select_id')

     The 'SELECT' identifier.  This is the sequential
     number of the 'SELECT' within the query.  The value
     can be 'NULL' if the row refers to the union result of other rows.
     In this case, the 'table' column shows a value like '<unionM,N>' to
     indicate that the row refers to the union of the rows with 'id'
     values of M and N.

   * 'select_type' (JSON name: none)

     The type of 'SELECT', which can be any of those shown
     in the following table.  A JSON-formatted 'EXPLAIN' exposes the
     'SELECT' type as a property of a 'query_block', unless it is
     'SIMPLE' or 'PRIMARY'.  The JSON names (where applicable) are also
     shown in the table.

     'select_type'      JSON Name          Meaning
     Value

     'SIMPLE'           None               Simple 'SELECT'.
                                           (not using 'UNION'.
                                           or subqueries)

     'PRIMARY'          None               Outermost 'SELECT'.

     See 'UNION'.
                             select. statement in a
                                           'UNION'.

     'DEPENDENT         'dependent'        Second or later 'SELECT'
     statement in a
                                           'UNION', dependent on outer
                                           query

     'UNION RESULT'     'union_result'     Result of a 'UNION'.

     'SUBQUERY'         None               First 'SELECT' in
                                           subquery

     'DEPENDENT         'dependent'        First 'SELECT' in
     SUBQUERY'          ('true')           subquery, dependent on outer query

     'DERIVED'          None               Derived table 'SELECT'.
                                        (subquery in 'FROM'
                                           clause)

     'MATERIALIZED'     'materialized_from_subquery'Materialized subquery

     'UNCACHEABLE       'cacheable'        A subquery for which the result
     SUBQUERY'          ('false')          cannot be cached and must be
                                           re-evaluated for each row of the
                                           outer query

     'UNCACHEABLE       'cacheable'        The second or later select in a
     UNION'             ('false')          'UNION' that belongs
                                           to an uncacheable subquery (see
                                           'UNCACHEABLE SUBQUERY')

     'DEPENDENT' typically signifies the use of a correlated subquery.
     See correlated-subqueries.

     'DEPENDENT SUBQUERY' evaluation differs from 'UNCACHEABLE SUBQUERY'
     evaluation.  For 'DEPENDENT SUBQUERY', the subquery is re-evaluated
     only once for each set of different values of the variables from
     its outer context.  For 'UNCACHEABLE SUBQUERY', the subquery is
     re-evaluated for each row of the outer context.

     Cacheability of subqueries differs from caching of query results in
     the query cache (which is described in
     query-cache-operation).  Subquery caching occurs during query
     execution, whereas the query cache is used to store results only
     after query execution finishes.

     When you specify 'FORMAT=JSON' with 'EXPLAIN', the output has no
     single property directly equivalent to 'select_type'; the
     'query_block' property corresponds to a given 'SELECT'.  Properties
     equivalent to most of the 'SELECT' subquery types just shown are
     available (an example being 'materialized_from_subquery' for
     'MATERIALIZED'), and are displayed when appropriate.  There are no
     JSON equivalents for 'SIMPLE' or 'PRIMARY'.

     The 'select_type' value for non-see 'SELECT' statements
     displays the statement type for affected tables.  For example,
     'select_type' is 'DELETE' for 'DELETE' statements.

   * 'table' (JSON name: 'table_name')

     The name of the table to which the row of output refers.  This can
     also be one of the following values:

        * '<unionM,N>': The row refers to the union of the rows with
          'id' values of M and N.

        * '<derivedN>': The row refers to the derived table result for
          the row with an 'id' value of N.  A derived table may result,
          for example, from a subquery in the 'FROM' clause.

        * '<subqueryN>': The row refers to the result of a materialized
          subquery for the row with an 'id' value of N.  See
          subquery-materialization.

   * 'partitions' (JSON name: 'partitions')

     The partitions from which records would be matched by the query.
     The value is 'NULL' for nonpartitioned tables.  See
     partitioning-info.

   * 'type' (JSON name: 'access_type')

     The join type.  For descriptions of the different types, see
     'EXPLAIN' Join Types.

   * 'possible_keys' (JSON name: 'possible_keys')

     The 'possible_keys' column indicates the indexes from which MySQL
     can choose to find the rows in this table.  Note that this column
     is totally independent of the order of the tables as displayed in
     the output from 'EXPLAIN'.  That means that some of
     the keys in 'possible_keys' might not be usable in practice with
     the generated table order.

     If this column is 'NULL' (or undefined in JSON-formatted output),
     there are no relevant indexes.  In this case, you may be able to
     improve the performance of your query by examining the 'WHERE'
     clause to check whether it refers to some column or columns that
     would be suitable for indexing.  If so, create an appropriate index
     and check the query with 'EXPLAIN' again.  See
     alter-table.

     To see what indexes a table has, use 'SHOW INDEX FROM TBL_NAME'.

   * 'key' (JSON name: 'key')

     The 'key' column indicates the key (index) that MySQL actually
     decided to use.  If MySQL decides to use one of the 'possible_keys'
     indexes to look up rows, that index is listed as the key value.

     It is possible that 'key' will name an index that is not present in
     the 'possible_keys' value.  This can happen if none of the
     'possible_keys' indexes are suitable for looking up rows, but all
     the columns selected by the query are columns of some other index.
     That is, the named index covers the selected columns, so although
     it is not used to determine which rows to retrieve, an index scan
     is more efficient than a data row scan.

     For 'InnoDB', a secondary index might cover the selected columns
     even if the query also selects the primary key because 'InnoDB'
     stores the primary key value with each secondary index.  If 'key'
     is 'NULL', MySQL found no index to use for executing the query more
     efficiently.

     To force MySQL to use or ignore an index listed in the
     'possible_keys' column, use 'FORCE INDEX', 'USE INDEX', or 'IGNORE
     INDEX' in your query.  See index-hints.

     For 'MyISAM' tables, running 'ANALYZE TABLE'.
     helps the optimizer choose better indexes.  For 'MyISAM' tables,
     see 'myisamchk --analyze' does the same.  See
     analyze-table, and myisam-table-maintenance.

   * 'key_len' (JSON name: 'key_length')

     The 'key_len' column indicates the length of the key that MySQL
     decided to use.  The value of 'key_len' enables you to determine
     how many parts of a multiple-part key MySQL actually uses.  If the
     'key' column says 'NULL', the 'len_len' column also says 'NULL'.

     Due to the key storage format, the key length is one greater for a
     column that can be 'NULL' than for a 'NOT NULL' column.

   * 'ref' (JSON name: 'ref')

     The 'ref' column shows which columns or constants are compared to
     the index named in the 'key' column to select rows from the table.

     If the value is 'func', the value used is the result of some
     function.  To see which function, use 'SHOW WARNINGS'
     following 'EXPLAIN' to see the
     extended 'EXPLAIN' output.  The function might
     actually be an operator such as an arithmetic operator.

   * 'rows' (JSON name: 'rows')

     The 'rows' column indicates the number of rows MySQL believes it
     must examine to execute the query.

     For 'InnoDB' tables, this number is
     an estimate, and may not always be exact.

   * 'filtered' (JSON name: 'filtered')

     The 'filtered' column indicates an estimated percentage of table
     rows that will be filtered by the table condition.  That is, 'rows'
     shows the estimated number of rows examined and 'rows' x 'filtered'
     / '100' shows the number of rows that will be joined with previous
     tables.

   * 'Extra' (JSON name: none)

     This column contains additional information about how MySQL
     resolves the query.  For descriptions of the different values, see
     'EXPLAIN' Extra Information.

     There is no single JSON property corresponding to the 'Extra'
     column; however, values that can occur in this column are exposed
     as JSON properties, or as the text of the 'message' property.

*EXPLAIN Join Types*

The 'type' column of 'EXPLAIN' output describes how
tables are joined.  In JSON-formatted output, these are found as values
of the 'access_type' property.  The following list describes the join
types, ordered from the best type to the worst:

   *
     'system'

     The table has only one row (= system table).  This is a special
     case of the 'const' join type.

   *
     'const'

     The table has at most one matching row, which is read at the start
     of the query.  Because there is only one row, values from the
     column in this row can be regarded as constants by the rest of the
     optimizer.  'const' tables are very fast because they are read only
     once.

     'const' is used when you compare all parts of a 'PRIMARY KEY' or
     'UNIQUE' index to constant values.  In the following queries,
     TBL_NAME can be used as a 'const' table:

          SELECT * FROM TBL_NAME WHERE PRIMARY_KEY=1;

          SELECT * FROM TBL_NAME
            WHERE PRIMARY_KEY_PART1=1 AND PRIMARY_KEY_PART2=2;

   *
     'eq_ref'

     One row is read from this table for each combination of rows from
     the previous tables.  Other than the 'system' and 'const' types,
     this is the best possible join type.  It is used when all parts of
     an index are used by the join and the index is a 'PRIMARY KEY' or
     'UNIQUE NOT NULL' index.

     'eq_ref' can be used for indexed columns that are compared using
     the '=' operator.  The comparison value can be a constant or an
     expression that uses columns from tables that are read before this
     table.  In the following examples, MySQL can use an 'eq_ref' join
     to process REF_TABLE:

          SELECT * FROM REF_TABLE,OTHER_TABLE
            WHERE REF_TABLE.KEY_COLUMN=OTHER_TABLE.COLUMN;

          SELECT * FROM REF_TABLE,OTHER_TABLE
            WHERE REF_TABLE.KEY_COLUMN_PART1=OTHER_TABLE.COLUMN
            AND REF_TABLE.KEY_COLUMN_PART2=1;

   *
     'ref'

     All rows with matching index values are read from this table for
     each combination of rows from the previous tables.  'ref' is used
     if the join uses only a leftmost prefix of the key or if the key is
     not a 'PRIMARY KEY' or 'UNIQUE' index (in other words, if the join
     cannot select a single row based on the key value).  If the key
     that is used matches only a few rows, this is a good join type.

     'ref' can be used for indexed columns that are compared using the
     '=' or '<=>' operator.  In the following examples, MySQL can use a
     'ref' join to process REF_TABLE:

          SELECT * FROM REF_TABLE WHERE KEY_COLUMN=EXPR;

          SELECT * FROM REF_TABLE,OTHER_TABLE
            WHERE REF_TABLE.KEY_COLUMN=OTHER_TABLE.COLUMN;

          SELECT * FROM REF_TABLE,OTHER_TABLE
            WHERE REF_TABLE.KEY_COLUMN_PART1=OTHER_TABLE.COLUMN
            AND REF_TABLE.KEY_COLUMN_PART2=1;

   *
     'fulltext'

     The join is performed using a 'FULLTEXT' index.

   *
     'ref_or_null'

     This join type is like 'ref', but with the addition that MySQL does
     an extra search for rows that contain 'NULL' values.  This join
     type optimization is used most often in resolving subqueries.  In
     the following examples, MySQL can use a 'ref_or_null' join to
     process REF_TABLE:

          SELECT * FROM REF_TABLE
            WHERE KEY_COLUMN=EXPR OR KEY_COLUMN IS NULL;

     See is-null-optimization.

   *
     'index_merge'

     This join type indicates that the Index Merge optimization is used.
     In this case, the 'key' column in the output row contains a list of
     indexes used, and 'key_len' contains a list of the longest key
     parts for the indexes used.  For more information, see
     index-merge-optimization.

   *
     'unique_subquery'

     This type replaces 'eq_ref' for some 'IN' subqueries of the
     following form:

          VALUE IN (SELECT PRIMARY_KEY FROM SINGLE_TABLE WHERE SOME_EXPR)

     'unique_subquery' is just an index lookup function that replaces
     the subquery completely for better efficiency.

   *
     'index_subquery'

     This join type is similar to 'unique_subquery'.  It replaces 'IN'
     subqueries, but it works for nonunique indexes in subqueries of the
     following form:

          VALUE IN (SELECT KEY_COLUMN FROM SINGLE_TABLE WHERE SOME_EXPR)

   *
     'range'

     Only rows that are in a given range are retrieved, using an index
     to select the rows.  The 'key' column in the output row indicates
     which index is used.  The 'key_len' contains the longest key part
     that was used.  The 'ref' column is 'NULL' for this type.

     'range' can be used when a key column is compared to a constant
     using any of the '=', '<>', '>', '>=', '<', '<=', 'IS NULL', '<=>',
     'BETWEEN', or 'IN()' operators:

          SELECT * FROM TBL_NAME
            WHERE KEY_COLUMN = 10;

          SELECT * FROM TBL_NAME
            WHERE KEY_COLUMN BETWEEN 10 and 20;

          SELECT * FROM TBL_NAME
            WHERE KEY_COLUMN IN (10,20,30);

          SELECT * FROM TBL_NAME
            WHERE KEY_PART1 = 10 AND KEY_PART2 IN (10,20,30);

   *
     'index'

     The 'index' join type is the same as 'ALL', except that the index
     tree is scanned.  This occurs two ways:

        * If the index is a covering index for the queries and can be
          used to satisfy all data required from the table, only the
          index tree is scanned.  In this case, the 'Extra' column says
          'Using index'.  An index-only scan usually is faster than
          'ALL' because the size of the index usually is smaller than
          the table data.

        * A full table scan is performed using reads from the index to
          look up data rows in index order.  'Uses index' does not
          appear in the 'Extra' column.

     MySQL can use this join type when the query uses only columns that
     are part of a single index.

   *
     'ALL'

     A full table scan is done for each combination of rows from the
     previous tables.  This is normally not good if the table is the
     first table not marked 'const', and usually _very_ bad in all other
     cases.  Normally, you can avoid 'ALL' by adding indexes that enable
     row retrieval from the table based on constant values or column
     values from earlier tables.

*EXPLAIN Extra Information*

The 'Extra' column of 'EXPLAIN' output contains
additional information about how MySQL resolves the query.  The
following list explains the values that can appear in this column.  Each
item also indicates for JSON-formatted output which property displays
the 'Extra' value.  For some of these, there is a specific property.
The others display as the text of the 'message' property.

If you want to make your queries as fast as possible, look out for
'Extra' column values of 'Using filesort' and 'Using temporary', or, in
JSON-formatted 'EXPLAIN' output, for 'using_filesort' and
'using_temporary_table' properties equal to 'true'.

   * 'Child of 'TABLE' pushed join@1' (JSON: 'message' text)

     This table is referenced as the child of TABLE in a join that can
     be pushed down to the NDB kernel.  Applies only in NDB Cluster,
     when pushed-down joins are enabled.  See the description of the
     'ndb_join_pushdown' server system variable for more information and
     examples.

   * 'const row not found' (JSON property: 'const_row_not_found')

     For a query such as 'SELECT ... FROM TBL_NAME', the table was
     empty.

   * 'Deleting all rows' (JSON property: 'message')

     For 'DELETE', some storage engines (such as
     'MyISAM') support a handler method that
     removes all table rows in a simple and fast way.  This 'Extra'
     value is displayed if the engine uses this optimization.

   * 'Distinct' (JSON property: 'distinct')

     MySQL is looking for distinct values, so it stops searching for
     more rows for the current row combination after it has found the
     first matching row.

   * 'FirstMatch(TBL_NAME)' (JSON property: 'first_match')

     The semi-join FirstMatch join shortcutting strategy is used for
     TBL_NAME.

   * 'Full scan on NULL key' (JSON property: 'message')

     This occurs for subquery optimization as a fallback strategy when
     the optimizer cannot use an index-lookup access method.

   * 'Impossible HAVING' (JSON property: 'message')

     The 'HAVING' clause is always false and cannot select any rows.

   * 'Impossible WHERE' (JSON property: 'message')

     The 'WHERE' clause is always false and cannot select any rows.

   * 'Impossible WHERE noticed after reading const tables' (JSON
     property: 'message')

     MySQL has read all 'const' (and 'system') tables and notice that
     the 'WHERE' clause is always false.

   * 'LooseScan(M..N)' (JSON property: 'message')

     The semi-join LooseScan strategy is used.  M and N are key part
     numbers.

   * 'No matching min/max row' (JSON property: 'message')

     No row satisfies the condition for a query such as 'SELECT MIN(...)
     FROM ... WHERE CONDITION'.

   * 'no matching row in const table' (JSON property: 'message')

     For a query with a join, there was an empty table or a table with
     no rows satisfying a unique index condition.

   * 'No matching rows after partition pruning' (JSON property:
     'message')

     For 'DELETE' or 'UPDATE', the
     optimizer found nothing to delete or update after partition
     pruning.  It is similar in meaning to 'Impossible WHERE' for
     'SELECT' statements.

   * 'No tables used' (JSON property: 'message')

     The query has no 'FROM' clause, or has a 'FROM DUAL' clause.

     For 'INSERT' or 'REPLACE'.
     statements, see 'EXPLAIN' displays this value when
     there is no 'SELECT' part.  For example, it appears
     for 'EXPLAIN INSERT INTO t VALUES(10)' because that is equivalent
     to 'EXPLAIN INSERT INTO t SELECT 10 FROM DUAL'.

   * 'Not exists' (JSON property: 'message')

     MySQL was able to do a 'LEFT JOIN' optimization on the query and
     does not examine more rows in this table for the previous row
     combination after it finds one row that matches the 'LEFT JOIN'
     criteria.  Here is an example of the type of query that can be
     optimized this way:

          SELECT * FROM t1 LEFT JOIN t2 ON t1.id=t2.id
            WHERE t2.id IS NULL;

     Assume that 't2.id' is defined as 'NOT NULL'.  In this case, MySQL
     scans 't1' and looks up the rows in 't2' using the values of
     't1.id'.  If MySQL finds a matching row in 't2', it knows that
     't2.id' can never be 'NULL', and does not scan through the rest of
     the rows in 't2' that have the same 'id' value.  In other words,
     for each row in 't1', MySQL needs to do only a single lookup in
     't2', regardless of how many rows actually match in 't2'.

   * 'Plan isn't ready yet' (JSON property: none)

     This value occurs with 'EXPLAIN FOR CONNECTION'
     when the optimizer has not finished
     creating the execution plan for the statement executing in the
     named connection.  If execution plan output comprises multiple
     lines, any or all of them could have this 'Extra' value, depending
     on the progress of the optimizer in determining the full execution
     plan.

   * 'Range checked for each record (index map: N)' (JSON property:
     'message')

     MySQL found no good index to use, but found that some of indexes
     might be used after column values from preceding tables are known.
     For each row combination in the preceding tables, MySQL checks
     whether it is possible to use a 'range' or 'index_merge' access
     method to retrieve rows.  This is not very fast, but is faster than
     performing a join with no index at all.  The applicability criteria
     are as described in range-optimization, and
     index-merge-optimization, with the exception that all column
     values for the preceding table are known and considered to be
     constants.

     Indexes are numbered beginning with 1, in the same order as shown
     by 'SHOW INDEX' for the table.  The index map
     value N is a bitmask value that indicates which indexes are
     candidates.  For example, a value of '0x19' (binary 11001) means
     that indexes 1, 4, and 5 will be considered.

   * 'Scanned N databases' (JSON property: 'message')

     This indicates how many directory scans the server performs when
     processing a query for 'INFORMATION_SCHEMA' tables, as described in
     information-schema-optimization.  The value of N can be 0,
     1, or 'all'.

   * 'Select tables optimized away' (JSON property: 'message')

     The optimizer determined 1) that at most one row should be
     returned, and 2) that to produce this row, a deterministic set of
     rows must be read.  When the rows to be read can be read during the
     optimization phase (for example, by reading index rows), there is
     no need to read any tables during query execution.

     The first condition is fulfilled when the query is implicitly
     grouped (contains an aggregate function but no 'GROUP BY' clause).
     The second condition is fulfilled when one row lookup is performed
     per index used.  The number of indexes read determines the number
     of rows to read.

     Consider the following implicitly grouped query:

          SELECT MIN(c1), MIN(c2) FROM t1;

     Suppose that 'MIN(c1)' can be retrieved by reading one index row
     and 'MIN(c2)' can be retrieved by reading one row from a different
     index.  That is, for each column 'c1' and 'c2', there exists an
     index where the column is the first column of the index.  In this
     case, one row is returned, produced by reading two deterministic
     rows.

     This 'Extra' value does not occur if the rows to read are not
     deterministic.  Consider this query:

          SELECT MIN(c2) FROM t1 WHERE c1 <= 10;

     Suppose that '(c1, c2)' is a covering index.  Using this index, all
     rows with 'c1 <= 10' must be scanned to find the minimum 'c2'
     value.  By contrast, consider this query:

          SELECT MIN(c2) FROM t1 WHERE c1 = 10;

     In this case, the first index row with 'c1 = 10' contains the
     minimum 'c2' value.  Only one row must be read to produce the
     returned row.

     For storage engines that maintain an exact row count per table
     (such as 'MyISAM', but not 'InnoDB'), this 'Extra' value can occur
     for 'COUNT(*)' queries for which the 'WHERE' clause is missing or
     always true and there is no 'GROUP BY' clause.  (This is an
     instance of an implicitly grouped query where the storage engine
     influences whether a deterministic number of rows can be read.)

   * 'Skip_open_table', 'Open_frm_only', 'Open_full_table' (JSON
     property: 'message')

     These values indicate file-opening optimizations that apply to
     queries for 'INFORMATION_SCHEMA' tables, as described in
     information-schema-optimization.

        * 'Skip_open_table': Table files do not need to be opened.  The
          information has already become available within the query by
          scanning the database directory.

        * 'Open_frm_only': Only the table's '.frm' file need be opened.

        * 'Open_full_table': The unoptimized information lookup.  The
          '.frm', '.MYD', and '.MYI' files must be opened.

   * 'Start temporary', 'End temporary' (JSON property: 'message')

     This indicates temporary table use for the semi-join Duplicate
     Weedout strategy.

   * 'unique row not found' (JSON property: 'message')

     For a query such as 'SELECT ... FROM TBL_NAME', no rows satisfy the
     condition for a 'UNIQUE' index or 'PRIMARY KEY' on the table.

   * 'Using filesort' (JSON property: 'using_filesort')

     MySQL must do an extra pass to find out how to retrieve the rows in
     sorted order.  The sort is done by going through all rows according
     to the join type and storing the sort key and pointer to the row
     for all rows that match the 'WHERE' clause.  The keys then are
     sorted and the rows are retrieved in sorted order.  See
     order-by-optimization.

   * 'Using index' (JSON property: 'using_index')

     The column information is retrieved from the table using only
     information in the index tree without having to do an additional
     seek to read the actual row.  This strategy can be used when the
     query uses only columns that are part of a single index.

     For 'InnoDB' tables that have a user-defined clustered index, that
     index can be used even when 'Using index' is absent from the
     'Extra' column.  This is the case if 'type' is 'index' and 'key' is
     'PRIMARY'.

   * 'Using index condition' (JSON property: 'using_index_condition')

     Tables are read by accessing index tuples and testing them first to
     determine whether to read full table rows.  In this way, index
     information is used to defer ('push down') reading full table rows
     unless it is necessary.  See
     index-condition-pushdown-optimization.

   * 'Using index for group-by' (JSON property:
     'using_index_for_group_by')

     Similar to the 'Using index' table access method, 'Using index for
     group-by' indicates that MySQL found an index that can be used to
     retrieve all columns of a 'GROUP BY' or 'DISTINCT' query without
     any extra disk access to the actual table.  Additionally, the index
     is used in the most efficient way so that for each group, only a
     few index entries are read.  For details, see
     group-by-optimization.

   * 'Using join buffer (Block Nested Loop)', 'Using join buffer
     (Batched Key Access)' (JSON property: 'using_join_buffer')

     Tables from earlier joins are read in portions into the join
     buffer, and then their rows are used from the buffer to perform the
     join with the current table.  '(Block Nested Loop)' indicates use
     of the Block Nested-Loop algorithm and '(Batched Key Access)'
     indicates use of the Batched Key Access algorithm.  That is, the
     keys from the table on the preceding line of the 'EXPLAIN'
     output will be buffered, and the matching rows will be
     fetched in batches from the table represented by the line in which
     'Using join buffer' appears.

     In JSON-formatted output, the value of 'using_join_buffer' is
     always either one of 'Block Nested Loop' or 'Batched Key Access'.

   * 'Using MRR' (JSON property: 'message')

     Tables are read using the Multi-Range Read optimization strategy.
     See mrr-optimization.

   * 'Using sort_union(...)', 'Using union(...)', 'Using intersect(...)'
     (JSON property: 'message')

     These indicate the particular algorithm showing how index scans are
     merged for the 'index_merge' join type.  See
     index-merge-optimization.

   * 'Using temporary' (JSON property: 'using_temporary_table')

     To resolve the query, MySQL needs to create a temporary table to
     hold the result.  This typically happens if the query contains
     'GROUP BY' and 'ORDER BY' clauses that list columns differently.

   * 'Using where' (JSON property: 'attached_condition')

     A 'WHERE' clause is used to restrict which rows to match against
     the next table or send to the client.  Unless you specifically
     intend to fetch or examine all rows from the table, you may have
     something wrong in your query if the 'Extra' value is not 'Using
     where' and the table join type is 'ALL' or 'index'.

     'Using where' has no direct counterpart in JSON-formatted output;
     the 'attached_condition' property contains any 'WHERE' condition
     used.

   * 'Using where with pushed condition' (JSON property: 'message')

     This item applies to 'NDB' tables _only_.  It
     means that NDB Cluster is using the Condition Pushdown optimization
     to improve the efficiency of a direct comparison between a
     nonindexed column and a constant.  In such cases, the condition is
     'pushed down' to the cluster's data nodes and is evaluated on all
     data nodes simultaneously.  This eliminates the need to send
     nonmatching rows over the network, and can speed up such queries by
     a factor of 5 to 10 times over cases where Condition Pushdown could
     be but is not used.  For more information, see
     condition-pushdown-optimization.

   * 'Zero limit' (JSON property: 'message')

     The query had a 'LIMIT 0' clause and cannot select any rows.

*EXPLAIN Output Interpretation*

You can get a good indication of how good a join is by taking the
product of the values in the 'rows' column of the 'EXPLAIN'
output.  This should tell you roughly how many rows MySQL must
examine to execute the query.  If you restrict queries with the
'max_join_size' system variable, this row product also is used to
determine which multiple-table 'SELECT' statements to
execute and which to abort.  See server-configuration.

The following example shows how a multiple-table join can be optimized
progressively based on the information provided by 'EXPLAIN'.

Suppose that you have the 'SELECT' statement shown here
and that you plan to examine it using 'EXPLAIN'.:

     EXPLAIN SELECT tt.TicketNumber, tt.TimeIn,
                    tt.ProjectReference, tt.EstimatedShipDate,
                    tt.ActualShipDate, tt.ClientID,
                    tt.ServiceCodes, tt.RepetitiveID,
                    tt.CurrentProcess, tt.CurrentDPPerson,
                    tt.RecordVolume, tt.DPPrinted, et.COUNTRY,
                    et_1.COUNTRY, do.CUSTNAME
             FROM tt, et, et AS et_1, do
             WHERE tt.SubmitTime IS NULL
               AND tt.ActualPC = et.EMPLOYID
               AND tt.AssignedPC = et_1.EMPLOYID
               AND tt.ClientID = do.CUSTNMBR;

For this example, make the following assumptions:

   * The columns being compared have been declared as follows.

     Table   Column             Data Type

     'tt'    'ActualPC'         'CHAR(10)'

     'tt'    'AssignedPC'       'CHAR(10)'

     'tt'    'ClientID'         'CHAR(10)'

     'et'    'EMPLOYID'         'CHAR(15)'

     'do'    'CUSTNMBR'         'CHAR(15)'

   * The tables have the following indexes.

     Table   Index

     'tt'    'ActualPC'

     'tt'    'AssignedPC'

     'tt'    'ClientID'

     'et'    'EMPLOYID' (primary key)

     'do'    'CUSTNMBR' (primary key)

   * The 'tt.ActualPC' values are not evenly distributed.

Initially, before any optimizations have been performed, the
'EXPLAIN' statement produces the following information:

     table type possible_keys key  key_len ref  rows  Extra
     et    ALL  PRIMARY       NULL NULL    NULL 74
     do    ALL  PRIMARY       NULL NULL    NULL 2135
     et_1  ALL  PRIMARY       NULL NULL    NULL 74
     tt    ALL  AssignedPC,   NULL NULL    NULL 3872
                ClientID,
                ActualPC
           Range checked for each record (index map: 0x23)

Because 'type' is 'ALL' for each table, this output indicates that MySQL
is generating a Cartesian product of all the tables; that is, every
combination of rows.  This takes quite a long time, because the product
of the number of rows in each table must be examined.  For the case at
hand, this product is 74 x 2135 x 74 x 3872 = 45,268,558,720 rows.  If
the tables were bigger, you can only imagine how long it would take.

One problem here is that MySQL can use indexes on columns more
efficiently if they are declared as the same type and size.  In this
context, see 'VARCHAR' and 'CHAR' are considered
the same if they are declared as the same size.  'tt.ActualPC' is
declared as 'CHAR(10)' and 'et.EMPLOYID' is 'CHAR(15)', so there is a
length mismatch.

To fix this disparity between column lengths, use 'ALTER TABLE'
to lengthen 'ActualPC' from 10 characters to 15 characters:

     mysql> ALTER TABLE tt MODIFY ActualPC VARCHAR(15);

Now 'tt.ActualPC' and 'et.EMPLOYID' are both 'VARCHAR(15)'.  Executing
the 'EXPLAIN' statement again produces this result:

     table type   possible_keys key     key_len ref         rows    Extra
     tt    ALL    AssignedPC,   NULL    NULL    NULL        3872    Using
                  ClientID,                                         where
                  ActualPC
     do    ALL    PRIMARY       NULL    NULL    NULL        2135
           Range checked for each record (index map: 0x1)
     et_1  ALL    PRIMARY       NULL    NULL    NULL        74
           Range checked for each record (index map: 0x1)
     et    eq_ref PRIMARY       PRIMARY 15      tt.ActualPC 1

This is not perfect, but is much better: The product of the 'rows'
values is less by a factor of 74.  This version executes in a couple of
seconds.

A second alteration can be made to eliminate the column length
mismatches for the 'tt.AssignedPC = et_1.EMPLOYID' and 'tt.ClientID =
do.CUSTNMBR' comparisons:

     mysql> ALTER TABLE tt MODIFY AssignedPC VARCHAR(15),
                           MODIFY ClientID   VARCHAR(15);

After that modification, see 'EXPLAIN' produces the output
shown here:

     table type   possible_keys key      key_len ref           rows Extra
     et    ALL    PRIMARY       NULL     NULL    NULL          74
     tt    ref    AssignedPC,   ActualPC 15      et.EMPLOYID   52   Using
                  ClientID,                                         where
                  ActualPC
     et_1  eq_ref PRIMARY       PRIMARY  15      tt.AssignedPC 1
     do    eq_ref PRIMARY       PRIMARY  15      tt.ClientID   1

At this point, the query is optimized almost as well as possible.  The
remaining problem is that, by default, MySQL assumes that values in the
'tt.ActualPC' column are evenly distributed, and that is not the case
for the 'tt' table.  Fortunately, it is easy to tell MySQL to analyze
the key distribution:

     mysql> ANALYZE TABLE tt;

With the additional index information, the join is perfect and
'EXPLAIN' produces this result:

     table type   possible_keys key     key_len ref           rows Extra
     tt    ALL    AssignedPC    NULL    NULL    NULL          3872 Using
                  ClientID,                                        where
                  ActualPC
     et    eq_ref PRIMARY       PRIMARY 15      tt.ActualPC   1
     et_1  eq_ref PRIMARY       PRIMARY 15      tt.AssignedPC 1
     do    eq_ref PRIMARY       PRIMARY 15      tt.ClientID   1

The 'rows' column in the output from 'EXPLAIN' is an
educated guess from the MySQL join optimizer.  Check whether the numbers
are even close to the truth by comparing the 'rows' product with the
actual number of rows that the query returns.  If the numbers are quite
different, you might get better performance by using 'STRAIGHT_JOIN' in
your 'SELECT' statement and trying to list the tables in
a different order in the 'FROM' clause.  (However, 'STRAIGHT_JOIN' may
prevent indexes from being used because it disables semi-join
transformations.  See semi-joins.)

It is possible in some cases to execute statements that modify data when
'EXPLAIN SELECT' is used with a subquery; for more
information, see derived-tables.

8.8.3 Extended EXPLAIN Output Format
------------------------------------

For 'SELECT' statements, the 'EXPLAIN'.
statement produces extra ('extended') information that is not part of
'EXPLAIN' output but can be viewed by issuing a
'SHOW WARNINGS' statement following 'EXPLAIN'.
The 'Message' value in 'SHOW WARNINGS'.
output displays how the optimizer qualifies table and column names in
the 'SELECT' statement, what the 'SELECT'.
looks like after the application of rewriting and optimization rules,
and possibly other notes about the optimization process.

The extended information displayable with a 'SHOW WARNINGS'
statement following 'EXPLAIN' is produced
only for 'SELECT' statements.  'SHOW WARNINGS'
displays an empty result for other explainable statements
(see 'DELETE', 'INSERT', 'REPLACE',
and 'UPDATE').

*Note*:

In older MySQL releases, extended information was produced using
'EXPLAIN EXTENDED'.  That syntax is still recognized for
backward compatibility but extended output is now enabled by default, so
the 'EXTENDED' keyword is superfluous and deprecated.  Its use results
in a warning, and it will be removed from 'EXPLAIN'.
syntax in a future MySQL release.

Here is an example of extended 'EXPLAIN' output:

     mysql> EXPLAIN
            SELECT t1.a, t1.a IN (SELECT t2.a FROM t2) FROM t1\G
     *************************** 1. row ***************************
                id: 1
       select_type: PRIMARY
             table: t1
              type: index
     possible_keys: NULL
               key: PRIMARY
           key_len: 4
               ref: NULL
              rows: 4
          filtered: 100.00
             Extra: Using index
     *************************** 2. row ***************************
                id: 2
       select_type: SUBQUERY
             table: t2
              type: index
     possible_keys: a
               key: a
           key_len: 5
               ref: NULL
              rows: 3
          filtered: 100.00
             Extra: Using index
     2 rows in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Note
        Code: 1003
     Message: /* select#1 */ select `test`.`t1`.`a` AS `a`,
              <in_optimizer>(`test`.`t1`.`a`,`test`.`t1`.`a` in
              ( <materialize> (/* select#2 */ select `test`.`t2`.`a`
              from `test`.`t2` where 1 having 1 ),
              <primary_index_lookup>(`test`.`t1`.`a` in
              <temporary table> on <auto_key>
              where ((`test`.`t1`.`a` = `materialized-subquery`.`a`))))) AS `t1.a
              IN (SELECT t2.a FROM t2)` from `test`.`t1`
     1 row in set (0.00 sec)

Because the statement displayed by 'SHOW WARNINGS'.
may contain special markers to provide information about query rewriting
or optimizer actions, the statement is not necessarily valid SQL and is
not intended to be executed.  The output may also include rows with
'Message' values that provide additional non-SQL explanatory notes about
actions taken by the optimizer.

The following list describes special markers that can appear in the
extended output displayed by 'SHOW WARNINGS'.:

   * '<auto_key>'

     An automatically generated key for a temporary table.

   * '<cache>(EXPR)'

     The expression (such as a scalar subquery) is executed once and the
     resulting value is saved in memory for later use.  For results
     consisting of multiple values, a temporary table may be created and
     you will see '<temporary table>' instead.

   * '<exists>(QUERY FRAGMENT)'

     The subquery predicate is converted to an 'EXISTS' predicate and
     the subquery is transformed so that it can be used together with
     the 'EXISTS' predicate.

   * '<in_optimizer>(QUERY FRAGMENT)'

     This is an internal optimizer object with no user significance.

   * '<index_lookup>(QUERY FRAGMENT)'

     The query fragment is processed using an index lookup to find
     qualifying rows.

   * '<if>(CONDITION, EXPR1, EXPR2)'

     If the condition is true, evaluate to EXPR1, otherwise EXPR2.

   * '<is_not_null_test>(EXPR)'

     A test to verify that the expression does not evaluate to 'NULL'.

   * '<materialize>(QUERY FRAGMENT)'

     Subquery materialization is used.

   * '`materialized-subquery`.COL_NAME'

     A reference to the column COL_NAME in an internal temporary table
     materialized to hold the result from evaluating a subquery.

   * '<primary_index_lookup>(QUERY FRAGMENT)'

     The query fragment is processed using a primary key lookup to find
     qualifying rows.

   * '<ref_null_helper>(EXPR)'

     This is an internal optimizer object with no user significance.

   * '/* select#N */ SELECT_STMT'

     The 'SELECT' is associated with the row in non-extended
     'EXPLAIN' output that has an 'id' value of N.

   * 'OUTER_TABLES semi join (INNER_TABLES)'

     A semi-join operation.  INNER_TABLES shows the tables that were not
     pulled out.  See semi-joins.

   * '<temporary table>'

     This represents an internal temporary table created to cache an
     intermediate result.

When some tables are of 'const' or 'system' type, expressions involving
columns from these tables are evaluated early by the optimizer and are
not part of the displayed statement.  However, with 'FORMAT=JSON', some
'const' table accesses are displayed as a 'ref' access that uses a const
value.

8.8.4 Obtaining Execution Plan Information for a Named Connection
-----------------------------------------------------------------

To obtain the execution plan for an explainable statement executing in a
named connection, use this statement:

     EXPLAIN [OPTIONS] FOR CONNECTION CONNECTION_ID;

'EXPLAIN FOR CONNECTION' returns the
'EXPLAIN' information that is currently being used to
execute a query in a given connection.  Because of changes to data (and
supporting statistics) it may produce a different result from running
'EXPLAIN' on the equivalent query text.  This difference
in behavior can be useful in diagnosing more transient performance
problems.  For example, if you are running a statement in one session
that is taking a long time to complete, using 'EXPLAIN FOR CONNECTION'
in another session may yield useful
information about the cause of the delay.

CONNECTION_ID is the connection identifier, as obtained from the
'INFORMATION_SCHEMA' 'PROCESSLIST' table or
the 'SHOW PROCESSLIST' statement.  If you have
the 'PROCESS' privilege, you can specify the identifier for any
connection.  Otherwise, you can specify the identifier only for your own
connections.

If the named connection is not executing a statement, the result is
empty.  Otherwise, 'EXPLAIN FOR CONNECTION' applies only if the
statement being executed in the named connection is explainable.  This
includes 'SELECT', 'DELETE', 'INSERT',
see 'REPLACE', and 'UPDATE'.  (However,
'EXPLAIN FOR CONNECTION' does not work for prepared statements, even
prepared statements of those types.)

If the named connection is executing an explainable statement, the
output is what you would obtain by using 'EXPLAIN' on the statement
itself.

If the named connection is executing a statement that is not
explainable, an error occurs.  For example, you cannot name the
connection identifier for your current session because 'EXPLAIN' is not
explainable:

     mysql> SELECT CONNECTION_ID();
     +-----------------+
     | CONNECTION_ID() |
     +-----------------+
     |             373 |
     +-----------------+
     1 row in set (0.00 sec)

     mysql> EXPLAIN FOR CONNECTION 373;
     ERROR 1889 (HY000): EXPLAIN FOR CONNECTION command is supported
     only for SELECT/UPDATE/INSERT/DELETE/REPLACE

The 'Com_explain_other' status variable indicates the number of
'EXPLAIN FOR CONNECTION' statements executed.

8.8.5 Estimating Query Performance
----------------------------------

In most cases, you can estimate query performance by counting disk
seeks.  For small tables, you can usually find a row in one disk seek
(because the index is probably cached).  For bigger tables, you can
estimate that, using B-tree indexes, you need this many seeks to find a
row: 'log(ROW_COUNT) / log(INDEX_BLOCK_LENGTH / 3 * 2 / (INDEX_LENGTH +
DATA_POINTER_LENGTH)) + 1'.

In MySQL, an index block is usually 1,024 bytes and the data pointer is
usually four bytes.  For a 500,000-row table with a key value length of
three bytes (the size of 'MEDIUMINT'), the formula
indicates 'log(500,000)/log(1024/3*2/(3+4)) + 1' = '4' seeks.

This index would require storage of about 500,000 * 7 * 3/2 = 5.2MB
(assuming a typical index buffer fill ratio of 2/3), so you probably
have much of the index in memory and so need only one or two calls to
read data to find the row.

For writes, however, you need four seek requests to find where to place
a new index value and normally two seeks to update the index and write
the row.

The preceding discussion does not mean that your application performance
slowly degenerates by log N.  As long as everything is cached by the OS
or the MySQL server, things become only marginally slower as the table
gets bigger.  After the data gets too big to be cached, things start to
go much slower until your applications are bound only by disk seeks
(which increase by log N).  To avoid this, increase the key cache size
as the data grows.  For 'MyISAM' tables, the key cache size is
controlled by the 'key_buffer_size' system variable.  See
server-configuration.

8.9 Controlling the Query Optimizer
===================================

MySQL provides optimizer control through system variables that affect
how query plans are evaluated, switchable optimizations, optimizer and
index hints, and the optimizer cost model.

8.9.1 Controlling Query Plan Evaluation
---------------------------------------

The task of the query optimizer is to find an optimal plan for executing
an SQL query.  Because the difference in performance between 'good' and
'bad' plans can be orders of magnitude (that is, seconds versus hours or
even days), most query optimizers, including that of MySQL, perform a
more or less exhaustive search for an optimal plan among all possible
query evaluation plans.  For join queries, the number of possible plans
investigated by the MySQL optimizer grows exponentially with the number
of tables referenced in a query.  For small numbers of tables (typically
less than 7 to 10) this is not a problem.  However, when larger queries
are submitted, the time spent in query optimization may easily become
the major bottleneck in the server's performance.

A more flexible method for query optimization enables the user to
control how exhaustive the optimizer is in its search for an optimal
query evaluation plan.  The general idea is that the fewer plans that
are investigated by the optimizer, the less time it spends in compiling
a query.  On the other hand, because the optimizer skips some plans, it
may miss finding an optimal plan.

The behavior of the optimizer with respect to the number of plans it
evaluates can be controlled using two system variables:

   * The 'optimizer_prune_level' variable tells the optimizer to skip
     certain plans based on estimates of the number of rows accessed for
     each table.  Our experience shows that this kind of 'educated
     guess' rarely misses optimal plans, and may dramatically reduce
     query compilation times.  That is why this option is on
     ('optimizer_prune_level=1') by default.  However, if you believe
     that the optimizer missed a better query plan, this option can be
     switched off ('optimizer_prune_level=0') with the risk that query
     compilation may take much longer.  Note that, even with the use of
     this heuristic, the optimizer still explores a roughly exponential
     number of plans.

   * The 'optimizer_search_depth' variable tells how far into the
     'future' of each incomplete plan the optimizer should look to
     evaluate whether it should be expanded further.  Smaller values of
     'optimizer_search_depth' may result in orders of magnitude smaller
     query compilation times.  For example, queries with 12, 13, or more
     tables may easily require hours and even days to compile if
     'optimizer_search_depth' is close to the number of tables in the
     query.  At the same time, if compiled with 'optimizer_search_depth'
     equal to 3 or 4, the optimizer may compile in less than a minute
     for the same query.  If you are unsure of what a reasonable value
     is for 'optimizer_search_depth', this variable can be set to 0 to
     tell the optimizer to determine the value automatically.

8.9.2 Optimizer Hints
---------------------

One means of control over optimizer strategies is to set the
'optimizer_switch' system variable (see
switchable-optimizations).  Changes to this variable affect execution
of all subsequent queries; to affect one query differently from another,
it's necessary to change 'optimizer_switch' before each one.

another way to control the optimizer is by using optimizer hints, which
can be specified within individual statements.  Because optimizer hints
apply on a per-statement basis, they provide finer control over
statement execution plans than can be achieved using 'optimizer_switch'.
For example, you can enable an optimization for one table in a statement
and disable the optimization for a different table.  Hints within a
statement take precedence over 'optimizer_switch' flags.

Examples:

     SELECT /*+ NO_RANGE_OPTIMIZATION(t3 PRIMARY, f2_idx) */ f1
       FROM t3 WHERE f1 > 30 AND f1 < 33;
     SELECT /*+ BKA(t1) NO_BKA(t2) */ * FROM t1 INNER JOIN t2 WHERE ...;
     SELECT /*+ NO_ICP(t1, t2) */ * FROM t1 INNER JOIN t2 WHERE ...;
     SELECT /*+ SEMIJOIN(FIRSTMATCH, LOOSESCAN) */ * FROM t1 ...;
     EXPLAIN SELECT /*+ NO_ICP(t1) */ * FROM t1 WHERE ...;

*Note*:

The 'mysql' client by default strips comments from SQL
statements sent to the server (including optimizer hints) until MySQL
5.7.7, when it was changed to pass optimizer hints to the server.  To
ensure that optimizer hints are not stripped if you are using an older
version of the 'mysql' client with a version of the server
that understands optimizer hints, invoke 'mysql' with the
'--comments' option.

Optimizer hints, described here, differ from index hints, described in
index-hints.  Optimizer and index hints may be used separately
or together.

   * optimizer-hints-overview

   * optimizer-hints-syntax

   * optimizer-hints-table-level

   * optimizer-hints-index-level

   * optimizer-hints-subquery

   * optimizer-hints-execution-time

   * optimizer-hints-query-block-naming

*Optimizer Hint Overview*

Optimizer hints apply at different scope levels:

   * Global: The hint affects the entire statement

   * Query block: The hint affects a particular query block within a
     statement

   * Table-level: The hint affects a particular table within a query
     block

   * Index-level: The hint affects a particular index within a table

The following table summarizes the available optimizer hints, the
optimizer strategies they affect, and the scope or scopes at which they
apply.  More details are given later.

*Optimizer Hints Available*

Hint Name              Description                   Applicable Scopes

'BKA', 'NO_BKA'        Affects Batched Key Access    Query block, table
                       join processing

'BNL', 'NO_BNL'        Affects Block Nested-Loop     Query block, table
                       join processing

'MAX_EXECUTION_TIME'   Limits statement execution    Global
                       time

'MRR', 'NO_MRR'        Affects Multi-Range Read      Table, index
                       optimization

'NO_ICP'               Affects Index Condition       Table, index
                       Pushdown optimization

'NO_RANGE_OPTIMIZATION'Affects range optimization    Table, index

'QB_NAME'              Assigns name to query block   Query block

'SEMIJOIN',            Affects semi-join             Query block
'NO_SEMIJOIN'          strategies

'SUBQUERY'             Affects materialization,      Query block
                       'IN'-to-'EXISTS' subquery
                       stratgies

Disabling an optimization prevents the optimizer from using it.
Enabling an optimization means the optimizer is free to use the strategy
if it applies to statement execution, not that the optimizer necessarily
will use it.

*Optimizer Hint Syntax*

MySQL supports comments in SQL statements as described in
comments.  Optimizer hints must be specified within '/*+ ... */'
comments.  That is, optimizer hints use a variant of '/* ... */' C-style
comment syntax, with a '+' character following the '/*' comment opening
sequence.  Examples:

     /*+ BKA(t1) */
     /*+ BNL(t1, t2) */
     /*+ NO_RANGE_OPTIMIZATION(t4 PRIMARY) */
     /*+ QB_NAME(qb2) */

Whitespace is permitted after the '+' character.

The parser recognizes optimizer hint comments after the initial keyword
of 'SELECT', 'UPDATE', 'INSERT',
see 'REPLACE', and 'DELETE'.
statements.  Hints are permitted in these contexts:

   * At the beginning of query and data change statements:

          SELECT /*+ ... */ ...
          INSERT /*+ ... */ ...
          REPLACE /*+ ... */ ...
          UPDATE /*+ ... */ ...
          DELETE /*+ ... */ ...

   * At the beginning of query blocks:

          (SELECT /*+ ... */ ... )
          (SELECT ... ) UNION (SELECT /*+ ... */ ... )
          (SELECT /*+ ... */ ... ) UNION (SELECT /*+ ... */ ... )
          UPDATE ... WHERE x IN (SELECT /*+ ... */ ...)
          INSERT ... SELECT /*+ ... */ ...

   * In hintable statements prefaced by 'EXPLAIN'.  For
     example:

          EXPLAIN SELECT /*+ ... */ ...
          EXPLAIN UPDATE ... WHERE x IN (SELECT /*+ ... */ ...)

     The implication is that you can use 'EXPLAIN' to
     see how optimizer hints affect execution plans.  Use 'SHOW WARNINGS'
     immediately after 'EXPLAIN'
     to see how hints are used.  The extended 'EXPLAIN' output
     displayed by a following 'SHOW WARNINGS'.
     indicates which hints were used.  Ignored hints are not displayed.

A hint comment may contain multiple hints, but a query block cannot
contain multiple hint comments.  This is valid:

     SELECT /*+ BNL(t1) BKA(t2) */ ...

But this is invalid:

     SELECT /*+ BNL(t1) */ /* BKA(t2) */ ...

When a hint comment contains multiple hints, the possibility of
duplicates and conflicts exists.  The following general guidelines
apply.  For specific hint types, additional rules may apply, as
indicated in the hint descriptions.

   * Duplicate hints: For a hint such as '/*+ MRR(idx1) MRR(idx1) */',
     MySQL uses the first hint and issues a warning about the duplicate
     hint.

   * Conflicting hints: For a hint such as '/*+ MRR(idx1) NO_MRR(idx1)
     */', MySQL uses the first hint and issues a warning about the
     second conflicting hint.

Query block names are identifiers and follow the usual rules about what
names are valid and how to quote them (see identifiers).

Hint names, query block names, and strategy names are not case
sensitive.  References to table and index names follow the usual
identifier case sensitivity rules (see
identifier-case-sensitivity).

*Table-Level Optimizer Hints*

Table-level hints affect use of the Block Nested-Loop (BNL) and Batched
Key Access (BKA) join-processing algorithms (see
bnl-bka-optimization).  These hint types apply to specific tables, or
all tables in a query block.

Syntax of table-level hints:

     HINT_NAME([@QUERY_BLOCK_NAME] [TBL_NAME [, TBL_NAME] ...])
     HINT_NAME([TBL_NAME@QUERY_BLOCK_NAME [, TBL_NAME@QUERY_BLOCK_NAME] ...])

The syntax refers to these terms:

   * HINT_NAME: These hint names are permitted:

        * 'BKA', 'NO_BKA': Enable or disable BKA for the specified
          tables.

        * 'BNL', 'NO_BNL': Enable or disable BNL for the specified
          tables.

     *Note*:

     To use a BNL or BKA hint to enable join buffering for any inner
     table of an outer join, join buffering must be enabled for all
     inner tables of the outer join.

   * TBL_NAME: The name of a table used in the statement.  The hint
     applies to all tables that it names.  If the hint names no tables,
     it applies to all tables of the query block in which it occurs.

     If a table has an alias, hints must refer to the alias, not the
     table name.

     Table names in hints cannot be qualified with schema names.

   * QUERY_BLOCK_NAME: The query block to which the hint applies.  If
     the hint includes no leading '@QUERY_BLOCK_NAME', the hint applies
     to the query block in which it occurs.  For
     'TBL_NAME@QUERY_BLOCK_NAME' syntax, the hint applies to the named
     table in the named query block.  To assign a name to a query block,
     see optimizer-hints-query-block-naming.

Examples:

     SELECT /*+ NO_BKA(t1, t2) */ t1.* FROM t1 INNER JOIN t2 INNER JOIN t3;
     SELECT /*+ NO_BNL() BKA(t1) */ t1.* FROM t1 INNER JOIN t2 INNER JOIN t3;

A table-level hint applies to tables that receive records from previous
tables, not sender tables.  Consider this statement:

     SELECT /*+ BNL(t2) */ FROM t1, t2;

If the optimizer chooses to process 't1' first, it applies a Block
Nested-Loop join to 't2' by buffering the rows from 't1' before starting
to read from 't2'.  If the optimizer instead chooses to process 't2'
first, the hint has no effect because 't2' is a sender table.

*Index-Level Optimizer Hints*

Index-level hints affect which index-processing strategies the optimizer
uses for particular tables or indexes.  These hint types affect use of
Index Condition Pushdown (ICP), Multi-Range Read (MRR), and range
optimizations (see select-optimization).

Syntax of index-level hints:

     HINT_NAME([@QUERY_BLOCK_NAME] TBL_NAME [INDEX_NAME [, INDEX_NAME] ...])
     HINT_NAME(TBL_NAME@QUERY_BLOCK_NAME [INDEX_NAME [, INDEX_NAME] ...])

The syntax refers to these terms:

   * HINT_NAME: These hint names are permitted:

        * 'MRR', 'NO_MRR': Enable or disable MRR for the specified
          tables or indexes.  MRR hints apply only to 'InnoDB' and
          'MyISAM' tables.

        * 'NO_ICP': Disable ICP for the specified tables or indexes.  By
          default, ICP is a candidate optimization strategy, so there is
          no hint for enabling it.

        * 'NO_RANGE_OPTIMIZATION': Disable index range access for the
          specified tables or indexes.  This hint also disables Index
          Merge and Loose Index Scan for the tables or indexes.  By
          default, range access is a candidate optimization strategy, so
          there is no hint for enabling it.

          This hint may be useful when the number of ranges may be high
          and range optimization would require many resources.

   * TBL_NAME: The table to which the hint applies.'

   * INDEX_NAME: The name of an index in the named table.  The hint
     applies to all indexes that it names.  If the hint names no
     indexes, it applies to all indexes in the table.

     To refer to a primary key, use the name 'PRIMARY'.  To see the
     index names for a table, use 'SHOW INDEX'.

   * QUERY_BLOCK_NAME: The query block to which the hint applies.  If
     the hint includes no leading '@QUERY_BLOCK_NAME', the hint applies
     to the query block in which it occurs.  For
     'TBL_NAME@QUERY_BLOCK_NAME' syntax, the hint applies to the named
     table in the named query block.  To assign a name to a query block,
     see optimizer-hints-query-block-naming.

Examples:

     SELECT /*+ MRR(t1) */ * FROM t1 WHERE f2 <= 3 AND 3 <= f3;
     SELECT /*+ NO_RANGE_OPTIMIZATION(t3 PRIMARY, f2_idx) */ f1
       FROM t3 WHERE f1 > 30 AND f1 < 33;
     INSERT INTO t3(f1, f2, f3)
       (SELECT /*+ NO_ICP(t2) */ t2.f1, t2.f2, t2.f3 FROM t1,t2
        WHERE t1.f1=t2.f1 AND t2.f2 BETWEEN t1.f1
        AND t1.f2 AND t2.f2 + 1 >= t1.f1 + 1);

*Subquery Optimizer Hints*

Subquery hints affect whether to use semi-join transformations and which
semi-join strategies to permit, and, when semi-joins are not used,
whether to use subquery materialization or 'IN'-to-'EXISTS'
transformations.  For more information about these optimizations, see
subquery-optimization.

Syntax of hints that affect semi-join strategies:

     HINT_NAME([@QUERY_BLOCK_NAME] [STRATEGY [, STRATEGY] ...])

The syntax refers to these terms:

   * HINT_NAME: These hint names are permitted:

        * 'SEMIJOIN', 'NO_SEMIJOIN': Enable or disable the named
          semi-join strategies.

   * STRATEGY: A semi-join strategy to be enabled or disabled.  These
     strategy names are permitted: 'DUPSWEEDOUT', 'FIRSTMATCH',
     'LOOSESCAN', 'MATERIALIZATION'.

     For 'SEMIJOIN' hints, if no strategies are named, semi-join is used
     if possible based on the strategies enabled according to the
     'optimizer_switch' system variable.  If strategies are named but
     inapplicable for the statement, 'DUPSWEEDOUT' is used.

     For 'NO_SEMIJOIN' hints, if no strategies are named, semi-join is
     not used.  If strategies are named that rule out all applicable
     strategies for the statement, 'DUPSWEEDOUT' is used.

If one subquery is nested within another and both are merged into a
semi-join of an outer query, any specification of semi-join strategies
for the innermost query are ignored.  'SEMIJOIN' and 'NO_SEMIJOIN' hints
can still be used to enable or disable semi-join transformations for
such nested subqueries.

If 'DUPSWEEDOUT' is disabled, on occasion the optimizer may generate a
query plan that is far from optimal.  This occurs due to heuristic
pruning during greedy search, which can be avoided by setting
'optimizer_prune_level=0'.

Examples:

     SELECT /*+ NO_SEMIJOIN(@subq1 FIRSTMATCH, LOOSESCAN) */ * FROM t2
       WHERE t2.a IN (SELECT /*+ QB_NAME(subq1) */ a FROM t3);
     SELECT /*+ SEMIJOIN(@subq1 MATERIALIZATION, DUPSWEEDOUT) */ * FROM t2
       WHERE t2.a IN (SELECT /*+ QB_NAME(subq1) */ a FROM t3);

Syntax of hints that affect whether to use subquery materialization or
'IN'-to-'EXISTS' transformations:

     SUBQUERY([@QUERY_BLOCK_NAME] STRATEGY)

The hint name is always 'SUBQUERY'.

For 'SUBQUERY' hints, these STRATEGY values are permitted: 'INTOEXISTS',
'MATERIALIZATION'.

Examples:

     SELECT id, a IN (SELECT /*+ SUBQUERY(MATERIALIZATION) */ a FROM t1) FROM t2;
     SELECT * FROM t2 WHERE t2.a IN (SELECT /*+ SUBQUERY(INTOEXISTS) */ a FROM t1);

For semi-join and 'SUBQUERY' hints, a leading '@QUERY_BLOCK_NAME'
specifies the query block to which the hint applies.  If the hint
includes no leading '@QUERY_BLOCK_NAME', the hint applies to the query
block in which it occurs.  To assign a name to a query block, see
optimizer-hints-query-block-naming.

If a hint comment contains multiple subquery hints, the first is used.
If there are other following hints of that type, they produce a warning.
Following hints of other types are silently ignored.

*Statement Execution Time Optimizer Hints*

The 'MAX_EXECUTION_TIME' hint is permitted only for 'SELECT'
statements.  It places a limit N (a timeout value in
milliseconds) on how long a statement is permitted to execute before the
server terminates it:

     MAX_EXECUTION_TIME(N)

Example with a timeout of 1 second (1000 milliseconds):

     SELECT /*+ MAX_EXECUTION_TIME(1000) */ * FROM t1 INNER JOIN t2 WHERE ...

The 'MAX_EXECUTION_TIME(N)' hint sets a statement execution timeout of N
milliseconds.  If this option is absent or N is 0, the statement timeout
established by the 'max_execution_time' system variable applies.

The 'MAX_EXECUTION_TIME' hint is applicable as follows:

   * For statements with multiple 'SELECT' keywords, such as unions or
     statements with subqueries, 'MAX_EXECUTION_TIME' applies to the
     entire statement and must appear after the first 'SELECT'.

   * It applies to read-only 'SELECT' statements.
     Statements that are not read only are those that invoke a stored
     function that modifies data as a side effect.

   * It does not apply to 'SELECT' statements in stored
     programs and is ignored.

*Optimizer Hints for Naming Query Blocks*

Table-level, index-level, and subquery optimizer hints permit specific
query blocks to be named as part of their argument syntax.  To create
these names, use the 'QB_NAME' hint, which assigns a name to the query
block in which it occurs:

     QB_NAME(NAME)

'QB_NAME' hints can be used to make explicit in a clear way which query
blocks other hints apply to.  They also permit all non-query block name
hints to be specified within a single hint comment for easier
understanding of complex statements.  Consider the following statement:

     SELECT ...
       FROM (SELECT ...
       FROM (SELECT ... FROM ...)) ...

'QB_NAME' hints assign names to query blocks in the statement:

     SELECT /*+ QB_NAME(qb1) */ ...
       FROM (SELECT /*+ QB_NAME(qb2) */ ...
       FROM (SELECT /*+ QB_NAME(qb3) */ ... FROM ...)) ...

Then other hints can use those names to refer to the appropriate query
blocks:

     SELECT /*+ QB_NAME(qb1) MRR(@qb1 t1) BKA(@qb2) NO_MRR(@qb3t1 idx1, id2) */ ...
       FROM (SELECT /*+ QB_NAME(qb2) */ ...
       FROM (SELECT /*+ QB_NAME(qb3) */ ... FROM ...)) ...

The resulting effect is as follows:

   * 'MRR(@qb1 t1)' applies to table 't1' in query block 'qb1'.

   * 'BKA(@qb2)' applies to query block 'qb2'.

   * 'NO_MRR(@qb3 t1 idx1, id2)' applies to indexes 'idx1' and 'idx2' in
     table 't1' in query block 'qb3'.

Query block names are identifiers and follow the usual rules about what
names are valid and how to quote them (see identifiers).  For
example, a query block name that contains spaces must be quoted, which
can be done using backticks:

     SELECT /*+ BKA(@`my hint name`) */ ...
       FROM (SELECT /*+ QB_NAME(`my hint name`) */ ...) ...

If the 'ANSI_QUOTES' SQL mode is enabled, it is also possible to quote
query block names within double quotation marks:

     SELECT /*+ BKA(@"my hint name") */ ...
       FROM (SELECT /*+ QB_NAME("my hint name") */ ...) ...

8.9.3 Switchable Optimizations
------------------------------

The 'optimizer_switch' system variable enables control over optimizer
behavior.  Its value is a set of flags, each of which has a value of
'on' or 'off' to indicate whether the corresponding optimizer behavior
is enabled or disabled.  This variable has global and session values and
can be changed at runtime.  The global default can be set at server
startup.

To see the current set of optimizer flags, select the variable value:

     mysql> SELECT @@optimizer_switch\G
     *************************** 1. row ***************************
     @@optimizer_switch: index_merge=on,index_merge_union=on,
                         index_merge_sort_union=on,
                         index_merge_intersection=on,
                         engine_condition_pushdown=on,
                         index_condition_pushdown=on,
                         mrr=on,mrr_cost_based=on,
                         block_nested_loop=on,batched_key_access=off,
                         materialization=on,semijoin=on,loosescan=on,
                         firstmatch=on,duplicateweedout=on,
                         subquery_materialization_cost_based=on,
                         use_index_extensions=on,
                         condition_fanout_filter=on,derived_merge=on

To change the value of 'optimizer_switch', assign a value consisting of
a comma-separated list of one or more commands:

     SET [GLOBAL|SESSION] optimizer_switch='COMMAND[,COMMAND]...';

Each COMMAND value should have one of the forms shown in the following
table.

Command Syntax     Meaning

'default'          Reset every optimization to its default value

'OPT_NAME=default' Set the named optimization to its default value

'OPT_NAME=off'     Disable the named optimization

'OPT_NAME=on'      Enable the named optimization

The order of the commands in the value does not matter, although the
'default' command is executed first if present.  Setting an OPT_NAME
flag to 'default' sets it to whichever of 'on' or 'off' is its default
value.  Specifying any given OPT_NAME more than once in the value is not
permitted and causes an error.  Any errors in the value cause the
assignment to fail with an error, leaving the value of
'optimizer_switch' unchanged.

The following list describes the permissible OPT_NAME flag names,
grouped by optimization strategy:

   * Batched Key Access Flags

        * 'batched_key_access' (default 'off')

          Controls use of BKA join algorithm.

     For 'batched_key_access' to have any effect when set to 'on', the
     'mrr' flag must also be 'on'.  Currently, the cost estimation for
     MRR is too pessimistic.  Hence, it is also necessary for
     'mrr_cost_based' to be 'off' for BKA to be used.

     For more information, see bnl-bka-optimization.

   * Block Nested-Loop Flags

        * 'block_nested_loop' (default 'on')

          Controls use of BNL join algorithm.

     For more information, see bnl-bka-optimization.

   * Condition Filtering Flags

        * 'condition_fanout_filter' (default 'on')

          Controls use of condition filtering.

   * Derived Table Merging Flags

        * 'derived_merge' (default 'on')

          Controls merging of derived tables and views into outer query
          block.

     The 'derived_merge' flag controls whether the optimizer attempts to
     merge derived tables and view references into the outer query
     block, assuming that no other rule prevents merging; for example,
     an 'ALGORITHM' directive for a view takes precedence over the
     'derived_merge' setting.  By default, the flag is 'on' to enable
     merging.

     For more information, see derived-table-optimization.

   * Engine Condition Pushdown Flags

        * 'engine_condition_pushdown' (default 'on')

          Controls engine condition pushdown.

     For more information, see condition-pushdown-optimization.

   * Index Condition Pushdown Flags

        * 'index_condition_pushdown' (default 'on')

          Controls index condition pushdown.

     For more information, see
     index-condition-pushdown-optimization.

   * Index Extensions Flags

        * 'use_index_extensions' (default 'on')

          Controls use of index extensions.

     For more information, see index-extensions.

   * Index Merge Flags

        * 'index_merge' (default 'on')

          Controls all Index Merge optimizations.

        * 'index_merge_intersection' (default 'on')

          Controls the Index Merge Intersection Access optimization.

        * 'index_merge_sort_union' (default 'on')

          Controls the Index Merge Sort-Union Access optimization.

        * 'index_merge_union' (default 'on')

          Controls the Index Merge Union Access optimization.

     For more information, see index-merge-optimization.

   * Multi-Range Read Flags

        * 'mrr' (default 'on')

          Controls the Multi-Range Read strategy.

        * 'mrr_cost_based' (default 'on')

          Controls use of cost-based MRR if 'mrr=on'.

     For more information, see mrr-optimization.

   * Semi-Join Flags

        * 'semijoin' (default 'on')

          Controls all semi-join strategies.

        * 'duplicateweedout' (default 'on')

          Controls the semi-join Duplicate Weedout strategy.

        * 'firstmatch' (default 'on')

          Controls the semi-join FirstMatch strategy.

        * 'loosescan' (default 'on')

          Controls the semi-join LooseScan strategy (not to be confused
          with LooseScan for 'GROUP BY').

     The 'semijoin', 'firstmatch', 'loosescan', and 'duplicateweedout'
     flags enable control over semi-join strategies.  The 'semijoin'
     flag controls whether semi-joins are used.  If it is set to 'on',
     the 'firstmatch' and 'loosescan' flags enable finer control over
     the permitted semi-join strategies.

     If the 'duplicateweedout' semi-join strategy is disabled, it is not
     used unless all other applicable strategies are also disabled.

     If 'semijoin' and 'materialization' are both 'on', semi-joins also
     use materialization where applicable.  These flags are 'on' by
     default.

     For more information, see semi-joins.

   * Subquery Materialization Flags

        * 'materialization' (default 'on')

          Controls materialization (including semi-join
          materialization).

        * 'subquery_materialization_cost_based' (default 'on')

          Use cost-based materialization choice.

     The 'materialization' flag controls whether subquery
     materialization is used.  If 'semijoin' and 'materialization' are
     both 'on', semi-joins also use materialization where applicable.
     These flags are 'on' by default.

     The 'subquery_materialization_cost_based' flag enables control over
     the choice between subquery materialization and 'IN'-to-'EXISTS'
     subquery transformation.  If the flag is 'on' (the default), the
     optimizer performs a cost-based choice between subquery
     materialization and 'IN'-to-'EXISTS' subquery transformation if
     either method could be used.  If the flag is 'off', the optimizer
     chooses subquery materialization over 'IN'-to-'EXISTS' subquery
     transformation.

     For more information, see subquery-optimization.

When you assign a value to 'optimizer_switch', flags that are not
mentioned keep their current values.  This makes it possible to enable
or disable specific optimizer behaviors in a single statement without
affecting other behaviors.  The statement does not depend on what other
optimizer flags exist and what their values are.  Suppose that all Index
Merge optimizations are enabled:

     mysql> SELECT @@optimizer_switch\G
     *************************** 1. row ***************************
     @@optimizer_switch: index_merge=on,index_merge_union=on,
                         index_merge_sort_union=on,
                         index_merge_intersection=on,
                         engine_condition_pushdown=on,
                         index_condition_pushdown=on,
                         mrr=on,mrr_cost_based=on,
                         block_nested_loop=on,batched_key_access=off,
                         materialization=on,semijoin=on,loosescan=on,
                         firstmatch=on,
                         subquery_materialization_cost_based=on,
                         use_index_extensions=on,
                         condition_fanout_filter=on

If the server is using the Index Merge Union or Index Merge Sort-Union
access methods for certain queries and you want to check whether the
optimizer will perform better without them, set the variable value like
this:

     mysql> SET optimizer_switch='index_merge_union=off,index_merge_sort_union=off';

     mysql> SELECT @@optimizer_switch\G
     *************************** 1. row ***************************
     @@optimizer_switch: index_merge=on,index_merge_union=off,
                         index_merge_sort_union=off,
                         index_merge_intersection=on,
                         engine_condition_pushdown=on,
                         index_condition_pushdown=on,
                         mrr=on,mrr_cost_based=on,
                         block_nested_loop=on,batched_key_access=off,
                         materialization=on,semijoin=on,loosescan=on,
                         firstmatch=on,
                         subquery_materialization_cost_based=on,
                         use_index_extensions=on,
                         condition_fanout_filter=on

8.9.4 Index Hints
-----------------

Index hints give the optimizer information about how to choose indexes
during query processing.  Index hints, described here, differ from
optimizer hints, described in optimizer-hints.  Index and
optimizer hints may be used separately or together.

Index hints are specified following a table name.  (For the general
syntax for specifying tables in a 'SELECT' statement, see
join.)  The syntax for referring to an individual table,
including index hints, looks like this:

     TBL_NAME [[AS] ALIAS] [INDEX_HINT_LIST]

     INDEX_HINT_LIST:
         INDEX_HINT [INDEX_HINT] ...

     INDEX_HINT:
         USE {INDEX|KEY}
           [FOR {JOIN|ORDER BY|GROUP BY}] ([INDEX_LIST])
       | IGNORE {INDEX|KEY}
           [FOR {JOIN|ORDER BY|GROUP BY}] (INDEX_LIST)
       | FORCE {INDEX|KEY}
           [FOR {JOIN|ORDER BY|GROUP BY}] (INDEX_LIST)

     INDEX_LIST:
         INDEX_NAME [, INDEX_NAME] ...

The 'USE INDEX (INDEX_LIST)' hint tells MySQL to use only one of the
named indexes to find rows in the table.  The alternative syntax 'IGNORE
INDEX (INDEX_LIST)' tells MySQL to not use some particular index or
indexes.  These hints are useful if 'EXPLAIN' shows that
MySQL is using the wrong index from the list of possible indexes.

The 'FORCE INDEX' hint acts like 'USE INDEX (INDEX_LIST)', with the
addition that a table scan is assumed to be _very_ expensive.  In other
words, a table scan is used only if there is no way to use one of the
named indexes to find rows in the table.

Each hint requires index names, not column names.  To refer to a primary
key, use the name 'PRIMARY'.  To see the index names for a table, use
the 'SHOW INDEX' statement or the
'INFORMATION_SCHEMA.STATISTICS' table.

An INDEX_NAME value need not be a full index name.  It can be an
unambiguous prefix of an index name.  If a prefix is ambiguous, an error
occurs.

Examples:

     SELECT * FROM table1 USE INDEX (col1_index,col2_index)
       WHERE col1=1 AND col2=2 AND col3=3;

     SELECT * FROM table1 IGNORE INDEX (col3_index)
       WHERE col1=1 AND col2=2 AND col3=3;

The syntax for index hints has the following characteristics:

   * It is syntactically valid to omit INDEX_LIST for 'USE INDEX', which
     means 'use no indexes.' Omitting INDEX_LIST for 'FORCE INDEX' or
     'IGNORE INDEX' is a syntax error.

   * You can specify the scope of an index hint by adding a 'FOR' clause
     to the hint.  This provides more fine-grained control over
     optimizer selection of an execution plan for various phases of
     query processing.  To affect only the indexes used when MySQL
     decides how to find rows in the table and how to process joins, use
     'FOR JOIN'.  To influence index usage for sorting or grouping rows,
     use 'FOR ORDER BY' or 'FOR GROUP BY'.

   * You can specify multiple index hints:

          SELECT * FROM t1 USE INDEX (i1) IGNORE INDEX FOR ORDER BY (i2) ORDER BY a;

     It is not an error to name the same index in several hints (even
     within the same hint):

          SELECT * FROM t1 USE INDEX (i1) USE INDEX (i1,i1);

     However, it is an error to mix 'USE INDEX' and 'FORCE INDEX' for
     the same table:

          SELECT * FROM t1 USE INDEX FOR JOIN (i1) FORCE INDEX FOR JOIN (i2);

If an index hint includes no 'FOR' clause, the scope of the hint is to
apply to all parts of the statement.  For example, this hint:

     IGNORE INDEX (i1)

is equivalent to this combination of hints:

     IGNORE INDEX FOR JOIN (i1)
     IGNORE INDEX FOR ORDER BY (i1)
     IGNORE INDEX FOR GROUP BY (i1)

In MySQL 5.0, hint scope with no 'FOR' clause was to apply only to row
retrieval.  To cause the server to use this older behavior when no 'FOR'
clause is present, enable the 'old' system variable at server startup.
Take care about enabling this variable in a replication setup.  With
statement-based binary logging, having different modes for the master
and slaves might lead to replication errors.

When index hints are processed, they are collected in a single list by
type ('USE', 'FORCE', 'IGNORE') and by scope ('FOR JOIN', 'FOR ORDER
BY', 'FOR GROUP BY').  For example:

     SELECT * FROM t1
       USE INDEX () IGNORE INDEX (i2) USE INDEX (i1) USE INDEX (i2);

is equivalent to:

     SELECT * FROM t1
        USE INDEX (i1,i2) IGNORE INDEX (i2);

The index hints then are applied for each scope in the following order:

  1. '{USE|FORCE} INDEX' is applied if present.  (If not, the
     optimizer-determined set of indexes is used.)

  2. 'IGNORE INDEX' is applied over the result of the previous step.
     For example, the following two queries are equivalent:

          SELECT * FROM t1 USE INDEX (i1) IGNORE INDEX (i2) USE INDEX (i2);

          SELECT * FROM t1 USE INDEX (i1);

For 'FULLTEXT' searches, index hints work as follows:

   * For natural language mode searches, index hints are silently
     ignored.  For example, 'IGNORE INDEX(i1)' is ignored with no
     warning and the index is still used.

   * For boolean mode searches, index hints with 'FOR ORDER BY' or 'FOR
     GROUP BY' are silently ignored.  Index hints with 'FOR JOIN' or no
     'FOR' modifier are honored.  In contrast to how hints apply for
     non-'FULLTEXT' searches, the hint is used for all phases of query
     execution (finding rows and retrieval, grouping, and ordering).
     This is true even if the hint is given for a non-'FULLTEXT' index.

     For example, the following two queries are equivalent:

          SELECT * FROM t
            USE INDEX (index1)
            IGNORE INDEX (index1) FOR ORDER BY
            IGNORE INDEX (index1) FOR GROUP BY
            WHERE ... IN BOOLEAN MODE ... ;

          SELECT * FROM t
            USE INDEX (index1)
            WHERE ... IN BOOLEAN MODE ... ;

8.9.5 The Optimizer Cost Model
------------------------------

To generate execution plans, the optimizer uses a cost model that is
based on estimates of the cost of various operations that occur during
query execution.  The optimizer has a set of compiled-in default 'cost
constants' available to it to make decisions regarding execution plans.

The optimizer also has a database of cost estimates to use during
execution plan construction.  These estimates are stored in the
'server_cost' and 'engine_cost' tables in the 'mysql' system database
and are configurable at any time.  The intent of these tables is to make
it possible to easily adjust the cost estimates that the optimizer uses
when it attempts to arrive at query execution plans.

   * cost-model-operation

   * cost-model-database

   * cost-model-database-modifications

*Cost Model General Operation*

The configurable optimizer cost model works like this:

   * The server reads the cost model tables into memory at startup and
     uses the in-memory values at runtime.  Any non-'NULL' cost estimate
     specified in the tables takes precedence over the corresponding
     compiled-in default cost constant.  Any 'NULL' estimate indicates
     to the optimizer to use the compiled-in default.

   * At runtime, the server may reread the cost tables.  This occurs
     when a storage engine is dynamically loaded or when a 'FLUSH
     OPTIMIZER_COSTS' statement is executed.

   * Cost tables enable server administrators to easily adjust cost
     estimates by changing entries in the tables.  It is also easy to
     revert to a default by setting an entry's cost to 'NULL'.  The
     optimizer uses the in-memory cost values, so changes to the tables
     should be followed by 'FLUSH OPTIMIZER_COSTS' to take effect.

   * The in-memory cost estimates that are current when a client session
     begins apply throughout that session until it ends.  In particular,
     if the server rereads the cost tables, any changed estimates apply
     only to subsequently started sessions.  Existing sessions are
     unaffected.

   * Cost tables are specific to a given server instance.  The server
     does not replicate cost table changes to replication slaves.

*The Cost Model Database*

The optimizer cost model database consists of two tables in the 'mysql'
system database that contain cost estimate information for operations
that occur during query execution:

   *
     'server_cost': Optimizer cost estimates for general server
     operations

   *
     'engine_cost': Optimizer cost estimates for operations specific to
     particular storage engines

The 'server_cost' table contains these columns:

   * 'cost_name'

     The name of a cost estimate used in the cost model.  The name is
     not case-sensitive.  If the server does not recognize the cost name
     when it reads this table, it writes a warning to the error log.

   * 'cost_value'

     The cost estimate value.  If the value is non-'NULL', the server
     uses it as the cost.  Otherwise, it uses the default estimate (the
     compiled-in value).  DBAs can change a cost estimate by updating
     this column.  If the server finds that the cost value is invalid
     (nonpositive) when it reads this table, it writes a warning to the
     error log.

     To override a default cost estimate (for an entry that specifies
     'NULL'), set the cost to a non-'NULL' value.  To revert to the
     default, set the value to 'NULL'.  Then execute 'FLUSH
     OPTIMIZER_COSTS' to tell the server to reread the cost tables.

   * 'last_update'

     The time of the last row update.

   * 'comment'

     A descriptive comment associated with the cost estimate.  DBAs can
     use this column to provide information about why a cost estimate
     row stores a particular value.

The primary key for the 'server_cost' table is the 'cost_name' column,
so it is not possible to create multiple entries for any cost estimate.

The server recognizes these 'cost_name' values for the 'server_cost'
table:

   * 'disk_temptable_create_cost' (default 40.0),
     'disk_temptable_row_cost' (default 1.0)

     The cost estimates for internally created temporary tables stored
     in a disk-based storage engine (either 'InnoDB' or 'MyISAM').
     Increasing these values increases the cost estimate of using
     internal temporary tables and makes the optimizer prefer query
     plans with less use of them.  For information about such tables,
     see internal-temporary-tables.

     The larger default values for these disk parameters compared to the
     default values for the corresponding memory parameters
     ('memory_temptable_create_cost', 'memory_temptable_row_cost')
     reflects the greater cost of processing disk-based tables.

   * 'key_compare_cost' (default 0.1)

     The cost of comparing record keys.  Increasing this value causes a
     query plan that compares many keys to become more expensive.  For
     example, a query plan that performs a 'filesort' becomes relatively
     more expensive compared to a query plan that avoids sorting by
     using an index.

   * 'memory_temptable_create_cost' (default 2.0),
     'memory_temptable_row_cost' (default 0.2)

     The cost estimates for internally created temporary tables stored
     in the 'MEMORY' storage engine.  Increasing these values increases
     the cost estimate of using internal temporary tables and makes the
     optimizer prefer query plans with less use of them.  For
     information about such tables, see
     internal-temporary-tables.

     The smaller default values for these memory parameters compared to
     the default values for the corresponding disk parameters
     ('disk_temptable_create_cost', 'disk_temptable_row_cost') reflects
     the lesser cost of processing memory-based tables.

   * 'row_evaluate_cost' (default 0.2)

     The cost of evaluating record conditions.  Increasing this value
     causes a query plan that examines many rows to become more
     expensive compared to a query plan that examines fewer rows.  For
     example, a table scan becomes relatively more expensive compared to
     a range scan that reads fewer rows.

The 'engine_cost' table contains these columns:

   * 'engine_name'

     The name of the storage engine to which this cost estimate applies.
     The name is not case-sensitive.  If the value is 'default', it
     applies to all storage engines that have no named entry of their
     own.  If the server does not recognize the engine name when it
     reads this table, it writes a warning to the error log.

   * 'device_type'

     The device type to which this cost estimate applies.  The column is
     intended for specifying different cost estimates for different
     storage device types, such as hard disk drives versus solid state
     drives.  Currently, this information is not used and 0 is the only
     permitted value.

   * 'cost_name'

     Same as in the 'server_cost' table.

   * 'cost_value'

     Same as in the 'server_cost' table.

   * 'last_update'

     Same as in the 'server_cost' table.

   * 'comment'

     Same as in the 'server_cost' table.

The primary key for the 'engine_cost' table is a tuple comprising the
('cost_name', 'engine_name', 'device_type') columns, so it is not
possible to create multiple entries for any combination of values in
those columns.

The server recognizes these 'cost_name' values for the 'engine_cost'
table:

   * 'io_block_read_cost' (default 1.0)

     The cost of reading an index or data block from disk.  Increasing
     this value causes a query plan that reads many disk blocks to
     become more expensive compared to a query plan that reads fewer
     disk blocks.  For example, a table scan becomes relatively more
     expensive compared to a range scan that reads fewer blocks.

   * 'memory_block_read_cost' (default 1.0)

     Similar to 'io_block_read_cost', but represents the cost of reading
     an index or data block from an in-memory database buffer.

If the 'io_block_read_cost' and 'memory_block_read_cost' values differ,
the execution plan may change between two runs of the same query.
Suppose that the cost for memory access is less than the cost for disk
access.  In that case, at server startup before data has been read into
the buffer pool, you may get a different plan than after the query has
been run because then the data will be in memory.

*Making Changes to the Cost Model Database*

For DBAs who wish to change the cost model parameters from their
defaults, try doubling or halving the value and measuring the effect.

Changes to the 'io_block_read_cost' and 'memory_block_read_cost'
parameters are most likely to yield worthwhile results.  These parameter
values enable cost models for data access methods to take into account
the costs of reading information from different sources; that is, the
cost of reading information from disk versus reading information already
in a memory buffer.  For example, all other things being equal, setting
'io_block_read_cost' to a value larger than 'memory_block_read_cost'
causes the optimizer to prefer query plans that read information already
held in memory to plans that must read from disk.

This example shows how to change the default value for
'io_block_read_cost':

     UPDATE mysql.engine_cost
       SET cost_value = 2.0
       WHERE cost_name = 'io_block_read_cost';
     FLUSH OPTIMIZER_COSTS;

This example shows how to change the value of 'io_block_read_cost' only
for the 'InnoDB' storage engine:

     INSERT INTO mysql.engine_cost
       VALUES ('InnoDB', 0, 'io_block_read_cost', 3.0,
       CURRENT_TIMESTAMP, 'Using a slower disk for InnoDB');
     FLUSH OPTIMIZER_COSTS;

8.10 Buffering and Caching
==========================

MySQL uses several strategies that cache information in memory buffers
to increase performance.

8.10.1 InnoDB Buffer Pool Optimization
--------------------------------------

'InnoDB' maintains a storage area called
the buffer pool for caching data and indexes in memory.  Knowing how the
'InnoDB' buffer pool works, and taking advantage of it to keep
frequently accessed data in memory, is an important aspect of MySQL
tuning.

For an explanation of the inner workings of the 'InnoDB' buffer pool, an
overview of its LRU replacement algorithm, and general configuration
information, see innodb-buffer-pool.

For additional 'InnoDB' buffer pool configuration and tuning
information, see these sections:

   * innodb-performance-read_ahead

   * innodb-performance-adaptive_flushing

   * innodb-performance-midpoint_insertion

   * innodb-multiple-buffer-pools

   * innodb-preload-buffer-pool

   * innodb-lru-background-flushing

   * innodb-buffer-pool-resize

8.10.2 The MyISAM Key Cache
---------------------------

To minimize disk I/O, the 'MyISAM' storage engine exploits a strategy
that is used by many database management systems.  It employs a cache
mechanism to keep the most frequently accessed table blocks in memory:

   * For index blocks, a special structure called the _key cache_ (or
     _key buffer_) is maintained.  The structure contains a number of
     block buffers where the most-used index blocks are placed.

   * For data blocks, MySQL uses no special cache.  Instead it relies on
     the native operating system file system cache.

This section first describes the basic operation of the 'MyISAM' key
cache.  Then it discusses features that improve key cache performance
and that enable you to better control cache operation:

   * Multiple sessions can access the cache concurrently.

   * You can set up multiple key caches and assign table indexes to
     specific caches.

To control the size of the key cache, use the 'key_buffer_size' system
variable.  If this variable is set equal to zero, no key cache is used.
The key cache also is not used if the 'key_buffer_size' value is too
small to allocate the minimal number of block buffers (8).

When the key cache is not operational, index files are accessed using
only the native file system buffering provided by the operating system.
(In other words, table index blocks are accessed using the same strategy
as that employed for table data blocks.)

An index block is a contiguous unit of access to the 'MyISAM' index
files.  Usually the size of an index block is equal to the size of nodes
of the index B-tree.  (Indexes are represented on disk using a B-tree
data structure.  Nodes at the bottom of the tree are leaf nodes.  Nodes
above the leaf nodes are nonleaf nodes.)

All block buffers in a key cache structure are the same size.  This size
can be equal to, greater than, or less than the size of a table index
block.  Usually one these two values is a multiple of the other.

When data from any table index block must be accessed, the server first
checks whether it is available in some block buffer of the key cache.
If it is, the server accesses data in the key cache rather than on disk.
That is, it reads from the cache or writes into it rather than reading
from or writing to disk.  Otherwise, the server chooses a cache block
buffer containing a different table index block (or blocks) and replaces
the data there by a copy of required table index block.  As soon as the
new index block is in the cache, the index data can be accessed.

If it happens that a block selected for replacement has been modified,
the block is considered 'dirty.' In this case, prior to being replaced,
its contents are flushed to the table index from which it came.

Usually the server follows an _LRU (Least Recently Used)_ strategy: When
choosing a block for replacement, it selects the least recently used
index block.  To make this choice easier, the key cache module maintains
all used blocks in a special list (_LRU chain_) ordered by time of use.
When a block is accessed, it is the most recently used and is placed at
the end of the list.  When blocks need to be replaced, blocks at the
beginning of the list are the least recently used and become the first
candidates for eviction.

The 'InnoDB' storage engine also uses an LRU algorithm, to manage its
buffer pool.  See innodb-buffer-pool.

8.10.2.1 Shared Key Cache Access
................................

Threads can access key cache buffers simultaneously, subject to the
following conditions:

   * A buffer that is not being updated can be accessed by multiple
     sessions.

   * A buffer that is being updated causes sessions that need to use it
     to wait until the update is complete.

   * Multiple sessions can initiate requests that result in cache block
     replacements, as long as they do not interfere with each other
     (that is, as long as they need different index blocks, and thus
     cause different cache blocks to be replaced).

Shared access to the key cache enables the server to improve throughput
significantly.

8.10.2.2 Multiple Key Caches
............................

Shared access to the key cache improves performance but does not
eliminate contention among sessions entirely.  They still compete for
control structures that manage access to the key cache buffers.  To
reduce key cache access contention further, MySQL also provides multiple
key caches.  This feature enables you to assign different table indexes
to different key caches.

Where there are multiple key caches, the server must know which cache to
use when processing queries for a given 'MyISAM' table.  By default, all
'MyISAM' table indexes are cached in the default key cache.  To assign
table indexes to a specific key cache, use the 'CACHE INDEX'
statement (see cache-index).  For example, the
following statement assigns indexes from the tables 't1', 't2', and 't3'
to the key cache named 'hot_cache':

     mysql> CACHE INDEX t1, t2, t3 IN hot_cache;
     +---------+--------------------+----------+----------+
     | Table   | Op                 | Msg_type | Msg_text |
     +---------+--------------------+----------+----------+
     | test.t1 | assign_to_keycache | status   | OK       |
     | test.t2 | assign_to_keycache | status   | OK       |
     | test.t3 | assign_to_keycache | status   | OK       |
     +---------+--------------------+----------+----------+

The key cache referred to in a 'CACHE INDEX'.
statement can be created by setting its size with a 'SET GLOBAL'
parameter setting statement or by using server startup
options.  For example:

     mysql> SET GLOBAL keycache1.key_buffer_size=128*1024;

To destroy a key cache, set its size to zero:

     mysql> SET GLOBAL keycache1.key_buffer_size=0;

You cannot destroy the default key cache.  Any attempt to do this is
ignored:

     mysql> SET GLOBAL key_buffer_size = 0;

     mysql> SHOW VARIABLES LIKE 'key_buffer_size';
     +-----------------+---------+
     | Variable_name   | Value   |
     +-----------------+---------+
     | key_buffer_size | 8384512 |
     +-----------------+---------+

Key cache variables are structured system variables that have a name and
components.  For 'keycache1.key_buffer_size', 'keycache1' is the cache
variable name and 'key_buffer_size' is the cache component.  See
structured-system-variables, for a description of the syntax used for
referring to structured key cache system variables.

By default, table indexes are assigned to the main (default) key cache
created at the server startup.  When a key cache is destroyed, all
indexes assigned to it are reassigned to the default key cache.

For a busy server, you can use a strategy that involves three key
caches:

   * A 'hot' key cache that takes up 20% of the space allocated for all
     key caches.  Use this for tables that are heavily used for searches
     but that are not updated.

   * A 'cold' key cache that takes up 20% of the space allocated for all
     key caches.  Use this cache for medium-sized, intensively modified
     tables, such as temporary tables.

   * A 'warm' key cache that takes up 60% of the key cache space.
     Employ this as the default key cache, to be used by default for all
     other tables.

One reason the use of three key caches is beneficial is that access to
one key cache structure does not block access to the others.  Statements
that access tables assigned to one cache do not compete with statements
that access tables assigned to another cache.  Performance gains occur
for other reasons as well:

   * The hot cache is used only for retrieval queries, so its contents
     are never modified.  Consequently, whenever an index block needs to
     be pulled in from disk, the contents of the cache block chosen for
     replacement need not be flushed first.

   * For an index assigned to the hot cache, if there are no queries
     requiring an index scan, there is a high probability that the index
     blocks corresponding to nonleaf nodes of the index B-tree remain in
     the cache.

   * An update operation most frequently executed for temporary tables
     is performed much faster when the updated node is in the cache and
     need not be read in from disk first.  If the size of the indexes of
     the temporary tables are comparable with the size of cold key
     cache, the probability is very high that the updated node is in the
     cache.

The 'CACHE INDEX' statement sets up an association
between a table and a key cache, but the association is lost each time
the server restarts.  If you want the association to take effect each
time the server starts, one way to accomplish this is to use an option
file: Include variable settings that configure your key caches, and an
'init-file' option that names a file containing 'CACHE INDEX'
statements to be executed.  For example:

     key_buffer_size = 4G
     hot_cache.key_buffer_size = 2G
     cold_cache.key_buffer_size = 2G
     init_file=/PATH/TO/DATA-DIRECTORY/mysqld_init.sql

The statements in 'mysqld_init.sql' are executed each time the server
starts.  The file should contain one SQL statement per line.  The
following example assigns several tables each to 'hot_cache' and
'cold_cache':

     CACHE INDEX db1.t1, db1.t2, db2.t3 IN hot_cache
     CACHE INDEX db1.t4, db2.t5, db2.t6 IN cold_cache

8.10.2.3 Midpoint Insertion Strategy
....................................

By default, the key cache management system uses a simple LRU strategy
for choosing key cache blocks to be evicted, but it also supports a more
sophisticated method called the _midpoint insertion strategy._

When using the midpoint insertion strategy, the LRU chain is divided
into two parts: a hot sublist and a warm sublist.  The division point
between two parts is not fixed, but the key cache management system
takes care that the warm part is not 'too short,' always containing at
least 'key_cache_division_limit' percent of the key cache blocks.
'key_cache_division_limit' is a component of structured key cache
variables, so its value is a parameter that can be set per cache.

When an index block is read from a table into the key cache, it is
placed at the end of the warm sublist.  After a certain number of hits
(accesses of the block), it is promoted to the hot sublist.  At present,
the number of hits required to promote a block (3) is the same for all
index blocks.

A block promoted into the hot sublist is placed at the end of the list.
The block then circulates within this sublist.  If the block stays at
the beginning of the sublist for a long enough time, it is demoted to
the warm sublist.  This time is determined by the value of the
'key_cache_age_threshold' component of the key cache.

The threshold value prescribes that, for a key cache containing N
blocks, the block at the beginning of the hot sublist not accessed
within the last 'N * key_cache_age_threshold / 100' hits is to be moved
to the beginning of the warm sublist.  It then becomes the first
candidate for eviction, because blocks for replacement always are taken
from the beginning of the warm sublist.

The midpoint insertion strategy enables you to keep more-valued blocks
always in the cache.  If you prefer to use the plain LRU strategy, leave
the 'key_cache_division_limit' value set to its default of 100.

The midpoint insertion strategy helps to improve performance when
execution of a query that requires an index scan effectively pushes out
of the cache all the index blocks corresponding to valuable high-level
B-tree nodes.  To avoid this, you must use a midpoint insertion strategy
with the 'key_cache_division_limit' set to much less than 100.  Then
valuable frequently hit nodes are preserved in the hot sublist during an
index scan operation as well.

8.10.2.4 Index Preloading
.........................

If there are enough blocks in a key cache to hold blocks of an entire
index, or at least the blocks corresponding to its nonleaf nodes, it
makes sense to preload the key cache with index blocks before starting
to use it.  Preloading enables you to put the table index blocks into a
key cache buffer in the most efficient way: by reading the index blocks
from disk sequentially.

Without preloading, the blocks are still placed into the key cache as
needed by queries.  Although the blocks will stay in the cache, because
there are enough buffers for all of them, they are fetched from disk in
random order, and not sequentially.

To preload an index into a cache, use the 'LOAD INDEX INTO CACHE'
statement.  For example, the following statement preloads
nodes (index blocks) of indexes of the tables 't1' and 't2':

     mysql> LOAD INDEX INTO CACHE t1, t2 IGNORE LEAVES;
     +---------+--------------+----------+----------+
     | Table   | Op           | Msg_type | Msg_text |
     +---------+--------------+----------+----------+
     | test.t1 | preload_keys | status   | OK       |
     | test.t2 | preload_keys | status   | OK       |
     +---------+--------------+----------+----------+

The 'IGNORE LEAVES' modifier causes only blocks for the nonleaf nodes of
the index to be preloaded.  Thus, the statement shown preloads all index
blocks from 't1', but only blocks for the nonleaf nodes from 't2'.

If an index has been assigned to a key cache using a 'CACHE INDEX'
statement, preloading places index blocks into that
cache.  Otherwise, the index is loaded into the default key cache.

8.10.2.5 Key Cache Block Size
.............................

It is possible to specify the size of the block buffers for an
individual key cache using the 'key_cache_block_size' variable.  This
permits tuning of the performance of I/O operations for index files.

The best performance for I/O operations is achieved when the size of
read buffers is equal to the size of the native operating system I/O
buffers.  But setting the size of key nodes equal to the size of the I/O
buffer does not always ensure the best overall performance.  When
reading the big leaf nodes, the server pulls in a lot of unnecessary
data, effectively preventing reading other leaf nodes.

To control the size of blocks in the '.MYI' index file of 'MyISAM'
tables, use the '--myisam-block-size' option at server startup.

8.10.2.6 Restructuring a Key Cache
..................................

A key cache can be restructured at any time by updating its parameter
values.  For example:

     mysql> SET GLOBAL cold_cache.key_buffer_size=4*1024*1024;

If you assign to either the 'key_buffer_size' or 'key_cache_block_size'
key cache component a value that differs from the component's current
value, the server destroys the cache's old structure and creates a new
one based on the new values.  If the cache contains any dirty blocks,
the server saves them to disk before destroying and re-creating the
cache.  Restructuring does not occur if you change other key cache
parameters.

When restructuring a key cache, the server first flushes the contents of
any dirty buffers to disk.  After that, the cache contents become
unavailable.  However, restructuring does not block queries that need to
use indexes assigned to the cache.  Instead, the server directly
accesses the table indexes using native file system caching.  File
system caching is not as efficient as using a key cache, so although
queries execute, a slowdown can be anticipated.  After the cache has
been restructured, it becomes available again for caching indexes
assigned to it, and the use of file system caching for the indexes
ceases.

8.10.3 The MySQL Query Cache
----------------------------

*Note*:

The query cache is deprecated as of MySQL 5.7.20, and is removed in
MySQL 8.0.

The query cache stores the text of a 'SELECT' statement
together with the corresponding result that was sent to the client.  If
an identical statement is received later, the server retrieves the
results from the query cache rather than parsing and executing the
statement again.  The query cache is shared among sessions, so a result
set generated by one client can be sent in response to the same query
issued by another client.

The query cache can be useful in an environment where you have tables
that do not change very often and for which the server receives many
identical queries.  This is a typical situation for many Web servers
that generate many dynamic pages based on database content.

The query cache does not return stale data.  When tables are modified,
any relevant entries in the query cache are flushed.

*Note*:

The query cache does not work in an environment where you have multiple
'mysqld' servers updating the same 'MyISAM' tables.

The query cache is used for prepared statements under the conditions
described in query-cache-operation.

*Note*:

The query cache is not supported for partitioned tables, and is
automatically disabled for queries involving partitioned tables.  The
query cache cannot be enabled for such queries.

Some performance data for the query cache follows.  These results were
generated by running the MySQL benchmark suite on a Linux Alpha 2x500MHz
system with 2GB RAM and a 64MB query cache.

   * If all the queries you are performing are simple (such as selecting
     a row from a table with one row), but still differ so that the
     queries cannot be cached, the overhead for having the query cache
     active is 13%.  This could be regarded as the worst case scenario.
     In real life, queries tend to be much more complicated, so the
     overhead normally is significantly lower.

   * Searches for a single row in a single-row table are 238% faster
     with the query cache than without it.  This can be regarded as
     close to the minimum speedup to be expected for a query that is
     cached.

To disable the query cache at server startup, set the 'query_cache_size'
system variable to 0.  By disabling the query cache code, there is no
noticeable overhead.

The query cache offers the potential for substantial performance
improvement, but do not assume that it will do so under all
circumstances.  With some query cache configurations or server
workloads, you might actually see a performance decrease:

   * Be cautious about sizing the query cache excessively large, which
     increases the overhead required to maintain the cache, possibly
     beyond the benefit of enabling it.  Sizes in tens of megabytes are
     usually beneficial.  Sizes in the hundreds of megabytes might not
     be.

   * Server workload has a significant effect on query cache efficiency.
     A query mix consisting almost entirely of a fixed set of
     'SELECT' statements is much more likely to benefit from
     enabling the cache than a mix in which frequent 'INSERT'
     statements cause continual invalidation of results in the
     cache.  In some cases, a workaround is to use the 'SQL_NO_CACHE'
     option to prevent results from even entering the cache for
     'SELECT' statements that use frequently modified tables.
     (See query-cache-in-select.)

To verify that enabling the query cache is beneficial, test the
operation of your MySQL server with the cache enabled and disabled.
Then retest periodically because query cache efficiency may change as
server workload changes.

8.10.3.1 How the Query Cache Operates
.....................................

*Note*:

The query cache is deprecated as of MySQL 5.7.20, and is removed in
MySQL 8.0.

This section describes how the query cache works when it is operational.
See query-cache-configuration, describes how to control whether it
is operational.

Incoming queries are compared to those in the query cache before
parsing, so the following two queries are regarded as different by the
query cache:

     SELECT * FROM TBL_NAME
     Select * from TBL_NAME

Queries must be _exactly_ the same (byte for byte) to be seen as
identical.  In addition, query strings that are identical may be treated
as different for other reasons.  Queries that use different databases,
different protocol versions, or different default character sets are
considered different queries and are cached separately.

The cache is not used for queries of the following types:

   * Queries that are a subquery of an outer query

   * Queries executed within the body of a stored function, trigger, or
     event

Before a query result is fetched from the query cache, MySQL checks
whether the user has 'SELECT' privilege for all databases
and tables involved.  If this is not the case, the cached result is not
used.

If a query result is returned from query cache, the server increments
the 'Qcache_hits' status variable, not 'Com_select'.  See
query-cache-status-and-maintenance.

If a table changes, all cached queries that use the table become invalid
and are removed from the cache.  This includes queries that use 'MERGE'
tables that map to the changed table.  A table can be changed by many
types of statements, such as 'INSERT', 'UPDATE',
see 'DELETE', 'TRUNCATE TABLE',
'ALTER TABLE', 'DROP TABLE', or
'DROP DATABASE'.

The query cache also works within transactions when using 'InnoDB'
tables.

The result from a 'SELECT' query on a view is cached.

The query cache works for 'SELECT SQL_CALC_FOUND_ROWS ...' queries and
stores a value that is returned by a following 'SELECT FOUND_ROWS()'
query.  'FOUND_ROWS()' returns the correct value even if the preceding
query was fetched from the cache because the number of found rows is
also stored in the cache.  The 'SELECT FOUND_ROWS()' query itself cannot
be cached.

Prepared statements that are issued using the binary protocol using
'mysql_stmt_prepare()' and
'mysql_stmt_execute()'. (see
c-api-prepared-statements), are subject to limitations on caching.
Comparison with statements in the query cache is based on the text of
the statement after expansion of '?' parameter markers.  The statement
is compared only with other cached statements that were executed using
the binary protocol.  That is, for query cache purposes, prepared
statements issued using the binary protocol are distinct from prepared
statements issued using the text protocol (see
sql-syntax-prepared-statements).

A query cannot be cached if it uses any of the following functions:

   * 'AES_DECRYPT()'

   * 'AES_ENCRYPT()'

   * 'BENCHMARK()'

   * 'CONNECTION_ID()'

   * 'CONVERT_TZ()'

   * 'CURDATE()'

   * 'CURRENT_DATE()'

   * 'CURRENT_TIME()'

   * 'CURRENT_TIMESTAMP()'

   * 'CURRENT_USER()'

   * 'CURTIME()'

   * 'DATABASE()'

   * 'ENCRYPT()' with one parameter

   * 'FOUND_ROWS()'

   * 'GET_LOCK()'

   * 'IS_FREE_LOCK()'

   * 'IS_USED_LOCK()'

   * 'LAST_INSERT_ID()'

   * 'LOAD_FILE()'

   * 'MASTER_POS_WAIT()'

   * 'NOW()'

   * 'PASSWORD()'

   * 'RAND()'

   * 'RANDOM_BYTES()'

   * 'RELEASE_ALL_LOCKS()'

   * 'RELEASE_LOCK()'

   * 'SLEEP()'

   * 'SYSDATE()'

   * 'UNIX_TIMESTAMP()' with no parameters

   * 'USER()'

   * 'UUID()'

   * 'UUID_SHORT()'

A query also is not cached under these conditions:

   * It refers to user-defined functions (UDFs) or stored functions.

   * It refers to user variables or local stored program variables.

   * It refers to tables in the 'mysql', 'INFORMATION_SCHEMA', or
     'performance_schema' database.

   * It refers to any partitioned tables.

   * It is of any of the following forms:

          SELECT ... LOCK IN SHARE MODE
          SELECT ... FOR UPDATE
          SELECT ... INTO OUTFILE ...
          SELECT ... INTO DUMPFILE ...
          SELECT * FROM ... WHERE autoincrement_col IS NULL

     The last form is not cached because it is used as the ODBC
     workaround for obtaining the last insert ID value.  See the
     Connector/ODBC section of connectors-apis.

     Statements within transactions that use 'SERIALIZABLE' isolation
     level also cannot be cached because they use 'LOCK IN SHARE MODE'
     locking.

   * It uses 'TEMPORARY' tables.

   * It does not use any tables.

   * It generates warnings.

   * The user has a column-level privilege for any of the involved
     tables.

8.10.3.2 Query Cache SELECT Options
...................................

*Note*:

The query cache is deprecated as of MySQL 5.7.20, and is removed in
MySQL 8.0.

Two query cache-related options may be specified in 'SELECT'
statements:

   *
     'SQL_CACHE'

     The query result is cached if it is cacheable and the value of the
     'query_cache_type' system variable is 'ON' or 'DEMAND'.

   *
     'SQL_NO_CACHE'

     The server does not use the query cache.  It neither checks the
     query cache to see whether the result is already cached, nor does
     it cache the query result.

Examples:

     SELECT SQL_CACHE id, name FROM customer;
     SELECT SQL_NO_CACHE id, name FROM customer;

8.10.3.3 Query Cache Configuration
..................................

*Note*:

The query cache is deprecated as of MySQL 5.7.20, and is removed in
MySQL 8.0.

The 'have_query_cache' server system variable indicates whether the
query cache is available:

     mysql> SHOW VARIABLES LIKE 'have_query_cache';
     +------------------+-------+
     | Variable_name    | Value |
     +------------------+-------+
     | have_query_cache | YES   |
     +------------------+-------+

When using a standard MySQL binary, this value is always 'YES', even if
query caching is disabled.

Several other system variables control query cache operation.  These can
be set in an option file or on the command line when starting
'mysqld'.  The query cache system variables all have names that
begin with 'query_cache_'.  They are described briefly in
server-system-variables, with additional configuration information
given here.

To set the size of the query cache, set the 'query_cache_size' system
variable.  Setting it to 0 disables the query cache, as does setting
'query_cache_type=0'.  By default, the query cache is disabled.  This is
achieved using a default size of 1M, with a default for
'query_cache_type' of 0.

To reduce overhead significantly, start the server with
'query_cache_type=0' if you will not be using the query cache.

*Note*:

When using the Windows Configuration Wizard to install or configure
MySQL, the default value for 'query_cache_size' will be configured
automatically for you based on the different configuration types
available.  When using the Windows Configuration Wizard, the query cache
may be enabled (that is, set to a nonzero value) due to the selected
configuration.  The query cache is also controlled by the setting of the
'query_cache_type' variable.  Check the values of these variables as set
in your 'my.ini' file after configuration has taken place.

When you set 'query_cache_size' to a nonzero value, keep in mind that
the query cache needs a minimum size of about 40KB to allocate its
structures.  (The exact size depends on system architecture.)  If you
set the value too small, you'll get a warning, as in this example:

     mysql> SET GLOBAL query_cache_size = 40000;
     Query OK, 0 rows affected, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Warning
        Code: 1282
     Message: Query cache failed to set size 39936;
              new query cache size is 0

     mysql> SET GLOBAL query_cache_size = 41984;
     Query OK, 0 rows affected (0.00 sec)

     mysql> SHOW VARIABLES LIKE 'query_cache_size';
     +------------------+-------+
     | Variable_name    | Value |
     +------------------+-------+
     | query_cache_size | 41984 |
     +------------------+-------+

For the query cache to actually be able to hold any query results, its
size must be set larger:

     mysql> SET GLOBAL query_cache_size = 1000000;
     Query OK, 0 rows affected (0.04 sec)

     mysql> SHOW VARIABLES LIKE 'query_cache_size';
     +------------------+--------+
     | Variable_name    | Value  |
     +------------------+--------+
     | query_cache_size | 999424 |
     +------------------+--------+
     1 row in set (0.00 sec)

The 'query_cache_size' value is aligned to the nearest 1024 byte block.
The value reported may therefore be different from the value that you
assign.

If the query cache size is greater than 0, the 'query_cache_type'
variable influences how it works.  This variable can be set to the
following values:

   * A value of '0' or 'OFF' prevents caching or retrieval of cached
     results.

   * A value of '1' or 'ON' enables caching except of those statements
     that begin with 'SELECT SQL_NO_CACHE'.

   * A value of '2' or 'DEMAND' causes caching of only those statements
     that begin with 'SELECT SQL_CACHE'.

If 'query_cache_size' is 0, you should also set 'query_cache_type'
variable to 0.  In this case, the server does not acquire the query
cache mutex at all, which means that the query cache cannot be enabled
at runtime and there is reduced overhead in query execution.

Setting the 'GLOBAL' 'query_cache_type' value determines query cache
behavior for all clients that connect after the change is made.
Individual clients can control cache behavior for their own connection
by setting the 'SESSION' 'query_cache_type' value.  For example, a
client can disable use of the query cache for its own queries like this:

     mysql> SET SESSION query_cache_type = OFF;

If you set 'query_cache_type' at server startup (rather than at runtime
with a 'SET' statement), only the numeric values
are permitted.

To control the maximum size of individual query results that can be
cached, set the 'query_cache_limit' system variable.  The default value
is 1MB.

Be careful not to set the size of the cache too large.  Due to the need
for threads to lock the cache during updates, you may see lock
contention issues with a very large cache.

*Note*:

You can set the maximum size that can be specified for the query cache
at runtime with the 'SET' statement by using the
'--maximum-query_cache_size=32M' option on the command line or in the
configuration file.

When a query is to be cached, its result (the data sent to the client)
is stored in the query cache during result retrieval.  Therefore the
data usually is not handled in one big chunk.  The query cache allocates
blocks for storing this data on demand, so when one block is filled, a
new block is allocated.  Because memory allocation operation is costly
(timewise), the query cache allocates blocks with a minimum size given
by the 'query_cache_min_res_unit' system variable.  When a query is
executed, the last result block is trimmed to the actual data size so
that unused memory is freed.  Depending on the types of queries your
server executes, you might find it helpful to tune the value of
'query_cache_min_res_unit':

   * The default value of 'query_cache_min_res_unit' is 4KB. This should
     be adequate for most cases.

   * If you have a lot of queries with small results, the default block
     size may lead to memory fragmentation, as indicated by a large
     number of free blocks.  Fragmentation can force the query cache to
     prune (delete) queries from the cache due to lack of memory.  In
     this case, decrease the value of 'query_cache_min_res_unit'.  The
     number of free blocks and queries removed due to pruning are given
     by the values of the 'Qcache_free_blocks' and
     'Qcache_lowmem_prunes' status variables.

   * If most of your queries have large results (check the
     'Qcache_total_blocks' and 'Qcache_queries_in_cache' status
     variables), you can increase performance by increasing
     'query_cache_min_res_unit'.  However, be careful to not make it too
     large (see the previous item).

8.10.3.4 Query Cache Status and Maintenance
...........................................

*Note*:

The query cache is deprecated as of MySQL 5.7.20, and is removed in
MySQL 8.0.

To check whether the query cache is present in your MySQL server, use
the following statement:

     mysql> SHOW VARIABLES LIKE 'have_query_cache';
     +------------------+-------+
     | Variable_name    | Value |
     +------------------+-------+
     | have_query_cache | YES   |
     +------------------+-------+

You can defragment the query cache to better utilize its memory with the
'FLUSH QUERY CACHE' statement.  The statement does not remove any
queries from the cache.

The 'RESET QUERY CACHE' statement removes all query results from the
query cache.  The 'FLUSH TABLES' statement also does this.

To monitor query cache performance, use 'SHOW STATUS'
to view the cache status variables:

     mysql> SHOW STATUS LIKE 'Qcache%';
     +-------------------------+--------+
     | Variable_name           | Value  |
     +-------------------------+--------+
     | Qcache_free_blocks      | 36     |
     | Qcache_free_memory      | 138488 |
     | Qcache_hits             | 79570  |
     | Qcache_inserts          | 27087  |
     | Qcache_lowmem_prunes    | 3114   |
     | Qcache_not_cached       | 22989  |
     | Qcache_queries_in_cache | 415    |
     | Qcache_total_blocks     | 912    |
     +-------------------------+--------+

Descriptions of each of these variables are given in
server-status-variables.  Some uses for them are described here.

The total number of 'SELECT' queries is given by this
formula:

       Com_select
     + Qcache_hits
     + queries with errors found by parser

The 'Com_select' value is given by this formula:

       Qcache_inserts
     + Qcache_not_cached
     + queries with errors found during the column-privileges check

The query cache uses variable-length blocks, so 'Qcache_total_blocks'
and 'Qcache_free_blocks' may indicate query cache memory fragmentation.
After 'FLUSH QUERY CACHE', only a single free block remains.

Every cached query requires a minimum of two blocks (one for the query
text and one or more for the query results).  Also, every table that is
used by a query requires one block.  However, if two or more queries use
the same table, only one table block needs to be allocated.

The information provided by the 'Qcache_lowmem_prunes' status variable
can help you tune the query cache size.  It counts the number of queries
that have been removed from the cache to free up memory for caching new
queries.  The query cache uses a least recently used (LRU) strategy to
decide which queries to remove from the cache.  Tuning information is
given in query-cache-configuration.

8.10.4 Caching of Prepared Statements and Stored Programs
---------------------------------------------------------

For certain statements that a client might execute multiple times during
a session, the server converts the statement to an internal structure
and caches that structure to be used during execution.  Caching enables
the server to perform more efficiently because it avoids the overhead of
reconverting the statement should it be needed again during the session.
Conversion and caching occurs for these statements:

   * Prepared statements, both those processed at the SQL level (using
     the 'PREPARE' statement) and those processed using
     the binary client/server protocol (using the
     'mysql_stmt_prepare()'. C API function).  The
     'max_prepared_stmt_count' system variable controls the total number
     of statements the server caches.  (The sum of the number of
     prepared statements across all sessions.)

   * Stored programs (stored procedures and functions, triggers, and
     events).  In this case, the server converts and caches the entire
     program body.  The 'stored_program_cache' system variable indicates
     the approximate number of stored programs the server caches per
     session.

The server maintains caches for prepared statements and stored programs
on a per-session basis.  Statements cached for one session are not
accessible to other sessions.  When a session ends, the server discards
any statements cached for it.

When the server uses a cached internal statement structure, it must take
care that the structure does not go out of date.  Metadata changes can
occur for an object used by the statement, causing a mismatch between
the current object definition and the definition as represented in the
internal statement structure.  Metadata changes occur for DDL statements
such as those that create, drop, alter, rename, or truncate tables, or
that analyze, optimize, or repair tables.  Table content changes (for
example, with 'INSERT' or 'UPDATE') do not
change metadata, nor do 'SELECT' statements.

Here is an illustration of the problem.  Suppose that a client prepares
this statement:

     PREPARE s1 FROM 'SELECT * FROM t1';

The 'SELECT *' expands in the internal structure to the list of columns
in the table.  If the set of columns in the table is modified with
'ALTER TABLE', the prepared statement goes out of date.  If the server
does not detect this change the next time the client executes 's1', the
prepared statement will return incorrect results.

To avoid problems caused by metadata changes to tables or views referred
to by the prepared statement, the server detects these changes and
automatically reprepares the statement when it is next executed.  That
is, the server reparses the statement and rebuilds the internal
structure.  Reparsing also occurs after referenced tables or views are
flushed from the table definition cache, either implicitly to make room
for new entries in the cache, or explicitly due to 'FLUSH TABLES'.

Similarly, if changes occur to objects used by a stored program, the
server reparses affected statements within the program.

The server also detects metadata changes for objects in expressions.
These might be used in statements specific to stored programs, such as
'DECLARE CURSOR' or flow-control statements such as 'IF',
'CASE', and 'RETURN'.

To avoid reparsing entire stored programs, the server reparses affected
statements or expressions within a program only as needed.  Examples:

   * Suppose that metadata for a table or view is changed.  Reparsing
     occurs for a 'SELECT *' within the program that accesses the table
     or view, but not for a 'SELECT *' that does not access the table or
     view.

   * When a statement is affected, the server reparses it only partially
     if possible.  Consider this 'CASE' statement:

          CASE CASE_EXPR
            WHEN WHEN_EXPR1 ...
            WHEN WHEN_EXPR2 ...
            WHEN WHEN_EXPR3 ...
            ...
          END CASE

     If a metadata change affects only 'WHEN WHEN_EXPR3', that
     expression is reparsed.  CASE_EXPR and the other 'WHEN' expressions
     are not reparsed.

Reparsing uses the default database and SQL mode that were in effect for
the original conversion to internal form.

The server attempts reparsing up to three times.  An error occurs if all
attempts fail.

Reparsing is automatic, but to the extent that it occurs, diminishes
prepared statement and stored program performance.

For prepared statements, the 'Com_stmt_reprepare' status variable tracks
the number of repreparations.

8.11 Optimizing Locking Operations
==================================

MySQL manages contention for table contents using locking:

   * Internal locking is performed within the MySQL server itself to
     manage contention for table contents by multiple threads.  This
     type of locking is internal because it is performed entirely by the
     server and involves no other programs.  See
     internal-locking.

   * External locking occurs when the server and other programs lock
     'MyISAM' table files to coordinate
     among themselves which program can access the tables at which time.
     See external-locking.

8.11.1 Internal Locking Methods
-------------------------------

This section discusses internal locking; that is, locking performed
within the MySQL server itself to manage contention for table contents
by multiple sessions.  This type of locking is internal because it is
performed entirely by the server and involves no other programs.  For
locking performed on MySQL files by other programs, see
external-locking.

   * internal-row-level-locking

   * internal-table-level-locking

   * internal-locking-choices

*Row-Level Locking*

MySQL uses row-level locking for 'InnoDB' tables to support simultaneous
write access by multiple sessions, making them suitable for multi-user,
highly concurrent, and OLTP applications.

To avoid deadlocks when performing multiple concurrent write operations
on a single 'InnoDB' table, acquire necessary locks at the start of the
transaction by issuing a 'SELECT ... FOR UPDATE' statement for each
group of rows expected to be modified, even if the data change
statements come later in the transaction.  If transactions modify or
lock more than one table, issue the applicable statements in the same
order within each transaction.  Deadlocks affect performance rather than
representing a serious error, because 'InnoDB' automatically detects
deadlock conditions and rolls back one of the affected transactions.

On high concurrency systems, deadlock detection can cause a slowdown
when numerous threads wait for the same lock.  At times, it may be more
efficient to disable deadlock detection and rely on the
'innodb_lock_wait_timeout' setting for transaction rollback when a
deadlock occurs.  Deadlock detection can be disabled using the
'innodb_deadlock_detect' configuration option.

Advantages of row-level locking:

   * Fewer lock conflicts when different sessions access different rows.

   * Fewer changes for rollbacks.

   * Possible to lock a single row for a long time.

*Table-Level Locking*

MySQL uses table-level locking for 'MyISAM', 'MEMORY', and 'MERGE'
tables, permitting only one session to update those tables at a time.
This locking level makes these storage engines more suitable for
read-only, read-mostly, or single-user applications.

These storage engines avoid deadlocks by always requesting all needed
locks at once at the beginning of a query and always locking the tables
in the same order.  The tradeoff is that this strategy reduces
concurrency; other sessions that want to modify the table must wait
until the current data change statement finishes.

Advantages of table-level locking:

   * Relatively little memory required (row locking requires memory per
     row or group of rows locked)

   * Fast when used on a large part of the table because only a single
     lock is involved.

   * Fast if you often do 'GROUP BY' operations on a large part of the
     data or must scan the entire table frequently.

MySQL grants table write locks as follows:

  1. If there are no locks on the table, put a write lock on it.

  2. Otherwise, put the lock request in the write lock queue.

MySQL grants table read locks as follows:

  1. If there are no write locks on the table, put a read lock on it.

  2. Otherwise, put the lock request in the read lock queue.

Table updates are given higher priority than table retrievals.
Therefore, when a lock is released, the lock is made available to the
requests in the write lock queue and then to the requests in the read
lock queue.  This ensures that updates to a table are not 'starved' even
when there is heavy 'SELECT' activity for the table.
However, if there are many updates for a table, see 'SELECT'.
statements wait until there are no more updates.

For information on altering the priority of reads and writes, see
table-locking.

You can analyze the table lock contention on your system by checking the
'Table_locks_immediate' and 'Table_locks_waited' status variables, which
indicate the number of times that requests for table locks could be
granted immediately and the number that had to wait, respectively:

     mysql> SHOW STATUS LIKE 'Table%';
     +-----------------------+---------+
     | Variable_name         | Value   |
     +-----------------------+---------+
     | Table_locks_immediate | 1151552 |
     | Table_locks_waited    | 15324   |
     +-----------------------+---------+

The Performance Schema lock tables also provide locking information.
See performance-schema-lock-tables.

The 'MyISAM' storage engine supports concurrent inserts to reduce
contention between readers and writers for a given table: If a 'MyISAM'
table has no free blocks in the middle of the data file, rows are always
inserted at the end of the data file.  In this case, you can freely mix
concurrent 'INSERT' and 'SELECT'.
statements for a 'MyISAM' table without locks.  That is, you can insert
rows into a 'MyISAM' table at the same time other clients are reading
from it.  Holes can result from rows having been deleted from or updated
in the middle of the table.  If there are holes, concurrent inserts are
disabled but are enabled again automatically when all holes have been
filled with new data.  To control this behavior, use the
'concurrent_insert' system variable.  See concurrent-inserts.

If you acquire a table lock explicitly with 'LOCK TABLES',
you can request a 'READ LOCAL' lock rather than a 'READ'
lock to enable other sessions to perform concurrent inserts while you
have the table locked.

To perform many 'INSERT' and 'SELECT'.
operations on a table 't1' when concurrent inserts are not possible, you
can insert rows into a temporary table 'temp_t1' and update the real
table with the rows from the temporary table:

     mysql> LOCK TABLES t1 WRITE, temp_t1 WRITE;
     mysql> INSERT INTO t1 SELECT * FROM temp_t1;
     mysql> DELETE FROM temp_t1;
     mysql> UNLOCK TABLES;

*Choosing the Type of Locking*

Generally, table locks are superior to row-level locks in the following
cases:

   * Most statements for the table are reads.

   * Statements for the table are a mix of reads and writes, where
     writes are updates or deletes for a single row that can be fetched
     with one key read:

          UPDATE TBL_NAME SET COLUMN=VALUE WHERE UNIQUE_KEY_COL=KEY_VALUE;
          DELETE FROM TBL_NAME WHERE UNIQUE_KEY_COL=KEY_VALUE;

   * 'SELECT' combined with concurrent 'INSERT'
     statements, and very few 'UPDATE' or
     'DELETE' statements.

   * Many scans or 'GROUP BY' operations on the entire table without any
     writers.

With higher-level locks, you can more easily tune applications by
supporting locks of different types, because the lock overhead is less
than for row-level locks.

Options other than row-level locking:

   * Versioning (such as that used in MySQL for concurrent inserts)
     where it is possible to have one writer at the same time as many
     readers.  This means that the database or table supports different
     views for the data depending on when access begins.  Other common
     terms for this are 'time travel,' 'copy on write,' or 'copy on
     demand.'

   * Copy on demand is in many cases superior to row-level locking.
     However, in the worst case, it can use much more memory than using
     normal locks.

   * Instead of using row-level locks, you can employ application-level
     locks, such as those provided by 'GET_LOCK()' and 'RELEASE_LOCK()'
     in MySQL. These are advisory locks, so they work only with
     applications that cooperate with each other.  See
     miscellaneous-functions.

8.11.2 Table Locking Issues
---------------------------

'InnoDB' tables use row-level locking so that multiple sessions and
applications can read from and write to the same table simultaneously,
without making each other wait or producing inconsistent results.  For
this storage engine, avoid using the 'LOCK TABLES'.
statement, because it does not offer any extra protection, but instead
reduces concurrency.  The automatic row-level locking makes these tables
suitable for your busiest databases with your most important data, while
also simplifying application logic since you do not need to lock and
unlock tables.  Consequently, the 'InnoDB' storage engine is the default
in MySQL.

MySQL uses table locking (instead of page, row, or column locking) for
all storage engines except 'InnoDB'.  The locking operations themselves
do not have much overhead.  But because only one session can write to a
table at any one time, for best performance with these other storage
engines, use them primarily for tables that are queried often and rarely
inserted into or updated.

   * table-locking-innodb

   * table-locking-workarounds

*Performance Considerations Favoring InnoDB*

When choosing whether to create a table using 'InnoDB' or a different
storage engine, keep in mind the following disadvantages of table
locking:

   * Table locking enables many sessions to read from a table at the
     same time, but if a session wants to write to a table, it must
     first get exclusive access, meaning it might have to wait for other
     sessions to finish with the table first.  During the update, all
     other sessions that want to access this particular table must wait
     until the update is done.

   * Table locking causes problems when a session is waiting because the
     disk is full and free space needs to become available before the
     session can proceed.  In this case, all sessions that want to
     access the problem table are also put in a waiting state until more
     disk space is made available.

   * A 'SELECT' statement that takes a long time to run
     prevents other sessions from updating the table in the meantime,
     making the other sessions appear slow or unresponsive.  While a
     session is waiting to get exclusive access to the table for
     updates, other sessions that issue 'SELECT'.
     statements will queue up behind it, reducing concurrency even for
     read-only sessions.

*Workarounds for Locking Performance Issues*

The following items describe some ways to avoid or reduce contention
caused by table locking:

   * Consider switching the table to the 'InnoDB' storage engine, either
     using 'CREATE TABLE ... ENGINE=INNODB' during setup, or using
     'ALTER TABLE ... ENGINE=INNODB' for an existing table.  See
     innodb-storage-engine for more details about this storage engine.

   * Optimize 'SELECT' statements to run faster so that
     they lock tables for a shorter time.  You might have to create some
     summary tables to do this.

   * Start 'mysqld' with '--low-priority-updates'.  For
     storage engines that use only table-level locking (such as
     'MyISAM', 'MEMORY', and 'MERGE'), this gives all statements that
     update (modify) a table lower priority than 'SELECT'.
     statements.  In this case, the second 'SELECT'.
     statement in the preceding scenario would execute before the
     'UPDATE' statement, and would not wait for the first
     'SELECT' to finish.

   * To specify that all updates issued in a specific connection should
     be done with low priority, set the 'low_priority_updates' server
     system variable equal to 1.

   * To give a specific 'INSERT', 'UPDATE',
     or 'DELETE' statement lower priority, use the
     'LOW_PRIORITY' attribute.

   * To give a specific 'SELECT' statement higher
     priority, use the 'HIGH_PRIORITY' attribute.  See select.

   * Start 'mysqld' with a low value for the
     'max_write_lock_count' system variable to force MySQL to
     temporarily elevate the priority of all 'SELECT'.
     statements that are waiting for a table after a specific number of
     inserts to the table occur.  This permits 'READ' locks after a
     certain number of 'WRITE' locks.

   * If you have problems with 'INSERT' combined with
     'SELECT', consider switching to 'MyISAM' tables,
     which support concurrent 'SELECT' and
     'INSERT' statements.  (See concurrent-inserts.)

   * If you have problems with mixed 'SELECT' and
     'DELETE' statements, the 'LIMIT' option to 'DELETE'
     may help.  See delete.

   * Using 'SQL_BUFFER_RESULT' with 'SELECT' statements
     can help to make the duration of table locks shorter.  See
     select.

   * Splitting table contents into separate tables may help, by allowing
     queries to run against columns in one table, while updates are
     confined to columns in a different table.

   * You could change the locking code in 'mysys/thr_lock.c' to use a
     single queue.  In this case, write locks and read locks would have
     the same priority, which might help some applications.

8.11.3 Concurrent Inserts
-------------------------

The 'MyISAM' storage engine supports concurrent inserts to reduce
contention between readers and writers for a given table: If a 'MyISAM'
table has no holes in the data file (deleted rows in the middle), an
'INSERT' statement can be executed to add rows to the end
of the table at the same time that 'SELECT' statements
are reading rows from the table.  If there are multiple 'INSERT'
statements, they are queued and performed in sequence,
concurrently with the 'SELECT' statements.  The results
of a concurrent 'INSERT' may not be visible immediately.

The 'concurrent_insert' system variable can be set to modify the
concurrent-insert processing.  By default, the variable is set to 'AUTO'
(or 1) and concurrent inserts are handled as just described.  If
'concurrent_insert' is set to 'NEVER' (or 0), concurrent inserts are
disabled.  If the variable is set to 'ALWAYS' (or 2), concurrent inserts
at the end of the table are permitted even for tables that have deleted
rows.  See also the description of the 'concurrent_insert' system
variable.

If you are using the binary log, concurrent inserts are converted to
normal inserts for 'CREATE ... SELECT' or 'INSERT ... SELECT'
statements.  This is done to ensure that you can
re-create an exact copy of your tables by applying the log during a
backup operation.  See binary-log.  In addition, for those
statements a read lock is placed on the selected-from table such that
inserts into that table are blocked.  The effect is that concurrent
inserts for that table must wait as well.

With 'LOAD DATA INFILE', if you specify 'CONCURRENT'
with a 'MyISAM' table that satisfies the condition for concurrent
inserts (that is, it contains no free blocks in the middle), other
sessions can retrieve data from the table while 'LOAD DATA'
is executing.  Use of the 'CONCURRENT' option affects the
performance of 'LOAD DATA' a bit, even if no other
session is using the table at the same time.

If you specify 'HIGH_PRIORITY', it overrides the effect of the
'--low-priority-updates' option if the server was started with that
option.  It also causes concurrent inserts not to be used.

For 'LOCK TABLE', the difference between 'READ LOCAL'
and 'READ' is that 'READ LOCAL' permits nonconflicting 'INSERT'
statements (concurrent inserts) to execute while the lock is
held.  However, this cannot be used if you are going to manipulate the
database using processes external to the server while you hold the lock.

8.11.4 Metadata Locking
-----------------------

MySQL uses metadata locking to manage concurrent access to database
objects and to ensure data consistency.  Metadata locking applies not
just to tables, but also to schemas, stored programs (procedures,
functions, triggers, and scheduled events), and tablespaces.

Metadata locking does involve some overhead, which increases as query
volume increases.  Metadata contention increases the more that multiple
queries attempt to access the same objects.

Metadata locking is not a replacement for the table definition cache,
and its mutexes and locks differ from the 'LOCK_open' mutex.  The
following discussion provides some information about how metadata
locking works.

To ensure transaction serializability, the server must not permit one
session to perform a data definition language (DDL) statement on a table
that is used in an uncompleted explicitly or implicitly started
transaction in another session.  The server achieves this by acquiring
metadata locks on tables used within a transaction and deferring release
of those locks until the transaction ends.  A metadata lock on a table
prevents changes to the table's structure.  This locking approach has
the implication that a table that is being used by a transaction within
one session cannot be used in DDL statements by other sessions until the
transaction ends.

This principle applies not only to transactional tables, but also to
nontransactional tables.  Suppose that a session begins a transaction
that uses transactional table 't' and nontransactional table 'nt' as
follows:

     START TRANSACTION;
     SELECT * FROM t;
     SELECT * FROM nt;

The server holds metadata locks on both 't' and 'nt' until the
transaction ends.  If another session attempts a DDL or write lock
operation on either table, it blocks until metadata lock release at
transaction end.  For example, a second session blocks if it attempts
any of these operations:

     DROP TABLE t;
     ALTER TABLE t ...;
     DROP TABLE nt;
     ALTER TABLE nt ...;
     LOCK TABLE t ... WRITE;

The same behavior applies for The 'LOCK TABLES ... READ'.
That is, explicitly or implicitly started transactions
that update any table (transactional or nontransactional) will block and
be blocked by 'LOCK TABLES ... READ' for that table.

If the server acquires metadata locks for a statement that is
syntactically valid but fails during execution, it does not release the
locks early.  Lock release is still deferred to the end of the
transaction because the failed statement is written to the binary log
and the locks protect log consistency.

In autocommit mode, each statement is in effect a complete transaction,
so metadata locks acquired for the statement are held only to the end of
the statement.

Metadata locks acquired during a 'PREPARE' statement are
released once the statement has been prepared, even if preparation
occurs within a multiple-statement transaction.

8.11.5 External Locking
-----------------------

External locking is the use of file system locking to manage contention
for 'MyISAM' database tables by multiple
processes.  External locking is used in situations where a single
process such as the MySQL server cannot be assumed to be the only
process that requires access to tables.  Here are some examples:

   * If you run multiple servers that use the same database directory
     (not recommended), each server must have external locking enabled.

   * If you use 'myisamchk' to perform table
     maintenance operations on 'MyISAM'.
     tables, you must either ensure that the server is not running, or
     that the server has external locking enabled so that it locks table
     files as necessary to coordinate with 'myisamchk'.
     for access to the tables.  The same is true for use of
     'myisampack' to pack 'MyISAM'
     tables.

     If the server is run with external locking enabled, you can use
     'myisamchk' at any time for read operations such
     a checking tables.  In this case, if the server tries to update a
     table that 'myisamchk' is using, the server will
     wait for 'myisamchk' to finish before it
     continues.

     If you use 'myisamchk' for write operations such
     as repairing or optimizing tables, or if you use
     'myisampack' to pack tables, you _must_ always ensure
     that the 'mysqld' server is not using the table.  If
     you do not stop 'mysqld', at least do a
     'mysqladmin flush-tables' before you run
     'myisamchk'.  Your tables _may become corrupted_ if the
     server and 'myisamchk' access the tables
     simultaneously.

With external locking in effect, each process that requires access to a
table acquires a file system lock for the table files before proceeding
to access the table.  If all necessary locks cannot be acquired, the
process is blocked from accessing the table until the locks can be
obtained (after the process that currently holds the locks releases
them).

External locking affects server performance because the server must
sometimes wait for other processes before it can access tables.

External locking is unnecessary if you run a single server to access a
given data directory (which is the usual case) and if no other programs
such as 'myisamchk' need to modify tables while the
server is running.  If you only _read_ tables with other programs,
external locking is not required, although 'myisamchk'.
might report warnings if the server changes tables while
'myisamchk' is reading them.

With external locking disabled, to use 'myisamchk', you
must either stop the server while 'myisamchk' executes
or else lock and flush the tables before running 'myisamchk'.
(See system-optimization.)  To avoid this
requirement, use the 'CHECK TABLE' and 'REPAIR TABLE'
statements to check and repair 'MyISAM'
tables.

For 'mysqld', external locking is controlled by the value
of the 'skip_external_locking' system variable.  When this variable is
enabled, external locking is disabled, and vice versa.  External locking
is disabled by default.

Use of external locking can be controlled at server startup by using the
'--external-locking' or '--skip-external-locking' option.

If you do use external locking option to enable updates to
'MyISAM' tables from many MySQL processes, you
must ensure that the following conditions are satisfied:

   * Do not use the query cache for queries that use tables that are
     updated by another process.

   * Do not start the server with the '--delay-key-write=ALL' option or
     use the 'DELAY_KEY_WRITE=1' table option for any shared tables.
     Otherwise, index corruption can occur.

The easiest way to satisfy these conditions is to always use
'--external-locking' together with '--delay-key-write=OFF' and
'--query-cache-size=0'.  (This is not done by default because in many
setups it is useful to have a mixture of the preceding options.)

8.12 Optimizing the MySQL Server
================================

This section discusses optimization techniques for the database server,
primarily dealing with system configuration rather than tuning SQL
statements.  The information in this section is appropriate for DBAs who
want to ensure performance and scalability across the servers they
manage; for developers constructing installation scripts that include
setting up the database; and people running MySQL themselves for
development, testing, and so on who want to maximize their own
productivity.

8.12.1 System Factors
---------------------

Some system-level factors can affect performance in a major way:

   * If you have enough RAM, you could remove all swap devices.  Some
     operating systems use a swap device in some contexts even if you
     have free memory.

   * Avoid external locking for 'MyISAM'.
     tables.  The default is for external locking to be disabled.  The
     '--external-locking' and '--skip-external-locking' options
     explicitly enable and disable external locking.

     Disabling external locking does not affect MySQL's functionality as
     long as you run only one server.  Just remember to take down the
     server (or lock and flush the relevant tables) before you run
     'myisamchk'.  On some systems it is mandatory to disable
     external locking because it does not work, anyway.

     The only case in which you cannot disable external locking is when
     you run multiple MySQL _servers_ (not clients) on the same data, or
     if you run 'myisamchk' to check (not repair) a
     table without telling the server to flush and lock the tables
     first.  Note that using multiple MySQL servers to access the same
     data concurrently is generally _not_ recommended, except when using
     NDB Cluster.

     The 'LOCK TABLES' and 'UNLOCK TABLES'
     statements use internal locking, so you can use them
     even if external locking is disabled.

8.12.2 Optimizing Disk I/O
--------------------------

     This section describes ways to configure storage devices when you
     can devote more and faster storage hardware to the database server.
     For information about optimizing an 'InnoDB' configuration to
     improve I/O performance, see optimizing-innodb-diskio.

   * Disk seeks are a huge performance bottleneck.  This problem becomes
     more apparent when the amount of data starts to grow so large that
     effective caching becomes impossible.  For large databases where
     you access data more or less randomly, you can be sure that you
     need at least one disk seek to read and a couple of disk seeks to
     write things.  To minimize this problem, use disks with low seek
     times.

   * Increase the number of available disk spindles (and thereby reduce
     the seek overhead) by either symlinking files to different disks or
     striping the disks:

        * Using symbolic links

          This means that, for 'MyISAM' tables, you symlink the index
          file and data files from their usual location in the data
          directory to another disk (that may also be striped).  This
          makes both the seek and read times better, assuming that the
          disk is not used for other purposes as well.  See
          symbolic-links.

          Symbolic links are not supported for use with 'InnoDB' tables.
          However, it is possible to place 'InnoDB' data and log files
          on different physical disks.  For more information, see
          optimizing-innodb-diskio.

        *
          Striping

          Striping means that you have many disks and put the first
          block on the first disk, the second block on the second disk,
          and the N-th block on the ('N MOD NUMBER_OF_DISKS') disk, and
          so on.  This means if your normal data size is less than the
          stripe size (or perfectly aligned), you get much better
          performance.  Striping is very dependent on the operating
          system and the stripe size, so benchmark your application with
          different stripe sizes.  See custom-benchmarks.

          The speed difference for striping is _very_ dependent on the
          parameters.  Depending on how you set the striping parameters
          and number of disks, you may get differences measured in
          orders of magnitude.  You have to choose to optimize for
          random or sequential access.

   * For reliability, you may want to use RAID 0+1 (striping plus
     mirroring), but in this case, you need 2 x N drives to hold N
     drives of data.  This is probably the best option if you have the
     money for it.  However, you may also have to invest in some
     volume-management software to handle it efficiently.

   * A good option is to vary the RAID level according to how critical a
     type of data is.  For example, store semi-important data that can
     be regenerated on a RAID 0 disk, but store really important data
     such as host information and logs on a RAID 0+1 or RAID N disk.
     RAID N can be a problem if you have many writes, due to the time
     required to update the parity bits.

   * You can also set the parameters for the file system that the
     database uses:

     If you do not need to know when files were last accessed (which is
     not really useful on a database server), you can mount your file
     systems with the '-o noatime' option.  That skips updates to the
     last access time in inodes on the file system, which avoids some
     disk seeks.

     On many operating systems, you can set a file system to be updated
     asynchronously by mounting it with the '-o async' option.  If your
     computer is reasonably stable, this should give you better
     performance without sacrificing too much reliability.  (This flag
     is on by default on Linux.)

*Using NFS with MySQL*

Caution is advised when considering using NFS with MySQL. Potential
issues, which vary by operating system and NFS version, include:

   * MySQL data and log files placed on NFS volumes becoming locked and
     unavailable for use.  Locking issues may occur in cases where
     multiple instances of MySQL access the same data directory or where
     MySQL is shut down improperly, due to a power outage, for example.
     NFS version 4 addresses underlying locking issues with the
     introduction of advisory and lease-based locking.  However, sharing
     a data directory among MySQL instances is not recommended.

   * Data inconsistencies introduced due to messages received out of
     order or lost network traffic.  To avoid this issue, use TCP with
     'hard' and 'intr' mount options.

   * Maximum file size limitations.  NFS Version 2 clients can only
     access the lowest 2GB of a file (signed 32 bit offset).  NFS
     Version 3 clients support larger files (up to 64 bit offsets).  The
     maximum supported file size also depends on the local file system
     of the NFS server.

Using NFS within a professional SAN environment or other storage system
tends to offer greater reliability than using NFS outside of such an
environment.  However, NFS within a SAN environment may be slower than
directly attached or bus-attached non-rotational storage.

If you choose to use NFS, NFS Version 4 or later is recommended, as is
testing your NFS setup thoroughly before deploying into a production
environment.

8.12.3 Using Symbolic Links
---------------------------

You can move databases or tables from the database directory to other
locations and replace them with symbolic links to the new locations.
You might want to do this, for example, to move a database to a file
system with more free space or increase the speed of your system by
spreading your tables to different disks.

For 'InnoDB' tables, use the 'DATA DIRECTORY' clause on the
'CREATE TABLE' statement instead of symbolic links, as
explained in tablespace-placing.  This new feature is a
supported, cross-platform technique.

The recommended way to do this is to symlink entire database directories
to a different disk.  Symlink 'MyISAM' tables only as a last resort.

To determine the location of your data directory, use this statement:

     SHOW VARIABLES LIKE 'datadir';

8.12.3.1 Using Symbolic Links for Databases on Unix
...................................................

On Unix, the way to symlink a database is first to create a directory on
some disk where you have free space and then to create a soft link to it
from the MySQL data directory.

     shell> mkdir /dr1/databases/test
     shell> ln -s /dr1/databases/test /PATH/TO/DATADIR

MySQL does not support linking one directory to multiple databases.
Replacing a database directory with a symbolic link works as long as you
do not make a symbolic link between databases.  Suppose that you have a
database 'db1' under the MySQL data directory, and then make a symlink
'db2' that points to 'db1':

     shell> cd /PATH/TO/DATADIR
     shell> ln -s db1 db2

The result is that, for any table 'tbl_a' in 'db1', there also appears
to be a table 'tbl_a' in 'db2'.  If one client updates 'db1.tbl_a' and
another client updates 'db2.tbl_a', problems are likely to occur.

8.12.3.2 Using Symbolic Links for MyISAM Tables on Unix
.......................................................

Symlinks are fully supported only for 'MyISAM' tables.  For files used
by tables for other storage engines, you may get strange problems if you
try to use symbolic links.  For 'InnoDB' tables, use the alternative
technique explained in tablespace-placing instead.

Do not symlink tables on systems that do not have a fully operational
'realpath()' call.  (Linux and Solaris support 'realpath()').  To
determine whether your system supports symbolic links, check the value
of the 'have_symlink' system variable using this statement:

     SHOW VARIABLES LIKE 'have_symlink';

The handling of symbolic links for 'MyISAM' tables works as follows:

   * In the data directory, you always have the table format ('.frm')
     file, the data ('.MYD') file, and the index ('.MYI') file.  The
     data file and index file can be moved elsewhere and replaced in the
     data directory by symlinks.  The format file cannot.

   * You can symlink the data file and the index file independently to
     different directories.

   * To instruct a running MySQL server to perform the symlinking, use
     the 'DATA DIRECTORY' and 'INDEX DIRECTORY' options to 'CREATE TABLE'.
     See create-table.  Alternatively, if
     'mysqld' is not running, symlinking can be
     accomplished manually using 'ln -s' from the command line.

     *Note*:

     The path used with either or both of the 'DATA DIRECTORY' and
     'INDEX DIRECTORY' options may not include the MySQL 'data'
     directory.  (Bug #32167)

   * 'myisamchk' does not replace a symlink with the
     data file or index file.  It works directly on the file to which
     the symlink points.  Any temporary files are created in the
     directory where the data file or index file is located.  The same
     is true for the 'ALTER TABLE', 'OPTIMIZE TABLE',
     and 'REPAIR TABLE'.
     statements.

   * *Note*:

     When you drop a table that is using symlinks, _both the symlink and
     the file to which the symlink points are dropped_.  This is an
     extremely good reason _not_ to run 'mysqld' as the
     system 'root' or permit system users to have write access to MySQL
     database directories.

   * If you rename a table with 'ALTER TABLE ... RENAME'
     or 'RENAME TABLE' and you do not
     move the table to another database, the symlinks in the database
     directory are renamed to the new names and the data file and index
     file are renamed accordingly.

   * If you use 'ALTER TABLE ... RENAME' or
     'RENAME TABLE' to move a table to another database,
     the table is moved to the other database directory.  If the table
     name changed, the symlinks in the new database directory are
     renamed to the new names and the data file and index file are
     renamed accordingly.

   * If you are not using symlinks, start 'mysqld' with
     the '--skip-symbolic-links' option to ensure that no one can use
     'mysqld' to drop or rename a file outside of the
     data directory.

These table symlink operations are not supported:

   * 'ALTER TABLE' ignores the 'DATA DIRECTORY' and
     'INDEX DIRECTORY' table options.

   * As indicated previously, only the data and index files can be
     symbolic links.  The '.frm' file must _never_ be a symbolic link.
     Attempting to do this (for example, to make one table name a
     synonym for another) produces incorrect results.  Suppose that you
     have a database 'db1' under the MySQL data directory, a table
     'tbl1' in this database, and in the 'db1' directory you make a
     symlink 'tbl2' that points to 'tbl1':

          shell> cd /PATH/TO/DATADIR/db1
          shell> ln -s tbl1.frm tbl2.frm
          shell> ln -s tbl1.MYD tbl2.MYD
          shell> ln -s tbl1.MYI tbl2.MYI

     Problems result if one thread reads 'db1.tbl1' and another thread
     updates 'db1.tbl2':

        * The query cache is 'fooled' (it has no way of knowing that
          'tbl1' has not been updated, so it returns outdated results).

        * 'ALTER' statements on 'tbl2' fail.

8.12.3.3 Using Symbolic Links for Databases on Windows
......................................................

On Windows, symbolic links can be used for database directories.  This
enables you to put a database directory at a different location (for
example, on a different disk) by setting up a symbolic link to it.  Use
of database symlinks on Windows is similar to their use on Unix,
although the procedure for setting up the link differs.

Suppose that you want to place the database directory for a database
named 'mydb' at 'D:\data\mydb'.  To do this, create a symbolic link in
the MySQL data directory that points to 'D:\data\mydb'.  However, before
creating the symbolic link, make sure that the 'D:\data\mydb' directory
exists by creating it if necessary.  If you already have a database
directory named 'mydb' in the data directory, move it to 'D:\data'.
Otherwise, the symbolic link will be ineffective.  To avoid problems,
make sure that the server is not running when you move the database
directory.

Windows Vista, Windows Server 2008, or newer have native symbolic link
support, so you can create a symlink using the 'mklink' command.  This
command requires administrative privileges.

  1. Change location into the data directory:

          C:\> cd \PATH\TO\DATADIR

  2. In the data directory, create a symlink named 'mydb' that points to
     the location of the database directory:

          C:\> mklink /d mydb D:\data\mydb

After this, all tables created in the database 'mydb' are created in
'D:\data\mydb'.

8.12.4 Optimizing Memory Use
----------------------------

8.12.4.1 How MySQL Uses Memory
..............................

MySQL allocates buffers and caches to improve performance of database
operations.  The default configuration is designed to permit a MySQL
server to start on a virtual machine that has approximately 512MB of
RAM. You can improve MySQL performance by increasing the values of
certain cache and buffer-related system variables.  You can also modify
the default configuration to run MySQL on systems with limited memory.

The following list describes some of the ways that MySQL uses memory.
Where applicable, relevant system variables are referenced.  Some items
are storage engine or feature specific.

   * The 'InnoDB' buffer pool is a memory area that holds cached
     'InnoDB' data for tables, indexes, and other auxiliary buffers.
     For efficiency of high-volume read operations, the buffer pool is
     divided into pages that can potentially hold multiple rows.  For
     efficiency of cache management, the buffer pool is implemented as a
     linked list of pages; data that is rarely used is aged out of the
     cache, using a variation of the LRU algorithm.  For more
     information, see innodb-buffer-pool.

     The size of the buffer pool is important for system performance:

        * 'InnoDB' allocates memory for the entire buffer pool at server
          startup, using 'malloc()' operations.  The
          'innodb_buffer_pool_size' system variable defines the buffer
          pool size.  Typically, a recommended 'innodb_buffer_pool_size'
          value is 50 to 75 percent of system memory.
          'innodb_buffer_pool_size' can be configured dynamically, while
          the server is running.  For more information, see
          innodb-buffer-pool-resize.

        * On systems with a large amount of memory, you can improve
          concurrency by dividing the buffer pool into multiple buffer
          pool instances.  The 'innodb_buffer_pool_instances' system
          variable defines the number of buffer pool instances.

        * A buffer pool that is too small may cause excessive churning
          as pages are flushed from the buffer pool only to be required
          again a short time later.

        * A buffer pool that is too large may cause swapping due to
          competition for memory.

   * All threads share the 'MyISAM' key
     buffer.  The 'key_buffer_size' system variable determines its size.

     For each 'MyISAM' table the server opens, the index file is opened
     once; the data file is opened once for each concurrently running
     thread that accesses the table.  For each concurrent thread, a
     table structure, column structures for each column, and a buffer of
     size '3 * N' are allocated (where N is the maximum row length, not
     counting 'BLOB' columns).  A 'BLOB'.
     column requires five to eight bytes plus the length of the
     'BLOB' data.  The 'MyISAM' storage engine maintains one
     extra row buffer for internal use.

   * The 'myisam_use_mmap' system variable can be set to 1 to enable
     memory-mapping for all 'MyISAM' tables.

   * If an internal in-memory temporary table becomes too large (as
     determined using the 'tmp_table_size' and 'max_heap_table_size'
     system variables), MySQL automatically converts the table from
     in-memory to on-disk format.  On-disk temporary tables use the
     storage engine defined by the 'internal_tmp_disk_storage_engine'
     system variable.  You can increase the permissible temporary table
     size as described in internal-temporary-tables.

     For 'MEMORY' tables explicitly
     created with 'CREATE TABLE', only the
     'max_heap_table_size' system variable determines how large the
     table is permitted to grow and there is no conversion to on-disk
     format.

   * The MySQL Performance Schema is a
     feature for monitoring MySQL server execution at a low level.  The
     Performance Schema dynamically allocates memory incrementally,
     scaling its memory use to actual server load, instead of allocating
     required memory during server startup.  Once memory is allocated,
     it is not freed until the server is restarted.  For more
     information, see performance-schema-memory-model.

   * Each thread that the server uses to manage client connections
     requires some thread-specific space.  The following list indicates
     these and which system variables control their size:

        * A stack ('thread_stack')

        * A connection buffer ('net_buffer_length')

        * A result buffer ('net_buffer_length')

     The connection buffer and result buffer each begin with a size
     equal to 'net_buffer_length' bytes, but are dynamically enlarged up
     to 'max_allowed_packet' bytes as needed.  The result buffer shrinks
     to 'net_buffer_length' bytes after each SQL statement.  While a
     statement is running, a copy of the current statement string is
     also allocated.

     Each connection thread uses memory for computing statement digests.
     The server allocates 'max_digest_length' bytes per session.  See
     performance-schema-statement-digests.

   * All threads share the same base memory.

   * When a thread is no longer needed, the memory allocated to it is
     released and returned to the system unless the thread goes back
     into the thread cache.  In that case, the memory remains allocated.

   * Each request that performs a sequential scan of a table allocates a
     _read buffer_.  The 'read_buffer_size' system variable determines
     the buffer size.

   * When reading rows in an arbitrary sequence (for example, following
     a sort), a _random-read buffer_ may be allocated to avoid disk
     seeks.  The 'read_rnd_buffer_size' system variable determines the
     buffer size.

   * All joins are executed in a single pass, and most joins can be done
     without even using a temporary table.  Most temporary tables are
     memory-based hash tables.  Temporary tables with a large row length
     (calculated as the sum of all column lengths) or that contain
     'BLOB' columns are stored on disk.

   * Most requests that perform a sort allocate a sort buffer and zero
     to two temporary files depending on the result set size.  See
     temporary-files.

   * Almost all parsing and calculating is done in thread-local and
     reusable memory pools.  No memory overhead is needed for small
     items, thus avoiding the normal slow memory allocation and freeing.
     Memory is allocated only for unexpectedly large strings.

   * For each table having 'BLOB' columns, a buffer is
     enlarged dynamically to read in larger 'BLOB' values.
     If you scan a table, the buffer grows as large as the largest
     'BLOB' value.

   * MySQL requires memory and descriptors for the table cache.  Handler
     structures for all in-use tables are saved in the table cache and
     managed as 'First In, First Out' (FIFO). The 'table_open_cache'
     system variable defines the initial table cache size; see
     table-cache.

     MySQL also requires memory for the table definition cache.  The
     'table_definition_cache' system variable defines the number of
     table definitions (from '.frm' files) that can be stored in the
     table definition cache.  If you use a large number of tables, you
     can create a large table definition cache to speed up the opening
     of tables.  The table definition cache takes less space and does
     not use file descriptors, unlike the table cache.

   * A 'FLUSH TABLES' statement or 'mysqladmin flush-tables'
     command closes all tables that are not in use at once
     and marks all in-use tables to be closed when the currently
     executing thread finishes.  This effectively frees most in-use
     memory.  'FLUSH TABLES' does not return until all tables have been
     closed.

   * The server caches information in memory as a result of
     'GRANT', 'CREATE USER', 'CREATE SERVER',
     and 'INSTALL PLUGIN'.
     statements.  This memory is not released by the corresponding
     'REVOKE', 'DROP USER', 'DROP SERVER',
     and 'UNINSTALL PLUGIN'
     statements, so for a server that executes many
     instances of the statements that cause caching, there will be an
     increase in memory use.  This cached memory can be freed with
     'FLUSH PRIVILEGES'.

'ps' and other system status programs may report that 'mysqld'
uses a lot of memory.  This may be caused by thread stacks on
different memory addresses.  For example, the Solaris version of 'ps'
counts the unused memory between stacks as used memory.  To verify this,
check available swap with 'swap -s'.  We test 'mysqld'.
with several memory-leakage detectors (both commercial and Open Source),
so there should be no memory leaks.

*Monitoring MySQL Memory Usage*

The following example demonstrates how to use Performance Schema
and sys schema to monitor MySQL
memory usage.

Most Performance Schema memory instrumentation is disabled by default.
Instruments can be enabled by updating the 'ENABLED' column of the
Performance Schema 'setup_instruments'.
table.  Memory instruments have names in the form of
'memory/CODE_AREA/INSTRUMENT_NAME', where CODE_AREA is a value such as
'sql' or 'innodb', and INSTRUMENT_NAME is the instrument detail.

  1. To view available MySQL memory instruments, query the Performance
     Schema 'setup_instruments' table.
     The following query returns hundreds of memory instruments for all
     code areas.

          mysql> SELECT * FROM performance_schema.setup_instruments
                 WHERE NAME LIKE '%memory%';

     You can narrow results by specifying a code area.  For example, you
     can limit results to 'InnoDB' memory instruments by specifying
     'innodb' as the code area.

          mysql> SELECT * FROM performance_schema.setup_instruments
                 WHERE NAME LIKE '%memory/innodb%';
          +-------------------------------------------+---------+-------+
          | NAME                                      | ENABLED | TIMED |
          +-------------------------------------------+---------+-------+
          | memory/innodb/adaptive hash index         | NO      | NO    |
          | memory/innodb/buf_buf_pool                | NO      | NO    |
          | memory/innodb/dict_stats_bg_recalc_pool_t | NO      | NO    |
          | memory/innodb/dict_stats_index_map_t      | NO      | NO    |
          | memory/innodb/dict_stats_n_diff_on_level  | NO      | NO    |
          | memory/innodb/other                       | NO      | NO    |
          | memory/innodb/row_log_buf                 | NO      | NO    |
          | memory/innodb/row_merge_sort              | NO      | NO    |
          | memory/innodb/std                         | NO      | NO    |
          | memory/innodb/trx_sys_t::rw_trx_ids       | NO      | NO    |
          ...

     Depending on your MySQL installation, code areas may include
     'performance_schema', 'sql', 'client', 'innodb', 'myisam', 'csv',
     'memory', 'blackhole', 'archive', 'partition', and others.

  2. To enable memory instruments, add a 'performance-schema-instrument'
     rule to your MySQL configuration file.  For example, to enable all
     memory instruments, add this rule to your configuration file and
     restart the server:

          performance-schema-instrument='memory/%=COUNTED'

     *Note*:

     Enabling memory instruments at startup ensures that memory
     allocations that occur at startup are counted.

     After restarting the server, the 'ENABLED' column of the
     Performance Schema 'setup_instruments'
     table should report 'YES' for memory
     instruments that you enabled.  The 'TIMED' column in the
     'setup_instruments' table is ignored for
     memory instruments because memory operations are not timed.

          mysql> SELECT * FROM performance_schema.setup_instruments
                 WHERE NAME LIKE '%memory/innodb%';
          +-------------------------------------------+---------+-------+
          | NAME                                      | ENABLED | TIMED |
          +-------------------------------------------+---------+-------+
          | memory/innodb/adaptive hash index         | NO      | NO    |
          | memory/innodb/buf_buf_pool                | NO      | NO    |
          | memory/innodb/dict_stats_bg_recalc_pool_t | NO      | NO    |
          | memory/innodb/dict_stats_index_map_t      | NO      | NO    |
          | memory/innodb/dict_stats_n_diff_on_level  | NO      | NO    |
          | memory/innodb/other                       | NO      | NO    |
          | memory/innodb/row_log_buf                 | NO      | NO    |
          | memory/innodb/row_merge_sort              | NO      | NO    |
          | memory/innodb/std                         | NO      | NO    |
          | memory/innodb/trx_sys_t::rw_trx_ids       | NO      | NO    |
          ...

  3. Query memory instrument data.  In this example, memory instrument
     data is queried in the Performance Schema
     'memory_summary_global_by_event_name'.
     table, which summarizes data by 'EVENT_NAME'.  The 'EVENT_NAME' is
     the name of the instrument.

     The following query returns memory data for the 'InnoDB' buffer
     pool.  For column descriptions, see memory-summary-tables.

          mysql> SELECT * FROM performance_schema.memory_summary_global_by_event_name
                 WHERE EVENT_NAME LIKE 'memory/innodb/buf_buf_pool'\G
                            EVENT_NAME: memory/innodb/buf_buf_pool
                           COUNT_ALLOC: 1
                            COUNT_FREE: 0
             SUM_NUMBER_OF_BYTES_ALLOC: 137428992
              SUM_NUMBER_OF_BYTES_FREE: 0
                        LOW_COUNT_USED: 0
                    CURRENT_COUNT_USED: 1
                       HIGH_COUNT_USED: 1
              LOW_NUMBER_OF_BYTES_USED: 0
          CURRENT_NUMBER_OF_BYTES_USED: 137428992
             HIGH_NUMBER_OF_BYTES_USED: 137428992

     The same underlying data can be queried using the 'sys'
     schema 'memory_global_by_current_bytes'
     table, which shows current
     memory usage within the server globally, broken down by allocation
     type.

          mysql> SELECT * FROM sys.memory_global_by_current_bytes
                 WHERE event_name LIKE 'memory/innodb/buf_buf_pool'\G
          *************************** 1. row ***************************
                 event_name: memory/innodb/buf_buf_pool
              current_count: 1
              current_alloc: 131.06 MiB
          current_avg_alloc: 131.06 MiB
                 high_count: 1
                 high_alloc: 131.06 MiB
             high_avg_alloc: 131.06 MiB

     This 'sys' schema query aggregates currently
     allocated memory ('current_alloc') by code area:

          mysql> SELECT SUBSTRING_INDEX(event_name,'/',2) AS
                 code_area, sys.format_bytes(SUM(current_alloc))
                 AS current_alloc
                 FROM sys.x$memory_global_by_current_bytes
                 GROUP BY SUBSTRING_INDEX(event_name,'/',2)
                 ORDER BY SUM(current_alloc) DESC;
          +---------------------------+---------------+
          | code_area                 | current_alloc |
          +---------------------------+---------------+
          | memory/innodb             | 843.24 MiB    |
          | memory/performance_schema | 81.29 MiB     |
          | memory/mysys              | 8.20 MiB      |
          | memory/sql                | 2.47 MiB      |
          | memory/memory             | 174.01 KiB    |
          | memory/myisam             | 46.53 KiB     |
          | memory/blackhole          | 512 bytes     |
          | memory/federated          | 512 bytes     |
          | memory/csv                | 512 bytes     |
          | memory/vio                | 496 bytes     |
          +---------------------------+---------------+

     For more information about 'sys' schema, see
     sys-schema.

8.12.4.2 Enabling Large Page Support
....................................

Some hardware/operating system architectures support memory pages
greater than the default (usually 4KB). The actual implementation of
this support depends on the underlying hardware and operating system.
Applications that perform a lot of memory accesses may obtain
performance improvements by using large pages due to reduced Translation
Lookaside Buffer (TLB) misses.

In MySQL, large pages can be used by InnoDB, to allocate memory for its
buffer pool and additional memory pool.

Standard use of large pages in MySQL attempts to use the largest size
supported, up to 4MB. Under Solaris, a 'super large pages' feature
enables uses of pages up to 256MB. This feature is available for recent
SPARC platforms.  It can be enabled or disabled by using the
'--super-large-pages' or '--skip-super-large-pages' option.

MySQL also supports the Linux implementation of large page support
(which is called HugeTLB in Linux).

Before large pages can be used on Linux, the kernel must be enabled to
support them and it is necessary to configure the HugeTLB memory pool.
For reference, the HugeTBL API is documented in the
'Documentation/vm/hugetlbpage.txt' file of your Linux sources.

The kernel for some recent systems such as Red Hat Enterprise Linux
appear to have the large pages feature enabled by default.  To check
whether this is true for your kernel, use the following command and look
for output lines containing 'huge':

     shell> cat /proc/meminfo | grep -i huge
     HugePages_Total:       0
     HugePages_Free:        0
     HugePages_Rsvd:        0
     HugePages_Surp:        0
     Hugepagesize:       4096 kB

The nonempty command output indicates that large page support is
present, but the zero values indicate that no pages are configured for
use.

If your kernel needs to be reconfigured to support large pages, consult
the 'hugetlbpage.txt' file for instructions.

Assuming that your Linux kernel has large page support enabled,
configure it for use by MySQL using the following commands.  Normally,
you put these in an 'rc' file or equivalent startup file that is
executed during the system boot sequence, so that the commands execute
each time the system starts.  The commands should execute early in the
boot sequence, before the MySQL server starts.  Be sure to change the
allocation numbers and the group number as appropriate for your system.

     # Set the number of pages to be used.
     # Each page is normally 2MB, so a value of 20 = 40MB.
     # This command actually allocates memory, so this much
     # memory must be available.
     echo 20 > /proc/sys/vm/nr_hugepages

     # Set the group number that is permitted to access this
     # memory (102 in this case). The mysql user must be a
     # member of this group.
     echo 102 > /proc/sys/vm/hugetlb_shm_group

     # Increase the amount of shmem permitted per segment
     # (12G in this case).
     echo 1560281088 > /proc/sys/kernel/shmmax

     # Increase total amount of shared memory.  The value
     # is the number of pages. At 4KB/page, 4194304 = 16GB.
     echo 4194304 > /proc/sys/kernel/shmall

For MySQL usage, you normally want the value of 'shmmax' to be close to
the value of 'shmall'.

To verify the large page configuration, check '/proc/meminfo' again as
described previously.  Now you should see some nonzero values:

     shell> cat /proc/meminfo | grep -i huge
     HugePages_Total:      20
     HugePages_Free:       20
     HugePages_Rsvd:        0
     HugePages_Surp:        0
     Hugepagesize:       4096 kB

The final step to make use of the 'hugetlb_shm_group' is to give the
'mysql' user an 'unlimited' value for the memlock limit.  This can be
done either by editing '/etc/security/limits.conf' or by adding the
following command to your 'mysqld_safe' script:

     ulimit -l unlimited

Adding the 'ulimit' command to 'mysqld_safe' causes
the 'root' user to set the memlock limit to 'unlimited' before switching
to the 'mysql' user.  (This assumes that 'mysqld_safe'
is started by 'root'.)

Large page support in MySQL is disabled by default.  To enable it, start
the server with the '--large-pages' option.  For example, you can use
the following lines in your server's 'my.cnf' file:

     [mysqld]
     large-pages

With this option, 'InnoDB' uses large pages automatically for its buffer
pool and additional memory pool.  If 'InnoDB' cannot do this, it falls
back to use of traditional memory and writes a warning to the error log:
'Warning: Using conventional memory pool'

To verify that large pages are being used, check '/proc/meminfo' again:

     shell> cat /proc/meminfo | grep -i huge
     HugePages_Total:      20
     HugePages_Free:       20
     HugePages_Rsvd:        2
     HugePages_Surp:        0
     Hugepagesize:       4096 kB

8.12.5 Optimizing Network Use
-----------------------------

8.12.5.1 How MySQL Uses Threads for Client Connections
......................................................

Connection manager threads handle client connection requests on the
network interfaces that the server listens to.  On all platforms, one
manager thread handles TCP/IP connection requests.  On Unix, this
manager thread also handles Unix socket file connection requests.  On
Windows, a manager thread handles shared-memory connection requests, and
another handles named-pipe connection requests.  The server does not
create threads to handle interfaces that it does not listen to.  For
example, a Windows server that does not have support for named-pipe
connections enabled does not create a thread to handle them.

Connection manager threads associate each client connection with a
thread dedicated to it that handles authentication and request
processing for that connection.  Manager threads create a new thread
when necessary but try to avoid doing so by consulting the thread cache
first to see whether it contains a thread that can be used for the
connection.  When a connection ends, its thread is returned to the
thread cache if the cache is not full.

In this connection thread model, there are as many threads as there are
clients currently connected, which has some disadvantages when server
workload must scale to handle large numbers of connections.  For
example, thread creation and disposal becomes expensive.  Also, each
thread requires server and kernel resources, such as stack space.  To
accommodate a large number of simultaneous connections, the stack size
per thread must be kept small, leading to a situation where it is either
too small or the server consumes large amounts of memory.  Exhaustion of
other resources can occur as well, and scheduling overhead can become
significant.

To control and monitor how the server manages threads that handle client
connections, several system and status variables are relevant.  (See
server-system-variables, and server-status-variables.)

The thread cache has a size determined by the 'thread_cache_size' system
variable.  The default value is 0 (no caching), which causes a thread to
be set up for each new connection and disposed of when the connection
terminates.  Set 'thread_cache_size' to N to enable N inactive
connection threads to be cached.  'thread_cache_size' can be set at
server startup or changed while the server runs.  A connection thread
becomes inactive when the client connection with which it was associated
terminates.

To monitor the number of threads in the cache and how many threads have
been created because a thread could not be taken from the cache, monitor
the 'Threads_cached' and 'Threads_created' status variables.

You can set 'max_connections' at server startup or at runtime to control
the maximum number of clients that can connect simultaneously.

When the thread stack is too small, this limits the complexity of the
SQL statements which the server can handle, the recursion depth of
stored procedures, and other memory-consuming actions.  To set a stack
size of N bytes for each thread, start the server with
'--thread_stack=N'.

8.12.5.2 DNS Lookup Optimization and the Host Cache
...................................................

The MySQL server maintains a host cache in memory that contains
information about clients: IP address, host name, and error information.
The server uses this cache for nonlocal TCP connections.  It does not
use the cache for TCP connections established using a loopback interface
address ('127.0.0.1' or '::1'), or for connections established using a
Unix socket file, named pipe, or shared memory.

For each new client connection, the server uses the client IP address to
check whether the client host name is in the host cache.  If not, the
server attempts to resolve the host name.  First, it resolves the IP
address to a host name and resolves that host name back to an IP
address.  Then it compares the result to the original IP address to
ensure that they are the same.  The server stores information about the
result of this operation in the host cache.  If the cache is full, the
least recently used entry is discarded.

The 'host_cache'. Performance Schema table
exposes the contents of the host cache so that it can be examined using
'SELECT' statements.  This may help you diagnose the
causes of connection problems.  See host-cache-table.

The server handles entries in the host cache like this:

  1. When the first TCP client connection reaches the server from a
     given IP address, a new entry is created to record the client IP,
     host name, and client lookup validation flag.  Initially, the host
     name is set to 'NULL' and the flag is false.  This entry is also
     used for subsequent client connections from the same originating
     IP.

  2. If the validation flag for the client IP entry is false, the server
     attempts an IP-to-host name DNS resolution.  If that is successful,
     the host name is updated with the resolved host name and the
     validation flag is set to true.  If resolution is unsuccessful, the
     action taken depends on whether the error is permanent or
     transient.  For permanent failures, the host name remains 'NULL'
     and the validation flag is set to true.  For transient failures,
     the host name and validation flag remain unchanged.  (Another DNS
     resolution attempt occurs the next time a client connects from this
     IP.)

  3. If an error occurs while processing an incoming client connection
     from a given IP address, the server updates the corresponding error
     counters in the entry for that IP. For a description of the errors
     recorded, see host-cache-table.

The server performs host name resolution using the thread-safe
'gethostbyaddr_r()' and 'gethostbyname_r()' calls if the operating
system supports them.  Otherwise, the thread performing the lookup locks
a mutex and calls 'gethostbyaddr()' and 'gethostbyname()' instead.  In
this case, no other thread can resolve host names that are not in the
host cache until the thread holding the mutex lock releases it.

The server uses the host cache for several purposes:

   * By caching the results of IP-to-host name lookups, the server
     avoids doing a DNS lookup for each client connection.  Instead, for
     a given host, it needs to perform a lookup only for the first
     connection from that host.

   * The cache contains information about errors that occur during the
     connection process.  Some errors are considered 'blocking.' If too
     many of these occur successively from a given host without a
     successful connection, the server blocks further connections from
     that host.  The 'max_connect_errors' system variable determines the
     number of permitted errors before blocking occurs.  See
     blocked-host.

To unblock blocked hosts, flush the host cache by issuing a 'FLUSH
HOSTS' statement or executing a 'mysqladmin flush-hosts'
command.

It is possible for a blocked host to become unblocked even without
'FLUSH HOSTS' if activity from other hosts has occurred since the last
connection attempt from the blocked host.  This can occur because the
server discards the least recently used cache entry to make room for a
new entry if the cache is full when a connection arrives from a client
IP not in the cache.  If the discarded entry is for a blocked host, that
host becomes unblocked.

The host cache is enabled by default.  To disable it, set the
'host_cache_size' system variable to 0, either at server startup or at
runtime.

To disable DNS host name lookups, start the server with the
'--skip-name-resolve' option.  In this case, the server uses only IP
addresses and not host names to match connecting hosts to rows in the
MySQL grant tables.  Only accounts specified in those tables using IP
addresses can be used.  (Be sure that an account exists that specifies
an IP address or you may not be able to connect.)

If you have a very slow DNS and many hosts, you might be able to improve
performance either by disabling DNS lookups with '--skip-name-resolve'
or by increasing the value of 'host_cache_size' to make the host cache
larger.

To disallow TCP/IP connections entirely, start the server with the
'--skip-networking' option.

Some connection errors are not associated with TCP connections, occur
very early in the connection process (even before an IP address is
known), or are not specific to any particular IP address (such as
out-of-memory conditions).  For information about these errors, check
the 'Connection_errors_XXX' status variables (see
server-status-variables).

8.13 Measuring Performance (Benchmarking)
=========================================

To measure performance, consider the following factors:

   * Whether you are measuring the speed of a single operation on a
     quiet system, or how a set of operations (a 'workload') works over
     a period of time.  With simple tests, you usually test how changing
     one aspect (a configuration setting, the set of indexes on a table,
     the SQL clauses in a query) affects performance.  Benchmarks are
     typically long-running and elaborate performance tests, where the
     results could dictate high-level choices such as hardware and
     storage configuration, or how soon to upgrade to a new MySQL
     version.

   * For benchmarking, sometimes you must simulate a heavy database
     workload to get an accurate picture.

   * Performance can vary depending on so many different factors that a
     difference of a few percentage points might not be a decisive
     victory.  The results might shift the opposite way when you test in
     a different environment.

   * Certain MySQL features help or do not help performance depending on
     the workload.  For completeness, always test performance with those
     features turned on and turned off.  The two most important features
     to try with each workload are the MySQL query cache,
     and the adaptive hash index
     for 'InnoDB' tables.

This section progresses from simple and direct measurement techniques
that a single developer can do, to more complicated ones that require
additional expertise to perform and interpret the results.

8.13.1 Measuring the Speed of Expressions and Functions
-------------------------------------------------------

To measure the speed of a specific MySQL expression or function, invoke
the 'BENCHMARK()' function using the 'mysql' client
program.  Its syntax is 'BENCHMARK(LOOP_COUNT,EXPRESSION)'.  The return
value is always zero, but 'mysql' prints a line displaying
approximately how long the statement took to execute.  For example:

     mysql> SELECT BENCHMARK(1000000,1+1);
     +------------------------+
     | BENCHMARK(1000000,1+1) |
     +------------------------+
     |                      0 |
     +------------------------+
     1 row in set (0.32 sec)

This result was obtained on a Pentium II 400MHz system.  It shows that
MySQL can execute 1,000,000 simple addition expressions in 0.32 seconds
on that system.

The built-in MySQL functions are typically highly optimized, but there
may be some exceptions.  'BENCHMARK()' is an excellent tool for finding
out if some function is a problem for your queries.

8.13.2 Using Your Own Benchmarks
--------------------------------

Benchmark your application and database to find out where the
bottlenecks are.  After fixing one bottleneck (or by replacing it with a
'dummy' module), you can proceed to identify the next bottleneck.  Even
if the overall performance for your application currently is acceptable,
you should at least make a plan for each bottleneck and decide how to
solve it if someday you really need the extra performance.

A free benchmark suite is the Open Source Database Benchmark, available
at <http://osdb.sourceforge.net/>.

It is very common for a problem to occur only when the system is very
heavily loaded.  We have had many customers who contact us when they
have a (tested) system in production and have encountered load problems.
In most cases, performance problems turn out to be due to issues of
basic database design (for example, table scans are not good under high
load) or problems with the operating system or libraries.  Most of the
time, these problems would be much easier to fix if the systems were not
already in production.

To avoid problems like this, benchmark your whole application under the
worst possible load:

   * The 'mysqlslap' program can be helpful for
     simulating a high load produced by multiple clients issuing queries
     simultaneously.  See mysqlslap.

   * You can also try benchmarking packages such as SysBench and DBT2,
     available at <https://launchpad.net/sysbench>, and
     <http://osdldbt.sourceforge.net/#dbt2>.

These programs or packages can bring a system to its knees, so be sure
to use them only on your development systems.

8.13.3 Measuring Performance with performance_schema
----------------------------------------------------

You can query the tables in the 'performance_schema' database to see
real-time information about the performance characteristics of your
server and the applications it is running.  See
performance-schema for details.

8.14 Examining Thread Information
=================================

When you are attempting to ascertain what your MySQL server is doing, it
can be helpful to examine the process list, which is the set of threads
currently executing within the server.  Process list information is
available from these sources:

   * The 'SHOW [FULL] PROCESSLIST' statement: show-processlist

   * The 'SHOW PROFILE' statement:
     show-profiles

   * The 'INFORMATION_SCHEMA' 'PROCESSLIST'.
     table: processlist-table

   * The 'mysqladmin processlist' command:
     mysqladmin

   * The Performance Schema 'threads' table, stage
     tables, and lock tables:
     performance-schema-miscellaneous-tables,
     performance-schema-stage-tables,
     performance-schema-lock-tables.

   * The 'sys' schema 'processlist' view, which
     presents information from the Performance Schema 'threads'
     table in a more accessible format:
     sys-processlist

   * The 'sys' schema 'session' view, which presents
     information about user sessions (like the 'sys' schema
     'processlist' view, but with background processes
     filtered out): sys-session

Access to 'threads' does not require a mutex and
has minimal impact on server performance.
'INFORMATION_SCHEMA.PROCESSLIST' and 'SHOW PROCESSLIST'
have negative performance consequences
because they require a mutex.  'threads' also
shows information about background threads, which
'INFORMATION_SCHEMA.PROCESSLIST' and 'SHOW PROCESSLIST'
do not.  This means that
'threads' can be used to monitor activity the other
thread information sources cannot.

You can always view information about your own threads.  To view
information about threads being executed for other accounts, you must
have the 'PROCESS' privilege.

Each process list entry contains several pieces of information:

   * 'Id' is the connection identifier for the client associated with
     the thread.

   * 'User' and 'Host' indicate the account associated with the thread.

   * 'db' is the default database for the thread, or 'NULL' if none is
     selected.

   * 'Command' and 'State' indicate what the thread is doing.

     Most states correspond to very quick operations.  If a thread stays
     in a given state for many seconds, there might be a problem that
     needs to be investigated.

   * 'Time' indicates how long the thread has been in its current state.
     The thread's notion of the current time may be altered in some
     cases: The thread can change the time with 'SET TIMESTAMP = VALUE'.
     For a thread running on a slave that is
     processing events from the master, the thread time is set to the
     time found in the events and thus reflects current time on the
     master and not the slave.

   * 'Info' contains the text of the statement being executed by the
     thread, or 'NULL' if it is not executing one.  By default, this
     value contains only the first 100 characters of the statement.  To
     see the complete statements, use 'SHOW FULL PROCESSLIST'.

The following sections list the possible 'Command' values, and 'State'
values grouped by category.  The meaning for some of these values is
self-evident.  For others, additional description is provided.

8.14.1 Thread Command Values
----------------------------

A thread can have any of the following 'Command' values:

   *
     'Binlog Dump'

     This is a thread on a master server for sending binary log contents
     to a slave server.

   *
     'Change user'

     The thread is executing a change-user operation.

   *
     'Close stmt'

     The thread is closing a prepared statement.

   *
     'Connect'

     A replication slave is connected to its master.

   *
     'Connect Out'

     A replication slave is connecting to its master.

   *
     'Create DB'

     The thread is executing a create-database operation.

   *
     'Daemon'

     This thread is internal to the server, not a thread that services a
     client connection.

   *
     'Debug'

     The thread is generating debugging information.

   *
     'Delayed insert'

     The thread is a delayed-insert handler.

   *
     'Drop DB'

     The thread is executing a drop-database operation.

   *
     'Error'

   *
     'Execute'

     The thread is executing a prepared statement.

   *
     'Fetch'

     The thread is fetching the results from executing a prepared
     statement.

   *
     'Field List'

     The thread is retrieving information for table columns.

   *
     'Init DB'

     The thread is selecting a default database.

   *
     'Kill'

     The thread is killing another thread.

   *
     'Long Data'

     The thread is retrieving long data in the result of executing a
     prepared statement.

   *
     'Ping'

     The thread is handling a server-ping request.

   *
     'Prepare'

     The thread is preparing a prepared statement.

   *
     'Processlist'

     The thread is producing information about server threads.

   *
     'Query'

     The thread is executing a statement.

   *
     'Quit'

     The thread is terminating.

   *
     'Refresh'

     The thread is flushing table, logs, or caches, or resetting status
     variable or replication server information.

   *
     'Register Slave'

     The thread is registering a slave server.

   *
     'Reset stmt'

     The thread is resetting a prepared statement.

   *
     'Set option'

     The thread is setting or resetting a client statement-execution
     option.

   *
     'Shutdown'

     The thread is shutting down the server.

   *
     'Sleep'

     The thread is waiting for the client to send a new statement to it.

   *
     'Statistics'

     The thread is producing server-status information.

   *
     'Table Dump'

     The thread is sending table contents to a slave server.

   *
     'Time'

     Unused.

8.14.2 General Thread States
----------------------------

The following list describes thread 'State' values that are associated
with general query processing and not more specialized activities such
as replication.  Many of these are useful only for finding bugs in the
server.

   *
     'After create'

     This occurs when the thread creates a table (including internal
     temporary tables), at the end of the function that creates the
     table.  This state is used even if the table could not be created
     due to some error.

   *
     'Analyzing'

     The thread is calculating a 'MyISAM' table key distributions (for
     example, for 'ANALYZE TABLE').

   *
     'checking permissions'

     The thread is checking whether the server has the required
     privileges to execute the statement.

   *
     'Checking table'

     The thread is performing a table check operation.

   *
     'cleaning up'

     The thread has processed one command and is preparing to free
     memory and reset certain state variables.

   *
     'closing tables'

     The thread is flushing the changed table data to disk and closing
     the used tables.  This should be a fast operation.  If not, verify
     that you do not have a full disk and that the disk is not in very
     heavy use.

   *
     'converting HEAP to ondisk'

     The thread is converting an internal temporary table from a
     'MEMORY' table to an on-disk table.

   *
     'copy to tmp table'

     The thread is processing an 'ALTER TABLE'.
     statement.  This state occurs after the table with the new
     structure has been created but before rows are copied into it.

     For a thread in this state, the Performance Schema can be used to
     obtain about the progress of the copy operation.  See
     performance-schema-stage-tables.

   *
     'Copying to group table'

     If a statement has different 'ORDER BY' and 'GROUP BY' criteria,
     the rows are sorted by group and copied to a temporary table.

   *
     'Copying to tmp table'

     The server is copying to a temporary table in memory.

   *
     'altering table'

     The server is in the process of executing an in-place 'ALTER TABLE'.

   *
     'Copying to tmp table on disk'

     The server is copying to a temporary table on disk.  The temporary
     result set has become too large (see
     internal-temporary-tables).  Consequently, the thread is changing
     the temporary table from in-memory to disk-based format to save
     memory.

   *
     'Creating index'

     The thread is processing 'ALTER TABLE ... ENABLE KEYS' for a
     'MyISAM' table.

   *
     'Creating sort index'

     The thread is processing a 'SELECT' that is resolved
     using an internal temporary table.

   *
     'creating table'

     The thread is creating a table.  This includes creation of
     temporary tables.

   *
     'Creating tmp table'

     The thread is creating a temporary table in memory or on disk.  If
     the table is created in memory but later is converted to an on-disk
     table, the state during that operation will be 'Copying to tmp
     table on disk'.

   *
     'committing alter table to storage engine'

     The server has finished an in-place 'ALTER TABLE'
     and is committing the result.

   *
     'deleting from main table'

     The server is executing the first part of a multiple-table delete.
     It is deleting only from the first table, and saving columns and
     offsets to be used for deleting from the other (reference) tables.

   *
     'deleting from reference tables'

     The server is executing the second part of a multiple-table delete
     and deleting the matched rows from the other tables.

   *
     'discard_or_import_tablespace'

     The thread is processing an 'ALTER TABLE ... DISCARD TABLESPACE' or
     'ALTER TABLE ... IMPORT TABLESPACE' statement.

   *
     'end'

     This occurs at the end but before the cleanup of 'ALTER TABLE',
     see 'CREATE VIEW',
     'DELETE', 'INSERT', 'SELECT',
     or 'UPDATE' statements.

   *
     'executing'

     The thread has begun executing a statement.

   *
     'Execution of init_command'

     The thread is executing statements in the value of the
     'init_command' system variable.

   *
     'freeing items'

     The thread has executed a command.  Some freeing of items done
     during this state involves the query cache.  This state is usually
     followed by 'cleaning up'.

   *
     'FULLTEXT initialization'

     The server is preparing to perform a natural-language full-text
     search.

   *
     'init'

     This occurs before the initialization of 'ALTER TABLE',
     see 'DELETE', 'INSERT',
     'SELECT', or 'UPDATE' statements.  Actions
     taken by the server in this state include flushing the binary log,
     the 'InnoDB' log, and some query cache cleanup operations.

     For the 'end' state, the following operations could be happening:

        * Removing query cache entries after data in a table is changed

        * Writing an event to the binary log

        * Freeing memory buffers, including for blobs

   *
     'Killed'

     Someone has sent a 'KILL' statement to the thread and
     it should abort next time it checks the kill flag.  The flag is
     checked in each major loop in MySQL, but in some cases it might
     still take a short time for the thread to die.  If the thread is
     locked by some other thread, the kill takes effect as soon as the
     other thread releases its lock.

   *
     'logging slow query'

     The thread is writing a statement to the slow-query log.

   *
     'login'

     The initial state for a connection thread until the client has been
     authenticated successfully.

   *
     'manage keys'

     The server is enabling or disabling a table index.

   *
     'NULL'

     This state is used for the 'SHOW PROCESSLIST'
     state.

   *
     'Opening tables'

     The thread is trying to open a table.  This is should be very fast
     procedure, unless something prevents opening.  For example, an
     'ALTER TABLE' or a 'LOCK TABLE'
     statement can prevent opening a table until the
     statement is finished.  It is also worth checking that your
     'table_open_cache' value is large enough.

   *
     'optimizing'

     The server is performing initial optimizations for a query.

   *
     'preparing'

     This state occurs during query optimization.

   *
     'Purging old relay logs'

     The thread is removing unneeded relay log files.

   *
     'query end'

     This state occurs after processing a query but before the 'freeing
     items' state.

   *
     'Receiving from client'

     The server is reading a packet from the client.  This state is
     called 'Reading from net' prior to MySQL 5.7.8.

   *
     'Removing duplicates'

     The query was using 'SELECT DISTINCT' in such a way
     that MySQL could not optimize away the distinct operation at an
     early stage.  Because of this, MySQL requires an extra stage to
     remove all duplicated rows before sending the result to the client.

   *
     'removing tmp table'

     The thread is removing an internal temporary table after processing
     a 'SELECT' statement.  This state is not used if no
     temporary table was created.

   *
     'rename'

     The thread is renaming a table.

   *
     'rename result table'

     The thread is processing an 'ALTER TABLE'.
     statement, has created the new table, and is renaming it to replace
     the original table.

   *
     'Reopen tables'

     The thread got a lock for the table, but noticed after getting the
     lock that the underlying table structure changed.  It has freed the
     lock, closed the table, and is trying to reopen it.

   *
     'Repair by sorting'

     The repair code is using a sort to create indexes.

   *
     'preparing for alter table'

     The server is preparing to execute an in-place 'ALTER TABLE'.

   *
     'Repair done'

     The thread has completed a multi-threaded repair for a 'MyISAM'
     table.

   *
     'Repair with keycache'

     The repair code is using creating keys one by one through the key
     cache.  This is much slower than 'Repair by sorting'.

   *
     'Rolling back'

     The thread is rolling back a transaction.

   *
     'Saving state'

     For 'MyISAM' table operations such as repair or analysis, the
     thread is saving the new table state to the '.MYI' file header.
     State includes information such as number of rows, the
     'AUTO_INCREMENT' counter, and key distributions.

   *
     'Searching rows for update'

     The thread is doing a first phase to find all matching rows before
     updating them.  This has to be done if the 'UPDATE'.
     is changing the index that is used to find the involved rows.

   * 'Sending data'

     The thread is reading and processing rows for a 'SELECT'
     statement, and sending data to the client.  Because
     operations occurring during this state tend to perform large
     amounts of disk access (reads), it is often the longest-running
     state over the lifetime of a given query.

   *
     'Sending to client'

     The server is writing a packet to the client.  This state is called
     'Writing to net' prior to MySQL 5.7.8.

   *
     'setup'

     The thread is beginning an 'ALTER TABLE'.
     operation.

   *
     'Sorting for group'

     The thread is doing a sort to satisfy a 'GROUP BY'.

   *
     'Sorting for order'

     The thread is doing a sort to satisfy an 'ORDER BY'.

   *
     'Sorting index'

     The thread is sorting index pages for more efficient access during
     a 'MyISAM' table optimization operation.

   *
     'Sorting result'

     For a 'SELECT' statement, this is similar to
     'Creating sort index', but for nontemporary tables.

   *
     'statistics'

     The server is calculating statistics to develop a query execution
     plan.  If a thread is in this state for a long time, the server is
     probably disk-bound performing other work.

   *
     'System lock'

     The thread has called 'mysql_lock_tables()' and the thread state
     has not been updated since.  This is a very general state that can
     occur for many reasons.

     For example, the thread is going to request or is waiting for an
     internal or external system lock for the table.  This can occur
     when 'InnoDB' waits for a table-level
     lock during execution of 'LOCK TABLES'.  If this
     state is being caused by requests for external locks and you are
     not using multiple 'mysqld' servers that are
     accessing the same 'MyISAM' tables,
     you can disable external system locks with the
     '--skip-external-locking' option.  However, external locking is
     disabled by default, so it is likely that this option will have no
     effect.  For 'SHOW PROFILE', this state means
     the thread is requesting the lock (not waiting for it).

   *
     'update'

     The thread is getting ready to start updating the table.

   *
     'Updating'

     The thread is searching for rows to update and is updating them.

   *
     'updating main table'

     The server is executing the first part of a multiple-table update.
     It is updating only the first table, and saving columns and offsets
     to be used for updating the other (reference) tables.

   *
     'updating reference tables'

     The server is executing the second part of a multiple-table update
     and updating the matched rows from the other tables.

   *
     'User lock'

     The thread is going to request or is waiting for an advisory lock
     requested with a 'GET_LOCK()' call.  For 'SHOW PROFILE',
     this state means the thread is requesting the lock
     (not waiting for it).

   *
     'User sleep'

     The thread has invoked a 'SLEEP()' call.

   *
     'Waiting for commit lock'

     'FLUSH TABLES WITH READ LOCK' is waiting for a commit lock.

   *
     'Waiting for global read lock'

     'FLUSH TABLES WITH READ LOCK' is waiting for a global read lock or
     the global 'read_only' system variable is being set.

   *
     'Waiting for tables'

     The thread got a notification that the underlying structure for a
     table has changed and it needs to reopen the table to get the new
     structure.  However, to reopen the table, it must wait until all
     other threads have closed the table in question.

     This notification takes place if another thread has used 'FLUSH
     TABLES' or one of the following statements on the table in
     question: 'FLUSH TABLES TBL_NAME', see 'ALTER TABLE',
     see 'RENAME TABLE', 'REPAIR TABLE',
     see 'ANALYZE TABLE', or
     'OPTIMIZE TABLE'.

   *
     'Waiting for table flush'

     The thread is executing 'FLUSH TABLES' and is waiting for all
     threads to close their tables, or the thread got a notification
     that the underlying structure for a table has changed and it needs
     to reopen the table to get the new structure.  However, to reopen
     the table, it must wait until all other threads have closed the
     table in question.

     This notification takes place if another thread has used 'FLUSH
     TABLES' or one of the following statements on the table in
     question: 'FLUSH TABLES TBL_NAME', see 'ALTER TABLE',
     see 'RENAME TABLE', 'REPAIR TABLE',
     see 'ANALYZE TABLE', or
     'OPTIMIZE TABLE'.

   *
     'Waiting for LOCK_TYPE lock'

     The server is waiting to acquire a 'THR_LOCK' lock or a lock from
     the metadata locking subsystem, where LOCK_TYPE indicates the type
     of lock.

     This state indicates a wait for a 'THR_LOCK':

        * 'Waiting for table level lock'

     These states indicate a wait for a metadata lock:

        * 'Waiting for event metadata lock'

        * 'Waiting for global read lock'

        * 'Waiting for schema metadata lock'

        * 'Waiting for stored function metadata lock'

        * 'Waiting for stored procedure metadata lock'

        * 'Waiting for table metadata lock'

        * 'Waiting for trigger metadata lock'

     For information about table lock indicators, see
     internal-locking.  For information about metadata locking, see
     metadata-locking.  To see which locks are blocking lock
     requests, use the Performance Schema lock tables described at
     performance-schema-lock-tables.

   *
     'Waiting on cond'

     A generic state in which the thread is waiting for a condition to
     become true.  No specific state information is available.

   *
     'Writing to net'

     The server is writing a packet to the network.  This state is
     called 'Sending to client' as of MySQL 5.7.8.

8.14.3 Query Cache Thread States
--------------------------------

These thread states are associated with the query cache (see
query-cache).

   *
     'checking privileges on cached query'

     The server is checking whether the user has privileges to access a
     cached query result.

   *
     'checking query cache for query'

     The server is checking whether the current query is present in the
     query cache.

   *
     'invalidating query cache entries'

     Query cache entries are being marked invalid because the underlying
     tables have changed.

   *
     'sending cached result to client'

     The server is taking the result of a query from the query cache and
     sending it to the client.

   *
     'storing result in query cache'

     The server is storing the result of a query in the query cache.

   *
     'Waiting for query cache lock'

     This state occurs while a session is waiting to take the query
     cache lock.  This can happen for any statement that needs to
     perform some query cache operation, such as an 'INSERT'
     or 'DELETE' that invalidates the query
     cache, a 'SELECT' that looks for a cached entry,
     see 'RESET QUERY CACHE', and so forth.

8.14.4 Replication Master Thread States
---------------------------------------

The following list shows the most common states you may see in the
'State' column for the master's 'Binlog Dump' thread.  If you see no
'Binlog Dump' threads on a master server, this means that replication is
not running; that is, that no slaves are currently connected.

   *
     'Finished reading one binlog; switching to next binlog'

     The thread has finished reading a binary log file and is opening
     the next one to send to the slave.

   *
     'Master has sent all binlog to slave; waiting for more updates'

     The thread has read all remaining updates from the binary logs and
     sent them to the slave.  The thread is now idle, waiting for new
     events to appear in the binary log resulting from new updates
     occurring on the master.

   *
     'Sending binlog event to slave'

     Binary logs consist of _events_, where an event is usually an
     update plus some other information.  The thread has read an event
     from the binary log and is now sending it to the slave.

   *
     'Waiting to finalize termination'

     A very brief state that occurs as the thread is stopping.

8.14.5 Replication Slave I/O Thread States
------------------------------------------

The following list shows the most common states you see in the 'State'
column for a slave server I/O thread.  This state also appears in the
'Slave_IO_State' column displayed by 'SHOW SLAVE STATUS',
so you can get a good view of what is happening by
using that statement.

   *
     'Checking master version'

     A state that occurs very briefly, after the connection to the
     master is established.

   *
     'Connecting to master'

     The thread is attempting to connect to the master.

   *
     'Queueing master event to the relay log'

     The thread has read an event and is copying it to the relay log so
     that the SQL thread can process it.

   *
     'Reconnecting after a failed binlog dump request'

     The thread is trying to reconnect to the master.

   *
     'Reconnecting after a failed master event read'

     The thread is trying to reconnect to the master.  When connection
     is established again, the state becomes 'Waiting for master to send
     event'.

   *
     'Registering slave on master'

     A state that occurs very briefly after the connection to the master
     is established.

   *
     'Requesting binlog dump'

     A state that occurs very briefly, after the connection to the
     master is established.  The thread sends to the master a request
     for the contents of its binary logs, starting from the requested
     binary log file name and position.

   *
     'Waiting for its turn to commit'

     A state that occurs when the slave thread is waiting for older
     worker threads to commit if 'slave_preserve_commit_order' is
     enabled.

   *
     'Waiting for master to send event'

     The thread has connected to the master and is waiting for binary
     log events to arrive.  This can last for a long time if the master
     is idle.  If the wait lasts for 'slave_net_timeout' seconds, a
     timeout occurs.  At that point, the thread considers the connection
     to be broken and makes an attempt to reconnect.

   *
     'Waiting for master update'

     The initial state before 'Connecting to master'.

   *
     'Waiting for slave mutex on exit'

     A state that occurs briefly as the thread is stopping.

   *
     'Waiting for the slave SQL thread to free enough relay log space'

     You are using a nonzero 'relay_log_space_limit' value, and the
     relay logs have grown large enough that their combined size exceeds
     this value.  The I/O thread is waiting until the SQL thread frees
     enough space by processing relay log contents so that it can delete
     some relay log files.

   *
     'Waiting to reconnect after a failed binlog dump request'

     If the binary log dump request failed (due to disconnection), the
     thread goes into this state while it sleeps, then tries to
     reconnect periodically.  The interval between retries can be
     specified using the 'CHANGE MASTER TO'.
     statement.

   *
     'Waiting to reconnect after a failed master event read'

     An error occurred while reading (due to disconnection).  The thread
     is sleeping for the number of seconds set by the 'CHANGE MASTER TO'
     statement (default 60) before
     attempting to reconnect.

8.14.6 Replication Slave SQL Thread States
------------------------------------------

The following list shows the most common states you may see in the
'State' column for a slave server SQL thread:

   *
     'Killing slave'

     The thread is processing a 'STOP SLAVE' statement.

   *
     'Making temporary file (append) before replaying LOAD DATA INFILE'

     The thread is executing a 'LOAD DATA INFILE'.
     statement and is appending the data to a temporary file containing
     the data from which the slave will read rows.

   *
     'Making temporary file (create) before replaying LOAD DATA INFILE'

     The thread is executing a 'LOAD DATA INFILE'.
     statement and is creating a temporary file containing the data from
     which the slave will read rows.  This state can only be encountered
     if the original 'LOAD DATA INFILE' statement was
     logged by a master running a version of MySQL earlier than version
     5.0.3.

   *
     'Reading event from the relay log'

     The thread has read an event from the relay log so that the event
     can be processed.

   *
     'Slave has read all relay log; waiting for more updates'

     The thread has processed all events in the relay log files, and is
     now waiting for the I/O thread to write new events to the relay
     log.

   *
     'Waiting for an event from Coordinator'

     Using the multi-threaded slave ('slave_parallel_workers' is greater
     than 1), one of the slave worker threads is waiting for an event
     from the coordinator thread.

   *
     'Waiting for slave mutex on exit'

     A very brief state that occurs as the thread is stopping.

   *
     'Waiting for Slave Workers to free pending events'

     This waiting action occurs when the total size of events being
     processed by Workers exceeds the size of the
     'slave_pending_jobs_size_max' system variable.  The Coordinator
     resumes scheduling when the size drops below this limit.  This
     state occurs only when 'slave_parallel_workers' is set greater than
     0.

   *
     'Waiting for the next event in relay log'

     The initial state before 'Reading event from the relay log'.

   *
     'Waiting until MASTER_DELAY seconds after master executed event'

     The SQL thread has read an event but is waiting for the slave delay
     to lapse.  This delay is set with the 'MASTER_DELAY' option of
     'CHANGE MASTER TO'.

The 'Info' column for the SQL thread may also show the text of a
statement.  This indicates that the thread has read an event from the
relay log, extracted the statement from it, and may be executing it.

8.14.7 Replication Slave Connection Thread States
-------------------------------------------------

These thread states occur on a replication slave but are associated with
connection threads, not with the I/O or SQL threads.

   *
     'Changing master'

     The thread is processing a 'CHANGE MASTER TO'
     statement.

   *
     'Killing slave'

     The thread is processing a 'STOP SLAVE' statement.

   *
     'Opening master dump table'

     This state occurs after 'Creating table from master dump'.

   *
     'Reading master dump table data'

     This state occurs after 'Opening master dump table'.

   *
     'Rebuilding the index on master dump table'

     This state occurs after 'Reading master dump table data'.

8.14.8 NDB Cluster Thread States
--------------------------------

   *
     'Committing events to binlog'

   *
     'Opening mysql.ndb_apply_status'

   *
     'Processing events'

     The thread is processing events for binary logging.

   *
     'Processing events from schema table'

     The thread is doing the work of schema replication.

   *
     'Shutting down'

   *
     'Syncing ndb table schema operation and binlog'

     This is used to have a correct binary log of schema operations for
     NDB.

   *
     'Waiting for allowed to take ndbcluster global schema lock'

     The thread is waiting for permission to take a global schema lock.

   *
     'Waiting for event from ndbcluster'

     The server is acting as an SQL node in an NDB Cluster, and is
     connected to a cluster management node.

   *
     'Waiting for first event from ndbcluster'

   *
     'Waiting for ndbcluster binlog update to reach current position'

   *
     'Waiting for ndbcluster global schema lock'

     The thread is waiting for a global schema lock held by another
     thread to be released.

   *
     'Waiting for ndbcluster to start'

   *
     'Waiting for schema epoch'

     The thread is waiting for a schema epoch (that is, a global
     checkpoint).

8.14.9 Event Scheduler Thread States
------------------------------------

These states occur for the Event Scheduler thread, threads that are
created to execute scheduled events, or threads that terminate the
scheduler.

   *
     'Clearing'

     The scheduler thread or a thread that was executing an event is
     terminating and is about to end.

   *
     'Initialized'

     The scheduler thread or a thread that will execute an event has
     been initialized.

   *
     'Waiting for next activation'

     The scheduler has a nonempty event queue but the next activation is
     in the future.

   *
     'Waiting for scheduler to stop'

     The thread issued 'SET GLOBAL event_scheduler=OFF' and is waiting
     for the scheduler to stop.

   *
     'Waiting on empty queue'

     The scheduler's event queue is empty and it is sleeping.

9 Language Structure
********************

This chapter discusses the rules for writing the following elements of
SQL statements when using MySQL:

   * Literal values such as strings and numbers

   * Identifiers such as database, table, and column names

   * Keywords and reserved words

   * User-defined and system variables

   * Comments

9.1 Literal Values
==================

This section describes how to write literal values in MySQL. These
include strings, numbers, hexadecimal and bit values, boolean values,
and 'NULL'.  The section also covers various nuances that you may
encounter when dealing with these basic types in MySQL.

9.1.1 String Literals
---------------------

A string is a sequence of bytes or characters, enclosed within either
single quote (''') or double quote ('"') characters.  Examples:

     'a string'
     "another string"

Quoted strings placed next to each other are concatenated to a single
string.  The following lines are equivalent:

     'a string'
     'a' ' ' 'string'

If the 'ANSI_QUOTES' SQL mode is enabled, string literals can be quoted
only within single quotation marks because a string quoted within double
quotation marks is interpreted as an identifier.

A _binary string_ is a string of bytes.  Every binary string has a
character set and collation named 'binary'.  A _nonbinary string_ is a
string of characters.  It has a character set other than 'binary' and a
collation that is compatible with the character set.

For both types of strings, comparisons are based on the numeric values
of the string unit.  For binary strings, the unit is the byte;
comparisons use numeric byte values.  For nonbinary strings, the unit is
the character and some character sets support multibyte characters;
comparisons use numeric character code values.  Character code ordering
is a function of the string collation.  (For more information, see
charset-binary-collations.)

A character string literal may have an optional character set introducer
and 'COLLATE' clause, to designate it as a string that uses a particular
character set and collation:

     [_CHARSET_NAME]'STRING' [COLLATE COLLATION_NAME]

Examples:

     SELECT _latin1'STRING';
     SELECT _binary'STRING';
     SELECT _utf8'STRING' COLLATE utf8_danish_ci;

You can use 'N'LITERAL'' (or 'n'LITERAL'') to create a string in the
national character set.  These statements are equivalent:

     SELECT N'some text';
     SELECT n'some text';
     SELECT _utf8'some text';

For information about these forms of string syntax, see
charset-national, and charset-introducer.

Within a string, certain sequences have special meaning unless the
'NO_BACKSLASH_ESCAPES' SQL mode is enabled.  Each of these sequences
begins with a backslash ('\'), known as the _escape character_.  MySQL
recognizes the escape sequences shown in
character-escape-sequences.  For all other escape sequences, backslash
is ignored.  That is, the escaped character is interpreted as if it was
not escaped.  For example, '\x' is just 'x'.  These sequences are
case-sensitive.  For example, '\b' is interpreted as a backspace, but
'\B' is interpreted as 'B'.  Escape processing is done according to the
character set indicated by the 'character_set_connection' system
variable.  This is true even for strings that are preceded by an
introducer that indicates a different character set, as discussed in
charset-literal.

*Special Character Escape Sequences*

Escape      Character Represented by Sequence
Sequence

'\0'        An ASCII NUL ('X'00'') character

'\''        A single quote (''') character

'\"'        A double quote ('"') character

'\b'        A backspace character

'\n'        A newline (linefeed) character

'\r'        A carriage return character

'\t'        A tab character

'\Z'        ASCII 26 (Control+Z); see note following the table

'\\'        A backslash ('\') character

'\%'        A '%' character; see note following the table

'\_'        A '_' character; see note following the table

The ASCII 26 character can be encoded as '\Z' to enable you to work
around the problem that ASCII 26 stands for END-OF-FILE on Windows.
ASCII 26 within a file causes problems if you try to use 'mysql DB_NAME
< FILE_NAME'.

The '\%' and '\_' sequences are used to search for literal instances of
'%' and '_' in pattern-matching contexts where they would otherwise be
interpreted as wildcard characters.  See the description of the 'LIKE'
operator in string-comparison-functions.  If you use '\%' or
'\_' outside of pattern-matching contexts, they evaluate to the strings
'\%' and '\_', not to '%' and '_'.

There are several ways to include quote characters within a string:

   * A ''' inside a string quoted with ''' may be written as ''''.

   * A '"' inside a string quoted with '"' may be written as '""'.

   * Precede the quote character by an escape character ('\').

   * A ''' inside a string quoted with '"' needs no special treatment
     and need not be doubled or escaped.  In the same way, '"' inside a
     string quoted with ''' needs no special treatment.

The following 'SELECT' statements demonstrate how quoting
and escaping work:

     mysql> SELECT 'hello', '"hello"', '""hello""', 'hel''lo', '\'hello';
     +-------+---------+-----------+--------+--------+
     | hello | "hello" | ""hello"" | hel'lo | 'hello |
     +-------+---------+-----------+--------+--------+

     mysql> SELECT "hello", "'hello'", "''hello''", "hel""lo", "\"hello";
     +-------+---------+-----------+--------+--------+
     | hello | 'hello' | ''hello'' | hel"lo | "hello |
     +-------+---------+-----------+--------+--------+

     mysql> SELECT 'This\nIs\nFour\nLines';
     +--------------------+
     | This
     Is
     Four
     Lines |
     +--------------------+

     mysql> SELECT 'disappearing\ backslash';
     +------------------------+
     | disappearing backslash |
     +------------------------+

To insert binary data into a string column (such as a 'BLOB'
column), you should represent certain characters by escape
sequences.  Backslash ('\') and the quote character used to quote the
string must be escaped.  In certain client environments, it may also be
necessary to escape 'NUL' or Control+Z. The 'mysql' client
truncates quoted strings containing 'NUL' characters if they are not
escaped, and Control+Z may be taken for END-OF-FILE on Windows if not
escaped.  For the escape sequences that represent each of these
characters, see character-escape-sequences.

When writing application programs, any string that might contain any of
these special characters must be properly escaped before the string is
used as a data value in an SQL statement that is sent to the MySQL
server.  You can do this in two ways:

   * Process the string with a function that escapes the special
     characters.  In a C program, you can use the
     'mysql_real_escape_string_quote()'.
     C API function to escape characters.  See
     mysql-real-escape-string-quote.  Within SQL statements that
     construct other SQL statements, you can use the 'QUOTE()' function.
     The Perl DBI interface provides a 'quote' method to convert special
     characters to the proper escape sequences.  See apis-perl.
     Other language interfaces may provide a similar capability.

   * As an alternative to explicitly escaping special characters, many
     MySQL APIs provide a placeholder capability that enables you to
     insert special markers into a statement string, and then bind data
     values to them when you issue the statement.  In this case, the API
     takes care of escaping special characters in the values for you.

9.1.2 Numeric Literals
----------------------

Number literals include exact-value (integer and 'DECIMAL')
literals and approximate-value (floating-point)
literals.

Integers are represented as a sequence of digits.  Numbers may include
'.' as a decimal separator.  Numbers may be preceded by '-' or '+' to
indicate a negative or positive value, respectively.  Numbers
represented in scientific notation with a mantissa and exponent are
approximate-value numbers.

Exact-value numeric literals have an integer part or fractional part, or
both.  They may be signed.  Examples: '1', '.2', '3.4', '-5', '-6.78',
'+9.10'.

Approximate-value numeric literals are represented in scientific
notation with a mantissa and exponent.  Either or both parts may be
signed.  Examples: '1.2E3', '1.2E-3', '-1.2E3', '-1.2E-3'.

Two numbers that look similar may be treated differently.  For example,
'2.34' is an exact-value (fixed-point) number, whereas '2.34E0' is an
approximate-value (floating-point) number.

The 'DECIMAL' data type is a fixed-point type
and calculations are exact.  In MySQL, the 'DECIMAL'
type has several synonyms: 'NUMERIC',
see 'DEC', 'FIXED'.
The integer types also are exact-value types.  For
more information about exact-value calculations, see
precision-math.

The 'FLOAT' and 'DOUBLE'
data types are floating-point types and
calculations are approximate.  In MySQL, types that are synonymous with
'FLOAT' or 'DOUBLE'
are 'DOUBLE PRECISION'
and 'REAL'.

An integer may be used in a floating-point context; it is interpreted as
the equivalent floating-point number.

9.1.3 Date and Time Literals
----------------------------

Date and time values can be represented in several formats, such as
quoted strings or as numbers, depending on the exact type of the value
and other factors.  For example, in contexts where MySQL expects a date,
it interprets any of ''2015-07-21'', ''20150721'', and '20150721' as a
date.

This section describes the acceptable formats for date and time
literals.  For more information about the temporal data types, such as
the range of permitted values, consult these sections:

   * date-and-time-type-overview

   * date-and-time-types

Standard SQL and ODBC Date and Time Literals

Standard SQL permits temporal literals to be specified using a type
keyword and a string.  The space between the keyword and string is
optional.

     DATE 'STR'
     TIME 'STR'
     TIMESTAMP 'STR'

MySQL recognizes those constructions and also the corresponding ODBC
syntax:

     { d 'STR' }
     { t 'STR' }
     { ts 'STR' }

MySQL uses the type keyword and these constructions produce
'DATE', 'TIME', and 'DATETIME'.
values, respectively, including a trailing fractional seconds part if
specified.  The 'TIMESTAMP' syntax produces a
'DATETIME' value in MySQL because 'DATETIME'.
has a range that more closely corresponds to the standard SQL
'TIMESTAMP' type, which has a year range from '0001' to
'9999'.  (The MySQL 'TIMESTAMP' year range is '1970' to
'2038'.)

String and Numeric Literals in Date and Time Context

MySQL recognizes 'DATE' values in these formats:

   * As a string in either ''YYYY-MM-DD'' or ''YY-MM-DD'' format.  A
     'relaxed' syntax is permitted: Any punctuation character may be
     used as the delimiter between date parts.  For example,
     ''2012-12-31'', ''2012/12/31'', ''2012^12^31'', and ''2012@12@31''
     are equivalent.

   * As a string with no delimiters in either ''YYYYMMDD'' or ''YYMMDD''
     format, provided that the string makes sense as a date.  For
     example, ''20070523'' and ''070523'' are interpreted as
     ''2007-05-23'', but ''071332'' is illegal (it has nonsensical month
     and day parts) and becomes ''0000-00-00''.

   * As a number in either 'YYYYMMDD' or 'YYMMDD' format, provided that
     the number makes sense as a date.  For example, '19830905' and
     '830905' are interpreted as ''1983-09-05''.

MySQL recognizes 'DATETIME' and 'TIMESTAMP'
values in these formats:

   * As a string in either ''YYYY-MM-DD HH:MM:SS'' or ''YY-MM-DD
     HH:MM:SS'' format.  A 'relaxed' syntax is permitted here, too: Any
     punctuation character may be used as the delimiter between date
     parts or time parts.  For example, ''2012-12-31 11:30:45'',
     ''2012^12^31 11+30+45'', ''2012/12/31 11*30*45'', and ''2012@12@31
     11^30^45'' are equivalent.

     The only delimiter recognized between a date and time part and a
     fractional seconds part is the decimal point.

     The date and time parts can be separated by 'T' rather than a
     space.  For example, ''2012-12-31 11:30:45''
     ''2012-12-31T11:30:45'' are equivalent.

   * As a string with no delimiters in either ''YYYYMMDDHHMMSS'' or
     ''YYMMDDHHMMSS'' format, provided that the string makes sense as a
     date.  For example, ''20070523091528'' and ''070523091528'' are
     interpreted as ''2007-05-23 09:15:28'', but ''071122129015'' is
     illegal (it has a nonsensical minute part) and becomes ''0000-00-00
     00:00:00''.

   * As a number in either 'YYYYMMDDHHMMSS' or 'YYMMDDHHMMSS' format,
     provided that the number makes sense as a date.  For example,
     '19830905132800' and '830905132800' are interpreted as ''1983-09-05
     13:28:00''.

A 'DATETIME' or 'TIMESTAMP' value can
include a trailing fractional seconds part in up to microseconds (6
digits) precision.  The fractional part should always be separated from
the rest of the time by a decimal point; no other fractional seconds
delimiter is recognized.  For information about fractional seconds
support in MySQL, see fractional-seconds.

Dates containing two-digit year values are ambiguous because the century
is unknown.  MySQL interprets two-digit year values using these rules:

   * Year values in the range '70-99' are converted to '1970-1999'.

   * Year values in the range '00-69' are converted to '2000-2069'.

See also two-digit-years.

For values specified as strings that include date part delimiters, it is
unnecessary to specify two digits for month or day values that are less
than '10'.  ''2015-6-9'' is the same as ''2015-06-09''.  Similarly, for
values specified as strings that include time part delimiters, it is
unnecessary to specify two digits for hour, minute, or second values
that are less than '10'.  ''2015-10-30 1:2:3'' is the same as
''2015-10-30 01:02:03''.

Values specified as numbers should be 6, 8, 12, or 14 digits long.  If a
number is 8 or 14 digits long, it is assumed to be in 'YYYYMMDD' or
'YYYYMMDDHHMMSS' format and that the year is given by the first 4
digits.  If the number is 6 or 12 digits long, it is assumed to be in
'YYMMDD' or 'YYMMDDHHMMSS' format and that the year is given by the
first 2 digits.  Numbers that are not one of these lengths are
interpreted as though padded with leading zeros to the closest length.

Values specified as nondelimited strings are interpreted according their
length.  For a string 8 or 14 characters long, the year is assumed to be
given by the first 4 characters.  Otherwise, the year is assumed to be
given by the first 2 characters.  The string is interpreted from left to
right to find year, month, day, hour, minute, and second values, for as
many parts as are present in the string.  This means you should not use
strings that have fewer than 6 characters.  For example, if you specify
''9903'', thinking that represents March, 1999, MySQL converts it to the
'zero' date value.  This occurs because the year and month values are
'99' and '03', but the day part is completely missing.  However, you can
explicitly specify a value of zero to represent missing month or day
parts.  For example, to insert the value ''1999-03-00'', use ''990300''.

MySQL recognizes 'TIME' values in these formats:

   * As a string in ''D HH:MM:SS'' format.  You can also use one of the
     following 'relaxed' syntaxes: ''HH:MM:SS'', ''HH:MM'', ''D HH:MM'',
     ''D HH'', or ''SS''.  Here 'D' represents days and can have a value
     from 0 to 34.

   * As a string with no delimiters in ''HHMMSS'' format, provided that
     it makes sense as a time.  For example, ''101112'' is understood as
     ''10:11:12'', but ''109712'' is illegal (it has a nonsensical
     minute part) and becomes ''00:00:00''.

   * As a number in 'HHMMSS' format, provided that it makes sense as a
     time.  For example, '101112' is understood as ''10:11:12''.  The
     following alternative formats are also understood: 'SS', 'MMSS', or
     'HHMMSS'.

A trailing fractional seconds part is recognized in the ''D
HH:MM:SS.fraction'', ''HH:MM:SS.fraction'', ''HHMMSS.fraction'', and
'HHMMSS.fraction' time formats, where 'fraction' is the fractional part
in up to microseconds (6 digits) precision.  The fractional part should
always be separated from the rest of the time by a decimal point; no
other fractional seconds delimiter is recognized.  For information about
fractional seconds support in MySQL, see fractional-seconds.

For 'TIME' values specified as strings that include a time
part delimiter, it is unnecessary to specify two digits for hours,
minutes, or seconds values that are less than '10'.  ''8:3:2'' is the
same as ''08:03:02''.

9.1.4 Hexadecimal Literals
--------------------------

Hexadecimal literal values are written using 'X'VAL'' or '0xVAL'
notation, where VAL contains hexadecimal digits ('0..9', 'A..F').
Lettercase of the digits and of any leading 'X' does not matter.  A
leading '0x' is case-sensitive and cannot be written as '0X'.

Legal hexadecimal literals:

     X'01AF'
     X'01af'
     x'01AF'
     x'01af'
     0x01AF
     0x01af

Illegal hexadecimal literals:

     X'0G'   (G is not a hexadecimal digit)
     0X01AF  (0X must be written as 0x)

Values written using 'X'VAL'' notation must contain an even number of
digits or a syntax error occurs.  To correct the problem, pad the value
with a leading zero:

     mysql> SET @s = X'FFF';
     ERROR 1064 (42000): You have an error in your SQL syntax;
     check the manual that corresponds to your MySQL server
     version for the right syntax to use near 'X'FFF''

     mysql> SET @s = X'0FFF';
     Query OK, 0 rows affected (0.00 sec)

Values written using '0xVAL' notation that contain an odd number of
digits are treated as having an extra leading '0'.  For example, '0xaaa'
is interpreted as '0x0aaa'.

By default, a hexadecimal literal is a binary string, where each pair of
hexadecimal digits represents a character:

     mysql> SELECT X'4D7953514C', CHARSET(X'4D7953514C');
     +---------------+------------------------+
     | X'4D7953514C' | CHARSET(X'4D7953514C') |
     +---------------+------------------------+
     | MySQL         | binary                 |
     +---------------+------------------------+
     mysql> SELECT 0x5461626c65, CHARSET(0x5461626c65);
     +--------------+-----------------------+
     | 0x5461626c65 | CHARSET(0x5461626c65) |
     +--------------+-----------------------+
     | Table        | binary                |
     +--------------+-----------------------+

A hexadecimal literal may have an optional character set introducer and
'COLLATE' clause, to designate it as a string that uses a particular
character set and collation:

     [_CHARSET_NAME] X'VAL' [COLLATE COLLATION_NAME]

Examples:

     SELECT _latin1 X'4D7953514C';
     SELECT _utf8 0x4D7953514C COLLATE utf8_danish_ci;

The examples use 'X'VAL'' notation, but '0xVAL' notation permits
introducers as well.  For information about introducers, see
charset-introducer.

In numeric contexts, MySQL treats a hexadecimal literal like a
'BIGINT'. (64-bit integer).  To ensure numeric treatment
of a hexadecimal literal, use it in numeric context.  Ways to do this
include adding 0 or using 'CAST(... AS UNSIGNED)'.  For example, a
hexadecimal literal assigned to a user-defined variable is a binary
string by default.  To assign the value as a number, use it in numeric
context:

     mysql> SET @v1 = X'41';
     mysql> SET @v2 = X'41'+0;
     mysql> SET @v3 = CAST(X'41' AS UNSIGNED);
     mysql> SELECT @v1, @v2, @v3;
     +------+------+------+
     | @v1  | @v2  | @v3  |
     +------+------+------+
     | A    |   65 |   65 |
     +------+------+------+

An empty hexadecimal value ('X''') evaluates to a zero-length binary
string.  Converted to a number, it produces 0:

     mysql> SELECT CHARSET(X''), LENGTH(X'');
     +--------------+-------------+
     | CHARSET(X'') | LENGTH(X'') |
     +--------------+-------------+
     | binary       |           0 |
     +--------------+-------------+
     mysql> SELECT X''+0;
     +-------+
     | X''+0 |
     +-------+
     |     0 |
     +-------+

The 'X'VAL'' notation is based on standard SQL. The '0x' notation is
based on ODBC, for which hexadecimal strings are often used to supply
values for 'BLOB' columns.

To convert a string or a number to a string in hexadecimal format, use
the 'HEX()' function:

     mysql> SELECT HEX('cat');
     +------------+
     | HEX('cat') |
     +------------+
     | 636174     |
     +------------+
     mysql> SELECT X'636174';
     +-----------+
     | X'636174' |
     +-----------+
     | cat       |
     +-----------+

9.1.5 Bit-Value Literals
------------------------

Bit-value literals are written using 'b'VAL'' or '0bVAL' notation.  VAL
is a binary value written using zeros and ones.  Lettercase of any
leading 'b' does not matter.  A leading '0b' is case sensitive and
cannot be written as '0B'.

Legal bit-value literals:

     b'01'
     B'01'
     0b01

Illegal bit-value literals:

     b'2'    (2 is not a binary digit)
     0B01    (0B must be written as 0b)

By default, a bit-value literal is a binary string:

     mysql> SELECT b'1000001', CHARSET(b'1000001');
     +------------+---------------------+
     | b'1000001' | CHARSET(b'1000001') |
     +------------+---------------------+
     | A          | binary              |
     +------------+---------------------+
     mysql> SELECT 0b1100001, CHARSET(0b1100001);
     +-----------+--------------------+
     | 0b1100001 | CHARSET(0b1100001) |
     +-----------+--------------------+
     | a         | binary             |
     +-----------+--------------------+

A bit-value literal may have an optional character set introducer and
'COLLATE' clause, to designate it as a string that uses a particular
character set and collation:

     [_CHARSET_NAME] b'VAL' [COLLATE COLLATION_NAME]

Examples:

     SELECT _latin1 b'1000001';
     SELECT _utf8 0b1000001 COLLATE utf8_danish_ci;

The examples use 'b'VAL'' notation, but '0bVAL' notation permits
introducers as well.  For information about introducers, see
charset-introducer.

In numeric contexts, MySQL treats a bit literal like an integer.  To
ensure numeric treatment of a bit literal, use it in numeric context.
Ways to do this include adding 0 or using 'CAST(... AS UNSIGNED)'.  For
example, a bit literal assigned to a user-defined variable is a binary
string by default.  To assign the value as a number, use it in numeric
context:

     mysql> SET @v1 = b'1100001';
     mysql> SET @v2 = b'1100001'+0;
     mysql> SET @v3 = CAST(b'1100001' AS UNSIGNED);
     mysql> SELECT @v1, @v2, @v3;
     +------+------+------+
     | @v1  | @v2  | @v3  |
     +------+------+------+
     | a    |   97 |   97 |
     +------+------+------+

An empty bit value ('b''') evaluates to a zero-length binary string.
Converted to a number, it produces 0:

     mysql> SELECT CHARSET(b''), LENGTH(b'');
     +--------------+-------------+
     | CHARSET(b'') | LENGTH(b'') |
     +--------------+-------------+
     | binary       |           0 |
     +--------------+-------------+
     mysql> SELECT b''+0;
     +-------+
     | b''+0 |
     +-------+
     |     0 |
     +-------+

Bit-value notation is convenient for specifying values to be assigned to
'BIT' columns:

     mysql> CREATE TABLE t (b BIT(8));
     mysql> INSERT INTO t SET b = b'11111111';
     mysql> INSERT INTO t SET b = b'1010';
     mysql> INSERT INTO t SET b = b'0101';

Bit values in result sets are returned as binary values, which may not
display well.  To convert a bit value to printable form, use it in
numeric context or use a conversion function such as 'BIN()' or 'HEX()'.
High-order 0 digits are not displayed in the converted value.

     mysql> SELECT b+0, BIN(b), OCT(b), HEX(b) FROM t;
     +------+----------+--------+--------+
     | b+0  | BIN(b)   | OCT(b) | HEX(b) |
     +------+----------+--------+--------+
     |  255 | 11111111 | 377    | FF     |
     |   10 | 1010     | 12     | A      |
     |    5 | 101      | 5      | 5      |
     +------+----------+--------+--------+

9.1.6 Boolean Literals
----------------------

The constants 'TRUE' and 'FALSE' evaluate to '1' and '0', respectively.
The constant names can be written in any lettercase.

     mysql> SELECT TRUE, true, FALSE, false;
             -> 1, 1, 0, 0

9.1.7 NULL Values
-----------------

The 'NULL' value means 'no data.'  'NULL' can be written in any
lettercase.  A synonym is '\N' (case-sensitive).  Treatment of '\N' as a
synonym for 'NULL' in SQL statements is deprecated as of MySQL 5.7.18
and is removed in MySQL 8.0; use 'NULL' instead.

Be aware that the 'NULL' value is different from values such as '0' for
numeric types or the empty string for string types.  For more
information, see problems-with-null.

For text file import or export operations performed with 'LOAD DATA INFILE'
or 'SELECT ... INTO OUTFILE',
'NULL' is represented by the '\N' sequence.  See
load-data.  Use of '\N' in text files is unaffected by the deprecation
of '\N' in SQL statements.

For sorting with 'ORDER BY', 'NULL' values sort before other values for
ascending sorts, after other values for descending sorts.

9.2 Schema Object Names
=======================

Certain objects within MySQL, including database, table, index, column,
alias, view, stored procedure, partition, tablespace, and other object
names are known as identifiers.  This section describes the permissible
syntax for identifiers in MySQL. See identifier-case-sensitivity,
describes which types of identifiers are case-sensitive and under what
conditions.

An identifier may be quoted or unquoted.  If an identifier contains
special characters or is a reserved word, you _must_ quote it whenever
you refer to it.  (Exception: A reserved word that follows a period in a
qualified name must be an identifier, so it need not be quoted.)
Reserved words are listed at keywords.

Identifiers are converted to Unicode internally.  They may contain these
characters:

   * Permitted characters in unquoted identifiers:

        * ASCII: [0-9,a-z,A-Z$_] (basic Latin letters, digits 0-9,
          dollar, underscore)

        * Extended: U+0080 ..  U+FFFF

   * Permitted characters in quoted identifiers include the full Unicode
     Basic Multilingual Plane (BMP), except U+0000:

        * ASCII: U+0001 ..  U+007F

        * Extended: U+0080 ..  U+FFFF

   * ASCII NUL (U+0000) and supplementary characters (U+10000 and
     higher) are not permitted in quoted or unquoted identifiers.

   * Identifiers may begin with a digit but unless quoted may not
     consist solely of digits.

   * Database, table, and column names cannot end with space characters.

The identifier quote character is the backtick ('`'):

     mysql> SELECT * FROM `select` WHERE `select`.id > 100;

If the 'ANSI_QUOTES' SQL mode is enabled, it is also permissible to
quote identifiers within double quotation marks:

     mysql> CREATE TABLE "test" (col INT);
     ERROR 1064: You have an error in your SQL syntax...
     mysql> SET sql_mode='ANSI_QUOTES';
     mysql> CREATE TABLE "test" (col INT);
     Query OK, 0 rows affected (0.00 sec)

The 'ANSI_QUOTES' mode causes the server to interpret double-quoted
strings as identifiers.  Consequently, when this mode is enabled, string
literals must be enclosed within single quotation marks.  They cannot be
enclosed within double quotation marks.  The server SQL mode is
controlled as described in sql-mode.

Identifier quote characters can be included within an identifier if you
quote the identifier.  If the character to be included within the
identifier is the same as that used to quote the identifier itself, then
you need to double the character.  The following statement creates a
table named 'a`b' that contains a column named 'c"d':

     mysql> CREATE TABLE `a``b` (`c"d` INT);

In the select list of a query, a quoted column alias can be specified
using identifier or string quoting characters:

     mysql> SELECT 1 AS `one`, 2 AS 'two';
     +-----+-----+
     | one | two |
     +-----+-----+
     |   1 |   2 |
     +-----+-----+

Elsewhere in the statement, quoted references to the alias must use
identifier quoting or the reference is treated as a string literal.

It is recommended that you do not use names that begin with 'Me' or
'MeN', where M and N are integers.  For example, avoid using '1e' as an
identifier, because an expression such as '1e+3' is ambiguous.
Depending on context, it might be interpreted as the expression '1e + 3'
or as the number '1e+3'.

Be careful when using 'MD5()' to produce table names because it can
produce names in illegal or ambiguous formats such as those just
described.

A user variable cannot be used directly in an SQL statement as an
identifier or as part of an identifier.  See user-variables, for
more information and examples of workarounds.

Special characters in database and table names are encoded in the
corresponding file system names as described in
identifier-mapping.  If you have databases or tables from an older
version of MySQL that contain special characters and for which the
underlying directory names or file names have not been updated to use
the new encoding, the server displays their names with a prefix of
'#mysql50#'.  For information about referring to such names or
converting them to the newer encoding, see that section.

The following table describes the maximum length for each type of
identifier.

Identifier  Maximum
Type        Length
            (characters)

Database

64 (see
'NDB'.
storage
engine:
63)

Table

64 (see
'NDB'.
storage
engine:
63)

Column

64

Index

64

Constraint

64

Stored
Program

64

View

64

Tablespace

64

Server

64

Log File
Group

64

Alias

256 (see
exception
following
table)

Compound
Statement
Label

16

User-Defined
Variable

64

Aliases for column names in 'CREATE VIEW' statements
are checked against the maximum column length of 64 characters (not the
maximum alias length of 256 characters).

Identifiers are stored using Unicode (UTF-8).  This applies to
identifiers in table definitions that are stored in '.frm' files and to
identifiers stored in the grant tables in the 'mysql' database.  The
sizes of the identifier string columns in the grant tables are measured
in characters.  You can use multibyte characters without reducing the
number of characters permitted for values stored in these columns.  As
indicated earlier, the permissible Unicode characters are those in the
Basic Multilingual Plane (BMP). Supplementary characters are not
permitted.

NDB Cluster imposes a maximum length of 63 characters for names of
databases and tables.  See
mysql-cluster-limitations-database-objects.

9.2.1 Identifier Qualifiers
---------------------------

Object names may be unqualified or qualified.  An unqualified name is
permitted in contexts where interpretation of the name is unambiguous.
A qualified name includes at least one qualifier to clarify the
interpretive context by overriding a default context or providing
missing context.

For example, this statement creates a table using the unqualified name
't1':

     CREATE TABLE t1 (i INT);

Because 't1' includes no qualifier to specify a database, the statement
creates the table in the default database.  If there is no default
database, an error occurs.

This statement creates a table using the qualified name 'db1.t1':

     CREATE TABLE db1.t1 (i INT);

Because 'db1.t1' includes a database qualifier 'db1', the statement
creates 't1' in the database named 'db1', regardless of the default
database.  The qualifier _must_ be specified if there is no default
database.  The qualifier _may_ be specified if there is a default
database, to specify a database different from the default, or to make
the database explicit if the default is the same as the one specified.

Qualifiers have these characteristics:

   * An unqualified name consists of a single identifier.  A qualified
     name consists of multiple identifiers.

   * The components of a multiple-part name must be separated by period
     ('.') characters.  The initial parts of a multiple-part name act as
     qualifiers that affect the context within which to interpret the
     final identifier.

   * The qualifier character is a separate token and need not be
     contiguous with the associated identifiers.  For example,
     TBL_NAME.COL_NAME and TBL_NAME . COL_NAME are equivalent.

   * If any components of a multiple-part name require quoting, quote
     them individually rather than quoting the name as a whole.  For
     example, write '`my-table`.`my-column`', not
     '`my-table.my-column`'.

   * A reserved word that follows a period in a qualified name must be
     an identifier, so in that context it need not be quoted.

   * The syntax '.TBL_NAME' means the table TBL_NAME in the default
     database.

     *Note*:

     This syntax is deprecated as of MySQL 5.7.20 and will be removed in
     a future version of MySQL.

The permitted qualifiers for object names depend on the object type:

   * A database name is fully qualified and takes no qualifier:

          CREATE DATABASE db1;

   * A table, view, or stored program name may be given a database-name
     qualifier.  Examples of unqualified and qualified names in 'CREATE'
     statements:

          CREATE TABLE mytable ...;
          CREATE VIEW myview ...;
          CREATE PROCEDURE myproc ...;
          CREATE FUNCTION myfunc ...;
          CREATE EVENT myevent ...;

          CREATE TABLE mydb.mytable ...;
          CREATE VIEW mydb.myview ...;
          CREATE PROCEDURE mydb.myproc ...;
          CREATE FUNCTION mydb.myfunc ...;
          CREATE EVENT mydb.myevent ...;

   * A trigger is associated with a table, so any qualifier applies to
     the table name:

          CREATE TRIGGER mytrigger ... ON mytable ...;

          CREATE TRIGGER mytrigger ... ON mydb.mytable ...;

   * A column name may be given multiple qualifiers to indicate context
     in statements that reference it, as shown in the following table.

     Column Reference          Meaning

     COL_NAME                  Column COL_NAME from whichever table used in
                               the statement contains a column of that name

     TBL_NAME.COL_NAME         Column COL_NAME from table TBL_NAME of the
                               default database

     DB_NAME.TBL_NAME.COL_NAME Column COL_NAME from table TBL_NAME of the
                               database DB_NAME

     In other words, a column name may be given a table-name qualifier,
     which itself may be given a database-name qualifier.  Examples of
     unqualified and qualified column references in 'SELECT' statements:

          SELECT c1 FROM mytable
          WHERE c2 > 100;

          SELECT mytable.c1 FROM mytable
          WHERE mytable.c2 > 100;

          SELECT mydb.mytable.c1 FROM mydb.mytable
          WHERE mydb.mytable.c2 > 100;

You need not specify a qualifier for an object reference in a statement
unless the unqualified reference is ambiguous.  Suppose that column 'c1'
occurs only in table 't1', 'c2' only in 't2', and 'c' in both 't1' and
't2'.  Any unqualified reference to 'c' is ambiguous in a statement that
refers to both tables and must be qualified as 't1.c' or 't2.c' to
indicate which table you mean:

     SELECT c1, c2, t1.c FROM t1 INNER JOIN t2
     WHERE t2.c > 100;

Similarly, to retrieve from a table 't' in database 'db1' and from a
table 't' in database 'db2' in the same statement, you must qualify the
table references: For references to columns in those tables, qualifiers
are required only for column names that appear in both tables.  Suppose
that column 'c1' occurs only in table 'db1.t', 'c2' only in 'db2.t', and
'c' in both 'db1.t' and 'db2.t'.  In this case, 'c' is ambiguous and
must be qualified but 'c1' and 'c2' need not be:

     SELECT c1, c2, db1.t.c FROM db1.t INNER JOIN db2.t
     WHERE db2.t.c > 100;

Table aliases enable qualified column references to be written more
simply:

     SELECT c1, c2, t1.c FROM db1.t AS t1 INNER JOIN db2.t AS t2
     WHERE t2.c > 100;

9.2.2 Identifier Case Sensitivity
---------------------------------

In MySQL, databases correspond to directories within the data directory.
Each table within a database corresponds to at least one file within the
database directory (and possibly more, depending on the storage engine).
Triggers also correspond to files.  Consequently, the case sensitivity
of the underlying operating system plays a part in the case sensitivity
of database, table, and trigger names.  This means such names are not
case-sensitive in Windows, but are case-sensitive in most varieties of
Unix.  One notable exception is OS X, which is Unix-based but uses a
default file system type (HFS+) that is not case-sensitive.  However, OS
X also supports UFS volumes, which are case-sensitive just as on any
Unix.  See extensions-to-ansi.  The 'lower_case_table_names'
system variable also affects how the server handles identifier case
sensitivity, as described later in this section.

*Note*:

Although database, table, and trigger names are not case sensitive on
some platforms, you should not refer to one of these using different
cases within the same statement.  The following statement would not work
because it refers to a table both as 'my_table' and as 'MY_TABLE':

     mysql> SELECT * FROM my_table WHERE MY_TABLE.col=1;

Column, index, stored routine, and event names are not case sensitive on
any platform, nor are column aliases.

However, names of logfile groups are case-sensitive.  This differs from
standard SQL.

By default, table aliases are case-sensitive on Unix, but not so on
Windows or OS X. The following statement would not work on Unix, because
it refers to the alias both as 'a' and as 'A':

     mysql> SELECT COL_NAME FROM TBL_NAME AS a
         -> WHERE a.COL_NAME = 1 OR A.COL_NAME = 2;

However, this same statement is permitted on Windows.  To avoid problems
caused by such differences, it is best to adopt a consistent convention,
such as always creating and referring to databases and tables using
lowercase names.  This convention is recommended for maximum portability
and ease of use.

How table and database names are stored on disk and used in MySQL is
affected by the 'lower_case_table_names' system variable, which you can
set when starting 'mysqld'.  'lower_case_table_names' can
take the values shown in the following table.  This variable does _not_
affect case sensitivity of trigger identifiers.  On Unix, the default
value of 'lower_case_table_names' is 0.  On Windows, the default value
is 1.  On OS X, the default value is 2.

Value   Meaning

'0'     Table and database names are stored on disk using the
        lettercase specified in the 'CREATE TABLE'.
        or 'CREATE DATABASE' statement.  Name
        comparisons are case sensitive.  You should _not_ set this
        variable to 0 if you are running MySQL on a system that has
        case-insensitive file names (such as Windows or OS X). If you
        force this variable to 0 with '--lower-case-table-names=0' on a
        case-insensitive file system and access 'MyISAM' tablenames
        using different lettercases, index corruption may result.

'1'     Table names are stored in lowercase on disk and name
        comparisons are not case-sensitive.  MySQL converts all table
        names to lowercase on storage and lookup.  This behavior also
        applies to database names and table aliases.

'2'     Table and database names are stored on disk using the
        lettercase specified in the 'CREATE TABLE'.
        or 'CREATE DATABASE' statement, but
        MySQL converts them to lowercase on lookup.  Name comparisons
        are not case sensitive.  This works _only_ on file systems that
        are not case-sensitive!  'InnoDB' table names are stored in
        lowercase, as for 'lower_case_table_names=1'.

If you are using MySQL on only one platform, you do not normally have to
change the 'lower_case_table_names' variable from its default value.
However, you may encounter difficulties if you want to transfer tables
between platforms that differ in file system case sensitivity.  For
example, on Unix, you can have two different tables named 'my_table' and
'MY_TABLE', but on Windows these two names are considered identical.  To
avoid data transfer problems arising from lettercase of database or
table names, you have two options:

   * Use 'lower_case_table_names=1' on all systems.  The main
     disadvantage with this is that when you use 'SHOW TABLES'
     or 'SHOW DATABASES', you do not
     see the names in their original lettercase.

   * Use 'lower_case_table_names=0' on Unix and
     'lower_case_table_names=2' on Windows.  This preserves the
     lettercase of database and table names.  The disadvantage of this
     is that you must ensure that your statements always refer to your
     database and table names with the correct lettercase on Windows.
     If you transfer your statements to Unix, where lettercase is
     significant, they do not work if the lettercase is incorrect.

     *Exception*: If you are using 'InnoDB' tables and you are trying to
     avoid these data transfer problems, you should set
     'lower_case_table_names' to 1 on all platforms to force names to be
     converted to lowercase.

If you plan to set the 'lower_case_table_names' system variable to 1 on
Unix, you must first convert your old database and table names to
lowercase before stopping 'mysqld' and restarting it with
the new variable setting.  To do this for an individual table, use
'RENAME TABLE'.:

     RENAME TABLE T1 TO t1;

To convert one or more entire databases, dump them before setting
'lower_case_table_names', then drop the databases, and reload them after
setting 'lower_case_table_names':

  1. Use 'mysqldump' to dump each database:

          mysqldump --databases db1 > db1.sql
          mysqldump --databases db2 > db2.sql
          ...

     Do this for each database that must be recreated.

  2. Use 'DROP DATABASE' to drop each database.

  3. Stop the server, set 'lower_case_table_names', and restart the
     server.

  4. Reload the dump file for each database.  Because
     'lower_case_table_names' is set, each database and table name will
     be converted to lowercase as it is recreated:

          mysql < db1.sql
          mysql < db2.sql
          ...

Object names may be considered duplicates if their uppercase forms are
equal according to a binary collation.  That is true for names of
cursors, conditions, procedures, functions, savepoints, stored routine
parameters, stored program local variables, and plugins.  It is not true
for names of columns, constraints, databases, partitions, statements
prepared with 'PREPARE', tables, triggers, users, and
user-defined variables.

File system case sensitivity can affect searches in string columns of
'INFORMATION_SCHEMA' tables.  For more information, see
charset-collation-information-schema.

9.2.3 Mapping of Identifiers to File Names
------------------------------------------

There is a correspondence between database and table identifiers and
names in the file system.  For the basic structure, MySQL represents
each database as a directory in the data directory, and each table by
one or more files in the appropriate database directory.  For the table
format files ('.FRM'), the data is always stored in this structure and
location.

For the data and index files, the exact representation on disk is
storage engine specific.  These files may be stored in the same location
as the 'FRM' files, or the information may be stored in a separate file.
'InnoDB' data is stored in the InnoDB data files.  If you are using
tablespaces with 'InnoDB', then the specific tablespace files you create
are used instead.

Any character is legal in database or table identifiers except ASCII NUL
('X'00'').  MySQL encodes any characters that are problematic in the
corresponding file system objects when it creates database directories
or table files:

   * Basic Latin letters ('a..zA..Z'), digits ('0..9') and underscore
     ('_') are encoded as is.  Consequently, their case sensitivity
     directly depends on file system features.

   * All other national letters from alphabets that have
     uppercase/lowercase mapping are encoded as shown in the following
     table.  Values in the Code Range column are UCS-2 values.

     Code        Pattern     Number      Used        Unused      Blocks
     Range

     00C0..017F  [@][0..4][g..z]5*20= 10097          3           Latin-1
                                                                 Supplement +
                                                                 Latin Extended-A

     0370..03FF  [@][5..9][g..z]5*20= 10088          12          Greek and Coptic

     0400..052F  [@][g..z][0..6]20*7= 140137         3           Cyrillic +
                                                                 Cyrillic
                                                                 Supplement

     0530..058F  [@][g..z][7..8]20*2= 40 38          2           Armenian

     2160..217F  [@][g..z][9]20*1= 20    16          4           Number Forms

     0180..02AF  [@][g..z][a..k]20*11=220203         17          Latin Extended-B
                                                                 + IPA Extensions

     1E00..1EFF  [@][g..z][l..r]20*7= 140136         4           Latin Extended
                                                                 Additional

     1F00..1FFF  [@][g..z][s..z]20*8= 160144         16          Greek Extended

     ....        [@][a..f][g..z]6*20= 1200           120         RESERVED
     ....

     24B6..24E9  [@][@][a..z]26          26          0           Enclosed
                                                                 Alphanumerics

     FF21..FF5A  [@][a..z][@]26          26          0           Halfwidth and
                                                                 Fullwidth forms

     One of the bytes in the sequence encodes lettercase.  For example:
     'LATIN CAPITAL LETTER A WITH GRAVE' is encoded as '@0G', whereas
     'LATIN SMALL LETTER A WITH GRAVE' is encoded as '@0g'.  Here the
     third byte ('G' or 'g') indicates lettercase.  (On a
     case-insensitive file system, both letters will be treated as the
     same.)

     For some blocks, such as Cyrillic, the second byte determines
     lettercase.  For other blocks, such as Latin1 Supplement, the third
     byte determines lettercase.  If two bytes in the sequence are
     letters (as in Greek Extended), the leftmost letter character
     stands for lettercase.  All other letter bytes must be in
     lowercase.

   * All nonletter characters except underscore ('_'), as well as
     letters from alphabets that do not have uppercase/lowercase mapping
     (such as Hebrew) are encoded using hexadecimal representation using
     lowercase letters for hexadecimal digits 'a..f':

          0x003F -> @003f
          0xFFFF -> @ffff

     The hexadecimal values correspond to character values in the 'ucs2'
     double-byte character set.

On Windows, some names such as 'nul', 'prn', and 'aux' are encoded by
appending '@@@' to the name when the server creates the corresponding
file or directory.  This occurs on all platforms for portability of the
corresponding database object between platforms.

If you have databases or tables from a version of MySQL older than 5.1.6
that contain special characters and for which the underlying directory
names or file names have not been updated to use the new encoding, the
server displays their names with a prefix of '#mysql50#' in the output
from 'INFORMATION_SCHEMA' tables or 'SHOW' statements.  For
example, if you have a table named 'a@b' and its name encoding has not
been updated, see 'SHOW TABLES' displays it like this:

     mysql> SHOW TABLES;
     +----------------+
     | Tables_in_test |
     +----------------+
     | #mysql50#a@b   |
     +----------------+

To refer to such a name for which the encoding has not been updated, you
must supply the '#mysql50#' prefix:

     mysql> SHOW COLUMNS FROM `a@b`;
     ERROR 1146 (42S02): Table 'test.a@b' doesn't exist

     mysql> SHOW COLUMNS FROM `#mysql50#a@b`;
     +-------+---------+------+-----+---------+-------+
     | Field | Type    | Null | Key | Default | Extra |
     +-------+---------+------+-----+---------+-------+
     | i     | int(11) | YES  |     | NULL    |       |
     +-------+---------+------+-----+---------+-------+

To update old names to eliminate the need to use the special prefix to
refer to them, re-encode them with 'mysqlcheck'.  The
following commands update all names to the new encoding:

     mysqlcheck --check-upgrade --all-databases
     mysqlcheck --fix-db-names --fix-table-names --all-databases

To check only specific databases or tables, omit '--all-databases' and
provide the appropriate database or table arguments.  For information
about 'mysqlcheck' invocation syntax, see
mysqlcheck.

*Note*:

The '#mysql50#' prefix is intended only to be used internally by the
server.  You should not create databases or tables with names that use
this prefix.

Also, see 'mysqlcheck' cannot fix names that contain
literal instances of the '@' character that is used for encoding special
characters.  If you have databases or tables that contain this
character, use 'mysqldump' to dump them before
upgrading to MySQL 5.1.6 or later, and then reload the dump file after
upgrading.

*Note*:

Conversion of pre-MySQL 5.1 database names containing special characters
to 5.1 format with the addition of a '#mysql50#' prefix is deprecated
and will be removed in a future version of MySQL. Because such
conversions are deprecated, the '--fix-db-names' and '--fix-table-names'
options for 'mysqlcheck' and the 'UPGRADE DATA
DIRECTORY NAME' clause for the 'ALTER DATABASE'.
statement are also deprecated.

Upgrades are supported only from one release series to another (for
example, 5.0 to 5.1, or 5.1 to 5.5), so there should be little remaining
need for conversion of older 5.0 database names to current versions of
MySQL. As a workaround, upgrade a MySQL 5.0 installation to MySQL 5.1
before upgrading to a more recent release.

9.2.4 Function Name Parsing and Resolution
------------------------------------------

MySQL supports built-in (native) functions, user-defined functions
(UDFs), and stored functions.  This section describes how the server
recognizes whether the name of a built-in function is used as a function
call or as an identifier, and how the server determines which function
to use in cases when functions of different types exist with a given
name.

   * function-name-parsing

   * function-name-resolution

*Built-In Function Name Parsing*

The parser uses default rules for parsing names of built-in functions.
These rules can be changed by enabling the 'IGNORE_SPACE' SQL mode.

When the parser encounters a word that is the name of a built-in
function, it must determine whether the name signifies a function call
or is instead a nonexpression reference to an identifier such as a table
or column name.  For example, in the following statements, the first
reference to 'count' is a function call, whereas the second reference is
a table name:

     SELECT COUNT(*) FROM mytable;
     CREATE TABLE count (i INT);

The parser should recognize the name of a built-in function as
indicating a function call only when parsing what is expected to be an
expression.  That is, in nonexpression context, function names are
permitted as identifiers.

However, some built-in functions have special parsing or implementation
considerations, so the parser uses the following rules by default to
distinguish whether their names are being used as function calls or as
identifiers in nonexpression context:

   * To use the name as a function call in an expression, there must be
     no whitespace between the name and the following '(' parenthesis
     character.

   * Conversely, to use the function name as an identifier, it must not
     be followed immediately by a parenthesis.

The requirement that function calls be written with no whitespace
between the name and the parenthesis applies only to the built-in
functions that have special considerations.  'COUNT' is one such name.
The 'sql/lex.h' source file lists the names of these special functions
for which following whitespace determines their interpretation: names
defined by the 'SYM_FN()' macro in the 'symbols[]' array.

In MySQL 5.7, there are about 30 such function names.  You may find it
easiest to treat the no-whitespace requirement as applying to all
function calls.

The following list names the functions that are affected by the
'IGNORE_SPACE' setting and listed as special in the 'sql/lex.h' source
file.

   * 'ADDDATE'

   * 'BIT_AND'

   * 'BIT_OR'

   * 'BIT_XOR'

   * 'CAST'

   * 'COUNT'

   * 'CURDATE'

   * 'CURTIME'

   * 'DATE_ADD'

   * 'DATE_SUB'

   * 'EXTRACT'

   * 'GROUP_CONCAT'

   * 'MAX'

   * 'MID'

   * 'MIN'

   * 'NOW'

   * 'POSITION'

   * 'SESSION_USER'

   * 'STD'

   * 'STDDEV'

   * 'STDDEV_POP'

   * 'STDDEV_SAMP'

   * 'SUBDATE'

   * 'SUBSTR'

   * 'SUBSTRING'

   * 'SUM'

   * 'SYSDATE'

   * 'SYSTEM_USER'

   * 'TRIM'

   * 'VARIANCE'

   * 'VAR_POP'

   * 'VAR_SAMP'

For functions not listed as special in 'sql/lex.h', whitespace does not
matter.  They are interpreted as function calls only when used in
expression context and may be used freely as identifiers otherwise.
'ASCII' is one such name.  However, for these nonaffected function
names, interpretation may vary in expression context: 'FUNC_NAME ()' is
interpreted as a built-in function if there is one with the given name;
if not, 'FUNC_NAME ()' is interpreted as a user-defined function or
stored function if one exists with that name.

The 'IGNORE_SPACE' SQL mode can be used to modify how the parser treats
function names that are whitespace-sensitive:

   * With 'IGNORE_SPACE' disabled, the parser interprets the name as a
     function call when there is no whitespace between the name and the
     following parenthesis.  This occurs even when the function name is
     used in nonexpression context:

          mysql> CREATE TABLE count(i INT);
          ERROR 1064 (42000): You have an error in your SQL syntax ...
          near 'count(i INT)'

     To eliminate the error and cause the name to be treated as an
     identifier, either use whitespace following the name or write it as
     a quoted identifier (or both):

          CREATE TABLE count (i INT);
          CREATE TABLE `count`(i INT);
          CREATE TABLE `count` (i INT);

   * With 'IGNORE_SPACE' enabled, the parser loosens the requirement
     that there be no whitespace between the function name and the
     following parenthesis.  This provides more flexibility in writing
     function calls.  For example, either of the following function
     calls are legal:

          SELECT COUNT(*) FROM mytable;
          SELECT COUNT (*) FROM mytable;

     However, enabling 'IGNORE_SPACE' also has the side effect that the
     parser treats the affected function names as reserved words (see
     keywords).  This means that a space following the name no
     longer signifies its use as an identifier.  The name can be used in
     function calls with or without following whitespace, but causes a
     syntax error in nonexpression context unless it is quoted.  For
     example, with 'IGNORE_SPACE' enabled, both of the following
     statements fail with a syntax error because the parser interprets
     'count' as a reserved word:

          CREATE TABLE count(i INT);
          CREATE TABLE count (i INT);

     To use the function name in nonexpression context, write it as a
     quoted identifier:

          CREATE TABLE `count`(i INT);
          CREATE TABLE `count` (i INT);

To enable the 'IGNORE_SPACE' SQL mode, use this statement:

     SET sql_mode = 'IGNORE_SPACE';

'IGNORE_SPACE' is also enabled by certain other composite modes such as
'ANSI' that include it in their value:

     SET sql_mode = 'ANSI';

Check sql-mode, to see which composite modes enable
'IGNORE_SPACE'.

To minimize the dependency of SQL code on the 'IGNORE_SPACE' setting,
use these guidelines:

   * Avoid creating UDFs or stored functions that have the same name as
     a built-in function.

   * Avoid using function names in nonexpression context.  For example,
     these statements use 'count' (one of the affected function names
     affected by 'IGNORE_SPACE'), so they fail with or without
     whitespace following the name if 'IGNORE_SPACE' is enabled:

          CREATE TABLE count(i INT);
          CREATE TABLE count (i INT);

     If you must use a function name in nonexpression context, write it
     as a quoted identifier:

          CREATE TABLE `count`(i INT);
          CREATE TABLE `count` (i INT);

*Function Name Resolution*

The following rules describe how the server resolves references to
function names for function creation and invocation:

   * Built-in functions and user-defined functions

     An error occurs if you try to create a UDF with the same name as a
     built-in function.

   * Built-in functions and stored functions

     It is possible to create a stored function with the same name as a
     built-in function, but to invoke the stored function it is
     necessary to qualify it with a schema name.  For example, if you
     create a stored function named 'PI' in the 'test' schema, invoke it
     as 'test.PI()' because the server resolves 'PI()' without a
     qualifier as a reference to the built-in function.  The server
     generates a warning if the stored function name collides with a
     built-in function name.  The warning can be displayed with
     'SHOW WARNINGS'.

   * User-defined functions and stored functions

     User-defined functions and stored functions share the same
     namespace, so you cannot create a UDF and a stored function with
     the same name.

The preceding function name resolution rules have implications for
upgrading to versions of MySQL that implement new built-in functions:

   * If you have already created a user-defined function with a given
     name and upgrade MySQL to a version that implements a new built-in
     function with the same name, the UDF becomes inaccessible.  To
     correct this, use 'DROP FUNCTION' to drop the
     UDF and 'CREATE FUNCTION' to re-create the
     UDF with a different nonconflicting name.  Then modify any affected
     code to use the new name.

   * If a new version of MySQL implements a built-in function with the
     same name as an existing stored function, you have two choices:
     Rename the stored function to use a nonconflicting name, or change
     calls to the function so that they use a schema qualifier (that is,
     use 'SCHEMA_NAME.FUNC_NAME()' syntax).  In either case, modify any
     affected code accordingly.

9.3 Keywords and Reserved Words
===============================

Keywords are words that have significance in SQL. Certain keywords, such
as 'SELECT', 'DELETE', or 'BIGINT',
are reserved and require special treatment for use as
identifiers such as table and column names.  This may also be true for
the names of built-in functions.

Nonreserved keywords are permitted as identifiers without quoting.
Reserved words are permitted as identifiers if you quote them as
described in identifiers:

     mysql> CREATE TABLE interval (begin INT, end INT);
     ERROR 1064 (42000): You have an error in your SQL syntax ...
     near 'interval (begin INT, end INT)'

'BEGIN' and 'END' are keywords but not reserved, so their use as
identifiers does not require quoting.  'INTERVAL' is a reserved keyword
and must be quoted to be used as an identifier:

     mysql> CREATE TABLE `interval` (begin INT, end INT);
     Query OK, 0 rows affected (0.01 sec)

Exception: A word that follows a period in a qualified name must be an
identifier, so it need not be quoted even if it is reserved:

     mysql> CREATE TABLE mydb.interval (begin INT, end INT);
     Query OK, 0 rows affected (0.01 sec)

Names of built-in functions are permitted as identifiers but may require
care to be used as such.  For example, 'COUNT' is acceptable as a column
name.  However, by default, no whitespace is permitted in function
invocations between the function name and the following '(' character.
This requirement enables the parser to distinguish whether the name is
used in a function call or in nonfunction context.  For further details
on recognition of function names, see function-resolution.

   * keywords-in-current-series

   * keywords-new-in-current-series

   * keywords-removed-in-current-series

*MySQL 5.7 Keywords and Reserved Words*

The following list shows the keywords and reserved words in MySQL 5.7,
along with changes to individual words from version to version.
Reserved keywords are marked with (R). In addition, '_FILENAME' is
reserved.

At some point, you might upgrade to a higher version, so it is a good
idea to have a look at future reserved words, too.  You can find these
in the manuals that cover higher versions of MySQL. Most of the reserved
words in the list are forbidden by standard SQL as column or table names
(for example, 'GROUP').  A few are reserved because MySQL needs them and
uses a 'yacc' parser.

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R |
S | T | U | V | W | X | Y | Z

A

   * 'ACCESSIBLE' (R)

   * 'ACCOUNT' added in 5.7.6 (nonreserved)

   * 'ACTION'

   * 'ADD' (R)

   * 'AFTER'

   * 'AGAINST'

   * 'AGGREGATE'

   * 'ALGORITHM'

   * 'ALL' (R)

   * 'ALTER' (R)

   * 'ALWAYS' added in 5.7.6 (nonreserved)

   * 'ANALYSE'

   * 'ANALYZE' (R)

   * 'AND' (R)

   * 'ANY'

   * 'AS' (R)

   * 'ASC' (R)

   * 'ASCII'

   * 'ASENSITIVE' (R)

   * 'AT'

   * 'AUTOEXTEND_SIZE'

   * 'AUTO_INCREMENT'

   * 'AVG'

   * 'AVG_ROW_LENGTH'

B

   * 'BACKUP'

   * 'BEFORE' (R)

   * 'BEGIN'

   * 'BETWEEN' (R)

   * 'BIGINT' (R)

   * 'BINARY' (R)

   * 'BINLOG'

   * 'BIT'

   * 'BLOB' (R)

   * 'BLOCK'

   * 'BOOL'

   * 'BOOLEAN'

   * 'BOTH' (R)

   * 'BTREE'

   * 'BY' (R)

   * 'BYTE'

C

   * 'CACHE'

   * 'CALL' (R)

   * 'CASCADE' (R)

   * 'CASCADED'

   * 'CASE' (R)

   * 'CATALOG_NAME'

   * 'CHAIN'

   * 'CHANGE' (R)

   * 'CHANGED'

   * 'CHANNEL' added in 5.7.6 (nonreserved)

   * 'CHAR' (R)

   * 'CHARACTER' (R)

   * 'CHARSET'

   * 'CHECK' (R)

   * 'CHECKSUM'

   * 'CIPHER'

   * 'CLASS_ORIGIN'

   * 'CLIENT'

   * 'CLOSE'

   * 'COALESCE'

   * 'CODE'

   * 'COLLATE' (R)

   * 'COLLATION'

   * 'COLUMN' (R)

   * 'COLUMNS'

   * 'COLUMN_FORMAT'

   * 'COLUMN_NAME'

   * 'COMMENT'

   * 'COMMIT'

   * 'COMMITTED'

   * 'COMPACT'

   * 'COMPLETION'

   * 'COMPRESSED'

   * 'COMPRESSION' added in 5.7.8 (nonreserved)

   * 'CONCURRENT'

   * 'CONDITION' (R)

   * 'CONNECTION'

   * 'CONSISTENT'

   * 'CONSTRAINT' (R)

   * 'CONSTRAINT_CATALOG'

   * 'CONSTRAINT_NAME'

   * 'CONSTRAINT_SCHEMA'

   * 'CONTAINS'

   * 'CONTEXT'

   * 'CONTINUE' (R)

   * 'CONVERT' (R)

   * 'CPU'

   * 'CREATE' (R)

   * 'CROSS' (R)

   * 'CUBE'

   * 'CURRENT'

   * 'CURRENT_DATE' (R)

   * 'CURRENT_TIME' (R)

   * 'CURRENT_TIMESTAMP' (R)

   * 'CURRENT_USER' (R)

   * 'CURSOR' (R)

   * 'CURSOR_NAME'

D

   * 'DATA'

   * 'DATABASE' (R)

   * 'DATABASES' (R)

   * 'DATAFILE'

   * 'DATE'

   * 'DATETIME'

   * 'DAY'

   * 'DAY_HOUR' (R)

   * 'DAY_MICROSECOND' (R)

   * 'DAY_MINUTE' (R)

   * 'DAY_SECOND' (R)

   * 'DEALLOCATE'

   * 'DEC' (R)

   * 'DECIMAL' (R)

   * 'DECLARE' (R)

   * 'DEFAULT' (R)

   * 'DEFAULT_AUTH'

   * 'DEFINER'

   * 'DELAYED' (R)

   * 'DELAY_KEY_WRITE'

   * 'DELETE' (R)

   * 'DESC' (R)

   * 'DESCRIBE' (R)

   * 'DES_KEY_FILE'

   * 'DETERMINISTIC' (R)

   * 'DIAGNOSTICS'

   * 'DIRECTORY'

   * 'DISABLE'

   * 'DISCARD'

   * 'DISK'

   * 'DISTINCT' (R)

   * 'DISTINCTROW' (R)

   * 'DIV' (R)

   * 'DO'

   * 'DOUBLE' (R)

   * 'DROP' (R)

   * 'DUAL' (R)

   * 'DUMPFILE'

   * 'DUPLICATE'

   * 'DYNAMIC'

E

   * 'EACH' (R)

   * 'ELSE' (R)

   * 'ELSEIF' (R)

   * 'ENABLE'

   * 'ENCLOSED' (R)

   * 'ENCRYPTION' added in 5.7.11 (nonreserved)

   * 'END'

   * 'ENDS'

   * 'ENGINE'

   * 'ENGINES'

   * 'ENUM'

   * 'ERROR'

   * 'ERRORS'

   * 'ESCAPE'

   * 'ESCAPED' (R)

   * 'EVENT'

   * 'EVENTS'

   * 'EVERY'

   * 'EXCHANGE'

   * 'EXECUTE'

   * 'EXISTS' (R)

   * 'EXIT' (R)

   * 'EXPANSION'

   * 'EXPIRE'

   * 'EXPLAIN' (R)

   * 'EXPORT'

   * 'EXTENDED'

   * 'EXTENT_SIZE'

F

   * 'FALSE' (R)

   * 'FAST'

   * 'FAULTS'

   * 'FETCH' (R)

   * 'FIELDS'

   * 'FILE'

   * 'FILE_BLOCK_SIZE' added in 5.7.6 (nonreserved)

   * 'FILTER' added in 5.7.3 (nonreserved)

   * 'FIRST'

   * 'FIXED'

   * 'FLOAT' (R)

   * 'FLOAT4' (R)

   * 'FLOAT8' (R)

   * 'FLUSH'

   * 'FOLLOWS' added in 5.7.2 (nonreserved)

   * 'FOR' (R)

   * 'FORCE' (R)

   * 'FOREIGN' (R)

   * 'FORMAT'

   * 'FOUND'

   * 'FROM' (R)

   * 'FULL'

   * 'FULLTEXT' (R)

   * 'FUNCTION'

G

   * 'GENERAL'

   * 'GENERATED' (R) added in 5.7.6 (reserved)

   * 'GEOMETRY'

   * 'GEOMETRYCOLLECTION'

   * 'GET' (R)

   * 'GET_FORMAT'

   * 'GLOBAL'

   * 'GRANT' (R)

   * 'GRANTS'

   * 'GROUP' (R)

   * 'GROUP_REPLICATION' added in 5.7.6 (nonreserved)

H

   * 'HANDLER'

   * 'HASH'

   * 'HAVING' (R)

   * 'HELP'

   * 'HIGH_PRIORITY' (R)

   * 'HOST'

   * 'HOSTS'

   * 'HOUR'

   * 'HOUR_MICROSECOND' (R)

   * 'HOUR_MINUTE' (R)

   * 'HOUR_SECOND' (R)

I

   * 'IDENTIFIED'

   * 'IF' (R)

   * 'IGNORE' (R)

   * 'IGNORE_SERVER_IDS'

   * 'IMPORT'

   * 'IN' (R)

   * 'INDEX' (R)

   * 'INDEXES'

   * 'INFILE' (R)

   * 'INITIAL_SIZE'

   * 'INNER' (R)

   * 'INOUT' (R)

   * 'INSENSITIVE' (R)

   * 'INSERT' (R)

   * 'INSERT_METHOD'

   * 'INSTALL'

   * 'INSTANCE' added in 5.7.11 (nonreserved)

   * 'INT' (R)

   * 'INT1' (R)

   * 'INT2' (R)

   * 'INT3' (R)

   * 'INT4' (R)

   * 'INT8' (R)

   * 'INTEGER' (R)

   * 'INTERVAL' (R)

   * 'INTO' (R)

   * 'INVOKER'

   * 'IO'

   * 'IO_AFTER_GTIDS' (R)

   * 'IO_BEFORE_GTIDS' (R)

   * 'IO_THREAD'

   * 'IPC'

   * 'IS' (R)

   * 'ISOLATION'

   * 'ISSUER'

   * 'ITERATE' (R)

J

   * 'JOIN' (R)

   * 'JSON' added in 5.7.8 (nonreserved)

K

   * 'KEY' (R)

   * 'KEYS' (R)

   * 'KEY_BLOCK_SIZE'

   * 'KILL' (R)

L

   * 'LANGUAGE'

   * 'LAST'

   * 'LEADING' (R)

   * 'LEAVE' (R)

   * 'LEAVES'

   * 'LEFT' (R)

   * 'LESS'

   * 'LEVEL'

   * 'LIKE' (R)

   * 'LIMIT' (R)

   * 'LINEAR' (R)

   * 'LINES' (R)

   * 'LINESTRING'

   * 'LIST'

   * 'LOAD' (R)

   * 'LOCAL'

   * 'LOCALTIME' (R)

   * 'LOCALTIMESTAMP' (R)

   * 'LOCK' (R)

   * 'LOCKS'

   * 'LOGFILE'

   * 'LOGS'

   * 'LONG' (R)

   * 'LONGBLOB' (R)

   * 'LONGTEXT' (R)

   * 'LOOP' (R)

   * 'LOW_PRIORITY' (R)

M

   * 'MASTER'

   * 'MASTER_AUTO_POSITION'

   * 'MASTER_BIND' (R)

   * 'MASTER_CONNECT_RETRY'

   * 'MASTER_DELAY'

   * 'MASTER_HEARTBEAT_PERIOD'

   * 'MASTER_HOST'

   * 'MASTER_LOG_FILE'

   * 'MASTER_LOG_POS'

   * 'MASTER_PASSWORD'

   * 'MASTER_PORT'

   * 'MASTER_RETRY_COUNT'

   * 'MASTER_SERVER_ID'

   * 'MASTER_SSL'

   * 'MASTER_SSL_CA'

   * 'MASTER_SSL_CAPATH'

   * 'MASTER_SSL_CERT'

   * 'MASTER_SSL_CIPHER'

   * 'MASTER_SSL_CRL'

   * 'MASTER_SSL_CRLPATH'

   * 'MASTER_SSL_KEY'

   * 'MASTER_SSL_VERIFY_SERVER_CERT' (R)

   * 'MASTER_TLS_VERSION' added in 5.7.10 (nonreserved)

   * 'MASTER_USER'

   * 'MATCH' (R)

   * 'MAXVALUE' (R)

   * 'MAX_CONNECTIONS_PER_HOUR'

   * 'MAX_QUERIES_PER_HOUR'

   * 'MAX_ROWS'

   * 'MAX_SIZE'

   * 'MAX_STATEMENT_TIME' added in 5.7.4 (nonreserved); removed in 5.7.8

   * 'MAX_UPDATES_PER_HOUR'

   * 'MAX_USER_CONNECTIONS'

   * 'MEDIUM'

   * 'MEDIUMBLOB' (R)

   * 'MEDIUMINT' (R)

   * 'MEDIUMTEXT' (R)

   * 'MEMORY'

   * 'MERGE'

   * 'MESSAGE_TEXT'

   * 'MICROSECOND'

   * 'MIDDLEINT' (R)

   * 'MIGRATE'

   * 'MINUTE'

   * 'MINUTE_MICROSECOND' (R)

   * 'MINUTE_SECOND' (R)

   * 'MIN_ROWS'

   * 'MOD' (R)

   * 'MODE'

   * 'MODIFIES' (R)

   * 'MODIFY'

   * 'MONTH'

   * 'MULTILINESTRING'

   * 'MULTIPOINT'

   * 'MULTIPOLYGON'

   * 'MUTEX'

   * 'MYSQL_ERRNO'

N

   * 'NAME'

   * 'NAMES'

   * 'NATIONAL'

   * 'NATURAL' (R)

   * 'NCHAR'

   * 'NDB'

   * 'NDBCLUSTER'

   * 'NEVER' added in 5.7.4 (nonreserved)

   * 'NEW'

   * 'NEXT'

   * 'NO'

   * 'NODEGROUP'

   * 'NONBLOCKING' removed in 5.7.6

   * 'NONE'

   * 'NOT' (R)

   * 'NO_WAIT'

   * 'NO_WRITE_TO_BINLOG' (R)

   * 'NULL' (R)

   * 'NUMBER'

   * 'NUMERIC' (R)

   * 'NVARCHAR'

O

   * 'OFFSET'

   * 'OLD_PASSWORD' removed in 5.7.5

   * 'ON' (R)

   * 'ONE'

   * 'ONLY'

   * 'OPEN'

   * 'OPTIMIZE' (R)

   * 'OPTIMIZER_COSTS' (R) added in 5.7.5 (reserved)

   * 'OPTION' (R)

   * 'OPTIONALLY' (R)

   * 'OPTIONS'

   * 'OR' (R)

   * 'ORDER' (R)

   * 'OUT' (R)

   * 'OUTER' (R)

   * 'OUTFILE' (R)

   * 'OWNER'

P

   * 'PACK_KEYS'

   * 'PAGE'

   * 'PARSER'

   * 'PARSE_GCOL_EXPR' added in 5.7.6 (reserved); became nonreserved in
     5.7.8

   * 'PARTIAL'

   * 'PARTITION' (R)

   * 'PARTITIONING'

   * 'PARTITIONS'

   * 'PASSWORD'

   * 'PHASE'

   * 'PLUGIN'

   * 'PLUGINS'

   * 'PLUGIN_DIR'

   * 'POINT'

   * 'POLYGON'

   * 'PORT'

   * 'PRECEDES' added in 5.7.2 (nonreserved)

   * 'PRECISION' (R)

   * 'PREPARE'

   * 'PRESERVE'

   * 'PREV'

   * 'PRIMARY' (R)

   * 'PRIVILEGES'

   * 'PROCEDURE' (R)

   * 'PROCESSLIST'

   * 'PROFILE'

   * 'PROFILES'

   * 'PROXY'

   * 'PURGE' (R)

Q

   * 'QUARTER'

   * 'QUERY'

   * 'QUICK'

R

   * 'RANGE' (R)

   * 'READ' (R)

   * 'READS' (R)

   * 'READ_ONLY'

   * 'READ_WRITE' (R)

   * 'REAL' (R)

   * 'REBUILD'

   * 'RECOVER'

   * 'REDOFILE'

   * 'REDO_BUFFER_SIZE'

   * 'REDUNDANT'

   * 'REFERENCES' (R)

   * 'REGEXP' (R)

   * 'RELAY'

   * 'RELAYLOG'

   * 'RELAY_LOG_FILE'

   * 'RELAY_LOG_POS'

   * 'RELAY_THREAD'

   * 'RELEASE' (R)

   * 'RELOAD'

   * 'REMOVE'

   * 'RENAME' (R)

   * 'REORGANIZE'

   * 'REPAIR'

   * 'REPEAT' (R)

   * 'REPEATABLE'

   * 'REPLACE' (R)

   * 'REPLICATE_DO_DB' added in 5.7.3 (nonreserved)

   * 'REPLICATE_DO_TABLE' added in 5.7.3 (nonreserved)

   * 'REPLICATE_IGNORE_DB' added in 5.7.3 (nonreserved)

   * 'REPLICATE_IGNORE_TABLE' added in 5.7.3 (nonreserved)

   * 'REPLICATE_REWRITE_DB' added in 5.7.3 (nonreserved)

   * 'REPLICATE_WILD_DO_TABLE' added in 5.7.3 (nonreserved)

   * 'REPLICATE_WILD_IGNORE_TABLE' added in 5.7.3 (nonreserved)

   * 'REPLICATION'

   * 'REQUIRE' (R)

   * 'RESET'

   * 'RESIGNAL' (R)

   * 'RESTORE'

   * 'RESTRICT' (R)

   * 'RESUME'

   * 'RETURN' (R)

   * 'RETURNED_SQLSTATE'

   * 'RETURNS'

   * 'REVERSE'

   * 'REVOKE' (R)

   * 'RIGHT' (R)

   * 'RLIKE' (R)

   * 'ROLLBACK'

   * 'ROLLUP'

   * 'ROTATE' added in 5.7.11 (nonreserved)

   * 'ROUTINE'

   * 'ROW'

   * 'ROWS'

   * 'ROW_COUNT'

   * 'ROW_FORMAT'

   * 'RTREE'

S

   * 'SAVEPOINT'

   * 'SCHEDULE'

   * 'SCHEMA' (R)

   * 'SCHEMAS' (R)

   * 'SCHEMA_NAME'

   * 'SECOND'

   * 'SECOND_MICROSECOND' (R)

   * 'SECURITY'

   * 'SELECT' (R)

   * 'SENSITIVE' (R)

   * 'SEPARATOR' (R)

   * 'SERIAL'

   * 'SERIALIZABLE'

   * 'SERVER'

   * 'SESSION'

   * 'SET' (R)

   * 'SHARE'

   * 'SHOW' (R)

   * 'SHUTDOWN'

   * 'SIGNAL' (R)

   * 'SIGNED'

   * 'SIMPLE'

   * 'SLAVE'

   * 'SLOW'

   * 'SMALLINT' (R)

   * 'SNAPSHOT'

   * 'SOCKET'

   * 'SOME'

   * 'SONAME'

   * 'SOUNDS'

   * 'SOURCE'

   * 'SPATIAL' (R)

   * 'SPECIFIC' (R)

   * 'SQL' (R)

   * 'SQLEXCEPTION' (R)

   * 'SQLSTATE' (R)

   * 'SQLWARNING' (R)

   * 'SQL_AFTER_GTIDS'

   * 'SQL_AFTER_MTS_GAPS'

   * 'SQL_BEFORE_GTIDS'

   * 'SQL_BIG_RESULT' (R)

   * 'SQL_BUFFER_RESULT'

   * 'SQL_CACHE'

   * 'SQL_CALC_FOUND_ROWS' (R)

   * 'SQL_NO_CACHE'

   * 'SQL_SMALL_RESULT' (R)

   * 'SQL_THREAD'

   * 'SQL_TSI_DAY'

   * 'SQL_TSI_HOUR'

   * 'SQL_TSI_MINUTE'

   * 'SQL_TSI_MONTH'

   * 'SQL_TSI_QUARTER'

   * 'SQL_TSI_SECOND'

   * 'SQL_TSI_WEEK'

   * 'SQL_TSI_YEAR'

   * 'SSL' (R)

   * 'STACKED'

   * 'START'

   * 'STARTING' (R)

   * 'STARTS'

   * 'STATS_AUTO_RECALC'

   * 'STATS_PERSISTENT'

   * 'STATS_SAMPLE_PAGES'

   * 'STATUS'

   * 'STOP'

   * 'STORAGE'

   * 'STORED' (R) added in 5.7.6 (reserved)

   * 'STRAIGHT_JOIN' (R)

   * 'STRING'

   * 'SUBCLASS_ORIGIN'

   * 'SUBJECT'

   * 'SUBPARTITION'

   * 'SUBPARTITIONS'

   * 'SUPER'

   * 'SUSPEND'

   * 'SWAPS'

   * 'SWITCHES'

T

   * 'TABLE' (R)

   * 'TABLES'

   * 'TABLESPACE'

   * 'TABLE_CHECKSUM'

   * 'TABLE_NAME'

   * 'TEMPORARY'

   * 'TEMPTABLE'

   * 'TERMINATED' (R)

   * 'TEXT'

   * 'THAN'

   * 'THEN' (R)

   * 'TIME'

   * 'TIMESTAMP'

   * 'TIMESTAMPADD'

   * 'TIMESTAMPDIFF'

   * 'TINYBLOB' (R)

   * 'TINYINT' (R)

   * 'TINYTEXT' (R)

   * 'TO' (R)

   * 'TRAILING' (R)

   * 'TRANSACTION'

   * 'TRIGGER' (R)

   * 'TRIGGERS'

   * 'TRUE' (R)

   * 'TRUNCATE'

   * 'TYPE'

   * 'TYPES'

U

   * 'UNCOMMITTED'

   * 'UNDEFINED'

   * 'UNDO' (R)

   * 'UNDOFILE'

   * 'UNDO_BUFFER_SIZE'

   * 'UNICODE'

   * 'UNINSTALL'

   * 'UNION' (R)

   * 'UNIQUE' (R)

   * 'UNKNOWN'

   * 'UNLOCK' (R)

   * 'UNSIGNED' (R)

   * 'UNTIL'

   * 'UPDATE' (R)

   * 'UPGRADE'

   * 'USAGE' (R)

   * 'USE' (R)

   * 'USER'

   * 'USER_RESOURCES'

   * 'USE_FRM'

   * 'USING' (R)

   * 'UTC_DATE' (R)

   * 'UTC_TIME' (R)

   * 'UTC_TIMESTAMP' (R)

V

   * 'VALIDATION' added in 5.7.5 (nonreserved)

   * 'VALUE'

   * 'VALUES' (R)

   * 'VARBINARY' (R)

   * 'VARCHAR' (R)

   * 'VARCHARACTER' (R)

   * 'VARIABLES'

   * 'VARYING' (R)

   * 'VIEW'

   * 'VIRTUAL' (R) added in 5.7.6 (reserved)

W

   * 'WAIT'

   * 'WARNINGS'

   * 'WEEK'

   * 'WEIGHT_STRING'

   * 'WHEN' (R)

   * 'WHERE' (R)

   * 'WHILE' (R)

   * 'WITH' (R)

   * 'WITHOUT' added in 5.7.5 (nonreserved)

   * 'WORK'

   * 'WRAPPER'

   * 'WRITE' (R)

X

   * 'X509'

   * 'XA'

   * 'XID' added in 5.7.5 (nonreserved)

   * 'XML'

   * 'XOR' (R)

Y

   * 'YEAR'

   * 'YEAR_MONTH' (R)

Z

   * 'ZEROFILL' (R)

*MySQL 5.7 New Keywords and Reserved Words*

The following list shows the keywords and reserved words that are added
in MySQL 5.7, compared to MySQL 5.6.  Reserved keywords are marked with
(R).

A | C | E | F | G | I | J | M | N | O | P | R | S | V | W | X

A

   * 'ACCOUNT'

   * 'ALWAYS'

C

   * 'CHANNEL'

   * 'COMPRESSION'

E

   * 'ENCRYPTION'

F

   * 'FILE_BLOCK_SIZE'

   * 'FILTER'

   * 'FOLLOWS'

G

   * 'GENERATED' (R)

   * 'GROUP_REPLICATION'

I

   * 'INSTANCE'

J

   * 'JSON'

M

   * 'MASTER_TLS_VERSION'

N

   * 'NEVER'

O

   * 'OPTIMIZER_COSTS' (R)

P

   * 'PARSE_GCOL_EXPR'

   * 'PRECEDES'

R

   * 'REPLICATE_DO_DB'

   * 'REPLICATE_DO_TABLE'

   * 'REPLICATE_IGNORE_DB'

   * 'REPLICATE_IGNORE_TABLE'

   * 'REPLICATE_REWRITE_DB'

   * 'REPLICATE_WILD_DO_TABLE'

   * 'REPLICATE_WILD_IGNORE_TABLE'

   * 'ROTATE'

S

   * 'STACKED'

   * 'STORED' (R)

V

   * 'VALIDATION'

   * 'VIRTUAL' (R)

W

   * 'WITHOUT'

X

   * 'XID'

*MySQL 5.7 Removed Keywords and Reserved Words*

The following list shows the keywords and reserved words that are
removed in MySQL 5.7, compared to MySQL 5.6.  Reserved keywords are
marked with (R).

   * 'OLD_PASSWORD'

9.4 User-Defined Variables
==========================

You can store a value in a user-defined variable in one statement and
refer to it later in another statement.  This enables you to pass values
from one statement to another.

User variables are written as '@VAR_NAME', where the variable name
VAR_NAME consists of alphanumeric characters, '.', '_', and '$'.  A user
variable name can contain other characters if you quote it as a string
or identifier (for example, '@'my-var'', '@"my-var"', or '@`my-var`').

User-defined variables are session specific.  A user variable defined by
one client cannot be seen or used by other clients.  (Exception: A user
with access to the Performance Schema 'user_variables_by_thread'
table can see all user
variables for all sessions.)  All variables for a given client session
are automatically freed when that client exits.

User variable names are not case-sensitive.  Names have a maximum length
of 64 characters.

One way to set a user-defined variable is by issuing a 'SET'
statement:

     SET @VAR_NAME = EXPR [, @VAR_NAME = EXPR] ...

For 'SET', either '=' or ':=' can be used as the
assignment operator.

You can also assign a value to a user variable in statements other than
'SET'.  In this case, the assignment operator must
be ':=' and not '=' because the latter is treated as the comparison
operator '=' in non-see 'SET' statements:

     mysql> SET @t1=1, @t2=2, @t3:=4;
     mysql> SELECT @t1, @t2, @t3, @t4 := @t1+@t2+@t3;
     +------+------+------+--------------------+
     | @t1  | @t2  | @t3  | @t4 := @t1+@t2+@t3 |
     +------+------+------+--------------------+
     |    1 |    2 |    4 |                  7 |
     +------+------+------+--------------------+

User variables can be assigned a value from a limited set of data types:
integer, decimal, floating-point, binary or nonbinary string, or 'NULL'
value.  Assignment of decimal and real values does not preserve the
precision or scale of the value.  A value of a type other than one of
the permissible types is converted to a permissible type.  For example,
a value having a temporal or spatial data type is converted to a binary
string.  A value having the 'JSON' data type is converted
to a string with a character set of 'utf8mb4' and a collation of
'utf8mb4_bin'.

If a user variable is assigned a nonbinary (character) string value, it
has the same character set and collation as the string.  The
coercibility of user variables is implicit.  (This is the same
coercibility as for table column values.)

Hexadecimal or bit values assigned to user variables are treated as
binary strings.  To assign a hexadecimal or bit value as a number to a
user variable, use it in numeric context.  For example, add 0 or use
'CAST(... AS UNSIGNED)':

     mysql> SET @v1 = X'41';
     mysql> SET @v2 = X'41'+0;
     mysql> SET @v3 = CAST(X'41' AS UNSIGNED);
     mysql> SELECT @v1, @v2, @v3;
     +------+------+------+
     | @v1  | @v2  | @v3  |
     +------+------+------+
     | A    |   65 |   65 |
     +------+------+------+
     mysql> SET @v1 = b'1000001';
     mysql> SET @v2 = b'1000001'+0;
     mysql> SET @v3 = CAST(b'1000001' AS UNSIGNED);
     mysql> SELECT @v1, @v2, @v3;
     +------+------+------+
     | @v1  | @v2  | @v3  |
     +------+------+------+
     | A    |   65 |   65 |
     +------+------+------+

If the value of a user variable is selected in a result set, it is
returned to the client as a string.

If you refer to a variable that has not been initialized, it has a value
of 'NULL' and a type of string.

User variables may be used in most contexts where expressions are
permitted.  This does not currently include contexts that explicitly
require a literal value, such as in the 'LIMIT' clause of a
'SELECT' statement, or the 'IGNORE N LINES' clause of a
'LOAD DATA' statement.

As a general rule, other than in 'SET' statements,
you should never assign a value to a user variable and read the value
within the same statement.  For example, to increment a variable, this
is okay:

     SET @a = @a + 1;

For other statements, such as 'SELECT', you might get the
results you expect, but this is not guaranteed.  In the following
statement, you might think that MySQL will evaluate '@a' first and then
do an assignment second:

     SELECT @a, @a:=@a+1, ...;

However, the order of evaluation for expressions involving user
variables is undefined.

Another issue with assigning a value to a variable and reading the value
within the same non-see 'SET' statement is that the
default result type of a variable is based on its type at the start of
the statement.  The following example illustrates this:

     mysql> SET @a='test';
     mysql> SELECT @a,(@a:=20) FROM TBL_NAME;

For this 'SELECT' statement, MySQL reports to the client
that column one is a string and converts all accesses of '@a' to
strings, even though @a is set to a number for the second row.  After
the 'SELECT' statement executes, '@a' is regarded as a
number for the next statement.

To avoid problems with this behavior, either do not assign a value to
and read the value of the same variable within a single statement, or
else set the variable to '0', '0.0', or '''' to define its type before
you use it.

In a 'SELECT' statement, each select expression is
evaluated only when sent to the client.  This means that in a 'HAVING',
'GROUP BY', or 'ORDER BY' clause, referring to a variable that is
assigned a value in the select expression list does _not_ work as
expected:

     mysql> SELECT (@aa:=id) AS a, (@aa+3) AS b FROM TBL_NAME HAVING b=5;

The reference to 'b' in the 'HAVING' clause refers to an alias for an
expression in the select list that uses '@aa'.  This does not work as
expected: '@aa' contains the value of 'id' from the previous selected
row, not from the current row.

User variables are intended to provide data values.  They cannot be used
directly in an SQL statement as an identifier or as part of an
identifier, such as in contexts where a table or database name is
expected, or as a reserved word such as 'SELECT'.  This is
true even if the variable is quoted, as shown in the following example:

     mysql> SELECT c1 FROM t;
     +----+
     | c1 |
     +----+
     |  0 |
     +----+
     |  1 |
     +----+
     2 rows in set (0.00 sec)

     mysql> SET @col = "c1";
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @col FROM t;
     +------+
     | @col |
     +------+
     | c1   |
     +------+
     1 row in set (0.00 sec)

     mysql> SELECT `@col` FROM t;
     ERROR 1054 (42S22): Unknown column '@col' in 'field list'

     mysql> SET @col = "`c1`";
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @col FROM t;
     +------+
     | @col |
     +------+
     | `c1` |
     +------+
     1 row in set (0.00 sec)

An exception to this principle that user variables cannot be used to
provide identifiers, is when you are constructing a string for use as a
prepared statement to execute later.  In this case, user variables can
be used to provide any part of the statement.  The following example
illustrates how this can be done:

     mysql> SET @c = "c1";
     Query OK, 0 rows affected (0.00 sec)

     mysql> SET @s = CONCAT("SELECT ", @c, " FROM t");
     Query OK, 0 rows affected (0.00 sec)

     mysql> PREPARE stmt FROM @s;
     Query OK, 0 rows affected (0.04 sec)
     Statement prepared

     mysql> EXECUTE stmt;
     +----+
     | c1 |
     +----+
     |  0 |
     +----+
     |  1 |
     +----+
     2 rows in set (0.00 sec)

     mysql> DEALLOCATE PREPARE stmt;
     Query OK, 0 rows affected (0.00 sec)

See sql-syntax-prepared-statements, for more information.

A similar technique can be used in application programs to construct SQL
statements using program variables, as shown here using PHP 5:

     <?php
       $mysqli = new mysqli("localhost", "user", "pass", "test");

       if( mysqli_connect_errno() )
         die("Connection failed: %s\n", mysqli_connect_error());

       $col = "c1";

       $query = "SELECT $col FROM t";

       $result = $mysqli->query($query);

       while($row = $result->fetch_assoc())
       {
         echo "<p>" . $row["$col"] . "</p>\n";
       }

       $result->close();

       $mysqli->close();
     ?>

Assembling an SQL statement in this fashion is sometimes known as
'Dynamic SQL'.

9.5 Expression Syntax
=====================

The following rules define expression syntax in MySQL. The grammar shown
here is based on that given in the 'sql/sql_yacc.yy' file of MySQL
source distributions.  See the notes after the grammar for additional
information about some of the terms.

     EXPR:
         EXPR OR EXPR
       | EXPR || EXPR
       | EXPR XOR EXPR
       | EXPR AND EXPR
       | EXPR && EXPR
       | NOT EXPR
       | ! EXPR
       | BOOLEAN_PRIMARY IS [NOT] {TRUE | FALSE | UNKNOWN}
       | BOOLEAN_PRIMARY

     BOOLEAN_PRIMARY:
         BOOLEAN_PRIMARY IS [NOT] NULL
       | BOOLEAN_PRIMARY <=> PREDICATE
       | BOOLEAN_PRIMARY COMPARISON_OPERATOR PREDICATE
       | BOOLEAN_PRIMARY COMPARISON_OPERATOR {ALL | ANY} (SUBQUERY)
       | PREDICATE

     COMPARISON_OPERATOR: = | >= | > | <= | < | <> | !=

     PREDICATE:
         BIT_EXPR [NOT] IN (SUBQUERY)
       | BIT_EXPR [NOT] IN (EXPR [, EXPR] ...)
       | BIT_EXPR [NOT] BETWEEN BIT_EXPR AND PREDICATE
       | BIT_EXPR SOUNDS LIKE BIT_EXPR
       | BIT_EXPR [NOT] LIKE SIMPLE_EXPR [ESCAPE SIMPLE_EXPR]
       | BIT_EXPR [NOT] REGEXP BIT_EXPR
       | BIT_EXPR

     BIT_EXPR:
         BIT_EXPR | BIT_EXPR
       | BIT_EXPR & BIT_EXPR
       | BIT_EXPR << BIT_EXPR
       | BIT_EXPR >> BIT_EXPR
       | BIT_EXPR + BIT_EXPR
       | BIT_EXPR - BIT_EXPR
       | BIT_EXPR * BIT_EXPR
       | BIT_EXPR / BIT_EXPR
       | BIT_EXPR DIV BIT_EXPR
       | BIT_EXPR MOD BIT_EXPR
       | BIT_EXPR % BIT_EXPR
       | BIT_EXPR ^ BIT_EXPR
       | BIT_EXPR + INTERVAL_EXPR
       | BIT_EXPR - INTERVAL_EXPR
       | SIMPLE_EXPR

     SIMPLE_EXPR:
         LITERAL
       | IDENTIFIER
       | FUNCTION_CALL
       | SIMPLE_EXPR COLLATE COLLATION_NAME
       | PARAM_MARKER
       | VARIABLE
       | SIMPLE_EXPR || SIMPLE_EXPR
       | + SIMPLE_EXPR
       | - SIMPLE_EXPR
       | ~ SIMPLE_EXPR
       | ! SIMPLE_EXPR
       | BINARY SIMPLE_EXPR
       | (EXPR [, EXPR] ...)
       | ROW (EXPR, EXPR [, EXPR] ...)
       | (SUBQUERY)
       | EXISTS (SUBQUERY)
       | {IDENTIFIER EXPR}
       | MATCH_EXPR
       | CASE_EXPR
       | INTERVAL_EXPR

Notes:

For operator precedence, see in operator-precedence.

For literal value syntax, see literals.

For identifier syntax, see identifiers.

Variables can be user variables, system variables, or stored program
local variables or parameters:

   * User variables: user-variables

   * System variables: using-system-variables

   * Local variables: declare-local-variable

   * Parameters: create-procedure

PARAM_MARKER is '?' as used in prepared statements for placeholders.
See prepare.

'(SUBQUERY)' indicates a subquery that returns a single value; that is,
a scalar subquery.  See scalar-subqueries.

'{IDENTIFIER EXPR}' is ODBC escape syntax and is accepted for ODBC
compatibility.  The value is EXPR.  The curly braces in the syntax
should be written literally; they are not metasyntax as used elsewhere
in syntax descriptions.

MATCH_EXPR indicates a 'MATCH' expression.  See fulltext-search.

CASE_EXPR indicates a 'CASE' expression.  See
control-flow-functions.

INTERVAL_EXPR represents a time interval.  The syntax is 'INTERVAL EXPR
UNIT', where UNIT is a specifier such as 'HOUR', 'DAY', or 'WEEK'.  For
the full list of UNIT specifiers, see the description of the
'DATE_ADD()' function in date-and-time-functions.

The meaning of some operators depends on the SQL mode:

   * By default, '||' is a logical 'OR' operator.  With
     'PIPES_AS_CONCAT' enabled, '||' is string concatenation, with a
     precedence between '^' and the unary operators.

   * By default, '!' has a higher precedence than 'NOT'.  With
     'HIGH_NOT_PRECEDENCE' enabled, '!' and 'NOT' have the same
     precedence.

See sql-mode.

9.6 Comment Syntax
==================

MySQL Server supports three comment styles:

   * From a '#' character to the end of the line.

   * From a '-- ' sequence to the end of the line.  In MySQL, the '-- '
     (double-dash) comment style requires the second dash to be followed
     by at least one whitespace or control character (such as a space,
     tab, newline, and so on).  This syntax differs slightly from
     standard SQL comment syntax, as discussed in
     ansi-diff-comments.

   * From a '/*' sequence to the following '*/' sequence, as in the C
     programming language.  This syntax enables a comment to extend over
     multiple lines because the beginning and closing sequences need not
     be on the same line.

The following example demonstrates all three comment styles:

     mysql> SELECT 1+1;     # This comment continues to the end of line
     mysql> SELECT 1+1;     -- This comment continues to the end of line
     mysql> SELECT 1 /* this is an in-line comment */ + 1;
     mysql> SELECT 1+
     /*
     this is a
     multiple-line comment
     */
     1;

Nested comments are not supported.  (Under some conditions, nested
comments might be permitted, but usually are not, and users should avoid
them.)

MySQL Server supports some variants of C-style comments.  These enable
you to write code that includes MySQL extensions, but is still portable,
by using comments of the following form:

     /*! MYSQL-SPECIFIC CODE */

In this case, MySQL Server parses and executes the code within the
comment as it would any other SQL statement, but other SQL servers will
ignore the extensions.  For example, MySQL Server recognizes the
'STRAIGHT_JOIN' keyword in the following statement, but other servers
will not:

     SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...

If you add a version number after the '!' character, the syntax within
the comment is executed only if the MySQL version is greater than or
equal to the specified version number.  The 'KEY_BLOCK_SIZE' keyword in
the following comment is executed only by servers from MySQL 5.1.10 or
higher:

     CREATE TABLE t1(a INT, KEY (a)) /*!50110 KEY_BLOCK_SIZE=1024 */;

The comment syntax just described applies to how the 'mysqld'
server parses SQL statements.  The 'mysql' client
program also performs some parsing of statements before sending them to
the server.  (It does this to determine statement boundaries within a
multiple-statement input line.)

Comments in this format, '/*!12345 ... */', are not stored on the
server.  If this format is used to comment stored routines, the comments
will not be retained on the server.

Another variant of C-style comment syntax is used to specify optimizer
hints.  Hint comments include a '+' character following the '/*' comment
opening sequence.  Example:

     SELECT /*+ BKA(t1) */ FROM ... ;

For more information, see optimizer-hints.

The use of short-form 'mysql' commands such as '\C' within
multiple-line '/* ... */' comments is not supported.

10 Character Sets, Collations, Unicode
**************************************

MySQL includes character set support that enables you to store data
using a variety of character sets and perform comparisons according to a
variety of collations.  You can specify character sets at the server,
database, table, and column level.  MySQL supports the use of character
sets for the 'MyISAM', 'MEMORY', and 'InnoDB' storage engines.

This chapter discusses the following topics:

   * What are character sets and collations?

   * The multiple-level default system for character set assignment.

   * Syntax for specifying character sets and collations.

   * Affected functions and operations.

   * Unicode support.

   * The character sets and collations that are available, with notes.

   * Selecting the language for error messages.

   * Selecting the locale for day and month names.

Character set issues affect not only data storage, but also
communication between client programs and the MySQL server.  If you want
the client program to communicate with the server using a character set
different from the default, you'll need to indicate which one.  For
example, to use the 'utf8' Unicode character set, issue this statement
after connecting to the server:

     SET NAMES 'utf8';

For more information about configuring character sets for application
use and character set-related issues in client/server communication, see
charset-applications, and charset-connection.

10.1 Character Sets and Collations in General
=============================================

A _character set_ is a set of symbols and encodings.  A _collation_ is a
set of rules for comparing characters in a character set.  Let's make
the distinction clear with an example of an imaginary character set.

Suppose that we have an alphabet with four letters: 'A', 'B', 'a', 'b'.
We give each letter a number: 'A' = 0, 'B' = 1, 'a' = 2, 'b' = 3.  The
letter 'A' is a symbol, the number 0 is the _encoding_ for 'A', and the
combination of all four letters and their encodings is a _character
set_.

Suppose that we want to compare two string values, 'A' and 'B'.  The
simplest way to do this is to look at the encodings: 0 for 'A' and 1 for
'B'.  Because 0 is less than 1, we say 'A' is less than 'B'.  What we've
just done is apply a collation to our character set.  The collation is a
set of rules (only one rule in this case): 'compare the encodings.' We
call this simplest of all possible collations a _binary_ collation.

But what if we want to say that the lowercase and uppercase letters are
equivalent?  Then we would have at least two rules: (1) treat the
lowercase letters 'a' and 'b' as equivalent to 'A' and 'B'; (2) then
compare the encodings.  We call this a _case-insensitive_ collation.  It
is a little more complex than a binary collation.

In real life, most character sets have many characters: not just 'A' and
'B' but whole alphabets, sometimes multiple alphabets or eastern writing
systems with thousands of characters, along with many special symbols
and punctuation marks.  Also in real life, most collations have many
rules, not just for whether to distinguish lettercase, but also for
whether to distinguish accents (an 'accent' is a mark attached to a
character as in German 'O"'), and for multiple-character mappings (such
as the rule that 'O"' = 'OE' in one of the two German collations).

MySQL can do these things for you:

   * Store strings using a variety of character sets.

   * Compare strings using a variety of collations.

   * Mix strings with different character sets or collations in the same
     server, the same database, or even the same table.

   * Enable specification of character set and collation at any level.

To use these features effectively, you must know what character sets and
collations are available, how to change the defaults, and how they
affect the behavior of string operators and functions.

10.2 Character Sets and Collations in MySQL
===========================================

MySQL Server supports multiple character sets.  To display the available
character sets, use the 'INFORMATION_SCHEMA' 'CHARACTER_SETS'
table or the 'SHOW CHARACTER SET'
statement.  A partial listing follows.  For more
complete information, see charset-charsets.

     mysql> SHOW CHARACTER SET;
     +----------+---------------------------------+---------------------+--------+
     | Charset  | Description                     | Default collation   | Maxlen |
     +----------+---------------------------------+---------------------+--------+
     | big5     | Big5 Traditional Chinese        | big5_chinese_ci     |      2 |
     ...
     | latin1   | cp1252 West European            | latin1_swedish_ci   |      1 |
     | latin2   | ISO 8859-2 Central European     | latin2_general_ci   |      1 |
     ...
     | utf8     | UTF-8 Unicode                   | utf8_general_ci     |      3 |
     | ucs2     | UCS-2 Unicode                   | ucs2_general_ci     |      2 |
     ...
     | utf8mb4  | UTF-8 Unicode                   | utf8mb4_general_ci  |      4 |
     ...
     | binary   | Binary pseudo charset           | binary              |      1 |
     ...

By default, the 'SHOW CHARACTER SET'.
statement displays all available character sets.  It takes an optional
'LIKE' or 'WHERE' clause that indicates which character set names to
match.  For example:

     mysql> SHOW CHARACTER SET LIKE 'latin%';
     +---------+-----------------------------+-------------------+--------+
     | Charset | Description                 | Default collation | Maxlen |
     +---------+-----------------------------+-------------------+--------+
     | latin1  | cp1252 West European        | latin1_swedish_ci |      1 |
     | latin2  | ISO 8859-2 Central European | latin2_general_ci |      1 |
     | latin5  | ISO 8859-9 Turkish          | latin5_turkish_ci |      1 |
     | latin7  | ISO 8859-13 Baltic          | latin7_general_ci |      1 |
     +---------+-----------------------------+-------------------+--------+

A given character set always has at least one collation, and most
character sets have several.  To list the display collations for a
character set, use the 'INFORMATION_SCHEMA' 'COLLATIONS'
table or the 'SHOW COLLATION'.
statement.

By default, the 'SHOW COLLATION' statement
displays all available collations.  It takes an optional 'LIKE' or
'WHERE' clause that indicates which collation names to display.  For
example, to see the collations for the default character set, 'latin1'
(cp1252 West European), use this statement:

     mysql> SHOW COLLATION WHERE Charset = 'latin1';
     +-------------------+---------+----+---------+----------+---------+
     | Collation         | Charset | Id | Default | Compiled | Sortlen |
     +-------------------+---------+----+---------+----------+---------+
     | latin1_german1_ci | latin1  |  5 |         | Yes      |       1 |
     | latin1_swedish_ci | latin1  |  8 | Yes     | Yes      |       1 |
     | latin1_danish_ci  | latin1  | 15 |         | Yes      |       1 |
     | latin1_german2_ci | latin1  | 31 |         | Yes      |       2 |
     | latin1_bin        | latin1  | 47 |         | Yes      |       1 |
     | latin1_general_ci | latin1  | 48 |         | Yes      |       1 |
     | latin1_general_cs | latin1  | 49 |         | Yes      |       1 |
     | latin1_spanish_ci | latin1  | 94 |         | Yes      |       1 |
     +-------------------+---------+----+---------+----------+---------+

The 'latin1' collations have the following meanings.

Collation                     Meaning

'latin1_bin'                  Binary according to 'latin1' encoding

'latin1_danish_ci'            Danish/Norwegian

'latin1_general_ci'           Multilingual (Western European)

'latin1_general_cs'           Multilingual (ISO Western European),
                              case-sensitive

'latin1_german1_ci'           German DIN-1 (dictionary order)

'latin1_german2_ci'           German DIN-2 (phone book order)

'latin1_spanish_ci'           Modern Spanish

'latin1_swedish_ci'           Swedish/Finnish

Collations have these general characteristics:

   * Two different character sets cannot have the same collation.

   * Each character set has a _default collation_.  For example, the
     default collations for 'latin1' and 'utf8' are 'latin1_swedish_ci'
     and 'utf8_general_ci', respectively.  The 'INFORMATION_SCHEMA'
     'CHARACTER_SETS' table and the
     'SHOW CHARACTER SET' statement indicate the
     default collation for each character set.  The 'INFORMATION_SCHEMA'
     'COLLATIONS' table and the 'SHOW COLLATION'
     statement have a column that indicates
     for each collation whether it is the default for its character set
     ('Yes' if so, empty if not).

   * Collation names start with the name of the character set with which
     they are associated, generally followed by one or more suffixes
     indicating other collation characteristics.  For additional
     information about naming conventions, see
     charset-collation-names.

When a character set has multiple collations, it might not be clear
which collation is most suitable for a given application.  To avoid
choosing an inappropriate collation, perform some comparisons with
representative data values to make sure that a given collation sorts
values the way you expect.

10.2.1 Character Set Repertoire
-------------------------------

The _repertoire_ of a character set is the collection of characters in
the set.

String expressions have a repertoire attribute, which can have two
values:

   * 'ASCII': The expression can contain only characters in the Unicode
     range 'U+0000' to 'U+007F'.

   * 'UNICODE': The expression can contain characters in the Unicode
     range 'U+0000' to 'U+10FFFF'.  This includes characters in the
     Basic Multilingual Plane (BMP) range ('U+0000' to 'U+FFFF') and
     supplementary characters outside the BMP range ('U+10000' to
     'U+10FFFF').

The 'ASCII' range is a subset of 'UNICODE' range, so a string with
'ASCII' repertoire can be converted safely without loss of information
to the character set of any string with 'UNICODE' repertoire or to a
character set that is a superset of 'ASCII'.  (All MySQL character sets
are supersets of 'ASCII' with the exception of 'swe7', which reuses some
punctuation characters for Swedish accented characters.)  The use of
repertoire enables character set conversion in expressions for many
cases where MySQL would otherwise return an 'illegal mix of collations'
error.

The following discussion provides examples of expressions and their
repertoires, and describes how the use of repertoire changes string
expression evaluation:

   * The repertoire for a string constant depends on string content and
     may differ from the repertoire of the string character set.
     Consider these statements:

          SET NAMES utf8; SELECT 'abc';
          SELECT _utf8'def';
          SELECT N'MySQL';

     Although the character set is 'utf8' in each of the preceding
     cases, the strings do not actually contain any characters outside
     the ASCII range, so their repertoire is 'ASCII' rather than
     'UNICODE'.

   * A column having the 'ascii' character set has 'ASCII' repertoire
     because of its character set.  In the following table, 'c1' has
     'ASCII' repertoire:

          CREATE TABLE t1 (c1 CHAR(1) CHARACTER SET ascii);

     The following example illustrates how repertoire enables a result
     to be determined in a case where an error occurs without
     repertoire:

          CREATE TABLE t1 (
            c1 CHAR(1) CHARACTER SET latin1,
            c2 CHAR(1) CHARACTER SET ascii
          );
          INSERT INTO t1 VALUES ('a','b');
          SELECT CONCAT(c1,c2) FROM t1;

     Without repertoire, this error occurs:

          ERROR 1267 (HY000): Illegal mix of collations (latin1_swedish_ci,IMPLICIT)
          and (ascii_general_ci,IMPLICIT) for operation 'concat'

     Using repertoire, subset to superset ('ascii' to 'latin1')
     conversion can occur and a result is returned:

          +---------------+
          | CONCAT(c1,c2) |
          +---------------+
          | ab            |
          +---------------+

   * Functions with one string argument inherit the repertoire of their
     argument.  The result of 'UPPER(_utf8'ABC')' has 'ASCII' repertoire
     because its argument has 'ASCII' repertoire.

   * For functions that return a string but do not have string arguments
     and use 'character_set_connection' as the result character set, the
     result repertoire is 'ASCII' if 'character_set_connection' is
     'ascii', and 'UNICODE' otherwise:

          FORMAT(NUMERIC_COLUMN, 4);

     Use of repertoire changes how MySQL evaluates the following
     example:

          SET NAMES ascii;
          CREATE TABLE t1 (a INT, b VARCHAR(10) CHARACTER SET latin1);
          INSERT INTO t1 VALUES (1,'b');
          SELECT CONCAT(FORMAT(a, 4), b) FROM t1;

     Without repertoire, this error occurs:

          ERROR 1267 (HY000): Illegal mix of collations (ascii_general_ci,COERCIBLE)
          and (latin1_swedish_ci,IMPLICIT) for operation 'concat'

     With repertoire, a result is returned:

          +-------------------------+
          | CONCAT(FORMAT(a, 4), b) |
          +-------------------------+
          | 1.0000b                 |
          +-------------------------+

   * Functions with two or more string arguments use the 'widest'
     argument repertoire for the result repertoire ('UNICODE' is wider
     than 'ASCII').  Consider the following 'CONCAT()' calls:

          CONCAT(_ucs2 X'0041', _ucs2 X'0042')
          CONCAT(_ucs2 X'0041', _ucs2 X'00C2')

     For the first call, the repertoire is 'ASCII' because both
     arguments are within the range of the 'ascii' character set.  For
     the second call, the repertoire is 'UNICODE' because the second
     argument is outside the 'ascii' character set range.

   * The repertoire for function return values is determined based only
     on the repertoire of the arguments that affect the result's
     character set and collation.

          IF(column1 < column2, 'smaller', 'greater')

     The result repertoire is 'ASCII' because the two string arguments
     (the second argument and the third argument) both have 'ASCII'
     repertoire.  The first argument does not matter for the result
     repertoire, even if the expression uses string values.

10.2.2 UTF-8 for Metadata
-------------------------

_Metadata_ is 'the data about the data.' Anything that _describes_ the
database--as opposed to being the _contents_ of the database--is
metadata.  Thus column names, database names, user names, version names,
and most of the string results from 'SHOW' are metadata.
This is also true of the contents of tables in 'INFORMATION_SCHEMA'
because those tables by definition contain information about database
objects.

Representation of metadata must satisfy these requirements:

   * All metadata must be in the same character set.  Otherwise, neither
     the 'SHOW' statements nor 'SELECT'.
     statements for tables in 'INFORMATION_SCHEMA' would work properly
     because different rows in the same column of the results of these
     operations would be in different character sets.

   * Metadata must include all characters in all languages.  Otherwise,
     users would not be able to name columns and tables using their own
     languages.

To satisfy both requirements, MySQL stores metadata in a Unicode
character set, namely UTF-8.  This does not cause any disruption if you
never use accented or non-Latin characters.  But if you do, you should
be aware that metadata is in UTF-8.

The metadata requirements mean that the return values of the 'USER()',
'CURRENT_USER()', 'SESSION_USER()', 'SYSTEM_USER()', 'DATABASE()', and
'VERSION()' functions have the UTF-8 character set by default.

The server sets the 'character_set_system' system variable to the name
of the metadata character set:

     mysql> SHOW VARIABLES LIKE 'character_set_system';
     +----------------------+-------+
     | Variable_name        | Value |
     +----------------------+-------+
     | character_set_system | utf8  |
     +----------------------+-------+

Storage of metadata using Unicode does _not_ mean that the server
returns headers of columns and the results of 'DESCRIBE'
functions in the 'character_set_system' character set by
default.  When you use 'SELECT column1 FROM t', the name 'column1'
itself is returned from the server to the client in the character set
determined by the value of the 'character_set_results' system variable,
which has a default value of 'latin1'.  If you want the server to pass
metadata results back in a different character set, use the 'SET NAMES'
statement to force the server to perform character
set conversion.  'SET NAMES' sets the
'character_set_results' and other related system variables.  (See
charset-connection.)  Alternatively, a client program can perform the
conversion after receiving the result from the server.  It is more
efficient for the client to perform the conversion, but this option is
not always available for all clients.

If 'character_set_results' is set to 'NULL', no conversion is performed
and the server returns metadata using its original character set (the
set indicated by 'character_set_system').

Error messages returned from the server to the client are converted to
the client character set automatically, as with metadata.

If you are using (for example) the 'USER()' function for comparison or
assignment within a single statement, don't worry.  MySQL performs some
automatic conversion for you.

     SELECT * FROM t1 WHERE USER() = latin1_column;

This works because the contents of 'latin1_column' are automatically
converted to UTF-8 before the comparison.

     INSERT INTO t1 (latin1_column) SELECT USER();

This works because the contents of 'USER()' are automatically converted
to 'latin1' before the assignment.

Although automatic conversion is not in the SQL standard, the standard
does say that every character set is (in terms of supported characters)
a 'subset' of Unicode.  Because it is a well-known principle that 'what
applies to a superset can apply to a subset,' we believe that a
collation for Unicode can apply for comparisons with non-Unicode
strings.  For more information about coercion of strings, see
charset-collation-coercibility.

10.3 Specifying Character Sets and Collations
=============================================

There are default settings for character sets and collations at four
levels: server, database, table, and column.  The description in the
following sections may appear complex, but it has been found in practice
that multiple-level defaulting leads to natural and obvious results.

'CHARACTER SET' is used in clauses that specify a character set.
'CHARSET' can be used as a synonym for 'CHARACTER SET'.

Character set issues affect not only data storage, but also
communication between client programs and the MySQL server.  If you want
the client program to communicate with the server using a character set
different from the default, you'll need to indicate which one.  For
example, to use the 'utf8' Unicode character set, issue this statement
after connecting to the server:

     SET NAMES 'utf8';

For more information about character set-related issues in client/server
communication, see charset-connection.

10.3.1 Collation Naming Conventions
-----------------------------------

MySQL collation names follow these conventions:

   * A collation name starts with the name of the character set with
     which it is associated, generally followed by one or more suffixes
     indicating other collation characteristics.  For example,
     'utf8_general_ci' and 'latin1_swedish_ci' are collations for the
     'utf8' and 'latin1' character sets, respectively.  The 'binary'
     character set has a single collation, also named 'binary', with no
     suffixes.

   * A language-specific collation includes a language name.  For
     example, 'utf8_turkish_ci' and 'utf8_hungarian_ci' sort characters
     for the 'utf8' character set using the rules of Turkish and
     Hungarian, respectively.

   * Collation suffixes indicate whether a collation is case and accent
     sensitive, or binary.  The following table shows the suffixes used
     to indicate these characteristics.

     *Collation Case Sensitivity Suffixes*

     Suffix         Meaning

     '_ai'          Accent insensitive

     '_as'          Accent sensitive

     '_ci'          Case insensitive

     '_cs'          case-sensitive

     '_bin'         Binary

     For nonbinary collation names that do not specify accent
     sensitivity, it is determined by case sensitivity.  If a collation
     name does not contain '_ai' or '_as', '_ci' in the name implies
     '_ai' and '_cs' in the name implies '_as'.  For example,
     'latin1_general_ci' is explicitly case insensitive and implicitly
     accent insensitive, and 'latin1_general_cs' is explicitly case
     sensitive and implicitly accent sensitive.

     For the 'binary' collation of the 'binary' character set,
     comparisons are based on numeric byte values.  For the '_bin'
     collation of a nonbinary character set, comparisons are based on
     numeric character code values, which differ from byte values for
     multibyte characters.  For more information, see
     charset-binary-collations.

   * For Unicode character sets, collation names may include a version
     number to indicate the version of the Unicode Collation Algorithm
     (UCA) on which the collation is based.  UCA-based collations
     without a version number in the name use the version-4.0.0 UCA
     weight keys.  For example:

        * 'utf8_unicode_520_ci' is based on UCA 5.2.0 weight keys
          (<http://www.unicode.org/Public/UCA/5.2.0/allkeys.txt>).

        * 'utf8_unicode_ci' (with no version named) is based on UCA
          4.0.0 weight keys
          (<http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt>).

   * For Unicode character sets, the 'XXX_general_mysql500_ci'
     collations preserve the pre-5.1.24 ordering of the original
     'XXX_general_ci' collations and permit upgrades for tables created
     before MySQL 5.1.24 (Bug #27877).

10.3.2 Server Character Set and Collation
-----------------------------------------

MySQL Server has a server character set and a server collation.  These
can be set at server startup on the command line or in an option file
and changed at runtime.

Initially, the server character set and collation depend on the options
that you use when you start 'mysqld'.  You can use
'--character-set-server' for the character set.  Along with it, you can
add '--collation-server' for the collation.  If you don't specify a
character set, that is the same as saying
'--character-set-server=latin1'.  If you specify only a character set
(for example, 'latin1') but not a collation, that is the same as saying
'--character-set-server=latin1' '--collation-server=latin1_swedish_ci'
because 'latin1_swedish_ci' is the default collation for 'latin1'.
Therefore, the following three commands all have the same effect:

     mysqld
     mysqld --character-set-server=latin1
     mysqld --character-set-server=latin1 \
       --collation-server=latin1_swedish_ci

One way to change the settings is by recompiling.  To change the default
server character set and collation when building from sources, use the
'DEFAULT_CHARSET' and 'DEFAULT_COLLATION' options for 'CMake'.  For
example:

     cmake . -DDEFAULT_CHARSET=latin1

Or:

     cmake . -DDEFAULT_CHARSET=latin1 \
       -DDEFAULT_COLLATION=latin1_german1_ci

Both 'mysqld' and 'CMake' verify that the character
set/collation combination is valid.  If not, each program displays an
error message and terminates.

The server character set and collation are used as default values if the
database character set and collation are not specified in 'CREATE DATABASE'
statements.  They have no other purpose.

The current server character set and collation can be determined from
the values of the 'character_set_server' and 'collation_server' system
variables.  These variables can be changed at runtime.

10.3.3 Database Character Set and Collation
-------------------------------------------

Every database has a database character set and a database collation.
The 'CREATE DATABASE' and 'ALTER DATABASE'
statements have optional clauses for
specifying the database character set and collation:

     CREATE DATABASE DB_NAME
         [[DEFAULT] CHARACTER SET CHARSET_NAME]
         [[DEFAULT] COLLATE COLLATION_NAME]

     ALTER DATABASE DB_NAME
         [[DEFAULT] CHARACTER SET CHARSET_NAME]
         [[DEFAULT] COLLATE COLLATION_NAME]

The keyword 'SCHEMA' can be used instead of 'DATABASE'.

All database options are stored in a text file named 'db.opt' that can
be found in the database directory.

The 'CHARACTER SET' and 'COLLATE' clauses make it possible to create
databases with different character sets and collations on the same MySQL
server.

Example:

     CREATE DATABASE DB_NAME CHARACTER SET latin1 COLLATE latin1_swedish_ci;

MySQL chooses the database character set and database collation in the
following manner:

   * If both 'CHARACTER SET CHARSET_NAME' and 'COLLATE COLLATION_NAME'
     are specified, character set CHARSET_NAME and collation
     COLLATION_NAME are used.

   * If 'CHARACTER SET CHARSET_NAME' is specified without 'COLLATE',
     character set CHARSET_NAME and its default collation are used.  To
     see the default collation for each character set, use the
     'SHOW CHARACTER SET' statement.

   * If 'COLLATE COLLATION_NAME' is specified without 'CHARACTER SET',
     the character set associated with COLLATION_NAME and collation
     COLLATION_NAME are used.

   * Otherwise (neither 'CHARACTER SET' nor 'COLLATE' is specified), the
     server character set and server collation are used.

The character set and collation for the default database can be
determined from the values of the 'character_set_database' and
'collation_database' system variables.  The server sets these variables
whenever the default database changes.  If there is no default database,
the variables have the same value as the corresponding server-level
system variables, 'character_set_server' and 'collation_server'.

To see the default character set and collation for a given database, use
these statements:

     USE DB_NAME;
     SELECT @@character_set_database, @@collation_database;

Alternatively, to display the values without changing the default
database:

     SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME
     FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = 'DB_NAME';

The database character set and collation affect these aspects of server
operation:

   * For 'CREATE TABLE' statements, the database
     character set and collation are used as default values for table
     definitions if the table character set and collation are not
     specified.  To override this, provide explicit 'CHARACTER SET' and
     'COLLATE' table options.

   * For 'LOAD DATA' statements that include no
     'CHARACTER SET' clause, the server uses the character set indicated
     by the 'character_set_database' system variable to interpret the
     information in the file.  To override this, provide an explicit
     'CHARACTER SET' clause.

   * For stored routines (procedures and functions), the database
     character set and collation in effect at routine creation time are
     used as the character set and collation of character data
     parameters for which the declaration includes no 'CHARACTER SET' or
     'COLLATE' attribute.  To override this, provide explicit 'CHARACTER
     SET' and 'COLLATE' attributes.

10.3.4 Table Character Set and Collation
----------------------------------------

Every table has a table character set and a table collation.  The
'CREATE TABLE' and 'ALTER TABLE'.
statements have optional clauses for specifying the table character set
and collation:

     CREATE TABLE TBL_NAME (COLUMN_LIST)
         [[DEFAULT] CHARACTER SET CHARSET_NAME]
         [COLLATE COLLATION_NAME]]

     ALTER TABLE TBL_NAME
         [[DEFAULT] CHARACTER SET CHARSET_NAME]
         [COLLATE COLLATION_NAME]

Example:

     CREATE TABLE t1 ( ... )
     CHARACTER SET latin1 COLLATE latin1_danish_ci;

MySQL chooses the table character set and collation in the following
manner:

   * If both 'CHARACTER SET CHARSET_NAME' and 'COLLATE COLLATION_NAME'
     are specified, character set CHARSET_NAME and collation
     COLLATION_NAME are used.

   * If 'CHARACTER SET CHARSET_NAME' is specified without 'COLLATE',
     character set CHARSET_NAME and its default collation are used.  To
     see the default collation for each character set, use the
     'SHOW CHARACTER SET' statement.

   * If 'COLLATE COLLATION_NAME' is specified without 'CHARACTER SET',
     the character set associated with COLLATION_NAME and collation
     COLLATION_NAME are used.

   * Otherwise (neither 'CHARACTER SET' nor 'COLLATE' is specified), the
     database character set and collation are used.

The table character set and collation are used as default values for
column definitions if the column character set and collation are not
specified in individual column definitions.  The table character set and
collation are MySQL extensions; there are no such things in standard
SQL.

10.3.5 Column Character Set and Collation
-----------------------------------------

Every 'character' column (that is, a column of type 'CHAR',
'VARCHAR', or 'TEXT') has a column character
set and a column collation.  Column definition syntax for 'CREATE TABLE'
and 'ALTER TABLE' has optional
clauses for specifying the column character set and collation:

     COL_NAME {CHAR | VARCHAR | TEXT} (COL_LENGTH)
         [CHARACTER SET CHARSET_NAME]
         [COLLATE COLLATION_NAME]

These clauses can also be used for 'ENUM' and 'SET'
columns:

     COL_NAME {ENUM | SET} (VAL_LIST)
         [CHARACTER SET CHARSET_NAME]
         [COLLATE COLLATION_NAME]

Examples:

     CREATE TABLE t1
     (
         col1 VARCHAR(5)
           CHARACTER SET latin1
           COLLATE latin1_german1_ci
     );

     ALTER TABLE t1 MODIFY
         col1 VARCHAR(5)
           CHARACTER SET latin1
           COLLATE latin1_swedish_ci;

MySQL chooses the column character set and collation in the following
manner:

   * If both 'CHARACTER SET CHARSET_NAME' and 'COLLATE COLLATION_NAME'
     are specified, character set CHARSET_NAME and collation
     COLLATION_NAME are used.

          CREATE TABLE t1
          (
              col1 CHAR(10) CHARACTER SET utf8 COLLATE utf8_unicode_ci
          ) CHARACTER SET latin1 COLLATE latin1_bin;

     The character set and collation are specified for the column, so
     they are used.  The column has character set 'utf8' and collation
     'utf8_unicode_ci'.

   * If 'CHARACTER SET CHARSET_NAME' is specified without 'COLLATE',
     character set CHARSET_NAME and its default collation are used.

          CREATE TABLE t1
          (
              col1 CHAR(10) CHARACTER SET utf8
          ) CHARACTER SET latin1 COLLATE latin1_bin;

     The character set is specified for the column, but the collation is
     not.  The column has character set 'utf8' and the default collation
     for 'utf8', which is 'utf8_general_ci'.  To see the default
     collation for each character set, use the 'SHOW CHARACTER SET'
     statement.

   * If 'COLLATE COLLATION_NAME' is specified without 'CHARACTER SET',
     the character set associated with COLLATION_NAME and collation
     COLLATION_NAME are used.

          CREATE TABLE t1
          (
              col1 CHAR(10) COLLATE utf8_polish_ci
          ) CHARACTER SET latin1 COLLATE latin1_bin;

     The collation is specified for the column, but the character set is
     not.  The column has collation 'utf8_polish_ci' and the character
     set is the one associated with the collation, which is 'utf8'.

   * Otherwise (neither 'CHARACTER SET' nor 'COLLATE' is specified), the
     table character set and collation are used.

          CREATE TABLE t1
          (
              col1 CHAR(10)
          ) CHARACTER SET latin1 COLLATE latin1_bin;

     Neither the character set nor collation is specified for the
     column, so the table defaults are used.  The column has character
     set 'latin1' and collation 'latin1_bin'.

The 'CHARACTER SET' and 'COLLATE' clauses are standard SQL.

If you use 'ALTER TABLE' to convert a column from
one character set to another, MySQL attempts to map the data values, but
if the character sets are incompatible, there may be data loss.

10.3.6 Character String Literal Character Set and Collation
-----------------------------------------------------------

Every character string literal has a character set and a collation.

For the simple statement 'SELECT 'STRING'', the string has the
connection default character set and collation defined by the
'character_set_connection' and 'collation_connection' system variables.

A character string literal may have an optional character set introducer
and 'COLLATE' clause, to designate it as a string that uses a particular
character set and collation:

     [_CHARSET_NAME]'STRING' [COLLATE COLLATION_NAME]

Character set introducers and the 'COLLATE' clause are implemented
according to standard SQL specifications.

Examples:

     SELECT 'abc';
     SELECT _latin1'abc';
     SELECT _binary'abc';
     SELECT _utf8'abc' COLLATE utf8_danish_ci;

The '_CHARSET_NAME' expression is formally called an _introducer_.  It
tells the parser, 'the string that follows uses character set
CHARSET_NAME.' An introducer does not change the string to the
introducer character set like 'CONVERT()' would do.  It does not change
the string value, although padding may occur.  The introducer is just a
signal.

MySQL determines the character set and collation of a character string
literal in the following manner:

   * If both _CHARSET_NAME and 'COLLATE COLLATION_NAME' are specified,
     character set CHARSET_NAME and collation COLLATION_NAME are used.
     COLLATION_NAME must be a permitted collation for CHARSET_NAME.

   * If _CHARSET_NAME is specified but 'COLLATE' is not specified,
     character set CHARSET_NAME and its default collation are used.  To
     see the default collation for each character set, use the
     'SHOW CHARACTER SET' statement.

   * If _CHARSET_NAME is not specified but 'COLLATE COLLATION_NAME' is
     specified, the connection default character set given by the
     'character_set_connection' system variable and collation
     COLLATION_NAME are used.  COLLATION_NAME must be a permitted
     collation for the connection default character set.

   * Otherwise (neither _CHARSET_NAME nor 'COLLATE COLLATION_NAME' is
     specified), the connection default character set and collation
     given by the 'character_set_connection' and 'collation_connection'
     system variables are used.

Examples:

   * A nonbinary string with 'latin1' character set and
     'latin1_german1_ci' collation:

          SELECT _latin1'Mu"ller' COLLATE latin1_german1_ci;

   * A nonbinary string with 'utf8' character set and its default
     collation (that is, 'utf8_general_ci'):

          SELECT _utf8'Mu"ller';

   * A binary string with 'binary' character set and its default
     collation (that is, 'binary'):

          SELECT _binary'Mu"ller';

   * A nonbinary string with the connection default character set and
     'utf8_general_ci' collation (fails if the connection character set
     is not 'utf8'):

          SELECT 'Mu"ller' COLLATE utf8_general_ci;

   * A string with the connection default character set and collation:

          SELECT 'Mu"ller';

An introducer indicates the character set for the following string, but
does not change how the parser performs escape processing within the
string.  Escapes are always interpreted by the parser according to the
character set given by 'character_set_connection'.

The following examples show that escape processing occurs using
'character_set_connection' even in the presence of an introducer.  The
examples use 'SET NAMES'. (which changes
'character_set_connection', as discussed in charset-connection),
and display the resulting strings using the 'HEX()' function so that the
exact string contents can be seen.

Example 1:

     mysql> SET NAMES latin1;
     mysql> SELECT HEX('a`\n'), HEX(_sjis'a`\n');
     +------------+-----------------+
     | HEX('a`\n')  | HEX(_sjis'a`\n')  |
     +------------+-----------------+
     | E00A       | E00A            |
     +------------+-----------------+

Here, 'a`' (hexadecimal value 'E0') is followed by '\n', the escape
sequence for newline.  The escape sequence is interpreted using the
'character_set_connection' value of 'latin1' to produce a literal
newline (hexadecimal value '0A').  This happens even for the second
string.  That is, the '_sjis' introducer does not affect the parser's
escape processing.

Example 2:

     mysql> SET NAMES sjis;
     mysql> SELECT HEX('a`\n'), HEX(_latin1'a`\n');
     +------------+-------------------+
     | HEX('a`\n')  | HEX(_latin1'a`\n')  |
     +------------+-------------------+
     | E05C6E     | E05C6E            |
     +------------+-------------------+

Here, 'character_set_connection' is 'sjis', a character set in which the
sequence of 'a`' followed by '\' (hexadecimal values '05' and '5C') is a
valid multibyte character.  Hence, the first two bytes of the string are
interpreted as a single 'sjis' character, and the '\' is not interpreted
as an escape character.  The following 'n' (hexadecimal value '6E') is
not interpreted as part of an escape sequence.  This is true even for
the second string; the '_latin1' introducer does not affect escape
processing.

10.3.7 The National Character Set
---------------------------------

Standard SQL defines 'NCHAR' or 'NATIONAL CHAR'
as a way to indicate that a 'CHAR' column should use
some predefined character set.  MySQL uses 'utf8' as this predefined
character set.  For example, these data type declarations are
equivalent:

     CHAR(10) CHARACTER SET utf8
     NATIONAL CHARACTER(10)
     NCHAR(10)

As are these:

     VARCHAR(10) CHARACTER SET utf8
     NATIONAL VARCHAR(10)
     NVARCHAR(10)
     NCHAR VARCHAR(10)
     NATIONAL CHARACTER VARYING(10)
     NATIONAL CHAR VARYING(10)

You can use 'N'LITERAL'' (or 'n'LITERAL'') to create a string in the
national character set.  These statements are equivalent:

     SELECT N'some text';
     SELECT n'some text';
     SELECT _utf8'some text';

10.3.8 Character Set Introducers
--------------------------------

A character string literal, hexadecimal literal, or bit-value literal
may have an optional character set introducer and 'COLLATE' clause, to
designate it as a string that uses a particular character set and
collation:

     [_CHARSET_NAME] LITERAL [COLLATE COLLATION_NAME]

Character set introducers and the 'COLLATE' clause are implemented
according to standard SQL specifications.

Examples:

     SELECT 'abc';
     SELECT _latin1'abc';
     SELECT _binary'abc';
     SELECT _utf8'abc' COLLATE utf8_danish_ci;

     SELECT _latin1 X'4D7953514C';
     SELECT _utf8 0x4D7953514C COLLATE utf8_danish_ci;

     SELECT _latin1 b'1000001';
     SELECT _utf8 0b1000001 COLLATE utf8_danish_ci;

The '_CHARSET_NAME' expression is formally called an _introducer_.  It
tells the parser, 'the string that follows uses character set
CHARSET_NAME.' An introducer does not change the string to the
introducer character set like 'CONVERT()' would do.  It does not change
the string value, although padding may occur.  The introducer is just a
signal.

For character string literals, space between the introducer and the
string is permitted but optional.

Character string literals can be designated as binary strings by using
the '_binary' introducer.  Hexadecimal literals and bit-value literals
are binary strings by default, so '_binary' is permitted, but
unnecessary.

MySQL determines the character set and collation of a character string
literal, hexadecimal literal, or bit-value literal in the following
manner:

   * If both _CHARSET_NAME and 'COLLATE COLLATION_NAME' are specified,
     character set CHARSET_NAME and collation COLLATION_NAME are used.
     COLLATION_NAME must be a permitted collation for CHARSET_NAME.

   * If _CHARSET_NAME is specified but 'COLLATE' is not specified,
     character set CHARSET_NAME and its default collation are used.  To
     see the default collation for each character set, use the
     'SHOW CHARACTER SET' statement.

   * If _CHARSET_NAME is not specified but 'COLLATE COLLATION_NAME' is
     specified:

        * For a character string literal, the connection default
          character set given by the 'character_set_connection' system
          variable and collation COLLATION_NAME are used.
          COLLATION_NAME must be a permitted collation for the
          connection default character set.

        * For a hexadecimal literal or bit-value literal, the only
          permitted collation is 'binary' because these types of
          literals are binary strings by default.

   * Otherwise (neither _CHARSET_NAME nor 'COLLATE COLLATION_NAME' is
     specified):

        * For a character string literal, the connection default
          character set and collation given by the
          'character_set_connection' and 'collation_connection' system
          variables are used.

        * For a hexadecimal literal or bit-value literal, the character
          set and collation are 'binary'.

Examples:

   * Nonbinary strings with 'latin1' character set and
     'latin1_german1_ci' collation:

          SELECT _latin1'Mu"ller' COLLATE latin1_german1_ci;
          SELECT _latin1 X'0A0D' COLLATE latin1_german1_ci;
          SELECT _latin1 b'0110' COLLATE latin1_german1_ci;

   * Nonbinary strings with 'utf8' character set and its default
     collation (that is, 'utf8_general_ci'):

          SELECT _utf8'Mu"ller';
          SELECT _utf8 X'0A0D';
          SELECT _utf8 b'0110';

   * Binary strings with 'binary' character set and its default
     collation (that is, 'binary'):

          SELECT _binary'Mu"ller';
          SELECT X'0A0D';
          SELECT b'0110';

     The hexadecimal literal and bit-value literal need no introducer
     because they are binary strings by default.

   * A nonbinary string with the connection default character set and
     'utf8_general_ci' collation (fails if the connection character set
     is not 'utf8'):

          SELECT 'Mu"ller' COLLATE utf8_general_ci;

     This construction ('COLLATE' only) does not work for hexadecimal
     literals or bit literals because their character set is 'binary' no
     matter the connection character set, and 'binary' is not compatible
     with the 'utf8_general_ci' collation.  The only permitted 'COLLATE'
     clause in the absence of an introducer is 'COLLATE binary'.

   * A string with the connection default character set and collation:

          SELECT 'Mu"ller';

For character set literals, an introducer indicates the character set
for the following string, but does not change how the parser performs
escape processing within the string.  Escapes are always interpreted by
the parser according to the character set given by
'character_set_connection'.  For additional discussion and examples, see
charset-literal.

10.3.9 Examples of Character Set and Collation Assignment
---------------------------------------------------------

The following examples show how MySQL determines default character set
and collation values.

*Example 1: Table and Column Definition*

     CREATE TABLE t1
     (
         c1 CHAR(10) CHARACTER SET latin1 COLLATE latin1_german1_ci
     ) DEFAULT CHARACTER SET latin2 COLLATE latin2_bin;

Here we have a column with a 'latin1' character set and a
'latin1_german1_ci' collation.  The definition is explicit, so that is
straightforward.  Notice that there is no problem with storing a
'latin1' column in a 'latin2' table.

*Example 2: Table and Column Definition*

     CREATE TABLE t1
     (
         c1 CHAR(10) CHARACTER SET latin1
     ) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;

This time we have a column with a 'latin1' character set and a default
collation.  Although it might seem natural, the default collation is not
taken from the table level.  Instead, because the default collation for
'latin1' is always 'latin1_swedish_ci', column 'c1' has a collation of
'latin1_swedish_ci' (not 'latin1_danish_ci').

*Example 3: Table and Column Definition*

     CREATE TABLE t1
     (
         c1 CHAR(10)
     ) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;

We have a column with a default character set and a default collation.
In this circumstance, MySQL checks the table level to determine the
column character set and collation.  Consequently, the character set for
column 'c1' is 'latin1' and its collation is 'latin1_danish_ci'.

*Example 4: Database, Table, and Column Definition*

     CREATE DATABASE d1
         DEFAULT CHARACTER SET latin2 COLLATE latin2_czech_ci;
     USE d1;
     CREATE TABLE t1
     (
         c1 CHAR(10)
     );

We create a column without specifying its character set and collation.
We're also not specifying a character set and a collation at the table
level.  In this circumstance, MySQL checks the database level to
determine the table settings, which thereafter become the column
settings.)  Consequently, the character set for column 'c1' is 'latin2'
and its collation is 'latin2_czech_ci'.

10.3.10 Compatibility with Other DBMSs
--------------------------------------

For MaxDB compatibility these two statements are the same:

     CREATE TABLE t1 (f1 CHAR(N) UNICODE);
     CREATE TABLE t1 (f1 CHAR(N) CHARACTER SET ucs2);

10.4 Connection Character Sets and Collations
=============================================

Several character set and collation system variables relate to a
client's interaction with the server.  Some of these have been mentioned
in earlier sections:

   * The server character set and collation are the values of the
     'character_set_server' and 'collation_server' system variables.

   * The character set and collation of the default database are the
     values of the 'character_set_database' and 'collation_database'
     system variables.

Additional character set and collation system variables are involved in
handling traffic for the connection between a client and the server.
Every client has connection-related character set and collation system
variables.

A 'connection' is what you make when you connect to the server.  The
client sends SQL statements, such as queries, over the connection to the
server.  The server sends responses, such as result sets or error
messages, over the connection back to the client.  This leads to several
questions about character set and collation handling for client
connections, each of which can be answered in terms of system variables:

   * What character set is the statement in when it leaves the client?

     The server takes the 'character_set_client' system variable to be
     the character set in which statements are sent by the client.

   * What character set should the server translate a statement to after
     receiving it?

     For this, the server uses the 'character_set_connection' and
     'collation_connection' system variables.  It converts statements
     sent by the client from 'character_set_client' to
     'character_set_connection', except for string literals that have an
     introducer (for example, '_utf8mb4' or '_latin2').
     'collation_connection' is important for comparisons of literal
     strings.  For comparisons of strings with column values,
     'collation_connection' does not matter because columns have their
     own collation, which has a higher collation precedence.

   * What character set should the server translate to before shipping
     result sets or error messages back to the client?

     The 'character_set_results' system variable indicates the character
     set in which the server returns query results to the client.  This
     includes result data such as column values, and result metadata
     such as column names and error messages.

Clients can fine-tune the settings for these variables, or depend on the
defaults (in which case, you can skip the rest of this section).  If you
do not use the defaults, you must change the character settings _for
each connection to the server._

Two statements affect the connection-related character set variables as
a group:

   * 'SET NAMES 'CHARSET_NAME' [COLLATE 'COLLATION_NAME']'

     'SET NAMES' indicates what character set the
     client will use to send SQL statements to the server.  Thus, see
     'SET NAMES 'cp1251'' tells the server, 'future incoming
     messages from this client are in character set 'cp1251'.' It also
     specifies the character set that the server should use for sending
     results back to the client.  (For example, it indicates what
     character set to use for column values if you use a 'SELECT'
     statement.)

     A 'SET NAMES 'CHARSET_NAME'' statement is
     equivalent to these three statements:

          SET character_set_client = CHARSET_NAME;
          SET character_set_results = CHARSET_NAME;
          SET character_set_connection = CHARSET_NAME;

     Setting 'character_set_connection' to CHARSET_NAME also implicitly
     sets 'collation_connection' to the default collation for
     CHARSET_NAME.  It is unnecessary to set that collation explicitly.
     To specify a particular collation, use the optional 'COLLATE'
     clause:

          SET NAMES 'CHARSET_NAME' COLLATE 'COLLATION_NAME'

   * 'SET CHARACTER SET 'CHARSET_NAME''

     'SET CHARACTER SET' is similar to
     'SET NAMES' but sets 'character_set_connection' and
     'collation_connection' to 'character_set_database' and
     'collation_database'.  A 'SET CHARACTER SET CHARSET_NAME'
     statement is equivalent to these three
     statements:

          SET character_set_client = CHARSET_NAME;
          SET character_set_results = CHARSET_NAME;
          SET collation_connection = @@collation_database;

     Setting 'collation_connection' also implicitly sets
     'character_set_connection' to the character set associated with the
     collation (equivalent to executing 'SET character_set_connection =
     @@character_set_database').  It is unnecessary to set
     'character_set_connection' explicitly.

*Note*:

'ucs2', 'utf16', 'utf16le', and 'utf32' cannot be used as a client
character set, which means that they do not work for 'SET NAMES'
or 'SET CHARACTER SET'.

The MySQL client programs 'mysql', 'mysqladmin',
see 'mysqlcheck', 'mysqlimport',
and 'mysqlshow' determine the default
character set to use as follows:

   * In the absence of other information, the programs use the
     compiled-in default character set, usually 'latin1'.

   * The programs can autodetect which character set to use based on the
     operating system setting, such as the value of the 'LANG' or
     'LC_ALL' locale environment variable on Unix systems or the code
     page setting on Windows systems.  For systems on which the locale
     is available from the OS, the client uses it to set the default
     character set rather than using the compiled-in default.  For
     example, setting 'LANG' to 'ru_RU.KOI8-R' causes the 'koi8r'
     character set to be used.  Thus, users can configure the locale in
     their environment for use by MySQL clients.

     The OS character set is mapped to the closest MySQL character set
     if there is no exact match.  If the client does not support the
     matching character set, it uses the compiled-in default.  For
     example, 'ucs2' is not supported as a connection character set.

     C applications can use character set autodetection based on the OS
     setting by invoking 'mysql_options()' as
     follows before connecting to the server:

          mysql_options(mysql,
                        MYSQL_SET_CHARSET_NAME,
                        MYSQL_AUTODETECT_CHARSET_NAME);

   * The programs support a '--default-character-set' option, which
     enables users to specify the character set explicitly to override
     whatever default the client otherwise determines.

When a client connects to the server, it sends the name of the character
set to be used for communication with the server.  The server uses the
name to set the 'character_set_client', 'character_set_results', and
'character_set_connection' system variables.  In effect, the server
performs a 'SET NAMES' operation using the character
set name.

With the 'mysql' client, to use a character set different
from the default, you could explicitly execute 'SET NAMES'
every time you start up.  To accomplish the same result more
easily, add the '--default-character-set' option setting to your
'mysql' command line or in your option file.  For example, the
following option file setting changes the three connection-related
character set variables set to 'koi8r' each time you invoke
'mysql'.:

     [mysql]
     default-character-set=koi8r

If you are using the 'mysql' client with auto-reconnect
enabled (which is not recommended), it is preferable to use the
'charset' command rather than 'SET NAMES'.  For
example:

     mysql> charset utf8
     Charset changed

The 'charset' command issues a 'SET NAMES' statement,
and also changes the default character set that 'mysql'.
uses when it reconnects after the connection has dropped.

Example: Suppose that 'column1' is defined as 'CHAR(5) CHARACTER SET
latin2'.  If you do not say 'SET NAMES' or 'SET CHARACTER SET',
then for 'SELECT column1 FROM t', the
server sends back all the values for 'column1' using the character set
that the client specified when it connected.  On the other hand, if you
say 'SET NAMES 'latin1'' or 'SET CHARACTER SET latin1' before issuing
the 'SELECT' statement, the server converts the 'latin2'
values to 'latin1' just before sending results back.  Conversion may be
lossy if there are characters that are not in both character sets.

If you want the server to perform no conversion of result sets or error
messages, set 'character_set_results' to 'NULL' or 'binary':

     SET character_set_results = NULL;
     SET character_set_results = binary;

To see the values of the character set and collation system variables
that apply to your connection, use these statements:

     SHOW VARIABLES LIKE 'character_set%';
     SHOW VARIABLES LIKE 'collation%';

You must also consider the environment within which your MySQL
applications execute.  See charset-applications.

For more information about character sets and error messages, see
charset-errors.

10.5 Configuring Application Character Set and Collation
========================================================

For applications that store data using the default MySQL character set
and collation ('latin1', 'latin1_swedish_ci'), no special configuration
should be needed.  If applications require data storage using a
different character set or collation, you can configure character set
information several ways:

   * Specify character settings per database.  For example, applications
     that use one database might require 'utf8', whereas applications
     that use another database might require 'sjis'.

   * Specify character settings at server startup.  This causes the
     server to use the given settings for all applications that do not
     make other arrangements.

   * Specify character settings at configuration time, if you build
     MySQL from source.  This causes the server to use the given
     settings for all applications, without having to specify them at
     server startup.

When different applications require different character settings, the
per-database technique provides a good deal of flexibility.  If most or
all applications use the same character set, specifying character
settings at server startup or configuration time may be most convenient.

For the per-database or server-startup techniques, the settings control
the character set for data storage.  Applications must also tell the
server which character set to use for client/server communications, as
described in the following instructions.

The examples shown here assume use of the 'utf8' character set and
'utf8_general_ci' collation.

*Specify character settings per database.*  To create a database such
that its tables will use a given default character set and collation for
data storage, use a 'CREATE DATABASE' statement
like this:

     CREATE DATABASE mydb
       DEFAULT CHARACTER SET utf8
       DEFAULT COLLATE utf8_general_ci;

Tables created in the database will use 'utf8' and 'utf8_general_ci' by
default for any character columns.

Applications that use the database should also configure their
connection to the server each time they connect.  This can be done by
executing a 'SET NAMES 'utf8'' statement after connecting.  The
statement can be used regardless of connection method: The
'mysql' client, PHP scripts, and so forth.

In some cases, it may be possible to configure the connection to use the
desired character set some other way.  For example, for connections made
using 'mysql', you can specify the
'--default-character-set=utf8' command-line option to achieve the same
effect as 'SET NAMES 'utf8''.

For more information about configuring client connections, see
charset-connection.

If you change the default character set or collation for a database,
stored routines that use the database defaults must be dropped and
recreated so that they use the new defaults.  (In a stored routine,
variables with character data types use the database defaults if the
character set or collation are not specified explicitly.  See
create-procedure.)

*Specify character settings at server startup.*  To select a character
set and collation at server startup, use the '--character-set-server'
and '--collation-server' options.  For example, to specify the options
in an option file, include these lines:

     [mysqld]
     character-set-server=utf8
     collation-server=utf8_general_ci

These settings apply server-wide and apply as the defaults for databases
created by any application, and for tables created in those databases.

It is still necessary for applications to configure their connection
using 'SET NAMES' or equivalent after they connect, as
described previously.  You might be tempted to start the server with the
'--init_connect="SET NAMES 'utf8'"' option to cause 'SET NAMES'
to be executed automatically for each client that connects.
However, this will yield inconsistent results because the 'init_connect'
value is not executed for users who have the 'SUPER' privilege.

*Specify character settings at MySQL configuration time.*  To select a
character set and collation when you configure and build MySQL from
source, use the 'DEFAULT_CHARSET' and 'DEFAULT_COLLATION' options for
'CMake':

     cmake . -DDEFAULT_CHARSET=utf8 \
       -DDEFAULT_COLLATION=utf8_general_ci

The resulting server uses 'utf8' and 'utf8_general_ci' as the default
for databases and tables and for client connections.  It is unnecessary
to use '--character-set-server' and '--collation-server' to specify
those defaults at server startup.  It is also unnecessary for
applications to configure their connection using 'SET NAMES'
or equivalent after they connect to the server.

Regardless of how you configure the MySQL character set for application
use, you must also consider the environment within which those
applications execute.  If you will send statements using UTF-8 text
taken from a file that you create in an editor, you should edit the file
with the locale of your environment set to UTF-8 so that the file
encoding is correct and so that the operating system handles it
correctly.  If you use the 'mysql' client from within a
terminal window, the window must be configured to use UTF-8 or
characters may not display properly.  For a script that executes in a
Web environment, the script must handle character encoding properly for
its interaction with the MySQL server, and it must generate pages that
correctly indicate the encoding so that browsers know how to display the
content of the pages.  For example, you can include this '<meta>' tag
within your '<head>' element:

     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

10.6 Error Message Character Set
================================

This section describes how the MySQL server uses character sets for
constructing error messages and returning them to clients.  For
information about the language of error messages (rather than the
character set), see error-message-language.  For general
information about configuring error logging, see error-log.

The server constructs error messages using UTF-8 and returns them to
clients in the character set specified by the 'character_set_results'
system variable.

The server constructs error messages as follows:

   * The message template uses UTF-8.

   * Parameters in the message template are replaced with values that
     apply to a specific error occurrence:

        * Identifiers such as table or column names use UTF-8 internally
          so they are copied as is.

        * Character (nonbinary) string values are converted from their
          character set to UTF-8.

        * Binary string values are copied as is for bytes in the range
          '0x20' to '0x7E', and using '\x' hexadecimal encoding for
          bytes outside that range.  For example, if a duplicate-key
          error occurs for an attempt to insert '0x41CF9F' into a
          'VARBINARY' unique column, the resulting
          error message uses UTF-8 with some bytes hexadecimal encoded:

               Duplicate entry 'A\xC3\x9F' for key 1

To return a message to the client after it has been constructed, the
server converts it from UTF-8 to the character set specified by the
'character_set_results' system variable.  If 'character_set_results' has
a value of 'NULL' or 'binary', no conversion occurs.  No conversion
occurs if the variable value is 'utf8', either, because that matches the
original error message character set.

For characters that cannot be represented in 'character_set_results',
some encoding may occur during the conversion.  The encoding uses
Unicode code point values:

   * Characters in the Basic Multilingual Plane (BMP) range ('0x0000' to
     '0xFFFF') are written using '\NNNN' notation.

   * Characters outside the BMP range ('0x10000' to '0x10FFFF') are
     written using '\+NNNNNN' notation.

Clients can set 'character_set_results' to control the character set in
which they receive error messages.  The variable can be set directly, or
indirectly by means such as 'SET NAMES'.  For more
information about 'character_set_results', see
charset-connection.

10.7 Column Character Set Conversion
====================================

To convert a binary or nonbinary string column to use a particular
character set, use 'ALTER TABLE'.  For successful
conversion to occur, one of the following conditions must apply:

   * If the column has a binary data type (see 'BINARY',
     see 'VARBINARY',
     'BLOB'), all the values that it contains must be encoded
     using a single character set (the character set you're converting
     the column to).  If you use a binary column to store information in
     multiple character sets, MySQL has no way to know which values use
     which character set and cannot convert the data properly.

   * If the column has a nonbinary data type (see 'CHAR',
     'VARCHAR', 'TEXT'), its contents should be
     encoded in the column character set, not some other character set.
     If the contents are encoded in a different character set, you can
     convert the column to use a binary data type first, and then to a
     nonbinary column with the desired character set.

Suppose that a table 't' has a binary column named 'col1' defined as
'VARBINARY(50)'.  Assuming that the information in the column is encoded
using a single character set, you can convert it to a nonbinary column
that has that character set.  For example, if 'col1' contains binary
data representing characters in the 'greek' character set, you can
convert it as follows:

     ALTER TABLE t MODIFY col1 VARCHAR(50) CHARACTER SET greek;

If your original column has a type of 'BINARY(50)', you could convert it
to 'CHAR(50)', but the resulting values will be padded with '0x00' bytes
at the end, which may be undesirable.  To remove these bytes, use the
'TRIM()' function:

     UPDATE t SET col1 = TRIM(TRAILING 0x00 FROM col1);

Suppose that table 't' has a nonbinary column named 'col1' defined as
'CHAR(50) CHARACTER SET latin1' but you want to convert it to use 'utf8'
so that you can store values from many languages.  The following
statement accomplishes this:

     ALTER TABLE t MODIFY col1 CHAR(50) CHARACTER SET utf8;

Conversion may be lossy if the column contains characters that are not
in both character sets.

A special case occurs if you have old tables from before MySQL 4.1 where
a nonbinary column contains values that actually are encoded in a
character set different from the server's default character set.  For
example, an application might have stored 'sjis' values in a column,
even though MySQL's default character set was 'latin1'.  It is possible
to convert the column to use the proper character set but an additional
step is required.  Suppose that the server's default character set was
'latin1' and 'col1' is defined as 'CHAR(50)' but its contents are 'sjis'
values.  The first step is to convert the column to a binary data type,
which removes the existing character set information without performing
any character conversion:

     ALTER TABLE t MODIFY col1 BLOB;

The next step is to convert the column to a nonbinary data type with the
proper character set:

     ALTER TABLE t MODIFY col1 CHAR(50) CHARACTER SET sjis;

This procedure requires that the table not have been modified already
with statements such as 'INSERT' or 'UPDATE'
after an upgrade to MySQL 4.1 or later.  In that case, MySQL
would store new values in the column using 'latin1', and the column will
contain a mix of 'sjis' and 'latin1' values and cannot be converted
properly.

If you specified attributes when creating a column initially, you should
also specify them when altering the table with 'ALTER TABLE'.
For example, if you specified 'NOT NULL' and an explicit
'DEFAULT' value, you should also provide them in the 'ALTER TABLE'
statement.  Otherwise, the resulting column
definition will not include those attributes.

To convert all character columns in a table, the 'ALTER TABLE ...
CONVERT TO CHARACTER SET CHARSET' statement may be useful.  See
alter-table.

10.8 Collation Issues
=====================

The following sections discuss various aspects of character set
collations.

10.8.1 Using COLLATE in SQL Statements
--------------------------------------

With the 'COLLATE' clause, you can override whatever the default
collation is for a comparison.  'COLLATE' may be used in various parts
of SQL statements.  Here are some examples:

   * With 'ORDER BY':

          SELECT k
          FROM t1
          ORDER BY k COLLATE latin1_german2_ci;

   * With 'AS':

          SELECT k COLLATE latin1_german2_ci AS k1
          FROM t1
          ORDER BY k1;

   * With 'GROUP BY':

          SELECT k
          FROM t1
          GROUP BY k COLLATE latin1_german2_ci;

   * With aggregate functions:

          SELECT MAX(k COLLATE latin1_german2_ci)
          FROM t1;

   * With 'DISTINCT':

          SELECT DISTINCT k COLLATE latin1_german2_ci
          FROM t1;

   * With 'WHERE':

               SELECT *
               FROM t1
               WHERE _latin1 'Mu"ller' COLLATE latin1_german2_ci = k;

               SELECT *
               FROM t1
               WHERE k LIKE _latin1 'Mu"ller' COLLATE latin1_german2_ci;

   * With 'HAVING':

          SELECT k
          FROM t1
          GROUP BY k
          HAVING k = _latin1 'Mu"ller' COLLATE latin1_german2_ci;

10.8.2 COLLATE Clause Precedence
--------------------------------

The 'COLLATE' clause has high precedence (higher than '||'), so the
following two expressions are equivalent:

     x || y COLLATE z
     x || (y COLLATE z)

10.8.3 Character Set and Collation Compatibility
------------------------------------------------

Each character set has one or more collations, but each collation is
associated with one and only one character set.  Therefore, the
following statement causes an error message because the 'latin2_bin'
collation is not legal with the 'latin1' character set:

     mysql> SELECT _latin1 'x' COLLATE latin2_bin;
     ERROR 1253 (42000): COLLATION 'latin2_bin' is not valid
     for CHARACTER SET 'latin1'

10.8.4 Collation Coercibility in Expressions
--------------------------------------------

In the great majority of statements, it is obvious what collation MySQL
uses to resolve a comparison operation.  For example, in the following
cases, it should be clear that the collation is the collation of column
'x':

     SELECT x FROM T ORDER BY x;
     SELECT x FROM T WHERE x = x;
     SELECT DISTINCT x FROM T;

However, with multiple operands, there can be ambiguity.  For example:

     SELECT x FROM T WHERE x = 'Y';

Should the comparison use the collation of the column 'x', or of the
string literal ''Y''?  Both 'x' and ''Y'' have collations, so which
collation takes precedence?

A mix of collations may also occur in contexts other than comparison.
For example, a multiple-argument concatenation operation such as
'CONCAT(x,'Y')' combines its arguments to produce a single string.  What
collation should the result have?

To resolve questions like these, MySQL checks whether the collation of
one item can be coerced to the collation of the other.  MySQL assigns
coercibility values as follows:

   * An explicit 'COLLATE' clause has a coercibility of 0 (not coercible
     at all).

   * The concatenation of two strings with different collations has a
     coercibility of 1.

   * The collation of a column or a stored routine parameter or local
     variable has a coercibility of 2.

   * A 'system constant' (the string returned by functions such as
     'USER()' or 'VERSION()') has a coercibility of 3.

   * The collation of a literal has a coercibility of 4.

   * The collation of a numeric or temporal value has a coercibility of
     5.

   * 'NULL' or an expression that is derived from 'NULL' has a
     coercibility of 6.

MySQL uses coercibility values with the following rules to resolve
ambiguities:

   * Use the collation with the lowest coercibility value.

   * If both sides have the same coercibility, then:

        * If both sides are Unicode, or both sides are not Unicode, it
          is an error.

        * If one of the sides has a Unicode character set, and another
          side has a non-Unicode character set, the side with Unicode
          character set wins, and automatic character set conversion is
          applied to the non-Unicode side.  For example, the following
          statement does not return an error:

               SELECT CONCAT(utf8_column, latin1_column) FROM t1;

          It returns a result that has a character set of 'utf8' and the
          same collation as 'utf8_column'.  Values of 'latin1_column'
          are automatically converted to 'utf8' before concatenating.

        * For an operation with operands from the same character set but
          that mix a '_bin' collation and a '_ci' or '_cs' collation,
          the '_bin' collation is used.  This is similar to how
          operations that mix nonbinary and binary strings evaluate the
          operands as binary strings, except that it is for collations
          rather than data types.

Although automatic conversion is not in the SQL standard, the standard
does say that every character set is (in terms of supported characters)
a 'subset' of Unicode.  Because it is a well-known principle that 'what
applies to a superset can apply to a subset,' we believe that a
collation for Unicode can apply for comparisons with non-Unicode
strings.

The following table illustrates some applications of the preceding
rules.

Comparison                           Collation Used

'column1 = 'A''                      Use collation of 'column1'

'column1 = 'A' COLLATE x'            Use collation of ''A' COLLATE x'

'column1 COLLATE x = 'A' COLLATE     Error
y'

To determine the coercibility of a string expression, use the
'COERCIBILITY()' function (see information-functions):

     mysql> SELECT COERCIBILITY('A' COLLATE latin1_swedish_ci);
             -> 0
     mysql> SELECT COERCIBILITY(VERSION());
             -> 3
     mysql> SELECT COERCIBILITY('A');
             -> 4
     mysql> SELECT COERCIBILITY(1000);
             -> 5

For implicit conversion of a numeric or temporal value to a string, such
as occurs for the argument '1' in the expression 'CONCAT(1, 'abc')', the
result is a character (nonbinary) string that has a character set and
collation determined by the 'character_set_connection' and
'collation_connection' system variables.  See type-conversion.

10.8.5 The binary Collation Compared to _bin Collations
-------------------------------------------------------

This section describes how the 'binary' collation for binary strings
compares to the '_bin' collations for nonbinary strings.

Binary strings (as stored using the 'BINARY',
'VARBINARY', and 'BLOB' data types)
have a character set and collation named 'binary'.  Binary strings are
sequences of bytes and the numeric values of those bytes determine
comparison and sort order.

Nonbinary strings (as stored using the 'CHAR',
'VARCHAR', and 'TEXT' data types) have a character
set and collation other than 'binary'.  A given nonbinary character set
can have several collations, each of which defines a particular
comparison and sort order for the characters in the set.  One of these
is the binary collation for the character set, indicated by a '_bin'
suffix in the collation name.  For example, the binary collations for
'latin1' and 'utf8' are named 'latin1_bin' and 'utf8_bin', respectively.

The 'binary' collation differs from the '_bin' collations in several
respects.

The unit for comparison and sorting

Binary strings are sequences of bytes.  For the 'binary' collation,
comparison and sorting are based on numeric byte values.  Nonbinary
strings are sequences of characters, which might be multibyte.
Collations for nonbinary strings define an ordering of the character
values for comparison and sorting.  For the '_bin' collation, this
ordering is based on numeric character code values, which is similar to
ordering for binary strings except that character code values might be
multibyte.

Character set conversion

A nonbinary string has a character set and is automatically converted to
another character set in many cases, even when the string has a '_bin'
collation:

   * When assigning column values from another column that has a
     different character set:

          UPDATE t1 SET utf8_bin_column=latin1_column;
          INSERT INTO t1 (latin1_column) SELECT utf8_bin_column FROM t2;

   * When assigning column values for 'INSERT' or
     'UPDATE' using a string literal:

          SET NAMES latin1;
          INSERT INTO t1 (utf8_bin_column) VALUES ('string-in-latin1');

   * When sending results from the server to a client:

          SET NAMES latin1;
          SELECT utf8_bin_column FROM t2;

For binary string columns, no conversion occurs.  For the preceding
cases, the string value is copied byte-wise.

Lettercase conversion

Collations for nonbinary character sets provide information about
lettercase of characters, so characters in a nonbinary string can be
converted from one lettercase to another, even for '_bin' collations
that ignore lettercase for ordering:

     mysql> SET NAMES latin1 COLLATE latin1_bin;
     mysql> SELECT LOWER('aA'), UPPER('zZ');
     +-------------+-------------+
     | LOWER('aA') | UPPER('zZ') |
     +-------------+-------------+
     | aa          | ZZ          |
     +-------------+-------------+

The concept of lettercase does not apply to bytes in a binary string.
To perform lettercase conversion, the string must be converted to a
nonbinary string:

     mysql> SET NAMES binary;
     mysql> SELECT LOWER('aA'), LOWER(CONVERT('aA' USING latin1));
     +-------------+-----------------------------------+
     | LOWER('aA') | LOWER(CONVERT('aA' USING latin1)) |
     +-------------+-----------------------------------+
     | aA          | aa                                |
     +-------------+-----------------------------------+

Trailing space handling in comparisons

Nonbinary strings have PAD SPACE behavior for all collations, including
'_bin' collations.  Trailing spaces are insignificant in comparisons:

     mysql> SET NAMES utf8 COLLATE utf8_bin;
     mysql> SELECT 'a ' = 'a';
     +------------+
     | 'a ' = 'a' |
     +------------+
     |          1 |
     +------------+

For binary strings, all characters are significant in comparisons,
including trailing spaces:

     mysql> SET NAMES binary;
     mysql> SELECT 'a ' = 'a';
     +------------+
     | 'a ' = 'a' |
     +------------+
     |          0 |
     +------------+

Trailing space handling for inserts and retrievals

'CHAR(N)' columns store nonbinary strings.  Values shorter than N
characters are extended with spaces on insertion.  For retrieval,
trailing spaces are removed.

'BINARY(N)' columns store binary strings.  Values shorter than N bytes
are extended with '0x00' bytes on insertion.  For retrieval, nothing is
removed; a value of the declared length is always returned.

     mysql> CREATE TABLE t1 (
              a CHAR(10) CHARACTER SET utf8 COLLATE utf8_bin,
              b BINARY(10)
            );
     mysql> INSERT INTO t1 VALUES ('a','a');
     mysql> SELECT HEX(a), HEX(b) FROM t1;
     +--------+----------------------+
     | HEX(a) | HEX(b)               |
     +--------+----------------------+
     | 61     | 61000000000000000000 |
     +--------+----------------------+

10.8.6 Examples of the Effect of Collation
------------------------------------------

*Example 1: Sorting German Umlauts*

Suppose that column 'X' in table 'T' has these 'latin1' column values:

     Muffler
     Mu"ller
     MX Systems
     MySQL

Suppose also that the column values are retrieved using the following
statement:

     SELECT X FROM T ORDER BY X COLLATE COLLATION_NAME;

The following table shows the resulting order of the values if we use
'ORDER BY' with different collations.

'latin1_swedish_ci'    'latin1_german1_ci'    'latin1_german2_ci'

Muffler                Muffler                Mu"ller

MX Systems             Mu"ller                Muffler

Mu"ller                MX Systems             MX Systems

MySQL                  MySQL                  MySQL

The character that causes the different sort orders in this example is
the U with two dots over it ('u"'), which the Germans call 'U-umlaut.'

   * The first column shows the result of the 'SELECT'.
     using the Swedish/Finnish collating rule, which says that U-umlaut
     sorts with Y.

   * The second column shows the result of the 'SELECT'.
     using the German DIN-1 rule, which says that U-umlaut sorts with U.

   * The third column shows the result of the 'SELECT'.
     using the German DIN-2 rule, which says that U-umlaut sorts with
     UE.

*Example 2: Searching for German Umlauts*

Suppose that you have three tables that differ only by the character set
and collation used:

     mysql> SET NAMES utf8;
     mysql> CREATE TABLE german1 (
              c CHAR(10)
            ) CHARACTER SET latin1 COLLATE latin1_german1_ci;
     mysql> CREATE TABLE german2 (
              c CHAR(10)
            ) CHARACTER SET latin1 COLLATE latin1_german2_ci;
     mysql> CREATE TABLE germanutf8 (
              c CHAR(10)
            ) CHARACTER SET utf8 COLLATE utf8_unicode_ci;

Each table contains two records:

     mysql> INSERT INTO german1 VALUES ('Bar'), ('Ba"r');
     mysql> INSERT INTO german2 VALUES ('Bar'), ('Ba"r');
     mysql> INSERT INTO germanutf8 VALUES ('Bar'), ('Ba"r');

Two of the above collations have an 'A = A"' equality, and one has no
such equality ('latin1_german2_ci').  For that reason, you'll get these
results in comparisons:

     mysql> SELECT * FROM german1 WHERE c = 'Ba"r';
     +------+
     | c    |
     +------+
     | Bar  |
     | Ba"r  |
     +------+
     mysql> SELECT * FROM german2 WHERE c = 'Ba"r';
     +------+
     | c    |
     +------+
     | Ba"r  |
     +------+
     mysql> SELECT * FROM germanutf8 WHERE c = 'Ba"r';
     +------+
     | c    |
     +------+
     | Bar  |
     | Ba"r  |
     +------+

This is not a bug but rather a consequence of the sorting properties of
'latin1_german1_ci' and 'utf8_unicode_ci' (the sorting shown is done
according to the German DIN 5007 standard).

10.8.7 Using Collation in INFORMATION_SCHEMA Searches
-----------------------------------------------------

String columns in 'INFORMATION_SCHEMA' tables have a collation of
'utf8_general_ci', which is case insensitive.  However, for values that
correspond to objects that are represented in the file system, such as
databases and tables, searches in 'INFORMATION_SCHEMA' string columns
can be case-sensitive or insensitive, depending on the characteristics
of the underlying file system and the value of the
'lower_case_table_names' system variable.  For example, searches may be
case-sensitive if the file system is case-sensitive.  This section
describes this behavior and how to modify it if necessary; see also Bug
#34921.

Suppose that a query searches the 'SCHEMATA.SCHEMA_NAME' column for the
'test' database.  On Linux, file systems are case-sensitive, so
comparisons of 'SCHEMATA.SCHEMA_NAME' with ''test'' match, but
comparisons with ''TEST'' do not:

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME = 'test';
     +-------------+
     | SCHEMA_NAME |
     +-------------+
     | test        |
     +-------------+

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME = 'TEST';
     Empty set (0.00 sec)

These results occur with the 'lower_case_table_names' system system
variable set to 0.  Changing the value of 'lower_case_table_names' to 1
or 2 causes the second query to return the same (nonempty) result as the
first query.

On Windows or OS X, file systems are not case-sensitive, so comparisons
match both ''test'' and ''TEST'':

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME = 'test';
     +-------------+
     | SCHEMA_NAME |
     +-------------+
     | test        |
     +-------------+

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME = 'TEST';
     +-------------+
     | SCHEMA_NAME |
     +-------------+
     | TEST        |
     +-------------+

The value of 'lower_case_table_names' makes no difference in this
context.

The preceding behavior occurs because the 'utf8_general_ci' collation is
not used for 'INFORMATION_SCHEMA' queries when searching for values that
correspond to objects represented in the file system.  It is a result of
file system-scanning optimizations implemented for 'INFORMATION_SCHEMA'
searches.  For information about these optimizations, see
information-schema-optimization.

If the result of a string operation on an 'INFORMATION_SCHEMA' column
differs from expectations, a workaround is to use an explicit 'COLLATE'
clause to force a suitable collation (see charset-collate).  For
example, to perform a case-insensitive search, use 'COLLATE' with the
'INFORMATION_SCHEMA' column name:

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME COLLATE utf8_general_ci = 'test';
     +-------------+
     | SCHEMA_NAME |
     +-------------+
     | test        |
     +-------------+

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME COLLATE utf8_general_ci = 'TEST';
     +-------------+
     | SCHEMA_NAME |
     +-------------+
     | test        |
     +-------------+

In the preceding queries, it is important to apply the 'COLLATE' clause
to the 'INFORMATION_SCHEMA' column name.  Applying 'COLLATE' to the
comparison value has no effect.

You can also use the 'UPPER()' or 'LOWER()' function:

     WHERE UPPER(SCHEMA_NAME) = 'TEST'
     WHERE LOWER(SCHEMA_NAME) = 'test'

Although a case-insensitive comparison can be performed even on
platforms with case-sensitive file systems, as just shown, it is not
necessarily always the right thing to do.  On such platforms, it is
possible to have multiple objects with names that differ only in
lettercase.  For example, tables named 'city', 'CITY', and 'City' can
all exist simultaneously.  Consider whether a search should match all
such names or just one and write queries accordingly.  The first of the
following comparisons (with 'utf8_bin') is case sensitive; the others
are not:

     WHERE TABLE_NAME COLLATE utf8_bin = 'City'
     WHERE TABLE_NAME COLLATE utf8_general_ci = 'city'
     WHERE UPPER(TABLE_NAME) = 'CITY'
     WHERE LOWER(TABLE_NAME) = 'city'

Searches in 'INFORMATION_SCHEMA' string columns for values that refer to
'INFORMATION_SCHEMA' itself do use the 'utf8_general_ci' collation
because 'INFORMATION_SCHEMA' is a 'virtual' database not represented in
the file system.  For example, comparisons with 'SCHEMATA.SCHEMA_NAME'
match ''information_schema'' or ''INFORMATION_SCHEMA'' regardless of
platform:

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME = 'information_schema';
     +--------------------+
     | SCHEMA_NAME        |
     +--------------------+
     | information_schema |
     +--------------------+

     mysql> SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA
            WHERE SCHEMA_NAME = 'INFORMATION_SCHEMA';
     +--------------------+
     | SCHEMA_NAME        |
     +--------------------+
     | information_schema |
     +--------------------+

10.9 Unicode Support
====================

The Unicode Standard includes characters from the Basic Multilingual
Plane (BMP) and supplementary characters that lie outside the BMP. This
section describes support for Unicode in MySQL. For information about
the Unicode Standard itself, visit the Unicode Consortium website
(http://www.unicode.org/).

BMP characters have these characteristics:

   * Their code point values are between 0 and 65535 (or 'U+0000' and
     'U+FFFF').

   * They can be encoded in a variable-length encoding using 8, 16, or
     24 bits (1 to 3 bytes).

   * They can be encoded in a fixed-length encoding using 16 bits (2
     bytes).

   * They are sufficient for almost all characters in major languages.

Supplementary characters lie outside the BMP:

   * Their code point values are between 'U+10000' and 'U+10FFFF').

   * Unicode support for supplementary characters requires character
     sets that have a range outside BMP characters and therefore take
     more space than BMP characters (up to 4 bytes per character).

The UTF-8 (Unicode Transformation Format with 8-bit units) method for
encoding Unicode data is implemented according to RFC 3629, which
describes encoding sequences that take from one to four bytes.  The idea
of UTF-8 is that various Unicode characters are encoded using byte
sequences of different lengths:

   * Basic Latin letters, digits, and punctuation signs use one byte.

   * Most European and Middle East script letters fit into a 2-byte
     sequence: extended Latin letters (with tilde, macron, acute, grave
     and other accents), Cyrillic, Greek, Armenian, Hebrew, Arabic,
     Syriac, and others.

   * Korean, Chinese, and Japanese ideographs use 3-byte or 4-byte
     sequences.

MySQL supports these Unicode character sets:

   * 'utf8mb4': A UTF-8 encoding of the Unicode character set using one
     to four bytes per character.

   * 'utf8mb3': A UTF-8 encoding of the Unicode character set using one
     to three bytes per character.

   * 'utf8': An alias for 'utfmb3'.

   * 'ucs2': The UCS-2 encoding of the Unicode character set using two
     bytes per character.

   * 'utf16': The UTF-16 encoding for the Unicode character set using
     two or four bytes per character.  Like 'ucs2' but with an extension
     for supplementary characters.

   * 'utf16le': The UTF-16LE encoding for the Unicode character set.
     Like 'utf16' but little-endian rather than big-endian.

   * 'utf32': The UTF-32 encoding for the Unicode character set using
     four bytes per character.

See charset-unicode-charset-characteristics, summarizes the general
characteristics of Unicode character sets supported by MySQL.

*Unicode Character Set General Characteristics*

Character      Supported Characters          Required Storage Per
Set                                          Character

'utf8mb3',     BMP only                      1, 2, or 3 bytes
'utf8'

'ucs2'         BMP only                      2 bytes

'utf8mb4'      BMP and supplementary         1, 2, 3, or 4 bytes

'utf16'        BMP and supplementary         2 or 4 bytes

'utf16le'      BMP and supplementary         2 or 4 bytes

'utf32'        BMP and supplementary         4 bytes

Characters outside the BMP compare as REPLACEMENT CHARACTER and convert
to ''?'' when converted to a Unicode character set that supports only
BMP characters ('utf8mb3' or 'ucs2').

If you use character sets that support supplementary characters and thus
are 'wider' than the BMP-only 'utf8mb3' and 'ucs2' character sets, there
are potential incompatibility issues for your applications; see
charset-unicode-conversion.  That section also describes how to
convert tables from the (3-byte) 'utf8mb3' to the (4-byte) 'utf8mb4',
and what constraints may apply in doing so.

A similar set of collations is available for most Unicode character
sets.  For example, each has a Danish collation, the names of which are
'utf8mb4_danish_ci', 'utf8mb3_danish_ci', 'utf8_danish_ci',
'ucs2_danish_ci', 'utf16_danish_ci', and 'utf32_danish_ci'.  The
exception is 'utf16le', which has only two collations.  For information
about Unicode collations and their differentiating properties, including
collation properties for supplementary characters, see
charset-unicode-sets.

The MySQL implementation of UCS-2, UTF-16, and UTF-32 stores characters
in big-endian byte order and does not use a byte order mark (BOM) at the
beginning of values.  Other database systems might use little-endian
byte order or a BOM. In such cases, conversion of values will need to be
performed when transferring data between those systems and MySQL. The
implementation of UTF-16LE is little-endian.

MySQL uses no BOM for UTF-8 values.

Client applications that communicate with the server using Unicode
should set the client character set accordingly; for example, by issuing
a 'SET NAMES 'utf8mb4'' statement.  'ucs2', 'utf16', 'utf16le', and
'utf32' cannot be used as a client character set, which means that they
do not work for 'SET NAMES' or 'SET CHARACTER SET'.
(See charset-connection.)

The following sections provide additional detail on the Unicode
character sets in MySQL.

10.9.1 The utf8mb4 Character Set (4-Byte UTF-8 Unicode Encoding)
----------------------------------------------------------------

The 'utfmb4' character set has these characteristics:

   * Supports BMP and supplementary characters.

   * Requires a maximum of four bytes per multibyte character.

'utf8mb4' contrasts with the 'utf8mb3' character set, which supports
only BMP characters and uses a maximum of three bytes per character:

   * For a BMP character, 'utf8mb4' and 'utf8mb3' have identical storage
     characteristics: same code values, same encoding, same length.

   * For a supplementary character, 'utf8mb4' requires four bytes to
     store it, whereas 'utf8mb3' cannot store the character at all.
     When converting 'utfmb3' columns to 'utf8mb4', you need not worry
     about converting supplementary characters because there will be
     none.

'utf8mb4' is a superset of 'utf8mb3', so for an operation such as the
following concatenation, the result has character set 'utf8mb4' and the
collation of 'utf8mb4_col':

     SELECT CONCAT(utf8mb3_col, utf8mb4_col);

Similarly, the following comparison in the 'WHERE' clause works
according to the collation of 'utf8mb4_col':

     SELECT * FROM utf8mb3_tbl, utf8mb4_tbl
     WHERE utf8mb3_tbl.utf8mb3_col = utf8mb4_tbl.utf8mb4_col;

*Tip*:

To save space with 'utf8mb4', use 'VARCHAR' instead of
'CHAR'.  Otherwise, MySQL must reserve four bytes for each
character in a 'CHAR' column that uses 'utf8mb4' because
that is the maximum possible length.  For example, MySQL must reserve 40
bytes for a 'CHAR(10)' column that uses 'utf8mb4'.

For additional information about data type storage, see
storage-requirements.  For information about 'InnoDB' physical row
storage, including how 'InnoDB' tables that use 'COMPACT' row format
handle UTF-8 'CHAR(N)' columns internally, see
innodb-physical-record.

10.9.2 The utf8mb3 Character Set (3-Byte UTF-8 Unicode Encoding)
----------------------------------------------------------------

The 'utfmb3' character set has these characteristics:

   * Supports BMP characters only (no support for supplementary
     characters)

   * Requires a maximum of three bytes per multibyte character.

Applications that use UTF-8 data but require supplementary character
support should use 'utf8mb4' rather than 'utf8mb3' (see
charset-unicode-utf8mb4).

Exactly the same set of characters is available in 'utf8mb3' and 'ucs2'.
That is, they have the same repertoire.

'utf8' is an alias for 'utf8mb3'; the character limit is implicit,
rather than explicit in the name.

'utf8mb3' can be used in 'CHARACTER SET' clauses, and
'utf8mb3_COLLATION_SUBSTRING' in 'COLLATE' clauses, where
COLLATION_SUBSTRING is 'bin', 'czech_ci', 'danish_ci', 'esperanto_ci',
'estonian_ci', and so forth.  For example:

     CREATE TABLE t (s1 CHAR(1) CHARACTER SET utf8mb3;
     SELECT * FROM t WHERE s1 COLLATE utf8mb3_general_ci = 'x';
     DECLARE x VARCHAR(5) CHARACTER SET utf8mb3 COLLATE utf8mb3_danish_ci;
     SELECT CAST('a' AS CHAR CHARACTER SET utf8) COLLATE utf8_czech_ci;

MySQL immediately converts instances of 'utf8mb3' in statements to
'utf8', so in statements such as 'SHOW CREATE TABLE' or 'SELECT
CHARACTER_SET_NAME FROM INFORMATION_SCHEMA.COLUMNS' or 'SELECT
COLLATION_NAME FROM INFORMATION_SCHEMA.COLUMNS', users will see the name
'utf8' or 'utf8_COLLATION_SUBSTRING'.

'utf8mb3' is also valid in contexts other than 'CHARACTER SET' clauses.
For example:

     mysqld --character-set-server=utf8mb3

     SET NAMES 'utf8mb3'; /* and other SET statements that have similar effect */
     SELECT _utf8mb3 'a';

*Tip*:

To save space with 'utf8mb3', use 'VARCHAR' instead of
'CHAR'.  Otherwise, MySQL must reserve three bytes for each
character in a 'CHAR' column that uses 'utf8mb3' because
that is the maximum possible length.  For example, MySQL must reserve 30
bytes for a 'CHAR(10)' column that uses 'utf8mb3'.

For additional information about data type storage, see
storage-requirements.  For information about 'InnoDB' physical row
storage, including how 'InnoDB' tables that use 'COMPACT' row format
handle UTF-8 'CHAR(N)' columns internally, see
innodb-physical-record.

10.9.3 The utf8 Character Set (Alias for utf8mb3)
-------------------------------------------------

'utf8' is an alias for the 'utfmb3' character set.  For more
information, see charset-unicode-utf8mb3.

10.9.4 The ucs2 Character Set (UCS-2 Unicode Encoding)
------------------------------------------------------

In UCS-2, every character is represented by a 2-byte Unicode code with
the most significant byte first.  For example: 'LATIN CAPITAL LETTER A'
has the code '0x0041' and it is stored as a 2-byte sequence: '0x00
0x41'.  'CYRILLIC SMALL LETTER YERU' (Unicode '0x044B') is stored as a
2-byte sequence: '0x04 0x4B'.  For Unicode characters and their codes,
please refer to the Unicode Consortium website
(http://www.unicode.org/).

The 'ucs2' character set has these characteristics:

   * Supports BMP characters only (no support for supplementary
     characters)

   * Uses a fixed-length 16-bit encoding and requires two bytes per
     character.

10.9.5 The utf16 Character Set (UTF-16 Unicode Encoding)
--------------------------------------------------------

The 'utf16' character set is the 'ucs2' character set with an extension
that enables encoding of supplementary characters:

   * For a BMP character, 'utf16' and 'ucs2' have identical storage
     characteristics: same code values, same encoding, same length.

   * For a supplementary character, 'utf16' has a special sequence for
     representing the character using 32 bits.  This is called the
     'surrogate' mechanism: For a number greater than '0xffff', take 10
     bits and add them to '0xd800' and put them in the first 16-bit
     word, take 10 more bits and add them to '0xdc00' and put them in
     the next 16-bit word.  Consequently, all supplementary characters
     require 32 bits, where the first 16 bits are a number between
     '0xd800' and '0xdbff', and the last 16 bits are a number between
     '0xdc00' and '0xdfff'.  Examples are in Section 15.5 Surrogates
     Area (http://www.unicode.org/versions/Unicode4.0.0/ch15.pdf) of the
     Unicode 4.0 document.

Because 'utf16' supports surrogates and 'ucs2' does not, there is a
validity check that applies only in 'utf16': You cannot insert a top
surrogate without a bottom surrogate, or vice versa.  For example:

     INSERT INTO t (ucs2_column) VALUES (0xd800); /* legal */
     INSERT INTO t (utf16_column)VALUES (0xd800); /* illegal */

There is no validity check for characters that are technically valid but
are not true Unicode (that is, characters that Unicode considers to be
'unassigned code points' or 'private use' characters or even 'illegals'
like '0xffff').  For example, since 'U+F8FF' is the Apple Logo, this is
legal:

     INSERT INTO t (utf16_column)VALUES (0xf8ff); /* legal */

Such characters cannot be expected to mean the same thing to everyone.

Because MySQL must allow for the worst case (that one character requires
four bytes) the maximum length of a 'utf16' column or index is only half
of the maximum length for a 'ucs2' column or index.  For example, the
maximum length of a 'MEMORY' table index key is 3072 bytes, so these
statements create tables with the longest permitted indexes for 'ucs2'
and 'utf16' columns:

     CREATE TABLE tf (s1 VARCHAR(1536) CHARACTER SET ucs2) ENGINE=MEMORY;
     CREATE INDEX i ON tf (s1);
     CREATE TABLE tg (s1 VARCHAR(768) CHARACTER SET utf16) ENGINE=MEMORY;
     CREATE INDEX i ON tg (s1);

10.9.6 The utf16le Character Set (UTF-16LE Unicode Encoding)
------------------------------------------------------------

This is the same as 'utf16' but is little-endian rather than big-endian.

10.9.7 The utf32 Character Set (UTF-32 Unicode Encoding)
--------------------------------------------------------

The 'utf32' character set is fixed length (like 'ucs2' and unlike
'utf16').  'utf32' uses 32 bits for every character, unlike 'ucs2'
(which uses 16 bits for every character), and unlike 'utf16' (which uses
16 bits for some characters and 32 bits for others).

'utf32' takes twice as much space as 'ucs2' and more space than 'utf16',
but 'utf32' has the same advantage as 'ucs2' that it is predictable for
storage: The required number of bytes for 'utf32' equals the number of
characters times 4.  Also, unlike 'utf16', there are no tricks for
encoding in 'utf32', so the stored value equals the code value.

To demonstrate how the latter advantage is useful, here is an example
that shows how to determine a 'utf8mb4' value given the 'utf32' code
value:

     /* Assume code value = 100cc LINEAR B WHEELED CHARIOT */
     CREATE TABLE tmp (utf32_col CHAR(1) CHARACTER SET utf32,
                       utf8mb4_col CHAR(1) CHARACTER SET utf8mb4);
     INSERT INTO tmp VALUES (0x000100cc,NULL);
     UPDATE tmp SET utf8mb4_col = utf32_col;
     SELECT HEX(utf32_col),HEX(utf8mb4_col) FROM tmp;

MySQL is very forgiving about additions of unassigned Unicode characters
or private-use-area characters.  There is in fact only one validity
check for 'utf32': No code value may be greater than '0x10ffff'.  For
example, this is illegal:

     INSERT INTO t (utf32_column) VALUES (0x110000); /* illegal */

10.9.8 Converting Between 3-Byte and 4-Byte Unicode Character Sets
------------------------------------------------------------------

This section describes issues that you may face when converting
character data between the 'utf8mb3' and 'utf8mb4' character sets.

*Note*:

This discussion focuses primarily on converting between 'utf8mb3' and
'utf8mb4', but similar principles apply to converting between the 'ucs2'
character set and character sets such as 'utf16' or 'utf32'.

The 'utf8mb3' and 'utf8mb4' character sets differ as follows:

   * 'utf8mb3' supports only characters in the Basic Multilingual Plane
     (BMP). 'utf8mb4' additionally supports supplementary characters
     that lie outside the BMP.

   * 'utf8mb3' uses a maximum of three bytes per character.  'utf8mb4'
     uses a maximum of four bytes per character.

*Note*:

This discussion refers to the 'utf8mb3' and 'utf8mb4' character set
names to be explicit about referring to 3-byte and 4-byte UTF-8
character set data.  The exception is that in table definitions, 'utf8'
is used because MySQL converts instances of 'utf8mb3' specified in such
definitions to 'utf8', which is an alias for 'utf8mb3'.

One advantage of converting from 'utf8mb3' to 'utf8mb4' is that this
enables applications to use supplementary characters.  One tradeoff is
that this may increase data storage space requirements.

In terms of table content, conversion from 'utf8mb3' to 'utf8mb4'
presents no problems:

   * For a BMP character, 'utf8mb4' and 'utf8mb3' have identical storage
     characteristics: same code values, same encoding, same length.

   * For a supplementary character, 'utf8mb4' requires four bytes to
     store it, whereas 'utf8mb3' cannot store the character at all.
     When converting 'utfmb3' columns to 'utf8mb4', you need not worry
     about converting supplementary characters because there will be
     none.

In terms of table structure, these are the primary potential
incompatibilities:

   * For the variable-length character data types (see 'VARCHAR'
     and the 'TEXT' types), the maximum permitted
     length in characters is less for 'utf8mb4' columns than for
     'utf8mb3' columns.

   * For all character data types (see 'CHAR', 'VARCHAR',
     and the 'TEXT' types), the maximum number of
     characters that can be indexed is less for 'utf8mb4' columns than
     for 'utf8mb3' columns.

Consequently, to convert tables from 'utf8mb3' to 'utf8mb4', it may be
necessary to change some column or index definitions.

Tables can be converted from 'utf8mb3' to 'utf8mb4' by using
'ALTER TABLE'.  Suppose that a table has this definition:

     CREATE TABLE t1 (
       col1 CHAR(10) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL,
       col2 CHAR(10) CHARACTER SET utf8 COLLATE utf8_bin NOT NULL
     ) CHARACTER SET utf8;

The following statement converts 't1' to use 'utf8mb4':

     ALTER TABLE t1
       DEFAULT CHARACTER SET utf8mb4,
       MODIFY col1 CHAR(10)
         CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
       MODIFY col2 CHAR(10)
         CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;

The catch when converting from 'utf8mb3' to 'utf8mb4' is that the
maximum length of a column or index key is unchanged in terms of
_bytes_.  Therefore, it is smaller in terms of _characters_ because the
maximum length of a character is four bytes instead of three.  For the
'CHAR', 'VARCHAR', and 'TEXT' data
types, watch for these issues when converting your MySQL tables:

   * Check all definitions of 'utf8mb3' columns and make sure they will
     not exceed the maximum length for the storage engine.

   * Check all indexes on 'utf8mb3' columns and make sure they will not
     exceed the maximum length for the storage engine.  Sometimes the
     maximum can change due to storage engine enhancements.

If the preceding conditions apply, you must either reduce the defined
length of columns or indexes, or continue to use 'utf8mb3' rather than
'utf8mb4'.

Here are some examples where structural changes may be needed:

   * A 'TINYTEXT' column can hold up to 255 bytes, so it
     can hold up to 85 3-byte or 63 4-byte characters.  Suppose that you
     have a 'TINYTEXT' column that uses 'utf8mb3' but must
     be able to contain more than 63 characters.  You cannot convert it
     to 'utf8mb4' unless you also change the data type to a longer type
     such as 'TEXT'.

     Similarly, a very long 'VARCHAR' column may need to be
     changed to one of the longer 'TEXT' types if you want
     to convert it from 'utf8mb3' to 'utf8mb4'.

   * 'InnoDB' has a maximum index length of 767 bytes for tables that
     use 'COMPACT' or 'REDUNDANT' row format, so for 'utf8mb3' or
     'utf8mb4' columns, you can index a maximum of 255 or 191
     characters, respectively.  If you currently have 'utf8mb3' columns
     with indexes longer than 191 characters, you must index a smaller
     number of characters.

     In an 'InnoDB' table that uses 'COMPACT' or 'REDUNDANT' row format,
     these column and index definitions are legal:

          col1 VARCHAR(500) CHARACTER SET utf8, INDEX (col1(255))

     To use 'utf8mb4' instead, the index must be smaller:

          col1 VARCHAR(500) CHARACTER SET utf8mb4, INDEX (col1(191))

     *Note*:

     For 'InnoDB' tables that use 'COMPRESSED' or 'DYNAMIC' row format,
     you can enable the 'innodb_large_prefix' option to permit index key
     prefixes longer than 767 bytes (up to 3072 bytes).  Creating such
     tables also requires the option values
     'innodb_file_format=barracuda' and 'innodb_file_per_table=true'.)
     In this case, enabling the 'innodb_large_prefix' option enables you
     to index a maximum of 1024 or 768 characters for 'utf8mb3' or
     'utf8mb4' columns, respectively.  For related information, see
     innodb-restrictions.

The preceding types of changes are most likely to be required only if
you have very long columns or indexes.  Otherwise, you should be able to
convert your tables from 'utf8mb3' to 'utf8mb4' without problems, using
'ALTER TABLE' as described previously.

The following items summarize other potential incompatibilities:

   * 'SET NAMES 'utf8mb4'' causes use of the 4-byte character set for
     connection character sets.  As long as no 4-byte characters are
     sent from the server, there should be no problems.  Otherwise,
     applications that expect to receive a maximum of three bytes per
     character may have problems.  Conversely, applications that expect
     to send 4-byte characters must ensure that the server understands
     them.

   * For replication, if character sets that support supplementary
     characters are to be used on the master, all slaves must understand
     them as well.

     Also, keep in mind the general principle that if a table has
     different definitions on the master and slave, this can lead to
     unexpected results.  For example, the differences in maximum index
     key length make it risky to use 'utf8mb3' on the master and
     'utf8mb4' on the slave.

If you have converted to 'utf8mb4', 'utf16', 'utf16le', or 'utf32', and
then decide to convert back to 'utf8mb3' or 'ucs2' (for example, to
downgrade to an older version of MySQL), these considerations apply:

   * 'utf8mb3' and 'ucs2' data should present no problems.

   * The server must be recent enough to recognize definitions referring
     to the character set from which you are converting.

   * For object definitions that refer to the 'utf8mb4' character set,
     you can dump them with 'mysqldump' prior to
     downgrading, edit the dump file to change instances of 'utf8mb4' to
     'utf8', and reload the file in the older server, as long as there
     are no 4-byte characters in the data.  The older server will see
     'utf8' in the dump file object definitions and create new objects
     that use the (3-byte) 'utf8' character set.

10.10 Supported Character Sets and Collations
=============================================

This section indicates which character sets MySQL supports.  There is
one subsection for each group of related character sets.  For each
character set, the permissible collations are listed.

To list the available character sets and their default collations, use
the 'SHOW CHARACTER SET' statement or query
the 'INFORMATION_SCHEMA' 'CHARACTER_SETS'.
table.  For example:

     mysql> SHOW CHARACTER SET;
     +----------+---------------------------------+---------------------+--------+
     | Charset  | Description                     | Default collation   | Maxlen |
     +----------+---------------------------------+---------------------+--------+
     | big5     | Big5 Traditional Chinese        | big5_chinese_ci     |      2 |
     | dec8     | DEC West European               | dec8_swedish_ci     |      1 |
     | cp850    | DOS West European               | cp850_general_ci    |      1 |
     | hp8      | HP West European                | hp8_english_ci      |      1 |
     | koi8r    | KOI8-R Relcom Russian           | koi8r_general_ci    |      1 |
     | latin1   | cp1252 West European            | latin1_swedish_ci   |      1 |
     | latin2   | ISO 8859-2 Central European     | latin2_general_ci   |      1 |
     | swe7     | 7bit Swedish                    | swe7_swedish_ci     |      1 |
     | ascii    | US ASCII                        | ascii_general_ci    |      1 |
     | ujis     | EUC-JP Japanese                 | ujis_japanese_ci    |      3 |
     | sjis     | Shift-JIS Japanese              | sjis_japanese_ci    |      2 |
     | hebrew   | ISO 8859-8 Hebrew               | hebrew_general_ci   |      1 |
     | tis620   | TIS620 Thai                     | tis620_thai_ci      |      1 |
     | euckr    | EUC-KR Korean                   | euckr_korean_ci     |      2 |
     | koi8u    | KOI8-U Ukrainian                | koi8u_general_ci    |      1 |
     | gb2312   | GB2312 Simplified Chinese       | gb2312_chinese_ci   |      2 |
     | greek    | ISO 8859-7 Greek                | greek_general_ci    |      1 |
     | cp1250   | Windows Central European        | cp1250_general_ci   |      1 |
     | gbk      | GBK Simplified Chinese          | gbk_chinese_ci      |      2 |
     | latin5   | ISO 8859-9 Turkish              | latin5_turkish_ci   |      1 |
     | armscii8 | ARMSCII-8 Armenian              | armscii8_general_ci |      1 |
     | utf8     | UTF-8 Unicode                   | utf8_general_ci     |      3 |
     | ucs2     | UCS-2 Unicode                   | ucs2_general_ci     |      2 |
     | cp866    | DOS Russian                     | cp866_general_ci    |      1 |
     | keybcs2  | DOS Kamenicky Czech-Slovak      | keybcs2_general_ci  |      1 |
     | macce    | Mac Central European            | macce_general_ci    |      1 |
     | macroman | Mac West European               | macroman_general_ci |      1 |
     | cp852    | DOS Central European            | cp852_general_ci    |      1 |
     | latin7   | ISO 8859-13 Baltic              | latin7_general_ci   |      1 |
     | utf8mb4  | UTF-8 Unicode                   | utf8mb4_general_ci  |      4 |
     | cp1251   | Windows Cyrillic                | cp1251_general_ci   |      1 |
     | utf16    | UTF-16 Unicode                  | utf16_general_ci    |      4 |
     | utf16le  | UTF-16LE Unicode                | utf16le_general_ci  |      4 |
     | cp1256   | Windows Arabic                  | cp1256_general_ci   |      1 |
     | cp1257   | Windows Baltic                  | cp1257_general_ci   |      1 |
     | utf32    | UTF-32 Unicode                  | utf32_general_ci    |      4 |
     | binary   | Binary pseudo charset           | binary              |      1 |
     | geostd8  | GEOSTD8 Georgian                | geostd8_general_ci  |      1 |
     | cp932    | SJIS for Windows Japanese       | cp932_japanese_ci   |      2 |
     | eucjpms  | UJIS for Windows Japanese       | eucjpms_japanese_ci |      3 |
     | gb18030  | China National Standard GB18030 | gb18030_chinese_ci  |      4 |
     +----------+---------------------------------+---------------------+--------+

In cases where a character set has multiple collations, it might not be
clear which collation is most suitable for a given application.  To
avoid choosing the wrong collation, it can be helpful to perform some
comparisons with representative data values to make sure that a given
collation sorts values the way you expect.

10.10.1 Unicode Character Sets
------------------------------

MySQL supports multiple Unicode character sets:

   * 'utf8mb4': A UTF-8 encoding of the Unicode character set using one
     to four bytes per character.

   * 'utf8mb3': A UTF-8 encoding of the Unicode character set using one
     to three bytes per character.

   * 'utf8': An alias for 'utfmb3'.

   * 'ucs2': The UCS-2 encoding of the Unicode character set using two
     bytes per character.

   * 'utf16': The UTF-16 encoding for the Unicode character set using
     two or four bytes per character.  Like 'ucs2' but with an extension
     for supplementary characters.

   * 'utf16le': The UTF-16LE encoding for the Unicode character set.
     Like 'utf16' but little-endian rather than big-endian.

   * 'utf32': The UTF-32 encoding for the Unicode character set using
     four bytes per character.

'utf8' and 'ucs2' support Basic Multilingual Plane (BMP) characters.
'utf8mb4', 'utf16', 'utf16le', and 'utf32' support BMP and supplementary
characters.

This section describes the collations available for Unicode character
sets and their differentiating properties.  For general information
about Unicode, see charset-unicode.

Most Unicode character sets have a general collation (indicated by
'_general' in the name or by the absence of a language specifier), a
binary collation (indicated by '_bin' in the name), and several
language-specific collations (indicated by language specifiers).  For
example, for 'utf8', 'utf8_general_ci' and 'utf8_bin' are its general
and binary collations, and 'utf8_danish_ci' is one of its
language-specific collations.

Collation support for 'utf16le' is limited.  The only collations
available are 'utf16le_general_ci' and 'utf16le_bin'.  These are similar
to 'utf16_general_ci' and 'utf16_bin'.

A language name shown in the following table indicates a
language-specific collation.  Unicode character sets may include
collations for one or more of these languages.

*Unicode Collation Language Specifiers*

Language                      Language Specifier

Classical Latin               'roman'

Croatian                      'croatian'

Czech                         'czech'

Danish                        'danish'

Esperanto                     'esperanto'

Estonian                      'estonian'

German phone book order       'german2'

Hungarian                     'hungarian'

Icelandic                     'icelandic'

Latvian                       'latvian'

Lithuanian                    'lithuanian'

Persian                       'persian'

Polish                        'polish'

Romanian                      'romanian'

Sinhala                       'sinhala'

Slovak                        'slovak'

Slovenian                     'slovenian'

Modern Spanish                'spanish'

Traditional Spanish           'spanish2'

Swedish                       'swedish'

Turkish                       'turkish'

Vietnamese                    'vietnamese'

Croatian collations are tailored for these Croatian letters: 'Č', 'Ć',
'Dž', 'Đ', 'Lj', 'Nj', '�', 'Ž'.

Danish collations may also be used for Norwegian.

For Classical Latin collations, 'I' and 'J' compare as equal, and 'U'
and 'V' compare as equal.

Spanish collations are available for modern and traditional Spanish.
For both, 'ñ' (n-tilde) is a separate letter between 'n' and 'o'.  In
addition, for traditional Spanish, 'ch' is a separate letter between 'c'
and 'd', and 'll' is a separate letter between 'l' and 'm'.

Traditional Spanish collations may also be used for Asturian and
Galician.

Swedish collations include Swedish rules.  For example, in Swedish, the
following relationship holds, which is not something expected by a
German or French speaker:

     U" = Y < O"

For questions about particular language orderings, <unicode.org>
provides Common Locale Data Repository (CLDR) collation charts at
<http://www.unicode.org/cldr/charts/30/collation/index.html>.

The 'XXX_general_mysql500_ci' collations preserve the pre-5.1.24
ordering of the original 'XXX_general_ci' collations and permit upgrades
for tables created before MySQL 5.1.24 (Bug #27877).

MySQL implements the 'XXX_unicode_ci' collations according to the
Unicode Collation Algorithm (UCA) described at
<http://www.unicode.org/reports/tr10/>.  The collation uses the
version-4.0.0 UCA weight keys:
<http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt>.  The
'XXX_unicode_ci' collations have only partial support for the Unicode
Collation Algorithm.  Some characters are not supported, and combining
marks are not fully supported.  This affects primarily Vietnamese,
Yoruba, and some smaller languages such as Navajo.  A combined character
is considered different from the same character written with a single
unicode character in string comparisons, and the two characters are
considered to have a different length (for example, as returned by the
'CHAR_LENGTH()' function or in result set metadata).

Unicode collations based on UCA versions later than 4.0.0 include the
version in the collation name.  Thus, 'utf8_unicode_520_ci' is based on
UCA 5.2.0 weight keys
(<http://www.unicode.org/Public/UCA/5.2.0/allkeys.txt>).

MySQL implements language-specific Unicode collations if the ordering
based only on UCA does not work well for a language.  Language-specific
collations are UCA-based, with additional language tailoring rules.

'LOWER()' and 'UPPER()' perform case folding according to the collation
of their argument.  A character that has uppercase and lowercase
versions only in a Unicode version more recent than 4.0.0 is converted
by these functions only if the argument has a collation that uses a
recent enough UCA version.

For any Unicode character set, operations performed using the
'XXX_general_ci' collation are faster than those for the
'XXX_unicode_ci' collation.  For example, comparisons for the
'utf8_general_ci' collation are faster, but slightly less correct, than
comparisons for 'utf8_unicode_ci'.  The reason for this is that
'utf8_unicode_ci' supports mappings such as expansions; that is, when
one character compares as equal to combinations of other characters.
For example, in German and some other languages 'ss' is equal to 'ss'.
'utf8_unicode_ci' also supports contractions and ignorable characters.
'utf8_general_ci' is a legacy collation that does not support
expansions, contractions, or ignorable characters.  It can make only
one-to-one comparisons between characters.

To further illustrate, the following equalities hold in both
'utf8_general_ci' and 'utf8_unicode_ci' (for the effect of this in
comparisons or searches, see charset-collation-effect):

     A" = A
     O" = O
     U" = U

A difference between the collations is that this is true for
'utf8_general_ci':

     ss = s

Whereas this is true for 'utf8_unicode_ci', which supports the German
DIN-1 ordering (also known as dictionary order):

     ss = ss

MySQL implements 'utf8' language-specific collations if the ordering
with 'utf8_unicode_ci' does not work well for a language.  For example,
'utf8_unicode_ci' works fine for German dictionary order and French, so
there is no need to create special 'utf8' collations.

'utf8_general_ci' also is satisfactory for both German and French,
except that 'ss' is equal to 's', and not to 'ss'.  If this is
acceptable for your application, you should use 'utf8_general_ci'
because it is faster.  If this is not acceptable (for example, if you
require German dictionary order), use 'utf8_unicode_ci' because it is
more accurate.

If you require German DIN-2 (phone book) ordering, use the
'utf8_german2_ci' collation, which compares the following sets of
characters equal:

     A" = Æ = AE
     O" = Œ = OE
     U" = UE
     ss = ss

'utf8_german2_ci' is similar to 'latin1_german2_ci', but the latter does
not compare 'Æ' equal to 'AE' or 'Œ' equal to 'OE'.  There is no
'utf8_german_ci' corresponding to 'latin1_german_ci' for German
dictionary order because 'utf8_general_ci' suffices.

For all Unicode collations except the binary ('_bin') collations, MySQL
performs a table lookup to find a character's collating weight.  This
weight can be displayed using the 'WEIGHT_STRING()' function.  (See
string-functions.)  If a character is not in the table (for
example, because it is a 'new' character), collating weight
determination becomes more complex:

   * For BMP characters in general collations ('XXX_general_ci'), weight
     = code point.

   * For BMP characters in UCA collations (for example, 'XXX_unicode_ci'
     and language-specific collations), the following algorithm applies:

          if (code >= 0x3400 && code <= 0x4DB5)
            base= 0xFB80; /* CJK Ideograph Extension */
          else if (code >= 0x4E00 && code <= 0x9FA5)
            base= 0xFB40; /* CJK Ideograph */
          else
            base= 0xFBC0; /* All other characters */
          aaaa= base +  (code >> 15);
          bbbb= (code & 0x7FFF) | 0x8000;

     The result is a sequence of two collating elements, 'aaaa' followed
     by 'bbbb'.  For example:

          mysql> SELECT HEX(WEIGHT_STRING(_ucs2 0x04CF COLLATE ucs2_unicode_ci));
          +----------------------------------------------------------+
          | HEX(WEIGHT_STRING(_ucs2 0x04CF COLLATE ucs2_unicode_ci)) |
          +----------------------------------------------------------+
          | FBC084CF                                                 |
          +----------------------------------------------------------+

     Thus, 'U+04cf CYRILLIC SMALL LETTER PALOCHKA' is, with all UCA
     4.0.0 collations, greater than 'U+04c0 CYRILLIC LETTER PALOCHKA'.
     With UCA 5.2.0 collations, all palochkas sort together.

   * For supplementary characters in general collations, the weight is
     the weight for '0xfffd REPLACEMENT CHARACTER'.  For supplementary
     characters in UCA 4.0.0 collations, their collating weight is
     '0xfffd'.  That is, to MySQL, all supplementary characters are
     equal to each other, and greater than almost all BMP characters.

     An example with Deseret characters and 'COUNT(DISTINCT)':

          CREATE TABLE t (s1 VARCHAR(5) CHARACTER SET utf32 COLLATE utf32_unicode_ci);
          INSERT INTO t VALUES (0xfffd);   /* REPLACEMENT CHARACTER */
          INSERT INTO t VALUES (0x010412); /* DESERET CAPITAL LETTER BEE */
          INSERT INTO t VALUES (0x010413); /* DESERET CAPITAL LETTER TEE */
          SELECT COUNT(DISTINCT s1) FROM t;

     The result is 2 because in the MySQL 'XXX_unicode_ci' collations,
     the replacement character has a weight of '0x0dc6', whereas Deseret
     Bee and Deseret Tee both have a weight of '0xfffd'.  (Were the
     'utf32_general_ci' collation used instead, the result is 1 because
     all three characters have a weight of '0xfffd' in that collation.)

     An example with cuneiform characters and 'WEIGHT_STRING()':

          /*
          The four characters in the INSERT string are
          00000041  # LATIN CAPITAL LETTER A
          0001218F  # CUNEIFORM SIGN KAB
          000121A7  # CUNEIFORM SIGN KISH
          00000042  # LATIN CAPITAL LETTER B
          */
          CREATE TABLE t (s1 CHAR(4) CHARACTER SET utf32 COLLATE utf32_unicode_ci);
          INSERT INTO t VALUES (0x000000410001218f000121a700000042);
          SELECT HEX(WEIGHT_STRING(s1)) FROM t;

     The result is:

          0E33 FFFD FFFD 0E4A

     '0E33' and '0E4A' are primary weights as in UCA 4.0.0
     (ftp://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt).  'FFFD'
     is the weight for KAB and also for KISH.

     The rule that all supplementary characters are equal to each other
     is nonoptimal but is not expected to cause trouble.  These
     characters are very rare, so it is very rare that a multi-character
     string consists entirely of supplementary characters.  In Japan,
     since the supplementary characters are obscure Kanji ideographs,
     the typical user does not care what order they are in, anyway.  If
     you really want rows sorted by the MySQL rule and secondarily by
     code point value, it is easy:

          ORDER BY s1 COLLATE utf32_unicode_ci, s1 COLLATE utf32_bin

   * For supplementary characters based on UCA versions higher than
     4.0.0 (for example, 'XXX_unicode_520_ci'), supplementary characters
     do not necessarily all have the same collation weight.  Some have
     explicit weights from the UCA 'allkeys.txt' file.  Others have
     weights calculated from this algorithm:

          aaaa= base +  (code >> 15);
          bbbb= (code & 0x7FFF) | 0x8000;

There is a difference between 'ordering by the character's code value'
and 'ordering by the character's binary representation,' a difference
that appears only with 'utf16_bin', because of surrogates.

Suppose that 'utf16_bin' (the binary collation for 'utf16') was a binary
comparison 'byte by byte' rather than 'character by character.' If that
were so, the order of characters in 'utf16_bin' would differ from the
order in 'utf8_bin'.  For example, the following chart shows two rare
characters.  The first character is in the range 'E000'-'FFFF', so it is
greater than a surrogate but less than a supplementary.  The second
character is a supplementary.

     Code point  Character                    utf8         utf16
     ----------  ---------                    ----         -----
     0FF9D       HALFWIDTH KATAKANA LETTER N  EF BE 9D     FF 9D
     10384       UGARITIC LETTER DELTA        F0 90 8E 84  D8 00 DF 84

The two characters in the chart are in order by code point value because
'0xff9d' < '0x10384'.  And they are in order by 'utf8' value because
'0xef' < '0xf0'.  But they are not in order by 'utf16' value, if we use
byte-by-byte comparison, because '0xff' > '0xd8'.

So MySQL's 'utf16_bin' collation is not 'byte by byte.' It is 'by code
point.' When MySQL sees a supplementary-character encoding in 'utf16',
it converts to the character's code-point value, and then compares.
Therefore, 'utf8_bin' and 'utf16_bin' are the same ordering.  This is
consistent with the SQL:2008 standard requirement for a UCS_BASIC
collation: 'UCS_BASIC is a collation in which the ordering is determined
entirely by the Unicode scalar values of the characters in the strings
being sorted. It is applicable to the UCS character repertoire. Since
every character repertoire is a subset of the UCS repertoire, the
UCS_BASIC collation is potentially applicable to every character set.
NOTE 11: The Unicode scalar value of a character is its code point
treated as an unsigned integer.'

If the character set is 'ucs2', comparison is byte-by-byte, but 'ucs2'
strings should not contain surrogates, anyway.

10.10.2 West European Character Sets
------------------------------------

Western European character sets cover most West European languages, such
as French, Spanish, Catalan, Basque, Portuguese, Italian, Albanian,
Dutch, German, Danish, Swedish, Norwegian, Finnish, Faroese, Icelandic,
Irish, Scottish, and English.

   * 'ascii' (US ASCII) collations:

        * 'ascii_bin'

        * 'ascii_general_ci' (default)

   * 'cp850' (DOS West European) collations:

        * 'cp850_bin'

        * 'cp850_general_ci' (default)

   * 'dec8' (DEC Western European) collations:

        * 'dec8_bin'

        * 'dec8_swedish_ci' (default)

   * 'hp8' (HP Western European) collations:

        * 'hp8_bin'

        * 'hp8_english_ci' (default)

   * 'latin1' (cp1252 West European) collations:

        * 'latin1_bin'

        * 'latin1_danish_ci'

        * 'latin1_general_ci'

        * 'latin1_general_cs'

        * 'latin1_german1_ci'

        * 'latin1_german2_ci'

        * 'latin1_spanish_ci'

        * 'latin1_swedish_ci' (default)

     'latin1' is the default character set.  MySQL's 'latin1' is the
     same as the Windows 'cp1252' character set.  This means it is the
     same as the official 'ISO 8859-1' or IANA (Internet Assigned
     Numbers Authority) 'latin1', except that IANA 'latin1' treats the
     code points between '0x80' and '0x9f' as 'undefined,' whereas
     'cp1252', and therefore MySQL's 'latin1', assign characters for
     those positions.  For example, '0x80' is the Euro sign.  For the
     'undefined' entries in 'cp1252', MySQL translates '0x81' to Unicode
     '0x0081', '0x8d' to '0x008d', '0x8f' to '0x008f', '0x90' to
     '0x0090', and '0x9d' to '0x009d'.

     The 'latin1_swedish_ci' collation is the default that probably is
     used by the majority of MySQL customers.  Although it is frequently
     said that it is based on the Swedish/Finnish collation rules, there
     are Swedes and Finns who disagree with this statement.

     The 'latin1_german1_ci' and 'latin1_german2_ci' collations are
     based on the DIN-1 and DIN-2 standards, where DIN stands for
     _Deutsches Institut fu"r Normung_ (the German equivalent of ANSI).
     DIN-1 is called the 'dictionary collation' and DIN-2 is called the
     'phone book collation.' For an example of the effect this has in
     comparisons or when doing searches, see
     charset-collation-effect.

        * 'latin1_german1_ci' (dictionary) rules:

               A" = A
               O" = O
               U" = U
               ss = s

        * 'latin1_german2_ci' (phone-book) rules:

               A" = AE
               O" = OE
               U" = UE
               ss = ss

     In the 'latin1_spanish_ci' collation, 'ñ' (n-tilde) is a separate
     letter between 'n' and 'o'.

   * 'macroman' (Mac West European) collations:

        * 'macroman_bin'

        * 'macroman_general_ci' (default)

   * 'swe7' (7bit Swedish) collations:

        * 'swe7_bin'

        * 'swe7_swedish_ci' (default)

10.10.3 Central European Character Sets
---------------------------------------

MySQL provides some support for character sets used in the Czech
Republic, Slovakia, Hungary, Romania, Slovenia, Croatia, Poland, and
Serbia (Latin).

   * 'cp1250' (Windows Central European) collations:

        * 'cp1250_bin'

        * 'cp1250_croatian_ci'

        * 'cp1250_czech_cs'

        * 'cp1250_general_ci' (default)

        * 'cp1250_polish_ci'

   * 'cp852' (DOS Central European) collations:

        * 'cp852_bin'

        * 'cp852_general_ci' (default)

   * 'keybcs2' (DOS Kamenicky Czech-Slovak) collations:

        * 'keybcs2_bin'

        * 'keybcs2_general_ci' (default)

   * 'latin2' (ISO 8859-2 Central European) collations:

        * 'latin2_bin'

        * 'latin2_croatian_ci'

        * 'latin2_czech_cs'

        * 'latin2_general_ci' (default)

        * 'latin2_hungarian_ci'

   * 'macce' (Mac Central European) collations:

        * 'macce_bin'

        * 'macce_general_ci' (default)

10.10.4 South European and Middle East Character Sets
-----------------------------------------------------

South European and Middle Eastern character sets supported by MySQL
include Armenian, Arabic, Georgian, Greek, Hebrew, and Turkish.

   * 'armscii8' (ARMSCII-8 Armenian) collations:

        * 'armscii8_bin'

        * 'armscii8_general_ci' (default)

   * 'cp1256' (Windows Arabic) collations:

        * 'cp1256_bin'

        * 'cp1256_general_ci' (default)

   * 'geostd8' (GEOSTD8 Georgian) collations:

        * 'geostd8_bin'

        * 'geostd8_general_ci' (default)

   * 'greek' (ISO 8859-7 Greek) collations:

        * 'greek_bin'

        * 'greek_general_ci' (default)

   * 'hebrew' (ISO 8859-8 Hebrew) collations:

        * 'hebrew_bin'

        * 'hebrew_general_ci' (default)

   * 'latin5' (ISO 8859-9 Turkish) collations:

        * 'latin5_bin'

        * 'latin5_turkish_ci' (default)

10.10.5 Baltic Character Sets
-----------------------------

The Baltic character sets cover Estonian, Latvian, and Lithuanian
languages.

   * 'cp1257' (Windows Baltic) collations:

        * 'cp1257_bin'

        * 'cp1257_general_ci' (default)

        * 'cp1257_lithuanian_ci'

   * 'latin7' (ISO 8859-13 Baltic) collations:

        * 'latin7_bin'

        * 'latin7_estonian_cs'

        * 'latin7_general_ci' (default)

        * 'latin7_general_cs'

10.10.6 Cyrillic Character Sets
-------------------------------

The Cyrillic character sets and collations are for use with Belarusian,
Bulgarian, Russian, Ukrainian, and Serbian (Cyrillic) languages.

   * 'cp1251' (Windows Cyrillic) collations:

        * 'cp1251_bin'

        * 'cp1251_bulgarian_ci'

        * 'cp1251_general_ci' (default)

        * 'cp1251_general_cs'

        * 'cp1251_ukrainian_ci'

   * 'cp866' (DOS Russian) collations:

        * 'cp866_bin'

        * 'cp866_general_ci' (default)

   * 'koi8r' (KOI8-R Relcom Russian) collations:

        * 'koi8r_bin'

        * 'koi8r_general_ci' (default)

   * 'koi8u' (KOI8-U Ukrainian) collations:

        * 'koi8u_bin'

        * 'koi8u_general_ci' (default)

10.10.7 Asian Character Sets
----------------------------

The Asian character sets that we support include Chinese, Japanese,
Korean, and Thai.  These can be complicated.  For example, the Chinese
sets must allow for thousands of different characters.  See
charset-cp932, for additional information about the 'cp932' and 'sjis'
character sets.  See charset-gb18030, for additional information
about character set support for the Chinese National Standard GB 18030.

For answers to some common questions and problems relating support for
Asian character sets in MySQL, see faqs-cjk.

   * 'big5' (Big5 Traditional Chinese) collations:

        * 'big5_bin'

        * 'big5_chinese_ci' (default)

   * 'cp932'. (SJIS for Windows Japanese)
     collations:

        * 'cp932_bin'

        * 'cp932_japanese_ci' (default)

   * 'eucjpms' (UJIS for Windows Japanese) collations:

        * 'eucjpms_bin'

        * 'eucjpms_japanese_ci' (default)

   * 'euckr' (EUC-KR Korean) collations:

        * 'euckr_bin'

        * 'euckr_korean_ci' (default)

   * 'gb2312' (GB2312 Simplified Chinese) collations:

        * 'gb2312_bin'

        * 'gb2312_chinese_ci' (default)

   * 'gbk' (GBK Simplified Chinese) collations:

        * 'gbk_bin'

        * 'gbk_chinese_ci' (default)

   * 'gb18030'. (China National Standard GB18030)
     collations:

        * 'gb18030_bin'

        * 'gb18030_chinese_ci' (default)

        * 'gb18030_unicode_520_ci'

   * 'sjis' (Shift-JIS Japanese) collations:

        * 'sjis_bin'

        * 'sjis_japanese_ci' (default)

   * 'tis620' (TIS620 Thai) collations:

        * 'tis620_bin'

        * 'tis620_thai_ci' (default)

   * 'ujis' (EUC-JP Japanese) collations:

        * 'ujis_bin'

        * 'ujis_japanese_ci' (default)

The 'big5_chinese_ci' collation sorts on number of strokes.

10.10.7.1 The cp932 Character Set
.................................

*Why is 'cp932' needed?*

In MySQL, the 'sjis' character set corresponds to the 'Shift_JIS'
character set defined by IANA, which supports JIS X0201 and JIS X0208
characters.  (See <http://www.iana.org/assignments/character-sets>.)

However, the meaning of 'SHIFT JIS' as a descriptive term has become
very vague and it often includes the extensions to 'Shift_JIS' that are
defined by various vendors.

For example, 'SHIFT JIS' used in Japanese Windows environments is a
Microsoft extension of 'Shift_JIS' and its exact name is 'Microsoft
Windows Codepage : 932' or 'cp932'.  In addition to the characters
supported by 'Shift_JIS', 'cp932' supports extension characters such as
NEC special characters, NEC selected--IBM extended characters, and IBM
selected characters.

Many Japanese users have experienced problems using these extension
characters.  These problems stem from the following factors:

   * MySQL automatically converts character sets.

   * Character sets are converted using Unicode ('ucs2').

   * The 'sjis' character set does not support the conversion of these
     extension characters.

   * There are several conversion rules from so-called 'SHIFT JIS' to
     Unicode, and some characters are converted to Unicode differently
     depending on the conversion rule.  MySQL supports only one of these
     rules (described later).

The MySQL 'cp932' character set is designed to solve these problems.

Because MySQL supports character set conversion, it is important to
separate IANA 'Shift_JIS' and 'cp932' into two different character sets
because they provide different conversion rules.

*How does 'cp932' differ from 'sjis'?*

The 'cp932' character set differs from 'sjis' in the following ways:

   * 'cp932' supports NEC special characters, NEC selected--IBM extended
     characters, and IBM selected characters.

   * Some 'cp932' characters have two different code points, both of
     which convert to the same Unicode code point.  When converting from
     Unicode back to 'cp932', one of the code points must be selected.
     For this 'round trip conversion,' the rule recommended by Microsoft
     is used.  (See <http://support.microsoft.com/kb/170559/EN-US/>.)

     The conversion rule works like this:

        * If the character is in both JIS X 0208 and NEC special
          characters, use the code point of JIS X 0208.

        * If the character is in both NEC special characters and IBM
          selected characters, use the code point of NEC special
          characters.

        * If the character is in both IBM selected characters and NEC
          selected--IBM extended characters, use the code point of IBM
          extended characters.

     The table shown at
     <https://msdn.microsoft.com/en-us/goglobal/cc305152.aspx> provides
     information about the Unicode values of 'cp932' characters.  For
     'cp932' table entries with characters under which a four-digit
     number appears, the number represents the corresponding Unicode
     ('ucs2') encoding.  For table entries with an underlined two-digit
     value appears, there is a range of 'cp932' character values that
     begin with those two digits.  Clicking such a table entry takes you
     to a page that displays the Unicode value for each of the 'cp932'
     characters that begin with those digits.

     The following links are of special interest.  They correspond to
     the encodings for the following sets of characters:

        * NEC special characters (lead byte '0x87'):

               <https://msdn.microsoft.com/en-us/goglobal/gg674964>

        * NEC selected--IBM extended characters (lead byte '0xED' and
          '0xEE'):

               <https://msdn.microsoft.com/en-us/goglobal/gg671837>
               <https://msdn.microsoft.com/en-us/goglobal/gg671838>

        * IBM selected characters (lead byte '0xFA', '0xFB', '0xFC'):

               <https://msdn.microsoft.com/en-us/goglobal/gg671839>
               <https://msdn.microsoft.com/en-us/goglobal/gg671840>
               <https://msdn.microsoft.com/en-us/goglobal/gg671841>

   * 'cp932' supports conversion of user-defined characters in
     combination with 'eucjpms', and solves the problems with
     'sjis'/'ujis' conversion.  For details, please refer to
     <http://www.sljfaq.org/afaq/encodings.html>.

For some characters, conversion to and from 'ucs2' is different for
'sjis' and 'cp932'.  The following tables illustrate these differences.

Conversion to 'ucs2':

'sjis'/'cp932' Value     'sjis' -> 'ucs2'         'cp932' -> 'ucs2'
                         Conversion               Conversion

5C                       005C                     005C

7E                       007E                     007E

815C                     2015                     2015

815F                     005C                     FF3C

8160                     301C                     FF5E

8161                     2016                     2225

817C                     2212                     FF0D

8191                     00A2                     FFE0

8192                     00A3                     FFE1

81CA                     00AC                     FFE2

Conversion from 'ucs2':

'ucs2' value             'ucs2' -> 'sjis'         'ucs2' -> 'cp932'
                         Conversion               Conversion

005C                     815F                     5C

007E                     7E                       7E

00A2                     8191                     3F

00A3                     8192                     3F

00AC                     81CA                     3F

2015                     815C                     815C

2016                     8161                     3F

2212                     817C                     3F

2225                     3F                       8161

301C                     8160                     3F

FF0D                     3F                       817C

FF3C                     3F                       815F

FF5E                     3F                       8160

FFE0                     3F                       8191

FFE1                     3F                       8192

FFE2                     3F                       81CA

Users of any Japanese character sets should be aware that using
'--character-set-client-handshake' (or
'--skip-character-set-client-handshake') has an important effect.  See
server-options.

10.10.7.2 The gb18030 Character Set
...................................

In MySQL, the 'gb18030' character set corresponds to the 'Chinese
National Standard GB 18030-2005: Information technology --- Chinese
coded character set', which is the official character set of the
People's Republic of China (PRC).

*Characteristics of the MySQL gb18030 Character Set*

   * Supports all code points defined by the GB 18030-2005 standard.
     Unassigned code points in the ranges (GB+8431A439, GB+90308130) and
     (GB+E3329A36, GB+EF39EF39) are treated as ''?'' (0x3F). Conversion
     of unassigned code points return ''?''.

   * Supports UPPER and LOWER conversion for all GB18030 code points.
     Case folding defined by Unicode is also supported (based on
     'CaseFolding-6.3.0.txt').

   * Supports Conversion of data to and from other character sets.

   * Supports SQL statements such as 'SET NAMES'.

   * Supports comparison between 'gb18030' strings, and between
     'gb18030' strings and strings of other character sets.  There is a
     conversion if strings have different character sets.  Comparisons
     that include or ignore trailing spaces are also supported.

   * The private use area (U+E000, U+F8FF) in Unicode is mapped to
     'gb18030'.

   * There is no mapping between (U+D800, U+DFFF) and GB18030.
     Attempted conversion of code points in this range returns ''?''.

   * If an incoming sequence is illegal, an error or warning is
     returned.  If an illegal sequence is used in 'CONVERT()', an error
     is returned.  Otherwise, a warning is returned.

   * For consistency with 'utf8' and 'utf8mb4', UPPER is not supported
     for ligatures.

   * Searches for ligatures also match uppercase ligatures when using
     the 'gb18030_unicode_520_ci' collation.

   * If a character has more than one uppercase character, the chosen
     uppercase character is the one whose lowercase is the character
     itself.

   * The minimum multibyte length is 1 and the maximum is 4.  The
     character set determines the length of a sequence using the first 1
     or 2 bytes.

*Supported Collations*

   * 'gb18030_bin': A binary collation.

   * 'gb18030_chinese_ci': The default collation, which supports Pinyin.
     Sorting of non-Chinese characters is based on the order of the
     original sort key.  The original sort key is 'GB(UPPER(ch))' if
     'UPPER(ch)' exists.  Otherwise, the original sort key is 'GB(ch)'.
     Chinese characters are sorted according to the Pinyin collation
     defined in the Unicode Common Locale Data Repository (CLDR 24).
     Non-Chinese characters are sorted before Chinese characters with
     the exception of 'GB+FE39FE39', which is the code point maximum.

   * 'gb18030_unicode_520_ci': A Unicode collation.  Use this collation
     if you need to ensure that ligatures are sorted correctly.

10.10.8 The Binary Character Set
--------------------------------

The 'binary' character set is the chararcter set of binary strings,
which are sequences of bytes.  The 'binary' character set has one
collation, also named 'binary'.  Comparison and sorting are based on
numeric byte values.  The effect is that lettercase and accent
differences are significant in comparisons.  That is, the 'binary'
collation is case-sensitive and accent sensitive.

     mysql> SET NAMES 'binary';
     mysql> SELECT CHARSET('abc'), COLLATION('abc');
     +----------------+------------------+
     | CHARSET('abc') | COLLATION('abc') |
     +----------------+------------------+
     | binary         | binary           |
     +----------------+------------------+
     mysql> SELECT 'abc' = 'ABC', 'a' = 'a"';
     +---------------+------------+
     | 'abc' = 'ABC' | 'a' = 'a"'  |
     +---------------+------------+
     |             0 |          0 |
     +---------------+------------+

For information about the differences between the 'binary' collation of
the 'binary' character set and the '_bin' collations of nonbinary
character sets, see charset-binary-collations.

To convert a string expression to a binary string, any of these
constructs are equivalent:

     BINARY EXPR
     CAST(EXPR AS BINARY)
     CONVERT(EXPR USING BINARY)

If EXPR is a character string literal, the '_binary' introducer may be
used to designate it as a binary string.  For example:

     _binary 'a'

The '_binary' introducer is permitted for hexadecimal literals and
bit-value literals as well, but unnecessary; such literals are binary
strings by default.

For more information about introducers, see charset-introducer.

10.11 Setting the Error Message Language
========================================

By default, see 'mysqld' produces error messages in English,
but they can be displayed instead in any of several other languages:
Czech, Danish, Dutch, Estonian, French, German, Greek, Hungarian,
Italian, Japanese, Korean, Norwegian, Norwegian-ny, Polish, Portuguese,
Romanian, Russian, Slovak, Spanish, or Swedish.  This applies to
messages the server writes to the error log and sends to clients.

To select the language in which the server writes error messages, follow
the instructions in this section.  For information about changing the
character set for error messages (rather than the language), see
charset-errors.  For general information about configuring error
logging, see error-log.

The server searches for the error message file using these rules:

   * It tries to find the file in a directory constructed from two
     system variable values, 'lc_messages_dir' and 'lc_messages', with
     the latter converted to a language name.  Suppose that you start
     the server using this command:

          mysqld --lc_messages_dir=/usr/share/mysql --lc_messages=fr_FR

     In this case, see 'mysqld' maps the locale 'fr_FR' to
     the language 'french' and looks for the error file in the
     '/usr/share/mysql/french' directory.

     By default, the language files are located in the
     'share/mysql/LANGUAGE' directory under the MySQL base directory.

   * If the message file cannot be found in the directory constructed as
     just described, the server ignores the 'lc_messages' value and uses
     only the 'lc_messages_dir' value as the location in which to look.

The 'lc_messages_dir' system variable can be set only at server startup
and has only a global read-only value at runtime.  'lc_messages' can be
set at server startup and has global and session values that can be
modified at runtime.  Thus, the error message language can be changed
while the server is running, and individual clients each can have a
different error message language by changing their session 'lc_messages'
value to a different locale name.  For example, if the server is using
the 'fr_FR' locale for error messages, a client can execute this
statement to receive error messages in English:

     SET lc_messages = 'en_US';

You can change the content of the error messages produced by the server
using the instructions in the MySQL Internals manual, available at MySQL
Internals: Error Messages
(http://dev.mysql.com/doc/internals/en/error-messages.html).  If you do
change error message content, remember to repeat your changes after each
upgrade to a newer version of MySQL.

10.12 Adding a Character Set
============================

This section discusses the procedure for adding a character set to
MySQL. The proper procedure depends on whether the character set is
simple or complex:

   * If the character set does not need special string collating
     routines for sorting and does not need multibyte character support,
     it is simple.

   * If the character set needs either of those features, it is complex.

For example, 'greek' and 'swe7' are simple character sets, whereas
'big5' and 'czech' are complex character sets.

To use the following instructions, you must have a MySQL source
distribution.  In the instructions, MYSET represents the name of the
character set that you want to add.

  1. Add a '<charset>' element for MYSET to the
     'sql/share/charsets/Index.xml' file.  Use the existing contents in
     the file as a guide to adding new contents.  A partial listing for
     the 'latin1' '<charset>' element follows:

          <charset name="latin1">
            <family>Western</family>
            <description>cp1252 West European</description>
            ...
            <collation name="latin1_swedish_ci" id="8" order="Finnish, Swedish">
              <flag>primary</flag>
              <flag>compiled</flag>
            </collation>
            <collation name="latin1_danish_ci" id="15" order="Danish"/>
            ...
            <collation name="latin1_bin" id="47" order="Binary">
              <flag>binary</flag>
              <flag>compiled</flag>
            </collation>
            ...
          </charset>

     The '<charset>' element must list all the collations for the
     character set.  These must include at least a binary collation and
     a default (primary) collation.  The default collation is often
     named using a suffix of 'general_ci' (general, case insensitive).
     It is possible for the binary collation to be the default
     collation, but usually they are different.  The default collation
     should have a 'primary' flag.  The binary collation should have a
     'binary' flag.

     You must assign a unique ID number to each collation.  The range of
     IDs from 1024 to 2047 is reserved for user-defined collations.  To
     find the maximum of the currently used collation IDs, use this
     query:

          SELECT MAX(ID) FROM INFORMATION_SCHEMA.COLLATIONS;

  2. This step depends on whether you are adding a simple or complex
     character set.  A simple character set requires only a
     configuration file, whereas a complex character set requires C
     source file that defines collation functions, multibyte functions,
     or both.

     For a simple character set, create a configuration file,
     'MYSET.xml', that describes the character set properties.  Create
     this file in the 'sql/share/charsets' directory.  You can use a
     copy of 'latin1.xml' as the basis for this file.  The syntax for
     the file is very simple:

        * Comments are written as ordinary XML comments ('<!-- TEXT
          -->').

        * Words within '<map>' array elements are separated by arbitrary
          amounts of whitespace.

        * Each word within '<map>' array elements must be a number in
          hexadecimal format.

        * The '<map>' array element for the '<ctype>' element has 257
          words.  The other '<map>' array elements after that have 256
          words.  See character-arrays.

        * For each collation listed in the '<charset>' element for the
          character set in 'Index.xml', 'MYSET.xml' must contain a
          '<collation>' element that defines the character ordering.

     For a complex character set, create a C source file that describes
     the character set properties and defines the support routines
     necessary to properly perform operations on the character set:

        * Create the file 'ctype-MYSET.c' in the 'strings' directory.
          Look at one of the existing 'ctype-*.c' files (such as
          'ctype-big5.c') to see what needs to be defined.  The arrays
          in your file must have names like 'ctype_MYSET',
          'to_lower_MYSET', and so on.  These correspond to the arrays
          for a simple character set.  See character-arrays.

        * For each '<collation>' element listed in the '<charset>'
          element for the character set in 'Index.xml', the
          'ctype-MYSET.c' file must provide an implementation of the
          collation.

        * If the character set requires string collating functions, see
          string-collating.

        * If the character set requires multibyte character support, see
          multibyte-characters.

  3. Modify the configuration information.  Use the existing
     configuration information as a guide to adding information for
     MYSYS.  The example here assumes that the character set has default
     and binary collations, but more lines are needed if MYSET has
     additional collations.

       1. Edit 'mysys/charset-def.c', and 'register' the collations for
          the new character set.

          Add these lines to the 'declaration' section:

               #ifdef HAVE_CHARSET_MYSET
               extern CHARSET_INFO my_charset_MYSET_general_ci;
               extern CHARSET_INFO my_charset_MYSET_bin;
               #endif

          Add these lines to the 'registration' section:

               #ifdef HAVE_CHARSET_MYSET
                 add_compiled_collation(&my_charset_MYSET_general_ci);
                 add_compiled_collation(&my_charset_MYSET_bin);
               #endif

       2. If the character set uses 'ctype-MYSET.c', edit
          'strings/CMakeLists.txt' and add 'ctype-MYSET.c' to the
          definition of the 'STRINGS_SOURCES' variable.

       3. Edit 'cmake/character_sets.cmake':

            1. Add MYSET to the value of with 'CHARSETS_AVAILABLE' in
               alphabetic order.

            2. Add MYSET to the value of 'CHARSETS_COMPLEX' in
               alphabetic order.  This is needed even for simple
               character sets, or 'CMake' will not recognize
               '-DDEFAULT_CHARSET=MYSET'.

  4. Reconfigure, recompile, and test.

10.12.1 Character Definition Arrays
-----------------------------------

Each simple character set has a configuration file located in the
'sql/share/charsets' directory.  For a character set named MYSYS, the
file is named 'MYSET.xml'.  It uses '<map>' array elements to list
character set properties.  '<map>' elements appear within these
elements:

   * '<ctype>' defines attributes for each character.

   * '<lower>' and '<upper>' list the lowercase and uppercase
     characters.

   * '<unicode>' maps 8-bit character values to Unicode values.

   * '<collation>' elements indicate character ordering for comparison
     and sorting, one element per collation.  Binary collations need no
     '<map>' element because the character codes themselves provide the
     ordering.

For a complex character set as implemented in a 'ctype-MYSET.c' file in
the 'strings' directory, there are corresponding arrays:
'ctype_MYSET[]', 'to_lower_MYSET[]', and so forth.  Not every complex
character set has all of the arrays.  See also the existing 'ctype-*.c'
files for examples.  See the 'CHARSET_INFO.txt' file in the 'strings'
directory for additional information.

Most of the arrays are indexed by character value and have 256 elements.
The '<ctype>' array is indexed by character value + 1 and has 257
elements.  This is a legacy convention for handling 'EOF'.

'<ctype>' array elements are bit values.  Each element describes the
attributes of a single character in the character set.  Each attribute
is associated with a bitmask, as defined in 'include/m_ctype.h':

     #define _MY_U   01      /* Upper case */
     #define _MY_L   02      /* Lower case */
     #define _MY_NMR 04      /* Numeral (digit) */
     #define _MY_SPC 010     /* Spacing character */
     #define _MY_PNT 020     /* Punctuation */
     #define _MY_CTR 040     /* Control character */
     #define _MY_B   0100    /* Blank */
     #define _MY_X   0200    /* heXadecimal digit */

The '<ctype>' value for a given character should be the union of the
applicable bitmask values that describe the character.  For example,
''A'' is an uppercase character ('_MY_U') as well as a hexadecimal digit
('_MY_X'), so its 'ctype' value should be defined like this:

     ctype['A'+1] = _MY_U | _MY_X = 01 | 0200 = 0201

The bitmask values in 'm_ctype.h' are octal values, but the elements of
the '<ctype>' array in 'MYSET.xml' should be written as hexadecimal
values.

The '<lower>' and '<upper>' arrays hold the lowercase and uppercase
characters corresponding to each member of the character set.  For
example:

     lower['A'] should contain 'a'
     upper['a'] should contain 'A'

Each '<collation>' array indicates how characters should be ordered for
comparison and sorting purposes.  MySQL sorts characters based on the
values of this information.  In some cases, this is the same as the
'<upper>' array, which means that sorting is case-insensitive.  For more
complicated sorting rules (for complex character sets), see the
discussion of string collating in string-collating.

10.12.2 String Collating Support for Complex Character Sets
-----------------------------------------------------------

For a simple character set named MYSET, sorting rules are specified in
the 'MYSET.xml' configuration file using '<map>' array elements within
'<collation>' elements.  If the sorting rules for your language are too
complex to be handled with simple arrays, you must define string
collating functions in the 'ctype-MYSET.c' source file in the 'strings'
directory.

The existing character sets provide the best documentation and examples
to show how these functions are implemented.  Look at the 'ctype-*.c'
files in the 'strings' directory, such as the files for the 'big5',
'czech', 'gbk', 'sjis', and 'tis160' character sets.  Take a look at the
'MY_COLLATION_HANDLER' structures to see how they are used.  See also
the 'CHARSET_INFO.txt' file in the 'strings' directory for additional
information.

10.12.3 Multi-Byte Character Support for Complex Character Sets
---------------------------------------------------------------

If you want to add support for a new character set named MYSET that
includes multibyte characters, you must use multibyte character
functions in the 'ctype-MYSET.c' source file in the 'strings' directory.

The existing character sets provide the best documentation and examples
to show how these functions are implemented.  Look at the 'ctype-*.c'
files in the 'strings' directory, such as the files for the 'euc_kr',
'gb2312', 'gbk', 'sjis', and 'ujis' character sets.  Take a look at the
'MY_CHARSET_HANDLER' structures to see how they are used.  See also the
'CHARSET_INFO.txt' file in the 'strings' directory for additional
information.

10.13 Adding a Collation to a Character Set
===========================================

A collation is a set of rules that defines how to compare and sort
character strings.  Each collation in MySQL belongs to a single
character set.  Every character set has at least one collation, and most
have two or more collations.

A collation orders characters based on weights.  Each character in a
character set maps to a weight.  Characters with equal weights compare
as equal, and characters with unequal weights compare according to the
relative magnitude of their weights.

The 'WEIGHT_STRING()' function can be used to see the weights for the
characters in a string.  The value that it returns to indicate weights
is a binary string, so it is convenient to use 'HEX(WEIGHT_STRING(STR))'
to display the weights in printable form.  The following example shows
that weights do not differ for lettercase for the letters in ''AaBb'' if
it is a nonbinary case-insensitive string, but do differ if it is a
binary string:

     mysql> SELECT HEX(WEIGHT_STRING('AaBb' COLLATE latin1_swedish_ci));
     +------------------------------------------------------+
     | HEX(WEIGHT_STRING('AaBb' COLLATE latin1_swedish_ci)) |
     +------------------------------------------------------+
     | 41414242                                             |
     +------------------------------------------------------+
     mysql> SELECT HEX(WEIGHT_STRING(BINARY 'AaBb'));
     +-----------------------------------+
     | HEX(WEIGHT_STRING(BINARY 'AaBb')) |
     +-----------------------------------+
     | 41614262                          |
     +-----------------------------------+

MySQL supports several collation implementations, as discussed in
charset-collation-implementations.  Some of these can be added to
MySQL without recompiling:

   * Simple collations for 8-bit character sets.

   * UCA-based collations for Unicode character sets.

   * Binary ('XXX_bin') collations.

The following sections describe how to add collations of the first two
types to existing character sets.  All existing character sets already
have a binary collation, so there is no need here to describe how to add
one.

Summary of the procedure for adding a new collation:

  1. Choose a collation ID.

  2. Add configuration information that names the collation and
     describes the character-ordering rules.

  3. Restart the server.

  4. Verify that the collation is present.

The instructions here cover only collations that can be added without
recompiling MySQL. To add a collation that does require recompiling (as
implemented by means of functions in a C source file), use the
instructions in adding-character-set.  However, instead of
adding all the information required for a complete character set, just
modify the appropriate files for an existing character set.  That is,
based on what is already present for the character set's current
collations, add data structures, functions, and configuration
information for the new collation.

*Note*:

If you modify an existing collation, that may affect the ordering of
rows for indexes on columns that use the collation.  In this case,
rebuild any such indexes to avoid problems such as incorrect query
results.  See rebuilding-tables.

*Additional Resources*

   * The Unicode Collation Algorithm (UCA) specification:
     <http://www.unicode.org/reports/tr10/>

   * The Locale Data Markup Language (LDML) specification:
     <http://www.unicode.org/reports/tr35/>

10.13.1 Collation Implementation Types
--------------------------------------

MySQL implements several types of collations:

*Simple collations for 8-bit character sets*

This kind of collation is implemented using an array of 256 weights that
defines a one-to-one mapping from character codes to weights.
'latin1_swedish_ci' is an example.  It is a case-insensitive collation,
so the uppercase and lowercase versions of a character have the same
weights and they compare as equal.

     mysql> SET NAMES 'latin1' COLLATE 'latin1_swedish_ci';
     Query OK, 0 rows affected (0.01 sec)

     mysql> SELECT HEX(WEIGHT_STRING('a')), HEX(WEIGHT_STRING('A'));
     +-------------------------+-------------------------+
     | HEX(WEIGHT_STRING('a')) | HEX(WEIGHT_STRING('A')) |
     +-------------------------+-------------------------+
     | 41                      | 41                      |
     +-------------------------+-------------------------+
     1 row in set (0.01 sec)

     mysql> SELECT 'a' = 'A';
     +-----------+
     | 'a' = 'A' |
     +-----------+
     |         1 |
     +-----------+
     1 row in set (0.12 sec)

For implementation instructions, see
adding-collation-simple-8bit.

*Complex collations for 8-bit character sets*

This kind of collation is implemented using functions in a C source file
that define how to order characters, as described in
adding-character-set.

*Collations for non-Unicode multibyte character sets*

For this type of collation, 8-bit (single-byte) and multibyte characters
are handled differently.  For 8-bit characters, character codes map to
weights in case-insensitive fashion.  (For example, the single-byte
characters ''a'' and ''A'' both have a weight of '0x41'.)  For multibyte
characters, there are two types of relationship between character codes
and weights:

   * Weights equal character codes.  'sjis_japanese_ci' is an example of
     this kind of collation.  The multibyte character ''ぢ'' has a
     character code of '0x82C0', and the weight is also '0x82C0'.

          mysql> CREATE TABLE t1
                 (c1 VARCHAR(2) CHARACTER SET sjis COLLATE sjis_japanese_ci);
          Query OK, 0 rows affected (0.01 sec)

          mysql> INSERT INTO t1 VALUES ('a'),('A'),(0x82C0);
          Query OK, 3 rows affected (0.00 sec)
          Records: 3  Duplicates: 0  Warnings: 0

          mysql> SELECT c1, HEX(c1), HEX(WEIGHT_STRING(c1)) FROM t1;
          +------+---------+------------------------+
          | c1   | HEX(c1) | HEX(WEIGHT_STRING(c1)) |
          +------+---------+------------------------+
          | a    | 61      | 41                     |
          | A    | 41      | 41                     |
          | ぢ    | 82C0    | 82C0                   |
          +------+---------+------------------------+
          3 rows in set (0.00 sec)

   * Character codes map one-to-one to weights, but a code is not
     necessarily equal to the weight.  'gbk_chinese_ci' is an example of
     this kind of collation.  The multibyte character ''膰'' has a
     character code of '0x81B0' but a weight of '0xC286'.

          mysql> CREATE TABLE t1
                 (c1 VARCHAR(2) CHARACTER SET gbk COLLATE gbk_chinese_ci);
          Query OK, 0 rows affected (0.33 sec)

          mysql> INSERT INTO t1 VALUES ('a'),('A'),(0x81B0);
          Query OK, 3 rows affected (0.00 sec)
          Records: 3  Duplicates: 0  Warnings: 0

          mysql> SELECT c1, HEX(c1), HEX(WEIGHT_STRING(c1)) FROM t1;
          +------+---------+------------------------+
          | c1   | HEX(c1) | HEX(WEIGHT_STRING(c1)) |
          +------+---------+------------------------+
          | a    | 61      | 41                     |
          | A    | 41      | 41                     |
          | 膰    | 81B0    | C286                   |
          +------+---------+------------------------+
          3 rows in set (0.00 sec)

For implementation instructions, see adding-character-set.

*Collations for Unicode multibyte character sets*

Some of these collations are based on the Unicode Collation Algorithm
(UCA), others are not.

Non-UCA collations have a one-to-one mapping from character code to
weight.  In MySQL, such collations are case insensitive and accent
insensitive.  'utf8_general_ci' is an example: ''a'', ''A'', ''A`'', and
''a''' each have different character codes but all have a weight of
'0x0041' and compare as equal.

     mysql> SET NAMES 'utf8' COLLATE 'utf8_general_ci';
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t1
            (c1 CHAR(1) CHARACTER SET UTF8 COLLATE utf8_general_ci);
     Query OK, 0 rows affected (0.01 sec)

     mysql> INSERT INTO t1 VALUES ('a'),('A'),('A`'),('a'');
     Query OK, 4 rows affected (0.00 sec)
     Records: 4  Duplicates: 0  Warnings: 0

     mysql> SELECT c1, HEX(c1), HEX(WEIGHT_STRING(c1)) FROM t1;
     +------+---------+------------------------+
     | c1   | HEX(c1) | HEX(WEIGHT_STRING(c1)) |
     +------+---------+------------------------+
     | a    | 61      | 0041                   |
     | A    | 41      | 0041                   |
     | A`    | C380    | 0041                   |
     | a'    | C3A1    | 0041                   |
     +------+---------+------------------------+
     4 rows in set (0.00 sec)

UCA-based collations in MySQL have these properties:

   * If a character has weights, each weight uses 2 bytes (16 bits).

   * A character may have zero weights (or an empty weight).  In this
     case, the character is ignorable.  Example: "U+0000 NULL" does not
     have a weight and is ignorable.

   * A character may have one weight.  Example: ''a'' has a weight of
     '0x0E33'.

          mysql> SET NAMES 'utf8' COLLATE 'utf8_unicode_ci';
          Query OK, 0 rows affected (0.05 sec)

          mysql> SELECT HEX('a'), HEX(WEIGHT_STRING('a'));
          +----------+-------------------------+
          | HEX('a') | HEX(WEIGHT_STRING('a')) |
          +----------+-------------------------+
          | 61       | 0E33                    |
          +----------+-------------------------+
          1 row in set (0.02 sec)

   * A character may have many weights.  This is an expansion.  Example:
     The German letter ''ss'' (SZ ligature, or SHARP S) has a weight of
     '0x0FEA0FEA'.

          mysql> SET NAMES 'utf8' COLLATE 'utf8_unicode_ci';
          Query OK, 0 rows affected (0.11 sec)

          mysql> SELECT HEX('ss'), HEX(WEIGHT_STRING('ss'));
          +-----------+--------------------------+
          | HEX('ss')  | HEX(WEIGHT_STRING('ss'))  |
          +-----------+--------------------------+
          | C39F      | 0FEA0FEA                 |
          +-----------+--------------------------+
          1 row in set (0.00 sec)

   * Many characters may have one weight.  This is a contraction.
     Example: ''ch'' is a single letter in Czech and has a weight of
     '0x0EE2'.

          mysql> SET NAMES 'utf8' COLLATE 'utf8_czech_ci';
          Query OK, 0 rows affected (0.09 sec)

          mysql> SELECT HEX('ch'), HEX(WEIGHT_STRING('ch'));
          +-----------+--------------------------+
          | HEX('ch') | HEX(WEIGHT_STRING('ch')) |
          +-----------+--------------------------+
          | 6368      | 0EE2                     |
          +-----------+--------------------------+
          1 row in set (0.00 sec)

A many-characters-to-many-weights mapping is also possible (this is
contraction with expansion), but is not supported by MySQL.

For implementation instructions, for a non-UCA collation, see
adding-character-set.  For a UCA collation, see
adding-collation-unicode-uca.

*Miscellaneous collations*

There are also a few collations that do not fall into any of the
previous categories.

10.13.2 Choosing a Collation ID
-------------------------------

Each collation must have a unique ID. To add a collation, you must
choose an ID value that is not currently used.  MySQL supports two-byte
collation IDs.  The range of IDs from 1024 to 2047 is reserved for
user-defined collations.  The collation ID that you choose will appear
in these contexts:

   * The 'ID' column of the 'INFORMATION_SCHEMA.COLLATIONS'
     table.

   * The 'Id' column of 'SHOW COLLATION' output.

   * The 'charsetnr' member of the 'MYSQL_FIELD' C API data structure.

   * The 'number' member of the 'MY_CHARSET_INFO' data structure
     returned by the 'mysql_get_character_set_info()'.
     C API function.

To determine the largest currently used ID, issue the following
statement:

     mysql> SELECT MAX(ID) FROM INFORMATION_SCHEMA.COLLATIONS;
     +---------+
     | MAX(ID) |
     +---------+
     |     210 |
     +---------+

To display a list of all currently used IDs, issue this statement:

     mysql> SELECT ID FROM INFORMATION_SCHEMA.COLLATIONS ORDER BY ID;
     +-----+
     | ID  |
     +-----+
     |   1 |
     |   2 |
     | ... |
     |  52 |
     |  53 |
     |  57 |
     |  58 |
     | ... |
     |  98 |
     |  99 |
     | 128 |
     | 129 |
     | ... |
     | 210 |
     +-----+

*Warning*:

Before upgrading, you should save the configuration files that you
change.  If you upgrade in place, the process will replace the your
modified files.

10.13.3 Adding a Simple Collation to an 8-Bit Character Set
-----------------------------------------------------------

This section describes how to add a simple collation for an 8-bit
character set by writing the '<collation>' elements associated with a
'<charset>' character set description in the MySQL 'Index.xml' file.
The procedure described here does not require recompiling MySQL. The
example adds a collation named 'latin1_test_ci' to the 'latin1'
character set.

  1. Choose a collation ID, as shown in
     adding-collation-choosing-id.  The following steps use an ID of
     1024.

  2. Modify the 'Index.xml' and 'latin1.xml' configuration files.  These
     files are located in the directory named by the
     'character_sets_dir' system variable.  You can check the variable
     value as follows, although the path name might be different on your
     system:

          mysql> SHOW VARIABLES LIKE 'character_sets_dir';
          +--------------------+-----------------------------------------+
          | Variable_name      | Value                                   |
          +--------------------+-----------------------------------------+
          | character_sets_dir | /user/local/mysql/share/mysql/charsets/ |
          +--------------------+-----------------------------------------+

  3. Choose a name for the collation and list it in the 'Index.xml'
     file.  Find the '<charset>' element for the character set to which
     the collation is being added, and add a '<collation>' element that
     indicates the collation name and ID, to associate the name with the
     ID. For example:

          <charset name="latin1">
            ...
            <collation name="latin1_test_ci" id="1024"/>
            ...
          </charset>

  4. In the 'latin1.xml' configuration file, add a '<collation>' element
     that names the collation and that contains a '<map>' element that
     defines a character code-to-weight mapping table for character
     codes 0 to 255.  Each value within the '<map>' element must be a
     number in hexadecimal format.

          <collation name="latin1_test_ci">
          <map>
           00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
           10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
           20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
           30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
           40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
           50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
           60 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
           50 51 52 53 54 55 56 57 58 59 5A 7B 7C 7D 7E 7F
           80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F
           90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
           A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF
           B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF
           41 41 41 41 5B 5D 5B 43 45 45 45 45 49 49 49 49
           44 4E 4F 4F 4F 4F 5C D7 5C 55 55 55 59 59 DE DF
           41 41 41 41 5B 5D 5B 43 45 45 45 45 49 49 49 49
           44 4E 4F 4F 4F 4F 5C F7 5C 55 55 55 59 59 DE FF
          </map>
          </collation>

  5. Restart the server and use this statement to verify that the
     collation is present:

          mysql> SHOW COLLATION WHERE Collation = 'latin1_test_ci';
          +----------------+---------+------+---------+----------+---------+
          | Collation      | Charset | Id   | Default | Compiled | Sortlen |
          +----------------+---------+------+---------+----------+---------+
          | latin1_test_ci | latin1  | 1024 |         |          |       1 |
          +----------------+---------+------+---------+----------+---------+

10.13.4 Adding a UCA Collation to a Unicode Character Set
---------------------------------------------------------

This section describes how to add a UCA collation for a Unicode
character set by writing the '<collation>' element within a '<charset>'
character set description in the MySQL 'Index.xml' file.  The procedure
described here does not require recompiling MySQL. It uses a subset of
the Locale Data Markup Language (LDML) specification, which is available
at <http://www.unicode.org/reports/tr35/>.  With this method, you need
not define the entire collation.  Instead, you begin with an existing
'base' collation and describe the new collation in terms of how it
differs from the base collation.  The following table lists the base
collations of the Unicode character sets for which UCA collations can be
defined.  It is not possible to create user-defined UCA collations for
'utf16le'; there is no 'utf16le_unicode_ci' collation that would serve
as the basis for such collations.

*MySQL Character Sets Available for User-Defined UCA Collations*

Character Set          Base Collation

'utf8'

'utf8_unicode_ci'

'ucs2'

'ucs2_unicode_ci'

'utf16'

'utf16_unicode_ci'

'utf32'

'utf32_unicode_ci'

The following sections show how to add a collation that is defined using
LDML syntax, and provide a summary of LDML rules supported in MySQL.

10.13.4.1 Defining a UCA Collation Using LDML Syntax
....................................................

To add a UCA collation for a Unicode character set without recompiling
MySQL, use the following procedure.  If you are unfamiliar with the LDML
rules used to describe the collation's sort characteristics, see
ldml-rules.

The example adds a collation named 'utf8_phone_ci' to the 'utf8'
character set.  The collation is designed for a scenario involving a Web
application for which users post their names and phone numbers.  Phone
numbers can be given in very different formats:

     +7-12345-67
     +7-12-345-67
     +7 12 345 67
     +7 (12) 345 67
     +71234567

The problem raised by dealing with these kinds of values is that the
varying permissible formats make searching for a specific phone number
very difficult.  The solution is to define a new collation that reorders
punctuation characters, making them ignorable.

  1. Choose a collation ID, as shown in
     adding-collation-choosing-id.  The following steps use an ID of
     1029.

  2. To modify the 'Index.xml' configuration file.  This file is located
     in the directory named by the 'character_sets_dir' system variable.
     You can check the variable value as follows, although the path name
     might be different on your system:

          mysql> SHOW VARIABLES LIKE 'character_sets_dir';
          +--------------------+-----------------------------------------+
          | Variable_name      | Value                                   |
          +--------------------+-----------------------------------------+
          | character_sets_dir | /user/local/mysql/share/mysql/charsets/ |
          +--------------------+-----------------------------------------+

  3. Choose a name for the collation and list it in the 'Index.xml'
     file.  In addition, you'll need to provide the collation ordering
     rules.  Find the '<charset>' element for the character set to which
     the collation is being added, and add a '<collation>' element that
     indicates the collation name and ID, to associate the name with the
     ID. Within the '<collation>' element, provide a '<rules>' element
     containing the ordering rules:

          <charset name="utf8">
            ...
            <collation name="utf8_phone_ci" id="1029">
              <rules>
                <reset>\u0000</reset>
                <i>\u0020</i> <!-- space -->
                <i>\u0028</i> <!-- left parenthesis -->
                <i>\u0029</i> <!-- right parenthesis -->
                <i>\u002B</i> <!-- plus -->
                <i>\u002D</i> <!-- hyphen -->
              </rules>
            </collation>
            ...
          </charset>

  4. If you want a similar collation for other Unicode character sets,
     add other '<collation>' elements.  For example, to define
     'ucs2_phone_ci', add a '<collation>' element to the '<charset
     name="ucs2">' element.  Remember that each collation must have its
     own unique ID.

  5. Restart the server and use this statement to verify that the
     collation is present:

          mysql> SHOW COLLATION WHERE Collation = 'utf8_phone_ci';
          +---------------+---------+------+---------+----------+---------+
          | Collation     | Charset | Id   | Default | Compiled | Sortlen |
          +---------------+---------+------+---------+----------+---------+
          | utf8_phone_ci | utf8    | 1029 |         |          |       8 |
          +---------------+---------+------+---------+----------+---------+

Now test the collation to make sure that it has the desired properties.

Create a table containing some sample phone numbers using the new
collation:

     mysql> CREATE TABLE phonebook (
              name VARCHAR(64),
              phone VARCHAR(64) CHARACTER SET utf8 COLLATE utf8_phone_ci
            );
     Query OK, 0 rows affected (0.09 sec)

     mysql> INSERT INTO phonebook VALUES ('Svoj','+7 912 800 80 02');
     Query OK, 1 row affected (0.00 sec)

     mysql> INSERT INTO phonebook VALUES ('Hf','+7 (912) 800 80 04');
     Query OK, 1 row affected (0.00 sec)

     mysql> INSERT INTO phonebook VALUES ('Bar','+7-912-800-80-01');
     Query OK, 1 row affected (0.00 sec)

     mysql> INSERT INTO phonebook VALUES ('Ramil','(7912) 800 80 03');
     Query OK, 1 row affected (0.00 sec)

     mysql> INSERT INTO phonebook VALUES ('Sanja','+380 (912) 8008005');
     Query OK, 1 row affected (0.00 sec)

Run some queries to see whether the ignored punctuation characters are
in fact ignored for comparison and sorting:

     mysql> SELECT * FROM phonebook ORDER BY phone;
     +-------+--------------------+
     | name  | phone              |
     +-------+--------------------+
     | Sanja | +380 (912) 8008005 |
     | Bar   | +7-912-800-80-01   |
     | Svoj  | +7 912 800 80 02   |
     | Ramil | (7912) 800 80 03   |
     | Hf    | +7 (912) 800 80 04 |
     +-------+--------------------+
     5 rows in set (0.00 sec)

     mysql> SELECT * FROM phonebook WHERE phone='+7(912)800-80-01';
     +------+------------------+
     | name | phone            |
     +------+------------------+
     | Bar  | +7-912-800-80-01 |
     +------+------------------+
     1 row in set (0.00 sec)

     mysql> SELECT * FROM phonebook WHERE phone='79128008001';
     +------+------------------+
     | name | phone            |
     +------+------------------+
     | Bar  | +7-912-800-80-01 |
     +------+------------------+
     1 row in set (0.00 sec)

     mysql> SELECT * FROM phonebook WHERE phone='7 9 1 2 8 0 0 8 0 0 1';
     +------+------------------+
     | name | phone            |
     +------+------------------+
     | Bar  | +7-912-800-80-01 |
     +------+------------------+
     1 row in set (0.00 sec)

10.13.4.2 LDML Syntax Supported in MySQL
........................................

This section describes the LDML syntax that MySQL recognizes.  This is a
subset of the syntax described in the LDML specification available at
<http://www.unicode.org/reports/tr35/>, which should be consulted for
further information.  MySQL recognizes a large enough subset of the
syntax that, in many cases, it is possible to download a collation
definition from the Unicode Common Locale Data Repository and paste the
relevant part (that is, the part between the '<rules>' and '</rules>'
tags) into the MySQL 'Index.xml' file.  The rules described here are all
supported except that character sorting occurs only at the primary
level.  Rules that specify differences at secondary or higher sort
levels are recognized (and thus can be included in collation
definitions) but are treated as equality at the primary level.

The MySQL server generates diagnostics when it finds problems while
parsing the 'Index.xml' file.  See collation-diagnostics.

*Character Representation*

Characters named in LDML rules can be written literally or in '\uNNNN'
format, where NNNN is the hexadecimal Unicode code point value.  For
example, 'A' and 'a'' can be written literally or as '\u0041' and
'\u00E1'.  Within hexadecimal values, the digits 'A' through 'F' are not
case-sensitive; '\u00E1' and '\u00e1' are equivalent.  For UCA 4.0.0
collations, hexadecimal notation can be used only for characters in the
Basic Multilingual Plane, not for characters outside the BMP range of
'0000' to 'FFFF'.  For UCA 5.2.0 collations, hexadecimal notation can be
used for any character.

The 'Index.xml' file itself should be written using UTF-8 encoding.

*Syntax Rules*

LDML has reset rules and shift rules to specify character ordering.
Orderings are given as a set of rules that begin with a reset rule that
establishes an anchor point, followed by shift rules that indicate how
characters sort relative to the anchor point.

   * A '<reset>' rule does not specify any ordering in and of itself.
     Instead, it 'resets' the ordering for subsequent shift rules to
     cause them to be taken in relation to a given character.  Either of
     the following rules resets subsequent shift rules to be taken in
     relation to the letter ''A'':

          <reset>A</reset>

          <reset>\u0041</reset>

   * The '<p>', '<s>', and '<t>' shift rules define primary, secondary,
     and tertiary differences of a character from another character:

        * Use primary differences to distinguish separate letters.

        * Use secondary differences to distinguish accent variations.

        * Use tertiary differences to distinguish lettercase variations.

     Either of these rules specifies a primary shift rule for the ''G''
     character:

          <p>G</p>

          <p>\u0047</p>

   * The '<i>' shift rule indicates that one character sorts identically
     to another.  The following rules cause ''b'' to sort the same as
     ''a'':

          <reset>a</reset>
          <i>b</i>

   * Abbreviated shift syntax specifies multiple shift rules using a
     single pair of tags.  The following table shows the correspondence
     between abbreviated syntax rules and the equivalent nonabbreviated
     rules.

     *Abbreviated Shift Syntax*

     Abbreviated Syntax            Nonabbreviated Syntax

     '<pc>xyz</pc>'                '<p>x</p><p>y</p><p>z</p>'

     '<sc>xyz</sc>'                '<s>x</s><s>y</s><s>z</s>'

     '<tc>xyz</tc>'                '<t>x</t><t>y</t><t>z</t>'

     '<ic>xyz</ic>'                '<i>x</i><i>y</i><i>z</i>'

   * An expansion is a reset rule that establishes an anchor point for a
     multiple-character sequence.  MySQL supports expansions 2 to 6
     characters long.  The following rules put ''z'' greater at the
     primary level than the sequence of three characters ''abc'':

          <reset>abc</reset>
          <p>z</p>

   * A contraction is a shift rule that sorts a multiple-character
     sequence.  MySQL supports contractions 2 to 6 characters long.  The
     following rules put the sequence of three characters ''xyz''
     greater at the primary level than ''a'':

          <reset>a</reset>
          <p>xyz</p>

   * Long expansions and long contractions can be used together.  These
     rules put the sequence of three characters ''xyz'' greater at the
     primary level than the sequence of three characters ''abc'':

          <reset>abc</reset>
          <p>xyz</p>

   * Normal expansion syntax uses '<x>' plus '<extend>' elements to
     specify an expansion.  The following rules put the character ''k''
     greater at the secondary level than the sequence ''ch''.  That is,
     ''k'' behaves as if it expands to a character after ''c'' followed
     by ''h'':

          <reset>c</reset>
          <x><s>k</s><extend>h</extend></x>

     This syntax permits long sequences.  These rules sort the sequence
     ''ccs'' greater at the tertiary level than the sequence ''cscs'':

          <reset>cs</reset>
          <x><t>ccs</t><extend>cs</extend></x>

     The LDML specification describes normal expansion syntax as
     'tricky.' See that specification for details.

   * Previous context syntax uses '<x>' plus '<context>' elements to
     specify that the context before a character affects how it sorts.
     The following rules put ''-'' greater at the secondary level than
     ''a'', but only when ''-'' occurs after ''b'':

          <reset>a</reset>
          <x><context>b</context><s>-</s></x>

   * Previous context syntax can include the '<extend>' element.  These
     rules put ''def'' greater at the primary level than ''aghi'', but
     only when ''def'' comes after ''abc'':

          <reset>a</reset>
          <x><context>abc</context><p>def</p><extend>ghi</extend></x>

   * Reset rules permit a 'before' attribute.  Normally, shift rules
     after a reset rule indicate characters that sort after the reset
     character.  Shift rules after a reset rule that has the 'before'
     attribute indicate characters that sort before the reset character.
     The following rules put the character ''b'' immediately before
     ''a'' at the primary level:

          <reset before="primary">a</reset>
          <p>b</p>

     Permissible 'before' attribute values specify the sort level by
     name or the equivalent numeric value:

          <reset before="primary">
          <reset before="1">

          <reset before="secondary">
          <reset before="2">

          <reset before="tertiary">
          <reset before="3">

   * A reset rule can name a logical reset position rather than a
     literal character:

          <first_tertiary_ignorable/>
          <last_tertiary_ignorable/>
          <first_secondary_ignorable/>
          <last_secondary_ignorable/>
          <first_primary_ignorable/>
          <last_primary_ignorable/>
          <first_variable/>
          <last_variable/>
          <first_non_ignorable/>
          <last_non_ignorable/>
          <first_trailing/>
          <last_trailing/>

     These rules put ''z'' greater at the primary level than
     nonignorable characters that have a Default Unicode Collation
     Element Table (DUCET) entry and that are not CJK:

          <reset><last_non_ignorable/></reset>
          <p>z</p>

     Logical positions have the code points shown in the following
     table.

     *Logical Reset Position Code Points*

     Logical Position              Unicode 4.0.0 Code     Unicode 5.2.0 Code
                                   Point                  Point

     '<first_non_ignorable/>'      U+02D0                 U+02D0

     '<last_non_ignorable/>'       U+A48C                 U+1342E

     '<first_primary_ignorable/>'  U+0332                 U+0332

     '<last_primary_ignorable/>'   U+20EA                 U+101FD

     '<first_secondary_ignorable/>'U+0000                 U+0000

     '<last_secondary_ignorable/>' U+FE73                 U+FE73

     '<first_tertiary_ignorable/>' U+0000                 U+0000

     '<last_tertiary_ignorable/>'  U+FE73                 U+FE73

     '<first_trailing/>'           U+0000                 U+0000

     '<last_trailing/>'            U+0000                 U+0000

     '<first_variable/>'           U+0009                 U+0009

     '<last_variable/>'            U+2183                 U+1D371

   * The '<collation>' element permits a 'shift-after-method' attribute
     that affects character weight calculation for shift rules.  The
     attribute has these permitted values:

        * 'simple': Calculate character weights as for reset rules that
          do not have a 'before' attribute.  This is the default if the
          attribute is not given.

        * 'expand': Use expansions for shifts after reset rules.

     Suppose that ''0'' and ''1'' have weights of '0E29' and '0E2A' and
     we want to put all basic Latin letters between ''0'' and ''1'':

          <reset>0</reset>
          <pc>abcdefghijklmnopqrstuvwxyz</pc>

     For simple shift mode, weights are calculated as follows:

          'a' has weight 0E29+1
          'b' has weight 0E29+2
          'c' has weight 0E29+3
          ...

     However, there are not enough vacant positions to put 26 characters
     between ''0'' and ''1''.  The result is that digits and letters are
     intermixed.

     To solve this, use 'shift-after-method="expand"'.  Then weights are
     calculated like this:

          'a' has weight [0E29][233D+1]
          'b' has weight [0E29][233D+2]
          'c' has weight [0E29][233D+3]
          ...

     '233D' is the UCA 4.0.0 weight for character '0xA48C', which is the
     last nonignorable character (a sort of the greatest character in
     the collation, excluding CJK). UCA 5.2.0 is similar but uses
     '3ACA', for character '0x1342E'.

*MySQL-Specific LDML Extensions*

An extension to LDML rules permits the '<collation>' element to include
an optional 'version' attribute in '<collation>' tags to indicate the
UCA version on which the collation is based.  If the 'version' attribute
is omitted, its default value is '4.0.0'.  For example, this
specification indicates a collation that is based on UCA 5.2.0:

     <collation id="NNN" name="utf8_XXX_ci" version="5.2.0">
     ...
     </collation>

10.13.4.3 Diagnostics During Index.xml Parsing
..............................................

The MySQL server generates diagnostics when it finds problems while
parsing the 'Index.xml' file:

   * Unknown tags are written to the error log.  For example, the
     following message results if a collation definition contains a
     '<aaa>' tag:

          [Warning] Buffered warning: Unknown LDML tag:
          'charsets/charset/collation/rules/aaa'

   * If collation initialization is not possible, the server reports an
     'Unknown collation' error, and also generates warnings explaining
     the problems, such as in the previous example.  In other cases,
     when a collation description is generally correct but contains some
     unknown tags, the collation is initialized and is available for
     use.  The unknown parts are ignored, but a warning is generated in
     the error log.

   * Problems with collations generate warnings that clients can display
     with 'SHOW WARNINGS'.  Suppose that a reset
     rule contains an expansion longer than the maximum supported length
     of 6 characters:

          <reset>abcdefghi</reset>
          <i>x</i>

     An attempt to use the collation produces warnings:

          mysql> SELECT _utf8'test' COLLATE utf8_test_ci;
          ERROR 1273 (HY000): Unknown collation: 'utf8_test_ci'
          mysql> SHOW WARNINGS;
          +---------+------+----------------------------------------+
          | Level   | Code | Message                                |
          +---------+------+----------------------------------------+
          | Error   | 1273 | Unknown collation: 'utf8_test_ci'      |
          | Warning | 1273 | Expansion is too long at 'abcdefghi=x' |
          +---------+------+----------------------------------------+

10.14 Character Set Configuration
=================================

You can change the default server character set and collation with the
'--character-set-server' and '--collation-server' options when you start
the server.  The collation must be a legal collation for the default
character set.  (Use the 'SHOW COLLATION'.
statement to determine which collations are available for each character
set.)  See server-options.

If you try to use a character set that is not compiled into your binary,
you might run into the following problems:

   * Your program uses an incorrect path to determine where the
     character sets are stored (which is typically the
     'share/mysql/charsets' or 'share/charsets' directory under the
     MySQL installation directory).  This can be fixed by using the
     '--character-sets-dir' option when you run the program in question.
     For example, to specify a directory to be used by MySQL client
     programs, list it in the '[client]' group of your option file.  The
     examples given here show what the setting might look like for Unix
     or Windows, respectively:

          [client]
          character-sets-dir=/usr/local/mysql/share/mysql/charsets

          [client]
          character-sets-dir="C:/Program Files/MySQL/MySQL Server 5.7/share/charsets"

   * The character set is a complex character set that cannot be loaded
     dynamically.  In this case, you must recompile the program with
     support for the character set.

     For Unicode character sets, you can define collations without
     recompiling by using LDML notation.  See
     adding-collation-unicode-uca.

   * The character set is a dynamic character set, but you do not have a
     configuration file for it.  In this case, you should install the
     configuration file for the character set from a new MySQL
     distribution.

   * If your character set index file does not contain the name for the
     character set, your program displays an error message.  The file is
     named 'Index.xml' and the message is:

          Character set 'CHARSET_NAME' is not a compiled character set and is not
          specified in the '/usr/share/mysql/charsets/Index.xml' file

     To solve this problem, you should either get a new index file or
     manually add the name of any missing character sets to the current
     file.

You can force client programs to use specific character set as follows:

     [client]
     default-character-set=CHARSET_NAME

This is normally unnecessary.  However, when 'character_set_system'
differs from 'character_set_server' or 'character_set_client', and you
input characters manually (as database object identifiers, column
values, or both), these may be displayed incorrectly in output from the
client or the output itself may be formatted incorrectly.  In such
cases, starting the mysql client with
'--default-character-set=SYSTEM_CHARACTER_SET'--that is, setting the
client character set to match the system character set--should fix the
problem.

For 'MyISAM' tables, you can check the character set name and number for
a table with 'myisamchk -dvv TBL_NAME'.

10.15 MySQL Server Locale Support
=================================

The locale indicated by the 'lc_time_names' system variable controls the
language used to display day and month names and abbreviations.  This
variable affects the output from the 'DATE_FORMAT()', 'DAYNAME()', and
'MONTHNAME()' functions.

'lc_time_names' does not affect the 'STR_TO_DATE()' or 'GET_FORMAT()'
function.

The 'lc_time_names' value does not affect the result from 'FORMAT()',
but this function takes an optional third parameter that enables a
locale to be specified to be used for the result number's decimal point,
thousands separator, and grouping between separators.  Permissible
locale values are the same as the legal values for the 'lc_time_names'
system variable.

Locale names have language and region subtags listed by IANA
(<http://www.iana.org/assignments/language-subtag-registry>) such as
''ja_JP'' or ''pt_BR''.  The default value is ''en_US'' regardless of
your system's locale setting, but you can set the value at server
startup or set the 'GLOBAL' value if you have the 'SUPER' privilege.
Any client can examine the value of 'lc_time_names' or set its 'SESSION'
value to affect the locale for its own connection.

     mysql> SET NAMES 'utf8';
     Query OK, 0 rows affected (0.09 sec)

     mysql> SELECT @@lc_time_names;
     +-----------------+
     | @@lc_time_names |
     +-----------------+
     | en_US           |
     +-----------------+
     1 row in set (0.00 sec)

     mysql> SELECT DAYNAME('2010-01-01'), MONTHNAME('2010-01-01');
     +-----------------------+-------------------------+
     | DAYNAME('2010-01-01') | MONTHNAME('2010-01-01') |
     +-----------------------+-------------------------+
     | Friday                | January                 |
     +-----------------------+-------------------------+
     1 row in set (0.00 sec)

     mysql> SELECT DATE_FORMAT('2010-01-01','%W %a %M %b');
     +-----------------------------------------+
     | DATE_FORMAT('2010-01-01','%W %a %M %b') |
     +-----------------------------------------+
     | Friday Fri January Jan                  |
     +-----------------------------------------+
     1 row in set (0.00 sec)

     mysql> SET lc_time_names = 'es_MX';
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @@lc_time_names;
     +-----------------+
     | @@lc_time_names |
     +-----------------+
     | es_MX           |
     +-----------------+
     1 row in set (0.00 sec)

     mysql> SELECT DAYNAME('2010-01-01'), MONTHNAME('2010-01-01');
     +-----------------------+-------------------------+
     | DAYNAME('2010-01-01') | MONTHNAME('2010-01-01') |
     +-----------------------+-------------------------+
     | viernes               | enero                   |
     +-----------------------+-------------------------+
     1 row in set (0.00 sec)

     mysql> SELECT DATE_FORMAT('2010-01-01','%W %a %M %b');
     +-----------------------------------------+
     | DATE_FORMAT('2010-01-01','%W %a %M %b') |
     +-----------------------------------------+
     | viernes vie enero ene                   |
     +-----------------------------------------+
     1 row in set (0.00 sec)

The day or month name for each of the affected functions is converted
from 'utf8' to the character set indicated by the
'character_set_connection' system variable.

'lc_time_names' may be set to any of the following locale values.  The
set of locales supported by MySQL may differ from those supported by
your operating system.

Locale Value                         Meaning

'ar_AE': Arabic - United Arab        'ar_BH': Arabic - Bahrain
Emirates

'ar_DZ': Arabic - Algeria            'ar_EG': Arabic - Egypt

'ar_IN': Arabic - India              'ar_IQ': Arabic - Iraq

'ar_JO': Arabic - Jordan             'ar_KW': Arabic - Kuwait

'ar_LB': Arabic - Lebanon            'ar_LY': Arabic - Libya

'ar_MA': Arabic - Morocco            'ar_OM': Arabic - Oman

'ar_QA': Arabic - Qatar              'ar_SA': Arabic - Saudi Arabia

'ar_SD': Arabic - Sudan              'ar_SY': Arabic - Syria

'ar_TN': Arabic - Tunisia            'ar_YE': Arabic - Yemen

'be_BY': Belarusian - Belarus        'bg_BG': Bulgarian - Bulgaria

'ca_ES': Catalan - Spain             'cs_CZ': Czech - Czech Republic

'da_DK': Danish - Denmark            'de_AT': German - Austria

'de_BE': German - Belgium            'de_CH': German - Switzerland

'de_DE': German - Germany            'de_LU': German - Luxembourg

'el_GR': Greek - Greece              'en_AU': English - Australia

'en_CA': English - Canada            'en_GB': English - United Kingdom

'en_IN': English - India             'en_NZ': English - New Zealand

'en_PH': English - Philippines       'en_US': English - United States

'en_ZA': English - South Africa      'en_ZW': English - Zimbabwe

'es_AR': Spanish - Argentina         'es_BO': Spanish - Bolivia

'es_CL': Spanish - Chile             'es_CO': Spanish - Colombia

'es_CR': Spanish - Costa Rica        'es_DO': Spanish - Dominican
                                     Republic

'es_EC': Spanish - Ecuador           'es_ES': Spanish - Spain

'es_GT': Spanish - Guatemala         'es_HN': Spanish - Honduras

'es_MX': Spanish - Mexico            'es_NI': Spanish - Nicaragua

'es_PA': Spanish - Panama            'es_PE': Spanish - Peru

'es_PR': Spanish - Puerto Rico       'es_PY': Spanish - Paraguay

'es_SV': Spanish - El Salvador       'es_US': Spanish - United States

'es_UY': Spanish - Uruguay           'es_VE': Spanish - Venezuela

'et_EE': Estonian - Estonia          'eu_ES': Basque - Basque

'fi_FI': Finnish - Finland           'fo_FO': Faroese - Faroe Islands

'fr_BE': French - Belgium            'fr_CA': French - Canada

'fr_CH': French - Switzerland        'fr_FR': French - France

'fr_LU': French - Luxembourg         'gl_ES': Galician - Spain

'gu_IN': Gujarati - India            'he_IL': Hebrew - Israel

'hi_IN': Hindi - India               'hr_HR': Croatian - Croatia

'hu_HU': Hungarian - Hungary         'id_ID': Indonesian - Indonesia

'is_IS': Icelandic - Iceland         'it_CH': Italian - Switzerland

'it_IT': Italian - Italy             'ja_JP': Japanese - Japan

'ko_KR': Korean - Republic of        'lt_LT': Lithuanian - Lithuania
Korea

'lv_LV': Latvian - Latvia            'mk_MK': Macedonian - FYROM

'mn_MN': Mongolia - Mongolian        'ms_MY': Malay - Malaysia

'nb_NO': Norwegian(Bokmaal) -        'nl_BE': Dutch - Belgium
Norway

'nl_NL': Dutch - The Netherlands     'no_NO': Norwegian - Norway

'pl_PL': Polish - Poland             'pt_BR': Portugese - Brazil

'pt_PT': Portugese - Portugal        'rm_CH': Romansh - Switzerland

'ro_RO': Romanian - Romania          'ru_RU': Russian - Russia

'ru_UA': Russian - Ukraine           'sk_SK': Slovak - Slovakia

'sl_SI': Slovenian - Slovenia        'sq_AL': Albanian - Albania

'sr_RS': Serbian - Yugoslavia        'sv_FI': Swedish - Finland

'sv_SE': Swedish - Sweden            'ta_IN': Tamil - India

'te_IN': Telugu - India              'th_TH': Thai - Thailand

'tr_TR': Turkish - Turkey            'uk_UA': Ukrainian - Ukraine

'ur_PK': Urdu - Pakistan             'vi_VN': Vietnamese - Viet Nam

'zh_CN': Chinese - China             'zh_HK': Chinese - Hong Kong

'zh_TW': Chinese - Taiwan Province
of China

11 Data Types
*************

MySQL supports a number of SQL data types in several categories: numeric
types, date and time types, string (character and byte) types, spatial
types, and the 'JSON' data type.  This chapter provides an
overview of these data types, a more detailed description of the
properties of the types in each category, and a summary of the data type
storage requirements.  The initial overview is intentionally brief.  The
more detailed descriptions later in the chapter should be consulted for
additional information about particular data types, such as the
permissible formats in which you can specify values.

Data type descriptions use these conventions:

   *
     M indicates the maximum display width for integer types.  For
     floating-point and fixed-point types, M is the total number of
     digits that can be stored (the precision).  For string types, M is
     the maximum length.  The maximum permissible value of M depends on
     the data type.

   *
     D applies to floating-point and fixed-point types and indicates the
     number of digits following the decimal point (the scale).  The
     maximum possible value is 30, but should be no greater than M−2.

   *
     FSP applies to the 'TIME', 'DATETIME',
     and 'TIMESTAMP' types and represents fractional
     seconds precision; that is, the number of digits following the
     decimal point for fractional parts of seconds.  The FSP value, if
     given, must be in the range 0 to 6.  A value of 0 signifies that
     there is no fractional part.  If omitted, the default precision is
     0.  (This differs from the standard SQL default of 6, for
     compatibility with previous MySQL versions.)

   *
     Square brackets ('[' and ']') indicate optional parts of type
     definitions.

11.1 Data Type Overview
=======================

11.1.1 Numeric Type Overview
----------------------------

A summary of the numeric data types follows.  For additional information
about properties and storage requirements of the numeric types, see
numeric-types, and storage-requirements.

M indicates the maximum display width for integer types.  The maximum
display width is 255.  Display width is unrelated to the range of values
a type can contain, as described in numeric-types.  For
floating-point and fixed-point types, M is the total number of digits
that can be stored.

If you specify 'ZEROFILL' for a numeric column, MySQL automatically adds
the 'UNSIGNED' attribute to the column.

Numeric data types that permit the 'UNSIGNED' attribute also permit
'SIGNED'.  However, these data types are signed by default, so the
'SIGNED' attribute has no effect.

'SERIAL' is an alias for 'BIGINT UNSIGNED NOT NULL AUTO_INCREMENT
UNIQUE'.

'SERIAL DEFAULT VALUE' in the definition of an integer column is an
alias for 'NOT NULL AUTO_INCREMENT UNIQUE'.

*Warning*:

When you use subtraction between integer values where one is of type
'UNSIGNED', the result is unsigned unless the 'NO_UNSIGNED_SUBTRACTION'
SQL mode is enabled.  See cast-functions.

   *
     'BIT[(M)]'.

     A bit-value type.  M indicates the number of bits per value, from 1
     to 64.  The default is 1 if M is omitted.

   *
     'TINYINT[(M)] [UNSIGNED] [ZEROFILL]'.

     A very small integer.  The signed range is '-128' to '127'.  The
     unsigned range is '0' to '255'.

   *
     'BOOL', 'BOOLEAN'.

     These types are synonyms for 'TINYINT(1)'.  A
     value of zero is considered false.  Nonzero values are considered
     true:

          mysql> SELECT IF(0, 'true', 'false');
          +------------------------+
          | IF(0, 'true', 'false') |
          +------------------------+
          | false                  |
          +------------------------+

          mysql> SELECT IF(1, 'true', 'false');
          +------------------------+
          | IF(1, 'true', 'false') |
          +------------------------+
          | true                   |
          +------------------------+

          mysql> SELECT IF(2, 'true', 'false');
          +------------------------+
          | IF(2, 'true', 'false') |
          +------------------------+
          | true                   |
          +------------------------+

     However, the values 'TRUE' and 'FALSE' are merely aliases for '1'
     and '0', respectively, as shown here:

          mysql> SELECT IF(0 = FALSE, 'true', 'false');
          +--------------------------------+
          | IF(0 = FALSE, 'true', 'false') |
          +--------------------------------+
          | true                           |
          +--------------------------------+

          mysql> SELECT IF(1 = TRUE, 'true', 'false');
          +-------------------------------+
          | IF(1 = TRUE, 'true', 'false') |
          +-------------------------------+
          | true                          |
          +-------------------------------+

          mysql> SELECT IF(2 = TRUE, 'true', 'false');
          +-------------------------------+
          | IF(2 = TRUE, 'true', 'false') |
          +-------------------------------+
          | false                         |
          +-------------------------------+

          mysql> SELECT IF(2 = FALSE, 'true', 'false');
          +--------------------------------+
          | IF(2 = FALSE, 'true', 'false') |
          +--------------------------------+
          | false                          |
          +--------------------------------+

     The last two statements display the results shown because '2' is
     equal to neither '1' nor '0'.

   *
     'SMALLINT[(M)] [UNSIGNED] [ZEROFILL]'.

     A small integer.  The signed range is '-32768' to '32767'.  The
     unsigned range is '0' to '65535'.

   *
     'MEDIUMINT[(M)] [UNSIGNED] [ZEROFILL]'.

     A medium-sized integer.  The signed range is '-8388608' to
     '8388607'.  The unsigned range is '0' to '16777215'.

   *
     'INT[(M)] [UNSIGNED] [ZEROFILL]'.

     A normal-size integer.  The signed range is '-2147483648' to
     '2147483647'.  The unsigned range is '0' to '4294967295'.

   *
     'INTEGER[(M)] [UNSIGNED] [ZEROFILL]'.

     This type is a synonym for 'INT'.

   *
     'BIGINT[(M)] [UNSIGNED] [ZEROFILL]'.

     A large integer.  The signed range is '-9223372036854775808' to
     '9223372036854775807'.  The unsigned range is '0' to
     '18446744073709551615'.

     'SERIAL' is an alias for 'BIGINT UNSIGNED NOT NULL AUTO_INCREMENT
     UNIQUE'.

     Some things you should be aware of with respect to 'BIGINT'
     columns:

        *
          All arithmetic is done using signed 'BIGINT'
          or 'DOUBLE'.
          values, so you should not use unsigned big integers larger
          than '9223372036854775807' (63 bits) except with bit
          functions!  If you do that, some of the last digits in the
          result may be wrong because of rounding errors when converting
          a 'BIGINT' value to a 'DOUBLE'.

          MySQL can handle 'BIGINT' in the
          following cases:

             * When using integers to store large unsigned values in a
               'BIGINT' column.

             * In 'MIN(COL_NAME)' or 'MAX(COL_NAME)', where COL_NAME
               refers to a 'BIGINT' column.

             * When using operators ('+', '-', '*', and so on) where
               both operands are integers.

        * You can always store an exact integer value in a
          'BIGINT' column by storing it using a string.
          In this case, MySQL performs a string-to-number conversion
          that involves no intermediate double-precision representation.

        * The '-', '+', and '*' operators use 'BIGINT'
          arithmetic when both operands are integer
          values.  This means that if you multiply two big integers (or
          results from functions that return integers), you may get
          unexpected results when the result is larger than
          '9223372036854775807'.

   *
     'DECIMAL[(M[,D])] [UNSIGNED] [ZEROFILL]'.

     A packed 'exact' fixed-point number.  M is the total number of
     digits (the precision) and D is the number of digits after the
     decimal point (the scale).  The decimal point and (for negative
     numbers) the '-' sign are not counted in M.  If D is 0, values have
     no decimal point or fractional part.  The maximum number of digits
     (M) for 'DECIMAL' is 65.  The maximum
     number of supported decimals (D) is 30.  If D is omitted, the
     default is 0.  If M is omitted, the default is 10.

     'UNSIGNED', if specified, disallows negative values.

     All basic calculations ('+, -, *, /') with 'DECIMAL'
     columns are done with a precision of 65 digits.

   *
     'DEC[(M[,D])] [UNSIGNED] [ZEROFILL]',
     'NUMERIC[(M[,D])] [UNSIGNED] [ZEROFILL]'
     'FIXED[(M[,D])] [UNSIGNED] [ZEROFILL]'.

     These types are synonyms for 'DECIMAL'.
     The 'FIXED' synonym is available for
     compatibility with other database systems.

   *
     'FLOAT[(M,D)] [UNSIGNED] [ZEROFILL]'.

     A small (single-precision) floating-point number.  Permissible
     values are '-3.402823466E+38' to '-1.175494351E-38', '0', and
     '1.175494351E-38' to '3.402823466E+38'.  These are the theoretical
     limits, based on the IEEE standard.  The actual range might be
     slightly smaller depending on your hardware or operating system.

     M is the total number of digits and D is the number of digits
     following the decimal point.  If M and D are omitted, values are
     stored to the limits permitted by the hardware.  A single-precision
     floating-point number is accurate to approximately 7 decimal
     places.

     'UNSIGNED', if specified, disallows negative values.

     Using 'FLOAT' might give you some
     unexpected problems because all calculations in MySQL are done with
     double precision.  See no-matching-rows.

   *
     'DOUBLE[(M,D)] [UNSIGNED] [ZEROFILL]'.

     A normal-size (double-precision) floating-point number.
     Permissible values are '-1.7976931348623157E+308' to
     '-2.2250738585072014E-308', '0', and '2.2250738585072014E-308' to
     '1.7976931348623157E+308'.  These are the theoretical limits, based
     on the IEEE standard.  The actual range might be slightly smaller
     depending on your hardware or operating system.

     M is the total number of digits and D is the number of digits
     following the decimal point.  If M and D are omitted, values are
     stored to the limits permitted by the hardware.  A double-precision
     floating-point number is accurate to approximately 15 decimal
     places.

     'UNSIGNED', if specified, disallows negative values.

   *
     'DOUBLE PRECISION[(M,D)] [UNSIGNED] [ZEROFILL]',
     see 'REAL[(M,D)] [UNSIGNED] [ZEROFILL]'.

     These types are synonyms for 'DOUBLE'.
     Exception: If the 'REAL_AS_FLOAT' SQL mode is enabled, see
     'REAL' is a synonym for 'FLOAT'
     rather than 'DOUBLE'.

   *
     'FLOAT(P) [UNSIGNED] [ZEROFILL]'.

     A floating-point number.  P represents the precision in bits, but
     MySQL uses this value only to determine whether to use
     'FLOAT' or 'DOUBLE'
     for the resulting data type.  If P is from 0
     to 24, the data type becomes 'FLOAT'.
     with no M or D values.  If P is from 25 to 53, the data type
     becomes 'DOUBLE' with no M or D
     values.  The range of the resulting column is the same as for the
     single-precision 'FLOAT' or
     double-precision 'DOUBLE' data types
     described earlier in this section.

     'FLOAT(P)' syntax is provided for ODBC
     compatibility.

11.1.2 Date and Time Type Overview
----------------------------------

A summary of the temporal data types follows.  For additional
information about properties and storage requirements of the temporal
types, see date-and-time-types, and
storage-requirements.  For descriptions of functions that operate on
temporal values, see date-and-time-functions.

For the 'DATE' and 'DATETIME' range
descriptions, 'supported' means that although earlier values might work,
there is no guarantee.

MySQL permits fractional seconds for 'TIME',
'DATETIME', and 'TIMESTAMP' values, with up
to microseconds (6 digits) precision.  To define a column that includes
a fractional seconds part, use the syntax 'TYPE_NAME(FSP)', where
TYPE_NAME is 'TIME', 'DATETIME', or
'TIMESTAMP', and FSP is the fractional seconds precision.  For
example:

     CREATE TABLE t1 (t TIME(3), dt DATETIME(6));

The FSP value, if given, must be in the range 0 to 6.  A value of 0
signifies that there is no fractional part.  If omitted, the default
precision is 0.  (This differs from the standard SQL default of 6, for
compatibility with previous MySQL versions.)

Any 'TIMESTAMP' or 'DATETIME' column
in a table can have automatic initialization and updating properties.

   *
     'DATE'.

     A date.  The supported range is ''1000-01-01'' to ''9999-12-31''.
     MySQL displays 'DATE' values in ''YYYY-MM-DD''
     format, but permits assignment of values to 'DATE'.
     columns using either strings or numbers.

   *
     'DATETIME[(FSP)]'.

     A date and time combination.  The supported range is ''1000-01-01
     00:00:00.000000'' to ''9999-12-31 23:59:59.999999''.  MySQL
     displays 'DATETIME' values in ''YYYY-MM-DD
     HH:MM:SS[.fraction]'' format, but permits assignment of values to
     'DATETIME' columns using either strings or
     numbers.

     An optional FSP value in the range from 0 to 6 may be given to
     specify fractional seconds precision.  A value of 0 signifies that
     there is no fractional part.  If omitted, the default precision is
     0.

     Automatic initialization and updating to the current date and time
     for 'DATETIME' columns can be specified using
     'DEFAULT' and 'ON UPDATE' column definition clauses, as described
     in timestamp-initialization.

   *
     'TIMESTAMP[(FSP)]'.

     A timestamp.  The range is ''1970-01-01 00:00:01.000000'' UTC to
     ''2038-01-19 03:14:07.999999'' UTC. See 'TIMESTAMP'.
     values are stored as the number of seconds since the epoch
     (''1970-01-01 00:00:00'' UTC). A 'TIMESTAMP'.
     cannot represent the value ''1970-01-01 00:00:00'' because that is
     equivalent to 0 seconds from the epoch and the value 0 is reserved
     for representing ''0000-00-00 00:00:00'', the 'zero'
     'TIMESTAMP' value.

     An optional FSP value in the range from 0 to 6 may be given to
     specify fractional seconds precision.  A value of 0 signifies that
     there is no fractional part.  If omitted, the default precision is
     0.

     The way the server handles 'TIMESTAMP' definitions depends on the
     value of the 'explicit_defaults_for_timestamp' system variable (see
     server-system-variables).

     If 'explicit_defaults_for_timestamp' is enabled, there is no
     automatic assignment of the 'DEFAULT CURRENT_TIMESTAMP' or 'ON
     UPDATE CURRENT_TIMESTAMP' attributes to any 'TIMESTAMP'
     column.  They must be included explicitly in the column
     definition.  Also, any 'TIMESTAMP' not explicitly
     declared as 'NOT NULL' permits 'NULL' values.

     If 'explicit_defaults_for_timestamp' is disabled, the server
     handles 'TIMESTAMP' as follows:

     Unless specified otherwise, the first 'TIMESTAMP'.
     column in a table is defined to be automatically set to the date
     and time of the most recent modification if not explicitly assigned
     a value.  This makes 'TIMESTAMP' useful for
     recording the timestamp of an 'INSERT' or
     'UPDATE' operation.  You can also set any
     'TIMESTAMP' column to the current date and time by
     assigning it a 'NULL' value, unless it has been defined with the
     'NULL' attribute to permit 'NULL' values.

     Automatic initialization and updating to the current date and time
     can be specified using 'DEFAULT CURRENT_TIMESTAMP' and 'ON UPDATE
     CURRENT_TIMESTAMP' column definition clauses.  By default, the
     first 'TIMESTAMP' column has these properties, as
     previously noted.  However, any 'TIMESTAMP' column
     in a table can be defined to have these properties.

   *
     'TIME[(FSP)]'.

     A time.  The range is ''-838:59:59.000000'' to
     ''838:59:59.000000''.  MySQL displays 'TIME' values in
     ''HH:MM:SS[.fraction]'' format, but permits assignment of values to
     'TIME' columns using either strings or numbers.

     An optional FSP value in the range from 0 to 6 may be given to
     specify fractional seconds precision.  A value of 0 signifies that
     there is no fractional part.  If omitted, the default precision is
     0.

   *
     'YEAR[(4)]'.

     A year in four-digit format.  MySQL displays 'YEAR'.
     values in 'YYYY' format, but permits assignment of values to
     'YEAR' columns using either strings or numbers.  Values
     display as '1901' to '2155', and '0000'.

     *Note*:

     The 'YEAR(2)' data type is deprecated and support for
     it is removed in MySQL 5.7.5.  To convert 'YEAR(2)'.
     columns to 'YEAR(4)', see migrating-to-year4.

     For additional information about 'YEAR' display format
     and interpretation of input values, see year.

The 'SUM()' and 'AVG()' aggregate functions do not work with temporal
values.  (They convert the values to numbers, losing everything after
the first nonnumeric character.)  To work around this problem, convert
to numeric units, perform the aggregate operation, and convert back to a
temporal value.  Examples:

     SELECT SEC_TO_TIME(SUM(TIME_TO_SEC(TIME_COL))) FROM TBL_NAME;
     SELECT FROM_DAYS(SUM(TO_DAYS(DATE_COL))) FROM TBL_NAME;

*Note*:

The MySQL server can be run with the 'MAXDB' SQL mode enabled.  In this
case, see 'TIMESTAMP' is identical with 'DATETIME'.
If this mode is enabled at the time that a table is created,
see 'TIMESTAMP' columns are created as 'DATETIME'
columns.  As a result, such columns use 'DATETIME'
display format, have the same range of values, and there is no
automatic initialization or updating to the current date and time.  See
sql-mode.

*Note*:

As of MySQL 5.7.22, 'MAXDB' is deprecated.  It will be removed in a
future version of MySQL.

11.1.3 String Type Overview
---------------------------

A summary of the string data types follows.  For additional information
about properties and storage requirements of the string types, see
string-types, and storage-requirements.

In some cases, MySQL may change a string column to a type different from
that given in a 'CREATE TABLE' or 'ALTER TABLE'
statement.  See silent-column-changes.

MySQL interprets length specifications in character column definitions
in character units.  This applies to 'CHAR',
'VARCHAR', and the 'TEXT' types.

Column definitions for many string data types can include attributes
that specify the character set or collation of the column.  These
attributes apply to the 'CHAR', 'VARCHAR', the
'TEXT' types, see 'ENUM', and 'SET'.
data types:

   * The 'CHARACTER SET' attribute specifies the character set, and the
     'COLLATE' attribute specifies a collation for the character set.
     For example:

          CREATE TABLE t
          (
              c1 VARCHAR(20) CHARACTER SET utf8,
              c2 TEXT CHARACTER SET latin1 COLLATE latin1_general_cs
          );

     This table definition creates a column named 'c1' that has a
     character set of 'utf8' with the default collation for that
     character set, and a column named 'c2' that has a character set of
     'latin1' and a case-sensitive collation.

     The rules for assigning the character set and collation when either
     or both of the 'CHARACTER SET' and 'COLLATE' attributes are missing
     are described in charset-column.

     'CHARSET' is a synonym for 'CHARACTER SET'.

   * Specifying the 'CHARACTER SET binary' attribute for a character
     string data type causes the column to be created as the
     corresponding binary string data type: 'CHAR' becomes
     'BINARY', 'VARCHAR' becomes
     'VARBINARY', and 'TEXT'.
     becomes 'BLOB'.  For the 'ENUM' and
     'SET' data types, this does not occur; they are created as
     declared.  Suppose that you specify a table using this definition:

          CREATE TABLE t
          (
            c1 VARCHAR(10) CHARACTER SET binary,
            c2 TEXT CHARACTER SET binary,
            c3 ENUM('a','b','c') CHARACTER SET binary
          );

     The resulting table has this definition:

          CREATE TABLE t
          (
            c1 VARBINARY(10),
            c2 BLOB,
            c3 ENUM('a','b','c') CHARACTER SET binary
          );

   * The 'BINARY' attribute is shorthand for specifying the table
     default character set and the binary ('_bin') collation of that
     character set.  In this case, comparison and sorting are based on
     numeric character code values.

   * The 'ASCII' attribute is shorthand for 'CHARACTER SET latin1'.

   * The 'UNICODE' attribute is shorthand for 'CHARACTER SET ucs2'.

Character column comparison and sorting are based on the collation
assigned to the column.  For the 'CHAR', 'VARCHAR',
see 'TEXT', 'ENUM', and 'SET' data
types, you can declare a column with a binary ('_bin') collation or the
'BINARY' attribute to cause comparison and sorting to use the underlying
character code values rather than a lexical ordering.

For additional information about use of character sets in MySQL, see
charset.

   *
     '[NATIONAL] CHAR[(M)] [CHARACTER SET CHARSET_NAME] [COLLATE
     COLLATION_NAME]'

     A fixed-length string that is always right-padded with spaces to
     the specified length when stored.  M represents the column length
     in characters.  The range of M is 0 to 255.  If M is omitted, the
     length is 1.

     *Note*:

     Trailing spaces are removed when 'CHAR' values are
     retrieved unless the 'PAD_CHAR_TO_FULL_LENGTH' SQL mode is enabled.

     'CHAR' is shorthand for 'CHARACTER'.
     See 'NATIONAL CHAR'. (or its equivalent short form, see
     'NCHAR') is the standard SQL way to define that a
     'CHAR' column should use some predefined character set.
     MySQL uses 'utf8' as this predefined character set.  See
     charset-national.

     The 'CHAR BYTE' data type is an alias for
     the 'BINARY' data type.  This is a
     compatibility feature.

     MySQL permits you to create a column of type 'CHAR(0)'.  This is
     useful primarily when you have to be compliant with old
     applications that depend on the existence of a column but that do
     not actually use its value.  'CHAR(0)' is also quite nice when you
     need a column that can take only two values: A column that is
     defined as 'CHAR(0) NULL' occupies only one bit and can take only
     the values 'NULL' and '''' (the empty string).

   *
     '[NATIONAL] VARCHAR(M) [CHARACTER SET CHARSET_NAME] [COLLATE
     COLLATION_NAME]'

     A variable-length string.  M represents the maximum column length
     in characters.  The range of M is 0 to 65,535.  The effective
     maximum length of a 'VARCHAR' is subject to the
     maximum row size (65,535 bytes, which is shared among all columns)
     and the character set used.  For example, 'utf8' characters can
     require up to three bytes per character, so a 'VARCHAR'
     column that uses the 'utf8' character set can be declared to
     be a maximum of 21,844 characters.  See column-count-limit.

     MySQL stores 'VARCHAR' values as a 1-byte or 2-byte
     length prefix plus data.  The length prefix indicates the number of
     bytes in the value.  A 'VARCHAR' column uses one
     length byte if values require no more than 255 bytes, two length
     bytes if values may require more than 255 bytes.

     *Note*:

     MySQL follows the standard SQL specification, and does _not_ remove
     trailing spaces from 'VARCHAR' values.

     'VARCHAR' is shorthand for 'CHARACTER VARYING'.
     'NATIONAL VARCHAR' is the standard SQL way to
     define that a 'VARCHAR' column should use some
     predefined character set.  MySQL uses 'utf8' as this predefined
     character set.  See charset-national.  See 'NVARCHAR'.
     is shorthand for 'NATIONAL VARCHAR'.

   *
     'BINARY[(M)]'.

     The 'BINARY' type is similar to the
     'CHAR' type, but stores binary byte strings rather than
     nonbinary character strings.  An optional length M represents the
     column length in bytes.  If omitted, M defaults to 1.

   *
     'VARBINARY(M)'.

     The 'VARBINARY' type is similar to the
     'VARCHAR' type, but stores binary byte strings rather
     than nonbinary character strings.  M represents the maximum column
     length in bytes.

   *
     'TINYBLOB'.

     A 'BLOB' column with a maximum length of 255 (2^8 −
     1) bytes.  Each 'TINYBLOB' value is stored using a
     1-byte length prefix that indicates the number of bytes in the
     value.

   *
     'TINYTEXT [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]'.

     A 'TEXT' column with a maximum length of 255 (2^8 −
     1) characters.  The effective maximum length is less if the value
     contains multibyte characters.  Each 'TINYTEXT' value
     is stored using a 1-byte length prefix that indicates the number of
     bytes in the value.

   *
     'BLOB[(M)]'.

     A 'BLOB' column with a maximum length of 65,535 (2^16
     − 1) bytes.  Each 'BLOB' value is stored using a
     2-byte length prefix that indicates the number of bytes in the
     value.

     An optional length M can be given for this type.  If this is done,
     MySQL creates the column as the smallest 'BLOB' type
     large enough to hold values M bytes long.

   *
     'TEXT[(M)] [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]'.

     A 'TEXT' column with a maximum length of 65,535 (2^16
     − 1) characters.  The effective maximum length is less if the
     value contains multibyte characters.  Each 'TEXT'.
     value is stored using a 2-byte length prefix that indicates the
     number of bytes in the value.

     An optional length M can be given for this type.  If this is done,
     MySQL creates the column as the smallest 'TEXT' type
     large enough to hold values M characters long.

   *
     'MEDIUMBLOB'.

     A 'BLOB' column with a maximum length of 16,777,215
     (2^24 − 1) bytes.  Each 'MEDIUMBLOB' value is stored
     using a 3-byte length prefix that indicates the number of bytes in
     the value.

   *
     'MEDIUMTEXT [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]'.

     A 'TEXT' column with a maximum length of 16,777,215
     (2^24 − 1) characters.  The effective maximum length is less if
     the value contains multibyte characters.  Each 'MEDIUMTEXT'
     value is stored using a 3-byte length prefix that indicates
     the number of bytes in the value.

   *
     'LONGBLOB'.

     A 'BLOB' column with a maximum length of 4,294,967,295
     or 4GB (2^32 − 1) bytes.  The effective maximum length of
     'LONGBLOB' columns depends on the configured maximum packet
     size in the client/server protocol and available memory.  Each
     'LONGBLOB' value is stored using a 4-byte length
     prefix that indicates the number of bytes in the value.

   *
     'LONGTEXT [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]'.

     A 'TEXT' column with a maximum length of 4,294,967,295
     or 4GB (2^32 − 1) characters.  The effective maximum length is
     less if the value contains multibyte characters.  The effective
     maximum length of 'LONGTEXT' columns also depends on
     the configured maximum packet size in the client/server protocol
     and available memory.  Each 'LONGTEXT' value is stored
     using a 4-byte length prefix that indicates the number of bytes in
     the value.

   *
     'ENUM('VALUE1','VALUE2',...) [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]'.

     An enumeration.  A string object that can have only one value,
     chosen from the list of values ''VALUE1'', ''VALUE2'', '...',
     'NULL' or the special '''' error value.  'ENUM' values
     are represented internally as integers.

     An 'ENUM' column can have a maximum of 65,535 distinct
     elements.  (The practical limit is less than 3000.)  A table can
     have no more than 255 unique element list definitions among its
     'ENUM' and 'SET' columns considered as a
     group.  For more information on these limits, see
     limits-frm-file.

   *
     'SET('VALUE1','VALUE2',...) [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]'.

     A set.  A string object that can have zero or more values, each of
     which must be chosen from the list of values ''VALUE1'',
     ''VALUE2'', '...' 'SET' values are represented
     internally as integers.

     A 'SET' column can have a maximum of 64 distinct
     members.  A table can have no more than 255 unique element list
     definitions among its 'ENUM' and 'SET'.
     columns considered as a group.  For more information on this limit,
     see limits-frm-file.

11.2 Numeric Types
==================

MySQL supports all standard SQL numeric data types.  These types include
the exact numeric data types (see 'INTEGER',
'SMALLINT', 'DECIMAL', and
'NUMERIC'), as well as the approximate numeric data
types (see 'FLOAT', 'REAL',
and 'DOUBLE PRECISION').
The keyword 'INT' is a
synonym for 'INTEGER', and the keywords
'DEC' and 'FIXED' are
synonyms for 'DECIMAL'.  MySQL treats
'DOUBLE' as a synonym for 'DOUBLE PRECISION'.
(a nonstandard extension).  MySQL also
treats 'REAL' as a synonym for
'DOUBLE PRECISION'. (a nonstandard variation),
unless the 'REAL_AS_FLOAT' SQL mode is enabled.

The 'BIT' data type stores bit values and is supported
for 'MyISAM', 'MEMORY',
see 'InnoDB', and
'NDB' tables.

For information about how MySQL handles assignment of out-of-range
values to columns and overflow during expression evaluation, see
out-of-range-and-overflow.

For information about numeric type storage requirements, see
storage-requirements.

The data type used for the result of a calculation on numeric operands
depends on the types of the operands and the operations performed on
them.  For more information, see arithmetic-functions.

11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT, BIGINT
---------------------------------------------------------------------------------------

MySQL supports the SQL standard integer types 'INTEGER' (or 'INT') and
'SMALLINT'.  As an extension to the standard, MySQL also supports the
integer types 'TINYINT', 'MEDIUMINT', and 'BIGINT'.  The following table
shows the required storage and range for each integer type.

*Required Storage and Range for Integer Types Supported by MySQL*

Type    Storage Minimum Minimum Maximum Maximum
        (Bytes) Value   Value   Value   Value
                Signed  UnsignedSigned  Unsigned

'TINYINT'1      '-128'  '0'     '127'   '255'

'SMALLINT'2     '-32768''0'     '32767' '65535'

'MEDIUMINT'3    '-8388608''0'   '8388607''16777215'

'INT'   4       '-2147483648''0''2147483647''4294967295'

'BIGINT'8       '-2^63' '0'     '2^63-1''2^64-1'

11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC
---------------------------------------------------------

The 'DECIMAL' and 'NUMERIC' types store exact numeric data values.
These types are used when it is important to preserve exact precision,
for example with monetary data.  In MySQL, 'NUMERIC' is implemented as
'DECIMAL', so the following remarks about 'DECIMAL' apply equally to
'NUMERIC'.

MySQL stores 'DECIMAL' values in binary format.  See
precision-math.

In a 'DECIMAL' column declaration, the precision and scale can be (and
usually is) specified; for example:

     salary DECIMAL(5,2)

In this example, '5' is the precision and '2' is the scale.  The
precision represents the number of significant digits that are stored
for values, and the scale represents the number of digits that can be
stored following the decimal point.

Standard SQL requires that 'DECIMAL(5,2)' be able to store any value
with five digits and two decimals, so values that can be stored in the
'salary' column range from '-999.99' to '999.99'.

In standard SQL, the syntax 'DECIMAL(M)' is equivalent to
'DECIMAL(M,0)'.  Similarly, the syntax 'DECIMAL' is equivalent to
'DECIMAL(M,0)', where the implementation is permitted to decide the
value of M.  MySQL supports both of these variant forms of 'DECIMAL'
syntax.  The default value of M is 10.

If the scale is 0, 'DECIMAL' values contain no decimal point or
fractional part.

The maximum number of digits for 'DECIMAL' is 65, but the actual range
for a given 'DECIMAL' column can be constrained by the precision or
scale for a given column.  When such a column is assigned a value with
more digits following the decimal point than are permitted by the
specified scale, the value is converted to that scale.  (The precise
behavior is operating system-specific, but generally the effect is
truncation to the permissible number of digits.)

11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE
---------------------------------------------------------------

The 'FLOAT' and 'DOUBLE' types represent approximate numeric data
values.  MySQL uses four bytes for single-precision values and eight
bytes for double-precision values.

For 'FLOAT', the SQL standard permits an optional specification of the
precision (but not the range of the exponent) in bits following the
keyword 'FLOAT' in parentheses.  MySQL also supports this optional
precision specification, but the precision value is used only to
determine storage size.  A precision from 0 to 23 results in a 4-byte
single-precision 'FLOAT' column.  A precision from 24 to 53 results in
an 8-byte double-precision 'DOUBLE' column.

MySQL permits a nonstandard syntax: 'FLOAT(M,D)' or 'REAL(M,D)' or
'DOUBLE PRECISION(M,D)'.  Here, '(M,D)' means than values can be stored
with up to M digits in total, of which D digits may be after the decimal
point.  For example, a column defined as 'FLOAT(7,4)' will look like
'-999.9999' when displayed.  MySQL performs rounding when storing
values, so if you insert '999.00009' into a 'FLOAT(7,4)' column, the
approximate result is '999.0001'.

Because floating-point values are approximate and not stored as exact
values, attempts to treat them as exact in comparisons may lead to
problems.  They are also subject to platform or implementation
dependencies.  For more information, see problems-with-float

For maximum portability, code requiring storage of approximate numeric
data values should use 'FLOAT' or 'DOUBLE PRECISION' with no
specification of precision or number of digits.

11.2.4 Bit-Value Type - BIT
---------------------------

The 'BIT' data type is used to store bit values.  A type of 'BIT(M)'
enables storage of M-bit values.  M can range from 1 to 64.

To specify bit values, 'b'VALUE'' notation can be used.  VALUE is a
binary value written using zeros and ones.  For example, 'b'111'' and
'b'10000000'' represent 7 and 128, respectively.  See
bit-value-literals.

If you assign a value to a 'BIT(M)' column that is less than M bits
long, the value is padded on the left with zeros.  For example,
assigning a value of 'b'101'' to a 'BIT(6)' column is, in effect, the
same as assigning 'b'000101''.

NDB Cluster

The maximum combined size of all 'BIT' columns used in a given
'NDB' table must not exceed 4096 bits.

11.2.5 Numeric Type Attributes
------------------------------

MySQL supports an extension for optionally specifying the display width
of integer data types in parentheses following the base keyword for the
type.  For example, see 'INT(4)' specifies an
'INT' with a display width of four digits.  This
optional display width may be used by applications to display integer
values having a width less than the width specified for the column by
left-padding them with spaces.  (That is, this width is present in the
metadata returned with result sets.  Whether it is used or not is up to
the application.)

The display width does _not_ constrain the range of values that can be
stored in the column.  Nor does it prevent values wider than the column
display width from being displayed correctly.  For example, a column
specified as 'SMALLINT(3)' has the usual
'SMALLINT' range of '-32768' to '32767', and values
outside the range permitted by three digits are displayed in full using
more than three digits.

When used in conjunction with the optional (nonstandard) attribute
'ZEROFILL', the default padding of spaces is replaced with zeros.  For
example, for a column declared as 'INT(4) ZEROFILL',
a value of '5' is retrieved as '0005'.

*Note*:

The 'ZEROFILL' attribute is ignored when a column is involved in
expressions or 'UNION' queries.

If you store values larger than the display width in an integer column
that has the 'ZEROFILL' attribute, you may experience problems when
MySQL generates temporary tables for some complicated joins.  In these
cases, MySQL assumes that the data values fit within the column display
width.

All integer types can have an optional (nonstandard) attribute
'UNSIGNED'.  Unsigned type can be used to permit only nonnegative
numbers in a column or when you need a larger upper numeric range for
the column.  For example, if an 'INT' column is
'UNSIGNED', the size of the column's range is the same but its endpoints
shift from '-2147483648' and '2147483647' up to '0' and '4294967295'.

Floating-point and fixed-point types also can be 'UNSIGNED'.  As with
integer types, this attribute prevents negative values from being stored
in the column.  Unlike the integer types, the upper range of column
values remains the same.

If you specify 'ZEROFILL' for a numeric column, MySQL automatically adds
the 'UNSIGNED' attribute to the column.

Integer or floating-point data types can have the additional attribute
'AUTO_INCREMENT'.  When you insert a value of 'NULL' into an indexed
'AUTO_INCREMENT' column, the column is set to the next sequence value.
Typically this is 'VALUE+1', where VALUE is the largest value for the
column currently in the table.  ('AUTO_INCREMENT' sequences begin with
'1'.)

Storing '0' into an 'AUTO_INCREMENT' column has the same effect as
storing 'NULL', unless the 'NO_AUTO_VALUE_ON_ZERO' SQL mode is enabled.

Inserting 'NULL' to generate 'AUTO_INCREMENT' values requires that the
column be declared 'NOT NULL'.  If the column is declared 'NULL',
inserting 'NULL' stores a 'NULL'.  When you insert any other value into
an 'AUTO_INCREMENT' column, the column is set to that value and the
sequence is reset so that the next automatically generated value follows
sequentially from the inserted value.

In MySQL 5.7, negative values for 'AUTO_INCREMENT' columns are not
supported.

11.2.6 Out-of-Range and Overflow Handling
-----------------------------------------

When MySQL stores a value in a numeric column that is outside the
permissible range of the column data type, the result depends on the SQL
mode in effect at the time:

   * If strict SQL mode is enabled, MySQL rejects the out-of-range value
     with an error, and the insert fails, in accordance with the SQL
     standard.

   * If no restrictive modes are enabled, MySQL clips the value to the
     appropriate endpoint of the column data type range and stores the
     resulting value instead.

     When an out-of-range value is assigned to an integer column, MySQL
     stores the value representing the corresponding endpoint of the
     column data type range.

     When a floating-point or fixed-point column is assigned a value
     that exceeds the range implied by the specified (or default)
     precision and scale, MySQL stores the value representing the
     corresponding endpoint of that range.

Suppose that a table 't1' has this definition:

     CREATE TABLE t1 (i1 TINYINT, i2 TINYINT UNSIGNED);

With strict SQL mode enabled, an out of range error occurs:

     mysql> SET sql_mode = 'TRADITIONAL';
     mysql> INSERT INTO t1 (i1, i2) VALUES(256, 256);
     ERROR 1264 (22003): Out of range value for column 'i1' at row 1
     mysql> SELECT * FROM t1;
     Empty set (0.00 sec)

With strict SQL mode not enabled, clipping with warnings occurs:

     mysql> SET sql_mode = '';
     mysql> INSERT INTO t1 (i1, i2) VALUES(256, 256);
     mysql> SHOW WARNINGS;
     +---------+------+---------------------------------------------+
     | Level   | Code | Message                                     |
     +---------+------+---------------------------------------------+
     | Warning | 1264 | Out of range value for column 'i1' at row 1 |
     | Warning | 1264 | Out of range value for column 'i2' at row 1 |
     +---------+------+---------------------------------------------+
     mysql> SELECT * FROM t1;
     +------+------+
     | i1   | i2   |
     +------+------+
     |  127 |  255 |
     +------+------+

When strict SQL mode is not enabled, column-assignment conversions that
occur due to clipping are reported as warnings for 'ALTER TABLE',
see 'LOAD DATA INFILE', 'UPDATE',
and multiple-row 'INSERT' statements.  In strict
mode, these statements fail, and some or all the values are not inserted
or changed, depending on whether the table is a transactional table and
other factors.  For details, see sql-mode.

Overflow during numeric expression evaluation results in an error.  For
example, the largest signed 'BIGINT' value is
9223372036854775807, so the following expression produces an error:

     mysql> SELECT 9223372036854775807 + 1;
     ERROR 1690 (22003): BIGINT value is out of range in '(9223372036854775807 + 1)'

To enable the operation to succeed in this case, convert the value to
unsigned;

     mysql> SELECT CAST(9223372036854775807 AS UNSIGNED) + 1;
     +-------------------------------------------+
     | CAST(9223372036854775807 AS UNSIGNED) + 1 |
     +-------------------------------------------+
     |                       9223372036854775808 |
     +-------------------------------------------+

Whether overflow occurs depends on the range of the operands, so another
way to handle the preceding expression is to use exact-value arithmetic
because 'DECIMAL' values have a larger range
than integers:

     mysql> SELECT 9223372036854775807.0 + 1;
     +---------------------------+
     | 9223372036854775807.0 + 1 |
     +---------------------------+
     |     9223372036854775808.0 |
     +---------------------------+

Subtraction between integer values, where one is of type 'UNSIGNED',
produces an unsigned result by default.  If the result would otherwise
have been negative, an error results:

     mysql> SET sql_mode = '';
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT CAST(0 AS UNSIGNED) - 1;
     ERROR 1690 (22003): BIGINT UNSIGNED value is out of range in '(cast(0 as unsigned) - 1)'

If the 'NO_UNSIGNED_SUBTRACTION' SQL mode is enabled, the result is
negative:

     mysql> SET sql_mode = 'NO_UNSIGNED_SUBTRACTION';
     mysql> SELECT CAST(0 AS UNSIGNED) - 1;
     +-------------------------+
     | CAST(0 AS UNSIGNED) - 1 |
     +-------------------------+
     |                      -1 |
     +-------------------------+

If the result of such an operation is used to update an 'UNSIGNED'
integer column, the result is clipped to the maximum value for the
column type, or clipped to 0 if 'NO_UNSIGNED_SUBTRACTION' is enabled.
If strict SQL mode is enabled, an error occurs and the column remains
unchanged.

11.3 Date and Time Types
========================

The date and time types for representing temporal values are
'DATE', 'TIME', 'DATETIME',
'TIMESTAMP', and 'YEAR'.  Each temporal type has a
range of valid values, as well as a 'zero' value that may be used when
you specify an invalid value that MySQL cannot represent.  The
'TIMESTAMP' type has special automatic updating behavior,
described later.  For temporal type storage requirements, see
storage-requirements.

Keep in mind these general considerations when working with date and
time types:

   * MySQL retrieves values for a given date or time type in a standard
     output format, but it attempts to interpret a variety of formats
     for input values that you supply (for example, when you specify a
     value to be assigned to or compared to a date or time type).  For a
     description of the permitted formats for date and time types, see
     date-and-time-literals.  It is expected that you supply
     valid values.  Unpredictable results may occur if you use values in
     other formats.

   * Although MySQL tries to interpret values in several formats, date
     parts must always be given in year-month-day order (for example,
     ''98-09-04''), rather than in the month-day-year or day-month-year
     orders commonly used elsewhere (for example, ''09-04-98'',
     ''04-09-98'').

   * Dates containing two-digit year values are ambiguous because the
     century is unknown.  MySQL interprets two-digit year values using
     these rules:

        * Year values in the range '70-99' are converted to '1970-1999'.

        * Year values in the range '00-69' are converted to '2000-2069'.

     See also two-digit-years.

   * Conversion of values from one temporal type to another occurs
     according to the rules in date-and-time-type-conversion.

   * MySQL automatically converts a date or time value to a number if
     the value is used in a numeric context and vice versa.

   * By default, when MySQL encounters a value for a date or time type
     that is out of range or otherwise invalid for the type, it converts
     the value to the 'zero' value for that type.  The exception is that
     out-of-range 'TIME' values are clipped to the
     appropriate endpoint of the 'TIME' range.

   * By setting the SQL mode to the appropriate value, you can specify
     more exactly what kind of dates you want MySQL to support.  (See
     sql-mode.)  You can get MySQL to accept certain dates, such
     as ''2009-11-31'', by enabling the 'ALLOW_INVALID_DATES' SQL mode.
     This is useful when you want to store a 'possibly wrong' value
     which the user has specified (for example, in a web form) in the
     database for future processing.  Under this mode, MySQL verifies
     only that the month is in the range from 1 to 12 and that the day
     is in the range from 1 to 31.

   * MySQL permits you to store dates where the day or month and day are
     zero in a 'DATE' or 'DATETIME'.
     column.  This is useful for applications that need to store
     birthdates for which you may not know the exact date.  In this
     case, you simply store the date as ''2009-00-00'' or
     ''2009-01-00''.  If you store dates such as these, you should not
     expect to get correct results for functions such as 'DATE_SUB()' or
     'DATE_ADD()' that require complete dates.  To disallow zero month
     or day parts in dates, enable the 'NO_ZERO_IN_DATE' mode.

   * MySQL permits you to store a 'zero' value of ''0000-00-00'' as a
     'dummy date.' This is in some cases more convenient than using
     'NULL' values, and uses less data and index space.  To disallow
     ''0000-00-00'', enable the 'NO_ZERO_DATE' mode.

   * 'Zero' date or time values used through Connector/ODBC are
     converted automatically to 'NULL' because ODBC cannot handle such
     values.

The following table shows the format of the 'zero' value for each type.
The 'zero' values are special, but you can store or refer to them
explicitly using the values shown in the table.  You can also do this
using the values ''0'' or '0', which are easier to write.  For temporal
types that include a date part (see 'DATE',
'DATETIME', and 'TIMESTAMP'), use of these
values produces warnings if the 'NO_ZERO_DATE' SQL mode is enabled.

Data Type              'Zero' Value

See 'DATE'.

See 'TIME'.    ''00:00:00''

See 'DATETIME'.

See 'TIMESTAMP'.

See 'YEAR'.    '0000'

11.3.1 The DATE, DATETIME, and TIMESTAMP Types
----------------------------------------------

The 'DATE', 'DATETIME', and 'TIMESTAMP' types are related.  This section
describes their characteristics, how they are similar, and how they
differ.  MySQL recognizes 'DATE', 'DATETIME', and 'TIMESTAMP' values in
several formats, described in date-and-time-literals.  For the
'DATE' and 'DATETIME' range descriptions, 'supported' means that
although earlier values might work, there is no guarantee.

The 'DATE' type is used for values with a date part but no time part.
MySQL retrieves and displays 'DATE' values in ''YYYY-MM-DD'' format.
The supported range is ''1000-01-01'' to ''9999-12-31''.

The 'DATETIME' type is used for values that contain both date and time
parts.  MySQL retrieves and displays 'DATETIME' values in ''YYYY-MM-DD
HH:MM:SS'' format.  The supported range is ''1000-01-01 00:00:00'' to
''9999-12-31 23:59:59''.

The 'TIMESTAMP' data type is used for values that contain both date and
time parts.  'TIMESTAMP' has a range of ''1970-01-01 00:00:01'' UTC to
''2038-01-19 03:14:07'' UTC.

A 'DATETIME' or 'TIMESTAMP' value can include a trailing fractional
seconds part in up to microseconds (6 digits) precision.  In particular,
any fractional part in a value inserted into a 'DATETIME' or 'TIMESTAMP'
column is stored rather than discarded.  With the fractional part
included, the format for these values is ''YYYY-MM-DD
HH:MM:SS[.fraction]'', the range for 'DATETIME' values is ''1000-01-01
00:00:00.000000'' to ''9999-12-31 23:59:59.999999'', and the range for
'TIMESTAMP' values is ''1970-01-01 00:00:01.000000'' to ''2038-01-19
03:14:07.999999''.  The fractional part should always be separated from
the rest of the time by a decimal point; no other fractional seconds
delimiter is recognized.  For information about fractional seconds
support in MySQL, see fractional-seconds.

The 'TIMESTAMP' and 'DATETIME' data types offer automatic initialization
and updating to the current date and time.  For more information, see
timestamp-initialization.

MySQL converts 'TIMESTAMP' values from the current time zone to UTC for
storage, and back from UTC to the current time zone for retrieval.
(This does not occur for other types such as 'DATETIME'.)  By default,
the current time zone for each connection is the server's time.  The
time zone can be set on a per-connection basis.  As long as the time
zone setting remains constant, you get back the same value you store.
If you store a 'TIMESTAMP' value, and then change the time zone and
retrieve the value, the retrieved value is different from the value you
stored.  This occurs because the same time zone was not used for
conversion in both directions.  The current time zone is available as
the value of the 'time_zone' system variable.  For more information, see
time-zone-support.

Invalid 'DATE', 'DATETIME', or 'TIMESTAMP' values are converted to the
'zero' value of the appropriate type (''0000-00-00'' or ''0000-00-00
00:00:00'').

Be aware of certain properties of date value interpretation in MySQL:

   * MySQL permits a 'relaxed' format for values specified as strings,
     in which any punctuation character may be used as the delimiter
     between date parts or time parts.  In some cases, this syntax can
     be deceiving.  For example, a value such as ''10:11:12'' might look
     like a time value because of the ':', but is interpreted as the
     year ''2010-11-12'' if used in a date context.  The value
     ''10:45:15'' is converted to ''0000-00-00'' because ''45'' is not a
     valid month.

     The only delimiter recognized between a date and time part and a
     fractional seconds part is the decimal point.

   * The server requires that month and day values be valid, and not
     merely in the range 1 to 12 and 1 to 31, respectively.  With strict
     mode disabled, invalid dates such as ''2004-04-31'' are converted
     to ''0000-00-00'' and a warning is generated.  With strict mode
     enabled, invalid dates generate an error.  To permit such dates,
     enable 'ALLOW_INVALID_DATES'.  See sql-mode, for more
     information.

   * MySQL does not accept 'TIMESTAMP' values that include a zero in the
     day or month column or values that are not a valid date.  The sole
     exception to this rule is the special 'zero' value ''0000-00-00
     00:00:00''.

   * Dates containing two-digit year values are ambiguous because the
     century is unknown.  MySQL interprets two-digit year values using
     these rules:

        * Year values in the range '00-69' are converted to '2000-2069'.

        * Year values in the range '70-99' are converted to '1970-1999'.

     See also two-digit-years.

*Note*:

The MySQL server can be run with the 'MAXDB' SQL mode enabled.  In this
case, 'TIMESTAMP' is identical with 'DATETIME'.  If this mode is enabled
at the time that a table is created, 'TIMESTAMP' columns are created as
'DATETIME' columns.  As a result, such columns use 'DATETIME' display
format, have the same range of values, and there is no automatic
initialization or updating to the current date and time.  See
sql-mode.

*Note*:

As of MySQL 5.7.22, 'MAXDB' is deprecated.  It will be removed in a
future version of MySQL.

11.3.2 The TIME Type
--------------------

MySQL retrieves and displays 'TIME' values in ''HH:MM:SS'' format (or
''HHH:MM:SS'' format for large hours values).  'TIME' values may range
from ''-838:59:59'' to ''838:59:59''.  The hours part may be so large
because the 'TIME' type can be used not only to represent a time of day
(which must be less than 24 hours), but also elapsed time or a time
interval between two events (which may be much greater than 24 hours, or
even negative).

MySQL recognizes 'TIME' values in several formats, some of which can
include a trailing fractional seconds part in up to microseconds (6
digits) precision.  See date-and-time-literals.  For information
about fractional seconds support in MySQL, see
fractional-seconds.  In particular, any fractional part in a value
inserted into a 'TIME' column is stored rather than discarded.  With the
fractional part included, the range for 'TIME' values is
''-838:59:59.000000'' to ''838:59:59.000000''.

Be careful about assigning abbreviated values to a 'TIME' column.  MySQL
interprets abbreviated 'TIME' values with colons as time of the day.
That is, ''11:12'' means ''11:12:00'', not ''00:11:12''.  MySQL
interprets abbreviated values without colons using the assumption that
the two rightmost digits represent seconds (that is, as elapsed time
rather than as time of day).  For example, you might think of ''1112''
and '1112' as meaning ''11:12:00'' (12 minutes after 11 o'clock), but
MySQL interprets them as ''00:11:12'' (11 minutes, 12 seconds).
Similarly, ''12'' and '12' are interpreted as ''00:00:12''.

The only delimiter recognized between a time part and a fractional
seconds part is the decimal point.

By default, values that lie outside the 'TIME' range but are otherwise
valid are clipped to the closest endpoint of the range.  For example,
''-850:00:00'' and ''850:00:00'' are converted to ''-838:59:59'' and
''838:59:59''.  Invalid 'TIME' values are converted to ''00:00:00''.
Note that because ''00:00:00'' is itself a valid 'TIME' value, there is
no way to tell, from a value of ''00:00:00'' stored in a table, whether
the original value was specified as ''00:00:00'' or whether it was
invalid.

For more restrictive treatment of invalid 'TIME' values, enable strict
SQL mode to cause errors to occur.  See sql-mode.

11.3.3 The YEAR Type
--------------------

The 'YEAR' type is a 1-byte type used to represent year values.  It can
be declared as 'YEAR' or 'YEAR(4)' and has a display width of four
characters.

*Note*:

The 'YEAR(2)' data type is deprecated and support for it is removed in
MySQL 5.7.5.  To convert 'YEAR(2)' columns to 'YEAR(4)', see
migrating-to-year4.

MySQL displays 'YEAR' values in 'YYYY' format, with a range of '1901' to
'2155', or '0000'.

You can specify input 'YEAR' values in a variety of formats:

   * As a 4-digit number in the range '1901' to '2155'.

   * As a 4-digit string in the range ''1901'' to ''2155''.

   * As a 1- or 2-digit number in the range '1' to '99'.  MySQL converts
     values in the ranges '1' to '69' and '70' to '99' to 'YEAR' values
     in the ranges '2001' to '2069' and '1970' to '1999'.

   * As a 1- or 2-digit string in the range ''0'' to ''99''.  MySQL
     converts values in the ranges ''0'' to ''69'' and ''70'' to ''99''
     to 'YEAR' values in the ranges '2000' to '2069' and '1970' to
     '1999'.

   * The result of inserting a numeric '0' has a display value of '0000'
     and an internal value of '0000'.  To insert zero and have it be
     interpreted as '2000', specify it as a string ''0'' or ''00''.

   * As the result of a function that returns a value that is acceptable
     in a 'YEAR' context, such as 'NOW()'.

MySQL converts invalid 'YEAR' values to '0000'.

See also two-digit-years.

11.3.4 YEAR(2) Limitations and Migrating to YEAR(4)
---------------------------------------------------

This section describes problems that can occur when using
'YEAR(2)' and provides information about converting existing
'YEAR(2)' columns to 'YEAR(4)'.

Although the internal range of values for 'YEAR(4)' and the
deprecated 'YEAR(2)' type is the same ('1901' to '2155',
and '0000'), the display width for 'YEAR(2)' makes that
type inherently ambiguous because displayed values indicate only the
last two digits of the internal values and omit the century digits.  The
result can be a loss of information under certain circumstances.  For
this reason, before MySQL 5.7.5, avoid using 'YEAR(2)' in
your applications and use 'YEAR(4)' wherever you need a
'YEAR' data type.  As of MySQL 5.7.5, support for
'YEAR(2)' is removed and existing 'YEAR(2)' columns
must be converted to 'YEAR(4)' to become usable again.

*YEAR(2) Limitations*

Issues with the 'YEAR(2)' data type include ambiguity of
displayed values, and possible loss of information when values are
dumped and reloaded or converted to strings.

   * Displayed 'YEAR(2)' values can be ambiguous.  It is
     possible for up to three 'YEAR(2)' values that have
     different internal values to have the same displayed value, as the
     following example demonstrates:

          mysql> CREATE TABLE t (y2 YEAR(2), y4 YEAR(4));
          Query OK, 0 rows affected (0.01 sec)

          mysql> INSERT INTO t (y2) VALUES(1912),(2012),(2112);
          Query OK, 3 rows affected (0.00 sec)
          Records: 3  Duplicates: 0  Warnings: 0

          mysql> UPDATE t SET y4 = y2;
          Query OK, 3 rows affected (0.00 sec)
          Rows matched: 3  Changed: 3  Warnings: 0

          mysql> SELECT * FROM t;
          +------+------+
          | y2   | y4   |
          +------+------+
          |   12 | 1912 |
          |   12 | 2012 |
          |   12 | 2112 |
          +------+------+
          3 rows in set (0.00 sec)

   * If you use 'mysqldump' to dump the table created
     in the preceding item, the dump file represents all 'y2' values
     using the same 2-digit representation ('12').  If you reload the
     table from the dump file, all resulting rows have internal value
     '2012' and display value '12', thus losing the distinctions among
     them.

   * Conversion of a 'YEAR(2)' or 'YEAR(4)'.
     data value to string form uses the display width of the
     'YEAR' type.  Suppose that 'YEAR(2)' and
     'YEAR(4)' columns both contain the value '1970'.  Assigning
     each column to a string results in a value of ''70'' or ''1970'',
     respectively.  That is, loss of information occurs for conversion
     from 'YEAR(2)' to string.

   * Values outside the range from '1970' to '2069' are stored
     incorrectly when inserted into a 'YEAR(2)' column in a
     'CSV' table.  For example, inserting
     '2111' results in a display value of '11' but an internal value of
     '2011'.

To avoid these problems, use 'YEAR(4)' rather than
'YEAR(2)'.  Suggestions regarding migration strategies appear
later in this section.

*Reduced/Removed YEAR(2) Support in MySQL 5.7*

Before MySQL 5.7.5, support for 'YEAR(2)' is diminished.
As of MySQL 5.7.5, support for 'YEAR(2)' is removed.

   * 'YEAR(2)' column definitions for new tables produce
     warnings or errors:

        * Before MySQL 5.7.5, see 'YEAR(2)' column definitions
          for new tables are converted (with an
          'ER_INVALID_YEAR_COLUMN_LENGTH' warning) to 'YEAR(4)'.:

               mysql> CREATE TABLE t1 (y YEAR(2));
               Query OK, 0 rows affected, 1 warning (0.04 sec)

               mysql> SHOW WARNINGS\G
               *************************** 1. row ***************************
                 Level: Warning
                  Code: 1818
               Message: YEAR(2) column type is deprecated. Creating YEAR(4) column instead.
               1 row in set (0.00 sec)

               mysql> SHOW CREATE TABLE t1\G
               *************************** 1. row ***************************
                      Table: t1
               Create Table: CREATE TABLE `t1` (
                 `y` year(4) DEFAULT NULL
               ) ENGINE=InnoDB DEFAULT CHARSET=latin1
               1 row in set (0.00 sec)

        * As of MySQL 5.7.5, see 'YEAR(2)' column definitions
          for new tables produce an 'ER_INVALID_YEAR_COLUMN_LENGTH'
          error:

               mysql> CREATE TABLE t1 (y YEAR(2));
               ERROR 1818 (HY000): Supports only YEAR or YEAR(4) column.

   * 'YEAR(2)' column in existing tables remain as
     'YEAR(2)'.:

        * Before MySQL 5.7.5, see 'YEAR(2)' is processed in
          queries as in older versions of MySQL.

        * As of MySQL 5.7.5, see 'YEAR(2)' columns in queries
          produce warnings or errors.

   * Several programs or statements convert 'YEAR(2)' to
     'YEAR(4)' automatically:

        * 'ALTER TABLE' statements that result in a
          table rebuild.

        * 'REPAIR TABLE'. (which 'CHECK TABLE'
          recommends you use if it finds that a
          table contains 'YEAR(2)' columns).

        * 'mysql_upgrade'. (which uses
          'REPAIR TABLE').

        * Dumping with 'mysqldump' and reloading the
          dump file.  Unlike the conversions performed by the preceding
          three items, a dump and reload has the potential to change
          values.

     A MySQL upgrade usually involves at least one of the last two
     items.  However, with respect to 'YEAR(2)',
     'mysql_upgrade' is preferable.  You should avoid
     using 'mysqldump' because, as noted, that can
     change values.

*Migrating from YEAR(2) to YEAR(4)*

To convert 'YEAR(2)' columns to 'YEAR(4)', you
can do so manually at any time without upgrading.  Alternatively, you
can upgrade to a version of MySQL with reduced or removed support for
'YEAR(2)'. (MySQL 5.6.6 or later), then have MySQL convert
'YEAR(2)' columns automatically.  In the latter case, avoid
upgrading by dumping and reloading your data because that can change
data values.  In addition, if you use replication, there are upgrade
considerations you must take into account.

To convert 'YEAR(2)' columns to 'YEAR(4)'.
manually, use 'ALTER TABLE' or 'REPAIR TABLE'.
Suppose that a table 't1' has this definition:

     CREATE TABLE t1 (ycol YEAR(2) NOT NULL DEFAULT '70');

Modify the column using 'ALTER TABLE' as follows:

     ALTER TABLE t1 FORCE;

The 'ALTER TABLE' statement converts the table
without changing 'YEAR(2)' values.  If the server is a
replication master, the 'ALTER TABLE' statement
replicates to slaves and makes the corresponding table change on each
one.

Another migration method is to perform a binary upgrade: Install MySQL
without dumping and reloading your data.  Then run
'mysql_upgrade', which uses 'REPAIR TABLE'
to convert 'YEAR(2)' columns to
'YEAR(4)' without changing data values.  If the server is a
replication master, the 'REPAIR TABLE' statements
replicate to slaves and make the corresponding table changes on each
one, unless you invoke 'mysql_upgrade' with the
'--skip-write-binlog' option.

Upgrades to replication servers usually involve upgrading slaves to a
newer version of MySQL, then upgrading the master.  For example, if a
master and slave both run MySQL 5.5, a typical upgrade sequence involves
upgrading the slave to 5.6, then upgrading the master to 5.6.  With
regard to the different treatment of 'YEAR(2)' as of MySQL
5.6.6, that upgrade sequence results in a problem: Suppose that the
slave has been upgraded but not yet the master.  Then creating a table
containing a 'YEAR(2)' column on the master results in a
table containing a 'YEAR(4)' column on the slave.
Consequently, these operations will have a different result on the
master and slave, if you use statement-based replication:

   * Inserting numeric '0'.  The resulting value has an internal value
     of '2000' on the master but '0000' on the slave.

   * Converting 'YEAR(2)' to string.  This operation uses
     the display value of 'YEAR(2)' on the master but
     'YEAR(4)' on the slave.

To avoid such problems, modify all 'YEAR(2)' columns on the
master to 'YEAR(4)' before upgrading.  (Use 'ALTER TABLE',
as described previously.)  Then you can upgrade
normally (slave first, then master) without introducing any
'YEAR(2)' to 'YEAR(4)' differences between the
master and slave.

One migration method should be avoided: Do not dump your data with
'mysqldump' and reload the dump file after upgrading.  This
has the potential to change 'YEAR(2)' values, as described
previously.

A migration from 'YEAR(2)' to 'YEAR(4)' should
also involve examining application code for the possibility of changed
behavior under conditions such as these:

   * Code that expects selecting a 'YEAR' column to produce
     exactly two digits.

   * Code that does not account for different handling for inserts of
     numeric '0': Inserting '0' into 'YEAR(2)' or
     'YEAR(4)' results in an internal value of '2000' or '0000',
     respectively.

11.3.5 Automatic Initialization and Updating for TIMESTAMP and DATETIME
-----------------------------------------------------------------------

'TIMESTAMP' and 'DATETIME' columns can
be automatically initializated and updated to the current date and time
(that is, the current timestamp).

For any 'TIMESTAMP' or 'DATETIME'.
column in a table, you can assign the current timestamp as the default
value, the auto-update value, or both:

   * An auto-initialized column is set to the current timestamp for
     inserted rows that specify no value for the column.

   * An auto-updated column is automatically updated to the current
     timestamp when the value of any other column in the row is changed
     from its current value.  An auto-updated column remains unchanged
     if all other columns are set to their current values.  To prevent
     an auto-updated column from updating when other columns change,
     explicitly set it to its current value.  To update an auto-updated
     column even when other columns do not change, explicitly set it to
     the value it should have (for example, set it to
     'CURRENT_TIMESTAMP').

In addition, if the 'explicit_defaults_for_timestamp' system variable is
disabled, you can initialize or update any 'TIMESTAMP'.
(but not 'DATETIME') column to the current date and time by assigning it
a 'NULL' value, unless it has been defined with the 'NULL' attribute to
permit 'NULL' values.

To specify automatic properties, use the 'DEFAULT CURRENT_TIMESTAMP' and
'ON UPDATE CURRENT_TIMESTAMP' clauses in column definitions.  The order
of the clauses does not matter.  If both are present in a column
definition, either can occur first.  Any of the synonyms for
'CURRENT_TIMESTAMP' have the same meaning as 'CURRENT_TIMESTAMP'.  These
are 'CURRENT_TIMESTAMP()', 'NOW()', 'LOCALTIME', 'LOCALTIME()',
'LOCALTIMESTAMP', and 'LOCALTIMESTAMP()'.

Use of 'DEFAULT CURRENT_TIMESTAMP' and 'ON UPDATE CURRENT_TIMESTAMP' is
specific to 'TIMESTAMP' and 'DATETIME'.
The 'DEFAULT' clause also can be used to specify a constant
(nonautomatic) default value; for example, 'DEFAULT 0' or 'DEFAULT
'2000-01-01 00:00:00''.

*Note*:

The following examples use 'DEFAULT 0', a default that can produce
warnings or errors depending on whether strict SQL mode or the
'NO_ZERO_DATE' SQL mode is enabled.  Be aware that the 'TRADITIONAL' SQL
mode includes strict mode and 'NO_ZERO_DATE'.  See sql-mode.

'TIMESTAMP' or 'DATETIME' column
definitions can specify the current timestamp for both the default and
auto-update values, for one but not the other, or for neither.
Different columns can have different combinations of automatic
properties.  The following rules describe the possibilities:

   * With both 'DEFAULT CURRENT_TIMESTAMP' and 'ON UPDATE
     CURRENT_TIMESTAMP', the column has the current timestamp for its
     default value and is automatically updated to the current
     timestamp.

          CREATE TABLE t1 (
            ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
            dt DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
          );

   * With a 'DEFAULT' clause but no 'ON UPDATE CURRENT_TIMESTAMP'
     clause, the column has the given default value and is not
     automatically updated to the current timestamp.

     The default depends on whether the 'DEFAULT' clause specifies
     'CURRENT_TIMESTAMP' or a constant value.  With 'CURRENT_TIMESTAMP',
     the default is the current timestamp.

          CREATE TABLE t1 (
            ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            dt DATETIME DEFAULT CURRENT_TIMESTAMP
          );

     With a constant, the default is the given value.  In this case, the
     column has no automatic properties at all.

          CREATE TABLE t1 (
            ts TIMESTAMP DEFAULT 0,
            dt DATETIME DEFAULT 0
          );

   * With an 'ON UPDATE CURRENT_TIMESTAMP' clause and a constant
     'DEFAULT' clause, the column is automatically updated to the
     current timestamp and has the given constant default value.

          CREATE TABLE t1 (
            ts TIMESTAMP DEFAULT 0 ON UPDATE CURRENT_TIMESTAMP,
            dt DATETIME DEFAULT 0 ON UPDATE CURRENT_TIMESTAMP
          );

   * With an 'ON UPDATE CURRENT_TIMESTAMP' clause but no 'DEFAULT'
     clause, the column is automatically updated to the current
     timestamp but does not have the current timestamp for its default
     value.

     The default in this case is type dependent.  'TIMESTAMP'
     has a default of 0 unless defined with the 'NULL'
     attribute, in which case the default is 'NULL'.

          CREATE TABLE t1 (
            ts1 TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,     -- default 0
            ts2 TIMESTAMP NULL ON UPDATE CURRENT_TIMESTAMP -- default NULL
          );

     'DATETIME' has a default of 'NULL' unless defined
     with the 'NOT NULL' attribute, in which case the default is 0.

          CREATE TABLE t1 (
            dt1 DATETIME ON UPDATE CURRENT_TIMESTAMP,         -- default NULL
            dt2 DATETIME NOT NULL ON UPDATE CURRENT_TIMESTAMP -- default 0
          );

'TIMESTAMP' and 'DATETIME' columns
have no automatic properties unless they are specified explicitly, with
this exception: If the 'explicit_defaults_for_timestamp' system variable
is disabled, the _first_ 'TIMESTAMP' column has both
'DEFAULT CURRENT_TIMESTAMP' and 'ON UPDATE CURRENT_TIMESTAMP' if neither
is specified explicitly.  To suppress automatic properties for the first
'TIMESTAMP' column, use one of these strategies:

   * Enable the 'explicit_defaults_for_timestamp' system variable.  In
     this case, the 'DEFAULT CURRENT_TIMESTAMP' and 'ON UPDATE
     CURRENT_TIMESTAMP' clauses that specify automatic initialization
     and updating are available, but are not assigned to any
     'TIMESTAMP' column unless explicitly included in the
     column definition.

   * Alternatively, if 'explicit_defaults_for_timestamp' is disabled, do
     either of the following:

        * Define the column with a 'DEFAULT' clause that specifies a
          constant default value.

        * Specify the 'NULL' attribute.  This also causes the column to
          permit 'NULL' values, which means that you cannot assign the
          current timestamp by setting the column to 'NULL'.  Assigning
          'NULL' sets the column to 'NULL', not the current timestamp.
          To assign the current timestamp, set the column to
          'CURRENT_TIMESTAMP' or a synonym such as 'NOW()'.

Consider these table definitions:

     CREATE TABLE t1 (
       ts1 TIMESTAMP DEFAULT 0,
       ts2 TIMESTAMP DEFAULT CURRENT_TIMESTAMP
                     ON UPDATE CURRENT_TIMESTAMP);
     CREATE TABLE t2 (
       ts1 TIMESTAMP NULL,
       ts2 TIMESTAMP DEFAULT CURRENT_TIMESTAMP
                     ON UPDATE CURRENT_TIMESTAMP);
     CREATE TABLE t3 (
       ts1 TIMESTAMP NULL DEFAULT 0,
       ts2 TIMESTAMP DEFAULT CURRENT_TIMESTAMP
                     ON UPDATE CURRENT_TIMESTAMP);

The tables have these properties:

   * In each table definition, the first 'TIMESTAMP'.
     column has no automatic initialization or updating.

   * The tables differ in how the 'ts1' column handles 'NULL' values.
     For 't1', 'ts1' is 'NOT NULL' and assigning it a value of 'NULL'
     sets it to the current timestamp.  For 't2' and 't3', 'ts1' permits
     'NULL' and assigning it a value of 'NULL' sets it to 'NULL'.

   * 't2' and 't3' differ in the default value for 'ts1'.  For 't2',
     'ts1' is defined to permit 'NULL', so the default is also 'NULL' in
     the absence of an explicit 'DEFAULT' clause.  For 't3', 'ts1'
     permits 'NULL' but has an explicit default of 0.

If a 'TIMESTAMP' or 'DATETIME' column
definition includes an explicit fractional seconds precision value
anywhere, the same value must be used throughout the column definition.
This is permitted:

     CREATE TABLE t1 (
       ts TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6)
     );

This is not permitted:

     CREATE TABLE t1 (
       ts TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP(3)
     );

*TIMESTAMP Initialization and the NULL Attribute*

If the 'explicit_defaults_for_timestamp' system variable is disabled,
see 'TIMESTAMP' columns by default are 'NOT NULL', cannot
contain 'NULL' values, and assigning 'NULL' assigns the current
timestamp.  To permit a 'TIMESTAMP' column to contain
'NULL', explicitly declare it with the 'NULL' attribute.  In this case,
the default value also becomes 'NULL' unless overridden with a 'DEFAULT'
clause that specifies a different default value.  'DEFAULT NULL' can be
used to explicitly specify 'NULL' as the default value.  (For a
'TIMESTAMP' column not declared with the 'NULL' attribute,
'DEFAULT NULL' is invalid.)  If a 'TIMESTAMP' column
permits 'NULL' values, assigning 'NULL' sets it to 'NULL', not to the
current timestamp.

The following table contains several 'TIMESTAMP'.
columns that permit 'NULL' values:

     CREATE TABLE t
     (
       ts1 TIMESTAMP NULL DEFAULT NULL,
       ts2 TIMESTAMP NULL DEFAULT 0,
       ts3 TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP
     );

A 'TIMESTAMP' column that permits 'NULL' values does
_not_ take on the current timestamp at insert time except under one of
the following conditions:

   * Its default value is defined as 'CURRENT_TIMESTAMP' and no value is
     specified for the column

   * 'CURRENT_TIMESTAMP' or any of its synonyms such as 'NOW()' is
     explicitly inserted into the column

In other words, a 'TIMESTAMP' column defined to permit
'NULL' values auto-initializes only if its definition includes 'DEFAULT
CURRENT_TIMESTAMP':

     CREATE TABLE t (ts TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP);

If the 'TIMESTAMP' column permits 'NULL' values but its
definition does not include 'DEFAULT CURRENT_TIMESTAMP', you must
explicitly insert a value corresponding to the current date and time.
Suppose that tables 't1' and 't2' have these definitions:

     CREATE TABLE t1 (ts TIMESTAMP NULL DEFAULT '0000-00-00 00:00:00');
     CREATE TABLE t2 (ts TIMESTAMP NULL DEFAULT NULL);

To set the 'TIMESTAMP' column in either table to the
current timestamp at insert time, explicitly assign it that value.  For
example:

     INSERT INTO t2 VALUES (CURRENT_TIMESTAMP);
     INSERT INTO t1 VALUES (NOW());

If the 'explicit_defaults_for_timestamp' system variable is enabled,
see 'TIMESTAMP' columns permit 'NULL' values only if
declared with the 'NULL' attribute.  Also, see 'TIMESTAMP'.
columns do not permit assigning 'NULL' to assign the current timestamp,
whether declared with the 'NULL' or 'NOT NULL' attribute.  To assign the
current timestamp, set the column to 'CURRENT_TIMESTAMP' or a synonym
such as 'NOW()'.

11.3.6 Fractional Seconds in Time Values
----------------------------------------

MySQL 5.7 has fractional seconds support for 'TIME',
'DATETIME', and 'TIMESTAMP' values, with up
to microseconds (6 digits) precision:

   * To define a column that includes a fractional seconds part, use the
     syntax 'TYPE_NAME(FSP)', where TYPE_NAME is 'TIME',
     'DATETIME', or 'TIMESTAMP', and FSP
     is the fractional seconds precision.  For example:

          CREATE TABLE t1 (t TIME(3), dt DATETIME(6));

     The FSP value, if given, must be in the range 0 to 6.  A value of 0
     signifies that there is no fractional part.  If omitted, the
     default precision is 0.  (This differs from the standard SQL
     default of 6, for compatibility with previous MySQL versions.)

   * Inserting a 'TIME', 'DATE', or
     'TIMESTAMP' value with a fractional seconds part into a
     column of the same type but having fewer fractional digits results
     in rounding, as shown in this example:

          mysql> CREATE TABLE fractest( c1 TIME(2), c2 DATETIME(2), c3 TIMESTAMP(2) );
          Query OK, 0 rows affected (0.33 sec)

          mysql> INSERT INTO fractest VALUES
               > ('17:51:04.777', '2014-09-08 17:51:04.777', '2014-09-08 17:51:04.777');
          Query OK, 1 row affected (0.03 sec)

          mysql> SELECT * FROM fractest;
          +-------------+------------------------+------------------------+
          | c1          | c2                     | c3                     |
          +-------------+------------------------+------------------------+
          | 17:51:04.78 | 2014-09-08 17:51:04.78 | 2014-09-08 17:51:04.78 |
          +-------------+------------------------+------------------------+
          1 row in set (0.00 sec)

     No warning or error is given when such rounding occurs.  This
     behavior follows the SQL standard, and is not affected by the
     server's 'sql_mode' setting.

   * Functions that take temporal arguments accept values with
     fractional seconds.  Return values from temporal functions include
     fractional seconds as appropriate.  For example, 'NOW()' with no
     argument returns the current date and time with no fractional part,
     but takes an optional argument from 0 to 6 to specify that the
     return value includes a fractional seconds part of that many
     digits.

   * Syntax for temporal literals produces temporal values: 'DATE
     'STR'', 'TIME 'STR'', and 'TIMESTAMP 'STR'', and the ODBC-syntax
     equivalents.  The resulting value includes a trailing fractional
     seconds part if specified.  Previously, the temporal type keyword
     was ignored and these constructs produced the string value.  See
     date-and-time-standard-sql-literals

11.3.7 Conversion Between Date and Time Types
---------------------------------------------

To some extent, you can convert a value from one temporal type to
another.  However, there may be some alteration of the value or loss of
information.  In all cases, conversion between temporal types is subject
to the range of valid values for the resulting type.  For example,
although 'DATE', 'DATETIME', and
'TIMESTAMP' values all can be specified using the same set of
formats, the types do not all have the same range of values.
'TIMESTAMP' values cannot be earlier than '1970' UTC or later
than ''2038-01-19 03:14:07'' UTC. This means that a date such as
''1968-01-01'', while valid as a 'DATE' or
'DATETIME' value, is not valid as a 'TIMESTAMP'
value and is converted to '0'.

Conversion of 'DATE' values:

   * Conversion to a 'DATETIME' or 'TIMESTAMP'
     value adds a time part of ''00:00:00'' because the
     'DATE' value contains no time information.

   * Conversion to a 'TIME' value is not useful; the result
     is ''00:00:00''.

Conversion of 'DATETIME' and 'TIMESTAMP'
values:

   * Conversion to a 'DATE' value takes fractional
     seconds into account and rounds the time part.  For example,
     ''1999-12-31 23:59:59.499'' becomes ''1999-12-31'', whereas
     ''1999-12-31 23:59:59.500'' becomes ''2000-01-01''.

   * Conversion to a 'TIME' value discards the date part
     because the 'TIME' type contains no date information.

For conversion of 'TIME' values to other temporal types,
the value of 'CURRENT_DATE()' is used for the date part.  The
'TIME' is interpreted as elapsed time (not time of day) and added
to the date.  This means that the date part of the result differs from
the current date if the time value is outside the range from
''00:00:00'' to ''23:59:59''.

Suppose that the current date is ''2012-01-01''.  See 'TIME'.
values of ''12:00:00'', ''24:00:00'', and ''-12:00:00'', when converted
to 'DATETIME' or 'TIMESTAMP' values,
result in ''2012-01-01 12:00:00'', ''2012-01-02 00:00:00'', and
''2011-12-31 12:00:00'', respectively.

Conversion of 'TIME' to 'DATE' is similar
but discards the time part from the result: ''2012-01-01'',
''2012-01-02'', and ''2011-12-31'', respectively.

Explicit conversion can be used to override implicit conversion.  For
example, in comparison of 'DATE' and 'DATETIME'
values, the 'DATE' value is coerced to the
'DATETIME' type by adding a time part of ''00:00:00''.
To perform the comparison by ignoring the time part of the
'DATETIME' value instead, use the 'CAST()' function in the
following way:

     DATE_COL = CAST(DATETIME_COL AS DATE)

Conversion of 'TIME' and 'DATETIME' values
to numeric form (for example, by adding '+0') depends on whether the
value contains a fractional seconds part.  'TIME(N)' or
'DATETIME(N)' is converted to integer when N is 0 (or
omitted) and to a 'DECIMAL' value with N decimal digits when N is
greater than 0:

     mysql> SELECT CURTIME(), CURTIME()+0, CURTIME(3)+0;
     +-----------+-------------+--------------+
     | CURTIME() | CURTIME()+0 | CURTIME(3)+0 |
     +-----------+-------------+--------------+
     | 09:28:00  |       92800 |    92800.887 |
     +-----------+-------------+--------------+
     mysql> SELECT NOW(), NOW()+0, NOW(3)+0;
     +---------------------+----------------+--------------------+
     | NOW()               | NOW()+0        | NOW(3)+0           |
     +---------------------+----------------+--------------------+
     | 2012-08-15 09:28:00 | 20120815092800 | 20120815092800.889 |
     +---------------------+----------------+--------------------+

11.3.8 Two-Digit Years in Dates
-------------------------------

Date values with two-digit years are ambiguous because the century is
unknown.  Such values must be interpreted into four-digit form because
MySQL stores years internally using four digits.

For 'DATETIME', 'DATE', and
'TIMESTAMP' types, MySQL interprets dates specified with
ambiguous year values using these rules:

   * Year values in the range '00-69' are converted to '2000-2069'.

   * Year values in the range '70-99' are converted to '1970-1999'.

For 'YEAR', the rules are the same, with this exception: A numeric '00'
inserted into 'YEAR(4)' results in '0000' rather than '2000'.  To
specify zero for 'YEAR(4)' and have it be interpreted as '2000', specify
it as a string ''0'' or ''00''.

Remember that these rules are only heuristics that provide reasonable
guesses as to what your data values mean.  If the rules used by MySQL do
not produce the values you require, you must provide unambiguous input
containing four-digit year values.

'ORDER BY' properly sorts 'YEAR' values that have two-digit
years.

Some functions like 'MIN()' and 'MAX()' convert a 'YEAR' to
a number.  This means that a value with a two-digit year does not work
properly with these functions.  The fix in this case is to convert the
'YEAR' to four-digit year format.

11.4 String Types
=================

The string types are 'CHAR', 'VARCHAR',
'BINARY', 'VARBINARY',
'BLOB', 'TEXT', 'ENUM', and 'SET'.
This section describes how these types work and how to use them in
your queries.  For string type storage requirements, see
storage-requirements.

11.4.1 The CHAR and VARCHAR Types
---------------------------------

The 'CHAR' and 'VARCHAR' types are similar, but differ in the way they
are stored and retrieved.  They also differ in maximum length and in
whether trailing spaces are retained.

The 'CHAR' and 'VARCHAR' types are declared with a length that indicates
the maximum number of characters you want to store.  For example,
'CHAR(30)' can hold up to 30 characters.

The length of a 'CHAR' column is fixed to the length that you declare
when you create the table.  The length can be any value from 0 to 255.
When 'CHAR' values are stored, they are right-padded with spaces to the
specified length.  When 'CHAR' values are retrieved, trailing spaces are
removed unless the 'PAD_CHAR_TO_FULL_LENGTH' SQL mode is enabled.

Values in 'VARCHAR' columns are variable-length strings.  The length can
be specified as a value from 0 to 65,535.  The effective maximum length
of a 'VARCHAR' is subject to the maximum row size (65,535 bytes, which
is shared among all columns) and the character set used.  See
column-count-limit.

In contrast to 'CHAR', 'VARCHAR' values are stored as a 1-byte or 2-byte
length prefix plus data.  The length prefix indicates the number of
bytes in the value.  A column uses one length byte if values require no
more than 255 bytes, two length bytes if values may require more than
255 bytes.

If strict SQL mode is not enabled and you assign a value to a 'CHAR' or
'VARCHAR' column that exceeds the column's maximum length, the value is
truncated to fit and a warning is generated.  For truncation of nonspace
characters, you can cause an error to occur (rather than a warning) and
suppress insertion of the value by using strict SQL mode.  See
sql-mode.

For 'VARCHAR' columns, trailing spaces in excess of the column length
are truncated prior to insertion and a warning is generated, regardless
of the SQL mode in use.  For 'CHAR' columns, truncation of excess
trailing spaces from inserted values is performed silently regardless of
the SQL mode.

'VARCHAR' values are not padded when they are stored.  Trailing spaces
are retained when values are stored and retrieved, in conformance with
standard SQL.

The following table illustrates the differences between 'CHAR' and
'VARCHAR' by showing the result of storing various string values into
'CHAR(4)' and 'VARCHAR(4)' columns (assuming that the column uses a
single-byte character set such as 'latin1').

Value       'CHAR(4)'   Storage        'VARCHAR(4)'Storage
                        Required                   Required

''''        ''    ''    4 bytes        ''''        1 byte

''ab''      ''ab  ''    4 bytes        ''ab''      3 bytes

''abcd''    ''abcd''    4 bytes        ''abcd''    5 bytes

''abcdefgh''''abcd''    4 bytes        ''abcd''    5 bytes

The values shown as stored in the last row of the table apply _only when
not using strict mode_; if MySQL is running in strict mode, values that
exceed the column length are _not stored_, and an error results.

'InnoDB' encodes fixed-length fields greater than or equal to 768 bytes
in length as variable-length fields, which can be stored off-page.  For
example, a 'CHAR(255)' column can exceed 768 bytes if the maximum byte
length of the character set is greater than 3, as it is with 'utf8mb4'.

If a given value is stored into the 'CHAR(4)' and 'VARCHAR(4)' columns,
the values retrieved from the columns are not always the same because
trailing spaces are removed from 'CHAR' columns upon retrieval.  The
following example illustrates this difference:

     mysql> CREATE TABLE vc (v VARCHAR(4), c CHAR(4));
     Query OK, 0 rows affected (0.01 sec)

     mysql> INSERT INTO vc VALUES ('ab  ', 'ab  ');
     Query OK, 1 row affected (0.00 sec)

     mysql> SELECT CONCAT('(', v, ')'), CONCAT('(', c, ')') FROM vc;
     +---------------------+---------------------+
     | CONCAT('(', v, ')') | CONCAT('(', c, ')') |
     +---------------------+---------------------+
     | (ab  )              | (ab)                |
     +---------------------+---------------------+
     1 row in set (0.06 sec)

Values in 'CHAR' and 'VARCHAR' columns are sorted and compared according
to the character set collation assigned to the column.

All MySQL collations are of type PAD SPACE. This means that all 'CHAR',
'VARCHAR', and 'TEXT' values are compared without regard to any trailing
spaces.  'Comparison' in this context does not include the 'LIKE'
pattern-matching operator, for which trailing spaces are significant.
For example:

     mysql> CREATE TABLE names (myname CHAR(10));
     Query OK, 0 rows affected (0.03 sec)

     mysql> INSERT INTO names VALUES ('Monty');
     Query OK, 1 row affected (0.00 sec)

     mysql> SELECT myname = 'Monty', myname = 'Monty  ' FROM names;
     +------------------+--------------------+
     | myname = 'Monty' | myname = 'Monty  ' |
     +------------------+--------------------+
     |                1 |                  1 |
     +------------------+--------------------+
     1 row in set (0.00 sec)

     mysql> SELECT myname LIKE 'Monty', myname LIKE 'Monty  ' FROM names;
     +---------------------+-----------------------+
     | myname LIKE 'Monty' | myname LIKE 'Monty  ' |
     +---------------------+-----------------------+
     |                   1 |                     0 |
     +---------------------+-----------------------+
     1 row in set (0.00 sec)

This is true for all MySQL versions, and is not affected by the server
SQL mode.

*Note*:

For more information about MySQL character sets and collations, see
charset.  For additional information about storage requirements,
see storage-requirements.

For those cases where trailing pad characters are stripped or
comparisons ignore them, if a column has an index that requires unique
values, inserting into the column values that differ only in number of
trailing pad characters will result in a duplicate-key error.  For
example, if a table contains ''a'', an attempt to store ''a '' causes a
duplicate-key error.

11.4.2 The BINARY and VARBINARY Types
-------------------------------------

The 'BINARY' and 'VARBINARY' types are similar to 'CHAR'.
and 'VARCHAR', except that they contain binary strings
rather than nonbinary strings.  That is, they contain byte strings
rather than character strings.  This means they have the 'binary'
character set and collation, and comparison and sorting are based on the
numeric values of the bytes in the values.

The permissible maximum length is the same for 'BINARY' and 'VARBINARY'
as it is for 'CHAR' and 'VARCHAR', except that
the length for 'BINARY' and 'VARBINARY' is a length in bytes rather than
in characters.

The 'BINARY' and 'VARBINARY' data types are distinct from the 'CHAR
BINARY' and 'VARCHAR BINARY' data types.  For the latter types, the
'BINARY' attribute does not cause the column to be treated as a binary
string column.  Instead, it causes the binary ('_bin') collation for the
column character set to be used, and the column itself contains
nonbinary character strings rather than binary byte strings.  For
example, 'CHAR(5) BINARY' is treated as 'CHAR(5) CHARACTER SET latin1
COLLATE latin1_bin', assuming that the default character set is
'latin1'.  This differs from 'BINARY(5)', which stores 5-bytes binary
strings that have the 'binary' character set and collation.  For
information about differences between binary strings and binary
collations for nonbinary strings, see charset-binary-collations.

If strict SQL mode is not enabled and you assign a value to a 'BINARY'
or 'VARBINARY' column that exceeds the column's maximum length, the
value is truncated to fit and a warning is generated.  For cases of
truncation, you can cause an error to occur (rather than a warning) and
suppress insertion of the value by using strict SQL mode.  See
sql-mode.

When 'BINARY' values are stored, they are right-padded with the pad
value to the specified length.  The pad value is '0x00' (the zero byte).
Values are right-padded with '0x00' on insert, and no trailing bytes are
removed on select.  All bytes are significant in comparisons, including
'ORDER BY' and 'DISTINCT' operations.  '0x00' bytes and spaces are
different in comparisons, with '0x00' < space.

Example: For a 'BINARY(3)' column, ''a '' becomes ''a \0'' when
inserted.  ''a\0'' becomes ''a\0\0'' when inserted.  Both inserted
values remain unchanged when selected.

For 'VARBINARY', there is no padding on insert and no bytes are stripped
on select.  All bytes are significant in comparisons, including 'ORDER
BY' and 'DISTINCT' operations.  '0x00' bytes and spaces are different in
comparisons, with '0x00' < space.

For those cases where trailing pad bytes are stripped or comparisons
ignore them, if a column has an index that requires unique values,
inserting into the column values that differ only in number of trailing
pad bytes will result in a duplicate-key error.  For example, if a table
contains ''a'', an attempt to store ''a\0'' causes a duplicate-key
error.

You should consider the preceding padding and stripping characteristics
carefully if you plan to use the 'BINARY' data type for storing binary
data and you require that the value retrieved be exactly the same as the
value stored.  The following example illustrates how '0x00'-padding of
'BINARY' values affects column value comparisons:

     mysql> CREATE TABLE t (c BINARY(3));
     Query OK, 0 rows affected (0.01 sec)

     mysql> INSERT INTO t SET c = 'a';
     Query OK, 1 row affected (0.01 sec)

     mysql> SELECT HEX(c), c = 'a', c = 'a\0\0' from t;
     +--------+---------+-------------+
     | HEX(c) | c = 'a' | c = 'a\0\0' |
     +--------+---------+-------------+
     | 610000 |       0 |           1 |
     +--------+---------+-------------+
     1 row in set (0.09 sec)

If the value retrieved must be the same as the value specified for
storage with no padding, it might be preferable to use 'VARBINARY' or
one of the 'BLOB' data types instead.

11.4.3 The BLOB and TEXT Types
------------------------------

A 'BLOB' is a binary large object that can hold a variable amount of
data.  The four 'BLOB' types are 'TINYBLOB', 'BLOB', 'MEDIUMBLOB', and
'LONGBLOB'.  These differ only in the maximum length of the values they
can hold.  The four 'TEXT' types are 'TINYTEXT', 'TEXT', 'MEDIUMTEXT',
and 'LONGTEXT'.  These correspond to the four 'BLOB' types and have the
same maximum lengths and storage requirements.  See
storage-requirements.

'BLOB' values are treated as binary strings (byte strings).  They have
the 'binary' character set and collation, and comparison and sorting are
based on the numeric values of the bytes in column values.  'TEXT'
values are treated as nonbinary strings (character strings).  They have
a character set other than 'binary', and values are sorted and compared
based on the collation of the character set.

If strict SQL mode is not enabled and you assign a value to a 'BLOB' or
'TEXT' column that exceeds the column's maximum length, the value is
truncated to fit and a warning is generated.  For truncation of nonspace
characters, you can cause an error to occur (rather than a warning) and
suppress insertion of the value by using strict SQL mode.  See
sql-mode.

Truncation of excess trailing spaces from values to be inserted into
'TEXT' columns always generates a warning, regardless of
the SQL mode.

For 'TEXT' and 'BLOB' columns, there is no padding on insert and no
bytes are stripped on select.

If a 'TEXT' column is indexed, index entry comparisons are space-padded
at the end.  This means that, if the index requires unique values,
duplicate-key errors will occur for values that differ only in the
number of trailing spaces.  For example, if a table contains ''a'', an
attempt to store ''a '' causes a duplicate-key error.  This is not true
for 'BLOB' columns.

In most respects, you can regard a 'BLOB' column as a 'VARBINARY'
column that can be as large as you like.  Similarly,
you can regard a 'TEXT' column as a 'VARCHAR' column.
'BLOB' and 'TEXT' differ from 'VARBINARY' and
'VARCHAR' in the following ways:

   * For indexes on 'BLOB' and 'TEXT' columns, you must specify an index
     prefix length.  For 'CHAR' and 'VARCHAR',
     a prefix length is optional.  See column-indexes.

   *
     'BLOB' and 'TEXT' columns cannot have 'DEFAULT' values.

If you use the 'BINARY' attribute with a 'TEXT' data type, the column is
assigned the binary ('_bin') collation of the column character set.

'LONG' and 'LONG VARCHAR' map to the 'MEDIUMTEXT' data type.  This is a
compatibility feature.

MySQL Connector/ODBC defines 'BLOB' values as 'LONGVARBINARY' and 'TEXT'
values as 'LONGVARCHAR'.

Because 'BLOB' and 'TEXT' values can be extremely long, you might
encounter some constraints in using them:

   * Only the first 'max_sort_length' bytes of the column are used when
     sorting.  The default value of 'max_sort_length' is 1024.  You can
     make more bytes significant in sorting or grouping by increasing
     the value of 'max_sort_length' at server startup or runtime.  Any
     client can change the value of its session 'max_sort_length'
     variable:

          mysql> SET max_sort_length = 2000;
          mysql> SELECT id, comment FROM t
              -> ORDER BY comment;

   * Instances of 'BLOB' or 'TEXT' columns in the result of a query that
     is processed using a temporary table causes the server to use a
     table on disk rather than in memory because the 'MEMORY' storage
     engine does not support those data types (see
     internal-temporary-tables).  Use of disk incurs a performance
     penalty, so include 'BLOB' or 'TEXT' columns in the query result
     only if they are really needed.  For example, avoid using
     'SELECT *', which selects all columns.

   * The maximum size of a 'BLOB' or 'TEXT' object is determined by its
     type, but the largest value you actually can transmit between the
     client and server is determined by the amount of available memory
     and the size of the communications buffers.  You can change the
     message buffer size by changing the value of the
     'max_allowed_packet' variable, but you must do so for both the
     server and your client program.  For example, both 'mysql'
     and 'mysqldump' enable you to change the
     client-side 'max_allowed_packet' value.  See
     server-configuration, mysql, and mysqldump.  You
     may also want to compare the packet sizes and the size of the data
     objects you are storing with the storage requirements, see
     storage-requirements

Each 'BLOB' or 'TEXT' value is represented internally by a separately
allocated object.  This is in contrast to all other data types, for
which storage is allocated once per column when the table is opened.

In some cases, it may be desirable to store binary data such as media
files in 'BLOB' or 'TEXT' columns.  You may find MySQL's string handling
functions useful for working with such data.  See
string-functions.  For security and other reasons, it is usually
preferable to do so using application code rather than giving
application users the 'FILE' privilege.  You can discuss specifics for
various languages and platforms in the MySQL Forums
(<http://forums.mysql.com/>).

11.4.4 The ENUM Type
--------------------

An 'ENUM' is a string object with a value chosen from a list of
permitted values that are enumerated explicitly in the column
specification at table creation time.  It has these advantages:

   * Compact data storage in situations where a column has a limited set
     of possible values.  The strings you specify as input values are
     automatically encoded as numbers.  See storage-requirements
     for the storage requirements for 'ENUM' types.

   * Readable queries and output.  The numbers are translated back to
     the corresponding strings in query results.

and these potential issues to consider:

   * If you make enumeration values that look like numbers, it is easy
     to mix up the literal values with their internal index numbers, as
     explained in enum-limits.

   * Using 'ENUM' columns in 'ORDER BY' clauses requires extra care, as
     explained in enum-sorting.

   * enum-using

   * enum-indexes

   * enum-literals

   * enum-nulls

   * enum-sorting

   * enum-limits

*Creating and Using ENUM Columns*

An enumeration value must be a quoted string literal.  For example, you
can create a table with an 'ENUM' column like this:

     CREATE TABLE shirts (
         name VARCHAR(40),
         size ENUM('x-small', 'small', 'medium', 'large', 'x-large')
     );
     INSERT INTO shirts (name, size) VALUES ('dress shirt','large'), ('t-shirt','medium'),
       ('polo shirt','small');
     SELECT name, size FROM shirts WHERE size = 'medium';
     +---------+--------+
     | name    | size   |
     +---------+--------+
     | t-shirt | medium |
     +---------+--------+
     UPDATE shirts SET size = 'small' WHERE size = 'large';
     COMMIT;

Inserting 1 million rows into this table with a value of ''medium''
would require 1 million bytes of storage, as opposed to 6 million bytes
if you stored the actual string ''medium'' in a 'VARCHAR' column.

*Index Values for Enumeration Literals*

Each enumeration value has an index:

   * The elements listed in the column specification are assigned index
     numbers, beginning with 1.

   * The index value of the empty string error value is 0.  This means
     that you can use the following 'SELECT' statement to
     find rows into which invalid 'ENUM' values were assigned:

          mysql> SELECT * FROM TBL_NAME WHERE ENUM_COL=0;

   * The index of the 'NULL' value is 'NULL'.

   * The term 'index' here refers to a position within the list of
     enumeration values.  It has nothing to do with table indexes.

For example, a column specified as 'ENUM('Mercury', 'Venus', 'Earth')'
can have any of the values shown here.  The index of each value is also
shown.

Value       Index

'NULL'      'NULL'

''''        0

''Mercury'' 1

''Venus''   2

''Earth''   3

An 'ENUM' column can have a maximum of 65,535 distinct
elements.  (The practical limit is less than 3000.)  A table can have no
more than 255 unique element list definitions among its 'ENUM'
and 'SET' columns considered as a group.  For more
information on these limits, see limits-frm-file.

If you retrieve an 'ENUM' value in a numeric context, the column value's
index is returned.  For example, you can retrieve numeric values from an
'ENUM' column like this:

     mysql> SELECT ENUM_COL+0 FROM TBL_NAME;

Functions such as 'SUM()' or 'AVG()' that expect a numeric argument cast
the argument to a number if necessary.  For 'ENUM' values, the index
number is used in the calculation.

*Handling of Enumeration Literals*

Trailing spaces are automatically deleted from 'ENUM' member values in
the table definition when a table is created.

When retrieved, values stored into an 'ENUM' column are displayed using
the lettercase that was used in the column definition.  Note that 'ENUM'
columns can be assigned a character set and collation.  For binary or
case-sensitive collations, lettercase is taken into account when
assigning values to the column.

If you store a number into an 'ENUM' column, the number is treated as
the index into the possible values, and the value stored is the
enumeration member with that index.  (However, this does _not_ work with
'LOAD DATA', which treats all input as strings.)  If
the numeric value is quoted, it is still interpreted as an index if
there is no matching string in the list of enumeration values.  For
these reasons, it is not advisable to define an 'ENUM' column with
enumeration values that look like numbers, because this can easily
become confusing.  For example, the following column has enumeration
members with string values of ''0'', ''1'', and ''2'', but numeric index
values of '1', '2', and '3':

     numbers ENUM('0','1','2')

If you store '2', it is interpreted as an index value, and becomes ''1''
(the value with index 2).  If you store ''2'', it matches an enumeration
value, so it is stored as ''2''.  If you store ''3'', it does not match
any enumeration value, so it is treated as an index and becomes ''2''
(the value with index 3).

     mysql> INSERT INTO t (numbers) VALUES(2),('2'),('3');
     mysql> SELECT * FROM t;
     +---------+
     | numbers |
     +---------+
     | 1       |
     | 2       |
     | 2       |
     +---------+

To determine all possible values for an 'ENUM' column, use 'SHOW COLUMNS FROM TBL_NAME LIKE 'ENUM_COL''
and parse the
'ENUM' definition in the 'Type' column of the output.

In the C API, 'ENUM' values are returned as strings.  For information
about using result set metadata to distinguish them from other strings,
see c-api-data-structures.

*Empty or NULL Enumeration Values*

An enumeration value can also be the empty string ('''') or 'NULL' under
certain circumstances:

   * If you insert an invalid value into an 'ENUM' (that is, a string
     not present in the list of permitted values), the empty string is
     inserted instead as a special error value.  This string can be
     distinguished from a 'normal' empty string by the fact that this
     string has the numeric value 0.  See enum-indexes for
     details about the numeric indexes for the enumeration values.

     If strict SQL mode is enabled, attempts to insert invalid 'ENUM'
     values result in an error.

   * If an 'ENUM' column is declared to permit 'NULL', the 'NULL' value
     is a valid value for the column, and the default value is 'NULL'.
     If an 'ENUM' column is declared 'NOT NULL', its default value is
     the first element of the list of permitted values.

*Enumeration Sorting*

'ENUM' values are sorted based on their index numbers, which depend on
the order in which the enumeration members were listed in the column
specification.  For example, ''b'' sorts before ''a'' for 'ENUM('b',
'a')'.  The empty string sorts before nonempty strings, and 'NULL'
values sort before all other enumeration values.

To prevent unexpected results when using the 'ORDER BY' clause on an
'ENUM' column, use one of these techniques:

   * Specify the 'ENUM' list in alphabetic order.

   * Make sure that the column is sorted lexically rather than by index
     number by coding 'ORDER BY CAST(COL AS CHAR)' or 'ORDER BY
     CONCAT(COL)'.

*Enumeration Limitations*

An enumeration value cannot be an expression, even one that evaluates to
a string value.

For example, this 'CREATE TABLE' statement does
_not_ work because the 'CONCAT' function cannot be used to construct an
enumeration value:

     CREATE TABLE sizes (
         size ENUM('small', CONCAT('med','ium'), 'large')
     );

You also cannot employ a user variable as an enumeration value.  This
pair of statements do _not_ work:

     SET @mysize = 'medium';

     CREATE TABLE sizes (
         size ENUM('small', @mysize, 'large')
     );

We strongly recommend that you do _not_ use numbers as enumeration
values, because it does not save on storage over the appropriate
'TINYINT' or 'SMALLINT' type, and
it is easy to mix up the strings and the underlying number values (which
might not be the same) if you quote the 'ENUM' values incorrectly.  If
you do use a number as an enumeration value, always enclose it in
quotation marks.  If the quotation marks are omitted, the number is
regarded as an index.  See enum-literals to see how even a
quoted number could be mistakenly used as a numeric index value.

Duplicate values in the definition cause a warning, or an error if
strict SQL mode is enabled.

11.4.5 The SET Type
-------------------

A 'SET' is a string object that can have zero or more values, each of
which must be chosen from a list of permitted values specified when the
table is created.  'SET' column values that consist of multiple set
members are specified with members separated by commas (',').  A
consequence of this is that 'SET' member values should not themselves
contain commas.

For example, a column specified as 'SET('one', 'two') NOT NULL' can have
any of these values:

     ''
     'one'
     'two'
     'one,two'

A 'SET' column can have a maximum of 64 distinct members.  A
table can have no more than 255 unique element list definitions among
its 'ENUM' and 'SET' columns considered as a
group.  For more information on this limit, see limits-frm-file.

Duplicate values in the definition cause a warning, or an error if
strict SQL mode is enabled.

Trailing spaces are automatically deleted from 'SET' member values in
the table definition when a table is created.

When retrieved, values stored in a 'SET' column are displayed using the
lettercase that was used in the column definition.  Note that 'SET'
columns can be assigned a character set and collation.  For binary or
case-sensitive collations, lettercase is taken into account when
assigning values to the column.

MySQL stores 'SET' values numerically, with the low-order bit of the
stored value corresponding to the first set member.  If you retrieve a
'SET' value in a numeric context, the value retrieved has bits set
corresponding to the set members that make up the column value.  For
example, you can retrieve numeric values from a 'SET' column like this:

     mysql> SELECT SET_COL+0 FROM TBL_NAME;

If a number is stored into a 'SET' column, the bits that are set in the
binary representation of the number determine the set members in the
column value.  For a column specified as 'SET('a','b','c','d')', the
members have the following decimal and binary values.

'SET'       Decimal        Binary Value
Member      Value

''a''       '1'            '0001'

''b''       '2'            '0010'

''c''       '4'            '0100'

''d''       '8'            '1000'

If you assign a value of '9' to this column, that is '1001' in binary,
so the first and fourth 'SET' value members ''a'' and ''d'' are selected
and the resulting value is ''a,d''.

For a value containing more than one 'SET' element, it does not matter
what order the elements are listed in when you insert the value.  It
also does not matter how many times a given element is listed in the
value.  When the value is retrieved later, each element in the value
appears once, with elements listed according to the order in which they
were specified at table creation time.  For example, suppose that a
column is specified as 'SET('a','b','c','d')':

     mysql> CREATE TABLE myset (col SET('a', 'b', 'c', 'd'));

If you insert the values ''a,d'', ''d,a'', ''a,d,d'', ''a,d,a'', and
''d,a,d'':

     mysql> INSERT INTO myset (col) VALUES
     -> ('a,d'), ('d,a'), ('a,d,a'), ('a,d,d'), ('d,a,d');
     Query OK, 5 rows affected (0.01 sec)
     Records: 5  Duplicates: 0  Warnings: 0

Then all these values appear as ''a,d'' when retrieved:

     mysql> SELECT col FROM myset;
     +------+
     | col  |
     +------+
     | a,d  |
     | a,d  |
     | a,d  |
     | a,d  |
     | a,d  |
     +------+
     5 rows in set (0.04 sec)

If you set a 'SET' column to an unsupported value, the value is ignored
and a warning is issued:

     mysql> INSERT INTO myset (col) VALUES ('a,d,d,s');
     Query OK, 1 row affected, 1 warning (0.03 sec)

     mysql> SHOW WARNINGS;
     +---------+------+------------------------------------------+
     | Level   | Code | Message                                  |
     +---------+------+------------------------------------------+
     | Warning | 1265 | Data truncated for column 'col' at row 1 |
     +---------+------+------------------------------------------+
     1 row in set (0.04 sec)

     mysql> SELECT col FROM myset;
     +------+
     | col  |
     +------+
     | a,d  |
     | a,d  |
     | a,d  |
     | a,d  |
     | a,d  |
     | a,d  |
     +------+
     6 rows in set (0.01 sec)

If strict SQL mode is enabled, attempts to insert invalid 'SET' values
result in an error.

'SET' values are sorted numerically.  'NULL' values sort before
non-'NULL' 'SET' values.

Functions such as 'SUM()' or 'AVG()' that expect a numeric argument cast
the argument to a number if necessary.  For 'SET' values, the cast
operation causes the numeric value to be used.

Normally, you search for 'SET' values using the 'FIND_IN_SET()' function
or the 'LIKE' operator:

     mysql> SELECT * FROM TBL_NAME WHERE FIND_IN_SET('VALUE',SET_COL)>0;
     mysql> SELECT * FROM TBL_NAME WHERE SET_COL LIKE '%VALUE%';

The first statement finds rows where SET_COL contains the VALUE set
member.  The second is similar, but not the same: It finds rows where
SET_COL contains VALUE anywhere, even as a substring of another set
member.

The following statements also are permitted:

     mysql> SELECT * FROM TBL_NAME WHERE SET_COL & 1;
     mysql> SELECT * FROM TBL_NAME WHERE SET_COL = 'VAL1,VAL2';

The first of these statements looks for values containing the first set
member.  The second looks for an exact match.  Be careful with
comparisons of the second type.  Comparing set values to ''VAL1,VAL2''
returns different results than comparing values to ''VAL2,VAL1''.  You
should specify the values in the same order they are listed in the
column definition.

To determine all possible values for a 'SET' column, use 'SHOW COLUMNS
FROM TBL_NAME LIKE SET_COL' and parse the 'SET' definition in the 'Type'
column of the output.

In the C API, 'SET' values are returned as strings.  For information
about using result set metadata to distinguish them from other strings,
see c-api-data-structures.

11.5 Spatial Data Types
=======================

The Open Geospatial Consortium (OGC) is an international consortium of
more than 250 companies, agencies, and universities participating in the
development of publicly available conceptual solutions that can be
useful with all kinds of applications that manage spatial data.

The Open Geospatial Consortium publishes the 'OpenGIS(R) Implementation
Standard for Geographic information - Simple feature access - Part 2:
SQL option', a document that proposes several conceptual ways for
extending an SQL RDBMS to support spatial data.  This specification is
available from the OGC website at
<http://www.opengeospatial.org/standards/sfs>.

Following the OGC specification, MySQL implements spatial extensions as
a subset of the *SQL with Geometry Types* environment.  This term refers
to an SQL environment that has been extended with a set of geometry
types.  A geometry-valued SQL column is implemented as a column that has
a geometry type.  The specification describes a set of SQL geometry
types, as well as functions on those types to create and analyze
geometry values.

MySQL spatial extensions enable the generation, storage, and analysis of
geographic features:

   * Data types for representing spatial values

   * Functions for manipulating spatial values

   * Spatial indexing for improved access times to spatial columns

The spatial data types and functions are available for 'MyISAM',
see 'InnoDB',
'NDB', and 'ARCHIVE'.
tables.  For indexing spatial columns, 'MyISAM' and 'InnoDB' support
both 'SPATIAL' and non-'SPATIAL' indexes.  The other storage engines
support non-'SPATIAL' indexes, as described in create-index.

A *geographic feature* is anything in the world that has a location.  A
feature can be:

   * An entity.  For example, a mountain, a pond, a city.

   * A space.  For example, town district, the tropics.

   * A definable location.  For example, a crossroad, as a particular
     place where two streets intersect.

Some documents use the term *geospatial feature* to refer to geographic
features.

*Geometry* is another word that denotes a geographic feature.
Originally the word *geometry* meant measurement of the earth.  Another
meaning comes from cartography, referring to the geometric features that
cartographers use to map the world.

The discussion here considers these terms synonymous: *geographic
feature*, *geospatial feature*, *feature*, or *geometry*.  The term most
commonly used is *geometry*, defined as _a point or an aggregate of
points representing anything in the world that has a location_.

The following material covers these topics:

   * The spatial data types implemented in MySQL model

   * The basis of the spatial extensions in the OpenGIS geometry model

   * Data formats for representing spatial data

   * How to use spatial data in MySQL

   * Use of indexing for spatial data

   * MySQL differences from the OpenGIS specification

For information about functions that operate on spatial data, see
spatial-analysis-functions.

*MySQL GIS Conformance and Compatibility*

MySQL does not implement the following GIS features:

   * Additional Metadata Views

     OpenGIS specifications propose several additional metadata views.
     For example, a system view named 'GEOMETRY_COLUMNS' contains a
     description of geometry columns, one row for each geometry column
     in the database.

   * The OpenGIS function 'Length()' on 'LineString' and
     'MultiLineString' should be called in MySQL as 'ST_Length()'

     The problem is that there is an existing SQL function 'Length()'
     that calculates the length of string values, and sometimes it is
     not possible to distinguish whether the function is called in a
     textual or spatial context.

*Additional Resources*

   * The Open Geospatial Consortium publishes the 'OpenGIS(R)
     Implementation Standard for Geographic information - Simple feature
     access - Part 2: SQL option', a document that proposes several
     conceptual ways for extending an SQL RDBMS to support spatial data.
     The Open Geospatial Consortium (OGC) maintains a website at
     <http://www.opengeospatial.org/>.  The specification is available
     there at <http://www.opengeospatial.org/standards/sfs>.  It
     contains additional information relevant to the material here.

   * If you have questions or concerns about the use of the spatial
     extensions to MySQL, you can discuss them in the GIS forum:
     <http://forums.mysql.com/list.php?23>.

11.5.1 Spatial Data Types
-------------------------

MySQL has spatial data types that correspond to OpenGIS classes.  The
basis for these types is described in opengis-geometry-model.

Some spatial data types hold single geometry values:

   * 'GEOMETRY'

   * 'POINT'

   * 'LINESTRING'

   * 'POLYGON'

'GEOMETRY' can store geometry values of any type.  The other
single-value types ('POINT', 'LINESTRING', and 'POLYGON') restrict their
values to a particular geometry type.

The other spatial data types hold collections of values:

   * 'MULTIPOINT'

   * 'MULTILINESTRING'

   * 'MULTIPOLYGON'

   * 'GEOMETRYCOLLECTION'

'GEOMETRYCOLLECTION' can store a collection of objects of any type.  The
other collection types ('MULTIPOINT', 'MULTILINESTRING', 'MULTIPOLYGON',
and 'GEOMETRYCOLLECTION') restrict collection members to those having a
particular geometry type.

Example: To create a table named 'geom' that has a column named 'g' that
can store values of any geometry type, use this statement:

     CREATE TABLE geom (g GEOMETRY);

'SPATIAL' indexes can be created on 'NOT NULL' spatial columns, so if
you plan to index the column, declare it 'NOT NULL':

     CREATE TABLE geom (g GEOMETRY NOT NULL);

For other examples showing how to use spatial data types in MySQL, see
creating-spatial-columns.

11.5.2 The OpenGIS Geometry Model
---------------------------------

The set of geometry types proposed by OGC's *SQL with Geometry Types*
environment is based on the *OpenGIS Geometry Model*.  In this model,
each geometric object has the following general properties:

   * It is associated with a spatial reference system, which describes
     the coordinate space in which the object is defined.

   * It belongs to some geometry class.

11.5.2.1 The Geometry Class Hierarchy
.....................................

The geometry classes define a hierarchy as follows:

   * 'Geometry' (noninstantiable)

        * 'Point' (instantiable)

        * 'Curve' (noninstantiable)

             * 'LineString' (instantiable)

                  * 'Line'

                  * 'LinearRing'

        * 'Surface' (noninstantiable)

             * 'Polygon' (instantiable)

        * 'GeometryCollection' (instantiable)

             * 'MultiPoint' (instantiable)

             * 'MultiCurve' (noninstantiable)

                  * 'MultiLineString' (instantiable)

             * 'MultiSurface' (noninstantiable)

                  * 'MultiPolygon' (instantiable)

It is not possible to create objects in noninstantiable classes.  It is
possible to create objects in instantiable classes.  All classes have
properties, and instantiable classes may also have assertions (rules
that define valid class instances).

'Geometry' is the base class.  It is an abstract class.  The
instantiable subclasses of 'Geometry' are restricted to zero-, one-, and
two-dimensional geometric objects that exist in two-dimensional
coordinate space.  All instantiable geometry classes are defined so that
valid instances of a geometry class are topologically closed (that is,
all defined geometries include their boundary).

The base 'Geometry' class has subclasses for 'Point', 'Curve',
'Surface', and 'GeometryCollection':

   * 'Point' represents zero-dimensional objects.

   * 'Curve' represents one-dimensional objects, and has subclass
     'LineString', with sub-subclasses 'Line' and 'LinearRing'.

   * 'Surface' is designed for two-dimensional objects and has subclass
     'Polygon'.

   * 'GeometryCollection' has specialized zero-, one-, and
     two-dimensional collection classes named 'MultiPoint',
     'MultiLineString', and 'MultiPolygon' for modeling geometries
     corresponding to collections of 'Points', 'LineStrings', and
     'Polygons', respectively.  'MultiCurve' and 'MultiSurface' are
     introduced as abstract superclasses that generalize the collection
     interfaces to handle 'Curves' and 'Surfaces'.

'Geometry', 'Curve', 'Surface', 'MultiCurve', and 'MultiSurface' are
defined as noninstantiable classes.  They define a common set of methods
for their subclasses and are included for extensibility.

'Point', 'LineString', 'Polygon', 'GeometryCollection', 'MultiPoint',
'MultiLineString', and 'MultiPolygon' are instantiable classes.

11.5.2.2 Geometry Class
.......................

'Geometry' is the root class of the hierarchy.  It is a noninstantiable
class but has a number of properties, described in the following list,
that are common to all geometry values created from any of the
'Geometry' subclasses.  Particular subclasses have their own specific
properties, described later.

*Geometry Properties*

A geometry value has the following properties:

   * Its *type*.  Each geometry belongs to one of the instantiable
     classes in the hierarchy.

   * Its *SRID*, or spatial reference identifier.  This value identifies
     the geometry's associated spatial reference system that describes
     the coordinate space in which the geometry object is defined.

     In MySQL, the SRID value is an integer associated with the geometry
     value.  The maximum usable SRID value is 2^32−1.  If a larger
     value is given, only the lower 32 bits are used.  All computations
     are done assuming SRID 0, regardless of the actual SRID value.
     SRID 0 represents an infinite flat Cartesian plane with no units
     assigned to its axes.

   * Its *coordinates* in its spatial reference system, represented as
     double-precision (8-byte) numbers.  All nonempty geometries include
     at least one pair of (X,Y) coordinates.  Empty geometries contain
     no coordinates.

     Coordinates are related to the SRID. For example, in different
     coordinate systems, the distance between two objects may differ
     even when objects have the same coordinates, because the distance
     on the *planar* coordinate system and the distance on the
     *geodetic* system (coordinates on the Earth's surface) are
     different things.

   * Its *interior*, *boundary*, and *exterior*.

     Every geometry occupies some position in space.  The exterior of a
     geometry is all space not occupied by the geometry.  The interior
     is the space occupied by the geometry.  The boundary is the
     interface between the geometry's interior and exterior.

   * Its *MBR* (minimum bounding rectangle), or envelope.  This is the
     bounding geometry, formed by the minimum and maximum (X,Y)
     coordinates:

          ((MINX MINY, MAXX MINY, MAXX MAXY, MINX MAXY, MINX MINY))

   * Whether the value is *simple* or *nonsimple*.  Geometry values of
     types ('LineString', 'MultiPoint', 'MultiLineString') are either
     simple or nonsimple.  Each type determines its own assertions for
     being simple or nonsimple.

   * Whether the value is *closed* or *not closed*.  Geometry values of
     types ('LineString', 'MultiString') are either closed or not
     closed.  Each type determines its own assertions for being closed
     or not closed.

   * Whether the value is *empty* or *nonempty* A geometry is empty if
     it does not have any points.  Exterior, interior, and boundary of
     an empty geometry are not defined (that is, they are represented by
     a 'NULL' value).  An empty geometry is defined to be always simple
     and has an area of 0.

   * Its *dimension*.  A geometry can have a dimension of −1, 0, 1, or
     2:

        * −1 for an empty geometry.

        * 0 for a geometry with no length and no area.

        * 1 for a geometry with nonzero length and zero area.

        * 2 for a geometry with nonzero area.

     'Point' objects have a dimension of zero.  'LineString' objects
     have a dimension of 1.  'Polygon' objects have a dimension of 2.
     The dimensions of 'MultiPoint', 'MultiLineString', and
     'MultiPolygon' objects are the same as the dimensions of the
     elements they consist of.

11.5.2.3 Point Class
....................

A 'Point' is a geometry that represents a single location in coordinate
space.

*'Point' Examples*

   * Imagine a large-scale map of the world with many cities.  A 'Point'
     object could represent each city.

   * On a city map, a 'Point' object could represent a bus stop.

*'Point' Properties*

   * X-coordinate value.

   * Y-coordinate value.

   * 'Point' is defined as a zero-dimensional geometry.

   * The boundary of a 'Point' is the empty set.

11.5.2.4 Curve Class
....................

A 'Curve' is a one-dimensional geometry, usually represented by a
sequence of points.  Particular subclasses of 'Curve' define the type of
interpolation between points.  'Curve' is a noninstantiable class.

*'Curve' Properties*

   * A 'Curve' has the coordinates of its points.

   * A 'Curve' is defined as a one-dimensional geometry.

   * A 'Curve' is simple if it does not pass through the same point
     twice, with the exception that a curve can still be simple if the
     start and end points are the same.

   * A 'Curve' is closed if its start point is equal to its endpoint.

   * The boundary of a closed 'Curve' is empty.

   * The boundary of a nonclosed 'Curve' consists of its two endpoints.

   * A 'Curve' that is simple and closed is a 'LinearRing'.

11.5.2.5 LineString Class
.........................

A 'LineString' is a 'Curve' with linear interpolation between points.

*'LineString' Examples*

   * On a world map, 'LineString' objects could represent rivers.

   * In a city map, 'LineString' objects could represent streets.

*'LineString' Properties*

   * A 'LineString' has coordinates of segments, defined by each
     consecutive pair of points.

   * A 'LineString' is a 'Line' if it consists of exactly two points.

   * A 'LineString' is a 'LinearRing' if it is both closed and simple.

11.5.2.6 Surface Class
......................

A 'Surface' is a two-dimensional geometry.  It is a noninstantiable
class.  Its only instantiable subclass is 'Polygon'.

*'Surface' Properties*

   * A 'Surface' is defined as a two-dimensional geometry.

   * The OpenGIS specification defines a simple 'Surface' as a geometry
     that consists of a single 'patch' that is associated with a single
     exterior boundary and zero or more interior boundaries.

   * The boundary of a simple 'Surface' is the set of closed curves
     corresponding to its exterior and interior boundaries.

11.5.2.7 Polygon Class
......................

A 'Polygon' is a planar 'Surface' representing a multisided geometry.
It is defined by a single exterior boundary and zero or more interior
boundaries, where each interior boundary defines a hole in the
'Polygon'.

*'Polygon' Examples*

   * On a region map, 'Polygon' objects could represent forests,
     districts, and so on.

*'Polygon' Assertions*

   * The boundary of a 'Polygon' consists of a set of 'LinearRing'
     objects (that is, 'LineString' objects that are both simple and
     closed) that make up its exterior and interior boundaries.

   * A 'Polygon' has no rings that cross.  The rings in the boundary of
     a 'Polygon' may intersect at a 'Point', but only as a tangent.

   * A 'Polygon' has no lines, spikes, or punctures.

   * A 'Polygon' has an interior that is a connected point set.

   * A 'Polygon' may have holes.  The exterior of a 'Polygon' with holes
     is not connected.  Each hole defines a connected component of the
     exterior.

The preceding assertions make a 'Polygon' a simple geometry.

11.5.2.8 GeometryCollection Class
.................................

A 'GeometryCollection' is a geometry that is a collection of zero or
more geometries of any class.

All the elements in a geometry collection must be in the same spatial
reference system (that is, in the same coordinate system).  There are no
other constraints on the elements of a geometry collection, although the
subclasses of 'GeometryCollection' described in the following sections
may restrict membership.  Restrictions may be based on:

   * Element type (for example, a 'MultiPoint' may contain only 'Point'
     elements)

   * Dimension

   * Constraints on the degree of spatial overlap between elements

11.5.2.9 MultiPoint Class
.........................

A 'MultiPoint' is a geometry collection composed of 'Point' elements.
The points are not connected or ordered in any way.

*'MultiPoint' Examples*

   * On a world map, a 'MultiPoint' could represent a chain of small
     islands.

   * On a city map, a 'MultiPoint' could represent the outlets for a
     ticket office.

*'MultiPoint' Properties*

   * A 'MultiPoint' is a zero-dimensional geometry.

   * A 'MultiPoint' is simple if no two of its 'Point' values are equal
     (have identical coordinate values).

   * The boundary of a 'MultiPoint' is the empty set.

11.5.2.10 MultiCurve Class
..........................

A 'MultiCurve' is a geometry collection composed of 'Curve' elements.
'MultiCurve' is a noninstantiable class.

*'MultiCurve' Properties*

   * A 'MultiCurve' is a one-dimensional geometry.

   * A 'MultiCurve' is simple if and only if all of its elements are
     simple; the only intersections between any two elements occur at
     points that are on the boundaries of both elements.

   * A 'MultiCurve' boundary is obtained by applying the 'mod 2 union
     rule' (also known as the 'odd-even rule'): A point is in the
     boundary of a 'MultiCurve' if it is in the boundaries of an odd
     number of 'Curve' elements.

   * A 'MultiCurve' is closed if all of its elements are closed.

   * The boundary of a closed 'MultiCurve' is always empty.

11.5.2.11 MultiLineString Class
...............................

A 'MultiLineString' is a 'MultiCurve' geometry collection composed of
'LineString' elements.

*'MultiLineString' Examples*

   * On a region map, a 'MultiLineString' could represent a river system
     or a highway system.

11.5.2.12 MultiSurface Class
............................

A 'MultiSurface' is a geometry collection composed of surface elements.
'MultiSurface' is a noninstantiable class.  Its only instantiable
subclass is 'MultiPolygon'.

*'MultiSurface' Assertions*

   * Surfaces within a 'MultiSurface' have no interiors that intersect.

   * Surfaces within a 'MultiSurface' have boundaries that intersect at
     most at a finite number of points.

11.5.2.13 MultiPolygon Class
............................

A 'MultiPolygon' is a 'MultiSurface' object composed of 'Polygon'
elements.

*'MultiPolygon' Examples*

   * On a region map, a 'MultiPolygon' could represent a system of
     lakes.

*'MultiPolygon' Assertions*

   * A 'MultiPolygon' has no two 'Polygon' elements with interiors that
     intersect.

   * A 'MultiPolygon' has no two 'Polygon' elements that cross (crossing
     is also forbidden by the previous assertion), or that touch at an
     infinite number of points.

   * A 'MultiPolygon' may not have cut lines, spikes, or punctures.  A
     'MultiPolygon' is a regular, closed point set.

   * A 'MultiPolygon' that has more than one 'Polygon' has an interior
     that is not connected.  The number of connected components of the
     interior of a 'MultiPolygon' is equal to the number of 'Polygon'
     values in the 'MultiPolygon'.

*'MultiPolygon' Properties*

   * A 'MultiPolygon' is a two-dimensional geometry.

   * A 'MultiPolygon' boundary is a set of closed curves ('LineString'
     values) corresponding to the boundaries of its 'Polygon' elements.

   * Each 'Curve' in the boundary of the 'MultiPolygon' is in the
     boundary of exactly one 'Polygon' element.

   * Every 'Curve' in the boundary of an 'Polygon' element is in the
     boundary of the 'MultiPolygon'.

11.5.3 Supported Spatial Data Formats
-------------------------------------

Two standard spatial data formats are used to represent geometry objects
in queries:

   * Well-Known Text (WKT) format

   * Well-Known Binary (WKB) format

Internally, MySQL stores geometry values in a format that is not
identical to either WKT or WKB format.  (Internal format is like WKB but
with an initial 4 bytes to indicate the SRID.)

There are functions available to convert between different data formats;
see gis-format-conversion-functions.

The following sections describe the spatial data formats MySQL uses:

   * gis-wkt-format

   * gis-wkb-format

   * gis-internal-format

*Well-Known Text (WKT) Format*

The Well-Known Text (WKT) representation of geometry values is designed
for exchanging geometry data in ASCII form.  The OpenGIS specification
provides a Backus-Naur grammar that specifies the formal production
rules for writing WKT values (see spatial-types).

Examples of WKT representations of geometry objects:

   * A 'Point':

          POINT(15 20)

     The point coordinates are specified with no separating comma.  This
     differs from the syntax for the SQL 'Point()' function, which
     requires a comma between the coordinates.  Take care to use the
     syntax appropriate to the context of a given spatial operation.
     For example, the following statements both use 'ST_X()' to extract
     the X-coordinate from a 'Point' object.  The first produces the
     object directly using the 'Point()' function.  The second uses a
     WKT representation converted to a 'Point' with 'ST_GeomFromText()'.

          mysql> SELECT ST_X(Point(15, 20));
          +---------------------+
          | ST_X(POINT(15, 20)) |
          +---------------------+
          |                  15 |
          +---------------------+

          mysql> SELECT ST_X(ST_GeomFromText('POINT(15 20)'));
          +---------------------------------------+
          | ST_X(ST_GeomFromText('POINT(15 20)')) |
          +---------------------------------------+
          |                                    15 |
          +---------------------------------------+

   * A 'LineString' with four points:

          LINESTRING(0 0, 10 10, 20 25, 50 60)

     The point coordinate pairs are separated by commas.

   * A 'Polygon' with one exterior ring and one interior ring:

          POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7, 5 5))

   * A 'MultiPoint' with three 'Point' values:

          MULTIPOINT(0 0, 20 20, 60 60)

     As of MySQL 5.7.9, spatial functions such as 'ST_MPointFromText()'
     and 'ST_GeomFromText()' that accept WKT-format representations of
     'MultiPoint' values permit individual points within values to be
     surrounded by parentheses.  For example, both of the following
     function calls are valid, whereas before MySQL 5.7.9 the second one
     produces an error:

          ST_MPointFromText('MULTIPOINT (1 1, 2 2, 3 3)')
          ST_MPointFromText('MULTIPOINT ((1 1), (2 2), (3 3))')

     As of MySQL 5.7.9, output for 'MultiPoint' values includes
     parentheses around each point.  For example:

          mysql> SET @mp = 'MULTIPOINT(1 1, 2 2, 3 3)';
          mysql> SELECT ST_AsText(ST_GeomFromText(@mp));
          +---------------------------------+
          | ST_AsText(ST_GeomFromText(@mp)) |
          +---------------------------------+
          | MULTIPOINT((1 1),(2 2),(3 3))   |
          +---------------------------------+

     Before MySQL 5.7.9, output for the same value does not include
     parentheses around each point:

          mysql> SET @mp = 'MULTIPOINT(1 1, 2 2, 3 3)';
          mysql> SELECT ST_AsText(ST_GeomFromText(@mp));
          +---------------------------------+
          | ST_AsText(ST_GeomFromText(@mp)) |
          +---------------------------------+
          | MULTIPOINT(1 1,2 2,3 3)         |
          +---------------------------------+

   * A 'MultiLineString' with two 'LineString' values:

          MULTILINESTRING((10 10, 20 20), (15 15, 30 15))

   * A 'MultiPolygon' with two 'Polygon' values:

          MULTIPOLYGON(((0 0,10 0,10 10,0 10,0 0)),((5 5,7 5,7 7,5 7, 5 5)))

   * A 'GeometryCollection' consisting of two 'Point' values and one
     'LineString':

          GEOMETRYCOLLECTION(POINT(10 10), POINT(30 30), LINESTRING(15 15, 20 20))

*Well-Known Binary (WKB) Format*

The Well-Known Binary (WKB) representation of geometric values is used
for exchanging geometry data as binary streams represented by
'BLOB' values containing geometric WKB information.  This format
is defined by the OpenGIS specification (see spatial-types).  It
is also defined in the ISO 'SQL/MM Part 3: Spatial' standard.

WKB uses 1-byte unsigned integers, 4-byte unsigned integers, and 8-byte
double-precision numbers (IEEE 754 format).  A byte is eight bits.

For example, a WKB value that corresponds to 'POINT(1 -1)' consists of
this sequence of 21 bytes, each represented by two hexadecimal digits:

     0101000000000000000000F03F000000000000F0BF

The sequence consists of the components shown in the following table.

*WKB Components Example*

Component              Size                   Value

Byte order             1 byte                 '01'

WKB type               4 bytes                '01000000'

X coordinate           8 bytes                '000000000000F03F'

Y coordinate           8 bytes                '000000000000F0BF'

Component representation is as follows:

   * The byte order indicator is either 1 or 0 to signify little-endian
     or big-endian storage.  The little-endian and big-endian byte
     orders are also known as Network Data Representation (NDR) and
     External Data Representation (XDR), respectively.

   * The WKB type is a code that indicates the geometry type.  MySQL
     uses values from 1 through 7 to indicate 'Point', 'LineString',
     'Polygon', 'MultiPoint', 'MultiLineString', 'MultiPolygon', and
     'GeometryCollection'.

   * A 'Point' value has X and Y coordinates, each represented as a
     double-precision value.

WKB values for more complex geometry values have more complex data
structures, as detailed in the OpenGIS specification.

*Internal Geometry Storage Format*

MySQL stores geometry values using 4 bytes to indicate the SRID followed
by the WKB representation of the value.  For a description of WKB
format, see gis-wkb-format.

For the WKB part, these MySQL-specific considerations apply:

   * The byte-order indicator byte is 1 because MySQL stores geometries
     as little-ending values.

   * MySQL supports geometry types of 'Point', 'LineString', 'Polygon',
     'MultiPoint', 'MultiLineString', 'MultiPolygon', and
     'GeometryCollection'.  Other geometry types are not supported.

The 'LENGTH()' function returns the space in bytes required for value
storage.  Example:

     mysql> SET @g = ST_GeomFromText('POINT(1 -1)');
     mysql> SELECT LENGTH(@g);
     +------------+
     | LENGTH(@g) |
     +------------+
     |         25 |
     +------------+
     mysql> SELECT HEX(@g);
     +----------------------------------------------------+
     | HEX(@g)                                            |
     +----------------------------------------------------+
     | 000000000101000000000000000000F03F000000000000F0BF |
     +----------------------------------------------------+

The value length is 25 bytes, made up of these components (as can be
seen from the hexadecimal value):

   * 4 bytes for integer SRID (0)

   * 1 byte for integer byte order (1 = little-endian)

   * 4 bytes for integer type information (1 = 'Point')

   * 8 bytes for double-precision X coordinate (1)

   * 8 bytes for double-precision Y coordinate (−1)

11.5.4 Geometry Well-Formedness and Validity
--------------------------------------------

For geometry values, MySQL distinguishes between the concepts of
syntactically well-formed and geometrically valid.

A geometry is syntactically well-formed if it satisfies conditions such
as those in this (nonexhaustive) list:

   * Linestrings have at least two points

   * Polygons have at least one ring

   * Polygon rings are closed (first and last points the same)

   * Polygon rings have at least 4 points (minimum polygon is a triangle
     with first and last points the same)

   * Collections are not empty (except 'GeometryCollection')

A geometry is geometrically valid if it is syntactically well-formed and
satisfies conditions such as those in this (nonexhaustive) list:

   * Polygons are not self-intersecting

   * Polygon interior rings are inside the exterior ring

   * Multipolygons do not have overlapping polygons

Spatial functions fail if a geometry is not syntactically well-formed.
Spatial import functions that parse WKT or WKB values raise an error for
attempts to create a geometry that is not syntactically well-formed.
Syntactic well-formedness is also checked for attempts to store
geometries into tables.

It is permitted to insert, select, and update geometrically invalid
geometries, but they must be syntactically well-formed.  Due to the
computational expense, MySQL does not check explicitly for geometric
validity.  Spatial computations may detect some cases of invalid
geometries and raise an error, but they may also return an undefined
result without detecting the invalidity.  Applications that require
geometically valid geometries should check them using the 'ST_IsValid()'
function.

11.5.5 Creating Spatial Columns
-------------------------------

MySQL provides a standard way of creating spatial columns for geometry
types, for example, with 'CREATE TABLE' or
'ALTER TABLE'.  Spatial columns are supported for
'MyISAM', 'InnoDB',
'NDB', and 'ARCHIVE'.
tables.  See also the notes about spatial indexes under
creating-spatial-indexes.

   * Use the 'CREATE TABLE' statement to create a
     table with a spatial column:

          CREATE TABLE geom (g GEOMETRY);

   * Use the 'ALTER TABLE' statement to add or drop
     a spatial column to or from an existing table:

          ALTER TABLE geom ADD pt POINT;
          ALTER TABLE geom DROP pt;

11.5.6 Populating Spatial Columns
---------------------------------

After you have created spatial columns, you can populate them with
spatial data.

Values should be stored in internal geometry format, but you can convert
them to that format from either Well-Known Text (WKT) or Well-Known
Binary (WKB) format.  The following examples demonstrate how to insert
geometry values into a table by converting WKT values to internal
geometry format:

   * Perform the conversion directly in the 'INSERT'.
     statement:

          INSERT INTO geom VALUES (ST_GeomFromText('POINT(1 1)'));

          SET @g = 'POINT(1 1)';
          INSERT INTO geom VALUES (ST_GeomFromText(@g));

   * Perform the conversion prior to the 'INSERT'.:

          SET @g = ST_GeomFromText('POINT(1 1)');
          INSERT INTO geom VALUES (@g);

The following examples insert more complex geometries into the table:

     SET @g = 'LINESTRING(0 0,1 1,2 2)';
     INSERT INTO geom VALUES (ST_GeomFromText(@g));

     SET @g = 'POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7, 5 5))';
     INSERT INTO geom VALUES (ST_GeomFromText(@g));

     SET @g =
     'GEOMETRYCOLLECTION(POINT(1 1),LINESTRING(0 0,1 1,2 2,3 3,4 4))';
     INSERT INTO geom VALUES (ST_GeomFromText(@g));

The preceding examples use 'ST_GeomFromText()' to create geometry
values.  You can also use type-specific functions:

     SET @g = 'POINT(1 1)';
     INSERT INTO geom VALUES (ST_PointFromText(@g));

     SET @g = 'LINESTRING(0 0,1 1,2 2)';
     INSERT INTO geom VALUES (ST_LineStringFromText(@g));

     SET @g = 'POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7, 5 5))';
     INSERT INTO geom VALUES (ST_PolygonFromText(@g));

     SET @g =
     'GEOMETRYCOLLECTION(POINT(1 1),LINESTRING(0 0,1 1,2 2,3 3,4 4))';
     INSERT INTO geom VALUES (ST_GeomCollFromText(@g));

A client application program that wants to use WKB representations of
geometry values is responsible for sending correctly formed WKB in
queries to the server.  There are several ways to satisfy this
requirement.  For example:

   * Inserting a 'POINT(1 1)' value with hex literal syntax:

          INSERT INTO geom VALUES
          (ST_GeomFromWKB(X'0101000000000000000000F03F000000000000F03F'));

   * An ODBC application can send a WKB representation, binding it to a
     placeholder using an argument of 'BLOB' type:

          INSERT INTO geom VALUES (ST_GeomFromWKB(?))

     Other programming interfaces may support a similar placeholder
     mechanism.

   * In a C program, you can escape a binary value using
     'mysql_real_escape_string_quote()'.
     and include the result in a query string that is sent to the
     server.  See mysql-real-escape-string-quote.

11.5.7 Fetching Spatial Data
----------------------------

Geometry values stored in a table can be fetched in internal format.
You can also convert them to WKT or WKB format.

   * Fetching spatial data in internal format:

     Fetching geometry values using internal format can be useful in
     table-to-table transfers:

          CREATE TABLE geom2 (g GEOMETRY) SELECT g FROM geom;

   * Fetching spatial data in WKT format:

     The 'ST_AsText()' function converts a geometry from internal format
     to a WKT string.

          SELECT ST_AsText(g) FROM geom;

   * Fetching spatial data in WKB format:

     The 'ST_AsBinary()' function converts a geometry from internal
     format to a 'BLOB' containing the WKB value.

          SELECT ST_AsBinary(g) FROM geom;

11.5.8 Optimizing Spatial Analysis
----------------------------------

For 'MyISAM' and 'InnoDB' tables, search
operations in columns containing spatial data can be optimized using
'SPATIAL' indexes.  The most typical operations are:

   * Point queries that search for all objects that contain a given
     point

   * Region queries that search for all objects that overlap a given
     region

MySQL uses *R-Trees with quadratic splitting* for 'SPATIAL' indexes on
spatial columns.  A 'SPATIAL' index is built using the minimum bounding
rectangle (MBR) of a geometry.  For most geometries, the MBR is a
minimum rectangle that surrounds the geometries.  For a horizontal or a
vertical linestring, the MBR is a rectangle degenerated into the
linestring.  For a point, the MBR is a rectangle degenerated into the
point.

It is also possible to create normal indexes on spatial columns.  In a
non-'SPATIAL' index, you must declare a prefix for any spatial column
except for 'POINT' columns.

'MyISAM' and 'InnoDB' support both 'SPATIAL' and non-'SPATIAL' indexes.
Other storage engines support non-'SPATIAL' indexes, as described in
create-index.

11.5.9 Creating Spatial Indexes
-------------------------------

For 'InnoDB' and 'MyISAM' tables, MySQL can create spatial indexes using
syntax similar to that for creating regular indexes, but using the
'SPATIAL' keyword.  Columns in spatial indexes must be declared 'NOT
NULL'.  The following examples demonstrate how to create spatial
indexes:

   * With 'CREATE TABLE'.:

          CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));

   * With 'ALTER TABLE'.:

          CREATE TABLE geom (g GEOMETRY NOT NULL);
          ALTER TABLE geom ADD SPATIAL INDEX(g);

   * With 'CREATE INDEX'.:

          CREATE TABLE geom (g GEOMETRY NOT NULL);
          CREATE SPATIAL INDEX g ON geom (g);

'SPATIAL INDEX' creates an R-tree index.  For storage engines that
support nonspatial indexing of spatial columns, the engine creates a
B-tree index.  A B-tree index on spatial values is useful for
exact-value lookups, but not for range scans.

For more information on indexing spatial columns, see
create-index.

To drop spatial indexes, use 'ALTER TABLE' or
'DROP INDEX'.:

   * With 'ALTER TABLE'.:

          ALTER TABLE geom DROP INDEX g;

   * With 'DROP INDEX'.:

          DROP INDEX g ON geom;

Example: Suppose that a table 'geom' contains more than 32,000
geometries, which are stored in the column 'g' of type 'GEOMETRY'.  The
table also has an 'AUTO_INCREMENT' column 'fid' for storing object ID
values.

     mysql> DESCRIBE geom;
     +-------+----------+------+-----+---------+----------------+
     | Field | Type     | Null | Key | Default | Extra          |
     +-------+----------+------+-----+---------+----------------+
     | fid   | int(11)  |      | PRI | NULL    | auto_increment |
     | g     | geometry |      |     |         |                |
     +-------+----------+------+-----+---------+----------------+
     2 rows in set (0.00 sec)

     mysql> SELECT COUNT(*) FROM geom;
     +----------+
     | count(*) |
     +----------+
     |    32376 |
     +----------+
     1 row in set (0.00 sec)

To add a spatial index on the column 'g', use this statement:

     mysql> ALTER TABLE geom ADD SPATIAL INDEX(g);
     Query OK, 32376 rows affected (4.05 sec)
     Records: 32376  Duplicates: 0  Warnings: 0

11.5.10 Using Spatial Indexes
-----------------------------

The optimizer investigates whether available spatial indexes can be
involved in the search for queries that use a function such as
'MBRContains()' or 'MBRWithin()' in the 'WHERE' clause.  The following
query finds all objects that are in the given rectangle:

     mysql> SET @poly =
         -> 'Polygon((30000 15000,
                      31000 15000,
                      31000 16000,
                      30000 16000,
                      30000 15000))';
     mysql> SELECT fid,ST_AsText(g) FROM geom WHERE
         -> MBRContains(ST_GeomFromText(@poly),g);
     +-----+---------------------------------------------------------------+
     | fid | ST_AsText(g)                                                  |
     +-----+---------------------------------------------------------------+
     |  21 | LINESTRING(30350.4 15828.8,30350.6 15845,30333.8 15845,30 ... |
     |  22 | LINESTRING(30350.6 15871.4,30350.6 15887.8,30334 15887.8, ... |
     |  23 | LINESTRING(30350.6 15914.2,30350.6 15930.4,30334 15930.4, ... |
     |  24 | LINESTRING(30290.2 15823,30290.2 15839.4,30273.4 15839.4, ... |
     |  25 | LINESTRING(30291.4 15866.2,30291.6 15882.4,30274.8 15882. ... |
     |  26 | LINESTRING(30291.6 15918.2,30291.6 15934.4,30275 15934.4, ... |
     | 249 | LINESTRING(30337.8 15938.6,30337.8 15946.8,30320.4 15946. ... |
     |   1 | LINESTRING(30250.4 15129.2,30248.8 15138.4,30238.2 15136. ... |
     |   2 | LINESTRING(30220.2 15122.8,30217.2 15137.8,30207.6 15136, ... |
     |   3 | LINESTRING(30179 15114.4,30176.6 15129.4,30167 15128,3016 ... |
     |   4 | LINESTRING(30155.2 15121.4,30140.4 15118.6,30142 15109,30 ... |
     |   5 | LINESTRING(30192.4 15085,30177.6 15082.2,30179.2 15072.4, ... |
     |   6 | LINESTRING(30244 15087,30229 15086.2,30229.4 15076.4,3024 ... |
     |   7 | LINESTRING(30200.6 15059.4,30185.6 15058.6,30186 15048.8, ... |
     |  10 | LINESTRING(30179.6 15017.8,30181 15002.8,30190.8 15003.6, ... |
     |  11 | LINESTRING(30154.2 15000.4,30168.6 15004.8,30166 15014.2, ... |
     |  13 | LINESTRING(30105 15065.8,30108.4 15050.8,30118 15053,3011 ... |
     | 154 | LINESTRING(30276.2 15143.8,30261.4 15141,30263 15131.4,30 ... |
     | 155 | LINESTRING(30269.8 15084,30269.4 15093.4,30258.6 15093,30 ... |
     | 157 | LINESTRING(30128.2 15011,30113.2 15010.2,30113.6 15000.4, ... |
     +-----+---------------------------------------------------------------+
     20 rows in set (0.00 sec)

Use 'EXPLAIN' to check the way this query is executed:

     mysql> SET @poly =
         -> 'Polygon((30000 15000,
                      31000 15000,
                      31000 16000,
                      30000 16000,
                      30000 15000))';
     mysql> EXPLAIN SELECT fid,ST_AsText(g) FROM geom WHERE
         -> MBRContains(ST_GeomFromText(@poly),g)\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: geom
              type: range
     possible_keys: g
               key: g
           key_len: 32
               ref: NULL
              rows: 50
             Extra: Using where
     1 row in set (0.00 sec)

Check what would happen without a spatial index:

     mysql> SET @poly =
         -> 'Polygon((30000 15000,
                      31000 15000,
                      31000 16000,
                      30000 16000,
                      30000 15000))';
     mysql> EXPLAIN SELECT fid,ST_AsText(g) FROM g IGNORE INDEX (g) WHERE
         -> MBRContains(ST_GeomFromText(@poly),g)\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: geom
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: 32376
             Extra: Using where
     1 row in set (0.00 sec)

Executing the 'SELECT' statement without the spatial
index yields the same result but causes the execution time to rise from
0.00 seconds to 0.46 seconds:

     mysql> SET @poly =
         -> 'Polygon((30000 15000,
                      31000 15000,
                      31000 16000,
                      30000 16000,
                      30000 15000))';
     mysql> SELECT fid,ST_AsText(g) FROM geom IGNORE INDEX (g) WHERE
         -> MBRContains(ST_GeomFromText(@poly),g);
     +-----+---------------------------------------------------------------+
     | fid | ST_AsText(g)                                                  |
     +-----+---------------------------------------------------------------+
     |   1 | LINESTRING(30250.4 15129.2,30248.8 15138.4,30238.2 15136. ... |
     |   2 | LINESTRING(30220.2 15122.8,30217.2 15137.8,30207.6 15136, ... |
     |   3 | LINESTRING(30179 15114.4,30176.6 15129.4,30167 15128,3016 ... |
     |   4 | LINESTRING(30155.2 15121.4,30140.4 15118.6,30142 15109,30 ... |
     |   5 | LINESTRING(30192.4 15085,30177.6 15082.2,30179.2 15072.4, ... |
     |   6 | LINESTRING(30244 15087,30229 15086.2,30229.4 15076.4,3024 ... |
     |   7 | LINESTRING(30200.6 15059.4,30185.6 15058.6,30186 15048.8, ... |
     |  10 | LINESTRING(30179.6 15017.8,30181 15002.8,30190.8 15003.6, ... |
     |  11 | LINESTRING(30154.2 15000.4,30168.6 15004.8,30166 15014.2, ... |
     |  13 | LINESTRING(30105 15065.8,30108.4 15050.8,30118 15053,3011 ... |
     |  21 | LINESTRING(30350.4 15828.8,30350.6 15845,30333.8 15845,30 ... |
     |  22 | LINESTRING(30350.6 15871.4,30350.6 15887.8,30334 15887.8, ... |
     |  23 | LINESTRING(30350.6 15914.2,30350.6 15930.4,30334 15930.4, ... |
     |  24 | LINESTRING(30290.2 15823,30290.2 15839.4,30273.4 15839.4, ... |
     |  25 | LINESTRING(30291.4 15866.2,30291.6 15882.4,30274.8 15882. ... |
     |  26 | LINESTRING(30291.6 15918.2,30291.6 15934.4,30275 15934.4, ... |
     | 154 | LINESTRING(30276.2 15143.8,30261.4 15141,30263 15131.4,30 ... |
     | 155 | LINESTRING(30269.8 15084,30269.4 15093.4,30258.6 15093,30 ... |
     | 157 | LINESTRING(30128.2 15011,30113.2 15010.2,30113.6 15000.4, ... |
     | 249 | LINESTRING(30337.8 15938.6,30337.8 15946.8,30320.4 15946. ... |
     +-----+---------------------------------------------------------------+
     20 rows in set (0.46 sec)

11.6 The JSON Data Type
=======================

   * json-values

   * json-normalization

   * json-paths

   * json-comparison

   * json-converting-between-types

   * json-aggregation

As of MySQL 5.7.8, MySQL supports a native 'JSON' data type defined by
RFC 7159 (https://tools.ietf.org/html/rfc7159) that enables efficient
access to data in JSON (JavaScript Object Notation) documents.  The
'JSON' data type provides these advantages over storing JSON-format
strings in a string column:

   * Automatic validation of JSON documents stored in 'JSON' columns.
     Invalid documents produce an error.

   * Optimized storage format.  JSON documents stored in 'JSON' columns
     are converted to an internal format that permits quick read access
     to document elements.  When the server later must read a JSON value
     stored in this binary format, the value need not be parsed from a
     text representation.  The binary format is structured to enable the
     server to look up subobjects or nested values directly by key or
     array index without reading all values before or after them in the
     document.

*Note*:

This discussion uses 'JSON' in monotype to indicate specifically the
JSON data type and 'JSON' in regular font to indicate JSON data in
general.

The space required to store a 'JSON' document is roughly the same as for
'LONGBLOB' or 'LONGTEXT'.; see
storage-requirements, for more information.  It is important to keep
in mind that the size of any JSON document stored in a 'JSON' column is
limited to the value of the 'max_allowed_packet' system variable.  (When
the server is manipulating a JSON value internally in memory, it can be
larger than this; the limit applies when the server stores it.)

A 'JSON' column cannot have a default value.

Along with the 'JSON' data type, a set of SQL functions is available to
enable operations on JSON values, such as creation, manipulation, and
searching.  The following discussion shows examples of these operations.
For details about individual functions, see json-functions.

A set of spatial functions for operating on GeoJSON values is also
available.  See spatial-geojson-functions.

'JSON' columns, like columns of other binary types, are not indexed
directly; instead, you can create an index on a generated column that
extracts a scalar value from the 'JSON' column.  See
json-column-indirect-index, for a detailed example.

The MySQL optimizer also looks for compatible indexes on virtual columns
that match JSON expressions.

MySQL NDB Cluster 7.5 (7.5.2 and later) supports 'JSON' columns and
MySQL JSON functions, including creation of an index on a column
generated from a 'JSON' column as a workaround for being unable to index
a 'JSON' column.  A maximum of 3 'JSON' columns per 'NDB'
table is supported.

The next few sections provide basic information regarding the creation
and manipulation of JSON values.

*Creating JSON Values*

A JSON array contains a list of values separated by commas and enclosed
within '[' and ']' characters:

     ["abc", 10, null, true, false]

A JSON object contains a set of key-value pairs separated by commas and
enclosed within '{' and '}' characters:

     {"k1": "value", "k2": 10}

As the examples illustrate, JSON arrays and objects can contain scalar
values that are strings or numbers, the JSON null literal, or the JSON
boolean true or false literals.  Keys in JSON objects must be strings.
Temporal (date, time, or datetime) scalar values are also permitted:

     ["12:18:29.000000", "2015-07-29", "2015-07-29 12:18:29.000000"]

Nesting is permitted within JSON array elements and JSON object key
values:

     [99, {"id": "HK500", "cost": 75.99}, ["hot", "cold"]]
     {"k1": "value", "k2": [10, 20]}

You can also obtain JSON values from a number of functions supplied by
MySQL for this purpose (see json-creation-functions) as well as
by casting values of other types to the 'JSON' type using 'CAST(VALUE AS
JSON)' (see json-converting-between-types).  The next several
paragraphs describe how MySQL handles JSON values provided as input.

In MySQL, JSON values are written as strings.  MySQL parses any string
used in a context that requires a JSON value, and produces an error if
it is not valid as JSON. These contexts include inserting a value into a
column that has the 'JSON' data type and passing an argument to a
function that expects a JSON value (usually shown as JSON_DOC or
JSON_VAL in the documentation for MySQL JSON functions), as the
following examples demonstrate:

   * Attempting to insert a value into a 'JSON' column succeeds if the
     value is a valid JSON value, but fails if it is not:

          mysql> CREATE TABLE t1 (jdoc JSON);
          Query OK, 0 rows affected (0.20 sec)

          mysql> INSERT INTO t1 VALUES('{"key1": "value1", "key2": "value2"}');
          Query OK, 1 row affected (0.01 sec)

          mysql> INSERT INTO t1 VALUES('[1, 2,');
          ERROR 3140 (22032) at line 2: Invalid JSON text:
          "Invalid value." at position 6 in value (or column) '[1, 2,'.

     Positions for 'at position N' in such error messages are 0-based,
     but should be considered rough indications of where the problem in
     a value actually occurs.

   * The 'JSON_TYPE()' function expects a JSON argument and attempts to
     parse it into a JSON value.  It returns the value's JSON type if it
     is valid and produces an error otherwise:

          mysql> SELECT JSON_TYPE('["a", "b", 1]');
          +----------------------------+
          | JSON_TYPE('["a", "b", 1]') |
          +----------------------------+
          | ARRAY                      |
          +----------------------------+

          mysql> SELECT JSON_TYPE('"hello"');
          +----------------------+
          | JSON_TYPE('"hello"') |
          +----------------------+
          | STRING               |
          +----------------------+

          mysql> SELECT JSON_TYPE('hello');
          ERROR 3146 (22032): Invalid data type for JSON data in argument 1
          to function json_type; a JSON string or JSON type is required.

MySQL handles strings used in JSON context using the 'utf8mb4' character
set and 'utf8mb4_bin' collation.  Strings in other character sets are
converted to 'utf8mb4' as necessary.  (For strings in the 'ascii' or
'utf8' character sets, no conversion is needed because 'ascii' and
'utf8' are subsets of 'utf8mb4'.)

As an alternative to writing JSON values using literal strings,
functions exist for composing JSON values from component elements.
'JSON_ARRAY()' takes a (possibly empty) list of values and returns a
JSON array containing those values:

     mysql> SELECT JSON_ARRAY('a', 1, NOW());
     +----------------------------------------+
     | JSON_ARRAY('a', 1, NOW())              |
     +----------------------------------------+
     | ["a", 1, "2015-07-27 09:43:47.000000"] |
     +----------------------------------------+

'JSON_OBJECT()' takes a (possibly empty) list of key-value pairs and
returns a JSON object containing those pairs:

     mysql> SELECT JSON_OBJECT('key1', 1, 'key2', 'abc');
     +---------------------------------------+
     | JSON_OBJECT('key1', 1, 'key2', 'abc') |
     +---------------------------------------+
     | {"key1": 1, "key2": "abc"}            |
     +---------------------------------------+

'JSON_MERGE()' takes two or more JSON documents and returns the combined
result:

     mysql> SELECT JSON_MERGE('["a", 1]', '{"key": "value"}');
     +--------------------------------------------+
     | JSON_MERGE('["a", 1]', '{"key": "value"}') |
     +--------------------------------------------+
     | ["a", 1, {"key": "value"}]                 |
     +--------------------------------------------+

For information about the merging rules, see json-normalization.

JSON values can be assigned to user-defined variables:

     mysql> SET @j = JSON_OBJECT('key', 'value');
     mysql> SELECT @j;
     +------------------+
     | @j               |
     +------------------+
     | {"key": "value"} |
     +------------------+

However, user-defined variables cannot be of 'JSON' data type, so
although '@j' in the preceding example looks like a JSON value and has
the same character set and collation as a JSON value, it does _not_ have
the 'JSON' data type.  Instead, the result from 'JSON_OBJECT()' is
converted to a string when assigned to the variable.

Strings produced by converting JSON values have a character set of
'utf8mb4' and a collation of 'utf8mb4_bin':

     mysql> SELECT CHARSET(@j), COLLATION(@j);
     +-------------+---------------+
     | CHARSET(@j) | COLLATION(@j) |
     +-------------+---------------+
     | utf8mb4     | utf8mb4_bin   |
     +-------------+---------------+

Because 'utf8mb4_bin' is a binary collation, comparison of JSON values
is case-sensitive.

     mysql> SELECT JSON_ARRAY('x') = JSON_ARRAY('X');
     +-----------------------------------+
     | JSON_ARRAY('x') = JSON_ARRAY('X') |
     +-----------------------------------+
     |                                 0 |
     +-----------------------------------+

Case sensitivity also applies to the JSON 'null', 'true', and 'false'
literals, which always must be written in lowercase:

     mysql> SELECT JSON_VALID('null'), JSON_VALID('Null'), JSON_VALID('NULL');
     +--------------------+--------------------+--------------------+
     | JSON_VALID('null') | JSON_VALID('Null') | JSON_VALID('NULL') |
     +--------------------+--------------------+--------------------+
     |                  1 |                  0 |                  0 |
     +--------------------+--------------------+--------------------+

     mysql> SELECT CAST('null' AS JSON);
     +----------------------+
     | CAST('null' AS JSON) |
     +----------------------+
     | null                 |
     +----------------------+
     1 row in set (0.00 sec)

     mysql> SELECT CAST('NULL' AS JSON);
     ERROR 3141 (22032): Invalid JSON text in argument 1 to function cast_as_json:
     "Invalid value." at position 0 in 'NULL'.

Case sensitivity of the JSON literals differs from that of the SQL
'NULL', 'TRUE', and 'FALSE' literals, which can be written in any
lettercase:

     mysql> SELECT ISNULL(null), ISNULL(Null), ISNULL(NULL);
     +--------------+--------------+--------------+
     | ISNULL(null) | ISNULL(Null) | ISNULL(NULL) |
     +--------------+--------------+--------------+
     |            1 |            1 |            1 |
     +--------------+--------------+--------------+

Sometimes it may be necessary or desirable to insert quote characters
('"' or ''') into a JSON document.  Assume for this example that you
want to insert some JSON objects containing strings representing
sentences that state some facts about MySQL, each paired with an
appropriate keyword, into a table created using the SQL statement shown
here:

     mysql> CREATE TABLE facts (sentence JSON);

Among these keyword-sentence pairs is this one:

     mascot: The MySQL mascot is a dolphin named "Sakila".

One way to insert this as a JSON object into the 'facts' table is to use
the MySQL 'JSON_OBJECT()' function.  In this case, you must escape each
quote character using a backslash, as shown here:

     mysql> INSERT INTO facts VALUES
          >   (JSON_OBJECT("mascot", "Our mascot is a dolphin named \"Sakila\"."));

This does not work in the same way if you insert the value as a JSON
object literal, in which case, you must use the double backslash escape
sequence, like this:

     mysql> INSERT INTO facts VALUES
          >   ('{"mascot": "Our mascot is a dolphin named \\"Sakila\\"."}');

Using the double backslash keeps MySQL from performing escape sequence
processing, and instead causes it to pass the string literal to the
storage engine for processing.  After inserting the JSON object in
either of the ways just shown, you can see that the backslashes are
present in the JSON column value by doing a simple 'SELECT',
like this:

     mysql> SELECT sentence FROM facts;
     +---------------------------------------------------------+
     | sentence                                                |
     +---------------------------------------------------------+
     | {"mascot": "Our mascot is a dolphin named \"Sakila\"."} |
     +---------------------------------------------------------+

To look up this particular sentence employing 'mascot' as the key, you
can use the column-path operator '->', as shown here:

     mysql> SELECT col->"$.mascot" FROM qtest;
     +---------------------------------------------+
     | col->"$.mascot"                             |
     +---------------------------------------------+
     | "Our mascot is a dolphin named \"Sakila\"." |
     +---------------------------------------------+
     1 row in set (0.00 sec)

This leaves the backslashes intact, along with the surrounding quote
marks.  To display the desired value using 'mascot' as the key, but
without including the surrounding quote marks or any escapes, use the
inline path operator '->>', like this:

     mysql> SELECT sentence->>"$.mascot" FROM facts;
     +-----------------------------------------+
     | sentence->>"$.mascot"                   |
     +-----------------------------------------+
     | Our mascot is a dolphin named "Sakila". |
     +-----------------------------------------+

*Note*:

The previous example does not work as shown if the
'NO_BACKSLASH_ESCAPES' server SQL mode is enabled.  If this mode is set,
a single backslash instead of double backslashes can be used to insert
the JSON object literal, and the backslashes are preserved.  If you use
the 'JSON_OBJECT()' function when performing the insert and this mode is
set, you must alternate single and double quotes, like this:

     mysql> INSERT INTO facts VALUES
          > (JSON_OBJECT('mascot', 'Our mascot is a dolphin named "Sakila".'));

See the description of the 'JSON_UNQUOTE()' function for more
information about the effects of this mode on escaped characters in JSON
values.

*Normalization, Merging, and Autowrapping of JSON Values*

When a string is parsed and found to be a valid JSON document, it is
also normalized: Members with keys that duplicate a key found earlier in
the document are discarded (even if the values differ).  The object
value produced by the following 'JSON_OBJECT()' call does not include
the second 'key1' element because that key name occurs earlier in the
value:

     mysql> SELECT JSON_OBJECT('key1', 1, 'key2', 'abc', 'key1', 'def');
     +------------------------------------------------------+
     | JSON_OBJECT('key1', 1, 'key2', 'abc', 'key1', 'def') |
     +------------------------------------------------------+
     | {"key1": 1, "key2": "abc"}                           |
     +------------------------------------------------------+

*Note*:

This 'first key wins' handling of duplicate keys is not consistent with
RFC 7159 (https://tools.ietf.org/html/rfc7159).  This is a known issue
in MySQL 5.7, which is fixed in MySQL 8.0.  (Bug #86866, Bug #26369555)

MySQL also discards extra whitespace between keys, values, or elements
in the original JSON document.  To make lookups more efficient, it also
sorts the keys of a JSON object.  _You should be aware that the result
of this ordering is subject to change and not guaranteed to be
consistent across releases._

MySQL functions that produce JSON values (see
json-creation-functions) always return normalized values.

*Merging JSON Values*

In contexts that combine multiple arrays, the arrays are merged into a
single array by concatenating arrays named later to the end of the first
array.  In the following example, 'JSON_MERGE()' merges its arguments
into a single array:

     mysql> SELECT JSON_MERGE('[1, 2]', '["a", "b"]', '[true, false]');
     +-----------------------------------------------------+
     | JSON_MERGE('[1, 2]', '["a", "b"]', '[true, false]') |
     +-----------------------------------------------------+
     | [1, 2, "a", "b", true, false]                       |
     +-----------------------------------------------------+

Normalization is also performed when values are inserted into JSON
columns, as shown here:

     mysql> CREATE TABLE t1 (c1 JSON);

     mysql> INSERT INTO t1 VALUES
          >     ('{"x": 17, "x": "red"}'),
          >     ('{"x": 17, "x": "red", "x": [3, 5, 7]}');

     mysql> SELECT c1 FROM t1;
     +-----------+
     | c1        |
     +-----------+
     | {"x": 17} |
     | {"x": 17} |
     +-----------+

Multiple objects when merged produce a single object.  If multiple
objects have the same key, the value for that key in the resulting
merged object is an array containing the key values:

     mysql> SELECT JSON_MERGE('{"a": 1, "b": 2}', '{"c": 3, "a": 4}');
     +----------------------------------------------------+
     | JSON_MERGE('{"a": 1, "b": 2}', '{"c": 3, "a": 4}') |
     +----------------------------------------------------+
     | {"a": [1, 4], "b": 2, "c": 3}                      |
     +----------------------------------------------------+

Nonarray values used in a context that requires an array value are
autowrapped: The value is surrounded by '[' and ']' characters to
convert it to an array.  In the following statement, each argument is
autowrapped as an array ('[1]', '[2]').  These are then merged to
produce a single result array:

     mysql> SELECT JSON_MERGE('1', '2');
     +----------------------+
     | JSON_MERGE('1', '2') |
     +----------------------+
     | [1, 2]               |
     +----------------------+

Array and object values are merged by autowrapping the object as an
array and merging the two arrays:

     mysql> SELECT JSON_MERGE('[10, 20]', '{"a": "x", "b": "y"}');
     +------------------------------------------------+
     | JSON_MERGE('[10, 20]', '{"a": "x", "b": "y"}') |
     +------------------------------------------------+
     | [10, 20, {"a": "x", "b": "y"}]                 |
     +------------------------------------------------+

*Searching and Modifying JSON Values*

A JSON path expression selects a value within a JSON document.

Path expressions are useful with functions that extract parts of or
modify a JSON document, to specify where within that document to
operate.  For example, the following query extracts from a JSON document
the value of the member with the 'name' key:

     mysql> SELECT JSON_EXTRACT('{"id": 14, "name": "Aztalan"}', '$.name');
     +---------------------------------------------------------+
     | JSON_EXTRACT('{"id": 14, "name": "Aztalan"}', '$.name') |
     +---------------------------------------------------------+
     | "Aztalan"                                               |
     +---------------------------------------------------------+

Path syntax uses a leading '$' character to represent the JSON document
under consideration, optionally followed by selectors that indicate
successively more specific parts of the document:

   * A period followed by a key name names the member in an object with
     the given key.  The key name must be specified within double
     quotation marks if the name without quotes is not legal within path
     expressions (for example, if it contains a space).

   * '[N]' appended to a PATH that selects an array names the value at
     position N within the array.  Array positions are integers
     beginning with zero.  If PATH does not select an array value,
     PATH[0] evaluates to the same value as PATH:

          mysql> SELECT JSON_SET('"x"', '$[0]', 'a');
          +------------------------------+
          | JSON_SET('"x"', '$[0]', 'a') |
          +------------------------------+
          | "a"                          |
          +------------------------------+
          1 row in set (0.00 sec)

   * Paths can contain '*' or '**' wildcards:

        * '.[*]' evaluates to the values of all members in a JSON
          object.

        * '[*]' evaluates to the values of all elements in a JSON array.

        * 'PREFIX**SUFFIX' evaluates to all paths that begin with the
          named prefix and end with the named suffix.

   * A path that does not exist in the document (evaluates to
     nonexistent data) evaluates to 'NULL'.

Let '$' refer to this JSON array with three elements:

     [3, {"a": [5, 6], "b": 10}, [99, 100]]

Then:

   * '$[0]' evaluates to '3'.

   * '$[1]' evaluates to '{"a": [5, 6], "b": 10}'.

   * '$[2]' evaluates to '[99, 100]'.

   * '$[3]' evaluates to 'NULL' (it refers to the fourth array element,
     which does not exist).

Because '$[1]' and '$[2]' evaluate to nonscalar values, they can be used
as the basis for more-specific path expressions that select nested
values.  Examples:

   * '$[1].a' evaluates to '[5, 6]'.

   * '$[1].a[1]' evaluates to '6'.

   * '$[1].b' evaluates to '10'.

   * '$[2][0]' evaluates to '99'.

As mentioned previously, path components that name keys must be quoted
if the unquoted key name is not legal in path expressions.  Let '$'
refer to this value:

     {"a fish": "shark", "a bird": "sparrow"}

The keys both contain a space and must be quoted:

   * '$."a fish"' evaluates to 'shark'.

   * '$."a bird"' evaluates to 'sparrow'.

Paths that use wildcards evaluate to an array that can contain multiple
values:

     mysql> SELECT JSON_EXTRACT('{"a": 1, "b": 2, "c": [3, 4, 5]}', '$.*');
     +---------------------------------------------------------+
     | JSON_EXTRACT('{"a": 1, "b": 2, "c": [3, 4, 5]}', '$.*') |
     +---------------------------------------------------------+
     | [1, 2, [3, 4, 5]]                                       |
     +---------------------------------------------------------+
     mysql> SELECT JSON_EXTRACT('{"a": 1, "b": 2, "c": [3, 4, 5]}', '$.c[*]');
     +------------------------------------------------------------+
     | JSON_EXTRACT('{"a": 1, "b": 2, "c": [3, 4, 5]}', '$.c[*]') |
     +------------------------------------------------------------+
     | [3, 4, 5]                                                  |
     +------------------------------------------------------------+

In the following example, the path '$**.b' evaluates to multiple paths
('$.a.b' and '$.c.b') and produces an array of the matching path values:

     mysql> SELECT JSON_EXTRACT('{"a": {"b": 1}, "c": {"b": 2}}', '$**.b');
     +---------------------------------------------------------+
     | JSON_EXTRACT('{"a": {"b": 1}, "c": {"b": 2}}', '$**.b') |
     +---------------------------------------------------------+
     | [1, 2]                                                  |
     +---------------------------------------------------------+

In MySQL 5.7.9 and later, you can use 'COLUMN->PATH' with a JSON column
identifier and JSON path expression as a synonym for
'JSON_EXTRACT(COLUMN, PATH)'.  See json-search-functions, for
more information.  See also json-column-indirect-index.

Some functions take an existing JSON document, modify it in some way,
and return the resulting modified document.  Path expressions indicate
where in the document to make changes.  For example, the 'JSON_SET()',
'JSON_INSERT()', and 'JSON_REPLACE()' functions each take a JSON
document, plus one or more path/value pairs that describe where to
modify the document and the values to use.  The functions differ in how
they handle existing and nonexisting values within the document.

Consider this document:

     mysql> SET @j = '["a", {"b": [true, false]}, [10, 20]]';

'JSON_SET()' replaces values for paths that exist and adds values for
paths that do not exist:.

     mysql> SELECT JSON_SET(@j, '$[1].b[0]', 1, '$[2][2]', 2);
     +--------------------------------------------+
     | JSON_SET(@j, '$[1].b[0]', 1, '$[2][2]', 2) |
     +--------------------------------------------+
     | ["a", {"b": [1, false]}, [10, 20, 2]]      |
     +--------------------------------------------+

In this case, the path '$[1].b[0]' selects an existing value ('true'),
which is replaced with the value following the path argument ('1').  The
path '$[2][2]' does not exist, so the corresponding value ('2') is added
to the value selected by '$[2]'.

'JSON_INSERT()' adds new values but does not replace existing values:

     mysql> SELECT JSON_INSERT(@j, '$[1].b[0]', 1, '$[2][2]', 2);
     +-----------------------------------------------+
     | JSON_INSERT(@j, '$[1].b[0]', 1, '$[2][2]', 2) |
     +-----------------------------------------------+
     | ["a", {"b": [true, false]}, [10, 20, 2]]      |
     +-----------------------------------------------+

'JSON_REPLACE()' replaces existing values and ignores new values:

     mysql> SELECT JSON_REPLACE(@j, '$[1].b[0]', 1, '$[2][2]', 2);
     +------------------------------------------------+
     | JSON_REPLACE(@j, '$[1].b[0]', 1, '$[2][2]', 2) |
     +------------------------------------------------+
     | ["a", {"b": [1, false]}, [10, 20]]             |
     +------------------------------------------------+

The path/value pairs are evaluated left to right.  The document produced
by evaluating one pair becomes the new value against which the next pair
is evaluated.

'JSON_REMOVE()' takes a JSON document and one or more paths that specify
values to be removed from the document.  The return value is the
original document minus the values selected by paths that exist within
the document:

     mysql> SELECT JSON_REMOVE(@j, '$[2]', '$[1].b[1]', '$[1].b[1]');
     +---------------------------------------------------+
     | JSON_REMOVE(@j, '$[2]', '$[1].b[1]', '$[1].b[1]') |
     +---------------------------------------------------+
     | ["a", {"b": [true]}]                              |
     +---------------------------------------------------+

The paths have these effects:

   * '$[2]' matches '[10, 20]' and removes it.

   * The first instance of '$[1].b[1]' matches 'false' in the 'b'
     element and removes it.

   * The second instance of '$[1].b[1]' matches nothing: That element
     has already been removed, the path no longer exists, and has no
     effect.

*Comparison and Ordering of JSON Values*

JSON values can be compared using the '=', '<', '<=', '>', '>=', '<>',
'!=', and '<=>' operators.

The following comparison operators and functions are not yet supported
with JSON values:

   * 'BETWEEN'

   * 'IN()'

   * 'GREATEST()'

   * 'LEAST()'

A workaround for the comparison operators and functions just listed is
to cast JSON values to a native MySQL numeric or string data type so
they have a consistent non-JSON scalar type.

Comparison of JSON values takes place at two levels.  The first level of
comparison is based on the JSON types of the compared values.  If the
types differ, the comparison result is determined solely by which type
has higher precedence.  If the two values have the same JSON type, a
second level of comparison occurs using type-specific rules.

The following list shows the precedences of JSON types, from highest
precedence to the lowest.  (The type names are those returned by the
'JSON_TYPE()' function.)  Types shown together on a line have the same
precedence.  Any value having a JSON type listed earlier in the list
compares greater than any value having a JSON type listed later in the
list.

     BLOB
     BIT
     OPAQUE
     DATETIME
     TIME
     DATE
     BOOLEAN
     ARRAY
     OBJECT
     STRING
     INTEGER, DOUBLE
     NULL

For JSON values of the same precedence, the comparison rules are type
specific:

   * 'BLOB'

     The first N bytes of the two values are compared, where N is the
     number of bytes in the shorter value.  If the first N bytes of the
     two values are identical, the shorter value is ordered before the
     longer value.

   * 'BIT'

     Same rules as for 'BLOB'.

   * 'OPAQUE'

     Same rules as for 'BLOB'.  'OPAQUE' values are values that are not
     classified as one of the other types.

   * 'DATETIME'

     A value that represents an earlier point in time is ordered before
     a value that represents a later point in time.  If two values
     originally come from the MySQL 'DATETIME' and 'TIMESTAMP' types,
     respectively, they are equal if they represent the same point in
     time.

   * 'TIME'

     The smaller of two time values is ordered before the larger one.

   * 'DATE'

     The earlier date is ordered before the more recent date.

   * 'ARRAY'

     Two JSON arrays are equal if they have the same length and values
     in corresponding positions in the arrays are equal.

     If the arrays are not equal, their order is determined by the
     elements in the first position where there is a difference.  The
     array with the smaller value in that position is ordered first.  If
     all values of the shorter array are equal to the corresponding
     values in the longer array, the shorter array is ordered first.

     Example:

          [] < ["a"] < ["ab"] < ["ab", "cd", "ef"] < ["ab", "ef"]

   * 'BOOLEAN'

     The JSON false literal is less than the JSON true literal.

   * 'OBJECT'

     Two JSON objects are equal if they have the same set of keys, and
     each key has the same value in both objects.

     Example:

          {"a": 1, "b": 2} = {"b": 2, "a": 1}

     The order of two objects that are not equal is unspecified but
     deterministic.

   * 'STRING'

     Strings are ordered lexically on the first N bytes of the 'utf8mb4'
     representation of the two strings being compared, where N is the
     length of the shorter string.  If the first N bytes of the two
     strings are identical, the shorter string is considered smaller
     than the longer string.

     Example:

          "a" < "ab" < "b" < "bc"

     This ordering is equivalent to the ordering of SQL strings with
     collation 'utf8mb4_bin'.  Because 'utf8mb4_bin' is a binary
     collation, comparison of JSON values is case-sensitive:

          "A" < "a"

   * 'INTEGER', 'DOUBLE'

     JSON values can contain exact-value numbers and approximate-value
     numbers.  For a general discussion of these types of numbers, see
     number-literals.

     The rules for comparing native MySQL numeric types are discussed in
     type-conversion, but the rules for comparing numbers within
     JSON values differ somewhat:

        * In a comparison between two columns that use the native MySQL
          'INT' and 'DOUBLE'
          numeric types, respectively, it is known
          that all comparisons involve an integer and a double, so the
          integer is converted to double for all rows.  That is,
          exact-value numbers are converted to approximate-value
          numbers.

        * On the other hand, if the query compares two JSON columns
          containing numbers, it cannot be known in advance whether
          numbers will be integer or double.  To provide the most
          consistent behavior across all rows, MySQL converts
          approximate-value numbers to exact-value numbers.  The
          resulting ordering is consistent and does not lose precision
          for the exact-value numbers.  For example, given the scalars
          9223372036854775805, 9223372036854775806, 9223372036854775807
          and 9.223372036854776e18, the order is such as this:

               9223372036854775805 < 9223372036854775806 < 9223372036854775807
               < 9.223372036854776e18 = 9223372036854776000 < 9223372036854776001

     Were JSON comparisons to use the non-JSON numeric comparison rules,
     inconsistent ordering could occur.  The usual MySQL comparison
     rules for numbers yield these orderings:

        * Integer comparison:

               9223372036854775805 < 9223372036854775806 < 9223372036854775807

          (not defined for 9.223372036854776e18)

        * Double comparison:

               9223372036854775805 = 9223372036854775806 = 9223372036854775807 = 9.223372036854776e18

For comparison of any JSON value to SQL 'NULL', the result is 'UNKNOWN'.

For comparison of JSON and non-JSON values, the non-JSON value is
converted to JSON according to the rules in the following table, then
the values compared as described previously.

*Converting between JSON and non-JSON values*

The following table provides a summary of the rules that MySQL follows
when casting between JSON values and values of other types:

*JSON Conversion Rules*

other type     CAST(other type AS JSON)      CAST(JSON AS other type)

JSON           No change                     No change

utf8           The string is parsed into a   The JSON value is
character      JSON value.                   serialized into a 'utf8mb4'
type                                         string.
('utf8mb4',
'utf8',
'ascii')

Other          Other character encodings     The JSON value is
character      are implicitly converted to   serialized into a 'utf8mb4'
types          'utf8mb4' and treated as      string, then cast to the
               described for utf8            other character encoding.
               character type.               The result may not be
                                             meaningful.

'NULL'         Results in a 'NULL' value     Not applicable.
               of type JSON.

Geometry       The geometry value is         Illegal operation.
types          converted into a JSON         Workaround: Pass the result
               document by calling           of 'CAST(JSON_VAL AS CHAR)'
               'ST_AsGeoJSON()'.             to 'ST_GeomFromGeoJSON()'.

All other      Results in a JSON document    Succeeds if the JSON
types          consisting of a single        document consists of a
               scalar value.                 single scalar value of the
                                             target type and that scalar
                                             value can be cast to the
                                             target type.  Otherwise,
                                             returns 'NULL' and produces
                                             a warning.

'ORDER BY' and 'GROUP BY' for JSON values works according to these
principles:

   * Ordering of scalar JSON values uses the same rules as in the
     preceding discussion.

   * For ascending sorts, SQL 'NULL' orders before all JSON values,
     including the JSON null literal; for descending sorts, SQL 'NULL'
     orders after all JSON values, including the JSON null literal.

   * Sort keys for JSON values are bound by the value of the
     'max_sort_length' system variable, so keys that differ only after
     the first 'max_sort_length' bytes compare as equal.

   * Sorting of nonscalar values is not currently supported and a
     warning occurs.

For sorting, it can be beneficial to cast a JSON scalar to some other
native MySQL type.  For example, if a column named 'jdoc' contains JSON
objects having a member consisting of an 'id' key and a nonnegative
value, use this expression to sort by 'id' values:

     ORDER BY CAST(JSON_EXTRACT(jdoc, '$.id') AS UNSIGNED)

If there happens to be a generated column defined to use the same
expression as in the 'ORDER BY', the MySQL optimizer recognizes that and
considers using the index for the query execution plan.  See
generated-column-index-optimizations.

*Aggregation of JSON Values*

For aggregation of JSON values, SQL 'NULL' values are ignored as for
other data types.  Non-'NULL' values are converted to a numeric type and
aggregated, except for 'MIN()', 'MAX()', and 'GROUP_CONCAT()'.  The
conversion to number should produce a meaningful result for JSON values
that are numeric scalars, although (depending on the values) truncation
and loss of precision may occur.  Conversion to number of other JSON
values may not produce a meaningful result.

11.7 Data Type Default Values
=============================

The 'DEFAULT VALUE' clause in a data type specification indicates a
default value for a column.  With one exception, the default value must
be a constant; it cannot be a function or an expression.  This means,
for example, that you cannot set the default for a date column to be the
value of a function such as 'NOW()' or 'CURRENT_DATE'.  The exception is
that you can specify 'CURRENT_TIMESTAMP' as the default for
'TIMESTAMP' and 'DATETIME' columns.  See
timestamp-initialization.

See 'BLOB', 'TEXT', 'GEOMETRY', and 'JSON'
columns cannot be assigned a default value.

If a column definition includes no explicit 'DEFAULT' value, MySQL
determines the default value as follows:

If the column can take 'NULL' as a value, the column is defined with an
explicit 'DEFAULT NULL' clause.

If the column cannot take 'NULL' as the value, MySQL defines the column
with no explicit 'DEFAULT' clause.  Exception: If the column is defined
as part of a 'PRIMARY KEY' but not explicitly as 'NOT NULL', MySQL
creates it as a 'NOT NULL' column (because 'PRIMARY KEY' columns must be
'NOT NULL').  Before MySQL 5.7.3, the column is also assigned a
'DEFAULT' clause using the implicit default value.  To prevent this,
include an explicit 'NOT NULL' in the definition of any 'PRIMARY KEY'
column.

For data entry into a 'NOT NULL' column that has no explicit 'DEFAULT'
clause, if an 'INSERT' or 'REPLACE'.
statement includes no value for the column, or an 'UPDATE'
statement sets the column to 'NULL', MySQL handles the column
according to the SQL mode in effect at the time:

   * If strict SQL mode is enabled, an error occurs for transactional
     tables and the statement is rolled back.  For nontransactional
     tables, an error occurs, but if this happens for the second or
     subsequent row of a multiple-row statement, the preceding rows will
     have been inserted.

   * If strict mode is not enabled, MySQL sets the column to the
     implicit default value for the column data type.

Suppose that a table 't' is defined as follows:

     CREATE TABLE t (i INT NOT NULL);

In this case, 'i' has no explicit default, so in strict mode each of the
following statements produce an error and no row is inserted.  When not
using strict mode, only the third statement produces an error; the
implicit default is inserted for the first two statements, but the third
fails because 'DEFAULT(i)' cannot produce a value:

     INSERT INTO t VALUES();
     INSERT INTO t VALUES(DEFAULT);
     INSERT INTO t VALUES(DEFAULT(i));

See sql-mode.

For a given table, you can use the 'SHOW CREATE TABLE'
statement to see which columns have an explicit
'DEFAULT' clause.

Implicit defaults are defined as follows:

   * For numeric types, the default is '0', with the exception that for
     integer or floating-point types declared with the 'AUTO_INCREMENT'
     attribute, the default is the next value in the sequence.

   * For date and time types other than 'TIMESTAMP', the
     default is the appropriate 'zero' value for the type.  This is also
     true for 'TIMESTAMP' if the
     'explicit_defaults_for_timestamp' system variable is enabled (see
     server-system-variables).  Otherwise, for the first
     'TIMESTAMP' column in a table, the default value is the
     current date and time.  See date-and-time-types.

   * For string types other than 'ENUM', the default value
     is the empty string.  For 'ENUM', the default is the
     first enumeration value.

'SERIAL DEFAULT VALUE' in the definition of an integer column is an
alias for 'NOT NULL AUTO_INCREMENT UNIQUE'.

11.8 Data Type Storage Requirements
===================================

   * data-types-storage-reqs-innodb

   * data-types-storage-reqs-ndb

   * data-types-storage-reqs-numeric

   * data-types-storage-reqs-date-time

   * data-types-storage-reqs-strings

   * data-types-storage-reqs-gis

   * data-types-storage-reqs-json

The storage requirements for table data on disk depend on several
factors.  Different storage engines represent data types and store raw
data differently.  Table data might be compressed, either for a column
or an entire row, complicating the calculation of storage requirements
for a table or column.

Despite differences in storage layout on disk, the internal MySQL APIs
that communicate and exchange information about table rows use a
consistent data structure that applies across all storage engines.

This section includes guidelines and information for the storage
requirements for each data type supported by MySQL, including the
internal format and size for storage engines that use a fixed-size
representation for data types.  Information is listed by category or
storage engine.

The internal representation of a table has a maximum row size of 65,535
bytes, even if the storage engine is capable of supporting larger rows.
This figure excludes 'BLOB' or 'TEXT' columns,
which contribute only 9 to 12 bytes toward this size.  For 'BLOB'
and 'TEXT' data, the information is stored internally
in a different area of memory than the row buffer.  Different storage
engines handle the allocation and storage of this data in different
ways, according to the method they use for handling the corresponding
types.  For more information, see storage-engines, and
column-count-limit.

*InnoDB Table Storage Requirements*

See innodb-physical-record for information about storage
requirements for 'InnoDB' tables.

*NDB Table Storage Requirements*

*Important*:

'NDB' tables use _4-byte alignment_; all
'NDB' data storage is done in multiples of 4 bytes.
Thus, a column value that would typically take 15 bytes requires 16
bytes in an 'NDB' table.  For example, in
'NDB' tables, the 'TINYINT',
'SMALLINT', 'MEDIUMINT', and
'INTEGER'. (see 'INT') column types
each require 4 bytes storage per record due to the alignment factor.

Each 'BIT(M)' column takes M bits of storage space.  Although an
individual 'BIT' column is _not_ 4-byte aligned, see
'NDB' reserves 4 bytes (32 bits) per row for the first
1-32 bits needed for 'BIT' columns, then another 4 bytes for bits 33-64,
and so on.

While a 'NULL' itself does not require any storage space, see 'NDB'
reserves 4 bytes per row if the table definition contains
any columns defined as 'NULL', up to 32 'NULL' columns.  (If an NDB
Cluster table is defined with more than 32 'NULL' columns up to 64
'NULL' columns, then 8 bytes per row are reserved.)

Every table using the 'NDB' storage engine
requires a primary key; if you do not define a primary key, a 'hidden'
primary key is created by 'NDB'.  This hidden
primary key consumes 31-35 bytes per table record.

You can use the 'ndb_size.pl'.
Perl script to estimate 'NDB' storage
requirements.  It connects to a current MySQL (not NDB Cluster) database
and creates a report on how much space that database would require if it
used the 'NDB' storage engine.  See
mysql-cluster-programs-ndb-size-pl for more information.

*Numeric Type Storage Requirements*

Data Type                     Storage Required

See 'TINYINT'.

See 'SMALLINT'.

See 'MEDIUMINT'.

See 'INT',   4 bytes
'INTEGER'.

See 'BIGINT'.

'FLOAT(P)'                    4 bytes if 0 <= P <= 24, 8 bytes if 25 <=
                              P <= 53

See 'FLOAT'.

'DOUBLE [PRECISION]', see 8 bytes 'REAL'.

'DECIMAL(M,D)',               Varies; see following discussion
'NUMERIC(M,D)'

'BIT(M)'                      approximately (M+7)/8 bytes

Values for 'DECIMAL'. (and 'NUMERIC')
columns are represented using a binary format that
packs nine decimal (base 10) digits into four bytes.  Storage for the
integer and fractional parts of each value are determined separately.
Each multiple of nine digits requires four bytes, and the 'leftover'
digits require some fraction of four bytes.  The storage required for
excess digits is given by the following table.

Leftover Digits    Number of Bytes

0                  0

1                  1

2                  1

3                  2

4                  2

5                  3

6                  3

7                  4

8                  4

*Date and Time Type Storage Requirements*

For 'TIME', 'DATETIME', and
'TIMESTAMP' columns, the storage required for tables created
before MySQL 5.6.4 differs from tables created from 5.6.4 on.  This is
due to a change in 5.6.4 that permits these types to have a fractional
part, which requires from 0 to 3 bytes.

Data Type      Storage Required Before       Storage Required as of
               MySQL 5.6.4                   MySQL 5.6.4

See 1 byte 1 byte 'YEAR'.

See 3 bytes 3 bytes 'DATE'.

See 3 bytes 3 bytes + fractional 'TIME'.

See 8 bytes 5 bytes + fractional 'DATETIME'.

See 4 bytes 4 bytes + fractional 'TIMESTAMP'.

As of MySQL 5.6.4, storage for 'YEAR' and 'DATE'
remains unchanged.  However, see 'TIME',
'DATETIME', and 'TIMESTAMP' are represented
differently.  'DATETIME' is packed more efficiently,
requiring 5 rather than 8 bytes for the nonfractional part, and all
three parts have a fractional part that requires from 0 to 3 bytes,
depending on the fractional seconds precision of stored values.

Fractional Seconds Precision         Storage Required

0                                    0 bytes

1, 2                                 1 byte

3, 4                                 2 bytes

5, 6                                 3 bytes

For example, see 'TIME(0)', 'TIME(2)',
'TIME(4)', and 'TIME(6)' use 3, 4, 5, and 6 bytes,
respectively.  'TIME' and 'TIME(0)' are
equivalent and require the same storage.

For details about internal representation of temporal values, see MySQL
Internals: Important Algorithms and Structures
(http://dev.mysql.com/doc/internals/en/algorithms.html).

*String Type Storage Requirements*

In the following table, M represents the declared column length in
characters for nonbinary string types and bytes for binary string types.
L represents the actual length in bytes of a given string value.

Data Type                     Storage Required

'CHAR(M)'                     M x W bytes, 0 '<= M <=' 255, where W is
                              the number of bytes required for the
                              maximum-length character in the character
                              set.  See innodb-physical-record
                              for information about 'CHAR' data type
                              storage requirements for 'InnoDB' tables.

'BINARY(M)'                   M bytes, 0 '<= M <=' 255

'VARCHAR(M)',                 L + 1 bytes if column values require 0
'VARBINARY(M)'                − 255 bytes, L + 2 bytes if values may
                              require more than 255 bytes

See 'TINYBLOB',       L + 1 bytes, where L < 2^8
'TINYTEXT'.

See 'BLOB', L + 2 bytes, where L < 2^16 'TEXT'.

See 'MEDIUMBLOB',     L + 3 bytes, where L < 2^24
'MEDIUMTEXT'.

See 'LONGBLOB',       L + 4 bytes, where L < 2^32
'LONGTEXT'.

'ENUM('VALUE1','VALUE2',...)' 1 or 2 bytes, depending on the number of
                              enumeration values (65,535 values
                              maximum)

'SET('VALUE1','VALUE2',...)'  1, 2, 3, 4, or 8 bytes, depending on the
                              number of set members (64 members
                              maximum)

Variable-length string types are stored using a length prefix plus data.
The length prefix requires from one to four bytes depending on the data
type, and the value of the prefix is L (the byte length of the string).
For example, storage for a 'MEDIUMTEXT' value requires L
bytes to store the value plus three bytes to store the length of the
value.

To calculate the number of bytes used to store a particular
'CHAR', 'VARCHAR', or 'TEXT' column
value, you must take into account the character set used for that column
and whether the value contains multibyte characters.  In particular,
when using a 'utf8' Unicode character set, you must keep in mind that
not all characters use the same number of bytes.  'utf8mb3' and
'utf8mb4' character sets can require up to three and four bytes per
character, respectively.  For a breakdown of the storage used for
different categories of 'utf8mb3' or 'utf8mb4' characters, see
charset-unicode.

See 'VARCHAR', 'VARBINARY', and the
'BLOB' and 'TEXT' types are variable-length
types.  For each, the storage requirements depend on these factors:

   * The actual length of the column value

   * The column's maximum possible length

   * The character set used for the column, because some character sets
     contain multibyte characters

For example, a 'VARCHAR(255)' column can hold a string with a maximum
length of 255 characters.  Assuming that the column uses the 'latin1'
character set (one byte per character), the actual storage required is
the length of the string (L), plus one byte to record the length of the
string.  For the string ''abcd'', L is 4 and the storage requirement is
five bytes.  If the same column is instead declared to use the 'ucs2'
double-byte character set, the storage requirement is 10 bytes: The
length of ''abcd'' is eight bytes and the column requires two bytes to
store lengths because the maximum length is greater than 255 (up to 510
bytes).

The effective maximum number of _bytes_ that can be stored in a
'VARCHAR' or 'VARBINARY' column is
subject to the maximum row size of 65,535 bytes, which is shared among
all columns.  For a 'VARCHAR' column that stores multibyte
characters, the effective maximum number of _characters_ is less.  For
example, 'utf8mb3' characters can require up to three bytes per
character, so a 'VARCHAR' column that uses the 'utf8mb3'
character set can be declared to be a maximum of 21,844 characters.  See
column-count-limit.

'InnoDB' encodes fixed-length fields greater than or equal to 768 bytes
in length as variable-length fields, which can be stored off-page.  For
example, a 'CHAR(255)' column can exceed 768 bytes if the maximum byte
length of the character set is greater than 3, as it is with 'utf8mb4'.

The 'NDB' storage engine supports variable-width
columns.  This means that a 'VARCHAR' column in an NDB
Cluster table requires the same amount of storage as would any other
storage engine, with the exception that such values are 4-byte aligned.
Thus, the string ''abcd'' stored in a 'VARCHAR(50)' column using the
'latin1' character set requires 8 bytes (rather than 5 bytes for the
same column value in a 'MyISAM' table).

'TEXT' and 'BLOB' columns are implemented
differently in the 'NDB' storage engine, wherein
each row in a 'TEXT' column is made up of two separate
parts.  One of these is of fixed size (256 bytes), and is actually
stored in the original table.  The other consists of any data in excess
of 256 bytes, which is stored in a hidden table.  The rows in this
second table are always 2,000 bytes long.  This means that the size of a
'TEXT' column is 256 if SIZE <= 256 (where SIZE represents
the size of the row); otherwise, the size is 256 + SIZE + (2000 −
(SIZE − 256) % 2000).

The size of an 'ENUM' object is determined by the number of
different enumeration values.  One byte is used for enumerations with up
to 255 possible values.  Two bytes are used for enumerations having
between 256 and 65,535 possible values.  See enum.

The size of a 'SET' object is determined by the number of
different set members.  If the set size is N, the object occupies
'(N+7)/8' bytes, rounded up to 1, 2, 3, 4, or 8 bytes.  A 'SET'
can have a maximum of 64 members.  See set.

*Spatial Type Storage Requirements*

MySQL stores geometry values using 4 bytes to indicate the SRID followed
by the WKB representation of the value.  The 'LENGTH()' function returns
the space in bytes required for value storage.

For descriptions of WKB and internal storage formats for spatial values,
see gis-data-formats.

*JSON Storage Requirements*

In general, the storage requirement for a 'JSON' column is
approximately the same as for a 'LONGBLOB' or 'LONGTEXT' column; that
is, the space consumed by a JSON document is roughly the same as it
would be for the document's string representation stored in a column of
one of these types.  However, there is an overhead imposed by the binary
encoding, including metadata and dictionaries needed for lookup, of the
individual values stored in the JSON document.  For example, a string
stored in a JSON document requires 4 to 10 bytes additional storage,
depending on the length of the string and the size of the object or
array in which it is stored.

In addition, MySQL imposes a limit on the size of any JSON document
stored in a 'JSON' column such that it cannot be any larger than the
value of 'max_allowed_packet'.

11.9 Choosing the Right Type for a Column
=========================================

For optimum storage, you should try to use the most precise type in all
cases.  For example, if an integer column is used for values in the
range from '1' to '99999', 'MEDIUMINT UNSIGNED' is the best type.  Of
the types that represent all the required values, this type uses the
least amount of storage.

All basic calculations ('+', '-', '*', and '/') with 'DECIMAL'
columns are done with precision of 65 decimal (base
10) digits.  See numeric-type-overview.

If accuracy is not too important or if speed is the highest priority,
the 'DOUBLE' type may be good enough.  For
high precision, you can always convert to a fixed-point type stored in a
'BIGINT'.  This enables you to do all calculations
with 64-bit integers and then convert results back to floating-point
values as necessary.

11.10 Using Data Types from Other Database Engines
==================================================

To facilitate the use of code written for SQL implementations from other
vendors, MySQL maps data types as shown in the following table.  These
mappings make it easier to import table definitions from other database
systems into MySQL.

Other Vendor Type         MySQL Type

See 'BOOL'.
integer-types.

See 'BOOLEAN'.
integer-types.

'CHARACTER VARYING(M)'    'VARCHAR(M)'

See 'FIXED'.
fixed-point-types.

See 'FLOAT4'.
floating-point-types.

See 'FLOAT8'.
floating-point-types.

See 'INT1'.
integer-types.

See 'INT2'.
integer-types.

See 'INT3'.
integer-types.

See 'INT4'.
integer-types.

'INT8'                    'BIGINT'.

'LONG VARBINARY'          'MEDIUMBLOB'.

'LONG VARCHAR'            'MEDIUMTEXT'.

'LONG'                    'MEDIUMTEXT'.

See 'MIDDLEINT'.
integer-types.

See 'NUMERIC'.
fixed-point-types.

Data type mapping occurs at table creation time, after which the
original type specifications are discarded.  If you create a table with
types used by other vendors and then issue a 'DESCRIBE TBL_NAME'
statement, MySQL reports the table structure using the equivalent MySQL
types.  For example:

     mysql> CREATE TABLE t (a BOOL, b FLOAT8, c LONG VARCHAR, d NUMERIC);
     Query OK, 0 rows affected (0.00 sec)

     mysql> DESCRIBE t;
     +-------+---------------+------+-----+---------+-------+
     | Field | Type          | Null | Key | Default | Extra |
     +-------+---------------+------+-----+---------+-------+
     | a     | tinyint(1)    | YES  |     | NULL    |       |
     | b     | double        | YES  |     | NULL    |       |
     | c     | mediumtext    | YES  |     | NULL    |       |
     | d     | decimal(10,0) | YES  |     | NULL    |       |
     +-------+---------------+------+-----+---------+-------+
     4 rows in set (0.01 sec)

12 Functions and Operators
**************************

Expressions can be used at several points in SQL statements, such as in
the 'ORDER BY' or 'HAVING' clauses of 'SELECT'.
statements, in the 'WHERE' clause of a 'SELECT',
'DELETE', or 'UPDATE' statement, or in
'SET' statements.  Expressions can be written using
literal values, column values, 'NULL', built-in functions, stored
functions, user-defined functions, and operators.  This chapter
describes the functions and operators that are permitted for writing
expressions in MySQL. Instructions for writing stored functions and
user-defined functions are given in stored-routines, and
adding-functions.  See function-resolution, for the rules
describing how the server interprets references to different kinds of
functions.

An expression that contains 'NULL' always produces a 'NULL' value unless
otherwise indicated in the documentation for a particular function or
operator.

*Note*:

By default, there must be no whitespace between a function name and the
parenthesis following it.  This helps the MySQL parser distinguish
between function calls and references to tables or columns that happen
to have the same name as a function.  However, spaces around function
arguments are permitted.

You can tell the MySQL server to accept spaces after function names by
starting it with the '--sql-mode=IGNORE_SPACE' option.  (See
sql-mode.)  Individual client programs can request this behavior by
using the 'CLIENT_IGNORE_SPACE' option for 'mysql_real_connect()'.
In either case, all function names become reserved
words.

For the sake of brevity, most examples in this chapter display the
output from the 'mysql' program in abbreviated form.
Rather than showing examples in this format:

     mysql> SELECT MOD(29,9);
     +-----------+
     | mod(29,9) |
     +-----------+
     |         2 |
     +-----------+
     1 rows in set (0.00 sec)

This format is used instead:

     mysql> SELECT MOD(29,9);
             -> 2

12.1 Function and Operator Reference
====================================

*Functions and Operators*

Name                          Description

'ABS()'                       Return the absolute value

'ACOS()'                      Return the arc cosine

'ADDDATE()'                   Add time values (intervals) to a date
                              value

'ADDTIME()'                   Add time

'AES_DECRYPT()'               Decrypt using AES

'AES_ENCRYPT()'               Encrypt using AES

'AND', '&&'                   Logical AND

'ANY_VALUE()'                 Suppress ONLY_FULL_GROUP_BY value
                              rejection

'Area()' (deprecated 5.7.6)   Return Polygon or MultiPolygon area

'AsBinary()', 'AsWKB()'       Convert from internal geometry format to
(deprecated 5.7.6)            WKB

'ASCII()'                     Return numeric value of left-most
                              character

'ASIN()'                      Return the arc sine

'='                           Assign a value (as part of a 'SET'
                              statement, or as part of
                              the 'SET' clause in an 'UPDATE'
                              statement)

':='                          Assign a value

'AsText()', 'AsWKT()'         Convert from internal geometry format to
(deprecated 5.7.6)            WKT

'ASYMMETRIC_DECRYPT()'        Decrypt ciphertext using private or
                              public key

'ASYMMETRIC_DERIVE()'         Derive symmetric key from asymmetric keys

'ASYMMETRIC_ENCRYPT()'        Encrypt cleartext using private or public
                              key

'ASYMMETRIC_SIGN()'           Generate signature from digest

'ASYMMETRIC_VERIFY()'         Verify that signature matches digest

'ATAN()'                      Return the arc tangent

'ATAN2()', 'ATAN()'           Return the arc tangent of the two
                              arguments

'AVG()'                       Return the average value of the argument

'BENCHMARK()'                 Repeatedly execute an expression

'BETWEEN ... AND ...'         Check whether a value is within a range
                              of values

'BIN()'                       Return a string containing binary
                              representation of a number

'BINARY'                      Cast a string to a binary string

'BIT_AND()'                   Return bitwise AND

'BIT_COUNT()'                 Return the number of bits that are set

'BIT_LENGTH()'                Return length of argument in bits

'BIT_OR()'                    Return bitwise OR

'BIT_XOR()'                   Return bitwise XOR

'&'                           Bitwise AND

'~'                           Bitwise inversion

'|'                           Bitwise OR

'^'                           Bitwise XOR

'Buffer()' (deprecated        Return geometry of points within given
5.7.6)                        distance from geometry

'CASE'                        Case operator

'CAST()'                      Cast a value as a certain type

'CEIL()'                      Return the smallest integer value not
                              less than the argument

'CEILING()'                   Return the smallest integer value not
                              less than the argument

'Centroid()' (deprecated      Return centroid as a point
5.7.6)

'CHAR()'                      Return the character for each integer
                              passed

'CHAR_LENGTH()'               Return number of characters in argument

'CHARACTER_LENGTH()'          Synonym for CHAR_LENGTH()

'CHARSET()'                   Return the character set of the argument

'COALESCE()'                  Return the first non-NULL argument

'COERCIBILITY()'              Return the collation coercibility value
                              of the string argument

'COLLATION()'                 Return the collation of the string
                              argument

'COMPRESS()'                  Return result as a binary string

'CONCAT()'                    Return concatenated string

'CONCAT_WS()'                 Return concatenate with separator

'CONNECTION_ID()'             Return the connection ID (thread ID) for
                              the connection

'Contains()' (deprecated      Whether MBR of one geometry contains MBR
5.7.6)                        of another

'CONV()'                      Convert numbers between different number
                              bases

'CONVERT()'                   Cast a value as a certain type

'CONVERT_TZ()'                Convert from one time zone to another

'ConvexHull()' (deprecated    Return convex hull of geometry
5.7.6)

'COS()'                       Return the cosine

'COT()'                       Return the cotangent

'COUNT()'                     Return a count of the number of rows
                              returned

'COUNT(DISTINCT)'             Return the count of a number of different
                              values

'CRC32()'                     Compute a cyclic redundancy check value

'CREATE_ASYMMETRIC_PRIV_KEY()'Create private key

'CREATE_ASYMMETRIC_PUB_KEY()' Create public key

'CREATE_DH_PARAMETERS()'      Generate shared DH secret

'CREATE_DIGEST()'             Generate digest from string

'Crosses()' (deprecated       Whether one geometry crosses another
5.7.6)

'CURDATE()'                   Return the current date

'CURRENT_DATE()',             Synonyms for CURDATE()
'CURRENT_DATE'

'CURRENT_TIME()',             Synonyms for CURTIME()
'CURRENT_TIME'

'CURRENT_TIMESTAMP()',        Synonyms for NOW()
'CURRENT_TIMESTAMP'

'CURRENT_USER()',             The authenticated user name and host name
'CURRENT_USER'

'CURTIME()'                   Return the current time

'DATABASE()'                  Return the default (current) database
                              name

'DATE()'                      Extract the date part of a date or
                              datetime expression

'DATE_ADD()'                  Add time values (intervals) to a date
                              value

'DATE_FORMAT()'               Format date as specified

'DATE_SUB()'                  Subtract a time value (interval) from a
                              date

'DATEDIFF()'                  Subtract two dates

'DAY()'                       Synonym for DAYOFMONTH()

'DAYNAME()'                   Return the name of the weekday

'DAYOFMONTH()'                Return the day of the month (0-31)

'DAYOFWEEK()'                 Return the weekday index of the argument

'DAYOFYEAR()'                 Return the day of the year (1-366)

'DECODE()' (deprecated        Decodes a string encrypted using ENCODE()
5.7.2)

'DEFAULT()'                   Return the default value for a table
                              column

'DEGREES()'                   Convert radians to degrees

'DES_DECRYPT()' (deprecated   Decrypt a string
5.7.6)

'DES_ENCRYPT()' (deprecated   Encrypt a string
5.7.6)

'Dimension()' (deprecated     Dimension of geometry
5.7.6)

'Disjoint()' (deprecated      Whether MBRs of two geometries are
5.7.6)                        disjoint

'Distance()' (deprecated      The distance of one geometry from another
5.7.6)

'DIV'                         Integer division

'/'                           Division operator

'ELT()'                       Return string at index number

'ENCODE()' (deprecated        Encode a string
5.7.2)

'ENCRYPT()' (deprecated       Encrypt a string
5.7.6)

'EndPoint()' (deprecated      End Point of LineString
5.7.6)

'Envelope()' (deprecated      Return MBR of geometry
5.7.6)

'='                           Equal operator

'<=>'                         NULL-safe equal to operator

'Equals()' (deprecated        Whether MBRs of two geometries are equal
5.7.6)

'EXP()'                       Raise to the power of

'EXPORT_SET()'                Return a string such that for every bit
                              set in the value bits, you get an on
                              string and for every unset bit, you get
                              an off string

'ExteriorRing()'              Return exterior ring of Polygon
(deprecated 5.7.6)

'EXTRACT()'                   Extract part of a date

'ExtractValue()'              Extracts a value from an XML string using
                              XPath notation

'FIELD()'                     Return the index (position) of the first
                              argument in the subsequent arguments

'FIND_IN_SET()'               Return the index position of the first
                              argument within the second argument

'FLOOR()'                     Return the largest integer value not
                              greater than the argument

'FORMAT()'                    Return a number formatted to specified
                              number of decimal places

'FOUND_ROWS()'                For a SELECT with a LIMIT clause, the
                              number of rows that would be returned
                              were there no LIMIT clause

'FROM_BASE64()'               Decode to a base-64 string and return
                              result

'FROM_DAYS()'                 Convert a day number to a date

'FROM_UNIXTIME()'             Format Unix timestamp as a date

'GeomCollFromText()',         Return geometry collection from WKT
'GeometryCollectionFromText()'
(deprecated 5.7.6)

'GeomCollFromWKB()',          Return geometry collection from WKB
'GeometryCollectionFromWKB()'
(deprecated 5.7.6)

'GeometryCollection()'        Construct geometry collection from
                              geometries

'GeometryN()' (deprecated     Return N-th geometry from geometry
5.7.6)                        collection

'GeometryType()'              Return name of geometry type
(deprecated 5.7.6)

'GeomFromText()',             Return geometry from WKT
'GeometryFromText()'
(deprecated 5.7.6)

'GeomFromWKB()',              Return geometry from WKB
'GeometryFromWKB()'
(deprecated 5.7.6)

'GET_FORMAT()'                Return a date format string

'GET_LOCK()'                  Get a named lock

'GLength()' (deprecated       Return length of LineString
5.7.6)

'>'                           Greater than operator

'>='                          Greater than or equal operator

'GREATEST()'                  Return the largest argument

'GROUP_CONCAT()'              Return a concatenated string

'GTID_SUBSET()'               Return true if all GTIDs in subset are
                              also in set; otherwise false.

'GTID_SUBTRACT()'             Return all GTIDs in set that are not in
                              subset.

'HEX()'                       Return a hexadecimal representation of a
                              decimal or string value

'HOUR()'                      Extract the hour

'IF()'                        If/else construct

'IFNULL()'                    Null if/else construct

'IN()'                        Check whether a value is within a set of
                              values

'INET_ATON()'                 Return the numeric value of an IP address

'INET_NTOA()'                 Return the IP address from a numeric
                              value

'INET6_ATON()'                Return the numeric value of an IPv6
                              address

'INET6_NTOA()'                Return the IPv6 address from a numeric
                              value

'INSERT()'                    Insert a substring at the specified
                              position up to the specified number of
                              characters

'INSTR()'                     Return the index of the first occurrence
                              of substring

'InteriorRingN()'             Return N-th interior ring of Polygon
(deprecated 5.7.6)

'Intersects()' (deprecated    Whether MBRs of two geometries intersect
5.7.6)

'INTERVAL()'                  Return the index of the argument that is
                              less than the first argument

'IS'                          Test a value against a boolean

'IS_FREE_LOCK()'              Whether the named lock is free

'IS_IPV4()'                   Whether argument is an IPv4 address

'IS_IPV4_COMPAT()'            Whether argument is an IPv4-compatible
                              address

'IS_IPV4_MAPPED()'            Whether argument is an IPv4-mapped
                              address

'IS_IPV6()'                   Whether argument is an IPv6 address

'IS NOT'                      Test a value against a boolean

'IS NOT NULL'                 NOT NULL value test

'IS NULL'                     NULL value test

'IS_USED_LOCK()'              Whether the named lock is in use; return
                              connection identifier if true

'IsClosed()' (deprecated      Whether a geometry is closed and simple
5.7.6)

'IsEmpty()' (deprecated       Placeholder function
5.7.6)

'ISNULL()'                    Test whether the argument is NULL

'IsSimple()' (deprecated      Whether a geometry is simple
5.7.6)

'JSON_APPEND()' (deprecated   Append data to JSON document
5.7.9)

'JSON_ARRAY()'                Create JSON array

'JSON_ARRAY_APPEND()'         Append data to JSON document

'JSON_ARRAY_INSERT()'         Insert into JSON array

'JSON_ARRAYAGG()'             Return result set as a single JSON array

'->'                          Return value from JSON column after
                              evaluating path; equivalent to
                              JSON_EXTRACT().

'JSON_CONTAINS()'             Whether JSON document contains specific
                              object at path

'JSON_CONTAINS_PATH()'        Whether JSON document contains any data
                              at path

'JSON_DEPTH()'                Maximum depth of JSON document

'JSON_EXTRACT()'              Return data from JSON document

'->>'                         Return value from JSON column after
                              evaluating path and unquoting the result;
                              equivalent to
                              JSON_UNQUOTE(JSON_EXTRACT()).

'JSON_INSERT()'               Insert data into JSON document

'JSON_KEYS()'                 Array of keys from JSON document

'JSON_LENGTH()'               Number of elements in JSON document

'JSON_MERGE()' (deprecated    Merge JSON documents, preserving
5.7.22)                       duplicate keys.  Deprecated synonym for
                              JSON_MERGE_PRESERVE()

'JSON_MERGE_PATCH()'          Merge JSON documents, replacing values of
                              duplicate keys

'JSON_MERGE_PRESERVE()'       Merge JSON documents, preserving
                              duplicate keys

'JSON_OBJECT()'               Create JSON object

'JSON_OBJECTAGG()'            Return result set as a single JSON object

'JSON_PRETTY()'               Prints a JSON document in human-readable
                              format, with each array element or object
                              member printed on a new line, indented
                              two spaces with respect to its parent.

'JSON_QUOTE()'                Quote JSON document

'JSON_REMOVE()'               Remove data from JSON document

'JSON_REPLACE()'              Replace values in JSON document

'JSON_SEARCH()'               Path to value within JSON document

'JSON_SET()'                  Insert data into JSON document

'JSON_STORAGE_SIZE()'         Space used for storage of binary
                              representation of a JSON document; for a
                              JSON column, the space used when the
                              document was inserted, prior to any
                              partial updates

'JSON_TYPE()'                 Type of JSON value

'JSON_UNQUOTE()'              Unquote JSON value

'JSON_VALID()'                Whether JSON value is valid

'LAST_DAY'                    Return the last day of the month for the
                              argument

'LAST_INSERT_ID()'            Value of the AUTOINCREMENT column for the
                              last INSERT

'LCASE()'                     Synonym for LOWER()

'LEAST()'                     Return the smallest argument

'LEFT()'                      Return the leftmost number of characters
                              as specified

'<<'                          Left shift

'LENGTH()'                    Return the length of a string in bytes

'<'                           Less than operator

'<='                          Less than or equal operator

'LIKE'                        Simple pattern matching

'LineFromText()',             Construct LineString from WKT
'LineStringFromText()'
(deprecated 5.7.6)

'LineFromWKB()',              Construct LineString from WKB
'LineStringFromWKB()'
(deprecated 5.7.6)

'LineString()'                Construct LineString from Point values

'LN()'                        Return the natural logarithm of the
                              argument

'LOAD_FILE()'                 Load the named file

'LOCALTIME()', 'LOCALTIME'    Synonym for NOW()

'LOCALTIMESTAMP',             Synonym for NOW()
'LOCALTIMESTAMP()'

'LOCATE()'                    Return the position of the first
                              occurrence of substring

'LOG()'                       Return the natural logarithm of the first
                              argument

'LOG10()'                     Return the base-10 logarithm of the
                              argument

'LOG2()'                      Return the base-2 logarithm of the
                              argument

'LOWER()'                     Return the argument in lowercase

'LPAD()'                      Return the string argument, left-padded
                              with the specified string

'LTRIM()'                     Remove leading spaces

'MAKE_SET()'                  Return a set of comma-separated strings
                              that have the corresponding bit in bits
                              set

'MAKEDATE()'                  Create a date from the year and day of
                              year

'MAKETIME()'                  Create time from hour, minute, second

'MASTER_POS_WAIT()'           Block until the slave has read and
                              applied all updates up to the specified
                              position

'MATCH'                       Perform full-text search

'MAX()'                       Return the maximum value

'MBRContains()'               Whether MBR of one geometry contains MBR
                              of another

'MBRCoveredBy()'              Whether one MBR is covered by another

'MBRCovers()'                 Whether one MBR covers another

'MBRDisjoint()'               Whether MBRs of two geometries are
                              disjoint

'MBREqual()' (deprecated      Whether MBRs of two geometries are equal
5.7.6)

'MBREquals()'                 Whether MBRs of two geometries are equal

'MBRIntersects()'             Whether MBRs of two geometries intersect

'MBROverlaps()'               Whether MBRs of two geometries overlap

'MBRTouches()'                Whether MBRs of two geometries touch

'MBRWithin()'                 Whether MBR of one geometry is within MBR
                              of another

'MD5()'                       Calculate MD5 checksum

'MICROSECOND()'               Return the microseconds from argument

'MID()'                       Return a substring starting from the
                              specified position

'MIN()'                       Return the minimum value

'-'                           Minus operator

'MINUTE()'                    Return the minute from the argument

'MLineFromText()',            Construct MultiLineString from WKT
'MultiLineStringFromText()'
(deprecated 5.7.6)

'MLineFromWKB()',             Construct MultiLineString from WKB
'MultiLineStringFromWKB()'
(deprecated 5.7.6)

'MOD()'                       Return the remainder

'%', 'MOD'                    Modulo operator

'MONTH()'                     Return the month from the date passed

'MONTHNAME()'                 Return the name of the month

'MPointFromText()',           Construct MultiPoint from WKT
'MultiPointFromText()'
(deprecated 5.7.6)

'MPointFromWKB()',            Construct MultiPoint from WKB
'MultiPointFromWKB()'
(deprecated 5.7.6)

'MPolyFromText()',            Construct MultiPolygon from WKT
'MultiPolygonFromText()'
(deprecated 5.7.6)

'MPolyFromWKB()',             Construct MultiPolygon from WKB
'MultiPolygonFromWKB()'
(deprecated 5.7.6)

'MultiLineString()'           Contruct MultiLineString from LineString
                              values

'MultiPoint()'                Construct MultiPoint from Point values

'MultiPolygon()'              Construct MultiPolygon from Polygon
                              values

'NAME_CONST()'                Causes the column to have the given name

'NOT', '!'                    Negates value

'NOT BETWEEN ... AND ...'     Check whether a value is not within a
                              range of values

'!=', '<>'                    Not equal operator

'NOT IN()'                    Check whether a value is not within a set
                              of values

'NOT LIKE'                    Negation of simple pattern matching

'NOT REGEXP'                  Negation of REGEXP

'NOW()'                       Return the current date and time

'NULLIF()'                    Return NULL if expr1 = expr2

'NumGeometries()'             Return number of geometries in geometry
(deprecated 5.7.6)            collection

'NumInteriorRings()'          Return number of interior rings in
(deprecated 5.7.6)            Polygon

'NumPoints()' (deprecated     Return number of points in LineString
5.7.6)

'OCT()'                       Return a string containing octal
                              representation of a number

'OCTET_LENGTH()'              Synonym for LENGTH()

'OLD_PASSWORD()'              Return the value of the pre-4.1
                              implementation of PASSWORD

'||', 'OR'                    Logical OR

'ORD()'                       Return character code for leftmost
                              character of the argument

'Overlaps()' (deprecated      Whether MBRs of two geometries overlap
5.7.6)

'PASSWORD()' (deprecated      Calculate and return a password string
5.7.6)

'PERIOD_ADD()'                Add a period to a year-month

'PERIOD_DIFF()'               Return the number of months between
                              periods

'PI()'                        Return the value of pi

'+'                           Addition operator

'Point()'                     Construct Point from coordinates

'PointFromText()'             Construct Point from WKT
(deprecated 5.7.6)

'PointFromWKB()'              Construct Point from WKB
(deprecated 5.7.6)

'PointN()' (deprecated        Return N-th point from LineString
5.7.6)

'PolyFromText()',             Construct Polygon from WKT
'PolygonFromText()'
(deprecated 5.7.6)

'PolyFromWKB()',              Construct Polygon from WKB
'PolygonFromWKB()'
(deprecated 5.7.6)

'Polygon()'                   Construct Polygon from LineString
                              arguments

'POSITION()'                  Synonym for LOCATE()

'POW()'                       Return the argument raised to the
                              specified power

'POWER()'                     Return the argument raised to the
                              specified power

See 'PROCEDURE Analyze the results of a query ANALYSE()'.
(deprecated 5.7.18)

'QUARTER()'                   Return the quarter from a date argument

'QUOTE()'                     Escape the argument for use in an SQL
                              statement

'RADIANS()'                   Return argument converted to radians

'RAND()'                      Return a random floating-point value

'RANDOM_BYTES()'              Return a random byte vector

'REGEXP'                      Whether string matches regular expression

'RELEASE_ALL_LOCKS()'         Releases all current named locks

'RELEASE_LOCK()'              Releases the named lock

'REPEAT()'                    Repeat a string the specified number of
                              times

'REPLACE()'                   Replace occurrences of a specified string

'REVERSE()'                   Reverse the characters in a string

'RIGHT()'                     Return the specified rightmost number of
                              characters

'>>'                          Right shift

'RLIKE'                       Whether string matches regular expression

'ROUND()'                     Round the argument

'ROW_COUNT()'                 The number of rows updated

'RPAD()'                      Append string the specified number of
                              times

'RTRIM()'                     Remove trailing spaces

'SCHEMA()'                    Synonym for DATABASE()

'SEC_TO_TIME()'               Converts seconds to 'HH:MM:SS' format

'SECOND()'                    Return the second (0-59)

'SESSION_USER()'              Synonym for USER()

'SHA1()', 'SHA()'             Calculate an SHA-1 160-bit checksum

'SHA2()'                      Calculate an SHA-2 checksum

'SIGN()'                      Return the sign of the argument

'SIN()'                       Return the sine of the argument

'SLEEP()'                     Sleep for a number of seconds

'SOUNDEX()'                   Return a soundex string

'SOUNDS LIKE'                 Compare sounds

'SPACE()'                     Return a string of the specified number
                              of spaces

'SQRT()'                      Return the square root of the argument

'SRID()' (deprecated 5.7.6)   Return spatial reference system ID for
                              geometry

'ST_Area()'                   Return Polygon or MultiPolygon area

'ST_AsBinary()',              Convert from internal geometry format to
'ST_AsWKB()'                  WKB

'ST_AsGeoJSON()'              Generate GeoJSON object from geometry

'ST_AsText()', 'ST_AsWKT()'   Convert from internal geometry format to
                              WKT

'ST_Buffer()'                 Return geometry of points within given
                              distance from geometry

'ST_Buffer_Strategy()'        Produce strategy option for ST_Buffer()

'ST_Centroid()'               Return centroid as a point

'ST_Contains()'               Whether one geometry contains another

'ST_ConvexHull()'             Return convex hull of geometry

'ST_Crosses()'                Whether one geometry crosses another

'ST_Difference()'             Return point set difference of two
                              geometries

'ST_Dimension()'              Dimension of geometry

'ST_Disjoint()'               Whether one geometry is disjoint from
                              another

'ST_Distance()'               The distance of one geometry from another

'ST_Distance_Sphere()'        Minimum distance on earth between two
                              geometries

'ST_EndPoint()'               End Point of LineString

'ST_Envelope()'               Return MBR of geometry

'ST_Equals()'                 Whether one geometry is equal to another

'ST_ExteriorRing()'           Return exterior ring of Polygon

'ST_GeoHash()'                Produce a geohash value

'ST_GeomCollFromText()',      Return geometry collection from WKT
'ST_GeometryCollectionFromText()',
'ST_GeomCollFromTxt()'

'ST_GeomCollFromWKB()',       Return geometry collection from WKB
'ST_GeometryCollectionFromWKB()'

'ST_GeometryN()'              Return N-th geometry from geometry
                              collection

'ST_GeometryType()'           Return name of geometry type

'ST_GeomFromGeoJSON()'        Generate geometry from GeoJSON object

'ST_GeomFromText()',          Return geometry from WKT
'ST_GeometryFromText()'

'ST_GeomFromWKB()',           Return geometry from WKB
'ST_GeometryFromWKB()'

'ST_InteriorRingN()'          Return N-th interior ring of Polygon

'ST_Intersection()'           Return point set intersection of two
                              geometries

'ST_Intersects()'             Whether one geometry intersects another

'ST_IsClosed()'               Whether a geometry is closed and simple

'ST_IsEmpty()'                Placeholder function

'ST_IsSimple()'               Whether a geometry is simple

'ST_IsValid()'                Whether a geometry is valid

'ST_LatFromGeoHash()'         Return latitude from geohash value

'ST_Length()'                 Return length of LineString

'ST_LineFromText()',          Construct LineString from WKT
'ST_LineStringFromText()'

'ST_LineFromWKB()',           Construct LineString from WKB
'ST_LineStringFromWKB()'

'ST_LongFromGeoHash()'        Return longitude from geohash value

'ST_MakeEnvelope()'           Rectangle around two points

'ST_MLineFromText()',         Construct MultiLineString from WKT
'ST_MultiLineStringFromText()'

'ST_MLineFromWKB()',          Construct MultiLineString from WKB
'ST_MultiLineStringFromWKB()'

'ST_MPointFromText()',        Construct MultiPoint from WKT
'ST_MultiPointFromText()'

'ST_MPointFromWKB()',         Construct MultiPoint from WKB
'ST_MultiPointFromWKB()'

'ST_MPolyFromText()',         Construct MultiPolygon from WKT
'ST_MultiPolygonFromText()'

'ST_MPolyFromWKB()',          Construct MultiPolygon from WKB
'ST_MultiPolygonFromWKB()'

'ST_NumGeometries()'          Return number of geometries in geometry
                              collection

'ST_NumInteriorRing()',       Return number of interior rings in
'ST_NumInteriorRings()'       Polygon

'ST_NumPoints()'              Return number of points in LineString

'ST_Overlaps()'               Whether one geometry overlaps another

'ST_PointFromGeoHash()'       Convert geohash value to POINT value

'ST_PointFromText()'          Construct Point from WKT

'ST_PointFromWKB()'           Construct Point from WKB

'ST_PointN()'                 Return N-th point from LineString

'ST_PolyFromText()',          Construct Polygon from WKT
'ST_PolygonFromText()'

'ST_PolyFromWKB()',           Construct Polygon from WKB
'ST_PolygonFromWKB()'

'ST_Simplify()'               Return simplified geometry

'ST_SRID()'                   Return spatial reference system ID for
                              geometry

'ST_StartPoint()'             Start Point of LineString

'ST_SymDifference()'          Return point set symmetric difference of
                              two geometries

'ST_Touches()'                Whether one geometry touches another

'ST_Union()'                  Return point set union of two geometries

'ST_Validate()'               Return validated geometry

'ST_Within()'                 Whether one geometry is within another

'ST_X()'                      Return X coordinate of Point

'ST_Y()'                      Return Y coordinate of Point

'StartPoint()' (deprecated    Start Point of LineString
5.7.6)

'STD()'                       Return the population standard deviation

'STDDEV()'                    Return the population standard deviation

'STDDEV_POP()'                Return the population standard deviation

'STDDEV_SAMP()'               Return the sample standard deviation

'STR_TO_DATE()'               Convert a string to a date

'STRCMP()'                    Compare two strings

'SUBDATE()'                   Synonym for DATE_SUB() when invoked with
                              three arguments

'SUBSTR()'                    Return the substring as specified

'SUBSTRING()'                 Return the substring as specified

'SUBSTRING_INDEX()'           Return a substring from a string before
                              the specified number of occurrences of
                              the delimiter

'SUBTIME()'                   Subtract times

'SUM()'                       Return the sum

'SYSDATE()'                   Return the time at which the function
                              executes

'SYSTEM_USER()'               Synonym for USER()

'TAN()'                       Return the tangent of the argument

'TIME()'                      Extract the time portion of the
                              expression passed

'TIME_FORMAT()'               Format as time

'TIME_TO_SEC()'               Return the argument converted to seconds

'TIMEDIFF()'                  Subtract time

'*'                           Multiplication operator

'TIMESTAMP()'                 With a single argument, this function
                              returns the date or datetime expression;
                              with two arguments, the sum of the
                              arguments

'TIMESTAMPADD()'              Add an interval to a datetime expression

'TIMESTAMPDIFF()'             Subtract an interval from a datetime
                              expression

'TO_BASE64()'                 Return the argument converted to a
                              base-64 string

'TO_DAYS()'                   Return the date argument converted to
                              days

'TO_SECONDS()'                Return the date or datetime argument
                              converted to seconds since Year 0

'Touches()' (deprecated       Whether one geometry touches another
5.7.6)

'TRIM()'                      Remove leading and trailing spaces

'TRUNCATE()'                  Truncate to specified number of decimal
                              places

'UCASE()'                     Synonym for UPPER()

'-'                           Change the sign of the argument

'UNCOMPRESS()'                Uncompress a string compressed

'UNCOMPRESSED_LENGTH()'       Return the length of a string before
                              compression

'UNHEX()'                     Return a string containing hex
                              representation of a number

'UNIX_TIMESTAMP()'            Return a Unix timestamp

'UpdateXML()'                 Return replaced XML fragment

'UPPER()'                     Convert to uppercase

'USER()'                      The user name and host name provided by
                              the client

'UTC_DATE()'                  Return the current UTC date

'UTC_TIME()'                  Return the current UTC time

'UTC_TIMESTAMP()'             Return the current UTC date and time

'UUID()'                      Return a Universal Unique Identifier
                              (UUID)

'UUID_SHORT()'                Return an integer-valued universal
                              identifier

'VALIDATE_PASSWORD_STRENGTH()'Determine strength of password

'VALUES()'                    Defines the values to be used during an
                              INSERT

'VAR_POP()'                   Return the population standard variance

'VAR_SAMP()'                  Return the sample variance

'VARIANCE()'                  Return the population standard variance

'VERSION()'                   Return a string that indicates the MySQL
                              server version

'WAIT_FOR_EXECUTED_GTID_SET()'Wait until the given GTIDs have executed
                              on slave.

'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()'Wait until the given GTIDs have executed
                              on slave.

'WEEK()'                      Return the week number

'WEEKDAY()'                   Return the weekday index

'WEEKOFYEAR()'                Return the calendar week of the date
                              (1-53)

'WEIGHT_STRING()'             Return the weight string for a string

'Within()' (deprecated        Whether MBR of one geometry is within MBR
5.7.6)                        of another

'X()' (deprecated 5.7.6)      Return X coordinate of Point

'XOR'                         Logical XOR

'Y()' (deprecated 5.7.6)      Return Y coordinate of Point

'YEAR()'                      Return the year

'YEARWEEK()'                  Return the year and week

12.2 Type Conversion in Expression Evaluation
=============================================

When an operator is used with operands of different types, type
conversion occurs to make the operands compatible.  Some conversions
occur implicitly.  For example, MySQL automatically converts numbers to
strings as necessary, and vice versa.

     mysql> SELECT 1+'1';
             -> 2
     mysql> SELECT CONCAT(2,' test');
             -> '2 test'

It is also possible to convert a number to a string explicitly using the
'CAST()' function.  Conversion occurs implicitly with the 'CONCAT()'
function because it expects string arguments.

     mysql> SELECT 38.8, CAST(38.8 AS CHAR);
             -> 38.8, '38.8'
     mysql> SELECT 38.8, CONCAT(38.8);
             -> 38.8, '38.8'

See later in this section for information about the character set of
implicit number-to-string conversions, and for modified rules that apply
to 'CREATE TABLE ... SELECT' statements.

The following rules describe how conversion occurs for comparison
operations:

   * If one or both arguments are 'NULL', the result of the comparison
     is 'NULL', except for the 'NULL'-safe '<=>' equality comparison
     operator.  For 'NULL <=> NULL', the result is true.  No conversion
     is needed.

   * If both arguments in a comparison operation are strings, they are
     compared as strings.

   * If both arguments are integers, they are compared as integers.

   * Hexadecimal values are treated as binary strings if not compared to
     a number.

   *
     If one of the arguments is a 'TIMESTAMP' or
     'DATETIME' column and the other argument is a constant,
     the constant is converted to a timestamp before the comparison is
     performed.  This is done to be more ODBC-friendly.  This is not
     done for the arguments to 'IN()'.  To be safe, always use complete
     datetime, date, or time strings when doing comparisons.  For
     example, to achieve best results when using 'BETWEEN' with date or
     time values, use 'CAST()' to explicitly convert the values to the
     desired data type.

     A single-row subquery from a table or tables is not considered a
     constant.  For example, if a subquery returns an integer to be
     compared to a 'DATETIME' value, the comparison is
     done as two integers.  The integer is not converted to a temporal
     value.  To compare the operands as 'DATETIME'.
     values, use 'CAST()' to explicitly convert the subquery value to
     'DATETIME'.

   * If one of the arguments is a decimal value, comparison depends on
     the other argument.  The arguments are compared as decimal values
     if the other argument is a decimal or integer value, or as
     floating-point values if the other argument is a floating-point
     value.

   * In all other cases, the arguments are compared as floating-point
     (real) numbers.

For information about conversion of values from one temporal type to
another, see date-and-time-type-conversion.

Comparison of JSON values takes place at two levels.  The first level of
comparison is based on the JSON types of the compared values.  If the
types differ, the comparison result is determined solely by which type
has higher precedence.  If the two values have the same JSON type, a
second level of comparison occurs using type-specific rules.  For
comparison of JSON and non-JSON values, the non-JSON value is converted
to JSON and the values compared as JSON values.  For details, see
json-comparison.

The following examples illustrate conversion of strings to numbers for
comparison operations:

     mysql> SELECT 1 > '6x';
             -> 0
     mysql> SELECT 7 > '6x';
             -> 1
     mysql> SELECT 0 > 'x6';
             -> 0
     mysql> SELECT 0 = 'x6';
             -> 1

For comparisons of a string column with a number, MySQL cannot use an
index on the column to look up the value quickly.  If STR_COL is an
indexed string column, the index cannot be used when performing the
lookup in the following statement:

     SELECT * FROM TBL_NAME WHERE STR_COL=1;

The reason for this is that there are many different strings that may
convert to the value '1', such as ''1'', '' 1'', or ''1a''.

Comparisons that use floating-point numbers (or values that are
converted to floating-point numbers) are approximate because such
numbers are inexact.  This might lead to results that appear
inconsistent:

     mysql> SELECT '18015376320243458' = 18015376320243458;
             -> 1
     mysql> SELECT '18015376320243459' = 18015376320243459;
             -> 0

Such results can occur because the values are converted to
floating-point numbers, which have only 53 bits of precision and are
subject to rounding:

     mysql> SELECT '18015376320243459'+0.0;
             -> 1.8015376320243e+16

Furthermore, the conversion from string to floating-point and from
integer to floating-point do not necessarily occur the same way.  The
integer may be converted to floating-point by the CPU, whereas the
string is converted digit by digit in an operation that involves
floating-point multiplications.

The results shown will vary on different systems, and can be affected by
factors such as computer architecture or the compiler version or
optimization level.  One way to avoid such problems is to use 'CAST()'
so that a value is not converted implicitly to a float-point number:

     mysql> SELECT CAST('18015376320243459' AS UNSIGNED) = 18015376320243459;
             -> 1

For more information about floating-point comparisons, see
problems-with-float.

The server includes 'dtoa', a conversion library that provides the basis
for improved conversion between string or 'DECIMAL'
values and approximate-value (see 'FLOAT'.
/see 'DOUBLE') numbers:

   * Consistent conversion results across platforms, which eliminates,
     for example, Unix versus Windows conversion differences.

   * Accurate representation of values in cases where results previously
     did not provide sufficient precision, such as for values close to
     IEEE limits.

   * Conversion of numbers to string format with the best possible
     precision.  The precision of 'dtoa' is always the same or better
     than that of the standard C library functions.

Because the conversions produced by this library differ in some cases
from non-'dtoa' results, the potential exists for incompatibilities in
applications that rely on previous results.  For example, applications
that depend on a specific exact result from previous conversions might
need adjustment to accommodate additional precision.

The 'dtoa' library provides conversions with the following properties.
D represents a value with a 'DECIMAL' or
string representation, and F represents a floating-point number in
native binary (IEEE) format.

   * F -> D conversion is done with the best possible precision,
     returning D as the shortest string that yields F when read back in
     and rounded to the nearest value in native binary format as
     specified by IEEE.

   * D -> F conversion is done such that F is the nearest native binary
     number to the input decimal string D.

These properties imply that F -> D -> F conversions are lossless unless
F is '-inf', '+inf', or 'NaN'.  The latter values are not supported
because the SQL standard defines them as invalid values for
'FLOAT' or 'DOUBLE'.

For D -> F -> D conversions, a sufficient condition for losslessness is
that D uses 15 or fewer digits of precision, is not a denormal value,
'-inf', '+inf', or 'NaN'.  In some cases, the conversion is lossless
even if D has more than 15 digits of precision, but this is not always
the case.

Implicit conversion of a numeric or temporal value to string produces a
value that has a character set and collation determined by the
'character_set_connection' and 'collation_connection' system variables.
(These variables commonly are set with 'SET NAMES'.
For information about connection character sets, see
charset-connection.)

This means that such a conversion results in a character (nonbinary)
string (a 'CHAR', 'VARCHAR', or
'LONGTEXT' value), except in the case that the connection
character set is set to 'binary'.  In that case, the conversion result
is a binary string (a 'BINARY',
'VARBINARY', or 'LONGBLOB' value).

For integer expressions, the preceding remarks about expression
_evaluation_ apply somewhat differently for expression _assignment_; for
example, in a statement such as this:

     CREATE TABLE t SELECT INTEGER_EXPR;

In this case, the table in the column resulting from the expression has
type 'INT' or 'BIGINT'.
depending on the length of the integer expression.  If the maximum
length of the expression does not fit in an 'INT',
'BIGINT' is used instead.  The length is taken
from the 'max_length' value of the 'SELECT' result set
metadata (see c-api-data-structures).  This means that you can
force a 'BIGINT' rather than 'INT'
by use of a sufficiently long expression:

     CREATE TABLE t SELECT 000000000000000000000;

12.3 Operators
==============

*Operators*

Name                          Description

'AND', '&&'                   Logical AND

'='                           Assign a value (as part of a 'SET'
                              statement, or as part of
                              the 'SET' clause in an 'UPDATE'
                              statement)

':='                          Assign a value

'BETWEEN ... AND ...'         Check whether a value is within a range
                              of values

'BINARY'                      Cast a string to a binary string

'&'                           Bitwise AND

'~'                           Bitwise inversion

'|'                           Bitwise OR

'^'                           Bitwise XOR

'CASE'                        Case operator

'DIV'                         Integer division

'/'                           Division operator

'='                           Equal operator

'<=>'                         NULL-safe equal to operator

'>'                           Greater than operator

'>='                          Greater than or equal operator

'IS'                          Test a value against a boolean

'IS NOT'                      Test a value against a boolean

'IS NOT NULL'                 NOT NULL value test

'IS NULL'                     NULL value test

'->'                          Return value from JSON column after
                              evaluating path; equivalent to
                              JSON_EXTRACT().

'->>'                         Return value from JSON column after
                              evaluating path and unquoting the result;
                              equivalent to
                              JSON_UNQUOTE(JSON_EXTRACT()).

'<<'                          Left shift

'<'                           Less than operator

'<='                          Less than or equal operator

'LIKE'                        Simple pattern matching

'-'                           Minus operator

'%', 'MOD'                    Modulo operator

'NOT', '!'                    Negates value

'NOT BETWEEN ... AND ...'     Check whether a value is not within a
                              range of values

'!=', '<>'                    Not equal operator

'NOT LIKE'                    Negation of simple pattern matching

'NOT REGEXP'                  Negation of REGEXP

'||', 'OR'                    Logical OR

'+'                           Addition operator

'REGEXP'                      Whether string matches regular expression

'>>'                          Right shift

'RLIKE'                       Whether string matches regular expression

'SOUNDS LIKE'                 Compare sounds

'*'                           Multiplication operator

'-'                           Change the sign of the argument

'XOR'                         Logical XOR

12.3.1 Operator Precedence
--------------------------

Operator precedences are shown in the following list, from highest
precedence to the lowest.  Operators that are shown together on a line
have the same precedence.

     INTERVAL
     BINARY, COLLATE
     !
     - (unary minus), ~ (unary bit inversion)
     ^
     *, /, DIV, %, MOD
     -, +
     <<, >>
     &
     |
     = (comparison), <=>, >=, >, <=, <, <>, !=, IS, LIKE, REGEXP, IN
     BETWEEN, CASE, WHEN, THEN, ELSE
     NOT
     AND, &&
     XOR
     OR, ||
     = (assignment), :=

The precedence of '=' depends on whether it is used as a comparison
operator ('=') or as an assignment operator ('=').  When used as a
comparison operator, it has the same precedence as '<=>', '>=', '>',
'<=', '<', '<>', '!=', 'IS', 'LIKE', 'REGEXP', and 'IN'.  When used as
an assignment operator, it has the same precedence as ':='.  See
set-variable, and user-variables, explain how MySQL determines
which interpretation of '=' should apply.

For operators that occur at the same precedence level within an
expression, evaluation proceeds left to right, with the exception that
assignments evaluate right to left.

The meaning of some operators depends on the SQL mode:

   * By default, '||' is a logical 'OR' operator.  With
     'PIPES_AS_CONCAT' enabled, '||' is string concatenation, with a
     precedence between '^' and the unary operators.

   * By default, '!' has a higher precedence than 'NOT'.  With
     'HIGH_NOT_PRECEDENCE' enabled, '!' and 'NOT' have the same
     precedence.

See sql-mode.

The precedence of operators determines the order of evaluation of terms
in an expression.  To override this order and group terms explicitly,
use parentheses.  For example:

     mysql> SELECT 1+2*3;
             -> 7
     mysql> SELECT (1+2)*3;
             -> 9

12.3.2 Comparison Functions and Operators
-----------------------------------------

*Comparison Operators*

Name                          Description

'BETWEEN ... AND ...'         Check whether a value is within a range
                              of values

'COALESCE()'                  Return the first non-NULL argument

'='                           Equal operator

'<=>'                         NULL-safe equal to operator

'>'                           Greater than operator

'>='                          Greater than or equal operator

'GREATEST()'                  Return the largest argument

'IN()'                        Check whether a value is within a set of
                              values

'INTERVAL()'                  Return the index of the argument that is
                              less than the first argument

'IS'                          Test a value against a boolean

'IS NOT'                      Test a value against a boolean

'IS NOT NULL'                 NOT NULL value test

'IS NULL'                     NULL value test

'ISNULL()'                    Test whether the argument is NULL

'LEAST()'                     Return the smallest argument

'<'                           Less than operator

'<='                          Less than or equal operator

'LIKE'                        Simple pattern matching

'NOT BETWEEN ... AND ...'     Check whether a value is not within a
                              range of values

'!=', '<>'                    Not equal operator

'NOT IN()'                    Check whether a value is not within a set
                              of values

'NOT LIKE'                    Negation of simple pattern matching

'STRCMP()'                    Compare two strings

Comparison operations result in a value of '1' ('TRUE'), '0' ('FALSE'),
or 'NULL'.  These operations work for both numbers and strings.  Strings
are automatically converted to numbers and numbers to strings as
necessary.

The following relational comparison operators can be used to compare not
only scalar operands, but row operands:

     =  >  <  >=  <=  <>  !=

The descriptions for those operators later in this section detail how
they work with row operands.  For additional examples of row comparisons
in the context of row subqueries, see row-subqueries.

Some of the functions in this section return values other than '1'
('TRUE'), '0' ('FALSE'), or 'NULL'.  'LEAST()' and 'GREATEST()' are
examples of such functions; see type-conversion, describes the rules
for comparison operations performed by these and similar functions for
determining their return values.

To convert a value to a specific type for comparison purposes, you can
use the 'CAST()' function.  String values can be converted to a
different character set using 'CONVERT()'.  See cast-functions.

By default, string comparisons are not case-sensitive and use the
current character set.  The default is 'latin1' (cp1252 West European),
which also works well for English.

   *
     '='

     Equal:

          mysql> SELECT 1 = 0;
                  -> 0
          mysql> SELECT '0' = 0;
                  -> 1
          mysql> SELECT '0.0' = 0;
                  -> 1
          mysql> SELECT '0.01' = 0;
                  -> 0
          mysql> SELECT '.01' = 0.01;
                  -> 1

     For row comparisons, '(a, b) = (x, y)' is equivalent to:

          (a = x) AND (b = y)

   *
     '<=>'

     'NULL'-safe equal.  This operator performs an equality comparison
     like the '=' operator, but returns '1' rather than 'NULL' if both
     operands are 'NULL', and '0' rather than 'NULL' if one operand is
     'NULL'.

     The '<=>' operator is equivalent to the standard SQL 'IS NOT
     DISTINCT FROM' operator.

          mysql> SELECT 1 <=> 1, NULL <=> NULL, 1 <=> NULL;
                  -> 1, 1, 0
          mysql> SELECT 1 = 1, NULL = NULL, 1 = NULL;
                  -> 1, NULL, NULL

     For row comparisons, '(a, b) <=> (x, y)' is equivalent to:

          (a <=> x) AND (b <=> y)

   *
     '<>', '!='

     Not equal:

          mysql> SELECT '.01' <> '0.01';
                  -> 1
          mysql> SELECT .01 <> '0.01';
                  -> 0
          mysql> SELECT 'zapp' <> 'zappp';
                  -> 1

     For row comparisons, '(a, b) <> (x, y)' and '(a, b) != (x, y)' are
     equivalent to:

          (a <> x) OR (b <> y)

   *
     '<='

     Less than or equal:

          mysql> SELECT 0.1 <= 2;
                  -> 1

     For row comparisons, '(a, b) <= (x, y)' is equivalent to:

          (a < x) OR ((a = x) AND (b <= y))

   *
     '<'

     Less than:

          mysql> SELECT 2 < 2;
                  -> 0

     For row comparisons, '(a, b) < (x, y)' is equivalent to:

          (a < x) OR ((a = x) AND (b < y))

   *
     '>='

     Greater than or equal:

          mysql> SELECT 2 >= 2;
                  -> 1

     For row comparisons, '(a, b) >= (x, y)' is equivalent to:

          (a > x) OR ((a = x) AND (b >= y))

   *
     '>'

     Greater than:

          mysql> SELECT 2 > 2;
                  -> 0

     For row comparisons, '(a, b) > (x, y)' is equivalent to:

          (a > x) OR ((a = x) AND (b > y))

   *
     'IS BOOLEAN_VALUE'

     Tests a value against a boolean value, where BOOLEAN_VALUE can be
     'TRUE', 'FALSE', or 'UNKNOWN'.

          mysql> SELECT 1 IS TRUE, 0 IS FALSE, NULL IS UNKNOWN;
                  -> 1, 1, 1

   *
     'IS NOT BOOLEAN_VALUE'

     Tests a value against a boolean value, where BOOLEAN_VALUE can be
     'TRUE', 'FALSE', or 'UNKNOWN'.

          mysql> SELECT 1 IS NOT UNKNOWN, 0 IS NOT UNKNOWN, NULL IS NOT UNKNOWN;
                  -> 1, 1, 0

   *
     'IS NULL'

     Tests whether a value is 'NULL'.

          mysql> SELECT 1 IS NULL, 0 IS NULL, NULL IS NULL;
                  -> 0, 0, 1

     To work well with ODBC programs, MySQL supports the following extra
     features when using 'IS NULL':

        * If 'sql_auto_is_null' variable is set to 1, then after a
          statement that successfully inserts an automatically generated
          'AUTO_INCREMENT' value, you can find that value by issuing a
          statement of the following form:

               SELECT * FROM TBL_NAME WHERE AUTO_COL IS NULL

          If the statement returns a row, the value returned is the same
          as if you invoked the 'LAST_INSERT_ID()' function.  For
          details, including the return value after a multiple-row
          insert, see information-functions.  If no
          'AUTO_INCREMENT' value was successfully inserted, the
          'SELECT' statement returns no row.

          The behavior of retrieving an 'AUTO_INCREMENT' value by using
          an 'IS NULL' comparison can be disabled by setting
          'sql_auto_is_null = 0'.  See server-system-variables.

          The default value of 'sql_auto_is_null' is 0.

        * For 'DATE' and 'DATETIME'.
          columns that are declared as 'NOT NULL', you can find the
          special date ''0000-00-00'' by using a statement like this:

               SELECT * FROM TBL_NAME WHERE DATE_COLUMN IS NULL

          This is needed to get some ODBC applications to work because
          ODBC does not support a ''0000-00-00'' date value.

          See Obtaining Auto-Increment Values
          (http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-usagenotes-functionality-last-insert-id.html),
          and the description for the 'FLAG_AUTO_IS_NULL' option at
          Connector/ODBC Connection Parameters
          (http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-configuration-connection-parameters.html).

   *
     'IS NOT NULL'

     Tests whether a value is not 'NULL'.

          mysql> SELECT 1 IS NOT NULL, 0 IS NOT NULL, NULL IS NOT NULL;
                  -> 1, 1, 0

   *
     'EXPR BETWEEN MIN AND MAX'

     If EXPR is greater than or equal to MIN and EXPR is less than or
     equal to MAX, 'BETWEEN' returns '1', otherwise it returns '0'.
     This is equivalent to the expression '(MIN <= EXPR AND EXPR <=
     MAX)' if all the arguments are of the same type.  Otherwise type
     conversion takes place according to the rules described in
     type-conversion, but applied to all the three arguments.

          mysql> SELECT 2 BETWEEN 1 AND 3, 2 BETWEEN 3 and 1;
                  -> 1, 0
          mysql> SELECT 1 BETWEEN 2 AND 3;
                  -> 0
          mysql> SELECT 'b' BETWEEN 'a' AND 'c';
                  -> 1
          mysql> SELECT 2 BETWEEN 2 AND '3';
                  -> 1
          mysql> SELECT 2 BETWEEN 2 AND 'x-3';
                  -> 0

     For best results when using 'BETWEEN' with date or time values, use
     'CAST()' to explicitly convert the values to the desired data type.
     Examples: If you compare a 'DATETIME' to two
     'DATE' values, convert the 'DATE'.
     values to 'DATETIME' values.  If you use a string
     constant such as ''2001-1-1'' in a comparison to a 'DATE',
     cast the string to a 'DATE'.

   *
     'EXPR NOT BETWEEN MIN AND MAX'

     This is the same as 'NOT (EXPR BETWEEN MIN AND MAX)'.

   *
     'COALESCE(VALUE,...)'

     Returns the first non-'NULL' value in the list, or 'NULL' if there
     are no non-'NULL' values.

     The return type of 'COALESCE()' is the aggregated type of the
     argument types.

          mysql> SELECT COALESCE(NULL,1);
                  -> 1
          mysql> SELECT COALESCE(NULL,NULL,NULL);
                  -> NULL

   *
     'GREATEST(VALUE1,VALUE2,...)'

     With two or more arguments, returns the largest (maximum-valued)
     argument.  The arguments are compared using the same rules as for
     'LEAST()'.

          mysql> SELECT GREATEST(2,0);
                  -> 2
          mysql> SELECT GREATEST(34.0,3.0,5.0,767.0);
                  -> 767.0
          mysql> SELECT GREATEST('B','A','C');
                  -> 'C'

     'GREATEST()' returns 'NULL' if any argument is 'NULL'.

   *
     'EXPR IN (VALUE,...)'

     Returns '1' if EXPR is equal to any of the values in the 'IN' list,
     else returns '0'.  If all values are constants, they are evaluated
     according to the type of EXPR and sorted.  The search for the item
     then is done using a binary search.  This means 'IN' is very quick
     if the 'IN' value list consists entirely of constants.  Otherwise,
     type conversion takes place according to the rules described in
     type-conversion, but applied to all the arguments.

          mysql> SELECT 2 IN (0,3,5,7);
                  -> 0
          mysql> SELECT 'wefwf' IN ('wee','wefwf','weg');
                  -> 1

     'IN' can be used to compare row constructors:

          mysql> SELECT (3,4) IN ((1,2), (3,4));
                  -> 1
          mysql> SELECT (3,4) IN ((1,2), (3,5));
                  -> 0

     You should never mix quoted and unquoted values in an 'IN' list
     because the comparison rules for quoted values (such as strings)
     and unquoted values (such as numbers) differ.  Mixing types may
     therefore lead to inconsistent results.  For example, do not write
     an 'IN' expression like this:

          SELECT val1 FROM tbl1 WHERE val1 IN (1,2,'a');

     Instead, write it like this:

          SELECT val1 FROM tbl1 WHERE val1 IN ('1','2','a');

     The number of values in the 'IN' list is only limited by the
     'max_allowed_packet' value.

     To comply with the SQL standard, 'IN' returns 'NULL' not only if
     the expression on the left hand side is 'NULL', but also if no
     match is found in the list and one of the expressions in the list
     is 'NULL'.

     'IN()' syntax can also be used to write certain types of
     subqueries.  See any-in-some-subqueries.

   *
     'EXPR NOT IN (VALUE,...)'

     This is the same as 'NOT (EXPR IN (VALUE,...))'.

   *
     'ISNULL(EXPR)'

     If EXPR is 'NULL', 'ISNULL()' returns '1', otherwise it returns
     '0'.

          mysql> SELECT ISNULL(1+1);
                  -> 0
          mysql> SELECT ISNULL(1/0);
                  -> 1

     'ISNULL()' can be used instead of '=' to test whether a value is
     'NULL'.  (Comparing a value to 'NULL' using '=' always yields
     'NULL'.)

     The 'ISNULL()' function shares some special behaviors with the 'IS
     NULL' comparison operator.  See the description of 'IS NULL'.

   *
     'INTERVAL(N,N1,N2,N3,...)'

     Returns '0' if N < N1, '1' if N < N2 and so on or '-1' if N is
     'NULL'.  All arguments are treated as integers.  It is required
     that N1 < N2 < N3 < '...' < NN for this function to work correctly.
     This is because a binary search is used (very fast).

          mysql> SELECT INTERVAL(23, 1, 15, 17, 30, 44, 200);
                  -> 3
          mysql> SELECT INTERVAL(10, 1, 10, 100, 1000);
                  -> 2
          mysql> SELECT INTERVAL(22, 23, 30, 44, 200);
                  -> 0

   *
     'LEAST(VALUE1,VALUE2,...)'

     With two or more arguments, returns the smallest (minimum-valued)
     argument.  The arguments are compared using the following rules:

        * If any argument is 'NULL', the result is 'NULL'.  No
          comparison is needed.

        * If all arguments are integer-valued, they are compared as
          integers.

        * If at least one argument is double precision, they are
          compared as double-precision values.  Otherwise, if at least
          one argument is a 'DECIMAL' value,
          they are compared as 'DECIMAL'.
          values.

        * If the arguments comprise a mix of numbers and strings, they
          are compared as numbers.

        * If any argument is a nonbinary (character) string, the
          arguments are compared as nonbinary strings.

        * In all other cases, the arguments are compared as binary
          strings.

     The return type of 'LEAST()' is the aggregated type of the
     comparison argument types.

          mysql> SELECT LEAST(2,0);
                  -> 0
          mysql> SELECT LEAST(34.0,3.0,5.0,767.0);
                  -> 3.0
          mysql> SELECT LEAST('B','A','C');
                  -> 'A'

12.3.3 Logical Operators
------------------------

*Logical Operators*

Name                          Description

'AND', '&&'                   Logical AND

'NOT', '!'                    Negates value

'||', 'OR'                    Logical OR

'XOR'                         Logical XOR

In SQL, all logical operators evaluate to 'TRUE', 'FALSE', or 'NULL'
('UNKNOWN').  In MySQL, these are implemented as 1 ('TRUE'), 0
('FALSE'), and 'NULL'.  Most of this is common to different SQL database
servers, although some servers may return any nonzero value for 'TRUE'.

MySQL evaluates any nonzero, non-'NULL' value to 'TRUE'.  For example,
the following statements all assess to 'TRUE':

     mysql> SELECT 10 IS TRUE;
     -> 1
     mysql> SELECT -10 IS TRUE;
     -> 1
     mysql> SELECT 'string' IS NOT NULL;
     -> 1

   *
     'NOT', '!'

     Logical NOT. Evaluates to '1' if the operand is '0', to '0' if the
     operand is nonzero, and 'NOT NULL' returns 'NULL'.

          mysql> SELECT NOT 10;
                  -> 0
          mysql> SELECT NOT 0;
                  -> 1
          mysql> SELECT NOT NULL;
                  -> NULL
          mysql> SELECT ! (1+1);
                  -> 0
          mysql> SELECT ! 1+1;
                  -> 1

     The last example produces '1' because the expression evaluates the
     same way as '(!1)+1'.

   *
     'AND', '&&'

     Logical AND. Evaluates to '1' if all operands are nonzero and not
     'NULL', to '0' if one or more operands are '0', otherwise 'NULL' is
     returned.

          mysql> SELECT 1 AND 1;
                  -> 1
          mysql> SELECT 1 AND 0;
                  -> 0
          mysql> SELECT 1 AND NULL;
                  -> NULL
          mysql> SELECT 0 AND NULL;
                  -> 0
          mysql> SELECT NULL AND 0;
                  -> 0

   *
     'OR', '||'

     Logical OR. When both operands are non-'NULL', the result is '1' if
     any operand is nonzero, and '0' otherwise.  With a 'NULL' operand,
     the result is '1' if the other operand is nonzero, and 'NULL'
     otherwise.  If both operands are 'NULL', the result is 'NULL'.

          mysql> SELECT 1 OR 1;
                  -> 1
          mysql> SELECT 1 OR 0;
                  -> 1
          mysql> SELECT 0 OR 0;
                  -> 0
          mysql> SELECT 0 OR NULL;
                  -> NULL
          mysql> SELECT 1 OR NULL;
                  -> 1

   *
     'XOR'

     Logical XOR. Returns 'NULL' if either operand is 'NULL'.  For
     non-'NULL' operands, evaluates to '1' if an odd number of operands
     is nonzero, otherwise '0' is returned.

          mysql> SELECT 1 XOR 1;
                  -> 0
          mysql> SELECT 1 XOR 0;
                  -> 1
          mysql> SELECT 1 XOR NULL;
                  -> NULL
          mysql> SELECT 1 XOR 1 XOR 1;
                  -> 1

     'a XOR b' is mathematically equal to '(a AND (NOT b)) OR ((NOT a)
     and b)'.

12.3.4 Assignment Operators
---------------------------

*Assignment Operators*

Name                          Description

'='                           Assign a value (as part of a 'SET'
                              statement, or as part of
                              the 'SET' clause in an 'UPDATE'
                              statement)

':='                          Assign a value

   *
     ':='

     Assignment operator.  Causes the user variable on the left hand
     side of the operator to take on the value to its right.  The value
     on the right hand side may be a literal value, another variable
     storing a value, or any legal expression that yields a scalar
     value, including the result of a query (provided that this value is
     a scalar value).  You can perform multiple assignments in the same
     'SET' statement.  You can perform multiple
     assignments in the same statement.

     Unlike '=', the ':=' operator is never interpreted as a comparison
     operator.  This means you can use ':=' in any valid SQL statement
     (not just in 'SET' statements) to assign a
     value to a variable.

          mysql> SELECT @var1, @var2;
                  -> NULL, NULL
          mysql> SELECT @var1 := 1, @var2;
                  -> 1, NULL
          mysql> SELECT @var1, @var2;
                  -> 1, NULL
          mysql> SELECT @var1, @var2 := @var1;
                  -> 1, 1
          mysql> SELECT @var1, @var2;
                  -> 1, 1

          mysql> SELECT @var1:=COUNT(*) FROM t1;
                  -> 4
          mysql> SELECT @var1;
                  -> 4

     You can make value assignments using ':=' in other statements
     besides 'SELECT', such as 'UPDATE', as
     shown here:

          mysql> SELECT @var1;
                  -> 4
          mysql> SELECT * FROM t1;
                  -> 1, 3, 5, 7

          mysql> UPDATE t1 SET c1 = 2 WHERE c1 = @var1:= 1;
          Query OK, 1 row affected (0.00 sec)
          Rows matched: 1  Changed: 1  Warnings: 0

          mysql> SELECT @var1;
                  -> 1
          mysql> SELECT * FROM t1;
                  -> 2, 3, 5, 7

     While it is also possible both to set and to read the value of the
     same variable in a single SQL statement using the ':=' operator,
     this is not recommended.  See user-variables, explains why you
     should avoid doing this.

   *
     '='

     This operator is used to perform value assignments in two cases,
     described in the next two paragraphs.

     Within a 'SET' statement, '=' is treated as an
     assignment operator that causes the user variable on the left hand
     side of the operator to take on the value to its right.  (In other
     words, when used in a 'SET' statement, '=' is
     treated identically to ':='.)  The value on the right hand side may
     be a literal value, another variable storing a value, or any legal
     expression that yields a scalar value, including the result of a
     query (provided that this value is a scalar value).  You can
     perform multiple assignments in the same 'SET'.
     statement.

     In the 'SET' clause of an 'UPDATE' statement, '='
     also acts as an assignment operator; in this case, however, it
     causes the column named on the left hand side of the operator to
     assume the value given to the right, provided any 'WHERE'
     conditions that are part of the 'UPDATE' are met.
     You can make multiple assignments in the same 'SET' clause of an
     'UPDATE' statement.

     In any other context, '=' is treated as a comparison operator.

          mysql> SELECT @var1, @var2;
                  -> NULL, NULL
          mysql> SELECT @var1 := 1, @var2;
                  -> 1, NULL
          mysql> SELECT @var1, @var2;
                  -> 1, NULL
          mysql> SELECT @var1, @var2 := @var1;
                  -> 1, 1
          mysql> SELECT @var1, @var2;
                  -> 1, 1

     For more information, see set-variable, update, and
     subqueries.

12.4 Control Flow Functions
===========================

*Flow Control Operators*

Name                          Description

'CASE'                        Case operator

'IF()'                        If/else construct

'IFNULL()'                    Null if/else construct

'NULLIF()'                    Return NULL if expr1 = expr2

   *
     'CASE VALUE WHEN [COMPARE_VALUE] THEN RESULT [WHEN [COMPARE_VALUE]
     THEN RESULT ...] [ELSE RESULT] END'

     'CASE WHEN [CONDITION] THEN RESULT [WHEN [CONDITION] THEN RESULT
     ...] [ELSE RESULT] END'

     The first 'CASE' syntax returns the RESULT for the first
     'VALUE=COMPARE_VALUE' comparison that is true.  The second syntax
     returns the result for the first condition that is true.  If no
     comparison or condition is true, the result after 'ELSE' is
     returned, or 'NULL' if there is no 'ELSE' part.

     *Note*:

     The syntax of the 'CASE' _expression_ described here differs
     slightly from that of the SQL 'CASE'. _statement_
     described in case, for use inside stored programs.  The
     'CASE' statement cannot have an 'ELSE NULL' clause,
     and it is terminated with 'END CASE' instead of 'END'.

     The return type of a 'CASE' expression result is the aggregated
     type of all result values.

          mysql> SELECT CASE 1 WHEN 1 THEN 'one'
              ->     WHEN 2 THEN 'two' ELSE 'more' END;
                  -> 'one'
          mysql> SELECT CASE WHEN 1>0 THEN 'true' ELSE 'false' END;
                  -> 'true'
          mysql> SELECT CASE BINARY 'B'
              ->     WHEN 'a' THEN 1 WHEN 'b' THEN 2 END;
                  -> NULL

   *
     'IF(EXPR1,EXPR2,EXPR3)'

     If EXPR1 is 'TRUE' ('EXPR1 <> 0' and 'EXPR1 <> NULL'), 'IF()'
     returns EXPR2.  Otherwise, it returns EXPR3.

     *Note*:

     There is also an 'IF'. _statement_, which differs from
     the 'IF()' _function_ described here.  See if.

     If only one of EXPR2 or EXPR3 is explicitly 'NULL', the result type
     of the 'IF()' function is the type of the non-'NULL' expression.

     The default return type of 'IF()' (which may matter when it is
     stored into a temporary table) is calculated as follows:

        * If EXPR2 or EXPR3 produce a string, the result is a string.

          If EXPR2 and EXPR3 are both strings, the result is
          case-sensitive if either string is case sensitive.

        * If EXPR2 or EXPR3 produce a floating-point value, the result
          is a floating-point value.

        * If EXPR2 or EXPR3 produce an integer, the result is an
          integer.

          mysql> SELECT IF(1>2,2,3);
                  -> 3
          mysql> SELECT IF(1<2,'yes','no');
                  -> 'yes'
          mysql> SELECT IF(STRCMP('test','test1'),'no','yes');
                  -> 'no'

   *
     'IFNULL(EXPR1,EXPR2)'

     If EXPR1 is not 'NULL', 'IFNULL()' returns EXPR1; otherwise it
     returns EXPR2.

          mysql> SELECT IFNULL(1,0);
                  -> 1
          mysql> SELECT IFNULL(NULL,10);
                  -> 10
          mysql> SELECT IFNULL(1/0,10);
                  -> 10
          mysql> SELECT IFNULL(1/0,'yes');
                  -> 'yes'

     The default return type of 'IFNULL(EXPR1,EXPR2)' is the more
     'general' of the two expressions, in the order 'STRING', 'REAL', or
     'INTEGER'.  Consider the case of a table based on expressions or
     where MySQL must internally store a value returned by 'IFNULL()' in
     a temporary table:

          mysql> CREATE TABLE tmp SELECT IFNULL(1,'test') AS test;
          mysql> DESCRIBE tmp;
          +-------+--------------+------+-----+---------+-------+
          | Field | Type         | Null | Key | Default | Extra |
          +-------+--------------+------+-----+---------+-------+
          | test  | varbinary(4) | NO   |     |         |       |
          +-------+--------------+------+-----+---------+-------+

     In this example, the type of the 'test' column is
     'VARBINARY(4)'. (a string type).

   *
     'NULLIF(EXPR1,EXPR2)'

     Returns 'NULL' if 'EXPR1 = EXPR2' is true, otherwise returns EXPR1.
     This is the same as 'CASE WHEN EXPR1 = EXPR2 THEN NULL ELSE EXPR1
     END'.

     The return value has the same type as the first argument.

          mysql> SELECT NULLIF(1,1);
                  -> NULL
          mysql> SELECT NULLIF(1,2);
                  -> 1

     *Note*:

     MySQL evaluates EXPR1 twice if the arguments are not equal.

12.5 String Functions
=====================

*String Operators*

Name                          Description

'ASCII()'                     Return numeric value of left-most
                              character

'BIN()'                       Return a string containing binary
                              representation of a number

'BIT_LENGTH()'                Return length of argument in bits

'CHAR()'                      Return the character for each integer
                              passed

'CHAR_LENGTH()'               Return number of characters in argument

'CHARACTER_LENGTH()'          Synonym for CHAR_LENGTH()

'CONCAT()'                    Return concatenated string

'CONCAT_WS()'                 Return concatenate with separator

'ELT()'                       Return string at index number

'EXPORT_SET()'                Return a string such that for every bit
                              set in the value bits, you get an on
                              string and for every unset bit, you get
                              an off string

'FIELD()'                     Return the index (position) of the first
                              argument in the subsequent arguments

'FIND_IN_SET()'               Return the index position of the first
                              argument within the second argument

'FORMAT()'                    Return a number formatted to specified
                              number of decimal places

'FROM_BASE64()'               Decode to a base-64 string and return
                              result

'HEX()'                       Return a hexadecimal representation of a
                              decimal or string value

'INSERT()'                    Insert a substring at the specified
                              position up to the specified number of
                              characters

'INSTR()'                     Return the index of the first occurrence
                              of substring

'LCASE()'                     Synonym for LOWER()

'LEFT()'                      Return the leftmost number of characters
                              as specified

'LENGTH()'                    Return the length of a string in bytes

'LIKE'                        Simple pattern matching

'LOAD_FILE()'                 Load the named file

'LOCATE()'                    Return the position of the first
                              occurrence of substring

'LOWER()'                     Return the argument in lowercase

'LPAD()'                      Return the string argument, left-padded
                              with the specified string

'LTRIM()'                     Remove leading spaces

'MAKE_SET()'                  Return a set of comma-separated strings
                              that have the corresponding bit in bits
                              set

'MATCH'                       Perform full-text search

'MID()'                       Return a substring starting from the
                              specified position

'NOT LIKE'                    Negation of simple pattern matching

'NOT REGEXP'                  Negation of REGEXP

'OCT()'                       Return a string containing octal
                              representation of a number

'OCTET_LENGTH()'              Synonym for LENGTH()

'ORD()'                       Return character code for leftmost
                              character of the argument

'POSITION()'                  Synonym for LOCATE()

'QUOTE()'                     Escape the argument for use in an SQL
                              statement

'REGEXP'                      Whether string matches regular expression

'REPEAT()'                    Repeat a string the specified number of
                              times

'REPLACE()'                   Replace occurrences of a specified string

'REVERSE()'                   Reverse the characters in a string

'RIGHT()'                     Return the specified rightmost number of
                              characters

'RLIKE'                       Whether string matches regular expression

'RPAD()'                      Append string the specified number of
                              times

'RTRIM()'                     Remove trailing spaces

'SOUNDEX()'                   Return a soundex string

'SOUNDS LIKE'                 Compare sounds

'SPACE()'                     Return a string of the specified number
                              of spaces

'STRCMP()'                    Compare two strings

'SUBSTR()'                    Return the substring as specified

'SUBSTRING()'                 Return the substring as specified

'SUBSTRING_INDEX()'           Return a substring from a string before
                              the specified number of occurrences of
                              the delimiter

'TO_BASE64()'                 Return the argument converted to a
                              base-64 string

'TRIM()'                      Remove leading and trailing spaces

'UCASE()'                     Synonym for UPPER()

'UNHEX()'                     Return a string containing hex
                              representation of a number

'UPPER()'                     Convert to uppercase

'WEIGHT_STRING()'             Return the weight string for a string

String-valued functions return 'NULL' if the length of the result would
be greater than the value of the 'max_allowed_packet' system variable.
See server-configuration.

For functions that operate on string positions, the first position is
numbered 1.

For functions that take length arguments, noninteger arguments are
rounded to the nearest integer.

   *
     'ASCII(STR)'

     Returns the numeric value of the leftmost character of the string
     STR.  Returns '0' if STR is the empty string.  Returns 'NULL' if
     STR is 'NULL'.  'ASCII()' works for 8-bit characters.

          mysql> SELECT ASCII('2');
                  -> 50
          mysql> SELECT ASCII(2);
                  -> 50
          mysql> SELECT ASCII('dx');
                  -> 100

     See also the 'ORD()' function.

   *
     'BIN(N)'

     Returns a string representation of the binary value of N, where N
     is a longlong (see 'BIGINT') number.  This is
     equivalent to 'CONV(N,10,2)'.  Returns 'NULL' if N is 'NULL'.

          mysql> SELECT BIN(12);
                  -> '1100'

   *
     'BIT_LENGTH(STR)'

     Returns the length of the string STR in bits.

          mysql> SELECT BIT_LENGTH('text');
                  -> 32

   *
     'CHAR(N,... [USING CHARSET_NAME])'

     'CHAR()' interprets each argument N as an integer and returns a
     string consisting of the characters given by the code values of
     those integers.  'NULL' values are skipped.

          mysql> SELECT CHAR(77,121,83,81,'76');
                  -> 'MySQL'
          mysql> SELECT CHAR(77,77.3,'77.3');
                  -> 'MMM'

     'CHAR()' arguments larger than 255 are converted into multiple
     result bytes.  For example, 'CHAR(256)' is equivalent to
     'CHAR(1,0)', and 'CHAR(256*256)' is equivalent to 'CHAR(1,0,0)':

          mysql> SELECT HEX(CHAR(1,0)), HEX(CHAR(256));
          +----------------+----------------+
          | HEX(CHAR(1,0)) | HEX(CHAR(256)) |
          +----------------+----------------+
          | 0100           | 0100           |
          +----------------+----------------+
          mysql> SELECT HEX(CHAR(1,0,0)), HEX(CHAR(256*256));
          +------------------+--------------------+
          | HEX(CHAR(1,0,0)) | HEX(CHAR(256*256)) |
          +------------------+--------------------+
          | 010000           | 010000             |
          +------------------+--------------------+

     By default, 'CHAR()' returns a binary string.  To produce a string
     in a given character set, use the optional 'USING' clause:

          mysql> SELECT CHARSET(CHAR(X'65')), CHARSET(CHAR(X'65' USING utf8));
          +----------------------+---------------------------------+
          | CHARSET(CHAR(X'65')) | CHARSET(CHAR(X'65' USING utf8)) |
          +----------------------+---------------------------------+
          | binary               | utf8                            |
          +----------------------+---------------------------------+

     If 'USING' is given and the result string is illegal for the given
     character set, a warning is issued.  Also, if strict SQL mode is
     enabled, the result from 'CHAR()' becomes 'NULL'.

   *
     'CHAR_LENGTH(STR)'

     Returns the length of the string STR, measured in characters.  A
     multibyte character counts as a single character.  This means that
     for a string containing five 2-byte characters, 'LENGTH()' returns
     '10', whereas 'CHAR_LENGTH()' returns '5'.

   *
     'CHARACTER_LENGTH(STR)'

     'CHARACTER_LENGTH()' is a synonym for 'CHAR_LENGTH()'.

   *
     'CONCAT(STR1,STR2,...)'

     Returns the string that results from concatenating the arguments.
     May have one or more arguments.  If all arguments are nonbinary
     strings, the result is a nonbinary string.  If the arguments
     include any binary strings, the result is a binary string.  A
     numeric argument is converted to its equivalent nonbinary string
     form.

     'CONCAT()' returns 'NULL' if any argument is 'NULL'.

          mysql> SELECT CONCAT('My', 'S', 'QL');
                  -> 'MySQL'
          mysql> SELECT CONCAT('My', NULL, 'QL');
                  -> NULL
          mysql> SELECT CONCAT(14.3);
                  -> '14.3'

     For quoted strings, concatenation can be performed by placing the
     strings next to each other:

          mysql> SELECT 'My' 'S' 'QL';
                  -> 'MySQL'

   *
     'CONCAT_WS(SEPARATOR,STR1,STR2,...)'

     'CONCAT_WS()' stands for Concatenate With Separator and is a
     special form of 'CONCAT()'.  The first argument is the separator
     for the rest of the arguments.  The separator is added between the
     strings to be concatenated.  The separator can be a string, as can
     the rest of the arguments.  If the separator is 'NULL', the result
     is 'NULL'.

          mysql> SELECT CONCAT_WS(',','First name','Second name','Last Name');
                  -> 'First name,Second name,Last Name'
          mysql> SELECT CONCAT_WS(',','First name',NULL,'Last Name');
                  -> 'First name,Last Name'

     'CONCAT_WS()' does not skip empty strings.  However, it does skip
     any 'NULL' values after the separator argument.

   *
     'ELT(N,STR1,STR2,STR3,...)'

     'ELT()' returns the Nth element of the list of strings: STR1 if N =
     '1', STR2 if N = '2', and so on.  Returns 'NULL' if N is less than
     '1' or greater than the number of arguments.  'ELT()' is the
     complement of 'FIELD()'.

          mysql> SELECT ELT(1, 'Aa', 'Bb', 'Cc', 'Dd');
                  -> 'Aa'
          mysql> SELECT ELT(4, 'Aa', 'Bb', 'Cc', 'Dd');
                  -> 'Dd'

   *
     'EXPORT_SET(BITS,ON,OFF[,SEPARATOR[,NUMBER_OF_BITS]])'

     Returns a string such that for every bit set in the value BITS, you
     get an ON string and for every bit not set in the value, you get an
     OFF string.  Bits in BITS are examined from right to left (from
     low-order to high-order bits).  Strings are added to the result
     from left to right, separated by the SEPARATOR string (the default
     being the comma character ',').  The number of bits examined is
     given by NUMBER_OF_BITS, which has a default of 64 if not
     specified.  NUMBER_OF_BITS is silently clipped to 64 if larger than
     64.  It is treated as an unsigned integer, so a value of −1 is
     effectively the same as 64.

          mysql> SELECT EXPORT_SET(5,'Y','N',',',4);
                  -> 'Y,N,Y,N'
          mysql> SELECT EXPORT_SET(6,'1','0',',',10);
                  -> '0,1,1,0,0,0,0,0,0,0'

   *
     'FIELD(STR,STR1,STR2,STR3,...)'

     Returns the index (position) of STR in the STR1, STR2, STR3, '...'
     list.  Returns '0' if STR is not found.

     If all arguments to 'FIELD()' are strings, all arguments are
     compared as strings.  If all arguments are numbers, they are
     compared as numbers.  Otherwise, the arguments are compared as
     double.

     If STR is 'NULL', the return value is '0' because 'NULL' fails
     equality comparison with any value.  'FIELD()' is the complement of
     'ELT()'.

          mysql> SELECT FIELD('Bb', 'Aa', 'Bb', 'Cc', 'Dd', 'Ff');
                  -> 2
          mysql> SELECT FIELD('Gg', 'Aa', 'Bb', 'Cc', 'Dd', 'Ff');
                  -> 0

   *
     'FIND_IN_SET(STR,STRLIST)'

     Returns a value in the range of 1 to N if the string STR is in the
     string list STRLIST consisting of N substrings.  A string list is a
     string composed of substrings separated by ',' characters.  If the
     first argument is a constant string and the second is a column of
     type 'SET', the 'FIND_IN_SET()' function is optimized to
     use bit arithmetic.  Returns '0' if STR is not in STRLIST or if
     STRLIST is the empty string.  Returns 'NULL' if either argument is
     'NULL'.  This function does not work properly if the first argument
     contains a comma (',') character.

          mysql> SELECT FIND_IN_SET('b','a,b,c,d');
                  -> 2

   *
     'FORMAT(X,D[,LOCALE])'

     Formats the number X to a format like ''#,###,###.##'', rounded to
     D decimal places, and returns the result as a string.  If D is '0',
     the result has no decimal point or fractional part.

     The optional third parameter enables a locale to be specified to be
     used for the result number's decimal point, thousands separator,
     and grouping between separators.  Permissible locale values are the
     same as the legal values for the 'lc_time_names' system variable
     (see locale-support).  If no locale is specified, the
     default is ''en_US''.

          mysql> SELECT FORMAT(12332.123456, 4);
                  -> '12,332.1235'
          mysql> SELECT FORMAT(12332.1,4);
                  -> '12,332.1000'
          mysql> SELECT FORMAT(12332.2,0);
                  -> '12,332'
          mysql> SELECT FORMAT(12332.2,2,'de_DE');
                  -> '12.332,20'

   *
     'FROM_BASE64(STR)'

     Takes a string encoded with the base-64 encoded rules used by
     'TO_BASE64()' and returns the decoded result as a binary string.
     The result is 'NULL' if the argument is 'NULL' or not a valid
     base-64 string.  See the description of 'TO_BASE64()' for details
     about the encoding and decoding rules.

          mysql> SELECT TO_BASE64('abc'), FROM_BASE64(TO_BASE64('abc'));
                  -> 'JWJj', 'abc'

   *
     'HEX(STR)', 'HEX(N)'

     For a string argument STR, 'HEX()' returns a hexadecimal string
     representation of STR where each byte of each character in STR is
     converted to two hexadecimal digits.  (Multibyte characters
     therefore become more than two digits.)  The inverse of this
     operation is performed by the 'UNHEX()' function.

     For a numeric argument N, 'HEX()' returns a hexadecimal string
     representation of the value of N treated as a longlong (see
     'BIGINT') number.  This is equivalent to
     'CONV(N,10,16)'.  The inverse of this operation is performed by
     'CONV(HEX(N),16,10)'.

          mysql> SELECT X'616263', HEX('abc'), UNHEX(HEX('abc'));
                  -> 'abc', 616263, 'abc'
          mysql> SELECT HEX(255), CONV(HEX(255),16,10);
                  -> 'FF', 255

   *
     'INSERT(STR,POS,LEN,NEWSTR)'

     Returns the string STR, with the substring beginning at position
     POS and LEN characters long replaced by the string NEWSTR.  Returns
     the original string if POS is not within the length of the string.
     Replaces the rest of the string from position POS if LEN is not
     within the length of the rest of the string.  Returns 'NULL' if any
     argument is 'NULL'.

          mysql> SELECT INSERT('Quadratic', 3, 4, 'What');
                  -> 'QuWhattic'
          mysql> SELECT INSERT('Quadratic', -1, 4, 'What');
                  -> 'Quadratic'
          mysql> SELECT INSERT('Quadratic', 3, 100, 'What');
                  -> 'QuWhat'

     This function is multibyte safe.

   *
     'INSTR(STR,SUBSTR)'

     Returns the position of the first occurrence of substring SUBSTR in
     string STR.  This is the same as the two-argument form of
     'LOCATE()', except that the order of the arguments is reversed.

          mysql> SELECT INSTR('foobarbar', 'bar');
                  -> 4
          mysql> SELECT INSTR('xbar', 'foobar');
                  -> 0

     This function is multibyte safe, and is case-sensitive only if at
     least one argument is a binary string.

   *
     'LCASE(STR)'

     'LCASE()' is a synonym for 'LOWER()'.

     In MySQL 5.7, 'LCASE()' used in a view is rewritten as 'LOWER()'
     when storing the view's definition.  (Bug #12844279)

   *
     'LEFT(STR,LEN)'

     Returns the leftmost LEN characters from the string STR, or 'NULL'
     if any argument is 'NULL'.

          mysql> SELECT LEFT('foobarbar', 5);
                  -> 'fooba'

     This function is multibyte safe.

   *
     'LENGTH(STR)'

     Returns the length of the string STR, measured in bytes.  A
     multibyte character counts as multiple bytes.  This means that for
     a string containing five 2-byte characters, 'LENGTH()' returns
     '10', whereas 'CHAR_LENGTH()' returns '5'.

          mysql> SELECT LENGTH('text');
                  -> 4

     *Note*:

     The 'Length()' OpenGIS spatial function is named 'ST_Length()' in
     MySQL.

   *
     'LOAD_FILE(FILE_NAME)'

     Reads the file and returns the file contents as a string.  To use
     this function, the file must be located on the server host, you
     must specify the full path name to the file, and you must have the
     'FILE' privilege.  The file must be readable by all and its size
     less than 'max_allowed_packet' bytes.  If the 'secure_file_priv'
     system variable is set to a nonempty directory name, the file to be
     loaded must be located in that directory.

     If the file does not exist or cannot be read because one of the
     preceding conditions is not satisfied, the function returns 'NULL'.

     The 'character_set_filesystem' system variable controls
     interpretation of file names that are given as literal strings.

          mysql> UPDATE t
                      SET blob_col=LOAD_FILE('/tmp/picture')
                      WHERE id=1;

   *
     'LOCATE(SUBSTR,STR)', 'LOCATE(SUBSTR,STR,POS)'

     The first syntax returns the position of the first occurrence of
     substring SUBSTR in string STR.  The second syntax returns the
     position of the first occurrence of substring SUBSTR in string STR,
     starting at position POS.  Returns '0' if SUBSTR is not in STR.
     Returns 'NULL' if SUBSTR or STR is 'NULL'.

          mysql> SELECT LOCATE('bar', 'foobarbar');
                  -> 4
          mysql> SELECT LOCATE('xbar', 'foobar');
                  -> 0
          mysql> SELECT LOCATE('bar', 'foobarbar', 5);
                  -> 7

     This function is multibyte safe, and is case-sensitive only if at
     least one argument is a binary string.

   *
     'LOWER(STR)'

     Returns the string STR with all characters changed to lowercase
     according to the current character set mapping.  The default is
     'latin1' (cp1252 West European).

          mysql> SELECT LOWER('QUADRATICALLY');
                  -> 'quadratically'

     'LOWER()' (and 'UPPER()') are ineffective when applied to binary
     strings (see 'BINARY', 'VARBINARY',
     see 'BLOB').  To perform lettercase
     conversion, convert the string to a nonbinary string:

          mysql> SET @str = BINARY 'New York';
          mysql> SELECT LOWER(@str), LOWER(CONVERT(@str USING latin1));
          +-------------+-----------------------------------+
          | LOWER(@str) | LOWER(CONVERT(@str USING latin1)) |
          +-------------+-----------------------------------+
          | New York    | new york                          |
          +-------------+-----------------------------------+

     For collations of Unicode character sets, 'LOWER()' and 'UPPER()'
     work according to the Unicode Collation Algorithm (UCA) version in
     the collation name, if there is one, and UCA 4.0.0 if no version is
     specified.  For example, 'utf8_unicode_520_ci' works according to
     UCA 5.2.0, whereas 'utf8_unicode_ci' works according to UCA 4.0.0.
     See charset-unicode-sets.

     This function is multibyte safe.

     In previous versions of MySQL, 'LOWER()' used within a view was
     rewritten as 'LCASE()' when storing the view's definition.  In
     MySQL 5.7, 'LOWER()' is never rewritten in such cases, but
     'LCASE()' used within views is instead rewritten as 'LOWER()'.
     (Bug #12844279)

   *
     'LPAD(STR,LEN,PADSTR)'

     Returns the string STR, left-padded with the string PADSTR to a
     length of LEN characters.  If STR is longer than LEN, the return
     value is shortened to LEN characters.

          mysql> SELECT LPAD('hi',4,'??');
                  -> '??hi'
          mysql> SELECT LPAD('hi',1,'??');
                  -> 'h'

   *
     'LTRIM(STR)'

     Returns the string STR with leading space characters removed.

          mysql> SELECT LTRIM('  barbar');
                  -> 'barbar'

     This function is multibyte safe.

   *
     'MAKE_SET(BITS,STR1,STR2,...)'

     Returns a set value (a string containing substrings separated by
     ',' characters) consisting of the strings that have the
     corresponding bit in BITS set.  STR1 corresponds to bit 0, STR2 to
     bit 1, and so on.  'NULL' values in STR1, STR2, '...' are not
     appended to the result.

          mysql> SELECT MAKE_SET(1,'a','b','c');
                  -> 'a'
          mysql> SELECT MAKE_SET(1 | 4,'hello','nice','world');
                  -> 'hello,world'
          mysql> SELECT MAKE_SET(1 | 4,'hello','nice',NULL,'world');
                  -> 'hello'
          mysql> SELECT MAKE_SET(0,'a','b','c');
                  -> ''

   *
     'MID(STR,POS,LEN)'

     'MID(STR,POS,LEN)' is a synonym for 'SUBSTRING(STR,POS,LEN)'.

   *
     'OCT(N)'

     Returns a string representation of the octal value of N, where N is
     a longlong (see 'BIGINT') number.  This is
     equivalent to 'CONV(N,10,8)'.  Returns 'NULL' if N is 'NULL'.

          mysql> SELECT OCT(12);
                  -> '14'

   *
     'OCTET_LENGTH(STR)'

     'OCTET_LENGTH()' is a synonym for 'LENGTH()'.

   *
     'ORD(STR)'

     If the leftmost character of the string STR is a multibyte
     character, returns the code for that character, calculated from the
     numeric values of its constituent bytes using this formula:

            (1st byte code)
          + (2nd byte code * 256)
          + (3rd byte code * 256^2) ...

     If the leftmost character is not a multibyte character, 'ORD()'
     returns the same value as the 'ASCII()' function.

          mysql> SELECT ORD('2');
                  -> 50

   *
     'POSITION(SUBSTR IN STR)'

     'POSITION(SUBSTR IN STR)' is a synonym for 'LOCATE(SUBSTR,STR)'.

   *
     'QUOTE(STR)'

     Quotes a string to produce a result that can be used as a properly
     escaped data value in an SQL statement.  The string is returned
     enclosed by single quotation marks and with each instance of
     backslash ('\'), single quote ('''), ASCII 'NUL', and Control+Z
     preceded by a backslash.  If the argument is 'NULL', the return
     value is the word 'NULL' without enclosing single quotation marks.

          mysql> SELECT QUOTE('Don\'t!');
                  -> 'Don\'t!'
          mysql> SELECT QUOTE(NULL);
                  -> NULL

     For comparison, see the quoting rules for literal strings and
     within the C API in string-literals, and
     mysql-real-escape-string-quote.

   *
     'REPEAT(STR,COUNT)'

     Returns a string consisting of the string STR repeated COUNT times.
     If COUNT is less than 1, returns an empty string.  Returns 'NULL'
     if STR or COUNT are 'NULL'.

          mysql> SELECT REPEAT('MySQL', 3);
                  -> 'MySQLMySQLMySQL'

   *
     'REPLACE(STR,FROM_STR,TO_STR)'

     Returns the string STR with all occurrences of the string FROM_STR
     replaced by the string TO_STR.  'REPLACE()' performs a
     case-sensitive match when searching for FROM_STR.

          mysql> SELECT REPLACE('www.mysql.com', 'w', 'Ww');
                  -> 'WwWwWw.mysql.com'

     This function is multibyte safe.

   *
     'REVERSE(STR)'

     Returns the string STR with the order of the characters reversed.

          mysql> SELECT REVERSE('abc');
                  -> 'cba'

     This function is multibyte safe.

   *
     'RIGHT(STR,LEN)'

     Returns the rightmost LEN characters from the string STR, or 'NULL'
     if any argument is 'NULL'.

          mysql> SELECT RIGHT('foobarbar', 4);
                  -> 'rbar'

     This function is multibyte safe.

   *
     'RPAD(STR,LEN,PADSTR)'

     Returns the string STR, right-padded with the string PADSTR to a
     length of LEN characters.  If STR is longer than LEN, the return
     value is shortened to LEN characters.

          mysql> SELECT RPAD('hi',5,'?');
                  -> 'hi???'
          mysql> SELECT RPAD('hi',1,'?');
                  -> 'h'

     This function is multibyte safe.

   *
     'RTRIM(STR)'

     Returns the string STR with trailing space characters removed.

          mysql> SELECT RTRIM('barbar   ');
                  -> 'barbar'

     This function is multibyte safe.

   *
     'SOUNDEX(STR)'

     Returns a soundex string from STR.  Two strings that sound almost
     the same should have identical soundex strings.  A standard soundex
     string is four characters long, but the 'SOUNDEX()' function
     returns an arbitrarily long string.  You can use 'SUBSTRING()' on
     the result to get a standard soundex string.  All nonalphabetic
     characters in STR are ignored.  All international alphabetic
     characters outside the A-Z range are treated as vowels.

     *Important*:

     When using 'SOUNDEX()', you should be aware of the following
     limitations:

        * This function, as currently implemented, is intended to work
          well with strings that are in the English language only.
          Strings in other languages may not produce reliable results.

        * This function is not guaranteed to provide consistent results
          with strings that use multibyte character sets, including
          'utf-8'.  See Bug #22638 for more information.

          mysql> SELECT SOUNDEX('Hello');
                  -> 'H400'
          mysql> SELECT SOUNDEX('Quadratically');
                  -> 'Q36324'

     *Note*:

     This function implements the original Soundex algorithm, not the
     more popular enhanced version (also described by D. Knuth).  The
     difference is that original version discards vowels first and
     duplicates second, whereas the enhanced version discards duplicates
     first and vowels second.

   *
     'EXPR1 SOUNDS LIKE EXPR2'

     This is the same as 'SOUNDEX(EXPR1) = SOUNDEX(EXPR2)'.

   *
     'SPACE(N)'

     Returns a string consisting of N space characters.

          mysql> SELECT SPACE(6);
                  -> '      '

   *
     'SUBSTR(STR,POS)', 'SUBSTR(STR FROM POS)', 'SUBSTR(STR,POS,LEN)',
     'SUBSTR(STR FROM POS FOR LEN)'

     'SUBSTR()' is a synonym for 'SUBSTRING()'.

   *
     'SUBSTRING(STR,POS)', 'SUBSTRING(STR FROM POS)',
     'SUBSTRING(STR,POS,LEN)', 'SUBSTRING(STR FROM POS FOR LEN)'

     The forms without a LEN argument return a substring from string STR
     starting at position POS.  The forms with a LEN argument return a
     substring LEN characters long from string STR, starting at position
     POS.  The forms that use 'FROM' are standard SQL syntax.  It is
     also possible to use a negative value for POS.  In this case, the
     beginning of the substring is POS characters from the end of the
     string, rather than the beginning.  A negative value may be used
     for POS in any of the forms of this function.

     For all forms of 'SUBSTRING()', the position of the first character
     in the string from which the substring is to be extracted is
     reckoned as '1'.

          mysql> SELECT SUBSTRING('Quadratically',5);
                  -> 'ratically'
          mysql> SELECT SUBSTRING('foobarbar' FROM 4);
                  -> 'barbar'
          mysql> SELECT SUBSTRING('Quadratically',5,6);
                  -> 'ratica'
          mysql> SELECT SUBSTRING('Sakila', -3);
                  -> 'ila'
          mysql> SELECT SUBSTRING('Sakila', -5, 3);
                  -> 'aki'
          mysql> SELECT SUBSTRING('Sakila' FROM -4 FOR 2);
                  -> 'ki'

     This function is multibyte safe.

     If LEN is less than 1, the result is the empty string.

   *
     'SUBSTRING_INDEX(STR,DELIM,COUNT)'

     Returns the substring from string STR before COUNT occurrences of
     the delimiter DELIM.  If COUNT is positive, everything to the left
     of the final delimiter (counting from the left) is returned.  If
     COUNT is negative, everything to the right of the final delimiter
     (counting from the right) is returned.  'SUBSTRING_INDEX()'
     performs a case-sensitive match when searching for DELIM.

          mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', 2);
                  -> 'www.mysql'
          mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', -2);
                  -> 'mysql.com'

     This function is multibyte safe.

   *
     'TO_BASE64(STR)'

     Converts the string argument to base-64 encoded form and returns
     the result as a character string with the connection character set
     and collation.  If the argument is not a string, it is converted to
     a string before conversion takes place.  The result is 'NULL' if
     the argument is 'NULL'.  Base-64 encoded strings can be decoded
     using the 'FROM_BASE64()' function.

          mysql> SELECT TO_BASE64('abc'), FROM_BASE64(TO_BASE64('abc'));
                  -> 'JWJj', 'abc'

     Different base-64 encoding schemes exist.  These are the encoding
     and decoding rules used by 'TO_BASE64()' and 'FROM_BASE64()':

        * The encoding for alphabet value 62 is ''+''.

        * The encoding for alphabet value 63 is ''/''.

        * Encoded output consists of groups of 4 printable characters.
          Each 3 bytes of the input data are encoded using 4 characters.
          If the last group is incomplete, it is padded with ''=''
          characters to a length of 4.

        * A newline is added after each 76 characters of encoded output
          to divide long output into multiple lines.

        * Decoding recognizes and ignores newline, carriage return, tab,
          and space.

   *
     'TRIM([{BOTH | LEADING | TRAILING} [REMSTR] FROM] STR)',
     'TRIM([REMSTR FROM] STR)'

     Returns the string STR with all REMSTR prefixes or suffixes
     removed.  If none of the specifiers 'BOTH', 'LEADING', or
     'TRAILING' is given, 'BOTH' is assumed.  REMSTR is optional and, if
     not specified, spaces are removed.

          mysql> SELECT TRIM('  bar   ');
                  -> 'bar'
          mysql> SELECT TRIM(LEADING 'x' FROM 'xxxbarxxx');
                  -> 'barxxx'
          mysql> SELECT TRIM(BOTH 'x' FROM 'xxxbarxxx');
                  -> 'bar'
          mysql> SELECT TRIM(TRAILING 'xyz' FROM 'barxxyz');
                  -> 'barx'

     This function is multibyte safe.

   *
     'UCASE(STR)'

     'UCASE()' is a synonym for 'UPPER()'.

     In MySQL 5.7, 'UCASE()' used in a view is rewritten as 'UPPER()'
     when storing the view's definition.  (Bug #12844279)

   *
     'UNHEX(STR)'

     For a string argument STR, 'UNHEX(STR)' interprets each pair of
     characters in the argument as a hexadecimal number and converts it
     to the byte represented by the number.  The return value is a
     binary string.

          mysql> SELECT UNHEX('4D7953514C');
                  -> 'MySQL'
          mysql> SELECT X'4D7953514C';
                  -> 'MySQL'
          mysql> SELECT UNHEX(HEX('string'));
                  -> 'string'
          mysql> SELECT HEX(UNHEX('1267'));
                  -> '1267'

     The characters in the argument string must be legal hexadecimal
     digits: ''0'' ..  ''9'', ''A'' ..  ''F'', ''a'' ..  ''f''.  If the
     argument contains any nonhexadecimal digits, the result is 'NULL':

          mysql> SELECT UNHEX('GG');
          +-------------+
          | UNHEX('GG') |
          +-------------+
          | NULL        |
          +-------------+

     A 'NULL' result can occur if the argument to 'UNHEX()' is a
     'BINARY' column, because values are padded with
     0x00 bytes when stored but those bytes are not stripped on
     retrieval.  For example, ''41'' is stored into a 'CHAR(3)' column
     as ''41 '' and retrieved as ''41'' (with the trailing pad space
     stripped), so 'UNHEX()' for the column value returns ''A''.  By
     contrast ''41'' is stored into a 'BINARY(3)' column as ''41\0'' and
     retrieved as ''41\0'' (with the trailing pad '0x00' byte not
     stripped).  ''\0'' is not a legal hexadecimal digit, so 'UNHEX()'
     for the column value returns 'NULL'.

     For a numeric argument N, the inverse of 'HEX(N)' is not performed
     by 'UNHEX()'.  Use 'CONV(HEX(N),16,10)' instead.  See the
     description of 'HEX()'.

   *
     'UPPER(STR)'

     Returns the string STR with all characters changed to uppercase
     according to the current character set mapping.  The default is
     'latin1' (cp1252 West European).

          mysql> SELECT UPPER('Hej');
                  -> 'HEJ'

     See the description of 'LOWER()' for information that also applies
     to 'UPPER()'.  This included information about how to perform
     lettercase conversion of binary strings (see 'BINARY',
     see 'VARBINARY',
     'BLOB') for which these functions are ineffective, and
     information about case folding for Unicode character sets.

     This function is multibyte safe.

     In previous versions of MySQL, 'UPPER()' used within a view was
     rewritten as 'UCASE()' when storing the view's definition.  In
     MySQL 5.7, 'UPPER()' is never rewritten in such cases, but
     'UCASE()' used within views is instead rewritten as 'UPPER()'.
     (Bug #12844279)

   *
     'WEIGHT_STRING(STR [AS {CHAR|BINARY}(N)] [LEVEL LEVELS] [FLAGS])'

     'LEVELS: N [ASC|DESC|REVERSE] [, N [ASC|DESC|REVERSE]] ...'

     This function returns the weight string for the input string.  The
     return value is a binary string that represents the comparison and
     sorting value of the string.  It has these properties:

        * If 'WEIGHT_STRING(STR1)' = 'WEIGHT_STRING(STR2)', then 'STR1 =
          STR2' (STR1 and STR2 are considered equal)

        * If 'WEIGHT_STRING(STR1)' < 'WEIGHT_STRING(STR2)', then 'STR1 <
          STR2' (STR1 sorts before STR2)

     'WEIGHT_STRING()' is a debugging function intended for internal
     use.  Its behavior can change without notice between MySQL
     versions.  It can be used for testing and debugging of collations,
     especially if you are adding a new collation.  See
     adding-collation.

     This list briefly summarizes the arguments.  More details are given
     in the discussion following the list.

        * STR: The input string expression.

        * 'AS' clause: Optional; cast the input string to a given type
          and length.

        * 'LEVEL' clause: Optional; specify weight levels for the return
          value.

        * FLAGS: Optional; unused.

     The input string, STR, is a string expression.  If the input is a
     nonbinary (character) string such as a 'CHAR',
     'VARCHAR', or 'TEXT' value, the return value
     contains the collation weights for the string.  If the input is a
     binary (byte) string such as a 'BINARY',
     'VARBINARY', or 'BLOB' value,
     the return value is the same as the input (the weight for each byte
     in a binary string is the byte value).  If the input is 'NULL',
     'WEIGHT_STRING()' returns 'NULL'.

     Examples:

          mysql> SET @s = _latin1 'AB' COLLATE latin1_swedish_ci;
          mysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));
          +------+---------+------------------------+
          | @s   | HEX(@s) | HEX(WEIGHT_STRING(@s)) |
          +------+---------+------------------------+
          | AB   | 4142    | 4142                   |
          +------+---------+------------------------+

          mysql> SET @s = _latin1 'ab' COLLATE latin1_swedish_ci;
          mysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));
          +------+---------+------------------------+
          | @s   | HEX(@s) | HEX(WEIGHT_STRING(@s)) |
          +------+---------+------------------------+
          | ab   | 6162    | 4142                   |
          +------+---------+------------------------+

          mysql> SET @s = CAST('AB' AS BINARY);
          mysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));
          +------+---------+------------------------+
          | @s   | HEX(@s) | HEX(WEIGHT_STRING(@s)) |
          +------+---------+------------------------+
          | AB   | 4142    | 4142                   |
          +------+---------+------------------------+

          mysql> SET @s = CAST('ab' AS BINARY);
          mysql> SELECT @s, HEX(@s), HEX(WEIGHT_STRING(@s));
          +------+---------+------------------------+
          | @s   | HEX(@s) | HEX(WEIGHT_STRING(@s)) |
          +------+---------+------------------------+
          | ab   | 6162    | 6162                   |
          +------+---------+------------------------+

     The preceding examples use 'HEX()' to display the 'WEIGHT_STRING()'
     result.  Because the result is a binary value, 'HEX()' can be
     especially useful when the result contains nonprinting values, to
     display it in printable form:

          mysql> SET @s = CONVERT(X'C39F' USING utf8) COLLATE utf8_czech_ci;
          mysql> SELECT HEX(WEIGHT_STRING(@s));
          +------------------------+
          | HEX(WEIGHT_STRING(@s)) |
          +------------------------+
          | 0FEA0FEA               |
          +------------------------+

     For non-'NULL' return values, the data type of the value is
     'VARBINARY' if its length is within the maximum
     length for 'VARBINARY', otherwise the data
     type is 'BLOB'.

     The 'AS' clause may be given to cast the input string to a
     nonbinary or binary string and to force it to a given length:

        * 'AS CHAR(N)' casts the string to a nonbinary string and pads
          it on the right with spaces to a length of N characters.  N
          must be at least 1.  If N is less than the length of the input
          string, the string is truncated to N characters.  No warning
          occurs for truncation.

        * 'AS BINARY(N)' is similar but casts the string to a binary
          string, N is measured in bytes (not characters), and padding
          uses '0x00' bytes (not spaces).

          mysql> SET NAMES 'latin1';
          mysql> SELECT HEX(WEIGHT_STRING('ab' AS CHAR(4)));
          +-------------------------------------+
          | HEX(WEIGHT_STRING('ab' AS CHAR(4))) |
          +-------------------------------------+
          | 41422020                            |
          +-------------------------------------+
          mysql> SET NAMES 'utf8';
          mysql> SELECT HEX(WEIGHT_STRING('ab' AS CHAR(4)));
          +-------------------------------------+
          | HEX(WEIGHT_STRING('ab' AS CHAR(4))) |
          +-------------------------------------+
          | 0041004200200020                    |
          +-------------------------------------+

          mysql> SELECT HEX(WEIGHT_STRING('ab' AS BINARY(4)));
          +---------------------------------------+
          | HEX(WEIGHT_STRING('ab' AS BINARY(4))) |
          +---------------------------------------+
          | 61620000                              |
          +---------------------------------------+

     The 'LEVEL' clause may be given to specify that the return value
     should contain weights for specific collation levels.

     The LEVELS specifier following the 'LEVEL' keyword may be given
     either as a list of one or more integers separated by commas, or as
     a range of two integers separated by a dash.  Whitespace around the
     punctuation characters does not matter.

     Examples:

          LEVEL 1
          LEVEL 2, 3, 5
          LEVEL 1-3

     Any level less than 1 is treated as 1.  Any level greater than the
     maximum for the input string collation is treated as maximum for
     the collation.  The maximum varies per collation, but is never
     greater than 6.

     In a list of levels, levels must be given in increasing order.  In
     a range of levels, if the second number is less than the first, it
     is treated as the first number (for example, 4-2 is the same as
     4-4).

     If the 'LEVEL' clause is omitted, MySQL assumes 'LEVEL 1 - MAX',
     where MAX is the maximum level for the collation.

     If 'LEVEL' is specified using list syntax (not range syntax), any
     level number can be followed by these modifiers:

        * 'ASC': Return the weights without modification.  This is the
          default.

        * 'DESC': Return bitwise-inverted weights (for example, '0x78f0
          DESC' = '0x870f').

        * 'REVERSE': Return the weights in reverse order (that is,the
          weights for the reversed string, with the first character last
          and the last first).

     Examples:

          mysql> SELECT HEX(WEIGHT_STRING(0x007fff LEVEL 1));
          +--------------------------------------+
          | HEX(WEIGHT_STRING(0x007fff LEVEL 1)) |
          +--------------------------------------+
          | 007FFF                               |
          +--------------------------------------+

          mysql> SELECT HEX(WEIGHT_STRING(0x007fff LEVEL 1 DESC));
          +-------------------------------------------+
          | HEX(WEIGHT_STRING(0x007fff LEVEL 1 DESC)) |
          +-------------------------------------------+
          | FF8000                                    |
          +-------------------------------------------+

          mysql> SELECT HEX(WEIGHT_STRING(0x007fff LEVEL 1 REVERSE));
          +----------------------------------------------+
          | HEX(WEIGHT_STRING(0x007fff LEVEL 1 REVERSE)) |
          +----------------------------------------------+
          | FF7F00                                       |
          +----------------------------------------------+

          mysql> SELECT HEX(WEIGHT_STRING(0x007fff LEVEL 1 DESC REVERSE));
          +---------------------------------------------------+
          | HEX(WEIGHT_STRING(0x007fff LEVEL 1 DESC REVERSE)) |
          +---------------------------------------------------+
          | 0080FF                                            |
          +---------------------------------------------------+

     The FLAGS clause currently is unused.

12.5.1 String Comparison Functions
----------------------------------

*String Comparison Operators*

Name                          Description

'LIKE'                        Simple pattern matching

'NOT LIKE'                    Negation of simple pattern matching

'STRCMP()'                    Compare two strings

If a string function is given a binary string as an argument, the
resulting string is also a binary string.  A number converted to a
string is treated as a binary string.  This affects only comparisons.

Normally, if any expression in a string comparison is case sensitive,
the comparison is performed in case-sensitive fashion.

   *
     'EXPR LIKE PAT [ESCAPE 'ESCAPE_CHAR']'

     Pattern matching using an SQL pattern.  Returns '1' ('TRUE') or '0'
     ('FALSE').  If either EXPR or PAT is 'NULL', the result is 'NULL'.

     The pattern need not be a literal string.  For example, it can be
     specified as a string expression or table column.

     Per the SQL standard, 'LIKE' performs matching on a per-character
     basis, thus it can produce results different from the '='
     comparison operator:

          mysql> SELECT 'a"' LIKE 'ae' COLLATE latin1_german2_ci;
          +-----------------------------------------+
          | 'a"' LIKE 'ae' COLLATE latin1_german2_ci |
          +-----------------------------------------+
          |                                       0 |
          +-----------------------------------------+
          mysql> SELECT 'a"' = 'ae' COLLATE latin1_german2_ci;
          +--------------------------------------+
          | 'a"' = 'ae' COLLATE latin1_german2_ci |
          +--------------------------------------+
          |                                    1 |
          +--------------------------------------+

     In particular, trailing spaces are significant, which is not true
     for 'CHAR' or 'VARCHAR' comparisons
     performed with the '=' operator:

          mysql> SELECT 'a' = 'a ', 'a' LIKE 'a ';
          +------------+---------------+
          | 'a' = 'a ' | 'a' LIKE 'a ' |
          +------------+---------------+
          |          1 |             0 |
          +------------+---------------+
          1 row in set (0.00 sec)

     With 'LIKE' you can use the following two wildcard characters in
     the pattern:

        * '%' matches any number of characters, even zero characters.

        * '_' matches exactly one character.

          mysql> SELECT 'David!' LIKE 'David_';
                  -> 1
          mysql> SELECT 'David!' LIKE '%D%v%';
                  -> 1

     To test for literal instances of a wildcard character, precede it
     by the escape character.  If you do not specify the 'ESCAPE'
     character, '\' is assumed.

        * '\%' matches one '%' character.

        * '\_' matches one '_' character.

          mysql> SELECT 'David!' LIKE 'David\_';
                  -> 0
          mysql> SELECT 'David_' LIKE 'David\_';
                  -> 1

     To specify a different escape character, use the 'ESCAPE' clause:

          mysql> SELECT 'David_' LIKE 'David|_' ESCAPE '|';
                  -> 1

     The escape sequence should be empty or one character long.  The
     expression must evaluate as a constant at execution time.  If the
     'NO_BACKSLASH_ESCAPES' SQL mode is enabled, the sequence cannot be
     empty.

     The following two statements illustrate that string comparisons are
     not case-sensitive unless one of the operands is case-sensitive
     (uses a case-sensitive collation or is a binary string):

          mysql> SELECT 'abc' LIKE 'ABC';
                  -> 1
          mysql> SELECT 'abc' LIKE _latin1 'ABC' COLLATE latin1_general_cs;
                  -> 0
          mysql> SELECT 'abc' LIKE _latin1 'ABC' COLLATE latin1_bin;
                  -> 0
          mysql> SELECT 'abc' LIKE BINARY 'ABC';
                  -> 0

     As an extension to standard SQL, MySQL permits 'LIKE' on numeric
     expressions.

          mysql> SELECT 10 LIKE '1%';
                  -> 1

     *Note*:

     Because MySQL uses C escape syntax in strings (for example, '\n' to
     represent a newline character), you must double any '\' that you
     use in 'LIKE' strings.  For example, to search for '\n', specify it
     as '\\n'.  To search for '\', specify it as '\\\\'; this is because
     the backslashes are stripped once by the parser and again when the
     pattern match is made, leaving a single backslash to be matched
     against.

     Exception: At the end of the pattern string, backslash can be
     specified as '\\'.  At the end of the string, backslash stands for
     itself because there is nothing following to escape.  Suppose that
     a table contains the following values:

          mysql> SELECT filename FROM t1;
          +--------------+
          | filename     |
          +--------------+
          | C:           |
          | C:\          |
          | C:\Programs  |
          | C:\Programs\ |
          +--------------+

     To test for values that end with backslash, you can match the
     values using either of the following patterns:

          mysql> SELECT filename, filename LIKE '%\\' FROM t1;
          +--------------+---------------------+
          | filename     | filename LIKE '%\\' |
          +--------------+---------------------+
          | C:           |                   0 |
          | C:\          |                   1 |
          | C:\Programs  |                   0 |
          | C:\Programs\ |                   1 |
          +--------------+---------------------+

          mysql> SELECT filename, filename LIKE '%\\\\' FROM t1;
          +--------------+-----------------------+
          | filename     | filename LIKE '%\\\\' |
          +--------------+-----------------------+
          | C:           |                     0 |
          | C:\          |                     1 |
          | C:\Programs  |                     0 |
          | C:\Programs\ |                     1 |
          +--------------+-----------------------+

   *
     'EXPR NOT LIKE PAT [ESCAPE 'ESCAPE_CHAR']'

     This is the same as 'NOT (EXPR LIKE PAT [ESCAPE 'ESCAPE_CHAR'])'.

     *Note*:

     Aggregate queries involving 'NOT LIKE' comparisons with columns
     containing 'NULL' may yield unexpected results.  For example,
     consider the following table and data:

          CREATE TABLE foo (bar VARCHAR(10));

          INSERT INTO foo VALUES (NULL), (NULL);

     The query 'SELECT COUNT(*) FROM foo WHERE bar LIKE '%baz%';'
     returns '0'.  You might assume that 'SELECT COUNT(*) FROM foo WHERE
     bar NOT LIKE '%baz%';' would return '2'.  However, this is not the
     case: The second query returns '0'.  This is because 'NULL NOT LIKE
     EXPR' always returns 'NULL', regardless of the value of EXPR.  The
     same is true for aggregate queries involving 'NULL' and comparisons
     using 'NOT RLIKE' or 'NOT REGEXP'.  In such cases, you must test
     explicitly for 'NOT NULL' using 'OR' (and not 'AND'), as shown
     here:

          SELECT COUNT(*) FROM foo WHERE bar NOT LIKE '%baz%' OR bar IS NULL;

   *
     'STRCMP(EXPR1,EXPR2)'

     'STRCMP()' returns '0' if the strings are the same, '-1' if the
     first argument is smaller than the second according to the current
     sort order, and '1' otherwise.

          mysql> SELECT STRCMP('text', 'text2');
                  -> -1
          mysql> SELECT STRCMP('text2', 'text');
                  -> 1
          mysql> SELECT STRCMP('text', 'text');
                  -> 0

     'STRCMP()' performs the comparison using the collation of the
     arguments.

          mysql> SET @s1 = _latin1 'x' COLLATE latin1_general_ci;
          mysql> SET @s2 = _latin1 'X' COLLATE latin1_general_ci;
          mysql> SET @s3 = _latin1 'x' COLLATE latin1_general_cs;
          mysql> SET @s4 = _latin1 'X' COLLATE latin1_general_cs;
          mysql> SELECT STRCMP(@s1, @s2), STRCMP(@s3, @s4);
          +------------------+------------------+
          | STRCMP(@s1, @s2) | STRCMP(@s3, @s4) |
          +------------------+------------------+
          |                0 |                1 |
          +------------------+------------------+

     If the collations are incompatible, one of the arguments must be
     converted to be compatible with the other.  See
     charset-collation-coercibility.

          mysql> SELECT STRCMP(@s1, @s3);
          ERROR 1267 (HY000): Illegal mix of collations (latin1_general_ci,IMPLICIT)
          and (latin1_general_cs,IMPLICIT) for operation 'strcmp'
          mysql> SELECT STRCMP(@s1, @s3 COLLATE latin1_general_ci);
          +--------------------------------------------+
          | STRCMP(@s1, @s3 COLLATE latin1_general_ci) |
          +--------------------------------------------+
          |                                          0 |
          +--------------------------------------------+

12.5.2 Regular Expressions
--------------------------

*Regular Expression Operators*

Name                          Description

'NOT REGEXP'                  Negation of REGEXP

'REGEXP'                      Whether string matches regular expression

'RLIKE'                       Whether string matches regular expression

A regular expression is a powerful way of specifying a pattern for a
complex search.  This section discusses the operators available for
regular expression matching and illustrates, with examples, some of the
special characters and constructs that can be used for regular
expression operations.  See also pattern-matching.

MySQL uses Henry Spencer's implementation of regular expressions, which
is aimed at conformance with POSIX 1003.2.  MySQL uses the extended
version to support regular expression pattern-matching operations in SQL
statements.  This section does not contain all the details that can be
found in Henry Spencer's 'regex(7)' manual page.  That manual page is
included in MySQL source distributions, in the 'regex.7' file under the
'regex' directory.

   * regexp-operators

   * regexp-syntax

*Regular Expression Operators*

   *
     'EXPR NOT REGEXP PAT', 'EXPR NOT RLIKE PAT'

     This is the same as 'NOT (EXPR REGEXP PAT)'.

   *
     'EXPR REGEXP PAT', 'EXPR RLIKE PAT'

     Returns 1 if the string EXPR matches the regular expression
     specified by the pattern PAT, 0 otherwise.  If either EXPR or PAT
     is 'NULL', the return value is 'NULL'.

     'RLIKE' is a synonym for 'REGEXP'.

     The pattern can be an extended regular expression, the syntax for
     which is discussed in regexp-syntax.  The pattern need not
     be a literal string.  For example, it can be specified as a string
     expression or table column.

     *Note*:

     Because MySQL uses the C escape syntax in strings (for example,
     '\n' to represent the newline character), you must double any '\'
     that you use in your 'REGEXP' arguments.

     Regular expression operations use the character set and collation
     of the string expression and pattern arguments when deciding the
     type of a character and performing the comparison.  If the
     arguments have different character sets or collations, coercibility
     rules apply as described in charset-collation-coercibility.
     If either argument is a binary string, the arguments are handled in
     case-sensitive fashion as binary strings.

          mysql> SELECT 'Michael!' REGEXP '.*';
          +------------------------+
          | 'Michael!' REGEXP '.*' |
          +------------------------+
          |                      1 |
          +------------------------+
          mysql> SELECT 'new*\n*line' REGEXP 'new\\*.\\*line';
          +---------------------------------------+
          | 'new*\n*line' REGEXP 'new\\*.\\*line' |
          +---------------------------------------+
          |                                     0 |
          +---------------------------------------+
          mysql> SELECT 'a' REGEXP '^[a-d]';
          +---------------------+
          | 'a' REGEXP '^[a-d]' |
          +---------------------+
          |                   1 |
          +---------------------+
          mysql> SELECT 'a' REGEXP 'A', 'a' REGEXP BINARY 'A';
          +----------------+-----------------------+
          | 'a' REGEXP 'A' | 'a' REGEXP BINARY 'A' |
          +----------------+-----------------------+
          |              1 |                     0 |
          +----------------+-----------------------+

     *Warning*:

     The 'REGEXP' and 'RLIKE' operators work in byte-wise fashion, so
     they are not multibyte safe and may produce unexpected results with
     multibyte character sets.  In addition, these operators compare
     characters by their byte values and accented characters may not
     compare as equal even if a given collation treats them as equal.

*Regular Expression Syntax*

A regular expression describes a set of strings.  The simplest regular
expression is one that has no special characters in it.  For example,
the regular expression 'hello' matches 'hello' and nothing else.

Nontrivial regular expressions use certain special constructs so that
they can match more than one string.  For example, the regular
expression 'hello|world' contains the '|' alternation operator and
matches either the 'hello' or 'world'.

As a more complex example, the regular expression 'B[an]*s' matches any
of the strings 'Bananas', 'Baaaaas', 'Bs', and any other string starting
with a 'B', ending with an 's', and containing any number of 'a' or 'n'
characters in between.

A regular expression for the 'REGEXP' operator may use any of the
following special characters and constructs:

   * '^'

     Match the beginning of a string.

          mysql> SELECT 'fo\nfo' REGEXP '^fo$';                   -> 0
          mysql> SELECT 'fofo' REGEXP '^fo';                      -> 1

   * '$'

     Match the end of a string.

          mysql> SELECT 'fo\no' REGEXP '^fo\no$';                 -> 1
          mysql> SELECT 'fo\no' REGEXP '^fo$';                    -> 0

   * '.'

     Match any character (including carriage return and newline).

          mysql> SELECT 'fofo' REGEXP '^f.*$';                    -> 1
          mysql> SELECT 'fo\r\nfo' REGEXP '^f.*$';                -> 1

   * 'a*'

     Match any sequence of zero or more 'a' characters.

          mysql> SELECT 'Ban' REGEXP '^Ba*n';                     -> 1
          mysql> SELECT 'Baaan' REGEXP '^Ba*n';                   -> 1
          mysql> SELECT 'Bn' REGEXP '^Ba*n';                      -> 1

   * 'a+'

     Match any sequence of one or more 'a' characters.

          mysql> SELECT 'Ban' REGEXP '^Ba+n';                     -> 1
          mysql> SELECT 'Bn' REGEXP '^Ba+n';                      -> 0

   * 'a?'

     Match either zero or one 'a' character.

          mysql> SELECT 'Bn' REGEXP '^Ba?n';                      -> 1
          mysql> SELECT 'Ban' REGEXP '^Ba?n';                     -> 1
          mysql> SELECT 'Baan' REGEXP '^Ba?n';                    -> 0

   * 'de|abc'

     Alternation; match either of the sequences 'de' or 'abc'.

          mysql> SELECT 'pi' REGEXP 'pi|apa';                     -> 1
          mysql> SELECT 'axe' REGEXP 'pi|apa';                    -> 0
          mysql> SELECT 'apa' REGEXP 'pi|apa';                    -> 1
          mysql> SELECT 'apa' REGEXP '^(pi|apa)$';                -> 1
          mysql> SELECT 'pi' REGEXP '^(pi|apa)$';                 -> 1
          mysql> SELECT 'pix' REGEXP '^(pi|apa)$';                -> 0

   * '(abc)*'

     Match zero or more instances of the sequence 'abc'.

          mysql> SELECT 'pi' REGEXP '^(pi)*$';                    -> 1
          mysql> SELECT 'pip' REGEXP '^(pi)*$';                   -> 0
          mysql> SELECT 'pipi' REGEXP '^(pi)*$';                  -> 1

   * '{1}', '{2,3}'

     Repetition; '{N}' and '{M,N}' notation provide a more general way
     of writing regular expressions that match many occurrences of the
     previous atom (or 'piece') of the pattern.  M and N are integers.

        * 'a*'

          Can be written as 'a{0,}'.

        * 'a+'

          Can be written as 'a{1,}'.

        * 'a?'

          Can be written as 'a{0,1}'.

     To be more precise, 'a{N}' matches exactly N instances of 'a'.
     'a{N,}' matches N or more instances of 'a'.  'a{M,N}' matches M
     through N instances of 'a', inclusive.  If both M and N are given,
     M must be less than or equal to N.

     M and N must be in the range from '0' to 'RE_DUP_MAX' (default
     255), inclusive.

          mysql> SELECT 'abcde' REGEXP 'a[bcd]{2}e';              -> 0
          mysql> SELECT 'abcde' REGEXP 'a[bcd]{3}e';              -> 1
          mysql> SELECT 'abcde' REGEXP 'a[bcd]{1,10}e';           -> 1

   * '[a-dX]', '[^a-dX]'

     Matches any character that is (or is not, if '^' is used) either
     'a', 'b', 'c', 'd' or 'X'.  A '-' character between two other
     characters forms a range that matches all characters from the first
     character to the second.  For example, '[0-9]' matches any decimal
     digit.  To include a literal ']' character, it must immediately
     follow the opening bracket '['.  To include a literal '-'
     character, it must be written first or last.  Any character that
     does not have a defined special meaning inside a '[]' pair matches
     only itself.

          mysql> SELECT 'aXbc' REGEXP '[a-dXYZ]';                 -> 1
          mysql> SELECT 'aXbc' REGEXP '^[a-dXYZ]$';               -> 0
          mysql> SELECT 'aXbc' REGEXP '^[a-dXYZ]+$';              -> 1
          mysql> SELECT 'aXbc' REGEXP '^[^a-dXYZ]+$';             -> 0
          mysql> SELECT 'gheis' REGEXP '^[^a-dXYZ]+$';            -> 1
          mysql> SELECT 'gheisa' REGEXP '^[^a-dXYZ]+$';           -> 0

   * '[.characters.]'

     Within a bracket expression (written using '[' and ']'), matches
     the sequence of characters of that collating element.  'characters'
     is either a single character or a character name like 'newline'.
     The following table lists the permissible character names.

     The following table shows the permissible character names and the
     characters that they match.  For characters given as numeric
     values, the values are represented in octal.

     Name               Character          Name               Character

     'NUL'              '0'                'SOH'              '001'

     'STX'              '002'              'ETX'              '003'

     'EOT'              '004'              'ENQ'              '005'

     'ACK'              '006'              'BEL'              '007'

     'alert'            '007'              'BS'               '010'

     'backspace'        ''\b''             'HT'               '011'

     'tab'              ''\t''             'LF'               '012'

     'newline'          ''\n''             'VT'               '013'

     'vertical-tab'     ''\v''             'FF'               '014'

     'form-feed'        ''\f''             'CR'               '015'

     'carriage-return'  ''\r''             'SO'               '016'

     'SI'               '017'              'DLE'              '020'

     'DC1'              '021'              'DC2'              '022'

     'DC3'              '023'              'DC4'              '024'

     'NAK'              '025'              'SYN'              '026'

     'ETB'              '027'              'CAN'              '030'

     'EM'               '031'              'SUB'              '032'

     'ESC'              '033'              'IS4'              '034'

     'FS'               '034'              'IS3'              '035'

     'GS'               '035'              'IS2'              '036'

     'RS'               '036'              'IS1'              '037'

     'US'               '037'              'space'            '' ''

     'exclamation-mark' ''!''              'quotation-mark'   ''"''

     'number-sign'      ''#''              'dollar-sign'      ''$''

     'percent-sign'     ''%''              'ampersand'        ''&''

     'apostrophe'       ''\'''             'left-parenthesis' ''(''

     'right-parenthesis''')''              'asterisk'         ''*''

     'plus-sign'        ''+''              'comma'            '',''

     'hyphen'           ''-''              'hyphen-minus'     ''-''

     'period'           ''.''              'full-stop'        ''.''

     'slash'            ''/''              'solidus'          ''/''

     'zero'             ''0''              'one'              ''1''

     'two'              ''2''              'three'            ''3''

     'four'             ''4''              'five'             ''5''

     'six'              ''6''              'seven'            ''7''

     'eight'            ''8''              'nine'             ''9''

     'colon'            '':''              'semicolon'        '';''

     'less-than-sign'   ''<''              'equals-sign'      ''=''

     'greater-than-sign'''>''              'question-mark'    ''?''

     'commercial-at'    ''@''              'left-square-bracket'''[''

     'backslash'        ''\\''             'reverse-solidus'  ''\\''

     'right-square-bracket''']''           'circumflex'       ''^''

     'circumflex-accent'''^''              'underscore'       ''_''

     'low-line'         ''_''              'grave-accent'     ''`''

     'left-brace'       ''{''              'left-curly-bracket'''{''

     'vertical-line'    ''|''              'right-brace'      ''}''

     'right-curly-bracket'''}''            'tilde'            ''~''

     'DEL'              '177'

          mysql> SELECT '~' REGEXP '[[.~.]]';                     -> 1
          mysql> SELECT '~' REGEXP '[[.tilde.]]';                 -> 1

   * '[=character_class=]'

     Within a bracket expression (written using '[' and ']'),
     '[=character_class=]' represents an equivalence class.  It matches
     all characters with the same collation value, including itself.
     For example, if 'o' and '(+)' are the members of an equivalence
     class, '[[=o=]]', '[[=(+)=]]', and '[o(+)]' are all synonymous.  An
     equivalence class may not be used as an endpoint of a range.

   * '[:character_class:]'

     Within a bracket expression (written using '[' and ']'),
     '[:character_class:]' represents a character class that matches all
     characters belonging to that class.  The following table lists the
     standard class names.  These names stand for the character classes
     defined in the 'ctype(3)' manual page.  A particular locale may
     provide other class names.  A character class may not be used as an
     endpoint of a range.

     Character      Meaning
     Class Name

     'alnum'        Alphanumeric characters

     'alpha'        Alphabetic characters

     'blank'        Whitespace characters

     'cntrl'        Control characters

     'digit'        Digit characters

     'graph'        Graphic characters

     'lower'        Lowercase alphabetic characters

     'print'        Graphic or space characters

     'punct'        Punctuation characters

     'space'        Space, tab, newline, and carriage return

     'upper'        Uppercase alphabetic characters

     'xdigit'       Hexadecimal digit characters

          mysql> SELECT 'justalnums' REGEXP '[[:alnum:]]+';       -> 1
          mysql> SELECT '!!' REGEXP '[[:alnum:]]+';               -> 0

   * '[[:<:]]', '[[:>:]]'

     These markers stand for word boundaries.  They match the beginning
     and end of words, respectively.  A word is a sequence of word
     characters that is not preceded by or followed by word characters.
     A word character is an alphanumeric character in the 'alnum' class
     or an underscore ('_').

          mysql> SELECT 'a word a' REGEXP '[[:<:]]word[[:>:]]';   -> 1
          mysql> SELECT 'a xword a' REGEXP '[[:<:]]word[[:>:]]';  -> 0

To use a literal instance of a special character in a regular
expression, precede it by two backslash (\) characters.  The MySQL
parser interprets one of the backslashes, and the regular expression
library interprets the other.  For example, to match the string '1+2'
that contains the special '+' character, only the last of the following
regular expressions is the correct one:

     mysql> SELECT '1+2' REGEXP '1+2';                       -> 0
     mysql> SELECT '1+2' REGEXP '1\+2';                      -> 0
     mysql> SELECT '1+2' REGEXP '1\\+2';                     -> 1

12.5.3 Character Set and Collation of Function Results
------------------------------------------------------

MySQL has many operators and functions that return a string.  This
section answers the question: What is the character set and collation of
such a string?

For simple functions that take string input and return a string result
as output, the output's character set and collation are the same as
those of the principal input value.  For example, 'UPPER(X)' returns a
string with the same character string and collation as X.  The same
applies for 'INSTR()', 'LCASE()', 'LOWER()', 'LTRIM()', 'MID()',
'REPEAT()', 'REPLACE()', 'REVERSE()', 'RIGHT()', 'RPAD()', 'RTRIM()',
'SOUNDEX()', 'SUBSTRING()', 'TRIM()', 'UCASE()', and 'UPPER()'.

*Note*:

The 'REPLACE()' function, unlike all other functions, always ignores the
collation of the string input and performs a case-sensitive comparison.

If a string input or function result is a binary string, the string has
the 'binary' character set and collation.  This can be checked by using
the 'CHARSET()' and 'COLLATION()' functions, both of which return
'binary' for a binary string argument:

     mysql> SELECT CHARSET(BINARY 'a'), COLLATION(BINARY 'a');
     +---------------------+-----------------------+
     | CHARSET(BINARY 'a') | COLLATION(BINARY 'a') |
     +---------------------+-----------------------+
     | binary              | binary                |
     +---------------------+-----------------------+

For operations that combine multiple string inputs and return a single
string output, the 'aggregation rules' of standard SQL apply for
determining the collation of the result:

   * If an explicit 'COLLATE Y' occurs, use Y.

   * If explicit 'COLLATE Y' and 'COLLATE Z' occur, raise an error.

   * Otherwise, if all collations are Y, use Y.

   * Otherwise, the result has no collation.

For example, with 'CASE ... WHEN a THEN b WHEN b THEN c COLLATE X END',
the resulting collation is X.  The same applies for 'UNION',
'||', 'CONCAT()', 'ELT()', 'GREATEST()', 'IF()', and 'LEAST()'.

For operations that convert to character data, the character set and
collation of the strings that result from the operations are defined by
the 'character_set_connection' and 'collation_connection' system
variables that determine the default connection character set and
collation (see charset-connection).  This applies only to
'CAST()', 'CONV()', 'FORMAT()', 'HEX()', and 'SPACE()'.

As of MySQL 5.7.19, an exception to the preceding priniciple occurs for
expressions for virtual generated columns.  In such expressions, the
table character set is used for 'CONV()' or 'HEX()' results, regardless
of connection character set.

If there is any question about the character set or collation of the
result returned by a string function, use the 'CHARSET()' or
'COLLATION()' function to find out:

     mysql> SELECT USER(), CHARSET(USER()), COLLATION(USER());
     +----------------+-----------------+-------------------+
     | USER()         | CHARSET(USER()) | COLLATION(USER()) |
     +----------------+-----------------+-------------------+
     | test@localhost | utf8            | utf8_general_ci   |
     +----------------+-----------------+-------------------+
     mysql> SELECT CHARSET(COMPRESS('abc')), COLLATION(COMPRESS('abc'));
     +--------------------------+----------------------------+
     | CHARSET(COMPRESS('abc')) | COLLATION(COMPRESS('abc')) |
     +--------------------------+----------------------------+
     | binary                   | binary                     |
     +--------------------------+----------------------------+

12.6 Numeric Functions and Operators
====================================

*Numeric Functions and Operators*

Name                          Description

'ABS()'                       Return the absolute value

'ACOS()'                      Return the arc cosine

'ASIN()'                      Return the arc sine

'ATAN()'                      Return the arc tangent

'ATAN2()', 'ATAN()'           Return the arc tangent of the two
                              arguments

'CEIL()'                      Return the smallest integer value not
                              less than the argument

'CEILING()'                   Return the smallest integer value not
                              less than the argument

'CONV()'                      Convert numbers between different number
                              bases

'COS()'                       Return the cosine

'COT()'                       Return the cotangent

'CRC32()'                     Compute a cyclic redundancy check value

'DEGREES()'                   Convert radians to degrees

'DIV'                         Integer division

'/'                           Division operator

'EXP()'                       Raise to the power of

'FLOOR()'                     Return the largest integer value not
                              greater than the argument

'LN()'                        Return the natural logarithm of the
                              argument

'LOG()'                       Return the natural logarithm of the first
                              argument

'LOG10()'                     Return the base-10 logarithm of the
                              argument

'LOG2()'                      Return the base-2 logarithm of the
                              argument

'-'                           Minus operator

'MOD()'                       Return the remainder

'%', 'MOD'                    Modulo operator

'PI()'                        Return the value of pi

'+'                           Addition operator

'POW()'                       Return the argument raised to the
                              specified power

'POWER()'                     Return the argument raised to the
                              specified power

'RADIANS()'                   Return argument converted to radians

'RAND()'                      Return a random floating-point value

'ROUND()'                     Round the argument

'SIGN()'                      Return the sign of the argument

'SIN()'                       Return the sine of the argument

'SQRT()'                      Return the square root of the argument

'TAN()'                       Return the tangent of the argument

'*'                           Multiplication operator

'TRUNCATE()'                  Truncate to specified number of decimal
                              places

'-'                           Change the sign of the argument

12.6.1 Arithmetic Operators
---------------------------

*Arithmetic Operators*

Name                          Description

'DIV'                         Integer division

'/'                           Division operator

'-'                           Minus operator

'%', 'MOD'                    Modulo operator

'+'                           Addition operator

'*'                           Multiplication operator

'-'                           Change the sign of the argument

The usual arithmetic operators are available.  The result is determined
according to the following rules:

   * In the case of '-', '+', and '*', the result is calculated with
     'BIGINT'. (64-bit) precision if both operands
     are integers.

   * If both operands are integers and any of them are unsigned, the
     result is an unsigned integer.  For subtraction, if the
     'NO_UNSIGNED_SUBTRACTION' SQL mode is enabled, the result is signed
     even if any operand is unsigned.

   * If any of the operands of a '+', '-', '/', '*', '%' is a real or
     string value, the precision of the result is the precision of the
     operand with the maximum precision.

   * In division performed with '/', the scale of the result when using
     two exact-value operands is the scale of the first operand plus the
     value of the 'div_precision_increment' system variable (which is 4
     by default).  For example, the result of the expression '5.05 /
     0.014' has a scale of six decimal places ('360.714286').

These rules are applied for each operation, such that nested
calculations imply the precision of each component.  Hence, '(14620 /
9432456) / (24250 / 9432456)', resolves first to '(0.0014) / (0.0026)',
with the final result having 8 decimal places ('0.60288653').

Because of these rules and the way they are applied, care should be
taken to ensure that components and subcomponents of a calculation use
the appropriate level of precision.  See cast-functions.

For information about handling of overflow in numeric expression
evaluation, see out-of-range-and-overflow.

Arithmetic operators apply to numbers.  For other types of values,
alternative operations may be available.  For example, to add date
values, use 'DATE_ADD()'; see date-and-time-functions.

   *
     '+'

     Addition:

          mysql> SELECT 3+5;
                  -> 8

   *
     '-'

     Subtraction:

          mysql> SELECT 3-5;
                  -> -2

   *
     '-'

     Unary minus.  This operator changes the sign of the operand.

          mysql> SELECT - 2;
                  -> -2

     *Note*:

     If this operator is used with a 'BIGINT', the
     return value is also a 'BIGINT'.  This means
     that you should avoid using '-' on integers that may have the value
     of −2^63.

   *
     '*'

     Multiplication:

          mysql> SELECT 3*5;
                  -> 15
          mysql> SELECT 18014398509481984*18014398509481984.0;
                  -> 324518553658426726783156020576256.0
          mysql> SELECT 18014398509481984*18014398509481984;
                  -> out-of-range error

     The last expression produces an error because the result of the
     integer multiplication exceeds the 64-bit range of 'BIGINT'
     calculations.  (See numeric-types.)

   *
     '/'

     Division:

          mysql> SELECT 3/5;
                  -> 0.60

     Division by zero produces a 'NULL' result:

          mysql> SELECT 102/(1-1);
                  -> NULL

     A division is calculated with 'BIGINT'.
     arithmetic only if performed in a context where its result is
     converted to an integer.

   *
     'DIV'

     Integer division.  Discards from the division result any fractional
     part to the right of the decimal point.

     If either operand has a noninteger type, the operands are converted
     to 'DECIMAL' and divided using
     'DECIMAL' arithmetic before converting the
     result to 'BIGINT'.  If the result exceeds
     'BIGINT' range, an error occurs.

          mysql> SELECT 5 DIV 2, -5 DIV 2, 5 DIV -2, -5 DIV -2;
                  -> 2, -2, -2, 2

   *
     'N % M', 'N MOD M'

     Modulo operation.  Returns the remainder of N divided by M.  For
     more information, see the description for the 'MOD()' function in
     mathematical-functions.

12.6.2 Mathematical Functions
-----------------------------

*Mathematical Functions*

Name                          Description

'ABS()'                       Return the absolute value

'ACOS()'                      Return the arc cosine

'ASIN()'                      Return the arc sine

'ATAN()'                      Return the arc tangent

'ATAN2()', 'ATAN()'           Return the arc tangent of the two
                              arguments

'CEIL()'                      Return the smallest integer value not
                              less than the argument

'CEILING()'                   Return the smallest integer value not
                              less than the argument

'CONV()'                      Convert numbers between different number
                              bases

'COS()'                       Return the cosine

'COT()'                       Return the cotangent

'CRC32()'                     Compute a cyclic redundancy check value

'DEGREES()'                   Convert radians to degrees

'EXP()'                       Raise to the power of

'FLOOR()'                     Return the largest integer value not
                              greater than the argument

'LN()'                        Return the natural logarithm of the
                              argument

'LOG()'                       Return the natural logarithm of the first
                              argument

'LOG10()'                     Return the base-10 logarithm of the
                              argument

'LOG2()'                      Return the base-2 logarithm of the
                              argument

'MOD()'                       Return the remainder

'PI()'                        Return the value of pi

'POW()'                       Return the argument raised to the
                              specified power

'POWER()'                     Return the argument raised to the
                              specified power

'RADIANS()'                   Return argument converted to radians

'RAND()'                      Return a random floating-point value

'ROUND()'                     Round the argument

'SIGN()'                      Return the sign of the argument

'SIN()'                       Return the sine of the argument

'SQRT()'                      Return the square root of the argument

'TAN()'                       Return the tangent of the argument

'TRUNCATE()'                  Truncate to specified number of decimal
                              places

All mathematical functions return 'NULL' in the event of an error.

   *
     'ABS(X)'

     Returns the absolute value of X.

          mysql> SELECT ABS(2);
                  -> 2
          mysql> SELECT ABS(-32);
                  -> 32

     This function is safe to use with 'BIGINT'.
     values.

   *
     'ACOS(X)'

     Returns the arc cosine of X, that is, the value whose cosine is X.
     Returns 'NULL' if X is not in the range '-1' to '1'.

          mysql> SELECT ACOS(1);
                  -> 0
          mysql> SELECT ACOS(1.0001);
                  -> NULL
          mysql> SELECT ACOS(0);
                  -> 1.5707963267949

   *
     'ASIN(X)'

     Returns the arc sine of X, that is, the value whose sine is X.
     Returns 'NULL' if X is not in the range '-1' to '1'.

          mysql> SELECT ASIN(0.2);
                  -> 0.20135792079033
          mysql> SELECT ASIN('foo');

          +-------------+
          | ASIN('foo') |
          +-------------+
          |           0 |
          +-------------+
          1 row in set, 1 warning (0.00 sec)

          mysql> SHOW WARNINGS;
          +---------+------+-----------------------------------------+
          | Level   | Code | Message                                 |
          +---------+------+-----------------------------------------+
          | Warning | 1292 | Truncated incorrect DOUBLE value: 'foo' |
          +---------+------+-----------------------------------------+

   *
     'ATAN(X)'

     Returns the arc tangent of X, that is, the value whose tangent is
     X.

          mysql> SELECT ATAN(2);
                  -> 1.1071487177941
          mysql> SELECT ATAN(-2);
                  -> -1.1071487177941

   *
     'ATAN(Y,X)', 'ATAN2(Y,X)'

     Returns the arc tangent of the two variables X and Y.  It is
     similar to calculating the arc tangent of 'Y / X', except that the
     signs of both arguments are used to determine the quadrant of the
     result.

          mysql> SELECT ATAN(-2,2);
                  -> -0.78539816339745
          mysql> SELECT ATAN2(PI(),0);
                  -> 1.5707963267949

   *
     'CEIL(X)'

     'CEIL()' is a synonym for 'CEILING()'.

   *
     'CEILING(X)'

     Returns the smallest integer value not less than X.

          mysql> SELECT CEILING(1.23);
                  -> 2
          mysql> SELECT CEILING(-1.23);
                  -> -1

     For exact-value numeric arguments, the return value has an
     exact-value numeric type.  For string or floating-point arguments,
     the return value has a floating-point type.

   *
     'CONV(N,FROM_BASE,TO_BASE)'

     Converts numbers between different number bases.  Returns a string
     representation of the number N, converted from base FROM_BASE to
     base TO_BASE.  Returns 'NULL' if any argument is 'NULL'.  The
     argument N is interpreted as an integer, but may be specified as an
     integer or a string.  The minimum base is '2' and the maximum base
     is '36'.  If FROM_BASE is a negative number, N is regarded as a
     signed number.  Otherwise, N is treated as unsigned.  'CONV()'
     works with 64-bit precision.

          mysql> SELECT CONV('a',16,2);
                  -> '1010'
          mysql> SELECT CONV('6E',18,8);
                  -> '172'
          mysql> SELECT CONV(-17,10,-18);
                  -> '-H'
          mysql> SELECT CONV(10+'10'+'10'+X'0a',10,10);
                  -> '40'

   *
     'COS(X)'

     Returns the cosine of X, where X is given in radians.

          mysql> SELECT COS(PI());
                  -> -1

   *
     'COT(X)'

     Returns the cotangent of X.

          mysql> SELECT COT(12);
                  -> -1.5726734063977
          mysql> SELECT COT(0);
                  -> out-of-range error

   *
     'CRC32(EXPR)'

     Computes a cyclic redundancy check value and returns a 32-bit
     unsigned value.  The result is 'NULL' if the argument is 'NULL'.
     The argument is expected to be a string and (if possible) is
     treated as one if it is not.

          mysql> SELECT CRC32('MySQL');
                  -> 3259397556
          mysql> SELECT CRC32('mysql');
                  -> 2501908538

   *
     'DEGREES(X)'

     Returns the argument X, converted from radians to degrees.

          mysql> SELECT DEGREES(PI());
                  -> 180
          mysql> SELECT DEGREES(PI() / 2);
                  -> 90

   *
     'EXP(X)'

     Returns the value of _e_ (the base of natural logarithms) raised to
     the power of X.  The inverse of this function is 'LOG()' (using a
     single argument only) or 'LN()'.

          mysql> SELECT EXP(2);
                  -> 7.3890560989307
          mysql> SELECT EXP(-2);
                  -> 0.13533528323661
          mysql> SELECT EXP(0);
                  -> 1

   *
     'FLOOR(X)'

     Returns the largest integer value not greater than X.

          mysql> SELECT FLOOR(1.23), FLOOR(-1.23);
                  -> 1, -2

     For exact-value numeric arguments, the return value has an
     exact-value numeric type.  For string or floating-point arguments,
     the return value has a floating-point type.

   * 'FORMAT(X,D)'

     Formats the number X to a format like ''#,###,###.##'', rounded to
     D decimal places, and returns the result as a string.  For details,
     see string-functions.

   *
     'HEX(N_or_S)'

     This function can be used to obtain a hexadecimal representation of
     a decimal number or a string; the manner in which it does so varies
     according to the argument's type.  See this function's description
     in string-functions, for details.

   *
     'LN(X)'

     Returns the natural logarithm of X; that is, the base-_e_ logarithm
     of X.  If X is less than or equal to 0.0E0, the function returns
     'NULL' and (as of MySQL 5.7.4) a warning 'Invalid argument for
     logarithm' is reported.

          mysql> SELECT LN(2);
                  -> 0.69314718055995
          mysql> SELECT LN(-2);
                  -> NULL

     This function is synonymous with 'LOG(X)'.  The inverse of this
     function is the 'EXP()' function.

   *
     'LOG(X)', 'LOG(B,X)'

     If called with one parameter, this function returns the natural
     logarithm of X.  If X is less than or equal to 0.0E0, the function
     returns 'NULL' and (as of MySQL 5.7.4) a warning 'Invalid argument
     for logarithm' is reported.

     The inverse of this function (when called with a single argument)
     is the 'EXP()' function.

          mysql> SELECT LOG(2);
                  -> 0.69314718055995
          mysql> SELECT LOG(-2);
                  -> NULL

     If called with two parameters, this function returns the logarithm
     of X to the base B.  If X is less than or equal to 0, or if B is
     less than or equal to 1, then 'NULL' is returned.

          mysql> SELECT LOG(2,65536);
                  -> 16
          mysql> SELECT LOG(10,100);
                  -> 2
          mysql> SELECT LOG(1,100);
                  -> NULL

     'LOG(B,X)' is equivalent to 'LOG(X) / LOG(B)'.

   *
     'LOG2(X)'

     Returns the base-2 logarithm of 'X'.  If X is less than or equal to
     0.0E0, the function returns 'NULL' and (as of MySQL 5.7.4) a
     warning 'Invalid argument for logarithm' is reported.

          mysql> SELECT LOG2(65536);
                  -> 16
          mysql> SELECT LOG2(-100);
                  -> NULL

     'LOG2()' is useful for finding out how many bits a number requires
     for storage.  This function is equivalent to the expression 'LOG(X)
     / LOG(2)'.

   *
     'LOG10(X)'

     Returns the base-10 logarithm of X.  If X is less than or equal to
     0.0E0, the function returns 'NULL' and (as of MySQL 5.7.4) a
     warning 'Invalid argument for logarithm' is reported.

          mysql> SELECT LOG10(2);
                  -> 0.30102999566398
          mysql> SELECT LOG10(100);
                  -> 2
          mysql> SELECT LOG10(-100);
                  -> NULL

     'LOG10(X)' is equivalent to 'LOG(10,X)'.

   *
     'MOD(N,M)', 'N % M', 'N MOD M'

     Modulo operation.  Returns the remainder of N divided by M.

          mysql> SELECT MOD(234, 10);
                  -> 4
          mysql> SELECT 253 % 7;
                  -> 1
          mysql> SELECT MOD(29,9);
                  -> 2
          mysql> SELECT 29 MOD 9;
                  -> 2

     This function is safe to use with 'BIGINT'.
     values.

     'MOD()' also works on values that have a fractional part and
     returns the exact remainder after division:

          mysql> SELECT MOD(34.5,3);
                  -> 1.5

     'MOD(N,0)' returns 'NULL'.

   *
     'PI()'

     Returns the value of π (pi).  The default number of decimal places
     displayed is seven, but MySQL uses the full double-precision value
     internally.

          mysql> SELECT PI();
                  -> 3.141593
          mysql> SELECT PI()+0.000000000000000000;
                  -> 3.141592653589793116

   *
     'POW(X,Y)'

     Returns the value of X raised to the power of Y.

          mysql> SELECT POW(2,2);
                  -> 4
          mysql> SELECT POW(2,-2);
                  -> 0.25

   *
     'POWER(X,Y)'

     This is a synonym for 'POW()'.

   *
     'RADIANS(X)'

     Returns the argument X, converted from degrees to radians.  (Note
     that π radians equals 180 degrees.)

          mysql> SELECT RADIANS(90);
                  -> 1.5707963267949

   *
     'RAND([N])'

     Returns a random floating-point value V in the range '0' <= V <
     '1.0'.  To obtain a random integer R in the range I <= R < J, use
     the expression 'FLOOR(I + RAND() * (J' − 'I))'.  For example, to
     obtain a random integer in the range the range '7' <= R < '12', use
     the following statement:

          SELECT FLOOR(7 + (RAND() * 5));

     If an integer argument N is specified, it is used as the seed
     value:

        * With a constant initializer argument, the seed is initialized
          once when the statement is prepared, prior to execution.

        * With a nonconstant initializer argument (such as a column
          name), the seed is initialized with the value for each
          invocation of 'RAND()'.

     One implication of this behavior is that for equal argument values,
     'RAND(N)' returns the same value each time, and thus produces a
     repeatable sequence of column values.  In the following example,
     the sequence of values produced by 'RAND(3)' is the same both
     places it occurs.

          mysql> CREATE TABLE t (i INT);
          Query OK, 0 rows affected (0.42 sec)

          mysql> INSERT INTO t VALUES(1),(2),(3);
          Query OK, 3 rows affected (0.00 sec)
          Records: 3  Duplicates: 0  Warnings: 0

          mysql> SELECT i, RAND() FROM t;
          +------+------------------+
          | i    | RAND()           |
          +------+------------------+
          |    1 | 0.61914388706828 |
          |    2 | 0.93845168309142 |
          |    3 | 0.83482678498591 |
          +------+------------------+
          3 rows in set (0.00 sec)

          mysql> SELECT i, RAND(3) FROM t;
          +------+------------------+
          | i    | RAND(3)          |
          +------+------------------+
          |    1 | 0.90576975597606 |
          |    2 | 0.37307905813035 |
          |    3 | 0.14808605345719 |
          +------+------------------+
          3 rows in set (0.00 sec)

          mysql> SELECT i, RAND() FROM t;
          +------+------------------+
          | i    | RAND()           |
          +------+------------------+
          |    1 | 0.35877890638893 |
          |    2 | 0.28941420772058 |
          |    3 | 0.37073435016976 |
          +------+------------------+
          3 rows in set (0.00 sec)

          mysql> SELECT i, RAND(3) FROM t;
          +------+------------------+
          | i    | RAND(3)          |
          +------+------------------+
          |    1 | 0.90576975597606 |
          |    2 | 0.37307905813035 |
          |    3 | 0.14808605345719 |
          +------+------------------+
          3 rows in set (0.01 sec)

     'RAND()' in a 'WHERE' clause is evaluated for every row (when
     selecting from one table) or combination of rows (when selecting
     from a multiple-table join).  Thus, for optimizer purposes,
     'RAND()' is not a constant value and cannot be used for index
     optimizations.  For more information, see
     function-optimization.

     Use of a column with 'RAND()' values in an 'ORDER BY' or 'GROUP BY'
     clause may yield unexpected results because for either clause a
     'RAND()' expression can be evaluated multiple times for the same
     row, each time returning a different result.  If the goal is to
     retrieve rows in random order, you can use a statement like this:

          SELECT * FROM TBL_NAME ORDER BY RAND();

     To select a random sample from a set of rows, combine 'ORDER BY
     RAND()' with 'LIMIT':

          SELECT * FROM table1, table2 WHERE a=b AND c<d ORDER BY RAND() LIMIT 1000;

     'RAND()' is not meant to be a perfect random generator.  It is a
     fast way to generate random numbers on demand that is portable
     between platforms for the same MySQL version.

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.  (Bug #49222)

   *
     'ROUND(X)', 'ROUND(X,D)'

     Rounds the argument X to D decimal places.  The rounding algorithm
     depends on the data type of X.  D defaults to 0 if not specified.
     D can be negative to cause D digits left of the decimal point of
     the value X to become zero.

          mysql> SELECT ROUND(-1.23);
                  -> -1
          mysql> SELECT ROUND(-1.58);
                  -> -2
          mysql> SELECT ROUND(1.58);
                  -> 2
          mysql> SELECT ROUND(1.298, 1);
                  -> 1.3
          mysql> SELECT ROUND(1.298, 0);
                  -> 1
          mysql> SELECT ROUND(23.298, -1);
                  -> 20

     The return value has the same type as the first argument (assuming
     that it is integer, double, or decimal).  This means that for an
     integer argument, the result is an integer (no decimal places):

          mysql> SELECT ROUND(150.000,2), ROUND(150,2);
          +------------------+--------------+
          | ROUND(150.000,2) | ROUND(150,2) |
          +------------------+--------------+
          |           150.00 |          150 |
          +------------------+--------------+

     'ROUND()' uses the following rules depending on the type of the
     first argument:

        * For exact-value numbers, 'ROUND()' uses the 'round half away
          from zero' or 'round toward nearest' rule: A value with a
          fractional part of .5 or greater is rounded up to the next
          integer if positive or down to the next integer if negative.
          (In other words, it is rounded away from zero.)  A value with
          a fractional part less than .5 is rounded down to the next
          integer if positive or up to the next integer if negative.

        * For approximate-value numbers, the result depends on the C
          library.  On many systems, this means that 'ROUND()' uses the
          "round to nearest even" rule: A value with any fractional part
          is rounded to the nearest even integer.

     The following example shows how rounding differs for exact and
     approximate values:

          mysql> SELECT ROUND(2.5), ROUND(25E-1);
          +------------+--------------+
          | ROUND(2.5) | ROUND(25E-1) |
          +------------+--------------+
          | 3          |            2 |
          +------------+--------------+

     For more information, see precision-math.

   *
     'SIGN(X)'

     Returns the sign of the argument as '-1', '0', or '1', depending on
     whether X is negative, zero, or positive.

          mysql> SELECT SIGN(-32);
                  -> -1
          mysql> SELECT SIGN(0);
                  -> 0
          mysql> SELECT SIGN(234);
                  -> 1

   *
     'SIN(X)'

     Returns the sine of X, where X is given in radians.

          mysql> SELECT SIN(PI());
                  -> 1.2246063538224e-16
          mysql> SELECT ROUND(SIN(PI()));
                  -> 0

   *
     'SQRT(X)'

     Returns the square root of a nonnegative number X.

          mysql> SELECT SQRT(4);
                  -> 2
          mysql> SELECT SQRT(20);
                  -> 4.4721359549996
          mysql> SELECT SQRT(-16);
                  -> NULL

   *
     'TAN(X)'

     Returns the tangent of X, where X is given in radians.

          mysql> SELECT TAN(PI());
                  -> -1.2246063538224e-16
          mysql> SELECT TAN(PI()+1);
                  -> 1.5574077246549

   *
     'TRUNCATE(X,D)'

     Returns the number X, truncated to D decimal places.  If D is '0',
     the result has no decimal point or fractional part.  D can be
     negative to cause D digits left of the decimal point of the value X
     to become zero.

          mysql> SELECT TRUNCATE(1.223,1);
                  -> 1.2
          mysql> SELECT TRUNCATE(1.999,1);
                  -> 1.9
          mysql> SELECT TRUNCATE(1.999,0);
                  -> 1
          mysql> SELECT TRUNCATE(-1.999,1);
                  -> -1.9
          mysql> SELECT TRUNCATE(122,-2);
                 -> 100
          mysql> SELECT TRUNCATE(10.28*100,0);
                 -> 1028

     All numbers are rounded toward zero.

12.7 Date and Time Functions
============================

This section describes the functions that can be used to manipulate
temporal values.  See date-and-time-types, for a description of
the range of values each date and time type has and the valid formats in
which values may be specified.

*Date and Time Functions*

Name                          Description

'ADDDATE()'                   Add time values (intervals) to a date
                              value

'ADDTIME()'                   Add time

'CONVERT_TZ()'                Convert from one time zone to another

'CURDATE()'                   Return the current date

'CURRENT_DATE()',             Synonyms for CURDATE()
'CURRENT_DATE'

'CURRENT_TIME()',             Synonyms for CURTIME()
'CURRENT_TIME'

'CURRENT_TIMESTAMP()',        Synonyms for NOW()
'CURRENT_TIMESTAMP'

'CURTIME()'                   Return the current time

'DATE()'                      Extract the date part of a date or
                              datetime expression

'DATE_ADD()'                  Add time values (intervals) to a date
                              value

'DATE_FORMAT()'               Format date as specified

'DATE_SUB()'                  Subtract a time value (interval) from a
                              date

'DATEDIFF()'                  Subtract two dates

'DAY()'                       Synonym for DAYOFMONTH()

'DAYNAME()'                   Return the name of the weekday

'DAYOFMONTH()'                Return the day of the month (0-31)

'DAYOFWEEK()'                 Return the weekday index of the argument

'DAYOFYEAR()'                 Return the day of the year (1-366)

'EXTRACT()'                   Extract part of a date

'FROM_DAYS()'                 Convert a day number to a date

'FROM_UNIXTIME()'             Format Unix timestamp as a date

'GET_FORMAT()'                Return a date format string

'HOUR()'                      Extract the hour

'LAST_DAY'                    Return the last day of the month for the
                              argument

'LOCALTIME()', 'LOCALTIME'    Synonym for NOW()

'LOCALTIMESTAMP',             Synonym for NOW()
'LOCALTIMESTAMP()'

'MAKEDATE()'                  Create a date from the year and day of
                              year

'MAKETIME()'                  Create time from hour, minute, second

'MICROSECOND()'               Return the microseconds from argument

'MINUTE()'                    Return the minute from the argument

'MONTH()'                     Return the month from the date passed

'MONTHNAME()'                 Return the name of the month

'NOW()'                       Return the current date and time

'PERIOD_ADD()'                Add a period to a year-month

'PERIOD_DIFF()'               Return the number of months between
                              periods

'QUARTER()'                   Return the quarter from a date argument

'SEC_TO_TIME()'               Converts seconds to 'HH:MM:SS' format

'SECOND()'                    Return the second (0-59)

'STR_TO_DATE()'               Convert a string to a date

'SUBDATE()'                   Synonym for DATE_SUB() when invoked with
                              three arguments

'SUBTIME()'                   Subtract times

'SYSDATE()'                   Return the time at which the function
                              executes

'TIME()'                      Extract the time portion of the
                              expression passed

'TIME_FORMAT()'               Format as time

'TIME_TO_SEC()'               Return the argument converted to seconds

'TIMEDIFF()'                  Subtract time

'TIMESTAMP()'                 With a single argument, this function
                              returns the date or datetime expression;
                              with two arguments, the sum of the
                              arguments

'TIMESTAMPADD()'              Add an interval to a datetime expression

'TIMESTAMPDIFF()'             Subtract an interval from a datetime
                              expression

'TO_DAYS()'                   Return the date argument converted to
                              days

'TO_SECONDS()'                Return the date or datetime argument
                              converted to seconds since Year 0

'UNIX_TIMESTAMP()'            Return a Unix timestamp

'UTC_DATE()'                  Return the current UTC date

'UTC_TIME()'                  Return the current UTC time

'UTC_TIMESTAMP()'             Return the current UTC date and time

'WEEK()'                      Return the week number

'WEEKDAY()'                   Return the weekday index

'WEEKOFYEAR()'                Return the calendar week of the date
                              (1-53)

'YEAR()'                      Return the year

'YEARWEEK()'                  Return the year and week

Here is an example that uses date functions.  The following query
selects all rows with a DATE_COL value from within the last 30 days:

     mysql> SELECT SOMETHING FROM TBL_NAME
         -> WHERE DATE_SUB(CURDATE(),INTERVAL 30 DAY) <= DATE_COL;

The query also selects rows with dates that lie in the future.

Functions that expect date values usually accept datetime values and
ignore the time part.  Functions that expect time values usually accept
datetime values and ignore the date part.

Functions that return the current date or time each are evaluated only
once per query at the start of query execution.  This means that
multiple references to a function such as 'NOW()' within a single query
always produce the same result.  (For our purposes, a single query also
includes a call to a stored program (stored routine, trigger, or event)
and all subprograms called by that program.)  This principle also
applies to 'CURDATE()', 'CURTIME()', 'UTC_DATE()', 'UTC_TIME()',
'UTC_TIMESTAMP()', and to any of their synonyms.

The 'CURRENT_TIMESTAMP()', 'CURRENT_TIME()', 'CURRENT_DATE()', and
'FROM_UNIXTIME()' functions return values in the connection's current
time zone, which is available as the value of the 'time_zone' system
variable.  In addition, 'UNIX_TIMESTAMP()' assumes that its argument is
a datetime value in the current time zone.  See
time-zone-support.

Some date functions can be used with 'zero' dates or incomplete dates
such as ''2001-11-00'', whereas others cannot.  Functions that extract
parts of dates typically work with incomplete dates and thus can return
0 when you might otherwise expect a nonzero value.  For example:

     mysql> SELECT DAYOFMONTH('2001-11-00'), MONTH('2005-00-00');
             -> 0, 0

Other functions expect complete dates and return 'NULL' for incomplete
dates.  These include functions that perform date arithmetic or that map
parts of dates to names.  For example:

     mysql> SELECT DATE_ADD('2006-05-00',INTERVAL 1 DAY);
             -> NULL
     mysql> SELECT DAYNAME('2006-05-00');
             -> NULL

Several functions are more strict when passed a 'DATE()' function value
as their argument and reject incomplete dates with a day part of zero.
These functions are affected: 'CONVERT_TZ()', 'DATE_ADD()',
'DATE_SUB()', 'DAYOFYEAR()', 'LAST_DAY()' (permits a day part of zero),
'TIMESTAMPDIFF()', 'TO_DAYS()', 'TO_SECONDS()', 'WEEK()', 'WEEKDAY()',
'WEEKOFYEAR()', 'YEARWEEK()'.

Fractional seconds for 'TIME', 'DATETIME', and 'TIMESTAMP' values are
supported, with up to microsecond precision.  Functions that take
temporal arguments accept values with fractional seconds.  Return values
from temporal functions include fractional seconds as appropriate.

   *
     'ADDDATE(DATE,INTERVAL EXPR UNIT)', 'ADDDATE(EXPR,DAYS)'

     When invoked with the 'INTERVAL' form of the second argument,
     'ADDDATE()' is a synonym for 'DATE_ADD()'.  The related function
     'SUBDATE()' is a synonym for 'DATE_SUB()'.  For information on the
     'INTERVAL' UNIT argument, see the discussion for 'DATE_ADD()'.

          mysql> SELECT DATE_ADD('2008-01-02', INTERVAL 31 DAY);
                  -> '2008-02-02'
          mysql> SELECT ADDDATE('2008-01-02', INTERVAL 31 DAY);
                  -> '2008-02-02'

     When invoked with the DAYS form of the second argument, MySQL
     treats it as an integer number of days to be added to EXPR.

          mysql> SELECT ADDDATE('2008-01-02', 31);
                  -> '2008-02-02'

   *
     'ADDTIME(EXPR1,EXPR2)'

     'ADDTIME()' adds EXPR2 to EXPR1 and returns the result.  EXPR1 is a
     time or datetime expression, and EXPR2 is a time expression.

          mysql> SELECT ADDTIME('2007-12-31 23:59:59.999999', '1 1:1:1.000002');
                  -> '2008-01-02 01:01:01.000001'
          mysql> SELECT ADDTIME('01:00:00.999999', '02:00:00.999998');
                  -> '03:00:01.999997'

   *
     'CONVERT_TZ(DT,FROM_TZ,TO_TZ)'

     'CONVERT_TZ()' converts a datetime value DT from the time zone
     given by FROM_TZ to the time zone given by TO_TZ and returns the
     resulting value.  Time zones are specified as described in
     time-zone-support.  This function returns 'NULL' if the arguments
     are invalid.

     If the value falls out of the supported range of the
     'TIMESTAMP' type when converted from FROM_TZ to UTC, no
     conversion occurs.  The 'TIMESTAMP' range is
     described in date-and-time-type-overview.

          mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','GMT','MET');
                  -> '2004-01-01 13:00:00'
          mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','+00:00','+10:00');
                  -> '2004-01-01 22:00:00'

     *Note*:

     To use named time zones such as ''MET'' or ''Europe/Moscow'', the
     time zone tables must be properly set up.  See
     time-zone-support, for instructions.

   *
     'CURDATE()'

     Returns the current date as a value in ''YYYY-MM-DD'' or 'YYYYMMDD'
     format, depending on whether the function is used in a string or
     numeric context.

          mysql> SELECT CURDATE();
                  -> '2008-06-13'
          mysql> SELECT CURDATE() + 0;
                  -> 20080613

   *
     'CURRENT_DATE', 'CURRENT_DATE()'

     'CURRENT_DATE' and 'CURRENT_DATE()' are synonyms for 'CURDATE()'.

   *
     'CURRENT_TIME', 'CURRENT_TIME([FSP])'

     'CURRENT_TIME' and 'CURRENT_TIME()' are synonyms for 'CURTIME()'.

   *
     'CURRENT_TIMESTAMP', 'CURRENT_TIMESTAMP([FSP])'

     'CURRENT_TIMESTAMP' and 'CURRENT_TIMESTAMP()' are synonyms for
     'NOW()'.

   *
     'CURTIME([FSP])'

     Returns the current time as a value in ''HH:MM:SS'' or 'HHMMSS'
     format, depending on whether the function is used in a string or
     numeric context.  The value is expressed in the current time zone.

     If the FSP argument is given to specify a fractional seconds
     precision from 0 to 6, the return value includes a fractional
     seconds part of that many digits.

          mysql> SELECT CURTIME();
                  -> '23:50:26'
          mysql> SELECT CURTIME() + 0;
                  -> 235026.000000

   *
     'DATE(EXPR)'

     Extracts the date part of the date or datetime expression EXPR.

          mysql> SELECT DATE('2003-12-31 01:02:03');
                  -> '2003-12-31'

   *
     'DATEDIFF(EXPR1,EXPR2)'

     'DATEDIFF()' returns EXPR1 − EXPR2 expressed as a value in days
     from one date to the other.  EXPR1 and EXPR2 are date or
     date-and-time expressions.  Only the date parts of the values are
     used in the calculation.

          mysql> SELECT DATEDIFF('2007-12-31 23:59:59','2007-12-30');
                  -> 1
          mysql> SELECT DATEDIFF('2010-11-30 23:59:59','2010-12-31');
                  -> -31

   *
     'DATE_ADD(DATE,INTERVAL EXPR UNIT)', 'DATE_SUB(DATE,INTERVAL EXPR
     UNIT)'

     These functions perform date arithmetic.  The DATE argument
     specifies the starting date or datetime value.  EXPR is an
     expression specifying the interval value to be added or subtracted
     from the starting date.  EXPR is a string; it may start with a '-'
     for negative intervals.  UNIT is a keyword indicating the units in
     which the expression should be interpreted.

     The 'INTERVAL' keyword and the UNIT specifier are not case
     sensitive.

     The following table shows the expected form of the EXPR argument
     for each UNIT value.

     UNIT Value                           Expected EXPR Format

     'MICROSECOND'                        'MICROSECONDS'

     'SECOND'                             'SECONDS'

     'MINUTE'                             'MINUTES'

     'HOUR'                               'HOURS'

     'DAY'                                'DAYS'

     'WEEK'                               'WEEKS'

     'MONTH'                              'MONTHS'

     'QUARTER'                            'QUARTERS'

     'YEAR'                               'YEARS'

     'SECOND_MICROSECOND'                 ''SECONDS.MICROSECONDS''

     'MINUTE_MICROSECOND'                 ''MINUTES:SECONDS.MICROSECONDS''

     'MINUTE_SECOND'                      ''MINUTES:SECONDS''

     'HOUR_MICROSECOND'                   ''HOURS:MINUTES:SECONDS.MICROSECONDS''

     'HOUR_SECOND'                        ''HOURS:MINUTES:SECONDS''

     'HOUR_MINUTE'                        ''HOURS:MINUTES''

     'DAY_MICROSECOND'                    ''DAYS
                                          HOURS:MINUTES:SECONDS.MICROSECONDS''

     'DAY_SECOND'                         ''DAYS HOURS:MINUTES:SECONDS''

     'DAY_MINUTE'                         ''DAYS HOURS:MINUTES''

     'DAY_HOUR'                           ''DAYS HOURS''

     'YEAR_MONTH'                         ''YEARS-MONTHS''

     The return value depends on the arguments:

        * 'DATETIME' if the first argument is a
          'DATETIME'. (or 'TIMESTAMP') value,
          or if the first argument is a 'DATE' and the
          UNIT value uses 'HOURS', 'MINUTES', or 'SECONDS'.

        * String otherwise.

     To ensure that the result is 'DATETIME', you can
     use 'CAST()' to convert the first argument to 'DATETIME'.

     MySQL permits any punctuation delimiter in the EXPR format.  Those
     shown in the table are the suggested delimiters.  If the DATE
     argument is a 'DATE' value and your calculations
     involve only 'YEAR', 'MONTH', and 'DAY' parts (that is, no time
     parts), the result is a 'DATE' value.  Otherwise,
     the result is a 'DATETIME' value.

     Date arithmetic also can be performed using 'INTERVAL' together
     with the '+' or '-' operator:

          date + INTERVAL EXPR UNIT
          date - INTERVAL EXPR UNIT

     'INTERVAL EXPR UNIT' is permitted on either side of the '+'
     operator if the expression on the other side is a date or datetime
     value.  For the '-' operator, 'INTERVAL EXPR UNIT' is permitted
     only on the right side, because it makes no sense to subtract a
     date or datetime value from an interval.

          mysql> SELECT '2008-12-31 23:59:59' + INTERVAL 1 SECOND;
                  -> '2009-01-01 00:00:00'
          mysql> SELECT INTERVAL 1 DAY + '2008-12-31';
                  -> '2009-01-01'
          mysql> SELECT '2005-01-01' - INTERVAL 1 SECOND;
                  -> '2004-12-31 23:59:59'
          mysql> SELECT DATE_ADD('2000-12-31 23:59:59',
              ->                 INTERVAL 1 SECOND);
                  -> '2001-01-01 00:00:00'
          mysql> SELECT DATE_ADD('2010-12-31 23:59:59',
              ->                 INTERVAL 1 DAY);
                  -> '2011-01-01 23:59:59'
          mysql> SELECT DATE_ADD('2100-12-31 23:59:59',
              ->                 INTERVAL '1:1' MINUTE_SECOND);
                  -> '2101-01-01 00:01:00'
          mysql> SELECT DATE_SUB('2005-01-01 00:00:00',
              ->                 INTERVAL '1 1:1:1' DAY_SECOND);
                  -> '2004-12-30 22:58:59'
          mysql> SELECT DATE_ADD('1900-01-01 00:00:00',
              ->                 INTERVAL '-1 10' DAY_HOUR);
                  -> '1899-12-30 14:00:00'
          mysql> SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY);
                  -> '1997-12-02'
          mysql> SELECT DATE_ADD('1992-12-31 23:59:59.000002',
              ->            INTERVAL '1.999999' SECOND_MICROSECOND);
                  -> '1993-01-01 00:00:01.000001'

     If you specify an interval value that is too short (does not
     include all the interval parts that would be expected from the UNIT
     keyword), MySQL assumes that you have left out the leftmost parts
     of the interval value.  For example, if you specify a UNIT of
     'DAY_SECOND', the value of EXPR is expected to have days, hours,
     minutes, and seconds parts.  If you specify a value like ''1:10'',
     MySQL assumes that the days and hours parts are missing and the
     value represents minutes and seconds.  In other words, ''1:10'
     DAY_SECOND' is interpreted in such a way that it is equivalent to
     ''1:10' MINUTE_SECOND'.  This is analogous to the way that MySQL
     interprets 'TIME' values as representing elapsed time
     rather than as a time of day.

     Because EXPR is treated as a string, be careful if you specify a
     nonstring value with 'INTERVAL'.  For example, with an interval
     specifier of 'HOUR_MINUTE', '6/4' evaluates to '1.5000' and is
     treated as 1 hour, 5000 minutes:

          mysql> SELECT 6/4;
                  -> 1.5000
          mysql> SELECT DATE_ADD('2009-01-01', INTERVAL 6/4 HOUR_MINUTE);
                  -> '2009-01-04 12:20:00'

     To ensure interpretation of the interval value as you expect, a
     'CAST()' operation may be used.  To treat '6/4' as 1 hour, 5
     minutes, cast it to a 'DECIMAL' value
     with a single fractional digit:

          mysql> SELECT CAST(6/4 AS DECIMAL(3,1));
                  -> 1.5
          mysql> SELECT DATE_ADD('1970-01-01 12:00:00',
              ->                 INTERVAL CAST(6/4 AS DECIMAL(3,1)) HOUR_MINUTE);
                  -> '1970-01-01 13:05:00'

     If you add to or subtract from a date value something that contains
     a time part, the result is automatically converted to a datetime
     value:

          mysql> SELECT DATE_ADD('2013-01-01', INTERVAL 1 DAY);
                  -> '2013-01-02'
          mysql> SELECT DATE_ADD('2013-01-01', INTERVAL 1 HOUR);
                  -> '2013-01-01 01:00:00'

     If you add 'MONTH', 'YEAR_MONTH', or 'YEAR' and the resulting date
     has a day that is larger than the maximum day for the new month,
     the day is adjusted to the maximum days in the new month:

          mysql> SELECT DATE_ADD('2009-01-30', INTERVAL 1 MONTH);
                  -> '2009-02-28'

     Date arithmetic operations require complete dates and do not work
     with incomplete dates such as ''2006-07-00'' or badly malformed
     dates:

          mysql> SELECT DATE_ADD('2006-07-00', INTERVAL 1 DAY);
                  -> NULL
          mysql> SELECT '2005-03-32' + INTERVAL 1 MONTH;
                  -> NULL

   *
     'DATE_FORMAT(DATE,FORMAT)'

     Formats the DATE value according to the FORMAT string.

     The following specifiers may be used in the FORMAT string.  The '%'
     character is required before format specifier characters.

     Specifier      Description

     '%a'           Abbreviated weekday name ('Sun'..'Sat')

     '%b'           Abbreviated month name ('Jan'..'Dec')

     '%c'           Month, numeric ('0'..'12')

     '%D'           Day of the month with English suffix ('0th',
                    '1st', '2nd', '3rd', ...)

     '%d'           Day of the month, numeric ('00'..'31')

     '%e'           Day of the month, numeric ('0'..'31')

     '%f'           Microseconds ('000000'..'999999')

     '%H'           Hour ('00'..'23')

     '%h'           Hour ('01'..'12')

     '%I'           Hour ('01'..'12')

     '%i'           Minutes, numeric ('00'..'59')

     '%j'           Day of year ('001'..'366')

     '%k'           Hour ('0'..'23')

     '%l'           Hour ('1'..'12')

     '%M'           Month name ('January'..'December')

     '%m'           Month, numeric ('00'..'12')

     '%p'           'AM' or 'PM'

     '%r'           Time, 12-hour ('hh:mm:ss' followed by 'AM' or
                    'PM')

     '%S'           Seconds ('00'..'59')

     '%s'           Seconds ('00'..'59')

     '%T'           Time, 24-hour ('hh:mm:ss')

     '%U'           Week ('00'..'53'), where Sunday is the first day
                    of the week; 'WEEK()' mode 0

     '%u'           Week ('00'..'53'), where Monday is the first day
                    of the week; 'WEEK()' mode 1

     '%V'           Week ('01'..'53'), where Sunday is the first day
                    of the week; 'WEEK()' mode 2; used with '%X'

     '%v'           Week ('01'..'53'), where Monday is the first day
                    of the week; 'WEEK()' mode 3; used with '%x'

     '%W'           Weekday name ('Sunday'..'Saturday')

     '%w'           Day of the week ('0'=Sunday..'6'=Saturday)

     '%X'           Year for the week where Sunday is the first day
                    of the week, numeric, four digits; used with
                    '%V'

     '%x'           Year for the week, where Monday is the first day
                    of the week, numeric, four digits; used with
                    '%v'

     '%Y'           Year, numeric, four digits

     '%y'           Year, numeric (two digits)

     '%%'           A literal '%' character

     '%X'           X, for any 'X' not listed above

     Ranges for the month and day specifiers begin with zero due to the
     fact that MySQL permits the storing of incomplete dates such as
     ''2014-00-00''.

     The language used for day and month names and abbreviations is
     controlled by the value of the 'lc_time_names' system variable
     (see locale-support).

     For the '%U', '%u', '%V', and '%v' specifiers, see the description
     of the 'WEEK()' function for information about the mode values.
     The mode affects how week numbering occurs.

     'DATE_FORMAT()' returns a string with a character set and collation
     given by 'character_set_connection' and 'collation_connection' so
     that it can return month and weekday names containing non-ASCII
     characters.

          mysql> SELECT DATE_FORMAT('2009-10-04 22:23:00', '%W %M %Y');
                  -> 'Sunday October 2009'
          mysql> SELECT DATE_FORMAT('2007-10-04 22:23:00', '%H:%i:%s');
                  -> '22:23:00'
          mysql> SELECT DATE_FORMAT('1900-10-04 22:23:00',
              ->                 '%D %y %a %d %m %b %j');
                  -> '4th 00 Thu 04 10 Oct 277'
          mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00',
              ->                 '%H %k %I %r %T %S %w');
                  -> '22 22 10 10:23:00 PM 22:23:00 00 6'
          mysql> SELECT DATE_FORMAT('1999-01-01', '%X %V');
                  -> '1998 52'
          mysql> SELECT DATE_FORMAT('2006-06-00', '%d');
                  -> '00'

   *
     'DATE_SUB(DATE,INTERVAL EXPR UNIT)'

     See the description for 'DATE_ADD()'.

   *
     'DAY(DATE)'

     'DAY()' is a synonym for 'DAYOFMONTH()'.

   *
     'DAYNAME(DATE)'

     Returns the name of the weekday for DATE.  The language used for
     the name is controlled by the value of the 'lc_time_names' system
     variable (see locale-support).

          mysql> SELECT DAYNAME('2007-02-03');
                  -> 'Saturday'

   *
     'DAYOFMONTH(DATE)'

     Returns the day of the month for DATE, in the range '1' to '31', or
     '0' for dates such as ''0000-00-00'' or ''2008-00-00'' that have a
     zero day part.

          mysql> SELECT DAYOFMONTH('2007-02-03');
                  -> 3

   *
     'DAYOFWEEK(DATE)'

     Returns the weekday index for DATE ('1' = Sunday, '2' = Monday,
     ..., '7' = Saturday).  These index values correspond to the ODBC
     standard.

          mysql> SELECT DAYOFWEEK('2007-02-03');
                  -> 7

   *
     'DAYOFYEAR(DATE)'

     Returns the day of the year for DATE, in the range '1' to '366'.

          mysql> SELECT DAYOFYEAR('2007-02-03');
                  -> 34

   *
     'EXTRACT(UNIT FROM DATE)'

     The 'EXTRACT()' function uses the same kinds of unit specifiers as
     'DATE_ADD()' or 'DATE_SUB()', but extracts parts from the date
     rather than performing date arithmetic.

          mysql> SELECT EXTRACT(YEAR FROM '2009-07-02');
                 -> 2009
          mysql> SELECT EXTRACT(YEAR_MONTH FROM '2009-07-02 01:02:03');
                 -> 200907
          mysql> SELECT EXTRACT(DAY_MINUTE FROM '2009-07-02 01:02:03');
                 -> 20102
          mysql> SELECT EXTRACT(MICROSECOND
              ->                FROM '2003-01-02 10:30:00.000123');
                  -> 123

   *
     'FROM_DAYS(N)'

     Given a day number N, returns a 'DATE' value.

          mysql> SELECT FROM_DAYS(730669);
                  -> '2000-07-03'

     Use 'FROM_DAYS()' with caution on old dates.  It is not intended
     for use with values that precede the advent of the Gregorian
     calendar (1582).  See mysql-calendar.

   *
     'FROM_UNIXTIME(UNIX_TIMESTAMP)',
     'FROM_UNIXTIME(UNIX_TIMESTAMP,FORMAT)'

     Returns a representation of the UNIX_TIMESTAMP argument as a value
     in ''YYYY-MM-DD HH:MM:SS'' or 'YYYYMMDDHHMMSS' format, depending on
     whether the function is used in a string or numeric context.  The
     value is expressed in the current time zone.  UNIX_TIMESTAMP is an
     internal timestamp value such as is produced by the
     'UNIX_TIMESTAMP()' function.

     If FORMAT is given, the result is formatted according to the FORMAT
     string, which is used the same way as listed in the entry for the
     'DATE_FORMAT()' function.

          mysql> SELECT FROM_UNIXTIME(1447430881);
                  -> '2015-11-13 10:08:01'
          mysql> SELECT FROM_UNIXTIME(1447430881) + 0;
                  -> 20151113100801
          mysql> SELECT FROM_UNIXTIME(UNIX_TIMESTAMP(),
              ->                      '%Y %D %M %h:%i:%s %x');
                  -> '2015 13th November 10:08:01 2015'

     Note: If you use 'UNIX_TIMESTAMP()' and 'FROM_UNIXTIME()' to
     convert between 'TIMESTAMP' values and Unix
     timestamp values, the conversion is lossy because the mapping is
     not one-to-one in both directions.  For details, see the
     description of the 'UNIX_TIMESTAMP()' function.

   *
     'GET_FORMAT({DATE|TIME|DATETIME},
     {'EUR'|'USA'|'JIS'|'ISO'|'INTERNAL'})'

     Returns a format string.  This function is useful in combination
     with the 'DATE_FORMAT()' and the 'STR_TO_DATE()' functions.

     The possible values for the first and second arguments result in
     several possible format strings (for the specifiers used, see the
     table in the 'DATE_FORMAT()' function description).  ISO format
     refers to ISO 9075, not ISO 8601.

     Function Call                               Result

     'GET_FORMAT(DATE,'USA')'                    ''%m.%d.%Y''

     'GET_FORMAT(DATE,'JIS')'                    ''%Y-%m-%d''

     'GET_FORMAT(DATE,'ISO')'                    ''%Y-%m-%d''

     'GET_FORMAT(DATE,'EUR')'                    ''%d.%m.%Y''

     'GET_FORMAT(DATE,'INTERNAL')'               ''%Y%m%d''

     'GET_FORMAT(DATETIME,'USA')'                ''%Y-%m-%d %H.%i.%s''

     'GET_FORMAT(DATETIME,'JIS')'                ''%Y-%m-%d %H:%i:%s''

     'GET_FORMAT(DATETIME,'ISO')'                ''%Y-%m-%d %H:%i:%s''

     'GET_FORMAT(DATETIME,'EUR')'                ''%Y-%m-%d %H.%i.%s''

     'GET_FORMAT(DATETIME,'INTERNAL')'           ''%Y%m%d%H%i%s''

     'GET_FORMAT(TIME,'USA')'                    ''%h:%i:%s %p''

     'GET_FORMAT(TIME,'JIS')'                    ''%H:%i:%s''

     'GET_FORMAT(TIME,'ISO')'                    ''%H:%i:%s''

     'GET_FORMAT(TIME,'EUR')'                    ''%H.%i.%s''

     'GET_FORMAT(TIME,'INTERNAL')'               ''%H%i%s''

     'TIMESTAMP' can also be used as the first argument
     to 'GET_FORMAT()', in which case the function returns the same
     values as for 'DATETIME'.

          mysql> SELECT DATE_FORMAT('2003-10-03',GET_FORMAT(DATE,'EUR'));
                  -> '03.10.2003'
          mysql> SELECT STR_TO_DATE('10.31.2003',GET_FORMAT(DATE,'USA'));
                  -> '2003-10-31'

   *
     'HOUR(TIME)'

     Returns the hour for TIME.  The range of the return value is '0' to
     '23' for time-of-day values.  However, the range of 'TIME'
     values actually is much larger, so 'HOUR' can return values
     greater than '23'.

          mysql> SELECT HOUR('10:05:03');
                  -> 10
          mysql> SELECT HOUR('272:59:59');
                  -> 272

   *
     'LAST_DAY(DATE)'

     Takes a date or datetime value and returns the corresponding value
     for the last day of the month.  Returns 'NULL' if the argument is
     invalid.

          mysql> SELECT LAST_DAY('2003-02-05');
                  -> '2003-02-28'
          mysql> SELECT LAST_DAY('2004-02-05');
                  -> '2004-02-29'
          mysql> SELECT LAST_DAY('2004-01-01 01:01:01');
                  -> '2004-01-31'
          mysql> SELECT LAST_DAY('2003-03-32');
                  -> NULL

   *
     'LOCALTIME', 'LOCALTIME([FSP])'

     'LOCALTIME' and 'LOCALTIME()' are synonyms for 'NOW()'.

   *
     'LOCALTIMESTAMP', 'LOCALTIMESTAMP([FSP])'

     'LOCALTIMESTAMP' and 'LOCALTIMESTAMP()' are synonyms for 'NOW()'.

   *
     'MAKEDATE(YEAR,DAYOFYEAR)'

     Returns a date, given year and day-of-year values.  DAYOFYEAR must
     be greater than 0 or the result is 'NULL'.

          mysql> SELECT MAKEDATE(2011,31), MAKEDATE(2011,32);
                  -> '2011-01-31', '2011-02-01'
          mysql> SELECT MAKEDATE(2011,365), MAKEDATE(2014,365);
                  -> '2011-12-31', '2014-12-31'
          mysql> SELECT MAKEDATE(2011,0);
                  -> NULL

   *
     'MAKETIME(HOUR,MINUTE,SECOND)'

     Returns a time value calculated from the HOUR, MINUTE, and SECOND
     arguments.

     The SECOND argument can have a fractional part.

          mysql> SELECT MAKETIME(12,15,30);
                  -> '12:15:30'

   *
     'MICROSECOND(EXPR)'

     Returns the microseconds from the time or datetime expression EXPR
     as a number in the range from '0' to '999999'.

          mysql> SELECT MICROSECOND('12:00:00.123456');
                  -> 123456
          mysql> SELECT MICROSECOND('2009-12-31 23:59:59.000010');
                  -> 10

   *
     'MINUTE(TIME)'

     Returns the minute for TIME, in the range '0' to '59'.

          mysql> SELECT MINUTE('2008-02-03 10:05:03');
                  -> 5

   *
     'MONTH(DATE)'

     Returns the month for DATE, in the range '1' to '12' for January to
     December, or '0' for dates such as ''0000-00-00'' or ''2008-00-00''
     that have a zero month part.

          mysql> SELECT MONTH('2008-02-03');
                  -> 2

   *
     'MONTHNAME(DATE)'

     Returns the full name of the month for DATE.  The language used for
     the name is controlled by the value of the 'lc_time_names' system
     variable (see locale-support).

          mysql> SELECT MONTHNAME('2008-02-03');
                  -> 'February'

   *
     'NOW([FSP])'

     Returns the current date and time as a value in ''YYYY-MM-DD
     HH:MM:SS'' or 'YYYYMMDDHHMMSS' format, depending on whether the
     function is used in a string or numeric context.  The value is
     expressed in the current time zone.

     If the FSP argument is given to specify a fractional seconds
     precision from 0 to 6, the return value includes a fractional
     seconds part of that many digits.

          mysql> SELECT NOW();
                  -> '2007-12-15 23:50:26'
          mysql> SELECT NOW() + 0;
                  -> 20071215235026.000000

     'NOW()' returns a constant time that indicates the time at which
     the statement began to execute.  (Within a stored function or
     trigger, 'NOW()' returns the time at which the function or
     triggering statement began to execute.)  This differs from the
     behavior for 'SYSDATE()', which returns the exact time at which it
     executes.

          mysql> SELECT NOW(), SLEEP(2), NOW();
          +---------------------+----------+---------------------+
          | NOW()               | SLEEP(2) | NOW()               |
          +---------------------+----------+---------------------+
          | 2006-04-12 13:47:36 |        0 | 2006-04-12 13:47:36 |
          +---------------------+----------+---------------------+

          mysql> SELECT SYSDATE(), SLEEP(2), SYSDATE();
          +---------------------+----------+---------------------+
          | SYSDATE()           | SLEEP(2) | SYSDATE()           |
          +---------------------+----------+---------------------+
          | 2006-04-12 13:47:44 |        0 | 2006-04-12 13:47:46 |
          +---------------------+----------+---------------------+

     In addition, the 'SET TIMESTAMP' statement affects the value
     returned by 'NOW()' but not by 'SYSDATE()'.  This means that
     timestamp settings in the binary log have no effect on invocations
     of 'SYSDATE()'.  Setting the timestamp to a nonzero value causes
     each subsequent invocation of 'NOW()' to return that value.
     Setting the timestamp to zero cancels this effect so that 'NOW()'
     once again returns the current date and time.

     See the description for 'SYSDATE()' for additional information
     about the differences between the two functions.

   *
     'PERIOD_ADD(P,N)'

     Adds N months to period P (in the format 'YYMM' or 'YYYYMM').
     Returns a value in the format 'YYYYMM'.  Note that the period
     argument P is _not_ a date value.

          mysql> SELECT PERIOD_ADD(200801,2);
                  -> 200803

   *
     'PERIOD_DIFF(P1,P2)'

     Returns the number of months between periods P1 and P2.  P1 and P2
     should be in the format 'YYMM' or 'YYYYMM'.  Note that the period
     arguments P1 and P2 are _not_ date values.

          mysql> SELECT PERIOD_DIFF(200802,200703);
                  -> 11

   *
     'QUARTER(DATE)'

     Returns the quarter of the year for DATE, in the range '1' to '4'.

          mysql> SELECT QUARTER('2008-04-01');
                  -> 2

   *
     'SECOND(TIME)'

     Returns the second for TIME, in the range '0' to '59'.

          mysql> SELECT SECOND('10:05:03');
                  -> 3

   *
     'SEC_TO_TIME(SECONDS)'

     Returns the SECONDS argument, converted to hours, minutes, and
     seconds, as a 'TIME' value.  The range of the result
     is constrained to that of the 'TIME' data type.  A
     warning occurs if the argument corresponds to a value outside that
     range.

          mysql> SELECT SEC_TO_TIME(2378);
                  -> '00:39:38'
          mysql> SELECT SEC_TO_TIME(2378) + 0;
                  -> 3938

   *
     'STR_TO_DATE(STR,FORMAT)'

     This is the inverse of the 'DATE_FORMAT()' function.  It takes a
     string STR and a format string FORMAT.  'STR_TO_DATE()' returns a
     'DATETIME' value if the format string contains
     both date and time parts, or a 'DATE' or
     'TIME' value if the string contains only date or time parts.
     If the date, time, or datetime value extracted from STR is illegal,
     'STR_TO_DATE()' returns 'NULL' and produces a warning.

     The server scans STR attempting to match FORMAT to it.  The format
     string can contain literal characters and format specifiers
     beginning with '%'.  Literal characters in FORMAT must match
     literally in STR.  Format specifiers in FORMAT must match a date or
     time part in STR.  For the specifiers that can be used in FORMAT,
     see the 'DATE_FORMAT()' function description.

          mysql> SELECT STR_TO_DATE('01,5,2013','%d,%m,%Y');
                  -> '2013-05-01'
          mysql> SELECT STR_TO_DATE('May 1, 2013','%M %d,%Y');
                  -> '2013-05-01'

     Scanning starts at the beginning of STR and fails if FORMAT is
     found not to match.  Extra characters at the end of STR are
     ignored.

          mysql> SELECT STR_TO_DATE('a09:30:17','a%h:%i:%s');
                  -> '09:30:17'
          mysql> SELECT STR_TO_DATE('a09:30:17','%h:%i:%s');
                  -> NULL
          mysql> SELECT STR_TO_DATE('09:30:17a','%h:%i:%s');
                  -> '09:30:17'

     Unspecified date or time parts have a value of 0, so incompletely
     specified values in STR produce a result with some or all parts set
     to 0:

          mysql> SELECT STR_TO_DATE('abc','abc');
                  -> '0000-00-00'
          mysql> SELECT STR_TO_DATE('9','%m');
                  -> '0000-09-00'
          mysql> SELECT STR_TO_DATE('9','%s');
                  -> '00:00:09'

     Range checking on the parts of date values is as described in
     datetime.  This means, for example, that 'zero' dates or dates
     with part values of 0 are permitted unless the SQL mode is set to
     disallow such values.

          mysql> SELECT STR_TO_DATE('00/00/0000', '%m/%d/%Y');
                  -> '0000-00-00'
          mysql> SELECT STR_TO_DATE('04/31/2004', '%m/%d/%Y');
                  -> '2004-04-31'

     If the 'NO_ZERO_DATE' or 'NO_ZERO_IN_DATE' SQL mode is enabled,
     zero dates or part of dates are disallowed.  In that case,
     'STR_TO_DATE()' returns 'NULL' and generates a warning:

          mysql> SET sql_mode = '';
          mysql> SELECT STR_TO_DATE('15:35:00', '%H:%i:%s');
          +-------------------------------------+
          | STR_TO_DATE('15:35:00', '%H:%i:%s') |
          +-------------------------------------+
          | 15:35:00                            |
          +-------------------------------------+
          mysql> SET sql_mode = 'NO_ZERO_IN_DATE';
          mysql> SELECT STR_TO_DATE('15:35:00', '%h:%i:%s');
          +-------------------------------------+
          | STR_TO_DATE('15:35:00', '%h:%i:%s') |
          +-------------------------------------+
          | NULL                                |
          +-------------------------------------+
          mysql> SHOW WARNINGS\G
          *************************** 1. row ***************************
            Level: Warning
             Code: 1411
          Message: Incorrect datetime value: '15:35:00' for function str_to_date

     *Note*:

     You cannot use format '"%X%V"' to convert a year-week string to a
     date because the combination of a year and week does not uniquely
     identify a year and month if the week crosses a month boundary.  To
     convert a year-week to a date, you should also specify the weekday:

          mysql> SELECT STR_TO_DATE('200442 Monday', '%X%V %W');
                  -> '2004-10-18'

   *
     'SUBDATE(DATE,INTERVAL EXPR UNIT)', 'SUBDATE(EXPR,DAYS)'

     When invoked with the 'INTERVAL' form of the second argument,
     'SUBDATE()' is a synonym for 'DATE_SUB()'.  For information on the
     'INTERVAL' UNIT argument, see the discussion for 'DATE_ADD()'.

          mysql> SELECT DATE_SUB('2008-01-02', INTERVAL 31 DAY);
                  -> '2007-12-02'
          mysql> SELECT SUBDATE('2008-01-02', INTERVAL 31 DAY);
                  -> '2007-12-02'

     The second form enables the use of an integer value for DAYS.  In
     such cases, it is interpreted as the number of days to be
     subtracted from the date or datetime expression EXPR.

          mysql> SELECT SUBDATE('2008-01-02 12:00:00', 31);
                  -> '2007-12-02 12:00:00'

   *
     'SUBTIME(EXPR1,EXPR2)'

     'SUBTIME()' returns EXPR1 − EXPR2 expressed as a value in the
     same format as EXPR1.  EXPR1 is a time or datetime expression, and
     EXPR2 is a time expression.

          mysql> SELECT SUBTIME('2007-12-31 23:59:59.999999','1 1:1:1.000002');
                  -> '2007-12-30 22:58:58.999997'
          mysql> SELECT SUBTIME('01:00:00.999999', '02:00:00.999998');
                  -> '-00:59:59.999999'

   *
     'SYSDATE([FSP])'

     Returns the current date and time as a value in ''YYYY-MM-DD
     HH:MM:SS'' or 'YYYYMMDDHHMMSS' format, depending on whether the
     function is used in a string or numeric context.

     If the FSP argument is given to specify a fractional seconds
     precision from 0 to 6, the return value includes a fractional
     seconds part of that many digits.

     'SYSDATE()' returns the time at which it executes.  This differs
     from the behavior for 'NOW()', which returns a constant time that
     indicates the time at which the statement began to execute.
     (Within a stored function or trigger, 'NOW()' returns the time at
     which the function or triggering statement began to execute.)

          mysql> SELECT NOW(), SLEEP(2), NOW();
          +---------------------+----------+---------------------+
          | NOW()               | SLEEP(2) | NOW()               |
          +---------------------+----------+---------------------+
          | 2006-04-12 13:47:36 |        0 | 2006-04-12 13:47:36 |
          +---------------------+----------+---------------------+

          mysql> SELECT SYSDATE(), SLEEP(2), SYSDATE();
          +---------------------+----------+---------------------+
          | SYSDATE()           | SLEEP(2) | SYSDATE()           |
          +---------------------+----------+---------------------+
          | 2006-04-12 13:47:44 |        0 | 2006-04-12 13:47:46 |
          +---------------------+----------+---------------------+

     In addition, the 'SET TIMESTAMP' statement affects the value
     returned by 'NOW()' but not by 'SYSDATE()'.  This means that
     timestamp settings in the binary log have no effect on invocations
     of 'SYSDATE()'.

     Because 'SYSDATE()' can return different values even within the
     same statement, and is not affected by 'SET TIMESTAMP', it is
     nondeterministic and therefore unsafe for replication if
     statement-based binary logging is used.  If that is a problem, you
     can use row-based logging.

     Alternatively, you can use the '--sysdate-is-now' option to cause
     'SYSDATE()' to be an alias for 'NOW()'.  This works if the option
     is used on both the master and the slave.

     The nondeterministic nature of 'SYSDATE()' also means that indexes
     cannot be used for evaluating expressions that refer to it.

   *
     'TIME(EXPR)'

     Extracts the time part of the time or datetime expression EXPR and
     returns it as a string.

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

          mysql> SELECT TIME('2003-12-31 01:02:03');
                  -> '01:02:03'
          mysql> SELECT TIME('2003-12-31 01:02:03.000123');
                  -> '01:02:03.000123'

   *
     'TIMEDIFF(EXPR1,EXPR2)'

     'TIMEDIFF()' returns EXPR1 − EXPR2 expressed as a time value.
     EXPR1 and EXPR2 are time or date-and-time expressions, but both
     must be of the same type.

     The result returned by 'TIMEDIFF()' is limited to the range allowed
     for 'TIME' values.  Alternatively, you can use either
     of the functions 'TIMESTAMPDIFF()' and 'UNIX_TIMESTAMP()', both of
     which return integers.

          mysql> SELECT TIMEDIFF('2000:01:01 00:00:00',
              ->                 '2000:01:01 00:00:00.000001');
                  -> '-00:00:00.000001'
          mysql> SELECT TIMEDIFF('2008-12-31 23:59:59.000001',
              ->                 '2008-12-30 01:01:01.000002');
                  -> '46:58:57.999999'

   *
     'TIMESTAMP(EXPR)', 'TIMESTAMP(EXPR1,EXPR2)'

     With a single argument, this function returns the date or datetime
     expression EXPR as a datetime value.  With two arguments, it adds
     the time expression EXPR2 to the date or datetime expression EXPR1
     and returns the result as a datetime value.

          mysql> SELECT TIMESTAMP('2003-12-31');
                  -> '2003-12-31 00:00:00'
          mysql> SELECT TIMESTAMP('2003-12-31 12:00:00','12:00:00');
                  -> '2004-01-01 00:00:00'

   *
     'TIMESTAMPADD(UNIT,INTERVAL,DATETIME_EXPR)'

     Adds the integer expression INTERVAL to the date or datetime
     expression DATETIME_EXPR.  The unit for INTERVAL is given by the
     UNIT argument, which should be one of the following values:
     'MICROSECOND' (microseconds), 'SECOND', 'MINUTE', 'HOUR', 'DAY',
     'WEEK', 'MONTH', 'QUARTER', or 'YEAR'.

     The UNIT value may be specified using one of keywords as shown, or
     with a prefix of 'SQL_TSI_'.  For example, 'DAY' and 'SQL_TSI_DAY'
     both are legal.

          mysql> SELECT TIMESTAMPADD(MINUTE,1,'2003-01-02');
                  -> '2003-01-02 00:01:00'
          mysql> SELECT TIMESTAMPADD(WEEK,1,'2003-01-02');
                  -> '2003-01-09'

   *
     'TIMESTAMPDIFF(UNIT,DATETIME_EXPR1,DATETIME_EXPR2)'

     Returns DATETIME_EXPR2 − DATETIME_EXPR1, where DATETIME_EXPR1 and
     DATETIME_EXPR2 are date or datetime expressions.  One expression
     may be a date and the other a datetime; a date value is treated as
     a datetime having the time part ''00:00:00'' where necessary.  The
     unit for the result (an integer) is given by the UNIT argument.
     The legal values for UNIT are the same as those listed in the
     description of the 'TIMESTAMPADD()' function.

          mysql> SELECT TIMESTAMPDIFF(MONTH,'2003-02-01','2003-05-01');
                  -> 3
          mysql> SELECT TIMESTAMPDIFF(YEAR,'2002-05-01','2001-01-01');
                  -> -1
          mysql> SELECT TIMESTAMPDIFF(MINUTE,'2003-02-01','2003-05-01 12:05:55');
                  -> 128885

     *Note*:

     The order of the date or datetime arguments for this function is
     the opposite of that used with the 'TIMESTAMP()' function when
     invoked with 2 arguments.

   *
     'TIME_FORMAT(TIME,FORMAT)'

     This is used like the 'DATE_FORMAT()' function, but the FORMAT
     string may contain format specifiers only for hours, minutes,
     seconds, and microseconds.  Other specifiers produce a 'NULL' value
     or '0'.

     If the TIME value contains an hour part that is greater than '23',
     the '%H' and '%k' hour format specifiers produce a value larger
     than the usual range of '0..23'.  The other hour format specifiers
     produce the hour value modulo 12.

          mysql> SELECT TIME_FORMAT('100:00:00', '%H %k %h %I %l');
                  -> '100 100 04 04 4'

   *
     'TIME_TO_SEC(TIME)'

     Returns the TIME argument, converted to seconds.

          mysql> SELECT TIME_TO_SEC('22:23:00');
                  -> 80580
          mysql> SELECT TIME_TO_SEC('00:39:38');
                  -> 2378

   *
     'TO_DAYS(DATE)'

     Given a date DATE, returns a day number (the number of days since
     year 0).

          mysql> SELECT TO_DAYS(950501);
                  -> 728779
          mysql> SELECT TO_DAYS('2007-10-07');
                  -> 733321

     'TO_DAYS()' is not intended for use with values that precede the
     advent of the Gregorian calendar (1582), because it does not take
     into account the days that were lost when the calendar was changed.
     For dates before 1582 (and possibly a later year in other locales),
     results from this function are not reliable.  See
     mysql-calendar, for details.

     Remember that MySQL converts two-digit year values in dates to
     four-digit form using the rules in date-and-time-types.
     For example, ''2008-10-07'' and ''08-10-07'' are seen as identical
     dates:

          mysql> SELECT TO_DAYS('2008-10-07'), TO_DAYS('08-10-07');
                  -> 733687, 733687

     In MySQL, the zero date is defined as ''0000-00-00'', even though
     this date is itself considered invalid.  This means that, for
     ''0000-00-00'' and ''0000-01-01'', 'TO_DAYS()' returns the values
     shown here:

          mysql> SELECT TO_DAYS('0000-00-00');
          +-----------------------+
          | to_days('0000-00-00') |
          +-----------------------+
          |                  NULL |
          +-----------------------+
          1 row in set, 1 warning (0.00 sec)

          mysql> SHOW WARNINGS;
          +---------+------+----------------------------------------+
          | Level   | Code | Message                                |
          +---------+------+----------------------------------------+
          | Warning | 1292 | Incorrect datetime value: '0000-00-00' |
          +---------+------+----------------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT TO_DAYS('0000-01-01');
          +-----------------------+
          | to_days('0000-01-01') |
          +-----------------------+
          |                     1 |
          +-----------------------+
          1 row in set (0.00 sec)

     This is true whether or not the 'ALLOW_INVALID_DATES' SQL server
     mode is enabled.

   *
     'TO_SECONDS(EXPR)'

     Given a date or datetime EXPR, returns the number of seconds since
     the year 0.  If EXPR is not a valid date or datetime value, returns
     'NULL'.

          mysql> SELECT TO_SECONDS(950501);
                  -> 62966505600
          mysql> SELECT TO_SECONDS('2009-11-29');
                  -> 63426672000
          mysql> SELECT TO_SECONDS('2009-11-29 13:43:32');
                  -> 63426721412
          mysql> SELECT TO_SECONDS( NOW() );
                  -> 63426721458

     Like 'TO_DAYS()', 'TO_SECONDS()' is not intended for use with
     values that precede the advent of the Gregorian calendar (1582),
     because it does not take into account the days that were lost when
     the calendar was changed.  For dates before 1582 (and possibly a
     later year in other locales), results from this function are not
     reliable.  See mysql-calendar, for details.

     Like 'TO_DAYS()', 'TO_SECONDS()', converts two-digit year values in
     dates to four-digit form using the rules in
     date-and-time-types.

     In MySQL, the zero date is defined as ''0000-00-00'', even though
     this date is itself considered invalid.  This means that, for
     ''0000-00-00'' and ''0000-01-01'', 'TO_SECONDS()' returns the
     values shown here:

          mysql> SELECT TO_SECONDS('0000-00-00');
          +--------------------------+
          | TO_SECONDS('0000-00-00') |
          +--------------------------+
          |                     NULL |
          +--------------------------+
          1 row in set, 1 warning (0.00 sec)

          mysql> SHOW WARNINGS;
          +---------+------+----------------------------------------+
          | Level   | Code | Message                                |
          +---------+------+----------------------------------------+
          | Warning | 1292 | Incorrect datetime value: '0000-00-00' |
          +---------+------+----------------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT TO_SECONDS('0000-01-01');
          +--------------------------+
          | TO_SECONDS('0000-01-01') |
          +--------------------------+
          |                    86400 |
          +--------------------------+
          1 row in set (0.00 sec)

     This is true whether or not the 'ALLOW_INVALID_DATES' SQL server
     mode is enabled.

   *
     'UNIX_TIMESTAMP()', 'UNIX_TIMESTAMP(DATE)'

     If called with no argument, returns a Unix timestamp (seconds since
     ''1970-01-01 00:00:00'' UTC). The return value is an integer if no
     argument is given or the argument does not include a fractional
     seconds part, or 'DECIMAL' if an argument
     is given that includes a fractional seconds part.

     If 'UNIX_TIMESTAMP()' is called with a DATE argument, it returns
     the value of the argument as seconds since ''1970-01-01 00:00:00''
     UTC. The DATE argument may be a 'DATE',
     'DATETIME', or 'TIMESTAMP' string, or a
     number in 'YYMMDD', 'YYMMDDHHMMSS', 'YYYYMMDD', or 'YYYYMMDDHHMMSS'
     format.  If the argument includes a time part, it may optionally
     include a fractional seconds part.  The server interprets DATE as a
     value in the current time zone and converts it to an internal value
     in UTC. Clients can set their time zone as described in
     time-zone-support.

          mysql> SELECT UNIX_TIMESTAMP();
                  -> 1447431666
          mysql> SELECT UNIX_TIMESTAMP('2015-11-13 10:20:19');
                  -> 1447431619
          mysql> SELECT UNIX_TIMESTAMP('2015-11-13 10:20:19.012');
                  -> 1447431619.012

     When 'UNIX_TIMESTAMP()' is used on a 'TIMESTAMP'.
     column, the function returns the internal timestamp value directly,
     with no implicit 'string-to-Unix-timestamp' conversion.  If you
     pass an out-of-range date to 'UNIX_TIMESTAMP()', it returns '0'.
     The valid range of values is the same as for the 'TIMESTAMP'
     data type: ''1970-01-01 00:00:01.000000'' UTC to
     ''2038-01-19 03:14:07.999999'' UTC.

     Note: If you use 'UNIX_TIMESTAMP()' and 'FROM_UNIXTIME()' to
     convert between 'TIMESTAMP' values and Unix
     timestamp values, the conversion is lossy because the mapping is
     not one-to-one in both directions.  For example, due to conventions
     for local time zone changes, it is possible for two
     'UNIX_TIMESTAMP()' to map two 'TIMESTAMP' values
     to the same Unix timestamp value.  'FROM_UNIXTIME()' will map that
     value back to only one of the original 'TIMESTAMP'.
     values.  Here is an example, using 'TIMESTAMP'.
     values in the 'CET' time zone:

          mysql> SELECT UNIX_TIMESTAMP('2005-03-27 03:00:00');
          +---------------------------------------+
          | UNIX_TIMESTAMP('2005-03-27 03:00:00') |
          +---------------------------------------+
          |                            1111885200 |
          +---------------------------------------+
          mysql> SELECT UNIX_TIMESTAMP('2005-03-27 02:00:00');
          +---------------------------------------+
          | UNIX_TIMESTAMP('2005-03-27 02:00:00') |
          +---------------------------------------+
          |                            1111885200 |
          +---------------------------------------+
          mysql> SELECT FROM_UNIXTIME(1111885200);
          +---------------------------+
          | FROM_UNIXTIME(1111885200) |
          +---------------------------+
          | 2005-03-27 03:00:00       |
          +---------------------------+

     If you want to subtract 'UNIX_TIMESTAMP()' columns, you might want
     to cast the result to signed integers.  See cast-functions.

   *
     'UTC_DATE', 'UTC_DATE()'

     Returns the current UTC date as a value in ''YYYY-MM-DD'' or
     'YYYYMMDD' format, depending on whether the function is used in a
     string or numeric context.

          mysql> SELECT UTC_DATE(), UTC_DATE() + 0;
                  -> '2003-08-14', 20030814

   *
     'UTC_TIME', 'UTC_TIME([FSP])'

     Returns the current UTC time as a value in ''HH:MM:SS'' or 'HHMMSS'
     format, depending on whether the function is used in a string or
     numeric context.

     If the FSP argument is given to specify a fractional seconds
     precision from 0 to 6, the return value includes a fractional
     seconds part of that many digits.

          mysql> SELECT UTC_TIME(), UTC_TIME() + 0;
                  -> '18:07:53', 180753.000000

   *
     'UTC_TIMESTAMP', 'UTC_TIMESTAMP([FSP])'

     Returns the current UTC date and time as a value in ''YYYY-MM-DD
     HH:MM:SS'' or 'YYYYMMDDHHMMSS' format, depending on whether the
     function is used in a string or numeric context.

     If the FSP argument is given to specify a fractional seconds
     precision from 0 to 6, the return value includes a fractional
     seconds part of that many digits.

          mysql> SELECT UTC_TIMESTAMP(), UTC_TIMESTAMP() + 0;
                  -> '2003-08-14 18:08:04', 20030814180804.000000

   *
     'WEEK(DATE[,MODE])'

     This function returns the week number for DATE.  The two-argument
     form of 'WEEK()' enables you to specify whether the week starts on
     Sunday or Monday and whether the return value should be in the
     range from '0' to '53' or from '1' to '53'.  If the MODE argument
     is omitted, the value of the 'default_week_format' system variable
     is used.  See server-system-variables.

     The following table describes how the MODE argument works.

     Mode    First day of   Range          Week 1 is the first week ...
             week

     0       Sunday         0-53           with a Sunday in this year

     1       Monday         0-53           with 4 or more days this year

     2       Sunday         1-53           with a Sunday in this year

     3       Monday         1-53           with 4 or more days this year

     4       Sunday         0-53           with 4 or more days this year

     5       Monday         0-53           with a Monday in this year

     6       Sunday         1-53           with 4 or more days this year

     7       Monday         1-53           with a Monday in this year

     For MODE values with a meaning of 'with 4 or more days this year,'
     weeks are numbered according to ISO 8601:1988:

        * If the week containing January 1 has 4 or more days in the new
          year, it is week 1.

        * Otherwise, it is the last week of the previous year, and the
          next week is week 1.

          mysql> SELECT WEEK('2008-02-20');
                  -> 7
          mysql> SELECT WEEK('2008-02-20',0);
                  -> 7
          mysql> SELECT WEEK('2008-02-20',1);
                  -> 8
          mysql> SELECT WEEK('2008-12-31',1);
                  -> 53

     Note that if a date falls in the last week of the previous year,
     MySQL returns '0' if you do not use '2', '3', '6', or '7' as the
     optional MODE argument:

          mysql> SELECT YEAR('2000-01-01'), WEEK('2000-01-01',0);
                  -> 2000, 0

     One might argue that 'WEEK()' should return '52' because the given
     date actually occurs in the 52nd week of 1999.  'WEEK()' returns
     '0' instead so that the return value is 'the week number in the
     given year.' This makes use of the 'WEEK()' function reliable when
     combined with other functions that extract a date part from a date.

     If you prefer a result evaluated with respect to the year that
     contains the first day of the week for the given date, use '0',
     '2', '5', or '7' as the optional MODE argument.

          mysql> SELECT WEEK('2000-01-01',2);
                  -> 52

     Alternatively, use the 'YEARWEEK()' function:

          mysql> SELECT YEARWEEK('2000-01-01');
                  -> 199952
          mysql> SELECT MID(YEARWEEK('2000-01-01'),5,2);
                  -> '52'

   *
     'WEEKDAY(DATE)'

     Returns the weekday index for DATE ('0' = Monday, '1' = Tuesday,
     ... '6' = Sunday).

          mysql> SELECT WEEKDAY('2008-02-03 22:23:00');
                  -> 6
          mysql> SELECT WEEKDAY('2007-11-06');
                  -> 1

   *
     'WEEKOFYEAR(DATE)'

     Returns the calendar week of the date as a number in the range from
     '1' to '53'.  'WEEKOFYEAR()' is a compatibility function that is
     equivalent to 'WEEK(DATE,3)'.

          mysql> SELECT WEEKOFYEAR('2008-02-20');
                  -> 8

   *
     'YEAR(DATE)'

     Returns the year for DATE, in the range '1000' to '9999', or '0'
     for the 'zero' date.

          mysql> SELECT YEAR('1987-01-01');
                  -> 1987

   *
     'YEARWEEK(DATE)', 'YEARWEEK(DATE,MODE)'

     Returns year and week for a date.  The year in the result may be
     different from the year in the date argument for the first and the
     last week of the year.

     The MODE argument works exactly like the MODE argument to 'WEEK()'.
     For the single-argument syntax, a MODE value of 0 is used.  Unlike
     'WEEK()', the value of 'default_week_format' does not influence
     'YEARWEEK()'.

          mysql> SELECT YEARWEEK('1987-01-01');
                  -> 198652

     Note that the week number is different from what the 'WEEK()'
     function would return ('0') for optional arguments '0' or '1', as
     'WEEK()' then returns the week in the context of the given year.

12.8 What Calendar Is Used By MySQL?
====================================

MySQL uses what is known as a _proleptic Gregorian calendar_.

Every country that has switched from the Julian to the Gregorian
calendar has had to discard at least ten days during the switch.  To see
how this works, consider the month of October 1582, when the first
Julian-to-Gregorian switch occurred.

Monday     Tuesday    Wednesday  Thursday   Friday     Saturday   Sunday

1          2          3          4          15         16         17

18         19         20         21         22         23         24

25         26         27         28         29         30         31

There are no dates between October 4 and October 15.  This discontinuity
is called the _cutover_.  Any dates before the cutover are Julian, and
any dates following the cutover are Gregorian.  Dates during a cutover
are nonexistent.

A calendar applied to dates when it was not actually in use is called
_proleptic_.  Thus, if we assume there was never a cutover and Gregorian
rules always rule, we have a proleptic Gregorian calendar.  This is what
is used by MySQL, as is required by standard SQL. For this reason, dates
prior to the cutover stored as MySQL 'DATE' or
'DATETIME' values must be adjusted to compensate for the
difference.  It is important to realize that the cutover did not occur
at the same time in all countries, and that the later it happened, the
more days were lost.  For example, in Great Britain, it took place in
1752, when Wednesday September 2 was followed by Thursday September 14.
Russia remained on the Julian calendar until 1918, losing 13 days in the
process, and what is popularly referred to as its 'October Revolution'
occurred in November according to the Gregorian calendar.

12.9 Full-Text Search Functions
===============================

'MATCH (COL1,COL2,...) AGAINST (EXPR [SEARCH_MODIFIER])'

     SEARCH_MODIFIER:
       {
            IN NATURAL LANGUAGE MODE
          | IN NATURAL LANGUAGE MODE WITH QUERY EXPANSION
          | IN BOOLEAN MODE
          | WITH QUERY EXPANSION
       }

MySQL has support for full-text indexing and searching:

   * A full-text index in MySQL is an index of type 'FULLTEXT'.

   * Full-text indexes can be used only with 'InnoDB'
     or 'MyISAM'.
     tables, and can be created only for 'CHAR',
     'VARCHAR', or 'TEXT' columns.

   * As of MySQL 5.7.6, 'MySQL' provides a built-in full-text ngram
     parser that supports Chinese, Japanese, and Korean (CJK), and an
     installable MeCab full-text parser plugin for Japanese.  Parsing
     differences are outlined in fulltext-search-ngram, and
     fulltext-search-mecab.

   * A 'FULLTEXT' index definition can be given in the 'CREATE TABLE'
     statement when a table is created, or added
     later using 'ALTER TABLE' or 'CREATE INDEX'.

   * For large data sets, it is much faster to load your data into a
     table that has no 'FULLTEXT' index and then create the index after
     that, than to load data into a table that has an existing
     'FULLTEXT' index.

Full-text searching is performed using 'MATCH() ... AGAINST' syntax.
'MATCH()' takes a comma-separated list that names the columns to be
searched.  'AGAINST' takes a string to search for, and an optional
modifier that indicates what type of search to perform.  The search
string must be a string value that is constant during query evaluation.
This rules out, for example, a table column because that can differ for
each row.

There are three types of full-text searches:

   * A natural language search interprets the search string as a phrase
     in natural human language (a phrase in free text).  There are no
     special operators, with the exception of double quote (")
     characters.  The stopword list applies.  For more information about
     stopword lists, see fulltext-stopwords.

     Full-text searches are natural language searches if the 'IN NATURAL
     LANGUAGE MODE' modifier is given or if no modifier is given.  For
     more information, see fulltext-natural-language.

   * A boolean search interprets the search string using the rules of a
     special query language.  The string contains the words to search
     for.  It can also contain operators that specify requirements such
     that a word must be present or absent in matching rows, or that it
     should be weighted higher or lower than usual.  Certain common
     words (stopwords) are omitted from the search index and do not
     match if present in the search string.  The 'IN BOOLEAN MODE'
     modifier specifies a boolean search.  For more information, see
     fulltext-boolean.

   * A query expansion search is a modification of a natural language
     search.  The search string is used to perform a natural language
     search.  Then words from the most relevant rows returned by the
     search are added to the search string and the search is done again.
     The query returns the rows from the second search.  The 'IN NATURAL
     LANGUAGE MODE WITH QUERY EXPANSION' or 'WITH QUERY EXPANSION'
     modifier specifies a query expansion search.  For more information,
     see fulltext-query-expansion.

For information about 'FULLTEXT' query performance, see
column-indexes.

For more information about 'InnoDB' 'FULLTEXT' indexes, see
innodb-fulltext-index.

Constraints on full-text searching are listed in
fulltext-restrictions.

The 'myisam_ftdump' utility dumps the contents of
a 'MyISAM' full-text index.  This may be helpful for debugging full-text
queries.  See myisam-ftdump.

12.9.1 Natural Language Full-Text Searches
------------------------------------------

By default or with the 'IN NATURAL LANGUAGE MODE' modifier, the
'MATCH()' function performs a natural language search for a string
against a _text collection_.  A collection is a set of one or more
columns included in a 'FULLTEXT' index.  The search string is given as
the argument to 'AGAINST()'.  For each row in the table, 'MATCH()'
returns a relevance value; that is, a similarity measure between the
search string and the text in that row in the columns named in the
'MATCH()' list.

     mysql> CREATE TABLE articles (
               id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
               title VARCHAR(200),
               body TEXT,
               FULLTEXT (title,body)
             ) ENGINE=InnoDB;
     Query OK, 0 rows affected (0.08 sec)

     mysql> INSERT INTO articles (title,body) VALUES
             ('MySQL Tutorial','DBMS stands for DataBase ...'),
             ('How To Use MySQL Well','After you went through a ...'),
             ('Optimizing MySQL','In this tutorial we will show ...'),
             ('1001 MySQL Tricks','1. Never run mysqld as root. 2. ...'),
             ('MySQL vs. YourSQL','In the following database comparison ...'),
             ('MySQL Security','When configured properly, MySQL ...');
     Query OK, 6 rows affected (0.01 sec)
     Records: 6  Duplicates: 0  Warnings: 0

     mysql> SELECT * FROM articles
             WHERE MATCH (title,body)
             AGAINST ('database' IN NATURAL LANGUAGE MODE);
     +----+-------------------+------------------------------------------+
     | id | title             | body                                     |
     +----+-------------------+------------------------------------------+
     |  1 | MySQL Tutorial    | DBMS stands for DataBase ...             |
     |  5 | MySQL vs. YourSQL | In the following database comparison ... |
     +----+-------------------+------------------------------------------+
     2 rows in set (0.00 sec)

By default, the search is performed in case-insensitive fashion.  To
perform a case-sensitive full-text search, use a binary collation for
the indexed columns.  For example, a column that uses the 'latin1'
character set of can be assigned a collation of 'latin1_bin' to make it
case-sensitive for full-text searches.

When 'MATCH()' is used in a 'WHERE' clause, as in the example shown
earlier, the rows returned are automatically sorted with the highest
relevance first.  Relevance values are nonnegative floating-point
numbers.  Zero relevance means no similarity.  Relevance is computed
based on the number of words in the row (document), the number of unique
words in the row, the total number of words in the collection, and the
number of rows that contain a particular word.

*Note*:

The term 'document' may be used interchangeably with the term 'row', and
both terms refer to the indexed part of the row.  The term 'collection'
refers to the indexed columns and encompasses all rows.

To simply count matches, you could use a query like this:

     mysql> SELECT COUNT(*) FROM articles
         WHERE MATCH (title,body)
         AGAINST ('database' IN NATURAL LANGUAGE MODE);
     +----------+
     | COUNT(*) |
     +----------+
     |        2 |
     +----------+
     1 row in set (0.00 sec)

You might find it quicker to rewrite the query as follows:

     mysql> SELECT
         COUNT(IF(MATCH (title,body) AGAINST ('database' IN NATURAL LANGUAGE MODE), 1, NULL))
         AS count
         FROM articles;
     +-------+
     | count |
     +-------+
     |     2 |
     +-------+
     1 row in set (0.03 sec)

The first query does some extra work (sorting the results by relevance)
but also can use an index lookup based on the 'WHERE' clause.  The index
lookup might make the first query faster if the search matches few rows.
The second query performs a full table scan, which might be faster than
the index lookup if the search term was present in most rows.

For natural-language full-text searches, the columns named in the
'MATCH()' function must be the same columns included in some 'FULLTEXT'
index in your table.  For the preceding query, note that the columns
named in the 'MATCH()' function ('title' and 'body') are the same as
those named in the definition of the 'article' table's 'FULLTEXT' index.
To search the 'title' or 'body' separately, you would create separate
'FULLTEXT' indexes for each column.

You can also perform a boolean search or a search with query expansion.
These search types are described in fulltext-boolean, and
fulltext-query-expansion.

A full-text search that uses an index can name columns only from a
single table in the 'MATCH()' clause because an index cannot span
multiple tables.  For 'MyISAM' tables, a boolean search can be done in
the absence of an index (albeit more slowly), in which case it is
possible to name columns from multiple tables.

The preceding example is a basic illustration that shows how to use the
'MATCH()' function where rows are returned in order of decreasing
relevance.  The next example shows how to retrieve the relevance values
explicitly.  Returned rows are not ordered because the 'SELECT'
statement includes neither 'WHERE' nor 'ORDER BY' clauses:

     mysql> SELECT id, MATCH (title,body)
         AGAINST ('Tutorial' IN NATURAL LANGUAGE MODE) AS score
         FROM articles;
     +----+---------------------+
     | id | score               |
     +----+---------------------+
     |  1 | 0.22764469683170319 |
     |  2 |                   0 |
     |  3 | 0.22764469683170319 |
     |  4 |                   0 |
     |  5 |                   0 |
     |  6 |                   0 |
     +----+---------------------+
     6 rows in set (0.00 sec)

The following example is more complex.  The query returns the relevance
values and it also sorts the rows in order of decreasing relevance.  To
achieve this result, specify 'MATCH()' twice: once in the
'SELECT' list and once in the 'WHERE' clause.  This causes no
additional overhead, because the MySQL optimizer notices that the two
'MATCH()' calls are identical and invokes the full-text search code only
once.

     mysql> SELECT id, body, MATCH (title,body) AGAINST
         ('Security implications of running MySQL as root'
         IN NATURAL LANGUAGE MODE) AS score
         FROM articles WHERE MATCH (title,body) AGAINST
         ('Security implications of running MySQL as root'
         IN NATURAL LANGUAGE MODE);
     +----+-------------------------------------+-----------------+
     | id | body                                | score           |
     +----+-------------------------------------+-----------------+
     |  4 | 1. Never run mysqld as root. 2. ... | 1.5219271183014 |
     |  6 | When configured properly, MySQL ... | 1.3114095926285 |
     +----+-------------------------------------+-----------------+
     2 rows in set (0.00 sec)

A phrase that is enclosed within double quote ('"') characters matches
only rows that contain the phrase _literally, as it was typed_.  The
full-text engine splits the phrase into words and performs a search in
the 'FULLTEXT' index for the words.  Nonword characters need not be
matched exactly: Phrase searching requires only that matches contain
exactly the same words as the phrase and in the same order.  For
example, '"test phrase"' matches '"test, phrase"'.  If the phrase
contains no words that are in the index, the result is empty.  For
example, if all words are either stopwords or shorter than the minimum
length of indexed words, the result is empty.

The MySQL 'FULLTEXT' implementation regards any sequence of true word
characters (letters, digits, and underscores) as a word.  That sequence
may also contain apostrophes ('''), but not more than one in a row.
This means that 'aaa'bbb' is regarded as one word, but 'aaa''bbb' is
regarded as two words.  Apostrophes at the beginning or the end of a
word are stripped by the 'FULLTEXT' parser; ''aaa'bbb'' would be parsed
as 'aaa'bbb'.

The built-in 'FULLTEXT' parser determines where words start and end by
looking for certain delimiter characters; for example, ' ' (space), ','
(comma), and '.' (period).  If words are not separated by delimiters (as
in, for example, Chinese), the built-in 'FULLTEXT' parser cannot
determine where a word begins or ends.  To be able to add words or other
indexed terms in such languages to a 'FULLTEXT' index that uses the
built-in 'FULLTEXT' parser, you must preprocess them so that they are
separated by some arbitrary delimiter.  Alternatively, as of MySQL
5.7.6, you can create 'FULLTEXT' indexes using the ngram parser plugin
(for Chinese, Japanese, or Korean) or the MeCab parser plugin (for
Japanese).

It is possible to write a plugin that replaces the built-in full-text
parser.  For details, see plugin-api.  For example parser plugin
source code, see the 'plugin/fulltext' directory of a MySQL source
distribution.

Some words are ignored in full-text searches:

   * Any word that is too short is ignored.  The default minimum length
     of words that are found by full-text searches is three characters
     for 'InnoDB' search indexes, or four characters for 'MyISAM'.  You
     can control the cutoff by setting a configuration option before
     creating the index: 'innodb_ft_min_token_size' configuration option
     for 'InnoDB' search indexes, or 'ft_min_word_len' for 'MyISAM'.

     *Note*:

     This behavior does not apply to 'FULLTEXT' indexes that use the
     ngram parser.  For the ngram parser, token length is defined by the
     'ngram_token_size' option.

   * Words in the stopword list are ignored.  A stopword is a word such
     as 'the' or 'some' that is so common that it is considered to have
     zero semantic value.  There is a built-in stopword list, but it can
     be overridden by a user-defined list.  The stopword lists and
     related configuration options are different for 'InnoDB' search
     indexes and 'MyISAM' ones.  Stopword processing is controlled by
     the configuration options 'innodb_ft_enable_stopword',
     'innodb_ft_server_stopword_table', and
     'innodb_ft_user_stopword_table' for 'InnoDB' search indexes, and
     'ft_stopword_file' for 'MyISAM' ones.

See fulltext-stopwords to view default stopword lists and how to
change them.  The default minimum word length can be changed as
described in fulltext-fine-tuning.

Every correct word in the collection and in the query is weighted
according to its significance in the collection or query.  Thus, a word
that is present in many documents has a lower weight, because it has
lower semantic value in this particular collection.  Conversely, if the
word is rare, it receives a higher weight.  The weights of the words are
combined to compute the relevance of the row.  This technique works best
with large collections.

*MyISAM Limitation*:

For very small tables, word distribution does not adequately reflect
their semantic value, and this model may sometimes produce bizarre
results for search indexes on 'MyISAM' tables.  For example, although
the word 'MySQL' is present in every row of the 'articles' table shown
earlier, a search for the word in a 'MyISAM' search index produces no
results:

     mysql> SELECT * FROM articles
         WHERE MATCH (title,body)
         AGAINST ('MySQL' IN NATURAL LANGUAGE MODE);
     Empty set (0.00 sec)

The search result is empty because the word 'MySQL' is present in at
least 50% of the rows, and so is effectively treated as a stopword.
This filtering technique is more suitable for large data sets, where you
might not want the result set to return every second row from a 1GB
table, than for small data sets where it might cause poor results for
popular terms.

The 50% threshold can surprise you when you first try full-text
searching to see how it works, and makes 'InnoDB' tables more suited to
experimentation with full-text searches.  If you create a 'MyISAM' table
and insert only one or two rows of text into it, every word in the text
occurs in at least 50% of the rows.  As a result, no search returns any
results until the table contains more rows.  Users who need to bypass
the 50% limitation can build search indexes on 'InnoDB' tables, or use
the boolean search mode explained in fulltext-boolean.

12.9.2 Boolean Full-Text Searches
---------------------------------

MySQL can perform boolean full-text searches using the 'IN BOOLEAN MODE'
modifier.  With this modifier, certain characters have special meaning
at the beginning or end of words in the search string.  In the following
query, the '+' and '-' operators indicate that a word must be present or
absent, respectively, for a match to occur.  Thus, the query retrieves
all the rows that contain the word 'MySQL' but that do _not_ contain the
word 'YourSQL':

     mysql> SELECT * FROM articles WHERE MATCH (title,body)
         AGAINST ('+MySQL -YourSQL' IN BOOLEAN MODE);
     +----+-----------------------+-------------------------------------+
     | id | title                 | body                                |
     +----+-----------------------+-------------------------------------+
     |  1 | MySQL Tutorial        | DBMS stands for DataBase ...        |
     |  2 | How To Use MySQL Well | After you went through a ...        |
     |  3 | Optimizing MySQL      | In this tutorial we will show ...   |
     |  4 | 1001 MySQL Tricks     | 1. Never run mysqld as root. 2. ... |
     |  6 | MySQL Security        | When configured properly, MySQL ... |
     +----+-----------------------+-------------------------------------+

*Note*:

In implementing this feature, MySQL uses what is sometimes referred to
as _implied Boolean logic_, in which

   * '+' stands for 'AND'

   * '-' stands for 'NOT'

   * [_no operator_] implies 'OR'

Boolean full-text searches have these characteristics:

   * They do not automatically sort rows in order of decreasing
     relevance.

   * 'InnoDB' tables require a 'FULLTEXT' index on all columns of the
     'MATCH()' expression to perform boolean queries.  Boolean queries
     against a 'MyISAM' search index can work even without a 'FULLTEXT'
     index, although a search executed in this fashion would be quite
     slow.

   * The minimum and maximum word length full-text parameters apply to
     'FULLTEXT' indexes created using the built-in 'FULLTEXT' parser and
     MeCab parser plugin.  'innodb_ft_min_token_size' and
     'innodb_ft_max_token_size' are used for 'InnoDB' search indexes.
     'ft_min_word_len' and 'ft_max_word_len' are used for 'MyISAM'
     search indexes.

     Minimum and maximum word length full-text parameters do not apply
     to 'FULLTEXT' indexes created using the ngram parser.  ngram token
     size is defined by the 'ngram_token_size' option.

   * The stopword list applies, controlled by
     'innodb_ft_enable_stopword', 'innodb_ft_server_stopword_table', and
     'innodb_ft_user_stopword_table' for 'InnoDB' search indexes, and
     'ft_stopword_file' for 'MyISAM' ones.

   * 'InnoDB' full-text search does not support the use of multiple
     operators on a single search word, as in this example: ''++apple''.
     Use of multiple operators on a single search word returns a syntax
     error to standard out.  MyISAM full-text search will successfully
     process the same search ignoring all operators except for the
     operator immediately adjacent to the search word.

   * 'InnoDB' full-text search only supports leading plus or minus
     signs.  For example, 'InnoDB' supports ''+apple'' but does not
     support ''apple+''.  Specifying a trailing plus or minus sign
     causes 'InnoDB' to report a syntax error.

   * 'InnoDB' full-text search does not support the use of a leading
     plus sign with wildcard (''+*''), a plus and minus sign combination
     (''+-''), or leading a plus and minus sign combination
     (''+-apple'').  These invalid queries return a syntax error.

   * 'InnoDB' full-text search does not support the use of the '@'
     symbol in boolean full-text searches.  The '@' symbol is reserved
     for use by the '@distance' proximity search operator.

   * They do not use the 50% threshold that applies to 'MyISAM' search
     indexes.

The boolean full-text search capability supports the following
operators:

   * '+'

     A leading or trailing plus sign indicates that this word _must_ be
     present in each row that is returned.  'InnoDB' only supports
     leading plus signs.

   * '-'

     A leading or trailing minus sign indicates that this word must
     _not_ be present in any of the rows that are returned.  'InnoDB'
     only supports leading minus signs.

     Note: The '-' operator acts only to exclude rows that are otherwise
     matched by other search terms.  Thus, a boolean-mode search that
     contains only terms preceded by '-' returns an empty result.  It
     does not return 'all rows except those containing any of the
     excluded terms.'

   * (no operator)

     By default (when neither '+' nor '-' is specified), the word is
     optional, but the rows that contain it are rated higher.  This
     mimics the behavior of 'MATCH() ... AGAINST()' without the 'IN
     BOOLEAN MODE' modifier.

   * '@DISTANCE'

     This operator works on 'InnoDB' tables only.  It tests whether two
     or more words all start within a specified distance from each
     other, measured in words.  Specify the search words within a
     double-quoted string immediately before the '@DISTANCE' operator,
     for example, 'MATCH(col1) AGAINST('"word1 word2 word3" @8' IN
     BOOLEAN MODE)'

   * '> <'

     These two operators are used to change a word's contribution to the
     relevance value that is assigned to a row.  The '>' operator
     increases the contribution and the '<' operator decreases it.  See
     the example following this list.

   * '( )'

     Parentheses group words into subexpressions.  Parenthesized groups
     can be nested.

   * '~'

     A leading tilde acts as a negation operator, causing the word's
     contribution to the row's relevance to be negative.  This is useful
     for marking 'noise' words.  A row containing such a word is rated
     lower than others, but is not excluded altogether, as it would be
     with the '-' operator.

   * '*'

     The asterisk serves as the truncation (or wildcard) operator.
     Unlike the other operators, it is _appended_ to the word to be
     affected.  Words match if they begin with the word preceding the
     '*' operator.

     If a word is specified with the truncation operator, it is not
     stripped from a boolean query, even if it is too short or a
     stopword.  Whether a word is too short is determined from the
     'innodb_ft_min_token_size' setting for 'InnoDB' tables, or
     'ft_min_word_len' for 'MyISAM' tables.  These options are not
     applicable to 'FULLTEXT' indexes that use the ngram parser.

     The wildcarded word is considered as a prefix that must be present
     at the start of one or more words.  If the minimum word length is
     4, a search for ''+WORD +the*'' could return fewer rows than a
     search for ''+WORD +the'', because the second query ignores the
     too-short search term 'the'.

   * '"'

     A phrase that is enclosed within double quote ('"') characters
     matches only rows that contain the phrase _literally, as it was
     typed_.  The full-text engine splits the phrase into words and
     performs a search in the 'FULLTEXT' index for the words.  Nonword
     characters need not be matched exactly: Phrase searching requires
     only that matches contain exactly the same words as the phrase and
     in the same order.  For example, '"test phrase"' matches '"test,
     phrase"'.

     If the phrase contains no words that are in the index, the result
     is empty.  The words might not be in the index because of a
     combination of factors: if they do not exist in the text, are
     stopwords, or are shorter than the minimum length of indexed words.

The following examples demonstrate some search strings that use boolean
full-text operators:

   * ''apple banana''

     Find rows that contain at least one of the two words.

   * ''+apple +juice''

     Find rows that contain both words.

   * ''+apple macintosh''

     Find rows that contain the word 'apple', but rank rows higher if
     they also contain 'macintosh'.

   * ''+apple -macintosh''

     Find rows that contain the word 'apple' but not 'macintosh'.

   * ''+apple ~macintosh''

     Find rows that contain the word 'apple', but if the row also
     contains the word 'macintosh', rate it lower than if row does not.
     This is 'softer' than a search for ''+apple -macintosh'', for which
     the presence of 'macintosh' causes the row not to be returned at
     all.

   * ''+apple +(>turnover <strudel)''

     Find rows that contain the words 'apple' and 'turnover', or 'apple'
     and 'strudel' (in any order), but rank 'apple turnover' higher than
     'apple strudel'.

   * ''apple*''

     Find rows that contain words such as 'apple', 'apples',
     'applesauce', or 'applet'.

   * ''"some words"''

     Find rows that contain the exact phrase 'some words' (for example,
     rows that contain 'some words of wisdom' but not 'some noise
     words').  Note that the '"' characters that enclose the phrase are
     operator characters that delimit the phrase.  They are not the
     quotation marks that enclose the search string itself.

*Relevancy Rankings for InnoDB Boolean Mode Search*

'InnoDB' full-text search is modeled on
the Sphinx (http://sphinxsearch.com/) full-text search engine, and the
algorithms used are based on BM25
(http://en.wikipedia.org/wiki/Okapi_BM25) and TF-IDF
(http://en.wikipedia.org/wiki/TF-IDF) ranking algorithms.  For these
reasons, relevancy rankings for 'InnoDB' boolean full-text search may
differ from 'MyISAM' relevancy rankings.

'InnoDB' uses a variation of the 'term frequency-inverse document
frequency' ('TF-IDF') weighting system to rank a document's relevance
for a given full-text search query.  The 'TF-IDF' weighting is based on
how frequently a word appears in a document, offset by how frequently
the word appears in all documents in the collection.  In other words,
the more frequently a word appears in a document, and the less
frequently the word appears in the document collection, the higher the
document is ranked.

*How Relevancy Ranking is Calculated*

The term frequency ('TF') value is the number of times that a word
appears in a document.  The inverse document frequency ('IDF') value of
a word is calculated using the following formula, where 'total_records'
is the number of records in the collection, and 'matching_records' is
the number of records that the search term appears in.

     ${IDF} = log10( ${total_records} / ${matching_records} )

When a document contains a word multiple times, the IDF value is
multiplied by the TF value:

     ${TF} * ${IDF}

Using the 'TF' and 'IDF' values, the relevancy ranking for a document is
calculated using this formula:

     ${rank} = ${TF} * ${IDF} * ${IDF}

The formula is demonstrated in the following examples.

*Relevancy Ranking for a Single Word Search*

This example demonstrates the relevancy ranking calculation for a
single-word search.

     mysql> CREATE TABLE articles (
     id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
     title VARCHAR(200),
     body TEXT,
     FULLTEXT (title,body)
     ) ENGINE=InnoDB;
     Query OK, 0 rows affected (1.04 sec)

     mysql> INSERT INTO articles (title,body) VALUES
     ('MySQL Tutorial','This database tutorial ...'),
     ("How To Use MySQL",'After you went through a ...'),
     ('Optimizing Your Database','In this database tutorial ...'),
     ('MySQL vs. YourSQL','When comparing databases ...'),
     ('MySQL Security','When configured properly, MySQL ...'),
     ('Database, Database, Database','database database database'),
     ('1001 MySQL Tricks','1. Never run mysqld as root. 2. ...'),
     ('MySQL Full-Text Indexes', 'MySQL fulltext indexes use a ..');
     Query OK, 8 rows affected (0.06 sec)
     Records: 8  Duplicates: 0  Warnings: 0

     mysql> SELECT id, title, body, MATCH (title,body)  AGAINST ('database' IN BOOLEAN MODE)
     AS score FROM articles ORDER BY score DESC;
     +----+------------------------------+-------------------------------------+---------------------+
     | id | title                        | body                                | score               |
     +----+------------------------------+-------------------------------------+---------------------+
     |  6 | Database, Database, Database | database database database          |  1.0886961221694946 |
     |  3 | Optimizing Your Database     | In this database tutorial ...       | 0.36289870738983154 |
     |  1 | MySQL Tutorial               | This database tutorial ...          | 0.18144935369491577 |
     |  2 | How To Use MySQL             | After you went through a ...        |                   0 |
     |  4 | MySQL vs. YourSQL            | When comparing databases ...        |                   0 |
     |  5 | MySQL Security               | When configured properly, MySQL ... |                   0 |
     |  7 | 1001 MySQL Tricks            | 1. Never run mysqld as root. 2. ... |                   0 |
     |  8 | MySQL Full-Text Indexes      | MySQL fulltext indexes use a ..     |                   0 |
     +----+------------------------------+-------------------------------------+---------------------+
     8 rows in set (0.00 sec)

There are 8 records in total, with 3 that match the 'database' search
term.  The first record ('id 6') contains the search term 6 times and
has a relevancy ranking of '1.0886961221694946'.  This ranking value is
calculated using a 'TF' value of 6 (the 'database' search term appears 6
times in record 'id 6') and an 'IDF' value of 0.42596873216370745, which
is calculated as follows (where 8 is the total number of records and 3
is the number of records that the search term appears in):

     ${IDF} = log10( 8 / 3 ) = 0.42596873216370745

The 'TF' and 'IDF' values are then entered into the ranking formula:

     ${rank} = ${TF} * ${IDF} * ${IDF}

Performing the calculation in the MySQL command-line client returns a
ranking value of 1.088696164686938.

     mysql> SELECT 6*log10(8/3)*log10(8/3);
     +-------------------------+
     | 6*log10(8/3)*log10(8/3) |
     +-------------------------+
     |       1.088696164686938 |
     +-------------------------+
     1 row in set (0.00 sec)

*Note*:

You may notice a slight difference in the ranking values returned by the
'SELECT ... MATCH ... AGAINST' statement and the MySQL command-line
client ('1.0886961221694946' versus '1.088696164686938').  The
difference is due to how the casts between integers and floats/doubles
are performed internally by 'InnoDB' (along with related precision and
rounding decisions), and how they are performed elsewhere, such as in
the MySQL command-line client or other types of calculators.

*Relevancy Ranking for a Multiple Word Search*

This example demonstrates the relevancy ranking calculation for a
multiple-word full-text search based on the 'articles' table and data
used in the previous example.

If you search on more than one word, the relevancy ranking value is a
sum of the relevancy ranking value for each word, as shown in this
formula:

     ${rank} = ${TF} * ${IDF} * ${IDF} + ${TF} * ${IDF} * ${IDF}

Performing a search on two terms ('mysql tutorial') returns the
following results:

     mysql> SELECT id, title, body, MATCH (title,body)  AGAINST ('mysql tutorial' IN BOOLEAN MODE)
         AS score FROM articles ORDER BY score DESC;
     +----+------------------------------+-------------------------------------+----------------------+
     | id | title                        | body                                | score                |
     +----+------------------------------+-------------------------------------+----------------------+
     |  1 | MySQL Tutorial               | This database tutorial ...          |   0.7405621409416199 |
     |  3 | Optimizing Your Database     | In this database tutorial ...       |   0.3624762296676636 |
     |  5 | MySQL Security               | When configured properly, MySQL ... | 0.031219376251101494 |
     |  8 | MySQL Full-Text Indexes      | MySQL fulltext indexes use a ..     | 0.031219376251101494 |
     |  2 | How To Use MySQL             | After you went through a ...        | 0.015609688125550747 |
     |  4 | MySQL vs. YourSQL            | When comparing databases ...        | 0.015609688125550747 |
     |  7 | 1001 MySQL Tricks            | 1. Never run mysqld as root. 2. ... | 0.015609688125550747 |
     |  6 | Database, Database, Database | database database database          |                    0 |
     +----+------------------------------+-------------------------------------+----------------------+
     8 rows in set (0.00 sec)

In the first record ('id 8'), 'mysql' appears once and 'tutorial'
appears twice.  There are six matching records for 'mysql' and two
matching records for 'tutorial'.  The MySQL command-line client returns
the expected ranking value when inserting these values into the ranking
formula for a multiple word search:

     mysql> SELECT (1*log10(8/6)*log10(8/6)) + (2*log10(8/2)*log10(8/2));
     +-------------------------------------------------------+
     | (1*log10(8/6)*log10(8/6)) + (2*log10(8/2)*log10(8/2)) |
     +-------------------------------------------------------+
     |                                    0.7405621541938003 |
     +-------------------------------------------------------+
     1 row in set (0.00 sec)

*Note*:

The slight difference in the ranking values returned by the 'SELECT ...
MATCH ... AGAINST' statement and the MySQL command-line client is
explained in the preceding example.

12.9.3 Full-Text Searches with Query Expansion
----------------------------------------------

Full-text search supports query expansion (and in particular, its
variant 'blind query expansion').  This is generally useful when a
search phrase is too short, which often means that the user is relying
on implied knowledge that the full-text search engine lacks.  For
example, a user searching for 'database' may really mean that 'MySQL',
'Oracle', 'DB2', and 'RDBMS' all are phrases that should match
'databases' and should be returned, too.  This is implied knowledge.

Blind query expansion (also known as automatic relevance feedback) is
enabled by adding 'WITH QUERY EXPANSION' or 'IN NATURAL LANGUAGE MODE
WITH QUERY EXPANSION' following the search phrase.  It works by
performing the search twice, where the search phrase for the second
search is the original search phrase concatenated with the few most
highly relevant documents from the first search.  Thus, if one of these
documents contains the word 'databases' and the word 'MySQL', the second
search finds the documents that contain the word 'MySQL' even if they do
not contain the word 'database'.  The following example shows this
difference:

     mysql> SELECT * FROM articles
         WHERE MATCH (title,body)
         AGAINST ('database' IN NATURAL LANGUAGE MODE);
     +----+-------------------+------------------------------------------+
     | id | title             | body                                     |
     +----+-------------------+------------------------------------------+
     |  1 | MySQL Tutorial    | DBMS stands for DataBase ...             |
     |  5 | MySQL vs. YourSQL | In the following database comparison ... |
     +----+-------------------+------------------------------------------+
     2 rows in set (0.00 sec)

     mysql> SELECT * FROM articles
         WHERE MATCH (title,body)
         AGAINST ('database' WITH QUERY EXPANSION);
     +----+-----------------------+------------------------------------------+
     | id | title                 | body                                     |
     +----+-----------------------+------------------------------------------+
     |  5 | MySQL vs. YourSQL     | In the following database comparison ... |
     |  1 | MySQL Tutorial        | DBMS stands for DataBase ...             |
     |  3 | Optimizing MySQL      | In this tutorial we will show ...        |
     |  6 | MySQL Security        | When configured properly, MySQL ...      |
     |  2 | How To Use MySQL Well | After you went through a ...             |
     |  4 | 1001 MySQL Tricks     | 1. Never run mysqld as root. 2. ...      |
     +----+-----------------------+------------------------------------------+
     6 rows in set (0.00 sec)

Another example could be searching for books by Georges Simenon about
Maigret, when a user is not sure how to spell 'Maigret'.  A search for
'Megre and the reluctant witnesses' finds only 'Maigret and the
Reluctant Witnesses' without query expansion.  A search with query
expansion finds all books with the word 'Maigret' on the second pass.

*Note*:

Because blind query expansion tends to increase noise significantly by
returning nonrelevant documents, use it only when a search phrase is
short.

12.9.4 Full-Text Stopwords
--------------------------

The stopword list is loaded and searched for full-text queries using the
server character set and collation (the values of the
'character_set_server' and 'collation_server' system variables).  False
hits or misses might occur for stopword lookups if the stopword file or
columns used for full-text indexing or searches have a character set or
collation different from 'character_set_server' or 'collation_server'.

Case sensitivity of stopword lookups depends on the server collation.
For example, lookups are case insensitive if the collation is
'latin1_swedish_ci', whereas lookups are case-sensitive if the collation
is 'latin1_general_cs' or 'latin1_bin'.

   * fulltext-stopwords-stopwords-for-innodb-search-indexes

   * fulltext-stopwords-stopwords-for-myisam-search-indexes

*Stopwords for InnoDB Search Indexes*

'InnoDB' has a relatively short list of default stopwords, because
documents from technical, literary, and other sources often use short
words as keywords or in significant phrases.  For example, you might
search for 'to be or not to be' and expect to get a sensible result,
rather than having all those words ignored.

To see the default 'InnoDB' stopword list, query the
'INFORMATION_SCHEMA.INNODB_FT_DEFAULT_STOPWORD'
table.

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_DEFAULT_STOPWORD;
     +-------+
     | value |
     +-------+
     | a     |
     | about |
     | an    |
     | are   |
     | as    |
     | at    |
     | be    |
     | by    |
     | com   |
     | de    |
     | en    |
     | for   |
     | from  |
     | how   |
     | i     |
     | in    |
     | is    |
     | it    |
     | la    |
     | of    |
     | on    |
     | or    |
     | that  |
     | the   |
     | this  |
     | to    |
     | was   |
     | what  |
     | when  |
     | where |
     | who   |
     | will  |
     | with  |
     | und   |
     | the   |
     | www   |
     +-------+
     36 rows in set (0.00 sec)

To define your own stopword list for all 'InnoDB' tables, define a table
with the same structure as the 'INNODB_FT_DEFAULT_STOPWORD'
table, populate it with stopwords, and
set the value of the 'innodb_ft_server_stopword_table' option to a value
in the form 'DB_NAME/TABLE_NAME' before creating the full-text index.
The stopword table must have a single 'VARCHAR' column
named 'value'.  The following example demonstrates creating and
configuring a new global stopword table for 'InnoDB'.

     -- Create a new stopword table

     mysql> CREATE TABLE my_stopwords(value VARCHAR(30)) ENGINE = INNODB;
     Query OK, 0 rows affected (0.01 sec)

     -- Insert stopwords (for simplicity, a single stopword is used in this example)

     mysql> INSERT INTO my_stopwords(value) VALUES ('Ishmael');
     Query OK, 1 row affected (0.00 sec)

     -- Create the table

     mysql> CREATE TABLE opening_lines (
     id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
     opening_line TEXT(500),
     author VARCHAR(200),
     title VARCHAR(200)
     ) ENGINE=InnoDB;
     Query OK, 0 rows affected (0.01 sec)

     -- Insert data into the table

     mysql> INSERT INTO opening_lines(opening_line,author,title) VALUES
     ('Call me Ishmael.','Herman Melville','Moby-Dick'),
     ('A screaming comes across the sky.','Thomas Pynchon','Gravity\'s Rainbow'),
     ('I am an invisible man.','Ralph Ellison','Invisible Man'),
     ('Where now? Who now? When now?','Samuel Beckett','The Unnamable'),
     ('It was love at first sight.','Joseph Heller','Catch-22'),
     ('All this happened, more or less.','Kurt Vonnegut','Slaughterhouse-Five'),
     ('Mrs. Dalloway said she would buy the flowers herself.','Virginia Woolf','Mrs. Dalloway'),
     ('It was a pleasure to burn.','Ray Bradbury','Fahrenheit 451');
     Query OK, 8 rows affected (0.00 sec)
     Records: 8  Duplicates: 0  Warnings: 0

     -- Set the innodb_ft_server_stopword_table option to the new stopword table

     mysql> SET GLOBAL innodb_ft_server_stopword_table = 'test/my_stopwords';
     Query OK, 0 rows affected (0.00 sec)

     -- Create the full-text index (which rebuilds the table if no FTS_DOC_ID column is defined)

     mysql> CREATE FULLTEXT INDEX idx ON opening_lines(opening_line);
     Query OK, 0 rows affected, 1 warning (1.17 sec)
     Records: 0  Duplicates: 0  Warnings: 1

Verify that the specified stopword ('Ishmael') does not appear by
querying the words in 'INFORMATION_SCHEMA.INNODB_FT_INDEX_TABLE'.

*Note*:

By default, words less than 3 characters in length or greater than 84
characters in length do not appear in an 'InnoDB' full-text search
index.  Maximum and minimum word length values are configurable using
the 'innodb_ft_max_token_size' and 'innodb_ft_min_token_size' variables.
This default behavior does not apply to the ngram parser plugin.  ngram
token size is defined by the 'ngram_token_size' option.

     mysql> SET GLOBAL innodb_ft_aux_table='test/opening_lines';
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT word FROM INFORMATION_SCHEMA.INNODB_FT_INDEX_TABLE LIMIT 15;
     +-----------+
     | word      |
     +-----------+
     | across    |
     | all       |
     | burn      |
     | buy       |
     | call      |
     | comes     |
     | dalloway  |
     | first     |
     | flowers   |
     | happened  |
     | herself   |
     | invisible |
     | less      |
     | love      |
     | man       |
     +-----------+
     15 rows in set (0.00 sec)

To create stopword lists on a table-by-table basis, create other
stopword tables and use the 'innodb_ft_user_stopword_table' option to
specify the stopword table that you want to use before you create the
full-text index.

*Stopwords for MyISAM Search Indexes*

The stopword file is loaded and searched using 'latin1' if
'character_set_server' is 'ucs2', 'utf16', 'utf16le', or 'utf32'.

To override the default stopword list for MyISAM tables, set the
'ft_stopword_file' system variable.  (See
server-system-variables.)  The variable value should be the path name
of the file containing the stopword list, or the empty string to disable
stopword filtering.  The server looks for the file in the data directory
unless an absolute path name is given to specify a different directory.
After changing the value of this variable or the contents of the
stopword file, restart the server and rebuild your 'FULLTEXT' indexes.

The stopword list is free-form, separating stopwords with any
nonalphanumeric character such as newline, space, or comma.  Exceptions
are the underscore character ('_') and a single apostrophe (''') which
are treated as part of a word.  The character set of the stopword list
is the server's default character set; see charset-server.

The following list shows the default stopwords for 'MyISAM' search
indexes.  In a MySQL source distribution, you can find this list in the
'storage/myisam/ft_static.c' file.

     a's           able          about         above         according
     accordingly   across        actually      after         afterwards
     again         against       ain't         all           allow
     allows        almost        alone         along         already
     also          although      always        am            among
     amongst       an            and           another       any
     anybody       anyhow        anyone        anything      anyway
     anyways       anywhere      apart         appear        appreciate
     appropriate   are           aren't        around        as
     aside         ask           asking        associated    at
     available     away          awfully       be            became
     because       become        becomes       becoming      been
     before        beforehand    behind        being         believe
     below         beside        besides       best          better
     between       beyond        both          brief         but
     by            c'mon         c's           came          can
     can't         cannot        cant          cause         causes
     certain       certainly     changes       clearly       co
     com           come          comes         concerning    consequently
     consider      considering   contain       containing    contains
     corresponding could         couldn't      course        currently
     definitely    described     despite       did           didn't
     different     do            does          doesn't       doing
     don't         done          down          downwards     during
     each          edu           eg            eight         either
     else          elsewhere     enough        entirely      especially
     et            etc           even          ever          every
     everybody     everyone      everything    everywhere    ex
     exactly       example       except        far           few
     fifth         first         five          followed      following
     follows       for           former        formerly      forth
     four          from          further       furthermore   get
     gets          getting       given         gives         go
     goes          going         gone          got           gotten
     greetings     had           hadn't        happens       hardly
     has           hasn't        have          haven't       having
     he            he's          hello         help          hence
     her           here          here's        hereafter     hereby
     herein        hereupon      hers          herself       hi
     him           himself       his           hither        hopefully
     how           howbeit       however       i'd           i'll
     i'm           i've          ie            if            ignored
     immediate     in            inasmuch      inc           indeed
     indicate      indicated     indicates     inner         insofar
     instead       into          inward        is            isn't
     it            it'd          it'll         it's          its
     itself        just          keep          keeps         kept
     know          known         knows         last          lately
     later         latter        latterly      least         less
     lest          let           let's         like          liked
     likely        little        look          looking       looks
     ltd           mainly        many          may           maybe
     me            mean          meanwhile     merely        might
     more          moreover      most          mostly        much
     must          my            myself        name          namely
     nd            near          nearly        necessary     need
     needs         neither       never         nevertheless  new
     next          nine          no            nobody        non
     none          noone         nor           normally      not
     nothing       novel         now           nowhere       obviously
     of            off           often         oh            ok
     okay          old           on            once          one
     ones          only          onto          or            other
     others        otherwise     ought         our           ours
     ourselves     out           outside       over          overall
     own           particular    particularly  per           perhaps
     placed        please        plus          possible      presumably
     probably      provides      que           quite         qv
     rather        rd            re            really        reasonably
     regarding     regardless    regards       relatively    respectively
     right         said          same          saw           say
     saying        says          second        secondly      see
     seeing        seem          seemed        seeming       seems
     seen          self          selves        sensible      sent
     serious       seriously     seven         several       shall
     she           should        shouldn't     since         six
     so            some          somebody      somehow       someone
     something     sometime      sometimes     somewhat      somewhere
     soon          sorry         specified     specify       specifying
     still         sub           such          sup           sure
     t's           take          taken         tell          tends
     th            than          thank         thanks        thanx
     that          that's        thats         the           their
     theirs        them          themselves    then          thence
     there         there's       thereafter    thereby       therefore
     therein       theres        thereupon     these         they
     they'd        they'll       they're       they've       think
     third         this          thorough      thoroughly    those
     though        three         through       throughout    thru
     thus          to            together      too           took
     toward        towards       tried         tries         truly
     try           trying        twice         two           un
     under         unfortunately unless        unlikely      until
     unto          up            upon          us            use
     used          useful        uses          using         usually
     value         various       very          via           viz
     vs            want          wants         was           wasn't
     way           we            we'd          we'll         we're
     we've         welcome       well          went          were
     weren't       what          what's        whatever      when
     whence        whenever      where         where's       whereafter
     whereas       whereby       wherein       whereupon     wherever
     whether       which         while         whither       who
     who's         whoever       whole         whom          whose
     why           will          willing       wish          with
     within        without       won't         wonder        would
     wouldn't      yes           yet           you           you'd
     you'll        you're        you've        your          yours
     yourself      yourselves    zero

12.9.5 Full-Text Restrictions
-----------------------------

   * Full-text searches are supported for 'InnoDB'
     and 'MyISAM'.
     tables only.

   * Full-text searches are not supported for partitioned tables.  See
     partitioning-limitations.

   * Full-text searches can be used with most multibyte character sets.
     The exception is that for Unicode, the 'utf8' character set can be
     used, but not the 'ucs2' character set.  Although 'FULLTEXT'
     indexes on 'ucs2' columns cannot be used, you can perform 'IN
     BOOLEAN MODE' searches on a 'ucs2' column that has no such index.

     The remarks for 'utf8' also apply to 'utf8mb4', and the remarks for
     'ucs2' also apply to 'utf16', 'utf16le', and 'utf32'.

   * Ideographic languages such as Chinese and Japanese do not have word
     delimiters.  Therefore, the built-in full-text parser _cannot
     determine where words begin and end in these and other such
     languages_.

     In MySQL 5.7.6, a character-based ngram full-text parser that
     supports Chinese, Japanese, and Korean (CJK), and a word-based
     MeCab parser plugin that supports Japanese are provided for use
     with 'InnoDB' and 'MySIAM' tables.

   * Although the use of multiple character sets within a single table
     is supported, all columns in a 'FULLTEXT' index must use the same
     character set and collation.

   * The 'MATCH()' column list must match exactly the column list in
     some 'FULLTEXT' index definition for the table, unless this
     'MATCH()' is 'IN BOOLEAN MODE' on a 'MyISAM' table.  For 'MyISAM'
     tables, boolean-mode searches can be done on nonindexed columns,
     although they are likely to be slow.

   * The argument to 'AGAINST()' must be a string value that is constant
     during query evaluation.  This rules out, for example, a table
     column because that can differ for each row.

   * Index hints are more limited for 'FULLTEXT' searches than for
     non-'FULLTEXT' searches.  See index-hints.

   * For 'InnoDB', all DML operations (see 'INSERT',
     'UPDATE', 'DELETE') involving columns with
     full-text indexes are processed at transaction commit time.  For
     example, for an 'INSERT' operation, an inserted string is tokenized
     and decomposed into individual words.  The individual words are
     then added to full-text index tables when the transaction is
     committed.  As a result, full-text searches only return committed
     data.

   * The '%' character is not a supported wildcard character for
     full-text searches.

12.9.6 Fine-Tuning MySQL Full-Text Search
-----------------------------------------

MySQL's full-text search capability has few user-tunable parameters.
You can exert more control over full-text searching behavior if you have
a MySQL source distribution because some changes require source code
modifications.  See source-installation.

Full-text search is carefully tuned for effectiveness.  Modifying the
default behavior in most cases can actually decrease effectiveness.  _Do
not alter the MySQL sources unless you know what you are doing_.

Most full-text variables described in this section must be set at server
startup time.  A server restart is required to change them; they cannot
be modified while the server is running.

Some variable changes require that you rebuild the 'FULLTEXT' indexes in
your tables.  Instructions for doing so are given later in this section.

   * fulltext-word-length

   * fulltext-natural-language-threshold

   * fulltext-modify-boolean-operators

   * fulltext-modify-character-set

   * fulltext-rebuild-innodb-indexes

   * fulltext-optimize

   * fulltext-rebuild-myisam-indexes

*Configuring Minimum and Maximum Word Length*

The minimum and maximum lengths of words to be indexed are defined by
the 'innodb_ft_min_token_size' and 'innodb_ft_max_token_size' for
'InnoDB' search indexes, and 'ft_min_word_len' and 'ft_max_word_len' for
'MyISAM' ones.

*Note*:

Minimum and maximum word length full-text parameters do not apply to
'FULLTEXT' indexes created using the ngram parser.  ngram token size is
defined by the 'ngram_token_size' option.

After changing any of these options, rebuild your 'FULLTEXT' indexes for
the change to take effect.  For example, to make two-character words
searchable, you could put the following lines in an option file:

     [mysqld]
     innodb_ft_min_token_size=2
     ft_min_word_len=2

Then restart the server and rebuild your 'FULLTEXT' indexes.  For
'MyISAM' tables, note the remarks regarding 'myisamchk'
in the instructions that follow for rebuilding 'MyISAM'
full-text indexes.

*Configuring the Natural Language Search Threshold*

For 'MyISAM' search indexes, the 50% threshold for natural language
searches is determined by the particular weighting scheme chosen.  To
disable it, look for the following line in 'storage/myisam/ftdefs.h':

     #define GWS_IN_USE GWS_PROB

Change that line to this:

     #define GWS_IN_USE GWS_FREQ

Then recompile MySQL. There is no need to rebuild the indexes in this
case.

*Note*:

By making this change, you _severely_ decrease MySQL's ability to
provide adequate relevance values for the 'MATCH()' function.  If you
really need to search for such common words, it would be better to
search using 'IN BOOLEAN MODE' instead, which does not observe the 50%
threshold.

*Modifying Boolean Full-Text Search Operators*

To change the operators used for boolean full-text searches on 'MyISAM'
tables, set the 'ft_boolean_syntax' system variable.  ('InnoDB' does not
have an equivalent setting.)  This variable can be changed while the
server is running, but you must have the 'SUPER' privilege to do so.  No
rebuilding of indexes is necessary in this case.  See
server-system-variables, which describes the rules governing how to
set this variable.

*Character Set Modifications*

For the built-in full-text parser, you can change the set of characters
that are considered word characters in several ways, as described in the
following list.  After making the modification, rebuild the indexes for
each table that contains any 'FULLTEXT' indexes.  Suppose that you want
to treat the hyphen character ('-') as a word character.  Use one of
these methods:

   * Modify the MySQL source: In 'storage/innobase/handler/ha_innodb.cc'
     (for 'InnoDB'), or in 'storage/myisam/ftdefs.h' (for 'MyISAM'), see
     the 'true_word_char()' and 'misc_word_char()' macros.  Add ''-'' to
     one of those macros and recompile MySQL.

   * Modify a character set file: This requires no recompilation.  The
     'true_word_char()' macro uses a 'character type' table to
     distinguish letters and numbers from other characters.  .  You can
     edit the contents of the '<ctype><map>' array in one of the
     character set XML files to specify that ''-'' is a 'letter.' Then
     use the given character set for your 'FULLTEXT' indexes.  For
     information about the '<ctype><map>' array format, see
     character-arrays.

   * Add a new collation for the character set used by the indexed
     columns, and alter the columns to use that collation.  For general
     information about adding collations, see adding-collation.
     For an example specific to full-text indexing, see
     full-text-adding-collation.

*Rebuilding InnoDB Full-Text Indexes*

If you modify full-text variables that affect indexing
('innodb_ft_min_token_size', 'innodb_ft_max_token_size',
'innodb_ft_server_stopword_table', 'innodb_ft_user_stopword_table',
'innodb_ft_enable_stopword', 'ngram_token_size' you must rebuild your
'FULLTEXT' indexes after making the changes.  Modifying the
'innodb_ft_min_token_size', 'innodb_ft_max_token_size', or
'ngram_token_size' variables, which cannot be set dynamically, require
restarting the server and rebuilding the indexes.

To rebuild the 'FULLTEXT' indexes for an 'InnoDB' table, use
'ALTER TABLE' with the 'DROP INDEX' and 'ADD INDEX'
options to drop and re-create each index.

*Optimizing InnoDB Full-Text Indexes*

Running 'OPTIMIZE TABLE' on a table with a
full-text index rebuilds the full-text index, removing deleted Document
IDs and consolidating multiple entries for the same word, where
possible.

To optimize a full-text index, enable 'innodb_optimize_fulltext_only'
and run 'OPTIMIZE TABLE'.

     mysql> set GLOBAL innodb_optimize_fulltext_only=ON;
     Query OK, 0 rows affected (0.01 sec)

     mysql> OPTIMIZE TABLE opening_lines;
     +--------------------+----------+----------+----------+
     | Table              | Op       | Msg_type | Msg_text |
     +--------------------+----------+----------+----------+
     | test.opening_lines | optimize | status   | OK       |
     +--------------------+----------+----------+----------+
     1 row in set (0.01 sec)

To avoid lengthy rebuild times for full-text indexes on large tables,
you can use the 'innodb_ft_num_word_optimize' option to perform the
optimization in stages.  The 'innodb_ft_num_word_optimize' option
defines the number of words that are optimized each time 'OPTIMIZE TABLE'
is run.  The default setting is 2000, which
means that 2000 words are optimized each time 'OPTIMIZE TABLE'
is run.  Subsequent 'OPTIMIZE TABLE'
operations continue from where the preceding
'OPTIMIZE TABLE' operation ended.

*Rebuilding MyISAM Full-Text Indexes*

If you modify full-text variables that affect indexing
('ft_min_word_len', 'ft_max_word_len', or 'ft_stopword_file'), or if you
change the stopword file itself, you must rebuild your 'FULLTEXT'
indexes after making the changes and restarting the server.

To rebuild the 'FULLTEXT' indexes for a 'MyISAM' table, it is sufficient
to do a 'QUICK' repair operation:

     mysql> REPAIR TABLE TBL_NAME QUICK;

Alternatively, use 'ALTER TABLE' as just described.
In some cases, this may be faster than a repair operation.

Each table that contains any 'FULLTEXT' index must be repaired as just
shown.  Otherwise, queries for the table may yield incorrect results,
and modifications to the table will cause the server to see the table as
corrupt and in need of repair.

If you use 'myisamchk' to perform an operation that
modifies 'MyISAM ' table indexes (such as repair or analyze), the
'FULLTEXT' indexes are rebuilt using the _default_ full-text parameter
values for minimum word length, maximum word length, and stopword file
unless you specify otherwise.  This can result in queries failing.

The problem occurs because these parameters are known only by the
server.  They are not stored in 'MyISAM' index files.  To avoid the
problem if you have modified the minimum or maximum word length or
stopword file values used by the server, specify the same
'ft_min_word_len', 'ft_max_word_len', and 'ft_stopword_file' values for
'myisamchk' that you use for 'mysqld'.
For example, if you have set the minimum word length to 3, you can
repair a table with 'myisamchk' like this:

     myisamchk --recover --ft_min_word_len=3 TBL_NAME.MYI

To ensure that 'myisamchk' and the server use the same
values for full-text parameters, place each one in both the '[mysqld]'
and '[myisamchk]' sections of an option file:

     [mysqld]
     ft_min_word_len=3

     [myisamchk]
     ft_min_word_len=3

An alternative to using 'myisamchk' for 'MyISAM' table
index modification is to use the 'REPAIR TABLE',
'ANALYZE TABLE', 'OPTIMIZE TABLE',
or 'ALTER TABLE' statements.  These
statements are performed by the server, which knows the proper full-text
parameter values to use.

12.9.7 Adding a Collation for Full-Text Indexing
------------------------------------------------

This section describes how to add a new collation for full-text searches
using the built-in full-text parser.  The sample collation is like
'latin1_swedish_ci' but treats the ''-'' character as a letter rather
than as a punctuation character so that it can be indexed as a word
character.  General information about adding collations is given in
adding-collation; it is assumed that you have read it and are
familiar with the files involved.

To add a collation for full-text indexing, use the following procedure.
The instructions here add a collation for a simple character set, which
as discussed in adding-collation, can be created using a
configuration file that describes the character set properties.  For a
complex character set such as Unicode, create collations using C source
files that describe the character set properties.

  1. Add a collation to the 'Index.xml' file.  The collation ID must be
     unused, so choose a value different from 1000 if that ID is already
     taken on your system.

          <charset name="latin1">
          ...
          <collation name="latin1_fulltext_ci" id="1000"/>
          </charset>

  2. Declare the sort order for the collation in the 'latin1.xml' file.
     In this case, the order can be copied from 'latin1_swedish_ci':

          <collation name="latin1_fulltext_ci">
          <map>
          00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
          20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
          30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
          40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
          50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
          60 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
          50 51 52 53 54 55 56 57 58 59 5A 7B 7C 7D 7E 7F
          80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F
          90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
          A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF
          B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF
          41 41 41 41 5C 5B 5C 43 45 45 45 45 49 49 49 49
          44 4E 4F 4F 4F 4F 5D D7 D8 55 55 55 59 59 DE DF
          41 41 41 41 5C 5B 5C 43 45 45 45 45 49 49 49 49
          44 4E 4F 4F 4F 4F 5D F7 D8 55 55 55 59 59 DE FF
          </map>
          </collation>

  3. Modify the 'ctype' array in 'latin1.xml'.  Change the value
     corresponding to 0x2D (which is the code for the ''-'' character)
     from 10 (punctuation) to 01 (small letter).  In the following
     array, this is the element in the fourth row down, third value from
     the end.

          <ctype>
          <map>
          00
          20 20 20 20 20 20 20 20 20 28 28 28 28 28 20 20
          20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
          48 10 10 10 10 10 10 10 10 10 10 10 10 *01* 10 10
          84 84 84 84 84 84 84 84 84 84 10 10 10 10 10 10
          10 81 81 81 81 81 81 01 01 01 01 01 01 01 01 01
          01 01 01 01 01 01 01 01 01 01 01 10 10 10 10 10
          10 82 82 82 82 82 82 02 02 02 02 02 02 02 02 02
          02 02 02 02 02 02 02 02 02 02 02 10 10 10 10 20
          10 00 10 02 10 10 10 10 10 10 01 10 01 00 01 00
          00 10 10 10 10 10 10 10 10 10 02 10 02 00 02 01
          48 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10
          10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10
          01 01 01 01 01 01 01 01 01 01 01 01 01 01 01 01
          01 01 01 01 01 01 01 10 01 01 01 01 01 01 01 02
          02 02 02 02 02 02 02 02 02 02 02 02 02 02 02 02
          02 02 02 02 02 02 02 10 02 02 02 02 02 02 02 02
          </map>
          </ctype>

  4. Restart the server.

  5. To employ the new collation, include it in the definition of
     columns that are to use it:

          mysql> DROP TABLE IF EXISTS t1;
          Query OK, 0 rows affected (0.13 sec)

          mysql> CREATE TABLE t1 (
              a TEXT CHARACTER SET latin1 COLLATE latin1_fulltext_ci,
              FULLTEXT INDEX(a)
              ) ENGINE=InnoDB;
          Query OK, 0 rows affected (0.47 sec)

  6. Test the collation to verify that hyphen is considered as a word
     character:

          mysql> INSERT INTO t1 VALUEs ('----'),('....'),('abcd');
          Query OK, 3 rows affected (0.22 sec)
          Records: 3  Duplicates: 0  Warnings: 0

          mysql> SELECT * FROM t1 WHERE MATCH a AGAINST ('----' IN BOOLEAN MODE);
          +------+
          | a    |
          +------+
          | ---- |
          +------+
          1 row in set (0.00 sec)

12.9.8 ngram Full-Text Parser
-----------------------------

The built-in MySQL full-text parser uses the white space between words
as a delimiter to determine where words begin and end, which is a
limitation when working with ideographic languages that do not use word
delimiters.  To address this limitation, MySQL provides an ngram
full-text parser that supports Chinese, Japanese, and Korean (CJK). The
ngram full-text parser is supported for use with 'InnoDB'
and 'MyISAM'.

*Note*:

MySQL also provides a MeCab full-text parser plugin for Japanese, which
tokenizes documents into meaningful words.  For more information, see
fulltext-search-mecab.

An ngram is a contiguous sequence of N characters from a given sequence
of text.  The ngram parser tokenizes a sequence of text into a
contiguous sequence of N characters.  For example, you can tokenize
'abcd' for different values of N using the ngram full-text parser.

     n=1: 'a', 'b', 'c', 'd'
     n=2: 'ab', 'bc', 'cd'
     n=3: 'abc', 'bcd'
     n=4: 'abcd'

The ngram full-text parser, introduced in MySQL 5.7.6, is a built-in
server plugin.  As with other built-in server plugins, it is
automatically loaded when the server is started.

The full-text search syntax described in fulltext-search applies
to the ngram parser plugin.  Differences in parsing behavior are
described in this section.  Full-text-related configuration options,
except for minimum and maximum word length options
('innodb_ft_min_token_size', 'innodb_ft_max_token_size',
'ft_min_word_len', 'ft_max_word_len') are also applicable.

*Configuring ngram Token Size*

The ngram parser has a default ngram token size of 2 (bigram).  For
example, with a token size of 2, the ngram parser parses the string 'abc
def' into four tokens: 'ab', 'bc', 'de' and 'ef'.

ngram token size is configurable using the 'ngram_token_size'
configuration option, which has a minimum value of 1 and maximum value
of 10.

Typically, 'ngram_token_size' is set to the size of the largest token
that you want to search for.  If you only intend to search for single
characters, set 'ngram_token_size' to 1.  A smaller token size produces
a smaller full-text search index, and faster searches.  If you need to
search for words comprised of more than one character, set
'ngram_token_size' accordingly.  For example, 'Happy Birthday' is
'生日快乐' in simplified Chinese, where '生日' is 'birthday', and
'快乐' translates as 'happy'.  To search on two-character words such
as these, set 'ngram_token_size' to a value of 2 or higher.

As a read-only variable, 'ngram_token_size' may only be set as part of a
startup string or in a configuration file:

   * Startup string:

          mysqld --ngram_token_size=2

   * Configuration file:

          [mysqld]
          ngram_token_size=2

*Note*:

The following minimum and maximum word length configuration options are
ignored for 'FULLTEXT' indexes that use the ngram parser:
'innodb_ft_min_token_size', 'innodb_ft_max_token_size',
'ft_min_word_len', and 'ft_max_word_len'.

*Creating a FULLTEXT Index that Uses the ngram Parser*

To create a 'FULLTEXT' index that uses the ngram parser, specify 'WITH
PARSER ngram' with 'CREATE TABLE', 'ALTER TABLE',
or 'CREATE INDEX'.

The following example demonstrates creating a table with an 'ngram'
'FULLTEXT' index, inserting sample data (Simplified Chinese text), and
viewing tokenized data in the
'INFORMATION_SCHEMA.INNODB_FT_INDEX_CACHE'.
table.

     mysql> USE test;

     mysql> CREATE TABLE articles (
           id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
           title VARCHAR(200),
           body TEXT,
           FULLTEXT (title,body) WITH PARSER ngram
         ) ENGINE=InnoDB CHARACTER SET utf8mb4;

     mysql> SET NAMES utf8mb4;

     INSERT INTO articles (title,body) VALUES
         ('数据库管理','在本教程中我将向你展示如何管理数据库'),
         ('数据库应用开发','学习开发数据库应用程序');

     mysql> SET GLOBAL innodb_ft_aux_table="test/articles";

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_INDEX_CACHE ORDER BY doc_id, position;

To add a 'FULLTEXT' index to an existing table, you can use 'ALTER TABLE'
or 'CREATE INDEX'.  For
example:

     CREATE TABLE articles (
           id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
           title VARCHAR(200),
           body TEXT
          ) ENGINE=InnoDB CHARACTER SET utf8;

     ALTER TABLE articles ADD FULLTEXT INDEX ft_index (title,body) WITH PARSER ngram;

     # Or:

     CREATE FULLTEXT INDEX ft_index ON articles (title,body) WITH PARSER ngram;

*ngram Parser Space Handling*

The ngram parser eliminates spaces when parsing.  For example:

   * 'ab cd' is parsed to 'ab', 'cd'

   * 'a bc' is parsed to 'bc'

*ngram Parser Stopword Handling*

The built-in MySQL full-text parser compares words to entries in the
stopword list.  If a word is equal to an entry in the stopword list, the
word is excluded from the index.  For the ngram parser, stopword
handling is performed differently.  Instead of excluding tokens that are
equal to entries in the stopword list, the ngram parser excludes tokens
that _contain_ stopwords.  For example, assuming 'ngram_token_size=2', a
document that contains 'a,b' is parsed to 'a,' and ',b'.  If a comma
(',') is defined as a stopword, both 'a,' and ',b' are excluded from the
index because they contain a comma.

By default, the ngram parser uses the default stopword list, which
contains a list of English stopwords.  For a stopword list applicable to
Chinese, Japanese, or Korean, you must create your own.  For information
about creating a stopword list, see fulltext-stopwords.

Stopwords greater in length than 'ngram_token_size' are ignored.

*ngram Parser Term Search*

For _natural language mode_ search, the search term is converted to a
union of ngram terms.  For example, the string 'abc' (assuming
'ngram_token_size=2') is converted to 'ab bc'.  Given two documents, one
containing 'ab' and the other containing 'abc', the search term 'ab bc'
matches both documents.

For _boolean mode search_, the search term is converted to an ngram
phrase search.  For example, the string 'abc' (assuming
'ngram_token_size=2') is converted to ''ab bc''.  Given two documents,
one containing 'ab' and the other containing 'abc', the search phrase
''ab bc'' only matches the document containing 'abc'.

*ngram Parser Wildcard Search*

Because an ngram 'FULLTEXT' index contains only ngrams, and does not
contain information about the beginning of terms, wildcard searches may
return unexpected results.  The following behaviors apply to wildcard
searches using ngram 'FULLTEXT' search indexes:

   * If the prefix term of a wildcard search is shorter than ngram token
     size, the query returns all indexed rows that contain ngram tokens
     starting with the prefix term.  For example, assuming
     'ngram_token_size=2', a search on 'a*' returns all rows starting
     with 'a'.

   * If the prefix term of a wildcard search is longer than ngram token
     size, the prefix term is converted to an ngram phrase and the
     wildcard operator is ignored.  For example, assuming
     'ngram_token_size=2', an 'abc*' wildcard search is converted to 'ab
     bc'.

*ngram Parser Phrase Search*

Phrase searches are converted to ngram phrase searches.  For example,
The search phrase 'abc' is converted to 'ab bc', which returns documents
containing 'abc' and 'ab bc'.

The search phrase 'abc def' is converted to 'ab bc de ef', which returns
documents containing 'abc def' and 'ab bc de ef'.  A document that
contains 'abcdef' is not returned.

12.9.9 MeCab Full-Text Parser Plugin
------------------------------------

The built-in MySQL full-text parser uses the white space between words
as a delimiter to determine where words begin and end, which is a
limitation when working with ideographic languages that do not use word
delimiters.  To address this limitation for Japanese, MySQL provides a
MeCab full-text parser plugin.  The MeCab full-text parser plugin is
supported for use with 'InnoDB' and
'MyISAM'.

*Note*:

MySQL also provides an ngram full-text parser plugin that supports
Japanese.  For more information, see fulltext-search-ngram.

The MeCab full-text parser plugin, introduced in MySQL 5.7.6, is a
full-text parser plugin for Japanese that tokenizes a sequence of text
into meaningful words.  For example, MeCab tokenizes
'データベース管理' ('Database Management') into
'データベース' ('Database') and '管理' ('Management').  By
comparison, the ngram full-text parser
tokenizes text into a contiguous sequence of N characters, where N
represents a number between 1 and 10.

In addition to tokenizing text into meaningful words, MeCab indexes are
typically smaller than ngram indexes, and MeCab full-text searches are
generally faster.  One drawback is that it may take longer for the MeCab
full-text parser to tokenize documents, compared to the ngram full-text
parser.

The full-text search syntax described in fulltext-search applies
to the MeCab parser plugin.  Differences in parsing behavior are
described in this section.  Full-text related configuration options are
also applicable.

For additional information about the MeCab parser, refer to the MeCab:
Yet Another Part-of-Speech and Morphological Analyzer
(http://taku910.github.io/mecab/) project on Github.

*Installing the MeCab Parser Plugin*

The MeCab parser plugin requires 'mecab' and 'mecab-ipadic'.

On supported Fedora, Debian and Ubuntu platforms (except Ubuntu 12.04
where the system 'mecab' version is too old), MySQL dynamically links to
the system 'mecab' installation if it is installed to the default
location.  On other supported Unix-like platforms, 'libmecab.so' is
statically linked in 'libpluginmecab.so', which is located in the MySQL
plugin directory.  'mecab-ipadic' is included in MySQL binaries and is
located in 'MYSQL_HOME\lib\mecab'.

You can install 'mecab' and 'mecab-ipadic' using a native package
management utility (on Fedora, Debian, and Ubuntu), or you can build
'mecab' and 'mecab-ipadic' from source.  For information about
installing 'mecab' and 'mecab-ipadic' using a native package management
utility, see Installing MeCab From a Binary Distribution (Optional).  If
you want to build 'mecab' and 'mecab-ipadic' from source, see Building
MeCab From Source (Optional).

On Windows, 'libmecab.dll' is found in the MySQL 'bin' directory.
'mecab-ipadic' is located in 'MYSQL_HOME/lib/mecab'.

To install and configure the MeCab parser plugin, perform the following
steps:

  1. In the MySQL configuration file, set the 'mecab_rc_file'
     configuration option to the location of the 'mecabrc' configuration
     file, which is the configuration file for MeCab.  If you are using
     the MeCab package distributed with MySQL, the 'mecabrc' file is
     located in 'MYSQL_HOME/lib/mecab/etc/'.

          [mysqld]
          loose-mecab-rc-file=MYSQL_HOME/lib/mecab/etc/mecabrc

     The 'loose' prefix is an option modifier.
     The 'mecab_rc_file' option is not recognized by MySQL until the
     MeCaB parser plugin is installed but it must be set before
     attempting to install the MeCaB parser plugin.  The 'loose' prefix
     allows you restart MySQL without encountering an error due to an
     unrecognized variable.

     If you use your own MeCab installation, or build MeCab from source,
     the location of the 'mecabrc' configuration file may differ.

     For information about the MySQL configuration file and its
     location, see option-files.

  2. Also in the MySQL configuration file, set the minimum token size to
     1 or 2, which are the values recommended for use with the MeCab
     parser.  For 'InnoDB' tables, minimum token size is defined by the
     'innodb_ft_min_token_size' configuration option, which has a
     default value of 3.  For 'MyISAM' tables, minimum token size is
     defined by 'ft_min_word_len', which has a default value of 4.

          [mysqld]
          innodb_ft_min_token_size=1

  3. Modify the 'mecabrc' configuration file to specify the dictionary
     you want to use.  The 'mecab-ipadic' package distributed with MySQL
     binaries includes three dictionaries ('ipadic_euc-jp',
     'ipadic_sjis', and 'ipadic_utf-8').  The 'mecabrc' configuration
     file packaged with MySQL contains and entry similar to the
     following:

          dicdir =  /path/to/mysql/lib/mecab/lib/mecab/dic/ipadic_euc-jp

     To use the 'ipadic_utf-8' dictionary, for example, modify the entry
     as follows:

          dicdir=MYSQL_HOME/lib/mecab/dic/ipadic_utf-8

     If you are using your own MeCab installation or have built MeCab
     from source, the default 'dicdir' entry in the 'mecabrc' file will
     differ, as will the dictionaries and their location.

     *Note*:

     After the MeCab parser plugin is installed, you can use the
     'mecab_charset' status variable to view the character set used with
     MeCab.  The three MeCab dictionaries provided with the MySQL binary
     support the following character sets.

        * The 'ipadic_euc-jp' dictionary supports the 'ujis' and
          'eucjpms' character sets.

        * The 'ipadic_sjis' dictionary supports the 'sjis' and 'cp932'
          character sets.

        * The 'ipadic_utf-8' dictionary supports the 'utf8' and
          'utf8mb4' character sets.

     'mecab_charset' only reports the first supported character set.
     For example, the 'ipadic_utf-8' dictionary supports both 'utf8' and
     'utf8mb4'.  'mecab_charset' always reports 'utf8' when this
     dictionary is in use.

  4. Restart MySQL.

  5. Install the MeCab parser plugin:

     The MeCab parser plugin is installed using 'INSTALL PLUGIN'
     syntax.  The plugin name is 'mecab', and the shared
     library name is 'libpluginmecab.so'.  For additional information
     about installing plugins, see server-plugin-loading.

          INSTALL PLUGIN mecab SONAME 'libpluginmecab.so';

     Once installed, the MeCab parser plugin loads at every normal MySQL
     restart.

  6. Verify that the MeCab parser plugin is loaded using the 'SHOW PLUGINS'
     statement.

          mysql> SHOW PLUGINS;

     A 'mecab' plugin should appear in the list of plugins.

*Creating a FULLTEXT Index that uses the MeCab Parser*

To create a 'FULLTEXT' index that uses the mecab parser, specify 'WITH
PARSER ngram' with 'CREATE TABLE', 'ALTER TABLE',
or 'CREATE INDEX'.

This example demonstrates creating a table with a 'mecab' 'FULLTEXT'
index, inserting sample data, and viewing tokenized data in the
'INFORMATION_SCHEMA.INNODB_FT_INDEX_CACHE'.
table:

     mysql> USE test;

     mysql> CREATE TABLE articles (
           id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
           title VARCHAR(200),
           body TEXT,
           FULLTEXT (title,body) WITH PARSER mecab
         ) ENGINE=InnoDB CHARACTER SET utf8;

     mysql> SET NAMES utf8;

     mysql> INSERT INTO articles (title,body) VALUES
         ('データベース管理','このチュートリアルでは、私はどのようにデータベースを管理する方法を紹介します'),
         ('データベースアプリケーション開発','データベースアプリケーションを開発することを学ぶ');

     mysql> SET GLOBAL innodb_ft_aux_table="test/articles";

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_INDEX_CACHE ORDER BY doc_id, position;

To add a 'FULLTEXT' index to an existing table, you can use 'ALTER TABLE'
or 'CREATE INDEX'.  For
example:

     CREATE TABLE articles (
           id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
           title VARCHAR(200),
           body TEXT
          ) ENGINE=InnoDB CHARACTER SET utf8;

     ALTER TABLE articles ADD FULLTEXT INDEX ft_index (title,body) WITH PARSER mecab;

     # Or:

     CREATE FULLTEXT INDEX ft_index ON articles (title,body) WITH PARSER mecab;

*MeCab Parser Space Handling*

The MeCab parser uses spaces as separators in query strings.  For
example, the MeCab parser tokenizes データベース管理 as
データベース and 管理.

*MeCab Parser Stopword Handling*

By default, the MeCab parser uses the default stopword list, which
contains a short list of English stopwords.  For a stopword list
applicable to Japanese, you must create your own.  For information about
creating stopword lists, see fulltext-stopwords.

*MeCab Parser Term Search*

For natural language mode search, the search term is converted to a
union of tokens.  For example, データベース管理 is converted to
データベース 管理.

     SELECT COUNT(*) FROM articles WHERE MATCH(title,body) AGAINST('データベース管理' IN NATURAL LANGUAGE MODE);

For boolean mode search, the search term is converted to a search
phrase.  For example, データベース管理 is converted to
データベース 管理.

     SELECT COUNT(*) FROM articles WHERE MATCH(title,body) AGAINST('データベース管理' IN BOOLEAN MODE);

*MeCab Parser Wildcard Search*

Wildcard search terms are not tokenized.  A search on
データベース管理* is performed on the prefix,
データベース管理.

     SELECT COUNT(*) FROM articles WHERE MATCH(title,body) AGAINST('データベース*' IN BOOLEAN MODE);

*MeCab Parser Phrase Search*

Phrases are tokenized.  For example, データベース管理 is
tokenized as データベース 管理.

     SELECT COUNT(*) FROM articles WHERE MATCH(title,body) AGAINST('"データベース管理"' IN BOOLEAN MODE);

*Installing MeCab From a Binary Distribution (Optional)*

This section describes how to install 'mecab' and 'mecab-ipadic' from a
binary distribution using a native package management utility.  For
example, on Fedora, you can use Yum to perform the installation:

     yum mecab-devel

On Debian or Ubuntu, you can perform an APT installation:

     apt-get install mecab
     apt-get install mecab-ipadic

*Installing MeCab From Source (Optional)*

If you want to build 'mecab' and 'mecab-ipadic' from source, basic
installation steps are provided below.  For additional information,
refer to the MeCab documentation.

  1. Download the tar.gz packages for 'mecab' and 'mecab-ipadic' from
     <http://taku910.github.io/mecab/#download>.  As of February, 2016,
     the latest available packages are 'mecab-0.996.tar.gz' and
     'mecab-ipadic-2.7.0-20070801.tar.gz'.

  2. Install 'mecab':

          tar zxfv mecab-0.996.tar
          cd mecab-0.996
          ./configure
          make
          make check
          su
          make install

  3. Install 'mecab-ipadic':

          tar zxfv mecab-ipadic-2.7.0-20070801.tar
          cd mecab-ipadic-2.7.0-20070801
          ./configure
          make
          su
          make install

  4. Compile MySQL using the 'WITH_MECAB' CMake option.  Set the
     'WITH_MECAB' option to 'system' if you have installed 'mecab' and
     'mecab-ipadic' to the default location.

          -DWITH_MECAB=system

     If you defined a custom installation directory, set 'WITH_MECAB' to
     the custom directory.  For example:

          -DWITH_MECAB=/path/to/mecab

12.10 Cast Functions and Operators
==================================

*Cast Functions and Operators*

Name                          Description

'BINARY'                      Cast a string to a binary string

'CAST()'                      Cast a value as a certain type

'CONVERT()'                   Cast a value as a certain type

Cast functions and operators enable conversion of values from one data
type to another.

'CONVERT()' with a 'USING' clause provides a way to convert data between
different character sets:

     CONVERT(EXPR USING TRANSCODING_NAME)

In MySQL, transcoding names are the same as the corresponding character
set names.

Examples:

     SELECT CONVERT(_latin1'Mu"ller' USING utf8);
     INSERT INTO utf8_table (utf8_column)
         SELECT CONVERT(latin1_column USING utf8) FROM latin1_table;

You can also use 'CONVERT()' without 'USING' or 'CAST()' to convert
strings between different character sets:

     CONVERT(STRING, CHAR[(N)] CHARACTER SET CHARSET_NAME)
     CAST(STRING AS CHAR[(N)] CHARACTER SET CHARSET_NAME)

Examples:

     SELECT CONVERT('test', CHAR CHARACTER SET utf8);
     SELECT CAST('test' AS CHAR CHARACTER SET utf8);

If you specify 'CHARACTER SET CHARSET_NAME' as just shown, the resulting
character set and collation are CHARSET_NAME and the default collation
of CHARSET_NAME.  If you omit 'CHARACTER SET CHARSET_NAME', the
resulting character set and collation are defined by the
'character_set_connection' and 'collation_connection' system variables
that determine the default connection character set and collation (see
charset-connection).

A 'COLLATE' clause is not permitted within a 'CONVERT()' or 'CAST()'
call, but you can apply it to the function result.  For example, this is
legal:

     SELECT CAST('test' AS CHAR CHARACTER SET utf8) COLLATE utf8_bin;

But this is illegal:

     SELECT CAST('test' AS CHAR CHARACTER SET utf8 COLLATE utf8_bin);

Normally, you cannot compare a 'BLOB' value or other binary
string in case-insensitive fashion because binary strings use the
'binary' character set, which has no collation with the concept of
lettercase.  To perform a case-insensitive comparison, use the
'CONVERT()' or 'CAST()' function to convert the value to a nonbinary
string.  Comparisons of the resulting string use its collation.  For
example, if the conversion result character set has a case-insensitive
collation, a 'LIKE' operation is not case-sensitive:

     SELECT 'A' LIKE CONVERT(BLOB_COL USING latin1)
       FROM TBL_NAME;

To use a different character set, substitute its name for 'latin1' in
the preceding statement.  To specify a particular collation for the
converted string, use a 'COLLATE' clause following the 'CONVERT()' call:

     SELECT 'A' LIKE CONVERT(BLOB_COL USING latin1) COLLATE latin1_german1_ci
       FROM TBL_NAME;

'CONVERT()' and 'CAST()' can be used more generally for comparing
strings that are represented in different character sets.  For example,
a comparison of these strings results in an error because they have
different character sets:

     mysql> SET @s1 = _latin1 'abc', @s2 = _latin2 'abc';
     mysql> SELECT @s1 = @s2;
     ERROR 1267 (HY000): Illegal mix of collations (latin1_swedish_ci,IMPLICIT)
     and (latin2_general_ci,IMPLICIT) for operation '='

Converting one of the strings to a character set compatible with the
other enables the comparison to occur without error:

     mysql> SELECT @s1 = CONVERT(@s2 USING latin1);
     +---------------------------------+
     | @s1 = CONVERT(@s2 USING latin1) |
     +---------------------------------+
     |                               1 |
     +---------------------------------+

For string literals, another way to specify the character set is to use
a character set introducer ('_latin1' and '_latin2' in the preceding
example are instances of introducers).  Unlike conversion functions such
as 'CAST()', or 'CONVERT()', which convert a string from one character
set to another, an introducer designates a string literal as having a
particular character set, with no conversion involved.  For more
information, see charset-introducer.

Character set conversion is also useful preceding lettercase conversion
of binary strings.  'LOWER()' and 'UPPER()' are ineffective when applied
directly to binary strings because the concept of lettercase does not
apply.  To perform lettercase conversion of a binary string, first
convert it to a nonbinary string:

     mysql> SET @str = BINARY 'New York';
     mysql> SELECT LOWER(@str), LOWER(CONVERT(@str USING latin1));
     +-------------+-----------------------------------+
     | LOWER(@str) | LOWER(CONVERT(@str USING latin1)) |
     +-------------+-----------------------------------+
     | New York    | new york                          |
     +-------------+-----------------------------------+

If you convert an indexed column using 'BINARY', 'CAST()', or
'CONVERT()', MySQL may not be able to use the index efficiently.

The cast functions are useful for creating a column with a specific type
in a 'CREATE TABLE ... SELECT' statement:

     mysql> CREATE TABLE new_table SELECT CAST('2000-01-01' AS DATE) AS c1;
     mysql> SHOW CREATE TABLE new_table\G
     *************************** 1. row ***************************
            Table: new_table
     Create Table: CREATE TABLE `new_table` (
       `c1` date DEFAULT NULL
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1

The cast functions are useful for sorting 'ENUM' columns in
lexical order.  Normally, sorting of 'ENUM' columns occurs
using the internal numeric values.  Casting the values to 'CHAR'
results in a lexical sort:

     SELECT ENUM_COL FROM TBL_NAME ORDER BY CAST(ENUM_COL AS CHAR);

'CAST()' also changes the result if you use it as part of a more complex
expression such as 'CONCAT('Date: ',CAST(NOW() AS DATE))'.

For temporal values, there is little need to use 'CAST()' to extract
data in different formats.  Instead, use a function such as 'EXTRACT()',
'DATE_FORMAT()', or 'TIME_FORMAT()'.  See
date-and-time-functions.

To cast a string to a number, you normally need do nothing other than
use the string value in numeric context:

     mysql> SELECT 1+'1';
            -> 2

That is also true for hexadecimal and bit literals, which are binary
strings by default:

     mysql> SELECT X'41', X'41'+0;
             -> 'A', 65
     mysql> SELECT b'1100001', b'1100001'+0;
             -> 'a', 97

A string used in an arithmetic operation is converted to a
floating-point number during expression evaluation.

A number used in string context is converted to a string:

     mysql> SELECT CONCAT('hello you ',2);
             -> 'hello you 2'

For information about implicit conversion of numbers to strings, see
type-conversion.

MySQL supports arithmetic with both signed and unsigned 64-bit values.
For numeric operators (such as '+' or '-') where one of the operands is
an unsigned integer, the result is unsigned by default (see
arithmetic-functions).  To override this, use the 'SIGNED' or
'UNSIGNED' cast operator to cast a value to a signed or unsigned 64-bit
integer, respectively.

     mysql> SELECT 1 - 2;
             -> -1
     mysql> SELECT CAST(1 - 2 AS UNSIGNED);
             -> 18446744073709551615
     mysql> SELECT CAST(CAST(1 - 2 AS UNSIGNED) AS SIGNED);
             -> -1

If either operand is a floating-point value, the result is a
floating-point value and is not affected by the preceding rule.  (In
this context, see 'DECIMAL' column values are
regarded as floating-point values.)

     mysql> SELECT CAST(1 AS UNSIGNED) - 2.0;
             -> -1.0

The SQL mode affects the result of conversion operations (see
sql-mode).  Examples:

   * For conversion of a 'zero' date string to a date, 'CONVERT()' and
     'CAST()' return 'NULL' and produce a warning when the
     'NO_ZERO_DATE' SQL mode is enabled.

   * For integer subtraction, if the 'NO_UNSIGNED_SUBTRACTION' SQL mode
     is enabled, the subtraction result is signed even if any operand is
     unsigned.

The following list describes the available cast functions and operators:

   *
     'BINARY' EXPR

     The 'BINARY' operator converts the expression to a binary string.
     A common use for 'BINARY' is to force a character string comparison
     to be done byte by byte rather than character by character, in
     effect becoming case-sensitive.  The 'BINARY' operator also causes
     trailing spaces in comparisons to be significant.

          mysql> SELECT 'a' = 'A';
                  -> 1
          mysql> SELECT BINARY 'a' = 'A';
                  -> 0
          mysql> SELECT 'a' = 'a ';
                  -> 1
          mysql> SELECT BINARY 'a' = 'a ';
                  -> 0

     In a comparison, 'BINARY' affects the entire operation; it can be
     given before either operand with the same result.

     For purposes of converting a string expression to a binary string,
     these constructs are equivalent:

          BINARY EXPR
          CAST(EXPR AS BINARY)
          CONVERT(EXPR USING BINARY)

     If a value is a string literal, it can be designated as a binary
     string without performing any conversion by using the '_binary'
     character set introducer:

          mysql> SELECT 'a' = 'A';
                  -> 1
          mysql> SELECT _binary 'a' = 'A';
                  -> 0

     For information about introducers, see charset-introducer.

     The 'BINARY' operator in expressions differs in effect from the
     'BINARY' attribute in character column definitions.  A character
     column defined with the 'BINARY' attribute is assigned table
     default character set and the binary ('_bin') collation of that
     character set.  Every nonbinary character set has a '_bin'
     collation.  For example, the binary collation for the 'utf8'
     character set is 'utf8_bin', so if the table default character set
     is 'utf8', these two column definitions are equivalent:

          CHAR(10) BINARY
          CHAR(10) CHARACTER SET utf8 COLLATE utf8_bin

     The use of 'CHARACTER SET binary' in the definition of a
     'CHAR', 'VARCHAR', or 'TEXT' column
     causes the column to be treated as the corresponding binary string
     data type.  For example, the following pairs of definitions are
     equivalent:

          CHAR(10) CHARACTER SET binary
          BINARY(10)

          VARCHAR(10) CHARACTER SET binary
          VARBINARY(10)

          TEXT CHARACTER SET binary
          BLOB

   *
     'CAST(EXPR AS TYPE)'

     The 'CAST()' function takes an expression of any type and produces
     a result value of the specified type, similar to 'CONVERT()'.  For
     more information, see the description of 'CONVERT()'.

     'CAST()' is standard SQL syntax.

   *
     'CONVERT(EXPR,TYPE)', 'CONVERT(EXPR USING TRANSCODING_NAME)'

     The 'CONVERT()' function takes an expression of any type and
     produces a result value of the specified type.

     Discussion of 'CONVERT(EXPR, TYPE)' syntax here also applies to
     'CAST(EXPR AS TYPE)', which is equivalent.

     'CONVERT(... USING ...)' is standard SQL syntax.  The non-'USING'
     form of 'CONVERT()' is ODBC syntax.

     'CONVERT()' with 'USING' converts data between different character
     sets.  In MySQL, transcoding names are the same as the
     corresponding character set names.  For example, this statement
     converts the string ''abc'' in the default character set to the
     corresponding string in the 'utf8' character set:

          SELECT CONVERT('abc' USING utf8);

     'CONVERT()' without 'USING' and 'CAST()' take an expression and a
     TYPE value specifying the result type.  These TYPE values are
     permitted:

        * 'BINARY[(N)]'

          Produces a string with the 'BINARY'.
          data type.  See binary-varbinary for a description of
          how this affects comparisons.  If the optional length N is
          given, 'BINARY(N)' causes the cast to use no more than N bytes
          of the argument.  Values shorter than N bytes are padded with
          '0x00' bytes to a length of N.

        * 'CHAR[(N)] [CHARSET_INFO]'

          Produces a string with the 'CHAR' data type.  If
          the optional length N is given, 'CHAR(N)' causes the cast to
          use no more than N characters of the argument.  No padding
          occurs for values shorter than N characters.

          With no CHARSET_INFO clause, 'CHAR' produces a string with the
          default character set.  To specify the character set
          explicitly, these CHARSET_INFO values are permitted:

             * 'CHARACTER SET CHARSET_NAME': Produces a string with the
               given character set.

             * 'ASCII': Shorthand for 'CHARACTER SET latin1'.

             * 'UNICODE': Shorthand for 'CHARACTER SET ucs2'.

          In all cases, the string has the default collation for the
          character set.

        * 'DATE'

          Produces a 'DATE' value.

        * 'DATETIME'

          Produces a 'DATETIME' value.

        * 'DECIMAL[(M[,D])]'

          Produces a 'DECIMAL' value.  If the
          optional M and D values are given, they specify the maximum
          number of digits (the precision) and the number of digits
          following the decimal point (the scale).

        * 'JSON' (added in MySQL 5.7.8)

          Produces a 'JSON' value.  For details on the
          rules for conversion of values between 'JSON' and
          other types, see json-comparison.

        * 'NCHAR[(N)]'

          Like 'CHAR', but produces a string with the national character
          set.  See charset-national.

          Unlike 'CHAR', 'NCHAR' does not permit trailing character set
          information to be specified.

        * 'SIGNED [INTEGER]'

          Produces a signed integer value.

        * 'TIME'

          Produces a 'TIME' value.

        * 'UNSIGNED [INTEGER]'

          Produces an unsigned integer value.

12.11 XML Functions
===================

*XML Functions*

Name                          Description

'ExtractValue()'              Extracts a value from an XML string using
                              XPath notation

'UpdateXML()'                 Return replaced XML fragment

This section discusses XML and related functionality in MySQL.

*Note*:

It is possible to obtain XML-formatted output from MySQL in the
'mysql' and 'mysqldump' clients by invoking
them with the '--xml' option.  See mysql, and mysqldump.

Two functions providing basic XPath 1.0 (XML Path Language, version 1.0)
capabilities are available.  Some basic information about XPath syntax
and usage is provided later in this section; however, an in-depth
discussion of these topics is beyond the scope of this manual, and you
should refer to the XML Path Language (XPath) 1.0 standard
(http://www.w3.org/TR/xpath) for definitive information.  A useful
resource for those new to XPath or who desire a refresher in the basics
is the Zvon.org XPath Tutorial (http://www.zvon.org/xxl/XPathTutorial/),
which is available in several languages.

*Note*:

These functions remain under development.  We continue to improve these
and other aspects of XML and XPath functionality in MySQL 5.7 and
onwards.  You may discuss these, ask questions about them, and obtain
help from other users with them in the MySQL XML User Forum
(http://forums.mysql.com/list.php?44).

XPath expressions used with these functions support user variables and
local stored program variables.  User variables are weakly checked;
variables local to stored programs are strongly checked (see also Bug
#26518):

   * User variables (weak checking)

     Variables using the syntax '$@VARIABLE_NAME' (that is, user
     variables) are not checked.  No warnings or errors are issued by
     the server if a variable has the wrong type or has previously not
     been assigned a value.  This also means the user is fully
     responsible for any typographical errors, since no warnings will be
     given if (for example) '$@myvariable' is used where '$@myvariable'
     was intended.

     Example:

          mysql> SET @xml = '<a><b>X</b><b>Y</b></a>';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SET @i =1, @j = 2;
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT @i, ExtractValue(@xml, '//b[$@i]');
          +------+--------------------------------+
          | @i   | ExtractValue(@xml, '//b[$@i]') |
          +------+--------------------------------+
          |    1 | X                              |
          +------+--------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT @j, ExtractValue(@xml, '//b[$@j]');
          +------+--------------------------------+
          | @j   | ExtractValue(@xml, '//b[$@j]') |
          +------+--------------------------------+
          |    2 | Y                              |
          +------+--------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT @k, ExtractValue(@xml, '//b[$@k]');
          +------+--------------------------------+
          | @k   | ExtractValue(@xml, '//b[$@k]') |
          +------+--------------------------------+
          | NULL |                                |
          +------+--------------------------------+
          1 row in set (0.00 sec)

   * Variables in stored programs (strong checking)

     Variables using the syntax '$VARIABLE_NAME' can be declared and
     used with these functions when they are called inside stored
     programs.  Such variables are local to the stored program in which
     they are defined, and are strongly checked for type and value.

     Example:

          mysql> DELIMITER |

          mysql> CREATE PROCEDURE myproc ()
              -> BEGIN
              ->   DECLARE i INT DEFAULT 1;
              ->   DECLARE xml VARCHAR(25) DEFAULT '<a>X</a><a>Y</a><a>Z</a>';
              ->
              ->   WHILE i < 4 DO
              ->     SELECT xml, i, ExtractValue(xml, '//a[$i]');
              ->     SET i = i+1;
              ->   END WHILE;
              -> END |
          Query OK, 0 rows affected (0.01 sec)

          mysql> DELIMITER ;

          mysql> CALL myproc();
          +--------------------------+---+------------------------------+
          | xml                      | i | ExtractValue(xml, '//a[$i]') |
          +--------------------------+---+------------------------------+
          | <a>X</a><a>Y</a><a>Z</a> | 1 | X                            |
          +--------------------------+---+------------------------------+
          1 row in set (0.00 sec)

          +--------------------------+---+------------------------------+
          | xml                      | i | ExtractValue(xml, '//a[$i]') |
          +--------------------------+---+------------------------------+
          | <a>X</a><a>Y</a><a>Z</a> | 2 | Y                            |
          +--------------------------+---+------------------------------+
          1 row in set (0.01 sec)

          +--------------------------+---+------------------------------+
          | xml                      | i | ExtractValue(xml, '//a[$i]') |
          +--------------------------+---+------------------------------+
          | <a>X</a><a>Y</a><a>Z</a> | 3 | Z                            |
          +--------------------------+---+------------------------------+
          1 row in set (0.01 sec)

     Parameters

     Variables used in XPath expressions inside stored routines that are
     passed in as parameters are also subject to strong checking.

Expressions containing user variables or variables local to stored
programs must otherwise (except for notation) conform to the rules for
XPath expressions containing variables as given in the XPath 1.0
specification.

*Note*:

A user variable used to store an XPath expression is treated as an empty
string.  Because of this, it is not possible to store an XPath
expression as a user variable.  (Bug #32911)

   *
     'ExtractValue(XML_FRAG, XPATH_EXPR)'

     'ExtractValue()' takes two string arguments, a fragment of XML
     markup XML_FRAG and an XPath expression XPATH_EXPR (also known as a
     _locator_); it returns the text ('CDATA') of the first text node
     which is a child of the element or elements matched by the XPath
     expression.

     Using this function is the equivalent of performing a match using
     the XPATH_EXPR after appending '/text()'.  In other words,
     'ExtractValue('<a><b>Sakila</b></a>', '/a/b')' and
     'ExtractValue('<a><b>Sakila</b></a>', '/a/b/text()')' produce the
     same result.

     If multiple matches are found, the content of the first child text
     node of each matching element is returned (in the order matched) as
     a single, space-delimited string.

     If no matching text node is found for the expression (including the
     implicit '/text()')--for whatever reason, as long as XPATH_EXPR is
     valid, and XML_FRAG consists of elements which are properly nested
     and closed--an empty string is returned.  No distinction is made
     between a match on an empty element and no match at all.  This is
     by design.

     If you need to determine whether no matching element was found in
     XML_FRAG or such an element was found but contained no child text
     nodes, you should test the result of an expression that uses the
     XPath 'count()' function.  For example, both of these statements
     return an empty string, as shown here:

          mysql> SELECT ExtractValue('<a><b/></a>', '/a/b');
          +-------------------------------------+
          | ExtractValue('<a><b/></a>', '/a/b') |
          +-------------------------------------+
          |                                     |
          +-------------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT ExtractValue('<a><c/></a>', '/a/b');
          +-------------------------------------+
          | ExtractValue('<a><c/></a>', '/a/b') |
          +-------------------------------------+
          |                                     |
          +-------------------------------------+
          1 row in set (0.00 sec)

     However, you can determine whether there was actually a matching
     element using the following:

          mysql> SELECT ExtractValue('<a><b/></a>', 'count(/a/b)');
          +-------------------------------------+
          | ExtractValue('<a><b/></a>', 'count(/a/b)') |
          +-------------------------------------+
          | 1                                   |
          +-------------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT ExtractValue('<a><c/></a>', 'count(/a/b)');
          +-------------------------------------+
          | ExtractValue('<a><c/></a>', 'count(/a/b)') |
          +-------------------------------------+
          | 0                                   |
          +-------------------------------------+
          1 row in set (0.01 sec)

     *Important*:

     'ExtractValue()' returns only 'CDATA', and does not return any tags
     that might be contained within a matching tag, nor any of their
     content (see the result returned as 'val1' in the following
     example).

          mysql> SELECT
              ->   ExtractValue('<a>ccc<b>ddd</b></a>', '/a') AS val1,
              ->   ExtractValue('<a>ccc<b>ddd</b></a>', '/a/b') AS val2,
              ->   ExtractValue('<a>ccc<b>ddd</b></a>', '//b') AS val3,
              ->   ExtractValue('<a>ccc<b>ddd</b></a>', '/b') AS val4,
              ->   ExtractValue('<a>ccc<b>ddd</b><b>eee</b></a>', '//b') AS val5;

          +------+------+------+------+---------+
          | val1 | val2 | val3 | val4 | val5    |
          +------+------+------+------+---------+
          | ccc  | ddd  | ddd  |      | ddd eee |
          +------+------+------+------+---------+

     This function uses the current SQL collation for making comparisons
     with 'contains()', performing the same collation aggregation as
     other string functions (such as 'CONCAT()'), in taking into account
     the collation coercibility of their arguments; see
     charset-collation-coercibility, for an explanation of the rules
     governing this behavior.

     (Previously, binary--that is, case-sensitive--comparison was always
     used.)

     'NULL' is returned if XML_FRAG contains elements which are not
     properly nested or closed, and a warning is generated, as shown in
     this example:

          mysql> SELECT ExtractValue('<a>c</a><b', '//a');
          +-----------------------------------+
          | ExtractValue('<a>c</a><b', '//a') |
          +-----------------------------------+
          | NULL                              |
          +-----------------------------------+
          1 row in set, 1 warning (0.00 sec)

          mysql> SHOW WARNINGS\G
          *************************** 1. row ***************************
            Level: Warning
             Code: 1525
          Message: Incorrect XML value: 'parse error at line 1 pos 11:
                   END-OF-INPUT unexpected ('>' wanted)'
          1 row in set (0.00 sec)

          mysql> SELECT ExtractValue('<a>c</a><b/>', '//a');
          +-------------------------------------+
          | ExtractValue('<a>c</a><b/>', '//a') |
          +-------------------------------------+
          | c                                   |
          +-------------------------------------+
          1 row in set (0.00 sec)

   *
     'UpdateXML(XML_TARGET, XPATH_EXPR, NEW_XML)'

     This function replaces a single portion of a given fragment of XML
     markup XML_TARGET with a new XML fragment NEW_XML, and then returns
     the changed XML. The portion of XML_TARGET that is replaced matches
     an XPath expression XPATH_EXPR supplied by the user.

     If no expression matching XPATH_EXPR is found, or if multiple
     matches are found, the function returns the original XML_TARGET XML
     fragment.  All three arguments should be strings.

          mysql> SELECT
              ->   UpdateXML('<a><b>ccc</b><d></d></a>', '/a', '<e>fff</e>') AS val1,
              ->   UpdateXML('<a><b>ccc</b><d></d></a>', '/b', '<e>fff</e>') AS val2,
              ->   UpdateXML('<a><b>ccc</b><d></d></a>', '//b', '<e>fff</e>') AS val3,
              ->   UpdateXML('<a><b>ccc</b><d></d></a>', '/a/d', '<e>fff</e>') AS val4,
              ->   UpdateXML('<a><d></d><b>ccc</b><d></d></a>', '/a/d', '<e>fff</e>') AS val5
              -> \G

          *************************** 1. row ***************************
          val1: <e>fff</e>
          val2: <a><b>ccc</b><d></d></a>
          val3: <a><e>fff</e><d></d></a>
          val4: <a><b>ccc</b><e>fff</e></a>
          val5: <a><d></d><b>ccc</b><d></d></a>

*Note*:

A discussion in depth of XPath syntax and usage are beyond the scope of
this manual.  Please see the XML Path Language (XPath) 1.0 specification
(http://www.w3.org/TR/xpath) for definitive information.  A useful
resource for those new to XPath or who are wishing a refresher in the
basics is the Zvon.org XPath Tutorial
(http://www.zvon.org/xxl/XPathTutorial/), which is available in several
languages.

Descriptions and examples of some basic XPath expressions follow:

   * '/TAG'

     Matches '<TAG/>' if and only if '<TAG/>' is the root element.

     Example: '/a' has a match in '<a><b/></a>' because it matches the
     outermost (root) tag.  It does not match the inner A element in
     '<b><a/></b>' because in this instance it is the child of another
     element.

   * '/TAG1/TAG2'

     Matches '<TAG2/>' if and only if it is a child of '<TAG1/>', and
     '<TAG1/>' is the root element.

     Example: '/a/b' matches the B element in the XML fragment
     '<a><b/></a>' because it is a child of the root element A.  It does
     not have a match in '<b><a/></b>' because in this case, B is the
     root element (and hence the child of no other element).  Nor does
     the XPath expression have a match in '<a><c><b/></c></a>'; here, B
     is a descendant of A, but not actually a child of A.

     This construct is extendable to three or more elements.  For
     example, the XPath expression '/a/b/c' matches the C element in the
     fragment '<a><b><c/></b></a>'.

   * '//TAG'

     Matches any instance of '<TAG>'.

     Example: '//a' matches the A element in any of the following:
     '<a><b><c/></b></a>'; '<c><a><b/></a></b>'; '<c><b><a/></b></c>'.

     '//' can be combined with '/'.  For example, '//a/b' matches the B
     element in either of the fragments '<a><b/></a>' or
     '<c><a><b/></a></c>'.

     *Note*:

     '//TAG' is the equivalent of '/descendant-or-self::*/TAG'.  A
     common error is to confuse this with '/descendant-or-self::TAG',
     although the latter expression can actually lead to very different
     results, as can be seen here:

          mysql> SET @xml = '<a><b><c>w</c><b>x</b><d>y</d>z</b></a>';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT @xml;
          +-----------------------------------------+
          | @xml                                    |
          +-----------------------------------------+
          | <a><b><c>w</c><b>x</b><d>y</d>z</b></a> |
          +-----------------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT ExtractValue(@xml, '//b[1]');
          +------------------------------+
          | ExtractValue(@xml, '//b[1]') |
          +------------------------------+
          | x z                          |
          +------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT ExtractValue(@xml, '//b[2]');
          +------------------------------+
          | ExtractValue(@xml, '//b[2]') |
          +------------------------------+
          |                              |
          +------------------------------+
          1 row in set (0.01 sec)

          mysql> SELECT ExtractValue(@xml, '/descendant-or-self::*/b[1]');
          +---------------------------------------------------+
          | ExtractValue(@xml, '/descendant-or-self::*/b[1]') |
          +---------------------------------------------------+
          | x z                                               |
          +---------------------------------------------------+
          1 row in set (0.06 sec)

          mysql> SELECT ExtractValue(@xml, '/descendant-or-self::*/b[2]');
          +---------------------------------------------------+
          | ExtractValue(@xml, '/descendant-or-self::*/b[2]') |
          +---------------------------------------------------+
          |                                                   |
          +---------------------------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT ExtractValue(@xml, '/descendant-or-self::b[1]');
          +-------------------------------------------------+
          | ExtractValue(@xml, '/descendant-or-self::b[1]') |
          +-------------------------------------------------+
          | z                                               |
          +-------------------------------------------------+
          1 row in set (0.00 sec)

          mysql> SELECT ExtractValue(@xml, '/descendant-or-self::b[2]');
          +-------------------------------------------------+
          | ExtractValue(@xml, '/descendant-or-self::b[2]') |
          +-------------------------------------------------+
          | x                                               |
          +-------------------------------------------------+
          1 row in set (0.00 sec)

   * The '*' operator acts as a 'wildcard' that matches any element.
     For example, the expression '/*/b' matches the B element in either
     of the XML fragments '<a><b/></a>' or '<c><b/></c>'.  However, the
     expression does not produce a match in the fragment '<b><a/></b>'
     because B must be a child of some other element.  The wildcard may
     be used in any position: The expression '/*/b/*' will match any
     child of a B element that is itself not the root element.

   * You can match any of several locators using the '|' (see 'UNION')
     operator.  For example, the expression '//b|//c' matches
     all B and C elements in the XML target.

   * It is also possible to match an element based on the value of one
     or more of its attributes.  This done using the syntax
     'TAG[@ATTRIBUTE="VALUE"]'.  For example, the expression
     '//b[@id="idB"]' matches the second B element in the fragment
     '<a><b id="idA"/><c/><b id="idB"/></a>'.  To match against _any_
     element having 'ATTRIBUTE="VALUE"', use the XPath expression
     '//*[ATTRIBUTE="VALUE"]'.

     To filter multiple attribute values, simply use multiple
     attribute-comparison clauses in succession.  For example, the
     expression '//b[@c="x"][@d="y"]' matches the element '<b c="x"
     d="y"/>' occurring anywhere in a given XML fragment.

     To find elements for which the same attribute matches any of
     several values, you can use multiple locators joined by the '|'
     operator.  For example, to match all B elements whose C attributes
     have either of the values 23 or 17, use the expression
     '//b[@c="23"]|//b[@c="17"]'.  You can also use the logical 'or'
     operator for this purpose: '//b[@c="23" or @c="17"]'.

     *Note*:

     The difference between 'or' and '|' is that 'or' joins conditions,
     while '|' joins result sets.

XPath Limitations

The XPath syntax supported by these functions is currently subject to
the following limitations:

   * Nodeset-to-nodeset comparison (such as ''/a/b[@c=@d]'') is not
     supported.

   * All of the standard XPath comparison operators are supported.  (Bug
     #22823)

   * Relative locator expressions are resolved in the context of the
     root node.  For example, consider the following query and result:

          mysql> SELECT ExtractValue(
              ->   '<a><b c="1">X</b><b c="2">Y</b></a>',
              ->    'a/b'
              -> ) AS result;
          +--------+
          | result |
          +--------+
          | X Y    |
          +--------+
          1 row in set (0.03 sec)

     In this case, the locator 'a/b' resolves to '/a/b'.

     Relative locators are also supported within predicates.  In the
     following example, 'd[../@c="1"]' is resolved as '/a/b[@c="1"]/d':

          mysql> SELECT ExtractValue(
              ->      '<a>
              ->        <b c="1"><d>X</d></b>
              ->        <b c="2"><d>X</d></b>
              ->      </a>',
              ->      'a/b/d[../@c="1"]')
              -> AS result;
          +--------+
          | result |
          +--------+
          | X      |
          +--------+
          1 row in set (0.00 sec)

   * Locators prefixed with expressions that evaluate as scalar
     values--including variable references, literals, numbers, and
     scalar function calls--are not permitted, and their use results in
     an error.

   * The '::' operator is not supported in combination with node types
     such as the following:

        * 'AXIS::comment()'

        * 'AXIS::text()'

        * 'AXIS::processing-instructions()'

        * 'AXIS::node()'

     However, name tests (such as 'AXIS::NAME' and 'AXIS::*') are
     supported, as shown in these examples:

          mysql> SELECT ExtractValue('<a><b>x</b><c>y</c></a>','/a/child::b');
          +-------------------------------------------------------+
          | ExtractValue('<a><b>x</b><c>y</c></a>','/a/child::b') |
          +-------------------------------------------------------+
          | x                                                     |
          +-------------------------------------------------------+
          1 row in set (0.02 sec)

          mysql> SELECT ExtractValue('<a><b>x</b><c>y</c></a>','/a/child::*');
          +-------------------------------------------------------+
          | ExtractValue('<a><b>x</b><c>y</c></a>','/a/child::*') |
          +-------------------------------------------------------+
          | x y                                                   |
          +-------------------------------------------------------+
          1 row in set (0.01 sec)

   * 'Up-and-down' navigation is not supported in cases where the path
     would lead 'above' the root element.  That is, you cannot use
     expressions which match on descendants of ancestors of a given
     element, where one or more of the ancestors of the current element
     is also an ancestor of the root element (see Bug #16321).

   * The following XPath functions are not supported, or have known
     issues as indicated:

        * 'id()'

        * 'lang()'

        * 'local-name()'

        * 'name()'

        * 'namespace-uri()'

        * 'normalize-space()'

        * 'starts-with()'

        * 'string()'

        * 'substring-after()'

        * 'substring-before()'

        * 'translate()'

   * The following axes are not supported:

        * 'following-sibling'

        * 'following'

        * 'preceding-sibling'

        * 'preceding'

XPath expressions passed as arguments to 'ExtractValue()' and
'UpdateXML()' may contain the colon character (':') in element
selectors, which enables their use with markup employing XML namespaces
notation.  For example:

     mysql> SET @xml = '<a>111<b:c>222<d>333</d><e:f>444</e:f></b:c></a>';
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT ExtractValue(@xml, '//e:f');
     +-----------------------------+
     | ExtractValue(@xml, '//e:f') |
     +-----------------------------+
     | 444                         |
     +-----------------------------+
     1 row in set (0.00 sec)

     mysql> SELECT UpdateXML(@xml, '//b:c', '<g:h>555</g:h>');
     +--------------------------------------------+
     | UpdateXML(@xml, '//b:c', '<g:h>555</g:h>') |
     +--------------------------------------------+
     | <a>111<g:h>555</g:h></a>                   |
     +--------------------------------------------+
     1 row in set (0.00 sec)

This is similar in some respects to what is permitted by Apache Xalan
(http://xalan.apache.org/) and some other parsers, and is much simpler
than requiring namespace declarations or the use of the
'namespace-uri()' and 'local-name()' functions.

Error handling

For both 'ExtractValue()' and 'UpdateXML()', the XPath locator used must
be valid and the XML to be searched must consist of elements which are
properly nested and closed.  If the locator is invalid, an error is
generated:

     mysql> SELECT ExtractValue('<a>c</a><b/>', '/&a');
     ERROR 1105 (HY000): XPATH syntax error: '&a'

If XML_FRAG does not consist of elements which are properly nested and
closed, 'NULL' is returned and a warning is generated, as shown in this
example:

     mysql> SELECT ExtractValue('<a>c</a><b', '//a');
     +-----------------------------------+
     | ExtractValue('<a>c</a><b', '//a') |
     +-----------------------------------+
     | NULL                              |
     +-----------------------------------+
     1 row in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Warning
        Code: 1525
     Message: Incorrect XML value: 'parse error at line 1 pos 11:
              END-OF-INPUT unexpected ('>' wanted)'
     1 row in set (0.00 sec)

     mysql> SELECT ExtractValue('<a>c</a><b/>', '//a');
     +-------------------------------------+
     | ExtractValue('<a>c</a><b/>', '//a') |
     +-------------------------------------+
     | c                                   |
     +-------------------------------------+
     1 row in set (0.00 sec)

*Important*:

The replacement XML used as the third argument to 'UpdateXML()' is _not_
checked to determine whether it consists solely of elements which are
properly nested and closed.

XPath Injection

_code injection_ occurs when malicious code is introduced into the
system to gain unauthorized access to privileges and data.  It is based
on exploiting assumptions made by developers about the type and content
of data input from users.  XPath is no exception in this regard.

A common scenario in which this can happen is the case of application
which handles authorization by matching the combination of a login name
and password with those found in an XML file, using an XPath expression
like this one:

     //user[login/text()='neapolitan' and password/text()='1c3cr34m']/attribute::id

This is the XPath equivalent of an SQL statement like this one:

     SELECT id FROM users WHERE login='neapolitan' AND password='1c3cr34m';

A PHP application employing XPath might handle the login process like
this:

     <?php

       $file     =   "users.xml";

       $login    =   $POST["login"];
       $password =   $POST["password"];

       $xpath = "//user[login/text()=$login and password/text()=$password]/attribute::id";

       if( file_exists($file) )
       {
         $xml = simplexml_load_file($file);

         if($result = $xml->xpath($xpath))
           echo "You are now logged in as user $result[0].";
         else
           echo "Invalid login name or password.";
       }
       else
         exit("Failed to open $file.");

     ?>

No checks are performed on the input.  This means that a malevolent user
can 'short-circuit' the test by entering '' or 1=1' for both the login
name and password, resulting in $xpath being evaluated as shown here:

     //user[login/text()='' or 1=1 and password/text()='' or 1=1]/attribute::id

Since the expression inside the square brackets always evaluates as
'true', it is effectively the same as this one, which matches the 'id'
attribute of every 'user' element in the XML document:

     //user/attribute::id

One way in which this particular attack can be circumvented is simply by
quoting the variable names to be interpolated in the definition of
'$xpath', forcing the values passed from a Web form to be converted to
strings:

     $xpath = "//user[login/text()='$login' and password/text()='$password']/attribute::id";

This is the same strategy that is often recommended for preventing SQL
injection attacks.  In general, the practices you should follow for
preventing XPath injection attacks are the same as for preventing SQL
injection:

   * Never accepted untested data from users in your application.

   * Check all user-submitted data for type; reject or convert data that
     is of the wrong type

   * Test numeric data for out of range values; truncate, round, or
     reject values that are out of range.  Test strings for illegal
     characters and either strip them out or reject input containing
     them.

   * Do not output explicit error messages that might provide an
     unauthorized user with clues that could be used to compromise the
     system; log these to a file or database table instead.

Just as SQL injection attacks can be used to obtain information about
database schemas, so can XPath injection be used to traverse XML files
to uncover their structure, as discussed in Amit Klein's paper Blind
XPath Injection
(http://www.packetstormsecurity.org/papers/bypass/Blind_XPath_Injection_20040518.pdf)
(PDF file, 46KB).

It is also important to check the output being sent back to the client.
Consider what can happen when we use the MySQL 'ExtractValue()'
function:

     mysql> SELECT ExtractValue(
         ->     LOAD_FILE('users.xml'),
         ->     '//user[login/text()="" or 1=1 and password/text()="" or 1=1]/attribute::id'
         -> ) AS id;
     +-------------------------------+
     | id                            |
     +-------------------------------+
     | 00327 13579 02403 42354 28570 |
     +-------------------------------+
     1 row in set (0.01 sec)

Because 'ExtractValue()' returns multiple matches as a single
space-delimited string, this injection attack provides every valid ID
contained within 'users.xml' to the user as a single row of output.  As
an extra safeguard, you should also test output before returning it to
the user.  Here is a simple example:

     mysql> SELECT @id = ExtractValue(
         ->     LOAD_FILE('users.xml'),
         ->     '//user[login/text()="" or 1=1 and password/text()="" or 1=1]/attribute::id'
         -> );
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT IF(
         ->     INSTR(@id, ' ') = 0,
         ->     @id,
         ->     'Unable to retrieve user ID')
         -> AS singleID;
     +----------------------------+
     | singleID                   |
     +----------------------------+
     | Unable to retrieve user ID |
     +----------------------------+
     1 row in set (0.00 sec)

In general, the guidelines for returning data to users securely are the
same as for accepting user input.  These can be summed up as:

   * Always test outgoing data for type and permissible values.

   * Never permit unauthorized users to view error messages that might
     provide information about the application that could be used to
     exploit it.

12.12 Bit Functions and Operators
=================================

*Bit Functions and Operators*

Name                          Description

'BIT_COUNT()'                 Return the number of bits that are set

'&'                           Bitwise AND

'~'                           Bitwise inversion

'|'                           Bitwise OR

'^'                           Bitwise XOR

'<<'                          Left shift

'>>'                          Right shift

Bit functions and operators comprise 'BIT_COUNT()', 'BIT_AND()',
'BIT_OR()', 'BIT_XOR()', '&', '|', '^', '~', '<<', and '>>'.  (The
'BIT_AND()', 'BIT_OR()', and 'BIT_XOR()' functions are aggregate
functions described at group-by-functions.)  Currently, bit
functions and operators require 'BIGINT'. (64-bit
integer) arguments and return 'BIGINT' values, so
they have a maximum range of 64 bits.  Arguments of other types are
converted to 'BIGINT' and truncation might occur.

An extension for MySQL 8.0 changes this cast-to-see 'BIGINT'
behavior: Bit functions and operators permit binary
string type arguments (see 'BINARY',
'VARBINARY', and the 'BLOB' types),
enabling them to take arguments and produce return values larger than 64
bits.  Consequently, bit operations on binary arguments in MySQL 5.7
might produce different results in MySQL 8.0.  To provide advance notice
about this potential change in behavior, the server produces warnings as
of MySQL 5.7.11 for bit operations for which binary arguments are not
converted to integer in MySQL 8.0.  These warnings afford an opportunity
to rewrite affected statements.  To explicitly produce MySQL 5.7
behavior in a way that will not change after an upgrade to 8.0, cast
bit-operation binary arguments to convert them to integer.

The five problematic expression types to watch out for are:

     NONLITERAL_BINARY { & | ^ } BINARY
     BINARY  { & | ^ } NONLITERAL_BINARY
     NONLITERAL_BINARY { << >> } ANYTHING
     ~ NONLITERAL_BINARY
     AGGR_BIT_FUNC(NONLITERAL_BINARY)

Those expressions return 'BIGINT' in MySQL 5.7,
binary string in 8.0.

Explanation of notation:

   * '{ OP1 OP2 ... }': List of operators that apply to the given
     expression type.

   * BINARY: Any kind of binary string argument, including a hexadecimal
     literal, bit literal, or 'NULL' literal.

   * NONLITERAL_BINARY: An argument that is a binary string value other
     than a hexadecimal literal, bit literal, or 'NULL' literal.

   * AGGR_BIT_FUNC: An aggregate function that takes bit-value
     arguments: 'BIT_AND()', 'BIT_OR()', 'BIT_XOR()'.

The server produces a single warning for each problematic expression in
a statement, not a warning for each row processed.  Suppose that a
statement containing two problematic expressions selects three rows from
a table.  The number of warnings per statement execution is two, not
six.  The following example illustrates this.

     mysql> CREATE TABLE t(vbin1 VARBINARY(32), vbin2 VARBINARY(32));
     Query OK, 0 rows affected (0.03 sec)

     mysql> INSERT INTO t VALUES (3,1), (3,2), (3,3);
     Query OK, 3 rows affected (0.01 sec)
     Records: 3  Duplicates: 0  Warnings: 0

     mysql> SELECT HEX(vbin1 & vbin2) AS op1,
         -> HEX(vbin1 | vbin2) AS op2
         -> FROM t;
     +------+------+
     | op1  | op2  |
     +------+------+
     | 1    | 3    |
     | 2    | 3    |
     | 3    | 3    |
     +------+------+
     3 rows in set, 2 warnings (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Warning
        Code: 1287
     Message: Bitwise operations on BINARY will change behavior in a future
              version, check the 'Bit functions' section in the manual.
     *************************** 2. row ***************************
       Level: Warning
        Code: 1287
     Message: Bitwise operations on BINARY will change behavior in a future
              version, check the 'Bit functions' section in the manual.
     2 rows in set (0.00 sec)

To avoid having an affected statement produce a different result after
an upgrade to MySQL 8.0, rewrite it so that it generates no
bit-operation warnings.  To do this, cast at least one binary argument
to 'BIGINT' with 'CAST(... AS UNSIGNED)'.  This
makes the MySQL 5.7 implicit binary-to-integer cast explicit:

     mysql> SELECT HEX(CAST(vbin1 AS UNSIGNED) & CAST(vbin2 AS UNSIGNED)) AS op1,
         -> HEX(CAST(vbin1 AS UNSIGNED) | CAST(vbin2 AS UNSIGNED)) AS op2
         -> FROM t;
     +------+------+
     | op1  | op2  |
     +------+------+
     | 1    | 3    |
     | 2    | 3    |
     | 3    | 3    |
     +------+------+
     3 rows in set (0.01 sec)

     mysql> SHOW WARNINGS\G
     Empty set (0.00 sec)

With the statement rewritten as shown, MySQL 8.0 respects the intention
to treat the binary arguments as integers and produces the same result
as in 5.7.  Also, replicating the statement from MySQL 5.7 to 8.0 does
not produce different results on different servers.

An affected statement that cannot be rewritten is subject to these
potential problems with respect to upgrades and replication:

   * The statement might return a different result after an upgrade to
     MySQL 8.0.

   * Replication to MySQL 8.0 from older versions might fail for
     statement-based and mixed-format binary logging.  This is also true
     for replaying older binary logs on an 8.0 server (for example,
     using 'mysqlbinlog').  To avoid this, switch to
     row-based binary logging on the older master server.

The following list describes available bit functions and operators:

   *
     '|'

     Bitwise OR.

     The result is an unsigned 64-bit integer.

          mysql> SELECT 29 | 15;
                  -> 31

   *
     '&'

     Bitwise AND.

     The result is an unsigned 64-bit integer.

          mysql> SELECT 29 & 15;
                  -> 13

   *
     '^'

     Bitwise XOR.

     The result is an unsigned 64-bit integer.

          mysql> SELECT 1 ^ 1;
                  -> 0
          mysql> SELECT 1 ^ 0;
                  -> 1
          mysql> SELECT 11 ^ 3;
                  -> 8

   *
     '<<'

     Shifts a longlong (see 'BIGINT') number to the
     left.

     The result is an unsigned 64-bit integer.  The value is truncated
     to 64 bits.  In particular, if the shift count is greater or equal
     to the width of an unsigned 64-bit number, the result is zero.

          mysql> SELECT 1 << 2;
                  -> 4

   *
     '>>'

     Shifts a longlong (see 'BIGINT') number to the
     right.

     The result is an unsigned 64-bit integer.  The value is truncated
     to 64 bits.  In particular, if the shift count is greater or equal
     to the width of an unsigned 64-bit number, the result is zero.

          mysql> SELECT 4 >> 2;
                  -> 1

   *
     '~'

     Invert all bits.

     The result is an unsigned 64-bit integer.

          mysql> SELECT 5 & ~1;
                  -> 4

   *
     'BIT_COUNT(N)'

     Returns the number of bits that are set in the argument N as an
     unsigned 64-bit integer, or 'NULL' if the argument is 'NULL'.

          mysql> SELECT BIT_COUNT(29), BIT_COUNT(b'101010');
                  -> 4, 3

12.13 Encryption and Compression Functions
==========================================

*Encryption Functions*

Name                          Description

'AES_DECRYPT()'               Decrypt using AES

'AES_ENCRYPT()'               Encrypt using AES

'ASYMMETRIC_DECRYPT()'        Decrypt ciphertext using private or
                              public key

'ASYMMETRIC_DERIVE()'         Derive symmetric key from asymmetric keys

'ASYMMETRIC_ENCRYPT()'        Encrypt cleartext using private or public
                              key

'ASYMMETRIC_SIGN()'           Generate signature from digest

'ASYMMETRIC_VERIFY()'         Verify that signature matches digest

'COMPRESS()'                  Return result as a binary string

'CREATE_ASYMMETRIC_PRIV_KEY()'Create private key

'CREATE_ASYMMETRIC_PUB_KEY()' Create public key

'CREATE_DH_PARAMETERS()'      Generate shared DH secret

'CREATE_DIGEST()'             Generate digest from string

'DECODE()' (deprecated        Decodes a string encrypted using ENCODE()
5.7.2)

'DES_DECRYPT()' (deprecated   Decrypt a string
5.7.6)

'DES_ENCRYPT()' (deprecated   Encrypt a string
5.7.6)

'ENCODE()' (deprecated        Encode a string
5.7.2)

'ENCRYPT()' (deprecated       Encrypt a string
5.7.6)

'MD5()'                       Calculate MD5 checksum

'OLD_PASSWORD()'              Return the value of the pre-4.1
                              implementation of PASSWORD

'PASSWORD()' (deprecated      Calculate and return a password string
5.7.6)

'RANDOM_BYTES()'              Return a random byte vector

'SHA1()', 'SHA()'             Calculate an SHA-1 160-bit checksum

'SHA2()'                      Calculate an SHA-2 checksum

'UNCOMPRESS()'                Uncompress a string compressed

'UNCOMPRESSED_LENGTH()'       Return the length of a string before
                              compression

'VALIDATE_PASSWORD_STRENGTH()'Determine strength of password

Many encryption and compression functions return strings for which the
result might contain arbitrary byte values.  If you want to store these
results, use a column with a 'VARBINARY' or
'BLOB' binary string data type.  This will avoid potential
problems with trailing space removal or character set conversion that
would change data values, such as may occur if you use a nonbinary
string data type (see 'CHAR', 'VARCHAR',
'TEXT').

Some encryption functions return strings of ASCII characters: 'MD5()',
'OLD_PASSWORD()', 'PASSWORD()', 'SHA()', 'SHA1()', 'SHA2()'.  Their
return value is a string that has a character set and collation
determined by the 'character_set_connection' and 'collation_connection'
system variables.  This is a nonbinary string unless the character set
is 'binary'.

If an application stores values from a function such as 'MD5()' or
'SHA1()' that returns a string of hex digits, more efficient storage and
comparisons can be obtained by converting the hex representation to
binary using 'UNHEX()' and storing the result in a 'BINARY(N)'
column.  Each pair of hexadecimal digits requires one
byte in binary form, so the value of N depends on the length of the hex
string.  N is 16 for an 'MD5()' value and 20 for a 'SHA1()' value.  For
'SHA2()', N ranges from 28 to 32 depending on the argument specifying
the desired bit length of the result.

The size penalty for storing the hex string in a 'CHAR'.
column is at least two times, up to eight times if the value is stored
in a column that uses the 'utf8' character set (where each character
uses 4 bytes).  Storing the string also results in slower comparisons
because of the larger values and the need to take character set
collation rules into account.

Suppose that an application stores 'MD5()' string values in a
'CHAR(32)' column:

     CREATE TABLE md5_tbl (md5_val CHAR(32), ...);
     INSERT INTO md5_tbl (md5_val, ...) VALUES(MD5('abcdef'), ...);

To convert hex strings to more compact form, modify the application to
use 'UNHEX()' and 'BINARY(16)' instead as
follows:

     CREATE TABLE md5_tbl (md5_val BINARY(16), ...);
     INSERT INTO md5_tbl (md5_val, ...) VALUES(UNHEX(MD5('abcdef')), ...);

Applications should be prepared to handle the very rare case that a
hashing function produces the same value for two different input values.
One way to make collisions detectable is to make the hash column a
primary key.

*Note*:

Exploits for the MD5 and SHA-1 algorithms have become known.  You may
wish to consider using another one-way encryption function described in
this section instead, such as 'SHA2()'.

*Caution*:

Passwords or other sensitive values supplied as arguments to encryption
functions are sent in cleartext to the MySQL server unless an SSL
connection is used.  Also, such values will appear in any MySQL logs to
which they are written.  To avoid these types of exposure, applications
can encrypt sensitive values on the client side before sending them to
the server.  The same considerations apply to encryption keys.  To avoid
exposing these, applications can use stored procedures to encrypt and
decrypt values on the server side.

   *
     'AES_DECRYPT(CRYPT_STR,KEY_STR[,INIT_VECTOR])'

     This function decrypts data using the official AES (Advanced
     Encryption Standard) algorithm.  For more information, see the
     description of 'AES_ENCRYPT()'.

     The optional initialization vector argument, INIT_VECTOR, is
     available as of MySQL 5.7.4.  As of that version, statements that
     use 'AES_DECRYPT()' are unsafe for statement-based replication and
     cannot be stored in the query cache.

   *
     'AES_ENCRYPT(STR,KEY_STR[,INIT_VECTOR])'

     'AES_ENCRYPT()' and 'AES_DECRYPT()' implement encryption and
     decryption of data using the official AES (Advanced Encryption
     Standard) algorithm, previously known as 'Rijndael.' The AES
     standard permits various key lengths.  By default these functions
     implement AES with a 128-bit key length.  As of MySQL 5.7.4, key
     lengths of 196 or 256 bits can be used, as described later.  The
     key length is a trade off between performance and security.

     'AES_ENCRYPT()' encrypts the string STR using the key string
     KEY_STR and returns a binary string containing the encrypted
     output.  'AES_DECRYPT()' decrypts the encrypted string CRYPT_STR
     using the key string KEY_STR and returns the original cleartext
     string.  If either function argument is 'NULL', the function
     returns 'NULL'.

     The STR and CRYPT_STR arguments can be any length, and padding is
     automatically added to STR so it is a multiple of a block as
     required by block-based algorithms such as AES. This padding is
     automatically removed by the 'AES_DECRYPT()' function.  The length
     of CRYPT_STR can be calculated using this formula:

          16 * (trunc(STRING_LENGTH / 16) + 1)

     For a key length of 128 bits, the most secure way to pass a key to
     the KEY_STR argument is to create a truly random 128-bit value and
     pass it as a binary value.  For example:

          INSERT INTO t
          VALUES (1,AES_ENCRYPT('text',UNHEX('F3229A0B371ED2D9441B830D21A390C3')));

     A passphrase can be used to generate an AES key by hashing the
     passphrase.  For example:

          INSERT INTO t
          VALUES (1,AES_ENCRYPT('text', UNHEX(SHA2('My secret passphrase',512))));

     Do not pass a password or passphrase directly to CRYPT_STR, hash it
     first.  Previous versions of this documentation suggested the
     former approach, but it is no longer recommended as the examples
     shown here are more secure.

     If 'AES_DECRYPT()' detects invalid data or incorrect padding, it
     returns 'NULL'.  However, it is possible for 'AES_DECRYPT()' to
     return a non-'NULL' value (possibly garbage) if the input data or
     the key is invalid.

     As of MySQL 5.7.4, 'AES_ENCRYPT()' and 'AES_DECRYPT()' permit
     control of the block encryption mode and take an optional
     INIT_VECTOR initialization vector argument:

        * The 'block_encryption_mode' system variable controls the mode
          for block-based encryption algorithms.  Its default value is
          'aes-128-ecb', which signifies encryption using a key length
          of 128 bits and ECB mode.  For a description of the permitted
          values of this variable, see server-system-variables.

        * The optional INIT_VECTOR argument provides an initialization
          vector for block encryption modes that require it.

     For modes that require the optional INIT_VECTOR argument, it must
     be 16 bytes or longer (bytes in excess of 16 are ignored).  An
     error occurs if INIT_VECTOR is missing.

     For modes that do not require INIT_VECTOR, it is ignored and a
     warning is generated if it is specified.

     A random string of bytes to use for the initialization vector can
     be produced by calling 'RANDOM_BYTES(16)'.  For encryption modes
     that require an initialization vector, the same vector must be used
     for encryption and decryption.

          mysql> SET block_encryption_mode = 'aes-256-cbc';
          mysql> SET @key_str = SHA2('My secret passphrase',512);
          mysql> SET @init_vector = RANDOM_BYTES(16);
          mysql> SET @crypt_str = AES_ENCRYPT('text',@key_str,@init_vector);
          mysql> SELECT AES_DECRYPT(@crypt_str,@key_str,@init_vector);
          +-----------------------------------------------+
          | AES_DECRYPT(@crypt_str,@key_str,@init_vector) |
          +-----------------------------------------------+
          | text                                          |
          +-----------------------------------------------+

     The following table lists each permitted block encryption mode, the
     SSL libraries that support it, and whether the initialization
     vector argument is required.

     Block Encryption       SSL Libraries that        Initialization Vector
     Mode                   Support Mode              Required

     ECB                    OpenSSL, yaSSL            No

     CBC                    OpenSSL, yaSSL            Yes

     CFB1                   OpenSSL                   Yes

     CFB8                   OpenSSL                   Yes

     CFB128                 OpenSSL                   Yes

     OFB                    OpenSSL                   Yes

     As of MySQL 5.7.4, statements that use 'AES_ENCRYPT()' or
     'AES_DECRYPT()' are unsafe for statement-based replication and
     cannot be stored in the query cache.

   *
     'COMPRESS(STRING_TO_COMPRESS)'

     Compresses a string and returns the result as a binary string.
     This function requires MySQL to have been compiled with a
     compression library such as 'zlib'.  Otherwise, the return value is
     always 'NULL'.  The compressed string can be uncompressed with
     'UNCOMPRESS()'.

          mysql> SELECT LENGTH(COMPRESS(REPEAT('a',1000)));
                  -> 21
          mysql> SELECT LENGTH(COMPRESS(''));
                  -> 0
          mysql> SELECT LENGTH(COMPRESS('a'));
                  -> 13
          mysql> SELECT LENGTH(COMPRESS(REPEAT('a',16)));
                  -> 15

     The compressed string contents are stored the following way:

        * Empty strings are stored as empty strings.

        * Nonempty strings are stored as a 4-byte length of the
          uncompressed string (low byte first), followed by the
          compressed string.  If the string ends with space, an extra
          '.' character is added to avoid problems with endspace
          trimming should the result be stored in a 'CHAR'.
          or 'VARCHAR' column.  (However, use of nonbinary
          string data types such as 'CHAR' or
          'VARCHAR' to store compressed strings is not
          recommended anyway because character set conversion may occur.
          Use a 'VARBINARY' or 'BLOB'
          binary string column instead.)

   *
     'DECODE(CRYPT_STR,PASS_STR)'

     'DECODE()' decrypts the encrypted string CRYPT_STR using PASS_STR
     as the password.  CRYPT_STR should be a string returned from
     'ENCODE()'.

     *Note*:

     The 'ENCODE()' and 'DECODE()' functions are deprecated in MySQL
     5.7, will be removed in a future MySQL release, and should no
     longer be used.  Consider using 'AES_ENCRYPT()' and 'AES_DECRYPT()'
     instead.

   *
     'DES_DECRYPT(CRYPT_STR[,KEY_STR])'

     Decrypts a string encrypted with 'DES_ENCRYPT()'.  If an error
     occurs, this function returns 'NULL'.

     This function works only if MySQL has been configured with SSL
     support.  See encrypted-connections.

     If no KEY_STR argument is given, 'DES_DECRYPT()' examines the first
     byte of the encrypted string to determine the DES key number that
     was used to encrypt the original string, and then reads the key
     from the DES key file to decrypt the message.  For this to work,
     the user must have the 'SUPER' privilege.  The key file can be
     specified with the '--des-key-file' server option.

     If you pass this function a KEY_STR argument, that string is used
     as the key for decrypting the message.

     If the CRYPT_STR argument does not appear to be an encrypted
     string, MySQL returns the given CRYPT_STR.

     *Note*:

     The 'DES_ENCRYPT()' and 'DES_DECRYPT()' functions are deprecated as
     of MySQL 5.7.6, will be removed in a future MySQL release, and
     should no longer be used.  Consider using 'AES_ENCRYPT()' and
     'AES_DECRYPT()' instead.

   *
     'DES_ENCRYPT(STR[,{KEY_NUM|KEY_STR}])'

     Encrypts the string with the given key using the Triple-DES
     algorithm.

     This function works only if MySQL has been configured with SSL
     support.  See encrypted-connections.

     The encryption key to use is chosen based on the second argument to
     'DES_ENCRYPT()', if one was given.  With no argument, the first key
     from the DES key file is used.  With a KEY_NUM argument, the given
     key number (0 to 9) from the DES key file is used.  With a KEY_STR
     argument, the given key string is used to encrypt STR.

     The key file can be specified with the '--des-key-file' server
     option.

     The return string is a binary string where the first character is
     'CHAR(128 | KEY_NUM)'.  If an error occurs, 'DES_ENCRYPT()' returns
     'NULL'.

     The 128 is added to make it easier to recognize an encrypted key.
     If you use a string key, KEY_NUM is 127.

     The string length for the result is given by this formula:

          NEW_LEN = ORIG_LEN + (8 - (ORIG_LEN % 8)) + 1

     Each line in the DES key file has the following format:

          KEY_NUM DES_KEY_STR

     Each KEY_NUM value must be a number in the range from '0' to '9'.
     Lines in the file may be in any order.  DES_KEY_STR is the string
     that is used to encrypt the message.  There should be at least one
     space between the number and the key.  The first key is the default
     key that is used if you do not specify any key argument to
     'DES_ENCRYPT()'.

     You can tell MySQL to read new key values from the key file with
     the 'FLUSH DES_KEY_FILE' statement.  This requires the 'RELOAD'
     privilege.

     One benefit of having a set of default keys is that it gives
     applications a way to check for the existence of encrypted column
     values, without giving the end user the right to decrypt those
     values.

     *Note*:

     The 'DES_ENCRYPT()' and 'DES_DECRYPT()' functions are deprecated as
     of MySQL 5.7.6, will be removed in a future MySQL release, and
     should no longer be used.  Consider using 'AES_ENCRYPT()' and
     'AES_DECRYPT()' instead.

          mysql> SELECT customer_address FROM customer_table
               > WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number');

   *
     'ENCODE(STR,PASS_STR)'

     'ENCODE()' encrypts STR using PASS_STR as the password.  The result
     is a binary string of the same length as STR.  To decrypt the
     result, use 'DECODE()'.

     *Note*:

     The 'ENCODE()' and 'DECODE()' functions are deprecated in MySQL
     5.7, will be removed in a future MySQL release, and should no
     longer be used.

     If you still need to use 'ENCODE()', a salt value must be used with
     it to reduce risk.  For example:

          ENCODE('cleartext', CONCAT('my_random_salt','my_secret_password'))

     A new random salt value must be used whenever a password is
     updated.

   *
     'ENCRYPT(STR[,SALT])'

     Encrypts STR using the Unix 'crypt()' system call and returns a
     binary string.  The SALT argument must be a string with at least
     two characters or the result will be 'NULL'.  If no SALT argument
     is given, a random value is used.

     *Note*:

     The 'ENCRYPT()' function is deprecated as of MySQL 5.7.6, will be
     removed in a future MySQL release, and should no longer be used.
     For one-way hashing, consider using 'SHA2()' instead.

          mysql> SELECT ENCRYPT('hello');
                  -> 'VxuFAJXVARROc'

     'ENCRYPT()' ignores all but the first eight characters of STR, at
     least on some systems.  This behavior is determined by the
     implementation of the underlying 'crypt()' system call.

     The use of 'ENCRYPT()' with the 'ucs2', 'utf16', 'utf16le', or
     'utf32' multibyte character sets is not recommended because the
     system call expects a string terminated by a zero byte.

     If 'crypt()' is not available on your system (as is the case with
     Windows), 'ENCRYPT()' always returns 'NULL'.

   *
     'MD5(STR)'

     Calculates an MD5 128-bit checksum for the string.  The value is
     returned as a string of 32 hexadecimal digits, or 'NULL' if the
     argument was 'NULL'.  The return value can, for example, be used as
     a hash key.  See the notes at the beginning of this section about
     storing hash values efficiently.

     The return value is a string in the connection character set.

          mysql> SELECT MD5('testing');
                  -> 'ae2b1fca515949e5d54fb22b8ed95575'

     This is the 'RSA Data Security, Inc. MD5 Message-Digest Algorithm.'

     See the note regarding the MD5 algorithm at the beginning this
     section.

   *
     'OLD_PASSWORD(STR)'

     'OLD_PASSWORD()' was added when the implementation of 'PASSWORD()'
     was changed in MySQL 4.1 to improve security.  'OLD_PASSWORD()'
     returned the value of the pre-4.1 implementation of 'PASSWORD()' as
     a string, and was intended to permit you to reset passwords for any
     pre-4.1 clients that need to connect to your MySQL server without
     locking them out.  See password-hashing.

     Passwords that use the pre-4.1 hashing method are less secure than
     passwords that use the native password hashing method.  Support for
     pre-4.1 passwords was removed in MySQL 5.7.5, as was
     'OLD_PASSWORD()'.

   *
     'PASSWORD(STR)'

     *Note*:

     This function is deprecated as of MySQL 5.7.6 and will be removed
     in a future MySQL release.

     Returns a hashed password string calculated from the cleartext
     password STR.  The return value is a string in the connection
     character set, or 'NULL' if the argument is 'NULL'.  This function
     is the SQL interface to the algorithm used by the server to encrypt
     MySQL passwords for storage in the 'mysql.user' grant table.

     The 'old_passwords' system variable controls the password hashing
     method used by the 'PASSWORD()' function.  It also influences
     password hashing performed by 'CREATE USER' and
     'GRANT' statements that specify a password using an
     'IDENTIFIED BY' clause.

     The following table shows, for each password hashing method, the
     permitted value of 'old_passwords' and which authentication plugins
     use the hashing method.

     Password Hashing Method       old_passwords  Associated Authentication
                                   Value          Plugin

     MySQL 4.1 native hashing      0              'mysql_native_password'

     SHA-256 hashing               2              'sha256_password'

     SHA-256 password hashing ('old_passwords=2') uses a random salt
     value, which makes the result from 'PASSWORD()' nondeterministic.
     Consequently, statements that use this function are not safe for
     statement-based replication and cannot be stored in the query
     cache.

     Encryption performed by 'PASSWORD()' is one-way (not reversible),
     but it is not the same type of encryption used for Unix passwords.

     *Note*:

     'PASSWORD()' is used by the authentication system in MySQL Server;
     you should _not_ use it in your own applications.  For that
     purpose, consider a more secure function such as 'SHA2()' instead.
     Also see section 2 (Challenge-Response Authentication Mechanism
     (CRAM)), for more information about handling passwords and
     authentication securely in your applications.

     *Caution*:

     Under some circumstances, statements that invoke 'PASSWORD()' may
     be recorded in server logs or on the client side in a history file
     such as '~/.mysql_history', which means that cleartext passwords
     may be read by anyone having read access to that information.  For
     information about the conditions under which this occurs for the
     server logs and how to control it, see password-logging.
     For similar information about client-side logging, see
     mysql-logging.

   *
     'RANDOM_BYTES(LEN)'

     This function returns a binary string of LEN random bytes generated
     using the random number generator of the SSL library.  Permitted
     values of LEN range from 1 to 1024.  For values outside that range,
     'RANDOM_BYTES()' generates a warning and returns 'NULL'.

     'RANDOM_BYTES()' can be used to provide the initialization vector
     for the 'AES_DECRYPT()' and 'AES_ENCRYPT()' functions.  For use in
     that context, LEN must be at least 16.  Larger values are
     permitted, but bytes in excess of 16 are ignored.

     'RANDOM_BYTES()' generates a random value, which makes its result
     nondeterministic.  Consequently, statements that use this function
     are unsafe for statement-based replication and cannot be stored in
     the query cache.

     This function is available as of MySQL 5.7.4.

   *
     'SHA1(STR)', 'SHA(STR)'

     Calculates an SHA-1 160-bit checksum for the string, as described
     in RFC 3174 (Secure Hash Algorithm).  The value is returned as a
     string of 40 hexadecimal digits, or 'NULL' if the argument was
     'NULL'.  One of the possible uses for this function is as a hash
     key.  See the notes at the beginning of this section about storing
     hash values efficiently.  You can also use 'SHA1()' as a
     cryptographic function for storing passwords.  'SHA()' is
     synonymous with 'SHA1()'.

     The return value is a string in the connection character set.

          mysql> SELECT SHA1('abc');
                  -> 'a9993e364706816aba3e25717850c26c9cd0d89d'

     'SHA1()' can be considered a cryptographically more secure
     equivalent of 'MD5()'.  However, see the note regarding the MD5 and
     SHA-1 algorithms at the beginning this section.

   *
     'SHA2(STR, HASH_LENGTH)'

     Calculates the SHA-2 family of hash functions (SHA-224, SHA-256,
     SHA-384, and SHA-512).  The first argument is the cleartext string
     to be hashed.  The second argument indicates the desired bit length
     of the result, which must have a value of 224, 256, 384, 512, or 0
     (which is equivalent to 256).  If either argument is 'NULL' or the
     hash length is not one of the permitted values, the return value is
     'NULL'.  Otherwise, the function result is a hash value containing
     the desired number of bits.  See the notes at the beginning of this
     section about storing hash values efficiently.

     The return value is a string in the connection character set.

          mysql> SELECT SHA2('abc', 224);
                  -> '23097d223405d8228642a477bda255b32aadbce4bda0b3f7e36c9da7'

     This function works only if MySQL has been configured with SSL
     support.  See encrypted-connections.

     'SHA2()' can be considered cryptographically more secure than
     'MD5()' or 'SHA1()'.

   *
     'UNCOMPRESS(STRING_TO_UNCOMPRESS)'

     Uncompresses a string compressed by the 'COMPRESS()' function.  If
     the argument is not a compressed value, the result is 'NULL'.  This
     function requires MySQL to have been compiled with a compression
     library such as 'zlib'.  Otherwise, the return value is always
     'NULL'.

          mysql> SELECT UNCOMPRESS(COMPRESS('any string'));
                  -> 'any string'
          mysql> SELECT UNCOMPRESS('any string');
                  -> NULL

   *
     'UNCOMPRESSED_LENGTH(COMPRESSED_STRING)'

     Returns the length that the compressed string had before being
     compressed.

          mysql> SELECT UNCOMPRESSED_LENGTH(COMPRESS(REPEAT('a',30)));
                  -> 30

   *
     'VALIDATE_PASSWORD_STRENGTH(STR)'

     Given an argument representing a cleartext password, this function
     returns an integer to indicate how strong the password is.  The
     return value ranges from 0 (weak) to 100 (strong).

     Password assessment by 'VALIDATE_PASSWORD_STRENGTH()' is done by
     the 'validate_password' plugin.  If that plugin is not installed,
     the function always returns 0.  For information about installing
     'validate_password', see validate-password.  To examine or
     configure the parameters that affect password testing, check or set
     the system variables implemented by 'validate_password'.  See
     validate-password-options-variables.

     The password is subjected to increasingly strict tests and the
     return value reflects which tests were satisfied, as shown in the
     following table.  In addition, if the
     'validate_password_check_user_name' system variable is enabled and
     the password matches the user name, 'VALIDATE_PASSWORD_STRENGTH()'
     returns 0 regardless of how other 'validate_password' system
     variables are set.

     Password Test                               Return Value

     Length < 4                                  0

     Length ≥ 4 and <                           25
     'validate_password_length'

     Satisfies policy 1 ('LOW')                  50

     Satisfies policy 2 ('MEDIUM')               75

     Satisfies policy 3 ('STRONG')               100

12.14 Information Functions
===========================

*Information Functions*

Name                          Description

'BENCHMARK()'                 Repeatedly execute an expression

'CHARSET()'                   Return the character set of the argument

'COERCIBILITY()'              Return the collation coercibility value
                              of the string argument

'COLLATION()'                 Return the collation of the string
                              argument

'CONNECTION_ID()'             Return the connection ID (thread ID) for
                              the connection

'CURRENT_USER()',             The authenticated user name and host name
'CURRENT_USER'

'DATABASE()'                  Return the default (current) database
                              name

'FOUND_ROWS()'                For a SELECT with a LIMIT clause, the
                              number of rows that would be returned
                              were there no LIMIT clause

'LAST_INSERT_ID()'            Value of the AUTOINCREMENT column for the
                              last INSERT

'ROW_COUNT()'                 The number of rows updated

'SCHEMA()'                    Synonym for DATABASE()

'SESSION_USER()'              Synonym for USER()

'SYSTEM_USER()'               Synonym for USER()

'USER()'                      The user name and host name provided by
                              the client

'VERSION()'                   Return a string that indicates the MySQL
                              server version

   *
     'BENCHMARK(COUNT,EXPR)'

     The 'BENCHMARK()' function executes the expression EXPR repeatedly
     COUNT times.  It may be used to time how quickly MySQL processes
     the expression.  The result value is always '0'.  The intended use
     is from within the 'mysql' client, which reports
     query execution times:

          mysql> SELECT BENCHMARK(1000000,AES_ENCRYPT('hello','goodbye'));
          +---------------------------------------------------+
          | BENCHMARK(1000000,AES_ENCRYPT('hello','goodbye')) |
          +---------------------------------------------------+
          |                                                 0 |
          +---------------------------------------------------+
          1 row in set (4.74 sec)

     The time reported is elapsed time on the client end, not CPU time
     on the server end.  It is advisable to execute 'BENCHMARK()'
     several times, and to interpret the result with regard to how
     heavily loaded the server machine is.

     'BENCHMARK()' is intended for measuring the runtime performance of
     scalar expressions, which has some significant implications for the
     way that you use it and interpret the results:

        * Only scalar expressions can be used.  Although the expression
          can be a subquery, it must return a single column and at most
          a single row.  For example, 'BENCHMARK(10, (SELECT * FROM t))'
          will fail if the table 't' has more than one column or more
          than one row.

        * Executing a 'SELECT EXPR' statement N times differs from
          executing 'SELECT BENCHMARK(N, EXPR)' in terms of the amount
          of overhead involved.  The two have very different execution
          profiles and you should not expect them to take the same
          amount of time.  The former involves the parser, optimizer,
          table locking, and runtime evaluation N times each.  The
          latter involves only runtime evaluation N times, and all the
          other components just once.  Memory structures already
          allocated are reused, and runtime optimizations such as local
          caching of results already evaluated for aggregate functions
          can alter the results.  Use of 'BENCHMARK()' thus measures
          performance of the runtime component by giving more weight to
          that component and removing the 'noise' introduced by the
          network, parser, optimizer, and so forth.

   *
     'CHARSET(STR)'

     Returns the character set of the string argument.

          mysql> SELECT CHARSET('abc');
                  -> 'latin1'
          mysql> SELECT CHARSET(CONVERT('abc' USING utf8));
                  -> 'utf8'
          mysql> SELECT CHARSET(USER());
                  -> 'utf8'

   *
     'COERCIBILITY(STR)'

     Returns the collation coercibility value of the string argument.

          mysql> SELECT COERCIBILITY('abc' COLLATE latin1_swedish_ci);
                  -> 0
          mysql> SELECT COERCIBILITY(USER());
                  -> 3
          mysql> SELECT COERCIBILITY('abc');
                  -> 4
          mysql> SELECT COERCIBILITY(1000);
                  -> 5

     The return values have the meanings shown in the following table.
     Lower values have higher precedence.

     CoercibilityMeaning     Example

     '0'         Explicit    Value with 'COLLATE' clause
                 collation

     '1'         No          Concatenation of strings with different
                 collation   collations

     '2'         Implicit    Column value, stored routine parameter or local
                 collation   variable

     '3'         System      'USER()' return value
                 constant

     '4'         Coercible   Literal string

     '5'         Numeric     Numeric or temporal value

     '5'         Ignorable   'NULL' or an expression derived from 'NULL'

     For more information, see charset-collation-coercibility.

   *
     'COLLATION(STR)'

     Returns the collation of the string argument.

          mysql> SELECT COLLATION('abc');
                  -> 'latin1_swedish_ci'
          mysql> SELECT COLLATION(_utf8'abc');
                  -> 'utf8_general_ci'

   *
     'CONNECTION_ID()'

     Returns the connection ID (thread ID) for the connection.  Every
     connection has an ID that is unique among the set of currently
     connected clients.

     The value returned by 'CONNECTION_ID()' is the same type of value
     as displayed in the 'ID' column of the
     'INFORMATION_SCHEMA.PROCESSLIST' table, the
     'Id' column of 'SHOW PROCESSLIST' output,
     and the 'PROCESSLIST_ID' column of the Performance Schema
     'threads' table.

          mysql> SELECT CONNECTION_ID();
                  -> 23786

   *
     'CURRENT_USER', 'CURRENT_USER()'

     Returns the user name and host name combination for the MySQL
     account that the server used to authenticate the current client.
     This account determines your access privileges.  The return value
     is a string in the 'utf8' character set.

     The value of 'CURRENT_USER()' can differ from the value of
     'USER()'.

          mysql> SELECT USER();
                  -> 'davida@localhost'
          mysql> SELECT * FROM mysql.user;
          ERROR 1044: Access denied for user ''@'localhost' to
          database 'mysql'
          mysql> SELECT CURRENT_USER();
                  -> '@localhost'

     The example illustrates that although the client specified a user
     name of 'davida' (as indicated by the value of the 'USER()'
     function), the server authenticated the client using an anonymous
     user account (as seen by the empty user name part of the
     'CURRENT_USER()' value).  One way this might occur is that there is
     no account listed in the grant tables for 'davida'.

     Within a stored program or view, 'CURRENT_USER()' returns the
     account for the user who defined the object (as given by its
     'DEFINER' value) unless defined with the 'SQL SECURITY INVOKER'
     characteristic.  In the latter case, 'CURRENT_USER()' returns the
     object's invoker.

     Triggers and events have no option to define the 'SQL SECURITY'
     characteristic, so for these objects, 'CURRENT_USER()' returns the
     account for the user who defined the object.  To return the
     invoker, use 'USER()' or 'SESSION_USER()'.

     The following statements support use of the 'CURRENT_USER()'
     function to take the place of the name of (and, possibly, a host
     for) an affected user or a definer; in such cases, 'CURRENT_USER()'
     is expanded where and as needed:

        * 'DROP USER'.

        * 'RENAME USER'.

        * 'GRANT'.

        * 'REVOKE'.

        * 'CREATE FUNCTION'.

        * 'CREATE PROCEDURE'.

        * 'CREATE TRIGGER'.

        * 'CREATE EVENT'.

        * 'CREATE VIEW'.

        * 'ALTER EVENT'.

        * 'ALTER VIEW'.

        * 'SET PASSWORD'.

     For information about the implications that this expansion of
     'CURRENT_USER()' has for replication, see
     replication-features-current-user.

   *
     'DATABASE()'

     Returns the default (current) database name as a string in the
     'utf8' character set.  If there is no default database,
     'DATABASE()' returns 'NULL'.  Within a stored routine, the default
     database is the database that the routine is associated with, which
     is not necessarily the same as the database that is the default in
     the calling context.

          mysql> SELECT DATABASE();
                  -> 'test'

     If there is no default database, 'DATABASE()' returns 'NULL'.

   *
     'FOUND_ROWS()'

     A 'SELECT' statement may include a 'LIMIT' clause to
     restrict the number of rows the server returns to the client.  In
     some cases, it is desirable to know how many rows the statement
     would have returned without the 'LIMIT', but without running the
     statement again.  To obtain this row count, include an
     'SQL_CALC_FOUND_ROWS' option in the 'SELECT'.
     statement, and then invoke 'FOUND_ROWS()' afterward:

          mysql> SELECT SQL_CALC_FOUND_ROWS * FROM TBL_NAME
              -> WHERE id > 100 LIMIT 10;
          mysql> SELECT FOUND_ROWS();

     The second 'SELECT' returns a number indicating how
     many rows the first 'SELECT' would have returned had
     it been written without the 'LIMIT' clause.

     In the absence of the 'SQL_CALC_FOUND_ROWS' option in the most
     recent successful 'SELECT' statement, 'FOUND_ROWS()'
     returns the number of rows in the result set returned by that
     statement.  If the statement includes a 'LIMIT' clause,
     'FOUND_ROWS()' returns the number of rows up to the limit.  For
     example, 'FOUND_ROWS()' returns 10 or 60, respectively, if the
     statement includes 'LIMIT 10' or 'LIMIT 50, 10'.

     The row count available through 'FOUND_ROWS()' is transient and not
     intended to be available past the statement following the 'SELECT
     SQL_CALC_FOUND_ROWS' statement.  If you need to refer to the value
     later, save it:

          mysql> SELECT SQL_CALC_FOUND_ROWS * FROM ... ;
          mysql> SET @rows = FOUND_ROWS();

     If you are using 'SELECT SQL_CALC_FOUND_ROWS', MySQL must calculate
     how many rows are in the full result set.  However, this is faster
     than running the query again without 'LIMIT', because the result
     set need not be sent to the client.

     'SQL_CALC_FOUND_ROWS' and 'FOUND_ROWS()' can be useful in
     situations when you want to restrict the number of rows that a
     query returns, but also determine the number of rows in the full
     result set without running the query again.  An example is a Web
     script that presents a paged display containing links to the pages
     that show other sections of a search result.  Using 'FOUND_ROWS()'
     enables you to determine how many other pages are needed for the
     rest of the result.

     The use of 'SQL_CALC_FOUND_ROWS' and 'FOUND_ROWS()' is more complex
     for 'UNION' statements than for simple
     'SELECT' statements, because 'LIMIT' may occur at multiple
     places in a 'UNION'.  It may be applied to individual
     'SELECT' statements in the 'UNION', or
     global to the 'UNION' result as a whole.

     The intent of 'SQL_CALC_FOUND_ROWS' for 'UNION' is
     that it should return the row count that would be returned without
     a global 'LIMIT'.  The conditions for use of 'SQL_CALC_FOUND_ROWS'
     with 'UNION' are:

        * The 'SQL_CALC_FOUND_ROWS' keyword must appear in the first
          'SELECT' of the 'UNION'.

        * The value of 'FOUND_ROWS()' is exact only if 'UNION ALL'
          is used.  If 'UNION' without 'ALL'
          is used, duplicate removal occurs and the value of
          'FOUND_ROWS()' is only approximate.

        * If no 'LIMIT' is present in the 'UNION',
          'SQL_CALC_FOUND_ROWS' is ignored and returns the number of
          rows in the temporary table that is created to process the
          'UNION'.

     Beyond the cases described here, the behavior of 'FOUND_ROWS()' is
     undefined (for example, its value following a 'SELECT'
     statement that fails with an error).

     *Important*:

     'FOUND_ROWS()' is not replicated reliably using statement-based
     replication.  This function is automatically replicated using
     row-based replication.

   *
     'LAST_INSERT_ID()', 'LAST_INSERT_ID(EXPR)'

     With no argument, 'LAST_INSERT_ID()' returns a 'BIGINT UNSIGNED'
     (64-bit) value representing the first automatically generated value
     successfully inserted for an 'AUTO_INCREMENT' column as a result of
     the most recently executed 'INSERT' statement.  The
     value of 'LAST_INSERT_ID()' remains unchanged if no rows are
     successfully inserted.

     With an argument, 'LAST_INSERT_ID()' returns an unsigned integer.

     For example, after inserting a row that generates an
     'AUTO_INCREMENT' value, you can get the value like this:

          mysql> SELECT LAST_INSERT_ID();
                  -> 195

     The currently executing statement does not affect the value of
     'LAST_INSERT_ID()'.  Suppose that you generate an 'AUTO_INCREMENT'
     value with one statement, and then refer to 'LAST_INSERT_ID()' in a
     multiple-row 'INSERT' statement that inserts rows
     into a table with its own 'AUTO_INCREMENT' column.  The value of
     'LAST_INSERT_ID()' will remain stable in the second statement; its
     value for the second and later rows is not affected by the earlier
     row insertions.  (However, if you mix references to
     'LAST_INSERT_ID()' and 'LAST_INSERT_ID(EXPR)', the effect is
     undefined.)

     If the previous statement returned an error, the value of
     'LAST_INSERT_ID()' is undefined.  For transactional tables, if the
     statement is rolled back due to an error, the value of
     'LAST_INSERT_ID()' is left undefined.  For manual 'ROLLBACK',
     the value of 'LAST_INSERT_ID()' is not restored to that
     before the transaction; it remains as it was at the point of the
     'ROLLBACK'.

     Prior to MySQL 5.7.3, this function was not replicated correctly if
     replication filtering rules were in use.  (Bug #17234370, Bug
     #69861)

     Within the body of a stored routine (procedure or function) or a
     trigger, the value of 'LAST_INSERT_ID()' changes the same way as
     for statements executed outside the body of these kinds of objects.
     The effect of a stored routine or trigger upon the value of
     'LAST_INSERT_ID()' that is seen by following statements depends on
     the kind of routine:

        * If a stored procedure executes statements that change the
          value of 'LAST_INSERT_ID()', the changed value is seen by
          statements that follow the procedure call.

        * For stored functions and triggers that change the value, the
          value is restored when the function or trigger ends, so
          following statements will not see a changed value.

     The ID that was generated is maintained in the server on a
     _per-connection basis_.  This means that the value returned by the
     function to a given client is the first 'AUTO_INCREMENT' value
     generated for most recent statement affecting an 'AUTO_INCREMENT'
     column _by that client_.  This value cannot be affected by other
     clients, even if they generate 'AUTO_INCREMENT' values of their
     own.  This behavior ensures that each client can retrieve its own
     ID without concern for the activity of other clients, and without
     the need for locks or transactions.

     The value of 'LAST_INSERT_ID()' is not changed if you set the
     'AUTO_INCREMENT' column of a row to a non-'magic' value (that is, a
     value that is not 'NULL' and not '0').

     *Important*:

     If you insert multiple rows using a single 'INSERT'.
     statement, 'LAST_INSERT_ID()' returns the value generated for the
     _first_ inserted row _only_.  The reason for this is to make it
     possible to reproduce easily the same 'INSERT'.
     statement against some other server.

     For example:

          mysql> USE test;

          mysql> CREATE TABLE t (
                 id INT AUTO_INCREMENT NOT NULL PRIMARY KEY,
                 name VARCHAR(10) NOT NULL
                 );

          mysql> INSERT INTO t VALUES (NULL, 'Bob');

          mysql> SELECT * FROM t;
          +----+------+
          | id | name |
          +----+------+
          |  1 | Bob  |
          +----+------+

          mysql> SELECT LAST_INSERT_ID();
          +------------------+
          | LAST_INSERT_ID() |
          +------------------+
          |                1 |
          +------------------+

          mysql> INSERT INTO t VALUES
                 (NULL, 'Mary'), (NULL, 'Jane'), (NULL, 'Lisa');

          mysql> SELECT * FROM t;
          +----+------+
          | id | name |
          +----+------+
          |  1 | Bob  |
          |  2 | Mary |
          |  3 | Jane |
          |  4 | Lisa |
          +----+------+

          mysql> SELECT LAST_INSERT_ID();
          +------------------+
          | LAST_INSERT_ID() |
          +------------------+
          |                2 |
          +------------------+

     Although the second 'INSERT' statement inserted
     three new rows into 't', the ID generated for the first of these
     rows was '2', and it is this value that is returned by
     'LAST_INSERT_ID()' for the following 'SELECT'.
     statement.

     If you use 'INSERT IGNORE' and the row is ignored,
     the 'LAST_INSERT_ID()' remains unchanged from the current value (or
     0 is returned if the connection has not yet performed a successful
     'INSERT') and, for non-transactional tables, the 'AUTO_INCREMENT'
     counter is not incremented.  For 'InnoDB' tables, the
     'AUTO_INCREMENT' counter is incremented if
     'innodb_autoinc_lock_mode' is set to '1' or '2', as demonstrated in
     the following example:

          mysql> USE test;

          mysql> SELECT @@innodb_autoinc_lock_mode;
          +----------------------------+
          | @@innodb_autoinc_lock_mode |
          +----------------------------+
          |                          1 |
          +----------------------------+

          mysql> CREATE TABLE `t` (
                 `id` INT(11) NOT NULL AUTO_INCREMENT,
                 `val` INT(11) DEFAULT NULL,
                 PRIMARY KEY (`id`),
                 UNIQUE KEY `i1` (`val`)
                 ) ENGINE=InnoDB DEFAULT CHARSET=latin1;

          # Insert two rows

          mysql> INSERT INTO t (val) VALUES (1),(2);

          # With auto_increment_offset=1, the inserted rows
          # result in an AUTO_INCREMENT value of 3

          mysql> SHOW CREATE TABLE t\G
          *************************** 1. row ***************************
                 Table: t
          Create Table: CREATE TABLE `t` (
            `id` int(11) NOT NULL AUTO_INCREMENT,
            `val` int(11) DEFAULT NULL,
            PRIMARY KEY (`id`),
            UNIQUE KEY `i1` (`val`)
          ) ENGINE=InnoDB AUTO_INCREMENT=3 DEFAULT CHARSET=latin1

          # LAST_INSERT_ID() returns the first automatically generated
          # value that is successfully inserted for the AUTO_INCREMENT column

          mysql> SELECT LAST_INSERT_ID();
          +------------------+
          | LAST_INSERT_ID() |
          +------------------+
          |                1 |
          +------------------+

          # The attempted insertion of duplicate rows fail but errors are ignored

          mysql> INSERT IGNORE INTO t (val) VALUES (1),(2);
          Query OK, 0 rows affected (0.00 sec)
          Records: 2  Duplicates: 2  Warnings: 0

          # With innodb_autoinc_lock_mode=1, the AUTO_INCREMENT counter
          # is incremented for the ignored rows

          mysql> SHOW CREATE TABLE t\G
          *************************** 1. row ***************************
                 Table: t
          Create Table: CREATE TABLE `t` (
            `id` int(11) NOT NULL AUTO_INCREMENT,
            `val` int(11) DEFAULT NULL,
            PRIMARY KEY (`id`),
            UNIQUE KEY `i1` (`val`)
          ) ENGINE=InnoDB AUTO_INCREMENT=5 DEFAULT CHARSET=latin1

          # The LAST_INSERT_ID is unchanged because the previous insert was unsuccessful

          mysql> SELECT LAST_INSERT_ID();
          +------------------+
          | LAST_INSERT_ID() |
          +------------------+
          |                1 |
          +------------------+

     For more information, see innodb-auto-increment-handling.

     If EXPR is given as an argument to 'LAST_INSERT_ID()', the value of
     the argument is returned by the function and is remembered as the
     next value to be returned by 'LAST_INSERT_ID()'.  This can be used
     to simulate sequences:

       1. Create a table to hold the sequence counter and initialize it:

               mysql> CREATE TABLE sequence (id INT NOT NULL);
               mysql> INSERT INTO sequence VALUES (0);

       2. Use the table to generate sequence numbers like this:

               mysql> UPDATE sequence SET id=LAST_INSERT_ID(id+1);
               mysql> SELECT LAST_INSERT_ID();

          The 'UPDATE' statement increments the sequence
          counter and causes the next call to 'LAST_INSERT_ID()' to
          return the updated value.  The 'SELECT'.
          statement retrieves that value.  The
          'mysql_insert_id()'. C API function can also
          be used to get the value.  See mysql-insert-id.

     You can generate sequences without calling 'LAST_INSERT_ID()', but
     the utility of using the function this way is that the ID value is
     maintained in the server as the last automatically generated value.
     It is multi-user safe because multiple clients can issue the
     'UPDATE' statement and get their own sequence value with
     the 'SELECT' statement (or
     'mysql_insert_id()'), without affecting or being
     affected by other clients that generate their own sequence values.

     Note that 'mysql_insert_id()' is only
     updated after 'INSERT' and 'UPDATE'.
     statements, so you cannot use the C API function to retrieve the
     value for 'LAST_INSERT_ID(EXPR)' after executing other SQL
     statements like 'SELECT' or 'SET'.

   *
     'ROW_COUNT()'

     'ROW_COUNT()' returns a value as follows:

        * DDL statements: 0.  This applies to statements such as
          'CREATE TABLE' or 'DROP TABLE'.

        * DML statements other than 'SELECT'.: The number
          of affected rows.  This applies to statements such as
          'UPDATE', 'INSERT', or 'DELETE'.
          (as before), but now also to statements such as
          'ALTER TABLE' and 'LOAD DATA INFILE'.

        * 'SELECT'.: -1 if the statement returns a result
          set, or the number of rows 'affected' if it does not.  For
          example, for 'SELECT * FROM t1', 'ROW_COUNT()' returns -1.
          For 'SELECT * FROM t1 INTO OUTFILE 'FILE_NAME'', 'ROW_COUNT()'
          returns the number of rows written to the file.

        * 'SIGNAL' statements: 0.

     For 'UPDATE' statements, the affected-rows value by
     default is the number of rows actually changed.  If you specify the
     'CLIENT_FOUND_ROWS' flag to 'mysql_real_connect()'
     when connecting to 'mysqld', the
     affected-rows value is the number of rows 'found'; that is, matched
     by the 'WHERE' clause.

     For 'REPLACE' statements, the affected-rows value
     is 2 if the new row replaced an old row, because in this case, one
     row was inserted after the duplicate was deleted.

     For 'INSERT ... ON DUPLICATE KEY UPDATE'
     statements, the affected-rows value per row is
     1 if the row is inserted as a new row, 2 if an existing row is
     updated, and 0 if an existing row is set to its current values.  If
     you specify the 'CLIENT_FOUND_ROWS' flag, the affected-rows value
     is 1 (not 0) if an existing row is set to its current values.

     The 'ROW_COUNT()' value is similar to the value from the
     'mysql_affected_rows()'. C API function and
     the row count that the 'mysql' client displays
     following statement execution.

          mysql> INSERT INTO t VALUES(1),(2),(3);
          Query OK, 3 rows affected (0.00 sec)
          Records: 3  Duplicates: 0  Warnings: 0

          mysql> SELECT ROW_COUNT();
          +-------------+
          | ROW_COUNT() |
          +-------------+
          |           3 |
          +-------------+
          1 row in set (0.00 sec)

          mysql> DELETE FROM t WHERE i IN(1,2);
          Query OK, 2 rows affected (0.00 sec)

          mysql> SELECT ROW_COUNT();
          +-------------+
          | ROW_COUNT() |
          +-------------+
          |           2 |
          +-------------+
          1 row in set (0.00 sec)

     *Important*:

     'ROW_COUNT()' is not replicated reliably using statement-based
     replication.  This function is automatically replicated using
     row-based replication.

   *
     'SCHEMA()'

     This function is a synonym for 'DATABASE()'.

   *
     'SESSION_USER()'

     'SESSION_USER()' is a synonym for 'USER()'.

   *
     'SYSTEM_USER()'

     'SYSTEM_USER()' is a synonym for 'USER()'.

   *
     'USER()'

     Returns the current MySQL user name and host name as a string in
     the 'utf8' character set.

          mysql> SELECT USER();
                  -> 'davida@localhost'

     The value indicates the user name you specified when connecting to
     the server, and the client host from which you connected.  The
     value can be different from that of 'CURRENT_USER()'.

   *
     'VERSION()'

     Returns a string that indicates the MySQL server version.  The
     string uses the 'utf8' character set.  The value might have a
     suffix in addition to the version number.  See the description of
     the 'version' system variable in server-system-variables.

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

          mysql> SELECT VERSION();
                  -> '5.7.23-standard'

12.15 Spatial Analysis Functions
================================

MySQL provides functions to perform various operations on spatial data.
These functions can be grouped into several major categories according
to the type of operation they perform:

   * Functions that create geometries in various formats (WKT, WKB,
     internal)

   * Functions that convert geometries between formats

   * Functions that access qualitative or quantitative properties of a
     geometry

   * Functions that describe relations between two geometries

   * Functions that create new geometries from existing ones

For general background about MySQL support for using spatial data, see
spatial-types.

12.15.1 Spatial Function Reference
----------------------------------

The following table lists each spatial function and provides a short
description of each one.

*Spatial Functions*

Name                          Description

'Area()' (deprecated 5.7.6)   Return Polygon or MultiPolygon area

'AsBinary()', 'AsWKB()'       Convert from internal geometry format to
(deprecated 5.7.6)            WKB

'AsText()', 'AsWKT()'         Convert from internal geometry format to
(deprecated 5.7.6)            WKT

'Buffer()' (deprecated        Return geometry of points within given
5.7.6)                        distance from geometry

'Centroid()' (deprecated      Return centroid as a point
5.7.6)

'Contains()' (deprecated      Whether MBR of one geometry contains MBR
5.7.6)                        of another

'ConvexHull()' (deprecated    Return convex hull of geometry
5.7.6)

'Crosses()' (deprecated       Whether one geometry crosses another
5.7.6)

'Dimension()' (deprecated     Dimension of geometry
5.7.6)

'Disjoint()' (deprecated      Whether MBRs of two geometries are
5.7.6)                        disjoint

'Distance()' (deprecated      The distance of one geometry from another
5.7.6)

'EndPoint()' (deprecated      End Point of LineString
5.7.6)

'Envelope()' (deprecated      Return MBR of geometry
5.7.6)

'Equals()' (deprecated        Whether MBRs of two geometries are equal
5.7.6)

'ExteriorRing()'              Return exterior ring of Polygon
(deprecated 5.7.6)

'GeomCollFromText()',         Return geometry collection from WKT
'GeometryCollectionFromText()'
(deprecated 5.7.6)

'GeomCollFromWKB()',          Return geometry collection from WKB
'GeometryCollectionFromWKB()'
(deprecated 5.7.6)

'GeometryCollection()'        Construct geometry collection from
                              geometries

'GeometryN()' (deprecated     Return N-th geometry from geometry
5.7.6)                        collection

'GeometryType()'              Return name of geometry type
(deprecated 5.7.6)

'GeomFromText()',             Return geometry from WKT
'GeometryFromText()'
(deprecated 5.7.6)

'GeomFromWKB()',              Return geometry from WKB
'GeometryFromWKB()'
(deprecated 5.7.6)

'GLength()' (deprecated       Return length of LineString
5.7.6)

'InteriorRingN()'             Return N-th interior ring of Polygon
(deprecated 5.7.6)

'Intersects()' (deprecated    Whether MBRs of two geometries intersect
5.7.6)

'IsClosed()' (deprecated      Whether a geometry is closed and simple
5.7.6)

'IsEmpty()' (deprecated       Placeholder function
5.7.6)

'IsSimple()' (deprecated      Whether a geometry is simple
5.7.6)

'LineFromText()',             Construct LineString from WKT
'LineStringFromText()'
(deprecated 5.7.6)

'LineFromWKB()',              Construct LineString from WKB
'LineStringFromWKB()'
(deprecated 5.7.6)

'LineString()'                Construct LineString from Point values

'MBRContains()'               Whether MBR of one geometry contains MBR
                              of another

'MBRCoveredBy()'              Whether one MBR is covered by another

'MBRCovers()'                 Whether one MBR covers another

'MBRDisjoint()'               Whether MBRs of two geometries are
                              disjoint

'MBREqual()' (deprecated      Whether MBRs of two geometries are equal
5.7.6)

'MBREquals()'                 Whether MBRs of two geometries are equal

'MBRIntersects()'             Whether MBRs of two geometries intersect

'MBROverlaps()'               Whether MBRs of two geometries overlap

'MBRTouches()'                Whether MBRs of two geometries touch

'MBRWithin()'                 Whether MBR of one geometry is within MBR
                              of another

'MLineFromText()',            Construct MultiLineString from WKT
'MultiLineStringFromText()'
(deprecated 5.7.6)

'MLineFromWKB()',             Construct MultiLineString from WKB
'MultiLineStringFromWKB()'
(deprecated 5.7.6)

'MPointFromText()',           Construct MultiPoint from WKT
'MultiPointFromText()'
(deprecated 5.7.6)

'MPointFromWKB()',            Construct MultiPoint from WKB
'MultiPointFromWKB()'
(deprecated 5.7.6)

'MPolyFromText()',            Construct MultiPolygon from WKT
'MultiPolygonFromText()'
(deprecated 5.7.6)

'MPolyFromWKB()',             Construct MultiPolygon from WKB
'MultiPolygonFromWKB()'
(deprecated 5.7.6)

'MultiLineString()'           Contruct MultiLineString from LineString
                              values

'MultiPoint()'                Construct MultiPoint from Point values

'MultiPolygon()'              Construct MultiPolygon from Polygon
                              values

'NumGeometries()'             Return number of geometries in geometry
(deprecated 5.7.6)            collection

'NumInteriorRings()'          Return number of interior rings in
(deprecated 5.7.6)            Polygon

'NumPoints()' (deprecated     Return number of points in LineString
5.7.6)

'Overlaps()' (deprecated      Whether MBRs of two geometries overlap
5.7.6)

'Point()'                     Construct Point from coordinates

'PointFromText()'             Construct Point from WKT
(deprecated 5.7.6)

'PointFromWKB()'              Construct Point from WKB
(deprecated 5.7.6)

'PointN()' (deprecated        Return N-th point from LineString
5.7.6)

'PolyFromText()',             Construct Polygon from WKT
'PolygonFromText()'
(deprecated 5.7.6)

'PolyFromWKB()',              Construct Polygon from WKB
'PolygonFromWKB()'
(deprecated 5.7.6)

'Polygon()'                   Construct Polygon from LineString
                              arguments

'SRID()' (deprecated 5.7.6)   Return spatial reference system ID for
                              geometry

'ST_Area()'                   Return Polygon or MultiPolygon area

'ST_AsBinary()',              Convert from internal geometry format to
'ST_AsWKB()'                  WKB

'ST_AsGeoJSON()'              Generate GeoJSON object from geometry

'ST_AsText()', 'ST_AsWKT()'   Convert from internal geometry format to
                              WKT

'ST_Buffer()'                 Return geometry of points within given
                              distance from geometry

'ST_Buffer_Strategy()'        Produce strategy option for ST_Buffer()

'ST_Centroid()'               Return centroid as a point

'ST_Contains()'               Whether one geometry contains another

'ST_ConvexHull()'             Return convex hull of geometry

'ST_Crosses()'                Whether one geometry crosses another

'ST_Difference()'             Return point set difference of two
                              geometries

'ST_Dimension()'              Dimension of geometry

'ST_Disjoint()'               Whether one geometry is disjoint from
                              another

'ST_Distance()'               The distance of one geometry from another

'ST_Distance_Sphere()'        Minimum distance on earth between two
                              geometries

'ST_EndPoint()'               End Point of LineString

'ST_Envelope()'               Return MBR of geometry

'ST_Equals()'                 Whether one geometry is equal to another

'ST_ExteriorRing()'           Return exterior ring of Polygon

'ST_GeoHash()'                Produce a geohash value

'ST_GeomCollFromText()',      Return geometry collection from WKT
'ST_GeometryCollectionFromText()',
'ST_GeomCollFromTxt()'

'ST_GeomCollFromWKB()',       Return geometry collection from WKB
'ST_GeometryCollectionFromWKB()'

'ST_GeometryN()'              Return N-th geometry from geometry
                              collection

'ST_GeometryType()'           Return name of geometry type

'ST_GeomFromGeoJSON()'        Generate geometry from GeoJSON object

'ST_GeomFromText()',          Return geometry from WKT
'ST_GeometryFromText()'

'ST_GeomFromWKB()',           Return geometry from WKB
'ST_GeometryFromWKB()'

'ST_InteriorRingN()'          Return N-th interior ring of Polygon

'ST_Intersection()'           Return point set intersection of two
                              geometries

'ST_Intersects()'             Whether one geometry intersects another

'ST_IsClosed()'               Whether a geometry is closed and simple

'ST_IsEmpty()'                Placeholder function

'ST_IsSimple()'               Whether a geometry is simple

'ST_IsValid()'                Whether a geometry is valid

'ST_LatFromGeoHash()'         Return latitude from geohash value

'ST_Length()'                 Return length of LineString

'ST_LineFromText()',          Construct LineString from WKT
'ST_LineStringFromText()'

'ST_LineFromWKB()',           Construct LineString from WKB
'ST_LineStringFromWKB()'

'ST_LongFromGeoHash()'        Return longitude from geohash value

'ST_MakeEnvelope()'           Rectangle around two points

'ST_MLineFromText()',         Construct MultiLineString from WKT
'ST_MultiLineStringFromText()'

'ST_MLineFromWKB()',          Construct MultiLineString from WKB
'ST_MultiLineStringFromWKB()'

'ST_MPointFromText()',        Construct MultiPoint from WKT
'ST_MultiPointFromText()'

'ST_MPointFromWKB()',         Construct MultiPoint from WKB
'ST_MultiPointFromWKB()'

'ST_MPolyFromText()',         Construct MultiPolygon from WKT
'ST_MultiPolygonFromText()'

'ST_MPolyFromWKB()',          Construct MultiPolygon from WKB
'ST_MultiPolygonFromWKB()'

'ST_NumGeometries()'          Return number of geometries in geometry
                              collection

'ST_NumInteriorRing()',       Return number of interior rings in
'ST_NumInteriorRings()'       Polygon

'ST_NumPoints()'              Return number of points in LineString

'ST_Overlaps()'               Whether one geometry overlaps another

'ST_PointFromGeoHash()'       Convert geohash value to POINT value

'ST_PointFromText()'          Construct Point from WKT

'ST_PointFromWKB()'           Construct Point from WKB

'ST_PointN()'                 Return N-th point from LineString

'ST_PolyFromText()',          Construct Polygon from WKT
'ST_PolygonFromText()'

'ST_PolyFromWKB()',           Construct Polygon from WKB
'ST_PolygonFromWKB()'

'ST_Simplify()'               Return simplified geometry

'ST_SRID()'                   Return spatial reference system ID for
                              geometry

'ST_StartPoint()'             Start Point of LineString

'ST_SymDifference()'          Return point set symmetric difference of
                              two geometries

'ST_Touches()'                Whether one geometry touches another

'ST_Union()'                  Return point set union of two geometries

'ST_Validate()'               Return validated geometry

'ST_Within()'                 Whether one geometry is within another

'ST_X()'                      Return X coordinate of Point

'ST_Y()'                      Return Y coordinate of Point

'StartPoint()' (deprecated    Start Point of LineString
5.7.6)

'Touches()' (deprecated       Whether one geometry touches another
5.7.6)

'Within()' (deprecated        Whether MBR of one geometry is within MBR
5.7.6)                        of another

'X()' (deprecated 5.7.6)      Return X coordinate of Point

'Y()' (deprecated 5.7.6)      Return Y coordinate of Point

12.15.2 Argument Handling by Spatial Functions
----------------------------------------------

Spatial values, or geometries, have the properties described at
gis-class-geometry.  The following discussion lists general spatial
function argument-handling characteristics.  Specific functions or
groups of functions may have additional argument-handling
characteristics, as discussed in the sections where those function
descriptions occur.

Spatial functions are defined only for valid geometry values.

The spatial reference identifier (SRID) of a geometry identifies the
coordinate space in which the geometry is defined.  In MySQL, the SRID
value is an integer associated with the geometry value.  The maximum
usable SRID value is 2^32−1.  If a larger value is given, only the
lower 32 bits are used.

In MySQL, all computations are done assuming SRID 0, regardless of the
actual SRID value.  SRID 0 represents an infinite flat Cartesian plane
with no units assigned to its axes.  In the future, computations may use
the specified SRID values.  To ensure SRID 0 behavior, create geometry
values using SRID 0.  SRID 0 is the default for new geometry values if
no SRID is specified.

Geometry values produced by any spatial function inherit the SRID of the
geometry arguments.

Spatial functions that take multiple geometry arguments require those
arguments to have the same SRID value (that is, same value in the lower
32 bits).  Assuming equal SRIDs, spatial functions do nothing with them
after performing the equality check; geometry values are implicitly
handled using Cartesian coordinates (SRID 0).  If a spatial function
returns 'ER_GIS_DIFFERENT_SRIDS', it means that the geometry arguments
did not all have the same SRID. You must modify them to have the same
SRID.

The Open Geospatial Consortium guidelines require that input polygons
already be closed, so unclosed polygons are rejected as invalid rather
than being closed.

Empty geometry-collection handling is as follows: An empty WKT input
geometry collection may be specified as ''GEOMETRYCOLLECTION()''.  This
is also the output WKT resulting from a spatial operation that produces
an empty geometry collection.

During parsing of a nested geometry collection, the collection is
flattened and its basic components are used in various GIS operations to
compute results.  This provides additional flexibility to users because
it is unnecessary to be concerned about the uniqueness of geometry data.
Nested geometry collections may be produced from nested GIS function
calls without having to be explicitly flattened first.

12.15.3 Functions That Create Geometry Values from WKT Values
-------------------------------------------------------------

These functions take as arguments a Well-Known Text (WKT) representation
and, optionally, a spatial reference system identifier (SRID). They
return the corresponding geometry.

'ST_GeomFromText()' accepts a WKT value of any geometry type as its
first argument.  Other functions provide type-specific construction
functions for construction of geometry values of each geometry type.

For a description of WKT format, see gis-wkt-format.

   *
     'GeomCollFromText(WKT[, SRID])', 'GeometryCollectionFromText(WKT[,
     SRID])'

     'ST_GeomCollFromText()', 'ST_GeometryCollectionFromText()',
     'ST_GeomCollFromTxt()', 'GeomCollFromText()', and
     'GeometryCollectionFromText()' are synonyms.  For more information,
     see the description of 'ST_GeomCollFromText()'.

     'GeomCollFromText()' and 'GeometryCollectionFromText()' are
     deprecated as of MySQL 5.7.6 and will be removed in a future MySQL
     release.  Use 'ST_GeomCollFromText()' and
     'ST_GeometryCollectionFromText()' instead.

   *
     'GeomFromText(WKT[, SRID])', 'GeometryFromText(WKT[, SRID])'

     'ST_GeomFromText()', 'ST_GeometryFromText()', 'GeomFromText()', and
     'GeometryFromText()' are synonyms.  For more information, see the
     description of 'ST_GeomFromText()'.

     'GeomFromText()' and 'GeometryFromText()' are deprecated as of
     MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_GeomFromText()' and 'ST_GeometryFromText()' instead.

   *
     'LineFromText(WKT[, SRID])', 'LineStringFromText(WKT[, SRID])'

     'ST_LineFromText()', 'ST_LineStringFromText()', 'LineFromText()',
     and 'LineStringFromText()' are synonyms.  For more information, see
     the description of 'ST_LineFromText()'.

     'LineFromText()' and 'LineStringFromText()' are deprecated as of
     MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_LineFromText()' and 'ST_LineStringFromText()' instead.

   *
     'MLineFromText(WKT[, SRID])', 'MultiLineStringFromText(WKT[,
     SRID])'

     'ST_MLineFromText()', 'ST_MultiLineStringFromText()',
     'MLineFromText()', and 'MultiLineStringFromText()' are synonyms.
     For more information, see the description of 'ST_MLineFromText()'.

     'MLineFromText()' and 'MultiLineStringFromText()' are deprecated as
     of MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_MLineFromText()' and 'ST_MultiLineStringFromText()' instead.

   *
     'MPointFromText(WKT[, SRID])', 'MultiPointFromText(WKT[, SRID])'

     'ST_MPointFromText()', 'ST_MultiPointFromText()',
     'MPointFromText()', and 'MultiPointFromText()' are synonyms.  For
     more information, see the description of 'ST_MPointFromText()'.

     'MPointFromText()' and 'MultiPointFromText()' are deprecated as of
     MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_MPointFromText()' and 'ST_MultiPointFromText()' instead.

   *
     'MPolyFromText(WKT[, SRID])', 'MultiPolygonFromText(WKT[, SRID])'

     'ST_MPolyFromText()', 'ST_MultiPolygonFromText()',
     'MPolyFromText()', and 'MultiPolygonFromText()' are synonyms.  For
     more information, see the description of 'ST_MPolyFromText()'.

     'MPolyFromText()' and 'MultiPolygonFromText()' are deprecated as of
     MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_MPolyFromText()' and 'ST_MultiPolygonFromText()' instead.

   *
     'PointFromText(WKT[, SRID])'

     'ST_PointFromText()' and 'PointFromText()' are synonyms.  For more
     information, see the description of 'ST_PointFromText()'.

     'PointFromText()' is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.  Use 'ST_PointFromText()'
     instead.

   *
     'PolyFromText(WKT[, SRID])', 'PolygonFromText(WKT[, SRID])'

     'ST_PolyFromText()', 'ST_PolygonFromText()', 'PolyFromText()', and
     'PolygonFromText()' are synonyms.  For more information, see the
     description of 'ST_PolyFromText()'.

     'PolyFromText()' and 'PolygonFromText()' are deprecated as of MySQL
     5.7.6 and will be removed in a future MySQL release.  Use
     'ST_PolyFromText()' and 'ST_PolygonFromText()' instead.

   *
     'ST_GeomCollFromText(WKT[, SRID])',
     'ST_GeometryCollectionFromText(WKT[, SRID])',
     'ST_GeomCollFromTxt(WKT[, SRID])'

     Constructs a 'GeometryCollection' value using its WKT
     representation and SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

          mysql> SET @g = "MULTILINESTRING((10 10, 11 11), (9 9, 10 10))";
          mysql> SELECT ST_AsText(ST_GeomCollFromText(@g));
          +--------------------------------------------+
          | ST_AsText(ST_GeomCollFromText(@g))         |
          +--------------------------------------------+
          | MULTILINESTRING((10 10,11 11),(9 9,10 10)) |
          +--------------------------------------------+

     'ST_GeomCollFromText()', 'ST_GeometryCollectionFromText()',
     'ST_GeomCollFromTxt()', 'GeomCollFromText()', and
     'GeometryCollectionFromText()' are synonyms.
     'ST_GeomCollFromTxt()' was added in MySQL 5.7.6.

   *
     'ST_GeomFromText(WKT[, SRID])', 'ST_GeometryFromText(WKT[, SRID])'

     Constructs a geometry value of any type using its WKT
     representation and SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

     'ST_GeomFromText()', 'ST_GeometryFromText()', 'GeomFromText()', and
     'GeometryFromText()' are synonyms.

   *
     'ST_LineFromText(WKT[, SRID])', 'ST_LineStringFromText(WKT[,
     SRID])'

     Constructs a 'LineString' value using its WKT representation and
     SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

     'ST_LineFromText()', 'ST_LineStringFromText()', 'LineFromText()',
     and 'LineStringFromText()' are synonyms.

   *
     'ST_MLineFromText(WKT[, SRID])', 'ST_MultiLineStringFromText(WKT[,
     SRID])'

     Constructs a 'MultiLineString' value using its WKT representation
     and SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

     'ST_MLineFromText()', 'ST_MultiLineStringFromText()',
     'MLineFromText()', and 'MultiLineStringFromText()' are synonyms.

     'ST_MLineFromText()' and 'ST_MultiLineStringFromText()' were added
     in MySQL 5.7.6.

   *
     'ST_MPointFromText(WKT[, SRID])', 'ST_MultiPointFromText(WKT[,
     SRID])'

     Constructs a 'MultiPoint' value using its WKT representation and
     SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

     As of MySQL 5.7.9, spatial functions such as 'ST_MPointFromText()'
     and 'ST_GeomFromText()' that accept WKT-format representations of
     'MultiPoint' values permit individual points within values to be
     surrounded by parentheses.  For example, both of the following
     function calls are valid, whereas before MySQL 5.7.9 the second one
     produces an error:

          ST_MPointFromText('MULTIPOINT (1 1, 2 2, 3 3)')
          ST_MPointFromText('MULTIPOINT ((1 1), (2 2), (3 3))')

     'ST_MPointFromText()', 'ST_MultiPointFromText()',
     'MPointFromText()', and 'MultiPointFromText()' are synonyms.

     'ST_MPointFromText()' and 'ST_MultiPointFromText()' were added in
     MySQL 5.7.6.

   *
     'ST_MPolyFromText(WKT[, SRID])', 'ST_MultiPolygonFromText(WKT[,
     SRID])'

     Constructs a 'MultiPolygon' value using its WKT representation and
     SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

     'ST_MPolyFromText()', 'ST_MultiPolygonFromText()',
     'MPolyFromText()', and 'MultiPolygonFromText()' are synonyms.

     'ST_MPolyFromText()' and 'ST_MultiPolygonFromText()' were added in
     MySQL 5.7.6.

   *
     'ST_PointFromText(WKT[, SRID])'

     Constructs a 'Point' value using its WKT representation and SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

     'ST_PointFromText()' and 'PointFromText()' are synonyms.

   *
     'ST_PolyFromText(WKT[, SRID])', 'ST_PolygonFromText(WKT[, SRID])'

     Constructs a 'Polygon' value using its WKT representation and SRID.

     If the geometry argument is 'NULL' or not a syntactically
     well-formed geometry, or if the SRID argument is 'NULL', the return
     value is 'NULL'.

     'ST_PolyFromText()', 'ST_PolygonFromText()', 'PolyFromText()', and
     'PolygonFromText()' are synonyms.

12.15.4 Functions That Create Geometry Values from WKB Values
-------------------------------------------------------------

These functions take as arguments a 'BLOB' containing a
Well-Known Binary (WKB) representation and, optionally, a spatial
reference system identifier (SRID). They return the corresponding
geometry.

'ST_GeomFromWKB()' accepts a WKB value of any geometry type as its first
argument.  Other functions provide type-specific construction functions
for construction of geometry values of each geometry type.

These functions also accept geometry objects as returned by the
functions in gis-mysql-specific-functions.  Thus, those
functions may be used to provide the first argument to the functions in
this section.  However, as of MySQL 5.7.19, use of geometry arguments is
deprecated and generates a warning.  Geometry arguments are not accepted
in MySQL 8.0.  To migrate calls from using geometry arguments to using
WKB arguments, follow these guidelines:

For a description of WKB format, see gis-wkb-format.

   * Rewrite constructs such as 'ST_GeomFromWKB(Point(0, 0))' as
     'Point(0, 0)'.

   * Rewrite constructs such as 'ST_GeomFromWKB(Point(0, 0), 4326)' as
     'ST_GeomFromWKB(ST_AsWKB(Point(0, 0)), 4326)'.  (Alternatively, in
     MySQL 8.0, you can use 'ST_SRID(Point(0, 0), 4326)'.)

   *
     'GeomCollFromWKB(WKB[, SRID])', 'GeometryCollectionFromWKB(WKB[,
     SRID])'

     'ST_GeomCollFromWKB()', 'ST_GeometryCollectionFromWKB()',
     'GeomCollFromWKB()', and 'GeometryCollectionFromWKB()' are
     synonyms.  For more information, see the description of
     'ST_GeomCollFromWKB()'.

     'GeomCollFromWKB()' and 'GeometryCollectionFromWKB()' are
     deprecated as of MySQL 5.7.6 and will be removed in a future MySQL
     release.  Use 'ST_GeomCollFromWKB()' and
     'ST_GeometryCollectionFromWKB()' instead.

   *
     'GeomFromWKB(WKB[, SRID])', 'GeometryFromWKB(WKB[, SRID])'

     'ST_GeomFromWKB()', 'ST_GeometryFromWKB()', 'GeomFromWKB()', and
     'GeometryFromWKB()' are synonyms.  For more information, see the
     description of 'ST_GeomFromWKB()'.

     'GeomFromWKB()' and 'GeometryFromWKB()' are deprecated as of MySQL
     5.7.6 and will be removed in a future MySQL release.  Use
     'ST_GeomFromWKB()' and 'ST_GeometryFromWKB()' instead.

   *
     'LineFromWKB(WKB[, SRID])', 'LineStringFromWKB(WKB[, SRID])'

     'ST_LineFromWKB()', 'ST_LineStringFromWKB()', 'LineFromWKB()', and
     'LineStringFromWKB()' are synonyms.  For more information, see the
     description of 'ST_LineFromWKB()'.

     'LineFromWKB()' and 'LineStringFromWKB()' are deprecated as of
     MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_LineFromWKB()' and 'ST_LineStringFromWKB()' instead.

   *
     'MLineFromWKB(WKB[, SRID])', 'MultiLineStringFromWKB(WKB[, SRID])'

     'ST_MLineFromWKB()', 'ST_MultiLineStringFromWKB()',
     'MLineFromWKB()', and 'MultiLineStringFromWKB()' are synonyms.  For
     more information, see the description of 'ST_MLineFromWKB()'.

     'MLineFromWKB()' and 'MultiLineStringFromWKB()' are deprecated as
     of MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_MLineFromWKB()' and 'ST_MultiLineStringFromWKB()' instead.

   *
     'MPointFromWKB(WKB[, SRID])', 'MultiPointFromWKB(WKB[, SRID])'

     'ST_MPointFromWKB()', 'ST_MultiPointFromWKB()', 'MPointFromWKB()',
     and 'MultiPointFromWKB()' are synonyms.  For more information, see
     the description of 'ST_MPointFromWKB()'.

     'MPointFromWKB()' and 'MultiPointFromWKB()' are deprecated as of
     MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_MPointFromWKB()' and 'ST_MultiPointFromWKB()' instead.

   *
     'MPolyFromWKB(WKB[, SRID])', 'MultiPolygonFromWKB(WKB[, SRID])'

     'ST_MPolyFromWKB()', 'ST_MultiPolygonFromWKB()', 'MPolyFromWKB()',
     and 'MultiPolygonFromWKB()' are synonyms.  For more information,
     see the description of 'ST_MPolyFromWKB()'.

     'MPolyFromWKB()' and 'MultiPolygonFromWKB()' are deprecated as of
     MySQL 5.7.6 and will be removed in a future MySQL release.  Use
     'ST_MPolyFromWKB()' and 'ST_MultiPolygonFromWKB()' instead.

   *
     'PointFromWKB(WKB[, SRID])'

     'ST_PointFromWKB()' and 'PointFromWKB()' are synonyms.  For more
     information, see the description of 'ST_PointFromWKB()'.

     'PointFromWKB()' is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.  Use 'ST_PointFromWKB()'
     instead.

   *
     'PolyFromWKB(WKB[, SRID])', 'PolygonFromWKB(WKB[, SRID])'

     'ST_PolyFromWKB()', 'ST_PolygonFromWKB()', 'PolyFromWKB()', and
     'PolygonFromWKB()' are synonyms.  For more information, see the
     description of 'ST_PolyFromWKB()'.

     'PolyFromWKB()' and 'PolygonFromWKB()' are deprecated as of MySQL
     5.7.6 and will be removed in a future MySQL release.  Use
     'ST_PolyFromWKB()' and 'ST_PolygonFromWKB()' instead.

   *
     'ST_GeomCollFromWKB(WKB[, SRID])',
     'ST_GeometryCollectionFromWKB(WKB[, SRID])'

     Constructs a 'GeometryCollection' value using its WKB
     representation and SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_GeomCollFromWKB()', 'ST_GeometryCollectionFromWKB()',
     'GeomCollFromWKB()', and 'GeometryCollectionFromWKB()' are
     synonyms.

   *
     'ST_GeomFromWKB(WKB[, SRID])', 'ST_GeometryFromWKB(WKB[, SRID])'

     Constructs a geometry value of any type using its WKB
     representation and SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_GeomFromWKB()', 'ST_GeometryFromWKB()', 'GeomFromWKB()', and
     'GeometryFromWKB()' are synonyms.

   *
     'ST_LineFromWKB(WKB[, SRID])', 'ST_LineStringFromWKB(WKB[, SRID])'

     Constructs a 'LineString' value using its WKB representation and
     SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_LineFromWKB()', 'ST_LineStringFromWKB()', 'LineFromWKB()', and
     'LineStringFromWKB()' are synonyms.

   *
     'ST_MLineFromWKB(WKB[, SRID])', 'ST_MultiLineStringFromWKB(WKB[,
     SRID])'

     Constructs a 'MultiLineString' value using its WKB representation
     and SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_MLineFromWKB()', 'ST_MultiLineStringFromWKB()',
     'MLineFromWKB()', and 'MultiLineStringFromWKB()' are synonyms.

     'ST_MLineFromWKB()' and 'ST_MultiLineStringFromWKB()' were added in
     MySQL 5.7.6.

   *
     'ST_MPointFromWKB(WKB[, SRID])', 'ST_MultiPointFromWKB(WKB[,
     SRID])'

     Constructs a 'MultiPoint' value using its WKB representation and
     SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_MPointFromWKB()', 'ST_MultiPointFromWKB()', 'MPointFromWKB()',
     and 'MultiPointFromWKB()' are synonyms.

     'ST_MPointFromWKB()' and 'ST_MultiPointFromWKB()' were added in
     MySQL 5.7.6.

   *
     'ST_MPolyFromWKB(WKB[, SRID])', 'ST_MultiPolygonFromWKB(WKB[,
     SRID])'

     Constructs a 'MultiPolygon' value using its WKB representation and
     SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_MPolyFromWKB()', 'ST_MultiPolygonFromWKB()', 'MPolyFromWKB()',
     and 'MultiPolygonFromWKB()' are synonyms.

     'ST_MPolyFromWKB()' and 'ST_MultiPolygonFromWKB()' were added in
     MySQL 5.7.6.

   *
     'ST_PointFromWKB(WKB[, SRID])'

     Constructs a 'Point' value using its WKB representation and SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_PointFromWKB()' and 'PointFromWKB()' are synonyms.

   *
     'ST_PolyFromWKB(WKB[, SRID])', 'ST_PolygonFromWKB(WKB[, SRID])'

     Constructs a 'Polygon' value using its WKB representation and SRID.

     The result is 'NULL' if the WKB or SRID argument is 'NULL'.

     'ST_PolyFromWKB()', 'ST_PolygonFromWKB()', 'PolyFromWKB()', and
     'PolygonFromWKB()' are synonyms.

12.15.5 MySQL-Specific Functions That Create Geometry Values
------------------------------------------------------------

MySQL provides a set of useful nonstandard functions for creating
geometry values.  The functions described in this section are MySQL
extensions to the OpenGIS specification.

These functions produce geometry objects from either WKB values or
geometry objects as arguments.  If any argument is not a proper WKB or
geometry representation of the proper object type, the return value is
'NULL'.

For example, you can insert the geometry return value from 'Point()'
directly into a 'POINT' column:

     INSERT INTO t1 (pt_col) VALUES(Point(1,2));

   * 'GeometryCollection(G [, G] ...)'

     Constructs a 'GeometryCollection' value from the geometry
     arguments.

     'GeometryCollection()' returns all the proper geometries contained
     in the arguments even if a nonsupported geometry is present.

     'GeometryCollection()' with no arguments is permitted as a way to
     create an empty geometry.

   * 'LineString(PT [, PT] ...)'

     Constructs a 'LineString' value from a number of 'Point' or WKB
     'Point' arguments.  If the number of arguments is less than two,
     the return value is 'NULL'.

   * 'MultiLineString(LS [, LS] ...)'

     Constructs a 'MultiLineString' value using 'LineString' or WKB
     'LineString' arguments.

   * 'MultiPoint(PT [, PT2] ...)'

     Constructs a 'MultiPoint' value using 'Point' or WKB 'Point'
     arguments.

   * 'MultiPolygon(POLY [, POLY] ...)'

     Constructs a 'MultiPolygon' value from a set of 'Polygon' or WKB
     'Polygon' arguments.

   * 'Point(X, Y)'

     Constructs a 'Point' using its coordinates.

   * 'Polygon(LS [, LS] ...)'

     Constructs a 'Polygon' value from a number of 'LineString' or WKB
     'LineString' arguments.  If any argument does not represent a
     'LinearRing' (that is, not a closed and simple 'LineString'), the
     return value is 'NULL'.

12.15.6 Geometry Format Conversion Functions
--------------------------------------------

MySQL supports the functions listed in this section for converting
geometry values from internal geometry format to WKT or WKB format.

There are also functions to convert a string from WKT or WKB format to
internal geometry format.  See gis-wkt-functions, and
gis-wkb-functions.

   * 'AsBinary(G)', 'AsWKB(G)'

     'ST_AsBinary()', 'ST_AsWKB()', 'AsBinary()', and 'AsWKB()' are
     synonyms.  For more information, see the description of
     'ST_AsBinary()'.

     'AsBinary()' and 'AsWKB()' are deprecated as of MySQL 5.7.6 and
     will be removed in a future MySQL release.  Use 'ST_AsBinary()' and
     'ST_AsWKB()' instead.

   * 'AsText(G)', 'AsWKT(G)'

     'ST_AsText()', 'ST_AsWKT()', 'AsText()', and 'AsWKT()' are
     synonyms.  For more information, see the description of
     'ST_AsText()'.

     'AsText()' and 'AsWKT()' are deprecated as of MySQL 5.7.6 and will
     be removed in a future MySQL release.  Use 'ST_AsText()' and
     'ST_AsWKT()' instead.

   * 'ST_AsBinary(G)', 'ST_AsWKB(G)'

     Converts a value in internal geometry format to its WKB
     representation and returns the binary result.

     If the argument is 'NULL', the return value is 'NULL'.  If the
     argument is not a syntactically well-formed geometry, an
     'ER_GIS_INVALID_DATA' error occurs.

          SELECT ST_AsBinary(g) FROM geom;

     'ST_AsBinary()', 'ST_AsWKB()', 'AsBinary()', and 'AsWKB()' are
     synonyms.

   * 'ST_AsText(G)', 'ST_AsWKT(G)'

     Converts a value in internal geometry format to its WKT
     representation and returns the string result.

     If the argument is 'NULL', the return value is 'NULL'.  If the
     argument is not a syntactically well-formed geometry, an
     'ER_GIS_INVALID_DATA' error occurs.

          mysql> SET @g = 'LineString(1 1,2 2,3 3)';
          mysql> SELECT ST_AsText(ST_GeomFromText(@g));
          +--------------------------------+
          | ST_AsText(ST_GeomFromText(@g)) |
          +--------------------------------+
          | LINESTRING(1 1,2 2,3 3)        |
          +--------------------------------+

     'ST_AsText()', 'ST_AsWKT()', 'AsText()', and 'AsWKT()' are
     synonyms.

     As of MySQL 5.7.9, output for 'MultiPoint' values includes
     parentheses around each point.  For example:

          mysql> SET @mp = 'MULTIPOINT(1 1, 2 2, 3 3)';
          mysql> SELECT ST_AsText(ST_GeomFromText(@mp));
          +---------------------------------+
          | ST_AsText(ST_GeomFromText(@mp)) |
          +---------------------------------+
          | MULTIPOINT((1 1),(2 2),(3 3))   |
          +---------------------------------+

     Before MySQL 5.7.9, output for the same value does not include
     parentheses around each point:

          mysql> SET @mp = 'MULTIPOINT(1 1, 2 2, 3 3)';
          mysql> SELECT ST_AsText(ST_GeomFromText(@mp));
          +---------------------------------+
          | ST_AsText(ST_GeomFromText(@mp)) |
          +---------------------------------+
          | MULTIPOINT(1 1,2 2,3 3)         |
          +---------------------------------+

12.15.7 Geometry Property Functions
-----------------------------------

Each function that belongs to this group takes a geometry value as its
argument and returns some quantitative or qualitative property of the
geometry.  Some functions restrict their argument type.  Such functions
return 'NULL' if the argument is of an incorrect geometry type.  For
example, the 'ST_Area()' polygon function returns 'NULL' if the object
type is neither 'Polygon' nor 'MultiPolygon'.

12.15.7.1 General Geometry Property Functions
.............................................

The functions listed in this section do not restrict their argument and
accept a geometry value of any type.

   * 'Dimension(G)'

     'ST_Dimension()' and 'Dimension()' are synonyms.  For more
     information, see the description of 'ST_Dimension()'.

     'Dimension()' is deprecated as of MySQL 5.7.6 and will be removed
     in a future MySQL release.  Use 'ST_Dimension()' instead.

   * 'Envelope(G)'

     'ST_Envelope()' and 'Envelope()' are synonyms.  For more
     information, see the description of 'ST_Envelope()'.

     'Envelope()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_Envelope()' instead.

   * 'GeometryType(G)'

     'ST_GeometryType()' and 'GeometryType()' are synonyms.  For more
     information, see the description of 'ST_GeometryType()'.

     'GeometryType()' is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.  Use 'ST_GeometryType()'
     instead.

   * 'IsEmpty(G)'

     'ST_IsEmpty()' and 'IsEmpty()' are synonyms.  For more information,
     see the description of 'ST_IsEmpty()'.

     'IsEmpty()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_IsEmpty()' instead.

   * 'IsSimple(G)'

     'ST_IsSimple()' and 'IsSimple()' are synonyms.  For more
     information, see the description of 'ST_IsSimple()'.

     'IsSimple()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_IsSimple()' instead.

   * 'SRID(G)'

     'ST_SRID()' and 'SRID()' are synonyms.  For more information, see
     the description of 'ST_SRID()'.

     'SRID()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'ST_SRID()' instead.

   * 'ST_Dimension(G)'

     Returns the inherent dimension of the geometry value G, or 'NULL'
     if the argument is 'NULL'.  The dimension can be −1, 0, 1, or 2.
     The meaning of these values is given in gis-class-geometry.

          mysql> SELECT ST_Dimension(ST_GeomFromText('LineString(1 1,2 2)'));
          +------------------------------------------------------+
          | ST_Dimension(ST_GeomFromText('LineString(1 1,2 2)')) |
          +------------------------------------------------------+
          |                                                    1 |
          +------------------------------------------------------+

     'ST_Dimension()' and 'Dimension()' are synonyms.

   * 'ST_Envelope(G)'

     Returns the minimum bounding rectangle (MBR) for the geometry value
     G, or 'NULL' if the argument is 'NULL'.  The result is returned as
     a 'Polygon' value that is defined by the corner points of the
     bounding box:

          POLYGON((MINX MINY, MAXX MINY, MAXX MAXY, MINX MAXY, MINX MINY))

          mysql> SELECT ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,2 2)')));
          +----------------------------------------------------------------+
          | ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,2 2)'))) |
          +----------------------------------------------------------------+
          | POLYGON((1 1,2 1,2 2,1 2,1 1))                                 |
          +----------------------------------------------------------------+

     As of MySQL 5.7.6, if the argument is a point or a vertical or
     horizontal line segment, 'ST_Envelope()' returns the point or the
     line segment as its MBR rather than returning an invalid polygon:

          mysql> SELECT ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,1 2)')));
          +----------------------------------------------------------------+
          | ST_AsText(ST_Envelope(ST_GeomFromText('LineString(1 1,1 2)'))) |
          +----------------------------------------------------------------+
          | LINESTRING(1 1,1 2)                                            |
          +----------------------------------------------------------------+

     'ST_Envelope()' and 'Envelope()' are synonyms.

   * 'ST_GeometryType(G)'

     Returns a binary string indicating the name of the geometry type of
     which the geometry instance G is a member, or 'NULL' if the
     argument is 'NULL'.  The name corresponds to one of the
     instantiable 'Geometry' subclasses.

          mysql> SELECT ST_GeometryType(ST_GeomFromText('POINT(1 1)'));
          +------------------------------------------------+
          | ST_GeometryType(ST_GeomFromText('POINT(1 1)')) |
          +------------------------------------------------+
          | POINT                                          |
          +------------------------------------------------+

     'ST_GeometryType()' and 'GeometryType()' are synonyms.

   * 'ST_IsEmpty(G)'

     This function is a placeholder that returns 0 for any valid
     geometry value, 1 for any invalid geometry value, or 'NULL' if the
     argument is 'NULL'.

     MySQL does not support GIS 'EMPTY' values such as 'POINT EMPTY'.

     'ST_IsEmpty()' and 'IsEmpty()' are synonyms.

   * 'ST_IsSimple(G)'

     Returns 1 if the geometry value G has no anomalous geometric
     points, such as self-intersection or self-tangency.
     'ST_IsSimple()' returns 0 if the argument is not simple, and 'NULL'
     if the argument is 'NULL'.

     The descriptions of the instantiable geometric classes given under
     opengis-geometry-model includes the specific conditions
     that cause class instances to be classified as not simple.

     'ST_IsSimple()' and 'IsSimple()' are synonyms.

   * 'ST_SRID(G)'

     Returns an integer indicating the spatial reference system ID
     associated with the geometry value G, or 'NULL' if the argument is
     'NULL'.

          mysql> SELECT ST_SRID(ST_GeomFromText('LineString(1 1,2 2)',101));
          +-----------------------------------------------------+
          | ST_SRID(ST_GeomFromText('LineString(1 1,2 2)',101)) |
          +-----------------------------------------------------+
          |                                                 101 |
          +-----------------------------------------------------+

     'ST_SRID()' and 'SRID()' are synonyms.

12.15.7.2 Point Property Functions
..................................

A 'Point' consists of X and Y coordinates, which may be obtained using
the following functions:

   *
     'ST_X(P)'

     Returns the X-coordinate value for the 'Point' object P as a
     double-precision number.

          mysql> SELECT ST_X(Point(56.7, 53.34));
          +--------------------------+
          | ST_X(Point(56.7, 53.34)) |
          +--------------------------+
          |                     56.7 |
          +--------------------------+

     'ST_X()' and 'X()' are synonyms.

   *
     'ST_Y(P)'

     Returns the Y-coordinate value for the 'Point' object P as a
     double-precision number.

          mysql> SELECT ST_Y(Point(56.7, 53.34));
          +--------------------------+
          | ST_Y(Point(56.7, 53.34)) |
          +--------------------------+
          |                    53.34 |
          +--------------------------+

     'ST_Y()' and 'Y()' are synonyms.

   *
     'X(P)'

     'ST_X()' and 'X()' are synonyms.  For more information, see the
     description of 'ST_X()'.

     'X()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'ST_X()' instead.

   *
     'Y(P)'

     'ST_Y()' and 'Y()' are synonyms.  For more information, see the
     description of 'ST_Y()'.

     'Y()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'ST_Y()' instead.

12.15.7.3 LineString and MultiLineString Property Functions
...........................................................

A 'LineString' consists of 'Point' values.  You can extract particular
points of a 'LineString', count the number of points that it contains,
or obtain its length.

Some functions in this section also work for 'MultiLineString' values.

   *
     'EndPoint(LS)'

     'ST_EndPoint()' and 'EndPoint()' are synonyms.  For more
     information, see the description of 'ST_EndPoint()'.

     'EndPoint()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_EndPoint()' instead.

   *
     'GLength(LS)'

     'GLength()' is a nonstandard name.  It corresponds to the OpenGIS
     'ST_Length()' function.  (There is an existing SQL function
     'Length()' that calculates the length of string values.)

     'GLength()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_Length()' instead.

   *
     'IsClosed(LS)'

     'ST_IsClosed()' and 'IsClosed()' are synonyms.  For more
     information, see the description of 'ST_IsClosed()'.

     'IsClosed()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_IsClosed()' instead.

   *
     'NumPoints(LS)'

     'ST_NumPoints()' and 'NumPoints()' are synonyms.  For more
     information, see the description of 'ST_NumPoints()'.

     'NumPoints()' is deprecated as of MySQL 5.7.6 and will be removed
     in a future MySQL release.  Use 'ST_NumPoints()' instead.

   *
     'PointN(LS, N)'

     'ST_PointN()' and 'PointN()' are synonyms.  For more information,
     see the description of 'ST_PointN()'.

     'PointN()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'ST_PointN()' instead.

   *
     'ST_EndPoint(LS)'

     Returns the 'Point' that is the endpoint of the 'LineString' value
     LS.  If the argument is 'NULL' or an empty geometry, the return
     value is 'NULL'.

          mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
          mysql> SELECT ST_AsText(ST_EndPoint(ST_GeomFromText(@ls)));
          +----------------------------------------------+
          | ST_AsText(ST_EndPoint(ST_GeomFromText(@ls))) |
          +----------------------------------------------+
          | POINT(3 3)                                   |
          +----------------------------------------------+

     'ST_EndPoint()' and 'EndPoint()' are synonyms.

   *
     'ST_IsClosed(LS)'

     For a 'LineString' value LS, 'ST_IsClosed()' returns 1 if LS is
     closed (that is, its 'ST_StartPoint()' and 'ST_EndPoint()' values
     are the same).  If the argument is 'NULL' or an empty geometry, the
     return value is 'NULL'.

     For a 'MultiLineString' value LS, 'ST_IsClosed()' returns 1 if LS
     is closed (that is, the 'ST_StartPoint()' and 'ST_EndPoint()'
     values are the same for each 'LineString' in LS).

     'ST_IsClosed()' returns 0 if LS is not closed.

          mysql> SET @ls1 = 'LineString(1 1,2 2,3 3,2 2)';
          mysql> SET @ls2 = 'LineString(1 1,2 2,3 3,1 1)';

          mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls1));
          +------------------------------------+
          | ST_IsClosed(ST_GeomFromText(@ls1)) |
          +------------------------------------+
          |                                  0 |
          +------------------------------------+

          mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls2));
          +------------------------------------+
          | ST_IsClosed(ST_GeomFromText(@ls2)) |
          +------------------------------------+
          |                                  1 |
          +------------------------------------+

          mysql> SET @ls3 = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))';

          mysql> SELECT ST_IsClosed(ST_GeomFromText(@ls3));
          +------------------------------------+
          | ST_IsClosed(ST_GeomFromText(@ls3)) |
          +------------------------------------+
          |                                  0 |
          +------------------------------------+

     'ST_IsClosed()' and 'IsClosed()' are synonyms.

   *
     'ST_Length(LS)'

     Returns a double-precision number indicating the length of the
     'LineString' or 'MultiLineString' value LS in its associated
     spatial reference.  The length of a 'MultiLineString' value is
     equal to the sum of the lengths of its elements.  If the argument
     is 'NULL' or an empty geometry, the return value is 'NULL'.

          mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
          mysql> SELECT ST_Length(ST_GeomFromText(@ls));
          +---------------------------------+
          | ST_Length(ST_GeomFromText(@ls)) |
          +---------------------------------+
          |              2.8284271247461903 |
          +---------------------------------+

          mysql> SET @mls = 'MultiLineString((1 1,2 2,3 3),(4 4,5 5))';
          mysql> SELECT ST_Length(ST_GeomFromText(@mls));
          +----------------------------------+
          | ST_Length(ST_GeomFromText(@mls)) |
          +----------------------------------+
          |                4.242640687119286 |
          +----------------------------------+

     'ST_Length()' was added in MySQL 5.7.6.  It should be used in
     preference to 'GLength()', which has a nonstandard name.

   *
     'ST_NumPoints(LS)'

     Returns the number of 'Point' objects in the 'LineString' value LS.
     If the argument is 'NULL' or an empty geometry, the return value is
     'NULL'.

          mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
          mysql> SELECT ST_NumPoints(ST_GeomFromText(@ls));
          +------------------------------------+
          | ST_NumPoints(ST_GeomFromText(@ls)) |
          +------------------------------------+
          |                                  3 |
          +------------------------------------+

     'ST_NumPoints()' and 'NumPoints()' are synonyms.

   *
     'ST_PointN(LS, N)'

     Returns the N-th 'Point' in the 'Linestring' value LS.  Points are
     numbered beginning with 1.  If any argument is 'NULL' or the
     geometry argument is an empty geometry, the return value is 'NULL'.

          mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
          mysql> SELECT ST_AsText(ST_PointN(ST_GeomFromText(@ls),2));
          +----------------------------------------------+
          | ST_AsText(ST_PointN(ST_GeomFromText(@ls),2)) |
          +----------------------------------------------+
          | POINT(2 2)                                   |
          +----------------------------------------------+

     'ST_PointN()' and 'PointN()' are synonyms.

   *
     'ST_StartPoint(LS)'

     Returns the 'Point' that is the start point of the 'LineString'
     value LS.  If the argument is 'NULL' or an empty geometry, the
     return value is 'NULL'.

          mysql> SET @ls = 'LineString(1 1,2 2,3 3)';
          mysql> SELECT ST_AsText(ST_StartPoint(ST_GeomFromText(@ls)));
          +------------------------------------------------+
          | ST_AsText(ST_StartPoint(ST_GeomFromText(@ls))) |
          +------------------------------------------------+
          | POINT(1 1)                                     |
          +------------------------------------------------+

     'ST_StartPoint()' and 'StartPoint()' are synonyms.

   *
     'StartPoint(LS)'

     'ST_StartPoint()' and 'StartPoint()' are synonyms.  For more
     information, see the description of 'ST_StartPoint()'.

     'StartPoint()' is deprecated as of MySQL 5.7.6 and will be removed
     in a future MySQL release.  Use 'ST_StartPoint()' instead.

12.15.7.4 Polygon and MultiPolygon Property Functions
.....................................................

Functions in this section return properties of 'Polygon' or
'MultiPolygon' values.

   *
     'Area(POLY)'

     'ST_Area()' and 'Area()' are synonyms.  For more information, see
     the description of 'ST_Area()'.

     'Area()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'ST_Area()' instead.

   *
     'Centroid(MPOLY)'

     'ST_Centroid()' and 'Centroid()' are synonyms.  For more
     information, see the description of 'ST_Centroid()'.

     'Centroid()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_Centroid()' instead.

   *
     'ExteriorRing(POLY)'

     'ST_ExteriorRing()' and 'ExteriorRing()' are synonyms.  For more
     information, see the description of 'ST_ExteriorRing()'.

     'ExteriorRing()' is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.  Use 'ST_ExteriorRing()'
     instead.

   *
     'InteriorRingN(POLY, N)'

     'ST_InteriorRingN()' and 'InteriorRingN()' are synonyms.  For more
     information, see the description of 'ST_InteriorRingN()'.

     'InteriorRingN()' is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.  Use 'ST_InteriorRingN()'
     instead.

   *
     'NumInteriorRings(POLY)'

     'ST_NumInteriorRings()' and 'NumInteriorRings()' are synonyms.  For
     more information, see the description of 'ST_NumInteriorRings()'.

     'NumInteriorRings()' is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.  Use 'ST_NumInteriorRings()'
     instead.

   *
     'ST_Area(POLY)'

     Returns a double-precision number indicating the area of the
     argument, as measured in its spatial reference system.  For
     arguments of dimension 0 or 1, the result is 0.  If the argument is
     an empty geometry the return value is 0.  If the argument is 'NULL'
     the return value is 'NULL'.

     The result is the sum of the area values of all components for a
     geometry collection.  If a geometry collection is empty, its area
     is returned as 0.

          mysql> SET @poly =
                 'Polygon((0 0,0 3,3 0,0 0),(1 1,1 2,2 1,1 1))';
          mysql> SELECT ST_Area(ST_GeomFromText(@poly));
          +---------------------------------+
          | ST_Area(ST_GeomFromText(@poly)) |
          +---------------------------------+
          |                               4 |
          +---------------------------------+

          mysql> SET @mpoly =
              -> 'MultiPolygon(((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1)))';
          mysql> SELECT ST_Area(ST_GeomFromText(@mpoly));
          +----------------------------------+
          | ST_Area(ST_GeomFromText(@mpoly)) |
          +----------------------------------+
          |                                8 |
          +----------------------------------+

     'ST_Area()' and 'Area()' are synonyms.

   *
     'ST_Centroid(MPOLY)'

     Returns the mathematical centroid for the 'MultiPolygon' value
     MPOLY as a 'Point'.  The result is not guaranteed to be on the
     'MultiPolygon'.  If the argument is 'NULL' or an empty geometry,
     the return value is 'NULL'.

     This function processes geometry collections by computing the
     centroid point for components of highest dimension in the
     collection.  Such components are extracted and made into a single
     'MultiPolygon', 'MultiLineString', or 'MultiPoint' for centroid
     computation.  If the argument is an empty geometry collection, the
     return value is 'NULL'.

          mysql> SET @poly =
              -> ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0),(5 5,7 5,7 7,5 7,5 5))');
          mysql> SELECT ST_GeometryType(@poly),ST_AsText(ST_Centroid(@poly));
          +------------------------+--------------------------------------------+
          | ST_GeometryType(@poly) | ST_AsText(ST_Centroid(@poly))              |
          +------------------------+--------------------------------------------+
          | POLYGON                | POINT(4.958333333333333 4.958333333333333) |
          +------------------------+--------------------------------------------+

     'ST_Centroid()' and 'Centroid()' are synonyms.

   *
     'ST_ExteriorRing(POLY)'

     Returns the exterior ring of the 'Polygon' value POLY as a
     'LineString'.  If the argument is 'NULL' or an empty geometry, the
     return value is 'NULL'.

          mysql> SET @poly =
              -> 'Polygon((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1))';
          mysql> SELECT ST_AsText(ST_ExteriorRing(ST_GeomFromText(@poly)));
          +----------------------------------------------------+
          | ST_AsText(ST_ExteriorRing(ST_GeomFromText(@poly))) |
          +----------------------------------------------------+
          | LINESTRING(0 0,0 3,3 3,3 0,0 0)                    |
          +----------------------------------------------------+

     'ST_ExteriorRing()' and 'ExteriorRing()' are synonyms.

   *
     'ST_InteriorRingN(POLY, N)'

     Returns the N-th interior ring for the 'Polygon' value POLY as a
     'LineString'.  Rings are numbered beginning with 1.  If the
     argument is 'NULL' or an empty geometry, the return value is
     'NULL'.

          mysql> SET @poly =
              -> 'Polygon((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1))';
          mysql> SELECT ST_AsText(ST_InteriorRingN(ST_GeomFromText(@poly),1));
          +-------------------------------------------------------+
          | ST_AsText(ST_InteriorRingN(ST_GeomFromText(@poly),1)) |
          +-------------------------------------------------------+
          | LINESTRING(1 1,1 2,2 2,2 1,1 1)                       |
          +-------------------------------------------------------+

     'ST_InteriorRingN()' and 'InteriorRingN()' are synonyms.

   *
     'ST_NumInteriorRing(POLY)', 'ST_NumInteriorRings(POLY)'

     Returns the number of interior rings in the 'Polygon' value POLY.
     If the argument is 'NULL' or an empty geometry, the return value is
     'NULL'.

          mysql> SET @poly =
              -> 'Polygon((0 0,0 3,3 3,3 0,0 0),(1 1,1 2,2 2,2 1,1 1))';
          mysql> SELECT ST_NumInteriorRings(ST_GeomFromText(@poly));
          +---------------------------------------------+
          | ST_NumInteriorRings(ST_GeomFromText(@poly)) |
          +---------------------------------------------+
          |                                           1 |
          +---------------------------------------------+

     'ST_NumInteriorRing()', 'ST_NumInteriorRings()', and
     'NumInteriorRings()' are synonyms.  'ST_NumInteriorRing()' was
     added in MySQL 5.7.8.

12.15.7.5 GeometryCollection Property Functions
...............................................

These functions return properties of 'GeometryCollection' values.

   *
     'GeometryN(GC, N)'

     'ST_GeometryN()' and 'GeometryN()' are synonyms.  For more
     information, see the description of 'ST_GeometryN()'.

     'GeometryN()' is deprecated as of MySQL 5.7.6 and will be removed
     in a future MySQL release.  Use 'ST_GeometryN()' instead.

   *
     'NumGeometries(GC)'

     'ST_NumGeometries()' and 'NumGeometries()' are synonyms.  For more
     information, see the description of 'ST_NumGeometries()'.

     'NumGeometries()' is deprecated as of MySQL 5.7.6 and will be
     removed in a future MySQL release.  Use 'ST_NumGeometries()'
     instead.

   *
     'ST_GeometryN(GC, N)'

     Returns the N-th geometry in the 'GeometryCollection' value GC.
     Geometries are numbered beginning with 1.  If any argument is
     'NULL' or the geometry argument is an empty geometry, the return
     value is 'NULL'.

          mysql> SET @gc = 'GeometryCollection(Point(1 1),LineString(2 2, 3 3))';
          mysql> SELECT ST_AsText(ST_GeometryN(ST_GeomFromText(@gc),1));
          +-------------------------------------------------+
          | ST_AsText(ST_GeometryN(ST_GeomFromText(@gc),1)) |
          +-------------------------------------------------+
          | POINT(1 1)                                      |
          +-------------------------------------------------+

     'ST_GeometryN()' and 'GeometryN()' are synonyms.

   *
     'ST_NumGeometries(GC)'

     Returns the number of geometries in the 'GeometryCollection' value
     GC.  If the argument is 'NULL' or an empty geometry, the return
     value is 'NULL'.

          mysql> SET @gc = 'GeometryCollection(Point(1 1),LineString(2 2, 3 3))';
          mysql> SELECT ST_NumGeometries(ST_GeomFromText(@gc));
          +----------------------------------------+
          | ST_NumGeometries(ST_GeomFromText(@gc)) |
          +----------------------------------------+
          |                                      2 |
          +----------------------------------------+

     'ST_NumGeometries()' and 'NumGeometries()' are synonyms.

12.15.8 Spatial Operator Functions
----------------------------------

OpenGIS proposes a number of functions that can produce geometries.
They are designed to implement spatial operators.

These functions support all argument type combinations except those that
are inapplicable according to the Open Geospatial Consortium
specification.

   *
     'Buffer(G, D[, STRATEGY1[, STRATEGY2[, STRATEGY3]]])'

     'ST_Buffer()' and 'Buffer()' are synonyms.  For more information,
     see the description of 'ST_Buffer()'.

     'Buffer()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'ST_Buffer()' instead.

   *
     'ConvexHull(G)'

     'ST_ConvexHull()' and 'ConvexHull()' are synonyms.  For more
     information, see the description of 'ST_ConvexHull()'.

     'ConvexHull()' is deprecated and will be removed in a future MySQL
     release.  Use 'ST_ConvexHull()' instead.

   *
     'ST_Buffer(G, D[, STRATEGY1[, STRATEGY2[, STRATEGY3]]])'

     Returns a geometry that represents all points whose distance from
     the geometry value G is less than or equal to a distance of D, or
     'NULL' if any argument is 'NULL'.  The SRID of the geometry
     argument must be 0 because 'ST_Buffer()' supports only the
     Cartesian coordinate system.  If any geometry argument is not a
     syntactically well-formed geometry, an 'ER_GIS_INVALID_DATA' error
     occurs.

     If the geometry argument is empty, 'ST_Buffer()' returns an empty
     geometry.

     If the distance is 0, 'ST_Buffer()' returns the geometry argument
     unchanged:

          mysql> SET @pt = ST_GeomFromText('POINT(0 0)');
          mysql> SELECT ST_AsText(ST_Buffer(@pt, 0));
          +------------------------------+
          | ST_AsText(ST_Buffer(@pt, 0)) |
          +------------------------------+
          | POINT(0 0)                   |
          +------------------------------+

     'ST_Buffer()' supports negative distances for 'Polygon' and
     'MultiPolygon' values, and for geometry collections containing
     'Polygon' or 'MultiPolygon' values.  The result may be an empty
     geometry.  An 'ER_WRONG_ARGUMENTS' error occurs for 'ST_Buffer()'
     with a negative distance for 'Point', 'MultiPoint', 'LineString',
     and 'MultiLineString' values, and for geometry collections not
     containing any 'Polygon' or 'MultiPolygon' values.

     As of MySQL 5.7.7, 'ST_Buffer()' permits up to three optional
     strategy arguments following the distance argument.  Strategies
     influence buffer computation.  These arguments are byte string
     values produced by the 'ST_Buffer_Strategy()' function, to be used
     for point, join, and end strategies:

        * Point strategies apply to 'Point' and 'MultiPoint' geometries.
          If no point strategy is specified, the default is
          'ST_Buffer_Strategy('point_circle', 32)'.

        * Join strategies apply to 'LineString', 'MultiLineString',
          'Polygon', and 'MultiPolygon' geometries.  If no join strategy
          is specified, the default is 'ST_Buffer_Strategy('join_round',
          32)'.

        * End strategies apply to 'LineString' and 'MultiLineString'
          geometries.  If no end strategy is specified, the default is
          'ST_Buffer_Strategy('end_round', 32)'.

     Up to one strategy of each type may be specified, and they may be
     given in any order.  If multiple strategies of a given type are
     specified, an 'ER_WRONG_ARGUMENTS' error occurs.

          mysql> SET @pt = ST_GeomFromText('POINT(0 0)');
          mysql> SET @pt_strategy = ST_Buffer_Strategy('point_square');
          mysql> SELECT ST_AsText(ST_Buffer(@pt, 2, @pt_strategy));
          +--------------------------------------------+
          | ST_AsText(ST_Buffer(@pt, 2, @pt_strategy)) |
          +--------------------------------------------+
          | POLYGON((-2 -2,2 -2,2 2,-2 2,-2 -2))       |
          +--------------------------------------------+

          mysql> SET @ls = ST_GeomFromText('LINESTRING(0 0,0 5,5 5)');
          mysql> SET @end_strategy = ST_Buffer_Strategy('end_flat');
          mysql> SET @join_strategy = ST_Buffer_Strategy('join_round', 10);
          mysql> SELECT ST_AsText(ST_Buffer(@ls, 5, @end_strategy, @join_strategy))
          +---------------------------------------------------------------+
          | ST_AsText(ST_Buffer(@ls, 5, @end_strategy, @join_strategy))   |
          +---------------------------------------------------------------+
          | POLYGON((5 5,5 10,0 10,-3.5355339059327373 8.535533905932738, |
          | -5 5,-5 0,0 0,5 0,5 5))                                       |
          +---------------------------------------------------------------+

     'ST_Buffer()' and 'Buffer()' are synonyms.

   *
     'ST_Buffer_Strategy(STRATEGY[, POINTS_PER_CIRCLE])'

     This function returns a strategy byte string for use with
     'ST_Buffer()' to influence buffer computation.  If any argument is
     'NULL', the return value is 'NULL'.  If any argument is invalid, an
     'ER_WRONG_ARGUMENTS' error occurs.

     Information about strategies is available at Boost.org
     (http://www.boost.org).

     The first argument must be a string indicating a strategy option:

        * For point strategies, permitted values are ''point_circle''
          and ''point_square''.

        * For join strategies, permitted values are ''join_round'' and
          ''join_miter''.

        * For end strategies, permitted values are ''end_round'' and
          ''end_flat''.

     If the first argument is ''point_circle'', ''join_round'',
     ''join_miter'', or ''end_round'', the POINTS_PER_CIRCLE argument
     must be given as a positive numeric value.  The maximum
     POINTS_PER_CIRCLE value is the value of the
     'max_points_in_geometry' system variable as of MySQL 5.7.8, 65,536
     before that.  If the first argument is ''point_square'' or
     ''end_flat'', the POINTS_PER_CIRCLE argument must not be given or
     an 'ER_WRONG_ARGUMENTS' error occurs.

     For examples, see the description of 'ST_Buffer()'.

     This function was added in MySQL 5.7.7.

   *
     'ST_ConvexHull(G)'

     Returns a geometry that represents the convex hull of the geometry
     value G.  If the argument is 'NULL', the return value is 'NULL'.

     This function computes a geometry's convex hull by first checking
     whether its vertex points are colinear.  The function returns a
     linear hull if so, a polygon hull otherwise.  This function
     processes geometry collections by extracting all vertex points of
     all components of the collection, creating a 'MultiPoint' value
     from them, and computing its convex hull.  If the argument is an
     empty geometry collection, the return value is 'NULL'.

          mysql> SET @g = 'MULTIPOINT(5 0,25 0,15 10,15 25)';
          mysql> SELECT ST_AsText(ST_ConvexHull(ST_GeomFromText(@g)));
          +-----------------------------------------------+
          | ST_AsText(ST_ConvexHull(ST_GeomFromText(@g))) |
          +-----------------------------------------------+
          | POLYGON((5 0,25 0,15 25,5 0))                 |
          +-----------------------------------------------+

     'ST_ConvexHull()' and 'ConvexHull()' are synonyms.

   *
     'ST_Difference(G1, G2)'

     Returns a geometry that represents the point set difference of the
     geometry values G1 and G2.  If any argument is 'NULL', the return
     value is 'NULL'.

          mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
          mysql> SELECT ST_AsText(ST_Difference(@g1, @g2));
          +------------------------------------+
          | ST_AsText(ST_Difference(@g1, @g2)) |
          +------------------------------------+
          | POINT(1 1)                         |
          +------------------------------------+

   *
     'ST_Intersection(G1, G2)'

     Returns a geometry that represents the point set intersection of
     the geometry values G1 and G2.  If any argument is 'NULL', the
     return value is 'NULL'.

          mysql> SET @g1 = ST_GeomFromText('LineString(1 1, 3 3)');
          mysql> SET @g2 = ST_GeomFromText('LineString(1 3, 3 1)');
          mysql> SELECT ST_AsText(ST_Intersection(@g1, @g2));
          +--------------------------------------+
          | ST_AsText(ST_Intersection(@g1, @g2)) |
          +--------------------------------------+
          | POINT(2 2)                           |
          +--------------------------------------+

   *
     'ST_SymDifference(G1, G2)'

     Returns a geometry that represents the point set symmetric
     difference of the geometry values G1 and G2, which is defined as:

          G1 symdifference G2 := (G1 union G2) difference (G1 intersection G2)

     Or, in function call notation:

          ST_SymDifference(G1, G2) = ST_Difference(ST_Union(G1, G2), ST_Intersection(G1, G2))

     If any argument is 'NULL', the return value is 'NULL'.

          mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
          mysql> SELECT ST_AsText(ST_SymDifference(@g1, @g2));
          +---------------------------------------+
          | ST_AsText(ST_SymDifference(@g1, @g2)) |
          +---------------------------------------+
          | MULTIPOINT((1 1),(2 2))               |
          +---------------------------------------+

   *
     'ST_Union(G1, G2)'

     Returns a geometry that represents the point set union of the
     geometry values G1 and G2.  If any argument is 'NULL', the return
     value is 'NULL'.

          mysql> SET @g1 = ST_GeomFromText('LineString(1 1, 3 3)');
          mysql> SET @g2 = ST_GeomFromText('LineString(1 3, 3 1)');
          mysql> SELECT ST_AsText(ST_Union(@g1, @g2));
          +--------------------------------------+
          | ST_AsText(ST_Union(@g1, @g2))        |
          +--------------------------------------+
          | MULTILINESTRING((1 1,3 3),(1 3,3 1)) |
          +--------------------------------------+

In addition, see gis-property-functions, discusses several functions
that construct new geometries from existing ones.  See that section for
descriptions of these functions:

   * 'ST_Envelope(G)'

   * 'ST_StartPoint(LS)'

   * 'ST_EndPoint(LS)'

   * 'ST_PointN(LS, N)'

   * 'ST_ExteriorRing(POLY)'

   * 'ST_InteriorRingN(POLY, N)'

   * 'ST_GeometryN(GC, N)'

12.15.9 Functions That Test Spatial Relations Between Geometry Objects
----------------------------------------------------------------------

The functions described in this section take two geometries as arguments
and return a qualitative or quantitative relation between them.

MySQL implements two sets of functions using function names defined by
the OpenGIS specification.  One set tests the relationship between two
geometry values using precise object shapes, the other set uses object
minimum bounding rectangles (MBRs).

There is also a MySQL-specific set of MBR-based functions available to
test the relationship between two geometry values.

12.15.9.1 Spatial Relation Functions That Use Object Shapes
...........................................................

The OpenGIS specification defines the following functions to test the
relationship between two geometry values 'g1' and 'g2', using precise
object shapes.  Except for 'ST_Distance()' and 'Distance()', the return
values 1 and 0 indicate true and false, respectively.  'ST_Distance()'
'Distance()', return distance values.

These functions support all argument type combinations except those that
are inapplicable according to the Open Geospatial Consortium
specification.

   *
     'Crosses(G1, G2)'

     'ST_Crosses()' and 'Crosses()' are synonyms.  For more information,
     see the description of 'ST_Crosses()'.

     'Crosses()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_Crosses()' instead.

   *
     'Distance(G1, G2)'

     'ST_Distance()' and 'Distance()' are synonyms.  For more
     information, see the description of 'ST_Distance()'.

     'Distance()' is deprecated and will be removed in a future MySQL
     release.  Use 'ST_Distance()' instead.

   *
     'ST_Contains(G1, G2)'

     Returns 1 or 0 to indicate whether G1 completely contains G2.  This
     tests the opposite relationship as 'ST_Within()'.

   *
     'ST_Crosses(G1, G2)'

     The term _spatially crosses_ denotes a spatial relation between two
     given geometries that has the following properties:

        * The two geometries intersect.

        * Their intersection results in a geometry that has a dimension
          that is one less than the maximum dimension of the two given
          geometries.

        * Their intersection is not equal to either of the two given
          geometries.

     This function returns 1 or 0 to indicate whether G1 spatially
     crosses G2.  If 'g1' is a 'Polygon' or a 'MultiPolygon', or if G2
     is a 'Point' or a 'MultiPoint', the return value is 'NULL'.

     This function returns 0 if called with an inapplicable geometry
     argument type combination.  For example, it returns 0 if the first
     argument is a 'Polygon' or 'MultiPolygon' and/or the second
     argument is a 'Point' or 'MultiPoint'.

     Returns 1 if G1 spatially crosses G2.  Returns 'NULL' if 'g1' is a
     'Polygon' or a 'MultiPolygon', or if G2 is a 'Point' or a
     'MultiPoint'.  Otherwise, returns 0.

     This function returns 0 if called with an inapplicable geometry
     argument type combination.  For example, it returns 0 if the first
     argument is a 'Polygon' or 'MultiPolygon' and/or the second
     argument is a 'Point' or 'MultiPoint'.

     'ST_Crosses()' and 'Crosses()' are synonyms.

   *
     'ST_Disjoint(G1, G2)'

     Returns 1 or 0 to indicate whether G1 is spatially disjoint from
     (does not intersect) G2.

   *
     'ST_Distance(G1, G2)'

     Returns the distance between G1 and G2.  If either argument is
     'NULL' or an empty geometry, the return value is 'NULL'.

     This function processes geometry collections by returning the
     shortest distance among all combinations of the components of the
     two geometry arguments.

     If an intermediate or final result produces NaN or a negative
     number, an 'ER_GIS_INVALID_DATA' error occurs.

          mysql> SET @g1 = Point(1,1);
          mysql> SET @g2 = Point(2,2);
          mysql> SELECT ST_Distance(@g1, @g2);
          +-----------------------+
          | ST_Distance(@g1, @g2) |
          +-----------------------+
          |    1.4142135623730951 |
          +-----------------------+

     'ST_Distance()' and 'Distance()' are synonyms.

   *
     'ST_Equals(G1, G2)'

     Returns 1 or 0 to indicate whether G1 is spatially equal to G2.

          mysql> SET @g1 = Point(1,1), @g2 = Point(2,2);
          mysql> SELECT ST_Equals(@g1, @g1), ST_Equals(@g1, @g2);
          +---------------------+---------------------+
          | ST_Equals(@g1, @g1) | ST_Equals(@g1, @g2) |
          +---------------------+---------------------+
          |                   1 |                   0 |
          +---------------------+---------------------+

   *
     'ST_Intersects(G1, G2)'

     Returns 1 or 0 to indicate whether G1 spatially intersects G2.

   *
     'ST_Overlaps(G1, G2)'

     Two geometries _spatially overlap_ if they intersect and their
     intersection results in a geometry of the same dimension but not
     equal to either of the given geometries.

     This function returns 1 or 0 to indicate whether G1 spatially
     overlaps G2.

     This function returns 0 if called with an inapplicable geometry
     argument type combination.  For example, it returns 0 if called
     with geometries of different dimensions or any argument is a
     'Point'.

   *
     'ST_Touches(G1, G2)'

     Two geometries _spatially touch_ if their interiors do not
     intersect, but the boundary of one of the geometries intersects
     either the boundary or the interior of the other.

     This function returns 1 or 0 to indicate whether G1 spatially
     touches G2.

     This function returns 0 if called with an inapplicable geometry
     argument type combination.  For example, it returns 0 if either of
     the arguments is a 'Point' or 'MultiPoint'.

     'ST_Touches()' and 'Touches()' are synonyms.

   *
     'ST_Within(G1, G2)'

     Returns 1 or 0 to indicate whether G1 is spatially within G2.  This
     tests the opposite relationship as 'ST_Contains()'.

   *
     'Touches(G1, G2)'

     'ST_Touches()' and 'Touches()' are synonyms.  For more information,
     see the description of 'ST_Touches()'.

     'Touches()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'ST_Touches()' instead.

12.15.9.2 Spatial Relation Functions That Use Minimum Bounding Rectangles
.........................................................................

MySQL provides several MySQL-specific functions that test the
relationship between minimum bounding rectangles (MBRs) of two
geometries 'g1' and 'g2'.  The return values 1 and 0 indicate true and
false, respectively.

A corresponding set of MBR functions defined according to the OpenGIS
specification is described later in this section.

   *
     'MBRContains(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangle
     of G1 contains the minimum bounding rectangle of G2.  This tests
     the opposite relationship as 'MBRWithin()'.

          mysql> SET @g1 = ST_GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))');
          mysql> SET @g2 = ST_GeomFromText('Point(1 1)');
          mysql> SELECT MBRContains(@g1,@g2), MBRWithin(@g2,@g1);
          +----------------------+--------------------+
          | MBRContains(@g1,@g2) | MBRWithin(@g2,@g1) |
          +----------------------+--------------------+
          |                    1 |                  1 |
          +----------------------+--------------------+

     'MBRContains()' and 'Contains()' are synonyms.

   *
     'MBRCoveredBy(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangle
     of G1 is covered by the minimum bounding rectangle of G2.  This
     tests the opposite relationship as 'MBRCovers()'.

     'MBRCoveredBy()' handles its arguments as follows:

        * If either argument is 'NULL' or an empty geometry, the return
          value is 'NULL'.

        * If either argument is not a syntactically well-formed geometry
          byte string, an 'ER_GIS_INVALID_DATA' error occurs.

        * Otherwise, the return value is non-'NULL'.

          mysql> SET @g1 = ST_GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))');
          mysql> SET @g2 = ST_GeomFromText('Point(1 1)');
          mysql> SELECT MBRCovers(@g1,@g2), MBRCoveredby(@g1,@g2);
          +--------------------+-----------------------+
          | MBRCovers(@g1,@g2) | MBRCoveredby(@g1,@g2) |
          +--------------------+-----------------------+
          |                  1 |                     0 |
          +--------------------+-----------------------+
          mysql> SELECT MBRCovers(@g2,@g1), MBRCoveredby(@g2,@g1);
          +--------------------+-----------------------+
          | MBRCovers(@g2,@g1) | MBRCoveredby(@g2,@g1) |
          +--------------------+-----------------------+
          |                  0 |                     1 |
          +--------------------+-----------------------+

   *
     'MBRCovers(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangle
     of G1 covers the minimum bounding rectangle of G2.  This tests the
     opposite relationship as 'MBRCoveredBy()'.  See the description of
     'MBRCoveredBy()' for examples.

     'MBRCovers()' handles its arguments as follows:

        * If either argument is 'NULL' or an empty geometry, the return
          value is 'NULL'.

        * If either argument is not a syntactically well-formed geometry
          byte string, an 'ER_GIS_INVALID_DATA' error occurs.

        * Otherwise, the return value is non-'NULL'.

   *
     'MBRDisjoint(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangles
     of the two geometries G1 and G2 are disjoint (do not intersect).

     'MBRDisjoint()' and 'Disjoint()' are synonyms.

   *
     'MBREqual(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangles
     of the two geometries G1 and G2 are the same.

     'MBREqual()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'MBREquals()' instead.

   *
     'MBREquals(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangles
     of the two geometries G1 and G2 are the same.

     'MBREquals()', 'MBREqual()', and 'Equals()' are synonyms.

     This function was added in MySQL 5.7.6.

   *
     'MBRIntersects(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangles
     of the two geometries G1 and G2 intersect.

     'MBRIntersects()' and 'Intersects()' are synonyms.

   *
     'MBROverlaps(G1, G2)'

     Two geometries _spatially overlap_ if they intersect and their
     intersection results in a geometry of the same dimension but not
     equal to either of the given geometries.

     This function returns 1 or 0 to indicate whether the minimum
     bounding rectangles of the two geometries G1 and G2 overlap.

     'MBROverlaps()' and 'Overlaps()' are synonyms.

   *
     'MBRTouches(G1, G2)'

     Two geometries _spatially touch_ if their interiors do not
     intersect, but the boundary of one of the geometries intersects
     either the boundary or the interior of the other.

     This function returns 1 or 0 to indicate whether the minimum
     bounding rectangles of the two geometries G1 and G2 touch.

   *
     'MBRWithin(G1, G2)'

     Returns 1 or 0 to indicate whether the minimum bounding rectangle
     of G1 is within the minimum bounding rectangle of G2.  This tests
     the opposite relationship as 'MBRContains()'.

          mysql> SET @g1 = ST_GeomFromText('Polygon((0 0,0 3,3 3,3 0,0 0))');
          mysql> SET @g2 = ST_GeomFromText('Polygon((0 0,0 5,5 5,5 0,0 0))');
          mysql> SELECT MBRWithin(@g1,@g2), MBRWithin(@g2,@g1);
          +--------------------+--------------------+
          | MBRWithin(@g1,@g2) | MBRWithin(@g2,@g1) |
          +--------------------+--------------------+
          |                  1 |                  0 |
          +--------------------+--------------------+

     'MBRWithin()' and 'Within()' are synonyms.

The OpenGIS specification defines the following functions that test the
relationship between two geometry values 'g1' and 'g2'.  The MySQL
implementation uses minimum bounding rectangles, so these functions
return the same result as the corresponding MBR-based functions
described earlier in this section.  The return values 1 and 0 indicate
true and false, respectively.

These functions support all argument type combinations except those that
are inapplicable according to the Open Geospatial Consortium
specification.

   *
     'Contains(G1, G2)'

     'MBRContains()' and 'Contains()' are synonyms.  For more
     information, see the description of 'MBRContains()'.

     'Contains()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'MBRContains()' instead.

   *
     'Disjoint(G1, G2)'

     'MBRDisjoint()' and 'Disjoint()' are synonyms.  For more
     information, see the description of 'MBRDisjoint()'.

     'Disjoint()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'MBRDisjoint()' instead.

   *
     'Equals(G1, G2)'

     'MBREquals()' and 'Equals()' are synonyms.  For more information,
     see the description of 'MBREquals()'.

     'Equals()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'MBREquals()' instead.

   *
     'Intersects(G1, G2)'

     'MBRIntersects()' and 'Intersects()' are synonyms.  For more
     information, see the description of 'MBRIntersects()'.

     'Intersects()' is deprecated as of MySQL 5.7.6 and will be removed
     in a future MySQL release.  Use 'MBRIntersects()' instead.

   *
     'Overlaps(G1, G2)'

     'MBROverlaps()' and 'Overlaps()' are synonyms.  For more
     information, see the description of 'MBROverlaps()'.

     'Overlaps()' is deprecated as of MySQL 5.7.6 and will be removed in
     a future MySQL release.  Use 'MBROverlaps()' instead.

   *
     'Within(G1, G2)'

     'MBRWithin()' and 'Within()' are synonyms.  For more information,
     see the description of 'MBRWithin()'.

     'Within()' is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.  Use 'MBRWithin()' instead.

12.15.10 Spatial Geohash Functions
----------------------------------

Geohash is a system for encoding latitude and longitude coordinates of
arbitrary precision into a text string.  Geohash values are strings that
contain only characters chosen from
'"0123456789bcdefghjkmnpqrstuvwxyz"'.

The functions in this section enable manipulation of geohash values,
which provides applications the capabilities of importing and exporting
geohash data, and of indexing and searching geohash values.

   *
     'ST_GeoHash(LONGITUDE, LATITUDE, MAX_LENGTH)', 'ST_GeoHash(POINT,
     MAX_LENGTH)'

     Returns a geohash string in the connection character set and
     collation.

     If any argument is 'NULL', the return value is 'NULL'.  If any
     argument is invalid, an error occurs.

     For the first syntax, the LONGITUDE must be a number in the range
     [−180, 180], and the LATITUDE must be a number in the range
     [−90, 90].  For the second syntax, a 'POINT' value is required,
     where the X and Y coordinates are in the valid ranges for longitude
     and latitude, respectively.

     The resulting string is no longer than MAX_LENGTH characters, which
     has an upper limit of 100.  The string might be shorter than
     MAX_LENGTH characters because the algorithm that creates the
     geohash value continues until it has created a string that is
     either an exact representation of the location or MAX_LENGTH
     characters, whichever comes first.

          mysql> SELECT ST_GeoHash(180,0,10), ST_GeoHash(-180,-90,15);
          +----------------------+-------------------------+
          | ST_GeoHash(180,0,10) | ST_GeoHash(-180,-90,15) |
          +----------------------+-------------------------+
          | xbpbpbpbpb           | 000000000000000         |
          +----------------------+-------------------------+

   *
     'ST_LatFromGeoHash(GEOHASH_STR)'

     Returns the latitude from a geohash string value, as a
     'DOUBLE' value in the range [−90, 90].

     If the argument is 'NULL', the return value is 'NULL'.  If the
     argument is invalid, an error occurs.

     The 'ST_LatFromGeoHash()' decoding function reads no more than 433
     characters from the GEOHASH_STR argument.  That represents the
     upper limit on information in the internal representation of
     coordinate values.  Characters past the 433rd are ignored, even if
     they are otherwise illegal and produce an error.

          mysql> SELECT ST_LatFromGeoHash(ST_GeoHash(45,-20,10));
          +------------------------------------------+
          | ST_LatFromGeoHash(ST_GeoHash(45,-20,10)) |
          +------------------------------------------+
          |                                      -20 |
          +------------------------------------------+

   *
     'ST_LongFromGeoHash(GEOHASH_STR)'

     Returns the longitude from a geohash string value, as a
     'DOUBLE' value in the range [−180, 180].

     If the argument is 'NULL', the return value is 'NULL'.  If the
     argument is invalid, an error occurs.

     The remarks in the description of 'ST_LatFromGeoHash()' regarding
     the maximum number of characters processed from the GEOHASH_STR
     argument also apply to 'ST_LongFromGeoHash()'.

          mysql> SELECT ST_LongFromGeoHash(ST_GeoHash(45,-20,10));
          +-------------------------------------------+
          | ST_LongFromGeoHash(ST_GeoHash(45,-20,10)) |
          +-------------------------------------------+
          |                                        45 |
          +-------------------------------------------+

   *
     'ST_PointFromGeoHash(GEOHASH_STR, SRID)'

     Returns a 'POINT' value containing the decoded geohash value, given
     a geohash string value.

     The X and Y coordinates of the point are the longitude in the range
     [−180, 180] and the latitude in the range [−90, 90],
     respectively.

     If any argument is 'NULL', the return value is 'NULL'.  If any
     argument is invalid, an error occurs.

     The SRID argument is an unsigned 32-bit integer.

     The remarks in the description of 'ST_LatFromGeoHash()' regarding
     the maximum number of characters processed from the GEOHASH_STR
     argument also apply to 'ST_PointFromGeoHash()'.

          mysql> SET @gh = ST_GeoHash(45,-20,10);
          mysql> SELECT ST_AsText(ST_PointFromGeoHash(@gh,0));
          +---------------------------------------+
          | ST_AsText(ST_PointFromGeoHash(@gh,0)) |
          +---------------------------------------+
          | POINT(45 -20)                         |
          +---------------------------------------+

12.15.11 Spatial GeoJSON Functions
----------------------------------

This section describes functions for converting between GeoJSON
documents and spatial values.  GeoJSON is an open standard for encoding
geometric/geographical features.  For more information, see
<http://geojson.org>.  The functions discussed here follow GeoJSON
specification revision 1.0.

GeoJSON supports the same geometric/geographic data types that MySQL
supports.  Feature and FeatureCollection objects are not supported,
except that geometry objects are extracted from them.  CRS support is
limited to values that identify an SRID.

MySQL also supports a native 'JSON' data type and a set of
SQL functions to enable operations on JSON values.  For more
information, see json, and json-functions.

   *
     'ST_AsGeoJSON(G [, MAX_DEC_DIGITS [, OPTIONS]])'

     Generates a GeoJSON object from the geometry G.  The object string
     has the connection character set and collation.

     If any argument is 'NULL', the return value is 'NULL'.  If any
     non-'NULL' argument is invalid, an error occurs.

     MAX_DEC_DIGITS, if specified, limits the number of decimal digits
     for coordinates and causes rounding of output.  If not specified,
     this argument defaults to its maximum value of 2^32 − 1.  The
     minimum is 0.

     OPTIONS, if specified, is a bitmask.  The following table shows the
     permitted flag values.  If the geometry argument has an SRID of 0,
     no CRS object is produced even for those flag values that request
     one.

     Flag    Meaning
     Value

     0       No options.  This is the default if OPTIONS is not specified.

     1       Add a bounding box to the output.

     2       Add a short-format CRS URN to the output.  The default format
             is a short format ('EPSG:SRID').

     4       Add a long-format CRS URN ('urn:ogc:def:crs:EPSG::SRID').  This
             flag overrides flag 2.  For example, option values of 5 and 7
             mean the same (add a bounding box and a long-format CRS URN).

          mysql> SELECT ST_AsGeoJSON(ST_GeomFromText('POINT(11.11111 12.22222)'),2);
          +-------------------------------------------------------------+
          | ST_AsGeoJSON(ST_GeomFromText('POINT(11.11111 12.22222)'),2) |
          +-------------------------------------------------------------+
          | {"type": "Point", "coordinates": [11.11, 12.22]}            |
          +-------------------------------------------------------------+

   *
     'ST_GeomFromGeoJSON(STR [, OPTIONS [, SRID]])'

     Parses a string STR representing a GeoJSON object and returns a
     geometry.

     If any argument is 'NULL', the return value is 'NULL'.  If any
     non-'NULL' argument is invalid, an error occurs.

     OPTIONS, if given, describes how to handle GeoJSON documents that
     contain geometries with coordinate dimensions higher than 2.  The
     following table shows the permitted OPTIONS values.

     Option  Meaning
     Value

     1       Reject the document and produce an error.  This is the default
             if OPTIONS is not specified.

     2, 3,   Accept the document and strip off the coordinates for higher
     4       coordinate dimensions.

     OPTIONS values of 2, 3, and 4 currently produce the same effect.
     If geometries with coordinate dimensions higher than 2 are
     supported in the future, these values will produce different
     effects.

     The SRID argument, if given, must be a 32-bit unsigned integer.  If
     not given, the geometry return value has an SRID of 4326.

     GeoJSON geometry, feature, and feature collection objects may have
     a 'crs' property.  The parsing function parses named CRS URNs in
     the 'urn:ogc:def:crs:EPSG::SRID' and 'EPSG:SRID' namespaces, but
     not CRSs given as link objects.  Also,
     'urn:ogc:def:crs:OGC:1.3:CRS84' is recognized as SRID 4326.  If an
     object has a CRS that is not understood, an error occurs, with the
     exception that if the optional SRID argument is given, any CRS is
     ignored even if it is invalid.

     As specified in the GeoJSON specification, parsing is case
     sensitive for the 'type' member of the GeoJSON input ('Point',
     'LineString', and so forth).  The specification is silent regarding
     case sensitivity for other parsing, which in MySQL is not
     case-sensitive.

     This example shows the parsing result for a simple GeoJSON object:

          mysql> SET @json = '{ "type": "Point", "coordinates": [102.0, 0.0]}';
          mysql> SELECT ST_AsText(ST_GeomFromGeoJSON(@json));
          +--------------------------------------+
          | ST_AsText(ST_GeomFromGeoJSON(@json)) |
          +--------------------------------------+
          | POINT(102 0)                         |
          +--------------------------------------+

12.15.12 Spatial Convenience Functions
--------------------------------------

The functions in this section provide convenience operations on geometry
values.

   *
     'ST_Distance_Sphere(G1, G2 [, RADIUS])'

     Returns the mimimum spherical distance between two points and/or
     multipoints on a sphere, in meters, or 'NULL' if any geometry
     argument is 'NULL' or empty.

     Calculations use a spherical earth and a configurable radius.  The
     optional RADIUS argument should be given in meters.  If omitted,
     the default radius is 6,370,986 meters.  An 'ER_WRONG_ARGUMENTS'
     error occurs if the RADIUS argument is present but not positive.

     The geometry arguments should consist of points that specify
     (longitude, latitude) coordinate values:

        * Longitude and latitude are the first and second coordinates of
          the point, respectively.

        * Both coordinates are in degrees.

        * Longitude values must be in the range (-180, 180].  Positive
          values are east of the prime meridian.

        * Latitude values must be in the range [-90, 90].  Positive
          values are north of the equator.

     Supported argument combinations are ('Point', 'Point'), ('Point',
     'MultiPoint'), and ('MultiPoint', 'Point').  An
     'ER_GIS_UNSUPPORTED_ARGUMENT' error occurs for other combinations.

     If any geometry argument is not a syntactically well-formed
     geometry byte string, an 'ER_GIS_INVALID_DATA' error occurs.

          mysql> SET @pt1 = ST_GeomFromText('POINT(0 0)');
          mysql> SET @pt2 = ST_GeomFromText('POINT(180 0)');
          mysql> SELECT ST_Distance_Sphere(@pt1, @pt2);
          +--------------------------------+
          | ST_Distance_Sphere(@pt1, @pt2) |
          +--------------------------------+
          |             20015042.813723423 |
          +--------------------------------+

     This function was added in MySQL 5.7.6.

   *
     'ST_IsValid(G)'

     Returns 1 if the argument is syntactically well-formed and is
     geometrically valid, 0 if the argument is not syntactically
     well-formed or is not geometrically valid.  If the argument is
     'NULL', the return value is 'NULL'.  Geometry validity is defined
     by the OGC specification.

     The only valid empty geometry is represented in the form of an
     empty geometry collection value.  'ST_IsValid()' returns 1 in this
     case.

     'ST_IsValid()' works only for the Cartesian coordinate system and
     requires a geometry argument with an SRID of 0.  An
     'ER_WRONG_ARGUMENTS' error occurs otherwise.

          mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0,-0.00 0,0.0 0)');
          mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 0, 1 1)');
          mysql> SELECT ST_IsValid(@ls1);
          +------------------+
          | ST_IsValid(@ls1) |
          +------------------+
          |                0 |
          +------------------+
          mysql> SELECT ST_IsValid(@ls2);
          +------------------+
          | ST_IsValid(@ls2) |
          +------------------+
          |                1 |
          +------------------+

     This function was added in MySQL 5.7.6.

   *
     'ST_MakeEnvelope(PT1, PT2)'

     Returns the rectangle that forms the envelope around two points, as
     a 'Point', 'LineString', or 'Polygon'.  If any argument is 'NULL',
     the return value is 'NULL'.

     Calculations are done using the Cartesian coordinate system rather
     than on a sphere, spheroid, or on earth.

     Given two points PT1 and PT2, 'ST_MakeEnvelope()' creates the
     result geometry on an abstract plane like this:

        * If PT1 and PT2 are equal, the result is the point PT1.

        * Otherwise, if '(PT1, PT2)' is a vertical or horizontal line
          segment, the result is the line segment '(PT1, PT2)'.

        * Otherwise, the result is a polygon using PT1 and PT2 as
          diagonal points.

     The result geometry has an SRID of 0.

     'ST_MakeEnvelope()' requires 'Point' geometry arguments with an
     SRID of 0.  An 'ER_WRONG_ARGUMENTS' error occurs otherwise.

     If any argument is not a syntactically well-formed geometry byte
     string, or if any coordinate value of the two points is infinite
     (that is, 'NaN'), an 'ER_GIS_INVALID_DATA' error occurs.

          mysql> SET @pt1 = ST_GeomFromText('POINT(0 0)');
          mysql> SET @pt2 = ST_GeomFromText('POINT(1 1)');
          mysql> SELECT ST_AsText(ST_MakeEnvelope(@pt1, @pt2));
          +----------------------------------------+
          | ST_AsText(ST_MakeEnvelope(@pt1, @pt2)) |
          +----------------------------------------+
          | POLYGON((0 0,1 0,1 1,0 1,0 0))         |
          +----------------------------------------+

     This function was added in MySQL 5.7.6.

   *
     'ST_Simplify(G, MAX_DISTANCE)'

     Simplifies a geometry using the Douglas-Peucker algorithm and
     returns a simplified value of the same type.  If any argument is
     'NULL', the return value is 'NULL'.

     The geometry may be any geometry type, although the Douglas-Peucker
     algorithm may not actually process every type.  A geometry
     collection is processed by giving its components one by one to the
     simplification algorithm, and the returned geometries are put into
     a geometry collection as result.

     The MAX_DISTANCE argument is the distance (in units of the input
     coordinates) of a vertex to other segments to be removed.  Vertices
     within this distance of the simplified linestring are removed.  If
     the MAX_DISTANCE argument is not positive, or is 'NaN', an
     'ER_WRONG_ARGUMENTS' error occurs.

     According to Boost.Geometry, geometries might become invalid as a
     result of the simplification process, and the process might create
     self-intersections.  To check the validity of the result, pass it
     to 'ST_IsValid()'.

     If the geometry argument is not a syntactically well-formed
     geometry byte string, an 'ER_GIS_INVALID_DATA' error occurs.

          mysql> SET @g = ST_GeomFromText('LINESTRING(0 0,0 1,1 1,1 2,2 2,2 3,3 3)');
          mysql> SELECT ST_AsText(ST_Simplify(@g, 0.5));
          +---------------------------------+
          | ST_AsText(ST_Simplify(@g, 0.5)) |
          +---------------------------------+
          | LINESTRING(0 0,0 1,1 1,2 3,3 3) |
          +---------------------------------+
          mysql> SELECT ST_AsText(ST_Simplify(@g, 1.0));
          +---------------------------------+
          | ST_AsText(ST_Simplify(@g, 1.0)) |
          +---------------------------------+
          | LINESTRING(0 0,3 3)             |
          +---------------------------------+

     This function was added in MySQL 5.7.6.

   *
     'ST_Validate(G)'

     Validates a geometry according to the OGC specification.  A
     geometry can be syntactically well-formed (WKB value plus SRID) but
     geometrically invalid.  For example, this polygon is geometrically
     invalid: 'POLYGON((0 0, 0 0, 0 0, 0 0, 0 0))'

     'ST_Validate()' returns the geometry if it is syntactically
     well-formed and is geometrically valid, 'NULL' if the argument is
     not syntactically well-formed or is not geometrically valid or is
     'NULL'.

     'ST_Validate()' can be used to filter out invalid geometry data,
     although at a cost.  For applications that require more precise
     results not tainted by invalid data, this penalty may be
     worthwhile.

     If the geometry argument is valid, it is returned as is, except
     that if an input 'Polygon' or 'MultiPolygon' has clockwise rings,
     those rings are reversed before checking for validity.  If the
     geometry is valid, the value with the reversed rings is returned.

     The only valid empty geometry is represented in the form of an
     empty geometry collection value.  'ST_Validate()' returns it
     directly without further checks in this case.

     'ST_Validate()' works only for the Cartesian coordinate system and
     requires a geometry argument with an SRID of 0.  An
     'ER_WRONG_ARGUMENTS' error occurs otherwise.

          mysql> SET @ls1 = ST_GeomFromText('LINESTRING(0 0)');
          mysql> SET @ls2 = ST_GeomFromText('LINESTRING(0 0, 1 1)');
          mysql> SELECT ST_AsText(ST_Validate(@ls1));
          +------------------------------+
          | ST_AsText(ST_Validate(@ls1)) |
          +------------------------------+
          | NULL                         |
          +------------------------------+
          mysql> SELECT ST_AsText(ST_Validate(@ls2));
          +------------------------------+
          | ST_AsText(ST_Validate(@ls2)) |
          +------------------------------+
          | LINESTRING(0 0,1 1)          |
          +------------------------------+

     This function was added in MySQL 5.7.6.

12.16 JSON Functions
====================

The functions described in this section perform operations on JSON
values.  For discussion of the 'JSON' data type and
additional examples showing how to use these functions, see
json.

For functions that take a JSON argument, an error occurs if the argument
is not a valid JSON value.  Arguments parsed as JSON are indicated by
JSON_DOC; arguments indicated by VAL are not parsed.

Unless otherwise indicated, the JSON functions were added in MySQL
5.7.8.

A set of spatial functions for operating on GeoJSON values is also
available.  See spatial-geojson-functions.

12.16.1 JSON Function Reference
-------------------------------

*JSON Functions*

Name                          Description

'JSON_APPEND()' (deprecated   Append data to JSON document
5.7.9)

'JSON_ARRAY()'                Create JSON array

'JSON_ARRAY_APPEND()'         Append data to JSON document

'JSON_ARRAY_INSERT()'         Insert into JSON array

'->'                          Return value from JSON column after
                              evaluating path; equivalent to
                              JSON_EXTRACT().

'JSON_CONTAINS()'             Whether JSON document contains specific
                              object at path

'JSON_CONTAINS_PATH()'        Whether JSON document contains any data
                              at path

'JSON_DEPTH()'                Maximum depth of JSON document

'JSON_EXTRACT()'              Return data from JSON document

'->>'                         Return value from JSON column after
                              evaluating path and unquoting the result;
                              equivalent to
                              JSON_UNQUOTE(JSON_EXTRACT()).

'JSON_INSERT()'               Insert data into JSON document

'JSON_KEYS()'                 Array of keys from JSON document

'JSON_LENGTH()'               Number of elements in JSON document

'JSON_MERGE()' (deprecated    Merge JSON documents, preserving
5.7.22)                       duplicate keys.  Deprecated synonym for
                              JSON_MERGE_PRESERVE()

'JSON_MERGE_PATCH()'          Merge JSON documents, replacing values of
                              duplicate keys

'JSON_MERGE_PRESERVE()'       Merge JSON documents, preserving
                              duplicate keys

'JSON_OBJECT()'               Create JSON object

'JSON_PRETTY()'               Prints a JSON document in human-readable
                              format, with each array element or object
                              member printed on a new line, indented
                              two spaces with respect to its parent.

'JSON_QUOTE()'                Quote JSON document

'JSON_REMOVE()'               Remove data from JSON document

'JSON_REPLACE()'              Replace values in JSON document

'JSON_SEARCH()'               Path to value within JSON document

'JSON_SET()'                  Insert data into JSON document

'JSON_STORAGE_SIZE()'         Space used for storage of binary
                              representation of a JSON document; for a
                              JSON column, the space used when the
                              document was inserted, prior to any
                              partial updates

'JSON_TYPE()'                 Type of JSON value

'JSON_UNQUOTE()'              Unquote JSON value

'JSON_VALID()'                Whether JSON value is valid

MySQL 5.7.22 and later supports two aggregate JSON functions
'JSON_ARRAYAGG()' and 'JSON_OBJECTAGG()'.  See
group-by-functions-and-modifiers, for descriptions of these.

Also beginning with MySQL 5.7.22:

   * 'pretty-printing' of JSON values in an easy-to-read format can be
     obtained using the 'JSON_PRETTY()' function.

   * You can see how much storage space a given JSON value takes up
     using 'JSON_STORAGE_SIZE()'.

For complete descriptions of these two functions, see
json-utility-functions.

12.16.2 Functions That Create JSON Values
-----------------------------------------

The functions listed in this section compose JSON values from component
elements.

   *
     'JSON_ARRAY([VAL[, VAL] ...])'

     Evaluates a (possibly empty) list of values and returns a JSON
     array containing those values.

          mysql> SELECT JSON_ARRAY(1, "abc", NULL, TRUE, CURTIME());
          +---------------------------------------------+
          | JSON_ARRAY(1, "abc", NULL, TRUE, CURTIME()) |
          +---------------------------------------------+
          | [1, "abc", null, true, "11:30:24.000000"]   |
          +---------------------------------------------+

   *
     'JSON_OBJECT([KEY, VAL[, KEY, VAL] ...])'

     Evaluates a (possibly empty) list of key-value pairs and returns a
     JSON object containing those pairs.  An error occurs if any key
     name is 'NULL' or the number of arguments is odd.

          mysql> SELECT JSON_OBJECT('id', 87, 'name', 'carrot');
          +-----------------------------------------+
          | JSON_OBJECT('id', 87, 'name', 'carrot') |
          +-----------------------------------------+
          | {"id": 87, "name": "carrot"}            |
          +-----------------------------------------+

   *
     'JSON_QUOTE(STRING)'

     Quotes a string as a JSON value by wrapping it with double quote
     characters and escaping interior quote and other characters, then
     returning the result as a 'utf8mb4' string.  Returns 'NULL' if the
     argument is 'NULL'.

     This function is typically used to produce a valid JSON string
     literal for inclusion within a JSON document.

     Certain special characters are escaped with backslashes per the
     escape sequences shown in
     json-unquote-character-escape-sequences.

          mysql> SELECT JSON_QUOTE('null'), JSON_QUOTE('"null"');
          +--------------------+----------------------+
          | JSON_QUOTE('null') | JSON_QUOTE('"null"') |
          +--------------------+----------------------+
          | "null"             | "\"null\""           |
          +--------------------+----------------------+
          mysql> SELECT JSON_QUOTE('[1, 2, 3]');
          +-------------------------+
          | JSON_QUOTE('[1, 2, 3]') |
          +-------------------------+
          | "[1, 2, 3]"             |
          +-------------------------+

You can also obtain JSON values by casting values of other types to the
'JSON' type using 'CAST(VALUE AS JSON)'; see
json-converting-between-types, for more information.

Two aggregate functions generating JSON values are available (MySQL
5.7.22 and later).  'JSON_ARRAYAGG()' returns a result set as a single
JSON array, and 'JSON_OBJECTAGG()' returns a result set as a single JSON
object.  For more information, see
group-by-functions-and-modifiers.

12.16.3 Functions That Search JSON Values
-----------------------------------------

The functions in this section perform search operations on JSON values
to extract data from them, report whether data exists at a location
within them, or report the path to data within them.

   *
     'JSON_CONTAINS(TARGET, CANDIDATE[, PATH])'

     Indicates by returning 1 or 0 whether a given CANDIDATE JSON
     document is contained within a TARGET JSON document, or--if a PATH
     argument was supplied--whether the candidate is found at a specific
     path within the target.  Returns 'NULL' if any argument is 'NULL',
     or if the path argument does not identify a section of the target
     document.  An error occurs if TARGET or CANDIDATE is not a valid
     JSON document, or if the PATH argument is not a valid path
     expression or contains a '*' or '**' wildcard.

     To check only whether any data exists at the path, use
     'JSON_CONTAINS_PATH()' instead.

     The following rules define containment:

        * A candidate scalar is contained in a target scalar if and only
          if they are comparable and are equal.  Two scalar values are
          comparable if they have the same 'JSON_TYPE()' types, with the
          exception that values of types 'INTEGER' and 'DECIMAL' are
          also comparable to each other.

        * A candidate array is contained in a target array if and only
          if every element in the candidate is contained in some element
          of the target.

        * A candidate nonarray is contained in a target array if and
          only if the candidate is contained in some element of the
          target.

        * A candidate object is contained in a target object if and only
          if for each key in the candidate there is a key with the same
          name in the target and the value associated with the candidate
          key is contained in the value associated with the target key.

     Otherwise, the candidate value is not contained in the target
     document.

          mysql> SET @j = '{"a": 1, "b": 2, "c": {"d": 4}}';
          mysql> SET @j2 = '1';
          mysql> SELECT JSON_CONTAINS(@j, @j2, '$.a');
          +-------------------------------+
          | JSON_CONTAINS(@j, @j2, '$.a') |
          +-------------------------------+
          |                             1 |
          +-------------------------------+
          mysql> SELECT JSON_CONTAINS(@j, @j2, '$.b');
          +-------------------------------+
          | JSON_CONTAINS(@j, @j2, '$.b') |
          +-------------------------------+
          |                             0 |
          +-------------------------------+

          mysql> SET @j2 = '{"d": 4}';
          mysql> SELECT JSON_CONTAINS(@j, @j2, '$.a');
          +-------------------------------+
          | JSON_CONTAINS(@j, @j2, '$.a') |
          +-------------------------------+
          |                             0 |
          +-------------------------------+
          mysql> SELECT JSON_CONTAINS(@j, @j2, '$.c');
          +-------------------------------+
          | JSON_CONTAINS(@j, @j2, '$.c') |
          +-------------------------------+
          |                             1 |
          +-------------------------------+

   *
     'JSON_CONTAINS_PATH(JSON_DOC, ONE_OR_ALL, PATH[, PATH] ...)'

     Returns 0 or 1 to indicate whether a JSON document contains data at
     a given path or paths.  Returns 'NULL' if any argument is 'NULL'.
     An error occurs if the JSON_DOC argument is not a valid JSON
     document, any PATH argument is not a valid path expression, or
     ONE_OR_ALL is not ''one'' or ''all''.

     To check for a specific value at a path, use 'JSON_CONTAINS()'
     instead.

     The return value is 0 if no specified path exists within the
     document.  Otherwise, the return value depends on the ONE_OR_ALL
     argument:

        * ''one'': 1 if at least one path exists within the document, 0
          otherwise.

        * ''all'': 1 if all paths exist within the document, 0
          otherwise.

          mysql> SET @j = '{"a": 1, "b": 2, "c": {"d": 4}}';
          mysql> SELECT JSON_CONTAINS_PATH(@j, 'one', '$.a', '$.e');
          +---------------------------------------------+
          | JSON_CONTAINS_PATH(@j, 'one', '$.a', '$.e') |
          +---------------------------------------------+
          |                                           1 |
          +---------------------------------------------+
          mysql> SELECT JSON_CONTAINS_PATH(@j, 'all', '$.a', '$.e');
          +---------------------------------------------+
          | JSON_CONTAINS_PATH(@j, 'all', '$.a', '$.e') |
          +---------------------------------------------+
          |                                           0 |
          +---------------------------------------------+
          mysql> SELECT JSON_CONTAINS_PATH(@j, 'one', '$.c.d');
          +----------------------------------------+
          | JSON_CONTAINS_PATH(@j, 'one', '$.c.d') |
          +----------------------------------------+
          |                                      1 |
          +----------------------------------------+
          mysql> SELECT JSON_CONTAINS_PATH(@j, 'one', '$.a.d');
          +----------------------------------------+
          | JSON_CONTAINS_PATH(@j, 'one', '$.a.d') |
          +----------------------------------------+
          |                                      0 |
          +----------------------------------------+

   *
     'JSON_EXTRACT(JSON_DOC, PATH[, PATH] ...)'

     Returns data from a JSON document, selected from the parts of the
     document matched by the PATH arguments.  Returns 'NULL' if any
     argument is 'NULL' or no paths locate a value in the document.  An
     error occurs if the JSON_DOC argument is not a valid JSON document
     or any PATH argument is not a valid path expression.

     The return value consists of all values matched by the PATH
     arguments.  If it is possible that those arguments could return
     multiple values, the matched values are autowrapped as an array, in
     the order corresponding to the paths that produced them.
     Otherwise, the return value is the single matched value.

          mysql> SELECT JSON_EXTRACT('[10, 20, [30, 40]]', '$[1]');
          +--------------------------------------------+
          | JSON_EXTRACT('[10, 20, [30, 40]]', '$[1]') |
          +--------------------------------------------+
          | 20                                         |
          +--------------------------------------------+
          mysql> SELECT JSON_EXTRACT('[10, 20, [30, 40]]', '$[1]', '$[0]');
          +----------------------------------------------------+
          | JSON_EXTRACT('[10, 20, [30, 40]]', '$[1]', '$[0]') |
          +----------------------------------------------------+
          | [20, 10]                                           |
          +----------------------------------------------------+
          mysql> SELECT JSON_EXTRACT('[10, 20, [30, 40]]', '$[2][*]');
          +-----------------------------------------------+
          | JSON_EXTRACT('[10, 20, [30, 40]]', '$[2][*]') |
          +-----------------------------------------------+
          | [30, 40]                                      |
          +-----------------------------------------------+

     MySQL 5.7.9 and later supports the '->' operator as shorthand for
     this function as used with 2 arguments where the left hand side is
     a 'JSON' column identifier (not an expression) and the
     right hand side is the JSON path to be matched within the column.

   *
     'COLUMN->PATH'

     In MySQL 5.7.9 and later, the '->' operator serves as an alias for
     the 'JSON_EXTRACT()' function when used with two arguments, a
     column identifier on the left and a JSON path on the right that is
     evaluated against the JSON document (the column value).  You can
     use such expressions in place of column identifiers wherever they
     occur in SQL statements.

     The two 'SELECT' statements shown here produce the
     same output:

          mysql> SELECT c, JSON_EXTRACT(c, "$.id"), g
               > FROM jemp
               > WHERE JSON_EXTRACT(c, "$.id") > 1
               > ORDER BY JSON_EXTRACT(c, "$.name");
          +-------------------------------+-----------+------+
          | c                             | c->"$.id" | g    |
          +-------------------------------+-----------+------+
          | {"id": "3", "name": "Barney"} | "3"       |    3 |
          | {"id": "4", "name": "Betty"}  | "4"       |    4 |
          | {"id": "2", "name": "Wilma"}  | "2"       |    2 |
          +-------------------------------+-----------+------+
          3 rows in set (0.00 sec)

          mysql> SELECT c, c->"$.id", g
               > FROM jemp
               > WHERE c->"$.id" > 1
               > ORDER BY c->"$.name";
          +-------------------------------+-----------+------+
          | c                             | c->"$.id" | g    |
          +-------------------------------+-----------+------+
          | {"id": "3", "name": "Barney"} | "3"       |    3 |
          | {"id": "4", "name": "Betty"}  | "4"       |    4 |
          | {"id": "2", "name": "Wilma"}  | "2"       |    2 |
          +-------------------------------+-----------+------+
          3 rows in set (0.00 sec)

     This functionality is not limited to 'SELECT', as shown here:

          mysql> ALTER TABLE jemp ADD COLUMN n INT;
          Query OK, 0 rows affected (0.68 sec)
          Records: 0  Duplicates: 0  Warnings: 0

          mysql> UPDATE jemp SET n=1 WHERE c->"$.id" = "4";
          Query OK, 1 row affected (0.04 sec)
          Rows matched: 1  Changed: 1  Warnings: 0

          mysql> SELECT c, c->"$.id", g, n
               > FROM jemp
               > WHERE JSON_EXTRACT(c, "$.id") > 1
               > ORDER BY c->"$.name";
          +-------------------------------+-----------+------+------+
          | c                             | c->"$.id" | g    | n    |
          +-------------------------------+-----------+------+------+
          | {"id": "3", "name": "Barney"} | "3"       |    3 | NULL |
          | {"id": "4", "name": "Betty"}  | "4"       |    4 |    1 |
          | {"id": "2", "name": "Wilma"}  | "2"       |    2 | NULL |
          +-------------------------------+-----------+------+------+
          3 rows in set (0.00 sec)

          mysql> DELETE FROM jemp WHERE c->"$.id" = "4";
          Query OK, 1 row affected (0.04 sec)

          mysql> SELECT c, c->"$.id", g, n
               > FROM jemp
               > WHERE JSON_EXTRACT(c, "$.id") > 1
               > ORDER BY c->"$.name";
          +-------------------------------+-----------+------+------+
          | c                             | c->"$.id" | g    | n    |
          +-------------------------------+-----------+------+------+
          | {"id": "3", "name": "Barney"} | "3"       |    3 | NULL |
          | {"id": "2", "name": "Wilma"}  | "2"       |    2 | NULL |
          +-------------------------------+-----------+------+------+
          2 rows in set (0.00 sec)

     (See json-column-indirect-index, for the statements used to
     create and populate the table just shown.)

     This also works with JSON array values, as shown here:

          mysql> CREATE TABLE tj10 (a JSON, b INT);
          Query OK, 0 rows affected (0.26 sec)

          mysql> INSERT INTO tj10
               > VALUES ("[3,10,5,17,44]", 33), ("[3,10,5,17,[22,44,66]]", 0);
          Query OK, 1 row affected (0.04 sec)

          mysql> SELECT a->"$[4]" FROM tj10;
          +--------------+
          | a->"$[4]"    |
          +--------------+
          | 44           |
          | [22, 44, 66] |
          +--------------+
          2 rows in set (0.00 sec)

          mysql> SELECT * FROM tj10 WHERE a->"$[0]" = 3;
          +------------------------------+------+
          | a                            | b    |
          +------------------------------+------+
          | [3, 10, 5, 17, 44]           |   33 |
          | [3, 10, 5, 17, [22, 44, 66]] |    0 |
          +------------------------------+------+
          2 rows in set (0.00 sec)

     Nested arrays are supported.  An expression using '->' evaluates as
     'NULL' if no matching key is found in the target JSON document, as
     shown here:

          mysql> SELECT * FROM tj10 WHERE a->"$[4][1]" IS NOT NULL;
          +------------------------------+------+
          | a                            | b    |
          +------------------------------+------+
          | [3, 10, 5, 17, [22, 44, 66]] |    0 |
          +------------------------------+------+

          mysql> SELECT a->"$[4][1]" FROM tj10;
          +--------------+
          | a->"$[4][1]" |
          +--------------+
          | NULL         |
          | 44           |
          +--------------+
          2 rows in set (0.00 sec)

     This is the same behavior as seen in such cases when using
     'JSON_EXTRACT()':

          mysql> SELECT JSON_EXTRACT(a, "$[4][1]") FROM tj10;
          +----------------------------+
          | JSON_EXTRACT(a, "$[4][1]") |
          +----------------------------+
          | NULL                       |
          | 44                         |
          +----------------------------+
          2 rows in set (0.00 sec)

   *
     'COLUMN->>PATH'

     This is an improved, unquoting extraction operator available in
     MySQL 5.7.13 and later.  Whereas the '->' operator simply extracts
     a value, the '->>' operator in addition unquotes the extracted
     result.  In other words, given a 'JSON' column value
     COLUMN and a path expression PATH, the following three expressions
     return the same value:

        * 'JSON_UNQUOTE(' 'JSON_EXTRACT(COLUMN, PATH) )'

        * 'JSON_UNQUOTE(COLUMN' '->' 'PATH)'

        * 'COLUMN->>PATH'

     The '->>' operator can be used wherever
     'JSON_UNQUOTE(JSON_EXTRACT())' would be allowed.  This includes
     (but is not limited to) 'SELECT' lists, 'WHERE' and 'HAVING'
     clauses, and 'ORDER BY' and 'GROUP BY' clauses.

     The next few statements demonstrate some '->>' operator
     equivalences with other expressions in the 'mysql'.
     client:

          mysql> SELECT * FROM jemp WHERE g > 2;
          +-------------------------------+------+
          | c                             | g    |
          +-------------------------------+------+
          | {"id": "3", "name": "Barney"} |    3 |
          | {"id": "4", "name": "Betty"}  |    4 |
          +-------------------------------+------+
          2 rows in set (0.01 sec)

          mysql> SELECT c->'$.name' AS name
              ->     FROM jemp WHERE g > 2;
          +----------+
          | name     |
          +----------+
          | "Barney" |
          | "Betty"  |
          +----------+
          2 rows in set (0.00 sec)

          mysql> SELECT JSON_UNQUOTE(c->'$.name') AS name
              ->     FROM jemp WHERE g > 2;
          +--------+
          | name   |
          +--------+
          | Barney |
          | Betty  |
          +--------+
          2 rows in set (0.00 sec)

          mysql> SELECT c->>'$.name' AS name
              ->     FROM jemp WHERE g > 2;
          +--------+
          | name   |
          +--------+
          | Barney |
          | Betty  |
          +--------+
          2 rows in set (0.00 sec)

     See json-column-indirect-index, for the SQL statements used
     to create and populate the 'jemp' table in the set of examples just
     shown.

     This operator can also be used with JSON arrays, as shown here:

          mysql> CREATE TABLE tj10 (a JSON, b INT);
          Query OK, 0 rows affected (0.26 sec)

          mysql> INSERT INTO tj10 VALUES
              ->     ('[3,10,5,"x",44]', 33),
              ->     ('[3,10,5,17,[22,"y",66]]', 0);
          Query OK, 2 rows affected (0.04 sec)
          Records: 2  Duplicates: 0  Warnings: 0

          mysql> SELECT a->"$[3]", a->"$[4][1]" FROM tj10;
          +-----------+--------------+
          | a->"$[3]" | a->"$[4][1]" |
          +-----------+--------------+
          | "x"       | NULL         |
          | 17        | "y"          |
          +-----------+--------------+
          2 rows in set (0.00 sec)

          mysql> SELECT a->>"$[3]", a->>"$[4][1]" FROM tj10;
          +------------+---------------+
          | a->>"$[3]" | a->>"$[4][1]" |
          +------------+---------------+
          | x          | NULL          |
          | 17         | y             |
          +------------+---------------+
          2 rows in set (0.00 sec)

     As with '->', the '->>' operator is always expanded in the output
     of 'EXPLAIN', as the following example demonstrates:

          mysql> EXPLAIN SELECT c->>'$.name' AS name
              ->     FROM jemp WHERE g > 2\G
          *************************** 1. row ***************************
                     id: 1
            select_type: SIMPLE
                  table: jemp
             partitions: NULL
                   type: range
          possible_keys: i
                    key: i
                key_len: 5
                    ref: NULL
                   rows: 2
               filtered: 100.00
                  Extra: Using where
          1 row in set, 1 warning (0.00 sec)

          mysql> SHOW WARNINGS\G
          *************************** 1. row ***************************
            Level: Note
             Code: 1003
          Message: /* select#1 */ select
          json_unquote(json_extract(`jtest`.`jemp`.`c`,'$.name')) AS `name` from
          `jtest`.`jemp` where (`jtest`.`jemp`.`g` > 2)
          1 row in set (0.00 sec)

     This is similar to how MySQL expands the '->' operator in the same
     circumstances.

     The '->>' operator was added in MySQL 5.7.13.

   *
     'JSON_KEYS(JSON_DOC[, PATH])'

     Returns the keys from the top-level value of a JSON object as a
     JSON array, or, if a PATH argument is given, the top-level keys
     from the selected path.  Returns 'NULL' if any argument is 'NULL',
     the JSON_DOC argument is not an object, or PATH, if given, does not
     locate an object.  An error occurs if the JSON_DOC argument is not
     a valid JSON document or the PATH argument is not a valid path
     expression or contains a '*' or '**' wildcard.

     The result array is empty if the selected object is empty.  If the
     top-level value has nested subobjects, the return value does not
     include keys from those subobjects.

          mysql> SELECT JSON_KEYS('{"a": 1, "b": {"c": 30}}');
          +---------------------------------------+
          | JSON_KEYS('{"a": 1, "b": {"c": 30}}') |
          +---------------------------------------+
          | ["a", "b"]                            |
          +---------------------------------------+
          mysql> SELECT JSON_KEYS('{"a": 1, "b": {"c": 30}}', '$.b');
          +----------------------------------------------+
          | JSON_KEYS('{"a": 1, "b": {"c": 30}}', '$.b') |
          +----------------------------------------------+
          | ["c"]                                        |
          +----------------------------------------------+

   *
     'JSON_SEARCH(JSON_DOC, ONE_OR_ALL, SEARCH_STR[, ESCAPE_CHAR[, PATH]
     ...])'

     Returns the path to the given string within a JSON document.
     Returns 'NULL' if any of the JSON_DOC, SEARCH_STR, or PATH
     arguments are 'NULL'; no PATH exists within the document; or
     SEARCH_STR is not found.  An error occurs if the JSON_DOC argument
     is not a valid JSON document, any PATH argument is not a valid path
     expression, ONE_OR_ALL is not ''one'' or ''all'', or ESCAPE_CHAR is
     not a constant expression.

     The ONE_OR_ALL argument affects the search as follows:

        * ''one'': The search terminates after the first match and
          returns one path string.  It is undefined which match is
          considered first.

        * ''all'': The search returns all matching path strings such
          that no duplicate paths are included.  If there are multiple
          strings, they are autowrapped as an array.  The order of the
          array elements is undefined.

     Within the SEARCH_STR search string argument, the '%' and '_'
     characters work as for the 'LIKE' operator: '%' matches any number
     of characters (including zero characters), and '_' matches exactly
     one character.

     To specify a literal '%' or '_' character in the search string,
     precede it by the escape character.  The default is '\' if the
     ESCAPE_CHAR argument is missing or 'NULL'.  Otherwise, ESCAPE_CHAR
     must be a constant that is empty or one character.

     For more information about matching and escape character behavior,
     see the description of 'LIKE' in
     string-comparison-functions.  For escape character handling, a
     difference from the 'LIKE' behavior is that the escape character
     for 'JSON_SEARCH()' must evaluate to a constant at compile time,
     not just at execution time.  For example, if 'JSON_SEARCH()' is
     used in a prepared statement and the ESCAPE_CHAR argument is
     supplied using a '?' parameter, the parameter value might be
     constant at execution time, but is not at compile time.

          mysql> SET @j = '["abc", [{"k": "10"}, "def"], {"x":"abc"}, {"y":"bcd"}]';

          mysql> SELECT JSON_SEARCH(@j, 'one', 'abc');
          +-------------------------------+
          | JSON_SEARCH(@j, 'one', 'abc') |
          +-------------------------------+
          | "$[0]"                        |
          +-------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', 'abc');
          +-------------------------------+
          | JSON_SEARCH(@j, 'all', 'abc') |
          +-------------------------------+
          | ["$[0]", "$[2].x"]            |
          +-------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', 'ghi');
          +-------------------------------+
          | JSON_SEARCH(@j, 'all', 'ghi') |
          +-------------------------------+
          | NULL                          |
          +-------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '10');
          +------------------------------+
          | JSON_SEARCH(@j, 'all', '10') |
          +------------------------------+
          | "$[1][0].k"                  |
          +------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '10', NULL, '$');
          +-----------------------------------------+
          | JSON_SEARCH(@j, 'all', '10', NULL, '$') |
          +-----------------------------------------+
          | "$[1][0].k"                             |
          +-----------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '10', NULL, '$[*]');
          +--------------------------------------------+
          | JSON_SEARCH(@j, 'all', '10', NULL, '$[*]') |
          +--------------------------------------------+
          | "$[1][0].k"                                |
          +--------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '10', NULL, '$**.k');
          +---------------------------------------------+
          | JSON_SEARCH(@j, 'all', '10', NULL, '$**.k') |
          +---------------------------------------------+
          | "$[1][0].k"                                 |
          +---------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '10', NULL, '$[*][0].k');
          +-------------------------------------------------+
          | JSON_SEARCH(@j, 'all', '10', NULL, '$[*][0].k') |
          +-------------------------------------------------+
          | "$[1][0].k"                                     |
          +-------------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '10', NULL, '$[1]');
          +--------------------------------------------+
          | JSON_SEARCH(@j, 'all', '10', NULL, '$[1]') |
          +--------------------------------------------+
          | "$[1][0].k"                                |
          +--------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '10', NULL, '$[1][0]');
          +-----------------------------------------------+
          | JSON_SEARCH(@j, 'all', '10', NULL, '$[1][0]') |
          +-----------------------------------------------+
          | "$[1][0].k"                                   |
          +-----------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', 'abc', NULL, '$[2]');
          +---------------------------------------------+
          | JSON_SEARCH(@j, 'all', 'abc', NULL, '$[2]') |
          +---------------------------------------------+
          | "$[2].x"                                    |
          +---------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '%a%');
          +-------------------------------+
          | JSON_SEARCH(@j, 'all', '%a%') |
          +-------------------------------+
          | ["$[0]", "$[2].x"]            |
          +-------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '%b%');
          +-------------------------------+
          | JSON_SEARCH(@j, 'all', '%b%') |
          +-------------------------------+
          | ["$[0]", "$[2].x", "$[3].y"]  |
          +-------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '%b%', NULL, '$[0]');
          +---------------------------------------------+
          | JSON_SEARCH(@j, 'all', '%b%', NULL, '$[0]') |
          +---------------------------------------------+
          | "$[0]"                                      |
          +---------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '%b%', NULL, '$[2]');
          +---------------------------------------------+
          | JSON_SEARCH(@j, 'all', '%b%', NULL, '$[2]') |
          +---------------------------------------------+
          | "$[2].x"                                    |
          +---------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '%b%', NULL, '$[1]');
          +---------------------------------------------+
          | JSON_SEARCH(@j, 'all', '%b%', NULL, '$[1]') |
          +---------------------------------------------+
          | NULL                                        |
          +---------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '%b%', '', '$[1]');
          +-------------------------------------------+
          | JSON_SEARCH(@j, 'all', '%b%', '', '$[1]') |
          +-------------------------------------------+
          | NULL                                      |
          +-------------------------------------------+

          mysql> SELECT JSON_SEARCH(@j, 'all', '%b%', '', '$[3]');
          +-------------------------------------------+
          | JSON_SEARCH(@j, 'all', '%b%', '', '$[3]') |
          +-------------------------------------------+
          | "$[3].y"                                  |
          +-------------------------------------------+

     For more information about the JSON path syntax supported by MySQL,
     including rules governing the wildcard operators '*' and '**', see
     json-path-syntax.

12.16.4 Functions That Modify JSON Values
-----------------------------------------

The functions in this section modify JSON values and return the result.

   *
     'JSON_APPEND(JSON_DOC, PATH, VAL[, PATH, VAL] ...)'

     Appends values to the end of the indicated arrays within a JSON
     document and returns the result.  This function was renamed to
     'JSON_ARRAY_APPEND()' in MySQL 5.7.9; the alias 'JSON_APPEND()' is
     now deprecated in MySQL 5.7, and is removed in MySQL 8.0.

   *
     'JSON_ARRAY_APPEND(JSON_DOC, PATH, VAL[, PATH, VAL] ...)'

     Appends values to the end of the indicated arrays within a JSON
     document and returns the result.  Returns 'NULL' if any argument is
     'NULL'.  An error occurs if the JSON_DOC argument is not a valid
     JSON document or any PATH argument is not a valid path expression
     or contains a '*' or '**' wildcard.

     The path-value pairs are evaluated left to right.  The document
     produced by evaluating one pair becomes the new value against which
     the next pair is evaluated.

     If a path selects a scalar or object value, that value is
     autowrapped within an array and the new value is added to that
     array.  Pairs for which the path does not identify any value in the
     JSON document are ignored.

          mysql> SET @j = '["a", ["b", "c"], "d"]';
          mysql> SELECT JSON_ARRAY_APPEND(@j, '$[1]', 1);
          +----------------------------------+
          | JSON_ARRAY_APPEND(@j, '$[1]', 1) |
          +----------------------------------+
          | ["a", ["b", "c", 1], "d"]        |
          +----------------------------------+
          mysql> SELECT JSON_ARRAY_APPEND(@j, '$[0]', 2);
          +----------------------------------+
          | JSON_ARRAY_APPEND(@j, '$[0]', 2) |
          +----------------------------------+
          | [["a", 2], ["b", "c"], "d"]      |
          +----------------------------------+
          mysql> SELECT JSON_ARRAY_APPEND(@j, '$[1][0]', 3);
          +-------------------------------------+
          | JSON_ARRAY_APPEND(@j, '$[1][0]', 3) |
          +-------------------------------------+
          | ["a", [["b", 3], "c"], "d"]         |
          +-------------------------------------+

          mysql> SET @j = '{"a": 1, "b": [2, 3], "c": 4}';
          mysql> SELECT JSON_ARRAY_APPEND(@j, '$.b', 'x');
          +------------------------------------+
          | JSON_ARRAY_APPEND(@j, '$.b', 'x')  |
          +------------------------------------+
          | {"a": 1, "b": [2, 3, "x"], "c": 4} |
          +------------------------------------+
          mysql> SELECT JSON_ARRAY_APPEND(@j, '$.c', 'y');
          +--------------------------------------+
          | JSON_ARRAY_APPEND(@j, '$.c', 'y')    |
          +--------------------------------------+
          | {"a": 1, "b": [2, 3], "c": [4, "y"]} |
          +--------------------------------------+

          mysql> SET @j = '{"a": 1}';
          mysql> SELECT JSON_ARRAY_APPEND(@j, '$', 'z');
          +---------------------------------+
          | JSON_ARRAY_APPEND(@j, '$', 'z') |
          +---------------------------------+
          | [{"a": 1}, "z"]                 |
          +---------------------------------+

   *
     'JSON_ARRAY_INSERT(JSON_DOC, PATH, VAL[, PATH, VAL] ...)'

     Updates a JSON document, inserting into an array within the
     document and returning the modified document.  Returns 'NULL' if
     any argument is 'NULL'.  An error occurs if the JSON_DOC argument
     is not a valid JSON document or any PATH argument is not a valid
     path expression or contains a '*' or '**' wildcard or does not end
     with an array element identifier.

     The path-value pairs are evaluated left to right.  The document
     produced by evaluating one pair becomes the new value against which
     the next pair is evaluated.

     Pairs for which the path does not identify any array in the JSON
     document are ignored.  If a path identifies an array element, the
     corresponding value is inserted at that element position, shifting
     any following values to the right.  If a path identifies an array
     position past the end of an array, the value is inserted at the end
     of the array.

          mysql> SET @j = '["a", {"b": [1, 2]}, [3, 4]]';
          mysql> SELECT JSON_ARRAY_INSERT(@j, '$[1]', 'x');
          +------------------------------------+
          | JSON_ARRAY_INSERT(@j, '$[1]', 'x') |
          +------------------------------------+
          | ["a", "x", {"b": [1, 2]}, [3, 4]]  |
          +------------------------------------+
          mysql> SELECT JSON_ARRAY_INSERT(@j, '$[100]', 'x');
          +--------------------------------------+
          | JSON_ARRAY_INSERT(@j, '$[100]', 'x') |
          +--------------------------------------+
          | ["a", {"b": [1, 2]}, [3, 4], "x"]    |
          +--------------------------------------+
          mysql> SELECT JSON_ARRAY_INSERT(@j, '$[1].b[0]', 'x');
          +-----------------------------------------+
          | JSON_ARRAY_INSERT(@j, '$[1].b[0]', 'x') |
          +-----------------------------------------+
          | ["a", {"b": ["x", 1, 2]}, [3, 4]]       |
          +-----------------------------------------+
          mysql> SELECT JSON_ARRAY_INSERT(@j, '$[2][1]', 'y');
          +---------------------------------------+
          | JSON_ARRAY_INSERT(@j, '$[2][1]', 'y') |
          +---------------------------------------+
          | ["a", {"b": [1, 2]}, [3, "y", 4]]     |
          +---------------------------------------+
          mysql> SELECT JSON_ARRAY_INSERT(@j, '$[0]', 'x', '$[2][1]', 'y');
          +----------------------------------------------------+
          | JSON_ARRAY_INSERT(@j, '$[0]', 'x', '$[2][1]', 'y') |
          +----------------------------------------------------+
          | ["x", "a", {"b": [1, 2]}, [3, 4]]                  |
          +----------------------------------------------------+

     Earlier modifications affect the positions of the following
     elements in the array, so subsequent paths in the same
     'JSON_ARRAY_INSERT()' call should take this into account.  In the
     final example, the second path inserts nothing because the path no
     longer matches anything after the first insert.

   *
     'JSON_INSERT(JSON_DOC, PATH, VAL[, PATH, VAL] ...)'

     Inserts data into a JSON document and returns the result.  Returns
     'NULL' if any argument is 'NULL'.  An error occurs if the JSON_DOC
     argument is not a valid JSON document or any PATH argument is not a
     valid path expression or contains a '*' or '**' wildcard.

     The path-value pairs are evaluated left to right.  The document
     produced by evaluating one pair becomes the new value against which
     the next pair is evaluated.

     A path-value pair for an existing path in the document is ignored
     and does not overwrite the existing document value.  A path-value
     pair for a nonexisting path in the document adds the value to the
     document if the path identifies one of these types of values:

        * A member not present in an existing object.  The member is
          added to the object and associated with the new value.

        * A position past the end of an existing array.  The array is
          extended with the new value.  If the existing value is not an
          array, it is autowrapped as an array, then extended with the
          new value.

     Otherwise, a path-value pair for a nonexisting path in the document
     is ignored and has no effect.

     For a comparison of 'JSON_INSERT()', 'JSON_REPLACE()', and
     'JSON_SET()', see the discussion of 'JSON_SET()'.

          mysql> SET @j = '{ "a": 1, "b": [2, 3]}';
          mysql> SELECT JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]');
          +----------------------------------------------------+
          | JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]') |
          +----------------------------------------------------+
          | {"a": 1, "b": [2, 3], "c": "[true, false]"}        |
          +----------------------------------------------------+

     The third and final value listed in the result is a quoted string
     and not an array like the second one (which is not quoted in the
     output); no casting of values to the JSON type is performed.  To
     insert the array as an array, you must perform such casts
     explicitly, as shown here:

          mysql> SELECT JSON_INSERT(@j, '$.a', 10, '$.c', CAST('[true, false]' AS JSON));
          +------------------------------------------------------------------+
          | JSON_INSERT(@j, '$.a', 10, '$.c', CAST('[true, false]' AS JSON)) |
          +------------------------------------------------------------------+
          | {"a": 1, "b": [2, 3], "c": [true, false]}                        |
          +------------------------------------------------------------------+
          1 row in set (0.00 sec)

   *
     'JSON_MERGE(JSON_DOC, JSON_DOC[, JSON_DOC] ...)'

     Merges two or more JSON documents.  Synonym for
     'JSON_MERGE_PRESERVE()'; deprecated in MySQL 5.7.22 and subject to
     removal in a future release.

          mysql> SELECT JSON_MERGE('[1, 2]', '[true, false]');
          +---------------------------------------+
          | JSON_MERGE('[1, 2]', '[true, false]') |
          +---------------------------------------+
          | [1, 2, true, false]                   |
          +---------------------------------------+
          1 row in set, 1 warning (0.00 sec)

          mysql> SHOW WARNINGS\G
          *************************** 1. row ***************************
            Level: Warning
             Code: 1287
          Message: 'JSON_MERGE' is deprecated and will be removed in a future release. \
           Please use JSON_MERGE_PRESERVE/JSON_MERGE_PATCH instead
          1 row in set (0.00 sec)

     For additional examples, see the entry for 'JSON_MERGE_PRESERVE()'.

   *
     'JSON_MERGE_PATCH(JSON_DOC, JSON_DOC[, JSON_DOC] ...)'

     Performs an RFC 7396 (https://tools.ietf.org/html/rfc7396)
     compliant merge of two or more JSON documents and returns the
     merged result, without preserving members having duplicate keys.
     Raises an error if at least one of the documents passed as
     arguments to this function is not valid.

     *Note*:

     For an explanation and example of the differences between this
     function and 'JSON_MERGE_PRESERVE()', see
     json-merge-patch-json-merge-preserve-compared.

     'JSON_MERGE_PATCH()' performs a merge as follows:

       1. If the first argument is not an object, the result of the
          merge is the same as if an empty object had been merged with
          the second argument.

       2. If the second argument is not an object, the result of the
          merge is the second argument.

       3. If both arguments are objects, the result of the merge is an
          object with the following members:

             * All members of the first object which do not have a
               corresponding member with the same key in the second
               object.

             * All members of the second object which do not have a
               corresponding key in the first object, and whose value is
               not the JSON 'null' literal.

             * All members with a key that exists in both the first and
               the second object, and whose value in the second object
               is not the JSON 'null' literal.  The values of these
               members are the results of recursively merging the value
               in the first object with the value in the second object.

     For additional information, see json-normalization.

          mysql> SELECT JSON_MERGE_PATCH('[1, 2]', '[true, false]');
          +---------------------------------------------+
          | JSON_MERGE_PATCH('[1, 2]', '[true, false]') |
          +---------------------------------------------+
          | [true, false]                               |
          +---------------------------------------------+

          mysql> SELECT JSON_MERGE_PATCH('{"name": "x"}', '{"id": 47}');
          +-------------------------------------------------+
          | JSON_MERGE_PATCH('{"name": "x"}', '{"id": 47}') |
          +-------------------------------------------------+
          | {"id": 47, "name": "x"}                         |
          +-------------------------------------------------+

          mysql> SELECT JSON_MERGE_PATCH('1', 'true');
          +-------------------------------+
          | JSON_MERGE_PATCH('1', 'true') |
          +-------------------------------+
          | true                          |
          +-------------------------------+

          mysql> SELECT JSON_MERGE_PATCH('[1, 2]', '{"id": 47}');
          +------------------------------------------+
          | JSON_MERGE_PATCH('[1, 2]', '{"id": 47}') |
          +------------------------------------------+
          | {"id": 47}                               |
          +------------------------------------------+

          mysql> SELECT JSON_MERGE_PATCH('{ "a": 1, "b":2 }',
               >     '{ "a": 3, "c":4 }');
          +-----------------------------------------------------------+
          | JSON_MERGE_PATCH('{ "a": 1, "b":2 }','{ "a": 3, "c":4 }') |
          +-----------------------------------------------------------+
          | {"a": 3, "b": 2, "c": 4}                                  |
          +-----------------------------------------------------------+

          mysql> SELECT JSON_MERGE_PATCH('{ "a": 1, "b":2 }','{ "a": 3, "c":4 }',
               >     '{ "a": 5, "d":6 }');
          +-------------------------------------------------------------------------------+
          | JSON_MERGE_PATCH('{ "a": 1, "b":2 }','{ "a": 3, "c":4 }','{ "a": 5, "d":6 }') |
          +-------------------------------------------------------------------------------+
          | {"a": 5, "b": 2, "c": 4, "d": 6}                                              |
          +-------------------------------------------------------------------------------+

     You can use this function to remove a member by specifying 'null'
     as the value of the same member in the seond argument, as shown
     here:

          mysql> SELECT JSON_MERGE_PATCH('{"a":1, "b":2}', '{"b":null}');
          +--------------------------------------------------+
          | JSON_MERGE_PATCH('{"a":1, "b":2}', '{"b":null}') |
          +--------------------------------------------------+
          | {"a": 1}                                         |
          +--------------------------------------------------+

     This example shows that the function operates in a recursive
     fashion; that is, values of members are not limited to scalars, but
     rather can themselves be JSON documents:

          mysql> SELECT JSON_MERGE_PATCH('{"a":{"x":1}}', '{"a":{"y":2}}');
          +----------------------------------------------------+
          | JSON_MERGE_PATCH('{"a":{"x":1}}', '{"a":{"y":2}}') |
          +----------------------------------------------------+
          | {"a": {"x": 1, "y": 2}}                            |
          +----------------------------------------------------+

     'JSON_MERGE_PATCH()' is supported in MySQL 5.7.22 and later.

     JSON_MERGE_PATCH() compared with JSON_MERGE_PRESERVE()

     The behavior of 'JSON_MERGE_PATCH()' is the same as that of
     'JSON_MERGE_PRESERVE()', with the following two exceptions:

        * 'JSON_MERGE_PATCH()' removes any member in the first object
          with a matching key in the second object, provided that the
          value associated with the key in the second object is not JSON
          'null'.

        * If the second object has a member with a key matching a member
          in the first object, 'JSON_MERGE_PATCH()' _replaces_ the value
          in the first object with the value in the second object,
          whereas 'JSON_MERGE_PRESERVE()' _appends_ the second value to
          the first value.

     This example compares the results of merging the same 3 JSON
     objects, each having a matching key '"a"', with each of these two
     functions:

          mysql> SET @x = '{ "a": 1, "b": 2 }',
               >     @y = '{ "a": 3, "c": 4 }',
               >     @z = '{ "a": 5, "d": 6 }';

          mysql> SELECT  JSON_MERGE_PATCH(@x, @y, @z)    AS Patch,
              ->         JSON_MERGE_PRESERVE(@x, @y, @z) AS Preserve\G
          *************************** 1. row ***************************
             Patch: {"a": 5, "b": 2, "c": 4, "d": 6}
          Preserve: {"a": [1, 3, 5], "b": 2, "c": 4, "d": 6}

   *
     'JSON_MERGE_PRESERVE(JSON_DOC, JSON_DOC[, JSON_DOC] ...)'

     Merges two or more JSON documents and returns the merged result.
     Returns 'NULL' if any argument is 'NULL'.  An error occurs if any
     argument is not a valid JSON document.

     Merging takes place according to the following rules.  For
     additional information, see json-normalization.

        * Adjacent arrays are merged to a single array.

        * Adjacent objects are merged to a single object.

        * A scalar value is autowrapped as an array and merged as an
          array.

        * An adjacent array and object are merged by autowrapping the
          object as an array and merging the two arrays.

          mysql> SELECT JSON_MERGE_PRESERVE('[1, 2]', '[true, false]');
          +------------------------------------------------+
          | JSON_MERGE_PRESERVE('[1, 2]', '[true, false]') |
          +------------------------------------------------+
          | [1, 2, true, false]                            |
          +------------------------------------------------+

          mysql> SELECT JSON_MERGE_PRESERVE('{"name": "x"}', '{"id": 47}');
          +----------------------------------------------------+
          | JSON_MERGE_PRESERVE('{"name": "x"}', '{"id": 47}') |
          +----------------------------------------------------+
          | {"id": 47, "name": "x"}                            |
          +----------------------------------------------------+

          mysql> SELECT JSON_MERGE_PRESERVE('1', 'true');
          +----------------------------------+
          | JSON_MERGE_PRESERVE('1', 'true') |
          +----------------------------------+
          | [1, true]                        |
          +----------------------------------+

          mysql> SELECT JSON_MERGE_PRESERVE('[1, 2]', '{"id": 47}');
          +---------------------------------------------+
          | JSON_MERGE_PRESERVE('[1, 2]', '{"id": 47}') |
          +---------------------------------------------+
          | [1, 2, {"id": 47}]                          |
          +---------------------------------------------+

          mysql> SELECT JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }',
               >    '{ "a": 3, "c": 4 }');
          +--------------------------------------------------------------+
          | JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }','{ "a": 3, "c":4 }') |
          +--------------------------------------------------------------+
          | {"a": [1, 3], "b": 2, "c": 4}                                |
          +--------------------------------------------------------------+

          mysql> SELECT JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }','{ "a": 3, "c": 4 }',
               >    '{ "a": 5, "d": 6 }');
          +----------------------------------------------------------------------------------+
          | JSON_MERGE_PRESERVE('{ "a": 1, "b": 2 }','{ "a": 3, "c": 4 }','{ "a": 5, "d": 6 }') |
          +----------------------------------------------------------------------------------+
          | {"a": [1, 3, 5], "b": 2, "c": 4, "d": 6}                                         |
          +----------------------------------------------------------------------------------+

     This function was added in MySQL 5.7.22 as a synonym for
     'JSON_MERGE()'.  The 'JSON_MERGE()' function is now deprecated, and
     is subject to removal in a future release of MySQL.

     This function is similar to but differs from 'JSON_MERGE_PATCH()'
     in significant respects; see
     json-merge-patch-json-merge-preserve-compared, for more
     information.

   *
     'JSON_REMOVE(JSON_DOC, PATH[, PATH] ...)'

     Removes data from a JSON document and returns the result.  Returns
     'NULL' if any argument is 'NULL'.  An error occurs if the JSON_DOC
     argument is not a valid JSON document or any PATH argument is not a
     valid path expression or is '$' or contains a '*' or '**' wildcard.

     The PATH arguments are evaluated left to right.  The document
     produced by evaluating one path becomes the new value against which
     the next path is evaluated.

     It is not an error if the element to be removed does not exist in
     the document; in that case, the path does not affect the document.

          mysql> SET @j = '["a", ["b", "c"], "d"]';
          mysql> SELECT JSON_REMOVE(@j, '$[1]');
          +-------------------------+
          | JSON_REMOVE(@j, '$[1]') |
          +-------------------------+
          | ["a", "d"]              |
          +-------------------------+

   *
     'JSON_REPLACE(JSON_DOC, PATH, VAL[, PATH, VAL] ...)'

     Replaces existing values in a JSON document and returns the result.
     Returns 'NULL' if any argument is 'NULL'.  An error occurs if the
     JSON_DOC argument is not a valid JSON document or any PATH argument
     is not a valid path expression or contains a '*' or '**' wildcard.

     The path-value pairs are evaluated left to right.  The document
     produced by evaluating one pair becomes the new value against which
     the next pair is evaluated.

     A path-value pair for an existing path in the document overwrites
     the existing document value with the new value.  A path-value pair
     for a nonexisting path in the document is ignored and has no
     effect.

     For a comparison of 'JSON_INSERT()', 'JSON_REPLACE()', and
     'JSON_SET()', see the discussion of 'JSON_SET()'.

          mysql> SET @j = '{ "a": 1, "b": [2, 3]}';
          mysql> SELECT JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]');
          +-----------------------------------------------------+
          | JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]') |
          +-----------------------------------------------------+
          | {"a": 10, "b": [2, 3]}                              |
          +-----------------------------------------------------+

   *
     'JSON_SET(JSON_DOC, PATH, VAL[, PATH, VAL] ...)'

     Inserts or updates data in a JSON document and returns the result.
     Returns 'NULL' if any argument is 'NULL' or PATH, if given, does
     not locate an object.  An error occurs if the JSON_DOC argument is
     not a valid JSON document or any PATH argument is not a valid path
     expression or contains a '*' or '**' wildcard.

     The path-value pairs are evaluated left to right.  The document
     produced by evaluating one pair becomes the new value against which
     the next pair is evaluated.

     A path-value pair for an existing path in the document overwrites
     the existing document value with the new value.  A path-value pair
     for a nonexisting path in the document adds the value to the
     document if the path identifies one of these types of values:

        * A member not present in an existing object.  The member is
          added to the object and associated with the new value.

        * A position past the end of an existing array.  The array is
          extended with the new value.  If the existing value is not an
          array, it is autowrapped as an array, then extended with the
          new value.

     Otherwise, a path-value pair for a nonexisting path in the document
     is ignored and has no effect.

     The 'JSON_SET()', 'JSON_INSERT()', and 'JSON_REPLACE()' functions
     are related:

        * 'JSON_SET()' replaces existing values and adds nonexisting
          values.

        * 'JSON_INSERT()' inserts values without replacing existing
          values.

        * 'JSON_REPLACE()' replaces _only_ existing values.

     The following examples illustrate these differences, using one path
     that does exist in the document ('$.a') and another that does not
     exist ('$.c'):

          mysql> SET @j = '{ "a": 1, "b": [2, 3]}';
          mysql> SELECT JSON_SET(@j, '$.a', 10, '$.c', '[true, false]');
          +-------------------------------------------------+
          | JSON_SET(@j, '$.a', 10, '$.c', '[true, false]') |
          +-------------------------------------------------+
          | {"a": 10, "b": [2, 3], "c": "[true, false]"}    |
          +-------------------------------------------------+
          mysql> SELECT JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]');
          +----------------------------------------------------+
          | JSON_INSERT(@j, '$.a', 10, '$.c', '[true, false]') |
          +----------------------------------------------------+
          | {"a": 1, "b": [2, 3], "c": "[true, false]"}        |
          +----------------------------------------------------+
          mysql> SELECT JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]');
          +-----------------------------------------------------+
          | JSON_REPLACE(@j, '$.a', 10, '$.c', '[true, false]') |
          +-----------------------------------------------------+
          | {"a": 10, "b": [2, 3]}                              |
          +-----------------------------------------------------+

   *
     'JSON_UNQUOTE(JSON_VAL)'

     Unquotes JSON value and returns the result as a 'utf8mb4' string.
     Returns 'NULL' if the argument is 'NULL'.  An error occurs if the
     value starts and ends with double quotes but is not a valid JSON
     string literal.

     Within a string, certain sequences have special meaning unless the
     'NO_BACKSLASH_ESCAPES' SQL mode is enabled.  Each of these
     sequences begins with a backslash ('\'), known as the _escape
     character_.  MySQL recognizes the escape sequences shown in
     json-unquote-character-escape-sequences.  For all other escape
     sequences, backslash is ignored.  That is, the escaped character is
     interpreted as if it was not escaped.  For example, '\x' is just
     'x'.  These sequences are case-sensitive.  For example, '\b' is
     interpreted as a backspace, but '\B' is interpreted as 'B'.

     *JSON_UNQUOTE() Special Character Escape Sequences*

     Escape      Character Represented by Sequence
     Sequence

     '\"'        A double quote ('"') character

     '\b'        A backspace character

     '\f'        A formfeed character

     '\n'        A newline (linefeed) character

     '\r'        A carriage return character

     '\t'        A tab character

     '\\'        A backslash ('\') character

     '\uXXXX'    UTF-8 bytes for Unicode value XXXX

     Two simple examples of the use of this function are shown here:

          mysql> SET @j = '"abc"';
          mysql> SELECT @j, JSON_UNQUOTE(@j);
          +-------+------------------+
          | @j    | JSON_UNQUOTE(@j) |
          +-------+------------------+
          | "abc" | abc              |
          +-------+------------------+
          mysql> SET @j = '[1, 2, 3]';
          mysql> SELECT @j, JSON_UNQUOTE(@j);
          +-----------+------------------+
          | @j        | JSON_UNQUOTE(@j) |
          +-----------+------------------+
          | [1, 2, 3] | [1, 2, 3]        |
          +-----------+------------------+

     The following set of examples shows how 'JSON_UNQUOTE' handles
     escapes with 'NO_BACKSLASH_ESCAPES' disabled and enabled:

          mysql> SELECT @@sql_mode;
          +------------+
          | @@sql_mode |
          +------------+
          |            |
          +------------+

          mysql> SELECT JSON_UNQUOTE('"\\t\\u0032"');
          +------------------------------+
          | JSON_UNQUOTE('"\\t\\u0032"') |
          +------------------------------+
          |       2                           |
          +------------------------------+

          mysql> SET @@sql_mode = 'NO_BACKSLASH_ESCAPES';
          mysql> SELECT JSON_UNQUOTE('"\\t\\u0032"');
          +------------------------------+
          | JSON_UNQUOTE('"\\t\\u0032"') |
          +------------------------------+
          | \t\u0032                     |
          +------------------------------+

          mysql> SELECT JSON_UNQUOTE('"\t\u0032"');
          +----------------------------+
          | JSON_UNQUOTE('"\t\u0032"') |
          +----------------------------+
          |       2                         |
          +----------------------------+

12.16.5 Functions That Return JSON Value Attributes
---------------------------------------------------

The functions in this section return attributes of JSON values.

   *
     'JSON_DEPTH(JSON_DOC)'

     Returns the maximum depth of a JSON document.  Returns 'NULL' if
     the argument is 'NULL'.  An error occurs if the argument is not a
     valid JSON document.

     An empty array, empty object, or scalar value has depth 1.  A
     nonempty array containing only elements of depth 1 or nonempty
     object containing only member values of depth 1 has depth 2.
     Otherwise, a JSON document has depth greater than 2.

          mysql> SELECT JSON_DEPTH('{}'), JSON_DEPTH('[]'), JSON_DEPTH('true');
          +------------------+------------------+--------------------+
          | JSON_DEPTH('{}') | JSON_DEPTH('[]') | JSON_DEPTH('true') |
          +------------------+------------------+--------------------+
          |                1 |                1 |                  1 |
          +------------------+------------------+--------------------+
          mysql> SELECT JSON_DEPTH('[10, 20]'), JSON_DEPTH('[[], {}]');
          +------------------------+------------------------+
          | JSON_DEPTH('[10, 20]') | JSON_DEPTH('[[], {}]') |
          +------------------------+------------------------+
          |                      2 |                      2 |
          +------------------------+------------------------+
          mysql> SELECT JSON_DEPTH('[10, {"a": 20}]');
          +-------------------------------+
          | JSON_DEPTH('[10, {"a": 20}]') |
          +-------------------------------+
          |                             3 |
          +-------------------------------+

   *
     'JSON_LENGTH(JSON_DOC[, PATH])'

     Returns the length of a JSON document, or, if a PATH argument is
     given, the length of the value within the document identified by
     the path.  Returns 'NULL' if any argument is 'NULL' or the PATH
     argument does not identify a value in the document.  An error
     occurs if the JSON_DOC argument is not a valid JSON document or the
     PATH argument is not a valid path expression or contains a '*' or
     '**' wildcard.

     The length of a document is determined as follows:

        * The length of a scalar is 1.

        * The length of an array is the number of array elements.

        * The length of an object is the number of object members.

        * The length does not count the length of nested arrays or
          objects.

          mysql> SELECT JSON_LENGTH('[1, 2, {"a": 3}]');
          +---------------------------------+
          | JSON_LENGTH('[1, 2, {"a": 3}]') |
          +---------------------------------+
          |                               3 |
          +---------------------------------+
          mysql> SELECT JSON_LENGTH('{"a": 1, "b": {"c": 30}}');
          +-----------------------------------------+
          | JSON_LENGTH('{"a": 1, "b": {"c": 30}}') |
          +-----------------------------------------+
          |                                       2 |
          +-----------------------------------------+
          mysql> SELECT JSON_LENGTH('{"a": 1, "b": {"c": 30}}', '$.b');
          +------------------------------------------------+
          | JSON_LENGTH('{"a": 1, "b": {"c": 30}}', '$.b') |
          +------------------------------------------------+
          |                                              1 |
          +------------------------------------------------+

   *
     'JSON_TYPE(JSON_VAL)'

     Returns a 'utf8mb4' string indicating the type of a JSON value.
     This can be an object, an array, or a scalar type, as shown here:

          mysql> SET @j = '{"a": [10, true]}';
          mysql> SELECT JSON_TYPE(@j);
          +---------------+
          | JSON_TYPE(@j) |
          +---------------+
          | OBJECT        |
          +---------------+
          mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a'));
          +------------------------------------+
          | JSON_TYPE(JSON_EXTRACT(@j, '$.a')) |
          +------------------------------------+
          | ARRAY                              |
          +------------------------------------+
          mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]'));
          +---------------------------------------+
          | JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]')) |
          +---------------------------------------+
          | INTEGER                               |
          +---------------------------------------+
          mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]'));
          +---------------------------------------+
          | JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]')) |
          +---------------------------------------+
          | BOOLEAN                               |
          +---------------------------------------+

     'JSON_TYPE()' returns 'NULL' if the argument is 'NULL':

          mysql> SELECT JSON_TYPE(NULL);
          +-----------------+
          | JSON_TYPE(NULL) |
          +-----------------+
          | NULL            |
          +-----------------+

     An error occurs if the argument is not a valid JSON value:

          mysql> SELECT JSON_TYPE(1);
          ERROR 3146 (22032): Invalid data type for JSON data in argument 1
          to function json_type; a JSON string or JSON type is required.

     For a non-'NULL', non-error result, the following list describes
     the possible 'JSON_TYPE()' return values:

        * Purely JSON types:

             * 'OBJECT': JSON objects

             * 'ARRAY': JSON arrays

             * 'BOOLEAN': The JSON true and false literals

             * 'NULL': The JSON null literal

        * Numeric types:

             * 'INTEGER': MySQL 'TINYINT',
               'SMALLINT', 'MEDIUMINT'
               and 'INT' and
               'BIGINT' scalars

             * 'DOUBLE': MySQL 'DOUBLE'.
               'FLOAT' scalars

             * 'DECIMAL': MySQL 'DECIMAL' and
               'NUMERIC' scalars

        * Temporal types:

             * 'DATETIME': MySQL 'DATETIME' and
               'TIMESTAMP' scalars

             * 'DATE': MySQL 'DATE' scalars

             * 'TIME': MySQL 'TIME' scalars

        * String types:

             * 'STRING': MySQL 'utf8' character type scalars:
               'CHAR', 'VARCHAR', 'TEXT',
               'ENUM', and 'SET'.

        * Binary types:

             * 'BLOB': MySQL binary type scalars: 'BINARY',
               see 'VARBINARY',
               'BLOB'.

             * 'BIT': MySQL 'BIT' scalars

        * All other types:

             * 'OPAQUE' (raw bits)

   *
     'JSON_VALID(VAL)'

     Returns 0 or 1 to indicate whether a value is valid JSON. Returns
     'NULL' if the argument is 'NULL'.

          mysql> SELECT JSON_VALID('{"a": 1}');
          +------------------------+
          | JSON_VALID('{"a": 1}') |
          +------------------------+
          |                      1 |
          +------------------------+
          mysql> SELECT JSON_VALID('hello'), JSON_VALID('"hello"');
          +---------------------+-----------------------+
          | JSON_VALID('hello') | JSON_VALID('"hello"') |
          +---------------------+-----------------------+
          |                   0 |                     1 |
          +---------------------+-----------------------+

12.16.6 JSON Utility Functions
------------------------------

This section documents utility functions that act on JSON values, or
strings that can be parsed as JSON values.  'JSON_PRETTY()' prints out a
JSON value in a format that is easy to read.  'JSON_STORAGE_SIZE()'
shows the amount of storage space used by a given JSON value.

   *
     'JSON_PRETTY(JSON_VAL)'

     Provides pretty-printing of JSON values similar to that implemented
     in PHP and by other languages and database systems.  The value
     supplied must be a JSON value or a valid string representation of a
     JSON value.  Extraneous whitespaces and newlines present in this
     value have no effect on the output.  For a 'NULL' value, the
     function returns 'NULL'.  If the value is not a JSON document, or
     if it cannot cannot be parsed as one, the function fails with an
     error.

     Formatting of the output from this function adheres to the
     following rules:

        * Each array element or object member appears on a separate
          line, indented by one additional level as compared to its
          parent.

        * Each level of indentation adds two leading spaces.

        * A comma separating individual array elements or object members
          is printed before the newline that separates the two elements
          or members.

        * The key and the value of an object member are separated by a
          colon followed by a space ('': '').

        * An empty object or array is printed on a single line.  No
          space is printed between the opening and closing brace.

        * Special characters in string scalars and key names are escaped
          employing the same rules used by the 'JSON_QUOTE()' function.

          mysql> SELECT JSON_PRETTY('123'); # scalar
          +--------------------+
          | JSON_PRETTY('123') |
          +--------------------+
          | 123                |
          +--------------------+

          mysql> SELECT JSON_PRETTY("[1,3,5]"); # array
          +------------------------+
          | JSON_PRETTY("[1,3,5]") |
          +------------------------+
          | [
            1,
            3,
            5
          ]      |
          +------------------------+

          mysql> SELECT JSON_PRETTY('{"a":"10","b":"15","x":"25"}'); # object
          +---------------------------------------------+
          | JSON_PRETTY('{"a":"10","b":"15","x":"25"}') |
          +---------------------------------------------+
          | {
            "a": "10",
            "b": "15",
            "x": "25"
          }   |
          +---------------------------------------------+

          mysql> SELECT JSON_PRETTY('["a",1,{"key1":
               >    "value1"},"5",     "77" ,
               >       {"key2":["value3","valueX",
               > "valueY"]},"j", "2"   ]')\G  # nested arrays and objects
          *************************** 1. row ***************************
          JSON_PRETTY('["a",1,{"key1":
                       "value1"},"5",     "77" ,
                          {"key2":["value3","valuex",
                    "valuey"]},"j", "2"   ]'): [
            "a",
            1,
            {
              "key1": "value1"
            },
            "5",
            "77",
            {
              "key2": [
                "value3",
                "valuex",
                "valuey"
              ]
            },
            "j",
            "2"
          ]

     Added in MySQL 5.7.22.

   *
     'JSON_STORAGE_SIZE(JSON_VAL)'

     This function returns the number of bytes used to store the binary
     representation of a JSON document.  When the argument is a 'JSON'
     column, this is the space used to store the JSON document.
     JSON_VAL must be a valid JSON document or a string which can be
     parsed as one.  In the case where it is string, the function
     returns the amount of storage space in the JSON binary
     representation that is created by parsing the string as JSON and
     converting it to binary.  It returns 'NULL' if the argument is
     'NULL'.

     An error results when JSON_VAL is not 'NULL', and is not--or cannot
     be successfully parsed as--a JSON document.

     To illustrate this function's behavior when used with a 'JSON'
     column as its argument, we create a table named 'jtable' containing
     a 'JSON' column 'jcol', insert a JSON value into the table, then
     obtain the storage space used by this column with
     'JSON_STORAGE_SIZE()', as shown here:

          mysql> CREATE TABLE jtable (jcol JSON);
          Query OK, 0 rows affected (0.42 sec)

          mysql> INSERT INTO jtable VALUES
              ->     ('{"a": 1000, "b": "wxyz", "c": "[1, 3, 5, 7]"}');
          Query OK, 1 row affected (0.04 sec)

          mysql> SELECT
              ->     jcol,
              ->     JSON_STORAGE_SIZE(jcol) AS Size
              -> FROM jtable;
          +-----------------------------------------------+------+
          | jcol                                          | Size |
          +-----------------------------------------------+------+
          | {"a": 1000, "b": "wxyz", "c": "[1, 3, 5, 7]"} |   47 |
          +-----------------------------------------------+------+
          1 row in set (0.00 sec)

     According to the output of 'JSON_STORAGE_SIZE()', the JSON document
     inserted into the column takes up 47 bytes.  Following an update,
     the function shows the storage used for the newly-set value:

          mysql> UPDATE jtable
          mysql>     SET jcol = '{"a": 4.55, "b": "wxyz", "c": "[true, false]"}';
          Query OK, 1 row affected (0.04 sec)
          Rows matched: 1  Changed: 1  Warnings: 0

          mysql> SELECT
              ->     jcol,
              ->     JSON_STORAGE_SIZE(jcol) AS Size
              -> FROM jtable;
          +------------------------------------------------+------+
          | jcol                                           | Size |
          +------------------------------------------------+------+
          | {"a": 4.55, "b": "wxyz", "c": "[true, false]"} |   56 |
          +------------------------------------------------+------+
          1 row in set (0.00 sec)

     This function also shows the space currently used to store a JSON
     document in a user variable:

          mysql> SET @j = '[100, "sakila", [1, 3, 5], 425.05]';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT @j, JSON_STORAGE_SIZE(@j) AS Size;
          +------------------------------------+------+
          | @j                                 | Size |
          +------------------------------------+------+
          | [100, "sakila", [1, 3, 5], 425.05] |   45 |
          +------------------------------------+------+
          1 row in set (0.00 sec)

          mysql> SET @j = JSON_SET(@j, '$[1]', "json");
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT @j, JSON_STORAGE_SIZE(@j) AS Size;
          +----------------------------------+------+
          | @j                               | Size |
          +----------------------------------+------+
          | [100, "json", [1, 3, 5], 425.05] |   43 |
          +----------------------------------+------+
          1 row in set (0.00 sec)

          mysql> SET @j = JSON_SET(@j, '$[2][0]', JSON_ARRAY(10, 20, 30));
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT @j, JSON_STORAGE_SIZE(@j) AS Size;
          +---------------------------------------------+------+
          | @j                                          | Size |
          +---------------------------------------------+------+
          | [100, "json", [[10, 20, 30], 3, 5], 425.05] |   56 |
          +---------------------------------------------+------+
          1 row in set (0.00 sec)

     For a JSON literal, this function also returns the current storage
     space used, as shown here:

          mysql> SELECT
              ->     JSON_STORAGE_SIZE('[100, "sakila", [1, 3, 5], 425.05]') AS A,
              ->     JSON_STORAGE_SIZE('{"a": 1000, "b": "a", "c": "[1, 3, 5, 7]"}') AS B,
              ->     JSON_STORAGE_SIZE('{"a": 1000, "b": "wxyz", "c": "[1, 3, 5, 7]"}') AS C,
              ->     JSON_STORAGE_SIZE('[100, "json", [[10, 20, 30], 3, 5], 425.05]') AS D;
          +----+----+----+----+
          | A  | B  | C  | D  |
          +----+----+----+----+
          | 45 | 44 | 47 | 56 |
          +----+----+----+----+
          1 row in set (0.00 sec)

     This function was added in MySQL 5.7.22.

12.16.7 JSON Path Syntax
------------------------

Many of the functions described in previous sections require a path
expression in order to identify a specific element in a JSON document.
A path consists of the path's scope followed by one or more path legs.
For paths used in MySQL JSON functions, the scope is always the document
being searched or otherwise operated on, represented by a leading '$'
character.  Path legs are separated by period characters ('.').  Cells
in arrays are represented by '[N]', where N is a non-negative integer.
Names of keys must be double-quoted strings or valid ECMAScript
identifiers (see
http://www.ecma-international.org/ecma-262/5.1/#sec-7.6).  Path
expressions, like JSON text, should be encoded using the 'ascii',
'utf8', or 'utf8mb4' character set.  Other character encodings are
implicitly coerced to 'utf8mb4'.  The complete syntax is shown here:

     PATHEXPRESSION:
         SCOPE[(PATHLEG)*]

     PATHLEG:
         MEMBER | ARRAYLOCATION | DOUBLEASTERISK

     MEMBER:
         PERIOD ( KEYNAME | ASTERISK )

     ARRAYLOCATION:
         LEFTBRACKET ( NONNEGATIVEINTEGER | ASTERISK ) RIGHTBRACKET

     KEYNAME:
         ESIDENTIFIER | DOUBLEQUOTEDSTRING

     DOUBLEASTERISK:
         '**'

     PERIOD:
         '.'

     ASTERISK:
         '*'

     LEFTBRACKET:
         '['

     RIGHTBRACKET:
         ']'

As noted previously, in MySQL, the scope of the path is always the
document being operated on, represented as '$'.  You can use ''$'' as a
synonynm for the document in JSON path expressions.

*Note*:

Some implementations support column references for scopes of JSON paths;
currently, MySQL does not support these.

The wildcard '*' and '**' tokens are used as follows:

   * '.*' represents the values of all members in the object.

   * '[*]' represents the values of all cells in the array.

   * '[PREFIX]**SUFFIX' represents all paths beginning with PREFIX and
     ending with SUFFIX.  PREFIX is optional, while SUFFIX is required;
     in other words, a path may not end in '**'.

     In addition, a path may not contain the sequence '***'.

For path syntax examples, see the descriptions of the various JSON
fuinctions that take paths as arguments, such as 'JSON_CONTAINS_PATH()',
'JSON_SET()', and 'JSON_REPLACE()'.  For examples which include the use
of the '*' and '**' wildcards, see the description of the
'JSON_SEARCH()' function.

12.17 Functions Used with Global Transaction IDs
================================================

The functions described in this section are used with GTID-based
replication.  It is important to keep in mind that all of these
functions take string representations of GTID sets as arguments--as
such, the GTID sets must always be quoted when used with them.  See
replication-gtids-concepts-gtid-sets for more information.

The union of two GTID sets is simply their representations as strings,
joined together with an interposed comma.  In other words, you can
define a very simple function for obtaining the union of two GTID sets,
similar to that created here:

     CREATE FUNCTION GTID_UNION(g1 TEXT, g2 TEXT)
         RETURNS TEXT DETERMINISTIC
         RETURN CONCAT(g1,',',g2);

For more information about GTIDs and how these GTID functions are used
in practice, see replication-gtids.

*GTID Functions*

Name                          Description

'GTID_SUBSET()'               Return true if all GTIDs in subset are
                              also in set; otherwise false.

'GTID_SUBTRACT()'             Return all GTIDs in set that are not in
                              subset.

'WAIT_FOR_EXECUTED_GTID_SET()'Wait until the given GTIDs have executed
                              on slave.

'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()'Wait until the given GTIDs have executed
                              on slave.

   *
     'GTID_SUBSET(SUBSET,SET)'

     Given two sets of global transaction IDs SUBSET and SET, returns
     true if all GTIDs in SUBSET are also in SET.  Returns false
     otherwise.

     The GTID sets used with this function are represented as strings,
     as shown in the following examples:

          mysql> SELECT GTID_SUBSET('3E11FA47-71CA-11E1-9E33-C80AA9429562:23',
              ->     '3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57')\G
          *************************** 1. row ***************************
          GTID_SUBSET('3E11FA47-71CA-11E1-9E33-C80AA9429562:23',
              '3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57'): 1
          1 row in set (0.00 sec)

          mysql> SELECT GTID_SUBSET('3E11FA47-71CA-11E1-9E33-C80AA9429562:23-25',
              ->     '3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57')\G
          *************************** 1. row ***************************
          GTID_SUBSET('3E11FA47-71CA-11E1-9E33-C80AA9429562:23-25',
              '3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57'): 1
          1 row in set (0.00 sec)

          mysql> SELECT GTID_SUBSET('3E11FA47-71CA-11E1-9E33-C80AA9429562:20-25',
              ->     '3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57')\G
          *************************** 1. row ***************************
          GTID_SUBSET('3E11FA47-71CA-11E1-9E33-C80AA9429562:20-25',
              '3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57'): 0
          1 row in set (0.00 sec)

   *
     'GTID_SUBTRACT(SET,SUBSET)'

     Given two sets of global transaction IDs SUBSET and SET, returns
     only those GTIDs from SET that are not in SUBSET.

     All GTID sets used with this function are represented as strings
     and must be quoted, as shown in these examples:

          mysql> SELECT GTID_SUBTRACT('3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57',
              ->     '3E11FA47-71CA-11E1-9E33-C80AA9429562:21')\G
          *************************** 1. row ***************************
          GTID_SUBTRACT('3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57',
              '3E11FA47-71CA-11E1-9E33-C80AA9429562:21'): 3e11fa47-71ca-11e1-9e33-c80aa9429562:22-57
          1 row in set (0.00 sec)

          mysql> SELECT GTID_SUBTRACT('3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57',
              ->     '3E11FA47-71CA-11E1-9E33-C80AA9429562:20-25')\G
          *************************** 1. row ***************************
          GTID_SUBTRACT('3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57',
              '3E11FA47-71CA-11E1-9E33-C80AA9429562:20-25'): 3e11fa47-71ca-11e1-9e33-c80aa9429562:26-57
          1 row in set (0.00 sec)

          mysql> SELECT GTID_SUBTRACT('3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57',
              ->     '3E11FA47-71CA-11E1-9E33-C80AA9429562:23-24')\G
          *************************** 1. row ***************************
          GTID_SUBTRACT('3E11FA47-71CA-11E1-9E33-C80AA9429562:21-57',
              '3E11FA47-71CA-11E1-9E33-C80AA9429562:23-24'): 3e11fa47-71ca-11e1-9e33-c80aa9429562:21-22:25-57
          1 row in set (0.01 sec)

   *
     'WAIT_FOR_EXECUTED_GTID_SET(GTID_SET[, TIMEOUT])'

     Wait until the server has applied all of the transactions whose
     global transaction identifiers are contained in GTID_SET; that is,
     until the condition GTID_SUBSET(GTID_SUBSET,
     '@@global.gtid_executed') holds.  See
     replication-gtids-concepts for a definition of GTID sets.

     If a timeout is specified, and TIMEOUT seconds elapse before all of
     the transactions in the GTID set have been applied, the function
     stops waiting.  TIMEOUT is optional, and the default timeout is 0
     seconds, in which case the function always waits until all of the
     transactions in the GTID set have been applied.

     'WAIT_FOR_EXECUTED_GTID_SET()' monitors all the GTIDs that are
     applied on the server, including transactions that arrive from all
     replication channels and user clients.  It does not take into
     account whether replication channels have been started or stopped.

     For more information, see replication-gtids.

     GTID sets used with this function are represented as strings and so
     must be quoted as shown in the following example:

          mysql> SELECT WAIT_FOR_EXECUTED_GTID_SET('3E11FA47-71CA-11E1-9E33-C80AA9429562:1-5');
                  -> 0

     For a syntax description for GTID sets, see
     replication-gtids-concepts.

     For 'WAIT_FOR_EXECUTED_GTID_SET()', the return value is the state
     of the query, where 0 represents success, and 1 represents timeout.
     Any other failures generate an error.

     'gtid_mode' cannot be changed to OFF while any client is using this
     function to wait for GTIDs to be applied.

   *
     'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS(GTID_SET[, TIMEOUT][,CHANNEL])'

     'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()' is similar to
     'WAIT_FOR_EXECUTED_GTID_SET()' in that it waits until all of the
     transactions whose global transaction identifiers are contained in
     GTID_SET have been applied, or until TIMEOUT seconds have elapsed,
     whichever occurs first.  However,
     'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()' applies to a specific
     replication channel, and stops only after the transactions have
     been applied on the specified channel, for which the applier must
     be running.  In contrast, 'WAIT_FOR_EXECUTED_GTID_SET()' stops
     after the transactions have been applied, regardless of where they
     were applied (on any replication channel or any user client), and
     whether or not any replication channels are running.

     The CHANNEL option names which replication channel the function
     applies to.  If no channel is named and no channels other than the
     default replication channel exist, the function applies to the
     default replication channel.  If multiple replication channels
     exist, you must specify a channel as otherwise it is not known
     which replication channel the function applies to.  See
     replication-channels for more information on replication
     channels.

     *Note*:

     Because 'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()' applies to a specific
     replication channel, if an expected transaction arrives on a
     different replication channel or from a user client, for example in
     a failover or manual recovery situation, the function can hang
     indefinitely if no timeout is set.  Use
     'WAIT_FOR_EXECUTED_GTID_SET()' instead to ensure correct handling
     of transactions in these situations.

     GTID sets used with 'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()' are
     represented as strings and must be quoted in the same way as for
     'WAIT_FOR_EXECUTED_GTID_SET()'.  For
     'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()', the return value for the
     function is an arbitrary positive number.  If GTID-based
     replication is not active (that is, if the value of the 'gtid_mode'
     variable is OFF), then this value is undefined and
     'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()' returns NULL. If the slave is
     not running then the function also returns NULL.

     'gtid_mode' cannot be changed to OFF while any client is using this
     function to wait for GTIDs to be applied.

12.18 MySQL Enterprise Encryption Functions
===========================================

*Note*:

MySQL Enterprise Encryption is an extension included in MySQL Enterprise
Edition, a commercial product.  To learn more about commercial products,
<http://www.mysql.com/products/>.

MySQL Enterprise Edition includes a set of encryption functions based on
the OpenSSL library that expose OpenSSL capabilities at the SQL level.
These functions enable Enterprise applications to perform the following
operations:

   * Implement added data protection using public-key asymmetric
     cryptography

   * Create public and private keys and digital signatures

   * Perform asymmetric encryption and decryption

   * Use cryptographic hashing for digital signing and data verification
     and validation

Enterprise Encryption supports the RSA, DSA, and DH cryptographic
algorithms.

Enterprise Encryption is supplied as a user-defined function (UDF)
library, from which individual functions can be installed individually.

12.18.1 Enterprise Encryption Installation
------------------------------------------

Enterprise Encryption functions are located in a user-defined function
(UDF) library file installed in the plugin directory (the directory
named by the 'plugin_dir' system variable).  The UDF library base name
is 'openssl_udf' and the suffix is platform dependent.  For example, the
file name on Linux or Windows is 'openssl_udf.so' or 'openssl_udf.dll',
respectively.

To install functions from the library file, use the 'CREATE FUNCTION'
statement.  To load all functions from
the library, use this set of statements (adjust the file name suffix as
necessary):

     CREATE FUNCTION asymmetric_decrypt RETURNS STRING
       SONAME 'openssl_udf.so';
     CREATE FUNCTION asymmetric_derive RETURNS STRING
       SONAME 'openssl_udf.so';
     CREATE FUNCTION asymmetric_encrypt RETURNS STRING
       SONAME 'openssl_udf.so';
     CREATE FUNCTION asymmetric_sign RETURNS STRING
       SONAME 'openssl_udf.so';
     CREATE FUNCTION asymmetric_verify RETURNS INTEGER
       SONAME 'openssl_udf.so';
     CREATE FUNCTION create_asymmetric_priv_key RETURNS STRING
       SONAME 'openssl_udf.so';
     CREATE FUNCTION create_asymmetric_pub_key RETURNS STRING
       SONAME 'openssl_udf.so';
     CREATE FUNCTION create_dh_parameters RETURNS STRING
       SONAME 'openssl_udf.so';
     CREATE FUNCTION create_digest RETURNS STRING
       SONAME 'openssl_udf.so';

Once installed, UDFs remain installed across server restarts.  To unload
UDFs, use the 'DROP FUNCTION' statement.  For
example, to unload the key-generation functions, do this:

     DROP FUNCTION create_asymmetric_priv_key;
     DROP FUNCTION create_asymmetric_pub_key;

In the 'CREATE FUNCTION' and 'DROP FUNCTION'
statements, the function names must be
specified in lowercase.  This differs from their use at function
invocation time, for which you can use any lettercase.

The 'CREATE FUNCTION' and 'DROP FUNCTION'
statements require the 'INSERT' and 'DROP'
privilege, respectively, for the 'mysql' database.

12.18.2 Enterprise Encryption Usage and Examples
------------------------------------------------

To use Enterprise Encryption in applications, invoke the functions that
are appropriate for the operations you wish to perform.  This section
demonstrates how to carry out some representative tasks:

   * enterprise-encryption-usage-create-key-pair

   * enterprise-encryption-usage-encrypt-decrypt

   * enterprise-encryption-usage-create-digest

   * enterprise-encryption-usage-digital-signing

   * enterprise-encryption-usage-create-symmetic-key

   * enterprise-encryption-usage-limit-cpu

*Create a private/public key pair using RSA encryption*

     -- Encryption algorithm; can be 'DSA' or 'DH' instead
     SET @algo = 'RSA';
     -- Key length in bits; make larger for stronger keys
     SET @key_len = 1024;

     -- Create private key
     SET @priv = CREATE_ASYMMETRIC_PRIV_KEY(@algo, @key_len);
     -- Derive corresponding public key from private key, using same algorithm
     SET @pub = CREATE_ASYMMETRIC_PUB_KEY(@algo, @priv);

Now you can use the key pair to encrypt and decrypt data, sign and
verify data, or generate symmetric keys.

*Use the private key to encrypt data and the public key to decrypt it*

This requires that the members of the key pair be RSA keys.

     SET @ciphertext = ASYMMETRIC_ENCRYPT(@algo, 'My secret text', @priv);
     SET @cleartext = ASYMMETRIC_DECRYPT(@algo, @ciphertext, @pub);

Conversely, you can encrypt using the public key and decrypt using the
private key.

     SET @ciphertext = ASYMMETRIC_ENCRYPT(@algo, 'My secret text', @pub);
     SET @cleartext = ASYMMETRIC_DECRYPT(@algo, @ciphertext, @priv);

In either case, the algorithm specified for the encryption and
decryption functions must match that used to generate the keys.

*Generate a digest from a string*

     -- Digest type; can be 'SHA256', 'SHA384', or 'SHA512' instead
     SET @dig_type = 'SHA224';

     -- Generate digest string
     SET @dig = CREATE_DIGEST(@dig_type, 'My text to digest');

*Use the digest with a key pair*

The key pair can be used to sign data, then verify that the signature
matches the digest.

     -- Encryption algorithm; could be 'DSA' instead; keys must
     -- have been created using same algorithm
     SET @algo = 'RSA';

     -- Generate signature for digest and verify signature against digest
     SET @sig = ASYMMETRIC_SIGN(@algo, @dig, @priv, @dig_type);
     -- Verify signature against digest
     SET @verf = ASYMMETRIC_VERIFY(@algo, @dig, @sig, @pub, @dig_type);

*Create a symmetric key*

This requires DH private/public keys as inputs, created using a shared
symmetric secret.  Create the secret by passing the key length to
'CREATE_DH_PARAMETERS()', then pass the secret as the 'key length' to
'CREATE_ASYMMETRIC_PRIV_KEY()'.

     -- Generate DH shared symmetric secret
     SET @dhp = CREATE_DH_PARAMETERS(1024);
     -- Generate DH key pairs
     SET @algo = 'DH';
     SET @priv1 = CREATE_ASYMMETRIC_PRIV_KEY(@algo, @dhp);
     SET @pub1 = CREATE_ASYMMETRIC_PUB_KEY(@algo, @priv1);
     SET @priv2 = CREATE_ASYMMETRIC_PRIV_KEY(@algo, @dhp);
     SET @pub2 = CREATE_ASYMMETRIC_PUB_KEY(@algo, @priv2);

     -- Generate symmetric key using public key of first party,
     -- private key of second party
     SET @sym1 = ASYMMETRIC_DERIVE(@pub1, @priv2);

     -- Or use public key of second party, private key of first party
     SET @sym2 = ASYMMETRIC_DERIVE(@pub2, @priv1);

Key string values can be created at runtime and stored into a variable
or table using 'SET', 'SELECT', or
'INSERT'.:

     SET @priv1 = CREATE_ASYMMETRIC_PRIV_KEY('RSA', 1024);
     SELECT CREATE_ASYMMETRIC_PRIV_KEY('RSA', 1024) INTO @priv2;
     INSERT INTO t (key_col) VALUES(CREATE_ASYMMETRIC_PRIV_KEY('RSA', 1024));

Key string values stored in files can be read using the 'LOAD_FILE()'
function by users who have the 'FILE' privilege.

Digest and signature strings can be handled similarly.

*Limit CPU usage by key-generation operations*

The 'CREATE_ASYMMETRIC_PRIV_KEY()' and 'CREATE_DH_PARAMETERS()'
encryption functions take a key-length parameter, and the amount of CPU
resources required by these functions increases as the key length
increases.  For some installations, this might result in unacceptable
CPU usage if applications frequently generate excessively long keys.

OpenSSL imposes a minimum key length of 1,024 bits for all keys.
OpenSSL also imposes a maximum key length of 10,000 bits and 16,384 bits
for DSA and RSA keys, respectively, for 'CREATE_ASYMMETRIC_PRIV_KEY()',
and a maximum key length of 10,000 bits for 'CREATE_DH_PARAMETERS()'.
If those maximum values are too high, three environment variables are
available as of MySQL 5.7.17 to enable MySQL server administrators to
set lower maximum lengths for key generation, and thereby to limit CPU
usage:

   * 'MYSQL_OPENSSL_UDF_DSA_BITS_THRESHOLD': Maximum DSA key length in
     bits for 'CREATE_ASYMMETRIC_PRIV_KEY()'.  The minimum and maximum
     values for this variable are 1,024 and 10,000.

   * 'MYSQL_OPENSSL_UDF_RSA_BITS_THRESHOLD': Maximum RSA key length in
     bits for 'CREATE_ASYMMETRIC_PRIV_KEY()'.  The minimum and maximum
     values for this variable are 1,024 and 16,384.

   * 'MYSQL_OPENSSL_UDF_DH_BITS_THRESHOLD': Maximum key length in bits
     for 'CREATE_DH_PARAMETERS()'.  The minimum and maximum values for
     this variable are 1,024 and 10,000.

To use any of these environment variables, set them in the environment
of the process that starts the server.  If set, their values take
precedence over the maximum key lengths imposed by OpenSSL. For example,
to set a maximum key length of 4,096 bits for DSA and RSA keys for
'CREATE_ASYMMETRIC_PRIV_KEY()', set these variables:

     export MYSQL_OPENSSL_UDF_DSA_BITS_THRESHOLD=4096
     export MYSQL_OPENSSL_UDF_RSA_BITS_THRESHOLD=4096

The example uses Bourne shell syntax.  The syntax for other shells may
differ.

12.18.3 Enterprise Encryption Function Reference
------------------------------------------------

*MySQL Enterprise Encryption Functions*

Name                          Description

'ASYMMETRIC_DECRYPT()'        Decrypt ciphertext using private or
                              public key

'ASYMMETRIC_DERIVE()'         Derive symmetric key from asymmetric keys

'ASYMMETRIC_ENCRYPT()'        Encrypt cleartext using private or public
                              key

'ASYMMETRIC_SIGN()'           Generate signature from digest

'ASYMMETRIC_VERIFY()'         Verify that signature matches digest

'CREATE_ASYMMETRIC_PRIV_KEY()'Create private key

'CREATE_ASYMMETRIC_PUB_KEY()' Create public key

'CREATE_DH_PARAMETERS()'      Generate shared DH secret

'CREATE_DIGEST()'             Generate digest from string

12.18.4 Enterprise Encryption Function Descriptions
---------------------------------------------------

Enterprise Encryption functions have these general characteristics:

   * For arguments of the wrong type or an incorrect number of
     arguments, each function returns an error.

   * If the arguments are not suitable to permit a function to perform
     the requested operation, it returns 'NULL' or 0 as appropriate.
     This occurs, for example, if a function does not support a
     specified algorithm, a key length is too short or long, or a string
     expected to be a key string in PEM format is not a valid key.
     (OpenSSL imposes its own key-length limits, and server
     administrators can impose additional limits on maximum key length
     by setting environment variables.  See
     enterprise-encryption-usage.)

   * The underlying SSL library takes care of randomness initialization.

Several of the functions take an encryption algorithm argument.  The
following table summarizes the supported algorithms by function.

*Supported Algorithms by Function*

Function                             Supported Algorithms

'ASYMMETRIC_DECRYPT()'               RSA

'ASYMMETRIC_DERIVE()'                DH

'ASYMMETRIC_ENCRYPT()'               RSA

'ASYMMETRIC_SIGN()'                  RSA, DSA

'ASYMMETRIC_VERIFY()'                RSA, DSA

'CREATE_ASYMMETRIC_PRIV_KEY()'       RSA, DSA, DH

'CREATE_ASYMMETRIC_PUB_KEY()'        RSA, DSA, DH

'CREATE_DH_PARAMETERS()'             DH

*Note*:

Although you can create keys using any of the RSA, DSA, or DH encryption
algorithms, other functions that take key arguments might accept only
certain types of keys.  For example, 'ASYMMETRIC_ENCRYPT()' and
'ASYMMETRIC_DECRYPT()' accept only RSA keys.

The following descriptions describe the calling sequences for Enterprise
Encryption functions.  For additional examples and discussion, see
enterprise-encryption-usage.

   *
     'ASYMMETRIC_DECRYPT(ALGORITHM, CRYPT_STR, KEY_STR)'

     Decrypts an encrypted string using the given algorithm and key
     string, and returns the resulting cleartext as a binary string.  If
     decryption fails, the result is 'NULL'.

     KEY_STR must be a valid key string in PEM format.  For successful
     decryption, it must be the public or private key string
     corresponding to the private or public key string used with
     'ASYMMETRIC_ENCRYPT()' to produce the encrypted string.  ALGORITHM
     indicates the encryption algorithm used to create the key.

     Supported ALGORITHM values: ''RSA''

     For a usage example, see the description of 'ASYMMETRIC_ENCRYPT()'.

   *
     'ASYMMETRIC_DERIVE(PUB_KEY_STR, PRIV_KEY_STR)'

     Derives a symmetric key using the private key of one party and the
     public key of another, and returns the resulting key as a binary
     string.  If key derivation fails, the result is 'NULL'.

     PUB_KEY_STR and PRIV_KEY_STR must be valid key strings in PEM
     format.  They must be created using the DH algorithm.

     Suppose that you have two pairs of public and private keys:

          SET @dhp = CREATE_DH_PARAMETERS(1024);
          SET @priv1 = CREATE_ASYMMETRIC_PRIV_KEY('DH', @dhp);
          SET @pub1 = CREATE_ASYMMETRIC_PUB_KEY('DH', @priv1);
          SET @priv2 = CREATE_ASYMMETRIC_PRIV_KEY('DH', @dhp);
          SET @pub2 = CREATE_ASYMMETRIC_PUB_KEY('DH', @priv2);

     Suppose further that you use the private key from one pair and the
     public key from the other pair to create a symmetric key string.
     Then this symmetric key identity relationship holds:

          ASYMMETRIC_DERIVE(@pub1, @priv2) = ASYMMETRIC_DERIVE(@pub2, @priv1)

   *
     'ASYMMETRIC_ENCRYPT(ALGORITHM, STR, KEY_STR)'

     Encrypts a string using the given algorithm and key string, and
     returns the resulting ciphertext as a binary string.  If encryption
     fails, the result is 'NULL'.

     The STR length cannot be greater than the KEY_STR length − 11, in
     bytes

     KEY_STR must be a valid key string in PEM format.  ALGORITHM
     indicates the encryption algorithm used to create the key.

     Supported ALGORITHM values: ''RSA''

     To encrypt a string, pass a private or public key string to
     'ASYMMETRIC_ENCRYPT()'.  To recover the original unencrypted
     string, pass the encrypted string to 'ASYMMETRIC_DECRYPT()', along
     with the public or private key string correponding to the private
     or public key string used for encryption.

          -- Generate private/public key pair
          SET @priv = CREATE_ASYMMETRIC_PRIV_KEY('RSA', 1024);
          SET @pub = CREATE_ASYMMETRIC_PUB_KEY('RSA', @priv);

          -- Encrypt using private key, decrypt using public key
          SET @ciphertext = ASYMMETRIC_ENCRYPT('RSA', 'The quick brown fox', @priv);
          SET @cleartext = ASYMMETRIC_DECRYPT('RSA', @ciphertext, @pub);

          -- Encrypt using public key, decrypt using private key
          SET @ciphertext = ASYMMETRIC_ENCRYPT('RSA', 'The quick brown fox', @pub);
          SET @cleartext = ASYMMETRIC_DECRYPT('RSA', @ciphertext, @priv);

     Suppose that:

          SET @s = a string to be encrypted
          SET @priv = a valid private RSA key string in PEM format
          SET @pub = the corresponding public RSA key string in PEM format

     Then these identity relationships hold:

          ASYMMETRIC_DECRYPT('RSA', ASYMMETRIC_ENCRYPT('RSA', @s, @priv), @pub) = @s
          ASYMMETRIC_DECRYPT('RSA', ASYMMETRIC_ENCRYPT('RSA', @s, @pub), @priv) = @s

   *
     'ASYMMETRIC_SIGN(ALGORITHM, DIGEST_STR, PRIV_KEY_STR, DIGEST_TYPE)'

     Signs a digest string using a private key string, and returns the
     signature as a binary string.  If signing fails, the result is
     'NULL'.

     DIGEST_STR is the digest string.  It can be generated by calling
     'CREATE_DIGEST()'.  DIGEST_TYPE indicates the digest algorithm used
     to generate the digest string.

     PRIV_KEY_STR is the private key string to use for signing the
     digest string.  It must be a valid key string in PEM format.
     ALGORITHM indicates the encryption algorithm used to create the
     key.

     Supported ALGORITHM values: ''RSA'', ''DSA''

     Supported DIGEST_TYPE values: ''SHA224'', ''SHA256'', ''SHA384'',
     ''SHA512''

     For a usage example, see the description of 'ASYMMETRIC_VERIFY()'.

   *
     'ASYMMETRIC_VERIFY(ALGORITHM, DIGEST_STR, SIG_STR, PUB_KEY_STR,
     DIGEST_TYPE)'

     Verifies whether the signature string matches the digest string,
     and returns 1 or 0 to indicate whether verification succeeded or
     failed.

     DIGEST_STR is the digest string.  It can be generated by calling
     'CREATE_DIGEST()'.  DIGEST_TYPE indicates the digest algorithm used
     to generate the digest string.

     SIG_STR is the signature string.  It can be generated by calling
     'ASYMMETRIC_SIGN()'.

     PUB_KEY_STR is the public key string of the signer.  It corresponds
     to the private key passed to 'ASYMMETRIC_SIGN()' to generate the
     signature string and must be a valid key string in PEM format.
     ALGORITHM indicates the encryption algorithm used to create the
     key.

     Supported ALGORITHM values: ''RSA'', ''DSA''

     Supported DIGEST_TYPE values: ''SHA224'', ''SHA256'', ''SHA384'',
     ''SHA512''

          -- Set the encryption algorithm and digest type
          SET @algo = 'RSA';
          SET @dig_type = 'SHA224';

          -- Create private/public key pair
          SET @priv = CREATE_ASYMMETRIC_PRIV_KEY(@algo, 1024);
          SET @pub = CREATE_ASYMMETRIC_PUB_KEY(@algo, @priv);

          -- Generate digest from string
          SET @dig = CREATE_DIGEST(@dig_type, 'The quick brown fox');

          -- Generate signature for digest and verify signature against digest
          SET @sig = ASYMMETRIC_SIGN(@algo, @dig, @priv, @dig_type);
          SET @verf = ASYMMETRIC_VERIFY(@algo, @dig, @sig, @pub, @dig_type);

   *
     'CREATE_ASYMMETRIC_PRIV_KEY(ALGORITHM, {KEY_LEN|DH_SECRET})'

     Creates a private key using the given algorithm and key length or
     DH secret, and returns the key as a binary string in PEM format.
     If key generation fails, the result is 'NULL'.

     Supported ALGORITHM values: ''RSA'', ''DSA'', ''DH''

     Supported KEY_LEN values: The minimum key length in bits is 1,024.
     The maximum key length depends on the algorithm: 16,384 for RSA and
     10,000 for DSA. These key-length limits are constraints imposed by
     OpenSSL. Server administrators can impose additional limits on
     maximum key length by setting environment variables.  See
     enterprise-encryption-usage.

     For DH keys, pass a shared DH secret instead of a key length.  To
     create the secret, pass the key length to 'CREATE_DH_PARAMETERS()'.

     This example creates a 2,048-bit DSA private key, then derives a
     public key from the private key:

          SET @priv = CREATE_ASYMMETRIC_PRIV_KEY('DSA', 2048);
          SET @pub = CREATE_ASYMMETRIC_PUB_KEY('DSA', @priv);

     For an example showing DH key generation, see the description of
     'ASYMMETRIC_DERIVE()'.

     Some general considerations in choosing key lengths and encryption
     algorithms:

        * The strength of encryption for private and public keys
          increases with the key size, but the time for key generation
          increases as well.

        * Generation of DH keys takes much longer than RSA or RSA keys.

        * Asymmetric encryption functions are slower than symmetric
          functions.  If performance is an important factor and the
          functions are to be used very frequently, you are better off
          using symmetric encryption.  For example, consider using
          'AES_ENCRYPT()' and 'AES_DECRYPT()'.

   *
     'CREATE_ASYMMETRIC_PUB_KEY(ALGORITHM, PRIV_KEY_STR)'

     Derives a public key from the given private key using the given
     algorithm, and returns the key as a binary string in PEM format.
     If key derivation fails, the result is 'NULL'.

     PRIV_KEY_STR must be a valid key string in PEM format.  ALGORITHM
     indicates the encryption algorithm used to create the key.

     Supported ALGORITHM values: ''RSA'', ''DSA'', ''DH''

     For a usage example, see the description of
     'CREATE_ASYMMETRIC_PRIV_KEY()'.

   *
     'CREATE_DH_PARAMETERS(KEY_LEN)'

     Creates a shared secret for generating a DH private/public key pair
     and returns a binary string that can be passed to
     'CREATE_ASYMMETRIC_PRIV_KEY()'.  If secret generation fails, the
     result is null.

     Supported KEY_LEN values: The minimum and maximum key lengths in
     bits are 1,024 and 10,000.  These key-length limits are constraints
     imposed by OpenSSL. Server administrators can impose additional
     limits on maximum key length by setting environment variables.  See
     enterprise-encryption-usage.

     For an example showing how to use the return value for generating
     symmetric keys, see the description of 'ASYMMETRIC_DERIVE()'.

          SET @dhp = CREATE_DH_PARAMETERS(1024);

   *
     'CREATE_DIGEST(DIGEST_TYPE, STR)'

     Creates a digest from the given string using the given digest type,
     and returns the digest as a binary string.  If digest generation
     fails, the result is 'NULL'.

     Supported DIGEST_TYPE values: ''SHA224'', ''SHA256'', ''SHA384'',
     ''SHA512''

          SET @dig = CREATE_DIGEST('SHA512', The quick brown fox');

     The resulting digest string is suitable for use with
     'ASYMMETRIC_SIGN()' and 'ASYMMETRIC_VERIFY()'.

12.19 Aggregate (GROUP BY) Functions
====================================

12.19.1 Aggregate (GROUP BY) Function Descriptions
--------------------------------------------------

This section describes group (aggregate) functions that operate on sets
of values.

*Aggregate (GROUP BY) Functions*

Name                          Description

'AVG()'                       Return the average value of the argument

'BIT_AND()'                   Return bitwise AND

'BIT_OR()'                    Return bitwise OR

'BIT_XOR()'                   Return bitwise XOR

'COUNT()'                     Return a count of the number of rows
                              returned

'COUNT(DISTINCT)'             Return the count of a number of different
                              values

'GROUP_CONCAT()'              Return a concatenated string

'JSON_ARRAYAGG()'             Return result set as a single JSON array

'JSON_OBJECTAGG()'            Return result set as a single JSON object

'MAX()'                       Return the maximum value

'MIN()'                       Return the minimum value

'STD()'                       Return the population standard deviation

'STDDEV()'                    Return the population standard deviation

'STDDEV_POP()'                Return the population standard deviation

'STDDEV_SAMP()'               Return the sample standard deviation

'SUM()'                       Return the sum

'VAR_POP()'                   Return the population standard variance

'VAR_SAMP()'                  Return the sample variance

'VARIANCE()'                  Return the population standard variance

Unless otherwise stated, group functions ignore 'NULL' values.

If you use a group function in a statement containing no 'GROUP BY'
clause, it is equivalent to grouping on all rows.  For more information,
see group-by-handling.

For numeric arguments, the variance and standard deviation functions
return a 'DOUBLE' value.  The 'SUM()' and
'AVG()' functions return a 'DECIMAL' value for
exact-value arguments (integer or 'DECIMAL'),
and a 'DOUBLE' value for approximate-value
arguments (see 'FLOAT' or 'DOUBLE').

The 'SUM()' and 'AVG()' aggregate functions do not work with temporal
values.  (They convert the values to numbers, losing everything after
the first nonnumeric character.)  To work around this problem, convert
to numeric units, perform the aggregate operation, and convert back to a
temporal value.  Examples:

     SELECT SEC_TO_TIME(SUM(TIME_TO_SEC(TIME_COL))) FROM TBL_NAME;
     SELECT FROM_DAYS(SUM(TO_DAYS(DATE_COL))) FROM TBL_NAME;

Functions such as 'SUM()' or 'AVG()' that expect a numeric argument cast
the argument to a number if necessary.  For 'SET' or
'ENUM' values, the cast operation causes the underlying numeric
value to be used.

The 'BIT_AND()', 'BIT_OR()', and 'BIT_XOR()' aggregate functions perform
bit operations.  They require 'BIGINT'. (64-bit
integer) arguments and return 'BIGINT' values.
Arguments of other types are converted to 'BIGINT'.
and truncation might occur.  For information about a change in MySQL 8.0
that permits bit operations to take binary string type arguments (see
'BINARY', 'VARBINARY', and the
'BLOB' types), see bit-functions.

   *
     'AVG([DISTINCT] EXPR)'

     Returns the average value of 'EXPR'.  The 'DISTINCT' option can be
     used to return the average of the distinct values of EXPR.

     If there are no matching rows, 'AVG()' returns 'NULL'.

          mysql> SELECT student_name, AVG(test_score)
                 FROM student
                 GROUP BY student_name;

   *
     'BIT_AND(EXPR)'

     Returns the bitwise 'AND' of all bits in EXPR.  The calculation is
     performed with 64-bit (see 'BIGINT') precision.

     If there are no matching rows, 'BIT_AND()' returns a neutral value
     (all bits set to 1).

   *
     'BIT_OR(EXPR)'

     Returns the bitwise 'OR' of all bits in EXPR.  The calculation is
     performed with 64-bit (see 'BIGINT') precision.

     If there are no matching rows, 'BIT_OR()' returns a neutral value
     (all bits set to 0).

   *
     'BIT_XOR(EXPR)'

     Returns the bitwise 'XOR' of all bits in EXPR.  The calculation is
     performed with 64-bit (see 'BIGINT') precision.

     If there are no matching rows, 'BIT_XOR()' returns a neutral value
     (all bits set to 0).

   *
     'COUNT(EXPR)'

     Returns a count of the number of non-'NULL' values of EXPR in the
     rows retrieved by a 'SELECT' statement.  The result
     is a 'BIGINT' value.

     If there are no matching rows, 'COUNT()' returns '0'.

          mysql> SELECT student.student_name,COUNT(*)
                 FROM student,course
                 WHERE student.student_id=course.student_id
                 GROUP BY student_name;

     'COUNT(*)' is somewhat different in that it returns a count of the
     number of rows retrieved, whether or not they contain 'NULL'
     values.

     For 'MyISAM' tables, 'COUNT(*)' is optimized to return very quickly
     if the 'SELECT' retrieves from one table, no other
     columns are retrieved, and there is no 'WHERE' clause.  For
     example:

          mysql> SELECT COUNT(*) FROM student;

     This optimization only applies to 'MyISAM' tables, because an exact
     row count is stored for this storage engine and can be accessed
     very quickly.  'COUNT(1)' is only subject to the same optimization
     if the first column is defined as 'NOT NULL'.

     For transactional storage engines such as 'InnoDB', storing an
     exact row count is problematic because multiple transactions may be
     occurring, each of which may affect the count.  For more
     information about how 'InnoDB' handles 'COUNT(*)' operations, see
     innodb-restrictions.

   *
     'COUNT(DISTINCT EXPR,[EXPR...])'

     Returns a count of the number of rows with different non-'NULL'
     EXPR values.

     If there are no matching rows, 'COUNT(DISTINCT)' returns '0'.

          mysql> SELECT COUNT(DISTINCT results) FROM student;

     In MySQL, you can obtain the number of distinct expression
     combinations that do not contain 'NULL' by giving a list of
     expressions.  In standard SQL, you would have to do a concatenation
     of all expressions inside 'COUNT(DISTINCT ...)'.

   *
     'GROUP_CONCAT(EXPR)'

     This function returns a string result with the concatenated
     non-'NULL' values from a group.  It returns 'NULL' if there are no
     non-'NULL' values.  The full syntax is as follows:

          GROUP_CONCAT([DISTINCT] EXPR [,EXPR ...]
                       [ORDER BY {UNSIGNED_INTEGER | COL_NAME | EXPR}
                           [ASC | DESC] [,COL_NAME ...]]
                       [SEPARATOR STR_VAL])

          mysql> SELECT student_name,
                   GROUP_CONCAT(test_score)
                 FROM student
                 GROUP BY student_name;

     Or:

          mysql> SELECT student_name,
                   GROUP_CONCAT(DISTINCT test_score
                                ORDER BY test_score DESC SEPARATOR ' ')
                 FROM student
                 GROUP BY student_name;

     In MySQL, you can get the concatenated values of expression
     combinations.  To eliminate duplicate values, use the 'DISTINCT'
     clause.  To sort values in the result, use the 'ORDER BY' clause.
     To sort in reverse order, add the 'DESC' (descending) keyword to
     the name of the column you are sorting by in the 'ORDER BY' clause.
     The default is ascending order; this may be specified explicitly
     using the 'ASC' keyword.  The default separator between values in a
     group is comma (',').  To specify a separator explicitly, use
     'SEPARATOR' followed by the string literal value that should be
     inserted between group values.  To eliminate the separator
     altogether, specify 'SEPARATOR '''.

     The result is truncated to the maximum length that is given by the
     'group_concat_max_len' system variable, which has a default value
     of 1024.  The value can be set higher, although the effective
     maximum length of the return value is constrained by the value of
     'max_allowed_packet'.  The syntax to change the value of
     'group_concat_max_len' at runtime is as follows, where VAL is an
     unsigned integer:

          SET [GLOBAL | SESSION] group_concat_max_len = VAL;

     The return value is a nonbinary or binary string, depending on
     whether the arguments are nonbinary or binary strings.  The result
     type is 'TEXT' or 'BLOB' unless
     'group_concat_max_len' is less than or equal to 512, in which case
     the result type is 'VARCHAR' or 'VARBINARY'.

     See also 'CONCAT()' and 'CONCAT_WS()': string-functions.

   *
     'JSON_ARRAYAGG(COL_OR_EXPR)'

     Aggregates a result set as a single 'JSON' array whose
     elements consist of the rows.  The order of elements in this array
     is undefined.  The function acts on a column or an expression that
     evaluates to a single value.  Returns 'NULL' if the result contains
     no rows, or in the event of an error.

          mysql> SELECT o_id, attribute, value FROM t3;
          +------+-----------+-------+
          | o_id | attribute | value |
          +------+-----------+-------+
          |    2 | color     | red   |
          |    2 | fabric    | silk  |
          |    3 | color     | green |
          |    3 | shape     | square|
          +------+-----------+-------+
          4 rows in set (0.00 sec)

          mysql> SELECT o_id, JSON_ARRAYAGG(attribute) AS attributes
               > FROM t3 GROUP BY o_id;
          +------+---------------------+
          | o_id | attributes          |
          +------+---------------------+
          |    2 | ["color", "fabric"] |
          |    3 | ["color", "shape"]  |
          +------+---------------------+
          2 rows in set (0.00 sec)

     Added in MySQL 5.7.22.

   *
     'JSON_OBJECTAGG(KEY, VALUE)'

     Takes two column names or expressions as arguments, the first of
     these being used as a key and the second as a value, and returns a
     JSON object containing key-value pairs.  Returns 'NULL' if the
     result contains no rows, or in the event of an error.  An error
     occurs if any key name is 'NULL' or the number of arguments is not
     equal to 2.

          mysql> SELECT o_id, attribute, value FROM t3;
          +------+-----------+-------+
          | o_id | attribute | value |
          +------+-----------+-------+
          |    2 | color     | red   |
          |    2 | fabric    | silk  |
          |    3 | color     | green |
          |    3 | shape     | square|
          +------+-----------+-------+
          4 rows in set (0.00 sec)

          mysql> SELECT o_id, JSON_OBJECTAGG(attribute, value) FROM t3 GROUP BY o_id;
          +------+----------------------------------------+
          | o_id | JSON_OBJECTAGG(attribute, name)        |
          +------+----------------------------------------+
          |    2 | {"color": "red", "fabric": "silk"}     |
          |    3 | {"color": "green", "shape": "square"}  |
          +------+----------------------------------------+
          1 row in set (0.00 sec)

     Added in MySQL 5.7.22.

   *
     'MAX([DISTINCT] EXPR)'

     Returns the maximum value of EXPR.  'MAX()' may take a string
     argument; in such cases, it returns the maximum string value.  See
     mysql-indexes.  The 'DISTINCT' keyword can be used to find
     the maximum of the distinct values of EXPR, however, this produces
     the same result as omitting 'DISTINCT'.

     If there are no matching rows, 'MAX()' returns 'NULL'.

          mysql> SELECT student_name, MIN(test_score), MAX(test_score)
                 FROM student
                 GROUP BY student_name;

     For 'MAX()', MySQL currently compares 'ENUM' and
     'SET' columns by their string value rather than by the
     string's relative position in the set.  This differs from how
     'ORDER BY' compares them.

   *
     'MIN([DISTINCT] EXPR)'

     Returns the minimum value of EXPR.  'MIN()' may take a string
     argument; in such cases, it returns the minimum string value.  See
     mysql-indexes.  The 'DISTINCT' keyword can be used to find
     the minimum of the distinct values of EXPR, however, this produces
     the same result as omitting 'DISTINCT'.

     If there are no matching rows, 'MIN()' returns 'NULL'.

          mysql> SELECT student_name, MIN(test_score), MAX(test_score)
                 FROM student
                 GROUP BY student_name;

     For 'MIN()', MySQL currently compares 'ENUM' and
     'SET' columns by their string value rather than by the
     string's relative position in the set.  This differs from how
     'ORDER BY' compares them.

   *
     'STD(EXPR)'

     Returns the population standard deviation of EXPR.  'STD()' is a
     synonym for the standard SQL function 'STDDEV_POP()', provided as a
     MySQL extension.

     If there are no matching rows, 'STD()' returns 'NULL'.

   *
     'STDDEV(EXPR)'

     Returns the population standard deviation of EXPR.  'STDDEV()' is a
     synonym for the standard SQL function 'STDDEV_POP()', provided for
     compatibility with Oracle.

     If there are no matching rows, 'STDDEV()' returns 'NULL'.

   *
     'STDDEV_POP(EXPR)'

     Returns the population standard deviation of EXPR (the square root
     of 'VAR_POP()').  You can also use 'STD()' or 'STDDEV()', which are
     equivalent but not standard SQL.

     If there are no matching rows, 'STDDEV_POP()' returns 'NULL'.

   *
     'STDDEV_SAMP(EXPR)'

     Returns the sample standard deviation of EXPR (the square root of
     'VAR_SAMP()'.

     If there are no matching rows, 'STDDEV_SAMP()' returns 'NULL'.

   *
     'SUM([DISTINCT] EXPR)'

     Returns the sum of EXPR.  If the return set has no rows, 'SUM()'
     returns 'NULL'.  The 'DISTINCT' keyword can be used to sum only the
     distinct values of EXPR.

     If there are no matching rows, 'SUM()' returns 'NULL'.

   *
     'VAR_POP(EXPR)'

     Returns the population standard variance of EXPR.  It considers
     rows as the whole population, not as a sample, so it has the number
     of rows as the denominator.  You can also use 'VARIANCE()', which
     is equivalent but is not standard SQL.

     If there are no matching rows, 'VAR_POP()' returns 'NULL'.

   *
     'VAR_SAMP(EXPR)'

     Returns the sample variance of EXPR.  That is, the denominator is
     the number of rows minus one.

     If there are no matching rows, 'VAR_SAMP()' returns 'NULL'.

   *
     'VARIANCE(EXPR)'

     Returns the population standard variance of EXPR.  'VARIANCE()' is
     a synonym for the standard SQL function 'VAR_POP()', provided as a
     MySQL extension.

     If there are no matching rows, 'VARIANCE()' returns 'NULL'.

12.19.2 GROUP BY Modifiers
--------------------------

The 'GROUP BY' clause permits a 'WITH ROLLUP' modifier that causes
summary output to include extra rows that represent higher-level (that
is, super-aggregate) summary operations.  'ROLLUP' thus enables you to
answer questions at multiple levels of analysis with a single query.
For example, 'ROLLUP' can be used to provide support for OLAP (Online
Analytical Processing) operations.

Suppose that a 'sales' table has 'year', 'country', 'product', and
'profit' columns for recording sales profitability:

     CREATE TABLE sales
     (
         year    INT,
         country VARCHAR(20),
         product VARCHAR(32),
         profit  INT
     );

To summarize table contents per year, use a simple 'GROUP BY' like this:

     mysql> SELECT year, SUM(profit) AS profit
            FROM sales
            GROUP BY year ASC;
     +------+--------+
     | year | profit |
     +------+--------+
     | 2000 |   4525 |
     | 2001 |   3010 |
     +------+--------+

The output shows the total profit for each year.  To also determine the
total profit summed over all years, you must add up the individual
values yourself or run an additional query.  Or you can use 'ROLLUP',
which provides both levels of analysis with a single query.  Adding a
'WITH ROLLUP' modifier to the 'GROUP BY' clause causes the query to
produce another row that shows the grand total over all year values:

     mysql> SELECT year, SUM(profit) AS profit
            FROM sales
            GROUP BY year ASC WITH ROLLUP;
     +------+--------+
     | year | profit |
     +------+--------+
     | 2000 |   4525 |
     | 2001 |   3010 |
     | NULL |   7535 |
     +------+--------+

The 'NULL' value in the 'year' column identifies the grand total
super-aggregate line.

'ROLLUP' has a more complex effect when there are multiple 'GROUP BY'
columns.  In this case, each time there is a change in value in any but
the last grouping column, the query produces an extra super-aggregate
summary row.

For example, without 'ROLLUP', a summary of the 'sales' table based on
'year', 'country', and 'product' might look like this, where the output
indicates summary values only at the year/country/product level of
analysis:

     mysql> SELECT year, country, product, SUM(profit) AS profit
            FROM sales
            GROUP BY year ASC, country ASC, product ASC;
     +------+---------+------------+--------+
     | year | country | product    | profit |
     +------+---------+------------+--------+
     | 2000 | Finland | Computer   |   1500 |
     | 2000 | Finland | Phone      |    100 |
     | 2000 | India   | Calculator |    150 |
     | 2000 | India   | Computer   |   1200 |
     | 2000 | USA     | Calculator |     75 |
     | 2000 | USA     | Computer   |   1500 |
     | 2001 | Finland | Phone      |     10 |
     | 2001 | USA     | Calculator |     50 |
     | 2001 | USA     | Computer   |   2700 |
     | 2001 | USA     | TV         |    250 |
     +------+---------+------------+--------+

With 'ROLLUP' added, the query produces several extra rows:

     mysql> SELECT year, country, product, SUM(profit) AS profit
            FROM sales
            GROUP BY year ASC, country ASC, product ASC WITH ROLLUP;
     +------+---------+------------+--------+
     | year | country | product    | profit |
     +------+---------+------------+--------+
     | 2000 | Finland | Computer   |   1500 |
     | 2000 | Finland | Phone      |    100 |
     | 2000 | Finland | NULL       |   1600 |
     | 2000 | India   | Calculator |    150 |
     | 2000 | India   | Computer   |   1200 |
     | 2000 | India   | NULL       |   1350 |
     | 2000 | USA     | Calculator |     75 |
     | 2000 | USA     | Computer   |   1500 |
     | 2000 | USA     | NULL       |   1575 |
     | 2000 | NULL    | NULL       |   4525 |
     | 2001 | Finland | Phone      |     10 |
     | 2001 | Finland | NULL       |     10 |
     | 2001 | USA     | Calculator |     50 |
     | 2001 | USA     | Computer   |   2700 |
     | 2001 | USA     | TV         |    250 |
     | 2001 | USA     | NULL       |   3000 |
     | 2001 | NULL    | NULL       |   3010 |
     | NULL | NULL    | NULL       |   7535 |
     +------+---------+------------+--------+

Now the output includes summary information at four levels of analysis,
not just one:

   * Following each set of product rows for a given year and country, an
     extra summary row appears showing the total for all products.
     These rows have the 'product' column set to 'NULL'.

   * Following each set of rows for a given year, an extra summary row
     appears showing the total for all countries and products.  These
     rows have the 'country' and 'products' columns set to 'NULL'.

   * Finally, following all other rows, an extra summary row appears
     showing the grand total for all years, countries, and products.
     This row has the 'year', 'country', and 'products' columns set to
     'NULL'.

*Other Considerations When using ROLLUP*

The following discussion lists some behaviors specific to the MySQL
implementation of 'ROLLUP'.

When you use 'ROLLUP', you cannot also use an 'ORDER BY' clause to sort
the results.  In other words, 'ROLLUP' and 'ORDER BY' are mutually
exclusive in MySQL. However, you still have some control over sort
order.  'GROUP BY' in MySQL implicitly sorts results by default (in the
absence of 'ASC' or 'DESC' designators).  However, implicit 'GROUP BY'
sorting in MySQL is deprecated.  To achieve a specific sort order of
grouped results:

   * Use explicit 'ASC' and 'DESC' keywords with columns named in the
     'GROUP BY' list to specify sort order for individual columns.  In
     this case, the super-aggregate summary rows added by 'ROLLUP' still
     appear after the rows from which they are calculated, regardless of
     the sort order.

   * To work around the restriction that prevents using 'ROLLUP' with
     'ORDER BY', generate the grouped result set as a derived table and
     apply 'ORDER BY' to it.  For example:

          SELECT * FROM
          (SELECT year, SUM(profit) FROM sales GROUP BY year WITH ROLLUP) AS dt
          ORDER BY year;

     In this case, the super-aggregate summary rows sort with the rows
     from which they are calculated, and their placement depends on sort
     order (at the beginning for ascending sort, at the end for
     descending sort).

'LIMIT' can be used to restrict the number of rows returned to the
client.  'LIMIT' is applied after 'ROLLUP', so the limit applies against
the extra rows added by 'ROLLUP'.  For example:

     mysql> SELECT year, country, product, SUM(profit) AS profit
            FROM sales
            GROUP BY year ASC, country ASC, product ASC WITH ROLLUP
            LIMIT 5;
     +------+---------+------------+--------+
     | year | country | product    | profit |
     +------+---------+------------+--------+
     | 2000 | Finland | Computer   |   1500 |
     | 2000 | Finland | Phone      |    100 |
     | 2000 | Finland | NULL       |   1600 |
     | 2000 | India   | Calculator |    150 |
     | 2000 | India   | Computer   |   1200 |
     +------+---------+------------+--------+

Using 'LIMIT' with 'ROLLUP' may produce results that are more difficult
to interpret, because there is less context for understanding the
super-aggregate rows.

The 'NULL' indicators in each super-aggregate row are produced when the
row is sent to the client.  The server looks at the columns named in the
'GROUP BY' clause following the leftmost one that has changed value.
For any column in the result set with a name that matches any of those
names, its value is set to 'NULL'.  (If you specify grouping columns by
column position, the server identifies which columns to set to 'NULL' by
position.)

Because the 'NULL' values in the super-aggregate rows are placed into
the result set at such a late stage in query processing, you can test
them as 'NULL' values only in the select list or 'HAVING' clause.  You
cannot test them as 'NULL' values in join conditions or the 'WHERE'
clause to determine which rows to select.  For example, you cannot add
'WHERE product IS NULL' to the query to eliminate from the output all
but the super-aggregate rows.

The 'NULL' values do appear as 'NULL' on the client side and can be
tested as such using any MySQL client programming interface.  However,
at this point, you cannot distinguish whether a 'NULL' represents a
regular grouped value or a super-aggregate value.

A MySQL extension permits a column that does not appear in the 'GROUP
BY' list to be named in the select list.  (For information about
nonaggregated columns and 'GROUP BY', see group-by-handling.)
In this case, the server is free to choose any value from this
nonaggregated column in summary rows, and this includes the extra rows
added by 'WITH ROLLUP'.  For example, in the following query, 'country'
is a nonaggregated column that does not appear in the 'GROUP BY' list
and values chosen for this column are nondeterministic:

     mysql> SELECT year, country, SUM(profit) AS profit
            FROM sales
            GROUP BY year ASC WITH ROLLUP;
     +------+---------+--------+
     | year | country | profit |
     +------+---------+--------+
     | 2000 | India   |   4525 |
     | 2001 | USA     |   3010 |
     | NULL | USA     |   7535 |
     +------+---------+--------+

This behavior is permitted when the 'ONLY_FULL_GROUP_BY' SQL mode is not
enabled.  If that mode is enabled, the server rejects the query as
illegal because 'country' is not listed in the 'GROUP BY' clause.  With
'ONLY_FULL_GROUP_BY' enabled, you can still execute the query by using
the 'ANY_VALUE()' function for nondeterministic-value columns:

     mysql> SELECT year, ANY_VALUE(country) AS country, SUM(profit) AS profit
            FROM sales
            GROUP BY year ASC WITH ROLLUP;
     +------+---------+--------+
     | year | country | profit |
     +------+---------+--------+
     | 2000 | India   |   4525 |
     | 2001 | USA     |   3010 |
     | NULL | USA     |   7535 |
     +------+---------+--------+

12.19.3 MySQL Handling of GROUP BY
----------------------------------

SQL92 and earlier does not permit queries for which the select list,
'HAVING' condition, or 'ORDER BY' list refer to nonaggregated columns
that are not named in the 'GROUP BY' clause.  For example, this query is
illegal in standard SQL92 because the nonaggregated 'name' column in the
select list does not appear in the 'GROUP BY':

     SELECT o.custid, c.name, MAX(o.payment)
       FROM orders AS o, customers AS c
       WHERE o.custid = c.custid
       GROUP BY o.custid;

For the query to be legal in SQL92, the 'name' column must be omitted
from the select list or named in the 'GROUP BY' clause.

SQL99 and later permits such nonaggregates per optional feature T301 if
they are functionally dependent on 'GROUP BY' columns: If such a
relationship exists between 'name' and 'custid', the query is legal.
This would be the case, for example, were 'custid' a primary key of
'customers'.

MySQL 5.7.5 and up implements detection of functional dependence.  If
the 'ONLY_FULL_GROUP_BY' SQL mode is enabled (which it is by default),
MySQL rejects queries for which the select list, 'HAVING' condition, or
'ORDER BY' list refer to nonaggregated columns that are neither named in
the 'GROUP BY' clause nor are functionally dependent on them.  (Before
5.7.5, MySQL does not detect functional dependency and
'ONLY_FULL_GROUP_BY' is not enabled by default.  For a description of
pre-5.7.5 behavior, see the MySQL 5.6 Reference Manual
(http://dev.mysql.com/doc/refman/5.6/en/sql-mode.html).)

If 'ONLY_FULL_GROUP_BY' is disabled, a MySQL extension to the standard
SQL use of 'GROUP BY' permits the select list, 'HAVING' condition, or
'ORDER BY' list to refer to nonaggregated columns even if the columns
are not functionally dependent on 'GROUP BY' columns.  This causes MySQL
to accept the preceding query.  In this case, the server is free to
choose any value from each group, so unless they are the same, the
values chosen are nondeterministic, which is probably not what you want.
Furthermore, the selection of values from each group cannot be
influenced by adding an 'ORDER BY' clause.  Result set sorting occurs
after values have been chosen, and 'ORDER BY' does not affect which
value within each group the server chooses.  Disabling
'ONLY_FULL_GROUP_BY' is useful primarily when you know that, due to some
property of the data, all values in each nonaggregated column not named
in the 'GROUP BY' are the same for each group.

You can achieve the same effect without disabling 'ONLY_FULL_GROUP_BY'
by using 'ANY_VALUE()' to refer to the nonaggregated column.

The following discussion demonstrates functional dependence, the error
message MySQL produces when functional dependence is absent, and ways of
causing MySQL to accept a query in the absence of functional dependence.

This query might be invalid with 'ONLY_FULL_GROUP_BY' enabled because
the nonaggregated 'address' column in the select list is not named in
the 'GROUP BY' clause:

     SELECT name, address, MAX(age) FROM t GROUP BY name;

The query is valid if 'name' is a primary key of 't' or is a unique 'NOT
NULL' column.  In such cases, MySQL recognizes that the selected column
is functionally dependent on a grouping column.  For example, if 'name'
is a primary key, its value determines the value of 'address' because
each group has only one value of the primary key and thus only one row.
As a result, there is no randomness in the choice of 'address' value in
a group and no need to reject the query.

The query is invalid if 'name' is not a primary key of 't' or a unique
'NOT NULL' column.  In this case, no functional dependency can be
inferred and an error occurs:

     mysql> SELECT name, address, MAX(age) FROM t GROUP BY name;
     ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP
     BY clause and contains nonaggregated column 'mydb.t.address' which
     is not functionally dependent on columns in GROUP BY clause; this
     is incompatible with sql_mode=only_full_group_by

If you know that, _for a given data set,_ each 'name' value in fact
uniquely determines the 'address' value, 'address' is effectively
functionally dependent on 'name'.  To tell MySQL to accept the query,
you can use the 'ANY_VALUE()' function:

     SELECT name, ANY_VALUE(address), MAX(age) FROM t GROUP BY name;

Alternatively, disable 'ONLY_FULL_GROUP_BY'.

The preceding example is quite simple, however.  In particular, it is
unlikely you would group on a single primary key column because every
group would contain only one row.  For addtional examples demonstrating
functional dependence in more complex queries, see
group-by-functional-dependence.

If a query has aggregate functions and no 'GROUP BY' clause, it cannot
have nonaggregated columns in the select list, 'HAVING' condition, or
'ORDER BY' list with 'ONLY_FULL_GROUP_BY' enabled:

     mysql> SELECT name, MAX(age) FROM t;
     ERROR 1140 (42000): In aggregated query without GROUP BY, expression
     #1 of SELECT list contains nonaggregated column 'mydb.t.name'; this
     is incompatible with sql_mode=only_full_group_by

Without 'GROUP BY', there is a single group and it is nondeterministic
which 'name' value to choose for the group.  Here, too, 'ANY_VALUE()'
can be used, if it is immaterial which 'name' value MySQL chooses:

     SELECT ANY_VALUE(name), MAX(age) FROM t;

In MySQL 5.7.5 and higher, 'ONLY_FULL_GROUP_BY' also affects handling of
queries that use 'DISTINCT' and 'ORDER BY'.  Consider the case of a
table 't' with three columns 'c1', 'c2', and 'c3' that contains these
rows:

     c1 c2 c3
     1  2  A
     3  4  B
     1  2  C

Suppose that we execute the following query, expecting the results to be
ordered by 'c3':

     SELECT DISTINCT c1, c2 FROM t ORDER BY c3;

To order the result, duplicates must be eliminated first.  But to do so,
should we keep the first row or the third?  This arbitrary choice
influences the retained value of 'c3', which in turn influences ordering
and makes it arbitrary as well.  To prevent this problem, a query that
has 'DISTINCT' and 'ORDER BY' is rejected as invalid if any 'ORDER BY'
expression does not satisfy at least one of these conditions:

   * The expression is equal to one in the select list

   * All columns referenced by the expression and belonging to the
     query's selected tables are elements of the select list

Another MySQL extension to standard SQL permits references in the
'HAVING' clause to aliased expressions in the select list.  For example,
the following query returns 'name' values that occur only once in table
'orders':

     SELECT name, COUNT(name) FROM orders
       GROUP BY name
       HAVING COUNT(name) = 1;

The MySQL extension permits the use of an alias in the 'HAVING' clause
for the aggregated column:

     SELECT name, COUNT(name) AS c FROM orders
       GROUP BY name
       HAVING c = 1;

*Note*:

Before MySQL 5.7.5, enabling 'ONLY_FULL_GROUP_BY' disables this
extension, thus requiring the 'HAVING' clause to be written using
unaliased expressions.

Standard SQL permits only column expressions in 'GROUP BY' clauses, so a
statement such as this is invalid because 'FLOOR(value/100)' is a
noncolumn expression:

     SELECT id, FLOOR(value/100)
       FROM TBL_NAME
       GROUP BY id, FLOOR(value/100);

MySQL extends standard SQL to permit noncolumn expressions in 'GROUP BY'
clauses and considers the preceding statement valid.

Standard SQL also does not permit aliases in 'GROUP BY' clauses.  MySQL
extends standard SQL to permit aliases, so another way to write the
query is as follows:

     SELECT id, FLOOR(value/100) AS val
       FROM TBL_NAME
       GROUP BY id, val;

The alias 'val' is considered a column expression in the 'GROUP BY'
clause.

In the presence of a noncolumn expression in the 'GROUP BY' clause,
MySQL recognizes equality between that expression and expressions in the
select list.  This means that with 'ONLY_FULL_GROUP_BY' SQL mode
enabled, the query containing 'GROUP BY id, FLOOR(value/100)' is valid
because that same 'FLOOR()' expression occurs in the select list.
However, MySQL does not try to recognize functional dependence on 'GROUP
BY' noncolumn expressions, so the following query is invalid with
'ONLY_FULL_GROUP_BY' enabled, even though the third selected expression
is a simple formula of the 'id' column and the 'FLOOR()' expression in
the 'GROUP BY' clause:

     SELECT id, FLOOR(value/100), id+FLOOR(value/100)
       FROM TBL_NAME
       GROUP BY id, FLOOR(value/100);

A workaround is to use a derived table:

     SELECT id, F, id+F
       FROM
         (SELECT id, FLOOR(value/100) AS F
          FROM TBL_NAME
          GROUP BY id, FLOOR(value/100)) AS dt;

12.19.4 Detection of Functional Dependence
------------------------------------------

The following discussion provides several examples of the ways in which
MySQL detects functional dependencies.  The examples use this notation:

     {X} -> {Y}

Understand this as 'X uniquely determines Y,' which also means that Y is
functionally dependent on X.

The examples use the 'world' database, which can be downloaded from the
MySQL Documentation page (http://dev.mysql.com/doc/index-other.html).
You can find details on how to install the database on the same page.

   * functional-dependence-keys

   * functional-dependence-multiple-column-keys

   * functional-dependence-special-cases

   * functional-dependence-views

   * functional-dependence-combinations

*Functional Dependencies Derived from Keys*

The following query selects, for each country, a count of spoken
languages:

     SELECT co.Name, COUNT(*)
     FROM countrylanguage cl, country co
     WHERE cl.CountryCode = co.Code
     GROUP BY co.Code;

'co.Code' is a primary key of 'co', so all columns of 'co' are
functionally dependent on it, as expressed using this notation:

     {co.Code} -> {co.*}

Thus, 'co.name' is functionally dependent on 'GROUP BY' columns and the
query is valid.

A 'UNIQUE' index over a 'NOT NULL' column could be used instead of a
primary key and the same functional dependence would apply.  (This is
not true for a 'UNIQUE' index that permits 'NULL' values because it
permits multiple 'NULL' values and in that case uniqueness is lost.)

*Functional Dependencies Derived from Multiple-Column Keys and from
Equalities*

This query selects, for each country, a list of all spoken languages and
how many people speak them:

     SELECT co.Name, cl.Language,
     cl.Percentage * co.Population / 100.0 AS SpokenBy
     FROM countryLanguage cl, country co
     WHERE cl.CountryCode = co.Code
     GROUP BY cl.CountryCode, cl.Language;

The pair ('cl.CountryCode', 'cl.Language') is a two-column composite
primary key of 'cl', so that column pair uniquely determines all columns
of 'cl':

     {cl.CountryCode, cl.Language} -> {cl.*}

Moreover, because of the equality in the 'WHERE' clause:

     {cl.CountryCode} -> {co.Code}

And, because 'co.Code' is primary key of 'co':

     {co.Code} -> {co.*}

'Uniquely determines' relationships are transitive, therefore:

     {cl.CountryCode, cl.Language} -> {cl.*,co.*}

As a result, the query is valid.

As with the previous example, a 'UNIQUE' key over 'NOT NULL' columns
could be used instead of a primary key.

An 'INNER JOIN' condition can be used instead of 'WHERE'.  The same
functional dependencies apply:

     SELECT co.Name, cl.Language,
     cl.Percentage * co.Population/100.0 AS SpokenBy
     FROM countrylanguage cl INNER JOIN country co
     ON cl.CountryCode = co.Code
     GROUP BY cl.CountryCode, cl.Language;

*Functional Dependency Special Cases*

Whereas an equality test in a 'WHERE' condition or 'INNER JOIN'
condition is symmetric, an equality test in an outer join condition is
not, because tables play different roles.

Assume that referential integrity has been accidentally broken and there
exists a row of 'countrylanguage' without a corresponding row in
'country'.  Consider the same query as in the previous example, but with
a 'LEFT JOIN':

     SELECT co.Name, cl.Language,
     cl.Percentage * co.Population/100.0 AS SpokenBy
     FROM countrylanguage cl LEFT JOIN country co
     ON cl.CountryCode = co.Code
     GROUP BY cl.CountryCode, cl.Language;

For a given value of 'cl.CountryCode', the value of 'co.Code' in the
join result is either found in a matching row (determined by
'cl.CountryCode') or is 'NULL'-complemented if there is no match (also
determined by 'cl.CountryCode').  In each case, this relationship
applies:

     {cl.CountryCode} -> {co.Code}

'cl.CountryCode' is itself functionally dependent on {'cl.CountryCode',
'cl.Language'} which is a primary key.

If in the join result 'co.Code' is 'NULL'-complemented, 'co.Name' is as
well.  If 'co.Code' is not 'NULL'-complemented, then because 'co.Code'
is a primary key, it determines 'co.Name'.  Therefore, in all cases:

     {co.Code} -> {co.Name}

Which yields:

     {cl.CountryCode, cl.Language} -> {cl.*,co.*}

As a result, the query is valid.

However, suppose that the tables are swapped, as in this query:

     SELECT co.Name, cl.Language,
     cl.Percentage * co.Population/100.0 AS SpokenBy
     FROM country co LEFT JOIN countrylanguage cl
     ON cl.CountryCode = co.Code
     GROUP BY cl.CountryCode, cl.Language;

Now this relationship does _not_ apply:

     {cl.CountryCode, cl.Language} -> {cl.*,co.*}

Indeed, all 'NULL'-complemented rows made for 'cl' will be put into a
single group (they have both 'GROUP BY' columns equal to 'NULL'), and
inside this group the value of 'co.Name' can vary.  The query is invalid
and MySQL rejects it.

Functional dependence in outer joins is thus linked to whether
determinant columns belong to the left or right side of the 'LEFT JOIN'.
Determination of functional dependence becomes more complex if there are
nested outer joins or the join condition does not consist entirely of
equality comparisons.

*Functional Dependencies and Views*

Suppose that a view on countries produces their code, their name in
uppercase, and how many different official languages they have:

     CREATE VIEW country2 AS
     SELECT co.Code, UPPER(co.Name) AS UpperName,
     COUNT(cl.Language) AS OfficialLanguages
     FROM country AS co JOIN countrylanguage AS cl
     ON cl.CountryCode = co.Code
     WHERE cl.isOfficial = 'T'
     GROUP BY co.Code;

This definition is valid because:

     {co.Code} -> {co.*}

In the view result, the first selected column is 'co.Code', which is
also the group column and thus determines all other selected
expressions:

     {country2.Code} -> {country2.*}

MySQL understands this and uses this information, as described
following.

This query displays countries, how many different official languages
they have, and how many cities they have, by joining the view with the
'city' table:

     SELECT co2.Code, co2.UpperName, co2.OfficialLanguages,
     COUNT(*) AS Cities
     FROM country2 AS co2 JOIN city ci
     ON ci.CountryCode = co2.Code
     GROUP BY co2.Code;

This query is valid because, as seen previously:

     {co2.Code} -> {co2.*}

MySQL is able to discover a functional dependency in the result of a
view and use that to validate a query which uses the view.  The same
would be true if 'country2' were a derived table, as in:

     SELECT co2.Code, co2.UpperName, co2.OfficialLanguages,
     COUNT(*) AS Cities
     FROM
     (
      SELECT co.Code, UPPER(co.Name) AS UpperName,
      COUNT(cl.Language) AS OfficialLanguages
      FROM country AS co JOIN countrylanguage AS cl
      ON cl.CountryCode=co.Code
      WHERE cl.isOfficial='T'
      GROUP BY co.Code
     ) AS co2
     JOIN City ci ON ci.CountryCode = co2.Code
     GROUP BY co2.Code;

*Combinations of Functional Dependencies*

MySQL is able to combine all of the preceding types of functional
dependencies (key based, equality based, view based) to validate more
complex queries.

12.20 Miscellaneous Functions
=============================

*Miscellaneous Functions*

Name                          Description

'ANY_VALUE()'                 Suppress ONLY_FULL_GROUP_BY value
                              rejection

'DEFAULT()'                   Return the default value for a table
                              column

'GET_LOCK()'                  Get a named lock

'INET_ATON()'                 Return the numeric value of an IP address

'INET_NTOA()'                 Return the IP address from a numeric
                              value

'INET6_ATON()'                Return the numeric value of an IPv6
                              address

'INET6_NTOA()'                Return the IPv6 address from a numeric
                              value

'IS_FREE_LOCK()'              Whether the named lock is free

'IS_IPV4()'                   Whether argument is an IPv4 address

'IS_IPV4_COMPAT()'            Whether argument is an IPv4-compatible
                              address

'IS_IPV4_MAPPED()'            Whether argument is an IPv4-mapped
                              address

'IS_IPV6()'                   Whether argument is an IPv6 address

'IS_USED_LOCK()'              Whether the named lock is in use; return
                              connection identifier if true

'MASTER_POS_WAIT()'           Block until the slave has read and
                              applied all updates up to the specified
                              position

'NAME_CONST()'                Causes the column to have the given name

'RAND()'                      Return a random floating-point value

'RELEASE_ALL_LOCKS()'         Releases all current named locks

'RELEASE_LOCK()'              Releases the named lock

'SLEEP()'                     Sleep for a number of seconds

'UUID()'                      Return a Universal Unique Identifier
                              (UUID)

'UUID_SHORT()'                Return an integer-valued universal
                              identifier

'VALUES()'                    Defines the values to be used during an
                              INSERT

   *
     'ANY_VALUE(ARG)'

     This function is useful for 'GROUP BY' queries when the
     'ONLY_FULL_GROUP_BY' SQL mode is enabled, for cases when MySQL
     rejects a query that you know is valid for reasons that MySQL
     cannot determine.  The function return value and type are the same
     as the return value and type of its argument, but the function
     result is not checked for the 'ONLY_FULL_GROUP_BY' SQL mode.

     For example, if 'name' is a nonindexed column, the following query
     fails with 'ONLY_FULL_GROUP_BY' enabled:

          mysql> SELECT name, address, MAX(age) FROM t GROUP BY name;
          ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP
          BY clause and contains nonaggregated column 'mydb.t.address' which
          is not functionally dependent on columns in GROUP BY clause; this
          is incompatible with sql_mode=only_full_group_by

     The failure occurs because 'address' is a nonaggregated column that
     is neither named among 'GROUP BY' columns nor functionally
     dependent on them.  As a result, the 'address' value for rows
     within each 'name' group is nondeterministic.  There are multiple
     ways to cause MySQL to accept the query:

        * Alter the table to make 'name' a primary key or a unique 'NOT
          NULL' column.  This enables MySQL to determine that 'address'
          is functionally dependent on 'name'; that is, 'address' is
          uniquely determined by 'name'.  (This technique is
          inapplicable if 'NULL' must be permitted as a valid 'name'
          value.)

        * Use 'ANY_VALUE()' to refer to 'address':

               SELECT name, ANY_VALUE(address), MAX(age) FROM t GROUP BY name;

          In this case, MySQL ignores the nondeterminism of 'address'
          values within each 'name' group and accepts the query.  This
          may be useful if you simply do not care which value of a
          nonaggregated column is chosen for each group.  'ANY_VALUE()'
          is not an aggregate function, unlike functions such as 'SUM()'
          or 'COUNT()'.  It simply acts to suppress the test for
          nondeterminism.

        * Disable 'ONLY_FULL_GROUP_BY'.  This is equivalent to using
          'ANY_VALUE()' with 'ONLY_FULL_GROUP_BY' enabled, as described
          in the previous item.

     'ANY_VALUE()' is also useful if functional dependence exists
     between columns but MySQL cannot determine it.  The following query
     is valid because 'age' is functionally dependent on the grouping
     column 'age-1', but MySQL cannot tell that and rejects the query
     with 'ONLY_FULL_GROUP_BY' enabled:

          SELECT age FROM t GROUP BY age-1;

     To cause MySQL to accept the query, use 'ANY_VALUE()':

          SELECT ANY_VALUE(age) FROM t GROUP BY age-1;

     'ANY_VALUE()' can be used for queries that refer to aggregate
     functions in the absence of a 'GROUP BY' clause:

          mysql> SELECT name, MAX(age) FROM t;
          ERROR 1140 (42000): In aggregated query without GROUP BY, expression
          #1 of SELECT list contains nonaggregated column 'mydb.t.name'; this
          is incompatible with sql_mode=only_full_group_by

     Without 'GROUP BY', there is a single group and it is
     nondeterministic which 'name' value to choose for the group.
     'ANY_VALUE()' tells MySQL to accept the query:

          SELECT ANY_VALUE(name), MAX(age) FROM t;

     It may be that, due to some property of a given data set, you know
     that a selected nonaggregated column is effectively functionally
     dependent on a 'GROUP BY' column.  For example, an application may
     enforce uniqueness of one column with respect to another.  In this
     case, using 'ANY_VALUE()' for the effectively functionally
     dependent column may make sense.

     For additional discussion, see group-by-handling.

   *
     'DEFAULT(COL_NAME)'

     Returns the default value for a table column.  An error results if
     the column has no default value.

          mysql> UPDATE t SET i = DEFAULT(i)+1 WHERE id < 100;

   * 'FORMAT(X,D)'

     Formats the number X to a format like ''#,###,###.##'', rounded to
     D decimal places, and returns the result as a string.  For details,
     see string-functions.

   *
     'GET_LOCK(STR,TIMEOUT)'

     Tries to obtain a lock with a name given by the string STR, using a
     timeout of TIMEOUT seconds.  A negative TIMEOUT value means
     infinite timeout.  The lock is exclusive.  While held by one
     session, other sessions cannot obtain a lock of the same name.

     Returns '1' if the lock was obtained successfully, '0' if the
     attempt timed out (for example, because another client has
     previously locked the name), or 'NULL' if an error occurred (such
     as running out of memory or the thread was killed with
     'mysqladmin kill').

     A lock obtained with 'GET_LOCK()' is released explicitly by
     executing 'RELEASE_LOCK()' or implicitly when your session
     terminates (either normally or abnormally).  Lock release may also
     occur with another call to 'GET_LOCK()':

        * Before 5.7.5, only a single simultaneous lock can be acquired
          and 'GET_LOCK()' releases any existing lock.

        * In MySQL 5.7.5, 'GET_LOCK()' was reimplemented using the
          metadata locking (MDL) subsystem and its capabilities were
          extended.  Multiple simultaneous locks can be acquired and
          'GET_LOCK()' does not release any existing locks.  It is even
          possible for a given session to acquire multiple locks for the
          same name.  Other sessions cannot acquire a lock with that
          name until the acquiring session releases all its locks for
          the name.

          As a result of the MDL reimplementation, locks acquired with
          'GET_LOCK()' appear in the Performance Schema
          'metadata_locks' table.  The
          'OBJECT_TYPE' column says 'USER LEVEL LOCK' and the
          'OBJECT_NAME' column indicates the lock name.  Also, the
          capability of acquiring multiple locks introduces the
          possibility of deadlock among clients.  When this happens, the
          server chooses a caller and terminates its lock-acquisition
          request with an 'ER_USER_LOCK_DEADLOCK' error.  This error
          does not cause transactions to roll back.

     The difference in lock acquisition behavior as of MySQL 5.7.5 can
     be seen by the following example.  Suppose that you execute these
     statements:

          SELECT GET_LOCK('lock1',10);
          SELECT GET_LOCK('lock2',10);
          SELECT RELEASE_LOCK('lock2');
          SELECT RELEASE_LOCK('lock1');

     In MySQL 5.7.5 or later, the second 'GET_LOCK()' acquires a second
     lock and both 'RELEASE_LOCK()' calls return 1 (success).  Before
     MySQL 5.7.5, the second 'GET_LOCK()' releases the first lock
     (''lock1')' and the second 'RELEASE_LOCK()' returns 'NULL'
     (failure) because there is no ''lock1'' to release.

     MySQL 5.7.5 and later enforces a maximum length on lock names of 64
     characters.  Previously, no limit was enforced.

     Locks obtained with 'GET_LOCK()' are not released when transactions
     commit or roll back.

     'GET_LOCK()' can be used to implement application locks or to
     simulate record locks.  Names are locked on a server-wide basis.
     If a name has been locked within one session, 'GET_LOCK()' blocks
     any request by another session for a lock with the same name.  This
     enables clients that agree on a given lock name to use the name to
     perform cooperative advisory locking.  But be aware that it also
     enables a client that is not among the set of cooperating clients
     to lock a name, either inadvertently or deliberately, and thus
     prevent any of the cooperating clients from locking that name.  One
     way to reduce the likelihood of this is to use lock names that are
     database-specific or application-specific.  For example, use lock
     names of the form DB_NAME.STR or APP_NAME.STR.

     If multiple clients are waiting for a lock, the order in which they
     will acquire it is undefined.  Applications should not assume that
     clients will acquire the lock in the same order that they issued
     the lock requests.

     'GET_LOCK()' is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

     *Caution*:

     With the capability of acquiring multiple named locks in MySQL
     5.7.5, it is possible for a single statement to acquire a large
     number of locks.  For example:

          INSERT INTO ... SELECT GET_LOCK(t1.col_name) FROM t1;

     These types of statements may have certain adverse effects.  For
     example, if the statement fails part way through and rolls back,
     locks acquired up to the point of failure will still exist.  If the
     intent is for there to be a correspondence between rows inserted
     and locks acquired, that intent will not be satisfied.  Also, if it
     is important that locks are granted in a certain order, be aware
     that result set order may differ depending on which execution plan
     the optimizer chooses.  For these reasons, it may be best to limit
     applications to a single lock-acquisition call per statement.

     A different locking interface is available as either a plugin
     service or a set of user-defined functions.  This interface
     provides lock namespaces and distinct read and write locks, unlike
     the interface provided by 'GET_LOCK()' and related functions.  For
     details, see locking-service.

   *
     'INET_ATON(EXPR)'

     Given the dotted-quad representation of an IPv4 network address as
     a string, returns an integer that represents the numeric value of
     the address in network byte order (big endian).  'INET_ATON()'
     returns 'NULL' if it does not understand its argument.

          mysql> SELECT INET_ATON('10.0.5.9');
                  -> 167773449

     For this example, the return value is calculated as 10x256^3 +
     0x256^2 + 5x256 + 9.

     'INET_ATON()' may or may not return a non-'NULL' result for
     short-form IP addresses (such as ''127.1'' as a representation of
     ''127.0.0.1'').  Because of this, 'INET_ATON()'a should not be used
     for such addresses.

     *Note*:

     To store values generated by 'INET_ATON()', use an 'INT UNSIGNED'
     column rather than 'INT', which is signed.  If
     you use a signed column, values corresponding to IP addresses for
     which the first octet is greater than 127 cannot be stored
     correctly.  See out-of-range-and-overflow.

   *
     'INET_NTOA(EXPR)'

     Given a numeric IPv4 network address in network byte order, returns
     the dotted-quad string representation of the address as a string in
     the connection character set.  'INET_NTOA()' returns 'NULL' if it
     does not understand its argument.

          mysql> SELECT INET_NTOA(167773449);
                  -> '10.0.5.9'

   *
     'INET6_ATON(EXPR)'

     Given an IPv6 or IPv4 network address as a string, returns a binary
     string that represents the numeric value of the address in network
     byte order (big endian).  Because numeric-format IPv6 addresses
     require more bytes than the largest integer type, the
     representation returned by this function has the 'VARBINARY'
     data type: 'VARBINARY(16)'
     for IPv6 addresses and 'VARBINARY(4)'
     for IPv4 addresses.  If the argument is not a
     valid address, 'INET6_ATON()' returns 'NULL'.

     The following examples use 'HEX()' to display the 'INET6_ATON()'
     result in printable form:

          mysql> SELECT HEX(INET6_ATON('fdfe::5a55:caff:fefa:9089'));
                  -> 'FDFE0000000000005A55CAFFFEFA9089'
          mysql> SELECT HEX(INET6_ATON('10.0.5.9'));
                  -> '0A000509'

     'INET6_ATON()' observes several constraints on valid arguments.
     These are given in the following list along with examples.

        * A trailing zone ID is not permitted, as in 'fe80::3%1' or
          'fe80::3%eth0'.

        * A trailing network mask is not permitted, as in
          '2001:45f:3:ba::/64' or '198.51.100.0/24'.

        * For values representing IPv4 addresses, only classless
          addresses are supported.  Classful addresses such as
          '198.51.1' are rejected.  A trailing port number is not
          permitted, as in '198.51.100.2:8080'.  Hexadecimal numbers in
          address components are not permitted, as in '198.0xa0.1.2'.
          Octal numbers are not supported: '198.51.010.1' is treated as
          '198.51.10.1', not '198.51.8.1'.  These IPv4 constraints also
          apply to IPv6 addresses that have IPv4 address parts, such as
          IPv4-compatible or IPv4-mapped addresses.

     To convert an IPv4 address EXPR represented in numeric form as an
     'INT' value to an IPv6 address represented in
     numeric form as a 'VARBINARY' value, use
     this expression:

          INET6_ATON(INET_NTOA(EXPR))

     For example:

          mysql> SELECT HEX(INET6_ATON(INET_NTOA(167773449)));
                  -> '0A000509'

   *
     'INET6_NTOA(EXPR)'

     Given an IPv6 or IPv4 network address represented in numeric form
     as a binary string, returns the string representation of the
     address as a string in the connection character set.  If the
     argument is not a valid address, 'INET6_NTOA()' returns 'NULL'.

     'INET6_NTOA()' has these properties:

        * It does not use operating system functions to perform
          conversions, thus the output string is platform independent.

        * The return string has a maximum length of 39 (4 x 8 + 7).
          Given this statement:

               CREATE TABLE t AS SELECT INET6_NTOA(EXPR) AS c1;

          The resulting table would have this definition:

               CREATE TABLE t (c1 VARCHAR(39) CHARACTER SET utf8 DEFAULT NULL);

        * The return string uses lowercase letters for IPv6 addresses.

          mysql> SELECT INET6_NTOA(INET6_ATON('fdfe::5a55:caff:fefa:9089'));
                  -> 'fdfe::5a55:caff:fefa:9089'
          mysql> SELECT INET6_NTOA(INET6_ATON('10.0.5.9'));
                  -> '10.0.5.9'

          mysql> SELECT INET6_NTOA(UNHEX('FDFE0000000000005A55CAFFFEFA9089'));
                  -> 'fdfe::5a55:caff:fefa:9089'
          mysql> SELECT INET6_NTOA(UNHEX('0A000509'));
                  -> '10.0.5.9'

   *
     'IS_FREE_LOCK(STR)'

     Checks whether the lock named STR is free to use (that is, not
     locked).  Returns '1' if the lock is free (no one is using the
     lock), '0' if the lock is in use, and 'NULL' if an error occurs
     (such as an incorrect argument).

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

   *
     'IS_IPV4(EXPR)'

     Returns 1 if the argument is a valid IPv4 address specified as a
     string, 0 otherwise.

          mysql> SELECT IS_IPV4('10.0.5.9'), IS_IPV4('10.0.5.256');
                  -> 1, 0

     For a given argument, if 'IS_IPV4()' returns 1, 'INET_ATON()' (and
     'INET6_ATON()') will return non-'NULL'.  The converse statement is
     not true: In some cases, 'INET_ATON()' returns non-'NULL' when
     'IS_IPV4()' returns 0.

     As implied by the preceding remarks, 'IS_IPV4()' is more strict
     than 'INET_ATON()' about what constitutes a valid IPv4 address, so
     it may be useful for applications that need to perform strong
     checks against invalid values.  Alternatively, use 'INET6_ATON()'
     to convert IPv4 addresses to internal form and check for a 'NULL'
     result (which indicates an invalid address).  'INET6_ATON()' is
     equally strong as 'IS_IPV4()' about checking IPv4 addresses.

   *
     'IS_IPV4_COMPAT(EXPR)'

     This function takes an IPv6 address represented in numeric form as
     a binary string, as returned by 'INET6_ATON()'.  It returns 1 if
     the argument is a valid IPv4-compatible IPv6 address, 0 otherwise.
     IPv4-compatible addresses have the form '::IPV4_ADDRESS'.

          mysql> SELECT IS_IPV4_COMPAT(INET6_ATON('::10.0.5.9'));
                  -> 1
          mysql> SELECT IS_IPV4_COMPAT(INET6_ATON('::ffff:10.0.5.9'));
                  -> 0

     The IPv4 part of an IPv4-compatible address can also be represented
     using hexadecimal notation.  For example, '198.51.100.1' has this
     raw hexadecimal value:

          mysql> SELECT HEX(INET6_ATON('198.51.100.1'));
                  -> 'C6336401'

     Expressed in IPv4-compatible form, '::198.51.100.1' is equivalent
     to '::c0a8:0001' or (without leading zeros) '::c0a8:1'

          mysql> SELECT
              ->   IS_IPV4_COMPAT(INET6_ATON('::198.51.100.1')),
              ->   IS_IPV4_COMPAT(INET6_ATON('::c0a8:0001')),
              ->   IS_IPV4_COMPAT(INET6_ATON('::c0a8:1'));
                  -> 1, 1, 1

   *
     'IS_IPV4_MAPPED(EXPR)'

     This function takes an IPv6 address represented in numeric form as
     a binary string, as returned by 'INET6_ATON()'.  It returns 1 if
     the argument is a valid IPv4-mapped IPv6 address, 0 otherwise.
     IPv4-mapped addresses have the form '::ffff:IPV4_ADDRESS'.

          mysql> SELECT IS_IPV4_MAPPED(INET6_ATON('::10.0.5.9'));
                  -> 0
          mysql> SELECT IS_IPV4_MAPPED(INET6_ATON('::ffff:10.0.5.9'));
                  -> 1

     As with 'IS_IPV4_COMPAT()' the IPv4 part of an IPv4-mapped address
     can also be represented using hexadecimal notation:

          mysql> SELECT
              ->   IS_IPV4_MAPPED(INET6_ATON('::ffff:198.51.100.1')),
              ->   IS_IPV4_MAPPED(INET6_ATON('::ffff:c0a8:0001')),
              ->   IS_IPV4_MAPPED(INET6_ATON('::ffff:c0a8:1'));
                  -> 1, 1, 1

   *
     'IS_IPV6(EXPR)'

     Returns 1 if the argument is a valid IPv6 address specified as a
     string, 0 otherwise.  This function does not consider IPv4
     addresses to be valid IPv6 addresses.

          mysql> SELECT IS_IPV6('10.0.5.9'), IS_IPV6('::1');
                  -> 0, 1

     For a given argument, if 'IS_IPV6()' returns 1, 'INET6_ATON()' will
     return non-'NULL'.

   *
     'IS_USED_LOCK(STR)'

     Checks whether the lock named STR is in use (that is, locked).  If
     so, it returns the connection identifier of the client session that
     holds the lock.  Otherwise, it returns 'NULL'.

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

   *
     'MASTER_POS_WAIT(LOG_NAME,LOG_POS[,TIMEOUT][,CHANNEL])'

     This function is useful for control of master/slave
     synchronization.  It blocks until the slave has read and applied
     all updates up to the specified position in the master log.  The
     return value is the number of log events the slave had to wait for
     to advance to the specified position.  The function returns 'NULL'
     if the slave SQL thread is not started, the slave's master
     information is not initialized, the arguments are incorrect, or an
     error occurs.  It returns '-1' if the timeout has been exceeded.
     If the slave SQL thread stops while 'MASTER_POS_WAIT()' is waiting,
     the function returns 'NULL'.  If the slave is past the specified
     position, the function returns immediately.

     On a multi-threaded slave, the function waits until expiry of the
     limit set by the 'slave_checkpoint_group' or
     'slave_checkpoint_period' system variable, when the checkpoint
     operation is called to update the status of the slave.  Depending
     on the setting for the system variables, the function might
     therefore return some time after the specified position was
     reached.

     If a TIMEOUT value is specified, 'MASTER_POS_WAIT()' stops waiting
     when TIMEOUT seconds have elapsed.  TIMEOUT must be greater than 0;
     a zero or negative TIMEOUT means no timeout.

     The optional CHANNEL value enables you to name which replication
     channel the function applies to.  See replication-channels
     for more information.

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

   *
     'NAME_CONST(NAME,VALUE)'

     Returns the given value.  When used to produce a result set column,
     'NAME_CONST()' causes the column to have the given name.  The
     arguments should be constants.

          mysql> SELECT NAME_CONST('myname', 14);
          +--------+
          | myname |
          +--------+
          |     14 |
          +--------+

     This function is for internal use only.  The server uses it when
     writing statements from stored programs that contain references to
     local program variables, as described in
     stored-programs-logging.  You might see this function in the
     output from 'mysqlbinlog'.

     For your applications, you can obtain exactly the same result as in
     the example just shown by using simple aliasing, like this:

          mysql> SELECT 14 AS myname;
          +--------+
          | myname |
          +--------+
          |     14 |
          +--------+
          1 row in set (0.00 sec)

     See select, for more information about column aliases.

   *
     'RELEASE_ALL_LOCKS()'

     Releases all named locks held by the current session and returns
     the number of locks released (0 if there were none)

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

   *
     'RELEASE_LOCK(STR)'

     Releases the lock named by the string STR that was obtained with
     'GET_LOCK()'.  Returns '1' if the lock was released, '0' if the
     lock was not established by this thread (in which case the lock is
     not released), and 'NULL' if the named lock did not exist.  The
     lock does not exist if it was never obtained by a call to
     'GET_LOCK()' or if it has previously been released.

     The 'DO' statement is convenient to use with
     'RELEASE_LOCK()'.  See do.

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

   *
     'SLEEP(DURATION)'

     Sleeps (pauses) for the number of seconds given by the DURATION
     argument, then returns 0.  The duration may have a fractional part.
     If the argument is 'NULL' or negative, 'SLEEP()' produces a
     warning, or an error in strict SQL mode.

     When sleep returns normally (without interruption), it returns 0:

          mysql> SELECT SLEEP(1000);
          +-------------+
          | SLEEP(1000) |
          +-------------+
          |           0 |
          +-------------+

     When 'SLEEP()' is the only thing invoked by a query that is
     interrupted, it returns 1 and the query itself returns no error.
     This is true whether the query is killed or times out:

        * This statement is interrupted using 'KILL QUERY'.
          from another session:

               mysql> SELECT SLEEP(1000);
               +-------------+
               | SLEEP(1000) |
               +-------------+
               |           1 |
               +-------------+

        * This statement is interrupted by timing out:

               mysql> SELECT /*+ MAX_EXECUTION_TIME(1) */ SLEEP(1000);
               +-------------+
               | SLEEP(1000) |
               +-------------+
               |           1 |
               +-------------+

     When 'SLEEP()' is only part of a query that is interrupted, the
     query returns an error:

        * This statement is interrupted using 'KILL QUERY'.
          from another session:

               mysql> SELECT 1 FROM t1 WHERE SLEEP(1000);
               ERROR 1317 (70100): Query execution was interrupted

        * This statement is interrupted by timing out:

               mysql> SELECT /*+ MAX_EXECUTION_TIME(1000) */ 1 FROM t1 WHERE SLEEP(1000);
               ERROR 3024 (HY000): Query execution was interrupted, maximum statement
               execution time exceeded

     This function is unsafe for statement-based replication.  A warning
     is logged if you use this function when 'binlog_format' is set to
     'STATEMENT'.

   *
     'UUID()'

     Returns a Universal Unique Identifier (UUID) generated according to
     RFC 4122, 'A Universally Unique IDentifier (UUID) URN Namespace'
     (<http://www.ietf.org/rfc/rfc4122.txt>).

     A UUID is designed as a number that is globally unique in space and
     time.  Two calls to 'UUID()' are expected to generate two different
     values, even if these calls are performed on two separate devices
     not connected to each other.

     *Warning*:

     Although 'UUID()' values are intended to be unique, they are not
     necessarily unguessable or unpredictable.  If unpredictability is
     required, UUID values should be generated some other way.

     'UUID()' returns a value that conforms to UUID version 1 as
     described in RFC 4122.  The value is a 128-bit number represented
     as a 'utf8' string of five hexadecimal numbers in
     'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' format:

        * The first three numbers are generated from the low, middle,
          and high parts of a timestamp.  The high part also includes
          the UUID version number.

        * The fourth number preserves temporal uniqueness in case the
          timestamp value loses monotonicity (for example, due to
          daylight saving time).

        * The fifth number is an IEEE 802 node number that provides
          spatial uniqueness.  A random number is substituted if the
          latter is not available (for example, because the host device
          has no Ethernet card, or it is unknown how to find the
          hardware address of an interface on the host operating
          system).  In this case, spatial uniqueness cannot be
          guaranteed.  Nevertheless, a collision should have _very_ low
          probability.

          The MAC address of an interface is taken into account only on
          FreeBSD and Linux.  On other operating systems, MySQL uses a
          randomly generated 48-bit number.

          mysql> SELECT UUID();
                  -> '6ccd780c-baba-1026-9564-5b8c656024db'

     *Note*:

     'UUID()' does not work with statement-based replication.

   *
     'UUID_SHORT()'

     Returns a 'short' universal identifier as a 64-bit unsigned
     integer.  Values returned by 'UUID_SHORT()' differ from the
     string-format 128-bit identifiers returned by the 'UUID()' function
     and have different uniqueness properties.  The value of
     'UUID_SHORT()' is guaranteed to be unique if the following
     conditions hold:

        * The 'server_id' value of the current server is between 0 and
          255 and is unique among your set of master and slave servers

        * You do not set back the system time for your server host
          between 'mysqld' restarts

        * You invoke 'UUID_SHORT()' on average fewer than 16 million
          times per second between 'mysqld' restarts

     The 'UUID_SHORT()' return value is constructed this way:

            (server_id & 255) << 56
          + (server_startup_time_in_seconds << 24)
          + incremented_variable++;

          mysql> SELECT UUID_SHORT();
                  -> 92395783831158784

     *Note*:

     'UUID_SHORT()' does not work with statement-based replication.

   *
     'VALUES(COL_NAME)'

     In an 'INSERT ... ON DUPLICATE KEY UPDATE'
     statement, you can use the 'VALUES(COL_NAME)'
     function in the 'UPDATE' clause to refer to column
     values from the 'INSERT' portion of the statement.
     In other words, 'VALUES(COL_NAME)' in the 'UPDATE'.
     clause refers to the value of COL_NAME that would be inserted, had
     no duplicate-key conflict occurred.  This function is especially
     useful in multiple-row inserts.  The 'VALUES()' function is
     meaningful only in the 'ON DUPLICATE KEY UPDATE' clause of
     'INSERT' statements and returns 'NULL' otherwise.  See
     insert-on-duplicate.

          mysql> INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6)
              -> ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);

12.21 Precision Math
====================

MySQL provides support for precision math: numeric value handling that
results in extremely accurate results and a high degree control over
invalid values.  Precision math is based on these two features:

   * SQL modes that control how strict the server is about accepting or
     rejecting invalid data.

   * The MySQL library for fixed-point arithmetic.

These features have several implications for numeric operations and
provide a high degree of compliance with standard SQL:

   * *Precise calculations*: For exact-value numbers, calculations do
     not introduce floating-point errors.  Instead, exact precision is
     used.  For example, MySQL treats a number such as '.0001' as an
     exact value rather than as an approximation, and summing it 10,000
     times produces a result of exactly '1', not a value that is merely
     'close' to 1.

   * *Well-defined rounding behavior*: For exact-value numbers, the
     result of 'ROUND()' depends on its argument, not on environmental
     factors such as how the underlying C library works.

   * *Platform independence*: Operations on exact numeric values are the
     same across different platforms such as Windows and Unix.

   * *Control over handling of invalid values*: Overflow and division by
     zero are detectable and can be treated as errors.  For example, you
     can treat a value that is too large for a column as an error rather
     than having the value truncated to lie within the range of the
     column's data type.  Similarly, you can treat division by zero as
     an error rather than as an operation that produces a result of
     'NULL'.  The choice of which approach to take is determined by the
     setting of the server SQL mode.

The following discussion covers several aspects of how precision math
works, including possible incompatibilities with older applications.  At
the end, some examples are given that demonstrate how MySQL handles
numeric operations precisely.  For information about controlling the SQL
mode, see sql-mode.

12.21.1 Types of Numeric Values
-------------------------------

The scope of precision math for exact-value operations includes the
exact-value data types (integer and 'DECIMAL'.
types) and exact-value numeric literals.  Approximate-value data types
and numeric literals are handled as floating-point numbers.

Exact-value numeric literals have an integer part or fractional part, or
both.  They may be signed.  Examples: '1', '.2', '3.4', '-5', '-6.78',
'+9.10'.

Approximate-value numeric literals are represented in scientific
notation with a mantissa and exponent.  Either or both parts may be
signed.  Examples: '1.2E3', '1.2E-3', '-1.2E3', '-1.2E-3'.

Two numbers that look similar may be treated differently.  For example,
'2.34' is an exact-value (fixed-point) number, whereas '2.34E0' is an
approximate-value (floating-point) number.

The 'DECIMAL' data type is a fixed-point type
and calculations are exact.  In MySQL, the 'DECIMAL'
type has several synonyms: 'NUMERIC',
see 'DEC', 'FIXED'.
The integer types also are exact-value types.

The 'FLOAT' and 'DOUBLE'
data types are floating-point types and
calculations are approximate.  In MySQL, types that are synonymous with
'FLOAT' or 'DOUBLE'
are 'DOUBLE PRECISION'
and 'REAL'.

12.21.2 DECIMAL Data Type Characteristics
-----------------------------------------

This section discusses the characteristics of the 'DECIMAL'
data type (and its synonyms), with particular regard
to the following topics:

   * Maximum number of digits

   * Storage format

   * Storage requirements

   * The nonstandard MySQL extension to the upper range of
     'DECIMAL' columns

The declaration syntax for a 'DECIMAL' column
is 'DECIMAL(M,D)'.  The ranges of values for the arguments are as
follows:

   * M is the maximum number of digits (the precision).  It has a range
     of 1 to 65.

   * D is the number of digits to the right of the decimal point (the
     scale).  It has a range of 0 to 30 and must be no larger than M.

The maximum value of 65 for M means that calculations on
'DECIMAL' values are accurate up to 65 digits.  This
limit of 65 digits of precision also applies to exact-value numeric
literals, so the maximum range of such literals differs from before.

Values for 'DECIMAL' columns are stored using
a binary format that packs nine decimal digits into 4 bytes.  The
storage requirements for the integer and fractional parts of each value
are determined separately.  Each multiple of nine digits requires 4
bytes, and any remaining digits left over require some fraction of 4
bytes.  The storage required for remaining digits is given by the
following table.

Leftover Digits    Number of Bytes

0                  0

1-2                1

3-4                2

5-6                3

7-9                4

For example, a 'DECIMAL(18,9)' column has nine digits on either side of
the decimal point, so the integer part and the fractional part each
require 4 bytes.  A 'DECIMAL(20,6)' column has fourteen integer digits
and six fractional digits.  The integer digits require four bytes for
nine of the digits and 3 bytes for the remaining five digits.  The six
fractional digits require 3 bytes.

'DECIMAL' columns do not store a leading '+'
character or '-' character or leading '0' digits.  If you insert
'+0003.1' into a 'DECIMAL(5,1)' column, it is stored as '3.1'.  For
negative numbers, a literal '-' character is not stored.

'DECIMAL' columns do not permit values larger
than the range implied by the column definition.  For example, a
'DECIMAL(3,0)' column supports a range of '-999' to '999'.  A
'DECIMAL(M,D)' column permits up to M - D digits to the left of the
decimal point.

The SQL standard requires that the precision of 'NUMERIC(M,D)' be
_exactly_ M digits.  For 'DECIMAL(M,D)', the standard requires a
precision of at least M digits but permits more.  In MySQL,
'DECIMAL(M,D)' and 'NUMERIC(M,D)' are the same, and both have a
precision of exactly M digits.

For a full explanation of the internal format of 'DECIMAL' values, see
the file 'strings/decimal.c' in a MySQL source distribution.  The format
is explained (with an example) in the 'decimal2bin()' function.

12.21.3 Expression Handling
---------------------------

With precision math, exact-value numbers are used as given whenever
possible.  For example, numbers in comparisons are used exactly as given
without a change in value.  In strict SQL mode, for 'INSERT'
into a column with an exact data type (see 'DECIMAL'
or integer), a number is inserted with its exact
value if it is within the column range.  When retrieved, the value
should be the same as what was inserted.  (If strict SQL mode is not
enabled, truncation for 'INSERT' is permissible.)

Handling of a numeric expression depends on what kind of values the
expression contains:

   * If any approximate values are present, the expression is
     approximate and is evaluated using floating-point arithmetic.

   * If no approximate values are present, the expression contains only
     exact values.  If any exact value contains a fractional part (a
     value following the decimal point), the expression is evaluated
     using 'DECIMAL' exact arithmetic and has
     a precision of 65 digits.  The term 'exact' is subject to the
     limits of what can be represented in binary.  For example,
     '1.0/3.0' can be approximated in decimal notation as '.333...', but
     not written as an exact number, so '(1.0/3.0)*3.0' does not
     evaluate to exactly '1.0'.

   * Otherwise, the expression contains only integer values.  The
     expression is exact and is evaluated using integer arithmetic and
     has a precision the same as 'BIGINT'. (64
     bits).

If a numeric expression contains any strings, they are converted to
double-precision floating-point values and the expression is
approximate.

Inserts into numeric columns are affected by the SQL mode, which is
controlled by the 'sql_mode' system variable.  (See sql-mode.)
The following discussion mentions strict mode (selected by the
'STRICT_ALL_TABLES' or 'STRICT_TRANS_TABLES' mode values) and
'ERROR_FOR_DIVISION_BY_ZERO'.  To turn on all restrictions, you can
simply use 'TRADITIONAL' mode, which includes both strict mode values
and 'ERROR_FOR_DIVISION_BY_ZERO':

     mysql> SET sql_mode='TRADITIONAL';

If a number is inserted into an exact type column (see 'DECIMAL'
or integer), it is inserted with its exact value if
it is within the column range.

If the value has too many digits in the fractional part, rounding occurs
and a warning is generated.  Rounding is done as described in
precision-math-rounding.

If the value has too many digits in the integer part, it is too large
and is handled as follows:

   * If strict mode is not enabled, the value is truncated to the
     nearest legal value and a warning is generated.

   * If strict mode is enabled, an overflow error occurs.

Underflow is not detected, so underflow handling is undefined.

For inserts of strings into numeric columns, conversion from string to
number is handled as follows if the string has nonnumeric contents:

   * A string that does not begin with a number cannot be used as a
     number and produces an error in strict mode, or a warning
     otherwise.  This includes the empty string.

   * A string that begins with a number can be converted, but the
     trailing nonnumeric portion is truncated.  If the truncated portion
     contains anything other than spaces, this produces an error in
     strict mode, or a warning otherwise.

By default, division by zero produces a result of 'NULL' and no warning.
By setting the SQL mode appropriately, division by zero can be
restricted.

With the 'ERROR_FOR_DIVISION_BY_ZERO' SQL mode enabled, MySQL handles
division by zero differently:

   * If strict mode is not enabled, a warning occurs.

   * If strict mode is enabled, inserts and updates involving division
     by zero are prohibited, and an error occurs.

In other words, inserts and updates involving expressions that perform
division by zero can be treated as errors, but this requires
'ERROR_FOR_DIVISION_BY_ZERO' in addition to strict mode.

Suppose that we have this statement:

     INSERT INTO t SET i = 1/0;

This is what happens for combinations of strict and
'ERROR_FOR_DIVISION_BY_ZERO' modes.

'sql_mode' Value                     Result

'''' (Default)                       No warning, no error; 'i' is set
                                     to 'NULL'.

strict                               No warning, no error; 'i' is set
                                     to 'NULL'.

'ERROR_FOR_DIVISION_BY_ZERO'         Warning, no error; 'i' is set to
                                     'NULL'.

strict,'ERROR_FOR_DIVISION_BY_ZERO'  Error condition; no row is
                                     inserted.

12.21.4 Rounding Behavior
-------------------------

This section discusses precision math rounding for the 'ROUND()'
function and for inserts into columns with exact-value types (see
'DECIMAL' and integer).

The 'ROUND()' function rounds differently depending on whether its
argument is exact or approximate:

   * For exact-value numbers, 'ROUND()' uses the 'round half up' rule: A
     value with a fractional part of .5 or greater is rounded up to the
     next integer if positive or down to the next integer if negative.
     (In other words, it is rounded away from zero.)  A value with a
     fractional part less than .5 is rounded down to the next integer if
     positive or up to the next integer if negative.

   * For approximate-value numbers, the result depends on the C library.
     On many systems, this means that 'ROUND()' uses the 'round to
     nearest even' rule: A value with any fractional part is rounded to
     the nearest even integer.

The following example shows how rounding differs for exact and
approximate values:

     mysql> SELECT ROUND(2.5), ROUND(25E-1);
     +------------+--------------+
     | ROUND(2.5) | ROUND(25E-1) |
     +------------+--------------+
     | 3          |            2 |
     +------------+--------------+

For inserts into a 'DECIMAL' or integer
column, the target is an exact data type, so rounding uses 'round half
away from zero,' regardless of whether the value to be inserted is exact
or approximate:

     mysql> CREATE TABLE t (d DECIMAL(10,0));
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t VALUES(2.5),(2.5E0);
     Query OK, 2 rows affected, 2 warnings (0.00 sec)
     Records: 2  Duplicates: 0  Warnings: 2

     mysql> SELECT d FROM t;
     +------+
     | d    |
     +------+
     | 3    |
     | 3    |
     +------+

12.21.5 Precision Math Examples
-------------------------------

This section provides some examples that show precision math query
results in MySQL. These examples demonstrate the principles described in
precision-math-expressions, and precision-math-rounding.

*Example 1*.  Numbers are used with their exact value as given when
possible:

     mysql> SELECT (.1 + .2) = .3;
     +----------------+
     | (.1 + .2) = .3 |
     +----------------+
     |              1 |
     +----------------+

For floating-point values, results are inexact:

     mysql> SELECT (.1E0 + .2E0) = .3E0;
     +----------------------+
     | (.1E0 + .2E0) = .3E0 |
     +----------------------+
     |                    0 |
     +----------------------+

Another way to see the difference in exact and approximate value
handling is to add a small number to a sum many times.  Consider the
following stored procedure, which adds '.0001' to a variable 1,000
times.

     CREATE PROCEDURE p ()
     BEGIN
       DECLARE i INT DEFAULT 0;
       DECLARE d DECIMAL(10,4) DEFAULT 0;
       DECLARE f FLOAT DEFAULT 0;
       WHILE i < 10000 DO
         SET d = d + .0001;
         SET f = f + .0001E0;
         SET i = i + 1;
       END WHILE;
       SELECT d, f;
     END;

The sum for both 'd' and 'f' logically should be 1, but that is true
only for the decimal calculation.  The floating-point calculation
introduces small errors:

     +--------+------------------+
     | d      | f                |
     +--------+------------------+
     | 1.0000 | 0.99999999999991 |
     +--------+------------------+

*Example 2*.  Multiplication is performed with the scale required by
standard SQL. That is, for two numbers X1 and X2 that have scale S1 and
S2, the scale of the result is 'S1 + S2':

     mysql> SELECT .01 * .01;
     +-----------+
     | .01 * .01 |
     +-----------+
     | 0.0001    |
     +-----------+

*Example 3*.  Rounding behavior for exact-value numbers is well-defined:

Rounding behavior (for example, with the 'ROUND()' function) is
independent of the implementation of the underlying C library, which
means that results are consistent from platform to platform.

   * Rounding for exact-value columns (see 'DECIMAL'
     and integer) and exact-valued numbers uses the
     'round half away from zero' rule.  Values with a fractional part of
     .5 or greater are rounded away from zero to the nearest integer, as
     shown here:

          mysql> SELECT ROUND(2.5), ROUND(-2.5);
          +------------+-------------+
          | ROUND(2.5) | ROUND(-2.5) |
          +------------+-------------+
          | 3          | -3          |
          +------------+-------------+

   * Rounding for floating-point values uses the C library, which on
     many systems uses the 'round to nearest even' rule.  Values with
     any fractional part on such systems are rounded to the nearest even
     integer:

          mysql> SELECT ROUND(2.5E0), ROUND(-2.5E0);
          +--------------+---------------+
          | ROUND(2.5E0) | ROUND(-2.5E0) |
          +--------------+---------------+
          |            2 |            -2 |
          +--------------+---------------+

*Example 4*.  In strict mode, inserting a value that is out of range for
a column causes an error, rather than truncation to a legal value.

When MySQL is not running in strict mode, truncation to a legal value
occurs:

     mysql> SET sql_mode='';
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t (i TINYINT);
     Query OK, 0 rows affected (0.01 sec)

     mysql> INSERT INTO t SET i = 128;
     Query OK, 1 row affected, 1 warning (0.00 sec)

     mysql> SELECT i FROM t;
     +------+
     | i    |
     +------+
     |  127 |
     +------+
     1 row in set (0.00 sec)

However, an error occurs if strict mode is in effect:

     mysql> SET sql_mode='STRICT_ALL_TABLES';
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t (i TINYINT);
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t SET i = 128;
     ERROR 1264 (22003): Out of range value adjusted for column 'i' at row 1

     mysql> SELECT i FROM t;
     Empty set (0.00 sec)

*Example 5*: In strict mode and with 'ERROR_FOR_DIVISION_BY_ZERO' set,
division by zero causes an error, not a result of 'NULL'.

In nonstrict mode, division by zero has a result of 'NULL':

     mysql> SET sql_mode='';
     Query OK, 0 rows affected (0.01 sec)

     mysql> CREATE TABLE t (i TINYINT);
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t SET i = 1 / 0;
     Query OK, 1 row affected (0.00 sec)

     mysql> SELECT i FROM t;
     +------+
     | i    |
     +------+
     | NULL |
     +------+
     1 row in set (0.03 sec)

However, division by zero is an error if the proper SQL modes are in
effect:

     mysql> SET sql_mode='STRICT_ALL_TABLES,ERROR_FOR_DIVISION_BY_ZERO';
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t (i TINYINT);
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO t SET i = 1 / 0;
     ERROR 1365 (22012): Division by 0

     mysql> SELECT i FROM t;
     Empty set (0.01 sec)

*Example 6*.  Exact-value literals are evaluated as exact values.

Approximate-value literals are evaluated using floating point, but
exact-value literals are handled as 'DECIMAL'.:

     mysql> CREATE TABLE t SELECT 2.5 AS a, 25E-1 AS b;
     Query OK, 1 row affected (0.01 sec)
     Records: 1  Duplicates: 0  Warnings: 0

     mysql> DESCRIBE t;
     +-------+-----------------------+------+-----+---------+-------+
     | Field | Type                  | Null | Key | Default | Extra |
     +-------+-----------------------+------+-----+---------+-------+
     | a     | decimal(2,1) unsigned | NO   |     | 0.0     |       |
     | b     | double                | NO   |     | 0       |       |
     +-------+-----------------------+------+-----+---------+-------+
     2 rows in set (0.01 sec)

*Example 7*.  If the argument to an aggregate function is an exact
numeric type, the result is also an exact numeric type, with a scale at
least that of the argument.

Consider these statements:

     mysql> CREATE TABLE t (i INT, d DECIMAL, f FLOAT);
     mysql> INSERT INTO t VALUES(1,1,1);
     mysql> CREATE TABLE y SELECT AVG(i), AVG(d), AVG(f) FROM t;

The result is a double only for the floating-point argument.  For exact
type arguments, the result is also an exact type:

     mysql> DESCRIBE y;
     +--------+---------------+------+-----+---------+-------+
     | Field  | Type          | Null | Key | Default | Extra |
     +--------+---------------+------+-----+---------+-------+
     | AVG(i) | decimal(14,4) | YES  |     | NULL    |       |
     | AVG(d) | decimal(14,4) | YES  |     | NULL    |       |
     | AVG(f) | double        | YES  |     | NULL    |       |
     +--------+---------------+------+-----+---------+-------+

The result is a double only for the floating-point argument.  For exact
type arguments, the result is also an exact type.

13 SQL Statement Syntax
***********************

This chapter describes the syntax for the SQL statements supported by
MySQL.

13.1 Data Definition Statements
===============================

13.1.1 ALTER DATABASE Syntax
----------------------------

     ALTER {DATABASE | SCHEMA} [DB_NAME]
         ALTER_SPECIFICATION ...
     ALTER {DATABASE | SCHEMA} DB_NAME
         UPGRADE DATA DIRECTORY NAME

     ALTER_SPECIFICATION:
         [DEFAULT] CHARACTER SET [=] CHARSET_NAME
       | [DEFAULT] COLLATE [=] COLLATION_NAME

'ALTER DATABASE' enables you to change the
overall characteristics of a database.  These characteristics are stored
in the 'db.opt' file in the database directory.  To use 'ALTER DATABASE',
you need the 'ALTER' privilege on the
database.  'ALTER SCHEMA' is a synonym for
'ALTER DATABASE'.

The database name can be omitted from the first syntax, in which case
the statement applies to the default database.

*National Language Characteristics*

The 'CHARACTER SET' clause changes the default database character set.
The 'COLLATE' clause changes the default database collation.  See
charset, discusses character set and collation names.

You can see what character sets and collations are available using,
respectively, the 'SHOW CHARACTER SET' and
'SHOW COLLATION' statements.  See
show-character-set, and show-collation, for more information.

If you change the default character set or collation for a database,
stored routines that use the database defaults must be dropped and
recreated so that they use the new defaults.  (In a stored routine,
variables with character data types use the database defaults if the
character set or collation are not specified explicitly.  See
create-procedure.)

*Upgrading from Versions Older than MySQL 5.1*

The syntax that includes the 'UPGRADE DATA DIRECTORY NAME' clause
updates the name of the directory associated with the database to use
the encoding implemented in MySQL 5.1 for mapping database names to
database directory names (see identifier-mapping).  This clause
is for use under these conditions:

   * It is intended when upgrading MySQL to 5.1 or later from older
     versions.

   * It is intended to update a database directory name to the current
     encoding format if the name contains special characters that need
     encoding.

   * The statement is used by 'mysqlcheck'. (as
     invoked by 'mysql_upgrade').

For example, if a database in MySQL 5.0 has the name 'a-b-c', the name
contains instances of the '-' (dash) character.  In MySQL 5.0, the
database directory is also named 'a-b-c', which is not necessarily safe
for all file systems.  In MySQL 5.1 and later, the same database name is
encoded as 'a@002db@002dc' to produce a file system-neutral directory
name.

When a MySQL installation is upgraded to MySQL 5.1 or later from an
older version,the server displays a name such as 'a-b-c' (which is in
the old format) as '#mysql50#a-b-c', and you must refer to the name
using the '#mysql50#' prefix.  Use 'UPGRADE DATA DIRECTORY NAME' in this
case to explicitly tell the server to re-encode the database directory
name to the current encoding format:

     ALTER DATABASE `#mysql50#a-b-c` UPGRADE DATA DIRECTORY NAME;

After executing this statement, you can refer to the database as 'a-b-c'
without the special '#mysql50#' prefix.

*Note*:

The 'UPGRADE DATA DIRECTORY NAME' clause is deprecated in MySQL 5.7.6
and will be removed in a future version of MySQL. If it is necessary to
convert MySQL 5.0 database or table names, a workaround is to upgrade a
MySQL 5.0 installation to MySQL 5.1 before upgrading to a more recent
release.

13.1.2 ALTER EVENT Syntax
-------------------------

     ALTER
         [DEFINER = { USER | CURRENT_USER }]
         EVENT EVENT_NAME
         [ON SCHEDULE SCHEDULE]
         [ON COMPLETION [NOT] PRESERVE]
         [RENAME TO NEW_EVENT_NAME]
         [ENABLE | DISABLE | DISABLE ON SLAVE]
         [COMMENT 'STRING']
         [DO EVENT_BODY]

The 'ALTER EVENT' statement changes one or more of
the characteristics of an existing event without the need to drop and
recreate it.  The syntax for each of the 'DEFINER', 'ON SCHEDULE', 'ON
COMPLETION', 'COMMENT', 'ENABLE' / 'DISABLE', and 'DO'.
clauses is exactly the same as when used with 'CREATE EVENT'.
(See create-event.)

Any user can alter an event defined on a database for which that user
has the 'EVENT' privilege.  When a user executes a successful
'ALTER EVENT' statement, that user becomes the definer for
the affected event.

'ALTER EVENT' works only with an existing event:

     mysql> ALTER EVENT no_such_event
          >     ON SCHEDULE
          >       EVERY '2:3' DAY_HOUR;
     ERROR 1517 (HY000): Unknown event 'no_such_event'

In each of the following examples, assume that the event named 'myevent'
is defined as shown here:

     CREATE EVENT myevent
         ON SCHEDULE
           EVERY 6 HOUR
         COMMENT 'A sample comment.'
         DO
           UPDATE myschema.mytable SET mycol = mycol + 1;

The following statement changes the schedule for 'myevent' from once
every six hours starting immediately to once every twelve hours,
starting four hours from the time the statement is run:

     ALTER EVENT myevent
         ON SCHEDULE
           EVERY 12 HOUR
         STARTS CURRENT_TIMESTAMP + INTERVAL 4 HOUR;

It is possible to change multiple characteristics of an event in a
single statement.  This example changes the SQL statement executed by
'myevent' to one that deletes all records from 'mytable'; it also
changes the schedule for the event such that it executes once, one day
after this 'ALTER EVENT' statement is run.

     ALTER EVENT myevent
         ON SCHEDULE
           AT CURRENT_TIMESTAMP + INTERVAL 1 DAY
         DO
           TRUNCATE TABLE myschema.mytable;

Specify the options in an 'ALTER EVENT' statement
only for those characteristics that you want to change; omitted options
keep their existing values.  This includes any default values for
'CREATE EVENT' such as 'ENABLE'.

To disable 'myevent', use this 'ALTER EVENT'.
statement:

     ALTER EVENT myevent
         DISABLE;

The 'ON SCHEDULE' clause may use expressions involving built-in MySQL
functions and user variables to obtain any of the TIMESTAMP or INTERVAL
values which it contains.  You cannot use stored routines or
user-defined functions in such expressions, and you cannot use any table
references; however, you can use 'SELECT FROM DUAL'.  This is true for
both 'ALTER EVENT' and 'CREATE EVENT'
statements.  References to stored routines, user-defined
functions, and tables in such cases are specifically not permitted, and
fail with an error (see Bug #22830).

Although an 'ALTER EVENT' statement that contains
another 'ALTER EVENT' statement in its 'DO'
clause appears to succeed, when the server attempts to execute the
resulting scheduled event, the execution fails with an error.

To rename an event, use the 'ALTER EVENT'.
statement's 'RENAME TO' clause.  This statement renames the event
'myevent' to 'yourevent':

     ALTER EVENT myevent
         RENAME TO yourevent;

You can also move an event to a different database using 'ALTER EVENT
... RENAME TO ...' and 'DB_NAME.EVENT_NAME' notation, as shown here:

     ALTER EVENT olddb.myevent
         RENAME TO newdb.myevent;

To execute the previous statement, the user executing it must have the
'EVENT' privilege on both the 'olddb' and 'newdb' databases.

*Note*:

There is no 'RENAME EVENT' statement.

The value 'DISABLE ON SLAVE' is used on a replication slave instead of
'ENABLE' or 'DISABLE' to indicate an event that was created on the
master and replicated to the slave, but that is not executed on the
slave.  Normally, 'DISABLE ON SLAVE' is set automatically as required;
however, there are some circumstances under which you may want or need
to change it manually.  See replication-features-invoked, for
more information.

13.1.3 ALTER FUNCTION Syntax
----------------------------

     ALTER FUNCTION FUNC_NAME [CHARACTERISTIC ...]

     CHARACTERISTIC:
         COMMENT 'STRING'
       | LANGUAGE SQL
       | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }
       | SQL SECURITY { DEFINER | INVOKER }

This statement can be used to change the characteristics of a stored
function.  More than one change may be specified in an 'ALTER FUNCTION'
statement.  However, you cannot change the
parameters or body of a stored function using this statement; to make
such changes, you must drop and re-create the function using 'DROP FUNCTION'
and 'CREATE FUNCTION'.

You must have the 'ALTER ROUTINE' privilege for the function.  (That
privilege is granted automatically to the function creator.)  If binary
logging is enabled, the 'ALTER FUNCTION'.
statement might also require the 'SUPER' privilege, as described in
stored-programs-logging.

13.1.4 ALTER INSTANCE Syntax
----------------------------

     ALTER INSTANCE ROTATE INNODB MASTER KEY

'ALTER INSTANCE', introduced in MySQL 5.7.11, defines actions applicable
to a MySQL server instance.

The 'ALTER INSTANCE ROTATE INNODB MASTER KEY' statement is used to
rotate the master encryption key used for 'InnoDB' tablespace
encryption.  A keyring plugin must be loaded to use this statement.  For
information about keyring plugins, see keyring.  Key rotation
requires the 'SUPER' privilege.

'ALTER INSTANCE ROTATE INNODB MASTER KEY' supports concurrent DML.
However, it cannot be run concurrently with 'CREATE TABLE ... ENCRYPTION'
or 'ALTER TABLE ... ENCRYPTION'
operations, and locks are taken to prevent conflicts that
could arise from concurrent execution of these statements.  If one of
the conflicting statements is running, it must complete before another
can proceed.

'ALTER INSTANCE' actions are written to the binary log so that they can
be executed on replicated servers.

For additional 'ALTER INSTANCE ROTATE INNODB MASTER KEY' usage
information, see innodb-tablespace-encryption.  For information
about keyring plugins, see keyring.

13.1.5 ALTER LOGFILE GROUP Syntax
---------------------------------

     ALTER LOGFILE GROUP LOGFILE_GROUP
         ADD UNDOFILE 'FILE_NAME'
         [INITIAL_SIZE [=] SIZE]
         [WAIT]
         ENGINE [=] ENGINE_NAME

This statement adds an 'UNDO' file named 'FILE_NAME' to an existing log
file group LOGFILE_GROUP.  An 'ALTER LOGFILE GROUP'
statement has one and only one 'ADD UNDOFILE'
clause.  No 'DROP UNDOFILE' clause is currently supported.

*Note*:

All NDB Cluster Disk Data objects share the same namespace.  This means
that _each Disk Data object_ must be uniquely named (and not merely each
Disk Data object of a given type).  For example, you cannot have a
tablespace and an undo log file with the same name, or an undo log file
and a data file with the same name.

The optional 'INITIAL_SIZE' parameter sets the 'UNDO' file's initial
size in bytes; if not specified, the initial size defaults to 134217728
(128 MB). You may optionally follow SIZE with a one-letter abbreviation
for an order of magnitude, similar to those used in 'my.cnf'.
Generally, this is one of the letters 'M' (megabytes) or 'G'
(gigabytes).  (Bug #13116514, Bug #16104705, Bug #62858)

On 32-bit systems, the maximum supported value for 'INITIAL_SIZE' is
4294967296 (4 GB). (Bug #29186)

The minimum allowed value for 'INITIAL_SIZE' is 1048576 (1 MB). (Bug
#29574)

*Note*:

'WAIT' is parsed but otherwise ignored.  This keyword currently has no
effect, and is intended for future expansion.

The 'ENGINE' parameter (required) determines the storage engine which is
used by this log file group, with ENGINE_NAME being the name of the
storage engine.  Currently, the only accepted values for ENGINE_NAME are
''NDBCLUSTER'.' and ''NDB'.'.
The two values are equivalent.

Here is an example, which assumes that the log file group 'lg_3' has
already been created using 'CREATE LOGFILE GROUP'.
(see create-logfile-group):

     ALTER LOGFILE GROUP lg_3
         ADD UNDOFILE 'undo_10.dat'
         INITIAL_SIZE=32M
         ENGINE=NDBCLUSTER;

When 'ALTER LOGFILE GROUP' is used with
'ENGINE = NDBCLUSTER' (alternatively, 'ENGINE = NDB'), an 'UNDO' log
file is created on each NDB Cluster data node.  You can verify that the
'UNDO' files were created and obtain information about them by querying
the 'INFORMATION_SCHEMA.FILES' table.  For example:

     mysql> SELECT FILE_NAME, LOGFILE_GROUP_NUMBER, EXTRA
         -> FROM INFORMATION_SCHEMA.FILES
         -> WHERE LOGFILE_GROUP_NAME = 'lg_3';
     +-------------+----------------------+----------------+
     | FILE_NAME   | LOGFILE_GROUP_NUMBER | EXTRA          |
     +-------------+----------------------+----------------+
     | newdata.dat |                    0 | CLUSTER_NODE=3 |
     | newdata.dat |                    0 | CLUSTER_NODE=4 |
     | undo_10.dat |                   11 | CLUSTER_NODE=3 |
     | undo_10.dat |                   11 | CLUSTER_NODE=4 |
     +-------------+----------------------+----------------+
     4 rows in set (0.01 sec)

(See files-table.)

Memory used for 'UNDO_BUFFER_SIZE' comes from the global pool whose size
is determined by the value of the 'SharedGlobalMemory' data node
configuration parameter.  This includes any default value implied for
this option by the setting of the 'InitialLogFileGroup' data node
configuration parameter.

'ALTER LOGFILE GROUP' is useful only with
Disk Data storage for NDB Cluster.  For more information, see
mysql-cluster-disk-data.

13.1.6 ALTER PROCEDURE Syntax
-----------------------------

     ALTER PROCEDURE PROC_NAME [CHARACTERISTIC ...]

     CHARACTERISTIC:
         COMMENT 'STRING'
       | LANGUAGE SQL
       | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }
       | SQL SECURITY { DEFINER | INVOKER }

This statement can be used to change the characteristics of a stored
procedure.  More than one change may be specified in an 'ALTER PROCEDURE'
statement.  However, you cannot change the
parameters or body of a stored procedure using this statement; to make
such changes, you must drop and re-create the procedure using
'DROP PROCEDURE' and 'CREATE PROCEDURE'.

You must have the 'ALTER ROUTINE' privilege for the procedure.  By
default, that privilege is granted automatically to the procedure
creator.  This behavior can be changed by disabling the
'automatic_sp_privileges' system variable.  See
stored-routines-privileges.

13.1.7 ALTER SERVER Syntax
--------------------------

     ALTER SERVER  SERVER_NAME
         OPTIONS (OPTION [, OPTION] ...)

Alters the server information for 'SERVER_NAME', adjusting any of the
options permitted in the 'CREATE SERVER'.
statement.  The corresponding fields in the 'mysql.servers' table are
updated accordingly.  This statement requires the 'SUPER' privilege.

For example, to update the 'USER' option:

     ALTER SERVER s OPTIONS (USER 'sally');

'ALTER SERVER' causes an implicit commit.  See implicit-commit.

'ALTER SERVER' is not written to the binary log, regardless of the
logging format that is in use.

13.1.8 ALTER TABLE Syntax
-------------------------

     ALTER TABLE TBL_NAME
         [ALTER_SPECIFICATION [, ALTER_SPECIFICATION] ...]
         [PARTITION_OPTIONS]

     ALTER_SPECIFICATION:
         TABLE_OPTIONS
       | ADD [COLUMN] COL_NAME COLUMN_DEFINITION
             [FIRST | AFTER COL_NAME]
       | ADD [COLUMN] (COL_NAME COLUMN_DEFINITION,...)
       | ADD {INDEX|KEY} [INDEX_NAME]
             [INDEX_TYPE] (INDEX_COL_NAME,...) [INDEX_OPTION] ...
       | ADD [CONSTRAINT [SYMBOL]] PRIMARY KEY
             [INDEX_TYPE] (INDEX_COL_NAME,...) [INDEX_OPTION] ...
       | ADD [CONSTRAINT [SYMBOL]]
             UNIQUE [INDEX|KEY] [INDEX_NAME]
             [INDEX_TYPE] (INDEX_COL_NAME,...) [INDEX_OPTION] ...
       | ADD FULLTEXT [INDEX|KEY] [INDEX_NAME]
             (INDEX_COL_NAME,...) [INDEX_OPTION] ...
       | ADD SPATIAL [INDEX|KEY] [INDEX_NAME]
             (INDEX_COL_NAME,...) [INDEX_OPTION] ...
       | ADD [CONSTRAINT [SYMBOL]]
             FOREIGN KEY [INDEX_NAME] (INDEX_COL_NAME,...)
             REFERENCE_DEFINITION
       | ALGORITHM [=] {DEFAULT|INPLACE|COPY}
       | ALTER [COLUMN] COL_NAME {SET DEFAULT LITERAL | DROP DEFAULT}
       | CHANGE [COLUMN] OLD_COL_NAME NEW_COL_NAME COLUMN_DEFINITION
             [FIRST|AFTER COL_NAME]
       | [DEFAULT] CHARACTER SET [=] CHARSET_NAME [COLLATE [=] COLLATION_NAME]
       | CONVERT TO CHARACTER SET CHARSET_NAME [COLLATE COLLATION_NAME]
       | {DISABLE|ENABLE} KEYS
       | {DISCARD|IMPORT} TABLESPACE
       | DROP [COLUMN] COL_NAME
       | DROP {INDEX|KEY} INDEX_NAME
       | DROP PRIMARY KEY
       | DROP FOREIGN KEY FK_SYMBOL
       | FORCE
       | LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}
       | MODIFY [COLUMN] COL_NAME COLUMN_DEFINITION
             [FIRST | AFTER COL_NAME]
       | ORDER BY COL_NAME [, COL_NAME] ...
       | RENAME {INDEX|KEY} OLD_INDEX_NAME TO NEW_INDEX_NAME
       | RENAME [TO|AS] NEW_TBL_NAME
       | {WITHOUT|WITH} VALIDATION
       | ADD PARTITION (PARTITION_DEFINITION)
       | DROP PARTITION PARTITION_NAMES
       | DISCARD PARTITION {PARTITION_NAMES | ALL} TABLESPACE
       | IMPORT PARTITION {PARTITION_NAMES | ALL} TABLESPACE
       | TRUNCATE PARTITION {PARTITION_NAMES | ALL}
       | COALESCE PARTITION NUMBER
       | REORGANIZE PARTITION PARTITION_NAMES INTO (PARTITION_DEFINITIONS)
       | EXCHANGE PARTITION PARTITION_NAME WITH TABLE TBL_NAME [{WITH|WITHOUT} VALIDATION]
       | ANALYZE PARTITION {PARTITION_NAMES | ALL}
       | CHECK PARTITION {PARTITION_NAMES | ALL}
       | OPTIMIZE PARTITION {PARTITION_NAMES | ALL}
       | REBUILD PARTITION {PARTITION_NAMES | ALL}
       | REPAIR PARTITION {PARTITION_NAMES | ALL}
       | REMOVE PARTITIONING
       | UPGRADE PARTITIONING

     INDEX_COL_NAME:
         COL_NAME [(LENGTH)] [ASC | DESC]

     INDEX_TYPE:
         USING {BTREE | HASH}

     INDEX_OPTION:
         KEY_BLOCK_SIZE [=] VALUE
       | INDEX_TYPE
       | WITH PARSER PARSER_NAME
       | COMMENT 'STRING'

     TABLE_OPTIONS:
         TABLE_OPTION [[,] TABLE_OPTION] ...

     TABLE_OPTION:
         AUTO_INCREMENT [=] VALUE
       | AVG_ROW_LENGTH [=] VALUE
       | [DEFAULT] CHARACTER SET [=] CHARSET_NAME
       | CHECKSUM [=] {0 | 1}
       | [DEFAULT] COLLATE [=] COLLATION_NAME
       | COMMENT [=] 'STRING'
       | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'}
       | CONNECTION [=] 'CONNECT_STRING'
       | {DATA|INDEX} DIRECTORY [=] 'ABSOLUTE PATH TO DIRECTORY'
       | DELAY_KEY_WRITE [=] {0 | 1}
       | ENCRYPTION [=] {'Y' | 'N'}
       | ENGINE [=] ENGINE_NAME
       | INSERT_METHOD [=] { NO | FIRST | LAST }
       | KEY_BLOCK_SIZE [=] VALUE
       | MAX_ROWS [=] VALUE
       | MIN_ROWS [=] VALUE
       | PACK_KEYS [=] {0 | 1 | DEFAULT}
       | PASSWORD [=] 'STRING'
       | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT}
       | STATS_AUTO_RECALC [=] {DEFAULT|0|1}
       | STATS_PERSISTENT [=] {DEFAULT|0|1}
       | STATS_SAMPLE_PAGES [=] VALUE
       | TABLESPACE TABLESPACE_NAME [STORAGE {DISK|MEMORY|DEFAULT}]
       | UNION [=] (TBL_NAME[,TBL_NAME]...)

     PARTITION_OPTIONS:
         (see CREATE TABLE options)

'ALTER TABLE' changes the structure of a table.  For
example, you can add or delete columns, create or destroy indexes,
change the type of existing columns, or rename columns or the table
itself.  You can also change characteristics such as the storage engine
used for the table or the table comment.

   * To use 'ALTER TABLE', you need 'ALTER',
     'CREATE', and 'INSERT' privileges for the table.  Renaming a table
     requires 'ALTER' and 'DROP' on the old table, 'ALTER', 'CREATE',
     and 'INSERT' on the new table.

   * Following the table name, specify the alterations to be made.  If
     none are given, see 'ALTER TABLE' does nothing.

   * The syntax for many of the permissible alterations is similar to
     clauses of the 'CREATE TABLE' statement.
     COLUMN_DEFINITION clauses use the same syntax for 'ADD' and
     'CHANGE' as for 'CREATE TABLE'.  For more
     information, see create-table.

   * The word 'COLUMN' is optional and can be omitted.

   * Multiple 'ADD', 'ALTER', 'DROP', and 'CHANGE' clauses are permitted
     in a single 'ALTER TABLE' statement, separated
     by commas.  This is a MySQL extension to standard SQL, which
     permits only one of each clause per 'ALTER TABLE'
     statement.  For example, to drop multiple columns in a
     single statement, do this:

          ALTER TABLE t2 DROP COLUMN c, DROP COLUMN d;

   * If a storage engine does not support an attempted 'ALTER TABLE'
     operation, a warning may result.  Such
     warnings can be displayed with 'SHOW WARNINGS'.
     See show-warnings.  For information on
     troubleshooting 'ALTER TABLE', see
     alter-table-problems.

   * For information about generated columns, see
     alter-table-generated-columns.

   * For usage examples, see alter-table-examples.

   * With the 'mysql_info()'. C API function, you can
     find out how many rows were copied by 'ALTER TABLE'.
     See mysql-info.

There are several additional aspects to the 'ALTER TABLE' statement,
described under the following topics in this section:

   * alter-table-options

   * alter-table-performance

   * alter-table-concurrency

   * alter-table-add-drop-column

   * alter-table-redefine-column

   * alter-table-index

   * alter-table-foreign-key

   * alter-table-character-set

   * alter-table-discard-import

   * alter-table-row-order

   * alter-table-partition-options

*Table Options*

TABLE_OPTIONS signifies table options of the kind that can be used in
the 'CREATE TABLE' statement, such as 'ENGINE',
'AUTO_INCREMENT', 'AVG_ROW_LENGTH', 'MAX_ROWS', 'ROW_FORMAT', or
'TABLESPACE'.

For descriptions of all table options, see create-table.
However, see 'ALTER TABLE' ignores 'DATA DIRECTORY' and
'INDEX DIRECTORY' when given as table options.  'ALTER TABLE'
permits them only as partitioning options, and, as of MySQL
5.7.17, requires that you have the 'FILE' privilege.

Use of table options with 'ALTER TABLE' provides a
convenient way of altering single table characteristics.  For example:

   * If 't1' is currently not an 'InnoDB' table, this statement changes
     its storage engine to 'InnoDB':

          ALTER TABLE t1 ENGINE = InnoDB;

        * See converting-tables-to-innodb for considerations
          when switching tables to the 'InnoDB' storage engine.

        * When you specify an 'ENGINE' clause, see 'ALTER TABLE'
          rebuilds the table.  This is true even if the
          table already has the specified storage engine.

        * Running 'ALTER TABLE TBL_NAME ENGINE=INNODB'
          on an existing 'InnoDB' table performs a 'null'
          'ALTER TABLE' operation, which can be used
          to defragment an 'InnoDB' table, as described in
          innodb-file-defragmenting.  Running 'ALTER TABLE TBL_NAME FORCE'
          on an 'InnoDB' table performs
          the same function.

        * 'ALTER TABLE TBL_NAME ENGINE=INNODB' and
          'ALTER TABLE TBL_NAME FORCE' use
          online DDL.  For more information, see
          innodb-create-index-overview.

        * The outcome of attempting to change the storage engine of a
          table is affected by whether the desired storage engine is
          available and the setting of the 'NO_ENGINE_SUBSTITUTION' SQL
          mode, as described in sql-mode.

        * To prevent inadvertent loss of data, see 'ALTER TABLE'
          cannot be used to change the storage engine of a
          table to 'MERGE' or 'BLACKHOLE'.

   * To change the 'InnoDB' table to use compressed row-storage format:

          ALTER TABLE t1 ROW_FORMAT = COMPRESSED;

   * If the 'InnoDB' tablespace encryption feature is enabled (see
     innodb-tablespace-encryption), encryption for 't1' can be enabled
     or disabled like this:

          ALTER TABLE t1 ENCRYPTION='Y';
          ALTER TABLE t1 ENCRYPTION='N';

   * To reset the current auto-increment value:

          ALTER TABLE t1 AUTO_INCREMENT = 13;

     You cannot reset the counter to a value less than or equal to the
     value that is currently in use.  For both 'InnoDB' and 'MyISAM', if
     the value is less than or equal to the maximum value currently in
     the 'AUTO_INCREMENT' column, the value is reset to the current
     maximum 'AUTO_INCREMENT' column value plus one.

   * To change the default table character set:

          ALTER TABLE t1 CHARACTER SET = utf8;

     See also alter-table-character-set.

   * To add (or change) a table comment:

          ALTER TABLE t1 COMMENT = 'New table comment';

   * Use 'ALTER TABLE' with the 'TABLESPACE' option to move
     non-partitioned 'InnoDB' tables between existing general
     tablespaces, file-per-table tablespaces, and the system tablespace.
     See general-tablespaces-moving-non-partitioned-tables.

        * For partitioned tables, 'ALTER TABLE tbl_name TABLESPACE [=]
          TABLESPACE_NAME' only modifies the default tablespace.  It
          does not move partitions from one tablespace to another.  To
          move table partitions, you must move each partition using
          'ALTER TABLE TBL_NAME REORGANIZE PARTITION'.  See
          general-tablespaces-moving-partitions.

        * 'ALTER TABLE ... TABLESPACE' operations always cause a full
          table rebuild, even if the 'TABLESPACE' attribute has not
          changed from its previous value.

        * 'ALTER TABLE ... TABLESPACE' syntax does not support moving a
          table from a temporary tablespace to a persistent tablespace.

        * The 'DATA DIRECTORY' clause, which is supported with
          'CREATE TABLE ... TABLESPACE', is not supported
          with 'ALTER TABLE ... TABLESPACE', and is ignored if
          specified.

        * For more information about the capabilities and limitations of
          the 'TABLESPACE' option, see 'CREATE TABLE'.

   * MySQL NDB Cluster 7.5.2 and later supports setting 'NDB_TABLE'
     options for controlling a table's partition balance (fragment count
     type), read-from-any-replica capability, full replication, or any
     combination of these, as part of the table comment for an 'ALTER
     TABLE' statement in the same manner as for 'CREATE TABLE',
     as shown in this example:

          ALTER TABLE t1 COMMENT = "NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RA_BY_NODE";

     Bear in mind that 'ALTER TABLE ... COMMENT ...' discards any
     existing comment for the table.  See
     create-table-comment-ndb-table-options, for additional
     information and examples.

To verify that the table options were changed as intended, use
'SHOW CREATE TABLE', or query the
'INFORMATION_SCHEMA.TABLES' table.

*Performance and Storage Considerations*

Some 'ALTER TABLE' operations can be performed in
place without making a temporary copy of the table.  In-place operations
tend to be very fast.

Other 'ALTER TABLE' operations perform the
alteration on a temporary copy of the table, which can require more
time, particularly for large tables.

In-place 'ALTER TABLE' operations that do not
require creating a temporary copy of the original table include:

   * 'ALTER TABLE' operations on 'InnoDB' tables that are supported by
     the 'InnoDB' online DDL feature.  For an overview of supported
     operations, see innodb-create-index-overview.  For
     information about performance and concurrency of online DDL
     operations, see innodb-create-index-concurrency.

   * 'ALTER TABLE TBL_NAME RENAME TO NEW_TBL_NAME'.  When run without
     other options, MySQL renames files that correspond to the table
     TBL_NAME without making a copy.  (You can also use the
     'RENAME TABLE' statement to rename tables.  See
     rename-table.)  Privileges granted specifically for the
     renamed table are not migrated to the new name.  They must be
     changed manually.

   * Alterations that modify only table metadata and not table data are
     immediate because the server only needs to alter the table '.frm'
     file, not touch table contents.  The following changes are made in
     this way:

        * Renaming a column.

        * Changing the default value of a column (except for
          'NDB' tables).

        * Changing the definition of an 'ENUM' or
          'SET' column by adding new enumeration or set members to
          the _end_ of the list of valid member values, as long as the
          storage size of the data type does not change.  For example,
          adding a member to a 'SET' column that has 8
          members changes the required storage per value from 1 byte to
          2 bytes; this requires a table copy.  Adding members in the
          middle of the list causes renumbering of existing members,
          which requires a table copy.

   * Renaming an index.

   * Adding or dropping an index, for 'InnoDB'
     and 'NDB'.  See
     innodb-create-index-overview.

   * For 'NDB' tables, operations that add and
     drop indexes on variable-width columns occur online, without table
     copying and without blocking concurrent DML actions for most of
     their duration.  See alter-table-online-operations.

Specifying 'ALGORITHM=INPLACE' makes the operation use the in-place
technique for clauses and storage engines that support it, and fail with
an error otherwise, thus avoiding a lengthy table copy if you try
altering a table that uses a different storage engine than you expect.

'ALTER TABLE' operations that are *not* performed in
place make a temporary copy of the original table.  MySQL waits for
other operations that are modifying the table, then proceeds.  It
incorporates the alteration into the copy, deletes the original table,
and renames the new one.  While 'ALTER TABLE' is
executing, the original table is readable by other sessions (with the
exception noted shortly).  Updates and writes to the table that begin
after the 'ALTER TABLE' operation begins are stalled
until the new table is ready, then are automatically redirected to the
new table without any failed updates.  The temporary copy of the
original table is created in the database directory of the new table.
This can differ from the database directory of the original table for
'ALTER TABLE' operations that rename the table to a
different database.

The exception referred to earlier is that 'ALTER TABLE'
blocks reads (not just writes) at the point where it is
ready to install a new version of the table '.frm' file, discard the old
file, and clear outdated table structures from the table and table
definition caches.  At this point, it must acquire an exclusive lock.
To do so, it waits for current readers to finish, and blocks new reads
(and writes).

For 'MyISAM' tables, you can speed up index re-creation (the slowest
part of the alteration process) by setting the 'myisam_sort_buffer_size'
system variable to a high value.

For 'InnoDB' tables, a table-copying 'ALTER TABLE'.
operation on table that resides in a shared tablespace such as a general
tablespace or the system tablespace can increase the amount of space
used by the tablespace.  Such operations require as much additional
space as the data in the table plus indexes.  For a table that resides
in a shared tablespace, the additional space used during a table-copying
'ALTER TABLE' operation is not released back to the
operating system as it is for a table that resides in a file-per-table
tablespace.

To force use of the table-copy method for an 'ALTER TABLE' operation
that would otherwise not use it, set the 'old_alter_table' system
variable to 'ON', or specify 'ALGORITHM=COPY' as one of the
ALTER_SPECIFICATION clauses.  If there is a conflict between the
'old_alter_table' setting and an 'ALGORITHM' clause with a value other
than 'DEFAULT', the 'ALGORITHM' clause takes precedence.

Specifying 'ALGORITHM=DEFAULT' is the same a specifying no 'ALGORITHM'
clause at all, in which case 'ALGORITHM=INPLACE' is used if supported by
the storage engine.  Otherwise, 'ALGORITHM=COPY' is used.

An 'ALTER TABLE' operation run with the
'ALGORITHM=COPY' clause prevents concurrent DML operations.  Concurrent
queries are still allowed.  That is, a table-copying operation always
includes at least the concurrency restrictions of 'LOCK=SHARED' (allow
queries but not DML). You can further restrict concurrency for such
operations by specifying 'LOCK=EXCLUSIVE', which prevents DML and
queries.

'ALTER TABLE' upgrades MySQL 5.5 temporal columns to
5.6 format for 'ADD COLUMN', 'CHANGE COLUMN', 'MODIFY COLUMN', 'ADD
INDEX', and 'FORCE' operations.  This conversion cannot be done using
the 'INPLACE' algorithm because the table must be rebuilt, so specifying
'ALGORITHM=INPLACE' in these cases results in an error.  Specify
'ALGORITHM=COPY' if necessary.

If an 'ALTER TABLE' operation on a multicolumn index used to partition a
table by 'KEY' changes the order of the columns, it can only be
performed using 'ALGORITHM=COPY'.

The 'WITHOUT VALIDATION' and 'WITH VALIDATION' clauses affect whether
'ALTER TABLE' performs an in-place operation for
virtual generated column modifications.  See
alter-table-generated-columns.

NDB Cluster formerly supported online 'ALTER TABLE' operations using the
'ONLINE' and 'OFFLINE' keywords.  These keywords are no longer
supported; their use causes a syntax error.  MySQL NDB Cluster 7.5 (and
later) supports online operations using the same 'ALGORITHM=INPLACE'
syntax used with the standard MySQL Server.  See
alter-table-online-operations, for more information.

'ALTER TABLE' with 'DISCARD ... PARTITION ... TABLESPACE' or 'IMPORT ...
PARTITION ... TABLESPACE' does not create any temporary tables or
temporary partition files.

'ALTER TABLE' with 'ADD PARTITION', 'DROP PARTITION', 'COALESCE
PARTITION', 'REBUILD PARTITION', or 'REORGANIZE PARTITION' does not
create temporary tables (except when used with 'NDB'
tables); however, these operations can and do create
temporary partition files.

'ADD' or 'DROP' operations for 'RANGE' or 'LIST' partitions are
immediate operations or nearly so.  'ADD' or 'COALESCE' operations for
'HASH' or 'KEY' partitions copy data between all partitions, unless
'LINEAR HASH' or 'LINEAR KEY' was used; this is effectively the same as
creating a new table, although the 'ADD' or 'COALESCE' operation is
performed partition by partition.  'REORGANIZE' operations copy only
changed partitions and do not touch unchanged ones.

*Locking and Concurrency Control*

To control the level of concurrent reading and writing of the table
while it is being altered, use the 'LOCK' clause.  Specifying a
non-default value for this clause enables you to require a certain
amount of concurrent access or exclusivity during the alter operation,
and halts the operation if the requested degree of locking is not
available.  The parameters for the 'LOCK' clause are:

   *
     LOCK = DEFAULT

     Maximum level of concurrency for the given 'ALGORITHM' clause (if
     any) and 'ALTER TABLE' operation: Permit concurrent reads and
     writes if supported.  If not, permit concurrent reads if supported.
     If not, enforce exclusive access.

   *
     LOCK = NONE

     If supported, permit concurrent reads and writes.  Otherwise, an
     error occurs.

   *
     LOCK = SHARED

     If supported, permit concurrent reads but block writes.  Writes are
     blocked even if concurrent writes are supported by the storage
     engine for the given 'ALGORITHM' clause (if any) and 'ALTER TABLE'
     operation.  If concurrent reads are not supported, an error occurs.

   *
     LOCK = EXCLUSIVE

     Enforce exclusive access.  This is done even if concurrent
     reads/writes are supported by the storage engine for the given
     'ALGORITHM' clause (if any) and 'ALTER TABLE' operation.

*Adding and Dropping Columns*

Use 'ADD' to add new columns to a table, and 'DROP' to remove existing
columns.

'DROP COL_NAME' is a MySQL extension to standard SQL.

To add a column at a specific position within a table row, use 'FIRST'
or 'AFTER COL_NAME'.  The default is to add the column last.

If a table contains only one column, the column cannot be dropped.  If
what you intend is to remove the table, use the 'DROP TABLE'
statement instead.

If columns are dropped from a table, the columns are also removed from
any index of which they are a part.  If all columns that make up an
index are dropped, the index is dropped as well.

*Renaming, Redefining, and Reordering Columns*

The 'CHANGE', 'MODIFY', and 'ALTER' clauses enable the names and
definitions of existing columns to be altered.  They have these
comparative characteristics:

   * 'CHANGE':

        * Can rename a column and change its definition, or both.

        * Has more capability than 'MODIFY', but at the expense of
          convenience for some operations.  'CHANGE' requires naming the
          column twice if not renaming it.

        * With 'FIRST' or 'AFTER', can reorder columns.

   * 'MODIFY':

        * Can change a column definition but not its name.

        * More convenient than 'CHANGE' to change a column definition
          without renaming it.

        * With 'FIRST' or 'AFTER', can reorder columns.

   * 'ALTER': Used only to change a column default value.

'CHANGE' is a MySQL extension to standard SQL. 'MODIFY' is a MySQL
extension for Oracle compatibility.

To alter a column to change both its name and definition, use 'CHANGE',
specifying the old and new names and the new definition.  For example,
to rename an 'INT NOT NULL' column from 'a' to 'b' and change its
definition to use the 'BIGINT' data type while retaining the 'NOT NULL'
attribute, do this:

     ALTER TABLE t1 CHANGE a b BIGINT NOT NULL;

To change a column definition but not its name, use 'CHANGE' or
'MODIFY'.  With 'CHANGE', the syntax requires two column names, so you
must specify the same name twice to leave the name unchanged.  For
example, to change the definition of column 'b', do this:

     ALTER TABLE t1 CHANGE b b INT NOT NULL;

'MODIFY' is more convenient to change the definition without changing
the name because it requires the column name only once:

     ALTER TABLE t1 MODIFY b INT NOT NULL;

To change a column name but not its definition, use 'CHANGE'.  The
syntax requires a column definition, so to leave the definition
unchanged, you must respecify the definition the column currently has.
For example, to rename an 'INT NOT NULL' column from 'b' to 'a', do
this:

     ALTER TABLE t1 CHANGE b a INT NOT NULL;

For column definition changes using 'CHANGE' or 'MODIFY', the definition
must include the data type and all attributes that should apply to the
new column, other than index attributes such as 'PRIMARY KEY' or
'UNIQUE'.  Attributes present in the original definition but not
specified for the new definition are not carried forward.  Suppose that
a column 'col1' is defined as 'INT UNSIGNED DEFAULT 1 COMMENT 'my
column'' and you modify the column as follows, intending to change only
'INT' to 'BIGINT':

     ALTER TABLE t1 MODIFY col1 BIGINT;

That statement changes the data type from 'INT' to 'BIGINT', but it also
drops the 'UNSIGNED', 'DEFAULT', and 'COMMENT' attributes.  To retain
them, the statement must include them explicitly:

     ALTER TABLE t1 MODIFY col1 BIGINT UNSIGNED DEFAULT 1 COMMENT 'my column';

For data type changes using 'CHANGE' or 'MODIFY', MySQL tries to convert
existing column values to the new type as well as possible.

*Warning*:

This conversion may result in alteration of data.  For example, if you
shorten a string column, values may be truncated.  To prevent the
operation from succeeding if conversions to the new data type would
result in loss of data, enable strict SQL mode before using 'ALTER TABLE'.
(see sql-mode).

If you use 'CHANGE' or 'MODIFY' to shorten a column for which an index
exists on the column, and the resulting column length is less than the
index length, MySQL shortens the index automatically.

For columns renamed by 'CHANGE', MySQL automatically renames these
references to the renamed column:

   * Indexes that refer to the old column, including indexes and
     disabled 'MyISAM' indexes.

   * Foreign keys that refer to the old column.

For columns renamed by 'CHANGE', MySQL does not automatically rename
these references to the renamed column:

   * Generated column and partition expressions that refer to the
     renamed column.  You must use 'CHANGE' to redefine such expressions
     in the same 'ALTER TABLE' statement as the one
     that renames the column.

   * Views and stored programs that refer to the renamed column.  You
     must manually alter the definition of these objects to refer to the
     new column name.

To reorder columns within a table, use 'FIRST' and 'AFTER' in 'CHANGE'
or 'MODIFY' operations.

'ALTER ... SET DEFAULT' or 'ALTER ... DROP DEFAULT' specify a new
default value for a column or remove the old default value,
respectively.  If the old default is removed and the column can be
'NULL', the new default is 'NULL'.  If the column cannot be 'NULL',
MySQL assigns a default value as described in
data-type-defaults.

*Primary Keys and Indexes*

'DROP PRIMARY KEY' drops the primary key.  If there is no primary key,
an error occurs.  For information about the performance characteristics
of primary keys, especially for 'InnoDB' tables, see
primary-key-optimization.

If you add a 'UNIQUE INDEX' or 'PRIMARY KEY' to a table, MySQL stores it
before any nonunique index to permit detection of duplicate keys as
early as possible.

'DROP INDEX' removes an index.  This is a MySQL
extension to standard SQL. See drop-index.  To determine index
names, use 'SHOW INDEX FROM TBL_NAME'.

Some storage engines permit you to specify an index type when creating
an index.  The syntax for the INDEX_TYPE specifier is 'USING TYPE_NAME'.
For details about 'USING', see create-index.  The preferred
position is after the column list.  Support for use of the option before
the column list will be removed in a future MySQL release.

INDEX_OPTION values specify additional options for an index.  For
details about permissible INDEX_OPTION values, see create-index.

'RENAME INDEX OLD_INDEX_NAME TO NEW_INDEX_NAME' renames an index.  This
is a MySQL extension to standard SQL. The content of the table remains
unchanged.  OLD_INDEX_NAME must be the name of an existing index in the
table that is not dropped by the same 'ALTER TABLE'.
statement.  NEW_INDEX_NAME is the new index name, which cannot duplicate
the name of an index in the resulting table after changes have been
applied.  Neither index name can be 'PRIMARY'.

If you use 'ALTER TABLE' on a 'MyISAM' table, all
nonunique indexes are created in a separate batch (as for 'REPAIR TABLE').
This should make 'ALTER TABLE'
much faster when you have many indexes.

For 'MyISAM' tables, key updating can be controlled explicitly.  Use
'ALTER TABLE ... DISABLE KEYS' to tell MySQL to stop updating nonunique
indexes.  Then use 'ALTER TABLE ... ENABLE KEYS' to re-create missing
indexes.  'MyISAM' does this with a special algorithm that is much
faster than inserting keys one by one, so disabling keys before
performing bulk insert operations should give a considerable speedup.
Using 'ALTER TABLE ... DISABLE KEYS' requires the 'INDEX' privilege in
addition to the privileges mentioned earlier.

While the nonunique indexes are disabled, they are ignored for
statements such as 'SELECT' and 'EXPLAIN'.
that otherwise would use them.

After an 'ALTER TABLE' statement, it may be
necessary to run 'ANALYZE TABLE' to update index
cardinality information.  See show-index.

*Foreign Keys*

The 'FOREIGN KEY' and 'REFERENCES' clauses are supported by the 'InnoDB'
and 'NDB' storage engines, which implement 'ADD [CONSTRAINT [SYMBOL]]
FOREIGN KEY [INDEX_NAME] (...) REFERENCES ... (...)'.  See
constraint-foreign-key; for information specific to 'InnoDB', see
innodb-foreign-key-constraints.

For other storage engines, the clauses are parsed but ignored.  The
'CHECK' clause is parsed but ignored by all storage engines.  See
create-table.  The reason for accepting but ignoring syntax clauses is
for compatibility, to make it easier to port code from other SQL
servers, and to run applications that create tables with references.
See differences-from-ansi.

For 'ALTER TABLE', unlike 'CREATE TABLE',
'ADD FOREIGN KEY' ignores INDEX_NAME if given and uses an
automatically generated foreign key name.  As a workaround, include the
'CONSTRAINT' clause to specify the foreign key name:

     ADD CONSTRAINT NAME FOREIGN KEY (....) ...

*Important*:

MySQL silently ignores inline 'REFERENCES' specifications, where the
references are defined as part of the column specification.  MySQL
accepts only 'REFERENCES' clauses defined as part of a separate 'FOREIGN
KEY' specification.

*Note*:

Partitioned 'InnoDB' tables do not support foreign keys.  This
restriction does not apply to 'NDB' tables, including those explicitly
partitioned by '[LINEAR] KEY'.  For more information, see
partitioning-limitations-storage-engines.

MySQL Server and NDB Cluster both support the use of 'ALTER TABLE'
to drop foreign keys:

     ALTER TABLE TBL_NAME DROP FOREIGN KEY FK_SYMBOL;

Adding and dropping a foreign key in the same 'ALTER TABLE'
statement is supported for 'ALTER TABLE ... ALGORITHM=INPLACE'
but not for 'ALTER TABLE ... ALGORITHM=COPY'.

The server prohibits changes to foreign key columns that have the
potential to cause loss of referential integrity.  It also prohibits
changes to the data type of such columns that may be unsafe.  For
example, changing 'VARCHAR(20)' to 'VARCHAR(30)'
is permitted, but changing it to 'VARCHAR(1024)' is
not because that alters the number of length bytes required to store
individual values.  A workaround is to use 'ALTER TABLE ... DROP FOREIGN KEY'
before changing the column definition and
'ALTER TABLE ... ADD FOREIGN KEY' afterward.

'ALTER TABLE TBL_NAME RENAME NEW_TBL_NAME' changes internally generated
foreign key constraint names and user-defined foreign key constraint
names that contain the string 'TBL_NAME_ibfk_' to reflect the new table
name.  'InnoDB' interprets foreign key constraint names that contain the
string 'TBL_NAME_ibfk_' as internally generated names.

*Changing the Character Set*

To change the table default character set and all character columns
(see 'CHAR', 'VARCHAR', 'TEXT') to a
new character set, use a statement like this:

     ALTER TABLE TBL_NAME CONVERT TO CHARACTER SET CHARSET_NAME;

The statement also changes the collation of all character columns.  If
you specify no 'COLLATE' clause to indicate which collation to use, the
statement uses default collation for the character set.  If this
collation is inappropriate for the intended table use (for example, if
it would change from a case-sensitive collation to a case-insensitive
collation), specify a collation explicitly.

For a column that has a data type of 'VARCHAR' or one of
the 'TEXT' types, 'CONVERT TO CHARACTER SET' changes the
data type as necessary to ensure that the new column is long enough to
store as many characters as the original column.  For example, a
'TEXT' column has two length bytes, which store the byte-length
of values in the column, up to a maximum of 65,535.  For a 'latin1'
'TEXT' column, each character requires a single byte, so
the column can store up to 65,535 characters.  If the column is
converted to 'utf8', each character might require up to three bytes, for
a maximum possible length of 3 x 65,535 = 196,605 bytes.  That length
does not fit in a 'TEXT' column's length bytes, so MySQL
converts the data type to 'MEDIUMTEXT', which is the
smallest string type for which the length bytes can record a value of
196,605.  Similarly, a 'VARCHAR' column might be converted
to 'MEDIUMTEXT'.

To avoid data type changes of the type just described, do not use
'CONVERT TO CHARACTER SET'.  Instead, use 'MODIFY' to change individual
columns.  For example:

     ALTER TABLE t MODIFY latin1_text_col TEXT CHARACTER SET utf8;
     ALTER TABLE t MODIFY latin1_varchar_col VARCHAR(M) CHARACTER SET utf8;

If you specify 'CONVERT TO CHARACTER SET binary', the 'CHAR',
see 'VARCHAR', and 'TEXT' columns are
converted to their corresponding binary string types (see 'BINARY',
see 'VARBINARY', 'BLOB').
This means that the columns no longer will have a character set
attribute and a subsequent 'CONVERT TO' operation will not apply to
them.

If CHARSET_NAME is 'DEFAULT' in a 'CONVERT TO CHARACTER SET' operation,
the character set named by the 'character_set_database' system variable
is used.

*Warning*:

The 'CONVERT TO' operation converts column values between the original
and named character sets.  This is _not_ what you want if you have a
column in one character set (like 'latin1') but the stored values
actually use some other, incompatible character set (like 'utf8').  In
this case, you have to do the following for each such column:

     ALTER TABLE t1 CHANGE c1 c1 BLOB;
     ALTER TABLE t1 CHANGE c1 c1 TEXT CHARACTER SET utf8;

The reason this works is that there is no conversion when you convert to
or from 'BLOB' columns.

To change only the _default_ character set for a table, use this
statement:

     ALTER TABLE TBL_NAME DEFAULT CHARACTER SET CHARSET_NAME;

The word 'DEFAULT' is optional.  The default character set is the
character set that is used if you do not specify the character set for
columns that you add to a table later (for example, with 'ALTER TABLE
... ADD column').

When the 'foreign_key_checks' system variable is enabled, which is the
default setting, character set conversion is not permitted on tables
that include a character string column used in a foreign key constraint.
The workaround is to disable 'foreign_key_checks' before performing the
character set conversion.  You must perform the conversion on both
tables involved in the foreign key constraint before re-enabling
'foreign_key_checks'.  If you re-enable 'foreign_key_checks' after
converting only one of the tables, an 'ON DELETE CASCADE' or 'ON UPDATE
CASCADE' operation could corrupt data in the referencing table due to
implicit conversion that occurs during these operations (Bug #45290, Bug
#74816).

*Discarding and Importing InnoDB Tablespaces*

An 'InnoDB' table created in its own file-per-table tablespace can be
discarded and imported using the 'DISCARD TABLESPACE' and 'IMPORT
TABLESPACE' options.  These options can be used to import a
file-per-table tablespace from a backup or to copy a file-per-table
tablespace from one database server to another.  See
tablespace-copying.

*Row Order for MyISAM Tables*

'ORDER BY' enables you to create the new table with the rows in a
specific order.  This option is useful primarily when you know that you
query the rows in a certain order most of the time.  By using this
option after major changes to the table, you might be able to get higher
performance.  In some cases, it might make sorting easier for MySQL if
the table is in order by the column that you want to order it by later.

*Note*:

The table does not remain in the specified order after inserts and
deletes.

'ORDER BY' syntax permits one or more column names to be specified for
sorting, each of which optionally can be followed by 'ASC' or 'DESC' to
indicate ascending or descending sort order, respectively.  The default
is ascending order.  Only column names are permitted as sort criteria;
arbitrary expressions are not permitted.  This clause should be given
last after any other clauses.

'ORDER BY' does not make sense for 'InnoDB' tables because 'InnoDB'
always orders table rows according to the clustered index.

When used on a partitioned table, 'ALTER TABLE ... ORDER BY' orders rows
within each partition only.

*Partitioning Options*

PARTITION_OPTIONS signifies options that can be used with partitioned
tables for repartitioning, to add, drop, discard, import, merge, and
split partitions, and to perform partitioning maintenance.

It is possible for an 'ALTER TABLE' statement to
contain a 'PARTITION BY' or 'REMOVE PARTITIONING' clause in an addition
to other alter specifications, but the 'PARTITION BY' or 'REMOVE
PARTITIONING' clause must be specified last after any other
specifications.  The 'ADD PARTITION', 'DROP PARTITION', 'DISCARD
PARTITION', 'IMPORT PARTITION', 'COALESCE PARTITION', 'REORGANIZE
PARTITION', 'EXCHANGE PARTITION', 'ANALYZE PARTITION', 'CHECK
PARTITION', and 'REPAIR PARTITION' options cannot be combined with other
alter specifications in a single 'ALTER TABLE', since the options just
listed act on individual partitions.

For more information about partition options, see create-table,
and alter-table-partition-operations.  For information about and
examples of 'ALTER TABLE ... EXCHANGE PARTITION' statements, see
partitioning-management-exchange.

Prior to MySQL 5.7.6, partitioned 'InnoDB' tables used the generic
'ha_partition' partitioning handler employed by 'MyISAM' and other
storage engines not supplying their own partitioning handlers; in MySQL
5.7.6 and later, such tables are created using the 'InnoDB' storage
engine's own (or 'native') partitioning handler.  Beginning with MySQL
5.7.9, you can upgrade an 'InnoDB' table that was created in MySQL 5.7.6
or earlier (that is, created using 'ha_partition') to the 'InnoDB'
native partition handler using 'ALTER TABLE ... UPGRADE PARTITIONING'.
(Bug #76734, Bug #20727344) This 'ALTER TABLE' syntax does not accept
any other options and can be used only on a single table at a time.  You
can also use 'mysql_upgrade' in MySQL 5.7.9 or
later to upgrade older partitioned 'InnoDB' tables to the native
partitioning handler.

13.1.8.1 ALTER TABLE Partition Operations
.........................................

Partitioning-related clauses for 'ALTER TABLE' can
be used with partitioned tables for repartitioning, to add, drop,
discard, import, merge, and split partitions, and to perform
partitioning maintenance.

   * Simply using a PARTITION_OPTIONS clause with 'ALTER TABLE'
     on a partitioned table repartitions the table
     according to the partitioning scheme defined by the
     PARTITION_OPTIONS.  This clause always begins with 'PARTITION BY',
     and follows the same syntax and other rules as apply to the
     PARTITION_OPTIONS clause for 'CREATE TABLE'.
     (for more detailed information, see create-table), and can
     also be used to partition an existing table that is not already
     partitioned.  For example, consider a (nonpartitioned) table
     defined as shown here:

          CREATE TABLE t1 (
              id INT,
              year_col INT
          );

     This table can be partitioned by 'HASH', using the 'id' column as
     the partitioning key, into 8 partitions by means of this statement:

          ALTER TABLE t1
              PARTITION BY HASH(id)
              PARTITIONS 8;

     MySQL supports an 'ALGORITHM' option with '[SUB]PARTITION BY
     [LINEAR] KEY'.  'ALGORITHM=1' causes the server to use the same
     key-hashing functions as MySQL 5.1 when computing the placement of
     rows in partitions; 'ALGORITHM=2' means that the server employs the
     key-hashing functions implemented and used by default for new 'KEY'
     partitioned tables in MySQL 5.5 and later.  (Partitioned tables
     created with the key-hashing functions employed in MySQL 5.5 and
     later cannot be used by a MySQL 5.1 server.)  Not specifying the
     option has the same effect as using 'ALGORITHM=2'.  This option is
     intended for use chiefly when upgrading or downgrading '[LINEAR]
     KEY' partitioned tables between MySQL 5.1 and later MySQL versions,
     or for creating tables partitioned by 'KEY' or 'LINEAR KEY' on a
     MySQL 5.5 or later server which can be used on a MySQL 5.1 server.

     To upgrade a 'KEY' partitioned table that was created in MySQL 5.1,
     first execute 'SHOW CREATE TABLE' and
     note the exact columns and number of partitions shown.  Now execute
     an 'ALTER TABLE' statement using exactly the same column list and
     number of partitions as in the 'CREATE TABLE' statement, while
     adding 'ALGORITHM=2' immediately following the 'PARTITION BY'
     keywords.  (You should also include the 'LINEAR' keyword if it was
     used for the original table definition.)  An example from a session
     in the 'mysql' client is shown here:

          mysql> SHOW CREATE TABLE p\G
          *************************** 1. row ***************************
                 Table: p
          Create Table: CREATE TABLE `p` (
            `id` int(11) NOT NULL AUTO_INCREMENT,
            `cd` datetime NOT NULL,
            PRIMARY KEY (`id`)
          ) ENGINE=InnoDB DEFAULT CHARSET=latin1
          /*!50100 _PARTITION BY LINEAR KEY (id)
          PARTITIONS 32_ */
          1 row in set (0.00 sec)

          mysql> ALTER TABLE p _PARTITION BY LINEAR KEY ALGORITHM=2 (id) PARTITIONS 32_;
          Query OK, 0 rows affected (5.34 sec)
          Records: 0  Duplicates: 0  Warnings: 0

          mysql> SHOW CREATE TABLE p\G
          *************************** 1. row ***************************
                 Table: p
          Create Table: CREATE TABLE `p` (
            `id` int(11) NOT NULL AUTO_INCREMENT,
            `cd` datetime NOT NULL,
            PRIMARY KEY (`id`)
          ) ENGINE=InnoDB DEFAULT CHARSET=latin1
          /*!50100 PARTITION BY LINEAR KEY (id)
          PARTITIONS 32 */
          1 row in set (0.00 sec)

     Downgrading a table created using the default key-hashing used in
     MySQL 5.5 and later to enable its use by a MySQL 5.1 server is
     similar, except in this case you should use 'ALGORITHM=1' to force
     the table's partitions to be rebuilt using the MySQL 5.1
     key-hashing functions.  It is recommended that you not do this
     except when necessary for compatibility with a MySQL 5.1 server, as
     the improved 'KEY' hashing functions used by default in MySQL 5.5
     and later provide fixes for a number of issues found in the older
     implementation.

     *Note*:

     A table upgraded by means of 'ALTER TABLE ... PARTITION BY
     ALGORITHM=2 [LINEAR] KEY ...' can no longer be used by a MySQL 5.1
     server.  (Such a table would need to be downgraded with 'ALTER
     TABLE ... PARTITION BY ALGORITHM=1 [LINEAR] KEY ...' before it
     could be used again by a MySQL 5.1 server.)

     The table that results from using an 'ALTER TABLE ... PARTITION BY'
     statement must follow the same rules as one created using 'CREATE
     TABLE ... PARTITION BY'.  This includes the rules governing the
     relationship between any unique keys (including any primary key)
     that the table might have, and the column or columns used in the
     partitioning expression, as discussed in
     partitioning-limitations-partitioning-keys-unique-keys.  The
     'CREATE TABLE ... PARTITION BY' rules for specifying the number of
     partitions also apply to 'ALTER TABLE ... PARTITION BY'.

     The PARTITION_DEFINITION clause for 'ALTER TABLE ADD PARTITION'
     supports the same options as the clause of the same name for the
     'CREATE TABLE' statement.  (See
     create-table, for the syntax and description.)  Suppose that you
     have the partitioned table created as shown here:

          CREATE TABLE t1 (
              id INT,
              year_col INT
          )
          PARTITION BY RANGE (year_col) (
              PARTITION p0 VALUES LESS THAN (1991),
              PARTITION p1 VALUES LESS THAN (1995),
              PARTITION p2 VALUES LESS THAN (1999)
          );

     You can add a new partition 'p3' to this table for storing values
     less than '2002' as follows:

          ALTER TABLE t1 ADD PARTITION (PARTITION p3 VALUES LESS THAN (2002));

     'ADD PARTITION' can also be used with the 'TABLESPACE' clause to
     add a new partition to an existing general tablespace, to a
     file-per-table tablespace, or to the system tablespace.

          ALTER TABLE t1 ADD PARTITION
              (PARTITION p4 VALUES LESS THAN (2015) TABLESPACE = `ts1`);

          ALTER TABLE t1 ADD PARTITION
              (PARTITION p4 VALUES LESS THAN (2015) TABLESPACE = `innodb_file_per_table`);

          ALTER TABLE t1 ADD PARTITION
              (PARTITION p4 VALUES LESS THAN (2015) TABLESPACE = `innodb_system`);

     *Note*:

     If the 'TABLESPACE = TABLESPACE_NAME' option is not defined, the
     'ALTER TABLE ... ADD PARTITION' operation adds
     the partition to the table's default tablespace, which can be
     specified at the table level during 'CREATE TABLE'
     or 'ALTER TABLE'.

     'DROP PARTITION' can be used to drop one or more 'RANGE' or 'LIST'
     partitions.  This statement cannot be used with 'HASH' or 'KEY'
     partitions; instead, use 'COALESCE PARTITION' (see below).  Any
     data that was stored in the dropped partitions named in the
     PARTITION_NAMES list is discarded.  For example, given the table
     't1' defined previously, you can drop the partitions named 'p0' and
     'p1' as shown here:

          ALTER TABLE t1 DROP PARTITION p0, p1;

     *Note*:

     'DROP PARTITION' does not work with tables that use the
     'NDB' storage engine.  See
     partitioning-management-range-list, and
     mysql-cluster-limitations.

     'ADD PARTITION' and 'DROP PARTITION' do not currently support 'IF
     [NOT] EXISTS'.

     'DISCARD PARTITION ... TABLESPACE' and
     'IMPORT PARTITION ... TABLESPACE' options extend the
     Transportable Tablespace feature to individual 'InnoDB' table
     partitions.  Each 'InnoDB' table partition has its own tablespace
     file ('.idb' file).  The Transportable Tablespace feature makes it
     easy to copy the tablespaces from a running MySQL server instance
     to another running instance, or to perform a restore on the same
     instance.  Both options take a list of one or more comma-separated
     partition names.  For example:

          ALTER TABLE t1 DISCARD PARTITION p2, p3 TABLESPACE;

          ALTER TABLE t1 IMPORT PARTITION p2, p3 TABLESPACE;

     When running 'DISCARD PARTITION ... TABLESPACE'.
     and 'IMPORT PARTITION ... TABLESPACE' on
     subpartitioned tables, both partition and subpartition names are
     allowed.  When a partition name is specified, subpartitions of that
     partition are included.

     The Transportable Tablespace feature also supports copying or
     restoring partitioned 'InnoDB' tables (all partitions at once).
     For addition information about the Transportable Tablespace
     feature, see tablespace-copying.  For usage examples, see
     innodb-transportable-tablespace-examples.

     Renames of partitioned tables are supported.  You can rename
     individual partitions indirectly using 'ALTER TABLE ... REORGANIZE
     PARTITION'; however, this operation copies the partition's data.

     To delete rows from selected partitions, use the 'TRUNCATE
     PARTITION' option.  This option takes a comma-separated list of one
     or more partition names.  For example, consider the table 't1' as
     defined here:

          CREATE TABLE t1 (
              id INT,
              year_col INT
          )
          PARTITION BY RANGE (year_col) (
              PARTITION p0 VALUES LESS THAN (1991),
              PARTITION p1 VALUES LESS THAN (1995),
              PARTITION p2 VALUES LESS THAN (1999),
              PARTITION p3 VALUES LESS THAN (2003),
              PARTITION p4 VALUES LESS THAN (2007)
          );

     To delete all rows from partition 'p0', use the following
     statement:

          ALTER TABLE t1 TRUNCATE PARTITION p0;

     The statement just shown has the same effect as the following
     'DELETE' statement:

          DELETE FROM t1 WHERE year_col < 1991;

     When truncating multiple partitions, the partitions do not have to
     be contiguous: This can greatly simplify delete operations on
     partitioned tables that would otherwise require very complex
     'WHERE' conditions if done with 'DELETE' statements.
     For example, this statement deletes all rows from partitions 'p1'
     and 'p3':

          ALTER TABLE t1 TRUNCATE PARTITION p1, p3;

     An equivalent 'DELETE' statement is shown here:

          DELETE FROM t1 WHERE
              (year_col >= 1991 AND year_col < 1995)
              OR
              (year_col >= 2003 AND year_col < 2007);

     If you use the 'ALL' keyword in place of the list of partition
     names, the statement acts on all table partitions.

     'TRUNCATE PARTITION' merely deletes rows; it does not alter the
     definition of the table itself, or of any of its partitions.

     To verify that the rows were dropped, check the
     'INFORMATION_SCHEMA.PARTITIONS' table, using a query such as this
     one:

          SELECT PARTITION_NAME, TABLE_ROWS
              FROM INFORMATION_SCHEMA.PARTITIONS
              WHERE TABLE_NAME = 't1';

     'TRUNCATE PARTITION' is supported only for partitioned tables that
     use the 'MyISAM', 'InnoDB',
     or 'MEMORY'.
     storage engine.  It also works on 'BLACKHOLE'
     tables (but has no effect).  It is not
     supported for 'ARCHIVE' tables.

     'COALESCE PARTITION' can be used with a table that is partitioned
     by 'HASH' or 'KEY' to reduce the number of partitions by NUMBER.
     Suppose that you have created table 't2' as follows:

          CREATE TABLE t2 (
              name VARCHAR (30),
              started DATE
          )
          PARTITION BY HASH( YEAR(started) )
          PARTITIONS 6;

     To reduce the number of partitions used by 't2' from 6 to 4, use
     the following statement:

          ALTER TABLE t2 COALESCE PARTITION 2;

     The data contained in the last NUMBER partitions will be merged
     into the remaining partitions.  In this case, partitions 4 and 5
     will be merged into the first 4 partitions (the partitions numbered
     0, 1, 2, and 3).

     To change some but not all the partitions used by a partitioned
     table, you can use 'REORGANIZE PARTITION'.  This statement can be
     used in several ways:

        * To merge a set of partitions into a single partition.  This is
          done by naming several partitions in the PARTITION_NAMES list
          and supplying a single definition for PARTITION_DEFINITION.

        * To split an existing partition into several partitions.
          Accomplish this by naming a single partition for
          PARTITION_NAMES and providing multiple PARTITION_DEFINITIONS.

        * To change the ranges for a subset of partitions defined using
          'VALUES LESS THAN' or the value lists for a subset of
          partitions defined using 'VALUES IN'.

        * To move a partition from one tablespace to another.  For an
          example, see general-tablespaces-moving-partitions.

        * This statement may also be used without the 'PARTITION_NAMES
          INTO (PARTITION_DEFINITIONS)' option on tables that are
          automatically partitioned using 'HASH' partitioning to force
          redistribution of data.  (Currently, only 'NDB'
          tables are automatically partitioned in this
          way.)  This is useful in NDB Cluster where, after you have
          added new NDB Cluster data nodes online to an existing NDB
          Cluster, you wish to redistribute existing NDB Cluster table
          data to the new data nodes.  In such cases, you should invoke
          the statement with the 'ALGORITHM=INPLACE' option; in other
          words, as shown here:

               ALTER TABLE TABLE ALGORITHM=INPLACE, REORGANIZE PARTITION;

          You cannot perform other DDL concurrently with online table
          reorganization--that is, no other DDL statements can be issued
          while an 'ALTER TABLE ... ALGORITHM=INPLACE, REORGANIZE
          PARTITION' statement is executing.  For more information about
          adding NDB Cluster data nodes online, see
          mysql-cluster-online-add-node.

          *Note*:

          'ALTER TABLE ... ALGORITHM=INPLACE, REORGANIZE PARTITION' does
          not work with tables which were created using the 'MAX_ROWS'
          option, because it uses the constant 'MAX_ROWS' value
          specified in the original 'CREATE TABLE'.
          statement to determine the number of partitions required, so
          no new partitions are created.  Instead, you can use 'ALTER
          TABLE ... ALGORITHM=INPLACE, MAX_ROWS=ROWS' to increase the
          maximum number of rows for such a table; in this case, 'ALTER
          TABLE ... ALGORITHM=INPLACE, REORGANIZE PARTITION' is not
          needed (and causes an error if executed).  The value of ROWS
          must be greater than the value specified for 'MAX_ROWS' in the
          original 'CREATE TABLE' statement for this to work.

          Employing 'MAX_ROWS' to force the number of table partitions
          is deprecated in NDB 7.5.4 and later; use 'PARTITION_BALANCE'
          instead (see create-table-comment-ndb-table-options).

          Attempting to use 'REORGANIZE PARTITION' without the
          'PARTITION_NAMES INTO (PARTITION_DEFINITIONS)' option on
          explicitly partitioned tables results in the error 'REORGANIZE
          PARTITION without parameters can only be used on
          auto-partitioned tables using HASH partitioning'.

     *Note*:

     For partitions that have not been explicitly named, MySQL
     automatically provides the default names 'p0', 'p1', 'p2', and so
     on.  The same is true with regard to subpartitions.

     For more detailed information about and examples of 'ALTER TABLE
     ... REORGANIZE PARTITION' statements, see
     partitioning-management-range-list.

   * To exchange a table partition or subpartition with a table, use the
     'ALTER TABLE ... EXCHANGE PARTITION'.
     statement--that is, to move any existing rows in the partition or
     subpartition to the nonpartitioned table, and any existing rows in
     the nonpartitioned table to the table partition or subpartition.

     For usage information and examples, see
     partitioning-management-exchange.

   * Several options provide partition maintenance and repair
     functionality analogous to that implemented for nonpartitioned
     tables by statements such as 'CHECK TABLE' and
     'REPAIR TABLE'. (which are also supported for
     partitioned tables; for more information, see
     table-maintenance-sql).  These include 'ANALYZE PARTITION',
     'CHECK PARTITION', 'OPTIMIZE PARTITION', 'REBUILD PARTITION', and
     'REPAIR PARTITION'.  Each of these options takes a PARTITION_NAMES
     clause consisting of one or more names of partitions, separated by
     commas.  The partitions must already exist in the table to be
     altered.  You can also use the 'ALL' keyword in place of
     PARTITION_NAMES, in which case the statement acts on all table
     partitions.  For more information and examples, see
     partitioning-maintenance.

     Some MySQL storage engines, such as 'InnoDB',
     do not support per-partition optimization.
     For a partitioned table using such a storage engine, 'ALTER TABLE
     ... OPTIMIZE PARTITION' causes the entire table to rebuilt and
     analyzed, and an appropriate warning to be issued.  (Bug #11751825,
     Bug #42822)

     To work around this problem, use the statements 'ALTER TABLE ...
     REBUILD PARTITION' and 'ALTER TABLE ... ANALYZE PARTITION' instead.

     The 'ANALYZE PARTITION', 'CHECK PARTITION', 'OPTIMIZE PARTITION',
     and 'REPAIR PARTITION' options are not permitted for tables which
     are not partitioned.

   * 'REMOVE PARTITIONING' enables you to remove a table's partitioning
     without otherwise affecting the table or its data.  This option can
     be combined with other 'ALTER TABLE' options
     such as those used to add, drop, or rename columns or indexes.

   * Using the 'ENGINE' option with 'ALTER TABLE'.
     changes the storage engine used by the table without affecting the
     partitioning.

When 'ALTER TABLE ... EXCHANGE PARTITION' or 'ALTER TABLE ... TRUNCATE
PARTITION' is run against a partitioned table that uses 'MyISAM'.
(or another storage engine that makes use of
table-level locking), only those partitions that are actually read from
are locked.  (This does not apply to partitioned tables using a storage
enginethat employs row-level locking, such as 'InnoDB')
See partitioning-limitations-locking.

It is possible for an 'ALTER TABLE' statement to
contain a 'PARTITION BY' or 'REMOVE PARTITIONING' clause in an addition
to other alter specifications, but the 'PARTITION BY' or 'REMOVE
PARTITIONING' clause must be specified last after any other
specifications.

The 'ADD PARTITION', 'DROP PARTITION', 'COALESCE PARTITION', 'REORGANIZE
PARTITION', 'ANALYZE PARTITION', 'CHECK PARTITION', and 'REPAIR
PARTITION' options cannot be combined with other alter specifications in
a single 'ALTER TABLE', since the options just listed act on individual
partitions.  For more information, see
alter-table-partition-operations.

Only a single instance of any one of the following options can be used
in a given 'ALTER TABLE' statement: 'PARTITION BY',
'ADD PARTITION', 'DROP PARTITION', 'TRUNCATE PARTITION', 'EXCHANGE
PARTITION', 'REORGANIZE PARTITION', or 'COALESCE PARTITION', 'ANALYZE
PARTITION', 'CHECK PARTITION', 'OPTIMIZE PARTITION', 'REBUILD
PARTITION', 'REMOVE PARTITIONING'.

For example, the following two statements are invalid:

     ALTER TABLE t1 ANALYZE PARTITION p1, ANALYZE PARTITION p2;

     ALTER TABLE t1 ANALYZE PARTITION p1, CHECK PARTITION p2;

In the first case, you can analyze partitions 'p1' and 'p2' of table
't1' concurrently using a single statement with a single 'ANALYZE
PARTITION' option that lists both of the partitions to be analyzed, like
this:

     ALTER TABLE t1 ANALYZE PARTITION p1, p2;

In the second case, it is not possible to perform 'ANALYZE' and 'CHECK'
operations on different partitions of the same table concurrently.
Instead, you must issue two separate statements, like this:

     ALTER TABLE t1 ANALYZE PARTITION p1;
     ALTER TABLE t1 CHECK PARTITION p2;

'REBUILD' operations are currently unsupported for subpartitions.  The
'REBUILD' keyword is expressly disallowed with subpartitions, and causes
'ALTER TABLE' to fail with an error if so used.

'CHECK PARTITION 'and' REPAIR PARTITION' operations fail when the
partition to be checked or repaired contains any duplicate key errors.

For more information about these statements, see
partitioning-maintenance.

13.1.8.2 ALTER TABLE Online Operations in NDB Cluster
.....................................................

MySQL NDB Cluster 7.5 supports online table schema changes using the
standard 'ALTER TABLE' syntax employed by the MySQL
Server ('ALGORITHM=DEFAULT|INPLACE|COPY'), and described elsewhere.

*Note*:

Some older releases of NDB Cluster used a syntax specific to
'NDB' for online 'ALTER TABLE' operations.  That syntax
has since been removed.

Operations that add and drop indexes on variable-width columns of
'NDB' tables occur online.  Online operations are
noncopying; that is, they do not require that indexes be re-created.
They do not lock the table being altered from access by other API nodes
in an NDB Cluster (but see alter-table-online-limitations, later
in this section).  Such operations do not require single user mode for
'NDB' table alterations made in an NDB cluster
with multiple API nodes; transactions can continue uninterrupted during
online DDL operations.

'ALGORITHM=INPLACE' can be used to perform online 'ADD COLUMN', 'ADD
INDEX' (including 'CREATE INDEX' statements), and 'DROP INDEX'
operations on 'NDB' tables.  Online renaming of
'NDB' tables is also supported.

Currently you cannot add disk-based columns to 'NDB'
tables online.  This means that, if you wish to add an
in-memory column to an 'NDB' table that uses a
table-level 'STORAGE DISK' option, you must declare the new column as
using memory-based storage explicitly.  For example--assuming that you
have already created tablespace 'ts1'--suppose that you create table
't1' as follows:

     mysql> CREATE TABLE t1 (
          >     c1 INT NOT NULL PRIMARY KEY,
          >     c2 VARCHAR(30)
          >     )
          >     TABLESPACE ts1 STORAGE DISK
          >     ENGINE NDB;
     Query OK, 0 rows affected (1.73 sec)
     Records: 0  Duplicates: 0  Warnings: 0

You can add a new in-memory column to this table online as shown here:

     mysql> ALTER TABLE t1
          >     ADD COLUMN c3 INT COLUMN_FORMAT DYNAMIC STORAGE MEMORY,
          >     ALGORITHM=INPLACE;
     Query OK, 0 rows affected (1.25 sec)
     Records: 0  Duplicates: 0  Warnings: 0

This statement fails if the 'STORAGE MEMORY' option is omitted:

     mysql> ALTER TABLE t1
          >     ADD COLUMN c4 INT COLUMN_FORMAT DYNAMIC,
          >     ALGORITHM=INPLACE;
     ERROR 1846 (0A000): ALGORITHM=INPLACE is not supported. Reason:
     Adding column(s) or add/reorganize partition not supported online. Try
     ALGORITHM=COPY.

If you omit the 'COLUMN_FORMAT DYNAMIC' option, the dynamic column
format is employed automatically, but a warning is issued, as shown
here:

     mysql> ALTER ONLINE TABLE t1 ADD COLUMN c4 INT STORAGE MEMORY;
     Query OK, 0 rows affected, 1 warning (1.17 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Warning
        Code: 1478
     Message: DYNAMIC column c4 with STORAGE DISK is not supported, column will
     become FIXED

     mysql> SHOW CREATE TABLE t1\G
     *************************** 1. row ***************************
            Table: t1
     Create Table: CREATE TABLE `t1` (
       `c1` int(11) NOT NULL,
       `c2` varchar(30) DEFAULT NULL,
       `c3` int(11) /*!50606 STORAGE MEMORY */ /*!50606 COLUMN_FORMAT DYNAMIC */ DEFAULT NULL,
       `c4` int(11) /*!50606 STORAGE MEMORY */ DEFAULT NULL,
       PRIMARY KEY (`c1`)
     ) /*!50606 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1
     1 row in set (0.03 sec)

*Note*:

The 'STORAGE' and 'COLUMN_FORMAT' keywords are supported only in NDB
Cluster; in any other version of MySQL, attempting to use either of
these keywords in a 'CREATE TABLE' or 'ALTER TABLE'
statement results in an error.

It is also possible to use the statement 'ALTER TABLE ... REORGANIZE
PARTITION, ALGORITHM=INPLACE' with no 'PARTITION_NAMES INTO
(PARTITION_DEFINITIONS)' option on 'NDB' tables.
This can be used to redistribute NDB Cluster data among new data nodes
that have been added to the cluster online.  This does _not_ perform any
defragmentation, which requires an 'OPTIMIZE TABLE'
or null 'ALTER TABLE' statement.
For more information, see mysql-cluster-online-add-node.

*Limitations of NDB Cluster online operations*

Online 'DROP COLUMN' operations are not supported.

Online 'ALTER TABLE', 'CREATE INDEX',
or 'DROP INDEX' statements that add
columns or add or drop indexes are subject to the following limitations:

   * A given online 'ALTER TABLE' can use only one
     of 'ADD COLUMN', 'ADD INDEX', or 'DROP INDEX'.  One or more columns
     can be added online in a single statement; only one index may be
     created or dropped online in a single statement.

   * The table being altered is not locked with respect to API nodes
     other than the one on which an online 'ALTER TABLE'.
     'ADD COLUMN', 'ADD INDEX', or 'DROP INDEX' operation
     (or 'CREATE INDEX' or 'DROP INDEX'
     statement) is run.  However, the table is locked
     against any other operations originating on the _same_ API node
     while the online operation is being executed.

   * The table to be altered must have an explicit primary key; the
     hidden primary key created by the 'NDB'.
     storage engine is not sufficient for this purpose.

   * The storage engine used by the table cannot be changed online.

   * When used with NDB Cluster Disk Data tables, it is not possible to
     change the storage type ('DISK' or 'MEMORY') of a column online.
     This means, that when you add or drop an index in such a way that
     the operation would be performed online, and you want the storage
     type of the column or columns to be changed, you must use
     'ALGORITHM=COPY' in the statement that adds or drops the index.

Columns to be added online cannot use the 'BLOB' or
'TEXT' type, and must meet the following criteria:

   * The columns must be dynamic; that is, it must be possible to create
     them using 'COLUMN_FORMAT DYNAMIC'.  If you omit the 'COLUMN_FORMAT
     DYNAMIC' option, the dynamic column format is employed
     automatically.

   * The columns must permit 'NULL' values and not have any explicit
     default value other than 'NULL'.  Columns added online are
     automatically created as 'DEFAULT NULL', as can be seen here:

          mysql> CREATE TABLE t2 (
               >     c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY
               >     ) ENGINE=NDB;
          Query OK, 0 rows affected (1.44 sec)

          mysql> ALTER TABLE t2
               >     ADD COLUMN c2 INT,
               >     ADD COLUMN c3 INT,
               >     ALGORITHM=INPLACE;
          Query OK, 0 rows affected, 2 warnings (0.93 sec)

          mysql> SHOW CREATE TABLE t1\G
          *************************** 1. row ***************************
                 Table: t1
          Create Table: CREATE TABLE `t2` (
            `c1` int(11) NOT NULL AUTO_INCREMENT,
            `c2` int(11) DEFAULT NULL,
            `c3` int(11) DEFAULT NULL,
            PRIMARY KEY (`c1`)
          ) ENGINE=ndbcluster DEFAULT CHARSET=latin1
          1 row in set (0.00 sec)

   * The columns must be added following any existing columns.  If you
     attempt to add a column online before any existing columns or using
     the 'FIRST' keyword, the statement fails with an error.

   * Existing table columns cannot be reordered online.

For online 'ALTER TABLE' operations on 'NDB'
tables, fixed-format columns are converted to dynamic
when they are added online, or when indexes are created or dropped
online, as shown here (repeating the 'CREATE TABLE' and 'ALTER TABLE'
statements just shown for the sake of clarity):

     mysql> CREATE TABLE t2 (
          >     c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY
          >     ) ENGINE=NDB;
     Query OK, 0 rows affected (1.44 sec)

     mysql> ALTER TABLE t2
          >     ADD COLUMN c2 INT,
          >     ADD COLUMN c3 INT,
          >     ALGORITHM=INPLACE;
     Query OK, 0 rows affected, 2 warnings (0.93 sec)

     mysql> SHOW WARNINGS;
     *************************** 1. row ***************************
       Level: Warning
        Code: 1478
     Message: Converted FIXED field 'c2' to DYNAMIC to enable online ADD COLUMN
     *************************** 2. row ***************************
       Level: Warning
        Code: 1478
     Message: Converted FIXED field 'c3' to DYNAMIC to enable online ADD COLUMN
     2 rows in set (0.00 sec)

Only the column or columns to be added online must be dynamic.  Existing
columns need not be; this includes the table's primary key, which may
also be 'FIXED', as shown here:

     mysql> CREATE TABLE t3 (
          >     c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY COLUMN_FORMAT FIXED
          >     ) ENGINE=NDB;
     Query OK, 0 rows affected (2.10 sec)

     mysql> ALTER TABLE t3 ADD COLUMN c2 INT, ALGORITHM=INPLACE;
     Query OK, 0 rows affected, 1 warning (0.78 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> SHOW WARNINGS;
     *************************** 1. row ***************************
       Level: Warning
        Code: 1478
     Message: Converted FIXED field 'c2' to DYNAMIC to enable online ADD COLUMN
     1 row in set (0.00 sec)

Columns are not converted from 'FIXED' to 'DYNAMIC' column format by
renaming operations.  For more information about 'COLUMN_FORMAT', see
create-table.

The 'KEY', 'CONSTRAINT', and 'IGNORE' keywords are supported in
'ALTER TABLE' statements using 'ALGORITHM=INPLACE'.

Beginning with NDB Cluster 7.5.7 and 7.6.3, setting 'MAX_ROWS' to 0
using an online 'ALTER TABLE' statement is disallowed.  You must use a
copying 'ALTER TABLE' to perform this operation.  (Bug #21960004)

13.1.8.3 ALTER TABLE and Generated Columns
..........................................

'ALTER TABLE' operations permitted for generated columns are 'ADD',
'MODIFY', and 'CHANGE'.

   * Generated columns can be added.

   * The data type and expression of generated columns can be modified.

   * Generated columns can be renamed or dropped, if no other column
     refers to them.

   * Virtual generated columns cannot be altered to stored generated
     columns, or vice versa.  To work around this, drop the column, then
     add it with the new definition.

   * Nongenerated columns can be altered to stored but not virtual
     generated columns.

   * Stored but not virtual generated columns can be altered to
     nongenerated columns.  The stored generated values become the
     values of the nongenerated column.

   * 'ADD COLUMN' is not an in-place operation for stored columns (done
     without using a temporary table) because the expression must be
     evaluated by the server.  For stored columns, indexing changes are
     done in place, and expression changes are not done in place.
     Changes to column comments are done in place.

   * For non-partitioned tables, 'ADD COLUMN' and 'DROP COLUMN' are
     in-place operations for virtual columns.  However, adding or
     dropping a virtual column cannot be performed in place in
     combination with other 'ALTER TABLE'.
     operations.

     For partitioned tables, 'ADD COLUMN' and 'DROP COLUMN' are not
     in-place operations for virtual columns.

   * 'InnoDB' supports secondary indexes on virtual generated columns.
     Adding or dropping a secondary index on a virtual generated column
     is an in-place operation.  For more information, see
     create-table-secondary-indexes.

   * When a 'VIRTUAL' generated column is added to a table or modified,
     it is not ensured that data being calculated by the generated
     column expression will not be out of range for the column.  This
     can lead to inconsistent data being returned and unexpectedly
     failed statements.  To permit control over whether validation
     occurs for such columns, 'ALTER TABLE' supports 'WITHOUT
     VALIDATION' and 'WITH VALIDATION' clauses:

        * With 'WITHOUT VALIDATION' (the default if neither clause is
          specified), an in-place operation is performed (if possible),
          data integrity is not checked, and the statement finishes more
          quickly.  However, later reads from the table might report
          warnings or errors for the column if values are out of range.

        * With 'WITH VALIDATION', 'ALTER TABLE' copies the table.  If an
          out-of-range or any other error occurs, the statement fails.
          Because a table copy is performed, the statement takes longer.

     'WITHOUT VALIDATION' and 'WITH VALIDATION' are permitted only with
     'ADD COLUMN', 'CHANGE COLUMN', and 'MODIFY COLUMN' operations.
     Otherwise, an 'ER_WRONG_USAGE' error occurs.

   * As of MySQL 5.7.10, if expression evaluation causes truncation or
     provides incorrect input to a function, the 'ALTER TABLE'
     statement terminates with an error and the DDL
     operation is rejected.

   * An 'ALTER TABLE' statement that changes the
     default value of a column COL_NAME may also change the value of a
     generated column expression that refers to the column using
     'DEFAULT(COL_NAME)'.  For this reason, as of MySQL 5.7.13, see
     'ALTER TABLE' operations that change the definition
     of a column now cause a table rebuild if any generated column
     expression uses 'DEFAULT()'.

13.1.8.4 ALTER TABLE Examples
.............................

Begin with a table 't1' created as shown here:

     CREATE TABLE t1 (a INTEGER, b CHAR(10));

To rename the table from 't1' to 't2':

     ALTER TABLE t1 RENAME t2;

To change column 'a' from 'INTEGER' to 'TINYINT
NOT NULL' (leaving the name the same), and to change column 'b' from
'CHAR(10)' to 'CHAR(20)' as well as renaming it from 'b' to 'c':

     ALTER TABLE t2 MODIFY a TINYINT NOT NULL, CHANGE b c CHAR(20);

To add a new 'TIMESTAMP' column named 'd':

     ALTER TABLE t2 ADD d TIMESTAMP;

To add an index on column 'd' and a 'UNIQUE' index on column 'a':

     ALTER TABLE t2 ADD INDEX (d), ADD UNIQUE (a);

To remove column 'c':

     ALTER TABLE t2 DROP COLUMN c;

To add a new 'AUTO_INCREMENT' integer column named 'c':

     ALTER TABLE t2 ADD c INT UNSIGNED NOT NULL AUTO_INCREMENT,
       ADD PRIMARY KEY (c);

We indexed 'c' (as a 'PRIMARY KEY') because 'AUTO_INCREMENT' columns
must be indexed, and we declare 'c' as 'NOT NULL' because primary key
columns cannot be 'NULL'.

For 'NDB' tables, it is also possible to change
the storage type used for a table or column.  For example, consider an
'NDB' table created as shown here:

     mysql> CREATE TABLE t1 (c1 INT) TABLESPACE ts_1 ENGINE NDB;
     Query OK, 0 rows affected (1.27 sec)

To convert this table to disk-based storage, you can use the following
'ALTER TABLE' statement:

     mysql> ALTER TABLE t1 TABLESPACE ts_1 STORAGE DISK;
     Query OK, 0 rows affected (2.99 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> SHOW CREATE TABLE t1\G
     *************************** 1. row ***************************
            Table: t1
     Create Table: CREATE TABLE `t1` (
       `c1` int(11) DEFAULT NULL
     ) /*!50100 TABLESPACE ts_1 STORAGE DISK */
     ENGINE=ndbcluster DEFAULT CHARSET=latin1
     1 row in set (0.01 sec)

It is not necessary that the tablespace was referenced when the table
was originally created; however, the tablespace must be referenced by
the 'ALTER TABLE'.:

     mysql> CREATE TABLE t2 (c1 INT) ts_1 ENGINE NDB;
     Query OK, 0 rows affected (1.00 sec)

     mysql> ALTER TABLE t2 STORAGE DISK;
     ERROR 1005 (HY000): Can't create table 'c.#sql-1750_3' (errno: 140)
     mysql> ALTER TABLE t2 TABLESPACE ts_1 STORAGE DISK;
     Query OK, 0 rows affected (3.42 sec)
     Records: 0  Duplicates: 0  Warnings: 0
     mysql> SHOW CREATE TABLE t2\G
     *************************** 1. row ***************************
            Table: t1
     Create Table: CREATE TABLE `t2` (
       `c1` int(11) DEFAULT NULL
     ) /*!50100 TABLESPACE ts_1 STORAGE DISK */
     ENGINE=ndbcluster DEFAULT CHARSET=latin1
     1 row in set (0.01 sec)

To change the storage type of an individual column, you can use 'ALTER
TABLE ... MODIFY [COLUMN]'.  For example, suppose you create an NDB
Cluster Disk Data table with two columns, using this 'CREATE TABLE'
statement:

     mysql> CREATE TABLE t3 (c1 INT, c2 INT)
         ->     TABLESPACE ts_1 STORAGE DISK ENGINE NDB;
     Query OK, 0 rows affected (1.34 sec)

To change column 'c2' from disk-based to in-memory storage, include a
STORAGE MEMORY clause in the column definition used by the ALTER TABLE
statement, as shown here:

     mysql> ALTER TABLE t3 MODIFY c2 INT STORAGE MEMORY;
     Query OK, 0 rows affected (3.14 sec)
     Records: 0  Duplicates: 0  Warnings: 0

You can make an in-memory column into a disk-based column by using
'STORAGE DISK' in a similar fashion.

Column 'c1' uses disk-based storage, since this is the default for the
table (determined by the table-level 'STORAGE DISK' clause in the
'CREATE TABLE' statement).  However, column 'c2' uses
in-memory storage, as can be seen here in the output of SHOW
'CREATE TABLE'.:

     mysql> SHOW CREATE TABLE t3\G
     *************************** 1. row ***************************
            Table: t3
     Create Table: CREATE TABLE `t3` (
       `c1` int(11) DEFAULT NULL,
       `c2` int(11) /*!50120 STORAGE MEMORY */ DEFAULT NULL
     ) /*!50100 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1
     1 row in set (0.02 sec)

When you add an 'AUTO_INCREMENT' column, column values are filled in
with sequence numbers automatically.  For 'MyISAM' tables, you can set
the first sequence number by executing 'SET INSERT_ID=VALUE' before
'ALTER TABLE' or by using the 'AUTO_INCREMENT=VALUE'
table option.

With 'MyISAM' tables, if you do not change the 'AUTO_INCREMENT' column,
the sequence number is not affected.  If you drop an 'AUTO_INCREMENT'
column and then add another 'AUTO_INCREMENT' column, the numbers are
resequenced beginning with 1.

When replication is used, adding an 'AUTO_INCREMENT' column to a table
might not produce the same ordering of the rows on the slave and the
master.  This occurs because the order in which the rows are numbered
depends on the specific storage engine used for the table and the order
in which the rows were inserted.  If it is important to have the same
order on the master and slave, the rows must be ordered before assigning
an 'AUTO_INCREMENT' number.  Assuming that you want to add an
'AUTO_INCREMENT' column to the table 't1', the following statements
produce a new table 't2' identical to 't1' but with an 'AUTO_INCREMENT'
column:

     CREATE TABLE t2 (id INT AUTO_INCREMENT PRIMARY KEY)
     SELECT * FROM t1 ORDER BY col1, col2;

This assumes that the table 't1' has columns 'col1' and 'col2'.

This set of statements will also produce a new table 't2' identical to
't1', with the addition of an 'AUTO_INCREMENT' column:

     CREATE TABLE t2 LIKE t1;
     ALTER TABLE t2 ADD id INT AUTO_INCREMENT PRIMARY KEY;
     INSERT INTO t2 SELECT * FROM t1 ORDER BY col1, col2;

*Important*:

To guarantee the same ordering on both master and slave, _all_ columns
of 't1' must be referenced in the 'ORDER BY' clause.

Regardless of the method used to create and populate the copy having the
'AUTO_INCREMENT' column, the final step is to drop the original table
and then rename the copy:

     DROP TABLE t1;
     ALTER TABLE t2 RENAME t1;

13.1.9 ALTER TABLESPACE Syntax
------------------------------

     ALTER TABLESPACE TABLESPACE_NAME
         {ADD|DROP} DATAFILE 'FILE_NAME'
         [INITIAL_SIZE [=] SIZE]
         [WAIT]
         ENGINE [=] ENGINE_NAME

This statement can be used either to add a new data file, or to drop a
data file from a tablespace.

The 'ADD DATAFILE' variant enables you to specify an initial size using
an 'INITIAL_SIZE' clause, where SIZE is measured in bytes; the default
value is 134217728 (128 MB). You may optionally follow SIZE with a
one-letter abbreviation for an order of magnitude, similar to those used
in 'my.cnf'.  Generally, this is one of the letters 'M' (megabytes) or
'G' (gigabytes).

*Note*:

All NDB Cluster Disk Data objects share the same namespace.  This means
that _each Disk Data object_ must be uniquely named (and not merely each
Disk Data object of a given type).  For example, you cannot have a
tablespace and an data file with the same name, or an undo log file and
a tablespace with the same name.

On 32-bit systems, the maximum supported value for 'INITIAL_SIZE' is
4294967296 (4 GB). (Bug #29186)

'INITIAL_SIZE' is rounded, explicitly, as for 'CREATE TABLESPACE'.

Once a data file has been created, its size cannot be changed; however,
you can add more data files to the tablespace using additional 'ALTER
TABLESPACE ... ADD DATAFILE' statements.

Using 'DROP DATAFILE' with 'ALTER TABLESPACE'.
drops the data file 'FILE_NAME' from the tablespace.  You cannot drop a
data file from a tablespace which is in use by any table; in other
words, the data file must be empty (no extents used).  See
mysql-cluster-disk-data-objects.  In addition, any data file to be
dropped must previously have been added to the tablespace with
'CREATE TABLESPACE' or 'ALTER TABLESPACE'.

Both 'ALTER TABLESPACE ... ADD DATAFILE' and 'ALTER TABLESPACE ... DROP
DATAFILE' require an 'ENGINE' clause which specifies the storage engine
used by the tablespace.  Currently, the only accepted values for
ENGINE_NAME are 'NDB' and 'NDBCLUSTER'.

'WAIT' is parsed but otherwise ignored, and so has no effect in MySQL
5.7.  It is intended for future expansion.

When 'ALTER TABLESPACE ... ADD DATAFILE' is used with 'ENGINE = NDB', a
data file is created on each Cluster data node.  You can verify that the
data files were created and obtain information about them by querying
the 'INFORMATION_SCHEMA.FILES' table.  For example,
the following query shows all data files belonging to the tablespace
named 'newts':

     mysql> SELECT LOGFILE_GROUP_NAME, FILE_NAME, EXTRA
         -> FROM INFORMATION_SCHEMA.FILES
         -> WHERE TABLESPACE_NAME = 'newts' AND FILE_TYPE = 'DATAFILE';
     +--------------------+--------------+----------------+
     | LOGFILE_GROUP_NAME | FILE_NAME    | EXTRA          |
     +--------------------+--------------+----------------+
     | lg_3               | newdata.dat  | CLUSTER_NODE=3 |
     | lg_3               | newdata.dat  | CLUSTER_NODE=4 |
     | lg_3               | newdata2.dat | CLUSTER_NODE=3 |
     | lg_3               | newdata2.dat | CLUSTER_NODE=4 |
     +--------------------+--------------+----------------+
     2 rows in set (0.03 sec)

See files-table.

'ALTER TABLESPACE' is useful only with Disk
Data storage for NDB Cluster.  See mysql-cluster-disk-data.

13.1.10 ALTER VIEW Syntax
-------------------------

     ALTER
         [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]
         [DEFINER = { USER | CURRENT_USER }]
         [SQL SECURITY { DEFINER | INVOKER }]
         VIEW VIEW_NAME [(COLUMN_LIST)]
         AS SELECT_STATEMENT
         [WITH [CASCADED | LOCAL] CHECK OPTION]

This statement changes the definition of a view, which must exist.  The
syntax is similar to that for 'CREATE VIEW' see
create-view).  This statement requires the 'CREATE VIEW' and
'DROP' privileges for the view, and some privilege for each column
referred to in the 'SELECT' statement.  'ALTER VIEW'
is permitted only to the definer or users with the
'SUPER' privilege.

13.1.11 CREATE DATABASE Syntax
------------------------------

     CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] DB_NAME
         [CREATE_SPECIFICATION] ...

     CREATE_SPECIFICATION:
         [DEFAULT] CHARACTER SET [=] CHARSET_NAME
       | [DEFAULT] COLLATE [=] COLLATION_NAME

'CREATE DATABASE' creates a database with the
given name.  To use this statement, you need the 'CREATE' privilege for
the database.  'CREATE SCHEMA' is a synonym for
'CREATE DATABASE'.

An error occurs if the database exists and you did not specify 'IF NOT
EXISTS'.

'CREATE DATABASE' is not permitted within a
session that has an active 'LOCK TABLES' statement.

CREATE_SPECIFICATION options specify database characteristics.  Database
characteristics are stored in the 'db.opt' file in the database
directory.  The 'CHARACTER SET' clause specifies the default database
character set.  The 'COLLATE' clause specifies the default database
collation.  See charset, discusses character set and collation
names.

A database in MySQL is implemented as a directory containing files that
correspond to tables in the database.  Because there are no tables in a
database when it is initially created, the 'CREATE DATABASE'
statement creates only a directory under the MySQL data
directory and the 'db.opt' file.  Rules for permissible database names
are given in identifiers.  If a database name contains special
characters, the name for the database directory contains encoded
versions of those characters as described in identifier-mapping.

If you manually create a directory under the data directory (for
example, with 'mkdir'), the server considers it a database directory and
it shows up in the output of 'SHOW DATABASES'.

You can also use the 'mysqladmin' program to create
databases.  See mysqladmin.

13.1.12 CREATE EVENT Syntax
---------------------------

     CREATE
         [DEFINER = { USER | CURRENT_USER }]
         EVENT
         [IF NOT EXISTS]
         EVENT_NAME
         ON SCHEDULE SCHEDULE
         [ON COMPLETION [NOT] PRESERVE]
         [ENABLE | DISABLE | DISABLE ON SLAVE]
         [COMMENT 'STRING']
         DO EVENT_BODY;

     SCHEDULE:
         AT TIMESTAMP [+ INTERVAL INTERVAL] ...
       | EVERY INTERVAL
         [STARTS TIMESTAMP [+ INTERVAL INTERVAL] ...]
         [ENDS TIMESTAMP [+ INTERVAL INTERVAL] ...]

     INTERVAL:
         QUANTITY {YEAR | QUARTER | MONTH | DAY | HOUR | MINUTE |
                   WEEK | SECOND | YEAR_MONTH | DAY_HOUR | DAY_MINUTE |
                   DAY_SECOND | HOUR_MINUTE | HOUR_SECOND | MINUTE_SECOND}

This statement creates and schedules a new event.  The event will not
run unless the Event Scheduler is enabled.  For information about
checking Event Scheduler status and enabling it if necessary, see
events-configuration.

'CREATE EVENT' requires the 'EVENT' privilege for
the schema in which the event is to be created.  It might also require
the 'SUPER' privilege, depending on the 'DEFINER' value, as described
later in this section.

The minimum requirements for a valid 'CREATE EVENT'.
statement are as follows:

   * The keywords 'CREATE EVENT' plus an event
     name, which uniquely identifies the event in a database schema.

   * An 'ON SCHEDULE' clause, which determines when and how often the
     event executes.

   * A 'DO' clause, which contains the SQL statement to be
     executed by an event.

This is an example of a minimal 'CREATE EVENT'.
statement:

     CREATE EVENT myevent
         ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR
         DO
           UPDATE myschema.mytable SET mycol = mycol + 1;

The previous statement creates an event named 'myevent'.  This event
executes once--one hour following its creation--by running an SQL
statement that increments the value of the 'myschema.mytable' table's
'mycol' column by 1.

The EVENT_NAME must be a valid MySQL identifier with a maximum length of
64 characters.  Event names are not case-sensitive, so you cannot have
two events named 'myevent' and 'MyEvent' in the same schema.  In
general, the rules governing event names are the same as those for names
of stored routines.  See identifiers.

An event is associated with a schema.  If no schema is indicated as part
of EVENT_NAME, the default (current) schema is assumed.  To create an
event in a specific schema, qualify the event name with a schema using
'SCHEMA_NAME.EVENT_NAME' syntax.

The 'DEFINER' clause specifies the MySQL account to be used when
checking access privileges at event execution time.  If a USER value is
given, it should be a MySQL account specified as
''USER_NAME'@'HOST_NAME'', 'CURRENT_USER', or 'CURRENT_USER()'.  The
default 'DEFINER' value is the user who executes the 'CREATE EVENT'
statement.  This is the same as specifying
'DEFINER = CURRENT_USER' explicitly.

If you specify the 'DEFINER' clause, these rules determine the valid
'DEFINER' user values:

   * If you do not have the 'SUPER' privilege, the only permitted USER
     value is your own account, either specified literally or by using
     'CURRENT_USER'.  You cannot set the definer to some other account.

   * If you have the 'SUPER' privilege, you can specify any
     syntactically valid account name.  If the account does not exist, a
     warning is generated.

   * Although it is possible to create an event with a nonexistent
     'DEFINER' account, an error occurs at event execution time if the
     account does not exist.

For more information about event security, see
stored-programs-security.

Within an event, the 'CURRENT_USER()' function returns the account used
to check privileges at event execution time, which is the 'DEFINER'
user.  For information about user auditing within events, see
account-activity-auditing.

'IF NOT EXISTS' has the same meaning for 'CREATE EVENT'
as for 'CREATE TABLE'.: If an event
named EVENT_NAME already exists in the same schema, no action is taken,
and no error results.  (However, a warning is generated in such cases.)

The 'ON SCHEDULE' clause determines when, how often, and for how long
the EVENT_BODY defined for the event repeats.  This clause takes one of
two forms:

   * 'AT TIMESTAMP' is used for a one-time event.  It specifies that the
     event executes one time only at the date and time given by
     TIMESTAMP, which must include both the date and time, or must be an
     expression that resolves to a datetime value.  You may use a value
     of either the 'DATETIME' or 'TIMESTAMP'
     type for this purpose.  If the date is in the past, a
     warning occurs, as shown here:

          mysql> SELECT NOW();
          +---------------------+
          | NOW()               |
          +---------------------+
          | 2006-02-10 23:59:01 |
          +---------------------+
          1 row in set (0.04 sec)

          mysql> CREATE EVENT e_totals
              ->     ON SCHEDULE AT '2006-02-10 23:59:00'
              ->     DO INSERT INTO test.totals VALUES (NOW());
          Query OK, 0 rows affected, 1 warning (0.00 sec)

          mysql> SHOW WARNINGS\G
          *************************** 1. row ***************************
            Level: Note
             Code: 1588
          Message: Event execution time is in the past and ON COMPLETION NOT
                   PRESERVE is set. The event was dropped immediately after
                   creation.

     'CREATE EVENT' statements which are themselves
     invalid--for whatever reason--fail with an error.

     You may use 'CURRENT_TIMESTAMP' to specify the current date and
     time.  In such a case, the event acts as soon as it is created.

     To create an event which occurs at some point in the future
     relative to the current date and time--such as that expressed by
     the phrase 'three weeks from now'--you can use the optional clause
     '+ INTERVAL INTERVAL'.  The INTERVAL portion consists of two parts,
     a quantity and a unit of time, and follows the same syntax rules
     that govern intervals used in the 'DATE_ADD()' function (see
     date-and-time-functions.  The units keywords are also the same,
     except that you cannot use any units involving microseconds when
     defining an event.  With some interval types, complex time units
     may be used.  For example, 'two minutes and ten seconds' can be
     expressed as '+ INTERVAL '2:10' MINUTE_SECOND'.

     You can also combine intervals.  For example, 'AT CURRENT_TIMESTAMP
     + INTERVAL 3 WEEK + INTERVAL 2 DAY' is equivalent to 'three weeks
     and two days from now'.  Each portion of such a clause must begin
     with '+ INTERVAL'.

   * To repeat actions at a regular interval, use an 'EVERY' clause.
     The 'EVERY' keyword is followed by an INTERVAL as described in the
     previous discussion of the 'AT' keyword.  ('+ INTERVAL' is _not_
     used with 'EVERY'.)  For example, 'EVERY 6 WEEK' means 'every six
     weeks'.

     Although '+ INTERVAL' clauses are not permitted in an 'EVERY'
     clause, you can use the same complex time units permitted in a '+
     INTERVAL'.

     An 'EVERY' clause may contain an optional 'STARTS' clause.
     'STARTS' is followed by a TIMESTAMP value that indicates when the
     action should begin repeating, and may also use '+ INTERVAL
     INTERVAL' to specify an amount of time 'from now'.  For example,
     'EVERY 3 MONTH STARTS CURRENT_TIMESTAMP + INTERVAL 1 WEEK' means
     'every three months, beginning one week from now'.  Similarly, you
     can express 'every two weeks, beginning six hours and fifteen
     minutes from now' as 'EVERY 2 WEEK STARTS CURRENT_TIMESTAMP +
     INTERVAL '6:15' HOUR_MINUTE'.  Not specifying 'STARTS' is the same
     as using 'STARTS CURRENT_TIMESTAMP'--that is, the action specified
     for the event begins repeating immediately upon creation of the
     event.

     An 'EVERY' clause may contain an optional 'ENDS' clause.  The
     'ENDS' keyword is followed by a TIMESTAMP value that tells MySQL
     when the event should stop repeating.  You may also use '+ INTERVAL
     INTERVAL' with 'ENDS'; for instance, 'EVERY 12 HOUR STARTS
     CURRENT_TIMESTAMP + INTERVAL 30 MINUTE ENDS CURRENT_TIMESTAMP +
     INTERVAL 4 WEEK' is equivalent to 'every twelve hours, beginning
     thirty minutes from now, and ending four weeks from now'.  Not
     using 'ENDS' means that the event continues executing indefinitely.

     'ENDS' supports the same syntax for complex time units as 'STARTS'
     does.

     You may use 'STARTS', 'ENDS', both, or neither in an 'EVERY'
     clause.

     If a repeating event does not terminate within its scheduling
     interval, the result may be multiple instances of the event
     executing simultaneously.  If this is undesirable, you should
     institute a mechanism to prevent simultaneous instances.  For
     example, you could use the 'GET_LOCK()' function, or row or table
     locking.

The 'ON SCHEDULE' clause may use expressions involving built-in MySQL
functions and user variables to obtain any of the TIMESTAMP or INTERVAL
values which it contains.  You may not use stored functions or
user-defined functions in such expressions, nor may you use any table
references; however, you may use 'SELECT FROM DUAL'.  This is true for
both 'CREATE EVENT' and 'ALTER EVENT'
statements.  References to stored functions, user-defined
functions, and tables in such cases are specifically not permitted, and
fail with an error (see Bug #22830).

Times in the 'ON SCHEDULE' clause are interpreted using the current
session 'time_zone' value.  This becomes the event time zone; that is,
the time zone that is used for event scheduling and is in effect within
the event as it executes.  These times are converted to UTC and stored
along with the event time zone in the 'mysql.event' table.  This enables
event execution to proceed as defined regardless of any subsequent
changes to the server time zone or daylight saving time effects.  For
additional information about representation of event times, see
events-metadata.  See also show-events, and
events-table.

Normally, once an event has expired, it is immediately dropped.  You can
override this behavior by specifying 'ON COMPLETION PRESERVE'.  Using
'ON COMPLETION NOT PRESERVE' merely makes the default nonpersistent
behavior explicit.

You can create an event but prevent it from being active using the
'DISABLE' keyword.  Alternatively, you can use 'ENABLE' to make explicit
the default status, which is active.  This is most useful in conjunction
with 'ALTER EVENT'. (see alter-event).

A third value may also appear in place of 'ENABLE' or 'DISABLE';
'DISABLE ON SLAVE' is set for the status of an event on a replication
slave to indicate that the event was created on the master and
replicated to the slave, but is not executed on the slave.  See
replication-features-invoked.

You may supply a comment for an event using a 'COMMENT' clause.  COMMENT
may be any string of up to 64 characters that you wish to use for
describing the event.  The comment text, being a string literal, must be
surrounded by quotation marks.

The 'DO' clause specifies an action carried by the event, and
consists of an SQL statement.  Nearly any valid MySQL statement that can
be used in a stored routine can also be used as the action statement for
a scheduled event.  (See stored-program-restrictions.)  For
example, the following event 'e_hourly' deletes all rows from the
'sessions' table once per hour, where this table is part of the
'site_activity' schema:

     CREATE EVENT e_hourly
         ON SCHEDULE
           EVERY 1 HOUR
         COMMENT 'Clears out sessions table each hour.'
         DO
           DELETE FROM site_activity.sessions;

MySQL stores the 'sql_mode' system variable setting in effect when an
event is created or altered, and always executes the event with this
setting in force, _regardless of the current server SQL mode when the
event begins executing_.

A 'CREATE EVENT' statement that contains an
'ALTER EVENT' statement in its 'DO' clause
appears to succeed; however, when the server attempts to execute the
resulting scheduled event, the execution fails with an error.

*Note*:

Statements such as 'SELECT' or 'SHOW' that
merely return a result set have no effect when used in an event; the
output from these is not sent to the MySQL Monitor, nor is it stored
anywhere.  However, you can use statements such as 'SELECT ... INTO'
and 'INSERT INTO ... SELECT' that
store a result.  (See the next example in this section for an instance
of the latter.)

The schema to which an event belongs is the default schema for table
references in the 'DO' clause.  Any references to tables in
other schemas must be qualified with the proper schema name.

As with stored routines, you can use compound-statement syntax in the
'DO' clause by using the 'BEGIN' and 'END' keywords, as shown
here:

     delimiter |

     CREATE EVENT e_daily
         ON SCHEDULE
           EVERY 1 DAY
         COMMENT 'Saves total number of sessions then clears the table each day'
         DO
           BEGIN
             INSERT INTO site_activity.totals (time, total)
               SELECT CURRENT_TIMESTAMP, COUNT(*)
                 FROM site_activity.sessions;
             DELETE FROM site_activity.sessions;
           END |

     delimiter ;

This example uses the 'delimiter' command to change the statement
delimiter.  See stored-programs-defining.

More complex compound statements, such as those used in stored routines,
are possible in an event.  This example uses local variables, an error
handler, and a flow control construct:

     delimiter |

     CREATE EVENT e
         ON SCHEDULE
           EVERY 5 SECOND
         DO
           BEGIN
             DECLARE v INTEGER;
             DECLARE CONTINUE HANDLER FOR SQLEXCEPTION BEGIN END;

             SET v = 0;

             WHILE v < 5 DO
               INSERT INTO t1 VALUES (0);
               UPDATE t2 SET s1 = s1 + 1;
               SET v = v + 1;
             END WHILE;
         END |

     delimiter ;

There is no way to pass parameters directly to or from events; however,
it is possible to invoke a stored routine with parameters within an
event:

     CREATE EVENT e_call_myproc
         ON SCHEDULE
           AT CURRENT_TIMESTAMP + INTERVAL 1 DAY
         DO CALL myproc(5, 27);

If an event's definer has the 'SUPER' privilege, the event can read and
write global variables.  As granting this privilege entails a potential
for abuse, extreme care must be taken in doing so.

Generally, any statements that are valid in stored routines may be used
for action statements executed by events.  For more information about
statements permissible within stored routines, see
stored-routines-syntax.  You can create an event as part of a stored
routine, but an event cannot be created by another event.

13.1.13 CREATE FUNCTION Syntax
------------------------------

The 'CREATE FUNCTION' statement is used to
create stored functions and user-defined functions (UDFs):

   * For information about creating stored functions, see
     create-procedure.

   * For information about creating user-defined functions, see
     create-function-udf.

13.1.14 CREATE INDEX Syntax
---------------------------

     CREATE [UNIQUE|FULLTEXT|SPATIAL] INDEX INDEX_NAME
         [INDEX_TYPE]
         ON TBL_NAME (INDEX_COL_NAME,...)
         [INDEX_OPTION]
         [ALGORITHM_OPTION | LOCK_OPTION] ...

     INDEX_COL_NAME:
         COL_NAME [(LENGTH)] [ASC | DESC]

     INDEX_OPTION:
         KEY_BLOCK_SIZE [=] VALUE
       | INDEX_TYPE
       | WITH PARSER PARSER_NAME
       | COMMENT 'STRING'

     INDEX_TYPE:
         USING {BTREE | HASH}

     ALGORITHM_OPTION:
         ALGORITHM [=] {DEFAULT|INPLACE|COPY}

     LOCK_OPTION:
         LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}

'CREATE INDEX' is mapped to an 'ALTER TABLE'
statement to create indexes.  See alter-table.
'CREATE INDEX' cannot be used to create a 'PRIMARY
KEY'; use 'ALTER TABLE' instead.  For more
information about indexes, see mysql-indexes.

Normally, you create all indexes on a table at the time the table itself
is created with 'CREATE TABLE'.  See
create-table.  This guideline is especially important for
'InnoDB' tables, where the primary key
determines the physical layout of rows in the data file.  'CREATE INDEX'
enables you to add indexes to existing tables.

A column list of the form '(col1, col2, ...)' creates a multiple-column
index.  Index key values are formed by concatenating the values of the
given columns.

For string columns, indexes can be created that use only the leading
part of column values, using 'COL_NAME(LENGTH)' syntax to specify an
index prefix length:

   * Prefixes can be specified for 'CHAR', 'VARCHAR',
     see 'BINARY', and 'VARBINARY'
     column indexes.

   * Prefixes _must_ be specified for 'BLOB' and
     'TEXT' column indexes.

   * Prefix limits are measured in bytes, whereas the prefix length in
     'CREATE TABLE', 'ALTER TABLE',
     and 'CREATE INDEX' statements is
     interpreted as number of characters for nonbinary string types
     (see 'CHAR', 'VARCHAR', 'TEXT')
     and number of bytes for binary string types (see 'BINARY',
     see 'VARBINARY',
     'BLOB').  Take this into account when specifying a prefix
     length for a nonbinary string column that uses a multibyte
     character set.

   * For spatial columns, prefix values cannot be given, as described
     later in this section.

The statement shown here creates an index using the first 10 characters
of the 'name' column (assuming that 'name' has a nonbinary string type):

     CREATE INDEX part_of_name ON customer (name(10));

If names in the column usually differ in the first 10 characters, this
index should not be much slower than an index created from the entire
'name' column.  Also, using column prefixes for indexes can make the
index file much smaller, which could save a lot of disk space and might
also speed up 'INSERT' operations.

Prefix support and lengths of prefixes (where supported) are storage
engine dependent.  For example, a prefix can be up to 767 bytes long for
'InnoDB' tables or 3072 bytes if the
'innodb_large_prefix' option is enabled.  For 'MyISAM'
tables, the prefix limit is 1000 bytes.  The
'NDB' storage engine does not support prefixes
(see mysql-cluster-limitations-unsupported).

NDB Cluster formerly supported online 'CREATE INDEX' operations using an
alternative syntax that is no longer supported.  NDB Cluster now
supports online operations using the same 'ALGORITHM=INPLACE' syntax
used with the standard MySQL Server.  See
alter-table-online-operations, for more information.

A 'UNIQUE' index creates a constraint such that all values in the index
must be distinct.  An error occurs if you try to add a new row with a
key value that matches an existing row.  For all engines, a 'UNIQUE'
index permits multiple 'NULL' values for columns that can contain
'NULL'.  If you specify a prefix value for a column in a 'UNIQUE' index,
the column values must be unique within the prefix.

If a 'UNIQUE' index consists of only one column that has an integer
type, you can also refer to the column as '_rowid' in 'SELECT'
statements.

As of MySQL 5.7.17, if a specified index prefix exceeds the maximum
column data type size, see 'CREATE INDEX' handles the
index as follows:

   * For a nonunique index, either an error occurs (if strict SQL mode
     is enabled), or the index length is reduced to lie within the
     maximum column data type size and a warning is produced (if strict
     mode is not enabled).

   * For a unique index, an error occurs regardless of SQL mode because
     reducing the index length might enable insertion of nonunique
     entries that do not meet the specified uniqueness requirement.

'FULLTEXT' indexes are supported only for 'InnoDB'
and 'MyISAM' tables
and can include only 'CHAR', 'VARCHAR', and
'TEXT' columns.  Indexing always happens over the entire
column; column prefix indexing is not supported and any prefix length is
ignored if specified.  See fulltext-search, for details of
operation.

The 'MyISAM', 'InnoDB',
see 'NDB', and 'ARCHIVE'
storage engines support spatial columns such as
(see 'POINT' and 'GEOMETRY'.
(see spatial-types, describes the spatial
data types.)  However, support for spatial column indexing varies among
engines.  Spatial and nonspatial indexes are available according to the
following rules.

Spatial indexes (created using 'SPATIAL INDEX') have these
characteristics:

   * Available only for 'MyISAM' and
     'InnoDB' tables.  Specifying 'SPATIAL
     INDEX' for other storage engines results in an error.

   * Indexed columns must be 'NOT NULL'.

   * Column prefix lengths are prohibited.  The full width of each
     column is indexed.

Characteristics of nonspatial indexes (created with 'INDEX', 'UNIQUE',
or 'PRIMARY KEY'):

   * Permitted for any storage engine that supports spatial columns
     except 'ARCHIVE'.

   * Columns can be 'NULL' unless the index is a primary key.

   * For each spatial column in a non-'SPATIAL' index except
     'POINT' columns, a column prefix length
     must be specified.  (This is the same requirement as for indexed
     'BLOB' columns.)  The prefix length is given in bytes.

   * The index type for a non-'SPATIAL' index depends on the storage
     engine.  Currently, B-tree is used.

   * You can add an index on a column that can have 'NULL' values only
     for 'InnoDB', 'MyISAM',
     and 'MEMORY'.
     tables.

   * You can add an index on a 'BLOB' or 'TEXT'
     column only for using the 'InnoDB'
     and 'MyISAM'.
     tables.

   * When the 'innodb_stats_persistent' setting is enabled, run the
     'ANALYZE TABLE' statement for an
     'InnoDB' table after creating an index on
     that table.

'InnoDB' supports secondary indexes on
virtual columns.  For more information, see
create-table-secondary-indexes.

An INDEX_COL_NAME specification can end with 'ASC' or 'DESC'.  These
keywords are permitted for future extensions for specifying ascending or
descending index value storage.  Currently, they are parsed but ignored;
index values are always stored in ascending order.

Following the index column list, index options can be given.  An
INDEX_OPTION value can be any of the following:

   * 'KEY_BLOCK_SIZE [=] VALUE'

     For 'MyISAM' tables, 'KEY_BLOCK_SIZE'
     optionally specifies the size in bytes to use for index key blocks.
     The value is treated as a hint; a different size could be used if
     necessary.  A 'KEY_BLOCK_SIZE' value specified for an individual
     index definition overrides a table-level 'KEY_BLOCK_SIZE' value.

     'KEY_BLOCK_SIZE' is not supported at the index level for
     'InnoDB' tables.  See create-table.

   * INDEX_TYPE

     Some storage engines permit you to specify an index type when
     creating an index.  For example:

          CREATE TABLE lookup (id INT) ENGINE = MEMORY;
          CREATE INDEX id_index ON lookup (id) USING BTREE;

     create-index-storage-engine-index-types shows the
     permissible index type values supported by different storage
     engines.  Where multiple index types are listed, the first one is
     the default when no index type specifier is given.  Storage engines
     not listed in the table do not support an INDEX_TYPE clause in
     index definitions.

     *Index Types Per Storage Engine*

     Storage        Permissible Index Types
     Engine

     See 'BTREE' 'InnoDB'.

     See 'BTREE' 'MyISAM'.

     See 'HASH', 'BTREE' 'MEMORY'.
     /'HEAP'

     See 'NDB', 'BTREE' (see note in text)
     mysql-cluster.

     The INDEX_TYPE clause cannot be used for 'FULLTEXT INDEX' or
     'SPATIAL INDEX' specifications.  Full-text index implementation is
     storage engine dependent.  Spatial indexes are implemented as
     R-tree indexes.

     'BTREE' indexes are implemented by the 'NDB'.
     storage engine as T-tree indexes.

     *Note*:

     For indexes on 'NDB' table columns, the
     'USING' option can be specified only for a unique index or primary
     key.  'USING HASH' prevents the creation of an ordered index;
     otherwise, creating a unique index or primary key on an
     'NDB' table automatically results in the creation
     of both an ordered index and a hash index, each of which indexes
     the same set of columns.

     For unique indexes that include one or more 'NULL' columns of an
     'NDB' table, the hash index can be used only
     to look up literal values, which means that 'IS [NOT] NULL'
     conditions require a full scan of the table.  One workaround is to
     make sure that a unique index using one or more 'NULL' columns on
     such a table is always created in such a way that it includes the
     ordered index; that is, avoid employing 'USING HASH' when creating
     the index.

     If you specify an index type that is not valid for a given storage
     engine, but another index type is available that the engine can use
     without affecting query results, the engine uses the available
     type.  The parser recognizes 'RTREE' as a type name, but currently
     this cannot be specified for any storage engine.

     *Note*:

     Use of the INDEX_TYPE option before the 'ON TBL_NAME' clause is
     deprecated; support for use of the option in this position will be
     removed in a future MySQL release.  If an INDEX_TYPE option is
     given in both the earlier and later positions, the final option
     applies.

     'TYPE TYPE_NAME' is recognized as a synonym for 'USING TYPE_NAME'.
     However, 'USING' is the preferred form.

     The following tables show index characteristics for the storage
     engines that support the INDEX_TYPE option.

     *InnoDB Storage Engine Index Characteristics*

     Index       Index   Stores      Permits        IS NULL Scan   IS NOT NULL
     Class       Type    NULL        Multiple       Type           Scan Type
                         VALUES      NULL Values

     Primary     'BTREE' No          No             N/A            N/A
     key

     Unique      'BTREE' Yes         Yes            Index          Index

     Key         'BTREE' Yes         Yes            Index          Index

     'FULLTEXT'  N/A     Yes         Yes            Table          Table

     'SPATIAL'   N/A     No          No             N/A            N/A

     *MyISAM Storage Engine Index Characteristics*

     Index       Index   Stores      Permits        IS NULL Scan   IS NOT NULL
     Class       Type    NULL        Multiple       Type           Scan Type
                         VALUES      NULL Values

     Primary     'BTREE' No          No             N/A            N/A
     key

     Unique      'BTREE' Yes         Yes            Index          Index

     Key         'BTREE' Yes         Yes            Index          Index

     'FULLTEXT'  N/A     Yes         Yes            Table          Table

     'SPATIAL'   N/A     No          No             N/A            N/A

     *MEMORY Storage Engine Index Characteristics*

     Index       Index   Stores      Permits        IS NULL Scan   IS NOT NULL
     Class       Type    NULL        Multiple       Type           Scan Type
                         VALUES      NULL Values

     Primary     'BTREE' No          No             N/A            N/A
     key

     Unique      'BTREE' Yes         Yes            Index          Index

     Key         'BTREE' Yes         Yes            Index          Index

     Primary     'HASH'  No          No             N/A            N/A
     key

     Unique      'HASH'  Yes         Yes            Index          Index

     Key         'HASH'  Yes         Yes            Index          Index

     *NDB Storage Engine Index Characteristics*

     Index       Index   Stores      Permits        IS NULL Scan   IS NOT NULL
     Class       Type    NULL        Multiple       Type           Scan Type
                         VALUES      NULL Values

     Primary     'BTREE' No          No             Index          Index
     key

     Unique      'BTREE' Yes         Yes            Index          Index

     Key         'BTREE' Yes         Yes            Index          Index

     Primary     'HASH'  No          No             Table (see     Table (see
     key                                            note 1)        note 1)

     Unique      'HASH'  Yes         Yes            Table (see     Table (see
                                                    note 1)        note 1)

     Key         'HASH'  Yes         Yes            Table (see     Table (see
                                                    note 1)        note 1)

     Table note:

     1.  If 'USING HASH' is specified that prevents creation of an
     implicit ordered index.

   * 'WITH PARSER PARSER_NAME'

     This option can be used only with 'FULLTEXT' indexes.  It
     associates a parser plugin with the index if full-text indexing and
     searching operations need special handling.  'InnoDB'
     and 'MyISAM'.
     support full-text parser plugins.  See
     full-text-plugin-type and writing-full-text-plugins for
     more information.

   * 'COMMENT 'STRING''

     Index definitions can include an optional comment of up to 1024
     characters.

     The 'MERGE_THRESHOLD' for index
     pages can be configured for individual indexes using the
     INDEX_OPTION 'COMMENT' clause of the 'CREATE INDEX'
     statement.  For example:

          CREATE TABLE t1 (id INT);
          CREATE INDEX id_index ON t1 (id) COMMENT 'MERGE_THRESHOLD=40';

     If the page-full percentage for an index page falls below the
     'MERGE_THRESHOLD' value when a row is deleted or when a row is
     shortened by an update operation, see 'InnoDB'
     attempts to merge the index page with a
     neighboring index page.  The default 'MERGE_THRESHOLD' value is 50,
     which is the previously hardcoded value.

     'MERGE_THRESHOLD' can also be defined at the index level and table
     level using 'CREATE TABLE' and 'ALTER TABLE'
     statements.  For more information, see
     index-page-merge-threshold.

'ALGORITHM' and 'LOCK' clauses may be given to influence the table
copying method and level of concurrency for reading and writing the
table while its indexes are being modified.  They have the same meaning
as for the 'ALTER TABLE' statement.  For more
information, see alter-table

13.1.15 CREATE LOGFILE GROUP Syntax
-----------------------------------

     CREATE LOGFILE GROUP LOGFILE_GROUP
         ADD UNDOFILE 'UNDO_FILE'
         [INITIAL_SIZE [=] INITIAL_SIZE]
         [UNDO_BUFFER_SIZE [=] UNDO_BUFFER_SIZE]
         [REDO_BUFFER_SIZE [=] REDO_BUFFER_SIZE]
         [NODEGROUP [=] NODEGROUP_ID]
         [WAIT]
         [COMMENT [=] 'STRING']
         ENGINE [=] ENGINE_NAME

This statement creates a new log file group named LOGFILE_GROUP having a
single 'UNDO' file named 'UNDO_FILE'.  A 'CREATE LOGFILE GROUP'
statement has one and only one 'ADD UNDOFILE'
clause.  For rules covering the naming of log file groups, see
identifiers.

*Note*:

All NDB Cluster Disk Data objects share the same namespace.  This means
that _each Disk Data object_ must be uniquely named (and not merely each
Disk Data object of a given type).  For example, you cannot have a
tablespace and a log file group with the same name, or a tablespace and
a data file with the same name.

There can be only one log file group per NDB Cluster instance at any
given time.

The optional 'INITIAL_SIZE' parameter sets the 'UNDO' file's initial
size; if not specified, it defaults to '128M' (128 megabytes).  The
optional 'UNDO_BUFFER_SIZE' parameter sets the size used by the 'UNDO'
buffer for the log file group; The default value for 'UNDO_BUFFER_SIZE'
is '8M' (eight megabytes); this value cannot exceed the amount of system
memory available.  Both of these parameters are specified in bytes.  You
may optionally follow either or both of these with a one-letter
abbreviation for an order of magnitude, similar to those used in
'my.cnf'.  Generally, this is one of the letters 'M' (for megabytes) or
'G' (for gigabytes).

Memory used for 'UNDO_BUFFER_SIZE' comes from the global pool whose size
is determined by the value of the 'SharedGlobalMemory' data node
configuration parameter.  This includes any default value implied for
this option by the setting of the 'InitialLogFileGroup' data node
configuration parameter.

The maximum permitted for 'UNDO_BUFFER_SIZE' is 629145600 (600 MB).

On 32-bit systems, the maximum supported value for 'INITIAL_SIZE' is
4294967296 (4 GB). (Bug #29186)

The minimum allowed value for 'INITIAL_SIZE' is 1048576 (1 MB).

The 'ENGINE' option determines the storage engine to be used by this log
file group, with ENGINE_NAME being the name of the storage engine.  In
MySQL 5.7, this must be 'NDB'. (or
'NDBCLUSTER').  If 'ENGINE' is not set, MySQL tries to
use the engine specified by the 'default_storage_engine' server system
variable (formerly 'storage_engine').  In any case, if the engine is not
specified as 'NDB' or 'NDBCLUSTER',
the 'CREATE LOGFILE GROUP' statement appears to succeed
but actually fails to create the log file group, as shown here:

     mysql> CREATE LOGFILE GROUP lg1
         ->     ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M;
     Query OK, 0 rows affected, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS;
     +-------+------+------------------------------------------------------------------------------------------------+
     | Level | Code | Message                                                                                        |
     +-------+------+------------------------------------------------------------------------------------------------+
     | Error | 1478 | Table storage engine 'InnoDB' does not support the create option 'TABLESPACE or LOGFILE GROUP' |
     +-------+------+------------------------------------------------------------------------------------------------+
     1 row in set (0.00 sec)

     mysql> DROP LOGFILE GROUP lg1 ENGINE = NDB;
     ERROR 1529 (HY000): Failed to drop LOGFILE GROUP

     mysql> CREATE LOGFILE GROUP lg1
         ->     ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M
         ->     ENGINE = NDB;
     Query OK, 0 rows affected (2.97 sec)

The fact that the 'CREATE LOGFILE GROUP' statement does not actually
return an error when a non-'NDB' storage engine is named, but rather
appears to succeed, is a known issue which we hope to address in a
future release of NDB Cluster.

REDO_BUFFER_SIZE, 'NODEGROUP', 'WAIT', and 'COMMENT' are parsed but
ignored, and so have no effect in MySQL 5.7.  These options are intended
for future expansion.

When used with 'ENGINE [=] NDB', a log file group and associated 'UNDO'
log file are created on each Cluster data node.  You can verify that the
'UNDO' files were created and obtain information about them by querying
the 'INFORMATION_SCHEMA.FILES' table.  For example:

     mysql> SELECT LOGFILE_GROUP_NAME, LOGFILE_GROUP_NUMBER, EXTRA
         -> FROM INFORMATION_SCHEMA.FILES
         -> WHERE FILE_NAME = 'undo_10.dat';
     +--------------------+----------------------+----------------+
     | LOGFILE_GROUP_NAME | LOGFILE_GROUP_NUMBER | EXTRA          |
     +--------------------+----------------------+----------------+
     | lg_3               |                   11 | CLUSTER_NODE=3 |
     | lg_3               |                   11 | CLUSTER_NODE=4 |
     +--------------------+----------------------+----------------+
     2 rows in set (0.06 sec)

'CREATE LOGFILE GROUP' is useful only with
Disk Data storage for NDB Cluster.  See mysql-cluster-disk-data.

13.1.16 CREATE PROCEDURE and CREATE FUNCTION Syntax
---------------------------------------------------

     CREATE
         [DEFINER = { USER | CURRENT_USER }]
         PROCEDURE SP_NAME ([PROC_PARAMETER[,...]])
         [CHARACTERISTIC ...] ROUTINE_BODY

     CREATE
         [DEFINER = { USER | CURRENT_USER }]
         FUNCTION SP_NAME ([FUNC_PARAMETER[,...]])
         RETURNS TYPE
         [CHARACTERISTIC ...] ROUTINE_BODY

     PROC_PARAMETER:
         [ IN | OUT | INOUT ] PARAM_NAME TYPE

     FUNC_PARAMETER:
         PARAM_NAME TYPE

     TYPE:
         ANY VALID MYSQL DATA TYPE

     CHARACTERISTIC:
         COMMENT 'STRING'
       | LANGUAGE SQL
       | [NOT] DETERMINISTIC
       | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }
       | SQL SECURITY { DEFINER | INVOKER }

     ROUTINE_BODY:
         VALID SQL ROUTINE STATEMENT

These statements create stored routines.  By default, a routine is
associated with the default database.  To associate the routine
explicitly with a given database, specify the name as DB_NAME.SP_NAME
when you create it.

The 'CREATE FUNCTION' statement is also used in
MySQL to support UDFs (user-defined functions).  See
adding-functions.  A UDF can be regarded as an external stored
function.  Stored functions share their namespace with UDFs.  See
function-resolution, for the rules describing how the server
interprets references to different kinds of functions.

To invoke a stored procedure, use the 'CALL' statement (see
call).  To invoke a stored function, refer to it in an
expression.  The function returns a value during expression evaluation.

'CREATE PROCEDURE' and 'CREATE FUNCTION'
require the 'CREATE ROUTINE' privilege.  They might
also require the 'SUPER' privilege, depending on the 'DEFINER' value, as
described later in this section.  If binary logging is enabled, see
'CREATE FUNCTION' might require the 'SUPER' privilege,
as described in stored-programs-logging.

By default, MySQL automatically grants the 'ALTER ROUTINE' and 'EXECUTE'
privileges to the routine creator.  This behavior can be changed by
disabling the 'automatic_sp_privileges' system variable.  See
stored-routines-privileges.

The 'DEFINER' and 'SQL SECURITY' clauses specify the security context to
be used when checking access privileges at routine execution time, as
described later in this section.

If the routine name is the same as the name of a built-in SQL function,
a syntax error occurs unless you use a space between the name and the
following parenthesis when defining the routine or invoking it later.
For this reason, avoid using the names of existing SQL functions for
your own stored routines.

The 'IGNORE_SPACE' SQL mode applies to built-in functions, not to stored
routines.  It is always permissible to have spaces after a stored
routine name, regardless of whether 'IGNORE_SPACE' is enabled.

The parameter list enclosed within parentheses must always be present.
If there are no parameters, an empty parameter list of '()' should be
used.  Parameter names are not case sensitive.

Each parameter is an 'IN' parameter by default.  To specify otherwise
for a parameter, use the keyword 'OUT' or 'INOUT' before the parameter
name.

*Note*:

Specifying a parameter as 'IN', 'OUT', or 'INOUT' is valid only for a
'PROCEDURE'.  For a 'FUNCTION', parameters are always regarded as 'IN'
parameters.

An 'IN' parameter passes a value into a procedure.  The procedure might
modify the value, but the modification is not visible to the caller when
the procedure returns.  An 'OUT' parameter passes a value from the
procedure back to the caller.  Its initial value is 'NULL' within the
procedure, and its value is visible to the caller when the procedure
returns.  An 'INOUT' parameter is initialized by the caller, can be
modified by the procedure, and any change made by the procedure is
visible to the caller when the procedure returns.

For each 'OUT' or 'INOUT' parameter, pass a user-defined variable in the
'CALL' statement that invokes the procedure so that you can
obtain its value when the procedure returns.  If you are calling the
procedure from within another stored procedure or function, you can also
pass a routine parameter or local routine variable as an 'IN' or 'INOUT'
parameter.

Routine parameters cannot be referenced in statements prepared within
the routine; see stored-program-restrictions.

The following example shows a simple stored procedure that uses an 'OUT'
parameter:

     mysql> delimiter //

     mysql> CREATE PROCEDURE simpleproc (OUT param1 INT)
         -> BEGIN
         ->   SELECT COUNT(*) INTO param1 FROM t;
         -> END//
     Query OK, 0 rows affected (0.00 sec)

     mysql> delimiter ;

     mysql> CALL simpleproc(@a);
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @a;
     +------+
     | @a   |
     +------+
     | 3    |
     +------+
     1 row in set (0.00 sec)

The example uses the 'mysql' client 'delimiter' command to
change the statement delimiter from ';' to '//' while the procedure is
being defined.  This enables the ';' delimiter used in the procedure
body to be passed through to the server rather than being interpreted by
'mysql' itself.  See stored-programs-defining.

The 'RETURNS' clause may be specified only for a 'FUNCTION', for which
it is mandatory.  It indicates the return type of the function, and the
function body must contain a 'RETURN VALUE' statement.  If the
'RETURN' statement returns a value of a different type, the
value is coerced to the proper type.  For example, if a function
specifies an 'ENUM' or 'SET' value in the
'RETURNS' clause, but the 'RETURN' statement returns an
integer, the value returned from the function is the string for the
corresponding 'ENUM' member of set of 'SET'.
members.

The following example function takes a parameter, performs an operation
using an SQL function, and returns the result.  In this case, it is
unnecessary to use 'delimiter' because the function definition contains
no internal ';' statement delimiters:

     mysql> CREATE FUNCTION hello (s CHAR(20))
     mysql> RETURNS CHAR(50) DETERMINISTIC
         -> RETURN CONCAT('Hello, ',s,'!');
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT hello('world');
     +----------------+
     | hello('world') |
     +----------------+
     | Hello, world!  |
     +----------------+
     1 row in set (0.00 sec)

Parameter types and function return types can be declared to use any
valid data type.  The 'COLLATE' attribute can be used if preceded by the
'CHARACTER SET' attribute.

The ROUTINE_BODY consists of a valid SQL routine statement.  This can be
a simple statement such as 'SELECT' or 'INSERT',
or a compound statement written using 'BEGIN' and 'END'.
Compound statements can contain declarations, loops, and other control
structure statements.  The syntax for these statements is described in
sql-syntax-compound-statements.

MySQL permits routines to contain DDL statements, such as 'CREATE' and
'DROP'.  MySQL also permits stored procedures (but not stored functions)
to contain SQL transaction statements such as 'COMMIT'.
Stored functions may not contain statements that perform explicit or
implicit commit or rollback.  Support for these statements is not
required by the SQL standard, which states that each DBMS vendor may
decide whether to permit them.

Statements that return a result set can be used within a stored
procedure but not within a stored function.  This prohibition includes
'SELECT' statements that do not have an 'INTO VAR_LIST'
clause and other statements such as 'SHOW', 'EXPLAIN',
and 'CHECK TABLE'.  For statements that can
be determined at function definition time to return a result set, a 'Not
allowed to return a result set from a function' error occurs
('ER_SP_NO_RETSET').  For statements that can be determined only at
runtime to return a result set, a 'PROCEDURE %s can't return a result
set in the given context' error occurs ('ER_SP_BADSELECT').

'USE' statements within stored routines are not permitted.
When a routine is invoked, an implicit 'USE DB_NAME' is performed (and
undone when the routine terminates).  The causes the routine to have the
given default database while it executes.  References to objects in
databases other than the routine default database should be qualified
with the appropriate database name.

For additional information about statements that are not permitted in
stored routines, see stored-program-restrictions.

For information about invoking stored procedures from within programs
written in a language that has a MySQL interface, see call.

MySQL stores the 'sql_mode' system variable setting in effect when a
routine is created or altered, and always executes the routine with this
setting in force, _regardless of the current server SQL mode when the
routine begins executing_.

The switch from the SQL mode of the invoker to that of the routine
occurs after evaluation of arguments and assignment of the resulting
values to routine parameters.  If you define a routine in strict SQL
mode but invoke it in nonstrict mode, assignment of arguments to routine
parameters does not take place in strict mode.  If you require that
expressions passed to a routine be assigned in strict SQL mode, you
should invoke the routine with strict mode in effect.

The 'COMMENT' characteristic is a MySQL extension, and may be used to
describe the stored routine.  This information is displayed by the
'SHOW CREATE PROCEDURE' and 'SHOW CREATE FUNCTION'
statements.

The 'LANGUAGE' characteristic indicates the language in which the
routine is written.  The server ignores this characteristic; only SQL
routines are supported.

A routine is considered 'deterministic' if it always produces the same
result for the same input parameters, and 'not deterministic' otherwise.
If neither 'DETERMINISTIC' nor 'NOT DETERMINISTIC' is given in the
routine definition, the default is 'NOT DETERMINISTIC'.  To declare that
a function is deterministic, you must specify 'DETERMINISTIC'
explicitly.

Assessment of the nature of a routine is based on the 'honesty' of the
creator: MySQL does not check that a routine declared 'DETERMINISTIC' is
free of statements that produce nondeterministic results.  However,
misdeclaring a routine might affect results or affect performance.
Declaring a nondeterministic routine as 'DETERMINISTIC' might lead to
unexpected results by causing the optimizer to make incorrect execution
plan choices.  Declaring a deterministic routine as 'NONDETERMINISTIC'
might diminish performance by causing available optimizations not to be
used.

If binary logging is enabled, the 'DETERMINISTIC' characteristic affects
which routine definitions MySQL accepts.  See
stored-programs-logging.

A routine that contains the 'NOW()' function (or its synonyms) or
'RAND()' is nondeterministic, but it might still be replication-safe.
For 'NOW()', the binary log includes the timestamp and replicates
correctly.  'RAND()' also replicates correctly as long as it is called
only a single time during the execution of a routine.  (You can consider
the routine execution timestamp and random number seed as implicit
inputs that are identical on the master and slave.)

Several characteristics provide information about the nature of data use
by the routine.  In MySQL, these characteristics are advisory only.  The
server does not use them to constrain what kinds of statements a routine
will be permitted to execute.

   * 'CONTAINS SQL' indicates that the routine does not contain
     statements that read or write data.  This is the default if none of
     these characteristics is given explicitly.  Examples of such
     statements are 'SET @x = 1' or 'DO RELEASE_LOCK('abc')', which
     execute but neither read nor write data.

   * 'NO SQL' indicates that the routine contains no SQL statements.

   * 'READS SQL DATA' indicates that the routine contains statements
     that read data (for example, see 'SELECT'), but not
     statements that write data.

   * 'MODIFIES SQL DATA' indicates that the routine contains statements
     that may write data (for example, see 'INSERT' or
     'DELETE').

The 'SQL SECURITY' characteristic can be 'DEFINER' or 'INVOKER' to
specify the security context; that is, whether the routine executes
using the privileges of the account named in the routine 'DEFINER'
clause or the user who invokes it.  This account must have permission to
access the database with which the routine is associated.  The default
value is 'DEFINER'.  The user who invokes the routine must have the
'EXECUTE' privilege for it, as must the 'DEFINER' account if the routine
executes in definer security context.

The 'DEFINER' clause specifies the MySQL account to be used when
checking access privileges at routine execution time for routines that
have the 'SQL SECURITY DEFINER' characteristic.

If a USER value is given for the 'DEFINER' clause, it should be a MySQL
account specified as ''USER_NAME'@'HOST_NAME'', 'CURRENT_USER', or
'CURRENT_USER()'.  The default 'DEFINER' value is the user who executes
the 'CREATE PROCEDURE' or 'CREATE FUNCTION'
statement.  This is the same as specifying
'DEFINER = CURRENT_USER' explicitly.

If you specify the 'DEFINER' clause, these rules determine the valid
'DEFINER' user values:

   * If you do not have the 'SUPER' privilege, the only permitted USER
     value is your own account, either specified literally or by using
     'CURRENT_USER'.  You cannot set the definer to some other account.

   * If you have the 'SUPER' privilege, you can specify any
     syntactically valid account name.  If the account does not exist, a
     warning is generated.

   * Although it is possible to create a routine with a nonexistent
     'DEFINER' account, an error occurs at routine execution time if the
     'SQL SECURITY' value is 'DEFINER' but the definer account does not
     exist.

For more information about stored routine security, see
stored-programs-security.

Within a stored routine that is defined with the 'SQL SECURITY DEFINER'
characteristic, 'CURRENT_USER' returns the routine's 'DEFINER' value.
For information about user auditing within stored routines, see
account-activity-auditing.

Consider the following procedure, which displays a count of the number
of MySQL accounts listed in the 'mysql.user' table:

     CREATE DEFINER = 'admin'@'localhost' PROCEDURE account_count()
     BEGIN
       SELECT 'Number of accounts:', COUNT(*) FROM mysql.user;
     END;

The procedure is assigned a 'DEFINER' account of ''admin'@'localhost''
no matter which user defines it.  It executes with the privileges of
that account no matter which user invokes it (because the default
security characteristic is 'DEFINER').  The procedure succeeds or fails
depending on whether invoker has the 'EXECUTE' privilege for it and
''admin'@'localhost'' has the 'SELECT' privilege for the 'mysql.user'
table.

Now suppose that the procedure is defined with the 'SQL SECURITY
INVOKER' characteristic:

     CREATE DEFINER = 'admin'@'localhost' PROCEDURE account_count()
     SQL SECURITY INVOKER
     BEGIN
       SELECT 'Number of accounts:', COUNT(*) FROM mysql.user;
     END;

The procedure still has a 'DEFINER' of ''admin'@'localhost'', but in
this case, it executes with the privileges of the invoking user.  Thus,
the procedure succeeds or fails depending on whether the invoker has the
'EXECUTE' privilege for it and the 'SELECT' privilege for the
'mysql.user' table.

The server handles the data type of a routine parameter, local routine
variable created with 'DECLARE', or function return value
as follows:

   * Assignments are checked for data type mismatches and overflow.
     Conversion and overflow problems result in warnings, or errors in
     strict SQL mode.

   * Only scalar values can be assigned.  For example, a statement such
     as 'SET x = (SELECT 1, 2)' is invalid.

   * For character data types, if there is a 'CHARACTER SET' attribute
     in the declaration, the specified character set and its default
     collation is used.  If the 'COLLATE' attribute is also present,
     that collation is used rather than the default collation.

     If 'CHARACTER SET' and 'COLLATE' attributes are not present, the
     database character set and collation in effect at routine creation
     time are used.  To avoid having the server use the database
     character set and collation, provide explicit 'CHARACTER SET' and
     'COLLATE' attributes for character data parameters.

     If you change the database default character set or collation,
     stored routines that use the database defaults must be dropped and
     recreated so that they use the new defaults.

     The database character set and collation are given by the value of
     the 'character_set_database' and 'collation_database' system
     variables.  For more information, see charset-database.

13.1.17 CREATE SERVER Syntax
----------------------------

     CREATE SERVER SERVER_NAME
         FOREIGN DATA WRAPPER WRAPPER_NAME
         OPTIONS (OPTION [, OPTION] ...)

     OPTION:
       { HOST CHARACTER-LITERAL
       | DATABASE CHARACTER-LITERAL
       | USER CHARACTER-LITERAL
       | PASSWORD CHARACTER-LITERAL
       | SOCKET CHARACTER-LITERAL
       | OWNER CHARACTER-LITERAL
       | PORT NUMERIC-LITERAL }

This statement creates the definition of a server for use with the
'FEDERATED' storage engine.  The 'CREATE SERVER' statement creates a new
row in the 'servers' table in the 'mysql' database.  This statement
requires the 'SUPER' privilege.

The 'SERVER_NAME' should be a unique reference to the server.  Server
definitions are global within the scope of the server, it is not
possible to qualify the server definition to a specific database.
'SERVER_NAME' has a maximum length of 64 characters (names longer than
64 characters are silently truncated), and is case insensitive.  You may
specify the name as a quoted string.

The 'WRAPPER_NAME' should be 'mysql', and may be quoted with single
quotation marks.  Other values for 'WRAPPER_NAME' are not currently
supported.

For each 'OPTION' you must specify either a character literal or numeric
literal.  Character literals are UTF-8, support a maximum length of 64
characters and default to a blank (empty) string.  String literals are
silently truncated to 64 characters.  Numeric literals must be a number
between 0 and 9999, default value is 0.

*Note*:

The 'OWNER' option is currently not applied, and has no effect on the
ownership or operation of the server connection that is created.

The 'CREATE SERVER' statement creates an entry in the 'mysql.servers'
table that can later be used with the 'CREATE TABLE'
statement when creating a 'FEDERATED' table.  The options
that you specify will be used to populate the columns in the
'mysql.servers' table.  The table columns are 'Server_name', 'Host',
'Db', 'Username', 'Password', 'Port' and 'Socket'.

For example:

     CREATE SERVER s
     FOREIGN DATA WRAPPER mysql
     OPTIONS (USER 'Remote', HOST '198.51.100.106', DATABASE 'test');

Be sure to specify all options necessary to establish a connection to
the server.  The user name, host name, and database name are mandatory.
Other options might be required as well, such as password.

The data stored in the table can be used when creating a connection to a
'FEDERATED' table:

     CREATE TABLE t (s1 INT) ENGINE=FEDERATED CONNECTION='s';

For more information, see federated-storage-engine.

'CREATE SERVER' causes an implicit commit.  See implicit-commit.

'CREATE SERVER' is not written to the binary log, regardless of the
logging format that is in use.

13.1.18 CREATE TABLE Syntax
---------------------------

     CREATE [TEMPORARY] TABLE [IF NOT EXISTS] TBL_NAME
         (CREATE_DEFINITION,...)
         [TABLE_OPTIONS]
         [PARTITION_OPTIONS]

     CREATE [TEMPORARY] TABLE [IF NOT EXISTS] TBL_NAME
         [(CREATE_DEFINITION,...)]
         [TABLE_OPTIONS]
         [PARTITION_OPTIONS]
         [IGNORE | REPLACE]
         [AS] QUERY_EXPRESSION

     CREATE [TEMPORARY] TABLE [IF NOT EXISTS] TBL_NAME
         { LIKE OLD_TBL_NAME | (LIKE OLD_TBL_NAME) }

     CREATE_DEFINITION:
         COL_NAME COLUMN_DEFINITION
       | [CONSTRAINT [SYMBOL]] PRIMARY KEY [INDEX_TYPE] (INDEX_COL_NAME,...)
           [INDEX_OPTION] ...
       | {INDEX|KEY} [INDEX_NAME] [INDEX_TYPE] (INDEX_COL_NAME,...)
           [INDEX_OPTION] ...
       | [CONSTRAINT [SYMBOL]] UNIQUE [INDEX|KEY]
           [INDEX_NAME] [INDEX_TYPE] (INDEX_COL_NAME,...)
           [INDEX_OPTION] ...
       | {FULLTEXT|SPATIAL} [INDEX|KEY] [INDEX_NAME] (INDEX_COL_NAME,...)
           [INDEX_OPTION] ...
       | [CONSTRAINT [SYMBOL]] FOREIGN KEY
           [INDEX_NAME] (INDEX_COL_NAME,...) REFERENCE_DEFINITION
       | CHECK (EXPR)

     COLUMN_DEFINITION:
         DATA_TYPE [NOT NULL | NULL] [DEFAULT DEFAULT_VALUE]
           [AUTO_INCREMENT] [UNIQUE [KEY]] [[PRIMARY] KEY]
           [COMMENT 'STRING']
           [COLUMN_FORMAT {FIXED|DYNAMIC|DEFAULT}]
           [STORAGE {DISK|MEMORY|DEFAULT}]
           [REFERENCE_DEFINITION]
       | DATA_TYPE [GENERATED ALWAYS] AS (EXPRESSION)
           [VIRTUAL | STORED] [NOT NULL | NULL]
           [UNIQUE [KEY]] [[PRIMARY] KEY]
           [COMMENT 'STRING']

     DATA_TYPE:
         BIT[(LENGTH)]
       | TINYINT[(LENGTH)] [UNSIGNED] [ZEROFILL]
       | SMALLINT[(LENGTH)] [UNSIGNED] [ZEROFILL]
       | MEDIUMINT[(LENGTH)] [UNSIGNED] [ZEROFILL]
       | INT[(LENGTH)] [UNSIGNED] [ZEROFILL]
       | INTEGER[(LENGTH)] [UNSIGNED] [ZEROFILL]
       | BIGINT[(LENGTH)] [UNSIGNED] [ZEROFILL]
       | REAL[(LENGTH,DECIMALS)] [UNSIGNED] [ZEROFILL]
       | DOUBLE[(LENGTH,DECIMALS)] [UNSIGNED] [ZEROFILL]
       | FLOAT[(LENGTH,DECIMALS)] [UNSIGNED] [ZEROFILL]
       | DECIMAL[(LENGTH[,DECIMALS])] [UNSIGNED] [ZEROFILL]
       | NUMERIC[(LENGTH[,DECIMALS])] [UNSIGNED] [ZEROFILL]
       | DATE
       | TIME[(FSP)]
       | TIMESTAMP[(FSP)]
       | DATETIME[(FSP)]
       | YEAR
       | CHAR[(LENGTH)]
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | VARCHAR(LENGTH)
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | BINARY[(LENGTH)]
       | VARBINARY(LENGTH)
       | TINYBLOB
       | BLOB[(LENGTH)]
       | MEDIUMBLOB
       | LONGBLOB
       | TINYTEXT
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | TEXT[(LENGTH)]
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | MEDIUMTEXT
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | LONGTEXT
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | ENUM(VALUE1,VALUE2,VALUE3,...)
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | SET(VALUE1,VALUE2,VALUE3,...)
           [CHARACTER SET CHARSET_NAME] [COLLATE COLLATION_NAME]
       | JSON
       | SPATIAL_TYPE

     INDEX_COL_NAME:
         COL_NAME [(LENGTH)] [ASC | DESC]

     INDEX_TYPE:
         USING {BTREE | HASH}

     INDEX_OPTION:
         KEY_BLOCK_SIZE [=] VALUE
       | INDEX_TYPE
       | WITH PARSER PARSER_NAME
       | COMMENT 'STRING'

     REFERENCE_DEFINITION:
         REFERENCES TBL_NAME (INDEX_COL_NAME,...)
           [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE]
           [ON DELETE REFERENCE_OPTION]
           [ON UPDATE REFERENCE_OPTION]

     REFERENCE_OPTION:
         RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT

     TABLE_OPTIONS:
         TABLE_OPTION [[,] TABLE_OPTION] ...

     TABLE_OPTION:
         AUTO_INCREMENT [=] VALUE
       | AVG_ROW_LENGTH [=] VALUE
       | [DEFAULT] CHARACTER SET [=] CHARSET_NAME
       | CHECKSUM [=] {0 | 1}
       | [DEFAULT] COLLATE [=] COLLATION_NAME
       | COMMENT [=] 'STRING'
       | COMPRESSION [=] {'ZLIB'|'LZ4'|'NONE'}
       | CONNECTION [=] 'CONNECT_STRING'
       | {DATA|INDEX} DIRECTORY [=] 'ABSOLUTE PATH TO DIRECTORY'
       | DELAY_KEY_WRITE [=] {0 | 1}
       | ENCRYPTION [=] {'Y' | 'N'}
       | ENGINE [=] ENGINE_NAME
       | INSERT_METHOD [=] { NO | FIRST | LAST }
       | KEY_BLOCK_SIZE [=] VALUE
       | MAX_ROWS [=] VALUE
       | MIN_ROWS [=] VALUE
       | PACK_KEYS [=] {0 | 1 | DEFAULT}
       | PASSWORD [=] 'STRING'
       | ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT}
       | STATS_AUTO_RECALC [=] {DEFAULT|0|1}
       | STATS_PERSISTENT [=] {DEFAULT|0|1}
       | STATS_SAMPLE_PAGES [=] VALUE
       | TABLESPACE TABLESPACE_NAME [STORAGE {DISK|MEMORY|DEFAULT}]
       | UNION [=] (TBL_NAME[,TBL_NAME]...)

     PARTITION_OPTIONS:
         PARTITION BY
             { [LINEAR] HASH(EXPR)
             | [LINEAR] KEY [ALGORITHM={1|2}] (COLUMN_LIST)
             | RANGE{(EXPR) | COLUMNS(COLUMN_LIST)}
             | LIST{(EXPR) | COLUMNS(COLUMN_LIST)} }
         [PARTITIONS NUM]
         [SUBPARTITION BY
             { [LINEAR] HASH(EXPR)
             | [LINEAR] KEY [ALGORITHM={1|2}] (COLUMN_LIST) }
           [SUBPARTITIONS NUM]
         ]
         [(PARTITION_DEFINITION [, PARTITION_DEFINITION] ...)]

     PARTITION_DEFINITION:
         PARTITION PARTITION_NAME
             [VALUES
                 {LESS THAN {(EXPR | VALUE_LIST) | MAXVALUE}
                 |
                 IN (VALUE_LIST)}]
             [[STORAGE] ENGINE [=] ENGINE_NAME]
             [COMMENT [=] 'STRING' ]
             [DATA DIRECTORY [=] 'DATA_DIR']
             [INDEX DIRECTORY [=] 'INDEX_DIR']
             [MAX_ROWS [=] MAX_NUMBER_OF_ROWS]
             [MIN_ROWS [=] MIN_NUMBER_OF_ROWS]
             [TABLESPACE [=] tablespace_name]
             [(SUBPARTITION_DEFINITION [, SUBPARTITION_DEFINITION] ...)]

     SUBPARTITION_DEFINITION:
         SUBPARTITION LOGICAL_NAME
             [[STORAGE] ENGINE [=] ENGINE_NAME]
             [COMMENT [=] 'STRING' ]
             [DATA DIRECTORY [=] 'DATA_DIR']
             [INDEX DIRECTORY [=] 'INDEX_DIR']
             [MAX_ROWS [=] MAX_NUMBER_OF_ROWS]
             [MIN_ROWS [=] MIN_NUMBER_OF_ROWS]
             [TABLESPACE [=] tablespace_name]

     QUERY_EXPRESSION:
         SELECT ...   (SOME VALID SELECT OR UNION STATEMENT)

'CREATE TABLE' creates a table with the given name.
You must have the 'CREATE' privilege for the table.

By default, tables are created in the default database, using the
'InnoDB' storage engine.  An error occurs if the
table exists, if there is no default database, or if the database does
not exist.

For information about the physical representation of a table, see
create-table-files.

The original 'CREATE TABLE' statement, including
all specifications and table options are stored by MySQL when the table
is created.  For more information, see
create-table-statement-retention.

There are several aspects to the 'CREATE TABLE'.
statement, described under the following topics in this section:

   * create-table-name

   * create-table-temporary-tables

   * create-table-clone-copy

   * create-table-types-attributes

   * create-table-indexes-keys

   * create-table-options

   * create-table-partitioning

*Table Name*

   * 'TBL_NAME'

     The table name can be specified as DB_NAME.TBL_NAME to create the
     table in a specific database.  This works regardless of whether
     there is a default database, assuming that the database exists.  If
     you use quoted identifiers, quote the database and table names
     separately.  For example, write '`mydb`.`mytbl`', not
     '`mydb.mytbl`'.

     Rules for permissible table names are given in identifiers.

   * 'IF NOT EXISTS'

     Prevents an error from occurring if the table exists.  However,
     there is no verification that the existing table has a structure
     identical to that indicated by the 'CREATE TABLE'
     statement.

*Temporary Tables*

You can use the 'TEMPORARY' keyword when creating a table.  A
'TEMPORARY' table is visible only within the current session, and is
dropped automatically when the session is closed.  For more information,
see create-temporary-table.

*Cloning or Copying a Table*

   * 'LIKE'

     Use 'CREATE TABLE ... LIKE' to create an empty table based on the
     definition of another table, including any column attributes and
     indexes defined in the original table:

          CREATE TABLE NEW_TBL LIKE ORIG_TBL;

     For more information, see create-table-like.

   * '[AS] QUERY_EXPRESSION'

     To create one table from another, add a 'SELECT'.
     statement at the end of the 'CREATE TABLE'.
     statement:

          CREATE TABLE NEW_TBL AS SELECT * FROM ORIG_TBL;

     For more information, see create-table-select.

   * 'IGNORE|REPLACE'

     The 'IGNORE' and 'REPLACE' options indicate how to handle rows that
     duplicate unique key values when copying a table using a
     'SELECT' statement.

     For more information, see create-table-select.

*Column Data Types and Attributes*

There is a hard limit of 4096 columns per table, but the effective
maximum may be less for a given table and depends on the factors
discussed in column-count-limit.

   * 'DATA_TYPE'

     DATA_TYPE represents the data type in a column definition.
     SPATIAL_TYPE represents a spatial data type.  The data type syntax
     shown is representative only.  For a full description of the syntax
     available for specifying column data types, as well as information
     about the properties of each type, see data-types, and
     spatial-types.  Beginning with MySQL 5.7.8, a 'JSON'
     data type is also supported for table columns; see
     json, for more information.

        * Some attributes do not apply to all data types.
          'AUTO_INCREMENT' applies only to integer and floating-point
          types.  'DEFAULT' does not apply to the 'BLOB',
          'TEXT', 'GEOMETRY', and 'JSON' types.

        * Character data types (see 'CHAR', 'VARCHAR',
          see 'TEXT') can include 'CHARACTER SET' and
          'COLLATE' attributes to specify the character set and
          collation for the column.  For details, see charset.
          'CHARSET' is a synonym for 'CHARACTER SET'.  Example:

               CREATE TABLE t (c CHAR(20) CHARACTER SET utf8 COLLATE utf8_bin);

          MySQL 5.7 interprets length specifications in character column
          definitions in characters.  Lengths for 'BINARY'
          and 'VARBINARY' are
          in bytes.

        * For 'CHAR', 'VARCHAR', 'BINARY',
          and 'VARBINARY'.
          columns, indexes can be created that use only the leading part
          of column values, using 'COL_NAME(LENGTH)' syntax to specify
          an index prefix length.  'BLOB' and 'TEXT'
          columns also can be indexed, but a prefix length _must_
          be given.  Prefix lengths are given in characters for
          nonbinary string types and in bytes for binary string types.
          That is, index entries consist of the first LENGTH characters
          of each column value for 'CHAR', 'VARCHAR',
          and 'TEXT' columns, and the first LENGTH
          bytes of each column value for 'BINARY',
          see 'VARBINARY', and
          'BLOB' columns.  Indexing only a prefix of column
          values like this can make the index file much smaller.  For
          additional information about index prefixes, see
          create-index.

          Only the 'InnoDB' and 'MyISAM' storage engines support
          indexing on 'BLOB' and 'TEXT'.
          columns.  For example:

               CREATE TABLE test (blob_col BLOB, INDEX(blob_col(10)));

          As of MySQL 5.7.17, if a specified index prefix exceeds the
          maximum column data type size, see 'CREATE TABLE'
          handles the index as follows:

             * For a nonunique index, either an error occurs (if strict
               SQL mode is enabled), or the index length is reduced to
               lie within the maximum column data type size and a
               warning is produced (if strict mode is not enabled).

             * For a unique index, an error occurs regardless of SQL
               mode because reducing the index length might enable
               insertion of nonunique entries that do not meet the
               specified uniqueness requirement.

        * 'JSON' columns cannot be indexed.  You can work
          around this restriction by creating an index on a generated
          column that extracts a scalar value from the 'JSON' column.
          See json-column-indirect-index, for a detailed
          example.

   * 'NOT NULL | NULL'

     If neither 'NULL' nor 'NOT NULL' is specified, the column is
     treated as though 'NULL' had been specified.

     In MySQL 5.7, only the 'InnoDB', 'MyISAM', and 'MEMORY' storage
     engines support indexes on columns that can have 'NULL' values.  In
     other cases, you must declare indexed columns as 'NOT NULL' or an
     error results.

   * 'DEFAULT'

     Specifies a default value for a column.  With one exception, the
     default value must be a constant; it cannot be a function or an
     expression.  This means, for example, that you cannot set the
     default for a date column to be the value of a function such as
     'NOW()' or 'CURRENT_DATE'.  The exception is that you can specify
     'CURRENT_TIMESTAMP' as the default for a 'TIMESTAMP'
     or 'DATETIME' column.  See
     timestamp-initialization.

     If a column definition includes no explicit 'DEFAULT' value, MySQL
     determines the default value as described in
     data-type-defaults.

     See 'BLOB', 'TEXT', and 'JSON'.
     columns cannot be assigned a default value.

     If the 'NO_ZERO_DATE' or 'NO_ZERO_IN_DATE' SQL mode is enabled and
     a date-valued default is not correct according to that mode, see
     'CREATE TABLE' produces a warning if strict SQL mode
     is not enabled and an error if strict mode is enabled.  For
     example, with 'NO_ZERO_IN_DATE' enabled, 'c1 DATE DEFAULT
     '2010-00-00'' produces a warning.

   * 'AUTO_INCREMENT'

     An integer or floating-point column can have the additional
     attribute 'AUTO_INCREMENT'.  When you insert a value of 'NULL'
     (recommended) or '0' into an indexed 'AUTO_INCREMENT' column, the
     column is set to the next sequence value.  Typically this is
     'VALUE+1', where VALUE is the largest value for the column
     currently in the table.  'AUTO_INCREMENT' sequences begin with '1'.

     To retrieve an 'AUTO_INCREMENT' value after inserting a row, use
     the 'LAST_INSERT_ID()' SQL function or the
     'mysql_insert_id()'. C API function.  See
     information-functions, and mysql-insert-id.

     If the 'NO_AUTO_VALUE_ON_ZERO' SQL mode is enabled, you can store
     '0' in 'AUTO_INCREMENT' columns as '0' without generating a new
     sequence value.  See sql-mode.

     There can be only one 'AUTO_INCREMENT' column per table, it must be
     indexed, and it cannot have a 'DEFAULT' value.  An 'AUTO_INCREMENT'
     column works properly only if it contains only positive values.
     Inserting a negative number is regarded as inserting a very large
     positive number.  This is done to avoid precision problems when
     numbers 'wrap' over from positive to negative and also to ensure
     that you do not accidentally get an 'AUTO_INCREMENT' column that
     contains '0'.

     For 'MyISAM' tables, you can specify an 'AUTO_INCREMENT' secondary
     column in a multiple-column key.  See
     example-auto-increment.

     To make MySQL compatible with some ODBC applications, you can find
     the 'AUTO_INCREMENT' value for the last inserted row with the
     following query:

          SELECT * FROM TBL_NAME WHERE AUTO_COL IS NULL

     This method requires that 'sql_auto_is_null' variable is not set to
     0.  See server-system-variables.

     For information about 'InnoDB' and 'AUTO_INCREMENT', see
     innodb-auto-increment-handling.  For information about
     'AUTO_INCREMENT' and MySQL Replication, see
     replication-features-auto-increment.

   * 'COMMENT'

     A comment for a column can be specified with the 'COMMENT' option,
     up to 1024 characters long.  The comment is displayed by the
     'SHOW CREATE TABLE' and 'SHOW FULL COLUMNS'
     statements.

   * 'COLUMN_FORMAT'

     In NDB Cluster, it is also possible to specify a data storage
     format for individual columns of 'NDB' tables
     using 'COLUMN_FORMAT'.  Permissible column formats are 'FIXED',
     'DYNAMIC', and 'DEFAULT'.  'FIXED' is used to specify fixed-width
     storage, 'DYNAMIC' permits the column to be variable-width, and
     'DEFAULT' causes the column to use fixed-width or variable-width
     storage as determined by the column's data type (possibly
     overridden by a 'ROW_FORMAT' specifier).

     Beginning with MySQL NDB Cluster 7.5.4, for 'NDB'
     tables, the default value for 'COLUMN_FORMAT' is
     'FIXED'.  (The default had been switched to 'DYNAMIC' in MySQL NDB
     Cluster 7.5.1, but this change was reverted to maintain backwards
     compatibility with existing GA release series.)  (Bug #24487363)

     'COLUMN_FORMAT' currently has no effect on columns of tables using
     storage engines other than 'NDB'.  In MySQL
     5.7 and later, 'COLUMN_FORMAT' is silently ignored.

   * 'STORAGE'

     For 'NDB' tables, it is possible to specify
     whether the column is stored on disk or in memory by using a
     'STORAGE' clause.  'STORAGE DISK' causes the column to be stored on
     disk, and 'STORAGE MEMORY' causes in-memory storage to be used.
     The 'CREATE TABLE' statement used must still
     include a 'TABLESPACE' clause:

          mysql> CREATE TABLE t1 (
              ->     c1 INT STORAGE DISK,
              ->     c2 INT STORAGE MEMORY
              -> ) ENGINE NDB;
          ERROR 1005 (HY000): Can't create table 'c.t1' (errno: 140)

          mysql> CREATE TABLE t1 (
              ->     c1 INT STORAGE DISK,
              ->     c2 INT STORAGE MEMORY
              -> ) TABLESPACE ts_1 ENGINE NDB;
          Query OK, 0 rows affected (1.06 sec)

     For 'NDB' tables, 'STORAGE DEFAULT' is
     equivalent to 'STORAGE MEMORY'.

     The 'STORAGE' clause has no effect on tables using storage engines
     other than 'NDB'.  The 'STORAGE' keyword is
     supported only in the build of 'mysqld' that is
     supplied with NDB Cluster; it is not recognized in any other
     version of MySQL, where any attempt to use the 'STORAGE' keyword
     causes a syntax error.

   * 'GENERATED ALWAYS'

     Used to specify a generated column expression.  For information
     about generated columns, see
     create-table-generated-columns.

     Stored generated columns can be indexed.  'InnoDB' supports
     secondary indexes on virtual generated columns.  See
     create-table-secondary-indexes.

*Indexes and Foreign Keys*

   * 'CONSTRAINT SYMBOL'

     If the 'CONSTRAINT SYMBOL' clause is given, the SYMBOL value, if
     used, must be unique in the database.  A duplicate SYMBOL results
     in an error.  If the clause is not given, or a SYMBOL is not
     included following the 'CONSTRAINT' keyword, a name for the
     constraint is created automatically.

   * 'PRIMARY KEY'

     A unique index where all key columns must be defined as 'NOT NULL'.
     If they are not explicitly declared as 'NOT NULL', MySQL declares
     them so implicitly (and silently).  A table can have only one
     'PRIMARY KEY'.  The name of a 'PRIMARY KEY' is always 'PRIMARY',
     which thus cannot be used as the name for any other kind of index.

     If you do not have a 'PRIMARY KEY' and an application asks for the
     'PRIMARY KEY' in your tables, MySQL returns the first 'UNIQUE'
     index that has no 'NULL' columns as the 'PRIMARY KEY'.

     In 'InnoDB' tables, keep the 'PRIMARY KEY' short to minimize
     storage overhead for secondary indexes.  Each secondary index entry
     contains a copy of the primary key columns for the corresponding
     row.  (See innodb-index-types.)

     In the created table, a 'PRIMARY KEY' is placed first, followed by
     all 'UNIQUE' indexes, and then the nonunique indexes.  This helps
     the MySQL optimizer to prioritize which index to use and also more
     quickly to detect duplicated 'UNIQUE' keys.

     A 'PRIMARY KEY' can be a multiple-column index.  However, you
     cannot create a multiple-column index using the 'PRIMARY KEY' key
     attribute in a column specification.  Doing so only marks that
     single column as primary.  You must use a separate 'PRIMARY
     KEY(INDEX_COL_NAME, ...)' clause.

     If a 'PRIMARY KEY' consists of only one column that has an integer
     type, you can also refer to the column as '_rowid' in
     'SELECT' statements.

     In MySQL, the name of a 'PRIMARY KEY' is 'PRIMARY'.  For other
     indexes, if you do not assign a name, the index is assigned the
     same name as the first indexed column, with an optional suffix
     ('_2', '_3', '...') to make it unique.  You can see index names for
     a table using 'SHOW INDEX FROM TBL_NAME'.  See show-index.

   * 'KEY | INDEX'

     'KEY' is normally a synonym for 'INDEX'.  The key attribute
     'PRIMARY KEY' can also be specified as just 'KEY' when given in a
     column definition.  This was implemented for compatibility with
     other database systems.

   * 'UNIQUE'

     A 'UNIQUE' index creates a constraint such that all values in the
     index must be distinct.  An error occurs if you try to add a new
     row with a key value that matches an existing row.  For all
     engines, a 'UNIQUE' index permits multiple 'NULL' values for
     columns that can contain 'NULL'.  If you specify a prefix value for
     a column in a 'UNIQUE' index, the column values must be unique
     within the prefix.

     If a 'UNIQUE' index consists of only one column that has an integer
     type, you can also refer to the column as '_rowid' in
     'SELECT' statements.

   * 'FULLTEXT'

     A 'FULLTEXT' index is a special type of index used for full-text
     searches.  Only the 'InnoDB' and
     'MyISAM' storage engines support
     'FULLTEXT' indexes.  They can be created only from 'CHAR',
     see 'VARCHAR', and 'TEXT' columns.
     Indexing always happens over the entire column; column prefix
     indexing is not supported and any prefix length is ignored if
     specified.  See fulltext-search, for details of operation.
     A 'WITH PARSER' clause can be specified as an INDEX_OPTION value to
     associate a parser plugin with the index if full-text indexing and
     searching operations need special handling.  This clause is valid
     only for 'FULLTEXT' indexes.  Both 'InnoDB'
     and 'MyISAM'.
     support full-text parser plugins.  See
     full-text-plugin-type and writing-full-text-plugins for
     more information.

   * 'SPATIAL'

     You can create 'SPATIAL' indexes on spatial data types.  Spatial
     types are supported only for 'MyISAM' and 'InnoDB' tables, and
     indexed columns must be declared as 'NOT NULL'.  See
     spatial-types.

   * 'FOREIGN KEY'

     MySQL supports foreign keys, which let you cross-reference related
     data across tables, and foreign key constraints, which help keep
     this spread-out data consistent.  For definition and option
     information, see REFERENCE_DEFINITION, and REFERENCE_OPTION.

     Partitioned tables employing the 'InnoDB'
     storage engine do not support foreign keys.
     See partitioning-limitations, for more information.

   * 'CHECK'

     The 'CHECK' clause is parsed but ignored by all storage engines.
     See ansi-diff-foreign-keys.

   * 'INDEX_COL_NAME'

        * An INDEX_COL_NAME specification can end with 'ASC' or 'DESC'.
          These keywords are permitted for future extensions for
          specifying ascending or descending index value storage.
          Currently, they are parsed but ignored; index values are
          always stored in ascending order.

        * Prefixes, defined by the LENGTH attribute, can be up to 767
          bytes long for 'InnoDB' tables or 3072 bytes if the
          'innodb_large_prefix' option is enabled.  For MyISAM tables,
          the prefix limit is 1000 bytes.

          Prefix limits are measured in bytes, whereas the prefix length
          in 'CREATE TABLE', 'ALTER TABLE',
          and 'CREATE INDEX'.
          statements is interpreted as number of characters for
          nonbinary string types (see 'CHAR', 'VARCHAR',
          see 'TEXT') and number of bytes for binary
          string types (see 'BINARY',
          'VARBINARY', 'BLOB').  Take
          this into account when specifying a prefix length for a
          nonbinary string column that uses a multibyte character set.

   * 'INDEX_TYPE'

     Some storage engines permit you to specify an index type when
     creating an index.  The syntax for the INDEX_TYPE specifier is
     'USING TYPE_NAME'.

     Example:

          CREATE TABLE lookup
            (id INT, INDEX USING BTREE (id))
            ENGINE = MEMORY;

     The preferred position for 'USING' is after the index column list.
     It can be given before the column list, but support for use of the
     option in that position is deprecated and will be removed in a
     future MySQL release.

   * 'INDEX_OPTION'

     INDEX_OPTION values specify additional options for an index.

        * 'KEY_BLOCK_SIZE'

          For 'MyISAM' tables,
          'KEY_BLOCK_SIZE' optionally specifies the size in bytes to use
          for index key blocks.  The value is treated as a hint; a
          different size could be used if necessary.  A 'KEY_BLOCK_SIZE'
          value specified for an individual index definition overrides
          the table-level 'KEY_BLOCK_SIZE' value.

          For information about the table-level 'KEY_BLOCK_SIZE'
          attribute, see create-table-options.

        * 'WITH PARSER'

          The 'WITH PARSER' option can only be used with 'FULLTEXT'
          indexes.  It associates a parser plugin with the index if
          full-text indexing and searching operations need special
          handling.  Both 'InnoDB' and
          'MyISAM' support full-text
          parser plugins.  If you have a 'MyISAM'
          table with an associated full-text
          parser plugin, you can convert the table to 'InnoDB' using
          'ALTER TABLE'.

        * 'COMMENT'

          In MySQL 5.7, index definitions can include an optional
          comment of up to 1024 characters.

          You can set the 'InnoDB' 'MERGE_THRESHOLD' value for an
          individual index using the 'INDEX_OPTION' 'COMMENT' clause.
          See index-page-merge-threshold.

     For more information about permissible INDEX_OPTION values, see
     create-index.  For more information about indexes, see
     mysql-indexes.

   * 'REFERENCE_DEFINITION'

     For REFERENCE_DEFINITION syntax details and examples, see
     create-table-foreign-keys.  For information specific to foreign
     keys in 'InnoDB', see innodb-foreign-key-constraints.

     'InnoDB' and 'NDB'
     tables support checking of foreign key constraints.
     The columns of the referenced table must always be explicitly
     named.  Both 'ON DELETE' and 'ON UPDATE' actions on foreign keys
     are supported.  For more detailed information and examples, see
     create-table-foreign-keys.  For information specific to
     foreign keys in 'InnoDB', see
     innodb-foreign-key-constraints.

     For other storage engines, MySQL Server parses and ignores the
     'FOREIGN KEY' and 'REFERENCES' syntax in 'CREATE TABLE'
     statements.  See ansi-diff-foreign-keys.

     *Important*:

     For users familiar with the ANSI/ISO SQL Standard, please note that
     no storage engine, including 'InnoDB', recognizes or enforces the
     'MATCH' clause used in referential integrity constraint
     definitions.  Use of an explicit 'MATCH' clause will not have the
     specified effect, and also causes 'ON DELETE' and 'ON UPDATE'
     clauses to be ignored.  For these reasons, specifying 'MATCH'
     should be avoided.

     The 'MATCH' clause in the SQL standard controls how 'NULL' values
     in a composite (multiple-column) foreign key are handled when
     comparing to a primary key.  'InnoDB' essentially implements the
     semantics defined by 'MATCH SIMPLE', which permit a foreign key to
     be all or partially 'NULL'.  In that case, the (child table) row
     containing such a foreign key is permitted to be inserted, and does
     not match any row in the referenced (parent) table.  It is possible
     to implement other semantics using triggers.

     Additionally, MySQL requires that the referenced columns be indexed
     for performance.  However, 'InnoDB' does not enforce any
     requirement that the referenced columns be declared 'UNIQUE' or
     'NOT NULL'.  The handling of foreign key references to nonunique
     keys or keys that contain 'NULL' values is not well defined for
     operations such as 'UPDATE' or 'DELETE CASCADE'.  You are advised
     to use foreign keys that reference only keys that are both 'UNIQUE'
     (or 'PRIMARY') and 'NOT NULL'.

     MySQL parses but ignores 'inline 'REFERENCES' specifications' (as
     defined in the SQL standard) where the references are defined as
     part of the column specification.  MySQL accepts 'REFERENCES'
     clauses only when specified as part of a separate 'FOREIGN KEY'
     specification.

   * 'REFERENCE_OPTION'

     For information about the 'RESTRICT', 'CASCADE', 'SET NULL', 'NO
     ACTION', and 'SET DEFAULT' options, see
     create-table-foreign-keys.

*Table Options*

Table options are used to optimize the behavior of the table.  In most
cases, you do not have to specify any of them.  These options apply to
all storage engines unless otherwise indicated.  Options that do not
apply to a given storage engine may be accepted and remembered as part
of the table definition.  Such options then apply if you later use
'ALTER TABLE' to convert the table to use a different
storage engine.

   * 'ENGINE'

     Specifies the storage engine for the table, using one of the names
     shown in the following table.  The engine name can be unquoted or
     quoted.  The quoted name ''DEFAULT'' is recognized but ignored.

     Storage Engine     Description

     'InnoDB'           Transaction-safe tables with row locking and
                        foreign keys.  The default storage engine for
                        new tables.  See innodb-storage-engine,
                        and in particular innodb-introduction if
                        you have MySQL experience but are new to
                        'InnoDB'.

     'MyISAM'           The binary portable storage engine that is
                        primarily used for read-only or read-mostly
                        workloads.  See myisam-storage-engine.

     'MEMORY'           The data for this storage engine is stored only
                        in memory.  See memory-storage-engine.

     'CSV'              Tables that store rows in comma-separated values
                        format.  See csv-storage-engine.

     'ARCHIVE'          The archiving storage engine.  See
                        archive-storage-engine.

     'EXAMPLE'          An example engine.  See
                        example-storage-engine.

     'FEDERATED'        Storage engine that accesses remote tables.  See
                        federated-storage-engine.

     'HEAP'             This is a synonym for 'MEMORY'.

     'MERGE'            A collection of 'MyISAM' tables used as one
                        table.  Also known as 'MRG_MyISAM'.  See
                        merge-storage-engine.

     See 'NDB', fault-tolerant, memory-based tables,
     mysql-cluster.     supporting transactions and foreign keys.  Also
                        known as 'NDBCLUSTER'.  See
                        mysql-cluster.

     By default, if a storage engine is specified that is not available,
     the statement fails with an error.  You can override this behavior
     by removing 'NO_ENGINE_SUBSTITUTION' from the server SQL mode (see
     sql-mode) so that MySQL allows substitution of the
     specified engine with the default storage engine instead.  Normally
     in such cases, this is 'InnoDB', which is the default value for the
     'default_storage_engine' system variable.  When
     'NO_ENGINE_SUBSTITUTION' is disabled, a warning occurs if the
     storage engine specification is not honored.

   * 'AUTO_INCREMENT'

     The initial 'AUTO_INCREMENT' value for the table.  In MySQL 5.7,
     this works for 'MyISAM', 'MEMORY', 'InnoDB', and 'ARCHIVE' tables.
     To set the first auto-increment value for engines that do not
     support the 'AUTO_INCREMENT' table option, insert a 'dummy' row
     with a value one less than the desired value after creating the
     table, and then delete the dummy row.

     For engines that support the 'AUTO_INCREMENT' table option in
     'CREATE TABLE' statements, you can also use 'ALTER
     TABLE TBL_NAME AUTO_INCREMENT = N' to reset the 'AUTO_INCREMENT'
     value.  The value cannot be set lower than the maximum value
     currently in the column.

   * 'AVG_ROW_LENGTH'

     An approximation of the average row length for your table.  You
     need to set this only for large tables with variable-size rows.

     When you create a 'MyISAM' table, MySQL uses the product of the
     'MAX_ROWS' and 'AVG_ROW_LENGTH' options to decide how big the
     resulting table is.  If you don't specify either option, the
     maximum size for 'MyISAM' data and index files is 256TB by default.
     (If your operating system does not support files that large, table
     sizes are constrained by the file size limit.)  If you want to keep
     down the pointer sizes to make the index smaller and faster and you
     don't really need big files, you can decrease the default pointer
     size by setting the 'myisam_data_pointer_size' system variable.
     (See server-system-variables.)  If you want all your tables
     to be able to grow above the default limit and are willing to have
     your tables slightly slower and larger than necessary, you can
     increase the default pointer size by setting this variable.
     Setting the value to 7 permits table sizes up to 65,536TB.

   * '[DEFAULT] CHARACTER SET'

     Specifies a default character set for the table.  'CHARSET' is a
     synonym for 'CHARACTER SET'.  If the character set name is
     'DEFAULT', the database character set is used.

   * 'CHECKSUM'

     Set this to 1 if you want MySQL to maintain a live checksum for all
     rows (that is, a checksum that MySQL updates automatically as the
     table changes).  This makes the table a little slower to update,
     but also makes it easier to find corrupted tables.  The
     'CHECKSUM TABLE' statement reports the checksum.
     ('MyISAM' only.)

   * '[DEFAULT] COLLATE'

     Specifies a default collation for the table.

   * 'COMMENT'

     A comment for the table, up to 2048 characters long.

     You can set the 'InnoDB' 'MERGE_THRESHOLD' value for a table using
     the 'TABLE_OPTION' 'COMMENT' clause.  See
     index-page-merge-threshold.

     Setting NDB_TABLE options

     In MySQL NDB Cluster 7.5.2 and later, the table comment in a
     'CREATE TABLE' or 'ALTER TABLE' statement can
     also be used to specify one to four of the 'NDB_TABLE' options
     'NOLOGGING', 'READ_BACKUP', 'PARTITION_BALANCE', or
     'FULLY_REPLICATED' as a set of name-value pairs, separated by
     commas if need be, immediately following the string 'NDB_TABLE='
     that begins the quoted comment text.  An example statement using
     this syntax is shown here (emphasized text):

          CREATE TABLE t1 (
              c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
              c2 VARCHAR(100),
              c3 VARCHAR(100) )
          ENGINE=NDB
          _COMMENT="NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE"_;

     Spaces are not permitted within the quoted string.  The string is
     case-insensitive.

     The comment is displayed as part of the ouput of 'SHOW CREATE TABLE'.
     The text of the comment is also
     available as the TABLE_COMMENT column of the MySQL Information
     Schema 'TABLES' table.

     This comment syntax is also supported with 'ALTER TABLE'
     statements for 'NDB' tables.  Keep in mind that a
     table comment used with 'ALTER TABLE' replaces any existing comment
     which the table might have had perviously.

     Setting the 'MERGE_THRESHOLD' option in table comments is not
     supported for 'NDB' tables (it is ignored).

     For complete syntax information and examples, see
     create-table-ndb-table-comment-options.

   * 'COMPRESSION'

     The compression algorithm used for page level compression for
     'InnoDB' tables.  Supported values include 'Zlib', 'LZ4', and
     'None'.  The 'COMPRESSION' attribute was introduced with the
     transparent page compression feature.  Page compression is only
     supported with 'InnoDB' tables that reside in file-per-table
     tablespaces, and is only available on Linux and Windows platforms
     that support sparse files and hole punching.  For more information,
     see innodb-page-compression.

   * 'CONNECTION'

     The connection string for a 'FEDERATED' table.

     *Note*:

     Older versions of MySQL used a 'COMMENT' option for the connection
     string.

   * 'DATA DIRECTORY', 'INDEX DIRECTORY'

     For 'InnoDB', the 'DATA DIRECTORY='DIRECTORY'' option allows you to
     create 'InnoDB' file-per-table tablespaces outside the MySQL data
     directory.  Within the directory that you specify, MySQL creates a
     subdirectory corresponding to the database name, and within that a
     '.ibd' file for the table.  The 'innodb_file_per_table'
     configuration option must be enabled to use the 'DATA DIRECTORY'
     option with 'InnoDB'.  The full directory path must be specified.
     See tablespace-placing for more information.

     When creating 'MyISAM' tables, you can use the 'DATA
     DIRECTORY='DIRECTORY'' clause, the 'INDEX DIRECTORY='DIRECTORY''
     clause, or both.  They specify where to put a 'MyISAM' table's data
     file and index file, respectively.  Unlike 'InnoDB' tables, MySQL
     does not create subdirectories that correspond to the database name
     when creating a 'MyISAM' table with a 'DATA DIRECTORY' or 'INDEX
     DIRECTORY' option.  Files are created in the directory that is
     specified.

     As of MySQL 5.7.17, you must have the 'FILE' privilege to use the
     'DATA DIRECTORY' or 'INDEX DIRECTORY' table option.

     *Important*:

     Table-level 'DATA DIRECTORY' and 'INDEX DIRECTORY' options are
     ignored for partitioned tables.  (Bug #32091)

     These options work only when you are not using the
     '--skip-symbolic-links' option.  Your operating system must also
     have a working, thread-safe 'realpath()' call.  See
     symbolic-links-to-tables, for more complete information.

     If a 'MyISAM' table is created with no 'DATA DIRECTORY' option, the
     '.MYD' file is created in the database directory.  By default, if
     'MyISAM' finds an existing '.MYD' file in this case, it overwrites
     it.  The same applies to '.MYI' files for tables created with no
     'INDEX DIRECTORY' option.  To suppress this behavior, start the
     server with the '--keep_files_on_create' option, in which case
     'MyISAM' will not overwrite existing files and returns an error
     instead.

     If a 'MyISAM' table is created with a 'DATA DIRECTORY' or 'INDEX
     DIRECTORY' option and an existing '.MYD' or '.MYI' file is found,
     MyISAM always returns an error.  It will not overwrite a file in
     the specified directory.

     *Important*:

     You cannot use path names that contain the MySQL data directory
     with 'DATA DIRECTORY' or 'INDEX DIRECTORY'.  This includes
     partitioned tables and individual table partitions.  (See Bug
     #32167.)

   * 'DELAY_KEY_WRITE'

     Set this to 1 if you want to delay key updates for the table until
     the table is closed.  See the description of the 'delay_key_write'
     system variable in server-system-variables.  ('MyISAM'
     only.)

   * 'ENCRYPTION'

     Set the 'ENCRYPTION' option to ''Y'' to enable page-level data
     encryption for an 'InnoDB' table created in a file-per-table
     tablespace.  Option values are not case-sensitive.  The
     'ENCRYPTION' option was introduced with the 'InnoDB' tablespace
     encryption feature; see innodb-tablespace-encryption.  The
     'keyring_file' plugin must be loaded to use the 'ENCRYPTION'
     option.

   * 'INSERT_METHOD'

     If you want to insert data into a 'MERGE' table, you must specify
     with 'INSERT_METHOD' the table into which the row should be
     inserted.  'INSERT_METHOD' is an option useful for 'MERGE' tables
     only.  Use a value of 'FIRST' or 'LAST' to have inserts go to the
     first or last table, or a value of 'NO' to prevent inserts.  See
     merge-storage-engine.

   * 'KEY_BLOCK_SIZE'

     For 'MyISAM' tables, 'KEY_BLOCK_SIZE'
     optionally specifies the size in bytes to use for index key blocks.
     The value is treated as a hint; a different size could be used if
     necessary.  A 'KEY_BLOCK_SIZE' value specified for an individual
     index definition overrides the table-level 'KEY_BLOCK_SIZE' value.

     For 'InnoDB' tables, 'KEY_BLOCK_SIZE'
     optionally specifies the page size (in kilobytes) to use for
     compressed 'InnoDB' tables.  The 'KEY_BLOCK_SIZE' value is treated
     as a hint; a different size could be used by 'InnoDB' if necessary.
     'KEY_BLOCK_SIZE' can only be less than or equal to the
     'innodb_page_size' value.  A value of 0 represents the default
     compressed page size, which is half of the 'innodb_page_size'
     value.  Depending on 'innodb_page_size', possible 'KEY_BLOCK_SIZE'
     values include 0, 1, 2, 4, 8, and 16.  See
     innodb-table-compression for more information.

     Oracle recommends enabling 'innodb_strict_mode' when specifying
     'KEY_BLOCK_SIZE' for 'InnoDB' tables.  When 'innodb_strict_mode' is
     enabled, specifying an invalid 'KEY_BLOCK_SIZE' value returns an
     error.  If 'innodb_strict_mode' is disabled, an invalid
     'KEY_BLOCK_SIZE' value results in a warning, and the
     'KEY_BLOCK_SIZE' option is ignored.

     The 'Create_options' column in response to 'SHOW TABLE STATUS'
     reports the originally specified
     'KEY_BLOCK_SIZE' option, as does 'SHOW CREATE TABLE'.

     'InnoDB' only supports 'KEY_BLOCK_SIZE' at the table level.

     'KEY_BLOCK_SIZE' is not supported with 32k and 64k
     'innodb_page_size' values.  'InnoDB' table compression does not
     support these pages sizes.

   * 'MAX_ROWS'

     The maximum number of rows you plan to store in the table.  This is
     not a hard limit, but rather a hint to the storage engine that the
     table must be able to store at least this many rows.

     *Important*:

     The use of 'MAX_ROWS' with 'NDB' tables to control the number of
     table partitions is deprecated as of NDB Cluster 7.5.4.  It remains
     supported in later versions for backward compatibility, but is
     subject to removal in a future release.  Use PARTITION_BALANCE
     instead; see create-table-comment-ndb-table-options.

     The 'NDB' storage engine treats this value as
     a maximum.  If you plan to create very large NDB Cluster tables
     (containing millions of rows), you should use this option to insure
     that 'NDB' allocates sufficient number of
     index slots in the hash table used for storing hashes of the
     table's primary keys by setting 'MAX_ROWS = 2 * ROWS', where ROWS
     is the number of rows that you expect to insert into the table.

     The maximum 'MAX_ROWS' value is 4294967295; larger values are
     truncated to this limit.

   * 'MIN_ROWS'

     The minimum number of rows you plan to store in the table.  The
     'MEMORY' storage engine uses this
     option as a hint about memory use.

   * 'PACK_KEYS'

     Takes effect only with 'MyISAM' tables.  Set this option to 1 if
     you want to have smaller indexes.  This usually makes updates
     slower and reads faster.  Setting the option to 0 disables all
     packing of keys.  Setting it to 'DEFAULT' tells the storage engine
     to pack only long 'CHAR', 'VARCHAR',
     'BINARY', or 'VARBINARY'.
     columns.

     If you do not use 'PACK_KEYS', the default is to pack strings, but
     not numbers.  If you use 'PACK_KEYS=1', numbers are packed as well.

     When packing binary number keys, MySQL uses prefix compression:

        * Every key needs one extra byte to indicate how many bytes of
          the previous key are the same for the next key.

        * The pointer to the row is stored in high-byte-first order
          directly after the key, to improve compression.

     This means that if you have many equal keys on two consecutive
     rows, all following 'same' keys usually only take two bytes
     (including the pointer to the row).  Compare this to the ordinary
     case where the following keys takes 'storage_size_for_key +
     pointer_size' (where the pointer size is usually 4).  Conversely,
     you get a significant benefit from prefix compression only if you
     have many numbers that are the same.  If all keys are totally
     different, you use one byte more per key, if the key is not a key
     that can have 'NULL' values.  (In this case, the packed key length
     is stored in the same byte that is used to mark if a key is
     'NULL'.)

   * 'PASSWORD'

     This option is unused.  If you have a need to scramble your '.frm'
     files and make them unusable to any other MySQL server, please
     contact our sales department.

   * 'ROW_FORMAT'

     Defines the physical format in which the rows are stored.

     When executing a 'CREATE TABLE' statement with
     strict mode disabled, if you specify a row format that is not
     supported by the storage engine that is used for the table, the
     table is created using that storage engine's default row format.
     The information reported in the 'Row_format' column in response to
     'SHOW TABLE STATUS' is the actual row
     format used.  This may differ from the value in the
     'Create_options' column because the original 'CREATE TABLE'
     definition is retained during creation.  'SHOW CREATE TABLE'
     also reports the row format used
     in the original 'CREATE TABLE' statement.

     Row format choices differ depending on the storage engine used for
     the table.

     For 'InnoDB' tables:

        * The default row format is defined by
          'innodb_default_row_format', which has a default setting of
          'DYNAMIC'.  The default row format is used when the
          'ROW_FORMAT' option is not defined or when
          'ROW_FORMAT=DEFAULT' is used.

          If the 'ROW_FORMAT' option is not defined, or if
          'ROW_FORMAT=DEFAULT' is used, operations that rebuild a table
          also silently change the row format of the table to the
          default defined by 'innodb_default_row_format'.  For more
          information, see innodb-row-format-specification.

        * For more efficient 'InnoDB' storage of data types, especially
          'BLOB' types, use the 'DYNAMIC'.  See
          innodb-row-format-dynamic for requirements associated with
          the 'DYNAMIC' row format.

        * To enable compression for 'InnoDB' tables, specify
          'ROW_FORMAT=COMPRESSED'.  See innodb-compression for
          requirements associated with the 'COMPRESSED' row format.

        * The row format used in older versions of MySQL can still be
          requested by specifying the 'REDUNDANT' row format.

        * When you specify a non-default 'ROW_FORMAT' clause, consider
          also enabling the 'innodb_strict_mode' configuration option.

        * 'ROW_FORMAT=FIXED' is not supported.  If 'ROW_FORMAT=FIXED' is
          specified while 'innodb_strict_mode' is disabled, 'InnoDB'
          issues a warning and assumes 'ROW_FORMAT=DYNAMIC'.  If
          'ROW_FORMAT=FIXED' is specified while 'innodb_strict_mode' is
          enabled, which is the default, 'InnoDB' returns an error.

        * For additional information about 'InnoDB' row formats, see
          innodb-row-format.

     For 'MyISAM' tables, the option value can be 'FIXED' or 'DYNAMIC'
     for static or variable-length row format.  'myisampack'
     sets the type to 'COMPRESSED'.  See
     myisam-table-formats.

     For 'NDB' tables, the default 'ROW_FORMAT' in
     MySQL NDB Cluster 7.5.1 and later is 'DYNAMIC'.  (Previously, it
     was 'FIXED'.)

   * 'STATS_AUTO_RECALC'

     Specifies whether to automatically recalculate persistent
     statistics for an 'InnoDB' table.  The value 'DEFAULT' causes the
     persistent statistics setting for the table to be determined by the
     'innodb_stats_auto_recalc' configuration option.  The value '1'
     causes statistics to be recalculated when 10% of the data in the
     table has changed.  The value '0' prevents automatic recalculation
     for this table; with this setting, issue an 'ANALYZE TABLE'
     statement to recalculate the statistics after making
     substantial changes to the table.  For more information about the
     persistent statistics feature, see innodb-persistent-stats.

   * 'STATS_PERSISTENT'

     Specifies whether to enable persistent statistics for an 'InnoDB'
     table.  The value 'DEFAULT' causes the persistent statistics
     setting for the table to be determined by the
     'innodb_stats_persistent' configuration option.  The value '1'
     enables persistent statistics for the table, while the value '0'
     turns off this feature.  After enabling persistent statistics
     through a 'CREATE TABLE' or 'ALTER TABLE' statement, issue an
     'ANALYZE TABLE' statement to calculate the
     statistics, after loading representative data into the table.  For
     more information about the persistent statistics feature, see
     innodb-persistent-stats.

   * 'STATS_SAMPLE_PAGES'

     The number of index pages to sample when estimating cardinality and
     other statistics for an indexed column, such as those calculated by
     'ANALYZE TABLE'.  For more information, see
     innodb-persistent-stats.

   * 'TABLESPACE'

     The 'TABLESPACE' option is used to create a table in an 'InnoDB'
     general tablespace.

          CREATE TABLE TBL_NAME ... TABLESPACE [=] TABLESPACE_NAME

     The general tablespace that you specify must exist prior to using
     the 'TABLESPACE' option.  For information about general
     tablespaces, see general-tablespaces.

     The 'TABLESPACE_NAME' is a case-sensitive identifier.  It may be
     quoted or unquoted.  The forward slash character ('/') is not
     permitted.  Names beginning with 'innodb_' are reserved for special
     use.

     The 'TABLESPACE' option may be used to assign 'InnoDB' table
     partitions or subpartitions to a general tablespace, a separate
     file-per-table tablespace, or the system tablespace.  'TABLESPACE'
     option support for table partitions and subpartitions was added in
     MySQL 5.7.  All partitions must belong to the same storage engine.

     A tablespace specified at the table level becomes the default
     tablespace for new partitions and subpartitions.  The default
     tablespace may be overridden by specifying a tablespace at the
     partition or subpartition level in a 'CREATE TABLE'
     or 'ALTER TABLE' statement.  The
     following example shows tablespaces defined at the table level and
     partition level.

          mysql> CREATE TABLE t1 ( a INT NOT NULL, PRIMARY KEY (a))
              -> ENGINE=InnoDB TABLESPACE ts1
              -> PARTITION BY RANGE (a) PARTITIONS 3 (
              -> PARTITION P1 VALUES LESS THAN (2),
              -> PARTITION P2 VALUES LESS THAN (4) TABLESPACE ts2,
              -> PARTITION P3 VALUES LESS THAN (6) TABLESPACE ts3);

     For more information about the 'TABLESPACE' option and
     partitioning, see general-tablespaces

     To create a table in the system tablespace, specify 'innodb_system'
     as the tablespace name.

          CREATE TABLE TBL_NAME ... TABLESPACE [=] innodb_system

     Using the 'TABLESPACE [=] innodb_system' option, you can place a
     table of any uncompressed row format in the system tablespace
     regardless of the 'innodb_file_per_table' setting.  For example,
     you can add a table with 'ROW_FORMAT=DYNAMIC' to the system
     tablespace using the 'TABLESPACE [=] innodb_system' option.

     To create a table in a file-per-table tablespace, specify
     'innodb_file_per_table' as the tablespace name.

          CREATE TABLE TBL_NAME ... TABLESPACE [=] innodb_file_per_table

     *Note*:

     If 'innodb_file_per_table' is enabled, you need not specify
     'TABLESPACE=innodb_file_per_table' to create an 'InnoDB'
     file-per-table tablespace.  'InnoDB' tables are created in
     file-per-table tablespaces by default when 'innodb_file_per_table'
     is enabled.

     The 'DATA DIRECTORY' clause is permitted with 'CREATE TABLE ...
     TABLESPACE=innodb_file_per_table' but is otherwise not supported
     for use in combination with the 'TABLESPACE' option.

     The 'TABLESPACE' option is supported with 'ALTER TABLE'
     and 'ALTER TABLE ... REORGANIZE PARTITION'
     statements, which can be used to move tables and
     partitions from one tablespace to another, respectively.  For more
     information, see general-tablespaces.

     The 'STORAGE' table option is employed only with 'NDB'
     tables.  'STORAGE' determines the type of storage
     used (disk or memory), and can be one of 'DISK', 'MEMORY', or
     'DEFAULT'.

     'TABLESPACE ... STORAGE DISK' assigns a table to an NDB Cluster
     Disk Data tablespace.  The tablespace must already have been
     created using 'CREATE TABLESPACE'.  See
     mysql-cluster-disk-data, for more information.

     *Important*:

     A 'STORAGE' clause cannot be used in a 'CREATE TABLE'
     statement without a 'TABLESPACE' clause.

   * 'UNION'.

     Used to access a collection of identical 'MyISAM' tables as one.
     This works only with 'MERGE' tables.  See
     merge-storage-engine.

     You must have 'SELECT', 'UPDATE', and 'DELETE' privileges for the
     tables you map to a 'MERGE' table.

     *Note*:

     Formerly, all tables used had to be in the same database as the
     'MERGE' table itself.  This restriction no longer applies.

*Creating Partitioned Tables*

PARTITION_OPTIONS can be used to control partitioning of the table
created with 'CREATE TABLE'.

Not all options shown in the syntax for PARTITION_OPTIONS at the
beginning of this section are available for all partitioning types.
Please see the listings for the following individual types for
information specific to each type, and see partitioning, for
more complete information about the workings of and uses for
partitioning in MySQL, as well as additional examples of table creation
and other statements relating to MySQL partitioning.

Partitions can be modified, merged, added to tables, and dropped from
tables.  For basic information about the MySQL statements to accomplish
these tasks, see alter-table.  For more detailed descriptions
and examples, see partitioning-management.

   * 'PARTITION BY'

     If used, a PARTITION_OPTIONS clause begins with 'PARTITION BY'.
     This clause contains the function that is used to determine the
     partition; the function returns an integer value ranging from 1 to
     NUM, where NUM is the number of partitions.  (The maximum number of
     user-defined partitions which a table may contain is 1024; the
     number of subpartitions--discussed later in this section--is
     included in this maximum.)

     *Note*:

     The expression (EXPR) used in a 'PARTITION BY' clause cannot refer
     to any columns not in the table being created; such references are
     specifically not permitted and cause the statement to fail with an
     error.  (Bug #29444)

   * 'HASH(EXPR)'

     Hashes one or more columns to create a key for placing and locating
     rows.  EXPR is an expression using one or more table columns.  This
     can be any valid MySQL expression (including MySQL functions) that
     yields a single integer value.  For example, these are both valid
     'CREATE TABLE' statements using 'PARTITION BY
     HASH':

          CREATE TABLE t1 (col1 INT, col2 CHAR(5))
              PARTITION BY HASH(col1);

          CREATE TABLE t1 (col1 INT, col2 CHAR(5), col3 DATETIME)
              PARTITION BY HASH ( YEAR(col3) );

     You may not use either 'VALUES LESS THAN' or 'VALUES IN' clauses
     with 'PARTITION BY HASH'.

     'PARTITION BY HASH' uses the remainder of EXPR divided by the
     number of partitions (that is, the modulus).  For examples and
     additional information, see partitioning-hash.

     The 'LINEAR' keyword entails a somewhat different algorithm.  In
     this case, the number of the partition in which a row is stored is
     calculated as the result of one or more logical 'AND' operations.
     For discussion and examples of linear hashing, see
     partitioning-linear-hash.

   * 'KEY(COLUMN_LIST)'

     This is similar to 'HASH', except that MySQL supplies the hashing
     function so as to guarantee an even data distribution.  The
     COLUMN_LIST argument is simply a list of 1 or more table columns
     (maximum: 16).  This example shows a simple table partitioned by
     key, with 4 partitions:

          CREATE TABLE tk (col1 INT, col2 CHAR(5), col3 DATE)
              PARTITION BY KEY(col3)
              PARTITIONS 4;

     For tables that are partitioned by key, you can employ linear
     partitioning by using the 'LINEAR' keyword.  This has the same
     effect as with tables that are partitioned by 'HASH'.  That is, the
     partition number is found using the '&' operator rather than the
     modulus (see partitioning-linear-hash, and
     partitioning-key, for details).  This example uses linear
     partitioning by key to distribute data between 5 partitions:

          CREATE TABLE tk (col1 INT, col2 CHAR(5), col3 DATE)
              PARTITION BY LINEAR KEY(col3)
              PARTITIONS 5;

     The 'ALGORITHM={1|2}' option is supported with '[SUB]PARTITION BY
     [LINEAR] KEY'.  'ALGORITHM=1' causes the server to use the same
     key-hashing functions as MySQL 5.1; 'ALGORITHM=2' means that the
     server employs the key-hashing functions implemented and used by
     default for new 'KEY' partitioned tables in MySQL 5.5 and later.
     (Partitioned tables created with the key-hashing functions employed
     in MySQL 5.5 and later cannot be used by a MySQL 5.1 server.)  Not
     specifying the option has the same effect as using 'ALGORITHM=2'.
     This option is intended for use chiefly when upgrading or
     downgrading '[LINEAR] KEY' partitioned tables between MySQL 5.1 and
     later MySQL versions, or for creating tables partitioned by 'KEY'
     or 'LINEAR KEY' on a MySQL 5.5 or later server which can be used on
     a MySQL 5.1 server.  For more information, see
     alter-table-partition-operations.

     'mysqldump' in MySQL 5.7 (and later) writes this
     option encased in versioned comments, like this:

          CREATE TABLE t1 (a INT)
          /*!50100 PARTITION BY KEY */ _/*!50611 ALGORITHM = 1 */_ /*!50100 ()
                PARTITIONS 3 */

     This causes MySQL 5.6.10 and earlier servers to ignore the option,
     which would otherwise cause a syntax error in those versions.  If
     you plan to load a dump made on a MySQL 5.7 server where you use
     tables that are partitioned or subpartitioned by 'KEY' into a MySQL
     5.6 server previous to version 5.6.11, be sure to consult Changes
     Affecting Upgrades to MySQL 5.6
     (http://dev.mysql.com/doc/refman/5.6/en/upgrading-from-previous-series.html),
     before proceeding.  (The information found there also applies if
     you are loading a dump containing 'KEY' partitioned or
     subpartitioned tables made from a MySQL 5.7--actually 5.6.11 or
     later--server into a MySQL 5.5.30 or earlier server.)

     Also in MySQL 5.6.11 and later, 'ALGORITHM=1' is shown when
     necessary in the output of 'SHOW CREATE TABLE'
     using versioned comments in the same manner as
     'mysqldump'.  'ALGORITHM=2' is always omitted from
     'SHOW CREATE TABLE' output, even if this option was specified when
     creating the original table.

     You may not use either 'VALUES LESS THAN' or 'VALUES IN' clauses
     with 'PARTITION BY KEY'.

   * 'RANGE(EXPR)'

     In this case, EXPR shows a range of values using a set of 'VALUES
     LESS THAN' operators.  When using range partitioning, you must
     define at least one partition using 'VALUES LESS THAN'.  You cannot
     use 'VALUES IN' with range partitioning.

     *Note*:

     For tables partitioned by 'RANGE', 'VALUES LESS THAN' must be used
     with either an integer literal value or an expression that
     evaluates to a single integer value.  In MySQL 5.7, you can
     overcome this limitation in a table that is defined using
     'PARTITION BY RANGE COLUMNS', as described later in this section.

     Suppose that you have a table that you wish to partition on a
     column containing year values, according to the following scheme.

     Partition Number:             Years Range:

     0                             1990 and earlier

     1                             1991 to 1994

     2                             1995 to 1998

     3                             1999 to 2002

     4                             2003 to 2005

     5                             2006 and later

     A table implementing such a partitioning scheme can be realized by
     the 'CREATE TABLE' statement shown here:

          CREATE TABLE t1 (
              year_col  INT,
              some_data INT
          )
          PARTITION BY RANGE (year_col) (
              PARTITION p0 VALUES LESS THAN (1991),
              PARTITION p1 VALUES LESS THAN (1995),
              PARTITION p2 VALUES LESS THAN (1999),
              PARTITION p3 VALUES LESS THAN (2002),
              PARTITION p4 VALUES LESS THAN (2006),
              PARTITION p5 VALUES LESS THAN MAXVALUE
          );

     'PARTITION ... VALUES LESS THAN ...' statements work in a
     consecutive fashion.  'VALUES LESS THAN MAXVALUE' works to specify
     'leftover' values that are greater than the maximum value otherwise
     specified.

     'VALUES LESS THAN' clauses work sequentially in a manner similar to
     that of the 'case' portions of a 'switch ... case' block (as found
     in many programming languages such as C, Java, and PHP). That is,
     the clauses must be arranged in such a way that the upper limit
     specified in each successive 'VALUES LESS THAN' is greater than
     that of the previous one, with the one referencing 'MAXVALUE'
     coming last of all in the list.

   * 'RANGE COLUMNS(COLUMN_LIST)'

     This variant on 'RANGE' facilitates partition pruning for queries
     using range conditions on multiple columns (that is, having
     conditions such as 'WHERE a = 1 AND b < 10' or 'WHERE a = 1 AND b =
     10 AND c < 10').  It enables you to specify value ranges in
     multiple columns by using a list of columns in the 'COLUMNS' clause
     and a set of column values in each 'PARTITION ... VALUES LESS THAN
     (VALUE_LIST)' partition definition clause.  (In the simplest case,
     this set consists of a single column.)  The maximum number of
     columns that can be referenced in the COLUMN_LIST and VALUE_LIST is
     16.

     The COLUMN_LIST used in the 'COLUMNS' clause may contain only names
     of columns; each column in the list must be one of the following
     MySQL data types: the integer types; the string types; and time or
     date column types.  Columns using 'BLOB', 'TEXT', 'SET', 'ENUM',
     'BIT', or spatial data types are not permitted; columns that use
     floating-point number types are also not permitted.  You also may
     not use functions or arithmetic expressions in the 'COLUMNS'
     clause.

     The 'VALUES LESS THAN' clause used in a partition definition must
     specify a literal value for each column that appears in the
     'COLUMNS()' clause; that is, the list of values used for each
     'VALUES LESS THAN' clause must contain the same number of values as
     there are columns listed in the 'COLUMNS' clause.  An attempt to
     use more or fewer values in a 'VALUES LESS THAN' clause than there
     are in the 'COLUMNS' clause causes the statement to fail with the
     error 'Inconsistency in usage of column lists for partitioning...'.
     You cannot use 'NULL' for any value appearing in 'VALUES LESS
     THAN'.  It is possible to use 'MAXVALUE' more than once for a given
     column other than the first, as shown in this example:

          CREATE TABLE rc (
              a INT NOT NULL,
              b INT NOT NULL
          )
          PARTITION BY RANGE COLUMNS(a,b) (
              PARTITION p0 VALUES LESS THAN (10,5),
              PARTITION p1 VALUES LESS THAN (20,10),
              PARTITION p2 VALUES LESS THAN (50,MAXVALUE),
              PARTITION p3 VALUES LESS THAN (65,MAXVALUE),
              PARTITION p4 VALUES LESS THAN (MAXVALUE,MAXVALUE)
          );

     Each value used in a 'VALUES LESS THAN' value list must match the
     type of the corresponding column exactly; no conversion is made.
     For example, you cannot use the string ''1'' for a value that
     matches a column that uses an integer type (you must use the
     numeral '1' instead), nor can you use the numeral '1' for a value
     that matches a column that uses a string type (in such a case, you
     must use a quoted string: ''1'').

     For more information, see partitioning-range, and
     partitioning-pruning.

   * 'LIST(EXPR)'

     This is useful when assigning partitions based on a table column
     with a restricted set of possible values, such as a state or
     country code.  In such a case, all rows pertaining to a certain
     state or country can be assigned to a single partition, or a
     partition can be reserved for a certain set of states or countries.
     It is similar to 'RANGE', except that only 'VALUES IN' may be used
     to specify permissible values for each partition.

     'VALUES IN' is used with a list of values to be matched.  For
     instance, you could create a partitioning scheme such as the
     following:

          CREATE TABLE client_firms (
              id   INT,
              name VARCHAR(35)
          )
          PARTITION BY LIST (id) (
              PARTITION r0 VALUES IN (1, 5, 9, 13, 17, 21),
              PARTITION r1 VALUES IN (2, 6, 10, 14, 18, 22),
              PARTITION r2 VALUES IN (3, 7, 11, 15, 19, 23),
              PARTITION r3 VALUES IN (4, 8, 12, 16, 20, 24)
          );

     When using list partitioning, you must define at least one
     partition using 'VALUES IN'.  You cannot use 'VALUES LESS THAN'
     with 'PARTITION BY LIST'.

     *Note*:

     For tables partitioned by 'LIST', the value list used with 'VALUES
     IN' must consist of integer values only.  In MySQL 5.7, you can
     overcome this limitation using partitioning by 'LIST COLUMNS',
     which is described later in this section.

   * 'LIST COLUMNS(COLUMN_LIST)'

     This variant on 'LIST' facilitates partition pruning for queries
     using comparison conditions on multiple columns (that is, having
     conditions such as 'WHERE a = 5 AND b = 5' or 'WHERE a = 1 AND b =
     10 AND c = 5').  It enables you to specify values in multiple
     columns by using a list of columns in the 'COLUMNS' clause and a
     set of column values in each 'PARTITION ... VALUES IN (VALUE_LIST)'
     partition definition clause.

     The rules governing regarding data types for the column list used
     in 'LIST COLUMNS(COLUMN_LIST)' and the value list used in 'VALUES
     IN(VALUE_LIST)' are the same as those for the column list used in
     'RANGE COLUMNS(COLUMN_LIST)' and the value list used in 'VALUES
     LESS THAN(VALUE_LIST)', respectively, except that in the 'VALUES
     IN' clause, 'MAXVALUE' is not permitted, and you may use 'NULL'.

     There is one important difference between the list of values used
     for 'VALUES IN' with 'PARTITION BY LIST COLUMNS' as opposed to when
     it is used with 'PARTITION BY LIST'.  When used with 'PARTITION BY
     LIST COLUMNS', each element in the 'VALUES IN' clause must be a
     _set_ of column values; the number of values in each set must be
     the same as the number of columns used in the 'COLUMNS' clause, and
     the data types of these values must match those of the columns (and
     occur in the same order).  In the simplest case, the set consists
     of a single column.  The maximum number of columns that can be used
     in the COLUMN_LIST and in the elements making up the VALUE_LIST is
     16.

     The table defined by the following 'CREATE TABLE' statement
     provides an example of a table using 'LIST COLUMNS' partitioning:

          CREATE TABLE lc (
              a INT NULL,
              b INT NULL
          )
          PARTITION BY LIST COLUMNS(a,b) (
              PARTITION p0 VALUES IN( (0,0), (NULL,NULL) ),
              PARTITION p1 VALUES IN( (0,1), (0,2), (0,3), (1,1), (1,2) ),
              PARTITION p2 VALUES IN( (1,0), (2,0), (2,1), (3,0), (3,1) ),
              PARTITION p3 VALUES IN( (1,3), (2,2), (2,3), (3,2), (3,3) )
          );

   * 'PARTITIONS NUM'

     The number of partitions may optionally be specified with a
     'PARTITIONS NUM' clause, where NUM is the number of partitions.  If
     both this clause _and_ any 'PARTITION' clauses are used, NUM must
     be equal to the total number of any partitions that are declared
     using 'PARTITION' clauses.

     *Note*:

     Whether or not you use a 'PARTITIONS' clause in creating a table
     that is partitioned by 'RANGE' or 'LIST', you must still include at
     least one 'PARTITION VALUES' clause in the table definition (see
     below).

   * 'SUBPARTITION BY'

     A partition may optionally be divided into a number of
     subpartitions.  This can be indicated by using the optional
     'SUBPARTITION BY' clause.  Subpartitioning may be done by 'HASH' or
     'KEY'.  Either of these may be 'LINEAR'.  These work in the same
     way as previously described for the equivalent partitioning types.
     (It is not possible to subpartition by 'LIST' or 'RANGE'.)

     The number of subpartitions can be indicated using the
     'SUBPARTITIONS' keyword followed by an integer value.

   * Rigorous checking of the value used in 'PARTITIONS' or
     'SUBPARTITIONS' clauses is applied and this value must adhere to
     the following rules:

        * The value must be a positive, nonzero integer.

        * No leading zeros are permitted.

        * The value must be an integer literal, and cannot not be an
          expression.  For example, 'PARTITIONS 0.2E+01' is not
          permitted, even though '0.2E+01' evaluates to '2'.  (Bug
          #15890)

   * 'PARTITION_DEFINITION'

     Each partition may be individually defined using a
     PARTITION_DEFINITION clause.  The individual parts making up this
     clause are as follows:

        * 'PARTITION PARTITION_NAME'

          Specifies a logical name for the partition.

        * 'VALUES'

          For range partitioning, each partition must include a 'VALUES
          LESS THAN' clause; for list partitioning, you must specify a
          'VALUES IN' clause for each partition.  This is used to
          determine which rows are to be stored in this partition.  See
          the discussions of partitioning types in partitioning,
          for syntax examples.

        * '[STORAGE] ENGINE'

          The partitioning handler accepts a '[STORAGE] ENGINE' option
          for both 'PARTITION' and 'SUBPARTITION'.  Currently, the only
          way in which this can be used is to set all partitions or all
          subpartitions to the same storage engine, and an attempt to
          set different storage engines for partitions or subpartitions
          in the same table will give rise to the error 'ERROR 1469
          (HY000): The mix of handlers in the partitions is not
          permitted in this version of MySQL'.  We expect to lift this
          restriction on partitioning in a future MySQL release.

        * 'COMMENT'

          An optional 'COMMENT' clause may be used to specify a string
          that describes the partition.  Example:

               COMMENT = 'Data for the years previous to 1999'

          The maximum length for a partition comment is 1024 characters.

        * 'DATA DIRECTORY' and 'INDEX DIRECTORY'

          'DATA DIRECTORY' and 'INDEX DIRECTORY' may be used to indicate
          the directory where, respectively, the data and indexes for
          this partition are to be stored.  Both the 'DATA_DIR' and the
          'INDEX_DIR' must be absolute system path names.

          As of MySQL 5.7.17, you must have the 'FILE' privilege to use
          the 'DATA DIRECTORY' or 'INDEX DIRECTORY' partition option.

          Example:

               CREATE TABLE th (id INT, name VARCHAR(30), adate DATE)
               PARTITION BY LIST(YEAR(adate))
               (
                 PARTITION p1999 VALUES IN (1995, 1999, 2003)
                   DATA DIRECTORY = '/var/appdata/95/data'
                   INDEX DIRECTORY = '/var/appdata/95/idx',
                 PARTITION p2000 VALUES IN (1996, 2000, 2004)
                   DATA DIRECTORY = '/var/appdata/96/data'
                   INDEX DIRECTORY = '/var/appdata/96/idx',
                 PARTITION p2001 VALUES IN (1997, 2001, 2005)
                   DATA DIRECTORY = '/var/appdata/97/data'
                   INDEX DIRECTORY = '/var/appdata/97/idx',
                 PARTITION p2002 VALUES IN (1998, 2002, 2006)
                   DATA DIRECTORY = '/var/appdata/98/data'
                   INDEX DIRECTORY = '/var/appdata/98/idx'
               );

          'DATA DIRECTORY' and 'INDEX DIRECTORY' behave in the same way
          as in the 'CREATE TABLE' statement's
          TABLE_OPTION clause as used for 'MyISAM' tables.

          One data directory and one index directory may be specified
          per partition.  If left unspecified, the data and indexes are
          stored by default in the table's database directory.

          On Windows, the 'DATA DIRECTORY' and 'INDEX DIRECTORY' options
          are not supported for individual partitions or subpartitions
          of 'MyISAM' tables, and the
          'INDEX DIRECTORY' option is not supported for individual
          partitions or subpartitions of 'InnoDB'
          tables.  These options are ignored on
          Windows, except that a warning is generated.  (Bug #30459)

          *Note*:

          The 'DATA DIRECTORY' and 'INDEX DIRECTORY' options are ignored
          for creating partitioned tables if 'NO_DIR_IN_CREATE' is in
          effect.  (Bug #24633)

        * 'MAX_ROWS' and 'MIN_ROWS'

          May be used to specify, respectively, the maximum and minimum
          number of rows to be stored in the partition.  The values for
          MAX_NUMBER_OF_ROWS and MIN_NUMBER_OF_ROWS must be positive
          integers.  As with the table-level options with the same
          names, these act only as 'suggestions' to the server and are
          not hard limits.

        * 'TABLESPACE'

          May be used to assign 'InnoDB' table partitions or
          subpartitions to a general tablespace, a separate
          file-per-table tablespace, or the system tablespace.
          'TABLESPACE' option support for table partitions and
          subpartitions was added in MySQL 5.7 see
          general-tablespaces.  It is also supported by NDB Cluster.
          All partitions must belong to the same storage engine.

   * 'SUBPARTITION_DEFINITION'

     The partition definition may optionally contain one or more
     SUBPARTITION_DEFINITION clauses.  Each of these consists at a
     minimum of the 'SUBPARTITION NAME', where NAME is an identifier for
     the subpartition.  Except for the replacement of the 'PARTITION'
     keyword with 'SUBPARTITION', the syntax for a subpartition
     definition is identical to that for a partition definition.

     Subpartitioning must be done by 'HASH' or 'KEY', and can be done
     only on 'RANGE' or 'LIST' partitions.  See
     partitioning-subpartitions.

*Partitioning by Generated Columns*

Partitioning by generated columns is permitted.  For example:

     CREATE TABLE t1 (
       s1 INT,
       s2 INT AS (EXP(s1)) STORED
     )
     PARTITION BY LIST (s2) (
       PARTITION p1 VALUES IN (1)
     );

Partitioning sees a generated column as a regular column, which enables
workarounds for limitations on functions that are not permitted for
partitioning (see partitioning-limitations-functions).  The
preceding example demonstrates this technique: 'EXP()' cannot be used
directly in the 'PARTITION BY' clause, but a generated column defined
using 'EXP()' is permitted.

13.1.18.1 CREATE TABLE Statement Retention
..........................................

The original 'CREATE TABLE' statement, including
all specifications and table options are stored by MySQL when the table
is created.  The information is retained so that if you change storage
engines, collations or other settings using an 'ALTER TABLE'
statement, the original table options specified are
retained.  This enables you to change between 'InnoDB'
and 'MyISAM' table
types even though the row formats supported by the two engines are
different.

Because the text of the original statement is retained, but due to the
way that certain values and options may be silently reconfigured (such
as the 'ROW_FORMAT'), the active table definition (accessible through
'DESCRIBE' or with 'SHOW TABLE STATUS')
and the table creation string (accessible through
'SHOW CREATE TABLE') will report different
values.

13.1.18.2 Files Created by CREATE TABLE
.......................................

MySQL represents each table by an '.frm' table format (definition) file
in the database directory.  The storage engine for the table might
create other files as well.

For an 'InnoDB' table created in a file-per-table tablespace or general
tablespace, table data and associated indexes are stored in an ibd file
in the database directory.  When an 'InnoDB' table is created in the
system tablespace, table data and indexes are stored in the ibdata*
files that represent the system tablespace.  The 'innodb_file_per_table'
option controls whether tables are created in file-per-table tablespaces
or the system tablespace, by default.  The 'TABLESPACE' option can be
used to place a table in a file-per-table tablespace, general
tablespace, or the system tablespace, regardless of the
'innodb_file_per_table' setting.

For 'MyISAM' tables, the storage engine creates data and index files.
Thus, for each 'MyISAM' table TBL_NAME, there are three disk files.

File                   Purpose

'TBL_NAME.frm'         Table format (definition) file

'TBL_NAME.MYD'         Data file

'TBL_NAME.MYI'         Index file

See storage-engines, describes what files each storage engine
creates to represent tables.  If a table name contains special
characters, the names for the table files contain encoded versions of
those characters as described in identifier-mapping.

13.1.18.3 CREATE TEMPORARY TABLE Syntax
.......................................

You can use the 'TEMPORARY' keyword when creating a table.  A
'TEMPORARY' table is visible only within the current session, and is
dropped automatically when the session is closed.  This means that two
different sessions can use the same temporary table name without
conflicting with each other or with an existing non-'TEMPORARY' table of
the same name.  (The existing table is hidden until the temporary table
is dropped.)

'CREATE TABLE' causes an implicit commit, except
when used with the 'TEMPORARY' keyword.  See implicit-commit.

'TEMPORARY' tables have a very loose relationship with databases
(schemas).  Dropping a database does not automatically drop any
'TEMPORARY' tables created within that database.  Also, you can create a
'TEMPORARY' table in a nonexistent database if you qualify the table
name with the database name in the 'CREATE TABLE' statement.  In this
case, all subsequent references to the table must be qualified with the
database name.

To create a temporary table, you must have the 'CREATE TEMPORARY TABLES'
privilege.  After a session has created a temporary table, the server
performs no further privilege checks on the table.  The creating session
can perform any operation on the table, such as 'DROP TABLE',
see 'INSERT', 'UPDATE', or
'SELECT'.

One implication of this behavior is that a session can manipulate its
temporary tables even if the current user has no privilege to create
them.  Suppose that the current user does not have the 'CREATE TEMPORARY
TABLES' privilege but is able to execute a definer-context stored
procedure that executes with the privileges of a user who does have
'CREATE TEMPORARY TABLES' and that creates a temporary table.  While the
procedure executes, the session uses the privileges of the defining
user.  After the procedure returns, the effective privileges revert to
those of the current user, which can still see the temporary table and
perform any operation on it.

13.1.18.4 CREATE TABLE ... LIKE Syntax
......................................

Use 'CREATE TABLE ... LIKE' to create an empty table based on the
definition of another table, including any column attributes and indexes
defined in the original table:

     CREATE TABLE NEW_TBL LIKE ORIG_TBL;

The copy is created using the same version of the table storage format
as the original table.  The 'SELECT' privilege is required on the
original table.

'LIKE' works only for base tables, not for views.

*Important*:

You cannot execute 'CREATE TABLE' or 'CREATE TABLE ... LIKE' while a
'LOCK TABLES' statement is in effect.

'CREATE TABLE ... LIKE' makes the same checks as
'CREATE TABLE' and does not just copy the '.frm'
file.  This means that if the current SQL mode is different from the
mode in effect when the original table was created, the table definition
might be considered invalid for the new mode and the statement will
fail.

For 'CREATE TABLE ... LIKE', the destination table preserves generated
column information from the original table.

'CREATE TABLE ... LIKE' does not preserve any 'DATA DIRECTORY' or 'INDEX
DIRECTORY' table options that were specified for the original table, or
any foreign key definitions.

If the original table is a 'TEMPORARY' table, 'CREATE TABLE ... LIKE'
does not preserve 'TEMPORARY'.  To create a 'TEMPORARY' destination
table, use 'CREATE TEMPORARY TABLE ... LIKE'.

13.1.18.5 CREATE TABLE ... SELECT Syntax
........................................

You can create one table from another by adding a 'SELECT'
statement at the end of the 'CREATE TABLE'.
statement:

     CREATE TABLE NEW_TBL [AS] SELECT * FROM ORIG_TBL;

MySQL creates new columns for all elements in the 'SELECT'.
For example:

     mysql> CREATE TABLE test (a INT NOT NULL AUTO_INCREMENT,
         ->        PRIMARY KEY (a), KEY(b))
         ->        ENGINE=MyISAM SELECT b,c FROM test2;

This creates a 'MyISAM' table with three
columns, 'a', 'b', and 'c'.  The 'ENGINE' option is part of the
'CREATE TABLE' statement, and should not be used
following the 'SELECT'.; this would result in a syntax
error.  The same is true for other 'CREATE TABLE'.
options such as 'CHARSET'.

Notice that the columns from the 'SELECT' statement are
appended to the right side of the table, not overlapped onto it.  Take
the following example:

     mysql> SELECT * FROM foo;
     +---+
     | n |
     +---+
     | 1 |
     +---+

     mysql> CREATE TABLE bar (m INT) SELECT n FROM foo;
     Query OK, 1 row affected (0.02 sec)
     Records: 1  Duplicates: 0  Warnings: 0

     mysql> SELECT * FROM bar;
     +------+---+
     | m    | n |
     +------+---+
     | NULL | 1 |
     +------+---+
     1 row in set (0.00 sec)

For each row in table 'foo', a row is inserted in 'bar' with the values
from 'foo' and default values for the new columns.

In a table resulting from 'CREATE TABLE ... SELECT',
columns named only in the 'CREATE TABLE' part come
first.  Columns named in both parts or only in the 'SELECT'
part come after that.  The data type of 'SELECT'.
columns can be overridden by also specifying the column in the
'CREATE TABLE' part.

If any errors occur while copying the data to the table, it is
automatically dropped and not created.

You can precede the 'SELECT' by 'IGNORE' or 'REPLACE' to
indicate how to handle rows that duplicate unique key values.  With
'IGNORE', rows that duplicate an existing row on a unique key value are
discarded.  With 'REPLACE', new rows replace rows that have the same
unique key value.  If neither 'IGNORE' nor 'REPLACE' is specified,
duplicate unique key values result in an error.  For more information,
see ignore-strict-comparison.

Because the ordering of the rows in the underlying 'SELECT'
statements cannot always be determined, 'CREATE TABLE ... IGNORE
SELECT' and 'CREATE TABLE ... REPLACE SELECT' statements are flagged as
unsafe for statement-based replication.  Such statements produce a
warning in the error log when using statement-based mode and are written
to the binary log using the row-based format when using 'MIXED' mode.
See also replication-sbr-rbr.

'CREATE TABLE ... SELECT' does not automatically
create any indexes for you.  This is done intentionally to make the
statement as flexible as possible.  If you want to have indexes in the
created table, you should specify these before the 'SELECT'
statement:

     mysql> CREATE TABLE bar (UNIQUE (n)) SELECT n FROM foo;

For 'CREATE TABLE ... SELECT', the destination table does not preserve
information about whether columns in the selected-from table are
generated columns.  The 'SELECT' part of the statement
cannot assign values to generated columns in the destination table.

Some conversion of data types might occur.  For example, the
'AUTO_INCREMENT' attribute is not preserved, and 'VARCHAR'.
columns can become 'CHAR' columns.  Retrained attributes
are 'NULL' (or 'NOT NULL') and, for those columns that have them,
'CHARACTER SET', 'COLLATION', 'COMMENT', and the 'DEFAULT' clause.

When creating a table with 'CREATE TABLE ... SELECT',
make sure to alias any function calls or
expressions in the query.  If you do not, the 'CREATE' statement might
fail or result in undesirable column names.

     CREATE TABLE artists_and_works
       SELECT artist.name, COUNT(work.artist_id) AS number_of_works
       FROM artist LEFT JOIN work ON artist.id = work.artist_id
       GROUP BY artist.id;

You can also explicitly specify the data type for a column in the
created table:

     CREATE TABLE foo (a TINYINT NOT NULL) SELECT b+1 AS a FROM bar;

For 'CREATE TABLE ... SELECT', if 'IF NOT EXISTS' is
given and the target table exists, nothing is inserted into the
destination table, and the statement is not logged.

To ensure that the binary log can be used to re-create the original
tables, MySQL does not permit concurrent inserts during 'CREATE TABLE ... SELECT'.

You cannot use 'FOR UPDATE' as part of the 'SELECT' in a
statement such as 'CREATE TABLE NEW_TABLE SELECT ... FROM OLD_TABLE ...'.
If you attempt to do so, the
statement fails.

13.1.18.6 Using FOREIGN KEY Constraints
.......................................

MySQL supports foreign keys, which let you cross-reference related data
across tables, and foreign key constraints, which help keep this
spread-out data consistent.  The essential syntax for a foreign key
constraint definition in a 'CREATE TABLE' or
'ALTER TABLE' statement looks like this:

     [CONSTRAINT [SYMBOL]] FOREIGN KEY
         [INDEX_NAME] (INDEX_COL_NAME, ...)
         REFERENCES TBL_NAME (INDEX_COL_NAME,...)
         [ON DELETE REFERENCE_OPTION]
         [ON UPDATE REFERENCE_OPTION]

     REFERENCE_OPTION:
         RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT

INDEX_NAME represents a foreign key ID. The INDEX_NAME value is ignored
if there is already an explicitly defined index on the child table that
can support the foreign key.  Otherwise, MySQL implicitly creates a
foreign key index that is named according to the following rules:

   * If defined, the 'CONSTRAINT' SYMBOL value is used.  Otherwise, the
     'FOREIGN KEY' INDEX_NAME value is used.

   * If neither a 'CONSTRAINT' SYMBOL or 'FOREIGN KEY' INDEX_NAME is
     defined, the foreign key index name is generated using the name of
     the referencing foreign key column.

Foreign keys definitions are subject to the following conditions:

   * Foreign key relationships involve a parent table that holds the
     central data values, and a child table with identical values
     pointing back to its parent.  The 'FOREIGN KEY' clause is specified
     in the child table.  The parent and child tables must use the same
     storage engine.  They must not be 'TEMPORARY' tables.

     In MySQL 5.7, creation of a foreign key constraint requires the
     'REFERENCES' privilege for the parent table.

   * Corresponding columns in the foreign key and the referenced key
     must have similar data types.  _The size and sign of integer types
     must be the same_.  The length of string types need not be the
     same.  For nonbinary (character) string columns, the character set
     and collation must be the same.

   * When 'foreign_key_checks' is enabled, which is the default setting,
     character set conversion is not permitted on tables that include a
     character string column used in a foreign key constraint.  The
     workaround is described in alter-table.

   * MySQL requires indexes on foreign keys and referenced keys so that
     foreign key checks can be fast and not require a table scan.  In
     the referencing table, there must be an index where the foreign key
     columns are listed as the _first_ columns in the same order.  Such
     an index is created on the referencing table automatically if it
     does not exist.  This index might be silently dropped later, if you
     create another index that can be used to enforce the foreign key
     constraint.  INDEX_NAME, if given, is used as described previously.

   * 'InnoDB' permits a foreign key to reference any column or group of
     columns.  However, in the referenced table, there must be an index
     where the referenced columns are listed as the _first_ columns in
     the same order.

     'NDB' requires an explicit unique key (or primary key) on any
     column referenced as a foreign key.

   * Index prefixes on foreign key columns are not supported.  One
     consequence of this is that 'BLOB' and 'TEXT'
     columns cannot be included in a foreign key because indexes
     on those columns must always include a prefix length.

   * If the 'CONSTRAINT SYMBOL' clause is given, the SYMBOL value, if
     used, must be unique in the database.  A duplicate SYMBOL will
     result in an error similar to: 'ERROR 1022 (2300): Can't write;
     duplicate key in table '#sql- 464_1''.  If the clause is not given,
     or a SYMBOL is not included following the 'CONSTRAINT' keyword, a
     name for the constraint is created automatically.

   * 'InnoDB' does not currently support
     foreign keys for tables with user-defined partitioning.  This
     includes both parent and child tables.

     This restriction does not apply for 'NDB'.
     tables that are partitioned by 'KEY' or 'LINEAR KEY' (the only user
     partitioning types supported by the 'NDB' storage engine); these
     may have foreign key references or be the targets of such
     references.

   * For 'NDB' tables, 'ON UPDATE CASCADE' is not
     supported where the reference is to the parent table's primary key.

*Referential Actions*

This section describes how foreign keys help guarantee referential
integrity.

For storage engines supporting foreign keys, MySQL rejects any
'INSERT' or 'UPDATE' operation that attempts to
create a foreign key value in a child table if there is no a matching
candidate key value in the parent table.

When an 'UPDATE' or 'DELETE' operation
affects a key value in the parent table that has matching rows in the
child table, the result depends on the _referential action_ specified
using 'ON UPDATE' and 'ON DELETE' subclauses of the 'FOREIGN KEY'
clause.  MySQL supports five options regarding the action to be taken,
listed here:

   * 'CASCADE': Delete or update the row from the parent table, and
     automatically delete or update the matching rows in the child
     table.  Both 'ON DELETE CASCADE' and 'ON UPDATE CASCADE' are
     supported.  Between two tables, do not define several 'ON UPDATE
     CASCADE' clauses that act on the same column in the parent table or
     in the child table.

     *Note*:

     Cascaded foreign key actions do not activate triggers.

   * 'SET NULL': Delete or update the row from the parent table, and set
     the foreign key column or columns in the child table to 'NULL'.
     Both 'ON DELETE SET NULL' and 'ON UPDATE SET NULL' clauses are
     supported.

     If you specify a 'SET NULL' action, _make sure that you have not
     declared the columns in the child table as 'NOT NULL'_.

   * 'RESTRICT': Rejects the delete or update operation for the parent
     table.  Specifying 'RESTRICT' (or 'NO ACTION') is the same as
     omitting the 'ON DELETE' or 'ON UPDATE' clause.

   * 'NO ACTION': A keyword from standard SQL. In MySQL, equivalent to
     'RESTRICT'.  The MySQL Server rejects the delete or update
     operation for the parent table if there is a related foreign key
     value in the referenced table.  Some database systems have deferred
     checks, and 'NO ACTION' is a deferred check.  In MySQL, foreign key
     constraints are checked immediately, so 'NO ACTION' is the same as
     'RESTRICT'.

   * 'SET DEFAULT': This action is recognized by the MySQL parser, but
     both 'InnoDB' and 'NDB'
     reject table definitions containing 'ON DELETE SET
     DEFAULT' or 'ON UPDATE SET DEFAULT' clauses.

For an 'ON DELETE' or 'ON UPDATE' that is not specified, the default
action is always 'RESTRICT'.

MySQL supports foreign key references between one column and another
within a table.  (A column cannot have a foreign key reference to
itself.)  In these cases, 'child table records' really refers to
dependent records within the same table.

A foreign key constraint on a stored generated column cannot use 'ON
UPDATE CASCADE', 'ON DELETE SET NULL', 'ON UPDATE SET NULL', 'ON DELETE
SET DEFAULT', or 'ON UPDATE SET DEFAULT'.

A foreign key constraint cannot reference a virtual generated column.

For 'InnoDB' restrictions related to foreign keys and generated columns,
see innodb-foreign-key-constraints.

*Examples of Foreign Key Clauses*

Here is a simple example that relates 'parent' and 'child' tables
through a single-column foreign key:

     CREATE TABLE parent (
         id INT NOT NULL,
         PRIMARY KEY (id)
     ) ENGINE=INNODB;

     CREATE TABLE child (
         id INT,
         parent_id INT,
         INDEX par_ind (parent_id),
         FOREIGN KEY (parent_id)
             REFERENCES parent(id)
             ON DELETE CASCADE
     ) ENGINE=INNODB;

A more complex example in which a 'product_order' table has foreign keys
for two other tables.  One foreign key references a two-column index in
the 'product' table.  The other references a single-column index in the
'customer' table:

     CREATE TABLE product (
         category INT NOT NULL, id INT NOT NULL,
         price DECIMAL,
         PRIMARY KEY(category, id)
     )   ENGINE=INNODB;

     CREATE TABLE customer (
         id INT NOT NULL,
         PRIMARY KEY (id)
     )   ENGINE=INNODB;

     CREATE TABLE product_order (
         no INT NOT NULL AUTO_INCREMENT,
         product_category INT NOT NULL,
         product_id INT NOT NULL,
         customer_id INT NOT NULL,

         PRIMARY KEY(no),
         INDEX (product_category, product_id),
         INDEX (customer_id),

         FOREIGN KEY (product_category, product_id)
           REFERENCES product(category, id)
           ON UPDATE CASCADE ON DELETE RESTRICT,

         FOREIGN KEY (customer_id)
           REFERENCES customer(id)
     )   ENGINE=INNODB;

*Adding foreign keys*

You can add a new foreign key constraint to an existing table by using
'ALTER TABLE'.  The syntax relating to foreign keys
for this statement is shown here:

     ALTER TABLE TBL_NAME
         ADD [CONSTRAINT [SYMBOL]] FOREIGN KEY
         [INDEX_NAME] (INDEX_COL_NAME, ...)
         REFERENCES TBL_NAME (INDEX_COL_NAME,...)
         [ON DELETE REFERENCE_OPTION]
         [ON UPDATE REFERENCE_OPTION]

The foreign key can be self referential (referring to the same table).
When you add a foreign key constraint to a table using 'ALTER TABLE',
_remember to create the required indexes first._

*Dropping Foreign Keys*

You can also use 'ALTER TABLE' to drop foreign keys,
using the syntax shown here:

     ALTER TABLE TBL_NAME DROP FOREIGN KEY FK_SYMBOL;

If the 'FOREIGN KEY' clause included a 'CONSTRAINT' name when you
created the foreign key, you can refer to that name to drop the foreign
key.  Otherwise, the FK_SYMBOL value is generated internally when the
foreign key is created.  To find out the symbol value when you want to
drop a foreign key, use a 'SHOW CREATE TABLE'.
statement, as shown here:

     mysql> SHOW CREATE TABLE ibtest11c\G
     *************************** 1. row ***************************
            Table: ibtest11c
     Create Table: CREATE TABLE `ibtest11c` (
       `A` int(11) NOT NULL auto_increment,
       `D` int(11) NOT NULL default '0',
       `B` varchar(200) NOT NULL default '',
       `C` varchar(175) default NULL,
       PRIMARY KEY  (`A`,`D`,`B`),
       KEY `B` (`B`,`C`),
       KEY `C` (`C`),
       CONSTRAINT `0_38775` FOREIGN KEY (`A`, `D`)
     REFERENCES `ibtest11a` (`A`, `D`)
     ON DELETE CASCADE ON UPDATE CASCADE,
       CONSTRAINT `0_38776` FOREIGN KEY (`B`, `C`)
     REFERENCES `ibtest11a` (`B`, `C`)
     ON DELETE CASCADE ON UPDATE CASCADE
     ) ENGINE=INNODB CHARSET=latin1
     1 row in set (0.01 sec)

     mysql> ALTER TABLE ibtest11c DROP FOREIGN KEY `0_38775`;

Adding and dropping a foreign key in the same 'ALTER TABLE'
statement is supported for 'ALTER TABLE ... ALGORITHM=INPLACE'
but remains unsupported for
'ALTER TABLE ... ALGORITHM=COPY'.

The server prohibits changes to foreign key columns with the potential
to cause loss of referential integrity.  A workaround is to use
'ALTER TABLE ... DROP FOREIGN KEY' before changing the
column definition and 'ALTER TABLE ... ADD FOREIGN KEY'
afterward.

*Foreign Keys and Other MySQL Statements*

Table and column identifiers in a 'FOREIGN KEY ... REFERENCES ...'
clause can be quoted within backticks ('`').  Alternatively, double
quotation marks ('"') can be used if the 'ANSI_QUOTES' SQL mode is
enabled.  The setting of the 'lower_case_table_names' system variable is
also taken into account.

You can view a child table's foreign key definitions as part of the
output of the 'SHOW CREATE TABLE' statement:

     SHOW CREATE TABLE TBL_NAME;

You can also obtain information about foreign keys by querying the
'INFORMATION_SCHEMA.KEY_COLUMN_USAGE' table.

You can find information about foreign keys used by 'InnoDB'
tables in the 'INNODB_SYS_FOREIGN'
and 'INNODB_SYS_FOREIGN_COLS'
tables, also in the 'INFORMATION_SCHEMA'
database.

'mysqldump' produces correct definitions of tables in
the dump file, including the foreign keys for child tables.

To make it easier to reload dump files for tables that have foreign key
relationships, see 'mysqldump' automatically includes a
statement in the dump output to set 'foreign_key_checks' to 0.  This
avoids problems with tables having to be reloaded in a particular order
when the dump is reloaded.  It is also possible to set this variable
manually:

     mysql> SET foreign_key_checks = 0;
     mysql> SOURCE DUMP_FILE_NAME;
     mysql> SET foreign_key_checks = 1;

This enables you to import the tables in any order if the dump file
contains tables that are not correctly ordered for foreign keys.  It
also speeds up the import operation.  Setting 'foreign_key_checks' to 0
can also be useful for ignoring foreign key constraints during
'LOAD DATA' and 'ALTER TABLE'.
operations.  However, even if 'foreign_key_checks = 0', MySQL does not
permit the creation of a foreign key constraint where a column
references a nonmatching column type.  Also, if a table has foreign key
constraints, see 'ALTER TABLE' cannot be used to alter
the table to use another storage engine.  To change the storage engine,
you must drop any foreign key constraints first.

You cannot issue 'DROP TABLE' for a table that is
referenced by a 'FOREIGN KEY' constraint, unless you do 'SET
foreign_key_checks = 0'.  When you drop a table, any constraints that
were defined in the statement used to create that table are also
dropped.

If you re-create a table that was dropped, it must have a definition
that conforms to the foreign key constraints referencing it.  It must
have the correct column names and types, and it must have indexes on the
referenced keys, as stated earlier.  If these are not satisfied, MySQL
returns Error 1005 and refers to Error 150 in the error message, which
means that a foreign key constraint was not correctly formed.
Similarly, if an 'ALTER TABLE' fails due to Error
150, this means that a foreign key definition would be incorrectly
formed for the altered table.

For 'InnoDB' tables, you can obtain a detailed explanation of the most
recent 'InnoDB' foreign key error in the MySQL Server, by checking the
output of 'SHOW ENGINE INNODB STATUS'.

*Important*:

For users familiar with the ANSI/ISO SQL Standard, please note that no
storage engine, including 'InnoDB', recognizes or enforces the 'MATCH'
clause used in referential-integrity constraint definitions.  Use of an
explicit 'MATCH' clause will not have the specified effect, and also
causes 'ON DELETE' and 'ON UPDATE' clauses to be ignored.  For these
reasons, specifying 'MATCH' should be avoided.

The 'MATCH' clause in the SQL standard controls how 'NULL' values in a
composite (multiple-column) foreign key are handled when comparing to a
primary key.  MySQL essentially implements the semantics defined by
'MATCH SIMPLE', which permit a foreign key to be all or partially
'NULL'.  In that case, the (child table) row containing such a foreign
key is permitted to be inserted, and does not match any row in the
referenced (parent) table.  It is possible to implement other semantics
using triggers.

Additionally, MySQL requires that the referenced columns be indexed for
performance reasons.  However, the system does not enforce a requirement
that the referenced columns be 'UNIQUE' or be declared 'NOT NULL'.  The
handling of foreign key references to nonunique keys or keys that
contain 'NULL' values is not well defined for operations such as
'UPDATE' or 'DELETE CASCADE'.  You are advised to use foreign
keys that reference only 'UNIQUE' (including 'PRIMARY') and 'NOT NULL'
keys.

Furthermore, MySQL parses but ignores 'inline 'REFERENCES'
specifications' (as defined in the SQL standard) where the references
are defined as part of the column specification.  MySQL accepts
'REFERENCES' clauses only when specified as part of a separate 'FOREIGN
KEY' specification.  For storage engines that do not support foreign
keys (such as 'MyISAM'), MySQL Server
parses and ignores foreign key specifications.

13.1.18.7 Silent Column Specification Changes
.............................................

In some cases, MySQL silently changes column specifications from those
given in a 'CREATE TABLE' or 'ALTER TABLE'
statement.  These might be changes to a data type, to
attributes associated with a data type, or to an index specification.

All changes are subject to the internal row-size limit of 65,535 bytes,
which may cause some attempts at data type changes to fail.  See
column-count-limit.

   * Columns that are part of a 'PRIMARY KEY' are made 'NOT NULL' even
     if not declared that way.

   * Trailing spaces are automatically deleted from 'ENUM'.
     and 'SET' member values when the table is created.

   * MySQL maps certain data types used by other SQL database vendors to
     MySQL types.  See other-vendor-data-types.

   * If you include a 'USING' clause to specify an index type that is
     not permitted for a given storage engine, but there is another
     index type available that the engine can use without affecting
     query results, the engine uses the available type.

   * If strict SQL mode is not enabled, a 'VARCHAR' column
     with a length specification greater than 65535 is converted to
     'TEXT', and a 'VARBINARY'.
     column with a length specification greater than 65535 is converted
     to 'BLOB'.  Otherwise, an error occurs in either of
     these cases.

   * Specifying the 'CHARACTER SET binary' attribute for a character
     data type causes the column to be created as the corresponding
     binary data type: 'CHAR' becomes 'BINARY',
     see 'VARCHAR' becomes 'VARBINARY',
     and 'TEXT' becomes 'BLOB'.
     For the 'ENUM' and 'SET' data
     types, this does not occur; they are created as declared.  Suppose
     that you specify a table using this definition:

          CREATE TABLE t
          (
            c1 VARCHAR(10) CHARACTER SET binary,
            c2 TEXT CHARACTER SET binary,
            c3 ENUM('a','b','c') CHARACTER SET binary
          );

     The resulting table has this definition:

          CREATE TABLE t
          (
            c1 VARBINARY(10),
            c2 BLOB,
            c3 ENUM('a','b','c') CHARACTER SET binary
          );

To see whether MySQL used a data type other than the one you specified,
issue a 'DESCRIBE' or 'SHOW CREATE TABLE'
statement after creating or altering the table.

Certain other data type changes can occur if you compress a table using
'myisampack'.  See compressed-format.

13.1.18.8 CREATE TABLE and Generated Columns
............................................

'CREATE TABLE' supports the specification of
generated columns.  Values of a generated column are computed from an
expression included in the column definition.

Generated columns are supported by the 'NDB'.
storage engine beginning with MySQL NDB Cluster 7.5.3.

The following simple example shows a table that stores the lengths of
the sides of right triangles in the 'sidea' and 'sideb' columns, and
computes the length of the hypotenuse in 'sidec' (the square root of the
sums of the squares of the other sides):

     CREATE TABLE triangle (
       sidea DOUBLE,
       sideb DOUBLE,
       sidec DOUBLE AS (SQRT(sidea * sidea + sideb * sideb))
     );
     INSERT INTO triangle (sidea, sideb) VALUES(1,1),(3,4),(6,8);

Selecting from the table yields this result:

     mysql> SELECT * FROM triangle;
     +-------+-------+--------------------+
     | sidea | sideb | sidec              |
     +-------+-------+--------------------+
     |     1 |     1 | 1.4142135623730951 |
     |     3 |     4 |                  5 |
     |     6 |     8 |                 10 |
     +-------+-------+--------------------+

Any application that uses the 'triangle' table has access to the
hypotenuse values without having to specify the expression that
calculates them.

Generated column definitions have this syntax:

     COL_NAME DATA_TYPE [GENERATED ALWAYS] AS (EXPRESSION)
       [VIRTUAL | STORED] [NOT NULL | NULL]
       [UNIQUE [KEY]] [[PRIMARY] KEY]
       [COMMENT 'STRING']

'AS (EXPRESSION)' indicates that the column is generated and defines the
expression used to compute column values.  'AS' may be preceded by
'GENERATED ALWAYS' to make the generated nature of the column more
explicit.  Constructs that are permitted or prohibited in the expression
are discussed later.

The 'VIRTUAL' or 'STORED' keyword indicates how column values are
stored, which has implications for column use:

   * 'VIRTUAL': Column values are not stored, but are evaluated when
     rows are read, immediately after any 'BEFORE' triggers.  A virtual
     column takes no storage.

     'InnoDB' supports secondary indexes on virtual columns.  See
     create-table-secondary-indexes.

   * 'STORED': Column values are evaluated and stored when rows are
     inserted or updated.  A stored column does require storage space
     and can be indexed.

The default is 'VIRTUAL' if neither keyword is specified.

It is permitted to mix 'VIRTUAL' and 'STORED' columns within a table.

Other attributes may be given to indicate whether the column is indexed
or can be 'NULL', or provide a comment.

Generated column expressions must adhere to the following rules.  An
error occurs if an expression contains disallowed constructs.

   * Literals, deterministic built-in functions, and operators are
     permitted.  A function is deterministic if, given the same data in
     tables, multiple invocations produce the same result, independently
     of the connected user.  Examples of functions that fail this
     definition: 'CONNECTION_ID()', 'CURRENT_USER()', 'NOW()'.

   * Subqueries, parameters, variables, stored functions, and
     user-defined functions are not permitted.

   * A generated column definition can refer to other generated columns,
     but only those occurring earlier in the table definition.  A
     generated column definition can refer to any base (nongenerated)
     column in the table whether its definition occurs earlier or later.

   * The 'AUTO_INCREMENT' attribute cannot be used in a generated column
     definition.

   * An 'AUTO_INCREMENT' column cannot be used as a base column in a
     generated column definition.

   * As of MySQL 5.7.10, if expression evaluation causes truncation or
     provides incorrect input to a function, the 'CREATE TABLE'
     statement terminates with an error and the DDL
     operation is rejected.

If the expression evaluates to a data type that differs from the
declared column type, coercion to the declared type occurs according to
the usual MySQL type-conversion rules.  See type-conversion.

*Note*:

If any component of the expression depends on the SQL mode, different
results may occur for different uses of the table unless the SQL mode is
the same during all uses.

For 'CREATE TABLE ... LIKE', the destination
table preserves generated column information from the original table.

For 'CREATE TABLE ... SELECT', the
destination table does not preserve information about whether columns in
the selected-from table are generated columns.  The 'SELECT'
part of the statement cannot assign values to generated columns
in the destination table.

Partitioning by generated columns is permitted.  See
create-table-partitioning.

A foreign key constraint on a stored generated column cannot use 'ON
UPDATE CASCADE', 'ON DELETE SET NULL', 'ON UPDATE SET NULL', 'ON DELETE
SET DEFAULT', or 'ON UPDATE SET DEFAULT'.

A foreign key constraint cannot reference a virtual generated column.

For 'InnoDB' restrictions related to foreign keys and generated columns,
see innodb-foreign-key-constraints.

Triggers cannot use 'NEW.COL_NAME' or use 'OLD.COL_NAME' to refer to
generated columns.

For 'INSERT', 'REPLACE', and
'UPDATE', if a generated column is inserted into, replaced, or
updated explicitly, the only permitted value is 'DEFAULT'.

A generated column in a view is considered updatable because it is
possible to assign to it.  However, if such a column is updated
explicitly, the only permitted value is 'DEFAULT'.

Generated columns have several use cases, such as these:

   * Virtual generated columns can be used as a way to simplify and
     unify queries.  A complicated condition can be defined as a
     generated column and referred to from multiple queries on the table
     to ensure that all of them use exactly the same condition.

   * Stored generated columns can be used as a materialized cache for
     complicated conditions that are costly to calculate on the fly.

   * Generated columns can simulate functional indexes: Use a stored
     column to define a functional expression and index it.  This can be
     useful for working with columns of types that cannot be indexed
     directly, such as 'JSON' columns; see
     json-column-indirect-index, for a detailed example.

     The disadvantage of such an approach is that values are stored
     twice; once as the value of the generated column and once in the
     index.

   * If a generated column is indexed, the optimizer recognizes query
     expressions that match the column definition and uses indexes from
     the column as appropriate during query execution, even if a query
     does not refer to the column directly by name.  For details, see
     generated-column-index-optimizations.

Example:

Suppose that a table 't1' contains 'first_name' and 'last_name' columns
and that applications frequently construct the full name using an
expression like this:

     SELECT CONCAT(first_name,' ',last_name) AS full_name FROM t1;

One way to avoid writing out the expression is to create a view 'v1' on
't1', which simplifies applications by enabling them to select
'full_name' directly without using an expression:

     CREATE VIEW v1 AS
     SELECT *, CONCAT(first_name,' ',last_name) AS full_name FROM t1;

     SELECT full_name FROM v1;

A generated column also enables applications to select 'full_name'
directly without the need to define a view:

     CREATE TABLE t1 (
       first_name VARCHAR(10),
       last_name VARCHAR(10),
       full_name VARCHAR(255) AS (CONCAT(first_name,' ',last_name))
     );

     SELECT full_name FROM t1;

13.1.18.9 Secondary Indexes and Generated Columns
.................................................

'InnoDB' supports secondary indexes on virtual generated columns.  Other
index types are not supported.  A secondary index defined on a virtual
column is sometimes referred to as a 'virtual index'.

A secondary index may be created on one or more virtual columns or on a
combination of virtual columns and regular columns or stored generated
columns.  Secondary indexes that include virtual columns may be defined
as 'UNIQUE'.

When a secondary index is created on a virtual generated column,
generated column values are materialized in the records of the index.
If the index is a covering index (one that includes all the columns
retrieved by a query), generated column values are retrieved from
materialized values in the index structure instead of computed 'on the
fly'.

There are additional write costs to consider when using a secondary
index on a virtual column due to computation performed when
materializing virtual column values in secondary index records during
'INSERT' and 'UPDATE' operations.  Even
with additional write costs, secondary indexes on virtual columns may be
preferable to generated _stored_ columns, which are materialized in the
clustered index, resulting in larger tables that require more disk space
and memory.  If a secondary index is not defined on a virtual column,
there are additional costs for reads, as virtual column values must be
computed each time the column's row is examined.

Values of an indexed virtual column are MVCC-logged to avoid unnecessary
recomputation of generated column values during rollback or during a
purge operation.  The data length of logged values is limited by the
index key limit of 767 bytes for 'COMPACT' and 'REDUNDANT' row formats,
and 3072 bytes for 'DYNAMIC' and 'COMPRESSED' row formats.

Adding or dropping a secondary index on a virtual column is an in-place
operation.

Prior to 5.7.16, a foreign key constraint cannot reference a secondary
index defined on a virtual generated column.

In MySQL 5.7.13 and earlier, 'InnoDB' does not permit defining a foreign
key constraint with a cascading referential action on the base column of
an indexed generated virtual column.  This restriction is lifted in
MySQL 5.7.14.

*Indexing a Generated Column to Provide a JSON Column Index*

As noted elsewhere, see 'JSON' columns cannot be indexed
directly.  To create an index that references such a column indirectly,
you can define a generated column that extracts the information that
should be indexed, then create an index on the generated column, as
shown in this example:

     mysql> CREATE TABLE jemp (
         ->     c JSON,
         ->     g INT GENERATED ALWAYS AS (c->"$.id"),
         ->     INDEX i (g)
         -> );
     Query OK, 0 rows affected (0.28 sec)

     mysql> INSERT INTO jemp (c) VALUES
          >   ('{"id": "1", "name": "Fred"}'), ('{"id": "2", "name": "Wilma"}'),
          >   ('{"id": "3", "name": "Barney"}'), ('{"id": "4", "name": "Betty"}');
     Query OK, 4 rows affected (0.04 sec)
     Records: 4  Duplicates: 0  Warnings: 0

     mysql> SELECT c->>"$.name" AS name
          >     FROM jemp WHERE g > 2;
     +--------+
     | name   |
     +--------+
     | Barney |
     | Betty  |
     +--------+
     2 rows in set (0.00 sec)

     mysql> EXPLAIN SELECT c->>"$.name" AS name
          >    FROM jemp WHERE g > 2\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: jemp
        partitions: NULL
              type: range
     possible_keys: i
               key: i
           key_len: 5
               ref: NULL
              rows: 2
          filtered: 100.00
             Extra: Using where
     1 row in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Note
        Code: 1003
     Message: /* select#1 */ select json_unquote(json_extract(`test`.`jemp`.`c`,'$.name'))
     AS `name` from `test`.`jemp` where (`test`.`jemp`.`g` > 2)
     1 row in set (0.00 sec)

(We have wrapped the output from the last statement in this example to
fit the viewing area.)

The '->' operator is supported in MySQL 5.7.9 and later.  The '->>'
operator is supported beginning with MySQL 5.7.13.

When you use 'EXPLAIN' on a 'SELECT' or
other SQL statement containing one or more expressions that use the '->'
or '->>' operator, these expressions are translated into their
equivalents using 'JSON_EXTRACT()' and (if needed) 'JSON_UNQUOTE()'
instead, as shown here in the output from 'SHOW WARNINGS'
immediately following this 'EXPLAIN' statement:

     mysql> EXPLAIN SELECT c->>"$.name"
          > FROM jemp WHERE g > 2 ORDER BY c->"$.name"\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: jemp
        partitions: NULL
              type: range
     possible_keys: i
               key: i
           key_len: 5
               ref: NULL
              rows: 2
          filtered: 100.00
             Extra: Using where; Using filesort
     1 row in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Note
        Code: 1003
     Message: /* select#1 */ select json_unquote(json_extract(`test`.`jemp`.`c`,'$.name')) AS
     `c->>"$.name"` from `test`.`jemp` where (`test`.`jemp`.`g` > 2) order by
     json_extract(`test`.`jemp`.`c`,'$.name')
     1 row in set (0.00 sec)

See the descriptions of the '->' and '->>' operators, as well as those
of the 'JSON_EXTRACT()' and 'JSON_UNQUOTE()' functions, for additional
information and examples.

This technique also can be used to provide indexes that indirectly
reference columns of other types that cannot be indexed directly, such
as 'GEOMETRY' columns.

*JSON columns and indirect indexing in NDB Cluster*

It is also possible to use indirect indexing of JSON columns in MySQL
NDB Cluster 7.5.3 and later, subject to the following conditions:

  1. 'NDB' handles a 'JSON' column
     value internally as a 'BLOB'.  This means that any
     'NDB' table having one or more JSON columns must have a primary
     key, else it cannot be recorded in the binary log.

  2. The 'NDB' storage engine does not support
     indexing of virtual columns.  Since the default for generated
     columns is 'VIRTUAL', you must specify explicitly the generated
     column to which to apply the indirect index as 'STORED'.

The CREATE TABLE statement used to create the table 'jempn' shown here
is a version of the 'jemp' table shown previously, with modifications
making it compatible with 'NDB':

     CREATE TABLE jempn (
       a BIGINT(20) NOT NULL AUTO_INCREMENT PRIMARY KEY,
       c JSON DEFAULT NULL,
       g INT GENERATED ALWAYS AS (c->"$.name") STORED,
       INDEX i (g)
     ) ENGINE=NDB;

We can populate this table using the following 'INSERT'.
statement:

     INSERT INTO jempn (a, c) VALUES
       (NULL, '{"id": "1", "name": "Fred"}'),
       (NULL, '{"id": "2", "name": "Wilma"}'),
       (NULL, '{"id": "3", "name": "Barney"}'),
       (NULL, '{"id": "4", "name": "Betty"}');

Now 'NDB' can use index 'i', as shown here:

     mysql> EXPLAIN SELECT c->>"$.name" AS name
               FROM jempn WHERE g > 2\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: jempn
        partitions: p0,p1
              type: range
     possible_keys: i
               key: i
           key_len: 5
               ref: NULL
              rows: 3
          filtered: 100.00
             Extra: Using where with pushed condition (`test`.`jempn`.`g` > 2)
     1 row in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Note
        Code: 1003
     Message: /* select#1 */ select
     json_unquote(json_extract(`test`.`jempn`.`c`,'$.name')) AS `name` from
     `test`.`jempn` where (`test`.`jempn`.`g` > 2)
     1 row in set (0.00 sec)

You should keep in mind that a stored generated column uses
'DataMemory', and that an index on such a column uses 'IndexMemory'.

13.1.18.10 Setting NDB_TABLE Options
....................................

In MySQL NDB Cluster 7.5.2 and later, the table comment in a 'CREATE
TABLE' or 'ALTER TABLE' statement can also be used
to specify an 'NDB_TABLE' option, which consists of one or more
name-value pairs, separated by commas if need be, following the string
'NDB_TABLE='.  Complete syntax for names and values syntax is shown
here:

     COMMENT="NDB_TABLE=NDB_TABLE_OPTION[,NDB_TABLE_OPTION[,...]]"

     NDB_TABLE_OPTION:
         NOLOGGING={1|0}
       | READ_BACKUP={1|0}
       | PARTITION_BALANCE={FOR_RP_BY_NODE|FOR_RA_BY_NODE|FOR_RP_BY_LDM
                           |FOR_RA_BY_LDM|FOR_RA_BY_LDM_X_2
                           |FOR_RA_BY_LDM_X_3|FOR_RA_BY_LDM_X_4}
       | FULLY_REPLICATED={1|0}

Spaces are not permitted within the quoted string.  The string is
case-insensitive.

The four 'NDB' table options that can be set as part of a comment in
this way are described in more detail in the next few paragraphs.

'NOLOGGING': Using 1 corresponds to having 'ndb_table_no_logging'
enabled, but has no actual effect.  Provided as a placeholder, mostly
for completeness of 'ALTER TABLE' statements.

'READ_BACKUP': Setting this option to 1 has the same effect as though
'ndb_read_backup' were enabled; enables reading from any replica.
Starting with MySQL NDB Cluster 7.5.3, you can set 'READ_BACKUP' for an
existing table online (Bug #80858, Bug #23001617), using an 'ALTER
TABLE' statement similar to one of those shown here:

     ALTER TABLE ... ALGORITHM=INPLACE, COMMENT="NDB_TABLE=READ_BACKUP=1";

     ALTER TABLE ... ALGORITHM=INPLACE, COMMENT="NDB_TABLE=READ_BACKUP=0";

Prior to MySQL NDB Cluster 7.5.4, setting 'READ_BACKUP' to 1 also caused
'FRAGMENT_COUNT_TYPE' to be set to 'ONE_PER_LDM_PER_NODE_GROUP'.

For more information about the 'ALGORITHM' option for 'ALTER TABLE', see
alter-table-online-operations.

'PARTITION_BALANCE': Provides additional control over assignment and
placement of partitions.  The following four schemes are supported:

  1. 'FOR_RP_BY_NODE': One partition per node.

     Only one LDM on each node stores a primary partition.  Each
     partition is stored in the same LDM (same ID) on all nodes.

  2. 'FOR_RA_BY_NODE': One partition per node group.

     Each node stores a single partition, which can be either a primary
     replica or a backup replica.  Each partition is stored in the same
     LDM on all nodes.

  3. 'FOR_RP_BY_LDM': One partition for each LDM on each node; the
     default.

     This is the same behavior as prior to MySQL NDB Cluster 7.5.2,
     except for a slightly different mapping of partitions to LDMs,
     starting with LDM 0 and placing one partition per node group, then
     moving on to the next LDM.

     In MySQL NDB Cluster 7.5.4 and later, this is the setting used if
     'READ_BACKUP' is set to 1.  (Bug #82634, Bug #24482114)

  4. 'FOR_RA_BY_LDM': One partition per LDM in each node group.

     These partitions can be primary or backup partitions.

     Prior to MySQL NDB Cluster 7.5.4, this was the setting used if
     'READ_BACKUP' was set to 1.

  5. 'FOR_RA_BY_LDM_X_2': Two partitions per LDM in each node group.

     These partitions can be primary or backup partitions.

     This setting was added in NDB 7.5.4.

  6. 'FOR_RA_BY_LDM_X_3': Three partitions per LDM in each node group.

     These partitions can be primary or backup partitions.

     This setting was added in NDB 7.5.4.

  7. 'FOR_RA_BY_LDM_X_4': Four partitions per LDM in each node group.

     These partitions can be primary or backup partitions.

     This setting was added in NDB 7.5.4.

Beginning with NDB 7.5.4, 'PARTITION_BALANCE' is the preferred interface
for setting the number of partitions per table.  Using 'MAX_ROWS' to
force the number of partitions is deprecated as of NDB 7.5.4, continues
to be supported in NDB 7.6 for backward compatibility, but is subject to
removal in a future release of MySQL NDB Cluster.  (Bug #81759, Bug
#23544301)

Prior to MySQL NDB Cluster 7.5.4, 'PARTITION_BALANCE' was named
'FRAGMENT_COUNT_TYPE', and accepted as its value one of (in the same
order as that of the listing just shown) 'ONE_PER_NODE',
'ONE_PER_NODE_GROUP', 'ONE_PER_LDM_PER_NODE', or
'ONE_PER_LDM_PER_NODE_GROUP'.  (Bug #81761, Bug #23547525)

'FULLY_REPLICATED' controls whether the table is fully replicated, that
is, whether each data node has a complete copy of the table.  To enable
full replication of the table, use 'FULLY_REPLICATED=1'.

This setting can also be controlled using the 'ndb_fully_replicated'
system variable.  Setting it to 'ON' enables the option by default for
all new 'NDB' tables; the default is 'OFF', which maintains the previous
behavior (as in MySQL NDB Cluster 7.5.1 and earlier, before support for
fully replicated tables was introduced).  The 'ndb_data_node_neighbour'
system variable is also used for fully replicated tables, to ensure that
when a fully replicated table is accessed, we access the data node which
is local to this MySQL Server.

An example of a 'CREATE TABLE' statement using such a comment when
creating an 'NDB' table is shown here:

     mysql> CREATE TABLE t1 (
          >     c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
          >     c2 VARCHAR(100),
          >     c3 VARCHAR(100) )
          > ENGINE=NDB
          >
     COMMENT="NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE";

The comment is displayed as part of the ouput of 'SHOW CREATE TABLE'.
The text of the comment is also available
from querying the MySQL Information Schema 'TABLES'.
table, as in this example:

     mysql> SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
          > FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1";
     +------------+--------------+----------------------------------------------------------+
     | TABLE_NAME | TABLE_SCHEMA | TABLE_COMMENT                                            |
     +------------+--------------+----------------------------------------------------------+
     | t1         | c            | NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE |
     | t1         | d            |                                                          |
     +------------+--------------+----------------------------------------------------------+
     2 rows in set (0.00 sec)

This comment syntax is also supported with 'ALTER TABLE'
statements for 'NDB' tables.  Keep in mind that a table
comment used with 'ALTER TABLE' replaces any existing comment which the
table might have.

     mysql> ALTER TABLE t1 COMMENT="NDB_TABLE=PARTITION_BALANCE=FOR_RA_BY_NODE";
     Query OK, 0 rows affected (0.40 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
          > FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1";
     +------------+--------------+--------------------------------------------------+
     | TABLE_NAME | TABLE_SCHEMA | TABLE_COMMENT                                    |
     +------------+--------------+--------------------------------------------------+
     | t1         | c            | NDB_TABLE=PARTITION_BALANCE=FOR_RA_BY_NODE       |
     | t1         | d            |                                                  |
     +------------+--------------+--------------------------------------------------+
     2 rows in set (0.01 sec)

You can also see the value of the 'PARTITION_BALANCE' option in the
output of 'ndb_desc'.
'ndb_desc' also shows whether the
'READ_BACKUP' and 'FULLY_REPLICATED' options are set for the table.  See
the description of this program for more information.

Because the 'READ_BACKUP' value was not carried over to the new comment
set by the 'ALTER TABLE' statement, there is no longer a way using SQL
to retrieve the value previously set for it.  To keep this from
happening, it is suggested that you preserve any such values from the
existing comment string, like this:

     mysql> SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
          > FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1";
     +------------+--------------+----------------------------------------------------------+
     | TABLE_NAME | TABLE_SCHEMA | TABLE_COMMENT                                            |
     +------------+--------------+----------------------------------------------------------+
     | t1         | c            | NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE |
     | t1         | d            |                                                          |
     +------------+--------------+----------------------------------------------------------+
     2 rows in set (0.00 sec)

     mysql> ALTER TABLE t1 COMMENT="NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RA_BY_NODE";
     Query OK, 0 rows affected (1.56 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
          > FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1";
     +------------+--------------+----------------------------------------------------------------+
     | TABLE_NAME | TABLE_SCHEMA | TABLE_COMMENT                                                  |
     +------------+--------------+----------------------------------------------------------------+
     | t1         | c            | NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RA_BY_NODE       |
     | t1         | d            |                                                                |
     +------------+--------------+----------------------------------------------------------------+
     2 rows in set (0.01 sec)

13.1.19 CREATE TABLESPACE Syntax
--------------------------------

   * create-tablespace-innodb

   * create-tablespace-ndb

   * create-tablespace-options

   * create-tablespace-notes

   * create-tablespace-innodb-examples

   * create-tablespace-ndb-examples

     CREATE TABLESPACE TABLESPACE_NAME

       _InnoDB and NDB:_
         ADD DATAFILE 'FILE_NAME'

       _InnoDB only:_
         [FILE_BLOCK_SIZE = value]

       _NDB only:_
         USE LOGFILE GROUP LOGFILE_GROUP
         [EXTENT_SIZE [=] EXTENT_SIZE]
         [INITIAL_SIZE [=] INITIAL_SIZE]
         [AUTOEXTEND_SIZE [=] AUTOEXTEND_SIZE]
         [MAX_SIZE [=] MAX_SIZE]
         [NODEGROUP [=] NODEGROUP_ID]
         [WAIT]
         [COMMENT [=] 'STRING']

       _InnoDB and NDB:_
         [ENGINE [=] ENGINE_NAME]

This statement is used to create a tablespace.  The precise syntax and
semantics depend on the storage engine used.  In standard MySQL 5.7
releases, this is always an 'InnoDB'.
tablespace.  MySQL NDB Cluster 7.5 also supports tablespaces using the
'NDB' storage engine in addition to those using
'InnoDB'.

*Considerations for InnoDB*

An 'InnoDB' tablespace created using 'CREATE TABLESPACE' is referred to
as a _general tablespace_.  This is a shared tablespace, similar to the
system tablespace.  It can hold multiple tables, and supports all table
row formats.  General tablespaces can be created in a location relative
to or independent of the MySQL data directory.

After creating an 'InnoDB' general tablespace, you can use 'CREATE TABLE TBL_NAME ... TABLESPACE [=] TABLESPACE_NAME'
or
'ALTER TABLE TBL_NAME TABLESPACE [=] TABLESPACE_NAME'
to add tables to the tablespace.

For more information, see general-tablespaces.

*Considerations for NDB Cluster*

This statement is used to create a tablespace, which can contain one or
more data files, providing storage space for NDB Cluster Disk Data
tables (see mysql-cluster-disk-data).  One data file is created
and added to the tablespace using this statement.  Additional data files
may be added to the tablespace by using the 'ALTER TABLESPACE'
statement (see alter-tablespace).

*Note*:

All NDB Cluster Disk Data objects share the same namespace.  This means
that _each Disk Data object_ must be uniquely named (and not merely each
Disk Data object of a given type).  For example, you cannot have a
tablespace and a log file group with the same name, or a tablespace and
a data file with the same name.

A log file group of one or more 'UNDO' log files must be assigned to the
tablespace to be created with the 'USE LOGFILE GROUP' clause.
LOGFILE_GROUP must be an existing log file group created with
'CREATE LOGFILE GROUP'. (see
create-logfile-group).  Multiple tablespaces may use the same log file
group for 'UNDO' logging.

When setting 'EXTENT_SIZE' or 'INITIAL_SIZE', you may optionally follow
the number with a one-letter abbreviation for an order of magnitude,
similar to those used in 'my.cnf'.  Generally, this is one of the
letters 'M' (for megabytes) or 'G' (for gigabytes).

'INITIAL_SIZE' and 'EXTENT_SIZE' are subject to rounding as follows:

   * 'EXTENT_SIZE' is rounded up to the nearest whole multiple of 32K.

   * 'INITIAL_SIZE' is rounded _down_ to the nearest whole multiple of
     32K; this result is rounded up to the nearest whole multiple of
     'EXTENT_SIZE' (after any rounding).

The rounding just described is done explicitly, and a warning is issued
by the MySQL Server when any such rounding is performed.  The rounded
values are also used by the NDB kernel for calculating
'INFORMATION_SCHEMA.FILES' column values and other
purposes.  However, to avoid an unexpected result, we suggest that you
always use whole multiples of 32K in specifying these options.

When 'CREATE TABLESPACE' is used with 'ENGINE
[=] NDB', a tablespace and associated data file are created on each
Cluster data node.  You can verify that the data files were created and
obtain information about them by querying the
'INFORMATION_SCHEMA.FILES' table.  (See the example later
in this section.)

(See files-table.)

*Options*

   * 'ADD DATAFILE': Defines the name of a tablespace data file; this
     option is always required.  An 'InnoDB' tablespace supports only a
     single data file, whose name must include a '.ibd' extension.  An
     NDB Cluster tablespace supports multiple data files which can have
     any legal file names; more data files can be added to an NDB
     Cluster tablespace following its creation by using an 'ALTER TABLESPACE'
     statement.

     *Note*:

     'ALTER TABLESPACE' is not supported by 'InnoDB'.

     To place the data file in a location outside of the MySQL data
     directory ('datadir'), include an absolute directory path or a path
     relative to the MySQL data directory.  If you do not specify a
     path, the tablespace is created in the MySQL data directory.  An
     isl file is created in the MySQL data directory when an 'InnoDB'
     tablespace is created outside of the MySQL data directory.

     To avoid conflicts with implicitly created file-per-table
     tablespaces, creating a general tablespace in a subdirectory under
     the MySQL data directory is not supported.  Also, when creating a
     general tablespace outside of the MySQL data directory, the
     directory must exist prior to creating the tablespace.

     The 'FILE_NAME', including the path (optional), must be quoted with
     single or double quotations marks.  File names (not counting any
     '.ibd' extension for 'InnoDB' files) and directory names must be at
     least one byte in length.  Zero length file names and directory
     names are not supported.

   * 'FILE_BLOCK_SIZE': This option--which is specific to 'InnoDB', and
     is ignored by 'NDB'--defines the block size for the tablespace data
     file.  If you do not specify this option, 'FILE_BLOCK_SIZE'
     defaults to 'innodb_page_size'.  'FILE_BLOCK_SIZE' is required when
     you intend to use the tablespace for storing compressed 'InnoDB'
     tables ('ROW_FORMAT=COMPRESSED').

     If 'FILE_BLOCK_SIZE' is equal 'innodb_page_size', the tablespace
     can contain only tables having an uncompressed row format
     ('COMPACT', 'REDUNDANT', or 'DYNAMIC').  The physical page size for
     tables using 'COMPRESSED' differs from that of uncompressed tables;
     this means that compressed tables and uncompressed tables cannot
     coexist in the same tablespace.

     For a general tablespace to contain compressed tables,
     'FILE_BLOCK_SIZE' must be specified, and the 'FILE_BLOCK_SIZE'
     value must be a valid compressed page size in relation to the
     'innodb_page_size' value.  Also, the physical page size of the
     compressed table ('KEY_BLOCK_SIZE') must be equal to
     'FILE_BLOCK_SIZE/1024'.  For example, if 'innodb_page_size=16K',
     and 'FILE_BLOCK_SIZE=8K', the 'KEY_BLOCK_SIZE' of the table must be
     8.  For more information, see general-tablespaces.

   * 'USE LOGFILE GROUP': Required for 'NDB', this is the name of a log
     file group previously created using 'CREATE LOGFILE GROUP'.
     Not supported for 'InnoDB', where it fails
     with an error.

   * 'EXTENT_SIZE': This option is specific to NDB, and is not supported
     by InnoDB, where it fails with an error.  'EXTENT_SIZE' sets the
     size, in bytes, of the extents used by any files belonging to the
     tablespace.  The default value is 1M. The minimum size is 32K, and
     theoretical maximum is 2G, although the practical maximum size
     depends on a number of factors.  In most cases, changing the extent
     size does not have any measurable effect on performance, and the
     default value is recommended for all but the most unusual
     situations.

     An _extent_ is a unit of disk space allocation.  One extent is
     filled with as much data as that extent can contain before another
     extent is used.  In theory, up to 65,535 (64K) extents may used per
     data file; however, the recommended maximum is 32,768 (32K). The
     recommended maximum size for a single data file is 32G--that is,
     32K extents x 1 MB per extent.  In addition, once an extent is
     allocated to a given partition, it cannot be used to store data
     from a different partition; an extent cannot store data from more
     than one partition.  This means, for example that a tablespace
     having a single datafile whose 'INITIAL_SIZE' (described in the
     following item) is 256 MB and whose 'EXTENT_SIZE' is 128M has just
     two extents, and so can be used to store data from at most two
     different disk data table partitions.

     You can see how many extents remain free in a given data file by
     querying the 'INFORMATION_SCHEMA.FILES' table,
     and so derive an estimate for how much space remains free in the
     file.  For further discussion and examples, see
     files-table.

   * 'INITIAL_SIZE': This option is specific to 'NDB', and is not
     supported by 'InnoDB', where it fails with an error.

     The 'INITIAL_SIZE' parameter sets the total size in bytes of the
     data file that was specific using 'ADD DATATFILE'.  Once this file
     has been created, its size cannot be changed; however, you can add
     more data files to the tablespace using 'ALTER TABLESPACE ... ADD DATAFILE'.

     'INITIAL_SIZE' is optional; its default value is 134217728 (128
     MB).

     On 32-bit systems, the maximum supported value for 'INITIAL_SIZE'
     is 4294967296 (4 GB).

   * 'AUTOEXTEND_SIZE': Currently ignored by MySQL; reserved for
     possible future use.  Has no effect in any release of MySQL 5.7 or
     MySQL NDB Cluster 7.5, regardless of the storage engine used.

   * 'MAX_SIZE': Currently ignored by MySQL; reserved for possible
     future use.  Has no effect in any release of MySQL 5.7 or MySQL NDB
     Cluster 7.5, regardless of the storage engine used.

   * 'NODEGROUP': Currently ignored by MySQL; reserved for possible
     future use.  Has no effect in any release of MySQL 5.7 or MySQL NDB
     Cluster 7.5, regardless of the storage engine used.

   * 'WAIT': Currently ignored by MySQL; reserved for possible future
     use.  Has no effect in any release of MySQL 5.7 or MySQL NDB
     Cluster 7.5, regardless of the storage engine used.

   * 'COMMENT': Currently ignored by MySQL; reserved for possible future
     use.  Has no effect in any release of MySQL 5.7 or MySQL NDB
     Cluster 7.5, regardless of the storage engine used.

   * 'ENGINE': Defines the storage engine which uses the tablespace,
     where ENGINE_NAME is the name of the storage engine.  Currently,
     only the 'InnoDB' storage engine is supported by standard MySQL 5.7
     releases.  MySQL NDB Cluster 7.5 supports both 'NDB' and 'InnoDB'
     tablespaces.  The value of the 'default_storage_engine' system
     variable is used for 'ENGINE' if the option is not specified.

*Notes*

   * For the rules covering the naming of MySQL tablespaces, see
     identifiers.  In addition to these rules, the slash character
     ('/') is not permitted, nor can you use names beginning with
     'innodb_', as this prefix is reserved for system use.

   * Tablespaces do not support temporary tables.

   * The 'TABLESPACE' option may be used with 'CREATE TABLE'
     or 'ALTER TABLE' to assign
     'InnoDB' table partitions or subpartitions to a general tablespace,
     a separate file-per-table tablespace, or the system tablespace.
     'TABLESPACE' option support for table partitions and subpartitions
     was added in MySQL 5.7.  All partitions must belong to the same
     storage engine.  For more information, see
     general-tablespaces.

   * 'innodb_file_per_table', 'innodb_file_format', and
     'innodb_file_format_max' settings have no influence on 'CREATE
     TABLESPACE' operations.  'innodb_file_per_table' does not need to
     be enabled.  General tablespaces support all table row formats
     regardless of file format settings.  Likewise, general tablespaces
     support the addition of tables of any row format using
     'CREATE TABLE ... TABLESPACE', regardless of file
     format settings.

   * 'innodb_strict_mode' is not applicable to general tablespaces.
     Tablespace management rules are strictly enforced independently of
     'innodb_strict_mode'.  If 'CREATE TABLESPACE' parameters are
     incorrect or incompatible, the operation fails regardless of the
     'innodb_strict_mode' setting.  When a table is added to a general
     tablespace using 'CREATE TABLE ... TABLESPACE'.
     or 'ALTER TABLE ... TABLESPACE',
     'innodb_strict_mode' is ignored but the statement is evaluated as
     if 'innodb_strict_mode' is enabled.

   * Use 'DROP TABLESPACE' to remove a tablespace.  All tables must be
     dropped from a tablespace using 'DROP TABLE'.
     prior to dropping the tablespace.  Before dropping an NDB Cluster
     tablespace you must also remove all its data files using one or
     more 'ALTER TABLESPACE ... DROP DATATFILE'.
     statements.  See mysql-cluster-disk-data-objects.

   * All parts of an 'InnoDB' table added to an 'InnoDB' general
     tablespace reside in the general tablespace, including indexes and
     'BLOB' pages.

     For an 'NDB' table assigned to a tablespace, only those columns
     which are not indexed are stored on disk, and actually use the
     tablespace data files.  Indexes and indexed columns for all 'NDB'
     tables are always kept in memory.

   * Similar to the system tablespace, truncating or dropping tables
     stored in a general tablespace creates free space internally in the
     general tablespace .ibd data file which can only be used for new
     'InnoDB' data.  Space is not released back to the operating system
     as it is for file-per-table tablespaces.

   * A general tablespace is not associated with any database or schema.

   * 'ALTER TABLE ... DISCARD TABLESPACE' and
     'ALTER TABLE ...IMPORT TABLESPACE' are not supported
     for tables that belong to a general tablespace.

   * The server uses tablespace-level metadata locking for DDL that
     references general tablespaces.  By comparison, the server uses
     table-level metadata locking for DDL that references file-per-table
     tablespaces.

   * A generated or existing tablespace cannot be changed to a general
     tablespace.

   * Tables stored in a general tablespace can only be opened in MySQL
     5.7.6 or later due to the addition of new table flags.

   * There is no conflict between general tablespace names and
     file-per-table tablespace names.  The '/' character, which is
     present in file-per-table tablespace names, is not permitted in
     general tablespace names.

*InnoDB Examples*

This example demonstrates creating a general tablespace and adding three
uncompressed tables of different row formats.

     mysql> CREATE TABLESPACE `ts1`
         ->     ADD DATAFILE 'ts1.ibd'
         ->     ENGINE=INNODB;
     Query OK, 0 rows affected (0.01 sec)

     mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY)
         ->     TABLESPACE ts1
         ->     ROW_FORMAT=REDUNDANT;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t2 (c1 INT PRIMARY KEY)
         ->     TABLESPACE ts1
         ->     ROW_FORMAT=COMPACT;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t3 (c1 INT PRIMARY KEY)
         ->     TABLESPACE ts1
         ->     ROW_FORMAT=DYNAMIC;
     Query OK, 0 rows affected (0.00 sec)

This example demonstrates creating a general tablespace and adding a
compressed table.  The example assumes a default 'innodb_page_size' of
16K. The 'FILE_BLOCK_SIZE' of 8192 requires that the compressed table
have a 'KEY_BLOCK_SIZE' of 8.

     mysql> CREATE TABLESPACE `ts2`
         ->   ADD DATAFILE 'ts2.ibd'
         ->   FILE_BLOCK_SIZE = 8192
         ->   ENGINE=INNODB;
     Query OK, 0 rows affected (0.01 sec)

     mysql> CREATE TABLE t4 (c1 INT PRIMARY KEY)
         ->   TABLESPACE ts2
         ->   ROW_FORMAT=COMPRESSED
         ->   KEY_BLOCK_SIZE=8;
     Query OK, 0 rows affected (0.00 sec)

*NDB Example*

Suppose that you wish to create an NDB Cluster Disk Data tablespace
named 'myts' using a datafile named 'mydata-1.dat'.  An 'NDB' tablespace
always requires the use of a log file group consisting of one or more
undo log files.  For this example, we first create a log file group
named 'mylg' that contains one undo long file named 'myundo-1.dat',
using the 'CREATE LOGFILE GROUP' statement
shown here:

     mysql> CREATE LOGFILE GROUP myg1
         ->     ADD UNDOFILE 'myundo-1.dat'
         ->     ENGINE=NDB;
     Query OK, 0 rows affected (3.29 sec)

Now you can create the tablespace previously described using the
following statement:

     mysql> CREATE TABLESPACE myts
         ->     ADD DATAFILE 'mydata-1.dat'
         ->     USE LOGFILE GROUP mylg
         ->     ENGINE=NDB;
     Query OK, 0 rows affected (2.98 sec)

You can now create a Disk Data table using a 'CREATE TABLE'
statement with the 'TABLESPACE' and 'STORAGE DISK'
options, similar to what is shown here:

     mysql> CREATE TABLE mytable (
         ->     id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
         ->     lname VARCHAR(50) NOT NULL,
         ->     fname VARCHAR(50) NOT NULL,
         ->     dob DATE NOT NULL,
         ->     joined DATE NOT NULL,
         ->     INDEX(last_name, first_name)
         -> )
         ->     TABLESPACE myts STORAGE DISK
         ->     ENGINE=NDB;
     Query OK, 0 rows affected (1.41 sec)

It is important to note that only the 'dob' and 'joined' columns from
'mytable' are actually stored on disk, due to the fact that the 'id',
'lname', and 'fname' columns are all indexed.

As mentioned previously, when 'CREATE TABLESPACE' is used with 'ENGINE
[=] NDB', a tablespace and associated data file are created on each NDB
Cluster data node.  You can verify that the data files were created and
obtain information about them by querying the
'INFORMATION_SCHEMA.FILES' table, as shown here:

     mysql> SELECT FILE_NAME, FILE_TYPE, LOGFILE_GROUP_NAME, STATUS, EXTRA
         ->     FROM INFORMATION_SCHEMA.FILES
         ->     WHERE TABLESPACE_NAME = 'myts';

     +--------------+------------+--------------------+--------+----------------+
     | file_name    | file_type  | logfile_group_name | status | extra          |
     +--------------+------------+--------------------+--------+----------------+
     | mydata-1.dat | DATAFILE   | mylg               | NORMAL | CLUSTER_NODE=5 |
     | mydata-1.dat | DATAFILE   | mylg               | NORMAL | CLUSTER_NODE=6 |
     | NULL         | TABLESPACE | mylg               | NORMAL | NULL           |
     +--------------+------------+--------------------+--------+----------------+
     3 rows in set (0.01 sec)

For additional information and examples, see
mysql-cluster-disk-data-objects.

13.1.20 CREATE TRIGGER Syntax
-----------------------------

     CREATE
         [DEFINER = { USER | CURRENT_USER }]
         TRIGGER TRIGGER_NAME
         TRIGGER_TIME TRIGGER_EVENT
         ON TBL_NAME FOR EACH ROW
         [TRIGGER_ORDER]
         TRIGGER_BODY

     TRIGGER_TIME: { BEFORE | AFTER }

     TRIGGER_EVENT: { INSERT | UPDATE | DELETE }

     TRIGGER_ORDER: { FOLLOWS | PRECEDES } OTHER_TRIGGER_NAME

This statement creates a new trigger.  A trigger is a named database
object that is associated with a table, and that activates when a
particular event occurs for the table.  The trigger becomes associated
with the table named TBL_NAME, which must refer to a permanent table.
You cannot associate a trigger with a 'TEMPORARY' table or a view.

Trigger names exist in the schema namespace, meaning that all triggers
must have unique names within a schema.  Triggers in different schemas
can have the same name.

This section describes 'CREATE TRIGGER' syntax.
For additional discussion, see trigger-syntax.

'CREATE TRIGGER' requires the 'TRIGGER' privilege
for the table associated with the trigger.  The statement might also
require the 'SUPER' privilege, depending on the 'DEFINER' value, as
described later in this section.  If binary logging is enabled, see
'CREATE TRIGGER' might require the 'SUPER' privilege,
as described in stored-programs-logging.

The 'DEFINER' clause determines the security context to be used when
checking access privileges at trigger activation time, as described
later in this section.

TRIGGER_TIME is the trigger action time.  It can be 'BEFORE' or 'AFTER'
to indicate that the trigger activates before or after each row to be
modified.

Basic column value checks occur prior to trigger activation, so you
cannot use 'BEFORE' triggers to convert values inappropriate for the
column type to valid values.

TRIGGER_EVENT indicates the kind of operation that activates the
trigger.  These TRIGGER_EVENT values are permitted:

   * 'INSERT'.: The trigger activates whenever a new row
     is inserted into the table; for example, through 'INSERT',
     see 'LOAD DATA', and 'REPLACE'.
     statements.

   * 'UPDATE'.: The trigger activates whenever a row is
     modified; for example, through 'UPDATE' statements.

   * 'DELETE'.: The trigger activates whenever a row is
     deleted from the table; for example, through 'DELETE'
     and 'REPLACE' statements.  'DROP TABLE'
     and 'TRUNCATE TABLE'.
     statements on the table do _not_ activate this trigger, because
     they do not use 'DELETE'.  Dropping a partition does
     not activate 'DELETE' triggers, either.

The TRIGGER_EVENT does not represent a literal type of SQL statement
that activates the trigger so much as it represents a type of table
operation.  For example, an 'INSERT' trigger activates
not only for 'INSERT' statements but also 'LOAD DATA'
statements because both statements insert rows into a
table.

A potentially confusing example of this is the 'INSERT INTO ... ON
DUPLICATE KEY UPDATE ...' syntax: a 'BEFORE INSERT' trigger activates
for every row, followed by either an 'AFTER INSERT' trigger or both the
'BEFORE UPDATE' and 'AFTER UPDATE' triggers, depending on whether there
was a duplicate key for the row.

*Note*:

Cascaded foreign key actions do not activate triggers.

It is possible to define multiple triggers for a given table that have
the same trigger event and action time.  For example, you can have two
'BEFORE UPDATE' triggers for a table.  By default, triggers that have
the same trigger event and action time activate in the order they were
created.  To affect trigger order, specify a TRIGGER_ORDER clause that
indicates 'FOLLOWS' or 'PRECEDES' and the name of an existing trigger
that also has the same trigger event and action time.  With 'FOLLOWS',
the new trigger activates after the existing trigger.  With 'PRECEDES',
the new trigger activates before the existing trigger.

TRIGGER_BODY is the statement to execute when the trigger activates.  To
execute multiple statements, use the 'BEGIN ... END'.
compound statement construct.  This also enables you to use the same
statements that are permitted within stored routines.  See
begin-end.  Some statements are not permitted in triggers; see
stored-program-restrictions.

Within the trigger body, you can refer to columns in the subject table
(the table associated with the trigger) by using the aliases 'OLD' and
'NEW'.  'OLD.COL_NAME' refers to a column of an existing row before it
is updated or deleted.  'NEW.COL_NAME' refers to the column of a new row
to be inserted or an existing row after it is updated.

Triggers cannot use 'NEW.COL_NAME' or use 'OLD.COL_NAME' to refer to
generated columns.  For information about generated columns, see
create-table-generated-columns.

MySQL stores the 'sql_mode' system variable setting in effect when a
trigger is created, and always executes the trigger body with this
setting in force, _regardless of the current server SQL mode when the
trigger begins executing_.

The 'DEFINER' clause specifies the MySQL account to be used when
checking access privileges at trigger activation time.  If a USER value
is given, it should be a MySQL account specified as
''USER_NAME'@'HOST_NAME'', 'CURRENT_USER', or 'CURRENT_USER()'.  The
default 'DEFINER' value is the user who executes the 'CREATE TRIGGER'
statement.  This is the same as specifying
'DEFINER = CURRENT_USER' explicitly.

If you specify the 'DEFINER' clause, these rules determine the valid
'DEFINER' user values:

   * If you do not have the 'SUPER' privilege, the only permitted USER
     value is your own account, either specified literally or by using
     'CURRENT_USER'.  You cannot set the definer to some other account.

   * If you have the 'SUPER' privilege, you can specify any
     syntactically valid account name.  If the account does not exist, a
     warning is generated.

   * Although it is possible to create a trigger with a nonexistent
     'DEFINER' account, it is not a good idea for such triggers to be
     activated until the account actually does exist.  Otherwise, the
     behavior with respect to privilege checking is undefined.

MySQL takes the 'DEFINER' user into account when checking trigger
privileges as follows:

   * At 'CREATE TRIGGER' time, the user who
     issues the statement must have the 'TRIGGER' privilege.

   * At trigger activation time, privileges are checked against the
     'DEFINER' user.  This user must have these privileges:

        * The 'TRIGGER' privilege for the subject table.

        * The 'SELECT' privilege for the subject table if references to
          table columns occur using 'OLD.COL_NAME' or 'NEW.COL_NAME' in
          the trigger body.

        * The 'UPDATE' privilege for the subject table if table columns
          are targets of 'SET NEW.COL_NAME = VALUE' assignments in the
          trigger body.

        * Whatever other privileges normally are required for the
          statements executed by the trigger.

For more information about trigger security, see
stored-programs-security.

Within a trigger body, the 'CURRENT_USER()' function returns the account
used to check privileges at trigger activation time.  This is the
'DEFINER' user, not the user whose actions caused the trigger to be
activated.  For information about user auditing within triggers, see
account-activity-auditing.

If you use 'LOCK TABLES' to lock a table that has
triggers, the tables used within the trigger are also locked, as
described in lock-tables-and-triggers.

For additional discussion of trigger use, see trigger-syntax.

13.1.21 CREATE VIEW Syntax
--------------------------

     CREATE
         [OR REPLACE]
         [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]
         [DEFINER = { USER | CURRENT_USER }]
         [SQL SECURITY { DEFINER | INVOKER }]
         VIEW VIEW_NAME [(COLUMN_LIST)]
         AS SELECT_STATEMENT
         [WITH [CASCADED | LOCAL] CHECK OPTION]

The 'CREATE VIEW' statement creates a new view, or
replaces an existing view if the 'OR REPLACE' clause is given.  If the
view does not exist, see 'CREATE OR REPLACE VIEW' is the
same as 'CREATE VIEW'.  If the view does exist, see
'CREATE OR REPLACE VIEW' replaces it.

For information about restrictions on view use, see
view-restrictions.

The SELECT_STATEMENT is a 'SELECT' statement that
provides the definition of the view.  (Selecting from the view selects,
in effect, using the 'SELECT' statement.)  The
SELECT_STATEMENT can select from base tables or other views.

The view definition is 'frozen' at creation time and is not affected by
subsequent changes to the definitions of the underlying tables.  For
example, if a view is defined as 'SELECT *' on a table, new columns
added to the table later do not become part of the view, and columns
dropped from the table will result in an error when selecting from the
view.

The 'ALGORITHM' clause affects how MySQL processes the view.  The
'DEFINER' and 'SQL SECURITY' clauses specify the security context to be
used when checking access privileges at view invocation time.  The 'WITH
CHECK OPTION' clause can be given to constrain inserts or updates to
rows in tables referenced by the view.  These clauses are described
later in this section.

The 'CREATE VIEW' statement requires the 'CREATE
VIEW' privilege for the view, and some privilege for each column
selected by the 'SELECT' statement.  For columns used
elsewhere in the 'SELECT' statement, you must have the
'SELECT' privilege.  If the 'OR REPLACE' clause is present, you must
also have the 'DROP' privilege for the view.  'CREATE VIEW'
might also require the 'SUPER' privilege, depending on the
'DEFINER' value, as described later in this section.

When a view is referenced, privilege checking occurs as described later
in this section.

A view belongs to a database.  By default, a new view is created in the
default database.  To create the view explicitly in a given database,
use DB_NAME.VIEW_NAME syntax to qualify the view name with the database
name:

     CREATE VIEW test.v AS SELECT * FROM t;

Unqualified table or view names in the 'SELECT' statement
are also interpreted with respect to the default database.  A view can
refer to tables or views in other databases by qualifying the table or
view name with the appropriate database name.

Within a database, base tables and views share the same namespace, so a
base table and a view cannot have the same name.

Columns retrieved by the 'SELECT' statement can be simple
references to table columns, or expressions that use functions, constant
values, operators, and so forth.

A view must have unique column names with no duplicates, just like a
base table.  By default, the names of the columns retrieved by the
'SELECT' statement are used for the view column names.  To
define explicit names for the view columns, specify the optional
COLUMN_LIST clause as a list of comma-separated identifiers.  The number
of names in COLUMN_LIST must be the same as the number of columns
retrieved by the 'SELECT' statement.

A view can be created from many kinds of 'SELECT'.
statements.  It can refer to base tables or other views.  It can use
joins, see 'UNION', and subqueries.  The 'SELECT'
need not even refer to any tables:

     CREATE VIEW v_today (today) AS SELECT CURRENT_DATE;

The following example defines a view that selects two columns from
another table as well as an expression calculated from those columns:

     mysql> CREATE TABLE t (qty INT, price INT);
     mysql> INSERT INTO t VALUES(3, 50);
     mysql> CREATE VIEW v AS SELECT qty, price, qty*price AS value FROM t;
     mysql> SELECT * FROM v;
     +------+-------+-------+
     | qty  | price | value |
     +------+-------+-------+
     |    3 |    50 |   150 |
     +------+-------+-------+

A view definition is subject to the following restrictions:

   * The 'SELECT' statement cannot refer to system
     variables or user-defined variables.

   * Within a stored program, the 'SELECT' statement
     cannot refer to program parameters or local variables.

   * The 'SELECT' statement cannot refer to prepared
     statement parameters.

   * Any table or view referred to in the definition must exist.  If,
     after the view has been created, a table or view that the
     definition refers to is dropped, use of the view results in an
     error.  To check a view definition for problems of this kind, use
     the 'CHECK TABLE' statement.

   * The definition cannot refer to a 'TEMPORARY' table, and you cannot
     create a 'TEMPORARY' view.

   * You cannot associate a trigger with a view.

   * Aliases for column names in the 'SELECT' statement
     are checked against the maximum column length of 64 characters (not
     the maximum alias length of 256 characters).

'ORDER BY' is permitted in a view definition, but it is ignored if you
select from a view using a statement that has its own 'ORDER BY'.

For other options or clauses in the definition, they are added to the
options or clauses of the statement that references the view, but the
effect is undefined.  For example, if a view definition includes a
'LIMIT' clause, and you select from the view using a statement that has
its own 'LIMIT' clause, it is undefined which limit applies.  This same
principle applies to options such as 'ALL', 'DISTINCT', or
'SQL_SMALL_RESULT' that follow the 'SELECT' keyword, and
to clauses such as 'INTO', 'FOR UPDATE', 'LOCK IN SHARE MODE', and
'PROCEDURE'.

The results obtained from a view may be affected if you change the query
processing environment by changing system variables:

     mysql> CREATE VIEW v (mycol) AS SELECT 'abc';
     Query OK, 0 rows affected (0.01 sec)

     mysql> SET sql_mode = '';
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT "mycol" FROM v;
     +-------+
     | mycol |
     +-------+
     | mycol |
     +-------+
     1 row in set (0.01 sec)

     mysql> SET sql_mode = 'ANSI_QUOTES';
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT "mycol" FROM v;
     +-------+
     | mycol |
     +-------+
     | abc   |
     +-------+
     1 row in set (0.00 sec)

The 'DEFINER' and 'SQL SECURITY' clauses determine which MySQL account
to use when checking access privileges for the view when a statement is
executed that references the view.  The valid 'SQL SECURITY'
characteristic values are 'DEFINER' (the default) and 'INVOKER'.  These
indicate that the required privileges must be held by the user who
defined or invoked the view, respectively.

If a USER value is given for the 'DEFINER' clause, it should be a MySQL
account specified as ''USER_NAME'@'HOST_NAME'', 'CURRENT_USER', or
'CURRENT_USER()'.  The default 'DEFINER' value is the user who executes
the 'CREATE VIEW' statement.  This is the same as
specifying 'DEFINER = CURRENT_USER' explicitly.

If the 'DEFINER' clause is present, these rules determine the valid
'DEFINER' user values:

   * If you do not have the 'SUPER' privilege, the only valid USER value
     is your own account, either specified literally or by using
     'CURRENT_USER'.  You cannot set the definer to some other account.

   * If you have the 'SUPER' privilege, you can specify any
     syntactically valid account name.  If the account does not exist, a
     warning is generated.

   * Although it is possible to create a view with a nonexistent
     'DEFINER' account, an error occurs when the view is referenced if
     the 'SQL SECURITY' value is 'DEFINER' but the definer account does
     not exist.

For more information about view security, see
stored-programs-security.

Within a view definition, 'CURRENT_USER' returns the view's 'DEFINER'
value by default.  For views defined with the 'SQL SECURITY INVOKER'
characteristic, 'CURRENT_USER' returns the account for the view's
invoker.  For information about user auditing within views, see
account-activity-auditing.

Within a stored routine that is defined with the 'SQL SECURITY DEFINER'
characteristic, 'CURRENT_USER' returns the routine's 'DEFINER' value.
This also affects a view defined within such a routine, if the view
definition contains a 'DEFINER' value of 'CURRENT_USER'.

MySQL checks view privileges like this:

   * At view definition time, the view creator must have the privileges
     needed to use the top-level objects accessed by the view.  For
     example, if the view definition refers to table columns, the
     creator must have some privilege for each column in the select list
     of the definition, and the 'SELECT' privilege for each column used
     elsewhere in the definition.  If the definition refers to a stored
     function, only the privileges needed to invoke the function can be
     checked.  The privileges required at function invocation time can
     be checked only as it executes: For different invocations,
     different execution paths within the function might be taken.

   * The user who references a view must have appropriate privileges to
     access it ('SELECT' to select from it, 'INSERT' to insert into it,
     and so forth.)

   * When a view has been referenced, privileges for objects accessed by
     the view are checked against the privileges held by the view
     'DEFINER' account or invoker, depending on whether the 'SQL
     SECURITY' characteristic is 'DEFINER' or 'INVOKER', respectively.

   * If reference to a view causes execution of a stored function,
     privilege checking for statements executed within the function
     depend on whether the function 'SQL SECURITY' characteristic is
     'DEFINER' or 'INVOKER'.  If the security characteristic is
     'DEFINER', the function runs with the privileges of the 'DEFINER'
     account.  If the characteristic is 'INVOKER', the function runs
     with the privileges determined by the view's 'SQL SECURITY'
     characteristic.

Example: A view might depend on a stored function, and that function
might invoke other stored routines.  For example, the following view
invokes a stored function 'f()':

     CREATE VIEW v AS SELECT * FROM t WHERE t.id = f(t.name);

Suppose that 'f()' contains a statement such as this:

     IF name IS NULL then
       CALL p1();
     ELSE
       CALL p2();
     END IF;

The privileges required for executing statements within 'f()' need to be
checked when 'f()' executes.  This might mean that privileges are needed
for 'p1()' or 'p2()', depending on the execution path within 'f()'.
Those privileges must be checked at runtime, and the user who must
possess the privileges is determined by the 'SQL SECURITY' values of the
view 'v' and the function 'f()'.

The 'DEFINER' and 'SQL SECURITY' clauses for views are extensions to
standard SQL. In standard SQL, views are handled using the rules for
'SQL SECURITY DEFINER'.  The standard says that the definer of the view,
which is the same as the owner of the view's schema, gets applicable
privileges on the view (for example, 'SELECT') and may grant them.
MySQL has no concept of a schema 'owner', so MySQL adds a clause to
identify the definer.  The 'DEFINER' clause is an extension where the
intent is to have what the standard has; that is, a permanent record of
who defined the view.  This is why the default 'DEFINER' value is the
account of the view creator.

The optional 'ALGORITHM' clause is a MySQL extension to standard SQL. It
affects how MySQL processes the view.  'ALGORITHM' takes three values:
'MERGE', 'TEMPTABLE', or 'UNDEFINED'.  For more information, see
view-algorithms, as well as derived-table-optimization.

Some views are updatable.  That is, you can use them in statements such
as 'UPDATE', 'DELETE', or 'INSERT'
to update the contents of the underlying table.  For a view to
be updatable, there must be a one-to-one relationship between the rows
in the view and the rows in the underlying table.  There are also
certain other constructs that make a view nonupdatable.

A generated column in a view is considered updatable because it is
possible to assign to it.  However, if such a column is updated
explicitly, the only permitted value is 'DEFAULT'.  For information
about generated columns, see create-table-generated-columns.

The 'WITH CHECK OPTION' clause can be given for an updatable view to
prevent inserts or updates to rows except those for which the 'WHERE'
clause in the SELECT_STATEMENT is true.

In a 'WITH CHECK OPTION' clause for an updatable view, the 'LOCAL' and
'CASCADED' keywords determine the scope of check testing when the view
is defined in terms of another view.  The 'LOCAL' keyword restricts the
'CHECK OPTION' only to the view being defined.  'CASCADED' causes the
checks for underlying views to be evaluated as well.  When neither
keyword is given, the default is 'CASCADED'.

For more information about updatable views and the 'WITH CHECK OPTION'
clause, see view-updatability, and view-check-option.

Views created before MySQL 5.7.3 containing 'ORDER BY INTEGER' can
result in errors at view evaluation time.  Consider these view
definitions, which use 'ORDER BY' with an ordinal number:

     CREATE VIEW v1 AS SELECT x, y, z FROM t ORDER BY 2;
     CREATE VIEW v2 AS SELECT x, 1, z FROM t ORDER BY 2;

In the first case, 'ORDER BY 2' refers to a named column 'y'.  In the
second case, it refers to a constant 1.  For queries that select from
either view fewer than 2 columns (the number named in the 'ORDER BY'
clause), an error occurs if the server evaluates the view using the
MERGE algorithm.  Examples:

     mysql> SELECT x FROM v1;
     ERROR 1054 (42S22): Unknown column '2' in 'order clause'
     mysql> SELECT x FROM v2;
     ERROR 1054 (42S22): Unknown column '2' in 'order clause'

As of MySQL 5.7.3, to handle view definitions like this, the server
writes them differently into the '.frm' file that stores the view
definition.  This difference is visible with 'SHOW CREATE VIEW'.
Previously, the '.frm' file contained this for the
'ORDER BY 2' clause:

     For v1: ORDER BY 2
     For v2: ORDER BY 2

As of 5.7.3, the '.frm' file contains this:

     For v1: ORDER BY `t`.`y`
     For v2: ORDER BY ''

That is, for 'v1', 2 is replaced by a reference to the name of the
column referred to.  For 'v2', 2 is replaced by a constant string
expression (ordering by a constant has no effect, so ordering by any
constant will do).

If you experience view-evaluation errors such as just described, drop
and recreate the view so that the '.frm' file contains the updated view
representation.  Alternatively, for views like 'v2' that order by a
constant value, drop and recreate the view with no 'ORDER BY' clause.

13.1.22 DROP DATABASE Syntax
----------------------------

     DROP {DATABASE | SCHEMA} [IF EXISTS] DB_NAME

'DROP DATABASE' drops all tables in the database
and deletes the database.  Be _very_ careful with this statement!  To
use 'DROP DATABASE', you need the 'DROP' privilege
on the database.  'DROP SCHEMA' is a synonym for
'DROP DATABASE'.

*Important*:

When a database is dropped, privileges granted specifically for the
database are _not_ automatically dropped.  They must be dropped
manually.  See grant.

'IF EXISTS' is used to prevent an error from occurring if the database
does not exist.

If the default database is dropped, the default database is unset (the
'DATABASE()' function returns 'NULL').

If you use 'DROP DATABASE' on a symbolically
linked database, both the link and the original database are deleted.

'DROP DATABASE' returns the number of tables that
were removed.  This corresponds to the number of '.frm' files removed.

The 'DROP DATABASE' statement removes from the
given database directory those files and directories that MySQL itself
may create during normal operation:

   * All files with the following extensions:

        * '.BAK'

        * '.DAT'

        * '.HSH'

        * '.MRG'

        * '.MYD'

        * '.MYI'

        * '.TRG'

        * '.TRN'

        * '.cfg'

        * '.db'

        * '.frm'

        * '.ibd'

        * '.ndb'

        * '.par'

   * The 'db.opt' file, if it exists.

If other files or directories remain in the database directory after
MySQL removes those just listed, the database directory cannot be
removed.  In this case, you must remove any remaining files or
directories manually and issue the 'DROP DATABASE'.
statement again.

Dropping a database does not remove any 'TEMPORARY' tables that were
created in that database.  'TEMPORARY' tables are automatically removed
when the session that created them ends.  See
create-temporary-table.

You can also drop databases with 'mysqladmin'.  See
mysqladmin.

13.1.23 DROP EVENT Syntax
-------------------------

     DROP EVENT [IF EXISTS] EVENT_NAME

This statement drops the event named EVENT_NAME.  The event immediately
ceases being active, and is deleted completely from the server.

If the event does not exist, the error 'ERROR 1517 (HY000): Unknown
event 'EVENT_NAME'' results.  You can override this and cause the
statement to generate a warning for nonexistent events instead using 'IF
EXISTS'.

This statement requires the 'EVENT' privilege for the schema to which
the event to be dropped belongs.

13.1.24 DROP FUNCTION Syntax
----------------------------

The 'DROP FUNCTION' statement is used to drop
stored functions and user-defined functions (UDFs):

   * For information about dropping stored functions, see
     drop-procedure.

   * For information about dropping user-defined functions, see
     drop-function-udf.

13.1.25 DROP INDEX Syntax
-------------------------

     DROP INDEX INDEX_NAME ON TBL_NAME
         [ALGORITHM_OPTION | LOCK_OPTION] ...

     ALGORITHM_OPTION:
         ALGORITHM [=] {DEFAULT|INPLACE|COPY}

     LOCK_OPTION:
         LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}

'DROP INDEX' drops the index named INDEX_NAME from
the table TBL_NAME.  This statement is mapped to an 'ALTER TABLE'
statement to drop the index.  See alter-table.

To drop a primary key, the index name is always 'PRIMARY', which must be
specified as a quoted identifier because 'PRIMARY' is a reserved word:

     DROP INDEX `PRIMARY` ON t;

Indexes on variable-width columns of 'NDB' tables
are dropped online; that is, without any table copying.  The table is
not locked against access from other NDB Cluster API nodes, although it
is locked against other operations on the _same_ API node for the
duration of the operation.  This is done automatically by the server
whenever it determines that it is possible to do so; you do not have to
use any special SQL syntax or server options to cause it to happen.

'ALGORITHM' and 'LOCK' clauses may be given to influence the table
copying method and level of concurrency for reading and writing the
table while its indexes are being modified.  They have the same meaning
as for the 'ALTER TABLE' statement.  For more
information, see alter-table

NDB Cluster formerly supported online 'DROP INDEX' operations using the
'ONLINE' and 'OFFLINE' keywords.  These keywords are no longer supported
in MySQL NDB Cluster 7.5 and later, and their use causes a syntax error.
Instead, MySQL NDB Cluster 7.5 and later support online operations using
the same 'ALGORITHM=INPLACE' syntax used with the standard MySQL Server.
See alter-table-online-operations, for more information.

13.1.26 DROP LOGFILE GROUP Syntax
---------------------------------

     DROP LOGFILE GROUP LOGFILE_GROUP
         ENGINE [=] ENGINE_NAME

This statement drops the log file group named LOGFILE_GROUP.  The log
file group must already exist or an error results.  (For information on
creating log file groups, see create-logfile-group.)

*Important*:

Before dropping a log file group, you must drop all tablespaces that use
that log file group for 'UNDO' logging.

The required 'ENGINE' clause provides the name of the storage engine
used by the log file group to be dropped.  Currently, the only permitted
values for ENGINE_NAME are 'NDB' and
'NDBCLUSTER'.

'DROP LOGFILE GROUP' is useful only with Disk
Data storage for NDB Cluster.  See mysql-cluster-disk-data.

13.1.27 DROP PROCEDURE and DROP FUNCTION Syntax
-----------------------------------------------

     DROP {PROCEDURE | FUNCTION} [IF EXISTS] SP_NAME

This statement is used to drop a stored procedure or function.  That is,
the specified routine is removed from the server.  You must have the
'ALTER ROUTINE' privilege for the routine.  (If the
'automatic_sp_privileges' system variable is enabled, that privilege and
'EXECUTE' are granted automatically to the routine creator when the
routine is created and dropped from the creator when the routine is
dropped.  See stored-routines-privileges.)

The 'IF EXISTS' clause is a MySQL extension.  It prevents an error from
occurring if the procedure or function does not exist.  A warning is
produced that can be viewed with 'SHOW WARNINGS'.

'DROP FUNCTION' is also used to drop user-defined
functions (see drop-function-udf).

13.1.28 DROP SERVER Syntax
--------------------------

     DROP SERVER [ IF EXISTS ] SERVER_NAME

Drops the server definition for the server named 'SERVER_NAME'.  The
corresponding row in the 'mysql.servers' table is deleted.  This
statement requires the 'SUPER' privilege.

Dropping a server for a table does not affect any 'FEDERATED' tables
that used this connection information when they were created.  See
create-server.

'DROP SERVER' causes an implicit commit.  See implicit-commit.

'DROP SERVER' is not written to the binary log, regardless of the
logging format that is in use.

13.1.29 DROP TABLE Syntax
-------------------------

     DROP [TEMPORARY] TABLE [IF EXISTS]
         TBL_NAME [, TBL_NAME] ...
         [RESTRICT | CASCADE]

'DROP TABLE' removes one or more tables.  You must
have the 'DROP' privilege for each table.

_Be careful_ with this statement!  It removes the table definition and
all table data.  For a partitioned table, it permanently removes the
table definition, all its partitions, and all data stored in those
partitions.  It also removes partition definitions associated with the
dropped table.

'DROP TABLE' causes an implicit commit, except when
used with the 'TEMPORARY' keyword.  See implicit-commit.

*Important*:

When a table is dropped, privileges granted specifically for the table
are _not_ automatically dropped.  They must be dropped manually.  See
grant.

If any tables named in the argument list do not exist, the statement
returns an error indicating by name which nonexisting tables it was
unable to drop, but also drops all tables in the list that do exist.

Use 'IF EXISTS' to prevent an error from occurring for tables that do
not exist.  Instead of an error, a 'NOTE' is generated for each
nonexistent table; these notes can be displayed with 'SHOW WARNINGS'.
See show-warnings.

'IF EXISTS' can also be useful for dropping tables in unusual
circumstances under which there is an '.frm' file but no table managed
by the storage engine.  (For example, if an abnormal server exit occurs
after removal of the table from the storage engine but before '.frm'
file removal.)

The 'TEMPORARY' keyword has the following effects:

   * The statement drops only 'TEMPORARY' tables.

   * The statement does not cause an implicit commit.

   * No access rights are checked.  A 'TEMPORARY' table is visible only
     with the session that created it, so no check is necessary.

Using 'TEMPORARY' is a good way to ensure that you do not accidentally
drop a non-'TEMPORARY' table.

The 'RESTRICT' and 'CASCADE' keywords do nothing.  They are permitted to
make porting easier from other database systems.

'DROP TABLE' is not supported with all
'innodb_force_recovery' settings.  See forcing-innodb-recovery.

13.1.30 DROP TABLESPACE Syntax
------------------------------

     DROP TABLESPACE TABLESPACE_NAME
         [ENGINE [=] ENGINE_NAME]

This statement drops a tablespace that was previously created using
'CREATE TABLESPACE'.  It is supported with all
MySQL NDB Cluster 7.5 releases, and with 'InnoDB' in the standard MySQL
Server as well.

'ENGINE' sets the storage engine that uses the tablespace, where
ENGINE_NAME is the name of the storage engine.  Currently, the values
'InnoDB' and 'NDB' are supported.  If not set, the value of
'default_storage_engine' is used.  If it is not the same as the storage
engine used to create the tablespace, the 'DROP TABLESPACE' statement
fails.

For an 'InnoDB' tablespace, all tables must be dropped from the
tablespace prior to a 'DROP TABLESPACE' operation.  If the tablespace is
not empty, 'DROP TABLESPACE' returns an error.

As with the 'InnoDB' system tablespace, truncating or dropping 'InnoDB'
tables stored in a general tablespace creates free space in the
tablespace .ibd data file, which can only be used for new 'InnoDB' data.
Space is not released back to the operating system by such operations as
it is for file-per-table tablespaces.

An 'NDB' tablespace to be dropped must not contain any data files; in
other words, before you can drop an 'NDB' tablespace, you must first
drop each of its data files using 'ALTER TABLESPACE ... DROP DATAFILE'.

*Notes*

   * Tablespaces are not deleted automatically.  A tablespace must be
     dropped explicitly using 'DROP TABLESPACE'.  'DROP DATABASE'
     has no effect in this regard, even if the operation
     drops all tables belonging to the tablespace.

   * A 'DROP DATABASE' operation can drop tables
     that belong to a general tablespace but it cannot drop the
     tablespace, even if the operation drops all tables that belong to
     the tablespace.  The tablespace must be dropped explicitly using
     'DROP TABLESPACE TABLESPACE_NAME'.

   * Similar to the system tablespace, truncating or dropping tables
     stored in a general tablespace creates free space internally in the
     general tablespace .ibd data file which can only be used for new
     'InnoDB' data.  Space is not released back to the operating system
     as it is for file-per-table tablespaces.

*InnoDB Example*

This example demonstrates how to drop an 'InnoDB' general tablespace.
The general tablespace 'ts1' is created with a single table.  Before
dropping the tablespace, the table must be dropped.

     mysql> CREATE TABLESPACE `ts1`
         ->     ADD DATAFILE 'ts1.ibd'
         ->     ENGINE=INNODB;
     Query OK, 0 rows affected (0.01 sec)

     mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY)
         ->     TABLESPACE ts10
         ->     ENGINE=INNODB;
     Query OK, 0 rows affected (0.02 sec)

     mysql> DROP TABLE t1;
     Query OK, 0 rows affected (0.01 sec)

     mysql> DROP TABLESPACE ts1;
     Query OK, 0 rows affected (0.01 sec)

*NDB Example*

This example shows how to drop an 'NDB' tablespace 'myts' having a data
file named 'mydata-1.dat' after first creating the tablespace, and
assumes the existence of a log file group named 'mylg' (see
create-logfile-group).

     mysql> CREATE TABLESPACE myts
         ->     ADD DATAFILE 'mydata-1.dat'
         ->     USE LOGFILE GROUP mylg
         ->     ENGINE=NDB;

You must remove all data files from the tablespace using 'ALTER TABLESPACE',
as shown here, before it can be dropped:

     mysql> ALTER TABLESPACE myts
         ->     DROP DATAFILE 'mydata-1.dat'
         ->     ENGINE=NDB;

     mysql> DROP TABLESPACE myts;

13.1.31 DROP TRIGGER Syntax
---------------------------

     DROP TRIGGER [IF EXISTS] [SCHEMA_NAME.]TRIGGER_NAME

This statement drops a trigger.  The schema (database) name is optional.
If the schema is omitted, the trigger is dropped from the default
schema.  'DROP TRIGGER' requires the 'TRIGGER'
privilege for the table associated with the trigger.

Use 'IF EXISTS' to prevent an error from occurring for a trigger that
does not exist.  A 'NOTE' is generated for a nonexistent trigger when
using 'IF EXISTS'.  See show-warnings.

Triggers for a table are also dropped if you drop the table.

13.1.32 DROP VIEW Syntax
------------------------

     DROP VIEW [IF EXISTS]
         VIEW_NAME [, VIEW_NAME] ...
         [RESTRICT | CASCADE]

'DROP VIEW' removes one or more views.  You must have
the 'DROP' privilege for each view.

If any views named in the argument list do not exist, the statement
returns an error indicating by name which nonexisting views it was
unable to drop, but also drops all views in the list that do exist.

*Note*:

In MySQL 8.0, see 'DROP VIEW' fails if any views named in
the argument list do not exist.  Due to the change in behavior, a
partially completed 'DROP VIEW' operation on a MySQL
5.7 master fails when replicated to a MySQL 8.0 slave.  To avoid this
failure scenario, use 'IF EXISTS' syntax in 'DROP VIEW'
statements to prevent an error from occurring for views that
do not exist.  For more information, see Atomic Data Definition
Statement Support
(http://dev.mysql.com/doc/refman/8.0/en/atomic-ddl.html).

The 'IF EXISTS' clause prevents an error from occurring for views that
don't exist.  When this clause is given, a 'NOTE' is generated for each
nonexistent view.  See show-warnings.

'RESTRICT' and 'CASCADE', if given, are parsed and ignored.

13.1.33 RENAME TABLE Syntax
---------------------------

     RENAME TABLE
         TBL_NAME TO NEW_TBL_NAME
         [, TBL_NAME2 TO NEW_TBL_NAME2] ...

'RENAME TABLE' renames one or more tables.  You
must have 'ALTER' and 'DROP' privileges for the original table, and
'CREATE' and 'INSERT' privileges for the new table.

For example, to rename a table named 'old_table' to to 'new_table', use
this statement:

     RENAME TABLE old_table TO new_table;

That statement is equivalent to the following 'ALTER TABLE'
statement:

     ALTER TABLE old_table RENAME new_table;

'RENAME TABLE', unlike 'ALTER TABLE', can rename
multiple tables within a single statement:

     RENAME TABLE old_table1 TO new_table1,
                  old_table2 TO new_table2,
                  old_table3 TO new_table3;

Renaming operations are performed left to right.  Thus, to swap two
table names, do this (assuming that a table with the intermediary name
'tmp_table' does not already exist):

     RENAME TABLE old_table TO tmp_table,
                  new_table TO old_table,
                  tmp_table TO new_table;

When you execute 'RENAME TABLE', you cannot have any locked tables or
active transactions.  With that condition satisfied, the rename
operation is done atomically; no other session can access any of the
tables while the rename is in progress.

If any errors occur during a 'RENAME TABLE', the statement fails and no
changes are made.

You can use 'RENAME TABLE' to move a table from one database to another:

     RENAME TABLE CURRENT_DB.TBL_NAME TO OTHER_DB.TBL_NAME;

Using this method to move all tables from one database to a different
one in effect renames the database (an operation for which MySQL has no
single statement), except that the original database continues to exist,
albeit with no tables.

Like 'RENAME TABLE', 'ALTER TABLE ... RENAME' can also be used to move a
table to a different database.  Regardless of the statement used, if the
rename operation would move the table to a database located on a
different file system, the success of the outcome is platform specific
and depends on the underlying operating system calls used to move the
table files.

If a table has triggers, attempts to rename the table into a different
database fail with a 'Trigger in wrong schema' error.

'RENAME TABLE' does not work for 'TEMPORARY' tables.  However, you can
use 'ALTER TABLE' to rename 'TEMPORARY' tables.

'RENAME TABLE' works for views, except that views cannot be renamed into
a different database.

Any privileges granted specifically for a renamed table or view are not
migrated to the new name.  They must be changed manually.

'RENAME TABLE' changes internally generated foreign key constraint names
and user-defined foreign key constraint names that contain the string
'TBL_NAME_ibfk_' to reflect the new table name.  'InnoDB' interprets
foreign key constraint names that contain the string 'TBL_NAME_ibfk_' as
internally generated names.

Foreign key constraint names that point to the renamed table are
automatically updated unless there is a conflict, in which case, the
statement fails with an error.  A conflict occurs if the renamed
constraint name already exists.  In such cases, you must drop and
re-create the foreign keys in order for them to function properly.

13.1.34 TRUNCATE TABLE Syntax
-----------------------------

     TRUNCATE [TABLE] TBL_NAME

'TRUNCATE TABLE' empties a table completely.  It
requires the 'DROP' privilege.

Logically, see 'TRUNCATE TABLE' is similar to a
'DELETE' statement that deletes all rows, or a sequence of
'DROP TABLE' and 'CREATE TABLE'.
statements.  To achieve high performance, it bypasses the DML method of
deleting data.  Thus, it cannot be rolled back, it does not cause 'ON
DELETE' triggers to fire, and it cannot be performed for 'InnoDB' tables
with parent-child foreign key relationships.

Although 'TRUNCATE TABLE' is similar to
'DELETE', it is classified as a DDL statement rather than a DML
statement.  It differs from 'DELETE' in the following
ways:

   * Truncate operations drop and re-create the table, which is much
     faster than deleting rows one by one, particularly for large
     tables.

   * Truncate operations cause an implicit commit, and so cannot be
     rolled back.  See implicit-commit.

   * Truncation operations cannot be performed if the session holds an
     active table lock.

   * 'TRUNCATE TABLE' fails for an 'InnoDB' table
     or 'NDB' table if there are any 'FOREIGN KEY'
     constraints from other tables that reference the table.  Foreign
     key constraints between columns of the same table are permitted.

   * Truncation operations do not return a meaningful value for the
     number of deleted rows.  The usual result is '0 rows affected,'
     which should be interpreted as 'no information.'

   * As long as the table format file 'TBL_NAME.frm' is valid, the table
     can be re-created as an empty table with 'TRUNCATE TABLE',
     even if the data or index files have become
     corrupted.

   * Any 'AUTO_INCREMENT' value is reset to its start value.  This is
     true even for 'MyISAM' and 'InnoDB', which normally do not reuse
     sequence values.

   * When used with partitioned tables, see 'TRUNCATE TABLE'
     preserves the partitioning; that is, the data and
     index files are dropped and re-created, while the partition
     definitions ('.par') file is unaffected.

   * The 'TRUNCATE TABLE' statement does not
     invoke 'ON DELETE' triggers.

'TRUNCATE TABLE' for a table closes all handlers
for the table that were opened with 'HANDLER OPEN'.

'TRUNCATE TABLE' is treated for purposes of
binary logging and replication as 'DROP TABLE'.
followed by 'CREATE TABLE'.--that is, as DDL rather
than DML. This is due to the fact that, when using 'InnoDB'
and other transactional storage engines where the
transaction isolation level does not permit statement-based logging
('READ COMMITTED' or 'READ UNCOMMITTED'), the statement was not logged
and replicated when using 'STATEMENT' or 'MIXED' logging mode.  (Bug
#36763) However, it is still applied on replication slaves using
'InnoDB' in the manner described previously.

On a system with a large 'InnoDB' buffer pool and
'innodb_adaptive_hash_index' enabled, 'TRUNCATE TABLE' operations may
cause a temporary drop in system performance due to an LRU scan that
occurs when removing an 'InnoDB' table's adaptive hash index entries.
The problem was addressed for 'DROP TABLE' in MySQL
5.5.23 (Bug #13704145, Bug #64284) but remains a known issue for
'TRUNCATE TABLE' (Bug #68184).

'TRUNCATE TABLE' can be used with Performance
Schema summary tables, but the effect is to reset the summary columns to
0 or 'NULL', not to remove rows.  See
performance-schema-summary-tables.

13.2 Data Manipulation Statements
=================================

13.2.1 CALL Syntax
------------------

     CALL SP_NAME([PARAMETER[,...]])
     CALL SP_NAME[()]

The 'CALL' statement invokes a stored procedure that was
defined previously with 'CREATE PROCEDURE'.

Stored procedures that take no arguments can be invoked without
parentheses.  That is, 'CALL p()' and 'CALL p' are equivalent.

'CALL' can pass back values to its caller using parameters
that are declared as 'OUT' or 'INOUT' parameters.  When the procedure
returns, a client program can also obtain the number of rows affected
for the final statement executed within the routine: At the SQL level,
call the 'ROW_COUNT()' function; from the C API, call the
'mysql_affected_rows()' function.

To get back a value from a procedure using an 'OUT' or 'INOUT'
parameter, pass the parameter by means of a user variable, and then
check the value of the variable after the procedure returns.  (If you
are calling the procedure from within another stored procedure or
function, you can also pass a routine parameter or local routine
variable as an 'IN' or 'INOUT' parameter.)  For an 'INOUT' parameter,
initialize its value before passing it to the procedure.  The following
procedure has an 'OUT' parameter that the procedure sets to the current
server version, and an 'INOUT' value that the procedure increments by
one from its current value:

     CREATE PROCEDURE p (OUT ver_param VARCHAR(25), INOUT incr_param INT)
     BEGIN
       # Set value of OUT parameter
       SELECT VERSION() INTO ver_param;
       # Increment value of INOUT parameter
       SET incr_param = incr_param + 1;
     END;

Before calling the procedure, initialize the variable to be passed as
the 'INOUT' parameter.  After calling the procedure, the values of the
two variables will have been set or modified:

     mysql> SET @increment = 10;
     mysql> CALL p(@version, @increment);
     mysql> SELECT @version, @increment;
     +------------------+------------+
     | @version         | @increment |
     +------------------+------------+
     | 5.7.20-debug-log |         11 |
     +------------------+------------+

In prepared 'CALL' statements used with 'PREPARE'
and 'EXECUTE', placeholders can be used for 'IN'
parameters, 'OUT', and 'INOUT' parameters.  These types of parameters
can be used as follows:

     mysql> SET @increment = 10;
     mysql> PREPARE s FROM 'CALL p(?, ?)';
     mysql> EXECUTE s USING @version, @increment;
     mysql> SELECT @version, @increment;
     +------------------+------------+
     | @version         | @increment |
     +------------------+------------+
     | 5.7.20-debug-log |         11 |
     +------------------+------------+

To write C programs that use the 'CALL'. SQL statement to
execute stored procedures that produce result sets, the
'CLIENT_MULTI_RESULTS' flag must be enabled.  This is because each
'CALL' returns a result to indicate the call status, in addition
to any result sets that might be returned by statements executed within
the procedure.  'CLIENT_MULTI_RESULTS' must also be enabled if
'CALL' is used to execute any stored procedure that contains
prepared statements.  It cannot be determined when such a procedure is
loaded whether those statements will produce result sets, so it is
necessary to assume that they will.

'CLIENT_MULTI_RESULTS' can be enabled when you call
'mysql_real_connect()', either explicitly by passing
the 'CLIENT_MULTI_RESULTS' flag itself, or implicitly by passing
'CLIENT_MULTI_STATEMENTS' (which also enables 'CLIENT_MULTI_RESULTS').
'CLIENT_MULTI_RESULTS' is enabled by default.

To process the result of a 'CALL' statement executed using
'mysql_query()' or 'mysql_real_query()',
use a loop that calls 'mysql_next_result()'
to determine whether there are more results.  For an
example, see c-api-multiple-queries.

C programs can use the prepared-statement interface to execute
'CALL' statements and access 'OUT' and 'INOUT' parameters.  This
is done by processing the result of a 'CALL' statement
using a loop that calls 'mysql_stmt_next_result()'
to determine whether there are more results.
For an example, see c-api-prepared-call-statements.  Languages
that provide a MySQL interface can use prepared 'CALL'.
statements to directly retrieve 'OUT' and 'INOUT' procedure parameters.

Metadata changes to objects referred to by stored programs are detected
and cause automatic reparsing of the affected statements when the
program is next executed.  For more information, see
statement-caching.

13.2.2 DELETE Syntax
--------------------

'DELETE' is a DML statement that removes rows from a
table.

*Single-Table Syntax*

     DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROM TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         [WHERE WHERE_CONDITION]
         [ORDER BY ...]
         [LIMIT ROW_COUNT]

The 'DELETE' statement deletes rows from TBL_NAME and returns the number
of deleted rows.  To check the number of deleted rows, call the
'ROW_COUNT()' function described in information-functions.

*Main Clauses*

The conditions in the optional 'WHERE' clause identify which rows to
delete.  With no 'WHERE' clause, all rows are deleted.

WHERE_CONDITION is an expression that evaluates to true for each row to
be deleted.  It is specified as described in select.

If the 'ORDER BY' clause is specified, the rows are deleted in the order
that is specified.  The 'LIMIT' clause places a limit on the number of
rows that can be deleted.  These clauses apply to single-table deletes,
but not multi-table deletes.

*Multiple-Table Syntax*

     DELETE [LOW_PRIORITY] [QUICK] [IGNORE]
         TBL_NAME[.*] [, TBL_NAME[.*]] ...
         FROM TABLE_REFERENCES
         [WHERE WHERE_CONDITION]

     DELETE [LOW_PRIORITY] [QUICK] [IGNORE]
         FROM TBL_NAME[.*] [, TBL_NAME[.*]] ...
         USING TABLE_REFERENCES
         [WHERE WHERE_CONDITION]

*Privileges*

You need the 'DELETE' privilege on a table to delete rows from it.  You
need only the 'SELECT' privilege for any columns that are only read,
such as those named in the 'WHERE' clause.

*Performance*

When you do not need to know the number of deleted rows, the
'TRUNCATE TABLE' statement is a faster way to empty a
table than a 'DELETE' statement with no 'WHERE' clause.
Unlike 'DELETE', 'TRUNCATE TABLE'.
cannot be used within a transaction or if you have a lock on the table.
See truncate-table and lock-tables.

The speed of delete operations may also be affected by factors discussed
in delete-optimization.

To ensure that a given 'DELETE' statement does not take
too much time, the MySQL-specific 'LIMIT ROW_COUNT' clause for
'DELETE' specifies the maximum number of rows to be deleted.
If the number of rows to delete is larger than the limit, repeat the
'DELETE' statement until the number of affected rows is less than the
'LIMIT' value.

*Subqueries*

You cannot delete from a table and select from the same table in a
subquery.

*Partitioned Tables*

'DELETE' supports explicit partition selection using the 'PARTITION'
option, which takes a list of the comma-separated names of one or more
partitions or subpartitions (or both) from which to select rows to be
dropped.  Partitions not included in the list are ignored.  Given a
partitioned table 't' with a partition named 'p0', executing the
statement 'DELETE FROM t PARTITION (p0)' has the same effect on the
table as executing 'ALTER TABLE t TRUNCATE PARTITION (p0)'.;
in both cases, all rows in partition 'p0' are dropped.

'PARTITION' can be used along with a 'WHERE' condition, in which case
the condition is tested only on rows in the listed partitions.  For
example, 'DELETE FROM t PARTITION (p0) WHERE c < 5' deletes rows only
from partition 'p0' for which the condition 'c < 5' is true; rows in any
other partitions are not checked and thus not affected by the 'DELETE'.

The 'PARTITION' option can also be used in multiple-table 'DELETE'
statements.  You can use up to one such option per table named in the
'FROM' option.

For more information and examples, see partitioning-selection.

*Auto-Increment Columns*

If you delete the row containing the maximum value for an
'AUTO_INCREMENT' column, the value is not reused for a 'MyISAM' or
'InnoDB' table.  If you delete all rows in the table with 'DELETE FROM
TBL_NAME' (without a 'WHERE' clause) in 'autocommit' mode, the sequence
starts over for all storage engines except 'InnoDB' and 'MyISAM'.  There
are some exceptions to this behavior for 'InnoDB' tables, as discussed
in innodb-auto-increment-handling.

For 'MyISAM' tables, you can specify an 'AUTO_INCREMENT' secondary
column in a multiple-column key.  In this case, reuse of values deleted
from the top of the sequence occurs even for 'MyISAM' tables.  See
example-auto-increment.

*Modifiers*

The 'DELETE' statement supports the following modifiers:

   * If you specify 'LOW_PRIORITY', the server delays execution of the
     'DELETE' until no other clients are reading from the
     table.  This affects only storage engines that use only table-level
     locking (such as 'MyISAM', 'MEMORY', and 'MERGE').

   * For 'MyISAM' tables, if you use the 'QUICK' modifier, the storage
     engine does not merge index leaves during delete, which may speed
     up some kinds of delete operations.

   * The 'IGNORE' modifier causes MySQL to ignore errors during the
     process of deleting rows.  (Errors encountered during the parsing
     stage are processed in the usual manner.)  Errors that are ignored
     due to the use of 'IGNORE' are returned as warnings.  For more
     information, see ignore-strict-comparison.

*Order of Deletion*

If the 'DELETE' statement includes an 'ORDER BY' clause,
rows are deleted in the order specified by the clause.  This is useful
primarily in conjunction with 'LIMIT'.  For example, the following
statement finds rows matching the 'WHERE' clause, sorts them by
'timestamp_column', and deletes the first (oldest) one:

     DELETE FROM somelog WHERE user = 'jcole'
     ORDER BY timestamp_column LIMIT 1;

'ORDER BY' also helps to delete rows in an order required to avoid
referential integrity violations.

*InnoDB Tables*

If you are deleting many rows from a large table, you may exceed the
lock table size for an 'InnoDB' table.  To avoid this problem, or simply
to minimize the time that the table remains locked, the following
strategy (which does not use 'DELETE' at all) might be
helpful:

  1. Select the rows _not_ to be deleted into an empty table that has
     the same structure as the original table:

          INSERT INTO t_copy SELECT * FROM t WHERE ... ;

  2. Use 'RENAME TABLE' to atomically move the
     original table out of the way and rename the copy to the original
     name:

          RENAME TABLE t TO t_old, t_copy TO t;

  3. Drop the original table:

          DROP TABLE t_old;

No other sessions can access the tables involved while 'RENAME TABLE'
executes, so the rename operation is not subject
to concurrency problems.  See rename-table.

*MyISAM Tables*

In 'MyISAM' tables, deleted rows are maintained in a linked list and
subsequent 'INSERT' operations reuse old row positions.
To reclaim unused space and reduce file sizes, use the 'OPTIMIZE TABLE'
statement or the 'myisamchk'.
utility to reorganize tables.  See 'OPTIMIZE TABLE'.
is easier to use, but 'myisamchk' is faster.  See
optimize-table, and myisamchk.

The 'QUICK' modifier affects whether index leaves are merged for delete
operations.  'DELETE QUICK' is most useful for applications where index
values for deleted rows are replaced by similar index values from rows
inserted later.  In this case, the holes left by deleted values are
reused.

'DELETE QUICK' is not useful when deleted values lead to underfilled
index blocks spanning a range of index values for which new inserts
occur again.  In this case, use of 'QUICK' can lead to wasted space in
the index that remains unreclaimed.  Here is an example of such a
scenario:

  1. Create a table that contains an indexed 'AUTO_INCREMENT' column.

  2. Insert many rows into the table.  Each insert results in an index
     value that is added to the high end of the index.

  3. Delete a block of rows at the low end of the column range using
     'DELETE QUICK'.

In this scenario, the index blocks associated with the deleted index
values become underfilled but are not merged with other index blocks due
to the use of 'QUICK'.  They remain underfilled when new inserts occur,
because new rows do not have index values in the deleted range.
Furthermore, they remain underfilled even if you later use
'DELETE' without 'QUICK', unless some of the deleted index
values happen to lie in index blocks within or adjacent to the
underfilled blocks.  To reclaim unused index space under these
circumstances, use 'OPTIMIZE TABLE'.

If you are going to delete many rows from a table, it might be faster to
use 'DELETE QUICK' followed by 'OPTIMIZE TABLE'.
This rebuilds the index rather than performing many index block merge
operations.

*Multi-Table Deletes*

You can specify multiple tables in a 'DELETE' statement
to delete rows from one or more tables depending on the condition in the
'WHERE' clause.  You cannot use 'ORDER BY' or 'LIMIT' in a
multiple-table 'DELETE'.  The TABLE_REFERENCES clause lists the tables
involved in the join, as described in join.

For the first multiple-table syntax, only matching rows from the tables
listed before the 'FROM' clause are deleted.  For the second
multiple-table syntax, only matching rows from the tables listed in the
'FROM' clause (before the 'USING' clause) are deleted.  The effect is
that you can delete rows from many tables at the same time and have
additional tables that are used only for searching:

     DELETE t1, t2 FROM t1 INNER JOIN t2 INNER JOIN t3
     WHERE t1.id=t2.id AND t2.id=t3.id;

Or:

     DELETE FROM t1, t2 USING t1 INNER JOIN t2 INNER JOIN t3
     WHERE t1.id=t2.id AND t2.id=t3.id;

These statements use all three tables when searching for rows to delete,
but delete matching rows only from tables 't1' and 't2'.

The preceding examples use 'INNER JOIN', but multiple-table
'DELETE' statements can use other types of join permitted in
'SELECT' statements, such as 'LEFT JOIN'.  For example,
to delete rows that exist in 't1' that have no match in 't2', use a
'LEFT JOIN':

     DELETE t1 FROM t1 LEFT JOIN t2 ON t1.id=t2.id WHERE t2.id IS NULL;

The syntax permits '.*' after each TBL_NAME for compatibility with
'Access'.

If you use a multiple-table 'DELETE' statement involving
'InnoDB' tables for which there are foreign key constraints, the MySQL
optimizer might process tables in an order that differs from that of
their parent/child relationship.  In this case, the statement fails and
rolls back.  Instead, you should delete from a single table and rely on
the 'ON DELETE' capabilities that 'InnoDB' provides to cause the other
tables to be modified accordingly.

*Note*:

If you declare an alias for a table, you must use the alias when
referring to the table:

     DELETE t1 FROM test AS t1, test2 WHERE ...

Table aliases in a multiple-table 'DELETE' should be
declared only in the TABLE_REFERENCES part of the statement.  Elsewhere,
alias references are permitted but not alias declarations.

Correct:

     DELETE a1, a2 FROM t1 AS a1 INNER JOIN t2 AS a2
     WHERE a1.id=a2.id;

     DELETE FROM a1, a2 USING t1 AS a1 INNER JOIN t2 AS a2
     WHERE a1.id=a2.id;

Incorrect:

     DELETE t1 AS a1, t2 AS a2 FROM t1 INNER JOIN t2
     WHERE a1.id=a2.id;

     DELETE FROM t1 AS a1, t2 AS a2 USING t1 INNER JOIN t2
     WHERE a1.id=a2.id;

13.2.3 DO Syntax
----------------

     DO EXPR [, EXPR] ...

'DO' executes the expressions but does not return any
results.  In most respects, see 'DO' is shorthand for 'SELECT
EXPR, ...', but has the advantage that it is slightly faster when you do
not care about the result.

'DO' is useful primarily with functions that have side
effects, such as 'RELEASE_LOCK()'.

Example: This 'SELECT' statement pauses, but also
produces a result set:

     mysql> SELECT SLEEP(5);
     +----------+
     | SLEEP(5) |
     +----------+
     |        0 |
     +----------+
     1 row in set (5.02 sec)

See 'DO', on the other hand, pauses without producing a result
set.:

     mysql> DO SLEEP(5);
     Query OK, 0 rows affected (4.99 sec)

This could be useful, for example in a stored function or trigger, which
prohibit statements that produce result sets.

'DO' only executes expressions.  It cannot be used in all
cases where 'SELECT' can be used.  For example, 'DO id FROM t1' is
invalid because it references a table.

13.2.4 HANDLER Syntax
---------------------

     HANDLER TBL_NAME OPEN [ [AS] ALIAS]

     HANDLER TBL_NAME READ INDEX_NAME { = | <= | >= | < | > } (VALUE1,VALUE2,...)
         [ WHERE WHERE_CONDITION ] [LIMIT ... ]
     HANDLER TBL_NAME READ INDEX_NAME { FIRST | NEXT | PREV | LAST }
         [ WHERE WHERE_CONDITION ] [LIMIT ... ]
     HANDLER TBL_NAME READ { FIRST | NEXT }
         [ WHERE WHERE_CONDITION ] [LIMIT ... ]

     HANDLER TBL_NAME CLOSE

The 'HANDLER' statement provides direct access to table storage engine
interfaces.  It is available for 'InnoDB' and 'MyISAM' tables.

The 'HANDLER ... OPEN' statement opens a table, making it accessible
using subsequent 'HANDLER ... READ' statements.  This table object is
not shared by other sessions and is not closed until the session calls
'HANDLER ... CLOSE' or the session terminates.

If you open the table using an alias, further references to the open
table with other 'HANDLER' statements must use the alias rather than the
table name.  If you do not use an alias, but open the table using a
table name qualified by the database name, further references must use
the unqualified table name.  For example, for a table opened using
'mydb.mytable', further references must use 'mytable'.

The first 'HANDLER ... READ' syntax fetches a row where the index
specified satisfies the given values and the 'WHERE' condition is met.
If you have a multiple-column index, specify the index column values as
a comma-separated list.  Either specify values for all the columns in
the index, or specify values for a leftmost prefix of the index columns.
Suppose that an index 'my_idx' includes three columns named 'col_a',
'col_b', and 'col_c', in that order.  The 'HANDLER' statement can
specify values for all three columns in the index, or for the columns in
a leftmost prefix.  For example:

     HANDLER ... READ my_idx = (col_a_val,col_b_val,col_c_val) ...
     HANDLER ... READ my_idx = (col_a_val,col_b_val) ...
     HANDLER ... READ my_idx = (col_a_val) ...

To employ the 'HANDLER' interface to refer to a table's 'PRIMARY KEY',
use the quoted identifier '`PRIMARY`':

     HANDLER TBL_NAME READ `PRIMARY` ...

The second 'HANDLER ... READ' syntax fetches a row from the table in
index order that matches the 'WHERE' condition.

The third 'HANDLER ... READ' syntax fetches a row from the table in
natural row order that matches the 'WHERE' condition.  It is faster than
'HANDLER TBL_NAME READ INDEX_NAME' when a full table scan is desired.
Natural row order is the order in which rows are stored in a 'MyISAM'
table data file.  This statement works for 'InnoDB' tables as well, but
there is no such concept because there is no separate data file.

Without a 'LIMIT' clause, all forms of 'HANDLER ... READ' fetch a single
row if one is available.  To return a specific number of rows, include a
'LIMIT' clause.  It has the same syntax as for the 'SELECT'
statement.  See select.

'HANDLER ... CLOSE' closes a table that was opened with 'HANDLER ...
OPEN'.

There are several reasons to use the 'HANDLER' interface instead of
normal 'SELECT' statements:

   * 'HANDLER' is faster than 'SELECT'.:

        * A designated storage engine handler object is allocated for
          the 'HANDLER ... OPEN'.  The object is reused for subsequent
          'HANDLER' statements for that table; it need not be
          reinitialized for each one.

        * There is less parsing involved.

        * There is no optimizer or query-checking overhead.

        * The handler interface does not have to provide a consistent
          look of the data (for example, dirty reads are permitted), so
          the storage engine can use optimizations that 'SELECT'
          does not normally permit.

   * 'HANDLER' makes it easier to port to MySQL applications that use a
     low-level 'ISAM'-like interface.  (See innodb-memcached for
     an alternative way to adapt applications that use the key-value
     store paradigm.)

   * 'HANDLER' enables you to traverse a database in a manner that is
     difficult (or even impossible) to accomplish with 'SELECT'.
     The 'HANDLER' interface is a more natural way to look at
     data when working with applications that provide an interactive
     user interface to the database.

'HANDLER' is a somewhat low-level statement.  For example, it does not
provide consistency.  That is, 'HANDLER ... OPEN' does _not_ take a
snapshot of the table, and does _not_ lock the table.  This means that
after a 'HANDLER ... OPEN' statement is issued, table data can be
modified (by the current session or other sessions) and these
modifications might be only partially visible to 'HANDLER ... NEXT' or
'HANDLER ... PREV' scans.

An open handler can be closed and marked for reopen, in which case the
handler loses its position in the table.  This occurs when both of the
following circumstances are true:

   * Any session executes 'FLUSH TABLES' or DDL statements on the
     handler's table.

   * The session in which the handler is open executes non-'HANDLER'
     statements that use tables.

'TRUNCATE TABLE' for a table closes all handlers
for the table that were opened with 'HANDLER OPEN'.

If a table is flushed with 'FLUSH TABLES TBL_NAME WITH READ LOCK' was
opened with 'HANDLER', the handler is implicitly flushed and loses its
position.

13.2.5 INSERT Syntax
--------------------

     INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
         [INTO] TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         [(COL_NAME [, COL_NAME] ...)]
         {VALUES | VALUE} (VALUE_LIST) [, (VALUE_LIST)] ...
         [ON DUPLICATE KEY UPDATE ASSIGNMENT_LIST]

     INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
         [INTO] TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         SET ASSIGNMENT_LIST
         [ON DUPLICATE KEY UPDATE ASSIGNMENT_LIST]

     INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]
         [INTO] TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         [(COL_NAME [, COL_NAME] ...)]
         SELECT ...
         [ON DUPLICATE KEY UPDATE ASSIGNMENT_LIST]

     VALUE:
         {EXPR | DEFAULT}

     VALUE_LIST:
         VALUE [, VALUE] ...

     ASSIGNMENT:
         COL_NAME = VALUE

     ASSIGNMENT_LIST:
         ASSIGNMENT [, ASSIGNMENT] ...

'INSERT' inserts new rows into an existing table.  The
'INSERT ... VALUES' and 'INSERT ... SET'.
forms of the statement insert rows based on explicitly specified values.
The 'INSERT ... SELECT' form inserts rows selected
from another table or tables.  'INSERT' with an 'ON
DUPLICATE KEY UPDATE' clause enables existing rows to be updated if a
row to be inserted would cause a duplicate value in a 'UNIQUE' index or
'PRIMARY KEY'.

For additional information about 'INSERT ... SELECT'
and 'INSERT ... ON DUPLICATE KEY UPDATE',
see insert-select, and
insert-on-duplicate.

In MySQL 5.7, the 'DELAYED' keyword is accepted but ignored by the
server.  For the reasons for this, see insert-delayed,

Inserting into a table requires the 'INSERT' privilege for the table.
If the 'ON DUPLICATE KEY UPDATE' clause is used and a duplicate key
causes an 'UPDATE' to be performed instead, the statement
requires the 'UPDATE' privilege for the columns to be updated.  For
columns that are read but not modified you need only the 'SELECT'
privilege (such as for a column referenced only on the right hand side
of an COL_NAME=EXPR assignment in an 'ON DUPLICATE KEY UPDATE' clause).

When inserting into a partitioned table, you can control which
partitions and subpartitions accept new rows.  The 'PARTITION' option
takes a list of the comma-separated names of one or more partitions or
subpartitions (or both) of the table.  If any of the rows to be inserted
by a given 'INSERT' statement do not match one of the
partitions listed, the 'INSERT' statement fails with the
error 'Found a row not matching the given partition set'.  For more
information and examples, see partitioning-selection.

You can use 'REPLACE' instead of 'INSERT'.
to overwrite old rows.  'REPLACE' is the counterpart to
'INSERT IGNORE' in the treatment of new rows that contain
unique key values that duplicate old rows: The new rows replace the old
rows rather than being discarded.  See replace.

TBL_NAME is the table into which rows should be inserted.  Specify the
columns for which the statement provides values as follows:

   * Provide a parenthesized list of comma-separated column names
     following the table name.  In this case, a value for each named
     column must be provided by the 'VALUES' list or the 'SELECT'
     statement.

   * If you do not specify a list of column names for 'INSERT ... VALUES'
     or 'INSERT ... SELECT',
     values for every column in the table must be provided by the
     'VALUES' list or the 'SELECT' statement.  If you do
     not know the order of the columns in the table, use 'DESCRIBE
     TBL_NAME' to find out.

   * A 'SET' clause indicates columns explicitly by name, together with
     the value to assign each one.

Column values can be given in several ways:

   * If strict SQL mode is not enabled, any column not explicitly given
     a value is set to its default (explicit or implicit) value.  For
     example, if you specify a column list that does not name all the
     columns in the table, unnamed columns are set to their default
     values.  Default value assignment is described in
     data-type-defaults.  See also constraint-invalid-data.

     If strict SQL mode is enabled, an 'INSERT' statement
     generates an error if it does not specify an explicit value for
     every column that has no default value.  See sql-mode.

   * If both the column list and the 'VALUES' list are empty, see
     'INSERT' creates a row with each column set to its default
     value:

          INSERT INTO TBL_NAME () VALUES();

     If strict mode is not enabled, MySQL uses the implicit default
     value for any column that has no explicitly defined default.  If
     strict mode is enabled, an error occurs if any column has no
     default value.

   * Use the keyword 'DEFAULT' to set a column explicitly to its default
     value.  This makes it easier to write 'INSERT'.
     statements that assign values to all but a few columns, because it
     enables you to avoid writing an incomplete 'VALUES' list that does
     not include a value for each column in the table.  Otherwise, you
     must provide the list of column names corresponding to each value
     in the 'VALUES' list.

   * If a generated column is inserted into explicitly, the only
     permitted value is 'DEFAULT'.  For information about generated
     columns, see create-table-generated-columns.

   * In expressions, you can use 'DEFAULT(COL_NAME)' to produce the
     default value for column COL_NAME.

   * Type conversion of an expression EXPR that provides a column value
     might occur if the expression data type does not match the column
     data type.  Conversion of a given value can result in different
     inserted values depending on the column type.  For example,
     inserting the string ''1999.0e-2'' into an 'INT',
     see 'FLOAT',
     'DECIMAL(10,6)', or 'YEAR' column
     inserts the value '1999', '19.9921', '19.992100', or '1999',
     respectively.  The value stored in the 'INT'.
     and 'YEAR' columns is '1999' because the
     string-to-number conversion looks only at as much of the initial
     part of the string as may be considered a valid integer or year.
     For the 'FLOAT' and 'DECIMAL'
     columns, the string-to-number conversion
     considers the entire string a valid numeric value.

   * An expression EXPR can refer to any column that was set earlier in
     a value list.  For example, you can do this because the value for
     'col2' refers to 'col1', which has previously been assigned:

          INSERT INTO TBL_NAME (col1,col2) VALUES(15,col1*2);

     But the following is not legal, because the value for 'col1' refers
     to 'col2', which is assigned after 'col1':

          INSERT INTO TBL_NAME (col1,col2) VALUES(col2*2,15);

     An exception occurs for columns that contain 'AUTO_INCREMENT'
     values.  Because 'AUTO_INCREMENT' values are generated after other
     value assignments, any reference to an 'AUTO_INCREMENT' column in
     the assignment returns a '0'.

'INSERT' statements that use 'VALUES' syntax can insert
multiple rows.  To do this, include multiple lists of comma-separated
column values, with lists enclosed within parentheses and separated by
commas.  Example:

     INSERT INTO TBL_NAME (a,b,c) VALUES(1,2,3),(4,5,6),(7,8,9);

Each values list must contain exactly as many values as are to be
inserted per row.  The following statement is invalid because it
contains one list of nine values, rather than three lists of three
values each:

     INSERT INTO TBL_NAME (a,b,c) VALUES(1,2,3,4,5,6,7,8,9);

'VALUE' is a synonym for 'VALUES' in this context.  Neither implies
anything about the number of values lists, nor about the number of
values per list.  Either may be used whether there is a single values
list or multiple lists, and regardless of the number of values per list.

The affected-rows value for an 'INSERT' can be obtained
using the 'ROW_COUNT()' SQL function or the
'mysql_affected_rows()'. C API function.  See
information-functions, and mysql-affected-rows.

If you use an 'INSERT ... VALUES' statement with multiple
value lists or 'INSERT ... SELECT', the statement
returns an information string in this format:

     Records: N1 Duplicates: N2 Warnings: N3

If you are using the C API, the information string can be obtained by
invoking the 'mysql_info()' function.  See
mysql-info.

'Records' indicates the number of rows processed by the statement.
(This is not necessarily the number of rows actually inserted because
'Duplicates' can be nonzero.)  'Duplicates' indicates the number of rows
that could not be inserted because they would duplicate some existing
unique index value.  'Warnings' indicates the number of attempts to
insert column values that were problematic in some way.  Warnings can
occur under any of the following conditions:

   * Inserting 'NULL' into a column that has been declared 'NOT NULL'.
     For multiple-row 'INSERT' statements or
     'INSERT INTO ... SELECT' statements, the column is
     set to the implicit default value for the column data type.  This
     is '0' for numeric types, the empty string ('''') for string types,
     and the 'zero' value for date and time types.  'INSERT INTO ... SELECT'
     statements are handled the same way as
     multiple-row inserts because the server does not examine the result
     set from the 'SELECT' to see whether it returns a
     single row.  (For a single-row 'INSERT', no warning
     occurs when 'NULL' is inserted into a 'NOT NULL' column.  Instead,
     the statement fails with an error.)

   * Setting a numeric column to a value that lies outside the column's
     range.  The value is clipped to the closest endpoint of the range.

   * Assigning a value such as ''10.34 a'' to a numeric column.  The
     trailing nonnumeric text is stripped off and the remaining numeric
     part is inserted.  If the string value has no leading numeric part,
     the column is set to '0'.

   * Inserting a string into a string column (see 'CHAR',
     'VARCHAR', 'TEXT', or 'BLOB') that
     exceeds the column's maximum length.  The value is truncated to the
     column's maximum length.

   * Inserting a value into a date or time column that is illegal for
     the data type.  The column is set to the appropriate zero value for
     the type.

If 'INSERT' inserts a row into a table that has an
'AUTO_INCREMENT' column, you can find the value used for that column by
using the 'LAST_INSERT_ID()' SQL function or the
'mysql_insert_id()'. C API function.

*Note*:

These two functions do not always behave identically.  The behavior of
'INSERT' statements with respect to 'AUTO_INCREMENT'
columns is discussed further in information-functions, and
mysql-insert-id.

The 'INSERT' statement supports the following modifiers:

   * If you use the 'LOW_PRIORITY' modifier, execution of the
     'INSERT' is delayed until no other clients are reading
     from the table.  This includes other clients that began reading
     while existing clients are reading, and while the 'INSERT
     LOW_PRIORITY' statement is waiting.  It is possible, therefore, for
     a client that issues an 'INSERT LOW_PRIORITY' statement to wait for
     a very long time.

     'LOW_PRIORITY' affects only storage engines that use only
     table-level locking (such as 'MyISAM', 'MEMORY', and 'MERGE').

     *Note*:

     'LOW_PRIORITY' should normally not be used with 'MyISAM' tables
     because doing so disables concurrent inserts.  See
     concurrent-inserts.

   * If you specify 'HIGH_PRIORITY', it overrides the effect of the
     '--low-priority-updates' option if the server was started with that
     option.  It also causes concurrent inserts not to be used.  See
     concurrent-inserts.

     'HIGH_PRIORITY' affects only storage engines that use only
     table-level locking (such as 'MyISAM', 'MEMORY', and 'MERGE').

   * If you use the 'IGNORE' modifier, errors that occur while executing
     the 'INSERT' statement are ignored.  For example,
     without 'IGNORE', a row that duplicates an existing 'UNIQUE' index
     or 'PRIMARY KEY' value in the table causes a duplicate-key error
     and the statement is aborted.  With 'IGNORE', the row is discarded
     and no error occurs.  Ignored errors generate warnings instead.

     'IGNORE' has a similar effect on inserts into partitioned tables
     where no partition matching a given value is found.  Without
     'IGNORE', such 'INSERT' statements are aborted with
     an error.  When 'INSERT IGNORE' is used, the insert
     operation fails silently for rows containing the unmatched value,
     but inserts rows that are matched.  For an example, see
     partitioning-list.

     Data conversions that would trigger errors abort the statement if
     'IGNORE' is not specified.  With 'IGNORE', invalid values are
     adjusted to the closest values and inserted; warnings are produced
     but the statement does not abort.  You can determine with the
     'mysql_info()'. C API function how many rows were
     actually inserted into the table.

     For more information, see ignore-strict-comparison.

   * If you specify 'ON DUPLICATE KEY UPDATE', and a row is inserted
     that would cause a duplicate value in a 'UNIQUE' index or 'PRIMARY
     KEY', an 'UPDATE' of the old row occurs.  The
     affected-rows value per row is 1 if the row is inserted as a new
     row, 2 if an existing row is updated, and 0 if an existing row is
     set to its current values.  If you specify the 'CLIENT_FOUND_ROWS'
     flag to the 'mysql_real_connect()'. C API
     function when connecting to 'mysqld', the
     affected-rows value is 1 (not 0) if an existing row is set to its
     current values.  See insert-on-duplicate.

   * 'INSERT DELAYED' was deprecated in MySQL
     5.6, and is scheduled for eventual removal.  In MySQL 5.7, the
     'DELAYED' modifier is accepted but ignored.  Use 'INSERT' (without
     'DELAYED') instead.  See insert-delayed.

An 'INSERT' statement affecting a partitioned table using a storage
engine such as 'MyISAM' that employs
table-level locks locks only those partitions into which rows are
actually inserted.  (For storage engines such as 'InnoDB'
that employ row-level locking, no locking of
partitions takes place.)  For more information, see
partitioning-limitations-locking.

13.2.5.1 INSERT ... SELECT Syntax
.................................

     INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]
         [INTO] TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         [(COL_NAME [, COL_NAME] ...)]
         SELECT ...
         [ON DUPLICATE KEY UPDATE ASSIGNMENT_LIST]

     VALUE:
         {EXPR | DEFAULT}

     ASSIGNMENT:
         COL_NAME = VALUE

     ASSIGNMENT_LIST:
         ASSIGNMENT [, ASSIGNMENT] ...

With 'INSERT ... SELECT', you can quickly insert
many rows into a table from the result of a 'SELECT'.
statement, which can select from one or many tables.  For example:

     INSERT INTO tbl_temp2 (fld_id)
       SELECT tbl_temp1.fld_order_id
       FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;

The following conditions hold for 'INSERT ... SELECT'
statements:

   * Specify 'IGNORE' to ignore rows that would cause duplicate-key
     violations.

   * The target table of the 'INSERT' statement may
     appear in the 'FROM' clause of the 'SELECT' part of
     the query.  However, you cannot insert into a table and select from
     the same table in a subquery.

     When selecting from and inserting into the same table, MySQL
     creates an internal temporary table to hold the rows from the
     'SELECT' and then inserts those rows into the target
     table.  However, you cannot use 'INSERT INTO t ... SELECT ... FROM
     t' when 't' is a 'TEMPORARY' table, because 'TEMPORARY' tables
     cannot be referred to twice in the same statement.  See
     internal-temporary-tables, and temporary-table-problems.

   * 'AUTO_INCREMENT' columns work as usual.

   * To ensure that the binary log can be used to re-create the original
     tables, MySQL does not permit concurrent inserts for 'INSERT ... SELECT'
     statements (see
     concurrent-inserts).

   * To avoid ambiguous column reference problems when the
     'SELECT' and the 'INSERT' refer to the same
     table, provide a unique alias for each table used in the
     'SELECT' part, and qualify column names in that part with
     the appropriate alias.

You can explicitly select which partitions or subpartitions (or both) of
the source or target table (or both) are to be used with a 'PARTITION'
option following the name of the table.  When 'PARTITION' is used with
the name of the source table in the 'SELECT' portion of
the statement, rows are selected only from the partitions or
subpartitions named in its partition list.  When 'PARTITION' is used
with the name of the target table for the 'INSERT'.
portion of the statement, it must be possible to insert all rows
selected into the partitions or subpartitions named in the partition
list following the option.  Otherwise, the 'INSERT ... SELECT' statement
fails.  For more information and examples, see
partitioning-selection.

For 'INSERT ... SELECT' statements, see
insert-on-duplicate for conditions under which the
'SELECT' columns can be referred to in an 'ON DUPLICATE KEY
UPDATE' clause.

The order in which a 'SELECT' statement with no 'ORDER
BY' clause returns rows is nondeterministic.  This means that, when
using replication, there is no guarantee that such a 'SELECT'
returns rows in the same order on the master and the slave,
which can lead to inconsistencies between them.  To prevent this from
occurring, always write 'INSERT ... SELECT' statements that are to be
replicated using an 'ORDER BY' clause that produces the same row order
on the master and the slave.  See also
replication-features-limit.

Due to this issue, see 'INSERT ... SELECT ON DUPLICATE KEY UPDATE'
and 'INSERT IGNORE ... SELECT'
statements are flagged as unsafe for statement-based
replication.  Such statements produce a warning in the error log when
using statement-based mode and are written to the binary log using the
row-based format when using 'MIXED' mode.  (Bug #11758262, Bug #50439)

See also replication-sbr-rbr.

An 'INSERT ... SELECT' statement affecting partitioned tables using a
storage engine such as 'MyISAM' that
employs table-level locks locks all partitions of the target table;
however, only those partitions that are actually read from the source
table are locked.  (This does not occur with tables using storage
engines such as 'InnoDB' that employ
row-level locking.)  For more information, see
partitioning-limitations-locking.

13.2.5.2 INSERT ... ON DUPLICATE KEY UPDATE Syntax
..................................................

If you specify an 'ON DUPLICATE KEY UPDATE' clause and a row to be
inserted would cause a duplicate value in a 'UNIQUE' index or 'PRIMARY
KEY', an 'UPDATE' of the old row occurs.  For example, if
column 'a' is declared as 'UNIQUE' and contains the value '1', the
following two statements have similar effect:

     INSERT INTO t1 (a,b,c) VALUES (1,2,3)
       ON DUPLICATE KEY UPDATE c=c+1;

     UPDATE t1 SET c=c+1 WHERE a=1;

(The effects are not identical for an 'InnoDB' table where 'a' is an
auto-increment column.  With an auto-increment column, an 'INSERT'
statement increases the auto-increment value but 'UPDATE' does not.)

If column 'b' is also unique, the 'INSERT' is equivalent
to this 'UPDATE' statement instead:

     UPDATE t1 SET c=c+1 WHERE a=1 OR b=2 LIMIT 1;

If 'a=1 OR b=2' matches several rows, only _one_ row is updated.  In
general, you should try to avoid using an 'ON DUPLICATE KEY UPDATE'
clause on tables with multiple unique indexes.

With 'ON DUPLICATE KEY UPDATE', the affected-rows value per row is 1 if
the row is inserted as a new row, 2 if an existing row is updated, and 0
if an existing row is set to its current values.  If you specify the
'CLIENT_FOUND_ROWS' flag to the 'mysql_real_connect()'.
C API function when connecting to 'mysqld',
the affected-rows value is 1 (not 0) if an existing row is set
to its current values.

If a table contains an 'AUTO_INCREMENT' column and 'INSERT ... ON DUPLICATE KEY UPDATE'
inserts or updates a row,
the 'LAST_INSERT_ID()' function returns the 'AUTO_INCREMENT' value.

The 'ON DUPLICATE KEY UPDATE' clause can contain multiple column
assignments, separated by commas.

In assignment value expressions in the 'ON DUPLICATE KEY UPDATE' clause,
you can use the 'VALUES(COL_NAME)' function to refer to column values
from the 'INSERT' portion of the 'INSERT ... ON DUPLICATE KEY UPDATE'
statement.  In other words,
'VALUES(COL_NAME)' in the 'ON DUPLICATE KEY UPDATE' clause refers to the
value of COL_NAME that would be inserted, had no duplicate-key conflict
occurred.  This function is especially useful in multiple-row inserts.
The 'VALUES()' function is meaningful only in the 'ON DUPLICATE KEY
UPDATE' clause or 'INSERT' statements and returns 'NULL'
otherwise.  Example:

     INSERT INTO t1 (a,b,c) VALUES (1,2,3),(4,5,6)
       ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);

That statement is identical to the following two statements:

     INSERT INTO t1 (a,b,c) VALUES (1,2,3)
       ON DUPLICATE KEY UPDATE c=3;
     INSERT INTO t1 (a,b,c) VALUES (4,5,6)
       ON DUPLICATE KEY UPDATE c=9;

For 'INSERT ... SELECT' statements, these
rules apply regarding acceptable forms of 'SELECT' query expressions
that you can refer to in an 'ON DUPLICATE KEY UPDATE' clause:

   * References to columns from queries on a single table, which may be
     a derived table.

   * References to columns from queries on a join over multiple tables.

   * References to columns from 'DISTINCT' queries.

   * References to columns in other tables, as long as the
     'SELECT' does not use 'GROUP BY'.  One side effect is that
     you must qualify references to nonunique column names.

References to columns from a 'UNION' do not work reliably.
To work around this restriction, rewrite the 'UNION' as a
derived table so that its rows can be treated as a single-table result
set.  For example, this statement can produce incorrect results:

     INSERT INTO t1 (a, b)
       SELECT c, d FROM t2
       UNION
       SELECT e, f FROM t3
     ON DUPLICATE KEY UPDATE b = b + c;

Instead, use an equivalent statement that rewrites the 'UNION'
as a derived table:

     INSERT INTO t1 (a, b)
     SELECT * FROM
       (SELECT c, d FROM t2
        UNION
        SELECT e, f FROM t3) AS dt
     ON DUPLICATE KEY UPDATE b = b + c;

The technique of rewriting a query as a derived table also enables
references to columns from 'GROUP BY' queries.

Because the results of 'INSERT ... SELECT'.
statements depend on the ordering of rows from the 'SELECT'
and this order cannot always be guaranteed, it is possible when
logging 'INSERT ... SELECT ON DUPLICATE KEY UPDATE'
statements for the master and the slave to diverge.
Thus, see 'INSERT ... SELECT ON DUPLICATE KEY UPDATE'
statements are flagged as unsafe for
statement-based replication.  Such statements produce a warning in the
error log when using statement-based mode and are written to the binary
log using the row-based format when using 'MIXED' mode.  An
'INSERT ... ON DUPLICATE KEY UPDATE' statement
against a table having more than one unique or primary key is also
marked as unsafe.  (Bug #11765650, Bug #58637)

See also replication-sbr-rbr.

An 'INSERT ... ON DUPLICATE KEY UPDATE' on a partitioned table using a
storage engine such as 'MyISAM' that
employs table-level locks locks any partitions of the table in which a
partitioning key column is updated.  (This does not occur with tables
using storage engines such as 'InnoDB'.
that employ row-level locking.)  For more information, see
partitioning-limitations-locking.

13.2.5.3 INSERT DELAYED Syntax
..............................

     INSERT DELAYED ...

The 'DELAYED' option for the 'INSERT' statement is a
MySQL extension to standard SQL. In previous versions of MySQL, it can
be used for certain kinds of tables (such as 'MyISAM'), such that when a
client uses 'INSERT DELAYED', it gets an okay from
the server at once, and the row is queued to be inserted when the table
is not in use by any other thread.

'DELAYED' inserts and replaces were deprecated in MySQL 5.6.  In MySQL
5.7, 'DELAYED' is not supported.  The server recognizes but ignores the
'DELAYED' keyword, handles the insert as a nondelayed insert, and
generates an 'ER_WARN_LEGACY_SYNTAX_CONVERTED' warning ('INSERT DELAYED
is no longer supported. The statement was converted to INSERT').  The
'DELAYED' keyword is scheduled for removal in a future release.

13.2.6 LOAD DATA INFILE Syntax
------------------------------

     LOAD DATA [LOW_PRIORITY | CONCURRENT] [LOCAL] INFILE 'FILE_NAME'
         [REPLACE | IGNORE]
         INTO TABLE TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         [CHARACTER SET CHARSET_NAME]
         [{FIELDS | COLUMNS}
             [TERMINATED BY 'STRING']
             [[OPTIONALLY] ENCLOSED BY 'CHAR']
             [ESCAPED BY 'CHAR']
         ]
         [LINES
             [STARTING BY 'STRING']
             [TERMINATED BY 'STRING']
         ]
         [IGNORE NUMBER {LINES | ROWS}]
         [(COL_NAME_OR_USER_VAR
             [, COL_NAME_OR_USER_VAR] ...)]
         [SET COL_NAME={EXPR | DEFAULT},
             [, COL_NAME={EXPR | DEFAULT}] ...]

The 'LOAD DATA INFILE' statement reads rows from a
text file into a table at a very high speed.  'LOAD DATA INFILE'
is the complement of 'SELECT ... INTO OUTFILE'.
(See select-into.)  To write data from a table to
a file, use 'SELECT ... INTO OUTFILE'.  To read the
file back into a table, use 'LOAD DATA INFILE'.  The
syntax of the 'FIELDS' and 'LINES' clauses is the same for both
statements.  Both clauses are optional, but 'FIELDS' must precede
'LINES' if both are specified.

You can also load data files by using the 'mysqlimport'
utility; it operates by sending a 'LOAD DATA INFILE'
statement to the server.  The '--local' option causes
'mysqlimport' to read data files from the client host.
You can specify the '--compress' option to get better performance over
slow networks if the client and server support the compressed protocol.
See mysqlimport.

For more information about the efficiency of 'INSERT'.
versus 'LOAD DATA INFILE' and speeding up 'LOAD DATA INFILE',
see insert-optimization.

The file name must be given as a literal string.  On Windows, specify
backslashes in path names as forward slashes or doubled backslashes.
The 'character_set_filesystem' system variable controls the
interpretation of the file name.

'LOAD DATA' supports explicit partition selection using the 'PARTITION'
option with a list of one or more comma-separated names of partitions,
subpartitions, or both.  When this option is used, if any rows from the
file cannot be inserted into any of the partitions or subpartitions
named in the list, the statement fails with the error 'Found a row not
matching the given partition set'.  For more information and examples,
see partitioning-selection.

For partitioned tables using storage engines that employ table locks,
such as 'MyISAM', 'LOAD DATA' cannot prune
any partition locks.  This does not apply to tables using storage
engines which employ row-level locking, such as 'InnoDB'.
For more information, see
partitioning-limitations-locking.

The server uses the character set indicated by the
'character_set_database' system variable to interpret the information in
the file.  'SET NAMES' and the setting of
'character_set_client' do not affect interpretation of input.  If the
contents of the input file use a character set that differs from the
default, it is usually preferable to specify the character set of the
file by using the 'CHARACTER SET' clause.  A character set of 'binary'
specifies 'no conversion.'

'LOAD DATA INFILE' interprets all fields in the file
as having the same character set, regardless of the data types of the
columns into which field values are loaded.  For proper interpretation
of file contents, you must ensure that it was written with the correct
character set.  For example, if you write a data file with
'mysqldump -T' or by issuing a 'SELECT ... INTO OUTFILE'
statement in 'mysql', be sure to use
a '--default-character-set' option so that output is written in the
character set to be used when the file is loaded with 'LOAD DATA INFILE'.

*Note*:

It is not possible to load data files that use the 'ucs2', 'utf16',
'utf16le', or 'utf32' character set.

If you use 'LOW_PRIORITY', execution of the 'LOAD DATA'
statement is delayed until no other clients are reading from
the table.  This affects only storage engines that use only table-level
locking (such as 'MyISAM', 'MEMORY', and 'MERGE').

If you specify 'CONCURRENT' with a 'MyISAM' table that satisfies the
condition for concurrent inserts (that is, it contains no free blocks in
the middle), other threads can retrieve data from the table while
'LOAD DATA' is executing.  This option affects the
performance of 'LOAD DATA' a bit, even if no other
thread is using the table at the same time.

With row-based replication, 'CONCURRENT' is replicated regardless of
MySQL version.  With statement-based replication 'CONCURRENT' is not
replicated prior to MySQL 5.5.1 (see Bug #34628).  For more information,
see replication-features-load-data.

The 'LOCAL' keyword affects expected location of the file and error
handling, as described later.  'LOCAL' works only if your server and
your client both have been configured to permit it.  For example, if
'mysqld' was started with the 'local_infile' system
variable disabled, 'LOCAL' does not work.  See load-data-local.

The 'LOCAL' keyword affects where the file is expected to be found:

   * If 'LOCAL' is specified, the file is read by the client program on
     the client host and sent to the server.  The file can be given as a
     full path name to specify its exact location.  If given as a
     relative path name, the name is interpreted relative to the
     directory in which the client program was started.

     When using 'LOCAL' with 'LOAD DATA', a copy of the
     file is created in the server's temporary directory.  This is _not_
     the directory determined by the value of 'tmpdir' or
     'slave_load_tmpdir', but rather the operating system's temporary
     directory, and is not configurable in the MySQL Server.  (Typically
     the system temporary directory is '/tmp' on Linux systems and
     'C:\WINDOWS\TEMP' on Windows.)  Lack of sufficient space for the
     copy in this directory can cause the 'LOAD DATA LOCAL'
     statement to fail.

   * If 'LOCAL' is not specified, the file must be located on the server
     host and is read directly by the server.  The server uses the
     following rules to locate the file:

        * If the file name is an absolute path name, the server uses it
          as given.

        * If the file name is a relative path name with one or more
          leading components, the server searches for the file relative
          to the server's data directory.

        * If a file name with no leading components is given, the server
          looks for the file in the database directory of the default
          database.

In the non-'LOCAL' case, these rules mean that a file named as
'./myfile.txt' is read from the server's data directory, whereas the
file named as 'myfile.txt' is read from the database directory of the
default database.  For example, if 'db1' is the default database, the
following 'LOAD DATA' statement reads the file
'data.txt' from the database directory for 'db1', even though the
statement explicitly loads the file into a table in the 'db2' database:

     LOAD DATA INFILE 'data.txt' INTO TABLE db2.my_table;

Non-'LOCAL' load operations read text files located on the server.  For
security reasons, such operations require that you have the 'FILE'
privilege.  See privileges-provided.  Also, non-'LOCAL' load
operations are subject to the 'secure_file_priv' system variable
setting.  If the variable value is a nonempty directory name, the file
to be loaded must be located in that directory.  If the variable value
is empty (which is insecure), the file need only be readable by the
server.

Using 'LOCAL' is a bit slower than letting the server access the files
directly, because the contents of the file must be sent over the
connection by the client to the server.  On the other hand, you do not
need the 'FILE' privilege to load local files.

'LOCAL' also affects error handling:

   * With 'LOAD DATA INFILE', data-interpretation and
     duplicate-key errors terminate the operation.

   * With 'LOAD DATA LOCAL INFILE', data-interpretation
     and duplicate-key errors become warnings and the operation
     continues because the server has no way to stop transmission of the
     file in the middle of the operation.  For duplicate-key errors,
     this is the same as if 'IGNORE' is specified.  'IGNORE' is
     explained further later in this section.

The 'REPLACE' and 'IGNORE' keywords control handling of input rows that
duplicate existing rows on unique key values:

   * If you specify 'REPLACE', input rows replace existing rows.  In
     other words, rows that have the same value for a primary key or
     unique index as an existing row.  See replace.

   * If you specify 'IGNORE', rows that duplicate an existing row on a
     unique key value are discarded.  For more information, see
     ignore-strict-comparison.

   * If you do not specify either option, the behavior depends on
     whether the 'LOCAL' keyword is specified.  Without 'LOCAL', an
     error occurs when a duplicate key value is found, and the rest of
     the text file is ignored.  With 'LOCAL', the default behavior is
     the same as if 'IGNORE' is specified; this is because the server
     has no way to stop transmission of the file in the middle of the
     operation.

To ignore foreign key constraints during the load operation, issue a
'SET foreign_key_checks = 0' statement before executing 'LOAD DATA'.

If you use 'LOAD DATA INFILE' on an empty 'MyISAM'
table, all nonunique indexes are created in a separate batch (as for
'REPAIR TABLE').  Normally, this makes 'LOAD DATA INFILE'
much faster when you have many indexes.  In
some extreme cases, you can create the indexes even faster by turning
them off with 'ALTER TABLE ... DISABLE KEYS' before loading the file
into the table and using 'ALTER TABLE ... ENABLE KEYS' to re-create the
indexes after loading the file.  See insert-optimization.

For both the 'LOAD DATA INFILE' and 'SELECT ... INTO OUTFILE'
statements, the syntax of the 'FIELDS' and
'LINES' clauses is the same.  Both clauses are optional, but 'FIELDS'
must precede 'LINES' if both are specified.

If you specify a 'FIELDS' clause, each of its subclauses ('TERMINATED
BY', '[OPTIONALLY] ENCLOSED BY', and 'ESCAPED BY') is also optional,
except that you must specify at least one of them.

If you specify no 'FIELDS' or 'LINES' clause, the defaults are the same
as if you had written this:

     FIELDS TERMINATED BY '\t' ENCLOSED BY '' ESCAPED BY '\\'
     LINES TERMINATED BY '\n' STARTING BY ''

(Backslash is the MySQL escape character within strings in SQL
statements, so to specify a literal backslash, you must specify two
backslashes for the value to be interpreted as a single backslash.  The
escape sequences ''\t'' and ''\n'' specify tab and newline characters,
respectively.)

In other words, the defaults cause 'LOAD DATA INFILE'.
to act as follows when reading input:

   * Look for line boundaries at newlines.

   * Do not skip over any line prefix.

   * Break lines into fields at tabs.

   * Do not expect fields to be enclosed within any quoting characters.

   * Interpret characters preceded by the escape character '\' as escape
     sequences.  For example, '\t', '\n', and '\\' signify tab, newline,
     and backslash, respectively.  See the discussion of 'FIELDS ESCAPED
     BY' later for the full list of escape sequences.

Conversely, the defaults cause 'SELECT ... INTO OUTFILE'
to act as follows when writing output:

   * Write tabs between fields.

   * Do not enclose fields within any quoting characters.

   * Use '\' to escape instances of tab, newline, or '\' that occur
     within field values.

   * Write newlines at the ends of lines.

*Note*:

If you have generated the text file on a Windows system, you might have
to use 'LINES TERMINATED BY '\r\n'' to read the file properly, because
Windows programs typically use two characters as a line terminator.
Some programs, such as 'WordPad', might use '\r' as a line terminator
when writing files.  To read such files, use 'LINES TERMINATED BY '\r''.

If all the lines you want to read in have a common prefix that you want
to ignore, you can use 'LINES STARTING BY 'PREFIX_STRING'' to skip over
the prefix, _and anything before it_.  If a line does not include the
prefix, the entire line is skipped.  Suppose that you issue the
following statement:

     LOAD DATA INFILE '/tmp/test.txt' INTO TABLE test
       FIELDS TERMINATED BY ','  LINES STARTING BY 'xxx';

If the data file looks like this:

     xxx"abc",1
     something xxx"def",2
     "ghi",3

The resulting rows will be '("abc",1)' and '("def",2)'.  The third row
in the file is skipped because it does not contain the prefix.

The 'IGNORE NUMBER LINES' option can be used to ignore lines at the
start of the file.  For example, you can use 'IGNORE 1 LINES' to skip
over an initial header line containing column names:

     LOAD DATA INFILE '/tmp/test.txt' INTO TABLE test IGNORE 1 LINES;

When you use 'SELECT ... INTO OUTFILE' in tandem
with 'LOAD DATA INFILE' to write data from a database
into a file and then read the file back into the database later, the
field- and line-handling options for both statements must match.
Otherwise, see 'LOAD DATA INFILE' will not interpret the
contents of the file properly.  Suppose that you use 'SELECT ... INTO OUTFILE'
to write a file with fields delimited by
commas:

     SELECT * INTO OUTFILE 'data.txt'
       FIELDS TERMINATED BY ','
       FROM table2;

To read the comma-delimited file back in, the correct statement would
be:

     LOAD DATA INFILE 'data.txt' INTO TABLE table2
       FIELDS TERMINATED BY ',';

If instead you tried to read in the file with the statement shown
following, it wouldn't work because it instructs 'LOAD DATA INFILE'
to look for tabs between fields:

     LOAD DATA INFILE 'data.txt' INTO TABLE table2
       FIELDS TERMINATED BY '\t';

The likely result is that each input line would be interpreted as a
single field.

'LOAD DATA INFILE' can be used to read files obtained
from external sources.  For example, many programs can export data in
comma-separated values (CSV) format, such that lines have fields
separated by commas and enclosed within double quotation marks, with an
initial line of column names.  If the lines in such a file are
terminated by carriage return/newline pairs, the statement shown here
illustrates the field- and line-handling options you would use to load
the file:

     LOAD DATA INFILE 'data.txt' INTO TABLE TBL_NAME
       FIELDS TERMINATED BY ',' ENCLOSED BY '"'
       LINES TERMINATED BY '\r\n'
       IGNORE 1 LINES;

If the input values are not necessarily enclosed within quotation marks,
use 'OPTIONALLY' before the 'ENCLOSED BY' keywords.

Any of the field- or line-handling options can specify an empty string
('''').  If not empty, the 'FIELDS [OPTIONALLY] ENCLOSED BY' and 'FIELDS
ESCAPED BY' values must be a single character.  The 'FIELDS TERMINATED
BY', 'LINES STARTING BY', and 'LINES TERMINATED BY' values can be more
than one character.  For example, to write lines that are terminated by
carriage return/linefeed pairs, or to read a file containing such lines,
specify a 'LINES TERMINATED BY '\r\n'' clause.

To read a file containing jokes that are separated by lines consisting
of '%%', you can do this

     CREATE TABLE jokes
       (a INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
       joke TEXT NOT NULL);
     LOAD DATA INFILE '/tmp/jokes.txt' INTO TABLE jokes
       FIELDS TERMINATED BY ''
       LINES TERMINATED BY '\n%%\n' (joke);

'FIELDS [OPTIONALLY] ENCLOSED BY' controls quoting of fields.  For
output (see 'SELECT ... INTO OUTFILE'), if you omit the
word 'OPTIONALLY', all fields are enclosed by the 'ENCLOSED BY'
character.  An example of such output (using a comma as the field
delimiter) is shown here:

     "1","a string","100.20"
     "2","a string containing a , comma","102.20"
     "3","a string containing a \" quote","102.20"
     "4","a string containing a \", quote and comma","102.20"

If you specify 'OPTIONALLY', the 'ENCLOSED BY' character is used only to
enclose values from columns that have a string data type (such as
'CHAR', 'BINARY', 'TEXT', or
'ENUM'):

     1,"a string",100.20
     2,"a string containing a , comma",102.20
     3,"a string containing a \" quote",102.20
     4,"a string containing a \", quote and comma",102.20

Occurrences of the 'ENCLOSED BY' character within a field value are
escaped by prefixing them with the 'ESCAPED BY' character.  Also, if you
specify an empty 'ESCAPED BY' value, it is possible to inadvertently
generate output that cannot be read properly by 'LOAD DATA INFILE'.
For example, the preceding output just shown would
appear as follows if the escape character is empty.  Observe that the
second field in the fourth line contains a comma following the quote,
which (erroneously) appears to terminate the field:

     1,"a string",100.20
     2,"a string containing a , comma",102.20
     3,"a string containing a " quote",102.20
     4,"a string containing a ", quote and comma",102.20

For input, the 'ENCLOSED BY' character, if present, is stripped from the
ends of field values.  (This is true regardless of whether 'OPTIONALLY'
is specified; 'OPTIONALLY' has no effect on input interpretation.)
Occurrences of the 'ENCLOSED BY' character preceded by the 'ESCAPED BY'
character are interpreted as part of the current field value.

If the field begins with the 'ENCLOSED BY' character, instances of that
character are recognized as terminating a field value only if followed
by the field or line 'TERMINATED BY' sequence.  To avoid ambiguity,
occurrences of the 'ENCLOSED BY' character within a field value can be
doubled and are interpreted as a single instance of the character.  For
example, if 'ENCLOSED BY '"'' is specified, quotation marks are handled
as shown here:

     "The ""BIG"" boss"  -> The "BIG" boss
     The "BIG" boss      -> The "BIG" boss
     The ""BIG"" boss    -> The ""BIG"" boss

'FIELDS ESCAPED BY' controls how to read or write special characters:

   * For input, if the 'FIELDS ESCAPED BY' character is not empty,
     occurrences of that character are stripped and the following
     character is taken literally as part of a field value.  Some
     two-character sequences that are exceptions, where the first
     character is the escape character.  These sequences are shown in
     the following table (using '\' for the escape character).  The
     rules for 'NULL' handling are described later in this section.

     Character   Escape Sequence

     '\0'        An ASCII NUL ('X'00'') character

     '\b'        A backspace character

     '\n'        A newline (linefeed) character

     '\r'        A carriage return character

     '\t'        A tab character.

     '\Z'        ASCII 26 (Control+Z)

     '\N'        NULL

     For more information about '\'-escape syntax, see
     string-literals.

     If the 'FIELDS ESCAPED BY' character is empty, escape-sequence
     interpretation does not occur.

   * For output, if the 'FIELDS ESCAPED BY' character is not empty, it
     is used to prefix the following characters on output:

        * The 'FIELDS ESCAPED BY' character

        * The 'FIELDS [OPTIONALLY] ENCLOSED BY' character

        * The first character of the 'FIELDS TERMINATED BY' and 'LINES
          TERMINATED BY' values

        * ASCII '0' (what is actually written following the escape
          character is ASCII '0', not a zero-valued byte)

     If the 'FIELDS ESCAPED BY' character is empty, no characters are
     escaped and 'NULL' is output as 'NULL', not '\N'.  It is probably
     not a good idea to specify an empty escape character, particularly
     if field values in your data contain any of the characters in the
     list just given.

In certain cases, field- and line-handling options interact:

   * If 'LINES TERMINATED BY' is an empty string and 'FIELDS TERMINATED
     BY' is nonempty, lines are also terminated with 'FIELDS TERMINATED
     BY'.

   * If the 'FIELDS TERMINATED BY' and 'FIELDS ENCLOSED BY' values are
     both empty (''''), a fixed-row (nondelimited) format is used.  With
     fixed-row format, no delimiters are used between fields (but you
     can still have a line terminator).  Instead, column values are read
     and written using a field width wide enough to hold all values in
     the field.  For 'TINYINT', 'SMALLINT',
     see 'MEDIUMINT', 'INT',
     and 'BIGINT', the field widths
     are 4, 6, 8, 11, and 20, respectively, no matter what the declared
     display width is.

     'LINES TERMINATED BY' is still used to separate lines.  If a line
     does not contain all fields, the rest of the columns are set to
     their default values.  If you do not have a line terminator, you
     should set this to ''''.  In this case, the text file must contain
     all fields for each row.

     Fixed-row format also affects handling of 'NULL' values, as
     described later.

     *Note*:

     Fixed-size format does not work if you are using a multibyte
     character set.

Handling of 'NULL' values varies according to the 'FIELDS' and 'LINES'
options in use:

   * For the default 'FIELDS' and 'LINES' values, 'NULL' is written as a
     field value of '\N' for output, and a field value of '\N' is read
     as 'NULL' for input (assuming that the 'ESCAPED BY' character is
     '\').

   * If 'FIELDS ENCLOSED BY' is not empty, a field containing the
     literal word 'NULL' as its value is read as a 'NULL' value.  This
     differs from the word 'NULL' enclosed within 'FIELDS ENCLOSED BY'
     characters, which is read as the string ''NULL''.

   * If 'FIELDS ESCAPED BY' is empty, 'NULL' is written as the word
     'NULL'.

   * With fixed-row format (which is used when 'FIELDS TERMINATED BY'
     and 'FIELDS ENCLOSED BY' are both empty), 'NULL' is written as an
     empty string.  This causes both 'NULL' values and empty strings in
     the table to be indistinguishable when written to the file because
     both are written as empty strings.  If you need to be able to tell
     the two apart when reading the file back in, you should not use
     fixed-row format.

An attempt to load 'NULL' into a 'NOT NULL' column causes assignment of
the implicit default value for the column's data type and a warning, or
an error in strict SQL mode.  Implicit default values are discussed in
data-type-defaults.

Some cases are not supported by 'LOAD DATA INFILE'.:

   * Fixed-size rows ('FIELDS TERMINATED BY' and 'FIELDS ENCLOSED BY'
     both empty) and 'BLOB' or 'TEXT' columns.

   * If you specify one separator that is the same as or a prefix of
     another, see 'LOAD DATA INFILE' cannot interpret the
     input properly.  For example, the following 'FIELDS' clause would
     cause problems:

          FIELDS TERMINATED BY '"' ENCLOSED BY '"'

   * If 'FIELDS ESCAPED BY' is empty, a field value that contains an
     occurrence of 'FIELDS ENCLOSED BY' or 'LINES TERMINATED BY'
     followed by the 'FIELDS TERMINATED BY' value causes 'LOAD DATA INFILE'
     to stop reading a field or line too early.
     This happens because 'LOAD DATA INFILE' cannot
     properly determine where the field or line value ends.

The following example loads all columns of the 'persondata' table:

     LOAD DATA INFILE 'persondata.txt' INTO TABLE persondata;

By default, when no column list is provided at the end of the
'LOAD DATA INFILE' statement, input lines are expected to
contain a field for each table column.  If you want to load only some of
a table's columns, specify a column list:

     LOAD DATA INFILE 'persondata.txt' INTO TABLE persondata
     (COL_NAME_OR_USER_VAR [, COL_NAME_OR_USER_VAR] ...);

You must also specify a column list if the order of the fields in the
input file differs from the order of the columns in the table.
Otherwise, MySQL cannot tell how to match input fields with table
columns.

Each COL_NAME_OR_USER_VAR value is either a column name or a user
variable.  With user variables, the 'SET' clause enables you to perform
transformations on their values before assigning the result to columns.

User variables in the 'SET' clause can be used in several ways.  The
following example uses the first input column directly for the value of
't1.column1', and assigns the second input column to a user variable
that is subjected to a division operation before being used for the
value of 't1.column2':

     LOAD DATA INFILE 'file.txt'
       INTO TABLE t1
       (column1, @var1)
       SET column2 = @var1/100;

The 'SET' clause can be used to supply values not derived from the input
file.  The following statement sets 'column3' to the current date and
time:

     LOAD DATA INFILE 'file.txt'
       INTO TABLE t1
       (column1, column2)
       SET column3 = CURRENT_TIMESTAMP;

You can also discard an input value by assigning it to a user variable
and not assigning the variable to a table column:

     LOAD DATA INFILE 'file.txt'
       INTO TABLE t1
       (column1, @dummy, column2, @dummy, column3);

Use of the column/variable list and 'SET' clause is subject to the
following restrictions:

   * Assignments in the 'SET' clause should have only column names on
     the left hand side of assignment operators.

   * You can use subqueries in the right hand side of 'SET' assignments.
     A subquery that returns a value to be assigned to a column may be a
     scalar subquery only.  Also, you cannot use a subquery to select
     from the table that is being loaded.

   * Lines ignored by an 'IGNORE' clause are not processed for the
     column/variable list or 'SET' clause.

   * User variables cannot be used when loading data with fixed-row
     format because user variables do not have a display width.

When processing an input line, see 'LOAD DATA' splits it
into fields and uses the values according to the column/variable list
and the 'SET' clause, if they are present.  Then the resulting row is
inserted into the table.  If there are 'BEFORE INSERT' or 'AFTER INSERT'
triggers for the table, they are activated before or after inserting the
row, respectively.

If an input line has too many fields, the extra fields are ignored and
the number of warnings is incremented.

If an input line has too few fields, the table columns for which input
fields are missing are set to their default values.  Default value
assignment is described in data-type-defaults.

An empty field value is interpreted different from a missing field:

   * For string types, the column is set to the empty string.

   * For numeric types, the column is set to '0'.

   * For date and time types, the column is set to the appropriate
     'zero' value for the type.  See date-and-time-types.

These are the same values that result if you assign an empty string
explicitly to a string, numeric, or date or time type explicitly in an
'INSERT' or 'UPDATE' statement.

Treatment of empty or incorrect field values differs from that just
described if the SQL mode is set to a restrictive value.  For example,
if 'sql_mode' is set to 'TRADITIONAL', conversion of an empty value or a
value such as ''x'' for a numeric column results in an error, not
conversion to 0.  (With 'LOCAL' or 'IGNORE', warnings occur rather than
errors, even with a restrictive 'sql_mode' value, and the row is
inserted using the same closest-value behavior used for nonrestrictive
SQL modes.  This occurs because the server has no way to stop
transmission of the file in the middle of the operation.)

'TIMESTAMP' columns are set to the current date and
time only if there is a 'NULL' value for the column (that is, '\N') and
the column is not declared to permit 'NULL' values, or if the
'TIMESTAMP' column's default value is the current timestamp
and it is omitted from the field list when a field list is specified.

'LOAD DATA INFILE' regards all input as strings, so
you cannot use numeric values for 'ENUM' or 'SET'
columns the way you can with 'INSERT' statements.
All 'ENUM' and 'SET' values must be specified
as strings.

'BIT' values cannot be loaded directly using binary
notation (for example, 'b'011010'').  To work around this, use the 'SET'
clause to strip off the leading 'b'' and trailing ''' and perform a
base-2 to base-10 conversion so that MySQL loads the values into the
'BIT' column properly:

     shell> cat /tmp/bit_test.txt
     b'10'
     b'1111111'
     shell> mysql test
     mysql> LOAD DATA INFILE '/tmp/bit_test.txt'
            INTO TABLE bit_test (@var1)
            SET b = CAST(CONV(MID(@var1, 3, LENGTH(@var1)-3), 2, 10) AS UNSIGNED);
     Query OK, 2 rows affected (0.00 sec)
     Records: 2  Deleted: 0  Skipped: 0  Warnings: 0

     mysql> SELECT BIN(b+0) FROM bit_test;
     +----------+
     | BIN(b+0) |
     +----------+
     | 10       |
     | 1111111  |
     +----------+
     2 rows in set (0.00 sec)

For 'BIT' values in '0b' binary notation (for example,
'0b011010'), use this 'SET' clause instead to strip off the leading
'0b':

     SET b = CAST(CONV(MID(@var1, 3, LENGTH(@var1)-2), 2, 10) AS UNSIGNED)

On Unix, if you need 'LOAD DATA' to read from a pipe,
you can use the following technique (the example loads a listing of the
'/' directory into the table 'db1.t1'):

     mkfifo /mysql/data/db1/ls.dat
     chmod 666 /mysql/data/db1/ls.dat
     find / -ls > /mysql/data/db1/ls.dat &
     mysql -e "LOAD DATA INFILE 'ls.dat' INTO TABLE t1" db1

Here you must run the command that generates the data to be loaded and
the 'mysql' commands either on separate terminals, or run
the data generation process in the background (as shown in the preceding
example).  If you do not do this, the pipe will block until data is read
by the 'mysql' process.

When the 'LOAD DATA INFILE' statement finishes, it
returns an information string in the following format:

     Records: 1  Deleted: 0  Skipped: 0  Warnings: 0

Warnings occur under the same circumstances as when values are inserted
using the 'INSERT' statement (see insert), except
that 'LOAD DATA INFILE' also generates warnings when
there are too few or too many fields in the input row.

You can use 'SHOW WARNINGS' to get a list of the
first 'max_error_count' warnings as information about what went wrong.
See show-warnings.

If you are using the C API, you can get information about the statement
by calling the 'mysql_info()' function.  See
mysql-info.

13.2.7 LOAD XML Syntax
----------------------

     LOAD XML [LOW_PRIORITY | CONCURRENT] [LOCAL] INFILE 'FILE_NAME'
         [REPLACE | IGNORE]
         INTO TABLE [DB_NAME.]TBL_NAME
         [CHARACTER SET CHARSET_NAME]
         [ROWS IDENTIFIED BY '<TAGNAME>']
         [IGNORE NUMBER {LINES | ROWS}]
         [(FIELD_NAME_OR_USER_VAR
             [, FIELD_NAME_OR_USER_VAR] ...)]
         [SET COL_NAME={EXPR | DEFAULT},
             [, COL_NAME={EXPR | DEFAULT}] ...]

The 'LOAD XML' statement reads data from an XML file
into a table.  The FILE_NAME must be given as a literal string.  The
TAGNAME in the optional 'ROWS IDENTIFIED BY' clause must also be given
as a literal string, and must be surrounded by angle brackets ('<' and
'>').

'LOAD XML' acts as the complement of running the
'mysql' client in XML output mode (that is, starting the client
with the '--xml' option).  To write data from a table to an XML file,
you can invoke the 'mysql' client with the '--xml' and
'-e' options from the system shell, as shown here:

     shell> mysql --xml -e 'SELECT * FROM mydb.mytable' > file.xml

To read the file back into a table, use 'LOAD XML INFILE'.
By default, the '<row>' element is considered to be the
equivalent of a database table row; this can be changed using the 'ROWS
IDENTIFIED BY' clause.

This statement supports three different XML formats:

   * Column names as attributes and column values as attribute values:

          <ROW COLUMN1="VALUE1" COLUMN2="VALUE2" .../>

   * Column names as tags and column values as the content of these
     tags:

          <ROW>
            <COLUMN1>VALUE1</COLUMN1>
            <COLUMN2>VALUE2</COLUMN2>
          </ROW>

   * Column names are the 'name' attributes of '<field>' tags, and
     values are the contents of these tags:

          <row>
            <field name='COLUMN1'>VALUE1</field>
            <field name='COLUMN2'>VALUE2</field>
          </row>

     This is the format used by other MySQL tools, such as
     'mysqldump'.

All three formats can be used in the same XML file; the import routine
automatically detects the format for each row and interprets it
correctly.  Tags are matched based on the tag or attribute name and the
column name.

The following clauses work essentially the same way for 'LOAD XML'
as they do for 'LOAD DATA'.:

   * 'LOW_PRIORITY' or 'CONCURRENT'

   * 'LOCAL'

   * 'REPLACE' or 'IGNORE'

   * 'CHARACTER SET'

   * 'SET'

See load-data, for more information about these clauses.

'(FIELD_NAME_OR_USER_VAR, ...)' is a list of one or more comma-separated
XML fields or user variables.  The name of a user variable used for this
purpose must match the name of a field from the XML file, prefixed with
'@'.  You can use field names to select only desired fields.  User
variables can be employed to store the corresponding field values for
subsequent re-use.

The 'IGNORE NUMBER LINES' or 'IGNORE NUMBER ROWS' clause causes the
first NUMBER rows in the XML file to be skipped.  It is analogous to the
'LOAD DATA' statement's 'IGNORE ... LINES' clause.

Suppose that we have a table named 'person', created as shown here:

     USE test;

     CREATE TABLE person (
         person_id INT NOT NULL PRIMARY KEY,
         fname VARCHAR(40) NULL,
         lname VARCHAR(40) NULL,
         created TIMESTAMP
     );

Suppose further that this table is initially empty.

Now suppose that we have a simple XML file 'person.xml', whose contents
are as shown here:

     <list>
       <person person_id="1" fname="Kapek" lname="Sainnouine"/>
       <person person_id="2" fname="Sajon" lname="Rondela"/>
       <person person_id="3"><fname>Likame</fname><lname>O"rrtmons</lname></person>
       <person person_id="4"><fname>Slar</fname><lname>Manlanth</lname></person>
       <person><field name="person_id">5</field><field name="fname">Stoma</field>
         <field name="lname">Milu</field></person>
       <person><field name="person_id">6</field><field name="fname">Nirtam</field>
         <field name="lname">Sklo"d</field></person>
       <person person_id="7"><fname>Sungam</fname><lname>Dulbaad</lname></person>
       <person person_id="8" fname="Sraref" lname="Encmelt"/>
     </list>

Each of the permissible XML formats discussed previously is represented
in this example file.

To import the data in 'person.xml' into the 'person' table, you can use
this statement:

     mysql> LOAD XML LOCAL INFILE 'person.xml'
         ->   INTO TABLE person
         ->   ROWS IDENTIFIED BY '<person>';

     Query OK, 8 rows affected (0.00 sec)
     Records: 8  Deleted: 0  Skipped: 0  Warnings: 0

Here, we assume that 'person.xml' is located in the MySQL data
directory.  If the file cannot be found, the following error results:

     ERROR 2 (HY000): File '/person.xml' not found (Errcode: 2)

The 'ROWS IDENTIFIED BY '<person>'' clause means that each '<person>'
element in the XML file is considered equivalent to a row in the table
into which the data is to be imported.  In this case, this is the
'person' table in the 'test' database.

As can be seen by the response from the server, 8 rows were imported
into the 'test.person' table.  This can be verified by a simple
'SELECT' statement:

     mysql> SELECT * FROM person;
     +-----------+--------+------------+---------------------+
     | person_id | fname  | lname      | created             |
     +-----------+--------+------------+---------------------+
     |         1 | Kapek  | Sainnouine | 2007-07-13 16:18:47 |
     |         2 | Sajon  | Rondela    | 2007-07-13 16:18:47 |
     |         3 | Likame | O"rrtmons   | 2007-07-13 16:18:47 |
     |         4 | Slar   | Manlanth   | 2007-07-13 16:18:47 |
     |         5 | Stoma  | Nilu       | 2007-07-13 16:18:47 |
     |         6 | Nirtam | Sklo"d      | 2007-07-13 16:18:47 |
     |         7 | Sungam | Dulbaad     | 2007-07-13 16:18:47 |
     |         8 | Sreraf | Encmelt    | 2007-07-13 16:18:47 |
     +-----------+--------+------------+---------------------+
     8 rows in set (0.00 sec)

This shows, as stated earlier in this section, that any or all of the 3
permitted XML formats may appear in a single file and be read in using
'LOAD XML'.

The inverse of the import operation just shown--that is, dumping MySQL
table data into an XML file--can be accomplished using the
'mysql' client from the system shell, as shown here:

     shell> mysql --xml -e "SELECT * FROM test.person" > person-dump.xml
     shell> cat person-dump.xml
     <?xml version="1.0"?>

     <resultset statement="SELECT * FROM test.person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <row>
     	<field name="person_id">1</field>
     	<field name="fname">Kapek</field>
     	<field name="lname">Sainnouine</field>
       </row>

       <row>
     	<field name="person_id">2</field>
     	<field name="fname">Sajon</field>
     	<field name="lname">Rondela</field>
       </row>

       <row>
     	<field name="person_id">3</field>
     	<field name="fname">Likema</field>
     	<field name="lname">O"rrtmons</field>
       </row>

       <row>
     	<field name="person_id">4</field>
     	<field name="fname">Slar</field>
     	<field name="lname">Manlanth</field>
       </row>

       <row>
     	<field name="person_id">5</field>
     	<field name="fname">Stoma</field>
     	<field name="lname">Nilu</field>
       </row>

       <row>
     	<field name="person_id">6</field>
     	<field name="fname">Nirtam</field>
     	<field name="lname">Sklo"d</field>
       </row>

       <row>
     	<field name="person_id">7</field>
     	<field name="fname">Sungam</field>
     	<field name="lname">Dulbaad</field>
       </row>

       <row>
     	<field name="person_id">8</field>
     	<field name="fname">Sreraf</field>
     	<field name="lname">Encmelt</field>
       </row>
     </resultset>

*Note*:

The '--xml' option causes the 'mysql' client to use XML
formatting for its output; the '-e' option causes the client to execute
the SQL statement immediately following the option.  See mysql.

You can verify that the dump is valid by creating a copy of the 'person'
table and importing the dump file into the new table, like this:

     mysql> USE test;
     mysql> CREATE TABLE person2 LIKE person;
     Query OK, 0 rows affected (0.00 sec)

     mysql> LOAD XML LOCAL INFILE 'person-dump.xml'
         ->   INTO TABLE person2;
     Query OK, 8 rows affected (0.01 sec)
     Records: 8  Deleted: 0  Skipped: 0  Warnings: 0

     mysql> SELECT * FROM person2;
     +-----------+--------+------------+---------------------+
     | person_id | fname  | lname      | created             |
     +-----------+--------+------------+---------------------+
     |         1 | Kapek  | Sainnouine | 2007-07-13 16:18:47 |
     |         2 | Sajon  | Rondela    | 2007-07-13 16:18:47 |
     |         3 | Likema | O"rrtmons   | 2007-07-13 16:18:47 |
     |         4 | Slar   | Manlanth   | 2007-07-13 16:18:47 |
     |         5 | Stoma  | Nilu       | 2007-07-13 16:18:47 |
     |         6 | Nirtam | Sklo"d      | 2007-07-13 16:18:47 |
     |         7 | Sungam | Dulbaad     | 2007-07-13 16:18:47 |
     |         8 | Sreraf | Encmelt    | 2007-07-13 16:18:47 |
     +-----------+--------+------------+---------------------+
     8 rows in set (0.00 sec)

There is no requirement that every field in the XML file be matched with
a column in the corresponding table.  Fields which have no corresponding
columns are skipped.  You can see this by first emptying the 'person2'
table and dropping the 'created' column, then using the same 'LOAD XML'
statement we just employed previously, like this:

     mysql> TRUNCATE person2;
     Query OK, 8 rows affected (0.26 sec)

     mysql> ALTER TABLE person2 DROP COLUMN created;
     Query OK, 0 rows affected (0.52 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> SHOW CREATE TABLE person2\G
     *************************** 1. row ***************************
            Table: person2
     Create Table: CREATE TABLE `person2` (
       `person_id` int(11) NOT NULL,
       `fname` varchar(40) DEFAULT NULL,
       `lname` varchar(40) DEFAULT NULL,
       PRIMARY KEY (`person_id`)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8
     1 row in set (0.00 sec)

     mysql> LOAD XML LOCAL INFILE 'person-dump.xml'
         ->   INTO TABLE person2;
     Query OK, 8 rows affected (0.01 sec)
     Records: 8  Deleted: 0  Skipped: 0  Warnings: 0

     mysql> SELECT * FROM person2;
     +-----------+--------+------------+
     | person_id | fname  | lname      |
     +-----------+--------+------------+
     |         1 | Kapek  | Sainnouine |
     |         2 | Sajon  | Rondela    |
     |         3 | Likema | O"rrtmons   |
     |         4 | Slar   | Manlanth   |
     |         5 | Stoma  | Nilu       |
     |         6 | Nirtam | Sklo"d      |
     |         7 | Sungam | Dulbaad     |
     |         8 | Sreraf | Encmelt    |
     +-----------+--------+------------+
     8 rows in set (0.00 sec)

The order in which the fields are given within each row of the XML file
does not affect the operation of 'LOAD XML'; the field order can vary
from row to row, and is not required to be in the same order as the
corresponding columns in the table.

As mentioned previously, you can use a '(FIELD_NAME_OR_USER_VAR, ...)'
list of one or more XML fields (to select desired fields only) or user
variables (to store the corresponding field values for later use).  User
variables can be especially useful when you want to insert data from an
XML file into table columns whose names do not match those of the XML
fields.  To see how this works, we first create a table named
'individual' whose structure matches that of the 'person' table, but
whose columns are named differently:

     mysql> CREATE TABLE individual (
         ->     individual_id INT NOT NULL PRIMARY KEY,
         ->     name1 VARCHAR(40) NULL,
         ->     name2 VARCHAR(40) NULL,
         ->     made TIMESTAMP
         -> );
     Query OK, 0 rows affected (0.42 sec)

In this case, you cannot simply load the XML file directly into the
table, because the field and column names do not match:

     mysql> LOAD XML INFILE '../bin/person-dump.xml' INTO TABLE test.individual;
     ERROR 1263 (22004): Column set to default value; NULL supplied to NOT NULL column 'individual_id' at row 1

This happens because the MySQL server looks for field names matching the
column names of the target table.  You can work around this problem by
selecting the field values into user variables, then setting the target
table's columns equal to the values of those variables using 'SET'.  You
can perform both of these operations in a single statement, as shown
here:

     mysql> LOAD XML INFILE '../bin/person-dump.xml'
         ->     INTO TABLE test.individual (@person_id, @fname, @lname, @created)
         ->     SET individual_id=@person_id, name1=@fname, name2=@lname, made=@created;
     Query OK, 8 rows affected (0.05 sec)
     Records: 8  Deleted: 0  Skipped: 0  Warnings: 0

     mysql> SELECT * FROM individual;
     +---------------+--------+------------+---------------------+
     | individual_id | name1  | name2      | made                |
     +---------------+--------+------------+---------------------+
     |             1 | Kapek  | Sainnouine | 2007-07-13 16:18:47 |
     |             2 | Sajon  | Rondela    | 2007-07-13 16:18:47 |
     |             3 | Likema | O"rrtmons   | 2007-07-13 16:18:47 |
     |             4 | Slar   | Manlanth   | 2007-07-13 16:18:47 |
     |             5 | Stoma  | Nilu       | 2007-07-13 16:18:47 |
     |             6 | Nirtam | Sklo"d      | 2007-07-13 16:18:47 |
     |             7 | Sungam | Dulbaad     | 2007-07-13 16:18:47 |
     |             8 | Srraf  | Encmelt    | 2007-07-13 16:18:47 |
     +---------------+--------+------------+---------------------+
     8 rows in set (0.00 sec)

The names of the user variables _must_ match those of the corresponding
fields from the XML file, with the addition of the required '@' prefix
to indicate that they are variables.  The user variables need not be
listed or assigned in the same order as the corresponding fields.

Using a 'ROWS IDENTIFIED BY '<TAGNAME>'' clause, it is possible to
import data from the same XML file into database tables with different
definitions.  For this example, suppose that you have a file named
'address.xml' which contains the following XML:

     <?xml version="1.0"?>

     <list>
       <person person_id="1">
         <fname>Robert</fname>
         <lname>Jones</lname>
         <address address_id="1" street="Mill Creek Road" zip="45365" city="Sidney"/>
         <address address_id="2" street="Main Street" zip="28681" city="Taylorsville"/>
       </person>

       <person person_id="2">
         <fname>Mary</fname>
         <lname>Smith</lname>
         <address address_id="3" street="River Road" zip="80239" city="Denver"/>
         <!-- <address address_id="4" street="North Street" zip="37920" city="Knoxville"/> -->
       </person>

     </list>

You can again use the 'test.person' table as defined previously in this
section, after clearing all the existing records from the table and then
showing its structure as shown here:

     mysql< TRUNCATE person;
     Query OK, 0 rows affected (0.04 sec)

     mysql< SHOW CREATE TABLE person\G
     *************************** 1. row ***************************
            Table: person
     Create Table: CREATE TABLE `person` (
       `person_id` int(11) NOT NULL,
       `fname` varchar(40) DEFAULT NULL,
       `lname` varchar(40) DEFAULT NULL,
       `created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       PRIMARY KEY (`person_id`)
     ) ENGINE=MyISAM DEFAULT CHARSET=latin1
     1 row in set (0.00 sec)

Now create an 'address' table in the 'test' database using the following
'CREATE TABLE' statement:

     CREATE TABLE address (
         address_id INT NOT NULL PRIMARY KEY,
         person_id INT NULL,
         street VARCHAR(40) NULL,
         zip INT NULL,
         city VARCHAR(40) NULL,
         created TIMESTAMP
     );

To import the data from the XML file into the 'person' table, execute
the following 'LOAD XML' statement, which specifies
that rows are to be specified by the '<person>' element, as shown here;

     mysql> LOAD XML LOCAL INFILE 'address.xml'
         ->   INTO TABLE person
         ->   ROWS IDENTIFIED BY '<person>';
     Query OK, 2 rows affected (0.00 sec)
     Records: 2  Deleted: 0  Skipped: 0  Warnings: 0

You can verify that the records were imported using a 'SELECT'
statement:

     mysql> SELECT * FROM person;
     +-----------+--------+-------+---------------------+
     | person_id | fname  | lname | created             |
     +-----------+--------+-------+---------------------+
     |         1 | Robert | Jones | 2007-07-24 17:37:06 |
     |         2 | Mary   | Smith | 2007-07-24 17:37:06 |
     +-----------+--------+-------+---------------------+
     2 rows in set (0.00 sec)

Since the '<address>' elements in the XML file have no corresponding
columns in the 'person' table, they are skipped.

To import the data from the '<address>' elements into the 'address'
table, use the 'LOAD XML' statement shown here:

     mysql> LOAD XML LOCAL INFILE 'address.xml'
         ->   INTO TABLE address
         ->   ROWS IDENTIFIED BY '<address>';
     Query OK, 3 rows affected (0.00 sec)
     Records: 3  Deleted: 0  Skipped: 0  Warnings: 0

You can see that the data was imported using a 'SELECT'.
statement such as this one:

     mysql> SELECT * FROM address;
     +------------+-----------+-----------------+-------+--------------+---------------------+
     | address_id | person_id | street          | zip   | city         | created             |
     +------------+-----------+-----------------+-------+--------------+---------------------+
     |          1 |         1 | Mill Creek Road | 45365 | Sidney       | 2007-07-24 17:37:37 |
     |          2 |         1 | Main Street     | 28681 | Taylorsville | 2007-07-24 17:37:37 |
     |          3 |         2 | River Road      | 80239 | Denver       | 2007-07-24 17:37:37 |
     +------------+-----------+-----------------+-------+--------------+---------------------+
     3 rows in set (0.00 sec)

The data from the '<address>' element that is enclosed in XML comments
is not imported.  However, since there is a 'person_id' column in the
'address' table, the value of the 'person_id' attribute from the parent
'<person>' element for each '<address>' _is_ imported into the 'address'
table.

Security Considerations

As with the 'LOAD DATA' statement, the transfer of the
XML file from the client host to the server host is initiated by the
MySQL server.  In theory, a patched server could be built that would
tell the client program to transfer a file of the server's choosing
rather than the file named by the client in the 'LOAD XML'
statement.  Such a server could access any file on the client
host to which the client user has read access.

In a Web environment, clients usually connect to MySQL from a Web
server.  A user that can run any command against the MySQL server can
use 'LOAD XML LOCAL' to read any files to which the Web
server process has read access.  In this environment, the client with
respect to the MySQL server is actually the Web server, not the remote
program being run by the user who connects to the Web server.

You can disable loading of XML files from clients by starting the server
with '--local-infile=0' or '--local-infile=OFF'.  This option can also
be used when starting the 'mysql' client to disable
'LOAD XML' for the duration of the client session.

To prevent a client from loading XML files from the server, do not grant
the 'FILE' privilege to the corresponding MySQL user account, or revoke
this privilege if the client user account already has it.

*Important*:

Revoking the 'FILE' privilege (or not granting it in the first place)
keeps the user only from executing the 'LOAD XML INFILE'
statement (as well as the 'LOAD_FILE()' function; it does
_not_ prevent the user from executing 'LOAD XML LOCAL INFILE'.
To disallow this statement, you must start the server or the
client with '--local-infile=OFF'.

In other words, the 'FILE' privilege affects only whether the client can
read files on the server; it has no bearing on whether the client can
read files on the local file system.

For partitioned tables using storage engines that employ table locks,
such as 'MyISAM', any locks caused by 'LOAD
XML' perform locks on all partitions of the table.  This does not apply
to tables using storage engines which employ row-level locking, such as
'InnoDB'.  For more information, see
partitioning-limitations-locking.

13.2.8 REPLACE Syntax
---------------------

     REPLACE [LOW_PRIORITY | DELAYED]
         [INTO] TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         [(COL_NAME [, COL_NAME] ...)]
         {VALUES | VALUE} (VALUE_LIST) [, (VALUE_LIST)] ...

     REPLACE [LOW_PRIORITY | DELAYED]
         [INTO] TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         SET ASSIGNMENT_LIST

     REPLACE [LOW_PRIORITY | DELAYED]
         [INTO] TBL_NAME
         [PARTITION (PARTITION_NAME [, PARTITION_NAME] ...)]
         [(COL_NAME [, COL_NAME] ...)]
         SELECT ...

     VALUE:
         {EXPR | DEFAULT}

     VALUE_LIST:
         VALUE [, VALUE] ...

     ASSIGNMENT:
         COL_NAME = VALUE

     ASSIGNMENT_LIST:
         ASSIGNMENT [, ASSIGNMENT] ...

'REPLACE' works exactly like 'INSERT',
except that if an old row in the table has the same value as a new row
for a 'PRIMARY KEY' or a 'UNIQUE' index, the old row is deleted before
the new row is inserted.  See insert.

'REPLACE' is a MySQL extension to the SQL standard.  It
either inserts, or _deletes_ and inserts.  For another MySQL extension
to standard SQL--that either inserts or _updates_--see
insert-on-duplicate.

'DELAYED' inserts and replaces were deprecated in MySQL 5.6.  In MySQL
5.7, 'DELAYED' is not supported.  The server recognizes but ignores the
'DELAYED' keyword, handles the replace as a nondelayed replace, and
generates an 'ER_WARN_LEGACY_SYNTAX_CONVERTED' warning.  ('REPLACE
DELAYED is no longer supported. The statement was converted to
REPLACE.') The 'DELAYED' keyword will be removed in a future release.

*Note*:

'REPLACE' makes sense only if a table has a 'PRIMARY
KEY' or 'UNIQUE' index.  Otherwise, it becomes equivalent to
'INSERT', because there is no index to be used to determine
whether a new row duplicates another.

Values for all columns are taken from the values specified in the
'REPLACE' statement.  Any missing columns are set to their
default values, just as happens for 'INSERT'.  You cannot
refer to values from the current row and use them in the new row.  If
you use an assignment such as 'SET COL_NAME = COL_NAME + 1', the
reference to the column name on the right hand side is treated as
'DEFAULT(COL_NAME)', so the assignment is equivalent to 'SET COL_NAME =
DEFAULT(COL_NAME) + 1'.

To use 'REPLACE', you must have both the 'INSERT' and
'DELETE' privileges for the table.

If a generated column is replaced explicitly, the only permitted value
is 'DEFAULT'.  For information about generated columns, see
create-table-generated-columns.

'REPLACE' supports explicit partition selection using the 'PARTITION'
keyword with a list of comma-separated names of partitions,
subpartitions, or both.  As with 'INSERT', if it is not
possible to insert the new row into any of these partitions or
subpartitions, the 'REPLACE' statement fails with the error 'Found a row
not matching the given partition set'.  For more information and
examples, see partitioning-selection.

The 'REPLACE' statement returns a count to indicate the
number of rows affected.  This is the sum of the rows deleted and
inserted.  If the count is 1 for a single-row 'REPLACE',
a row was inserted and no rows were deleted.  If the count is greater
than 1, one or more old rows were deleted before the new row was
inserted.  It is possible for a single row to replace more than one old
row if the table contains multiple unique indexes and the new row
duplicates values for different old rows in different unique indexes.

The affected-rows count makes it easy to determine whether
'REPLACE' only added a row or whether it also replaced any
rows: Check whether the count is 1 (added) or greater (replaced).

If you are using the C API, the affected-rows count can be obtained
using the 'mysql_affected_rows()' function.

You cannot replace into a table and select from the same table in a
subquery.

MySQL uses the following algorithm for 'REPLACE'. (and
'LOAD DATA ... REPLACE'):

  1. Try to insert the new row into the table

  2. While the insertion fails because a duplicate-key error occurs for
     a primary key or unique index:

       1. Delete from the table the conflicting row that has the
          duplicate key value

       2. Try again to insert the new row into the table

It is possible that in the case of a duplicate-key error, a storage
engine may perform the 'REPLACE' as an update rather than a delete plus
insert, but the semantics are the same.  There are no user-visible
effects other than a possible difference in how the storage engine
increments 'Handler_XXX' status variables.

Because the results of 'REPLACE ... SELECT' statements depend on the
ordering of rows from the 'SELECT' and this order cannot
always be guaranteed, it is possible when logging these statements for
the master and the slave to diverge.  For this reason, 'REPLACE ...
SELECT' statements are flagged as unsafe for statement-based
replication.  such statements produce a warning in the error log when
using statement-based mode and are written to the binary log using the
row-based format when using 'MIXED' mode.  See also
replication-sbr-rbr.

When modifying an existing table that is not partitioned to accommodate
partitioning, or, when modifying the partitioning of an already
partitioned table, you may consider altering the table's primary key
(see partitioning-limitations-partitioning-keys-unique-keys).
You should be aware that, if you do this, the results of 'REPLACE'
statements may be affected, just as they would be if you modified the
primary key of a nonpartitioned table.  Consider the table created by
the following 'CREATE TABLE' statement:

     CREATE TABLE test (
       id INT UNSIGNED NOT NULL AUTO_INCREMENT,
       data VARCHAR(64) DEFAULT NULL,
       ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       PRIMARY KEY (id)
     );

When we create this table and run the statements shown in the mysql
client, the result is as follows:

     mysql> REPLACE INTO test VALUES (1, 'Old', '2014-08-20 18:47:00');
     Query OK, 1 row affected (0.04 sec)

     mysql> REPLACE INTO test VALUES (1, 'New', '2014-08-20 18:47:42');
     Query OK, 2 rows affected (0.04 sec)

     mysql> SELECT * FROM test;
     +----+------+---------------------+
     | id | data | ts                  |
     +----+------+---------------------+
     |  1 | New  | 2014-08-20 18:47:42 |
     +----+------+---------------------+
     1 row in set (0.00 sec)

Now we create a second table almost identical to the first, except that
the primary key now covers 2 columns, as shown here (emphasized text):

     CREATE TABLE test2 (
       id INT UNSIGNED NOT NULL AUTO_INCREMENT,
       data VARCHAR(64) DEFAULT NULL,
       ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       _PRIMARY KEY (id, ts)_
     );

When we run on 'test2' the same two 'REPLACE' statements as we did on
the original 'test' table, we obtain a different result:

     mysql> REPLACE INTO test2 VALUES (1, 'Old', '2014-08-20 18:47:00');
     Query OK, 1 row affected (0.05 sec)

     mysql> REPLACE INTO test2 VALUES (1, 'New', '2014-08-20 18:47:42');
     Query OK, 1 row affected (0.06 sec)

     mysql> SELECT * FROM test2;
     +----+------+---------------------+
     | id | data | ts                  |
     +----+------+---------------------+
     |  1 | Old  | 2014-08-20 18:47:00 |
     |  1 | New  | 2014-08-20 18:47:42 |
     +----+------+---------------------+
     2 rows in set (0.00 sec)

This is due to the fact that, when run on 'test2', both the 'id' and
'ts' column values must match those of an existing row for the row to be
replaced; otherwise, a row is inserted.

A 'REPLACE' statement affecting a partitioned table using a storage
engine such as 'MyISAM' that employs
table-level locks locks only those partitions containing rows that match
the 'REPLACE' statement 'WHERE' clause, as long as none of the table
partitioning columns are updated; otherwise the entire table is locked.
(For storage engines such as 'InnoDB' that
employ row-level locking, no locking of partitions takes place.)  For
more information, see partitioning-limitations-locking.

13.2.9 SELECT Syntax
--------------------

     SELECT
         [ALL | DISTINCT | DISTINCTROW ]
           [HIGH_PRIORITY]
           [STRAIGHT_JOIN]
           [SQL_SMALL_RESULT] [SQL_BIG_RESULT] [SQL_BUFFER_RESULT]
           [SQL_CACHE | SQL_NO_CACHE] [SQL_CALC_FOUND_ROWS]
         SELECT_EXPR [, SELECT_EXPR ...]
         [FROM TABLE_REFERENCES
           [PARTITION PARTITION_LIST]
         [WHERE WHERE_CONDITION]
         [GROUP BY {COL_NAME | EXPR | POSITION}
           [ASC | DESC], ... [WITH ROLLUP]]
         [HAVING WHERE_CONDITION]
         [ORDER BY {COL_NAME | EXPR | POSITION}
           [ASC | DESC], ...]
         [LIMIT {[OFFSET,] ROW_COUNT | ROW_COUNT OFFSET OFFSET}]
         [PROCEDURE PROCEDURE_NAME(ARGUMENT_LIST)]
         [INTO OUTFILE 'FILE_NAME'
             [CHARACTER SET CHARSET_NAME]
             EXPORT_OPTIONS
           | INTO DUMPFILE 'FILE_NAME'
           | INTO VAR_NAME [, VAR_NAME]]
         [FOR UPDATE | LOCK IN SHARE MODE]]

'SELECT' is used to retrieve rows selected from one or
more tables, and can include 'UNION' statements and
subqueries.  See union, and subqueries.

The most commonly used clauses of 'SELECT' statements are
these:

   * Each SELECT_EXPR indicates a column that you want to retrieve.
     There must be at least one SELECT_EXPR.

   * TABLE_REFERENCES indicates the table or tables from which to
     retrieve rows.  Its syntax is described in join.

   * 'SELECT' supports explicit partition selection using the
     'PARTITION' with a list of partitions or subpartitions (or both)
     following the name of the table in a TABLE_REFERENCE (see
     join).  In this case, rows are selected only from the partitions
     listed, and any other partitions of the table are ignored.  For
     more information and examples, see partitioning-selection.

     'SELECT ... PARTITION' from tables using storage engines such as
     'MyISAM' that perform table-level
     locks (and thus partition locks) lock only the partitions or
     subpartitions named by the 'PARTITION' option.

     For more information, see partitioning-limitations-locking.

   * The 'WHERE' clause, if given, indicates the condition or conditions
     that rows must satisfy to be selected.  WHERE_CONDITION is an
     expression that evaluates to true for each row to be selected.  The
     statement selects all rows if there is no 'WHERE' clause.

     In the 'WHERE' expression, you can use any of the functions and
     operators that MySQL supports, except for aggregate (summary)
     functions.  See expressions, and functions.

'SELECT' can also be used to retrieve rows computed
without reference to any table.

For example:

     mysql> SELECT 1 + 1;
             -> 2

You are permitted to specify 'DUAL' as a dummy table name in situations
where no tables are referenced:

     mysql> SELECT 1 + 1 FROM DUAL;
             -> 2

'DUAL' is purely for the convenience of people who require that all
'SELECT' statements should have 'FROM' and possibly other
clauses.  MySQL may ignore the clauses.  MySQL does not require 'FROM
DUAL' if no tables are referenced.

In general, clauses used must be given in exactly the order shown in the
syntax description.  For example, a 'HAVING' clause must come after any
'GROUP BY' clause and before any 'ORDER BY' clause.  The exception is
that the 'INTO' clause can appear either as shown in the syntax
description or immediately following the SELECT_EXPR list.  For more
information about 'INTO', see select-into.

The list of SELECT_EXPR terms comprises the select list that indicates
which columns to retrieve.  Terms specify a column or expression or can
use '*'-shorthand:

   * A select list consisting only of a single unqualified '*' can be
     used as shorthand to select all columns from all tables:

          SELECT * FROM t1 INNER JOIN t2 ...

   * 'TBL_NAME.*' can be used as a qualified shorthand to select all
     columns from the named table:

          SELECT t1.*, t2.* FROM t1 INNER JOIN t2 ...

   * Use of an unqualified '*' with other items in the select list may
     produce a parse error.  To avoid this problem, use a qualified
     'TBL_NAME.*' reference

          SELECT AVG(score), t1.* FROM t1 ...

The following list provides additional information about other 'SELECT'
clauses:

   *
     A SELECT_EXPR can be given an alias using 'AS ALIAS_NAME'.  The
     alias is used as the expression's column name and can be used in
     'GROUP BY', 'ORDER BY', or 'HAVING' clauses.  For example:

          SELECT CONCAT(last_name,', ',first_name) AS full_name
            FROM mytable ORDER BY full_name;

     The 'AS' keyword is optional when aliasing a SELECT_EXPR with an
     identifier.  The preceding example could have been written like
     this:

          SELECT CONCAT(last_name,', ',first_name) full_name
            FROM mytable ORDER BY full_name;

     However, because the 'AS' is optional, a subtle problem can occur
     if you forget the comma between two SELECT_EXPR expressions: MySQL
     interprets the second as an alias name.  For example, in the
     following statement, 'columnb' is treated as an alias name:

          SELECT columna columnb FROM mytable;

     For this reason, it is good practice to be in the habit of using
     'AS' explicitly when specifying column aliases.

     It is not permissible to refer to a column alias in a 'WHERE'
     clause, because the column value might not yet be determined when
     the 'WHERE' clause is executed.  See problems-with-alias.

   *
     The 'FROM TABLE_REFERENCES' clause indicates the table or tables
     from which to retrieve rows.  If you name more than one table, you
     are performing a join.  For information on join syntax, see
     join.  For each table specified, you can optionally specify an
     alias.

          TBL_NAME [[AS] ALIAS] [INDEX_HINT]

     The use of index hints provides the optimizer with information
     about how to choose indexes during query processing.  For a
     description of the syntax for specifying these hints, see
     index-hints.

     You can use 'SET max_seeks_for_key=VALUE' as an alternative way to
     force MySQL to prefer key scans instead of table scans.  See
     server-system-variables.

   * You can refer to a table within the default database as TBL_NAME,
     or as DB_NAME.TBL_NAME to specify a database explicitly.  You can
     refer to a column as COL_NAME, TBL_NAME.COL_NAME, or
     DB_NAME.TBL_NAME.COL_NAME.  You need not specify a TBL_NAME or
     DB_NAME.TBL_NAME prefix for a column reference unless the reference
     would be ambiguous.  See identifier-qualifiers, for
     examples of ambiguity that require the more explicit column
     reference forms.

   *
     A table reference can be aliased using 'TBL_NAME AS ALIAS_NAME' or
     TBL_NAME ALIAS_NAME:

          SELECT t1.name, t2.salary FROM employee AS t1, info AS t2
            WHERE t1.name = t2.name;

          SELECT t1.name, t2.salary FROM employee t1, info t2
            WHERE t1.name = t2.name;

   *
     Columns selected for output can be referred to in 'ORDER BY' and
     'GROUP BY' clauses using column names, column aliases, or column
     positions.  Column positions are integers and begin with 1:

          SELECT college, region, seed FROM tournament
            ORDER BY region, seed;

          SELECT college, region AS r, seed AS s FROM tournament
            ORDER BY r, s;

          SELECT college, region, seed FROM tournament
            ORDER BY 2, 3;

     To sort in reverse order, add the 'DESC' (descending) keyword to
     the name of the column in the 'ORDER BY' clause that you are
     sorting by.  The default is ascending order; this can be specified
     explicitly using the 'ASC' keyword.

     If 'ORDER BY' occurs within a subquery and also is applied in the
     outer query, the outermost 'ORDER BY' takes precedence.  For
     example, results for the following statement are sorted in
     descending order, not ascending order:

          (SELECT ... ORDER BY a) ORDER BY a DESC;

     Use of column positions is deprecated because the syntax has been
     removed from the SQL standard.

   *
     If you use 'GROUP BY', output rows are sorted according to the
     'GROUP BY' columns as if you had an 'ORDER BY' for the same
     columns.  To avoid the overhead of sorting that 'GROUP BY'
     produces, add 'ORDER BY NULL':

          SELECT a, COUNT(b) FROM test_table GROUP BY a ORDER BY NULL;

     Relying on implicit 'GROUP BY' sorting (that is, sorting in the
     absence of 'ASC' or 'DESC' designators) is deprecated.  To produce
     a given sort order, use explicit 'ASC' or 'DESC' designators for
     'GROUP BY' columns or provide an 'ORDER BY' clause.

   *
     When you use 'ORDER BY' or 'GROUP BY' to sort a column in a
     'SELECT', the server sorts values using only the initial
     number of bytes indicated by the 'max_sort_length' system variable.

   *
     MySQL extends the 'GROUP BY' clause so that you can also specify
     'ASC' and 'DESC' after columns named in the clause:

          SELECT a, COUNT(b) FROM test_table GROUP BY a DESC;

   * MySQL extends the use of 'GROUP BY' to permit selecting fields that
     are not mentioned in the 'GROUP BY' clause.  If you are not getting
     the results that you expect from your query, please read the
     description of 'GROUP BY' found in
     group-by-functions-and-modifiers.

   * 'GROUP BY' permits a 'WITH ROLLUP' modifier.  See
     group-by-modifiers.

   *
     The 'HAVING' clause is applied nearly last, just before items are
     sent to the client, with no optimization.  ('LIMIT' is applied
     after 'HAVING'.)

     The SQL standard requires that 'HAVING' must reference only columns
     in the 'GROUP BY' clause or columns used in aggregate functions.
     However, MySQL supports an extension to this behavior, and permits
     'HAVING' to refer to columns in the 'SELECT' list
     and columns in outer subqueries as well.

     If the 'HAVING' clause refers to a column that is ambiguous, a
     warning occurs.  In the following statement, 'col2' is ambiguous
     because it is used as both an alias and a column name:

          SELECT COUNT(col1) AS col2 FROM t GROUP BY col2 HAVING col2 = 2;

     Preference is given to standard SQL behavior, so if a 'HAVING'
     column name is used both in 'GROUP BY' and as an aliased column in
     the output column list, preference is given to the column in the
     'GROUP BY' column.

   * Do not use 'HAVING' for items that should be in the 'WHERE' clause.
     For example, do not write the following:

          SELECT COL_NAME FROM TBL_NAME HAVING COL_NAME > 0;

     Write this instead:

          SELECT COL_NAME FROM TBL_NAME WHERE COL_NAME > 0;

   * The 'HAVING' clause can refer to aggregate functions, which the
     'WHERE' clause cannot:

          SELECT user, MAX(salary) FROM users
            GROUP BY user HAVING MAX(salary) > 10;

     (This did not work in some older versions of MySQL.)

   * MySQL permits duplicate column names.  That is, there can be more
     than one SELECT_EXPR with the same name.  This is an extension to
     standard SQL. Because MySQL also permits 'GROUP BY' and 'HAVING' to
     refer to SELECT_EXPR values, this can result in an ambiguity:

          SELECT 12 AS a, a FROM t GROUP BY a;

     In that statement, both columns have the name 'a'.  To ensure that
     the correct column is used for grouping, use different names for
     each SELECT_EXPR.

   * MySQL resolves unqualified column or alias references in 'ORDER BY'
     clauses by searching in the SELECT_EXPR values, then in the columns
     of the tables in the 'FROM' clause.  For 'GROUP BY' or 'HAVING'
     clauses, it searches the 'FROM' clause before searching in the
     SELECT_EXPR values.  (For 'GROUP BY' and 'HAVING', this differs
     from the pre-MySQL 5.0 behavior that used the same rules as for
     'ORDER BY'.)

   *
     The 'LIMIT' clause can be used to constrain the number of rows
     returned by the 'SELECT' statement.  'LIMIT' takes
     one or two numeric arguments, which must both be nonnegative
     integer constants, with these exceptions:

        * Within prepared statements, 'LIMIT' parameters can be
          specified using '?' placeholder markers.

        * Within stored programs, 'LIMIT' parameters can be specified
          using integer-valued routine parameters or local variables.

     With two arguments, the first argument specifies the offset of the
     first row to return, and the second specifies the maximum number of
     rows to return.  The offset of the initial row is 0 (not 1):

          SELECT * FROM tbl LIMIT 5,10;  # Retrieve rows 6-15

     To retrieve all rows from a certain offset up to the end of the
     result set, you can use some large number for the second parameter.
     This statement retrieves all rows from the 96th row to the last:

          SELECT * FROM tbl LIMIT 95,18446744073709551615;

     With one argument, the value specifies the number of rows to return
     from the beginning of the result set:

          SELECT * FROM tbl LIMIT 5;     # Retrieve first 5 rows

     In other words, 'LIMIT ROW_COUNT' is equivalent to 'LIMIT 0,
     ROW_COUNT'.

     For prepared statements, you can use placeholders.  The following
     statements will return one row from the 'tbl' table:

          SET @a=1;
          PREPARE STMT FROM 'SELECT * FROM tbl LIMIT ?';
          EXECUTE STMT USING @a;

     The following statements will return the second to sixth row from
     the 'tbl' table:

          SET @skip=1; SET @numrows=5;
          PREPARE STMT FROM 'SELECT * FROM tbl LIMIT ?, ?';
          EXECUTE STMT USING @skip, @numrows;

     For compatibility with PostgreSQL, MySQL also supports the 'LIMIT
     ROW_COUNT OFFSET OFFSET' syntax.

     If 'LIMIT' occurs within a subquery and also is applied in the
     outer query, the outermost 'LIMIT' takes precedence.  For example,
     the following statement produces two rows, not one:

          (SELECT ... LIMIT 1) LIMIT 2;

   *
     A 'PROCEDURE' clause names a procedure that should process the data
     in the result set.  For an example, see procedure-analyse,
     which describes 'ANALYSE', a procedure that can be used to obtain
     suggestions for optimal column data types that may help reduce
     table sizes.

     A 'PROCEDURE' clause is not permitted in a 'UNION'.
     statement.

     *Note*:

     'PROCEDURE' syntax is deprecated as of MySQL 5.7.18, and is removed
     in MySQL 8.0.

   * The 'SELECT ... INTO' form of 'SELECT'
     enables the query result to be written to a file or stored
     in variables.  For more information, see select-into.

   *
     If you use 'FOR UPDATE' with a storage engine that uses page or row
     locks, rows examined by the query are write-locked until the end of
     the current transaction.  Using 'LOCK IN SHARE MODE' sets a shared
     lock that permits other transactions to read the examined rows but
     not to update or delete them.  See innodb-locking-reads.

     In addition, you cannot use 'FOR UPDATE' as part of the
     'SELECT' in a statement such as 'CREATE TABLE NEW_TABLE SELECT ... FROM OLD_TABLE ...'.
     (If
     you attempt to do so, the statement is rejected with the error
     'Can't update table 'OLD_TABLE' while 'NEW_TABLE' is being
     created'.)  This is a change in behavior from MySQL 5.5 and
     earlier, which permitted 'CREATE TABLE ... SELECT'
     statements to make changes in tables other
     than the table being created.

Following the 'SELECT' keyword, you can use a number of
modifiers that affect the operation of the statement.  'HIGH_PRIORITY',
'STRAIGHT_JOIN', and modifiers beginning with 'SQL_' are MySQL
extensions to standard SQL.

   * The 'ALL' and 'DISTINCT' modifiers specify whether duplicate rows
     should be returned.  'ALL' (the default) specifies that all
     matching rows should be returned, including duplicates.  'DISTINCT'
     specifies removal of duplicate rows from the result set.  It is an
     error to specify both modifiers.  'DISTINCTROW' is a synonym for
     'DISTINCT'.

   * 'HIGH_PRIORITY' gives the 'SELECT' higher priority
     than a statement that updates a table.  You should use this only
     for queries that are very fast and must be done at once.  A 'SELECT
     HIGH_PRIORITY' query that is issued while the table is locked for
     reading runs even if there is an update statement waiting for the
     table to be free.  This affects only storage engines that use only
     table-level locking (such as 'MyISAM', 'MEMORY', and 'MERGE').

     'HIGH_PRIORITY' cannot be used with 'SELECT'.
     statements that are part of a 'UNION'.

   * 'STRAIGHT_JOIN' forces the optimizer to join the tables in the
     order in which they are listed in the 'FROM' clause.  You can use
     this to speed up a query if the optimizer joins the tables in
     nonoptimal order.  'STRAIGHT_JOIN' also can be used in the
     TABLE_REFERENCES list.  See join.

     'STRAIGHT_JOIN' does not apply to any table that the optimizer
     treats as a 'const' or 'system' table.  Such a table produces a
     single row, is read during the optimization phase of query
     execution, and references to its columns are replaced with the
     appropriate column values before query execution proceeds.  These
     tables will appear first in the query plan displayed by
     'EXPLAIN'.  See using-explain.  This exception may
     not apply to 'const' or 'system' tables that are used on the
     'NULL'-complemented side of an outer join (that is, the right-side
     table of a 'LEFT JOIN' or the left-side table of a 'RIGHT JOIN'.

   * 'SQL_BIG_RESULT' or 'SQL_SMALL_RESULT' can be used with 'GROUP BY'
     or 'DISTINCT' to tell the optimizer that the result set has many
     rows or is small, respectively.  For 'SQL_BIG_RESULT', MySQL
     directly uses disk-based temporary tables if they are created, and
     prefers sorting to using a temporary table with a key on the 'GROUP
     BY' elements.  For 'SQL_SMALL_RESULT', MySQL uses in-memory
     temporary tables to store the resulting table instead of using
     sorting.  This should not normally be needed.

   * 'SQL_BUFFER_RESULT' forces the result to be put into a temporary
     table.  This helps MySQL free the table locks early and helps in
     cases where it takes a long time to send the result set to the
     client.  This modifier can be used only for top-level
     'SELECT' statements, not for subqueries or following
     'UNION'.

   * 'SQL_CALC_FOUND_ROWS' tells MySQL to calculate how many rows there
     would be in the result set, disregarding any 'LIMIT' clause.  The
     number of rows can then be retrieved with 'SELECT FOUND_ROWS()'.
     See information-functions.

   * The 'SQL_CACHE' and 'SQL_NO_CACHE' modifiers affect caching of
     query results in the query cache (see query-cache).
     'SQL_CACHE' tells MySQL to store the result in the query cache if
     it is cacheable and the value of the 'query_cache_type' system
     variable is '2' or 'DEMAND'.  With 'SQL_NO_CACHE', the server does
     not use the query cache.  It neither checks the query cache to see
     whether the result is already cached, nor does it cache the query
     result.

     These two modifiers are mutually exclusive and an error occurs if
     they are both specified.  Also, these modifiers are not permitted
     in subqueries (including subqueries in the 'FROM' clause), and
     'SELECT' statements in unions other than the first
     'SELECT'.

     For views, 'SQL_NO_CACHE' applies if it appears in any
     'SELECT' in the query.  For a cacheable query, 'SQL_CACHE'
     applies if it appears in the first 'SELECT' of a
     view referred to by the query.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'SQL_CACHE' and 'SQL_NO_CACHE'.

A 'SELECT' from a partitioned table using a storage engine such as
'MyISAM' that employs table-level locks locks
only those partitions containing rows that match the 'SELECT' statement
'WHERE' clause.  (This does not occur with storage engines such as
'InnoDB' that employ row-level locking.)  For
more information, see partitioning-limitations-locking.

13.2.9.1 SELECT ... INTO Syntax
...............................

The 'SELECT ... INTO' form of 'SELECT'
enables a query result to be stored in variables or written to a
file:

   * 'SELECT ... INTO VAR_LIST' selects column values and stores them
     into variables.

   * 'SELECT ... INTO OUTFILE' writes the selected rows to a file.
     Column and line terminators can be specified to produce a specific
     output format.

   * 'SELECT ... INTO DUMPFILE' writes a single row to a file without
     any formatting.

The 'SELECT' syntax description (see select)
shows the 'INTO' clause near the end of the statement.  It is also
possible to use 'INTO' immediately following the SELECT_EXPR list.

An 'INTO' clause should not be used in a nested 'SELECT'.
because such a 'SELECT' must return its result to the
outer context.

The 'INTO' clause can name a list of one or more variables, which can be
user-defined variables, stored procedure or function parameters, or
stored program local variables.  (Within a prepared 'SELECT ... INTO
OUTFILE' statement, only user-defined variables are permitted;see
local-variable-scope.)

The selected values are assigned to the variables.  The number of
variables must match the number of columns.  The query should return a
single row.  If the query returns no rows, a warning with error code
1329 occurs ('No data'), and the variable values remain unchanged.  If
the query returns multiple rows, error 1172 occurs ('Result consisted of
more than one row').  If it is possible that the statement may retrieve
multiple rows, you can use 'LIMIT 1' to limit the result set to a single
row.

     SELECT id, data INTO @x, @y FROM test.t1 LIMIT 1;

User variable names are not case-sensitive.  See user-variables.

The 'SELECT ... INTO OUTFILE 'FILE_NAME'' form of
'SELECT' writes the selected rows to a file.  The file is
created on the server host, so you must have the 'FILE' privilege to use
this syntax.  FILE_NAME cannot be an existing file, which among other
things prevents files such as '/etc/passwd' and database tables from
being destroyed.  The 'character_set_filesystem' system variable
controls the interpretation of the file name.

The 'SELECT ... INTO OUTFILE' statement is intended
primarily to let you very quickly dump a table to a text file on the
server machine.  If you want to create the resulting file on some other
host than the server host, you normally cannot use 'SELECT ... INTO OUTFILE'
since there is no way to write a path to the
file relative to the server host's file system.

However, if the MySQL client software is installed on the remote
machine, you can instead use a client command such as 'mysql -e "SELECT
..." > FILE_NAME' to generate the file on the client host.

It is also possible to create the resulting file on a different host
other than the server host, if the location of the file on the remote
host can be accessed using a network-mapped path on the server's file
system.  In this case, the presence of 'mysql'. (or some
other MySQL client program) is not required on the target host.

'SELECT ... INTO OUTFILE' is the complement of
'LOAD DATA INFILE'.  Column values are written converted to
the character set specified in the 'CHARACTER SET' clause.  If no such
clause is present, values are dumped using the 'binary' character set.
In effect, there is no character set conversion.  If a result set
contains columns in several character sets, the output data file will as
well and you may not be able to reload the file correctly.

The syntax for the EXPORT_OPTIONS part of the statement consists of the
same 'FIELDS' and 'LINES' clauses that are used with the 'LOAD DATA INFILE'
statement.  See load-data, for
information about the 'FIELDS' and 'LINES' clauses, including their
default values and permissible values.

'FIELDS ESCAPED BY' controls how to write special characters.  If the
'FIELDS ESCAPED BY' character is not empty, it is used when necessary to
avoid ambiguity as a prefix that precedes following characters on
output:

   * The 'FIELDS ESCAPED BY' character

   * The 'FIELDS [OPTIONALLY] ENCLOSED BY' character

   * The first character of the 'FIELDS TERMINATED BY' and 'LINES
     TERMINATED BY' values

   * ASCII 'NUL' (the zero-valued byte; what is actually written
     following the escape character is ASCII '0', not a zero-valued
     byte)

The 'FIELDS TERMINATED BY', 'ENCLOSED BY', 'ESCAPED BY', or 'LINES
TERMINATED BY' characters _must_ be escaped so that you can read the
file back in reliably.  ASCII 'NUL' is escaped to make it easier to view
with some pagers.

The resulting file does not have to conform to SQL syntax, so nothing
else need be escaped.

If the 'FIELDS ESCAPED BY' character is empty, no characters are escaped
and 'NULL' is output as 'NULL', not '\N'.  It is probably not a good
idea to specify an empty escape character, particularly if field values
in your data contain any of the characters in the list just given.

Here is an example that produces a file in the comma-separated values
(CSV) format used by many programs:

     SELECT a,b,a+b INTO OUTFILE '/tmp/result.txt'
       FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"'
       LINES TERMINATED BY '\n'
       FROM test_table;

If you use 'INTO DUMPFILE' instead of 'INTO OUTFILE', MySQL writes only
one row into the file, without any column or line termination and
without performing any escape processing.  This is useful if you want to
store a 'BLOB' value in a file.

*Note*:

Any file created by 'INTO OUTFILE' or 'INTO DUMPFILE' is writable by all
users on the server host.  The reason for this is that the MySQL server
cannot create a file that is owned by anyone other than the user under
whose account it is running.  (You should _never_ run 'mysqld'
as 'root' for this and other reasons.)  The file thus must be
world-writable so that you can manipulate its contents.

If the 'secure_file_priv' system variable is set to a nonempty directory
name, the file to be written must be located in that directory.

In the context of 'SELECT ... INTO' statements that
occur as part of events executed by the Event Scheduler, diagnostics
messages (not only errors, but also warnings) are written to the error
log, and, on Windows, to the application event log.  For additional
information, see events-status-info.

13.2.9.2 JOIN Syntax
....................

MySQL supports the following 'JOIN' syntax for the TABLE_REFERENCES part
of 'SELECT' statements and multiple-table 'DELETE'
and 'UPDATE' statements:

     TABLE_REFERENCES:
         ESCAPED_TABLE_REFERENCE [, ESCAPED_TABLE_REFERENCE] ...

     ESCAPED_TABLE_REFERENCE:
         TABLE_REFERENCE
       | { OJ TABLE_REFERENCE }

     TABLE_REFERENCE:
         TABLE_FACTOR
       | JOIN_TABLE

     TABLE_FACTOR:
         TBL_NAME [PARTITION (PARTITION_NAMES)]
             [[AS] ALIAS] [INDEX_HINT_LIST]
       | TABLE_SUBQUERY [AS] ALIAS
       | ( TABLE_REFERENCES )

     JOIN_TABLE:
         TABLE_REFERENCE [INNER | CROSS] JOIN TABLE_FACTOR [JOIN_CONDITION]
       | TABLE_REFERENCE STRAIGHT_JOIN TABLE_FACTOR
       | TABLE_REFERENCE STRAIGHT_JOIN TABLE_FACTOR ON CONDITIONAL_EXPR
       | TABLE_REFERENCE {LEFT|RIGHT} [OUTER] JOIN TABLE_REFERENCE JOIN_CONDITION
       | TABLE_REFERENCE NATURAL [{LEFT|RIGHT} [OUTER]] JOIN TABLE_FACTOR

     JOIN_CONDITION:
         ON CONDITIONAL_EXPR
       | USING (COLUMN_LIST)

     INDEX_HINT_LIST:
         INDEX_HINT [, INDEX_HINT] ...

     INDEX_HINT:
         USE {INDEX|KEY}
           [FOR {JOIN|ORDER BY|GROUP BY}] ([INDEX_LIST])
       | IGNORE {INDEX|KEY}
           [FOR {JOIN|ORDER BY|GROUP BY}] (INDEX_LIST)
       | FORCE {INDEX|KEY}
           [FOR {JOIN|ORDER BY|GROUP BY}] (INDEX_LIST)

     INDEX_LIST:
         INDEX_NAME [, INDEX_NAME] ...

A table reference is also known as a join expression.

A table reference (when it refers to a partitioned table) may contain a
'PARTITION' option, including a list of comma-separated partitions,
subpartitions, or both.  This option follows the name of the table and
precedes any alias declaration.  The effect of this option is that rows
are selected only from the listed partitions or subpartitions.  Any
partitions or subpartitions not named in the list are ignored.  For more
information and examples, see partitioning-selection.

The syntax of TABLE_FACTOR is extended in MySQL in comparison with
standard SQL. The standard accepts only TABLE_REFERENCE, not a list of
them inside a pair of parentheses.

This is a conservative extension if each comma in a list of
TABLE_REFERENCE items is considered as equivalent to an inner join.  For
example:

     SELECT * FROM t1 LEFT JOIN (t2, t3, t4)
                      ON (t2.a = t1.a AND t3.b = t1.b AND t4.c = t1.c)

is equivalent to:

     SELECT * FROM t1 LEFT JOIN (t2 CROSS JOIN t3 CROSS JOIN t4)
                      ON (t2.a = t1.a AND t3.b = t1.b AND t4.c = t1.c)

In MySQL, 'JOIN', 'CROSS JOIN', and 'INNER JOIN' are syntactic
equivalents (they can replace each other).  In standard SQL, they are
not equivalent.  'INNER JOIN' is used with an 'ON' clause, 'CROSS JOIN'
is used otherwise.

In general, parentheses can be ignored in join expressions containing
only inner join operations.  MySQL also supports nested joins.  See
nested-join-optimization.

Index hints can be specified to affect how the MySQL optimizer makes use
of indexes.  For more information, see index-hints.  Optimizer
hints and the 'optimizer_switch' system variable are other ways to
influence optimizer use of indexes.  See optimizer-hints, and
switchable-optimizations.

The following list describes general factors to take into account when
writing joins:

   * A table reference can be aliased using 'TBL_NAME AS ALIAS_NAME' or
     TBL_NAME ALIAS_NAME:

          SELECT t1.name, t2.salary
            FROM employee AS t1 INNER JOIN info AS t2 ON t1.name = t2.name;

          SELECT t1.name, t2.salary
            FROM employee t1 INNER JOIN info t2 ON t1.name = t2.name;

   * A TABLE_SUBQUERY is also known as a derived table or subquery in
     the 'FROM' clause.  See derived-tables.  Such subqueries
     _must_ include an alias to give the subquery result a table name.
     A trivial example follows:

          SELECT * FROM (SELECT 1, 2, 3) AS t1;

   * 'INNER JOIN' and ',' (comma) are semantically equivalent in the
     absence of a join condition: both produce a Cartesian product
     between the specified tables (that is, each and every row in the
     first table is joined to each and every row in the second table).

     However, the precedence of the comma operator is less than that of
     'INNER JOIN', 'CROSS JOIN', 'LEFT JOIN', and so on.  If you mix
     comma joins with the other join types when there is a join
     condition, an error of the form 'Unknown column 'COL_NAME' in 'on
     clause'' may occur.  Information about dealing with this problem is
     given later in this section.

   * The CONDITIONAL_EXPR used with 'ON' is any conditional expression
     of the form that can be used in a 'WHERE' clause.  Generally, the
     'ON' clause serves for conditions that specify how to join tables,
     and the 'WHERE' clause restricts which rows to include in the
     result set.

   * If there is no matching row for the right table in the 'ON' or
     'USING' part in a 'LEFT JOIN', a row with all columns set to 'NULL'
     is used for the right table.  You can use this fact to find rows in
     a table that have no counterpart in another table:

          SELECT left_tbl.*
            FROM left_tbl LEFT JOIN right_tbl ON left_tbl.id = right_tbl.id
            WHERE right_tbl.id IS NULL;

     This example finds all rows in 'left_tbl' with an 'id' value that
     is not present in 'right_tbl' (that is, all rows in 'left_tbl' with
     no corresponding row in 'right_tbl').  See
     left-join-optimization.

   * The 'USING(COLUMN_LIST)' clause names a list of columns that must
     exist in both tables.  If tables 'a' and 'b' both contain columns
     'c1', 'c2', and 'c3', the following join compares corresponding
     columns from the two tables:

          a LEFT JOIN b USING (c1, c2, c3)

   * The 'NATURAL [LEFT] JOIN' of two tables is defined to be
     semantically equivalent to an 'INNER JOIN' or a 'LEFT JOIN' with a
     'USING' clause that names all columns that exist in both tables.

   * 'RIGHT JOIN' works analogously to 'LEFT JOIN'.  To keep code
     portable across databases, it is recommended that you use 'LEFT
     JOIN' instead of 'RIGHT JOIN'.

   *
     The '{ OJ ... }' syntax shown in the join syntax description exists
     only for compatibility with ODBC. The curly braces in the syntax
     should be written literally; they are not metasyntax as used
     elsewhere in syntax descriptions.

          SELECT left_tbl.*
              FROM { OJ left_tbl LEFT OUTER JOIN right_tbl ON left_tbl.id = right_tbl.id }
              WHERE right_tbl.id IS NULL;

     You can use other types of joins within '{ OJ ... }', such as
     'INNER JOIN' or 'RIGHT OUTER JOIN'.  This helps with compatibility
     with some third-party applications, but is not official ODBC
     syntax.

   * 'STRAIGHT_JOIN' is similar to 'JOIN', except that the left table is
     always read before the right table.  This can be used for those
     (few) cases for which the join optimizer processes the tables in a
     suboptimal order.

Some join examples:

     SELECT * FROM table1, table2;

     SELECT * FROM table1 INNER JOIN table2 ON table1.id = table2.id;

     SELECT * FROM table1 LEFT JOIN table2 ON table1.id = table2.id;

     SELECT * FROM table1 LEFT JOIN table2 USING (id);

     SELECT * FROM table1 LEFT JOIN table2 ON table1.id = table2.id
       LEFT JOIN table3 ON table2.id = table3.id;

Natural joins and joins with 'USING', including outer join variants, are
processed according to the SQL:2003 standard:

   * Redundant columns of a 'NATURAL' join do not appear.  Consider this
     set of statements:

          CREATE TABLE t1 (i INT, j INT);
          CREATE TABLE t2 (k INT, j INT);
          INSERT INTO t1 VALUES(1, 1);
          INSERT INTO t2 VALUES(1, 1);
          SELECT * FROM t1 NATURAL JOIN t2;
          SELECT * FROM t1 JOIN t2 USING (j);

     In the first 'SELECT' statement, column 'j' appears
     in both tables and thus becomes a join column, so, according to
     standard SQL, it should appear only once in the output, not twice.
     Similarly, in the second SELECT statement, column 'j' is named in
     the 'USING' clause and should appear only once in the output, not
     twice.

     Thus, the statements produce this output:

          +------+------+------+
          | j    | i    | k    |
          +------+------+------+
          |    1 |    1 |    1 |
          +------+------+------+
          +------+------+------+
          | j    | i    | k    |
          +------+------+------+
          |    1 |    1 |    1 |
          +------+------+------+

     Redundant column elimination and column ordering occurs according
     to standard SQL, producing this display order:

        * First, coalesced common columns of the two joined tables, in
          the order in which they occur in the first table

        * Second, columns unique to the first table, in order in which
          they occur in that table

        * Third, columns unique to the second table, in order in which
          they occur in that table

     The single result column that replaces two common columns is
     defined using the coalesce operation.  That is, for two 't1.a' and
     't2.a' the resulting single join column 'a' is defined as 'a =
     COALESCE(t1.a, t2.a)', where:

          COALESCE(x, y) = (CASE WHEN x IS NOT NULL THEN x ELSE y END)

     If the join operation is any other join, the result columns of the
     join consist of the concatenation of all columns of the joined
     tables.

     A consequence of the definition of coalesced columns is that, for
     outer joins, the coalesced column contains the value of the
     non-'NULL' column if one of the two columns is always 'NULL'.  If
     neither or both columns are 'NULL', both common columns have the
     same value, so it doesn't matter which one is chosen as the value
     of the coalesced column.  A simple way to interpret this is to
     consider that a coalesced column of an outer join is represented by
     the common column of the inner table of a 'JOIN'.  Suppose that the
     tables 't1(a, b)' and 't2(a, c)' have the following contents:

          t1    t2
          ----  ----
          1 x   2 z
          2 y   3 w

     Then, for this join, column 'a' contains the values of 't1.a':

          mysql> SELECT * FROM t1 NATURAL LEFT JOIN t2;
          +------+------+------+
          | a    | b    | c    |
          +------+------+------+
          |    1 | x    | NULL |
          |    2 | y    | z    |
          +------+------+------+

     By contrast, for this join, column 'a' contains the values of
     't2.a'.

          mysql> SELECT * FROM t1 NATURAL RIGHT JOIN t2;
          +------+------+------+
          | a    | c    | b    |
          +------+------+------+
          |    2 | z    | y    |
          |    3 | w    | NULL |
          +------+------+------+

     Compare those results to the otherwise equivalent queries with
     'JOIN ... ON':

          mysql> SELECT * FROM t1 LEFT JOIN t2 ON (t1.a = t2.a);
          +------+------+------+------+
          | a    | b    | a    | c    |
          +------+------+------+------+
          |    1 | x    | NULL | NULL |
          |    2 | y    |    2 | z    |
          +------+------+------+------+

          mysql> SELECT * FROM t1 RIGHT JOIN t2 ON (t1.a = t2.a);
          +------+------+------+------+
          | a    | b    | a    | c    |
          +------+------+------+------+
          |    2 | y    |    2 | z    |
          | NULL | NULL |    3 | w    |
          +------+------+------+------+

   * A 'USING' clause can be rewritten as an 'ON' clause that compares
     corresponding columns.  However, although 'USING' and 'ON' are
     similar, they are not quite the same.  Consider the following two
     queries:

          a LEFT JOIN b USING (c1, c2, c3)
          a LEFT JOIN b ON a.c1 = b.c1 AND a.c2 = b.c2 AND a.c3 = b.c3

     With respect to determining which rows satisfy the join condition,
     both joins are semantically identical.

     With respect to determining which columns to display for 'SELECT *'
     expansion, the two joins are not semantically identical.  The
     'USING' join selects the coalesced value of corresponding columns,
     whereas the 'ON' join selects all columns from all tables.  For the
     'USING' join, 'SELECT *' selects these values:

          COALESCE(a.c1, b.c1), COALESCE(a.c2, b.c2), COALESCE(a.c3, b.c3)

     For the 'ON' join, 'SELECT *' selects these values:

          a.c1, a.c2, a.c3, b.c1, b.c2, b.c3

     With an inner join, 'COALESCE(a.c1, b.c1)' is the same as either
     'a.c1' or 'b.c1' because both columns will have the same value.
     With an outer join (such as 'LEFT JOIN'), one of the two columns
     can be 'NULL'.  That column is omitted from the result.

   * An 'ON' clause can refer only to its operands.

     Example:

          CREATE TABLE t1 (i1 INT);
          CREATE TABLE t2 (i2 INT);
          CREATE TABLE t3 (i3 INT);
          SELECT * FROM t1 JOIN t2 ON (i1 = i3) JOIN t3;

     The statement fails with an 'Unknown column 'i3' in 'on clause''
     error because 'i3' is a column in 't3', which is not an operand of
     the 'ON' clause.  To enable the join to be processed, rewrite the
     statement as follows:

          SELECT * FROM t1 JOIN t2 JOIN t3 ON (i1 = i3);

   * 'JOIN' has higher precedence than the comma operator (','), so the
     join expression 't1, t2 JOIN t3' is interpreted as '(t1, (t2 JOIN
     t3))', not as '((t1, t2) JOIN t3)'.  This affects statements that
     use an 'ON' clause because that clause can refer only to columns in
     the operands of the join, and the precedence affects interpretation
     of what those operands are.

     Example:

          CREATE TABLE t1 (i1 INT, j1 INT);
          CREATE TABLE t2 (i2 INT, j2 INT);
          CREATE TABLE t3 (i3 INT, j3 INT);
          INSERT INTO t1 VALUES(1, 1);
          INSERT INTO t2 VALUES(1, 1);
          INSERT INTO t3 VALUES(1, 1);
          SELECT * FROM t1, t2 JOIN t3 ON (t1.i1 = t3.i3);

     The 'JOIN' takes precedence over the comma operator, so the
     operands for the 'ON' clause are 't2' and 't3'.  Because 't1.i1' is
     not a column in either of the operands, the result is an 'Unknown
     column 't1.i1' in 'on clause'' error.

     To enable the join to be processed, use either of these strategies:

        * Group the first two tables explicitly with parentheses so that
          the operands for the 'ON' clause are '(t1, t2)' and 't3':

               SELECT * FROM (t1, t2) JOIN t3 ON (t1.i1 = t3.i3);

        * Avoid the use of the comma operator and use 'JOIN' instead:

               SELECT * FROM t1 JOIN t2 JOIN t3 ON (t1.i1 = t3.i3);

     The same precedence interpretation also applies to statements that
     mix the comma operator with 'INNER JOIN', 'CROSS JOIN', 'LEFT
     JOIN', and 'RIGHT JOIN', all of which have higher precedence than
     the comma operator.

   * A MySQL extension compared to the SQL:2003 standard is that MySQL
     permits you to qualify the common (coalesced) columns of 'NATURAL'
     or 'USING' joins, whereas the standard disallows that.

13.2.9.3 UNION Syntax
.....................

     SELECT ...
     UNION [ALL | DISTINCT] SELECT ...
     [UNION [ALL | DISTINCT] SELECT ...]

'UNION' is used to combine the result from multiple
'SELECT' statements into a single result set.

The column names from the first 'SELECT' statement are
used as the column names for the results returned.  Selected columns
listed in corresponding positions of each 'SELECT'.
statement should have the same data type.  (For example, the first
column selected by the first statement should have the same type as the
first column selected by the other statements.)

If the data types of corresponding 'SELECT' columns do
not match, the types and lengths of the columns in the 'UNION'
result take into account the values retrieved by all of the
'SELECT' statements.  For example, consider the following:

     mysql> SELECT REPEAT('a',1) UNION SELECT REPEAT('b',10);
     +---------------+
     | REPEAT('a',1) |
     +---------------+
     | a             |
     | bbbbbbbbbb    |
     +---------------+

The 'SELECT' statements are normal select statements, but
with the following restrictions:

   * Only the last 'SELECT' statement can use 'INTO
     OUTFILE'.  (However, the entire 'UNION' result is
     written to the file.)

   * 'HIGH_PRIORITY' cannot be used with 'SELECT'.
     statements that are part of a 'UNION'.  If you specify
     it for the first 'SELECT', it has no effect.  If you
     specify it for any subsequent 'SELECT' statements, a
     syntax error results.

The default behavior for 'UNION' is that duplicate rows
are removed from the result.  The optional 'DISTINCT' keyword has no
effect other than the default because it also specifies duplicate-row
removal.  With the optional 'ALL' keyword, duplicate-row removal does
not occur and the result includes all matching rows from all the
'SELECT' statements.

You can mix 'UNION ALL' and 'UNION DISTINCT'.
in the same query.  Mixed 'UNION' types are treated such
that a 'DISTINCT' union overrides any 'ALL' union to its left.  A
'DISTINCT' union can be produced explicitly by using 'UNION DISTINCT'
or implicitly by using 'UNION' with no
following 'DISTINCT' or 'ALL' keyword.

To apply 'ORDER BY' or 'LIMIT' to an individual 'SELECT',
place the clause inside the parentheses that enclose the 'SELECT'.:

     (SELECT a FROM t1 WHERE a=10 AND B=1 ORDER BY a LIMIT 10)
     UNION
     (SELECT a FROM t2 WHERE a=11 AND B=2 ORDER BY a LIMIT 10);

*Note*:

Previous versions of MySQL may permit such statements without
parentheses.  In MySQL 5.7, the requirement for parentheses is enforced.

Use of 'ORDER BY' for individual 'SELECT' statements
implies nothing about the order in which the rows appear in the final
result because 'UNION' by default produces an unordered
set of rows.  Therefore, the use of 'ORDER BY' in this context is
typically in conjunction with 'LIMIT', so that it is used to determine
the subset of the selected rows to retrieve for the 'SELECT',
even though it does not necessarily affect the order of those
rows in the final 'UNION' result.  If 'ORDER BY' appears
without 'LIMIT' in a 'SELECT', it is optimized away
because it will have no effect anyway.

To use an 'ORDER BY' or 'LIMIT' clause to sort or limit the entire
'UNION' result, parenthesize the individual 'SELECT'
statements and place the 'ORDER BY' or 'LIMIT' after the last
one.  The following example uses both clauses:

     (SELECT a FROM t1 WHERE a=10 AND B=1)
     UNION
     (SELECT a FROM t2 WHERE a=11 AND B=2)
     ORDER BY a LIMIT 10;

A statement without parentheses is equivalent to one parenthesized as
just shown.

This kind of 'ORDER BY' cannot use column references that include a
table name (that is, names in TBL_NAME.COL_NAME format).  Instead,
provide a column alias in the first 'SELECT' statement
and refer to the alias in the 'ORDER BY'.  (Alternatively, refer to the
column in the 'ORDER BY' using its column position.  However, use of
column positions is deprecated.)

Also, if a column to be sorted is aliased, the 'ORDER BY' clause _must_
refer to the alias, not the column name.  The first of the following
statements will work, but the second will fail with an 'Unknown column
'a' in 'order clause'' error:

     (SELECT a AS b FROM t) UNION (SELECT ...) ORDER BY b;
     (SELECT a AS b FROM t) UNION (SELECT ...) ORDER BY a;

To cause rows in a 'UNION' result to consist of the sets
of rows retrieved by each 'SELECT' one after the other,
select an additional column in each 'SELECT' to use as a
sort column and add an 'ORDER BY' following the last 'SELECT'.:

     (SELECT 1 AS sort_col, col1a, col1b, ... FROM t1)
     UNION
     (SELECT 2, col2a, col2b, ... FROM t2) ORDER BY sort_col;

To additionally maintain sort order within individual 'SELECT'
results, add a secondary column to the 'ORDER BY' clause:

     (SELECT 1 AS sort_col, col1a, col1b, ... FROM t1)
     UNION
     (SELECT 2, col2a, col2b, ... FROM t2) ORDER BY sort_col, col1a;

Use of an additional column also enables you to determine which
'SELECT' each row comes from.  Extra columns can provide other
identifying information as well, such as a string that indicates a table
name.

'UNION' queries with an aggregate function in an 'ORDER
BY' clause are rejected with an 'ER_AGGREGATE_ORDER_FOR_UNION' error.
Example:

     SELECT 1 AS foo UNION SELECT 2 ORDER BY MAX(1);

13.2.10 Subquery Syntax
-----------------------

A subquery is a 'SELECT' statement within another
statement.

All subquery forms and operations that the SQL standard requires are
supported, as well as a few features that are MySQL-specific.

Here is an example of a subquery:

     SELECT * FROM t1 WHERE column1 = (SELECT column1 FROM t2);

In this example, 'SELECT * FROM t1 ...' is the _outer query_ (or _outer
statement_), and '(SELECT column1 FROM t2)' is the _subquery_.  We say
that the subquery is _nested_ within the outer query, and in fact it is
possible to nest subqueries within other subqueries, to a considerable
depth.  A subquery must always appear within parentheses.

The main advantages of subqueries are:

   * They allow queries that are _structured_ so that it is possible to
     isolate each part of a statement.

   * They provide alternative ways to perform operations that would
     otherwise require complex joins and unions.

   * Many people find subqueries more readable than complex joins or
     unions.  Indeed, it was the innovation of subqueries that gave
     people the original idea of calling the early SQL 'Structured Query
     Language.'

Here is an example statement that shows the major points about subquery
syntax as specified by the SQL standard and supported in MySQL:

     DELETE FROM t1
     WHERE s11 > ANY
      (SELECT COUNT(*) /* no hint */ FROM t2
       WHERE NOT EXISTS
        (SELECT * FROM t3
         WHERE ROW(5*t2.s1,77)=
          (SELECT 50,11*s1 FROM t4 UNION SELECT 50,77 FROM
           (SELECT * FROM t5) AS t5)));

A subquery can return a scalar (a single value), a single row, a single
column, or a table (one or more rows of one or more columns).  These are
called scalar, column, row, and table subqueries.  Subqueries that
return a particular kind of result often can be used only in certain
contexts, as described in the following sections.

There are few restrictions on the type of statements in which subqueries
can be used.  A subquery can contain many of the keywords or clauses
that an ordinary 'SELECT' can contain: 'DISTINCT', 'GROUP
BY', 'ORDER BY', 'LIMIT', joins, index hints, see 'UNION'.
constructs, comments, functions, and so on.

A subquery's outer statement can be any one of: 'SELECT',
'INSERT', 'UPDATE', 'DELETE',
'SET', or 'DO'.

In MySQL, you cannot modify a table and select from the same table in a
subquery.  This applies to statements such as 'DELETE',
'INSERT', 'REPLACE', 'UPDATE',
and (because subqueries can be used in the 'SET' clause)
'LOAD DATA INFILE'.

For information about how the optimizer handles subqueries, see
subquery-optimization.  For a discussion of restrictions on subquery
use, including performance issues for certain forms of subquery syntax,
see subquery-restrictions.

13.2.10.1 The Subquery as Scalar Operand
........................................

In its simplest form, a subquery is a scalar subquery that returns a
single value.  A scalar subquery is a simple operand, and you can use it
almost anywhere a single column value or literal is legal, and you can
expect it to have those characteristics that all operands have: a data
type, a length, an indication that it can be 'NULL', and so on.  For
example:

     CREATE TABLE t1 (s1 INT, s2 CHAR(5) NOT NULL);
     INSERT INTO t1 VALUES(100, 'abcde');
     SELECT (SELECT s2 FROM t1);

The subquery in this 'SELECT' returns a single value
(''abcde'') that has a data type of 'CHAR', a length of 5, a
character set and collation equal to the defaults in effect at
'CREATE TABLE' time, and an indication that the value in
the column can be 'NULL'.  Nullability of the value selected by a scalar
subquery is not copied because if the subquery result is empty, the
result is 'NULL'.  For the subquery just shown, if 't1' were empty, the
result would be 'NULL' even though 's2' is 'NOT NULL'.

There are a few contexts in which a scalar subquery cannot be used.  If
a statement permits only a literal value, you cannot use a subquery.
For example, 'LIMIT' requires literal integer arguments, and 'LOAD DATA INFILE'
requires a literal string file name.  You
cannot use subqueries to supply these values.

When you see examples in the following sections that contain the rather
spartan construct '(SELECT column1 FROM t1)', imagine that your own code
contains much more diverse and complex constructions.

Suppose that we make two tables:

     CREATE TABLE t1 (s1 INT);
     INSERT INTO t1 VALUES (1);
     CREATE TABLE t2 (s1 INT);
     INSERT INTO t2 VALUES (2);

Then perform a 'SELECT'.:

     SELECT (SELECT s1 FROM t2) FROM t1;

The result is '2' because there is a row in 't2' containing a column
's1' that has a value of '2'.

A scalar subquery can be part of an expression, but remember the
parentheses, even if the subquery is an operand that provides an
argument for a function.  For example:

     SELECT UPPER((SELECT s1 FROM t1)) FROM t2;

13.2.10.2 Comparisons Using Subqueries
......................................

The most common use of a subquery is in the form:

     NON_SUBQUERY_OPERAND COMPARISON_OPERATOR (SUBQUERY)

Where COMPARISON_OPERATOR is one of these operators:

     =  >  <  >=  <=  <>  !=  <=>

For example:

     ... WHERE 'a' = (SELECT column1 FROM t1)

MySQL also permits this construct:

     NON_SUBQUERY_OPERAND LIKE (SUBQUERY)

At one time the only legal place for a subquery was on the right side of
a comparison, and you might still find some old DBMSs that insist on
this.

Here is an example of a common-form subquery comparison that you cannot
do with a join.  It finds all the rows in table 't1' for which the
'column1' value is equal to a maximum value in table 't2':

     SELECT * FROM t1
       WHERE column1 = (SELECT MAX(column2) FROM t2);

Here is another example, which again is impossible with a join because
it involves aggregating for one of the tables.  It finds all rows in
table 't1' containing a value that occurs twice in a given column:

     SELECT * FROM t1 AS t
       WHERE 2 = (SELECT COUNT(*) FROM t1 WHERE t1.id = t.id);

For a comparison of the subquery to a scalar, the subquery must return a
scalar.  For a comparison of the subquery to a row constructor, the
subquery must be a row subquery that returns a row with the same number
of values as the row constructor.  See row-subqueries.

13.2.10.3 Subqueries with ANY, IN, or SOME
..........................................

Syntax:

     OPERAND COMPARISON_OPERATOR ANY (SUBQUERY)
     OPERAND IN (SUBQUERY)
     OPERAND COMPARISON_OPERATOR SOME (SUBQUERY)

Where COMPARISON_OPERATOR is one of these operators:

     =  >  <  >=  <=  <>  !=

The 'ANY' keyword, which must follow a comparison operator, means
'return 'TRUE' if the comparison is 'TRUE' for 'ANY' of the values in
the column that the subquery returns.' For example:

     SELECT s1 FROM t1 WHERE s1 > ANY (SELECT s1 FROM t2);

Suppose that there is a row in table 't1' containing '(10)'.  The
expression is 'TRUE' if table 't2' contains '(21,14,7)' because there is
a value '7' in 't2' that is less than '10'.  The expression is 'FALSE'
if table 't2' contains '(20,10)', or if table 't2' is empty.  The
expression is _unknown_ (that is, 'NULL') if table 't2' contains
'(NULL,NULL,NULL)'.

When used with a subquery, the word 'IN' is an alias for '= ANY'.  Thus,
these two statements are the same:

     SELECT s1 FROM t1 WHERE s1 = ANY (SELECT s1 FROM t2);
     SELECT s1 FROM t1 WHERE s1 IN    (SELECT s1 FROM t2);

'IN' and '= ANY' are not synonyms when used with an expression list.
'IN' can take an expression list, but '= ANY' cannot.  See
comparison-operators.

'NOT IN' is not an alias for '<> ANY', but for '<> ALL'.  See
all-subqueries.

The word 'SOME' is an alias for 'ANY'.  Thus, these two statements are
the same:

     SELECT s1 FROM t1 WHERE s1 <> ANY  (SELECT s1 FROM t2);
     SELECT s1 FROM t1 WHERE s1 <> SOME (SELECT s1 FROM t2);

Use of the word 'SOME' is rare, but this example shows why it might be
useful.  To most people, the English phrase 'a is not equal to any b'
means 'there is no b which is equal to a,' but that is not what is meant
by the SQL syntax.  The syntax means 'there is some b to which a is not
equal.' Using '<> SOME' instead helps ensure that everyone understands
the true meaning of the query.

13.2.10.4 Subqueries with ALL
.............................

Syntax:

     OPERAND COMPARISON_OPERATOR ALL (SUBQUERY)

The word 'ALL', which must follow a comparison operator, means 'return
'TRUE' if the comparison is 'TRUE' for 'ALL' of the values in the column
that the subquery returns.' For example:

     SELECT s1 FROM t1 WHERE s1 > ALL (SELECT s1 FROM t2);

Suppose that there is a row in table 't1' containing '(10)'.  The
expression is 'TRUE' if table 't2' contains '(-5,0,+5)' because '10' is
greater than all three values in 't2'.  The expression is 'FALSE' if
table 't2' contains '(12,6,NULL,-100)' because there is a single value
'12' in table 't2' that is greater than '10'.  The expression is
_unknown_ (that is, 'NULL') if table 't2' contains '(0,NULL,1)'.

Finally, the expression is 'TRUE' if table 't2' is empty.  So, the
following expression is 'TRUE' when table 't2' is empty:

     SELECT * FROM t1 WHERE 1 > ALL (SELECT s1 FROM t2);

But this expression is 'NULL' when table 't2' is empty:

     SELECT * FROM t1 WHERE 1 > (SELECT s1 FROM t2);

In addition, the following expression is 'NULL' when table 't2' is
empty:

     SELECT * FROM t1 WHERE 1 > ALL (SELECT MAX(s1) FROM t2);

In general, _tables containing 'NULL' values_ and _empty tables_ are
'edge cases.' When writing subqueries, always consider whether you have
taken those two possibilities into account.

'NOT IN' is an alias for '<> ALL'.  Thus, these two statements are the
same:

     SELECT s1 FROM t1 WHERE s1 <> ALL (SELECT s1 FROM t2);
     SELECT s1 FROM t1 WHERE s1 NOT IN (SELECT s1 FROM t2);

13.2.10.5 Row Subqueries
........................

Scalar or column subqueries return a single value or a column of values.
A _row subquery_ is a subquery variant that returns a single row and can
thus return more than one column value.  Legal operators for row
subquery comparisons are:

     =  >  <  >=  <=  <>  !=  <=>

Here are two examples:

     SELECT * FROM t1
       WHERE (col1,col2) = (SELECT col3, col4 FROM t2 WHERE id = 10);
     SELECT * FROM t1
       WHERE ROW(col1,col2) = (SELECT col3, col4 FROM t2 WHERE id = 10);

For both queries, if the table 't2' contains a single row with 'id =
10', the subquery returns a single row.  If this row has 'col3' and
'col4' values equal to the 'col1' and 'col2' values of any rows in 't1',
the 'WHERE' expression is 'TRUE' and each query returns those 't1' rows.
If the 't2' row 'col3' and 'col4' values are not equal the 'col1' and
'col2' values of any 't1' row, the expression is 'FALSE' and the query
returns an empty result set.  The expression is _unknown_ (that is,
'NULL') if the subquery produces no rows.  An error occurs if the
subquery produces multiple rows because a row subquery can return at
most one row.

For information about how each operator works for row comparisons, see
comparison-operators.

The expressions '(1,2)' and 'ROW(1,2)' are sometimes called _row
constructors_.  The two are equivalent.  The row constructor and the row
returned by the subquery must contain the same number of values.

A row constructor is used for comparisons with subqueries that return
two or more columns.  When a subquery returns a single column, this is
regarded as a scalar value and not as a row, so a row constructor cannot
be used with a subquery that does not return at least two columns.
Thus, the following query fails with a syntax error:

     SELECT * FROM t1 WHERE ROW(1) = (SELECT column1 FROM t2)

Row constructors are legal in other contexts.  For example, the
following two statements are semantically equivalent (and are handled in
the same way by the optimizer):

     SELECT * FROM t1 WHERE (column1,column2) = (1,1);
     SELECT * FROM t1 WHERE column1 = 1 AND column2 = 1;

The following query answers the request, 'find all rows in table 't1'
that also exist in table 't2'':

     SELECT column1,column2,column3
       FROM t1
       WHERE (column1,column2,column3) IN
              (SELECT column1,column2,column3 FROM t2);

For more information about the optimizer and row constructors, see
row-constructor-optimization

13.2.10.6 Subqueries with EXISTS or NOT EXISTS
..............................................

If a subquery returns any rows at all, 'EXISTS SUBQUERY' is 'TRUE', and
'NOT EXISTS SUBQUERY' is 'FALSE'.  For example:

     SELECT column1 FROM t1 WHERE EXISTS (SELECT * FROM t2);

Traditionally, an 'EXISTS' subquery starts with 'SELECT *', but it could
begin with 'SELECT 5' or 'SELECT column1' or anything at all.  MySQL
ignores the 'SELECT' list in such a subquery, so it makes
no difference.

For the preceding example, if 't2' contains any rows, even rows with
nothing but 'NULL' values, the 'EXISTS' condition is 'TRUE'.  This is
actually an unlikely example because a '[NOT] EXISTS' subquery almost
always contains correlations.  Here are some more realistic examples:

   * What kind of store is present in one or more cities?

          SELECT DISTINCT store_type FROM stores
            WHERE EXISTS (SELECT * FROM cities_stores
                          WHERE cities_stores.store_type = stores.store_type);

   * What kind of store is present in no cities?

          SELECT DISTINCT store_type FROM stores
            WHERE NOT EXISTS (SELECT * FROM cities_stores
                              WHERE cities_stores.store_type = stores.store_type);

   * What kind of store is present in all cities?

          SELECT DISTINCT store_type FROM stores s1
            WHERE NOT EXISTS (
              SELECT * FROM cities WHERE NOT EXISTS (
                SELECT * FROM cities_stores
                 WHERE cities_stores.city = cities.city
                 AND cities_stores.store_type = stores.store_type));

The last example is a double-nested 'NOT EXISTS' query.  That is, it has
a 'NOT EXISTS' clause within a 'NOT EXISTS' clause.  Formally, it
answers the question 'does a city exist with a store that is not in
'Stores''?  But it is easier to say that a nested 'NOT EXISTS' answers
the question 'is X 'TRUE' for all Y?'

13.2.10.7 Correlated Subqueries
...............................

A _correlated subquery_ is a subquery that contains a reference to a
table that also appears in the outer query.  For example:

     SELECT * FROM t1
       WHERE column1 = ANY (SELECT column1 FROM t2
                            WHERE t2.column2 = t1.column2);

Notice that the subquery contains a reference to a column of 't1', even
though the subquery's 'FROM' clause does not mention a table 't1'.  So,
MySQL looks outside the subquery, and finds 't1' in the outer query.

Suppose that table 't1' contains a row where 'column1 = 5' and 'column2
= 6'; meanwhile, table 't2' contains a row where 'column1 = 5' and
'column2 = 7'.  The simple expression '... WHERE column1 = ANY (SELECT
column1 FROM t2)' would be 'TRUE', but in this example, the 'WHERE'
clause within the subquery is 'FALSE' (because '(5,6)' is not equal to
'(5,7)'), so the expression as a whole is 'FALSE'.

*Scoping rule:* MySQL evaluates from inside to outside.  For example:

     SELECT column1 FROM t1 AS x
       WHERE x.column1 = (SELECT column1 FROM t2 AS x
         WHERE x.column1 = (SELECT column1 FROM t3
           WHERE x.column2 = t3.column1));

In this statement, 'x.column2' must be a column in table 't2' because
'SELECT column1 FROM t2 AS x ...' renames 't2'.  It is not a column in
table 't1' because 'SELECT column1 FROM t1 ...' is an outer query that
is _farther out_.

For subqueries in 'HAVING' or 'ORDER BY' clauses, MySQL also looks for
column names in the outer select list.

For certain cases, a correlated subquery is optimized.  For example:

     VAL IN (SELECT KEY_VAL FROM TBL_NAME WHERE CORRELATED_CONDITION)

Otherwise, they are inefficient and likely to be slow.  Rewriting the
query as a join might improve performance.

Aggregate functions in correlated subqueries may contain outer
references, provided the function contains nothing but outer references,
and provided the function is not contained in another function or
expression.

13.2.10.8 Derived Tables (Subqueries in the FROM Clause)
........................................................

A derived table is a subquery in a 'SELECT' statement
'FROM' clause:

     SELECT ... FROM (SUBQUERY) [AS] TBL_NAME ...

The '[AS] TBL_NAME' clause is mandatory because every table in a 'FROM'
clause must have a name.  Any columns in the SUBQUERY select list must
have unique names.

For the sake of illustration, assume that you have this table:

     CREATE TABLE t1 (s1 INT, s2 CHAR(5), s3 FLOAT);

Here is how to use a subquery in the 'FROM' clause, using the example
table:

     INSERT INTO t1 VALUES (1,'1',1.0);
     INSERT INTO t1 VALUES (2,'2',2.0);
     SELECT sb1,sb2,sb3
       FROM (SELECT s1 AS sb1, s2 AS sb2, s3*2 AS sb3 FROM t1) AS sb
       WHERE sb1 > 1;

Result: '2, '2', 4.0'.

Here is another example: Suppose that you want to know the average of a
set of sums for a grouped table.  This does not work:

     SELECT AVG(SUM(column1)) FROM t1 GROUP BY column1;

However, this query provides the desired information:

     SELECT AVG(sum_column1)
       FROM (SELECT SUM(column1) AS sum_column1
             FROM t1 GROUP BY column1) AS t1;

Notice that the column name used within the subquery ('sum_column1') is
recognized in the outer query.

Derived tables can return a scalar, column, row, or table.

Derived tables cannot be correlated subqueries, or contain outer
references or references to other tables of the same 'SELECT'.

The optimizer determines information about derived tables in such a way
that materialization of them does not occur for 'EXPLAIN'.
See derived-table-optimization.

It is possible under certain circumstances that using 'EXPLAIN SELECT'
will modify table data.  This can occur if the outer
query accesses any tables and an inner query invokes a stored function
that changes one or more rows of a table.  Suppose that there are two
tables 't1' and 't2' in database 'd1', and a stored function 'f1' that
modifies 't2', created as shown here:

     CREATE DATABASE d1;
     USE d1;
     CREATE TABLE t1 (c1 INT);
     CREATE TABLE t2 (c1 INT);
     CREATE FUNCTION f1(p1 INT) RETURNS INT
       BEGIN
         INSERT INTO t2 VALUES (p1);
         RETURN p1;
       END;

Referencing the function directly in an 'EXPLAIN SELECT'.
has no effect on 't2', as shown here:

     mysql> SELECT * FROM t2;
     Empty set (0.02 sec)

     mysql> EXPLAIN SELECT f1(5)\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: NULL
        partitions: NULL
              type: NULL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: NULL
          filtered: NULL
             Extra: No tables used
     1 row in set (0.01 sec)

     mysql> SELECT * FROM t2;
     Empty set (0.01 sec)

This is because the 'SELECT' statement did not reference
any tables, as can be seen in the 'table' and 'Extra' columns of the
output.  This is also true of the following nested 'SELECT'.:

     mysql> EXPLAIN SELECT NOW() AS a1, (SELECT f1(5)) AS a2\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: NULL
              type: NULL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: NULL
          filtered: NULL
             Extra: No tables used
     1 row in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS;
     +-------+------+------------------------------------------+
     | Level | Code | Message                                  |
     +-------+------+------------------------------------------+
     | Note  | 1249 | Select 2 was reduced during optimization |
     +-------+------+------------------------------------------+
     1 row in set (0.00 sec)

     mysql> SELECT * FROM t2;
     Empty set (0.00 sec)

However, if the outer 'SELECT' references any tables, the
optimizer executes the statement in the subquery as well:

     mysql> EXPLAIN SELECT * FROM t1 AS a1, (SELECT f1(5)) AS a2\G
     *************************** 1. row ***************************
                id: 1
       select_type: PRIMARY
             table: <derived2>
        partitions: NULL
              type: system
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: 1
          filtered: 100.00
             Extra: NULL
     *************************** 2. row ***************************
                id: 1
       select_type: PRIMARY
             table: a1
        partitions: NULL
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: 1
          filtered: 100.00
             Extra: NULL
     *************************** 3. row ***************************
                id: 2
       select_type: DERIVED
             table: NULL
        partitions: NULL
              type: NULL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: NULL
          filtered: NULL
             Extra: No tables used
     3 rows in set (0.00 sec)

     mysql> SELECT * FROM t2;
     +------+
     | c1   |
     +------+
     |    5 |
     +------+
     1 row in set (0.00 sec)

This also means that an 'EXPLAIN SELECT' statement such
as the one shown here may take a long time to execute because the
'BENCHMARK()' function is executed once for each row in 't1':

     EXPLAIN SELECT * FROM t1 AS a1, (SELECT BENCHMARK(1000000, MD5(NOW())));

13.2.10.9 Subquery Errors
.........................

There are some errors that apply only to subqueries.  This section
describes them.

   * Unsupported subquery syntax:

          ERROR 1235 (ER_NOT_SUPPORTED_YET)
          SQLSTATE = 42000
          Message = "This version of MySQL doesn't yet support
          'LIMIT & IN/ALL/ANY/SOME subquery'"

     This means that MySQL does not support statements of the following
     form:

          SELECT * FROM t1 WHERE s1 IN (SELECT s2 FROM t2 ORDER BY s1 LIMIT 1)

   * Incorrect number of columns from subquery:

          ERROR 1241 (ER_OPERAND_COL)
          SQLSTATE = 21000
          Message = "Operand should contain 1 column(s)"

     This error occurs in cases like this:

          SELECT (SELECT column1, column2 FROM t2) FROM t1;

     You may use a subquery that returns multiple columns, if the
     purpose is row comparison.  In other contexts, the subquery must be
     a scalar operand.  See row-subqueries.

   * Incorrect number of rows from subquery:

          ERROR 1242 (ER_SUBSELECT_NO_1_ROW)
          SQLSTATE = 21000
          Message = "Subquery returns more than 1 row"

     This error occurs for statements where the subquery must return at
     most one row but returns multiple rows.  Consider the following
     example:

          SELECT * FROM t1 WHERE column1 = (SELECT column1 FROM t2);

     If 'SELECT column1 FROM t2' returns just one row, the previous
     query will work.  If the subquery returns more than one row, error
     1242 will occur.  In that case, the query should be rewritten as:

          SELECT * FROM t1 WHERE column1 = ANY (SELECT column1 FROM t2);

   * Incorrectly used table in subquery:

          Error 1093 (ER_UPDATE_TABLE_USED)
          SQLSTATE = HY000
          Message = "You can't specify target table 'x'
          for update in FROM clause"

     This error occurs in cases such as the following, which attempts to
     modify a table and select from the same table in the subquery:

          UPDATE t1 SET column2 = (SELECT MAX(column1) FROM t1);

     You can use a subquery for assignment within an 'UPDATE'
     statement because subqueries are legal in 'UPDATE'
     and 'DELETE' statements as well as in
     'SELECT' statements.  However, you cannot use the same
     table (in this case, table 't1') for both the subquery 'FROM'
     clause and the update target.

For transactional storage engines, the failure of a subquery causes the
entire statement to fail.  For nontransactional storage engines, data
modifications made before the error was encountered are preserved.

13.2.10.10 Optimizing Subqueries
................................

Development is ongoing, so no optimization tip is reliable for the long
term.  The following list provides some interesting tricks that you
might want to play with.  See also subquery-optimization.

   * Use subquery clauses that affect the number or order of the rows in
     the subquery.  For example:

          SELECT * FROM t1 WHERE t1.column1 IN
            (SELECT column1 FROM t2 ORDER BY column1);
          SELECT * FROM t1 WHERE t1.column1 IN
            (SELECT DISTINCT column1 FROM t2);
          SELECT * FROM t1 WHERE EXISTS
            (SELECT * FROM t2 LIMIT 1);

   * Replace a join with a subquery.  For example, try this:

          SELECT DISTINCT column1 FROM t1 WHERE t1.column1 IN (
            SELECT column1 FROM t2);

     Instead of this:

          SELECT DISTINCT t1.column1 FROM t1, t2
            WHERE t1.column1 = t2.column1;

   * Some subqueries can be transformed to joins for compatibility with
     older versions of MySQL that do not support subqueries.  However,
     in some cases, converting a subquery to a join may improve
     performance.  See rewriting-subqueries.

   * Move clauses from outside to inside the subquery.  For example, use
     this query:

          SELECT * FROM t1
            WHERE s1 IN (SELECT s1 FROM t1 UNION ALL SELECT s1 FROM t2);

     Instead of this query:

          SELECT * FROM t1
            WHERE s1 IN (SELECT s1 FROM t1) OR s1 IN (SELECT s1 FROM t2);

     For another example, use this query:

          SELECT (SELECT column1 + 5 FROM t1) FROM t2;

     Instead of this query:

          SELECT (SELECT column1 FROM t1) + 5 FROM t2;

   * Use a row subquery instead of a correlated subquery.  For example,
     use this query:

          SELECT * FROM t1
            WHERE (column1,column2) IN (SELECT column1,column2 FROM t2);

     Instead of this query:

          SELECT * FROM t1
            WHERE EXISTS (SELECT * FROM t2 WHERE t2.column1=t1.column1
                          AND t2.column2=t1.column2);

   * Use 'NOT (a = ANY (...))' rather than 'a <> ALL (...)'.

   * Use 'x = ANY (TABLE CONTAINING (1,2))' rather than 'x=1 OR x=2'.

   * Use '= ANY' rather than 'EXISTS'.

   * For uncorrelated subqueries that always return one row, 'IN' is
     always slower than '='.  For example, use this query:

          SELECT * FROM t1
            WHERE t1.COL_NAME = (SELECT a FROM t2 WHERE b = SOME_CONST);

     Instead of this query:

          SELECT * FROM t1
            WHERE t1.COL_NAME IN (SELECT a FROM t2 WHERE b = SOME_CONST);

These tricks might cause programs to go faster or slower.  Using MySQL
facilities like the 'BENCHMARK()' function, you can get an idea about
what helps in your own situation.  See information-functions.

Some optimizations that MySQL itself makes are:

   * MySQL executes uncorrelated subqueries only once.  Use
     'EXPLAIN' to make sure that a given subquery really is
     uncorrelated.

   * MySQL rewrites 'IN', 'ALL', 'ANY', and 'SOME' subqueries in an
     attempt to take advantage of the possibility that the select-list
     columns in the subquery are indexed.

   * MySQL replaces subqueries of the following form with an
     index-lookup function, which 'EXPLAIN' describes as
     a special join type ('unique_subquery' or 'index_subquery'):

          ... IN (SELECT INDEXED_COLUMN FROM SINGLE_TABLE ...)

   * MySQL enhances expressions of the following form with an expression
     involving 'MIN()' or 'MAX()', unless 'NULL' values or empty sets
     are involved:

          VALUE {ALL|ANY|SOME} {> | < | >= | <=} (UNCORRELATED SUBQUERY)

     For example, this 'WHERE' clause:

          WHERE 5 > ALL (SELECT x FROM t)

     might be treated by the optimizer like this:

          WHERE 5 > (SELECT MAX(x) FROM t)

See also MySQL Internals: How MySQL Transforms Subqueries
(http://dev.mysql.com/doc/internals/en/transformations.html).

13.2.10.11 Rewriting Subqueries as Joins
........................................

Sometimes there are other ways to test membership in a set of values
than by using a subquery.  Also, on some occasions, it is not only
possible to rewrite a query without a subquery, but it can be more
efficient to make use of some of these techniques rather than to use
subqueries.  One of these is the 'IN()' construct:

For example, this query:

     SELECT * FROM t1 WHERE id IN (SELECT id FROM t2);

Can be rewritten as:

     SELECT DISTINCT t1.* FROM t1, t2 WHERE t1.id=t2.id;

The queries:

     SELECT * FROM t1 WHERE id NOT IN (SELECT id FROM t2);
     SELECT * FROM t1 WHERE NOT EXISTS (SELECT id FROM t2 WHERE t1.id=t2.id);

Can be rewritten as:

     SELECT table1.*
       FROM table1 LEFT JOIN table2 ON table1.id=table2.id
       WHERE table2.id IS NULL;

A 'LEFT [OUTER] JOIN' can be faster than an equivalent subquery because
the server might be able to optimize it better--a fact that is not
specific to MySQL Server alone.  Prior to SQL-92, outer joins did not
exist, so subqueries were the only way to do certain things.  Today,
MySQL Server and many other modern database systems offer a wide range
of outer join types.

MySQL Server supports multiple-table 'DELETE' statements
that can be used to efficiently delete rows based on information from
one table or even from many tables at the same time.  Multiple-table
'UPDATE' statements are also supported.  See
delete, and update.

13.2.11 UPDATE Syntax
---------------------

'UPDATE' is a DML statement that modifies rows in a
table.

Single-table syntax:

     UPDATE [LOW_PRIORITY] [IGNORE] TABLE_REFERENCE
         SET ASSIGNMENT_LIST
         [WHERE WHERE_CONDITION]
         [ORDER BY ...]
         [LIMIT ROW_COUNT]

     VALUE:
         {EXPR | DEFAULT}

     ASSIGNMENT:
         COL_NAME = VALUE

     ASSIGNMENT_LIST:
         ASSIGNMENT [, ASSIGNMENT] ...

Multiple-table syntax:

     UPDATE [LOW_PRIORITY] [IGNORE] TABLE_REFERENCES
         SET ASSIGNMENT_LIST
         [WHERE WHERE_CONDITION]

For the single-table syntax, the 'UPDATE' statement
updates columns of existing rows in the named table with new values.
The 'SET' clause indicates which columns to modify and the values they
should be given.  Each value can be given as an expression, or the
keyword 'DEFAULT' to set a column explicitly to its default value.  The
'WHERE' clause, if given, specifies the conditions that identify which
rows to update.  With no 'WHERE' clause, all rows are updated.  If the
'ORDER BY' clause is specified, the rows are updated in the order that
is specified.  The 'LIMIT' clause places a limit on the number of rows
that can be updated.

For the multiple-table syntax, see 'UPDATE' updates rows in
each table named in TABLE_REFERENCES that satisfy the conditions.  Each
matching row is updated once, even if it matches the conditions multiple
times.  For multiple-table syntax, 'ORDER BY' and 'LIMIT' cannot be
used.

For partitioned tables, both the single-single and multiple-table forms
of this statement support the use of a 'PARTITION' option as part of a
table reference.  This option takes a list of one or more partitions or
subpartitions (or both).  Only the partitions (or subpartitions) listed
are checked for matches, and a row that is not in any of these
partitions or subpartitions is not updated, whether it satisfies the
WHERE_CONDITION or not.

*Note*:

Unlike the case when using 'PARTITION' with an 'INSERT'.
or 'REPLACE' statement, an otherwise valid 'UPDATE ...
PARTITION' statement is considered successful even if no rows in the
listed partitions (or subpartitions) match the WHERE_CONDITION.

For more information and examples, see partitioning-selection.

WHERE_CONDITION is an expression that evaluates to true for each row to
be updated.  For expression syntax, see expressions.

TABLE_REFERENCES and WHERE_CONDITION are specified as described in
select.

You need the 'UPDATE' privilege only for columns referenced in an
'UPDATE' that are actually updated.  You need only the 'SELECT'
privilege for any columns that are read but not modified.

The 'UPDATE' statement supports the following modifiers:

   * With the 'LOW_PRIORITY' modifier, execution of the 'UPDATE'
     is delayed until no other clients are reading from the
     table.  This affects only storage engines that use only table-level
     locking (such as 'MyISAM', 'MEMORY', and 'MERGE').

   * With the 'IGNORE' modifier, the update statement does not abort
     even if errors occur during the update.  Rows for which
     duplicate-key conflicts occur on a unique key value are not
     updated.  Rows updated to values that would cause data conversion
     errors are updated to the closest valid values instead.  For more
     information, see ignore-strict-comparison.

'UPDATE IGNORE' statements, including those having an
'ORDER BY' clause, are flagged as unsafe for statement-based
replication.  (This is because the order in which the rows are updated
determines which rows are ignored.)  Such statements produce a warning
in the error log when using statement-based mode and are written to the
binary log using the row-based format when using 'MIXED' mode.  (Bug
#11758262, Bug #50439) See replication-rbr-safe-unsafe, for more
information.

If you access a column from the table to be updated in an expression,
see 'UPDATE' uses the current value of the column.  For
example, the following statement sets 'col1' to one more than its
current value:

     UPDATE t1 SET col1 = col1 + 1;

The second assignment in the following statement sets 'col2' to the
current (updated) 'col1' value, not the original 'col1' value.  The
result is that 'col1' and 'col2' have the same value.  This behavior
differs from standard SQL.

     UPDATE t1 SET col1 = col1 + 1, col2 = col1;

Single-table 'UPDATE' assignments are generally evaluated
from left to right.  For multiple-table updates, there is no guarantee
that assignments are carried out in any particular order.

If you set a column to the value it currently has, MySQL notices this
and does not update it.

If you update a column that has been declared 'NOT NULL' by setting to
'NULL', an error occurs if strict SQL mode is enabled; otherwise, the
column is set to the implicit default value for the column data type and
the warning count is incremented.  The implicit default value is '0' for
numeric types, the empty string ('''') for string types, and the 'zero'
value for date and time types.  See data-type-defaults.

If a generated column is updated explicitly, the only permitted value is
'DEFAULT'.  For information about generated columns, see
create-table-generated-columns.

'UPDATE' returns the number of rows that were actually
changed.  The 'mysql_info()'. C API function returns
the number of rows that were matched and updated and the number of
warnings that occurred during the 'UPDATE'.

You can use 'LIMIT ROW_COUNT' to restrict the scope of the
'UPDATE'.  A 'LIMIT' clause is a rows-matched restriction.  The
statement stops as soon as it has found ROW_COUNT rows that satisfy the
'WHERE' clause, whether or not they actually were changed.

If an 'UPDATE' statement includes an 'ORDER BY' clause,
the rows are updated in the order specified by the clause.  This can be
useful in certain situations that might otherwise result in an error.
Suppose that a table 't' contains a column 'id' that has a unique index.
The following statement could fail with a duplicate-key error, depending
on the order in which rows are updated:

     UPDATE t SET id = id + 1;

For example, if the table contains 1 and 2 in the 'id' column and 1 is
updated to 2 before 2 is updated to 3, an error occurs.  To avoid this
problem, add an 'ORDER BY' clause to cause the rows with larger 'id'
values to be updated before those with smaller values:

     UPDATE t SET id = id + 1 ORDER BY id DESC;

You can also perform 'UPDATE' operations covering
multiple tables.  However, you cannot use 'ORDER BY' or 'LIMIT' with a
multiple-table 'UPDATE'.  The TABLE_REFERENCES clause
lists the tables involved in the join.  Its syntax is described in
join.  Here is an example:

     UPDATE items,month SET items.price=month.price
     WHERE items.id=month.id;

The preceding example shows an inner join that uses the comma operator,
but multiple-table 'UPDATE' statements can use any type
of join permitted in 'SELECT' statements, such as 'LEFT
JOIN'.

If you use a multiple-table 'UPDATE' statement involving
'InnoDB' tables for which there are foreign key constraints, the MySQL
optimizer might process tables in an order that differs from that of
their parent/child relationship.  In this case, the statement fails and
rolls back.  Instead, update a single table and rely on the 'ON UPDATE'
capabilities that 'InnoDB' provides to cause the other tables to be
modified accordingly.  See innodb-foreign-key-constraints.

You cannot update a table and select from the same table in a subquery.

An 'UPDATE' on a partitioned table using a storage engine such as
'MyISAM' that employs table-level locks locks
only those partitions containing rows that match the 'UPDATE' statement
'WHERE' clause, as long as none of the table partitioning columns are
updated.  (For storage engines such as 'InnoDB'
that employ row-level locking, no locking of
partitions takes place.)  For more information, see
partitioning-limitations-locking.

13.3 Transactional and Locking Statements
=========================================

MySQL supports local transactions (within a given client session)
through statements such as 'SET autocommit', 'START TRANSACTION',
see 'COMMIT', and 'ROLLBACK'.
See commit.  XA transaction support enables MySQL to
participate in distributed transactions as well.  See xa.

13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Syntax
-----------------------------------------------------

     START TRANSACTION
         [TRANSACTION_CHARACTERISTIC [, TRANSACTION_CHARACTERISTIC] ...]

     TRANSACTION_CHARACTERISTIC:
         WITH CONSISTENT SNAPSHOT
       | READ WRITE
       | READ ONLY

     BEGIN [WORK]
     COMMIT [WORK] [AND [NO] CHAIN] [[NO] RELEASE]
     ROLLBACK [WORK] [AND [NO] CHAIN] [[NO] RELEASE]
     SET autocommit = {0 | 1}

These statements provide control over use of transactions:

   * 'START TRANSACTION' or 'BEGIN' start a new transaction.

   * 'COMMIT' commits the current transaction, making its changes
     permanent.

   * 'ROLLBACK' rolls back the current transaction, canceling its
     changes.

   * 'SET autocommit' disables or enables the default autocommit mode
     for the current session.

By default, MySQL runs with autocommit mode enabled.  This means that as
soon as you execute a statement that updates (modifies) a table, MySQL
stores the update on disk to make it permanent.  The change cannot be
rolled back.

To disable autocommit mode implicitly for a single series of statements,
use the 'START TRANSACTION' statement:

     START TRANSACTION;
     SELECT @A:=SUM(salary) FROM table1 WHERE type=1;
     UPDATE table2 SET summary=@A WHERE type=1;
     COMMIT;

With 'START TRANSACTION', autocommit remains disabled until you end the
transaction with 'COMMIT' or 'ROLLBACK'.  The autocommit mode then
reverts to its previous state.

'START TRANSACTION' permits several modifiers that control transaction
characteristics.  To specify multiple modifiers, separate them by
commas.

   * The 'WITH CONSISTENT SNAPSHOT' modifier starts a consistent read
     for storage engines that are capable of it.  This applies only to
     'InnoDB'.  The effect is the same as issuing a 'START TRANSACTION'
     followed by a 'SELECT' from any 'InnoDB' table.  See
     innodb-consistent-read.  The 'WITH CONSISTENT SNAPSHOT'
     modifier does not change the current transaction isolation level,
     so it provides a consistent snapshot only if the current isolation
     level is one that permits a consistent read.  The only isolation
     level that permits a consistent read is 'REPEATABLE READ'.  For all
     other isolation levels, the 'WITH CONSISTENT SNAPSHOT' clause is
     ignored.  As of MySQL 5.7.2, a warning is generated when the 'WITH
     CONSISTENT SNAPSHOT' clause is ignored.

   * The 'READ WRITE' and 'READ ONLY' modifiers set the transaction
     access mode.  They permit or prohibit changes to tables used in the
     transaction.  The 'READ ONLY' restriction prevents the transaction
     from modifying or locking both transactional and nontransactional
     tables that are visible to other transactions; the transaction can
     still modify or lock temporary tables.

     MySQL enables extra optimizations for queries on 'InnoDB' tables
     when the transaction is known to be read-only.  Specifying 'READ
     ONLY' ensures these optimizations are applied in cases where the
     read-only status cannot be determined automatically.  See
     innodb-performance-ro-txn for more information.

     If no access mode is specified, the default mode applies.  Unless
     the default has been changed, it is read/write.  It is not
     permitted to specify both 'READ WRITE' and 'READ ONLY' in the same
     statement.

     In read-only mode, it remains possible to change tables created
     with the 'TEMPORARY' keyword using DML statements.  Changes made
     with DDL statements are not permitted, just as with permanent
     tables.

     For additional information about transaction access mode, including
     ways to change the default mode, see set-transaction.

     If the 'read_only' system variable is enabled, explicitly starting
     a transaction with 'START TRANSACTION READ WRITE' requires the
     'SUPER' privilege.

*Important*:

Many APIs used for writing MySQL client applications (such as JDBC)
provide their own methods for starting transactions that can (and
sometimes should) be used instead of sending a 'START TRANSACTION'
statement from the client.  See connectors-apis, or the
documentation for your API, for more information.

To disable autocommit mode explicitly, use the following statement:

     SET autocommit=0;

After disabling autocommit mode by setting the 'autocommit' variable to
zero, changes to transaction-safe tables (such as those for
'InnoDB' or 'NDB') are not
made permanent immediately.  You must use 'COMMIT' to
store your changes to disk or 'ROLLBACK' to ignore the changes.

'autocommit' is a session variable and must be set for each session.  To
disable autocommit mode for each new connection, see the description of
the 'autocommit' system variable at server-system-variables.

'BEGIN' and 'BEGIN WORK' are supported as aliases of 'START TRANSACTION'
for initiating a transaction.  'START TRANSACTION' is standard SQL
syntax, is the recommended way to start an ad-hoc transaction, and
permits modifiers that 'BEGIN' does not.

The 'BEGIN' statement differs from the use of the 'BEGIN' keyword that
starts a 'BEGIN ... END' compound statement.  The
latter does not begin a transaction.  See begin-end.

*Note*:

Within all stored programs (stored procedures and functions, triggers,
and events), the parser treats 'BEGIN [WORK]' as the beginning of a
'BEGIN ... END' block.  Begin a transaction in this
context with 'START TRANSACTION' instead.

The optional 'WORK' keyword is supported for 'COMMIT' and 'ROLLBACK', as
are the 'CHAIN' and 'RELEASE' clauses.  'CHAIN' and 'RELEASE' can be
used for additional control over transaction completion.  The value of
the 'completion_type' system variable determines the default completion
behavior.  See server-system-variables.

The 'AND CHAIN' clause causes a new transaction to begin as soon as the
current one ends, and the new transaction has the same isolation level
as the just-terminated transaction.  The new transaction also uses the
same access mode ('READ WRITE' or 'READ ONLY') as the just-terminated
transaction.  The 'RELEASE' clause causes the server to disconnect the
current client session after terminating the current transaction.
Including the 'NO' keyword suppresses 'CHAIN' or 'RELEASE' completion,
which can be useful if the 'completion_type' system variable is set to
cause chaining or release completion by default.

Beginning a transaction causes any pending transaction to be committed.
See implicit-commit, for more information.

Beginning a transaction also causes table locks acquired with
'LOCK TABLES' to be released, as though you had executed
'UNLOCK TABLES'.  Beginning a transaction does not
release a global read lock acquired with 'FLUSH TABLES WITH READ LOCK'.

For best results, transactions should be performed using only tables
managed by a single transaction-safe storage engine.  Otherwise, the
following problems can occur:

   * If you use tables from more than one transaction-safe storage
     engine (such as 'InnoDB'), and the transaction isolation level is
     not 'SERIALIZABLE', it is possible that when one transaction
     commits, another ongoing transaction that uses the same tables will
     see only some of the changes made by the first transaction.  That
     is, the atomicity of transactions is not guaranteed with mixed
     engines and inconsistencies can result.  (If mixed-engine
     transactions are infrequent, you can use 'SET TRANSACTION ISOLATION LEVEL'
     to set the isolation level to
     'SERIALIZABLE' on a per-transaction basis as necessary.)

   * If you use tables that are not transaction-safe within a
     transaction, changes to those tables are stored at once, regardless
     of the status of autocommit mode.

   * If you issue a 'ROLLBACK' statement after updating a
     nontransactional table within a transaction, an
     'ER_WARNING_NOT_COMPLETE_ROLLBACK' warning occurs.  Changes to
     transaction-safe tables are rolled back, but not changes to
     nontransaction-safe tables.

Each transaction is stored in the binary log in one chunk, upon
'COMMIT'.  Transactions that are rolled back are not logged.
(*Exception*: Modifications to nontransactional tables cannot be rolled
back.  If a transaction that is rolled back includes modifications to
nontransactional tables, the entire transaction is logged with a
'ROLLBACK' statement at the end to ensure that modifications to
the nontransactional tables are replicated.)  See binary-log.

You can change the isolation level or access mode for transactions with
the 'SET TRANSACTION' statement.  See
set-transaction.

Rolling back can be a slow operation that may occur implicitly without
the user having explicitly asked for it (for example, when an error
occurs).  Because of this, see 'SHOW PROCESSLIST'.
displays 'Rolling back' in the 'State' column for the session, not only
for explicit rollbacks performed with the 'ROLLBACK'.
statement but also for implicit rollbacks.

*Note*:

In MySQL 5.7, 'BEGIN', 'COMMIT', and 'ROLLBACK' are not affected by
'--replicate-do-db' or '--replicate-ignore-db' rules.

13.3.2 Statements That Cannot Be Rolled Back
--------------------------------------------

Some statements cannot be rolled back.  In general, these include data
definition language (DDL) statements, such as those that create or drop
databases, those that create, drop, or alter tables or stored routines.

You should design your transactions not to include such statements.  If
you issue a statement early in a transaction that cannot be rolled back,
and then another statement later fails, the full effect of the
transaction cannot be rolled back in such cases by issuing a
'ROLLBACK' statement.

13.3.3 Statements That Cause an Implicit Commit
-----------------------------------------------

The statements listed in this section (and any synonyms for them)
implicitly end any transaction active in the current session, as if you
had done a 'COMMIT' before executing the statement.

Most of these statements also cause an implicit commit after executing.
The intent is to handle each such statement in its own special
transaction because it cannot be rolled back anyway.
Transaction-control and locking statements are exceptions: If an
implicit commit occurs before execution, another does not occur after.

   * *Data definition language (DDL) statements that define or modify
     database objects.*  See 'ALTER DATABASE ... UPGRADE DATA DIRECTORY NAME',
     see 'ALTER EVENT',
     'ALTER PROCEDURE', 'ALTER SERVER',
     see 'ALTER TABLE', 'ALTER VIEW',
     see 'CREATE DATABASE', 'CREATE EVENT',
     see 'CREATE INDEX',
     'CREATE PROCEDURE', 'CREATE SERVER',
     see 'CREATE TABLE', 'CREATE TRIGGER',
     see 'CREATE VIEW',
     'DROP DATABASE', 'DROP EVENT',
     'DROP INDEX', 'DROP PROCEDURE',
     see 'DROP SERVER', 'DROP TABLE',
     see 'DROP TRIGGER', 'DROP VIEW',
     see 'INSTALL PLUGIN'. (as of
     MySQL 5.7.6), see 'RENAME TABLE', 'TRUNCATE TABLE',
     see 'UNINSTALL PLUGIN'.
     (as of MySQL 5.7.6).

     See 'ALTER FUNCTION', 'CREATE FUNCTION'
     and 'DROP FUNCTION' also
     cause an implicit commit when used with stored functions, but not
     with user-defined functions.  (see 'ALTER FUNCTION'
     can only be used with stored functions.)

     'CREATE TABLE' and 'DROP TABLE'
     statements do not commit a transaction if the
     'TEMPORARY' keyword is used.  (This does not apply to other
     operations on temporary tables such as 'ALTER TABLE'
     and 'CREATE INDEX', which do cause
     a commit.)  However, although no implicit commit occurs, neither
     can the statement be rolled back, which means that the use of such
     statements causes transactional atomicity to be violated.  For
     example, if you use 'CREATE TEMPORARY TABLE'.
     and then roll back the transaction, the table remains in existence.

     The 'CREATE TABLE' statement in 'InnoDB' is
     processed as a single transaction.  This means that a
     'ROLLBACK' from the user does not undo 'CREATE TABLE'
     statements the user made during that
     transaction.

     'CREATE TABLE ... SELECT' causes an implicit
     commit before and after the statement is executed when you are
     creating nontemporary tables.  (No commit occurs for 'CREATE
     TEMPORARY TABLE ... SELECT'.)

   * *Statements that implicitly use or modify tables in the 'mysql'
     database.*  See 'ALTER USER', 'CREATE USER',
     see 'DROP USER', 'GRANT',
     'RENAME USER', 'REVOKE',
     'SET PASSWORD'.

   * *Transaction-control and locking statements.*  See 'BEGIN',
     see 'LOCK TABLES', 'SET autocommit = 1' (if
     the value is not already 1), see 'START TRANSACTION',
     'UNLOCK TABLES'.

     'UNLOCK TABLES' commits a transaction only if
     any tables currently have been locked with 'LOCK TABLES'
     to acquire nontransactional table locks.  A commit
     does not occur for 'UNLOCK TABLES' following
     'FLUSH TABLES WITH READ LOCK' because the latter statement does not
     acquire table-level locks.

     Transactions cannot be nested.  This is a consequence of the
     implicit commit performed for any current transaction when you
     issue a 'START TRANSACTION' statement or one of its
     synonyms.

     Statements that cause an implicit commit cannot be used in an XA
     transaction while the transaction is in an 'ACTIVE' state.

     The 'BEGIN' statement differs from the use of the
     'BEGIN' keyword that starts a 'BEGIN ... END'.
     compound statement.  The latter does not cause an implicit commit.
     See begin-end.

   * *Data loading statements.*  See 'LOAD DATA INFILE'.
     'LOAD DATA INFILE' causes an implicit commit only
     for tables using the 'NDB' storage engine.

   * *Administrative statements.*  See 'ANALYZE TABLE',
     'CACHE INDEX', 'CHECK TABLE',
     'FLUSH', 'LOAD INDEX INTO CACHE',
     'OPTIMIZE TABLE', 'REPAIR TABLE',
     see 'RESET'.

   * *Replication control statements*.  See 'START SLAVE',
     see 'STOP SLAVE', 'RESET SLAVE',
     see 'CHANGE MASTER TO'.

13.3.4 SAVEPOINT, ROLLBACK TO SAVEPOINT, and RELEASE SAVEPOINT Syntax
---------------------------------------------------------------------

     SAVEPOINT IDENTIFIER
     ROLLBACK [WORK] TO [SAVEPOINT] IDENTIFIER
     RELEASE SAVEPOINT IDENTIFIER

'InnoDB' supports the SQL statements 'SAVEPOINT',
'ROLLBACK TO SAVEPOINT', 'RELEASE SAVEPOINT'
and the optional 'WORK' keyword for 'ROLLBACK'.

The 'SAVEPOINT' statement sets a named transaction
savepoint with a name of IDENTIFIER.  If the current transaction has a
savepoint with the same name, the old savepoint is deleted and a new one
is set.

The 'ROLLBACK TO SAVEPOINT' statement rolls back a
transaction to the named savepoint without terminating the transaction.
Modifications that the current transaction made to rows after the
savepoint was set are undone in the rollback, but 'InnoDB' does _not_
release the row locks that were stored in memory after the savepoint.
(For a new inserted row, the lock information is carried by the
transaction ID stored in the row; the lock is not separately stored in
memory.  In this case, the row lock is released in the undo.)
Savepoints that were set at a later time than the named savepoint are
deleted.

If the 'ROLLBACK TO SAVEPOINT' statement returns the
following error, it means that no savepoint with the specified name
exists:

     ERROR 1305 (42000): SAVEPOINT IDENTIFIER does not exist

The 'RELEASE SAVEPOINT' statement removes the named
savepoint from the set of savepoints of the current transaction.  No
commit or rollback occurs.  It is an error if the savepoint does not
exist.

All savepoints of the current transaction are deleted if you execute a
'COMMIT', or a 'ROLLBACK' that does not
name a savepoint.

A new savepoint level is created when a stored function is invoked or a
trigger is activated.  The savepoints on previous levels become
unavailable and thus do not conflict with savepoints on the new level.
When the function or trigger terminates, any savepoints it created are
released and the previous savepoint level is restored.

13.3.5 LOCK TABLES and UNLOCK TABLES Syntax
-------------------------------------------

     LOCK TABLES
         TBL_NAME [[AS] ALIAS] LOCK_TYPE
         [, TBL_NAME [[AS] ALIAS] LOCK_TYPE] ...

     LOCK_TYPE:
         READ [LOCAL]
       | [LOW_PRIORITY] WRITE

     UNLOCK TABLES

MySQL enables client sessions to acquire table locks explicitly for the
purpose of cooperating with other sessions for access to tables, or to
prevent other sessions from modifying tables during periods when a
session requires exclusive access to them.  A session can acquire or
release locks only for itself.  One session cannot acquire locks for
another session or release locks held by another session.

Locks may be used to emulate transactions or to get more speed when
updating tables.  This is explained in more detail later in this
section.

'LOCK TABLES' explicitly acquires table locks for
the current client session.  Table locks can be acquired for base tables
or views.  You must have the 'LOCK TABLES' privilege, and the 'SELECT'
privilege for each object to be locked.

For view locking, see 'LOCK TABLES' adds all base tables
used in the view to the set of tables to be locked and locks them
automatically.  If you lock a table explicitly with 'LOCK TABLES',
any tables used in triggers are also locked implicitly, as
described in lock-tables-and-triggers.

'UNLOCK TABLES' explicitly releases any table locks
held by the current session.  See 'LOCK TABLES'.
implicitly releases any table locks held by the current session before
acquiring new locks.

Another use for 'UNLOCK TABLES' is to release the
global read lock acquired with the 'FLUSH TABLES WITH READ LOCK'
statement, which enables you to lock all tables in all databases.  See
flush.  (This is a very convenient way to get backups if you
have a file system such as Veritas that can take snapshots in time.)

A table lock protects only against inappropriate reads or writes by
other sessions.  A session holding a 'WRITE' lock can perform
table-level operations such as 'DROP TABLE' or
'TRUNCATE TABLE'.  For sessions holding a 'READ' lock,
see 'DROP TABLE' and 'TRUNCATE TABLE'
operations are not permitted.

The following discussion applies only to non-'TEMPORARY' tables.
'LOCK TABLES' is permitted (but ignored) for a 'TEMPORARY'
table.  The table can be accessed freely by the session within which it
was created, regardless of what other locking may be in effect.  No lock
is necessary because no other session can see the table.

For information about other conditions on the use of 'LOCK TABLES'
and statements that cannot be used while
'LOCK TABLES' is in effect, see
lock-tables-restrictions

*Rules for Lock Acquisition*

To acquire table locks within the current session, use the 'LOCK TABLES'
statement.  The following lock types are
available:

'READ [LOCAL]' lock:

   * The session that holds the lock can read the table (but not write
     it).

   * Multiple sessions can acquire a 'READ' lock for the table at the
     same time.

   * Other sessions can read the table without explicitly acquiring a
     'READ' lock.

   * The 'LOCAL' modifier enables nonconflicting 'INSERT'.
     statements (concurrent inserts) by other sessions to execute while
     the lock is held.  (See concurrent-inserts.)  However,
     'READ LOCAL' cannot be used if you are going to manipulate the
     database using processes external to the server while you hold the
     lock.  For 'InnoDB' tables, 'READ LOCAL' is the same as 'READ'.

'[LOW_PRIORITY] WRITE' lock:

   * The session that holds the lock can read and write the table.

   * Only the session that holds the lock can access the table.  No
     other session can access it until the lock is released.

   * Lock requests for the table by other sessions block while the
     'WRITE' lock is held.

   * The 'LOW_PRIORITY' modifier has no effect.  In previous versions of
     MySQL, it affected locking behavior, but this is no longer true.
     It is now deprecated and its use produces a warning.  Use 'WRITE'
     without 'LOW_PRIORITY' instead.

If the 'LOCK TABLES' statement must wait due to
locks held by other sessions on any of the tables, it blocks until all
locks can be acquired.

A session that requires locks must acquire all the locks that it needs
in a single 'LOCK TABLES' statement.  While the
locks thus obtained are held, the session can access only the locked
tables.  For example, in the following sequence of statements, an error
occurs for the attempt to access 't2' because it was not locked in the
'LOCK TABLES' statement:

     mysql> LOCK TABLES t1 READ;
     mysql> SELECT COUNT(*) FROM t1;
     +----------+
     | COUNT(*) |
     +----------+
     |        3 |
     +----------+
     mysql> SELECT COUNT(*) FROM t2;
     ERROR 1100 (HY000): Table 't2' was not locked with LOCK TABLES

Tables in the 'INFORMATION_SCHEMA' database are an exception.  They can
be accessed without being locked explicitly even while a session holds
table locks obtained with 'LOCK TABLES'.

You cannot refer to a locked table multiple times in a single query
using the same name.  Use aliases instead, and obtain a separate lock
for the table and each alias:

     mysql> LOCK TABLE t WRITE, t AS t1 READ;
     mysql> INSERT INTO t SELECT * FROM t;
     ERROR 1100: Table 't' was not locked with LOCK TABLES
     mysql> INSERT INTO t SELECT * FROM t AS t1;

The error occurs for the first 'INSERT' because there are
two references to the same name for a locked table.  The second
'INSERT' succeeds because the references to the table use
different names.

If your statements refer to a table by means of an alias, you must lock
the table using that same alias.  It does not work to lock the table
without specifying the alias:

     mysql> LOCK TABLE t READ;
     mysql> SELECT * FROM t AS myalias;
     ERROR 1100: Table 'myalias' was not locked with LOCK TABLES

Conversely, if you lock a table using an alias, you must refer to it in
your statements using that alias:

     mysql> LOCK TABLE t AS myalias READ;
     mysql> SELECT * FROM t;
     ERROR 1100: Table 't' was not locked with LOCK TABLES
     mysql> SELECT * FROM t AS myalias;

'WRITE' locks normally have higher priority than 'READ' locks to ensure
that updates are processed as soon as possible.  This means that if one
session obtains a 'READ' lock and then another session requests a
'WRITE' lock, subsequent 'READ' lock requests wait until the session
that requested the 'WRITE' lock has obtained the lock and released it.

'LOCK TABLES' acquires locks as follows:

  1. Sort all tables to be locked in an internally defined order.  From
     the user standpoint, this order is undefined.

  2. If a table is to be locked with a read and a write lock, put the
     write lock request before the read lock request.

  3. Lock one table at a time until the session gets all locks.

This policy ensures that table locking is deadlock free.

*Note*:

'LOCK TABLES' or 'UNLOCK TABLES', when applied to a partitioned table,
always locks or unlocks the entire table; these statements do not
support partition lock pruning.  See
partitioning-limitations-locking.

*Rules for Lock Release*

When the table locks held by a session are released, they are all
released at the same time.  A session can release its locks explicitly,
or locks may be released implicitly under certain conditions.

   * A session can release its locks explicitly with 'UNLOCK TABLES'.

   * If a session issues a 'LOCK TABLES' statement
     to acquire a lock while already holding locks, its existing locks
     are released implicitly before the new locks are granted.

   * If a session begins a transaction (for example, with 'START TRANSACTION'),
     an implicit 'UNLOCK TABLES'
     is performed, which causes existing locks to be
     released.  (For additional information about the interaction
     between table locking and transactions, see
     lock-tables-and-transactions.)

If the connection for a client session terminates, whether normally or
abnormally, the server implicitly releases all table locks held by the
session (transactional and nontransactional).  If the client reconnects,
the locks will no longer be in effect.  In addition, if the client had
an active transaction, the server rolls back the transaction upon
disconnect, and if reconnect occurs, the new session begins with
autocommit enabled.  For this reason, clients may wish to disable
auto-reconnect.  With auto-reconnect in effect, the client is not
notified if reconnect occurs but any table locks or current transaction
will have been lost.  With auto-reconnect disabled, if the connection
drops, an error occurs for the next statement issued.  The client can
detect the error and take appropriate action such as reacquiring the
locks or redoing the transaction.  See c-api-auto-reconnect.

*Note*:

If you use 'ALTER TABLE' on a locked table, it may
become unlocked.  For example, if you attempt a second 'ALTER TABLE'
operation, the result may be an error 'Table
'TBL_NAME' was not locked with LOCK TABLES'.  To handle this, lock the
table again prior to the second alteration.  See also
alter-table-problems.

13.3.5.1 Interaction of Table Locking and Transactions
......................................................

'LOCK TABLES' and 'UNLOCK TABLES'
interact with the use of transactions as follows:

   * 'LOCK TABLES' is not transaction-safe and
     implicitly commits any active transaction before attempting to lock
     the tables.

   * 'UNLOCK TABLES' implicitly commits any active
     transaction, but only if 'LOCK TABLES' has been
     used to acquire table locks.  For example, in the following set of
     statements, see 'UNLOCK TABLES' releases the global
     read lock but does not commit the transaction because no table
     locks are in effect:

          FLUSH TABLES WITH READ LOCK;
          START TRANSACTION;
          SELECT ... ;
          UNLOCK TABLES;

   * Beginning a transaction (for example, with 'START TRANSACTION')
     implicitly commits any current transaction
     and releases existing table locks.

   * 'FLUSH TABLES WITH READ LOCK' acquires a global read lock and not
     table locks, so it is not subject to the same behavior as
     'LOCK TABLES' and 'UNLOCK TABLES'.
     with respect to table locking and implicit commits.  For example,
     see 'START TRANSACTION' does not release the global read
     lock.  See flush.

   * Other statements that implicitly cause transactions to be committed
     do not release existing table locks.  For a list of such
     statements, see implicit-commit.

   * The correct way to use 'LOCK TABLES' and
     'UNLOCK TABLES' with transactional tables, such as
     'InnoDB' tables, is to begin a transaction with 'SET autocommit =
     0' (not 'START TRANSACTION') followed by 'LOCK TABLES',
     and to not call 'UNLOCK TABLES'
     until you commit the transaction explicitly.  For
     example, if you need to write to table 't1' and read from table
     't2', you can do this:

          SET autocommit=0;
          LOCK TABLES t1 WRITE, t2 READ, ...;
          ... DO SOMETHING WITH TABLES T1 AND T2 HERE ...
          COMMIT;
          UNLOCK TABLES;

     When you call 'LOCK TABLES', 'InnoDB' internally
     takes its own table lock, and MySQL takes its own table lock.
     'InnoDB' releases its internal table lock at the next commit, but
     for MySQL to release its table lock, you have to call 'UNLOCK TABLES'.
     You should not have 'autocommit = 1',
     because then 'InnoDB' releases its internal table lock immediately
     after the call of 'LOCK TABLES', and deadlocks
     can very easily happen.  'InnoDB' does not acquire the internal
     table lock at all if 'autocommit = 1', to help old applications
     avoid unnecessary deadlocks.

   * 'ROLLBACK' does not release table locks.

13.3.5.2 LOCK TABLES and Triggers
.................................

If you lock a table explicitly with 'LOCK TABLES',
any tables used in triggers are also locked implicitly:

   * The locks are taken as the same time as those acquired explicitly
     with the 'LOCK TABLES' statement.

   * The lock on a table used in a trigger depends on whether the table
     is used only for reading.  If so, a read lock suffices.  Otherwise,
     a write lock is used.

   * If a table is locked explicitly for reading with 'LOCK TABLES',
     but needs to be locked for writing because it
     might be modified within a trigger, a write lock is taken rather
     than a read lock.  (That is, an implicit write lock needed due to
     the table's appearance within a trigger causes an explicit read
     lock request for the table to be converted to a write lock
     request.)

Suppose that you lock two tables, 't1' and 't2', using this statement:

     LOCK TABLES t1 WRITE, t2 READ;

If 't1' or 't2' have any triggers, tables used within the triggers will
also be locked.  Suppose that 't1' has a trigger defined like this:

     CREATE TRIGGER t1_a_ins AFTER INSERT ON t1 FOR EACH ROW
     BEGIN
       UPDATE t4 SET count = count+1
           WHERE id = NEW.id AND EXISTS (SELECT a FROM t3);
       INSERT INTO t2 VALUES(1, 2);
     END;

The result of the 'LOCK TABLES' statement is that
't1' and 't2' are locked because they appear in the statement, and 't3'
and 't4' are locked because they are used within the trigger:

   * 't1' is locked for writing per the 'WRITE' lock request.

   * 't2' is locked for writing, even though the request is for a 'READ'
     lock.  This occurs because 't2' is inserted into within the
     trigger, so the 'READ' request is converted to a 'WRITE' request.

   * 't3' is locked for reading because it is only read from within the
     trigger.

   * 't4' is locked for writing because it might be updated within the
     trigger.

13.3.5.3 Table-Locking Restrictions and Conditions
..................................................

You can safely use 'KILL' to terminate a session that is
waiting for a table lock.  See kill.

'LOCK TABLES' and 'UNLOCK TABLES'
cannot be used within stored programs.

Tables in the 'performance_schema' database cannot be locked with
'LOCK TABLES', except the 'setup_XXX' tables.

The following statements are prohibited while a 'LOCK TABLES'
statement is in effect: 'CREATE TABLE',
'CREATE TABLE ... LIKE', 'CREATE VIEW',
see 'DROP VIEW', and DDL statements on stored
functions and procedures and events.

For some operations, system tables in the 'mysql' database must be
accessed.  For example, the 'HELP' statement requires the
contents of the server-side help tables, and 'CONVERT_TZ()' might need
to read the time zone tables.  The server implicitly locks the system
tables for reading as necessary so that you need not lock them
explicitly.  These tables are treated as just described:

     mysql.help_category
     mysql.help_keyword
     mysql.help_relation
     mysql.help_topic
     mysql.proc
     mysql.time_zone
     mysql.time_zone_leap_second
     mysql.time_zone_name
     mysql.time_zone_transition
     mysql.time_zone_transition_type

If you want to explicitly place a 'WRITE' lock on any of those tables
with a 'LOCK TABLES' statement, the table must be
the only one locked; no other table can be locked with the same
statement.

Normally, you do not need to lock tables, because all single
'UPDATE' statements are atomic; no other session can interfere
with any other currently executing SQL statement.  However, there are a
few cases when locking tables may provide an advantage:

   * If you are going to run many operations on a set of 'MyISAM'
     tables, it is much faster to lock the tables you are going to use.
     Locking 'MyISAM' tables speeds up inserting, updating, or deleting
     on them because MySQL does not flush the key cache for the locked
     tables until 'UNLOCK TABLES' is called.
     Normally, the key cache is flushed after each SQL statement.

     The downside to locking the tables is that no session can update a
     'READ'-locked table (including the one holding the lock) and no
     session can access a 'WRITE'-locked table other than the one
     holding the lock.

   * If you are using tables for a nontransactional storage engine, you
     must use 'LOCK TABLES' if you want to ensure
     that no other session modifies the tables between a 'SELECT'
     and an 'UPDATE'.  The example shown here
     requires 'LOCK TABLES' to execute safely:

          LOCK TABLES trans READ, customer WRITE;
          SELECT SUM(value) FROM trans WHERE customer_id=SOME_ID;
          UPDATE customer
            SET total_value=SUM_FROM_PREVIOUS_STATEMENT
            WHERE customer_id=SOME_ID;
          UNLOCK TABLES;

     Without 'LOCK TABLES', it is possible that
     another session might insert a new row in the 'trans' table between
     execution of the 'SELECT' and 'UPDATE'
     statements.

You can avoid using 'LOCK TABLES' in many cases by
using relative updates ('UPDATE customer SET VALUE=VALUE+NEW_VALUE') or
the 'LAST_INSERT_ID()' function.

You can also avoid locking tables in some cases by using the user-level
advisory lock functions 'GET_LOCK()' and 'RELEASE_LOCK()'.  These locks
are saved in a hash table in the server and implemented with
'pthread_mutex_lock()' and 'pthread_mutex_unlock()' for high speed.  See
miscellaneous-functions.

See internal-locking, for more information on locking policy.

13.3.6 SET TRANSACTION Syntax
-----------------------------

     SET [GLOBAL | SESSION] TRANSACTION
         TRANSACTION_CHARACTERISTIC [, TRANSACTION_CHARACTERISTIC] ...

     TRANSACTION_CHARACTERISTIC:
         ISOLATION LEVEL LEVEL
       | READ WRITE
       | READ ONLY

     LEVEL:
          REPEATABLE READ
        | READ COMMITTED
        | READ UNCOMMITTED
        | SERIALIZABLE

This statement specifies transaction characteristics.  It takes a list
of one or more characteristic values separated by commas.  These
characteristics set the transaction isolation level or access mode.  The
isolation level is used for operations on 'InnoDB'
tables.  The access mode may be specified as to
whether transactions operate in read/write or read-only mode.

In addition, see 'SET TRANSACTION' can include an
optional 'GLOBAL' or 'SESSION' keyword to indicate the scope of the
statement.

*Scope of Transaction Characteristics*

You can set transaction characteristics globally, for the current
session, or for the next transaction:

   * With the 'GLOBAL' keyword, the statement applies globally for all
     subsequent sessions.  Existing sessions are unaffected.

   * With the 'SESSION' keyword, the statement applies to all subsequent
     transactions performed within the current session.

   * Without any 'SESSION' or 'GLOBAL' keyword, the statement applies to
     the next (not started) transaction performed within the current
     session.  Subsequent transactions revert to using the 'SESSION'
     isolation level.

A global change to transaction characteristics requires the 'SUPER'
privilege.  Any session is free to change its session characteristics
(even in the middle of a transaction), or the characteristics for its
next transaction.

'SET TRANSACTION' without 'GLOBAL' or 'SESSION'
is not permitted while there is an active transaction:

     mysql> START TRANSACTION;
     Query OK, 0 rows affected (0.02 sec)

     mysql> SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;
     ERROR 1568 (25001): Transaction characteristics can't be changed
     while a transaction is in progress

To set the global default isolation level at server startup, use the
'--transaction-isolation=LEVEL' option to 'mysqld' on the
command line or in an option file.  Values of LEVEL for this option use
dashes rather than spaces, so the permissible values are
'READ-UNCOMMITTED', 'READ-COMMITTED', 'REPEATABLE-READ', or
'SERIALIZABLE'.  For example, to set the default isolation level to
'REPEATABLE READ', use these lines in the '[mysqld]' section of an
option file:

     [mysqld]
     transaction-isolation = REPEATABLE-READ

It is possible to check or set the global and session transaction
isolation levels at runtime by using the 'transaction_isolation' system
variable:

     SELECT @@GLOBAL.transaction_isolation, @@transaction_isolation;
     SET GLOBAL transaction_isolation='REPEATABLE-READ';
     SET SESSION transaction_isolation='SERIALIZABLE';

Prior to MySQL 5.7.20, use 'tx_isolation' rather than
'transaction_isolation'.

Similarly, to set the transaction access mode at server startup or at
runtime, use the '--transaction-read-only' option or
'transaction_read_only' system variable.  By default, these are 'OFF'
(the mode is read/write) but can be set to 'ON' for a default mode of
read only.

Prior to MySQL 5.7.20, use 'tx_read_only' rather than
'transaction_read_only'.

Setting the global or session value of 'transaction_isolation' or
'transaction_read_only' is equivalent to setting the isolation level or
access mode with 'SET GLOBAL TRANSACTION' or
'SET SESSION TRANSACTION'.

*Transaction Isolation Levels*

For information about transaction isolation levels, see
innodb-transaction-isolation-levels.

*Transaction Access Mode*

The transaction access mode may be specified with 'SET TRANSACTION'.
By default, a transaction takes place in
read/write mode, with both reads and writes permitted to tables used in
the transaction.  This mode may be specified explicitly using an access
mode of 'READ WRITE'.

If the transaction access mode is set to 'READ ONLY', changes to tables
are prohibited.  This may enable storage engines to make performance
improvements that are possible when writes are not permitted.

It is not permitted to specify both 'READ WRITE' and 'READ ONLY' in the
same statement.

In read-only mode, it remains possible to change tables created with the
'TEMPORARY' keyword using DML statements.  Changes made with DDL
statements are not permitted, just as with permanent tables.

The 'READ WRITE' and 'READ ONLY' access modes also may be specified for
an individual transaction using the 'START TRANSACTION'.
statement.

13.3.7 XA Transactions
----------------------

Support for XA transactions is available for the 'InnoDB'
storage engine.  The MySQL XA implementation is
based on the X/Open CAE document 'Distributed Transaction Processing:
The XA Specification'.  This document is published by The Open Group and
available at <http://www.opengroup.org/public/pubs/catalog/c193.htm>.
Limitations of the current XA implementation are described in
xa-restrictions.

On the client side, there are no special requirements.  The XA interface
to a MySQL server consists of SQL statements that begin with the 'XA'
keyword.  MySQL client programs must be able to send SQL statements and
to understand the semantics of the XA statement interface.  They do not
need be linked against a recent client library.  Older client libraries
also will work.

Among the MySQL Connectors, MySQL Connector/J 5.0.0 and higher supports
XA directly, by means of a class interface that handles the XA SQL
statement interface for you.

XA supports distributed transactions, that is, the ability to permit
multiple separate transactional resources to participate in a global
transaction.  Transactional resources often are RDBMSs but may be other
kinds of resources.

A global transaction involves several actions that are transactional in
themselves, but that all must either complete successfully as a group,
or all be rolled back as a group.  In essence, this extends ACID
properties 'up a level' so that multiple ACID transactions can be
executed in concert as components of a global operation that also has
ACID properties.  (As with nondistributed transactions, 'SERIALIZABLE'
may be preferred if your applications are sensitive to read phenomena.
'REPEATABLE READ' may not be sufficient for distributed transactions.)

Some examples of distributed transactions:

   * An application may act as an integration tool that combines a
     messaging service with an RDBMS. The application makes sure that
     transactions dealing with message sending, retrieval, and
     processing that also involve a transactional database all happen in
     a global transaction.  You can think of this as 'transactional
     email.'

   * An application performs actions that involve different database
     servers, such as a MySQL server and an Oracle server (or multiple
     MySQL servers), where actions that involve multiple servers must
     happen as part of a global transaction, rather than as separate
     transactions local to each server.

   * A bank keeps account information in an RDBMS and distributes and
     receives money through automated teller machines (ATMs).  It is
     necessary to ensure that ATM actions are correctly reflected in the
     accounts, but this cannot be done with the RDBMS alone.  A global
     transaction manager integrates the ATM and database resources to
     ensure overall consistency of financial transactions.

Applications that use global transactions involve one or more Resource
Managers and a Transaction Manager:

   * A Resource Manager (RM) provides access to transactional resources.
     A database server is one kind of resource manager.  It must be
     possible to either commit or roll back transactions managed by the
     RM.

   * A Transaction Manager (TM) coordinates the transactions that are
     part of a global transaction.  It communicates with the RMs that
     handle each of these transactions.  The individual transactions
     within a global transaction are 'branches' of the global
     transaction.  Global transactions and their branches are identified
     by a naming scheme described later.

The MySQL implementation of XA enables a MySQL server to act as a
Resource Manager that handles XA transactions within a global
transaction.  A client program that connects to the MySQL server acts as
the Transaction Manager.

To carry out a global transaction, it is necessary to know which
components are involved, and bring each component to a point when it can
be committed or rolled back.  Depending on what each component reports
about its ability to succeed, they must all commit or roll back as an
atomic group.  That is, either all components must commit, or all
components must roll back.  To manage a global transaction, it is
necessary to take into account that any component or the connecting
network might fail.

The process for executing a global transaction uses two-phase commit
(2PC). This takes place after the actions performed by the branches of
the global transaction have been executed.

  1. In the first phase, all branches are prepared.  That is, they are
     told by the TM to get ready to commit.  Typically, this means each
     RM that manages a branch records the actions for the branch in
     stable storage.  The branches indicate whether they are able to do
     this, and these results are used for the second phase.

  2. In the second phase, the TM tells the RMs whether to commit or roll
     back.  If all branches indicated when they were prepared that they
     will be able to commit, all branches are told to commit.  If any
     branch indicated when it was prepared that it will not be able to
     commit, all branches are told to roll back.

In some cases, a global transaction might use one-phase commit (1PC).
For example, when a Transaction Manager finds that a global transaction
consists of only one transactional resource (that is, a single branch),
that resource can be told to prepare and commit at the same time.

13.3.7.1 XA Transaction SQL Syntax
..................................

To perform XA transactions in MySQL, use the following statements:

     XA {START|BEGIN} XID [JOIN|RESUME]

     XA END XID [SUSPEND [FOR MIGRATE]]

     XA PREPARE XID

     XA COMMIT XID [ONE PHASE]

     XA ROLLBACK XID

     XA RECOVER [CONVERT XID]

For 'XA START', the 'JOIN' and 'RESUME' clauses are
not supported.

For 'XA END' the 'SUSPEND [FOR MIGRATE]' clause is
not supported.

Each XA statement begins with the 'XA' keyword, and most of them require
an XID value.  An XID is an XA transaction identifier.  It indicates
which transaction the statement applies to.  XID values are supplied by
the client, or generated by the MySQL server.  An XID value has from one
to three parts:

     XID: GTRID [, BQUAL [, FORMATID ]]

GTRID is a global transaction identifier, BQUAL is a branch qualifier,
and FORMATID is a number that identifies the format used by the GTRID
and BQUAL values.  As indicated by the syntax, BQUAL and FORMATID are
optional.  The default BQUAL value is '''' if not given.  The default
FORMATID value is 1 if not given.

GTRID and BQUAL must be string literals, each up to 64 bytes (not
characters) long.  GTRID and BQUAL can be specified in several ways.
You can use a quoted string (''ab''), hex string ('X'6162'', '0x6162'),
or bit value ('b'NNNN'').

FORMATID is an unsigned integer.

The GTRID and BQUAL values are interpreted in bytes by the MySQL
server's underlying XA support routines.  However, while an SQL
statement containing an XA statement is being parsed, the server works
with some specific character set.  To be safe, write GTRID and BQUAL as
hex strings.

XID values typically are generated by the Transaction Manager.  Values
generated by one TM must be different from values generated by other
TMs.  A given TM must be able to recognize its own XID values in a list
of values returned by the 'XA RECOVER' statement.

For 'XA START XID' starts an XA transaction with
the given XID value.  Each XA transaction must have a unique XID value,
so the value must not currently be used by another XA transaction.
Uniqueness is assessed using the GTRID and BQUAL values.  All following
XA statements for the XA transaction must be specified using the same
XID value as that given in the 'XA START'.
statement.  If you use any of those statements but specify an XID value
that does not correspond to some existing XA transaction, an error
occurs.

One or more XA transactions can be part of the same global transaction.
All XA transactions within a given global transaction must use the same
GTRID value in the XID value.  For this reason, GTRID values must be
globally unique so that there is no ambiguity about which global
transaction a given XA transaction is part of.  The BQUAL part of the
XID value must be different for each XA transaction within a global
transaction.  (The requirement that BQUAL values be different is a
limitation of the current MySQL XA implementation.  It is not part of
the XA specification.)

The 'XA RECOVER' statement returns information for
those XA transactions on the MySQL server that are in the 'PREPARED'
state.  (See xa-states.)  The output includes a row for each
such XA transaction on the server, regardless of which client started
it.

'XA RECOVER' output rows look like this (for an
example XID value consisting of the parts ''abc'', ''def'', and '7'):

     mysql> XA RECOVER;
     +----------+--------------+--------------+--------+
     | formatID | gtrid_length | bqual_length | data   |
     +----------+--------------+--------------+--------+
     |        7 |            3 |            3 | abcdef |
     +----------+--------------+--------------+--------+

The output columns have the following meanings:

   * 'formatID' is the FORMATID part of the transaction XID

   * 'gtrid_length' is the length in bytes of the GTRID part of the XID

   * 'bqual_length' is the length in bytes of the BQUAL part of the XID

   * 'data' is the concatenation of the GTRID and BQUAL parts of the XID

XID values may contain nonprintable characters.  As of MySQL 5.7.5,
see 'XA RECOVER' permits an optional 'CONVERT XID'
clause so that clients can request XID values in hexadecimal.

13.3.7.2 XA Transaction States
..............................

An XA transaction progresses through the following states:

  1. Use 'XA START' to start an XA transaction and
     put it in the 'ACTIVE' state.

  2. For an 'ACTIVE' XA transaction, issue the SQL statements that make
     up the transaction, and then issue an 'XA END'
     statement.  'XA END' puts the
     transaction in the 'IDLE' state.

  3. For an 'IDLE' XA transaction, you can issue either an 'XA PREPARE'
     statement or an 'XA COMMIT ... ONE PHASE'
     statement:

        * 'XA PREPARE' puts the transaction in the
          'PREPARED' state.  An 'XA RECOVER'.
          statement at this point will include the transaction's XID
          value in its output, because 'XA RECOVER'
          lists all XA transactions that are in the
          'PREPARED' state.

        * 'XA COMMIT ... ONE PHASE' prepares and commits the
          transaction.  The XID value will not be listed by 'XA RECOVER'
          because the transaction terminates.

  4. For a 'PREPARED' XA transaction, you can issue an 'XA COMMIT'
     statement to commit and terminate the
     transaction, or 'XA ROLLBACK' to roll back
     and terminate the transaction.

Here is a simple XA transaction that inserts a row into a table as part
of a global transaction:

     mysql> XA START 'xatest';
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO mytable (i) VALUES(10);
     Query OK, 1 row affected (0.04 sec)

     mysql> XA END 'xatest';
     Query OK, 0 rows affected (0.00 sec)

     mysql> XA PREPARE 'xatest';
     Query OK, 0 rows affected (0.00 sec)

     mysql> XA COMMIT 'xatest';
     Query OK, 0 rows affected (0.00 sec)

Within the context of a given client connection, XA transactions and
local (non-XA) transactions are mutually exclusive.  For example, if
'XA START' has been issued to begin an XA
transaction, a local transaction cannot be started until the XA
transaction has been committed or rolled back.  Conversely, if a local
transaction has been started with 'START TRANSACTION', no
XA statements can be used until the transaction has been committed or
rolled back.

If an XA transaction is in the 'ACTIVE' state, you cannot issue any
statements that cause an implicit commit.  That would violate the XA
contract because you could not roll back the XA transaction.  You will
receive the following error if you try to execute such a statement:

     ERROR 1399 (XAE07): XAER_RMFAIL: The command cannot be executed
     when global transaction is in the ACTIVE state

Statements to which the preceding remark applies are listed at
implicit-commit.

13.4 Replication Statements
===========================

Replication can be controlled through the SQL interface using the
statements described in this section.  Statements are split into a group
which controls master servers, a group which controls slave servers, and
a group which can be applied to any replication servers.

13.4.1 SQL Statements for Controlling Master Servers
----------------------------------------------------

This section discusses statements for managing master replication
servers.  See replication-slave-sql, discusses statements for
managing slave servers.

In addition to the statements described here, the following
'SHOW' statements are used with master servers in replication.
For information about these statements, see show.

   * 'SHOW BINARY LOGS'.

   * 'SHOW BINLOG EVENTS'.

   * 'SHOW MASTER STATUS'.

   * 'SHOW SLAVE HOSTS'.

13.4.1.1 PURGE BINARY LOGS Syntax
.................................

     PURGE { BINARY | MASTER } LOGS
         { TO 'LOG_NAME' | BEFORE DATETIME_EXPR }

The binary log is a set of files that contain information about data
modifications made by the MySQL server.  The log consists of a set of
binary log files, plus an index file (see binary-log).

The 'PURGE BINARY LOGS' statement deletes all
the binary log files listed in the log index file prior to the specified
log file name or date.  'BINARY' and 'MASTER' are synonyms.  Deleted log
files also are removed from the list recorded in the index file, so that
the given log file becomes the first in the list.

This statement has no effect if the server was not started with the
'--log-bin' option to enable binary logging.

Examples:

     PURGE BINARY LOGS TO 'mysql-bin.010';
     PURGE BINARY LOGS BEFORE '2008-04-02 22:46:26';

The 'BEFORE' variant's DATETIME_EXPR argument should evaluate to a
'DATETIME' value (a value in ''YYYY-MM-DD hh:mm:ss'' format).

This statement is safe to run while slaves are replicating.  You need
not stop them.  If you have an active slave that currently is reading
one of the log files you are trying to delete, this statement does not
delete the log file that is in use or any log files later than that one,
but it deletes any earlier log files.  A warning message is issued in
this situation.  However, if a slave is not connected and you happen to
purge one of the log files it has yet to read, the slave will be unable
to replicate after it reconnects.

To safely purge binary log files, follow this procedure:

  1. On each slave server, use 'SHOW SLAVE STATUS'
     to check which log file it is reading.

  2. Obtain a listing of the binary log files on the master server with
     'SHOW BINARY LOGS'.

  3. Determine the earliest log file among all the slaves.  This is the
     target file.  If all the slaves are up to date, this is the last
     log file on the list.

  4. Make a backup of all the log files you are about to delete.  (This
     step is optional, but always advisable.)

  5. Purge all log files up to but not including the target file.

You can also set the 'expire_logs_days' system variable to expire binary
log files automatically after a given number of days (see
server-system-variables).  If you are using replication, you should
set the variable no lower than the maximum number of days your slaves
might lag behind the master.

'PURGE BINARY LOGS TO' and 'PURGE BINARY LOGS BEFORE' both fail with an
error when binary log files listed in the '.index' file had been removed
from the system by some other means (such as using 'rm' on Linux).  (Bug
#18199, Bug #18453) To handle such errors, edit the '.index' file (which
is a simple text file) manually to ensure that it lists only the binary
log files that are actually present, then run again the 'PURGE BINARY LOGS'
statement that failed.

13.4.1.2 RESET MASTER Syntax
............................

     RESET MASTER

Deletes all binary log files listed in the index file, resets the binary
log index file to be empty, and creates a new binary log file.

*Warning*:

Use this statement with caution to ensure you do not lose binary log
file data.

'RESET MASTER' also clears the values of the 'gtid_purged' system
variable as well as the global value of the 'gtid_executed' system
variable (but not its session value); that is, executing this statement
sets each of these values to an empty string ('''').  In MySQL 5.7.5 and
later, this statement also clears the 'mysql.gtid_executed' table (see
replication-gtids-gtid-executed-table).

*Important*:

The effects of 'RESET MASTER' differ from those of
'PURGE BINARY LOGS' in 2 key ways:

  1. 'RESET MASTER' removes _all_ binary log files
     that are listed in the index file, leaving only a single, empty
     binary log file with a numeric suffix of '.000001', whereas the
     numbering is not reset by 'PURGE BINARY LOGS'.

  2. 'RESET MASTER' is _not_ intended to be used
     while any replication slaves are running.  The behavior of
     'RESET MASTER' when used while slaves are running is
     undefined (and thus unsupported), whereas 'PURGE BINARY LOGS'
     may be safely used while replication
     slaves are running.

See also purge-binary-logs.

'RESET MASTER' can prove useful when you first set
up the master and the slave, so that you can verify the setup as
follows:

  1. Start the master and slave, and start replication (see
     replication-howto).

  2. Execute a few test queries on the master.

  3. Check that the queries were replicated to the slave.

  4. When replication is running correctly, issue 'STOP SLAVE'
     followed by 'RESET SLAVE' on the
     slave, then verify that any unwanted data no longer exists on the
     slave.

  5. Issue 'RESET MASTER' on the master to clean up
     the test queries.

After verifying the setup, resetting the master and slave and ensuring
that no unwanted data or binary log files generated by testing remain on
master or slave, you can start the slave and begin replicating.

13.4.1.3 SET sql_log_bin Syntax
...............................

     SET sql_log_bin = {0|1}

The 'sql_log_bin' variable controls whether logging to the binary log is
done.  The default value is 1 (do logging).  To change logging for the
current session, change the session value of this variable.  The session
user must have the 'SUPER' privilege to set this variable.  Set this
variable to 0 for a session to temporarily disable binary logging while
making changes to the master which you do not want to replicate to the
slave.

The global 'sql_log_bin' variable is read only and cannot be modified.
The global scope is deprecated and will be removed in a future MySQL
release.

It is not possible to set '@@session.sql_log_bin' within a transaction
or subquery.

13.4.2 SQL Statements for Controlling Slave Servers
---------------------------------------------------

This section discusses statements for managing slave replication
servers.  See replication-master-sql, discusses statements for
managing master servers.

In addition to the statements described here, see 'SHOW SLAVE STATUS'
and 'SHOW RELAYLOG EVENTS'
are also used with replication slaves.  For
information about these statements, see show-slave-status, and
show-relaylog-events.

13.4.2.1 CHANGE MASTER TO Syntax
................................

     CHANGE MASTER TO OPTION [, OPTION] ... [ CHANNEL_OPTION ]

     OPTION:
         MASTER_BIND = 'INTERFACE_NAME'
       | MASTER_HOST = 'HOST_NAME'
       | MASTER_USER = 'USER_NAME'
       | MASTER_PASSWORD = 'PASSWORD'
       | MASTER_PORT = PORT_NUM
       | MASTER_CONNECT_RETRY = INTERVAL
       | MASTER_RETRY_COUNT = COUNT
       | MASTER_DELAY = INTERVAL
       | MASTER_HEARTBEAT_PERIOD = INTERVAL
       | MASTER_LOG_FILE = 'MASTER_LOG_NAME'
       | MASTER_LOG_POS = MASTER_LOG_POS
       | MASTER_AUTO_POSITION = {0|1}
       | RELAY_LOG_FILE = 'RELAY_LOG_NAME'
       | RELAY_LOG_POS = RELAY_LOG_POS
       | MASTER_SSL = {0|1}
       | MASTER_SSL_CA = 'CA_FILE_NAME'
       | MASTER_SSL_CAPATH = 'CA_DIRECTORY_NAME'
       | MASTER_SSL_CERT = 'CERT_FILE_NAME'
       | MASTER_SSL_CRL = 'CRL_FILE_NAME'
       | MASTER_SSL_CRLPATH = 'CRL_DIRECTORY_NAME'
       | MASTER_SSL_KEY = 'KEY_FILE_NAME'
       | MASTER_SSL_CIPHER = 'CIPHER_LIST'
       | MASTER_SSL_VERIFY_SERVER_CERT = {0|1}
       | MASTER_TLS_VERSION = 'PROTOCOL_LIST'
       | IGNORE_SERVER_IDS = (SERVER_ID_LIST)

     CHANNEL_OPTION:
         FOR CHANNEL CHANNEL

     SERVER_ID_LIST:
         [SERVER_ID [, SERVER_ID] ... ]

'CHANGE MASTER TO' changes the parameters that
the slave server uses for connecting to the master server, for reading
the master binary log, and reading the slave relay log.  It also updates
the contents of the master info and relay log info repositories (see
slave-logs).  See 'CHANGE MASTER TO'.
requires the 'SUPER' privilege.

Prior to MySQL 5.7.4, the slave replication threads must be stopped,
using 'STOP SLAVE' if necessary, before issuing this
statement.  In MySQL 5.7.4 and later, you can issue 'CHANGE MASTER TO'
statements on a running slave without doing this, depending on the
states of the slave SQL thread and slave I/O thread.  The rules
governing such use are provided later in this section.

When using a multi-threaded slave (in other words
'slave_parallel_workers' is greater than 0), stopping the slave can
cause 'gaps' in the sequence of transactions that have been executed
from the relay log, regardless of whether the slave was stopped
intentionally or otherwise.  When such gaps exist, issuing 'CHANGE MASTER TO'
fails.  The solution in this situation is
to issue 'START SLAVE UNTIL SQL_AFTER_MTS_GAPS'.
which ensures that the gaps are closed.

The optional 'FOR CHANNEL CHANNEL' clause enables you to name which
replication channel the statement applies to.  Providing a 'FOR CHANNEL
CHANNEL' clause applies the 'CHANGE MASTER TO' statement to a specific
replication channel, and is used to add a new channel or modify an
existing channel.  For example, to add a new channel called channel2:

     CHANGE MASTER TO MASTER_HOST=host1, MASTER_PORT=3002 FOR CHANNEL 'channel2'

If no clause is named and no extra channels exist, the statement applies
to the default channel.

When using multiple replication channels, if a 'CHANGE MASTER TO'
statement does not name a channel using a 'FOR CHANNEL CHANNEL' clause,
an error occurs.  See replication-channels for more information.

Options not specified retain their value, except as indicated in the
following discussion.  Thus, in most cases, there is no need to specify
options that do not change.  For example, if the password to connect to
your MySQL master has changed, issue this statement to tell the slave
about the new password:

     CHANGE MASTER TO MASTER_PASSWORD='new3cret';

'MASTER_HOST', 'MASTER_USER', 'MASTER_PASSWORD', and 'MASTER_PORT'
provide information to the slave about how to connect to its master:

   * 'MASTER_HOST' and 'MASTER_PORT' are the host name (or IP address)
     of the master host and its TCP/IP port.

     *Note*:

     Replication cannot use Unix socket files.  You must be able to
     connect to the master MySQL server using TCP/IP.

     If you specify the 'MASTER_HOST' or 'MASTER_PORT' option, the slave
     assumes that the master server is different from before (even if
     the option value is the same as its current value.)  In this case,
     the old values for the master binary log file name and position are
     considered no longer applicable, so if you do not specify
     'MASTER_LOG_FILE' and 'MASTER_LOG_POS' in the statement,
     'MASTER_LOG_FILE=''' and 'MASTER_LOG_POS=4' are silently appended
     to it.

     Setting 'MASTER_HOST=''' (that is, setting its value explicitly to
     an empty string) is _not_ the same as not setting 'MASTER_HOST' at
     all.  Beginning with MySQL 5.5, trying to set 'MASTER_HOST' to an
     empty string fails with an error.  Previously, setting
     'MASTER_HOST' to an empty string caused 'START SLAVE'
     subsequently to fail.  (Bug #28796)

     Values used for 'MASTER_HOST' and other 'CHANGE MASTER TO' options
     are checked for linefeed ('\n' or '0x0A') characters; the presence
     of such characters in these values causes the statement to fail
     with 'ER_MASTER_INFO'.  (Bug #11758581, Bug #50801)

   * 'MASTER_USER' and 'MASTER_PASSWORD' are the user name and password
     of the account to use for connecting to the master.

     'MASTER_USER' cannot be made empty; setting 'MASTER_USER = ''' or
     leaving it unset when setting a value for 'MASTER_PASSWORD' causes
     an error (Bug #13427949).

     The password used for a MySQL Replication slave account in a
     'CHANGE MASTER TO' statement is limited to 32 characters in length;
     prior to MySQL 5.7.5, if the password was longer, the statement
     succeeded, but any excess characters were silently truncated.  In
     MySQL 5.7.5 and later, trying to use a password of more than 32
     characters causes 'CHANGE MASTER TO' to fail.  (Bug #11752299, Bug
     #43439)

     The text of a running 'CHANGE MASTER TO'.
     statement, including values for 'MASTER_USER' and
     'MASTER_PASSWORD', can be seen in the output of a concurrent
     'SHOW PROCESSLIST' statement.  (The complete
     text of a 'START SLAVE' statement is also
     visible to 'SHOW PROCESSLIST')

The 'MASTER_SSL_XXX' options, and the 'MASTER_TLS_VERSION' option,
specify how the slave uses encryption and ciphers to secure the
replication connection.  These options can be changed even on slaves
that are compiled without SSL support.  They are saved to the master
info repository, but are ignored if the slave does not have SSL support
enabled.  The 'MASTER_SSL_XXX' options perform the same functions as the
'--ssl-XXX' options described in encrypted-connection-options.
The correspondence between the two sets of options, and the use of the
'MASTER_SSL_XXX' and 'MASTER_TLS_VERSION' options to set up a secure
connection, is explained in
replication-solutions-encrypted-connections.

As of MySQL 5.7.3, 'MASTER_SSL=1' is prescriptive, not advisory.  When
given, the slave connection to the master must use SSL or the connection
attempt fails.  Before 5.7.3, an SSL connection is permitted but not
required.  This is analogous to the client-side meaning of the '--ssl'
command-line option; see encrypted-connection-options.

'MASTER_CONNECT_RETRY' specifies how many seconds to wait between
connect retries.  The default is 60.

'MASTER_RETRY_COUNT' limits the _number_ of reconnection attempts and
updates the value of the 'Master_Retry_Count' column in the output of
'SHOW SLAVE STATUS'.  The default value is 24 *
3600 = 86400.  'MASTER_RETRY_COUNT' is intended to replace the older
'--master-retry-count' server option, and is now the preferred method
for setting this limit.  You are encouraged not to rely on
'--master-retry-count' in new applications and, when upgrading from
versions earlier than MySQL 5.6, to update any existing applications
that rely on it, so that they use 'CHANGE MASTER TO ...
MASTER_RETRY_COUNT' instead.

'MASTER_DELAY' specifies how many seconds behind the master the slave
must lag.  An event received from the master is not executed until at
least INTERVAL seconds later than its execution on the master.  The
default is 0.  An error occurs if INTERVAL is not a nonnegative integer
in the range from 0 to 2^31−1.  For more information, see
replication-delayed.

From MySQL 5.7, a 'CHANGE MASTER TO' statement employing the
'MASTER_DELAY' option can be executed on a running slave when the slave
SQL thread is stopped.

'MASTER_BIND' is for use on replication slaves having multiple network
interfaces, and determines which of the slave's network interfaces is
chosen for connecting to the master.

The address configured with this option, if any, can be seen in the
'Master_Bind' column of the output from 'SHOW SLAVE STATUS'.
If you are using slave status log tables (server
started with '--master-info-repository=TABLE'), the value can also be
seen as the 'Master_bind' column of the 'mysql.slave_master_info' table.

The ability to bind a replication slave to a specific network interface
is also supported by NDB Cluster.

'MASTER_HEARTBEAT_PERIOD' sets the interval in seconds between
replication heartbeats.  Whenever the master's binary log is updated
with an event, the waiting period for the next heartbeat is reset.
INTERVAL is a decimal value having the range 0 to 4294967 seconds and a
resolution in milliseconds; the smallest nonzero value is 0.001.
Heartbeats are sent by the master only if there are no unsent events in
the binary log file for a period longer than INTERVAL.

Prior to MySQL 5.7.4, not including 'MASTER_HEARTBEAT_PERIOD' caused
'CHANGE MASTER TO' to reset the heartbeat period
('Slave_heartbeat_period') to the default, and
'Slave_received_heartbeats' to 0.  (Bug #18185490)

If you are logging master connection information to tables,
'MASTER_HEARTBEAT_PERIOD' can be seen as the value of the 'Heartbeat'
column of the 'mysql.slave_master_info' table.

Setting INTERVAL to 0 disables heartbeats altogether.  The default value
for INTERVAL is equal to the value of 'slave_net_timeout' divided by 2.

Setting '@@global.slave_net_timeout' to a value less than that of the
current heartbeat interval results in a warning being issued.  The
effect of issuing 'RESET SLAVE' on the heartbeat
interval is to reset it to the default value.

'MASTER_LOG_FILE' and 'MASTER_LOG_POS' are the coordinates at which the
slave I/O thread should begin reading from the master the next time the
thread starts.  'RELAY_LOG_FILE' and 'RELAY_LOG_POS' are the coordinates
at which the slave SQL thread should begin reading from the relay log
the next time the thread starts.  If you specify either of
'MASTER_LOG_FILE' or 'MASTER_LOG_POS', you cannot specify
'RELAY_LOG_FILE' or 'RELAY_LOG_POS'.  If you specify either of
'MASTER_LOG_FILE' or 'MASTER_LOG_POS', you also cannot specify
'MASTER_AUTO_POSITION = 1' (described later in this section).  If
neither of 'MASTER_LOG_FILE' or 'MASTER_LOG_POS' is specified, the slave
uses the last coordinates of the _slave SQL thread_ before 'CHANGE MASTER TO'
was issued.  This ensures that there is no
discontinuity in replication, even if the slave SQL thread was late
compared to the slave I/O thread, when you merely want to change, say,
the password to use.

From MySQL 5.7, a 'CHANGE MASTER TO' statement employing
'RELAY_LOG_FILE', 'RELAY_LOG_POS', or both options can be executed on a
running slave when the slave SQL thread is stopped.

If 'MASTER_AUTO_POSITION = 1' is used with 'CHANGE MASTER TO', the slave
attempts to connect to the master using the GTID-based replication
protocol.  From MySQL 5.7, this option can be employed by 'CHANGE MASTER
TO' only if both the slave SQL and slave I/O threads are stopped.

When using GTIDs, the slave tells the master which transactions it has
already received, executed, or both.  To compute this set, it reads the
global value of 'gtid_executed' and the value of the
'Retrieved_gtid_set' column from 'SHOW SLAVE STATUS'.
The GTID of the last transmitted transaction is
included in 'Retrieved_gtid_set' only when the full transaction is
received.  The slave computes the following set:

     UNION(@@global.gtid_executed, Retrieved_gtid_set)

Prior to MySQL 5.7.5, the GTID of the last transmitted transaction was
included in 'Retrieved_gtid_set' _even if_ the transaction was only
partially transmitted, and the last received GTID was subtracted from
this set.  (Bug #17943188) Thus, the slave computed the following set:

     UNION(@@global.gtid_executed, Retrieved_gtid_set - LAST_RECEIVED_GTID)

This set is sent to the master as part of the initial handshake, and the
master sends back all transactions that it has executed which are not
part of the set.  If any of these transactions have been already purged
from the master's binary log, the master sends the error
'ER_MASTER_HAS_PURGED_REQUIRED_GTIDS' to the slave, and replication does
not start.

When GTID-based replication is employed, the coordinates represented by
'MASTER_LOG_FILE' and 'MASTER_LOG_POS' are not used, and global
transaction identifiers are used instead.  Thus the use of either or
both of these options together with 'MASTER_AUTO_POSITION' causes an
error.

You can see whether replication is running with autopositioning enabled
by checking the output of 'SHOW SLAVE STATUS'.
(Bug #15992220)

'gtid_mode' must also be enabled before issuing 'CHANGE MASTER TO ...
MASTER_AUTO_POSITION = 1'.  Otherwise, the statement fails with an
error.

To revert to the older file-based replication protocol after using
GTIDs, you can issue a new 'CHANGE MASTER TO' statement that specifies
'MASTER_AUTO_POSITION = 0', as well as at least one of 'MASTER_LOG_FILE'
or 'MASTER_LOG_POS'.

Prior to MySQL 5.7.4, 'CHANGE MASTER TO' deletes all relay log files and
starts a new one, unless you specify 'RELAY_LOG_FILE' or
'RELAY_LOG_POS'.  In that case, relay log files are kept; the
'relay_log_purge' global variable is set silently to 0.  In MySQL 5.7.4
and later, relay logs are preserved if at least one of the slave SQL
thread and the slave I/O thread is running; if both threads are stopped,
all relay log files are deleted unless at least one of 'RELAY_LOG_FILE'
or 'RELAY_LOG_POS' is specified.

'RELAY_LOG_FILE' can use either an absolute or relative path, and uses
the same base name as 'MASTER_LOG_FILE'.  (Bug #12190)

'IGNORE_SERVER_IDS' takes a comma-separated list of 0 or more server
IDs.  Events originating from the corresponding servers are ignored,
with the exception of log rotation and deletion events, which are still
recorded in the relay log.

In circular replication, the originating server normally acts as the
terminator of its own events, so that they are not applied more than
once.  Thus, this option is useful in circular replication when one of
the servers in the circle is removed.  Suppose that you have a circular
replication setup with 4 servers, having server IDs 1, 2, 3, and 4, and
server 3 fails.  When bridging the gap by starting replication from
server 2 to server 4, you can include 'IGNORE_SERVER_IDS = (3)' in the
'CHANGE MASTER TO' statement that you issue on
server 4 to tell it to use server 2 as its master instead of server 3.
Doing so causes it to ignore and not to propagate any statements that
originated with the server that is no longer in use.

If a 'CHANGE MASTER TO' statement is issued
without any 'IGNORE_SERVER_IDS' option, any existing list is preserved.
To clear the list of ignored servers, it is necessary to use the option
with an empty list:

     CHANGE MASTER TO IGNORE_SERVER_IDS = ();

Prior to MySQL 5.7.5, see 'RESET SLAVE ALL' has no
effect on the server ID list.  In MySQL 5.7.5 and later, 'RESET SLAVE
ALL' clears 'IGNORE_SERVER_IDS'.  (Bug #18816897)

If 'IGNORE_SERVER_IDS' contains the server's own ID and the server was
started with the '--replicate-same-server-id' option enabled, an error
results.

The master info repository and the output of 'SHOW SLAVE STATUS'
provide the list of servers that are currently
ignored.  For more information, see slave-logs-status, and
show-slave-status.

Invoking 'CHANGE MASTER TO' causes the previous
values for 'MASTER_HOST', 'MASTER_PORT', 'MASTER_LOG_FILE', and
'MASTER_LOG_POS' to be written to the error log, along with other
information about the slave's state prior to execution.

'CHANGE MASTER TO' causes an implicit commit of an ongoing transaction.
See implicit-commit.

In MySQL 5.7.4 and later, the strict requirement to execute 'STOP SLAVE'
prior to issuing any 'CHANGE MASTER TO'
statement (and 'START SLAVE'.
afterward) is removed.  Instead of depending on whether the slave is
stopped, the behavior of 'CHANGE MASTER TO' depends (in MySQL 5.7.4 and
later) on the states of the slave SQL thread and slave I/O threads;
which of these threads is stopped or running now determines the options
that can or cannot be used with a 'CHANGE MASTER TO' statement at a
given point in time.  The rules for making this determination are listed
here:

   * If the SQL thread is stopped, you can execute 'CHANGE MASTER TO'
     using any combination that is otherwise allowed of
     'RELAY_LOG_FILE', 'RELAY_LOG_POS', and 'MASTER_DELAY' options, even
     if the slave I/O thread is running.  No other options may be used
     with this statement when the I/O thread is running.

   * If the I/O thread is stopped, you can execute 'CHANGE MASTER TO'
     using any of the options for this statement (in any allowed
     combination) _except_ 'RELAY_LOG_FILE', 'RELAY_LOG_POS', or
     'MASTER_DELAY', even when the SQL thread is running.  These three
     options may not be used when the I/O thread is running.

   * Both the SQL thread and the I/O thread must be stopped before
     issuing a 'CHANGE MASTER TO' statement that employs
     'MASTER_AUTO_POSITION = 1'.

You can check the current state of the slave SQL and I/O threads using
'SHOW SLAVE STATUS'.

For more information, see replication-solutions-switch.

If you are using statement-based replication and temporary tables, it is
possible for a 'CHANGE MASTER TO' statement following a 'STOP SLAVE'
statement to leave behind temporary tables on the slave.  From MySQL
5.7, a warning ('ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO') is issued
whenever this occurs.  You can avoid this in such cases by making sure
that the value of the 'Slave_open_temp_tables' system status variable is
equal to 0 prior to executing such a 'CHANGE MASTER TO' statement.

'CHANGE MASTER TO' is useful for setting up a
slave when you have the snapshot of the master and have recorded the
master binary log coordinates corresponding to the time of the snapshot.
After loading the snapshot into the slave to synchronize it with the
master, you can run 'CHANGE MASTER TO MASTER_LOG_FILE='LOG_NAME',
MASTER_LOG_POS=LOG_POS' on the slave to specify the coordinates at which
the slave should begin reading the master binary log.

The following example changes the master server the slave uses and
establishes the master binary log coordinates from which the slave
begins reading.  This is used when you want to set up the slave to
replicate the master:

     CHANGE MASTER TO
       MASTER_HOST='master2.example.com',
       MASTER_USER='replication',
       MASTER_PASSWORD='PASSWORD',
       MASTER_PORT=3306,
       MASTER_LOG_FILE='master2-bin.001',
       MASTER_LOG_POS=4,
       MASTER_CONNECT_RETRY=10;

The next example shows an operation that is less frequently employed.
It is used when the slave has relay log files that you want it to
execute again for some reason.  To do this, the master need not be
reachable.  You need only use 'CHANGE MASTER TO'
and start the SQL thread ('START SLAVE SQL_THREAD'):

     CHANGE MASTER TO
       RELAY_LOG_FILE='slave-relay-bin.006',
       RELAY_LOG_POS=4025;

You can even use the second operation in a nonreplication setup with a
standalone, nonslave server for recovery following a crash.  Suppose
that your server has crashed and you have restored it from a backup.
You want to replay the server's own binary log files (not relay log
files, but regular binary log files), named (for example)
'myhost-bin.*'.  First, make a backup copy of these binary log files in
some safe place, in case you don't exactly follow the procedure below
and accidentally have the server purge the binary log.  Use 'SET GLOBAL
relay_log_purge=0' for additional safety.  Then start the server without
the '--log-bin' option, Instead, use the '--replicate-same-server-id',
'--relay-log=myhost-bin' (to make the server believe that these regular
binary log files are relay log files) and '--skip-slave-start' options.
After the server starts, issue these statements:

     CHANGE MASTER TO
       RELAY_LOG_FILE='myhost-bin.153',
       RELAY_LOG_POS=410,
       MASTER_HOST='some_dummy_string';
     START SLAVE SQL_THREAD;

The server reads and executes its own binary log files, thus achieving
crash recovery.  Once the recovery is finished, run 'STOP SLAVE',
shut down the server, clear the master info and relay log
info repositories, and restart the server with its original options.

Specifying the 'MASTER_HOST' option (even with a dummy value) is
required to make the server think it is a slave.

The following table shows the maximum permissible length for the
string-valued options.

Option         Maximum
               Length

'MASTER_HOST'  60

'MASTER_USER'  16

'MASTER_PASSWORD'32

'MASTER_LOG_FILE'255

'RELAY_LOG_FILE'255

'MASTER_SSL_CA'255

'MASTER_SSL_CAPATH'255

'MASTER_SSL_CERT'255

'MASTER_SSL_CRL'255

'MASTER_SSL_CRLPATH'255

'MASTER_SSL_KEY'255

'MASTER_SSL_CIPHER'511

13.4.2.2 CHANGE REPLICATION FILTER Syntax
.........................................

     CHANGE REPLICATION FILTER FILTER[, FILTER][, ...]

     FILTER:
         REPLICATE_DO_DB = (DB_LIST)
       | REPLICATE_IGNORE_DB = (DB_LIST)
       | REPLICATE_DO_TABLE = (TBL_LIST)
       | REPLICATE_IGNORE_TABLE = (TBL_LIST)
       | REPLICATE_WILD_DO_TABLE = (WILD_TBL_LIST)
       | REPLICATE_WILD_IGNORE_TABLE = (WILD_TBL_LIST)
       | REPLICATE_REWRITE_DB = (DB_PAIR_LIST)

     DB_LIST:
         DB_NAME[, DB_NAME][, ...]

     TBL_LIST:
         DB_NAME.TABLE_NAME[, DB_TABLE_NAME][, ...]
     WILD_TBL_LIST:
         'DB_PATTERN.TABLE_PATTERN'[, 'DB_PATTERN.TABLE_PATTERN'][, ...]

     DB_PAIR_LIST:
         (DB_PAIR)[, (DB_PAIR)][, ...]

     DB_PAIR:
         FROM_DB, TO_DB

'CHANGE REPLICATION FILTER' sets one or more replication filtering rules
on the slave in the same way as starting the slave 'mysqld'
with replication filtering options such as '--replicate-do-db'
or '--replicate-wild-ignore-table'.  Unlike the case with the server
options, this statement does not require restarting the server to take
effect, only that the slave SQL thread be stopped using 'STOP SLAVE SQL_THREAD'
first (and restarted with 'START SLAVE SQL_THREAD'
afterwards).  'CHANGE REPLICATION FILTER'
requires the 'SUPER' privilege.

The following list shows the 'CHANGE REPLICATION FILTER' options and how
they relate to '--replicate-*' server options:

   * 'REPLICATE_DO_DB': Include updates based on database name.
     Equivalent to '--replicate-do-db'.

   * 'REPLICATE_IGNORE_DB': Exclude updates based on database name.
     Equivalent to '--replicate-ignore-db'.

   * 'REPLICATE_DO_TABLE': Include updates based on table name.
     Equivalent to '--replicate-do-table'.

   * 'REPLICATE_IGNORE_TABLE': Exclude updates based on table name.
     Equivalent to '--replicate-ignore-table'.

   * 'REPLICATE_WILD_DO_TABLE': Include updates based on wildcard
     pattern matching table name.  Equivalent to
     '--replicate-wild-do-table'.

   * 'REPLICATE_WILD_IGNORE_TABLE': Exclude updates based on wildcard
     pattern matching table name.  Equivalent to
     '--replicate-wild-ignore-table'.

   * 'REPLICATE_REWRITE_DB': Perform updates on slave after substituting
     new name on slave for specified database on master.  Equivalent to
     '--replicate-rewrite-db'.

The precise effects of 'REPLICATE_DO_DB' and 'REPLICATE_IGNORE_DB'
filters are dependent on whether statement-based or row-based
replication is in effect.  See replication-rules, for more
information.

Multiple replication filtering rules can be created in a single 'CHANGE
REPLICATION FILTER' statement by separating the rules with commas, as
shown here:

     CHANGE REPLICATION FILTER
         REPLICATE_DO_DB = (d1), REPLICATE_IGNORE_DB = (d2);

Issuing the statement just shown is equivalent to starting the slave
'mysqld' with the options '--replicate-do-db=d1'
'--replicate-ignore-db=d2'.

If the same filtering rule is specified multiple times, only the _last_
such rule is actually used.  For example, the two statements shown here
have exactly the same effect, because the first 'REPLICATE_DO_DB' rule
in the first statement is ignored:

     CHANGE REPLICATION FILTER
         REPLICATE_DO_DB = (db1, db2), REPLICATE_DO_DB = (db3, db4);

     CHANGE REPLICATION FILTER
         REPLICATE_DO_DB = (db3,db4);

*Caution*:

This behavior differs from that of the '--replicate-*' filter options
where specifying the same option multiple times causes the creation of
multiple filter rules.

Names of tables and database not containing any special characters need
not be quoted.  Values used with 'REPLICATION_WILD_TABLE' and
'REPLICATION_WILD_IGNORE_TABLE' are string expressions, possibly
containing (special) wildcard characters, and so must be quoted.  This
is shown in the following example statements:

     CHANGE REPLICATION FILTER
         REPLICATE_WILD_DO_TABLE = ('db1.old%');

     CHANGE REPLICATION FILTER
         REPLICATE_WILD_IGNORE_TABLE = ('db1.new%', 'db2.new%');

Values used with 'REPLICATE_REWRITE_DB' represent _pairs_ of database
names; each such value must be enclosed in parentheses.  The following
statement rewrites statements occurring on database 'db1' on the master
to database 'db2' on the slave:

     CHANGE REPLICATION FILTER REPLICATE_REWRITE_DB = ((db1, db2));

The statement just shown contains two sets of parentheses, one enclosing
the pair of database names, and the other enclosing the entire list.
This is perhap more easily seen in the following example, which creates
two 'rewrite-db' rules, one rewriting database 'dbA' to 'dbB', and one
rewriting database 'dbC' to 'dbD':

     CHANGE REPLICATION FILTER
       REPLICATE_REWRITE_DB = ((dbA, dbB), (dbC, dbD));

This statement leaves any existing replication filtering rules
unchanged; to unset all filters of a given type, set the filter's value
to an explicitly empty list, as shown in this example, which removes all
existing 'REPLICATE_DO_DB' and 'REPLICATE_IGNORE_DB' rules:

     CHANGE REPLICATION FILTER
         REPLICATE_DO_DB = (), REPLICATE_IGNORE_DB = ();

Setting a filter to empty in this way removes all existing rules, does
not create any new ones, and does not restore any rules set at mysqld
startup using '--replicate-*' options on the command line or in the
configuration file.

Values employed with 'REPLICATE_WILD_DO_TABLE' and
'REPLICATE_WILD_IGNORE_TABLE' must be in the format 'DB_NAME.TBL_NAME'.
Prior to MySQL 5.7.5, this was not strictly enforced, although using
nonconforming values with these options could lead to erroneous results
(Bug #18095449).

For more information, see replication-rules.

13.4.2.3 MASTER_POS_WAIT() Syntax
.................................

     SELECT MASTER_POS_WAIT('MASTER_LOG_FILE', MASTER_LOG_POS [, TIMEOUT][, CHANNEL])

This is actually a function, not a statement.  It is used to ensure that
the slave has read and executed events up to a given position in the
master's binary log.  See miscellaneous-functions, for a full
description.

13.4.2.4 RESET SLAVE Syntax
...........................

     RESET SLAVE [ALL] [CHANNEL_OPTION]

     CHANNEL_OPTION:
         FOR CHANNEL CHANNEL

'RESET SLAVE' makes the slave forget its replication
position in the master's binary log.  This statement is meant to be used
for a clean start: It clears the master info and relay log info
repositories, deletes all the relay log files, and starts a new relay
log file.  It also resets to 0 the replication delay specified with the
'MASTER_DELAY' option to 'CHANGE MASTER TO'.  'RESET SLAVE'
does not change the values of 'gtid_executed' or
'gtid_purged'.  To use 'RESET SLAVE', the slave
replication threads must be stopped, so on a running slave use
'STOP SLAVE' before issuing 'RESET SLAVE'.

*Note*:

All relay log files are deleted, even if they have not been completely
executed by the slave SQL thread.  (This is a condition likely to exist
on a replication slave if you have issued a 'STOP SLAVE'
statement or if the slave is highly loaded.)

The optional 'FOR CHANNEL CHANNEL' clause enables you to name which
replication channel the statement applies to.  Providing a 'FOR CHANNEL
CHANNEL' clause applies the 'RESET SLAVE' statement to a specific
replication channel.  Combining a 'FOR CHANNEL CHANNEL' clause with the
'ALL' option deletes the specified channel.  If no channel is named and
no extra channels exist, the statement applies to the default channel.
Issuing a 'RESET SLAVE ALL' statement without a 'FOR
CHANNEL CHANNEL' clause when multiple replication channels exist deletes
_all_ replication channels and recreates only the default channel.  See
replication-channels for more information.

'RESET SLAVE' does not change any replication
connection parameters such as master host, master port, master user, or
master password, which are retained in memory.  This means that
'START SLAVE' can be issued without requiring a
'CHANGE MASTER TO' statement following 'RESET SLAVE'.

Connection parameters are reset by 'RESET SLAVE ALL'.  ('RESET SLAVE'
followed by a restart of the slave 'mysqld' also does
this.)

'RESET SLAVE' causes an implicit commit of an ongoing transaction.  See
implicit-commit.

If the slave SQL thread was in the middle of replicating temporary
tables when it was stopped, and 'RESET SLAVE' is
issued, these replicated temporary tables are deleted on the slave.

Prior to MySQL 5.7.5, 'RESET SLAVE' also had the effect of resetting
both the heartbeat period ('Slave_heartbeat_period') and
'SSL_VERIFY_SERVER_CERT'.  This issue is fixed in MySQL 5.7.5 and later.
(Bug #18777899, Bug #18778485)

Prior to MySQL 5.7.5, 'RESET SLAVE ALL' did not clear the
'IGNORE_SERVER_IDS' list set by 'CHANGE MASTER TO'.
In MySQL 5.7.5 and later, the statement clears the
list.  (Bug #18816897)

*Note*:

When used on an NDB Cluster replication slave SQL node, 'RESET SLAVE'
clears the 'mysql.ndb_apply_status' table.  You should keep in mind when
using this statement that 'ndb_apply_status' uses the 'NDB'
storage engine and so is shared by all SQL nodes attached
to the slave cluster.

You can override this behavior by issuing 'SET'.
'GLOBAL @@''ndb_clear_apply_status=OFF' prior to executing 'RESET
SLAVE', which keeps the slave from purging the 'ndb_apply_status' table
in such cases.

13.4.2.5 SET GLOBAL sql_slave_skip_counter Syntax
.................................................

     SET GLOBAL sql_slave_skip_counter = N

This statement skips the next N events from the master.  This is useful
for recovering from replication stops caused by a statement.

This statement is valid only when the slave threads are not running.
Otherwise, it produces an error.

When using this statement, it is important to understand that the binary
log is actually organized as a sequence of groups known as _event
groups_.  Each event group consists of a sequence of events.

   * For transactional tables, an event group corresponds to a
     transaction.

   * For nontransactional tables, an event group corresponds to a single
     SQL statement.

*Note*:

A single transaction can contain changes to both transactional and
nontransactional tables.

When you use 'SET GLOBAL sql_slave_skip_counter'
to skip events and the result is in
the middle of a group, the slave continues to skip events until it
reaches the end of the group.  Execution then starts with the next event
group.

13.4.2.6 START SLAVE Syntax
...........................

     START SLAVE [THREAD_TYPES] [UNTIL_OPTION] [CONNECTION_OPTIONS] [CHANNEL_OPTION]

     THREAD_TYPES:
         [THREAD_TYPE [, THREAD_TYPE] ... ]

     THREAD_TYPE:
         IO_THREAD | SQL_THREAD

     UNTIL_OPTION:
         UNTIL {   {SQL_BEFORE_GTIDS | SQL_AFTER_GTIDS} = GTID_SET
               |   MASTER_LOG_FILE = 'LOG_NAME', MASTER_LOG_POS = LOG_POS
               |   RELAY_LOG_FILE = 'LOG_NAME', RELAY_LOG_POS = LOG_POS
               |   SQL_AFTER_MTS_GAPS  }

     CONNECTION_OPTIONS:
         [USER='USER_NAME'] [PASSWORD='USER_PASS'] [DEFAULT_AUTH='PLUGIN_NAME'] [PLUGIN_DIR='PLUGIN_DIR']

     CHANNEL_OPTION:
         FOR CHANNEL CHANNEL

     GTID_SET:
         UUID_SET [, UUID_SET] ...
         | ''

     UUID_SET:
         UUID:INTERVAL[:INTERVAL]...

     UUID:
         HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH

     H:
         [0-9,A-F]

     INTERVAL:
         N[-N]

         (N >= 1)

'START SLAVE' with no THREAD_TYPE options starts
both of the slave threads.  The I/O thread reads events from the master
server and stores them in the relay log.  The SQL thread reads events
from the relay log and executes them.  See 'START SLAVE'.
requires the 'SUPER' privilege.

If 'START SLAVE' succeeds in starting the slave
threads, it returns without any error.  However, even in that case, it
might be that the slave threads start and then later stop (for example,
because they do not manage to connect to the master or read its binary
log, or some other problem).  'START SLAVE' does not
warn you about this.  You must check the slave's error log for error
messages generated by the slave threads, or check that they are running
satisfactorily with 'SHOW SLAVE STATUS'.

In MySQL 5.7, 'START SLAVE' causes an implicit commit of an ongoing
transaction.  See implicit-commit.

'gtid_next' must be set to 'AUTOMATIC' before issuing this statement.

The optional 'FOR CHANNEL CHANNEL' clause enables you to name which
replication channel the statement applies to.  Providing a 'FOR CHANNEL
CHANNEL' clause applies the 'START SLAVE' statement to a specific
replication channel.  If no clause is named and no extra channels exist,
the statement applies to the default channel.  If a 'START SLAVE'
statement does not have a channel defined when using multiple channels,
this statement starts the specified threads for all channels.  This
statement is disallowed for the 'group_replication_recovery' channel.
See replication-channels for more information.

MySQL supports pluggable user-password authentication with 'START SLAVE'
with the 'USER', 'PASSWORD', 'DEFAULT_AUTH' and 'PLUGIN_DIR' options, as
described in the following list:

   * 'USER': User name.  Cannot be set to an empty or null string, or
     left unset if 'PASSWORD' is used.

   * 'PASSWORD': Password.

   * 'DEFAULT_AUTH': Name of plugin; default is MySQL native
     authentication.

   * 'PLUGIN_DIR': Location of plugin.

You cannot use the 'SQL_THREAD' option when specifying any of 'USER',
'PASSWORD', 'DEFAULT_AUTH', or 'PLUGIN_DIR', unless the 'IO_THREAD'
option is also provided.

See pluggable-authentication, for more information.

If an insecure connection is used with any these options, the server
issues the warning 'Sending passwords in plain text without SSL/TLS is
extremely insecure'.

'START SLAVE ... UNTIL' supports two additional options for use with
global transaction identifiers (GTIDs) (see replication-gtids).
Each of these takes a set of one or more global transaction identifiers
GTID_SET as an argument (see
replication-gtids-concepts-gtid-sets, for more information).

When no THREAD_TYPE is specified, 'START SLAVE UNTIL SQL_BEFORE_GTIDS'
causes the slave SQL thread to process transactions until it has reached
the _first_ transaction whose GTID is listed in the GTID_SET.  'START
SLAVE UNTIL SQL_AFTER_GTIDS' causes the slave threads to process all
transactions until the LAST transaction in the GTID_SET has been
processed by both threads.  In other words, 'START SLAVE UNTIL
SQL_BEFORE_GTIDS' causes the slave SQL thread to process all
transactions occurring before the first GTID in the GTID_SET is reached,
and 'START SLAVE UNTIL SQL_AFTER_GTIDS' causes the slave threads to
handle all transactions, including those whose GTIDs are found in
GTID_SET, until each has encountered a transaction whose GTID is not
part of the set.  'SQL_BEFORE_GTIDS' and 'SQL_AFTER_GTIDS' each support
the 'SQL_THREAD' and 'IO_THREAD' options, although using 'IO_THREAD'
with them currently has no effect.

For example, 'START SLAVE SQL_THREAD UNTIL SQL_BEFORE_GTIDS =
3E11FA47-71CA-11E1-9E33-C80AA9429562:11-56' causes the slave SQL thread
to process all transactions originating from the master whose
'server_uuid' is '3E11FA47-71CA-11E1-9E33-C80AA9429562' until it
encounters the transaction having sequence number 11; it then stops
without processing this transaction.  In other words, all transactions
up to and including the transaction with sequence number 10 are
processed.  Executing 'START SLAVE SQL_THREAD UNTIL SQL_AFTER_GTIDS =
3E11FA47-71CA-11E1-9E33-C80AA9429562:11-56', on the other hand, would
cause the slave SQL thread to obtain all transactions just mentioned
from the master, including all of the transactions having the sequence
numbers 11 through 56, and then to stop without processing any
additional transactions; that is, the transaction having sequence number
56 would be the last transaction fetched by the slave SQL thread.

Prior to MySQL 5.7.3, 'SQL_AFTER_GTIDS' did not stop the slave once the
indicated transaction was completed, but waited until another GTID event
was received (Bug #14767986).

When using a multi-threaded slave, there is a chance of gaps in the
sequence of transactions that have been executed from the relay log in
the following cases:

   * killing the coordinator thread

   * after an error occurs in the worker threads

   * 'mysqld' shuts down unexpectedly

Use the 'START SLAVE UNTIL SQL_AFTER_MTS_GAPS'.
statement to cause a multi-threaded slave's worker threads to only run
until no more gaps are found in the relay log, and then to stop.  This
statement can take an 'SQL_THREAD' option, but the effects of the
statement remain unchanged.  It has no effect on the slave I/O thread
(and cannot be used with the 'IO_THREAD' option).

Issuing 'START SLAVE' on a multi-threaded slave with
gaps in the sequence of transactions executed from the relay log
generates a warning.  In such a situation, the solution is to use
'START SLAVE UNTIL SQL_AFTER_MTS_GAPS', then issue
'RESET SLAVE' to remove any remaining relay logs.  See
replication-features-transaction-inconsistencies for more
information.

To change a failed multi-threaded slave to single-threaded mode, you can
issue the following series of statements, in the order shown:

     START SLAVE UNTIL SQL_AFTER_MTS_GAPS;

     SET @@GLOBAL.slave_parallel_workers = 0;

     START SLAVE SQL_THREAD;

*Note*:

It is possible to view the entire text of a running 'START SLAVE ...'
statement, including any 'USER' or 'PASSWORD' values used, in the output
of 'SHOW PROCESSLIST'.  This is also true for
the text of a running 'CHANGE MASTER TO'.
statement, including any values it employs for 'MASTER_USER' or
'MASTER_PASSWORD'.

'START SLAVE' sends an acknowledgment to the user
after both the I/O thread and the SQL thread have started.  However, the
I/O thread may not yet have connected.  For this reason, a successful
'START SLAVE' causes 'SHOW SLAVE STATUS'
to show 'Slave_SQL_Running=Yes', but this does not
guarantee that 'Slave_IO_Running=Yes' (because 'Slave_IO_Running=Yes'
only if the I/O thread is running _and connected_).  For more
information, see show-slave-status, and
replication-administration-status.

You can add 'IO_THREAD' and 'SQL_THREAD' options to the statement to
name which of the threads to start.  The 'SQL_THREAD' option is
disallowed when specifying any of 'USER', 'PASSWORD', 'DEFAULT_AUTH', or
'PLUGIN_DIR', unless the 'IO_THREAD' option is also provided.

An 'UNTIL' clause (UNTIL_OPTION, in the preceding grammar) may be added
to specify that the slave should start and run until the SQL thread
reaches a given point in the master binary log, specified by the
'MASTER_LOG_POS' and MASTER_LOG_FILE options, or a given point in the
slave relay log, indicated with the 'RELAY_LOG_POS' and 'RELAY_LOG_FILE'
options.  When the SQL thread reaches the point specified, it stops.  If
the 'SQL_THREAD' option is specified in the statement, it starts only
the SQL thread.  Otherwise, it starts both slave threads.  If the SQL
thread is running, the 'UNTIL' clause is ignored and a warning is
issued.  You cannot use an 'UNTIL' clause with the 'IO_THREAD' option.

It is also possible with 'START SLAVE UNTIL' to specify a stop point
relative to a given GTID or set of GTIDs using one of the options
'SQL_BEFORE_GTIDS' or 'SQL_AFTER_GTIDS', as explained previously in this
section.  When using one of these options, you can specify 'SQL_THREAD',
'IO_THREAD', both of these, or neither of them.  If you specify only
'SQL_THREAD', then only the slave SQL thread is affected by the
statement; if only 'IO_THREAD' is used, then only the slave I/O is
affected.  If both 'SQL_THREAD' and 'IO_THREAD' are used, or if neither
of them is used, then both the SQL and I/O threads are affected by the
statement.

The 'UNTIL' clause is not supported for multi-threaded slaves except
when also using 'SQL_AFTER_MTS_GAPS'.

For an 'UNTIL' clause, you must specify any one of the following:

   * _Both_ a log file name and a position in that file

   * _Either_ of 'SQL_BEFORE_GTIDS' or 'SQL_AFTER_GTIDS'

   * 'SQL_AFTER_MTS_GAPS'

Do not mix master and relay log options.  Do not mix log file options
with GTID options.

Any 'UNTIL' condition is reset by a subsequent 'STOP SLAVE'
statement, a 'START SLAVE' statement
that includes no 'UNTIL' clause, or a server restart.

When specifying a log file and position, you can use the 'IO_THREAD'
option with 'START SLAVE ... UNTIL' even though only the SQL thread is
affected by this statement.  The 'IO_THREAD' option is ignored in such
cases.  The preceding restriction does not apply when using one of the
GTID options ('SQL_BEFORE_GTIDS' and 'SQL_AFTER_GTIDS'); the GTID
options support both 'SQL_THREAD' and 'IO_THREAD', as explained
previously in this section.

The 'UNTIL' clause can be useful for debugging replication, or to cause
replication to proceed until just before the point where you want to
avoid having the slave replicate an event.  For example, if an unwise
'DROP TABLE' statement was executed on the master,
you can use 'UNTIL' to tell the slave to execute up to that point but no
farther.  To find what the event is, use 'mysqlbinlog'
with the master binary log or slave relay log, or by using
a 'SHOW BINLOG EVENTS' statement.

If you are using 'UNTIL' to have the slave process replicated queries in
sections, it is recommended that you start the slave with the
'--skip-slave-start' option to prevent the SQL thread from running when
the slave server starts.  It is probably best to use this option in an
option file rather than on the command line, so that an unexpected
server restart does not cause it to be forgotten.

The 'SHOW SLAVE STATUS' statement includes
output fields that display the current values of the 'UNTIL' condition.

Prior to MySQL 5.7.5, the failure of this statement caused the slave
heartbeat period to be reset.  This issue is fixed in MySQL 5.7.5 and
later.  (Bug #18791604)

In very old versions of MySQL (before 4.0.5), this statement was called
'SLAVE START'.  That syntax now produces an error.

13.4.2.7 STOP SLAVE Syntax
..........................

     STOP SLAVE [THREAD_TYPES]

     THREAD_TYPES:
         [THREAD_TYPE [, THREAD_TYPE] ... ]

     THREAD_TYPE: IO_THREAD | SQL_THREAD

     CHANNEL_OPTION:
         FOR CHANNEL CHANNEL

Stops the slave threads.  'STOP SLAVE' requires the
'SUPER' privilege.  Recommended best practice is to execute 'STOP SLAVE'
on the slave before stopping the slave server (see
server-shutdown, for more information).

_When using the row-based logging format_: You should execute 'STOP
SLAVE' or 'STOP SLAVE SQL_THREAD' on the slave prior to shutting down
the slave server if you are replicating any tables that use a
nontransactional storage engine (see the 'Note' later in this section).

Like 'START SLAVE', this statement may be used with
the 'IO_THREAD' and 'SQL_THREAD' options to name the thread or threads
to be stopped.

'STOP SLAVE' causes an implicit commit of an ongoing transaction.  See
implicit-commit.

From MySQL 5.7, 'gtid_next' must be set to 'AUTOMATIC' before issuing
this statement (Bug #16062608).

From MySQL 5.7, you can control how long 'STOP SLAVE' waits before
timing out by setting the 'rpl_stop_slave_timeout' system variable.
This can be used to avoid deadlocks between 'STOP SLAVE' and other slave
SQL statements using different client connections to the slave.  When
the timeout value is reached, the issuing client returns an error
message and stops waiting, but the 'STOP SLAVE' instruction remains in
effect.  Once the slave threads are no longer busy, the 'STOP SLAVE'
statement is executed and the slave stops.  (Bug #16856735)

Some 'CHANGE MASTER TO' statements are allowed while the slave is
running, depending on the states of the slave SQL and I/O threads.
However, using 'STOP SLAVE' prior to executing 'CHANGE MASTER TO' in
such cases is still supported.  See change-master-to, and
replication-solutions-switch, for more information.

The optional 'FOR CHANNEL CHANNEL' clause enables you to name which
replication channel the statement applies to.  Providing a 'FOR CHANNEL
CHANNEL' clause applies the 'STOP SLAVE' statement to a specific
replication channel.  If no channel is named and no extra channels
exist, the statement applies to the default channel.  If a 'STOP SLAVE'
statement does not name a channel when using multiple channels, this
statement stops the specified threads for all channels.  This statement
cannot be used with the 'group_replication_recovery' channel.  See
replication-channels for more information.

_When using statement-based replication_: changing the master while it
has open temporary tables is potentially unsafe.  This is one of the
reasons why statement-based replication of temporary tables is not
recommended.  You can find out whether there are any temporary tables on
the slave by checking the value of 'Slave_open_temp_tables'; when using
statement-based replication, this value should be 0 before executing
'CHANGE MASTER TO'.  If there are any temporary tables open on the
slave, issuing a 'CHANGE MASTER TO' statement after issuing a 'STOP
SLAVE' causes an 'ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO' warning.

When using a multi-threaded slave ('slave_parallel_workers' is a nonzero
value), any gaps in the sequence of transactions executed from the relay
log are closed as part of stopping the worker threads.  If the slave is
stopped unexpectedly (for example due to an error in a worker thread, or
another thread issuing 'KILL') while a 'STOP SLAVE'
statement is executing, the sequence of executed
transactions from the relay log may become inconsistent.  See
replication-features-transaction-inconsistencies, for more
information.

If the current replication event group has modified one or more
nontransactional tables, STOP SLAVE waits for up to 60 seconds for the
event group to complete, unless you issue a 'KILL QUERY' or
'KILL CONNECTION' statement for the slave SQL thread.  If
the event group remains incomplete after the timeout, an error message
is logged.

13.4.3 SQL Statements for Controlling Group Replication
-------------------------------------------------------

This section provides information about the statements used to control
servers running the MySQL Group Replication plugin.  See
group-replication for more information.

13.4.3.1 START GROUP_REPLICATION Syntax
.......................................

     START GROUP_REPLICATION

Starts Group Replication on this server instance.  This statement
requires the 'SUPER' privilege.  If 'super_read_only=ON' and the member
should join as a primary, 'super_read_only' is set to 'OFF' once Group
Replication successfully starts.

13.4.3.2 STOP GROUP_REPLICATION Syntax
......................................

     STOP GROUP_REPLICATION

Stops group replication.  This statement requires the 'SUPER' privilege.
As soon as you issue 'STOP GROUP_REPLICATION'
the member is set to 'super_read_only=ON', which
ensures that no writes can be made to the member while Group Replication
stops.

*Warning*:

Use this statement with extreme caution because it removes the server
instance from the group, meaning it is no longer protected by Group
Replication's consistency guarantee mechanisms.  To be completely safe,
ensure that your applications can no longer connect to the instance
before issuing this statement to avoid any chance of stale reads.

13.5 Prepared SQL Statement Syntax
==================================

MySQL 5.7 provides support for server-side prepared statements.  This
support takes advantage of the efficient client/server binary protocol.
Using prepared statements with placeholders for parameter values has the
following benefits:

   * Less overhead for parsing the statement each time it is executed.
     Typically, database applications process large volumes of
     almost-identical statements, with only changes to literal or
     variable values in clauses such as 'WHERE' for queries and deletes,
     'SET' for updates, and 'VALUES' for inserts.

   * Protection against SQL injection attacks.  The parameter values can
     contain unescaped SQL quote and delimiter characters.

*Prepared Statements in Application Programs*

You can use server-side prepared statements through client programming
interfaces, including the MySQL C API client library or
MySQL Connector/C (http://dev.mysql.com/doc/connector-c/en/) for C
programs, MySQL Connector/J
(http://dev.mysql.com/doc/connector-j/5.1/en/) for Java programs, and
MySQL Connector/Net (http://dev.mysql.com/doc/connector-net/en/) for
programs using .NET technologies.  For example, the C API provides a set
of function calls that make up its prepared statement API. See
c-api-prepared-statements.  Other language interfaces can provide
support for prepared statements that use the binary protocol by linking
in the C client library, one example being the 'mysqli' extension
(http://php.net/mysqli), available in PHP 5.0 and later.

*Prepared Statements in SQL Scripts*

An alternative SQL interface to prepared statements is available.  This
interface is not as efficient as using the binary protocol through a
prepared statement API, but requires no programming because it is
available directly at the SQL level:

   * You can use it when no programming interface is available to you.

   * You can use it from any program that can send SQL statements to the
     server to be executed, such as the 'mysql' client
     program.

   * You can use it even if the client is using an old version of the
     client library, as long as you connect to a server running MySQL
     4.1 or higher.

SQL syntax for prepared statements is intended to be used for situations
such as these:

   * To test how prepared statements work in your application before
     coding it.

   * To use prepared statements when you do not have access to a
     programming API that supports them.

   * To interactively troubleshoot application issues with prepared
     statements.

   * To create a test case that reproduces a problem with prepared
     statements, so that you can file a bug report.

*PREPARE, EXECUTE, and DEALLOCATE PREPARE Statements*

SQL syntax for prepared statements is based on three SQL statements:

   * 'PREPARE' prepares a statement for execution (see
     prepare).

   * 'EXECUTE' executes a prepared statement (see
     execute).

   * 'DEALLOCATE PREPARE' releases a prepared
     statement (see deallocate-prepare).

The following examples show two equivalent ways of preparing a statement
that computes the hypotenuse of a triangle given the lengths of the two
sides.

The first example shows how to create a prepared statement by using a
string literal to supply the text of the statement:

     mysql> PREPARE stmt1 FROM 'SELECT SQRT(POW(?,2) + POW(?,2)) AS hypotenuse';
     mysql> SET @a = 3;
     mysql> SET @b = 4;
     mysql> EXECUTE stmt1 USING @a, @b;
     +------------+
     | hypotenuse |
     +------------+
     |          5 |
     +------------+
     mysql> DEALLOCATE PREPARE stmt1;

The second example is similar, but supplies the text of the statement as
a user variable:

     mysql> SET @s = 'SELECT SQRT(POW(?,2) + POW(?,2)) AS hypotenuse';
     mysql> PREPARE stmt2 FROM @s;
     mysql> SET @a = 6;
     mysql> SET @b = 8;
     mysql> EXECUTE stmt2 USING @a, @b;
     +------------+
     | hypotenuse |
     +------------+
     |         10 |
     +------------+
     mysql> DEALLOCATE PREPARE stmt2;

Here is an additional example that demonstrates how to choose the table
on which to perform a query at runtime, by storing the name of the table
as a user variable:

     mysql> USE test;
     mysql> CREATE TABLE t1 (a INT NOT NULL);
     mysql> INSERT INTO t1 VALUES (4), (8), (11), (32), (80);

     mysql> SET @table = 't1';
     mysql> SET @s = CONCAT('SELECT * FROM ', @table);

     mysql> PREPARE stmt3 FROM @s;
     mysql> EXECUTE stmt3;
     +----+
     | a  |
     +----+
     |  4 |
     |  8 |
     | 11 |
     | 32 |
     | 80 |
     +----+

     mysql> DEALLOCATE PREPARE stmt3;

A prepared statement is specific to the session in which it was created.
If you terminate a session without deallocating a previously prepared
statement, the server deallocates it automatically.

A prepared statement is also global to the session.  If you create a
prepared statement within a stored routine, it is not deallocated when
the stored routine ends.

To guard against too many prepared statements being created
simultaneously, set the 'max_prepared_stmt_count' system variable.  To
prevent the use of prepared statements, set the value to 0.

*SQL Syntax Allowed in Prepared Statements*

The following SQL statements can be used as prepared statements:

     ALTER TABLE
     ALTER USER
     ANALYZE TABLE
     CACHE INDEX
     CALL
     CHANGE MASTER
     CHECKSUM {TABLE | TABLES}
     COMMIT
     {CREATE | DROP} INDEX
     {CREATE | RENAME | DROP} DATABASE
     {CREATE | DROP} TABLE
     {CREATE | RENAME | DROP} USER
     {CREATE | DROP} VIEW
     DELETE
     DO
     FLUSH {TABLE | TABLES | TABLES WITH READ LOCK | HOSTS | PRIVILEGES
       | LOGS | STATUS | MASTER | SLAVE | DES_KEY_FILE | USER_RESOURCES}
     GRANT
     INSERT
     INSTALL PLUGIN
     KILL
     LOAD INDEX INTO CACHE
     OPTIMIZE TABLE
     RENAME TABLE
     REPAIR TABLE
     REPLACE
     RESET {MASTER | SLAVE | QUERY CACHE}
     REVOKE
     SELECT
     SET
     SHOW {WARNINGS | ERRORS}
     SHOW BINLOG EVENTS
     SHOW CREATE {PROCEDURE | FUNCTION | EVENT | TABLE | VIEW}
     SHOW {MASTER | BINARY} LOGS
     SHOW {MASTER | SLAVE} STATUS
     SLAVE {START | STOP}
     TRUNCATE TABLE
     UNINSTALL PLUGIN
     UPDATE

As of MySQL 5.7.2, for compliance with the SQL standard, which states
that diagnostics statements are not preparable, MySQL does not support
the following as prepared statements:

   * 'SHOW WARNINGS', 'SHOW COUNT(*) WARNINGS'

   * 'SHOW ERRORS', 'SHOW COUNT(*) ERRORS'

   * Statements containing any reference to the 'warning_count' or
     'error_count' system variable.

Other statements are not supported in MySQL 5.7.

Generally, statements not permitted in SQL prepared statements are also
not permitted in stored programs.  Exceptions are noted in
stored-program-restrictions.

Metadata changes to tables or views referred to by prepared statements
are detected and cause automatic repreparation of the statement when it
is next executed.  For more information, see statement-caching.

Placeholders can be used for the arguments of the 'LIMIT' clause when
using prepared statements.  See select.

In prepared 'CALL' statements used with 'PREPARE'
and 'EXECUTE', placeholder support for 'OUT' and
'INOUT' parameters is available beginning with MySQL 5.7.  See
call, for an example and a workaround for earlier versions.
Placeholders can be used for 'IN' parameters regardless of version.

SQL syntax for prepared statements cannot be used in nested fashion.
That is, a statement passed to 'PREPARE' cannot itself
be a 'PREPARE', 'EXECUTE', or
'DEALLOCATE PREPARE' statement.

SQL syntax for prepared statements is distinct from using prepared
statement API calls.  For example, you cannot use the
'mysql_stmt_prepare()'. C API function to prepare a
'PREPARE', 'EXECUTE', or 'DEALLOCATE PREPARE'
statement.

SQL syntax for prepared statements can be used within stored procedures,
but not in stored functions or triggers.  However, a cursor cannot be
used for a dynamic statement that is prepared and executed with
'PREPARE' and 'EXECUTE'.  The statement for a
cursor is checked at cursor creation time, so the statement cannot be
dynamic.

SQL syntax for prepared statements does not support multi-statements
(that is, multiple statements within a single string separated by ';'
characters).

Prepared statements use the query cache under the conditions described
in query-cache-operation.

To write C programs that use the 'CALL'. SQL statement to
execute stored procedures that contain prepared statements, the
'CLIENT_MULTI_RESULTS' flag must be enabled.  This is because each
'CALL' returns a result to indicate the call status, in addition
to any result sets that might be returned by statements executed within
the procedure.

'CLIENT_MULTI_RESULTS' can be enabled when you call
'mysql_real_connect()', either explicitly by passing
the 'CLIENT_MULTI_RESULTS' flag itself, or implicitly by passing
'CLIENT_MULTI_STATEMENTS' (which also enables 'CLIENT_MULTI_RESULTS').
For additional information, see call.

13.5.1 PREPARE Syntax
---------------------

     PREPARE STMT_NAME FROM PREPARABLE_STMT

The 'PREPARE' statement prepares a SQL statement and
assigns it a name, STMT_NAME, by which to refer to the statement later.
The prepared statement is executed with 'EXECUTE' and
released with 'DEALLOCATE PREPARE'.  For
examples, see sql-syntax-prepared-statements.

Statement names are not case-sensitive.  PREPARABLE_STMT is either a
string literal or a user variable that contains the text of the SQL
statement.  The text must represent a single statement, not multiple
statements.  Within the statement, '?' characters can be used as
parameter markers to indicate where data values are to be bound to the
query later when you execute it.  The '?' characters should not be
enclosed within quotation marks, even if you intend to bind them to
string values.  Parameter markers can be used only where data values
should appear, not for SQL keywords, identifiers, and so forth.

If a prepared statement with the given name already exists, it is
deallocated implicitly before the new statement is prepared.  This means
that if the new statement contains an error and cannot be prepared, an
error is returned and no statement with the given name exists.

The scope of a prepared statement is the session within which it is
created, which as several implications:

   * A prepared statement created in one session is not available to
     other sessions.

   * When a session ends, whether normally or abnormally, its prepared
     statements no longer exist.  If auto-reconnect is enabled, the
     client is not notified that the connection was lost.  For this
     reason, clients may wish to disable auto-reconnect.  See
     c-api-auto-reconnect.

   * A prepared statement created within a stored program continues to
     exist after the program finishes executing and can be executed
     outside the program later.

   * A statement prepared in stored program context cannot refer to
     stored procedure or function parameters or local variables because
     they go out of scope when the program ends and would be unavailable
     were the statement to be executed later outside the program.  As a
     workaround, refer instead to user-defined variables, which also
     have session scope; see user-variables.

13.5.2 EXECUTE Syntax
---------------------

     EXECUTE STMT_NAME
         [USING @VAR_NAME [, @VAR_NAME] ...]

After preparing a statement with 'PREPARE', you execute
it with an 'EXECUTE' statement that refers to the
prepared statement name.  If the prepared statement contains any
parameter markers, you must supply a 'USING' clause that lists user
variables containing the values to be bound to the parameters.
Parameter values can be supplied only by user variables, and the 'USING'
clause must name exactly as many variables as the number of parameter
markers in the statement.

You can execute a given prepared statement multiple times, passing
different variables to it or setting the variables to different values
before each execution.

For examples, see sql-syntax-prepared-statements.

13.5.3 DEALLOCATE PREPARE Syntax
--------------------------------

     {DEALLOCATE | DROP} PREPARE STMT_NAME

To deallocate a prepared statement produced with 'PREPARE',
use a 'DEALLOCATE PREPARE' statement
that refers to the prepared statement name.  Attempting to execute a
prepared statement after deallocating it results in an error.  If too
many prepared statements are created and not deallocated by either the
'DEALLOCATE PREPARE' statement or the end of the session, you might
encounter the upper limit enforced by the 'max_prepared_stmt_count'
system variable.

For examples, see sql-syntax-prepared-statements.

13.6 Compound-Statement Syntax
==============================

This section describes the syntax for the 'BEGIN ... END'
compound statement and other statements that can be used in
the body of stored programs: Stored procedures and functions, triggers,
and events.  These objects are defined in terms of SQL code that is
stored on the server for later invocation (see
stored-programs-views).

A compound statement is a block that can contain other blocks;
declarations for variables, condition handlers, and cursors; and flow
control constructs such as loops and conditional tests.

13.6.1 BEGIN ... END Compound-Statement Syntax
----------------------------------------------

     [BEGIN_LABEL:] BEGIN
         [STATEMENT_LIST]
     END [END_LABEL]

'BEGIN ... END' syntax is used for writing compound
statements, which can appear within stored programs (stored procedures
and functions, triggers, and events).  A compound statement can contain
multiple statements, enclosed by the 'BEGIN' and 'END' keywords.
STATEMENT_LIST represents a list of one or more statements, each
terminated by a semicolon (';') statement delimiter.  The STATEMENT_LIST
itself is optional, so the empty compound statement ('BEGIN END') is
legal.

'BEGIN ... END' blocks can be nested.

Use of multiple statements requires that a client is able to send
statement strings containing the ';' statement delimiter.  In the
'mysql' command-line client, this is handled with the
'delimiter' command.  Changing the ';' end-of-statement delimiter (for
example, to '//') permit ';' to be used in a program body.  For an
example, see stored-programs-defining.

A 'BEGIN ... END' block can be labeled.  See
statement-labels.

The optional '[NOT] ATOMIC' clause is not supported.  This means that no
transactional savepoint is set at the start of the instruction block and
the 'BEGIN' clause used in this context has no effect on the current
transaction.

*Note*:

Within all stored programs, the parser treats 'BEGIN [WORK]'
as the beginning of a 'BEGIN ... END' block.
To begin a transaction in this context, use 'START TRANSACTION'
instead.

13.6.2 Statement Label Syntax
-----------------------------

     [BEGIN_LABEL:] BEGIN
         [STATEMENT_LIST]
     END [END_LABEL]

     [BEGIN_LABEL:] LOOP
         STATEMENT_LIST
     END LOOP [END_LABEL]

     [BEGIN_LABEL:] REPEAT
         STATEMENT_LIST
     UNTIL SEARCH_CONDITION
     END REPEAT [END_LABEL]

     [BEGIN_LABEL:] WHILE SEARCH_CONDITION DO
         STATEMENT_LIST
     END WHILE [END_LABEL]

Labels are permitted for 'BEGIN ... END' blocks and
for the 'LOOP', 'REPEAT', and 'WHILE'
statements.  Label use for those statements follows these rules:

   * BEGIN_LABEL must be followed by a colon.

   * BEGIN_LABEL can be given without END_LABEL.  If END_LABEL is
     present, it must be the same as BEGIN_LABEL.

   * END_LABEL cannot be given without BEGIN_LABEL.

   * Labels at the same nesting level must be distinct.

   * Labels can be up to 16 characters long.

To refer to a label within the labeled construct, use an
'ITERATE' or 'LEAVE' statement.  The following
example uses those statements to continue iterating or terminate the
loop:

     CREATE PROCEDURE doiterate(p1 INT)
     BEGIN
       label1: LOOP
         SET p1 = p1 + 1;
         IF p1 < 10 THEN ITERATE label1; END IF;
         LEAVE label1;
       END LOOP label1;
     END;

The scope of a block label does not include the code for handlers
declared within the block.  For details, see declare-handler.

13.6.3 DECLARE Syntax
---------------------

The 'DECLARE' statement is used to define various items
local to a program:

   * Local variables.  See stored-program-variables.

   * Conditions and handlers.  See condition-handling.

   * Cursors.  See cursors.

'DECLARE' is permitted only inside a 'BEGIN ... END'
compound statement and must be at its start, before any
other statements.

Declarations must follow a certain order.  Cursor declarations must
appear before handler declarations.  Variable and condition declarations
must appear before cursor or handler declarations.

13.6.4 Variables in Stored Programs
-----------------------------------

System variables and user-defined variables can be used in stored
programs, just as they can be used outside stored-program context.  In
addition, stored programs can use 'DECLARE' to define local variables,
and stored routines (procedures and functions) can be declared to take
parameters that communicate values between the routine and its caller.

   * To declare local variables, use the 'DECLARE'
     statement, as described in
     declare-local-variable.

   * Variables can be set directly with the 'SET'.
     statement.  See set-variable.

   * Results from queries can be retrieved into local variables using
     'SELECT ... INTO VAR_LIST' or by opening a
     cursor and using 'FETCH ... INTO VAR_LIST'.  See
     select-into, and cursors.

For information about the scope of local variables and how MySQL
resolves ambiguous names, see local-variable-scope.

It is not permitted to assign the value 'DEFAULT' to stored procedure or
function parameters or stored program local variables (for example with
a 'SET VAR_NAME = DEFAULT' statement).  In MySQL 5.7, this results in a
syntax error.

13.6.4.1 Local Variable DECLARE Syntax
......................................

     DECLARE VAR_NAME [, VAR_NAME] ... TYPE [DEFAULT VALUE]

This statement declares local variables within stored programs.  To
provide a default value for a variable, include a 'DEFAULT' clause.  The
value can be specified as an expression; it need not be a constant.  If
the 'DEFAULT' clause is missing, the initial value is 'NULL'.

Local variables are treated like stored routine parameters with respect
to data type and overflow checking.  See create-procedure.

Variable declarations must appear before cursor or handler declarations.

Local variable names are not case-sensitive.  Permissible characters and
quoting rules are the same as for other identifiers, as described in
identifiers.

The scope of a local variable is the 'BEGIN ... END'.
block within which it is declared.  The variable can be referred to in
blocks nested within the declaring block, except those blocks that
declare a variable with the same name.

For examples of variable declarations, see local-variable-scope.

13.6.4.2 Local Variable Scope and Resolution
............................................

The scope of a local variable is the 'BEGIN ... END'.
block within which it is declared.  The variable can be referred to in
blocks nested within the declaring block, except those blocks that
declare a variable with the same name.

Because local variables are in scope only during stored program
execution, references to them are not permitted in prepared statements
created within a stored program.  Prepared statement scope is the
current session, not the stored program, so the statement could be
executed after the program ends, at which point the variables would no
longer be in scope.  For example, 'SELECT ... INTO LOCAL_VAR' cannot be
used as a prepared statement.  This restriction also applies to stored
procedure and function parameters.  See prepare.

A local variable should not have the same name as a table column.  If an
SQL statement, such as a 'SELECT ... INTO' statement,
contains a reference to a column and a declared local variable with the
same name, MySQL currently interprets the reference as the name of a
variable.  Consider the following procedure definition:

     CREATE PROCEDURE sp1 (x VARCHAR(5))
     BEGIN
       DECLARE xname VARCHAR(5) DEFAULT 'bob';
       DECLARE newname VARCHAR(5);
       DECLARE xid INT;

       SELECT xname, id INTO newname, xid
         FROM table1 WHERE xname = xname;
       SELECT newname;
     END;

MySQL interprets 'xname' in the 'SELECT' statement as a
reference to the 'xname' _variable_ rather than the 'xname' _column_.
Consequently, when the procedure 'sp1()'is called, the 'newname'
variable returns the value ''bob'' regardless of the value of the
'table1.xname' column.

Similarly, the cursor definition in the following procedure contains a
'SELECT' statement that refers to 'xname'.  MySQL
interprets this as a reference to the variable of that name rather than
a column reference.

     CREATE PROCEDURE sp2 (x VARCHAR(5))
     BEGIN
       DECLARE xname VARCHAR(5) DEFAULT 'bob';
       DECLARE newname VARCHAR(5);
       DECLARE xid INT;
       DECLARE done TINYINT DEFAULT 0;
       DECLARE cur1 CURSOR FOR SELECT xname, id FROM table1;
       DECLARE CONTINUE HANDLER FOR NOT FOUND SET done = 1;

       OPEN cur1;
       read_loop: LOOP
         FETCH FROM cur1 INTO newname, xid;
         IF done THEN LEAVE read_loop; END IF;
         SELECT newname;
       END LOOP;
       CLOSE cur1;
     END;

See also stored-program-restrictions.

13.6.5 Flow Control Statements
------------------------------

MySQL supports the 'IF', 'CASE', 'ITERATE',
see 'LEAVE'. See 'LOOP', 'WHILE',
and 'REPEAT' constructs for flow control within stored
programs.  It also supports 'RETURN' within stored
functions.

Many of these constructs contain other statements, as indicated by the
grammar specifications in the following sections.  Such constructs may
be nested.  For example, an 'IF' statement might contain a
'WHILE' loop, which itself contains a 'CASE'.
statement.

MySQL does not support 'FOR' loops.

13.6.5.1 CASE Syntax
....................

     CASE CASE_VALUE
         WHEN WHEN_VALUE THEN STATEMENT_LIST
         [WHEN WHEN_VALUE THEN STATEMENT_LIST] ...
         [ELSE STATEMENT_LIST]
     END CASE

Or:

     CASE
         WHEN SEARCH_CONDITION THEN STATEMENT_LIST
         [WHEN SEARCH_CONDITION THEN STATEMENT_LIST] ...
         [ELSE STATEMENT_LIST]
     END CASE

The 'CASE' statement for stored programs implements a
complex conditional construct.

*Note*:

There is also a 'CASE' _expression_, which differs from the
'CASE'. _statement_ described here.  See
control-flow-functions.  The 'CASE' statement cannot have
an 'ELSE NULL' clause, and it is terminated with 'END CASE' instead of
'END'.

For the first syntax, CASE_VALUE is an expression.  This value is
compared to the WHEN_VALUE expression in each 'WHEN' clause until one of
them is equal.  When an equal WHEN_VALUE is found, the corresponding
'THEN' clause STATEMENT_LIST executes.  If no WHEN_VALUE is equal, the
'ELSE' clause STATEMENT_LIST executes, if there is one.

This syntax cannot be used to test for equality with 'NULL' because
'NULL = NULL' is false.  See working-with-null.

For the second syntax, each 'WHEN' clause SEARCH_CONDITION expression is
evaluated until one is true, at which point its corresponding 'THEN'
clause STATEMENT_LIST executes.  If no SEARCH_CONDITION is equal, the
'ELSE' clause STATEMENT_LIST executes, if there is one.

If no WHEN_VALUE or SEARCH_CONDITION matches the value tested and the
'CASE' statement contains no 'ELSE' clause, a 'Case not
found for CASE statement' error results.

Each STATEMENT_LIST consists of one or more SQL statements; an empty
STATEMENT_LIST is not permitted.

To handle situations where no value is matched by any 'WHEN' clause, use
an 'ELSE' containing an empty 'BEGIN ... END' block,
as shown in this example.  (The indentation used here in the 'ELSE'
clause is for purposes of clarity only, and is not otherwise
significant.)

     DELIMITER |

     CREATE PROCEDURE p()
       BEGIN
         DECLARE v INT DEFAULT 1;

         CASE v
           WHEN 2 THEN SELECT v;
           WHEN 3 THEN SELECT 0;
           ELSE
             BEGIN
             END;
         END CASE;
       END;
       |

13.6.5.2 IF Syntax
..................

     IF SEARCH_CONDITION THEN STATEMENT_LIST
         [ELSEIF SEARCH_CONDITION THEN STATEMENT_LIST] ...
         [ELSE STATEMENT_LIST]
     END IF

The 'IF' statement for stored programs implements a basic
conditional construct.

*Note*:

There is also an 'IF()' _function_, which differs from the 'IF'.
_statement_ described here.  See control-flow-functions.
The 'IF' statement can have 'THEN', 'ELSE', and 'ELSEIF'
clauses, and it is terminated with 'END IF'.

If the SEARCH_CONDITION evaluates to true, the corresponding 'THEN' or
'ELSEIF' clause STATEMENT_LIST executes.  If no SEARCH_CONDITION
matches, the 'ELSE' clause STATEMENT_LIST executes.

Each STATEMENT_LIST consists of one or more SQL statements; an empty
STATEMENT_LIST is not permitted.

An 'IF ... END IF' block, like all other flow-control blocks used within
stored programs, must be terminated with a semicolon, as shown in this
example:

     DELIMITER //

     CREATE FUNCTION SimpleCompare(n INT, m INT)
       RETURNS VARCHAR(20)

       BEGIN
         DECLARE s VARCHAR(20);

         IF n > m THEN SET s = '>';
         ELSEIF n = m THEN SET s = '=';
         ELSE SET s = '<';
         END IF;

         SET s = CONCAT(n, ' ', s, ' ', m);

         RETURN s;
       END //

     DELIMITER ;

As with other flow-control constructs, 'IF ... END IF' blocks may be
nested within other flow-control constructs, including other 'IF'
statements.  Each 'IF' must be terminated by its own 'END
IF' followed by a semicolon.  You can use indentation to make nested
flow-control blocks more easily readable by humans (although this is not
required by MySQL), as shown here:

     DELIMITER //

     CREATE FUNCTION VerboseCompare (n INT, m INT)
       RETURNS VARCHAR(50)

       BEGIN
         DECLARE s VARCHAR(50);

         IF n = m THEN SET s = 'equals';
         ELSE
           IF n > m THEN SET s = 'greater';
           ELSE SET s = 'less';
           END IF;

           SET s = CONCAT('is ', s, ' than');
         END IF;

         SET s = CONCAT(n, ' ', s, ' ', m, '.');

         RETURN s;
       END //

     DELIMITER ;

In this example, the inner 'IF' is evaluated only if 'n' is
not equal to 'm'.

13.6.5.3 ITERATE Syntax
.......................

     ITERATE LABEL

'ITERATE' can appear only within 'LOOP',
'REPEAT', and 'WHILE' statements.
'ITERATE' means 'start the loop again.'

For an example, see loop.

13.6.5.4 LEAVE Syntax
.....................

     LEAVE LABEL

This statement is used to exit the flow control construct that has the
given label.  If the label is for the outermost stored program block,
see 'LEAVE' exits the program.

'LEAVE' can be used within 'BEGIN ... END'
or loop constructs (see 'LOOP', 'REPEAT',
see 'WHILE').

For an example, see loop.

13.6.5.5 LOOP Syntax
....................

     [BEGIN_LABEL:] LOOP
         STATEMENT_LIST
     END LOOP [END_LABEL]

'LOOP' implements a simple loop construct, enabling
repeated execution of the statement list, which consists of one or more
statements, each terminated by a semicolon (';') statement delimiter.
The statements within the loop are repeated until the loop is
terminated.  Usually, this is accomplished with a 'LEAVE'.
statement.  Within a stored function, see 'RETURN' can also
be used, which exits the function entirely.

Neglecting to include a loop-termination statement results in an
infinite loop.

A 'LOOP' statement can be labeled.  For the rules regarding
label use, see statement-labels.

Example:

     CREATE PROCEDURE doiterate(p1 INT)
     BEGIN
       label1: LOOP
         SET p1 = p1 + 1;
         IF p1 < 10 THEN
           ITERATE label1;
         END IF;
         LEAVE label1;
       END LOOP label1;
       SET @x = p1;
     END;

13.6.5.6 REPEAT Syntax
......................

     [BEGIN_LABEL:] REPEAT
         STATEMENT_LIST
     UNTIL SEARCH_CONDITION
     END REPEAT [END_LABEL]

The statement list within a 'REPEAT' statement is
repeated until the SEARCH_CONDITION expression is true.  Thus, a
'REPEAT' always enters the loop at least once.  STATEMENT_LIST
consists of one or more statements, each terminated by a semicolon (';')
statement delimiter.

A 'REPEAT' statement can be labeled.  For the rules
regarding label use, see statement-labels.

Example:

     mysql> delimiter //

     mysql> CREATE PROCEDURE dorepeat(p1 INT)
         -> BEGIN
         ->   SET @x = 0;
         ->   REPEAT
         ->     SET @x = @x + 1;
         ->   UNTIL @x > p1 END REPEAT;
         -> END
         -> //
     Query OK, 0 rows affected (0.00 sec)

     mysql> CALL dorepeat(1000)//
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @x//
     +------+
     | @x   |
     +------+
     | 1001 |
     +------+
     1 row in set (0.00 sec)

13.6.5.7 RETURN Syntax
......................

     RETURN EXPR

The 'RETURN' statement terminates execution of a stored
function and returns the value EXPR to the function caller.  There must
be at least one 'RETURN' statement in a stored function.
There may be more than one if the function has multiple exit points.

This statement is not used in stored procedures, triggers, or events.
The 'LEAVE' statement can be used to exit a stored program
of those types.

13.6.5.8 WHILE Syntax
.....................

     [BEGIN_LABEL:] WHILE SEARCH_CONDITION DO
         STATEMENT_LIST
     END WHILE [END_LABEL]

The statement list within a 'WHILE' statement is repeated
as long as the SEARCH_CONDITION expression is true.  STATEMENT_LIST
consists of one or more SQL statements, each terminated by a semicolon
(';') statement delimiter.

A 'WHILE' statement can be labeled.  For the rules
regarding label use, see statement-labels.

Example:

     CREATE PROCEDURE dowhile()
     BEGIN
       DECLARE v1 INT DEFAULT 5;

       WHILE v1 > 0 DO
         ...
         SET v1 = v1 - 1;
       END WHILE;
     END;

13.6.6 Cursors
--------------

MySQL supports cursors inside stored programs.  The syntax is as in
embedded SQL. Cursors have these properties:

   * Asensitive: The server may or may not make a copy of its result
     table

   * Read only: Not updatable

   * Nonscrollable: Can be traversed only in one direction and cannot
     skip rows

Cursor declarations must appear before handler declarations and after
variable and condition declarations.

Example:

     CREATE PROCEDURE curdemo()
     BEGIN
       DECLARE done INT DEFAULT FALSE;
       DECLARE a CHAR(16);
       DECLARE b, c INT;
       DECLARE cur1 CURSOR FOR SELECT id,data FROM test.t1;
       DECLARE cur2 CURSOR FOR SELECT i FROM test.t2;
       DECLARE CONTINUE HANDLER FOR NOT FOUND SET done = TRUE;

       OPEN cur1;
       OPEN cur2;

       read_loop: LOOP
         FETCH cur1 INTO a, b;
         FETCH cur2 INTO c;
         IF done THEN
           LEAVE read_loop;
         END IF;
         IF b < c THEN
           INSERT INTO test.t3 VALUES (a,b);
         ELSE
           INSERT INTO test.t3 VALUES (a,c);
         END IF;
       END LOOP;

       CLOSE cur1;
       CLOSE cur2;
     END;

13.6.6.1 Cursor CLOSE Syntax
............................

     CLOSE CURSOR_NAME

This statement closes a previously opened cursor.  For an example, see
cursors.

An error occurs if the cursor is not open.

If not closed explicitly, a cursor is closed at the end of the
'BEGIN ... END' block in which it was declared.

13.6.6.2 Cursor DECLARE Syntax
..............................

     DECLARE CURSOR_NAME CURSOR FOR SELECT_STATEMENT

This statement declares a cursor and associates it with a
'SELECT' statement that retrieves the rows to be traversed by
the cursor.  To fetch the rows later, use a 'FETCH'.
statement.  The number of columns retrieved by the 'SELECT'
statement must match the number of output variables specified in
the 'FETCH' statement.

The 'SELECT' statement cannot have an 'INTO' clause.

Cursor declarations must appear before handler declarations and after
variable and condition declarations.

A stored program may contain multiple cursor declarations, but each
cursor declared in a given block must have a unique name.  For an
example, see cursors.

For information available through 'SHOW' statements, it is
possible in many cases to obtain equivalent information by using a
cursor with an 'INFORMATION_SCHEMA' table.

13.6.6.3 Cursor FETCH Syntax
............................

     FETCH [[NEXT] FROM] CURSOR_NAME INTO VAR_NAME [, VAR_NAME] ...

This statement fetches the next row for the 'SELECT'.
statement associated with the specified cursor (which must be open), and
advances the cursor pointer.  If a row exists, the fetched columns are
stored in the named variables.  The number of columns retrieved by the
'SELECT' statement must match the number of output
variables specified in the 'FETCH' statement.

If no more rows are available, a No Data condition occurs with SQLSTATE
value ''02000''.  To detect this condition, you can set up a handler for
it (or for a 'NOT FOUND' condition).  For an example, see
cursors.

Be aware that another operation, such as a 'SELECT' or another 'FETCH',
may also cause the handler to execute by raising the same condition.  If
it is necessary to distinguish which operation raised the condition,
place the operation within its own 'BEGIN ... END'.
block so that it can be associated with its own handler.

13.6.6.4 Cursor OPEN Syntax
...........................

     OPEN CURSOR_NAME

This statement opens a previously declared cursor.  For an example, see
cursors.

13.6.7 Condition Handling
-------------------------

Conditions may arise during stored program execution that require
special handling, such as exiting the current program block or
continuing execution.  Handlers can be defined for general conditions
such as warnings or exceptions, or for specific conditions such as a
particular error code.  Specific conditions can be assigned names and
referred to that way in handlers.

To name a condition, use the 'DECLARE ... CONDITION'
statement.  To declare a handler, use the
'DECLARE ... HANDLER' statement.  See
declare-condition, and declare-handler.  For information about
how the server chooses handlers when a condition occurs, see
handler-scope.

To raise a condition, use the 'SIGNAL' statement.  To
modify condition information within a condition handler, use
'RESIGNAL'.  See declare-condition, and
declare-handler.

To retrieve information from the diagnostics area, use the 'GET DIAGNOSTICS'
statement (see get-diagnostics).
For information about the diagnostics area, see
diagnostics-area.

13.6.7.1 DECLARE ... CONDITION Syntax
.....................................

     DECLARE CONDITION_NAME CONDITION FOR CONDITION_VALUE

     CONDITION_VALUE:
         MYSQL_ERROR_CODE
       | SQLSTATE [VALUE] SQLSTATE_VALUE

The 'DECLARE ... CONDITION' statement declares
a named error condition, associating a name with a condition that needs
specific handling.  The name can be referred to in a subsequent
'DECLARE ... HANDLER' statement (see
declare-handler).

Condition declarations must appear before cursor or handler
declarations.

The CONDITION_VALUE for 'DECLARE ... CONDITION'
indicates the specific condition or class of
conditions to associate with the condition name.  It can take the
following forms:

   * MYSQL_ERROR_CODE: An integer literal indicating a MySQL error code.

     Do not use MySQL error code 0 because that indicates success rather
     than an error condition.  For a list of MySQL error codes, see
     error-messages-server.

   * SQLSTATE [VALUE] SQLSTATE_VALUE: A 5-character string literal
     indicating an SQLSTATE value.

     Do not use SQLSTATE values that begin with ''00'' because those
     indicate success rather than an error condition.  For a list of
     SQLSTATE values, see error-messages-server.

Condition names referred to in 'SIGNAL' or use
'RESIGNAL' statements must be associated with SQLSTATE
values, not MySQL error codes.

Using names for conditions can help make stored program code clearer.
For example, this handler applies to attempts to drop a nonexistent
table, but that is apparent only if you know that 1051 is the MySQL
error code for 'unknown table':

     DECLARE CONTINUE HANDLER FOR 1051
       BEGIN
         -- body of handler
       END;

By declaring a name for the condition, the purpose of the handler is
more readily seen:

     DECLARE no_such_table CONDITION FOR 1051;
     DECLARE CONTINUE HANDLER FOR no_such_table
       BEGIN
         -- body of handler
       END;

Here is a named condition for the same condition, but based on the
corresponding SQLSTATE value rather than the MySQL error code:

     DECLARE no_such_table CONDITION FOR SQLSTATE '42S02';
     DECLARE CONTINUE HANDLER FOR no_such_table
       BEGIN
         -- body of handler
       END;

13.6.7.2 DECLARE ... HANDLER Syntax
...................................

     DECLARE HANDLER_ACTION HANDLER
         FOR CONDITION_VALUE [, CONDITION_VALUE] ...
         STATEMENT

     HANDLER_ACTION:
         CONTINUE
       | EXIT
       | UNDO

     CONDITION_VALUE:
         MYSQL_ERROR_CODE
       | SQLSTATE [VALUE] SQLSTATE_VALUE
       | CONDITION_NAME
       | SQLWARNING
       | NOT FOUND
       | SQLEXCEPTION

The 'DECLARE ... HANDLER' statement specifies a
handler that deals with one or more conditions.  If one of these
conditions occurs, the specified STATEMENT executes.  STATEMENT can be a
simple statement such as 'SET VAR_NAME = VALUE', or a compound statement
written using 'BEGIN' and 'END' (see begin-end).

Handler declarations must appear after variable or condition
declarations.

The HANDLER_ACTION value indicates what action the handler takes after
execution of the handler statement:

   * 'CONTINUE': Execution of the current program continues.

   * 'EXIT': Execution terminates for the 'BEGIN ... END'
     compound statement in which the handler is declared.
     This is true even if the condition occurs in an inner block.

   * 'UNDO': Not supported.

The CONDITION_VALUE for 'DECLARE ... HANDLER'.
indicates the specific condition or class of conditions that activates
the handler.  It can take the following forms:

   * MYSQL_ERROR_CODE: An integer literal indicating a MySQL error code,
     such as 1051 to specify 'unknown table':

          DECLARE CONTINUE HANDLER FOR 1051
            BEGIN
              -- body of handler
            END;

     Do not use MySQL error code 0 because that indicates success rather
     than an error condition.  For a list of MySQL error codes, see
     error-messages-server.

   * SQLSTATE [VALUE] SQLSTATE_VALUE: A 5-character string literal
     indicating an SQLSTATE value, such as ''42S01'' to specify 'unknown
     table':

          DECLARE CONTINUE HANDLER FOR SQLSTATE '42S02'
            BEGIN
              -- body of handler
            END;

     Do not use SQLSTATE values that begin with ''00'' because those
     indicate success rather than an error condition.  For a list of
     SQLSTATE values, see error-messages-server.

   * CONDITION_NAME: A condition name previously specified with
     'DECLARE ... CONDITION'.  A condition name can
     be associated with a MySQL error code or SQLSTATE value.  See
     declare-condition.

   * 'SQLWARNING': Shorthand for the class of SQLSTATE values that begin
     with ''01''.

          DECLARE CONTINUE HANDLER FOR SQLWARNING
            BEGIN
              -- body of handler
            END;

   * 'NOT FOUND': Shorthand for the class of SQLSTATE values that begin
     with ''02''.  This is relevant within the context of cursors and is
     used to control what happens when a cursor reaches the end of a
     data set.  If no more rows are available, a No Data condition
     occurs with SQLSTATE value ''02000''.  To detect this condition,
     you can set up a handler for it or for a 'NOT FOUND' condition.

          DECLARE CONTINUE HANDLER FOR NOT FOUND
            BEGIN
              -- body of handler
            END;

     For another example, see cursors.  The 'NOT FOUND'
     condition also occurs for 'SELECT ... INTO VAR_LIST' statements
     that retrieve no rows.

   * 'SQLEXCEPTION': Shorthand for the class of SQLSTATE values that do
     not begin with ''00'', ''01'', or ''02''.

          DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
            BEGIN
              -- body of handler
            END;

For information about how the server chooses handlers when a condition
occurs, see handler-scope.

If a condition occurs for which no handler has been declared, the action
taken depends on the condition class:

   * For 'SQLEXCEPTION' conditions, the stored program terminates at the
     statement that raised the condition, as if there were an 'EXIT'
     handler.  If the program was called by another stored program, the
     calling program handles the condition using the handler selection
     rules applied to its own handlers.

   * For 'SQLWARNING' conditions, the program continues executing, as if
     there were a 'CONTINUE' handler.

   * For 'NOT FOUND' conditions, if the condition was raised normally,
     the action is 'CONTINUE'.  If it was raised by 'SIGNAL'
     or 'RESIGNAL', the action is 'EXIT'.

The following example uses a handler for 'SQLSTATE '23000'', which
occurs for a duplicate-key error:

     mysql> CREATE TABLE test.t (s1 INT, PRIMARY KEY (s1));
     Query OK, 0 rows affected (0.00 sec)

     mysql> delimiter //

     mysql> CREATE PROCEDURE handlerdemo ()
         -> BEGIN
         ->   DECLARE CONTINUE HANDLER FOR SQLSTATE '23000' SET @x2 = 1;
         ->   SET @x = 1;
         ->   INSERT INTO test.t VALUES (1);
         ->   SET @x = 2;
         ->   INSERT INTO test.t VALUES (1);
         ->   SET @x = 3;
         -> END;
         -> //
     Query OK, 0 rows affected (0.00 sec)

     mysql> CALL handlerdemo()//
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @x//
         +------+
         | @x   |
         +------+
         | 3    |
         +------+
         1 row in set (0.00 sec)

Notice that '@x' is '3' after the procedure executes, which shows that
execution continued to the end of the procedure after the error
occurred.  If the 'DECLARE ... HANDLER'.
statement had not been present, MySQL would have taken the default
action ('EXIT') after the second 'INSERT' failed due to
the 'PRIMARY KEY' constraint, and 'SELECT @x' would have returned '2'.

To ignore a condition, declare a 'CONTINUE' handler for it and associate
it with an empty block.  For example:

     DECLARE CONTINUE HANDLER FOR SQLWARNING BEGIN END;

The scope of a block label does not include the code for handlers
declared within the block.  Therefore, the statement associated with a
handler cannot use 'ITERATE' or 'LEAVE' to
refer to labels for blocks that enclose the handler declaration.
Consider the following example, where the 'REPEAT' block
has a label of 'retry':

     CREATE PROCEDURE p ()
     BEGIN
       DECLARE i INT DEFAULT 3;
       retry:
         REPEAT
           BEGIN
             DECLARE CONTINUE HANDLER FOR SQLWARNING
               BEGIN
                 ITERATE retry;    # illegal
               END;
             IF i < 0 THEN
               LEAVE retry;        # legal
             END IF;
             SET i = i - 1;
           END;
         UNTIL FALSE END REPEAT;
     END;

The 'retry' label is in scope for the 'IF' statement within
the block.  It is not in scope for the 'CONTINUE' handler, so the
reference there is invalid and results in an error:

     ERROR 1308 (42000): LEAVE with no matching label: retry

To avoid references to outer labels in handlers, use one of these
strategies:

   * To leave the block, use an 'EXIT' handler.  If no block cleanup is
     required, the 'BEGIN ... END' handler body can be
     empty:

          DECLARE EXIT HANDLER FOR SQLWARNING BEGIN END;

     Otherwise, put the cleanup statements in the handler body:

          DECLARE EXIT HANDLER FOR SQLWARNING
            BEGIN
              BLOCK CLEANUP STATEMENTS
            END;

   * To continue execution, set a status variable in a 'CONTINUE'
     handler that can be checked in the enclosing block to determine
     whether the handler was invoked.  The following example uses the
     variable 'done' for this purpose:

          CREATE PROCEDURE p ()
          BEGIN
            DECLARE i INT DEFAULT 3;
            DECLARE done INT DEFAULT FALSE;
            retry:
              REPEAT
                BEGIN
                  DECLARE CONTINUE HANDLER FOR SQLWARNING
                    BEGIN
                      SET done = TRUE;
                    END;
                  IF done OR i < 0 THEN
                    LEAVE retry;
                  END IF;
                  SET i = i - 1;
                END;
              UNTIL FALSE END REPEAT;
          END;

13.6.7.3 GET DIAGNOSTICS Syntax
...............................

     GET [CURRENT | STACKED] DIAGNOSTICS
     {
         STATEMENT_INFORMATION_ITEM
         [, STATEMENT_INFORMATION_ITEM] ...
       | CONDITION CONDITION_NUMBER
         CONDITION_INFORMATION_ITEM
         [, CONDITION_INFORMATION_ITEM] ...
     }

     STATEMENT_INFORMATION_ITEM:
         TARGET = STATEMENT_INFORMATION_ITEM_NAME

     CONDITION_INFORMATION_ITEM:
         TARGET = CONDITION_INFORMATION_ITEM_NAME

     STATEMENT_INFORMATION_ITEM_NAME:
         NUMBER
       | ROW_COUNT

     CONDITION_INFORMATION_ITEM_NAME:
         CLASS_ORIGIN
       | SUBCLASS_ORIGIN
       | RETURNED_SQLSTATE
       | MESSAGE_TEXT
       | MYSQL_ERRNO
       | CONSTRAINT_CATALOG
       | CONSTRAINT_SCHEMA
       | CONSTRAINT_NAME
       | CATALOG_NAME
       | SCHEMA_NAME
       | TABLE_NAME
       | COLUMN_NAME
       | CURSOR_NAME

     CONDITION_NUMBER, TARGET:
         (see following discussion)

SQL statements produce diagnostic information that populates the
diagnostics area.  The 'GET DIAGNOSTICS'.
statement enables applications to inspect this information.  (You can
also use 'SHOW WARNINGS' or 'SHOW ERRORS'
to see conditions or errors.)

No special privileges are required to execute 'GET DIAGNOSTICS'.

The keyword 'CURRENT' means to retrieve information from the current
diagnostics area.  The keyword 'STACKED' means to retrieve information
from the second diagnostics area, which is available only if the current
context is a condition handler.  If neither keyword is given, the
default is to use the current diagnostics area.

The 'GET DIAGNOSTICS' statement is typically
used in a handler within a stored program.  It is a MySQL extension that
'GET [CURRENT] DIAGNOSTICS' is permitted outside
handler context to check the execution of any SQL statement.  For
example, if you invoke the 'mysql' client program, you can
enter these statements at the prompt:

     mysql> DROP TABLE test.no_such_table;
     ERROR 1051 (42S02): Unknown table 'test.no_such_table'
     mysql> GET DIAGNOSTICS CONDITION 1
         ->   @p1 = RETURNED_SQLSTATE, @p2 = MESSAGE_TEXT;
     mysql> SELECT @p1, @p2;
     +-------+------------------------------------+
     | @p1   | @p2                                |
     +-------+------------------------------------+
     | 42S02 | Unknown table 'test.no_such_table' |
     +-------+------------------------------------+

This extension applies only to the current diagnostics area.  It does
not apply to the second diagnostics area because 'GET STACKED
DIAGNOSTICS' is permitted only if the current context is a condition
handler.  If that is not the case, a 'GET STACKED DIAGNOSTICS when
handler not active' error occurs.

For a description of the diagnostics area, see diagnostics-area.
Briefly, it contains two kinds of information:

   * Statement information, such as the number of conditions that
     occurred or the affected-rows count.

   * Condition information, such as the error code and message.  If a
     statement raises multiple conditions, this part of the diagnostics
     area has a condition area for each one.  If a statement raises no
     conditions, this part of the diagnostics area is empty.

For a statement that produces three conditions, the diagnostics area
contains statement and condition information like this:

     Statement information:
       row count
       ... other statement information items ...
     Condition area list:
       Condition area 1:
         error code for condition 1
         error message for condition 1
         ... other condition information items ...
       Condition area 2:
         error code for condition 2:
         error message for condition 2
         ... other condition information items ...
       Condition area 3:
         error code for condition 3
         error message for condition 3
         ... other condition information items ...

'GET DIAGNOSTICS' can obtain either statement or
condition information, but not both in the same statement:

   * To obtain statement information, retrieve the desired statement
     items into target variables.  This instance of 'GET DIAGNOSTICS'
     assigns the number of available
     conditions and the rows-affected count to the user variables '@p1'
     and '@p2':

          GET DIAGNOSTICS @p1 = NUMBER, @p2 = ROW_COUNT;

   * To obtain condition information, specify the condition number and
     retrieve the desired condition items into target variables.  This
     instance of 'GET DIAGNOSTICS' assigns the
     SQLSTATE value and error message to the user variables '@p3' and
     '@p4':

          GET DIAGNOSTICS CONDITION 1
            @p3 = RETURNED_SQLSTATE, @p4 = MESSAGE_TEXT;

The retrieval list specifies one or more 'TARGET = ITEM_NAME'
assignments, separated by commas.  Each assignment names a target
variable and either a STATEMENT_INFORMATION_ITEM_NAME or
CONDITION_INFORMATION_ITEM_NAME designator, depending on whether the
statement retrieves statement or condition information.

Valid TARGET designators for storing item information can be stored
procedure or function parameters, stored program local variables
declared with 'DECLARE', or user-defined variables.

Valid CONDITION_NUMBER designators can be stored procedure or function
parameters, stored program local variables declared with
'DECLARE', user-defined variables, system variables, or
literals.  A character literal may include a _CHARSET introducer.  A
warning occurs if the condition number is not in the range from 1 to the
number of condition areas that have information.  In this case, the
warning is added to the diagnostics area without clearing it.

When a condition occurs, MySQL does not populate all condition items
recognized by 'GET DIAGNOSTICS'.  For example:

     mysql> GET DIAGNOSTICS CONDITION 1
         ->   @p5 = SCHEMA_NAME, @p6 = TABLE_NAME;
     mysql> SELECT @p5, @p6;
     +------+------+
     | @p5  | @p6  |
     +------+------+
     |      |      |
     +------+------+

In standard SQL, if there are multiple conditions, the first condition
relates to the 'SQLSTATE' value returned for the previous SQL statement.
In MySQL, this is not guaranteed.  To get the main error, you cannot do
this:

     GET DIAGNOSTICS CONDITION 1 @errno = MYSQL_ERRNO;

Instead, retrieve the condition count first, then use it to specify
which condition number to inspect:

     GET DIAGNOSTICS @cno = NUMBER;
     GET DIAGNOSTICS CONDITION @cno @errno = MYSQL_ERRNO;

For information about permissible statement and condition information
items, and which ones are populated when a condition occurs, see
diagnostics-area-information-items.

Here is an example that uses 'GET DIAGNOSTICS'.
and an exception handler in stored procedure context to assess the
outcome of an insert operation.  If the insert was successful, the
procedure uses 'GET DIAGNOSTICS' to get the
rows-affected count.  This shows that you can use 'GET DIAGNOSTICS'
multiple times to retrieve information
about a statement as long as the current diagnostics area has not been
cleared.

     CREATE PROCEDURE do_insert(value INT)
     BEGIN
       -- Declare variables to hold diagnostics area information
       DECLARE code CHAR(5) DEFAULT '00000';
       DECLARE msg TEXT;
       DECLARE rows INT;
       DECLARE result TEXT;
       -- Declare exception handler for failed insert
       DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
         BEGIN
           GET DIAGNOSTICS CONDITION 1
             code = RETURNED_SQLSTATE, msg = MESSAGE_TEXT;
         END;

       -- Perform the insert
       INSERT INTO t1 (int_col) VALUES(value);
       -- Check whether the insert was successful
       IF code = '00000' THEN
         GET DIAGNOSTICS rows = ROW_COUNT;
         SET result = CONCAT('insert succeeded, row count = ',rows);
       ELSE
         SET result = CONCAT('insert failed, error = ',code,', message = ',msg);
       END IF;
       -- Say what happened
       SELECT result;
     END;

Suppose that 't1.int_col' is an integer column that is declared as 'NOT
NULL'.  The procedure produces these results when invoked to insert
non-'NULL' and 'NULL' values, respectively:

     mysql> CALL do_insert(1);
     +---------------------------------+
     | result                          |
     +---------------------------------+
     | insert succeeded, row count = 1 |
     +---------------------------------+

     mysql> CALL do_insert(NULL);
     +-------------------------------------------------------------------------+
     | result                                                                  |
     +-------------------------------------------------------------------------+
     | insert failed, error = 23000, message = Column 'int_col' cannot be null |
     +-------------------------------------------------------------------------+

When a condition handler activates, a push to the diagnostics area stack
occurs:

   * The first (current) diagnostics area becomes the second (stacked)
     diagnostics area and a new current diagnostics area is created as a
     copy of it.

   * 'GET [CURRENT] DIAGNOSTICS' and 'GET STACKED DIAGNOSTICS'
     can be used within the
     handler to access the contents of the current and stacked
     diagnostics areas.

   * Initially, both diagnostics areas return the same result, so it is
     possible to get information from the current diagnostics area about
     the condition that activated the handler, _as long as_ you execute
     no statements within the handler that change its current
     diagnostics area.

   * However, statements executing within the handler can modify the
     current diagnostics area, clearing and setting its contents
     according to the normal rules (see
     diagnostics-area-populating).

     A more reliable way to obtain information about the
     handler-activating condition is to use the stacked diagnostics
     area, which cannot be modified by statements executing within the
     handler except 'RESIGNAL'.  For information about
     when the current diagnostics area is set and cleared, see
     diagnostics-area.

The next example shows how 'GET STACKED DIAGNOSTICS' can be used within
a handler to obtain information about the handled exception, even after
the current diagnostics area has been modified by handler statements.

Within a stored procedure 'p()', we attempt to insert two values into a
table that contains a 'TEXT NOT NULL' column.  The first value is a
non-'NULL' string and the second is 'NULL'.  The column prohibits 'NULL'
values, so the first insert succeeds but the second causes an exception.
The procedure includes an exception handler that maps attempts to insert
'NULL' into inserts of the empty string:

     DROP TABLE IF EXISTS t1;
     CREATE TABLE t1 (c1 TEXT NOT NULL);
     DROP PROCEDURE IF EXISTS p;
     delimiter //
     CREATE PROCEDURE p ()
     BEGIN
       -- Declare variables to hold diagnostics area information
       DECLARE errcount INT;
       DECLARE errno INT;
       DECLARE msg TEXT;
       DECLARE EXIT HANDLER FOR SQLEXCEPTION
       BEGIN
         -- Here the current DA is nonempty because no prior statements
         -- executing within the handler have cleared it
         GET CURRENT DIAGNOSTICS CONDITION 1
           errno = MYSQL_ERRNO, msg = MESSAGE_TEXT;
         SELECT 'current DA before mapped insert' AS op, errno, msg;
         GET STACKED DIAGNOSTICS CONDITION 1
           errno = MYSQL_ERRNO, msg = MESSAGE_TEXT;
         SELECT 'stacked DA before mapped insert' AS op, errno, msg;

         -- Map attempted NULL insert to empty string insert
         INSERT INTO t1 (c1) VALUES('');

         -- Here the current DA should be empty (if the INSERT succeeded),
         -- so check whether there are conditions before attempting to
         -- obtain condition information
         GET CURRENT DIAGNOSTICS errcount = NUMBER;
         IF errcount = 0
         THEN
           SELECT 'mapped insert succeeded, current DA is empty' AS op;
         ELSE
           GET CURRENT DIAGNOSTICS CONDITION 1
             errno = MYSQL_ERRNO, msg = MESSAGE_TEXT;
           SELECT 'current DA after mapped insert' AS op, errno, msg;
         END IF ;
         GET STACKED DIAGNOSTICS CONDITION 1
           errno = MYSQL_ERRNO, msg = MESSAGE_TEXT;
         SELECT 'stacked DA after mapped insert' AS op, errno, msg;
       END;
       INSERT INTO t1 (c1) VALUES('string 1');
       INSERT INTO t1 (c1) VALUES(NULL);
     END;
     //
     delimiter ;
     CALL p();
     SELECT * FROM t1;

When the handler activates, a copy of the current diagnostics area is
pushed to the diagnostics area stack.  The handler first displays the
contents of the current and stacked diagnostics areas, which are both
the same initially:

     +---------------------------------+-------+----------------------------+
     | op                              | errno | msg                        |
     +---------------------------------+-------+----------------------------+
     | current DA before mapped insert |  1048 | Column 'c1' cannot be null |
     +---------------------------------+-------+----------------------------+

     +---------------------------------+-------+----------------------------+
     | op                              | errno | msg                        |
     +---------------------------------+-------+----------------------------+
     | stacked DA before mapped insert |  1048 | Column 'c1' cannot be null |
     +---------------------------------+-------+----------------------------+

Statements executing after the 'GET DIAGNOSTICS'.
statements may reset the current diagnostics area.  statements may reset
the current diagnostics area.  For example, the handler maps the 'NULL'
insert to an empty-string insert and displays the result.  The new
insert succeeds and clears the current diagnostics area, but the stacked
diagnostics area remains unchanged and still contains information about
the condition that activated the handler:

     +----------------------------------------------+
     | op                                           |
     +----------------------------------------------+
     | mapped insert succeeded, current DA is empty |
     +----------------------------------------------+

     +--------------------------------+-------+----------------------------+
     | op                             | errno | msg                        |
     +--------------------------------+-------+----------------------------+
     | stacked DA after mapped insert |  1048 | Column 'c1' cannot be null |
     +--------------------------------+-------+----------------------------+

When the condition handler ends, its current diagnostics area is popped
from the stack and the stacked diagnostics area becomes the current
diagnostics area in the stored procedure.

After the procedure returns, the table contains two rows.  The empty row
results from the attempt to insert 'NULL' that was mapped to an
empty-string insert:

     +----------+
     | c1       |
     +----------+
     | string 1 |
     |          |
     +----------+

In the preceding example, the first two 'GET DIAGNOSTICS'
statements within the condition handler that retrieve
information from the current and stacked diagnostics areas return the
same values.  This will not be the case if statements that reset the
current diagnostics area execute earlier within the handler.  Suppose
that 'p()' is rewritten to place the 'DECLARE'.
statements within the handler definition rather than preceding it:

     CREATE PROCEDURE p ()
     BEGIN
       DECLARE EXIT HANDLER FOR SQLEXCEPTION
       BEGIN
         -- Declare variables to hold diagnostics area information
         DECLARE errcount INT;
         DECLARE errno INT;
         DECLARE msg TEXT;
         GET CURRENT DIAGNOSTICS CONDITION 1
           errno = MYSQL_ERRNO, msg = MESSAGE_TEXT;
         SELECT 'current DA before mapped insert' AS op, errno, msg;
         GET STACKED DIAGNOSTICS CONDITION 1
           errno = MYSQL_ERRNO, msg = MESSAGE_TEXT;
         SELECT 'stacked DA before mapped insert' AS op, errno, msg;
     ...

In this case, the result is version dependent:

   * Before MySQL 5.7.2, see 'DECLARE' does not change the
     current diagnostics area, so the first two 'GET DIAGNOSTICS'
     statements return the same result, just as in the
     original version of 'p()'.

     In MySQL 5.7.2, work was done to ensure that all nondiagnostic
     statements populate the diagnostics area, per the SQL standard.
     'DECLARE' is one of them, so in 5.7.2 and higher,
     see 'DECLARE' statements executing at the beginning of
     the handler clear the current diagnostics area and the 'GET DIAGNOSTICS'
     statements produce different
     results:

          +---------------------------------+-------+------+
          | op                              | errno | msg  |
          +---------------------------------+-------+------+
          | current DA before mapped insert |  NULL | NULL |
          +---------------------------------+-------+------+

          +---------------------------------+-------+----------------------------+
          | op                              | errno | msg                        |
          +---------------------------------+-------+----------------------------+
          | stacked DA before mapped insert |  1048 | Column 'c1' cannot be null |
          +---------------------------------+-------+----------------------------+

To avoid this issue within a condition handler when seeking to obtain
information about the condition that activated the handler, be sure to
access the stacked diagnostics area, not the current diagnostics area.

13.6.7.4 RESIGNAL Syntax
........................

     RESIGNAL [CONDITION_VALUE]
         [SET SIGNAL_INFORMATION_ITEM
         [, SIGNAL_INFORMATION_ITEM] ...]

     CONDITION_VALUE:
         SQLSTATE [VALUE] SQLSTATE_VALUE
       | CONDITION_NAME

     SIGNAL_INFORMATION_ITEM:
         CONDITION_INFORMATION_ITEM_NAME = SIMPLE_VALUE_SPECIFICATION

     CONDITION_INFORMATION_ITEM_NAME:
         CLASS_ORIGIN
       | SUBCLASS_ORIGIN
       | MESSAGE_TEXT
       | MYSQL_ERRNO
       | CONSTRAINT_CATALOG
       | CONSTRAINT_SCHEMA
       | CONSTRAINT_NAME
       | CATALOG_NAME
       | SCHEMA_NAME
       | TABLE_NAME
       | COLUMN_NAME
       | CURSOR_NAME

     CONDITION_NAME, SIMPLE_VALUE_SPECIFICATION:
         (see following discussion)

'RESIGNAL' passes on the error condition information
that is available during execution of a condition handler within a
compound statement inside a stored procedure or function, trigger, or
event.  'RESIGNAL' may change some or all information
before passing it on.  'RESIGNAL' is related to
'SIGNAL', but instead of originating a condition as
'SIGNAL' does, see 'RESIGNAL' relays existing
condition information, possibly after modifying it.

'RESIGNAL' makes it possible to both handle an error
and return the error information.  Otherwise, by executing an SQL
statement within the handler, information that caused the handler's
activation is destroyed.  'RESIGNAL' also can make some
procedures shorter if a given handler can handle part of a situation,
then pass the condition 'up the line' to another handler.

No special privileges are required to execute the 'RESIGNAL'
statement.

All forms of 'RESIGNAL' require that the current
context be a condition handler.  Otherwise, see 'RESIGNAL'.
is illegal and a 'RESIGNAL when handler not active' error occurs.

To retrieve information from the diagnostics area, use the 'GET DIAGNOSTICS'
statement (see get-diagnostics).
For information about the diagnostics area, see
diagnostics-area.

For CONDITION_VALUE and SIGNAL_INFORMATION_ITEM, the definitions and
rules are the same for 'RESIGNAL' as for
'SIGNAL'.  For example, the CONDITION_VALUE can be an 'SQLSTATE'
value, and the value can indicate errors, warnings, or 'not found.' For
additional information, see signal.

The 'RESIGNAL' statement takes CONDITION_VALUE and
'SET' clauses, both of which are optional.  This leads to several
possible uses:

   * 'RESIGNAL' alone:

          RESIGNAL;

   * 'RESIGNAL' with new signal information:

          RESIGNAL SET SIGNAL_INFORMATION_ITEM [, SIGNAL_INFORMATION_ITEM] ...;

   * 'RESIGNAL' with a condition value and possibly new
     signal information:

          RESIGNAL CONDITION_VALUE
              [SET SIGNAL_INFORMATION_ITEM [, SIGNAL_INFORMATION_ITEM] ...];

These use cases all cause changes to the diagnostics and condition
areas:

   * A diagnostics area contains one or more condition areas.

   * A condition area contains condition information items, such as the
     'SQLSTATE' value, 'MYSQL_ERRNO', or 'MESSAGE_TEXT'.

There is a stack of diagnostics areas.  When a handler takes control, it
pushes a diagnostics area to the top of the stack, so there are two
diagnostics areas during handler execution:

   * The first (current) diagnostics area, which starts as a copy of the
     last diagnostics area, but will be overwritten by the first
     statement in the handler that changes the current diagnostics area.

   * The last (stacked) diagnostics area, which has the condition areas
     that were set up before the handler took control.

The maximum number of condition areas in a diagnostics area is
determined by the value of the 'max_error_count' system variable.  See
diagnostics-area-system-variables.

13.6.7.5 RESIGNAL Alone
.......................

A simple 'RESIGNAL' alone means 'pass on the error with
no change.' It restores the last diagnostics area and makes it the
current diagnostics area.  That is, it 'pops' the diagnostics area
stack.

Within a condition handler that catches a condition, one use for
'RESIGNAL' alone is to perform some other actions, and then
pass on without change the original condition information (the
information that existed before entry into the handler).

Example:

     DROP TABLE IF EXISTS xx;
     delimiter //
     CREATE PROCEDURE p ()
     BEGIN
       DECLARE EXIT HANDLER FOR SQLEXCEPTION
       BEGIN
         SET @error_count = @error_count + 1;
         IF @a = 0 THEN RESIGNAL; END IF;
       END;
       DROP TABLE xx;
     END//
     delimiter ;
     SET @error_count = 0;
     SET @a = 0;
     CALL p();

Suppose that the 'DROP TABLE xx' statement fails.  The diagnostics area
stack looks like this:

     DA 1. ERROR 1051 (42S02): Unknown table 'xx'

Then execution enters the 'EXIT' handler.  It starts by pushing a
diagnostics area to the top of the stack, which now looks like this:

     DA 1. ERROR 1051 (42S02): Unknown table 'xx'
     DA 2. ERROR 1051 (42S02): Unknown table 'xx'

At this point, the contents of the first (current) and second (stacked)
diagnostics areas are the same.  The first diagnostics area may be
modified by statements executing subsequently within the handler.

Usually a procedure statement clears the first diagnostics area.
'BEGIN' is an exception, it does not clear, it does nothing.  'SET' is
not an exception, it clears, performs the operation, and produces a
result of 'success.' The diagnostics area stack now looks like this:

     DA 1. ERROR 0000 (00000): Successful operation
     DA 2. ERROR 1051 (42S02): Unknown table 'xx'

At this point, if '@a = 0', see 'RESIGNAL' pops the
diagnostics area stack, which now looks like this:

     DA 1. ERROR 1051 (42S02): Unknown table 'xx'

And that is what the caller sees.

If '@a' is not 0, the handler simply ends, which means that there is no
more use for the current diagnostics area (it has been 'handled'), so it
can be thrown away, causing the stacked diagnostics area to become the
current diagnostics area again.  The diagnostics area stack looks like
this:

     DA 1. ERROR 0000 (00000): Successful operation

The details make it look complex, but the end result is quite useful:
Handlers can execute without destroying information about the condition
that caused activation of the handler.

13.6.7.6 RESIGNAL with New Signal Information
.............................................

'RESIGNAL' with a 'SET' clause provides new signal
information, so the statement means 'pass on the error with changes':

     RESIGNAL SET SIGNAL_INFORMATION_ITEM [, SIGNAL_INFORMATION_ITEM] ...;

As with 'RESIGNAL' alone, the idea is to pop the
diagnostics area stack so that the original information will go out.
Unlike 'RESIGNAL' alone, anything specified in the
'SET' clause changes.

Example:

     DROP TABLE IF EXISTS xx;
     delimiter //
     CREATE PROCEDURE p ()
     BEGIN
       DECLARE EXIT HANDLER FOR SQLEXCEPTION
       BEGIN
         SET @error_count = @error_count + 1;
         IF @a = 0 THEN RESIGNAL SET MYSQL_ERRNO = 5; END IF;
       END;
       DROP TABLE xx;
     END//
     delimiter ;
     SET @error_count = 0;
     SET @a = 0;
     CALL p();

Remember from the previous discussion that 'RESIGNAL'.
alone results in a diagnostics area stack like this:

     DA 1. ERROR 1051 (42S02): Unknown table 'xx'

The 'RESIGNAL SET MYSQL_ERRNO = 5' statement results in this stack
instead, which is what the caller sees:

     DA 1. ERROR 5 (42S02): Unknown table 'xx'

In other words, it changes the error number, and nothing else.

The 'RESIGNAL' statement can change any or all of the
signal information items, making the first condition area of the
diagnostics area look quite different.

13.6.7.7 RESIGNAL with a Condition Value and Optional New Signal Information
............................................................................

'RESIGNAL' with a condition value means 'push a
condition into the current diagnostics area.' If the 'SET' clause is
present, it also changes the error information.

     RESIGNAL CONDITION_VALUE
         [SET SIGNAL_INFORMATION_ITEM [, SIGNAL_INFORMATION_ITEM] ...];

This form of 'RESIGNAL' restores the last diagnostics
area and makes it the current diagnostics area.  That is, it 'pops' the
diagnostics area stack, which is the same as what a simple
'RESIGNAL' alone would do.  However, it also changes the
diagnostics area depending on the condition value or signal information.

Example:

     DROP TABLE IF EXISTS xx;
     delimiter //
     CREATE PROCEDURE p ()
     BEGIN
       DECLARE EXIT HANDLER FOR SQLEXCEPTION
       BEGIN
         SET @error_count = @error_count + 1;
         IF @a = 0 THEN RESIGNAL SQLSTATE '45000' SET MYSQL_ERRNO=5; END IF;
       END;
       DROP TABLE xx;
     END//
     delimiter ;
     SET @error_count = 0;
     SET @a = 0;
     SET @@max_error_count = 2;
     CALL p();
     SHOW ERRORS;

This is similar to the previous example, and the effects are the same,
except that if 'RESIGNAL' happens, the current
condition area looks different at the end.  (The reason the condition
adds to rather than replaces the existing condition is the use of a
condition value.)

The 'RESIGNAL' statement includes a condition value
('SQLSTATE '45000''), so it adds a new condition area, resulting in a
diagnostics area stack that looks like this:

     DA 1. (condition 2) ERROR 1051 (42S02): Unknown table 'xx'
           (condition 1) ERROR 5 (45000) Unknown table 'xx'

The result of 'CALL p()' and 'SHOW ERRORS'
for this example is:

     mysql> CALL p();
     ERROR 5 (45000): Unknown table 'xx'
     mysql> SHOW ERRORS;
     +-------+------+----------------------------------+
     | Level | Code | Message                          |
     +-------+------+----------------------------------+
     | Error | 1051 | Unknown table 'xx'               |
     | Error |    5 | Unknown table 'xx'               |
     +-------+------+----------------------------------+

13.6.7.8 RESIGNAL Requires Condition Handler Context
....................................................

All forms of 'RESIGNAL' require that the current
context be a condition handler.  Otherwise, see 'RESIGNAL'.
is illegal and a 'RESIGNAL when handler not active' error occurs.  For
example:

     mysql> CREATE PROCEDURE p () RESIGNAL;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CALL p();
     ERROR 1645 (0K000): RESIGNAL when handler not active

Here is a more difficult example:

     delimiter //
     CREATE FUNCTION f () RETURNS INT
     BEGIN
       RESIGNAL;
       RETURN 5;
     END//
     CREATE PROCEDURE p ()
     BEGIN
       DECLARE EXIT HANDLER FOR SQLEXCEPTION SET @a=f();
       SIGNAL SQLSTATE '55555';
     END//
     delimiter ;
     CALL p();

'RESIGNAL' occurs within the stored function 'f()'.
Although 'f()' itself is invoked within the context of the 'EXIT'
handler, execution within 'f()' has its own context, which is not
handler context.  Thus, 'RESIGNAL' within 'f()' results in a 'handler
not active' error.

13.6.7.9 SIGNAL Syntax
......................

     SIGNAL CONDITION_VALUE
         [SET SIGNAL_INFORMATION_ITEM
         [, SIGNAL_INFORMATION_ITEM] ...]

     CONDITION_VALUE:
         SQLSTATE [VALUE] SQLSTATE_VALUE
       | CONDITION_NAME

     SIGNAL_INFORMATION_ITEM:
         CONDITION_INFORMATION_ITEM_NAME = SIMPLE_VALUE_SPECIFICATION

     CONDITION_INFORMATION_ITEM_NAME:
         CLASS_ORIGIN
       | SUBCLASS_ORIGIN
       | MESSAGE_TEXT
       | MYSQL_ERRNO
       | CONSTRAINT_CATALOG
       | CONSTRAINT_SCHEMA
       | CONSTRAINT_NAME
       | CATALOG_NAME
       | SCHEMA_NAME
       | TABLE_NAME
       | COLUMN_NAME
       | CURSOR_NAME

     CONDITION_NAME, SIMPLE_VALUE_SPECIFICATION:
         (see following discussion)

'SIGNAL' is the way to 'return' an error.
'SIGNAL' provides error information to a handler, to an outer
portion of the application, or to the client.  Also, it provides control
over the error's characteristics (error number, 'SQLSTATE' value,
message).  Without 'SIGNAL', it is necessary to resort to
workarounds such as deliberately referring to a nonexistent table to
cause a routine to return an error.

No special privileges are required to execute the 'SIGNAL'
statement.

To retrieve information from the diagnostics area, use the 'GET DIAGNOSTICS'
statement (see get-diagnostics).
For information about the diagnostics area, see
diagnostics-area.

The CONDITION_VALUE in a 'SIGNAL' statement indicates the
error value to be returned.  It can be an 'SQLSTATE' value (a
5-character string literal) or a CONDITION_NAME that refers to a named
condition previously defined with 'DECLARE ... CONDITION'.
(see declare-condition).

An 'SQLSTATE' value can indicate errors, warnings, or 'not found.' The
first two characters of the value indicate its error class, as discussed
in signal-condition-information-items.  Some signal values cause
statement termination; see signal-effects.

The 'SQLSTATE' value for a 'SIGNAL' statement should not
start with ''00'' because such values indicate success and are not valid
for signaling an error.  This is true whether the 'SQLSTATE' value is
specified directly in the 'SIGNAL' statement or in a
named condition referred to in the statement.  If the value is invalid,
a 'Bad SQLSTATE' error occurs.

To signal a generic 'SQLSTATE' value, use ''45000'', which means
'unhandled user-defined exception.'

The 'SIGNAL' statement optionally includes a 'SET' clause
that contains multiple signal items, in a comma-separated list of
CONDITION_INFORMATION_ITEM_NAME = SIMPLE_VALUE_SPECIFICATION
assignments.

Each CONDITION_INFORMATION_ITEM_NAME may be specified only once in the
'SET' clause.  Otherwise, a 'Duplicate condition information item' error
occurs.

Valid SIMPLE_VALUE_SPECIFICATION designators can be specified using
stored procedure or function parameters, stored program local variables
declared with 'DECLARE', user-defined variables, system
variables, or literals.  A character literal may include a _CHARSET
introducer.

For information about permissible CONDITION_INFORMATION_ITEM_NAME
values, see signal-condition-information-items.

The following procedure signals an error or warning depending on the
value of 'pval', its input parameter:

     CREATE PROCEDURE p (pval INT)
     BEGIN
       DECLARE specialty CONDITION FOR SQLSTATE '45000';
       IF pval = 0 THEN
         SIGNAL SQLSTATE '01000';
       ELSEIF pval = 1 THEN
         SIGNAL SQLSTATE '45000'
           SET MESSAGE_TEXT = 'An error occurred';
       ELSEIF pval = 2 THEN
         SIGNAL specialty
           SET MESSAGE_TEXT = 'An error occurred';
       ELSE
         SIGNAL SQLSTATE '01000'
           SET MESSAGE_TEXT = 'A warning occurred', MYSQL_ERRNO = 1000;
         SIGNAL SQLSTATE '45000'
           SET MESSAGE_TEXT = 'An error occurred', MYSQL_ERRNO = 1001;
       END IF;
     END;

If 'pval' is 0, 'p()' signals a warning because 'SQLSTATE' values that
begin with ''01'' are signals in the warning class.  The warning does
not terminate the procedure, and can be seen with 'SHOW WARNINGS'
after the procedure returns.

If 'pval' is 1, 'p()' signals an error and sets the 'MESSAGE_TEXT'
condition information item.  The error terminates the procedure, and the
text is returned with the error information.

If 'pval' is 2, the same error is signaled, although the 'SQLSTATE'
value is specified using a named condition in this case.

If 'pval' is anything else, 'p()' first signals a warning and sets the
message text and error number condition information items.  This warning
does not terminate the procedure, so execution continues and 'p()' then
signals an error.  The error does terminate the procedure.  The message
text and error number set by the warning are replaced by the values set
by the error, which are returned with the error information.

'SIGNAL' is typically used within stored programs, but it
is a MySQL extension that it is permitted outside handler context.  For
example, if you invoke the 'mysql' client program, you can
enter any of these statements at the prompt:

     mysql> SIGNAL SQLSTATE '77777';
     mysql> CREATE TRIGGER t_bi BEFORE INSERT ON t
         -> FOR EACH ROW SIGNAL SQLSTATE '77777';
     mysql> CREATE EVENT e ON SCHEDULE EVERY 1 SECOND
         -> DO SIGNAL SQLSTATE '77777';

'SIGNAL' executes according to the following rules:

If the 'SIGNAL' statement indicates a particular
'SQLSTATE' value, that value is used to signal the condition specified.
Example:

     CREATE PROCEDURE p (divisor INT)
     BEGIN
       IF divisor = 0 THEN
         SIGNAL SQLSTATE '22012';
       END IF;
     END;

If the 'SIGNAL' statement uses a named condition, the
condition must be declared in some scope that applies to the
'SIGNAL' statement, and must be defined using an 'SQLSTATE'
value, not a MySQL error number.  Example:

     CREATE PROCEDURE p (divisor INT)
     BEGIN
       DECLARE divide_by_zero CONDITION FOR SQLSTATE '22012';
       IF divisor = 0 THEN
         SIGNAL divide_by_zero;
       END IF;
     END;

If the named condition does not exist in the scope of the
'SIGNAL' statement, an 'Undefined CONDITION' error occurs.

If 'SIGNAL' refers to a named condition that is defined
with a MySQL error number rather than an 'SQLSTATE' value, a
'SIGNAL/RESIGNAL can only use a CONDITION defined with SQLSTATE' error
occurs.  The following statements cause that error because the named
condition is associated with a MySQL error number:

     DECLARE no_such_table CONDITION FOR 1051;
     SIGNAL no_such_table;

If a condition with a given name is declared multiple times in different
scopes, the declaration with the most local scope applies.  Consider the
following procedure:

     CREATE PROCEDURE p (divisor INT)
     BEGIN
       DECLARE my_error CONDITION FOR SQLSTATE '45000';
       IF divisor = 0 THEN
         BEGIN
           DECLARE my_error CONDITION FOR SQLSTATE '22012';
           SIGNAL my_error;
         END;
       END IF;
       SIGNAL my_error;
     END;

If 'divisor' is 0, the first 'SIGNAL' statement executes.
The innermost 'my_error' condition declaration applies, raising
'SQLSTATE' ''22012''.

If 'divisor' is not 0, the second 'SIGNAL' statement
executes.  The outermost 'my_error' condition declaration applies,
raising 'SQLSTATE' ''45000''.

For information about how the server chooses handlers when a condition
occurs, see handler-scope.

Signals can be raised within exception handlers:

     CREATE PROCEDURE p ()
     BEGIN
       DECLARE EXIT HANDLER FOR SQLEXCEPTION
       BEGIN
         SIGNAL SQLSTATE VALUE '99999'
           SET MESSAGE_TEXT = 'An error occurred';
       END;
       DROP TABLE no_such_table;
     END;

'CALL p()' reaches the 'DROP TABLE' statement.  There
is no table named 'no_such_table', so the error handler is activated.
The error handler destroys the original error ('no such table') and
makes a new error with 'SQLSTATE' ''99999'' and message 'An error
occurred'.

13.6.7.10 Signal Condition Information Items
............................................

The following table lists the names of diagnostics area condition
information items that can be set in a 'SIGNAL'. (or
'RESIGNAL') statement.  All items are standard SQL except
'MYSQL_ERRNO', which is a MySQL extension.  For more information about
these items see diagnostics-area.

     Item Name             Definition
     ---------             ----------
     CLASS_ORIGIN          VARCHAR(64)
     SUBCLASS_ORIGIN       VARCHAR(64)
     CONSTRAINT_CATALOG    VARCHAR(64)
     CONSTRAINT_SCHEMA     VARCHAR(64)
     CONSTRAINT_NAME       VARCHAR(64)
     CATALOG_NAME          VARCHAR(64)
     SCHEMA_NAME           VARCHAR(64)
     TABLE_NAME            VARCHAR(64)
     COLUMN_NAME           VARCHAR(64)
     CURSOR_NAME           VARCHAR(64)
     MESSAGE_TEXT          VARCHAR(128)
     MYSQL_ERRNO           SMALLINT UNSIGNED

The character set for character items is UTF-8.

It is illegal to assign 'NULL' to a condition information item in a
'SIGNAL' statement.

A 'SIGNAL' statement always specifies an 'SQLSTATE'
value, either directly, or indirectly by referring to a named condition
defined with an 'SQLSTATE' value.  The first two characters of an
'SQLSTATE' value are its class, and the class determines the default
value for the condition information items:

   * Class = ''00'' (success)

     Illegal.  'SQLSTATE' values that begin with ''00'' indicate success
     and are not valid for 'SIGNAL'.

   * Class = ''01'' (warning)

          MESSAGE_TEXT = 'Unhandled user-defined warning condition';
          MYSQL_ERRNO = ER_SIGNAL_WARN

   * Class = ''02'' (not found)

          MESSAGE_TEXT = 'Unhandled user-defined not found condition';
          MYSQL_ERRNO = ER_SIGNAL_NOT_FOUND

   * Class > ''02'' (exception)

          MESSAGE_TEXT = 'Unhandled user-defined exception condition';
          MYSQL_ERRNO = ER_SIGNAL_EXCEPTION

For legal classes, the other condition information items are set as
follows:

     CLASS_ORIGIN = SUBCLASS_ORIGIN = '';
     CONSTRAINT_CATALOG = CONSTRAINT_SCHEMA = CONSTRAINT_NAME = '';
     CATALOG_NAME = SCHEMA_NAME = TABLE_NAME = COLUMN_NAME = '';
     CURSOR_NAME = '';

The error values that are accessible after 'SIGNAL'.
executes are the 'SQLSTATE' value raised by the 'SIGNAL'.
statement and the 'MESSAGE_TEXT' and 'MYSQL_ERRNO' items.  These values
are available from the C API:

   * 'SQLSTATE' value: Call 'mysql_sqlstate()'.

   * 'MYSQL_ERRNO' value: Call 'mysql_errno()'.

   * 'MESSAGE_TEXT' value: Call 'mysql_error()'.

From SQL, the output from 'SHOW WARNINGS' and
'SHOW ERRORS' indicates the 'MYSQL_ERRNO' and
'MESSAGE_TEXT' values in the 'Code' and 'Message' columns.

To retrieve information from the diagnostics area, use the 'GET DIAGNOSTICS'
statement (see get-diagnostics).
For information about the diagnostics area, see
diagnostics-area.

13.6.7.11 Effect of Signals on Handlers, Cursors, and Statements
................................................................

Signals have different effects on statement execution depending on the
signal class.  The class determines how severe an error is.  MySQL
ignores the value of the 'sql_mode' system variable; in particular,
strict SQL mode does not matter.  MySQL also ignores 'IGNORE': The
intent of 'SIGNAL' is to raise a user-generated error
explicitly, so a signal is never ignored.

In the following descriptions, 'unhandled' means that no handler for the
signaled 'SQLSTATE' value has been defined with 'DECLARE ... HANDLER'.

   * Class = ''00'' (success)

     Illegal.  'SQLSTATE' values that begin with ''00'' indicate success
     and are not valid for 'SIGNAL'.

   * Class = ''01'' (warning)

     The value of the 'warning_count' system variable goes up.
     'SHOW WARNINGS' shows the signal.  'SQLWARNING'
     handlers catch the signal.  If the signal is unhandled in a
     function, statements do not end.

   * Class = ''02'' (not found)

     'NOT FOUND' handlers catch the signal.  There is no effect on
     cursors.  If the signal is unhandled in a function, statements end.

   * Class > ''02'' (exception)

     'SQLEXCEPTION' handlers catch the signal.  If the signal is
     unhandled in a function, statements end.

   * Class = ''40''

     Treated as an ordinary exception.

Example:

     mysql> delimiter //
     mysql> CREATE FUNCTION f () RETURNS INT
         -> BEGIN
         ->   SIGNAL SQLSTATE '01234';  -- signal a warning
         ->   RETURN 5;
         -> END//
     mysql> delimiter ;
     mysql> CREATE TABLE t (s1 INT);
     mysql> INSERT INTO t VALUES (f());

The result is that a row containing 5 is inserted into table 't'.  The
warning that is signaled can be viewed with 'SHOW WARNINGS'.

13.6.7.12 Scope Rules for Handlers
..................................

A stored program may include handlers to be invoked when certain
conditions occur within the program.  The applicability of each handler
depends on its location within the program definition and on the
condition or conditions that it handles:

   * A handler declared in a 'BEGIN ... END' block is
     in scope only for the SQL statements following the handler
     declarations in the block.  If the handler itself raises a
     condition, it cannot handle that condition, nor can any other
     handlers declared in the block.  In the following example, handlers
     'H1' and 'H2' are in scope for conditions raised by statements
     STMT1 and STMT2.  But neither 'H1' nor 'H2' are in scope for
     conditions raised in the body of 'H1' or 'H2'.

          BEGIN -- outer block
            DECLARE EXIT HANDLER FOR ...;  -- handler H1
            DECLARE EXIT HANDLER FOR ...;  -- handler H2
            STMT1;
            STMT2;
          END;

   * A handler is in scope only for the block in which it is declared,
     and cannot be activated for conditions occurring outside that
     block.  In the following example, handler 'H1' is in scope for
     STMT1 in the inner block, but not for STMT2 in the outer block:

          BEGIN -- outer block
            BEGIN -- inner block
              DECLARE EXIT HANDLER FOR ...;  -- handler H1
              STMT1;
            END;
            STMT2;
          END;

   * A handler can be specific or general.  A specific handler is for a
     MySQL error code, 'SQLSTATE' value, or condition name.  A general
     handler is for a condition in the 'SQLWARNING', 'SQLEXCEPTION', or
     'NOT FOUND' class.  Condition specificity is related to condition
     precedence, as described later.

Multiple handlers can be declared in different scopes and with different
specificities.  For example, there might be a specific MySQL error code
handler in an outer block, and a general 'SQLWARNING' handler in an
inner block.  Or there might be handlers for a specific MySQL error code
and the general 'SQLWARNING' class in the same block.

Whether a handler is activated depends not only on its own scope and
condition value, but on what other handlers are present.  When a
condition occurs in a stored program, the server searches for applicable
handlers in the current scope (current 'BEGIN ... END'.
block).  If there are no applicable handlers, the search continues
outward with the handlers in each successive containing scope (block).
When the server finds one or more applicable handlers at a given scope,
it chooses among them based on condition precedence:

   * A MySQL error code handler takes precedence over an 'SQLSTATE'
     value handler.

   * An 'SQLSTATE' value handler takes precedence over general
     'SQLWARNING', 'SQLEXCEPTION', or 'NOT FOUND' handlers.

   * An 'SQLEXCEPTION' handler takes precedence over an 'SQLWARNING'
     handler.

   * It is possible to have several applicable handlers with the same
     precedence.  For example, a statement could generate multiple
     warnings with different error codes, for each of which an
     error-specific handler exists.  In this case, the choice of which
     handler the server activates is nondeterministic, and may change
     depending on the circumstances under which the condition occurs.

One implication of the handler selection rules is that if multiple
applicable handlers occur in different scopes, handlers with the most
local scope take precedence over handlers in outer scopes, even over
those for more specific conditions.

If there is no appropriate handler when a condition occurs, the action
taken depends on the class of the condition:

   * For 'SQLEXCEPTION' conditions, the stored program terminates at the
     statement that raised the condition, as if there were an 'EXIT'
     handler.  If the program was called by another stored program, the
     calling program handles the condition using the handler selection
     rules applied to its own handlers.

   * For 'SQLWARNING' conditions, the program continues executing, as if
     there were a 'CONTINUE' handler.

   * For 'NOT FOUND' conditions, if the condition was raised normally,
     the action is 'CONTINUE'.  If it was raised by 'SIGNAL'
     or 'RESIGNAL', the action is 'EXIT'.

The following examples demonstrate how MySQL applies the handler
selection rules.

This procedure contains two handlers, one for the specific 'SQLSTATE'
value (''42S02'') that occurs for attempts to drop a nonexistent table,
and one for the general 'SQLEXCEPTION' class:

     CREATE PROCEDURE p1()
     BEGIN
       DECLARE CONTINUE HANDLER FOR SQLSTATE '42S02'
         SELECT 'SQLSTATE handler was activated' AS msg;
       DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
         SELECT 'SQLEXCEPTION handler was activated' AS msg;

       DROP TABLE test.t;
     END;

Both handlers are declared in the same block and have the same scope.
However, 'SQLSTATE' handlers take precedence over 'SQLEXCEPTION'
handlers, so if the table 't' is nonexistent, the 'DROP TABLE'
statement raises a condition that activates the 'SQLSTATE'
handler:

     mysql> CALL p1();
     +--------------------------------+
     | msg                            |
     +--------------------------------+
     | SQLSTATE handler was activated |
     +--------------------------------+

This procedure contains the same two handlers.  But this time, the
'DROP TABLE' statement and 'SQLEXCEPTION' handler are in an
inner block relative to the 'SQLSTATE' handler:

     CREATE PROCEDURE p2()
     BEGIN -- outer block
         DECLARE CONTINUE HANDLER FOR SQLSTATE '42S02'
           SELECT 'SQLSTATE handler was activated' AS msg;
       BEGIN -- inner block
         DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
           SELECT 'SQLEXCEPTION handler was activated' AS msg;

         DROP TABLE test.t; -- occurs within inner block
       END;
     END;

In this case, the handler that is more local to where the condition
occurs takes precedence.  The 'SQLEXCEPTION' handler activates, even
though it is more general than the 'SQLSTATE' handler:

     mysql> CALL p2();
     +------------------------------------+
     | msg                                |
     +------------------------------------+
     | SQLEXCEPTION handler was activated |
     +------------------------------------+

In this procedure, one of the handlers is declared in a block inner to
the scope of the 'DROP TABLE' statement:

     CREATE PROCEDURE p3()
     BEGIN -- outer block
       DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
         SELECT 'SQLEXCEPTION handler was activated' AS msg;
       BEGIN -- inner block
         DECLARE CONTINUE HANDLER FOR SQLSTATE '42S02'
           SELECT 'SQLSTATE handler was activated' AS msg;
       END;

       DROP TABLE test.t; -- occurs within outer block
     END;

Only the 'SQLEXCEPTION' handler applies because the other one is not in
scope for the condition raised by the 'DROP TABLE'.:

     mysql> CALL p3();
     +------------------------------------+
     | msg                                |
     +------------------------------------+
     | SQLEXCEPTION handler was activated |
     +------------------------------------+

In this procedure, both handlers are declared in a block inner to the
scope of the 'DROP TABLE' statement:

     CREATE PROCEDURE p4()
     BEGIN -- outer block
       BEGIN -- inner block
         DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
           SELECT 'SQLEXCEPTION handler was activated' AS msg;
         DECLARE CONTINUE HANDLER FOR SQLSTATE '42S02'
           SELECT 'SQLSTATE handler was activated' AS msg;
       END;

       DROP TABLE test.t; -- occurs within outer block
     END;

Neither handler applies because they are not in scope for the
'DROP TABLE'.  The condition raised by the statement goes
unhandled and terminates the procedure with an error:

     mysql> CALL p4();
     ERROR 1051 (42S02): Unknown table 'test.t'

13.6.7.13 The MySQL Diagnostics Area
....................................

SQL statements produce diagnostic information that populates the
diagnostics area.  Standard SQL has a diagnostics area stack, containing
a diagnostics area for each nested execution context.  Standard SQL also
supports 'GET STACKED DIAGNOSTICS' syntax for referring to the second
diagnostics area during condition handler execution.  MySQL supports the
'STACKED' keyword as of MySQL 5.7.  Before that, MySQL does not support
'STACKED'; there is a single diagnostics area containing information
from the most recent statement that wrote to it.

This section describes the structure of the diagnostics area in MySQL,
the information items recognized by MySQL, how statements clear and set
the diagnostics area, and how diagnostics areas are pushed to and popped
from the stack.

13.6.7.14 Diagnostics Area Structure
....................................

The diagnostics area contains two kinds of information:

   * Statement information, such as the number of conditions that
     occurred or the affected-rows count.

   * Condition information, such as the error code and message.  If a
     statement raises multiple conditions, this part of the diagnostics
     area has a condition area for each one.  If a statement raises no
     conditions, this part of the diagnostics area is empty.

For a statement that produces three conditions, the diagnostics area
contains statement and condition information like this:

     Statement information:
       row count
       ... other statement information items ...
     Condition area list:
       Condition area 1:
         error code for condition 1
         error message for condition 1
         ... other condition information items ...
       Condition area 2:
         error code for condition 2:
         error message for condition 2
         ... other condition information items ...
       Condition area 3:
         error code for condition 3
         error message for condition 3
         ... other condition information items ...

13.6.7.15 Diagnostics Area Information Items
............................................

The diagnostics area contains statement and condition information items.
Numeric items are integers.  The character set for character items is
UTF-8.  No item can be 'NULL'.  If a statement or condition item is not
set by a statement that populates the diagnostics area, its value is 0
or the empty string, depending on the item data type.

The statement information part of the diagnostics area contains these
items:

   * 'NUMBER': An integer indicating the number of condition areas that
     have information.

   * 'ROW_COUNT': An integer indicating the number of rows affected by
     the statement.  'ROW_COUNT' has the same value as the 'ROW_COUNT()'
     function (see information-functions).

The condition information part of the diagnostics area contains a
condition area for each condition.  Condition areas are numbered from 1
to the value of the 'NUMBER' statement condition item.  If 'NUMBER' is
0, there are no condition areas.

Each condition area contains the items in the following list.  All items
are standard SQL except 'MYSQL_ERRNO', which is a MySQL extension.  The
definitions apply for conditions generated other than by a signal (that
is, by a 'SIGNAL' or 'RESIGNAL'.
statement).  For nonsignal conditions, MySQL populates only those
condition items not described as always empty.  The effects of signals
on the condition area are described later.

   * 'CLASS_ORIGIN': A string containing the class of the
     'RETURNED_SQLSTATE' value.  If the 'RETURNED_SQLSTATE' value begins
     with a class value defined in SQL standards document ISO 9075-2
     (section 24.1, SQLSTATE), 'CLASS_ORIGIN' is ''ISO 9075''.
     Otherwise, 'CLASS_ORIGIN' is ''MySQL''.

   * 'SUBCLASS_ORIGIN': A string containing the subclass of the
     'RETURNED_SQLSTATE' value.  If 'CLASS_ORIGIN' is ''ISO 9075'' or
     'RETURNED_SQLSTATE' ends with ''000'', 'SUBCLASS_ORIGIN' is ''ISO
     9075''.  Otherwise, 'SUBCLASS_ORIGIN' is ''MySQL''.

   * 'RETURNED_SQLSTATE': A string that indicates the 'SQLSTATE' value
     for the condition.

   * 'MESSAGE_TEXT': A string that indicates the error message for the
     condition.

   * 'MYSQL_ERRNO': An integer that indicates the MySQL error code for
     the condition.

   * 'CONSTRAINT_CATALOG', 'CONSTRAINT_SCHEMA', 'CONSTRAINT_NAME':
     Strings that indicate the catalog, schema, and name for a violated
     constraint.  They are always empty.

   * 'CATALOG_NAME', 'SCHEMA_NAME', 'TABLE_NAME', 'COLUMN_NAME': Strings
     that indicate the catalog, schema, table, and column related to the
     condition.  They are always empty.

   * 'CURSOR_NAME': A string that indicates the cursor name.  This is
     always empty.

For the 'RETURNED_SQLSTATE', 'MESSAGE_TEXT', and 'MYSQL_ERRNO' values
for particular errors, see error-messages-server.

If a 'SIGNAL'. (or 'RESIGNAL') statement
populates the diagnostics area, its 'SET' clause can assign to any
condition information item except 'RETURNED_SQLSTATE' any value that is
legal for the item data type.  'SIGNAL' also sets the
'RETURNED_SQLSTATE' value, but not directly in its 'SET' clause.  That
value comes from the 'SIGNAL' statement 'SQLSTATE'
argument.

'SIGNAL' also sets statement information items.  It sets
'NUMBER' to 1.  It sets 'ROW_COUNT' to −1 for errors and 0 otherwise.

13.6.7.16 How the Diagnostics Area is Populated
...............................................

Nondiagnostic SQL statements populate the diagnostics area
automatically, and its contents can be set explicitly with the
'SIGNAL' and 'RESIGNAL' statements.  The
diagnostics area can be examined with 'GET DIAGNOSTICS'
to extract specific items, or with 'SHOW WARNINGS'
or 'SHOW ERRORS' to see
conditions or errors.

SQL statements clear and set the diagnostics area as follows:

   * When the server starts executing a statement after parsing it, it
     clears the diagnostics area for nondiagnostic statements.  (Before
     MySQL 5.7.2, the server clears the diagnostics area for
     nondiagnostic statements that use tables.)  Diagnostic statements
     do not clear the diagnostics area (see 'SHOW WARNINGS',
     see 'SHOW ERRORS', 'GET DIAGNOSTICS').

   * If a statement raises a condition, the diagnostics area is cleared
     of conditions that belong to earlier statements.  The exception is
     that conditions raised by 'GET DIAGNOSTICS'.
     and 'RESIGNAL' are added to the diagnostics area
     without clearing it.

Thus, even a statement that does not normally clear the diagnostics area
when it begins executing clears it if the statement raises a condition.

The following example shows the effect of various statements on the
diagnostics area, using 'SHOW WARNINGS' to display
information about conditions stored there.

This 'DROP TABLE' statement clears the diagnostics
area and populates it when the condition occurs:

     mysql> DROP TABLE IF EXISTS test.no_such_table;
     Query OK, 0 rows affected, 1 warning (0.01 sec)

     mysql> SHOW WARNINGS;
     +-------+------+------------------------------------+
     | Level | Code | Message                            |
     +-------+------+------------------------------------+
     | Note  | 1051 | Unknown table 'test.no_such_table' |
     +-------+------+------------------------------------+
     1 row in set (0.00 sec)

This 'SET' statement generates an error, so it
clears and populates the diagnostics area:

     mysql> SET @x = @@x;
     ERROR 1193 (HY000): Unknown system variable 'x'

     mysql> SHOW WARNINGS;
     +-------+------+-----------------------------+
     | Level | Code | Message                     |
     +-------+------+-----------------------------+
     | Error | 1193 | Unknown system variable 'x' |
     +-------+------+-----------------------------+
     1 row in set (0.00 sec)

The previous 'SET' statement produced a single
condition, so 1 is the only valid condition number for 'GET DIAGNOSTICS'
at this point.  The following statement
uses a condition number of 2, which produces a warning that is added to
the diagnostics area without clearing it:

     mysql> GET DIAGNOSTICS CONDITION 2 @p = MESSAGE_TEXT;
     Query OK, 0 rows affected, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS;
     +-------+------+------------------------------+
     | Level | Code | Message                      |
     +-------+------+------------------------------+
     | Error | 1193 | Unknown system variable 'xx' |
     | Error | 1753 | Invalid condition number     |
     +-------+------+------------------------------+
     2 rows in set (0.00 sec)

Now there are two conditions in the diagnostics area, so the same
'GET DIAGNOSTICS' statement succeeds:

     mysql> GET DIAGNOSTICS CONDITION 2 @p = MESSAGE_TEXT;
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @p;
     +--------------------------+
     | @p                       |
     +--------------------------+
     | Invalid condition number |
     +--------------------------+
     1 row in set (0.01 sec)

13.6.7.17 How the Diagnostics Area Stack Works
..............................................

When a push to the diagnostics area stack occurs, the first (current)
diagnostics area becomes the second (stacked) diagnostics area and a new
current diagnostics area is created as a copy of it.  Diagnostics areas
are pushed to and popped from the stack under the following
circumstances:

   * Execution of a stored program

     A push occurs before the program executes and a pop occurs
     afterward.  If the stored program ends while handlers are
     executing, there can be more than one diagnostics area to pop; this
     occurs due to an exception for which there are no appropriate
     handlers or due to 'RETURN' in the handler.

     Any warning or error conditions occurring during stored program
     execution then are added to the current diagnostics area, except
     that, for triggers, only errors are added.  When the stored program
     ends, the caller sees these conditions in its current diagonstics
     area.

   * Execution of a condition handler within a stored program

     When a push occurs as a result of condition handler activation, the
     stacked diagnostics area is the area that was current within the
     stored program prior to the push.  The new now-current diagnostics
     area is the handler's current diagnostics area.  'GET [CURRENT] DIAGNOSTICS'
     and 'GET STACKED DIAGNOSTICS'
     can be used within the handler to
     access the contents of the current (handler) and stacked (stored
     program) diagnostics areas.  Initially, they return the same
     result, but statements executing within the handler modify the
     current diagnostics area, clearing and setting its contents
     according to the normal rules (see
     diagnostics-area-populating).  The stacked diagnostics area
     cannot be modified by statements executing within the handler
     except 'RESIGNAL'.

     If the handler executes successfully, the current (handler)
     diagnostics area is popped and the stacked (stored program)
     diagnostics area again becomes the current diagnostics area.
     Conditions added to the handler diagnostics area during handler
     execution are added to the current diagnostics area.

   * Execution of 'RESIGNAL'.

     The 'RESIGNAL' statement passes on the error
     condition information that is available during execution of a
     condition handler within a compound statement inside a stored
     program.  'RESIGNAL' may change some or all
     information before passing it on, modifying the diagnostics stack
     as described in resignal.

13.6.7.18 Diagnostics Area-Related System Variables
...................................................

Certain system variables control or are related to some aspects of the
diagnostics area:

   * 'max_error_count' controls the number of condition areas in the
     diagnostics area.  If more conditions than this occur, MySQL
     silently discards information for the excess conditions.
     (Conditions added by 'RESIGNAL' are always added,
     with older conditions being discarded as necessary to make room.)

   * 'warning_count' indicates the number of conditions that occurred.
     This includes errors, warnings, and notes.  Normally, 'NUMBER' and
     'warning_count' are the same.  However, as the number of conditions
     generated exceeds 'max_error_count', the value of 'warning_count'
     continues to rise whereas 'NUMBER' remains capped at
     'max_error_count' because no additional conditions are stored in
     the diagnostics area.

   * 'error_count' indicates the number of errors that occurred.  This
     value includes 'not found' and exception conditions, but excludes
     warnings and notes.  Like 'warning_count', its value can exceed
     'max_error_count'.

   * If the 'sql_notes' system variable is set to 0, notes are not
     stored and do not increment 'warning_count'.

Example: If 'max_error_count' is 10, the diagnostics area can contain a
maximum of 10 condition areas.  Suppose that a statement raises 20
conditions, 12 of which are errors.  In that case, the diagnostics area
contains the first 10 conditions, 'NUMBER' is 10, 'warning_count' is 20,
and 'error_count' is 12.

Changes to the value of 'max_error_count' have no effect until the next
attempt to modify the diagnostics area.  If the diagnostics area
contains 10 condition areas and 'max_error_count' is set to 5, that has
no immediate effect on the size or content of the diagnostics area.

13.7 Database Administration Statements
=======================================

13.7.1 Account Management Statements
------------------------------------

MySQL account information is stored in the tables of the 'mysql'
database.  This database and the access control system are discussed
extensively in server-administration, which you should consult
for additional details.

*Important*:

Some MySQL releases introduce changes to the structure of the grant
tables to add new privileges or features.  To make sure that you can
take advantage of any new capabilities, update your grant tables to have
the current structure whenever you upgrade MySQL. See
mysql-upgrade.

When the 'read_only' system variable is enabled, account-management
statements require the 'SUPER' privilege, in addition to any other
required privileges.  This is because they modify tables in the 'mysql'
database.

13.7.1.1 ALTER USER Syntax
..........................

     ALTER USER [IF EXISTS]
         USER [AUTH_OPTION] [, USER [AUTH_OPTION]] ...
         [REQUIRE {NONE | TLS_OPTION [[AND] TLS_OPTION] ...}]
         [WITH RESOURCE_OPTION [RESOURCE_OPTION] ...]
         [PASSWORD_OPTION | LOCK_OPTION] ...

     ALTER USER [IF EXISTS]
         USER() IDENTIFIED BY 'AUTH_STRING'

     USER:
         (see account-names)

     AUTH_OPTION: {
         IDENTIFIED BY 'AUTH_STRING'
       | IDENTIFIED WITH AUTH_PLUGIN
       | IDENTIFIED WITH AUTH_PLUGIN BY 'AUTH_STRING'
       | IDENTIFIED WITH AUTH_PLUGIN AS 'HASH_STRING'
     }

     TLS_OPTION: {
        SSL
      | X509
      | CIPHER 'CIPHER'
      | ISSUER 'ISSUER'
      | SUBJECT 'SUBJECT'
     }

     RESOURCE_OPTION: {
         MAX_QUERIES_PER_HOUR COUNT
       | MAX_UPDATES_PER_HOUR COUNT
       | MAX_CONNECTIONS_PER_HOUR COUNT
       | MAX_USER_CONNECTIONS COUNT
     }

     PASSWORD_OPTION: {
         PASSWORD EXPIRE
       | PASSWORD EXPIRE DEFAULT
       | PASSWORD EXPIRE NEVER
       | PASSWORD EXPIRE INTERVAL N DAY
     }

     LOCK_OPTION: {
         ACCOUNT LOCK
       | ACCOUNT UNLOCK
     }

The 'ALTER USER' statement modifies MySQL accounts.
It enables authentication, SSL/TLS, resource-limit, and
password-management properties to be modified for existing accounts, and
enables account locking and unlocking.

To use 'ALTER USER', you must have the global 'CREATE
USER' privilege or the 'UPDATE' privilege for the 'mysql' database.
When the 'read_only' system variable is enabled, see 'ALTER USER'
additionally requires the 'SUPER' privilege.

By default, an error occurs if you try to modify a user that does not
exist.  If the 'IF EXISTS' clause is given, the statement produces a
warning for each named user that does not exist, rather than an error.

*Important*:

Under some circumstances, see 'ALTER USER' may be
recorded in server logs or on the client side in a history file such as
'~/.mysql_history', which means that cleartext passwords may be read by
anyone having read access to that information.  For information about
the conditions under which this occurs for the server logs and how to
control it, see password-logging.  For similar information about
client-side logging, see mysql-logging.

There are several aspects to the 'ALTER USER'.
statement, described under the following topics:

   * alter-user-overview

   * alter-user-authentication

   * alter-user-tls

   * alter-user-resource-limits

   * alter-user-password-management

   * alter-user-account-locking

*ALTER USER Overview*

For each affected account, see 'ALTER USER' modifies the
corresponding 'mysql.user' table row to reflect the properties specified
in the statement.  Unspecified properties retain their current values.

Example 1: Change an account's password and expire it.  As a result, the
user must connect with the named password and choose a new one at the
next connection:

     ALTER USER 'jeffrey'@'localhost'
       IDENTIFIED BY 'NEW_PASSWORD' PASSWORD EXPIRE;

Example 2: Modify an account to use the 'sha256_password' authentication
plugin and the given password.  Require that a new password be chosen
every 180 days:

     ALTER USER 'jeffrey'@'localhost'
       IDENTIFIED WITH sha256_password BY 'NEW_PASSWORD'
       PASSWORD EXPIRE INTERVAL 180 DAY;

Example 3: Lock or unlock an account:

     ALTER USER 'jeffrey'@'localhost' ACCOUNT LOCK;
     ALTER USER 'jeffrey'@'localhost' ACCOUNT UNLOCK;

Example 4: Require an account to connect using SSL and establish a limit
of 20 connections per hour:

     ALTER USER 'jeffrey'@'localhost'
       REQUIRE SSL WITH MAX_CONNECTIONS_PER_HOUR 20;

Each account name uses the format described in account-names.
The host name part of the account name, if omitted, defaults to ''%''.
It is also possible to specify 'CURRENT_USER' or 'CURRENT_USER()' to
refer to the account associated with the current session.

For one syntax only, the account may be specified with the 'USER()'
function:

     ALTER USER USER() IDENTIFIED BY 'AUTH_STRING';

This syntax enables changing your own password without naming your
account literally.

For 'ALTER USER' syntaxes that permit an AUTH_OPTION
value to follow a USER value, AUTH_OPTION indicates how the account
authenticates by specifying an account authentication plugin,
credentials (for example, a password), or both.  Each AUTH_OPTION value
applies _only_ to the account named immediately preceding it.

Following the USER specifications, the statement may include options for
SSL/TLS, resource-limit, password-management, and locking properties.
All such options are _global_ to the statement and apply to _all_ named
accounts.

Example: This statement alters two accounts, specifying some per-account
properties and some global properties:

     ALTER USER
       'jeffrey'@'localhost' IDENTIFIED BY 'NEW_PASSWORD',
       'jeanne'@'localhost'
       REQUIRE SSL WITH MAX_USER_CONNECTIONS 2;

The AUTH_OPTION value following 'jeffrey' ('IDENTIFIED BY') applies only
to its immediately preceding account, so it changes the password only
for 'jeffrey'.  For 'jeanne', there is no per-account value (thus
leaving the password unchanged).  The remaining properties apply
globally to the statement.  For both accounts, connections are required
to use SSL and each account can be used for a maximum of two
simultaneous connections:

In the absence of a particular type of option, the account remains
unchanged in that respect.  For example, with no locking option, the
locking state of the account is not changed.

*ALTER USER Authentication Options*

An account name may be followed by an AUTH_OPTION authentication option
that specifies the account authentication plugin, credentials, or both:

   * AUTH_PLUGIN names an authentication plugin.  The plugin name can be
     a quoted string literal or an unquoted name.  Plugin names are
     stored in the 'plugin' column of the 'mysql.user' system table.

     For AUTH_OPTION syntaxes that do not specify an authentication
     plugin, the default plugin is indicated by the value of the
     'default_authentication_plugin' system variable.  For descriptions
     of each plugin, see authentication-plugins.

   * Credentials are stored in the 'authentication_string' column of the
     'mysql.user' system table.  An ''AUTH_STRING'' or ''HASH_STRING''
     value specifies account credentials, either as a cleartext
     (unencrypted) string or hashed in the format expected by the
     authentication plugin associated with the account, respectively:

        * For syntaxes that use ''AUTH_STRING'', the string is cleartext
          and is passed to the authentication plugin for possible
          hashing.  The result returned by the plugin is stored in the
          'authentication_string' column.  A plugin may use the value as
          specified, in which case no hashing occurs.

        * For syntaxes that use ''HASH_STRING'', the string is assumed
          to be already hashed in the format required by the
          authentication plugin.  If the hash format is inappropriate
          for the plugin, it will not be usable and correct
          authentication of client connections will not occur.

'ALTER USER' permits these AUTH_OPTION syntaxes:

   * 'IDENTIFIED BY 'AUTH_STRING''

     Sets the account authentication plugin to the default plugin,
     passes the cleartext ''AUTH_STRING'' value to the plugin for
     hashing, and stores the result in the 'mysql.user' account row.

   * 'IDENTIFIED WITH AUTH_PLUGIN'

     Sets the account authentication plugin to AUTH_PLUGIN, clears the
     credentials to the empty string (the credentials are associated
     with the old authentication plugin, not the new one), and stores
     the result in the 'mysql.user' account row.

     In addition, the password is marked expired.  The user must choose
     a new one when next connecting.

   * 'IDENTIFIED WITH AUTH_PLUGIN BY 'AUTH_STRING''

     Sets the account authentication plugin to AUTH_PLUGIN, passes the
     cleartext ''AUTH_STRING'' value to the plugin for hashing, and
     stores the result in the 'mysql.user' account row.

   * 'IDENTIFIED WITH AUTH_PLUGIN AS 'HASH_STRING''

     Sets the account authentication plugin to AUTH_PLUGIN and stores
     the hashed ''HASH_STRING'' value as is in the 'mysql.user' account
     row.  The string is assumed to be already hashed in the format
     required by the plugin.

Example 1: Specify the password as cleartext; the default plugin is
used:

     ALTER USER 'jeffrey'@'localhost'
       IDENTIFIED BY 'PASSWORD';

Example 2: Specify the authentication plugin, along with a cleartext
password value:

     ALTER USER 'jeffrey'@'localhost'
       IDENTIFIED WITH mysql_native_password
                  BY 'PASSWORD';

Example 3: Specify the authentication plugin, along with a hashed
password value:

     ALTER USER 'jeffrey'@'localhost'
       IDENTIFIED WITH mysql_native_password
                  AS '*6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4';

For additional information about setting passwords and authentication
plugins, see assigning-passwords, and
pluggable-authentication.

*ALTER USER SSL/TLS Options*

MySQL can check X509 certificate attributes in addition to the usual
authentication that is based on the user name and credentials.  For
background information on the use of SSL/TLS with MySQL, see
encrypted-connections.

To specify SSL/TLS-related options for a MySQL account, use a 'REQUIRE'
clause that specifies one or more TLS_OPTION values.

Order of 'REQUIRE' options does not matter, but no option can be
specified twice.  The 'AND' keyword is optional between 'REQUIRE'
options.

'ALTER USER' permits these TLS_OPTION values:

   * 'NONE'

     Indicates that the account has no SSL or X509 requirements.
     Unencrypted connections are permitted if the user name and password
     are valid.  Encrypted connections can be used, at the client's
     option, if the client has the proper certificate and key files.

          ALTER USER 'jeffrey'@'localhost' REQUIRE NONE;

     Clients attempt to establish a secure connection by default.  For
     clients that have 'REQUIRE NONE', the connection attempt falls back
     to an unencrypted connection if a secure connection cannot be
     established.  To require an encrypted connection, a client need
     specify only the '--ssl-mode=REQUIRED' option; the connection
     attempt fails if a secure connection cannot be established.

   * 'SSL'

     Tells the server to permit only encrypted connections for the
     account.

          ALTER USER 'jeffrey'@'localhost' REQUIRE SSL;

     Clients attempt to establish a secure connection by default.  For
     accounts that have 'REQUIRE SSL', the connection attempt fails if a
     secure connection cannot be established.

   * 'X509'

     Requires that clients present a valid certificate, but the exact
     certificate, issuer, and subject do not matter.  The only
     requirement is that it should be possible to verify its signature
     with one of the CA certificates.  Use of X509 certificates always
     implies encryption, so the 'SSL' option is unnecessary in this
     case.

          ALTER USER 'jeffrey'@'localhost' REQUIRE X509;

     For accounts with 'REQUIRE X509', clients must specify the
     '--ssl-key' and '--ssl-cert' options to connect.  (It is
     recommended but not required that '--ssl-ca' also be specified so
     that the public certificate provided by the server can be
     verified.)  This is true for 'ISSUER' and 'SUBJECT' as well because
     those 'REQUIRE' options imply the requirements of 'X509'.

   * 'ISSUER 'ISSUER''

     Requires that clients present a valid X509 certificate issued by CA
     ''ISSUER''.  If a client presents a certificate that is valid but
     has a different issuer, the server rejects the connection.  Use of
     X509 certificates always implies encryption, so the 'SSL' option is
     unnecessary in this case.

          ALTER USER 'jeffrey'@'localhost'
            REQUIRE ISSUER '/C=SE/ST=Stockholm/L=Stockholm/
              O=MySQL/CN=CA/emailAddress=ca@example.com';

     Because 'ISSUER' implies the requirements of 'X509', clients must
     specify the '--ssl-key' and '--ssl-cert' options to connect.  (It
     is recommended but not required that '--ssl-ca' also be specified
     so that the public certificate provided by the server can be
     verified.)

   * 'SUBJECT 'SUBJECT''

     Requires that clients present a valid X509 certificate containing
     the subject SUBJECT.  If a client presents a certificate that is
     valid but has a different subject, the server rejects the
     connection.  Use of X509 certificates always implies encryption, so
     the 'SSL' option is unnecessary in this case.

          ALTER USER 'jeffrey'@'localhost'
            REQUIRE SUBJECT '/C=SE/ST=Stockholm/L=Stockholm/
              O=MySQL demo client certificate/
              CN=client/emailAddress=client@example.com';

     MySQL does a simple string comparison of the ''SUBJECT'' value to
     the value in the certificate, so lettercase and component ordering
     must be given exactly as present in the certificate.

     Because 'SUBJECT' implies the requirements of 'X509', clients must
     specify the '--ssl-key' and '--ssl-cert' options to connect.  (It
     is recommended but not required that '--ssl-ca' also be specified
     so that the public certificate provided by the server can be
     verified.)

   * 'CIPHER 'CIPHER''

     Requires a specific cipher method for encrypting connections.  This
     option is needed to ensure that ciphers and key lengths of
     sufficient strength are used.  Encryption can be weak if old
     algorithms using short encryption keys are used.

          ALTER USER 'jeffrey'@'localhost'
            REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';

The 'SUBJECT', 'ISSUER', and 'CIPHER' options can be combined in the
'REQUIRE' clause:

     ALTER USER 'jeffrey'@'localhost'
       REQUIRE SUBJECT '/C=SE/ST=Stockholm/L=Stockholm/
         O=MySQL demo client certificate/
         CN=client/emailAddress=client@example.com'
       AND ISSUER '/C=SE/ST=Stockholm/L=Stockholm/
         O=MySQL/CN=CA/emailAddress=ca@example.com'
       AND CIPHER 'EDH-RSA-DES-CBC3-SHA';

*ALTER USER Resource-Limit Options*

It is possible to place limits on use of server resources by an account,
as discussed in user-resources.  To do so, use a 'WITH' clause
that specifies one or more RESOURCE_OPTION values.

Order of 'WITH' options does not matter, except that if a given resource
limit is specified multiple times, the last instance takes precedence.

'ALTER USER' permits these RESOURCE_OPTION values:

   * 'MAX_QUERIES_PER_HOUR COUNT', 'MAX_UPDATES_PER_HOUR COUNT',
     'MAX_CONNECTIONS_PER_HOUR COUNT'

     These options restrict how many queries, updates, and connections
     to the server are permitted to this account during any given
     one-hour period.  (Queries for which results are served from the
     query cache do not count against the 'MAX_QUERIES_PER_HOUR' limit.)
     If COUNT is '0' (the default), this means that there is no
     limitation for the account.

   * 'MAX_USER_CONNECTIONS COUNT'

     Restricts the maximum number of simultaneous connections to the
     server by the account.  A nonzero COUNT specifies the limit for the
     account explicitly.  If COUNT is '0' (the default), the server
     determines the number of simultaneous connections for the account
     from the global value of the 'max_user_connections' system
     variable.  If 'max_user_connections' is also zero, there is no
     limit for the account.

Example:

     ALTER USER 'jeffrey'@'localhost'
       WITH MAX_QUERIES_PER_HOUR 500 MAX_UPDATES_PER_HOUR 100;

*ALTER USER Password-Management Options*

'ALTER USER' supports several PASSWORD_OPTION values
for password expiration management, to either expire an account password
manually or establish its password expiration policy.  Policy options do
not expire the password.  Instead, they determine how the server applies
automatic expiration to the account based on account password age.  For
a given account, its password age is assessed from the date and time of
the most recent password change.

These options apply to accounts that use a MySQL built-in authentication
plugin ('mysql_native_password' or 'caching_sha2_password').  For
accounts that use plugins that perform authentication against an
external credential system, password expiration must be handled
externally as well.  For information about password management policy,
see password-management.

A client session operates in restricted mode if the account password was
expired manually or if the password age is considered greater than its
permitted lifetime per the automatic expiration policy.  In restricted
mode, operations performed within the session result in an error until
the user establishes a new account password.  For information about
restricted mode, see expired-password-handling.

'ALTER USER' permits these PASSWORD_OPTION values:

   * 'PASSWORD EXPIRE'

     Immediately expires the account password.

          ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE;

   * 'PASSWORD EXPIRE DEFAULT'

     Sets the account so that the global expiration policy applies, as
     specified by the 'default_password_lifetime' system variable.

          ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE DEFAULT;

   * 'PASSWORD EXPIRE NEVER'

     Disables password expiration for the account so that its password
     never expires.

          ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE NEVER;

   * 'PASSWORD EXPIRE INTERVAL N DAY'

     Sets the account password lifetime to N days.  This statement
     requires the password to be changed every 180 days:

          ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE INTERVAL 180 DAY;

If multiple password-management options are specified, the last one
takes precedence.

*Note*:

It is possible to 'reset' a password by setting it to its current value.
As a matter of good policy, it is preferable to choose a different
password.

*ALTER USER Account-Locking Options*

MySQL supports account locking and unlocking using the 'ACCOUNT LOCK'
and 'ACCOUNT UNLOCK' options, which specify the locking state for an
account.  For additional discussion, see account-locking.

If multiple account-locking options are specified, the last one takes
precedence.

13.7.1.2 CREATE USER Syntax
...........................

     CREATE USER [IF NOT EXISTS]
         USER [AUTH_OPTION] [, USER [AUTH_OPTION]] ...
         [REQUIRE {NONE | TLS_OPTION [[AND] TLS_OPTION] ...}]
         [WITH RESOURCE_OPTION [RESOURCE_OPTION] ...]
         [PASSWORD_OPTION | LOCK_OPTION] ...

     USER:
         (see account-names)

     AUTH_OPTION: {
         IDENTIFIED BY 'AUTH_STRING'
       | IDENTIFIED WITH AUTH_PLUGIN
       | IDENTIFIED WITH AUTH_PLUGIN BY 'AUTH_STRING'
       | IDENTIFIED WITH AUTH_PLUGIN AS 'HASH_STRING'
       | IDENTIFIED BY PASSWORD 'HASH_STRING'
     }

     TLS_OPTION: {
        SSL
      | X509
      | CIPHER 'CIPHER'
      | ISSUER 'ISSUER'
      | SUBJECT 'SUBJECT'
     }

     RESOURCE_OPTION: {
         MAX_QUERIES_PER_HOUR COUNT
       | MAX_UPDATES_PER_HOUR COUNT
       | MAX_CONNECTIONS_PER_HOUR COUNT
       | MAX_USER_CONNECTIONS COUNT
     }

     PASSWORD_OPTION: {
         PASSWORD EXPIRE
       | PASSWORD EXPIRE DEFAULT
       | PASSWORD EXPIRE NEVER
       | PASSWORD EXPIRE INTERVAL N DAY
     }

     LOCK_OPTION: {
         ACCOUNT LOCK
       | ACCOUNT UNLOCK
     }

The 'CREATE USER' statement creates new MySQL
accounts.  It enables authentication, SSL/TLS, resource-limit, and
password-management properties to be established for new accounts, and
controls whether accounts are initially locked or unlocked.

To use 'CREATE USER', you must have the global
'CREATE USER' privilege, or the 'INSERT' privilege for the 'mysql'
database.  When the 'read_only' system variable is enabled, see
'CREATE USER' additionally requires the 'SUPER' privilege.

An error occurs if you try to create an account that already exists.  If
the 'IF NOT EXISTS' clause is given, the statement produces a warning
for each named account that already exists, rather than an error.

*Important*:

Under some circumstances, see 'CREATE USER' may be
recorded in server logs or on the client side in a history file such as
'~/.mysql_history', which means that cleartext passwords may be read by
anyone having read access to that information.  For information about
the conditions under which this occurs for the server logs and how to
control it, see password-logging.  For similar information about
client-side logging, see mysql-logging.

There are several aspects to the 'CREATE USER'.
statement, described under the following topics:

   * create-user-overview

   * create-user-authentication

   * create-user-tls

   * create-user-resource-limits

   * create-user-password-management

   * create-user-account-locking

*CREATE USER Overview*

For each account, see 'CREATE USER' creates a new row in
the 'mysql.user' system table.  The account row reflects the properties
specified in the statement.  Unspecified properties are set to their
default values:

   * Authentication: The authentication plugin defined by the
     'default_authentication_plugin' system variable, and empty
     credentials

   * SSL/TLS: 'NONE'

   * Resource limits: Unlimited

   * Password management: 'PASSWORD EXPIRE DEFAULT'

   * Account locking: 'ACCOUNT UNLOCK'

An account when first created has no privileges.  To assign privileges,
use the 'GRANT' statement.

Example 1: Create an account that uses the default authentication plugin
and the given password.  Mark the password expired so that the user must
choose a new one at the first connection to the server:

     CREATE USER 'jeffrey'@'localhost'
       IDENTIFIED BY 'NEW_PASSWORD' PASSWORD EXPIRE;

Example 2: Create an account that uses the 'sha256_password'
authentication plugin and the given password.  Require that a new
password be chosen every 180 days:

     CREATE USER 'jeffrey'@'localhost'
       IDENTIFIED WITH sha256_password BY 'NEW_PASSWORD'
       PASSWORD EXPIRE INTERVAL 180 DAY;

Each account name uses the format described in account-names.
For example:

     CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'PASSWORD';

The host name part of the account name, if omitted, defaults to ''%''.

Each USER value naming an account may be followed by an optional
AUTH_OPTION value that indicates how the account authenticates.  These
values enable account authentication plugins and credentials (for
example, a password) to be specified.  Each AUTH_OPTION value applies
_only_ to the account named immediately preceding it.

Following the USER specifications, the statement may include options for
SSL/TLS, resource-limit, password-management, and locking properties.
All such options are _global_ to the statement and apply to _all_ named
accounts.

Example: This statement creates two accounts, specifying some
per-account properties and some global properties:

     CREATE USER
       'jeffrey'@'localhost' IDENTIFIED WITH mysql_native_password
                                        BY 'NEW_PASSWORD1',
       'jeanne'@'localhost' IDENTIFIED WITH sha256_password
                                       BY 'NEW_PASSWORD2'
       REQUIRE X509 WITH MAX_QUERIES_PER_HOUR 60
       ACCOUNT LOCK;

Each AUTH_OPTION value ('IDENTIFIED WITH ... BY' in this case) applies
only to its immediately preceding account, so each account uses the
named authentication plugin and password.  The remaining properties
apply globally to the statement.  For both accounts, connections must be
made using a valid X509 certificate and up to 60 queries per hour are
permitted.  Both accounts are locked initially, so effectively they are
placeholders and cannot be used until an administrator unlocks them.

*CREATE USER Authentication Options*

An account name may be followed by an AUTH_OPTION authentication option
that specifies the account authentication plugin, credentials, or both:

   * AUTH_PLUGIN names an authentication plugin.  The plugin name can be
     a quoted string literal or an unquoted name.  Plugin names are
     stored in the 'plugin' column of the 'mysql.user' system table.

     For AUTH_OPTION syntaxes that do not specify an authentication
     plugin, the default plugin is indicated by the value of the
     'default_authentication_plugin' system variable.  For descriptions
     of each plugin, see authentication-plugins.

   * Credentials are stored in the 'authentication_string' column of the
     'mysql.user' system table.  An ''AUTH_STRING'' or ''HASH_STRING''
     value specifies account credentials, either as a cleartext
     (unencrypted) string or hashed in the format expected by the
     authentication plugin associated with the account, respectively:

        * For syntaxes that use ''AUTH_STRING'', the string is cleartext
          and is passed to the authentication plugin for possible
          hashing.  The result returned by the plugin is stored in the
          'authentication_string' column.  A plugin may use the value as
          specified, in which case no hashing occurs.

        * For syntaxes that use ''HASH_STRING'', the string is assumed
          to be already hashed in the format required by the
          authentication plugin.  If the hash format is inappropriate
          for the plugin, it will not be usable and correct
          authentication of client connections will not occur.

'CREATE USER' permits these AUTH_OPTION syntaxes:

   * 'IDENTIFIED BY 'AUTH_STRING''

     Sets the account authentication plugin to the default plugin,
     passes the cleartext ''AUTH_STRING'' value to the plugin for
     hashing, and stores the result in the 'mysql.user' account row.

   * 'IDENTIFIED WITH AUTH_PLUGIN'

     Sets the account authentication plugin to AUTH_PLUGIN, clears the
     credentials to the empty string, and stores the result in the
     'mysql.user' account row.

   * 'IDENTIFIED WITH AUTH_PLUGIN BY 'AUTH_STRING''

     Sets the account authentication plugin to AUTH_PLUGIN, passes the
     cleartext ''AUTH_STRING'' value to the plugin for hashing, and
     stores the result in the 'mysql.user' account row.

   * 'IDENTIFIED WITH AUTH_PLUGIN AS 'HASH_STRING''

     Sets the account authentication plugin to AUTH_PLUGIN and stores
     the hashed ''HASH_STRING'' value as is in the 'mysql.user' account
     row.  The string is assumed to be already hashed in the format
     required by the plugin.

   * 'IDENTIFIED BY PASSWORD 'HASH_STRING''

     Sets the account authentication plugin to the default plugin and
     stores the hashed ''HASH_STRING'' value as is in the 'mysql.user'
     account row.  The string is assumed to be already hashed in the
     format required by the plugin.

     *Note*:

     'IDENTIFIED BY PASSWORD' syntax is deprecated and will be removed
     in a future MySQL release.

Example 1: Specify the password as cleartext; the default plugin is
used:

     CREATE USER 'jeffrey'@'localhost'
       IDENTIFIED BY 'PASSWORD';

Example 2: Specify the authentication plugin, along with a cleartext
password value:

     CREATE USER 'jeffrey'@'localhost'
       IDENTIFIED WITH mysql_native_password BY 'PASSWORD';

In each case, the password value stored in the account row is the
cleartext value ''PASSWORD'' after it has been hashed by the
authentication plugin associated with the account.

For additional information about setting passwords and authentication
plugins, see assigning-passwords, and
pluggable-authentication.

*CREATE USER SSL/TLS Options*

MySQL can check X509 certificate attributes in addition to the usual
authentication that is based on the user name and credentials.  For
background information on the use of SSL/TLS with MySQL, see
encrypted-connections.

To specify SSL/TLS-related options for a MySQL account, use a 'REQUIRE'
clause that specifies one or more TLS_OPTION values.

Order of 'REQUIRE' options does not matter, but no option can be
specified twice.  The 'AND' keyword is optional between 'REQUIRE'
options.

'CREATE USER' permits these TLS_OPTION values:

   * 'NONE'

     Indicates that the account has no SSL or X509 requirements.
     Unencrypted connections are permitted if the user name and password
     are valid.  Encrypted connections can be used, at the client's
     option, if the client has the proper certificate and key files.

          CREATE USER 'jeffrey'@'localhost' REQUIRE NONE;

     Clients attempt to establish a secure connection by default.  For
     clients that have 'REQUIRE NONE', the connection attempt falls back
     to an unencrypted connection if a secure connection cannot be
     established.  To require an encrypted connection, a client need
     specify only the '--ssl-mode=REQUIRED' option; the connection
     attempt fails if a secure connection cannot be established.

     'NONE' is the default if no SSL-related 'REQUIRE' options are
     specified.

   * 'SSL'

     Tells the server to permit only encrypted connections for the
     account.

          CREATE USER 'jeffrey'@'localhost' REQUIRE SSL;

     Clients attempt to establish a secure connection by default.  For
     accounts that have 'REQUIRE SSL', the connection attempt fails if a
     secure connection cannot be established.

   * 'X509'

     Requires that clients present a valid certificate, but the exact
     certificate, issuer, and subject do not matter.  The only
     requirement is that it should be possible to verify its signature
     with one of the CA certificates.  Use of X509 certificates always
     implies encryption, so the 'SSL' option is unnecessary in this
     case.

          CREATE USER 'jeffrey'@'localhost' REQUIRE X509;

     For accounts with 'REQUIRE X509', clients must specify the
     '--ssl-key' and '--ssl-cert' options to connect.  (It is
     recommended but not required that '--ssl-ca' also be specified so
     that the public certificate provided by the server can be
     verified.)  This is true for 'ISSUER' and 'SUBJECT' as well because
     those 'REQUIRE' options imply the requirements of 'X509'.

   * 'ISSUER 'ISSUER''

     Requires that clients present a valid X509 certificate issued by CA
     ''ISSUER''.  If a client presents a certificate that is valid but
     has a different issuer, the server rejects the connection.  Use of
     X509 certificates always implies encryption, so the 'SSL' option is
     unnecessary in this case.

          CREATE USER 'jeffrey'@'localhost'
            REQUIRE ISSUER '/C=SE/ST=Stockholm/L=Stockholm/
              O=MySQL/CN=CA/emailAddress=ca@example.com';

     Because 'ISSUER' implies the requirements of 'X509', clients must
     specify the '--ssl-key' and '--ssl-cert' options to connect.  (It
     is recommended but not required that '--ssl-ca' also be specified
     so that the public certificate provided by the server can be
     verified.)

   * 'SUBJECT 'SUBJECT''

     Requires that clients present a valid X509 certificate containing
     the subject SUBJECT.  If a client presents a certificate that is
     valid but has a different subject, the server rejects the
     connection.  Use of X509 certificates always implies encryption, so
     the 'SSL' option is unnecessary in this case.

          CREATE USER 'jeffrey'@'localhost'
            REQUIRE SUBJECT '/C=SE/ST=Stockholm/L=Stockholm/
              O=MySQL demo client certificate/
              CN=client/emailAddress=client@example.com';

     MySQL does a simple string comparison of the ''SUBJECT'' value to
     the value in the certificate, so lettercase and component ordering
     must be given exactly as present in the certificate.

     Because 'SUBJECT' implies the requirements of 'X509', clients must
     specify the '--ssl-key' and '--ssl-cert' options to connect.  (It
     is recommended but not required that '--ssl-ca' also be specified
     so that the public certificate provided by the server can be
     verified.)

   * 'CIPHER 'CIPHER''

     Requires a specific cipher method for encrypting connections.  This
     option is needed to ensure that ciphers and key lengths of
     sufficient strength are used.  Encryption can be weak if old
     algorithms using short encryption keys are used.

          CREATE USER 'jeffrey'@'localhost'
            REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';

The 'SUBJECT', 'ISSUER', and 'CIPHER' options can be combined in the
'REQUIRE' clause:

     CREATE USER 'jeffrey'@'localhost'
       REQUIRE SUBJECT '/C=SE/ST=Stockholm/L=Stockholm/
         O=MySQL demo client certificate/
         CN=client/emailAddress=client@example.com'
       AND ISSUER '/C=SE/ST=Stockholm/L=Stockholm/
         O=MySQL/CN=CA/emailAddress=ca@example.com'
       AND CIPHER 'EDH-RSA-DES-CBC3-SHA';

*CREATE USER Resource-Limit Options*

It is possible to place limits on use of server resources by an account,
as discussed in user-resources.  To do so, use a 'WITH' clause
that specifies one or more RESOURCE_OPTION values.

Order of 'WITH' options does not matter, except that if a given resource
limit is specified multiple times, the last instance takes precedence.

'CREATE USER' permits these RESOURCE_OPTION values:

   * 'MAX_QUERIES_PER_HOUR COUNT', 'MAX_UPDATES_PER_HOUR COUNT',
     'MAX_CONNECTIONS_PER_HOUR COUNT'

     These options restrict how many queries, updates, and connections
     to the server are permitted to this account during any given
     one-hour period.  (Queries for which results are served from the
     query cache do not count against the 'MAX_QUERIES_PER_HOUR' limit.)
     If COUNT is '0' (the default), this means that there is no
     limitation for the account.

   * 'MAX_USER_CONNECTIONS COUNT'

     Restricts the maximum number of simultaneous connections to the
     server by the account.  A nonzero COUNT specifies the limit for the
     account explicitly.  If COUNT is '0' (the default), the server
     determines the number of simultaneous connections for the account
     from the global value of the 'max_user_connections' system
     variable.  If 'max_user_connections' is also zero, there is no
     limit for the account.

Example:

     CREATE USER 'jeffrey'@'localhost'
       WITH MAX_QUERIES_PER_HOUR 500 MAX_UPDATES_PER_HOUR 100;

*CREATE USER Password-Management Options*

Account passwords have an age, assessed from the date and time of the
most recent password change.

'CREATE USER' supports several PASSWORD_OPTION
values for password expiration management, to either expire an account
password manually or establish its password expiration policy.  Policy
options do not expire the password.  Instead, they determine how the
server applies automatic expiration to the account based on account
password age.  For a given account, its password age is assessed from
the date and time of the most recent password change.

These options apply to accounts that use a MySQL built-in authentication
plugin ('mysql_native_password' or 'caching_sha2_password').  For
accounts that use plugins that perform authentication against an
external credential system, password expiration must be handled
externally as well.  For information about password management policy,
see password-management.

A client session operates in restricted mode if the account password was
expired manually or if the password age is considered greater than its
permitted lifetime per the automatic expiration policy.  In restricted
mode, operations performed within the session result in an error until
the user establishes a new account password.  For information about
restricted mode, see expired-password-handling.

'CREATE USER' permits these PASSWORD_OPTION values:

   * 'PASSWORD EXPIRE'

     Causes the password for the new account to be marked expired.

          CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE;

   * 'PASSWORD EXPIRE DEFAULT'

     Sets the account so that the global expiration policy applies, as
     specified by the 'default_password_lifetime' system variable.

          CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE DEFAULT;

   * 'PASSWORD EXPIRE NEVER'

     Disables password expiration for the account so that its password
     never expires.

          CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE NEVER;

   * 'PASSWORD EXPIRE INTERVAL N DAY'

     Sets the account password lifetime to N days.  This statement
     requires the password to be changed every 180 days:

          CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE INTERVAL 180 DAY;

If multiple password-management options are specified, the last one
takes precedence.

*CREATE USER Account-Locking Options*

MySQL supports account locking and unlocking using the 'ACCOUNT LOCK'
and 'ACCOUNT UNLOCK' options, which specify the locking state for an
account.  For additional discussion, see account-locking.

If multiple account-locking options are specified, the last one takes
precedence.

13.7.1.3 DROP USER Syntax
.........................

     DROP USER [IF EXISTS] USER [, USER] ...

The 'DROP USER' statement removes one or more MySQL
accounts and their privileges.  It removes privilege rows for the
account from all grant tables.

To use 'DROP USER', you must have the global 'CREATE
USER' privilege, or the 'DELETE' privilege for the 'mysql' database.
When the 'read_only' system variable is enabled, see 'DROP USER'
additionally requires the 'SUPER' privilege.

An error occurs if you try to drop an account that does not exist.  If
the 'IF EXISTS' clause is given, the statement produces a warning for
each named user that does not exist, rather than an error.

Each account name uses the format described in account-names.
For example:

     DROP USER 'jeffrey'@'localhost';

The host name part of the account name, if omitted, defaults to ''%''.

*Important*:

'DROP USER' does not automatically close any open user
sessions.  Rather, in the event that a user with an open session is
dropped, the statement does not take effect until that user's session is
closed.  Once the session is closed, the user is dropped, and that
user's next attempt to log in will fail.  _This is by design_.

'DROP USER' does not automatically drop or invalidate
databases or objects within them that the old user created.  This
includes stored programs or views for which the 'DEFINER' attribute
names the dropped user.  Attempts to access such objects may produce an
error if they execute in definer security context.  (For information
about security context, see stored-programs-security.)

13.7.1.4 GRANT Syntax
.....................

     GRANT
         PRIV_TYPE [(COLUMN_LIST)]
           [, PRIV_TYPE [(COLUMN_LIST)]] ...
         ON [OBJECT_TYPE] PRIV_LEVEL
         TO USER [AUTH_OPTION] [, USER [AUTH_OPTION]] ...
         [REQUIRE {NONE | TLS_OPTION [[AND] TLS_OPTION] ...}]
         [WITH {GRANT OPTION | RESOURCE_OPTION} ...]

     GRANT PROXY ON USER
         TO USER [, USER] ...
         [WITH GRANT OPTION]

     OBJECT_TYPE: {
         TABLE
       | FUNCTION
       | PROCEDURE
     }

     PRIV_LEVEL: {
         *
       | *.*
       | DB_NAME.*
       | DB_NAME.TBL_NAME
       | TBL_NAME
       | DB_NAME.ROUTINE_NAME
     }

     USER:
         (see account-names)

     AUTH_OPTION: {
         IDENTIFIED BY 'AUTH_STRING'
       | IDENTIFIED WITH AUTH_PLUGIN
       | IDENTIFIED WITH AUTH_PLUGIN BY 'AUTH_STRING'
       | IDENTIFIED WITH AUTH_PLUGIN AS 'HASH_STRING'
       | IDENTIFIED BY PASSWORD 'HASH_STRING'
     }

     TLS_OPTION: {
         SSL
       | X509
       | CIPHER 'CIPHER'
       | ISSUER 'ISSUER'
       | SUBJECT 'SUBJECT'
     }

     RESOURCE_OPTION: {
       | MAX_QUERIES_PER_HOUR COUNT
       | MAX_UPDATES_PER_HOUR COUNT
       | MAX_CONNECTIONS_PER_HOUR COUNT
       | MAX_USER_CONNECTIONS COUNT
     }

The 'GRANT' statement grants privileges to MySQL user
accounts.  There are several aspects to the 'GRANT'.
statement, described under the following topics:

   * grant-overview

   * grant-quoting

   * grant-privileges

   * grant-accounts-passwords

   * grant-global-privileges

   * grant-database-privileges

   * grant-table-privileges

   * grant-column-privileges

   * grant-routine-privileges

   * grant-proxy-privileges

   * grant-account-creation

   * grant-other-characteristics

   * grant-mysql-vs-standard-sql

*GRANT General Overview*

The 'GRANT' statement grants privileges to MySQL user
accounts.

To use 'GRANT', you must have the 'GRANT OPTION' privilege,
and you must have the privileges that you are granting.  When the
'read_only' system variable is enabled, see 'GRANT'.
additionally requires the 'SUPER' privilege.

The 'REVOKE' statement is related to 'GRANT'
and enables administrators to remove account privileges.  See
revoke.

Each account name uses the format described in account-names.
For example:

     GRANT ALL ON db1.* TO 'jeffrey'@'localhost';

The host name part of the account, if omitted, defaults to ''%''.

Normally, a database administrator first uses 'CREATE USER'
to create an account and define its nonprivilege
characteristics such as its password, whether it uses secure
connections, and limits on access to server resources, then uses
'GRANT' to define its privileges.  'ALTER USER'
may be used to change the nonprivilege characteristics of
existing accounts.  For example:

     CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'PASSWORD';
     GRANT ALL ON db1.* TO 'jeffrey'@'localhost';
     GRANT SELECT ON db2.invoice TO 'jeffrey'@'localhost';
     ALTER USER 'jeffrey'@'localhost' WITH MAX_QUERIES_PER_HOUR 90;

*Note*:

Examples shown here include no 'IDENTIFIED' clause.  It is assumed that
you establish passwords with 'CREATE USER' at
account-creation time to avoid creating insecure accounts.

*Note*:

If an account named in a 'GRANT' statement does not
already exist, see 'GRANT' may create it under the conditions
described later in the discussion of the 'NO_AUTO_CREATE_USER' SQL mode.
It is also possible to use 'GRANT' to specify nonprivilege
account characteristics such as whether it uses secure connections and
limits on access to server resources.

However, use of 'GRANT' to create accounts or define
nonprivilege characteristics is deprecated as of MySQL 5.7.6.  Instead,
perform these tasks using 'CREATE USER' or
'ALTER USER'.

From the 'mysql' program, see 'GRANT' responds
with 'Query OK, 0 rows affected' when executed successfully.  To
determine what privileges result from the operation, use 'SHOW GRANTS'.
See show-grants.

*Important*:

Under some circumstances, see 'GRANT' may be recorded in
server logs or on the client side in a history file such as
'~/.mysql_history', which means that cleartext passwords may be read by
anyone having read access to that information.  For information about
the conditions under which this occurs for the server logs and how to
control it, see password-logging.  For similar information about
client-side logging, see mysql-logging.

'GRANT' supports host names up to 60 characters long.
User names can be up to 32 characters.  Database, table, column, and
routine names can be up to 64 characters.

*Warning*:

_Do not attempt to change the permissible length for user names by
altering the 'mysql.user' table.  Doing so results in unpredictable
behavior which may even make it impossible for users to log in to the
MySQL server_.  Never alter the structure of tables in the 'mysql'
database in any manner except by means of the procedure described in
mysql-upgrade.

*Object Quoting Guidelines*

Several objects within 'GRANT' statements are subject to
quoting, although quoting is optional in many cases: Account, database,
table, column, and routine names.  For example, if a USER_NAME or
HOST_NAME value in an account name is legal as an unquoted identifier,
you need not quote it.  However, quotation marks are necessary to
specify a USER_NAME string containing special characters (such as '-'),
or a HOST_NAME string containing special characters or wildcard
characters (such as '%'); for example, ''test-user'@'%.com''.  Quote the
user name and host name separately.

To specify quoted values:

   * Quote database, table, column, and routine names as identifiers.

   * Quote user names and host names as identifiers or as strings.

   * Quote passwords as strings.

For string-quoting and identifier-quoting guidelines, see
string-literals, and identifiers.

The '_' and '%' wildcards are permitted when specifying database names
in 'GRANT' statements that grant privileges at the
database level.  This means, for example, that to use a '_' character as
part of a database name, specify it as '\_' in the 'GRANT'.
statement, to prevent the user from being able to access additional
databases matching the wildcard pattern; for example, 'GRANT ... ON
`foo\_bar`.* TO ...'.

*Privileges Supported by MySQL*

The following table summarizes the permissible PRIV_TYPE privilege types
that can be specified for the 'GRANT' and 'REVOKE'
statements, and the levels at which each privilege can be
granted.  For additional information about each privilege, see
privileges-provided.

*Permissible Privileges for GRANT and REVOKE*

Privilege              Meaning and Grantable Levels

'ALL [PRIVILEGES]'     Grant all privileges at specified access level
                       except 'GRANT OPTION' and 'PROXY'.

'ALTER'                Enable use of 'ALTER TABLE'.
                       Levels: Global, database, table.

'ALTER ROUTINE'        Enable stored routines to be altered or dropped.
                       Levels: Global, database, procedure.

'CREATE'               Enable database and table creation.  Levels:
                       Global, database, table.

'CREATE ROUTINE'       Enable stored routine creation.  Levels: Global,
                       database.

'CREATE TABLESPACE'    Enable tablespaces and log file groups to be
                       created, altered, or dropped.  Level: Global.

'CREATE TEMPORARY      Enable use of 'CREATE TEMPORARY TABLE'.
Levels: Global, database.

'CREATE USER'          Enable use of 'CREATE USER',
                       'DROP USER', 'RENAME USER',
                       and 'REVOKE ALL PRIVILEGES'.
                       Level: Global.

'CREATE VIEW'          Enable views to be created or altered.  Levels:
                       Global, database, table.

'DELETE'               Enable use of 'DELETE'.  Level:
                       Global, database, table.

'DROP'                 Enable databases, tables, and views to be
                       dropped.  Levels: Global, database, table.

'EVENT'                Enable use of events for the Event Scheduler.
                       Levels: Global, database.

'EXECUTE'              Enable the user to execute stored routines.
                       Levels: Global, database, table.

'FILE'                 Enable the user to cause the server to read or
                       write files.  Level: Global.

'GRANT OPTION'         Enable privileges to be granted to or removed
                       from other accounts.  Levels: Global, database,
                       table, procedure, proxy.

'INDEX'                Enable indexes to be created or dropped.
                       Levels: Global, database, table.

'INSERT'               Enable use of 'INSERT'.  Levels:
                       Global, database, table, column.

'LOCK TABLES'          Enable use of 'LOCK TABLES'.
                       on tables for which you have the 'SELECT'
                       privilege.  Levels: Global, database.

'PROCESS'              Enable the user to see all processes with
                       'SHOW PROCESSLIST'.  Level:
                       Global.

'PROXY'                Enable user proxying.  Level: From user to user.

'REFERENCES'           Enable foreign key creation.  Levels: Global,
                       database, table, column.

'RELOAD'               Enable use of 'FLUSH' operations.
                       Level: Global.

'REPLICATION CLIENT'   Enable the user to ask where master or slave
                       servers are.  Level: Global.

'REPLICATION SLAVE'    Enable replication slaves to read binary log
                       events from the master.  Level: Global.

'SELECT'               Enable use of 'SELECT'.  Levels:
                       Global, database, table, column.

'SHOW DATABASES'       Enable 'SHOW DATABASES'.
                       to show all databases.  Level: Global.

'SHOW VIEW'            Enable use of 'SHOW CREATE VIEW'.
                       Levels: Global, database,
                       table.

'SHUTDOWN'             Enable use of 'mysqladmin shutdown'.
                       Level: Global.

'SUPER'                Enable use of other administrative operations
                       such as 'CHANGE MASTER TO',
                       see 'KILL',
                       'PURGE BINARY LOGS',
                       'SET GLOBAL', and
                       'mysqladmin debug' command.  Level:
                       Global.

'TRIGGER'              Enable trigger operations.  Levels: Global,
                       database, table.

'UPDATE'               Enable use of 'UPDATE'.  Levels:
                       Global, database, table, column.

'USAGE'                Synonym for 'no privileges'

A trigger is associated with a table.  To create or drop a trigger, you
must have the 'TRIGGER' privilege for the table, not the trigger.

In 'GRANT' statements, the 'ALL [PRIVILEGES]' or 'PROXY'
privilege must be named by itself and cannot be specified along with
other privileges.  'ALL [PRIVILEGES]' stands for all privileges
available for the level at which privileges are to be granted except for
the 'GRANT OPTION' and 'PROXY' privileges.

'USAGE' can be specified to create a user that has no privileges, or to
specify the 'REQUIRE' or 'WITH' clauses for an account without changing
its existing privileges.  (However, use of 'GRANT' to
define nonprivilege characteristics is deprecated.

MySQL account information is stored in the tables of the 'mysql'
database.  For additional details, consult privilege-system,
which discusses the 'mysql' database and the access control system
extensively.

If the grant tables hold privilege rows that contain mixed-case database
or table names and the 'lower_case_table_names' system variable is set
to a nonzero value, see 'REVOKE' cannot be used to revoke
these privileges.  It will be necessary to manipulate the grant tables
directly.  (see 'GRANT' will not create such rows when
'lower_case_table_names' is set, but such rows might have been created
prior to setting that variable.)

Privileges can be granted at several levels, depending on the syntax
used for the 'ON' clause.  For 'REVOKE', the same 'ON'
syntax specifies which privileges to remove.

For the global, database, table, and routine levels, see 'GRANT ALL'
assigns only the privileges that exist at the level you are
granting.  For example, 'GRANT ALL ON DB_NAME.*' is a database-level
statement, so it does not grant any global-only privileges such as
'FILE'.  Granting 'ALL' does not assign the 'GRANT OPTION' or 'PROXY'
privilege.

The OBJECT_TYPE clause, if present, should be specified as 'TABLE',
'FUNCTION', or 'PROCEDURE' when the following object is a table, a
stored function, or a stored procedure.

The privileges that a user holds for a database, table, column, or
routine are formed additively as the logical 'OR' of the account
privileges at each of the privilege levels.  For example, if a user has
a global 'SELECT' privilege, the privilege cannot be denied by an
absence of the privilege at the database, table, or column level.
Details of the privilege-checking procedure are presented in
request-access.

If you are using table, column, or routine privileges for even one user,
the server examines table, column, and routine privileges for all users
and this slows down MySQL a bit.  Similarly, if you limit the number of
queries, updates, or connections for any users, the server must monitor
these values.

MySQL enables you to grant privileges on databases or tables that do not
exist.  For tables, the privileges to be granted must include the
'CREATE' privilege.  _This behavior is by design_, and is intended to
enable the database administrator to prepare user accounts and
privileges for databases or tables that are to be created at a later
time.

*Important*:

_MySQL does not automatically revoke any privileges when you drop a
database or table_.  However, if you drop a routine, any routine-level
privileges granted for that routine are revoked.

*Account Names and Passwords*

A USER value in a 'GRANT' statement indicates a MySQL
account to which the statement applies.  To accommodate granting rights
to users from arbitrary hosts, MySQL supports specifying the USER value
in the form ''USER_NAME'@'HOST_NAME''.

You can specify wildcards in the host name.  For example,
''USER_NAME'@'%.example.com'' applies to USER_NAME for any host in the
'example.com' domain, and ''USER_NAME'@'198.51.100.%'' applies to
USER_NAME for any host in the '198.51.100' class C subnet.

The simple form ''USER_NAME'' is a synonym for ''USER_NAME'@'%''.

_MySQL does not support wildcards in user names_.  To refer to an
anonymous user, specify an account with an empty user name with the
'GRANT' statement:

     GRANT ALL ON test.* TO ''@'localhost' ...;

In this case, any user who connects from the local host with the correct
password for the anonymous user will be permitted access, with the
privileges associated with the anonymous-user account.

For additional information about user name and host name values in
account names, see account-names.

*Warning*:

If you permit local anonymous users to connect to the MySQL server, you
should also grant privileges to all local users as
''USER_NAME'@'localhost''.  Otherwise, the anonymous user account for
'localhost' in the 'mysql.user' system table is used when named users
try to log in to the MySQL server from the local machine.  For details,
see connection-access.

To determine whether this issue applies to you, execute the following
query, which lists any anonymous users:

     SELECT Host, User FROM mysql.user WHERE User='';

To avoid the problem just described, delete the local anonymous user
account using this statement:

     DROP USER ''@'localhost';

For 'GRANT' syntaxes that permit an AUTH_OPTION value to
follow a USER value, AUTH_OPTION begins with 'IDENTIFIED' and indicates
how the account authenticates by specifying an account authentication
plugin, credentials (for example, a password), or both.  Syntax of the
AUTH_OPTION clause is the same as for the 'CREATE USER'
statement.  For details, see create-user.

*Note*:

Use of 'GRANT' to define account authentication
characteristics is deprecated as of MySQL 5.7.6.  Instead, establish or
change authentication characteristics using 'CREATE USER'
or 'ALTER USER'.  This 'GRANT'
capability will be removed in a future MySQL release.

When 'IDENTIFIED' is present and you have the global grant privilege
('GRANT OPTION'), any password specified becomes the new password for
the account, even if the account exists and already has a password.
Without 'IDENTIFIED', the account password remains unchanged.

*Global Privileges*

Global privileges are administrative or apply to all databases on a
given server.  To assign global privileges, use 'ON *.*' syntax:

     GRANT ALL ON *.* TO 'someuser'@'somehost';
     GRANT SELECT, INSERT ON *.* TO 'someuser'@'somehost';

The 'CREATE TABLESPACE', 'CREATE USER', 'FILE', 'PROCESS', 'RELOAD',
'REPLICATION CLIENT', 'REPLICATION SLAVE', 'SHOW DATABASES', 'SHUTDOWN',
and 'SUPER' privileges are administrative and can only be granted
globally.

Other privileges can be granted globally or at more specific levels.

'GRANT OPTION' granted at the global level for any global privilege
applies to all global privileges.

MySQL stores global privileges in the 'mysql.user' system table.

*Database Privileges*

Database privileges apply to all objects in a given database.  To assign
database-level privileges, use 'ON DB_NAME.*' syntax:

     GRANT ALL ON mydb.* TO 'someuser'@'somehost';
     GRANT SELECT, INSERT ON mydb.* TO 'someuser'@'somehost';

If you use 'ON *' syntax (rather than 'ON *.*'), privileges are assigned
at the database level for the default database.  An error occurs if
there is no default database.

The 'CREATE', 'DROP', 'EVENT', 'GRANT OPTION', 'LOCK TABLES', and
'REFERENCES' privileges can be specified at the database level.  Table
or routine privileges also can be specified at the database level, in
which case they apply to all tables or routines in the database.

MySQL stores database privileges in the 'mysql.db' system table.

*Table Privileges*

Table privileges apply to all columns in a given table.  To assign
table-level privileges, use 'ON DB_NAME.TBL_NAME' syntax:

     GRANT ALL ON mydb.mytbl TO 'someuser'@'somehost';
     GRANT SELECT, INSERT ON mydb.mytbl TO 'someuser'@'somehost';

If you specify TBL_NAME rather than DB_NAME.TBL_NAME, the statement
applies to TBL_NAME in the default database.  An error occurs if there
is no default database.

The permissible PRIV_TYPE values at the table level are 'ALTER', 'CREATE
VIEW', 'CREATE', 'DELETE', 'DROP', 'GRANT OPTION', 'INDEX', 'INSERT',
'REFERENCES', 'SELECT', 'SHOW VIEW', 'TRIGGER', and 'UPDATE'.

Table-level privileges apply to base tables and views.  They do not
apply to tables created with 'CREATE TEMPORARY TABLE',
even if the table names match.  For information
about 'TEMPORARY' table privileges, see create-temporary-table.

MySQL stores table privileges in the 'mysql.tables_priv' system table.

*Column Privileges*

Column privileges apply to single columns in a given table.  Each
privilege to be granted at the column level must be followed by the
column or columns, enclosed within parentheses.

     GRANT SELECT (col1), INSERT (col1, col2) ON mydb.mytbl TO 'someuser'@'somehost';

The permissible PRIV_TYPE values for a column (that is, when you use a
COLUMN_LIST clause) are 'INSERT', 'REFERENCES', 'SELECT', and 'UPDATE'.

MySQL stores column privileges in the 'mysql.columns_priv' system table.

*Stored Routine Privileges*

The 'ALTER ROUTINE', 'CREATE ROUTINE', 'EXECUTE', and 'GRANT OPTION'
privileges apply to stored routines (procedures and functions).  They
can be granted at the global and database levels.  Except for 'CREATE
ROUTINE', these privileges can be granted at the routine level for
individual routines.

     GRANT CREATE ROUTINE ON mydb.* TO 'someuser'@'somehost';
     GRANT EXECUTE ON PROCEDURE mydb.myproc TO 'someuser'@'somehost';

The permissible PRIV_TYPE values at the routine level are 'ALTER
ROUTINE', 'EXECUTE', and 'GRANT OPTION'.  'CREATE ROUTINE' is not a
routine-level privilege because you must have the privilege at the
global or database level to create a routine in the first place.

MySQL stores routine-level privileges in the 'mysql.procs_priv' system
table.

*Proxy User Privileges*

The 'PROXY' privilege enables one user to be a proxy for another.  The
proxy user impersonates or takes the identity of the proxied user; that
is, it assumes the privileges of the proxied user.

     GRANT PROXY ON 'localuser'@'localhost' TO 'externaluser'@'somehost';

When 'PROXY' is granted, it must be the only privilege named in the
'GRANT' statement, the 'REQUIRE' clause cannot be given,
and the only permitted 'WITH' option is 'WITH GRANT OPTION'.

Proxying requires that the proxy user authenticate through a plugin that
returns the name of the proxied user to the server when the proxy user
connects, and that the proxy user have the 'PROXY' privilege for the
proxied user.  For details and examples, see proxy-users.

MySQL stores proxy privileges in the 'mysql.proxies_priv' system table.

*Implicit Account Creation*

If an account named in a 'GRANT' statement does not exist,
the action taken depends on the 'NO_AUTO_CREATE_USER' SQL mode:

   * If 'NO_AUTO_CREATE_USER' is not enabled, see 'GRANT'.
     creates the account.  _This is very insecure_ unless you specify a
     nonempty password using 'IDENTIFIED BY'.

   * If 'NO_AUTO_CREATE_USER' is enabled, see 'GRANT' fails
     and does not create the account, unless you specify a nonempty
     password using 'IDENTIFIED BY' or name an authentication plugin
     using 'IDENTIFIED WITH'.

If the account already exists, 'IDENTIFIED WITH' is prohibited because
it is intended only for use when creating new accounts.

*Other Account Characteristics*

MySQL can check X509 certificate attributes in addition to the usual
authentication that is based on the user name and credentials.  For
background information on the use of SSL with MySQL, see
encrypted-connections.

The optional 'REQUIRE' clause specifies SSL-related options for a MySQL
account.  The syntax is the same as for the 'CREATE USER'
statement.  For details, see create-user.

*Note*:

Use of 'GRANT' to define account SSL characteristics is
deprecated as of MySQL 5.7.6.  Instead, establish or change SSL
characteristics using 'CREATE USER' or 'ALTER USER'.
This 'GRANT' capability will be
removed in a future MySQL release.

The optional 'WITH' clause is used for these purposes:

   * To enable a user to grant privileges to other users

   * To specify resource limits for a user

The 'WITH GRANT OPTION' clause gives the user the ability to give to
other users any privileges the user has at the specified privilege
level.

To grant the 'GRANT OPTION' privilege to an account without otherwise
changing its privileges, do this:

     GRANT USAGE ON *.* TO 'someuser'@'somehost' WITH GRANT OPTION;

Be careful to whom you give the 'GRANT OPTION' privilege because two
users with different privileges may be able to combine privileges!

You cannot grant another user a privilege which you yourself do not
have; the 'GRANT OPTION' privilege enables you to assign only those
privileges which you yourself possess.

Be aware that when you grant a user the 'GRANT OPTION' privilege at a
particular privilege level, any privileges the user possesses (or may be
given in the future) at that level can also be granted by that user to
other users.  Suppose that you grant a user the 'INSERT' privilege on a
database.  If you then grant the 'SELECT' privilege on the database and
specify 'WITH GRANT OPTION', that user can give to other users not only
the 'SELECT' privilege, but also 'INSERT'.  If you then grant the
'UPDATE' privilege to the user on the database, the user can grant
'INSERT', 'SELECT', and 'UPDATE'.

For a nonadministrative user, you should not grant the 'ALTER' privilege
globally or for the 'mysql' database.  If you do that, the user can try
to subvert the privilege system by renaming tables!

For additional information about security risks associated with
particular privileges, see privileges-provided.

It is possible to place limits on use of server resources by an account,
as discussed in user-resources.  To do so, use a 'WITH' clause
that specifies one or more RESOURCE_OPTION values.  Limits not specified
retain their current values.  The syntax is the same as for the
'CREATE USER' statement.  For details, see
create-user.

*Note*:

Use of 'GRANT' to define account resource limits is
deprecated as of MySQL 5.7.6.  Instead, establish or change resource
limits using 'CREATE USER' or 'ALTER USER'.
This 'GRANT' capability will be removed in a
future MySQL release.

*MySQL and Standard SQL Versions of GRANT*

The biggest differences between the MySQL and standard SQL versions of
'GRANT' are:

   * MySQL associates privileges with the combination of a host name and
     user name and not with only a user name.

   * Standard SQL does not have global or database-level privileges, nor
     does it support all the privilege types that MySQL supports.

   * MySQL does not support the standard SQL 'UNDER' privilege.

   * Standard SQL privileges are structured in a hierarchical manner.
     If you remove a user, all privileges the user has been granted are
     revoked.  This is also true in MySQL if you use 'DROP USER'.
     See drop-user.

   * In standard SQL, when you drop a table, all privileges for the
     table are revoked.  In standard SQL, when you revoke a privilege,
     all privileges that were granted based on that privilege are also
     revoked.  In MySQL, privileges can be dropped with 'DROP USER'
     or 'REVOKE' statements.

   * In MySQL, it is possible to have the 'INSERT' privilege for only
     some of the columns in a table.  In this case, you can still
     execute 'INSERT' statements on the table, provided
     that you insert values only for those columns for which you have
     the 'INSERT' privilege.  The omitted columns are set to their
     implicit default values if strict SQL mode is not enabled.  In
     strict mode, the statement is rejected if any of the omitted
     columns have no default value.  (Standard SQL requires you to have
     the 'INSERT' privilege on all columns.)  For information about
     strict SQL mode and implicit default values, see sql-mode,
     and data-type-defaults.

13.7.1.5 RENAME USER Syntax
...........................

     RENAME USER OLD_USER TO NEW_USER
         [, OLD_USER TO NEW_USER] ...

The 'RENAME USER' statement renames existing MySQL
accounts.  An error occurs for old accounts that do not exist or new
accounts that already exist.

To use 'RENAME USER', you must have the global
'CREATE USER' privilege, or the 'UPDATE' privilege for the 'mysql'
database.  When the 'read_only' system variable is enabled, see
'RENAME USER' additionally requires the 'SUPER' privilege.

Each account name uses the format described in account-names.
For example:

     RENAME USER 'jeffrey'@'localhost' TO 'jeff'@'127.0.0.1';

The host name part of the account name, if omitted, defaults to ''%''.

'RENAME USER' causes the privileges held by the old
user to be those held by the new user.  However, see 'RENAME USER'
does not automatically drop or invalidate databases or
objects within them that the old user created.  This includes stored
programs or views for which the 'DEFINER' attribute names the old user.
Attempts to access such objects may produce an error if they execute in
definer security context.  (For information about security context, see
stored-programs-security.)

The privilege changes take effect as indicated in
privilege-changes.

13.7.1.6 REVOKE Syntax
......................

     REVOKE
         PRIV_TYPE [(COLUMN_LIST)]
           [, PRIV_TYPE [(COLUMN_LIST)]] ...
         ON [OBJECT_TYPE] PRIV_LEVEL
         FROM USER [, USER] ...

     REVOKE ALL [PRIVILEGES], GRANT OPTION
         FROM USER [, USER] ...

     REVOKE PROXY ON USER
         FROM USER [, USER] ...

The 'REVOKE' statement enables system administrators to
revoke privileges from MySQL accounts.

When the 'read_only' system variable is enabled, see 'REVOKE'.
requires the 'SUPER' privilege in addition to any other required
privileges described in the following discussion.

Each account name uses the format described in account-names.
For example:

     REVOKE INSERT ON *.* FROM 'jeffrey'@'localhost';

The host name part of the account name, if omitted, defaults to ''%''.

For details on the levels at which privileges exist, the permissible
PRIV_TYPE, PRIV_LEVEL, and OBJECT_TYPE values, and the syntax for
specifying users and passwords, see grant

To use the first 'REVOKE' syntax, you must have the
'GRANT OPTION' privilege, and you must have the privileges that you are
revoking.

To revoke all privileges, use the second syntax, which drops all global,
database, table, column, and routine privileges for the named user or
users:

     REVOKE ALL PRIVILEGES, GRANT OPTION FROM USER [, USER] ...

To use this 'REVOKE' syntax, you must have the global
'CREATE USER' privilege, or the 'UPDATE' privilege for the 'mysql'
database.

User accounts from which privileges are to be revoked must exist.

'REVOKE' removes privileges, but does not drop
'mysql.user' table entries.  To remove a user account entirely, use
'DROP USER'.  See drop-user.

If the grant tables hold privilege rows that contain mixed-case database
or table names and the 'lower_case_table_names' system variable is set
to a nonzero value, see 'REVOKE' cannot be used to revoke
these privileges.  It will be necessary to manipulate the grant tables
directly.  (see 'GRANT' will not create such rows when
'lower_case_table_names' is set, but such rows might have been created
prior to setting the variable.)

When successfully executed from the 'mysql' program, see
'REVOKE' responds with 'Query OK, 0 rows affected'.  To
determine what privileges remain after the operation, use 'SHOW GRANTS'.
See show-grants.

13.7.1.7 SET PASSWORD Syntax
............................

     SET PASSWORD [FOR USER] = PASSWORD_OPTION

     PASSWORD_OPTION: {
         'AUTH_STRING'
       | PASSWORD('AUTH_STRING')
     }

The 'SET PASSWORD' statement assigns a password to
a MySQL user account.  ''AUTH_STRING'' represents a cleartext
(unencrypted) password.

*Note*:

   * 'SET PASSWORD ... = PASSWORD('AUTH_STRING')'.
     syntax is deprecated as of MySQL 5.7.6 and will be removed in a
     future MySQL release.

   * 'SET PASSWORD ... = 'AUTH_STRING'' syntax is
     not deprecated, but 'ALTER USER' is the
     preferred statement for account alterations, including assigning
     passwords.  For example:

          ALTER USER USER IDENTIFIED BY 'AUTH_STRING';

*Important*:

Under some circumstances, see 'SET PASSWORD' may be
recorded in server logs or on the client side in a history file such as
'~/.mysql_history', which means that cleartext passwords may be read by
anyone having read access to that information.  For information about
the conditions under which this occurs for the server logs and how to
control it, see password-logging.  For similar information about
client-side logging, see mysql-logging.

'SET PASSWORD' can be used with or without a 'FOR'
clause that explicitly names a user account:

   * With a 'FOR USER' clause, the statement sets the password for the
     named account, which must exist:

          SET PASSWORD FOR 'jeffrey'@'localhost' = 'AUTH_STRING';

   * With no 'FOR USER' clause, the statement sets the password for the
     current user:

          SET PASSWORD = 'AUTH_STRING';

     Any client who connects to the server using a nonanonymous account
     can change the password for that account.  To see which account the
     server authenticated you as, invoke the 'CURRENT_USER()' function:

          SELECT CURRENT_USER();

Setting the password for a named account (with a 'FOR' clause) requires
the 'UPDATE' privilege for the 'mysql' database.  Setting
the password for yourself (for a nonanonymous account with no 'FOR'
clause) requires no special privileges.  When the 'read_only' system
variable is enabled, see 'SET PASSWORD' requires the
'SUPER' privilege in addition to any other required privileges.

If a 'FOR USER' clause is given, the account name uses the format
described in account-names.  For example:

     SET PASSWORD FOR 'bob'@'%.example.org' = 'AUTH_STRING';

The host name part of the account name, if omitted, defaults to ''%''.

The password can be specified in these ways:

   * Use a string without 'PASSWORD()'

          SET PASSWORD FOR 'jeffrey'@'localhost' = 'PASSWORD';

     'SET PASSWORD' interprets the string as a
     cleartext string, passes it to the authentication plugin associated
     with the account, and stores the result returned by the plugin in
     the 'mysql.user' account row.  (The plugin is given the opportunity
     to hash the value into the encryption format it expects.  The
     plugin may use the value as specified, in which case no hashing
     occurs.)

   * Use the 'PASSWORD()' function (deprecated as of MySQL 5.7.6)

          SET PASSWORD FOR 'jeffrey'@'localhost' = PASSWORD('PASSWORD');

     The 'PASSWORD()' argument is the cleartext (unencrypted) password.
     'PASSWORD()' hashes the password and returns the encrypted password
     string for storage in the 'mysql.user' account row.

     The 'PASSWORD()' function hashes the password using the hashing
     method determined by the value of the 'old_passwords' system
     variable value.  Be sure that 'old_passwords' has the value
     corresponding to the hashing method expected by the authentication
     plugin associated with the account.  For example, if the account
     uses the 'mysql_native_password' plugin, the 'old_passwords' value
     must be 0:

          SET old_passwords = 0;
          SET PASSWORD FOR 'jeffrey'@'localhost' = PASSWORD('PASSWORD');

     If the 'old_passwords' value differs from that required by the
     authentication plugin, the hashed password value returned by
     'PASSWORD()' will not by usable by the plugin and correct
     authentication of client connections will not occur.

The following table shows, for each password hashing method, the
permitted value of 'old_passwords' and which authentication plugins use
the hashing method.

Password Hashing Method       old_passwords  Associated Authentication
                              Value          Plugin

MySQL 4.1 native hashing      0              'mysql_native_password'

SHA-256 hashing               2              'sha256_password'

For additional information about setting passwords and authentication
plugins, see assigning-passwords, and
pluggable-authentication.

13.7.2 Table Maintenance Statements
-----------------------------------

13.7.2.1 ANALYZE TABLE Syntax
.............................

     ANALYZE [NO_WRITE_TO_BINLOG | LOCAL]
         TABLE TBL_NAME [, TBL_NAME] ...

'ANALYZE TABLE' performs a key distribution
analysis and stores the distribution for the named table or tables.  For
'MyISAM' tables, this statement is equivalent to using 'myisamchk --analyze'.

This statement requires 'SELECT' and 'INSERT' privileges for the table.

'ANALYZE TABLE' works with 'InnoDB', 'NDB', and
'MyISAM' tables.  It does not work with views.

'ANALYZE TABLE' is supported for partitioned
tables, and you can use 'ALTER TABLE ... ANALYZE PARTITION' to analyze
one or more partitions; for more information, see alter-table,
and partitioning-maintenance.

During the analysis, the table is locked with a read lock for 'InnoDB'
and 'MyISAM'.

By default, the server writes 'ANALYZE TABLE'.
statements to the binary log so that they replicate to replication
slaves.  To suppress logging, specify the optional 'NO_WRITE_TO_BINLOG'
keyword or its alias 'LOCAL'.

   * analyze-table-output

   * analyze-table-key-distribution-analysis

*ANALYZE TABLE Output*

'ANALYZE TABLE' returns a result set with the
columns shown in the following table.

Column      Value

'Table'     The table name

'Op'        Always 'analyze'

'Msg_type'  'status', 'error', 'info', 'note', or
            'warning'

'Msg_text'  An informational message

*Key Distribution Analysis*

If the table has not changed since the last key distribution analysis,
the table is not analyzed again.

MySQL uses the stored key distribution to decide the table join order
for joins on something other than a constant.  In addition, key
distributions can be used when deciding which indexes to use for a
specific table within a query.

For more information on how key distribution analysis works within
'InnoDB', see innodb-persistent-stats and
innodb-analyze-table-complexity.  Also see
innodb-restrictions.  In particular, if the 'innodb_stats_persistent'
system variable is enabled, you must run 'ANALYZE TABLE'
after loading substantial data into an 'InnoDB' table, or
creating a new index for one.

To check the stored key distribution cardinality, use the 'SHOW INDEX'
statement or the
'INFORMATION_SCHEMA.STATISTICS' table.  See
show-index, and statistics-table.

13.7.2.2 CHECK TABLE Syntax
...........................

     CHECK TABLE TBL_NAME [, TBL_NAME] ... [OPTION] ...

     OPTION = {
         FOR UPGRADE
       | QUICK
       | FAST
       | MEDIUM
       | EXTENDED
       | CHANGED
     }

'CHECK TABLE' checks a table or tables for errors.
For 'MyISAM' tables, the key statistics are updated as well.
'CHECK TABLE' can also check views for problems, such as
tables that are referenced in the view definition that no longer exist.

To check a table, you must have some privilege for it.

'CHECK TABLE' works for 'InnoDB',
see 'MyISAM',
'ARCHIVE', and 'CSV'.
tables.

Before running 'CHECK TABLE' on 'InnoDB' tables, see
check-table-innodb.

'CHECK TABLE' is supported for partitioned tables,
and you can use 'ALTER TABLE ... CHECK PARTITION' to check one or more
partitions; for more information, see alter-table, and
partitioning-maintenance.

'CHECK TABLE' ignores virtual generated columns that
are not indexed.

   * check-table-output

   * check-table-version-compatibility

   * check-table-data-consistency

   * check-table-innodb

   * check-table-myisam

*CHECK TABLE Output*

'CHECK TABLE' returns a result set with the columns
shown in the following table.

Column      Value

'Table'     The table name

'Op'        Always 'check'

'Msg_type'  'status', 'error', 'info', 'note', or
            'warning'

'Msg_text'  An informational message

The statement might produce many rows of information for each checked
table.  The last row has a 'Msg_type' value of 'status' and the
'Msg_text' normally should be 'OK'.  For a 'MyISAM' table, if you don't
get 'OK' or 'Table is already up to date', you should normally run a
repair of the table.  See myisam-table-maintenance.  'Table is
already up to date' means that the storage engine for the table
indicated that there was no need to check the table.

*Checking Version Compatibility*

The 'FOR UPGRADE' option checks whether the named tables are compatible
with the current version of MySQL. With 'FOR UPGRADE', the server checks
each table to determine whether there have been any incompatible changes
in any of the table's data types or indexes since the table was created.
If not, the check succeeds.  Otherwise, if there is a possible
incompatibility, the server runs a full check on the table (which might
take some time).  If the full check succeeds, the server marks the
table's '.frm' file with the current MySQL version number.  Marking the
'.frm' file ensures that further checks for the table with the same
version of the server will be fast.

Incompatibilities might occur because the storage format for a data type
has changed or because its sort order has changed.  Our aim is to avoid
these changes, but occasionally they are necessary to correct problems
that would be worse than an incompatibility between releases.

'FOR UPGRADE' discovers these incompatibilities:

   * The indexing order for end-space in 'TEXT' columns for
     'InnoDB' and 'MyISAM' tables changed between MySQL 4.1 and 5.0.

   * The storage method of the new 'DECIMAL'.
     data type changed between MySQL 5.0.3 and 5.0.5.

   * If your table was created by a different version of the MySQL
     server than the one you are currently running, 'FOR UPGRADE'
     indicates that the table has an '.frm' file with an incompatible
     version.  In this case, the result set returned by 'CHECK TABLE'
     contains a line with a 'Msg_type' value of
     'error' and a 'Msg_text' value of 'Table upgrade required. Please
     do "REPAIR TABLE `TBL_NAME`" to fix it!'

   * Changes are sometimes made to character sets or collations that
     require table indexes to be rebuilt.  For details about such
     changes, see upgrading-from-previous-series.  For
     information about rebuilding tables, see rebuilding-tables.

   * The 'YEAR(2)' data type is deprecated and support for
     it is removed in MySQL 5.7.5.  For tables containing
     'YEAR(2)' columns, see 'CHECK TABLE'.
     recommends 'REPAIR TABLE', which converts
     'YEAR(2)' to 'YEAR(4)'.

   * As of MySQL 5.7.2, trigger creation time is maintained.  If run
     against a table that has triggers, see 'CHECK TABLE ... FOR UPGRADE'
     displays this warning for each trigger
     created before MySQL 5.7.2:

          Trigger DB_NAME.TBL_NAME.TRIGGER_NAME does not have CREATED attribute.

     The warning is informational only.  No change is made to the
     trigger.

   * As of MySQL 5.7.7, a table is reported as needing a rebuild if it
     contains old temporal columns in pre-5.6.4 format (see 'TIME',
     see 'DATETIME', and 'TIMESTAMP'.
     columns without support for fractional seconds precision) and the
     'avoid_temporal_upgrade' system variable is disabled.  This helps
     'mysql_upgrade' detect and upgrade tables
     containing old temporal columns.  If 'avoid_temporal_upgrade' is
     enabled, 'FOR UPGRADE' ignores the old temporal columns present in
     the table; consequently, see 'mysql_upgrade' does
     not upgrade them.

     To check for tables that contain such temporal columns and need a
     rebuild, disable 'avoid_temporal_upgrade' before executing
     'CHECK TABLE ... FOR UPGRADE'.

   * Warnings are issued for tables that use nonnative partitioning
     because nonnative partitioning is deprecated in MySQL 5.7 and
     removed in MySQL 8.0.  See partitioning.

*Checking Data Consistency*

The following table shows the other check options that can be given.
These options are passed to the storage engine, which may use or ignore
them.

Type        Meaning

'QUICK'     Do not scan the rows to check for incorrect links.  Applies
            to 'InnoDB' and 'MyISAM' tables and views.

'FAST'      Check only tables that have not been closed properly.
            Ignored for 'InnoDB'; applies only to 'MyISAM' tables and
            views.

'CHANGED'   Check only tables that have been changed since the last
            check or that have not been closed properly.  Ignored for
            'InnoDB'; applies only to 'MyISAM' tables and views.

'MEDIUM'    Scan rows to verify that deleted links are valid.  This
            also calculates a key checksum for the rows and verifies
            this with a calculated checksum for the keys.  Ignored for
            'InnoDB'; applies only to 'MyISAM' tables and views.

'EXTENDED'  Do a full key lookup for all keys for each row.  This
            ensures that the table is 100% consistent, but takes a long
            time.  Ignored for 'InnoDB'; applies only to 'MyISAM'
            tables and views.

If none of the options 'QUICK', 'MEDIUM', or 'EXTENDED' are specified,
the default check type for dynamic-format 'MyISAM' tables is 'MEDIUM'.
This has the same result as running 'myisamchk --medium-check TBL_NAME'
on the table.  The default check type also is
'MEDIUM' for static-format 'MyISAM' tables, unless 'CHANGED' or 'FAST'
is specified.  In that case, the default is 'QUICK'.  The row scan is
skipped for 'CHANGED' and 'FAST' because the rows are very seldom
corrupted.

You can combine check options, as in the following example that does a
quick check on the table to determine whether it was closed properly:

     CHECK TABLE test_table FAST QUICK;

*Note*:

If 'CHECK TABLE' finds no problems with a table that
is marked as 'corrupted' or 'not closed properly', see 'CHECK TABLE'
may remove the mark.

If a table is corrupted, the problem is most likely in the indexes and
not in the data part.  All of the preceding check types check the
indexes thoroughly and should thus find most errors.

To check a table that you assume is okay, use no check options or the
'QUICK' option.  The latter should be used when you are in a hurry and
can take the very small risk that 'QUICK' does not find an error in the
data file.  (In most cases, under normal usage, MySQL should find any
error in the data file.  If this happens, the table is marked as
'corrupted' and cannot be used until it is repaired.)

'FAST' and 'CHANGED' are mostly intended to be used from a script (for
example, to be executed from 'cron') to check tables periodically.  In
most cases, 'FAST' is to be preferred over 'CHANGED'.  (The only case
when it is not preferred is when you suspect that you have found a bug
in the 'MyISAM' code.)

'EXTENDED' is to be used only after you have run a normal check but
still get errors from a table when MySQL tries to update a row or find a
row by key.  This is very unlikely if a normal check has succeeded.

Use of 'CHECK TABLE ... EXTENDED' might influence
execution plans generated by the query optimizer.

Some problems reported by 'CHECK TABLE' cannot be
corrected automatically:

   * 'Found row where the auto_increment column has the value 0'.

     This means that you have a row in the table where the
     'AUTO_INCREMENT' index column contains the value 0.  (It is
     possible to create a row where the 'AUTO_INCREMENT' column is 0 by
     explicitly setting the column to 0 with an 'UPDATE'.
     statement.)

     This is not an error in itself, but could cause trouble if you
     decide to dump the table and restore it or do an 'ALTER TABLE'
     on the table.  In this case, the
     'AUTO_INCREMENT' column changes value according to the rules of
     'AUTO_INCREMENT' columns, which could cause problems such as a
     duplicate-key error.

     To get rid of the warning, execute an 'UPDATE'.
     statement to set the column to some value other than 0.

*CHECK TABLE Usage Notes for InnoDB Tables*

The following notes apply to 'InnoDB'.
tables:

   * If 'CHECK TABLE' encounters a corrupt page, the
     server exits to prevent error propagation (Bug #10132).  If the
     corruption occurs in a secondary index but table data is readable,
     running 'CHECK TABLE' can still cause a server
     exit.

   * If 'CHECK TABLE' encounters a corrupted
     'DB_TRX_ID' or 'DB_ROLL_PTR' field in a clustered index, see
     'CHECK TABLE' can cause 'InnoDB' to access an invalid
     undo log record, resulting in an MVCC-related server exit.

   * If 'CHECK TABLE' encounters errors in 'InnoDB'
     tables or indexes, it reports an error, and usually marks the index
     and sometimes marks the table as corrupted, preventing further use
     of the index or table.  Such errors include an incorrect number of
     entries in a secondary index or incorrect links.

   * If 'CHECK TABLE' finds an incorrect number of
     entries in a secondary index, it reports an error but does not
     cause a server exit or prevent access to the file.

   * 'CHECK TABLE' surveys the index page structure,
     then surveys each key entry.  It does not validate the key pointer
     to a clustered record or follow the path for 'BLOB'.
     pointers.

   * When an 'InnoDB' table is stored in its own '.ibd' file, the first
     3 pages of the '.ibd' file contain header information rather than
     table or index data.  The 'CHECK TABLE'.
     statement does not detect inconsistencies that affect only the
     header data.  To verify the entire contents of an 'InnoDB' '.ibd'
     file, use the 'innochecksum' command.

   * When running 'CHECK TABLE' on large 'InnoDB'
     tables, other threads may be blocked during 'CHECK TABLE'
     execution.  To avoid timeouts, the semaphore wait
     threshold (600 seconds) is extended by 2 hours (7200 seconds) for
     'CHECK TABLE' operations.  If 'InnoDB' detects
     semaphore waits of 240 seconds or more, it starts printing 'InnoDB'
     monitor output to the error log.  If a lock request extends beyond
     the semaphore wait threshold, 'InnoDB' aborts the process.  To
     avoid the possibility of a semaphore wait timeout entirely, run
     'CHECK TABLE QUICK' instead of 'CHECK TABLE'.

   * 'CHECK TABLE' functionality for 'InnoDB'
     'SPATIAL' indexes includes an R-tree validity check and a check to
     ensure that the R-tree row count matches the clustered index.

   * 'CHECK TABLE' supports secondary indexes on
     virtual generated columns, which are supported by 'InnoDB'.

*CHECK TABLE Usage Notes for MyISAM Tables*

The following notes apply to 'MyISAM'.
tables:

   * 'CHECK TABLE' updates key statistics for
     'MyISAM' tables.

   * If 'CHECK TABLE' output does not return 'OK' or
     'Table is already up to date', you should normally run a repair of
     the table.  See myisam-table-maintenance.

   * If none of the 'CHECK TABLE' options 'QUICK',
     'MEDIUM', or 'EXTENDED' are specified, the default check type for
     dynamic-format 'MyISAM' tables is 'MEDIUM'.  This has the same
     result as running 'myisamchk --medium-check TBL_NAME'
     on the table.  The default check type also is 'MEDIUM'
     for static-format 'MyISAM' tables, unless 'CHANGED' or 'FAST' is
     specified.  In that case, the default is 'QUICK'.  The row scan is
     skipped for 'CHANGED' and 'FAST' because the rows are very seldom
     corrupted.

13.7.2.3 CHECKSUM TABLE Syntax
..............................

     CHECKSUM TABLE TBL_NAME [, TBL_NAME] ... [QUICK | EXTENDED]

'CHECKSUM TABLE' reports a checksum for the
contents of a table.  You can use this statement to verify that the
contents are the same before and after a backup, rollback, or other
operation that is intended to put the data back to a known state.

This statement requires the 'SELECT' privilege for the table.

This statement is not supported for views.  If you run 'CHECKSUM TABLE'
against a view, the 'Checksum' value is always
'NULL', and a warning is returned.

For a nonexistent table, see 'CHECKSUM TABLE' returns
'NULL' and generates a warning.

During the checksum operation, the table is locked with a read lock for
'InnoDB' and 'MyISAM'.

*Performance Considerations*

By default, the entire table is read row by row and the checksum is
calculated.  For large tables, this could take a long time, thus you
would only perform this operation occasionally.  This row-by-row
calculation is what you get with the 'EXTENDED' clause, with 'InnoDB'
and all other storage engines other than 'MyISAM', and with 'MyISAM'
tables not created with the 'CHECKSUM=1' clause.

For 'MyISAM' tables created with the 'CHECKSUM=1' clause, see
'CHECKSUM TABLE' or 'CHECKSUM TABLE ... QUICK'
returns the 'live' table checksum that can be returned
very fast.  If the table does not meet all these conditions, the 'QUICK'
method returns 'NULL'.  The 'QUICK' method is not supported with
'InnoDB' tables.  See create-table for the syntax of the
'CHECKSUM' clause.

The checksum value depends on the table row format.  If the row format
changes, the checksum also changes.  For example, the storage format for
temporal types such as 'TIME', 'DATETIME',
and 'TIMESTAMP' changed in MySQL 5.6 prior to MySQL
5.6.5, so if a 5.5 table is upgraded to MySQL 5.6, the checksum value
may change.

*Important*:

If the checksums for two tables are different, then it is almost certain
that the tables are different in some way.  However, because the hashing
function used by 'CHECKSUM TABLE' is not
guaranteed to be collision-free, there is a slight chance that two
tables which are not identical can produce the same checksum.

13.7.2.4 OPTIMIZE TABLE Syntax
..............................

     OPTIMIZE [NO_WRITE_TO_BINLOG | LOCAL]
         TABLE TBL_NAME [, TBL_NAME] ...

'OPTIMIZE TABLE' reorganizes the physical storage
of table data and associated index data, to reduce storage space and
improve I/O efficiency when accessing the table.  The exact changes made
to each table depend on the storage engine used by that table.

Use 'OPTIMIZE TABLE' in these cases, depending on
the type of table:

   * After doing substantial insert, update, or delete operations on an
     'InnoDB' table that has its own .ibd file because it was created
     with the 'innodb_file_per_table' option enabled.  The table and
     indexes are reorganized, and disk space can be reclaimed for use by
     the operating system.

   * After doing substantial insert, update, or delete operations on
     columns that are part of a 'FULLTEXT' index in an 'InnoDB' table.
     Set the configuration option 'innodb_optimize_fulltext_only=1'
     first.  To keep the index maintenance period to a reasonable time,
     set the 'innodb_ft_num_word_optimize' option to specify how many
     words to update in the search index, and run a sequence of
     'OPTIMIZE TABLE' statements until the search index is fully
     updated.

   * After deleting a large part of a 'MyISAM' or 'ARCHIVE' table, or
     making many changes to a 'MyISAM' or 'ARCHIVE 'table with
     variable-length rows (tables that have 'VARCHAR',
     'VARBINARY', 'BLOB', or 'TEXT'
     columns).  Deleted rows are maintained in a linked list and
     subsequent 'INSERT' operations reuse old row
     positions.  You can use 'OPTIMIZE TABLE' to
     reclaim the unused space and to defragment the data file.  After
     extensive changes to a table, this statement may also improve
     performance of statements that use the table, sometimes
     significantly.

This statement requires 'SELECT' and 'INSERT' privileges for the table.

'OPTIMIZE TABLE' works for 'InnoDB',
see 'MyISAM', and
'ARCHIVE' tables.  'OPTIMIZE TABLE'
is also supported for dynamic columns of in-memory
'NDB' tables.  It does not work for fixed-width columns
of in-memory tables, nor does it work for Disk Data tables.  The
performance of 'OPTIMIZE' on NDB Cluster tables can be tuned using
'--ndb_optimization_delay', which controls the length of time to wait
between processing batches of rows by 'OPTIMIZE TABLE'.
For more information, see Previous NDB Cluster Issues
Resolved in NDB Cluster 7.3
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-limitations-resolved.html).

For NDB Cluster tables, see 'OPTIMIZE TABLE' can be
interrupted by (for example) killing the SQL thread performing the
'OPTIMIZE' operation.

By default, see 'OPTIMIZE TABLE' does _not_ work for
tables created using any other storage engine and returns a result
indicating this lack of support.  You can make 'OPTIMIZE TABLE'
work for other storage engines by starting
'mysqld' with the '--skip-new' option.  In this case, see
'OPTIMIZE TABLE' is just mapped to 'ALTER TABLE'.

This statement does not work with views.

'OPTIMIZE TABLE' is supported for partitioned
tables.  For information about using this statement with partitioned
tables and table partitions, see partitioning-maintenance.

By default, the server writes 'OPTIMIZE TABLE'.
statements to the binary log so that they replicate to replication
slaves.  To suppress logging, specify the optional 'NO_WRITE_TO_BINLOG'
keyword or its alias 'LOCAL'.

   * optimize-table-output

   * optimize-table-innodb-details

   * optimize-table-myisam-details

   * optimize-table-other-considerations

*OPTIMIZE TABLE Output*

'OPTIMIZE TABLE' returns a result set with the
columns shown in the following table.

Column      Value

'Table'     The table name

'Op'        Always 'optimize'

'Msg_type'  'status', 'error', 'info', 'note', or
            'warning'

'Msg_text'  An informational message

'OPTIMIZE TABLE' table catches and throws any
errors that occur while copying table statistics from the old file to
the newly created file.  For example.  if the user ID of the owner of
the '.frm', '.MYD', or '.MYI' file is different from the user ID of the
'mysqld' process, see 'OPTIMIZE TABLE'.
generates a "cannot change ownership of the file" error unless
'mysqld' is started by the 'root' user.

*InnoDB Details*

For 'InnoDB' tables, see 'OPTIMIZE TABLE' is mapped
to 'ALTER TABLE ... FORCE', which rebuilds the table
to update index statistics and free unused space in the clustered index.
This is displayed in the output of 'OPTIMIZE TABLE'
when you run it on an 'InnoDB' table, as shown here:

     mysql> OPTIMIZE TABLE foo;
     +----------+----------+----------+-------------------------------------------------------------------+
     | Table    | Op       | Msg_type | Msg_text                                                          |
     +----------+----------+----------+-------------------------------------------------------------------+
     | test.foo | optimize | note     | Table does not support optimize, doing recreate + analyze instead |
     | test.foo | optimize | status   | OK                                                                |
     +----------+----------+----------+-------------------------------------------------------------------+

'OPTIMIZE TABLE' uses online DDL
for regular and partitioned 'InnoDB' tables, which
reduces downtime for concurrent DML operations.  The table rebuild
triggered by 'OPTIMIZE TABLE' and performed under
the cover by 'ALTER TABLE ... FORCE' is completed in
place.  An exclusive table lock is only taken briefly during the prepare
phase and the commit phase of the operation.  During the prepare phase,
metadata is updated and an intermediate table is created.  During the
commit phase, table metadata changes are committed.

'OPTIMIZE TABLE' rebuilds the table using the
table copy method under the following conditions:

   * When the 'old_alter_table' system variable is enabled.

   * When the 'mysqld'. '--skip-new' option is enabled.

'OPTIMIZE TABLE' using online DDL
is not supported for 'InnoDB' tables that contain
'FULLTEXT' indexes.  The table copy method is used instead.

'InnoDB' stores data using a page-allocation method and does not suffer
from fragmentation in the same way that legacy storage engines (such as
'MyISAM') will.  When considering whether or not to run optimize,
consider the workload of transactions that your server will process:

   * Some level of fragmentation is expected.  'InnoDB' only fills pages
     93% full, to leave room for updates without having to split pages.

   * Delete operations might leave gaps that leave pages less filled
     than desired, which could make it worthwhile to optimize the table.

   * Updates to rows usually rewrite the data within the same page,
     depending on the data type and row format, when sufficient space is
     available.  See innodb-compression-internals and
     innodb-row-format-overview.

   * High-concurrency workloads might leave gaps in indexes over time,
     as 'InnoDB' retains multiple versions of the same data due through
     its MVCC mechanism.  See innodb-multi-versioning.

*MyISAM Details*

For 'MyISAM' tables, see 'OPTIMIZE TABLE' works as
follows:

  1. If the table has deleted or split rows, repair the table.

  2. If the index pages are not sorted, sort them.

  3. If the table's statistics are not up to date (and the repair could
     not be accomplished by sorting the index), update them.

*Other Considerations*

'OPTIMIZE TABLE' is performed online for regular
and partitioned 'InnoDB' tables.  Otherwise, MySQL locks the table
during the time 'OPTIMIZE TABLE' is running.

'OPTIMIZE TABLE' does not sort R-tree indexes,
such as spatial indexes on 'POINT' columns.  (Bug #23578)

13.7.2.5 REPAIR TABLE Syntax
............................

     REPAIR [NO_WRITE_TO_BINLOG | LOCAL]
         TABLE TBL_NAME [, TBL_NAME] ...
         [QUICK] [EXTENDED] [USE_FRM]

'REPAIR TABLE' repairs a possibly corrupted table,
for certain storage engines only.

This statement requires 'SELECT' and 'INSERT' privileges for the table.

Although normally you should never have to run 'REPAIR TABLE',
if disaster strikes, this statement is very likely to get
back all your data from a 'MyISAM' table.  If your tables become
corrupted often, try to find the reason for it, to eliminate the need to
use 'REPAIR TABLE'.  See crashing, and
myisam-table-problems.

'REPAIR TABLE' checks the table to see whether an
upgrade is required.  If so, it performs the upgrade, following the same
rules as 'CHECK TABLE ... FOR UPGRADE'.  See
check-table, for more information.

*Important*:

   * Make a backup of a table before performing a table repair
     operation; under some circumstances the operation might cause data
     loss.  Possible causes include but are not limited to file system
     errors.  See backup-and-recovery.

   * If the server crashes during a 'REPAIR TABLE'.
     operation, it is essential after restarting it that you immediately
     execute another 'REPAIR TABLE' statement for
     the table before performing any other operations on it.  In the
     worst case, you might have a new clean index file without
     information about the data file, and then the next operation you
     perform could overwrite the data file.  This is an unlikely but
     possible scenario that underscores the value of making a backup
     first.

   * In the event that a table on the master becomes corrupted and you
     run 'REPAIR TABLE' on it, any resulting
     changes to the original table are _not_ propagated to slaves.

   * repair-table-support

   * repair-table-options

   * repair-table-output

   * repair-table-table-repair-considerations

*REPAIR TABLE Storage Engine and Partitioning Support*

'REPAIR TABLE' works for 'MyISAM',
see 'ARCHIVE', and
'CSV' tables.  For 'MyISAM'
tables, it has the same effect as
'myisamchk --recover TBL_NAME' by default.  This statement
does not work with views.

'REPAIR TABLE' is supported for partitioned tables.
However, the 'USE_FRM' option cannot be used with this statement on a
partitioned table.

You can use 'ALTER TABLE ... REPAIR PARTITION' to repair one or more
partitions; for more information, see alter-table, and
partitioning-maintenance.

*REPAIR TABLE Options*

   * 'NO_WRITE_TO_BINLOG' or 'LOCAL'

     By default, the server writes 'REPAIR TABLE'.
     statements to the binary log so that they replicate to replication
     slaves.  To suppress logging, specify the optional
     'NO_WRITE_TO_BINLOG' keyword or its alias 'LOCAL'.

   * 'QUICK'

     If you use the 'QUICK' option, see 'REPAIR TABLE'.
     tries to repair only the index file, and not the data file.  This
     type of repair is like that done by 'myisamchk --recover --quick'.

   * 'EXTENDED'

     If you use the 'EXTENDED' option, MySQL creates the index row by
     row instead of creating one index at a time with sorting.  This
     type of repair is like that done by 'myisamchk --safe-recover'.

   * 'USE_FRM'

     The 'USE_FRM' option is available for use if the '.MYI' index file
     is missing or if its header is corrupted.  This option tells MySQL
     not to trust the information in the '.MYI' file header and to
     re-create it using information from the '.frm' file.  This kind of
     repair cannot be done with 'myisamchk'.

     *Caution*:

     Use the 'USE_FRM' option _only_ if you cannot use regular 'REPAIR'
     modes.  Telling the server to ignore the '.MYI' file makes
     important table metadata stored in the '.MYI' unavailable to the
     repair process, which can have deleterious consequences:

        * The current 'AUTO_INCREMENT' value is lost.

        * The link to deleted records in the table is lost, which means
          that free space for deleted records will remain unoccupied
          thereafter.

        * The '.MYI' header indicates whether the table is compressed.
          If the server ignores this information, it cannot tell that a
          table is compressed and repair can cause change or loss of
          table contents.  This means that 'USE_FRM' should not be used
          with compressed tables.  That should not be necessary, anyway:
          Compressed tables are read only, so they should not become
          corrupt.

     If you use 'USE_FRM' for a table that was created by a different
     version of the MySQL server than the one you are currently running,
     see 'REPAIR TABLE' does not attempt to repair the
     table.  In this case, the result set returned by 'REPAIR TABLE'
     contains a line with a 'Msg_type' value of
     'error' and a 'Msg_text' value of 'Failed repairing incompatible
     .FRM file'.

     If 'USE_FRM' is used, see 'REPAIR TABLE' does not
     check the table to see whether an upgrade is required.

*REPAIR TABLE Output*

'REPAIR TABLE' returns a result set with the
columns shown in the following table.

Column      Value

'Table'     The table name

'Op'        Always 'repair'

'Msg_type'  'status', 'error', 'info', 'note', or
            'warning'

'Msg_text'  An informational message

The 'REPAIR TABLE' statement might produce many
rows of information for each repaired table.  The last row has a
'Msg_type' value of 'status' and 'Msg_test' normally should be 'OK'.
For a 'MyISAM' table, if you do not get 'OK', you should try repairing
it with 'myisamchk --safe-recover'.  (see 'REPAIR TABLE'
does not implement all the options of
'myisamchk'.  With 'myisamchk --safe-recover',
you can also use options that 'REPAIR TABLE'
does not support, such as '--max-record-length'.)

'REPAIR TABLE' table catches and throws any errors
that occur while copying table statistics from the old corrupted file to
the newly created file.  For example.  if the user ID of the owner of
the '.frm', '.MYD', or '.MYI' file is different from the user ID of the
'mysqld' process, see 'REPAIR TABLE'.
generates a "cannot change ownership of the file" error unless
'mysqld' is started by the 'root' user.

*Table Repair Considerations*

'REPAIR TABLE' upgrades a table if it contains old
temporal columns in pre-5.6.4 format (see 'TIME',
'DATETIME', and 'TIMESTAMP' columns without
support for fractional seconds precision) and the
'avoid_temporal_upgrade' system variable is disabled.  If
'avoid_temporal_upgrade' is enabled, see 'REPAIR TABLE'.
ignores the old temporal columns present in the table and does not
upgrade them.

To upgrade tables that contain such temporal columns, disable
'avoid_temporal_upgrade' before executing 'REPAIR TABLE'.

You may be able to increase 'REPAIR TABLE'.
performance by setting certain system variables.  See
repair-table-optimization.

13.7.3 Plugin and User-Defined Function Statements
--------------------------------------------------

13.7.3.1 CREATE FUNCTION Syntax for User-Defined Functions
..........................................................

     CREATE [AGGREGATE] FUNCTION FUNCTION_NAME
         RETURNS {STRING|INTEGER|REAL|DECIMAL}
         SONAME SHARED_LIBRARY_NAME

A user-defined function (UDF) is a way to extend MySQL with a new
function that works like a native (built-in) MySQL function such as
'ABS()' or 'CONCAT()'.

FUNCTION_NAME is the name that should be used in SQL statements to
invoke the function.  The 'RETURNS' clause indicates the type of the
function's return value.  'DECIMAL' is a legal
value after 'RETURNS', but currently 'DECIMAL'.
functions return string values and should be written like 'STRING'
functions.

SHARED_LIBRARY_NAME is the base name of the shared library file that
contains the code that implements the function.  The file must be
located in the plugin directory.  This directory is given by the value
of the 'plugin_dir' system variable.  For more information, see
udf-compiling.

To create a function, you must have the 'INSERT' privilege for the
'mysql' database.  This is necessary because 'CREATE FUNCTION'
adds a row to the 'mysql.func' system table that
records the function's name, type, and shared library name.  If you do
not have this table, you should run the 'mysql_upgrade'
command to create it.  See mysql-upgrade.

An active function is one that has been loaded with 'CREATE FUNCTION'
and not removed with 'DROP FUNCTION'.
All active functions are reloaded each time the server
starts, unless you start 'mysqld' with the
'--skip-grant-tables' option.  In this case, UDF initialization is
skipped and UDFs are unavailable.

For instructions on writing user-defined functions, see
adding-udf.  For the UDF mechanism to work, functions must be written
in C or C++ (or another language that can use C calling conventions),
your operating system must support dynamic loading and you must have
compiled 'mysqld' dynamically (not statically).

An 'AGGREGATE' function works exactly like a native MySQL aggregate
(summary) function such as 'SUM' or 'COUNT()'.  For 'AGGREGATE' to work,
your 'mysql.func' table must contain a 'type' column.  If your
'mysql.func' table does not have this column, you should run the
'mysql_upgrade' program to create it (see
mysql-upgrade).

*Note*:

To upgrade the shared library associated with a UDF, issue a 'DROP FUNCTION'
statement, upgrade the shared library, and
then issue a 'CREATE FUNCTION' statement.  If
you upgrade the shared library first and then use 'DROP FUNCTION',
the server may crash.

13.7.3.2 DROP FUNCTION Syntax
.............................

     DROP FUNCTION FUNCTION_NAME

This statement drops the user-defined function (UDF) named
FUNCTION_NAME.

To drop a function, you must have the 'DELETE' privilege for the 'mysql'
database.  This is because 'DROP FUNCTION' removes
a row from the 'mysql.func' system table that records the function's
name, type, and shared library name.

*Note*:

To upgrade the shared library associated with a UDF, issue a 'DROP FUNCTION'
statement, upgrade the shared library, and
then issue a 'CREATE FUNCTION' statement.  If
you upgrade the shared library first and then use 'DROP FUNCTION',
the server may crash.

'DROP FUNCTION' is also used to drop stored
functions (see drop-procedure).

13.7.3.3 INSTALL PLUGIN Syntax
..............................

     INSTALL PLUGIN PLUGIN_NAME SONAME 'SHARED_LIBRARY_NAME'

This statement installs a server plugin.  It requires the 'INSERT'
privilege for the 'mysql.plugin' system table.

PLUGIN_NAME is the name of the plugin as defined in the plugin
descriptor structure contained in the library file (see
plugin-data-structures).  Plugin names are not case-sensitive.  For
maximal compatibility, plugin names should be limited to ASCII letters,
digits, and underscore because they are used in C source files, shell
command lines, M4 and Bourne shell scripts, and SQL environments.

SHARED_LIBRARY_NAME is the name of the shared library that contains the
plugin code.  The name includes the file name extension (for example,
'libmyplugin.so', 'libmyplugin.dll', or 'libmyplugin.dylib').

The shared library must be located in the plugin directory (the
directory named by the 'plugin_dir' system variable).  The library must
be in the plugin directory itself, not in a subdirectory.  By default,
'plugin_dir' is the 'plugin' directory under the directory named by the
'pkglibdir' configuration variable, but it can be changed by setting the
value of 'plugin_dir' at server startup.  For example, set its value in
a 'my.cnf' file:

     [mysqld]
     plugin_dir=/PATH/TO/PLUGIN/DIRECTORY

If the value of 'plugin_dir' is a relative path name, it is taken to be
relative to the MySQL base directory (the value of the 'basedir' system
variable).

'INSTALL PLUGIN' loads and initializes the plugin
code to make the plugin available for use.  A plugin is initialized by
executing its initialization function, which handles any setup that the
plugin must perform before it can be used.  When the server shuts down,
it executes the deinitialization function for each plugin that is loaded
so that the plugin has a chance to perform any final cleanup.

'INSTALL PLUGIN' also registers the plugin by
adding a line that indicates the plugin name and library file name to
the 'mysql.plugin' table.  At server startup, the server loads and
initializes any plugin that is listed in the 'mysql.plugin' table.  This
means that a plugin is installed with 'INSTALL PLUGIN'
only once, not every time the server starts.  Plugin
loading at startup does not occur if the server is started with the
'--skip-grant-tables' option.

A plugin library can contain multiple plugins.  For each of them to be
installed, use a separate 'INSTALL PLUGIN'.
statement.  Each statement names a different plugin, but all of them
specify the same library name.

'INSTALL PLUGIN' causes the server to read option
('my.cnf') files just as during server startup.  This enables the plugin
to pick up any relevant options from those files.  It is possible to add
plugin options to an option file even before loading a plugin (if the
'loose' prefix is used).  It is also possible to uninstall a plugin,
edit 'my.cnf', and install the plugin again.  Restarting the plugin this
way enables it to the new option values without a server restart.

For options that control individual plugin loading at server startup,
see server-plugin-loading.  If you need to load plugins for a
single server startup when the '--skip-grant-tables' option is given
(which tells the server not to read system tables), use the
'--plugin-load' option.  See server-options.

To remove a plugin, use the 'UNINSTALL PLUGIN'.
statement.

For additional information about plugin loading, see
server-plugin-loading.

To see what plugins are installed, use the 'SHOW PLUGINS'
statement or query the 'INFORMATION_SCHEMA.PLUGINS'
table.

If you recompile a plugin library and need to reinstall it, you can use
either of the following methods:

   * Use 'UNINSTALL PLUGIN' to uninstall all
     plugins in the library, install the new plugin library file in the
     plugin directory, and then use 'INSTALL PLUGIN'
     to install all plugins in the library.  This
     procedure has the advantage that it can be used without stopping
     the server.  However, if the plugin library contains many plugins,
     you must issue many 'INSTALL PLUGIN' and
     'UNINSTALL PLUGIN' statements.

   * Stop the server, install the new plugin library file in the plugin
     directory, and restart the server.

13.7.3.4 UNINSTALL PLUGIN Syntax
................................

     UNINSTALL PLUGIN PLUGIN_NAME

This statement removes an installed server plugin.  It requires the
'DELETE' privilege for the 'mysql.plugin' system table.
'UNINSTALL PLUGIN' is the complement of
'INSTALL PLUGIN'.

PLUGIN_NAME must be the name of some plugin that is listed in the
'mysql.plugin' table.  The server executes the plugin's deinitialization
function and removes the row for the plugin from the 'mysql.plugin'
table, so that subsequent server restarts will not load and initialize
the plugin.  'UNINSTALL PLUGIN' does not remove
the plugin's shared library file.

You cannot uninstall a plugin if any table that uses it is open.

Plugin removal has implications for the use of associated tables.  For
example, if a full-text parser plugin is associated with a 'FULLTEXT'
index on the table, uninstalling the plugin makes the table unusable.
Any attempt to access the table results in an error.  The table cannot
even be opened, so you cannot drop an index for which the plugin is
used.  This means that uninstalling a plugin is something to do with
care unless you do not care about the table contents.  If you are
uninstalling a plugin with no intention of reinstalling it later and you
care about the table contents, you should dump the table with
'mysqldump' and remove the 'WITH PARSER' clause from the
dumped 'CREATE TABLE' statement so that you can
reload the table later.  If you do not care about the table, see 'DROP TABLE'
can be used even if any plugins associated with the
table are missing.

For additional information about plugin loading, see
server-plugin-loading.

13.7.4 SET Syntax
-----------------

The 'SET' statement has several forms.
Descriptions for those forms that are not associated with a specific
server capability appear in subsections of this section:

   * 'SET VAR_NAME = VALUE' enables you to assign
     values to variables that affect the operation of the server or
     clients.  See set-variable.

   * 'SET CHARACTER SET' and 'SET NAMES'
     assign values to character set and collation
     variables associated with the current connection to the server.
     See set-character-set, and set-names.

Descriptions for the other forms appear elsewhere, grouped with other
statements related to the capability they help implement:

   * 'SET PASSWORD' assigns account passwords.  See
     set-password.

   * 'SET TRANSACTION ISOLATION LEVEL' sets the
     isolation level for transaction processing.  See
     set-transaction.

13.7.4.1 SET Syntax for Variable Assignment
...........................................

     SET VARIABLE_ASSIGNMENT [, VARIABLE_ASSIGNMENT] ...

     VARIABLE_ASSIGNMENT:
           USER_VAR_NAME = EXPR
         | PARAM_NAME = EXPR
         | LOCAL_VAR_NAME = EXPR
         | [GLOBAL | SESSION]
             SYSTEM_VAR_NAME = EXPR
         | [@@global. | @@session. | @@]
             SYSTEM_VAR_NAME = EXPR

'SET' syntax for variable assignment enables you to
assign values to different types of variables that affect the operation
of the server or clients:

   * System variables.  See server-system-variables.  System
     variables also can be set at server startup, as described in
     using-system-variables.  (To _display_ system variable names and
     values, use the 'SHOW VARIABLES' statement;
     see show-variables.)

   * User-defined variables.  See user-variables.

   * Stored procedure and function parameters, and stored program local
     variables.  See stored-program-variables.

A 'SET' statement that assigns variable values is
not written to the binary log, so in replication scenarios it affects
only the host on which you execute it.  To affect all replication hosts,
execute the statement on each one.

The following examples illustrate 'SET' syntax for
setting variables.  They use the '=' assignment operator, but the ':='
assignment operator is also permitted for this purpose.

A user variable is written as '@VAR_NAME' and is assigned an expression
value as follows:

     SET @VAR_NAME = EXPR;

Examples:

     SET @name = 43;
     SET @total_tax = (SELECT SUM(tax) FROM taxable_transactions);

The EXPR can range from simple (a literal value) to more complex (the
value returned by a scalar subquery).

'SET' applies to parameters and local variables in
the context of the stored object within which they are defined.  The
following procedure uses the 'counter' local variable as a loop counter:

     CREATE PROCEDURE p()
     BEGIN
       DECLARE counter INT DEFAULT 0;
       WHILE counter < 10 DO
         -- ... do work ...
         SET counter = counter + 1;
       END WHILE;
     END;

Many system variables are dynamic and can be changed at runtime by using
the 'SET' statement.  For a list, see
dynamic-system-variables.  To change a system variable with
'SET', refer to it by name, optionally preceded by a
modifier:

   * To indicate that a variable is a global variable, precede its name
     by the 'GLOBAL' keyword or the '@@global.' qualifier:

          SET GLOBAL max_connections = 1000;
          SET @@global.max_connections = 1000;

     The 'SUPER' privilege is required to set global variables.

   * To indicate that a variable is a session variable, precede its name
     by the 'SESSION' keyword or either the '@@session.' or '@@'
     qualifier:

          SET SESSION sql_mode = 'TRADITIONAL';
          SET @@session.sql_mode = 'TRADITIONAL';
          SET @@sql_mode = 'TRADITIONAL';

     Setting a session variable normally requires no special privilege,
     although there are exceptions that require the 'SUPER' privilege
     (such as 'sql_log_bin').  A client can change its own session
     variables, but not those of any other client.

   * 'LOCAL' and '@@local.' are synonyms for 'SESSION' and '@@session.'.

   * If no modifier is present, see 'SET' changes the
     session variable.

   * An error occurs under these circumstances:

        * Use of 'SET GLOBAL'. (or '@@global.') when
          setting a variable that has only a session value:

               mysql> SET GLOBAL sql_log_bin = ON;
               ERROR 1231 (42000): Variable 'sql_log_bin' can't be
               set to the value of 'ON'

        * Omission of 'GLOBAL' (or '@@global.') when setting a variable
          that has only a global value:

               mysql> SET max_connections = 1000;
               ERROR 1229 (HY000): Variable 'max_connections' is a
               GLOBAL variable and should be set with SET GLOBAL

        * Use of 'SET SESSION'. (or '@@SESSION.')
          when setting a variable that has only a global value:

               mysql> SET SESSION max_connections = 1000;
               ERROR 1229 (HY000): Variable 'max_connections' is a
               GLOBAL variable and should be set with SET GLOBAL

The preceding modifiers apply only to system variables.  An error occurs
for attempts to apply them to user-defined variables, stored procedure
or function parameters, or stored program local variables.

A 'SET' statement can contain multiple variable
assignments, separated by commas.  This statement assigns values to a
user-defined variable and a system variable:

     SET @x = 1, SESSION sql_mode = '';

If you set multiple system variables, the most recent 'GLOBAL' or
'SESSION' modifier in the statement is used for following assignments
that have no modifier specified.

Examples of multiple-variable assignment:

     SET GLOBAL sort_buffer_size = 1000000, SESSION sort_buffer_size = 1000000;
     SET @@global.sort_buffer_size = 1000000, @@local.sort_buffer_size = 1000000;
     SET GLOBAL max_connections = 1000, sort_buffer_size = 1000000;

If any variable assignment in a 'SET' statement
fails, the entire statement fails and no variables are changed.

If you change a session system variable, the value remains in effect
within your session until you change the variable to a different value
or the session ends.  The change has no effect on other sessions.

If you change a global system variable, the value is remembered and used
for new sessions until you change the variable to a different value or
the server exits.  The change is visible to any client that accesses the
global variable.  However, the change affects the corresponding session
variable only for clients that connect after the change.  The global
variable change does not affect the session variable for any current
client sessions (not even the session within which the 'SET GLOBAL'
statement occurred).

To make a global system variable setting permanent so that it applies
across server restarts, you should also set it in an option file.

To set a 'GLOBAL' value to the compiled-in MySQL default value or a
'SESSION' variable to the current corresponding 'GLOBAL' value, set the
variable to the value 'DEFAULT'.  For example, the following two
statements are identical in setting the session value of 'max_join_size'
to the current global value:

     SET @@session.max_join_size=DEFAULT;
     SET @@session.max_join_size=@@global.max_join_size;

Not all system variables can be set to 'DEFAULT'.  In such cases,
assigning 'DEFAULT' results in an error.

An error occurs for attempts to assign 'DEFAULT' to user-defined
variables, stored procedure or function parameters, or stored program
local variables.

To refer to the value of a system variable in expressions, use one of
the '@@'-modifiers.  For example, you can retrieve values in a
'SELECT' statement like this:

     SELECT @@global.sql_mode, @@session.sql_mode, @@sql_mode;

For a reference to a system variable in an expression as '@@VAR_NAME'
(rather than with '@@global.' or '@@session.'), MySQL returns the
session value if it exists and the global value otherwise.  This differs
from 'SET @@VAR_NAME = EXPR', which always refers to the session value.

13.7.4.2 SET CHARACTER SET Syntax
.................................

     SET {CHARACTER SET | CHARSET}
         {'CHARSET_NAME' | DEFAULT}

This statement maps all strings sent between the server and the current
client with the given mapping.  'SET CHARACTER SET' sets three session
system variables: 'character_set_client' and 'character_set_results' are
set to the given character set, and 'character_set_connection' to the
value of 'character_set_database'.  See charset-connection.

CHARSET_NAME may be quoted or unquoted.

The default character set mapping can be restored by using the value
'DEFAULT'.  The default depends on the server configuration.

'ucs2', 'utf16', and 'utf32' cannot be used as a client character set,
which means that they do not work for 'SET CHARACTER SET'.

13.7.4.3 SET NAMES Syntax
.........................

     SET NAMES {'CHARSET_NAME'
         [COLLATE 'COLLATION_NAME'] | DEFAULT}

This statement sets the three session system variables
'character_set_client', 'character_set_connection', and
'character_set_results' to the given character set.  Setting
'character_set_connection' to 'charset_name' also sets
'collation_connection' to the default collation for 'charset_name'.  See
charset-connection.

The optional 'COLLATE' clause may be used to specify a collation
explicitly.  If given, the collation must one of the permitted
collations for CHARSET_NAME.

CHARSET_NAME and COLLATION_NAME may be quoted or unquoted.

The default mapping can be restored by using a value of 'DEFAULT'.  The
default depends on the server configuration.

'ucs2', 'utf16', and 'utf32' cannot be used as a client character set,
which means that they do not work for 'SET NAMES'.

13.7.5 SHOW Syntax
------------------

'SHOW' has many forms that provide information about
databases, tables, columns, or status information about the server.
This section describes those following:

     SHOW {BINARY | MASTER} LOGS
     SHOW BINLOG EVENTS [IN 'LOG_NAME'] [FROM POS] [LIMIT [OFFSET,] ROW_COUNT]
     SHOW CHARACTER SET [LIKE_OR_WHERE]
     SHOW COLLATION [LIKE_OR_WHERE]
     SHOW [FULL] COLUMNS FROM TBL_NAME [FROM DB_NAME] [LIKE_OR_WHERE]
     SHOW CREATE DATABASE DB_NAME
     SHOW CREATE EVENT EVENT_NAME
     SHOW CREATE FUNCTION FUNC_NAME
     SHOW CREATE PROCEDURE PROC_NAME
     SHOW CREATE TABLE TBL_NAME
     SHOW CREATE TRIGGER TRIGGER_NAME
     SHOW CREATE VIEW VIEW_NAME
     SHOW DATABASES [LIKE_OR_WHERE]
     SHOW ENGINE ENGINE_NAME {STATUS | MUTEX}
     SHOW [STORAGE] ENGINES
     SHOW ERRORS [LIMIT [OFFSET,] ROW_COUNT]
     SHOW EVENTS
     SHOW FUNCTION CODE FUNC_NAME
     SHOW FUNCTION STATUS [LIKE_OR_WHERE]
     SHOW GRANTS FOR USER
     SHOW INDEX FROM TBL_NAME [FROM DB_NAME]
     SHOW MASTER STATUS
     SHOW OPEN TABLES [FROM DB_NAME] [LIKE_OR_WHERE]
     SHOW PLUGINS
     SHOW PROCEDURE CODE PROC_NAME
     SHOW PROCEDURE STATUS [LIKE_OR_WHERE]
     SHOW PRIVILEGES
     SHOW [FULL] PROCESSLIST
     SHOW PROFILE [TYPES] [FOR QUERY N] [OFFSET N] [LIMIT N]
     SHOW PROFILES
     SHOW RELAYLOG EVENTS [IN 'LOG_NAME'] [FROM POS] [LIMIT [OFFSET,] ROW_COUNT]
     SHOW SLAVE HOSTS
     SHOW SLAVE STATUS [FOR CHANNEL CHANNEL]
     SHOW [GLOBAL | SESSION] STATUS [LIKE_OR_WHERE]
     SHOW TABLE STATUS [FROM DB_NAME] [LIKE_OR_WHERE]
     SHOW [FULL] TABLES [FROM DB_NAME] [LIKE_OR_WHERE]
     SHOW TRIGGERS [FROM DB_NAME] [LIKE_OR_WHERE]
     SHOW [GLOBAL | SESSION] VARIABLES [LIKE_OR_WHERE]
     SHOW WARNINGS [LIMIT [OFFSET,] ROW_COUNT]

     LIKE_OR_WHERE:
         LIKE 'PATTERN'
       | WHERE EXPR

If the syntax for a given 'SHOW' statement includes a 'LIKE
'PATTERN'' part, ''PATTERN'' is a string that can contain the SQL '%'
and '_' wildcard characters.  The pattern is useful for restricting
statement output to matching values.

Several 'SHOW' statements also accept a 'WHERE' clause that
provides more flexibility in specifying which rows to display.  See
extended-show.

Many MySQL APIs (such as PHP) enable you to treat the result returned
from a 'SHOW' statement as you would a result set from a
'SELECT'.; see connectors-apis, or your API
documentation for more information.  In addition, you can work in SQL
with results from queries on tables in the 'INFORMATION_SCHEMA'
database, which you cannot easily do with results from 'SHOW'
statements.  See information-schema.

13.7.5.1 SHOW BINARY LOGS Syntax
................................

     SHOW BINARY LOGS
     SHOW MASTER LOGS

Lists the binary log files on the server.  This statement is used as
part of the procedure described in purge-binary-logs, that shows
how to determine which logs can be purged.

     mysql> SHOW BINARY LOGS;
     +---------------+-----------+
     | Log_name      | File_size |
     +---------------+-----------+
     | binlog.000015 |    724935 |
     | binlog.000016 |    733481 |
     +---------------+-----------+

'SHOW MASTER LOGS' is equivalent to 'SHOW BINARY LOGS'.

A user with the 'SUPER' or 'REPLICATION CLIENT' privilege may execute
this statement.

13.7.5.2 SHOW BINLOG EVENTS Syntax
..................................

     SHOW BINLOG EVENTS
        [IN 'LOG_NAME']
        [FROM POS]
        [LIMIT [OFFSET,] ROW_COUNT]

Shows the events in the binary log.  If you do not specify ''LOG_NAME'',
the first binary log is displayed.

The 'LIMIT' clause has the same syntax as for the 'SELECT'
statement.  See select.

*Note*:

Issuing a 'SHOW BINLOG EVENTS' with no
'LIMIT' clause could start a very time- and resource-consuming process
because the server returns to the client the complete contents of the
binary log (which includes all statements executed by the server that
modify data).  As an alternative to 'SHOW BINLOG EVENTS',
use the 'mysqlbinlog' utility to
save the binary log to a text file for later examination and analysis.
See mysqlbinlog.

'SHOW BINLOG EVENTS' displays the following
fields for each event in the binary log:

   * 'Log_name'

     The name of the file that is being listed.

   * 'Pos'

     The position at which the event occurs.

   * 'Event_type'

     An identifier that describes the event type.

   * 'Server_id'

     The server ID of the server on which the event originated.

   * 'End_log_pos'

     The position at which the next event begins, which is equal to
     'Pos' plus the size of the event.

   * 'Info'

     More detailed information about the event type.  The format of this
     information depends on the event type.

*Note*:

Some events relating to the setting of user and system variables are not
included in the output from 'SHOW BINLOG EVENTS'.
To get complete coverage of events within a binary
log, use 'mysqlbinlog'.

*Note*:

'SHOW BINLOG EVENTS' does _not_ work with
relay log files.  You can use 'SHOW RELAYLOG EVENTS'
for this purpose.

13.7.5.3 SHOW CHARACTER SET Syntax
..................................

     SHOW CHARACTER SET
         [LIKE 'PATTERN' | WHERE EXPR]

The 'SHOW CHARACTER SET' statement shows all
available character sets.  The 'LIKE' clause, if present, indicates
which character set names to match.  The 'WHERE' clause can be given to
select rows using more general conditions, as discussed in
extended-show.  For example:

     mysql> SHOW CHARACTER SET LIKE 'latin%';
     +---------+-----------------------------+-------------------+--------+
     | Charset | Description                 | Default collation | Maxlen |
     +---------+-----------------------------+-------------------+--------+
     | latin1  | cp1252 West European        | latin1_swedish_ci |      1 |
     | latin2  | ISO 8859-2 Central European | latin2_general_ci |      1 |
     | latin5  | ISO 8859-9 Turkish          | latin5_turkish_ci |      1 |
     | latin7  | ISO 8859-13 Baltic          | latin7_general_ci |      1 |
     +---------+-----------------------------+-------------------+--------+

The 'Maxlen' column shows the maximum number of bytes required to store
one character.

The 'filename' character set is for internal use only; consequently,
see 'SHOW CHARACTER SET' does not display it.

You can also obtain information about character sets from
'INFORMATION_SCHEMA', which contains a 'CHARACTER_SETS'
table.  See character-sets-table.

13.7.5.4 SHOW COLLATION Syntax
..............................

     SHOW COLLATION
         [LIKE 'PATTERN' | WHERE EXPR]

This statement lists collations supported by the server.  By default,
the output from 'SHOW COLLATION' includes all
available collations.  The 'LIKE' clause, if present, indicates which
collation names to match.  The 'WHERE' clause can be given to select
rows using more general conditions, as discussed in
extended-show.  For example:

     mysql> SHOW COLLATION WHERE Charset = 'latin1';
     +-------------------+---------+----+---------+----------+---------+
     | Collation         | Charset | Id | Default | Compiled | Sortlen |
     +-------------------+---------+----+---------+----------+---------+
     | latin1_german1_ci | latin1  |  5 |         | Yes      |       1 |
     | latin1_swedish_ci | latin1  |  8 | Yes     | Yes      |       1 |
     | latin1_danish_ci  | latin1  | 15 |         | Yes      |       1 |
     | latin1_german2_ci | latin1  | 31 |         | Yes      |       2 |
     | latin1_bin        | latin1  | 47 |         | Yes      |       1 |
     | latin1_general_ci | latin1  | 48 |         | Yes      |       1 |
     | latin1_general_cs | latin1  | 49 |         | Yes      |       1 |
     | latin1_spanish_ci | latin1  | 94 |         | Yes      |       1 |
     +-------------------+---------+----+---------+----------+---------+

The 'Collation' and 'Charset' columns indicate the names of the
collation and the character set with which it is associated.  'Id' is
the collation ID. 'Default' indicates whether the collation is the
default for its character set.  'Compiled' indicates whether the
character set is compiled into the server.  'Sortlen' is related to the
amount of memory required to sort strings expressed in the character
set.

To see the default collation for each character set, use the following
statement.  'Default' is a reserved word, so to use it as an identifier,
it must be quoted as such:

     mysql> SHOW COLLATION WHERE `Default` = 'Yes';
     +---------------------+----------+----+---------+----------+---------+
     | Collation           | Charset  | Id | Default | Compiled | Sortlen |
     +---------------------+----------+----+---------+----------+---------+
     | big5_chinese_ci     | big5     |  1 | Yes     | Yes      |       1 |
     | dec8_swedish_ci     | dec8     |  3 | Yes     | Yes      |       1 |
     | cp850_general_ci    | cp850    |  4 | Yes     | Yes      |       1 |
     | hp8_english_ci      | hp8      |  6 | Yes     | Yes      |       1 |
     | koi8r_general_ci    | koi8r    |  7 | Yes     | Yes      |       1 |
     | latin1_swedish_ci   | latin1   |  8 | Yes     | Yes      |       1 |
     ...

You can also obtain information about collations from
'INFORMATION_SCHEMA', which contains a 'COLLATIONS'
table.  See collations-table.

13.7.5.5 SHOW COLUMNS Syntax
............................

     SHOW [FULL] {COLUMNS | FIELDS}
         {FROM | IN} TBL_NAME
         [{FROM | IN} DB_NAME]
         [LIKE 'PATTERN' | WHERE EXPR]

'SHOW COLUMNS' displays information about the
columns in a given table.  It also works for views.  'SHOW COLUMNS'
displays information only for those columns for
which you have some privilege.

You can use DB_NAME.TBL_NAME as an alternative to the 'TBL_NAME FROM
DB_NAME' syntax.  In other words, these two statements are equivalent:

     SHOW COLUMNS FROM mytable FROM mydb;
     SHOW COLUMNS FROM mydb.mytable;

The optional 'FULL' keyword causes the output to include the column
collation and comments, as well as the privileges you have for each
column.

The 'LIKE' clause, if present, indicates which column names to match.
The 'WHERE' clause can be given to select rows using more general
conditions, as discussed in extended-show.

     mysql> SHOW COLUMNS FROM City;
     +-------------+----------+------+-----+---------+----------------+
     | Field       | Type     | Null | Key | Default | Extra          |
     +-------------+----------+------+-----+---------+----------------+
     | ID          | int(11)  | NO   | PRI | NULL    | auto_increment |
     | Name        | char(35) | NO   |     |         |                |
     | CountryCode | char(3)  | NO   | MUL |         |                |
     | District    | char(20) | NO   |     |         |                |
     | Population  | int(11)  | NO   |     | 0       |                |
     +-------------+----------+------+-----+---------+----------------+

The data types may differ from what you expect them to be based on a
'CREATE TABLE' statement because MySQL sometimes
changes data types when you create or alter a table.  The conditions
under which this occurs are described in silent-column-changes.

'SHOW COLUMNS' displays the following values for
each table column:

   * 'Field'

     The column name.

   * 'Type'

     The column data type.

   * 'Collation'

     The collation for nonbinary string columns, or 'NULL' for other
     columns.  This value is displayed only if you use the 'FULL'
     keyword.

   * 'Null'

     Column nullability.  The value is 'YES' if 'NULL' values can be
     stored in the column, 'NO' if not.

   * 'Key'

     Whether the column is indexed:

        * If 'Key' is empty, the column either is not indexed or is
          indexed only as a secondary column in a multiple-column,
          nonunique index.

        * If 'Key' is 'PRI', the column is a 'PRIMARY KEY' or is one of
          the columns in a multiple-column 'PRIMARY KEY'.

        * If 'Key' is 'UNI', the column is the first column of a
          'UNIQUE' index.  (A 'UNIQUE' index permits multiple 'NULL'
          values, but you can tell whether the column permits 'NULL' by
          checking the 'Null' field.)

        * If 'Key' is 'MUL', the column is the first column of a
          nonunique index in which multiple occurrences of a given value
          are permitted within the column.

     If more than one of the 'Key' values applies to a given column of a
     table, 'Key' displays the one with the highest priority, in the
     order 'PRI', 'UNI', 'MUL'.

     A 'UNIQUE' index may be displayed as 'PRI' if it cannot contain
     'NULL' values and there is no 'PRIMARY KEY' in the table.  A
     'UNIQUE' index may display as 'MUL' if several columns form a
     composite 'UNIQUE' index; although the combination of the columns
     is unique, each column can still hold multiple occurrences of a
     given value.

   * 'Default'

     The default value for the column.  This is 'NULL' if the column has
     an explicit default of 'NULL', or if the column definition includes
     no 'DEFAULT' clause.

   * 'Extra'

     Any additional information that is available about a given column.
     The value is nonempty in these cases:

        * 'auto_increment' for columns that have the 'AUTO_INCREMENT'
          attribute

        * 'on update CURRENT_TIMESTAMP' for 'TIMESTAMP'.
          or 'DATETIME' columns that have the 'ON
          UPDATE CURRENT_TIMESTAMP' attribute

        * 'VIRTUAL GENERATED' or 'VIRTUAL STORED' for generated columns

   * 'Privileges'

     The privileges you have for the column.  This value is displayed
     only if you use the 'FULL' keyword.

   * 'Comment'

     Any comment included in the column definition.  This value is
     displayed only if you use the 'FULL' keyword.

You can also obtain information about table columns from
'INFORMATION_SCHEMA', which contains a 'COLUMNS'.
table.  See columns-table.

You can list a table's columns with the 'mysqlshow DB_NAME TBL_NAME'
command.

The 'DESCRIBE' statement provides information similar
to 'SHOW COLUMNS'.  See describe.

The 'SHOW CREATE TABLE', 'SHOW TABLE STATUS',
and 'SHOW INDEX'.
statements also provide information about tables.  See show.

13.7.5.6 SHOW CREATE DATABASE Syntax
....................................

     SHOW CREATE {DATABASE | SCHEMA} [IF NOT EXISTS] DB_NAME

Shows the 'CREATE DATABASE' statement that
creates the named database.  If the 'SHOW' statement includes an 'IF NOT
EXISTS' clause, the output too includes such a clause.  'SHOW CREATE SCHEMA'
is a synonym for 'SHOW CREATE DATABASE'.

     mysql> SHOW CREATE DATABASE test\G
     *************************** 1. row ***************************
            Database: test
     Create Database: CREATE DATABASE `test`
                      /*!40100 DEFAULT CHARACTER SET latin1 */

     mysql> SHOW CREATE SCHEMA test\G
     *************************** 1. row ***************************
            Database: test
     Create Database: CREATE DATABASE `test`
                      /*!40100 DEFAULT CHARACTER SET latin1 */

'SHOW CREATE DATABASE' quotes table and
column names according to the value of the 'sql_quote_show_create'
option.  See server-system-variables.

13.7.5.7 SHOW CREATE EVENT Syntax
.................................

     SHOW CREATE EVENT EVENT_NAME

This statement displays the 'CREATE EVENT'.
statement needed to re-create a given event.  It requires the 'EVENT'
privilege for the database from which the event is to be shown.  For
example (using the same event 'e_daily' defined and then altered in
show-events):

     mysql> SHOW CREATE EVENT test.e_daily\G
     *************************** 1. row ***************************
                    Event: e_daily
                 sql_mode:
                time_zone: SYSTEM
             Create Event: CREATE EVENT `e_daily`
                             ON SCHEDULE EVERY 1 DAY
                             STARTS CURRENT_TIMESTAMP + INTERVAL 6 HOUR
                             ON COMPLETION NOT PRESERVE
                             ENABLE
                             COMMENT 'Saves total number of sessions then
                                     clears the table each day'
                             DO BEGIN
                               INSERT INTO site_activity.totals (time, total)
                                 SELECT CURRENT_TIMESTAMP, COUNT(*)
                                 FROM site_activity.sessions;
                               DELETE FROM site_activity.sessions;
                             END
     character_set_client: latin1
     collation_connection: latin1_swedish_ci
       Database Collation: latin1_swedish_ci

'character_set_client' is the session value of the
'character_set_client' system variable when the event was created.
'collation_connection' is the session value of the
'collation_connection' system variable when the event was created.
'Database Collation' is the collation of the database with which the
event is associated.

The output reflects the current status of the event ('ENABLE') rather
than the status with which it was created.

13.7.5.8 SHOW CREATE FUNCTION Syntax
....................................

     SHOW CREATE FUNCTION FUNC_NAME

This statement is similar to 'SHOW CREATE PROCEDURE'
but for stored functions.  See
show-create-procedure.

13.7.5.9 SHOW CREATE PROCEDURE Syntax
.....................................

     SHOW CREATE PROCEDURE PROC_NAME

This statement is a MySQL extension.  It returns the exact string that
can be used to re-create the named stored procedure.  A similar
statement, see 'SHOW CREATE FUNCTION', displays
information about stored functions (see show-create-function).

To use either statement, you must be the user named in the routine
'DEFINER' clause or have 'SELECT' access to the
'mysql.proc' table.  If you do not have privileges for the routine
itself, the value displayed for the 'Create Procedure' or 'Create
Function' field will be 'NULL'.

     mysql> SHOW CREATE PROCEDURE test.simpleproc\G
     *************************** 1. row ***************************
                Procedure: simpleproc
                 sql_mode:
         Create Procedure: CREATE PROCEDURE `simpleproc`(OUT param1 INT)
                           BEGIN
                           SELECT COUNT(*) INTO param1 FROM t;
                           END
     character_set_client: latin1
     collation_connection: latin1_swedish_ci
       Database Collation: latin1_swedish_ci

     mysql> SHOW CREATE FUNCTION test.hello\G
     *************************** 1. row ***************************
                 Function: hello
                 sql_mode:
          Create Function: CREATE FUNCTION `hello`(s CHAR(20))
                           RETURNS CHAR(50)
                           RETURN CONCAT('Hello, ',s,'!')
     character_set_client: latin1
     collation_connection: latin1_swedish_ci
       Database Collation: latin1_swedish_ci

'character_set_client' is the session value of the
'character_set_client' system variable when the routine was created.
'collation_connection' is the session value of the
'collation_connection' system variable when the routine was created.
'Database Collation' is the collation of the database with which the
routine is associated.

13.7.5.10 SHOW CREATE TABLE Syntax
..................................

     SHOW CREATE TABLE TBL_NAME

Shows the 'CREATE TABLE' statement that creates the
named table.  To use this statement, you must have some privilege for
the table.  This statement also works with views.

     mysql> SHOW CREATE TABLE t\G
     *************************** 1. row ***************************
            Table: t
     Create Table: CREATE TABLE `t` (
       `id` int(11) NOT NULL AUTO_INCREMENT,
       `s` char(60) DEFAULT NULL,
       PRIMARY KEY (`id`)
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1

'SHOW CREATE TABLE' quotes table and column
names according to the value of the 'sql_quote_show_create' option.  See
server-system-variables.

For information about how 'CREATE TABLE' statements
are stored by MySQL, see create-table-statement-retention.

13.7.5.11 SHOW CREATE TRIGGER Syntax
....................................

     SHOW CREATE TRIGGER TRIGGER_NAME

This statement shows the 'CREATE TRIGGER'.
statement that creates the named trigger.  This statement requires the
'TRIGGER' privilege for the table associated with the trigger.

     mysql> SHOW CREATE TRIGGER ins_sum\G
     *************************** 1. row ***************************
                    Trigger: ins_sum
                   sql_mode: STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION
     SQL Original Statement: CREATE DEFINER=`me`@`localhost` TRIGGER ins_sum
                             BEFORE INSERT ON account
                             FOR EACH ROW SET @sum = @sum + NEW.amount
       character_set_client: utf8
       collation_connection: utf8_general_ci
         Database Collation: latin1_swedish_ci
                    Created: 2013-07-09 10:39:34.96

'SHOW CREATE TRIGGER' output has the
following columns:

   * 'Trigger': The trigger name.

   * 'sql_mode': The SQL mode in effect when the trigger executes.

   * 'SQL Original Statement': The 'CREATE TRIGGER'
     statement that defines the trigger.

   * 'character_set_client': The session value of the
     'character_set_client' system variable when the trigger was
     created.

   * 'collation_connection': The session value of the
     'collation_connection' system variable when the trigger was
     created.

   * 'Database Collation': The collation of the database with which the
     trigger is associated.

   * 'Created': The date and time when the trigger was created.  This is
     a 'TIMESTAMP(2)' value (with a fractional part in hundredths of
     seconds) for triggers created in MySQL 5.7.2 or later, 'NULL' for
     triggers created prior to 5.7.2.  This column was added in MySQL
     5.7.2.

You can also obtain information about trigger objects from
'INFORMATION_SCHEMA', which contains a 'TRIGGERS'.
table.  See triggers-table.

13.7.5.12 SHOW CREATE USER Syntax
.................................

     SHOW CREATE USER USER

This statement shows the 'CREATE USER' statement
that creates the named user.  An error occurs if the user does not
exist.  The statement requires the 'SELECT' privilege for the 'mysql'
database, except to display information for the current user.

To name the account, use the format described in account-names.
The host name part of the account name, if omitted, defaults to ''%''.
It is also possible to specify 'CURRENT_USER' or 'CURRENT_USER()' to
refer to the account associated with the current session.

     mysql> SHOW CREATE USER 'root'@'localhost'\G
     *************************** 1. row ***************************
     CREATE USER for root@localhost: CREATE USER 'root'@'localhost'
     IDENTIFIED WITH 'mysql_native_password'
     AS '*2470C0C06DEE42FD1618BB99005ADCA2EC9D1E19'
     REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK

The output format is affected by the setting of the
'log_builtin_as_identified_by_password' system variable.

To display the privileges granted to an account, use the 'SHOW GRANTS'
statement.  See show-grants.

13.7.5.13 SHOW CREATE VIEW Syntax
.................................

     SHOW CREATE VIEW VIEW_NAME

This statement shows the 'CREATE VIEW' statement
that creates the named view.

     mysql> SHOW CREATE VIEW v\G
     *************************** 1. row ***************************
                     View: v
              Create View: CREATE ALGORITHM=UNDEFINED
                           DEFINER=`bob`@`localhost`
                           SQL SECURITY DEFINER VIEW
                           `v` AS select 1 AS `a`,2 AS `b`
     character_set_client: latin1
     collation_connection: latin1_swedish_ci

'character_set_client' is the session value of the
'character_set_client' system variable when the view was created.
'collation_connection' is the session value of the
'collation_connection' system variable when the view was created.

Use of 'SHOW CREATE VIEW' requires the 'SHOW
VIEW' privilege, and the 'SELECT' privilege for the view in question.

You can also obtain information about view objects from
'INFORMATION_SCHEMA', which contains a 'VIEWS'.
table.  See views-table.

MySQL lets you use different 'sql_mode' settings to tell the server the
type of SQL syntax to support.  For example, you might use the 'ANSI'
SQL mode to ensure MySQL correctly interprets the standard SQL
concatenation operator, the double bar ('||'), in your queries.  If you
then create a view that concatenates items, you might worry that
changing the 'sql_mode' setting to a value different from 'ANSI' could
cause the view to become invalid.  But this is not the case.  No matter
how you write out a view definition, MySQL always stores it the same
way, in a canonical form.  Here is an example that shows how the server
changes a double bar concatenation operator to a 'CONCAT()' function:

     mysql> SET sql_mode = 'ANSI';
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE VIEW test.v AS SELECT 'a' || 'b' as col1;
     Query OK, 0 rows affected (0.01 sec)

     mysql> SHOW CREATE VIEW test.v\G
     *************************** 1. row ***************************
                     View: v
              Create View: CREATE VIEW "v" AS select concat('a','b') AS "col1"
     ...
     1 row in set (0.00 sec)

The advantage of storing a view definition in canonical form is that
changes made later to the value of 'sql_mode' will not affect the
results from the view.  However an additional consequence is that
comments prior to 'SELECT' are stripped from the
definition by the server.

13.7.5.14 SHOW DATABASES Syntax
...............................

     SHOW {DATABASES | SCHEMAS}
         [LIKE 'PATTERN' | WHERE EXPR]

'SHOW DATABASES' lists the databases on the MySQL
server host.  'SHOW SCHEMAS' is a synonym for
'SHOW DATABASES'.  The 'LIKE' clause, if present,
indicates which database names to match.  The 'WHERE' clause can be
given to select rows using more general conditions, as discussed in
extended-show.

You see only those databases for which you have some kind of privilege,
unless you have the global 'SHOW DATABASES'.
privilege.  You can also get this list using the 'mysqlshow'
command.

If the server was started with the '--skip-show-database' option, you
cannot use this statement at all unless you have the 'SHOW DATABASES'
privilege.

MySQL implements databases as directories in the data directory, so this
statement simply lists directories in that location.  However, the
output may include names of directories that do not correspond to actual
databases.

13.7.5.15 SHOW ENGINE Syntax
............................

     SHOW ENGINE ENGINE_NAME {STATUS | MUTEX}

'SHOW ENGINE' displays operational information about
a storage engine.  It requires the 'PROCESS' privilege.  The statement
has these variants:

     SHOW ENGINE INNODB STATUS
     SHOW ENGINE INNODB MUTEX
     SHOW ENGINE PERFORMANCE_SCHEMA STATUS

'SHOW ENGINE INNODB STATUS' displays extensive
information from the standard 'InnoDB' Monitor about the state of the
'InnoDB' storage engine.  For information about the standard monitor and
other 'InnoDB' Monitors that provide information about 'InnoDB'
processing, see innodb-monitors.

'SHOW ENGINE INNODB MUTEX' displays 'InnoDB' mutex
and rw-lock statistics.

*Note*:

'InnoDB' mutexes and rwlocks can also be monitored using
Performance Schema tables.  See
monitor-innodb-mutex-waits-performance-schema.

'SHOW ENGINE INNODB MUTEX' output was removed in
MySQL 5.7.2.  It was revised and reintroduced in MySQL 5.7.8.

In MySQL 5.7.8, mutex statistics collection is configured dynamically
using the following options:

   * To enable the collection of mutex statistics, run:

          SET GLOBAL innodb_monitor_enable='latch';

   * To reset mutex statistics, run:

          SET GLOBAL innodb_monitor_reset='latch';

   * To disable the collection of mutex statistics, run:

          SET GLOBAL innodb_monitor_disable='latch';

Collection of mutex statistics for 'SHOW ENGINE INNODB MUTEX'
can also be enabled by setting
'innodb_monitor_enable='all'', or disabled by setting
'innodb_monitor_disable='all''.

'SHOW ENGINE INNODB MUTEX' output has the following
columns:

   * 'Type'

     Always 'InnoDB'.

   * 'Name'

     Prior to MySQL 5.7.8, the 'Name' field reports the source file
     where the mutex is implemented, and the line number in the file
     where the mutex is created.  The line number is specific to your
     version of MySQL. As of MySQL 5.7.8, only the mutex name is
     reported.  File name and line number are still reported for
     rwlocks.

   * 'Status'

     The mutex status.

     Prior to MySQL 5.7.8, the 'Status' field displays several values if
     'WITH_DEBUG' was defined at MySQL compilation time.  If
     'WITH_DEBUG' was not defined, the statement displays only the
     'os_waits' value.  In the latter case (without 'WITH_DEBUG'), the
     information on which the output is based is insufficient to
     distinguish regular mutexes and mutexes that protect rwlocks (which
     permit multiple readers or a single writer).  Consequently, the
     output may appear to contain multiple rows for the same mutex.
     Pre-MySQL 5.7.8 'Status' field values include:

        * 'count' indicates how many times the mutex was requested.

        * 'spin_waits' indicates how many times the spinlock had to run.

        * 'spin_rounds' indicates the number of spinlock rounds.
          ('spin_rounds' divided by 'spin_waits' provides the average
          round count.)

        * 'os_waits' indicates the number of operating system waits.
          This occurs when the spinlock did not work (the mutex was not
          locked during the spinlock and it was necessary to yield to
          the operating system and wait).

        * 'os_yields' indicates the number of times a thread trying to
          lock a mutex gave up its timeslice and yielded to the
          operating system (on the presumption that permitting other
          threads to run will free the mutex so that it can be locked).

        * 'os_wait_times' indicates the amount of time (in ms) spent in
          operating system waits.  In MySQL 5.7 timing is disabled and
          this value is always 0.

     As of MySQL 5.7.8, the 'Status' field reports the number of spins,
     waits, and calls.  Statistics for low-level operating system
     mutexes, which are implemented outside of 'InnoDB', are not
     reported.

        * 'spins' indicates the number of spins.

        * 'waits' indicates the number of mutex waits.

        * 'calls' indicates how many times the mutex was requested.

'SHOW ENGINE INNODB MUTEX' skips the mutexes and rw-locks of buffer pool
blocks, as the amount of output can be overwhelming on systems with a
large buffer pool.  (There is one mutex and one rw-lock in each 16K
buffer pool block, and there are 65,536 blocks per gigabyte.)  'SHOW
ENGINE INNODB MUTEX' also does not list any mutexes or rw-locks that
have never been waited on ('os_waits=0').  Thus, 'SHOW ENGINE INNODB
MUTEX' only displays information about mutexes and rw-locks outside of
the buffer pool that have caused at least one OS-level wait.

Use 'SHOW ENGINE PERFORMANCE_SCHEMA STATUS' to
inspect the internal operation of the Performance Schema code:

     mysql> SHOW ENGINE PERFORMANCE_SCHEMA STATUS\G
     ...
     *************************** 3. row ***************************
       Type: performance_schema
       Name: events_waits_history.size
     Status: 76
     *************************** 4. row ***************************
       Type: performance_schema
       Name: events_waits_history.count
     Status: 10000
     *************************** 5. row ***************************
       Type: performance_schema
       Name: events_waits_history.memory
     Status: 760000
     ...
     *************************** 57. row ***************************
       Type: performance_schema
       Name: performance_schema.memory
     Status: 26459600
     ...

This statement is intended to help the DBA understand the effects that
different Performance Schema options have on memory requirements.

'Name' values consist of two parts, which name an internal buffer and a
buffer attribute, respectively.  Interpret buffer names as follows:

   * An internal buffer that is not exposed as a table is named within
     parentheses.  Examples: '(pfs_cond_class).size',
     '(pfs_mutex_class).memory'.

   * An internal buffer that is exposed as a table in the
     'performance_schema' database is named after the table, without
     parentheses.  Examples: 'events_waits_history.size',
     'mutex_instances.count'.

   * A value that applies to the Performance Schema as a whole begins
     with 'performance_schema'.  Example: 'performance_schema.memory'.

Buffer attributes have these meanings:

   * 'size' is the size of the internal record used by the
     implementation, such as the size of a row in a table.  'size'
     values cannot be changed.

   * 'count' is the number of internal records, such as the number of
     rows in a table.  'count' values can be changed using Performance
     Schema configuration options.

   * For a table, 'TBL_NAME.memory' is the product of 'size' and
     'count'.  For the Performance Schema as a whole,
     'performance_schema.memory' is the sum of all the memory used (the
     sum of all other 'memory' values).

In some cases, there is a direct relationship between a Performance
Schema configuration parameter and a 'SHOW ENGINE' value.  For example,
'events_waits_history_long.count' corresponds to
'performance_schema_events_waits_history_long_size'.  In other cases,
the relationship is more complex.  For example,
'events_waits_history.count' corresponds to
'performance_schema_events_waits_history_size' (the number of rows per
thread) multiplied by 'performance_schema_max_thread_instances' ( the
number of threads).

SHOW ENGINE NDB STATUS

If the server has the 'NDB' storage engine
enabled, 'SHOW ENGINE NDB STATUS' displays cluster status information
such as the number of connected data nodes, the cluster connectstring,
and cluster binary log epochs, as well as counts of various Cluster API
objects created by the MySQL Server when connected to the cluster.
Sample output from this statement is shown here:

     mysql> SHOW ENGINE NDB STATUS;
     +------------+-----------------------+--------------------------------------------------+
     | Type       | Name                  | Status                                           |
     +------------+-----------------------+--------------------------------------------------+
     | ndbcluster | connection            | cluster_node_id=7,
       connected_host=198.51.100.103, connected_port=1186, number_of_data_nodes=4,
       number_of_ready_data_nodes=3, connect_count=0                                         |
     | ndbcluster | NdbTransaction        | created=6, free=0, sizeof=212                    |
     | ndbcluster | NdbOperation          | created=8, free=8, sizeof=660                    |
     | ndbcluster | NdbIndexScanOperation | created=1, free=1, sizeof=744                    |
     | ndbcluster | NdbIndexOperation     | created=0, free=0, sizeof=664                    |
     | ndbcluster | NdbRecAttr            | created=1285, free=1285, sizeof=60               |
     | ndbcluster | NdbApiSignal          | created=16, free=16, sizeof=136                  |
     | ndbcluster | NdbLabel              | created=0, free=0, sizeof=196                    |
     | ndbcluster | NdbBranch             | created=0, free=0, sizeof=24                     |
     | ndbcluster | NdbSubroutine         | created=0, free=0, sizeof=68                     |
     | ndbcluster | NdbCall               | created=0, free=0, sizeof=16                     |
     | ndbcluster | NdbBlob               | created=1, free=1, sizeof=264                    |
     | ndbcluster | NdbReceiver           | created=4, free=0, sizeof=68                     |
     | ndbcluster | binlog                | latest_epoch=155467, latest_trans_epoch=148126,
       latest_received_binlog_epoch=0, latest_handled_binlog_epoch=0,
       latest_applied_binlog_epoch=0                                                         |
     +------------+-----------------------+--------------------------------------------------+

The 'Status' column in each of these rows provides information about the
MySQL server's connection to the cluster and about the cluster binary
log's status, respectively.  The 'Status' information is in the form of
comma-delimited set of name/value pairs.

The 'connection' row's 'Status' column contains the name/value pairs
described in the following table.

Name                          Value

'cluster_node_id'             The node ID of the MySQL server in the
                              cluster

'connected_host'              The host name or IP address of the
                              cluster management server to which the
                              MySQL server is connected

'connected_port'              The port used by the MySQL server to
                              connect to the management server
                              ('connected_host')

'number_of_data_nodes'        The number of data nodes configured for
                              the cluster (that is, the number of
                              '[ndbd]' sections in the cluster
                              'config.ini' file)

'number_of_ready_data_nodes'  The number of data nodes in the cluster
                              that are actually running

'connect_count'               The number of times this 'mysqld'
                              has connected or reconnected to
                              cluster data nodes

The 'binlog' row's 'Status' column contains information relating to NDB
Cluster Replication.  The name/value pairs it contains are described in
the following table.

Name                          Value

'latest_epoch'                The most recent epoch most recently run
                              on this MySQL server (that is, the
                              sequence number of the most recent
                              transaction run on the server)

'latest_trans_epoch'          The most recent epoch processed by the
                              cluster's data nodes

'latest_received_binlog_epoch'The most recent epoch received by the
                              binary log thread

'latest_handled_binlog_epoch' The most recent epoch processed by the
                              binary log thread (for writing to the
                              binary log)

'latest_applied_binlog_epoch' The most recent epoch actually written to
                              the binary log

See mysql-cluster-replication, for more information.

The remaining rows from the output of 'SHOW ENGINE NDB STATUS' which are
most likely to prove useful in monitoring the cluster are listed here by
'Name':

   * 'NdbTransaction': The number and size of 'NdbTransaction' objects
     that have been created.  An 'NdbTransaction' is created each time a
     table schema operation (such as 'CREATE TABLE'.
     or 'ALTER TABLE') is performed on an
     'NDB' table.

   * 'NdbOperation': The number and size of 'NdbOperation' objects that
     have been created.

   * 'NdbIndexScanOperation': The number and size of
     'NdbIndexScanOperation' objects that have been created.

   * 'NdbIndexOperation': The number and size of 'NdbIndexOperation'
     objects that have been created.

   * 'NdbRecAttr': The number and size of 'NdbRecAttr' objects that have
     been created.  In general, one of these is created each time a data
     manipulation statement is performed by an SQL node.

   * 'NdbBlob': The number and size of 'NdbBlob' objects that have been
     created.  An 'NdbBlob' is created for each new operation involving
     a 'BLOB' column in an 'NDB'.
     table.

   * 'NdbReceiver': The number and size of any 'NdbReceiver' object that
     have been created.  The number in the 'created' column is the same
     as the number of data nodes in the cluster to which the MySQL
     server has connected.

*Note*:

'SHOW ENGINE NDB STATUS' returns an empty result if no operations
involving 'NDB' tables have been performed during
the current session by the MySQL client accessing the SQL node on which
this statement is run.

13.7.5.16 SHOW ENGINES Syntax
.............................

     SHOW [STORAGE] ENGINES

'SHOW ENGINES' displays status information about
the server's storage engines.  This is particularly useful for checking
whether a storage engine is supported, or to see what the default engine
is.  This information can also be obtained from the 'INFORMATION_SCHEMA'
'ENGINES' table.  See engines-table.

     mysql> SHOW ENGINES\G
     *************************** 1. row ***************************
           Engine: InnoDB
          Support: DEFAULT
          Comment: Supports transactions, row-level locking, and foreign keys
     Transactions: YES
               XA: YES
       Savepoints: YES
     *************************** 2. row ***************************
           Engine: MRG_MYISAM
          Support: YES
          Comment: Collection of identical MyISAM tables
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 3. row ***************************
           Engine: MEMORY
          Support: YES
          Comment: Hash based, stored in memory, useful for temporary tables
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 4. row ***************************
           Engine: BLACKHOLE
          Support: YES
          Comment: /dev/null storage engine (anything you write to it disappears)
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 5. row ***************************
           Engine: MyISAM
          Support: YES
          Comment: MyISAM storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 6. row ***************************
           Engine: CSV
          Support: YES
          Comment: CSV storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 7. row ***************************
           Engine: ARCHIVE
          Support: YES
          Comment: Archive storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 8. row ***************************
           Engine: PERFORMANCE_SCHEMA
          Support: YES
          Comment: Performance Schema
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 9. row ***************************
           Engine: FEDERATED
          Support: YES
          Comment: Federated MySQL storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO

The output from 'SHOW ENGINES' may vary according
to the MySQL version used and other factors.  The values shown in the
'Support' column indicate the server's level of support for the storage
engine, as shown in the following table.

Value       Meaning

'YES'       The engine is supported and is active

'DEFAULT'   Like 'YES', plus this is the default engine

'NO'        The engine is not supported

'DISABLED'  The engine is supported but has been disabled

A value of 'NO' means that the server was compiled without support for
the engine, so it cannot be enabled at runtime.

A value of 'DISABLED' occurs either because the server was started with
an option that disables the engine, or because not all options required
to enable it were given.  In the latter case, the error log should
contain a reason indicating why the option is disabled.  See
error-log.

You might also see 'DISABLED' for a storage engine if the server was
compiled to support it, but was started with a '--skip-ENGINE_NAME'
option.

All MySQL servers support 'MyISAM' tables.  It is not possible to
disable 'MyISAM'.

The 'Transactions', 'XA', and 'Savepoints' columns indicate whether the
storage engine supports transactions, XA transactions, and savepoints,
respectively.

13.7.5.17 SHOW ERRORS Syntax
............................

     SHOW ERRORS [LIMIT [OFFSET,] ROW_COUNT]
     SHOW COUNT(*) ERRORS

'SHOW ERRORS' is a diagnostic statement that is
similar to 'SHOW WARNINGS', except that it displays
information only for errors, rather than for errors, warnings, and
notes.

The 'LIMIT' clause has the same syntax as for the 'SELECT'
statement.  See select.

The 'SHOW COUNT(*) ERRORS' statement displays the
number of errors.  You can also retrieve this number from the
'error_count' variable:

     SHOW COUNT(*) ERRORS;
     SELECT @@error_count;

'SHOW ERRORS' and 'error_count' apply only to
errors, not warnings or notes.  In other respects, they are similar to
'SHOW WARNINGS' and 'warning_count'.  In
particular, see 'SHOW ERRORS' cannot display information
for more than 'max_error_count' messages, and 'error_count' can exceed
the value of 'max_error_count' if the number of errors exceeds
'max_error_count'.

For more information, see show-warnings.

13.7.5.18 SHOW EVENTS Syntax
............................

     SHOW EVENTS
         [{FROM | IN} SCHEMA_NAME]
         [LIKE 'PATTERN' | WHERE EXPR]

This statement displays information about Event Manager events.  It
requires the 'EVENT' privilege for the database from which the events
are to be shown.

In its simplest form, see 'SHOW EVENTS' lists all of the
events in the current schema:

     mysql> SELECT CURRENT_USER(), SCHEMA();
     +----------------+----------+
     | CURRENT_USER() | SCHEMA() |
     +----------------+----------+
     | jon@ghidora    | myschema |
     +----------------+----------+
     1 row in set (0.00 sec)

     mysql> SHOW EVENTS\G
     *************************** 1. row ***************************
                       Db: myschema
                     Name: e_daily
                  Definer: jon@ghidora
                Time zone: SYSTEM
                     Type: RECURRING
               Execute at: NULL
           Interval value: 10
           Interval field: SECOND
                   Starts: 2006-02-09 10:41:23
                     Ends: NULL
                   Status: ENABLED
               Originator: 0
     character_set_client: latin1
     collation_connection: latin1_swedish_ci
       Database Collation: latin1_swedish_ci

To see events for a specific schema, use the 'FROM' clause.  For
example, to see events for the 'test' schema, use the following
statement:

     SHOW EVENTS FROM test;

The 'LIKE' clause, if present, indicates which event names to match.
The 'WHERE' clause can be given to select rows using more general
conditions, as discussed in extended-show.

'SHOW EVENTS' output has the following columns:

   * 'Db': The schema (database) on which the event is defined.

   * 'Name': The name of the event.

   * 'Time zone': The event time zone, which is the time zone used for
     scheduling the event and that is in effect within the event as it
     executes.  The default value is 'SYSTEM'.

   * 'Definer': The account of the user who created the event, in
     ''USER_NAME'@'HOST_NAME'' format.

   * 'Type': The event repetition type, either 'ONE TIME' (transient) or
     'RECURRING' (repeating).

   * 'Execute At': The date and time when a transient event is set to
     execute.  Shown as a 'DATETIME' value.

     For a recurring event, the value of this column is always 'NULL'.

   * 'Interval Value': For a recurring event, the number of intervals to
     wait between event executions.

     For a transient event, the value of this column is always 'NULL'.

   * 'Interval Field': The time units used for the interval which a
     recurring event waits before repeating.

     For a transient event, the value of this column is always 'NULL'.

   * 'Starts': The start date and time for a recurring event.  This is
     displayed as a 'DATETIME' value, and is 'NULL' if
     no start date and time are defined for the event.

     For a transient event, this column is always 'NULL'.

   * 'Ends': The end date and time for a recurring event.  This is
     displayed as a 'DATETIME' value, and defaults to
     'NULL' if no end date and time is defined for the event.

     For a transient event, this column is always 'NULL'.

   * 'Status': The event status.  One of 'ENABLED', 'DISABLED', or
     'SLAVESIDE_DISABLED'.

     'SLAVESIDE_DISABLED' indicates that the creation of the event
     occurred on another MySQL server acting as a replication master and
     replicated to the current MySQL server which is acting as a slave,
     but the event is not presently being executed on the slave.

   * 'Originator': The server ID of the MySQL server on which the event
     was created.  Defaults to 0.

   * 'character_set_client' is the session value of the
     'character_set_client' system variable when the routine was
     created.  'collation_connection' is the session value of the
     'collation_connection' system variable when the routine was
     created.  'Database Collation' is the collation of the database
     with which the routine is associated.

For more information about 'SLAVE_DISABLED' and the 'Originator' column,
see replication-features-invoked.

The event action statement is not shown in the output of 'SHOW EVENTS'.
Use 'SHOW CREATE EVENT'.
or the 'INFORMATION_SCHEMA.EVENTS' table.

Times displayed by 'SHOW EVENTS' are given in the
event time zone, as discussed in events-metadata.

The columns in the output of 'SHOW EVENTS' are
similar to, but not identical to the columns in the
'INFORMATION_SCHEMA.EVENTS' table.  See
events-table.

13.7.5.19 SHOW FUNCTION CODE Syntax
...................................

     SHOW FUNCTION CODE FUNC_NAME

This statement is similar to 'SHOW PROCEDURE CODE'
but for stored functions.  See
show-procedure-code.

13.7.5.20 SHOW FUNCTION STATUS Syntax
.....................................

     SHOW FUNCTION STATUS
         [LIKE 'PATTERN' | WHERE EXPR]

This statement is similar to 'SHOW PROCEDURE STATUS'
but for stored functions.  See
show-procedure-status.

13.7.5.21 SHOW GRANTS Syntax
............................

     SHOW GRANTS [FOR USER]

This statement displays the privileges that are assigned to a MySQL user
account, in the form of 'GRANT' statements that must be
executed to duplicate the privilege assignments.

*Note*:

To display nonprivilege information for MySQL accounts, use the
'SHOW CREATE USER' statement.  See
show-create-user.

'SHOW GRANTS' requires the 'SELECT' privilege for
the 'mysql' database, except to display privileges for the current user.

To name the account for 'SHOW GRANTS', use the same
format as for the 'GRANT' statement; for example,
''jeffrey'@'localhost'':

     mysql> SHOW GRANTS FOR 'jeffrey'@'localhost';
     +------------------------------------------------------------------+
     | Grants for jeffrey@localhost                                     |
     +------------------------------------------------------------------+
     | GRANT USAGE ON *.* TO `jeffrey`@`localhost`                      |
     | GRANT SELECT, INSERT, UPDATE ON `db1`.* TO `jeffrey`@`localhost` |
     +------------------------------------------------------------------+

The host part, if omitted, defaults to ''%''.  For additional
information about specifying account names, see account-names.

To display the privileges granted to the current user (the account you
are using to connect to the server), you can use any of the following
statements:

     SHOW GRANTS;
     SHOW GRANTS FOR CURRENT_USER;
     SHOW GRANTS FOR CURRENT_USER();

If 'SHOW GRANTS FOR CURRENT_USER' (or any of the equivalent syntaxes) is
used in definer context, such as within a stored procedure that executes
with definer rather than invoker privileges), the grants displayed are
those of the definer and not the invoker.

'SHOW GRANTS' does not display privileges that are
available to the named account but are granted to a different account.
For example, if an anonymous account exists, the named account might be
able to use its privileges, but 'SHOW GRANTS' does
not display them.

'SHOW GRANTS' output does not include 'IDENTIFIED BY PASSWORD' clauses.
Use the 'SHOW CREATE USER' statement instead.
See show-create-user.

13.7.5.22 SHOW INDEX Syntax
...........................

     SHOW {INDEX | INDEXES | KEYS}
         {FROM | IN} TBL_NAME
         [{FROM | IN} DB_NAME]
         [WHERE EXPR]

'SHOW INDEX' returns table index information.  The
format resembles that of the 'SQLStatistics' call in ODBC. This
statement requires some privilege for any column in the table.

You can use DB_NAME.TBL_NAME as an alternative to the 'TBL_NAME FROM
DB_NAME' syntax.  These two statements are equivalent:

     SHOW INDEX FROM mytable FROM mydb;
     SHOW INDEX FROM mydb.mytable;

The 'WHERE' clause can be given to select rows using more general
conditions, as discussed in extended-show.

     mysql> SHOW INDEX FROM City\G
     *************************** 1. row ***************************
             Table: city
        Non_unique: 0
          Key_name: PRIMARY
      Seq_in_index: 1
       Column_name: ID
         Collation: A
       Cardinality: 4321
          Sub_part: NULL
            Packed: NULL
              Null:
        Index_type: BTREE
           Comment:
     Index_comment:
     *************************** 2. row ***************************
             Table: city
        Non_unique: 1
          Key_name: CountryCode
      Seq_in_index: 1
       Column_name: CountryCode
         Collation: A
       Cardinality: 4321
          Sub_part: NULL
            Packed: NULL
              Null:
        Index_type: BTREE
           Comment:
     Index_comment:

'SHOW INDEX' returns the following fields:

   * 'Table'

     The name of the table.

   * 'Non_unique'

     0 if the index cannot contain duplicates, 1 if it can.

   * 'Key_name'

     The name of the index.  If the index is the primary key, the name
     is always 'PRIMARY'.

   * 'Seq_in_index'

     The column sequence number in the index, starting with 1.

   * 'Column_name'

     The column name.

   * 'Collation'

     How the column is sorted in the index.  This can have values 'A'
     (ascending) or 'NULL' (not sorted).

   * 'Cardinality'

     An estimate of the number of unique values in the index.  To update
     this number, run 'ANALYZE TABLE' or (for
     'MyISAM' tables) 'myisamchk -a'.

     'Cardinality' is counted based on statistics stored as integers, so
     the value is not necessarily exact even for small tables.  The
     higher the cardinality, the greater the chance that MySQL uses the
     index when doing joins.

   * 'Sub_part'

     The index prefix.  That is, the number of indexed characters if the
     column is only partly indexed, 'NULL' if the entire column is
     indexed.

     *Note*:

     Prefix limits are measured in bytes, whereas the prefix length in
     'CREATE TABLE', 'ALTER TABLE',
     and 'CREATE INDEX' statements is
     interpreted as number of characters for nonbinary string types
     (see 'CHAR', 'VARCHAR', 'TEXT')
     and number of bytes for binary string types (see 'BINARY',
     see 'VARBINARY',
     'BLOB').  Take this into account when specifying a prefix
     length for a nonbinary string column that uses a multibyte
     character set.

     For additional information about index prefixes, see
     column-indexes, and create-index.

   * 'Packed'

     Indicates how the key is packed.  'NULL' if it is not.

   * 'Null'

     Contains 'YES' if the column may contain 'NULL' values and '''' if
     not.

   * 'Index_type'

     The index method used ('BTREE', 'FULLTEXT', 'HASH', 'RTREE').

   * 'Comment'

     Information about the index not described in its own column, such
     as 'disabled' if the index is disabled.

   * 'Index_comment'

     Any comment provided for the index with a 'COMMENT' attribute when
     the index was created.

You can also obtain information about table indexes from
'INFORMATION_SCHEMA', which contains a 'STATISTICS'
table.  See statistics-table.

You can list a table's indexes with the 'mysqlshow -k DB_NAME TBL_NAME'
command.

13.7.5.23 SHOW MASTER STATUS Syntax
...................................

     SHOW MASTER STATUS

This statement provides status information about the binary log files of
the master.  It requires either the 'SUPER' or 'REPLICATION CLIENT'
privilege.

Example:

     mysql> SHOW MASTER STATUS\G
     *************************** 1. row ***************************
                  File: master-bin.000002
              Position: 1307
          Binlog_Do_DB: test
      Binlog_Ignore_DB: manual, mysql
     Executed_Gtid_Set: 3E11FA47-71CA-11E1-9E33-C80AA9429562:1-5
     1 row in set (0.00 sec)

When global transaction IDs are in use, 'Executed_Gtid_Set' shows the
set of GTIDs for transactions that have been executed on the master.
This is the same as the value for the 'gtid_executed' system variable on
this server, as well as the value for 'Executed_Gtid_Set' in the output
of 'SHOW SLAVE STATUS' on this server.

13.7.5.24 SHOW OPEN TABLES Syntax
.................................

     SHOW OPEN TABLES
         [{FROM | IN} DB_NAME]
         [LIKE 'PATTERN' | WHERE EXPR]

'SHOW OPEN TABLES' lists the non-'TEMPORARY'
tables that are currently open in the table cache.  See
table-cache.  The 'FROM' clause, if present, restricts the tables
shown to those present in the DB_NAME database.  The 'LIKE' clause, if
present, indicates which table names to match.  The 'WHERE' clause can
be given to select rows using more general conditions, as discussed in
extended-show.

'SHOW OPEN TABLES' output has the following
columns:

   * 'Database'

     The database containing the table.

   * 'Table'

     The table name.

   * 'In_use'

     The number of table locks or lock requests there are for the table.
     For example, if one client acquires a lock for a table using 'LOCK
     TABLE t1 WRITE', 'In_use' will be 1.  If another client issues
     'LOCK TABLE t1 WRITE' while the table remains locked, the client
     will block waiting for the lock, but the lock request causes
     'In_use' to be 2.  If the count is zero, the table is open but not
     currently being used.  'In_use' is also increased by the
     'HANDLER ... OPEN' statement and decreased by
     'HANDLER ... CLOSE'.

   * 'Name_locked'

     Whether the table name is locked.  Name locking is used for
     operations such as dropping or renaming tables.

If you have no privileges for a table, it does not show up in the output
from 'SHOW OPEN TABLES'.

13.7.5.25 SHOW PLUGINS Syntax
.............................

     SHOW PLUGINS

'SHOW PLUGINS' displays information about server
plugins.  Plugin information is also available in the
'INFORMATION_SCHEMA.PLUGINS' table.  See plugins-table.

Example of 'SHOW PLUGINS' output:

     mysql> SHOW PLUGINS\G
     *************************** 1. row ***************************
        Name: binlog
      Status: ACTIVE
        Type: STORAGE ENGINE
     Library: NULL
     License: GPL
     *************************** 2. row ***************************
        Name: CSV
      Status: ACTIVE
        Type: STORAGE ENGINE
     Library: NULL
     License: GPL
     *************************** 3. row ***************************
        Name: MEMORY
      Status: ACTIVE
        Type: STORAGE ENGINE
     Library: NULL
     License: GPL
     *************************** 4. row ***************************
        Name: MyISAM
      Status: ACTIVE
        Type: STORAGE ENGINE
     Library: NULL
     License: GPL
     ...

'SHOW PLUGINS' output has the following columns:

   * 'Name': The name used to refer to the plugin in statements such as
     'INSTALL PLUGIN' and 'UNINSTALL PLUGIN'.

   * 'Status': The plugin status, one of 'ACTIVE', 'INACTIVE',
     'DISABLED', or 'DELETED'.

   * 'Type': The type of plugin, such as 'STORAGE ENGINE',
     'INFORMATION_SCHEMA', or 'AUTHENTICATION'.

   * 'Library': The name of the plugin shared library file.  This is the
     name used to refer to the plugin file in statements such as
     'INSTALL PLUGIN' and 'UNINSTALL PLUGIN'.
     This file is located in the directory named by
     the 'plugin_dir' system variable.  If the library name is 'NULL',
     the plugin is compiled in and cannot be uninstalled with
     'UNINSTALL PLUGIN'.

   * 'License': How the plugin is licensed; for example, 'GPL'.

For plugins installed with 'INSTALL PLUGIN', the
'Name' and 'Library' values are also registered in the 'mysql.plugin'
table.

For information about plugin data structures that form the basis of the
information displayed by 'SHOW PLUGINS', see
plugin-api.

13.7.5.26 SHOW PRIVILEGES Syntax
................................

     SHOW PRIVILEGES

'SHOW PRIVILEGES' shows the list of system
privileges that the MySQL server supports.  The exact list of privileges
depends on the version of your server.

     mysql> SHOW PRIVILEGES\G
     *************************** 1. row ***************************
     Privilege: Alter
       Context: Tables
       Comment: To alter the table
     *************************** 2. row ***************************
     Privilege: Alter routine
       Context: Functions,Procedures
       Comment: To alter or drop stored functions/procedures
     *************************** 3. row ***************************
     Privilege: Create
       Context: Databases,Tables,Indexes
       Comment: To create new databases and tables
     *************************** 4. row ***************************
     Privilege: Create routine
       Context: Databases
       Comment: To use CREATE FUNCTION/PROCEDURE
     *************************** 5. row ***************************
     Privilege: Create temporary tables
       Context: Databases
       Comment: To use CREATE TEMPORARY TABLE
     ...

Privileges belonging to a specific user are displayed by the 'SHOW GRANTS'
statement.  See show-grants, for more
information.

13.7.5.27 SHOW PROCEDURE CODE Syntax
....................................

     SHOW PROCEDURE CODE PROC_NAME

This statement is a MySQL extension that is available only for servers
that have been built with debugging support.  It displays a
representation of the internal implementation of the named stored
procedure.  A similar statement, see 'SHOW FUNCTION CODE',
displays information about stored functions (see
show-function-code).

To use either statement, you must be the owner of the routine or have
'SELECT' access to the 'mysql.proc' table.

If the named routine is available, each statement produces a result set.
Each row in the result set corresponds to one 'instruction' in the
routine.  The first column is 'Pos', which is an ordinal number
beginning with 0.  The second column is 'Instruction', which contains an
SQL statement (usually changed from the original source), or a directive
which has meaning only to the stored-routine handler.

     mysql> DELIMITER //
     mysql> CREATE PROCEDURE p1 ()
         -> BEGIN
         ->   DECLARE fanta INT DEFAULT 55;
         ->   DROP TABLE t2;
         ->   LOOP
         ->     INSERT INTO t3 VALUES (fanta);
         ->     END LOOP;
         ->   END//
     Query OK, 0 rows affected (0.00 sec)

     mysql> SHOW PROCEDURE CODE p1//
     +-----+----------------------------------------+
     | Pos | Instruction                            |
     +-----+----------------------------------------+
     |   0 | set fanta@0 55                         |
     |   1 | stmt 9 "DROP TABLE t2"                 |
     |   2 | stmt 5 "INSERT INTO t3 VALUES (fanta)" |
     |   3 | jump 2                                 |
     +-----+----------------------------------------+
     4 rows in set (0.00 sec)

In this example, the nonexecutable 'BEGIN' and 'END' statements have
disappeared, and for the 'DECLARE VARIABLE_NAME' statement, only the
executable part appears (the part where the default is assigned).  For
each statement that is taken from source, there is a code word 'stmt'
followed by a type (9 means 'DROP', 5 means 'INSERT', and
so on).  The final row contains an instruction 'jump 2', meaning 'GOTO
instruction #2'.

13.7.5.28 SHOW PROCEDURE STATUS Syntax
......................................

     SHOW PROCEDURE STATUS
         [LIKE 'PATTERN' | WHERE EXPR]

This statement is a MySQL extension.  It returns characteristics of a
stored procedure, such as the database, name, type, creator, creation
and modification dates, and character set information.  A similar
statement, see 'SHOW FUNCTION STATUS', displays
information about stored functions (see show-function-status).

The 'LIKE' clause, if present, indicates which procedure or function
names to match.  The 'WHERE' clause can be given to select rows using
more general conditions, as discussed in extended-show.

     mysql> SHOW PROCEDURE STATUS LIKE 'sp1'\G
     *************************** 1. row ***************************
                       Db: test
                     Name: sp1
                     Type: PROCEDURE
                  Definer: testuser@localhost
                 Modified: 2004-08-03 15:29:37
                  Created: 2004-08-03 15:29:37
            Security_type: DEFINER
                  Comment:
     character_set_client: latin1
     collation_connection: latin1_swedish_ci
       Database Collation: latin1_swedish_ci

'character_set_client' is the session value of the
'character_set_client' system variable when the routine was created.
'collation_connection' is the session value of the
'collation_connection' system variable when the routine was created.
'Database Collation' is the collation of the database with which the
routine is associated.

You can also get information about stored routines from the
'ROUTINES' table in 'INFORMATION_SCHEMA'.  See
routines-table.

13.7.5.29 SHOW PROCESSLIST Syntax
.................................

     SHOW [FULL] PROCESSLIST

'SHOW PROCESSLIST' shows you which threads are
running.  You can also get this information from the
'INFORMATION_SCHEMA' 'PROCESSLIST' table or
the 'mysqladmin processlist' command.  If you have
the 'PROCESS' privilege, you can see all threads.  Otherwise, you can
see only your own threads (that is, threads associated with the MySQL
account that you are using).  If you do not use the 'FULL' keyword, only
the first 100 characters of each statement are shown in the 'Info'
field.

Process information is also available from the
'performance_schema.threads' table.  However, access to
'threads' does not require a mutex and has minimal
impact on server performance.  'INFORMATION_SCHEMA.PROCESSLIST'
and 'SHOW PROCESSLIST' have
negative performance consequences because they require a mutex.
'threads' also shows information about background
threads, which 'INFORMATION_SCHEMA.PROCESSLIST'
and 'SHOW PROCESSLIST' do
not.  This means that 'threads' can be used to
monitor activity the other thread information sources cannot.

The 'SHOW PROCESSLIST' statement is very useful
if you get the 'too many connections' error message and want to find out
what is going on.  MySQL reserves one extra connection to be used by
accounts that have the 'SUPER' privilege, to ensure that administrators
should always be able to connect and check the system (assuming that you
are not giving this privilege to all your users).

Threads can be killed with the 'KILL' statement.  See
kill.

Here is an example of 'SHOW PROCESSLIST'.
output:

     mysql> SHOW FULL PROCESSLIST\G
     *************************** 1. row ***************************
     Id: 1
     User: system user
     Host:
     db: NULL
     Command: Connect
     Time: 1030455
     State: Waiting for master to send event
     Info: NULL
     *************************** 2. row ***************************
     Id: 2
     User: system user
     Host:
     db: NULL
     Command: Connect
     Time: 1004
     State: Has read all relay log; waiting for the slave
            I/O thread to update it
     Info: NULL
     *************************** 3. row ***************************
     Id: 3112
     User: replikator
     Host: artemis:2204
     db: NULL
     Command: Binlog Dump
     Time: 2144
     State: Has sent all binlog to slave; waiting for binlog to be updated
     Info: NULL
     *************************** 4. row ***************************
     Id: 3113
     User: replikator
     Host: iconnect2:45781
     db: NULL
     Command: Binlog Dump
     Time: 2086
     State: Has sent all binlog to slave; waiting for binlog to be updated
     Info: NULL
     *************************** 5. row ***************************
     Id: 3123
     User: stefan
     Host: localhost
     db: apollon
     Command: Query
     Time: 0
     State: NULL
     Info: SHOW FULL PROCESSLIST
     5 rows in set (0.00 sec)

The columns produced by 'SHOW PROCESSLIST' have
the following meanings:

   * 'Id'

     The connection identifier.  This is the same type of value
     displayed in the 'ID' column of the
     'INFORMATION_SCHEMA.PROCESSLIST' table, the
     'PROCESSLIST_ID' column of the Performance Schema 'threads'
     table, and returned by the 'CONNECTION_ID()'
     function.

   * 'User'

     The MySQL user who issued the statement.  If this is 'system user',
     it refers to a nonclient thread spawned by the server to handle
     tasks internally.  This could be the I/O or SQL thread used on
     replication slaves or a delayed-row handler.  'unauthenticated
     user' refers to a thread that has become associated with a client
     connection but for which authentication of the client user has not
     yet been done.  'event_scheduler' refers to the thread that
     monitors scheduled events.  For 'system user', there is no host
     specified in the 'Host' column.

   * 'Host'

     The host name of the client issuing the statement (except for
     'system user' where there is no host).  'SHOW PROCESSLIST'
     reports the host name for TCP/IP connections in
     'HOST_NAME:CLIENT_PORT' format to make it easier to determine which
     client is doing what.

   * 'db'

     The default database, if one is selected, otherwise 'NULL'.

   * 'Command'

     The type of command the thread is executing.  For descriptions for
     thread commands, see thread-information.  The value of this
     column corresponds to the 'COM_XXX' commands of the client/server
     protocol and 'Com_XXX' status variables.  See
     server-status-variables

   * 'Time'

     The time in seconds that the thread has been in its current state.
     For a slave SQL thread, the value is the number of seconds between
     the timestamp of the last replicated event and the real time of the
     slave machine.  See replication-implementation-details.

   * 'State'

     An action, event, or state that indicates what the thread is doing.
     Descriptions for 'State' values can be found at
     thread-information.

     Most states correspond to very quick operations.  If a thread stays
     in a given state for many seconds, there might be a problem that
     needs to be investigated.

     For the 'SHOW PROCESSLIST' statement, the
     value of 'State' is 'NULL'.

   * 'Info'

     The statement the thread is executing, or 'NULL' if it is not
     executing any statement.  The statement might be the one sent to
     the server, or an innermost statement if the statement executes
     other statements.  For example, if a 'CALL' statement executes a
     stored procedure that is executing a 'SELECT'.
     statement, the 'Info' value shows the 'SELECT'.
     statement.

13.7.5.30 SHOW PROFILE Syntax
.............................

     SHOW PROFILE [TYPE [, TYPE] ... ]
         [FOR QUERY N]
         [LIMIT ROW_COUNT [OFFSET OFFSET]]

     TYPE:
         ALL
       | BLOCK IO
       | CONTEXT SWITCHES
       | CPU
       | IPC
       | MEMORY
       | PAGE FAULTS
       | SOURCE
       | SWAPS

The 'SHOW PROFILE' and 'SHOW PROFILES'
statements display profiling information that indicates
resource usage for statements executed during the course of the current
session.

*Note*:

These statements are deprecated and will be removed in a future MySQL
release.  Use the Performance Schema instead;
see performance-schema-query-profiling.

Profiling is controlled by the 'profiling' session variable, which has a
default value of 0 ('OFF').  Profiling is enabled by setting 'profiling'
to 1 or 'ON':

     mysql> SET profiling = 1;

'SHOW PROFILES' displays a list of the most recent
statements sent to the server.  The size of the list is controlled by
the 'profiling_history_size' session variable, which has a default value
of 15.  The maximum value is 100.  Setting the value to 0 has the
practical effect of disabling profiling.

All statements are profiled except 'SHOW PROFILE'.
and 'SHOW PROFILES', so you will find neither of
those statements in the profile list.  Malformed statements are
profiled.  For example, 'SHOW PROFILING' is an illegal statement, and a
syntax error occurs if you try to execute it, but it will show up in the
profiling list.

'SHOW PROFILE' displays detailed information about
a single statement.  Without the 'FOR QUERY N' clause, the output
pertains to the most recently executed statement.  If 'FOR QUERY N' is
included, see 'SHOW PROFILE' displays information for
statement N.  The values of N correspond to the 'Query_ID' values
displayed by 'SHOW PROFILES'.

The 'LIMIT ROW_COUNT' clause may be given to limit the output to
ROW_COUNT rows.  If 'LIMIT' is given, 'OFFSET OFFSET' may be added to
begin the output OFFSET rows into the full set of rows.

By default, see 'SHOW PROFILE' displays 'Status' and
'Duration' columns.  The 'Status' values are like the 'State' values
displayed by 'SHOW PROCESSLIST', although there
might be some minor differences in interpretion for the two statements
for some status values (see thread-information).

Optional TYPE values may be specified to display specific additional
types of information:

   * 'ALL' displays all information

   * 'BLOCK IO' displays counts for block input and output operations

   * 'CONTEXT SWITCHES' displays counts for voluntary and involuntary
     context switches

   * 'CPU' displays user and system CPU usage times

   * 'IPC' displays counts for messages sent and received

   * 'MEMORY' is not currently implemented

   * 'PAGE FAULTS' displays counts for major and minor page faults

   * 'SOURCE' displays the names of functions from the source code,
     together with the name and line number of the file in which the
     function occurs

   * 'SWAPS' displays swap counts

Profiling is enabled per session.  When a session ends, its profiling
information is lost.

     mysql> SELECT @@profiling;
     +-------------+
     | @@profiling |
     +-------------+
     |           0 |
     +-------------+
     1 row in set (0.00 sec)

     mysql> SET profiling = 1;
     Query OK, 0 rows affected (0.00 sec)

     mysql> DROP TABLE IF EXISTS t1;
     Query OK, 0 rows affected, 1 warning (0.00 sec)

     mysql> CREATE TABLE T1 (id INT);
     Query OK, 0 rows affected (0.01 sec)

     mysql> SHOW PROFILES;
     +----------+----------+--------------------------+
     | Query_ID | Duration | Query                    |
     +----------+----------+--------------------------+
     |        0 | 0.000088 | SET PROFILING = 1        |
     |        1 | 0.000136 | DROP TABLE IF EXISTS t1  |
     |        2 | 0.011947 | CREATE TABLE t1 (id INT) |
     +----------+----------+--------------------------+
     3 rows in set (0.00 sec)

     mysql> SHOW PROFILE;
     +----------------------+----------+
     | Status               | Duration |
     +----------------------+----------+
     | checking permissions | 0.000040 |
     | creating table       | 0.000056 |
     | After create         | 0.011363 |
     | query end            | 0.000375 |
     | freeing items        | 0.000089 |
     | logging slow query   | 0.000019 |
     | cleaning up          | 0.000005 |
     +----------------------+----------+
     7 rows in set (0.00 sec)

     mysql> SHOW PROFILE FOR QUERY 1;
     +--------------------+----------+
     | Status             | Duration |
     +--------------------+----------+
     | query end          | 0.000107 |
     | freeing items      | 0.000008 |
     | logging slow query | 0.000015 |
     | cleaning up        | 0.000006 |
     +--------------------+----------+
     4 rows in set (0.00 sec)

     mysql> SHOW PROFILE CPU FOR QUERY 2;
     +----------------------+----------+----------+------------+
     | Status               | Duration | CPU_user | CPU_system |
     +----------------------+----------+----------+------------+
     | checking permissions | 0.000040 | 0.000038 |   0.000002 |
     | creating table       | 0.000056 | 0.000028 |   0.000028 |
     | After create         | 0.011363 | 0.000217 |   0.001571 |
     | query end            | 0.000375 | 0.000013 |   0.000028 |
     | freeing items        | 0.000089 | 0.000010 |   0.000014 |
     | logging slow query   | 0.000019 | 0.000009 |   0.000010 |
     | cleaning up          | 0.000005 | 0.000003 |   0.000002 |
     +----------------------+----------+----------+------------+
     7 rows in set (0.00 sec)

*Note*:

Profiling is only partially functional on some architectures.  For
values that depend on the 'getrusage()' system call, 'NULL' is returned
on systems such as Windows that do not support the call.  In addition,
profiling is per process and not per thread.  This means that activity
on threads within the server other than your own may affect the timing
information that you see.

You can also get profiling information from the 'PROFILING'
table in 'INFORMATION_SCHEMA'.  See
profiling-table.  For example, the following queries produce the same
result:

     SHOW PROFILE FOR QUERY 2;

     SELECT STATE, FORMAT(DURATION, 6) AS DURATION
     FROM INFORMATION_SCHEMA.PROFILING
     WHERE QUERY_ID = 2 ORDER BY SEQ;

13.7.5.31 SHOW PROFILES Syntax
..............................

     SHOW PROFILES

The 'SHOW PROFILES' statement, together with
'SHOW PROFILE', displays profiling information that
indicates resource usage for statements executed during the course of
the current session.  For more information, see show-profile.

*Note*:

These statements are deprecated and will be removed in a future MySQL
release.  Use the Performance Schema instead; see
performance-schema.

13.7.5.32 SHOW RELAYLOG EVENTS Syntax
.....................................

     SHOW RELAYLOG EVENTS
         [IN 'LOG_NAME']
         [FROM POS]
         [LIMIT [OFFSET,] ROW_COUNT]
         [CHANNEL_OPTION]

     CHANNEL_OPTION:
         FOR CHANNEL CHANNEL

Shows the events in the relay log of a replication slave.  If you do not
specify ''LOG_NAME'', the first relay log is displayed.  This statement
has no effect on the master.

The 'LIMIT' clause has the same syntax as for the 'SELECT'
statement.  See select.

*Note*:

Issuing a 'SHOW RELAYLOG EVENTS' with no
'LIMIT' clause could start a very time- and resource-consuming process
because the server returns to the client the complete contents of the
relay log (including all statements modifying data that have been
received by the slave).

The optional 'FOR CHANNEL CHANNEL' clause enables you to name which
replication channel the statement applies to.  Providing a 'FOR CHANNEL
CHANNEL' clause applies the statement to a specific replication channel.
If no channel is named and no extra channels exist, the statement
applies to the default channel.

When using multiple replication channels, if a 'SHOW RELAYLOG EVENTS'
statement does not have a channel defined
using a 'FOR CHANNEL CHANNEL' clause an error is generated.  See
replication-channels for more information.

'SHOW RELAYLOG EVENTS' displays the
following fields for each event in the relay log:

   * 'Log_name'

     The name of the file that is being listed.

   * 'Pos'

     The position at which the event occurs.

   * 'Event_type'

     An identifier that describes the event type.

   * 'Server_id'

     The server ID of the server on which the event originated.

   * 'End_log_pos'

     The value of 'End_log_pos' for this event in the master's binary
     log.

   * 'Info'

     More detailed information about the event type.  The format of this
     information depends on the event type.

*Note*:

Some events relating to the setting of user and system variables are not
included in the output from 'SHOW RELAYLOG EVENTS'.
To get complete coverage of events within a relay
log, use 'mysqlbinlog'.

13.7.5.33 SHOW SLAVE HOSTS Syntax
.................................

     SHOW SLAVE HOSTS

Displays a list of replication slaves currently registered with the
master.

'SHOW SLAVE HOSTS' should be executed on a server that acts as a
replication master.  The statement displays information about servers
that are or have been connected as replication slaves, with each row of
the result corresponding to one slave server, as shown here:

     mysql> SHOW SLAVE HOSTS;
     +------------+-----------+------+-----------+--------------------------------------+
     | Server_id  | Host      | Port | Master_id | Slave_UUID                           |
     +------------+-----------+------+-----------+--------------------------------------+
     |  192168010 | iconnect2 | 3306 | 192168011 | 14cb6624-7f93-11e0-b2c0-c80aa9429562 |
     | 1921680101 | athena    | 3306 | 192168011 | 07af4990-f41f-11df-a566-7ac56fdaf645 |
     +------------+-----------+------+-----------+--------------------------------------+

   * 'Server_id': The unique server ID of the slave server, as
     configured in the slave server's option file, or on the command
     line with '--server-id=VALUE'.

   * 'Host': The host name of the slave server as specified on the slave
     with the '--report-host' option.  This can differ from the machine
     name as configured in the operating system.

   * 'User': The slave server user name as, specified on the slave with
     the '--report-user' option.  Statement output includes this column
     only if the master server is started with the
     '--show-slave-auth-info' option.

   * 'Password': The slave server password as, specified on the slave
     with the '--report-password' option.  Statement output includes
     this column only if the master server is started with the
     '--show-slave-auth-info' option.

   * 'Port': The port on the master to which the slave server is
     listening, as specified on the slave with the '--report-port'
     option.

     A zero in this column means that the slave port ('--report-port')
     was not set.

   * 'Master_id': The unique server ID of the master server that the
     slave server is replicating from.  This is the server ID of the
     server on which 'SHOW SLAVE HOSTS' is executed, so this same value
     is listed for each row in the result.

   *
     'Slave_UUID': The globally unique ID of this slave, as generated on
     the slave and found in the slave's 'auto.cnf' file.

13.7.5.34 SHOW SLAVE STATUS Syntax
..................................

     SHOW SLAVE STATUS [FOR CHANNEL CHANNEL]

This statement provides status information on essential parameters of
the slave threads.  It requires either the 'SUPER' or 'REPLICATION
CLIENT' privilege.

If you issue this statement using the 'mysql' client, you
can use a '\G' statement terminator rather than a semicolon to obtain a
more readable vertical layout:

     mysql> SHOW SLAVE STATUS\G
     *************************** 1. row ***************************
                    Slave_IO_State: Waiting for master to send event
                       Master_Host: localhost
                       Master_User: repl
                       Master_Port: 13000
                     Connect_Retry: 60
                   Master_Log_File: master-bin.000002
               Read_Master_Log_Pos: 1307
                    Relay_Log_File: slave-relay-bin.000003
                     Relay_Log_Pos: 1508
             Relay_Master_Log_File: master-bin.000002
                  Slave_IO_Running: Yes
                 Slave_SQL_Running: Yes
                   Replicate_Do_DB:
               Replicate_Ignore_DB:
                Replicate_Do_Table:
            Replicate_Ignore_Table:
           Replicate_Wild_Do_Table:
       Replicate_Wild_Ignore_Table:
                        Last_Errno: 0
                        Last_Error:
                      Skip_Counter: 0
               Exec_Master_Log_Pos: 1307
                   Relay_Log_Space: 1858
                   Until_Condition: None
                    Until_Log_File:
                     Until_Log_Pos: 0
                Master_SSL_Allowed: No
                Master_SSL_CA_File:
                Master_SSL_CA_Path:
                   Master_SSL_Cert:
                 Master_SSL_Cipher:
                    Master_SSL_Key:
             Seconds_Behind_Master: 0
     Master_SSL_Verify_Server_Cert: No
                     Last_IO_Errno: 0
                     Last_IO_Error:
                    Last_SQL_Errno: 0
                    Last_SQL_Error:
       Replicate_Ignore_Server_Ids:
                  Master_Server_Id: 1
                       Master_UUID: 3e11fa47-71ca-11e1-9e33-c80aa9429562
                  Master_Info_File: /var/mysqld.2/data/master.info
                         SQL_Delay: 0
               SQL_Remaining_Delay: NULL
           Slave_SQL_Running_State: Reading event from the relay log
                Master_Retry_Count: 10
                       Master_Bind:
           Last_IO_Error_Timestamp:
          Last_SQL_Error_Timestamp:
                    Master_SSL_Crl:
                Master_SSL_Crlpath:
                Retrieved_Gtid_Set: 3e11fa47-71ca-11e1-9e33-c80aa9429562:1-5
                 Executed_Gtid_Set: 3e11fa47-71ca-11e1-9e33-c80aa9429562:1-5
                     Auto_Position: 1
              Replicate_Rewrite_DB:
                      Channel_name:
                Master_TLS_Version: TLSv1.2

The Performance Schema provides tables that expose replication
information.  This is similar to the information available from the
'SHOW SLAVE STATUS' statement, but represented
in table form.  For details, see
performance-schema-replication-tables.

The following list describes the fields returned by 'SHOW SLAVE STATUS'.
For additional information about
interpreting their meanings, see
replication-administration-status.

   * 'Slave_IO_State'

     A copy of the 'State' field of the 'SHOW PROCESSLIST'
     output for the slave I/O thread.  This tells you
     what the thread is doing: trying to connect to the master, waiting
     for events from the master, reconnecting to the master, and so on.
     For a listing of possible states, see
     slave-io-thread-states.

   * 'Master_Host'

     The master host that the slave is connected to.

   * 'Master_User'

     The user name of the account used to connect to the master.

   * 'Master_Port'

     The port used to connect to the master.

   * 'Connect_Retry'

     The number of seconds between connect retries (default 60).  This
     can be set with the 'CHANGE MASTER TO'.
     statement.

   * 'Master_Log_File'

     The name of the master binary log file from which the I/O thread is
     currently reading.

   * 'Read_Master_Log_Pos'

     The position in the current master binary log file up to which the
     I/O thread has read.

   * 'Relay_Log_File'

     The name of the relay log file from which the SQL thread is
     currently reading and executing.

   * 'Relay_Log_Pos'

     The position in the current relay log file up to which the SQL
     thread has read and executed.

   * 'Relay_Master_Log_File'

     The name of the master binary log file containing the most recent
     event executed by the SQL thread.

   * 'Slave_IO_Running'

     Whether the I/O thread is started and has connected successfully to
     the master.  Internally, the state of this thread is represented by
     one of the following three values:

        * MYSQL_SLAVE_NOT_RUN

          The slave I/O thread is not running.  For this state,
          'Slave_IO_Running' is 'No'.

        * MYSQL_SLAVE_RUN_NOT_CONNECT

          The slave I/O thread is running, but is not connected to a
          replication master.  For this state, 'Slave_IO_Running' is
          'Connecting'.

        * MYSQL_SLAVE_RUN_CONNECT

          The slave I/O thread is running, and is connected to a
          replication master.  For this state, 'Slave_IO_Running' is
          'Yes'.

     The value of the 'Slave_running' system status variable corresponds
     with this value.

   * 'Slave_SQL_Running'

     Whether the SQL thread is started.

   * 'Replicate_Do_DB', 'Replicate_Ignore_DB'

     The lists of databases that were specified with the
     '--replicate-do-db' and '--replicate-ignore-db' options, if any.

   * 'Replicate_Do_Table', 'Replicate_Ignore_Table',
     'Replicate_Wild_Do_Table', 'Replicate_Wild_Ignore_Table'

     The lists of tables that were specified with the
     '--replicate-do-table', '--replicate-ignore-table',
     '--replicate-wild-do-table', and '--replicate-wild-ignore-table'
     options, if any.

   * 'Last_Errno', 'Last_Error'

     These columns are aliases for 'Last_SQL_Errno' and
     'Last_SQL_Error'.

     Issuing 'RESET MASTER' or 'RESET SLAVE'
     resets the values shown in these columns.

     *Note*:

     When the slave SQL thread receives an error, it reports the error
     first, then stops the SQL thread.  This means that there is a small
     window of time during which 'SHOW SLAVE STATUS'
     shows a nonzero value for 'Last_SQL_Errno' even
     though 'Slave_SQL_Running' still displays 'Yes'.

   * 'Skip_Counter'

     The current value of the 'sql_slave_skip_counter' system variable.
     See set-global-sql-slave-skip-counter.

   * 'Exec_Master_Log_Pos'

     The position in the current master binary log file to which the SQL
     thread has read and executed, marking the start of the next
     transaction or event to be processed.  You can use this value with
     the 'CHANGE MASTER TO' statement's
     'MASTER_LOG_POS' option when starting a new slave from an existing
     slave, so that the new slave reads from this point.  The
     coordinates given by ('Relay_Master_Log_File',
     'Exec_Master_Log_Pos') in the master's binary log correspond to the
     coordinates given by ('Relay_Log_File', 'Relay_Log_Pos') in the
     relay log.

     Inconsistencies in the sequence of transactions from the relay log
     which have been executed can cause this value to be a 'low-water
     mark'.  In other words, transactions appearing before the position
     are guaranteed to have committed, but transactions after the
     position may have committed or not.  If these gaps need to be
     corrected, use 'START SLAVE UNTIL SQL_AFTER_MTS_GAPS'.
     See
     replication-features-transaction-inconsistencies for more
     information.

   * 'Relay_Log_Space'

     The total combined size of all existing relay log files.

   * 'Until_Condition', 'Until_Log_File', 'Until_Log_Pos'

     The values specified in the 'UNTIL' clause of the 'START SLAVE'
     statement.

     'Until_Condition' has these values:

        * 'None' if no 'UNTIL' clause was specified

        * 'Master' if the slave is reading until a given position in the
          master's binary log

        * 'Relay' if the slave is reading until a given position in its
          relay log

        * 'SQL_BEFORE_GTIDS' if the slave SQL thread is processing
          transactions until it has reached the first transaction whose
          GTID is listed in the 'gtid_set'.

        * 'SQL_AFTER_GTIDS' if the slave threads are processing all
          transactions until the last transaction in the 'gtid_set' has
          been processed by both threads.

        * 'SQL_AFTER_MTS_GAPS' if a multi-threaded
          slave's SQL threads are running until no more gaps are found
          in the relay log.

     'Until_Log_File' and 'Until_Log_Pos' indicate the log file name and
     position that define the coordinates at which the SQL thread stops
     executing.

     For more information on 'UNTIL' clauses, see start-slave.

   * 'Master_SSL_Allowed', 'Master_SSL_CA_File', 'Master_SSL_CA_Path',
     'Master_SSL_Cert', 'Master_SSL_Cipher', 'Master_SSL_CRL_File',
     'Master_SSL_CRL_Path', 'Master_SSL_Key',
     'Master_SSL_Verify_Server_Cert'

     These fields show the SSL parameters used by the slave to connect
     to the master, if any.

     'Master_SSL_Allowed' has these values:

        * 'Yes' if an SSL connection to the master is permitted

        * 'No' if an SSL connection to the master is not permitted

        * 'Ignored' if an SSL connection is permitted but the slave
          server does not have SSL support enabled

     The values of the other SSL-related fields correspond to the values
     of the 'MASTER_SSL_CA', 'MASTER_SSL_CAPATH', 'MASTER_SSL_CERT',
     'MASTER_SSL_CIPHER', 'MASTER_SSL_CRL', 'MASTER_SSL_CRLPATH',
     'MASTER_SSL_KEY', and 'MASTER_SSL_VERIFY_SERVER_CERT' options to
     the 'CHANGE MASTER TO' statement.  See
     change-master-to.

   * 'Seconds_Behind_Master'

     This field is an indication of how 'late' the slave is:

        * When the slave is actively processing updates, this field
          shows the difference between the current timestamp on the
          slave and the original timestamp logged on the master for the
          event currently being processed on the slave.

        * When no event is currently being processed on the slave, this
          value is 0.

     In essence, this field measures the time difference in seconds
     between the slave SQL thread and the slave I/O thread.  If the
     network connection between master and slave is fast, the slave I/O
     thread is very close to the master, so this field is a good
     approximation of how late the slave SQL thread is compared to the
     master.  If the network is slow, this is _not_ a good
     approximation; the slave SQL thread may quite often be caught up
     with the slow-reading slave I/O thread, so 'Seconds_Behind_Master'
     often shows a value of 0, even if the I/O thread is late compared
     to the master.  In other words, _this column is useful only for
     fast networks_.

     This time difference computation works even if the master and slave
     do not have identical clock times, provided that the difference,
     computed when the slave I/O thread starts, remains constant from
     then on.  Any changes--including NTP updates--can lead to clock
     skews that can make calculation of 'Seconds_Behind_Master' less
     reliable.

     In MySQL 5.7, this field is 'NULL' (undefined or unknown) if the
     slave SQL thread is not running, or if the SQL thread has consumed
     all of the relay log and the slave I/O thread is not running.  (In
     older versions of MySQL, this field was 'NULL' if the slave SQL
     thread or the slave I/O thread was not running or was not connected
     to the master.)  If the I/O thread is running but the relay log is
     exhausted, 'Seconds_Behind_Master' is set to 0.

     The value of 'Seconds_Behind_Master' is based on the timestamps
     stored in events, which are preserved through replication.  This
     means that if a master M1 is itself a slave of M0, any event from
     M1's binary log that originates from M0's binary log has M0's
     timestamp for that event.  This enables MySQL to replicate
     'TIMESTAMP' successfully.  However, the problem for
     'Seconds_Behind_Master' is that if M1 also receives direct updates
     from clients, the 'Seconds_Behind_Master' value randomly fluctuates
     because sometimes the last event from M1 originates from M0 and
     sometimes is the result of a direct update on M1.

     When using a multi-threaded slave, you should keep in mind that
     this value is based on 'Exec_Master_Log_Pos', and so may not
     reflect the position of the most recently committed transaction.

   * 'Last_IO_Errno', 'Last_IO_Error'

     The error number and error message of the most recent error that
     caused the I/O thread to stop.  An error number of 0 and message of
     the empty string mean 'no error.' If the 'Last_IO_Error' value is
     not empty, the error values also appear in the slave's error log.

     I/O error information includes a timestamp showing when the most
     recent I/O thread error occurred.  This timestamp uses the format
     'YYMMDD HH:MM:SS', and appears in the 'Last_IO_Error_Timestamp'
     column.

     Issuing 'RESET MASTER' or 'RESET SLAVE'
     resets the values shown in these columns.

   * 'Last_SQL_Errno', 'Last_SQL_Error'

     The error number and error message of the most recent error that
     caused the SQL thread to stop.  An error number of 0 and message of
     the empty string mean 'no error.' If the 'Last_SQL_Error' value is
     not empty, the error values also appear in the slave's error log.

     If the slave is multi-threaded, the SQL thread is the coordinator
     for worker threads.  In this case, the 'Last_SQL_Error' field shows
     exactly what the 'Last_Error_Message' column in the Performance
     Schema 'replication_applier_status_by_coordinator'
     table shows.  The
     field value is modified to suggest that there may be more failures
     in the other worker threads which can be seen in the
     'replication_applier_status_by_worker'
     table that shows each
     worker thread's status.  If that table is not available, the slave
     error log can be used.  The log or the
     'replication_applier_status_by_worker'
     table should also be
     used to learn more about the failure shown by 'SHOW SLAVE STATUS'
     or the coordinator table.

     SQL error information includes a timestamp showing when the most
     recent SQL thread error occurred.  This timestamp uses the format
     'YYMMDD HH:MM:SS', and appears in the 'Last_SQL_Error_Timestamp'
     column.

     Issuing 'RESET MASTER' or 'RESET SLAVE'
     resets the values shown in these columns.

     In MySQL 5.7, all error codes and messages displayed in the
     'Last_SQL_Errno' and 'Last_SQL_Error' columns correspond to error
     values listed in error-messages-server.  This was not
     always true in previous versions.  (Bug #11760365, Bug #52768)

   * 'Replicate_Ignore_Server_Ids'

     In MySQL 5.7, you set a slave to ignore events from 0 or more
     masters using the 'IGNORE_SERVER_IDS' option of the 'CHANGE MASTER TO'
     statement.  By default this is blank,
     and is usually modified only when using a circular or other
     multi-master replication setup.  The message shown for
     'Replicate_Ignore_Server_Ids' when not blank consists of a
     comma-delimited list of one or more numbers, indicating the server
     IDs to be ignored.  For example:

          	Replicate_Ignore_Server_Ids: 2, 6, 9

     *Note*:

     'Ignored_server_ids' also shows the server IDs to be ignored, but
     is a space-delimited list, which is preceded by the total number of
     server IDs to be ignored.  For example, if a 'CHANGE MASTER TO'
     statement containing the 'IGNORE_SERVER_IDS
     = (2,6,9)' option has been issued to tell a slave to ignore masters
     having the server ID 2, 6, or 9, that information appears as shown
     here:

          	Ignored_server_ids: 3, 2, 6, 9

     The first number (in this case '3') shows the number of server IDs
     being ignored.

     'Replicate_Ignore_Server_Ids' filtering is performed by the I/O
     thread, rather than by the SQL thread, which means that events
     which are filtered out are not written to the relay log.  This
     differs from the filtering actions taken by server options such
     '--replicate-do-table', which apply to the SQL thread.

   * 'Master_Server_Id'

     The 'server_id' value from the master.

   * 'Master_UUID'

     The 'server_uuid' value from the master.

   * 'Master_Info_File'

     The location of the 'master.info' file.

   * 'SQL_Delay'

     The number of seconds that the slave must lag the master.

   * 'SQL_Remaining_Delay'

     When 'Slave_SQL_Running_State' is 'Waiting until MASTER_DELAY
     seconds after master executed event', this field contains the
     number of delay seconds remaining.  At other times, this field is
     'NULL'.

   * 'Slave_SQL_Running_State'

     The state of the SQL thread (analogous to 'Slave_IO_State').  The
     value is identical to the 'State' value of the SQL thread as
     displayed by 'SHOW PROCESSLIST'.  See
     slave-sql-thread-states, provides a listing of possible states

   * 'Master_Retry_Count'

     The number of times the slave can attempt to reconnect to the
     master in the event of a lost connection.  This value can be set
     using the 'MASTER_RETRY_COUNT' option of the 'CHANGE MASTER TO'
     statement (preferred) or the older
     '--master-retry-count' server option (still supported for backward
     compatibility).

   * 'Master_Bind'

     The network interface that the slave is bound to, if any.  This is
     set using the 'MASTER_BIND' option for the 'CHANGE MASTER TO'
     statement.

   * 'Last_IO_Error_Timestamp'

     A timestamp in 'YYMMDD HH:MM:SS' format that shows when the most
     recent I/O error took place.

   * 'Last_SQL_Error_Timestamp'

     A timestamp in 'YYMMDD HH:MM:SS' format that shows when the last
     SQL error occurred.

   * 'Retrieved_Gtid_Set'

     The set of global transaction IDs corresponding to all transactions
     received by this slave.  Empty if GTIDs are not in use.  See
     replication-gtids-concepts-gtid-sets for more information.

     This is the set of all GTIDs that exist or have existed in the
     relay logs.  Each GTID is added as soon as the 'Gtid_log_event' is
     received.  This can cause partially transmitted transactions to
     have their GTIDs included in the set.

     When all relay logs are lost due to executing 'RESET SLAVE'
     or 'CHANGE MASTER TO', or due
     to the effects of the '--relay-log-recovery' option, the set is
     cleared.  When 'relay_log_purge = 1', the newest relay log is
     always kept, and the set is not cleared.

   * 'Executed_Gtid_Set'

     The set of global transaction IDs written in the binary log.  This
     is the same as the value for the global 'gtid_executed' system
     variable on this server, as well as the value for
     'Executed_Gtid_Set' in the output of 'SHOW MASTER STATUS'
     on this server.  Empty if GTIDs are not in use.
     See replication-gtids-concepts-gtid-sets for more
     information.

   * 'Auto_Position'

     1 if autopositioning is in use; otherwise 0.

   * 'Replicate_Rewrite_DB'

     The 'Replicate_Rewrite_DB' value displays any replication filtering
     rules that were specified.  For example, if the following
     replication filter rule was set:

          CHANGE REPLICATION FILTER REPLICATE_REWRITE_DB=((db1,db2), (db3,db4));

     the 'Replicate_Rewrite_DB' value displays:

          Replicate_Rewrite_DB: (db1,db2),(db3,db4)

     For more information, see change-replication-filter.

   * 'Channel_name'

     The replication channel which is being displayed.  There is always
     a default replication channel, and more replication channels can be
     added.  See replication-channels for more information.

   * 'Master_TLS_Version'

     The TLS version used on the master.  For TLS version information,
     see encrypted-connection-protocols-ciphers.  This column
     was added in MySQL 5.7.10.

13.7.5.35 SHOW STATUS Syntax
............................

     SHOW [GLOBAL | SESSION] STATUS
         [LIKE 'PATTERN' | WHERE EXPR]

*Note*:

As of MySQL 5.7.6, the value of the 'show_compatibility_56' system
variable affects the information available from and privileges required
for the statement described here.  For details, see the description of
that variable in server-system-variables.

'SHOW STATUS' provides server status information
(see server-status-variables).  This statement does not require
any privilege.  It requires only the ability to connect to the server.

Status variable information is also available from these sources:

   * Performance Schema tables.  See
     performance-schema-status-variable-tables.

   * The 'GLOBAL_STATUS' and
     'SESSION_STATUS' tables.  See
     status-table.

   * The 'mysqladmin extended-status' command.  See
     mysqladmin.

For 'SHOW STATUS', a 'LIKE' clause, if present,
indicates which variable names to match.  A 'WHERE' clause can be given
to select rows using more general conditions, as discussed in
extended-show.

'SHOW STATUS' accepts an optional 'GLOBAL' or
'SESSION' variable scope modifier:

   * With a 'GLOBAL' modifier, the statement displays the global status
     values.  A global status variable may represent status for some
     aspect of the server itself (for example, 'Aborted_connects'), or
     the aggregated status over all connections to MySQL (for example,
     'Bytes_received' and 'Bytes_sent').  If a variable has no global
     value, the session value is displayed.

   * With a 'SESSION' modifier, the statement displays the status
     variable values for the current connection.  If a variable has no
     session value, the global value is displayed.  'LOCAL' is a synonym
     for 'SESSION'.

   * If no modifier is present, the default is 'SESSION'.

The scope for each status variable is listed at
server-status-variables.

Each invocation of the 'SHOW STATUS' statement uses
an internal temporary table and increments the global
'Created_tmp_tables' value.

Partial output is shown here.  The list of names and values may differ
for your server.  The meaning of each variable is given in
server-status-variables.

     mysql> SHOW STATUS;
     +--------------------------+------------+
     | Variable_name            | Value      |
     +--------------------------+------------+
     | Aborted_clients          | 0          |
     | Aborted_connects         | 0          |
     | Bytes_received           | 155372598  |
     | Bytes_sent               | 1176560426 |
     | Connections              | 30023      |
     | Created_tmp_disk_tables  | 0          |
     | Created_tmp_tables       | 8340       |
     | Created_tmp_files        | 60         |
     ...
     | Open_tables              | 1          |
     | Open_files               | 2          |
     | Open_streams             | 0          |
     | Opened_tables            | 44600      |
     | Questions                | 2026873    |
     ...
     | Table_locks_immediate    | 1920382    |
     | Table_locks_waited       | 0          |
     | Threads_cached           | 0          |
     | Threads_created          | 30022      |
     | Threads_connected        | 1          |
     | Threads_running          | 1          |
     | Uptime                   | 80380      |
     +--------------------------+------------+

With a 'LIKE' clause, the statement displays only rows for those
variables with names that match the pattern:

     mysql> SHOW STATUS LIKE 'Key%';
     +--------------------+----------+
     | Variable_name      | Value    |
     +--------------------+----------+
     | Key_blocks_used    | 14955    |
     | Key_read_requests  | 96854827 |
     | Key_reads          | 162040   |
     | Key_write_requests | 7589728  |
     | Key_writes         | 3813196  |
     +--------------------+----------+

13.7.5.36 SHOW TABLE STATUS Syntax
..................................

     SHOW TABLE STATUS
         [{FROM | IN} DB_NAME]
         [LIKE 'PATTERN' | WHERE EXPR]

'SHOW TABLE STATUS' works likes 'SHOW TABLES',
but provides a lot of information about each
non-'TEMPORARY' table.  You can also get this list using the
'mysqlshow --status DB_NAME' command.  The 'LIKE' clause, if
present, indicates which table names to match.  The 'WHERE' clause can
be given to select rows using more general conditions, as discussed in
extended-show.

This statement also displays information about views.

'SHOW TABLE STATUS' output has the following
columns:

   * 'Name'

     The name of the table.

   * 'Engine'

     The storage engine for the table.  See storage-engines.

   * 'Version'

     The version number of the table's '.frm' file.

   * 'Row_format'

     The row-storage format ('Fixed', 'Dynamic', 'Compressed',
     'Redundant', 'Compact').  For 'MyISAM' tables, 'Dynamic'
     corresponds to what 'myisamchk -dvv' reports as
     'Packed'.  'InnoDB' table format is either 'Redundant' or 'Compact'
     when using the 'Antelope' file format, or 'Compressed' or 'Dynamic'
     when using the 'Barracuda' file format.

   * 'Rows'

     The number of rows.  Some storage engines, such as 'MyISAM', store
     the exact count.  For other storage engines, such as 'InnoDB', this
     value is an approximation, and may vary from the actual value by as
     much as 40 to 50%.  In such cases, use 'SELECT COUNT(*)' to obtain
     an accurate count.

     The 'Rows' value is 'NULL' for tables in the 'INFORMATION_SCHEMA'
     database.

   * 'Avg_row_length'

     The average row length.

   * 'Data_length'

     For 'MyISAM', 'Data_length' is the length of the data file, in
     bytes.

     For 'InnoDB', 'Data_length' is the approximate amount of memory
     allocated for the clustered index, in bytes.  Specifically, it is
     the clustered index size, in pages, multiplied by the 'InnoDB' page
     size.

     Refer to the notes at the end of this section for information
     regarding other storage engines.

   * 'Max_data_length'

     For 'MyISAM', 'Max_data_length' is maximum length of the data file.
     This is the total number of bytes of data that can be stored in the
     table, given the data pointer size used.

     Unused for 'InnoDB'.

     Refer to the notes at the end of this section for information
     regarding other storage engines.

   * 'Index_length'

     For 'MyISAM', 'Index_length' is the length of the index file, in
     bytes.

     For 'InnoDB', 'Index_length' is the approximate amount of memory
     allocated for non-clustered indexes, in bytes.  Specifically, it is
     the sum of non-clustered index sizes, in pages, multiplied by the
     'InnoDB' page size.

     Refer to the notes at the end of this section for information
     regarding other storage engines.

   * 'Data_free'

     The number of allocated but unused bytes.

     This information is also shown for 'InnoDB' tables (previously, it
     was in the 'Comment' value).  'InnoDB' tables report the free space
     of the tablespace to which the table belongs.  For a table located
     in the shared tablespace, this is the free space of the shared
     tablespace.  If you are using multiple tablespaces and the table
     has its own tablespace, the free space is for only that table.
     Free space means the number of bytes in completely free extents
     minus a safety margin.  Even if free space displays as 0, it may be
     possible to insert rows as long as new extents need not be
     allocated.

     For partitioned tables, this value is only an estimate and may not
     be absolutely correct.  A more accurate method of obtaining this
     information in such cases is to query the
     'INFORMATION_SCHEMA.PARTITIONS' table, as shown in this example:

          SELECT    SUM(DATA_FREE)
              FROM  INFORMATION_SCHEMA.PARTITIONS
              WHERE TABLE_SCHEMA = 'mydb'
              AND   TABLE_NAME   = 'mytable';

     For more information, see partitions-table.

   * 'Auto_increment'

     The next 'AUTO_INCREMENT' value.

   * 'Create_time'

     When the table was created.

   * 'Update_time'

     When the data file was last updated.  For some storage engines,
     this value is 'NULL'.  For example, 'InnoDB' stores multiple tables
     in its system tablespace and the data file timestamp does not
     apply.  Even with file-per-table mode with each 'InnoDB' table in a
     separate '.ibd' file, change buffering can delay the write to the
     data file, so the file modification time is different from the time
     of the last insert, update, or delete.  For 'MyISAM', the data file
     timestamp is used; however, on Windows the timestamp is not updated
     by updates so the value is inaccurate.

   * 'Check_time'

     When the table was last checked.  Not all storage engines update
     this time, in which case the value is always 'NULL'.

   * 'Collation'

     The table's character set and collation.

   * 'Checksum'

     The live checksum value (if any).

   * 'Create_options'

     Extra options used with 'CREATE TABLE'.  The
     original options supplied when 'CREATE TABLE'.
     is called are retained and the options reported here may differ
     from the active table settings and options.

   * 'Comment'

     The comment used when creating the table (or information as to why
     MySQL could not access the table information).

*Notes*:

   * For 'MEMORY' tables, the 'Data_length', 'Max_data_length', and
     'Index_length' values approximate the actual amount of allocated
     memory.  The allocation algorithm reserves memory in large amounts
     to reduce the number of allocation operations.

   * For views, all the fields displayed by 'SHOW TABLE STATUS'
     are 'NULL' except that 'Name' indicates the view
     name and 'Comment' says 'view'.

13.7.5.37 SHOW TABLES Syntax
............................

     SHOW [FULL] TABLES
         [{FROM | IN} DB_NAME]
         [LIKE 'PATTERN' | WHERE EXPR]

'SHOW TABLES' lists the non-'TEMPORARY' tables in a
given database.  You can also get this list using the 'mysqlshow DB_NAME'
command.  The 'LIKE' clause, if present, indicates
which table names to match.  The 'WHERE' clause can be given to select
rows using more general conditions, as discussed in
extended-show.

Matching performed by the 'LIKE' clause is dependent on the setting of
the 'lower_case_table_names' system variable.

This statement also lists any views in the database.  The optional
'FULL' modifier causes 'SHOW TABLES' to display a
second output column with values of 'BASE TABLE' for a table and 'VIEW'
for a view.

If you have no privileges for a base table or view, it does not show up
in the output from 'SHOW TABLES' or 'mysqlshow db_name'.

13.7.5.38 SHOW TRIGGERS Syntax
..............................

     SHOW TRIGGERS
         [{FROM | IN} DB_NAME]
         [LIKE 'PATTERN' | WHERE EXPR]

'SHOW TRIGGERS' lists the triggers currently
defined for tables in a database (the default database unless a 'FROM'
clause is given).  This statement returns results only for databases and
tables for which you have the 'TRIGGER' privilege.  The 'LIKE' clause,
if present, indicates which table names to match (not trigger names) and
causes the statement to display triggers for those tables.  The 'WHERE'
clause can be given to select rows using more general conditions, as
discussed in extended-show.

For the trigger 'ins_sum' as defined in triggers, the output of
this statement is as shown here:

     mysql> SHOW TRIGGERS LIKE 'acc%'\G
     *************************** 1. row ***************************
                  Trigger: ins_sum
                    Event: INSERT
                    Table: account
                Statement: SET @sum = @sum + NEW.amount
                   Timing: BEFORE
                  Created: 2013-07-09 10:39:34.96
                 sql_mode: NO_ENGINE_SUBSTITUTION
                  Definer: me@localhost
     character_set_client: utf8
     collation_connection: utf8_general_ci
       Database Collation: latin1_swedish_ci

'SHOW TRIGGERS' output has the following columns:

   * 'Trigger': The trigger name.

   * 'Event': The type of operation that causes trigger activation.  The
     value is ''INSERT'', ''UPDATE'', or ''DELETE''.

   * 'Table': The table for which the trigger is defined.

   * 'Statement': The trigger body; that is, the statement executed when
     the trigger activates.

   * 'Timing': Whether the trigger activates before or after the
     triggering event.  The value is ''BEFORE'' or ''AFTER''.

   * 'Created': The date and time when the trigger was created.  This is
     a 'TIMESTAMP(2)' value (with a fractional part in hundredths of
     seconds) for triggers created in MySQL 5.7.2 or later, 'NULL' for
     triggers created prior to 5.7.2.

   * 'sql_mode': The SQL mode in effect when the trigger executes.

   * 'Definer': The account of the user who created the trigger, in
     ''USER_NAME'@'HOST_NAME'' format.

   * 'character_set_client': The session value of the
     'character_set_client' system variable when the trigger was
     created.

   * 'collation_connection': The session value of the
     'collation_connection' system variable when the trigger was
     created.

   * 'Database Collation': The collation of the database with which the
     trigger is associated.

You can also obtain information about trigger objects from
'INFORMATION_SCHEMA', which contains a 'TRIGGERS'.
table.  See triggers-table.

13.7.5.39 SHOW VARIABLES Syntax
...............................

     SHOW [GLOBAL | SESSION] VARIABLES
         [LIKE 'PATTERN' | WHERE EXPR]

*Note*:

As of MySQL 5.7.6, the value of the 'show_compatibility_56' system
variable affects the information available from and privileges required
for the statement described here.  For details, see the description of
that variable in server-system-variables.

'SHOW VARIABLES' shows the values of MySQL system
variables (see server-system-variables).  This statement does
not require any privilege.  It requires only the ability to connect to
the server.

System variable information is also available from these sources:

   * Performance Schema tables.  See
     performance-schema-system-variable-tables.

   * The 'GLOBAL_VARIABLES' and
     'SESSION_VARIABLES' tables.  See
     variables-table.

   * The 'mysqladmin variables' command.  See
     mysqladmin.

For 'SHOW VARIABLES', a 'LIKE' clause, if present,
indicates which variable names to match.  A 'WHERE' clause can be given
to select rows using more general conditions, as discussed in
extended-show.

'SHOW VARIABLES' accepts an optional 'GLOBAL' or
'SESSION' variable scope modifier:

   * With a 'GLOBAL' modifier, the statement displays global system
     variable values.  These are the values used to initialize the
     corresponding session variables for new connections to MySQL. If a
     variable has no global value, no value is displayed.

   * With a 'SESSION' modifier, the statement displays the system
     varaible values that are in effect for the current connection.  If
     a variable has no session value, the global value is displayed.
     'LOCAL' is a synonym for 'SESSION'.

   * If no modifier is present, the default is 'SESSION'.

The scope for each system variable is listed at
server-system-variables.

'SHOW VARIABLES' is subject to a
version-dependent display-width limit.  For variables with very long
values that are not completely displayed, use 'SELECT' as
a workaround.  For example:

     SELECT @@GLOBAL.innodb_data_file_path;

Most system variables can be set at server startup (read-only variables
such as 'version_comment' are exceptions).  Many can be changed at
runtime with the 'SET' statement.  See
using-system-variables, and set-variable.

Partial output is shown here.  The list of names and values may differ
for your server.  See server-system-variables, describes the meaning
of each variable, and server-configuration, provides information
about tuning them.

     mysql> SHOW VARIABLES;
     +-----------------------------------------+---------------------------+
     | Variable_name                           | Value                     |
     +-----------------------------------------+---------------------------+
     | auto_increment_increment                | 1                         |
     | auto_increment_offset                   | 1                         |
     | autocommit                              | ON                        |
     | automatic_sp_privileges                 | ON                        |
     | back_log                                | 50                        |
     | basedir                                 | /home/jon/bin/mysql-5.5   |
     | big_tables                              | OFF                       |
     | binlog_cache_size                       | 32768                     |
     | binlog_direct_non_transactional_updates | OFF                       |
     | binlog_format                           | STATEMENT                 |
     | binlog_stmt_cache_size                  | 32768                     |
     | bulk_insert_buffer_size                 | 8388608                   |
     ...
     | max_allowed_packet                      | 4194304                   |
     | max_binlog_cache_size                   | 18446744073709547520      |
     | max_binlog_size                         | 1073741824                |
     | max_binlog_stmt_cache_size              | 18446744073709547520      |
     | max_connect_errors                      | 100                       |
     | max_connections                         | 151                       |
     | max_delayed_threads                     | 20                        |
     | max_error_count                         | 64                        |
     | max_heap_table_size                     | 16777216                  |
     | max_insert_delayed_threads              | 20                        |
     | max_join_size                           | 18446744073709551615      |
     ...

     | thread_handling                         | one-thread-per-connection |
     | thread_stack                            | 262144                    |
     | time_format                             | %H:%i:%s                  |
     | time_zone                               | SYSTEM                    |
     | timestamp                               | 1316689732                |
     | tmp_table_size                          | 16777216                  |
     | tmpdir                                  | /tmp                      |
     | transaction_alloc_block_size            | 8192                      |
     | transaction_isolation                   | REPEATABLE-READ           |
     | transaction_prealloc_size               | 4096                      |
     | transaction_read_only                   | OFF                       |
     | tx_isolation                            | REPEATABLE-READ           |
     | tx_read_only                            | OFF                       |
     | unique_checks                           | ON                        |
     | updatable_views_with_limit              | YES                       |
     | version                                 | 5.5.17-log                |
     | version_comment                         | Source distribution       |
     | version_compile_machine                 | x86_64                    |
     | version_compile_os                      | Linux                     |
     | wait_timeout                            | 28800                     |
     | warning_count                           | 0                         |
     +-----------------------------------------+---------------------------+

With a 'LIKE' clause, the statement displays only rows for those
variables with names that match the pattern.  To obtain the row for a
specific variable, use a 'LIKE' clause as shown:

     SHOW VARIABLES LIKE 'max_join_size';
     SHOW SESSION VARIABLES LIKE 'max_join_size';

To get a list of variables whose name match a pattern, use the '%'
wildcard character in a 'LIKE' clause:

     SHOW VARIABLES LIKE '%size%';
     SHOW GLOBAL VARIABLES LIKE '%size%';

Wildcard characters can be used in any position within the pattern to be
matched.  Strictly speaking, because '_' is a wildcard that matches any
single character, you should escape it as '\_' to match it literally.
In practice, this is rarely necessary.

13.7.5.40 SHOW WARNINGS Syntax
..............................

     SHOW WARNINGS [LIMIT [OFFSET,] ROW_COUNT]
     SHOW COUNT(*) WARNINGS

'SHOW WARNINGS' is a diagnostic statement that
displays information about the conditions (errors, warnings, and notes)
resulting from executing a statement in the current session.  Warnings
are generated for DML statements such as 'INSERT',
'UPDATE', and 'LOAD DATA INFILE' as well as
DDL statements such as 'CREATE TABLE' and
'ALTER TABLE'.

The 'LIMIT' clause has the same syntax as for the 'SELECT'
statement.  See select.

'SHOW WARNINGS' is also used following
'EXPLAIN', to display the extended information generated by
'EXPLAIN'.  See explain-extended.

'SHOW WARNINGS' displays information about the
conditions resulting from execution of the most recent nondiagnostic
statement in the current session.  If the most recent statement resulted
in an error during parsing, see 'SHOW WARNINGS' shows
the resulting conditions, regardless of statement type (diagnostic or
nondiagnostic).

The 'SHOW COUNT(*) WARNINGS' diagnostic statement
displays the total number of errors, warnings, and notes.  You can also
retrieve this number from the 'warning_count' system variable:

     SHOW COUNT(*) WARNINGS;
     SELECT @@warning_count;

A difference in these statements is that the first is a diagnostic
statement that does not clear the message list.  The second, because it
is a 'SELECT' statement is considered nondiagnostic and
does clear the message list.

A related diagnostic statement, see 'SHOW ERRORS', shows
only error conditions (it excludes warnings and notes), and 'SHOW COUNT(*) ERRORS'
statement displays the total number of
errors.  See show-errors.  'GET DIAGNOSTICS'
can be used to examine information for individual
conditions.  See get-diagnostics.

Here is a simple example that shows data-conversion warnings for
'INSERT'.:

     mysql> CREATE TABLE t1 (a TINYINT NOT NULL, b CHAR(4));
     Query OK, 0 rows affected (0.05 sec)

     mysql> INSERT INTO t1 VALUES(10,'mysql'), (NULL,'test'), (300,'xyz');
     Query OK, 3 rows affected, 3 warnings (0.00 sec)
     Records: 3  Duplicates: 0  Warnings: 3

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Warning
        Code: 1265
     Message: Data truncated for column 'b' at row 1
     *************************** 2. row ***************************
       Level: Warning
        Code: 1048
     Message: Column 'a' cannot be null
     *************************** 3. row ***************************
       Level: Warning
        Code: 1264
     Message: Out of range value for column 'a' at row 3
     3 rows in set (0.00 sec)

The 'max_error_count' system variable controls the maximum number of
error, warning, and note messages for which the server stores
information, and thus the number of messages that 'SHOW WARNINGS'
displays.  To change the number of messages the server
can store, change the value of 'max_error_count'.  The default is 64.

'max_error_count' controls only how many messages are stored, not how
many are counted.  The value of 'warning_count' is not limited by
'max_error_count', even if the number of messages generated exceeds
'max_error_count'.  The following example demonstrates this.  The
'ALTER TABLE' statement produces three warning messages
(strict SQL mode is disabled for the example to prevent an error from
occuring after a single conversion issue).  Only one message is stored
and displayed because 'max_error_count' has been set to 1, but all three
are counted (as shown by the value of 'warning_count'):

     mysql> SHOW VARIABLES LIKE 'max_error_count';
     +-----------------+-------+
     | Variable_name   | Value |
     +-----------------+-------+
     | max_error_count | 64    |
     +-----------------+-------+
     1 row in set (0.00 sec)

     mysql> SET max_error_count=1, sql_mode = '';
     Query OK, 0 rows affected (0.00 sec)

     mysql> ALTER TABLE t1 MODIFY b CHAR;
     Query OK, 3 rows affected, 3 warnings (0.00 sec)
     Records: 3  Duplicates: 0  Warnings: 3

     mysql> SHOW WARNINGS;
     +---------+------+----------------------------------------+
     | Level   | Code | Message                                |
     +---------+------+----------------------------------------+
     | Warning | 1263 | Data truncated for column 'b' at row 1 |
     +---------+------+----------------------------------------+
     1 row in set (0.00 sec)

     mysql> SELECT @@warning_count;
     +-----------------+
     | @@warning_count |
     +-----------------+
     |               3 |
     +-----------------+
     1 row in set (0.01 sec)

To disable message storage, set 'max_error_count' to 0.  In this case,
'warning_count' still indicates how many warnings occurred, but messages
are not stored and cannot be displayed.

The 'sql_notes' system variable controls whether note messages increment
'warning_count' and whether the server stores them.  By default,
'sql_notes' is 1, but if set to 0, notes do not increment
'warning_count' and the server does not store them:

     mysql> SET sql_notes = 1;
     mysql> DROP TABLE IF EXISTS test.no_such_table;
     Query OK, 0 rows affected, 1 warning (0.00 sec)
     mysql> SHOW WARNINGS;
     +-------+------+------------------------------------+
     | Level | Code | Message                            |
     +-------+------+------------------------------------+
     | Note  | 1051 | Unknown table 'test.no_such_table' |
     +-------+------+------------------------------------+
     1 row in set (0.00 sec)

     mysql> SET sql_notes = 0;
     mysql> DROP TABLE IF EXISTS test.no_such_table;
     Query OK, 0 rows affected (0.00 sec)
     mysql> SHOW WARNINGS;
     Empty set (0.00 sec)

The MySQL server sends to each client a count indicating the total
number of errors, warnings, and notes resulting from the most recent
statement executed by that client.  From the C API, this value can be
obtained by calling 'mysql_warning_count()'.
See mysql-warning-count.

In the 'mysql' client, you can enable and disable
automatic warnings display using the 'warnings' and 'nowarning'
commands, respectively, or their shortcuts, '\W' and '\w' (see
mysql-commands).  For example:

     mysql> \W
     Show warnings enabled.
     mysql> SELECT 1/0;
     +------+
     | 1/0  |
     +------+
     | NULL |
     +------+
     1 row in set, 1 warning (0.03 sec)

     Warning (Code 1365): Division by 0
     mysql> \w
     Show warnings disabled.

13.7.6 Other Administrative Statements
--------------------------------------

13.7.6.1 BINLOG Syntax
......................

     BINLOG 'STR'

'BINLOG' is an internal-use statement.  It is generated
by the 'mysqlbinlog' program as the printable
representation of certain events in binary log files.  (See
mysqlbinlog.)  The ''STR'' value is a base 64-encoded string the that
server decodes to determine the data change indicated by the
corresponding event.  This statement requires the 'SUPER' privilege.

This statement can execute only format description events and row
events.

13.7.6.2 CACHE INDEX Syntax
...........................

     CACHE INDEX
       TBL_INDEX_LIST [, TBL_INDEX_LIST] ...
       [PARTITION (PARTITION_LIST | ALL)]
       IN KEY_CACHE_NAME

     TBL_INDEX_LIST:
       TBL_NAME [[INDEX|KEY] (INDEX_NAME[, INDEX_NAME] ...)]

     PARTITION_LIST:
       PARTITION_NAME[, PARTITION_NAME][, ...]

The 'CACHE INDEX' statement assigns table indexes to
a specific key cache.  It is used only for 'MyISAM' tables.  After the
indexes have been assigned, they can be preloaded into the cache if
desired with 'LOAD INDEX INTO CACHE'.

The following statement assigns indexes from the tables 't1', 't2', and
't3' to the key cache named 'hot_cache':

     mysql> CACHE INDEX t1, t2, t3 IN hot_cache;
     +---------+--------------------+----------+----------+
     | Table   | Op                 | Msg_type | Msg_text |
     +---------+--------------------+----------+----------+
     | test.t1 | assign_to_keycache | status   | OK       |
     | test.t2 | assign_to_keycache | status   | OK       |
     | test.t3 | assign_to_keycache | status   | OK       |
     +---------+--------------------+----------+----------+

The syntax of 'CACHE INDEX' enables you to specify
that only particular indexes from a table should be assigned to the
cache.  The current implementation assigns all the table's indexes to
the cache, so there is no reason to specify anything other than the
table name.

The key cache referred to in a 'CACHE INDEX'.
statement can be created by setting its size with a parameter setting
statement or in the server parameter settings.  For example:

     mysql> SET GLOBAL keycache1.key_buffer_size=128*1024;

Key cache parameters can be accessed as members of a structured system
variable.  See structured-system-variables.

A key cache must exist before you can assign indexes to it:

     mysql> CACHE INDEX t1 IN non_existent_cache;
     ERROR 1284 (HY000): Unknown key cache 'non_existent_cache'

By default, table indexes are assigned to the main (default) key cache
created at the server startup.  When a key cache is destroyed, all
indexes assigned to it become assigned to the default key cache again.

Index assignment affects the server globally: If one client assigns an
index to a given cache, this cache is used for all queries involving the
index, no matter which client issues the queries.

In MySQL 5.7, this statement is also supported for partitioned 'MyISAM'
tables.  You can assign one or more indexes for one, several, or all
partitions to a given key cache.  For example, you can do the following:

     CREATE TABLE pt (c1 INT, c2 VARCHAR(50), INDEX i(c1))
         ENGINE=MyISAM
         PARTITION BY HASH(c1)
         PARTITIONS 4;

     SET GLOBAL kc_fast.key_buffer_size = 128 * 1024;
     SET GLOBAL kc_slow.key_buffer_size = 128 * 1024;

     CACHE INDEX pt PARTITION (p0) IN kc_fast;
     CACHE INDEX pt PARTITION (p1, p3) IN kc_slow;

The previous set of statements performs the following actions:

   * Creates a partitioned table with 4 partitions; these partitions are
     automatically named 'p0', ..., 'p3'; this table has an index named
     'i' on column 'c1'.

   * Creates 2 key caches named 'kc_fast' and 'kc_slow'

   * Assigns the index for partition 'p0' to the 'kc_fast' key cache and
     the index for partitions 'p1' and 'p3' to the 'kc_slow' key cache;
     the index for the remaining partition ('p2') uses the server's
     default key cache.

If you wish instead to assign the indexes for all partitions in table
'pt' to a single key cache named 'kc_all', you can use either one of the
following 2 statements:

     CACHE INDEX pt PARTITION (ALL) IN kc_all;

     CACHE INDEX pt IN kc_all;

The two statements just shown are equivalent, and issuing either one of
them has exactly the same effect.  In other words, if you wish to assign
indexes for all partitions of a partitioned table to the same key cache,
then the 'PARTITION (ALL)' clause is optional.

When assigning indexes for multiple partitions to a key cache, the
partitions do not have to be contiguous, and you are not required to
list their names in any particular order.  Indexes for any partitions
that are not explicitly assigned to a key cache automatically use the
server's default key cache.

In MySQL 5.7, index preloading is also supported for partitioned
'MyISAM' tables.  For more information, see load-index.

13.7.6.3 FLUSH Syntax
.....................

     FLUSH [NO_WRITE_TO_BINLOG | LOCAL] {
         FLUSH_OPTION [, FLUSH_OPTION] ...
       | TABLES_OPTION
     }

     FLUSH_OPTION: {
         BINARY LOGS
       | DES_KEY_FILE
       | ENGINE LOGS
       | ERROR LOGS
       | GENERAL LOGS
       | HOSTS
       | LOGS
       | PRIVILEGES
       | OPTIMIZER_COSTS
       | QUERY CACHE
       | RELAY LOGS [FOR CHANNEL CHANNEL]
       | SLOW LOGS
       | STATUS
       | USER_RESOURCES
     }

     TABLES_OPTION: {
         TABLES
       | TABLES TBL_NAME [, TBL_NAME] ...
       | TABLES WITH READ LOCK
       | TABLES TBL_NAME [, TBL_NAME] ... WITH READ LOCK
       | TABLES TBL_NAME [, TBL_NAME] ... FOR EXPORT
     }

The 'FLUSH' statement has several variant forms that clear
or reload various internal caches, flush tables, or acquire locks.  To
execute 'FLUSH', you must have the 'RELOAD' privilege.
Specific flush options might require additional privileges, as described
later.

*Note*:

It is not possible to issue 'FLUSH' statements within
stored functions or triggers.  However, you may use 'FLUSH'
in stored procedures, so long as these are not called from stored
functions or triggers.  See stored-program-restrictions.

By default, the server writes 'FLUSH' statements to the
binary log so that they replicate to replication slaves.  To suppress
logging, specify the optional 'NO_WRITE_TO_BINLOG' keyword or its alias
'LOCAL'.

*Note*:

'FLUSH LOGS', 'FLUSH TABLES WITH READ LOCK' (with or without a table
list), and 'FLUSH TABLES TBL_NAME ... FOR EXPORT' are not written to the
binary log in any case because they would cause problems if replicated
to a slave.

The 'FLUSH' statement causes an implicit commit.  See
implicit-commit.

The 'mysqladmin' utility provides a command-line
interface to some flush operations, using commands such as
'flush-hosts', 'flush-logs', 'flush-privileges', 'flush-status', and
'flush-tables'.  See mysqladmin.

Sending a 'SIGHUP' signal to the server causes several flush operations
to occur that are similar to various forms of the 'FLUSH'.
statement.  See server-signal-response.

The 'RESET' statement is similar to 'FLUSH'.
See reset, for information about using the 'RESET'.
statement with replication.

The following list describes the permitted 'FLUSH'.
statement FLUSH_OPTION values.  For descriptions of 'FLUSH TABLES'
variants, see flush-tables-variants.

   * 'FLUSH BINARY LOGS'

     Closes and reopens any binary log file to which the server is
     writing.  If binary logging is enabled, the sequence number of the
     binary log file is incremented by one relative to the previous
     file.

   * 'FLUSH DES_KEY_FILE'

     Reloads the DES keys from the file that was specified with the
     '--des-key-file' option at server startup time.

     *Note*:

     The 'DES_ENCRYPT()' and 'DES_DECRYPT()' functions are deprecated as
     of MySQL 5.7.6, will be removed in a future MySQL release, and
     should no longer be used.  Consequently, '--des-key-file' and
     'DES_KEY_FILE' also are deprecated and will be removed.

   * 'FLUSH ENGINE LOGS'

     Closes and reopens any flushable logs for installed storage
     engines.  This causes 'InnoDB' to flush its logs to disk.

   * 'FLUSH ERROR LOGS'

     Closes and reopens any error log file to which the server is
     writing.

   * 'FLUSH GENERAL LOGS'

     Closes and reopens any general query log file to which the server
     is writing.

   * 'FLUSH HOSTS'

     Empties the host cache.  Flush the host cache if some of your hosts
     change IP address or if the error message 'Host 'HOST_NAME' is
     blocked' occurs for connections from legitimate hosts.  (See
     blocked-host.)  When more than 'max_connect_errors' errors occur
     successively for a given host while connecting to the MySQL server,
     MySQL assumes that something is wrong and blocks the host from
     further connection requests.  Flushing the host cache enables
     further connection attempts from the host.  The default value of
     'max_connect_errors' is 100.  To avoid this error message, start
     the server with 'max_connect_errors' set to a large value.

   * 'FLUSH LOGS'

     Closes and reopens any log file to which the server is writing.  If
     binary logging is enabled, the sequence number of the binary log
     file is incremented by one relative to the previous file.  If relay
     logging is enabled, the sequence number of the relay log file is
     incremented by one relative to the previous file.

     'FLUSH LOGS' has no effect on tables used for the general query log
     or for the slow query log (see log-destinations).

   * 'FLUSH OPTIMIZER_COSTS'

     Rereads the cost model tables so that the optimizer starts using
     the current cost estimates stored in them.  The server writes a
     warning to the error log for any unrecognized entries.  (For
     information about these tables, see cost-model.)  This
     operation affects only sessions that begin subsequent to the flush.
     Existing sessions continue to use the cost estimates that were
     current when they began.

   * 'FLUSH PRIVILEGES'

     Reloads the privileges from the grant tables in the 'mysql' system
     database.

     The server caches information in memory as a result of
     'GRANT', 'CREATE USER', 'CREATE SERVER',
     and 'INSTALL PLUGIN'.
     statements.  This memory is not released by the corresponding
     'REVOKE', 'DROP USER', 'DROP SERVER',
     and 'UNINSTALL PLUGIN'
     statements, so for a server that executes many
     instances of the statements that cause caching, there will be an
     increase in memory use.  This cached memory can be freed with
     'FLUSH PRIVILEGES'.

   * 'FLUSH QUERY CACHE'

     Defragment the query cache to better utilize its memory.  'FLUSH
     QUERY CACHE' does not remove any queries from the cache, unlike
     'FLUSH TABLES' or 'RESET QUERY CACHE'.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'FLUSH QUERY CACHE'.

   * 'FLUSH RELAY LOGS [FOR CHANNEL CHANNEL]'

     Closes and reopens any relay log file to which the server is
     writing.  If relay logging is enabled, the sequence number of the
     relay log file is incremented by one relative to the previous file.

     The 'FOR CHANNEL CHANNEL' clause enables you to name which
     replication channel the statement applies to.  Execute 'FLUSH RELAY
     LOGS FOR CHANNEL CHANNEL' to flush the relay log for a specific
     replication channel.  If no channel is named and no extra
     replication channels exist, the statement applies to the default
     channel.  If no channel is named and multiple replication channels
     exist, the statement applies to all replication channels.  For more
     information, see replication-channels.

   * 'FLUSH SLOW LOGS'

     Closes and reopens any slow query log file to which the server is
     writing.

   * 'FLUSH STATUS'

     *Note*:

     The value of the 'show_compatibility_56' system variable affects
     the operation of this option.  For details, see the description of
     that variable in server-system-variables.

     This option adds the current thread's session status variable
     values to the global values and resets the session values to zero.
     Some global variables may be reset to zero as well.  It also resets
     the counters for key caches (default and named) to zero and sets
     'Max_used_connections' to the current number of open connections.
     This information may be of use when debugging a query.  See
     bug-reports.

   * 'FLUSH USER_RESOURCES'

     Resets all per-hour user resources to zero.  This enables clients
     that have reached their hourly connection, query, or update limits
     to resume activity immediately.  'FLUSH USER_RESOURCES' does not
     apply to the limit on maximum simultaneous connections that is
     controlled by the 'max_user_connections' system variable.  See
     user-resources.

*FLUSH TABLES Syntax*

'FLUSH TABLES' flushes tables, and, depending on the variant used,
acquires locks.  Any 'TABLES' variant used in a 'FLUSH'.
statement must be the only option used.  'FLUSH TABLE' is a synonym for
'FLUSH TABLES'.

*Note*:

The descriptions here that indicate tables are flushed by closing them
apply differently for 'InnoDB', which flushes table contents to disk but
leaves them open.  This still permits table files to be copied while the
tables are open, as long as other activity does not modify them.

   * 'FLUSH TABLES'

     Closes all open tables, forces all tables in use to be closed, and
     flushes the query cache and prepared statement cache.  'FLUSH
     TABLES' also removes all query results from the query cache, like
     the 'RESET QUERY CACHE' statement.  For information about query
     caching and prepared statement caching, see query-cache.
     and statement-caching.

     'FLUSH TABLES' is not permitted when there is an active 'LOCK TABLES ... READ'.
     To flush and lock tables, use
     'FLUSH TABLES TBL_NAME ... WITH READ LOCK' instead.

   * 'FLUSH TABLES TBL_NAME [, TBL_NAME] ...'

     With a list of one or more comma-separated table names, this
     statement is like 'FLUSH TABLES' with no names except that the
     server flushes only the named tables.  If a named table does not
     exist, no error occurs.

   * 'FLUSH TABLES WITH READ LOCK'

     Closes all open tables and locks all tables for all databases with
     a global read lock.  This is a very convenient way to get backups
     if you have a file system such as Veritas or ZFS that can take
     snapshots in time.  Use 'UNLOCK TABLES' to
     release the lock.

     'FLUSH TABLES WITH READ LOCK' acquires a global read lock rather
     than table locks, so it is not subject to the same behavior as
     'LOCK TABLES' and 'UNLOCK TABLES'
     with respect to table locking and implicit commits:

        * 'UNLOCK TABLES' implicitly commits any
          active transaction only if any tables currently have been
          locked with 'LOCK TABLES'.  The commit does
          not occur for 'UNLOCK TABLES' following
          'FLUSH TABLES WITH READ LOCK' because the latter statement
          does not acquire table locks.

        * Beginning a transaction causes table locks acquired with
          'LOCK TABLES' to be released, as though you had
          executed 'UNLOCK TABLES'.  Beginning a
          transaction does not release a global read lock acquired with
          'FLUSH TABLES WITH READ LOCK'.

     'FLUSH TABLES WITH READ LOCK' is not compatible with XA
     transactions.

     'FLUSH TABLES WITH READ LOCK' does not prevent the server from
     inserting rows into the log tables (see log-destinations).

   * 'FLUSH TABLES TBL_NAME [, TBL_NAME] ... WITH READ LOCK'

     This statement flushes and acquires read locks for the named
     tables.  The statement first acquires exclusive metadata locks for
     the tables, so it waits for transactions that have those tables
     open to complete.  Then the statement flushes the tables from the
     table cache, reopens the tables, acquires table locks (like
     'LOCK TABLES ... READ'), and downgrades the metadata
     locks from exclusive to shared.  After the statement acquires locks
     and downgrades the metadata locks, other sessions can read but not
     modify the tables.

     Because this statement acquires table locks, you must have the
     'LOCK TABLES' privilege for each table, in addition to the 'RELOAD'
     privilege that is required to use any 'FLUSH'.
     statement.

     This statement applies only to existing base (non-'TEMPORARY)
     'tables.  If a name refers to a base table, that table is used.  If
     it refers to a 'TEMPORARY' table, it is ignored.  If a name applies
     to a view, an 'ER_WRONG_OBJECT' error occurs.  Otherwise, an
     'ER_NO_SUCH_TABLE' error occurs.

     Use 'UNLOCK TABLES' to release the locks, see
     'LOCK TABLES' to release the locks and acquire other
     locks, or 'START TRANSACTION' to release the locks
     and begin a new transaction.

     This 'FLUSH TABLES' variant enables tables to be flushed and locked
     in a single operation.  It provides a workaround for the
     restriction that 'FLUSH TABLES' is not permitted when there is an
     active 'LOCK TABLES ... READ'.

     This statement does not perform an implicit 'UNLOCK TABLES',
     so an error results if you use the statement while
     there is any active 'LOCK TABLES' or use it a
     second time without first releasing the locks acquired.

     If a flushed table was opened with 'HANDLER', the
     handler is implicitly flushed and loses its position.

   * 'FLUSH TABLES TBL_NAME [, TBL_NAME] ... FOR EXPORT'

     This 'FLUSH TABLES' variant applies to 'InnoDB' tables.  It ensures
     that changes to the named tables have been flushed to disk so that
     binary table copies can be made while the server is running.

     The statement works like this:

       1. It acquires shared metadata locks for the named tables.  The
          statement blocks as long as other sessions have active
          transactions that have modified those tables or hold table
          locks for them.  When the locks have been acquired, the
          statement blocks transactions that attempt to update the
          tables, while permitting read-only operations to continue.

       2. It checks whether all storage engines for the tables support
          'FOR EXPORT'.  If any do not, an 'ER_ILLEGAL_HA' error occurs
          and the statement fails.

       3. The statement notifies the storage engine for each table to
          make the table ready for export.  The storage engine must
          ensure that any pending changes are written to disk.

       4. The statement puts the session in lock-tables mode so that the
          metadata locks acquired earlier are not released when the 'FOR
          EXPORT' statement completes.

     The 'FLUSH TABLES ... FOR EXPORT' statement requires that you have
     the 'SELECT' privilege for each table.  Because this
     statement acquires table locks, you must also have the 'LOCK
     TABLES' privilege for each table, in addition to the 'RELOAD'
     privilege that is required to use any 'FLUSH'.
     statement.

     This statement applies only to existing base (non-'TEMPORARY')
     tables.  If a name refers to a base table, that table is used.  If
     it refers to a 'TEMPORARY' table, it is ignored.  If a name applies
     to a view, an 'ER_WRONG_OBJECT' error occurs.  Otherwise, an
     'ER_NO_SUCH_TABLE' error occurs.

     'InnoDB' supports 'FOR EXPORT' for tables that have their own
     '.ibd' file file (that is, tables created with the
     'innodb_file_per_table' setting enabled).  'InnoDB' ensures when
     notified by the 'FOR EXPORT' statement that any changes have been
     flushed to disk.  This permits a binary copy of table contents to
     be made while the 'FOR EXPORT' statement is in effect because the
     '.ibd' file is transaction consistent and can be copied while the
     server is running.  'FOR EXPORT' does not apply to 'InnoDB' system
     tablespace files, or to 'InnoDB' tables that have 'FULLTEXT'
     indexes.

     'FLUSH TABLES ...FOR EXPORT' is supported for partitioned 'InnoDB'
     tables.

     When notified by 'FOR EXPORT', 'InnoDB' writes to disk certain
     kinds of data that is normally held in memory or in separate disk
     buffers outside the tablespace files.  For each table, 'InnoDB'
     also produces a file named 'TABLE_NAME.cfg' in the same database
     directory as the table.  The '.cfg' file contains metadata needed
     to reimport the tablespace files later, into the same or different
     server.

     When the 'FOR EXPORT' statement completes, 'InnoDB' will have
     flushed all dirty pages to the table data files.  Any change buffer
     entries are merged prior to flushing.  At this point, the tables
     are locked and quiescent: The tables are in a transactionally
     consistent state on disk and you can copy the '.ibd' tablespace
     files along with the corresponding '.cfg' files to get a consistent
     snapshot of those tables.

     For the procedure to reimport the copied table data into a MySQL
     instance, see tablespace-copying.

     After you are done with the tables, use 'UNLOCK TABLES'
     to release the locks, see 'LOCK TABLES'
     to release the locks and acquire other locks, or
     'START TRANSACTION' to release the locks and begin a new
     transaction.

     While any of these statements is in effect within the session,
     attempts to use 'FLUSH TABLES ... FOR EXPORT' produce an error:

          FLUSH TABLES ... WITH READ LOCK
          FLUSH TABLES ... FOR EXPORT
          LOCK TABLES ... READ
          LOCK TABLES ... WRITE

     While 'FLUSH TABLES ... FOR EXPORT' is in effect within the
     session, attempts to use any of these statements produce an error:

          FLUSH TABLES WITH READ LOCK
          FLUSH TABLES ... WITH READ LOCK
          FLUSH TABLES ... FOR EXPORT

13.7.6.4 KILL Syntax
....................

     KILL [CONNECTION | QUERY] PROCESSLIST_ID

Each connection to 'mysqld' runs in a separate thread.
You can kill a thread with the 'KILL PROCESSLIST_ID' statement.

Thread processlist identifiers can be determined from the 'ID' column of
the 'INFORMATION_SCHEMA.PROCESSLIST' table,
the 'Id' column of 'SHOW PROCESSLIST' output,
and the 'PROCESSLIST_ID' column of the Performance Schema
'threads' table.  The value for the current thread is
returned by the 'CONNECTION_ID()' function.

'KILL' permits an optional 'CONNECTION' or 'QUERY'
modifier:

   * 'KILL CONNECTION' is the same as 'KILL'.
     with no modifier: It terminates the connection associated with the
     given PROCESSLIST_ID, after terminating any statement the
     connection is executing.

   * 'KILL QUERY' terminates the statement the connection
     is currently executing, but leaves the connection itself intact.

If you have the 'PROCESS' privilege, you can see all threads.  If you
have the 'SUPER' privilege, you can kill all threads and statements.
Otherwise, you can see and kill only your own threads and statements.

You can also use the 'mysqladmin processlist' and
'mysqladmin kill' commands to examine and kill
threads.

*Note*:

You cannot use 'KILL' with the Embedded MySQL Server
library because the embedded server merely runs inside the threads of
the host application.  It does not create any connection threads of its
own.

When you use 'KILL', a thread-specific kill flag is set for
the thread.  In most cases, it might take some time for the thread to
die because the kill flag is checked only at specific intervals:

   * During 'SELECT' operations, for 'ORDER BY' and
     'GROUP BY' loops, the flag is checked after reading a block of
     rows.  If the kill flag is set, the statement is aborted.

   * 'ALTER TABLE' operations that make a table copy
     check the kill flag periodically for each few copied rows read from
     the original table.  If the kill flag was set, the statement is
     aborted and the temporary table is deleted.

     The 'KILL' statement returns without waiting for
     confirmation, but the kill flag check aborts the operation within a
     reasonably small amount of time.  Aborting the operation to perform
     any necessary cleanup also takes some time.

   * During 'UPDATE' or 'DELETE'.
     operations, the kill flag is checked after each block read and
     after each updated or deleted row.  If the kill flag is set, the
     statement is aborted.  If you are not using transactions, the
     changes are not rolled back.

   * 'GET_LOCK()' aborts and returns 'NULL'.

   * If the thread is in the table lock handler (state: 'Locked'), the
     table lock is quickly aborted.

   * If the thread is waiting for free disk space in a write call, the
     write is aborted with a 'disk full' error message.

*Warning*:

Killing a 'REPAIR TABLE' or 'OPTIMIZE TABLE'
operation on a 'MyISAM' table results in a table that is
corrupted and unusable.  Any reads or writes to such a table fail until
you optimize or repair it again (without interruption).

13.7.6.5 LOAD INDEX INTO CACHE Syntax
.....................................

     LOAD INDEX INTO CACHE
       TBL_INDEX_LIST [, TBL_INDEX_LIST] ...

     TBL_INDEX_LIST:
       TBL_NAME
         [PARTITION (PARTITION_LIST | ALL)]
         [[INDEX|KEY] (INDEX_NAME[, INDEX_NAME] ...)]
         [IGNORE LEAVES]

     PARTITION_LIST:
         PARTITION_NAME[, PARTITION_NAME][, ...]

The 'LOAD INDEX INTO CACHE' statement preloads a
table index into the key cache to which it has been assigned by an
explicit 'CACHE INDEX' statement, or into the
default key cache otherwise.

'LOAD INDEX INTO CACHE' is used only for 'MyISAM'
tables.  In MySQL 5.7, it is also supported for partitioned 'MyISAM'
tables; in addition, indexes on partitioned tables can be preloaded for
one, several, or all partitions.

The 'IGNORE LEAVES' modifier causes only blocks for the nonleaf nodes of
the index to be preloaded.

'IGNORE LEAVES' is also supported for partitioned 'MyISAM' tables.

The following statement preloads nodes (index blocks) of indexes for the
tables 't1' and 't2':

     mysql> LOAD INDEX INTO CACHE t1, t2 IGNORE LEAVES;
     +---------+--------------+----------+----------+
     | Table   | Op           | Msg_type | Msg_text |
     +---------+--------------+----------+----------+
     | test.t1 | preload_keys | status   | OK       |
     | test.t2 | preload_keys | status   | OK       |
     +---------+--------------+----------+----------+

This statement preloads all index blocks from 't1'.  It preloads only
blocks for the nonleaf nodes from 't2'.

The syntax of 'LOAD INDEX INTO CACHE' enables you to
specify that only particular indexes from a table should be preloaded.
The current implementation preloads all the table's indexes into the
cache, so there is no reason to specify anything other than the table
name.

In MySQL 5.7, it is possible to preload indexes on specific partitions
of partitioned 'MyISAM' tables.  For example, of the following 2
statements, the first preloads indexes for partition 'p0' of a
partitioned table 'pt', while the second preloads the indexes for
partitions 'p1' and 'p3' of the same table:

     LOAD INDEX INTO CACHE pt PARTITION (p0);
     LOAD INDEX INTO CACHE pt PARTITION (p1, p3);

To preload the indexes for all partitions in table 'pt', you can use
either one of the following 2 statements:

     LOAD INDEX INTO CACHE pt PARTITION (ALL);

     LOAD INDEX INTO CACHE pt;

The two statements just shown are equivalent, and issuing either one of
them has exactly the same effect.  In other words, if you wish to
preload indexes for all partitions of a partitioned table, then the
'PARTITION (ALL)' clause is optional.

When preloading indexes for multiple partitions, the partitions do not
have to be contiguous, and you are not required to list their names in
any particular order.

'LOAD INDEX INTO CACHE ... IGNORE LEAVES' fails
unless all indexes in a table have the same block size.  You can
determine index block sizes for a table by using 'myisamchk -dv'
and checking the 'Blocksize' column.

13.7.6.6 RESET Syntax
.....................

     RESET RESET_OPTION [, RESET_OPTION] ...

     RESET_OPTION: {
         MASTER
       | QUERY CACHE
       | SLAVE
     }

The 'RESET' statement is used to clear the state of
various server operations.  You must have the 'RELOAD' privilege to
execute 'RESET'.

'RESET' acts as a stronger version of the 'FLUSH'
statement.  See flush.

The 'RESET' statement causes an implicit commit.  See
implicit-commit.

In MySQL 5.7.1, 'gtid_next' must be set to 'AUTOMATIC' before issuing
this statement.  This restriction does not apply in MySQL 5.7.2 or
later.  (Bug #16062608, Bug #16715809, Bug #69045)

The following list describes the permitted 'RESET'.
statement RESET_OPTION values:

   * 'RESET MASTER'

     Deletes all binary logs listed in the index file, resets the binary
     log index file to be empty, and creates a new binary log file.

   * 'RESET QUERY CACHE'

     Removes all query results from the query cache.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'RESET QUERY CACHE'.

   * 'RESET SLAVE'

     Makes the slave forget its replication position in the master
     binary logs.  Also resets the relay log by deleting any existing
     relay log files and beginning a new one.

13.7.6.7 SHUTDOWN Syntax
........................

     SHUTDOWN

This statement stops the MySQL server.  It requires the 'SHUTDOWN'
privilege.

'SHUTDOWN' was added in MySQL 5.7.9.  It provides an
SQL-level interface to the same functionality available using the
'mysqladmin shutdown' command or the
'mysql_shutdown()'. C API function.

13.8 Utility Statements
=======================

13.8.1 DESCRIBE Syntax
----------------------

The 'DESCRIBE' and 'EXPLAIN' statements
are synonyms, used either to obtain information about table structure or
query execution plans.  For more information, see show-columns,
and explain.

13.8.2 EXPLAIN Syntax
---------------------

     {EXPLAIN | DESCRIBE | DESC}
         TBL_NAME [COL_NAME | WILD]

     {EXPLAIN | DESCRIBE | DESC}
         [EXPLAIN_TYPE]
         {EXPLAINABLE_STMT | FOR CONNECTION CONNECTION_ID}

     EXPLAIN_TYPE: {
         EXTENDED
       | PARTITIONS
       | FORMAT = FORMAT_NAME
     }

     FORMAT_NAME: {
         TRADITIONAL
       | JSON
     }

     EXPLAINABLE_STMT: {
         SELECT statement
       | DELETE statement
       | INSERT statement
       | REPLACE statement
       | UPDATE statement
     }

The 'DESCRIBE' and 'EXPLAIN' statements
are synonyms.  In practice, the 'DESCRIBE' keyword is
more often used to obtain information about table structure, whereas
'EXPLAIN' is used to obtain a query execution plan (that
is, an explanation of how MySQL would execute a query).

The following discussion uses the 'DESCRIBE' and
'EXPLAIN' keywords in accordance with those uses, but the
MySQL parser treats them as completely synonymous.

   * explain-table-structure

   * explain-execution-plan

*Obtaining Table Structure Information*

'DESCRIBE' provides information about the columns in a
table:

     mysql> DESCRIBE City;
     +------------+----------+------+-----+---------+----------------+
     | Field      | Type     | Null | Key | Default | Extra          |
     +------------+----------+------+-----+---------+----------------+
     | Id         | int(11)  | NO   | PRI | NULL    | auto_increment |
     | Name       | char(35) | NO   |     |         |                |
     | Country    | char(3)  | NO   | UNI |         |                |
     | District   | char(20) | YES  | MUL |         |                |
     | Population | int(11)  | NO   |     | 0       |                |
     +------------+----------+------+-----+---------+----------------+

'DESCRIBE' is a shortcut for 'SHOW COLUMNS'.
These statements also display information for views.  The
description for 'SHOW COLUMNS' provides more
information about the output columns.  See show-columns.

By default, see 'DESCRIBE' displays information about all
columns in the table.  COL_NAME, if given, is the name of a column in
the table.  In this case, the statement displays information only for
the named column.  WILD, if given, is a pattern string.  It can contain
the SQL '%' and '_' wildcard characters.  In this case, the statement
displays output only for the columns with names matching the string.
There is no need to enclose the string within quotation marks unless it
contains spaces or other special characters.

The 'DESCRIBE' statement is provided for compatibility
with Oracle.

The 'SHOW CREATE TABLE', 'SHOW TABLE STATUS',
and 'SHOW INDEX'.
statements also provide information about tables.  See show.

*Obtaining Execution Plan Information*

The 'EXPLAIN' statement provides information about how
MySQL executes statements:

   * 'EXPLAIN' works with 'SELECT',
     'DELETE', 'INSERT', 'REPLACE',
     and 'UPDATE' statements.

   * When 'EXPLAIN' is used with an explainable
     statement, MySQL displays information from the optimizer about the
     statement execution plan.  That is, MySQL explains how it would
     process the statement, including information about how tables are
     joined and in which order.  For information about using
     'EXPLAIN' to obtain execution plan information, see
     explain-output.

   * When 'EXPLAIN' is used with 'FOR CONNECTION
     CONNECTION_ID' rather than an explainable statement, it displays
     the execution plan for the statement executing in the named
     connection.  See explain-for-connection.

   * For 'SELECT' statements, see 'EXPLAIN'.
     produces additional execution plan information that can be
     displayed using 'SHOW WARNINGS'.  See
     explain-extended.

     *Note*:

     In older MySQL releases, extended information was produced using
     'EXPLAIN EXTENDED'.  That syntax is still recognized
     for backward compatibility but extended output is now enabled by
     default, so the 'EXTENDED' keyword is superfluous and deprecated.
     Its use results in a warning, and it is removed from
     'EXPLAIN' syntax in MySQL 8.0.

   * 'EXPLAIN' is useful for examining queries involving
     partitioned tables.  See partitioning-info.

     *Note*:

     In older MySQL releases, partition information was produced using
     'EXPLAIN PARTITIONS'.  That syntax is still
     recognized for backward compatibility but partition output is now
     enabled by default, so the 'PARTITIONS' keyword is superfluous and
     deprecated.  Its use results in a warning, and it is removed from
     'EXPLAIN' syntax in MySQL 8.0.

   * The 'FORMAT' option can be used to select the output format.
     'TRADITIONAL' presents the output in tabular format.  This is the
     default if no 'FORMAT' option is present.  'JSON' format displays
     the information in JSON format.

'EXPLAIN' requires the 'SELECT' privilege for any tables
or views accessed, including any underlying tables of views.  For views,
see 'EXPLAIN' also requires the 'SHOW VIEW' privilege.

With the help of 'EXPLAIN', you can see where you should
add indexes to tables so that the statement executes faster by using
indexes to find rows.  You can also use 'EXPLAIN' to
check whether the optimizer joins the tables in an optimal order.  To
give a hint to the optimizer to use a join order corresponding to the
order in which the tables are named in a 'SELECT'.
statement, begin the statement with 'SELECT STRAIGHT_JOIN' rather than
just 'SELECT'.  (See select.)

The optimizer trace may sometimes provide information complementary to
that of 'EXPLAIN'.  However, the optimizer trace format
and content are subject to change between versions.  For details, see
MySQL Internals: Tracing the Optimizer
(http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

If you have a problem with indexes not being used when you believe that
they should be, run 'ANALYZE TABLE' to update
table statistics, such as cardinality of keys, that can affect the
choices the optimizer makes.  See analyze-table.

*Note*:

MySQL Workbench has a Visual Explain capability that provides a visual
representation of 'EXPLAIN' output.  See Tutorial: Using
Explain to Improve Query Performance
(http://dev.mysql.com/doc/workbench/en/wb-tutorial-visual-explain-dbt3.html).

13.8.3 HELP Syntax
------------------

     HELP 'SEARCH_STRING'

The 'HELP' statement returns online information from the
MySQL Reference manual.  Its proper operation requires that the help
tables in the 'mysql' database be initialized with help topic
information (see server-side-help-support).

The 'HELP' statement searches the help tables for the given
search string and displays the result of the search.  The search string
is not case-sensitive.

The search string can contain the wildcard characters '%' and '_'.
These have the same meaning as for pattern-matching operations performed
with the 'LIKE' operator.  For example, 'HELP 'rep%'' returns a list of
topics that begin with 'rep'.

The HELP statement understands several types of search strings:

   * At the most general level, use 'contents' to retrieve a list of the
     top-level help categories:

          HELP 'contents'

   * For a list of topics in a given help category, such as 'Data
     Types', use the category name:

          HELP 'data types'

   * For help on a specific help topic, such as the 'ASCII()' function
     or the 'CREATE TABLE' statement, use the
     associated keyword or keywords:

          HELP 'ascii'
          HELP 'create table'

In other words, the search string matches a category, many topics, or a
single topic.  You cannot necessarily tell in advance whether a given
search string will return a list of items or the help information for a
single help topic.  However, you can tell what kind of response
'HELP' returned by examining the number of rows and columns in
the result set.

The following descriptions indicate the forms that the result set can
take.  Output for the example statements is shown using the familiar
'tabular' or 'vertical' format that you see when using the
'mysql' client, but note that 'mysql' itself
reformats 'HELP' result sets in a different way.

   * Empty result set

     No match could be found for the search string.

   * Result set containing a single row with three columns

     This means that the search string yielded a hit for the help topic.
     The result has three columns:

        * 'name': The topic name.

        * 'description': Descriptive help text for the topic.

        * 'example': Usage example or examples.  This column might be
          blank.

     Example: 'HELP 'replace''

     Yields:

          name: REPLACE
          description: Syntax:
          REPLACE(str,from_str,to_str)

          Returns the string str with all occurrences of the string from_str
          replaced by the string to_str. REPLACE() performs a case-sensitive
          match when searching for from_str.
          example: mysql> SELECT REPLACE('www.mysql.com', 'w', 'Ww');
                  -> 'WwWwWw.mysql.com'

   * Result set containing multiple rows with two columns

     This means that the search string matched many help topics.  The
     result set indicates the help topic names:

        * 'name': The help topic name.

        * 'is_it_category': 'Y' if the name represents a help category,
          'N' if it does not.  If it does not, the 'name' value when
          specified as the argument to the 'HELP' statement
          should yield a single-row result set containing a description
          for the named item.

     Example: 'HELP 'status''

     Yields:

          +-----------------------+----------------+
          | name                  | is_it_category |
          +-----------------------+----------------+
          | SHOW                  | N              |
          | SHOW ENGINE           | N              |
          | SHOW MASTER STATUS    | N              |
          | SHOW PROCEDURE STATUS | N              |
          | SHOW SLAVE STATUS     | N              |
          | SHOW STATUS           | N              |
          | SHOW TABLE STATUS     | N              |
          +-----------------------+----------------+

   * Result set containing multiple rows with three columns

     This means the search string matches a category.  The result set
     contains category entries:

        * 'source_category_name': The help category name.

        * 'name': The category or topic name

        * 'is_it_category': 'Y' if the name represents a help category,
          'N' if it does not.  If it does not, the 'name' value when
          specified as the argument to the 'HELP' statement
          should yield a single-row result set containing a description
          for the named item.

     Example: 'HELP 'functions''

     Yields:

          +----------------------+-------------------------+----------------+
          | source_category_name | name                    | is_it_category |
          +----------------------+-------------------------+----------------+
          | Functions            | CREATE FUNCTION         | N              |
          | Functions            | DROP FUNCTION           | N              |
          | Functions            | Bit Functions           | Y              |
          | Functions            | Comparison operators    | Y              |
          | Functions            | Control flow functions  | Y              |
          | Functions            | Date and Time Functions | Y              |
          | Functions            | Encryption Functions    | Y              |
          | Functions            | Information Functions   | Y              |
          | Functions            | Logical operators       | Y              |
          | Functions            | Miscellaneous Functions | Y              |
          | Functions            | Numeric Functions       | Y              |
          | Functions            | String Functions        | Y              |
          +----------------------+-------------------------+----------------+

13.8.4 USE Syntax
-----------------

     USE DB_NAME

The 'USE DB_NAME' statement tells MySQL to use the DB_NAME database as
the default (current) database for subsequent statements.  The database
remains the default until the end of the session or another 'USE'
statement is issued:

     USE db1;
     SELECT COUNT(*) FROM mytable;   # selects from db1.mytable
     USE db2;
     SELECT COUNT(*) FROM mytable;   # selects from db2.mytable

Making a particular database the default by means of the 'USE'
statement does not preclude you from accessing tables in other
databases.  The following example accesses the 'author' table from the
'db1' database and the 'editor' table from the 'db2' database:

     USE db1;
     SELECT author_name,editor_name FROM author,db2.editor
       WHERE author.editor_id = db2.editor.editor_id;

14 The InnoDB Storage Engine
****************************

14.1 Introduction to InnoDB
===========================

'InnoDB' is a general-purpose storage engine that balances high
reliability and high performance.  In MySQL 5.7, 'InnoDB' is the default
MySQL storage engine.  Unless you have configured a different default
storage engine, issuing a 'CREATE TABLE' statement
without an 'ENGINE=' clause creates an 'InnoDB' table.

*Key Advantages of InnoDB*

   * Its DML operations follow the ACID model, with transactions
     featuring commit, rollback, and crash-recovery capabilities to
     protect user data.  See mysql-acid for more information.

   * Row-level locking and Oracle-style consistent reads increase
     multi-user concurrency and performance.  See
     innodb-locking-transaction-model for more information.

   * 'InnoDB' tables arrange your data on disk to optimize queries based
     on primary keys.  Each 'InnoDB' table has a primary key index
     called the clustered index that organizes the data to minimize I/O
     for primary key lookups.  See innodb-index-types for more
     information.

   * To maintain data integrity, 'InnoDB' supports 'FOREIGN KEY'
     constraints.  With foreign keys, inserts, updates, and deletes are
     checked to ensure they do not result in inconsistencies across
     different tables.  See innodb-foreign-key-constraints for
     more information.

*InnoDB Storage Engine Features*

Feature                                     Support

*B-tree indexes*                            Yes

*Backup/point-in-time recovery*             Yes
(Implemented in the server, rather than
in the storage engine.)

*Cluster database support*                  No

*Clustered indexes*                         Yes

*Compressed data*                           Yes

*Data caches*                               Yes

*Encrypted data* (Implemented in the        Yes
server via encryption functions.
Data-at-rest tablespace encryption is
available in MySQL 5.7 and later.)

*Foreign key support*                       Yes

*Full-text search indexes*                  Yes (InnoDB support for
                                            FULLTEXT indexes is
                                            available in MySQL 5.6 and
                                            later.)

*Geospatial data type support*              Yes

*Geospatial indexing support*               Yes (InnoDB support for
                                            geospatial indexing is
                                            available in MySQL 5.7 and
                                            later.)

*Hash indexes*                              No (InnoDB utilizes hash
                                            indexes internally for its
                                            Adaptive Hash Index
                                            feature.)

*Index caches*                              Yes

*Locking granularity*                       Row

*MVCC*                                      Yes

*Query cache support*                       Yes

*Replication support* (Implemented in the   Yes
server, rather than in the storage
engine.)

*Storage limits*                            64TB

*T-tree indexes*                            No

*Transactions*                              Yes

*Update statistics for data dictionary*     Yes

To compare the features of 'InnoDB' with other storage engines provided
with MySQL, see the _Storage Engine Features_ table in
storage-engines.

*InnoDB Enhancements and New Features*

For information about 'InnoDB' enhancements and new features, refer to:

   * The 'InnoDB' enhancements list in mysql-nutshell.

   * The Release Notes
     (http://dev.mysql.com/doc/relnotes/mysql/5.7/en/).

*Additional InnoDB Information and Resources*

   * For 'InnoDB'-related terms and definitions, see the
     glossary.

   * For a forum dedicated to the 'InnoDB' storage engine, see MySQL
     Forums::InnoDB (http://forums.mysql.com/list.php?22).

   * 'InnoDB' is published under the same GNU GPL License Version 2 (of
     June 1991) as MySQL. For more information on MySQL licensing, see
     <http://www.mysql.com/company/legal/licensing/>.

14.1.1 Benefits of Using InnoDB Tables
--------------------------------------

You may find 'InnoDB' tables beneficial for the following reasons:

   * If your server crashes because of a hardware or software issue,
     regardless of what was happening in the database at the time, you
     don't need to do anything special after restarting the database.
     'InnoDB' crash recovery automatically finalizes any changes that
     were committed before the time of the crash, and undoes any changes
     that were in process but not committed.  Just restart and continue
     where you left off.

   * The 'InnoDB' storage engine maintains its own buffer pool that
     caches table and index data in main memory as data is accessed.
     Frequently used data is processed directly from memory.  This cache
     applies to many types of information and speeds up processing.  On
     dedicated database servers, up to 80% of physical memory is often
     assigned to the buffer pool.

   * If you split up related data into different tables, you can set up
     foreign keys that enforce referential integrity.  Update or delete
     data, and the related data in other tables is updated or deleted
     automatically.  Try to insert data into a secondary table without
     corresponding data in the primary table, and the bad data gets
     kicked out automatically.

   * If data becomes corrupted on disk or in memory, a checksum
     mechanism alerts you to the bogus data before you use it.

   * When you design your database with appropriate primary key columns
     for each table, operations involving those columns are
     automatically optimized.  It is very fast to reference the primary
     key columns in 'WHERE' clauses, see 'ORDER BY'
     clauses, see 'GROUP BY' clauses, and join
     operations.

   * Inserts, updates, and deletes are optimized by an automatic
     mechanism called change buffering.  'InnoDB' not only allows
     concurrent read and write access to the same table, it caches
     changed data to streamline disk I/O.

   * Performance benefits are not limited to giant tables with
     long-running queries.  When the same rows are accessed over and
     over from a table, a feature called the Adaptive Hash Index takes
     over to make these lookups even faster, as if they came out of a
     hash table.

   * You can compress tables and associated indexes.

   * You can create and drop indexes with much less impact on
     performance and availability.

   * Truncating a file-per-table tablespace is very fast, and can free
     up disk space for the operating system to reuse, rather than
     freeing up space within the system tablespace that only 'InnoDB'
     can reuse.

   * The storage layout for table data is more efficient for
     'BLOB' and long text fields, with the DYNAMIC row format.

   * You can monitor the internal workings of the storage engine by
     querying INFORMATION_SCHEMA tables.

   * You can monitor the performance details of the storage engine by
     querying Performance Schema tables.

   * You can freely mix 'InnoDB' tables with tables from other MySQL
     storage engines, even within the same statement.  For example, you
     can use a join operation to combine data from 'InnoDB' and
     'MEMORY' tables in a single query.

   * 'InnoDB' has been designed for CPU efficiency and maximum
     performance when processing large data volumes.

   * 'InnoDB' tables can handle large quantities of data, even on
     operating systems where file size is limited to 2GB.

For 'InnoDB'-specific tuning techniques you can apply in your
application code, see optimizing-innodb.

14.1.2 Best Practices for InnoDB Tables
---------------------------------------

This section describes best practices when using 'InnoDB' tables.

   * Specifying a primary key for every table using the most frequently
     queried column or columns, or an auto-increment value if there is
     no obvious primary key.

   * Using joins wherever data is pulled from multiple tables based on
     identical ID values from those tables.  For fast join performance,
     define foreign keys on the join columns, and declare those columns
     with the same data type in each table.  Adding foreign keys ensures
     that referenced columns are indexed, which can improve performance.
     Foreign keys also propagate deletes or updates to all affected
     tables, and prevent insertion of data in a child table if the
     corresponding IDs are not present in the parent table.

   * Turning off autocommit.  Committing hundreds of times a second puts
     a cap on performance (limited by the write speed of your storage
     device).

   * Grouping sets of related DML operations into transactions, by
     bracketing them with 'START TRANSACTION' and 'COMMIT' statements.
     While you don't want to commit too often, you also don't want to
     issue huge batches of 'INSERT', 'UPDATE',
     or 'DELETE' statements that run for hours
     without committing.

   * Not using 'LOCK TABLES' statements.  'InnoDB'
     can handle multiple sessions all reading and writing to the same
     table at once, without sacrificing reliability or high performance.
     To get exclusive write access to a set of rows, use the
     'SELECT ... FOR UPDATE' syntax to lock just
     the rows you intend to update.

   * Enabling the 'innodb_file_per_table' option or using general
     tablespaces to put the data and indexes for tables into separate
     files, instead of the system tablespace.

     The 'innodb_file_per_table' option is enabled by default.

   * Evaluating whether your data and access patterns benefit from the
     'InnoDB' table or page compression features.  You can compress
     'InnoDB' tables without sacrificing read/write capability.

   * Running your server with the option
     '--sql_mode=NO_ENGINE_SUBSTITUTION' to prevent tables being created
     with a different storage engine if there is an issue with the
     engine specified in the 'ENGINE=' clause of 'CREATE TABLE'.

14.1.3 Verifying that InnoDB is the Default Storage Engine
----------------------------------------------------------

Issue the 'SHOW ENGINES' statement to view the
available MySQL storage engines.  Look for 'DEFAULT' in the 'InnoDB'
line.

     mysql> SHOW ENGINES;

Alternatively, query the 'INFORMATION_SCHEMA.ENGINES'
table.

     mysql> SELECT * FROM INFORMATION_SCHEMA.ENGINES;

14.1.4 Testing and Benchmarking with InnoDB
-------------------------------------------

If 'InnoDB' is not your default storage engine, you can determine if
your database server or applications work correctly with 'InnoDB' by
restarting the server with '--default-storage-engine=InnoDB' defined on
the command line or with 'default-storage-engine=innodb' defined in the
'[mysqld]' section of your MySQL server option file.

Since changing the default storage engine only affects new tables as
they are created, run all your application installation and setup steps
to confirm that everything installs properly.  Then exercise all the
application features to make sure all the data loading, editing, and
querying features work.  If a table relies on a feature that is specific
to another storage engine, you will receive an error; add the
'ENGINE=OTHER_ENGINE_NAME' clause to the 'CREATE TABLE'
statement to avoid the error.

If you did not make a deliberate decision about the storage engine, and
you want to preview how certain tables work when created using 'InnoDB',
issue the command 'ALTER TABLE table_name ENGINE=InnoDB;'
for each table.  Or, to run test queries and other
statements without disturbing the original table, make a copy:

     CREATE TABLE InnoDB_Table (...) ENGINE=InnoDB AS SELECT * FROM OTHER_ENGINE_TABLE;

To assess performance with a full application under a realistic
workload, install the latest MySQL server and run benchmarks.

Test the full application lifecycle, from installation, through heavy
usage, and server restart.  Kill the server process while the database
is busy to simulate a power failure, and verify that the data is
recovered successfully when you restart the server.

Test any replication configurations, especially if you use different
MySQL versions and options on the master and slaves.

14.1.5 Turning Off InnoDB
-------------------------

Oracle recommends 'InnoDB' as the preferred storage engine for typical
database applications, from single-user wikis and blogs running on a
local system, to high-end applications pushing the limits of
performance.  In MySQL 5.7, 'InnoDB' is the default storage engine for
new tables.

*Important*:

'InnoDB' cannot be disabled.  The '--skip-innodb' option is deprecated
and has no effect, and its use results in a warning.  It will be removed
in a future MySQL release.  This also applies to its synonyms
('--innodb=OFF', '--disable-innodb', and so forth).

14.2 InnoDB and the ACID Model
==============================

The ACID model is a set of database design principles that emphasize
aspects of reliability that are important for business data and
mission-critical applications.  MySQL includes components such as the
'InnoDB' storage engine that adhere closely to the ACID model, so that
data is not corrupted and results are not distorted by exceptional
conditions such as software crashes and hardware malfunctions.  When you
rely on ACID-compliant features, you do not need to reinvent the wheel
of consistency checking and crash recovery mechanisms.  In cases where
you have additional software safeguards, ultra-reliable hardware, or an
application that can tolerate a small amount of data loss or
inconsistency, you can adjust MySQL settings to trade some of the ACID
reliability for greater performance or throughput.

The following sections discuss how MySQL features, in particular the
'InnoDB' storage engine, interact with the categories of the ACID model:

   * *A*: atomicity.

   * *C*: consistency.

   * *I:*: isolation.

   * *D*: durability.

*Atomicity*

The *atomicity* aspect of the ACID model mainly involves 'InnoDB'
transactions.  Related MySQL features include:

   * Autocommit setting.

   * 'COMMIT' statement.

   * 'ROLLBACK' statement.

   * Operational data from the 'INFORMATION_SCHEMA' tables.

*Consistency*

The *consistency* aspect of the ACID model mainly involves internal
'InnoDB' processing to protect data from crashes.  Related MySQL
features include:

   * 'InnoDB' doublewrite buffer.

   * 'InnoDB' crash recovery.

*Isolation*

The *isolation* aspect of the ACID model mainly involves 'InnoDB'
transactions, in particular the isolation level that applies to each
transaction.  Related MySQL features include:

   * Autocommit setting.

   * 'SET ISOLATION LEVEL' statement.

   * The low-level details of 'InnoDB' locking.  During performance
     tuning, you see these details through 'INFORMATION_SCHEMA' tables.

*Durability*

The *durability* aspect of the ACID model involves MySQL software
features interacting with your particular hardware configuration.
Because of the many possibilities depending on the capabilities of your
CPU, network, and storage devices, this aspect is the most complicated
to provide concrete guidelines for.  (And those guidelines might take
the form of buy 'new hardware'.)  Related MySQL features include:

   * 'InnoDB' doublewrite buffer, turned on and off by the
     'innodb_doublewrite' configuration option.

   * Configuration option 'innodb_flush_log_at_trx_commit'.

   * Configuration option 'sync_binlog'.

   * Configuration option 'innodb_file_per_table'.

   * Write buffer in a storage device, such as a disk drive, SSD, or
     RAID array.

   * Battery-backed cache in a storage device.

   * The operating system used to run MySQL, in particular its support
     for the 'fsync()' system call.

   * Uninterruptible power supply (UPS) protecting the electrical power
     to all computer servers and storage devices that run MySQL servers
     and store MySQL data.

   * Your backup strategy, such as frequency and types of backups, and
     backup retention periods.

   * For distributed or hosted data applications, the particular
     characteristics of the data centers where the hardware for the
     MySQL servers is located, and network connections between the data
     centers.

14.3 InnoDB Multi-Versioning
============================

'InnoDB' is a multi-versioned storage engine: it keeps information about
old versions of changed rows, to support transactional features such as
concurrency and rollback.  This information is stored in the tablespace
in a data structure called a rollback segment (after an analogous data
structure in Oracle).  'InnoDB' uses the information in the rollback
segment to perform the undo operations needed in a transaction rollback.
It also uses the information to build earlier versions of a row for a
consistent read.

Internally, 'InnoDB' adds three fields to each row stored in the
database.  A 6-byte 'DB_TRX_ID' field indicates the transaction
identifier for the last transaction that inserted or updated the row.
Also, a deletion is treated internally as an update where a special bit
in the row is set to mark it as deleted.  Each row also contains a
7-byte 'DB_ROLL_PTR' field called the roll pointer.  The roll pointer
points to an undo log record written to the rollback segment.  If the
row was updated, the undo log record contains the information necessary
to rebuild the content of the row before it was updated.  A 6-byte
'DB_ROW_ID' field contains a row ID that increases monotonically as new
rows are inserted.  If 'InnoDB' generates a clustered index
automatically, the index contains row ID values.  Otherwise, the
'DB_ROW_ID' column does not appear in any index.

Undo logs in the rollback segment are divided into insert and update
undo logs.  Insert undo logs are needed only in transaction rollback and
can be discarded as soon as the transaction commits.  Update undo logs
are used also in consistent reads, but they can be discarded only after
there is no transaction present for which 'InnoDB' has assigned a
snapshot that in a consistent read could need the information in the
update undo log to build an earlier version of a database row.

Commit your transactions regularly, including those transactions that
issue only consistent reads.  Otherwise, 'InnoDB' cannot discard data
from the update undo logs, and the rollback segment may grow too big,
filling up your tablespace.

The physical size of an undo log record in the rollback segment is
typically smaller than the corresponding inserted or updated row.  You
can use this information to calculate the space needed for your rollback
segment.

In the 'InnoDB' multi-versioning scheme, a row is not physically removed
from the database immediately when you delete it with an SQL statement.
'InnoDB' only physically removes the corresponding row and its index
records when it discards the update undo log record written for the
deletion.  This removal operation is called a purge, and it is quite
fast, usually taking the same order of time as the SQL statement that
did the deletion.

If you insert and delete rows in smallish batches at about the same rate
in the table, the purge thread can start to lag behind and the table can
grow bigger and bigger because of all the 'dead' rows, making everything
disk-bound and very slow.  In such a case, throttle new row operations,
and allocate more resources to the purge thread by tuning the
'innodb_max_purge_lag' system variable.  See innodb-parameters
for more information.

*Multi-Versioning and Secondary Indexes*

'InnoDB' multiversion concurrency control (MVCC) treats secondary
indexes differently than clustered indexes.  Records in a clustered
index are updated in-place, and their hidden system columns point undo
log entries from which earlier versions of records can be reconstructed.
Unlike clustered index records, secondary index records do not contain
hidden system columns nor are they updated in-place.

When a secondary index column is updated, old secondary index records
are delete-marked, new records are inserted, and delete-marked records
are eventually purged.  When a secondary index record is delete-marked
or the secondary index page is updated by a newer transaction, 'InnoDB'
looks up the database record in the clustered index.  In the clustered
index, the record's 'DB_TRX_ID' is checked, and the correct version of
the record is retrieved from the undo log if the record was modified
after the reading transaction was initiated.

If a secondary index record is marked for deletion or the secondary
index page is updated by a newer transaction, the covering index
technique is not used.  Instead of returning values from the index
structure, 'InnoDB' looks up the record in the clustered index.

However, if the index condition pushdown (ICP)
optimization is enabled, and
parts of the 'WHERE' condition can be evaluated using only fields from
the index, the MySQL server still pushes this part of the 'WHERE'
condition down to the storage engine where it is evaluated using the
index.  If no matching records are found, the clustered index lookup is
avoided.  If matching records are found, even among delete-marked
records, 'InnoDB' looks up the record in the clustered index.

14.4 InnoDB Architecture
========================

This section provides an introduction to the major components of the
'InnoDB' storage engine architecture.

14.4.1 Buffer Pool
------------------

The buffer pool is an area in main memory where 'InnoDB' caches table
and index data as data is accessed.  The buffer pool allows frequently
used data to be processed directly from memory, which speeds up
processing.  On dedicated database servers, up to 80% of physical memory
is often assigned to the 'InnoDB' buffer pool.

For efficiency of high-volume read operations, the buffer pool is
divided into pages that can potentially hold multiple rows.  For
efficiency of cache management, the buffer pool is implemented as a
linked list of pages; data that is rarely used is aged out of the cache,
using a variation of the LRU algorithm.

For more information, see innodb-buffer-pool, and
innodb-performance-buffer-pool.

14.4.2 Change Buffer
--------------------

The change buffer is a special data structure that caches changes to
secondary index pages when affected pages are not in the buffer pool.
The buffered changes, which may result from 'INSERT',
'UPDATE', or 'DELETE' operations (DML), are
merged later when the pages are loaded into the buffer pool by other
read operations.

Unlike clustered indexes, secondary indexes are usually nonunique, and
inserts into secondary indexes happen in a relatively random order.
Similarly, deletes and updates may affect secondary index pages that are
not adjacently located in an index tree.  Merging cached changes at a
later time, when affected pages are read into the buffer pool by other
operations, avoids substantial random access I/O that would be required
to read-in secondary index pages from disk.

Periodically, the purge operation that runs when the system is mostly
idle, or during a slow shutdown, writes the updated index pages to disk.
The purge operation can write disk blocks for a series of index values
more efficiently than if each value were written to disk immediately.

Change buffer merging may take several hours when there are numerous
secondary indexes to update and many affected rows.  During this time,
disk I/O is increased, which can cause a significant slowdown for
disk-bound queries.  Change buffer merging may also continue to occur
after a transaction is committed.  In fact, change buffer merging may
continue to occur after a server shutdown and restart (see
forcing-innodb-recovery for more information).

In memory, the change buffer occupies part of the 'InnoDB' buffer pool.
On disk, the change buffer is part of the system tablespace, so that
index changes remain buffered across database restarts.

The type of data cached in the change buffer is governed by the
'innodb_change_buffering' configuration option.  For more information,
see innodb-performance-change_buffering.  You can also configure
the maximum change buffer size.  For more information, see
innodb-change-buffer-maximum-size.

*Monitoring the Change Buffer*

The following options are available for change buffer monitoring:

   * 'InnoDB' Standard Monitor output includes status information for
     the change buffer.  To view monitor data, issue the 'SHOW ENGINE
     INNODB STATUS' command.

          mysql> SHOW ENGINE INNODB STATUS\G

     Change buffer status information is located under the 'INSERT
     BUFFER AND ADAPTIVE HASH INDEX' heading and appears similar to the
     following:

          -------------------------------------
          INSERT BUFFER AND ADAPTIVE HASH INDEX
          -------------------------------------
          Ibuf: size 1, free list len 0, seg size 2, 0 merges
          merged operations:
           insert 0, delete mark 0, delete 0
          discarded operations:
           insert 0, delete mark 0, delete 0
          Hash table size 4425293, used cells 32, node heap has 1 buffer(s)
          13577.57 hash searches/s, 202.47 non-hash searches/s

     For more information, see innodb-standard-monitor.

   * The 'INFORMATION_SCHEMA.INNODB_METRICS'
     table provides most of the data points found
     in 'InnoDB' Standard Monitor output, plus other data points.  To
     view change buffer metrics and a description of each, issue the
     following query:

          mysql> SELECT NAME, COMMENT FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME LIKE '%ibuf%'\G

     For 'INNODB_METRICS' table usage
     information, see innodb-information-schema-metrics-table.

   * The 'INFORMATION_SCHEMA.INNODB_BUFFER_PAGE'
     table provides metadata about each page
     in the buffer pool, including change buffer index and change buffer
     bitmap pages.  Change buffer pages are identified by 'PAGE_TYPE'.
     'IBUF_INDEX' is the page type for change buffer index pages, and
     'IBUF_BITMAP' is the page type for change buffer bitmap pages.

     *Warning*:

     Querying the 'INNODB_BUFFER_PAGE'.
     table can introduce significant performance overhead.  To avoid
     impacting performance, reproduce the issue you want to investigate
     on a test instance and run your queries on the test instance.

     For example, you can query the 'INNODB_BUFFER_PAGE'
     table to determine the approximate number
     of 'IBUF_INDEX' and 'IBUF_BITMAP' pages as a percentage of total
     buffer pool pages.

          mysql> SELECT (SELECT COUNT(*) FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
                 WHERE PAGE_TYPE LIKE 'IBUF%') AS change_buffer_pages,
                 (SELECT COUNT(*) FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE) AS total_pages,
                 (SELECT ((change_buffer_pages/total_pages)*100))
                 AS change_buffer_page_percentage;
          +---------------------+-------------+-------------------------------+
          | change_buffer_pages | total_pages | change_buffer_page_percentage |
          +---------------------+-------------+-------------------------------+
          |                  25 |        8192 |                        0.3052 |
          +---------------------+-------------+-------------------------------+

     For information about other data provided by the
     'INNODB_BUFFER_PAGE' table, see
     innodb-buffer-page-table.  For related usage information, see
     innodb-information-schema-buffer-pool-tables.

   * Performance Schema provides change
     buffer mutex wait instrumentation for advanced performance
     monitoring.  To view change buffer instrumentation, issue the
     following query:

          mysql> SELECT * FROM performance_schema.setup_instruments
                 WHERE NAME LIKE '%wait/synch/mutex/innodb/ibuf%';
          +-------------------------------------------------------+---------+-------+
          | NAME                                                  | ENABLED | TIMED |
          +-------------------------------------------------------+---------+-------+
          | wait/synch/mutex/innodb/ibuf_bitmap_mutex             | YES     | YES   |
          | wait/synch/mutex/innodb/ibuf_mutex                    | YES     | YES   |
          | wait/synch/mutex/innodb/ibuf_pessimistic_insert_mutex | YES     | YES   |
          +-------------------------------------------------------+---------+-------+

     For information about monitoring 'InnoDB' mutex waits, see
     monitor-innodb-mutex-waits-performance-schema.

14.4.3 Adaptive Hash Index
--------------------------

The adaptive hash index (AHI) lets 'InnoDB' perform more like an
in-memory database on systems with appropriate combinations of workload
and ample memory for the buffer pool, without sacrificing any
transactional features or reliability.  This feature is enabled by the
'innodb_adaptive_hash_index' option, or turned off by
'--skip-innodb_adaptive_hash_index' at server startup.

Based on the observed pattern of searches, MySQL builds a hash index
using a prefix of the index key.  The prefix of the key can be any
length, and it may be that only some of the values in the B-tree appear
in the hash index.  Hash indexes are built on demand for those pages of
the index that are often accessed.

If a table fits almost entirely in main memory, a hash index can speed
up queries by enabling direct lookup of any element, turning the index
value into a sort of pointer.  'InnoDB' has a mechanism that monitors
index searches.  If 'InnoDB' notices that queries could benefit from
building a hash index, it does so automatically.

With some workloads, the speedup from hash index lookups greatly
outweighs the extra work to monitor index lookups and maintain the hash
index structure.  Sometimes, the read/write lock that guards access to
the adaptive hash index can become a source of contention under heavy
workloads, such as multiple concurrent joins.  Queries with 'LIKE'
operators and '%' wildcards also tend not to benefit from the AHI. For
workloads where the adaptive hash index is not needed, turning it off
reduces unnecessary performance overhead.  Because it is difficult to
predict in advance whether this feature is appropriate for a particular
system, consider running benchmarks with it both enabled and disabled,
using a realistic workload.  The architectural changes in MySQL 5.6 and
higher make more workloads suitable for disabling the adaptive hash
index than in earlier releases, although it is still enabled by default.

In MySQL 5.7, the adaptive hash index search system is partitioned.
Each index is bound to a specific partition, and each partition is
protected by a separate latch.  Partitioning is controlled by the
'innodb_adaptive_hash_index_parts' configuration option.  In earlier
releases, the adaptive hash index search system was protected by a
single latch which could become a point of contention under heavy
workloads.  The 'innodb_adaptive_hash_index_parts' option is set to 8 by
default.  The maximum setting is 512.

The hash index is always built based on an existing B-tree index on the
table.  'InnoDB' can build a hash index on a prefix of any length of the
key defined for the B-tree, depending on the pattern of searches that
'InnoDB' observes for the B-tree index.  A hash index can be partial,
covering only those pages of the index that are often accessed.

You can monitor the use of the adaptive hash index and the contention
for its use in the 'SEMAPHORES' section of the output of the 'SHOW ENGINE INNODB STATUS'
command.  If you see many threads
waiting on an RW-latch created in 'btr0sea.c', then it might be useful
to disable adaptive hash indexing.

For more information about the performance characteristics of hash
indexes, see index-btree-hash.

14.4.4 Redo Log Buffer
----------------------

The redo log buffer is the memory area that holds data to be written to
the redo log.  Redo log buffer size is defined by the
'innodb_log_buffer_size' configuration option.  The redo log buffer is
periodically flushed to the log file on disk.  A large redo log buffer
enables large transactions to run without the need to write redo log to
disk before the transactions commit.  Thus, if you have transactions
that update, insert, or delete many rows, making the log buffer larger
saves disk I/O.

The 'innodb_flush_log_at_trx_commit' option controls how the contents of
the redo log buffer are written to the log file.  The
'innodb_flush_log_at_timeout' option controls redo log flushing
frequency.

14.4.5 System Tablespace
------------------------

The 'InnoDB' system tablespace contains the 'InnoDB' data dictionary
(metadata for 'InnoDB'-related objects) and is the storage area for the
doublewrite buffer, the change buffer, and undo logs.  The system
tablespace also contains table and index data for any user-created
tables that are created in the system tablespace.  The system tablespace
is considered a shared tablespace since it is shared by multiple tables.

The system tablespace is represented by one or more data files.  By
default, one system data file, named 'ibdata1', is created in the MySQL
'data' directory.  The size and number of system data files is
controlled by the 'innodb_data_file_path' startup option.

For related information, see innodb-init-startup-configuration,
and innodb-resize-system-tablespace.

14.4.6 InnoDB Data Dictionary
-----------------------------

The 'InnoDB' data dictionary is comprised of internal system tables that
contain metadata used to keep track of objects such as tables, indexes,
and table columns.  The metadata is physically located in the 'InnoDB'
system tablespace.  For historical reasons, data dictionary metadata
overlaps to some degree with information stored in 'InnoDB' table
metadata files ('.frm' files).

14.4.7 Doublewrite Buffer
-------------------------

The doublewrite buffer is a storage area located in the system
tablespace where 'InnoDB' writes pages that are flushed from the
'InnoDB' buffer pool, before the pages are written to their proper
positions in the data file.  Only after flushing and writing pages to
the doublewrite buffer, does 'InnoDB' write pages to their proper
positions.  If there is an operating system, storage subsystem, or
'mysqld' process crash in the middle of a page write, 'InnoDB'
can later find a good copy of the page from the doublewrite buffer
during crash recovery.

Although data is always written twice, the doublewrite buffer does not
require twice as much I/O overhead or twice as many I/O operations.
Data is written to the doublewrite buffer itself as a large sequential
chunk, with a single 'fsync()' call to the operating system.

The doublewrite buffer is enabled by default in most cases.  To disable
the doublewrite buffer, set 'innodb_doublewrite' to 0.

If system tablespace files ('ibdata files') are located on Fusion-io
devices that support atomic writes, doublewrite buffering is
automatically disabled and Fusion-io atomic writes are used for all data
files.  Because the doublewrite buffer setting is global, doublewrite
buffering is also disabled for data files residing on non-Fusion-io
hardware.  This feature is only supported on Fusion-io hardware and is
only enabled for Fusion-io NVMFS on Linux.  To take full advantage of
this feature, an 'innodb_flush_method' setting of 'O_DIRECT' is
recommended.

14.4.8 Undo Logs
----------------

An undo log is a collection of undo log records associated with a single
transaction.  An undo log record contains information about how to undo
the latest change by a transaction to a clustered index record.  If
another transaction needs to see the original data (as part of a
consistent read operation), the unmodified data is retrieved from the
undo log records.  Undo logs exist within undo log segments, which are
contained within rollback segments.  Rollback segments reside in the
system tablespace, temporary tablespace, and undo tablespaces.  For more
information, see innodb-undo-tablespace.  For information about
multi-versioning, see innodb-multi-versioning.

'InnoDB' supports 128 rollback segments, 32 of which are reserved as
non-redo rollback segments for temporary table transactions.  Each
transaction that updates a temporary table (excluding read-only
transactions) is assigned two rollback segments, one redo-enabled
rollback segment and one non-redo rollback segment.  Read-only
transactions are only assigned non-redo rollback segments, as read-only
transactions are only permitted to modify temporary tables.

This leaves 96 available rollback segments, each of which supports up to
1023 concurrent data-modifying transactions, for a total limit of
approximately 96K concurrent data-modifying transactions.  The 96K limit
assumes that transactions do not modify temporary tables.  If all
data-modifying transactions also modify temporary tables, the total
limit is approximately 32K concurrent data modifying transactions.  For
more information about rollback segments that are reserved for temporary
table transactions, see innodb-temporary-table-undo-logs.

The 'innodb_rollback_segments' option defines the number of rollback
segments used by 'InnoDB'.

14.4.9 File-Per-Table Tablespaces
---------------------------------

A file-per-table tablespace is a single-table tablespace that is created
in its own data file rather than in the system tablespace.  Tables are
created in file-per-table tablespaces when the 'innodb_file_per_table'
option is enabled.  Otherwise, 'InnoDB' tables are created in the system
tablespace.  Each file-per-table tablespace is represented by a single
'.ibd' data file, which is created in the database directory by default.

File per-table tablespaces support 'DYNAMIC' and 'COMPRESSED' row
formats which support features such as off-page storage for variable
length data and table compression.  For information about these
features, and about other advantages of file-per-table tablespaces, see
innodb-multiple-tablespaces.

14.4.10 General Tablespaces
---------------------------

A shared 'InnoDB' tablespace created using 'CREATE TABLESPACE'
syntax.  General tablespaces can be created outside
of the MySQL data directory, are capable of holding multiple tables, and
support tables of all row formats.

Tables are added to a general tablespace using 'CREATE TABLE TBL_NAME ... TABLESPACE [=] TABLESPACE_NAME'
or
'ALTER TABLE TBL_NAME TABLESPACE [=] TABLESPACE_NAME'.
syntax.

For more information, see general-tablespaces.

14.4.11 Undo Tablespace
-----------------------

An undo tablespace comprises one or more files that contain undo logs.
The number of undo tablespaces used by 'InnoDB' is defined by the
'innodb_undo_tablespaces' configuration option.  For more information,
see innodb-undo-tablespace.

*Note*:

'innodb_undo_tablespaces' is deprecated and will be removed in a future
release.

14.4.12 Temporary Tablespace
----------------------------

Non-compressed, user-created temporary tables and on-disk internal
temporary tables are created in a shared temporary tablespace.  The
'innodb_temp_data_file_path' configuration option defines the relative
path, name, size, and attributes for temporary tablespace data files.
If no value is specified for 'innodb_temp_data_file_path', the default
behavior is to create an auto-extending data file named 'ibtmp1' in the
'innodb_data_home_dir' directory that is slightly larger than 12MB.

Compressed temporary tables, which are temporary tables created using
the 'ROW_FORMAT=COMPRESSED' attribute, are created in file-per-table
tablespaces in the temporary file directory.

The temporary tablespace is removed on normal shutdown or on an aborted
initialization, and is recreated each time the server is started.  The
temporary tablespace receives a dynamically generated space ID when it
is created.  Startup is refused if the temporary tablespace cannot be
created.  The temporary tablespace is not removed if the server halts
unexpectedly.  In this case, a database administrator can remove the
temporary tablespace manually or restart the server, which removes and
recreates the temporary tablespace automatically.

The temporary tablespace cannot reside on a raw device.

'INFORMATION_SCHEMA.FILES' provides metadata about
the 'InnoDB' temporary tablespace.  Issue a query similar to this one to
view temporary tablespace metadata:

     mysql> SELECT * FROM INFORMATION_SCHEMA.FILES WHERE TABLESPACE_NAME='innodb_temporary'\G

'INFORMATION_SCHEMA.INNODB_TEMP_TABLE_INFO'
provides metadata about user-created
temporary tables that are currently active within an 'InnoDB' instance.
For more information, see
innodb-information-schema-temp-table-info.

*Managing Temporary Tablespace Data File Size*

By default, the temporary tablespace data file is autoextending and
increases in size as necessary to accommodate on-disk temporary tables.
For example, if an operation creates a temporary table that is 20MB in
size, the temporary tablespace data file, which is 12MB in size by
default when created, extends in size to accommodate it.  When temporary
tables are dropped, freed space can be reused for new temporary tables,
but the data file remains at the extended size.

An autoextending temporary tablespace data file can become large in
environments that use large temporary tables or that use temporary
tables extensively.  A large data file can also result from long running
queries that use temporary tables.

To determine if a temporary tablespace data file is autoextending, check
the 'innodb_temp_data_file_path' setting:

     mysql> SELECT @@innodb_temp_data_file_path;
     +------------------------------+
     | @@innodb_temp_data_file_path |
     +------------------------------+
     | ibtmp1:12M:autoextend        |
     +------------------------------+

To check the size of temporary tablespace data files, query the
'INFORMATION_SCHEMA.FILES' table using a query similar to
this:

     mysql> SELECT FILE_NAME, TABLESPACE_NAME, ENGINE, INITIAL_SIZE, TOTAL_EXTENTS*EXTENT_SIZE
            AS TotalSizeBytes, DATA_FREE, MAXIMUM_SIZE FROM INFORMATION_SCHEMA.FILES
            WHERE TABLESPACE_NAME = 'innodb_temporary'\G
     *************************** 1. row ***************************
           FILE_NAME: ./ibtmp1
     TABLESPACE_NAME: innodb_temporary
              ENGINE: InnoDB
        INITIAL_SIZE: 12582912
      TotalSizeBytes: 12582912
           DATA_FREE: 6291456
        MAXIMUM_SIZE: NULL

The 'TotalSizeBytes' value reports the current size of the temporary
tablespace data file.  For information about other field values, see
files-table.

Alternatively, you can check the temporary tablespace data file size on
your operating system.  By default, the temporary tablespace data file
is located in the directory defined by the 'innodb_temp_data_file_path'
configuration option.  If a value was not specified for this option
explicitly, a temporary tablespace data file named 'ibtmp1' is created
in 'innodb_data_home_dir', which defaults to the MySQL data directory if
unspecified.

To reclaim disk space occupied by a temporary tablespace data file, you
can restart the MySQL server.  Restarting the server removes and
recreates the temporary tablespace data file according to the attributes
defined by 'innodb_temp_data_file_path'.

To prevent the temporary data file from becoming too large, you can
configure the 'innodb_temp_data_file_path' option to specify a maximum
file size.  For example:

     [mysqld]
     innodb_temp_data_file_path=ibtmp1:12M:autoextend:max:500M

When the data file reaches the maximum size, queries fail with an error
indicating that the table is full.  Configuring
'innodb_temp_data_file_path' requires restarting the server.

Alternatively, you can configure the 'default_tmp_storage_engine' and
'internal_tmp_disk_storage_engine' options, which define the storage
engine to use for user-created and on-disk internal temporary tables,
respectively.  Both options are set to 'InnoDB' by default.  The
'MyISAM' storage engine uses an individual file for each temporary
table, which is removed when the temporary table is dropped.

*Temporary Table Undo Logs*

Temporary table undo logs reside in the temporary tablespace and are
used for temporary tables and related objects.  Temporary table undo
logs are not redo-logged, as they are not required for crash recovery.
They are only used for rollback while the server is running.  This
special type of undo log benefits performance by avoiding redo logging
I/O. 32 rollback segments are reserved for temporary table undo logs for
transactions that modify temporary tables and related objects.

14.4.13 Redo Log
----------------

The redo log is a disk-based data structure used during crash recovery
to correct data written by incomplete transactions.  During normal
operations, the redo log encodes requests to change 'InnoDB' table data
that result from SQL statements or low-level API calls.  Modifications
that did not finish updating the data files before an unexpected
shutdown are replayed automatically during initialization, and before
the connections are accepted.  For information about the role of the
redo log in crash recovery, see innodb-recovery.

By default, the redo log is physically represented on disk as a set of
files, named 'ib_logfile0' and 'ib_logfile1'.  MySQL writes to the redo
log files in a circular fashion.  Data in the redo log is encoded in
terms of records affected; this data is collectively referred to as
redo.  The passage of data through the redo log is represented by an
ever-increasing LSN value.

For related information, see:

   * innodb-init-startup-configuration

   * optimizing-innodb-logging

   * innodb-data-log-reconfiguration

   * innodb-crash-recovery

14.4.13.1 Group Commit for Redo Log Flushing
............................................

'InnoDB', like any other ACID-compliant database engine, flushes the
redo log of a transaction before it is committed.  'InnoDB' uses group
commit functionality to group multiple such flush requests together to
avoid one flush for each commit.  With group commit, 'InnoDB' issues a
single write to the log file to perform the commit action for multiple
user transactions that commit at about the same time, significantly
improving throughput.

For more information about performance of 'COMMIT' and other
transactional operations, see
optimizing-innodb-transaction-management.

14.5 InnoDB Locking and Transaction Model
=========================================

To implement a large-scale, busy, or highly reliable database
application, to port substantial code from a different database system,
or to tune MySQL performance, it is important to understand 'InnoDB'
locking and the 'InnoDB' transaction model.

This section discusses several topics related to 'InnoDB' locking and
the 'InnoDB' transaction model with which you should be familiar.

   * innodb-locking describes lock types used by 'InnoDB'.

   * innodb-transaction-model describes transaction isolation
     levels and the locking strategies used by each.  It also discusses
     the use of 'autocommit', consistent non-locking reads, and locking
     reads.

   * innodb-locks-set discusses specific types of locks set in
     'InnoDB' for various statements.

   * innodb-next-key-locking describes how 'InnoDB' uses
     next-key locking to avoid phantom rows.

   * innodb-deadlocks provides a deadlock example, discusses
     deadlock detection and rollback, and provides tips for minimizing
     and handling deadlocks in 'InnoDB'.

14.5.1 InnoDB Locking
---------------------

This section describes lock types used by 'InnoDB'.

   * innodb-shared-exclusive-locks

   * innodb-intention-locks

   * innodb-record-locks

   * innodb-gap-locks

   * innodb-next-key-locks

   * innodb-insert-intention-locks

   * innodb-auto-inc-locks

   * innodb-predicate-locks

*Shared and Exclusive Locks*

'InnoDB' implements standard row-level locking where there are two types
of locks, shared (S) locks and exclusive (X) locks.

   * A shared (S) lock permits the transaction that holds the lock to
     read a row.

   * An exclusive (X) lock permits the transaction that holds the lock
     to update or delete a row.

If transaction 'T1' holds a shared (S) lock on row 'r', then requests
from some distinct transaction 'T2' for a lock on row 'r' are handled as
follows:

   * A request by 'T2' for an S lock can be granted immediately.  As a
     result, both 'T1' and 'T2' hold an S lock on 'r'.

   * A request by 'T2' for an X lock cannot be granted immediately.

If a transaction 'T1' holds an exclusive (X) lock on row 'r', a request
from some distinct transaction 'T2' for a lock of either type on 'r'
cannot be granted immediately.  Instead, transaction 'T2' has to wait
for transaction 'T1' to release its lock on row 'r'.

*Intention Locks*

'InnoDB' supports _multiple granularity locking_ which permits
coexistence of row locks and table locks.  For example, a statement such
as 'LOCK TABLES ... WRITE' takes an exclusive lock
(an 'X' lock) on the specified table.  To make locking at multiple
granularity levels practical, 'InnoDB' uses intention locks.  Intention
locks are table-level locks that indicate which type of lock (shared or
exclusive) a transaction requires later for a row in a table.  There are
two types of intention locks:

   * An intention shared lock ('IS') indicates that a transaction
     intends to set a _shared_ lock on individual rows in a table.

   * An intention exclusive lock ('IX') indicates that that a
     transaction intends to set an exclusive lock on individual rows in
     a table.

For example, see 'SELECT ... LOCK IN SHARE MODE' sets an 'IS'
lock, and 'SELECT ... FOR UPDATE' sets an 'IX' lock.

The intention locking protocol is as follows:

   * Before a transaction can acquire a shared lock on a row in a table,
     it must first acquire an 'IS' lock or stronger on the table.

   * Before a transaction can acquire an exclusive lock on a row in a
     table, it must first acquire an 'IX' lock on the table.

Table-level lock type compatibility is summarized in the following
matrix.

               X              IX             S              IS

X              Conflict       Conflict       Conflict       Conflict

IX             Conflict       Compatible     Conflict       Compatible

S              Conflict       Conflict       Compatible     Compatible

IS             Conflict       Compatible     Compatible     Compatible

A lock is granted to a requesting transaction if it is compatible with
existing locks, but not if it conflicts with existing locks.  A
transaction waits until the conflicting existing lock is released.  If a
lock request conflicts with an existing lock and cannot be granted
because it would cause deadlock, an error occurs.

Intention locks do not block anything except full table requests (for
example, see 'LOCK TABLES ... WRITE').  The main purpose
of intention locks is to show that someone is locking a row, or going to
lock a row in the table.

Transaction data for an intention lock appears similar to the following
in 'SHOW ENGINE INNODB STATUS' and InnoDB monitor
output:

     TABLE LOCK table `test`.`t` trx id 10080 lock mode IX

*Record Locks*

A record lock is a lock on an index record.  For example, 'SELECT c1
FROM t WHERE c1 = 10 FOR UPDATE;' prevents any other transaction from
inserting, updating, or deleting rows where the value of 't.c1' is '10'.

Record locks always lock index records, even if a table is defined with
no indexes.  For such cases, 'InnoDB' creates a hidden clustered index
and uses this index for record locking.  See innodb-index-types.

Transaction data for a record lock appears similar to the following in
'SHOW ENGINE INNODB STATUS' and InnoDB monitor
output:

     RECORD LOCKS space id 58 page no 3 n bits 72 index `PRIMARY` of table `test`.`t`
     trx id 10078 lock_mode X locks rec but not gap
     Record lock, heap no 2 PHYSICAL RECORD: n_fields 3; compact format; info bits 0
      0: len 4; hex 8000000a; asc     ;;
      1: len 6; hex 00000000274f; asc     'O;;
      2: len 7; hex b60000019d0110; asc        ;;

*Gap Locks*

A gap lock is a lock on a gap between index records, or a lock on the
gap before the first or after the last index record.  For example,
'SELECT c1 FROM t WHERE c1 BETWEEN 10 and 20 FOR UPDATE;' prevents other
transactions from inserting a value of '15' into column 't.c1', whether
or not there was already any such value in the column, because the gaps
between all existing values in the range are locked.

A gap might span a single index value, multiple index values, or even be
empty.

Gap locks are part of the tradeoff between performance and concurrency,
and are used in some transaction isolation levels and not others.

Gap locking is not needed for statements that lock rows using a unique
index to search for a unique row.  (This does not include the case that
the search condition includes only some columns of a multiple-column
unique index; in that case, gap locking does occur.)  For example, if
the 'id' column has a unique index, the following statement uses only an
index-record lock for the row having 'id' value 100 and it does not
matter whether other sessions insert rows in the preceding gap:

     SELECT * FROM child WHERE id = 100;

If 'id' is not indexed or has a nonunique index, the statement does lock
the preceding gap.

It is also worth noting here that conflicting locks can be held on a gap
by different transactions.  For example, transaction A can hold a shared
gap lock (gap S-lock) on a gap while transaction B holds an exclusive
gap lock (gap X-lock) on the same gap.  The reason conflicting gap locks
are allowed is that if a record is purged from an index, the gap locks
held on the record by different transactions must be merged.

Gap locks in 'InnoDB' are 'purely inhibitive', which means they only
stop other transactions from inserting to the gap.  They do not prevent
different transactions from taking gap locks on the same gap.  Thus, a
gap X-lock has the same effect as a gap S-lock.

Gap locking can be disabled explicitly.  This occurs if you change the
transaction isolation level to 'READ COMMITTED' or enable the
'innodb_locks_unsafe_for_binlog' system variable (which is now
deprecated).  Under these circumstances, gap locking is disabled for
searches and index scans and is used only for foreign-key constraint
checking and duplicate-key checking.

There are also other effects of using the 'READ COMMITTED' isolation
level or enabling 'innodb_locks_unsafe_for_binlog'.  Record locks for
nonmatching rows are released after MySQL has evaluated the 'WHERE'
condition.  For 'UPDATE' statements, 'InnoDB' does a 'semi-consistent'
read, such that it returns the latest committed version to MySQL so that
MySQL can determine whether the row matches the 'WHERE' condition of the
'UPDATE'.

*Next-Key Locks*

A next-key lock is a combination of a record lock on the index record
and a gap lock on the gap before the index record.

'InnoDB' performs row-level locking in such a way that when it searches
or scans a table index, it sets shared or exclusive locks on the index
records it encounters.  Thus, the row-level locks are actually
index-record locks.  A next-key lock on an index record also affects the
'gap' before that index record.  That is, a next-key lock is an
index-record lock plus a gap lock on the gap preceding the index record.
If one session has a shared or exclusive lock on record 'R' in an index,
another session cannot insert a new index record in the gap immediately
before 'R' in the index order.

Suppose that an index contains the values 10, 11, 13, and 20.  The
possible next-key locks for this index cover the following intervals,
where a round bracket denotes exclusion of the interval endpoint and a
square bracket denotes inclusion of the endpoint:

     (negative infinity, 10]
     (10, 11]
     (11, 13]
     (13, 20]
     (20, positive infinity)

For the last interval, the next-key lock locks the gap above the largest
value in the index and the 'supremum' pseudo-record having a value
higher than any value actually in the index.  The supremum is not a real
index record, so, in effect, this next-key lock locks only the gap
following the largest index value.

By default, 'InnoDB' operates in 'REPEATABLE READ' transaction isolation
level.  In this case, 'InnoDB' uses next-key locks for searches and
index scans, which prevents phantom rows (see
innodb-next-key-locking).

Transaction data for a next-key lock appears similar to the following in
'SHOW ENGINE INNODB STATUS' and InnoDB monitor
output:

     RECORD LOCKS space id 58 page no 3 n bits 72 index `PRIMARY` of table `test`.`t`
     trx id 10080 lock_mode X
     Record lock, heap no 1 PHYSICAL RECORD: n_fields 1; compact format; info bits 0
      0: len 8; hex 73757072656d756d; asc supremum;;

     Record lock, heap no 2 PHYSICAL RECORD: n_fields 3; compact format; info bits 0
      0: len 4; hex 8000000a; asc     ;;
      1: len 6; hex 00000000274f; asc     'O;;
      2: len 7; hex b60000019d0110; asc        ;;

*Insert Intention Locks*

An insert intention lock is a type of gap lock set by 'INSERT'
operations prior to row insertion.  This lock signals the intent
to insert in such a way that multiple transactions inserting into the
same index gap need not wait for each other if they are not inserting at
the same position within the gap.  Suppose that there are index records
with values of 4 and 7.  Separate transactions that attempt to insert
values of 5 and 6, respectively, each lock the gap between 4 and 7 with
insert intention locks prior to obtaining the exclusive lock on the
inserted row, but do not block each other because the rows are
nonconflicting.

The following example demonstrates a transaction taking an insert
intention lock prior to obtaining an exclusive lock on the inserted
record.  The example involves two clients, A and B.

Client A creates a table containing two index records (90 and 102) and
then starts a transaction that places an exclusive lock on index records
with an ID greater than 100.  The exclusive lock includes a gap lock
before record 102:

     mysql> CREATE TABLE child (id int(11) NOT NULL, PRIMARY KEY(id)) ENGINE=InnoDB;
     mysql> INSERT INTO child (id) values (90),(102);

     mysql> START TRANSACTION;
     mysql> SELECT * FROM child WHERE id > 100 FOR UPDATE;
     +-----+
     | id  |
     +-----+
     | 102 |
     +-----+

Client B begins a transaction to insert a record into the gap.  The
transaction takes an insert intention lock while it waits to obtain an
exclusive lock.

     mysql> START TRANSACTION;
     mysql> INSERT INTO child (id) VALUES (101);

Transaction data for an insert intention lock appears similar to the
following in 'SHOW ENGINE INNODB STATUS' and
InnoDB monitor output:

     RECORD LOCKS space id 31 page no 3 n bits 72 index `PRIMARY` of table `test`.`child`
     trx id 8731 lock_mode X locks gap before rec *insert intention* waiting
     Record lock, heap no 3 PHYSICAL RECORD: n_fields 3; compact format; info bits 0
      0: len 4; hex 80000066; asc    f;;
      1: len 6; hex 000000002215; asc     " ;;
      2: len 7; hex 9000000172011c; asc     r  ;;...

*AUTO-INC Locks*

An 'AUTO-INC' lock is a special table-level lock taken by transactions
inserting into tables with 'AUTO_INCREMENT' columns.  In the simplest
case, if one transaction is inserting values into the table, any other
transactions must wait to do their own inserts into that table, so that
rows inserted by the first transaction receive consecutive primary key
values.

The 'innodb_autoinc_lock_mode' configuration option controls the
algorithm used for auto-increment locking.  It allows you to choose how
to trade off between predictable sequences of auto-increment values and
maximum concurrency for insert operations.

For more information, see innodb-auto-increment-handling.

*Predicate Locks for Spatial Indexes*

'InnoDB' supports 'SPATIAL' indexing of columns containing spatial
columns (see optimizing-spatial-analysis).

To handle locking for operations involving 'SPATIAL' indexes, next-key
locking does not work well to support 'REPEATABLE READ' or
'SERIALIZABLE' transaction isolation levels.  There is no absolute
ordering concept in multidimensional data, so it is not clear which is
the 'next' key.

To enable support of isolation levels for tables with 'SPATIAL' indexes,
'InnoDB' uses predicate locks.  A 'SPATIAL' index contains minimum
bounding rectangle (MBR) values, so 'InnoDB' enforces consistent read on
the index by setting a predicate lock on the MBR value used for a query.
Other transactions cannot insert or modify a row that would match the
query condition.

14.5.2 InnoDB Transaction Model
-------------------------------

In the 'InnoDB' transaction model, the goal is to combine the best
properties of a multi-versioning database with traditional two-phase
locking.  'InnoDB' performs locking at the row level and runs queries as
nonlocking consistent reads by default, in the style of Oracle.  The
lock information in 'InnoDB' is stored space-efficiently so that lock
escalation is not needed.  Typically, several users are permitted to
lock every row in 'InnoDB' tables, or any random subset of the rows,
without causing 'InnoDB' memory exhaustion.

14.5.2.1 Transaction Isolation Levels
.....................................

Transaction isolation is one of the foundations of database processing.
Isolation is the I in the acronym ACID; the isolation level is the
setting that fine-tunes the balance between performance and reliability,
consistency, and reproducibility of results when multiple transactions
are making changes and performing queries at the same time.

'InnoDB' offers all four transaction isolation levels described by the
SQL:1992 standard: 'READ UNCOMMITTED', 'READ COMMITTED', 'REPEATABLE
READ', and 'SERIALIZABLE'.  The default isolation level for 'InnoDB' is
'REPEATABLE READ'.

A user can change the isolation level for a single session or for all
subsequent connections with the 'SET TRANSACTION'
statement.  To set the server's default isolation level
for all connections, use the '--transaction-isolation' option on the
command line or in an option file.  For detailed information about
isolation levels and level-setting syntax, see set-transaction.

'InnoDB' supports each of the transaction isolation levels described
here using different locking strategies.  You can enforce a high degree
of consistency with the default 'REPEATABLE READ' level, for operations
on crucial data where ACID compliance is important.  Or you can relax
the consistency rules with 'READ COMMITTED' or even 'READ UNCOMMITTED',
in situations such as bulk reporting where precise consistency and
repeatable results are less important than minimizing the amount of
overhead for locking.  'SERIALIZABLE' enforces even stricter rules than
'REPEATABLE READ', and is used mainly in specialized situations, such as
with XA transactions and for troubleshooting issues with concurrency and
deadlocks.

The following list describes how MySQL supports the different
transaction levels.  The list goes from the most commonly used level to
the least used.

   *
     'REPEATABLE READ'

     This is the default isolation level for 'InnoDB'.  Consistent reads
     within the same transaction read the snapshot established by the
     first read.  This means that if you issue several plain
     (nonlocking) 'SELECT' statements within the same
     transaction, these 'SELECT' statements are
     consistent also with respect to each other.  See
     innodb-consistent-read.

     For locking reads (see 'SELECT' with 'FOR UPDATE' or
     'LOCK IN SHARE MODE'), see 'UPDATE', and 'DELETE'
     statements, locking depends on whether the statement uses a
     unique index with a unique search condition, or a range-type search
     condition.

        * For a unique index with a unique search condition, 'InnoDB'
          locks only the index record found, not the gap before it.

        * For other search conditions, 'InnoDB' locks the index range
          scanned, using gap locks or next-key locks to block insertions
          by other sessions into the gaps covered by the range.  For
          information about gap locks and next-key locks, see
          innodb-locking.

   *
     'READ COMMITTED'

     Each consistent read, even within the same transaction, sets and
     reads its own fresh snapshot.  For information about consistent
     reads, see innodb-consistent-read.

     For locking reads (see 'SELECT' with 'FOR UPDATE' or
     'LOCK IN SHARE MODE'), see 'UPDATE' statements, and
     'DELETE' statements, 'InnoDB' locks only index
     records, not the gaps before them, and thus permits the free
     insertion of new records next to locked records.  Gap locking is
     only used for foreign-key constraint checking and duplicate-key
     checking.

     Because gap locking is disabled, phantom problems may occur, as
     other sessions can insert new rows into the gaps.  For information
     about phantoms, see innodb-next-key-locking.

     If you use 'READ COMMITTED', you _must_ use row-based binary
     logging.

     Using 'READ COMMITTED' has additional effects:

        * For 'UPDATE' or 'DELETE'.
          statements, 'InnoDB' holds locks only for rows that it updates
          or deletes.  Record locks for nonmatching rows are released
          after MySQL has evaluated the 'WHERE' condition.  This greatly
          reduces the probability of deadlocks, but they can still
          happen.

        * For 'UPDATE' statements, if a row is already
          locked, 'InnoDB' performs a 'semi-consistent' read, returning
          the latest committed version to MySQL so that MySQL can
          determine whether the row matches the 'WHERE' condition of the
          'UPDATE'.  If the row matches (must be updated),
          MySQL reads the row again and this time 'InnoDB' either locks
          it or waits for a lock on it.

     Consider the following example, beginning with this table:

          CREATE TABLE t (a INT NOT NULL, b INT) ENGINE = InnoDB;
          INSERT INTO t VALUES (1,2),(2,3),(3,2),(4,3),(5,2);
          COMMIT;

     In this case, the table has no indexes, so searches and index scans
     use the hidden clustered index for record locking (see
     innodb-index-types) rather than indexed columns.

     Suppose that one session performs an 'UPDATE' using
     these statements:

          # Session A
          START TRANSACTION;
          UPDATE t SET b = 5 WHERE b = 3;

     Suppose also that a second session performs an 'UPDATE'
     by executing this statement following those of the first
     session:

          # Session B
          UPDATE t SET b = 4 WHERE b = 2;

     As 'InnoDB' executes each
     'UPDATE', it first acquires an exclusive lock for each row
     that it reads, and then determines whether to modify it.  If
     'InnoDB' does not modify the row, it
     releases the lock.  Otherwise, see 'InnoDB'
     retains the lock until the end of the
     transaction.  This affects transaction processing as follows.

     When using the default 'REPEATABLE READ' isolation level, the first
     'UPDATE' acquires an x-lock on each row that it
     reads and does not release any of them:

          x-lock(1,2); retain x-lock
          x-lock(2,3); update(2,3) to (2,5); retain x-lock
          x-lock(3,2); retain x-lock
          x-lock(4,3); update(4,3) to (4,5); retain x-lock
          x-lock(5,2); retain x-lock

     The second 'UPDATE' blocks as soon as it tries to
     acquire any locks (because first update has retained locks on all
     rows), and does not proceed until the first 'UPDATE'.
     commits or rolls back:

          x-lock(1,2); block and wait for first UPDATE to commit or roll back

     If 'READ COMMITTED' is used instead, the first 'UPDATE'
     acquires an x-lock on each row that it reads and releases
     those for rows that it does not modify:

          x-lock(1,2); unlock(1,2)
          x-lock(2,3); update(2,3) to (2,5); retain x-lock
          x-lock(3,2); unlock(3,2)
          x-lock(4,3); update(4,3) to (4,5); retain x-lock
          x-lock(5,2); unlock(5,2)

     For the second 'UPDATE', 'InnoDB' does a 'semi-consistent' read,
     returning the latest committed version of each row that it reads to
     MySQL so that MySQL can determine whether the row matches the
     'WHERE' condition of the 'UPDATE'.:

          x-lock(1,2); update(1,2) to (1,4); retain x-lock
          x-lock(2,3); unlock(2,3)
          x-lock(3,2); update(3,2) to (3,4); retain x-lock
          x-lock(4,3); unlock(4,3)
          x-lock(5,2); update(5,2) to (5,4); retain x-lock

     However, if the 'WHERE' condition includes an indexed column, and
     'InnoDB' uses the index, only the indexed column is considered when
     taking and retaining record locks.  In the following example, the
     first 'UPDATE' takes and retains an x-lock on each
     row where b = 2.  The second 'UPDATE' blocks when it
     tries to acquire x-locks on the same records, as it also uses the
     index defined on column b.

          CREATE TABLE t (a INT NOT NULL, b INT, c INT, INDEX (b)) ENGINE = InnoDB;
          INSERT INTO t VALUES (1,2,3),(2,2,4);
          COMMIT;

          # Session A
          START TRANSACTION;
          UPDATE t SET b = 3 WHERE b = 2 AND c = 3;

          # Session B
          UPDATE t SET b = 4 WHERE b = 2 AND c = 4;

     The effects of using the 'READ COMMITTED' isolation level are the
     same as enabling the deprecated 'innodb_locks_unsafe_for_binlog'
     configuration option, with these exceptions:

        * Enabling 'innodb_locks_unsafe_for_binlog' is a global setting
          and affects all sessions, whereas the isolation level can be
          set globally for all sessions, or individually per session.

        * 'innodb_locks_unsafe_for_binlog' can be set only at server
          startup, whereas the isolation level can be set at startup or
          changed at runtime.

     'READ COMMITTED' therefore offers finer and more flexible control
     than 'innodb_locks_unsafe_for_binlog'.

   *
     'READ UNCOMMITTED'

     'SELECT' statements are performed in a nonlocking
     fashion, but a possible earlier version of a row might be used.
     Thus, using this isolation level, such reads are not consistent.
     This is also called a dirty read.  Otherwise, this isolation level
     works like 'READ COMMITTED'.

   *
     'SERIALIZABLE'

     This level is like 'REPEATABLE READ', but 'InnoDB' implicitly
     converts all plain 'SELECT' statements to
     'SELECT ... LOCK IN SHARE MODE' if 'autocommit' is
     disabled.  If 'autocommit' is enabled, the 'SELECT'.
     is its own transaction.  It therefore is known to be read only and
     can be serialized if performed as a consistent (nonlocking) read
     and need not block for other transactions.  (To force a plain
     'SELECT' to block if other transactions have modified the
     selected rows, disable 'autocommit'.)

14.5.2.2 autocommit, Commit, and Rollback
.........................................

In 'InnoDB', all user activity occurs inside a transaction.  If
'autocommit' mode is enabled, each SQL statement forms a single
transaction on its own.  By default, MySQL starts the session for each
new connection with 'autocommit' enabled, so MySQL does a commit after
each SQL statement if that statement did not return an error.  If a
statement returns an error, the commit or rollback behavior depends on
the error.  See innodb-error-handling.

A session that has 'autocommit' enabled can perform a multiple-statement
transaction by starting it with an explicit 'START TRANSACTION'
or 'BEGIN' statement and ending it with a
'COMMIT' or 'ROLLBACK' statement.  See
commit.

If 'autocommit' mode is disabled within a session with 'SET autocommit =
0', the session always has a transaction open.  A 'COMMIT'
or 'ROLLBACK' statement ends the current
transaction and a new one starts.

If a session that has 'autocommit' disabled ends without explicitly
committing the final transaction, MySQL rolls back that transaction.

Some statements implicitly end a transaction, as if you had done a
'COMMIT' before executing the statement.  For details, see
implicit-commit.

A 'COMMIT' means that the changes made in the current
transaction are made permanent and become visible to other sessions.  A
'ROLLBACK' statement, on the other hand, cancels all
modifications made by the current transaction.  Both 'COMMIT'
and 'ROLLBACK' release all 'InnoDB' locks that
were set during the current transaction.

*Grouping DML Operations with Transactions*

By default, connection to the MySQL server begins with autocommit mode
enabled, which automatically commits every SQL statement as you execute
it.  This mode of operation might be unfamiliar if you have experience
with other database systems, where it is standard practice to issue a
sequence of DML statements and commit them or roll them back all
together.

To use multiple-statement transactions, switch autocommit off with the
SQL statement 'SET autocommit = 0' and end each transaction with
'COMMIT' or 'ROLLBACK' as appropriate.  To leave
autocommit on, begin each transaction with 'START TRANSACTION'
and end it with 'COMMIT' or 'ROLLBACK'.
The following example shows two transactions.  The first is
committed; the second is rolled back.

     shell> mysql test

     mysql> CREATE TABLE customer (a INT, b CHAR (20), INDEX (a));
     Query OK, 0 rows affected (0.00 sec)
     mysql> -- Do a transaction with autocommit turned on.
     mysql> START TRANSACTION;
     Query OK, 0 rows affected (0.00 sec)
     mysql> INSERT INTO customer VALUES (10, 'Heikki');
     Query OK, 1 row affected (0.00 sec)
     mysql> COMMIT;
     Query OK, 0 rows affected (0.00 sec)
     mysql> -- Do another transaction with autocommit turned off.
     mysql> SET autocommit=0;
     Query OK, 0 rows affected (0.00 sec)
     mysql> INSERT INTO customer VALUES (15, 'John');
     Query OK, 1 row affected (0.00 sec)
     mysql> INSERT INTO customer VALUES (20, 'Paul');
     Query OK, 1 row affected (0.00 sec)
     mysql> DELETE FROM customer WHERE b = 'Heikki';
     Query OK, 1 row affected (0.00 sec)
     mysql> -- Now we undo those last 2 inserts and the delete.
     mysql> ROLLBACK;
     Query OK, 0 rows affected (0.00 sec)
     mysql> SELECT * FROM customer;
     +------+--------+
     | a    | b      |
     +------+--------+
     |   10 | Heikki |
     +------+--------+
     1 row in set (0.00 sec)
     mysql>

*Transactions in Client-Side Languages*

In APIs such as PHP, Perl DBI, JDBC, ODBC, or the standard C call
interface of MySQL, you can send transaction control statements such as
'COMMIT' to the MySQL server as strings just like any
other SQL statements such as 'SELECT' or 'INSERT'.
Some APIs also offer separate special transaction commit and
rollback functions or methods.

14.5.2.3 Consistent Nonlocking Reads
....................................

A consistent read means that 'InnoDB' uses multi-versioning to present
to a query a snapshot of the database at a point in time.  The query
sees the changes made by transactions that committed before that point
of time, and no changes made by later or uncommitted transactions.  The
exception to this rule is that the query sees the changes made by
earlier statements within the same transaction.  This exception causes
the following anomaly: If you update some rows in a table, a
'SELECT' sees the latest version of the updated rows, but it
might also see older versions of any rows.  If other sessions
simultaneously update the same table, the anomaly means that you might
see the table in a state that never existed in the database.

If the transaction isolation level is 'REPEATABLE READ' (the default
level), all consistent reads within the same transaction read the
snapshot established by the first such read in that transaction.  You
can get a fresher snapshot for your queries by committing the current
transaction and after that issuing new queries.

With 'READ COMMITTED' isolation level, each consistent read within a
transaction sets and reads its own fresh snapshot.

Consistent read is the default mode in which 'InnoDB' processes
'SELECT' statements in 'READ COMMITTED' and 'REPEATABLE READ'
isolation levels.  A consistent read does not set any locks on the
tables it accesses, and therefore other sessions are free to modify
those tables at the same time a consistent read is being performed on
the table.

Suppose that you are running in the default 'REPEATABLE READ' isolation
level.  When you issue a consistent read (that is, an ordinary
'SELECT' statement), 'InnoDB' gives your transaction a
timepoint according to which your query sees the database.  If another
transaction deletes a row and commits after your timepoint was assigned,
you do not see the row as having been deleted.  Inserts and updates are
treated similarly.

*Note*:

The snapshot of the database state applies to 'SELECT'.
statements within a transaction, not necessarily to DML statements.  If
you insert or modify some rows and then commit that transaction, a
'DELETE' or 'UPDATE' statement issued from
another concurrent 'REPEATABLE READ' transaction could affect those
just-committed rows, even though the session could not query them.  If a
transaction does update or delete rows committed by a different
transaction, those changes do become visible to the current transaction.
For example, you might encounter a situation like the following:

     SELECT COUNT(c1) FROM t1 WHERE c1 = 'xyz';
     -- Returns 0: no rows match.
     DELETE FROM t1 WHERE c1 = 'xyz';
     -- Deletes several rows recently committed by other transaction.

     SELECT COUNT(c2) FROM t1 WHERE c2 = 'abc';
     -- Returns 0: no rows match.
     UPDATE t1 SET c2 = 'cba' WHERE c2 = 'abc';
     -- Affects 10 rows: another txn just committed 10 rows with 'abc' values.
     SELECT COUNT(c2) FROM t1 WHERE c2 = 'cba';
     -- Returns 10: this txn can now see the rows it just updated.

You can advance your timepoint by committing your transaction and then
doing another 'SELECT' or 'START TRANSACTION WITH CONSISTENT SNAPSHOT'.

This is called _multi-versioned concurrency control_.

In the following example, session A sees the row inserted by B only when
B has committed the insert and A has committed as well, so that the
timepoint is advanced past the commit of B.

                  Session A              Session B

                SET autocommit=0;      SET autocommit=0;
     time
     |          SELECT * FROM t;
     |          empty set
     |                                 INSERT INTO t VALUES (1, 2);
     |
     v          SELECT * FROM t;
                empty set
                                       COMMIT;

                SELECT * FROM t;
                empty set

                COMMIT;

                SELECT * FROM t;
                ---------------------
                |    1    |    2    |
                ---------------------

If you want to see the 'freshest' state of the database, use either the
'READ COMMITTED' isolation level or a locking read:

     SELECT * FROM t FOR SHARE;

With 'READ COMMITTED' isolation level, each consistent read within a
transaction sets and reads its own fresh snapshot.  With 'LOCK IN SHARE
MODE', a locking read occurs instead: A 'SELECT' blocks until the
transaction containing the freshest rows ends (see
innodb-locking-reads).

Consistent read does not work over certain DDL statements:

   * Consistent read does not work over 'DROP TABLE',
     because MySQL cannot use a table that has been dropped and 'InnoDB'
     destroys the table.

   * Consistent read does not work over 'ALTER TABLE',
     because that statement makes a temporary copy of the
     original table and deletes the original table when the temporary
     copy is built.  When you reissue a consistent read within a
     transaction, rows in the new table are not visible because those
     rows did not exist when the transaction's snapshot was taken.  In
     this case, the transaction returns an error:
     'ER_TABLE_DEF_CHANGED', 'Table definition has changed, please retry
     transaction'.

The type of read varies for selects in clauses like 'INSERT INTO ... SELECT',
see 'UPDATE ... (SELECT)', and
'CREATE TABLE ... SELECT' that do not specify 'FOR
UPDATE' or 'LOCK IN SHARE MODE':

   * By default, 'InnoDB' uses stronger locks and the 'SELECT'
     part acts like 'READ COMMITTED', where each consistent
     read, even within the same transaction, sets and reads its own
     fresh snapshot.

   * To use a consistent read in such cases, enable the
     'innodb_locks_unsafe_for_binlog' option and set the isolation level
     of the transaction to 'READ UNCOMMITTED', 'READ COMMITTED', or
     'REPEATABLE READ' (that is, anything other than 'SERIALIZABLE').
     In this case, no locks are set on rows read from the selected
     table.

14.5.2.4 Locking Reads
......................

If you query data and then insert or update related data within the same
transaction, the regular 'SELECT' statement does not give enough
protection.  Other transactions can update or delete the same rows you
just queried.  'InnoDB' supports two types of locking reads that offer
extra safety:

   * 'SELECT ... LOCK IN SHARE MODE'.

     Sets a shared mode lock on any rows that are read.  Other sessions
     can read the rows, but cannot modify them until your transaction
     commits.  If any of these rows were changed by another transaction
     that has not yet committed, your query waits until that transaction
     ends and then uses the latest values.

   * 'SELECT ... FOR UPDATE'.

     For index records the search encounters, locks the rows and any
     associated index entries, the same as if you issued an 'UPDATE'
     statement for those rows.  Other transactions are blocked from
     updating those rows, from doing 'SELECT ... LOCK IN SHARE MODE', or
     from reading the data in certain transaction isolation levels.
     Consistent reads ignore any locks set on the records that exist in
     the read view.  (Old versions of a record cannot be locked; they
     are reconstructed by applying undo logs on an in-memory copy of the
     record.)

These clauses are primarily useful when dealing with tree-structured or
graph-structured data, either in a single table or split across multiple
tables.  You traverse edges or tree branches from one place to another,
while reserving the right to come back and change any of these 'pointer'
values.

All locks set by 'LOCK IN SHARE MODE' and 'FOR UPDATE' queries are
released when the transaction is committed or rolled back.

*Note*:

Locking of rows for update using 'SELECT FOR UPDATE' only applies when
autocommit is disabled (either by beginning transaction with
'START TRANSACTION' or by setting 'autocommit' to 0.  If
autocommit is enabled, the rows matching the specification are not
locked.

*Locking Read Examples*

Suppose that you want to insert a new row into a table 'child', and make
sure that the child row has a parent row in table 'parent'.  Your
application code can ensure referential integrity throughout this
sequence of operations.

First, use a consistent read to query the table 'PARENT' and verify that
the parent row exists.  Can you safely insert the child row to table
'CHILD'?  No, because some other session could delete the parent row in
the moment between your 'SELECT' and your 'INSERT', without you being
aware of it.

To avoid this potential issue, perform the 'SELECT' using
'LOCK IN SHARE MODE':

     SELECT * FROM parent WHERE NAME = 'Jones' LOCK IN SHARE MODE;

After the 'LOCK IN SHARE MODE' query returns the parent ''Jones'', you
can safely add the child record to the 'CHILD' table and commit the
transaction.  Any transaction that tries to acquire an exclusive lock in
the applicable row in the 'PARENT' table waits until you are finished,
that is, until the data in all tables is in a consistent state.

For another example, consider an integer counter field in a table
'CHILD_CODES', used to assign a unique identifier to each child added to
table 'CHILD'.  Do not use either consistent read or a shared mode read
to read the present value of the counter, because two users of the
database could see the same value for the counter, and a duplicate-key
error occurs if two transactions attempt to add rows with the same
identifier to the 'CHILD' table.

Here, 'LOCK IN SHARE MODE' is not a good solution because if two users
read the counter at the same time, at least one of them ends up in
deadlock when it attempts to update the counter.

To implement reading and incrementing the counter, first perform a
locking read of the counter using 'FOR UPDATE', and then increment the
counter.  For example:

     SELECT counter_field FROM child_codes FOR UPDATE;
     UPDATE child_codes SET counter_field = counter_field + 1;

A 'SELECT ... FOR UPDATE' reads the latest available
data, setting exclusive locks on each row it reads.  Thus, it sets the
same locks a searched SQL 'UPDATE' would set on the rows.

The preceding description is merely an example of how 'SELECT ... FOR UPDATE'
works.  In MySQL, the specific task of generating a
unique identifier actually can be accomplished using only a single
access to the table:

     UPDATE child_codes SET counter_field = LAST_INSERT_ID(counter_field + 1);
     SELECT LAST_INSERT_ID();

The 'SELECT' statement merely retrieves the identifier
information (specific to the current connection).  It does not access
any table.

14.5.3 Locks Set by Different SQL Statements in InnoDB
------------------------------------------------------

A locking read, an 'UPDATE', or a 'DELETE'.
generally set record locks on every index record that is scanned in the
processing of the SQL statement.  It does not matter whether there are
'WHERE' conditions in the statement that would exclude the row.
'InnoDB' does not remember the exact 'WHERE' condition, but only knows
which index ranges were scanned.  The locks are normally next-key locks
that also block inserts into the 'gap' immediately before the record.
However, gap locking can be disabled explicitly, which causes next-key
locking not to be used.  For more information, see
innodb-locking.  The transaction isolation level also can affect which
locks are set; see innodb-transaction-isolation-levels.

If a secondary index is used in a search and index record locks to be
set are exclusive, 'InnoDB' also retrieves the corresponding clustered
index records and sets locks on them.

Differences between shared and exclusive locks are described in
innodb-locking.

If you have no indexes suitable for your statement and MySQL must scan
the entire table to process the statement, every row of the table
becomes locked, which in turn blocks all inserts by other users to the
table.  It is important to create good indexes so that your queries do
not unnecessarily scan many rows.

For 'SELECT ... FOR UPDATE' or 'SELECT ... LOCK IN SHARE MODE',
locks are acquired for scanned rows, and expected
to be released for rows that do not qualify for inclusion in the result
set (for example, if they do not meet the criteria given in the 'WHERE'
clause).  However, in some cases, rows might not be unlocked immediately
because the relationship between a result row and its original source is
lost during query execution.  For example, in a 'UNION',
scanned (and locked) rows from a table might be inserted into a
temporary table before evaluation whether they qualify for the result
set.  In this circumstance, the relationship of the rows in the
temporary table to the rows in the original table is lost and the latter
rows are not unlocked until the end of query execution.

'InnoDB' sets specific types of locks as follows.

   * 'SELECT ... FROM' is a consistent read, reading a
     snapshot of the database and setting no locks unless the
     transaction isolation level is set to 'SERIALIZABLE'.  For
     'SERIALIZABLE' level, the search sets shared next-key locks on the
     index records it encounters.  However, only an index record lock is
     required for statements that lock rows using a unique index to
     search for a unique row.

   * 'SELECT ... FROM ... LOCK IN SHARE MODE' sets shared
     next-key locks on all index records the search encounters.
     However, only an index record lock is required for statements that
     lock rows using a unique index to search for a unique row.

   * 'SELECT ... FROM ... FOR UPDATE' sets an exclusive
     next-key lock on every record the search encounters.  However, only
     an index record lock is required for statements that lock rows
     using a unique index to search for a unique row.

     For index records the search encounters, see 'SELECT ... FROM ... FOR UPDATE'
     blocks other sessions from doing 'SELECT ... FROM ... LOCK IN SHARE MODE'
     or from reading in
     certain transaction isolation levels.  Consistent reads ignore any
     locks set on the records that exist in the read view.

   * 'UPDATE ... WHERE ...' sets an exclusive next-key
     lock on every record the search encounters.  However, only an index
     record lock is required for statements that lock rows using a
     unique index to search for a unique row.

   * When 'UPDATE' modifies a clustered index record,
     implicit locks are taken on affected secondary index records.  The
     'UPDATE' operation also takes shared locks on
     affected secondary index records when performing duplicate check
     scans prior to inserting new secondary index records, and when
     inserting new secondary index records.

   * 'DELETE FROM ... WHERE ...' sets an exclusive
     next-key lock on every record the search encounters.  However, only
     an index record lock is required for statements that lock rows
     using a unique index to search for a unique row.

   * 'INSERT' sets an exclusive lock on the inserted row.
     This lock is an index-record lock, not a next-key lock (that is,
     there is no gap lock) and does not prevent other sessions from
     inserting into the gap before the inserted row.

     Prior to inserting the row, a type of gap lock called an insert
     intention gap lock is set.  This lock signals the intent to insert
     in such a way that multiple transactions inserting into the same
     index gap need not wait for each other if they are not inserting at
     the same position within the gap.  Suppose that there are index
     records with values of 4 and 7.  Separate transactions that attempt
     to insert values of 5 and 6 each lock the gap between 4 and 7 with
     insert intention locks prior to obtaining the exclusive lock on the
     inserted row, but do not block each other because the rows are
     nonconflicting.

     If a duplicate-key error occurs, a shared lock on the duplicate
     index record is set.  This use of a shared lock can result in
     deadlock should there be multiple sessions trying to insert the
     same row if another session already has an exclusive lock.  This
     can occur if another session deletes the row.  Suppose that an
     'InnoDB' table 't1' has the following structure:

          CREATE TABLE t1 (i INT, PRIMARY KEY (i)) ENGINE = InnoDB;

     Now suppose that three sessions perform the following operations in
     order:

     Session 1:

          START TRANSACTION;
          INSERT INTO t1 VALUES(1);

     Session 2:

          START TRANSACTION;
          INSERT INTO t1 VALUES(1);

     Session 3:

          START TRANSACTION;
          INSERT INTO t1 VALUES(1);

     Session 1:

          ROLLBACK;

     The first operation by session 1 acquires an exclusive lock for the
     row.  The operations by sessions 2 and 3 both result in a
     duplicate-key error and they both request a shared lock for the
     row.  When session 1 rolls back, it releases its exclusive lock on
     the row and the queued shared lock requests for sessions 2 and 3
     are granted.  At this point, sessions 2 and 3 deadlock: Neither can
     acquire an exclusive lock for the row because of the shared lock
     held by the other.

     A similar situation occurs if the table already contains a row with
     key value 1 and three sessions perform the following operations in
     order:

     Session 1:

          START TRANSACTION;
          DELETE FROM t1 WHERE i = 1;

     Session 2:

          START TRANSACTION;
          INSERT INTO t1 VALUES(1);

     Session 3:

          START TRANSACTION;
          INSERT INTO t1 VALUES(1);

     Session 1:

          COMMIT;

     The first operation by session 1 acquires an exclusive lock for the
     row.  The operations by sessions 2 and 3 both result in a
     duplicate-key error and they both request a shared lock for the
     row.  When session 1 commits, it releases its exclusive lock on the
     row and the queued shared lock requests for sessions 2 and 3 are
     granted.  At this point, sessions 2 and 3 deadlock: Neither can
     acquire an exclusive lock for the row because of the shared lock
     held by the other.

   * 'INSERT ... ON DUPLICATE KEY UPDATE'.
     differs from a simple 'INSERT' in that an exclusive
     lock rather than a shared lock is placed on the row to be updated
     when a duplicate-key error occurs.  An exclusive index-record lock
     is taken for a duplicate primary key value.  An exclusive next-key
     lock is taken for a duplicate unique key value.

   * 'REPLACE' is done like an 'INSERT'.
     if there is no collision on a unique key.  Otherwise, an exclusive
     next-key lock is placed on the row to be replaced.

   * 'INSERT INTO T SELECT ... FROM S WHERE ...' sets an exclusive index
     record lock (without a gap lock) on each row inserted into 'T'.  If
     the transaction isolation level is 'READ COMMITTED', or
     'innodb_locks_unsafe_for_binlog' is enabled and the transaction
     isolation level is not 'SERIALIZABLE', 'InnoDB' does the search on
     'S' as a consistent read (no locks).  Otherwise, 'InnoDB' sets
     shared next-key locks on rows from 'S'.  'InnoDB' has to set locks
     in the latter case: In roll-forward recovery from a backup, every
     SQL statement must be executed in exactly the same way it was done
     originally.

     'CREATE TABLE ... SELECT ...' performs the
     'SELECT' with shared next-key locks or as a
     consistent read, as for 'INSERT ... SELECT'.

     When a 'SELECT' is used in the constructs 'REPLACE INTO t SELECT
     ... FROM s WHERE ...' or 'UPDATE t ... WHERE col IN (SELECT ...
     FROM s ...)', 'InnoDB' sets shared next-key locks on rows from
     table 's'.

   * While initializing a previously specified 'AUTO_INCREMENT' column
     on a table, 'InnoDB' sets an exclusive lock on the end of the index
     associated with the 'AUTO_INCREMENT' column.  In accessing the
     auto-increment counter, 'InnoDB' uses a specific 'AUTO-INC' table
     lock mode where the lock lasts only to the end of the current SQL
     statement, not to the end of the entire transaction.  Other
     sessions cannot insert into the table while the 'AUTO-INC' table
     lock is held; see innodb-transaction-model.

     'InnoDB' fetches the value of a previously initialized
     'AUTO_INCREMENT' column without setting any locks.

   * If a 'FOREIGN KEY' constraint is defined on a table, any insert,
     update, or delete that requires the constraint condition to be
     checked sets shared record-level locks on the records that it looks
     at to check the constraint.  'InnoDB' also sets these locks in the
     case where the constraint fails.

   * 'LOCK TABLES' sets table locks, but it is the
     higher MySQL layer above the 'InnoDB' layer that sets these locks.
     'InnoDB' is aware of table locks if 'innodb_table_locks = 1' (the
     default) and 'autocommit = 0', and the MySQL layer above 'InnoDB'
     knows about row-level locks.

     Otherwise, 'InnoDB''s automatic deadlock detection cannot detect
     deadlocks where such table locks are involved.  Also, because in
     this case the higher MySQL layer does not know about row-level
     locks, it is possible to get a table lock on a table where another
     session currently has row-level locks.  However, this does not
     endanger transaction integrity, as discussed in
     innodb-deadlock-detection.  See also innodb-restrictions.

14.5.4 Phantom Rows
-------------------

The so-called _phantom_ problem occurs within a transaction when the
same query produces different sets of rows at different times.  For
example, if a 'SELECT' is executed twice, but returns a
row the second time that was not returned the first time, the row is a
'phantom' row.

Suppose that there is an index on the 'id' column of the 'child' table
and that you want to read and lock all rows from the table having an
identifier value larger than 100, with the intention of updating some
column in the selected rows later:

     SELECT * FROM child WHERE id > 100 FOR UPDATE;

The query scans the index starting from the first record where 'id' is
bigger than 100.  Let the table contain rows having 'id' values of 90
and 102.  If the locks set on the index records in the scanned range do
not lock out inserts made in the gaps (in this case, the gap between 90
and 102), another session can insert a new row into the table with an
'id' of 101.  If you were to execute the same 'SELECT'.
within the same transaction, you would see a new row with an 'id' of 101
(a 'phantom') in the result set returned by the query.  If we regard a
set of rows as a data item, the new phantom child would violate the
isolation principle of transactions that a transaction should be able to
run so that the data it has read does not change during the transaction.

To prevent phantoms, 'InnoDB' uses an algorithm called _next-key
locking_ that combines index-row locking with gap locking.  'InnoDB'
performs row-level locking in such a way that when it searches or scans
a table index, it sets shared or exclusive locks on the index records it
encounters.  Thus, the row-level locks are actually index-record locks.
In addition, a next-key lock on an index record also affects the 'gap'
before that index record.  That is, a next-key lock is an index-record
lock plus a gap lock on the gap preceding the index record.  If one
session has a shared or exclusive lock on record 'R' in an index,
another session cannot insert a new index record in the gap immediately
before 'R' in the index order.

When 'InnoDB' scans an index, it can also lock the gap after the last
record in the index.  Just that happens in the preceding example: To
prevent any insert into the table where 'id' would be bigger than 100,
the locks set by 'InnoDB' include a lock on the gap following 'id' value
102.

You can use next-key locking to implement a uniqueness check in your
application: If you read your data in share mode and do not see a
duplicate for a row you are going to insert, then you can safely insert
your row and know that the next-key lock set on the successor of your
row during the read prevents anyone meanwhile inserting a duplicate for
your row.  Thus, the next-key locking enables you to 'lock' the
nonexistence of something in your table.

Gap locking can be disabled as discussed in innodb-locking.
This may cause phantom problems because other sessions can insert new
rows into the gaps when gap locking is disabled.

14.5.5 Deadlocks in InnoDB
--------------------------

A deadlock is a situation where different transactions are unable to
proceed because each holds a lock that the other needs.  Because both
transactions are waiting for a resource to become available, neither
ever release the locks it holds.

A deadlock can occur when transactions lock rows in multiple tables
(through statements such as 'UPDATE' or 'SELECT ... FOR UPDATE'),
but in the opposite order.  A deadlock can also
occur when such statements lock ranges of index records and gaps, with
each transaction acquiring some locks but not others due to a timing
issue.  For a deadlock example, see innodb-deadlock-example.

To reduce the possibility of deadlocks, use transactions rather than
'LOCK TABLES' statements; keep transactions that
insert or update data small enough that they do not stay open for long
periods of time; when different transactions update multiple tables or
large ranges of rows, use the same order of operations (such as
'SELECT ... FOR UPDATE') in each transaction; create indexes on
the columns used in 'SELECT ... FOR UPDATE' and
'UPDATE ... WHERE' statements.  The possibility of deadlocks is
not affected by the isolation level, because the isolation level changes
the behavior of read operations, while deadlocks occur because of write
operations.  For more information about avoiding and recovering from
deadlock conditions, see innodb-deadlocks-handling.

When deadlock detection is enabled (the default) and a deadlock does
occur, 'InnoDB' detects the condition and rolls back one of the
transactions (the victim).  If deadlock detection is disabled using the
'innodb_deadlock_detect' configuration option, 'InnoDB' relies on the
'innodb_lock_wait_timeout' setting to roll back transactions in case of
a deadlock.  Thus, even if your application logic is correct, you must
still handle the case where a transaction must be retried.  To see the
last deadlock in an 'InnoDB' user transaction, use the 'SHOW ENGINE INNODB STATUS'
command.  If frequent deadlocks
highlight a problem with transaction structure or application error
handling, run with the 'innodb_print_all_deadlocks' setting enabled to
print information about all deadlocks to the 'mysqld'.
error log.  For more information about how deadlocks are automatically
detected and handled, see innodb-deadlock-detection.

14.5.5.1 An InnoDB Deadlock Example
...................................

The following example illustrates how an error can occur when a lock
request would cause a deadlock.  The example involves two clients, A and
B.

First, client A creates a table containing one row, and then begins a
transaction.  Within the transaction, A obtains an S lock on the row by
selecting it in share mode:

     mysql> CREATE TABLE t (i INT) ENGINE = InnoDB;
     Query OK, 0 rows affected (1.07 sec)

     mysql> INSERT INTO t (i) VALUES(1);
     Query OK, 1 row affected (0.09 sec)

     mysql> START TRANSACTION;
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT * FROM t WHERE i = 1 LOCK IN SHARE MODE;
     +------+
     | i    |
     +------+
     |    1 |
     +------+

Next, client B begins a transaction and attempts to delete the row from
the table:

     mysql> START TRANSACTION;
     Query OK, 0 rows affected (0.00 sec)

     mysql> DELETE FROM t WHERE i = 1;

The delete operation requires an X lock.  The lock cannot be granted
because it is incompatible with the S lock that client A holds, so the
request goes on the queue of lock requests for the row and client B
blocks.

Finally, client A also attempts to delete the row from the table:

     mysql> DELETE FROM t WHERE i = 1;
     ERROR 1213 (40001): Deadlock found when trying to get lock;
     try restarting transaction

Deadlock occurs here because client A needs an X lock to delete the row.
However, that lock request cannot be granted because client B already
has a request for an X lock and is waiting for client A to release its S
lock.  Nor can the S lock held by A be upgraded to an X lock because of
the prior request by B for an X lock.  As a result, 'InnoDB' generates
an error for one of the clients and releases its locks.  The client
returns this error:

     ERROR 1213 (40001): Deadlock found when trying to get lock;
     try restarting transaction

At that point, the lock request for the other client can be granted and
it deletes the row from the table.

14.5.5.2 Deadlock Detection and Rollback
........................................

When deadlock detection is enabled (the default), 'InnoDB' automatically
detects transaction deadlocks and rolls back a transaction or
transactions to break the deadlock.  'InnoDB' tries to pick small
transactions to roll back, where the size of a transaction is determined
by the number of rows inserted, updated, or deleted.

'InnoDB' is aware of table locks if 'innodb_table_locks = 1' (the
default) and 'autocommit = 0', and the MySQL layer above it knows about
row-level locks.  Otherwise, 'InnoDB' cannot detect deadlocks where a
table lock set by a MySQL 'LOCK TABLES' statement or
a lock set by a storage engine other than 'InnoDB' is involved.  Resolve
these situations by setting the value of the 'innodb_lock_wait_timeout'
system variable.

When 'InnoDB' performs a complete rollback of a transaction, all locks
set by the transaction are released.  However, if just a single SQL
statement is rolled back as a result of an error, some of the locks set
by the statement may be preserved.  This happens because 'InnoDB' stores
row locks in a format such that it cannot know afterward which lock was
set by which statement.

If a 'SELECT' calls a stored function in a transaction,
and a statement within the function fails, that statement rolls back.
Furthermore, if 'ROLLBACK' is executed after that, the
entire transaction rolls back.

If the 'LATEST DETECTED DEADLOCK' section of 'InnoDB' Monitor output
includes a message stating, ''TOO DEEP OR LONG SEARCH IN THE LOCK TABLE
WAITS-FOR GRAPH, WE WILL ROLL BACK FOLLOWING TRANSACTION',' this
indicates that the number of transactions on the wait-for list has
reached a limit of 200.  A wait-for list that exceeds 200 transactions
is treated as a deadlock and the transaction attempting to check the
wait-for list is rolled back.  The same error may also occur if the
locking thread must look at more than 1,000,000 locks owned by
transactions on the wait-for list.

For techniques to organize database operations to avoid deadlocks, see
innodb-deadlocks.

*Disabling Deadlock Detection*

On high concurrency systems, deadlock detection can cause a slowdown
when numerous threads wait for the same lock.  At times, it may be more
efficient to disable deadlock detection and rely on the
'innodb_lock_wait_timeout' setting for transaction rollback when a
deadlock occurs.  Deadlock detection can be disabled using the
'innodb_deadlock_detect' configuration option.

14.5.5.3 How to Minimize and Handle Deadlocks
.............................................

This section builds on the conceptual information about deadlocks in
innodb-deadlock-detection.  It explains how to organize database
operations to minimize deadlocks and the subsequent error handling
required in applications.

Deadlocks are a classic problem in transactional databases, but they are
not dangerous unless they are so frequent that you cannot run certain
transactions at all.  Normally, you must write your applications so that
they are always prepared to re-issue a transaction if it gets rolled
back because of a deadlock.

'InnoDB' uses automatic row-level locking.  You can get deadlocks even
in the case of transactions that just insert or delete a single row.
That is because these operations are not really 'atomic'; they
automatically set locks on the (possibly several) index records of the
row inserted or deleted.

You can cope with deadlocks and reduce the likelihood of their
occurrence with the following techniques:

   * At any time, issue the 'SHOW ENGINE INNODB STATUS'
     command to determine the cause of the most recent
     deadlock.  That can help you to tune your application to avoid
     deadlocks.

   * If frequent deadlock warnings cause concern, collect more extensive
     debugging information by enabling the 'innodb_print_all_deadlocks'
     configuration option.  Information about each deadlock, not just
     the latest one, is recorded in the MySQL error log.  Disable this
     option when you are finished debugging.

   * Always be prepared to re-issue a transaction if it fails due to
     deadlock.  Deadlocks are not dangerous.  Just try again.

   * Keep transactions small and short in duration to make them less
     prone to collision.

   * Commit transactions immediately after making a set of related
     changes to make them less prone to collision.  In particular, do
     not leave an interactive 'mysql' session open for a
     long time with an uncommitted transaction.

   * If you use locking reads (see 'SELECT ... FOR UPDATE' or
     'SELECT ... LOCK IN SHARE MODE'), try using a lower isolation level
     such as 'READ COMMITTED'.

   * When modifying multiple tables within a transaction, or different
     sets of rows in the same table, do those operations in a consistent
     order each time.  Then transactions form well-defined queues and do
     not deadlock.  For example, organize database operations into
     functions within your application, or call stored routines, rather
     than coding multiple similar sequences of 'INSERT', 'UPDATE', and
     'DELETE' statements in different places.

   * Add well-chosen indexes to your tables.  Then your queries need to
     scan fewer index records and consequently set fewer locks.  Use
     'EXPLAIN SELECT' to determine which indexes the
     MySQL server regards as the most appropriate for your queries.

   * Use less locking.  If you can afford to permit a 'SELECT'
     to return data from an old snapshot, do not add the clause
     'FOR UPDATE' or 'LOCK IN SHARE MODE' to it.  Using the 'READ
     COMMITTED' isolation level is good here, because each consistent
     read within the same transaction reads from its own fresh snapshot.

   * If nothing else helps, serialize your transactions with table-level
     locks.  The correct way to use 'LOCK TABLES'.
     with transactional tables, such as 'InnoDB' tables, is to begin a
     transaction with 'SET autocommit = 0' (not 'START TRANSACTION')
     followed by 'LOCK TABLES',
     and to not call 'UNLOCK TABLES'.
     until you commit the transaction explicitly.  For example, if you
     need to write to table 't1' and read from table 't2', you can do
     this:

          SET autocommit=0;
          LOCK TABLES t1 WRITE, t2 READ, ...;
          ... DO SOMETHING WITH TABLES T1 AND T2 HERE ...
          COMMIT;
          UNLOCK TABLES;

     Table-level locks prevent concurrent updates to the table, avoiding
     deadlocks at the expense of less responsiveness for a busy system.

   * Another way to serialize transactions is to create an auxiliary
     'semaphore' table that contains just a single row.  Have each
     transaction update that row before accessing other tables.  In that
     way, all transactions happen in a serial fashion.  Note that the
     'InnoDB' instant deadlock detection algorithm also works in this
     case, because the serializing lock is a row-level lock.  With MySQL
     table-level locks, the timeout method must be used to resolve
     deadlocks.

14.6 InnoDB Configuration
=========================

This section provides configuration information and procedures for
'InnoDB' initialization, startup, and various components and features of
the 'InnoDB' storage engine.  For information about optimizing database
operations for 'InnoDB' tables, see optimizing-innodb.

14.6.1 InnoDB Startup Configuration
-----------------------------------

The first decisions to make about 'InnoDB' configuration involve the
configuration of data files, log files, page size, and memory buffers.
It is recommended that you define data file, log file, and page size
configuration before creating the 'InnoDB' instance.  Modifying data
file or log file configuration after the 'InnoDB' instance is created
may involve a non-trivial procedure, and page size can only be defined
when the 'InnoDB' instance is first initialized.

In addition to these topics, this section provides information about
specifying 'InnoDB' options in a configuration file, viewing 'InnoDB'
initialization information, and important storage considerations.

   * innodb-startup-mysql-configuration-file

   * innodb-startup-initialization-information

   * innodb-startup-storage-considerations

   * innodb-startup-data-file-configuration

   * innodb-startup-log-file-configuration

   * innodb-startup-undo-tablespace

   * innodb-startup-temporary-tablespace

   * innodb-startup-page-size

   * innodb-startup-memory-configuration

*Specifying Options in a MySQL Configuration File*

Because MySQL uses data file, log file, and page size configuration
settings to initialize the 'InnoDB' instance, it is recommended that you
define these settings in a configuration file that MySQL reads at
startup, prior to initializing 'InnoDB' for the first time.  'InnoDB' is
initialized when the MySQL server is started, and the first
initialization of 'InnoDB' normally occurs the first time you start the
MySQL server.

You can place 'InnoDB' options in the '[mysqld]' group of any option
file that your server reads when it starts.  The locations of MySQL
option files are described in option-files.

To make sure that 'mysqld' reads options only from a
specific file, use the '--defaults-file' option as the first option on
the command line when starting the server:

     mysqld --defaults-file=PATH_TO_CONFIGURATION_FILE

*Viewing InnoDB Initialization Information*

To view 'InnoDB' initialization information during startup, start
'mysqld' from a command prompt.  When 'mysqld'.
is started from a command prompt, initialization information is printed
to the console.

For example, on Windows, if 'mysqld' is located in
'C:\Program Files\MySQL\MySQL Server 5.7\bin', start the MySQL server
like this:

     C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld" --console

On Unix-like systems, see 'mysqld' is located in the 'bin'
directory of your MySQL installation:

     shell> bin/mysqld --user=mysql &

If you do not send server output to the console, check the error log
after startup to see the initialization information 'InnoDB' printed
during the startup process.

For information about starting MySQL using other methods, see
automatic-start.

*Note*:

'InnoDB' does not open all user tables and associated data files at
startup.  However, 'InnoDB' does check for the existence of tablespace
files ('*.ibd' files) that are referenced in the data dictionary.  If a
tablespace file is not found, 'InnoDB' logs an error and continues the
startup sequence.  Tablespace files that are referenced in the redo log
may be opened during crash recovery for redo application.

*Important Storage Considerations*

Review the following storage-related considerations before proceeding
with your startup configuration.

   * In some cases, database performance improves if the data is not all
     placed on the same physical disk.  Putting log files on a different
     disk from data is very often beneficial for performance.  For
     example, you can place system tablespace data files and log files
     on different disks.  You can also use raw disk partitions (raw
     devices) for 'InnoDB' data files, which may speed up I/O. See
     innodb-raw-devices.

   * 'InnoDB' is a transaction-safe (ACID compliant) storage engine for
     MySQL that has commit, rollback, and crash-recovery capabilities to
     protect user data.  *However, it cannot do so* if the underlying
     operating system or hardware does not work as advertised.  Many
     operating systems or disk subsystems may delay or reorder write
     operations to improve performance.  On some operating systems, the
     very 'fsync()' system call that should wait until all unwritten
     data for a file has been flushed might actually return before the
     data has been flushed to stable storage.  Because of this, an
     operating system crash or a power outage may destroy recently
     committed data, or in the worst case, even corrupt the database
     because of write operations having been reordered.  If data
     integrity is important to you, perform some 'pull-the-plug' tests
     before using anything in production.  On OS X 10.3 and higher,
     'InnoDB' uses a special 'fcntl()' file flush method.  Under Linux,
     it is advisable to *disable the write-back cache*.

     On ATA/SATA disk drives, a command such 'hdparm -W0 /dev/hda' may
     work to disable the write-back cache.  *Beware that some drives or
     disk controllers may be unable to disable the write-back cache.*

   * With regard to 'InnoDB' recovery capabilities that protect user
     data, 'InnoDB' uses a file flush technique involving a structure
     called the doublewrite buffer, which is enabled by default
     ('innodb_doublewrite=ON').  The doublewrite buffer adds safety to
     recovery following a crash or power outage, and improves
     performance on most varieties of Unix by reducing the need for
     'fsync()' operations.  It is recommended that the
     'innodb_doublewrite' option remains enabled if you are concerned
     with data integrity or possible failures.  For additional
     information about the doublewrite buffer, see
     innodb-disk-io.

   * Before using NFS with 'InnoDB', review potential issues outlined in
     disk-issues-nfs.

   * Running MySQL server on a 4K sector hard drive on Windows is not
     supported with 'innodb_flush_method=async_unbuffered', which is the
     default setting.  The workaround is to use
     'innodb_flush_method=normal'.

*System Tablespace Data File Configuration*

The 'innodb_data_file_path' configuration option defines the name, size,
and attributes of 'InnoDB' system tablespace data files.  If you do not
specify a value for 'innodb_data_file_path', the default behavior is to
create a single auto-extending data file, slightly larger than 12MB,
named 'ibdata1'.

To specify more than one data file, separate them by semicolon (';')
characters:

     innodb_data_file_path=DATAFILE_SPEC1[;DATAFILE_SPEC2]...

The following setting configures a single 12MB data file named 'ibdata1'
that is auto-extending.  No location for the file is given, so by
default, 'InnoDB' creates it in the MySQL data directory:

     [mysqld]
     innodb_data_file_path=ibdata1:12M:autoextend

File size is specified using 'K', 'M', or 'G' suffix letters to indicate
units of KB, MB, or GB. If specifying the data file size in kilobytes
(KB), do so in multiples of 1024.  Otherwise, KB values are rounded to
nearest megabyte (MB) boundary.  The sum of the sizes of the files must
be at least slightly larger than 12MB.

A minimum file size is enforced for the _first_ system tablespace data
file to ensure that there is enough space for doublewrite buffer pages:

   * For an 'innodb_page_size' value of 16KB or less, the minimum file
     size is 3MB.

   * For an 'innodb_page_size' value of 32KB, the minimum file size is
     6MB.

   * For an 'innodb_page_size' value of 64KB, the minimum file size is
     12MB.

A system tablespace with a fixed-size 50MB data file named 'ibdata1' and
a 50MB auto-extending file named 'ibdata2' can be configured like this:

     [mysqld]
     innodb_data_file_path=ibdata1:50M;ibdata2:50M:autoextend

The full syntax for a data file specification includes the file name,
file size, and optional 'autoextend' and 'max' attributes:

     FILE_NAME:FILE_SIZE[:autoextend[:max:MAX_FILE_SIZE]]

The 'autoextend' and 'max' attributes can be used only for the data file
that is specified last in the 'innodb_data_file_path' setting.

If you specify the 'autoextend' option for the last data file, 'InnoDB'
extends the data file if it runs out of free space in the tablespace.
The 'autoextend' increment is 64MB at a time by default.  To modify the
increment, change the 'innodb_autoextend_increment' system variable.

If the disk becomes full, you might want to add another data file on
another disk.  For instructions, see
innodb-resize-system-tablespace.

The size limit of individual files is determined by your operating
system.  You can set the file size to more than 4GB on operating systems
that support large files.  You can also use raw disk partitions as data files.

'InnoDB' is not aware of the file system maximum file size, so be
cautious on file systems where the maximum file size is a small value
such as 2GB. To specify a maximum size for an auto-extending data file,
use the 'max' attribute following the 'autoextend' attribute.  Use the
'max' attribute only in cases where constraining disk usage is of
critical importance, because exceeding the maximum size causes a fatal
error, possibly causing the server to exit.  The following configuration
permits 'ibdata1' to grow to a limit of 500MB:

     [mysqld]
     innodb_data_file_path=ibdata1:12M:autoextend:max:500M

'InnoDB' creates system tablespace files in the MySQL data directory by
default ('datadir').  To specify a location explicitly, use the
'innodb_data_home_dir' option.  For example, to create two files named
'ibdata1' and 'ibdata2' in a directory named 'myibdata', configure
'InnoDB' like this:

     [mysqld]
     innodb_data_home_dir = /path/to/myibdata/
     innodb_data_file_path=ibdata1:50M;ibdata2:50M:autoextend

*Note*:

A trailing slash is required when specifying a value for
'innodb_data_home_dir'.

'InnoDB' does not create directories, so make sure that the 'myibdata'
directory exists before you start the server.  Use the Unix or DOS
'mkdir' command to create directories.

Make sure that the MySQL server has the proper access rights to create
files in the data directory.  More generally, the server must have
access rights in any directory where it needs to create data files.

'InnoDB' forms the directory path for each data file by textually
concatenating the value of 'innodb_data_home_dir' to the data file name.
If the 'innodb_data_home_dir' option is not specified, the default value
is the 'dot' directory './', which means the MySQL data directory.  (The
MySQL server changes its current working directory to its data directory
when it begins executing.)

If you specify 'innodb_data_home_dir' as an empty string, you can
specify absolute paths for data files listed in the
'innodb_data_file_path' value.  The following example is equivalent to
the preceding one:

     [mysqld]
     innodb_data_home_dir =
     innodb_data_file_path=/path/to/myibdata/ibdata1:50M;/path/to/myibdata/ibdata2:50M:autoextend

*InnoDB Log File Configuration*

By default, 'InnoDB' creates two 48MB log files in the MySQL data
directory ('datadir') named 'ib_logfile0' and 'ib_logfile1'.

The following options can be used to modify the default configuration:

   * 'innodb_log_group_home_dir' defines directory path to the 'InnoDB'
     log files (the redo logs).  If this option is not configured,
     'InnoDB' log files are created in the MySQL data directory
     ('datadir').

     You might use this option to place 'InnoDB' log files in a
     different physical storage location than 'InnoDB' data files to
     avoid potential I/O resource conflicts.  For example:

          [mysqld]
          innodb_log_group_home_dir = /dr3/iblogs

     *Note*:

     'InnoDB' does not create directories, so make sure that the log
     directory exists before you start the server.  Use the Unix or DOS
     'mkdir' command to create any necessary directories.

     Make sure that the MySQL server has the proper access rights to
     create files in the log directory.  More generally, the server must
     have access rights in any directory where it needs to create log
     files.

   * 'innodb_log_files_in_group' defines the number of log files in the
     log group.  The default and recommended value is 2.

   * 'innodb_log_file_size' defines the size in bytes of each log file
     in the log group.  The combined size of log files
     ('innodb_log_file_size' * 'innodb_log_files_in_group') cannot
     exceed a maximum value that is slightly less than 512GB. A pair of
     255 GB log files, for example, approaches the limit but does not
     exceed it.  The default log file size is 48MB. Generally, the
     combined size of the log files should be large enough that the
     server can smooth out peaks and troughs in workload activity, which
     often means that there is enough redo log space to handle more than
     an hour of write activity.  The larger the value, the less
     checkpoint flush activity is needed in the buffer pool, saving disk
     I/O. For additional information, see
     optimizing-innodb-logging.

*InnoDB Undo Tablespace Configuration*

By default, 'InnoDB' undo logs are part of the system tablespace.
However, you can choose to store 'InnoDB' undo logs in one or more
separate undo tablespaces, typically on a different storage device.

The 'innodb_undo_directory' configuration option defines the path where
'InnoDB' creates separate tablespaces for the undo logs.  This option is
typically used in conjunction with the 'innodb_rollback_segments' and
'innodb_undo_tablespaces' options, which determine the disk layout of
the undo logs outside the system tablespace.

*Note*:

'innodb_undo_tablespaces' is deprecated and will be removed in a future
release.

For more information, see innodb-undo-tablespace.

*InnoDB Temporary Tablespace Configuration*

By default, 'InnoDB' creates a single auto-extending temporary
tablespace data file named 'ibtmp1' that is slightly larger than 12MB in
the 'innodb_data_home_dir' directory.  The default temporary tablespace
data file configuration can be modified at startup using the
'innodb_temp_data_file_path' configuration option.

The 'innodb_temp_data_file_path' option specifies the path, file name,
and file size for 'InnoDB' temporary tablespace data files.  The full
directory path for a file is formed by concatenating
'innodb_data_home_dir' to the path specified by
'innodb_temp_data_file_path'.  File size is specified in KB, MB, or GB
(1024MB) by appending K, M, or G to the size value.  The sum of the
sizes of the files must be slightly larger than 12MB.

The 'innodb_data_home_dir' default value is the MySQL data directory
('datadir').

*InnoDB Page Size Configuration*

The 'innodb_page_size' option specifies the page size for all 'InnoDB'
tablespaces in a MySQL instance.  This value is set when the instance is
created and remains constant afterward.  Valid values are 64k, 32k, 16k
(the default), 8k, and 4k.  Alternatively, you can specify page size in
bytes (65536, 32768, 16384, 8192, 4096).

The default page size of 16k is appropriate for a wide range of
workloads, particularly for queries involving table scans and DML
operations involving bulk updates.  Smaller page sizes might be more
efficient for OLTP workloads involving many small writes, where
contention can be an issue when a single page contains many rows.
Smaller pages might also be efficient with SSD storage devices, which
typically use small block sizes.  Keeping the 'InnoDB' page size close
to the storage device block size minimizes the amount of unchanged data
that is rewritten to disk.

*InnoDB Memory Configuration*

MySQL allocates memory to various caches and buffers to improve
performance of database operations.  When allocating memory for
'InnoDB', always consider memory required by the operating system,
memory allocated to other applications, and memory allocated for other
MySQL buffers and caches.  For example, if you use 'MyISAM' tables,
consider the amount of memory allocated for the key buffer
('key_buffer_size').  For an overview of MySQL buffers and caches, see
memory-use.

Buffers specific to 'InnoDB' are configured using the following
parameters:

   * 'innodb_buffer_pool_size' defines size of the buffer pool, which is
     the memory area that holds cached data for 'InnoDB' tables,
     indexes, and other auxiliary buffers.  The size of the buffer pool
     is important for system performance, and it is typically
     recommended that 'innodb_buffer_pool_size' is configured to 50 to
     75 percent of system memory.  The default buffer pool size is
     128MB. For additional guidance, see memory-use.  For
     information about how to configure 'InnoDB' buffer pool size, see
     innodb-buffer-pool-resize.  Buffer pool size can be
     configured at startup or dynamically.

     On systems with a large amount of memory, you can improve
     concurrency by dividing the buffer pool into multiple buffer pool
     instances.  The number of buffer pool instances is controlled by
     the by 'innodb_buffer_pool_instances' option.  By default, 'InnoDB'
     creates one buffer pool instance.  The number of buffer pool
     instances can be configured at startup.  For more information, see
     innodb-multiple-buffer-pools.

   * 'innodb_log_buffer_size' defines the size in bytes of the buffer
     that 'InnoDB' uses to write to the log files on disk.  The default
     size is 16MB. A large log buffer enables large transactions to run
     without a need to write the log to disk before the transactions
     commit.  If you have transactions that update, insert, or delete
     many rows, you might consider increasing the size of the log buffer
     to save disk I/O. 'innodb_log_buffer_size' can be configured at
     startup.  For related information, see
     optimizing-innodb-logging.

*Warning*:

On 32-bit GNU/Linux x86, be careful not to set memory usage too high.
'glibc' may permit the process heap to grow over thread stacks, which
crashes your server.  It is a risk if the memory allocated to the
'mysqld' process for global and per-thread buffers and caches
is close to or exceeds 2GB.

A formula similar to the following that calculates global and per-thread
memory allocation for MySQL can be used to estimate MySQL memory usage.
You may need to modify the formula to account for buffers and caches in
your MySQL version and configuration.  For an overview of MySQL buffers
and caches, see memory-use.

     innodb_buffer_pool_size
     + key_buffer_size
     + max_connections*(sort_buffer_size+read_buffer_size+binlog_cache_size)
     + max_connections*2MB

Each thread uses a stack (often 2MB, but only 256KB in MySQL binaries
provided by Oracle Corporation.)  and in the worst case also uses
'sort_buffer_size + read_buffer_size' additional memory.

On Linux, if the kernel is enabled for large page support, 'InnoDB' can
use large pages to allocate memory for its buffer pool.  See
large-page-support.

14.6.2 Configuring InnoDB for Read-Only Operation
-------------------------------------------------

You can now query 'InnoDB' tables where the MySQL data directory is on
read-only media, by enabling the '--innodb-read-only' configuration
option at server startup.

*How to Enable*

To prepare an instance for read-only operation, make sure all the
necessary information is flushed to the data files before storing it on
the read-only medium.  Run the server with change buffering disabled
('innodb_change_buffering=0') and do a slow shutdown.

To enable read-only mode for an entire MySQL instance, specify the
following configuration options at server startup:

   * '--innodb-read-only=1'

   * If the instance is on read-only media such as a DVD or CD, or the
     '/var' directory is not writeable by all:
     '--pid-file=PATH_ON_WRITEABLE_MEDIA' and
     '--event-scheduler=disabled'

   * '--innodb_temp_data_file_path'.  This option specifies the path,
     file name, and file size for 'InnoDB' temporary tablespace data
     files.  The default setting is 'ibtmp1:12M:autoextend', which
     creates the 'ibtmp1' temporary tablespace data file in the data
     directory.  To prepare an instance for read-only operation, set
     'innodb_temp_data_file_path' to a location outside of the data
     directory.  The path must be relative to the data directory; for
     example:

          --innodb_temp_data_file_path=../../../tmp/ibtmp1:12M:autoextend

*Usage Scenarios*

This mode of operation is appropriate in situations such as:

   * Distributing a MySQL application, or a set of MySQL data, on a
     read-only storage medium such as a DVD or CD.

   * Multiple MySQL instances querying the same data directory
     simultaneously, typically in a data warehousing configuration.  You
     might use this technique to avoid bottlenecks that can occur with a
     heavily loaded MySQL instance, or you might use different
     configuration options for the various instances to tune each one
     for particular kinds of queries.

   * Querying data that has been put into a read-only state for security
     or data integrity reasons, such as archived backup data.

*Note*:

This feature is mainly intended for flexibility in distribution and
deployment, rather than raw performance based on the read-only aspect.
See innodb-performance-ro-txn for ways to tune the performance
of read-only queries, which do not require making the entire server
read-only.

*How It Works*

When the server is run in read-only mode through the
'--innodb-read-only' option, certain 'InnoDB' features and components
are reduced or turned off entirely:

   * No change buffering is done, in particular no merges from the
     change buffer.  To make sure the change buffer is empty when you
     prepare the instance for read-only operation, disable change
     buffering ('innodb_change_buffering=0') and do a slow shutdown
     first.

   * There is no crash recovery phase at startup.  The instance must
     have performed a slow shutdown before being put into the read-only
     state.

   * Because the redo log is not used in read-only operation, you can
     set 'innodb_log_file_size' to the smallest size possible (1 MB)
     before making the instance read-only.

   * All background threads other than I/O read threads are turned off.
     As a consequence, a read-only instance cannot encounter any
     deadlocks.

   * Information about deadlocks, monitor output, and so on is not
     written to temporary files.  As a consequence, see 'SHOW ENGINE INNODB STATUS'
     does not produce any output.

   * If the MySQL server is started with '--innodb-read-only' but the
     data directory is still on writeable media, the root user can still
     perform DCL operations such as 'GRANT' and
     'REVOKE'.

   * Changes to configuration option settings that would normally change
     the behavior of write operations, have no effect when the server is
     in read-only mode.

   * The MVCC processing to enforce isolation levels is turned off.  All
     queries read the latest version of a record, because update and
     deletes are not possible.

   * The undo log is not used.  Disable any settings for the
     'innodb_undo_tablespaces' and 'innodb_undo_directory' configuration
     options.

14.6.3 InnoDB Buffer Pool Configuration
---------------------------------------

This section provides configuration and tuning information for the
'InnoDB' buffer pool.

14.6.3.1 The InnoDB Buffer Pool
...............................

'InnoDB' maintains a storage area called
the buffer pool for caching data and indexes in memory.  Knowing how the
'InnoDB' buffer pool works, and taking advantage of it to keep
frequently accessed data in memory, is an important aspect of MySQL
tuning.  For information about how the 'InnoDB' buffer pool works, see
innodb-buffer-pool-lru.

You can configure the various aspects of the 'InnoDB' buffer pool to
improve performance.

   * Ideally, you set the size of the buffer pool to as large a value as
     practical, leaving enough memory for other processes on the server
     to run without excessive paging.  The larger the buffer pool, the
     more 'InnoDB' acts like an in-memory database, reading data from
     disk once and then accessing the data from memory during subsequent
     reads.  See innodb-buffer-pool-resize.

   * With 64-bit systems with large memory sizes, you can split the
     buffer pool into multiple parts, to minimize contention for the
     memory structures among concurrent operations.  For details, see
     innodb-multiple-buffer-pools.

   * You can keep frequently accessed data in memory despite sudden
     spikes of activity for operations such as backups or reporting.
     For details, see innodb-performance-midpoint_insertion.

   * You can control when and how 'InnoDB' performs read-ahead requests
     to prefetch pages into the buffer pool asynchronously, in
     anticipation that the pages will be needed soon.  For details, see
     innodb-performance-read_ahead.

   * You can control when background flushing of dirty pages occurs and
     whether or not 'InnoDB' dynamically adjusts the rate of flushing
     based on workload.  For details, see
     innodb-performance-adaptive_flushing.

   * You can fine-tune aspects of 'InnoDB' buffer pool flushing behavior
     to improve performance.  For details, see
     innodb-lru-background-flushing.

   * You can configure how 'InnoDB' preserves the current buffer pool
     state to avoid a lengthy warmup period after a server restart.  You
     can also save the current buffer pool state while the server is
     running.  For details, see innodb-preload-buffer-pool.

*InnoDB Buffer Pool LRU Algorithm*

'InnoDB' manages the buffer pool as a list, using a variation of the
least recently used (LRU) algorithm.  When room is needed to add a new
page to the pool, 'InnoDB' evicts the least recently used page and adds
the new page to the middle of the list.  This 'midpoint insertion
strategy' treats the list as two sublists:

   * At the head, a sublist of 'new' (or 'young') pages that were
     accessed recently.

   * At the tail, a sublist of 'old' pages that were accessed less
     recently.

This algorithm keeps pages that are heavily used by queries in the new
sublist.  The old sublist contains less-used pages; these pages are
candidates for eviction.

The LRU algorithm operates as follows by default:

   * 3/8 of the buffer pool is devoted to the old sublist.

   * The midpoint of the list is the boundary where the tail of the new
     sublist meets the head of the old sublist.

   * When 'InnoDB' reads a page into the buffer pool, it initially
     inserts it at the midpoint (the head of the old sublist).  A page
     can be read in because it is required for a user-specified
     operation such as an SQL query, or as part of a read-ahead
     operation performed automatically by 'InnoDB'.

   * Accessing a page in the old sublist makes it 'young', moving it to
     the head of the buffer pool (the head of the new sublist).  If the
     page was read in because it was required, the first access occurs
     immediately and the page is made young.  If the page was read in
     due to read-ahead, the first access does not occur immediately (and
     might not occur at all before the page is evicted).

   * As the database operates, pages in the buffer pool that are not
     accessed 'age' by moving toward the tail of the list.  Pages in
     both the new and old sublists age as other pages are made new.
     Pages in the old sublist also age as pages are inserted at the
     midpoint.  Eventually, a page that remains unused for long enough
     reaches the tail of the old sublist and is evicted.

By default, pages read by queries immediately move into the new sublist,
meaning they stay in the buffer pool longer.  A table scan (such as
performed for a 'mysqldump' operation, or a 'SELECT'
statement with no 'WHERE' clause) can bring a large amount of data into
the buffer pool and evict an equivalent amount of older data, even if
the new data is never used again.  Similarly, pages that are loaded by
the read-ahead background thread and then accessed only once move to the
head of the new list.  These situations can push frequently used pages
to the old sublist, where they become subject to eviction.  For
information about optimizing this behavior, see
innodb-performance-midpoint_insertion, and
innodb-performance-read_ahead.

'InnoDB' Standard Monitor output contains several fields in the 'BUFFER
POOL AND MEMORY' section that pertain to operation of the buffer pool
LRU algorithm.  For details, see innodb-buffer-pool-monitoring.

*InnoDB Buffer Pool Configuration Options*

Several configuration options affect different aspects of the 'InnoDB'
buffer pool.

   * 'innodb_buffer_pool_size'

     Specifies the size of the buffer pool.  If the buffer pool is small
     and you have sufficient memory, making the buffer pool larger can
     improve performance by reducing the amount of disk I/O needed as
     queries access 'InnoDB' tables.  The
     'innodb_buffer_pool_size' option is dynamic, which allows you to
     configure buffer pool size without restarting the server.  See
     innodb-buffer-pool-resize for more information.

   * 'innodb_buffer_pool_chunk_size'

     Defines the chunk size for 'InnoDB' buffer pool resizing
     operations.  See innodb-buffer-pool-resize for more
     information.

   * 'innodb_buffer_pool_instances'

     Divides the buffer pool into a user-specified number of separate
     regions, each with its own LRU list and related data structures, to
     reduce contention during concurrent memory read and write
     operations.  This option only takes effect when you set
     'innodb_buffer_pool_size' to a value of 1GB or more.  The total
     size you specify is divided among all the buffer pools.  For best
     efficiency, specify a combination of 'innodb_buffer_pool_instances'
     and 'innodb_buffer_pool_size' so that each buffer pool instance is
     at least 1 gigabyte.  See innodb-multiple-buffer-pools for
     more information.

   * 'innodb_old_blocks_pct'

     Specifies the approximate percentage of the buffer pool that
     'InnoDB' uses for the old block sublist.  The range of values is 5
     to 95.  The default value is 37 (that is, 3/8 of the pool).  See
     innodb-performance-midpoint_insertion for more information.

   * 'innodb_old_blocks_time'

     Specifies how long in milliseconds (ms) a page inserted into the
     old sublist must stay there after its first access before it can be
     moved to the new sublist.  If the value is 0, a page inserted into
     the old sublist moves immediately to the new sublist the first time
     it is accessed, no matter how soon after insertion the access
     occurs.  If the value is greater than 0, pages remain in the old
     sublist until an access occurs at least that many milliseconds
     after the first access.  For example, a value of 1000 causes pages
     to stay in the old sublist for 1 second after the first access
     before they become eligible to move to the new sublist.

     Setting 'innodb_old_blocks_time' greater than 0 prevents one-time
     table scans from flooding the new sublist with pages used only for
     the scan.  Rows in a page read in for a scan are accessed many
     times in rapid succession, but the page is unused after that.  If
     'innodb_old_blocks_time' is set to a value greater than time to
     process the page, the page remains in the 'old' sublist and ages to
     the tail of the list to be evicted quickly.  This way, pages used
     only for a one-time scan do not act to the detriment of heavily
     used pages in the new sublist.

     'innodb_old_blocks_time' can be set at runtime, so you can change
     it temporarily while performing operations such as table scans and
     dumps:

          SET GLOBAL innodb_old_blocks_time = 1000;
          ... PERFORM QUERIES THAT SCAN TABLES ...
          SET GLOBAL innodb_old_blocks_time = 0;

     This strategy does not apply if your intent is to 'warm up' the
     buffer pool by filling it with a table's content.  For example,
     benchmark tests often perform a table or index scan at server
     startup, because that data would normally be in the buffer pool
     after a period of normal use.  In this case, leave
     'innodb_old_blocks_time' set to 0, at least until the warmup phase
     is complete.

     See innodb-performance-midpoint_insertion for more
     information.

   * 'innodb_read_ahead_threshold'

     Controls the sensitivity of linear read-ahead that 'InnoDB' uses to
     prefetch pages into the buffer pool.

     See innodb-performance-read_ahead for more information.

   * 'innodb_random_read_ahead'

     Enables random read-ahead technique for prefetching pages into the
     buffer pool.  Random read-ahead is a technique that predicts when
     pages might be needed soon based on pages already in the buffer
     pool, regardless of the order in which those pages were read.
     'innodb_random_read_ahead' is disabled by default.

     See innodb-performance-read_ahead for more information.

   * 'innodb_adaptive_flushing'

     Specifies whether to dynamically adjust the rate of flushing dirty
     pages in the buffer pool based on workload.  Adjusting the flush
     rate dynamically is intended to avoid bursts of I/O activity.  This
     setting is enabled by default.

     See innodb-performance-adaptive_flushing for more
     information.

   * 'innodb_adaptive_flushing_lwm'

     Low water mark representing percentage of redo log capacity at
     which adaptive flushing is enabled.

     See innodb-lru-background-flushing for more information.

   * 'innodb_flush_neighbors'

     Specifies whether flushing a page from the buffer pool also flushes
     other dirty pages in the same extent.

     See innodb-lru-background-flushing for more information.

   * 'innodb_flushing_avg_loops'

     Number of iterations for which InnoDB keeps the previously
     calculated snapshot of the flushing state, controlling how quickly
     adaptive flushing responds to changing workloads.

     See innodb-lru-background-flushing for more information.

   * 'innodb_lru_scan_depth'

     A parameter that influences the algorithms and heuristics for the
     flush operation for the buffer pool.  Primarily of interest to
     performance experts tuning I/O-intensive workloads.  It specifies,
     per buffer pool instance, how far down the buffer pool LRU list the
     'page_cleaner' thread scans looking for dirty pages to flush.

     See innodb-lru-background-flushing for more information.

   * 'innodb_max_dirty_pages_pct'

     'InnoDB' tries to flush data from the buffer pool so that the
     percentage of dirty pages does not exceed this value.  Specify an
     integer in the range from 0 to 99.  The default value is 75.

     See innodb-performance-adaptive_flushing for more
     information.

   * 'innodb_max_dirty_pages_pct_lwm'

     Low water mark representing percentage of dirty pages where
     preflushing is enabled to control the dirty page ratio.  The
     default of 0 disables the pre-flushing behavior entirely.

     See innodb-lru-background-flushing for more information.

   * 'innodb_buffer_pool_filename'

     Specifies the name of the file that holds the list of tablespace
     IDs and page IDs produced by 'innodb_buffer_pool_dump_at_shutdown'
     or 'innodb_buffer_pool_dump_now'.

     See innodb-preload-buffer-pool for more information.

   * 'innodb_buffer_pool_dump_at_shutdown'

     Specifies whether to record the pages cached in the buffer pool
     when the MySQL server is shut down, to shorten the warmup process
     at the next restart.

     See innodb-preload-buffer-pool for more information.

   * 'innodb_buffer_pool_load_at_startup'

     Specifies that, on MySQL server startup, the buffer pool is
     automatically warmed up by loading the same pages it held at an
     earlier time.  Typically used in combination with
     'innodb_buffer_pool_dump_at_shutdown'.

     See innodb-preload-buffer-pool for more information.

   * 'innodb_buffer_pool_dump_now'

     Immediately records the pages cached in the buffer pool.

     See innodb-preload-buffer-pool for more information.

   * 'innodb_buffer_pool_load_now'

     Immediately warms up the buffer pool by loading a set of data
     pages, without waiting for a server restart.  Can be useful to
     bring cache memory back to a known state during benchmarking, or to
     ready the MySQL server to resume its normal workload after running
     queries for reports or maintenance.  Typically used with
     'innodb_buffer_pool_dump_now'.

     See innodb-preload-buffer-pool for more information.

   * 'innodb_buffer_pool_dump_pct'

     Specifies the percentage of the most recently used pages for each
     buffer pool to read out and dump.  The range is 1 to 100.

     See innodb-preload-buffer-pool for more information.

   * 'innodb_buffer_pool_load_abort'

     Interrupts the process of restoring buffer pool contents triggered
     by 'innodb_buffer_pool_load_at_startup' or
     'innodb_buffer_pool_load_now'.

     See innodb-preload-buffer-pool for more information.

14.6.3.2 Configuring InnoDB Buffer Pool Size
............................................

You can configure 'InnoDB' buffer pool size offline (at startup) or
online, while the server is running.  Behavior described in this section
applies to both methods.  For additional information about configuring
buffer pool size online, see innodb-buffer-pool-online-resize.

When increasing or decreasing 'innodb_buffer_pool_size', the operation
is performed in chunks.  Chunk size is defined by the
'innodb_buffer_pool_chunk_size' configuration option, which has a
default of '128M'.  For more information, see
innodb-buffer-pool-chunk-size.

Buffer pool size must always be equal to or a multiple of
'innodb_buffer_pool_chunk_size' * 'innodb_buffer_pool_instances'.  If
you configure 'innodb_buffer_pool_size' to a value that is not equal to
or a multiple of 'innodb_buffer_pool_chunk_size' *
'innodb_buffer_pool_instances', buffer pool size is automatically
adjusted to a value that is equal to or a multiple of
'innodb_buffer_pool_chunk_size' * 'innodb_buffer_pool_instances' that is
not less than the specified buffer pool size.

In the following example, 'innodb_buffer_pool_size' is set to '8G', and
'innodb_buffer_pool_instances' is set to '16'.
'innodb_buffer_pool_chunk_size' is '128M', which is the default value.

'8G' is a valid 'innodb_buffer_pool_size' value because '8G' is a
multiple of 'innodb_buffer_pool_instances=16' *
'innodb_buffer_pool_chunk_size=128M', which is '2G'.

     shell> mysqld --innodb_buffer_pool_size=8G --innodb_buffer_pool_instances=16

     mysql> SELECT @@innodb_buffer_pool_size/1024/1024/1024;
     +------------------------------------------+
     | @@innodb_buffer_pool_size/1024/1024/1024 |
     +------------------------------------------+
     |                           8.000000000000 |
     +------------------------------------------+

In this example, 'innodb_buffer_pool_size' is set to '9G', and
'innodb_buffer_pool_instances' is set to '16'.
'innodb_buffer_pool_chunk_size' is '128M', which is the default value.
In this case, '9G' is not a multiple of
'innodb_buffer_pool_instances=16' *
'innodb_buffer_pool_chunk_size=128M', so 'innodb_buffer_pool_size' is
adjusted to '10G', which is the next multiple of
'innodb_buffer_pool_chunk_size' * 'innodb_buffer_pool_instances' that is
not less than the specified buffer pool size.

     shell> mysqld --innodb_buffer_pool_size=9G --innodb_buffer_pool_instances=16

     mysql> SELECT @@innodb_buffer_pool_size/1024/1024/1024;
     +------------------------------------------+
     | @@innodb_buffer_pool_size/1024/1024/1024 |
     +------------------------------------------+
     |                          10.000000000000 |
     +------------------------------------------+

*Configuring InnoDB Buffer Pool Chunk Size*

'innodb_buffer_pool_chunk_size' can be increased or decreased in 1MB
(1048576 byte) units but can only be modified at startup, in a command
line string or in a MySQL configuration file.

Command line:

     shell> mysqld --innodb_buffer_pool_chunk_size=134217728

Configuration file:

     [mysqld]
     innodb_buffer_pool_chunk_size=134217728

The following conditions apply when altering
'innodb_buffer_pool_chunk_size':

   * If the new ' innodb_buffer_pool_chunk_size' value *
     'innodb_buffer_pool_instances' is larger than the current buffer
     pool size when the buffer pool is initialized,
     'innodb_buffer_pool_chunk_size' is truncated to
     'innodb_buffer_pool_size' / 'innodb_buffer_pool_instances'.

     For example, if the buffer pool is initialized with a size of '2GB'
     (2147483648 bytes), '4' buffer pool instances, and a chunk size of
     '1GB' (1073741824 bytes), chunk size is truncated to a value equal
     to 'innodb_buffer_pool_size' / 'innodb_buffer_pool_instances', as
     shown below:

          shell> mysqld --innodb_buffer_pool_size=2147483648 --innodb_buffer_pool_instances=4
          --innodb_buffer_pool_chunk_size=1073741824;

          mysql> SELECT @@innodb_buffer_pool_size;
          +---------------------------+
          | @@innodb_buffer_pool_size |
          +---------------------------+
          |                2147483648 |
          +---------------------------+

          mysql> SELECT @@innodb_buffer_pool_instances;
          +--------------------------------+
          | @@innodb_buffer_pool_instances |
          +--------------------------------+
          |                              4 |
          +--------------------------------+

          # Chunk size was set to 1GB (1073741824 bytes) on startup but was
          # truncated to innodb_buffer_pool_size / innodb_buffer_pool_instances

          mysql> SELECT @@innodb_buffer_pool_chunk_size;
          +---------------------------------+
          | @@innodb_buffer_pool_chunk_size |
          +---------------------------------+
          |                       536870912 |
          +---------------------------------+

   * Buffer pool size must always be equal to or a multiple of
     'innodb_buffer_pool_chunk_size' * 'innodb_buffer_pool_instances'.
     If you alter 'innodb_buffer_pool_chunk_size',
     'innodb_buffer_pool_size' is automatically adjusted to a value that
     is equal to or a multiple of 'innodb_buffer_pool_chunk_size' *
     'innodb_buffer_pool_instances' that is not less than current buffer
     pool size.  The adjustment occurs when the buffer pool is
     initialized.  This behavior is demonstrated in the following
     example:

          # The buffer pool has a default size of 128MB (134217728 bytes)

          mysql> SELECT @@innodb_buffer_pool_size;
          +---------------------------+
          | @@innodb_buffer_pool_size |
          +---------------------------+
          |                 134217728 |
          +---------------------------+

          # The chunk size is also 128MB (134217728 bytes)

          mysql> SELECT @@innodb_buffer_pool_chunk_size;
          +---------------------------------+
          | @@innodb_buffer_pool_chunk_size |
          +---------------------------------+
          |                       134217728 |
          +---------------------------------+

          # There is a single buffer pool instance

          mysql> SELECT @@innodb_buffer_pool_instances;
          +--------------------------------+
          | @@innodb_buffer_pool_instances |
          +--------------------------------+
          |                              1 |
          +--------------------------------+

          # Chunk size is decreased by 1MB (1048576 bytes) at startup
          # (134217728 - 1048576 = 133169152):

          shell> mysqld --innodb_buffer_pool_chunk_size=133169152

          mysql> SELECT @@innodb_buffer_pool_chunk_size;
          +---------------------------------+
          | @@innodb_buffer_pool_chunk_size |
          +---------------------------------+
          |                       133169152 |
          +---------------------------------+

          # Buffer pool size increases from 134217728 to 266338304
          # Buffer pool size is automatically adjusted to a value that is equal to
          # or a multiple of innodb_buffer_pool_chunk_size * innodb_buffer_pool_instances
          # that is not less than current buffer pool size

          mysql> SELECT @@innodb_buffer_pool_size;
          +---------------------------+
          | @@innodb_buffer_pool_size |
          +---------------------------+
          |                 266338304 |
          +---------------------------+

     This example demonstrates the same behavior but with multiple
     buffer pool instances:

          # The buffer pool has a default size of 2GB (2147483648 bytes)

          mysql> SELECT @@innodb_buffer_pool_size;
          +---------------------------+
          | @@innodb_buffer_pool_size |
          +---------------------------+
          |                2147483648 |
          +---------------------------+

          # The chunk size is .5 GB (536870912 bytes)

          mysql> SELECT @@innodb_buffer_pool_chunk_size;
          +---------------------------------+
          | @@innodb_buffer_pool_chunk_size |
          +---------------------------------+
          |                       536870912 |
          +---------------------------------+

          # There are 4 buffer pool instances

          mysql> SELECT @@innodb_buffer_pool_instances;
          +--------------------------------+
          | @@innodb_buffer_pool_instances |
          +--------------------------------+
          |                              4 |
          +--------------------------------+

          # Chunk size is decreased by 1MB (1048576 bytes) at startup
          # (536870912 - 1048576 = 535822336):

          shell> mysqld --innodb_buffer_pool_chunk_size=535822336

          mysql> SELECT @@innodb_buffer_pool_chunk_size;
          +---------------------------------+
          | @@innodb_buffer_pool_chunk_size |
          +---------------------------------+
          |                       535822336 |
          +---------------------------------+

          # Buffer pool size increases from 2147483648 to 4286578688
          # Buffer pool size is automatically adjusted to a value that is equal to
          # or a multiple of innodb_buffer_pool_chunk_size * innodb_buffer_pool_instances
          # that is not less than current buffer pool size of 2147483648

          mysql> SELECT @@innodb_buffer_pool_size;
          +---------------------------+
          | @@innodb_buffer_pool_size |
          +---------------------------+
          |                4286578688 |
          +---------------------------+

     Care should be taken when changing 'innodb_buffer_pool_chunk_size',
     as changing this value can increase the size of the buffer pool, as
     shown in the examples above.  Before you change
     'innodb_buffer_pool_chunk_size', calculate the effect on
     'innodb_buffer_pool_size' to ensure that the resulting buffer pool
     size is acceptable.

*Note*:

To avoid potential performance issues, the number of chunks
('innodb_buffer_pool_size' / 'innodb_buffer_pool_chunk_size') should not
exceed 1000.

*Configuring InnoDB Buffer Pool Size Online*

The 'innodb_buffer_pool_size' configuration option can be set
dynamically using a 'SET' statement, allowing you to resize
the buffer pool without restarting the server.  For example:

     mysql> SET GLOBAL innodb_buffer_pool_size=402653184;

Active transactions and operations performed through 'InnoDB' APIs
should be completed before resizing the buffer pool.  When initiating a
resizing operation, the operation does not start until all active
transactions are completed.  Once the resizing operation is in progress,
new transactions and operations that require access to the buffer pool
must wait until the resizing operation finishes.  The exception to the
rule is that concurrent access to the buffer pool is permitted while the
buffer pool is defragmented and pages are withdrawn when buffer pool
size is decreased.  A drawback of allowing concurrent access is that it
could result in a temporary shortage of available pages while pages are
being withdrawn.

*Note*:

Nested transactions could fail if initiated after the buffer pool
resizing operation begins.

*Monitoring Online Buffer Pool Resizing Progress*

The 'Innodb_buffer_pool_resize_status' reports buffer pool resizing
progress.  For example:

     mysql> SHOW STATUS WHERE Variable_name='InnoDB_buffer_pool_resize_status';
     +----------------------------------+----------------------------------+
     | Variable_name                    | Value                            |
     +----------------------------------+----------------------------------+
     | Innodb_buffer_pool_resize_status | Resizing also other hash tables. |
     +----------------------------------+----------------------------------+

Buffer pool resizing progress is also logged in the server error log.
This example shows notes that are logged when increasing the size of the
buffer pool:

     [Note] InnoDB: Resizing buffer pool from 134217728 to 4294967296. (unit=134217728)
     [Note] InnoDB: disabled adaptive hash index.
     [Note] InnoDB: buffer pool 0 : 31 chunks (253952 blocks) was added.
     [Note] InnoDB: buffer pool 0 : hash tables were resized.
     [Note] InnoDB: Resized hash tables at lock_sys, adaptive hash index, dictionary.
     [Note] InnoDB: completed to resize buffer pool from 134217728 to 4294967296.
     [Note] InnoDB: re-enabled adaptive hash index.

This example shows notes that are logged when decreasing the size of the
buffer pool:

     [Note] InnoDB: Resizing buffer pool from 4294967296 to 134217728. (unit=134217728)
     [Note] InnoDB: disabled adaptive hash index.
     [Note] InnoDB: buffer pool 0 : start to withdraw the last 253952 blocks.
     [Note] InnoDB: buffer pool 0 : withdrew 253952 blocks from free list. tried to relocate 0 pages.
     (253952/253952)
     [Note] InnoDB: buffer pool 0 : withdrawn target 253952 blocks.
     [Note] InnoDB: buffer pool 0 : 31 chunks (253952 blocks) was freed.
     [Note] InnoDB: buffer pool 0 : hash tables were resized.
     [Note] InnoDB: Resized hash tables at lock_sys, adaptive hash index, dictionary.
     [Note] InnoDB: completed to resize buffer pool from 4294967296 to 134217728.
     [Note] InnoDB: re-enabled adaptive hash index.

*Online Buffer Pool Resizing Internals*

The resizing operation is performed by a background thread.  When
increasing the size of the buffer pool, the resizing operation:

   * Adds pages in 'chunks' (chunk size is defined by
     'innodb_buffer_pool_chunk_size')

   * Coverts hash tables, lists, and pointers to use new addresses in
     memory

   * Adds new pages to the free list

While these operations are in progress, other threads are blocked from
accessing the buffer pool.

When decreasing the size of the buffer pool, the resizing operation:

   * Defragments the buffer pool and withdraws (frees) pages

   * Removes pages in 'chunks' (chunk size is defined by
     'innodb_buffer_pool_chunk_size')

   * Converts hash tables, lists, and pointers to use new addresses in
     memory

Of these operations, only defragmenting the buffer pool and withdrawing
pages allow other threads to access to the buffer pool concurrently.

14.6.3.3 Configuring Multiple Buffer Pool Instances
...................................................

For systems with buffer pools in the multi-gigabyte range, dividing the
buffer pool into separate instances can improve concurrency, by reducing
contention as different threads read and write to cached pages.  This
feature is typically intended for systems with a buffer pool size in the
multi-gigabyte range.  Multiple buffer pool instances are configured
using the 'innodb_buffer_pool_instances' configuration option, and you
might also adjust the 'innodb_buffer_pool_size' value.

When the 'InnoDB' buffer pool is large, many data requests can be
satisfied by retrieving from memory.  You might encounter bottlenecks
from multiple threads trying to access the buffer pool at once.  You can
enable multiple buffer pools to minimize this contention.  Each page
that is stored in or read from the buffer pool is assigned to one of the
buffer pools randomly, using a hashing function.  Each buffer pool
manages its own free lists, flush lists, LRUs, and all other data
structures connected to a buffer pool, and is protected by its own
buffer pool mutex.

To enable multiple buffer pool instances, set the
'innodb_buffer_pool_instances' configuration option to a value greater
than 1 (the default) up to 64 (the maximum).  This option takes effect
only when you set 'innodb_buffer_pool_size' to a size of 1GB or more.
The total size you specify is divided among all the buffer pools.  For
best efficiency, specify a combination of 'innodb_buffer_pool_instances'
and 'innodb_buffer_pool_size' so that each buffer pool instance is at
least 1GB.

For information about modifying 'InnoDB' buffer pool size, see
innodb-buffer-pool-resize.

14.6.3.4 Making the Buffer Pool Scan Resistant
..............................................

Rather than using a strict LRU algorithm, 'InnoDB' uses a technique to
minimize the amount of data that is brought into the buffer pool and
never accessed again.  The goal is to make sure that frequently accessed
('hot') pages remain in the buffer pool, even as read-ahead and full
table scans bring in new blocks that might or might not be accessed
afterward.

Newly read blocks are inserted into the middle of the LRU list.  All
newly read pages are inserted at a location that by default is '3/8'
from the tail of the LRU list.  The pages are moved to the front of the
list (the most-recently used end) when they are accessed in the buffer
pool for the first time.  Thus, pages that are never accessed never make
it to the front portion of the LRU list, and 'age out' sooner than with
a strict LRU approach.  This arrangement divides the LRU list into two
segments, where the pages downstream of the insertion point are
considered 'old' and are desirable victims for LRU eviction.

For an explanation of the inner workings of the 'InnoDB' buffer pool and
specifics about the LRU algorithm, see innodb-buffer-pool.

You can control the insertion point in the LRU list and choose whether
'InnoDB' applies the same optimization to blocks brought into the buffer
pool by table or index scans.  The configuration parameter
'innodb_old_blocks_pct' controls the percentage of 'old' blocks in the
LRU list.  The default value of 'innodb_old_blocks_pct' is '37',
corresponding to the original fixed ratio of 3/8.  The value range is
'5' (new pages in the buffer pool age out very quickly) to '95' (only 5%
of the buffer pool is reserved for hot pages, making the algorithm close
to the familiar LRU strategy).

The optimization that keeps the buffer pool from being churned by
read-ahead can avoid similar problems due to table or index scans.  In
these scans, a data page is typically accessed a few times in quick
succession and is never touched again.  The configuration parameter
'innodb_old_blocks_time' specifies the time window (in milliseconds)
after the first access to a page during which it can be accessed without
being moved to the front (most-recently used end) of the LRU list.  The
default value of 'innodb_old_blocks_time' is '1000'.  Increasing this
value makes more and more blocks likely to age out faster from the
buffer pool.

Both 'innodb_old_blocks_pct' and 'innodb_old_blocks_time' are dynamic,
global and can be specified in the MySQL option file ('my.cnf' or
'my.ini') or changed at runtime with the 'SET GLOBAL' command.  Changing
the setting requires the 'SUPER' privilege.

To help you gauge the effect of setting these parameters, the 'SHOW
ENGINE INNODB STATUS' command reports buffer pool statistics.  For
details, see innodb-buffer-pool-monitoring.

Because the effects of these parameters can vary widely based on your
hardware configuration, your data, and the details of your workload,
always benchmark to verify the effectiveness before changing these
settings in any performance-critical or production environment.

In mixed workloads where most of the activity is OLTP type with periodic
batch reporting queries which result in large scans, setting the value
of 'innodb_old_blocks_time' during the batch runs can help keep the
working set of the normal workload in the buffer pool.

When scanning large tables that cannot fit entirely in the buffer pool,
setting 'innodb_old_blocks_pct' to a small value keeps the data that is
only read once from consuming a significant portion of the buffer pool.
For example, setting 'innodb_old_blocks_pct=5' restricts this data that
is only read once to 5% of the buffer pool.

When scanning small tables that do fit into memory, there is less
overhead for moving pages around within the buffer pool, so you can
leave 'innodb_old_blocks_pct' at its default value, or even higher, such
as 'innodb_old_blocks_pct=50'.

The effect of the 'innodb_old_blocks_time' parameter is harder to
predict than the 'innodb_old_blocks_pct' parameter, is relatively small,
and varies more with the workload.  To arrive at an optimal value,
conduct your own benchmarks if the performance improvement from
adjusting 'innodb_old_blocks_pct' is not sufficient.

14.6.3.5 Configuring InnoDB Buffer Pool Prefetching (Read-Ahead)
................................................................

A read-ahead request is an I/O request to prefetch multiple pages in the
buffer pool asynchronously, in anticipation that these pages will be
needed soon.  The requests bring in all the pages in one extent.
'InnoDB' uses two read-ahead algorithms to improve I/O performance:

_Linear_ read-ahead is a technique that predicts what pages might be
needed soon based on pages in the buffer pool being accessed
sequentially.  You control when 'InnoDB 'performs a read-ahead operation
by adjusting the number of sequential page accesses required to trigger
an asynchronous read request, using the configuration parameter
'innodb_read_ahead_threshold'.  Before this parameter was added,
'InnoDB' would only calculate whether to issue an asynchronous prefetch
request for the entire next extent when it read in the last page of the
current extent.

The configuration parameter 'innodb_read_ahead_threshold' controls how
sensitive 'InnoDB' is in detecting patterns of sequential page access.
If the number of pages read sequentially from an extent is greater than
or equal to 'innodb_read_ahead_threshold', 'InnoDB' initiates an
asynchronous read-ahead operation of the entire following extent.
'innodb_read_ahead_threshold' can be set to any value from 0-64.  The
default value is 56.  The higher the value, the more strict the access
pattern check.  For example, if you set the value to 48, 'InnoDB'
triggers a linear read-ahead request only when 48 pages in the current
extent have been accessed sequentially.  If the value is 8, 'InnoDB'
triggers an asynchronous read-ahead even if as few as 8 pages in the
extent are accessed sequentially.  You can set the value of this
parameter in the MySQL configuration file, or change it dynamically with
the 'SET GLOBAL' command, which requires the 'SUPER' privilege.

_Random_ read-ahead is a technique that predicts when pages might be
needed soon based on pages already in the buffer pool, regardless of the
order in which those pages were read.  If 13 consecutive pages from the
same extent are found in the buffer pool, 'InnoDB' asynchronously issues
a request to prefetch the remaining pages of the extent.  To enable this
feature, set the configuration variable 'innodb_random_read_ahead' to
'ON'.

The 'SHOW ENGINE INNODB STATUS' command displays statistics to help you
evaluate the effectiveness of the read-ahead algorithm.  Statistics
include counter information for the following global status variables:

   * 'Innodb_buffer_pool_read_ahead'

   * 'Innodb_buffer_pool_read_ahead_evicted'

   * 'Innodb_buffer_pool_read_ahead_rnd'

This information can be useful when fine-tuning the
'innodb_random_read_ahead' setting.

For more information about I/O performance, see
optimizing-innodb-diskio and disk-issues.

14.6.3.6 Configuring InnoDB Buffer Pool Flushing
................................................

'InnoDB' performs certain tasks in the background, including flushing of
dirty pages (those pages that have been changed but are not yet written
to the database files) from the buffer pool.

'InnoDB' starts flushing buffer pool pages when the percentage of dirty
pages in the buffer pool reaches the low water mark setting defined by
'innodb_max_dirty_pages_pct_lwm'.  This option is intended to control
the ratio of dirty pages in the buffer pool and ideally prevent the
percentage of dirty pages from reaching 'innodb_max_dirty_pages_pct'.
If the percentage of dirty pages in the buffer pool exceeds
'innodb_max_dirty_pages_pct', 'InnoDB' begins to aggressively flush
buffer pool pages.

'InnoDB' uses an algorithm to estimate the required rate of flushing,
based on the speed of redo log generation and the current rate of
flushing.  The intent is to smooth overall performance by ensuring that
buffer flush activity keeps up with the need to keep the buffer pool
'clean'.  Automatically adjusting the rate of flushing can help to avoid
sudden dips in throughput, when excessive buffer pool flushing limits
the I/O capacity available for ordinary read and write activity.

'InnoDB' uses its log files in a circular fashion.  Before reusing a
portion of a log file, 'InnoDB' flushes to disk all dirty buffer pool
pages whose redo entries are contained in that portion of the log file,
a process known as a sharp checkpoint.  If a workload is
write-intensive, it generates a lot of redo information, all written to
the log file.  If all available space in the log files is used up, a
sharp checkpoint occurs, causing a temporary reduction in throughput.
This situation can happen even if 'innodb_max_dirty_pages_pct' is not
reached.

'InnoDB' uses a heuristic-based algorithm to avoid such a scenario, by
measuring the number of dirty pages in the buffer pool and the rate at
which redo is being generated.  Based on these numbers, 'InnoDB' decides
how many dirty pages to flush from the buffer pool each second.  This
self-adapting algorithm is able to deal with sudden changes in workload.

Internal benchmarking has shown that this algorithm not only maintains
throughput over time, but can also improve overall throughput
significantly.

Because adaptive flushing can significantly affect the I/O pattern of a
workload, the 'innodb_adaptive_flushing' configuration parameter lets
you turn off this feature.  The default value for
'innodb_adaptive_flushing' is 'ON', enabling the adaptive flushing
algorithm.  You can set the value of this parameter in the MySQL option
file ('my.cnf' or 'my.ini') or change it dynamically with the 'SET
GLOBAL' command, which requires the 'SUPER' privilege.

For information about fine-tuning 'InnoDB' buffer pool flushing
behavior, see innodb-lru-background-flushing.

For more information about 'InnoDB' I/O performance, see
optimizing-innodb-diskio.

14.6.3.7 Fine-tuning InnoDB Buffer Pool Flushing
................................................

The configuration options 'innodb_flush_neighbors' and
'innodb_lru_scan_depth' let you fine-tune aspects of the flushing
process for the 'InnoDB' buffer pool.

   * 'innodb_flush_neighbors'

     Specifies whether flushing a page from the buffer pool also flushes
     other dirty pages in the same extent.  When the table data is
     stored on a traditional HDD storage device, flushing neighbor pages
     in one operation reduces I/O overhead (primarily for disk seek
     operations) compared to flushing individual pages at different
     times.  For table data stored on SSD, seek time is not a
     significant factor and you can disable this setting to spread out
     write operations.

   * 'innodb_lru_scan_depth'

     Specifies, per buffer pool instance, how far down the buffer pool
     LRU list the page cleaner thread scans looking for dirty pages to
     flush.  This is a background operation performed once per second.

These options primarily help write-intensive workloads.  With heavy DML
activity, flushing can fall behind if it is not aggressive enough,
resulting in excessive memory use in the buffer pool; or, disk writes
due to flushing can saturate your I/O capacity if that mechanism is too
aggressive.  The ideal settings depend on your workload, data access
patterns, and storage configuration (for example, whether data is stored
on HDD or SSD devices).

For systems with constant heavy workloads, or workloads that fluctuate
widely, several configuration options let you fine-tune the flushing
behavior for 'InnoDB' tables:

   * 'innodb_adaptive_flushing_lwm'

   * 'innodb_max_dirty_pages_pct_lwm'

   * 'innodb_io_capacity_max'

   * 'innodb_flushing_avg_loops'

These options feed into the formula used by the
'innodb_adaptive_flushing' option.

The 'innodb_adaptive_flushing', 'innodb_io_capacity' and
'innodb_max_dirty_pages_pct' options are limited or extended by the
following options:

   * 'innodb_adaptive_flushing_lwm'

   * 'innodb_io_capacity_max'

   * 'innodb_max_dirty_pages_pct_lwm'

The 'InnoDB' adaptive flushing mechanism is not appropriate in all
cases.  It gives the most benefit when the redo log is in danger of
filling up.  The 'innodb_adaptive_flushing_lwm' option specifies a 'low
water mark' percentage of redo log capacity; when that threshold is
crossed, 'InnoDB' turns on adaptive flushing even if not specified by
the 'innodb_adaptive_flushing' option.

If flushing activity falls far behind, 'InnoDB' can flush more
aggressively than specified by 'innodb_io_capacity'.
'innodb_io_capacity_max' represents an upper limit on the I/O capacity
used in such emergency situations, so that the spike in I/O does not
consume all the capacity of the server.

'InnoDB' tries to flush data from the buffer pool so that the percentage
of dirty pages does not exceed the value of
'innodb_max_dirty_pages_pct'.  The default value for
'innodb_max_dirty_pages_pct' is 75.

*Note*:

The 'innodb_max_dirty_pages_pct' setting establishes a target for
flushing activity.  It does not affect the rate of flushing.  For
information about managing the rate of flushing, see
innodb-performance-adaptive_flushing.

The 'innodb_max_dirty_pages_pct_lwm' option specifies a 'low water mark'
value that represents the percentage of dirty pages where pre-flushing
is enabled to control the dirty page ratio and ideally prevent the
percentage of dirty pages from reaching 'innodb_max_dirty_pages_pct'.  A
value of 'innodb_max_dirty_pages_pct_lwm=0' disables the 'pre-flushing'
behavior.

Most of the options referenced above are most applicable to servers that
run write-heavy workloads for long periods of time and have little
reduced load time to catch up with changes waiting to be written to
disk.

'innodb_flushing_avg_loops' defines the number of iterations for which
'InnoDB' keeps the previously calculated snapshot of the flushing state,
which controls how quickly adaptive flushing responds to foreground load
changes.  Setting a high value for 'innodb_flushing_avg_loops' means
that 'InnoDB' keeps the previously calculated snapshot longer, so
adaptive flushing responds more slowly.  A high value also reduces
positive feedback between foreground and background work, but when
setting a high value it is important to ensure that 'InnoDB' redo log
utilization does not reach 75% (the hardcoded limit at which async
flushing starts) and that the 'innodb_max_dirty_pages_pct' setting keeps
the number of dirty pages to a level that is appropriate for the
workload.

Systems with consistent workloads, a large 'innodb_log_file_size', and
small spikes that do not reach 75% redo log space utilization should use
a high 'innodb_flushing_avg_loops' value to keep flushing as smooth as
possible.  For systems with extreme load spikes or log files that do not
provide a lot of space, consider a smaller 'innodb_flushing_avg_loops'
value.  A smaller value allows flushing to closely track the load and
helps avoid reaching 75% redo log space utilization.

14.6.3.8 Saving and Restoring the Buffer Pool State
...................................................

To reduce the warmup period after restarting the server, 'InnoDB' saves
a percentage of the most recently used pages for each buffer pool at
server shutdown and restores these pages at server startup.  The
percentage of recently used pages that is stored is defined by the
'innodb_buffer_pool_dump_pct' configuration option.

After restarting a busy server, there is typically a warmup period with
steadily increasing throughput, as disk pages that were in the buffer
pool are brought back into memory (as the same data is queried, updated,
and so on).  The ability to restore the buffer pool at startup shortens
the warmup period by reloading disk pages that were in the buffer pool
before the restart rather than waiting for DML operations to access
corresponding rows.  Also, I/O requests can be performed in large
batches, making the overall I/O faster.  Page loading happens in the
background, and does not delay database startup.

In addition to saving the buffer pool state at shutdown and restoring it
at startup, you can save and restore the buffer pool state at any time,
while the server is running.  For example, you can save the state of the
buffer pool after reaching a stable throughput under a steady workload.
You could also restore the previous buffer pool state after running
reports or maintenance jobs that bring data pages into the buffer pool
that are only requited for those operations, or after running some other
non-typical workload.

Even though a buffer pool can be many gigabytes in size, the buffer pool
data that 'InnoDB' saves to disk is tiny by comparison.  Only tablespace
IDs and page IDs necessary to locate the appropriate pages are saved to
disk.  This information is derived from the
'INNODB_BUFFER_PAGE_LRU'.
'INFORMATION_SCHEMA' table.  By default, tablespace ID and page ID data
is saved in a file named 'ib_buffer_pool', which is saved to the
'InnoDB' data directory.  The file name and location can be modified
using the 'innodb_buffer_pool_filename' configuration parameter.

Because data is cached in and aged out of the buffer pool as it is with
regular database operations, there is no problem if the disk pages are
recently updated, or if a DML operation involves data that has not yet
been loaded.  The loading mechanism skips requested pages that no longer
exist.

The underlying mechanism involves a background thread that is dispatched
to perform the dump and load operations.

Disk pages from compressed tables are loaded into the buffer pool in
their compressed form.  Pages are uncompressed as usual when page
contents are accessed during DML operations.  Because uncompressing
pages is a CPU-intensive process, it is more efficient for concurrency
to perform the operation in a connection thread rather than in the
single thread that performs the buffer pool restore operation.

Operations related to saving and restoring the buffer pool state are
described in the following topics:

   * innodb-preload-buffer-pool-dump-pct

   * innodb-preload-buffer-pool-offline

   * innodb-preload-buffer-pool-online

   * innodb-preload-buffer-pool-dump-progress

   * innodb-preload-buffer-pool-load-progress

   * innodb-preload-buffer-pool-abort-load

   * monitor-buffer-pool-load-performance-schema

*Configuring the Dump Percentage for Buffer Pool Pages*

Before dumping pages from the buffer pool, you can configure the
percentage of most-recently-used buffer pool pages that you want to dump
by setting the 'innodb_buffer_pool_dump_pct' option.  If you plan to
dump buffer pool pages while the server is running, you can configure
the option dynamically:

     SET GLOBAL innodb_buffer_pool_dump_pct=40;

If you plan to dump buffer pool pages at server shutdown, set
'innodb_buffer_pool_dump_pct' in your configuration file.

     [mysqld]
     innodb_buffer_pool_dump_pct=40

The 'innodb_buffer_pool_dump_pct' default value was changed from 100
(dump all pages) to 25 (dump 25% of most-recently-used pages) in MySQL
5.7 when 'innodb_buffer_pool_dump_at_shutdown' and
'innodb_buffer_pool_load_at_startup' were enabled by default.

*Saving the Buffer Pool State at Shutdown and Restoring it at Startup*

To save the state of the buffer pool at server shutdown, issue the
following statement prior to shutting down the server:

     SET GLOBAL innodb_buffer_pool_dump_at_shutdown=ON;

'innodb_buffer_pool_dump_at_shutdown' is enabled by default.

To restore the buffer pool state at server startup, specify the
'--innodb_buffer_pool_load_at_startup' option when starting the server:

     mysqld --innodb_buffer_pool_load_at_startup=ON;

'innodb_buffer_pool_load_at_startup' is enabled by default.

*Saving and Restoring the Buffer Pool State Online*

To save the state of the buffer pool while MySQL server is running,
issue the following statement:

     SET GLOBAL innodb_buffer_pool_dump_now=ON;

To restore the buffer pool state while MySQL is running, issue the
following statement:

     SET GLOBAL innodb_buffer_pool_load_now=ON;

*Displaying Buffer Pool Dump Progress*

To display progress when saving the buffer pool state to disk, issue the
following statement:

     SHOW STATUS LIKE 'Innodb_buffer_pool_dump_status';

If the operation has not yet started, 'not started' is returned.  If the
operation is complete, the completion time is printed (e.g.  Finished at
110505 12:18:02).  If the operation is in progress, status information
is provided (e.g.  Dumping buffer pool 5/7, page 237/2873).

*Displaying Buffer Pool Load Progress*

To display progress when loading the buffer pool, issue the following
statement:

     SHOW STATUS LIKE 'Innodb_buffer_pool_load_status';

If the operation has not yet started, 'not started' is returned.  If the
operation is complete, the completion time is printed (e.g.  Finished at
110505 12:23:24).  If the operation is in progress, status information
is provided (e.g.  Loaded 123/22301 pages).

*Aborting a Buffer Pool Load Operation*

To abort a buffer pool load operation, issue the following statement:

     SET GLOBAL innodb_buffer_pool_load_abort=ON;

*Monitoring Buffer Pool Load Progress Using Performance Schema*

You can monitor buffer pool load progress using Performance Schema.

The following example demonstrates how to enable the
'stage/innodb/buffer pool load' stage event instrument and related
consumer tables to monitor buffer pool load progress.

For information about buffer pool dump and load procedures used in this
example, see innodb-preload-buffer-pool.  For information about
Performance Schema stage event instruments and related consumers, see
performance-schema-stage-tables.

  1. Enable the 'stage/innodb/buffer pool load' instrument:

          mysql> UPDATE performance_schema.setup_instruments SET ENABLED = 'YES'
                 WHERE NAME LIKE 'stage/innodb/buffer%';

  2. Enable the stage event consumer tables, which include
     'events_stages_current',
     'events_stages_history', and
     'events_stages_history_long'.

          mysql> UPDATE performance_schema.setup_consumers SET ENABLED = 'YES'
                 WHERE NAME LIKE '%stages%';

  3. Dump the current buffer pool state by enabling
     'innodb_buffer_pool_dump_now'.

          mysql> SET GLOBAL innodb_buffer_pool_dump_now=ON;

  4. Check the buffer pool dump status to ensure that the operation has
     completed.

          mysql> SHOW STATUS LIKE 'Innodb_buffer_pool_dump_status'\G
          *************************** 1. row ***************************
          Variable_name: Innodb_buffer_pool_dump_status
                  Value: Buffer pool(s) dump completed at 150202 16:38:58

  5. Load the buffer pool by enabling 'innodb_buffer_pool_load_now':

          mysql> SET GLOBAL innodb_buffer_pool_load_now=ON;

  6. Check the current status of the buffer pool load operation by
     querying the Performance Schema 'events_stages_current'
     table.  The 'WORK_COMPLETED' column
     shows the number of buffer pool pages loaded.  The 'WORK_ESTIMATED'
     column provides an estimate of the remaining work, in pages.

          mysql> SELECT EVENT_NAME, WORK_COMPLETED, WORK_ESTIMATED
                 FROM performance_schema.events_stages_current;
          +-------------------------------+----------------+----------------+
          | EVENT_NAME                    | WORK_COMPLETED | WORK_ESTIMATED |
          +-------------------------------+----------------+----------------+
          | stage/innodb/buffer pool load |           5353 |           7167 |
          +-------------------------------+----------------+----------------+

     The 'events_stages_current'.
     table returns an empty set if the buffer pool load operation has
     completed.  In this case, you can check the
     'events_stages_history' table to view
     data for the completed event.  For example:

          mysql> SELECT EVENT_NAME, WORK_COMPLETED, WORK_ESTIMATED
                 FROM performance_schema.events_stages_history;
          +-------------------------------+----------------+----------------+
          | EVENT_NAME                    | WORK_COMPLETED | WORK_ESTIMATED |
          +-------------------------------+----------------+----------------+
          | stage/innodb/buffer pool load |           7167 |           7167 |
          +-------------------------------+----------------+----------------+

*Note*:

You can also monitor buffer pool load progress using Performance Schema
when loading the buffer pool at startup using
'innodb_buffer_pool_load_at_startup'.  In this case, the
'stage/innodb/buffer pool load' instrument and related consumers must be
enabled at startup.  For more information, see
performance-schema-startup-configuration.

14.6.3.9 Monitoring the Buffer Pool Using the InnoDB Standard Monitor
.....................................................................

'InnoDB' Standard Monitor output, which can be accessed using
'SHOW ENGINE INNODB STATUS', provides metrics
that pertain to operation of the 'InnoDB' buffer pool.  Buffer pool
metrics are located in the 'BUFFER POOL AND MEMORY' section of 'InnoDB'
Standard Monitor output and appear similar to the following:

     ----------------------
     BUFFER POOL AND MEMORY
     ----------------------
     Total large memory allocated 2198863872
     Dictionary memory allocated 776332
     Buffer pool size   131072
     Free buffers       124908
     Database pages     5720
     Old database pages 2071
     Modified db pages  910
     Pending reads 0
     Pending writes: LRU 0, flush list 0, single page 0
     Pages made young 4, not young 0
     0.10 youngs/s, 0.00 non-youngs/s
     Pages read 197, created 5523, written 5060
     0.00 reads/s, 190.89 creates/s, 244.94 writes/s
     Buffer pool hit rate 1000 / 1000, young-making rate 0 / 1000 not
     0 / 1000
     Pages read ahead 0.00/s, evicted without access 0.00/s, Random read
     ahead 0.00/s
     LRU len: 5720, unzip_LRU len: 0
     I/O sum[0]:cur[0], unzip sum[0]:cur[0]

The following table describes 'InnoDB' buffer pool metrics reported by
the 'InnoDB' Standard Monitor.

*Note*:

Per second averages provided in 'InnoDB' Standard Monitor output are
based on the elapsed time since 'InnoDB' Standard Monitor output was
last printed.

*InnoDB Buffer Pool Metrics*

Name                      Description

Total memory allocated    The total memory allocated for the buffer
                          pool in bytes.

Dictionary memory         The total memory allocated for the 'InnoDB'
allocated                 data dictionary in bytes.

Buffer pool size          The total size in pages allocated to the
                          buffer pool.

Free buffers              The total size in pages of the buffer pool
                          free list.

Database pages            The total size in pages of the buffer pool
                          LRU list.

Old database pages        The total size in pages of the buffer pool
                          old LRU sublist.

Modified db pages         The current number of pages modified in the
                          buffer pool.

Pending reads             The number of buffer pool pages waiting to be
                          read in to the buffer pool.

Pending writes LRU        The number of old dirty pages within the
                          buffer pool to be written from the bottom of
                          the LRU list.

Pending writes flush      The number of buffer pool pages to be flushed
list                      during checkpointing.

Pending writes single     The number of pending independent page writes
page                      within the buffer pool.

Pages made young          The total number of pages made young in the
                          buffer pool LRU list (moved to the head of
                          sublist of 'new' pages).

Pages made not young      The total number of pages not made young in
                          the buffer pool LRU list (pages that have
                          remained in the 'old' sublist without being
                          made young).

youngs/s                  The per second average of accesses to old
                          pages in the buffer pool LRU list that have
                          resulted in making pages young.  See the
                          notes that follow this table for more
                          information.

non-youngs/s              The per second average of accesses to old
                          pages in the buffer pool LRU list that have
                          resulted in not making pages young.  See the
                          notes that follow this table for more
                          information.

Pages read                The total number of pages read from the
                          buffer pool.

Pages created             The total number of pages created within the
                          buffer pool.

Pages written             The total number of pages written from the
                          buffer pool.

reads/s                   The per second average number of buffer pool
                          page reads per second.

creates/s                 The per second average number of buffer pool
                          pages created per second.

writes/s                  The per second average number of buffer pool
                          page writes per second.

Buffer pool hit rate      The buffer pool page hit rate for pages read
                          from the buffer pool memory vs from disk
                          storage.

young-making rate         The average hit rate at which page accesses
                          have resulted in making pages young.  See the
                          notes that follow this table for more
                          information.

not (young-making rate)   The average hit rate at which page accesses
                          have not resulted in making pages young.  See
                          the notes that follow this table for more
                          information.

Pages read ahead          The per second average of read ahead
                          operations.

Pages evicted without     The per second average of the pages evicted
access                    without being accessed from the buffer pool.

Random read ahead         The per second average of random read ahead
                          operations.

LRU len                   The total size in pages of the buffer pool
                          LRU list.

unzip_LRU len             The total size in pages of the buffer pool
                          unzip_LRU list.

I/O sum                   The total number of buffer pool LRU list
                          pages accessed, for the last 50 seconds.

I/O cur                   The total number of buffer pool LRU list
                          pages accessed.

I/O unzip sum             The total number of buffer pool unzip_LRU
                          list pages accessed.

I/O unzip cur             The total number of buffer pool unzip_LRU
                          list pages accessed.

*Notes*:

   * The 'youngs/s' metric only relates to old pages.  It is based on
     the number of accesses to pages and not the number of pages.  There
     can be multiple accesses to a given page, all of which are counted.
     If you see very low 'youngs/s' values when there are no large scans
     occurring, you might need to reduce the delay time or increase the
     percentage of the buffer pool used for the old sublist.  Increasing
     the percentage makes the old sublist larger, so pages in that
     sublist take longer to move to the tail and to be evicted.  This
     increases the likelihood that the pages will be accessed again and
     be made young.

   * The 'non-youngs/s' metric only relates to old pages.  It is based
     on the number of accesses to pages and not the number of pages.
     There can be multiple accesses to a given page, all of which are
     counted.  If you do not see a lot of 'non-youngs/s' when you are
     doing large table scans (and lots of 'youngs/s'), increase the
     delay value.

   * The 'young-making' rate accounts for accesses to all buffer pool
     pages, not just accesses to pages in the old sublist.  The
     'young-making' rate and 'not' rate do not normally add up to the
     overall buffer pool hit rate.  Page hits in the old sublist cause
     pages to move to the new sublist, but page hits in the new sublist
     cause pages to move to the head of the list only if they are a
     certain distance from the head.

   * 'not (young-making rate)' is the average hit rate at which page
     accesses have not resulted in making pages young due to the delay
     defined by 'innodb_old_blocks_time' not being met, or due to page
     hits in the new sublist that did not result in pages being moved to
     the head.  This rate accounts for accesses to all buffer pool
     pages, not just accesses to pages in the old sublist.

'InnoDB' buffer pool server status variables
and the 'INNODB_BUFFER_POOL_STATS'
table provide many of the same buffer
pool metrics found in 'InnoDB' Standard Monitor output.  For more
information about the 'INNODB_BUFFER_POOL_STATS'
table, see
innodb-information-schema-buffer-pool-stats-example.

14.6.4 Configuring the Memory Allocator for InnoDB
--------------------------------------------------

When 'InnoDB' was developed, the memory allocators supplied with
operating systems and run-time libraries were often lacking in
performance and scalability.  At that time, there were no memory
allocator libraries tuned for multi-core CPUs.  Therefore, 'InnoDB'
implemented its own memory allocator in the 'mem' subsystem.  This
allocator is guarded by a single mutex, which may become a bottleneck.
'InnoDB' also implements a wrapper interface around the system allocator
('malloc' and 'free') that is likewise guarded by a single mutex.

Today, as multi-core systems have become more widely available, and as
operating systems have matured, significant improvements have been made
in the memory allocators provided with operating systems.  These new
memory allocators perform better and are more scalable than they were in
the past.  Most workloads, especially those where memory is frequently
allocated and released (such as multi-table joins), benefit from using a
more highly tuned memory allocator as opposed to the internal,
'InnoDB'-specific memory allocator.

You can control whether 'InnoDB' uses its own memory allocator or an
allocator of the operating system, by setting the value of the system
configuration parameter 'innodb_use_sys_malloc' in the MySQL option file
('my.cnf' or 'my.ini').  If set to 'ON' or '1' (the default), 'InnoDB'
uses the 'malloc' and 'free' functions of the underlying system rather
than manage memory pools itself.  This parameter is not dynamic, and
takes effect only when the system is started.  To continue to use the
'InnoDB' memory allocator, set 'innodb_use_sys_malloc' to '0'.

When the 'InnoDB' memory allocator is disabled, 'InnoDB' ignores the
value of the parameter 'innodb_additional_mem_pool_size'.  The 'InnoDB'
memory allocator uses an additional memory pool for satisfying
allocation requests without having to fall back to the system memory
allocator.  When the 'InnoDB' memory allocator is disabled, all such
allocation requests are fulfilled by the system memory allocator.

On Unix-like systems that use dynamic linking, replacing the memory
allocator may be as easy as making the environment variable 'LD_PRELOAD'
or 'LD_LIBRARY_PATH' point to the dynamic library that implements the
allocator.  On other systems, some relinking may be necessary.  Please
refer to the documentation of the memory allocator library of your
choice.

Since 'InnoDB' cannot track all memory use when the system memory
allocator is used ('innodb_use_sys_malloc' is 'ON'), the section 'BUFFER
POOL AND MEMORY' in the output of the 'SHOW ENGINE INNODB STATUS'
command only includes the buffer pool statistics in the 'Total memory
allocated'.  Any memory allocated using the 'mem' subsystem or using
'ut_malloc' is excluded.

*Note*:

'innodb_use_sys_malloc' and 'innodb_additional_mem_pool_size' were
deprecated in MySQL 5.6 and removed in MySQL 5.7.

For more information about the performance implications of 'InnoDB'
memory usage, see buffering-caching.

14.6.5 Configuring InnoDB Change Buffering
------------------------------------------

When 'INSERT', 'UPDATE', and 'DELETE'
operations are performed on a table, the values of indexed
columns (particularly the values of secondary keys) are often in an
unsorted order, requiring substantial I/O to bring secondary indexes up
to date.  'InnoDB' has a change buffer that caches changes to secondary
index entries when the relevant page is not in the buffer pool, thus
avoiding expensive I/O operations by not immediately reading in the page
from disk.  The buffered changes are merged when the page is loaded to
the buffer pool, and the updated page is later flushed to disk.  The
'InnoDB' main thread merges buffered changes when the server is nearly
idle, and during a slow shutdown.

Because it can result in fewer disk reads and writes, the change buffer
feature is most valuable for workloads that are I/O-bound, for example
applications with a high volume of DML operations such as bulk inserts.

However, the change buffer occupies a part of the buffer pool, reducing
the memory available to cache data pages.  If the working set almost
fits in the buffer pool, or if your tables have relatively few secondary
indexes, it may be useful to disable change buffering.  If the working
set fits entirely within the buffer, change buffering does not impose
extra overhead, because it only applies to pages that are not in the
buffer pool.

You can control the extent to which 'InnoDB' performs change buffering
using the 'innodb_change_buffering' configuration parameter.  You can
enable or disable buffering for inserts, delete operations (when index
records are initially marked for deletion) and purge operations (when
index records are physically deleted).  An update operation is a
combination of an insert and a delete.  The default
'innodb_change_buffering' value is 'all'.

Permitted 'innodb_change_buffering' values include:

   * *'all'*

     The default value: buffer inserts, delete-marking operations, and
     purges.

   * *'none'*

     Do not buffer any operations.

   * *'inserts'*

     Buffer insert operations.

   * *'deletes'*

     Buffer delete-marking operations.

   * *'changes'*

     Buffer both inserts and delete-marking operations.

   * *'purges'*

     Buffer the physical deletion operations that happen in the
     background.

You can set the 'innodb_change_buffering' parameter in the MySQL option
file ('my.cnf' or 'my.ini') or change it dynamically with the 'SET GLOBAL'
command, which requires the 'SUPER' privilege.
Changing the setting affects the buffering of new operations; the
merging of existing buffered entries is not affected.

For related information, see innodb-insert-buffering.  For
information about configuring change buffer size, see
innodb-change-buffer-maximum-size.

14.6.5.1 Configuring the Change Buffer Maximum Size
...................................................

As of MySQL 5.6.2, the 'innodb_change_buffer_max_size' configuration
option allows you to configure the maximum size of the change buffer as
a percentage of the total size of the buffer pool.  By default,
'innodb_change_buffer_max_size' is set to 25.  The maximum setting is
50.

You might consider increasing 'innodb_change_buffer_max_size' on a MySQL
server with heavy insert, update, and delete activity, where change
buffer merging does not keep pace with new change buffer entries,
causing the change buffer to reach its maximum size limit.

You might consider decreasing 'innodb_change_buffer_max_size' on a MySQL
server with static data used for reporting, or if the change buffer
consumes too much of the memory space that is shared with the buffer
pool, causing pages to age out of the buffer pool sooner than desired.

Test different settings with a representative workload to determine an
optimal configuration.  The 'innodb_change_buffer_max_size' setting is
dynamic, which allows you modify the setting without restarting the
server.

14.6.6 Configuring Thread Concurrency for InnoDB
------------------------------------------------

'InnoDB' uses operating system threads to process requests from user
transactions.  (Transactions may issue many requests to 'InnoDB' before
they commit or roll back.)  On modern operating systems and servers with
multi-core processors, where context switching is efficient, most
workloads run well without any limit on the number of concurrent
threads.  Scalability improvements in MySQL 5.5 and up reduce the need
to limit the number of concurrently executing threads inside 'InnoDB'.

In situations where it is helpful to minimize context switching between
threads, 'InnoDB' can use a number of techniques to limit the number of
concurrently executing operating system threads (and thus the number of
requests that are processed at any one time).  When 'InnoDB' receives a
new request from a user session, if the number of threads concurrently
executing is at a pre-defined limit, the new request sleeps for a short
time before it tries again.  A request that cannot be rescheduled after
the sleep is put in a first-in/first-out queue and eventually is
processed.  Threads waiting for locks are not counted in the number of
concurrently executing threads.

You can limit the number of concurrent threads by setting the
configuration parameter 'innodb_thread_concurrency'.  Once the number of
executing threads reaches this limit, additional threads sleep for a
number of microseconds, set by the configuration parameter
'innodb_thread_sleep_delay', before being placed into the queue.

Previously, it required experimentation to find the optimal value for
'innodb_thread_sleep_delay', and the optimal value could change
depending on the workload.  In MySQL 5.6.3 and higher, you can set the
configuration option 'innodb_adaptive_max_sleep_delay' to the highest
value you would allow for 'innodb_thread_sleep_delay', and 'InnoDB'
automatically adjusts 'innodb_thread_sleep_delay' up or down depending
on the current thread-scheduling activity.  This dynamic adjustment
helps the thread scheduling mechanism to work smoothly during times when
the system is lightly loaded and when it is operating near full
capacity.

The default value for 'innodb_thread_concurrency' and the implied
default limit on the number of concurrent threads has been changed in
various releases of MySQL and 'InnoDB'.  The default value of
'innodb_thread_concurrency' is '0', so that by default there is no limit
on the number of concurrently executing threads.

'InnoDB' causes threads to sleep only when the number of concurrent
threads is limited.  When there is no limit on the number of threads,
all contend equally to be scheduled.  That is, if
'innodb_thread_concurrency' is '0', the value of
'innodb_thread_sleep_delay' is ignored.

When there is a limit on the number of threads (when
'innodb_thread_concurrency' is > 0), 'InnoDB' reduces context switching
overhead by permitting multiple requests made during the execution of a
_single SQL statement_ to enter 'InnoDB' without observing the limit set
by 'innodb_thread_concurrency'.  Since an SQL statement (such as a join)
may comprise multiple row operations within 'InnoDB', 'InnoDB' assigns a
specified number of 'tickets' that allow a thread to be scheduled
repeatedly with minimal overhead.

When a new SQL statement starts, a thread has no tickets, and it must
observe 'innodb_thread_concurrency'.  Once the thread is entitled to
enter 'InnoDB', it is assigned a number of tickets that it can use for
subsequently entering 'InnoDB' to perform row operations.  If the
tickets run out, the thread is evicted, and 'innodb_thread_concurrency'
is observed again which may place the thread back into the
first-in/first-out queue of waiting threads.  When the thread is once
again entitled to enter 'InnoDB', tickets are assigned again.  The
number of tickets assigned is specified by the global option
'innodb_concurrency_tickets', which is 5000 by default.  A thread that
is waiting for a lock is given one ticket once the lock becomes
available.

The correct values of these variables depend on your environment and
workload.  Try a range of different values to determine what value works
for your applications.  Before limiting the number of concurrently
executing threads, review configuration options that may improve the
performance of 'InnoDB' on multi-core and multi-processor computers,
such as 'innodb_adaptive_hash_index'.

For general performance information about MySQL thread handling, see
connection-threads.

14.6.7 Configuring the Number of Background InnoDB I/O Threads
--------------------------------------------------------------

'InnoDB' uses background threads to service various types of I/O
requests.  You can configure the number of background threads that
service read and write I/O on data pages using the
'innodb_read_io_threads' and 'innodb_write_io_threads' configuration
parameters.  These parameters signify the number of background threads
used for read and write requests, respectively.  They are effective on
all supported platforms.  You can set values for these parameters in the
MySQL option file ('my.cnf' or 'my.ini'); you cannot change values
dynamically.  The default value for these parameters is '4' and
permissible values range from '1-64'.

The purpose of these configuration options to make 'InnoDB' more
scalable on high end systems.  Each background thread can handle up to
256 pending I/O requests.  A major source of background I/O is
read-ahead requests.  'InnoDB' tries to balance the load of incoming
requests in such way that most background threads share work equally.
'InnoDB' also attempts to allocate read requests from the same extent to
the same thread, to increase the chances of coalescing the requests.  If
you have a high end I/O subsystem and you see more than 64 x
'innodb_read_io_threads' pending read requests in 'SHOW ENGINE INNODB
STATUS' output, you might improve performance by increasing the value of
'innodb_read_io_threads'.

On Linux systems, 'InnoDB' uses the asynchronous I/O subsystem by
default to perform read-ahead and write requests for data file pages,
which changes the way that 'InnoDB' background threads service these
types of I/O requests.  For more information, see
innodb-linux-native-aio.

For more information about 'InnoDB' I/O performance, see
optimizing-innodb-diskio.

14.6.8 Using Asynchronous I/O on Linux
--------------------------------------

'InnoDB' uses the asynchronous I/O subsystem (native AIO) on Linux to
perform readahead and write requests for data file pages.  This behavior
is controlled by the 'innodb_use_native_aio' configuration option, which
applies to Linux systems only and is enabled by default.  On other
Unix-like systems, 'InnoDB' uses synchronous I/O only.  Historically,
'InnoDB' only used asynchronous I/O on Windows systems.  Using the
asynchronous I/O subsystem on Linux requires the 'libaio' library.

With synchronous I/O, query threads queue I/O requests, and 'InnoDB'
background threads retrieve the queued requests one at a time, issuing a
synchronous I/O call for each.  When an I/O request is completed and the
I/O call returns, the 'InnoDB' background thread that is handling the
request calls an I/O completion routine and returns to process the next
request.  The number of requests that can be processed in parallel is N,
where N is the number of 'InnoDB' background threads.  The number of
'InnoDB' background threads is controlled by 'innodb_read_io_threads'
and 'innodb_write_io_threads'.  See
innodb-performance-multiple_io_threads.

With native AIO, query threads dispatch I/O requests directly to the
operating system, thereby removing the limit imposed by the number of
background threads.  'InnoDB' background threads wait for I/O events to
signal completed requests.  When a request is completed, a background
thread calls an I/O completion routine and resumes waiting for I/O
events.

The advantage of native AIO is scalability for heavily I/O-bound systems
that typically show many pending reads/writes in 'SHOW ENGINE INNODB
STATUS\G' output.  The increase in parallel processing when using native
AIO means that the type of I/O scheduler or properties of the disk array
controller have a greater influence on I/O performance.

A potential disadvantage of native AIO for heavily I/O-bound systems is
lack of control over the number of I/O write requests dispatched to the
operating system at once.  Too many I/O write requests dispatched to the
operating system for parallel processing could, in some cases, result in
I/O read starvation, depending on the amount of I/O activity and system
capabilities.

If a problem with the asynchronous I/O subsystem in the OS prevents
'InnoDB' from starting, you can start the server with
'innodb_use_native_aio=0'.  This option may also be disabled
automatically during startup if 'InnoDB' detects a potential problem
such as a combination of 'tmpdir' location, 'tmpfs' file system, and
Linux kernel that does not support asynchronous I/O on 'tmpfs'.

14.6.9 Configuring the InnoDB Master Thread I/O Rate
----------------------------------------------------

The master thread in InnoDB is a thread that performs various tasks in
the background.  Most of these tasks are I/O related, such as flushing
dirty pages from the buffer pool or writing changes from the insert
buffer to the appropriate secondary indexes.  The master thread attempts
to perform these tasks in a way that does not adversely affect the
normal working of the server.  It tries to estimate the free I/O
bandwidth available and tune its activities to take advantage of this
free capacity.  Historically, InnoDB has used a hard coded value of
100 IOPs (input/output operations per second) as the total I/O capacity
of the server.

The parameter 'innodb_io_capacity' indicates the overall I/O capacity
available to InnoDB. This parameter should be set to approximately the
number of I/O operations that the system can perform per second.  The
value depends on your system configuration.  When 'innodb_io_capacity'
is set, the master threads estimates the I/O bandwidth available for
background tasks based on the set value.  Setting the value to '100'
reverts to the old behavior.

You can set the value of 'innodb_io_capacity' to any number 100 or
greater.  The default value is '200', reflecting that the performance of
typical modern I/O devices is higher than in the early days of MySQL.
Typically, values around the previous default of 100 are appropriate for
consumer-level storage devices, such as hard drives up to 7200 RPMs.
Faster hard drives, RAID configurations, and SSDs benefit from higher
values.

The 'innodb_io_capacity' setting is a total limit for all buffer pool
instances.  When dirty pages are flushed, the 'innodb_io_capacity' limit
is divided equally among buffer pool instances.  For more information,
see the 'innodb_io_capacity' system variable description.

You can set the value of this parameter in the MySQL option file
('my.cnf' or 'my.ini') or change it dynamically with the 'SET GLOBAL'
command, which requires the 'SUPER' privilege.

The 'innodb_flush_sync' configuration option causes the
'innodb_io_capacity' setting to be ignored during bursts of I/O activity
that occur at checkpoints.  'innodb_flush_sync' is enabled by default.

Formerly, the 'InnoDB' master thread also performed any needed purge
operations.  In MySQL 5.6.5 and higher, those I/O operations are moved
to other background threads, whose number is controlled by the
'innodb_purge_threads' configuration option.

For more information about InnoDB I/O performance, see
optimizing-innodb-diskio.

14.6.10 Configuring Spin Lock Polling
-------------------------------------

Many InnoDB mutexes and rw-locks are reserved for a short time.  On a
multi-core system, it can be more efficient for a thread to continuously
check if it can acquire a mutex or rw-lock for a while before sleeping.
If the mutex or rw-lock becomes available during this polling period,
the thread can continue immediately, in the same time slice.  However,
too-frequent polling by multiple threads of a shared object can cause
'cache ping pong', different processors invalidating portions of each
others' cache.  InnoDB minimizes this issue by waiting a random time
between subsequent polls.  The delay is implemented as a busy loop.

You can control the maximum delay between testing a mutex or rw-lock
using the parameter 'innodb_spin_wait_delay'.  The duration of the delay
loop depends on the C compiler and the target processor.  (In the 100MHz
Pentium era, the unit of delay was one microsecond.)  On a system where
all processor cores share a fast cache memory, you might reduce the
maximum delay or disable the busy loop altogether by setting
'innodb_spin_wait_delay=0'.  On a system with multiple processor chips,
the effect of cache invalidation can be more significant and you might
increase the maximum delay.

The default value of 'innodb_spin_wait_delay' is '6'.  The spin wait
delay is a dynamic, global parameter that you can specify in the MySQL
option file ('my.cnf' or 'my.ini') or change at runtime with the command
'SET GLOBAL innodb_spin_wait_delay=DELAY', where 'DELAY' is the desired
maximum delay.  Changing the setting requires the 'SUPER' privilege.

For performance considerations for InnoDB locking operations, see
locking-issues.

14.6.11 Configuring InnoDB Purge Scheduling
-------------------------------------------

The purge operations (a type of garbage collection) that InnoDB performs
automatically may be performed by one or more separate threads rather
than as part of the master thread.  The use of separate threads improves
scalability by allowing the main database operations to run
independently from maintenance work happening in the background.

To control this feature, increase the value of the configuration option
'innodb_purge_threads'.  If DML action is concentrated on a single table
or a few tables, keep the setting low so that the threads do not contend
with each other for access to the busy tables.  If DML operations are
spread across many tables, increase the setting.  Its maximum is 32.
'innodb_purge_threads' is a non-dynamic configuration option, which
means it cannot be configured at runtime.

There is another related configuration option, 'innodb_purge_batch_size'
with a default value of 300 and maximum value of 5000.  This option is
mainly intended for experimentation and tuning of purge operations, and
should not be interesting to typical users.

For more information about InnoDB I/O performance, see
optimizing-innodb-diskio.

14.6.12 Configuring Optimizer Statistics for InnoDB
---------------------------------------------------

This section describes how to configure persistent and non-persistent
optimizer statistics for 'InnoDB' tables.

Persistent optimizer statistics are persisted across server restarts,
allowing for greater plan stability and more consistent query
performance.  Persistent optimizer statistics also provide control and
flexibility with these additional benefits:

   * You can use the 'innodb_stats_auto_recalc' configuration option to
     control whether statistics are updated automatically after
     substantial changes to a table.

   * You can use the 'STATS_PERSISTENT', 'STATS_AUTO_RECALC', and
     'STATS_SAMPLE_PAGES' clauses with 'CREATE TABLE'
     and 'ALTER TABLE' statements to
     configure optimizer statistics for individual tables.

   * You can query optimizer statistics data in the
     'mysql.innodb_table_stats' and 'mysql.innodb_index_stats' tables.

   * You can view the 'last_update' column of the
     'mysql.innodb_table_stats' and 'mysql.innodb_index_stats' tables to
     see when statistics were last updated.

   * You can manually modify the 'mysql.innodb_table_stats' and
     'mysql.innodb_index_stats' tables to force a specific query
     optimization plan or to test alternative plans without modifying
     the database.

The persistent optimizer statistics feature is enabled by default
('innodb_stats_persistent=ON').

Non-persistent optimizer statistics are cleared on each server restart
and after some other operations, and recomputed on the next table
access.  As a result, different estimates could be produced when
recomputing statistics, leading to different choices in execution plans
and variations in query performance.

This section also provides information about estimating 'ANALYZE TABLE'
complexity, which may be useful when attempting
to achieve a balance between accurate statistics and 'ANALYZE TABLE'
execution time.

14.6.12.1 Configuring Persistent Optimizer Statistics Parameters
................................................................

The persistent optimizer statistics feature improves plan stability by
storing statistics to disk and making them persistent across server
restarts so that the optimizer is more likely to make consistent choices
each time for a given query.

Optimizer statistics are persisted to disk when
'innodb_stats_persistent=ON' or when individual tables are created or
altered with 'STATS_PERSISTENT=1'.
'innodb_stats_persistent' is enabled by default.

Formerly, optimizer statistics were cleared on each server restart and
after some other operations, and recomputed on the next table access.
Consequently, different estimates could be produced when recalculating
statistics, leading to different choices in query execution plans and
thus variations in query performance.

Persistent statistics are stored in the 'mysql.innodb_table_stats' and
'mysql.innodb_index_stats' tables, as described in
innodb-persistent-stats-tables.

To revert to using non-persistent optimizer statistics, you can modify
tables using an 'ALTER TABLE TBL_NAME STATS_PERSISTENT=0' statement.
For related information, see innodb-statistics-estimation

14.6.12.2 Configuring Automatic Statistics Calculation for Persistent Optimizer Statistics
..........................................................................................

The 'innodb_stats_auto_recalc' configuration option, which is enabled by
default, determines whether statistics are calculated automatically
whenever a table undergoes substantial changes (to more than 10% of the
rows).  You can also configure automatic statistics recalculation for
individual tables using a 'STATS_AUTO_RECALC' clause in a 'CREATE TABLE'
or 'ALTER TABLE' statement.
'innodb_stats_auto_recalc' is enabled by default.

Because of the asynchronous nature of automatic statistics recalculation
(which occurs in the background), statistics may not be recalculated
instantly after running a DML operation that affects more than 10% of a
table, even when 'innodb_stats_auto_recalc' is enabled.  In some cases,
statistics recalculation may be delayed by a few seconds.  If up-to-date
statistics are required immediately after changing significant portions
of a table, run 'ANALYZE TABLE' to initiate a
synchronous (foreground) recalculation of statistics.

If 'innodb_stats_auto_recalc' is disabled, ensure the accuracy of
optimizer statistics by issuing the 'ANALYZE TABLE'
statement for each applicable table after making
substantial changes to indexed columns.  You might run this statement in
your setup scripts after representative data has been loaded into the
table, and run it periodically after DML operations significantly change
the contents of indexed columns, or on a schedule at times of low
activity.  When a new index is added to an existing table, index
statistics are calculated and added to the 'innodb_index_stats' table
regardless of the value of 'innodb_stats_auto_recalc'.

*Caution*:

To ensure statistics are gathered when a new index is created, either
enable the 'innodb_stats_auto_recalc' option, or run 'ANALYZE TABLE'
after creating each new index when the persistent
statistics mode is enabled.

14.6.12.3 Configuring Optimizer Statistics Parameters for Individual Tables
...........................................................................

'innodb_stats_persistent', 'innodb_stats_auto_recalc', and
'innodb_stats_persistent_sample_pages' are global configuration options.
To override these system-wide settings and configure optimizer
statistics parameters for individual tables, you can define
'STATS_PERSISTENT', 'STATS_AUTO_RECALC', and 'STATS_SAMPLE_PAGES'
clauses in 'CREATE TABLE' or 'ALTER TABLE'
statements.

   * 'STATS_PERSISTENT' specifies whether to enable persistent
     statistics for an 'InnoDB' table.  The value 'DEFAULT' causes the
     persistent statistics setting for the table to be determined by the
     'innodb_stats_persistent' configuration option.  The value '1'
     enables persistent statistics for the table, while the value '0'
     turns off this feature.  After enabling persistent statistics
     through a 'CREATE TABLE' or 'ALTER TABLE' statement, issue an
     'ANALYZE TABLE' statement to calculate the
     statistics, after loading representative data into the table.

   * 'STATS_AUTO_RECALC' specifies whether to automatically recalculate
     persistent statistics for an 'InnoDB' table.  The value 'DEFAULT'
     causes the persistent statistics setting for the table to be
     determined by the 'innodb_stats_auto_recalc' configuration option.
     The value '1' causes statistics to be recalculated when 10% of the
     data in the table has changed.  The value '0' prevents automatic
     recalculation for this table; with this setting, issue an
     'ANALYZE TABLE' statement to recalculate the
     statistics after making substantial changes to the table.

   * 'STATS_SAMPLE_PAGES' specifies the number of index pages to sample
     when estimating cardinality and other statistics for an indexed
     column, such as those calculated by 'ANALYZE TABLE'.

All three clauses are specified in the following 'CREATE TABLE'
example:

     CREATE TABLE `t1` (
     `id` int(8) NOT NULL auto_increment,
     `data` varchar(255),
     `date` datetime,
     PRIMARY KEY  (`id`),
     INDEX `DATE_IX` (`date`)
     ) ENGINE=InnoDB,
       STATS_PERSISTENT=1,
       STATS_AUTO_RECALC=1,
       STATS_SAMPLE_PAGES=25;

14.6.12.4 Configuring the Number of Sampled Pages for InnoDB Optimizer Statistics
.................................................................................

The MySQL query optimizer uses estimated statistics about key
distributions to choose the indexes for an execution plan, based on the
relative selectivity of the index.  Operations such as 'ANALYZE TABLE'
cause 'InnoDB' to sample random pages from each
index on a table to estimate the cardinality of the index.  (This
technique is known as random dives.)

To give you control over the quality of the statistics estimate (and
thus better information for the query optimizer), you can change the
number of sampled pages using the parameter
'innodb_stats_persistent_sample_pages', which can be set at runtime.

'innodb_stats_persistent_sample_pages' has a default value of 20.  As a
general guideline, consider modifying this parameter when encountering
the following issues:

  1. _Statistics are not accurate enough and the optimizer chooses
     suboptimal plans_, as shown by 'EXPLAIN' output.
     The accuracy of statistics can be checked by comparing the actual
     cardinality of an index (as returned by running 'SELECT DISTINCT'
     on the index columns) with the estimates
     provided in the 'mysql.innodb_index_stats' persistent statistics
     table.

     If it is determined that statistics are not accurate enough, the
     value of 'innodb_stats_persistent_sample_pages' should be increased
     until the statistics estimates are sufficiently accurate.
     Increasing 'innodb_stats_persistent_sample_pages' too much,
     however, could cause 'ANALYZE TABLE' to run
     slowly.

  2. _'ANALYZE TABLE' is too slow_.  In this case
     'innodb_stats_persistent_sample_pages' should be decreased until
     'ANALYZE TABLE' execution time is acceptable.
     Decreasing the value too much, however, could lead to the first
     problem of inaccurate statistics and suboptimal query execution
     plans.

     If a balance cannot be achieved between accurate statistics and
     'ANALYZE TABLE' execution time, consider
     decreasing the number of indexed columns in the table or limiting
     the number of partitions to reduce 'ANALYZE TABLE'
     complexity.  The number of columns in the table's
     primary key is also important to consider, as primary key columns
     are appended to each nonunique index.

     For related information, see
     innodb-analyze-table-complexity.

14.6.12.5 Including Delete-marked Records in Persistent Statistics Calculations
...............................................................................

By default, 'InnoDB' reads uncommitted data when calculating statistics.
In the case of an uncommitted transaction that deletes rows from a
table, 'InnoDB' excludes records that are delete-marked when calculating
row estimates and index statistics, which can lead to non-optimal
execution plans for other transactions that are operating on the table
concurrently using a transaction isolation level other than 'READ
UNCOMMITTED'.  To avoid this scenario,
'innodb_stats_include_delete_marked' can be enabled to ensure that
'InnoDB' includes delete-marked records when calculating persistent
optimizer statistics.

When 'innodb_stats_include_delete_marked' is enabled, see 'ANALYZE TABLE'
considers delete-marked records when
recalculating statistics.

'innodb_stats_include_delete_marked' is a global setting that affects
all 'InnoDB' tables, and it is only applicable to persistent optimizer
statistics.

'innodb_stats_include_delete_marked' was introduced in MySQL 5.7.16.

14.6.12.6 InnoDB Persistent Statistics Tables
.............................................

The persistent statistics feature relies on the internally managed
tables in the 'mysql' database, named 'innodb_table_stats' and
'innodb_index_stats'.  These tables are set up automatically in all
install, upgrade, and build-from-source procedures.

*Columns of innodb_table_stats*

Column name            Description

'database_name'        Database name

'table_name'           Table name, partition name, or subpartition name

'last_update'          A timestamp indicating the last time that
                       'InnoDB' updated this row

'n_rows'               The number of rows in the table

'clustered_index_size' The size of the primary index, in pages

'sum_of_other_index_sizes'The total size of other (non-primary) indexes,
                       in pages

*Columns of innodb_index_stats*

Column name            Description

'database_name'        Database name

'table_name'           Table name, partition name, or subpartition name

'index_name'           Index name

'last_update'          A timestamp indicating the last time that
                       'InnoDB' updated this row

'stat_name'            The name of the statistic, whose value is
                       reported in the 'stat_value' column

'stat_value'           The value of the statistic that is named in
                       'stat_name' column

'sample_size'          The number of pages sampled for the estimate
                       provided in the 'stat_value' column

'stat_description'     Description of the statistic that is named in
                       the 'stat_name' column

Both the 'innodb_table_stats' and 'innodb_index_stats' tables include a
'last_update' column showing when 'InnoDB' last updated index
statistics, as shown in the following example:

     mysql> SELECT * FROM innodb_table_stats \G
     *************************** 1. row ***************************
                database_name: sakila
                   table_name: actor
                  last_update: 2014-05-28 16:16:44
                       n_rows: 200
         clustered_index_size: 1
     sum_of_other_index_sizes: 1
     ...

     mysql> SELECT * FROM innodb_index_stats \G
     *************************** 1. row ***************************
        database_name: sakila
           table_name: actor
           index_name: PRIMARY
          last_update: 2014-05-28 16:16:44
            stat_name: n_diff_pfx01
           stat_value: 200
          sample_size: 1
          ...

The 'innodb_table_stats' and 'innodb_index_stats' tables are ordinary
tables and can be updated manually.  The ability to update statistics
manually makes it possible to force a specific query optimization plan
or test alternative plans without modifying the database.  If you
manually update statistics, issue the 'FLUSH TABLE TBL_NAME' command to
make MySQL reload the updated statistics.

Persistent statistics are considered local information, because they
relate to the server instance.  The 'innodb_table_stats' and
'innodb_index_stats' tables are therefore not replicated when automatic
statistics recalculation takes place.  If you run 'ANALYZE TABLE'
to initiate a synchronous recalculation of statistics,
this statement is replicated (unless you suppressed logging for it), and
recalculation takes place on the replication slaves.

14.6.12.7 InnoDB Persistent Statistics Tables Example
.....................................................

The 'innodb_table_stats' table contains one row per table.  The data
collected is demonstrated in the following example.

Table 't1' contains a primary index (columns 'a', 'b') secondary index
(columns 'c', 'd'), and unique index (columns 'e',' f'):

     CREATE TABLE t1 (
     a INT, b INT, c INT, d INT, e INT, f INT,
     PRIMARY KEY (a, b), KEY i1 (c, d), UNIQUE KEY i2uniq (e, f)
     ) ENGINE=INNODB;

After inserting five rows of sample data, the table appears as follows:

     mysql> SELECT * FROM t1;
     +---+---+------+------+------+------+
     | a | b | c    | d    | e    | f    |
     +---+---+------+------+------+------+
     | 1 | 1 |   10 |   11 |  100 |  101 |
     | 1 | 2 |   10 |   11 |  200 |  102 |
     | 1 | 3 |   10 |   11 |  100 |  103 |
     | 1 | 4 |   10 |   12 |  200 |  104 |
     | 1 | 5 |   10 |   12 |  100 |  105 |
     +---+---+------+------+------+------+

To immediately update statistics, run 'ANALYZE TABLE'.
(if 'innodb_stats_auto_recalc' is enabled, statistics are
updated automatically within a few seconds assuming that the 10%
threshold for changed table rows is reached):

     mysql> ANALYZE TABLE t1;
     +---------+---------+----------+----------+
     | Table   | Op      | Msg_type | Msg_text |
     +---------+---------+----------+----------+
     | test.t1 | analyze | status   | OK       |
     +---------+---------+----------+----------+

Table statistics for table 't1' show the last time 'InnoDB' updated the
table statistics ('2014-03-14 14:36:34'), the number of rows in the
table ('5'), the clustered index size ('1' page), and the combined size
of the other indexes ('2' pages).

     mysql> SELECT * FROM mysql.innodb_table_stats WHERE table_name like 't1'\G
     *************************** 1. row ***************************
                database_name: test
                   table_name: t1
                  last_update: 2014-03-14 14:36:34
                       n_rows: 5
         clustered_index_size: 1
     sum_of_other_index_sizes: 2

The 'innodb_index_stats' table contains multiple rows for each index.
Each row in the 'innodb_index_stats' table provides data related to a
particular index statistic which is named in the 'stat_name' column and
described in the 'stat_description' column.  For example:

     mysql> SELECT index_name, stat_name, stat_value, stat_description
            FROM mysql.innodb_index_stats WHERE table_name like 't1';
     +------------+--------------+------------+-----------------------------------+
     | index_name | stat_name    | stat_value | stat_description                  |
     +------------+--------------+------------+-----------------------------------+
     | PRIMARY    | n_diff_pfx01 |          1 | a                                 |
     | PRIMARY    | n_diff_pfx02 |          5 | a,b                               |
     | PRIMARY    | n_leaf_pages |          1 | Number of leaf pages in the index |
     | PRIMARY    | size         |          1 | Number of pages in the index      |
     | i1         | n_diff_pfx01 |          1 | c                                 |
     | i1         | n_diff_pfx02 |          2 | c,d                               |
     | i1         | n_diff_pfx03 |          2 | c,d,a                             |
     | i1         | n_diff_pfx04 |          5 | c,d,a,b                           |
     | i1         | n_leaf_pages |          1 | Number of leaf pages in the index |
     | i1         | size         |          1 | Number of pages in the index      |
     | i2uniq     | n_diff_pfx01 |          2 | e                                 |
     | i2uniq     | n_diff_pfx02 |          5 | e,f                               |
     | i2uniq     | n_leaf_pages |          1 | Number of leaf pages in the index |
     | i2uniq     | size         |          1 | Number of pages in the index      |
     +------------+--------------+------------+-----------------------------------+

The 'stat_name' column shows the following types of statistics:

   * 'size': Where 'stat_name'='size', the 'stat_value' column displays
     the total number of pages in the index.

   * 'n_leaf_pages': Where 'stat_name'='n_leaf_pages', the 'stat_value'
     column displays the number of leaf pages in the index.

   * 'n_diff_pfxNN': Where 'stat_name'='n_diff_pfx01', the 'stat_value'
     column displays the number of distinct values in the first column
     of the index.  Where 'stat_name'='n_diff_pfx02', the 'stat_value'
     column displays the number of distinct values in the first two
     columns of the index, and so on.  Additionally, where
     'stat_name'='n_diff_pfxNN', the 'stat_description' column shows a
     comma separated list of the index columns that are counted.

To further illustrate the 'n_diff_pfxNN' statistic, which provides
cardinality data, consider once again the 't1' table example that was
introduced previously.  As shown below, the 't1' table is created with a
primary index (columns 'a', 'b'), a secondary index (columns 'c', 'd'),
and a unique index (columns 'e', 'f'):

     CREATE TABLE t1 (
       a INT, b INT, c INT, d INT, e INT, f INT,
       PRIMARY KEY (a, b), KEY i1 (c, d), UNIQUE KEY i2uniq (e, f)
     ) ENGINE=INNODB;

After inserting five rows of sample data, the table appears as follows:

     mysql> SELECT * FROM t1;
     +---+---+------+------+------+------+
     | a | b | c    | d    | e    | f    |
     +---+---+------+------+------+------+
     | 1 | 1 |   10 |   11 |  100 |  101 |
     | 1 | 2 |   10 |   11 |  200 |  102 |
     | 1 | 3 |   10 |   11 |  100 |  103 |
     | 1 | 4 |   10 |   12 |  200 |  104 |
     | 1 | 5 |   10 |   12 |  100 |  105 |
     +---+---+------+------+------+------+

When you query the 'index_name', 'stat_name', 'stat_value', and
'stat_description' where 'stat_name LIKE 'n_diff%'', the following
result set is returned:

     mysql> SELECT index_name, stat_name, stat_value, stat_description
            FROM mysql.innodb_index_stats
            WHERE table_name like 't1' AND stat_name LIKE 'n_diff%';
     +------------+--------------+------------+------------------+
     | index_name | stat_name    | stat_value | stat_description |
     +------------+--------------+------------+------------------+
     | PRIMARY    | n_diff_pfx01 |          1 | a                |
     | PRIMARY    | n_diff_pfx02 |          5 | a,b              |
     | i1         | n_diff_pfx01 |          1 | c                |
     | i1         | n_diff_pfx02 |          2 | c,d              |
     | i1         | n_diff_pfx03 |          2 | c,d,a            |
     | i1         | n_diff_pfx04 |          5 | c,d,a,b          |
     | i2uniq     | n_diff_pfx01 |          2 | e                |
     | i2uniq     | n_diff_pfx02 |          5 | e,f              |
     +------------+--------------+------------+------------------+

For the 'PRIMARY' index, there are two 'n_diff%' rows.  The number of
rows is equal to the number of columns in the index.

*Note*:

For nonunique indexes, 'InnoDB' appends the columns of the primary key.

   * Where 'index_name'='PRIMARY' and 'stat_name'='n_diff_pfx01', the
     'stat_value' is '1', which indicates that there is a single
     distinct value in the first column of the index (column 'a').  The
     number of distinct values in column 'a' is confirmed by viewing the
     data in column 'a' in table 't1', in which there is a single
     distinct value ('1').  The counted column ('a') is shown in the
     'stat_description' column of the result set.

   * Where 'index_name'='PRIMARY' and 'stat_name'='n_diff_pfx02', the
     'stat_value' is '5', which indicates that there are five distinct
     values in the two columns of the index ('a,b').  The number of
     distinct values in columns 'a' and 'b' is confirmed by viewing the
     data in columns 'a' and 'b' in table 't1', in which there are five
     distinct values: ('1,1'), ('1,2'), ('1,3'), ('1,4') and ('1,5').
     The counted columns ('a,b') are shown in the 'stat_description'
     column of the result set.

For the secondary index ('i1'), there are four 'n_diff%' rows.  Only two
columns are defined for the secondary index ('c,d') but there are four
'n_diff%' rows for the secondary index because 'InnoDB' suffixes all
nonunique indexes with the primary key.  As a result, there are four
'n_diff%' rows instead of two to account for the both the secondary
index columns ('c,d') and the primary key columns ('a,b').

   * Where 'index_name'='i1' and 'stat_name'='n_diff_pfx01', the
     'stat_value' is '1', which indicates that there is a single
     distinct value in the first column of the index (column 'c').  The
     number of distinct values in column 'c' is confirmed by viewing the
     data in column 'c' in table 't1', in which there is a single
     distinct value: ('10').  The counted column ('c') is shown in the
     'stat_description' column of the result set.

   * Where 'index_name'='i1' and 'stat_name'='n_diff_pfx02', the
     'stat_value' is '2', which indicates that there are two distinct
     values in the first two columns of the index ('c,d').  The number
     of distinct values in columns 'c' an 'd' is confirmed by viewing
     the data in columns 'c' and 'd' in table 't1', in which there are
     two distinct values: ('10,11') and ('10,12').  The counted columns
     ('c,d') are shown in the 'stat_description' column of the result
     set.

   * Where 'index_name'='i1' and 'stat_name'='n_diff_pfx03', the
     'stat_value' is '2', which indicates that there are two distinct
     values in the first three columns of the index ('c,d,a').  The
     number of distinct values in columns 'c', 'd', and 'a' is confirmed
     by viewing the data in column 'c', 'd', and 'a' in table 't1', in
     which there are two distinct values: ('10,11,1') and ('10,12,1').
     The counted columns ('c,d,a') are shown in the 'stat_description'
     column of the result set.

   * Where 'index_name'='i1' and 'stat_name'='n_diff_pfx04', the
     'stat_value' is '5', which indicates that there are five distinct
     values in the four columns of the index ('c,d,a,b').  The number of
     distinct values in columns 'c', 'd', 'a' and 'b' is confirmed by
     viewing the data in columns 'c', 'd', 'a', and 'b' in table 't1',
     in which there are five distinct values: ('10,11,1,1'),
     ('10,11,1,2'), ('10,11,1,3'), ('10,12,1,4') and ('10,12,1,5').  The
     counted columns ('c,d,a,b') are shown in the 'stat_description'
     column of the result set.

For the unique index ('i2uniq'), there are two 'n_diff%' rows.

   * Where 'index_name'='i2uniq' and 'stat_name'='n_diff_pfx01', the
     'stat_value' is '2', which indicates that there are two distinct
     values in the first column of the index (column 'e').  The number
     of distinct values in column 'e' is confirmed by viewing the data
     in column 'e' in table 't1', in which there are two distinct
     values: ('100') and ('200').  The counted column ('e') is shown in
     the 'stat_description' column of the result set.

   * Where 'index_name'='i2uniq' and 'stat_name'='n_diff_pfx02', the
     'stat_value' is '5', which indicates that there are five distinct
     values in the two columns of the index ('e,f').  The number of
     distinct values in columns 'e' and 'f' is confirmed by viewing the
     data in columns 'e' and 'f' in table 't1', in which there are five
     distinct values: ('100,101'), ('200,102'), ('100,103'), ('200,104')
     and ('100,105').  The counted columns ('e,f') are shown in the
     'stat_description' column of the result set.

14.6.12.8 Retrieving Index Size Using the innodb_index_stats Table
..................................................................

The size of indexes for tables, partitions, or subpartitions can be
retrieved using the 'innodb_index_stats' table.  In the following
example, index sizes are retrieved for table 't1'.  For a definition of
table 't1' and corresponding index statistics, see
innodb-persistent-stats-tables-example.

     mysql> SELECT SUM(stat_value) pages, index_name,
            SUM(stat_value)*@@innodb_page_size size
            FROM mysql.innodb_index_stats WHERE table_name='t1'
            AND stat_name = 'size' GROUP BY index_name;
     +-------+------------+-------+
     | pages | index_name | size  |
     +-------+------------+-------+
     |     1 | PRIMARY    | 16384 |
     |     1 | i1         | 16384 |
     |     1 | i2uniq     | 16384 |
     +-------+------------+-------+

For partitions or subpartitions, the same query with a modified 'WHERE'
clause can be used to retrieve index sizes.  For example, the following
query retrieves index sizes for partitions of table 't1':

     mysql> SELECT SUM(stat_value) pages, index_name,
            SUM(stat_value)*@@innodb_page_size size
            FROM mysql.innodb_index_stats WHERE table_name like 't1#P%'
            AND stat_name = 'size' GROUP BY index_name;

14.6.12.9 Configuring Non-Persistent Optimizer Statistics Parameters
....................................................................

This section describes how to configure non-persistent optimizer
statistics.  Optimizer statistics are not persisted to disk when
'innodb_stats_persistent=OFF' or when individual tables are created or
altered with 'STATS_PERSISTENT=0'.  Instead,
statistics are stored in memory, and are lost when the server is shut
down.  Statistics are also updated periodically by certain operations
and under certain conditions.

As of MySQL 5.6.6, optimizer statistics are persisted to disk by
default, enabled by the 'innodb_stats_persistent' configuration option.
For information about persistent optimizer statistics, see
innodb-persistent-stats.

*Optimizer Statistics Updates*

Non-persistent optimizer statistics are updated when:

   * Running 'ANALYZE TABLE'.

   * Running 'SHOW TABLE STATUS', 'SHOW INDEX',
     or querying the
     'INFORMATION_SCHEMA.TABLES' or
     'INFORMATION_SCHEMA.STATISTICS' tables with the
     'innodb_stats_on_metadata' option enabled.

     The default setting for 'innodb_stats_on_metadata' was changed to
     'OFF' when persistent optimizer statistics were enabled by default
     in MySQL 5.6.6.  Enabling 'innodb_stats_on_metadata' may reduce
     access speed for schemas that have a large number of tables or
     indexes, and reduce stability of execution plans for queries that
     involve 'InnoDB' tables.  'innodb_stats_on_metadata' is configured
     globally using a 'SET' statement.

          SET GLOBAL innodb_stats_on_metadata=ON

     *Note*:

     'innodb_stats_on_metadata' only applies when optimizer statistics
     are configured to be non-persistent (when 'innodb_stats_persistent'
     is disabled).

   * Starting a 'mysql' client with the '--auto-rehash'
     option enabled, which is the default.  The 'auto-rehash' option
     causes all 'InnoDB' tables to be opened, and the open table
     operations cause statistics to be recalculated.

     To improve the start up time of the 'mysql' client
     and to updating statistics, you can turn off 'auto-rehash' using
     the '--disable-auto-rehash' option.  The 'auto-rehash' feature
     enables automatic name completion of database, table, and column
     names for interactive users.

   * A table is first opened.

   * 'InnoDB' detects that 1 / 16 of table has been modified since the
     last time statistics were updated.

*Configuring the Number of Sampled Pages*

The MySQL query optimizer uses estimated statistics about key
distributions to choose the indexes for an execution plan, based on the
relative selectivity of the index.  When 'InnoDB' updates optimizer
statistics, it samples random pages from each index on a table to
estimate the cardinality of the index.  (This technique is known as
random dives.)

To give you control over the quality of the statistics estimate (and
thus better information for the query optimizer), you can change the
number of sampled pages using the parameter
'innodb_stats_transient_sample_pages'.  The default number of sampled
pages is 8, which could be insufficient to produce an accurate estimate,
leading to poor index choices by the query optimizer.  This technique is
especially important for large tables and tables used in joins.
Unnecessary full table scans for such tables can be a substantial
performance issue.  See table-scan-avoidance for tips on tuning
such queries.  'innodb_stats_transient_sample_pages' is a global
parameter that can be set at runtime.

The value of 'innodb_stats_transient_sample_pages' affects the index
sampling for all 'InnoDB' tables and indexes when
'innodb_stats_persistent=0'.  Be aware of the following potentially
significant impacts when you change the index sample size:

   * Small values like 1 or 2 can result in inaccurate estimates of
     cardinality.

   * Increasing the 'innodb_stats_transient_sample_pages' value might
     require more disk reads.  Values much larger than 8 (say, 100), can
     cause a significant slowdown in the time it takes to open a table
     or execute 'SHOW TABLE STATUS'.

   * The optimizer might choose very different query plans based on
     different estimates of index selectivity.

Whatever value of 'innodb_stats_transient_sample_pages' works best for a
system, set the option and leave it at that value.  Choose a value that
results in reasonably accurate estimates for all tables in your database
without requiring excessive I/O. Because the statistics are
automatically recalculated at various times other than on execution of
'ANALYZE TABLE', it does not make sense to increase
the index sample size, run 'ANALYZE TABLE', then
decrease sample size again.

Smaller tables generally require fewer index samples than larger tables.
If your database has many large tables, consider using a higher value
for 'innodb_stats_transient_sample_pages' than if you have mostly
smaller tables.

14.6.12.10 Estimating ANALYZE TABLE Complexity for InnoDB Tables
................................................................

'ANALYZE TABLE' complexity for 'InnoDB' tables is
dependent on:

   * The number of pages sampled, as defined by
     'innodb_stats_persistent_sample_pages'.

   * The number of indexed columns in a table

   * The number of partitions.  If a table has no partitions, the number
     of partitions is considered to be 1.

Using these parameters, an approximate formula for estimating
'ANALYZE TABLE' complexity would be:

The value of 'innodb_stats_persistent_sample_pages' * number of indexed
columns in a table * the number of partitions

Typically, the greater the resulting value, the greater the execution
time for 'ANALYZE TABLE'.

*Note*:

'innodb_stats_persistent_sample_pages' defines the number of pages
sampled at a global level.  To set the number of pages sampled for an
individual table, use the 'STATS_SAMPLE_PAGES' option with 'CREATE TABLE'
or 'ALTER TABLE'.  For more
information, see innodb-persistent-stats.

If 'innodb_stats_persistent=OFF', the number of pages sampled is defined
by 'innodb_stats_transient_sample_pages'.  See
innodb-statistics-estimation for additional information.

For a more in-depth approach to estimating 'ANALYZE TABLE' complexity,
consider the following example.

In Big O notation (http://en.wikipedia.org/wiki/Big_O_notation), see
'ANALYZE TABLE' complexity is described as:

     O(n_sample
       * (n_cols_in_uniq_i
          + n_cols_in_non_uniq_i
          + n_cols_in_pk * (1 + n_non_uniq_i))
       * n_part)

where:

   * 'n_sample' is the number of pages sampled (defined by
     'innodb_stats_persistent_sample_pages')

   * 'n_cols_in_uniq_i' is total number of all columns in all unique
     indexes (not counting the primary key columns)

   * 'n_cols_in_non_uniq_i' is the total number of all columns in all
     nonunique indexes

   * 'n_cols_in_pk' is the number of columns in the primary key (if a
     primary key is not defined, 'InnoDB' creates a single column
     primary key internally)

   * 'n_non_uniq_i' is the number of nonunique indexes in the table

   * 'n_part' is the number of partitions.  If no partitions are
     defined, the table is considered to be a single partition.

Now, consider the following table (table 't'), which has a primary key
(2 columns), a unique index (2 columns), and two nonunique indexes (two
columns each):

     CREATE TABLE t (
       a INT,
       b INT,
       c INT,
       d INT,
       e INT,
       f INT,
       g INT,
       h INT,
       PRIMARY KEY (a, b),
       UNIQUE KEY i1uniq (c, d),
       KEY i2nonuniq (e, f),
       KEY i3nonuniq (g, h)
     );

For the column and index data required by the algorithm described above,
query the 'mysql.innodb_index_stats' persistent index statistics table
for table 't'.  The 'n_diff_pfx%' statistics show the columns that are
counted for each index.  For example, columns 'a' and 'b' are counted
for the primary key index.  For the nonunique indexes, the primary key
columns (a,b) are counted in addition to the user defined columns.

*Note*:

For additional information about the 'InnoDB' persistent statistics
tables, see innodb-persistent-stats

     mysql> SELECT index_name, stat_name, stat_description
            FROM mysql.innodb_index_stats WHERE
            database_name='test' AND
            table_name='t' AND
            stat_name like 'n_diff_pfx%';
       +------------+--------------+------------------+
       | index_name | stat_name    | stat_description |
       +------------+--------------+------------------+
       | PRIMARY    | n_diff_pfx01 | a                |
       | PRIMARY    | n_diff_pfx02 | a,b              |
       | i1uniq     | n_diff_pfx01 | c                |
       | i1uniq     | n_diff_pfx02 | c,d              |
       | i2nonuniq  | n_diff_pfx01 | e                |
       | i2nonuniq  | n_diff_pfx02 | e,f              |
       | i2nonuniq  | n_diff_pfx03 | e,f,a            |
       | i2nonuniq  | n_diff_pfx04 | e,f,a,b          |
       | i3nonuniq  | n_diff_pfx01 | g                |
       | i3nonuniq  | n_diff_pfx02 | g,h              |
       | i3nonuniq  | n_diff_pfx03 | g,h,a            |
       | i3nonuniq  | n_diff_pfx04 | g,h,a,b          |
       +------------+--------------+------------------+

Based on the index statistics data shown above and the table definition,
the following values can be determined:

   * 'n_cols_in_uniq_i', the total number of all columns in all unique
     indexes not counting the primary key columns, is 2 ('c' and 'd')

   * 'n_cols_in_non_uniq_i', the total number of all columns in all
     nonunique indexes, is 4 ('e', 'f', 'g' and 'h')

   * 'n_cols_in_pk', the number of columns in the primary key, is 2 ('a'
     and 'b')

   * 'n_non_uniq_i', the number of nonunique indexes in the table, is 2
     ('i2nonuniq' and 'i3nonuniq'))

   * 'n_part', the number of partitions, is 1.

You can now calculate 'innodb_stats_persistent_sample_pages' * (2 + 4 +
2 * (1 + 2)) * 1 to determine the number of leaf pages that are scanned.
With 'innodb_stats_persistent_sample_pages' set to the default value of
'20', and with a default page size of 16 'KiB'
('innodb_page_size'=16384), you can then estimate that 20 * 12 * 16384
'bytes' are read for table 't', or about 4 'MiB'.

*Note*:

All 4 'MiB' may not be read from disk, as some leaf pages may already be
cached in the buffer pool.

14.6.13 Configuring the Merge Threshold for Index Pages
-------------------------------------------------------

You can configure the 'MERGE_THRESHOLD' value for index pages.  If the
'page-full' percentage for an index page falls below the
'MERGE_THRESHOLD' value when a row is deleted or when a row is shortened
by an 'UPDATE' operation, 'InnoDB' attempts to merge the
index page with a neighboring index page.  The default 'MERGE_THRESHOLD'
value is 50, which is the previously hardcoded value.  The minimum
'MERGE_THRESHOLD' value is 1 and the maximum value is 50.

When the 'page-full' percentage for an index page falls below 50%, which
is the default 'MERGE_THRESHOLD' setting, 'InnoDB' attempts to merge the
index page with a neighboring page.  If both pages are close to 50%
full, a page split can occur soon after the pages are merged.  If this
merge-split behavior occurs frequently, it can have an adverse affect on
performance.  To avoid frequent merge-splits, you can lower the
'MERGE_THRESHOLD' value so that 'InnoDB' attempts page merges at a lower
'page-full' percentage.  Merging pages at a lower page-full percentage
leaves more room in index pages and helps reduce merge-split behavior.

The 'MERGE_THRESHOLD' for index pages can be defined for a table or for
individual indexes.  A 'MERGE_THRESHOLD' value defined for an individual
index takes priority over a 'MERGE_THRESHOLD' value defined for the
table.  If undefined, the 'MERGE_THRESHOLD' value defaults to 50.

*Setting MERGE_THRESHOLD for a Table*

You can set the 'MERGE_THRESHOLD' value for a table using the
TABLE_OPTION 'COMMENT' clause of the 'CREATE TABLE'.
statement.  For example:

     CREATE TABLE t1 (
        id INT,
       KEY id_index (id)
     ) COMMENT='MERGE_THRESHOLD=45';

You can also set the 'MERGE_THRESHOLD' value for an existing table using
the TABLE_OPTION 'COMMENT' clause with 'ALTER TABLE'.:

     CREATE TABLE t1 (
        id INT,
       KEY id_index (id)
     );

     ALTER TABLE t1 COMMENT='MERGE_THRESHOLD=40';

*Setting MERGE_THRESHOLD for Individual Indexes*

To set the 'MERGE_THRESHOLD' value for an individual index, you can use
the INDEX_OPTION 'COMMENT' clause with 'CREATE TABLE',
see 'ALTER TABLE', or 'CREATE INDEX',
as shown in the following examples:

   * Setting 'MERGE_THRESHOLD' for an individual index using
     'CREATE TABLE'.:

          CREATE TABLE t1 (
             id INT,
            KEY id_index (id) COMMENT 'MERGE_THRESHOLD=40'
          );

   * Setting 'MERGE_THRESHOLD' for an individual index using
     'ALTER TABLE'.:

          CREATE TABLE t1 (
             id INT,
            KEY id_index (id)
          );

          ALTER TABLE t1 DROP KEY id_index;
          ALTER TABLE t1 ADD KEY id_index (id) COMMENT 'MERGE_THRESHOLD=40';

   * Setting 'MERGE_THRESHOLD' for an individual index using
     'CREATE INDEX'.:

          CREATE TABLE t1 (id INT);
          CREATE INDEX id_index ON t1 (id) COMMENT 'MERGE_THRESHOLD=40';

*Note*:

You cannot modify the 'MERGE_THRESHOLD' value at the index level for
'GEN_CLUST_INDEX', which is the clustered index created by 'InnoDB' when
an 'InnoDB' table is created without a primary key or unique key index.
You can only modify the 'MERGE_THRESHOLD' value for 'GEN_CLUST_INDEX' by
setting 'MERGE_THRESHOLD' for the table.

*Querying the MERGE_THRESHOLD Value for an Index*

The current 'MERGE_THRESHOLD' value for an index can be obtained by
querying the 'INNODB_SYS_INDEXES'.
table.  For example:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_INDEXES WHERE NAME='id_index' \G
     *************************** 1. row ***************************
            INDEX_ID: 91
                NAME: id_index
            TABLE_ID: 68
                TYPE: 0
            N_FIELDS: 1
             PAGE_NO: 4
               SPACE: 57
     MERGE_THRESHOLD: 40

You can use 'SHOW CREATE TABLE' to view the
'MERGE_THRESHOLD' value for a table, if explicitly defined using the
TABLE_OPTION 'COMMENT' clause:

     mysql> SHOW CREATE TABLE t2 \G
     *************************** 1. row ***************************
            Table: t2
     Create Table: CREATE TABLE `t2` (
       `id` int(11) DEFAULT NULL,
       KEY `id_index` (`id`) COMMENT 'MERGE_THRESHOLD=40'
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1

*Note*:

A 'MERGE_THRESHOLD' value defined at the index level takes priority over
a 'MERGE_THRESHOLD' value defined for the table.  If undefined,
'MERGE_THRESHOLD' defaults to 50% ('MERGE_THRESHOLD=50', which is the
previously hardcoded value.

Likewise, you can use 'SHOW INDEX' to view the
'MERGE_THRESHOLD' value for an index, if explicitly defined using the
INDEX_OPTION 'COMMENT' clause:

     mysql> SHOW INDEX FROM t2 \G
     *************************** 1. row ***************************
             Table: t2
        Non_unique: 1
          Key_name: id_index
      Seq_in_index: 1
       Column_name: id
         Collation: A
       Cardinality: 0
          Sub_part: NULL
            Packed: NULL
              Null: YES
        Index_type: BTREE
           Comment:
     Index_comment: MERGE_THRESHOLD=40

*Measuring the Effect of MERGE_THRESHOLD Settings*

The 'INNODB_METRICS' table provides two
counters that can be used to measure the effect of a 'MERGE_THRESHOLD'
setting on index page merges.

     mysql> SELECT NAME, COMMENT FROM INFORMATION_SCHEMA.INNODB_METRICS
            WHERE NAME like '%index_page_merge%';
     +-----------------------------+----------------------------------------+
     | NAME                        | COMMENT                                |
     +-----------------------------+----------------------------------------+
     | index_page_merge_attempts   | Number of index page merge attempts    |
     | index_page_merge_successful | Number of successful index page merges |
     +-----------------------------+----------------------------------------+

When lowering the 'MERGE_THRESHOLD' value, the objectives are:

   * A smaller number of page merge attempts and successful page merges

   * A similar number of page merge attempts and successful page merges

A 'MERGE_THRESHOLD' setting that is too small could result in large data
files due to an excessive amount of empty page space.

For information about using 'INNODB_METRICS'
counters, see
innodb-information-schema-metrics-table.

14.7 InnoDB Tablespaces
=======================

This section covers topics related to 'InnoDB' tablespaces.

14.7.1 Resizing the InnoDB System Tablespace
--------------------------------------------

This section describes how to increase or decrease the size of the
'InnoDB' system tablespace.

*Increasing the Size of the InnoDB System Tablespace*

The easiest way to increase the size of the 'InnoDB' system tablespace
is to configure it from the beginning to be auto-extending.  Specify the
'autoextend' attribute for the last data file in the tablespace
definition.  Then 'InnoDB' increases the size of that file automatically
in 64MB increments when it runs out of space.  The increment size can be
changed by setting the value of the 'innodb_autoextend_increment' system
variable, which is measured in megabytes.

You can expand the system tablespace by a defined amount by adding
another data file:

  1. Shut down the MySQL server.

  2. If the previous last data file is defined with the keyword
     'autoextend', change its definition to use a fixed size, based on
     how large it has actually grown.  Check the size of the data file,
     round it down to the closest multiple of 1024 x 1024 bytes (= 1MB),
     and specify this rounded size explicitly in
     'innodb_data_file_path'.

  3. Add a new data file to the end of 'innodb_data_file_path',
     optionally making that file auto-extending.  Only the last data
     file in the 'innodb_data_file_path' can be specified as
     auto-extending.

  4. Start the MySQL server again.

For example, this tablespace has just one auto-extending data file
'ibdata1':

     innodb_data_home_dir =
     innodb_data_file_path = /ibdata/ibdata1:10M:autoextend

Suppose that this data file, over time, has grown to 988MB. Here is the
configuration line after modifying the original data file to use a fixed
size and adding a new auto-extending data file:

     innodb_data_home_dir =
     innodb_data_file_path = /ibdata/ibdata1:988M;/disk2/ibdata2:50M:autoextend

When you add a new data file to the system tablespace configuration,
make sure that the filename does not refer to an existing file.
'InnoDB' creates and initializes the file when you restart the server.

*Decreasing the Size of the InnoDB System Tablespace*

You cannot remove a data file from the system tablespace.  To decrease
the system tablespace size, use this procedure:

  1. Use 'mysqldump' to dump all your 'InnoDB' tables,
     including 'InnoDB' tables located in the MySQL database.  As of
     5.6, there are five 'InnoDB' tables included in the MySQL database:

          mysql> SELECT TABLE_NAME from INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA='mysql' and ENGINE='InnoDB';
          +---------------------------+
          | TABLE_NAME                |
          +---------------------------+
          | engine_cost               |
          | gtid_executed             |
          | help_category             |
          | help_keyword              |
          | help_relation             |
          | help_topic                |
          | innodb_index_stats        |
          | innodb_table_stats        |
          | plugin                    |
          | server_cost               |
          | servers                   |
          | slave_master_info         |
          | slave_relay_log_info      |
          | slave_worker_info         |
          | time_zone                 |
          | time_zone_leap_second     |
          | time_zone_name            |
          | time_zone_transition      |
          | time_zone_transition_type |
          +---------------------------+

  2. Stop the server.

  3. Remove all the existing tablespace files ('*.ibd'), including the
     'ibdata' and 'ib_log' files.  Do not forget to remove '*.ibd' files
     for tables located in the MySQL database.

  4. Remove any '.frm' files for 'InnoDB' tables.

  5. Configure a new tablespace.

  6. Restart the server.

  7. Import the dump files.

*Note*:

If your databases only use the 'InnoDB' engine, it may be simpler to
dump *all* databases, stop the server, remove all databases and 'InnoDB'
log files, restart the server, and import the dump files.

14.7.2 Changing the Number or Size of InnoDB Redo Log Files
-----------------------------------------------------------

To change the number or the size of your 'InnoDB' redo log files,
perform the following steps:

  1. Stop the MySQL server and make sure that it shuts down without
     errors.

  2. Edit 'my.cnf' to change the log file configuration.  To change the
     log file size, configure 'innodb_log_file_size'.  To increase the
     number of log files, configure 'innodb_log_files_in_group'.

  3. Start the MySQL server again.

If 'InnoDB' detects that the 'innodb_log_file_size' differs from the
redo log file size, it writes a log checkpoint, closes and removes the
old log files, creates new log files at the requested size, and opens
the new log files.

14.7.3 Using Raw Disk Partitions for the System Tablespace
----------------------------------------------------------

You can use raw disk partitions as data files in the 'InnoDB' system
tablespace.  This technique enables nonbuffered I/O on Windows and on
some Linux and Unix systems without file system overhead.  Perform tests
with and without raw partitions to verify whether this change actually
improves performance on your system.

When you use a raw disk partition, ensure that the user ID that runs the
MySQL server has read and write privileges for that partition.  For
example, if you run the server as the 'mysql' user, the partition must
be readable and writeable by 'mysql'.  If you run the server with the
'--memlock' option, the server must be run as 'root', so the partition
must be readable and writeable by 'root'.

The procedures described below involve option file modification.  For
additional information, see option-files.

*Allocating a Raw Disk Partition on Linux and Unix Systems*

  1. When you create a new data file, specify the keyword 'newraw'
     immediately after the data file size for the
     'innodb_data_file_path' option.  The partition must be at least as
     large as the size that you specify.  Note that 1MB in 'InnoDB' is
     1024 x 1024 bytes, whereas 1MB in disk specifications usually means
     1,000,000 bytes.

          [mysqld]
          innodb_data_home_dir=
          innodb_data_file_path=/dev/hdd1:3Gnewraw;/dev/hdd2:2Gnewraw

  2. Restart the server.  'InnoDB' notices the 'newraw' keyword and
     initializes the new partition.  However, do not create or change
     any 'InnoDB' tables yet.  Otherwise, when you next restart the
     server, 'InnoDB' reinitializes the partition and your changes are
     lost.  (As a safety measure 'InnoDB' prevents users from modifying
     data when any partition with 'newraw' is specified.)

  3. After 'InnoDB' has initialized the new partition, stop the server,
     change 'newraw' in the data file specification to 'raw':

          [mysqld]
          innodb_data_home_dir=
          innodb_data_file_path=/dev/hdd1:3Graw;/dev/hdd2:2Graw

  4. Restart the server.  'InnoDB' now permits changes to be made.

*Allocating a Raw Disk Partition on Windows*

On Windows systems, the same steps and accompanying guidelines described
for Linux and Unix systems apply except that the 'innodb_data_file_path'
setting differs slightly on Windows.

  1. When you create a new data file, specify the keyword 'newraw'
     immediately after the data file size for the
     'innodb_data_file_path' option:

          [mysqld]
          innodb_data_home_dir=
          innodb_data_file_path=//./D::10Gnewraw

     The '//./' corresponds to the Windows syntax of '\\.\' for
     accessing physical drives.  In the example above, 'D:' is the drive
     letter of the partition.

  2. Restart the server.  'InnoDB' notices the 'newraw' keyword and
     initializes the new partition.

  3. After 'InnoDB' has initialized the new partition, stop the server,
     change 'newraw' in the data file specification to 'raw':

          [mysqld]
          innodb_data_home_dir=
          innodb_data_file_path=//./D::10Graw

  4. Restart the server.  'InnoDB' now permits changes to be made.

14.7.4 InnoDB File-Per-Table Tablespaces
----------------------------------------

Historically, all 'InnoDB' tables and indexes were stored in the system
tablespace.  This monolithic approach was targeted at machines dedicated
entirely to database processing, with carefully planned data growth,
where any disk storage allocated to MySQL would never be needed for
other purposes.  'InnoDB''s file-per-table tablespace feature provides a
more flexible alternative, where each 'InnoDB' table and its indexes are
stored in a separate '.ibd' data file.  Each such '.ibd' data file
represents an individual tablespace.  This feature is controlled by the
'innodb_file_per_table' configuration option, which is enabled by
default in MySQL 5.6.6 and higher.

*Advantages of File-Per-Table Tablespaces*

   * You can reclaim disk space when truncating or dropping a table
     stored in a file-per-table tablepace.  Truncating or dropping
     tables stored in the shared system tablespace creates free space
     internally in the system tablespace data files (ibdata files) which
     can only be used for new 'InnoDB' data.

     Similarly, a table-copying 'ALTER TABLE'.
     operation on table that resides in a shared tablespace can increase
     the amount of space used by the tablespace.  Such operations may
     require as much additional space as the data in the table plus
     indexes.  The additional space required for the table-copying
     'ALTER TABLE' operation is not released back to the
     operating system as it is for file-per-table tablespaces.

   * The 'TRUNCATE TABLE' operation is faster
     when run on tables stored in file-per-table tablepaces.

   * You can store specific tables on separate storage devices, for I/O
     optimization, space management, or backup purposes.  In previous
     releases, you had to move entire database directories to other
     drives and create symbolic links in the MySQL data directory, as
     described in symbolic-links.  In MySQL 5.6.6 and higher,
     you can specify the location of each table using the syntax 'CREATE
     TABLE ... DATA DIRECTORY = ABSOLUTE_PATH_TO_DIRECTORY', as
     explained in tablespace-placing.

   * You can run 'OPTIMIZE TABLE' to compact or
     recreate a file-per-table tablespace.  When you run an
     'OPTIMIZE TABLE', 'InnoDB' creates a new '.ibd'
     file with a temporary name, using only the space required to store
     actual data.  When the optimization is complete, 'InnoDB' removes
     the old '.ibd' file and replaces it with the new one.  If the
     previous '.ibd' file grew significantly but the actual data only
     accounted for a portion of its size, running 'OPTIMIZE TABLE'
     can reclaim the unused space.

   * You can move individual 'InnoDB' tables rather than entire
     databases.

   * You can copy individual 'InnoDB' tables from one MySQL instance to
     another (known as the transportable tablespace feature).

   * Tables created in file-per-table tablespaces use the Barracuda file
     format.  The Barracuda file format enables features such as
     compressed and dynamic row formats.

   * You can enable more efficient storage for tables with large 'BLOB'
     or 'TEXT' columns using the dynamic row format.

   * File-per-table tablespaces may improve chances for a successful
     recovery and save time when a corruption occurs, when a server
     cannot be restarted, or when backup and binary logs are
     unavailable.

   * You can back up or restore individual tables quickly using the
     MySQL Enterprise Backup product, without interrupting the use of
     other 'InnoDB' tables.  This is beneficial if you have tables that
     require backup less frequently or on a different backup schedule.
     See Making a Partial Backup
     (http://dev.mysql.com/doc/mysql-enterprise-backup/4.1/en/partial.html)
     for details.

   * File-per-table tablespaces are convenient for per-table status
     reporting when copying or backing up tables.

   * You can monitor table size at a file system level, without
     accessing MySQL.

   * Common Linux file systems do not permit concurrent writes to a
     single file when 'innodb_flush_method' is set to 'O_DIRECT'.  As a
     result, there are possible performance improvements when using
     file-per-table tablespaces in conjunction with
     'innodb_flush_method'.

   * The system tablespace stores the data dictionary and undo logs, and
     is limited in size by 'InnoDB' tablespace size limits.  See
     innodb-restrictions.  With file-per-table tablespaces, each table
     has its own tablespace, which provides room for growth.

*Potential Disadvantages of File-Per-Table Tablespaces*

   * With file-per-table tablespaces, each table may have unused space,
     which can only be utilized by rows of the same table.  This could
     lead to wasted space if not properly managed.

   * 'fsync' operations must run on each open table rather than on a
     single file.  Because there is a separate 'fsync' operation for
     each file, write operations on multiple tables cannot be combined
     into a single I/O operation.  This may require 'InnoDB' to perform
     a higher total number of 'fsync' operations.

   * 'mysqld' must keep one open file handle per table,
     which may impact performance if you have numerous tables in
     file-per-table tablespaces.

   * More file descriptors are used.

   * 'innodb_file_per_table' is enabled by default in MySQL 5.6.6 and
     higher.  You may consider disabling it if backward compatibility
     with MySQL 5.5 or 5.1 is a concern.  Disabling
     'innodb_file_per_table' prevents 'ALTER TABLE'.
     from moving an 'InnoDB' table from the system tablespace to an
     individual '.ibd' file in cases where 'ALTER TABLE'
     recreates the table ('ALGORITHM=COPY').

     For example, when restructuring the clustered index for an 'InnoDB'
     table, the table is re-created using the current setting for
     'innodb_file_per_table'.  This behavior does not apply when adding
     or dropping 'InnoDB' secondary indexes.  When a secondary index is
     created without rebuilding the table, the index is stored in the
     same file as the table data, regardless of the current
     'innodb_file_per_table' setting.  This behavior also does not apply
     to tables added to the system tablespace using 'CREATE TABLE ... TABLESPACE'
     or 'ALTER TABLE ... TABLESPACE'
     syntax.  These tables are not affected by
     the 'innodb_file_per_table' setting.

   * If many tables are growing there is potential for more
     fragmentation which can impede 'DROP TABLE' and
     table scan performance.  However, when fragmentation is managed,
     having files in their own tablespace can improve performance.

   * The buffer pool is scanned when dropping a file-per-table
     tablespace, which can take several seconds for buffer pools that
     are tens of gigabytes in size.  The scan is performed with a broad
     internal lock, which may delay other operations.  Tables in the
     system tablespace are not affected.

   * The 'innodb_autoextend_increment' variable, which defines increment
     size (in MB) for extending the size of an auto-extending shared
     tablespace file when it becomes full, does not apply to
     file-per-table tablespace files, which are auto-extending
     regardless of the 'innodb_autoextend_increment' setting.  The
     initial extensions are by small amounts, after which extensions
     occur in increments of 4MB.

14.7.4.1 Enabling and Disabling File-Per-Table Tablespaces
..........................................................

The 'innodb_file_per_table' option is enabled by default.

To set the 'innodb_file_per_table' option at startup, start the server
with the '--innodb_file_per_table' command-line option, or add this line
to the '[mysqld]' section of 'my.cnf':

     [mysqld]
     innodb_file_per_table=1

You can also set 'innodb_file_per_table' dynamically, while the server
is running:

     mysql> SET GLOBAL innodb_file_per_table=1;

With 'innodb_file_per_table' enabled, you can store 'InnoDB' tables in a
'TBL_NAME.ibd' file.  Unlike the 'MyISAM' storage engine, with its
separate 'TBL_NAME.MYD' and 'TBL_NAME.MYI' files for indexes and data,
'InnoDB' stores the data and the indexes together in a single '.ibd'
file.  The 'TBL_NAME.frm' file is still created as usual.

If you disable 'innodb_file_per_table' in your startup options and
restart the server, or disable it with the 'SET GLOBAL' command,
'InnoDB' creates new tables inside the system tablespace unless you have
explicitly placed the table in file-per-table tablespace or general
tablespace using the 'CREATE TABLE ... TABLESPACE'.
option.

You can always read and write any 'InnoDB' tables, regardless of the
file-per-table setting.

To move a table from the system tablespace to its own tablespace, change
the 'innodb_file_per_table' setting and rebuild the table:

     mysql> SET GLOBAL innodb_file_per_table=1;
     mysql> ALTER TABLE TABLE_NAME ENGINE=InnoDB;

Tables added to the system tablespace using 'CREATE TABLE ... TABLESPACE'
or 'ALTER TABLE ... TABLESPACE'
syntax are not affected by the 'innodb_file_per_table'
setting.  To move these tables from the system tablespace to a
file-per-table tablespace, they must be moved explicitly using
'ALTER TABLE ... TABLESPACE' syntax.

*Note*:

'InnoDB' always needs the system tablespace because it puts its internal
data dictionary and undo logs there.  The '.ibd' files are not
sufficient for 'InnoDB' to operate.

When a table is moved out of the system tablespace into its own '.ibd'
file, the data files that make up the system tablespace remain the same
size.  The space formerly occupied by the table can be reused for new
'InnoDB' data, but is not reclaimed for use by the operating system.
When moving large 'InnoDB' tables out of the system tablespace, where
disk space is limited, you may prefer to enable 'innodb_file_per_table'
and recreate the entire instance using the 'mysqldump'.
command.  As mentioned above, tables added to the system tablespace
using 'CREATE TABLE ... TABLESPACE' or 'ALTER TABLE ... TABLESPACE'
syntax are not affected by the
'innodb_file_per_table' setting.  These tables must be moved
individually.

14.7.5 Creating File-Per-Table Tablespaces Outside the Data Directory
---------------------------------------------------------------------

To create a file-per-table tablespace in a location outside the MySQL
data directory, use the 'DATA DIRECTORY = ABSOLUTE_PATH_TO_DIRECTORY'
clause of the 'CREATE TABLE' statement.

Plan the location in advance, because you cannot use the 'DATA
DIRECTORY' clause with the 'ALTER TABLE' statement
to change the location later.  The directory you specify could be on
another storage device with particular performance or capacity
characteristics, such as a fast SSD or a high-capacity HDD.

Within the target directory, MySQL creates a subdirectory corresponding
to the database name, and within that, a .ibd file for the new table.
In the database directory beneath the MySQL 'DATADIR' directory, MySQL
creates a 'TABLE_NAME.isl' file containing the path name for the table.
The .isl file is treated by MySQL like a symbolic link.  (see Using actual symbolic links
has never been supported for
'InnoDB' tables.)

The following example demonstrates creating a file-per-table tablespace
outside the MySQL data directory.  It shows the '.ibd' file created in
the specified directory, and the '.isl' file created in the database
directory beneath the MySQL data directory.

     mysql> USE test;
     Database changed

     mysql> SHOW VARIABLES LIKE 'innodb_file_per_table';
     +-----------------------+-------+
     | Variable_name         | Value |
     +-----------------------+-------+
     | innodb_file_per_table | ON    |
     +-----------------------+-------+

     mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY) DATA DIRECTORY = '/ALTERNATIVE/DIRECTORY';

     # MySQL creates a .ibd file for the new table in a subdirectory that corresponding
     # to the database name

     db_user@ubuntu:~/alternative/directory/test$ ls
     t1.ibd

     # MySQL creates a .isl file containing the path name for the table in a directory
     # beneath the MySQL data directory

     db_user@ubuntu:~/mysql/data/test$ ls
     db.opt  t1.frm  t1.isl

You can also use 'CREATE TABLE ... TABLESPACE' in
combination with the 'DATA DIRECTORY' clause to create a file-per-table
tablespace outside the MySQL data directory.  To do so, you must specify
'innodb_file_per_table' as the tablespace name.

     mysql> CREATE TABLE t2 (c1 INT PRIMARY KEY) TABLESPACE = innodb_file_per_table
            DATA DIRECTORY = '/alternative/directory';

You do not have to enable 'innodb_file_per_table' when using this
method.

*Usage Notes:*

   * MySQL initially holds the '.ibd' file open, preventing you from
     dismounting the device, but might eventually close the table if the
     server is busy.  Be careful not to accidentally dismount an
     external device while MySQL is running, or start MySQL while the
     device is disconnected.  Attempting to access a table when the
     associated '.ibd' file is missing causes a serious error that
     requires a server restart.

     A server restart might fail if the '.ibd' file is still not at the
     expected path.  In this case, manually remove the 'TABLE_NAME.isl'
     file in the database directory, and after restarting perform a
     'DROP TABLE' to delete the '.frm' file and
     remove the information about the table from the data dictionary.

   * Before placing tables on an NFS-mounted volume, review potential
     issues outlined in disk-issues-nfs.

   * If you use an LVM snapshot, file copy, or other file-based
     mechanism to back up the '.ibd' file, always use the 'FLUSH TABLES
     ... FOR EXPORT' statement first to make sure that all changes
     buffered in memory are flushed to disk before the backup occurs.

   * The 'DATA DIRECTORY' clause is a supported alternative to
     using symbolic links, which is not supported for
     individual 'InnoDB' tables.

14.7.6 Copying File-Per-Table Tablespaces to Another Instance
-------------------------------------------------------------

This section describes how to copy a file-per-table tablespace from one
MySQL instance to another, otherwise known as the Transportable
Tablespaces feature.

For information about other 'InnoDB' table copying methods, see
innodb-migration.

There are many reasons why you might copy an 'InnoDB' file-per-table
tablespace to a different instance:

   * To run reports without putting extra load on a production server.

   * To set up identical data for a table on a new slave server.

   * To restore a backed-up version of a table or partition after a
     problem or mistake.

   * As a faster way of moving data around than importing the results of
     a 'mysqldump' command.  The data is available
     immediately, rather than having to be re-inserted and the indexes
     rebuilt.

   * To move a file-per-table tablespace to a server with storage medium
     that better suits system requirements.  For example, you may want
     to have busy tables on an SSD device, or large tables on a
     high-capacity HDD device.

*Limitations and Usage Notes*

   * The tablespace copy procedure is only possible when
     'innodb_file_per_table' is set to 'ON', which is the default
     setting.  Tables residing in the shared system tablespace cannot be
     quiesced.

   * When a table is quiesced, only read-only transactions are allowed
     on the affected table.

   * When importing a tablespace, the page size must match the page size
     of the importing instance.

   * 'DISCARD TABLESPACE' is not supported for tablespaces with a
     parent-child (primary key-foreign key) relationship when
     'foreign_key_checks' is set to '1'.  Before discarding a tablespace
     for parent-child tables, set 'foreign_key_checks=0'.  Partitioned
     'InnoDB' tables do not support foreign keys.

   * 'ALTER TABLE ... IMPORT TABLESPACE' does not
     enforce foreign key constraints on imported data.  If there are
     foreign key constraints between tables, all tables should be
     exported at the same (logical) point in time.  Partitioned 'InnoDB'
     tables do not support foreign keys.

   * 'ALTER TABLE ... IMPORT TABLESPACE' and
     'ALTER TABLE ... IMPORT PARTITION ... TABLESPACE' do
     not require a '.cfg' metadata file to import a tablespace.
     However, metadata checks are not performed when importing without a
     '.cfg' file, and a warning similar to the following is issued:

          Message: InnoDB: IO Read error: (2, No such file or directory) Error opening '.\
          test\t.cfg', will attempt to import without schema verification
          1 row in set (0.00 sec)

     The ability to import without a '.cfg' file may be more convenient
     when no schema mismatches are expected.  Additionally, the ability
     to import without a '.cfg' file could be useful in crash recovery
     scenarios in which metadata cannot be collected from an '.ibd'
     file.

   * Due to a '.cfg' metadata file limitation, schema mismatches are not
     reported for partition type or partition definition differences
     when importing tablespace files for partitioned tables.  Column
     differences are reported.

   * When running 'ALTER TABLE ... DISCARD PARTITION ... TABLESPACE'
     and 'ALTER TABLE ... IMPORT PARTITION ... TABLESPACE'
     on subpartitioned tables,
     both partition and subpartition table names are allowed.  When a
     partition name is specified, subpartitions of that partition are
     included in the operation.

   * Importing a tablespace file from another MySQL server instance
     works if both instances have GA (General Availability) status and
     their versions are within the same series.  Otherwise, the file
     must have been created on the same server instance into which it is
     imported.

   * In replication scenarios, 'innodb_file_per_table' must be set to
     'ON' on both the master and slave.

   * On Windows, 'InnoDB' stores database, tablespace, and table names
     internally in lowercase.  To avoid import problems on
     case-sensitive operating systems such as Linux and UNIX, create all
     databases, tablespaces, and tables using lowercase names.  A
     convenient way to accomplish this is to add the following line to
     the '[mysqld]' section of your 'my.cnf' or 'my.ini' file before
     creating databases, tablespaces, or tables:

          [mysqld]
          lower_case_table_names=1

   * 'ALTER TABLE ... DISCARD TABLESPACE' and
     'ALTER TABLE ...IMPORT TABLESPACE' are not supported
     with tables that belong to an 'InnoDB' general tablespace.  For
     more information, see 'CREATE TABLESPACE'.

   * The default row format for 'InnoDB' tables is configurable using
     the 'innodb_default_row_format' configuration option.  Attempting
     to import a table that does not explicitly define a row format
     ('ROW_FORMAT'), or that uses 'ROW_FORMAT=DEFAULT', could result in
     a schema mismatch error if the 'innodb_default_row_format' setting
     on the source instance differs from the setting on the destination
     instance.  For related information, see
     innodb-row-format-specification.

   * When exporting a tablespace that is encrypted using the 'InnoDB'
     tablespace encryption feature, 'InnoDB' generates a '.cfp' file in
     addition to a '.cfg' metadata file.  The '.cfp' file must be copied
     to the destination instance together with the '.cfg' file and
     tablespace file before performing the 'ALTER TABLE ... IMPORT TABLESPACE'
     operation on the destination instance.
     The '.cfp' file contains a transfer key and an encrypted tablespace
     key.  On import, 'InnoDB' uses the transfer key to decrypt the
     tablespace key.  For related information, see
     innodb-tablespace-encryption.

14.7.6.1 Transportable Tablespace Examples
..........................................

*Note*:

If you are transporting tables that are encrypted using the 'InnoDB'
tablespace encryption, see
innodb-transportable-tablespace-limitations before you begin for
additional procedural information.

*Example 1: Copying an InnoDB Table to Another Instance*

This procedure demonstrates how to copy a regular 'InnoDB' table from a
running MySQL server instance to another running instance.  The same
procedure with minor adjustments can be used to perform a full table
restore on the same instance.

  1. On the source instance, create a table if one does not exist:

          mysql> USE test;
          mysql> CREATE TABLE t(c1 INT) ENGINE=InnoDB;

  2. On the destination instance, create a table if one does not exist:

          mysql> USE test;
          mysql> CREATE TABLE t(c1 INT) ENGINE=InnoDB;

  3. On the destination instance, discard the existing tablespace.
     (Before a tablespace can be imported, 'InnoDB' must discard the
     tablespace that is attached to the receiving table.)

          mysql> ALTER TABLE t DISCARD TABLESPACE;

  4. On the source instance, run 'FLUSH TABLES ... FOR EXPORT' to
     quiesce the table and create the '.cfg' metadata file:

          mysql> USE test;
          mysql> FLUSH TABLES t FOR EXPORT;

     The metadata ('.cfg') is created in the 'InnoDB' data directory.

     *Note*:

     The 'FLUSH TABLES ... FOR EXPORT' statement ensures that changes to
     the named table have been flushed to disk so that a binary table
     copy can be made while the instance is running.  When 'FLUSH TABLES
     ... FOR EXPORT' is run, 'InnoDB' produces a '.cfg' file in the same
     database directory as the table.  The '.cfg' file contains metadata
     used for schema verification when importing the tablespace file.

  5. Copy the '.ibd' file and '.cfg' metadata file from the source
     instance to the destination instance.  For example:

          shell> scp /PATH/TO/DATADIR/test/t.{ibd,cfg} destination-server:/PATH/TO/DATADIR/test

     *Note*:

     The '.ibd' file and '.cfg' file must be copied before releasing the
     shared locks, as described in the next step.

  6. On the source instance, use 'UNLOCK TABLES' to
     release the locks acquired by 'FLUSH TABLES ... FOR EXPORT':

          mysql> USE test;
          mysql> UNLOCK TABLES;

  7. On the destination instance, import the tablespace:

          mysql> USE test;
          mysql> ALTER TABLE t IMPORT TABLESPACE;

     *Note*:

     The 'ALTER TABLE ... IMPORT TABLESPACE' feature
     does not enforce foreign key constraints on imported data.  If
     there are foreign key constraints between tables, all tables should
     be exported at the same (logical) point in time.  In this case you
     would stop updating the tables, commit all transactions, acquire
     shared locks on the tables, and then perform the export operation.

*Example 2: Copying an InnoDB Partitioned Table to Another Instance*

This procedure demonstrates how to copy a partitioned 'InnoDB' table
from a running MySQL server instance to another running instance.  The
same procedure with minor adjustments can be used to perform a full
restore of a partitioned 'InnoDB' table on the same instance.

  1. On the source instance, create a partitioned table if one does not
     exist.  In the following example, a table with three partitions
     (p0, p1, p2) is created:

          mysql> USE test;
          mysql> CREATE TABLE t1 (i int) ENGINE = InnoDB PARTITION BY KEY (i) PARTITIONS 3;

     In the '/DATADIR/test' directory, there is a separate tablespace
     ('.ibd') file for each of the three partitions.

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt  t1.frm  t1#P#p0.ibd  t1#P#p1.ibd  t1#P#p2.ibd

  2. On the destination instance, create the same partitioned table:

          mysql> USE test;
          mysql> CREATE TABLE t1 (i int) ENGINE = InnoDB PARTITION BY KEY (i) PARTITIONS 3;

     In the '/DATADIR/test' directory, there is a separate tablespace
     ('.ibd') file for each of the three partitions.

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt  t1.frm  t1#P#p0.ibd  t1#P#p1.ibd  t1#P#p2.ibd

  3. On the destination instance, discard the tablespace for the
     partitioned table.  (Before the tablespace can be imported on the
     destination instance, the tablespace that is attached to the
     receiving table must be discarded.)

          mysql> ALTER TABLE t1 DISCARD TABLESPACE;

     The three '.ibd' files that make up the tablespace for the
     partitioned table are discarded from the '/DATADIR/test' directory,
     leaving the following files:

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt  t1.frm

  4. On the source instance, run 'FLUSH TABLES ... FOR EXPORT' to
     quiesce the partitioned table and create the '.cfg' metadata files:

          mysql> USE test;
          mysql> FLUSH TABLES t1 FOR EXPORT;

     Metadata ('.cfg') files, one for each tablespace ('.ibd') file, are
     created in the '/DATADIR/test' directory on the source instance:

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt t1#P#p0.ibd  t1#P#p1.ibd  t1#P#p2.ibd
          t1.frm  t1#P#p0.cfg  t1#P#p1.cfg  t1#P#p2.cfg

     *Note*:

     'FLUSH TABLES ... FOR EXPORT' statement ensures that changes to the
     named table have been flushed to disk so that binary table copy can
     be made while the instance is running.  When 'FLUSH TABLES ... FOR
     EXPORT' is run, 'InnoDB' produces a '.cfg' metadata file for the
     table's tablespace files in the same database directory as the
     table.  The '.cfg' files contain metadata used for schema
     verification when importing tablespace files.  'FLUSH TABLES ...
     FOR EXPORT' can only be run on the table, not on individual table
     partitions.

  5. Copy the '.ibd' and '.cfg' files from the source instance database
     directory to the destination instance database directory.  For
     example:

          shell>scp /PATH/TO/DATADIR/test/t1*.{ibd,cfg} destination-server:/PATH/TO/DATADIR/test

     *Note*:

     The '.ibd' and '.cfg' files must be copied before releasing the
     shared locks, as described in the next step.

  6. On the source instance, use 'UNLOCK TABLES' to
     release the locks acquired by 'FLUSH TABLES ... FOR EXPORT':

          mysql> USE test;
          mysql> UNLOCK TABLES;

  7. On the destination instance, import the tablespace for the
     partitioned table:

          mysql> USE test;
          mysql> ALTER TABLE t1 IMPORT TABLESPACE;

*Example 3: Copying InnoDB Table Partitions to Another Instance*

This procedure demonstrates how to copy 'InnoDB' table partitions from a
running MySQL server instance to another running instance.  The same
procedure with minor adjustments can be used to perform a restore of
'InnoDB' table partitions on the same instance.  In the following
example, a partitioned table with four partitions (p0, p1, p2, p3) is
created on the source instance.  Two of the partitions (p2 and p3) are
copied to the destination instance.

  1. On the source instance, create a partitioned table if one does not
     exist.  In the following example, a table with four partitions (p0,
     p1, p2, p3) is created:

          mysql> USE test;
          mysql> CREATE TABLE t1 (i int) ENGINE = InnoDB PARTITION BY KEY (i) PARTITIONS 4;

     In the '/DATADIR/test' directory, there is a separate tablespace
     ('.ibd') file for each of the four partitions.

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt  t1.frm  t1#P#p0.ibd  t1#P#p1.ibd  t1#P#p2.ibd t1#P#p3.ibd

  2. On the destination instance, create the same partitioned table:

          mysql> USE test;
          mysql> CREATE TABLE t1 (i int) ENGINE = InnoDB PARTITION BY KEY (i) PARTITIONS 4;

     In the '/DATADIR/test' directory, there is a separate tablespace
     ('.ibd') file for each of the four partitions.

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt  t1.frm  t1#P#p0.ibd  t1#P#p1.ibd  t1#P#p2.ibd t1#P#p3.ibd

  3. On the destination instance, discard the tablespace partitions that
     you plan to import from the source instance.  (Before tablespace
     partitions can be imported on the destination instance, the
     corresponding partitions that are attached to the receiving table
     must be discarded.)

          mysql> ALTER TABLE t1 DISCARD PARTITION p2, p3 TABLESPACE;

     The '.ibd' files for the two discarded partitions are removed from
     the '/DATADIR/test' directory on the destination instance, leaving
     the following files:

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt  t1.frm  t1#P#p0.ibd  t1#P#p1.ibd

     *Note*:

     When 'ALTER TABLE ... DISCARD PARTITION ... TABLESPACE'
     is run on subpartitioned tables, both partition and
     subpartition table names are allowed.  When a partition name is
     specified, subpartitions of that partition are included in the
     operation.

  4. On the source instance, run 'FLUSH TABLES ... FOR EXPORT' to
     quiesce the partitioned table and create the '.cfg' metadata files.

          mysql> USE test;
          mysql> FLUSH TABLES t1 FOR EXPORT;

     The metadata files ('.cfg' files) are created in the
     '/DATADIR/test' directory on the source instance.  There is a
     '.cfg' file for each tablespace ('.ibd') file.

          mysql> \! ls /PATH/TO/DATADIR/test/
          db.opt  t1#P#p0.ibd  t1#P#p1.ibd  t1#P#p2.ibd t1#P#p3.ibd
          t1.frm  t1#P#p0.cfg  t1#P#p1.cfg  t1#P#p2.cfg t1#P#p3.cfg

     *Note*:

     'FLUSH TABLES ... FOR EXPORT' statement ensures that changes to the
     named table have been flushed to disk so that binary table copy can
     be made while the instance is running.  When 'FLUSH TABLES ... FOR
     EXPORT' is run, 'InnoDB' produces a '.cfg' metadata file for the
     table's tablespace files in the same database directory as the
     table.  The '.cfg' files contain metadata used for schema
     verification when importing tablespace files.  'FLUSH TABLES ...
     FOR EXPORT' can only be run on the table, not on individual table
     partitions.

  5. Copy the '.ibd' and '.cfg' files from the source instance database
     directory to the destination instance database directory.  In this
     example, only the '.ibd' and '.cfg' files for partition 2 (p2) and
     partition 3 (p3) are copied to the 'data' directory on the
     destination instance.  Partition 0 (p0) and partition 1 (p1) remain
     on the source instance.

          shell> scp t1#P#p2.ibd  t1#P#p2.cfg t1#P#p3.ibd t1#P#p3.cfg destination-server:/PATH/TO/DATADIR/test

     *Note*:

     The '.ibd' files and '.cfg' files must be copied before releasing
     the shared locks, as described in the next step.

  6. On the source instance, use 'UNLOCK TABLES' to
     release the locks acquired by 'FLUSH TABLES ... FOR EXPORT':

          mysql> USE test;
          mysql> UNLOCK TABLES;

  7. On the destination instance, import the tablespace partitions (p2
     and p3):

          mysql> USE test;
          mysql> ALTER TABLE t1 IMPORT PARTITION p2, p3 TABLESPACE;

     *Note*:

     When 'ALTER TABLE ... IMPORT PARTITION ... TABLESPACE'
     is run on subpartitioned tables, both partition and
     subpartition table names are allowed.  When a partition name is
     specified, subpartitions of that partition are included in the
     operation.

14.7.6.2 Transportable Tablespace Internals
...........................................

The following information describes internals and error log messaging
for the transportable tablespaces copy procedure for a regular 'InnoDB'
table.

When 'ALTER TABLE ... DISCARD TABLESPACE' is run on
the destination instance:

   * The table is locked in X mode.

   * The tablespace is detached from the table.

When 'FLUSH TABLES ... FOR EXPORT' is run on the source instance:

   * The table being flushed for export is locked in shared mode.

   * The purge coordinator thread is stopped.

   * Dirty pages are synchronized to disk.

   * Table metadata is written to the binary '.cfg' file.

Expected error log messages for this operation:

     2013-09-24T13:10:19.903526Z 2 [Note] InnoDB: Sync to disk of '"test"."t"' started.
     2013-09-24T13:10:19.903586Z 2 [Note] InnoDB: Stopping purge
     2013-09-24T13:10:19.903725Z 2 [Note] InnoDB: Writing table metadata to './test/t.cfg'
     2013-09-24T13:10:19.904014Z 2 [Note] InnoDB: Table '"test"."t"' flushed to disk

When 'UNLOCK TABLES' is run on the source instance:

   * The binary .cfg file is deleted.

   * The shared lock on the table or tables being imported is released
     and the purge coordinator thread is restarted.

Expected error log messages for this operation:

     2013-09-24T13:10:21.181104Z 2 [Note] InnoDB: Deleting the meta-data file './test/t.cfg'
     2013-09-24T13:10:21.181180Z 2 [Note] InnoDB: Resuming purge

When 'ALTER TABLE ... IMPORT TABLESPACE' is run on
the destination instance, the import algorithm performs the following
operations for each tablespace being imported:

   * Each tablespace page is checked for corruption.

   * The space ID and log sequence numbers (LSNs) on each page are
     updated

   * Flags are validated and LSN updated for the header page.

   * Btree pages are updated.

   * The page state is set to dirty so that it is written to disk.

Expected error log messages for this operation:

     2013-07-18 15:15:01 34960 [Note] InnoDB: Importing tablespace for table 'test/t' that was exported from host 'ubuntu'
     2013-07-18 15:15:01 34960 [Note] InnoDB: Phase I - Update all pages
     2013-07-18 15:15:01 34960 [Note] InnoDB: Sync to disk
     2013-07-18 15:15:01 34960 [Note] InnoDB: Sync to disk - done!
     2013-07-18 15:15:01 34960 [Note] InnoDB: Phase III - Flush changes to disk
     2013-07-18 15:15:01 34960 [Note] InnoDB: Phase IV - Flush complete

*Note*:

You may also receive a warning that a tablespace is discarded (if you
discarded the tablespace for the destination table) and a message
stating that statistics could not be calculated due to a missing '.ibd'
file:

     2013-07-18 15:14:38 34960 [Warning] InnoDB: Table "test"."t" tablespace is set as discarded.
     2013-07-18 15:14:38 7f34d9a37700 InnoDB: cannot calculate statistics for table "test"."t" because the .ibd file is missing. For help, please refer to
     http://dev.mysql.com/doc/refman/5.7/en/innodb-troubleshooting.html

14.7.7 Configuring Undo Tablespaces
-----------------------------------

Undo logs may be stored in one or more undo tablespaces instead of the
system tablespace.  This layout differs from the default configuration
in which undo logs reside in the system tablespace.  The I/O patterns
for undo logs make undo tablespaces good candidates for SSD storage,
while keeping the system tablespace on hard disk storage.  Undo
tablespaces or individual segments inside those tablespaces cannot be
dropped.  However, undo logs stored in undo tablespaces can be
truncated.  For more information, see truncate-undo-tablespace.

To configure separate undo tablespaces for a MySQL instance, perform the
following steps.  It is assumed that you are performing the procedure on
a test instance prior to deploying the configuration to a production
system.

*Important*:

The number of undo tablespaces may only be configured when initializing
a new MySQL instance, as the 'innodb_undo_tablespaces' option can only
be set at initialization time.  The specified setting is fixed for the
life of the MySQL instance.

*Note*:

'innodb_undo_tablespaces' is deprecated and will be removed in a future
release.

  1. Specify a directory location for undo tablespaces using the
     'innodb_undo_directory' configuration option.  If a directory
     location is not specified, undo tablespaces are created in the
     MySQL data directory.

  2. Define the number of rollback segments using the
     'innodb_rollback_segments' configuration option.  Start with a
     relatively low value and increase it incrementally over time to
     examine the effect on performance.  The default setting for
     'innodb_rollback_segments' is 128, which is also the maximum value.

     One rollback segment is always assigned to the system tablespace,
     and 32 rollback segments are reserved for the temporary tablespace
     ('ibtmp1').  Therefore, to allocate rollback segments to undo
     tablespaces, set 'innodb_rollback_segments' to a value greater than
     33.  For example, if you have two undo tablespaces, set
     'innodb_rollback_segments' to 35 to assign one rollback segment to
     each of the two undo tablespaces.  Rollback segments are
     distributed among undo tablespaces in a circular fashion.

     When you configure separate undo tablespaces, the rollback segment
     in the system tablespace is rendered inactive.

  3. Define the number of undo tablespaces using the
     'innodb_undo_tablespaces' option.  This setting is fixed for the
     life of the MySQL instance, so if you are uncertain about the
     optimal value, estimate on the high side.

  4. Create a new MySQL test instance using the option values you have
     chosen.

  5. Use a realistic workload on your test instance with data volume
     similar to your production servers to test the configuration.

  6. Benchmark the performance of I/O intensive workloads.

  7. Periodically increase the value of 'innodb_rollback_segments' and
     rerun performance tests until there are no further improvements in
     I/O performance.

14.7.8 Truncating Undo Tablespaces
----------------------------------

To truncate undo tablespaces, the MySQL instance must be configured with
a minimum of two undo tablespaces.  A minimum of two undo tablespaces
ensures that one undo tablespace remains active while the other is taken
offline to be truncated.  The number of undo tablespaces is defined by
the 'innodb_undo_tablespaces' option.  The default value is 0.  Use this
statement to check the value of 'innodb_undo_tablespaces':

     mysql> SELECT @@innodb_undo_tablespaces;
     +---------------------------+
     | @@innodb_undo_tablespaces |
     +---------------------------+
     |                         2 |
     +---------------------------+

*Note*:

'innodb_undo_tablespaces' is deprecated and will be removed in a future
release.

For information about configuring undo tablespaces, see
innodb-undo-tablespace.

*Enabling Truncation of Undo Tablespaces*

To truncate undo tablespaces, enable 'innodb_undo_log_truncate'.

     mysql> SET GLOBAL innodb_undo_log_truncate=ON;

When 'innodb_undo_log_truncate' is enabled, undo tablespace files that
exceed the size limit defined by 'innodb_max_undo_log_size' are marked
for truncation.  'innodb_max_undo_log_size' is a dynamic global variable
with a default value of 1024 MiB (1073741824 bytes).

     mysql> SELECT @@innodb_max_undo_log_size;
     +----------------------------+
     | @@innodb_max_undo_log_size |
     +----------------------------+
     |                 1073741824 |
     +----------------------------+

You can configure 'innodb_max_undo_log_size' using a 'SET GLOBAL'
statement:

     mysql> SET GLOBAL innodb_max_undo_log_size=2147483648;

When 'innodb_undo_log_truncate' is enabled:

  1. Undo tablespaces that exceed the 'innodb_max_undo_log_size' setting
     are marked for truncation.  Selection of an undo tablespace for
     truncation is performed in a circular fashion to avoid truncating
     the same undo tablespace each time.

  2. Rollback segments residing in the selected undo tablespace are made
     inactive so that they are not assigned to new transactions.
     Existing transactions that are currently using rollback segments
     are allowed to complete.

  3. The purge system frees rollback segments that are no longer needed.

  4. After all rollback segments in the undo tablespace are freed, the
     truncate operation runs and the undo tablespace is truncated to its
     initial size.  The initial size of an undo tablespace file depends
     on the 'innodb_page_size' value.  For the default 16k 'InnoDB' page
     size, the initial undo tablespace file size is 10MiB. For 4k, 8k,
     32k, and 64k page sizes, the initial undo tablespace files sizes
     are 7MiB, 8MiB, 20MiB, and 40MiB, respectively.

     The size of an undo tablespace after a truncate operation may be
     larger than the initial size due to immediate use following the
     completion of the operation.

     The 'innodb_undo_directory' option defines the location of undo
     tablespace files.  The default value of '.' represents the
     directory where 'InnoDB' creates other log files by default.

          mysql> SELECT @@innodb_undo_directory;
          +-------------------------+
          | @@innodb_undo_directory |
          +-------------------------+
          | .                       |
          +-------------------------+

  5. The rollback segments are reactivated so that they can be assigned
     to new transactions.

*Expediting Truncation of Undo Tablespace Files*

An undo tablespace cannot be truncated until its rollback segments are
freed.  Normally, the purge system frees rollback segments once every
128 times that purge is invoked.  To expedite the truncation of undo
tablespaces, use the 'innodb_purge_rseg_truncate_frequency' option to
temporarily increase the frequency with which the purge system frees
rollback segments.  The default 'innodb_purge_rseg_truncate_frequency'
setting is 128, which is also the maximum value.

     mysql> SELECT @@innodb_purge_rseg_truncate_frequency;
     +----------------------------------------+
     | @@innodb_purge_rseg_truncate_frequency |
     +----------------------------------------+
     |                                    128 |
     +----------------------------------------+

To increase the frequency with which the purge thread frees rollback
segments, decrease the value of 'innodb_purge_rseg_truncate_frequency'.
For example:

     mysql> SET GLOBAL innodb_purge_rseg_truncate_frequency=32;

*Performance Impact of Truncating Undo Tablespace Files Online*

While an undo tablespace is truncated, rollback segments in that
tablespace are temporarily deactivated.  The remaining active rollback
segments in the other undo tablespaces assume responsibility for the
entire system load, which may result in a slight performance
degradation.  The degree of performance degradation depends on a number
of factors including:

   * Number of undo tablespaces

   * Number of undo logs

   * Undo tablespace size

   * Speed of the I/O susbsystem

   * Existing long running transactions

   * System load

14.7.9 InnoDB General Tablespaces
---------------------------------

A general tablespace is a shared 'InnoDB' tablespace that is created
using 'CREATE TABLESPACE' syntax.  General
tablespace capabilities and features are described under the following
topics in this section:

   * general-tablespaces-capabilities

   * general-tablespaces-creating

   * general-tablespaces-adding-tables

   * general-tablespaces-row-format-support

   * general-tablespaces-moving-non-partitioned-tables

   * general-tablespaces-table-partition-support

   * general-tablespaces-moving-partitions

   * general-tablespaces-dropping

   * general-tablespaces-limitations

*General Tablespace Capabilities*

The general tablespace feature provides the following capabilities:

   * Similar to the system tablespace, general tablespaces are shared
     tablespaces that can store data for multiple tables.

   * General tablespaces have a potential memory advantage over
     file-per-table tablespaces.  The
     server keeps tablespace metadata in memory for the lifetime of a
     tablespace.  Multiple tables in fewer general tablespaces consume
     less memory for tablespace metadata than the same number of tables
     in separate file-per-table tablespaces.

   * General tablespace data files may be placed in a directory relative
     to or independent of the MySQL data directory, which provides you
     with many of the data file and storage management capabilities of
     file-per-table tablespaces.  As
     with file-per-table tablespaces, the ability to place data files
     outside of the MySQL data directory allows you to manage
     performance of critical tables separately, setup RAID or DRBD for
     specific tables, or bind tables to particular disks, for example.

   * General tablespaces support both Antelope and Barracuda file
     formats, and therefore support all table row formats and associated
     features.  With support for both file formats, general tablespaces
     have no dependence on 'innodb_file_format' or
     'innodb_file_per_table' settings, nor do these variables have any
     effect on general tablespaces.

   * The 'TABLESPACE' option can be used with 'CREATE TABLE'
     to create tables in a general tablespaces,
     file-per-table tablespace, or in the system tablespace.

   * The 'TABLESPACE' option can be used with 'ALTER TABLE'
     to move tables between general tablespaces,
     file-per-table tablespaces, and the system tablespace.  Previously,
     it was not possible to move a table from a file-per-table
     tablespace to the system tablespace.  With the general tablespace
     feature, you can now do so.

*Creating a General Tablespace*

General tablespaces are created using 'CREATE TABLESPACE'
syntax.

     CREATE TABLESPACE tablespace_name
         ADD DATAFILE 'file_name'
         [FILE_BLOCK_SIZE = value]
             [ENGINE [=] engine_name]

A general tablespace may be created in the MySQL data directory or in a
directory outside of the MySQL data directory.  To avoid conflicts with
implicitly created file-per-table tablespaces, creating a general
tablespace in a subdirectory under the MySQL data directory is not
supported.  Also, when creating a general tablespace outside of the
MySQL data directory, the directory must exist prior to creating the
tablespace.

An .isl file is created in the MySQL data directory when a general
tablespace is created outside of the MySQL data directory.

Examples:

Creating a general tablespace in the MySQL data directory:

     mysql> CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' Engine=InnoDB;

Creating a general tablespace in a directory outside of the MySQL data
directory:

     mysql> CREATE TABLESPACE `ts1` ADD DATAFILE '/my/tablespace/directory/ts1.ibd' Engine=InnoDB;

You can specify a path that is relative to the MySQL data directory as
long as the tablespace directory is not under the MySQL data directory.
In this example, the 'my_tablespace' directory is at the same level as
the MySQL data directory:

     mysql> CREATE TABLESPACE `ts1` ADD DATAFILE '../my_tablespace/ts1.ibd' Engine=InnoDB;

*Note*:

The 'ENGINE = InnoDB' clause must be defined as part of the
'CREATE TABLESPACE' statement or 'InnoDB' must be
defined as the default storage engine ('default_storage_engine=InnoDB').

*Adding Tables to a General Tablespace*

After creating an 'InnoDB' general tablespace, you can use 'CREATE TABLE TBL_NAME ... TABLESPACE [=] TABLESPACE_NAME'
or
'ALTER TABLE TBL_NAME TABLESPACE [=] TABLESPACE_NAME'
to add tables to the tablespace, as shown in the following
examples:

'CREATE TABLE'.:

     mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=COMPACT;

See 'ALTER TABLE'.:

     mysql> ALTER TABLE t2 TABLESPACE ts1;

For detailed syntax information, see 'CREATE TABLE'.
and 'ALTER TABLE'.

*General Tablespace Row Format Support*

General tablespaces support all table row formats ('REDUNDANT',
'COMPACT', 'DYNAMIC', 'COMPRESSED') with the caveat that compressed and
uncompressed tables cannot coexist in the same general tablespace due to
different physical page sizes.

For a general tablespace to contain compressed tables
('ROW_FORMAT=COMPRESSED'), 'FILE_BLOCK_SIZE' must be specified, and the
'FILE_BLOCK_SIZE' value must be a valid compressed page size in relation
to the 'innodb_page_size' value.  Also, the physical page size of the
compressed table ('KEY_BLOCK_SIZE') must be equal to
'FILE_BLOCK_SIZE/1024'.  For example, if 'innodb_page_size=16K' and
'FILE_BLOCK_SIZE=8K', the 'KEY_BLOCK_SIZE' of the table must be 8.

The following table shows permitted 'innodb_page_size',
'FILE_BLOCK_SIZE', and 'KEY_BLOCK_SIZE' combinations.  'FILE_BLOCK_SIZE'
values may also be specified in bytes.  To determine a valid
'KEY_BLOCK_SIZE' value for a given 'FILE_BLOCK_SIZE', divide the
'FILE_BLOCK_SIZE' value by 1024.  Table compression is not support for
32K and 64K 'InnoDB' page sizes.  For more information about
'KEY_BLOCK_SIZE', see 'CREATE TABLE', and
innodb-compression-usage.

*Permitted Page Size, FILE_BLOCK_SIZE, and KEY_BLOCK_SIZE Combinations
for Compressed Tables*

InnoDB Page Size         Permitted                Permitted
(innodb_page_size)       FILE_BLOCK_SIZE Value    KEY_BLOCK_SIZE Value

64K                      64K (65536)              Compression is not
                                                  supported

32K                      32K (32768)              Compression is not
                                                  supported

16K                      16K (16384)              N/A: If
                                                  'innodb_page_size' is
                                                  equal to
                                                  'FILE_BLOCK_SIZE', the
                                                  tablespace cannot
                                                  contain a compressed
                                                  table.

16K                      8K (8192)                8

16K                      4K (4096)                4

16K                      2K (2048)                2

16K                      1K (1024)                1

8K                       8K (8192)                N/A: If
                                                  'innodb_page_size' is
                                                  equal to
                                                  'FILE_BLOCK_SIZE', the
                                                  tablespace cannot
                                                  contain a compressed
                                                  table.

8K                       4K (4096)                4

8K                       2K (2048)                2

8K                       1K (1024)                1

4K                       4K (4096)                N/A: If
                                                  'innodb_page_size' is
                                                  equal to
                                                  'FILE_BLOCK_SIZE', the
                                                  tablespace cannot
                                                  contain a compressed
                                                  table.

4K                       2K (2048)                2

4K                       1K (1024)                1

This example demonstrates creating a general tablespace and adding a
compressed table.  The example assumes a default 'innodb_page_size' of
16K. The 'FILE_BLOCK_SIZE' of 8192 requires that the compressed table
have a 'KEY_BLOCK_SIZE' of 8.

     mysql> CREATE TABLESPACE `ts2` ADD DATAFILE 'ts2.ibd' FILE_BLOCK_SIZE = 8192 Engine=InnoDB;

     mysql> CREATE TABLE t4 (c1 INT PRIMARY KEY) TABLESPACE ts2 ROW_FORMAT=COMPRESSED KEY_BLOCK_SIZE=8;

If you do not specify 'FILE_BLOCK_SIZE' when creating a general
tablespace, 'FILE_BLOCK_SIZE' defaults to 'innodb_page_size'.  When
'FILE_BLOCK_SIZE' is equal to 'innodb_page_size', the tablespace may
only contain tables with an uncompressed row format ('COMPACT',
'REDUNDANT', and 'DYNAMIC' row formats).

*Moving Non-Partitioned Tables Between Tablespaces Using ALTER TABLE*

You can use 'ALTER TABLE' with the 'TABLESPACE'
option to move a non-partitioned 'InnoDB' table to an existing general
tablespace, to a new file-per-table tablespace, or to the system
tablespace.

To move a non-partitioned table from a file-per-table tablespace or from
the system tablespace to a general tablespace, specify the name of the
general tablespace.  The general tablespace must exist.  See
'CREATE TABLESPACE' for more information.

     ALTER TABLE tbl_name TABLESPACE [=] TABLESPACE_NAME

To move a non-partitioned table from a general tablespace or
file-per-table tablespace to the system tablespace, specify
'innodb_system' as the tablespace name.

     ALTER TABLE tbl_name ... TABLESPACE [=] innodb_system

To move a non-partitioned table from the system tablespace or a general
tablespace to a file-per-table tablespace, specify
'innodb_file_per_table' as the tablespace name.

     ALTER TABLE tbl_name ... TABLESPACE [=] innodb_file_per_table

'ALTER TABLE ... TABLESPACE' operations always cause a full table
rebuild, even if the 'TABLESPACE' attribute has not changed from its
previous value.

'ALTER TABLE ... TABLESPACE' syntax does not support moving a table from
a temporary tablespace to a persistent tablespace.

The 'DATA DIRECTORY' clause is permitted with 'CREATE TABLE ...
TABLESPACE=innodb_file_per_table' but is otherwise not supported for use
in combination with the 'TABLESPACE' option.

*General Tablespace Table Partition Support*

The 'TABLESPACE' option may be used to assign individual table
partitions or subpartitions to a general tablespace, a separate
file-per-table tablespace, or the system tablespace.  All partitions
must belong to the same storage engine.  Usage is demonstrated in the
following examples.

     mysql> CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' Engine=InnoDB;
     mysql> CREATE TABLESPACE `ts2` ADD DATAFILE 'ts2.ibd' Engine=InnoDB;

     mysql> CREATE TABLE t1 (a INT, b INT) ENGINE = InnoDB
            PARTITION BY RANGE(a) SUBPARTITION BY KEY(b) (
             PARTITION p1 VALUES LESS THAN (100) TABLESPACE=`ts1`,
             PARTITION p2 VALUES LESS THAN (1000) TABLESPACE=`ts2`,
             PARTITION p3 VALUES LESS THAN (10000) TABLESPACE `innodb_file_per_table`,
             PARTITION p4 VALUES LESS THAN (100000) TABLESPACE `innodb_system`);

     mysql> CREATE TABLE t2 (a INT, b INT) ENGINE = InnoDB
            PARTITION BY RANGE(a) SUBPARTITION BY KEY(b) (
             PARTITION p1 VALUES LESS THAN (100) TABLESPACE=`ts1`
               (SUBPARTITION sp1,
                SUBPARTITION sp2),
             PARTITION p2 VALUES LESS THAN (1000)
               (SUBPARTITION sp3,
                SUBPARTITION sp4 TABLESPACE=`ts2`),
             PARTITION p3 VALUES LESS THAN (10000)
               (SUBPARTITION sp5 TABLESPACE `innodb_system`,
                SUBPARTITION sp6 TABLESPACE `innodb_file_per_table`));

The 'TABLESPACE' option is also supported with 'ALTER TABLE'.

     mysql> ALTER TABLE t1 ADD PARTITION (PARTITION p5 VALUES LESS THAN (1000000) TABLESPACE = `ts1`);

*Note*:

If the 'TABLESPACE = TABLESPACE_NAME' option is not defined, the
'ALTER TABLE ... ADD PARTITION' operation adds the
partition to the table's default tablespace, which can be specified at
the table level during 'CREATE TABLE' or
'ALTER TABLE'.

An 'ALTER TABLE TBL_NAME TABLESPACE [=] TABLESPACE_NAME' operation on a
_partitioned_ table only modifies the table's default tablespace.  It
does not move the table partitions.  However, after changing the default
tablespace, an operation that rebuilds the table, such as an
'ALTER TABLE' operation that uses 'ALGORITHM=COPY', moves
the partitions to the default tablespace if another tablespace is not
defined explicitly using the 'TABLESPACE [=] TABLESPACE_NAME' clause.

To verify that partitions were placed in the specified tablespaces, you
can query 'INFORMATION_SCHEMA.INNODB_SYS_TABLES'.:

     mysql> SELECT NAME, SPACE, SPACE_TYPE FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES
            WHERE NAME LIKE '%t1%';
     +-----------------------+-------+------------+
     | NAME                  | SPACE | SPACE_TYPE |
     +-----------------------+-------+------------+
     | test/t1#P#p1#SP#p1sp0 |    57 | General    |
     | test/t1#P#p2#SP#p2sp0 |    58 | General    |
     | test/t1#P#p3#SP#p3sp0 |    59 | Single     |
     | test/t1#P#p4#SP#p4sp0 |     0 | System     |
     | test/t1#P#p5#SP#p5sp0 |    57 | General    |
     +-----------------------+-------+------------+

     mysql> SELECT NAME, SPACE, SPACE_TYPE FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES
            WHERE NAME LIKE '%t2%';
     +---------------------+-------+------------+
     | NAME                | SPACE | SPACE_TYPE |
     +---------------------+-------+------------+
     | test/t2#P#p1#SP#sp1 |    57 | General    |
     | test/t2#P#p1#SP#sp2 |    57 | General    |
     | test/t2#P#p2#SP#sp3 |    60 | Single     |
     | test/t2#P#p2#SP#sp4 |    58 | General    |
     | test/t2#P#p3#SP#sp5 |     0 | System     |
     | test/t2#P#p3#SP#sp6 |    61 | Single     |
     +---------------------+-------+------------+

*Moving Table Partitions Between Tablespaces Using ALTER TABLE*

To move table partitions to a different tablespace, you must move each
partition using an 'ALTER TABLE TBL_NAME REORGANIZE PARTITION'
statement.

The following example demonstrates how to move table partitions to a
different tablespace.  'INFORMATION_SCHEMA.INNODB_SYS_TABLES'
and
'INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES'
are queried to verify that partitions are
placed in the expected tablespace.

*Note*:

If the 'TABLESPACE = TABLESPACE_NAME' option is not defined in the
'REORGANIZE PARTITION' statement, 'InnoDB' moves the partition to the
table's default tablespace.  In the example that follows, tablespace
'ts1', which is defined at the table level, is the default tablespace
for table 't1'.  Partition 'P3' is moved from the system tablespace to
tablespace 'ts1' since no 'TABLESPACE' option is specified in the
'ALTER TABLE t1 REORGANIZE PARTITION' statement for
partition 'P3'.

An operation that rebuilds the table, such as an 'ALTER TABLE'
operation that uses 'ALGORITHM=COPY', moves partitions to
the default tablespace if partitions reside in a different tablespace
that is not defined explicitly using the 'TABLESPACE [=]
TABLESPACE_NAME' clause.

     mysql> CREATE TABLESPACE ts1 ADD DATAFILE 'ts1.ibd';
     mysql> CREATE TABLESPACE ts2 ADD DATAFILE 'ts2.ibd';

     mysql> CREATE TABLE t1 ( a INT NOT NULL, PRIMARY KEY (a))
            ENGINE=InnoDB TABLESPACE ts1
            PARTITION BY RANGE (a) PARTITIONS 3 (
             PARTITION P1 VALUES LESS THAN (2),
             PARTITION P2 VALUES LESS THAN (4) TABLESPACE `innodb_file_per_table`,
             PARTITION P3 VALUES LESS THAN (6) TABLESPACE `innodb_system`);

     mysql> SELECT A.NAME as partition_name, A.SPACE_TYPE as space_type, B.NAME as space_name
            FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES A
            LEFT JOIN INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES B
            ON A.SPACE = B.SPACE WHERE A.NAME LIKE '%t1%' ORDER BY A.NAME;
     +----------------+------------+--------------+
     | partition_name | space_type | space_name   |
     +----------------+------------+--------------+
     | test/t1#P#P1   | General    | ts1          |
     | test/t1#P#P2   | Single     | test/t1#P#P2 |
     | test/t1#P#P3   | System     | NULL         |
     +----------------+------------+--------------+

     mysql> ALTER TABLE t1 REORGANIZE PARTITION P1
            INTO (PARTITION P1 VALUES LESS THAN (2) TABLESPACE = `ts2`);

     mysql> ALTER TABLE t1 REORGANIZE PARTITION P2
            INTO (PARTITION P2 VALUES LESS THAN (4) TABLESPACE = `ts2`);

     mysql> ALTER TABLE t1 REORGANIZE PARTITION P3
            INTO (PARTITION P3 VALUES LESS THAN (6));

     mysql> SELECT A.NAME AS partition_name, A.SPACE_TYPE AS space_type, B.NAME AS space_name
            FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES A
            LEFT JOIN INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES B
            ON A.SPACE = B.SPACE WHERE A.NAME LIKE '%t1%' ORDER BY A.NAME;
     +----------------+------------+------------+
     | partition_name | space_type | space_name |
     +----------------+------------+------------+
     | test/t1#P#P1   | General    | ts2        |
     | test/t1#P#P2   | General    | ts2        |
     | test/t1#P#P3   | General    | ts1        |
     +----------------+------------+------------+

*Dropping a General Tablespace*

The 'DROP TABLESPACE' statement is used to drop
an 'InnoDB' general tablespace.

All tables must be dropped from the tablespace prior to a 'DROP TABLESPACE'
operation.  If the tablespace is not
empty, see 'DROP TABLESPACE' returns an error.

If a 'DROP TABLESPACE' operation on an _empty_
general tablespace returns an error, the tablespace may contain an
orphan temporary or intermediate table that was left by an 'ALTER TABLE'
operation that was interrupted by a server exit.
For more information, see innodb-troubleshooting-datadict.

A general 'InnoDB' tablespace is not deleted automatically when the last
table in the tablespace is dropped.  The tablespace must be dropped
explicitly using 'DROP TABLESPACE TABLESPACE_NAME'.

A general tablespace does not belong to any particular database.  A
'DROP DATABASE' operation can drop tables that
belong to a general tablespace but it cannot drop the tablespace, even
if the 'DROP DATABASE' operation drops all tables
that belong to the tablespace.  A general tablespace must be dropped
explicitly using 'DROP TABLESPACE TABLESPACE_NAME'.

Similar to the system tablespace, truncating or dropping tables stored
in a general tablespace creates free space internally in the general
tablespace .ibd data file which can only be used for new 'InnoDB' data.
Space is not released back to the operating system as it is when a
file-per-table tablespace is deleted during a 'DROP TABLE'
operation.

This example demonstrates how to drop an 'InnoDB' general tablespace.
The general tablespace 'ts1' is created with a single table.  The table
must be dropped before dropping the tablespace.

     mysql> CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' Engine=InnoDB;

     mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts10 Engine=InnoDB;

     mysql> DROP TABLE t1;

     mysql> DROP TABLESPACE ts1;

*Note*:

'TABLESPACE_NAME' is a case-sensitive identifier in MySQL.

*General Tablespace Limitations*

   * A generated or existing tablespace cannot be changed to a general
     tablespace.

   * Creation of temporary general tablespaces is not supported.

   * General tablespaces do not support temporary tables.

   * Tables stored in a general tablespace may only be opened in MySQL
     releases that support general tablespaces.

   * Similar to the system tablespace, truncating or dropping tables
     stored in a general tablespace creates free space internally in the
     general tablespace .ibd data file which can only be used for new
     'InnoDB' data.  Space is not released back to the operating system
     as it is for file-per-table tablespaces.

     Additionally, a table-copying 'ALTER TABLE'.
     operation on table that resides in a shared tablespace (a general
     tablespace or the system tablespace) can increase the amount of
     space used by the tablespace.  Such operations require as much
     additional space as the data in the table plus indexes.  The
     additional space required for the table-copying 'ALTER TABLE'
     operation is not released back to the
     operating system as it is for file-per-table tablespaces.

   * 'ALTER TABLE ... DISCARD TABLESPACE' and
     'ALTER TABLE ...IMPORT TABLESPACE' are not supported
     for tables that belong to a general tablespace.

For more information see create-tablespace.

14.7.10 InnoDB Tablespace Encryption
------------------------------------

'InnoDB' supports data encryption for tables stored in file-per-table
tablespaces.  This feature provides at-rest encryption for physical
tablespace data files.

Tablespace encryption uses a two tier encryption key architecture,
consisting of a master encryption key and tablespace keys.  When a table
is encrypted, a tablespace key is encrypted and stored in the tablespace
header.  When an application or authenticated user wants to access
encrypted tablespace data, 'InnoDB' uses a master encryption key to
decrypt the tablespace key.  The decrypted version of a tablespace key
never changes, but the master encryption key may be changed as required.
This action is referred to as _master key rotation_.

The tablespace encryption feature relies on a keyring plugin for master
encryption key management.

All MySQL editions provide a 'keyring_file' plugin, which stores keyring
data in a file local to the server host.

MySQL Enterprise Edition offers these additional keyring plugins:

   * The 'keyring_encrypted_file' plugin, which stores keyring data in
     an encrypted file local to the server host.

   * The 'keyring_okv' plugin, which includes a KMIP client (KMIP 1.1)
     that works with KMIP-compatible products such as Oracle Key Vault
     (OKV) and Gemalto SafeNet KeySecure Appliance to provide encryption
     key management.

   * The 'keyring_aws' plugin, which communicates with the Amazon Web
     Services Key Management Service (AWS KMS) as a back end for key
     generation and uses a local file for key storage.

*Warning*:

The 'keyring_file' and 'keyring_encrypted_file' plugins are not intended
as a regulatory compliance solutions.  Security standards such as PCI,
FIPS, and others require use of key management systems to secure,
manage, and protect encryption keys in key vaults or hardware security
modules (HSMs).

A secure and robust encryption key management solution, as supported by
the 'keyring_okv' and 'keyring_aws' plugins, is critical for security
and for compliance with various security standards.  When the tablespace
encryption feature uses an encryption key management solution supported
by these plugins, the feature is referred to as 'MySQL Enterprise
Transparent Data Encryption (TDE)'.

Tablespace encryption supports the Advanced Encryption Standard (AES)
block-based encryption algorithm.  It uses Electronic Codebook (ECB)
block encryption mode for tablespace key encryption and Cipher Block
Chaining (CBC) block encryption mode for data encryption.

For frequently asked questions about the tablespace encryption feature,
see faqs-tablespace-encryption.

*InnoDB Tablespace Encryption Prerequisites*

   * A keyring plugin must be installed and configured.  Keyring plugin
     installation is performed at startup using the 'early-plugin-load'
     option.  Early loading ensures that the plugin is available prior
     to initialization of the 'InnoDB' storage engine.  For keyring
     plugin installation and configuration instructions, see
     keyring.

     Only one keyring plugin should be enabled at a time.  Enabling
     multiple keyring plugins is not supported.

     *Important*:

     Once encrypted tables are created in a MySQL instance, the keyring
     plugin that was loaded when creating the encrypted tables must
     continue to be loaded using the 'early-plugin-load' option, prior
     to 'InnoDB' initialization.  Failing to do so results in errors on
     startup and during 'InnoDB' recovery.

     To verify that a keyring plugin is active, use the 'SHOW PLUGINS'
     statement or query the
     'INFORMATION_SCHEMA.PLUGINS' table.  For example:

          mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
                 FROM INFORMATION_SCHEMA.PLUGINS
                 WHERE PLUGIN_NAME LIKE 'keyring%';
          +--------------+---------------+
          | PLUGIN_NAME  | PLUGIN_STATUS |
          +--------------+---------------+
          | keyring_file | ACTIVE        |
          +--------------+---------------+

   * The 'innodb_file_per_table' option must be enabled (the default).
     'InnoDB' tablespace encryption only supports file-per-table
     tablespaces.  Alternatively, you can specify the
     'TABLESPACE='innodb_file_per_table'' option when creating an
     encrypted table or altering an existing table to enable encryption.

   * Before using the 'InnoDB' tablespace encryption feature with
     production data, ensure that you have taken steps to prevent loss
     of the master encryption key.  _If the master encryption key is
     lost, data stored in encrypted tablespace files is unrecoverable._
     If you are using the 'keyring_file' or 'keyring_encrypted_file'
     plugin, it is recommended that you create a backup of the keyring
     data file immediately after creating the first encrypted table and
     before and after master key rotation.  For the 'keyring_file'
     plugin, the keyring data file location is defined by the
     'keyring_file_data' configuration option.  For the
     'keyring_encrypted_file' plugin, the keyring data file location is
     defined by the 'keyring_encrypted_file_data' configuration option.
     If you are using the 'keyring_okv' or 'keyring_aws' plugin, ensure
     that you have performed the necessary configuration.  For
     instructions, see keyring.

*Enabling and Disabling InnoDB Tablespace Encryption*

To enable encryption for a new 'InnoDB' table, specify the 'ENCRYPTION'
option in a 'CREATE TABLE' statement.

     mysql> CREATE TABLE t1 (c1 INT) ENCRYPTION='Y';

To enable encryption for an existing 'InnoDB' table, specify the
'ENCRYPTION' option in an 'ALTER TABLE' statement.

     mysql> ALTER TABLE t1 ENCRYPTION='Y';

To disable encryption for an 'InnoDB' table, set 'ENCRYPTION='N'' using
'ALTER TABLE'.

     mysql> ALTER TABLE t1 ENCRYPTION='N';

*Note*:

Plan appropriately when altering an existing table with the 'ENCRYPTION'
option.  'ALTER TABLE ... ENCRYPTION' operations
rebuild the table using 'ALGORITHM=COPY'.  'ALGORITHM=INPLACE' is not
supported.

*InnoDB Tablespace Encryption and Master Key Rotation*

The master encryption key should be rotated periodically and whenever
you suspect that the key may have been compromised.

Master key rotation is an atomic, instance-level operation.  Each time
the master encryption key is rotated, all tablespace keys in the MySQL
instance are re-encrypted and saved back to their respective tablespace
headers.  As an atomic operation, re-encryption must succeed for all
tablespace keys once a rotation operation is initiated.  If master key
rotation is interrupted by a server failure, 'InnoDB' rolls the
operation forward on server restart.  For more information, see
innodb-tablespace-encryption-recovery.

Rotating the master encryption key only changes the master encryption
key and re-encrypts tablespace keys.  It does not decrypt or re-encrypt
associated tablespace data.

Rotating the master encryption key requires the 'SUPER' privilege.

To rotate the master encryption key, run:

     mysql> ALTER INSTANCE ROTATE INNODB MASTER KEY;

See 'ALTER INSTANCE ROTATE INNODB MASTER KEY'.
supports concurrent DML. However, it cannot be run concurrently with
'CREATE TABLE ... ENCRYPTED' or 'ALTER TABLE ... ENCRYPTED'
operations, and locks are taken to prevent
conflicts that could arise from concurrent execution of these
statements.  If one of the conflicting statements is running, it must
complete before another can proceed.

*InnoDB Tablespace Encryption and Recovery*

If a server failure occurs during master key rotation, 'InnoDB'
continues the operation on server restart.

The keyring plugin must be loaded prior to storage engine initialization
so that the information necessary to decrypt tablespace data pages can
be retrieved from tablespace headers before 'InnoDB' initialization and
recovery activities access tablespace data.  (See
innodb-tablespace-encryption-encryption-prerequisites.)

When 'InnoDB' initialization and recovery begin, the master key rotation
operation resumes.  Due to the server failure, some tablespaces keys may
already be encrypted using the new master encryption key.  'InnoDB'
reads the encryption data from each tablespace header, and if the data
indicates that the tablespace key is encrypted using the old master
encryption key, 'InnoDB' retrieves the old key from the keyring and uses
it to decrypt the tablepace key.  'InnoDB' then re-encrypts the
tablespace key using the new master encryption key and saves the
re-encrypted tablespace key back to the tablespace header.

*Exporting Encrypted Tables*

When an encrypted table is exported, 'InnoDB' generates a _transfer key_
that is used to encrypt the tablespace key.  The encrypted tablespace
key and transfer key are stored in a 'TABLESPACE_NAME.cfp' file.  This
file together with the encrypted tablespace file is required to perform
an import operation.  On import, 'InnoDB' uses the transfer key to
decrypt the tablespace key in the 'TABLESPACE_NAME.cfp' file.  For
related information, see tablespace-copying.

*InnoDB Tablespace Encryption and Replication*

   * The 'ALTER INSTANCE ROTATE INNODB MASTER KEY'
     statement is only supported in replication
     environments where the master and slaves run a version of MySQL
     that supports the tablespace encryption feature.

   * Successful 'ALTER INSTANCE ROTATE INNODB MASTER KEY'
     statements are written to the binary log for
     replication on slaves.

   * If an 'ALTER INSTANCE ROTATE INNODB MASTER KEY'
     statement fails, it is not logged to the binary log
     and is not replicated on slaves.

   * Replication of an 'ALTER INSTANCE ROTATE INNODB MASTER KEY'
     operation fails if the keyring plugin is installed
     on the master but not on the slave.

   * If the 'keyring_file' plugin is installed on both the master and a
     slave but the slave does not have a keyring data file, the
     replicated 'ALTER INSTANCE ROTATE INNODB MASTER KEY'
     statement creates the keyring data file on the
     slave, assuming the keyring file data is not cached in memory.
     See 'ALTER INSTANCE ROTATE INNODB MASTER KEY'.
     uses keyring file data that is cached in memory, if available.

*Identifying Tables that Use InnoDB Tablespace Encryption*

When the 'ENCRYPTION' option is specified in a 'CREATE TABLE'
or 'ALTER TABLE' statement, it is
recorded in the 'CREATE_OPTIONS' field of
'INFORMATION_SCHEMA.TABLES'.  This field may be queried to
identify encrypted tables in a MySQL instance.

     mysql> SELECT TABLE_SCHEMA, TABLE_NAME, CREATE_OPTIONS FROM INFORMATION_SCHEMA.TABLES
            WHERE CREATE_OPTIONS LIKE '%ENCRYPTION="Y"%';
     +--------------+------------+----------------+
     | TABLE_SCHEMA | TABLE_NAME | CREATE_OPTIONS |
     +--------------+------------+----------------+
     | test         | t1         | ENCRYPTION="Y" |
     +--------------+------------+----------------+

*InnoDB Tablespace Encryption Usage Notes*

   * If the server exits or is stopped during normal operation, it is
     recommended to restart the server using the same encryption
     settings that were configured previously.

   * The first master encryption key is generated when the first new or
     existing table is encrypted.

   * Master key rotation re-encrypts tablespaces keys but does not
     change the tablespace key itself.  To change a tablespace key, you
     must disable and re-enable table encryption using 'ALTER TABLE TBL_NAME ENCRYPTION',
     which is an
     'ALGORITHM=COPY' operation that rebuilds the table.

   * If a table is created with both the 'COMPRESSION'
     and 'ENCRYPTION' options,
     compression is performed before tablespace data is encrypted.

   * If a keyring data file (the file named by the 'keyring_file_data'
     or 'keyring_encrypted_file_data' system variable) is empty or
     missing, the first execution of 'ALTER INSTANCE ROTATE INNODB MASTER KEY'
     creates a master encryption key.

   * Uninstalling the 'keyring_file' or 'keyring_encrypted_file' plugin
     does not remove an existing keyring data file.

   * It is recommended that you not place a keyring data file under the
     same directory as tablespace data files.

   * Modifying the 'keyring_file_data' or 'keyring_encrypted_file_data'
     setting at runtime or when restarting the server can cause
     previously encrypted tables to become inaccessible, resulting in
     the loss of data.

*InnoDB Tablespace Encryption Limitations*

   * Advanced Encryption Standard (AES) is the only supported encryption
     algorithm.  'InnoDB' tablespace encryption uses Electronic Codebook
     (ECB) block encryption mode for tablespace key encryption and
     Cipher Block Chaining (CBC) block encryption mode for data
     encryption.

   * Altering the 'ENCRYPTION' attribute of a table is an
     'ALGORITHM=COPY' operation.  'ALGORITHM=INPLACE' is not supported.

   * Tablespace encryption is only supported for tables stored in a
     file-per-table tablespace.  Encryption is not supported for tables
     stored in other tablespace types including general tablespaces, the
     system tablespace, undo log tablespaces, and the temporary
     tablespace.

   * You cannot move or copy an encrypted table from a file-per-table
     tablespace to an unsupported tablespace type.

   * Tablespace encryption only applies to data in the tablespace.  Data
     is not encrypted in the redo log, undo log, or binary log.

14.8 InnoDB Tables and Indexes
==============================

This section covers topics related to 'InnoDB' tables and indexes.

14.8.1 InnoDB Tables
--------------------

This section covers topics related to 'InnoDB' tables.

14.8.1.1 Creating InnoDB Tables
...............................

To create an 'InnoDB' table, use the 'CREATE TABLE'.
statement.

     CREATE TABLE t1 (a INT, b CHAR (20), PRIMARY KEY (a)) ENGINE=InnoDB;

You do not need to specify the 'ENGINE=InnoDB' clause if 'InnoDB' is
defined as the default storage engine, which it is by default.  To check
the default storage engine, issue the following statement:

     mysql> SELECT @@default_storage_engine;
     +--------------------------+
     | @@default_storage_engine |
     +--------------------------+
     | InnoDB                   |
     +--------------------------+

You might still use 'ENGINE=InnoDB' clause if you plan to use
'mysqldump' or replication to replay the 'CREATE TABLE'
statement on a server where the default storage
engine is not 'InnoDB'.

An 'InnoDB' table and its indexes can be created in the system
tablespace, in a file-per-table tablespace, or in a general tablespace.
When 'innodb_file_per_table' is enabled, which is the default, an
'InnoDB' table is implicitly created in an individual file-per-table
tablespace.  Conversely, when 'innodb_file_per_table' is disabled, an
'InnoDB' table is implicitly created in the 'InnoDB' system tablespace.
To create a table in a general tablespace, use 'CREATE TABLE ... TABLESPACE'
syntax.  For more information, see
general-tablespaces.

When you create an 'InnoDB' table, MySQL creates a .frm file in the
database directory under the MySQL data directory.  For more information
about '.frm' files, see innodb-frm-file.  For a table created in
a file-per-table tablespace, MySQL also creates an .ibd tablespace file
in the database directory, by default.  A table created in the 'InnoDB'
system tablespace is created in an existing ibdata file, which resides
in the MySQL data directory.  A table created in a general tablespace is
created in an existing general tablespace .ibd file.  General tablespace
files can be created inside or outside of the MySQL data directory.  For
more information, see general-tablespaces.

Internally, 'InnoDB' adds an entry for each table to the 'InnoDB' data
dictionary.  The entry includes the database name.  For example, if
table 't1' is created in the 'test' database, the data dictionary entry
for the database name is ''test/t1''.  This means you can create a table
of the same name ('t1') in a different database, and the table names do
not collide inside 'InnoDB'.

*InnoDB Tables and .frm Files*

MySQL stores data dictionary information for tables in .frm files in
database directories.  Unlike other MySQL storage engines, 'InnoDB' also
encodes information about the table in its own internal data dictionary
inside the system tablespace.  When MySQL drops a table or a database,
it deletes one or more '.frm' files as well as the corresponding entries
inside the 'InnoDB' data dictionary.  You cannot move 'InnoDB' tables
between databases simply by moving the '.frm' files.  For information
about moving 'InnoDB' tables, see innodb-migration.

*InnoDB Tables and Row Formats*

The default row format for 'InnoDB' tables is defined by the
'innodb_default_row_format' configuration option, which has a default
value of 'DYNAMIC'.  'Dynamic' and 'Compressed' row format allow you to
take advantage of 'InnoDB' features such as table compression and
efficient off-page storage of long column values.  To use these row
formats, 'innodb_file_per_table' must be enabled (the default as of
MySQL 5.6.6) and 'innodb_file_format' must be set to Barracuda.

     SET GLOBAL innodb_file_per_table=1;
     SET GLOBAL innodb_file_format=barracuda;
     CREATE TABLE t3 (a INT, b CHAR (20), PRIMARY KEY (a)) ROW_FORMAT=DYNAMIC;
     CREATE TABLE t4 (a INT, b CHAR (20), PRIMARY KEY (a)) ROW_FORMAT=COMPRESSED;

Alternatively, you can use 'CREATE TABLE ... TABLESPACE'
syntax to create an 'InnoDB' table in a general
tablespace.  General tablespaces support all row formats.  For more
information, see general-tablespaces.

     CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=DYNAMIC;

'CREATE TABLE ... TABLESPACE' syntax can also be
used to create 'InnoDB' tables with a 'Dynamic' row format in the system
tablespace, alongside tables with a 'Compact' or 'Redundant' row format.

     CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE = innodb_system ROW_FORMAT=DYNAMIC;

For more information about 'InnoDB' row formats, see
innodb-row-format.  For how to determine the row format of an 'InnoDB'
table and the physical characteristics of 'InnoDB' row formats, see
innodb-physical-record.

*InnoDB Tables and Primary Keys*

Always define a primary key for an 'InnoDB' table, specifying the column
or columns that:

   * Are referenced by the most important queries.

   * Are never left blank.

   * Never have duplicate values.

   * Rarely if ever change value once inserted.

For example, in a table containing information about people, you would
not create a primary key on '(firstname, lastname)' because more than
one person can have the same name, some people have blank last names,
and sometimes people change their names.  With so many constraints,
often there is not an obvious set of columns to use as a primary key, so
you create a new column with a numeric ID to serve as all or part of the
primary key.  You can declare an auto-increment column so that ascending
values are filled in automatically as rows are inserted:

     # The value of ID can act like a pointer between related items in different tables.
     CREATE TABLE t5 (id INT AUTO_INCREMENT, b CHAR (20), PRIMARY KEY (id));

     # The primary key can consist of more than one column. Any autoinc column must come first.
     CREATE TABLE t6 (id INT AUTO_INCREMENT, a INT, b CHAR (20), PRIMARY KEY (id,a));

Although the table works correctly without defining a primary key, the
primary key is involved with many aspects of performance and is a
crucial design aspect for any large or frequently used table.  It is
recommended that you always specify a primary key in the 'CREATE TABLE'
statement.  If you create the table, load data,
and then run 'ALTER TABLE' to add a primary key
later, that operation is much slower than defining the primary key when
creating the table.

*Viewing InnoDB Table Properties*

To view the properties of an 'InnoDB' table, issue a 'SHOW TABLE STATUS'
statement:

     mysql> SHOW TABLE STATUS FROM test LIKE 't%' \G;
     *************************** 1. row ***************************
                Name: t1
              Engine: InnoDB
             Version: 10
          Row_format: Compact
                Rows: 0
      Avg_row_length: 0
         Data_length: 16384
     Max_data_length: 0
        Index_length: 0
           Data_free: 0
      Auto_increment: NULL
         Create_time: 2015-03-16 15:13:31
         Update_time: NULL
          Check_time: NULL
           Collation: latin1_swedish_ci
            Checksum: NULL
      Create_options:
             Comment:
     1 row in set (0.00 sec)

For information about 'SHOW TABLE STATUS'.
output, see show-table-status.

'InnoDB' table properties may also be queried using the 'InnoDB'
Information Schema system tables:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME='test/t1' \G
     *************************** 1. row ***************************
          TABLE_ID: 45
              NAME: test/t1
              FLAG: 1
            N_COLS: 5
             SPACE: 35
       FILE_FORMAT: Antelope
        ROW_FORMAT: Compact
     ZIP_PAGE_SIZE: 0
        SPACE_TYPE: Single
     1 row in set (0.00 sec)

For more information, see
innodb-information-schema-system-tables.

14.8.1.2 The Physical Row Structure of an InnoDB Table
......................................................

The physical row structure of an 'InnoDB' table depends on the row
format specified when the table is created.  If a row format is not
specified, the default row format is used.  The default row format for
'InnoDB' tables is defined by the 'innodb_default_row_format'
configuration option, which has a default value of 'DYNAMIC'.

The following sections describe the characteristics of 'InnoDB' row
formats.

   * innodb-determining-row-format

   * innodb-redundant-row-format-characteristics

   * innodb-compact-row-format-characteristics

   * innodb-dynamic-compressed-row-format-characteristics

For more information about 'InnoDB' row formats, see
innodb-row-format.

*Determining the Row Format of an InnoDB Table*

To determine the row format of an 'InnoDB' table, use 'SHOW TABLE STATUS'.
For example:

     mysql> SHOW TABLE STATUS IN test1\G
     *************************** 1. row ***************************
                Name: t1
              Engine: InnoDB
             Version: 10
          Row_format: Dynamic
                Rows: 0
      Avg_row_length: 0
         Data_length: 16384
     Max_data_length: 0
        Index_length: 16384
           Data_free: 0
      Auto_increment: 1
         Create_time: 2016-09-14 16:29:38
         Update_time: NULL
          Check_time: NULL
           Collation: latin1_swedish_ci
            Checksum: NULL
      Create_options:
             Comment:

You can also determine the row format of an 'InnoDB' table by querying
'INFORMATION_SCHEMA.INNODB_SYS_TABLES'.

     mysql> SELECT NAME, ROW_FORMAT FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME='test1/t1';
     +----------+------------+
     | NAME     | ROW_FORMAT |
     +----------+------------+
     | test1/t1 | Dynamic    |
     +----------+------------+

*Redundant Row Format Characteristics*

The 'REDUNDANT' format is available to retain compatibility with older
versions of MySQL.

Rows in 'InnoDB' tables that use 'REDUNDANT' row format have the
following characteristics:

   * Each index record contains a 6-byte header.  The header is used to
     link together consecutive records, and also in row-level locking.

   * Records in the clustered index contain fields for all user-defined
     columns.  In addition, there is a 6-byte transaction ID field and a
     7-byte roll pointer field.

   * If no primary key was defined for a table, each clustered index
     record also contains a 6-byte row ID field.

   * Each secondary index record also contains all the primary key
     fields defined for the clustered index key that are not in the
     secondary index.

   * A record contains a pointer to each field of the record.  If the
     total length of the fields in a record is less than 128 bytes, the
     pointer is one byte; otherwise, two bytes.  The array of these
     pointers is called the record directory.  The area where these
     pointers point is called the data part of the record.

   * Internally, 'InnoDB' stores fixed-length character columns such as
     'CHAR(10)' in a fixed-length format.  'InnoDB' does
     not truncate trailing spaces from 'VARCHAR' columns.

   * 'InnoDB' encodes fixed-length fields greater than or equal to 768
     bytes in length as variable-length fields, which can be stored
     off-page.  For example, a 'CHAR(255)' column can exceed 768 bytes
     if the maximum byte length of the character set is greater than 3,
     as it is with 'utf8mb4'.

   * An SQL 'NULL' value reserves one or two bytes in the record
     directory.  Besides that, an SQL 'NULL' value reserves zero bytes
     in the data part of the record if stored in a variable length
     column.  In a fixed-length column, it reserves the fixed length of
     the column in the data part of the record.  Reserving the fixed
     space for 'NULL' values enables an update of the column from 'NULL'
     to a non-'NULL' value to be done in place without causing
     fragmentation of the index page.

*COMPACT Row Format Characteristics*

The 'COMPACT' row format decreases row storage space by about 20%
compared to the 'REDUNDANT' format at the cost of increasing CPU use for
some operations.  If your workload is a typical one that is limited by
cache hit rates and disk speed, 'COMPACT' format is likely to be faster.
If the workload is a rare case that is limited by CPU speed, compact
format might be slower.

Rows in 'InnoDB' tables that use 'COMPACT' row format have the following
characteristics:

   * Each index record contains a 5-byte header that may be preceded by
     a variable-length header.  The header is used to link together
     consecutive records, and also in row-level locking.

   * The variable-length part of the record header contains a bit vector
     for indicating 'NULL' columns.  If the number of columns in the
     index that can be 'NULL' is N, the bit vector occupies
     'CEILING(N/8)' bytes.  (For example, if there are anywhere from 9
     to 16 columns that can be 'NULL', the bit vector uses two bytes.)
     Columns that are 'NULL' do not occupy space other than the bit in
     this vector.  The variable-length part of the header also contains
     the lengths of variable-length columns.  Each length takes one or
     two bytes, depending on the maximum length of the column.  If all
     columns in the index are 'NOT NULL' and have a fixed length, the
     record header has no variable-length part.

   * For each non-'NULL' variable-length field, the record header
     contains the length of the column in one or two bytes.  Two bytes
     are only needed if part of the column is stored externally in
     overflow pages or the maximum length exceeds 255 bytes and the
     actual length exceeds 127 bytes.  For an externally stored column,
     the 2-byte length indicates the length of the internally stored
     part plus the 20-byte pointer to the externally stored part.  The
     internal part is 768 bytes, so the length is 768+20.  The 20-byte
     pointer stores the true length of the column.

   * The record header is followed by the data contents of the
     non-'NULL' columns.

   * Records in the clustered index contain fields for all user-defined
     columns.  In addition, there is a 6-byte transaction ID field and a
     7-byte roll pointer field.

   * If no primary key was defined for a table, each clustered index
     record also contains a 6-byte row ID field.

   * Each secondary index record also contains all the primary key
     fields defined for the clustered index key that are not in the
     secondary index.  If any of these primary key fields are variable
     length, the record header for each secondary index has a
     variable-length part to record their lengths, even if the secondary
     index is defined on fixed-length columns.

   * Internally, for nonvariable-length character sets, 'InnoDB' stores
     fixed-length character columns such as 'CHAR(10)' in a
     fixed-length format.

     'InnoDB' does not truncate trailing spaces from 'VARCHAR'
     columns.

   * Internally, for variable-length character sets such as 'utf8mb3'
     and 'utf8mb4', 'InnoDB' attempts to store 'CHAR(N)' in
     N bytes by trimming trailing spaces.  If the byte length of a
     'CHAR(N)' column value exceeds N bytes, 'InnoDB' trims
     trailing spaces to a minimum of the column value byte length.  The
     maximum length of a 'CHAR(N)' column is the maximum
     character byte length x N.

     'InnoDB' reserves a minimum of N bytes for 'CHAR(N)'.
     Reserving the minimum space N in many cases enables column updates
     to be done in place without causing fragmentation of the index
     page.  By comparison, for 'ROW_FORMAT=REDUNDANT', see 'CHAR(N)'
     columns occupy the maximum character byte length x N.

     'InnoDB' encodes fixed-length fields greater than or equal to 768
     bytes in length as variable-length fields, which can be stored
     off-page.  For example, a 'CHAR(255)' column can exceed 768 bytes
     if the maximum byte length of the character set is greater than 3,
     as it is with 'utf8mb4'.

     'ROW_FORMAT=DYNAMIC' and 'ROW_FORMAT=COMPRESSED' handle
     'CHAR' storage in the same way as 'ROW_FORMAT=COMPACT'.

*DYNAMIC and COMPRESSED Row Format Characteristics*

'DYNAMIC' and 'COMPRESSED' row formats are variations of the 'COMPACT'
row format.  For information about these row formats, see
innodb-row-format-dynamic.

14.8.1.3 Moving or Copying InnoDB Tables
........................................

This section describes techniques for moving or copying some or all
'InnoDB' tables to a different server or instance.  For example, you
might move an entire MySQL instance to a larger, faster server; you
might clone an entire MySQL instance to a new replication slave server;
you might copy individual tables to another instance to develop and test
an application, or to a data warehouse server to produce reports.

On Windows, 'InnoDB' always stores database and table names internally
in lowercase.  To move databases in a binary format from Unix to Windows
or from Windows to Unix, create all databases and tables using lowercase
names.  A convenient way to accomplish this is to add the following line
to the '[mysqld]' section of your 'my.cnf' or 'my.ini' file before
creating any databases or tables:

     [mysqld]
     lower_case_table_names=1

Techniques for moving or copying 'InnoDB' tables include:

   * copy-tables-transportable-tablespaces

   * copy-tables-meb

   * copy-tables-cold-backup

   * copy-tables-export-import

*Transportable Tablespaces*

The transportable tablespaces feature uses 'FLUSH TABLES ... FOR EXPORT'
to ready 'InnoDB' tables for copying from one server instance to
another.  To use this feature, 'InnoDB' tables must be created with
'innodb_file_per_table' set to 'ON' so that each 'InnoDB' table has its
own tablespace.  For usage information, see tablespace-copying.

*MySQL Enterprise Backup*

The MySQL Enterprise Backup product lets you back up a running MySQL
database with minimal disruption to operations while producing a
consistent snapshot of the database.  When MySQL Enterprise Backup is
copying tables, reads and writes can continue.  In addition, MySQL
Enterprise Backup can create compressed backup files, and back up
subsets of tables.  In conjunction with the MySQL binary log, you can
perform point-in-time recovery.  MySQL Enterprise Backup is included as
part of the MySQL Enterprise subscription.

For more details about MySQL Enterprise Backup, see
mysql-enterprise-backup.

*Copying Data Files (Cold Backup Method)*

You can move an 'InnoDB' database simply by copying all the relevant
files listed under "Cold Backups" in innodb-backup.

'InnoDB' data and log files are binary-compatible on all platforms
having the same floating-point number format.  If the floating-point
formats differ but you have not used 'FLOAT'
or 'DOUBLE' data
types in your tables, then the procedure is the same: simply copy the
relevant files.

When you move or copy file-per-table '.ibd' files, the database
directory name must be the same on the source and destination systems.
The table definition stored in the 'InnoDB' shared tablespace includes
the database name.  The transaction IDs and log sequence numbers stored
in the tablespace files also differ between databases.

To move an '.ibd' file and the associated table from one database to
another, use a 'RENAME TABLE' statement:

     RENAME TABLE DB1.TBL_NAME TO DB2.TBL_NAME;

If you have a 'clean' backup of an '.ibd' file, you can restore it to
the MySQL installation from which it originated as follows:

  1. The table must not have been dropped or truncated since you copied
     the '.ibd' file, because doing so changes the table ID stored
     inside the tablespace.

  2. Issue this 'ALTER TABLE' statement to delete
     the current '.ibd' file:

          ALTER TABLE TBL_NAME DISCARD TABLESPACE;

  3. Copy the backup '.ibd' file to the proper database directory.

  4. Issue this 'ALTER TABLE' statement to tell
     'InnoDB' to use the new '.ibd' file for the table:

          ALTER TABLE TBL_NAME IMPORT TABLESPACE;

     *Note*:

     The 'ALTER TABLE ... IMPORT TABLESPACE' feature
     does not enforce foreign key constraints on imported data.

In this context, a 'clean' '.ibd' file backup is one for which the
following requirements are satisfied:

   * There are no uncommitted modifications by transactions in the
     '.ibd' file.

   * There are no unmerged insert buffer entries in the '.ibd' file.

   * Purge has removed all delete-marked index records from the '.ibd'
     file.

   * 'mysqld' has flushed all modified pages of the
     '.ibd' file from the buffer pool to the file.

You can make a clean backup '.ibd' file using the following method:

  1. Stop all activity from the 'mysqld' server and
     commit all transactions.

  2. Wait until 'SHOW ENGINE INNODB STATUS' shows
     that there are no active transactions in the database, and the main
     thread status of 'InnoDB' is 'Waiting for server activity'.  Then
     you can make a copy of the '.ibd' file.

Another method for making a clean copy of an '.ibd' file is to use the
MySQL Enterprise Backup product:

  1. Use MySQL Enterprise Backup to back up the 'InnoDB' installation.

  2. Start a second 'mysqld' server on the backup and let
     it clean up the '.ibd' files in the backup.

*Export and Import (mysqldump)*

You can use 'mysqldump' to dump your tables on one
machine and then import the dump files on the other machine.  Using this
method, it does not matter whether the formats differ or if your tables
contain floating-point data.

One way to increase the performance of this method is to switch off
autocommit mode when importing data, assuming that the tablespace has
enough space for the big rollback segment that the import transactions
generate.  Do the commit only after importing a whole table or a segment
of a table.

14.8.1.4 Converting Tables from MyISAM to InnoDB
................................................

If you have 'MyISAM' tables that you want
to convert to 'InnoDB' for better
reliability and scalability, review the following guidelines and tips
before converting.

   * innodb-convert-memory-usage

   * innodb-convert-transactions

   * innodb-convert-deadlock

   * innodb-convert-plan-storage

   * innodb-convert-convert

   * innodb-convert-clone

   * innodb-convert-transfer

   * innodb-convert-storage-requirements

   * innodb-convert-primary-key

   * innodb-convert-application-performance

   * innodb-convert-understand-files

*Adjusting Memory Usage for MyISAM and InnoDB*

As you transition away from 'MyISAM' tables, lower the value of the
'key_buffer_size' configuration option to free memory no longer needed
for caching results.  Increase the value of the
'innodb_buffer_pool_size' configuration option, which performs a similar
role of allocating cache memory for 'InnoDB' tables.  The 'InnoDB'
buffer pool caches both table data and index data, speeding up lookups
for queries and keeping query results in memory for reuse.  For guidance
regarding buffer pool size configuration, see memory-use.

On a busy server, run benchmarks with the query cache turned off.  The
'InnoDB' buffer pool provides similar benefits, so the query cache might
be tying up memory unnecessarily.  For information about the query
cache, see query-cache.

*Handling Too-Long Or Too-Short Transactions*

Because 'MyISAM' tables do not support transactions, you might not have
paid much attention to the 'autocommit' configuration option and the
'COMMIT' and 'ROLLBACK' statements.  These
keywords are important to allow multiple sessions to read and write
'InnoDB' tables concurrently, providing substantial scalability benefits
in write-heavy workloads.

While a transaction is open, the system keeps a snapshot of the data as
seen at the beginning of the transaction, which can cause substantial
overhead if the system inserts, updates, and deletes millions of rows
while a stray transaction keeps running.  Thus, take care to avoid
transactions that run for too long:

   * If you are using a 'mysql' session for interactive
     experiments, always 'COMMIT'. (to finalize the
     changes) or 'ROLLBACK'. (to undo the changes) when
     finished.  Close down interactive sessions rather than leave them
     open for long periods, to avoid keeping transactions open for long
     periods by accident.

   * Make sure that any error handlers in your application also
     'ROLLBACK' incomplete changes or 'COMMIT'.
     completed changes.

   * 'ROLLBACK' is a relatively expensive operation,
     because 'INSERT', 'UPDATE', and
     'DELETE' operations are written to 'InnoDB' tables prior
     to the 'COMMIT', with the expectation that most
     changes are committed successfully and rollbacks are rare.  When
     experimenting with large volumes of data, avoid making changes to
     large numbers of rows and then rolling back those changes.

   * When loading large volumes of data with a sequence of
     'INSERT' statements, periodically 'COMMIT'.
     the results to avoid having transactions that last for hours.  In
     typical load operations for data warehousing, if something goes
     wrong, you truncate the table (using 'TRUNCATE TABLE')
     and start over from the beginning rather than
     doing a 'ROLLBACK'.

The preceding tips save memory and disk space that can be wasted during
too-long transactions.  When transactions are shorter than they should
be, the problem is excessive I/O. With each 'COMMIT',
MySQL makes sure each change is safely recorded to disk, which involves
some I/O.

   * For most operations on 'InnoDB' tables, you should use the setting
     'autocommit=0'.  From an efficiency perspective, this avoids
     unnecessary I/O when you issue large numbers of consecutive
     'INSERT', 'UPDATE', or 'DELETE'
     statements.  From a safety perspective, this allows you to
     issue a 'ROLLBACK' statement to recover lost or
     garbled data if you make a mistake on the 'mysql'.
     command line, or in an exception handler in your application.

   * The time when 'autocommit=1' is suitable for 'InnoDB' tables is
     when running a sequence of queries for generating reports or
     analyzing statistics.  In this situation, there is no I/O penalty
     related to 'COMMIT' or 'ROLLBACK', and
     'InnoDB' can automatically optimize the read-only workload.

   * If you make a series of related changes, finalize all the changes
     at once with a single 'COMMIT' at the end.  For
     example, if you insert related pieces of information into several
     tables, do a single 'COMMIT' after making all the
     changes.  Or if you run many consecutive 'INSERT'.
     statements, do a single 'COMMIT' after all the data
     is loaded; if you are doing millions of 'INSERT'.
     statements, perhaps split up the huge transaction by issuing a
     'COMMIT' every ten thousand or hundred thousand
     records, so the transaction does not grow too large.

   * Remember that even a 'SELECT' statement opens a
     transaction, so after running some report or debugging queries in
     an interactive 'mysql' session, either issue a
     'COMMIT' or close the 'mysql' session.

*Handling Deadlocks*

You might see warning messages referring to 'deadlocks' in the MySQL
error log, or the output of 'SHOW ENGINE INNODB STATUS'.
Despite the scary-sounding name, a deadlock is not a
serious issue for 'InnoDB' tables, and often does not require any
corrective action.  When two transactions start modifying multiple
tables, accessing the tables in a different order, they can reach a
state where each transaction is waiting for the other and neither can
proceed.  When deadlock detection is enabled (the default), MySQL
immediately detects this condition and cancels (rolls back) the
'smaller' transaction, allowing the other to proceed.  If deadlock
detection is disabled using the 'innodb_deadlock_detect' configuration
option, 'InnoDB' relies on the 'innodb_lock_wait_timeout' setting to
roll back transactions in case of a deadlock.

Either way, your applications need error-handling logic to restart a
transaction that is forcibly cancelled due to a deadlock.  When you
re-issue the same SQL statements as before, the original timing issue no
longer applies.  Either the other transaction has already finished and
yours can proceed, or the other transaction is still in progress and
your transaction waits until it finishes.

If deadlock warnings occur constantly, you might review the application
code to reorder the SQL operations in a consistent way, or to shorten
the transactions.  You can test with the 'innodb_print_all_deadlocks'
option enabled to see all deadlock warnings in the MySQL error log,
rather than only the last warning in the 'SHOW ENGINE INNODB STATUS'
output.

For more information, see innodb-deadlocks.

*Planning the Storage Layout*

To get the best performance from 'InnoDB' tables, you can adjust a
number of parameters related to storage layout.

When you convert 'MyISAM' tables that are large, frequently accessed,
and hold vital data, investigate and consider the
'innodb_file_per_table', 'innodb_file_format', and 'innodb_page_size'
configuration options, and the 'ROW_FORMAT' and 'KEY_BLOCK_SIZE' clauses
of the 'CREATE TABLE'.
statement.

During your initial experiments, the most important setting is
'innodb_file_per_table'.  When this setting is enabled, which is the
default as of MySQL 5.6.6, new 'InnoDB' tables are implicitly created in
file-per-table tablespaces.  In contrast with the 'InnoDB' system
tablespace, file-per-table tablespaces allow disk space to be reclaimed
by the operating system when a table is truncated or dropped.
File-per-table tablespaces also support the Barracuda file format and
associated features such as table compression, efficient off-page
storage for long variable-length columns, and large index prefixes.  For
more information, see innodb-multiple-tablespaces.

You can also store 'InnoDB' tables in a shared general tablespace.
General tablespaces support the Barracuda file format and can contain
multiple tables.  For more information, see general-tablespaces.

*Converting an Existing Table*

To convert a non-'InnoDB' table to use 'InnoDB' use 'ALTER TABLE'.:

     ALTER TABLE TABLE_NAME ENGINE=InnoDB;

*Important*:

Do not convert MySQL system tables in the 'mysql' database from 'MyISAM'
to the 'InnoDB' type.  This is an unsupported operation.  type.

*Cloning the Structure of a Table*

You might make an 'InnoDB' table that is a clone of a MyISAM table,
rather than using 'ALTER TABLE' to perform
conversion, to test the old and new table side-by-side before switching.

Create an empty 'InnoDB' table with identical column and index
definitions.  Use 'SHOW CREATE TABLE TABLE_NAME\G' to see the full
'CREATE TABLE' statement to use.  Change the 'ENGINE'
clause to 'ENGINE=INNODB'.

*Transferring Existing Data*

To transfer a large volume of data into an empty 'InnoDB' table created
as shown in the previous section, insert the rows with 'INSERT INTO
INNODB_TABLE SELECT * FROM MYISAM_TABLE ORDER BY PRIMARY_KEY_COLUMNS'.

You can also create the indexes for the 'InnoDB' table after inserting
the data.  Historically, creating new secondary indexes was a slow
operation for InnoDB, but now you can create the indexes after the data
is loaded with relatively little overhead from the index creation step.

If you have 'UNIQUE' constraints on secondary keys, you can speed up a
table import by turning off the uniqueness checks temporarily during the
import operation:

     SET unique_checks=0;
     ... IMPORT OPERATION ...
     SET unique_checks=1;

For big tables, this saves disk I/O because 'InnoDB' can use its change
buffer to write secondary index records as a batch.  Be certain that the
data contains no duplicate keys.  'unique_checks' permits but does not
require storage engines to ignore duplicate keys.

For better control over the insertion process, you can insert big tables
in pieces:

     INSERT INTO newtable SELECT * FROM oldtable
        WHERE yourkey > SOMETHING AND yourkey <= SOMETHINGELSE;

After all records are inserted, you can rename the tables.

During the conversion of big tables, increase the size of the 'InnoDB'
buffer pool to reduce disk I/O, to a maximum of 80% of physical memory.
You can also increase the size of 'InnoDB' log files.

*Storage Requirements*

If you intend to make several temporary copies of your data in 'InnoDB'
tables during the conversion process, it is recommended that you create
the tables in file-per-table tablespaces so that you can reclaim the
disk space when you drop the tables.  When the 'innodb_file_per_table'
configuration option is enabled (the default), newly created 'InnoDB'
tables are implicitly created in file-per-table tablespaces.

Whether you convert the 'MyISAM' table directly or create a cloned
'InnoDB' table, make sure that you have sufficient disk space to hold
both the old and new tables during the process.  *'InnoDB' tables
require more disk space than 'MyISAM' tables.*  If an 'ALTER TABLE'
operation runs out of space, it starts a rollback,
and that can take hours if it is disk-bound.  For inserts, 'InnoDB' uses
the insert buffer to merge secondary index records to indexes in
batches.  That saves a lot of disk I/O. For rollback, no such mechanism
is used, and the rollback can take 30 times longer than the insertion.

In the case of a runaway rollback, if you do not have valuable data in
your database, it may be advisable to kill the database process rather
than wait for millions of disk I/O operations to complete.  For the
complete procedure, see forcing-innodb-recovery.

*Defining a PRIMARY KEY for Each Table*

The 'PRIMARY KEY' clause is a critical factor affecting the performance
of MySQL queries and the space usage for tables and indexes.  The
primary key uniquely identifies a row in a table.  Every row in the
table must have a primary key value, and no two rows can have the same
primary key value.

These are guidelines for the primary key, followed by more detailed
explanations.

   * Declare a 'PRIMARY KEY' for each table.  Typically, it is the most
     important column that you refer to in 'WHERE' clauses when looking
     up a single row.

   * Declare the 'PRIMARY KEY' clause in the original 'CREATE TABLE'
     statement, rather than adding it later
     through an 'ALTER TABLE' statement.

   * Choose the column and its data type carefully.  Prefer numeric
     columns over character or string ones.

   * Consider using an auto-increment column if there is not another
     stable, unique, non-null, numeric column to use.

   * An auto-increment column is also a good choice if there is any
     doubt whether the value of the primary key column could ever
     change.  Changing the value of a primary key column is an expensive
     operation, possibly involving rearranging data within the table and
     within each secondary index.

Consider adding a primary key to any table that does not already have
one.  Use the smallest practical numeric type based on the maximum
projected size of the table.  This can make each row slightly more
compact, which can yield substantial space savings for large tables.
The space savings are multiplied if the table has any secondary indexes,
because the primary key value is repeated in each secondary index entry.
In addition to reducing data size on disk, a small primary key also lets
more data fit into the buffer pool, speeding up all kinds of operations
and improving concurrency.

If the table already has a primary key on some longer column, such as a
'VARCHAR', consider adding a new unsigned 'AUTO_INCREMENT' column and
switching the primary key to that, even if that column is not referenced
in queries.  This design change can produce substantial space savings in
the secondary indexes.  You can designate the former primary key columns
as 'UNIQUE NOT NULL' to enforce the same constraints as the 'PRIMARY
KEY' clause, that is, to prevent duplicate or null values across all
those columns.

If you spread related information across multiple tables, typically each
table uses the same column for its primary key.  For example, a
personnel database might have several tables, each with a primary key of
employee number.  A sales database might have some tables with a primary
key of customer number, and other tables with a primary key of order
number.  Because lookups using the primary key are very fast, you can
construct efficient join queries for such tables.

If you leave the 'PRIMARY KEY' clause out entirely, MySQL creates an
invisible one for you.  It is a 6-byte value that might be longer than
you need, thus wasting space.  Because it is hidden, you cannot refer to
it in queries.

*Application Performance Considerations*

The reliability and scalability features of 'InnoDB' require more disk
storage than equivalent 'MyISAM' tables.  You might change the column
and index definitions slightly, for better space utilization, reduced
I/O and memory consumption when processing result sets, and better query
optimization plans making efficient use of index lookups.

If you do set up a numeric ID column for the primary key, use that value
to cross-reference with related values in any other tables, particularly
for join queries.  For example, rather than accepting a country name as
input and doing queries searching for the same name, do one lookup to
determine the country ID, then do other queries (or a single join query)
to look up relevant information across several tables.  Rather than
storing a customer or catalog item number as a string of digits,
potentially using up several bytes, convert it to a numeric ID for
storing and querying.  A 4-byte unsigned 'INT'.
column can index over 4 billion items (with the US meaning of billion:
1000 million).  For the ranges of the different integer types, see
integer-types.

*Understanding Files Associated with InnoDB Tables*

'InnoDB' files require more care and planning than 'MyISAM' files do.

   * You must not delete the ibdata files that represent the 'InnoDB'
     system tablespace.

   * Methods of moving or copying 'InnoDB' tables to a different server
     are described in innodb-migration.

14.8.1.5 AUTO_INCREMENT Handling in InnoDB
..........................................

'InnoDB' provides a configurable locking mechanism that can
significantly improve scalability and performance of SQL statements that
add rows to tables with 'AUTO_INCREMENT' columns.  To use the
'AUTO_INCREMENT' mechanism with an 'InnoDB' table, an 'AUTO_INCREMENT'
column must be defined as part of an index such that it is possible to
perform the equivalent of an indexed 'SELECT MAX(AI_COL)' lookup on the
table to obtain the maximum column value.  Typically, this is achieved
by making the column the first column of some table index.

This section describes the behavior of 'AUTO_INCREMENT' lock modes,
usage implications for different 'AUTO_INCREMENT' lock mode settings,
and how 'InnoDB' initializes the 'AUTO_INCREMENT' counter.

   * InnoDB AUTO_INCREMENT Lock Modes

   * InnoDB AUTO_INCREMENT Lock Mode Usage Implications

   * InnoDB AUTO_INCREMENT Counter Initialization

*InnoDB AUTO_INCREMENT Lock Modes*

This section describes the behavior of 'AUTO_INCREMENT' lock modes used
to generate auto-increment values, and how each lock mode affects
replication.  Auto-increment lock modes are configured at startup using
the 'innodb_autoinc_lock_mode' configuration parameter.

The following terms are used in describing 'innodb_autoinc_lock_mode'
settings:

   * ''INSERT'.-like' statements

     All statements that generate new rows in a table, including
     'INSERT', 'INSERT ... SELECT',
     'REPLACE', 'REPLACE ... SELECT', and
     'LOAD DATA'.  Includes 'simple-inserts', 'bulk-inserts',
     and 'mixed-mode' inserts.

   * 'Simple inserts'

     Statements for which the number of rows to be inserted can be
     determined in advance (when the statement is initially processed).
     This includes single-row and multiple-row 'INSERT'.
     and 'REPLACE' statements that do not have a nested
     subquery, but not 'INSERT ... ON DUPLICATE KEY UPDATE'.

   * 'Bulk inserts'

     Statements for which the number of rows to be inserted (and the
     number of required auto-increment values) is not known in advance.
     This includes 'INSERT ... SELECT',
     'REPLACE ... SELECT', and 'LOAD DATA'.
     statements, but not plain 'INSERT'.  'InnoDB' assigns new values
     for the 'AUTO_INCREMENT' column one at a time as each row is
     processed.

   * 'Mixed-mode inserts'

     These are 'simple insert' statements that specify the
     auto-increment value for some (but not all) of the new rows.  An
     example follows, where 'c1' is an 'AUTO_INCREMENT' column of table
     't1':

          INSERT INTO t1 (c1,c2) VALUES (1,'a'), (NULL,'b'), (5,'c'), (NULL,'d');

     Another type of 'mixed-mode insert' is 'INSERT ... ON DUPLICATE KEY UPDATE',
     which in the worst case
     is in effect an 'INSERT' followed by a
     'UPDATE', where the allocated value for the
     'AUTO_INCREMENT' column may or may not be used during the update
     phase.

There are three possible settings for the 'innodb_autoinc_lock_mode'
configuration parameter.  The settings are 0, 1, or 2, for
'traditional', 'consecutive', or 'interleaved' lock mode, respectively.

   * 'innodb_autoinc_lock_mode = 0' ('traditional' lock mode)

     The traditional lock mode provides the same behavior that existed
     before the 'innodb_autoinc_lock_mode' configuration parameter was
     introduced in MySQL 5.1.  The traditional lock mode option is
     provided for backward compatibility, performance testing, and
     working around issues with "mixed-mode inserts", due to possible
     differences in semantics.

     In this lock mode, all 'INSERT-like' statements obtain a special
     table-level 'AUTO-INC' lock for inserts into tables with
     'AUTO_INCREMENT' columns.  This lock is normally held to the end of
     the statement (not to the end of the transaction) to ensure that
     auto-increment values are assigned in a predictable and repeatable
     order for a given sequence of 'INSERT' statements,
     and to ensure that auto-increment values assigned by any given
     statement are consecutive.

     In the case of statement-based replication, this means that when an
     SQL statement is replicated on a slave server, the same values are
     used for the auto-increment column as on the master server.  The
     result of execution of multiple 'INSERT' statements
     is deterministic, and the slave reproduces the same data as on the
     master.  If auto-increment values generated by multiple
     'INSERT' statements were interleaved, the result of two
     concurrent 'INSERT' statements would be
     nondeterministic, and could not reliably be propagated to a slave
     server using statement-based replication.

     To make this clear, consider an example that uses this table:

          CREATE TABLE t1 (
            c1 INT(11) NOT NULL AUTO_INCREMENT,
            c2 VARCHAR(10) DEFAULT NULL,
            PRIMARY KEY (c1)
          ) ENGINE=InnoDB;

     Suppose that there are two transactions running, each inserting
     rows into a table with an 'AUTO_INCREMENT' column.  One transaction
     is using an 'INSERT ... SELECT' statement
     that inserts 1000 rows, and another is using a simple
     'INSERT' statement that inserts one row:

          Tx1: INSERT INTO t1 (c2) SELECT 1000 rows from another table ...
          Tx2: INSERT INTO t1 (c2) VALUES ('xxx');

     'InnoDB' cannot tell in advance how many rows are retrieved from
     the 'SELECT' in the 'INSERT'.
     statement in Tx1, and it assigns the auto-increment values one at a
     time as the statement proceeds.  With a table-level lock, held to
     the end of the statement, only one 'INSERT'.
     statement referring to table 't1' can execute at a time, and the
     generation of auto-increment numbers by different statements is not
     interleaved.  The auto-increment value generated by the Tx1
     'INSERT ... SELECT' statement is consecutive, and
     the (single) auto-increment value used by the 'INSERT'
     statement in Tx2 is either be smaller or larger than all
     those used for Tx1, depending on which statement executes first.

     As long as the SQL statements execute in the same order when
     replayed from the binary log (when using statement-based
     replication, or in recovery scenarios), the results are the same as
     they were when Tx1 and Tx2 first ran.  Thus, table-level locks held
     until the end of a statement make 'INSERT'.
     statements using auto-increment safe for use with statement-based
     replication.  However, those table-level locks limit concurrency
     and scalability when multiple transactions are executing insert
     statements at the same time.

     In the preceding example, if there were no table-level lock, the
     value of the auto-increment column used for the 'INSERT'
     in Tx2 depends on precisely when the statement executes.
     If the 'INSERT' of Tx2 executes while the
     'INSERT' of Tx1 is running (rather than before it starts
     or after it completes), the specific auto-increment values assigned
     by the two 'INSERT' statements are nondeterministic,
     and may vary from run to run.

     Under the consecutive lock mode, 'InnoDB' can avoid using
     table-level 'AUTO-INC' locks for 'simple insert' statements where
     the number of rows is known in advance, and still preserve
     deterministic execution and safety for statement-based replication.

     If you are not using the binary log to replay SQL statements as
     part of recovery or replication, the interleaved lock mode can be
     used to eliminate all use of table-level 'AUTO-INC' locks for even
     greater concurrency and performance, at the cost of permitting gaps
     in auto-increment numbers assigned by a statement and potentially
     having the numbers assigned by concurrently executing statements
     interleaved.

   * 'innodb_autoinc_lock_mode = 1' ('consecutive' lock mode)

     This is the default lock mode.  In this mode, 'bulk inserts' use
     the special 'AUTO-INC' table-level lock and hold it until the end
     of the statement.  This applies to all 'INSERT ... SELECT',
     see 'REPLACE ... SELECT', and 'LOAD DATA'
     statements.  Only one statement holding the
     'AUTO-INC' lock can execute at a time.  If the source table of the
     bulk insert operation is different from the target table, the
     'AUTO-INC' lock on the target table is taken after a shared lock is
     taken on the first row selected from the source table.  If the
     source and target of the bulk insert operation are the same table,
     the 'AUTO-INC' lock is taken after shared locks are taken on all
     selected rows.

     'Simple inserts' (for which the number of rows to be inserted is
     known in advance) avoid table-level 'AUTO-INC' locks by obtaining
     the required number of auto-increment values under the control of a
     mutex (a light-weight lock) that is only held for the duration of
     the allocation process, _not_ until the statement completes.  No
     table-level 'AUTO-INC' lock is used unless an 'AUTO-INC' lock is
     held by another transaction.  If another transaction holds an
     'AUTO-INC' lock, a 'simple insert' waits for the 'AUTO-INC' lock,
     as if it were a 'bulk insert'.

     This lock mode ensures that, in the presence of 'INSERT'
     statements where the number of rows is not known in advance
     (and where auto-increment numbers are assigned as the statement
     progresses), all auto-increment values assigned by any '
     'INSERT'.-like' statement are consecutive, and operations
     are safe for statement-based replication.

     Simply put, this lock mode significantly improves scalability while
     being safe for use with statement-based replication.  Further, as
     with 'traditional' lock mode, auto-increment numbers assigned by
     any given statement are _consecutive_.  There is _no change_ in
     semantics compared to 'traditional' mode for any statement that
     uses auto-increment, with one important exception.

     The exception is for 'mixed-mode inserts', where the user provides
     explicit values for an 'AUTO_INCREMENT' column for some, but not
     all, rows in a multiple-row 'simple insert'.  For such inserts,
     'InnoDB' allocates more auto-increment values than the number of
     rows to be inserted.  However, all values automatically assigned
     are consecutively generated (and thus higher than) the
     auto-increment value generated by the most recently executed
     previous statement.  'Excess' numbers are lost.

   * 'innodb_autoinc_lock_mode = 2' ('interleaved' lock mode)

     In this lock mode, no ''INSERT'.-like' statements use
     the table-level 'AUTO-INC' lock, and multiple statements can
     execute at the same time.  This is the fastest and most scalable
     lock mode, but it is _not safe_ when using statement-based
     replication or recovery scenarios when SQL statements are replayed
     from the binary log.

     In this lock mode, auto-increment values are guaranteed to be
     unique and monotonically increasing across all concurrently
     executing ''INSERT'.-like' statements.  However,
     because multiple statements can be generating numbers at the same
     time (that is, allocation of numbers is _interleaved_ across
     statements), the values generated for the rows inserted by any
     given statement may not be consecutive.

     If the only statements executing are 'simple inserts' where the
     number of rows to be inserted is known ahead of time, there are no
     gaps in the numbers generated for a single statement, except for
     'mixed-mode inserts'.  However, when 'bulk inserts' are executed,
     there may be gaps in the auto-increment values assigned by any
     given statement.

*InnoDB AUTO_INCREMENT Lock Mode Usage Implications*

   * Using auto-increment with replication

     If you are using statement-based replication, set
     'innodb_autoinc_lock_mode' to 0 or 1 and use the same value on the
     master and its slaves.  Auto-increment values are not ensured to be
     the same on the slaves as on the master if you use
     'innodb_autoinc_lock_mode' = 2 ('interleaved') or configurations
     where the master and slaves do not use the same lock mode.

     If you are using row-based or mixed-format replication, all of the
     auto-increment lock modes are safe, since row-based replication is
     not sensitive to the order of execution of the SQL statements (and
     the mixed format uses row-based replication for any statements that
     are unsafe for statement-based replication).

   * 'Lost' auto-increment values and sequence gaps

     In all lock modes (0, 1, and 2), if a transaction that generated
     auto-increment values rolls back, those auto-increment values are
     'lost'.  Once a value is generated for an auto-increment column, it
     cannot be rolled back, whether or not the ''INSERT'.
     -like' statement is completed, and whether or not the
     containing transaction is rolled back.  Such lost values are not
     reused.  Thus, there may be gaps in the values stored in an
     'AUTO_INCREMENT' column of a table.

   * Specifying NULL or 0 for the 'AUTO_INCREMENT' column

     In all lock modes (0, 1, and 2), if a user specifies NULL or 0 for
     the 'AUTO_INCREMENT' column in an 'INSERT', 'InnoDB'
     treats the row as if the value was not specified and generates a
     new value for it.

   * Assigning a negative value to the 'AUTO_INCREMENT' column

     In all lock modes (0, 1, and 2), the behavior of the auto-increment
     mechanism is not defined if you assign a negative value to the
     'AUTO_INCREMENT' column.

   * If the 'AUTO_INCREMENT' value becomes larger than the maximum
     integer for the specified integer type

     In all lock modes (0, 1, and 2), the behavior of the auto-increment
     mechanism is not defined if the value becomes larger than the
     maximum integer that can be stored in the specified integer type.

   * Gaps in auto-increment values for 'bulk inserts'

     With 'innodb_autoinc_lock_mode' set to 0 ('traditional') or 1
     ('consecutive'), the auto-increment values generated by any given
     statement are consecutive, without gaps, because the table-level
     'AUTO-INC' lock is held until the end of the statement, and only
     one such statement can execute at a time.

     With 'innodb_autoinc_lock_mode' set to 2 ('interleaved'), there may
     be gaps in the auto-increment values generated by 'bulk inserts,'
     but only if there are concurrently executing ''INSERT'.
     -like' statements.

     For lock modes 1 or 2, gaps may occur between successive statements
     because for bulk inserts the exact number of auto-increment values
     required by each statement may not be known and overestimation is
     possible.

   * Auto-increment values assigned by 'mixed-mode inserts'

     Consider a 'mixed-mode insert,' where a 'simple insert' specifies
     the auto-increment value for some (but not all) resulting rows.
     Such a statement behaves differently in lock modes 0, 1, and 2.
     For example, assume 'c1' is an 'AUTO_INCREMENT' column of table
     't1', and that the most recent automatically generated sequence
     number is 100.

          mysql> CREATE TABLE t1 (
              -> c1 INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
              -> c2 CHAR(1)
              -> ) ENGINE = INNODB;

     Now, consider the following 'mixed-mode insert' statement:

          mysql> INSERT INTO t1 (c1,c2) VALUES (1,'a'), (NULL,'b'), (5,'c'), (NULL,'d');

     With 'innodb_autoinc_lock_mode' set to 0 ('traditional'), the four
     new rows are:

          mysql> SELECT c1, c2 FROM t1 ORDER BY c2;
          +-----+------+
          | c1  | c2   |
          +-----+------+
          |   1 | a    |
          | 101 | b    |
          |   5 | c    |
          | 102 | d    |
          +-----+------+

     The next available auto-increment value is 103 because the
     auto-increment values are allocated one at a time, not all at once
     at the beginning of statement execution.  This result is true
     whether or not there are concurrently executing ''INSERT'.
     -like' statements (of any type).

     With 'innodb_autoinc_lock_mode' set to 1 ('consecutive'), the four
     new rows are also:

          mysql> SELECT c1, c2 FROM t1 ORDER BY c2;
          +-----+------+
          | c1  | c2   |
          +-----+------+
          |   1 | a    |
          | 101 | b    |
          |   5 | c    |
          | 102 | d    |
          +-----+------+

     However, in this case, the next available auto-increment value is
     105, not 103 because four auto-increment values are allocated at
     the time the statement is processed, but only two are used.  This
     result is true whether or not there are concurrently executing
     ''INSERT'.-like' statements (of any type).

     With 'innodb_autoinc_lock_mode' set to mode 2 ('interleaved'), the
     four new rows are:

          mysql> SELECT c1, c2 FROM t1 ORDER BY c2;
          +-----+------+
          | c1  | c2   |
          +-----+------+
          |   1 | a    |
          |   X | b    |
          |   5 | c    |
          |   Y | d    |
          +-----+------+

     The values of X and Y are unique and larger than any previously
     generated rows.  However, the specific values of X and Y depend on
     the number of auto-increment values generated by concurrently
     executing statements.

     Finally, consider the following statement, issued when the
     most-recently generated sequence number is 100:

          mysql> INSERT INTO t1 (c1,c2) VALUES (1,'a'), (NULL,'b'), (101,'c'), (NULL,'d');

     With any 'innodb_autoinc_lock_mode' setting, this statement
     generates a duplicate-key error 23000 ('Can't write; duplicate key
     in table') because 101 is allocated for the row '(NULL, 'b')' and
     insertion of the row '(101, 'c')' fails.

   * Modifying 'AUTO_INCREMENT' column values in the middle of a
     sequence of 'INSERT' statements

     In all lock modes (0, 1, and 2), modifying an 'AUTO_INCREMENT'
     column value in the middle of a sequence of 'INSERT'.
     statements could lead to 'Duplicate entry' errors.  For example, if
     you perform an 'UPDATE' operation that changes an
     'AUTO_INCREMENT' column value to a value larger than the current
     maximum auto-increment value, subsequent 'INSERT'.
     operations that do not specify an unused auto-increment value could
     encounter 'Duplicate entry' errors.  This behavior is demonstrated
     in the following example.

          mysql> CREATE TABLE t1 (
              -> c1 INT NOT NULL AUTO_INCREMENT,
              -> PRIMARY KEY (c1)
              ->  ) ENGINE = InnoDB;

          mysql> INSERT INTO t1 VALUES(0), (0), (3);

          mysql> SELECT c1 FROM t1;
          +----+
          | c1 |
          +----+
          |  1 |
          |  2 |
          |  3 |
          +----+

          mysql> UPDATE t1 SET c1 = 4 WHERE c1 = 1;

          mysql> SELECT c1 FROM t1;
          +----+
          | c1 |
          +----+
          |  2 |
          |  3 |
          |  4 |
          +----+

          mysql> INSERT INTO t1 VALUES(0);
          ERROR 1062 (23000): Duplicate entry '4' for key 'PRIMARY'

*InnoDB AUTO_INCREMENT Counter Initialization*

This section describes how 'InnoDB' initializes 'AUTO_INCREMENT'
counters.

If you specify an 'AUTO_INCREMENT' column for an 'InnoDB' table, the
table handle in the 'InnoDB' data dictionary contains a special counter
called the auto-increment counter that is used in assigning new values
for the column.  This counter is stored only in main memory, not on
disk.

To initialize an auto-increment counter after a server restart, 'InnoDB'
executes the equivalent of the following statement on the first insert
into a table containing an 'AUTO_INCREMENT' column.

     SELECT MAX(ai_col) FROM TABLE_NAME FOR UPDATE;

'InnoDB' increments the value retrieved by the statement and assigns it
to the column and to the auto-increment counter for the table.  By
default, the value is incremented by 1.  This default can be overridden
by the 'auto_increment_increment' configuration setting.

If the table is empty, 'InnoDB' uses the value '1'.  This default can be
overridden by the 'auto_increment_offset' configuration setting.

If a 'SHOW TABLE STATUS' statement examines
the table before the auto-increment counter is initialized, 'InnoDB'
initializes but does not increment the value.  The value is stored for
use by later inserts.  This initialization uses a normal
exclusive-locking read on the table and the lock lasts to the end of the
transaction.  'InnoDB' follows the same procedure for initializing the
auto-increment counter for a newly created table.

After the auto-increment counter has been initialized, if you do not
explicitly specify a value for an 'AUTO_INCREMENT' column, 'InnoDB'
increments the counter and assigns the new value to the column.  If you
insert a row that explicitly specifies the column value, and the value
is greater than the current counter value, the counter is set to the
specified column value.

'InnoDB' uses the in-memory auto-increment counter as long as the server
runs.  When the server is stopped and restarted, 'InnoDB' reinitializes
the counter for each table for the first 'INSERT' to the
table, as described earlier.

A server restart also cancels the effect of the 'AUTO_INCREMENT = N'
table option in 'CREATE TABLE' and 'ALTER TABLE'
statements, which you can use with 'InnoDB' tables
to set the initial counter value or alter the current counter value.

14.8.1.6 InnoDB and FOREIGN KEY Constraints
...........................................

How the 'InnoDB' storage engine handles foreign key constraints is
described under the following topics in this section:

   * innodb-foreign-key-definitions

   * innodb-foreign-key-referential-actions

   * innodb-foreign-key-generated-columns

   * innodb-foreign-key-usage-errors

For foreign key usage information and examples, see
create-table-foreign-keys.

*Foreign Key Definitions*

Foreign key definitions for 'InnoDB' tables are subject to the following
conditions:

   * 'InnoDB' permits a foreign key to reference any index column or
     group of columns.  However, in the referenced table, there must be
     an index where the referenced columns are listed as the _first_
     columns in the same order.

   * 'InnoDB' does not currently support
     foreign keys for tables with user-defined partitioning.  This means
     that no user-partitioned 'InnoDB' table may contain foreign key
     references or columns referenced by foreign keys.

   * 'InnoDB' allows a foreign key constraint to reference a nonunique
     key.  _This is an 'InnoDB' extension to standard SQL._

*Referential Actions*

Referential actions for foreign keys of 'InnoDB' tables are subject to
the following conditions:

   * While 'SET DEFAULT' is allowed by the MySQL Server, it is rejected
     as invalid by 'InnoDB'.  'CREATE TABLE' and
     'ALTER TABLE' statements using this clause are
     not allowed for InnoDB tables.

   * If there are several rows in the parent table that have the same
     referenced key value, 'InnoDB' acts in foreign key checks as if the
     other parent rows with the same key value do not exist.  For
     example, if you have defined a 'RESTRICT' type constraint, and
     there is a child row with several parent rows, 'InnoDB' does not
     permit the deletion of any of those parent rows.

   * 'InnoDB' performs cascading operations through a depth-first
     algorithm, based on records in the indexes corresponding to the
     foreign key constraints.

   * If 'ON UPDATE CASCADE' or 'ON UPDATE SET NULL' recurses to update
     the _same table_ it has previously updated during the cascade, it
     acts like 'RESTRICT'.  This means that you cannot use
     self-referential 'ON UPDATE CASCADE' or 'ON UPDATE SET NULL'
     operations.  This is to prevent infinite loops resulting from
     cascaded updates.  A self-referential 'ON DELETE SET NULL', on the
     other hand, is possible, as is a self-referential 'ON DELETE
     CASCADE'.  Cascading operations may not be nested more than 15
     levels deep.

   * Like MySQL in general, in an SQL statement that inserts, deletes,
     or updates many rows, 'InnoDB' checks 'UNIQUE' and 'FOREIGN KEY'
     constraints row-by-row.  When performing foreign key checks,
     'InnoDB' sets shared row-level locks on child or parent records it
     has to look at.  'InnoDB' checks foreign key constraints
     immediately; the check is not deferred to transaction commit.
     According to the SQL standard, the default behavior should be
     deferred checking.  That is, constraints are only checked after the
     _entire SQL statement_ has been processed.  Until 'InnoDB'
     implements deferred constraint checking, some things are
     impossible, such as deleting a record that refers to itself using a
     foreign key.

*Foreign Key Restrictions for Generated Columns and Virtual Indexes*

   * A foreign key constraint on a stored generated column cannot use
     'ON UPDATE CASCADE', 'ON DELETE SET NULL', 'ON UPDATE SET NULL',
     'ON DELETE SET DEFAULT', or 'ON UPDATE SET DEFAULT'.

   * A foreign key constraint cannot reference a virtual generated
     column.

   * Prior to 5.7.16, a foreign key constraint cannot reference a
     secondary index defined on a virtual generated column.

   * In MySQL 5.7.13 and earlier, 'InnoDB' does not permit defining a
     foreign key constraint with a cascading referential action on the
     base column of an indexed virtual generated column.  This
     restriction is lifted in MySQL 5.7.14.

   * In MySQL 5.7.13 and earlier, 'InnoDB' does not permit defining
     cascading referential actions on non-virtual foreign key columns
     that are explicitly included in a virtual index.  This restriction
     is lifted in MySQL 5.7.14.

*Foreign Key Usage and Error Information*

You can obtain general information about foreign keys and their usage
from querying the 'INFORMATION_SCHEMA.KEY_COLUMN_USAGE'
table, and more information more specific to
'InnoDB' tables can be found in the 'INNODB_SYS_FOREIGN'
and 'INNODB_SYS_FOREIGN_COLS'
tables, also in the 'INFORMATION_SCHEMA'
database.

In addition to 'SHOW ERRORS', in the event of a
foreign key error involving 'InnoDB' tables (usually Error 150 in the
MySQL Server), you can obtain a detailed explanation of the most recent
'InnoDB' foreign key error by checking the output of 'SHOW ENGINE INNODB STATUS'.

14.8.1.7 Limits on InnoDB Tables
................................

Limits on 'InnoDB' tables are described under the following topics in
this section:

   * innodb-maximums-minimums

   * innodb-table-restrictions

   * innodb-locking-transactions

*Warning*:

Do _not_ convert MySQL system tables in the 'mysql' database from
'MyISAM' to 'InnoDB' tables.  This is an unsupported operation.  If you
do this, MySQL does not restart until you restore the old system tables
from a backup or regenerate them by reinitializing the data directory
(see data-directory-initialization).

*Warning*:

Before using NFS with 'InnoDB', review potential issues outlined in
disk-issues-nfs.

*Maximums and Minimums*

   * A table can contain a maximum of 1017 columns (raised in MySQL
     5.6.9 from the earlier limit of 1000).  Virtual generated columns
     are included in this limit.

   * A table can contain a maximum of 64 secondary indexes.

   * If 'innodb_large_prefix' is enabled (the default), the index key
     prefix limit is 3072 bytes for 'InnoDB' tables that use 'DYNAMIC'
     or 'COMPRESSED' row format.  If 'innodb_large_prefix' is disabled,
     the index key prefix limit is 767 bytes for tables of any row
     format.

     'innodb_large_prefix' is deprecated and will be removed in a future
     release.  'innodb_large_prefix' was introduced in MySQL 5.5 to
     disable large index key prefixes for compatibility with earlier
     versions of 'InnoDB' that do not support large index key prefixes.

     The index key prefix length limit is 767 bytes for 'InnoDB' tables
     that use the 'REDUNDANT' or 'COMPACT' row format.  For example, you
     might hit this limit with a column prefix index of more than 255
     characters on a 'TEXT' or 'VARCHAR' column, assuming a 'utf8mb3'
     character set and the maximum of 3 bytes for each character.

     Attempting to use an index key prefix length that exceeds the limit
     returns an error.  To avoid such errors in replication
     configurations, avoid enabling 'innodb_large_prefix' on the master
     if it cannot also be enabled on slaves.

     The limits that apply to index key prefixes also apply to
     full-column index keys.

   * If you reduce the 'InnoDB' page size to 8KB or 4KB by specifying
     the 'innodb_page_size' option when creating the MySQL instance, the
     maximum length of the index key is lowered proportionally, based on
     the limit of 3072 bytes for a 16KB page size.  That is, the maximum
     index key length is 1536 bytes when the page size is 8KB, and 768
     bytes when the page size is 4KB.

   * A maximum of 16 columns is permitted for multicolumn indexes.
     Exceeding the limit returns an error.

          ERROR 1070 (42000): Too many key parts specified; max 16 parts allowed

   * The maximum row length, except for variable-length columns (see
     'VARBINARY', 'VARCHAR', 'BLOB'
     and 'TEXT'), is slightly less than half of a
     page for 4KB, 8KB, 16KB, and 32KB page sizes.  For example, the
     maximum row length for the default 'innodb_page_size' of 16KB is
     about 8000 bytes.  For an 'InnoDB' page size of 64KB, the maximum
     row length is about 16000 bytes.  'LONGBLOB' and
     'LONGTEXT' columns must be less than 4GB, and the total row
     length, including 'BLOB' and 'TEXT'.
     columns, must be less than 4GB.

     If a row is less than half a page long, all of it is stored locally
     within the page.  If it exceeds half a page, variable-length
     columns are chosen for external off-page storage until the row fits
     within half a page, as described in innodb-file-space.

   * Although 'InnoDB' supports row sizes larger than 65,535 bytes
     internally, MySQL itself imposes a row-size limit of 65,535 for the
     combined size of all columns:

          mysql> CREATE TABLE t (a VARCHAR(8000), b VARCHAR(10000),
              -> c VARCHAR(10000), d VARCHAR(10000), e VARCHAR(10000),
              -> f VARCHAR(10000), g VARCHAR(10000)) ENGINE=InnoDB;
          ERROR 1118 (42000): Row size too large. The maximum row size for the
          used table type, not counting BLOBs, is 65535. You have to change some
          columns to TEXT or BLOBs

     See column-count-limit.

   * On some older operating systems, files must be less than 2GB. This
     is not a limitation of 'InnoDB' itself, but if you require a large
     tablespace, configure it using several smaller data files rather
     than one large data file.

   * The combined size of the 'InnoDB' log files can be up to 512GB.

   * The minimum tablespace size is slightly larger than 10MB. The
     maximum tablespace size depends on the 'InnoDB' page size.

     *InnoDB Maximum Tablespace Size*

     InnoDB Page Size              Maximum Tablespace Size

     4KB                           16TB

     8KB                           32TB

     16KB                          64TB

     32KB                          128TB

     64KB                          256TB

     The maximum tablespace size is also the maximum size for a table.

   *
     The default page size in 'InnoDB' is 16KB. You can increase or
     decrease the page size by configuring the 'innodb_page_size' option
     when creating the MySQL instance.

     'ROW_FORMAT=COMPRESSED' in the Barracuda file format assumes that
     the page size is at most 16KB and uses 14-bit pointers.

     32KB and 64KB page sizes are supported, but 'ROW_FORMAT=COMPRESSED'
     is unsupported for page sizes greater than 16KB. For both 32KB and
     64KB page sizes, the maximum record size is 16KB. For
     'innodb_page_size=32k', extent size is 2MB. For
     'innodb_page_size=64k', extent size is 4MB.

     A MySQL instance using a particular 'InnoDB' page size cannot use
     data files or log files from an instance that uses a different page
     size.

*Restrictions on InnoDB Tables*

   * 'ANALYZE TABLE' determines index cardinality
     (as displayed in the 'Cardinality' column of 'SHOW INDEX'
     output) by performing random dives on each of the index
     trees and updating index cardinality estimates accordingly.
     Because these are only estimates, repeated runs of 'ANALYZE TABLE'
     could produce different numbers.  This makes
     'ANALYZE TABLE' fast on 'InnoDB' tables but
     not 100% accurate because it does not take all rows into account.

     You can make the statistics collected by 'ANALYZE TABLE'
     more precise and more stable by turning on the
     'innodb_stats_persistent' configuration option, as explained in
     innodb-persistent-stats.  When that setting is enabled, it
     is important to run 'ANALYZE TABLE' after
     major changes to indexed column data, because the statistics are
     not recalculated periodically (such as after a server restart).

     If the persistent statistics setting is enabled, you can change the
     number of random dives by modifying the
     'innodb_stats_persistent_sample_pages' system variable.  If the
     persistent statistics setting is disabled, modify the
     'innodb_stats_transient_sample_pages' system variable instead.

     MySQL uses index cardinality estimates in join optimization.  If a
     join is not optimized in the right way, try using 'ANALYZE TABLE'.
     In the few cases that 'ANALYZE TABLE'
     does not produce values good enough for your
     particular tables, you can use 'FORCE INDEX' with your queries to
     force the use of a particular index, or set the 'max_seeks_for_key'
     system variable to ensure that MySQL prefers index lookups over
     table scans.  See optimizer-issues.

   * If statements or transactions are running on a table, and
     'ANALYZE TABLE' is run on the same table followed
     by a second 'ANALYZE TABLE' operation, the
     second 'ANALYZE TABLE' operation is blocked
     until the statements or transactions are completed.  This behavior
     occurs because 'ANALYZE TABLE' marks the
     currently loaded table definition as obsolete when 'ANALYZE TABLE'
     is finished running.  New statements or
     transactions (including a second 'ANALYZE TABLE'
     statement) must load the new table definition into
     the table cache, which cannot occur until currently running
     statements or transactions are completed and the old table
     definition is purged.  Loading multiple concurrent table
     definitions is not supported.

   * 'SHOW TABLE STATUS' does not give
     accurate statistics on 'InnoDB' tables except for the physical size
     reserved by the table.  The row count is only a rough estimate used
     in SQL optimization.

   * 'InnoDB' does not keep an internal count of rows in a table because
     concurrent transactions might 'see' different numbers of rows at
     the same time.  Consequently, 'SELECT COUNT(*)' statements only
     count rows visible to the current transaction.

     Prior to MySQL 5.7.18, 'InnoDB' processes 'SELECT COUNT(*)'
     statements by scanning the clustered index.  As of MySQL 5.7.18,
     'InnoDB' processes 'SELECT COUNT(*)' statements by traversing a
     smaller secondary index, if present.

     Processing 'SELECT COUNT(*)' statements takes some time if index
     records are not entirely in the buffer pool.  For a faster count,
     you can create a counter table and let your application update it
     according to the inserts and deletes it does.  However, this method
     may not scale well in situations where thousands of concurrent
     transactions are initiating updates to the same counter table.  If
     an approximate row count is sufficient, see 'SHOW TABLE STATUS'
     can be used.

     'InnoDB' handles 'SELECT COUNT(*)' and 'SELECT COUNT(1)' operations
     in the same way.  There is no performance difference.

   * On Windows, 'InnoDB' always stores database and table names
     internally in lowercase.  To move databases in a binary format from
     Unix to Windows or from Windows to Unix, create all databases and
     tables using lowercase names.

   * An 'AUTO_INCREMENT' column AI_COL must be defined as part of an
     index such that it is possible to perform the equivalent of an
     indexed 'SELECT MAX(AI_COL)' lookup on the table to obtain the
     maximum column value.  Typically, this is achieved by making the
     column the first column of some table index.

   * 'InnoDB' sets an exclusive lock on the end of the index associated
     with the 'AUTO_INCREMENT' column while initializing a previously
     specified 'AUTO_INCREMENT' column on a table.

     With 'innodb_autoinc_lock_mode=0', 'InnoDB' uses a special
     'AUTO-INC' table lock mode where the lock is obtained and held to
     the end of the current SQL statement while accessing the
     auto-increment counter.  Other clients cannot insert into the table
     while the 'AUTO-INC' table lock is held.  The same behavior occurs
     for 'bulk inserts' with 'innodb_autoinc_lock_mode=1'.  Table-level
     'AUTO-INC' locks are not used with 'innodb_autoinc_lock_mode=2'.
     For more information, See innodb-auto-increment-handling.

   * When you restart the MySQL server, 'InnoDB' may reuse an old value
     that was generated for an 'AUTO_INCREMENT' column but never stored
     (that is, a value that was generated during an old transaction that
     was rolled back).

   * When an 'AUTO_INCREMENT' integer column runs out of values, a
     subsequent 'INSERT' operation returns a duplicate-key error.  This
     is general MySQL behavior.

   * 'DELETE FROM TBL_NAME' does not regenerate the table but instead
     deletes all rows, one by one.

   * Cascaded foreign key actions do not activate triggers.

   * You cannot create a table with a column name that matches the name
     of an internal 'InnoDB' column (including 'DB_ROW_ID', 'DB_TRX_ID',
     'DB_ROLL_PTR', and 'DB_MIX_ID').  This restriction applies to use
     of the names in any letter case.

          mysql> CREATE TABLE t1 (c1 INT, db_row_id INT) ENGINE=INNODB;
          ERROR 1166 (42000): Incorrect column name 'db_row_id'

*Locking and Transactions*

   * 'LOCK TABLES' acquires two locks on each table
     if 'innodb_table_locks=1' (the default).  In addition to a table
     lock on the MySQL layer, it also acquires an 'InnoDB' table lock.
     Versions of MySQL before 4.1.2 did not acquire 'InnoDB' table
     locks; the old behavior can be selected by setting
     'innodb_table_locks=0'.  If no 'InnoDB' table lock is acquired,
     see 'LOCK TABLES' completes even if some records of
     the tables are being locked by other transactions.

     In MySQL 5.7, 'innodb_table_locks=0' has no effect for tables
     locked explicitly with 'LOCK TABLES ... WRITE'.
     It does have an effect for tables locked for read or write by
     'LOCK TABLES ... WRITE' implicitly (for example,
     through triggers) or by 'LOCK TABLES ... READ'.

   * All 'InnoDB' locks held by a transaction are released when the
     transaction is committed or aborted.  Thus, it does not make much
     sense to invoke 'LOCK TABLES' on 'InnoDB'
     tables in 'autocommit=1' mode because the acquired 'InnoDB' table
     locks would be released immediately.

   * You cannot lock additional tables in the middle of a transaction
     because 'LOCK TABLES' performs an implicit
     'COMMIT' and 'UNLOCK TABLES'.

   * The limit on data-modifying transactions is 96 * 1023 concurrent
     transactions that generate undo records.  32 of 128 rollback
     segments are assigned to non-redo logs for transactions that modify
     temporary tables and related objects.  This reduces the maximum
     number of concurrent data-modifying transactions from 128K to 96K.
     The 96K limit assumes that transactions do not modify temporary
     tables.  If all data-modifying transactions also modify temporary
     tables, the limit is 32K concurrent transactions.

14.8.2 InnoDB Indexes
---------------------

This section covers topics related to 'InnoDB' indexes.

14.8.2.1 Clustered and Secondary Indexes
........................................

Every 'InnoDB' table has a special index called the clustered index
where the data for the rows is stored.  Typically, the clustered index
is synonymous with the primary key.  To get the best performance from
queries, inserts, and other database operations, you must understand how
'InnoDB' uses the clustered index to optimize the most common lookup and
DML operations for each table.

   * When you define a 'PRIMARY KEY' on your table, 'InnoDB' uses it as
     the clustered index.  Define a primary key for each table that you
     create.  If there is no logical unique and non-null column or set
     of columns, add a new auto-increment column, whose values are
     filled in automatically.

   * If you do not define a 'PRIMARY KEY' for your table, MySQL locates
     the first 'UNIQUE' index where all the key columns are 'NOT NULL'
     and 'InnoDB' uses it as the clustered index.

   * If the table has no 'PRIMARY KEY' or suitable 'UNIQUE' index,
     'InnoDB' internally generates a hidden clustered index named
     'GEN_CLUST_INDEX' on a synthetic column containing row ID values.
     The rows are ordered by the ID that 'InnoDB' assigns to the rows in
     such a table.  The row ID is a 6-byte field that increases
     monotonically as new rows are inserted.  Thus, the rows ordered by
     the row ID are physically in insertion order.

*How the Clustered Index Speeds Up Queries*

Accessing a row through the clustered index is fast because the index
search leads directly to the page with all the row data.  If a table is
large, the clustered index architecture often saves a disk I/O operation
when compared to storage organizations that store row data using a
different page from the index record.

*How Secondary Indexes Relate to the Clustered Index*

All indexes other than the clustered index are known as secondary
indexes.  In 'InnoDB', each record in a secondary index contains the
primary key columns for the row, as well as the columns specified for
the secondary index.  'InnoDB' uses this primary key value to search for
the row in the clustered index.

If the primary key is long, the secondary indexes use more space, so it
is advantageous to have a short primary key.

For guidelines to take advantage of 'InnoDB' clustered and secondary
indexes, see optimization-indexes.

14.8.2.2 The Physical Structure of an InnoDB Index
..................................................

With the exception of spatial indexes, 'InnoDB' indexes are B-tree data
structures.  Spatial indexes use R-trees, which are specialized data
structures for indexing multi-dimensional data.  Index records are
stored in the leaf pages of their B-tree or R-tree data structure.  The
default size of an index page is 16KB.

When new records are inserted into an 'InnoDB' clustered index, 'InnoDB'
tries to leave 1/16 of the page free for future insertions and updates
of the index records.  If index records are inserted in a sequential
order (ascending or descending), the resulting index pages are about
15/16 full.  If records are inserted in a random order, the pages are
from 1/2 to 15/16 full.

'InnoDB' performs a bulk load when creating or rebuilding B-tree
indexes.  This method of index creation is known as a sorted index
build.  The 'innodb_fill_factor' configuration option defines the
percentage of space on each B-tree page that is filled during a sorted
index build, with the remaining space reserved for future index growth.
Sorted index builds are not supported for spatial indexes.  For more
information, see sorted-index-builds.  An 'innodb_fill_factor'
setting of 100 leaves 1/16 of the space in clustered index pages free
for future index growth.

If the fill factor of an 'InnoDB' index page drops below the
'MERGE_THRESHOLD', which is 50% by default if not specified, 'InnoDB'
tries to contract the index tree to free the page.  The
'MERGE_THRESHOLD' setting applies to both B-tree and R-tree indexes.
For more information, see index-page-merge-threshold.

You can define the page size for all 'InnoDB' tablespaces in a MySQL
instance by setting the 'innodb_page_size' configuration option prior to
initializing the MySQL instance.  Once the page size for an instance is
defined, you cannot change it without reinitializing the instance.
Supported sizes are 64KB, 32KB, 16KB (default), 8KB, and 4KB,
corresponding to the option values '64k', '32k', '16k', '8k', and '4k'.

Support for 32KB and 64KB pages sizes was added in MySQL 5.7.  For more
information, refer to the 'innodb_page_size' documentation.

A MySQL instance using a particular 'InnoDB' page size cannot use data
files or log files from an instance that uses a different page size.

14.8.2.3 Sorted Index Builds
............................

'InnoDB' performs a bulk load instead of inserting one index record at a
time when creating or rebuilding indexes.  This method of index creation
is also known as a sorted index build.  Sorted index builds are not
supported for spatial indexes.

There are three phases to an index build.  In the first phase, the
clustered index is scanned, and index entries are generated and added to
the sort buffer.  When the sort buffer becomes full, entries are sorted
and written out to a temporary intermediate file.  This process is also
known as a 'run'.  In the second phase, with one or more runs written to
the temporary intermediate file, a merge sort is performed on all
entries in the file.  In the third and final phase, the sorted entries
are inserted into the B-tree.

Prior to the introduction of sorted index builds, index entries were
inserted into the B-tree one record at a time using insert APIs.  This
method involved opening a B-tree cursor to find the insert position and
then inserting entries into a B-tree page using an optimistic insert.
If an insert failed due to a page being full, a pessimistic insert would
be performed, which involves opening a B-tree cursor and splitting and
merging B-tree nodes as necessary to find space for the entry.  The
drawbacks of this 'top-down' method of building an index are the cost of
searching for an insert position and the constant splitting and merging
of B-tree nodes.

Sorted index builds use a 'bottom-up' approach to building an index.
With this approach, a reference to the right-most leaf page is held at
all levels of the B-tree.  The right-most leaf page at the necessary
B-tree depth is allocated and entries are inserted according to their
sorted order.  Once a leaf page is full, a node pointer is appended to
the parent page and a sibling leaf page is allocated for the next
insert.  This process continues until all entries are inserted, which
may result in inserts up to the root level.  When a sibling page is
allocated, the reference to the previously pinned leaf page is released,
and the newly allocated leaf page becomes the right-most leaf page and
new default insert location.

*Reserving B-tree Page Space for Future Index Growth*

To set aside space for future index growth, you can use the
'innodb_fill_factor' configuration option to reserve a percentage of
B-tree page space.  For example, setting 'innodb_fill_factor' to 80
reserves 20 percent of the space in B-tree pages during a sorted index
build.  This setting applies to both B-tree leaf and non-leaf pages.  It
does not apply to external pages used for 'TEXT' or
'BLOB' entries.  The amount of space that is reserved may not be
exactly as configured, as the 'innodb_fill_factor' value is interpreted
as a hint rather than a hard limit.

*Sorted Index Builds and Full-Text Index Support*

Sorted index builds are supported for fulltext indexes.  Previously, SQL
was used to insert entries into a fulltext index.

*Sorted Index Builds and Compressed Tables*

For compressed tables, the previous index creation method appended
entries to both compressed and uncompressed pages.  When the
modification log (representing free space on the compressed page) became
full, the compressed page would be recompressed.  If compression failed
due to a lack of space, the page would be split.  With sorted index
builds, entries are only appended to uncompressed pages.  When an
uncompressed page becomes full, it is compressed.  Adaptive padding is
used to ensure that compression succeeds in most cases, but if
compression fails, the page is split and compression is attempted again.
This process continues until compression is successful.  For more
information about compression of B-Tree pages, see
innodb-compression-internals.

*Sorted Index Builds and Redo Logging*

Redo logging is disabled during a sorted index build.  Instead, there is
a checkpoint to ensure that the index build can withstand a crash or
failure.  The checkpoint forces a write of all dirty pages to disk.
During a sorted index build, the page cleaner thread is signaled
periodically to flush dirty pages to ensure that the checkpoint
operation can be processed quickly.  Normally, the page cleaner thread
flushes dirty pages when the number of clean pages falls below a set
threshold.  For sorted index builds, dirty pages are flushed promptly to
reduce checkpoint overhead and to parallelize I/O and CPU activity.

*Sorted Index Builds and Optimizer Statistics*

Sorted index builds may result in optimizer statistics that differ from
those generated by the previous method of index creation.  The
difference in statistics, which is not expected to affect workload
performance, is due to the different algorithm used to populate the
index.

14.8.2.4 InnoDB FULLTEXT Indexes
................................

'FULLTEXT' indexes are created on text-based columns (see 'CHAR',
see 'VARCHAR', or 'TEXT' columns) to help
speed up queries and DML operations on data contained within those
columns, omitting any words that are defined as stopwords.

A 'FULLTEXT' index is defined as part of a 'CREATE TABLE'
statement or added to an existing table using 'ALTER TABLE'
or 'CREATE INDEX'.

Full-text search is performed using 'MATCH() ... AGAINST' syntax.  For
usage information, see fulltext-search.

'InnoDB' 'FULLTEXT' indexes are described under the following topics in
this section:

   * innodb-fulltext-index-design

   * innodb-fulltext-index-tables

   * innodb-fulltext-index-cache

   * innodb-fulltext-index-docid

   * innodb-fulltext-index-deletion

   * innodb-fulltext-index-transaction

   * innodb-fulltext-index-monitoring

*InnoDB Full-Text Index Design*

'InnoDB' 'FULLTEXT' indexes have an inverted index design.  Inverted
indexes store a list of words, and for each word, a list of documents
that the word appears in.  To support proximity search, position
information for each word is also stored, as a byte offset.

*InnoDB Full-Text Index Tables*

When creating an 'InnoDB' 'FULLTEXT' index, a set of index tables is
created, as shown in the following example:

     mysql> CREATE TABLE opening_lines (
            id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
            opening_line TEXT(500),
            author VARCHAR(200),
            title VARCHAR(200),
            FULLTEXT idx (opening_line)
            ) ENGINE=InnoDB;

     mysql> SELECT table_id, name, space from INFORMATION_SCHEMA.INNODB_SYS_TABLES
            WHERE name LIKE 'test/%';
     +----------+----------------------------------------------------+-------+
     | table_id | name                                               | space |
     +----------+----------------------------------------------------+-------+
     |      333 | test/FTS_0000000000000147_00000000000001c9_INDEX_1 |   289 |
     |      334 | test/FTS_0000000000000147_00000000000001c9_INDEX_2 |   290 |
     |      335 | test/FTS_0000000000000147_00000000000001c9_INDEX_3 |   291 |
     |      336 | test/FTS_0000000000000147_00000000000001c9_INDEX_4 |   292 |
     |      337 | test/FTS_0000000000000147_00000000000001c9_INDEX_5 |   293 |
     |      338 | test/FTS_0000000000000147_00000000000001c9_INDEX_6 |   294 |
     |      330 | test/FTS_0000000000000147_BEING_DELETED            |   286 |
     |      331 | test/FTS_0000000000000147_BEING_DELETED_CACHE      |   287 |
     |      332 | test/FTS_0000000000000147_CONFIG                   |   288 |
     |      328 | test/FTS_0000000000000147_DELETED                  |   284 |
     |      329 | test/FTS_0000000000000147_DELETED_CACHE            |   285 |
     |      327 | test/opening_lines                                 |   283 |
     +----------+----------------------------------------------------+-------+

The first six tables represent the inverted index and are referred to as
auxiliary index tables.  When incoming documents are tokenized, the
individual words (also referred to as 'tokens') are inserted into the
index tables along with position information and the associated Document
ID ('DOC_ID').  The words are fully sorted and partitioned among the six
index tables based on the character set sort weight of the word's first
character.

The inverted index is partitioned into six auxiliary index tables to
support parallel index creation.  By default, two threads tokenize,
sort, and insert words and associated data into the index tables.  The
number of threads is configurable using the 'innodb_ft_sort_pll_degree'
option.  Consider increasing the number of threads when creating
'FULLTEXT' indexes on large tables.

Auxiliary index table names are prefixed with 'FTS_' and postfixed with
'INDEX_*'.  Each index table is associated with the indexed table by a
hex value in the index table name that matches the 'table_id' of the
indexed table.  For example, the 'table_id' of the 'test/opening_lines'
table is '327', for which the hex value is 0x147.  As shown in the
preceding example, the '147' hex value appears in the names of index
tables that are associated with the 'test/opening_lines' table.

A hex value representing the 'index_id' of the 'FULLTEXT' index also
appears in auxiliary index table names.  For example, in the auxiliary
table name 'test/FTS_0000000000000147_00000000000001c9_INDEX_1', the hex
value '1c9' has a decimal value of 457.  The index defined on the
'opening_lines' table ('idx') can be identified by querying the
'INFORMATION_SCHEMA.INNODB_SYS_INDEXES' table
for this value (457).

     mysql> SELECT index_id, name, table_id, space from INFORMATION_SCHEMA.INNODB_SYS_INDEXES
            WHERE index_id=457;
     +----------+------+----------+-------+
     | index_id | name | table_id | space |
     +----------+------+----------+-------+
     |      457 | idx  |      327 |   283 |
     +----------+------+----------+-------+

Index tables are stored in their own tablespace if the primary table is
created in a file-per-table tablespace.

The other index tables shown in the preceding example are referred to as
common index tables and are used for deletion handling and storing the
internal state of 'FULLTEXT' indexes.  Unlike the inverted index tables,
which are created for each full-text index, this set of tables is common
to all full-text indexes created on a particular table.

Common auxiliary tables are retained even if full-text indexes are
dropped.  When a full-text index is dropped, the 'FTS_DOC_ID' column
that was created for the index is retained, as removing the 'FTS_DOC_ID'
column would require rebuilding the table.  Common axillary tables are
required to manage the 'FTS_DOC_ID' column.

   * 'FTS_*_DELETED' and 'FTS_*_DELETED_CACHE'

     Contain the document IDs (DOC_ID) for documents that are deleted
     but whose data is not yet removed from the full-text index.  The
     'FTS_*_DELETED_CACHE' is the in-memory version of the
     'FTS_*_DELETED' table.

   * 'FTS_*_BEING_DELETED' and 'FTS_*_BEING_DELETED_CACHE'

     Contain the document IDs (DOC_ID) for documents that are deleted
     and whose data is currently in the process of being removed from
     the full-text index.  The 'FTS_*_BEING_DELETED_CACHE' table is the
     in-memory version of the 'FTS_*_BEING_DELETED' table.

   * 'FTS_*_CONFIG'

     Stores information about the internal state of the 'FULLTEXT'
     index.  Most importantly, it stores the 'FTS_SYNCED_DOC_ID', which
     identifies documents that have been parsed and flushed to disk.  In
     case of crash recovery, 'FTS_SYNCED_DOC_ID' values are used to
     identify documents that have not been flushed to disk so that the
     documents can be re-parsed and added back to the 'FULLTEXT' index
     cache.  To view the data in this table, query the
     'INFORMATION_SCHEMA.INNODB_FT_CONFIG'.
     table.

*InnoDB Full-Text Index Cache*

When a document is inserted, it is tokenized, and the individual words
and associated data are inserted into the 'FULLTEXT' index.  This
process, even for small documents, could result in numerous small
insertions into the auxiliary index tables, making concurrent access to
these tables a point of contention.  To avoid this problem, 'InnoDB'
uses a 'FULLTEXT' index cache to temporarily cache index table
insertions for recently inserted rows.  This in-memory cache structure
holds insertions until the cache is full and then batch flushes them to
disk (to the auxiliary index tables).  You can query the
'INFORMATION_SCHEMA.INNODB_FT_INDEX_CACHE'.
table to view tokenized data for recently inserted rows.

The caching and batch flushing behavior avoids frequent updates to
auxiliary index tables, which could result in concurrent access issues
during busy insert and update times.  The batching technique also avoids
multiple insertions for the same word, and minimizes duplicate entries.
Instead of flushing each word individually, insertions for the same word
are merged and flushed to disk as a single entry, improving insertion
efficiency while keeping auxiliary index tables as small as possible.

The 'innodb_ft_cache_size' variable is used to configure the full-text
index cache size (on a per-table basis), which affects how often the
full-text index cache is flushed.  You can also define a global
full-text index cache size limit for all tables in a given instance
using the 'innodb_ft_total_cache_size' option.

The full-text index cache stores the same information as auxiliary index
tables.  However, the full-text index cache only caches tokenized data
for recently inserted rows.  The data that is already flushed to disk
(to the full-text auxiliary tables) is not brought back into the
full-text index cache when queried.  The data in auxiliary index tables
is queried directly, and results from the auxiliary index tables are
merged with results from the full-text index cache before being
returned.

*InnoDB Full-Text Index Document ID and FTS_DOC_ID Column*

'InnoDB' uses a unique document identifier referred to as a Document ID
('DOC_ID') to map words in the full-text index to document records where
the word appears.  The mapping requires an 'FTS_DOC_ID' column on the
indexed table.  If an 'FTS_DOC_ID' column is not defined, 'InnoDB'
automatically adds a hidden 'FTS_DOC_ID' column when the full-text index
is created.  The following example demonstrates this behavior.

The following table definition does not include an 'FTS_DOC_ID' column:

     mysql> CREATE TABLE opening_lines (
            id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
            opening_line TEXT(500),
            author VARCHAR(200),
            title VARCHAR(200)
            ) ENGINE=InnoDB;

When you create a full-text index on the table using 'CREATE FULLTEXT
INDEX' syntax, a warning is returned which reports that 'InnoDB' is
rebuilding the table to add the 'FTS_DOC_ID' column.

     mysql> CREATE FULLTEXT INDEX idx ON opening_lines(opening_line);
     Query OK, 0 rows affected, 1 warning (0.19 sec)
     Records: 0  Duplicates: 0  Warnings: 1

     mysql> SHOW WARNINGS;
     +---------+------+--------------------------------------------------+
     | Level   | Code | Message                                          |
     +---------+------+--------------------------------------------------+
     | Warning |  124 | InnoDB rebuilding table to add column FTS_DOC_ID |
     +---------+------+--------------------------------------------------+

The same warning is returned when using 'ALTER TABLE'
to add a full-text index to a table that does not have an
'FTS_DOC_ID' column.  If you create a full-text index at 'CREATE TABLE'
time and do not specify an 'FTS_DOC_ID' column,
'InnoDB' adds a hidden 'FTS_DOC_ID' column, without warning.

Defining an 'FTS_DOC_ID' column at 'CREATE TABLE'.
time is less expensive than creating a full-text index on a table that
is already loaded with data.  If an 'FTS_DOC_ID' column is defined on a
table prior to loading data, the table and its indexes do not have to be
rebuilt to add the new column.  If you are not concerned with 'CREATE
FULLTEXT INDEX' performance, leave out the 'FTS_DOC_ID' column to have
'InnoDB' create it for you.  'InnoDB' creates a hidden 'FTS_DOC_ID'
column along with a unique index ('FTS_DOC_ID_INDEX') on the
'FTS_DOC_ID' column.  If you want to create your own 'FTS_DOC_ID'
column, the column must be defined as 'BIGINT UNSIGNED NOT NULL' and
named 'FTS_DOC_ID' (all upper case), as in the following example:

*Note*:

The 'FTS_DOC_ID' column does not need to be defined as an
'AUTO_INCREMENT' column, but 'AUTO_INCREMENT' could make loading data
easier.

     mysql> CREATE TABLE opening_lines (
            FTS_DOC_ID BIGINT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
            opening_line TEXT(500),
            author VARCHAR(200),
            title VARCHAR(200)
            ) ENGINE=InnoDB;

If you choose to define the 'FTS_DOC_ID' column yourself, you are
responsible for managing the column to avoid empty or duplicate values.
'FTS_DOC_ID' values cannot be reused, which means 'FTS_DOC_ID' values
must be ever increasing.

Optionally, you can create the required unique 'FTS_DOC_ID_INDEX' (all
upper case) on the 'FTS_DOC_ID' column.

     mysql> CREATE UNIQUE INDEX FTS_DOC_ID_INDEX on opening_lines(FTS_DOC_ID);

If you do not create the 'FTS_DOC_ID_INDEX', 'InnoDB' creates it
automatically.

Before MySQL 5.7.13, the permitted gap between the largest used
'FTS_DOC_ID' value and new 'FTS_DOC_ID' value is 10000.  In MySQL 5.7.13
and later, the permitted gap is 65535.

To avoid rebuilding the table, the 'FTS_DOC_ID' column is retained when
dropping a full-text index.

*InnoDB Full-Text Index Deletion Handling*

Deleting a record that has a full-text index column could result in
numerous small deletions in the auxiliary index tables, making
concurrent access to these tables a point of contention.  To avoid this
problem, the Document ID ('DOC_ID') of a deleted document is logged in a
special 'FTS_*_DELETED' table whenever a record is deleted from an
indexed table, and the indexed record remains in the full-text index.
Before returning query results, information in the 'FTS_*_DELETED' table
is used to filter out deleted Document IDs.  The benefit of this design
is that deletions are fast and inexpensive.  The drawback is that the
size of the index is not immediately reduced after deleting records.  To
remove full-text index entries for deleted records, run 'OPTIMIZE TABLE'
on the indexed table with 'innodb_optimize_fulltext_only=ON' to rebuild
the full-text index.  For more information, see
fulltext-optimize.

*InnoDB Full-Text Index Transaction Handling*

'InnoDB' 'FULLTEXT' indexes have special transaction handling
characteristics due its caching and batch processing behavior.
Specifically, updates and insertions on a 'FULLTEXT' index are processed
at transaction commit time, which means that a 'FULLTEXT' search can
only see committed data.  The following example demonstrates this
behavior.  The 'FULLTEXT' search only returns a result after the
inserted lines are committed.

     mysql> CREATE TABLE opening_lines (
            id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
            opening_line TEXT(500),
            author VARCHAR(200),
            title VARCHAR(200),
            FULLTEXT idx (opening_line)
            ) ENGINE=InnoDB;

     mysql> BEGIN;

     mysql> INSERT INTO opening_lines(opening_line,author,title) VALUES
            ('Call me Ishmael.','Herman Melville','Moby-Dick'),
            ('A screaming comes across the sky.','Thomas Pynchon','Gravity\'s Rainbow'),
            ('I am an invisible man.','Ralph Ellison','Invisible Man'),
            ('Where now? Who now? When now?','Samuel Beckett','The Unnamable'),
            ('It was love at first sight.','Joseph Heller','Catch-22'),
            ('All this happened, more or less.','Kurt Vonnegut','Slaughterhouse-Five'),
            ('Mrs. Dalloway said she would buy the flowers herself.','Virginia Woolf','Mrs. Dalloway'),
            ('It was a pleasure to burn.','Ray Bradbury','Fahrenheit 451');

     mysql> SELECT COUNT(*) FROM opening_lines WHERE MATCH(opening_line) AGAINST('Ishmael');
     +----------+
     | COUNT(*) |
     +----------+
     |        0 |
     +----------+

     mysql> COMMIT;

     mysql> SELECT COUNT(*) FROM opening_lines WHERE MATCH(opening_line) AGAINST('Ishmael');
     +----------+
     | COUNT(*) |
     +----------+
     |        1 |
     +----------+

*Monitoring InnoDB Full-Text Indexes*

You can monitor and examine the special text-processing aspects of
'InnoDB' 'FULLTEXT' indexes by querying the following
'INFORMATION_SCHEMA' tables:

   * 'INNODB_FT_CONFIG'.

   * 'INNODB_FT_INDEX_TABLE'.

   * 'INNODB_FT_INDEX_CACHE'.

   * 'INNODB_FT_DEFAULT_STOPWORD'.

   * 'INNODB_FT_DELETED'.

   * 'INNODB_FT_BEING_DELETED'.

You can also view basic information for 'FULLTEXT' indexes and tables by
querying 'INNODB_SYS_INDEXES' and
'INNODB_SYS_TABLES'.

For more information, see
innodb-information-schema-fulltext_index-tables.

14.9 InnoDB Table and Page Compression
======================================

This section provides information about the 'InnoDB' table compression
and 'InnoDB' page compression features.  The page compression feature is
referred to as transparent page compression.

Using the compression features of 'InnoDB', you can create tables where
the data is stored in compressed form.  Compression can help to improve
both raw performance and scalability.  The compression means less data
is transferred between disk and memory, and takes up less space on disk
and in memory.  The benefits are amplified for tables with secondary
indexes, because index data is compressed also.  Compression can be
especially important for SSD storage devices, because they tend to have
lower capacity than HDD devices.

14.9.1 InnoDB Table Compression
-------------------------------

This section describes 'InnoDB' table compression, which is supported
with 'InnoDB' tables that reside in file_per_table tablespaces or
general tablespaces.  Table compression is enabled using the
'ROW_FORMAT=COMPRESSED' attribute with 'CREATE TABLE'
or 'ALTER TABLE'.

14.9.1.1 Overview of Table Compression
......................................

Because processors and cache memories have increased in speed more than
disk storage devices, many workloads are disk-bound.  Data compression
enables smaller database size, reduced I/O, and improved throughput, at
the small cost of increased CPU utilization.  Compression is especially
valuable for read-intensive applications, on systems with enough RAM to
keep frequently used data in memory.

An 'InnoDB' table created with 'ROW_FORMAT=COMPRESSED' can use a smaller
page size on disk than the configured 'innodb_page_size' value.  Smaller
pages require less I/O to read from and write to disk, which is
especially valuable for SSD devices.

The compressed page size is specified through the 'CREATE TABLE'
or 'ALTER TABLE'. 'KEY_BLOCK_SIZE'
parameter.  The different page size requires that the table be placed in
a file-per-table tablespace or general tablespace rather than in the
system tablespace, as the system tablespace cannot store compressed
tables.  For more information, see innodb-multiple-tablespaces,
and general-tablespaces.

The level of compression is the same regardless of the 'KEY_BLOCK_SIZE'
value.  As you specify smaller values for 'KEY_BLOCK_SIZE', you get the
I/O benefits of increasingly smaller pages.  But if you specify a value
that is too small, there is additional overhead to reorganize the pages
when data values cannot be compressed enough to fit multiple rows in
each page.  There is a hard limit on how small 'KEY_BLOCK_SIZE' can be
for a table, based on the lengths of the key columns for each of its
indexes.  Specify a value that is too small, and the 'CREATE TABLE'
or 'ALTER TABLE' statement
fails.

In the buffer pool, the compressed data is held in small pages, with a
page size based on the 'KEY_BLOCK_SIZE' value.  For extracting or
updating the column values, MySQL also creates an uncompressed page in
the buffer pool with the uncompressed data.  Within the buffer pool, any
updates to the uncompressed page are also re-written back to the
equivalent compressed page.  You might need to size your buffer pool to
accommodate the additional data of both compressed and uncompressed
pages, although the uncompressed pages are evicted from the buffer pool
when space is needed, and then uncompressed again on the next access.

14.9.1.2 Creating Compressed Tables
...................................

Compressed tables can be created in file-per-table tablespaces or in
general tablespaces.  Table compression is not available for the InnoDB
system tablespace.  The system tablespace (space 0, the .ibdata files)
can contain user-created tables, but it also contains internal system
data, which is never compressed.  Thus, compression applies only to
tables (and indexes) stored in file-per-table or general tablespaces.

*Creating a Compressed Table in File-Per-Table Tablespace*

To create a compressed table in a file-per-table tablespace,
'innodb_file_per_table' must be enabled (the default in MySQL 5.6.6) and
'innodb_file_format' must be set to 'Barracuda'.  You can set these
parameters in the MySQL configuration file ('my.cnf' or 'my.ini') or
dynamically, using a 'SET' statement.

After the 'innodb_file_per_table' and 'innodb_file_format' options are
configured, specify the 'ROW_FORMAT=COMPRESSED' clause or
'KEY_BLOCK_SIZE' clause, or both, in a 'CREATE TABLE'
or 'ALTER TABLE' statement to create a
compressed table in a file-per-table tablespace.

For example, you might use the following statements:

     SET GLOBAL innodb_file_per_table=1;
     SET GLOBAL innodb_file_format=Barracuda;
     CREATE TABLE t1
      (c1 INT PRIMARY KEY)
      ROW_FORMAT=COMPRESSED
      KEY_BLOCK_SIZE=8;

*Creating a Compressed Table in a General Tablespace*

To create a compressed table in a general tablespace, 'FILE_BLOCK_SIZE'
must be defined for the general tablespace, which is specified when the
tablespace is created.  The 'FILE_BLOCK_SIZE' value must be a valid
compressed page size in relation to the 'innodb_page_size' value, and
the page size of the compressed table, defined by the 'CREATE TABLE'
or 'ALTER TABLE'.
'KEY_BLOCK_SIZE' clause, must be equal to 'FILE_BLOCK_SIZE/1024'.  For
example, if 'innodb_page_size=16384' and 'FILE_BLOCK_SIZE=8192', the
'KEY_BLOCK_SIZE' of the table must be 8.  For more information, see
general-tablespaces.

The following example demonstrates creating a general tablespace and
adding a compressed table.  The example assumes a default
'innodb_page_size' of 16K. The 'FILE_BLOCK_SIZE' of 8192 requires that
the compressed table have a 'KEY_BLOCK_SIZE' of 8.

     mysql> CREATE TABLESPACE `ts2` ADD DATAFILE 'ts2.ibd' FILE_BLOCK_SIZE = 8192 Engine=InnoDB;

     mysql> CREATE TABLE t4 (c1 INT PRIMARY KEY) TABLESPACE ts2 ROW_FORMAT=COMPRESSED KEY_BLOCK_SIZE=8;

*Notes*

   * If you specify 'ROW_FORMAT=COMPRESSED', you can omit
     'KEY_BLOCK_SIZE'; the 'KEY_BLOCK_SIZE' setting defaults to half the
     'innodb_page_size' value.

   * If you specify a valid 'KEY_BLOCK_SIZE' value, you can omit
     'ROW_FORMAT=COMPRESSED'; compression is enabled automatically.

   * To determine the best value for 'KEY_BLOCK_SIZE,' typically you
     create several copies of the same table with different values for
     this clause, then measure the size of the resulting '.ibd' files
     and see how well each performs with a realistic workload.  For
     general tablespaces, keep in mind that dropping a table does not
     reduce the size of the general tablespace '.ibd' file, nor does it
     return disk space to the operating system.  For more information,
     see general-tablespaces.

   * The 'KEY_BLOCK_SIZE' value is treated as a hint; a different size
     could be used by 'InnoDB' if necessary.  For file-per-table
     tablespaces, the 'KEY_BLOCK_SIZE' can only be less than or equal to
     the 'innodb_page_size' value.  If you specify a value greater than
     the 'innodb_page_size' value, the specified value is ignored, a
     warning is issued, and 'KEY_BLOCK_SIZE' is set to half of the
     'innodb_page_size' value.  If 'innodb_strict_mode=ON', specifying
     an invalid 'KEY_BLOCK_SIZE' value returns an error.  For general
     tablespaces, valid 'KEY_BLOCK_SIZE' values depend on the
     'FILE_BLOCK_SIZE' setting of the tablespace.  For more information,
     see general-tablespaces.

   * 32k and 64k page sizes do not support compression.  For more
     information, refer to the 'innodb_page_size' documentation.

   * The default uncompressed size of 'InnoDB' data pages is 16KB.
     Depending on the combination of option values, MySQL uses a page
     size of 1KB, 2KB, 4KB, 8KB, or 16KB for the tablespace data file
     ('.ibd' file).  The actual compression algorithm is not affected by
     the 'KEY_BLOCK_SIZE' value; the value determines how large each
     compressed chunk is, which in turn affects how many rows can be
     packed into each compressed page.

   * When creating a compressed table in a file-per-table tablespace,
     setting 'KEY_BLOCK_SIZE' equal to the 'InnoDB' page size does not
     typically result in much compression.  For example, setting
     'KEY_BLOCK_SIZE=16' typically would not result in much compression,
     since the normal 'InnoDB' page size is 16KB. This setting may still
     be useful for tables with many long 'BLOB',
     'VARCHAR' or 'TEXT' columns, because such
     values often do compress well, and might therefore require fewer
     overflow pages as described in
     innodb-compression-internals.  For general tablespaces, a
     'KEY_BLOCK_SIZE' value equal to the 'InnoDB' page size is not
     permitted.  For more information, see general-tablespaces.

   * All indexes of a table (including the clustered index) are
     compressed using the same page size, as specified in the 'CREATE
     TABLE' or 'ALTER TABLE' statement.  Table attributes such as
     'ROW_FORMAT' and 'KEY_BLOCK_SIZE' are not part of the 'CREATE
     INDEX' syntax for 'InnoDB' tables, and are ignored if they are
     specified (although, if specified, they will appear in the output
     of the 'SHOW CREATE TABLE' statement).

   * For performance-related configuration options, see
     innodb-compression-tuning.

*Restrictions on Compressed Tables*

   * MySQL versions prior to 5.1 cannot process compressed tables.

   * Compressed tables cannot be stored in the 'InnoDB' system
     tablespace.

   * General tablespaces can contain multiple tables, but compressed and
     uncompressed tables cannot coexist within the same general
     tablespace.

   * Compression applies to an entire table and all its associated
     indexes, not to individual rows, despite the clause name
     'ROW_FORMAT'.

14.9.1.3 Tuning Compression for InnoDB Tables
.............................................

Most often, the internal optimizations described in
innodb-compression-internals-storage ensure that the system runs well
with compressed data.  However, because the efficiency of compression
depends on the nature of your data, you can make decisions that affect
the performance of compressed tables:

   * Which tables to compress.

   * What compressed page size to use.

   * Whether to adjust the size of the buffer pool based on run-time
     performance characteristics, such as the amount of time the system
     spends compressing and uncompressing data.  Whether the workload is
     more like a data warehouse (primarily queries) or an OLTP system
     (mix of queries and DML).

   * If the system performs DML operations on compressed tables, and the
     way the data is distributed leads to expensive compression failures
     at runtime, you might adjust additional advanced configuration
     options.

Use the guidelines in this section to help make those architectural and
configuration choices.  When you are ready to conduct long-term testing
and put compressed tables into production, see
innodb-compression-tuning-monitoring for ways to verify the
effectiveness of those choices under real-world conditions.

*When to Use Compression*

In general, compression works best on tables that include a reasonable
number of character string columns and where the data is read far more
often than it is written.  Because there are no guaranteed ways to
predict whether or not compression benefits a particular situation,
always test with a specific workload and data set running on a
representative configuration.  Consider the following factors when
deciding which tables to compress.

*Data Characteristics and Compression*

A key determinant of the efficiency of compression in reducing the size
of data files is the nature of the data itself.  Recall that compression
works by identifying repeated strings of bytes in a block of data.
Completely randomized data is the worst case.  Typical data often has
repeated values, and so compresses effectively.  Character strings often
compress well, whether defined in 'CHAR', 'VARCHAR', 'TEXT' or 'BLOB'
columns.  On the other hand, tables containing mostly binary data
(integers or floating point numbers) or data that is previously
compressed (for example JPEG or PNG images) may not generally compress
well, significantly or at all.

You choose whether to turn on compression for each InnoDB table.  A
table and all of its indexes use the same (compressed) page size.  It
might be that the primary key (clustered) index, which contains the data
for all columns of a table, compresses more effectively than the
secondary indexes.  For those cases where there are long rows, the use
of compression might result in long column values being stored
'off-page', as discussed in innodb-row-format-dynamic.  Those
overflow pages may compress well.  Given these considerations, for many
applications, some tables compress more effectively than others, and you
might find that your workload performs best only with a subset of tables
compressed.

To determine whether or not to compress a particular table, conduct
experiments.  You can get a rough estimate of how efficiently your data
can be compressed by using a utility that implements LZ77 compression
(such as 'gzip' or WinZip) on a copy of the .ibd file for an
uncompressed table.  You can expect less compression from a MySQL
compressed table than from file-based compression tools, because MySQL
compresses data in chunks based on the page size, 16KB by default.  In
addition to user data, the page format includes some internal system
data that is not compressed.  File-based compression utilities can
examine much larger chunks of data, and so might find more repeated
strings in a huge file than MySQL can find in an individual page.

Another way to test compression on a specific table is to copy some data
from your uncompressed table to a similar, compressed table (having all
the same indexes) in a file-per-table tablespace and look at the size of
the resulting '.ibd' file.  For example:

     USE test;
     SET GLOBAL innodb_file_per_table=1;
     SET GLOBAL innodb_file_format=Barracuda;
     SET GLOBAL autocommit=0;

     -- Create an uncompressed table with a million or two rows.
     CREATE TABLE big_table AS SELECT * FROM information_schema.columns;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     INSERT INTO big_table SELECT * FROM big_table;
     COMMIT;
     ALTER TABLE big_table ADD id int unsigned NOT NULL PRIMARY KEY auto_increment;

     SHOW CREATE TABLE big_table\G

     select count(id) from big_table;

     -- Check how much space is needed for the uncompressed table.
     \! ls -l data/test/big_table.ibd

     CREATE TABLE key_block_size_4 LIKE big_table;
     ALTER TABLE key_block_size_4 key_block_size=4 row_format=compressed;

     INSERT INTO key_block_size_4 SELECT * FROM big_table;
     commit;

     -- Check how much space is needed for a compressed table
     -- with particular compression settings.
     \! ls -l data/test/key_block_size_4.ibd

This experiment produced the following numbers, which of course could
vary considerably depending on your table structure and data:

     -rw-rw----  1 cirrus  staff  310378496 Jan  9 13:44 data/test/big_table.ibd
     -rw-rw----  1 cirrus  staff  83886080 Jan  9 15:10 data/test/key_block_size_4.ibd

To see whether compression is efficient for your particular workload:

   * For simple tests, use a MySQL instance with no other compressed
     tables and run queries against the
     'INFORMATION_SCHEMA.INNODB_CMP' table.

   * For more elaborate tests involving workloads with multiple
     compressed tables, run queries against the
     'INFORMATION_SCHEMA.INNODB_CMP_PER_INDEX'
     table.  Because the statistics in the
     'INNODB_CMP_PER_INDEX' table are expensive to collect, you must
     enable the configuration option 'innodb_cmp_per_index_enabled'
     before querying that table, and you might restrict such testing to
     a development server or a non-critical slave server.

   * Run some typical SQL statements against the compressed table you
     are testing.

   * Examine the ratio of successful compression operations to overall
     compression operations by querying the
     'INFORMATION_SCHEMA.INNODB_CMP' or
     'INFORMATION_SCHEMA.INNODB_CMP_PER_INDEX'
     table, and comparing 'COMPRESS_OPS' to
     'COMPRESS_OPS_OK'.

   * If a high percentage of compression operations complete
     successfully, the table might be a good candidate for compression.

   * If you get a high proportion of compression failures, you can
     adjust 'innodb_compression_level',
     'innodb_compression_failure_threshold_pct', and
     'innodb_compression_pad_pct_max' options as described in
     innodb-performance-compression-oltp, and try further tests.

*Database Compression versus Application Compression*

Decide whether to compress data in your application or in the table; do
not use both types of compression for the same data.  When you compress
the data in the application and store the results in a compressed table,
extra space savings are extremely unlikely, and the double compression
just wastes CPU cycles.

*Compressing in the Database*

When enabled, MySQL table compression is automatic and applies to all
columns and index values.  The columns can still be tested with
operators such as 'LIKE', and sort operations can still use indexes even
when the index values are compressed.  Because indexes are often a
significant fraction of the total size of a database, compression could
result in significant savings in storage, I/O or processor time.  The
compression and decompression operations happen on the database server,
which likely is a powerful system that is sized to handle the expected
load.

*Compressing in the Application*

If you compress data such as text in your application, before it is
inserted into the database, You might save overhead for data that does
not compress well by compressing some columns and not others.  This
approach uses CPU cycles for compression and uncompression on the client
machine rather than the database server, which might be appropriate for
a distributed application with many clients, or where the client machine
has spare CPU cycles.

*Hybrid Approach*

Of course, it is possible to combine these approaches.  For some
applications, it may be appropriate to use some compressed tables and
some uncompressed tables.  It may be best to externally compress some
data (and store it in uncompressed tables) and allow MySQL to compress
(some of) the other tables in the application.  As always, up-front
design and real-life testing are valuable in reaching the right
decision.

*Workload Characteristics and Compression*

In addition to choosing which tables to compress (and the page size),
the workload is another key determinant of performance.  If the
application is dominated by reads, rather than updates, fewer pages need
to be reorganized and recompressed after the index page runs out of room
for the per-page 'modification log' that MySQL maintains for compressed
data.  If the updates predominantly change non-indexed columns or those
containing 'BLOB's or large strings that happen to be stored 'off-page',
the overhead of compression may be acceptable.  If the only changes to a
table are 'INSERT's that use a monotonically increasing primary key, and
there are few secondary indexes, there is little need to reorganize and
recompress index pages.  Since MySQL can 'delete-mark' and delete rows
on compressed pages 'in place' by modifying uncompressed data, 'DELETE'
operations on a table are relatively efficient.

For some environments, the time it takes to load data can be as
important as run-time retrieval.  Especially in data warehouse
environments, many tables may be read-only or read-mostly.  In those
cases, it might or might not be acceptable to pay the price of
compression in terms of increased load time, unless the resulting
savings in fewer disk reads or in storage cost is significant.

Fundamentally, compression works best when the CPU time is available for
compressing and uncompressing data.  Thus, if your workload is I/O
bound, rather than CPU-bound, you might find that compression can
improve overall performance.  When you test your application performance
with different compression configurations, test on a platform similar to
the planned configuration of the production system.

*Configuration Characteristics and Compression*

Reading and writing database pages from and to disk is the slowest
aspect of system performance.  Compression attempts to reduce I/O by
using CPU time to compress and uncompress data, and is most effective
when I/O is a relatively scarce resource compared to processor cycles.

This is often especially the case when running in a multi-user
environment with fast, multi-core CPUs.  When a page of a compressed
table is in memory, MySQL often uses additional memory, typically 16KB,
in the buffer pool for an uncompressed copy of the page.  The adaptive
LRU algorithm attempts to balance the use of memory between compressed
and uncompressed pages to take into account whether the workload is
running in an I/O-bound or CPU-bound manner.  Still, a configuration
with more memory dedicated to the buffer pool tends to run better when
using compressed tables than a configuration where memory is highly
constrained.

*Choosing the Compressed Page Size*

The optimal setting of the compressed page size depends on the type and
distribution of data that the table and its indexes contain.  The
compressed page size should always be bigger than the maximum record
size, or operations may fail as noted in
innodb-compression-internals-storage-btree.

Setting the compressed page size too large wastes some space, but the
pages do not have to be compressed as often.  If the compressed page
size is set too small, inserts or updates may require time-consuming
recompression, and the B-tree nodes may have to be split more
frequently, leading to bigger data files and less efficient indexing.

Typically, you set the compressed page size to 8K or 4K bytes.  Given
that the maximum row size for an InnoDB table is around 8K,
'KEY_BLOCK_SIZE=8' is usually a safe choice.

14.9.1.4 Monitoring InnoDB Table Compression at Runtime
.......................................................

Overall application performance, CPU and I/O utilization and the size of
disk files are good indicators of how effective compression is for your
application.  This section builds on the performance tuning advice from
innodb-compression-tuning, and shows how to find problems that
might not turn up during initial testing.

To dig deeper into performance considerations for compressed tables, you
can monitor compression performance at runtime using the Information
Schema tables described in
innodb-information-schema-examples-compression.  These tables reflect
the internal use of memory and the rates of compression used overall.

The 'INNODB_CMP' table reports information
about compression activity for each compressed page size
('KEY_BLOCK_SIZE') in use.  The information in these tables is
system-wide: it summarizes the compression statistics across all
compressed tables in your database.  You can use this data to help
decide whether or not to compress a table by examining these tables when
no other compressed tables are being accessed.  It involves relatively
low overhead on the server, so you might query it periodically on a
production server to check the overall efficiency of the compression
feature.

The 'INNODB_CMP_PER_INDEX' table
reports information about compression activity for individual tables and
indexes.  This information is more targeted and more useful for
evaluating compression efficiency and diagnosing performance issues one
table or index at a time.  (Because that each 'InnoDB' table is
represented as a clustered index, MySQL does not make a big distinction
between tables and indexes in this context.)  The
'INNODB_CMP_PER_INDEX' table does involve
substantial overhead, so it is more suitable for development servers,
where you can compare the effects of different workloads, data, and
compression settings in isolation.  To guard against imposing this
monitoring overhead by accident, you must enable the
'innodb_cmp_per_index_enabled' configuration option before you can query
the 'INNODB_CMP_PER_INDEX' table.

The key statistics to consider are the number of, and amount of time
spent performing, compression and uncompression operations.  Since MySQL
splits B-tree nodes when they are too full to contain the compressed
data following a modification, compare the number of 'successful'
compression operations with the number of such operations overall.
Based on the information in the 'INNODB_CMP'.
and 'INNODB_CMP_PER_INDEX' tables and
overall application performance and hardware resource utilization, you
might make changes in your hardware configuration, adjust the size of
the buffer pool, choose a different page size, or select a different set
of tables to compress.

If the amount of CPU time required for compressing and uncompressing is
high, changing to faster or multi-core CPUs can help improve performance
with the same data, application workload and set of compressed tables.
Increasing the size of the buffer pool might also help performance, so
that more uncompressed pages can stay in memory, reducing the need to
uncompress pages that exist in memory only in compressed form.

A large number of compression operations overall (compared to the number
of 'INSERT', 'UPDATE' and 'DELETE' operations in your application and
the size of the database) could indicate that some of your compressed
tables are being updated too heavily for effective compression.  If so,
choose a larger page size, or be more selective about which tables you
compress.

If the number of 'successful' compression operations ('COMPRESS_OPS_OK')
is a high percentage of the total number of compression operations
('COMPRESS_OPS'), then the system is likely performing well.  If the
ratio is low, then MySQL is reorganizing, recompressing, and splitting
B-tree nodes more often than is desirable.  In this case, avoid
compressing some tables, or increase 'KEY_BLOCK_SIZE' for some of the
compressed tables.  You might turn off compression for tables that cause
the number of 'compression failures' in your application to be more than
1% or 2% of the total.  (Such a failure ratio might be acceptable during
a temporary operation such as a data load).

14.9.1.5 How Compression Works for InnoDB Tables
................................................

This section describes some internal implementation details about
compression for InnoDB tables.  The information presented here may be
helpful in tuning for performance, but is not necessary to know for
basic use of compression.

*Compression Algorithms*

Some operating systems implement compression at the file system level.
Files are typically divided into fixed-size blocks that are compressed
into variable-size blocks, which easily leads into fragmentation.  Every
time something inside a block is modified, the whole block is
recompressed before it is written to disk.  These properties make this
compression technique unsuitable for use in an update-intensive database
system.

MySQL implements compression with the help of the well-known zlib
library (http://www.zlib.net/), which implements the LZ77 compression
algorithm.  This compression algorithm is mature, robust, and efficient
in both CPU utilization and in reduction of data size.  The algorithm is
'lossless', so that the original uncompressed data can always be
reconstructed from the compressed form.  LZ77 compression works by
finding sequences of data that are repeated within the data to be
compressed.  The patterns of values in your data determine how well it
compresses, but typical user data often compresses by 50% or more.

*Note*:

InnoDB supports the 'zlib' library only up to version 1.2.3.

Unlike compression performed by an application, or compression features
of some other database management systems, InnoDB compression applies
both to user data and to indexes.  In many cases, indexes can constitute
40-50% or more of the total database size, so this difference is
significant.  When compression is working well for a data set, the size
of the InnoDB data files (the file-per-table tablespace or general
tablespace '.idb' files) is 25% to 50% of the uncompressed size or
possibly smaller.  Depending on the workload, this smaller database can
in turn lead to a reduction in I/O, and an increase in throughput, at a
modest cost in terms of increased CPU utilization.  You can adjust the
balance between compression level and CPU overhead by modifying the
'innodb_compression_level' configuration option.

*InnoDB Data Storage and Compression*

All user data in InnoDB tables is stored in pages comprising a B-tree
index (the clustered index).  In some other database systems, this type
of index is called an 'index-organized table'.  Each row in the index
node contains the values of the (user-specified or system-generated)
primary key and all the other columns of the table.

Secondary indexes in InnoDB tables are also B-trees, containing pairs of
values: the index key and a pointer to a row in the clustered index.
The pointer is in fact the value of the primary key of the table, which
is used to access the clustered index if columns other than the index
key and primary key are required.  Secondary index records must always
fit on a single B-tree page.

The compression of B-tree nodes (of both clustered and secondary
indexes) is handled differently from compression of overflow pages used
to store long 'VARCHAR', 'BLOB', or 'TEXT' columns, as explained in the
following sections.

*Compression of B-Tree Pages*

Because they are frequently updated, B-tree pages require special
treatment.  It is important to minimize the number of times B-tree nodes
are split, as well as to minimize the need to uncompress and recompress
their content.

One technique MySQL uses is to maintain some system information in the
B-tree node in uncompressed form, thus facilitating certain in-place
updates.  For example, this allows rows to be delete-marked and deleted
without any compression operation.

In addition, MySQL attempts to avoid unnecessary uncompression and
recompression of index pages when they are changed.  Within each B-tree
page, the system keeps an uncompressed 'modification log' to record
changes made to the page.  Updates and inserts of small records may be
written to this modification log without requiring the entire page to be
completely reconstructed.

When the space for the modification log runs out, InnoDB uncompresses
the page, applies the changes and recompresses the page.  If
recompression fails (a situation known as a compression failure), the
B-tree nodes are split and the process is repeated until the update or
insert succeeds.

To avoid frequent compression failures in write-intensive workloads,
such as for OLTP applications, MySQL sometimes reserves some empty space
(padding) in the page, so that the modification log fills up sooner and
the page is recompressed while there is still enough room to avoid
splitting it.  The amount of padding space left in each page varies as
the system keeps track of the frequency of page splits.  On a busy
server doing frequent writes to compressed tables, you can adjust the
'innodb_compression_failure_threshold_pct', and
'innodb_compression_pad_pct_max' configuration options to fine-tune this
mechanism.

Generally, MySQL requires that each B-tree page in an InnoDB table can
accommodate at least two records.  For compressed tables, this
requirement has been relaxed.  Leaf pages of B-tree nodes (whether of
the primary key or secondary indexes) only need to accommodate one
record, but that record must fit, in uncompressed form, in the per-page
modification log.  If 'innodb_strict_mode' is 'ON', MySQL checks the
maximum row size during 'CREATE TABLE' or
'CREATE INDEX'.  If the row does not fit, the following
error message is issued: 'ERROR HY000: Too big row'.

If you create a table when 'innodb_strict_mode' is OFF, and a subsequent
'INSERT' or 'UPDATE' statement attempts to create an index entry that
does not fit in the size of the compressed page, the operation fails
with 'ERROR 42000: Row size too large'.  (This error message does not
name the index for which the record is too large, or mention the length
of the index record or the maximum record size on that particular index
page.)  To solve this problem, rebuild the table with 'ALTER TABLE'
and select a larger compressed page size
('KEY_BLOCK_SIZE'), shorten any column prefix indexes, or disable
compression entirely with 'ROW_FORMAT=DYNAMIC' or 'ROW_FORMAT=COMPACT'.

'innodb_strict_mode' is not applicable to general tablespaces, which
also support compressed tables.  Tablespace management rules for general
tablespaces are strictly enforced independently of 'innodb_strict_mode'.
For more information, see create-tablespace.

*Compressing BLOB, VARCHAR, and TEXT Columns*

In an InnoDB table, see 'BLOB', 'VARCHAR', and
'TEXT' columns that are not part of the primary key may be stored
on separately allocated overflow pages.  We refer to these columns as
off-page columns.  Their values are stored on singly-linked lists of
overflow pages.

For tables created in 'ROW_FORMAT=DYNAMIC' or 'ROW_FORMAT=COMPRESSED',
the values of 'BLOB', 'TEXT', or
'VARCHAR' columns may be stored fully off-page, depending on
their length and the length of the entire row.  For columns that are
stored off-page, the clustered index record only contains 20-byte
pointers to the overflow pages, one per column.  Whether any columns are
stored off-page depends on the page size and the total size of the row.
When the row is too long to fit entirely within the page of the
clustered index, MySQL chooses the longest columns for off-page storage
until the row fits on the clustered index page.  As noted above, if a
row does not fit by itself on a compressed page, an error occurs.

*Note*:

For tables created in 'ROW_FORMAT=DYNAMIC' or 'ROW_FORMAT=COMPRESSED',
see 'TEXT' and 'BLOB' columns that are less than
or equal to 40 bytes are always stored in-line.

Tables created in older versions of MySQL use the Antelope file format,
which supports only 'ROW_FORMAT=REDUNDANT' and 'ROW_FORMAT=COMPACT'.  In
these formats, MySQL stores the first 768 bytes of 'BLOB',
'VARCHAR', and 'TEXT' columns in the clustered
index record along with the primary key.  The 768-byte prefix is
followed by a 20-byte pointer to the overflow pages that contain the
rest of the column value.

When a table is in 'COMPRESSED' format, all data written to overflow
pages is compressed 'as is'; that is, MySQL applies the zlib compression
algorithm to the entire data item.  Other than the data, compressed
overflow pages contain an uncompressed header and trailer comprising a
page checksum and a link to the next overflow page, among other things.
Therefore, very significant storage savings can be obtained for longer
'BLOB', 'TEXT', or 'VARCHAR' columns if the data is highly compressible,
as is often the case with text data.  Image data, such as 'JPEG', is
typically already compressed and so does not benefit much from being
stored in a compressed table; the double compression can waste CPU
cycles for little or no space savings.

The overflow pages are of the same size as other pages.  A row
containing ten columns stored off-page occupies ten overflow pages, even
if the total length of the columns is only 8K bytes.  In an uncompressed
table, ten uncompressed overflow pages occupy 160K bytes.  In a
compressed table with an 8K page size, they occupy only 80K bytes.
Thus, it is often more efficient to use compressed table format for
tables with long column values.

For file-per-table tablespaces, using a 16K compressed page size can
reduce storage and I/O costs for 'BLOB', 'VARCHAR',
or 'TEXT' columns, because such data often compress
well, and might therefore require fewer overflow pages, even though the
B-tree nodes themselves take as many pages as in the uncompressed form.
General tablespaces do not support a 16K compressed page size
('KEY_BLOCK_SIZE').  For more information, see
general-tablespaces.

*Compression and the InnoDB Buffer Pool*

In a compressed 'InnoDB' table, every compressed page (whether 1K, 2K,
4K or 8K) corresponds to an uncompressed page of 16K bytes (or a smaller
size if 'innodb_page_size' is set).  To access the data in a page, MySQL
reads the compressed page from disk if it is not already in the buffer
pool, then uncompresses the page to its original form.  This section
describes how 'InnoDB' manages the buffer pool with respect to pages of
compressed tables.

To minimize I/O and to reduce the need to uncompress a page, at times
the buffer pool contains both the compressed and uncompressed form of a
database page.  To make room for other required database pages, MySQL
can evict from the buffer pool an uncompressed page, while leaving the
compressed page in memory.  Or, if a page has not been accessed in a
while, the compressed form of the page might be written to disk, to free
space for other data.  Thus, at any given time, the buffer pool might
contain both the compressed and uncompressed forms of the page, or only
the compressed form of the page, or neither.

MySQL keeps track of which pages to keep in memory and which to evict
using a least-recently-used (LRU) list, so that hot (frequently
accessed) data tends to stay in memory.  When compressed tables are
accessed, MySQL uses an adaptive LRU algorithm to achieve an appropriate
balance of compressed and uncompressed pages in memory.  This adaptive
algorithm is sensitive to whether the system is running in an I/O-bound
or CPU-bound manner.  The goal is to avoid spending too much processing
time uncompressing pages when the CPU is busy, and to avoid doing excess
I/O when the CPU has spare cycles that can be used for uncompressing
compressed pages (that may already be in memory).  When the system is
I/O-bound, the algorithm prefers to evict the uncompressed copy of a
page rather than both copies, to make more room for other disk pages to
become memory resident.  When the system is CPU-bound, MySQL prefers to
evict both the compressed and uncompressed page, so that more memory can
be used for 'hot' pages and reducing the need to uncompress data in
memory only in compressed form.

*Compression and the InnoDB Redo Log Files*

Before a compressed page is written to a data file, MySQL writes a copy
of the page to the redo log (if it has been recompressed since the last
time it was written to the database).  This is done to ensure that redo
logs are usable for crash recovery, even in the unlikely case that the
'zlib' library is upgraded and that change introduces a compatibility
problem with the compressed data.  Therefore, some increase in the size
of log files, or a need for more frequent checkpoints, can be expected
when using compression.  The amount of increase in the log file size or
checkpoint frequency depends on the number of times compressed pages are
modified in a way that requires reorganization and recompression.

Compressed tables require the Barracuda file format.  To create a
compressed table in a file-per-table tablespace, 'innodb_file_per_table'
must be enabled and 'innodb_file_format' must be set to Barracuda.
There is no dependence on the 'innodb_file_format' setting when creating
a compressed table in a general tablespace.  For more information, see
general-tablespaces.  The MySQL Enterprise Backup product
supports the Barracuda file format.

14.9.1.6 Compression for OLTP Workloads
.......................................

Traditionally, the 'InnoDB' compression feature was recommended
primarily for read-only or read-mostly workloads, such as in a data
warehouse configuration.  The rise of SSD storage devices, which are
fast but relatively small and expensive, makes compression attractive
also for 'OLTP' workloads: high-traffic, interactive websites can reduce
their storage requirements and their I/O operations per second (IOPS) by
using compressed tables with applications that do frequent
'INSERT', 'UPDATE', and 'DELETE'.
operations.

Configuration options introduced in MySQL 5.6 let you adjust the way
compression works for a particular MySQL instance, with an emphasis on
performance and scalability for write-intensive operations:

   * 'innodb_compression_level' lets you turn the degree of compression
     up or down.  A higher value lets you fit more data onto a storage
     device, at the expense of more CPU overhead during compression.  A
     lower value lets you reduce CPU overhead when storage space is not
     critical, or you expect the data is not especially compressible.

   * 'innodb_compression_failure_threshold_pct' specifies a cutoff point
     for compression failures during updates to a compressed table.
     When this threshold is passed, MySQL begins to leave additional
     free space within each new compressed page, dynamically adjusting
     the amount of free space up to the percentage of page size
     specified by 'innodb_compression_pad_pct_max'

   * 'innodb_compression_pad_pct_max' lets you adjust the maximum amount
     of space reserved within each page to record changes to compressed
     rows, without needing to compress the entire page again.  The
     higher the value, the more changes can be recorded without
     recompressing the page.  MySQL uses a variable amount of free space
     for the pages within each compressed table, only when a designated
     percentage of compression operations 'fail' at runtime, requiring
     an expensive operation to split the compressed page.

   * 'innodb_log_compressed_pages' lets you disable writing of images of
     re-compressed pages to the redo log.  Re-compression may occur when
     changes are made to compressed data.  This option is enabled by
     default to prevent corruption that could occur if a different
     version of the 'zlib' compression algorithm is used during
     recovery.  If you are certain that the 'zlib' version will not
     change, disable 'innodb_log_compressed_pages' to reduce redo log
     generation for workloads that modify compressed data.

Because working with compressed data sometimes involves keeping both
compressed and uncompressed versions of a page in memory at the same
time, when using compression with an OLTP-style workload, be prepared to
increase the value of the 'innodb_buffer_pool_size' configuration
option.

14.9.1.7 SQL Compression Syntax Warnings and Errors
...................................................

This section describes syntax warnings and errors that you may encounter
when using the table compression feature with file-per-table tablespaces
and general tablespaces.

*SQL Compression Syntax Warnings and Errors for File-Per-Table
Tablespaces*

When 'innodb_strict_mode' is enabled (the default), specifying
'ROW_FORMAT=COMPRESSED' or 'KEY_BLOCK_SIZE' in 'CREATE TABLE'
or 'ALTER TABLE' statements produces
the following error if 'innodb_file_per_table' is disabled or if
'innodb_file_format' is set to 'Antelope' rather than 'Barracuda'.

     ERROR 1031 (HY000): Table storage engine for 't1' doesn't have this option

*Note*:

The table is not created if the current configuration does not permit
using compressed tables.

When 'innodb_strict_mode' is disabled, specifying
'ROW_FORMAT=COMPRESSED' or 'KEY_BLOCK_SIZE' in 'CREATE TABLE'
or 'ALTER TABLE' statements produces
the following warnings if 'innodb_file_per_table' is disabled.

     mysql> SHOW WARNINGS;
     +---------+------+---------------------------------------------------------------+
     | Level   | Code | Message                                                       |
     +---------+------+---------------------------------------------------------------+
     | Warning | 1478 | InnoDB: KEY_BLOCK_SIZE requires innodb_file_per_table.        |
     | Warning | 1478 | InnoDB: ignoring KEY_BLOCK_SIZE=4.                            |
     | Warning | 1478 | InnoDB: ROW_FORMAT=COMPRESSED requires innodb_file_per_table. |
     | Warning | 1478 | InnoDB: assuming ROW_FORMAT=DYNAMIC.                          |
     +---------+------+---------------------------------------------------------------+

Similar warnings are issued if 'innodb_file_format' is set to 'Antelope'
rather than 'Barracuda'.

*Note*:

These messages are only warnings, not errors, and the table is created
without compression, as if the options were not specified.

The 'non-strict' behavior lets you import a 'mysqldump' file into a
database that does not support compressed tables, even if the source
database contained compressed tables.  In that case, MySQL creates the
table in 'ROW_FORMAT=COMPACT' instead of preventing the operation.

To import the dump file into a new database, and have the tables
re-created as they exist in the original database, ensure the server has
the proper settings for the configuration parameters
'innodb_file_format' and 'innodb_file_per_table'.

The attribute 'KEY_BLOCK_SIZE' is permitted only when 'ROW_FORMAT' is
specified as 'COMPRESSED' or is omitted.  Specifying a 'KEY_BLOCK_SIZE'
with any other 'ROW_FORMAT' generates a warning that you can view with
'SHOW WARNINGS'.  However, the table is non-compressed; the specified
'KEY_BLOCK_SIZE' is ignored).

Level                                       Code                          Message

Warning                                     1478                          ' InnoDB: ignoring
                                                                          KEY_BLOCK_SIZE=N unless
                                                                          ROW_FORMAT=COMPRESSED. '

If you are running with 'innodb_strict_mode' enabled, the combination of
a 'KEY_BLOCK_SIZE' with any 'ROW_FORMAT' other than 'COMPRESSED'
generates an error, not a warning, and the table is not created.

innodb-compression-create-and-alter-options-table provides an
overview the 'ROW_FORMAT' and 'KEY_BLOCK_SIZE' options that are used
with 'CREATE TABLE' or 'ALTER TABLE'.

*ROW_FORMAT and KEY_BLOCK_SIZE Options*

Option         Usage Notes                   Description

'ROW_FORMAT=​REDUNDANT'Storage format used priorLess efficient than
               to MySQL 5.0.3                'ROW_FORMAT=COMPACT'; for
                                             backward compatibility

'ROW_FORMAT=​COMPACT'Default storage format  Stores a prefix of 768
               since MySQL 5.0.3             bytes of long column values
                                             in the clustered index
                                             page, with the remaining
                                             bytes stored in an overflow
                                             page

'ROW_FORMAT=​DYNAMIC'File-per-table tablespacesStore values within the
               require                       clustered index page if
               'innodb_file​_format=Barracuda'they fit; if not, stores
                                             only a 20-byte pointer to
                                             an overflow page (no
                                             prefix)

'ROW_FORMAT=​COMPRESSED'File-per-table tablespacesCompresses the table and
               require                       indexes using zlib
               'innodb_file​_format=Barracuda'

'KEY_BLOCK_​SIZE=N'File-per-table tablespacesSpecifies compressed page
               require                       size of 1, 2, 4, 8 or 16
               'innodb_file​_format=Barracuda'kilobytes; implies
                                             'ROW_FORMAT=COMPRESSED'.
                                             For general tablespaces, a
                                             'KEY_BLOCK_SIZE' value
                                             equal to the 'InnoDB' page
                                             size is not permitted.

innodb-compression-create-and-alter-errors-table summarizes
error conditions that occur with certain combinations of configuration
parameters and options on the 'CREATE TABLE' or
'ALTER TABLE' statements, and how the options appear
in the output of 'SHOW TABLE STATUS'.

When 'innodb_strict_mode' is 'OFF', MySQL creates or alters the table,
but ignores certain settings as shown below.  You can see the warning
messages in the MySQL error log.  When 'innodb_strict_mode' is 'ON',
these specified combinations of options generate errors, and the table
is not created or altered.  To see the full description of the error
condition, issue the 'SHOW ERRORS' statement: example:

     mysql> CREATE TABLE x (id INT PRIMARY KEY, c INT)

     -> ENGINE=INNODB KEY_BLOCK_SIZE=33333;

     ERROR 1005 (HY000): Can't create table 'test.x' (errno: 1478)

     mysql> SHOW ERRORS;
     +-------+------+-------------------------------------------+
     | Level | Code | Message                                   |
     +-------+------+-------------------------------------------+
     | Error | 1478 | InnoDB: invalid KEY_BLOCK_SIZE=33333.     |
     | Error | 1005 | Can't create table 'test.x' (errno: 1478) |
     +-------+------+-------------------------------------------+

*CREATE/ALTER TABLE Warnings and Errors when InnoDB Strict Mode is OFF*

Syntax         Warning or Error        Resulting
               Condition               'ROW_FORMAT',
                                       as shown in
                                       'SHOW TABLE
                                       STATUS'

'ROW_FORMAT=REDUNDANT'None             'REDUNDANT'

'ROW_FORMAT=COMPACT'None               'COMPACT'

'ROW_FORMAT=COMPRESSED'Ignored for     'the default
or             file-per-table          row format for
'ROW_FORMAT=DYNAMIC'tablespaces unless file-per-table
or             both                    tablespaces;
'KEY_BLOCK_SIZE''innodb_file_format''=Barracuda'the specified
is specified   and                     row format for
               'innodb_file_per_table' general
               are enabled.  General   tablespaces'
               tablespaces support
               all row formats (with
               some restrictions)
               regardless of
               'innodb_file_format'
               and
               'innodb_file_per_table'
               settings.  See
               general-tablespaces.

Invalid        'KEY_BLOCK_SIZE' is     the specified
'KEY_BLOCK_SIZE'ignored                row format, or
is specified                           the default
(not 1, 2,                             row format
4, 8 or 16)

'ROW_FORMAT=COMPRESSED'None;           'COMPRESSED'
and valid      'KEY_BLOCK_SIZE'
'KEY_BLOCK_SIZE'specified is used
are
specified

'KEY_BLOCK_SIZE''KEY_BLOCK_SIZE' is    'REDUNDANT',
is specified   ignored                 'COMPACT' or
with                                   'DYNAMIC'
'REDUNDANT',
'COMPACT' or
'DYNAMIC'
row format

'ROW_FORMAT'   Ignored if recognized   the default
is not one     by the MySQL parser.    row format or
of             Otherwise, an error     N/A
'REDUNDANT',   is issued.
'COMPACT',
'DYNAMIC' or
'COMPRESSED'

When 'innodb_strict_mode' is 'ON', MySQL rejects invalid 'ROW_FORMAT' or
'KEY_BLOCK_SIZE' parameters and issues errors.  When
'innodb_strict_mode' is 'OFF', MySQL issues warnings instead of errors
for ignored invalid parameters.  'innodb_strict_mode' is 'ON' by
default.

When 'innodb_strict_mode' is 'ON', MySQL rejects invalid 'ROW_FORMAT' or
'KEY_BLOCK_SIZE' parameters.  For compatibility with earlier versions of
MySQL, strict mode is not enabled by default; instead, MySQL issues
warnings (not errors) for ignored invalid parameters.

It is not possible to see the chosen 'KEY_BLOCK_SIZE' using 'SHOW TABLE
STATUS'.  The statement 'SHOW CREATE TABLE' displays the
'KEY_BLOCK_SIZE' (even if it was ignored when creating the table).  The
real compressed page size of the table cannot be displayed by MySQL.

*SQL Compression Syntax Warnings and Errors for General Tablespaces*

   * If 'FILE_BLOCK_SIZE' was not defined for the general tablespace
     when the tablespace was created, the tablespace cannot contain
     compressed tables.  If you attempt to add a compressed table, an
     error is returned, as shown in the following example:

          mysql> CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' Engine=InnoDB;

          mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=COMPRESSED
                 KEY_BLOCK_SIZE=8;
          ERROR 1478 (HY000): InnoDB: Tablespace `ts1` cannot contain a COMPRESSED table

   * Attempting to add a table with an invalid 'KEY_BLOCK_SIZE' to a
     general tablespace returns an error, as shown in the following
     example:

          mysql> CREATE TABLESPACE `ts2` ADD DATAFILE 'ts2.ibd' FILE_BLOCK_SIZE = 8192 Engine=InnoDB;

          mysql> CREATE TABLE t2 (c1 INT PRIMARY KEY) TABLESPACE ts2 ROW_FORMAT=COMPRESSED
                 KEY_BLOCK_SIZE=4;
          ERROR 1478 (HY000): InnoDB: Tablespace `ts2` uses block size 8192 and cannot
          contain a table with physical page size 4096

     For general tablespaces, the 'KEY_BLOCK_SIZE' of the table must be
     equal to the 'FILE_BLOCK_SIZE' of the tablespace divided by 1024.
     For example, if the 'FILE_BLOCK_SIZE' of the tablespace is 8192,
     the 'KEY_BLOCK_SIZE' of the table must be 8.

   * Attempting to add a table with an uncompressed row format to a
     general tablespace configured to store compressed tables returns an
     error, as shown in the following example:

          mysql> CREATE TABLESPACE `ts3` ADD DATAFILE 'ts3.ibd' FILE_BLOCK_SIZE = 8192 Engine=InnoDB;

          mysql> CREATE TABLE t3 (c1 INT PRIMARY KEY) TABLESPACE ts3 ROW_FORMAT=COMPACT;
          ERROR 1478 (HY000): InnoDB: Tablespace `ts3` uses block size 8192 and cannot
          contain a table with physical page size 16384

'innodb_strict_mode' is not applicable to general tablespaces.
Tablespace management rules for general tablespaces are strictly
enforced independently of 'innodb_strict_mode'.  For more information,
see create-tablespace.

For more information about using compressed tables with general
tablespaces, see general-tablespaces.

14.9.2 InnoDB Page Compression
------------------------------

'InnoDB' supports page-level compression for tables that reside in
file-per-table tablespaces.  This feature is referred to as _Transparent
Page Compression_.  Page compression is enabled by specifying the
'COMPRESSION' attribute with 'CREATE TABLE' or
'ALTER TABLE'.  Supported compression algorithms
include 'Zlib' and 'LZ4'.

*Supported Platforms*

Page compression requires sparse file and hole punching support.  Page
compression is supported on Windows with NTFS, and on the following
subset of MySQL-supported Linux platforms where the kernel level
provides hole punching support:

   * RHEL 7 and derived distributions that use kernel version 3.10.0-123
     or higher

   * OEL 5.10 (UEK2) kernel version 2.6.39 or higher

   * OEL 6.5 (UEK3) kernel version 3.8.13 or higher

   * OEL 7.0 kernel version 3.8.13 or higher

   * SLE11 kernel version 3.0-x

   * SLE12 kernel version 3.12-x

   * OES11 kernel version 3.0-x

   * Ubuntu 14.0.4 LTS kernel version 3.13 or higher

   * Ubuntu 12.0.4 LTS kernel version 3.2 or higher

   * Debian 7 kernel version 3.2 or higher

*Note*:

All of the available file systems for a given Linux distribution may not
support hole punching.

*How Page Compression Works*

When a page is written, it is compressed using the specified compression
algorithm.  The compressed data is written to disk, where the hole
punching mechanism releases empty blocks from the end of the page.  If
compression fails, data is written out as-is.

*Hole Punch Size on Linux*

On Linux systems, the file system block size is the unit size used for
hole punching.  Therefore, page compression only works if page data can
be compressed to a size that is less than or equal to the 'InnoDB' page
size minus the file system block size.  For example, if
'innodb_page_size=16K' and the file system block size is 4K, page data
must compress to less than or equal to 12K to make hole punching
possible.

*Hole Punch Size on Windows*

On Windows systems, the underlying infrastructure for sparse files is
based on NTFS compression.  Hole punching size is the NTFS compression
unit, which is 16 times the NTFS cluster size.  Cluster sizes and their
compression units are shown in the following table:

*Windows NTFS Cluster Size and Compression Units*

Cluster Size                         Compression Unit

512 Bytes                            8 KB

1 KB                                 16 KB

2 KB                                 32 KB

4 KB                                 64 KB

Page compression on Windows systems only works if page data can be
compressed to a size that is less than or equal to the 'InnoDB' page
size minus the compression unit size.

The default NTFS cluster size is 4K, for which the compression unit size
is 64K. This means that page compression has no benefit for an
out-of-the box Windows NTFS configuration, as the maximum
'innodb_page_size' is also 64K.

For page compression to work on Windows, the file system must be created
with a cluster size smaller than 4K, and the 'innodb_page_size' must be
at least twice the size of the compression unit.  For example, for page
compression to work on Windows, you could build the file system with a
cluster size of 512 Bytes (which has a compression unit of 8KB) and
initialize 'InnoDB' with an 'innodb_page_size' value of 16K or greater.

*Enabling Page Compression*

To enable page compression, specify the 'COMPRESSION' attribute in the
'CREATE TABLE' statement.  For example:

     CREATE TABLE t1 (c1 INT) COMPRESSION="zlib";

You can also enable page compression in an 'ALTER TABLE'
statement.  However, see 'ALTER TABLE ... COMPRESSION'
only updates the tablespace compression attribute.  Writes
to the tablespace that occur after setting the new compression algorithm
use the new setting, but to apply the new compression algorithm to
existing pages, you must rebuild the table using 'OPTIMIZE TABLE'.

     ALTER TABLE t1 COMPRESSION="zlib";
     OPTIMIZE TABLE t1;

*Disabling Page Compression*

To disable page compression, set 'COMPRESSION=None' using 'ALTER TABLE'.
Writes to the tablespace that occur after setting
'COMPRESSION=None' no longer use page compression.  To uncompress
existing pages, you must rebuild the table using 'OPTIMIZE TABLE'
after setting 'COMPRESSION=None'.

     ALTER TABLE t1 COMPRESSION="None";
     OPTIMIZE TABLE t1;

*Page Compression Metadata*

Page compression metadata is found in the
'INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES'
table, in the following columns:

   * 'FS_BLOCK_SIZE': The file system block size, which is the unit size
     used for hole punching.

   * 'FILE_SIZE': The apparent size of the file, which represents the
     maximum size of the file, uncompressed.

   * 'ALLOCATED_SIZE': The actual size of the file, which is the amount
     of space allocated on disk.

*Note*:

On Unix-like systems, 'ls -l TABLESPACE_NAME.IBD' shows the apparent
file size (equivalent to 'FILE_SIZE') in bytes.  To view the actual
amount of space allocated on disk (equivalent to 'ALLOCATED_SIZE'), use
'du --block-size=1 TABLESPACE_NAME.IBD'.  The '--block-size=1' option
prints the allocated space in bytes instead of blocks, so that it can be
compared to 'ls -l' output.

Use 'SHOW CREATE TABLE' to view the current
page compression setting ('Zlib', 'Lz4', or 'None').  A table may
contain a mix of pages with different compression settings.

In the following example, page compression metadata for the employees
table is retrieved from the
'INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES'
table.

     # Create the employees table with Zlib page compression

     CREATE TABLE employees (
         emp_no      INT             NOT NULL,
         birth_date  DATE            NOT NULL,
         first_name  VARCHAR(14)     NOT NULL,
         last_name   VARCHAR(16)     NOT NULL,
         gender      ENUM ('M','F')  NOT NULL,
         hire_date   DATE            NOT NULL,
         PRIMARY KEY (emp_no)
     ) COMPRESSION="zlib";

     # Insert data (not shown)

     # Query page compression metadata in INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES

     mysql> SELECT SPACE, NAME, FS_BLOCK_SIZE, FILE_SIZE, ALLOCATED_SIZE FROM
            INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES WHERE NAME='employees/employees'\G
     *************************** 1. row ***************************
     SPACE: 45
     NAME: employees/employees
     FS_BLOCK_SIZE: 4096
     FILE_SIZE: 23068672
     ALLOCATED_SIZE: 19415040

Page compression metadata for the employees table shows that the
apparent file size is 23068672 bytes while the actual file size (with
page compression) is 19415040 bytes.  The file system block size is 4096
bytes, which is the block size used for hole punching.

*Page Compression Limitations and Usage Notes*

   * Page compression is disabled if the file system block size (or
     compression unit size on Windows) * 2 > 'innodb_page_size'.

   * Page compression is not supported for tables that reside in shared
     tablespaces, which include the system tablespace, the temporary
     tablespace, and general tablespaces.

   * Page compression is not supported for undo log tablespaces.

   * Page compression is not supported for redo log pages.

   * R-tree pages, which are used for spatial indexes, are not
     compressed.

   * Pages that belong to compressed tables ('ROW_FORMAT=COMPRESSED')
     are left as-is.

   * During recovery, updated pages are written out in an uncompressed
     form.

   * Loading a page-compressed tablespace on a server that does not
     support the compression algorithm that was used causes an I/O
     error.

   * Before downgrading to an earlier version of MySQL that does not
     support page compression, uncompress the tables that use the page
     compression feature.  To uncompress a table, run 'ALTER TABLE ... COMPRESSION=None'
     and 'OPTIMIZE TABLE'.

   * Page-compressed tablespaces can be copied between Linux and Windows
     servers if the compression algorithm that was used is available on
     both servers.

   * Preserving page compression when moving a page-compressed
     tablespace file from one host to another requires a utility that
     preserves sparse files.

   * Better page compression may be achieved on Fusion-io hardware with
     NVMFS than on other platforms, as NVMFS is designed to take
     advantage of punch hole functionality.

   * Using the page compression feature with a large 'InnoDB' page size
     and relatively small file system block size could result in write
     amplification.  For example, a maximum 'InnoDB' page size of 64KB
     with a 4KB file system block size may improve compression but may
     also increase demand on the buffer pool, leading to increased I/O
     and potential write amplification.

14.10 InnoDB File-Format Management
===================================

As 'InnoDB' evolves, data file formats that are not compatible with
prior versions of 'InnoDB' are sometimes required to support new
features.  To help manage compatibility in upgrade and downgrade
situations, and systems that run different versions of MySQL, 'InnoDB'
uses named file formats.  'InnoDB' currently supports two named file
formats, Antelope and Barracuda.

   * Antelope is the original 'InnoDB' file format, which previously did
     not have a name.  It supports the COMPACT and REDUNDANT row formats
     for 'InnoDB' tables.

   * Barracuda is the newest file format.  It supports all 'InnoDB' row
     formats including the newer COMPRESSED and DYNAMIC row formats.
     The features associated with COMPRESSED and DYNAMIC row formats
     include compressed tables, efficient storage of off-page columns,
     and index key prefixes up to 3072 bytes ('innodb_large_prefix').
     See innodb-row-format.

This section discusses enabling 'InnoDB' file formats for new 'InnoDB'
tables, verifying compatibility of different file formats between MySQL
releases, and identifying the file format in use.

InnoDB file format settings do not apply to tables stored in
general tablespaces.  General tablespaces provide
support for all row formats and associated features.  For more
information, see general-tablespaces.

*Note*:

The following file format configuration parameters have new default
values:

   * The 'innodb_file_format' default value was changed to 'Barracuda'.
     The previous default value was 'Antelope'.

   * The 'innodb_large_prefix' default value was changed to 'ON'.  The
     previous default was 'OFF'.

The following file format configuration parameters are deprecated in and
may be removed in a future release:

   * 'innodb_file_format'

   * 'innodb_file_format_check'

   * 'innodb_file_format_max'

   * 'innodb_large_prefix'

The file format configuration parameters were provided for creating
tables compatible with earlier versions of 'InnoDB' in MySQL 5.1.  Now
that MySQL 5.1 has reached the end of its product lifecycle, the
parameters are no longer required.

14.10.1 Enabling File Formats
-----------------------------

The 'innodb_file_format' configuration option enables an 'InnoDB' file
format for file-per-table tablespaces.

'Barracuda' is the default 'innodb_file_format' setting.  In earlier
releases, the default file format was 'Antelope'.

*Note*:

The 'innodb_file_format' configuration option is deprecated and may be
removed in a future release.  For more information, see
innodb-file-format.

You can set the value of 'innodb_file_format' on the command line when
you start 'mysqld', or in the option file ('my.cnf' on
Unix, 'my.ini' on Windows).  You can also change it dynamically with a
'SET GLOBAL' statement.

     SET GLOBAL innodb_file_format=Barracuda;

*Usage notes*

   * 'InnoDB' file format settings do not apply to tables stored in
     general tablespaces.  General
     tablespaces provide support for all row formats and associated
     features.  For more information, see general-tablespaces.

   * The 'innodb_file_format' setting is not applicable when using the
     'TABLESPACE [=] innodb_system' table option with 'CREATE TABLE'
     or 'ALTER TABLE' to store
     a 'DYNAMIC' table in the system tablespace.

   * The 'innodb_file_format' setting is ignored when creating tables
     that use the 'DYNAMIC' row format.  For more information, see
     innodb-row-format-dynamic.

14.10.2 Verifying File Format Compatibility
-------------------------------------------

InnoDB incorporates several checks to guard against the possible crashes
and data corruptions that might occur if you run an old release of the
MySQL server on InnoDB data files that use a newer file format.  These
checks take place when the server is started, and when you first access
a table.  This section describes these checks, how you can control them,
and error and warning conditions that might arise.

*Backward Compatibility*

You only need to consider backward file format compatibility when using
a recent version of InnoDB (MySQL 5.5 and higher with InnoDB) alongside
an older version (MySQL 5.1 or earlier, with the built-in InnoDB rather
than the InnoDB Plugin).  To minimize the chance of compatibility
issues, you can standardize on the InnoDB Plugin for all your MySQL 5.1
and earlier database servers.

In general, a newer version of InnoDB may create a table or index that
cannot safely be read or written with an older version of InnoDB without
risk of crashes, hangs, wrong results or corruptions.  InnoDB includes a
mechanism to guard against these conditions, and to help preserve
compatibility among database files and versions of InnoDB. This
mechanism lets you take advantage of some new features of an InnoDB
release (such as performance improvements and bug fixes), and still
preserve the option of using your database with an old version of
InnoDB, by preventing accidental use of new features that create
downward-incompatible disk files.

If a version of InnoDB supports a particular file format (whether or not
that format is the default), you can query and update any table that
requires that format or an earlier format.  Only the creation of new
tables using new features is limited based on the particular file format
enabled.  Conversely, if a tablespace contains a table or index that
uses a file format that is not supported, it cannot be accessed at all,
even for read access.

The only way to 'downgrade' an InnoDB tablespace to the earlier Antelope
file format is to copy the data to a new table, in a tablespace that
uses the earlier format.

The easiest way to determine the file format of an existing InnoDB
tablespace is to examine the properties of the table it contains, using
the 'SHOW TABLE STATUS' command or querying the table
'INFORMATION_SCHEMA.TABLES'.  If the 'Row_format' of the table is
reported as ''Compressed'' or ''Dynamic'', the tablespace containing the
table supports the Barracuda format.

*Internal Details*

Every InnoDB file-per-table tablespace (represented by a '*.ibd' file)
file is labeled with a file format identifier.  The system tablespace
(represented by the 'ibdata' files) is tagged with the 'highest' file
format in use in a group of InnoDB database files, and this tag is
checked when the files are opened.

Creating a compressed table, or a table with 'ROW_FORMAT=DYNAMIC',
updates the file header of the corresponding file-per-table '.ibd' file
and the table type in the InnoDB data dictionary with the identifier for
the Barracuda file format.  From that point forward, the table cannot be
used with a version of InnoDB that does not support the Barracuda file
format.  To protect against anomalous behavior, InnoDB performs a
compatibility check when the table is opened.  (In many cases, the
'ALTER TABLE' statement recreates a table and thus changes
its properties.  The special case of adding or dropping indexes without
rebuilding the table is described in
innodb-create-index-overview.)

General tablespaces, which are also represented by a '*.ibd' file,
support both Antelope and Barracuda file formats.  For more information
about general tablespaces, see general-tablespaces.

*Definition of ib-file set*

To avoid confusion, for the purposes of this discussion we define the
term 'ib-file set' to mean the set of operating system files that InnoDB
manages as a unit.  The ib-file set includes the following files:

   * The system tablespace (one or more 'ibdata' files) that contain
     internal system information (including internal catalogs and undo
     information) and may include user data and indexes.

   * Zero or more single-table tablespaces (also called 'file per table'
     files, named '*.ibd' files).

   * InnoDB log files; usually two, 'ib_logfile0' and 'ib_logfile1'.
     Used for crash recovery and in backups.

An 'ib-file set' does not include the corresponding '.frm' files that
contain metadata about InnoDB tables.  The '.frm' files are created and
managed by MySQL, and can sometimes get out of sync with the internal
metadata in InnoDB.

Multiple tables, even from more than one database, can be stored in a
single 'ib-file set'.  (In MySQL, a 'database' is a logical collection
of tables, what other systems refer to as a 'schema' or 'catalog'.)

14.10.2.1 Compatibility Check When InnoDB Is Started
....................................................

To prevent possible crashes or data corruptions when InnoDB opens an
ib-file set, it checks that it can fully support the file formats in use
within the ib-file set.  If the system is restarted following a crash,
or a 'fast shutdown' (i.e., 'innodb_fast_shutdown' is greater than
zero), there may be on-disk data structures (such as redo or undo
entries, or doublewrite pages) that are in a 'too-new' format for the
current software.  During the recovery process, serious damage can be
done to your data files if these data structures are accessed.  The
startup check of the file format occurs before any recovery process
begins, thereby preventing consistency issues with the new tables or
startup problems for the MySQL server.

Beginning with version InnoDB 1.0.1, the system tablespace records an
identifier or tag for the 'highest' file format used by any table in any
of the tablespaces that is part of the ib-file set.  Checks against this
file format tag are controlled by the configuration parameter
'innodb_file_format_check', which is 'ON' by default.

If the file format tag in the system tablespace is newer or higher than
the highest version supported by the particular currently executing
software and if 'innodb_file_format_check' is 'ON', the following error
is issued when the server is started:

     InnoDB: Error: the system tablespace is in a
     file format that this version doesn't support

You can also set 'innodb_file_format' to a file format name.  Doing so
prevents InnoDB from starting if the current software does not support
the file format specified.  It also sets the 'high water mark' to the
value you specify.  The ability to set 'innodb_file_format_check' is
useful (with future releases) if you manually 'downgrade' all of the
tables in an ib-file set.  You can then rely on the file format check at
startup if you subsequently use an older version of InnoDB to access the
ib-file set.

In some limited circumstances, you might want to start the server and
use an ib-file set that is in a new file format that is not supported by
the software you are using.  If you set the configuration parameter
'innodb_file_format_check' to 'OFF', InnoDB opens the database, but
issues this warning message in the error log:

     InnoDB: Warning: the system tablespace is in a
     file format that this version doesn't support

*Note*:

This is a dangerous setting, as it permits the recovery process to run,
possibly corrupting your database if the previous shutdown was a crash
or 'fast shutdown'.  You should only set 'innodb_file_format_check' to
'OFF' if you are sure that the previous shutdown was done with
'innodb_fast_shutdown=0', so that essentially no recovery process
occurs.

The parameter 'innodb_file_format_check' affects only what happens when
a database is opened, not subsequently.  Conversely, the parameter
'innodb_file_format' (which enables a specific format) only determines
whether or not a new table can be created in the enabled format and has
no effect on whether or not a database can be opened.

The file format tag is a 'high water mark', and as such it is increased
after the server is started, if a table in a 'higher' format is created
or an existing table is accessed for read or write (assuming its format
is supported).  If you access an existing table in a format higher than
the format the running software supports, the system tablespace tag is
not updated, but table-level compatibility checking applies (and an
error is issued), as described in
innodb-file-format-compatibility-checking-table-access.  Any time the
high water mark is updated, the value of 'innodb_file_format_check' is
updated as well, so the command 'SELECT @@innodb_file_format_check;'
displays the name of the latest file format known to be used by tables
in the currently open ib-file set and supported by the currently
executing software.

14.10.2.2 Compatibility Check When a Table Is Opened
....................................................

When a table is first accessed, InnoDB (including some releases prior to
InnoDB 1.0) checks that the file format of the tablespace in which the
table is stored is fully supported.  This check prevents crashes or
corruptions that would otherwise occur when tables using a 'too new'
data structure are encountered.

All tables using any file format supported by a release can be read or
written (assuming the user has sufficient privileges).  The setting of
the system configuration parameter 'innodb_file_format' can prevent
creating a new table that uses a specific file format, even if the file
format is supported by a given release.  Such a setting might be used to
preserve backward compatibility, but it does not prevent accessing any
table that uses a supported format.

Versions of MySQL older than 5.0.21 cannot reliably use database files
created by newer versions if a new file format was used when a table was
created.  To prevent various error conditions or corruptions, InnoDB
checks file format compatibility when it opens a file (for example, upon
first access to a table).  If the currently running version of InnoDB
does not support the file format identified by the table type in the
InnoDB data dictionary, MySQL reports the following error:

     ERROR 1146 (42S02): Table 'TEST.T1' doesn't exist

InnoDB also writes a message to the error log:

     InnoDB: table TEST/T1: unknown table type 33

The table type should be equal to the tablespace flags, which contains
the file format version as discussed in
innodb-file-format-identifying.

Versions of InnoDB prior to MySQL 4.1 did not include table format
identifiers in the database files, and versions prior to MySQL 5.0.21
did not include a table format compatibility check.  Therefore, there is
no way to ensure proper operations if a table in a newer file format is
used with versions of InnoDB prior to 5.0.21.

The file format management capability in InnoDB 1.0 and higher
(tablespace tagging and run-time checks) allows InnoDB to verify as soon
as possible that the running version of software can properly process
the tables existing in the database.

If you permit InnoDB to open a database containing files in a format it
does not support (by setting the parameter 'innodb_file_format_check' to
'OFF'), the table-level checking described in this section still
applies.

Users are _strongly_ urged not to use database files that contain
Barracuda file format tables with releases of InnoDB older than the
MySQL 5.1 with the InnoDB Plugin.  It may be possible to rebuild such
tables to use the Antelope format.

14.10.3 Identifying the File Format in Use
------------------------------------------

If you enable a different file format using the 'innodb_file_format'
configuration option, the change only applies to newly created tables.
Also, when you create a new table, the tablespace containing the table
is tagged with the 'earliest' or 'simplest' file format that is required
to support the table's features.  For example, if you enable the
'Barracuda' file format, and create a new table that does not use the
Dynamic or Compressed row format, the new tablespace that contains the
table is tagged as using the 'Antelope' file format .

It is easy to identify the file format used by a given table.  The table
uses the 'Antelope' file format if the row format reported by 'SHOW
TABLE STATUS' is either 'Compact' or 'Redundant'.  The table uses the
'Barracuda' file format if the row format reported by 'SHOW TABLE
STATUS' is either 'Compressed' or 'Dynamic'.

     mysql> SHOW TABLE STATUS\G
     *************************** 1. row ***************************
                Name: t1
              Engine: InnoDB
             Version: 10
          Row_format: Compact
                Rows: 0
      Avg_row_length: 0
         Data_length: 16384
     Max_data_length: 0
        Index_length: 16384
           Data_free: 0
      Auto_increment: 1
         Create_time: 2014-11-03 13:32:10
         Update_time: NULL
          Check_time: NULL
           Collation: latin1_swedish_ci
            Checksum: NULL
      Create_options:
             Comment:

You can also identify the file format used by a given table or
tablespace using 'InnoDB' 'INFORMATION_SCHEMA' tables.  For example:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME='test/t1'\G
     *************************** 1. row ***************************
          TABLE_ID: 44
              NAME: test/t1
              FLAG: 1
            N_COLS: 6
             SPACE: 30
       FILE_FORMAT: Antelope
        ROW_FORMAT: Compact
     ZIP_PAGE_SIZE: 0

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES WHERE NAME='test/t1'\G
     *************************** 1. row ***************************
             SPACE: 30
              NAME: test/t1
              FLAG: 0
       FILE_FORMAT: Antelope
        ROW_FORMAT: Compact or Redundant
         PAGE_SIZE: 16384
     ZIP_PAGE_SIZE: 0

14.10.4 Modifying the File Format
---------------------------------

Each InnoDB tablespace file (with a name matching '*.ibd') is tagged
with the file format used to create its table and indexes.  The way to
modify the file format is to re-create the table and its indexes.  The
easiest way to recreate a table and its indexes is to use the following
command on each table that you want to modify:

     ALTER TABLE T ROW_FORMAT=FORMAT_NAME;

If you are modifying the file format to downgrade to an older MySQL
version, there may be incompatibilities in table storage formats that
require additional steps.  For information about downgrading to a
previous MySQL version, see downgrading.

14.11 InnoDB Row Storage and Row Formats
========================================

This section discusses how InnoDB features such as table compression,
off-page storage of long variable-length column values, and large index
key prefixes ('innodb_large_prefix') are controlled by the row format of
an 'InnoDB' table.  It also discusses considerations for choosing the
right row format, and compatibility of row formats between MySQL
releases.

14.11.1 Overview of InnoDB Row Storage
--------------------------------------

The storage for rows and associated columns affects performance for
queries and DML operations.  As more rows fit into a single disk page,
queries and index lookups can work faster, less cache memory is required
in the InnoDB buffer pool, and less I/O is required to write out updated
values for the numeric and short string columns.

The data in each InnoDB table is divided into pages.  The pages that
make up each table are arranged in a tree data structure called a B-tree
index.  Table data and secondary indexes both use this type of
structure.  The B-tree index that represents an entire table is known as
the clustered index, which is organized according to the primary key
columns.  The nodes of the index data structure contain the values of
all the columns in that row (for the clustered index) or the index
columns and the primary key columns (for secondary indexes).

Variable-length columns are an exception to this rule.  Columns such as
'BLOB' and 'VARCHAR' that are too long to fit on a B-tree page are
stored on separately allocated disk pages called overflow pages.  We
call such columns off-page columns.  The values of these columns are
stored in singly-linked lists of overflow pages, and each such column
has its own list of one or more overflow pages.  In some cases, all or a
prefix of the long column value is stored in the B-tree, to avoid
wasting storage and eliminating the need to read a separate page.

The following sections describe how to configure the row format of
'InnoDB' tables to control how variable-length columns values are
stored.  Row format configuration also determines the availability of
the table compression feature and the large index key prefix feature
('innodb_large_prefix').

14.11.2 Specifying the Row Format for a Table
---------------------------------------------

The default row format is defined by 'innodb_default_row_format', which
has a default value of 'DYNAMIC'.  The default row format is used when
the 'ROW_FORMAT' table option is not defined explicitly or when
'ROW_FORMAT=DEFAULT' is specified.

The row format of a table can be defined explicitly using the
'ROW_FORMAT' table option in a 'CREATE TABLE' or
'ALTER TABLE' statement.  For example:

     CREATE TABLE t1 (c1 INT) ROW_FORMAT=DYNAMIC;

An explicitly defined 'ROW_FORMAT' setting overrides the implicit
default.  Specifying 'ROW_FORMAT=DEFAULT' is equivalent to using the
implicit default.

The 'innodb_default_row_format' option can be set dynamically:

     mysql> SET GLOBAL innodb_default_row_format=DYNAMIC;

Valid 'innodb_default_row_format' options include 'DYNAMIC', 'COMPACT',
and 'REDUNDANT'.  The 'COMPRESSED' row format, which is not supported
for use in the system tablespace, cannot be defined as the default.  It
can only be specified explicitly in a 'CREATE TABLE'
or 'ALTER TABLE' statement.
Attempting to set 'innodb_default_row_format' to 'COMPRESSED' returns an
error:

     mysql> SET GLOBAL innodb_default_row_format=COMPRESSED;
     ERROR 1231 (42000): Variable 'innodb_default_row_format'
     can't be set to the value of 'COMPRESSED'

Newly created tables use the row format defined by
'innodb_default_row_format' when a 'ROW_FORMAT' option is not specified
explicitly or when 'ROW_FORMAT=DEFAULT' is used.  For example, the
following 'CREATE TABLE' statements use the row
format defined by 'innodb_default_row_format'.

     CREATE TABLE t1 (c1 INT);

     CREATE TABLE t2 (c1 INT) ROW_FORMAT=DEFAULT;

When a 'ROW_FORMAT' option is not specified explicitly or when
'ROW_FORMAT=DEFAULT' is used, any operation that rebuilds a table also
silently changes the row format of the table to the format defined by
'innodb_default_row_format'.

Table-rebuilding operations include 'ALTER TABLE'.
operations that use 'ALGORITHM=COPY' or 'ALTER TABLE'
operations that use 'ALGORITHM=INPLACE' where table
rebuilding is required.  See innodb-online-ddl-summary-grid for
an overview of the online status of DDL operations.  'OPTIMIZE TABLE'
is also a table-rebuilding operation.

The following example demonstrates a table-rebuilding operation that
silently changes the row format of a table created without an explicitly
defined row format.

     mysql> SELECT @@innodb_default_row_format;
     +-----------------------------+
     | @@innodb_default_row_format |
     +-----------------------------+
     | dynamic                     |
     +-----------------------------+

     mysql> CREATE TABLE t1 (c1 INT);

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME LIKE 'test/t1' \G
     *************************** 1. row ***************************
          TABLE_ID: 54
              NAME: test/t1
              FLAG: 33
            N_COLS: 4
             SPACE: 35
       FILE_FORMAT: Barracuda
        ROW_FORMAT: Dynamic
     ZIP_PAGE_SIZE: 0
        SPACE_TYPE: Single

     mysql> SET GLOBAL innodb_default_row_format=COMPACT;

     mysql> ALTER TABLE t1 ADD COLUMN (c2 INT);

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME LIKE 'test/t1' \G
     *************************** 1. row ***************************
          TABLE_ID: 55
              NAME: test/t1
              FLAG: 1
            N_COLS: 5
             SPACE: 36
       FILE_FORMAT: Antelope
        ROW_FORMAT: Compact
     ZIP_PAGE_SIZE: 0
        SPACE_TYPE: Single

Consider the following potential issues before changing the row format
of existing tables from 'REDUNDANT' or 'COMPACT' to 'DYNAMIC'.

   * The 'REDUNDANT' and 'COMPACT' row format supports a maximum index
     key prefix length of 767 bytes whereas 'DYNAMIC' and 'COMPRESSED'
     row formats support an index key prefix length of 3072 bytes if the
     'innodb_large_prefix' configuration option is enabled.  In a
     replication environment, if 'innodb_default_row_format' is set to
     'DYNAMIC' on the master and set to 'COMPACT' on the slave, the
     following DDL statement, which does not explicitly define a row
     format, succeeds on the master but fails on the slave:

          CREATE TABLE t1 (c1 INT PRIMARY KEY, c2 VARCHAR(5000), KEY i1(c2(3070)));

     For related information, see innodb-restrictions.

   * Importing a table that does not explicitly define a row format
     results in a schema mismatch error if the
     'innodb_default_row_format' setting on the source server differs
     from the setting on the destination server.  For more information,
     refer to the limitations outlined in tablespace-copying.

To view the row format of a table, issue a 'SHOW TABLE STATUS'
statement or query 'INFORMATION_SCHEMA.TABLES'.

     SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME LIKE 'test/t1' \G

The row format of an 'InnoDB' table determines its physical row
structure.  See innodb-physical-record for more information.

14.11.3 DYNAMIC and COMPRESSED Row Formats
------------------------------------------

When a table is created with 'ROW_FORMAT=DYNAMIC' or
'ROW_FORMAT=COMPRESSED', 'InnoDB' can store long variable-length column
values (for 'VARCHAR', 'VARBINARY',
and 'BLOB' and 'TEXT' types) fully off-page,
with the clustered index record containing only a 20-byte pointer to the
overflow page.  'InnoDB' also encodes fixed-length fields greater than
or equal to 768 bytes in length as variable-length fields.  For example,
a 'CHAR(255)' column can exceed 768 bytes if the maximum byte length of
the character set is greater than 3, as it is with 'utf8mb4'.

Whether any columns are stored off-page depends on the page size and the
total size of the row.  When the row is too long, 'InnoDB' chooses the
longest columns for off-page storage until the clustered index record
fits on the B-tree page.  'TEXT' and 'BLOB'.
columns that are less than or equal to 40 bytes are always stored
in-line.

The 'DYNAMIC' row format maintains the efficiency of storing the entire
row in the index node if it fits (as do the 'COMPACT' and 'REDUNDANT'
formats), but the 'DYNAMIC' row format avoids the problem of filling
B-tree nodes with a large number of data bytes of long columns.  The
'DYNAMIC' format is based on the idea that if a portion of a long data
value is stored off-page, it is usually most efficient to store all of
the value off-page.  With 'DYNAMIC' format, shorter columns are likely
to remain in the B-tree node, minimizing the number of overflow pages
needed for any given row.

The 'COMPRESSED' row format uses similar internal details for off-page
storage as the 'DYNAMIC' row format, with additional storage and
performance considerations from the table and index data being
compressed and using smaller page sizes.  With the 'COMPRESSED' row
format, the 'KEY_BLOCK_SIZE' option controls how much column data is
stored in the clustered index, and how much is placed on overflow pages.
For full details about the 'COMPRESSED' row format, see
innodb-compression.

Both 'DYNAMIC' and 'COMPRESSED' row formats support index key prefixes
up to 3072 bytes.  This feature is controlled by the
'innodb_large_prefix' configuration option, which is enabled by default.
See the 'innodb_large_prefix' option description for more information.

Tables that use the 'COMPRESSED' row format can be created in
file-per-table tablespaces or general tablespaces.  The system
tablespace does not support the 'COMPRESSED' row format.  To store a
'COMPRESSED' table in a file-per-table tablespace,
'innodb_file_per_table' must be enabled and 'innodb_file_format' must be
set to 'Barracuda'.  The 'innodb_file_per_table' and
'innodb_file_format' configuration options are not applicable to general
tablespaces.  General tablespaces support all row formats with the
caveat that compressed and uncompressed tables cannot coexist in the
same general tablespace due to different physical page sizes.  For more
information about general tablespaces, see general-tablespaces.

'DYNAMIC' tables can be stored in file-per-table tablespaces, general
tablespaces, and the system tablespace.  To store 'DYNAMIC' tables in
the system tablespace, you must use the 'TABLESPACE [=] innodb_system'
table option with 'CREATE TABLE' or 'ALTER TABLE'.  The
'innodb_file_per_table' and 'innodb_file_format' configuration options
are not applicable to general tablespaces, nor are they applicable when
using the 'TABLESPACE [=] innodb_system' table option to store 'DYNAMIC'
tables in the system tablespace.

You can add a 'DYNAMIC' table to the system tablespace by disabling
'innodb_file_per_table' and using a regular 'CREATE TABLE' or 'ALTER
TABLE' statement.  The 'innodb_file_format' setting is ignored.  A
'DYNAMIC' table always uses the 'Barracuda' file format.

'DYNAMIC' and 'COMPRESSED' row formats are variations of the 'COMPACT'
row format and therefore handle 'CHAR' storage in the same
way as the 'COMPACT' row format.  For more information, see
innodb-physical-record.

14.11.4 COMPACT and REDUNDANT Row Formats
-----------------------------------------

Early versions of 'InnoDB' used an unnamed file format (now called
Antelope) for database files.  With that file format, tables are defined
with 'ROW_FORMAT=COMPACT' or 'ROW_FORMAT=REDUNDANT'.  With these row
formats, 'InnoDB' stores up to the first 768 bytes of variable-length
columns (see 'VARCHAR', 'VARBINARY', and
'BLOB' and 'TEXT' types) in the index record
within the B-tree node, with the remainder stored on the overflow pages.
'InnoDB' also encodes fixed-length fields greater than or equal to 768
bytes in length as variable-length fields, which can be stored off-page.
For example, a 'CHAR(255)' column can exceed 768 bytes if the maximum
byte length of the character set is greater than 3, as it is with
'utf8mb4'.

With the Antelope file format, if the value of a column is 768 bytes or
less, no overflow page is needed, and some savings in I/O may result,
since the value is in the B-tree node.  This works well for relatively
short 'BLOB's, but may cause B-tree nodes to fill with data rather than
key values, reducing their efficiency.  Tables with many 'BLOB' columns
could cause B-tree nodes to become too full of data, and contain too few
rows, making the entire index less efficient than if the rows were
shorter or if the column values were stored off-page.

For information about the physical row structure of tables that use the
'REDUNDANT' or 'COMPACT' row format, see innodb-physical-record.

14.12 InnoDB Disk I/O and File Space Management
===============================================

As a DBA, you must manage disk I/O to keep the I/O subsystem from
becoming saturated, and manage disk space to avoid filling up storage
devices.  The ACID design model requires a certain amount of I/O that
might seem redundant, but helps to ensure data reliability.  Within
these constraints, 'InnoDB' tries to optimize the database work and the
organization of disk files to minimize the amount of disk I/O.
Sometimes, I/O is postponed until the database is not busy, or until
everything needs to be brought to a consistent state, such as during a
database restart after a fast shutdown.

This section discusses the main considerations for I/O and disk space
with the default kind of MySQL tables (also known as 'InnoDB' tables):

   * Controlling the amount of background I/O used to improve query
     performance.

   * Enabling or disabling features that provide extra durability at the
     expense of additional I/O.

   * Organizing tables into many small files, a few larger files, or a
     combination of both.

   * Balancing the size of redo log files against the I/O activity that
     occurs when the log files become full.

   * How to reorganize a table for optimal query performance.

14.12.1 InnoDB Disk I/O
-----------------------

'InnoDB' uses asynchronous disk I/O where possible, by creating a number
of threads to handle I/O operations, while permitting other database
operations to proceed while the I/O is still in progress.  On Linux and
Windows platforms, 'InnoDB' uses the available OS and library functions
to perform 'native' asynchronous I/O. On other platforms, 'InnoDB' still
uses I/O threads, but the threads may actually wait for I/O requests to
complete; this technique is known as 'simulated' asynchronous I/O.

*Read-Ahead*

If 'InnoDB' can determine there is a high probability that data might be
needed soon, it performs read-ahead operations to bring that data into
the buffer pool so that it is available in memory.  Making a few large
read requests for contiguous data can be more efficient than making
several small, spread-out requests.  There are two read-ahead heuristics
in 'InnoDB':

   * In sequential read-ahead, if 'InnoDB' notices that the access
     pattern to a segment in the tablespace is sequential, it posts in
     advance a batch of reads of database pages to the I/O system.

   * In random read-ahead, if 'InnoDB' notices that some area in a
     tablespace seems to be in the process of being fully read into the
     buffer pool, it posts the remaining reads to the I/O system.

For information about configuring read-ahead heuristics, see
innodb-performance-read_ahead.

*Doublewrite Buffer*

'InnoDB' uses a novel file flush technique involving a structure called
the doublewrite buffer, which is enabled by default in most cases
('innodb_doublewrite=ON').  It adds safety to recovery following a crash
or power outage, and improves performance on most varieties of Unix by
reducing the need for 'fsync()' operations.

Before writing pages to a data file, 'InnoDB' first writes them to a
contiguous tablespace area called the doublewrite buffer.  Only after
the write and the flush to the doublewrite buffer has completed does
'InnoDB' write the pages to their proper positions in the data file.  If
there is an operating system, storage subsystem, or 'mysqld'
process crash in the middle of a page write (causing a torn page
condition), 'InnoDB' can later find a good copy of the page from the
doublewrite buffer during recovery.

If system tablespace files ('ibdata files') are located on Fusion-io
devices that support atomic writes, doublewrite buffering is
automatically disabled and Fusion-io atomic writes are used for all data
files.  Because the doublewrite buffer setting is global, doublewrite
buffering is also disabled for data files residing on non-Fusion-io
hardware.  This feature is only supported on Fusion-io hardware and is
only enabled for Fusion-io NVMFS on Linux.  To take full advantage of
this feature, an 'innodb_flush_method' setting of 'O_DIRECT' is
recommended.

14.12.2 File Space Management
-----------------------------

The data files that you define in the configuration file using the
'innodb_data_file_path' configuration option form the 'InnoDB' system
tablespace.  The files are logically concatenated to form the system
tablespace.  There is no striping in use.  You cannot define where
within the system tablespace your tables are allocated.  In a newly
created system tablespace, 'InnoDB' allocates space starting from the
first data file.

To avoid the issues that come with storing all tables and indexes inside
the system tablespace, you can enable the 'innodb_file_per_table'
configuration option (the default), which stores each newly created
table in a separate tablespace file (with extension '.ibd').  For tables
stored this way, there is less fragmentation within the disk file, and
when the table is truncated, the space is returned to the operating
system rather than still being reserved by InnoDB within the system
tablespace.  For more information, see
innodb-multiple-tablespaces.

You can also store tables in general tablespaces.  General tablespaces
are shared tablespaces created using 'CREATE TABLESPACE'
syntax.  They can be created outside of the MySQL
data directory, are capable of holding multiple tables, and support
tables of all row formats.  For more information, see
general-tablespaces.

*Pages, Extents, Segments, and Tablespaces*

Each tablespace consists of database pages.  Every tablespace in a MySQL
instance has the same page size.  By default, all tablespaces have a
page size of 16KB; you can reduce the page size to 8KB or 4KB by
specifying the 'innodb_page_size' option when you create the MySQL
instance.  You can also increase the page size to 32KB or 64KB. For more
information, refer to the 'innodb_page_size' documentation.

The pages are grouped into extents of size 1MB for pages up to 16KB in
size (64 consecutive 16KB pages, or 128 8KB pages, or 256 4KB pages).
For a page size of 32KB, extent size is 2MB. For page size of 64KB,
extent size is 4MB. The 'files' inside a tablespace are called segments
in 'InnoDB'.  (These segments are different from the rollback segment,
which actually contains many tablespace segments.)

When a segment grows inside the tablespace, 'InnoDB' allocates the first
32 pages to it one at a time.  After that, 'InnoDB' starts to allocate
whole extents to the segment.  'InnoDB' can add up to 4 extents at a
time to a large segment to ensure good sequentiality of data.

Two segments are allocated for each index in 'InnoDB'.  One is for
nonleaf nodes of the B-tree, the other is for the leaf nodes.  Keeping
the leaf nodes contiguous on disk enables better sequential I/O
operations, because these leaf nodes contain the actual table data.

Some pages in the tablespace contain bitmaps of other pages, and
therefore a few extents in an 'InnoDB' tablespace cannot be allocated to
segments as a whole, but only as individual pages.

When you ask for available free space in the tablespace by issuing a
'SHOW TABLE STATUS' statement, 'InnoDB'
reports the extents that are definitely free in the tablespace.
'InnoDB' always reserves some extents for cleanup and other internal
purposes; these reserved extents are not included in the free space.

When you delete data from a table, 'InnoDB' contracts the corresponding
B-tree indexes.  Whether the freed space becomes available for other
users depends on whether the pattern of deletes frees individual pages
or extents to the tablespace.  Dropping a table or deleting all rows
from it is guaranteed to release the space to other users, but remember
that deleted rows are physically removed only by the purge operation,
which happens automatically some time after they are no longer needed
for transaction rollbacks or consistent reads.  (See
innodb-multi-versioning.)

*How Pages Relate to Table Rows*

The maximum row length is slightly less than half a database page for
4KB, 8KB, 16KB, and 32KB 'innodb_page_size' settings.  For example, the
maximum row length is slightly less than 8KB for the default 16KB
'InnoDB' page size.  For 64KB pages, the maximum row length is slightly
less than 16KB.

If a row does not exceed the maximum row length, all of it is stored
locally within the page.  If a row exceeds the maximum row length,
variable-length columns are chosen for external off-page storage until
the row fits within the maximum row length limit.  External off-page
storage for variable-length columns differs by row format:

   * _COMPACT and REDUNDANT Row Formats_

     When a variable-length column is chosen for external off-page
     storage, 'InnoDB' stores the first 768 bytes locally in the row,
     and the rest externally into overflow pages.  Each such column has
     its own list of overflow pages.  The 768-byte prefix is accompanied
     by a 20-byte value that stores the true length of the column and
     points into the overflow list where the rest of the value is
     stored.  See innodb-row-format-antelope.

   * _DYNAMIC and COMPRESSED Row Formats_

     When a variable-length column is chosen for external off-page
     storage, 'InnoDB' stores a 20-byte pointer locally in the row, and
     the rest externally into overflow pages.  See
     innodb-row-format-dynamic.

'LONGBLOB' and 'LONGTEXT' columns must be less
than 4GB, and the total row length, including 'BLOB' and
'TEXT' columns, must be less than 4GB.

14.12.3 InnoDB Checkpoints
--------------------------

Making your log files very large may reduce disk I/O during
checkpointing.  It often makes sense to set the total size of the log
files as large as the buffer pool or even larger.  Although in the past
large log files could make crash recovery take excessive time, starting
with MySQL 5.5, performance enhancements to crash recovery make it
possible to use large log files with fast startup after a crash.
(Strictly speaking, this performance improvement is available for MySQL
5.1 with the InnoDB Plugin 1.0.7 and higher.  It is with MySQL 5.5 that
this improvement is available in the default InnoDB storage engine.)

*How Checkpoint Processing Works*

'InnoDB' implements a checkpoint mechanism known as fuzzy checkpointing.
'InnoDB' flushes modified database pages from the buffer pool in small
batches.  There is no need to flush the buffer pool in one single batch,
which would disrupt processing of user SQL statements during the
checkpointing process.

During crash recovery, 'InnoDB' looks for a checkpoint label written to
the log files.  It knows that all modifications to the database before
the label are present in the disk image of the database.  Then 'InnoDB'
scans the log files forward from the checkpoint, applying the logged
modifications to the database.

14.12.4 Defragmenting a Table
-----------------------------

Random insertions into or deletions from a secondary index can cause the
index to become fragmented.  Fragmentation means that the physical
ordering of the index pages on the disk is not close to the index
ordering of the records on the pages, or that there are many unused
pages in the 64-page blocks that were allocated to the index.

One symptom of fragmentation is that a table takes more space than it
'should' take.  How much that is exactly, is difficult to determine.
All 'InnoDB' data and indexes are stored in B-trees, and their fill
factor may vary from 50% to 100%.  Another symptom of fragmentation is
that a table scan such as this takes more time than it 'should' take:

     SELECT COUNT(*) FROM t WHERE NON_INDEXED_COLUMN <> 12345;

The preceding query requires MySQL to perform a full table scan, the
slowest type of query for a large table.

To speed up index scans, you can periodically perform a 'null'
'ALTER TABLE' operation, which causes MySQL to rebuild the
table:

     ALTER TABLE TBL_NAME ENGINE=INNODB

You can also use 'ALTER TABLE TBL_NAME FORCE' to
perform a 'null' alter operation that rebuilds the table.

Both 'ALTER TABLE TBL_NAME ENGINE=INNODB' and
'ALTER TABLE TBL_NAME FORCE' use online DDL.
For more information, see
innodb-create-index-overview.

Another way to perform a defragmentation operation is to use
'mysqldump' to dump the table to a text file, drop the
table, and reload it from the dump file.

If the insertions into an index are always ascending and records are
deleted only from the end, the 'InnoDB' filespace management algorithm
guarantees that fragmentation in the index does not occur.

14.12.5 Reclaiming Disk Space with TRUNCATE TABLE
-------------------------------------------------

To reclaim operating system disk space when truncating an 'InnoDB'
table, the table must be stored in its own .ibd file.  For a table to be
stored in its own .ibd file, 'innodb_file_per_table' must enabled when
the table is created.  Additionally, there cannot be a foreign key
constraint between the table being truncated and other tables, otherwise
the 'TRUNCATE TABLE' operation fails.  A foreign key constraint between
two columns in the same table, however, is permitted.

When a table is truncated, it is dropped and re-created in a new '.ibd'
file, and the freed space is returned to the operating system.  This is
in contrast to truncating 'InnoDB' tables that are stored within the
'InnoDB' system tablespace (tables created when
'innodb_file_per_table=OFF') and tables stored in shared general
tablespaces, where only 'InnoDB' can use the freed space after the table
is truncated.

The ability to truncate tables and return disk space to the operating
system also means that physical backups can be smaller.  Truncating
tables that are stored in the system tablespace (tables created when
'innodb_file_per_table=OFF') or in a general tablespace leaves blocks of
unused space in the tablespace.

14.13 InnoDB and Online DDL
===========================

The 'InnoDB' online DDL feature permits in-place table alterations or
concurrent DML, or both.  Benefits of this feature include:

   * Improved responsiveness and availability in busy production
     environments, where making a table unavailable for minutes or hours
     is not practical.

   * The ability to adjust the balance between performance and
     concurrency during a DDL operations using the 'LOCK' clause.

        * 'LOCK=EXCLUSIVE' blocks access to the table entirely.

        * 'LOCK=SHARED' allows queries but not DML.

        * 'LOCK=NONE' allows full query and DML access to the table.

        * 'LOCK=DEFAULT' or omitting the 'LOCK' clause permits as much
          concurrency as possible depending on the type of DDL
          operation.

   * Avoidance of disk space usage and I/O overhead associated with
     copying the table and reconstructing secondary indexes.

14.13.1 Online DDL Overview
---------------------------

The online DDL feature enhances many DDL operations that formerly
required a table copy or blocked DML operations on the table, or both.
innodb-online-ddl-summary-grid shows how the online DDL feature
applies to each DDL statement.

With the exception of most 'ALTER TABLE'.
partitioning clauses, online DDL operations for partitioned 'InnoDB'
tables follow the same rules that apply to regular 'InnoDB' tables.  For
more information, see online-ddl-partitioning.

Some factors affect the performance, space usage, and semantics of
online DDL operations.  For more information, see
innodb-create-index-limitations.

   * The 'In-Place?' column shows which operations permit the
     'ALGORITHM=INPLACE' clause.

   * The 'Rebuilds Table?' column shows which operations rebuild the
     table.  For operations that use the 'INPLACE' algorithm, the table
     is rebuilt in place.  For operations that do not support the
     'INPLACE' algorithm, the table copy method is used to rebuild the
     table.

   * The 'Permits Concurrent DML?' column shows which operations are
     performed fully online.  You can specify 'LOCK=NONE' to assert that
     concurrent DML is permitted during the DDL operation.  MySQL
     automatically permits concurrent DML when possible.

     Concurrent queries are permitted during all online DDL operations.
     You can specify 'LOCK=SHARED' to assert that concurrent queries are
     permitted during a DDL operation.  MySQL automatically permits
     concurrent queries when possible.

   * The 'Notes' column provides additional information and explains
     exceptions and dependencies related to the 'Yes/No' values of other
     columns.  An asterisk indicates an exception or dependency.

*Online Status for DDL Operations*

Operation         In Place?                                                  Rebuilds  Permits   Only      Notes
                                                                             Table?    ConcurrentModifies
                                                                                       DML?      Metadata?

See 'CREATE Yes* No* Yes No Restrictions apply INDEX',
                                                                                      indexes; see next
'ADD row. INDEX'.

*note 'ADD        Yes*                                                       No*       No        No        Adding the first
FULLTEXT                                                                                                   'FULLTEXT' index
INDEX':                                                                                                    rebuilds the table if
alter-table.                                                                                               there is no
                                                                                                           user-defined
                                                                                                           'FTS_DOC_ID' column.
                                                                                                           Subsequent 'FULLTEXT'
                                                                                                           indexes may be added
                                                                                                           on the same table
                                                                                                           without rebuilding
                                                                                                           the table.

See 'ADD Yes No No No SPATIAL INDEX'.

See 'RENAME Yes No Yes Yes Only modifies table INDEX'.
alter-table.

See 'DROP Yes No Yes Yes Only modifies table INDEX'.
drop-index.

See 'OPTIMIZE Yes* Yes Yes No In-place operation is TABLE'.
                                                                                    tables with
                                                                                                           'FULLTEXT' indexes.

Set column        Yes                                                        No        Yes       Yes       Only modifies table
default value                                                                                              metadata.

Change            Yes                                                        No        Yes       No*       Modifies a value
auto-increment                                                                                             stored in memory, not
value                                                                                                      the data file.

Add foreign key   Yes*                                                       No        Yes       Yes       The 'INPLACE'
constraint                                                                                                 algorithm is
                                                                                                           supported when
                                                                                                           'foreign_key_checks'
                                                                                                           is disabled.
                                                                                                           Otherwise, only the
                                                                                                           'COPY' algorithm is
                                                                                                           supported.

Drop foreign      Yes                                                        No        Yes       Yes       'foreign_key_checks'
key constraint                                                                                             can be enabled or
                                                                                                           disabled.

Rename column     Yes*                                                       No        Yes*      Yes       To permit concurrent
                                                                                                           DML, keep the same
                                                                                                           data type and only
                                                                                                           change the column
                                                                                                           name.
                                                                                                           'ALGORITHM=INPLACE'
                                                                                                           is not supported for
                                                                                                           renaming a generated
                                                                                                           column.

Add column        Yes*                                                       Yes*      Yes*      No        Concurrent DML is not
                                                                                                           permitted when adding
                                                                                                           an auto-increment
                                                                                                           column.  Data is
                                                                                                           reorganized
                                                                                                           substantially, making
                                                                                                           it an expensive
                                                                                                           operation.
                                                                                                           'ALGORITHM=INPLACE'
                                                                                                           is supported for
                                                                                                           adding a virtual
                                                                                                           generated column but
                                                                                                           not for adding a
                                                                                                           stored generated
                                                                                                           column.  Adding a
                                                                                                           virtual generated
                                                                                                           column does not
                                                                                                           require a table
                                                                                                           rebuild.

Drop column       Yes                                                        Yes*      Yes       No        Data is reorganized
                                                                                                           substantially, making
                                                                                                           it an expensive
                                                                                                           operation.
                                                                                                           'ALGORITHM=INPLACE'
                                                                                                           is supported for
                                                                                                           dropping a generated
                                                                                                           column.  Dropping a
                                                                                                           virtual generated
                                                                                                           column does not
                                                                                                           require a table
                                                                                                           rebuild.

Reorder columns   Yes                                                        Yes       Yes       No        Data is reorganized
                                                                                                           substantially, making
                                                                                                           it an expensive
                                                                                                           operation.

Change            Yes                                                        Yes       Yes       No        Data is reorganized
'ROW_FORMAT'                                                                                               substantially, making
property                                                                                                   it an expensive
                                                                                                           operation.

Change            Yes                                                        Yes       Yes       No        Data is reorganized
'KEY_BLOCK_SIZE'                                                                                           substantially, making
property                                                                                                   it an expensive
                                                                                                           operation.

Make column       Yes                                                        Yes*      Yes       No        Rebuilds the table in
'NULL'                                                                                                     place.  Data is
                                                                                                           reorganized
                                                                                                           substantially, making
                                                                                                           it an expensive
                                                                                                           operation.

Make column       Yes*                                                       Yes       Yes       No        Rebuilds the table in
'NOT NULL'                                                                                                 place.
                                                                                                           'STRICT_ALL_TABLES'
                                                                                                           or
                                                                                                           'STRICT_TRANS_TABLES'
                                                                                                           'SQL_MODE' is
                                                                                                           required for the
                                                                                                           operation to succeed.
                                                                                                           The operation fails
                                                                                                           if the column
                                                                                                           contains NULL values.
                                                                                                           The server prohibits
                                                                                                           changes to foreign
                                                                                                           key columns that have
                                                                                                           the potential to
                                                                                                           cause loss of
                                                                                                           referential
                                                                                                           integrity.  See
                                                                                                           alter-table.  Data
                                                                                                           is reorganized
                                                                                                           substantially, making
                                                                                                           it an expensive
                                                                                                           operation.

Change column     No*                                                        Yes       No        No        'VARCHAR'
size may be
                                                                                                           increased using
                                                                                                           online 'ALTER TABLE'.
                                                                                                           See
                                                                                                           innodb-online-ddl-column-properties
                                                                                                           for more information.

Add primary key   Yes*                                                       Yes*      Yes       No        Rebuilds the table in
                                                                                                           place.  Data is
                                                                                                           reorganized
                                                                                                           substantially, making
                                                                                                           it an expensive
                                                                                                           operation.
                                                                                                           'ALGORITHM=INPLACE'
                                                                                                           is not permitted
                                                                                                           under certain
                                                                                                           conditions if columns
                                                                                                           have to be converted
                                                                                                           to 'NOT NULL'.

Drop primary      Yes                                                        Yes       Yes       No        Data is reorganized
key and add                                                                                                substantially, making
another                                                                                                    it an expensive
                                                                                                           operation.

Drop primary      No                                                         Yes       No        No        Only 'ALGORITHM=COPY'
key                                                                                                        supports dropping a
                                                                                                           primary key without
                                                                                                           adding a new one in
                                                                                                           the same 'ALTER
                                                                                                           TABLE' statement.

Convert           No                                                         Yes*      No        No        Rebuilds the table if
character set                                                                                              the new character
                                                                                                           encoding is
                                                                                                           different.

Specify           No                                                         Yes*      No        No        Rebuilds the table if
character set                                                                                              the new character
                                                                                                           encoding is
                                                                                                           different.

Rebuild with      Yes*                                                       Yes       Yes       No        Uses
'FORCE' option                                                                                             'ALGORITHM=INPLACE'''.
                                                                                                           'ALGORITHM=INPLACE'
                                                                                                           is not supported for
                                                                                                           tables with
                                                                                                           'FULLTEXT' indexes.

'null' rebuild    Yes*                                                       Yes       Yes       No        Uses
using 'ALTER                                                                                               'ALGORITHM=INPLACE'.
TABLE ...                                                                                                  'ALGORITHM=INPLACE'
ENGINE=INNODB'                                                                                             is not supported for
                                                                                                           tables with
                                                                                                           'FULLTEXT' indexes.

Set               Yes                                                        No        Yes       Yes       Only modifies table
'STATS_PERSISTENT',                                                                                        metadata.
'STATS_AUTO_RECALC',
'STATS_SAMPLE_PAGES'
persistent
statistics
options

'ALTER TABLE      No                                                         Yes       No        Yes
... ENCRYPTION'

Drop a 'STORED'   Yes                                                        Yes*      Yes       No        Rebuilds the table in
column                                                                                                     place.

Modify 'STORED'   Yes                                                        Yes*      Yes       No        Rebuilds the table in
column order                                                                                               place.

Add a 'STORED'    Yes                                                        Yes*      Yes       No        Rebuilds the table in
column                                                                                                     place.

Drop a            Yes                                                        No        Yes       Yes
'VIRTUAL'
column

Modify            Yes                                                        No        Yes       Yes
'VIRTUAL'
column order

Add a 'VIRTUAL'   Yes                                                        No        Yes       Yes
column

The sections that follow provide basic syntax and usage notes for
various online DDL operations.

*Adding or Dropping Secondary Indexes*

   * Adding a secondary index:

          CREATE INDEX NAME ON TABLE (COL_LIST);

          ALTER TABLE TABLE ADD INDEX NAME (COL_LIST);

   * Dropping a secondary index:

          DROP INDEX NAME ON TABLE;

          ALTER TABLE TABLE DROP INDEX NAME;

Although no syntax changes are required in the 'CREATE INDEX'
or 'DROP INDEX' commands, some factors
affect the performance, space usage, and semantics of this operation
(see innodb-create-index-limitations).

Creating and dropping secondary indexes on 'InnoDB' tables skips the
table-copying behavior.

The table remains available for read and write operations while the
index is being created or dropped.  The 'CREATE INDEX'
or 'DROP INDEX' statement only finishes
after all transactions that are accessing the table are completed, so
that the initial state of the index reflects the most recent contents of
the table.  Previously, modifying the table while an index is being
created or dropped typically resulted in a deadlock that cancelled the
'INSERT', 'UPDATE', or 'DELETE'
statement on the table.

Online DDL support for adding secondary indexes means that you can
generally speed the overall process of creating and loading a table and
associated indexes by creating the table without any secondary indexes,
then adding the secondary indexes after the data is loaded.

*Modifying Column Properties*

   * Modify the default value for a column:

          ALTER TABLE TBL ALTER COLUMN COL SET DEFAULT LITERAL;

          ALTER TABLE TBL ALTER COLUMN COL DROP DEFAULT;

     The default values for columns are stored in the .frm file for the
     table, not the 'InnoDB' data dictionary.

   * Changing the auto-increment value for a column:

          ALTER TABLE TABLE AUTO_INCREMENT=NEXT_VALUE;

     Especially in a distributed system using replication or sharding,
     you sometimes reset the auto-increment counter for a table to a
     specific value.  The next row inserted into the table uses the
     specified value for its auto-increment column.  You might also use
     this technique in a data warehousing environment where you
     periodically empty all the tables and reload them, and you can
     restart the auto-increment sequence from 1.

   * Renaming a column:

          ALTER TABLE TBL CHANGE OLD_COL_NAME NEW_COL_NAME DATATYPE;

     When you keep the same data type and '[NOT] NULL' attribute, only
     changing the column name, this operation can always be performed
     online.

     You can also rename a column that is part of a foreign key
     constraint.  The foreign key definition is automatically updated to
     use the new column name.  Renaming a column participating in a
     foreign key only works with the in-place mode of 'ALTER TABLE'.
     If you use the 'ALGORITHM=COPY' clause, or
     some other condition causes the command to use 'ALGORITHM=COPY'
     behind the scenes, the 'ALTER TABLE' statement fails.

   * Extending 'VARCHAR' size using an in-place
     'ALTER TABLE' statement:

          ALTER TABLE t1 ALGORITHM=INPLACE, CHANGE COLUMN c1 c1 VARCHAR(255);

     The number of length bytes required by a 'VARCHAR'.
     column must remain the same.  For 'VARCHAR' values of
     0 to 255, one length byte is required to encode the value.  For
     'VARCHAR' values of 256 bytes or more, two length
     bytes are required.  As a result, in-place 'ALTER TABLE'
     only supports increasing 'VARCHAR' size
     from 0 to 255 bytes or increasing 'VARCHAR' size from
     a value equal to or greater than 256 bytes.  In-place 'ALTER TABLE'
     does not support increasing 'VARCHAR'
     size from less than 256 bytes to a value equal to or greater
     than 256 bytes.  In this case, the number of required length bytes
     would change from 1 to 2, which is only supported by a table copy
     ('ALGORITHM=COPY').  For example, attempting to change
     'VARCHAR' column size from 255 to 256 using in-place
     'ALTER TABLE' would return an error:

          ALTER TABLE t1 ALGORITHM=INPLACE, CHANGE COLUMN c1 c1 VARCHAR(256);
          ERROR 0A000: ALGORITHM=INPLACE is not supported. Reason: Cannot change
          column type INPLACE. Try ALGORITHM=COPY.

     Decreasing 'VARCHAR' size using in-place 'ALTER TABLE'
     is not supported.  Decreasing 'VARCHAR'
     size requires a table copy ('ALGORITHM=COPY').

*Adding or Dropping Foreign Keys*

   * Adding or dropping a foreign key constraint:

          ALTER TABLE TBL1 ADD CONSTRAINT FK_NAME FOREIGN KEY INDEX (COL1)
            REFERENCES TBL2(COL2) REFERENTIAL_ACTIONS;

          ALTER TABLE TBL DROP FOREIGN KEY FK_NAME;

     Dropping a foreign key can be performed online with the
     'foreign_key_checks' option enabled or disabled.  Creating a
     foreign key online requires 'foreign_key_checks' to be disabled.

     If you do not know the names of the foreign key constraints on a
     particular table, issue the following statement and find the
     constraint name in the 'CONSTRAINT' clause for each foreign key:

          SHOW CREATE TABLE TABLE\G

     Or, query the 'INFORMATION_SCHEMA.TABLE_CONSTRAINTS'
     table and use the 'CONSTRAINT_NAME' and
     'CONSTRAINT_TYPE' columns to identify the foreign key names.

     You can also drop a foreign key and its associated index in a
     single statement:

          ALTER TABLE TABLE DROP FOREIGN KEY CONSTRAINT, DROP INDEX INDEX;

If foreign keys are already present in the table being altered (that is,
it is a child table containing a 'FOREIGN KEY ... REFERENCE' clause),
additional restrictions apply to online DDL operations, even those not
directly involving the foreign key columns:

   * An 'ALTER TABLE' on the child table could wait
     for another transaction to commit, if a change to the parent table
     caused associated changes in the child table through an 'ON UPDATE'
     or 'ON DELETE' clause using the 'CASCADE' or 'SET NULL' parameters.

   * In the same way, if a table is the parent table in a foreign key
     relationship, even though it does not contain any 'FOREIGN KEY'
     clauses, it could wait for the 'ALTER TABLE' to
     complete if an 'INSERT', 'UPDATE', or
     'DELETE' statement caused an 'ON UPDATE' or 'ON
     DELETE' action in the child table.

*Maintaining CREATE TABLE Statements*

As your database schema evolves with new columns, data types,
constraints, indexes, and so on, keep your 'CREATE TABLE'
statements up to date with the latest table definitions.
Even with the performance improvements of online DDL, it is more
efficient to create stable database structures at the beginning, rather
than creating part of the schema and then issuing 'ALTER TABLE'
statements afterward.

The main exception to this guideline is for secondary indexes on tables
with large numbers of rows.  It is typically most efficient to create
the table with all details specified except the secondary indexes, load
the data, then create the secondary indexes.  You can use the same
technique with foreign keys (load the data first, then set up the
foreign keys) if you know the initial data is clean and do not need
consistency checks during the loading process.

Whatever sequence of 'CREATE TABLE', 'CREATE INDEX',
see 'ALTER TABLE', and similar
statements went into putting a table together, you can capture the SQL
needed to reconstruct the current form of the table by issuing the
statement 'SHOW CREATE TABLE TABLE\G' (uppercase '\G' required for tidy
formatting).  This output shows clauses such as numeric precision, 'NOT
NULL', and 'CHARACTER SET' that are sometimes added behind the scenes,
which you may want to leave out when cloning the table on a new system
or setting up foreign key columns with identical type.

14.13.2 Online DDL Performance, Concurrency, and Space Requirements
-------------------------------------------------------------------

Online DDL improves several aspects of MySQL operation, such as
performance, concurrency, availability, and scalability:

   * Because queries and DML operations on the table can proceed while
     the DDL is in progress, applications that access the table are more
     responsive.  Reduced locking and waiting for other resources
     throughout the MySQL server leads to greater scalability, even for
     operations not involving the table being altered.

   * For in-place operations, by avoiding the disk I/O and CPU cycles to
     rebuild the table, you minimize the overall load on the database
     and maintain good performance and high throughput during the DDL
     operation.

   * For in-place operations, because less data is read into the buffer
     pool than if all the data was copied, you avoid purging frequently
     accessed data from memory, which formerly could cause a temporary
     performance dip after a DDL operation.

If an online operation requires temporary sort files, 'InnoDB' creates
them in the temporary file directory by default, not the directory
containing the original table.  If this directory is not large enough to
hold such files, you may need to set the 'tmpdir' system variable to a
different directory.  Alternatively, you can define a separate temporary
directory for 'InnoDB' online 'ALTER TABLE'.
operations using the 'innodb_tmpdir' configuration option.  For more
information, see innodb-online-ddl-space-requirements, and
temporary-files.

*Locking Options for Online DDL*

While an InnoDB table is being changed by a DDL operation, the table may
or may not be locked, depending on the internal workings of that
operation and the 'LOCK' clause of the 'ALTER TABLE'.
statement.  By default, MySQL uses as little locking as possible during
a DDL operation; you specify the clause either to make the locking more
restrictive than it normally would be (thus limiting concurrent DML, or
DML and queries), or to ensure that some expected degree of locking is
allowed for an operation.  If the 'LOCK' clause specifies a level of
locking that is not available for that specific kind of DDL operation,
such as 'LOCK=SHARED' or 'LOCK=NONE' while creating or dropping a
primary key, the clause works like an assertion, causing the statement
to fail with an error.  The following list shows the different
possibilities for the 'LOCK' clause, from the most permissive to the
most restrictive:

   * For DDL operations with 'LOCK=NONE', both queries and concurrent
     DML are allowed.  This clause makes the 'ALTER TABLE'
     fail if the kind of DDL operation cannot be performed
     with the requested type of locking, so specify 'LOCK=NONE' if
     keeping the table fully available is vital and it is OK to cancel
     the DDL if that is not possible.  For example, you might use this
     clause in DDLs for tables involving customer signups or purchases,
     to avoid making those tables unavailable by mistakenly issuing an
     expensive 'ALTER TABLE' statement.

   * For DDL operations with 'LOCK=SHARED', any writes to the table
     (that is, DML operations) are blocked, but the data in the table
     can be read.  This clause makes the 'ALTER TABLE'
     fail if the kind of DDL operation cannot be performed
     with the requested type of locking, so specify 'LOCK=SHARED' if
     keeping the table available for queries is vital and it is OK to
     cancel the DDL if that is not possible.  For example, you might use
     this clause in DDLs for tables in a data warehouse, where it is OK
     to delay data load operations until the DDL is finished, but
     queries cannot be delayed for long periods.

   * For DDL operations with 'LOCK=DEFAULT', or with the 'LOCK' clause
     omitted, MySQL uses the lowest level of locking that is available
     for that kind of operation, allowing concurrent queries, DML, or
     both wherever possible.  This is the setting to use when making
     pre-planned, pre-tested changes that you know do not cause any
     availability problems based on the workload for that table.

   * For DDL operations with 'LOCK=EXCLUSIVE', both queries and DML
     operations are blocked.  This clause makes the 'ALTER TABLE'
     fail if the kind of DDL operation cannot be performed
     with the requested type of locking, so specify 'LOCK=EXCLUSIVE' if
     the primary concern is finishing the DDL in the shortest time
     possible, and it is OK to make applications wait when they try to
     access the table.  You might also use 'LOCK=EXCLUSIVE' if the
     server is supposed to be idle, to avoid unexpected accesses to the
     table.

In most cases, an online DDL operation on a table waits for currently
executing transactions that are accessing the table to commit or roll
back because it requires exclusive access to the table for a brief
period while the DDL statement is being prepared.  Likewise, the online
DDL operation requires exclusive access to the table for a brief time
before finishing.  Thus, an online DDL statement also waits for
transactions that are started while the DDL is in progress to commit or
roll back before completing.  Consequently, in the case of long running
transactions that perform inserts, updates, deletes, or 'SELECT ... FOR
UPDATE' operations on the table, it is possible for online DDL operation
to time out waiting for exclusive access to the table.

A case in which an online DDL operation on a table does not wait for a
currently executing transaction to complete can occur when the table is
in a foreign key relationship and a transaction is run explicitly on the
other table in the foreign key relationship.  In this case, the
transaction holds an exclusive metadata lock on the table it is
updating, but only holds shared 'InnoDB' table lock (required for
foreign key checking) on the other table.  The shared 'InnoDB' table
lock permits the online DDL operation to proceed but blocks the
operation at the commit phase, when an exclusive 'InnoDB' table lock is
required.  This scenario can result in deadlocks as other transactions
wait for the online DDL operation to commit.  (See Bug #48652, and Bug
#77390)

Because there is some processing work involved with recording the
changes made by concurrent DML operations, then applying those changes
at the end, an online DDL operation could take longer overall than the
old-style mechanism that blocks table access from other sessions.  The
reduction in raw performance is balanced against better responsiveness
for applications that use the table.  When evaluating the ideal
techniques for changing table structure, consider end-user perception of
performance, based on factors such as load times for web pages.

A newly created InnoDB secondary index contains only the committed data
in the table at the time the 'CREATE INDEX' or
'ALTER TABLE' statement finishes executing.  It does
not contain any uncommitted values, old versions of values, or values
marked for deletion but not yet removed from the old index.

*Performance of In-Place versus Table-Copying DDL Operations*

The raw performance of an online DDL operation is largely determined by
whether the operation is performed in-place, or requires copying and
rebuilding the entire table.  See innodb-online-ddl-summary-grid
to see what kinds of operations can be performed in-place, and any
requirements for avoiding table-copy operations.

The performance speedup from in-place DDL applies to operations on
secondary indexes, not to the primary key index.  The rows of an InnoDB
table are stored in a clustered index organized based on the primary
key, forming what some database systems call an 'index-organized table'.
Because the table structure is closely tied to the primary key,
redefining the primary key still requires copying the data.

When an operation on the primary key uses 'ALGORITHM=INPLACE', even
though the data is still copied, it is more efficient than using
'ALGORITHM=COPY' because:

   * No undo logging or associated redo logging is required for
     'ALGORITHM=INPLACE'.  These operations add overhead to DDL
     statements that use 'ALGORITHM=COPY'.

   * The secondary index entries are pre-sorted, and so can be loaded in
     order.

   * The change buffer is not used, because there are no random-access
     inserts into the secondary indexes.

To judge the relative performance of online DDL operations, you can run
such operations on a big 'InnoDB' table using current and earlier
versions of MySQL. You can also run all the performance tests under the
latest MySQL version, simulating the previous DDL behavior for the
'before' results, by setting the 'old_alter_table' system variable.
Issue the statement 'set old_alter_table=1' in the session, and measure
DDL performance to record the 'before' figures.  Then 'set
old_alter_table=0' to re-enable the newer, faster behavior, and run the
DDL operations again to record the 'after' figures.

For a basic idea of whether a DDL operation does its changes in-place or
performs a table copy, look at the 'rows affected' value displayed after
the command finishes.  For example, here are lines you might see after
doing different types of DDL operations:

   * Changing the default value of a column (super-fast, does not affect
     the table data at all):

          Query OK, 0 rows affected (0.07 sec)

   * Adding an index (takes time, but '0 rows affected' shows that the
     table is not copied):

          Query OK, 0 rows affected (21.42 sec)

   * Changing the data type of a column (takes substantial time and does
     require rebuilding all the rows of the table):

          Query OK, 1671168 rows affected (1 min 35.54 sec)

     *Note*:

     Changing the data type of a column requires rebuilding all the rows
     of the table with the exception of changing 'VARCHAR'.
     size, which may be performed using online 'ALTER TABLE'.
     See innodb-online-ddl-column-properties for
     more information.

For example, before running a DDL operation on a big table, you might
check whether the operation is fast or slow as follows:

  1. Clone the table structure.

  2. Populate the cloned table with a tiny amount of data.

  3. Run the DDL operation on the cloned table.

  4. Check whether the 'rows affected' value is zero or not.  A nonzero
     value means the operation requires rebuilding the entire table,
     which might require special planning.  For example, you might do
     the DDL operation during a period of scheduled downtime, or on each
     replication slave server one at a time.

For a deeper understanding of the reduction in MySQL processing, examine
the 'performance_schema' and 'INFORMATION_SCHEMA' tables related to
'InnoDB' before and after DDL operations, to see the number of physical
reads, writes, memory allocations, and so on.

*Space Requirements for Online DDL Operations*

Online DDL operations have the following space requirements:

   * Space for temporary log files

     There is one such log file for each index being created or table
     being altered.  This log file stores data inserted, updated, or
     deleted in the table during the DDL operation.  The temporary log
     file is extended when needed by the value of
     'innodb_sort_buffer_size', up to the maximum specified by
     'innodb_online_alter_log_max_size'.  If a temporary log file
     exceeds the upper size limit, the 'ALTER TABLE'.
     operation fails and all uncommitted concurrent DML operations are
     rolled back.  Thus, a large value for this option allows more DML
     to happen during an online DDL operation, but also extends the
     period of time at the end of the DDL operation when the table is
     locked to apply the data from the log.

     If the operation takes so long, and concurrent DML modifies the
     table so much, that the size of the temporary online log exceeds
     the value of the 'innodb_online_alter_log_max_size' configuration
     option, the online DDL operation fails with a
     'DB_ONLINE_LOG_TOO_BIG' error.

   * Space for temporary sort files

     Online DDL operations that rebuild the table write temporary sort
     files to the MySQL temporary directory ('$TMPDIR' on Unix, '%TEMP%'
     on Windows, or the directory specified by the '--tmpdir'
     configuration variable) during index creation.  Each temporary sort
     file is large enough to hold all columns defined for the new
     secondary index plus the columns that are part of the primary key
     of the clustered index, and each one is removed as soon as it is
     merged into the final table or index.  Such operations may require
     temporary space equal to the amount of data in the table plus
     indexes.  An online DDL operation that rebuilds the table can cause
     an error if the operation uses all of the available disk space on
     the file system where the data directory ('datadir') resides.

     As of MySQL 5.7.11, you can use the 'innodb_tmpdir' configuration
     option to define a separate temporary directory for online DDL
     operations.  The 'innodb_tmpdir' option was introduced to help
     avoid temporary directory overflows that could occur as a result of
     large temporary sort files created during online 'ALTER TABLE'
     operations that rebuild the table.

   * Space for an intermediate table file

     Some online DDL operations that rebuild the table create a
     temporary intermediate table file in the same directory as the
     original table as opposed to rebuilding the table in place.  An
     intermediate table file may require space equal to the size of the
     original table.  Operations that rebuild the table in place are
     noted in innodb-create-index-overview.

14.13.3 Online DDL SQL Syntax
-----------------------------

Typically, you do not need to do anything special to enable online DDL
when using the 'ALTER TABLE' statement for 'InnoDB'
tables.  See innodb-online-ddl-summary-grid for the kinds of DDL
operations that can be performed in-place, allowing concurrent DML, or
both.  Some variations require particular combinations of configuration
settings or 'ALTER TABLE' clauses.

You can control the various aspects of a particular online DDL operation
by using the 'LOCK' and 'ALGORITHM' clauses of the 'ALTER TABLE'
statement.  These clauses come at the end of the statement,
separated from the table and column specifications by commas.  The
'LOCK' clause is useful for fine-tuning the degree of concurrent access
to the table.  The 'ALGORITHM' clause is primarily intended for
performance comparisons and as a fallback to the older table-copying
behavior in case you encounter any issues with existing DDL code.  For
example:

   * To avoid accidentally making the table unavailable for reads,
     writes, or both, specify a clause on the 'ALTER TABLE'
     statement such as 'LOCK=NONE' (allow both reads and
     writes) or 'LOCK=SHARED' (allow reads).  The operation halts
     immediately if the requested level of concurrency is not available.

   * To compare performance, run one statement with 'ALGORITHM=INPLACE'
     and another with 'ALGORITHM=COPY', as an alternative to setting the
     'old_alter_table' configuration option.

   * To avoid tying up the server with an 'ALTER TABLE'
     operation that copies the table, include
     'ALGORITHM=INPLACE'.  The statement halts immediately if it cannot
     use the in-place mechanism.  See
     innodb-online-ddl-summary-grid for a list of the DDL operations
     that can or cannot be performed in-place.

See innodb-create-index-concurrency for more details about the
'LOCK' clause.

14.13.4 Simplifying DDL Statements with Online DDL
--------------------------------------------------

Before the introduction of online DDL, it was common practice to combine
many DDL operations into a single 'ALTER TABLE'.
statement.  Because each 'ALTER TABLE' statement
involved copying and rebuilding the table, it was more efficient to make
several changes to the same table at once, since those changes could all
be done with a single rebuild operation for the table.  The downside was
that SQL code involving DDL operations was harder to maintain and to
reuse in different scripts.  If the specific changes were different each
time, you might have to construct a new complex 'ALTER TABLE'
for each slightly different scenario.

For DDL operations that can be done in-place, as shown in
innodb-online-ddl-summary-grid, now you can separate them into
individual 'ALTER TABLE' statements for easier
scripting and maintenance, without sacrificing efficiency.  For example,
you might take a complicated statement such as:

     ALTER TABLE t1 ADD INDEX i1(c1), ADD UNIQUE INDEX i2(c2),
       CHANGE c4_old_name c4_new_name INTEGER UNSIGNED;

and break it down into simpler parts that can be tested and performed
independently, such as:

     ALTER TABLE t1 ADD INDEX i1(c1);
     ALTER TABLE t1 ADD UNIQUE INDEX i2(c2);
     ALTER TABLE t1 CHANGE c4_old_name c4_new_name INTEGER UNSIGNED NOT NULL;

You might still use multi-part 'ALTER TABLE'.
statements for:

   * Operations that must be performed in a specific sequence, such as
     creating an index followed by a foreign key constraint that uses
     that index.

   * Operations all using the same specific 'LOCK' clause, that you want
     to either succeed or fail as a group.

   * Operations that cannot be performed in-place, that is, that still
     copy and rebuild the table.

   * Operations for which you specify 'ALGORITHM=COPY' or
     'old_alter_table=1', to force the table-copying behavior if needed
     for precise backward-compatibility in specialized scenarios.

14.13.5 Online DDL Implementation Details
-----------------------------------------

Each 'ALTER TABLE' operation for an 'InnoDB' table
is governed by several aspects:

   * Whether there is any change to the physical representation of the
     table, or whether it purely a change to metadata that can be done
     without touching the table itself.

   * Whether the volume of data in the table stays the same, increases,
     or decreases.

   * Whether a change in table data involves the clustered index,
     secondary indexes, or both.

   * Whether there are any foreign key relationships between the table
     being altered and some other table.  The mechanics differ depending
     on whether the 'foreign_key_checks' configuration option is enabled
     or disabled.

   * Whether the table is partitioned.  Partitioning clauses of
     'ALTER TABLE' are turned into low-level operations
     involving one or more tables, and those operations follow the
     regular rules for online DDL.

   * Whether the table data must be copied, whether the table can be
     reorganized 'in-place', or a combination of both.

   * Whether the table contains any auto-increment columns.

   * What degree of locking is required, either by the nature of the
     underlying database operations, or a 'LOCK' clause that you specify
     in the 'ALTER TABLE' statement.

*Error Conditions for Online DDL*

Here are the primary reasons why an online DDL operation could fail:

   * If a 'LOCK' clause specifies a low degree of locking ('SHARED' or
     'NONE') that is not compatible with the particular type of DDL
     operation.

   * If a timeout occurs while waiting to get an exclusive lock on the
     table, which may be needed briefly during the initial and final
     phases of the DDL operation.

   * If the 'tmpdir' or 'innodb_tmpdir' file system runs out of disk
     space, while MySQL writes temporary sort files on disk during index
     creation.  For more information, see temporary-files.

   * If the 'ALTER TABLE' takes so long, and
     concurrent DML modifies the table so much, that the size of the
     temporary online log exceeds the value of the
     'innodb_online_alter_log_max_size' configuration option.  This
     condition causes a 'DB_ONLINE_LOG_TOO_BIG' error.

   * If concurrent DML makes changes to the table that are allowed with
     the original table definition, but not with the new one.  The
     operation only fails at the very end, when MySQL tries to apply all
     the changes from concurrent DML statements.  For example, you might
     insert duplicate values into a column while a unique index is being
     created, or you might insert 'NULL' values into a column while
     creating a primary key index on that column.  The changes made by
     the concurrent DML take precedence, and the 'ALTER TABLE'
     operation is effectively rolled back.

Although the configuration option 'innodb_file_per_table' has a dramatic
effect on the representation for an 'InnoDB' table, all online DDL
operations work equally well whether that option is enabled or disabled,
and whether the table is physically located in its own .ibd file or
inside the system tablespace.

InnoDB has two types of indexes: the clustered index representing all
the data in the table, and optional secondary indexes to speed up
queries.  Since the clustered index contains the data values in its
B-tree nodes, adding or dropping a clustered index does involve copying
the data, and creating a new copy of the table.  A secondary index,
however, contains only the index key and the value of the primary key.
This type of index can be created or dropped without copying the data in
the clustered index.  Because each secondary index contains copies of
the primary key values (used to access the clustered index when needed),
when you change the definition of the primary key, all secondary indexes
are recreated as well.

Dropping a secondary index is simple.  Only the internal InnoDB system
tables and the MySQL data dictionary tables are updated to reflect the
fact that the index no longer exists.  InnoDB returns the storage used
for the index to the tablespace that contained it, so that new indexes
or additional table rows can use the space.

To add a secondary index to an existing table, InnoDB scans the table,
and sorts the rows using memory buffers and temporary files in order by
the values of the secondary index key columns.  The B-tree is then built
in key-value order, which is more efficient than inserting rows into an
index in random order.  Because the B-tree nodes are split when they
fill, building the index in this way results in a higher fill-factor for
the index, making it more efficient for subsequent access.

14.13.6 Online DDL and Crash Recovery
-------------------------------------

Although no data is lost if the server crashes while an 'ALTER TABLE'
statement is executing, the crash recovery process
is different for clustered indexes and secondary indexes.

If the server crashes while creating an InnoDB secondary index, upon
recovery, MySQL drops any partially created indexes.  You must re-run
the 'ALTER TABLE' or 'CREATE INDEX'
statement.

When a crash occurs during the creation of an InnoDB clustered index,
recovery is more complicated, because the data in the table must be
copied to an entirely new clustered index.  Remember that all InnoDB
tables are stored as clustered indexes.

MySQL creates the new clustered index by copying the existing data from
the original InnoDB table to a temporary table that has the desired
index structure.  Once the data is completely copied to this temporary
table, the original table is renamed with a different temporary table
name.  The temporary table comprising the new clustered index is renamed
with the name of the original table, and the original table is dropped
from the database.

If a system crash occurs while creating a new clustered index, no data
is lost, but you must complete the recovery process using the temporary
tables that exist during the process.  Since it is rare to re-create a
clustered index or re-define primary keys on large tables, or to
encounter a system crash during this operation, this manual does not
provide information on recovering from this scenario.

14.13.7 Online DDL for Partitioned Tables
-----------------------------------------

Most 'ALTER TABLE' partitioning clauses do not go
through the same internal online DDL API as regular non-partitioned
'InnoDB' tables.  As a result, online support for 'ALTER TABLE'
partitioning clauses varies.

The following table shows the online status for each 'ALTER TABLE'
partitioning statement.  Regardless of the online DDL API that is used,
MySQL attempts to minimize data copying and locking where possible.

   * The 'In-Place?' column shows which operations permit the
     'ALGORITHM=INPLACE' clause.

   * The 'Permits Concurrent DML?' column shows which operations are
     performed fully online.  You can specify 'LOCK=NONE' to assert that
     concurrent DML is permitted during the DDL operation.  MySQL
     automatically permits concurrent DML when possible.

     For operations that support 'ALGORITHM={COPY|INPLACE}', you can
     specify 'LOCK=SHARED' to assert that concurrent queries are
     permitted during a DDL operation.  MySQL automatically permits
     concurrent queries where possible.

   * The 'Notes' column provides additional information and explains
     exceptions and dependencies related to the 'Yes/No' values of other
     columns.  An asterisk indicates an exception or dependency.

'ALTER TABLE' partitioning options that use
'ALGORITHM=COPY' or that only permit ''ALGORITHM=DEFAULT,
LOCK=DEFAULT'', repartition the table using the 'COPY' algorithm.  In
other words, a new partitioned table is created with the new
partitioning scheme.  The newly created table includes any changes
applied by the 'ALTER TABLE' statement, and table
data is copied into the new table structure.

*Online Status for ALTER TABLE Partitioning Clauses*

Partitioning      In Place?                                                  Permits   Notes
Clause                                                                       Concurrent
                                                                             DML?

See No No Permits 'PARTITION BY',
alter-table.                                                                           'LOCK={DEFAULT|SHARED|EXCLUSIVE}'

See 'ADD No No Only permits PARTITION',
alter-table.                                                                           'LOCK=DEFAULT'.  Does
                                                                                       not copy existing
                                                                                       data for tables
                                                                                       partitioned by
                                                                                       'RANGE' or 'LIST'.
                                                                                       Concurrent queries
                                                                                       are permitted for
                                                                                       tables partitioned by
                                                                                       'HASH' or 'LIST'.
                                                                                       MySQL copies the data
                                                                                       while holding a
                                                                                       shared lock.

See 'DROP No No Only permits PARTITION',
alter-table.                                                                           'LOCK=DEFAULT'.  Does
                                                                                       not copy existing
                                                                                       data for tables
                                                                                       partitioned by
                                                                                       'RANGE' or 'LIST'.

See 'DISCARD No No Only permits PARTITION',
alter-table.                                                                           'LOCK=DEFAULT'

See 'IMPORT No No Only permits PARTITION',
alter-table.                                                                           'LOCK=DEFAULT'

See 'TRUNCATE Yes Yes Does not copy PARTITION'.
It
alter-table.                                                                           merely deletes rows;
                                                                                       it does not alter the
                                                                                       definition of the
                                                                                       table itself, or of
                                                                                       any of its
                                                                                       partitions.

See 'COALESCE No No Only permits PARTITION',
alter-table.                                                                           'LOCK=DEFAULT'.
                                                                                       Concurrent queries
                                                                                       are permitted for
                                                                                       tables partitioned by
                                                                                       'HASH' or 'LIST', as
                                                                                       MySQL copies the data
                                                                                       while holding a
                                                                                       shared lock.

*note             No                                                         No        Only permits
'REORGANIZE                                                                            'ALGORITHM=DEFAULT',
PARTITION':                                                                            'LOCK=DEFAULT'.
alter-table.                                                                           Concurrent queries
                                                                                       are permitted for
                                                                                       tables partitioned by
                                                                                       'LINEAR HASH' or
                                                                                       'LIST'.  MySQL copies
                                                                                       data from affected
                                                                                       partitions while
                                                                                       holding a shared
                                                                                       metadata lock.

See 'EXCHANGE Yes Yes PARTITION'.

See 'ANALYZE Yes Yes PARTITION'.

See 'CHECK Yes Yes PARTITION'.

See 'OPTIMIZE No No 'ALGORITHM' and PARTITION'.
                                                                   ignored.  Rebuilds
                                                                                       the entire table.
                                                                                       See
                                                                                       partitioning-maintenance.

See 'REBUILD No No Only permits PARTITION',
alter-table.                                                                           'LOCK=DEFAULT'.
                                                                                       Concurrent queries
                                                                                       are permitted for
                                                                                       tables partitioned by
                                                                                       'LINEAR HASH' or
                                                                                       'LIST'.  MySQL copies
                                                                                       data from affected
                                                                                       partitions while
                                                                                       holding a shared
                                                                                       metadata lock.

See 'REPAIR Yes Yes PARTITION'.

See 'REMOVE No No Permits PARTITIONING',
alter-table.                                                                           'LOCK={DEFAULT|SHARED|EXCLUSIVE}'

Non-partitioning online 'ALTER TABLE' operations on
partitioned tables follow the same rules that apply to regular tables.
However, see 'ALTER TABLE' performs online operations on
each table partition, which causes increased demand on system resources
due to operations being performed on multiple partitions.

For additional information about 'ALTER TABLE'.
partitioning clauses, see alter-table-partition-options, and
alter-table-partition-operations.  For information about
partitioning in general, see partitioning.

14.13.8 Online DDL Limitations
------------------------------

The following limitations apply to online DDL operations:

   * The table is copied, rather than using Fast Index Creation when you
     create an index on a 'TEMPORARY TABLE'.  This has been reported as
     MySQL Bug #39833.

   * InnoDB handles error cases when users attempt to drop indexes
     needed for foreign keys.  See error-messages-server for
     information related to error '1553'.

   * The 'ALTER TABLE' clause 'LOCK=NONE' is not
     allowed if there are 'ON...CASCADE' or 'ON...SET NULL' constraints
     on the table.

   * Depending on the internal workings of the online DDL operation and
     the 'LOCK' clause of the 'ALTER TABLE' statement, an online DDL
     operation may require exclusive access to the table for a brief
     time during the initial and final phases of the DDL operation.
     Thus, an online DDL operation might wait before finishing if there
     is a long-running transaction performing inserts, updates, deletes,
     or 'SELECT ... FOR UPDATE' on the table; and an online DDL
     operation might wait before finishing if a similar long-running
     transaction is started while the 'ALTER TABLE'.
     is in progress.

   * When running an online DDL operation, the thread that runs the
     'ALTER TABLE' statement applies an 'online log'
     of DML operations that were run concurrently on the same table from
     other connection threads.  When the DML operations are applied, it
     is possible to encounter a duplicate key entry error ('ERROR 1062
     (23000): Duplicate entry'), even if the duplicate entry is only
     temporary and would be reverted by a later entry in the 'online
     log'.  This is similar to the idea of a foreign key constraint
     check in 'InnoDB' in which constraints must hold during a
     transaction.

   * 'OPTIMIZE TABLE' for an 'InnoDB' table is
     mapped to an 'ALTER TABLE' operation to rebuild
     the table and update index statistics and free unused space in the
     clustered index.  Secondary indexes are not created as efficiently
     because keys are inserted in the order they appeared in the primary
     key.  'OPTIMIZE TABLE' is supported with the
     addition of online DDL support for
     rebuilding regular and partitioned 'InnoDB' tables.  For additional
     information, see innodb-create-index-overview.

   * 'InnoDB' tables created before MySQL 5.6 do not support
     'ALTER TABLE ... ALGORITHM=INPLACE' for tables that
     include temporal columns (see 'DATE', 'DATETIME'
     or 'TIMESTAMP') and have not been
     rebuilt using 'ALTER TABLE ... ALGORITHM=COPY'.
     In this case, an 'ALTER TABLE ... ALGORITHM=INPLACE'
     operation returns the following error:

          ERROR 1846 (0A000): ALGORITHM=INPLACE is not supported.
          Reason: Cannot change column type INPLACE. Try ALGORITHM=COPY.

   * These limitations are generally applicable to online DDL operations
     on large tables where table copying is involved:

        * There is no mechanism to pause an online DDL operation or to
          throttle I/O or CPU usage for an online DDL operation.

        * Rollback of an online DDL operation can be expensive should
          the operation fail.

        * Long running online DDL operations can cause replication lag.
          An online DDL operation must finish running on the master
          before it is run on the slave.  Also, DML that was processed
          concurrently on the master is only processed on the slave
          after the DDL operation on the slave is completed (Bug
          #73196).

     For additional information related to running online DDL operations
     on large tables, see innodb-create-index-concurrency.

14.14 InnoDB Startup Options and System Variables
=================================================

   * System variables that are true or false can be enabled at server
     startup by naming them, or disabled by using a '--skip-' prefix.
     For example, to enable or disable the 'InnoDB' adaptive hash index,
     you can use '--innodb_adaptive_hash_index' or
     '--skip-innodb_adaptive_hash_index' on the command line, or
     'innodb_adaptive_hash_index' or 'skip-innodb_adaptive_hash_index'
     in an option file.

   * System variables that take a numeric value can be specified as
     '--VAR_NAME=VALUE' on the command line or as 'VAR_NAME=VALUE' in
     option files.

   * Many system variables can be changed at runtime (see
     dynamic-system-variables).

   * For information about 'GLOBAL' and 'SESSION' variable scope
     modifiers, refer to the 'SET' statement
     documentation.

   * Certain options control the locations and layout of the 'InnoDB'
     data files.  innodb-init-startup-configuration explains how
     to use these options.

   * Some options, which you might not use initially, help tune 'InnoDB'
     performance characteristics based on machine capacity and your
     database workload.

   * For more information on specifying options and system variables,
     see program-options.

*InnoDB Option and Variable Reference*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

daemon_memcached_enable_binlogYesYes   Yes                     Global      No

daemon_memcached_engine_lib_nameYesYes Yes                     Global      No

daemon_memcached_engine_lib_pathYesYes Yes                     Global      No

daemon_memcached_optionYes Yes         Yes                     Global      No

daemon_memcached_r_batch_sizeYesYes    Yes                     Global      No

daemon_memcached_w_batch_sizeYesYes    Yes                     Global      No

foreign_key_checks                     Yes                     Both        Yes

ignore-builtin-innodbYes   Yes                                 Global      No

-                                      Yes                     Global      No
_Variable_:
ignore_builtin_innodb

innodb         Yes         Yes

innodb_adaptive_flushingYesYes         Yes                     Global      Yes

innodb_adaptive_flushing_lwmYesYes     Yes                     Global      Yes

innodb_adaptive_hash_indexYesYes       Yes                     Global      Yes

innodb_adaptive_hash_index_partsYesYes Yes                     Global      No

innodb_adaptive_max_sleep_delayYesYes  Yes                     Global      Yes

innodb_additional_mem_pool_sizeYesYes  Yes                     Global      No

innodb_api_bk_commit_intervalYesYes    Yes                     Global      Yes

innodb_api_disable_rowlockYesYes       Yes                     Global      No

innodb_api_enable_binlogYesYes         Yes                     Global      No

innodb_api_enable_mdlYes   Yes         Yes                     Global      No

innodb_api_trx_levelYes    Yes         Yes                     Global      Yes

innodb_autoextend_incrementYesYes      Yes                     Global      Yes

innodb_autoinc_lock_modeYesYes         Yes                     Global      No

Innodb_available_undo_logs                         Yes         Global      No

innodb_background_drop_list_emptyYesYesYes                     Global      Yes

Innodb_buffer_pool_bytes_data                      Yes         Global      No

Innodb_buffer_pool_bytes_dirty                     Yes         Global      No

innodb_buffer_pool_chunk_sizeYesYes    Yes                     Global      No

innodb_buffer_pool_dump_at_shutdownYesYesYes                   Global      Yes

innodb_buffer_pool_dump_nowYesYes      Yes                     Global      Yes

innodb_buffer_pool_dump_pctYesYes      Yes                     Global      Yes

Innodb_buffer_pool_dump_status                     Yes         Global      No

innodb_buffer_pool_filenameYesYes      Yes                     Global      Yes

innodb_buffer_pool_instancesYesYes     Yes                     Global      No

innodb_buffer_pool_load_abortYesYes    Yes                     Global      Yes

innodb_buffer_pool_load_at_startupYesYesYes                    Global      No

innodb_buffer_pool_load_nowYesYes      Yes                     Global      Yes

Innodb_buffer_pool_load_status                     Yes         Global      No

Innodb_buffer_pool_pages_data                      Yes         Global      No

Innodb_buffer_pool_pages_dirty                     Yes         Global      No

Innodb_buffer_pool_pages_flushed                   Yes         Global      No

Innodb_buffer_pool_pages_free                      Yes         Global      No

Innodb_buffer_pool_pages_latched                   Yes         Global      No

Innodb_buffer_pool_pages_misc                      Yes         Global      No

Innodb_buffer_pool_pages_total                     Yes         Global      No

Innodb_buffer_pool_read_ahead                      Yes         Global      No

Innodb_buffer_pool_read_ahead_evicted              Yes         Global      No

Innodb_buffer_pool_read_ahead_rnd                  Yes         Global      No

Innodb_buffer_pool_read_requests                   Yes         Global      No

Innodb_buffer_pool_reads                           Yes         Global      No

Innodb_buffer_pool_resize_status                   Yes         Global      No

innodb_buffer_pool_sizeYes Yes         Yes                     Global      Varies

Innodb_buffer_pool_wait_free                       Yes         Global      No

Innodb_buffer_pool_write_requests                  Yes         Global      No

innodb_change_buffer_max_sizeYesYes    Yes                     Global      Yes

innodb_change_bufferingYes Yes         Yes                     Global      Yes

innodb_change_buffering_debugYesYes    Yes                     Global      Yes

innodb_checksum_algorithmYesYes        Yes                     Global      Yes

innodb_checksumsYes        Yes         Yes                     Global      No

innodb_cmp_per_index_enabledYesYes     Yes                     Global      Yes

innodb_commit_concurrencyYesYes        Yes                     Global      Yes

innodb_compress_debugYes   Yes         Yes                     Global      Yes

innodb_compression_failure_threshold_pctYesYesYes              Global      Yes

innodb_compression_levelYesYes         Yes                     Global      Yes

innodb_compression_pad_pct_maxYesYes   Yes                     Global      Yes

innodb_concurrency_ticketsYesYes       Yes                     Global      Yes

innodb_data_file_pathYes   Yes         Yes                     Global      No

Innodb_data_fsyncs                                 Yes         Global      No

innodb_data_home_dirYes    Yes         Yes                     Global      No

Innodb_data_pending_fsyncs                         Yes         Global      No

Innodb_data_pending_reads                          Yes         Global      No

Innodb_data_pending_writes                         Yes         Global      No

Innodb_data_read                                   Yes         Global      No

Innodb_data_reads                                  Yes         Global      No

Innodb_data_writes                                 Yes         Global      No

Innodb_data_written                                Yes         Global      No

Innodb_dblwr_pages_written                         Yes         Global      No

Innodb_dblwr_writes                                Yes         Global      No

innodb_default_row_formatYesYes        Yes                     Global      Yes

innodb_disable_resize_buffer_pool_debugYesYesYes               Global      Yes

innodb_disable_sort_file_cacheYesYes   Yes                     Global      Yes

innodb_doublewriteYes      Yes         Yes                     Global      No

innodb_fast_shutdownYes    Yes         Yes                     Global      Yes

innodb_fil_make_page_dirty_debugYesYes Yes                     Global      Yes

innodb_file_formatYes      Yes         Yes                     Global      Yes

innodb_file_format_checkYesYes         Yes                     Global      No

innodb_file_format_maxYes  Yes         Yes                     Global      Yes

innodb_file_per_tableYes   Yes         Yes                     Global      Yes

innodb_fill_factorYes      Yes         Yes                     Global      Yes

innodb_flush_log_at_timeout            Yes                     Global      Yes

innodb_flush_log_at_trx_commitYesYes   Yes                     Global      Yes

innodb_flush_methodYes     Yes         Yes                     Global      No

innodb_flush_neighborsYes  Yes         Yes                     Global      Yes

innodb_flush_syncYes       Yes         Yes                     Global      Yes

innodb_flushing_avg_loopsYesYes        Yes                     Global      Yes

innodb_force_load_corruptedYesYes      Yes                     Global      No

innodb_force_recoveryYes   Yes         Yes                     Global      No

innodb_ft_aux_tableYes     Yes         Yes                     Global      Yes

innodb_ft_cache_sizeYes    Yes         Yes                     Global      No

innodb_ft_enable_diag_printYesYes      Yes                     Global      Yes

innodb_ft_enable_stopwordYesYes        Yes                     Global      Yes

innodb_ft_max_token_sizeYesYes         Yes                     Global      No

innodb_ft_min_token_sizeYesYes         Yes                     Global      No

innodb_ft_num_word_optimizeYesYes      Yes                     Global      Yes

innodb_ft_result_cache_limitYesYes     Yes                     Global      Yes

innodb_ft_server_stopword_tableYesYes  Yes                     Global      Yes

innodb_ft_sort_pll_degreeYesYes        Yes                     Global      No

innodb_ft_total_cache_sizeYesYes       Yes                     Global      No

innodb_ft_user_stopword_tableYesYes    Yes                     Both        Yes

Innodb_have_atomic_builtins                        Yes         Global      No

innodb_io_capacityYes      Yes         Yes                     Global      Yes

innodb_io_capacity_maxYes  Yes         Yes                     Global      Yes

innodb_large_prefixYes     Yes         Yes                     Global      Yes

innodb_limit_optimistic_insert_debugYesYesYes                  Global      Yes

innodb_lock_wait_timeoutYesYes         Yes                     Both        Yes

innodb_locks_unsafe_for_binlogYesYes   Yes                     Global      No

innodb_log_buffer_sizeYes  Yes         Yes                     Global      No

innodb_log_checksum_algorithmYesYes    Yes                     Global      Yes

innodb_log_checksumsYes    Yes         Yes                     Global      Yes

innodb_log_compressed_pagesYesYes      Yes                     Global      Yes

innodb_log_file_sizeYes    Yes         Yes                     Global      No

innodb_log_files_in_groupYesYes        Yes                     Global      No

innodb_log_group_home_dirYesYes        Yes                     Global      No

Innodb_log_waits                                   Yes         Global      No

innodb_log_write_ahead_sizeYesYes      Yes                     Global      Yes

Innodb_log_write_requests                          Yes         Global      No

Innodb_log_writes                                  Yes         Global      No

innodb_lru_scan_depthYes   Yes         Yes                     Global      Yes

innodb_max_dirty_pages_pctYesYes       Yes                     Global      Yes

innodb_max_dirty_pages_pct_lwmYesYes   Yes                     Global      Yes

innodb_max_purge_lagYes    Yes         Yes                     Global      Yes

innodb_max_purge_lag_delayYesYes       Yes                     Global      Yes

innodb_max_undo_log_sizeYesYes         Yes                     Global      Yes

innodb_merge_threshold_set_all_debugYesYesYes                  Global      Yes

innodb_monitor_disableYes  Yes         Yes                     Global      Yes

innodb_monitor_enableYes   Yes         Yes                     Global      Yes

innodb_monitor_resetYes    Yes         Yes                     Global      Yes

innodb_monitor_reset_allYesYes         Yes                     Global      Yes

Innodb_num_open_files                              Yes         Global      No

innodb_numa_interleaveYes  Yes         Yes                     Global      No

innodb_old_blocks_pctYes   Yes         Yes                     Global      Yes

innodb_old_blocks_timeYes  Yes         Yes                     Global      Yes

innodb_online_alter_log_max_sizeYesYes Yes                     Global      Yes

innodb_open_filesYes       Yes         Yes                     Global      No

innodb_optimize_fulltext_onlyYesYes    Yes                     Global      Yes

innodb_optimize_point_storageYesYes    Yes                     Session     Yes

Innodb_os_log_fsyncs                               Yes         Global      No

Innodb_os_log_pending_fsyncs                       Yes         Global      No

Innodb_os_log_pending_writes                       Yes         Global      No

Innodb_os_log_written                              Yes         Global      No

innodb_page_cleanersYes    Yes         Yes                     Global      No

Innodb_page_size                                   Yes         Global      No

innodb_page_sizeYes        Yes         Yes                     Global      No

Innodb_pages_created                               Yes         Global      No

Innodb_pages_read                                  Yes         Global      No

Innodb_pages_written                               Yes         Global      No

innodb_print_all_deadlocksYesYes       Yes                     Global      Yes

innodb_purge_batch_sizeYes Yes         Yes                     Global      Yes

innodb_purge_rseg_truncate_frequencyYesYesYes                  Global      Yes

innodb_purge_threadsYes    Yes         Yes                     Global      No

innodb_random_read_aheadYesYes         Yes                     Global      Yes

innodb_read_ahead_thresholdYesYes      Yes                     Global      Yes

innodb_read_io_threadsYes  Yes         Yes                     Global      No

innodb_read_onlyYes        Yes         Yes                     Global      No

innodb_replication_delayYesYes         Yes                     Global      Yes

innodb_rollback_on_timeoutYesYes       Yes                     Global      No

innodb_rollback_segmentsYesYes         Yes                     Global      Yes

Innodb_row_lock_current_waits                      Yes         Global      No

Innodb_row_lock_time                               Yes         Global      No

Innodb_row_lock_time_avg                           Yes         Global      No

Innodb_row_lock_time_max                           Yes         Global      No

Innodb_row_lock_waits                              Yes         Global      No

Innodb_rows_deleted                                Yes         Global      No

Innodb_rows_inserted                               Yes         Global      No

Innodb_rows_read                                   Yes         Global      No

Innodb_rows_updated                                Yes         Global      No

innodb_saved_page_number_debugYesYes   Yes                     Global      Yes

innodb_sort_buffer_sizeYes Yes         Yes                     Global      No

innodb_spin_wait_delayYes  Yes         Yes                     Global      Yes

innodb_stats_auto_recalcYesYes         Yes                     Global      Yes

innodb_stats_include_delete_markedYesYesYes                    Global      Yes

innodb_stats_methodYes     Yes         Yes                     Global      Yes

innodb_stats_on_metadataYesYes         Yes                     Global      Yes

innodb_stats_persistentYes Yes         Yes                     Global      Yes

innodb_stats_persistent_sample_pagesYesYesYes                  Global      Yes

innodb_stats_sample_pagesYesYes        Yes                     Global      Yes

innodb_stats_transient_sample_pagesYesYesYes                   Global      Yes

innodb-status-fileYes      Yes

innodb_status_outputYes    Yes         Yes                     Global      Yes

innodb_status_output_locksYesYes       Yes                     Global      Yes

innodb_strict_modeYes      Yes         Yes                     Both        Yes

innodb_support_xaYes       Yes         Yes                     Both        Yes

innodb_sync_array_sizeYes  Yes         Yes                     Global      No

innodb_sync_debugYes       Yes         Yes                     Global      No

innodb_sync_spin_loopsYes  Yes         Yes                     Global      Yes

innodb_table_locksYes      Yes         Yes                     Both        Yes

innodb_temp_data_file_pathYesYes       Yes                     Global      No

innodb_thread_concurrencyYesYes        Yes                     Global      Yes

innodb_thread_sleep_delayYesYes        Yes                     Global      Yes

innodb_tmpdir  Yes         Yes         Yes                     Both        Yes

Innodb_truncated_status_writes                     Yes         Global      No

innodb_trx_purge_view_update_only_debugYesYesYes               Global      Yes

innodb_trx_rseg_n_slots_debugYesYes    Yes                     Global      Yes

innodb_undo_directoryYes   Yes         Yes                     Global      No

innodb_undo_log_truncateYesYes         Yes                     Global      Yes

innodb_undo_logsYes        Yes         Yes                     Global      Yes

innodb_undo_tablespacesYes Yes         Yes                     Global      No

innodb_use_native_aioYes   Yes         Yes                     Global      No

innodb_use_sys_mallocYes   Yes         Yes                     Global      No

innodb_version                         Yes                     Global      No

innodb_write_io_threadsYes Yes         Yes                     Global      No

timed_mutexes  Yes         Yes         Yes                     Global      Yes

unique_checks                          Yes                     Both        Yes

*InnoDB Command Options*

   *
     '--ignore-builtin-innodb'

     Property                             Value

     *Command-Line Format*                '--ignore-builtin-innodb'

     *Deprecated*                         Yes

     *System Variable*                    'ignore_builtin_innodb'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     In MySQL 5.1, this option caused the server to behave as if the
     built-in 'InnoDB' were not present, which enabled the 'InnoDB
     Plugin' to be used instead.  In MySQL 5.7, 'InnoDB' is the default
     storage engine and 'InnoDB Plugin' is not used, so this option is
     ignored.

   *
     '--innodb[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--innodb[=value]'

     *Deprecated*                         5.7.5

     *Type*                               enumeration

     *Default Value*                      'ON'

     *Valid Values*                       'OFF' 'ON' 'FORCE'

     Controls loading of the 'InnoDB' storage engine, if the server was
     compiled with 'InnoDB' support.  This option has a tristate format,
     with possible values of 'OFF', 'ON', or 'FORCE'.  See
     server-plugin-loading.

     To disable 'InnoDB', use '--innodb=OFF' or '--skip-innodb'.  In
     this case, because the default storage engine is 'InnoDB',
     the server does not start unless you also
     use '--default-storage-engine' and '--default-tmp-storage-engine'
     to set the default to some other engine for both permanent and
     'TEMPORARY' tables.

     The 'InnoDB' storage engine can no longer be disabled, and the
     '--innodb=OFF' and '--skip-innodb' options are deprecated and have
     no effect.  Their use results in a warning.  These options will be
     removed in a future MySQL release.

   *
     '--innodb-status-file'

     Property                             Value

     *Command-Line Format*                '--innodb-status-file'

     *Type*                               boolean

     *Default Value*                      'OFF'

     Controls whether 'InnoDB' creates a file named 'innodb_status.PID'
     in the MySQL data directory.  If enabled, 'InnoDB' periodically
     writes the output of 'SHOW ENGINE INNODB STATUS'
     to this file.

     By default, the file is not created.  To create it, start
     'mysqld' with the '--innodb-status-file=1' option.  The
     file is deleted during normal shutdown.

   *
     '--skip-innodb'

     Disable the 'InnoDB' storage engine.  See the description of
     '--innodb'.

*InnoDB System Variables*

   *
     'daemon_memcached_enable_binlog'

     Property                             Value

     *Command-Line Format*                '--daemon-memcached-enable-binlog=#'

     *System Variable*                    'daemon_memcached_enable_binlog'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'false'

     Enable this option on the master server to use the 'InnoDB'
     'memcached' plugin ('daemon_memcached') with the MySQL binary log.
     This option can only be set at server startup.  You must also
     enable the MySQL binary log on the master server using the
     '--log-bin' option.

     For more information, see innodb-memcached-replication.

   *
     'daemon_memcached_engine_lib_name'

     Property                             Value

     *Command-Line Format*                '--daemon-memcached-engine-lib-name=library'

     *System Variable*                    'daemon_memcached_engine_lib_name'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'innodb_engine.so'

     Specifies the shared library that implements the 'InnoDB'
     'memcached' plugin.

     For more information, see innodb-memcached-setup.

   *
     'daemon_memcached_engine_lib_path'

     Property                             Value

     *Command-Line Format*                '--daemon-memcached-engine-lib-path=directory'

     *System Variable*                    'daemon_memcached_engine_lib_path'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     *Default Value*                      'NULL'

     The path of the directory containing the shared library that
     implements the 'InnoDB' 'memcached' plugin.  The default value is
     NULL, representing the MySQL plugin directory.  You should not need
     to modify this parameter unless specifying a 'memcached' plugin for
     a different storage engine that is located outside of the MySQL
     plugin directory.

     For more information, see innodb-memcached-setup.

   *
     'daemon_memcached_option'

     Property                             Value

     *Command-Line Format*                '--daemon-memcached-option=options'

     *System Variable*                    'daemon_memcached_option'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      ''

     Used to pass space-separated memcached options to the underlying
     'memcached' memory object caching daemon on startup.  For example,
     you might change the port that 'memcached' listens on, reduce the
     maximum number of simultaneous connections, change the maximum
     memory size for a key/value pair, or enable debugging messages for
     the error log.

     See innodb-memcached-setup for usage details.  For
     information about 'memcached' options, refer to the 'memcached' man
     page.

   *
     'daemon_memcached_r_batch_size'

     Property                             Value

     *Command-Line Format*                '--daemon-memcached-r-batch-size=#'

     *System Variable*                    'daemon_memcached_r_batch_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1'

     Specifies how many 'memcached' read operations ('get' operations)
     to perform before doing a 'COMMIT' to start a new
     transaction.  Counterpart of 'daemon_memcached_w_batch_size'.

     This value is set to 1 by default, so that any changes made to the
     table through SQL statements are immediately visible to 'memcached'
     operations.  You might increase it to reduce the overhead from
     frequent commits on a system where the underlying table is only
     being accessed through the 'memcached' interface.  If you set the
     value too large, the amount of undo or redo data could impose some
     storage overhead, as with any long-running transaction.

     For more information, see innodb-memcached-setup.

   *
     'daemon_memcached_w_batch_size'

     Property                             Value

     *Command-Line Format*                '--daemon-memcached-w-batch-size=#'

     *System Variable*                    'daemon_memcached_w_batch_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1'

     Specifies how many 'memcached' write operations, such as 'add',
     'set', and 'incr', to perform before doing a 'COMMIT'
     to start a new transaction.  Counterpart of
     'daemon_memcached_r_batch_size'.

     This value is set to 1 by default, on the assumption that data
     being stored is important to preserve in case of an outage and
     should immediately be committed.  When storing non-critical data,
     you might increase this value to reduce the overhead from frequent
     commits; but then the last N-1 uncommitted write operations could
     be lost if a crash occurs.

     For more information, see innodb-memcached-setup.

   *
     'ignore_builtin_innodb'

     Property                             Value

     *Command-Line Format*                '--ignore-builtin-innodb'

     *Deprecated*                         Yes

     *System Variable*                    'ignore_builtin_innodb'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     See the description of '--ignore-builtin-innodb' under 'InnoDB
     Command Options' earlier in this section.

   *
     'innodb_adaptive_flushing'

     Property                             Value

     *Command-Line Format*                '--innodb-adaptive-flushing=#'

     *System Variable*                    'innodb_adaptive_flushing'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Specifies whether to dynamically adjust the rate of flushing dirty
     pages in the 'InnoDB' buffer pool based on the workload.  Adjusting
     the flush rate dynamically is intended to avoid bursts of I/O
     activity.  This setting is enabled by default.  See
     innodb-performance-adaptive_flushing for more information.  For
     general I/O tuning advice, see optimizing-innodb-diskio.

   *
     'innodb_adaptive_flushing_lwm'

     Property                             Value

     *Command-Line Format*                '--innodb-adaptive-flushing-lwm=#'

     *System Variable*                    'innodb_adaptive_flushing_lwm'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '10'

     *Minimum Value*                      '0'

     *Maximum Value*                      '70'

     Defines the low water mark representing percentage of redo log
     capacity at which adaptive flushing is enabled.  For more
     information, see innodb-lru-background-flushing.

   *
     'innodb_adaptive_hash_index'

     Property                             Value

     *Command-Line Format*                '--innodb-adaptive-hash-index=#'

     *System Variable*                    'innodb_adaptive_hash_index'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Whether the 'InnoDB' adaptive hash index is enabled or disabled.
     It may be desirable, depending on your workload, to dynamically
     enable or disable adaptive hash indexing to improve query
     performance.  Because the adaptive hash index may not be useful for
     all workloads, conduct benchmarks with it both enabled and
     disabled, using realistic workloads.  See
     innodb-adaptive-hash for details.

     This variable is enabled by default.  You can modify this parameter
     using the 'SET GLOBAL' statement, without restarting the server.
     Changing the setting requires the 'SUPER' privilege.  You can also
     use '--skip-innodb_adaptive_hash_index' at server startup to
     disable it.

     Disabling the adaptive hash index empties the hash table
     immediately.  Normal operations can continue while the hash table
     is emptied, and executing queries that were using the hash table
     access the index B-trees directly instead.  When the adaptive hash
     index is re-enabled, the hash table is populated again during
     normal operation.

   *
     'innodb_adaptive_hash_index_parts'

     Property                             Value

     *Command-Line Format*                '--innodb-adaptive-hash-index-parts=#'

     *Introduced*                         5.7.8

     *System Variable*                    'innodb_adaptive_hash_index_parts'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               numeric

     *Default Value*                      '8'

     *Minimum Value*                      '1'

     *Maximum Value*                      '512'

     Partitions the adaptive hash index search system.  Each index is
     bound to a specific partition, with each partition protected by a
     separate latch.

     In earlier releases, the adaptive hash index search system was
     protected by a single latch ('btr_search_latch') which could become
     a point of contention.  With the introduction of the
     'innodb_adaptive_hash_index_parts' option, the search system is
     partitioned into 8 parts by default.  The maximum setting is 512.

     For related information, see innodb-adaptive-hash.

   *
     'innodb_adaptive_max_sleep_delay'

     Property                             Value

     *Command-Line Format*                '--innodb-adaptive-max-sleep-delay=#'

     *System Variable*                    'innodb_adaptive_max_sleep_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '150000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1000000'

     Permits 'InnoDB' to automatically adjust the value of
     'innodb_thread_sleep_delay' up or down according to the current
     workload.  Any nonzero value enables automated, dynamic adjustment
     of the 'innodb_thread_sleep_delay' value, up to the maximum value
     specified in the 'innodb_adaptive_max_sleep_delay' option.  The
     value represents the number of microseconds.  This option can be
     useful in busy systems, with greater than 16 'InnoDB' threads.  (In
     practice, it is most valuable for MySQL systems with hundreds or
     thousands of simultaneous connections.)

     For more information, see
     innodb-performance-thread_concurrency.

   *
     'innodb_additional_mem_pool_size'

     Property                             Value

     *Command-Line Format*                '--innodb-additional-mem-pool-size=#'

     *Deprecated*                         Yes (removed in 5.7.4)

     *System Variable*                    'innodb_additional_mem_pool_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '8388608'

     *Minimum Value*                      '2097152'

     *Maximum Value*                      '4294967295'

     The size in bytes of a memory pool 'InnoDB' uses to store data
     dictionary information and other internal data structures.  The
     more tables you have in your application, the more memory you
     allocate here.  If 'InnoDB' runs out of memory in this pool, it
     starts to allocate memory from the operating system and writes
     warning messages to the MySQL error log.  The default value is 8MB.

     This variable relates to the 'InnoDB' internal memory allocator,
     which is unused if 'innodb_use_sys_malloc' is enabled.  For more
     information, see innodb-performance-use_sys_malloc.

   *
     'innodb_api_bk_commit_interval'

     Property                             Value

     *Command-Line Format*                '--innodb-api-bk-commit-interval=#'

     *System Variable*                    'innodb_api_bk_commit_interval'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '5'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1073741824'

     How often to auto-commit idle connections that use the 'InnoDB'
     'memcached' interface, in seconds.  For more information, see
     innodb-memcached-txn.

   *
     'innodb_api_disable_rowlock'

     Property                             Value

     *Command-Line Format*                '--innodb-api-disable-rowlock=#'

     *System Variable*                    'innodb_api_disable_rowlock'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Use this option to disable row locks when 'InnoDB' 'memcached'
     performs DML operations.  By default, 'innodb_api_disable_rowlock'
     is disabled, which means that 'memcached' requests row locks for
     'get' and 'set' operations.  When 'innodb_api_disable_rowlock' is
     enabled, 'memcached' requests a table lock instead of row locks.

     'innodb_api_disable_rowlock' is not dynamic.  It must be specified
     on the 'mysqld' command line or entered in the MySQL
     configuration file.  Configuration takes effect when the plugin is
     installed, which occurs when the MySQL server is started.

     For more information, see innodb-memcached-txn.

   *
     'innodb_api_enable_binlog'

     Property                             Value

     *Command-Line Format*                '--innodb-api-enable-binlog=#'

     *System Variable*                    'innodb_api_enable_binlog'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Lets you use the 'InnoDB' 'memcached' plugin with the MySQL binary
     log.  For more information, see
     innodb-memcached-replication-enable-binlog.

   *
     'innodb_api_enable_mdl'

     Property                             Value

     *Command-Line Format*                '--innodb-api-enable-mdl=#'

     *System Variable*                    'innodb_api_enable_mdl'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Locks the table used by the 'InnoDB' 'memcached' plugin, so that it
     cannot be dropped or altered by DDL through the SQL interface.  For
     more information, see innodb-memcached-txn.

   *
     'innodb_api_trx_level'

     Property                             Value

     *Command-Line Format*                '--innodb-api-trx-level=#'

     *System Variable*                    'innodb_api_trx_level'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     Controls the transaction isolation level on queries processed by
     the 'memcached' interface.  The constants corresponding to the
     familiar names are:

        * 0 = 'READ UNCOMMITTED'

        * 1 = 'READ COMMITTED'

        * 2 = 'REPEATABLE READ'

        * 3 = 'SERIALIZABLE'

     For more information, see innodb-memcached-txn.

   *
     'innodb_autoextend_increment'

     Property                             Value

     *Command-Line Format*                '--innodb-autoextend-increment=#'

     *System Variable*                    'innodb_autoextend_increment'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '64'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1000'

     The increment size (in megabytes) for extending the size of an
     auto-extending 'InnoDB' system tablespace file when it becomes
     full.  The default value is 64.  For related information, see
     innodb-startup-data-file-configuration, and
     innodb-resize-system-tablespace.

     The 'innodb_autoextend_increment' setting does not affect
     file-per-table tablespace files or general tablespace files.  These
     files are auto-extending regardless of the
     'innodb_autoextend_increment' setting.  The initial extensions are
     by small amounts, after which extensions occur in increments of
     4MB.

   *
     'innodb_autoinc_lock_mode'

     Property                             Value

     *Command-Line Format*                '--innodb-autoinc-lock-mode=#'

     *System Variable*                    'innodb_autoinc_lock_mode'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1'

     *Valid Values*                       '0' '1' '2'

     The lock mode to use for generating auto-increment values.
     Permissible values are 0, 1, or 2, for traditional, consecutive, or
     interleaved, respectively.  The default setting is 1 (consecutive).
     For the characteristics of each lock mode, see
     innodb-auto-increment-lock-modes.

   *
     'innodb_background_drop_list_empty'

     Property                             Value

     *Command-Line Format*                '--innodb-background-drop-list-empty=#'

     *Introduced*                         5.7.10

     *System Variable*                    'innodb_background_drop_list_empty'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enabling the 'innodb_background_drop_list_empty' debug option helps
     avoid test case failures by delaying table creation until the
     background drop list is empty.  For example, if test case A places
     table 't1' on the background drop list, test case B waits until the
     background drop list is empty before creating table 't1'.

   *
     'innodb_buffer_pool_chunk_size'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-chunk-size'

     *Introduced*                         5.7.5

     *System Variable*                    'innodb_buffer_pool_chunk_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '134217728'

     *Minimum Value*                      '1048576'

     *Maximum Value*                      'innodb_buffer_pool_size /
                                          innodb_buffer_pool_instances'

     'innodb_buffer_pool_chunk_size' defines the chunk size for 'InnoDB'
     buffer pool resizing operations.  The 'innodb_buffer_pool_size'
     parameter is dynamic, which allows you to resize the buffer pool
     without restarting the server.

     To avoid copying all buffer pool pages during resizing operations,
     the operation is performed in 'chunks'.  By default,
     'innodb_buffer_pool_chunk_size' is 128MB (134217728 bytes).  The
     number of pages contained in a chunk depends on the value of
     'innodb_page_size'.  'innodb_buffer_pool_chunk_size' can be
     increased or decreased in units of 1MB (1048576 bytes).

     The following conditions apply when altering the
     'innodb_buffer_pool_chunk_size' value:

        * If ' innodb_buffer_pool_chunk_size' *
          'innodb_buffer_pool_instances' is larger than the current
          buffer pool size when the buffer pool is initialized,
          'innodb_buffer_pool_chunk_size' is truncated to
          'innodb_buffer_pool_size' / 'innodb_buffer_pool_instances'.

        * Buffer pool size must always be equal to or a multiple of
          'innodb_buffer_pool_chunk_size' *
          'innodb_buffer_pool_instances'.  If you alter
          'innodb_buffer_pool_chunk_size', 'innodb_buffer_pool_size' is
          automatically adjusted to a value that is equal to or a
          multiple of 'innodb_buffer_pool_chunk_size' *
          'innodb_buffer_pool_instances' that is not less than the
          current buffer pool size.  The adjustment occurs when the
          buffer pool is initialized.

     *Important*:

     Care should be taken when changing 'innodb_buffer_pool_chunk_size',
     as changing this value can automatically increase the size of the
     buffer pool.  Before changing 'innodb_buffer_pool_chunk_size',
     calculate the effect it will have on 'innodb_buffer_pool_size' to
     ensure that the resulting buffer pool size is acceptable.

     To avoid potential performance issues, the number of chunks
     ('innodb_buffer_pool_size' / 'innodb_buffer_pool_chunk_size')
     should not exceed 1000.

     See innodb-buffer-pool-resize for more information.

   *
     'innodb_buffer_pool_dump_at_shutdown'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-dump-at-shutdown=#'

     *System Variable*                    'innodb_buffer_pool_dump_at_shutdown'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value* (>= 5.7.7)           'ON'

     *Default Value* (<= 5.7.6)           'OFF'

     Specifies whether to record the pages cached in the 'InnoDB' buffer
     pool when the MySQL server is shut down, to shorten the warmup
     process at the next restart.  Typically used in combination with
     'innodb_buffer_pool_load_at_startup'.  The
     'innodb_buffer_pool_dump_pct' option defines the percentage of most
     recently used buffer pool pages to dump.

     Both 'innodb_buffer_pool_dump_at_shutdown' and
     'innodb_buffer_pool_load_at_startup' are enabled by default.

     For more information, see innodb-preload-buffer-pool.

   *
     'innodb_buffer_pool_dump_now'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-dump-now=#'

     *System Variable*                    'innodb_buffer_pool_dump_now'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Immediately records the pages cached in the 'InnoDB' buffer pool.
     Typically used in combination with 'innodb_buffer_pool_load_now'.

     For more information, see innodb-preload-buffer-pool.

   *
     'innodb_buffer_pool_dump_pct'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-dump-pct=#'

     *Introduced*                         5.7.2

     *System Variable*                    'innodb_buffer_pool_dump_pct'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value* (>= 5.7.7)           '25'

     *Default Value* (<= 5.7.6)           '100'

     *Minimum Value*                      '1'

     *Maximum Value*                      '100'

     Specifies the percentage of the most recently used pages for each
     buffer pool to read out and dump.  The range is 1 to 100.  The
     default value is 25.  For example, if there are 4 buffer pools with
     100 pages each, and 'innodb_buffer_pool_dump_pct' is set to 25, the
     25 most recently used pages from each buffer pool are dumped.

     The change to the 'innodb_buffer_pool_dump_pct' default value
     coincides with default value changes for
     'innodb_buffer_pool_dump_at_shutdown' and
     'innodb_buffer_pool_load_at_startup', which are both enabled by
     default in MySQL 5.7.

   *
     'innodb_buffer_pool_filename'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-filename=file'

     *System Variable*                    'innodb_buffer_pool_filename'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               file name

     *Default Value*                      'ib_buffer_pool'

     Specifies the name of the file that holds the list of tablespace
     IDs and page IDs produced by 'innodb_buffer_pool_dump_at_shutdown'
     or 'innodb_buffer_pool_dump_now'.  Tablespace IDs and page IDs are
     saved in the following format: 'space, page_id'.  By default, the
     file is named 'ib_buffer_pool' and is located in the 'InnoDB' data
     directory.  A non-default location must be specified relative to
     the data directory.

     A file name can be specified at runtime, using a 'SET'
     statement:

          SET GLOBAL innodb_buffer_pool_filename='FILE_NAME';

     You can also specify a file name at startup, in a startup string or
     MySQL configuration file.  When specifying a file name at startup,
     the file must exist or 'InnoDB' will return a startup error
     indicating that there is no such file or directory.

     For more information, see innodb-preload-buffer-pool.

   *
     'innodb_buffer_pool_instances'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-instances=#'

     *System Variable*                    'innodb_buffer_pool_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (Other)                       integer

     *Type* (Windows, 32-bit platforms)   integer

     *Default Value* (Other)              '8 (or 1 if
                                          innodb_buffer_pool_size < 1GB'

     *Default Value* (Windows, 32-bit     '(autosized)'
     platforms)

     *Minimum Value* (Other)              '1'

     *Minimum Value* (Windows, 32-bit     '1'
     platforms)

     *Maximum Value* (Other)              '64'

     *Maximum Value* (Windows, 32-bit     '64'
     platforms)

     The number of regions that the 'InnoDB' buffer pool is divided
     into.  For systems with buffer pools in the multi-gigabyte range,
     dividing the buffer pool into separate instances can improve
     concurrency, by reducing contention as different threads read and
     write to cached pages.  Each page that is stored in or read from
     the buffer pool is assigned to one of the buffer pool instances
     randomly, using a hashing function.  Each buffer pool manages its
     own free lists, flush lists, LRUs, and all other data structures
     connected to a buffer pool, and is protected by its own buffer pool
     mutex.

     This option only takes effect when setting
     'innodb_buffer_pool_size' to 1GB or more.  The total buffer pool
     size is divided among all the buffer pools.  For best efficiency,
     specify a combination of 'innodb_buffer_pool_instances' and
     'innodb_buffer_pool_size' so that each buffer pool instance is at
     least 1GB.

     The default value on 32-bit Windows systems depends on the value of
     'innodb_buffer_pool_size', as described below:

        * If 'innodb_buffer_pool_size' is greater than 1.3GB, the
          default for 'innodb_buffer_pool_instances' is
          'innodb_buffer_pool_size'/128MB, with individual memory
          allocation requests for each chunk.  1.3GB was chosen as the
          boundary at which there is significant risk for 32-bit Windows
          to be unable to allocate the contiguous address space needed
          for a single buffer pool.

        * Otherwise, the default is 1.

     On all other platforms, the default value is 8 when
     'innodb_buffer_pool_size' is greater than or equal to 1GB.
     Otherwise, the default is 1.

     For related information, see innodb-buffer-pool-resize.

   *
     'innodb_buffer_pool_load_abort'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-load-abort=#'

     *System Variable*                    'innodb_buffer_pool_load_abort'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Interrupts the process of restoring 'InnoDB' buffer pool contents
     triggered by 'innodb_buffer_pool_load_at_startup' or
     'innodb_buffer_pool_load_now'.

     For more information, see innodb-preload-buffer-pool.

   *
     'innodb_buffer_pool_load_at_startup'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-load-at-startup=#'

     *System Variable*                    'innodb_buffer_pool_load_at_startup'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value* (>= 5.7.7)           'ON'

     *Default Value* (<= 5.7.6)           'OFF'

     Specifies that, on MySQL server startup, the 'InnoDB' buffer pool
     is automatically warmed up by loading the same pages it held at an
     earlier time.  Typically used in combination with
     'innodb_buffer_pool_dump_at_shutdown'.

     Both 'innodb_buffer_pool_dump_at_shutdown' and
     'innodb_buffer_pool_load_at_startup' are enabled by default.

     For more information, see innodb-preload-buffer-pool.

   *
     'innodb_buffer_pool_load_now'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-load-now=#'

     *System Variable*                    'innodb_buffer_pool_load_now'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Immediately warms up the 'InnoDB' buffer pool by loading a set of
     data pages, without waiting for a server restart.  Can be useful to
     bring cache memory back to a known state during benchmarking, or to
     ready the MySQL server to resume its normal workload after running
     queries for reports or maintenance.

     For more information, see innodb-preload-buffer-pool.

   *
     'innodb_buffer_pool_size'

     Property                             Value

     *Command-Line Format*                '--innodb-buffer-pool-size=#'

     *System Variable*                    'innodb_buffer_pool_size'

     *Scope*                              Global

     *Dynamic* (>= 5.7.5)                 Yes

     *Dynamic* (<= 5.7.4)                 No

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '134217728'

     *Default Value* (32-bit platforms)   '134217728'

     *Minimum Value* (64-bit platforms)   '5242880'

     *Minimum Value* (32-bit platforms)   '5242880'

     *Maximum Value* (64-bit platforms)   '2**64-1'

     *Maximum Value* (32-bit platforms)   '2**32-1'

     The size in bytes of the buffer pool, the memory area where
     'InnoDB' caches table and index data.  The default value is
     134217728 bytes (128MB). The maximum value depends on the CPU
     architecture; the maximum is 4294967295 (2^32-1) on 32-bit systems
     and 18446744073709551615 (2^64-1) on 64-bit systems.  On 32-bit
     systems, the CPU architecture and operating system may impose a
     lower practical maximum size than the stated maximum.  When the
     size of the buffer pool is greater than 1GB, setting
     'innodb_buffer_pool_instances' to a value greater than 1 can
     improve the scalability on a busy server.

     A larger buffer pool requires less disk I/O to access the same
     table data more than once.  On a dedicated database server, you
     might set the buffer pool size to 80% of the machine's physical
     memory size.  Be aware of the following potential issues when
     configuring buffer pool size, and be prepared to scale back the
     size of the buffer pool if necessary.

        * Competition for physical memory can cause paging in the
          operating system.

        * 'InnoDB' reserves additional memory for buffers and control
          structures, so that the total allocated space is approximately
          10% greater than the specified buffer pool size.

        * Address space for the buffer pool must be contiguous, which
          can be an issue on Windows systems with DLLs that load at
          specific addresses.

        * The time to initialize the buffer pool is roughly proportional
          to its size.  On instances with large buffer pools,
          initialization time might be significant.  To reduce the
          initialization period, you can save the buffer pool state at
          server shutdown and restore it at server startup.  See
          innodb-preload-buffer-pool.

     When you increase or decrease buffer pool size, the operation is
     performed in chunks.  Chunk size is defined by the
     'innodb_buffer_pool_chunk_size' configuration option, which has a
     default of 128 MB.

     Buffer pool size must always be equal to or a multiple of
     'innodb_buffer_pool_chunk_size' * 'innodb_buffer_pool_instances'.
     If you alter the buffer pool size to a value that is not equal to
     or a multiple of 'innodb_buffer_pool_chunk_size' *
     'innodb_buffer_pool_instances', buffer pool size is automatically
     adjusted to a value that is equal to or a multiple of
     'innodb_buffer_pool_chunk_size' * 'innodb_buffer_pool_instances'
     that is not less than the specified buffer pool size.

     'innodb_buffer_pool_size' can be set dynamically, which allows you
     to resize the buffer pool without restarting the server.  The
     'Innodb_buffer_pool_resize_status' status variable reports the
     status of online buffer pool resizing operations.  See
     innodb-buffer-pool-resize for more information.

   *
     'innodb_change_buffer_max_size'

     Property                             Value

     *Command-Line Format*                '--innodb-change-buffer-max-size=#'

     *System Variable*                    'innodb_change_buffer_max_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '25'

     *Minimum Value*                      '0'

     *Maximum Value*                      '50'

     Maximum size for the 'InnoDB' change buffer, as a percentage of the
     total size of the buffer pool.  You might increase this value for a
     MySQL server with heavy insert, update, and delete activity, or
     decrease it for a MySQL server with unchanging data used for
     reporting.  For more information, see
     innodb-insert-buffering, and
     innodb-performance-change_buffering.  For general I/O tuning
     advice, see optimizing-innodb-diskio.

   *
     'innodb_change_buffering'

     Property                             Value

     *Command-Line Format*                '--innodb-change-buffering=#'

     *System Variable*                    'innodb_change_buffering'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'all'

     *Valid Values*                       'none' 'inserts' 'deletes'
                                          'changes' 'purges' 'all'

     Whether 'InnoDB' performs change buffering, an optimization that
     delays write operations to secondary indexes so that the I/O
     operations can be performed sequentially.  Permitted values are
     described in the following table.

     *Permitted Values for innodb_change_buffering*

     Value          Description

     'none'         Do not buffer any operations.

     'inserts'      Buffer insert operations.

     'deletes'      Buffer delete marking operations;
                    strictly speaking, the writes that mark
                    index records for later deletion during a
                    purge operation.

     'changes'      Buffer inserts and delete-marking
                    operations.

     'purges'       Buffer the physical deletion operations
                    that happen in the background.

     'all'          The default.  Buffer inserts,
                    delete-marking operations, and purges.

     For more information, see innodb-insert-buffering, and
     innodb-performance-change_buffering.  For general I/O
     tuning advice, see optimizing-innodb-diskio.

   *
     'innodb_change_buffering_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-change-buffering-debug=#'

     *System Variable*                    'innodb_change_buffering_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Maximum Value*                      '2'

     Sets a debug flag for 'InnoDB' change buffering.  A value of 1
     forces all changes to the change buffer.  A value of 2 causes a
     crash at merge.  A default value of 0 indicates that the change
     buffering debug flag is not set.  This option is only available
     when debugging support is compiled in using the 'WITH_DEBUG'
     'CMake' option.

   *
     'innodb_checksum_algorithm'

     Property                             Value

     *Command-Line Format*                '--innodb-checksum-algorithm=#'

     *System Variable*                    'innodb_checksum_algorithm'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value* (>= 5.7.7)           'crc32'

     *Default Value* (<= 5.7.6)           'innodb'

     *Valid Values*                       'innodb' 'crc32' 'none'
                                          'strict_innodb' 'strict_crc32'
                                          'strict_none'

     Specifies how to generate and verify the checksum stored in the
     disk blocks of 'InnoDB' tablespaces.  'crc32' is the default value
     as of MySQL 5.7.7.

     'innodb_checksum_algorithm' replaces the 'innodb_checksums' option.
     The following values were provided for compatibility, up to and
     including MySQL 5.7.6:

        * 'innodb_checksums=ON' is the same as
          'innodb_checksum_algorithm=innodb'.

        * 'innodb_checksums=OFF' is the same as
          'innodb_checksum_algorithm=none'.

     As of MySQL 5.7.7, with a default 'innodb_checksum_algorithm' value
     of crc32, 'innodb_checksums=ON' is now the same as
     'innodb_checksum_algorithm=crc32'.  'innodb_checksums=OFF' is still
     the same as 'innodb_checksum_algorithm=none'.

     To avoid conflicts, remove references to 'innodb_checksums' from
     MySQL configuration files and startup scripts.

     The value 'innodb' is backward-compatible with earlier versions of
     MySQL. The value 'crc32' uses an algorithm that is faster to
     compute the checksum for every modified block, and to check the
     checksums for each disk read.  It scans blocks 32 bits at a time,
     which is faster than the 'innodb' checksum algorithm, which scans
     blocks 8 bits at a time.  The value 'none' writes a constant value
     in the checksum field rather than computing a value based on the
     block data.  The blocks in a tablespace can use a mix of old, new,
     and no checksum values, being updated gradually as the data is
     modified; once blocks in a tablespace are modified to use the
     'crc32' algorithm, the associated tables cannot be read by earlier
     versions of MySQL.

     The strict form of a checksum algorithm reports an error if it
     encounters a valid but non-matching checksum value in a tablespace.
     It is recommended that you only use strict settings in a new
     instance, to set up tablespaces for the first time.  Strict
     settings are somewhat faster, because they do not need to compute
     all checksum values during disk reads.

     *Note*:

     Prior to MySQL 5.7.8, a strict mode setting for
     'innodb_checksum_algorithm' caused 'InnoDB' to halt when
     encountering a _valid_ but non-matching checksum.  In MySQL 5.7.8
     and later, only an error message is printed, and the page is
     accepted as valid if it has a valid 'innodb', 'crc32' or 'none'
     checksum.

     The following table shows the difference between the 'none',
     'innodb', and 'crc32' option values, and their strict counterparts.
     'none', 'innodb', and 'crc32' write the specified type of checksum
     value into each data block, but for compatibility accept other
     checksum values when verifying a block during a read operation.
     Strict settings also accept valid checksum values but print an
     error message when a valid non-matching checksum value is
     encountered.  Using the strict form can make verification faster if
     all 'InnoDB' data files in an instance are created under an
     identical 'innodb_checksum_algorithm' value.

     *Permitted innodb_checksum_algorithm Values*

     Value          Generated checksum (when      Permitted checksums (when
                    writing)                      reading)

     none           A constant number.            Any of the checksums
                                                  generated by 'none',
                                                  'innodb', or 'crc32'.

     innodb         A checksum calculated in      Any of the checksums
                    software, using the           generated by 'none',
                    original algorithm from       'innodb', or 'crc32'.
                    'InnoDB'.

     crc32          A checksum calculated using   Any of the checksums
                    the 'crc32' algorithm,        generated by 'none',
                    possibly done with a          'innodb', or 'crc32'.
                    hardware assist.

     strict_none    A constant number             Any of the checksums
                                                  generated by 'none',
                                                  'innodb', or 'crc32'.
                                                  'InnoDB' prints an error
                                                  message if a valid but
                                                  non-matching checksum is
                                                  encountered.

     strict_innodb  A checksum calculated in      Any of the checksums
                    software, using the           generated by 'none',
                    original algorithm from       'innodb', or 'crc32'.
                    'InnoDB'.                     'InnoDB' prints an error
                                                  message if a valid but
                                                  non-matching checksum is
                                                  encountered.

     strict_crc32   A checksum calculated using   Any of the checksums
                    the 'crc32' algorithm,        generated by 'none',
                    possibly done with a          'innodb', or 'crc32'.
                    hardware assist.              'InnoDB' prints an error
                                                  message if a valid but
                                                  non-matching checksum is
                                                  encountered.

     Versions of MySQL Enterprise Backup.
     up to 3.8.0 do not support backing up tablespaces that use CRC32
     checksums.  See MySQL Enterprise Backup.
     adds CRC32 checksum support in 3.8.1, with some limitations.  Refer
     to the MySQL Enterprise Backup.
     3.8.1 Change History for more information.

   *
     'innodb_checksums'

     Property                             Value

     *Command-Line Format*                '--innodb-checksums'

     *Deprecated*                         Yes

     *System Variable*                    'innodb_checksums'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     'InnoDB' can use checksum validation on all tablespace pages read
     from disk to ensure extra fault tolerance against hardware faults
     or corrupted data files.  This validation is enabled by default.
     Under specialized circumstances (such as when running benchmarks)
     this safety feature can be disabled with '--skip-innodb-checksums'.
     You can specify the method of calculating the checksum using the
     'innodb_checksum_algorithm' option.

     'innodb_checksums' is deprecated, replaced by
     'innodb_checksum_algorithm'.

     Prior to MySQL 5.7.7, 'innodb_checksums=ON' is the same as
     'innodb_checksum_algorithm=innodb'.  As of MySQL 5.7.7, the
     'innodb_checksum_algorithm' default value is 'crc32', and
     'innodb_checksums=ON' is the same as
     'innodb_checksum_algorithm=crc32'.  'innodb_checksums=OFF' is the
     same as 'innodb_checksum_algorithm=none'.

     Remove any 'innodb_checksums' options from your configuration files
     and startup scripts to avoid conflicts with
     'innodb_checksum_algorithm'.  'innodb_checksums=OFF' automatically
     sets 'innodb_checksum_algorithm=none'.  'innodb_checksums=ON' is
     ignored and overridden by any other setting for
     'innodb_checksum_algorithm'.

   *
     'innodb_cmp_per_index_enabled'

     Property                             Value

     *Command-Line Format*                '--innodb-cmp-per-index-enabled=#'

     *System Variable*                    'innodb_cmp_per_index_enabled'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     *Valid Values*                       'OFF' 'ON'

     Enables per-index compression-related statistics in the
     'INFORMATION_SCHEMA.INNODB_CMP_PER_INDEX'
     table.  Because these statistics can be
     expensive to gather, only enable this option on development, test,
     or slave instances during performance tuning related to 'InnoDB'
     compressed tables.

     For more information, see innodb-cmp-per-index-table, and
     innodb-compression-tuning-monitoring.

   *
     'innodb_commit_concurrency'

     Property                             Value

     *Command-Line Format*                '--innodb-commit-concurrency=#'

     *System Variable*                    'innodb_commit_concurrency'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1000'

     The number of threads that can commit at the same time.  A value of
     0 (the default) permits any number of transactions to commit
     simultaneously.

     The value of 'innodb_commit_concurrency' cannot be changed at
     runtime from zero to nonzero or vice versa.  The value can be
     changed from one nonzero value to another.

   *
     'innodb_compress_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-compress-debug=#'

     *Introduced*                         5.7.8

     *System Variable*                    'innodb_compress_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'none'

     *Valid Values*                       'none' 'zlib' 'lz4' 'lz4hc'

     Compresses all tables using a specified compression algorithm
     without having to define a 'COMPRESSION' attribute for each table.
     This option is only available if debugging support is compiled in
     using the 'WITH_DEBUG' 'CMake' option.

     For related information, see innodb-page-compression.

   *
     'innodb_compression_failure_threshold_pct'

     Property                             Value

     *Command-Line Format*                '--innodb-compression-failure-threshold-pct=#'

     *System Variable*                    'innodb_compression_failure_threshold_pct'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '5'

     *Minimum Value*                      '0'

     *Maximum Value*                      '100'

     Defines the compression failure rate threshold for a table, as a
     percentage, at which point MySQL begins adding padding within
     compressed pages to avoid expensive compression failures.  When
     this threshold is passed, MySQL begins to leave additional free
     space within each new compressed page, dynamically adjusting the
     amount of free space up to the percentage of page size specified by
     'innodb_compression_pad_pct_max'.  A value of zero disables the
     mechanism that monitors compression efficiency and dynamically
     adjusts the padding amount.

     For more information, see
     innodb-performance-compression-oltp.

   *
     'innodb_compression_level'

     Property                             Value

     *Command-Line Format*                '--innodb-compression-level=#'

     *System Variable*                    'innodb_compression_level'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '6'

     *Minimum Value*                      '0'

     *Maximum Value*                      '9'

     Specifies the level of zlib compression to use for 'InnoDB'
     compressed tables and indexes.  A higher value lets you fit more
     data onto a storage device, at the expense of more CPU overhead
     during compression.  A lower value lets you reduce CPU overhead
     when storage space is not critical, or you expect the data is not
     especially compressible.

     For more information, see
     innodb-performance-compression-oltp.

   *
     'innodb_compression_pad_pct_max'

     Property                             Value

     *Command-Line Format*                '--innodb-compression-pad-pct-max=#'

     *System Variable*                    'innodb_compression_pad_pct_max'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '50'

     *Minimum Value*                      '0'

     *Maximum Value*                      '75'

     Specifies the maximum percentage that can be reserved as free space
     within each compressed page, allowing room to reorganize the data
     and modification log within the page when a compressed table or
     index is updated and the data might be recompressed.  Only applies
     when 'innodb_compression_failure_threshold_pct' is set to a nonzero
     value, and the rate of compression failures passes the cutoff
     point.

     For more information, see
     innodb-performance-compression-oltp.

   *
     'innodb_concurrency_tickets'

     Property                             Value

     *Command-Line Format*                '--innodb-concurrency-tickets=#'

     *System Variable*                    'innodb_concurrency_tickets'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '5000'

     *Minimum Value*                      '1'

     *Maximum Value*                      '4294967295'

     Determines the number of threads that can enter 'InnoDB'
     concurrently.  A thread is placed in a queue when it tries to enter
     'InnoDB' if the number of threads has already reached the
     concurrency limit.  When a thread is permitted to enter 'InnoDB',
     it is given a number of ' tickets' equal to the value of
     'innodb_concurrency_tickets', and the thread can enter and leave
     'InnoDB' freely until it has used up its tickets.  After that
     point, the thread again becomes subject to the concurrency check
     (and possible queuing) the next time it tries to enter 'InnoDB'.
     The default value is 5000.

     With a small 'innodb_concurrency_tickets' value, small transactions
     that only need to process a few rows compete fairly with larger
     transactions that process many rows.  The disadvantage of a small
     'innodb_concurrency_tickets' value is that large transactions must
     loop through the queue many times before they can complete, which
     extends the amount of time required to complete their task.

     With a large 'innodb_concurrency_tickets' value, large transactions
     spend less time waiting for a position at the end of the queue
     (controlled by 'innodb_thread_concurrency') and more time
     retrieving rows.  Large transactions also require fewer trips
     through the queue to complete their task.  The disadvantage of a
     large 'innodb_concurrency_tickets' value is that too many large
     transactions running at the same time can starve smaller
     transactions by making them wait a longer time before executing.

     With a nonzero 'innodb_thread_concurrency' value, you may need to
     adjust the 'innodb_concurrency_tickets' value up or down to find
     the optimal balance between larger and smaller transactions.  The
     'SHOW ENGINE INNODB STATUS' report shows the number of tickets
     remaining for an executing transaction in its current pass through
     the queue.  This data may also be obtained from the
     'TRX_CONCURRENCY_TICKETS' column of the
     'INFORMATION_SCHEMA.INNODB_TRX' table.

     For more information, see
     innodb-performance-thread_concurrency.

   *
     'innodb_data_file_path'

     Property                             Value

     *Command-Line Format*                '--innodb-data-file-path=name'

     *System Variable*                    'innodb_data_file_path'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'ibdata1:12M:autoextend'

     Defines the name, size, and attributes of 'InnoDB' system
     tablespace data files.  If you do not specify a value for
     'innodb_data_file_path', the default behavior is to create a single
     auto-extending data file, slightly larger than 12MB, named
     'ibdata1'.

     The full syntax for a data file specification includes the file
     name, file size, and 'autoextend' and 'max' attributes:

          FILE_NAME:FILE_SIZE[:autoextend[:max:MAX_FILE_SIZE]]

     File sizes are specified KB, MB or GB (1024MB) by appending 'K',
     'M' or 'G' to the size value.  If specifying the data file size in
     kilobytes (KB), do so in multiples of 1024.  Otherwise, KB values
     are rounded to nearest megabyte (MB) boundary.  The sum of the
     sizes of the files must be at least slightly larger than 12MB.

     A minimum file size is enforced for the _first_ system tablespace
     data file to ensure that there is enough space for doublewrite
     buffer pages:

        * For an 'innodb_page_size' value of 16KB or less, the minimum
          file size is 3MB.

        * For an 'innodb_page_size' value of 32KB, the minimum file size
          is 6MB.

        * For an 'innodb_page_size' value of 64KB, the minimum file size
          is 12MB.

     The size limit of individual files is determined by your operating
     system.  You can set the file size to more than 4GB on operating
     systems that support large files.  You can also use raw disk partitions as data files.

     The 'autoextend' and 'max' attributes can be used only for the data
     file that is specified last in the 'innodb_data_file_path' setting.
     For example:

          [mysqld]
          innodb_data_file_path=ibdata1:50M;ibdata2:12M:autoextend:max:500MB

     If you specify the 'autoextend' option, 'InnoDB' extends the data
     file if it runs out of free space.  The 'autoextend' increment is
     64MB by default.  To modify the increment, change the
     'innodb_autoextend_increment' system variable.

     The full directory path for system tablespace data files is formed
     by concatenating the paths defined by 'innodb_data_home_dir' and
     'innodb_data_file_path'.

     For more information about configuring system tablespace data
     files, see innodb-init-startup-configuration.

   *
     'innodb_data_home_dir'

     Property                             Value

     *Command-Line Format*                '--innodb-data-home-dir=dir_name'

     *System Variable*                    'innodb_data_home_dir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The common part of the directory path for 'InnoDB' system
     tablespace data files.  This setting does not affect the location
     of file-per-table tablespaces when 'innodb_file_per_table' is
     enabled.  The default value is the MySQL 'data' directory.  If you
     specify the value as an empty string, you can specify an absolute
     file paths for 'innodb_data_file_path'.

     A trailing slash is required when specifying a value for
     'innodb_data_home_dir'.  For example:

          [mysqld]
          innodb_data_home_dir = /path/to/myibdata/

     For related information, see
     innodb-init-startup-configuration.

   *
     'innodb_deadlock_detect'

     Property                             Value

     *Command-Line Format*                '--innodb-deadlock-detect'

     *Introduced*                         5.7.15

     *System Variable*                    'innodb_deadlock_detect'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     This option is used to disable deadlock detection.  On high
     concurrency systems, deadlock detection can cause a slowdown when
     numerous threads wait for the same lock.  At times, it may be more
     efficient to disable deadlock detection and rely on the
     'innodb_lock_wait_timeout' setting for transaction rollback when a
     deadlock occurs.

     For related information, see innodb-deadlock-detection.

   *
     'innodb_default_row_format'

     Property                             Value

     *Command-Line Format*                '--innodb-default-row-format=#'

     *Introduced*                         5.7.9

     *System Variable*                    'innodb_default_row_format'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'DYNAMIC'

     *Valid Values*                       'DYNAMIC' 'COMPACT' 'REDUNDANT'

     The 'innodb_default_row_format' option defines the default row
     format for 'InnoDB' tables and user-created temporary tables.  The
     default setting is 'DYNAMIC'.  Other permitted values are 'COMPACT'
     and 'REDUNDANT'.  The 'COMPRESSED' row format, which is not
     supported for use in the system tablespace, cannot be defined as
     the default.

     Newly created tables use the row format defined by
     'innodb_default_row_format' when a 'ROW_FORMAT' option is not
     specified explicitly or when 'ROW_FORMAT=DEFAULT' is used.

     When a 'ROW_FORMAT' option is not specified explicitly or when
     'ROW_FORMAT=DEFAULT' is used, any operation that rebuilds a table
     also silently changes the row format of the table to the format
     defined by 'innodb_default_row_format'.  For more information, see
     innodb-row-format-specification.

     Internal 'InnoDB' temporary tables created by the server to process
     queries use the 'DYNAMIC' row format, regardless of the
     'innodb_default_row_format' setting.

   *
     'innodb_disable_sort_file_cache'

     Property                             Value

     *Command-Line Format*                '--innodb-disable-sort-file-cache=#'

     *System Variable*                    'innodb_disable_sort_file_cache'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Disables the operating system file system cache for merge-sort
     temporary files.  The effect is to open such files with the
     equivalent of 'O_DIRECT'.

   *
     'innodb_disable_resize_buffer_pool_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-disable-resize-buffer-pool-debug=#'

     *Introduced*                         5.7.6

     *System Variable*                    'innodb_disable_resize_buffer_pool_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Disables resizing of the 'InnoDB' buffer pool.  This option is only
     available if debugging support is compiled in using the
     'WITH_DEBUG' 'CMake' option.

   *
     'innodb_doublewrite'

     Property                             Value

     *Command-Line Format*                '--innodb-doublewrite'

     *System Variable*                    'innodb_doublewrite'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     When enabled (the default), 'InnoDB' stores all data twice, first
     to the doublewrite buffer, then to the actual data files.  This
     variable can be turned off with '--skip-innodb_doublewrite' for
     benchmarks or cases when top performance is needed rather than
     concern for data integrity or possible failures.

     If system tablespace data files ('ibdata*' files) are located on
     Fusion-io devices that support atomic writes, doublewrite buffering
     is automatically disabled and Fusion-io atomic writes are used for
     all data files.  Because the doublewrite buffer setting is global,
     doublewrite buffering is also disabled for data files residing on
     non-Fusion-io hardware.  This feature is only supported on
     Fusion-io hardware and only enabled for Fusion-io NVMFS on Linux.
     To take full advantage of this feature, an 'innodb_flush_method'
     setting of 'O_DIRECT' is recommended.

     For related information, see innodb-doublewrite-buffer.

   *
     'innodb_fast_shutdown'

     Property                             Value

     *Command-Line Format*                '--innodb-fast-shutdown[=#]'

     *System Variable*                    'innodb_fast_shutdown'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Valid Values*                       '0' '1' '2'

     The 'InnoDB' shutdown mode.  If the value is 0, 'InnoDB' does a
     slow shutdown, a full purge and a change buffer merge before
     shutting down.  If the value is 1 (the default), 'InnoDB' skips
     these operations at shutdown, a process known as a fast shutdown.
     If the value is 2, 'InnoDB' flushes its logs and shuts down cold,
     as if MySQL had crashed; no committed transactions are lost, but
     the crash recovery operation makes the next startup take longer.

     The slow shutdown can take minutes, or even hours in extreme cases
     where substantial amounts of data are still buffered.  Use the slow
     shutdown technique before upgrading or downgrading between MySQL
     major releases, so that all data files are fully prepared in case
     the upgrade process updates the file format.

     Use 'innodb_fast_shutdown=2' in emergency or troubleshooting
     situations, to get the absolute fastest shutdown if data is at risk
     of corruption.

   *
     'innodb_fil_make_page_dirty_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-fil-make-page-dirty-debug=#'

     *System Variable*                    'innodb_fil_make_page_dirty_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Maximum Value*                      '2**32-1'

     By default, setting 'innodb_fil_make_page_dirty_debug' to the ID of
     a tablespace immediately dirties the first page of the tablespace.
     If 'innodb_saved_page_number_debug' is set to a non-default value,
     setting 'innodb_fil_make_page_dirty_debug' dirties the specified
     page.  The 'innodb_fil_make_page_dirty_debug' option is only
     available if debugging support is compiled in using the
     'WITH_DEBUG' 'CMake' option.

   *
     'innodb_file_format'

     Property                             Value

     *Command-Line Format*                '--innodb-file-format=#'

     *Deprecated*                         5.7.7

     *System Variable*                    'innodb_file_format'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value* (>= 5.7.7)           'Barracuda'

     *Default Value* (<= 5.7.6)           'Antelope'

     *Valid Values*                       'Antelope' 'Barracuda'

     Enables an 'InnoDB' file format for file-per-table tablespaces.
     Supported file formats are 'Antelope' and 'Barracuda'.  'Antelope'
     is the original 'InnoDB' file format, which supports 'REDUNDANT'
     and 'COMPACT' row formats.  'Barracuda' is the newer file format,
     which supports 'COMPRESSED' and 'DYNAMIC' row formats.

     'COMPRESSED' and 'DYNAMIC' row formats enable important storage
     features for 'InnoDB' tables.  See innodb-row-format.

     Changing the 'innodb_file_format' setting does not affect the file
     format of existing 'InnoDB' tablespace files.

     The 'innodb_file_format' setting does not apply to general
     tablespaces, which support tables of all row formats.  See
     general-tablespaces.

     The 'innodb_file_format' default value was changed to 'Barracuda'
     in MySQL 5.7.

     The 'innodb_file_format' setting is ignored when creating tables
     that use the 'DYNAMIC' row format.  A table created using the
     'DYNAMIC' row format always uses the 'Barracuda' file format,
     regardless of the 'innodb_file_format' setting.  To use the
     'COMPRESSED' row format, 'innodb_file_format' must be set to
     'Barracuda'.

     The 'innodb_file_format' option is deprecated and will be removed
     in a future release.  The purpose of the 'innodb_file_format'
     option was to allow users to downgrade to the built-in version of
     'InnoDB' in MySQL 5.1.  Now that MySQL 5.1 has reached the end of
     its product lifecycle, downgrade support provided by this option is
     no longer necessary.

     For more information, see innodb-file-format.

   *
     'innodb_file_format_check'

     Property                             Value

     *Command-Line Format*                '--innodb-file-format-check=#'

     *Deprecated*                         5.7.7

     *System Variable*                    'innodb_file_format_check'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     This variable can be set to 1 or 0 at server startup to enable or
     disable whether 'InnoDB' checks the file format tag in the system
     tablespace (for example, 'Antelope' or 'Barracuda').  If the tag is
     checked and is higher than that supported by the current version of
     'InnoDB', an error occurs and 'InnoDB' does not start.  If the tag
     is not higher, 'InnoDB' sets the value of 'innodb_file_format_max'
     to the file format tag.

     *Note*:

     Despite the default value sometimes being displayed as 'ON' or
     'OFF', always use the numeric values 1 or 0 to turn this option on
     or off in your configuration file or command line string.

     For more information, see
     innodb-file-format-compatibility-checking.

     The 'innodb_file_format_check' option is deprecated together with
     the 'innodb_file_format' option.  Both options will be removed in a
     future release.

   *
     'innodb_file_format_max'

     Property                             Value

     *Command-Line Format*                '--innodb-file-format-max=#'

     *Deprecated*                         5.7.7

     *System Variable*                    'innodb_file_format_max'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value* (>= 5.7.9)           'Barracuda'

     *Default Value* (<= 5.7.8)           'Antelope'

     *Valid Values*                       'Antelope' 'Barracuda'

     At server startup, 'InnoDB' sets the value of this variable to the
     file format tag in the system tablespace (for example, 'Antelope'
     or 'Barracuda').  If the server creates or opens a table with a
     'higher' file format, it sets the value of 'innodb_file_format_max'
     to that format.

     For related information, see innodb-file-format.

     The 'innodb_file_format_max' option is deprecated together with the
     'innodb_file_format' option.  Both options will be removed in a
     future release.

   *
     'innodb_file_per_table'

     Property                             Value

     *Command-Line Format*                '--innodb-file-per-table'

     *System Variable*                    'innodb_file_per_table'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     When 'innodb_file_per_table' is enabled (the default), 'InnoDB'
     stores the data and indexes for each newly created table in a
     separate '.ibd' file instead of the system tablespace.  The storage
     for these tables is reclaimed when the tables are dropped or
     truncated.  This setting enables 'InnoDB'features such as table
     compression.  See innodb-multiple-tablespaces for more
     information.

     Enabling 'innodb_file_per_table' also means that an 'ALTER TABLE'
     operation moves an 'InnoDB' table from the
     system tablespace to an individual '.ibd' file in cases where
     'ALTER TABLE' rebuilds the table ('ALGORITHM=COPY').
     An exception to this rule is for tables placed in the system
     tablespace using the 'TABLESPACE=innodb_system' option with
     'CREATE TABLE' or 'ALTER TABLE'.
     These tables are unaffected by the 'innodb_file_per_table' setting
     and can only be moved to file-per-table tablespaces using
     'ALTER TABLE ... TABLESPACE=innodb_file_per_table'.

     When 'innodb_file_per_table' is disabled, 'InnoDB' stores the data
     for tables and indexes in the ibdata files that make up the system
     tablespace.  This setting reduces the performance overhead of file
     system operations for operations such as 'DROP TABLE'
     or 'TRUNCATE TABLE'.  It is most
     appropriate for a server environment where entire storage devices
     are devoted to MySQL data.  Because the system tablespace never
     shrinks, and is shared across all databases in an instance, avoid
     loading huge amounts of temporary data on a space-constrained
     system when 'innodb_file_per_table' is disabled.  Set up a separate
     instance in such cases, so that you can drop the entire instance to
     reclaim the space.

     'innodb_file_per_table' is enabled by default.  Consider disabling
     it if backward compatibility with MySQL 5.5 or 5.1 is a concern.
     This will prevent 'ALTER TABLE' from moving
     'InnoDB' tables from the system
     tablespace to individual '.ibd' files.

     'innodb_file_per_table' is dynamic and can be set 'ON' or 'OFF'
     using 'SET GLOBAL'.  You can also set this option in the MySQL
     configuration file ('my.cnf' or 'my.ini') but this requires
     shutting down and restarting the server.

     Dynamically changing the value requires the 'SUPER' privilege and
     immediately affects the operation of all connections.

   *
     'innodb_fill_factor'

     Property                             Value

     *Command-Line Format*                '--innodb-fill-factor=#'

     *Introduced*                         5.7.5

     *System Variable*                    'innodb_fill_factor'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '100'

     *Minimum Value*                      '10'

     *Maximum Value*                      '100'

     'InnoDB' performs a bulk load when creating or rebuilding indexes.
     This method of index creation is known as a 'sorted index build'.

     'innodb_fill_factor' defines the percentage of space on each B-tree
     page that is filled during a sorted index build, with the remaining
     space reserved for future index growth.  For example, setting
     'innodb_fill_factor' to 80 reserves 20 percent of the space on each
     B-tree page for future index growth.  Actual percentages may vary.
     The 'innodb_fill_factor' setting is interpreted as a hint rather
     than a hard limit.

     An 'innodb_fill_factor' setting of 100 leaves 1/16 of the space in
     clustered index pages free for future index growth.

     'innodb_fill_factor' applies to both B-tree leaf and non-leaf
     pages.  It does not apply to external pages used for 'TEXT'
     or 'BLOB' entries.

     For more information, see sorted-index-builds.

   *
     'innodb_flush_log_at_timeout'

     Property                             Value

     *System Variable*                    'innodb_flush_log_at_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '2700'

     Write and flush the logs every N seconds.
     'innodb_flush_log_at_timeout' allows the timeout period between
     flushes to be increased in order to reduce flushing and avoid
     impacting performance of binary log group commit.  The default
     setting for 'innodb_flush_log_at_timeout' is once per second.

   *
     'innodb_flush_log_at_trx_commit'

     Property                             Value

     *Command-Line Format*                '--innodb-flush-log-at-trx-commit[=#]'

     *System Variable*                    'innodb_flush_log_at_trx_commit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      '1'

     *Valid Values*                       '0' '1' '2'

     Controls the balance between strict ACID compliance for commit
     operations and higher performance that is possible when
     commit-related I/O operations are rearranged and done in batches.
     You can achieve better performance by changing the default value
     but then you can lose up to a second of transactions in a crash.

        * The default value of 1 is required for full ACID compliance.
          With this value, the contents of the 'InnoDB' log buffer are
          written out to the log file at each transaction commit and the
          log file is flushed to disk.

        * With a value of 0, the contents of the 'InnoDB' log buffer are
          written to the log file approximately once per second and the
          log file is flushed to disk.  No writes from the log buffer to
          the log file are performed at transaction commit.
          Once-per-second flushing is not guaranteed to happen every
          second due to process scheduling issues.  Because the flush to
          disk operation only occurs approximately once per second, you
          can lose up to a second of transactions with any
          'mysqld' process crash.

        * With a value of 2, the contents of the 'InnoDB' log buffer are
          written to the log file after each transaction commit and the
          log file is flushed to disk approximately once per second.
          Once-per-second flushing is not 100% guaranteed to happen
          every second, due to process scheduling issues.  Because the
          flush to disk operation only occurs approximately once per
          second, you can lose up to a second of transactions in an
          operating system crash or a power outage.

        * 'InnoDB' log flushing frequency is controlled by
          'innodb_flush_log_at_timeout', which allows you to set log
          flushing frequency to N seconds (where N is '1 ... 2700', with
          a default value of 1).  However, any 'mysqld'.
          process crash can erase up to N seconds of transactions.

        * DDL changes and other internal 'InnoDB' activities flush the
          'InnoDB' log independent of the
          'innodb_flush_log_at_trx_commit' setting.

        * 'InnoDB' crash recovery works regardless of the
          'innodb_flush_log_at_trx_commit' setting.  Transactions are
          either applied entirely or erased entirely.

     For durability and consistency in a replication setup that uses
     'InnoDB' with transactions:

        * If binary logging is enabled, set 'sync_binlog=1'.

        * Always set 'innodb_flush_log_at_trx_commit=1'.

     *Caution*:

     Many operating systems and some disk hardware fool the
     flush-to-disk operation.  They may tell 'mysqld'.
     that the flush has taken place, even though it has not.  In this
     case, the durability of transactions is not guaranteed even with
     the setting 1, and in the worst case, a power outage can corrupt
     'InnoDB' data.  Using a battery-backed disk cache in the SCSI disk
     controller or in the disk itself speeds up file flushes, and makes
     the operation safer.  You can also try to disable the caching of
     disk writes in hardware caches.

   *
     'innodb_flush_method'

     Property                             Value

     *Command-Line Format*                '--innodb-flush-method=name'

     *System Variable*                    'innodb_flush_method'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (Windows)                     string

     *Type* (Unix)                        string

     *Default Value* (Windows)            'NULL'

     *Default Value* (Unix)               'NULL'

     *Valid Values* (Windows)             'async_unbuffered' 'normal'
                                          'unbuffered'

     *Valid Values* (Unix)                'fsync' 'O_DSYNC' 'littlesync'
                                          'nosync' 'O_DIRECT'
                                          'O_DIRECT_NO_FSYNC'

     Defines the method used to flush data to 'InnoDB' data files and
     log files, which can affect I/O throughput.

     If 'innodb_flush_method' is set to 'NULL' on a Unix-like system,
     the 'fsync' option is used by default.  If 'innodb_flush_method' is
     set to 'NULL' on Windows, the 'async_unbuffered' option is used by
     default.

     The 'innodb_flush_method' options for Unix-like systems include:

        * 'fsync': 'InnoDB' uses the 'fsync()' system call to flush both
          the data and log files.  'fsync' is the default setting.

        * 'O_DSYNC': 'InnoDB' uses 'O_SYNC' to open and flush the log
          files, and 'fsync()' to flush the data files.  'InnoDB' does
          not use 'O_DSYNC' directly because there have been problems
          with it on many varieties of Unix.

        * 'littlesync': This option is used for internal performance
          testing and is currently unsupported.  Use at your own risk.

        * 'nosync': This option is used for internal performance testing
          and is currently unsupported.  Use at your own risk.

        * 'O_DIRECT': 'InnoDB' uses 'O_DIRECT' (or 'directio()' on
          Solaris) to open the data files, and uses 'fsync()' to flush
          both the data and log files.  This option is available on some
          GNU/Linux versions, FreeBSD, and Solaris.

        * 'O_DIRECT_NO_FSYNC': 'InnoDB' uses 'O_DIRECT' during flushing
          I/O, but skips the 'fsync()' system call afterward.  This
          setting is suitable for some types of file systems but not
          others.  For example, it is not suitable for XFS. If you are
          not sure whether the file system you use requires an
          'fsync()', for example to preserve all file metadata, use
          'O_DIRECT' instead.

     The 'innodb_flush_method' options for Windows systems include:

        * 'async_unbuffered': 'InnoDB' uses Windows asynchronous I/O and
          non-buffered I/O. 'async_unbuffered' is the default setting on
          Windows systems.

          Running MySQL server on a 4K sector hard drive on Windows is
          not supported with 'async_unbuffered'.  The workaround is to
          use 'innodb_flush_method=normal'.

        * 'normal': 'InnoDB' uses simulated asynchronous I/O and
          buffered I/O.

        * 'unbuffered': 'InnoDB' uses simulated asynchronous I/O and
          non-buffered I/O.

     How each setting affects performance depends on hardware
     configuration and workload.  Benchmark your particular
     configuration to decide which setting to use, or whether to keep
     the default setting.  Examine the 'Innodb_data_fsyncs' status
     variable to see the overall number of 'fsync()' calls for each
     setting.  The mix of read and write operations in your workload can
     affect how a setting performs.  For example, on a system with a
     hardware RAID controller and battery-backed write cache, 'O_DIRECT'
     can help to avoid double buffering between the 'InnoDB' buffer pool
     and the operating system file system cache.  On some systems where
     'InnoDB' data and log files are located on a SAN, the default value
     or 'O_DSYNC' might be faster for a read-heavy workload with mostly
     'SELECT' statements.  Always test this parameter with hardware and
     workload that reflect your production environment.  For general I/O
     tuning advice, see optimizing-innodb-diskio.

   *
     'innodb_flush_neighbors'

     Property                             Value

     *Command-Line Format*                '--innodb-flush-neighbors'

     *System Variable*                    'innodb_flush_neighbors'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      '1'

     *Valid Values*                       '0' '1' '2'

     Specifies whether flushing a page from the 'InnoDB' buffer pool
     also flushes other dirty pages in the same extent.

        * The default value of 1 flushes contiguous dirty pages in the
          same extent from the buffer pool.

        * A setting of 0 turns 'innodb_flush_neighbors' off and no other
          dirty pages are flushed from the buffer pool.

        * A setting of 2 flushes dirty pages in the same extent from the
          buffer pool.

     When the table data is stored on a traditional HDD storage device,
     flushing such neighbor pages in one operation reduces I/O overhead
     (primarily for disk seek operations) compared to flushing
     individual pages at different times.  For table data stored on SSD,
     seek time is not a significant factor and you can turn this setting
     off to spread out write operations.  For related information, see
     innodb-lru-background-flushing.

   *
     'innodb_flush_sync'

     Property                             Value

     *Command-Line Format*                '--innodb-flush-sync=#'

     *Introduced*                         5.7.8

     *System Variable*                    'innodb_flush_sync'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     The 'innodb_flush_sync' parameter, which is enabled by default,
     causes the 'innodb_io_capacity' setting to be ignored for bursts of
     I/O activity that occur at checkpoints.  To adhere to the limit on
     'InnoDB' background I/O activity defined by the
     'innodb_io_capacity' setting, disable 'innodb_flush_sync'.

     For related information, see
     innodb-performance-thread_io_rate.

   *
     'innodb_flushing_avg_loops'

     Property                             Value

     *Command-Line Format*                '--innodb-flushing-avg-loops=#'

     *System Variable*                    'innodb_flushing_avg_loops'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '30'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1000'

     Number of iterations for which 'InnoDB' keeps the previously
     calculated snapshot of the flushing state, controlling how quickly
     adaptive flushing responds to changing workloads.  Increasing the
     value makes the rate of flush operations change smoothly and
     gradually as the workload changes.  Decreasing the value makes
     adaptive flushing adjust quickly to workload changes, which can
     cause spikes in flushing activity if the workload increases and
     decreases suddenly.

     For related information, see
     innodb-lru-background-flushing.

   *
     'innodb_force_load_corrupted'

     Property                             Value

     *Command-Line Format*                '--innodb-force-load-corrupted'

     *System Variable*                    'innodb_force_load_corrupted'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Permits 'InnoDB' to load tables at startup that are marked as
     corrupted.  Use only during troubleshooting, to recover data that
     is otherwise inaccessible.  When troubleshooting is complete,
     disable this setting and restart the server.

   *
     'innodb_force_recovery'

     Property                             Value

     *Command-Line Format*                '--innodb-force-recovery=#'

     *System Variable*                    'innodb_force_recovery'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '6'

     The crash recovery mode, typically only changed in serious
     troubleshooting situations.  Possible values are from 0 to 6.  For
     the meanings of these values and important information about
     'innodb_force_recovery', see forcing-innodb-recovery.

     *Warning*:

     Only set this variable to a value greater than 0 in an emergency
     situation so that you can start 'InnoDB' and dump your tables.  As
     a safety measure, 'InnoDB' prevents 'INSERT',
     'UPDATE', or 'DELETE' operations when
     'innodb_force_recovery' is greater than 0.  An
     'innodb_force_recovery' setting of 4 or greater places 'InnoDB'
     into read-only mode.

     These restrictions may cause replication administration commands to
     fail with an error, as replication options such as
     '--relay-log-info-repository=TABLE' and
     '--master-info-repository=TABLE' store information in 'InnoDB'
     tables.

   *
     'innodb_ft_aux_table'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-aux-table=#' (>=
                                          5.7.2)

     *System Variable*                    'innodb_ft_aux_table'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     Specifies the qualified name of an 'InnoDB' table containing a
     'FULLTEXT' index.  This variable is intended for diagnostic
     purposes.

     After you set this variable to a name in the format
     'DB_NAME/TABLE_NAME', the 'INFORMATION_SCHEMA' tables
     'INNODB_FT_INDEX_TABLE',
     'INNODB_FT_INDEX_CACHE',
     'INNODB_FT_CONFIG',
     'INNODB_FT_DELETED', and
     'INNODB_FT_BEING_DELETED' show
     information about the search index for the specified table.

     For more information, see
     innodb-information-schema-fulltext_index-tables.

   *
     'innodb_ft_cache_size'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-cache-size=#'

     *System Variable*                    'innodb_ft_cache_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '8000000'

     *Minimum Value*                      '1600000'

     *Maximum Value*                      '80000000'

     The memory allocated, in bytes, for the 'InnoDB' 'FULLTEXT' search
     index cache, which holds a parsed document in memory while creating
     an 'InnoDB' 'FULLTEXT' index.  Index inserts and updates are only
     committed to disk when the 'innodb_ft_cache_size' size limit is
     reached.  'innodb_ft_cache_size' defines the cache size on a per
     table basis.  To set a global limit for all tables, see
     'innodb_ft_total_cache_size'.

     For more information, see innodb-fulltext-index-cache.

   *
     'innodb_ft_enable_diag_print'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-enable-diag-print=#'

     *System Variable*                    'innodb_ft_enable_diag_print'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether to enable additional full-text search (FTS) diagnostic
     output.  This option is primarily intended for advanced FTS
     debugging and will not be of interest to most users.  Output is
     printed to the error log and includes information such as:

        * FTS index sync progress (when the FTS cache limit is reached).
          For example:

               FTS SYNC for table test, deleted count: 100 size: 10000 bytes
               SYNC words: 100

        * FTS optimize progress.  For example:

               FTS start optimize test
               FTS_OPTIMIZE: optimize "mysql"
               FTS_OPTIMIZE: processed "mysql"

        * FTS index build progress.  For example:

               Number of doc processed: 1000

        * For FTS queries, the query parsing tree, word weight, query
          processing time, and memory usage are printed.  For example:

               FTS Search Processing time: 1 secs: 100 millisec: row(s) 10000
               Full Search Memory: 245666 (bytes),  Row: 10000

   *
     'innodb_ft_enable_stopword'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-enable-stopword=#'

     *System Variable*                    'innodb_ft_enable_stopword'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Specifies that a set of stopwords is associated with an 'InnoDB'
     'FULLTEXT' index at the time the index is created.  If the
     'innodb_ft_user_stopword_table' option is set, the stopwords are
     taken from that table.  Else, if the
     'innodb_ft_server_stopword_table' option is set, the stopwords are
     taken from that table.  Otherwise, a built-in set of default
     stopwords is used.

     For more information, see fulltext-stopwords.

   *
     'innodb_ft_max_token_size'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-max-token-size=#'

     *System Variable*                    'innodb_ft_max_token_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Type*                               integer

     *Default Value*                      '84'

     *Default Value*                      '84'

     *Minimum Value*                      '10'

     *Minimum Value*                      '10'

     *Maximum Value* (>= 5.7.3)           '84'

     *Maximum Value* (<= 5.7.2)           '252'

     *Maximum Value*                      '84'

     Maximum character length of words that are stored in an 'InnoDB'
     'FULLTEXT' index.  Setting a limit on this value reduces the size
     of the index, thus speeding up queries, by omitting long keywords
     or arbitrary collections of letters that are not real words and are
     not likely to be search terms.

     For more information, see fulltext-fine-tuning.

   *
     'innodb_ft_min_token_size'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-min-token-size=#'

     *System Variable*                    'innodb_ft_min_token_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '3'

     *Minimum Value*                      '0'

     *Maximum Value*                      '16'

     Minimum length of words that are stored in an 'InnoDB' 'FULLTEXT'
     index.  Increasing this value reduces the size of the index, thus
     speeding up queries, by omitting common words that are unlikely to
     be significant in a search context, such as the English words 'a'
     and 'to'.  For content using a CJK (Chinese, Japanese, Korean)
     character set, specify a value of 1.

     For more information, see fulltext-fine-tuning.

   *
     'innodb_ft_num_word_optimize'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-num-word-optimize=#'

     *System Variable*                    'innodb_ft_num_word_optimize'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '2000'

     Number of words to process during each 'OPTIMIZE TABLE'
     operation on an 'InnoDB' 'FULLTEXT' index.  Because
     a bulk insert or update operation to a table containing a full-text
     search index could require substantial index maintenance to
     incorporate all changes, you might do a series of 'OPTIMIZE TABLE'
     statements, each picking up where the last
     left off.

     For more information, see fulltext-fine-tuning.

   *
     'innodb_ft_result_cache_limit'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-result-cache-limit=#'

     *Introduced*                         5.7.2

     *System Variable*                    'innodb_ft_result_cache_limit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (Windows, >= 5.7.2, <=        integer
     5.7.3)

     *Type* (Unix, 64-bit platforms, >=   integer
     5.7.2, <= 5.7.3)

     *Type* (Unix, 32-bit platforms, >=   integer
     5.7.2, <= 5.7.3)

     *Type* (>= 5.7.4)                    integer

     *Default Value* (Windows, >=         '2000000000'
     5.7.2, <= 5.7.3)

     *Default Value* (Unix, 64-bit        '2000000000'
     platforms, >= 5.7.2, <= 5.7.3)

     *Default Value* (Unix, 32-bit        '2000000000'
     platforms, >= 5.7.2, <= 5.7.3)

     *Default Value* (>= 5.7.4)           '2000000000'

     *Minimum Value* (Windows, >=         '1000000'
     5.7.2, <= 5.7.3)

     *Minimum Value* (Unix, 64-bit        '1000000'
     platforms, >= 5.7.2, <= 5.7.3)

     *Minimum Value* (Unix, 32-bit        '1000000'
     platforms, >= 5.7.2, <= 5.7.3)

     *Minimum Value* (>= 5.7.4)           '1000000'

     *Maximum Value* (Windows, >=         '2**32-1'
     5.7.2, <= 5.7.3)

     *Maximum Value* (Unix, 64-bit        '2**64-1'
     platforms, >= 5.7.2, <= 5.7.3)

     *Maximum Value* (Unix, 32-bit        '2**32-1'
     platforms, >= 5.7.2, <= 5.7.3)

     *Maximum Value* (>= 5.7.4)           '2**32-1'

     The 'InnoDB' full-text search query result cache limit (defined in
     bytes) per full-text search query or per thread.  Intermediate and
     final 'InnoDB' full-text search query results are handled in
     memory.  Use 'innodb_ft_result_cache_limit' to place a size limit
     on the full-text search query result cache to avoid excessive
     memory consumption in case of very large 'InnoDB' full-text search
     query results (millions or hundreds of millions of rows, for
     example).  Memory is allocated as required when a full-text search
     query is processed.  If the result cache size limit is reached, an
     error is returned indicating that the query exceeds the maximum
     allowed memory.

     The maximum value of 'innodb_ft_result_cache_limit' for all
     platform types and bit sizes is 2**32-1.

   *
     'innodb_ft_server_stopword_table'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-server-stopword-table=db_name/table_name'

     *System Variable*                    'innodb_ft_server_stopword_table'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     This option is used to specify your own 'InnoDB' 'FULLTEXT' index
     stopword list for all 'InnoDB' tables.  To configure your own
     stopword list for a specific 'InnoDB' table, use
     'innodb_ft_user_stopword_table'.

     Set 'innodb_ft_server_stopword_table' to the name of the table
     containing a list of stopwords, in the format 'DB_NAME/TABLE_NAME'.

     The stopword table must exist before you configure
     'innodb_ft_server_stopword_table'.  'innodb_ft_enable_stopword'
     must be enabled and 'innodb_ft_server_stopword_table' option must
     be configured before you create the 'FULLTEXT' index.

     The stopword table must be an 'InnoDB' table, containing a single
     'VARCHAR' column named 'value'.

     For more information, see fulltext-stopwords.

   *
     'innodb_ft_sort_pll_degree'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-sort-pll-degree=#'

     *System Variable*                    'innodb_ft_sort_pll_degree'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '2'

     *Minimum Value*                      '1'

     *Maximum Value*                      '32'

     Number of threads used in parallel to index and tokenize text in an
     'InnoDB' 'FULLTEXT' index when building a search index.

     For related information, see innodb-fulltext-index, and
     'innodb_sort_buffer_size'.

   *
     'innodb_ft_total_cache_size'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-total-cache-size=#'

     *Introduced*                         5.7.2

     *System Variable*                    'innodb_ft_total_cache_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '640000000'

     *Minimum Value*                      '32000000'

     *Maximum Value*                      '1600000000'

     The total memory allocated, in bytes, for the 'InnoDB' full-text
     search index cache for all tables.  Creating numerous tables, each
     with a 'FULLTEXT' search index, could consume a significant portion
     of available memory.  'innodb_ft_total_cache_size' defines a global
     memory limit for all full-text search indexes to help avoid
     excessive memory consumption.  If the global limit is reached by an
     index operation, a forced sync is triggered.

     For more information, see innodb-fulltext-index-cache.

   *
     'innodb_ft_user_stopword_table'

     Property                             Value

     *Command-Line Format*                '--innodb-ft-user-stopword-table=db_name/table_name'

     *System Variable*                    'innodb_ft_user_stopword_table'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'NULL'

     This option is used to specify your own 'InnoDB' 'FULLTEXT' index
     stopword list on a specific table.  To configure your own stopword
     list for all 'InnoDB' tables, use
     'innodb_ft_server_stopword_table'.

     Set 'innodb_ft_user_stopword_table' to the name of the table
     containing a list of stopwords, in the format 'DB_NAME/TABLE_NAME'.

     The stopword table must exist before you configure
     'innodb_ft_user_stopword_table'.  'innodb_ft_enable_stopword' must
     be enabled and 'innodb_ft_user_stopword_table' must be configured
     before you create the 'FULLTEXT' index.

     The stopword table must be an 'InnoDB' table, containing a single
     'VARCHAR' column named 'value'.

     For more information, see fulltext-stopwords.

   *
     'innodb_io_capacity'

     Property                             Value

     *Command-Line Format*                '--innodb-io-capacity=#'

     *System Variable*                    'innodb_io_capacity'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '200'

     *Default Value* (32-bit platforms)   '200'

     *Minimum Value* (64-bit platforms)   '100'

     *Minimum Value* (32-bit platforms)   '100'

     *Maximum Value* (64-bit platforms)   '2**64-1'

     *Maximum Value* (32-bit platforms)   '2**32-1'

     The 'innodb_io_capacity' parameter sets an upper limit on the
     number of I/O operations performed per second by 'InnoDB'
     background tasks, such as flushing pages from the buffer pool and
     merging data from the change buffer.

     The 'innodb_io_capacity' limit is a total limit for all buffer pool
     instances.  When dirty pages are flushed, the limit is divided
     equally among buffer pool instances.

     'innodb_io_capacity' should be set to approximately the number of
     I/O operations that the system can perform per second.  Ideally,
     keep the setting as low as practical, but not so low that
     background activities fall behind.  If the value is too high, data
     is removed from the buffer pool and insert buffer too quickly for
     caching to provide a significant benefit.

     The default value is 200.  For busy systems capable of higher I/O
     rates, you can set a higher value to help the server handle the
     background maintenance work associated with a high rate of row
     changes.

     In general, you can increase the value as a function of the number
     of drives used for 'InnoDB'. I/O. For
     example, you can increase the value on systems that use multiple
     disks or solid-state disks (SSD).

     The default setting of 200 is generally sufficient for a lower-end
     SSD. For a higher-end, bus-attached SSD, consider a higher setting
     such as 1000, for example.  For systems with individual 5400 RPM or
     7200 RPM drives, you might lower the value to '100', which
     represents an estimated proportion of the I/O operations per second
     (IOPS) available to older-generation disk drives that can perform
     about 100 IOPS.

     Although you can specify a very high value such as one million, in
     practice such large values have little if any benefit.  Generally,
     a value of 20000 or higher is not recommended unless you have
     proven that lower values are insufficient for your workload.

     Consider write workload when tuning 'innodb_io_capacity'.  Systems
     with large write workloads are likely to benefit from a higher
     setting.  A lower setting may be sufficient for systems with a
     small write workload.

     You can set 'innodb_io_capacity' to any number 100 or greater to a
     maximum defined by 'innodb_io_capacity_max'.  'innodb_io_capacity'
     can be set in the MySQL option file ('my.cnf' or 'my.ini') or
     changed dynamically using a 'SET GLOBAL' statement, which requires
     the 'SUPER' privilege.

     The 'innodb_flush_sync' configuration option causes the
     'innodb_io_capacity' setting to be ignored during bursts of I/O
     activity that occur at checkpoints.  'innodb_flush_sync' is enabled
     by default.

     See innodb-performance-thread_io_rate for more information.
     For general information about 'InnoDB' I/O performance, see
     optimizing-innodb-diskio.

   *
     'innodb_io_capacity_max'

     Property                             Value

     *Command-Line Format*                '--innodb-io-capacity-max=#'

     *System Variable*                    'innodb_io_capacity_max'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (Windows, 64-bit platforms)   integer

     *Type* (Unix, 64-bit platforms)      integer

     *Type* (32-bit platforms)            integer

     *Default Value* (Windows, 64-bit     'see description'
     platforms)

     *Default Value* (Unix, 64-bit        'see description'
     platforms)

     *Default Value* (32-bit platforms)   'see description'

     *Minimum Value* (Windows, 64-bit     '100'
     platforms)

     *Minimum Value* (Unix, 64-bit        '100'
     platforms)

     *Minimum Value* (32-bit platforms)   '100'

     *Maximum Value* (Windows, 64-bit     '2**32-1'
     platforms)

     *Maximum Value* (Unix, 64-bit        '2**64-1'
     platforms)

     *Maximum Value* (32-bit platforms)   '2**32-1'

     If flushing activity falls behind, 'InnoDB' can flush more
     aggressively than the limit imposed by 'innodb_io_capacity'.
     'innodb_io_capacity_max' defines an upper limit the number of I/O
     operations performed per second by 'InnoDB' background tasks in
     such situations.

     The 'innodb_io_capacity_max' setting is a total limit for all
     buffer pool instances.

     If you specify an 'innodb_io_capacity' setting at startup but do
     not specify a value for 'innodb_io_capacity_max',
     'innodb_io_capacity_max' defaults to twice the value of
     'innodb_io_capacity', with a minimum value of 2000.

     When configuring 'innodb_io_capacity_max', twice the
     'innodb_io_capacity' is often a good starting point.  The default
     value of 2000 is intended for workloads that use a solid-state disk
     (SSD) or more than one regular disk drive.  A setting of 2000 is
     likely too high for workloads that do not use SSD or multiple disk
     drives, and could allow too much flushing.  For a single regular
     disk drive, a setting between 200 and 400 is recommended.  For a
     high-end, bus-attached SSD, consider a higher setting such as 2500.
     As with the 'innodb_io_capacity' setting, keep the setting as low
     as practical, but not so low that 'InnoDB' cannot sufficiently
     extend beyond the 'innodb_io_capacity' limit, if necessary.

     Consider write workload when tuning 'innodb_io_capacity_max'.
     Systems with large write workloads may benefit from a higher
     setting.  A lower setting may be sufficient for systems with a
     small write workload.

     'innodb_io_capacity_max' cannot be set to a value lower than the
     'innodb_io_capacity' value.

     Setting 'innodb_io_capacity_max' to 'DEFAULT' using a 'SET'
     statement ('SET GLOBAL
     innodb_io_capacity_max=DEFAULT') sets 'innodb_io_capacity_max' to
     the maximum value.

     For related information, see
     innodb-lru-background-flushing.

   *
     'innodb_large_prefix'

     Property                             Value

     *Command-Line Format*                '--innodb-large-prefix'

     *Deprecated*                         5.7.7

     *System Variable*                    'innodb_large_prefix'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value* (>= 5.7.7)           'ON'

     *Default Value* (<= 5.7.6)           'OFF'

     When this option is enabled, index key prefixes longer than 767
     bytes (up to 3072 bytes) are allowed for 'InnoDB' tables that use
     'DYNAMIC' or 'COMPRESSED' row format.  See
     innodb-restrictions for maximums associated with index key
     prefixes under various settings.

     For tables that use 'REDUNDANT' or 'COMPACT' row format, this
     option does not affect the permitted index key prefix length.

     'innodb_large_prefix' is enabled by default in MySQL 5.7.  This
     change coincides with the default value change for
     'innodb_file_format', which is set to 'Barracuda' by default in
     MySQL 5.7.  Together, these default value changes allow larger
     index key prefixes to be created when using 'DYNAMIC' or
     'COMPRESSED' row format.  If either option is set to a non-default
     value, index key prefixes larger than 767 bytes are silently
     truncated.

     'innodb_large_prefix' is deprecated and will be removed in a future
     release.  'innodb_large_prefix' was introduced in MySQL 5.5 to
     disable large index key prefixes for compatibility with earlier
     versions of 'InnoDB' that do not support large index key prefixes.

   *
     'innodb_limit_optimistic_insert_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-limit-optimistic-insert-debug=#'

     *System Variable*                    'innodb_limit_optimistic_insert_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '2**32-1'

     Limits the number of records per B-tree page.  A default value of 0
     means that no limit is imposed.  This option is only available if
     debugging support is compiled in using the 'WITH_DEBUG' 'CMake'
     option.

   *
     'innodb_lock_wait_timeout'

     Property                             Value

     *Command-Line Format*                '--innodb-lock-wait-timeout=#'

     *System Variable*                    'innodb_lock_wait_timeout'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '50'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1073741824'

     The length of time in seconds an 'InnoDB' transaction waits for a
     row lock before giving up.  The default value is 50 seconds.  A
     transaction that tries to access a row that is locked by another
     'InnoDB' transaction waits at most this many seconds for write
     access to the row before issuing the following error:

          ERROR 1205 (HY000): Lock wait timeout exceeded; try restarting transaction

     When a lock wait timeout occurs, the current statement is rolled
     back (not the entire transaction).  To have the entire transaction
     roll back, start the server with the '--innodb_rollback_on_timeout'
     option.  See also innodb-error-handling.

     You might decrease this value for highly interactive applications
     or OLTP systems, to display user feedback quickly or put the update
     into a queue for processing later.  You might increase this value
     for long-running back-end operations, such as a transform step in a
     data warehouse that waits for other large insert or update
     operations to finish.

     'innodb_lock_wait_timeout' applies to 'InnoDB' row locks only.  A
     MySQL table lock does not happen inside 'InnoDB' and this timeout
     does not apply to waits for table locks.

     The lock wait timeout value does not apply to deadlocks when
     'innodb_deadlock_detect' is enabled (the default) because 'InnoDB'
     detects deadlocks immediately and rolls back one of the deadlocked
     transactions.  When 'innodb_deadlock_detect' is disabled, 'InnoDB'
     relies on 'innodb_lock_wait_timeout' for transaction rollback when
     a deadlock occurs.  See innodb-deadlock-detection.

     'innodb_lock_wait_timeout' can be set at runtime with the 'SET
     GLOBAL' or 'SET SESSION' statement.  Changing the 'GLOBAL' setting
     requires the 'SUPER' privilege and affects the operation of all
     clients that subsequently connect.  Any client can change the
     'SESSION' setting for 'innodb_lock_wait_timeout', which affects
     only that client.

   *
     'innodb_locks_unsafe_for_binlog'

     Property                             Value

     *Command-Line Format*                '--innodb-locks-unsafe-for-binlog'

     *Deprecated*                         Yes

     *System Variable*                    'innodb_locks_unsafe_for_binlog'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     This variable affects how 'InnoDB' uses gap locking for searches
     and index scans.  'innodb_locks_unsafe_for_binlog' is deprecated
     and will be removed in a future MySQL release.

     Normally, 'InnoDB' uses an algorithm called next-key locking that
     combines index-row locking with gap locking.  'InnoDB' performs
     row-level locking in such a way that when it searches or scans a
     table index, it sets shared or exclusive locks on the index records
     it encounters.  Thus, row-level locks are actually index-record
     locks.  In addition, a next-key lock on an index record also
     affects the gap before the index record.  That is, a next-key lock
     is an index-record lock plus a gap lock on the gap preceding the
     index record.  If one session has a shared or exclusive lock on
     record 'R' in an index, another session cannot insert a new index
     record in the gap immediately before 'R' in the index order.  See
     innodb-locking.

     By default, the value of 'innodb_locks_unsafe_for_binlog' is 0
     (disabled), which means that gap locking is enabled: 'InnoDB' uses
     next-key locks for searches and index scans.  To enable the
     variable, set it to 1.  This causes gap locking to be disabled:
     'InnoDB' uses only index-record locks for searches and index scans.

     Enabling 'innodb_locks_unsafe_for_binlog' does not disable the use
     of gap locking for foreign-key constraint checking or duplicate-key
     checking.

     The effects of enabling 'innodb_locks_unsafe_for_binlog' are the
     same as setting the transaction isolation level to 'READ
     COMMITTED', with these exceptions:

        * Enabling 'innodb_locks_unsafe_for_binlog' is a global setting
          and affects all sessions, whereas the isolation level can be
          set globally for all sessions, or individually per session.

        * 'innodb_locks_unsafe_for_binlog' can be set only at server
          startup, whereas the isolation level can be set at startup or
          changed at runtime.

     'READ COMMITTED' therefore offers finer and more flexible control
     than 'innodb_locks_unsafe_for_binlog'.  For more information about
     the effect of isolation level on gap locking, see
     innodb-transaction-isolation-levels.

     Enabling 'innodb_locks_unsafe_for_binlog' may cause phantom
     problems because other sessions can insert new rows into the gaps
     when gap locking is disabled.  Suppose that there is an index on
     the 'id' column of the 'child' table and that you want to read and
     lock all rows from the table having an identifier value larger than
     100, with the intention of updating some column in the selected
     rows later:

          SELECT * FROM child WHERE id > 100 FOR UPDATE;

     The query scans the index starting from the first record where the
     'id' is greater than 100.  If the locks set on the index records in
     that range do not lock out inserts made in the gaps, another
     session can insert a new row into the table.  Consequently, if you
     were to execute the same 'SELECT' again within the
     same transaction, you would see a new row in the result set
     returned by the query.  This also means that if new items are added
     to the database, 'InnoDB' does not guarantee serializability.
     Therefore, if 'innodb_locks_unsafe_for_binlog' is enabled, 'InnoDB'
     guarantees at most an isolation level of 'READ COMMITTED'.
     (Conflict serializability is still guaranteed.)  For more
     information about phantoms, see innodb-next-key-locking.

     Enabling 'innodb_locks_unsafe_for_binlog' has additional effects:

        * For 'UPDATE' or 'DELETE'.
          statements, 'InnoDB' holds locks only for rows that it updates
          or deletes.  Record locks for nonmatching rows are released
          after MySQL has evaluated the 'WHERE' condition.  This greatly
          reduces the probability of deadlocks, but they can still
          happen.

        * For 'UPDATE' statements, if a row is already
          locked, 'InnoDB' performs a 'semi-consistent' read, returning
          the latest committed version to MySQL so that MySQL can
          determine whether the row matches the 'WHERE' condition of the
          'UPDATE'.  If the row matches (must be updated),
          MySQL reads the row again and this time 'InnoDB' either locks
          it or waits for a lock on it.

     Consider the following example, beginning with this table:

          CREATE TABLE t (a INT NOT NULL, b INT) ENGINE = InnoDB;
          INSERT INTO t VALUES (1,2),(2,3),(3,2),(4,3),(5,2);
          COMMIT;

     In this case, table has no indexes, so searches and index scans use
     the hidden clustered index for record locking (see
     innodb-index-types).

     Suppose that one client performs an 'UPDATE' using
     these statements:

          SET autocommit = 0;
          UPDATE t SET b = 5 WHERE b = 3;

     Suppose also that a second client performs an 'UPDATE'
     by executing these statements following those of the first
     client:

          SET autocommit = 0;
          UPDATE t SET b = 4 WHERE b = 2;

     As 'InnoDB' executes each 'UPDATE', it first acquires
     an exclusive lock for each row, and then determines whether to
     modify it.  If 'InnoDB' does not modify the row and
     'innodb_locks_unsafe_for_binlog' is enabled, it releases the lock.
     Otherwise, 'InnoDB' retains the lock until the end of the
     transaction.  This affects transaction processing as follows.

     If 'innodb_locks_unsafe_for_binlog' is disabled, the first
     'UPDATE' acquires x-locks and does not release any of
     them:

          x-lock(1,2); retain x-lock
          x-lock(2,3); update(2,3) to (2,5); retain x-lock
          x-lock(3,2); retain x-lock
          x-lock(4,3); update(4,3) to (4,5); retain x-lock
          x-lock(5,2); retain x-lock

     The second 'UPDATE' blocks as soon as it tries to
     acquire any locks (because the first update has retained locks on
     all rows), and does not proceed until the first 'UPDATE'
     commits or rolls back:

          x-lock(1,2); block and wait for first UPDATE to commit or roll back

     If 'innodb_locks_unsafe_for_binlog' is enabled, the first
     'UPDATE' acquires x-locks and releases those for rows that
     it does not modify:

          x-lock(1,2); unlock(1,2)
          x-lock(2,3); update(2,3) to (2,5); retain x-lock
          x-lock(3,2); unlock(3,2)
          x-lock(4,3); update(4,3) to (4,5); retain x-lock
          x-lock(5,2); unlock(5,2)

     For the second 'UPDATE', 'InnoDB' does a 'semi-consistent' read,
     returning the latest committed version of each row to MySQL so that
     MySQL can determine whether the row matches the 'WHERE' condition
     of the 'UPDATE'.:

          x-lock(1,2); update(1,2) to (1,4); retain x-lock
          x-lock(2,3); unlock(2,3)
          x-lock(3,2); update(3,2) to (3,4); retain x-lock
          x-lock(4,3); unlock(4,3)
          x-lock(5,2); update(5,2) to (5,4); retain x-lock

   *
     'innodb_log_buffer_size'

     Property                             Value

     *Command-Line Format*                '--innodb-log-buffer-size=#'

     *System Variable*                    'innodb_log_buffer_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '16777216'

     *Default Value* (<= 5.7.5)           '8388608'

     *Minimum Value* (>= 5.7.6)           '1048576'

     *Minimum Value* (<= 5.7.5)           '262144'

     *Maximum Value*                      '4294967295'

     The size in bytes of the buffer that 'InnoDB' uses to write to the
     log files on disk.  The default value changed from 8MB to 16MB with
     the introduction of 32k and 64k 'innodb_page_size' values.  A large
     log buffer enables large transactions to run without the need to
     write the log to disk before the transactions commit.  Thus, if you
     have transactions that update, insert, or delete many rows, making
     the log buffer larger saves disk I/O. For related information, see
     innodb-startup-memory-configuration, and
     optimizing-innodb-logging.  For general I/O tuning advice, see
     optimizing-innodb-diskio.

   *
     'innodb_log_checksum_algorithm'

     Property                             Value

     *Command-Line Format*                '--innodb-log-checksum-algorithm=#'

     *Introduced*                         5.7.8

     *Removed*                            5.7.9

     *System Variable*                    'innodb_log_checksum_algorithm'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (>= 5.7.8)                    enumeration

     *Default Value* (>= 5.7.8)           'innodb'

     *Valid Values* (>= 5.7.8)            'innodb' 'crc32' 'none'
                                          'strict_innodb' 'strict_crc32'
                                          'strict_none'

     This configuration option was removed and replaced by
     'innodb_log_checksums'.

     Specifies how to generate and verify the checksum stored in each
     redo log disk block.  'innodb_log_checksum_algorithm' supports same
     algorithms as 'innodb_checksum_algorithm'.  Previously, only the
     'innodb' algorithm was supported for redo log disk blocks.
     'innodb_log_checksum_algorithm=innodb' is the default setting.

     The strict forms work the same as 'innodb', 'crc32', and 'none',
     except that 'InnoDB' halts if it encounters a mix of checksum
     values in the same redo log.  You can only use the strict settings
     in a completely new instance.  The strict settings are somewhat
     faster, because they do not need to compute both new and old
     checksum values to accept both during disk reads.

     The following table shows the difference between the 'none',
     'innodb', and 'crc32' option values, and their strict counterparts.
     'none', 'innodb', and 'crc32' write the specified type of checksum
     value into each data block, but for compatibility accept any of the
     other checksum values when verifying a block during a read
     operation.  The strict form of each option only recognizes one kind
     of checksum, which makes verification faster but requires that all
     'InnoDB' redo logs in an instance are created under an identical
     'innodb_log_checksum_algorithm' value.

     *innodb_log_checksum_algorithm Settings*

     Value          Generated checksum (when      Permitted checksums (when
                    writing)                      reading)

     none           A constant number.            Any of the checksums
                                                  generated by 'none',
                                                  'innodb', or 'crc32'.

     innodb         A checksum calculated in      Any of the checksums
                    software, using the           generated by 'none',
                    original algorithm from       'innodb', or 'crc32'.
                    'InnoDB'.

     crc32          A checksum calculated using   Any of the checksums
                    the 'crc32' algorithm,        generated by 'none',
                    possibly done with a          'innodb', or 'crc32'.
                    hardware assist.

     strict_none    A constant number             Only the checksum generated
                                                  by 'none'.

     strict_innodb  A checksum calculated in      Only the checksum generated
                    software, using the           by 'innodb'.
                    original algorithm from
                    'InnoDB'.

     strict_crc32   A checksum calculated using   Only the checksum generated
                    the 'crc32' algorithm,        by 'crc32'.
                    possibly done with a
                    hardware assist.

   *
     'innodb_log_checksums'

     Property                             Value

     *Command-Line Format*                '--innodb-log-checksums=#'

     *Introduced*                         5.7.9

     *System Variable*                    'innodb_log_checksums'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Enables or disables checksums for redo log pages.
     'innodb_log_checksums' replaces 'innodb_log_checksum_algorithm'.

     'innodb_log_checksums=ON' enables the 'CRC-32C' checksum algorithm
     for redo log pages.  When 'innodb_log_checksums' is disabled, the
     contents of the redo log page checksum field are ignored.

     Checksums on the redo log header page and redo log checkpoint pages
     are never disabled.

   *
     'innodb_log_compressed_pages'

     Property                             Value

     *Command-Line Format*                '--innodb-log-compressed-pages=#'

     *System Variable*                    'innodb_log_compressed_pages'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Specifies whether images of re-compressed pages are written to the
     redo log.  Re-compression may occur when changes are made to
     compressed data.

     'innodb_log_compressed_pages' is enabled by default to prevent
     corruption that could occur if a different version of the 'zlib'
     compression algorithm is used during recovery.  If you are certain
     that the 'zlib' version will not change, you can disable
     'innodb_log_compressed_pages' to reduce redo log generation for
     workloads that modify compressed data.

     To measure the effect of enabling or disabling
     'innodb_log_compressed_pages', compare redo log generation for both
     settings under the same workload.  Options for measuring redo log
     generation include observing the 'Log sequence number' (LSN) in the
     'LOG' section of 'SHOW ENGINE INNODB STATUS'.
     output, or monitoring 'Innodb_os_log_written' status for the number
     of bytes written to the redo log files.

     For related information, see
     innodb-performance-compression-oltp.

   *
     'innodb_log_file_size'

     Property                             Value

     *Command-Line Format*                '--innodb-log-file-size=#'

     *System Variable*                    'innodb_log_file_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '50331648'

     *Minimum Value* (>= 5.7.11)          '4194304'

     *Minimum Value* (<= 5.7.10)          '1048576'

     *Maximum Value*                      '512GB /
                                          innodb_log_files_in_group'

     The size in bytes of each log file in a log group.  The combined
     size of log files ('innodb_log_file_size' *
     'innodb_log_files_in_group') cannot exceed a maximum value that is
     slightly less than 512GB. A pair of 255 GB log files, for example,
     approaches the limit but does not exceed it.  The default value is
     48MB.

     Generally, the combined size of the log files should be large
     enough that the server can smooth out peaks and troughs in workload
     activity, which often means that there is enough redo log space to
     handle more than an hour of write activity.  The larger the value,
     the less checkpoint flush activity is required in the buffer pool,
     saving disk I/O. Larger log files also make crash recovery slower,
     although improvements to recovery performance in MySQL 5.5 and
     higher make the log file size less of a consideration.

     The minimum 'innodb_log_file_size' value was increased from 1MB to
     4MB in MySQL 5.7.11.

     For related information, see
     innodb-startup-log-file-configuration.  For general I/O tuning
     advice, see optimizing-innodb-diskio.

   *
     'innodb_log_files_in_group'

     Property                             Value

     *Command-Line Format*                '--innodb-log-files-in-group=#'

     *System Variable*                    'innodb_log_files_in_group'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '2'

     *Minimum Value*                      '2'

     *Maximum Value*                      '100'

     The number of log files in the log group.  'InnoDB' writes to the
     files in a circular fashion.  The default (and recommended) value
     is 2.  The location of the files is specified by
     'innodb_log_group_home_dir'.  The combined size of log files
     ('innodb_log_file_size' * 'innodb_log_files_in_group') can be up to
     512GB.

     For related information, see
     innodb-startup-log-file-configuration.

   *
     'innodb_log_group_home_dir'

     Property                             Value

     *Command-Line Format*                '--innodb-log-group-home-dir=dir_name'

     *System Variable*                    'innodb_log_group_home_dir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The directory path to the 'InnoDB' redo log files, whose number is
     specified by 'innodb_log_files_in_group'.  If you do not specify
     any 'InnoDB' log variables, the default is to create two files
     named 'ib_logfile0' and 'ib_logfile1' in the MySQL data directory.
     Log file size is given by the 'innodb_log_file_size' system
     variable.

     For related information, see
     innodb-startup-log-file-configuration.

   *
     'innodb_log_write_ahead_size'

     Property                             Value

     *Command-Line Format*                '--innodb-log-write-ahead-size=#'

     *Introduced*                         5.7.4

     *System Variable*                    'innodb_log_write_ahead_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '8192'

     *Minimum Value*                      '512 (log file block size)'

     *Maximum Value*                      'Equal to innodb_page_size'

     Defines the write-ahead block size for the redo log, in bytes.  To
     avoid 'read-on-write', set 'innodb_log_write_ahead_size' to match
     the operating system or file system cache block size.  The default
     setting is 8192 bytes.  Read-on-write occurs when redo log blocks
     are not entirely cached to the operating system or file system due
     to a mismatch between write-ahead block size for the redo log and
     operating system or file system cache block size.

     Valid values for 'innodb_log_write_ahead_size' are multiples of the
     'InnoDB' log file block size (2^n).  The minimum value is the
     'InnoDB' log file block size (512).  Write-ahead does not occur
     when the minimum value is specified.  The maximum value is equal to
     the 'innodb_page_size' value.  If you specify a value for
     'innodb_log_write_ahead_size' that is larger than the
     'innodb_page_size' value, the 'innodb_log_write_ahead_size' setting
     is truncated to the 'innodb_page_size' value.

     Setting the 'innodb_log_write_ahead_size' value too low in relation
     to the operating system or file system cache block size results in
     'read-on-write'.  Setting the value too high may have a slight
     impact on 'fsync' performance for log file writes due to several
     blocks being written at once.

     For related information, see optimizing-innodb-logging.

   *
     'innodb_lru_scan_depth'

     Property                             Value

     *Command-Line Format*                '--innodb-lru-scan-depth=#'

     *System Variable*                    'innodb_lru_scan_depth'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1024'

     *Default Value* (32-bit platforms)   '1024'

     *Minimum Value* (64-bit platforms)   '100'

     *Minimum Value* (32-bit platforms)   '100'

     *Maximum Value* (64-bit platforms)   '2**64-1'

     *Maximum Value* (32-bit platforms)   '2**32-1'

     A parameter that influences the algorithms and heuristics for the
     flush operation for the 'InnoDB' buffer pool.  Primarily of
     interest to performance experts tuning I/O-intensive workloads.  It
     specifies, per buffer pool instance, how far down the buffer pool
     LRU page list the page cleaner thread scans looking for dirty pages
     to flush.  This is a background operation performed once per
     second.

     A setting smaller than the default is generally suitable for most
     workloads.  A value that is much higher than necessary may impact
     performance.  Only consider increasing the value if you have spare
     I/O capacity under a typical workload.  Conversely, if a
     write-intensive workload saturates your I/O capacity, decrease the
     value, especially in the case of a large buffer pool.

     When tuning 'innodb_lru_scan_depth', start with a low value and
     configure the setting upward with the goal of rarely seeing zero
     free pages.  Also, consider adjusting 'innodb_lru_scan_depth' when
     changing the number of buffer pool instances, since
     'innodb_lru_scan_depth' * 'innodb_buffer_pool_instances' defines
     the amount of work performed by the page cleaner thread each
     second.

     For related information, see
     innodb-lru-background-flushing.  For general I/O tuning advice,
     see optimizing-innodb-diskio.

   *
     'innodb_max_dirty_pages_pct'

     Property                             Value

     *Command-Line Format*                '--innodb-max-dirty-pages-pct=#'

     *System Variable*                    'innodb_max_dirty_pages_pct'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               numeric

     *Default Value*                      '75'

     *Minimum Value*                      '0'

     *Maximum Value* (>= 5.7.5)           '99.99'

     *Maximum Value* (<= 5.7.4)           '99'

     'InnoDB' tries to flush data from the buffer pool so that the
     percentage of dirty pages does not exceed this value.  The default
     value is 75.

     The 'innodb_max_dirty_pages_pct' setting establishes a target for
     flushing activity.  It does not affect the rate of flushing.  For
     information about managing the rate of flushing, see
     innodb-performance-adaptive_flushing.

     For related information, see
     innodb-lru-background-flushing.  For general I/O tuning advice,
     see optimizing-innodb-diskio.

   *
     'innodb_max_dirty_pages_pct_lwm'

     Property                             Value

     *Command-Line Format*                '--innodb-max-dirty-pages-pct-lwm=#'

     *System Variable*                    'innodb_max_dirty_pages_pct_lwm'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               numeric

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value* (>= 5.7.5)           '99.99'

     *Maximum Value* (<= 5.7.4)           '99'

     Defines a low water mark representing the percentage of dirty pages
     at which preflushing is enabled to control the dirty page ratio.
     The default of 0 disables the pre-flushing behavior entirely.  For
     more information, see innodb-lru-background-flushing.

   *
     'innodb_max_purge_lag'

     Property                             Value

     *Command-Line Format*                '--innodb-max-purge-lag=#'

     *System Variable*                    'innodb_max_purge_lag'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     Defines the maximum length of the purge queue.  The default value
     of 0 indicates no limit (no delays).

     Use this option to impose a delay for 'INSERT',
     'UPDATE', and 'DELETE' operations when purge
     operations are lagging (see innodb-multi-versioning).

     The 'InnoDB' transaction system maintains a list of transactions
     that have index records delete-marked by 'UPDATE' or
     'DELETE' operations.  The length of the list
     represents the PURGE_LAG value.  When PURGE_LAG exceeds
     'innodb_max_purge_lag', see 'INSERT', 'UPDATE',
     and 'DELETE' operations are delayed.

     To prevent excessive delays in extreme situations where PURGE_LAG
     becomes huge, you can limit the delay by setting the
     'innodb_max_purge_lag_delay' configuration option.  The delay is
     computed at the beginning of a purge batch.

     A typical setting for a problematic workload might be 1 million,
     assuming that transactions are small, only 100 bytes in size, and
     it is permissible to have 100MB of unpurged 'InnoDB' table rows.

     The lag value is displayed as the history list length in the
     'TRANSACTIONS' section of InnoDB Monitor output.
     The lag value is 20 in this example
     output:

          ------------
          TRANSACTIONS
          ------------
          Trx id counter 0 290328385
          Purge done for trx's n:o < 0 290315608 undo n:o < 0 17
          History list length 20

     For general I/O tuning advice, see
     optimizing-innodb-diskio.

   *
     'innodb_max_purge_lag_delay'

     Property                             Value

     *Command-Line Format*                '--innodb-max-purge-lag-delay=#'

     *System Variable*                    'innodb_max_purge_lag_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     Specifies the maximum delay in microseconds for the delay imposed
     by the 'innodb_max_purge_lag' configuration option.  A nonzero
     value represents an upper limit on the delay period computed from
     the formula based on the value of 'innodb_max_purge_lag'.  The
     default of zero means that there is no upper limit imposed on the
     delay interval.

     For general I/O tuning advice, see
     optimizing-innodb-diskio.

   *
     'innodb_max_undo_log_size'

     Property                             Value

     *Command-Line Format*                '--innodb-max-undo-log-size=#'

     *Introduced*                         5.7.5

     *System Variable*                    'innodb_max_undo_log_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1073741824'

     *Minimum Value*                      '10485760'

     *Maximum Value*                      '2**64-1'

     Defines a threshold size for undo tablespaces.  If an undo
     tablespace exceeds the threshold, it can be marked for truncation
     when 'innodb_undo_log_truncate' is enabled.  The default value is
     1073741824 bytes (1024 MiB).

     For more information, see truncate-undo-tablespace.

   *
     'innodb_merge_threshold_set_all_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-merge-threshold-set-all-debug=#'

     *Introduced*                         5.7.6

     *System Variable*                    'innodb_merge_threshold_set_all_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '50'

     *Minimum Value*                      '1'

     *Maximum Value*                      '50'

     Defines a page-full percentage value for index pages that overrides
     the current 'MERGE_THRESHOLD' setting for all indexes that are
     currently in the dictionary cache.  This option is only available
     if debugging support is compiled in using the 'WITH_DEBUG' 'CMake'
     option.  For related information, see
     index-page-merge-threshold.

   *
     'innodb_monitor_disable'

     Property                             Value

     *Command-Line Format*                '--innodb-monitor-disable=[counter|module|pattern|all]'

     *System Variable*                    'innodb_monitor_disable'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     Disables 'InnoDB' metrics counters.  Counter data may be queried
     using the 'INFORMATION_SCHEMA.INNODB_METRICS'
     table.  For usage information, see
     innodb-information-schema-metrics-table.

     'innodb_monitor_disable='latch'' disables statistics collection for
     'SHOW ENGINE INNODB MUTEX'.  For more
     information, see show-engine.

   *
     'innodb_monitor_enable'

     Property                             Value

     *Command-Line Format*                '--innodb-monitor-enable=[counter|module|pattern|all]'

     *System Variable*                    'innodb_monitor_enable'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     Enables 'InnoDB' metrics counters.  Counter data may be queried
     using the 'INFORMATION_SCHEMA.INNODB_METRICS'
     table.  For usage information, see
     innodb-information-schema-metrics-table.

     'innodb_monitor_enable='latch'' enables statistics collection for
     'SHOW ENGINE INNODB MUTEX'.  For more
     information, see show-engine.

   *
     'innodb_monitor_reset'

     Property                             Value

     *Command-Line Format*                '--innodb-monitor-reset=[counter|module|pattern|all]'

     *System Variable*                    'innodb_monitor_reset'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     Resets the count value for 'InnoDB' metrics counters to zero.
     Counter data may be queried using the
     'INFORMATION_SCHEMA.INNODB_METRICS' table.
     For usage information, see
     innodb-information-schema-metrics-table.

     'innodb_monitor_reset='latch'' resets statistics reported by
     'SHOW ENGINE INNODB MUTEX'.  For more information, see
     show-engine.

   *
     'innodb_monitor_reset_all'

     Property                             Value

     *Command-Line Format*                '--innodb-monitor-reset-all=[counter|module|pattern|all]'

     *System Variable*                    'innodb_monitor_reset_all'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     Resets all values (minimum, maximum, and so on) for 'InnoDB'
     metrics counters.  Counter data may be queried using the
     'INFORMATION_SCHEMA.INNODB_METRICS' table.
     For usage information, see
     innodb-information-schema-metrics-table.

   *
     'innodb_numa_interleave'

     Property                             Value

     *Command-Line Format*                '--innodb-numa-interleave=#'

     *Introduced*                         5.7.9

     *System Variable*                    'innodb_numa_interleave'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enables the NUMA interleave memory policy for allocation of the
     'InnoDB' buffer pool.  When 'innodb_numa_interleave' is enabled,
     the NUMA memory policy is set to 'MPOL_INTERLEAVE' for the
     'mysqld' process.  After the 'InnoDB' buffer pool is
     allocated, the NUMA memory policy is set back to 'MPOL_DEFAULT'.
     For the 'innodb_numa_interleave' option to be available, MySQL must
     be compiled on a NUMA-enabled Linux system.

     As of MySQL 5.7.17, 'CMake' sets the default 'WITH_NUMA' value
     based on whether the current platform has 'NUMA' support.  For more
     information, see source-configuration-options.

   *
     'innodb_old_blocks_pct'

     Property                             Value

     *Command-Line Format*                '--innodb-old-blocks-pct=#'

     *System Variable*                    'innodb_old_blocks_pct'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '37'

     *Minimum Value*                      '5'

     *Maximum Value*                      '95'

     Specifies the approximate percentage of the 'InnoDB' buffer pool
     used for the old block sublist.  The range of values is 5 to 95.
     The default value is 37 (that is, 3/8 of the pool).  Often used in
     combination with 'innodb_old_blocks_time'.

     For more information, see
     innodb-performance-midpoint_insertion.  For information about
     buffer pool management, the LRU algorithm, and eviction policies,
     see innodb-buffer-pool.

   *
     'innodb_old_blocks_time'

     Property                             Value

     *Command-Line Format*                '--innodb-old-blocks-time=#'

     *System Variable*                    'innodb_old_blocks_time'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '2**32-1'

     Non-zero values protect against the buffer pool being filled by
     data that is referenced only for a brief period, such as during a
     full table scan.  Increasing this value offers more protection
     against full table scans interfering with data cached in the buffer
     pool.

     Specifies how long in milliseconds a block inserted into the old
     sublist must stay there after its first access before it can be
     moved to the new sublist.  If the value is 0, a block inserted into
     the old sublist moves immediately to the new sublist the first time
     it is accessed, no matter how soon after insertion the access
     occurs.  If the value is greater than 0, blocks remain in the old
     sublist until an access occurs at least that many milliseconds
     after the first access.  For example, a value of 1000 causes blocks
     to stay in the old sublist for 1 second after the first access
     before they become eligible to move to the new sublist.

     The default value is 1000.

     This configuration option is often used in combination with
     'innodb_old_blocks_pct'.  For more information, see
     innodb-performance-midpoint_insertion.  For information about
     buffer pool management, the LRU algorithm, and eviction policies,
     see innodb-buffer-pool.

   *
     'innodb_online_alter_log_max_size'

     Property                             Value

     *Command-Line Format*                '--innodb-online-alter-log-max-size=#'

     *System Variable*                    'innodb_online_alter_log_max_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '134217728'

     *Minimum Value*                      '65536'

     *Maximum Value*                      '2**64-1'

     Specifies an upper limit in bytes on the size of the temporary log
     files used during online DDL operations for 'InnoDB' tables.  There
     is one such log file for each index being created or table being
     altered.  This log file stores data inserted, updated, or deleted
     in the table during the DDL operation.  The temporary log file is
     extended when needed by the value of 'innodb_sort_buffer_size', up
     to the maximum specified by 'innodb_online_alter_log_max_size'.  If
     a temporary log file exceeds the upper size limit, the 'ALTER TABLE'
     operation fails and all uncommitted concurrent
     DML operations are rolled back.  Thus, a large value for this
     option allows more DML to happen during an online DDL operation,
     but also extends the period of time at the end of the DDL operation
     when the table is locked to apply the data from the log.

   *
     'innodb_open_files'

     Property                             Value

     *Command-Line Format*                '--innodb-open-files=#'

     *System Variable*                    'innodb_open_files'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     *Minimum Value*                      '10'

     *Maximum Value*                      '4294967295'

     This configuration option is only relevant if you use multiple
     'InnoDB' tablespaces.  It specifies the maximum number of '.ibd'
     files that MySQL can keep open at one time.  The minimum value is
     10.  The default value is 300 if 'innodb_file_per_table' is not
     enabled, and the higher of 300 and 'table_open_cache' otherwise.

     The file descriptors used for '.ibd' files are for 'InnoDB' tables
     only.  They are independent of those specified by the
     '--open-files-limit' server option, and do not affect the operation
     of the table cache.  For general I/O tuning advice, see
     optimizing-innodb-diskio.

   *
     'innodb_optimize_fulltext_only'

     Property                             Value

     *Command-Line Format*                '--innodb-optimize-fulltext-only=#'

     *System Variable*                    'innodb_optimize_fulltext_only'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Changes the way 'OPTIMIZE TABLE' operates on
     'InnoDB' tables.  Intended to be enabled temporarily, during
     maintenance operations for 'InnoDB' tables with 'FULLTEXT' indexes.

     By default, see 'OPTIMIZE TABLE' reorganizes
     data in the clustered index of the table.  When this option is
     enabled, see 'OPTIMIZE TABLE' skips the
     reorganization of table data, and instead processes newly added,
     deleted, and updated token data for 'InnoDB' 'FULLTEXT' indexes.
     Fore more information, see fulltext-optimize.

   *
     'innodb_optimize_point_storage'

     Property                             Value

     *Command-Line Format*                '--innodb-optimize-point-storage=#'

     *Introduced*                         5.7.5

     *Removed*                            5.7.6

     *System Variable*                    'innodb_optimize_point_storage'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enable this variable before creating a column of type 'POINT' to
     store the 'POINT' data type internally as variable-length 'BLOB'
     data.

   *
     'innodb_page_cleaners'

     Property                             Value

     *Command-Line Format*                '--innodb-page-cleaners=#'

     *Introduced*                         5.7.4

     *System Variable*                    'innodb_page_cleaners'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.8)           '4'

     *Default Value* (<= 5.7.7)           '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '64'

     The number of page cleaner threads that flush dirty pages from
     buffer pool instances.  Page cleaner threads perform flush list and
     LRU flushing.  A single page cleaner thread was introduced in MySQL
     5.6 to offload buffer pool flushing work from the 'InnoDB' master
     thread.  In MySQL 5.7, 'InnoDB' provides support for multiple page
     cleaner threads.  A value of 1 maintains the pre-MySQL 5.7
     configuration in which there is a single page cleaner thread.  When
     there are multiple page cleaner threads, buffer pool flushing tasks
     for each buffer pool instance are dispatched to idle page cleaner
     threads.  The 'innodb_page_cleaners' default value was changed from
     1 to 4 in MySQL 5.7.  If the number of page cleaner threads exceeds
     the number of buffer pool instances, 'innodb_page_cleaners' is
     automatically set to the same value as
     'innodb_buffer_pool_instances'.

     If your workload is write-IO bound when flushing dirty pages from
     buffer pool instances to data files, and if your system hardware
     has available capacity, increasing the number of page cleaner
     threads may help improve write-IO throughput.

     Multi-threaded page cleaner support is extended to shutdown and
     recovery phases in MySQL 5.7.

     The 'setpriority()' system call is used on Linux platforms where it
     is supported, and where the 'mysqld' execution user
     is authorized to give 'page_cleaner' threads priority over other
     MySQL and 'InnoDB' threads to help page flushing keep pace with the
     current workload.  'setpriority()' support is indicated by this
     'InnoDB' startup message:

          [Note] InnoDB: If the mysqld execution user is authorized, page cleaner
          thread priority can be changed. See the man page of setpriority().

     For systems where server startup and shutdown is not managed by
     systemd, see 'mysqld' execution user authorization can
     be configured in '/etc/security/limits.conf'.  For example, if
     'mysqld' is run under the 'mysql' user, you can
     authorize the 'mysql' user by adding these lines to
     '/etc/security/limits.conf':

          mysql              hard    nice       -20
          mysql              soft    nice       -20

     For systemd managed systems, the same can be achieved by specifying
     'LimitNICE=-20' in a localized systemd configuration file.  For
     example, create a file named 'override.conf' in
     '/etc/systemd/system/mysqld.service.d/override.conf' and add this
     entry:

          [Service]
          LimitNICE=-20

     After creating or changing 'override.conf', reload the systemd
     configuration, then tell systemd to restart the MySQL service:

          systemctl daemon-reload
          systemctl restart mysqld  # RPM platforms
          systemctl restart mysql   # Debian platforms

     For more information about using a localized systemd configuration
     file, see systemd-mysql-configuration.

     After authorizing the 'mysqld' execution user, use
     the 'cat' command to verify the configured 'Nice' limits for the
     'mysqld' process:

          shell> cat /proc/MYSQLD_PID/limits | grep nice
          Max nice priority         18446744073709551596 18446744073709551596

   *
     'innodb_page_size'

     Property                             Value

     *Command-Line Format*                '--innodb-page-size=#k'

     *System Variable*                    'innodb_page_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               enumeration

     *Default Value*                      '16384'

     *Valid Values* (>= 5.7.6)            '4k' '8k' '16k' '32k' '64k' '4096'
                                          '8192' '16384' '32768' '65536'

     *Valid Values* (<= 5.7.5)            '4k' '8k' '16k' '4096' '8192'
                                          '16384'

     Specifies the page size for all 'InnoDB' tablespaces in a MySQL
     instance.  You can specify page size using the values 64k, 32k,
     '16k' (the default), '8k', or '4k'.  Alternatively, you can specify
     page size in bytes (65536, 32768, 16384, 8192, 4096).

     'innodb_page_size' can only be configured prior to initializing the
     MySQL instance and cannot be changed afterward.  If no value is
     specified, the instance is initialized using the default page size.
     See innodb-init-startup-configuration.

     Support for 32k and 64k page sizes was added in MySQL 5.7.  For
     both 32k and 64k page sizes, the maximum row length is
     approximately 16000 bytes.  'ROW_FORMAT=COMPRESSED' is not
     supported when 'innodb_page_size' is set to 32KB or 64KB. For
     'innodb_page_size=32k', extent size is 2MB. For
     'innodb_page_size=64k', extent size is 4MB.
     'innodb_log_buffer_size' should be set to at least 16M (the
     default) when using 32k or 64k page sizes.

     The default 16KB page size or larger is appropriate for a wide
     range of workloads, particularly for queries involving table scans
     and DML operations involving bulk updates.  Smaller page sizes
     might be more efficient for OLTP workloads involving many small
     writes, where contention can be an issue when single pages contain
     many rows.  Smaller pages might also be efficient with SSD storage
     devices, which typically use small block sizes.  Keeping the
     'InnoDB' page size close to the storage device block size minimizes
     the amount of unchanged data that is rewritten to disk.

     The minimum file size for the first system tablespace data file
     ('ibdata1') differs depending on the 'innodb_page_size' value.  See
     the 'innodb_data_file_path' option description for more
     information.

     For general I/O tuning advice, see
     optimizing-innodb-diskio.

   *
     'innodb_print_all_deadlocks'

     Property                             Value

     *Command-Line Format*                '--innodb-print-all-deadlocks=#'

     *System Variable*                    'innodb_print_all_deadlocks'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     When this option is enabled, information about all deadlocks in
     'InnoDB' user transactions is recorded in the 'mysqld' error log.
     Otherwise, you see information about only the last
     deadlock, using the 'SHOW ENGINE INNODB STATUS' command.  An
     occasional 'InnoDB' deadlock is not necessarily an issue, because
     'InnoDB' detects the condition immediately and rolls back one of
     the transactions automatically.  You might use this option to
     troubleshoot why deadlocks are occurring if an application does not
     have appropriate error-handling logic to detect the rollback and
     retry its operation.  A large number of deadlocks might indicate
     the need to restructure transactions that issue DML or 'SELECT ...
     FOR UPDATE' statements for multiple tables, so that each
     transaction accesses the tables in the same order, thus avoiding
     the deadlock condition.

     For related information, see innodb-deadlocks.

   *
     'innodb_purge_batch_size'

     Property                             Value

     *Command-Line Format*                '--innodb-purge-batch-size=#'

     *System Variable*                    'innodb_purge_batch_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '300'

     *Minimum Value*                      '1'

     *Maximum Value*                      '5000'

     Defines the number of undo log pages that purge parses and
     processes in one batch from the history list.  In a multi-threaded
     purge configuration, the coordinator purge thread divides
     'innodb_purge_batch_size' by 'innodb_purge_threads' and assigns
     that number of pages to each purge thread.  The
     'innodb_purge_batch_size' option also defines the number of undo
     log pages that purge frees after every 128 iterations through the
     undo logs.

     The 'innodb_purge_batch_size' option is intended for advanced
     performance tuning in combination with the 'innodb_purge_threads'
     setting.  Most MySQL users need not change
     'innodb_purge_batch_size' from its default value.

     For related information, see
     innodb-improved-purge-scheduling.

   *
     'innodb_purge_threads'

     Property                             Value

     *Command-Line Format*                '--innodb-purge-threads=#'

     *System Variable*                    'innodb_purge_threads'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.8)           '4'

     *Default Value* (<= 5.7.7)           '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '32'

     The number of background threads devoted to the 'InnoDB' purge
     operation.  A minimum value of 1 signifies that the purge operation
     is always performed by a background thread, never as part of the
     master thread.  Running the purge operation in one or more
     background threads helps reduce internal contention within
     'InnoDB', improving scalability.  Increasing the value to greater
     than 1 creates that many separate purge threads, which can improve
     efficiency on systems where DML operations are performed on
     multiple tables.  The maximum is 32.

     For related information, see
     innodb-improved-purge-scheduling.

   *
     'innodb_purge_rseg_truncate_frequency'

     Property                             Value

     *Command-Line Format*                '--innodb-purge-rseg-truncate-frequency=#'

     *Introduced*                         5.7.5

     *System Variable*                    'innodb_purge_rseg_truncate_frequency'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '128'

     *Minimum Value*                      '1'

     *Maximum Value*                      '128'

     Defines the frequency with which the purge system frees rollback
     segments in terms of the number of times that purge is invoked.  An
     undo tablespace cannot be truncated until its rollback segments are
     freed.  Normally, the purge system frees rollback segments once
     every 128 times that purge is invoked.  The default value is 128.
     Reducing this value increases the frequency with which the purge
     thread frees rollback segments.

     'innodb_purge_rseg_truncate_frequency' is intended for use with
     'innodb_undo_log_truncate'.  For more information, see
     truncate-undo-tablespace.

   *
     'innodb_random_read_ahead'

     Property                             Value

     *Command-Line Format*                '--innodb-random-read-ahead=#'

     *System Variable*                    'innodb_random_read_ahead'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enables the random read-ahead technique for optimizing 'InnoDB'
     I/O.

     For details about performance considerations for different types of
     read-ahead requests, see innodb-performance-read_ahead.
     For general I/O tuning advice, see
     optimizing-innodb-diskio.

   *
     'innodb_read_ahead_threshold'

     Property                             Value

     *Command-Line Format*                '--innodb-read-ahead-threshold=#'

     *System Variable*                    'innodb_read_ahead_threshold'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '56'

     *Minimum Value*                      '0'

     *Maximum Value*                      '64'

     Controls the sensitivity of linear read-ahead that 'InnoDB' uses to
     prefetch pages into the buffer pool.  If 'InnoDB' reads at least
     'innodb_read_ahead_threshold' pages sequentially from an extent (64
     pages), it initiates an asynchronous read for the entire following
     extent.  The permissible range of values is 0 to 64.  A value of 0
     disables read-ahead.  For the default of 56, 'InnoDB' must read at
     least 56 pages sequentially from an extent to initiate an
     asynchronous read for the following extent.

     Knowing how many pages are read through the read-ahead mechanism,
     and how many of these pages are evicted from the buffer pool
     without ever being accessed, can be useful when fine-tuning the
     'innodb_read_ahead_threshold' setting.  'SHOW ENGINE INNODB STATUS'
     output displays counter information from the
     'Innodb_buffer_pool_read_ahead' and
     'Innodb_buffer_pool_read_ahead_evicted' global status variables,
     which report the number of pages brought into the buffer pool by
     read-ahead requests, and the number of such pages evicted from the
     buffer pool without ever being accessed, respectively.  The status
     variables report global values since the last server restart.

     'SHOW ENGINE INNODB STATUS' also shows the rate
     at which the read-ahead pages are read in and the rate at which
     such pages are evicted without being accessed.  The per-second
     averages are based on the statistics collected since the last
     invocation of 'SHOW ENGINE INNODB STATUS' and are displayed in the
     'BUFFER POOL AND MEMORY' section of the 'SHOW ENGINE INNODB STATUS'
     output.

     For more information, see innodb-performance-read_ahead.
     For general I/O tuning advice, see
     optimizing-innodb-diskio.

   *
     'innodb_read_io_threads'

     Property                             Value

     *Command-Line Format*                '--innodb-read-io-threads=#'

     *System Variable*                    'innodb_read_io_threads'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '4'

     *Minimum Value*                      '1'

     *Maximum Value*                      '64'

     The number of I/O threads for read operations in 'InnoDB'.  Its
     counterpart for write threads is 'innodb_write_io_threads'.  For
     more information, see
     innodb-performance-multiple_io_threads.  For general I/O tuning
     advice, see optimizing-innodb-diskio.

     *Note*:

     On Linux systems, running multiple MySQL servers (typically more
     than 12) with default settings for 'innodb_read_io_threads',
     'innodb_write_io_threads', and the Linux 'aio-max-nr' setting can
     exceed system limits.  Ideally, increase the 'aio-max-nr' setting;
     as a workaround, you might reduce the settings for one or both of
     the MySQL configuration options.

   *
     'innodb_read_only'

     Property                             Value

     *Command-Line Format*                '--innodb-read-only=#'

     *System Variable*                    'innodb_read_only'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Starts 'InnoDB' in read-only mode.  For distributing database
     applications or data sets on read-only media.  Can also be used in
     data warehouses to share the same data directory between multiple
     instances.  For more information, see
     innodb-read-only-instance.

   *
     'innodb_replication_delay'

     Property                             Value

     *Command-Line Format*                '--innodb-replication-delay=#'

     *System Variable*                    'innodb_replication_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     The replication thread delay in milliseconds on a slave server if
     'innodb_thread_concurrency' is reached.

   *
     'innodb_rollback_on_timeout'

     Property                             Value

     *Command-Line Format*                '--innodb-rollback-on-timeout'

     *System Variable*                    'innodb_rollback_on_timeout'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     'InnoDB' rolls back only the last statement on a transaction
     timeout by default.  If '--innodb_rollback_on_timeout' is
     specified, a transaction timeout causes 'InnoDB' to abort and roll
     back the entire transaction.

     *Note*:

     If the start-transaction statement was 'START TRANSACTION'
     or 'BEGIN' statement, rollback does not
     cancel that statement.  Further SQL statements become part of the
     transaction until the occurrence of 'COMMIT',
     'ROLLBACK', or some SQL statement that causes an implicit
     commit.

     For more information, see innodb-error-handling.

   *
     'innodb_rollback_segments'

     Property                             Value

     *Command-Line Format*                '--innodb-rollback-segments=#'

     *System Variable*                    'innodb_rollback_segments'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '128'

     *Minimum Value*                      '1'

     *Maximum Value*                      '128'

     Defines the number of rollback segments used by 'InnoDB'.

     One rollback segment is always assigned to the system tablespace,
     and 32 rollback segments are reserved for use by temporary tables
     and are hosted in the temporary tablespace ('ibtmp1').  To allocate
     additional rollback segments for data-modifying transactions that
     generate undo records, 'innodb_rollback_segments' must be set to a
     value greater than 33.  If you configure separate undo tablespaces,
     the rollback segment in the system tablespace is rendered inactive.
     Each rollback segment can support a maximum of 1023 data-modifying
     transactions.

     When 'innodb_rollback_segments' is set to 32 or less, 'InnoDB'
     assigns one rollback segment to the system tablespace and 32 to the
     temporary tablespace ('ibtmp1').

     When 'innodb_rollback_segments' is set to a value greater than 32,
     'InnoDB' assigns one rollback segment to the system tablespace, 32
     to the temporary tablespace ('ibtmp1'), and additional rollback
     segments to undo tablespaces, if present.  If undo tablespaces are
     not present, additional rollback segments are assigned to the
     system tablespace.

     Although you can increase or decrease the number of rollback
     segments used by 'InnoDB', the number of rollback segments
     physically present in the system never decreases.  Thus, you might
     start with a low value for this parameter and gradually increase
     it, to avoid allocating rollback segments that are not required.
     The 'innodb_rollback_segments' default value is 128, which is also
     the maximum value.

     For more information about rollback segments, see
     innodb-multi-versioning.  For information about configuring
     separate undo tablespaces, see innodb-undo-tablespace.

   *
     'innodb_saved_page_number_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-saved-page-number-debug=#'

     *System Variable*                    'innodb_saved_page_number_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Maximum Value*                      '2**23-1'

     Saves a page number.  Setting the
     'innodb_fil_make_page_dirty_debug' option dirties the page defined
     by 'innodb_saved_page_number_debug'.  The
     'innodb_saved_page_number_debug' option is only available if
     debugging support is compiled in using the 'WITH_DEBUG' 'CMake'
     option.

   *
     'innodb_sort_buffer_size'

     Property                             Value

     *Command-Line Format*                '--innodb-sort-buffer-size=#'

     *System Variable*                    'innodb_sort_buffer_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1048576'

     *Minimum Value*                      '65536'

     *Maximum Value*                      '67108864'

     Specifies the size of sort buffers used to sort data during
     creation of an 'InnoDB' index.  The specified size defines the
     amount of data that is read into memory for internal sorting and
     then written out to disk.  This process is referred to as a 'run'.
     During the merge phase, pairs of buffers of the specified size are
     read in and merged.  The larger the setting, the fewer runs and
     merges there are.

     This sort area is only used for merge sorts during index creation,
     not during later index maintenance operations.  Buffers are
     deallocated when index creation completes.

     The value of this option also controls the amount by which the
     temporary log file is extended to record concurrent DML during
     online DDL operations.

     Before this setting was made configurable, the size was hardcoded
     to 1048576 bytes (1MB), which remains the default.

     During an 'ALTER TABLE' or 'CREATE TABLE'
     statement that creates an index, 3 buffers
     are allocated, each with a size defined by this option.
     Additionally, auxiliary pointers are allocated to rows in the sort
     buffer so that the sort can run on pointers (as opposed to moving
     rows during the sort operation).

     For a typical sort operation, a formula such as this one can be
     used to estimate memory consumption:

          (6 /*FTS_NUM_AUX_INDEX*/ * (3*@@global.innodb_sort_buffer_size)
          + 2 * number_of_partitions * number_of_secondary_indexes_created
          * (@@global.innodb_sort_buffer_size/dict_index_get_min_size(index)*/)
          * 8 /*64-bit sizeof *buf->tuples*/")

     '@@global.innodb_sort_buffer_size/dict_index_get_min_size(index)'
     indicates the maximum tuples held.  '2 *
     (@@global.innodb_sort_buffer_size/*dict_index_get_min_size(index)*/)
     * 8 /*64-bit size of *buf->tuples*/' indicates auxiliary pointers
     allocated.

     *Note*:

     For 32-bit, multiply by 4 instead of 8.

     For parallel sorts on a full-text index, multiply by the
     'innodb_ft_sort_pll_degree' setting:

          (6 /*FTS_NUM_AUX_INDEX*/ * @@global.innodb_ft_sort_pll_degree)

   *
     'innodb_spin_wait_delay'

     Property                             Value

     *Command-Line Format*                '--innodb-spin-wait-delay=#'

     *System Variable*                    'innodb_spin_wait_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '6'

     *Default Value* (32-bit platforms)   '6'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '2**64-1'

     *Maximum Value* (32-bit platforms)   '2**32-1'

     The maximum delay between polls for a spin lock.  The low-level
     implementation of this mechanism varies depending on the
     combination of hardware and operating system, so the delay does not
     correspond to a fixed time interval.  For more information, see
     innodb-performance-spin_lock_polling.

   *
     'innodb_stats_auto_recalc'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-auto-recalc=#'

     *System Variable*                    'innodb_stats_auto_recalc'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Causes 'InnoDB' to automatically recalculate persistent statistics
     after the data in a table is changed substantially.  The threshold
     value is 10% of the rows in the table.  This setting applies to
     tables created when the 'innodb_stats_persistent' option is
     enabled.  Automatic statistics recalculation may also be configured
     by specifying 'STATS_PERSISTENT=1' in a 'CREATE TABLE'
     or 'ALTER TABLE' statement.  The
     amount of data sampled to produce the statistics is controlled by
     the 'innodb_stats_persistent_sample_pages' configuration option.

     For more information, see innodb-persistent-stats.

   *
     'innodb_stats_include_delete_marked'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-include-delete-marked=#'

     *Introduced*                         5.7.17

     *System Variable*                    'innodb_stats_include_delete_marked'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     By default, 'InnoDB' reads uncommitted data when calculating
     statistics.  In the case of an uncommitted transaction that deletes
     rows from a table, 'InnoDB' excludes records that are delete-marked
     when calculating row estimates and index statistics, which can lead
     to non-optimal execution plans for other transactions that are
     operating on the table concurrently using a transaction isolation
     level other than 'READ UNCOMMITTED'.  To avoid this scenario,
     'innodb_stats_include_delete_marked' can be enabled to ensure that
     'InnoDB' includes delete-marked records when calculating persistent
     optimizer statistics.

     When 'innodb_stats_include_delete_marked' is enabled, see
     'ANALYZE TABLE' considers delete-marked records
     when recalculating statistics.

     'innodb_stats_include_delete_marked' is a global setting that
     affects all 'InnoDB' tables.  It is only applicable to persistent
     optimizer statistics.

     For related information, see innodb-persistent-stats.

   *
     'innodb_stats_method'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-method=name'

     *System Variable*                    'innodb_stats_method'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'nulls_equal'

     *Valid Values*                       'nulls_equal' 'nulls_unequal'
                                          'nulls_ignored'

     How the server treats 'NULL' values when collecting statistics
     about the distribution of index values for 'InnoDB' tables.
     Permitted values are 'nulls_equal', 'nulls_unequal', and
     'nulls_ignored'.  For 'nulls_equal', all 'NULL' index values are
     considered equal and form a single value group with a size equal to
     the number of 'NULL' values.  For 'nulls_unequal', 'NULL' values
     are considered unequal, and each 'NULL' forms a distinct value
     group of size 1.  For 'nulls_ignored', 'NULL' values are ignored.

     The method used to generate table statistics influences how the
     optimizer chooses indexes for query execution, as described in
     index-statistics.

   *
     'innodb_stats_on_metadata'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-on-metadata'

     *System Variable*                    'innodb_stats_on_metadata'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     This option only applies when optimizer statistics are configured
     to be non-persistent.  Optimizer statistics are not persisted to
     disk when 'innodb_stats_persistent' is disabled or when individual
     tables are created or altered with 'STATS_PERSISTENT=0'.  For more
     information, see innodb-statistics-estimation.

     When 'innodb_stats_on_metadata' is enabled, 'InnoDB' updates
     non-persistent statistics when metadata statements such as
     'SHOW TABLE STATUS' or when accessing the
     'INFORMATION_SCHEMA.TABLES' or
     'INFORMATION_SCHEMA.STATISTICS' tables.  (These
     updates are similar to what happens for 'ANALYZE TABLE')
     When disabled, 'InnoDB' does not update statistics
     during these operations.  Leaving the setting disabled can improve
     access speed for schemas that have a large number of tables or
     indexes.  It can also improve the stability of execution plans for
     queries that involve 'InnoDB' tables.

     To change the setting, issue the statement 'SET GLOBAL
     innodb_stats_on_metadata=MODE', where 'MODE' is either 'ON' or
     'OFF' (or '1' or '0').  Changing the setting requires the 'SUPER'
     privilege and immediately affects the operation of all connections.

   *
     'innodb_stats_persistent'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-persistent=setting'

     *System Variable*                    'innodb_stats_persistent'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     *Valid Values*                       'OFF' 'ON' '0' '1'

     Specifies whether 'InnoDB' index statistics are persisted to disk.
     Otherwise, statistics may be recalculated frequently which can lead
     to variations in query execution plans.  This setting is stored
     with each table when the table is created.  You can set
     'innodb_stats_persistent' at the global level before creating a
     table, or use the 'STATS_PERSISTENT' clause of the 'CREATE TABLE'
     and 'ALTER TABLE'.
     statements to override the system-wide setting and configure
     persistent statistics for individual tables.

     For more information, see innodb-persistent-stats.

   *
     'innodb_stats_persistent_sample_pages'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-persistent-sample-pages=#'

     *System Variable*                    'innodb_stats_persistent_sample_pages'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '20'

     The number of index pages to sample when estimating cardinality and
     other statistics for an indexed column, such as those calculated by
     'ANALYZE TABLE'.  Increasing the value
     improves the accuracy of index statistics, which can improve the
     query execution plan, at the expense of increased I/O during the
     execution of 'ANALYZE TABLE' for an 'InnoDB'
     table.  For more information, see innodb-persistent-stats.

     *Note*:

     Setting a high value for 'innodb_stats_persistent_sample_pages'
     could result in lengthy 'ANALYZE TABLE'.
     execution time.  To estimate the number of database pages accessed
     by 'ANALYZE TABLE', see
     innodb-analyze-table-complexity.

     'innodb_stats_persistent_sample_pages' only applies when
     'innodb_stats_persistent' is enabled for a table; when
     'innodb_stats_persistent' is disabled,
     'innodb_stats_transient_sample_pages' applies instead.

   *
     'innodb_stats_sample_pages'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-sample-pages=#'

     *Deprecated*                         Yes

     *System Variable*                    'innodb_stats_sample_pages'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '8'

     *Minimum Value*                      '1'

     *Maximum Value*                      '2**64-1'

     Deprecated.  Use 'innodb_stats_transient_sample_pages' instead.

   *
     'innodb_stats_transient_sample_pages'

     Property                             Value

     *Command-Line Format*                '--innodb-stats-transient-sample-pages=#'

     *System Variable*                    'innodb_stats_transient_sample_pages'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '8'

     The number of index pages to sample when estimating cardinality and
     other statistics for an indexed column, such as those calculated by
     'ANALYZE TABLE'.  The default value is 8.
     Increasing the value improves the accuracy of index statistics,
     which can improve the query execution plan, at the expense of
     increased I/O when opening an 'InnoDB' table or recalculating
     statistics.  For more information, see
     innodb-statistics-estimation.

     *Note*:

     Setting a high value for 'innodb_stats_transient_sample_pages'
     could result in lengthy 'ANALYZE TABLE'.
     execution time.  To estimate the number of database pages accessed
     by 'ANALYZE TABLE', see
     innodb-analyze-table-complexity.

     'innodb_stats_transient_sample_pages' only applies when
     'innodb_stats_persistent' is disabled for a table; when
     'innodb_stats_persistent' is enabled,
     'innodb_stats_persistent_sample_pages' applies instead.  Takes the
     place of 'innodb_stats_sample_pages'.  For more information, see
     innodb-statistics-estimation.

   *
     'innodb_status_output'

     Property                             Value

     *Command-Line Format*                '--innodb-status-output'

     *Introduced*                         5.7.4

     *System Variable*                    'innodb_status_output'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enables or disables periodic output for the standard 'InnoDB'
     Monitor.  Also used in combination with
     'innodb_status_output_locks' to enable or disable periodic output
     for the 'InnoDB' Lock Monitor.  For more information, see
     innodb-enabling-monitors.

   *
     'innodb_status_output_locks'

     Property                             Value

     *Command-Line Format*                '--innodb-status-output-locks'

     *Introduced*                         5.7.4

     *System Variable*                    'innodb_status_output_locks'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enables or disables the 'InnoDB' Lock Monitor.  When enabled, the
     'InnoDB' Lock Monitor prints additional information about locks in
     'SHOW ENGINE INNODB STATUS' output and in periodic output printed
     to the MySQL error log.  Periodic output for the 'InnoDB' Lock
     Monitor is printed as part of the standard 'InnoDB' Monitor output.
     The standard 'InnoDB' Monitor must therefore be enabled for the
     'InnoDB' Lock Monitor to print data to the MySQL error log
     periodically.  For more information, see
     innodb-enabling-monitors.

   *
     'innodb_strict_mode'

     Property                             Value

     *Command-Line Format*                '--innodb-strict-mode=#'

     *System Variable*                    'innodb_strict_mode'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value* (>= 5.7.7)           'ON'

     *Default Value* (<= 5.7.6)           'OFF'

     When 'innodb_strict_mode' is enabled, 'InnoDB' returns errors
     rather than warnings for certain conditions.

     Strict mode helps guard against ignored typos and syntax errors in
     SQL, or other unintended consequences of various combinations of
     operational modes and SQL statements.  When 'innodb_strict_mode' is
     enabled, 'InnoDB' raises error conditions in certain cases, rather
     than issuing a warning and processing the specified statement
     (perhaps with unintended behavior).  This is analogous to
     'sql_mode' in MySQL, which controls what SQL syntax
     MySQL accepts, and determines whether it silently ignores errors,
     or validates input syntax and data values.

     The 'innodb_strict_mode' setting affects the handling of syntax
     errors for 'CREATE TABLE', 'ALTER TABLE',
     see 'CREATE INDEX', and
     'OPTIMIZE TABLE' statements.  'innodb_strict_mode'
     also enables a record size check, so that an 'INSERT' or 'UPDATE'
     never fails due to the record being too large for the selected page
     size.

     Oracle recommends enabling 'innodb_strict_mode' when using
     'ROW_FORMAT' and 'KEY_BLOCK_SIZE' clauses in 'CREATE TABLE',
     see 'ALTER TABLE', and 'CREATE INDEX'
     statements.  When 'innodb_strict_mode' is
     disabled, 'InnoDB' ignores conflicting clauses and creates the
     table or index with only a warning in the message log.  The
     resulting table might have different characteristics than intended,
     such as lack of compression support when attempting to create a
     compressed table.  When 'innodb_strict_mode' is enabled, such
     problems generate an immediate error and the table or index is not
     created.

     You can enable or disable 'innodb_strict_mode' on the command line
     when starting 'mysqld', or in a MySQL configuration file.  You can
     also enable or disable 'innodb_strict_mode' at runtime with the
     statement 'SET [GLOBAL|SESSION] innodb_strict_mode=MODE', where
     'MODE' is either 'ON' or 'OFF'.  Changing the 'GLOBAL' setting
     requires the 'SUPER' privilege and affects the operation of all
     clients that subsequently connect.  Any client can change the
     'SESSION' setting for 'innodb_strict_mode', and the setting affects
     only that client.

     'innodb_strict_mode' is not applicable to general tablespaces.
     Tablespace management rules for general tablespaces are strictly
     enforced independently of 'innodb_strict_mode'.  For more
     information, see create-tablespace.

   *
     'innodb_support_xa'

     Property                             Value

     *Command-Line Format*                '--innodb-support-xa'

     *Deprecated*                         5.7.10

     *System Variable*                    'innodb_support_xa'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Enables 'InnoDB' support for two-phase commit in XA transactions,
     causing an extra disk flush for transaction preparation.  The XA
     mechanism is used internally and is essential for any server that
     has its binary log turned on and is accepting changes to its data
     from more than one thread.  If you disable 'innodb_support_xa',
     transactions can be written to the binary log in a different order
     than the live database is committing them, which can produce
     different data when the binary log is replayed in disaster recovery
     or on a replication slave.  Do not disable 'innodb_support_xa' on a
     replication master server unless you have an unusual setup where
     only one thread is able to change data.

     'innodb_support_xa' is deprecated and will be removed in a future
     MySQL release.  'InnoDB' support for two-phase commit in XA
     transactions is always enabled as of MySQL 5.7.10.  Disabling
     'innodb_support_xa' is no longer permitted as it makes replication
     unsafe and prevents performance gains associated with binary log
     group commit.

   *
     'innodb_sync_array_size'

     Property                             Value

     *Command-Line Format*                '--innodb-sync-array-size=#'

     *System Variable*                    'innodb_sync_array_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1024'

     Defines the size of the mutex/lock wait array.  Increasing the
     value splits the internal data structure used to coordinate
     threads, for higher concurrency in workloads with large numbers of
     waiting threads.  This setting must be configured when the MySQL
     instance is starting up, and cannot be changed afterward.
     Increasing the value is recommended for workloads that frequently
     produce a large number of waiting threads, typically greater than
     768.

   *
     'innodb_sync_spin_loops'

     Property                             Value

     *Command-Line Format*                '--innodb-sync-spin-loops=#'

     *System Variable*                    'innodb_sync_spin_loops'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '30'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     The number of times a thread waits for an 'InnoDB' mutex to be
     freed before the thread is suspended.

   *
     'innodb_sync_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-sync-debug=#'

     *Introduced*                         5.7.8

     *System Variable*                    'innodb_sync_debug'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enables sync debug checking for the 'InnoDB' storage engine.  This
     option is only available if debugging support is compiled in using
     the 'WITH_DEBUG' 'CMake' option.

     Previously, enabling 'InnoDB' sync debug checking required that the
     Debug Sync facility be enabled using the 'ENABLE_DEBUG_SYNC'
     'CMake' option.  This requirement was removed in MySQL 5.7 with the
     introduction of this configuration option.

   *
     'innodb_table_locks'

     Property                             Value

     *Command-Line Format*                '--innodb-table-locks'

     *System Variable*                    'innodb_table_locks'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'TRUE'

     If 'autocommit = 0', 'InnoDB' honors 'LOCK TABLES'.;
     MySQL does not return from 'LOCK TABLES ... WRITE'
     until all other threads have released all their locks to the table.
     The default value of 'innodb_table_locks' is 1, which means that
     'LOCK TABLES' causes InnoDB to lock a table
     internally if 'autocommit = 0'.

     In MySQL 5.7, 'innodb_table_locks = 0' has no effect for tables
     locked explicitly with 'LOCK TABLES ... WRITE'.
     It does have an effect for tables locked for read or write by
     'LOCK TABLES ... WRITE' implicitly (for example,
     through triggers) or by 'LOCK TABLES ... READ'.

     For related information, see
     innodb-locking-transaction-model.

   *
     'innodb_temp_data_file_path'

     Property                             Value

     *Command-Line Format*                '--innodb-temp-data-file-path=file'

     *Introduced*                         5.7.1

     *System Variable*                    'innodb_temp_data_file_path'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'ibtmp1:12M:autoextend'

     Defines the relative path, name, size, and attributes of 'InnoDB'
     temporary tablespace data files.  If you do not specify a value for
     'innodb_temp_data_file_path', the default behavior is to create a
     single, auto-extending data file named 'ibtmp1' in the MySQL data
     directory that is slightly larger than 12MB.

     The full syntax for a temporary tablespace data file specification
     includes the file name, file size, and 'autoextend' and 'max'
     attributes:

          FILE_NAME:FILE_SIZE[:autoextend[:max:MAX_FILE_SIZE]]

     The temporary tablespace data file cannot have the same name as
     another 'InnoDB' data file.  Any inability or error creating a
     temporary tablespace data file is treated as fatal and server
     startup is refused.  The temporary tablespace has a dynamically
     generated space ID, which can change on each server restart.

     File sizes are specified KB, MB or GB (1024MB) by appending 'K',
     'M' or 'G' to the size value.  The sum of the sizes of the files
     must be slightly larger than 12MB.

     The size limit of individual files is determined by your operating
     system.  You can set the file size to more than 4GB on operating
     systems that support large files.  Use of raw disk partitions for
     temporary tablespace data files is not supported.

     The 'autoextend' and 'max' attributes can be used only for the data
     file that is specified last in the 'innodb_temp_data_file_path'
     setting.  For example:

          [mysqld]
          innodb_temp_data_file_path=ibtmp1:50M;ibtmp2:12M:autoextend:max:500MB

     If you specify the 'autoextend' option, 'InnoDB' extends the data
     file if it runs out of free space.  The 'autoextend' increment is
     64MB by default.  To modify the increment, change the
     'innodb_autoextend_increment' system variable.

     The full directory path for temporary tablespace data files is
     formed by concatenating the paths defined by 'innodb_data_home_dir'
     and 'innodb_temp_data_file_path'.

     The temporary tablespace is shared by all non-compressed 'InnoDB'
     temporary tables.  Compressed temporary tables reside in
     file-per-table tablespace files created in the temporary file
     directory, which is defined by the 'tmpdir' configuration option.

     Before running 'InnoDB' in read-only mode, set
     'innodb_temp_data_file_path' to a location outside of the data
     directory.  The path must be relative to the data directory.  For
     example:

          --innodb_temp_data_file_path=../../../tmp/ibtmp1:12M:autoextend

     Metadata about active 'InnoDB' temporary tables is located in
     'INFORMATION_SCHEMA.INNODB_TEMP_TABLE_INFO'.

     For related information, see innodb-temporary-tablespace.

   *
     'innodb_tmpdir'

     Property                             Value

     *Command-Line Format*                '--innodb-tmpdir=path'

     *Introduced*                         5.7.11

     *System Variable*                    'innodb_tmpdir'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               directory name

     *Default Value*                      'NULL'

     Used to define an alternate directory for temporary sort files
     created during online 'ALTER TABLE' operations
     that rebuild the table.

     Online 'ALTER TABLE' operations that rebuild
     the table also create an _intermediate_ table file in the same
     directory as the original table.  The 'innodb_tmpdir' option is not
     applicable to intermediate table files.

     A valid value is any directory path other than the MySQL data
     directory path.  If the value is NULL (the default), temporary
     files are created MySQL temporary directory ('$TMPDIR' on Unix,
     '%TEMP%' on Windows, or the directory specified by the '--tmpdir'
     configuration option).  If a directory is specified, existence of
     the directory and permissions are only checked when 'innodb_tmpdir'
     is configured using a 'SET' statement.  If a
     symlink is provided in a directory string, the symlink is resolved
     and stored as an absolute path.  The path should not exceed 512
     bytes.  An online 'ALTER TABLE' operation
     reports an error if 'innodb_tmpdir' is set to an invalid directory.
     'innodb_tmpdir' overrides the MySQL 'tmpdir' setting but only for
     online 'ALTER TABLE' operations.

     The 'FILE' privilege is required to configure 'innodb_tmpdir'.

     The 'innodb_tmpdir' option was introduced to help avoid overflowing
     a temporary file directory located on a 'tmpfs' file system.  Such
     overflows could occur as a result of large temporary sort files
     created during online 'ALTER TABLE' operations
     that rebuild the table.

     In replication environments, only consider replicating the
     'innodb_tmpdir' setting if all servers have the same operating
     system environment.  Otherwise, replicating the 'innodb_tmpdir'
     setting could result in a replication failure when running online
     'ALTER TABLE' operations that rebuild the
     table.  If server operating environments differ, it is recommended
     that you configure 'innodb_tmpdir' on each server individually.

     For more information, see innodb-temporary-files.  For
     information about online 'ALTER TABLE'.
     operations, see innodb-online-ddl.

   *
     'innodb_thread_concurrency'

     Property                             Value

     *Command-Line Format*                '--innodb-thread-concurrency=#'

     *System Variable*                    'innodb_thread_concurrency'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1000'

     'InnoDB' tries to keep the number of operating system threads
     concurrently inside 'InnoDB' less than or equal to the limit given
     by this variable ('InnoDB' uses operating system threads to process
     user transactions).  Once the number of threads reaches this limit,
     additional threads are placed into a wait state within a 'First In,
     First Out' (FIFO) queue for execution.  Threads waiting for locks
     are not counted in the number of concurrently executing threads.

     The range of this variable is 0 to 1000.  A value of 0 (the
     default) is interpreted as infinite concurrency (no concurrency
     checking).  Disabling thread concurrency checking enables 'InnoDB'
     to create as many threads as it needs.  A value of 0 also disables
     the 'queries inside InnoDB' and 'queries in queue counters' in the
     'ROW OPERATIONS' section of 'SHOW ENGINE INNODB STATUS' output.

     Consider setting this variable if your MySQL instance shares CPU
     resources with other applications, or if your workload or number of
     concurrent users is growing.  The correct setting depends on
     workload, computing environment, and the version of MySQL that you
     are running.  You will need to test a range of values to determine
     the setting that provides the best performance.
     'innodb_thread_concurrency' is a dynamic variable, which allows you
     to experiment with different settings on a live test system.  If a
     particular setting performs poorly, you can quickly set
     'innodb_thread_concurrency' back to 0.

     Use the following guidelines to help find and maintain an
     appropriate setting:

        * If the number of concurrent user threads for a workload is
          less than 64, set 'innodb_thread_concurrency=0'.

        * If your workload is consistently heavy or occasionally spikes,
          start by setting 'innodb_thread_concurrency=128' and then
          lowering the value to 96, 80, 64, and so on, until you find
          the number of threads that provides the best performance.  For
          example, suppose your system typically has 40 to 50 users, but
          periodically the number increases to 60, 70, or even 200.  You
          find that performance is stable at 80 concurrent users but
          starts to show a regression above this number.  In this case,
          you would set 'innodb_thread_concurrency=80' to avoid
          impacting performance.

        * If you do not want 'InnoDB' to use more than a certain number
          of vCPUs for user threads (20 vCPUs, for example), set
          'innodb_thread_concurrency' to this number (or possibly lower,
          depending on performance results).  If your goal is to isolate
          MySQL from other applications, you may consider binding the
          'mysqld' process exclusively to the vCPUs.  Be aware, however,
          that exclusive binding could result in non-optimal hardware
          usage if the 'mysqld' process is not consistently busy.  In
          this case, you might bind the 'mysqld' process to the vCPUs
          but also allow other applications to use some or all of the
          vCPUs.

          *Note*:

          From an operating system perspective, using a resource
          management solution to manage how CPU time is shared among
          applications may be preferable to binding the 'mysqld'
          process.  For example, you could assign 90% of vCPU time to a
          given application while other critical process _are not_
          running, and scale that value back to 40% when other critical
          processes _are_ running.

        * 'innodb_thread_concurrency' values that are too high can cause
          performance regression due to increased contention on system
          internals and resources.

        * In some cases, the optimal 'innodb_thread_concurrency' setting
          can be smaller than the number of vCPUs.

        * Monitor and analyze your system regularly.  Changes to
          workload, number of users, or computing environment may
          require that you adjust the 'innodb_thread_concurrency'
          setting.

     For related information, see
     innodb-performance-thread_concurrency.

   *
     'innodb_trx_purge_view_update_only_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-trx-purge-view-update-only-debug=#'

     *System Variable*                    'innodb_trx_purge_view_update_only_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Pauses purging of delete-marked records while allowing the purge
     view to be updated.  This option artificially creates a situation
     in which the purge view is updated but purges have not yet been
     performed.  This option is only available if debugging support is
     compiled in using the 'WITH_DEBUG' 'CMake' option.

   *
     'innodb_trx_rseg_n_slots_debug'

     Property                             Value

     *Command-Line Format*                '--innodb-trx-rseg-n-slots-debug=#'

     *System Variable*                    'innodb_trx_rseg_n_slots_debug'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Maximum Value*                      '1024'

     Sets a debug flag that limits 'TRX_RSEG_N_SLOTS' to a given value
     for the 'trx_rsegf_undo_find_free' function that looks for free
     slots for undo log segments.  This option is only available if
     debugging support is compiled in using the 'WITH_DEBUG' 'CMake'
     option.

   *
     'innodb_thread_sleep_delay'

     Property                             Value

     *Command-Line Format*                '--innodb-thread-sleep-delay=#'

     *System Variable*                    'innodb_thread_sleep_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms, <=         integer
     5.7.3)

     *Type* (32-bit platforms, <=         integer
     5.7.3)

     *Type* (>= 5.7.4)                    integer

     *Default Value* (64-bit platforms,   '10000'
     <= 5.7.3)

     *Default Value* (32-bit platforms,   '10000'
     <= 5.7.3)

     *Default Value* (>= 5.7.4)           '10000'

     *Minimum Value* (64-bit platforms,   '0'
     <= 5.7.3)

     *Minimum Value* (32-bit platforms,   '0'
     <= 5.7.3)

     *Minimum Value* (>= 5.7.4)           '0'

     *Maximum Value* (64-bit platforms,   '18446744073709551615'
     <= 5.7.3)

     *Maximum Value* (32-bit platforms,   '4294967295'
     <= 5.7.3)

     *Maximum Value* (>= 5.7.4)           '1000000'

     Defines how long 'InnoDB' threads sleep before joining the 'InnoDB'
     queue, in microseconds.  The default value is 10000.  A value of 0
     disables sleep.  You can set the configuration option
     'innodb_adaptive_max_sleep_delay' to the highest value you would
     allow for 'innodb_thread_sleep_delay', and 'InnoDB' automatically
     adjusts 'innodb_thread_sleep_delay' up or down depending on current
     thread-scheduling activity.  This dynamic adjustment helps the
     thread scheduling mechanism to work smoothly during times when the
     system is lightly loaded or when it is operating near full
     capacity.

     For more information, see
     innodb-performance-thread_concurrency.

   *
     'innodb_undo_directory'

     Property                             Value

     *Command-Line Format*                '--innodb-undo-directory=dir_name'

     *System Variable*                    'innodb_undo_directory'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     *Default Value* (<= 5.7.7)           '.'

     The path where 'InnoDB' creates undo tablespaces.  Typically used
     to place undo logs on a different storage device.  Used in
     conjunction with 'innodb_rollback_segments' and
     'innodb_undo_tablespaces'.

     There is no default value (it is NULL). If a path is not specified,
     undo tablespaces are created in the MySQL data directory, as
     defined by 'datadir'.

     For more information, see innodb-undo-tablespace.

   *
     'innodb_undo_log_truncate'

     Property                             Value

     *Command-Line Format*                '--innodb-undo-log-truncate=#'

     *Introduced*                         5.7.5

     *System Variable*                    'innodb_undo_log_truncate'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (>= 5.7.5)                    boolean

     *Default Value* (>= 5.7.5)           'OFF'

     When enabled, undo tablespaces that exceed the threshold value
     defined by 'innodb_max_undo_log_size' are marked for truncation.
     Only undo tablespaces can be truncated.  Truncating undo logs that
     reside in the system tablespace is not supported.  For truncation
     to occur, there must be at least two undo tablespaces and two
     redo-enabled undo logs configured to use undo tablespaces.  This
     means that 'innodb_undo_tablespaces' must be set to a value equal
     to or greater than 2, and 'innodb_rollback_segments' must set to a
     value equal to or greater than 35.

     The 'innodb_purge_rseg_truncate_frequency' configuration option can
     be used to expedite truncation of undo tablepaces.

     For more information, see truncate-undo-tablespace.

   *
     'innodb_undo_logs'

     Property                             Value

     *Command-Line Format*                '--innodb-undo-logs=#'

     *Deprecated*                         5.7.19

     *System Variable*                    'innodb_undo_logs'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '128'

     *Minimum Value*                      '1'

     *Maximum Value*                      '128'

     *Note*:

     'innodb_undo_logs' is deprecated and will be removed in a future
     release.

     Defines the number of rollback segments used by 'InnoDB'.  The
     'innodb_undo_logs' option is an alias for
     'innodb_rollback_segments'.  For more information, see the
     description of 'innodb_rollback_segments'.

   *
     'innodb_undo_tablespaces'

     Property                             Value

     *Command-Line Format*                '--innodb-undo-tablespaces=#'

     *Deprecated*                         5.7.21

     *System Variable*                    'innodb_undo_tablespaces'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value* (>= 5.7.8)           '95'

     *Maximum Value* (<= 5.7.7)           '126'

     The number of undo tablespaces used by 'InnoDB'.  The default value
     is 0.

     *Note*:

     'innodb_undo_tablespaces' is deprecated and will be removed in a
     future release.

     Because undo logs can become large during long-running
     transactions, having undo logs in multiple tablespaces reduces the
     maximum size of any one tablespace.  The undo tablespace files are
     created in the location defined by 'innodb_undo_directory', with
     names in the form of 'undoN', where N is a sequential series of
     integers (including leading zeros) representing the space ID.

     The initial size of an undo tablespace file depends on the
     'innodb_page_size' value.  For the default 16k 'InnoDB' page size,
     the initial undo tablespace file size is 10MiB. For 4k, 8k, 32k,
     and 64k page sizes, the initial undo tablespace files sizes are
     7MiB, 8MiB, 20MiB, and 40MiB, respectively.

     A minimum of two undo tablespaces is required to enable truncation
     of undo logs.  See truncate-undo-tablespace.

     *Important*:

     'innodb_undo_tablespaces' can only be configured prior to
     initializing the MySQL instance and cannot be changed afterward.
     If no value is specified, the instance is initialized using the
     default setting of 0.  Attempting to restart 'InnoDB' with a
     greater number of undo tablespaces than specified when the MySQL
     instance was initialized results in a startup failure and an error
     stating that 'InnoDB' did not find the expected number of undo
     tablespaces.

     32 of 128 rollback segments are reserved for temporary tables, as
     described in innodb-temporary-table-undo-logs.  One
     rollback segment is always assigned to the system tablespace, which
     leaves 95 rollback segments available for undo tablepaces.  This
     means the 'innodb_undo_tablespaces' maximum limit is 95.

     For more information, see innodb-undo-tablespace.

   *
     'innodb_use_native_aio'

     Property                             Value

     *Command-Line Format*                '--innodb-use-native-aio=#'

     *System Variable*                    'innodb_use_native_aio'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     Specifies whether to use the Linux asynchronous I/O subsystem.
     This variable applies to Linux systems only, and cannot be changed
     while the server is running.  Normally, you do not need to
     configure this option, because it is enabled by default.

     The asynchronous I/O capability that 'InnoDB' has on Windows
     systems is available on Linux systems.  (Other Unix-like systems
     continue to use synchronous I/O calls.)  This feature improves the
     scalability of heavily I/O-bound systems, which typically show many
     pending reads/writes in 'SHOW ENGINE INNODB STATUS\G' output.

     Running with a large number of 'InnoDB' I/O threads, and especially
     running multiple such instances on the same server machine, can
     exceed capacity limits on Linux systems.  In this case, you may
     receive the following error:

          EAGAIN: The specified maxevents exceeds the user's limit of available events.

     You can typically address this error by writing a higher limit to
     '/proc/sys/fs/aio-max-nr'.

     However, if a problem with the asynchronous I/O subsystem in the OS
     prevents 'InnoDB' from starting, you can start the server with
     'innodb_use_native_aio=0'.  This option may also be disabled
     automatically during startup if 'InnoDB' detects a potential
     problem such as a combination of 'tmpdir' location, 'tmpfs' file
     system, and Linux kernel that does not support AIO on 'tmpfs'.

     For more information, see innodb-linux-native-aio.

   *
     'innodb_use_sys_malloc'

     Property                             Value

     *Command-Line Format*                '--innodb-use-sys-malloc=#'

     *Deprecated*                         Yes (removed in 5.7.4)

     *System Variable*                    'innodb_use_sys_malloc'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     Enables the operating system memory allocator.  If disabled,
     'InnoDB' uses its own allocator.  The default value is 'ON'.  For
     more information, see innodb-performance-use_sys_malloc.

     'innodb_use_sys_malloc' is removed in MySQL 5.7.

   *
     'innodb_version'

     The 'InnoDB' version number.  In MySQL 5.7, separate version
     numbering for 'InnoDB' does not apply and this value is the same
     the 'version' number of the server.

   *
     'innodb_write_io_threads'

     Property                             Value

     *Command-Line Format*                '--innodb-write-io-threads=#'

     *System Variable*                    'innodb_write_io_threads'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '4'

     *Minimum Value*                      '1'

     *Maximum Value*                      '64'

     The number of I/O threads for write operations in 'InnoDB'.  The
     default value is 4.  Its counterpart for read threads is
     'innodb_read_io_threads'.  For more information, see
     innodb-performance-multiple_io_threads.  For general I/O tuning
     advice, see optimizing-innodb-diskio.

     *Note*:

     On Linux systems, running multiple MySQL servers (typically more
     than 12) with default settings for 'innodb_read_io_threads',
     'innodb_write_io_threads', and the Linux 'aio-max-nr' setting can
     exceed system limits.  Ideally, increase the 'aio-max-nr' setting;
     as a workaround, you might reduce the settings for one or both of
     the MySQL configuration options.

     Also take into consideration the value of 'sync_binlog', which
     controls synchronization of the binary log to disk.

     For general I/O tuning advice, see
     optimizing-innodb-diskio.

14.15 InnoDB INFORMATION_SCHEMA Tables
======================================

This section provides information and usage examples for 'InnoDB'
'INFORMATION_SCHEMA' tables.

'InnoDB' 'INFORMATION_SCHEMA' tables provide metadata, status
information, and statistics about various aspects of the 'InnoDB'
storage engine.  You can view a list of 'InnoDB' 'INFORMATION_SCHEMA'
tables by issuing a 'SHOW TABLES' statement on the
'INFORMATION_SCHEMA' database:

     mysql> SHOW TABLES FROM INFORMATION_SCHEMA LIKE 'INNODB%';

For table definitions, see innodb-i_s-tables.  For general
information regarding the 'MySQL' 'INFORMATION_SCHEMA' database, see
information-schema.

14.15.1 InnoDB INFORMATION_SCHEMA Tables about Compression
----------------------------------------------------------

There are two pairs of 'InnoDB' 'INFORMATION_SCHEMA' tables about
compression that can provide insight into how well compression is
working overall:

   * 'INNODB_CMP' and 'INNODB_CMP_RESET'
     contain information about the number of
     compression operations and the amount of time spent performing
     compression.

   * 'INNODB_CMPMEM' and
     'INNODB_CMP_RESET' contain information about the
     way memory is allocated for compression.

14.15.1.1 INNODB_CMP and INNODB_CMP_RESET
.........................................

The 'INNODB_CMP' and 'INNODB_CMP_RESET'
tables contain status information about operations
related to compressed tables, which are described in
innodb-compression.  The 'PAGE_SIZE' column reports the compressed
page size.

These two tables have identical contents, but reading from
'INNODB_CMP_RESET' resets the statistics on
compression and uncompression operations.  For example, if you archive
the output of 'INNODB_CMP_RESET' every 60
minutes, you see the statistics for each hourly period.  If you monitor
the output of 'INNODB_CMP'. (making sure never
to read 'INNODB_CMP_RESET'), you see the
cumulated statistics since InnoDB was started.

For the table definition, see innodb-cmp-table.

14.15.1.2 INNODB_CMPMEM and INNODB_CMPMEM_RESET
...............................................

The 'INNODB_CMPMEM' and
'INNODB_CMPMEM_RESET' tables contain status
information about compressed pages that reside in the buffer pool.
Please consult innodb-compression for further information on
compressed tables and the use of the buffer pool.  The
'INNODB_CMP' and 'INNODB_CMP_RESET'
tables should provide more useful statistics on
compression.

*Internal Details*

'InnoDB' uses a buddy allocator system to manage memory allocated to
pages of various sizes, from 1KB to 16KB. Each row of the two tables
described here corresponds to a single page size.

The 'INNODB_CMPMEM' and
'INNODB_CMPMEM_RESET' tables have identical
contents, but reading from 'INNODB_CMPMEM_RESET'
resets the statistics on relocation operations.
For example, if every 60 minutes you archived the output of
'INNODB_CMPMEM_RESET', it would show the hourly
statistics.  If you never read 'INNODB_CMPMEM_RESET'
and monitored the output of 'INNODB_CMPMEM'
instead, it would show the cumulated statistics
since 'InnoDB' was started.

For the table definition, see innodb-cmpmem-table.

14.15.1.3 Using the Compression Information Schema Tables
.........................................................

The following is sample output from a database that contains compressed
tables (see innodb-compression, 'INNODB_CMP',
see 'INNODB_CMP_PER_INDEX',
and 'INNODB_CMPMEM').

The following table shows the contents of
'INFORMATION_SCHEMA.INNODB_CMP' under a light
workload.  The only compressed page size that the buffer pool contains
is 8K. Compressing or uncompressing pages has consumed less than a
second since the time the statistics were reset, because the columns
'COMPRESS_TIME' and 'UNCOMPRESS_TIME' are zero.

page size   compress    compress    compress    uncompress     uncompress
            ops         ops ok      time        ops            time

1024        0           0           0           0              0

2048        0           0           0           0              0

4096        0           0           0           0              0

8192        1048        921         0           61             0

16384       0           0           0           0              0

According to 'INNODB_CMPMEM', there are 6169
compressed 8KB pages in the buffer pool.  The only other allocated block
size is 64 bytes.  The smallest 'PAGE_SIZE' in 'INNODB_CMPMEM'
is used for block descriptors of those compressed
pages for which no uncompressed page exists in the buffer pool.  We see
that there are 5910 such pages.  Indirectly, we see that 259 (6169-5910)
compressed pages also exist in the buffer pool in uncompressed form.

The following table shows the contents of
'INFORMATION_SCHEMA.INNODB_CMPMEM' under a light
workload.  Some memory is unusable due to fragmentation of the memory
allocator for compressed pages: 'SUM(PAGE_SIZE*PAGES_FREE)=6784'.  This
is because small memory allocation requests are fulfilled by splitting
bigger blocks, starting from the 16K blocks that are allocated from the
main buffer pool, using the buddy allocation system.  The fragmentation
is this low because some allocated blocks have been relocated (copied)
to form bigger adjacent free blocks.  This copying of
'SUM(PAGE_SIZE*RELOCATION_OPS)' bytes has consumed less than a second
'(SUM(RELOCATION_TIME)=0)'.

page size   pages       pages free     relocation     relocation
            used                       ops            time

64          5910        0              2436           0

128         0           1              0              0

256         0           0              0              0

512         0           1              0              0

1024        0           0              0              0

2048        0           1              0              0

4096        0           1              0              0

8192        6169        0              5              0

16384       0           0              0              0

14.15.2 InnoDB INFORMATION_SCHEMA Transaction and Locking Information
---------------------------------------------------------------------

Three 'InnoDB' 'INFORMATION_SCHEMA' tables enable you to monitor
transactions and diagnose potential locking problems:

   * 'INNODB_TRX'.: Contains information about
     every transaction currently executing inside 'InnoDB', including
     the transaction state (for example, whether it is running or
     waiting for a lock), when the transaction started, and the
     particular SQL statement the transaction is executing.

   * 'INNODB_LOCKS'.: Each transaction in
     InnoDB that is waiting for another transaction to release a lock
     ('INNODB_TRX.TRX_STATE' is 'LOCK WAIT') is blocked by exactly one
     blocking lock request.  That blocking lock request is for a row or
     table lock held by another transaction in an incompatible mode.  A
     lock that blocks a transaction is always held in a mode
     incompatible with the mode of requested lock (read vs.  write,
     shared vs.  exclusive).  The blocked transaction cannot proceed
     until the other transaction commits or rolls back, thereby
     releasing the requested lock.  For every blocked transaction, see
     'INNODB_LOCKS' contains one row that describes
     each lock the transaction has requested, and for which it is
     waiting.  'INNODB_LOCKS' also contains
     one row for each lock that is blocking another transaction,
     whatever the state of the transaction that holds the lock
     ('INNODB_TRX.TRX_STATE' is 'RUNNING', 'LOCK WAIT', 'ROLLING BACK'
     or 'COMMITTING').

   * 'INNODB_LOCK_WAITS'.: This table
     indicates which transactions are waiting for a given lock, or for
     which lock a given transaction is waiting.  This table contains one
     or more rows for each blocked transaction, indicating the lock it
     has requested and any locks that are blocking that request.  The
     'REQUESTED_LOCK_ID' value refers to the lock requested by a
     transaction, and the 'BLOCKING_LOCK_ID' value refers to the lock
     (held by another transaction) that prevents the first transaction
     from proceeding.  For any given blocked transaction, all rows in
     'INNODB_LOCK_WAITS' have the same
     value for 'REQUESTED_LOCK_ID' and different values for
     'BLOCKING_LOCK_ID'.

For more information about the preceding tables, see
innodb-trx-table, innodb-locks-table, and
innodb-lock-waits-table.

14.15.2.1 Using InnoDB Transaction and Locking Information
..........................................................

*Identifying Blocking Transactions*

It is sometimes helpful to identify which transaction blocks another.
The tables that contain information about 'InnoDB' transactions and data
locks enable you to determine which transaction is waiting for another,
and which resource is being requested.  (For descriptions of these
tables, see innodb-information-schema-transactions.)

Suppose that three sessions are running concurrently.  Each session
corresponds to a MySQL thread, and executes one transaction after
another.  Consider the state of the system when these sessions have
issued the following statements, but none has yet committed its
transaction:

   * Session A:

          BEGIN;
          SELECT a FROM t FOR UPDATE;
          SELECT SLEEP(100);

   * Session B:

          SELECT b FROM t FOR UPDATE;

   * Session C:

          SELECT c FROM t FOR UPDATE;

In this scenario, use the following query to see which transactions are
waiting and which transactions are blocking them:

     SELECT
       r.trx_id waiting_trx_id,
       r.trx_mysql_thread_id waiting_thread,
       r.trx_query waiting_query,
       b.trx_id blocking_trx_id,
       b.trx_mysql_thread_id blocking_thread,
       b.trx_query blocking_query
     FROM       information_schema.innodb_lock_waits w
     INNER JOIN information_schema.innodb_trx b
       ON b.trx_id = w.blocking_trx_id
     INNER JOIN information_schema.innodb_trx r
       ON r.trx_id = w.requesting_trx_id;

Or, more simply, use the 'sys' schema 'innodb_lock_waits'
view:

     SELECT
       waiting_trx_id,
       waiting_pid,
       waiting_query,
       blocking_trx_id,
       blocking_pid,
       blocking_query
     FROM sys.innodb_lock_waits;

If a NULL value is reported for the blocking query, see
innodb-information-schema-examples-null-blocking-query.

waiting trx id                                                    waiting thread                                                    waiting query            blockingblockingblocking query
                                                                                                                                                             trx     thread
                                                                                                                                                             id

'A4'                                                              '6'                                                               'SELECT b FROM t FOR     'A3'    '5'     'SELECT SLEEP(100)'
                                                                                                                                    UPDATE'

'A5'                                                              '7'                                                               'SELECT c FROM t FOR     'A3'    '5'     'SELECT SLEEP(100)'
                                                                                                                                    UPDATE'

'A5'                                                              '7'                                                               'SELECT c FROM t FOR     'A4'    '6'     'SELECT b FROM t FOR
                                                                                                                                    UPDATE'                                  UPDATE'

In the preceding table, you can identify sessions by the 'waiting query'
or 'blocking query' columns.  As you can see:

   * Session B (trx id 'A4', thread '6') and Session C (trx id 'A5',
     thread '7') are both waiting for Session A (trx id 'A3', thread
     '5').

   * Session C is waiting for Session B as well as Session A.

You can see the underlying data in the tables 'INNODB_TRX',
'INNODB_LOCKS', and 'INNODB_LOCK_WAITS'.

The following table shows some sample contents of
'INFORMATION_SCHEMA.INNODB_TRX'.

trx     trx       trx started                trx requested lock     trx wait started           trx weight     trx mysql         trx query
id      state                                id                                                               thread id

'A3'    'RUN­NING''2008-01-15 16:44:54'     'NULL'                 'NULL'                     '2'            '5'               'SELECT SLEEP(100)'

'A4'    'LOCK     '2008-01-15 16:45:09'      'A4:1:3:2'             '2008-01-15 16:45:09'      '2'            '6'               'SELECT b FROM t FOR UPDATE'
        WAIT'

'A5'    'LOCK     '2008-01-15 16:45:14'      'A5:1:3:2'             '2008-01-15 16:45:14'      '2'            '7'               'SELECT c FROM t FOR UPDATE'
        WAIT'

The following table shows some sample contents of
'INFORMATION_SCHEMA.INNODB_LOCKS'.

lock id             lock      lock       lock type       lock table             lock index            lock data
                    trx id    mode

'A3:1:3:2'          'A3'      'X'        'RECORD'        'test.t'               'PRIMARY'             '0x0200'

'A4:1:3:2'          'A4'      'X'        'RECORD'        'test.t'               'PRIMARY'             '0x0200'

'A5:1:3:2'          'A5'      'X'        'RECORD'        'test.t'               'PRIMARY'             '0x0200'

The following table shows some sample contents of
'INFORMATION_SCHEMA.INNODB_LOCK_WAITS'.

requestingrequested blockingblocking
trx     lock id     trx     lock id
id                  id

'A4'    'A4:1:3:2'  'A3'    'A3:1:3:2'

'A5'    'A5:1:3:2'  'A3'    'A3:1:3:2'

'A5'    'A5:1:3:2'  'A4'    'A4:1:3:2'

*Identifying a Blocking Query After the Issuing Session Becomes Idle*

When identifying blocking transactions, a NULL value is reported for the
blocking query if the session that issued the query has become idle.  In
this case, use the following steps to determine the blocking query:

  1. Identify the processlist ID of the blocking transaction.  In the
     'sys.innodb_lock_waits' table, the
     processlist ID of the blocking transaction is the 'blocking_pid'
     value.

  2. Using the 'blocking_pid', query the MySQL Performance Schema
     'threads' table to determine the 'THREAD_ID' of the
     blocking transaction.  For example, if the 'blocking_pid' is 6,
     issue this query:

          SELECT THREAD_ID FROM performance_schema.threads WHERE PROCESSLIST_ID = 6;

  3. Using the 'THREAD_ID', query the Performance Schema
     'events_statements_current' table
     to determine the last query executed by the thread.  For example,
     if the 'THREAD_ID' is 28, issue this query:

          SELECT THREAD_ID, SQL_TEXT FROM performance_schema.events_statements_current
          WHERE THREAD_ID = 28\G

  4. If the last query executed by the thread is not enough information
     to determine why a lock is held, you can query the Performance
     Schema 'events_statements_history'
     table to view the last 10
     statements executed by the thread.

          SELECT THREAD_ID, SQL_TEXT FROM performance_schema.events_statements_history
          WHERE THREAD_ID = 28 ORDER BY EVENT_ID;

*Correlating InnoDB Transactions with MySQL Sessions*

Sometimes it is useful to correlate internal 'InnoDB' locking
information with the session-level information maintained by MySQL. For
example, you might like to know, for a given 'InnoDB' transaction ID,
the corresponding MySQL session ID and name of the session that may be
holding a lock, and thus blocking other transactions.

The following output from the 'INFORMATION_SCHEMA' tables is taken from
a somewhat loaded system.  As can be seen, there are several
transactions running.

The following 'INNODB_LOCKS' and 'INNODB_LOCK_WAITS' tables show that:

   * Transaction '77F' (executing an 'INSERT') is waiting
     for transactions '77E', '77D', and '77B' to commit.

   * Transaction '77E' (executing an 'INSERT') is waiting
     for transactions '77D' and '77B' to commit.

   * Transaction '77D' (executing an 'INSERT') is waiting
     for transaction '77B' to commit.

   * Transaction '77B' (executing an 'INSERT') is waiting
     for transaction '77A' to commit.

   * Transaction '77A' is running, currently executing 'SELECT'.

   * Transaction 'E56' (executing an 'INSERT') is waiting
     for transaction 'E55' to commit.

   * Transaction 'E55' (executing an 'INSERT') is waiting
     for transaction '19C' to commit.

   * Transaction '19C' is running, currently executing an
     'INSERT'.

*Note*:

There may be inconsistencies between queries shown in the
'INFORMATION_SCHEMA' 'PROCESSLIST' and
'INNODB_TRX' tables.  For an explanation, see
innodb-information-schema-internal-data.

The following table shows the contents of
'INFORMATION_SCHEMA.PROCESSLIST' for a system
running a heavy workload.

ID                                                         USER     HOST            DB      COMMAND        TIME    STATE          INFO

'384'                                                      'root'   'localhost'     'test'  'Query'        '10'    'update'       'INSERT INTO t2
                                                                                                                                  VALUES ...'

'257'                                                      'root'   'localhost'     'test'  'Query'        '3'     'update'       'INSERT INTO t2
                                                                                                                                  VALUES ...'

'130'                                                      'root'   'localhost'     'test'  'Query'        '0'     'update'       'INSERT INTO t2
                                                                                                                                  VALUES ...'

'61'                                                       'root'   'localhost'     'test'  'Query'        '1'     'update'       'INSERT INTO t2
                                                                                                                                  VALUES ...'

'8'                                                        'root'   'localhost'     'test'  'Query'        '1'     'update'       'INSERT INTO t2
                                                                                                                                  VALUES ...'

'4'                                                        'root'   'localhost'     'test'  'Query'        '0'     'preparing'    'SELECT * FROM
                                                                                                                                  PROCESSLIST'

'2'                                                        'root'   'localhost'     'test'  'Sleep'        '566'   ''             'NULL'

The following table shows the contents of
'INFORMATION_SCHEMA.INNODB_TRX' for a system running
a heavy workload.

trx id                                                     trx     trx started    trx requested   trx wait       trx     trx     trx query
                                                           state                  lock id         started        weight  mysql
                                                                                                                         thread
                                                                                                                         id

'77F'                                                      'LOCK   '2008-01-15    '77F'           '2008-01-15    '1'     '876'   'INSERT INTO t09 (D,
                                                           WAIT'   13:10:16'                      13:10:16'                      B, C) VALUES ...'

'77E'                                                      'LOCK   '2008-01-15    '77E'           '2008-01-15    '1'     '875'   'INSERT INTO t09 (D,
                                                           WAIT'   13:10:16'                      13:10:16'                      B, C) VALUES ...'

'77D'                                                      'LOCK   '2008-01-15    '77D'           '2008-01-15    '1'     '874'   'INSERT INTO t09 (D,
                                                           WAIT'   13:10:16'                      13:10:16'                      B, C) VALUES ...'

'77B'                                                      'LOCK   '2008-01-15    '77B:733:12:1'  '2008-01-15    '4'     '873'   'INSERT INTO t09 (D,
                                                           WAIT'   13:10:16'                      13:10:16'                      B, C) VALUES ...'

'77A'                                                      'RUN­NING''2008-01-15 'NULL'          'NULL'         '4'     '872'   'SELECT b, c FROM
                                                                   13:10:16'                                                     t09 WHERE ...'

'E56'                                                      'LOCK   '2008-01-15    'E56:743:6:2'   '2008-01-15    '5'     '384'   'INSERT INTO t2
                                                           WAIT'   13:10:06'                      13:10:06'                      VALUES ...'

'E55'                                                      'LOCK   '2008-01-15    'E55:743:38:2'  '2008-01-15    '965'   '257'   'INSERT INTO t2
                                                           WAIT'   13:10:06'                      13:10:13'                      VALUES ...'

'19C'                                                      'RUN­NING''2008-01-15 'NULL'          'NULL'         '2900'  '130'   'INSERT INTO t2
                                                                   13:09:10'                                                     VALUES ...'

'E15'                                                      'RUN­NING''2008-01-15 'NULL'          'NULL'         '5395'  '61'    'INSERT INTO t2
                                                                   13:08:59'                                                     VALUES ...'

'51D'                                                      'RUN­NING''2008-01-15 'NULL'          'NULL'         '9807'  '8'     'INSERT INTO t2
                                                                   13:08:47'                                                     VALUES ...'

The following table shows the contents of
'INFORMATION_SCHEMA.INNODB_LOCK_WAITS' for a
system running a heavy workload.

requestingrequested    blockingblocking
trx     lock id        trx     lock id
id                     id

'77F'   '77F:806'      '77E'   '77E:806'

'77F'   '77F:806'      '77D'   '77D:806'

'77F'   '77F:806'      '77B'   '77B:806'

'77E'   '77E:806'      '77D'   '77D:806'

'77E'   '77E:806'      '77B'   '77B:806'

'77D'   '77D:806'      '77B'   '77B:806'

'77B'   '77B:733:12:1' '77A'   '77A:733:12:1'

'E56'   'E56:743:6:2'  'E55'   'E55:743:6:2'

'E55'   'E55:743:38:2' '19C'   '19C:743:38:2'

The following table shows the contents of
'INFORMATION_SCHEMA.INNODB_LOCKS' for a system
running a heavy workload.

lock id       lock trx id                                                       lock      lock      lock       lock index   lock data
                                                                                mode      type      table

'77F:806'     '77F'                                                             'AUTO_INC''TABLE'   'test.t09' 'NULL'       'NULL'

'77E:806'     '77E'                                                             'AUTO_INC''TABLE'   'test.t09' 'NULL'       'NULL'

'77D:806'     '77D'                                                             'AUTO_INC''TABLE'   'test.t09' 'NULL'       'NULL'

'77B:806'     '77B'                                                             'AUTO_INC''TABLE'   'test.t09' 'NULL'       'NULL'

'77B:733:12:1''77B'                                                             'X'       'RECORD'  'test.t09' 'PRIMARY'    'supremum
                                                                                                                            pseudo-record'

'77A:733:12:1''77A'                                                             'X'       'RECORD'  'test.t09' 'PRIMARY'    'supremum
                                                                                                                            pseudo-record'

'E56:743:6:2' 'E56'                                                             'S'       'RECORD'  'test.t2'  'PRIMARY'    '0, 0'

'E55:743:6:2' 'E55'                                                             'X'       'RECORD'  'test.t2'  'PRIMARY'    '0, 0'

'E55:743:38:2''E55'                                                             'S'       'RECORD'  'test.t2'  'PRIMARY'    '1922,
                                                                                                                            1922'

'19C:743:38:2''19C'                                                             'X'       'RECORD'  'test.t2'  'PRIMARY'    '1922,
                                                                                                                            1922'

14.15.2.2 InnoDB Lock and Lock-Wait Information
...............................................

When a transaction updates a row in a table, or locks it with 'SELECT
FOR UPDATE', 'InnoDB' establishes a list or queue of locks on that row.
Similarly, 'InnoDB' maintains a list of locks on a table for table-level
locks.  If a second transaction wants to update a row or lock a table
already locked by a prior transaction in an incompatible mode, 'InnoDB'
adds a lock request for the row to the corresponding queue.  For a lock
to be acquired by a transaction, all incompatible lock requests
previously entered into the lock queue for that row or table must be
removed (which occurs when the transactions holding or requesting those
locks either commit or roll back).

A transaction may have any number of lock requests for different rows or
tables.  At any given time, a transaction may request a lock that is
held by another transaction, in which case it is blocked by that other
transaction.  The requesting transaction must wait for the transaction
that holds the blocking lock to commit or roll back.  If a transaction
is not waiting for a lock, it is in a 'RUNNING' state.  If a transaction
is waiting for a lock, it is in a 'LOCK WAIT' state.  (The
'INFORMATION_SCHEMA' 'INNODB_TRX' table
indicates transaction state values.)

The 'INNODB_LOCKS' table holds one or more
rows for each 'LOCK WAIT' transaction, indicating any lock requests that
prevent its progress.  This table also contains one row describing each
lock in a queue of locks pending for a given row or table.  The
'INNODB_LOCK_WAITS' table shows which locks
already held by a transaction are blocking locks requested by other
transactions.

14.15.2.3 Persistence and Consistency of InnoDB Transaction and Locking Information
...................................................................................

The data exposed by the transaction and locking tables (see
'INNODB_TRX', 'INNODB_LOCKS',
and 'INNODB_LOCK_WAITS')
represents a glimpse into fast-changing data.
This is not like user tables, where the data changes only when
application-initiated updates occur.  The underlying data is internal
system-managed data, and can change very quickly.

For performance reasons, and to minimize the chance of misleading joins
between the transaction and locking tables, 'InnoDB' collects the
required transaction and locking information into an intermediate buffer
whenever a 'SELECT' on any of the tables is issued.  This buffer is
refreshed only if more than 0.1 seconds has elapsed since the last time
the buffer was read.  The data needed to fill the three tables is
fetched atomically and consistently and is saved in this global internal
buffer, forming a point-in-time 'snapshot'.  If multiple table accesses
occur within 0.1 seconds (as they almost certainly do when MySQL
processes a join among these tables), then the same snapshot is used to
satisfy the query.

A correct result is returned when you join any of these tables together
in a single query, because the data for the three tables comes from the
same snapshot.  Because the buffer is not refreshed with every query of
any of these tables, if you issue separate queries against these tables
within a tenth of a second, the results are the same from query to
query.  On the other hand, two separate queries of the same or different
tables issued more than a tenth of a second apart may see different
results, since the data come from different snapshots.

Because 'InnoDB' must temporarily stall while the transaction and
locking data is collected, too frequent queries of these tables can
negatively impact performance as seen by other users.

As these tables contain sensitive information (at least
'INNODB_LOCKS.LOCK_DATA' and 'INNODB_TRX.TRX_QUERY'), for security
reasons, only the users with the 'PROCESS' privilege are allowed to
'SELECT' from them.

As described previously, the data that fills the transaction and locking
tables (see 'INNODB_TRX', 'INNODB_LOCKS'
and 'INNODB_LOCK_WAITS')
is fetched automatically and saved to an
intermediate buffer that provides a 'point-in-time' snapshot.  The data
across all three tables is consistent when queried from the same
snapshot.  However, the underlying data changes so fast that similar
glimpses at other, similarly fast-changing data, may not be in
synchrony.  Thus, you should be careful when comparing data in the
'InnoDB' transaction and locking tables with data in the
'PROCESSLIST' table.  The data from the
'PROCESSLIST' table does not come from the same
snapshot as the data about locking and transactions.  Even if you issue
a single 'SELECT' (joining 'INNODB_TRX' and
'PROCESSLIST', for example), the content of
those tables is generally not consistent.  'INNODB_TRX'
may reference rows that are not present in
'PROCESSLIST' or the currently executing SQL query
of a transaction shown in 'INNODB_TRX.TRX_QUERY' may differ from the one
in 'PROCESSLIST.INFO'.

14.15.3 InnoDB INFORMATION_SCHEMA System Tables
-----------------------------------------------

You can extract metadata about schema objects managed by 'InnoDB' using
'InnoDB' 'INFORMATION_SCHEMA' system tables.  This information comes
from the 'InnoDB' internal system tables (also referred to as the
'InnoDB' data dictionary), which cannot be queried directly like regular
'InnoDB' tables.  Traditionally, you would get this type of information
using the techniques from innodb-monitors, setting up 'InnoDB'
monitors and parsing the output from the 'SHOW ENGINE INNODB STATUS'
statement.  The 'InnoDB' 'INFORMATION_SCHEMA'
table interface allows you to query this data using SQL.

With the exception of 'INNODB_SYS_TABLESTATS',
for which there is no corresponding
internal system table, 'InnoDB' 'INFORMATION_SCHEMA' system tables are
populated with data read directly from internal 'InnoDB' system tables
rather than from metadata that is cached in memory.

'InnoDB' 'INFORMATION_SCHEMA' system tables include the tables listed
below.  'INNODB_SYS_DATAFILES' and
'INNODB_SYS_TABLESPACES' were added
in MySQL 5.6.6 with the introduction of support for the 'DATA
DIRECTORY='DIRECTORY'' clause of the 'CREATE TABLE'.
statement, which allows 'InnoDB' file-per-table tablespaces ('.ibd'
files) to be created in a location outside the MySQL data directory.

     mysql> SHOW TABLES FROM INFORMATION_SCHEMA LIKE 'INNODB_SYS%';
     +--------------------------------------------+
     | Tables_in_information_schema (INNODB_SYS%) |
     +--------------------------------------------+
     | INNODB_SYS_DATAFILES                       |
     | INNODB_SYS_TABLESTATS                      |
     | INNODB_SYS_FOREIGN                         |
     | INNODB_SYS_COLUMNS                         |
     | INNODB_SYS_INDEXES                         |
     | INNODB_SYS_FIELDS                          |
     | INNODB_SYS_TABLESPACES                     |
     | INNODB_SYS_FOREIGN_COLS                    |
     | INNODB_SYS_TABLES                          |
     +--------------------------------------------+

The table names are indicative of the type of data provided:

   * 'INNODB_SYS_TABLES' provides
     metadata about 'InnoDB' tables, equivalent to the information in
     the 'SYS_TABLES' table in the 'InnoDB' data dictionary.

   * 'INNODB_SYS_COLUMNS' provides
     metadata about 'InnoDB' table columns, equivalent to the
     information in the 'SYS_COLUMNS' table in the 'InnoDB' data
     dictionary.

   * 'INNODB_SYS_INDEXES' provides
     metadata about 'InnoDB' indexes, equivalent to the information in
     the 'SYS_INDEXES' table in the 'InnoDB' data dictionary.

   * 'INNODB_SYS_FIELDS' provides
     metadata about the key columns (fields) of 'InnoDB' indexes,
     equivalent to the information in the 'SYS_FIELDS' table in the
     'InnoDB' data dictionary.

   * 'INNODB_SYS_TABLESTATS'.
     provides a view of low-level status information about 'InnoDB'
     tables that is derived from in-memory data structures.  There is no
     corresponding internal 'InnoDB' system table.

   * 'INNODB_SYS_DATAFILES' provides
     data file path information for 'InnoDB' file-per-table and general
     tablespaces, equivalent to information in the 'SYS_DATAFILES' table
     in the 'InnoDB' data dictionary.

   * 'INNODB_SYS_TABLESPACES'.
     provides metadata about 'InnoDB' file-per-table and general
     tablespaces, equivalent to the information in the 'SYS_TABLESPACES'
     table in the 'InnoDB' data dictionary.

   * 'INNODB_SYS_FOREIGN' provides
     metadata about foreign keys defined on 'InnoDB' tables, equivalent
     to the information in the 'SYS_FOREIGN' table in the 'InnoDB' data
     dictionary.

   * 'INNODB_SYS_FOREIGN_COLS'.
     provides metadata about the columns of foreign keys that are
     defined on 'InnoDB' tables, equivalent to the information in the
     'SYS_FOREIGN_COLS' table in the 'InnoDB' data dictionary.

'InnoDB' 'INFORMATION_SCHEMA' system tables can be joined together
through fields such as 'TABLE_ID', 'INDEX_ID', and 'SPACE', allowing you
to easily retrieve all available data for an object you want to study or
monitor.

Refer to the 'InnoDB' INFORMATION_SCHEMA.
documentation for information about the columns of each table.

This example uses a simple table ('t1') with a single index ('i1') to
demonstrate the type of metadata found in the 'InnoDB'
'INFORMATION_SCHEMA' system tables.

  1. Create a test database and table 't1':

          mysql> CREATE DATABASE test;

          mysql> USE test;

          mysql> CREATE TABLE t1 (
                 col1 INT,
                 col2 CHAR(10),
                 col3 VARCHAR(10))
                 ENGINE = InnoDB;

          mysql> CREATE INDEX i1 ON t1(col1);

  2. After creating the table 't1', query 'INNODB_SYS_TABLES'
     to locate the metadata for 'test/t1':

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME='test/t1' \G
          *************************** 1. row ***************************
               TABLE_ID: 71
                   NAME: test/t1
                   FLAG: 1
                 N_COLS: 6
                  SPACE: 57
            FILE_FORMAT: Antelope
             ROW_FORMAT: Compact
          ZIP_PAGE_SIZE: 0
          ...

     Table 't1' has a 'TABLE_ID' of 71.  The 'FLAG' field provides bit
     level information about table format and storage characteristics.
     There are six columns, three of which are hidden columns created by
     'InnoDB' ('DB_ROW_ID', 'DB_TRX_ID', and 'DB_ROLL_PTR').  The ID of
     the table's 'SPACE' is 57 (a value of 0 would indicate that the
     table resides in the system tablespace).  The 'FILE_FORMAT' is
     Antelope, and the 'ROW_FORMAT' is Compact.  'ZIP_PAGE_SIZE' only
     applies to tables with a 'Compressed' row format.

  3. Using the 'TABLE_ID' information from 'INNODB_SYS_TABLES',
     query the 'INNODB_SYS_COLUMNS'
     table for information about the table's
     columns.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_COLUMNS where TABLE_ID = 71 \G
          *************************** 1. row ***************************
          TABLE_ID: 71
              NAME: col1
               POS: 0
             MTYPE: 6
            PRTYPE: 1027
               LEN: 4
          *************************** 2. row ***************************
          TABLE_ID: 71
              NAME: col2
               POS: 1
             MTYPE: 2
            PRTYPE: 524542
               LEN: 10
          *************************** 3. row ***************************
          TABLE_ID: 71
              NAME: col3
               POS: 2
             MTYPE: 1
            PRTYPE: 524303
               LEN: 10

     In addition to the 'TABLE_ID' and column 'NAME', see
     'INNODB_SYS_COLUMNS' provides the
     ordinal position ('POS') of each column (starting from 0 and
     incrementing sequentially), the column 'MTYPE' or 'main type' (6 =
     INT, 2 = CHAR, 1 = VARCHAR), the 'PRTYPE' or 'precise type' (a
     binary value with bits that represent the MySQL data type,
     character set code, and nullability), and the column length
     ('LEN').

  4. Using the 'TABLE_ID' information from 'INNODB_SYS_TABLES'
     once again, query
     'INNODB_SYS_INDEXES' for information
     about the indexes associated with table 't1'.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_INDEXES WHERE TABLE_ID = 71 \G
          *************************** 1. row ***************************
                 INDEX_ID: 111
                     NAME: GEN_CLUST_INDEX
                 TABLE_ID: 71
                     TYPE: 1
                 N_FIELDS: 0
                  PAGE_NO: 3
                    SPACE: 57
          MERGE_THRESHOLD: 50
          *************************** 2. row ***************************
                 INDEX_ID: 112
                     NAME: i1
                 TABLE_ID: 71
                     TYPE: 0
                 N_FIELDS: 1
                  PAGE_NO: 4
                    SPACE: 57
          MERGE_THRESHOLD: 50

     'INNODB_SYS_INDEXES' returns data
     for two indexes.  The first index is 'GEN_CLUST_INDEX', which is a
     clustered index created by 'InnoDB' if the table does not have a
     user-defined clustered index.  The second index ('i1') is the
     user-defined secondary index.

     The 'INDEX_ID' is an identifier for the index that is unique across
     all databases in an instance.  The 'TABLE_ID' identifies the table
     that the index is associated with.  The index 'TYPE' value
     indicates the type of index (1 = Clustered Index, 0 = Secondary
     index).  The 'N_FILEDS' value is the number of fields that comprise
     the index.  'PAGE_NO' is the root page number of the index B-tree,
     and 'SPACE' is the ID of the tablespace where the index resides.  A
     nonzero value indicates that the index does not reside in the
     system tablespace.  'MERGE_THRESHOLD' defines a percentage
     threshold value for the amount of data in an index page.  If the
     amount of data in an index page falls below the this value (the
     default is 50%) when a row is deleted or when a row is shortened by
     an update operation, 'InnoDB' attempts to merge the index page with
     a neighboring index page.

  5. Using the 'INDEX_ID' information from 'INNODB_SYS_INDEXES',
     query 'INNODB_SYS_FIELDS'
     for information about the fields of index
     'i1'.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_FIELDS where INDEX_ID = 112 \G
          *************************** 1. row ***************************
          INDEX_ID: 112
              NAME: col1
               POS: 0

     'INNODB_SYS_FIELDS' provides the
     'NAME' of the indexed field and its ordinal position within the
     index.  If the index (i1) had been defined on multiple fields,
     see 'INNODB_SYS_FIELDS' would provide
     metadata for each of the indexed fields.

  6. Using the 'SPACE' information from 'INNODB_SYS_TABLES',
     query 'INNODB_SYS_TABLESPACES'
     table for information about the
     table's tablespace.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES WHERE SPACE = 57 \G
          *************************** 1. row ***************************
                  SPACE: 57
                   NAME: test/t1
                   FLAG: 0
            FILE_FORMAT: Antelope
             ROW_FORMAT: Compact or Redundant
              PAGE_SIZE: 16384
          ZIP_PAGE_SIZE: 0

     In addition to the 'SPACE' ID of the tablespace and the 'NAME' of
     the associated table, see 'INNODB_SYS_TABLESPACES'
     provides tablespace 'FLAG' data,
     which is bit level information about tablespace format and storage
     characteristics.  Also provided are tablespace 'FILE_FORMAT',
     'ROW_FORMAT', 'PAGE_SIZE', and several other tablespace metadata
     items.

  7. Using the 'SPACE' information from 'INNODB_SYS_TABLES'
     once again, query
     'INNODB_SYS_DATAFILES' for the
     location of the tablespace data file.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_DATAFILES WHERE SPACE = 57 \G
          *************************** 1. row ***************************
          SPACE: 57
           PATH: ./test/t1.ibd

     The datafile is located in the 'test' directory under MySQL's
     'data' directory.  If a file-per-table tablespace were created in a
     location outside the MySQL data directory using the 'DATA
     DIRECTORY' clause of the 'CREATE TABLE'.
     statement, the tablespace 'PATH' would be a fully qualified
     directory path.

  8. As a final step, insert a row into table 't1' ('TABLE_ID = 71') and
     view the data in the 'INNODB_SYS_TABLESTATS'
     table.  The data in this table is used
     by the MySQL optimizer to calculate which index to use when
     querying an 'InnoDB' table.  This information is derived from
     in-memory data structures.  There is no corresponding internal
     'InnoDB' system table.

          mysql> INSERT INTO t1 VALUES(5, 'abc', 'def');
          Query OK, 1 row affected (0.06 sec)

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLESTATS where TABLE_ID = 71 \G
          *************************** 1. row ***************************
                   TABLE_ID: 71
                       NAME: test/t1
          STATS_INITIALIZED: Initialized
                   NUM_ROWS: 1
           CLUST_INDEX_SIZE: 1
           OTHER_INDEX_SIZE: 0
           MODIFIED_COUNTER: 1
                    AUTOINC: 0
                  REF_COUNT: 1

     The 'STATS_INITIALIZED' field indicates whether or not statistics
     have been collected for the table.  'NUM_ROWS' is the current
     estimated number of rows in the table.  The 'CLUST_INDEX_SIZE' and
     'OTHER_INDEX_SIZE' fields report the number of pages on disk that
     store clustered and secondary indexes for the table, respectively.
     The 'MODIFIED_COUNTER' value shows the number of rows modified by
     DML operations and cascade operations from foreign keys.  The
     'AUTOINC' value is the next number to be issued for any
     autoincrement-based operation.  There are no autoincrement columns
     defined on table 't1', so the value is 0.  The 'REF_COUNT' value is
     a counter.  When the counter reaches 0, it signifies that the table
     metadata can be evicted from the table cache.

The 'INNODB_SYS_FOREIGN' and
'INNODB_SYS_FOREIGN_COLS' tables provide
data about foreign key relationships.  This example uses a parent table
and child table with a foreign key relationship to demonstrate the data
found in the 'INNODB_SYS_FOREIGN' and
'INNODB_SYS_FOREIGN_COLS' tables.

  1. Create the test database with parent and child tables:

          mysql> CREATE DATABASE test;

          mysql> USE test;

          mysql> CREATE TABLE parent (id INT NOT NULL,
                 PRIMARY KEY (id)) ENGINE=INNODB;

          mysql> CREATE TABLE child (id INT, parent_id INT,
                 INDEX par_ind (parent_id),
                 CONSTRAINT fk1
                 FOREIGN KEY (parent_id) REFERENCES parent(id)
                 ON DELETE CASCADE) ENGINE=INNODB;

  2. After the parent and child tables are created, query
     'INNODB_SYS_FOREIGN' and locate the
     foreign key data for the 'test/child' and 'test/parent' foreign key
     relationship:

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_FOREIGN \G
          *************************** 1. row ***************************
                ID: test/fk1
          FOR_NAME: test/child
          REF_NAME: test/parent
            N_COLS: 1
              TYPE: 1

     Metadata includes the foreign key 'ID' ('fk1'), which is named for
     the 'CONSTRAINT' that was defined on the child table.  The
     'FOR_NAME' is the name of the child table where the foreign key is
     defined.  'REF_NAME' is the name of the parent table (the
     'referenced' table).  'N_COLS' is the number of columns in the
     foreign key index.  'TYPE' is a numerical value representing bit
     flags that provide additional information about the foreign key
     column.  In this case, the 'TYPE' value is 1, which indicates that
     the 'ON DELETE CASCADE' option was specified for the foreign key.
     See the 'INNODB_SYS_FOREIGN' table
     definition for more information about 'TYPE' values.

  3. Using the foreign key 'ID', query 'INNODB_SYS_FOREIGN_COLS'
     to view data about the columns of
     the foreign key.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_FOREIGN_COLS WHERE ID = 'test/fk1' \G
          *************************** 1. row ***************************
                    ID: test/fk1
          FOR_COL_NAME: parent_id
          REF_COL_NAME: id
                   POS: 0

     'FOR_COL_NAME' is the name of the foreign key column in the child
     table, and 'REF_COL_NAME' is the name of the referenced column in
     the parent table.  The 'POS' value is the ordinal position of the
     key field within the foreign key index, starting at zero.

This example demonstrates joining three 'InnoDB' 'INFORMATION_SCHEMA'
system tables (see 'INNODB_SYS_TABLES',
'INNODB_SYS_TABLESPACES', and
'INNODB_SYS_TABLESTATS') to gather file
format, row format, page size, and index size information about tables
in the employees sample database.

The following table name aliases are used to shorten the query string:

   * 'INFORMATION_SCHEMA.INNODB_SYS_TABLES'.:
     a

   * 'INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES'.:
     b

   * 'INFORMATION_SCHEMA.INNODB_SYS_TABLESTATS'.:
     c

An 'IF()' control flow function is used to account for compressed
tables.  If a table is compressed, the index size is calculated using
'ZIP_PAGE_SIZE' rather than 'PAGE_SIZE'.  'CLUST_INDEX_SIZE' and
'OTHER_INDEX_SIZE', which are reported in bytes, are divided by
'1024*1024' to provide index sizes in megabytes (MBs).  MB values are
rounded to zero decimal spaces using the 'ROUND()' function.

     mysql> SELECT a.NAME, a.FILE_FORMAT, a.ROW_FORMAT,
             @page_size :=
              IF(a.ROW_FORMAT='Compressed',
               b.ZIP_PAGE_SIZE, b.PAGE_SIZE)
               AS page_size,
              ROUND((@page_size * c.CLUST_INDEX_SIZE)
               /(1024*1024)) AS pk_mb,
              ROUND((@page_size * c.OTHER_INDEX_SIZE)
               /(1024*1024)) AS secidx_mb
            FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES a
            INNER JOIN INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES b on a.NAME = b.NAME
            INNER JOIN INFORMATION_SCHEMA.INNODB_SYS_TABLESTATS c on b.NAME = c.NAME
            WHERE a.NAME LIKE 'employees/%'
            ORDER BY a.NAME DESC;
     +------------------------+-------------+------------+-----------+-------+-----------+
     | NAME                   | FILE_FORMAT | ROW_FORMAT | page_size | pk_mb | secidx_mb |
     +------------------------+-------------+------------+-----------+-------+-----------+
     | employees/titles       | Antelope    | Compact    |     16384 |    20 |        11 |
     | employees/salaries     | Antelope    | Compact    |     16384 |    91 |        33 |
     | employees/employees    | Antelope    | Compact    |     16384 |    15 |         0 |
     | employees/dept_manager | Antelope    | Compact    |     16384 |     0 |         0 |
     | employees/dept_emp     | Antelope    | Compact    |     16384 |    12 |        10 |
     | employees/departments  | Antelope    | Compact    |     16384 |     0 |         0 |
     +------------------------+-------------+------------+-----------+-------+-----------+

14.15.4 InnoDB INFORMATION_SCHEMA FULLTEXT Index Tables
-------------------------------------------------------

With the introduction of 'FULLTEXT' index support for 'InnoDB' tables in
MySQL 5.6.4, the following tables were added to the 'INFORMATION_SCHEMA'
database:

     mysql> SHOW TABLES FROM INFORMATION_SCHEMA LIKE 'INNODB_FT%';
     +-------------------------------------------+
     | Tables_in_INFORMATION_SCHEMA (INNODB_FT%) |
     +-------------------------------------------+
     | INNODB_FT_CONFIG                          |
     | INNODB_FT_BEING_DELETED                   |
     | INNODB_FT_DELETED                         |
     | INNODB_FT_DEFAULT_STOPWORD                |
     | INNODB_FT_INDEX_TABLE                     |
     | INNODB_FT_INDEX_CACHE                     |
     +-------------------------------------------+

*Table Overview*

   * 'INNODB_FT_CONFIG'.: Displays
     metadata about the 'FULLTEXT' index and associated processing for
     an 'InnoDB' table.

   * 'INNODB_FT_BEING_DELETED'.:
     Provides a snapshot of the 'INNODB_FT_DELETED'
     table that is only used during an
     'OPTIMIZE TABLE' maintenance operation.  When
     'OPTIMIZE TABLE' is run, the
     'INNODB_FT_BEING_DELETED' table is
     emptied, and DOC_IDs are removed from the
     'INNODB_FT_DELETED' table.  Because the
     contents of 'INNODB_FT_BEING_DELETED'
     typically have a short lifetime,
     this table has limited utility for monitoring or debugging.  For
     information about running 'OPTIMIZE TABLE'.
     on tables with 'FULLTEXT' indexes, see
     fulltext-fine-tuning.

   * 'INNODB_FT_DELETED'.: Records rows
     that are deleted from the 'FULLTEXT' index for an 'InnoDB' table.
     To avoid expensive index reorganization during DML operations for
     an 'InnoDB' 'FULLTEXT' index, the information about newly deleted
     words is stored separately, filtered out of search results when you
     perform a text search, and removed from the main search index only
     when you run 'OPTIMIZE TABLE'.

   * 'INNODB_FT_DEFAULT_STOPWORD'.:
     Holds a list of stopwords that
     are used by default when creating a 'FULLTEXT' index.

     For information about the 'INNODB_FT_DEFAULT_STOPWORD'
     table, see
     fulltext-stopwords.

   * 'INNODB_FT_INDEX_TABLE'.:
     Contains data about the inverted index used to process text
     searches against the 'FULLTEXT' index.

   * 'INNODB_FT_INDEX_CACHE'.:
     Contains token information about newly inserted rows in a
     'FULLTEXT' index.  To avoid expensive index reorganization during
     DML operations, the information about newly indexed words is stored
     separately, and combined with the main search index only when
     'OPTIMIZE TABLE' is run, when the server is shut
     down, or when the cache size exceeds a limit defined by
     'innodb_ft_cache_size' or 'innodb_ft_total_cache_size'.

*Note*:

With the exception of the 'INNODB_FT_DEFAULT_STOPWORD'
table, you must set the
'innodb_ft_aux_table' configuration variable to the name of the table
(DATABASE_NAME/TABLE_NAME) that contains the 'FULLTEXT' index.
Otherwise, the 'InnoDB' 'FULLTEXT' index 'INFORMATION_SCHEMA' tables
appear empty.

This example uses a table with a 'FULLTEXT' index to demonstrate the
data contained in the 'FULLTEXT' index 'INFORMATION_SCHEMA' tables.

  1. Create a table with a 'FULLTEXT' index and insert some data:

          mysql> CREATE TABLE articles (
                 id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
                 title VARCHAR(200),
                 body TEXT,
                 FULLTEXT (title,body)
                 ) ENGINE=InnoDB;

          mysql> INSERT INTO articles (title,body) VALUES
                 ('MySQL Tutorial','DBMS stands for DataBase ...'),
                 ('How To Use MySQL Well','After you went through a ...'),
                 ('Optimizing MySQL','In this tutorial we will show ...'),
                 ('1001 MySQL Tricks','1. Never run mysqld as root. 2. ...'),
                 ('MySQL vs. YourSQL','In the following database comparison ...'),
                 ('MySQL Security','When configured properly, MySQL ...');

  2. Set the 'innodb_ft_aux_table' variable to the name of the table
     with the 'FULLTEXT' index.  If this variable is not set, the
     'InnoDB' 'FULLTEXT' 'INFORMATION_SCHEMA' tables appear empty, with
     the exception of the 'INNODB_FT_DEFAULT_STOPWORD'
     table.

          SET GLOBAL innodb_ft_aux_table = 'test/articles';

  3. Query the 'INNODB_FT_INDEX_CACHE'
     table, which shows information about
     newly inserted rows in a 'FULLTEXT' index.  To avoid expensive
     index reorganization during DML operations, data for newly inserted
     rows remains in the 'FULLTEXT' index cache until 'OPTIMIZE TABLE'
     is run (or until the server is shutdown or
     cache limits are exceeded).

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_INDEX_CACHE LIMIT 5;
          +------------+--------------+-------------+-----------+--------+----------+
          | WORD       | FIRST_DOC_ID | LAST_DOC_ID | DOC_COUNT | DOC_ID | POSITION |
          +------------+--------------+-------------+-----------+--------+----------+
          | 1001       |            5 |           5 |         1 |      5 |        0 |
          | after      |            3 |           3 |         1 |      3 |       22 |
          | comparison |            6 |           6 |         1 |      6 |       44 |
          | configured |            7 |           7 |         1 |      7 |       20 |
          | database   |            2 |           6 |         2 |      2 |       31 |
          +------------+--------------+-------------+-----------+--------+----------+

  4. Enable 'innodb_optimize_fulltext_only' and run 'OPTIMIZE TABLE'
     on the table that contains the 'FULLTEXT'
     index.  This operation flushes the contents of the 'FULLTEXT' index
     cache to the main 'FULLTEXT' index.
     'innodb_optimize_fulltext_only' changes the way the 'OPTIMIZE TABLE'
     statement operates on 'InnoDB' tables, and
     is intended to be enabled temporarily, during maintenance
     operations on 'InnoDB' tables with 'FULLTEXT' indexes.

          mysql> SET GLOBAL innodb_optimize_fulltext_only=ON;
          Query OK, 0 rows affected (0.00 sec)

          mysql> OPTIMIZE TABLE articles;
          +---------------+----------+----------+----------+
          | Table         | Op       | Msg_type | Msg_text |
          +---------------+----------+----------+----------+
          | test.articles | optimize | status   | OK       |
          +---------------+----------+----------+----------+

  5. Query the 'INNODB_FT_INDEX_TABLE'
     table to view information about data
     in the main 'FULLTEXT' index, including information about the data
     that was just flushed from the 'FULLTEXT' index cache.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_INDEX_TABLE LIMIT 5;
          +------------+--------------+-------------+-----------+--------+----------+
          | WORD       | FIRST_DOC_ID | LAST_DOC_ID | DOC_COUNT | DOC_ID | POSITION |
          +------------+--------------+-------------+-----------+--------+----------+
          | 1001       |            5 |           5 |         1 |      5 |        0 |
          | after      |            3 |           3 |         1 |      3 |       22 |
          | comparison |            6 |           6 |         1 |      6 |       44 |
          | configured |            7 |           7 |         1 |      7 |       20 |
          | database   |            2 |           6 |         2 |      2 |       31 |
          +------------+--------------+-------------+-----------+--------+----------+

     The 'INNODB_FT_INDEX_CACHE'.
     table is now empty since the 'OPTIMIZE TABLE'
     operation flushed the 'FULLTEXT' index cache.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_INDEX_CACHE LIMIT 5;
          Empty set (0.00 sec)

  6. Delete some records from the 'test/articles' table.

          mysql> DELETE FROM test.articles WHERE id < 4;
          Query OK, 3 rows affected (0.11 sec)

  7. Query the 'INNODB_FT_DELETED'.
     table.  This table records rows that are deleted from the
     'FULLTEXT' index.  To avoid expensive index reorganization during
     DML operations, information about newly deleted records is stored
     separately, filtered out of search results when you do a text
     search, and removed from the main search index when you run
     'OPTIMIZE TABLE'.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_DELETED;
          +--------+
          | DOC_ID |
          +--------+
          |      2 |
          |      3 |
          |      4 |
          +--------+

  8. Run 'OPTIMIZE TABLE' to remove the deleted
     records.

          mysql> OPTIMIZE TABLE articles;
          +---------------+----------+----------+----------+
          | Table         | Op       | Msg_type | Msg_text |
          +---------------+----------+----------+----------+
          | test.articles | optimize | status   | OK       |
          +---------------+----------+----------+----------+

     The 'INNODB_FT_DELETED' table
     should now appear empty.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_DELETED;
          Empty set (0.00 sec)

  9. Query the 'INNODB_FT_CONFIG' table.
     This table contains metadata about the 'FULLTEXT' index and related
     processing:

        * 'optimize_checkpoint_limit' is the number of seconds after
          which an 'OPTIMIZE TABLE' run stops.

        * 'synced_doc_id' is the next 'DOC_ID' to be issued.

        * 'stopword_table_name' is the DATABASE/TABLE name for a
          user-defined stopword table.  This field appears empty if
          there is no user-defined stopword table.

        * 'use_stopword' indicates whether or not a stopword table is
          used, which is defined when the 'FULLTEXT' index is created.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_CONFIG;
          +---------------------------+-------+
          | KEY                       | VALUE |
          +---------------------------+-------+
          | optimize_checkpoint_limit | 180   |
          | synced_doc_id             | 8     |
          | stopword_table_name       |       |
          | use_stopword              | 1     |
          +---------------------------+-------+

14.15.5 InnoDB INFORMATION_SCHEMA Buffer Pool Tables
----------------------------------------------------

The 'InnoDB' 'INFORMATION_SCHEMA' buffer pool tables provide buffer pool
status information and metadata about the pages within the 'InnoDB'
buffer pool.  The tables were introduced in MySQL 5.6.2 and later
backported to MySQL 5.5 (in MySQL 5.5.28) and MySQL 5.1 (in MySQL
5.1.66).

The 'InnoDB' 'INFORMATION_SCHEMA' buffer pool tables include those
listed below:

     mysql> SHOW TABLES FROM INFORMATION_SCHEMA LIKE 'INNODB_BUFFER%';
     +-----------------------------------------------+
     | Tables_in_INFORMATION_SCHEMA (INNODB_BUFFER%) |
     +-----------------------------------------------+
     | INNODB_BUFFER_PAGE_LRU                        |
     | INNODB_BUFFER_PAGE                            |
     | INNODB_BUFFER_POOL_STATS                      |
     +-----------------------------------------------+

*Table Overview*

   * 'INNODB_BUFFER_PAGE'.: Holds
     information about each page in the 'InnoDB' buffer pool.

   * 'INNODB_BUFFER_PAGE_LRU'.:
     Holds information about the pages in the 'InnoDB' buffer pool, in
     particular how they are ordered in the LRU list that determines
     which pages to evict from the buffer pool when it becomes full.
     The 'INNODB_BUFFER_PAGE_LRU'.
     table has the same columns as the 'INNODB_BUFFER_PAGE'
     table, except that the
     'INNODB_BUFFER_PAGE_LRU' table has
     an 'LRU_POSITION' column instead of a 'BLOCK_ID' column.

   * 'INNODB_BUFFER_POOL_STATS'.:
     Provides buffer pool status information.  Much of the same
     information is provided by 'SHOW ENGINE INNODB STATUS'
     output, or may be obtained using 'InnoDB' buffer pool
     server status variables.

*Warning*:

Querying the 'INNODB_BUFFER_PAGE' table
or 'INNODB_BUFFER_PAGE_LRU' table
can introduce significant performance overhead.  Do not query these
tables on a production system unless you are aware of the performance
impact that your query may have, and have determined it to be
acceptable.  To avoid impacting performance, reproduce the issue you
want to investigate on a test instance and run your queries on the test
instance.

This query provides an approximate count of pages that contain system
data by excluding pages where the 'TABLE_NAME' value is either 'NULL' or
includes a slash '/' or period '.' in the table name, which indicates a
user-defined table.

     mysql> SELECT COUNT(*) FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE TABLE_NAME IS NULL OR (INSTR(TABLE_NAME, '/') = 0 AND INSTR(TABLE_NAME, '.') = 0);
     +----------+
     | COUNT(*) |
     +----------+
     |     1516 |
     +----------+

This query returns the approximate number of pages that contain system
data, the total number of buffer pool pages, and an approximate
percentage of pages that contain system data.

     mysql> SELECT
            (SELECT COUNT(*) FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE TABLE_NAME IS NULL OR (INSTR(TABLE_NAME, '/') = 0 AND INSTR(TABLE_NAME, '.') = 0)
            ) AS system_pages,
            (
            SELECT COUNT(*)
            FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            ) AS total_pages,
            (
            SELECT ROUND((system_pages/total_pages) * 100)
            ) AS system_page_percentage;
     +--------------+-------------+------------------------+
     | system_pages | total_pages | system_page_percentage |
     +--------------+-------------+------------------------+
     |          295 |        8192 |                      4 |
     +--------------+-------------+------------------------+

The type of system data in the buffer pool can be determined by querying
the 'PAGE_TYPE' value.  For example, the following query returns eight
distinct 'PAGE_TYPE' values among the pages that contain system data:

     mysql> SELECT DISTINCT PAGE_TYPE FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE TABLE_NAME IS NULL OR (INSTR(TABLE_NAME, '/') = 0 AND INSTR(TABLE_NAME, '.') = 0);
     +-------------------+
     | PAGE_TYPE         |
     +-------------------+
     | SYSTEM            |
     | IBUF_BITMAP       |
     | UNKNOWN           |
     | FILE_SPACE_HEADER |
     | INODE             |
     | UNDO_LOG          |
     | ALLOCATED         |
     +-------------------+

This query provides an approximate count of pages containing user data
by counting pages where the 'TABLE_NAME' value is 'NOT NULL' and 'NOT
LIKE '%INNODB_SYS_TABLES%''.

     mysql> SELECT COUNT(*) FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE TABLE_NAME IS NOT NULL AND TABLE_NAME NOT LIKE '%INNODB_SYS_TABLES%';
     +----------+
     | COUNT(*) |
     +----------+
     |     7897 |
     +----------+

This query returns the approximate number of pages that contain user
data, the total number of buffer pool pages, and an approximate
percentage of pages that contain user data.

     mysql> SELECT
            (SELECT COUNT(*) FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE TABLE_NAME IS NOT NULL AND (INSTR(TABLE_NAME, '/') > 0 OR INSTR(TABLE_NAME, '.') > 0)
            ) AS user_pages,
            (
            SELECT COUNT(*)
            FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            ) AS total_pages,
            (
            SELECT ROUND((user_pages/total_pages) * 100)
            ) AS user_page_percentage;
     +------------+-------------+----------------------+
     | user_pages | total_pages | user_page_percentage |
     +------------+-------------+----------------------+
     |       7897 |        8192 |                   96 |
     +------------+-------------+----------------------+

This query identifies user-defined tables with pages in the buffer pool:

     mysql> SELECT DISTINCT TABLE_NAME FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE TABLE_NAME IS NOT NULL AND (INSTR(TABLE_NAME, '/') > 0 OR INSTR(TABLE_NAME, '.') > 0)
            AND TABLE_NAME NOT LIKE '`mysql`.`innodb_%';
     +-------------------------+
     | TABLE_NAME              |
     +-------------------------+
     | `employees`.`salaries`  |
     | `employees`.`employees` |
     +-------------------------+

For information about index pages, query the 'INDEX_NAME' column using
the name of the index.  For example, the following query returns the
number of pages and total data size of pages for the 'emp_no' index that
is defined on the 'employees.salaries' table:

     mysql> SELECT INDEX_NAME, COUNT(*) AS Pages,
            ROUND(SUM(IF(COMPRESSED_SIZE = 0, @@global.innodb_page_size, COMPRESSED_SIZE))/1024/1024)
            AS 'Total Data (MB)'
            FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE INDEX_NAME='emp_no' AND TABLE_NAME = '`employees`.`salaries`';
     +------------+-------+-----------------+
     | INDEX_NAME | Pages | Total Data (MB) |
     +------------+-------+-----------------+
     | emp_no     |  1609 |              25 |
     +------------+-------+-----------------+

This query returns the number of pages and total data size of pages for
all indexes defined on the 'employees.salaries' table:

     mysql> SELECT INDEX_NAME, COUNT(*) AS Pages,
            ROUND(SUM(IF(COMPRESSED_SIZE = 0, @@global.innodb_page_size, COMPRESSED_SIZE))/1024/1024)
            AS 'Total Data (MB)'
            FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE
            WHERE TABLE_NAME = '`employees`.`salaries`'
            GROUP BY INDEX_NAME;
     +------------+-------+-----------------+
     | INDEX_NAME | Pages | Total Data (MB) |
     +------------+-------+-----------------+
     | emp_no     |  1608 |              25 |
     | PRIMARY    |  6086 |              95 |
     +------------+-------+-----------------+

The 'INNODB_BUFFER_PAGE_LRU' table
holds information about the pages in the 'InnoDB' buffer pool, in
particular how they are ordered that determines which pages to evict
from the buffer pool when it becomes full.  The definition for this page
is the same as for 'INNODB_BUFFER_PAGE',
except this table has an 'LRU_POSITION' column instead of a 'BLOCK_ID'
column.

This query counts the number of positions at a specific location in the
LRU list occupied by pages of the 'employees.employees' table.

     mysql> SELECT COUNT(LRU_POSITION) FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE_LRU
            WHERE TABLE_NAME='`employees`.`employees`' AND LRU_POSITION < 3072;
     +---------------------+
     | COUNT(LRU_POSITION) |
     +---------------------+
     |                 548 |
     +---------------------+

The 'INNODB_BUFFER_POOL_STATS'.
table provides information similar to 'SHOW ENGINE INNODB STATUS'
and 'InnoDB' buffer pool status variables.

     mysql> SELECT * FROM information_schema.INNODB_BUFFER_POOL_STATS \G
     *************************** 1. row ***************************
                              POOL_ID: 0
                            POOL_SIZE: 8192
                         FREE_BUFFERS: 1
                       DATABASE_PAGES: 8173
                   OLD_DATABASE_PAGES: 3014
              MODIFIED_DATABASE_PAGES: 0
                   PENDING_DECOMPRESS: 0
                        PENDING_READS: 0
                    PENDING_FLUSH_LRU: 0
                   PENDING_FLUSH_LIST: 0
                     PAGES_MADE_YOUNG: 15907
                 PAGES_NOT_MADE_YOUNG: 3803101
                PAGES_MADE_YOUNG_RATE: 0
            PAGES_MADE_NOT_YOUNG_RATE: 0
                    NUMBER_PAGES_READ: 3270
                 NUMBER_PAGES_CREATED: 13176
                 NUMBER_PAGES_WRITTEN: 15109
                      PAGES_READ_RATE: 0
                    PAGES_CREATE_RATE: 0
                   PAGES_WRITTEN_RATE: 0
                     NUMBER_PAGES_GET: 33069332
                             HIT_RATE: 0
         YOUNG_MAKE_PER_THOUSAND_GETS: 0
     NOT_YOUNG_MAKE_PER_THOUSAND_GETS: 0
              NUMBER_PAGES_READ_AHEAD: 2713
            NUMBER_READ_AHEAD_EVICTED: 0
                      READ_AHEAD_RATE: 0
              READ_AHEAD_EVICTED_RATE: 0
                         LRU_IO_TOTAL: 0
                       LRU_IO_CURRENT: 0
                     UNCOMPRESS_TOTAL: 0
                   UNCOMPRESS_CURRENT: 0

For comparison, see 'SHOW ENGINE INNODB STATUS' output
and 'InnoDB' buffer pool status variable output is shown below, based on
the same data set.

For more information about 'SHOW ENGINE INNODB STATUS'
output, see innodb-standard-monitor.

     mysql> SHOW ENGINE INNODB STATUS \G
     ...
     ----------------------
     BUFFER POOL AND MEMORY
     ----------------------
     Total large memory allocated 137428992
     Dictionary memory allocated 579084
     Buffer pool size   8192
     Free buffers       1
     Database pages     8173
     Old database pages 3014
     Modified db pages  0
     Pending reads 0
     Pending writes: LRU 0, flush list 0, single page 0
     Pages made young 15907, not young 3803101
     0.00 youngs/s, 0.00 non-youngs/s
     Pages read 3270, created 13176, written 15109
     0.00 reads/s, 0.00 creates/s, 0.00 writes/s
     No buffer pool page gets since the last printout
     Pages read ahead 0.00/s, evicted without access 0.00/s, Random read ahead 0.00/s
     LRU len: 8173, unzip_LRU len: 0
     I/O sum[0]:cur[0], unzip sum[0]:cur[0]
     ...

For status variable descriptions, see server-status-variables.

     mysql> SHOW STATUS LIKE 'Innodb_buffer%';
     +---------------------------------------+-------------+
     | Variable_name                         | Value       |
     +---------------------------------------+-------------+
     | Innodb_buffer_pool_dump_status        | not started |
     | Innodb_buffer_pool_load_status        | not started |
     | Innodb_buffer_pool_resize_status      | not started |
     | Innodb_buffer_pool_pages_data         | 8173        |
     | Innodb_buffer_pool_bytes_data         | 133906432   |
     | Innodb_buffer_pool_pages_dirty        | 0           |
     | Innodb_buffer_pool_bytes_dirty        | 0           |
     | Innodb_buffer_pool_pages_flushed      | 15109       |
     | Innodb_buffer_pool_pages_free         | 1           |
     | Innodb_buffer_pool_pages_misc         | 18          |
     | Innodb_buffer_pool_pages_total        | 8192        |
     | Innodb_buffer_pool_read_ahead_rnd     | 0           |
     | Innodb_buffer_pool_read_ahead         | 2713        |
     | Innodb_buffer_pool_read_ahead_evicted | 0           |
     | Innodb_buffer_pool_read_requests      | 33069332    |
     | Innodb_buffer_pool_reads              | 558         |
     | Innodb_buffer_pool_wait_free          | 0           |
     | Innodb_buffer_pool_write_requests     | 11985961    |
     +---------------------------------------+-------------+

14.15.6 InnoDB INFORMATION_SCHEMA Metrics Table
-----------------------------------------------

The 'INNODB_METRICS' table, introduced in
MySQL 5.6.2, consolidates all 'InnoDB' performance and resource-related
counters into a single 'INFORMATION_SCHEMA' table.

The columns of the 'INNODB_METRICS' table
are shown in the following example.  For a description of each column,
see innodb-metrics-table.

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts" \G
     *************************** 1. row ***************************
                NAME: dml_inserts
           SUBSYSTEM: dml
               COUNT: 46273
           MAX_COUNT: 46273
           MIN_COUNT: NULL
           AVG_COUNT: 492.2659574468085
         COUNT_RESET: 46273
     MAX_COUNT_RESET: 46273
     MIN_COUNT_RESET: NULL
     AVG_COUNT_RESET: NULL
        TIME_ENABLED: 2014-11-28 16:07:53
       TIME_DISABLED: NULL
        TIME_ELAPSED: 94
          TIME_RESET: NULL
              STATUS: enabled
                TYPE: status_counter
             COMMENT: Number of rows inserted

*Enabling, Disabling, and Resetting Counters*

You can enable, disable, and reset counters using the following
configuration options:

   * 'innodb_monitor_enable': Enables one or more counters.

          SET GLOBAL innodb_monitor_enable = [counter-name|module_name|pattern|all];

   * 'innodb_monitor_disable': Disables one or more counters.

          SET GLOBAL innodb_monitor_disable = [counter-name|module_name|pattern|all];

   * 'innodb_monitor_reset': Resets the count value for one or more
     counters to zero.

          SET GLOBAL innodb_monitor_reset = [counter-name|module_name|pattern|all];

   * 'innodb_monitor_reset_all': Resets all values for one or more
     counters.  A counter must be disabled before using
     'innodb_monitor_reset_all'.

          SET GLOBAL innodb_monitor_reset_all = [counter-name|module_name|pattern|all];

You can also enable counters and counter modules at startup using the
MySQL server configuration file.  For example, to enable the 'log'
module, 'metadata_table_handles_opened' and
'metadata_table_handles_closed' counters, enter the following line in
the '[mysqld]' section of your 'my.cnf' configuration file.

     [mysqld]
     innodb_monitor_enable = module_recovery,metadata_table_handles_opened,metadata_table_handles_closed

When enabling multiple counters or modules in your configuration file,
you must specify the 'innodb_monitor_enable' configuration option
followed by counter and module names separated by a comma, as shown in
the example above.  Only the 'innodb_monitor_enable' option can be used
in your configuration file.  The disable and reset configuration options
are only supported on the command line.

*Note*:

Because each counter imposes some degree of runtime overhead on the
server, typically you enable more counters on test and development
servers during experimentation and benchmarking, and only enable
counters on production servers to diagnose known issues or monitor
aspects that are likely to be bottlenecks for a particular server and
workload.

*Counters*

The counters represented in the 'INNODB_METRICS'
table are subject to change, so for the most
up-to-date list, query a running MySQL server.

Counters that are enabled by default correspond to those used by
'SHOW ENGINE INNODB STATUS'.  Counters used by 'SHOW ENGINE INNODB STATUS'
are always 'on' at a system level
but you can disable these counters for the 'INNODB_METRICS'
table, as required.  Also, counter status is not
persistent.  Unless specified otherwise, counters revert to their
default enabled or disabled status when the server is restarted.

If you run programs that would be affected by additions or changes to
the 'INNODB_METRICS' table, it is
recommended that you review releases notes and query the
'INNODB_METRICS' table for the new release prior
to upgrading.

     mysql> SELECT name, subsystem, status FROM INFORMATION_SCHEMA.INNODB_METRICS ORDER BY NAME;
     +------------------------------------------+---------------------+----------+
     | name                                     | subsystem           | status   |
     +------------------------------------------+---------------------+----------+
     | adaptive_hash_pages_added                | adaptive_hash_index | disabled |
     | adaptive_hash_pages_removed              | adaptive_hash_index | disabled |
     | adaptive_hash_rows_added                 | adaptive_hash_index | disabled |
     | adaptive_hash_rows_deleted_no_hash_entry | adaptive_hash_index | disabled |
     | adaptive_hash_rows_removed               | adaptive_hash_index | disabled |
     | adaptive_hash_rows_updated               | adaptive_hash_index | disabled |
     | adaptive_hash_searches                   | adaptive_hash_index | enabled  |
     | adaptive_hash_searches_btree             | adaptive_hash_index | enabled  |
     | buffer_data_reads                        | buffer              | enabled  |
     | buffer_data_written                      | buffer              | enabled  |
     | buffer_flush_adaptive                    | buffer              | disabled |
     | buffer_flush_adaptive_avg_pass           | buffer              | disabled |
     | buffer_flush_adaptive_avg_time_est       | buffer              | disabled |
     | buffer_flush_adaptive_avg_time_slot      | buffer              | disabled |
     | buffer_flush_adaptive_avg_time_thread    | buffer              | disabled |
     | buffer_flush_adaptive_pages              | buffer              | disabled |
     | buffer_flush_adaptive_total_pages        | buffer              | disabled |
     | buffer_flush_avg_page_rate               | buffer              | disabled |
     | buffer_flush_avg_pass                    | buffer              | disabled |
     | buffer_flush_avg_time                    | buffer              | disabled |
     | buffer_flush_background                  | buffer              | disabled |
     | buffer_flush_background_pages            | buffer              | disabled |
     | buffer_flush_background_total_pages      | buffer              | disabled |
     | buffer_flush_batches                     | buffer              | disabled |
     | buffer_flush_batch_num_scan              | buffer              | disabled |
     | buffer_flush_batch_pages                 | buffer              | disabled |
     | buffer_flush_batch_scanned               | buffer              | disabled |
     | buffer_flush_batch_scanned_per_call      | buffer              | disabled |
     | buffer_flush_batch_total_pages           | buffer              | disabled |
     | buffer_flush_lsn_avg_rate                | buffer              | disabled |
     | buffer_flush_neighbor                    | buffer              | disabled |
     | buffer_flush_neighbor_pages              | buffer              | disabled |
     | buffer_flush_neighbor_total_pages        | buffer              | disabled |
     | buffer_flush_n_to_flush_by_age           | buffer              | disabled |
     | buffer_flush_n_to_flush_requested        | buffer              | disabled |
     | buffer_flush_pct_for_dirty               | buffer              | disabled |
     | buffer_flush_pct_for_lsn                 | buffer              | disabled |
     | buffer_flush_sync                        | buffer              | disabled |
     | buffer_flush_sync_pages                  | buffer              | disabled |
     | buffer_flush_sync_total_pages            | buffer              | disabled |
     | buffer_flush_sync_waits                  | buffer              | disabled |
     | buffer_LRU_batches_evict                 | buffer              | disabled |
     | buffer_LRU_batches_flush                 | buffer              | disabled |
     | buffer_LRU_batch_evict_pages             | buffer              | disabled |
     | buffer_LRU_batch_evict_total_pages       | buffer              | disabled |
     | buffer_LRU_batch_flush_avg_pass          | buffer              | disabled |
     | buffer_LRU_batch_flush_avg_time_est      | buffer              | disabled |
     | buffer_LRU_batch_flush_avg_time_slot     | buffer              | disabled |
     | buffer_LRU_batch_flush_avg_time_thread   | buffer              | disabled |
     | buffer_LRU_batch_flush_pages             | buffer              | disabled |
     | buffer_LRU_batch_flush_total_pages       | buffer              | disabled |
     | buffer_LRU_batch_num_scan                | buffer              | disabled |
     | buffer_LRU_batch_scanned                 | buffer              | disabled |
     | buffer_LRU_batch_scanned_per_call        | buffer              | disabled |
     | buffer_LRU_get_free_loops                | buffer              | disabled |
     | buffer_LRU_get_free_search               | Buffer              | disabled |
     | buffer_LRU_get_free_waits                | buffer              | disabled |
     | buffer_LRU_search_num_scan               | buffer              | disabled |
     | buffer_LRU_search_scanned                | buffer              | disabled |
     | buffer_LRU_search_scanned_per_call       | buffer              | disabled |
     | buffer_LRU_single_flush_failure_count    | Buffer              | disabled |
     | buffer_LRU_single_flush_num_scan         | buffer              | disabled |
     | buffer_LRU_single_flush_scanned          | buffer              | disabled |
     | buffer_LRU_single_flush_scanned_per_call | buffer              | disabled |
     | buffer_LRU_unzip_search_num_scan         | buffer              | disabled |
     | buffer_LRU_unzip_search_scanned          | buffer              | disabled |
     | buffer_LRU_unzip_search_scanned_per_call | buffer              | disabled |
     | buffer_pages_created                     | buffer              | enabled  |
     | buffer_pages_read                        | buffer              | enabled  |
     | buffer_pages_written                     | buffer              | enabled  |
     | buffer_page_read_blob                    | buffer_page_io      | disabled |
     | buffer_page_read_fsp_hdr                 | buffer_page_io      | disabled |
     | buffer_page_read_ibuf_bitmap             | buffer_page_io      | disabled |
     | buffer_page_read_ibuf_free_list          | buffer_page_io      | disabled |
     | buffer_page_read_index_ibuf_leaf         | buffer_page_io      | disabled |
     | buffer_page_read_index_ibuf_non_leaf     | buffer_page_io      | disabled |
     | buffer_page_read_index_inode             | buffer_page_io      | disabled |
     | buffer_page_read_index_leaf              | buffer_page_io      | disabled |
     | buffer_page_read_index_non_leaf          | buffer_page_io      | disabled |
     | buffer_page_read_other                   | buffer_page_io      | disabled |
     | buffer_page_read_system_page             | buffer_page_io      | disabled |
     | buffer_page_read_trx_system              | buffer_page_io      | disabled |
     | buffer_page_read_undo_log                | buffer_page_io      | disabled |
     | buffer_page_read_xdes                    | buffer_page_io      | disabled |
     | buffer_page_read_zblob                   | buffer_page_io      | disabled |
     | buffer_page_read_zblob2                  | buffer_page_io      | disabled |
     | buffer_page_written_blob                 | buffer_page_io      | disabled |
     | buffer_page_written_fsp_hdr              | buffer_page_io      | disabled |
     | buffer_page_written_ibuf_bitmap          | buffer_page_io      | disabled |
     | buffer_page_written_ibuf_free_list       | buffer_page_io      | disabled |
     | buffer_page_written_index_ibuf_leaf      | buffer_page_io      | disabled |
     | buffer_page_written_index_ibuf_non_leaf  | buffer_page_io      | disabled |
     | buffer_page_written_index_inode          | buffer_page_io      | disabled |
     | buffer_page_written_index_leaf           | buffer_page_io      | disabled |
     | buffer_page_written_index_non_leaf       | buffer_page_io      | disabled |
     | buffer_page_written_other                | buffer_page_io      | disabled |
     | buffer_page_written_system_page          | buffer_page_io      | disabled |
     | buffer_page_written_trx_system           | buffer_page_io      | disabled |
     | buffer_page_written_undo_log             | buffer_page_io      | disabled |
     | buffer_page_written_xdes                 | buffer_page_io      | disabled |
     | buffer_page_written_zblob                | buffer_page_io      | disabled |
     | buffer_page_written_zblob2               | buffer_page_io      | disabled |
     | buffer_pool_bytes_data                   | buffer              | enabled  |
     | buffer_pool_bytes_dirty                  | buffer              | enabled  |
     | buffer_pool_pages_data                   | buffer              | enabled  |
     | buffer_pool_pages_dirty                  | buffer              | enabled  |
     | buffer_pool_pages_free                   | buffer              | enabled  |
     | buffer_pool_pages_misc                   | buffer              | enabled  |
     | buffer_pool_pages_total                  | buffer              | enabled  |
     | buffer_pool_reads                        | buffer              | enabled  |
     | buffer_pool_read_ahead                   | buffer              | enabled  |
     | buffer_pool_read_ahead_evicted           | buffer              | enabled  |
     | buffer_pool_read_requests                | buffer              | enabled  |
     | buffer_pool_size                         | server              | enabled  |
     | buffer_pool_wait_free                    | buffer              | enabled  |
     | buffer_pool_write_requests               | buffer              | enabled  |
     | compression_pad_decrements               | compression         | disabled |
     | compression_pad_increments               | compression         | disabled |
     | compress_pages_compressed                | compression         | disabled |
     | compress_pages_decompressed              | compression         | disabled |
     | ddl_background_drop_indexes              | ddl                 | disabled |
     | ddl_background_drop_tables               | ddl                 | disabled |
     | ddl_log_file_alter_table                 | ddl                 | disabled |
     | ddl_online_create_index                  | ddl                 | disabled |
     | ddl_pending_alter_table                  | ddl                 | disabled |
     | ddl_sort_file_alter_table                | ddl                 | disabled |
     | dml_deletes                              | dml                 | enabled  |
     | dml_inserts                              | dml                 | enabled  |
     | dml_reads                                | dml                 | disabled |
     | dml_updates                              | dml                 | enabled  |
     | file_num_open_files                      | file_system         | enabled  |
     | ibuf_merges                              | change_buffer       | enabled  |
     | ibuf_merges_delete                       | change_buffer       | enabled  |
     | ibuf_merges_delete_mark                  | change_buffer       | enabled  |
     | ibuf_merges_discard_delete               | change_buffer       | enabled  |
     | ibuf_merges_discard_delete_mark          | change_buffer       | enabled  |
     | ibuf_merges_discard_insert               | change_buffer       | enabled  |
     | ibuf_merges_insert                       | change_buffer       | enabled  |
     | ibuf_size                                | change_buffer       | enabled  |
     | icp_attempts                             | icp                 | disabled |
     | icp_match                                | icp                 | disabled |
     | icp_no_match                             | icp                 | disabled |
     | icp_out_of_range                         | icp                 | disabled |
     | index_page_discards                      | index               | disabled |
     | index_page_merge_attempts                | index               | disabled |
     | index_page_merge_successful              | index               | disabled |
     | index_page_reorg_attempts                | index               | disabled |
     | index_page_reorg_successful              | index               | disabled |
     | index_page_splits                        | index               | disabled |
     | innodb_activity_count                    | server              | enabled  |
     | innodb_background_drop_table_usec        | server              | disabled |
     | innodb_checkpoint_usec                   | server              | disabled |
     | innodb_dblwr_pages_written               | server              | enabled  |
     | innodb_dblwr_writes                      | server              | enabled  |
     | innodb_dict_lru_count                    | server              | disabled |
     | innodb_dict_lru_usec                     | server              | disabled |
     | innodb_ibuf_merge_usec                   | server              | disabled |
     | innodb_log_flush_usec                    | server              | disabled |
     | innodb_master_active_loops               | server              | disabled |
     | innodb_master_idle_loops                 | server              | disabled |
     | innodb_master_purge_usec                 | server              | disabled |
     | innodb_master_thread_sleeps              | server              | disabled |
     | innodb_mem_validate_usec                 | server              | disabled |
     | innodb_page_size                         | server              | enabled  |
     | innodb_rwlock_sx_os_waits                | server              | enabled  |
     | innodb_rwlock_sx_spin_rounds             | server              | enabled  |
     | innodb_rwlock_sx_spin_waits              | server              | enabled  |
     | innodb_rwlock_s_os_waits                 | server              | enabled  |
     | innodb_rwlock_s_spin_rounds              | server              | enabled  |
     | innodb_rwlock_s_spin_waits               | server              | enabled  |
     | innodb_rwlock_x_os_waits                 | server              | enabled  |
     | innodb_rwlock_x_spin_rounds              | server              | enabled  |
     | innodb_rwlock_x_spin_waits               | server              | enabled  |
     | lock_deadlocks                           | lock                | enabled  |
     | lock_rec_locks                           | lock                | disabled |
     | lock_rec_lock_created                    | lock                | disabled |
     | lock_rec_lock_removed                    | lock                | disabled |
     | lock_rec_lock_requests                   | lock                | disabled |
     | lock_rec_lock_waits                      | lock                | disabled |
     | lock_row_lock_current_waits              | lock                | enabled  |
     | lock_row_lock_time                       | lock                | enabled  |
     | lock_row_lock_time_avg                   | lock                | enabled  |
     | lock_row_lock_time_max                   | lock                | enabled  |
     | lock_row_lock_waits                      | lock                | enabled  |
     | lock_table_locks                         | lock                | disabled |
     | lock_table_lock_created                  | lock                | disabled |
     | lock_table_lock_removed                  | lock                | disabled |
     | lock_table_lock_waits                    | lock                | disabled |
     | lock_timeouts                            | lock                | enabled  |
     | log_checkpoints                          | recovery            | disabled |
     | log_lsn_buf_pool_oldest                  | recovery            | disabled |
     | log_lsn_checkpoint_age                   | recovery            | disabled |
     | log_lsn_current                          | recovery            | disabled |
     | log_lsn_last_checkpoint                  | recovery            | disabled |
     | log_lsn_last_flush                       | recovery            | disabled |
     | log_max_modified_age_async               | recovery            | disabled |
     | log_max_modified_age_sync                | recovery            | disabled |
     | log_num_log_io                           | recovery            | disabled |
     | log_padded                               | recovery            | enabled  |
     | log_pending_checkpoint_writes            | recovery            | disabled |
     | log_pending_log_flushes                  | recovery            | disabled |
     | log_waits                                | recovery            | enabled  |
     | log_writes                               | recovery            | enabled  |
     | log_write_requests                       | recovery            | enabled  |
     | metadata_table_handles_closed            | metadata            | disabled |
     | metadata_table_handles_opened            | metadata            | disabled |
     | metadata_table_reference_count           | metadata            | disabled |
     | os_data_fsyncs                           | os                  | enabled  |
     | os_data_reads                            | os                  | enabled  |
     | os_data_writes                           | os                  | enabled  |
     | os_log_bytes_written                     | os                  | enabled  |
     | os_log_fsyncs                            | os                  | enabled  |
     | os_log_pending_fsyncs                    | os                  | enabled  |
     | os_log_pending_writes                    | os                  | enabled  |
     | os_pending_reads                         | os                  | disabled |
     | os_pending_writes                        | os                  | disabled |
     | purge_del_mark_records                   | purge               | disabled |
     | purge_dml_delay_usec                     | purge               | disabled |
     | purge_invoked                            | purge               | disabled |
     | purge_resume_count                       | purge               | disabled |
     | purge_stop_count                         | purge               | disabled |
     | purge_undo_log_pages                     | purge               | disabled |
     | purge_upd_exist_or_extern_records        | purge               | disabled |
     | trx_active_transactions                  | transaction         | disabled |
     | trx_commits_insert_update                | transaction         | disabled |
     | trx_nl_ro_commits                        | transaction         | disabled |
     | trx_rollbacks                            | transaction         | disabled |
     | trx_rollbacks_savepoint                  | transaction         | disabled |
     | trx_rollback_active                      | transaction         | disabled |
     | trx_ro_commits                           | transaction         | disabled |
     | trx_rseg_current_size                    | transaction         | disabled |
     | trx_rseg_history_len                     | transaction         | enabled  |
     | trx_rw_commits                           | transaction         | disabled |
     | trx_undo_slots_cached                    | transaction         | disabled |
     | trx_undo_slots_used                      | transaction         | disabled |
     +------------------------------------------+---------------------+----------+
     235 rows in set (0.01 sec)

*Counter Modules*

The module names correspond to, but are not identical to, the values
from the 'SUBSYSTEM' column of the 'INNODB_METRICS'
table.  Rather enabling, disabling, or resetting
counters individually, you can use module names to quickly enable,
disable, or reset all counters for a particular subsystem.  For example,
use 'module_dml' to enable all counters associated with the 'dml'
subsystem.

     mysql> SET GLOBAL innodb_monitor_enable = module_dml;

     mysql> SELECT name, subsystem, status FROM INFORMATION_SCHEMA.INNODB_METRICS
            WHERE subsystem ='dml';
     +-------------+-----------+---------+
     | name        | subsystem | status  |
     +-------------+-----------+---------+
     | dml_reads   | dml       | enabled |
     | dml_inserts | dml       | enabled |
     | dml_deletes | dml       | enabled |
     | dml_updates | dml       | enabled |
     +-------------+-----------+---------+

Here are the values you can use for MODULE_NAME with the
'innodb_monitor_enable' and related configuration options, along with
the corresponding 'SUBSYSTEM' names:

   * 'module_adaptive_hash' (subsystem = 'adaptive_hash_index')

   * 'module_buffer' (subsystem = 'buffer')

   * 'module_buffer_page' (subsystem = 'buffer_page_io')

   * 'module_compress' (subsystem = 'compression')

   * 'module_ddl' (subsystem = 'ddl')

   * 'module_dml' (subsystem = 'dml')

   * 'module_file' (subsystem = 'file_system')

   * 'module_ibuf_system' (subsystem = 'change_buffer')

   * 'module_icp' (subsystem = 'icp')

   * 'module_index' (subsystem = 'index')

   * 'module_innodb' (subsystem = 'innodb')

   * 'module_lock' (subsystem = 'lock')

   * 'module_log' (subsystem = 'recovery')

   * 'module_metadata' (subsystem = 'metadata')

   * 'module_os' (subsystem = 'os')

   * 'module_purge' (subsystem = 'purge')

   * 'module_trx' (subsystem = 'transaction')

This example demonstrates enabling, disabling, and resetting a counter,
and querying counter data in the 'INNODB_METRICS'
table.

  1. Create a simple 'InnoDB' table:

          mysql> USE test;
          Database changed

          mysql> CREATE TABLE t1 (c1 INT) ENGINE=INNODB;
          Query OK, 0 rows affected (0.02 sec)

  2. Enable the 'dml_inserts' counter.

          mysql> SET GLOBAL innodb_monitor_enable = dml_inserts;
          Query OK, 0 rows affected (0.01 sec)

     A description of the 'dml_inserts' counter can be found in the
     'COMMENT' column of the 'INNODB_METRICS' table:

          mysql> SELECT NAME, COMMENT FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts";
          +-------------+-------------------------+
          | NAME        | COMMENT                 |
          +-------------+-------------------------+
          | dml_inserts | Number of rows inserted |
          +-------------+-------------------------+

  3. Query the 'INNODB_METRICS' table for
     the 'dml_inserts' counter data.  Because no DML operations have
     been performed, the counter values are zero or NULL. The
     'TIME_ENABLED' and 'TIME_ELAPSED' values indicate when the counter
     was last enabled and how many seconds have elapsed since this time.

          mysql>  SELECT * FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts" \G
          *************************** 1. row ***************************
                     NAME: dml_inserts
                SUBSYSTEM: dml
                    COUNT: 0
                MAX_COUNT: 0
                MIN_COUNT: NULL
                AVG_COUNT: 0
              COUNT_RESET: 0
          MAX_COUNT_RESET: 0
          MIN_COUNT_RESET: NULL
          AVG_COUNT_RESET: NULL
             TIME_ENABLED: 2014-12-04 14:18:28
            TIME_DISABLED: NULL
             TIME_ELAPSED: 28
               TIME_RESET: NULL
                   STATUS: enabled
                     TYPE: status_counter
                  COMMENT: Number of rows inserted

  4. Insert three rows of data into the table.

          mysql> INSERT INTO t1 values(1);
          Query OK, 1 row affected (0.00 sec)

          mysql> INSERT INTO t1 values(2);
          Query OK, 1 row affected (0.00 sec)

          mysql> INSERT INTO t1 values(3);
          Query OK, 1 row affected (0.00 sec)

  5. Query the 'INNODB_METRICS' table again
     for the 'dml_inserts' counter data.  A number of counter values
     have now incremented including 'COUNT', 'MAX_COUNT', 'AVG_COUNT',
     and 'COUNT_RESET'.  Refer to the 'INNODB_METRICS'
     table definition for descriptions of these
     values.

          mysql>  SELECT * FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts"\G
          *************************** 1. row ***************************
                     NAME: dml_inserts
                SUBSYSTEM: dml
                    COUNT: 3
                MAX_COUNT: 3
                MIN_COUNT: NULL
                AVG_COUNT: 0.046153846153846156
              COUNT_RESET: 3
          MAX_COUNT_RESET: 3
          MIN_COUNT_RESET: NULL
          AVG_COUNT_RESET: NULL
             TIME_ENABLED: 2014-12-04 14:18:28
            TIME_DISABLED: NULL
             TIME_ELAPSED: 65
               TIME_RESET: NULL
                   STATUS: enabled
                     TYPE: status_counter
                  COMMENT: Number of rows inserted

  6. Reset the 'dml_inserts' counter, and query the
     'INNODB_METRICS' table again for the
     'dml_inserts' counter data.  The '%_RESET' values that were
     reported previously, such as 'COUNT_RESET' and 'MAX_RESET', are set
     back to zero.  Values such as 'COUNT', 'MAX_COUNT', and
     'AVG_COUNT', which cumulatively collect data from the time the
     counter is enabled, are unaffected by the reset.

          mysql> SET GLOBAL innodb_monitor_reset = dml_inserts;
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts"\G
          *************************** 1. row ***************************
                     NAME: dml_inserts
                SUBSYSTEM: dml
                    COUNT: 3
                MAX_COUNT: 3
                MIN_COUNT: NULL
                AVG_COUNT: 0.03529411764705882
              COUNT_RESET: 0
          MAX_COUNT_RESET: 0
          MIN_COUNT_RESET: NULL
          AVG_COUNT_RESET: 0
             TIME_ENABLED: 2014-12-04 14:18:28
            TIME_DISABLED: NULL
             TIME_ELAPSED: 85
               TIME_RESET: 2014-12-04 14:19:44
                   STATUS: enabled
                     TYPE: status_counter
                  COMMENT: Number of rows inserted

  7. To reset all counter values, you must first disable the counter.
     Disabling the counter sets the 'STATUS' value to 'disbaled'.

          mysql> SET GLOBAL innodb_monitor_disable = dml_inserts;
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts"\G
          *************************** 1. row ***************************
                     NAME: dml_inserts
                SUBSYSTEM: dml
                    COUNT: 3
                MAX_COUNT: 3
                MIN_COUNT: NULL
                AVG_COUNT: 0.030612244897959183
              COUNT_RESET: 0
          MAX_COUNT_RESET: 0
          MIN_COUNT_RESET: NULL
          AVG_COUNT_RESET: 0
             TIME_ENABLED: 2014-12-04 14:18:28
            TIME_DISABLED: 2014-12-04 14:20:06
             TIME_ELAPSED: 98
               TIME_RESET: NULL
                   STATUS: disabled
                     TYPE: status_counter
                  COMMENT: Number of rows inserted

     *Note*:

     Wildcard match is supported for counter and module names.  For
     example, instead of specifying the full 'dml_inserts' counter name,
     you can specify 'dml_i%'.  You can also enable, disable, or reset
     multiple counters or modules at once using a wildcard match.  For
     example, specify 'dml_%' to enable, disable, or reset all counters
     that begin with 'dml_%'.

  8. After the counter is disabled, you can reset all counter values
     using the 'innodb_monitor_reset_all' option.  All values are set to
     zero or NULL.

          mysql> SET GLOBAL innodb_monitor_reset_all = dml_inserts;
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts"\G
          *************************** 1. row ***************************
                     NAME: dml_inserts
                SUBSYSTEM: dml
                    COUNT: 0
                MAX_COUNT: NULL
                MIN_COUNT: NULL
                AVG_COUNT: NULL
              COUNT_RESET: 0
          MAX_COUNT_RESET: NULL
          MIN_COUNT_RESET: NULL
          AVG_COUNT_RESET: NULL
             TIME_ENABLED: NULL
            TIME_DISABLED: NULL
             TIME_ELAPSED: NULL
               TIME_RESET: NULL
                   STATUS: disabled
                     TYPE: status_counter
                  COMMENT: Number of rows inserted

14.15.7 InnoDB INFORMATION_SCHEMA Temporary Table Info Table
------------------------------------------------------------

'INNODB_TEMP_TABLE_INFO' provides
information about user-created 'InnoDB' temporary tables that are
currently active within the 'InnoDB' instance.  It does not provide
information about internal 'InnoDB' temporary tables that are used by
the optimizer.

     mysql> SHOW TABLES FROM INFORMATION_SCHEMA LIKE 'INNODB_TEMP%';
     +---------------------------------------------+
     | Tables_in_INFORMATION_SCHEMA (INNODB_TEMP%) |
     +---------------------------------------------+
     | INNODB_TEMP_TABLE_INFO                      |
     +---------------------------------------------+

For the table definition, see innodb-temp-table-info-table.

This example demonstrates characteristics of the
'INNODB_TEMP_TABLE_INFO' table.

  1. Create a simple 'InnoDB' temporary table:

          mysql> CREATE TEMPORARY TABLE t1 (c1 INT PRIMARY KEY) ENGINE=INNODB;

  2. Query 'INNODB_TEMP_TABLE_INFO'.
     to view the temporary table metadata.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_TEMP_TABLE_INFO\G
          *************************** 1. row ***************************
                      TABLE_ID: 194
                          NAME: #sql7a79_1_0
                        N_COLS: 4
                         SPACE: 182
          PER_TABLE_TABLESPACE: FALSE
                 IS_COMPRESSED: FALSE

     The 'TABLE_ID ' is a unique identifier for the temporary table.
     The 'NAME' column displays the system-generated name for the
     temporary table, which is prefixed with '#sql'.  The number of
     columns ('N_COLS') is 4 rather than 1 because 'InnoDB' always
     creates three hidden table columns ('DB_ROW_ID', 'DB_TRX_ID', and
     'DB_ROLL_PTR').  'PER_TABLE_TABLESPACE' and 'IS_COMPRESSED' report
     'TRUE' for compressed temporary tables.  Otherwise, these fields
     report 'FALSE'.

  3. Create a compressed temporary table.

          mysql> CREATE TEMPORARY TABLE t2 (c1 INT) ROW_FORMAT=COMPRESSED ENGINE=INNODB;

  4. Query 'INNODB_TEMP_TABLE_INFO'.
     again.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_TEMP_TABLE_INFO\G
          *************************** 1. row ***************************
                      TABLE_ID: 195
                          NAME: #sql7a79_1_1
                        N_COLS: 4
                         SPACE: 183
          PER_TABLE_TABLESPACE: TRUE
                 IS_COMPRESSED: TRUE
          *************************** 2. row ***************************
                      TABLE_ID: 194
                          NAME: #sql7a79_1_0
                        N_COLS: 4
                         SPACE: 182
          PER_TABLE_TABLESPACE: FALSE
                 IS_COMPRESSED: FALSE

     'PER_TABLE_TABLESPACE' and 'IS_COMPRESSED' report 'TRUE' for the
     compressed temporary table.  The 'SPACE' ID for the compressed
     temporary table is different because compressed temporary tables
     are created in separate file-per-table tablespaces.  Non-compressed
     temporary tables are created in the shared temporary tablespace
     ('ibtmp1') and report the same 'SPACE' ID.

  5. Restart MySQL and query 'INNODB_TEMP_TABLE_INFO'.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_TEMP_TABLE_INFO\G
          Empty set (0.00 sec)

     An empty set is returned because 'INNODB_TEMP_TABLE_INFO'
     and the data within it are not
     persisted to disk on server shutdown.

  6. Create a new temporary table.

          mysql> CREATE TEMPORARY TABLE t1 (c1 INT PRIMARY KEY) ENGINE=INNODB;

  7. Query 'INNODB_TEMP_TABLE_INFO'.
     to view the temporary table metadata.

          mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_TEMP_TABLE_INFO\G
          *************************** 1. row ***************************
                      TABLE_ID: 196
                          NAME: #sql7b0e_1_0
                        N_COLS: 4
                         SPACE: 184
          PER_TABLE_TABLESPACE: FALSE
                 IS_COMPRESSED: FALSE

     The 'SPACE' ID is new because it is dynamically generated on server
     restart.

14.15.8 Retrieving InnoDB Tablespace Metadata from INFORMATION_SCHEMA.FILES
---------------------------------------------------------------------------

The 'INFORMATION_SCHEMA.FILES' table provides
metadata about all 'InnoDB' tablespace types including file-per-table
tablespaces, general tablespaces, the system tablespace, temporary table
tablespaces, and undo tablespaces (if present).

This section provides 'InnoDB'-specific usage examples.  For more
information about data provided by the 'INFORMATION_SCHEMA.FILES'
table, see files-table.

*Note*:

The 'INNODB_SYS_TABLESPACES' and
'INNODB_SYS_DATAFILES' tables also
provide metadata about 'InnoDB' tablespaces, but data is limited to
file-per-table and general tablespaces.

This query retrieves metadata about the 'InnoDB' system tablespace from
fields of the 'INFORMATION_SCHEMA.FILES' table that
are pertinent to 'InnoDB' tablespaces.
'INFORMATION_SCHEMA.FILES' fields that are not relevant to
'InnoDB' always return NULL, and are excluded from the query.

     mysql> SELECT FILE_ID, FILE_NAME, FILE_TYPE, TABLESPACE_NAME, FREE_EXTENTS,
            TOTAL_EXTENTS,  EXTENT_SIZE, INITIAL_SIZE, MAXIMUM_SIZE, AUTOEXTEND_SIZE, DATA_FREE, STATUS ENGINE
            FROM INFORMATION_SCHEMA.FILES WHERE TABLESPACE_NAME LIKE 'innodb_system' \G
     *************************** 1. row ***************************
             FILE_ID: 0
           FILE_NAME: ./ibdata1
           FILE_TYPE: TABLESPACE
     TABLESPACE_NAME: innodb_system
        FREE_EXTENTS: 0
       TOTAL_EXTENTS: 12
         EXTENT_SIZE: 1048576
        INITIAL_SIZE: 12582912
        MAXIMUM_SIZE: NULL
     AUTOEXTEND_SIZE: 67108864
           DATA_FREE: 4194304
              ENGINE: NORMAL

This query retrieves the 'FILE_ID' (equivalent to the space ID) and the
'FILE_NAME' (which includes path information) for 'InnoDB'
file-per-table and general tablespaces.  File-per-table and general
tablespaces have a '.ibd' file extension.

     mysql> SELECT FILE_ID, FILE_NAME FROM INFORMATION_SCHEMA.FILES
            WHERE FILE_NAME LIKE '%.ibd%' ORDER BY FILE_ID;
         +---------+---------------------------------------+
         | FILE_ID | FILE_NAME                             |
         +---------+---------------------------------------+
         |       2 | ./mysql/plugin.ibd                    |
         |       3 | ./mysql/servers.ibd                   |
         |       4 | ./mysql/help_topic.ibd                |
         |       5 | ./mysql/help_category.ibd             |
         |       6 | ./mysql/help_relation.ibd             |
         |       7 | ./mysql/help_keyword.ibd              |
         |       8 | ./mysql/time_zone_name.ibd            |
         |       9 | ./mysql/time_zone.ibd                 |
         |      10 | ./mysql/time_zone_transition.ibd      |
         |      11 | ./mysql/time_zone_transition_type.ibd |
         |      12 | ./mysql/time_zone_leap_second.ibd     |
         |      13 | ./mysql/innodb_table_stats.ibd        |
         |      14 | ./mysql/innodb_index_stats.ibd        |
         |      15 | ./mysql/slave_relay_log_info.ibd      |
         |      16 | ./mysql/slave_master_info.ibd         |
         |      17 | ./mysql/slave_worker_info.ibd         |
         |      18 | ./mysql/gtid_executed.ibd             |
         |      19 | ./mysql/server_cost.ibd               |
         |      20 | ./mysql/engine_cost.ibd               |
         |      21 | ./sys/sys_config.ibd                  |
         |      23 | ./test/t1.ibd                         |
         |      26 | /home/user/test/test/t2.ibd           |
         +---------+---------------------------------------+

This query retrieves the 'FILE_ID' and 'FILE_NAME' for 'InnoDB'
temporary tablespaces.  Temporary tablespace file names are prefixed by
'ibtmp'.

     mysql> SELECT FILE_ID, FILE_NAME FROM INFORMATION_SCHEMA.FILES
            WHERE FILE_NAME LIKE '%ibtmp%';
     +---------+-----------+
     | FILE_ID | FILE_NAME |
     +---------+-----------+
     |      22 | ./ibtmp1  |
     +---------+-----------+

Similarly, 'InnoDB' undo tablespace file names are prefixed by 'undo'.
The following query returns the 'FILE_ID' and 'FILE_NAME' for 'InnoDB'
undo tablespaces, if separate undo tablespaces are configured.

     mysql> SELECT FILE_ID, FILE_NAME FROM INFORMATION_SCHEMA.FILES
            WHERE FILE_NAME LIKE '%undo%';

14.16 InnoDB Integration with MySQL Performance Schema
======================================================

This section provides a brief introduction to 'InnoDB' integration with
Performance Schema.  For comprehensive Performance Schema documentation,
see performance-schema.

You can profile certain internal 'InnoDB' operations using the MySQL
Performance Schema feature.  This type of
tuning is primarily for expert users who evaluate optimization
strategies to overcome performance bottlenecks.  DBAs can also use this
feature for capacity planning, to see whether their typical workload
encounters any performance bottlenecks with a particular combination of
CPU, RAM, and disk storage; and if so, to judge whether performance can
be improved by increasing the capacity of some part of the system.

To use this feature to examine 'InnoDB' performance:

   * You must be generally familiar with how to use the
     Performance Schema feature.  For example, you
     should know how enable instruments and consumers, and how to query
     'performance_schema' tables to retrieve data.  For an introductory
     overview, see performance-schema-quick-start.

   * You should be familiar with Performance Schema instruments that are
     available for 'InnoDB'.  To view 'InnoDB'-related instruments, you
     can query the 'setup_instruments'.
     table for instrument names that contain ''innodb''.

          mysql> SELECT * FROM setup_instruments WHERE NAME LIKE '%innodb%';
          +-------------------------------------------------------+---------+-------+
          | NAME                                                  | ENABLED | TIMED |
          +-------------------------------------------------------+---------+-------+
          | wait/synch/mutex/innodb/commit_cond_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/innobase_share_mutex          | NO      | NO    |
          | wait/synch/mutex/innodb/autoinc_mutex                 | NO      | NO    |
          | wait/synch/mutex/innodb/buf_pool_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/buf_pool_zip_mutex            | NO      | NO    |
          | wait/synch/mutex/innodb/cache_last_read_mutex         | NO      | NO    |
          | wait/synch/mutex/innodb/dict_foreign_err_mutex        | NO      | NO    |
          | wait/synch/mutex/innodb/dict_sys_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/recalc_pool_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/file_format_max_mutex         | NO      | NO    |
          ...
          | wait/io/file/innodb/innodb_data_file                  | YES     | YES   |
          | wait/io/file/innodb/innodb_log_file                   | YES     | YES   |
          | wait/io/file/innodb/innodb_temp_file                  | YES     | YES   |
          | stage/innodb/alter table (end)                        | YES     | YES   |
          | stage/innodb/alter table (flush)                      | YES     | YES   |
          | stage/innodb/alter table (insert)                     | YES     | YES   |
          | stage/innodb/alter table (log apply index)            | YES     | YES   |
          | stage/innodb/alter table (log apply table)            | YES     | YES   |
          | stage/innodb/alter table (merge sort)                 | YES     | YES   |
          | stage/innodb/alter table (read PK and internal sort)  | YES     | YES   |
          | stage/innodb/buffer pool load                         | YES     | YES   |
          | memory/innodb/buf_buf_pool                            | NO      | NO    |
          | memory/innodb/dict_stats_bg_recalc_pool_t             | NO      | NO    |
          | memory/innodb/dict_stats_index_map_t                  | NO      | NO    |
          | memory/innodb/dict_stats_n_diff_on_level              | NO      | NO    |
          | memory/innodb/other                                   | NO      | NO    |
          | memory/innodb/row_log_buf                             | NO      | NO    |
          | memory/innodb/row_merge_sort                          | NO      | NO    |
          | memory/innodb/std                                     | NO      | NO    |
          | memory/innodb/sync_debug_latches                      | NO      | NO    |
          | memory/innodb/trx_sys_t::rw_trx_ids                   | NO      | NO    |
          ...
          +-------------------------------------------------------+---------+-------+
          155 rows in set (0.00 sec)

     For additional information about the instrumented 'InnoDB' objects,
     you can query Performance Schema instances tables,
     which provide additional
     information about instrumented objects.  Instance tables relevant
     to 'InnoDB' include:

        * The 'mutex_instances' table

        * The 'rwlock_instances' table

        * The 'cond_instances' table

        * The 'file_instances' table

     *Note*:

     Mutexes and RW-locks related to the 'InnoDB' buffer pool are not
     included in this coverage; the same applies to the output of the
     'SHOW ENGINE INNODB MUTEX' command.

     For example, to view information about instrumented 'InnoDB' file
     objects seen by the Performance Schema when executing file I/O
     instrumentation, you might issue the following query:

          mysql> SELECT * FROM file_instances WHERE EVENT_NAME LIKE '%innodb%'\G
          *************************** 1. row ***************************
           FILE_NAME: /path/to/mysql-5.7/data/ibdata1
          EVENT_NAME: wait/io/file/innodb/innodb_data_file
          OPEN_COUNT: 3
          *************************** 2. row ***************************
           FILE_NAME: /path/to/mysql-5.7/data/ib_logfile0
          EVENT_NAME: wait/io/file/innodb/innodb_log_file
          OPEN_COUNT: 2
          *************************** 3. row ***************************
           FILE_NAME: /path/to/mysql-5.7/data/ib_logfile1
          EVENT_NAME: wait/io/file/innodb/innodb_log_file
          OPEN_COUNT: 2
          *************************** 4. row ***************************
           FILE_NAME: /path/to/mysql-5.7/data/mysql/engine_cost.ibd
          EVENT_NAME: wait/io/file/innodb/innodb_data_file
          OPEN_COUNT: 3
          ...

   * You should be familiar with 'performance_schema' tables that store
     'InnoDB' event data.  Tables relevant to 'InnoDB'-related events
     include:

        * The Wait Event tables,
          which store wait events.

        * The Summary tables,
          which provide aggregated information for terminated events
          over time.  Summary tables include file I/O summary tables,
          which aggregate information about
          I/O operations.

        * Stage Event tables,
          which store event data for 'InnoDB' 'ALTER TABLE'
          and buffer pool load operations.  For more
          information, see
          monitor-alter-table-performance-schema, and
          monitor-buffer-pool-load-performance-schema.

     If you are only interested in 'InnoDB'-related objects, use the
     clause 'WHERE EVENT_NAME LIKE '%innodb%'' or 'WHERE NAME LIKE
     '%innodb%'' (as required) when querying these tables.

14.16.1 Monitoring ALTER TABLE Progress for InnoDB Tables Using Performance Schema
----------------------------------------------------------------------------------

You can monitor 'ALTER TABLE' progress for 'InnoDB'
tables using Performance Schema.

There are seven stage events that represent different phases of
'ALTER TABLE'.  Each stage event reports a running total of
'WORK_COMPLETED' and 'WORK_ESTIMATED' for the overall 'ALTER TABLE'
operation as it progresses through its different
phases.  'WORK_ESTIMATED' is calculated using a formula that takes into
account all of the work that 'ALTER TABLE' performs,
and may be revised during 'ALTER TABLE' processing.
'WORK_COMPLETED' and 'WORK_ESTIMATED' values are an abstract
representation of all of the work performed by 'ALTER TABLE'.

In order of occurrence, see 'ALTER TABLE' stage events
include:

   * 'stage/innodb/alter table (read PK and internal sort)': This stage
     is active when 'ALTER TABLE' is in the
     reading-primary-key phase.  It starts with 'WORK_COMPLETED=0' and
     'WORK_ESTIMATED' set to the estimated number of pages in the
     primary key.  When the stage is completed, 'WORK_ESTIMATED' is
     updated to the actual number of pages in the primary key.

   * 'stage/innodb/alter table (merge sort)': This stage is repeated for
     each index added by the 'ALTER TABLE'.
     operation.

   * 'stage/innodb/alter table (insert)': This stage is repeated for
     each index added by the 'ALTER TABLE'.
     operation.

   * 'stage/innodb/alter table (log apply index)': This stage includes
     the application of DML log generated while 'ALTER TABLE'
     was running.

   * 'stage/innodb/alter table (flush)': Before this stage begins,
     'WORK_ESTIMATED' is updated with a more accurate estimate, based on
     the length of the flush list.

   * 'stage/innodb/alter table (log apply table)': This stage includes
     the application of concurrent DML log generated while 'ALTER TABLE'
     was running.  The duration of this phase
     depends on the extent of table changes.  This phase is instant if
     no concurrent DML was run on the table.

   * 'stage/innodb/alter table (end)': Includes any remaining work that
     appeared after the flush phase, such as reapplying DML that was
     executed on the table while 'ALTER TABLE' was
     running.

*Note*:

'InnoDB' 'ALTER TABLE' stage events do not currently
account for the addition of spatial indexes.

*ALTER TABLE Monitoring Example Using Performance Schema*

The following example demonstrates how to enable the 'stage/innodb/alter
table%' stage event instruments and related consumer tables to monitor
'ALTER TABLE' progress.  For information about
Performance Schema stage event instruments and related consumers, see
performance-schema-stage-tables.

  1. Enable the 'stage/innodb/alter%' instruments:

          mysql> UPDATE setup_instruments SET ENABLED = 'YES' WHERE NAME LIKE 'stage/innodb/alter%';
          Query OK, 7 rows affected (0.00 sec)
          Rows matched: 7  Changed: 7  Warnings: 0

  2. Enable the stage event consumer tables, which include
     'events_stages_current',
     'events_stages_history', and
     'events_stages_history_long'.

          mysql> UPDATE setup_consumers SET ENABLED = 'YES' WHERE NAME LIKE '%stages%';
          Query OK, 3 rows affected (0.00 sec)
          Rows matched: 3  Changed: 3  Warnings: 0

  3. Run an 'ALTER TABLE' operation.  In this
     example, a 'middle_name' column is added to the employees table of
     the employees sample database.

          mysql> ALTER TABLE employees.employees ADD COLUMN middle_name varchar(14) AFTER first_name;
          Query OK, 0 rows affected (9.27 sec)
          Records: 0  Duplicates: 0  Warnings: 0

  4. Check the progress of the 'ALTER TABLE'.
     operation by querying the Performance Schema
     'events_stages_current' table.  The
     stage event shown differs depending on which 'ALTER TABLE'
     phase is currently in progress.  The 'WORK_COMPLETED'
     column shows the work completed.  The 'WORK_ESTIMATED' column
     provides an estimate of the remaining work.

          mysql> SELECT EVENT_NAME, WORK_COMPLETED, WORK_ESTIMATED FROM events_stages_current;
          +------------------------------------------------------+----------------+----------------+
          | EVENT_NAME                                           | WORK_COMPLETED | WORK_ESTIMATED |
          +------------------------------------------------------+----------------+----------------+
          | stage/innodb/alter table (read PK and internal sort) |            280 |           1245 |
          +------------------------------------------------------+----------------+----------------+
          1 row in set (0.01 sec)

     The 'events_stages_current'.
     table returns an empty set if the 'ALTER TABLE'.
     operation has completed.  In this case, you can check the
     'events_stages_history' table to view
     event data for the completed operation.  For example:

          mysql> SELECT EVENT_NAME, WORK_COMPLETED, WORK_ESTIMATED FROM events_stages_history;
          +------------------------------------------------------+----------------+----------------+
          | EVENT_NAME                                           | WORK_COMPLETED | WORK_ESTIMATED |
          +------------------------------------------------------+----------------+----------------+
          | stage/innodb/alter table (read PK and internal sort) |            886 |           1213 |
          | stage/innodb/alter table (flush)                     |           1213 |           1213 |
          | stage/innodb/alter table (log apply table)           |           1597 |           1597 |
          | stage/innodb/alter table (end)                       |           1597 |           1597 |
          | stage/innodb/alter table (log apply table)           |           1981 |           1981 |
          +------------------------------------------------------+----------------+----------------+
          5 rows in set (0.00 sec)

     As shown above, the 'WORK_ESTIMATED' value was revised during
     'ALTER TABLE' processing.  The estimated work after completion of
     the initial stage is 1213.  When 'ALTER TABLE' processing
     completed, 'WORK_ESTIMATED' was set to the actual value, which is
     1981.

14.16.2 Monitoring InnoDB Mutex Waits Using Performance Schema
--------------------------------------------------------------

A mutex is a synchronization mechanism used in the code to enforce that
only one thread at a given time can have access to a common resource.
When two or more threads executing in the server need to access the same
resource, the threads compete against each other.  The first thread to
obtain a lock on the mutex causes the other threads to wait until the
lock is released.

For 'InnoDB' mutexes that are instrumented, mutex waits can be monitored
using Performance Schema.  Wait event data
collected in Performance Schema tables can help identify mutexes with
the most waits or the greatest total wait time, for example.

The following example demonstrates how to enable 'InnoDB' mutex wait
instruments, how to enable associated consumers, and how to query wait
event data.

  1. To view available 'InnoDB' mutex wait instruments, query the
     Performance Schema 'setup_instruments'
     table, as shown below.  All 'InnoDB' mutex
     wait instruments are disabled by default.

          mysql> SELECT * FROM performance_schema.setup_instruments
                 WHERE NAME LIKE '%wait/synch/mutex/innodb%';
          +-------------------------------------------------------+---------+-------+
          | NAME                                                  | ENABLED | TIMED |
          +-------------------------------------------------------+---------+-------+
          | wait/synch/mutex/innodb/commit_cond_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/innobase_share_mutex          | NO      | NO    |
          | wait/synch/mutex/innodb/autoinc_mutex                 | NO      | NO    |
          | wait/synch/mutex/innodb/buf_pool_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/buf_pool_zip_mutex            | NO      | NO    |
          | wait/synch/mutex/innodb/cache_last_read_mutex         | NO      | NO    |
          | wait/synch/mutex/innodb/dict_foreign_err_mutex        | NO      | NO    |
          | wait/synch/mutex/innodb/dict_sys_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/recalc_pool_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/file_format_max_mutex         | NO      | NO    |
          | wait/synch/mutex/innodb/fil_system_mutex              | NO      | NO    |
          | wait/synch/mutex/innodb/flush_list_mutex              | NO      | NO    |
          | wait/synch/mutex/innodb/fts_bg_threads_mutex          | NO      | NO    |
          | wait/synch/mutex/innodb/fts_delete_mutex              | NO      | NO    |
          | wait/synch/mutex/innodb/fts_optimize_mutex            | NO      | NO    |
          | wait/synch/mutex/innodb/fts_doc_id_mutex              | NO      | NO    |
          | wait/synch/mutex/innodb/log_flush_order_mutex         | NO      | NO    |
          | wait/synch/mutex/innodb/hash_table_mutex              | NO      | NO    |
          | wait/synch/mutex/innodb/ibuf_bitmap_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/ibuf_mutex                    | NO      | NO    |
          | wait/synch/mutex/innodb/ibuf_pessimistic_insert_mutex | NO      | NO    |
          | wait/synch/mutex/innodb/log_sys_mutex                 | NO      | NO    |
          | wait/synch/mutex/innodb/page_zip_stat_per_index_mutex | NO      | NO    |
          | wait/synch/mutex/innodb/purge_sys_pq_mutex            | NO      | NO    |
          | wait/synch/mutex/innodb/recv_sys_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/recv_writer_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/redo_rseg_mutex               | NO      | NO    |
          | wait/synch/mutex/innodb/noredo_rseg_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/rw_lock_list_mutex            | NO      | NO    |
          | wait/synch/mutex/innodb/rw_lock_mutex                 | NO      | NO    |
          | wait/synch/mutex/innodb/srv_dict_tmpfile_mutex        | NO      | NO    |
          | wait/synch/mutex/innodb/srv_innodb_monitor_mutex      | NO      | NO    |
          | wait/synch/mutex/innodb/srv_misc_tmpfile_mutex        | NO      | NO    |
          | wait/synch/mutex/innodb/srv_monitor_file_mutex        | NO      | NO    |
          | wait/synch/mutex/innodb/buf_dblwr_mutex               | NO      | NO    |
          | wait/synch/mutex/innodb/trx_undo_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/trx_pool_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/trx_pool_manager_mutex        | NO      | NO    |
          | wait/synch/mutex/innodb/srv_sys_mutex                 | NO      | NO    |
          | wait/synch/mutex/innodb/lock_mutex                    | NO      | NO    |
          | wait/synch/mutex/innodb/lock_wait_mutex               | NO      | NO    |
          | wait/synch/mutex/innodb/trx_mutex                     | NO      | NO    |
          | wait/synch/mutex/innodb/srv_threads_mutex             | NO      | NO    |
          | wait/synch/mutex/innodb/rtr_active_mutex              | NO      | NO    |
          | wait/synch/mutex/innodb/rtr_match_mutex               | NO      | NO    |
          | wait/synch/mutex/innodb/rtr_path_mutex                | NO      | NO    |
          | wait/synch/mutex/innodb/rtr_ssn_mutex                 | NO      | NO    |
          | wait/synch/mutex/innodb/trx_sys_mutex                 | NO      | NO    |
          | wait/synch/mutex/innodb/zip_pad_mutex                 | NO      | NO    |
          +-------------------------------------------------------+---------+-------+
          49 rows in set (0.02 sec)

  2. Some 'InnoDB' mutex instances are created at server startup and are
     only instrumented if the associated instrument is also enabled at
     server startup.  To ensure that all 'InnoDB' mutex instances are
     instrumented and enabled, add the following
     'performance-schema-instrument' rule to your MySQL configuration
     file:

          performance-schema-instrument='wait/synch/mutex/innodb/%=ON'

     If you do not require wait event data for all 'InnoDB' mutexes, you
     can disable specific instruments by adding additional
     'performance-schema-instrument' rules to your MySQL configuration
     file.  For example, to disable 'InnoDB' mutex wait event
     instruments related to full-text search, add the following rule:

          performance-schema-instrument='wait/synch/mutex/innodb/fts%=OFF'

     *Note*:

     Rules with a longer prefix such as 'wait/synch/mutex/innodb/fts%'
     take precedence over rules with shorter prefixes such as
     'wait/synch/mutex/innodb/%'.

     After adding the 'performance-schema-instrument' rules to your
     configuration file, restart the server.  All the 'InnoDB' mutexes
     except for those related to full text search are enabled.  To
     verify, query the 'setup_instruments'
     table.  The 'ENABLED' and 'TIMED' columns
     should be set to 'YES' for the instruments that you enabled.

          mysql> SELECT * FROM performance_schema.setup_instruments
                  WHERE NAME LIKE '%wait/synch/mutex/innodb%';
          +-------------------------------------------------------+---------+-------+
          | NAME                                                  | ENABLED | TIMED |
          +-------------------------------------------------------+---------+-------+
          | wait/synch/mutex/innodb/commit_cond_mutex             | YES     | YES   |
          | wait/synch/mutex/innodb/innobase_share_mutex          | YES     | YES   |
          | wait/synch/mutex/innodb/autoinc_mutex                 | YES     | YES   |
          ...
          | wait/synch/mutex/innodb/zip_pad_mutex                 | YES     | YES   |
          +-------------------------------------------------------+---------+-------+
          49 rows in set (0.00 sec)

  3. Enable wait event consumers by updating the
     'setup_consumers' table.  Wait event
     consumers are disabled by default.

          mysql> UPDATE performance_schema.setup_consumers SET enabled = 'YES'
                 WHERE name like 'events_waits%';
          Query OK, 3 rows affected (0.00 sec)
          Rows matched: 3  Changed: 3  Warnings: 0

     You can verify that wait event consumers are enabled by querying
     the 'setup_consumers' table.  The
     'events_waits_current',
     'events_waits_history', and
     'events_waits_history_long'.
     consumers should be enabled.

          mysql> SELECT * FROM performance_schema.setup_consumers;
          +----------------------------------+---------+
          | NAME                             | ENABLED |
          +----------------------------------+---------+
          | events_stages_current            | NO      |
          | events_stages_history            | NO      |
          | events_stages_history_long       | NO      |
          | events_statements_current        | YES     |
          | events_statements_history        | YES     |
          | events_statements_history_long   | NO      |
          | events_transactions_current      | YES     |
          | events_transactions_history      | YES     |
          | events_transactions_history_long | NO      |
          | events_waits_current             | YES     |
          | events_waits_history             | YES     |
          | events_waits_history_long        | YES     |
          | global_instrumentation           | YES     |
          | thread_instrumentation           | YES     |
          | statements_digest                | YES     |
          +----------------------------------+---------+
          15 rows in set (0.00 sec)

  4. Once instruments and consumers are enabled, run the workload that
     you want to monitor.  In this example, the 'mysqlslap'
     load emulation client is used to simulate a workload.

          shell> ./mysqlslap --auto-generate-sql --concurrency=100 --iterations=10
                 --number-of-queries=1000 --number-char-cols=6 --number-int-cols=6;

  5. Query the wait event data.  In this example, wait event data is
     queried from the 'events_waits_summary_global_by_event_name'
     table which aggregates data found in the
     'events_waits_current',
     'events_waits_history', and
     'events_waits_history_long'.
     tables.  Data is summarized by event name ('EVENT_NAME'), which is
     the name of the instrument that produced the event.  Summarized
     data includes:

        * 'COUNT_STAR'

          The number of summarized wait events.

        * 'SUM_TIMER_WAIT'

          The total wait time of the summarized timed wait events.

        * 'MIN_TIMER_WAIT'

          The minimum wait time of the summarized timed wait events.

        * 'AVG_TIMER_WAIT'

          The average wait time of the summarized timed wait events.

        * 'MAX_TIMER_WAIT'

          The maximum wait time of the summarized timed wait events.

     The following query returns the instrument name ('EVENT_NAME'), the
     number of wait events ('COUNT_STAR'), and the total wait time for
     the events for that instrument ('SUM_TIMER_WAIT').  Because waits
     are timed in picoseconds (trillionths of a second) by default, wait
     times are divided by 1000000000 to show wait times in milliseconds.
     Data is presented in descending order, by the number of summarized
     wait events ('COUNT_STAR').  You can adjust the 'ORDER BY' clause
     to order the data by total wait time.

          mysql> SELECT EVENT_NAME, COUNT_STAR, SUM_TIMER_WAIT/1000000000 SUM_TIMER_WAIT_MS
                 FROM performance_schema.events_waits_summary_global_by_event_name
                 WHERE SUM_TIMER_WAIT > 0 AND EVENT_NAME LIKE 'wait/synch/mutex/innodb/%'
                 ORDER BY COUNT_STAR DESC;
          +--------------------------------------------------+------------+-------------------+
          | EVENT_NAME                                       | COUNT_STAR | SUM_TIMER_WAIT_MS |
          +--------------------------------------------------+------------+-------------------+
          | wait/synch/mutex/innodb/os_mutex                 |      78831 |           10.3283 |
          | wait/synch/mutex/innodb/log_sys_mutex            |      41488 |         6510.3233 |
          | wait/synch/mutex/innodb/trx_sys_mutex            |      29770 |         1107.9687 |
          | wait/synch/mutex/innodb/lock_mutex               |      24212 |          104.0724 |
          | wait/synch/mutex/innodb/trx_mutex                |      22756 |            1.9421 |
          | wait/synch/mutex/innodb/rseg_mutex               |      20333 |            3.6220 |
          | wait/synch/mutex/innodb/dict_sys_mutex           |      13422 |            2.2284 |
          | wait/synch/mutex/innodb/mutex_list_mutex         |      12694 |          344.1164 |
          | wait/synch/mutex/innodb/fil_system_mutex         |       9208 |            0.9542 |
          | wait/synch/mutex/innodb/rw_lock_list_mutex       |       8304 |            0.1794 |
          | wait/synch/mutex/innodb/trx_undo_mutex           |       6190 |            0.6801 |
          | wait/synch/mutex/innodb/buf_pool_mutex           |       2869 |           29.4623 |
          | wait/synch/mutex/innodb/innobase_share_mutex     |       2005 |            0.1349 |
          | wait/synch/mutex/innodb/flush_list_mutex         |       1274 |            0.1300 |
          | wait/synch/mutex/innodb/file_format_max_mutex    |       1016 |            0.0469 |
          | wait/synch/mutex/innodb/purge_sys_bh_mutex       |       1004 |            0.0326 |
          | wait/synch/mutex/innodb/buf_dblwr_mutex          |        640 |            0.0437 |
          | wait/synch/mutex/innodb/log_flush_order_mutex    |        437 |            0.0510 |
          | wait/synch/mutex/innodb/recv_sys_mutex           |        394 |            0.0202 |
          | wait/synch/mutex/innodb/srv_sys_mutex            |        169 |            0.5259 |
          | wait/synch/mutex/innodb/lock_wait_mutex          |        154 |            0.1172 |
          | wait/synch/mutex/innodb/ibuf_mutex               |          9 |            0.0027 |
          | wait/synch/mutex/innodb/srv_innodb_monitor_mutex |          2 |            0.0009 |
          | wait/synch/mutex/innodb/ut_list_mutex            |          1 |            0.0001 |
          | wait/synch/mutex/innodb/recv_writer_mutex        |          1 |            0.0005 |
          +--------------------------------------------------+------------+-------------------+
          25 rows in set (0.01 sec)

     *Note*:

     The preceding result set includes wait event data produced during
     the startup process.  To exclude this data, you can truncate the
     'events_waits_summary_global_by_event_name'
     table immediately after startup and before
     running your workload.  However, the truncate operation itself may
     produce a negligible amount wait event data.

          mysql> TRUNCATE performance_schema.events_waits_summary_global_by_event_name;

14.17 InnoDB Monitors
=====================

'InnoDB' monitors provide information about the 'InnoDB' internal state.
This information is useful for performance tuning.

14.17.1 InnoDB Monitor Types
----------------------------

There are two types of 'InnoDB' monitor:

   * The standard 'InnoDB' Monitor displays the following types of
     information:

        * Work done by the main background thread

        * Semaphore waits

        * Data about the most recent foreign key and deadlock errors

        * Lock waits for transactions

        * Table and record locks held by active transactions

        * Pending I/O operations and related statistics

        * Insert buffer and adaptive hash index statistics

        * Redo log data

        * Buffer pool statistics

        * Row operation data

   * The 'InnoDB' Lock Monitor prints additional lock information as
     part of the standard 'InnoDB' Monitor output.

14.17.2 Enabling InnoDB Monitors
--------------------------------

When 'InnoDB' monitors are enabled for periodic output, 'InnoDB' writes
the output to the 'mysqld' server standard error output
('stderr').  'InnoDB' sends diagnostic output to 'stderr' rather than to
'stdout' or fixed-size memory buffers to avoid potential buffer
overflows.

On Windows, 'stderr' is directed to the default log file unless
configured otherwise.  If you want to direct the output to the console
window rather than to the error log, start the server from a command
prompt in a console window with the '--console' option.  For more
information, see error-log-windows.

On Unix and Unix-like systems, 'stderr' is typically directed to the
terminal unless configured otherwise.  For more information, see
error-log-unix.

When enabled, 'InnoDB' monitors print data about every 15 seconds.  This
data is useful in performance tuning.  As a side effect, the output of
'SHOW ENGINE INNODB STATUS' is written to a status
file in the MySQL data directory every fifteen seconds.  The name of the
file is 'innodb_status.PID', where PID is the server process ID.
'InnoDB' removes the file when the server is shut down normally.  If
abnormal shutdowns have occurred, instances of these status files may be
present and must be removed manually.  Before removing the files,
examine them to see if they contain useful information about the cause
of abnormal shutdowns.  An 'innodb_status.PID' file is only created if
the 'innodb-status-file' configuration option is enabled.  It is
disabled by default.

'InnoDB' monitors should only be enabled when you actually want to see
monitor information because output generation causes some performance
decrement.  Also, if monitor output is directed to the error log, the
log may become quite large if you forget to disable the monitor later.

*Note*:

To assist with troubleshooting, 'InnoDB' temporarily enables standard
'InnoDB' Monitor output under certain conditions.  For more information,
see innodb-troubleshooting.

'InnoDB' monitor output begins with a header containing a timestamp and
the monitor name.  For example:

     =====================================
     2014-10-16 18:37:29 0x7fc2a95c1700 INNODB MONITOR OUTPUT
     =====================================

The header for the standard 'InnoDB' Monitor ('INNODB MONITOR OUTPUT')
is also used for the Lock Monitor because the latter produces the same
output with the addition of extra lock information.

The 'innodb_status_output' and 'innodb_status_output_locks' system
variables are used to enable the standard 'InnoDB' Monitor and 'InnoDB'
Lock Monitor.

The 'PROCESS' privilege is required to enable or disable 'InnoDB'
Monitors.

*Enabling the Standard InnoDB Monitor*

Enable the standard 'InnoDB' Monitor by setting the
'innodb_status_output' system variable to 'ON'.

     SET GLOBAL innodb_status_output=ON;

To disable the standard 'InnoDB' Monitor, set 'innodb_status_output' to
'OFF'.

When you shut down the server, the 'innodb_status_output' variable is
set to the default 'OFF' value.

*Obtaining Standard InnoDB Monitor Output On Demand*

As an alternative to enabling the standard 'InnoDB' Monitor for periodic
output, you can obtain standard 'InnoDB' Monitor output on demand using
the 'SHOW ENGINE INNODB STATUS'. SQL statement, which
fetches the output to your client program.  If you are using the
'mysql' interactive client, the output is more readable if you
replace the usual semicolon statement terminator with '\G':

     mysql> SHOW ENGINE INNODB STATUS\G

'SHOW ENGINE INNODB STATUS' output also includes
'InnoDB' Lock Monitor data if the 'InnoDB' Lock Monitor is enabled.

*Enabling the InnoDB Lock Monitor*

'InnoDB' Lock Monitor data is printed with the 'InnoDB' Standard Monitor
output.  Both the 'InnoDB' Standard Monitor and 'InnoDB' Lock Monitor
must be enabled to have 'InnoDB' Lock Monitor data printed periodically.

To enable the 'InnoDB' Lock Monitor, set the
'innodb_status_output_locks' system variable to 'ON'.  Both the 'InnoDB'
standard Monitor and 'InnoDB' Lock Monitor must be enabled to have
'InnoDB' Lock Monitor data printed periodically:

     SET GLOBAL innodb_status_output=ON;
     SET GLOBAL innodb_status_output_locks=ON;

To disable the 'InnoDB' Lock Monitor, set 'innodb_status_output_locks'
to 'OFF'.  Set 'innodb_status_output' to 'OFF' to also disable the
'InnoDB' Standard Monitor.

When you shut down the server, the 'innodb_status_output' and
'innodb_status_output_locks' variables are set to the default 'OFF'
value.

*Note*:

To enable the 'InnoDB' Lock Monitor for 'SHOW ENGINE INNODB STATUS'
output, you are only required to enable
'innodb_status_output_locks'.

14.17.3 InnoDB Standard Monitor and Lock Monitor Output
-------------------------------------------------------

The Lock Monitor is the same as the Standard Monitor except that it
includes additional lock information.  Enabling either monitor for
periodic output turns on the same output stream, but the stream includes
extra information if the Lock Monitor is enabled.  For example, if you
enable the Standard Monitor and Lock Monitor, that turns on a single
output stream.  The stream includes extra lock information until you
disable the Lock Monitor.

Standard Monitor output is limited to 1MB when produced using the
'SHOW ENGINE INNODB STATUS' statement.  This limit does
not apply to output written to tserver standard error output ('stderr').

Example Standard Monitor output:

     mysql> SHOW ENGINE INNODB STATUS\G
     *************************** 1. row ***************************
       Type: InnoDB
       Name:
     Status:
     =====================================
     2014-10-16 18:37:29 0x7fc2a95c1700 INNODB MONITOR OUTPUT
     =====================================
     Per second averages calculated from the last 20 seconds
     -----------------
     BACKGROUND THREAD
     -----------------
     srv_master_thread loops: 38 srv_active, 0 srv_shutdown, 252 srv_idle
     srv_master_thread log flush and writes: 290
     ----------
     SEMAPHORES
     ----------
     OS WAIT ARRAY INFO: reservation count 119
     OS WAIT ARRAY INFO: signal count 103
     Mutex spin waits 0, rounds 0, OS waits 0
     RW-shared spins 38, rounds 76, OS waits 38
     RW-excl spins 2, rounds 9383715, OS waits 3
     RW-sx spins 0, rounds 0, OS waits 0
     Spin rounds per wait: 0.00 mutex, 2.00 RW-shared, 4691857.50 RW-excl,
     0.00 RW-sx
     ------------------------
     LATEST FOREIGN KEY ERROR
     ------------------------
     2014-10-16 18:35:18 0x7fc2a95c1700 Transaction:
     TRANSACTION 1814, ACTIVE 0 sec inserting
     mysql tables in use 1, locked 1
     4 lock struct(s), heap size 1136, 3 row lock(s), undo log entries 3
     MySQL thread id 2, OS thread handle 140474041767680, query id 74 localhost
     root update
     INSERT INTO child VALUES
         (NULL, 1)
         , (NULL, 2)
         , (NULL, 3)
         , (NULL, 4)
         , (NULL, 5)
         , (NULL, 6)
     Foreign key constraint fails for table `mysql`.`child`:
     ,
       CONSTRAINT `child_ibfk_1` FOREIGN KEY (`parent_id`) REFERENCES `parent`
       (`id`) ON DELETE CASCADE ON UPDATE CASCADE
     Trying to add in child table, in index par_ind tuple:
     DATA TUPLE: 2 fields;
      0: len 4; hex 80000003; asc     ;;
      1: len 4; hex 80000003; asc     ;;

     But in parent table `mysql`.`parent`, in index PRIMARY,
     the closest match we can find is record:
     PHYSICAL RECORD: n_fields 3; compact format; info bits 0
      0: len 4; hex 80000004; asc     ;;
      1: len 6; hex 00000000070a; asc       ;;
      2: len 7; hex aa0000011d0134; asc       4;;

     ------------------------
     LATEST DETECTED DEADLOCK
     ------------------------
     2014-10-16 18:36:30 0x7fc2a95c1700
     *** (1) TRANSACTION:
     TRANSACTION 1824, ACTIVE 9 sec starting index read
     mysql tables in use 1, locked 1
     LOCK WAIT 2 lock struct(s), heap size 1136, 1 row lock(s)
     MySQL thread id 3, OS thread handle 140474041501440, query id 80 localhost
     root updating
     DELETE FROM t WHERE i = 1
     *** (1) WAITING FOR THIS LOCK TO BE GRANTED:
     RECORD LOCKS space id 35 page no 3 n bits 72 index GEN_CLUST_INDEX of table
     `mysql`.`t` trx id 1824 lock_mode X waiting
     Record lock, heap no 2 PHYSICAL RECORD: n_fields 4; compact format; info
     bits 0
      0: len 6; hex 000000000200; asc       ;;
      1: len 6; hex 00000000071f; asc       ;;
      2: len 7; hex b80000012b0110; asc     +  ;;
      3: len 4; hex 80000001; asc     ;;

     *** (2) TRANSACTION:
     TRANSACTION 1825, ACTIVE 29 sec starting index read
     mysql tables in use 1, locked 1
     4 lock struct(s), heap size 1136, 3 row lock(s)
     MySQL thread id 2, OS thread handle 140474041767680, query id 81 localhost
     root updating
     DELETE FROM t WHERE i = 1
     *** (2) HOLDS THE LOCK(S):
     RECORD LOCKS space id 35 page no 3 n bits 72 index GEN_CLUST_INDEX of table
     `mysql`.`t` trx id 1825 lock mode S
     Record lock, heap no 1 PHYSICAL RECORD: n_fields 1; compact format; info
     bits 0
      0: len 8; hex 73757072656d756d; asc supremum;;

     Record lock, heap no 2 PHYSICAL RECORD: n_fields 4; compact format; info bits 0
      0: len 6; hex 000000000200; asc       ;;
      1: len 6; hex 00000000071f; asc       ;;
      2: len 7; hex b80000012b0110; asc     +  ;;
      3: len 4; hex 80000001; asc     ;;

     *** (2) WAITING FOR THIS LOCK TO BE GRANTED:
     RECORD LOCKS space id 35 page no 3 n bits 72 index GEN_CLUST_INDEX of table
     `mysql`.`t` trx id 1825 lock_mode X waiting
     Record lock, heap no 2 PHYSICAL RECORD: n_fields 4; compact format; info
     bits 0
      0: len 6; hex 000000000200; asc       ;;
      1: len 6; hex 00000000071f; asc       ;;
      2: len 7; hex b80000012b0110; asc     +  ;;
      3: len 4; hex 80000001; asc     ;;

     *** WE ROLL BACK TRANSACTION (1)
     ------------
     TRANSACTIONS
     ------------
     Trx id counter 1950
     Purge done for trx's n:o < 1933 undo n:o < 0 state: running but idle
     History list length 23
     LIST OF TRANSACTIONS FOR EACH SESSION:
     ---TRANSACTION 421949033065200, not started
     0 lock struct(s), heap size 1136, 0 row lock(s)
     ---TRANSACTION 421949033064280, not started
     0 lock struct(s), heap size 1136, 0 row lock(s)
     ---TRANSACTION 1949, ACTIVE 0 sec inserting
     mysql tables in use 1, locked 1
     8 lock struct(s), heap size 1136, 1850 row lock(s), undo log entries 17415
     MySQL thread id 4, OS thread handle 140474041235200, query id 176 localhost
     root update
     INSERT INTO `salaries` VALUES (55723,39746,'1997-02-25','1998-02-25'),
     (55723,40758,'1998-02-25','1999-02-25'),(55723,44559,'1999-02-25','2000-02-25'),
     (55723,44081,'2000-02-25','2001-02-24'),(55723,44112,'2001-02-24','2001-08-16'),
     (55724,46461,'1996-12-06','1997-12-06'),(55724,48916,'1997-12-06','1998-12-06'),
     (55724,51269,'1998-12-06','1999-12-06'),(55724,51932,'1999-12-06','2000-12-05'),
     (55724,52617,'2000-12-05','2001-12-05'),(55724,56658,'2001-12-05','9999-01-01'),
     (55725,40000,'1993-01-30','1994-01-30'),(55725,41472,'1994-01-30','1995-01-30'),
     (55725,45293,'1995-01-30','1996-01-30'),(55725,473
     --------
     FILE I/O
     --------
     I/O thread 0 state: waiting for completed aio requests (insert buffer thread)
     I/O thread 1 state: waiting for completed aio requests (log thread)
     I/O thread 2 state: waiting for completed aio requests (read thread)
     I/O thread 3 state: waiting for completed aio requests (read thread)
     I/O thread 4 state: waiting for completed aio requests (read thread)
     I/O thread 5 state: waiting for completed aio requests (read thread)
     I/O thread 6 state: waiting for completed aio requests (write thread)
     I/O thread 7 state: waiting for completed aio requests (write thread)
     I/O thread 8 state: waiting for completed aio requests (write thread)
     I/O thread 9 state: waiting for completed aio requests (write thread)
     Pending normal aio reads: 0 [0, 0, 0, 0] , aio writes: 0 [0, 0, 0, 0] ,
      ibuf aio reads: 0, log i/o's: 0, sync i/o's: 0
     Pending flushes (fsync) log: 0; buffer pool: 0
     224 OS file reads, 5770 OS file writes, 803 OS fsyncs
     0.00 reads/s, 0 avg bytes/read, 264.84 writes/s, 23.05 fsyncs/s
     -------------------------------------
     INSERT BUFFER AND ADAPTIVE HASH INDEX
     -------------------------------------
     Ibuf: size 1, free list len 0, seg size 2, 0 merges
     merged operations:
      insert 0, delete mark 0, delete 0
     discarded operations:
      insert 0, delete mark 0, delete 0
     Hash table size 4425293, node heap has 444 buffer(s)
     68015.25 hash searches/s, 106259.24 non-hash searches/s
     ---
     LOG
     ---
     Log sequence number 165913808
     Log flushed up to   164814979
     Pages flushed up to 141544038
     Last checkpoint at  130503656
     0 pending log flushes, 0 pending chkp writes
     258 log i/o's done, 6.65 log i/o's/second
     ----------------------
     BUFFER POOL AND MEMORY
     ----------------------
     Total large memory allocated 2198863872
     Dictionary memory allocated 776332
     Buffer pool size   131072
     Free buffers       124908
     Database pages     5720
     Old database pages 2071
     Modified db pages  910
     Pending reads 0
     Pending writes: LRU 0, flush list 0, single page 0
     Pages made young 4, not young 0
     0.10 youngs/s, 0.00 non-youngs/s
     Pages read 197, created 5523, written 5060
     0.00 reads/s, 190.89 creates/s, 244.94 writes/s
     Buffer pool hit rate 1000 / 1000, young-making rate 0 / 1000 not
     0 / 1000
     Pages read ahead 0.00/s, evicted without access 0.00/s, Random read
     ahead 0.00/s
     LRU len: 5720, unzip_LRU len: 0
     I/O sum[0]:cur[0], unzip sum[0]:cur[0]
     ----------------------
     INDIVIDUAL BUFFER POOL INFO
     ----------------------
     ---BUFFER POOL 0
     Buffer pool size   65536
     Free buffers       62412
     Database pages     2899
     Old database pages 1050
     Modified db pages  449
     Pending reads 0
     Pending writes: LRU 0, flush list 0, single page 0
     Pages made young 3, not young 0
     0.05 youngs/s, 0.00 non-youngs/s
     Pages read 107, created 2792, written 2586
     0.00 reads/s, 92.65 creates/s, 122.89 writes/s
     Buffer pool hit rate 1000 / 1000, young-making rate 0 / 1000 not 0 / 1000
     Pages read ahead 0.00/s, evicted without access 0.00/s, Random read ahead
     0.00/s
     LRU len: 2899, unzip_LRU len: 0
     I/O sum[0]:cur[0], unzip sum[0]:cur[0]
     ---BUFFER POOL 1
     Buffer pool size   65536
     Free buffers       62496
     Database pages     2821
     Old database pages 1021
     Modified db pages  461
     Pending reads 0
     Pending writes: LRU 0, flush list 0, single page 0
     Pages made young 1, not young 0
     0.05 youngs/s, 0.00 non-youngs/s
     Pages read 90, created 2731, written 2474
     0.00 reads/s, 98.25 creates/s, 122.04 writes/s
     Buffer pool hit rate 1000 / 1000, young-making rate 0 / 1000 not 0 / 1000
     Pages read ahead 0.00/s, evicted without access 0.00/s, Random read ahead
     0.00/s
     LRU len: 2821, unzip_LRU len: 0
     I/O sum[0]:cur[0], unzip sum[0]:cur[0]
     --------------
     ROW OPERATIONS
     --------------
     0 queries inside InnoDB, 0 queries in queue
     0 read views open inside InnoDB
     Process ID=35909, Main thread ID=140471692396288, state: sleeping
     Number of rows inserted 1526363, updated 0, deleted 3, read 11
     52671.72 inserts/s, 0.00 updates/s, 0.00 deletes/s, 0.00 reads/s
     ----------------------------
     END OF INNODB MONITOR OUTPUT
     ============================

*Standard Monitor Output Sections*

For a description of each metric reported by the Standard Monitor, refer
to the Metrics
(http://dev.mysql.com/doc/mysql-em-plugin/en/myoem-metrics.html) chapter
in the Oracle Enterprise Manager for MySQL Database User's Guide
(http://dev.mysql.com/doc/mysql-em-plugin/en/).

   * 'Status'

     This section shows the timestamp, the monitor name, and the number
     of seconds that per-second averages are based on.  The number of
     seconds is the elapsed time between the current time and the last
     time 'InnoDB' Monitor output was printed.

   * 'BACKGROUND THREAD'

     The 'srv_master_thread' lines shows work done by the main
     background thread.

   * 'SEMAPHORES'

     This section reports threads waiting for a semaphore and statistics
     on how many times threads have needed a spin or a wait on a mutex
     or a rw-lock semaphore.  A large number of threads waiting for
     semaphores may be a result of disk I/O, or contention problems
     inside 'InnoDB'.  Contention can be due to heavy parallelism of
     queries or problems in operating system thread scheduling.  Setting
     the 'innodb_thread_concurrency' system variable smaller than the
     default value might help in such situations.  The 'Spin rounds per
     wait' line shows the number of spinlock rounds per OS wait for a
     mutex.

     Mutex metrics are reported by 'SHOW ENGINE INNODB MUTEX'.

   * 'LATEST FOREIGN KEY ERROR'

     This section provides information about the most recent foreign key
     constraint error.  It is not present if no such error has occurred.
     The contents include the statement that failed as well as
     information about the constraint that failed and the referenced and
     referencing tables.

   * 'LATEST DETECTED DEADLOCK'

     This section provides information about the most recent deadlock.
     It is not present if no deadlock has occurred.  The contents show
     which transactions are involved, the statement each was attempting
     to execute, the locks they have and need, and which transaction
     'InnoDB' decided to roll back to break the deadlock.  The lock
     modes reported in this section are explained in
     innodb-locking.

   * 'TRANSACTIONS'

     If this section reports lock waits, your applications might have
     lock contention.  The output can also help to trace the reasons for
     transaction deadlocks.

   * 'FILE I/O'

     This section provides information about threads that 'InnoDB' uses
     to perform various types of I/O. The first few of these are
     dedicated to general 'InnoDB' processing.  The contents also
     display information for pending I/O operations and statistics for
     I/O performance.

     The number of these threads are controlled by the
     'innodb_read_io_threads' and 'innodb_write_io_threads' parameters.
     See innodb-parameters.

   * 'INSERT BUFFER AND ADAPTIVE HASH INDEX'

     This section shows the status of the 'InnoDB' insert buffer (also
     referred to as the change buffer) and the adaptive hash index.

     For related information, see innodb-insert-buffering, and
     innodb-adaptive-hash.

   * 'LOG'

     This section displays information about the 'InnoDB' log.  The
     contents include the current log sequence number, how far the log
     has been flushed to disk, and the position at which 'InnoDB' last
     took a checkpoint.  (See innodb-checkpoints.)  The section
     also displays information about pending writes and write
     performance statistics.

   * 'BUFFER POOL AND MEMORY'

     This section gives you statistics on pages read and written.  You
     can calculate from these numbers how many data file I/O operations
     your queries currently are doing.

     For buffer pool statistics descriptions, see
     innodb-buffer-pool-monitoring.  For additional information about
     the operation of the buffer pool, see innodb-buffer-pool.

   * 'ROW OPERATIONS'

     This section shows what the main thread is doing, including the
     number and performance rate for each type of row operation.

14.18 InnoDB Backup and Recovery
================================

This section covers topics related to 'InnoDB' backup and recovery.

   * For information about backup techniques applicable to 'InnoDB', see
     innodb-backup.

   * For information about point-in-time recovery, recovery from disk
     failure or corruption, and how 'InnoDB' performs crash recovery,
     see innodb-recovery.

14.18.1 InnoDB Backup
---------------------

The key to safe database management is making regular backups.
Depending on your data volume, number of MySQL servers, and database
workload, you can use these backup techniques, alone or in combination:
hot backup with MySQL Enterprise Backup; cold backup by copying files
while the MySQL server is shut down; logical backup with
'mysqldump' for smaller data volumes or to record the
structure of schema objects.  Hot and cold backups are physical backups
that copy actual data files, which can be used directly by the
'mysqld' server for faster restore.

Using _MySQL Enterprise Backup_ is the recommended method for backing up
'InnoDB' data.

*Note*:

'InnoDB' does not support databases that are restored using third-party
backup tools.

*Hot Backups*

The 'mysqlbackup' command, part of the MySQL Enterprise Backup
component, lets you back up a running MySQL instance, including 'InnoDB'
tables, with minimal disruption to operations while producing a
consistent snapshot of the database.  When 'mysqlbackup' is copying
'InnoDB' tables, reads and writes to 'InnoDB' tables can continue.
MySQL Enterprise Backup can also create compressed backup files, and
back up subsets of tables and databases.  In conjunction with the MySQL
binary log, users can perform point-in-time recovery.  MySQL Enterprise
Backup is part of the MySQL Enterprise subscription.  For more details,
see mysql-enterprise-backup.

*Cold Backups*

If you can shut down the MySQL server, you can make a physical backup
that consists of all files used by 'InnoDB' to manage its tables.  Use
the following procedure:

  1. Perform a slow shutdown of the MySQL server and make sure that it
     stops without errors.

  2. Copy all 'InnoDB' data files ('ibdata' files and '.ibd' files) into
     a safe place.

  3. Copy all the '.frm' files for 'InnoDB' tables to a safe place.

  4. Copy all 'InnoDB' log files ('ib_logfile' files) to a safe place.

  5. Copy your 'my.cnf' configuration file or files to a safe place.

*Logical Backups Using mysqldump*

In addition to physical backups, it is recommended that you regularly
create logical backups by dumping your tables using 'mysqldump'.
A binary file might be corrupted without you noticing it.
Dumped tables are stored into text files that are human-readable, so
spotting table corruption becomes easier.  Also, because the format is
simpler, the chance for serious data corruption is smaller.
'mysqldump' also has a '--single-transaction' option for
making a consistent snapshot without locking out other clients.  See
backup-policy.

Replication works with 'InnoDB' tables, so
you can use MySQL replication capabilities to keep a copy of your
database at database sites requiring high availability.  See
innodb-and-mysql-replication.

14.18.2 InnoDB Recovery
-----------------------

This section describes 'InnoDB' recovery.  Topics include:

   * innodb-recovery-point-in-time

   * innodb-corruption-disk-failure-recovery

   * innodb-crash-recovery

   * innodb-recovery-tablespace-discovery

*Point-in-Time Recovery*

To recover an 'InnoDB' database to the present from the time at which
the physical backup was made, you must run MySQL server with binary
logging enabled, even before taking the backup.  To achieve
point-in-time recovery after restoring a backup, you can apply changes
from the binary log that occurred after the backup was made.  See
point-in-time-recovery.

*Recovery from Data Corruption or Disk Failure*

If your database becomes corrupted or disk failure occurs, you must
perform the recovery using a backup.  In the case of corruption, first
find a backup that is not corrupted.  After restoring the base backup,
do a point-in-time recovery from the binary log files using
'mysqlbinlog' and 'mysql' to restore the
changes that occurred after the backup was made.

In some cases of database corruption, it is enough to dump, drop, and
re-create one or a few corrupt tables.  You can use the 'CHECK TABLE'
statement to check whether a table is corrupt,
although 'CHECK TABLE' naturally cannot detect every
possible kind of corruption.

In some cases, apparent database page corruption is actually due to the
operating system corrupting its own file cache, and the data on disk may
be okay.  It is best to try restarting the computer first.  Doing so may
eliminate errors that appeared to be database page corruption.  If MySQL
still has trouble starting because of 'InnoDB' consistency problems, see
forcing-innodb-recovery for steps to start the instance in
recovery mode, which permits you to dump the data.

*InnoDB Crash Recovery*

To recover from a MySQL server crash, the only requirement is to restart
the MySQL server.  'InnoDB' automatically checks the logs and performs a
roll-forward of the database to the present.  'InnoDB' automatically
rolls back uncommitted transactions that were present at the time of the
crash.  During recovery, see 'mysqld' displays output similar
to this:

     InnoDB: Log scan progressed past the checkpoint lsn 369163704
     InnoDB: Doing recovery: scanned up to log sequence number 374340608
     InnoDB: Doing recovery: scanned up to log sequence number 379583488
     InnoDB: Doing recovery: scanned up to log sequence number 384826368
     InnoDB: Doing recovery: scanned up to log sequence number 390069248
     InnoDB: Doing recovery: scanned up to log sequence number 395312128
     InnoDB: Doing recovery: scanned up to log sequence number 400555008
     InnoDB: Doing recovery: scanned up to log sequence number 405797888
     InnoDB: Doing recovery: scanned up to log sequence number 411040768
     InnoDB: Doing recovery: scanned up to log sequence number 414724794
     InnoDB: Database was not shutdown normally!
     InnoDB: Starting crash recovery.
     InnoDB: 1 transaction(s) which must be rolled back or cleaned up in
     total 518425 row operations to undo
     InnoDB: Trx id counter is 1792
     InnoDB: Starting an apply batch of log records to the database...
     InnoDB: Progress in percent: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
     16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
     38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
     60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
     82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
     InnoDB: Apply batch completed
     ...
     InnoDB: Starting in background the rollback of uncommitted transactions
     InnoDB: Rolling back trx with id 1511, 518425 rows to undo
     ...
     InnoDB: Waiting for purge to start
     InnoDB: 5.7.18 started; log sequence number 414724794
     ...
     ./mysqld: ready for connections.

'InnoDB' crash recovery consists of several steps:

   * Tablespace discovery

     Tablespace discovery is the process that 'InnoDB' uses to identify
     tablespaces that require redo log application.  See
     innodb-recovery-tablespace-discovery.

   * Redo log application

     Redo log application is performed during initialization, before
     accepting any connections.  If all changes are flushed from the
     buffer pool to the tablespaces ('ibdata*' and '*.ibd' files) at the
     time of the shutdown or crash, redo log application is skipped.
     'InnoDB' also skips redo log application if redo log files are
     missing at startup.

     Removing redo logs to speed up recovery is not recommended, even if
     some data loss is acceptable.  Removing redo logs should only be
     considered after a clean shutdown, with 'innodb_fast_shutdown' set
     to '0' or '1'.

     For information about the process that 'InnoDB' uses to identify
     tablespaces that require redo log application, see
     innodb-recovery-tablespace-discovery.

   * Roll back of incomplete transactions

     Incomplete transactions are any transactions that were active at
     the time of crash or fast shutdown.  The time it takes to roll back
     an incomplete transaction can be three or four times the amount of
     time a transaction is active before it is interrupted, depending on
     server load.

     You cannot cancel transactions that are being rolled back.  In
     extreme cases, when rolling back transactions is expected to take
     an exceptionally long time, it may be faster to start 'InnoDB' with
     an 'innodb_force_recovery' setting of '3' or greater.  See
     forcing-innodb-recovery.

   * Change buffer merge

     Applying changes from the change buffer (part of the system
     tablespace) to leaf pages of secondary indexes, as the index pages
     are read to the buffer pool.

   * Purge

     Deleting delete-marked records that are no longer visible to active
     transactions.

The steps that follow redo log application do not depend on the redo log
(other than for logging the writes) and are performed in parallel with
normal processing.  Of these, only rollback of incomplete transactions
is special to crash recovery.  The insert buffer merge and the purge are
performed during normal processing.

After redo log application, 'InnoDB' attempts to accept connections as
early as possible, to reduce downtime.  As part of crash recovery,
'InnoDB' rolls back transactions that were not committed or in 'XA
PREPARE' state when the server crashed.  The rollback is performed by a
background thread, executed in parallel with transactions from new
connections.  Until the rollback operation is completed, new connections
may encounter locking conflicts with recovered transactions.

In most situations, even if the MySQL server was killed unexpectedly in
the middle of heavy activity, the recovery process happens automatically
and no action is required of the DBA. If a hardware failure or severe
system error corrupted 'InnoDB' data, MySQL might refuse to start.  In
this case, see forcing-innodb-recovery.

For information about the binary log and 'InnoDB' crash recovery, see
binary-log.

*Tablespace Discovery During Crash Recovery*

If, during recovery, 'InnoDB' encounters redo logs written since the
last checkpoint, the redo logs must be applied to affected tablespaces.
The process that identifies affected tablespaces during recovery is
referred to as _tablespace discovery_.

Tablespace discovery is performed by scanning redo logs from the last
checkpoint to the end of the log for 'MLOG_FILE_NAME' records that are
written when a tablespace page is modified.  An 'MLOG_FILE_NAME' record
contains the tablespace space ID and file name.

On startup, 'InnoDB' opens the system tablespace and redo log.  If there
are redo log records written since the last checkpoint, affected
tablespace files are opened based on 'MLOG_FILE_NAME' records.

'MLOG_FILE_NAME' records are written for all persistent tablespace types
including file-per-table tablespaces, general tablespaces, the system
tablespace, and undo log tablespaces.

Redo-log-based discovery has the following characteristics:

   * Only tablespace '*.ibd' files modified since the last checkpoint
     are accessed.

   * Tablespace '*.ibd' files that are not attached to the 'InnoDB'
     instance are ignored when redo logs are applied.

   * If 'MLOG_FILE_NAME' records for the system tablespace do not match
     the server configuration affecting system tablespace data file
     names, recovery fails with an error before redo logs are applied.

   * If tablespace files referenced in the scanned portion of the log
     are missing, startup is refused.

   * Redo logs for missing tablespace '*.ibd' files are only disregarded
     if there is a file-delete redo log record ('MLOG_FILE_DELETE') in
     the log.  For example, a table rename failure could result in a
     'missing' '*.ibd' file without an 'MLOG_FILE_DELETE' record.  In
     this case, you could manually rename the tablespace file and
     restart crash recovery, or you could restart the server in recovery
     mode using the 'innodb_force_recovery' option.  Missing '*.ibd'
     files are ignored when the server is started in recovery mode.

Redo-log-based discovery, introduced in MySQL 5.7, replaces directory
scans that were used in earlier MySQL releases to construct a 'space
ID-to-tablespace file name' map that was required to apply redo logs.

14.19 InnoDB and MySQL Replication
==================================

MySQL replication works for 'InnoDB' tables as it does for 'MyISAM'
tables.  It is also possible to use replication in a way where the
storage engine on the slave is not the same as the original storage
engine on the master.  For example, you can replicate modifications to
an 'InnoDB' table on the master to a 'MyISAM' table on the slave.  For
more information see, see replication-solutions-diffengines.

For information about setting up a new slave for a master, see
replication-setup-slaves, and replication-snapshot-method.  To
make a new slave without taking down the master or an existing slave,
use the MySQL Enterprise Backup product.

Transactions that fail on the master do not affect replication at all.
MySQL replication is based on the binary log where MySQL writes SQL
statements that modify data.  A transaction that fails (for example,
because of a foreign key violation, or because it is rolled back) is not
written to the binary log, so it is not sent to slaves.  See
commit.

Replication and CASCADE

Cascading actions for 'InnoDB' tables on the master are replicated on
the slave _only_ if the tables sharing the foreign key relation use
'InnoDB' on both the master and slave.  This is true whether you are
using statement-based or row-based replication.  Suppose that you have
started replication, and then create two tables on the master using the
following 'CREATE TABLE' statements:

     CREATE TABLE fc1 (
         i INT PRIMARY KEY,
         j INT
     ) ENGINE = InnoDB;

     CREATE TABLE fc2 (
         m INT PRIMARY KEY,
         n INT,
         FOREIGN KEY ni (n) REFERENCES fc1 (i)
             ON DELETE CASCADE
     ) ENGINE = InnoDB;

Suppose that the slave does not have 'InnoDB' support enabled.  If this
is the case, then the tables on the slave are created, but they use the
'MyISAM' storage engine, and the 'FOREIGN KEY' option is ignored.  Now
we insert some rows into the tables on the master:

     master> INSERT INTO fc1 VALUES (1, 1), (2, 2);
     Query OK, 2 rows affected (0.09 sec)
     Records: 2  Duplicates: 0  Warnings: 0

     master> INSERT INTO fc2 VALUES (1, 1), (2, 2), (3, 1);
     Query OK, 3 rows affected (0.19 sec)
     Records: 3  Duplicates: 0  Warnings: 0

At this point, on both the master and the slave, table 'fc1' contains 2
rows, and table 'fc2' contains 3 rows, as shown here:

     master> SELECT * FROM fc1;
     +---+------+
     | i | j    |
     +---+------+
     | 1 |    1 |
     | 2 |    2 |
     +---+------+
     2 rows in set (0.00 sec)

     master> SELECT * FROM fc2;
     +---+------+
     | m | n    |
     +---+------+
     | 1 |    1 |
     | 2 |    2 |
     | 3 |    1 |
     +---+------+
     3 rows in set (0.00 sec)

     slave> SELECT * FROM fc1;
     +---+------+
     | i | j    |
     +---+------+
     | 1 |    1 |
     | 2 |    2 |
     +---+------+
     2 rows in set (0.00 sec)

     slave> SELECT * FROM fc2;
     +---+------+
     | m | n    |
     +---+------+
     | 1 |    1 |
     | 2 |    2 |
     | 3 |    1 |
     +---+------+
     3 rows in set (0.00 sec)

Now suppose that you perform the following 'DELETE'.
statement on the master:

     master> DELETE FROM fc1 WHERE i=1;
     Query OK, 1 row affected (0.09 sec)

Due to the cascade, table 'fc2' on the master now contains only 1 row:

     master> SELECT * FROM fc2;
     +---+---+
     | m | n |
     +---+---+
     | 2 | 2 |
     +---+---+
     1 row in set (0.00 sec)

However, the cascade does not propagate on the slave because on the
slave the 'DELETE' for 'fc1' deletes no rows from 'fc2'.
The slave's copy of 'fc2' still contains all of the rows that were
originally inserted:

     slave> SELECT * FROM fc2;
     +---+---+
     | m | n |
     +---+---+
     | 1 | 1 |
     | 3 | 1 |
     | 2 | 2 |
     +---+---+
     3 rows in set (0.00 sec)

This difference is due to the fact that the cascading deletes are
handled internally by the 'InnoDB' storage engine, which means that none
of the changes are logged.

14.20 InnoDB memcached Plugin
=============================

The 'InnoDB' 'memcached' plugin ('daemon_memcached') provides an
integrated 'memcached' daemon that automatically stores and retrieves
data from 'InnoDB' tables, turning the MySQL server into a fast
'key-value store'.  Instead of formulating queries in SQL, you can use
simple 'get', 'set', and 'incr' operations that avoid the performance
overhead associated with SQL parsing and constructing a query
optimization plan.  You can also access the same 'InnoDB' tables through
SQL for convenience, complex queries, bulk operations, and other
strengths of traditional database software.

This 'NoSQL-style' interface uses the 'memcached' API to speed up
database operations, letting 'InnoDB' handle memory caching using its
buffer pool mechanism.  Data modified through 'memcached' operations
such as 'add', 'set', and 'incr' are stored to disk, in 'InnoDB' tables.
The combination of 'memcached' simplicity and 'InnoDB' reliability and
consistency provides users with the best of both worlds, as explained in
innodb-memcached-benefits.  For an architectural overview, see
innodb-memcached-intro.

14.20.1 Benefits of the InnoDB memcached Plugin
-----------------------------------------------

This section outlines advantages the 'daemon_memcached' plugin.  The
combination of 'InnoDB' tables and 'memcached' offers advantages over
using either by themselves.

   * Direct access to the 'InnoDB' storage engine avoids the parsing and
     planning overhead of SQL.

   * Running 'memcached' in the same process space as the MySQL server
     avoids the network overhead of passing requests back and forth.

   * Data written using the 'memcached' protocol is transparently
     written to an 'InnoDB' table, without going through the MySQL SQL
     layer.  You can control frequency of writes to achieve higher raw
     performance when updating non-critical data.

   * Data requested through the 'memcached' protocol is transparently
     queried from an 'InnoDB' table, without going through the MySQL SQL
     layer.

   * Subsequent requests for the same data is served from the 'InnoDB'
     buffer pool.  The buffer pool handles the in-memory caching.  You
     can tune performance of data-intensive operations using 'InnoDB'
     configuration options.

   * Data can be unstructured or structured, depending on the type of
     application.  You can create a new table for data, or use existing
     tables.

   * 'InnoDB' can handle composing and decomposing multiple column
     values into a single 'memcached' item value, reducing the amount of
     string parsing and concatenation required in your application.  For
     example, you can store the string value '2|4|6|8' in the
     'memcached' cache, and have 'InnoDB' split the value based on a
     separator character, then store the result in four numeric columns.

   * The transfer between memory and disk is handled automatically,
     simplifying application logic.

   * Data is stored in a MySQL database to protect against crashes,
     outages, and corruption.

   * You can access the underlying 'InnoDB' table through SQL for
     reporting, analysis, ad hoc queries, bulk loading, multi-step
     transactional computations, set operations such as union and
     intersection, and other operations suited to the expressiveness and
     flexibility of SQL.

   * You can ensure high availability by using the 'daemon_memcached'
     plugin on a master server in combination with MySQL replication.

   * The integration of 'memcached' with MySQL provides a way to make
     in-memory data persistent, so you can use it for more significant
     kinds of data.  You can use more 'add', 'incr', and similar write
     operations in your application without concern that data could be
     lost.  You can stop and start the 'memcached' server without losing
     updates made to cached data.  To guard against unexpected outages,
     you can take advantage of 'InnoDB' crash recovery, replication, and
     backup capabilities.

   * The way 'InnoDB' does fast primary key lookups is a natural fit for
     'memcached' single-item queries.  The direct, low-level database
     access path used by the 'daemon_memcached' plugin is much more
     efficient for key-value lookups than equivalent SQL queries.

   * The serialization features of 'memcached', which can turn complex
     data structures, binary files, or even code blocks into storeable
     strings, offer a simple way to get such objects into a database.

   * Because you can access the underlying data through SQL, you can
     produce reports, search or update across multiple keys, and call
     functions such as 'AVG()' and 'MAX()' on 'memcached' data.  All of
     these operations are expensive or complicated using 'memcached' by
     itself.

   * You do not need to manually load data into 'memcached' at startup.
     As particular keys are requested by an application, values are
     retrieved from the database automatically, and cached in memory
     using the 'InnoDB' buffer pool.

   * Because 'memcached' consumes relatively little CPU, and its memory
     footprint is easy to control, it can run comfortably alongside a
     MySQL instance on the same system.

   * Because data consistency is enforced by mechanisms used for regular
     'InnoDB' tables, you do not have to worry about stale 'memcached'
     data or fallback logic to query the database in the case of a
     missing key.

14.20.2 InnoDB memcached Architecture
-------------------------------------

The 'InnoDB' 'memcached' plugin implements 'memcached' as a MySQL plugin
daemon that accesses the 'InnoDB' storage engine directly, bypassing the
MySQL SQL layer.

The following diagram illustrates how an application accesses data
through the 'daemon_memcached' plugin, compared with SQL.

FIGURE GOES HERE: MySQL Server with Integrated 'memcached' Server

Features of the 'daemon_memcached' plugin:

   * 'memcached' as a daemon plugin of 'mysqld'.  Both
     'mysqld' and 'memcached' run in the same process
     space, with very low latency access to data.

   * Direct access to 'InnoDB' tables, bypassing the SQL parser, the
     optimizer, and even the Handler API layer.

   * Standard 'memcached' protocols, including the text-based protocol
     and the binary protocol.  The 'daemon_memcached' plugin passes all
     55 compatibility tests of the 'memcapable' command.

   * Multi-column support.  You can map multiple columns into the
     'value' part of the key/value store, with column values delimited
     by a user-specified separator character.

   * By default, the 'memcached' protocol is used to read and write data
     directly to 'InnoDB', letting MySQL manage in-memory caching using
     the 'InnoDB' buffer pool.  The default settings represent a
     combination of high reliability and the fewest surprises for
     database applications.  For example, default settings avoid
     uncommitted data on the database side, or stale data returned for
     'memcached' 'get' requests.

   * Advanced users can configure the system as a traditional
     'memcached' server, with all data cached only in the 'memcached'
     engine (memory caching), or use a combination of the ''memcached'
     engine' (memory caching) and the 'InnoDB' 'memcached' engine
     ('InnoDB' as back-end persistent storage).

   * Control over how often data is passed back and forth between
     'InnoDB' and 'memcached' operations through the
     'innodb_api_bk_commit_interval', 'daemon_memcached_r_batch_size',
     and 'daemon_memcached_w_batch_size' configuration options.  Batch
     size options default to a value of 1 for maximum reliability.

   * The ability to specify 'memcached' options through the
     'daemon_memcached_option' configuration parameter.  For example,
     you can change the port that 'memcached' listens on, reduce the
     maximum number of simultaneous connections, change the maximum
     memory size for a key/value pair, or enable debugging messages for
     the error log.

   * The 'innodb_api_trx_level' configuration option controls the
     transaction isolation level on queries processed by 'memcached'.
     Although 'memcached' has no concept of transactions, you can use
     this option to control how soon 'memcached' sees changes caused by
     SQL statements issued on the table used by the 'daemon_memcached'
     plugin.  By default, 'innodb_api_trx_level' is set to 'READ
     UNCOMMITTED'.

   * The 'innodb_api_enable_mdl' option can be used to lock the table at
     the MySQL level, so that the mapped table cannot be dropped or
     altered by DDL through the SQL interface.  Without the lock, the
     table can be dropped from the MySQL layer, but kept in 'InnoDB'
     storage until 'memcached' or some other user stops using it.  'MDL'
     stands for 'metadata locking'.

*Differences Between InnoDB memcached and Traditional memcached*

You may already be familiar with using 'memcached' with MySQL, as
described in Using MySQL with 'memcached'
(http://dev.mysql.com/doc/refman/5.6/en/ha-memcached.html).  This
section describes how features of the integrated 'InnoDB' 'memcached'
plugin differ from traditional 'memcached'.

   * Installation: The 'memcached' library comes with the MySQL server,
     making installation and setup relatively easy.  Installation
     involves running the 'innodb_memcached_config.sql' script to create
     a 'demo_test' table for 'memcached' to use, issuing an
     'INSTALL PLUGIN' statement to enable the
     'daemon_memcached' plugin, and adding desired 'memcached' options
     to a MySQL configuration file or startup script.  You might still
     install the traditional 'memcached' distribution for additional
     utilities such as 'memcp', 'memcat', and 'memcapable'.

     For comparison with traditional 'memcached', see Installing
     'memcached'
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-install.html).

   * Deployment: With traditional 'memcached', it is typical to run
     large numbers of low-capacity 'memcached' servers.  A typical
     deployment of the 'daemon_memcached' plugin, however, involves a
     smaller number of moderate or high-powered servers that are already
     running MySQL. The benefit of this configuration is in improving
     efficiency of individual database servers rather than exploiting
     unused memory or distributing lookups across large numbers of
     servers.  In the default configuration, very little memory is used
     for 'memcached', and in-memory lookups are served from the 'InnoDB'
     buffer pool, which automatically caches the most recently and
     frequently used data.  As with a traditional MySQL server instance,
     keep the value of the 'innodb_buffer_pool_size' configuration
     option as high as practical (without causing paging at the OS
     level), so that as much work as possible is performed in memory.

     For comparison with traditional 'memcached', see 'memcached'
     Deployment
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-using-deployment.html).

   * Expiry: By default (that is, using the 'innodb_only' caching
     policy), the latest data from the 'InnoDB' table is always
     returned, so the expiry options have no practical effect.  If you
     change the caching policy to 'caching' or 'cache-only', the expiry
     options work as usual, but requested data might be stale if it is
     updated in the underlying table before it expires from the memory
     cache.

     For comparison with traditional 'memcached', see Data Expiry
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-using-expiry.html).

   * Namespaces: 'memcached' is like a large directory where you give
     files elaborate names with prefixes and suffixes to keep the files
     from conflicting.  The 'daemon_memcached' plugin lets you use
     similar naming conventions for keys, with one addition.  Key names
     in the format '@@TABLE_ID.KEY'.TABLE_ID are decoded to reference a
     specific a table, using mapping data from the
     'innodb_memcache.containers' table.  The KEY is looked up in or
     written to the specified table.

     The '@@' notation only works for individual calls to 'get', 'add',
     and 'set' functions, but not others such as 'incr' or 'delete'.  To
     designate a default table for subsequent 'memcached' operations
     within a session, perform a 'get' request using the '@@' notation
     with a 'TABLE_ID', but without the key portion.  For example:

          get @@TABLE_ID

     Subsequent 'get', 'set', 'incr', 'delete', and other operations use
     the table designated by 'TABLE_ID' in the
     'innodb_memcache.containers.name' column.

     For comparison with traditional 'memcached', see Using Namespaces
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-using-namespaces.html).

   * Hashing and distribution: The default configuration, which uses the
     'innodb_only' caching policy, is suitable for a traditional
     deployment configuration where all data is available on all
     servers, such as a set of replication slave servers.

     If you physically divide data, as in a sharded configuration, you
     can split data across several machines running the
     'daemon_memcached' plugin, and use the traditional 'memcached'
     hashing mechanism to route requests to a particular machine.  On
     the MySQL side, you would typically let all data be inserted by
     'add' requests to 'memcached' so that appropriate values are stored
     in the database on the appropriate server.

     For comparison with traditional 'memcached', see 'memcached'
     Hashing/Distribution Types
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-using-hashtypes.html).

   * Memory usage: By default (with the 'innodb_only' caching policy),
     the 'memcached' protocol passes information back and forth with
     'InnoDB' tables, and the 'InnoDB' buffer pool handles in-memory
     lookups instead of 'memcached' memory usage growing and shrinking.
     Relatively little memory is used on the 'memcached' side.

     If you switch the caching policy to 'caching' or 'cache-only', the
     normal rules of 'memcached' memory usage apply.  Memory for
     'memcached' data values is allocated in terms of 'slabs'.  You can
     control slab size and maximum memory used for 'memcached'.

     Either way, you can monitor and troubleshoot the 'daemon_memcached'
     plugin using the familiar statistics
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-stats.html)
     system, accessed through the standard protocol, over a 'telnet'
     session, for example.  Extra utilities are not included with the
     'daemon_memcached' plugin.  You can use the 'memcached-tool' script
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-stats-memcached-tool.html)
     to install a full 'memcached' distribution.

     For comparison with traditional 'memcached', see Memory Allocation
     within 'memcached'
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-using-memory.html).

   * Thread usage: MySQL threads and 'memcached' threads co-exist on the
     same server.  Limits imposed on threads by the operating system
     apply to the total number of threads.

     For comparison with traditional 'memcached', see 'memcached' Thread
     Support
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-using-threads.html).

   * Log usage: Because the 'memcached' daemon is run alongside the
     MySQL server and writes to 'stderr', the '-v', '-vv', and '-vvv'
     options for logging write output to the MySQL error log.

     For comparison with traditional 'memcached', see 'memcached' Logs
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-using-logs.html).

   * 'memcached' operations: Familiar 'memcached' operations such as
     'get', 'set', 'add', and 'delete' are available.  Serialization
     (that is, the exact string format representing complex data
     structures) depends on the language interface.

     For comparison with traditional 'memcached', see Basic 'memcached'
     Operations
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-operations.html).

   * Using 'memcached' as a MySQL front end: This is the primary purpose
     of the 'InnoDB' 'memcached' plugin.  An integrated 'memcached'
     daemon improves application performance, and having 'InnoDB' handle
     data transfers between memory and disk simplifies application
     logic.

     For comparison with traditional 'memcached', see Using 'memcached'
     as a MySQL Caching Layer
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-mysql-frontend.html).

   * Utilities: The MySQL server includes the 'libmemcached' library but
     not additional command-line utilities.  To use commands such as
     'memcp', 'memcat', and 'memcapable' commands, install a full
     'memcached' distribution.  When 'memrm' and 'memflush' remove items
     from the cache, the items are also removed from the underlying
     'InnoDB' table.

     For comparison with traditional 'memcached', see 'libmemcached'
     Command-Line Utilities
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-libmemcached.html#ha-memcached-interfaces-libmemcached-utilities).

   * Programming interfaces: You can access the MySQL server through the
     'daemon_memcached' plugin using all supported languages: C and C++
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-libmemcached.html),
     Java
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-java.html),
     Perl
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-perl.html),
     Python
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-python.html),
     PHP
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-php.html),
     and Ruby
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-ruby.html).
     Specify the server hostname and port as with a traditional
     'memcached' server.  By default, the 'daemon_memcached' plugin
     listens on port '11211'.  You can use both the text and binary
     protocols
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-protocol.html).
     You can customize the behavior
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-libmemcached.html#ha-memcached-interfaces-libmemcached-behaviors)
     of 'memcached' functions at runtime.  Serialization (that is, the
     exact string format representing complex data structures) depends
     on the language interface.

     For comparison with traditional 'memcached', see Developing a
     'memcached' Application
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces.html).

   * Frequently asked questions: MySQL has an extensive FAQ for
     traditional 'memcached'.  The FAQ is mostly applicable, except that
     using 'InnoDB' tables as a storage medium for 'memcached' data
     means that you can use 'memcached' for more write-intensive
     applications than before, rather than as a read-only cache.

     See 'memcached' FAQ
     (http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-faq.html).

14.20.3 Setting Up the InnoDB memcached Plugin
----------------------------------------------

This section describes how to set up the 'daemon_memcached' plugin on a
MySQL server.  Because the 'memcached' daemon is tightly integrated with
the MySQL server to avoid network traffic and minimize latency, you
perform this process on each MySQL instance that uses this feature.

*Note*:

Before setting up the 'daemon_memcached' plugin, consult
innodb-memcached-security to understand the security procedures
required to prevent unauthorized access.

*Prerequisites*

   * The 'daemon_memcached' plugin is only supported on Linux, Solaris,
     and OS X platforms.  Other operating systems are not supported.

   * When building MySQL from source, you must build with
     '-DWITH_INNODB_MEMCACHED=ON'.  This build option generates two
     shared libraries in the MySQL plugin directory ('plugin_dir') that
     are required to run the 'daemon_memcached' plugin:

        * 'libmemcached.so': the 'memcached' daemon plugin to MySQL.

        * 'innodb_engine.so': an 'InnoDB' API plugin to 'memcached'.

   * 'libevent' must be installed.

        * If you did not build MySQL from source, the 'libevent' library
          is not included in your installation.  Use the installation
          method for your operating system to install 'libevent' 1.4.12
          or later.  For example, depending on the operating system, you
          might use 'apt-get', 'yum', or 'port install'.  For example,
          on Ubuntu Linux, use:

               sudo apt-get install libevent-dev

        * If you installed MySQL from a source code release, 'libevent'
          1.4.12 is bundled with the package and is located at the top
          level of the MySQL source code directory.  If you use the
          bundled version of 'libevent', no action is required.  If you
          want to use a local system version of 'libevent', you must
          build MySQL with the '-DWITH_LIBEVENT' build option set to
          'system' or 'yes'.

*Installing and Configuring the InnoDB memcached Plugin*

  1. Configure the 'daemon_memcached' plugin so it can interact with
     'InnoDB' tables by running the 'innodb_memcached_config.sql'
     configuration script, which is located in 'MYSQL_HOME/share'.  This
     script installs the 'innodb_memcache' database with three required
     tables ('cache_policies', 'config_options', and 'containers').  It
     also installs the 'demo_test' sample table in the 'test' database.

          mysql> source MYSQL_HOME/share/innodb_memcached_config.sql

     Running the 'innodb_memcached_config.sql' script is a one-time
     operation.  The tables remain in place if you later uninstall and
     re-install the 'daemon_memcached' plugin.

          mysql> USE innodb_memcache;
          mysql> SHOW TABLES;
          +---------------------------+
          | Tables_in_innodb_memcache |
          +---------------------------+
          | cache_policies            |
          | config_options            |
          | containers                |
          +---------------------------+

          mysql> USE test;
          mysql> SHOW TABLES;
          +----------------+
          | Tables_in_test |
          +----------------+
          | demo_test      |
          +----------------+

     Of these tables, the 'innodb_memcache.containers' table is the most
     important.  Entries in the 'containers' table provide a mapping to
     'InnoDB' table columns.  Each 'InnoDB' table used with the
     'daemon_memcached' plugin requires an entry in the 'containers'
     table.

     The 'innodb_memcached_config.sql' script inserts a single entry in
     the 'containers' table that provides a mapping for the 'demo_test'
     table.  It also inserts a single row of data into the 'demo_test'
     table.  This data allows you to immediately verify the installation
     after the setup is completed.

          mysql> SELECT * FROM innodb_memcache.containers\G
          *************************** 1. row ***************************
                            name: aaa
                       db_schema: test
                        db_table: demo_test
                     key_columns: c1
                   value_columns: c2
                           flags: c3
                      cas_column: c4
              expire_time_column: c5
          unique_idx_name_on_key: PRIMARY

          mysql> SELECT * FROM test.demo_test;
          +----+------------------+------+------+------+
          | c1 | c2               | c3   | c4   | c5   |
          +----+------------------+------+------+------+
          | AA | HELLO, HELLO     |    8 |    0 |    0 |
          +----+------------------+------+------+------+

     For more information about 'innodb_memcache' tables and the
     'demo_test' sample table, see innodb-memcached-internals.

  2. Activate the 'daemon_memcached' plugin by running the
     'INSTALL PLUGIN' statement:

          mysql> INSTALL PLUGIN daemon_memcached soname "libmemcached.so";

     Once the plugin is installed, it is automatically activated each
     time the MySQL server is restarted.

*Verifying the InnoDB and memcached Setup*

To verify the 'daemon_memcached' plugin setup, use a 'telnet' session to
issue 'memcached' commands.  By default, the 'memcached' daemon listens
on port 11211.

  1. Retrieve data from the 'test.demo_test' table.  The single row of
     data in the 'demo_test' table has a key value of 'AA'.

          telnet localhost 11211
          Trying 127.0.0.1...
          Connected to localhost.
          Escape character is '^]'.
          get AA
          VALUE AA 8 12
          HELLO, HELLO
          END

  2. Insert data using a 'set' command.

          set BB 10 0 16
          GOODBYE, GOODBYE
          STORED

     where:

        * 'set' is the command to store a value

        * 'BB' is the key

        * '10' is a flag for the operation; ignored by 'memcached' but
          may be used by the client to indicate any type of information;
          specify '0' if unused

        * '0' is the expiration time (TTL); specify '0' if unused

        * '16' is the length of the supplied value block in bytes

        * 'GOODBYE, GOODBYE' is the value that is stored

  3. Verify that the data inserted is stored in MySQL by connecting to
     the MySQL server and querying the 'test.demo_test' table.

          mysql> SELECT * FROM test.demo_test;
          +----+------------------+------+------+------+
          | c1 | c2               | c3   | c4   | c5   |
          +----+------------------+------+------+------+
          | AA | HELLO, HELLO     |    8 |    0 |    0 |
          | BB | GOODBYE, GOODBYE |   10 |    1 |    0 |
          +----+------------------+------+------+------+

  4. Return to the telnet session and retrieve the data that you
     inserted earlier using key 'BB'.

          get BB
          VALUE BB 10 16
          GOODBYE, GOODBYE
          END
          quit

If you shut down the MySQL server, which also shuts off the integrated
'memcached' server, further attempts to access the 'memcached' data fail
with a connection error.  Normally, the 'memcached' data also disappears
at this point, and you would require application logic to load the data
back into memory when 'memcached' is restarted.  However, the 'InnoDB'
'memcached' plugin automates this process for you.

When you restart MySQL, 'get' operations once again return the key/value
pairs you stored in the earlier 'memcached' session.  When a key is
requested and the associated value is not already in the memory cache,
the value is automatically queried from the MySQL 'test.demo_test'
table.

*Creating a New Table and Column Mapping*

This example shows how to setup your own 'InnoDB' table with the
'daemon_memcached' plugin.

  1. Create an 'InnoDB' table.  The table must have a key column with a
     unique index.  The key column of the city table is 'city_id', which
     is defined as the primary key.  The table must also include columns
     for 'flags', 'cas', and 'expiry' values.  There may be one or more
     value columns.  The 'city' table has three value columns ('name',
     'state', 'country').

     *Note*:

     There is no special requirement with respect to column names as
     along as a valid mapping is added to the
     'innodb_memcache.containers' table.

          mysql> CREATE TABLE city (
                 city_id VARCHAR(32),
                 name VARCHAR(1024),
                 state VARCHAR(1024),
                 country VARCHAR(1024),
                 flags INT,
                 cas BIGINT UNSIGNED,
                 expiry INT,
                 primary key(city_id)
                 ) ENGINE=InnoDB;

  2. Add an entry to the 'innodb_memcache.containers' table so that the
     'daemon_memcached' plugin knows how to access the 'InnoDB' table.
     The entry must satisfy the 'innodb_memcache.containers' table
     definition.  For a description of each field, see
     innodb-memcached-internals.

          mysql> DESCRIBE innodb_memcache.containers;
          +------------------------+--------------+------+-----+---------+-------+
          | Field                  | Type         | Null | Key | Default | Extra |
          +------------------------+--------------+------+-----+---------+-------+
          | name                   | varchar(50)  | NO   | PRI | NULL    |       |
          | db_schema              | varchar(250) | NO   |     | NULL    |       |
          | db_table               | varchar(250) | NO   |     | NULL    |       |
          | key_columns            | varchar(250) | NO   |     | NULL    |       |
          | value_columns          | varchar(250) | YES  |     | NULL    |       |
          | flags                  | varchar(250) | NO   |     | 0       |       |
          | cas_column             | varchar(250) | YES  |     | NULL    |       |
          | expire_time_column     | varchar(250) | YES  |     | NULL    |       |
          | unique_idx_name_on_key | varchar(250) | NO   |     | NULL    |       |
          +------------------------+--------------+------+-----+---------+-------+

     The 'innodb_memcache.containers' table entry for the city table is
     defined as:

          mysql> INSERT INTO `innodb_memcache`.`containers` (
                 `name`, `db_schema`, `db_table`, `key_columns`, `value_columns`,
                 `flags`, `cas_column`, `expire_time_column`, `unique_idx_name_on_key`)
                 VALUES ('default', 'test', 'city', 'city_id', 'name|state|country',
                 'flags','cas','expiry','PRIMARY');

        * 'default' is specified for the 'containers.name' column to
          configure the 'city' table as the default 'InnoDB' table to be
          used with the 'daemon_memcached' plugin.

        * Multiple 'InnoDB' table columns ('name', 'state', 'country')
          are mapped to 'containers.value_columns' using a '|'
          delimiter.

        * The 'flags', 'cas_column', and 'expire_time_column' fields of
          the 'innodb_memcache.containers' table are typically not
          significant in applications using the 'daemon_memcached'
          plugin.  However, a designated 'InnoDB' table column is
          required for each.  When inserting data, specify '0' for these
          columns if they are unused.

  3. After updating the 'innodb_memcache.containers' table, restart the
     'daemon_memcache' plugin to apply the changes.

          mysql> UNINSTALL PLUGIN daemon_memcached;

          mysql> INSTALL PLUGIN daemon_memcached soname "libmemcached.so";

  4. Using telnet, insert data into the 'city' table using a 'memcached'
     'set' command.

          telnet localhost 11211
          Trying 127.0.0.1...
          Connected to localhost.
          Escape character is '^]'.
          set B 0 0 22
          BANGALORE|BANGALORE|IN
          STORED

  5. Using MySQL, query the 'test.city' table to verify that the data
     you inserted was stored.

          mysql> SELECT * FROM test.city;
          +---------+-----------+-----------+---------+-------+------+--------+
          | city_id | name      | state     | country | flags | cas  | expiry |
          +---------+-----------+-----------+---------+-------+------+--------+
          | B       | BANGALORE | BANGALORE | IN      |     0 |    3 |      0 |
          +---------+-----------+-----------+---------+-------+------+--------+

  6. Using MySQL, insert additional data into the 'test.city' table.

          mysql> INSERT INTO city VALUES ('C','CHENNAI','TAMIL NADU','IN', 0, 0 ,0);
          mysql> INSERT INTO city VALUES ('D','DELHI','DELHI','IN', 0, 0, 0);
          mysql> INSERT INTO city VALUES ('H','HYDERABAD','TELANGANA','IN', 0, 0, 0);
          mysql> INSERT INTO city VALUES ('M','MUMBAI','MAHARASHTRA','IN', 0, 0, 0);

     *Note*:

     It is recommended that you specify a value of '0' for the 'flags',
     'cas_column', and 'expire_time_column' fields if they are unused.

  7. Using telnet, issue a 'memcached' 'get' command to retrieve data
     you inserted using MySQL.

          get H
          VALUE H 0 22
          HYDERABAD|TELANGANA|IN
          END

*Configuring the InnoDB memcached Plugin*

Traditional 'memcached' configuration options may be specified in a
MySQL configuration file or a 'mysqld' startup string,
encoded in the argument of the 'daemon_memcached_option' configuration
parameter.  'memcached' configuration options take effect when the
plugin is loaded, which occurs each time the MySQL server is started.

For example, to make 'memcached' listen on port 11222 instead of the
default port 11211, specify '-p11222' as an argument of the
'daemon_memcached_option' configuration option:

     mysqld .... --daemon_memcached_option="-p11222"

Other 'memcached' options can be encoded in the
'daemon_memcached_option' string.  For example, you can specify options
to reduce the maximum number of simultaneous connections, change the
maximum memory size for a key/value pair, or enable debugging messages
for the error log, and so on.

There are also configuration options specific to the 'daemon_memcached'
plugin.  These include:

   * 'daemon_memcached_engine_lib_name': Specifies the shared library
     that implements the 'InnoDB' 'memcached' plugin.  The default
     setting is 'innodb_engine.so'.

   * 'daemon_memcached_engine_lib_path': The path of the directory
     containing the shared library that implements the 'InnoDB'
     'memcached' plugin.  The default is NULL, representing the plugin
     directory.

   * 'daemon_memcached_r_batch_size': Defines the batch commit size for
     read operations ('get').  It specifies the number of 'memcached'
     read operations after which a commit occurs.
     'daemon_memcached_r_batch_size' is set to 1 by default so that
     every 'get' request accesses the most recently committed data in
     the 'InnoDB' table, whether the data was updated through
     'memcached' or by SQL. When the value is greater than 1, the
     counter for read operations is incremented with each 'get' call.  A
     'flush_all' call resets both read and write counters.

   * 'daemon_memcached_w_batch_size': Defines the batch commit size for
     write operations ('set', 'replace', 'append', 'prepend', 'incr',
     'decr', and so on).  'daemon_memcached_w_batch_size' is set to 1 by
     default so that no uncommitted data is lost in case of an outage,
     and so that SQL queries on the underlying table access the most
     recent data.  When the value is greater than 1, the counter for
     write operations is incremented for each 'add', 'set', 'incr',
     'decr', and 'delete' call.  A 'flush_all' call resets both read and
     write counters.

By default, you do not need to modify 'daemon_memcached_engine_lib_name'
or 'daemon_memcached_engine_lib_path'.  You might configure these
options if, for example, you want to use a different storage engine for
'memcached' (such as the NDB 'memcached' engine).

'daemon_memcached' plugin configuration parameters may be specified in
the MySQL configuration file or in a 'mysqld' startup
string.  They take effect when you load the 'daemon_memcached' plugin.

When making changes to 'daemon_memcached' plugin configuration, reload
the plugin to apply the changes.  To do so, issue the following
statements:

     mysql> UNINSTALL PLUGIN daemon_memcached;

     mysql> INSTALL PLUGIN daemon_memcached soname "libmemcached.so";

Configuration settings, required tables, and data are preserved when the
plugin is restarted.

For additional information about enabling and disabling plugins, see
server-plugin-loading.

14.20.4 Security Considerations for the InnoDB memcached Plugin
---------------------------------------------------------------

*Caution*:

Consult this section before deploying the 'daemon_memcached' plugin on a
production server, or even on a test server if the MySQL instance
contains sensitive data.

Because 'memcached' does not use an authentication mechanism by default,
and the optional SASL authentication is not as strong as traditional
DBMS security measures, only keep non-sensitive data in the MySQL
instance that uses the 'daemon_memcached' plugin, and wall off any
servers that use this configuration from potential intruders.  Do not
allow 'memcached' access to these servers from the Internet; only allow
access from within a firewalled intranet, ideally from a subnet whose
membership you can restrict.

*Password-Protecting memcached Using SASL*

SASL support provides the capability to protect your MySQL database from
unauthenticated access through 'memcached' clients.  This section
explains how to enable SASL with the 'daemon_memcached' plugin.  The
steps are almost identical to those performed to enabled SASL for a
traditional 'memcached' server.

SASL stands for 'Simple Authentication and Security Layer', a standard
for adding authentication support to connection-based protocols.
'memcached' added SASL support in version 1.4.3.

SASL authentication is only supported with the binary protocol.

'memcached' clients are only able to access 'InnoDB' tables that are
registered in the 'innodb_memcache.containers' table. Even though a DBA
can place access restrictions on such tables, access through 'memcached'
applications cannot be controlled.  For this reason, SASL support is
provided to control access to 'InnoDB' tables associated with the
'daemon_memcached' plugin.

The following section shows how to build, enable, and test an
SASL-enabled 'daemon_memcached' plugin.

*Building and Enabling SASL with the InnoDB memcached Plugin*

By default, an SASL-enabled 'daemon_memcached' plugin is not included in
MySQL release packages, since an SASL-enabled 'daemon_memcached' plugin
requires building 'memcached' with SASL libraries.  To enable SASL
support, download the MySQL source and rebuild the 'daemon_memcached'
plugin after downloading the SASL libraries:

  1. Install the SASL development and utility libraries.  For example,
     on Ubuntu, use 'apt-get' to obtain the libraries:

          sudo apt-get -f install libsasl2-2 sasl2-bin libsasl2-2 libsasl2-dev libsasl2-modules

  2. Build the 'daemon_memcached' plugin shared libraries with SASL
     capability by adding 'ENABLE_MEMCACHED_SASL=1' to your 'cmake'
     options.  'memcached' also provides _simple cleartext password
     support_, which facilitates testing.  To enable simple cleartext
     password support, specify the 'ENABLE_MEMCACHED_SASL_PWDB=1'
     'cmake' option.

     In summary, add following three 'cmake' options:

          cmake ... -DWITH_INNODB_MEMCACHED=1 -DENABLE_MEMCACHED_SASL=1 -DENABLE_MEMCACHED_SASL_PWDB=1

  3. Install the 'daemon_memcached' plugin, as described in
     innodb-memcached-setup.

  4. Configure a user name and password file.  (This example uses
     'memcached' simple cleartext password support.)

       1. In a file, create a user named 'testname' and define the
          password as 'testpasswd':

               echo "testname:testpasswd:::::::" >/home/jy/memcached-sasl-db

       2. Configure the 'MEMCACHED_SASL_PWDB' environment variable to
          inform 'memcached' of the user name and password file:

               export MEMCACHED_SASL_PWDB=/home/jy/memcached-sasl-db

       3. Inform 'memcached' that a cleartext password is used:

               echo "mech_list: plain" > /home/jy/work2/msasl/clients/memcached.conf
               export SASL_CONF_PATH=/home/jy/work2/msasl/clients

  5. Enable SASL by restarting the MySQL server with the 'memcached'
     '-S' option encoded in the 'daemon_memcached_option' configuration
     parameter:

          mysqld ... --daemon_memcached_option="-S"

  6. To test the setup, use an SASL-enabled client such as SASL-enabled
     libmemcached
     (https://code.launchpad.net/~trond-norbye/libmemcached/sasl).

          memcp --servers=localhost:11211 --binary  --username=testname
            --password=PASSWORD myfile.txt

          memcat --servers=localhost:11211 --binary --username=testname
            --password=PASSWORD myfile.txt

     If you specify an incorrect user name or password, the operation is
     rejected with a 'memcache error AUTHENTICATION FAILURE' message.
     In this case, examine the cleartext password set in the
     'memcached-sasl-db' file to verify that the credentials you
     supplied are correct.

There are other methods to test SASL authentication with 'memcached',
but the method described above is the most straightforward.

14.20.5 Writing Applications for the InnoDB memcached Plugin
------------------------------------------------------------

Typically, writing an application for the 'InnoDB' 'memcached' plugin
involves some degree of rewriting or adapting existing code that uses
MySQL or the 'memcached' API.

   * With the 'daemon_memcached' plugin, instead of many traditional
     'memcached' servers running on low-powered machines, you have the
     same number of 'memcached' servers as MySQL servers, running on
     relatively high-powered machines with substantial disk storage and
     memory.  You might reuse some existing code that works with the
     'memcached' API, but adaptation is likely required due to the
     different server configuration.

   * The data stored through the 'daemon_memcached' plugin goes into
     'VARCHAR', 'TEXT', or 'BLOB'.
     columns, and must be converted to do numeric operations.  You can
     perform the conversion on the application side, or by using the
     'CAST()' function in queries.

   * Coming from a database background, you might be used to
     general-purpose SQL tables with many columns.  The tables accessed
     by 'memcached' code likely have only a few or even a single column
     holding data values.

   * You might adapt parts of your application that perform single-row
     queries, inserts, updates, or deletes, to improve performance in
     critical sections of code.  Both queries (read) and DML (write)
     operations can be substantially faster when performed through the
     'InnoDB' 'memcached' interface.  The performance improvement for
     writes is typically greater than the performance improvement for
     reads, so you might focus on adapting code that performs logging or
     records interactive choices on a website.

The following sections explore these points in more detail.

14.20.5.1 Adapting an Existing MySQL Schema for the InnoDB memcached Plugin
...........................................................................

Consider these aspects of 'memcached' applications when adapting an
existing MySQL schema or application to use the 'daemon_memcached'
plugin:

   * 'memcached' keys cannot contain spaces or newlines, because these
     characters are used as separators in the ASCII protocol.  If you
     are using lookup values that contain spaces, transform or hash them
     into values without spaces before using them as keys in calls to
     'add()', 'set()', 'get()', and so on.  Although theoretically these
     characters are allowed in keys in programs that use the binary
     protocol, you should restrict the characters used in keys to ensure
     compatibility with a broad range of clients.

   * If there is a short numeric primary key column in an 'InnoDB'
     table, use it as the unique lookup key for 'memcached' by
     converting the integer to a string value.  If the 'memcached'
     server is used for multiple applications, or with more than one
     'InnoDB' table, consider modifying the name to ensure that it is
     unique.  For example, prepend the table name, or the database name
     and the table name, before the numeric value.

     *Note*:

     The 'daemon_memcached' plugin supports inserts and reads on mapped
     'InnoDB' tables that have an 'INTEGER' defined as the primary key.

   * You cannot use a partitioned table for data queried or stored using
     'memcached'.

   * The 'memcached' protocol passes numeric values around as strings.
     To store numeric values in the underlying 'InnoDB' table, to
     implement counters that can be used in SQL functions such as
     'SUM()' or 'AVG()', for example:

        * Use 'VARCHAR' columns with enough characters to
          hold all the digits of the largest expected number (and
          additional characters if appropriate for the negative sign,
          decimal point, or both).

        * In any query that performs arithmetic using column values, use
          the 'CAST()' function to convert the values from string to
          integer, or to some other numeric type.  For example:

               # Alphabetic entries are returned as zero.

               SELECT CAST(c2 as unsigned integer) FROM demo_test;

               # Since there could be numeric values of 0, can't disqualify them.
               # Test the string values to find the ones that are integers, and average only those.

               SELECT AVG(cast(c2 as unsigned integer)) FROM demo_test
                 WHERE c2 BETWEEN '0' and '9999999999';

               # Views let you hide the complexity of queries. The results are already converted;
               # no need to repeat conversion functions and WHERE clauses each time.

               CREATE VIEW numbers AS SELECT c1 KEY, CAST(c2 AS UNSIGNED INTEGER) val
                 FROM demo_test WHERE c2 BETWEEN '0' and '9999999999';
               SELECT SUM(val) FROM numbers;

          *Note*:

          Any alphabetic values in the result set are converted into 0
          by the call to 'CAST()'.  When using functions such as
          'AVG()', which depend on the number of rows in the result set,
          include 'WHERE' clauses to filter out non-numeric values.

   * If the 'InnoDB' column used as a key could have values longer than
     250 bytes, hash the value to less than 250 bytes.

   * To use an existing table with the 'daemon_memcached' plugin, define
     an entry for it in the 'innodb_memcache.containers' table.  To make
     that table the default for all 'memcached' requests, specify a
     value of 'default' in the 'name' column, then restart the MySQL
     server to make the change take effect.  If you use multiple tables
     for different classes of 'memcached' data, set up multiple entries
     in the 'innodb_memcache.containers' table with 'name' values of
     your choice, then issue a 'memcached' request in the form of 'get
     @@NAME' or 'set @@NAME' within the application to specify the table
     to be used for subsequent 'memcached' requests.

     For an example of using a table other than the predefined
     'test.demo_test' table, see
     innodb-memcached-tutorial-python.  For the required table layout,
     see innodb-memcached-internals.

   * To use multiple 'InnoDB' table column values with 'memcached'
     key/value pairs, specify column names separated by comma,
     semicolon, space, or pipe characters in the 'value_columns' field
     of the 'innodb_memcache.containers' entry for the 'InnoDB' table.
     For example, specify 'col1,col2,col3' or 'col1|col2|col3' in the
     'value_columns' field.

     Concatenate the column values into a single string using the pipe
     character as a separator before passing the string to 'memcached'
     'add' or 'set' calls.  The string is unpacked automatically into
     the correct column.  Each 'get' call returns a single string
     containing the column values that is also delimited by the pipe
     character.  You can unpack the values using the appropriate
     application language syntax.

This example shows how to use your own table with a sample Python
application that uses 'memcached' for data manipulation.

The example assumes that the 'daemon_memcached' plugin is installed as
described in innodb-memcached-setup.  It also assumes that your
system is configured to run a Python script that uses the
'python-memcache' module.

  1. Create the 'multicol' table which stores country information
     including population, area, and driver side data (''R'' for right
     and ''L'' for left).

          mysql> USE test;

          mysql> CREATE TABLE `multicol` (
                  `country` varchar(128) NOT NULL DEFAULT '',
                  `population` varchar(10) DEFAULT NULL,
                  `area_sq_km` varchar(9) DEFAULT NULL,
                  `drive_side` varchar(1) DEFAULT NULL,
                  `c3` int(11) DEFAULT NULL,
                  `c4` bigint(20) unsigned DEFAULT NULL,
                  `c5` int(11) DEFAULT NULL,
                  PRIMARY KEY (`country`)
                  ) ENGINE=InnoDB DEFAULT CHARSET=latin1;

  2. Insert a record into the 'innodb_memcache.containers' table so that
     the 'daemon_memcached' plugin can access the 'multicol' table.

          mysql> INSERT INTO innodb_memcache.containers
                 (name,db_schema,db_table,key_columns,value_columns,flags,cas_column,
                 expire_time_column,unique_idx_name_on_key)
                 VALUES
                 ('bbb','test','multicol','country','population,area_sq_km,drive_side',
                 'c3','c4','c5','PRIMARY');

          mysql> COMMIT;

        * The 'innodb_memcache.containers' record for the 'multicol'
          table specifies a 'name' value of ''bbb'', which is the table
          identifier.

          *Note*:

          If a single 'InnoDB' table is used for all 'memcached'
          applications, the 'name' value can be set to 'default' to
          avoid using '@@' notation to switch tables.

        * The 'db_schema' column is set to 'test', which is the name of
          the database where the 'multicol' table resides.

        * The 'db_table' column is set to 'multicol', which is the name
          of the 'InnoDB' table.

        * 'key_columns' is set to the unique 'country' column.  The
          'country' column is defined as the primary key in the
          'multicol' table definition.

        * Rather than a single 'InnoDB' table column to hold a composite
          data value, data is divided among three table columns
          ('population', 'area_sq_km', and 'drive_side').  To
          accommodate multiple value columns, a comma-separated list of
          columns is specified in the 'value_columns' field.  The
          columns defined in the 'value_columns' field are the columns
          used when storing or retrieving values.

        * Values for the 'flags', 'expire_time', and 'cas_column' fields
          are based on values used in the 'demo.test' sample table.
          These fields are typically not significant in applications
          that use the 'daemon_memcached' plugin because MySQL keeps
          data synchronized, and there is no need to worry about data
          expiring or becoming stale.

        * The 'unique_idx_name_on_key' field is set to 'PRIMARY', which
          refers to the primary index defined on the unique 'country'
          column in the 'multicol' table.

  3. Copy the sample Python application into a file.  In this example,
     the sample script is copied to a file named 'multicol.py'.

     The sample Python application inserts data into the 'multicol'
     table and retrieves data for all keys, demonstrating how to access
     an 'InnoDB' table through the 'daemon_memcached' plugin.

          import sys, os
          import memcache

          def connect_to_memcached():
            memc = memcache.Client(['127.0.0.1:11211'], debug=0);
            print "Connected to memcached."
            return memc

          def banner(message):
            print
            print "=" * len(message)
            print message
            print "=" * len(message)

          country_data = [
          ("Canada","34820000","9984670","R"),
          ("USA","314242000","9826675","R"),
          ("Ireland","6399152","84421","L"),
          ("UK","62262000","243610","L"),
          ("Mexico","113910608","1972550","R"),
          ("Denmark","5543453","43094","R"),
          ("Norway","5002942","385252","R"),
          ("UAE","8264070","83600","R"),
          ("India","1210193422","3287263","L"),
          ("China","1347350000","9640821","R"),
          ]

          def switch_table(memc,table):
            key = "@@" + table
            print "Switching default table to '" + table + "' by issuing GET for '" + key + "'."
            result = memc.get(key)

          def insert_country_data(memc):
            banner("Inserting initial data via memcached interface")
            for item in country_data:
              country = item[0]
              population = item[1]
              area = item[2]
              drive_side = item[3]

              key = country
              value = "|".join([population,area,drive_side])
              print "Key = " + key
              print "Value = " + value

              if memc.add(key,value):
                print "Added new key, value pair."
              else:
                print "Updating value for existing key."
                memc.set(key,value)

          def query_country_data(memc):
            banner("Retrieving data for all keys (country names)")
            for item in country_data:
              key = item[0]
              result = memc.get(key)
              print "Here is the result retrieved from the database for key " + key + ":"
              print result
              (m_population, m_area, m_drive_side) = result.split("|")
              print "Unpacked population value: " + m_population
              print "Unpacked area value      : " + m_area
              print "Unpacked drive side value: " + m_drive_side

          if __name__ == '__main__':

            memc = connect_to_memcached()
            switch_table(memc,"bbb")
            insert_country_data(memc)
            query_country_data(memc)

            sys.exit(0)

     Sample Python application notes:

        * No database authorization is required to run the application,
          since data manipulation is performed through the 'memcached'
          interface.  The only required information is the port number
          on the local system where the 'memcached' daemon listens.

        * To make sure the application uses the 'multicol' table, the
          'switch_table()' function is called, which performs a dummy
          'get' or 'set' request using '@@' notation.  The 'name' value
          in the request is 'bbb', which is the 'multicol' table
          identifier defined in the 'innodb_memcache.containers.name'
          field.

          A more descriptive 'name' value might be used in a real-world
          application.  This example simply illustrates that a table
          identifier is specified rather than the table name in 'get
          @@...' requests.

        * The utility functions used to insert and query data
          demonstrate how to turn a Python data structure into
          pipe-separated values for sending data to MySQL with 'add' or
          'set' requests, and how to unpack the pipe-separated values
          returned by 'get' requests.  This extra processing is only
          required when mapping a single 'memcached' value to multiple
          MySQL table columns.

  4. Run the sample Python application.

          shell> python multicol.py

     If successful, the sample application returns this output:

          Connected to memcached.
          Switching default table to 'bbb' by issuing GET for '@@bbb'.

          ==============================================
          Inserting initial data via memcached interface
          ==============================================
          Key = Canada
          Value = 34820000|9984670|R
          Added new key, value pair.
          Key = USA
          Value = 314242000|9826675|R
          Added new key, value pair.
          Key = Ireland
          Value = 6399152|84421|L
          Added new key, value pair.
          Key = UK
          Value = 62262000|243610|L
          Added new key, value pair.
          Key = Mexico
          Value = 113910608|1972550|R
          Added new key, value pair.
          Key = Denmark
          Value = 5543453|43094|R
          Added new key, value pair.
          Key = Norway
          Value = 5002942|385252|R
          Added new key, value pair.
          Key = UAE
          Value = 8264070|83600|R
          Added new key, value pair.
          Key = India
          Value = 1210193422|3287263|L
          Added new key, value pair.
          Key = China
          Value = 1347350000|9640821|R
          Added new key, value pair.

          ============================================
          Retrieving data for all keys (country names)
          ============================================
          Here is the result retrieved from the database for key Canada:
          34820000|9984670|R
          Unpacked population value: 34820000
          Unpacked area value      : 9984670
          Unpacked drive side value: R
          Here is the result retrieved from the database for key USA:
          314242000|9826675|R
          Unpacked population value: 314242000
          Unpacked area value      : 9826675
          Unpacked drive side value: R
          Here is the result retrieved from the database for key Ireland:
          6399152|84421|L
          Unpacked population value: 6399152
          Unpacked area value      : 84421
          Unpacked drive side value: L
          Here is the result retrieved from the database for key UK:
          62262000|243610|L
          Unpacked population value: 62262000
          Unpacked area value      : 243610
          Unpacked drive side value: L
          Here is the result retrieved from the database for key Mexico:
          113910608|1972550|R
          Unpacked population value: 113910608
          Unpacked area value      : 1972550
          Unpacked drive side value: R
          Here is the result retrieved from the database for key Denmark:
          5543453|43094|R
          Unpacked population value: 5543453
          Unpacked area value      : 43094
          Unpacked drive side value: R
          Here is the result retrieved from the database for key Norway:
          5002942|385252|R
          Unpacked population value: 5002942
          Unpacked area value      : 385252
          Unpacked drive side value: R
          Here is the result retrieved from the database for key UAE:
          8264070|83600|R
          Unpacked population value: 8264070
          Unpacked area value      : 83600
          Unpacked drive side value: R
          Here is the result retrieved from the database for key India:
          1210193422|3287263|L
          Unpacked population value: 1210193422
          Unpacked area value      : 3287263
          Unpacked drive side value: L
          Here is the result retrieved from the database for key China:
          1347350000|9640821|R
          Unpacked population value: 1347350000
          Unpacked area value      : 9640821
          Unpacked drive side value: R

  5. Query the 'innodb_memcache.containers' table to view the record you
     inserted earlier for the 'multicol' table.  The first record is the
     sample entry for the 'demo_test' table that is created during the
     initial 'daemon_memcached' plugin setup.  The second record is the
     entry you inserted for the 'multicol' table.

          mysql> SELECT * FROM innodb_memcache.containers\G
          *************************** 1. row ***************************
                            name: aaa
                       db_schema: test
                        db_table: demo_test
                     key_columns: c1
                   value_columns: c2
                           flags: c3
                      cas_column: c4
              expire_time_column: c5
          unique_idx_name_on_key: PRIMARY
          *************************** 2. row ***************************
                            name: bbb
                       db_schema: test
                        db_table: multicol
                     key_columns: country
                   value_columns: population,area_sq_km,drive_side
                           flags: c3
                      cas_column: c4
              expire_time_column: c5
          unique_idx_name_on_key: PRIMARY

  6. Query the 'multicol' table to view data inserted by the sample
     Python application.  The data is available for MySQL queries, which
     demonstrates how the same data can be accessed using SQL or through
     applications (using the appropriate MySQL Connector or API).

          mysql> SELECT * FROM test.multicol;
          +---------+------------+------------+------------+------+------+------+
          | country | population | area_sq_km | drive_side | c3   | c4   | c5   |
          +---------+------------+------------+------------+------+------+------+
          | Canada  | 34820000   | 9984670    | R          |    0 |   11 |    0 |
          | China   | 1347350000 | 9640821    | R          |    0 |   20 |    0 |
          | Denmark | 5543453    | 43094      | R          |    0 |   16 |    0 |
          | India   | 1210193422 | 3287263    | L          |    0 |   19 |    0 |
          | Ireland | 6399152    | 84421      | L          |    0 |   13 |    0 |
          | Mexico  | 113910608  | 1972550    | R          |    0 |   15 |    0 |
          | Norway  | 5002942    | 385252     | R          |    0 |   17 |    0 |
          | UAE     | 8264070    | 83600      | R          |    0 |   18 |    0 |
          | UK      | 62262000   | 243610     | L          |    0 |   14 |    0 |
          | USA     | 314242000  | 9826675    | R          |    0 |   12 |    0 |
          +---------+------------+------------+------------+------+------+------+

     *Note*:

     Always allow sufficient size to hold necessary digits, decimal
     points, sign characters, leading zeros, and so on when defining the
     length for columns that are treated as numbers.  Too-long values in
     a string column such as a 'VARCHAR' are truncated by removing some
     characters, which could produce nonsensical numeric values.

  7. Optionally, run report-type queries on the 'InnoDB' table that
     stores the 'memcached' data.

     You can produce reports through SQL queries, performing
     calculations and tests across any columns, not just the 'country'
     key column.  (Because the following examples use data from only a
     few countries, the numbers are for illustration purposes only.)
     The following queries return the average population of countries
     where people drive on the right, and the average size of countries
     whose names start with 'U':

          mysql> SELECT AVG(population) FROM multicol WHERE drive_side = 'R';
          +-------------------+
          | avg(population)   |
          +-------------------+
          | 261304724.7142857 |
          +-------------------+

          mysql> SELECT SUM(area_sq_km) FROM multicol WHERE country LIKE 'U%';
          +-----------------+
          | sum(area_sq_km) |
          +-----------------+
          |        10153885 |
          +-----------------+

     Because the 'population' and 'area_sq_km' columns store character
     data rather than strongly typed numeric data, functions such as
     'AVG()' and 'SUM()' work by converting each value to a number
     first.  This approach _does not work_ for operators such as '<' or
     '>', for example, when comparing character-based values, '9 >
     1000', which is not expected from a clause such as 'ORDER BY
     population DESC'.  For the most accurate type treatment, perform
     queries against views that cast numeric columns to the appropriate
     types.  This technique lets you issue simple 'SELECT *' queries
     from database applications, while ensuring that casting, filtering,
     and ordering is correct.  The following example shows a view that
     can be queried to find the top three countries in descending order
     of population, with the results reflecting the latest data in the
     'multicol' table, and with population and area figures treated as
     numbers:

          mysql> CREATE VIEW populous_countries AS
                 SELECT
                 country,
                 cast(population as unsigned integer) population,
                 cast(area_sq_km as unsigned integer) area_sq_km,
                 drive_side FROM multicol
                 ORDER BY CAST(population as unsigned integer) DESC
                 LIMIT 3;

          mysql> SELECT * FROM populous_countries;
          +---------+------------+------------+------------+
          | country | population | area_sq_km | drive_side |
          +---------+------------+------------+------------+
          | China   | 1347350000 |    9640821 | R          |
          | India   | 1210193422 |    3287263 | L          |
          | USA     |  314242000 |    9826675 | R          |
          +---------+------------+------------+------------+

          mysql> DESC populous_countries;
          +------------+---------------------+------+-----+---------+-------+
          | Field      | Type                | Null | Key | Default | Extra |
          +------------+---------------------+------+-----+---------+-------+
          | country    | varchar(128)        | NO   |     |         |       |
          | population | bigint(10) unsigned | YES  |     | NULL    |       |
          | area_sq_km | int(9) unsigned     | YES  |     | NULL    |       |
          | drive_side | varchar(1)          | YES  |     | NULL    |       |
          +------------+---------------------+------+-----+---------+-------+

14.20.5.2 Adapting a memcached Application for the InnoDB memcached Plugin
..........................................................................

Consider these aspects of MySQL and 'InnoDB' tables when adapting
existing 'memcached' applications to use the 'daemon_memcached' plugin:

   * If there are key values longer than a few bytes, it may be more
     efficient to use a numeric auto-increment column as the primary key
     of the 'InnoDB' table, and to create a unique secondary index on
     the column that contains the 'memcached' key values.  This is
     because 'InnoDB' performs best for large-scale insertions if
     primary key values are added in sorted order (as they are with
     auto-increment values).  Primary key values are included in
     secondary indexes, which takes up unnecessary space if the primary
     key is a long string value.

   * If you store several different classes of information using
     'memcached', consider setting up a separate 'InnoDB' table for each
     type of data.  Define additional table identifiers in the
     'innodb_memcache.containers' table, and use the '@@TABLE_ID.KEY'
     notation to store and retrieve items from different tables.
     Physically dividing different types of information allows you tune
     the characteristics of each table for optimum space utilization,
     performance, and reliability.  For example, you might enable
     compression for a table that holds blog posts, but not for a table
     that holds thumbnail images.  You might back up one table more
     frequently than another because it holds critical data.  You might
     create additional secondary indexes on tables that are frequently
     used to generate reports using SQL.

   * Preferably, configure a stable set of table definitions for use
     with the 'daemon_memcached' plugin, and leave the tables in place
     permanently.  Changes to the 'innodb_memcache.containers' table
     take effect the next time the 'innodb_memcache.containers' table is
     queried.  Entries in the containers table are processed at startup,
     and are consulted whenever an unrecognized table identifier (as
     defined by 'containers.name') is requested using '@@' notation.
     Thus, new entries are visible as soon as you use the associated
     table identifier, but changes to existing entries require a server
     restart before they take effect.

   * When you use the default 'innodb_only' caching policy, calls to
     'add()', 'set()', 'incr()', and so on can succeed but still trigger
     debugging messages such as 'while expecting 'STORED', got
     unexpected response 'NOT_STORED'.  Debug messages occur because new
     and updated values are sent directly to the 'InnoDB' table without
     being saved in the memory cache, due to the 'innodb_only' caching
     policy.

14.20.5.3 Tuning InnoDB memcached Plugin Performance
....................................................

Because using 'InnoDB' in combination with 'memcached' involves writing
all data to disk, whether immediately or sometime later, raw performance
is expected to be somewhat slower than using 'memcached' by itself.
When using the 'InnoDB' 'memcached' plugin, focus tuning goals for
'memcached' operations on achieving better performance than equivalent
SQL operations.

Benchmarks suggest that queries and DML operations (inserts, updates,
and deletes) that use the 'memcached' interface are faster than
traditional SQL. DML operations typically see a larger improvements.
Therefore, consider adapting write-intensive applications to use the
'memcached' interface first.  Also consider prioritizing adaptation of
write-intensive applications that use fast, lightweight mechanisms that
lack reliability.

*Adapting SQL Queries*

The types of queries that are most suited to simple 'GET' requests are
those with a single clause or a set of 'AND' conditions in the 'WHERE'
clause:

     SQL:
     SELECT col FROM tbl WHERE key = 'key_value';

     memcached:
     get key_value

     SQL:
     SELECT col FROM tbl WHERE col1 = val1 and col2 = val2 and col3 = val3;

     memcached:
     # Since you must always know these 3 values to look up the key,
     # combine them into a unique string and use that as the key
     # for all ADD, SET, and GET operations.
     key_value = val1 + ":" + val2 + ":" + val3
     get key_value

     SQL:
     SELECT 'key exists!' FROM tbl
       WHERE EXISTS (SELECT col1 FROM tbl WHERE KEY = 'key_value') LIMIT 1;

     memcached:
     # Test for existence of key by asking for its value and checking if the call succeeds,
     # ignoring the value itself. For existence checking, you typically only store a very
     # short value such as "1".
     get key_value

*Using System Memory*

For best performance, deploy the 'daemon_memcached' plugin on machines
that are configured as typical database servers, where the majority of
system RAM is devoted to the 'InnoDB' buffer pool, through the
'innodb_buffer_pool_size' configuration option.  For systems with
multi-gigabyte buffer pools, consider raising the value of
'innodb_buffer_pool_instances' for maximum throughput when most
operations involve data that is already cached in memory.

*Reducing Redundant I/O*

'InnoDB' has a number of settings that let you choose the balance
between high reliability, in case of a crash, and the amount of I/O
overhead during high write workloads.  For example, consider setting the
'innodb_doublewrite' to '0' and 'innodb_flush_log_at_trx_commit' to '2'.
Measure performance with different 'innodb_flush_method' settings.

*Note*:

'innodb_support_xa' is deprecated and will be removed in a future
release.  As of MySQL 5.7.10, 'InnoDB' support for two-phase commit in
XA transactions is always enabled and disabling 'innodb_support_xa' is
no longer permitted.

For other ways to reduce or tune I/O for table operations, see
optimizing-innodb-diskio.

*Reducing Transactional Overhead*

A default value of 1 for 'daemon_memcached_r_batch_size' and
'daemon_memcached_w_batch_size' is intended for maximum reliability of
results and safety of stored or updated data.

Depending on the type of application, you might increase one or both of
these settings to reduce the overhead of frequent commit operations.  On
a busy system, you might increase 'daemon_memcached_r_batch_size',
knowing that changes to data made through SQL may not become visible to
'memcached' immediately (that is, until N more 'get' operations are
processed).  When processing data where every write operation must be
reliably stored, leave 'daemon_memcached_w_batch_size' set to '1'.
Increase the setting when processing large numbers of updates intended
only for statistical analysis, where losing the last N updates in a
crash is an acceptable risk.

For example, imagine a system that monitors traffic crossing a busy
bridge, recording data for approximately 100,000 vehicles each day.  If
the application counts different types of vehicles to analyze traffic
patterns, changing 'daemon_memcached_w_batch_size' from '1' to '100'
reduces I/O overhead for commit operations by 99%.  In case of an
outage, a maximum of 100 records are lost, which may be an acceptable
margin of error.  If instead the application performed automated toll
collection for each car, you would set 'daemon_memcached_w_batch_size'
to '1' to ensure that each toll record is immediately saved to disk.

Because of the way 'InnoDB' organizes 'memcached' key values on disk, if
you have a large number of keys to create, it may be faster to sort the
data items by key value in the application and 'add' them in sorted
order, rather than create keys in arbitrary order.

The 'memslap' command, which is part of the regular 'memcached'
distribution but not included with the 'daemon_memcached' plugin, can be
useful for benchmarking different configurations.  It can also be used
to generate sample key/value pairs to use in your own benchmarks.  See
'libmemcached' Command-Line Utilities
(http://dev.mysql.com/doc/refman/5.6/en/ha-memcached-interfaces-libmemcached.html#ha-memcached-interfaces-libmemcached-utilities)
for details.

14.20.5.4 Controlling Transactional Behavior of the InnoDB memcached Plugin
...........................................................................

Unlike traditional 'memcached', the 'daemon_memcached' plugin allows you
to control durability of data values produced through calls to 'add',
'set', 'incr', and so on.  By default, data written through the
'memcached' interface is stored to disk, and calls to 'get' return the
most recent value from disk.  Although the default behavior does not
offer the best possible raw performance, it is still fast compared to
the SQL interface for 'InnoDB' tables.

As you gain experience using the 'daemon_memcached' plugin, you can
consider relaxing durability settings for non-critical classes of data,
at the risk of losing some updated values in the event of an outage, or
returning data that is slightly out-of-date.

*Frequency of Commits*

One tradeoff between durability and raw performance is how frequently
new and changed data is committed.  If data is critical, is should be
committed immediately so that it is safe in case of a crash or outage.
If data is less critical, such as counters that are reset after a crash
or logging data that you can afford to lose, you might prefer higher raw
throughput that is available with less frequent commits.

When a 'memcached' operation inserts, updates, or deletes data in the
underlying 'InnoDB' table, the change might be committed to the 'InnoDB'
table instantly (if 'daemon_memcached_w_batch_size=1') or some time
later (if the 'daemon_memcached_w_batch_size' value is greater than 1).
In either case, the change cannot be rolled back.  If you increase the
value of 'daemon_memcached_w_batch_size' to avoid high I/O overhead
during busy times, commits could become infrequent when the workload
decreases.  As a safety measure, a background thread automatically
commits changes made through the 'memcached' API at regular intervals.
The interval is controlled by the 'innodb_api_bk_commit_interval'
configuration option, which has a default setting of '5' seconds.

When a 'memcached' operation inserts or updates data in the underlying
'InnoDB' table, the changed data is immediately visible to other
'memcached' requests because the new value remains in the memory cache,
even if it is not yet committed on the MySQL side.

*Transaction Isolation*

When a 'memcached' operation such as 'get' or 'incr' causes a query or
DML operation on the underlying 'InnoDB' table, you can control whether
the operation sees the very latest data written to the table, only data
that has been committed, or other variations of transaction isolation
level.  Use the 'innodb_api_trx_level' configuration option to control
this feature.  The numeric values specified for this option correspond
to isolation levels such as 'REPEATABLE READ'.  See the description of
the 'innodb_api_trx_level' option for information about other settings.

A strict isolation level ensures that data you retrieve is not rolled
back or changed suddenly causing subsequent queries to return different
values.  However, strict isolation levels require greater locking
overhead, which can cause waits.  For a NoSQL-style application that
does not use long-running transactions, you can typically use the
default isolation level or switch to a less strict isolation level.

*Disabling Row Locks for memcached DML Operations*

The 'innodb_api_disable_rowlock' option can be used to disable row locks
when 'memcached' requests through the 'daemon_memcached' plugin cause
DML operations.  By default, 'innodb_api_disable_rowlock' is set to
'OFF' which means that 'memcached' requests row locks for 'get' and
'set' operations.  When 'innodb_api_disable_rowlock' is set to 'ON',
'memcached' requests a table lock instead of row locks.

The 'innodb_api_disable_rowlock' option is not dynamic.  It must be
specified at startup on the 'mysqld' command line or
entered in a MySQL configuration file.

*Allowing or Disallowing DDL*

By default, you can perform DDL operations such as 'ALTER TABLE'
on tables used by the 'daemon_memcached' plugin.  To avoid
potential slowdowns when these tables are used for high-throughput
applications, disable DDL operations on these tables by enabling
'innodb_api_enable_mdl' at startup.  This option is less appropriate
when accessing the same tables through both 'memcached' and SQL, because
it blocks 'CREATE INDEX' statements on the tables,
which could be important for running reporting queries.

*Storing Data on Disk, in Memory, or Both*

The 'innodb_memcache.cache_policies' table specifies whether to store
data written through the 'memcached' interface to disk ('innodb_only',
the default); in memory only, as with traditional 'memcached'
('cache-only'); or both ('caching').

With the 'caching' setting, if 'memcached' cannot find a key in memory,
it searches for the value in an 'InnoDB' table.  Values returned from
'get' calls under the 'caching' setting could be out-of-date if the
values were updated on disk in the 'InnoDB' table but are not yet
expired from the memory cache.

The caching policy can be set independently for 'get', 'set' (including
'incr' and 'decr'), 'delete', and 'flush' operations.

For example, you might allow 'get' and 'set' operations to query or
update a table and the 'memcached' memory cache at the same time (using
the 'caching' setting), while making 'delete', 'flush', or both operate
only on the in-memory copy (using the 'cache_only' setting).  That way,
deleting or flushing an item only expires the item from the cache, and
the latest value is returned from the 'InnoDB' table the next time the
item is requested.

     mysql> SELECT * FROM innodb_memcache.cache_policies;
     +--------------+-------------+-------------+---------------+--------------+
     | policy_name  | get_policy  | set_policy  | delete_policy | flush_policy |
     +--------------+-------------+-------------+---------------+--------------+
     | cache_policy | innodb_only | innodb_only | innodb_only   | innodb_only  |
     +--------------+-------------+-------------+---------------+--------------+

     mysql> UPDATE innodb_memcache.cache_policies SET set_policy = 'caching'
            WHERE policy_name = 'cache_policy';

'innodb_memcache.cache_policies' values are only read at startup.  After
changing values in this table, uninstall and reinstall the
'daemon_memcached' plugin to ensure that changes take effect.

     mysql> UNINSTALL PLUGIN daemon_memcached;

     mysql> INSTALL PLUGIN daemon_memcached soname "libmemcached.so";

14.20.5.5 Adapting DML Statements to memcached Operations
.........................................................

Benchmarks suggest that the 'daemon_memcached' plugin speeds up DML
operations (inserts, updates, and deletes) more than it speeds up
queries.  Therefore, consider focussing initial development efforts on
write-intensive applications that are I/O-bound, and look for
opportunities to use MySQL with the 'daemon_memcached' plugin for new
write-intensive applications.

Single-row DML statements are the easiest types of statements to turn
into 'memcached' operations.  'INSERT' becomes 'add', 'UPDATE' becomes
'set', 'incr' or 'decr', and 'DELETE' becomes 'delete'.  These
operations are guaranteed to only affect one row when issued through the
'memcached' interface, because the KEY is unique within the table.

In the following SQL examples, 't1' refers to the table used for
'memcached' operations, based on the configuration in the
'innodb_memcache.containers' table.  'key' refers to the column listed
under 'key_columns', and 'val' refers to the column listed under
'value_columns'.

     INSERT INTO t1 (key,val) VALUES (SOME_KEY,SOME_VALUE);
     SELECT val FROM t1 WHERE key = SOME_KEY;
     UPDATE t1 SET val = NEW_VALUE WHERE key = SOME_KEY;
     UPDATE t1 SET val = val + x WHERE key = SOME_KEY;
     DELETE FROM t1 WHERE key = SOME_KEY;

The following 'TRUNCATE TABLE' and
'DELETE' statements, which remove all rows from the table,
correspond to the 'flush_all' operation, where 't1' is configured as the
table for 'memcached' operations, as in the previous example.

     TRUNCATE TABLE t1;
     DELETE FROM t1;

14.20.5.6 Performing DML and DDL Statements on the Underlying InnoDB Table
..........................................................................

You can access the underlying 'InnoDB' table (which is 'test.demo_test'
by default) through standard SQL interfaces.  However, there are some
restrictions:

   * When querying a table that is also accessed through the 'memcached'
     interface, remember that 'memcached' operations can be configured
     to be committed periodically rather than after every write
     operation.  This behavior is controlled by the
     'daemon_memcached_w_batch_size' option.  If this option is set to a
     value greater than '1', use 'READ UNCOMMITTED' queries to find rows
     that were just inserted.

          mysql> SET SESSSION TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;

          mysql> SELECT * FROM demo_test;
          +------+------+------+------+-----------+------+------+------+------+------+------+
          | cx   | cy   | c1   | cz   | c2        | ca   | CB   | c3   | cu   | c4   | C5   |
          +------+------+------+------+-----------+------+------+------+------+------+------+
          | NULL | NULL | a11  | NULL | 123456789 | NULL | NULL |   10 | NULL |    3 | NULL |
          +------+------+------+------+-----------+------+------+------+------+------+------+

   * When modifying a table using SQL that is also accessed through the
     'memcached' interface, you can configure 'memcached' operations to
     start a new transaction periodically rather than for every read
     operation.  This behavior is controlled by the
     'daemon_memcached_r_batch_size' option.  If this option is set to a
     value greater than '1', changes made to the table using SQL are not
     immediately visible to 'memcached' operations.

   * The 'InnoDB' table is either IS (intention shared) or IX (intention
     exclusive) locked for all operations in a transaction.  If you
     increase 'daemon_memcached_r_batch_size' and
     'daemon_memcached_w_batch_size' substantially from their default
     value of '1', the table is most likely locked between each
     operation, preventing DDL statements on the table.

14.20.6 The InnoDB memcached Plugin and Replication
---------------------------------------------------

Because the 'daemon_memcached' plugin supports the MySQL binary log,
updates made on a master server through the 'memcached' interface can be
replicated for backup, balancing intensive read workloads, and high
availability.  All 'memcached' commands are supported with binary
logging.

You do not need to set up the 'daemon_memcached' plugin on slave
servers.  The primary advantage of this configuration is increased write
throughput on the master.  The speed of the replication mechanism is not
affected.

The following sections show how to use the binary log capability when
using the 'daemon_memcached' plugin with MySQL replication.  It is
assumed that you have completed the setup described in
innodb-memcached-setup.

*Enabling the InnoDB memcached Binary Log*

  1. To use the 'daemon_memcached' plugin with the MySQL binary log,
     enable the 'innodb_api_enable_binlog' configuration option on the
     master server.  This option can only be set at server startup.  You
     must also enable the MySQL binary log on the master server using
     the '--log-bin' option.  You can add these options to the MySQL
     configuration file, or on the 'mysqld' command line.

          mysqld ... --log-bin --innodb_api_enable_binlog=1

  2. Configure the master and slave server, as described in
     replication-howto.

  3. Use 'mysqldump' to create a master data snapshot,
     and sync the snapshot to the slave server.

          master shell> mysqldump --all-databases --lock-all-tables > dbdump.db
          slave shell> mysql < dbdump.db

  4. On the master server, issue 'SHOW MASTER STATUS'
     to obtain the master binary log coordinates.

          mysql> SHOW MASTER STATUS;

  5. On the slave server, use a 'CHANGE MASTER TO'
     statement to set up a slave server using the
     master binary log coordinates.

          mysql> CHANGE MASTER TO
                 MASTER_HOST='localhost',
                 MASTER_USER='root',
                 MASTER_PASSWORD='',
                 MASTER_PORT = 13000,
                 MASTER_LOG_FILE='0.000001,
                 MASTER_LOG_POS=114;

  6. Start the slave.

          mysql> START SLAVE;

     If the error log prints output similar to the following, the slave
     is ready for replication.

          2013-09-24T13:04:38.639684Z 49 [Note] Slave I/O thread: connected to
          master 'root@localhost:13000', replication started in log '0.000001'
          at position 114

*Testing the InnoDB memcached Replication Configuration*

This example demonstrates how to test the 'InnoDB' 'memcached'
replication configuration using the 'memcached' and telnet to insert,
update, and delete data.  A MySQL client is used to verify results on
the master and slave servers.

The example uses the 'demo_test' table, which was created by the
'innodb_memcached_config.sql' configuration script during the initial
setup of the 'daemon_memcached' plugin.  The 'demo_test' table contains
a single example record.

  1. Use the 'set' command to insert a record with a key of 'test1', a
     flag value of '10', an expiration value of '0', a cas value of 1,
     and a value of 't1'.

          telnet 127.0.0.1 11211
          Trying 127.0.0.1...
          Connected to 127.0.0.1.
          Escape character is '^]'.
          set test1 10 0 1
          t1
          STORED

  2. On the master server, check that the record was inserted into the
     'demo_test' table.  Assuming the 'demo_test' table was not
     previously modified, there should be two records.  The example
     record with a key of 'AA', and the record you just inserted, with a
     key of 'test1'.  The 'c1' column maps to the key, the 'c2' column
     to the value, the 'c3' column to the flag value, the 'c4' column to
     the cas value, and the 'c5' column to the expiration time.  The
     expiration time was set to 0, since it is unused.

          mysql> SELECT * FROM test.demo_test;
          +-------+--------------+------+------+------+
          | c1    | c2           | c3   | c4   | c5   |
          +-------+--------------+------+------+------+
          | AA    | HELLO, HELLO |    8 |    0 |    0 |
          | test1 | t1           |   10 |    1 |    0 |
          +-------+--------------+------+------+------+

  3. Check to verify that the same record was replicated to the slave
     server.

          mysql> SELECT * FROM test.demo_test;
          +-------+--------------+------+------+------+
          | c1    | c2           | c3   | c4   | c5   |
          +-------+--------------+------+------+------+
          | AA    | HELLO, HELLO |    8 |    0 |    0 |
          | test1 | t1           |   10 |    1 |    0 |
          +-------+--------------+------+------+------+

  4. Use the 'set' command to update the key to a value of 'new'.

          telnet 127.0.0.1 11211
          Trying 127.0.0.1...
          Connected to 127.0.0.1.
          Escape character is '^]'.
          set test1 10 0 2
          new
          STORED

     The update is replicated to the slave server (notice that the 'cas'
     value is also updated).

          mysql> SELECT * FROM test.demo_test;
          +-------+--------------+------+------+------+
          | c1    | c2           | c3   | c4   | c5   |
          +-------+--------------+------+------+------+
          | AA    | HELLO, HELLO |    8 |    0 |    0 |
          | test1 | new          |   10 |    2 |    0 |
          +-------+--------------+------+------+------+

  5. Delete the 'test1' record using a 'delete' command.

          telnet 127.0.0.1 11211
          Trying 127.0.0.1...
          Connected to 127.0.0.1.
          Escape character is '^]'.
          delete test1
          DELETED

     When the 'delete' operation is replicated to the slave, the 'test1'
     record on the slave is also deleted.

          mysql> SELECT * FROM test.demo_test;
          +----+--------------+------+------+------+
          | c1 | c2           | c3   | c4   | c5   |
          +----+--------------+------+------+------+
          | AA | HELLO, HELLO |    8 |    0 |    0 |
          +----+--------------+------+------+------+

  6. Remove all rows from the table using the 'flush_all' command.

          telnet 127.0.0.1 11211
          Trying 127.0.0.1...
          Connected to 127.0.0.1.
          Escape character is '^]'.
          flush_all
          OK

          mysql> SELECT * FROM test.demo_test;
          Empty set (0.00 sec)

  7. Telnet to the master server and enter two new records.

          telnet 127.0.0.1 11211
          Trying 127.0.0.1...
          Connected to 127.0.0.1.
          Escape character is '^]'
          set test2 10 0 4
          again
          STORED
          set test3 10 0 5
          again1
          STORED

  8. Confirm that the two records were replicated to the slave server.

          mysql> SELECT * FROM test.demo_test;
          +-------+--------------+------+------+------+
          | c1    | c2           | c3   | c4   | c5   |
          +-------+--------------+------+------+------+
          | test2 | again        |   10 |    4 |    0 |
          | test3 | again1       |   10 |    5 |    0 |
          +-------+--------------+------+------+------+

  9. Remove all rows from the table using the 'flush_all' command.

          telnet 127.0.0.1 11211
          Trying 127.0.0.1...
          Connected to 127.0.0.1.
          Escape character is '^]'.
          flush_all
          OK

  10. Check to ensure that the 'flush_all' operation was replicated on
     the slave server.

          mysql> SELECT * FROM test.demo_test;
          Empty set (0.00 sec)

*InnoDB memcached Binary Log Notes*

Binary Log Format:

   * Most 'memcached' operations are mapped to DML statements (analogous
     to insert, delete, update).  Since there is no actual SQL statement
     being processed by the MySQL server, all 'memcached' commands
     (except for 'flush_all') use Row-Based Replication (RBR) logging,
     which is independent of any server 'binlog_format' setting.

   * The 'memcached' 'flush_all' command is mapped to the
     'TRUNCATE TABLE' command.  Since DDL commands can
     only use statement-based logging, the 'flush_all' command is
     replicated by sending a 'TRUNCATE TABLE'.
     statement.

Transactions:

   * The concept of transactions has not typically been part of
     'memcached' applications.  For performance considerations,
     'daemon_memcached_r_batch_size' and 'daemon_memcached_w_batch_size'
     are used to control the batch size for read and write transactions.
     These settings do not affect replication.  Each SQL operation on
     the underlying 'InnoDB' table is replicated after successful
     completion.

   * The default value of 'daemon_memcached_w_batch_size' is '1', which
     means that each 'memcached' write operation is committed
     immediately.  This default setting incurs a certain amount of
     performance overhead to avoid inconsistencies in the data that is
     visible on the master and slave servers.  The replicated records
     are always available immediately on the slave server.  If you set
     'daemon_memcached_w_batch_size' to a value greater than '1',
     records inserted or updated through 'memcached' are not immediately
     visible on the master server; to view the records on the master
     server before they are committed, issue 'SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED'.

14.20.7 InnoDB memcached Plugin Internals
-----------------------------------------

*InnoDB API for the InnoDB memcached Plugin*

The 'InnoDB' 'memcached' engine accesses 'InnoDB' through 'InnoDB' APIs,
most of which are directly adopted from embedded 'InnoDB'.  'InnoDB' API
functions are passed to the 'InnoDB' 'memcached' engine as callback
functions.  'InnoDB' API functions access the 'InnoDB' tables directly,
and are mostly DML operations with the exception of 'TRUNCATE TABLE'.

'memcached' commands are implemented through the 'InnoDB' 'memcached'
API. The following table outlines how 'memcached' commands are mapped to
DML or DDL operations.

*memcached Commands and Associated DML or DDL Operations*

memcached          DML or DDL Operations
Command

'get'              a read/fetch command

'set'              a search followed by an 'INSERT' or 'UPDATE'
                   (depending on whether or not a key exists)

'add'              a search followed by an 'INSERT' or 'UPDATE'

'replace'          a search followed by an 'UPDATE'

'append'           a search followed by an 'UPDATE' (appends data to
                   the result before 'UPDATE')

'prepend'          a search followed by an 'UPDATE' (prepends data to
                   the result before 'UPDATE')

'incr'             a search followed by an 'UPDATE'

'decr'             a search followed by an 'UPDATE'

'delete'           a search followed by a 'DELETE'

'flush_all'        'TRUNCATE TABLE' (DDL)

*InnoDB memcached Plugin Configuration Tables*

This section describes configuration tables used by the
'daemon_memcached' plugin.  The 'cache_policies' table, 'config_options'
table, and 'containers' table are created by the
'innodb_memcached_config.sql' configuration script in the
'innodb_memcache' database.

     mysql> USE innodb_memcache;
     Database changed
     mysql> SHOW TABLES;
     +---------------------------+
     | Tables_in_innodb_memcache |
     +---------------------------+
     | cache_policies            |
     | config_options            |
     | containers                |
     +---------------------------+

*cache_policies Table*

The 'cache_policies' table defines a cache policy for the 'InnoDB'
'memcached' installation.  You can specify individual policies for
'get', 'set', 'delete', and 'flush' operations, within a single cache
policy.  The default setting for all operations is 'innodb_only'.

   * 'innodb_only': Use 'InnoDB' as the data store.

   * 'cache-only': Use the 'memcached' engine as the data store.

   * 'caching': Use both 'InnoDB' and the 'memcached' engine as data
     stores.  In this case, if 'memcached' cannot find a key in memory,
     it searches for the value in an 'InnoDB' table.

   * 'disable': Disable caching.

*cache_policies Columns*

Column                               Description

'policy_name'                        Name of the cache policy.  The
                                     default cache policy name is
                                     'cache_policy'.

'get_policy'                         The cache policy for get
                                     operations.  Valid values are
                                     'innodb_only', 'cache-only',
                                     'caching', or 'disabled'.  The
                                     default setting is 'innodb_only'.

'set_policy'                         The cache policy for set
                                     operations.  Valid values are
                                     'innodb_only', 'cache-only',
                                     'caching', or 'disabled'.  The
                                     default setting is 'innodb_only'.

'delete_policy'                      The cache policy for delete
                                     operations.  Valid values are
                                     'innodb_only', 'cache-only',
                                     'caching', or 'disabled'.  The
                                     default setting is 'innodb_only'.

'flush_policy'                       The cache policy for flush
                                     operations.  Valid values are
                                     'innodb_only', 'cache-only',
                                     'caching', or 'disabled'.  The
                                     default setting is 'innodb_only'.

*config_options Table*

The 'config_options' table stores 'memcached'-related settings that can
be changed at runtime using SQL. Supported configuration options are
'separator' and 'table_map_delimiter'.

*config_options Columns*

Column         Description

'Name'         Name of the 'memcached'-related configuration option.
               The following configuration options are supported by the
               'config_options' table:

                  * 'separator': Used to separate values of a long
                    string into separate values when there are multiple
                    'value_columns' defined.  By default, the
                    'separator' is a '|' character.  For example, if
                    you define 'col1, col2' as value columns, and you
                    define '|' as the separator, you can issue the
                    following 'memcached' command to insert values into
                    'col1' and 'col2', respectively:

                         set keyx 10 0 19
                         valuecolx|valuecoly

                    'valuecol1x' is stored in 'col1' and 'valuecoly' is
                    stored in 'col2'.

                  * 'table_map_delimiter': The character separating the
                    schema name and the table name when you use the
                    '@@' notation in a key name to access a key in a
                    specific table.  For example, '@@t1.some_key' and
                    '@@t2.some_key' have the same key value, but are
                    stored in different tables.

'Value'        The value assigned to the 'memcached'-related
               configuration option.

*containers Table*

The 'containers' table is the most important of the three configuration
tables.  Each 'InnoDB' table that is used to store 'memcached' values
must have an entry in the 'containers' table.  The entry provides a
mapping between 'InnoDB' table columns and container table columns,
which is required for 'memcached' to work with 'InnoDB' tables.

The 'containers' table contains a default entry for the 'test.demo_test'
table, which is created by the 'innodb_memcached_config.sql'
configuration script.  To use the 'daemon_memcached' plugin with your
own 'InnoDB' table, you must create an entry in the 'containers' table.

*containers Columns*

Column                 Description

'name'                 The name given to the container.  If an 'InnoDB'
                       table is not requested by name using '@@'
                       notation, the 'daemon_memcached' plugin uses the
                       'InnoDB' table with a 'containers.name' value of
                       'default'.  If there is no such entry, the first
                       entry in the 'containers' table, ordered
                       alphabetically by 'name' (ascending), determines
                       the default 'InnoDB' table.

'db_schema'            The name of the database where the 'InnoDB'
                       table resides.  This is a required value.

'db_table'             The name of the 'InnoDB' table that stores
                       'memcached' values.  This is a required value.

'key_columns'          The column in the 'InnoDB' table that contains
                       lookup key values for 'memcached' operations.
                       This is a required value.

'value_columns'        The 'InnoDB' table columns (one or more) that
                       store 'memcached' data.  Multiple columns can be
                       specified using the separator character
                       specified in the
                       'innodb_memcached.config_options' table.  By
                       default, the separator is a pipe character
                       ('|').  To specify multiple columns, separate
                       them with the defined separator character.  For
                       example: 'col1|col2|col3'.  This is a required
                       value.

'flags'                The 'InnoDB' table columns that are used as
                       flags (a user-defined numeric value that is
                       stored and retrieved along with the main value)
                       for 'memcached'.  A flag value can be used as a
                       column specifier for some operations (such as
                       'incr', 'prepend') if a 'memcached' value is
                       mapped to multiple columns, so that an operation
                       is performed on a specified column.  For
                       example, if you have mapped a 'value_columns' to
                       three 'InnoDB' table columns, and only want the
                       increment operation performed on one columns,
                       use the 'flags' column to specify the column.
                       If you do not use the 'flags' column, set a
                       value of '0' to indicate that it is unused.

'cas_column'           The 'InnoDB' table column that stores
                       compare-and-swap (cas) values.  The 'cas_column'
                       value is related to the way 'memcached' hashes
                       requests to different servers and caches data in
                       memory.  Because the 'InnoDB' 'memcached' plugin
                       is tightly integrated with a single 'memcached'
                       daemon, and the in-memory caching mechanism is
                       handled by MySQL and the InnoDB buffer pool,
                       this column is rarely needed.  If you do not use
                       this column, set a value of '0' to indicate that
                       it is unused.

'expire_time_column'   The 'InnoDB' table column that stores expiration
                       values.  The 'expire_time_column' value is
                       related to the way 'memcached' hashes requests
                       to different servers and caches data in memory.
                       Because the 'InnoDB' 'memcached' plugin is
                       tightly integrated with a single 'memcached'
                       daemon, and the in-memory caching mechanism is
                       handled by MySQL and the InnoDB buffer pool,
                       this column is rarely needed.  If you do not use
                       this column, set a value of '0' to indicate that
                       the column is unused.  The maximum expire time
                       is defined as 'INT_MAX32' or 2147483647 seconds
                       (approximately 68 years).

'unique_idx_name_on_key'The name of the index on the key column.  It
                       must be a unique index.  It can be the primary
                       key or a secondary index.  Preferably, use the
                       primary key of the 'InnoDB' table.  Using the
                       primary key avoids a lookup that is performed
                       when using a secondary index.  You cannot make a
                       covering index for 'memcached' lookups; 'InnoDB'
                       returns an error if you try to define a
                       composite secondary index over both the key and
                       value columns.

*containers Table Column Constraints*

   * You must supply a value for 'db_schema', 'db_name', 'key_columns',
     'value_columns' and 'unique_idx_name_on_key'.  Specify '0' for
     'flags', 'cas_column', and 'expire_time_column' if they are unused.
     Failing to do so could cause your setup to fail.

   * 'key_columns': The maximum limit for a 'memcached' key is 250
     characters, which is enforced by 'memcached'.  The mapped key must
     be a non-Null 'CHAR' or 'VARCHAR' type.

   * 'value_columns': Must be mapped to a 'CHAR',
     'VARCHAR', or 'BLOB' column.  There is no length
     restriction and the value can be NULL.

   * 'cas_column': The 'cas' value is a 64 bit integer.  It must be
     mapped to a 'BIGINT' of at least 8 bytes.  If
     you do not use this column, set a value of '0' to indicate that it
     is unused.

   * 'expiration_time_column': Must mapped to an 'INTEGER'
     of at least 4 bytes.  Expiration time is defined as
     a 32-bit integer for Unix time (the number of seconds since January
     1, 1970, as a 32-bit value), or the number of seconds starting from
     the current time.  For the latter, the number of seconds may not
     exceed 60*60*24*30 (the number of seconds in 30 days).  If the
     number sent by a client is larger, the server considers it to be a
     real Unix time value rather than an offset from the current time.
     If you do not use this column, set a value of '0' to indicate that
     it is unused.

   * 'flags': Must be mapped to an 'INTEGER' of at
     least 32-bits and can be NULL. If you do not use this column, set a
     value of '0' to indicate that it is unused.

A pre-check is performed at plugin load time to enforce column
constraints.  If mismatches are found, the plugin is not loaded.

*Multiple Value Column Mapping*

   * During plugin initialization, when 'InnoDB' 'memcached' is
     configured with information defined in the 'containers' table, each
     mapped column defined in 'containers.value_columns' is verified
     against the mapped 'InnoDB' table.  If multiple 'InnoDB' table
     columns are mapped, there is a check to ensure that each column
     exists and is the right type.

   * At run-time, for 'memcached' insert operations, if there are more
     delimited values than the number of mapped columns, only the number
     of mapped values are taken.  For example, if there are six mapped
     columns, and seven delimited values are provided, only the first
     six delimited values are taken.  The seventh delimited value is
     ignored.

   * If there are fewer delimited values than mapped columns, unfilled
     columns are set to NULL. If an unfilled column cannot be set to
     NULL, insert operations fail.

   * If a table has more columns than mapped values, the extra columns
     do not affect results.

*The demo_test Example Table*

The 'innodb_memcached_config.sql' configuration script creates a
'demo_test' table in the 'test' database, which can be used to verify
'InnoDB' 'memcached' plugin installation immediately after setup.

The 'innodb_memcached_config.sql' configuration script also creates an
entry for the 'demo_test' table in the 'innodb_memcache.containers'
table.

     mysql> SELECT * FROM innodb_memcache.containers\G
     *************************** 1. row ***************************
                       name: aaa
                  db_schema: test
                   db_table: demo_test
                key_columns: c1
              value_columns: c2
                      flags: c3
                 cas_column: c4
         expire_time_column: c5
     unique_idx_name_on_key: PRIMARY

     mysql> SELECT * FROM test.demo_test;
     +----+------------------+------+------+------+
     | c1 | c2               | c3   | c4   | c5   |
     +----+------------------+------+------+------+
     | AA | HELLO, HELLO     |    8 |    0 |    0 |
     +----+------------------+------+------+------+

14.20.8 Troubleshooting the InnoDB memcached Plugin
---------------------------------------------------

This section describes issues that you may encounter when using the
'InnoDB' 'memcached' plugin.

   * If you encounter the following error in the MySQL error log, the
     server might fail to start:

     'failed to set rlimit for open files. Try running as root or
     requesting smaller maxconns value.'

     The error message is from the 'memcached' daemon.  One solution is
     to raise the OS limit for the number of open files.  The commands
     for checking and increasing the open file limit varies by operating
     system.  This example shows commands for Linux and OS X:

          # Linux
          shell> ulimit -n
          1024
          shell> ulimit -n 4096
          shell> ulimit -n
          4096

          # OS X
          shell> ulimit -n
          256
          shell> ulimit -n 4096
          shell> ulimit -n
          4096

     The other solution is to reduce the number of concurrent
     connections permitted for the 'memcached' daemon.  To do so, encode
     the '-c' 'memcached' option in the 'daemon_memcached_option'
     configuration parameter in the MySQL configuration file.  The '-c'
     option has a default value of 1024.

          [mysqld]
          ...
          loose-daemon_memcached_option='-c 64'

   * To troubleshoot problems where the 'memcached' daemon is unable to
     store or retrieve 'InnoDB' table data, encode the '-vvv'
     'memcached' option in the 'daemon_memcached_option' configuration
     parameter in the MySQL configuration file.  Examine the MySQL error
     log for debug output related to 'memcached' operations.

          [mysqld]
          ...
          loose-daemon_memcached_option='-vvv'

   * If columns specified to hold 'memcached' values are the wrong data
     type, such as a numeric type instead of a string type, attempts to
     store key/value pairs fail with no specific error code or message.

   * If the 'daemon_memcached' plugin causes MySQL server startup
     issues, you can temporarily disable the 'daemon_memcached' plugin
     while troubleshooting by adding this line under the '[mysqld]'
     group in the MySQL configuration file:

          daemon_memcached=OFF

     For example, if you run the 'INSTALL PLUGIN'.
     statement before running the 'innodb_memcached_config.sql'
     configuration script to set up the necessary database and tables,
     the server might crash and fail to start.  The server could also
     fail to start if you incorrectly configure an entry in the
     'innodb_memcache.containers' table.

     To uninstall the 'memcached' plugin for a MySQL instance, issue the
     following statement:

          mysql> UNINSTALL PLUGIN daemon_memcached;

   * If you run more than one instance of MySQL on the same machine with
     the 'daemon_memcached' plugin enabled in each instance, use the
     'daemon_memcached_option' configuration parameter to specify a
     unique 'memcached' port for each 'daemon_memcached' plugin.

   * If an SQL statement cannot find the 'InnoDB' table or finds no data
     in the table, but 'memcached' API calls retrieve the expected data,
     you may be missing an entry for the 'InnoDB' table in the
     'innodb_memcache.containers' table, or you may have not switched to
     the correct 'InnoDB' table by issuing a 'get' or 'set' request
     using '@@TABLE_ID' notation.  This problem could also occur if you
     change an existing entry in the 'innodb_memcache.containers' table
     without restarting the MySQL server afterward.  The free-form
     storage mechanism is flexible enough that your requests to store or
     retrieve a multi-column value such as 'col1|col2|col3' may still
     work, even if the daemon is using the 'test.demo_test' table which
     stores values in a single column.

   * When defining your own 'InnoDB' table for use with the
     'daemon_memcached' plugin, and columns in the table are defined as
     'NOT NULL', ensure that values are supplied for the 'NOT NULL'
     columns when inserting a record for the table into the
     'innodb_memcache.containers' table.  If the 'INSERT'.
     statement for the 'innodb_memcache.containers' record contains
     fewer delimited values than there are mapped columns, unfilled
     columns are set to 'NULL'.  Attempting to insert a 'NULL' value
     into a 'NOT NULL' column causes the 'INSERT' to
     fail, which may only become evident after you reinitialize the
     'daemon_memcached' plugin to apply changes to the
     'innodb_memcache.containers' table.

   * If 'cas_column' and 'expire_time_column' fields of the
     'innodb_memcached.containers' table are set to 'NULL', the
     following error is returned when attempting to load the 'memcached'
     plugin:

          InnoDB_Memcached: column 6 in the entry for config table 'containers' in
          database 'innodb_memcache' has an invalid NULL value.

     The 'memcached' plugin rejects usage of 'NULL' in the 'cas_column'
     and 'expire_time_column' columns.  Set the value of these columns
     to '0' when the columns are unused.

   * As the length of the 'memcached' key and values increase, you might
     encounter size and length limits.

        * When the key exceeds 250 bytes, 'memcached' operations return
          an error.  This is currently a fixed limit within 'memcached'.

        * 'InnoDB' table limits may be encountered if values exceed 768
          bytes in size, 3072 bytes in size, or half of the
          'innodb_page_size' value.  These limits primarily apply if you
          intend to create an index on a value column to run
          report-generating queries on that column using SQL. See
          innodb-restrictions for details.

        * The maximum size for the key-value combination is 1 MB.

   * If you share configuration files across MySQL servers of different
     versions, using the latest configuration options for the
     'daemon_memcached' plugin could cause startup errors on older MySQL
     versions.  To avoid compatibility problems, use the 'loose' prefix
     with option names.  For example, use
     'loose-daemon_memcached_option='-c 64'' instead of
     'daemon_memcached_option='-c 64''.

   * There is no restriction or check in place to validate character set
     settings.  'memcached' stores and retrieves keys and values in
     bytes and is therefore not character set sensitive.  However, you
     must ensure that the 'memcached' client and the MySQL table use the
     same character set.

   * 'memcached' connections are blocked from accessing tables that
     contain an indexed virtual column.  Accessing an indexed virtual
     column requires a callback to the server, but a 'memcached'
     connection does not have access to the server code.

14.21 InnoDB Troubleshooting
============================

The following general guidelines apply to troubleshooting 'InnoDB'
problems:

   * When an operation fails or you suspect a bug, look at the MySQL
     server error log (see error-log).
     error-messages-server provides troubleshooting information for
     some of the common 'InnoDB'-specific errors that you may encounter.

   * If the failure is related to a deadlock, run with the
     'innodb_print_all_deadlocks' option enabled so that details about
     each deadlock are printed to the MySQL server error log.  For
     information about deadlocks, see innodb-deadlocks.

   * Issues relating to the 'InnoDB' data dictionary include failed
     'CREATE TABLE' statements (orphan table
     files), inability to open 'InnoDB' files, and 'system cannot find
     the path specified' errors.  For information about these sorts of
     problems and errors, see innodb-troubleshooting-datadict.

   * When troubleshooting, it is usually best to run the MySQL server
     from the command prompt, rather than through 'mysqld_safe'
     or as a Windows service.  You can then see what
     'mysqld' prints to the console, and so have a better grasp
     of what is going on.  On Windows, start 'mysqld'.
     with the '--console' option to direct the output to the console
     window.

   *
     Enable the 'InnoDB' Monitors to obtain information about a problem
     (see innodb-monitors).  If the problem is
     performance-related, or your server appears to be hung, you should
     enable the standard Monitor to print information about the internal
     state of 'InnoDB'.  If the problem is with locks, enable the Lock
     Monitor.  If the problem is with table creation, tablespaces, or
     data dictionary operations, refer to the InnoDB Information Schema system tables
     to
     examine contents of the 'InnoDB' internal data dictionary.

     'InnoDB' temporarily enables standard 'InnoDB' Monitor output under
     the following conditions:

        * A long semaphore wait

        * 'InnoDB' cannot find free blocks in the buffer pool

        * Over 67% of the buffer pool is occupied by lock heaps or the
          adaptive hash index

   * If you suspect that a table is corrupt, run 'CHECK TABLE'
     on that table.

14.21.1 Troubleshooting InnoDB I/O Problems
-------------------------------------------

The troubleshooting steps for 'InnoDB' I/O problems depend on when the
problem occurs: during startup of the MySQL server, or during normal
operations when a DML or DDL statement fails due to problems at the file
system level.

*Initialization Problems*

If something goes wrong when 'InnoDB' attempts to initialize its
tablespace or its log files, delete all files created by 'InnoDB': all
'ibdata' files and all 'ib_logfile' files.  If you already created some
'InnoDB' tables, also delete the corresponding '.frm' files for these
tables, and any '.ibd' files if you are using multiple tablespaces, from
the MySQL database directories.  Then try the 'InnoDB' database creation
again.  For easiest troubleshooting, start the MySQL server from a
command prompt so that you see what is happening.

*Runtime Problems*

If 'InnoDB' prints an operating system error during a file operation,
usually the problem has one of the following solutions:

   * Make sure the 'InnoDB' data file directory and the 'InnoDB' log
     directory exist.

   * Make sure 'mysqld' has access rights to create files
     in those directories.

   * Make sure 'mysqld' can read the proper 'my.cnf' or
     'my.ini' option file, so that it starts with the options that you
     specified.

   * Make sure the disk is not full and you are not exceeding any disk
     quota.

   * Make sure that the names you specify for subdirectories and data
     files do not clash.

   * Doublecheck the syntax of the 'innodb_data_home_dir' and
     'innodb_data_file_path' values.  In particular, any 'MAX' value in
     the 'innodb_data_file_path' option is a hard limit, and exceeding
     that limit causes a fatal error.

14.21.2 Forcing InnoDB Recovery
-------------------------------

To investigate database page corruption, you might dump your tables from
the database with 'SELECT ... INTO OUTFILE'.
Usually, most of the data obtained in this way is intact.  Serious
corruption might cause 'SELECT * FROM TBL_NAME' statements or 'InnoDB'
background operations to crash or assert, or even cause 'InnoDB'
roll-forward recovery to crash.  In such cases, you can use the
'innodb_force_recovery' option to force the 'InnoDB' storage engine to
start up while preventing background operations from running, so that
you can dump your tables.  For example, you can add the following line
to the '[mysqld]' section of your option file before restarting the
server:

     [mysqld]
     innodb_force_recovery = 1

*Warning*:

Only set 'innodb_force_recovery' to a value greater than 0 in an
emergency situation, so that you can start 'InnoDB' and dump your
tables.  Before doing so, ensure that you have a backup copy of your
database in case you need to recreate it.  Values of 4 or greater can
permanently corrupt data files.  Only use an 'innodb_force_recovery'
setting of 4 or greater on a production server instance after you have
successfully tested the setting on a separate physical copy of your
database.  When forcing 'InnoDB' recovery, you should always start with
'innodb_force_recovery=1' and only increase the value incrementally, as
necessary.

'innodb_force_recovery' is 0 by default (normal startup without forced
recovery).  The permissible nonzero values for 'innodb_force_recovery'
are 1 to 6.  A larger value includes the functionality of lesser values.
For example, a value of 3 includes all of the functionality of values 1
and 2.

If you are able to dump your tables with an 'innodb_force_recovery'
value of 3 or less, then you are relatively safe that only some data on
corrupt individual pages is lost.  A value of 4 or greater is considered
dangerous because data files can be permanently corrupted.  A value of 6
is considered drastic because database pages are left in an obsolete
state, which in turn may introduce more corruption into B-trees and
other database structures.

As a safety measure, 'InnoDB' prevents 'INSERT',
'UPDATE', or 'DELETE' operations when
'innodb_force_recovery' is greater than 0.  An 'innodb_force_recovery'
setting of 4 or greater places 'InnoDB' in read-only mode.

   * '1' ('SRV_FORCE_IGNORE_CORRUPT')

     Lets the server run even if it detects a corrupt page.  Tries to
     make 'SELECT * FROM TBL_NAME' jump over corrupt index records and
     pages, which helps in dumping tables.

   * '2' ('SRV_FORCE_NO_BACKGROUND')

     Prevents the master thread and any purge threads from running.  If
     a crash would occur during the purge operation, this recovery value
     prevents it.

   * '3' ('SRV_FORCE_NO_TRX_UNDO')

     Does not run transaction rollbacks after crash recovery.

   * '4' ('SRV_FORCE_NO_IBUF_MERGE')

     Prevents insert buffer merge operations.  If they would cause a
     crash, does not do them.  Does not calculate table statistics.
     This value can permanently corrupt data files.  After using this
     value, be prepared to drop and recreate all secondary indexes.
     Sets 'InnoDB' to read-only.

   * '5' ('SRV_FORCE_NO_UNDO_LOG_SCAN')

     Does not look at undo logs when starting the database: 'InnoDB'
     treats even incomplete transactions as committed.  This value can
     permanently corrupt data files.  Sets 'InnoDB' to read-only.

   * '6' ('SRV_FORCE_NO_LOG_REDO')

     Does not do the redo log roll-forward in connection with recovery.
     This value can permanently corrupt data files.  Leaves database
     pages in an obsolete state, which in turn may introduce more
     corruption into B-trees and other database structures.  Sets
     'InnoDB' to read-only.

You can 'SELECT' from tables to dump them.  With an
'innodb_force_recovery' value of 3 or less you can 'DROP' or 'CREATE'
tables.  'DROP TABLE' is also supported with an
'innodb_force_recovery' value greater than 3, up to MySQL 5.7.17.  As of
MySQL 5.7.18, see 'DROP TABLE' is not permitted with an
'innodb_force_recovery' value greater than 4.

If you know that a given table is causing a crash on rollback, you can
drop it.  If you encounter a runaway rollback caused by a failing mass
import or 'ALTER TABLE', you can kill the
'mysqld' process and set 'innodb_force_recovery' to '3' to
bring the database up without the rollback, and then 'DROP' the table
that is causing the runaway rollback.

If corruption within the table data prevents you from dumping the entire
table contents, a query with an 'ORDER BY PRIMARY_KEY DESC' clause might
be able to dump the portion of the table after the corrupted part.

If a high 'innodb_force_recovery' value is required to start 'InnoDB',
there may be corrupted data structures that could cause complex queries
(queries containing 'WHERE', 'ORDER BY', or other clauses) to fail.  In
this case, you may only be able to run basic 'SELECT * FROM t' queries.

14.21.3 Troubleshooting InnoDB Data Dictionary Operations
---------------------------------------------------------

Information about table definitions is stored both in the '.frm' files,
and in the InnoDB data dictionary.  If you move '.frm' files around, or
if the server crashes in the middle of a data dictionary operation,
these sources of information can become inconsistent.

If a data dictionary corruption or consistency issue prevents you from
starting 'InnoDB', see forcing-innodb-recovery for information
about manual recovery.

*CREATE TABLE Failure Due to Orphan Table*

A symptom of an out-of-sync data dictionary is that a 'CREATE TABLE'
statement fails.  If this occurs, look in the
server's error log.  If the log says that the table already exists
inside the 'InnoDB' internal data dictionary, you have an orphan table
inside the 'InnoDB' tablespace files that has no corresponding '.frm'
file.  The error message looks like this:

     InnoDB: Error: table test/parent already exists in InnoDB internal
     InnoDB: data dictionary. Have you deleted the .frm file
     InnoDB: and not used DROP TABLE? Have you used DROP DATABASE
     InnoDB: for InnoDB tables in MySQL version <= 3.23.43?
     InnoDB: See the Restrictions section of the InnoDB manual.
     InnoDB: You can drop the orphaned table inside InnoDB by
     InnoDB: creating an InnoDB table with the same name in another
     InnoDB: database and moving the .frm file to the current database.
     InnoDB: Then MySQL thinks the table exists, and DROP TABLE will
     InnoDB: succeed.

You can drop the orphan table by following the instructions given in the
error message.  If you are still unable to use 'DROP TABLE'
successfully, the problem may be due to name completion in
the 'mysql' client.  To work around this problem, start
the 'mysql' client with the '--skip-auto-rehash' option
and try 'DROP TABLE' again.  (With name completion
on, see 'mysql' tries to construct a list of table names,
which fails when a problem such as just described exists.)

*Cannot Open Datafile*

With 'innodb_file_per_table' enabled (the default), the following
messages may appear at startup if a file-per-table tablespace file
('.ibd' file) is missing:

     [ERROR] InnoDB: Operating system error number 2 in a file operation.
     [ERROR] InnoDB: The error means the system cannot find the path specified.
     [ERROR] InnoDB: Cannot open datafile for read-only: './test/t1.ibd' OS error: 71
     [Warning] InnoDB: Ignoring tablespace `test/t1` because it could not be opened.

To address the these messages, issue 'DROP TABLE'.
statement to remove data about the missing table from the data
dictionary.

*Cannot Open File Error*

Another symptom of an out-of-sync data dictionary is that MySQL prints
an error that it cannot open an 'InnoDB' file:

     ERROR 1016: Can't open file: 'child2.ibd'. (errno: 1)

In the error log you can find a message like this:

     InnoDB: Cannot find table test/child2 from the internal data dictionary
     InnoDB: of InnoDB though the .frm file for the table exists. Maybe you
     InnoDB: have deleted and recreated InnoDB data files but have forgotten
     InnoDB: to delete the corresponding .frm files of InnoDB tables?

This means that there is an orphan '.frm' file without a corresponding
table inside 'InnoDB'.  You can drop the orphan '.frm' file by deleting
it manually.

*Orphan Intermediate Tables*

If MySQL exits in the middle of an in-place 'ALTER TABLE'
operation ('ALGORITHM=INPLACE'), you may be left with an
orphan intermediate table that takes up space on your system.  Also, an
orphan intermediate table in an otherwise empty general tablespace
prevents you from dropping the general tablepace.  This section
describes how to identify and remove orphan intermediate tables.

Intermediate table names begin with an '#sql-ib' prefix (e.g.,
'#sql-ib87-856498050').  The accompanying '.frm' file has an '#sql-*'
prefix and is named differently (e.g., '#sql-36ab_2.frm').

To identify orphan intermediate tables on your system, you can query
'INFORMATION_SCHEMA.INNODB_SYS_TABLES'.
Look for table names that begin with '#sql'.  If the original table
resides in a file-per-table tablespace, the tablespace file (the
'#sql-*.ibd' file) for the orphan intermediate table should be visible
in the database directory.

     SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME LIKE '%#sql%';

To remove an orphan intermediate table, perform the following steps:

  1. In the database directory, rename the '#sql-*.frm' file to match
     the base name of the orphan intermediate table:

          shell> mv #sql-36ab_2.frm #sql-ib87-856498050.frm

     *Note*:

     If there is no '.frm' file, you can recreate it.  The '.frm' file
     must have the same table schema as the orphan intermediate table
     (it must have the same columns and indexes) and must be placed in
     the database directory of the orphan intermediate table.

  2. Drop the orphan intermediate table by issuing a 'DROP TABLE'
     statement, prefixing the name of the table with
     '#mysql50#' and enclosing the table name in backticks.  For
     example:

          mysql> DROP TABLE `#mysql50##sql-ib87-856498050`;

     The '#mysql50#' prefix tells MySQL to ignore 'file name safe
     encoding' introduced in MySQL 5.1.  Enclosing the table name in
     backticks is required to perform SQL statements on table names with
     special characters such as '#'.

*Note*:

If a crash occurs during an in-place 'ALTER TABLE'.
operation that was moving a table to a different tablespace, the
recovery process restores the table to its original location but leaves
an orphan intermediate table in the destination tablespace.

*Orphan Temporary Tables*

If MySQL exits in the middle of a table-copying 'ALTER TABLE'
operation ('ALGORITHM=COPY'), you may be left with an
orphan temporary table that takes up space on your system.  Also, an
orphan temporary table in an otherwise empty general tablespace prevents
you from dropping the general tablepace.  This section describes how to
identify and remove orphan temporary tables.

Orphan temporary table names begin with an '#sql-' prefix (e.g.,
'#sql-540_3').  The accompanying '.frm' file has the same base name as
the orphan temporary table.

*Note*:

If there is no '.frm' file, you can recreate it.  The '.frm' file must
have the same table schema as the orphan temporary table (it must have
the same columns and indexes) and must be placed in the database
directory of the orphan temporary table.

To identify orphan temporary tables on your system, you can query
'INFORMATION_SCHEMA.INNODB_SYS_TABLES'.  Look
for table names that begin with '#sql'.  If the original table resides
in a file-per-table tablespace, the tablespace file (the '#sql-*.ibd'
file) for the orphan temporary table should be visible in the database
directory.

     SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME LIKE '%#sql%';

To remove an orphan temporary table, drop the table by issuing a
'DROP TABLE' statement, prefixing the name of the table
with '#mysql50#' and enclosing the table name in backticks.  For
example:

     mysql> DROP TABLE `#mysql50##sql-540_3`;

The '#mysql50#' prefix tells MySQL to ignore 'file name safe encoding'
introduced in MySQL 5.1.  Enclosing the table name in backticks is
required to perform SQL statements on table names with special
characters such as '#'.

*Tablespace Does Not Exist*

With 'innodb_file_per_table' enabled, the following message might occur
if the '.frm' or '.ibd' files (or both) are missing:

     InnoDB: in InnoDB data dictionary has tablespace id N,
     InnoDB: but tablespace with that id or name does not exist. Have
     InnoDB: you deleted or moved .ibd files?
     InnoDB: This may also be a table created with CREATE TEMPORARY TABLE
     InnoDB: whose .ibd and .frm files MySQL automatically removed, but the
     InnoDB: table still exists in the InnoDB internal data dictionary.

If this occurs, try the following procedure to resolve the problem:

  1. Create a matching '.frm' file in some other database directory and
     copy it to the database directory where the orphan table is
     located.

  2. Issue 'DROP TABLE' for the original table.  That
     should successfully drop the table and 'InnoDB' should print a
     warning to the error log that the '.ibd' file was missing.

*Restoring Orphan File-Per-Table ibd Files*

This procedure describes how to restore orphan file-per-table '.ibd'
files to another MySQL instance.  You might use this procedure if the
system tablespace is lost or unrecoverable and you want to restore
'.idb' file backups on a new MySQL instance.

The procedure is not supported for general tablespace '.ibd' files.

The procedure assumes that you only have '.ibd' file backups, you are
recovering to the same version of MySQL that initially created the
orphan '.idb' files, and that '.idb' file backups are clean.  See
innodb-migration for information about creating clean backups.

Tablespace copying limitations outlined in tablespace-copying
are applicable to this procedure.

  1. On the new MySQL instance, recreate the table in a database of the
     same name.

          mysql> CREATE DATABASE sakila;

          mysql> USE sakila;

          mysql> CREATE TABLE actor (
                   actor_id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
                   first_name VARCHAR(45) NOT NULL,
                   last_name VARCHAR(45) NOT NULL,
                   last_update TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
                   PRIMARY KEY  (actor_id),
                   KEY idx_actor_last_name (last_name)
                 )ENGINE=InnoDB DEFAULT CHARSET=utf8;

  2. Discard the tablespace of the newly created table.

          mysql> ALTER TABLE sakila.actor DISCARD TABLESPACE;

  3. Copy the orphan '.idb' file from your backup directory to the new
     database directory.

          shell> cp /backup_directory/actor.ibd PATH/TO/MYSQL-5.7/DATA/sakila/

  4. Ensure that the '.ibd' file has the necessary file permissions.

  5. Import the orphan '.ibd' file.  A warning is issued indicating that
     'InnoDB' will attempt to import the file without schema
     verification.

          mysql> ALTER TABLE sakila.actor IMPORT TABLESPACE; SHOW WARNINGS;
          Query OK, 0 rows affected, 1 warning (0.15 sec)

          Warning | 1810 | InnoDB: IO Read error: (2, No such file or directory)
          Error opening './sakila/actor.cfg', will attempt to import
          without schema verification

  6. Query the table to verify that the '.ibd' file was successfully
     restored.

          mysql> SELECT COUNT(*) FROM sakila.actor;
          +----------+
          | count(*) |
          +----------+
          |      200 |
          +----------+

14.21.4 InnoDB Error Handling
-----------------------------

The following items describe how 'InnoDB' performs error handling.
'InnoDB' sometimes rolls back only the statement that failed, other
times it rolls back the entire transaction.

   * If you run out of file space in a tablespace, a MySQL 'Table is
     full' error occurs and 'InnoDB' rolls back the SQL statement.

   * A transaction deadlock causes 'InnoDB' to roll back the entire
     transaction.  Retry the whole transaction when this happens.

     A lock wait timeout causes 'InnoDB' to roll back only the single
     statement that was waiting for the lock and encountered the
     timeout.  (To have the entire transaction roll back, start the
     server with the '--innodb_rollback_on_timeout' option.)  Retry the
     statement if using the current behavior, or the entire transaction
     if using '--innodb_rollback_on_timeout'.

     Both deadlocks and lock wait timeouts are normal on busy servers
     and it is necessary for applications to be aware that they may
     happen and handle them by retrying.  You can make them less likely
     by doing as little work as possible between the first change to
     data during a transaction and the commit, so the locks are held for
     the shortest possible time and for the smallest possible number of
     rows.  Sometimes splitting work between different transactions may
     be practical and helpful.

     When a transaction rollback occurs due to a deadlock or lock wait
     timeout, it cancels the effect of the statements within the
     transaction.  But if the start-transaction statement was
     'START TRANSACTION' or 'BEGIN' statement,
     rollback does not cancel that statement.  Further SQL statements
     become part of the transaction until the occurrence of
     'COMMIT', 'ROLLBACK', or some SQL statement
     that causes an implicit commit.

   * A duplicate-key error rolls back the SQL statement, if you have not
     specified the 'IGNORE' option in your statement.

   * A 'row too long error' rolls back the SQL statement.

   * Other errors are mostly detected by the MySQL layer of code (above
     the 'InnoDB' storage engine level), and they roll back the
     corresponding SQL statement.  Locks are not released in a rollback
     of a single SQL statement.

During implicit rollbacks, as well as during the execution of an
explicit 'ROLLBACK'. SQL statement, see 'SHOW PROCESSLIST'
displays 'Rolling back' in the 'State'
column for the relevant connection.

15 Alternative Storage Engines
******************************

Storage engines are MySQL components that handle the SQL operations for
different table types.  'InnoDB' is the
default and most general-purpose storage engine, and Oracle recommends
using it for tables except for specialized use cases.  (The
'CREATE TABLE' statement in MySQL 5.7 creates 'InnoDB'
tables by default.)

MySQL Server uses a pluggable storage engine architecture that enables
storage engines to be loaded into and unloaded from a running MySQL
server.

To determine which storage engines your server supports, use the
'SHOW ENGINES' statement.  The value in the 'Support'
column indicates whether an engine can be used.  A value of 'YES', 'NO',
or 'DEFAULT' indicates that an engine is available, not available, or
available and currently set as the default storage engine.

     mysql> SHOW ENGINES\G
     *************************** 1. row ***************************
           Engine: PERFORMANCE_SCHEMA
          Support: YES
          Comment: Performance Schema
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 2. row ***************************
           Engine: InnoDB
          Support: DEFAULT
          Comment: Supports transactions, row-level locking, and foreign keys
     Transactions: YES
               XA: YES
       Savepoints: YES
     *************************** 3. row ***************************
           Engine: MRG_MYISAM
          Support: YES
          Comment: Collection of identical MyISAM tables
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 4. row ***************************
           Engine: BLACKHOLE
          Support: YES
          Comment: /dev/null storage engine (anything you write to it disappears)
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 5. row ***************************
           Engine: MyISAM
          Support: YES
          Comment: MyISAM storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO
     ...

This chapter covers use cases for special-purpose MySQL storage engines.
It does not cover the default 'InnoDB'.
storage engine or the 'NDB' storage engine which
are covered in innodb-storage-engine, and mysql-cluster.
For advanced users, this chapter also contains a description of the
pluggable storage engine architecture (see
pluggable-storage-overview).

For information about features offered in commercial MySQL Server
binaries, see 'MySQL Editions' (https://www.mysql.com/products/), on the
MySQL website.  The storage engines available might depend on which
edition of MySQL you are using.

For answers to commonly asked questions about MySQL storage engines, see
faqs-storage-engines.

*MySQL 5.7 Supported Storage Engines*

   * 'InnoDB'.: The default storage engine
     in MySQL 5.7.  'InnoDB' is a transaction-safe (ACID compliant)
     storage engine for MySQL that has commit, rollback, and
     crash-recovery capabilities to protect user data.  'InnoDB'
     row-level locking (without escalation to coarser granularity locks)
     and Oracle-style consistent nonlocking reads increase multi-user
     concurrency and performance.  'InnoDB' stores user data in
     clustered indexes to reduce I/O for common queries based on primary
     keys.  To maintain data integrity, 'InnoDB' also supports 'FOREIGN
     KEY' referential-integrity constraints.  For more information about
     'InnoDB', see innodb-storage-engine.

   * 'MyISAM'.: These tables have a small
     footprint.  Table-level locking limits the performance in
     read/write workloads, so it is often used in read-only or
     read-mostly workloads in Web and data warehousing configurations.

   * 'Memory'.: Stores all data in RAM, for
     fast access in environments that require quick lookups of
     non-critical data.  This engine was formerly known as the 'HEAP'
     engine.  Its use cases are decreasing; 'InnoDB' with its buffer
     pool memory area provides a general-purpose and durable way to keep
     most or all data in memory, and 'NDBCLUSTER' provides fast
     key-value lookups for huge distributed data sets.

   * 'CSV'.: Its tables are really text files
     with comma-separated values.  CSV tables let you import or dump
     data in CSV format, to exchange data with scripts and applications
     that read and write that same format.  Because CSV tables are not
     indexed, you typically keep the data in 'InnoDB' tables during
     normal operation, and only use CSV tables during the import or
     export stage.

   * 'Archive'.: These compact, unindexed
     tables are intended for storing and retrieving large amounts of
     seldom-referenced historical, archived, or security audit
     information.

   * 'Blackhole'.: The Blackhole storage
     engine accepts but does not store data, similar to the Unix
     '/dev/null' device.  Queries always return an empty set.  These
     tables can be used in replication configurations where DML
     statements are sent to slave servers, but the master server does
     not keep its own copy of the data.

   * 'NDB'. (also known as 'NDBCLUSTER'):
     This clustered database engine is particularly
     suited for applications that require the highest possible degree of
     uptime and availability.

   * 'Merge'.: Enables a MySQL DBA or
     developer to logically group a series of identical 'MyISAM' tables
     and reference them as one object.  Good for VLDB environments such
     as data warehousing.

   * 'Federated'.: Offers the ability to
     link separate MySQL servers to create one logical database from
     many physical servers.  Very good for distributed or data mart
     environments.

   * 'Example'.: This engine serves as an
     example in the MySQL source code that illustrates how to begin
     writing new storage engines.  It is primarily of interest to
     developers.  The storage engine is a 'stub' that does nothing.  You
     can create tables with this engine, but no data can be stored in
     them or retrieved from them.

You are not restricted to using the same storage engine for an entire
server or schema.  You can specify the storage engine for any table.
For example, an application might use mostly 'InnoDB' tables, with one
'CSV' table for exporting data to a spreadsheet and a few 'MEMORY'
tables for temporary workspaces.

*Choosing a Storage Engine*

The various storage engines provided with MySQL are designed with
different use cases in mind.  The following table provides an overview
of some storage engines provided with MySQL, with clarifying notes
following the table.

*Storage Engines Feature Summary*

Feature MyISAM       Memory       InnoDB       Archive      NDB

*B-tree Yes          Yes          Yes          No           No
indexes*

*Backup/point-in-timeYesYes       Yes          Yes          Yes
recovery*
(note
1)

*ClusterNo           No           No           No           Yes
database
support*

*ClusteredNo         No           Yes          No           No
indexes*

*CompressedYes (note No           Yes          Yes          No
data*   2)

*Data   No           N/A          Yes          No           Yes
caches*

*EncryptedYes        Yes          Yes          Yes          Yes
data*
(note
3)

*ForeignNo           No           Yes          No           Yes (note
key                                                         4)
support*

*Full-textYes        No           Yes (note    No           No
search                            5)
indexes*

*GeospatialYes       No           Yes          Yes          Yes
data
type
support*

*GeospatialYes       No           Yes (note    No           No
indexing                          6)
support*

*Hash   No           Yes          No (note     No           Yes
indexes*                          7)

*Index  Yes          N/A          Yes          No           Yes
caches*

*LockingTable        Table        Row          Row          Row
granularity*

*MVCC*  No           No           Yes          No           No

*Query  Yes          Yes          Yes          Yes          Yes
cache
support*

*ReplicationYes      Limited      Yes          Yes          Yes
support*             (note 8)
(note
1)

*Storage256TB        RAM          64TB         None         384EB
limits*

*T-tree No           No           No           No           Yes
indexes*

*Transactions*No     No           Yes          No           Yes

*Update Yes          Yes          Yes          Yes          Yes
statistics
for
data
dictionary*

*Notes:* 1.  Implemented in the server, rather than in the storage
engine.  2.  Compressed MyISAM tables are supported only when using the
compressed row format.  Tables using the compressed row format with
MyISAM are read only.  3.  Implemented in the server via encryption
functions.  Data-at-rest tablespace encryption is available in MySQL 5.7
and later.  4.  Support for foreign keys is available in MySQL Cluster
NDB 7.3 and later.  5.  InnoDB support for FULLTEXT indexes is available
in MySQL 5.6 and later.  6.  InnoDB support for geospatial indexing is
available in MySQL 5.7 and later.  7.  InnoDB utilizes hash indexes
internally for its Adaptive Hash Index feature.  8.  See the discussion
later in this section.

15.1 Setting the Storage Engine
===============================

When you create a new table, you can specify which storage engine to use
by adding an 'ENGINE' table option to the 'CREATE TABLE'
statement:

     -- ENGINE=INNODB not needed unless you have set a different
     -- default storage engine.
     CREATE TABLE t1 (i INT) ENGINE = INNODB;
     -- Simple table definitions can be switched from one to another.
     CREATE TABLE t2 (i INT) ENGINE = CSV;
     CREATE TABLE t3 (i INT) ENGINE = MEMORY;

When you omit the 'ENGINE' option, the default storage engine is used.
The default engine is 'InnoDB' in MySQL
5.7.  You can specify the default engine by using the
'--default-storage-engine' server startup option, or by setting the
'default-storage-engine' option in the 'my.cnf' configuration file.

You can set the default storage engine for the current session by
setting the 'default_storage_engine' variable:

     SET default_storage_engine=NDBCLUSTER;

The storage engine for 'TEMPORARY' tables created with 'CREATE TEMPORARY TABLE'
can be set separately from the engine
for permanent tables by setting the 'default_tmp_storage_engine', either
at startup or at runtime.

To convert a table from one storage engine to another, use an
'ALTER TABLE' statement that indicates the new engine:

     ALTER TABLE t ENGINE = InnoDB;

See create-table, and alter-table.

If you try to use a storage engine that is not compiled in or that is
compiled in but deactivated, MySQL instead creates a table using the
default storage engine.  For example, in a replication setup, perhaps
your master server uses 'InnoDB' tables for maximum safety, but the
slave servers use other storage engines for speed at the expense of
durability or concurrency.

By default, a warning is generated whenever 'CREATE TABLE'
or 'ALTER TABLE' cannot use the
default storage engine.  To prevent confusing, unintended behavior if
the desired engine is unavailable, enable the 'NO_ENGINE_SUBSTITUTION'
SQL mode.  If the desired engine is unavailable, this setting produces
an error instead of a warning, and the table is not created or altered.
See sql-mode.

For new tables, MySQL always creates an '.frm' file to hold the table
and column definitions.  The table's index and data may be stored in one
or more other files, depending on the storage engine.  The server
creates the '.frm' file above the storage engine level.  Individual
storage engines create any additional files required for the tables that
they manage.  If a table name contains special characters, the names for
the table files contain encoded versions of those characters as
described in identifier-mapping.

15.2 The MyISAM Storage Engine
==============================

'MyISAM' is based on the older (and no longer available) 'ISAM' storage
engine but has many useful extensions.

*MyISAM Storage Engine Features*

Feature                                     Support

*B-tree indexes*                            Yes

*Backup/point-in-time recovery*             Yes
(Implemented in the server, rather than
in the storage engine.)

*Cluster database support*                  No

*Clustered indexes*                         No

*Compressed data*                           Yes (Compressed MyISAM
                                            tables are supported only
                                            when using the compressed
                                            row format.  Tables using
                                            the compressed row format
                                            with MyISAM are read only.)

*Data caches*                               No

*Encrypted data* (Implemented in the        Yes
server via encryption functions.
Data-at-rest tablespace encryption is
available in MySQL 5.7 and later.)

*Foreign key support*                       No

*Full-text search indexes*                  Yes

*Geospatial data type support*              Yes

*Geospatial indexing support*               Yes

*Hash indexes*                              No

*Index caches*                              Yes

*Locking granularity*                       Table

*MVCC*                                      No

*Query cache support*                       Yes

*Replication support* (Implemented in the   Yes
server, rather than in the storage
engine.)

*Storage limits*                            256TB

*T-tree indexes*                            No

*Transactions*                              No

*Update statistics for data dictionary*     Yes

Each 'MyISAM' table is stored on disk in three files.  The files have
names that begin with the table name and have an extension to indicate
the file type.  An '.frm' file stores the table format.  The data file
has an '.MYD' ('MYData') extension.  The index file has an '.MYI'
('MYIndex') extension.

To specify explicitly that you want a 'MyISAM' table, indicate that with
an 'ENGINE' table option:

     CREATE TABLE t (i INT) ENGINE = MYISAM;

In MySQL 5.7, it is normally necessary to use 'ENGINE' to specify the
'MyISAM' storage engine because 'InnoDB' is the default engine.

You can check or repair 'MyISAM' tables with the 'mysqlcheck'
client or 'myisamchk' utility.  You can
also compress 'MyISAM' tables with 'myisampack' to
take up much less space.  See mysqlcheck, myisamchk, and
myisampack.

'MyISAM' tables have the following characteristics:

   * All data values are stored with the low byte first.  This makes the
     data machine and operating system independent.  The only
     requirements for binary portability are that the machine uses
     two's-complement signed integers and IEEE floating-point format.
     These requirements are widely used among mainstream machines.
     Binary compatibility might not be applicable to embedded systems,
     which sometimes have peculiar processors.

     There is no significant speed penalty for storing data low byte
     first; the bytes in a table row normally are unaligned and it takes
     little more processing to read an unaligned byte in order than in
     reverse order.  Also, the code in the server that fetches column
     values is not time critical compared to other code.

   * All numeric key values are stored with the high byte first to
     permit better index compression.

   * Large files (up to 63-bit file length) are supported on file
     systems and operating systems that support large files.

   * There is a limit of (2^32)^2 (1.844E+19) rows in a 'MyISAM' table.

   * The maximum number of indexes per 'MyISAM' table is 64.

     The maximum number of columns per index is 16.

   * The maximum key length is 1000 bytes.  This can also be changed by
     changing the source and recompiling.  For the case of a key longer
     than 250 bytes, a larger key block size than the default of 1024
     bytes is used.

   * When rows are inserted in sorted order (as when you are using an
     'AUTO_INCREMENT' column), the index tree is split so that the high
     node only contains one key.  This improves space utilization in the
     index tree.

   * Internal handling of one 'AUTO_INCREMENT' column per table is
     supported.  'MyISAM' automatically updates this column for
     'INSERT' and 'UPDATE' operations.  This
     makes 'AUTO_INCREMENT' columns faster (at least 10%).  Values at
     the top of the sequence are not reused after being deleted.  (When
     an 'AUTO_INCREMENT' column is defined as the last column of a
     multiple-column index, reuse of values deleted from the top of a
     sequence does occur.)  The 'AUTO_INCREMENT' value can be reset with
     'ALTER TABLE' or 'myisamchk'.

   * Dynamic-sized rows are much less fragmented when mixing deletes
     with updates and inserts.  This is done by automatically combining
     adjacent deleted blocks and by extending blocks if the next block
     is deleted.

   * 'MyISAM' supports concurrent inserts: If a table has no free blocks
     in the middle of the data file, you can 'INSERT' new
     rows into it at the same time that other threads are reading from
     the table.  A free block can occur as a result of deleting rows or
     an update of a dynamic length row with more data than its current
     contents.  When all free blocks are used up (filled in), future
     inserts become concurrent again.  See concurrent-inserts.

   * You can put the data file and index file in different directories
     on different physical devices to get more speed with the 'DATA
     DIRECTORY' and 'INDEX DIRECTORY' table options to 'CREATE TABLE'.
     See create-table.

   * 'BLOB' and 'TEXT' columns can be indexed.

   * 'NULL' values are permitted in indexed columns.  This takes 0 to 1
     bytes per key.

   * Each character column can have a different character set.  See
     charset.

   * There is a flag in the 'MyISAM' index file that indicates whether
     the table was closed correctly.  If 'mysqld' is
     started with the '--myisam-recover-options' option, 'MyISAM' tables
     are automatically checked when opened, and are repaired if the
     table wasn't closed properly.

   * 'myisamchk' marks tables as checked if you run it
     with the '--update-state' option.  'myisamchk --fast'
     checks only those tables that don't have this mark.

   * 'myisamchk --analyze' stores statistics for
     portions of keys, as well as for entire keys.

   * 'myisampack' can pack 'BLOB' and
     'VARCHAR' columns.

'MyISAM' also supports the following features:

   * Support for a true 'VARCHAR' type; a 'VARCHAR'
     column starts with a length stored in one or two bytes.

   * Tables with 'VARCHAR' columns may have fixed or
     dynamic row length.

   * The sum of the lengths of the 'VARCHAR' and
     'CHAR' columns in a table may be up to 64KB.

   * Arbitrary length 'UNIQUE' constraints.

*Additional Resources*

   * A forum dedicated to the 'MyISAM' storage engine is available at
     <http://forums.mysql.com/list.php?21>.

15.2.1 MyISAM Startup Options
-----------------------------

The following options to 'mysqld' can be used to change
the behavior of 'MyISAM' tables.  For additional information, see
server-options.

*MyISAM Option and Variable Reference*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

bulk_insert_buffer_sizeYes Yes         Yes                     Both        Yes

concurrent_insertYes       Yes         Yes                     Global      Yes

delay-key-writeYes         Yes                                 Global      Yes

-                                      Yes                     Global      Yes
_Variable_:
delay_key_write

have_rtree_keys                        Yes                     Global      No

key_buffer_sizeYes         Yes         Yes                     Global      Yes

log-isam       Yes         Yes

myisam-block-sizeYes       Yes

myisam_data_pointer_sizeYesYes         Yes                     Global      Yes

myisam_max_sort_file_sizeYesYes        Yes                     Global      Yes

myisam_mmap_sizeYes        Yes         Yes                     Global      No

myisam-recover-optionsYes  Yes

-
_Variable_:
myisam_recover_options

myisam_recover_options                 Yes                     Global      No

myisam_repair_threadsYes   Yes         Yes                     Both        Yes

myisam_sort_buffer_sizeYes Yes         Yes                     Both        Yes

myisam_stats_methodYes     Yes         Yes                     Both        Yes

myisam_use_mmapYes         Yes         Yes                     Global      Yes

skip-concurrent-insertYes  Yes

-
_Variable_:
concurrent_insert

tmp_table_size Yes         Yes         Yes                     Both        Yes

   *
     '--myisam-recover-options=MODE'

     Set the mode for automatic recovery of crashed 'MyISAM' tables.

   *
     '--delay-key-write=ALL'

     Don't flush key buffers between writes for any 'MyISAM' table.

     *Note*:

     If you do this, you should not access 'MyISAM' tables from another
     program (such as from another MySQL server or with
     'myisamchk') when the tables are in use.  Doing so
     risks index corruption.  Using '--external-locking' does not
     eliminate this risk.

The following system variables affect the behavior of 'MyISAM' tables.
For additional information, see server-system-variables.

   * 'bulk_insert_buffer_size'

     The size of the tree cache used in bulk insert optimization.

     *Note*:

     This is a limit _per thread_!

   * 'myisam_max_sort_file_size'

     The maximum size of the temporary file that MySQL is permitted to
     use while re-creating a 'MyISAM' index (during 'REPAIR TABLE',
     see 'ALTER TABLE', or
     'LOAD DATA INFILE').  If the file size would be larger
     than this value, the index is created using the key cache instead,
     which is slower.  The value is given in bytes.

   * 'myisam_sort_buffer_size'

     Set the size of the buffer used when recovering tables.

Automatic recovery is activated if you start 'mysqld'.
with the '--myisam-recover-options' option.  In this case, when the
server opens a 'MyISAM' table, it checks whether the table is marked as
crashed or whether the open count variable for the table is not 0 and
you are running the server with external locking disabled.  If either of
these conditions is true, the following happens:

   * The server checks the table for errors.

   * If the server finds an error, it tries to do a fast table repair
     (with sorting and without re-creating the data file).

   * If the repair fails because of an error in the data file (for
     example, a duplicate-key error), the server tries again, this time
     re-creating the data file.

   * If the repair still fails, the server tries once more with the old
     repair option method (write row by row without sorting).  This
     method should be able to repair any type of error and has low disk
     space requirements.

If the recovery wouldn't be able to recover all rows from previously
completed statements and you didn't specify 'FORCE' in the value of the
'--myisam-recover-options' option, automatic repair aborts with an error
message in the error log:

     Error: Couldn't repair table: test.g00pages

If you specify 'FORCE', a warning like this is written instead:

     Warning: Found 344 of 354 rows when repairing ./test/g00pages

If the automatic recovery value includes 'BACKUP', the recovery process
creates files with names of the form 'TBL_NAME-DATETIME.BAK'.  You
should have a 'cron' script that automatically moves these files from
the database directories to backup media.

15.2.2 Space Needed for Keys
----------------------------

'MyISAM' tables use B-tree indexes.  You can roughly calculate the size
for the index file as '(key_length+4)/0.67', summed over all keys.  This
is for the worst case when all keys are inserted in sorted order and the
table doesn't have any compressed keys.

String indexes are space compressed.  If the first index part is a
string, it is also prefix compressed.  Space compression makes the index
file smaller than the worst-case figure if a string column has a lot of
trailing space or is a 'VARCHAR' column that is not always
used to the full length.  Prefix compression is used on keys that start
with a string.  Prefix compression helps if there are many strings with
an identical prefix.

In 'MyISAM' tables, you can also prefix compress numbers by specifying
the 'PACK_KEYS=1' table option when you create the table.  Numbers are
stored with the high byte first, so this helps when you have many
integer keys that have an identical prefix.

15.2.3 MyISAM Table Storage Formats
-----------------------------------

'MyISAM' supports three different storage formats.  Two of them, fixed
and dynamic format, are chosen automatically depending on the type of
columns you are using.  The third, compressed format, can be created
only with the 'myisampack' utility (see
myisampack).

When you use 'CREATE TABLE' or 'ALTER TABLE'
for a table that has no 'BLOB' or
'TEXT' columns, you can force the table format to 'FIXED' or
'DYNAMIC' with the 'ROW_FORMAT' table option.

See create-table, for information about 'ROW_FORMAT'.

You can decompress (unpack) compressed 'MyISAM' tables using
'myisamchk --unpack'.; see myisamchk, for more
information.

15.2.3.1 Static (Fixed-Length) Table Characteristics
....................................................

Static format is the default for 'MyISAM' tables.  It is used when the
table contains no variable-length columns (see 'VARCHAR',
'VARBINARY', 'BLOB', or 'TEXT').
Each row is stored using a fixed number of bytes.

Of the three 'MyISAM' storage formats, static format is the simplest and
most secure (least subject to corruption).  It is also the fastest of
the on-disk formats due to the ease with which rows in the data file can
be found on disk: To look up a row based on a row number in the index,
multiply the row number by the row length to calculate the row position.
Also, when scanning a table, it is very easy to read a constant number
of rows with each disk read operation.

The security is evidenced if your computer crashes while the MySQL
server is writing to a fixed-format 'MyISAM' file.  In this case, see
'myisamchk' can easily determine where each row starts and
ends, so it can usually reclaim all rows except the partially written
one.  'MyISAM' table indexes can always be reconstructed based on the
data rows.

*Note*:

Fixed-length row format is only available for tables without
'BLOB' or 'TEXT' columns.  Creating a table with
these columns with an explicit 'ROW_FORMAT' clause will not raise an
error or warning; the format specification will be ignored.

Static-format tables have these characteristics:

   * 'CHAR' and 'VARCHAR' columns are
     space-padded to the specified column width, although the column
     type is not altered.  'BINARY' and
     'VARBINARY' columns are padded with '0x00' bytes
     to the column width.

   * 'NULL' columns require additional space in the row to record
     whether their values are 'NULL'.  Each 'NULL' column takes one bit
     extra, rounded up to the nearest byte.

   * Very quick.

   * Easy to cache.

   * Easy to reconstruct after a crash, because rows are located in
     fixed positions.

   * Reorganization is unnecessary unless you delete a huge number of
     rows and want to return free disk space to the operating system.
     To do this, use 'OPTIMIZE TABLE' or
     'myisamchk -r'.

   * Usually require more disk space than dynamic-format tables.

   * The expected row length in bytes for static-sized rows is
     calculated using the following expression:

          row length = 1
                       + (SUM OF COLUMN LENGTHS)
                       + (NUMBER OF NULL COLUMNS + DELETE_FLAG + 7)/8
                       + (NUMBER OF VARIABLE-LENGTH COLUMNS)

     DELETE_FLAG is 1 for tables with static row format.  Static tables
     use a bit in the row record for a flag that indicates whether the
     row has been deleted.  DELETE_FLAG is 0 for dynamic tables because
     the flag is stored in the dynamic row header.

15.2.3.2 Dynamic Table Characteristics
......................................

Dynamic storage format is used if a 'MyISAM' table contains any
variable-length columns (see 'VARCHAR', 'VARBINARY',
see 'BLOB', or 'TEXT'), or if the
table was created with the 'ROW_FORMAT=DYNAMIC' table option.

Dynamic format is a little more complex than static format because each
row has a header that indicates how long it is.  A row can become
fragmented (stored in noncontiguous pieces) when it is made longer as a
result of an update.

You can use 'OPTIMIZE TABLE' or 'myisamchk -r'
to defragment a table.  If you have fixed-length columns
that you access or change frequently in a table that also contains some
variable-length columns, it might be a good idea to move the
variable-length columns to other tables just to avoid fragmentation.

Dynamic-format tables have these characteristics:

   * All string columns are dynamic except those with a length less than
     four.

   * Each row is preceded by a bitmap that indicates which columns
     contain the empty string (for string columns) or zero (for numeric
     columns).  This does not include columns that contain 'NULL'
     values.  If a string column has a length of zero after trailing
     space removal, or a numeric column has a value of zero, it is
     marked in the bitmap and not saved to disk.  Nonempty strings are
     saved as a length byte plus the string contents.

   * 'NULL' columns require additional space in the row to record
     whether their values are 'NULL'.  Each 'NULL' column takes one bit
     extra, rounded up to the nearest byte.

   * Much less disk space usually is required than for fixed-length
     tables.

   * Each row uses only as much space as is required.  However, if a row
     becomes larger, it is split into as many pieces as are required,
     resulting in row fragmentation.  For example, if you update a row
     with information that extends the row length, the row becomes
     fragmented.  In this case, you may have to run 'OPTIMIZE TABLE'
     or 'myisamchk -r' from
     time to time to improve performance.  Use 'myisamchk -ei'
     to obtain table statistics.

   * More difficult than static-format tables to reconstruct after a
     crash, because rows may be fragmented into many pieces and links
     (fragments) may be missing.

   * The expected row length for dynamic-sized rows is calculated using
     the following expression:

          3
          + (NUMBER OF COLUMNS + 7) / 8
          + (NUMBER OF CHAR COLUMNS)
          + (PACKED SIZE OF NUMERIC COLUMNS)
          + (LENGTH OF STRINGS)
          + (NUMBER OF NULL COLUMNS + 7) / 8

     There is a penalty of 6 bytes for each link.  A dynamic row is
     linked whenever an update causes an enlargement of the row.  Each
     new link is at least 20 bytes, so the next enlargement probably
     goes in the same link.  If not, another link is created.  You can
     find the number of links using 'myisamchk -ed'.
     All links may be removed with 'OPTIMIZE TABLE'
     or 'myisamchk -r'.

15.2.3.3 Compressed Table Characteristics
.........................................

Compressed storage format is a read-only format that is generated with
the 'myisampack' tool.  Compressed tables can be
uncompressed with 'myisamchk'.

Compressed tables have the following characteristics:

   * Compressed tables take very little disk space.  This minimizes disk
     usage, which is helpful when using slow disks (such as CD-ROMs).

   * Each row is compressed separately, so there is very little access
     overhead.  The header for a row takes up one to three bytes
     depending on the biggest row in the table.  Each column is
     compressed differently.  There is usually a different Huffman tree
     for each column.  Some of the compression types are:

        * Suffix space compression.

        * Prefix space compression.

        * Numbers with a value of zero are stored using one bit.

        * If values in an integer column have a small range, the column
          is stored using the smallest possible type.  For example, a
          'BIGINT' column (eight bytes) can be
          stored as a 'TINYINT' column (one byte)
          if all its values are in the range from '-128' to '127'.

        * If a column has only a small set of possible values, the data
          type is converted to 'ENUM'.

        * A column may use any combination of the preceding compression
          types.

   * Can be used for fixed-length or dynamic-length rows.

*Note*:

While a compressed table is read only, and you cannot therefore update
or add rows in the table, DDL (Data Definition Language) operations are
still valid.  For example, you may still use 'DROP' to drop the table,
and 'TRUNCATE TABLE' to empty the table.

15.2.4 MyISAM Table Problems
----------------------------

The file format that MySQL uses to store data has been extensively
tested, but there are always circumstances that may cause database
tables to become corrupted.  The following discussion describes how this
can happen and how to handle it.

15.2.4.1 Corrupted MyISAM Tables
................................

Even though the 'MyISAM' table format is very reliable (all changes to a
table made by an SQL statement are written before the statement
returns), you can still get corrupted tables if any of the following
events occur:

   * The 'mysqld' process is killed in the middle of a
     write.

   * An unexpected computer shutdown occurs (for example, the computer
     is turned off).

   * Hardware failures.

   * You are using an external program (such as 'myisamchk')
     to modify a table that is being modified by the server
     at the same time.

   * A software bug in the MySQL or 'MyISAM' code.

Typical symptoms of a corrupt table are:

   * You get the following error while selecting data from the table:

          Incorrect key file for table: '...'. Try to repair it

   * Queries don't find rows in the table or return incomplete results.

You can check the health of a 'MyISAM' table using the 'CHECK TABLE'
statement, and repair a corrupted 'MyISAM' table
with 'REPAIR TABLE'.  When 'mysqld'.
is not running, you can also check or repair a table with the
'myisamchk' command.  See check-table,
repair-table, and myisamchk.

If your tables become corrupted frequently, you should try to determine
why this is happening.  The most important thing to know is whether the
table became corrupted as a result of a server crash.  You can verify
this easily by looking for a recent 'restarted mysqld' message in the
error log.  If there is such a message, it is likely that table
corruption is a result of the server dying.  Otherwise, corruption may
have occurred during normal operation.  This is a bug.  You should try
to create a reproducible test case that demonstrates the problem.  See
crashing, and porting.

15.2.4.2 Problems from Tables Not Being Closed Properly
.......................................................

Each 'MyISAM' index file ('.MYI' file) has a counter in the header that
can be used to check whether a table has been closed properly.  If you
get the following warning from 'CHECK TABLE' or
'myisamchk', it means that this counter has gone out of
sync:

     clients are using or haven't closed the table properly

This warning doesn't necessarily mean that the table is corrupted, but
you should at least check the table.

The counter works as follows:

   * The first time a table is updated in MySQL, a counter in the header
     of the index files is incremented.

   * The counter is not changed during further updates.

   * When the last instance of a table is closed (because a 'FLUSH
     TABLES' operation was performed or because there is no room in the
     table cache), the counter is decremented if the table has been
     updated at any point.

   * When you repair the table or check the table and it is found to be
     okay, the counter is reset to zero.

   * To avoid problems with interaction with other processes that might
     check the table, the counter is not decremented on close if it was
     zero.

In other words, the counter can become incorrect only under these
conditions:

   * A 'MyISAM' table is copied without first issuing 'LOCK TABLES'
     and 'FLUSH TABLES'.

   * MySQL has crashed between an update and the final close.  (The
     table may still be okay because MySQL always issues writes for
     everything between each statement.)

   * A table was modified by 'myisamchk --recover' or
     'myisamchk --update-state' at the same time that
     it was in use by 'mysqld'.

   * Multiple 'mysqld' servers are using the table and
     one server performed a 'REPAIR TABLE' or
     'CHECK TABLE' on the table while it was in use by
     another server.  In this setup, it is safe to use 'CHECK TABLE',
     although you might get the warning from other
     servers.  However, see 'REPAIR TABLE' should be
     avoided because when one server replaces the data file with a new
     one, this is not known to the other servers.

     In general, it is a bad idea to share a data directory among
     multiple servers.  See multiple-servers, for additional
     discussion.

15.3 The MEMORY Storage Engine
==============================

The 'MEMORY' storage engine (formerly known as 'HEAP') creates
special-purpose tables with contents that are stored in memory.  Because
the data is vulnerable to crashes, hardware issues, or power outages,
only use these tables as temporary work areas or read-only caches for
data pulled from other tables.

*MEMORY Storage Engine Features*

Feature                                     Support

*B-tree indexes*                            Yes

*Backup/point-in-time recovery*             Yes
(Implemented in the server, rather than
in the storage engine.)

*Cluster database support*                  No

*Clustered indexes*                         No

*Compressed data*                           No

*Data caches*                               N/A

*Encrypted data* (Implemented in the        Yes
server via encryption functions.
Data-at-rest tablespace encryption is
available in MySQL 5.7 and later.)

*Foreign key support*                       No

*Full-text search indexes*                  No

*Geospatial data type support*              No

*Geospatial indexing support*               No

*Hash indexes*                              Yes

*Index caches*                              N/A

*Locking granularity*                       Table

*MVCC*                                      No

*Query cache support*                       Yes

*Replication support* (Implemented in the   Limited (See the discussion
server, rather than in the storage          later in this section.)
engine.)

*Storage limits*                            RAM

*T-tree indexes*                            No

*Transactions*                              No

*Update statistics for data dictionary*     Yes

   * memory-storage-engine-compared-cluster

   * memory-storage-engine-performance-characteristics

   * memory-storage-engine-characteristics-of-memory-tables

   * memory-storage-engine-ddl-operations-for-memory-tables

   * memory-storage-engine-indexes

   * memory-storage-engine-user-created-and-temporary-tables

   * memory-storage-engine-loading-data

   * memory-tables-replication

   * memory-storage-engine-managing-memory-use

   * memory-storage-engine-additional-resources

*When to Use MEMORY or NDB Cluster*

Developers looking to deploy applications that use the 'MEMORY' storage
engine for important, highly available, or frequently updated data
should consider whether NDB Cluster is a better choice.  A typical use
case for the 'MEMORY' engine involves these characteristics:

   * Operations involving transient, non-critical data such as session
     management or caching.  When the MySQL server halts or restarts,
     the data in 'MEMORY' tables is lost.

   * In-memory storage for fast access and low latency.  Data volume can
     fit entirely in memory without causing the operating system to swap
     out virtual memory pages.

   * A read-only or read-mostly data access pattern (limited updates).

NDB Cluster offers the same features as the 'MEMORY' engine with higher
performance levels, and provides additional features not available with
'MEMORY':

   * Row-level locking and multiple-thread operation for low contention
     between clients.

   * Scalability even with statement mixes that include writes.

   * Optional disk-backed operation for data durability.

   * Shared-nothing architecture and multiple-host operation with no
     single point of failure, enabling 99.999% availability.

   * Automatic data distribution across nodes; application developers
     need not craft custom sharding or partitioning solutions.

   * Support for variable-length data types (including 'BLOB'
     and 'TEXT') not supported by 'MEMORY'.

*Performance Characteristics*

'MEMORY' performance is constrained by contention resulting from
single-thread execution and table lock overhead when processing updates.
This limits scalability when load increases, particularly for statement
mixes that include writes.

Despite the in-memory processing for 'MEMORY' tables, they are not
necessarily faster than 'InnoDB' tables on
a busy server, for general-purpose queries, or under a read/write
workload.  In particular, the table locking involved with performing
updates can slow down concurrent usage of 'MEMORY' tables from multiple
sessions.

Depending on the kinds of queries performed on a 'MEMORY' table, you
might create indexes as either the default hash data structure (for
looking up single values based on a unique key), or a general-purpose
B-tree data structure (for all kinds of queries involving equality,
inequality, or range operators such as less than or greater than).  The
following sections illustrate the syntax for creating both kinds of
indexes.  A common performance issue is using the default hash indexes
in workloads where B-tree indexes are more efficient.

*Characteristics of MEMORY Tables*

The 'MEMORY' storage engine associates each table with one disk file,
which stores the table definition (not the data).  The file name begins
with the table name and has an extension of '.frm'.

'MEMORY' tables have the following characteristics:

   * Space for 'MEMORY' tables is allocated in small blocks.  Tables use
     100% dynamic hashing for inserts.  No overflow area or extra key
     space is needed.  No extra space is needed for free lists.  Deleted
     rows are put in a linked list and are reused when you insert new
     data into the table.  'MEMORY' tables also have none of the
     problems commonly associated with deletes plus inserts in hashed
     tables.

   * 'MEMORY' tables use a fixed-length row-storage format.
     Variable-length types such as 'VARCHAR' are stored
     using a fixed length.

   * 'MEMORY' tables cannot contain 'BLOB' or 'TEXT'
     columns.

   * 'MEMORY' includes support for 'AUTO_INCREMENT' columns.

   * Non-'TEMPORARY' 'MEMORY' tables are shared among all clients, just
     like any other non-'TEMPORARY' table.

*DDL Operations for MEMORY Tables*

To create a 'MEMORY' table, specify the clause 'ENGINE=MEMORY' on the
'CREATE TABLE' statement.

     CREATE TABLE t (i INT) ENGINE = MEMORY;

As indicated by the engine name, 'MEMORY' tables are stored in memory.
They use hash indexes by default, which makes them very fast for
single-value lookups, and very useful for creating temporary tables.
However, when the server shuts down, all rows stored in 'MEMORY' tables
are lost.  The tables themselves continue to exist because their
definitions are stored in '.frm' files on disk, but they are empty when
the server restarts.

This example shows how you might create, use, and remove a 'MEMORY'
table:

     mysql> CREATE TABLE test ENGINE=MEMORY
         ->     SELECT ip,SUM(downloads) AS down
         ->     FROM log_table GROUP BY ip;
     mysql> SELECT COUNT(ip),AVG(down) FROM test;
     mysql> DROP TABLE test;

The maximum size of 'MEMORY' tables is limited by the
'max_heap_table_size' system variable, which has a default value of
16MB. To enforce different size limits for 'MEMORY' tables, change the
value of this variable.  The value in effect for 'CREATE TABLE',
or a subsequent 'ALTER TABLE' or
'TRUNCATE TABLE', is the value used for the life of the
table.  A server restart also sets the maximum size of existing 'MEMORY'
tables to the global 'max_heap_table_size' value.  You can set the size
for individual tables as described later in this section.

*Indexes*

The 'MEMORY' storage engine supports both 'HASH' and 'BTREE' indexes.
You can specify one or the other for a given index by adding a 'USING'
clause as shown here:

     CREATE TABLE lookup
         (id INT, INDEX USING HASH (id))
         ENGINE = MEMORY;
     CREATE TABLE lookup
         (id INT, INDEX USING BTREE (id))
         ENGINE = MEMORY;

For general characteristics of B-tree and hash indexes, see
mysql-indexes.

'MEMORY' tables can have up to 64 indexes per table, 16 columns per
index and a maximum key length of 3072 bytes.

If a 'MEMORY' table hash index has a high degree of key duplication
(many index entries containing the same value), updates to the table
that affect key values and all deletes are significantly slower.  The
degree of this slowdown is proportional to the degree of duplication
(or, inversely proportional to the index cardinality).  You can use a
'BTREE' index to avoid this problem.

'MEMORY' tables can have nonunique keys.  (This is an uncommon feature
for implementations of hash indexes.)

Columns that are indexed can contain 'NULL' values.

*User-Created and Temporary Tables*

'MEMORY' table contents are stored in memory, which is a property that
'MEMORY' tables share with internal temporary tables that the server
creates on the fly while processing queries.  However, the two types of
tables differ in that 'MEMORY' tables are not subject to storage
conversion, whereas internal temporary tables are:

   * If an internal temporary table becomes too large, the server
     automatically converts it to on-disk storage, as described in
     internal-temporary-tables.

   * User-created 'MEMORY' tables are never converted to disk tables.

*Loading Data*

To populate a 'MEMORY' table when the MySQL server starts, you can use
the '--init-file' option.  For example, you can put statements such as
'INSERT INTO ... SELECT' or 'LOAD DATA INFILE'
into this file to load the table from a persistent
data source.  See server-options, and load-data.

*MEMORY Tables and Replication*

A server's 'MEMORY' tables become empty when it is shut down and
restarted.  If the server is a replication master, its slaves are not
aware that these tables have become empty, so you see out-of-date
content if you select data from the tables on the slaves.  To
synchronize master and slave 'MEMORY' tables, when a 'MEMORY' table is
used on a master for the first time since it was started, a
'DELETE' statement is written to the master's binary log, to
empty the table on the slaves also.  The slave still has outdated data
in the table during the interval between the master's restart and its
first use of the table.  To avoid this interval when a direct query to
the slave could return stale data, use the '--init-file' option to
populate the 'MEMORY' table on the master at startup.

*Managing Memory Use*

The server needs sufficient memory to maintain all 'MEMORY' tables that
are in use at the same time.

Memory is not reclaimed if you delete individual rows from a 'MEMORY'
table.  Memory is reclaimed only when the entire table is deleted.
Memory that was previously used for deleted rows is re-used for new rows
within the same table.  To free all the memory used by a 'MEMORY' table
when you no longer require its contents, execute 'DELETE'.
or 'TRUNCATE TABLE' to remove all rows, or remove
the table altogether using 'DROP TABLE'.  To free up
the memory used by deleted rows, use 'ALTER TABLE ENGINE=MEMORY' to
force a table rebuild.

The memory needed for one row in a 'MEMORY' table is calculated using
the following expression:

     SUM_OVER_ALL_BTREE_KEYS(MAX_LENGTH_OF_KEY + sizeof(char*) * 4)
     + SUM_OVER_ALL_HASH_KEYS(sizeof(char*) * 2)
     + ALIGN(LENGTH_OF_ROW+1, sizeof(char*))

'ALIGN()' represents a round-up factor to cause the row length to be an
exact multiple of the 'char' pointer size.  'sizeof(char*)' is 4 on
32-bit machines and 8 on 64-bit machines.

As mentioned earlier, the 'max_heap_table_size' system variable sets the
limit on the maximum size of 'MEMORY' tables.  To control the maximum
size for individual tables, set the session value of this variable
before creating each table.  (Do not change the global
'max_heap_table_size' value unless you intend the value to be used for
'MEMORY' tables created by all clients.)  The following example creates
two 'MEMORY' tables, with a maximum size of 1MB and 2MB, respectively:

     mysql> SET max_heap_table_size = 1024*1024;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t1 (id INT, UNIQUE(id)) ENGINE = MEMORY;
     Query OK, 0 rows affected (0.01 sec)

     mysql> SET max_heap_table_size = 1024*1024*2;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t2 (id INT, UNIQUE(id)) ENGINE = MEMORY;
     Query OK, 0 rows affected (0.00 sec)

Both tables revert to the server's global 'max_heap_table_size' value if
the server restarts.

You can also specify a 'MAX_ROWS' table option in 'CREATE TABLE'
statements for 'MEMORY' tables to provide a hint about the
number of rows you plan to store in them.  This does not enable the
table to grow beyond the 'max_heap_table_size' value, which still acts
as a constraint on maximum table size.  For maximum flexibility in being
able to use 'MAX_ROWS', set 'max_heap_table_size' at least as high as
the value to which you want each 'MEMORY' table to be able to grow.

*Additional Resources*

A forum dedicated to the 'MEMORY' storage engine is available at
<http://forums.mysql.com/list.php?92>.

15.4 The CSV Storage Engine
===========================

The 'CSV' storage engine stores data in text files using comma-separated
values format.

The 'CSV' storage engine is always compiled into the MySQL server.

To examine the source for the 'CSV' engine, look in the 'storage/csv'
directory of a MySQL source distribution.

When you create a 'CSV' table, the server creates a table format file in
the database directory.  The file begins with the table name and has an
'.frm' extension.  The storage engine also creates a data file.  Its
name begins with the table name and has a '.CSV' extension.  The data
file is a plain text file.  When you store data into the table, the
storage engine saves it into the data file in comma-separated values
format.

     mysql> CREATE TABLE test (i INT NOT NULL, c CHAR(10) NOT NULL)
         -> ENGINE = CSV;
     Query OK, 0 rows affected (0.12 sec)

     mysql> INSERT INTO test VALUES(1,'record one'),(2,'record two');
     Query OK, 2 rows affected (0.00 sec)
     Records: 2  Duplicates: 0  Warnings: 0

     mysql> SELECT * FROM test;
     +------+------------+
     | i    | c          |
     +------+------------+
     |    1 | record one |
     |    2 | record two |
     +------+------------+
     2 rows in set (0.00 sec)

Creating a CSV table also creates a corresponding Metafile that stores
the state of the table and the number of rows that exist in the table.
The name of this file is the same as the name of the table with the
extension 'CSM'.

If you examine the 'test.CSV' file in the database directory created by
executing the preceding statements, its contents should look like this:

     "1","record one"
     "2","record two"

This format can be read, and even written, by spreadsheet applications
such as Microsoft Excel or StarOffice Calc.

15.4.1 Repairing and Checking CSV Tables
----------------------------------------

The CSV storage engines supports the 'CHECK' and 'REPAIR' statements to
verify and if possible repair a damaged CSV table.

When running the 'CHECK' statement, the CSV file will be checked for
validity by looking for the correct field separators, escaped fields
(matching or missing quotation marks), the correct number of fields
compared to the table definition and the existence of a corresponding
CSV metafile.  The first invalid row discovered will report an error.
Checking a valid table produces output like that shown below:

     mysql> check table csvtest;
     +--------------+-------+----------+----------+
     | Table        | Op    | Msg_type | Msg_text |
     +--------------+-------+----------+----------+
     | test.csvtest | check | status   | OK       |
     +--------------+-------+----------+----------+
     1 row in set (0.00 sec)

A check on a corrupted table returns a fault:

     mysql> check table csvtest;
     +--------------+-------+----------+----------+
     | Table        | Op    | Msg_type | Msg_text |
     +--------------+-------+----------+----------+
     | test.csvtest | check | error    | Corrupt  |
     +--------------+-------+----------+----------+
     1 row in set (0.01 sec)

If the check fails, the table is marked as crashed (corrupt).  Once a
table has been marked as corrupt, it is automatically repaired when you
next run 'CHECK' or execute a 'SELECT' statement.  The
corresponding corrupt status and new status will be displayed when
running 'CHECK':

     mysql> check table csvtest;
     +--------------+-------+----------+----------------------------+
     | Table        | Op    | Msg_type | Msg_text                   |
     +--------------+-------+----------+----------------------------+
     | test.csvtest | check | warning  | Table is marked as crashed |
     | test.csvtest | check | status   | OK                         |
     +--------------+-------+----------+----------------------------+
     2 rows in set (0.08 sec)

To repair a table you can use 'REPAIR', this copies as many valid rows
from the existing CSV data as possible, and then replaces the existing
CSV file with the recovered rows.  Any rows beyond the corrupted data
are lost.

     mysql> repair table csvtest;
     +--------------+--------+----------+----------+
     | Table        | Op     | Msg_type | Msg_text |
     +--------------+--------+----------+----------+
     | test.csvtest | repair | status   | OK       |
     +--------------+--------+----------+----------+
     1 row in set (0.02 sec)

*Warning*:

During repair, only the rows from the CSV file up to the first damaged
row are copied to the new table.  All other rows from the first damaged
row to the end of the table are removed, even valid rows.

15.4.2 CSV Limitations
----------------------

The 'CSV' storage engine does not support indexing.

Partitioning is not supported for tables using the 'CSV' storage engine.

All tables that you create using the 'CSV' storage engine must have the
'NOT NULL' attribute on all columns.  However, for backward
compatibility, you can continue to use tables with nullable columns that
were created in previous MySQL releases.  (Bug #32050)

15.5 The ARCHIVE Storage Engine
===============================

The 'ARCHIVE' storage engine produces special-purpose tables that store
large amounts of unindexed data in a very small footprint.

*ARCHIVE Storage Engine Features*

Feature                                     Support

*B-tree indexes*                            No

*Backup/point-in-time recovery*             Yes
(Implemented in the server, rather than
in the storage engine.)

*Cluster database support*                  No

*Clustered indexes*                         No

*Compressed data*                           Yes

*Data caches*                               No

*Encrypted data* (Implemented in the        Yes
server via encryption functions.
Data-at-rest tablespace encryption is
available in MySQL 5.7 and later.)

*Foreign key support*                       No

*Full-text search indexes*                  No

*Geospatial data type support*              Yes

*Geospatial indexing support*               No

*Hash indexes*                              No

*Index caches*                              No

*Locking granularity*                       Row

*MVCC*                                      No

*Query cache support*                       Yes

*Replication support* (Implemented in the   Yes
server, rather than in the storage
engine.)

*Storage limits*                            None

*T-tree indexes*                            No

*Transactions*                              No

*Update statistics for data dictionary*     Yes

The 'ARCHIVE' storage engine is included in MySQL binary distributions.
To enable this storage engine if you build MySQL from source, invoke
'CMake' with the '-DWITH_ARCHIVE_STORAGE_ENGINE' option.

To examine the source for the 'ARCHIVE' engine, look in the
'storage/archive' directory of a MySQL source distribution.

You can check whether the 'ARCHIVE' storage engine is available with the
'SHOW ENGINES' statement.

When you create an 'ARCHIVE' table, the server creates a table format
file in the database directory.  The file begins with the table name and
has an '.frm' extension.  The storage engine creates other files, all
having names beginning with the table name.  The data file has an
extension of '.ARZ'.  An '.ARN' file may appear during optimization
operations.

The 'ARCHIVE' engine supports 'INSERT', 'REPLACE',
and 'SELECT', but not 'DELETE' or
'UPDATE'.  It does support 'ORDER BY' operations, see
'BLOB' columns, and basically all but spatial data types (see
spatial-type-overview).  The 'ARCHIVE' engine uses row-level
locking.

The 'ARCHIVE' engine supports the 'AUTO_INCREMENT' column attribute.
The 'AUTO_INCREMENT' column can have either a unique or nonunique index.
Attempting to create an index on any other column results in an error.
The 'ARCHIVE' engine also supports the 'AUTO_INCREMENT' table option in
'CREATE TABLE' statements to specify the initial
sequence value for a new table or reset the sequence value for an
existing table, respectively.

'ARCHIVE' does not support inserting a value into an 'AUTO_INCREMENT'
column less than the current maximum column value.  Attempts to do so
result in an 'ER_DUP_KEY' error.

The 'ARCHIVE' engine ignores 'BLOB' columns if they are not
requested and scans past them while reading.

*Storage:* Rows are compressed as they are inserted.  The 'ARCHIVE'
engine uses 'zlib' lossless data compression (see
<http://www.zlib.net/>).  You can use 'OPTIMIZE TABLE'
to analyze the table and pack it into a smaller format
(for a reason to use 'OPTIMIZE TABLE', see later
in this section).  The engine also supports 'CHECK TABLE'.
There are several types of insertions that are used:

   * An 'INSERT' statement just pushes rows into a
     compression buffer, and that buffer flushes as necessary.  The
     insertion into the buffer is protected by a lock.  A
     'SELECT' forces a flush to occur.

   * A bulk insert is visible only after it completes, unless other
     inserts occur at the same time, in which case it can be seen
     partially.  A 'SELECT' never causes a flush of a
     bulk insert unless a normal insert occurs while it is loading.

*Retrieval*: On retrieval, rows are uncompressed on demand; there is no
row cache.  A 'SELECT' operation performs a complete
table scan: When a 'SELECT' occurs, it finds out how many
rows are currently available and reads that number of rows.
'SELECT' is performed as a consistent read.  Note that lots of
'SELECT' statements during insertion can deteriorate the
compression, unless only bulk or delayed inserts are used.  To achieve
better compression, you can use 'OPTIMIZE TABLE'.
or 'REPAIR TABLE'.  The number of rows in 'ARCHIVE'
tables reported by 'SHOW TABLE STATUS' is
always accurate.  See optimize-table, repair-table, and
show-table-status.

*Additional Resources*

   * A forum dedicated to the 'ARCHIVE' storage engine is available at
     <http://forums.mysql.com/list.php?112>.

15.6 The BLACKHOLE Storage Engine
=================================

The 'BLACKHOLE' storage engine acts as a 'black hole' that accepts data
but throws it away and does not store it.  Retrievals always return an
empty result:

     mysql> CREATE TABLE test(i INT, c CHAR(10)) ENGINE = BLACKHOLE;
     Query OK, 0 rows affected (0.03 sec)

     mysql> INSERT INTO test VALUES(1,'record one'),(2,'record two');
     Query OK, 2 rows affected (0.00 sec)
     Records: 2  Duplicates: 0  Warnings: 0

     mysql> SELECT * FROM test;
     Empty set (0.00 sec)

To enable the 'BLACKHOLE' storage engine if you build MySQL from source,
invoke 'CMake' with the '-DWITH_BLACKHOLE_STORAGE_ENGINE' option.

To examine the source for the 'BLACKHOLE' engine, look in the 'sql'
directory of a MySQL source distribution.

When you create a 'BLACKHOLE' table, the server creates a table format
file in the database directory.  The file begins with the table name and
has an '.frm' extension.  There are no other files associated with the
table.

The 'BLACKHOLE' storage engine supports all kinds of indexes.  That is,
you can include index declarations in the table definition.

You can check whether the 'BLACKHOLE' storage engine is available with
the 'SHOW ENGINES' statement.

Inserts into a 'BLACKHOLE' table do not store any data, but if statement
based binary logging is enabled, the SQL statements are logged and
replicated to slave servers.  This can be useful as a repeater or filter
mechanism.

Suppose that your application requires slave-side filtering rules, but
transferring all binary log data to the slave first results in too much
traffic.  In such a case, it is possible to set up on the master host a
'dummy' slave process whose default storage engine is 'BLACKHOLE',
depicted as follows:

FIGURE GOES HERE: Replication using BLACKHOLE for Filtering

The master writes to its binary log.  The 'dummy' 'mysqld'
process acts as a slave, applying the desired combination of
'replicate-do-*' and 'replicate-ignore-*' rules, and writes a new,
filtered binary log of its own.  (See replication-options.)
This filtered log is provided to the slave.

The dummy process does not actually store any data, so there is little
processing overhead incurred by running the additional 'mysqld'
process on the replication master host.  This type of setup can
be repeated with additional replication slaves.

'INSERT' triggers for 'BLACKHOLE' tables work as
expected.  However, because the 'BLACKHOLE' table does not actually
store any data, see 'UPDATE' and 'DELETE'.
triggers are not activated: The 'FOR EACH ROW' clause in the trigger
definition does not apply because there are no rows.

Other possible uses for the 'BLACKHOLE' storage engine include:

   * Verification of dump file syntax.

   * Measurement of the overhead from binary logging, by comparing
     performance using 'BLACKHOLE' with and without binary logging
     enabled.

   * 'BLACKHOLE' is essentially a 'no-op' storage engine, so it could be
     used for finding performance bottlenecks not related to the storage
     engine itself.

The 'BLACKHOLE' engine is transaction-aware, in the sense that committed
transactions are written to the binary log and rolled-back transactions
are not.

*Blackhole Engine and Auto Increment Columns*

The Blackhole engine is a no-op engine.  Any operations performed on a
table using Blackhole will have no effect.  This should be born in mind
when considering the behavior of primary key columns that auto
increment.  The engine will not automatically increment field values,
and does not retain auto increment field state.  This has important
implications in replication.

Consider the following replication scenario where all three of the
following conditions apply:

  1. On a master server there is a blackhole table with an auto
     increment field that is a primary key.

  2. On a slave the same table exists but using the MyISAM engine.

  3. Inserts are performed into the master's table without explicitly
     setting the auto increment value in the 'INSERT' statement itself
     or through using a 'SET INSERT_ID' statement.

In this scenario replication will fail with a duplicate entry error on
the primary key column.

In statement based replication, the value of 'INSERT_ID' in the context
event will always be the same.  Replication will therefore fail due to
trying insert a row with a duplicate value for a primary key column.

In row based replication, the value that the engine returns for the row
always be the same for each insert.  This will result in the slave
attempting to replay two insert log entries using the same value for the
primary key column, and so replication will fail.

*Column Filtering*

When using row-based replication, ('binlog_format=ROW'), a slave where
the last columns are missing from a table is supported, as described in
the section replication-features-differing-tables.

This filtering works on the slave side, that is, the columns are copied
to the slave before they are filtered out.  There are at least two cases
where it is not desirable to copy the columns to the slave:

  1. If the data is confidential, so the slave server should not have
     access to it.

  2. If the master has many slaves, filtering before sending to the
     slaves may reduce network traffic.

Master column filtering can be achieved using the 'BLACKHOLE' engine.
This is carried out in a way similar to how master table filtering is
achieved - by using the 'BLACKHOLE' engine and the
'--replicate-do-table' or '--replicate-ignore-table' option.

The setup for the master is:

     CREATE TABLE t1 (public_col_1, ..., public_col_N,
                      secret_col_1, ..., secret_col_M) ENGINE=MyISAM;

The setup for the trusted slave is:

     CREATE TABLE t1 (public_col_1, ..., public_col_N) ENGINE=BLACKHOLE;

The setup for the untrusted slave is:

     CREATE TABLE t1 (public_col_1, ..., public_col_N) ENGINE=MyISAM;

15.7 The MERGE Storage Engine
=============================

The 'MERGE' storage engine, also known as the 'MRG_MyISAM' engine, is a
collection of identical 'MyISAM' tables that can be used as one.
'Identical' means that all tables have identical column data types and
index information.  You cannot merge 'MyISAM' tables in which the
columns are listed in a different order, do not have exactly the same
data types in corresponding columns, or have the indexes in different
order.  However, any or all of the 'MyISAM' tables can be compressed
with 'myisampack'.  See myisampack.
Differences between tables such as these do not matter:

   * Names of corresponding columns and indexes can differ.

   * Comments for tables, columns, and indexes can differ.

   * Table options such as 'AVG_ROW_LENGTH', 'MAX_ROWS', or 'PACK_KEYS'
     can differ.

An alternative to a 'MERGE' table is a partitioned table, which stores
partitions of a single table in separate files.  Partitioning enables
some operations to be performed more efficiently and is not limited to
the 'MyISAM' storage engine.  For more information, see
partitioning.

When you create a 'MERGE' table, MySQL creates two files on disk.  The
files have names that begin with the table name and have an extension to
indicate the file type.  An '.frm' file stores the table format, and an
'.MRG' file contains the names of the underlying 'MyISAM' tables that
should be used as one.  The tables do not have to be in the same
database as the 'MERGE' table.

You can use 'SELECT', 'DELETE',
'UPDATE', and 'INSERT' on 'MERGE' tables.  You
must have 'SELECT', 'DELETE', and 'UPDATE' privileges on the 'MyISAM'
tables that you map to a 'MERGE' table.

*Note*:

The use of 'MERGE' tables entails the following security issue: If a
user has access to 'MyISAM' table T, that user can create a 'MERGE'
table M that accesses T.  However, if the user's privileges on T are
subsequently revoked, the user can continue to access T by doing so
through M.

Use of 'DROP TABLE' with a 'MERGE' table drops only
the 'MERGE' specification.  The underlying tables are not affected.

To create a 'MERGE' table, you must specify a 'UNION=(LIST-OF-TABLES)'
option that indicates which 'MyISAM' tables to use.  You can optionally
specify an 'INSERT_METHOD' option to control how inserts into the
'MERGE' table take place.  Use a value of 'FIRST' or 'LAST' to cause
inserts to be made in the first or last underlying table, respectively.
If you specify no 'INSERT_METHOD' option or if you specify it with a
value of 'NO', inserts into the 'MERGE' table are not permitted and
attempts to do so result in an error.

The following example shows how to create a 'MERGE' table:

     mysql> CREATE TABLE t1 (
         ->    a INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         ->    message CHAR(20)) ENGINE=MyISAM;
     mysql> CREATE TABLE t2 (
         ->    a INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         ->    message CHAR(20)) ENGINE=MyISAM;
     mysql> INSERT INTO t1 (message) VALUES ('Testing'),('table'),('t1');
     mysql> INSERT INTO t2 (message) VALUES ('Testing'),('table'),('t2');
     mysql> CREATE TABLE total (
         ->    a INT NOT NULL AUTO_INCREMENT,
         ->    message CHAR(20), INDEX(a))
         ->    ENGINE=MERGE UNION=(t1,t2) INSERT_METHOD=LAST;

Column 'a' is indexed as a 'PRIMARY KEY' in the underlying 'MyISAM'
tables, but not in the 'MERGE' table.  There it is indexed but not as a
'PRIMARY KEY' because a 'MERGE' table cannot enforce uniqueness over the
set of underlying tables.  (Similarly, a column with a 'UNIQUE' index in
the underlying tables should be indexed in the 'MERGE' table but not as
a 'UNIQUE' index.)

After creating the 'MERGE' table, you can use it to issue queries that
operate on the group of tables as a whole:

     mysql> SELECT * FROM total;
     +---+---------+
     | a | message |
     +---+---------+
     | 1 | Testing |
     | 2 | table   |
     | 3 | t1      |
     | 1 | Testing |
     | 2 | table   |
     | 3 | t2      |
     +---+---------+

To remap a 'MERGE' table to a different collection of 'MyISAM' tables,
you can use one of the following methods:

   * 'DROP' the 'MERGE' table and re-create it.

   * Use 'ALTER TABLE TBL_NAME UNION=(...)' to change the list of
     underlying tables.

     It is also possible to use 'ALTER TABLE ... UNION=()' (that is,
     with an empty 'UNION' clause) to remove all of the
     underlying tables.  However, in this case, the table is effectively
     empty and inserts fail because there is no underlying table to take
     new rows.  Such a table might be useful as a template for creating
     new 'MERGE' tables with 'CREATE TABLE ... LIKE'.

The underlying table definitions and indexes must conform closely to the
definition of the 'MERGE' table.  Conformance is checked when a table
that is part of a 'MERGE' table is opened, not when the 'MERGE' table is
created.  If any table fails the conformance checks, the operation that
triggered the opening of the table fails.  This means that changes to
the definitions of tables within a 'MERGE' may cause a failure when the
'MERGE' table is accessed.  The conformance checks applied to each table
are:

   * The underlying table and the 'MERGE' table must have the same
     number of columns.

   * The column order in the underlying table and the 'MERGE' table must
     match.

   * Additionally, the specification for each corresponding column in
     the parent 'MERGE' table and the underlying tables are compared and
     must satisfy these checks:

        * The column type in the underlying table and the 'MERGE' table
          must be equal.

        * The column length in the underlying table and the 'MERGE'
          table must be equal.

        * The column of the underlying table and the 'MERGE' table can
          be 'NULL'.

   * The underlying table must have at least as many indexes as the
     'MERGE' table.  The underlying table may have more indexes than the
     'MERGE' table, but cannot have fewer.

     *Note*:

     A known issue exists where indexes on the same columns must be in
     identical order, in both the 'MERGE' table and the underlying
     'MyISAM' table.  See Bug #33653.

     Each index must satisfy these checks:

        * The index type of the underlying table and the 'MERGE' table
          must be the same.

        * The number of index parts (that is, multiple columns within a
          compound index) in the index definition for the underlying
          table and the 'MERGE' table must be the same.

        * For each index part:

             * Index part lengths must be equal.

             * Index part types must be equal.

             * Index part languages must be equal.

             * Check whether index parts can be 'NULL'.

If a 'MERGE' table cannot be opened or used because of a problem with an
underlying table, see 'CHECK TABLE' displays information
about which table caused the problem.

*Additional Resources*

   * A forum dedicated to the 'MERGE' storage engine is available at
     <http://forums.mysql.com/list.php?93>.

15.7.1 MERGE Table Advantages and Disadvantages
-----------------------------------------------

'MERGE' tables can help you solve the following problems:

   * Easily manage a set of log tables.  For example, you can put data
     from different months into separate tables, compress some of them
     with 'myisampack', and then create a 'MERGE'
     table to use them as one.

   * Obtain more speed.  You can split a large read-only table based on
     some criteria, and then put individual tables on different disks.
     A 'MERGE' table structured this way could be much faster than using
     a single large table.

   * Perform more efficient searches.  If you know exactly what you are
     looking for, you can search in just one of the underlying tables
     for some queries and use a 'MERGE' table for others.  You can even
     have many different 'MERGE' tables that use overlapping sets of
     tables.

   * Perform more efficient repairs.  It is easier to repair individual
     smaller tables that are mapped to a 'MERGE' table than to repair a
     single large table.

   * Instantly map many tables as one.  A 'MERGE' table need not
     maintain an index of its own because it uses the indexes of the
     individual tables.  As a result, 'MERGE' table collections are
     _very_ fast to create or remap.  (You must still specify the index
     definitions when you create a 'MERGE' table, even though no indexes
     are created.)

   * If you have a set of tables from which you create a large table on
     demand, you can instead create a 'MERGE' table from them on demand.
     This is much faster and saves a lot of disk space.

   * Exceed the file size limit for the operating system.  Each 'MyISAM'
     table is bound by this limit, but a collection of 'MyISAM' tables
     is not.

   * You can create an alias or synonym for a 'MyISAM' table by defining
     a 'MERGE' table that maps to that single table.  There should be no
     really notable performance impact from doing this (only a couple of
     indirect calls and 'memcpy()' calls for each read).

The disadvantages of 'MERGE' tables are:

   * You can use only identical 'MyISAM' tables for a 'MERGE' table.

   * Some 'MyISAM' features are unavailable in 'MERGE' tables.  For
     example, you cannot create 'FULLTEXT' indexes on 'MERGE' tables.
     (You can create 'FULLTEXT' indexes on the underlying 'MyISAM'
     tables, but you cannot search the 'MERGE' table with a full-text
     search.)

   * If the 'MERGE' table is nontemporary, all underlying 'MyISAM'
     tables must be nontemporary.  If the 'MERGE' table is temporary,
     the 'MyISAM' tables can be any mix of temporary and nontemporary.

   * 'MERGE' tables use more file descriptors than 'MyISAM' tables.  If
     10 clients are using a 'MERGE' table that maps to 10 tables, the
     server uses (10 x 10) + 10 file descriptors.  (10 data file
     descriptors for each of the 10 clients, and 10 index file
     descriptors shared among the clients.)

   * Index reads are slower.  When you read an index, the 'MERGE'
     storage engine needs to issue a read on all underlying tables to
     check which one most closely matches a given index value.  To read
     the next index value, the 'MERGE' storage engine needs to search
     the read buffers to find the next value.  Only when one index
     buffer is used up does the storage engine need to read the next
     index block.  This makes 'MERGE' indexes much slower on 'eq_ref'
     searches, but not much slower on 'ref' searches.  For more
     information about 'eq_ref' and 'ref', see explain.

15.7.2 MERGE Table Problems
---------------------------

The following are known problems with 'MERGE' tables:

   * In versions of MySQL Server prior to 5.1.23, it was possible to
     create temporary merge tables with nontemporary child MyISAM
     tables.

     From versions 5.1.23, MERGE children were locked through the parent
     table.  If the parent was temporary, it was not locked and so the
     children were not locked either.  Parallel use of the MyISAM tables
     corrupted them.

   * If you use 'ALTER TABLE' to change a 'MERGE'
     table to another storage engine, the mapping to the underlying
     tables is lost.  Instead, the rows from the underlying 'MyISAM'
     tables are copied into the altered table, which then uses the
     specified storage engine.

   * The 'INSERT_METHOD' table option for a 'MERGE' table indicates
     which underlying 'MyISAM' table to use for inserts into the 'MERGE'
     table.  However, use of the 'AUTO_INCREMENT' table option for that
     'MyISAM' table has no effect for inserts into the 'MERGE' table
     until at least one row has been inserted directly into the 'MyISAM'
     table.

   * A 'MERGE' table cannot maintain uniqueness constraints over the
     entire table.  When you perform an 'INSERT', the data
     goes into the first or last 'MyISAM' table (as determined by the
     'INSERT_METHOD' option).  MySQL ensures that unique key values
     remain unique within that 'MyISAM' table, but not over all the
     underlying tables in the collection.

   * Because the 'MERGE' engine cannot enforce uniqueness over the set
     of underlying tables, see 'REPLACE' does not work as
     expected.  The two key facts are:

        * 'REPLACE' can detect unique key violations
          only in the underlying table to which it is going to write
          (which is determined by the 'INSERT_METHOD' option).  This
          differs from violations in the 'MERGE' table itself.

        * If 'REPLACE' detects a unique key violation,
          it will change only the corresponding row in the underlying
          table it is writing to; that is, the first or last table, as
          determined by the 'INSERT_METHOD' option.

     Similar considerations apply for 'INSERT ... ON DUPLICATE KEY UPDATE'.

   * 'MERGE' tables do not support partitioning.  That is, you cannot
     partition a 'MERGE' table, nor can any of a 'MERGE' table's
     underlying 'MyISAM' tables be partitioned.

   * You should not use 'ANALYZE TABLE',
     'REPAIR TABLE', 'OPTIMIZE TABLE',
     see 'ALTER TABLE', 'DROP TABLE',
     see 'DELETE' without a 'WHERE'
     clause, or 'TRUNCATE TABLE' on any of the
     tables that are mapped into an open 'MERGE' table.  If you do so,
     the 'MERGE' table may still refer to the original table and yield
     unexpected results.  To work around this problem, ensure that no
     'MERGE' tables remain open by issuing a 'FLUSH TABLES' statement
     prior to performing any of the named operations.

     The unexpected results include the possibility that the operation
     on the 'MERGE' table will report table corruption.  If this occurs
     after one of the named operations on the underlying 'MyISAM'
     tables, the corruption message is spurious.  To deal with this,
     issue a 'FLUSH TABLES' statement after modifying the 'MyISAM'
     tables.

   * 'DROP TABLE' on a table that is in use by a
     'MERGE' table does not work on Windows because the 'MERGE' storage
     engine's table mapping is hidden from the upper layer of MySQL.
     Windows does not permit open files to be deleted, so you first must
     flush all 'MERGE' tables (with 'FLUSH TABLES') or drop the 'MERGE'
     table before dropping the table.

   * The definition of the 'MyISAM' tables and the 'MERGE' table are
     checked when the tables are accessed (for example, as part of a
     'SELECT' or 'INSERT' statement).  The
     checks ensure that the definitions of the tables and the parent
     'MERGE' table definition match by comparing column order, types,
     sizes and associated indexes.  If there is a difference between the
     tables, an error is returned and the statement fails.  Because
     these checks take place when the tables are opened, any changes to
     the definition of a single table, including column changes, column
     ordering, and engine alterations will cause the statement to fail.

   * The order of indexes in the 'MERGE' table and its underlying tables
     should be the same.  If you use 'ALTER TABLE'.
     to add a 'UNIQUE' index to a table used in a 'MERGE' table, and
     then use 'ALTER TABLE' to add a nonunique index
     on the 'MERGE' table, the index ordering is different for the
     tables if there was already a nonunique index in the underlying
     table.  (This happens because 'ALTER TABLE'.
     puts 'UNIQUE' indexes before nonunique indexes to facilitate rapid
     detection of duplicate keys.)  Consequently, queries on tables with
     such indexes may return unexpected results.

   * If you encounter an error message similar to 'ERROR 1017 (HY000):
     Can't find file: 'TBL_NAME.MRG' (errno: 2)', it generally indicates
     that some of the underlying tables do not use the 'MyISAM' storage
     engine.  Confirm that all of these tables are 'MyISAM'.

   * The maximum number of rows in a 'MERGE' table is 2^64 (~1.844E+19;
     the same as for a 'MyISAM' table).  It is not possible to merge
     multiple 'MyISAM' tables into a single 'MERGE' table that would
     have more than this number of rows.

   * Use of underlying 'MyISAM' tables of differing row formats with a
     parent 'MERGE' table is currently known to fail.  See Bug #32364.

   * You cannot change the union list of a nontemporary 'MERGE' table
     when 'LOCK TABLES' is in effect.  The following
     does _not_ work:

          CREATE TABLE m1 ... ENGINE=MRG_MYISAM ...;
          LOCK TABLES t1 WRITE, t2 WRITE, m1 WRITE;
          ALTER TABLE m1 ... UNION=(t1,t2) ...;

     However, you can do this with a temporary 'MERGE' table.

   * You cannot create a 'MERGE' table with 'CREATE ... SELECT', neither
     as a temporary 'MERGE' table, nor as a nontemporary 'MERGE' table.
     For example:

          CREATE TABLE m1 ... ENGINE=MRG_MYISAM ... SELECT ...;

     Attempts to do this result in an error: TBL_NAME is not 'BASE
     TABLE'.

   * In some cases, differing 'PACK_KEYS' table option values among the
     'MERGE' and underlying tables cause unexpected results if the
     underlying tables contain 'CHAR' or 'BINARY' columns.  As a
     workaround, use 'ALTER TABLE' to ensure that all involved tables
     have the same 'PACK_KEYS' value.  (Bug #50646)

15.8 The FEDERATED Storage Engine
=================================

The 'FEDERATED' storage engine lets you access data from a remote MySQL
database without using replication or cluster technology.  Querying a
local 'FEDERATED' table automatically pulls the data from the remote
(federated) tables.  No data is stored on the local tables.

To include the 'FEDERATED' storage engine if you build MySQL from
source, invoke 'CMake' with the '-DWITH_FEDERATED_STORAGE_ENGINE'
option.

The 'FEDERATED' storage engine is not enabled by default in the running
server; to enable 'FEDERATED', you must start the MySQL server binary
using the '--federated' option.

To examine the source for the 'FEDERATED' engine, look in the
'storage/federated' directory of a MySQL source distribution.

15.8.1 FEDERATED Storage Engine Overview
----------------------------------------

When you create a table using one of the standard storage engines (such
as 'MyISAM', 'CSV' or 'InnoDB'), the table consists of the table
definition and the associated data.  When you create a 'FEDERATED'
table, the table definition is the same, but the physical storage of the
data is handled on a remote server.

A 'FEDERATED' table consists of two elements:

   * A _remote server_ with a database table, which in turn consists of
     the table definition (stored in the '.frm' file) and the associated
     table.  The table type of the remote table may be any type
     supported by the remote 'mysqld' server, including 'MyISAM' or
     'InnoDB'.

   * A _local server_ with a database table, where the table definition
     matches that of the corresponding table on the remote server.  The
     table definition is stored within the '.frm' file.  However, there
     is no data file on the local server.  Instead, the table definition
     includes a connection string that points to the remote table.

When executing queries and statements on a 'FEDERATED' table on the
local server, the operations that would normally insert, update or
delete information from a local data file are instead sent to the remote
server for execution, where they update the data file on the remote
server or return matching rows from the remote server.

The basic structure of a 'FEDERATED' table setup is shown in
figure-se-federated-structure.

FIGURE GOES HERE: FEDERATED Table Structure

When a client issues an SQL statement that refers to a 'FEDERATED'
table, the flow of information between the local server (where the SQL
statement is executed) and the remote server (where the data is
physically stored) is as follows:

  1. The storage engine looks through each column that the 'FEDERATED'
     table has and constructs an appropriate SQL statement that refers
     to the remote table.

  2. The statement is sent to the remote server using the MySQL client
     API.

  3. The remote server processes the statement and the local server
     retrieves any result that the statement produces (an affected-rows
     count or a result set).

  4. If the statement produces a result set, each column is converted to
     internal storage engine format that the 'FEDERATED' engine expects
     and can use to display the result to the client that issued the
     original statement.

The local server communicates with the remote server using MySQL client
C API functions.  It invokes 'mysql_real_query()'
to send the statement.  To read a result set, it uses
'mysql_store_result()' and fetches rows one
at a time using 'mysql_fetch_row()'.

15.8.2 How to Create FEDERATED Tables
-------------------------------------

To create a 'FEDERATED' table you should follow these steps:

  1. Create the table on the remote server.  Alternatively, make a note
     of the table definition of an existing table, perhaps using the
     'SHOW CREATE TABLE' statement.

  2. Create the table on the local server with an identical table
     definition, but adding the connection information that links the
     local table to the remote table.

For example, you could create the following table on the remote server:

     CREATE TABLE test_table (
         id     INT(20) NOT NULL AUTO_INCREMENT,
         name   VARCHAR(32) NOT NULL DEFAULT '',
         other  INT(20) NOT NULL DEFAULT '0',
         PRIMARY KEY  (id),
         INDEX name (name),
         INDEX other_key (other)
     )
     ENGINE=MyISAM
     DEFAULT CHARSET=latin1;

To create the local table that will be federated to the remote table,
there are two options available.  You can either create the local table
and specify the connection string (containing the server name, login,
password) to be used to connect to the remote table using the
'CONNECTION', or you can use an existing connection that you have
previously created using the 'CREATE SERVER'.
statement.

*Important*:

When you create the local table it _must_ have an identical field
definition to the remote table.

*Note*:

You can improve the performance of a 'FEDERATED' table by adding indexes
to the table on the host.  The optimization will occur because the query
sent to the remote server will include the contents of the 'WHERE'
clause and will be sent to the remote server and subsequently executed
locally.  This reduces the network traffic that would otherwise request
the entire table from the server for local processing.

15.8.2.1 Creating a FEDERATED Table Using CONNECTION
....................................................

To use the first method, you must specify the 'CONNECTION' string after
the engine type in a 'CREATE TABLE' statement.  For
example:

     CREATE TABLE federated_table (
         id     INT(20) NOT NULL AUTO_INCREMENT,
         name   VARCHAR(32) NOT NULL DEFAULT '',
         other  INT(20) NOT NULL DEFAULT '0',
         PRIMARY KEY  (id),
         INDEX name (name),
         INDEX other_key (other)
     )
     ENGINE=FEDERATED
     DEFAULT CHARSET=latin1
     CONNECTION='mysql://fed_user@remote_host:9306/federated/test_table';

*Note*:

'CONNECTION' replaces the 'COMMENT' used in some previous versions of
MySQL.

The 'CONNECTION' string contains the information required to connect to
the remote server containing the table that will be used to physically
store the data.  The connection string specifies the server name, login
credentials, port number and database/table information.  In the
example, the remote table is on the server 'remote_host', using port
9306.  The name and port number should match the host name (or IP
address) and port number of the remote MySQL server instance you want to
use as your remote table.

The format of the connection string is as follows:

     SCHEME://USER_NAME[:PASSWORD]@HOST_NAME[:PORT_NUM]/DB_NAME/TBL_NAME

Where:

   * SCHEME: A recognized connection protocol.  Only 'mysql' is
     supported as the SCHEME value at this point.

   * USER_NAME: The user name for the connection.  This user must have
     been created on the remote server, and must have suitable
     privileges to perform the required actions (see 'SELECT',
     'INSERT', 'UPDATE', and so forth) on
     the remote table.

   * PASSWORD: (Optional) The corresponding password for USER_NAME.

   * HOST_NAME: The host name or IP address of the remote server.

   * PORT_NUM: (Optional) The port number for the remote server.  The
     default is 3306.

   * DB_NAME: The name of the database holding the remote table.

   * TBL_NAME: The name of the remote table.  The name of the local and
     the remote table do not have to match.

Sample connection strings:

     CONNECTION='mysql://username:password@hostname:port/database/tablename'
     CONNECTION='mysql://username@hostname/database/tablename'
     CONNECTION='mysql://username:password@hostname/database/tablename'

15.8.2.2 Creating a FEDERATED Table Using CREATE SERVER
.......................................................

If you are creating a number of 'FEDERATED' tables on the same server,
or if you want to simplify the process of creating 'FEDERATED' tables,
you can use the 'CREATE SERVER' statement to
define the server connection parameters, just as you would with the
'CONNECTION' string.

The format of the 'CREATE SERVER' statement is:

     CREATE SERVER
     SERVER_NAME
     FOREIGN DATA WRAPPER WRAPPER_NAME
     OPTIONS (OPTION [, OPTION] ...)

The SERVER_NAME is used in the connection string when creating a new
'FEDERATED' table.

For example, to create a server connection identical to the 'CONNECTION'
string:

     CONNECTION='mysql://fed_user@remote_host:9306/federated/test_table';

You would use the following statement:

     CREATE SERVER fedlink
     FOREIGN DATA WRAPPER mysql
     OPTIONS (USER 'fed_user', HOST 'remote_host', PORT 9306, DATABASE 'federated');

To create a 'FEDERATED' table that uses this connection, you still use
the 'CONNECTION' keyword, but specify the name you used in the
'CREATE SERVER' statement.

     CREATE TABLE test_table (
         id     INT(20) NOT NULL AUTO_INCREMENT,
         name   VARCHAR(32) NOT NULL DEFAULT '',
         other  INT(20) NOT NULL DEFAULT '0',
         PRIMARY KEY  (id),
         INDEX name (name),
         INDEX other_key (other)
     )
     ENGINE=FEDERATED
     DEFAULT CHARSET=latin1
     CONNECTION='fedlink/test_table';

The connection name in this example contains the name of the connection
('fedlink') and the name of the table ('test_table') to link to,
separated by a slash.  If you specify only the connection name without a
table name, the table name of the local table is used instead.

For more information on 'CREATE SERVER', see
create-server.

The 'CREATE SERVER' statement accepts the same
arguments as the 'CONNECTION' string.  The 'CREATE SERVER'
statement updates the rows in the 'mysql.servers' table.
See the following table for information on the correspondence between
parameters in a connection string, options in the 'CREATE SERVER'
statement, and the columns in the 'mysql.servers' table.
For reference, the format of the 'CONNECTION' string is as follows:

     SCHEME://USER_NAME[:PASSWORD]@HOST_NAME[:PORT_NUM]/DB_NAME/TBL_NAME

Description        'CONNECTION'       'CREATE 'mysql.servers' string SERVER'.
                                      option

Connection         SCHEME             'wrapper_name'     'Wrapper'
scheme

Remote user        USER_NAME          'USER'             'Username'

Remote password    PASSWORD           'PASSWORD'         'Password'

Remote host        HOST_NAME          'HOST'             'Host'

Remote port        PORT_NUM           'PORT'             'Port'

Remote database    DB_NAME            'DATABASE'         'Db'

15.8.3 FEDERATED Storage Engine Notes and Tips
----------------------------------------------

You should be aware of the following points when using the 'FEDERATED'
storage engine:

   * 'FEDERATED' tables may be replicated to other slaves, but you must
     ensure that the slave servers are able to use the user/password
     combination that is defined in the 'CONNECTION' string (or the row
     in the 'mysql.servers' table) to connect to the remote server.

The following items indicate features that the 'FEDERATED' storage
engine does and does not support:

   * The remote server must be a MySQL server.

   * The remote table that a 'FEDERATED' table points to _must_ exist
     before you try to access the table through the 'FEDERATED' table.

   * It is possible for one 'FEDERATED' table to point to another, but
     you must be careful not to create a loop.

   * A 'FEDERATED' table does not support indexes in the usual sense;
     because access to the table data is handled remotely, it is
     actually the remote table that makes use of indexes.  This means
     that, for a query that cannot use any indexes and so requires a
     full table scan, the server fetches all rows from the remote table
     and filters them locally.  This occurs regardless of any 'WHERE' or
     'LIMIT' used with this 'SELECT' statement; these
     clauses are applied locally to the returned rows.

     Queries that fail to use indexes can thus cause poor performance
     and network overload.  In addition, since returned rows must be
     stored in memory, such a query can also lead to the local server
     swapping, or even hanging.

   * Care should be taken when creating a 'FEDERATED' table since the
     index definition from an equivalent 'MyISAM' or other table may not
     be supported.  For example, creating a 'FEDERATED' table with an
     index prefix on 'VARCHAR', 'TEXT' or
     'BLOB' columns will fail.  The following definition in
     'MyISAM' is valid:

          CREATE TABLE `T1`(`A` VARCHAR(100),UNIQUE KEY(`A`(30))) ENGINE=MYISAM;

     The key prefix in this example is incompatible with the 'FEDERATED'
     engine, and the equivalent statement will fail:

          CREATE TABLE `T1`(`A` VARCHAR(100),UNIQUE KEY(`A`(30))) ENGINE=FEDERATED
            CONNECTION='MYSQL://127.0.0.1:3306/TEST/T1';

     If possible, you should try to separate the column and index
     definition when creating tables on both the remote server and the
     local server to avoid these index issues.

   * Internally, the implementation uses 'SELECT',
     'INSERT', 'UPDATE', and 'DELETE',
     but not 'HANDLER'.

   * The 'FEDERATED' storage engine supports 'SELECT',
     'INSERT', 'UPDATE', 'DELETE',
     see 'TRUNCATE TABLE', and indexes.  It
     does not support 'ALTER TABLE', or any Data
     Definition Language statements that directly affect the structure
     of the table, other than 'DROP TABLE'.  The
     current implementation does not use prepared statements.

   * 'FEDERATED' accepts 'INSERT ... ON DUPLICATE KEY UPDATE'
     statements, but if a duplicate-key violation
     occurs, the statement fails with an error.

   * Transactions are not supported.

   * 'FEDERATED' performs bulk-insert handling such that multiple rows
     are sent to the remote table in a batch, which improves
     performance.  Also, if the remote table is transactional, it
     enables the remote storage engine to perform statement rollback
     properly should an error occur.  This capability has the following
     limitations:

        * The size of the insert cannot exceed the maximum packet size
          between servers.  If the insert exceeds this size, it is
          broken into multiple packets and the rollback problem can
          occur.

        * Bulk-insert handling does not occur for 'INSERT ... ON DUPLICATE KEY UPDATE'.

   * There is no way for the 'FEDERATED' engine to know if the remote
     table has changed.  The reason for this is that this table must
     work like a data file that would never be written to by anything
     other than the database system.  The integrity of the data in the
     local table could be breached if there was any change to the remote
     database.

   * When using a 'CONNECTION' string, you cannot use an '@' character
     in the password.  You can get round this limitation by using the
     'CREATE SERVER' statement to create a server
     connection.

   * The 'insert_id' and 'timestamp' options are not propagated to the
     data provider.

   * Any 'DROP TABLE' statement issued against a
     'FEDERATED' table drops only the local table, not the remote table.

   * 'FEDERATED' tables do not work with the query cache.

   * User-defined partitioning is not supported for 'FEDERATED' tables.

15.8.4 FEDERATED Storage Engine Resources
-----------------------------------------

The following additional resources are available for the 'FEDERATED'
storage engine:

   * A forum dedicated to the 'FEDERATED' storage engine is available at
     <http://forums.mysql.com/list.php?105>.

15.9 The EXAMPLE Storage Engine
===============================

The 'EXAMPLE' storage engine is a stub engine that does nothing.  Its
purpose is to serve as an example in the MySQL source code that
illustrates how to begin writing new storage engines.  As such, it is
primarily of interest to developers.

To enable the 'EXAMPLE' storage engine if you build MySQL from source,
invoke 'CMake' with the '-DWITH_EXAMPLE_STORAGE_ENGINE' option.

To examine the source for the 'EXAMPLE' engine, look in the
'storage/example' directory of a MySQL source distribution.

When you create an 'EXAMPLE' table, the server creates a table format
file in the database directory.  The file begins with the table name and
has an '.frm' extension.  No other files are created.  No data can be
stored into the table.  Retrievals return an empty result.

     mysql> CREATE TABLE test (i INT) ENGINE = EXAMPLE;
     Query OK, 0 rows affected (0.78 sec)

     mysql> INSERT INTO test VALUES(1),(2),(3);
     ERROR 1031 (HY000): Table storage engine for 'test' doesn't »
                         have this option

     mysql> SELECT * FROM test;
     Empty set (0.31 sec)

The 'EXAMPLE' storage engine does not support indexing.

15.10 Other Storage Engines
===========================

Other storage engines may be available from third parties and community
members that have used the Custom Storage Engine interface.

Third party engines are not supported by MySQL. For further information,
documentation, installation guides, bug reporting or for any help or
assistance with these engines, please contact the developer of the
engine directly.

For more information on developing a customer storage engine that can be
used with the Pluggable Storage Engine Architecture, see MySQL
Internals: Writing a Custom Storage Engine
(http://dev.mysql.com/doc/internals/en/custom-engine.html).

15.11 Overview of MySQL Storage Engine Architecture
===================================================

The MySQL pluggable storage engine architecture enables a database
professional to select a specialized storage engine for a particular
application need while being completely shielded from the need to manage
any specific application coding requirements.  The MySQL server
architecture isolates the application programmer and DBA from all of the
low-level implementation details at the storage level, providing a
consistent and easy application model and API. Thus, although there are
different capabilities across different storage engines, the application
is shielded from these differences.

The pluggable storage engine architecture provides a standard set of
management and support services that are common among all underlying
storage engines.  The storage engines themselves are the components of
the database server that actually perform actions on the underlying data
that is maintained at the physical server level.

This efficient and modular architecture provides huge benefits for those
wishing to specifically target a particular application need--such as
data warehousing, transaction processing, or high availability
situations--while enjoying the advantage of utilizing a set of
interfaces and services that are independent of any one storage engine.

The application programmer and DBA interact with the MySQL database
through Connector APIs and service layers that are above the storage
engines.  If application changes bring about requirements that demand
the underlying storage engine change, or that one or more storage
engines be added to support new needs, no significant coding or process
changes are required to make things work.  The MySQL server architecture
shields the application from the underlying complexity of the storage
engine by presenting a consistent and easy-to-use API that applies
across storage engines.

15.11.1 Pluggable Storage Engine Architecture
---------------------------------------------

MySQL Server uses a pluggable storage engine architecture that enables
storage engines to be loaded into and unloaded from a running MySQL
server.

*Plugging in a Storage Engine*

Before a storage engine can be used, the storage engine plugin shared
library must be loaded into MySQL using the 'INSTALL PLUGIN'
statement.  For example, if the 'EXAMPLE' engine plugin
is named 'example' and the shared library is named 'ha_example.so', you
load it with the following statement:

     INSTALL PLUGIN example SONAME 'ha_example.so';

To install a pluggable storage engine, the plugin file must be located
in the MySQL plugin directory, and the user issuing the 'INSTALL PLUGIN'
statement must have 'INSERT' privilege for the
'mysql.plugin' table.

The shared library must be located in the MySQL server plugin directory,
the location of which is given by the 'plugin_dir' system variable.

*Unplugging a Storage Engine*

To unplug a storage engine, use the 'UNINSTALL PLUGIN'
statement:

     UNINSTALL PLUGIN example;

If you unplug a storage engine that is needed by existing tables, those
tables become inaccessible, but will still be present on disk (where
applicable).  Ensure that there are no tables using a storage engine
before you unplug the storage engine.

15.11.2 The Common Database Server Layer
----------------------------------------

A MySQL pluggable storage engine is the component in the MySQL database
server that is responsible for performing the actual data I/O operations
for a database as well as enabling and enforcing certain feature sets
that target a specific application need.  A major benefit of using
specific storage engines is that you are only delivered the features
needed for a particular application, and therefore you have less system
overhead in the database, with the end result being more efficient and
higher database performance.  This is one of the reasons that MySQL has
always been known to have such high performance, matching or beating
proprietary monolithic databases in industry standard benchmarks.

From a technical perspective, what are some of the unique supporting
infrastructure components that are in a storage engine?  Some of the key
feature differentiations include:

   * _Concurrency_: Some applications have more granular lock
     requirements (such as row-level locks) than others.  Choosing the
     right locking strategy can reduce overhead and therefore improve
     overall performance.  This area also includes support for
     capabilities such as multi-version concurrency control or
     'snapshot' read.

   * _Transaction Support_: Not every application needs transactions,
     but for those that do, there are very well defined requirements
     such as ACID compliance and more.

   * _Referential Integrity_: The need to have the server enforce
     relational database referential integrity through DDL defined
     foreign keys.

   * _Physical Storage_: This involves everything from the overall page
     size for tables and indexes as well as the format used for storing
     data to physical disk.

   * _Index Support_: Different application scenarios tend to benefit
     from different index strategies.  Each storage engine generally has
     its own indexing methods, although some (such as B-tree indexes)
     are common to nearly all engines.

   * _Memory Caches_: Different applications respond better to some
     memory caching strategies than others, so although some memory
     caches are common to all storage engines (such as those used for
     user connections or MySQL's high-speed Query Cache), others are
     uniquely defined only when a particular storage engine is put in
     play.

   * _Performance Aids_: This includes multiple I/O threads for parallel
     operations, thread concurrency, database checkpointing, bulk insert
     handling, and more.

   * _Miscellaneous Target Features_: This may include support for
     geospatial operations, security restrictions for certain data
     manipulation operations, and other similar features.

Each set of the pluggable storage engine infrastructure components are
designed to offer a selective set of benefits for a particular
application.  Conversely, avoiding a set of component features helps
reduce unnecessary overhead.  It stands to reason that understanding a
particular application's set of requirements and selecting the proper
MySQL storage engine can have a dramatic impact on overall system
efficiency and performance.

16 Replication
**************

Replication enables data from one MySQL database server (the master) to
be copied to one or more MySQL database servers (the slaves).
Replication is asynchronous by default; slaves do not need to be
connected permanently to receive updates from the master.  Depending on
the configuration, you can replicate all databases, selected databases,
or even selected tables within a database.

Advantages of replication in MySQL include:

   * Scale-out solutions - spreading the load among multiple slaves to
     improve performance.  In this environment, all writes and updates
     must take place on the master server.  Reads, however, may take
     place on one or more slaves.  This model can improve the
     performance of writes (since the master is dedicated to updates),
     while dramatically increasing read speed across an increasing
     number of slaves.

   * Data security - because data is replicated to the slave, and the
     slave can pause the replication process, it is possible to run
     backup services on the slave without corrupting the corresponding
     master data.

   * Analytics - live data can be created on the master, while the
     analysis of the information can take place on the slave without
     affecting the performance of the master.

   * Long-distance data distribution - you can use replication to create
     a local copy of data for a remote site to use, without permanent
     access to the master.

For information on how to use replication in such scenarios, see
replication-solutions.

MySQL 5.7 supports different methods of replication.  The traditional
method is based on replicating events from the master's binary log, and
requires the log files and positions in them to be synchronized between
master and slave.  The newer method based on _global transaction
identifiers_ (GTIDs) is transactional and therefore does not require
working with log files or positions within these files, which greatly
simplifies many common replication tasks.  Replication using GTIDs
guarantees consistency between master and slave as long as all
transactions committed on the master have also been applied on the
slave.  For more information about GTIDs and GTID-based replication in
MySQL, see replication-gtids.  For information on using binary
log file position based replication, see
replication-configuration.

Replication in MySQL supports different types of synchronization.  The
original type of synchronization is one-way, asynchronous replication,
in which one server acts as the master, while one or more other servers
act as slaves.  This is in contrast to the _synchronous_ replication
which is a characteristic of NDB Cluster (see mysql-cluster).
In MySQL 5.7, semisynchronous replication is supported in addition to
the built-in asynchronous replication.  With semisynchronous
replication, a commit performed on the master blocks before returning to
the session that performed the transaction until at least one slave
acknowledges that it has received and logged the events for the
transaction; see replication-semisync.  MySQL 5.7 also supports
delayed replication such that a slave server deliberately lags behind
the master by at least a specified amount of time; see
replication-delayed.  For scenarios where _synchronous_ replication is
required, use NDB Cluster (see mysql-cluster).

There are a number of solutions available for setting up replication
between servers, and the best method to use depends on the presence of
data and the engine types you are using.  For more information on the
available options, see replication-howto.

There are two core types of replication format, Statement Based
Replication (SBR), which replicates entire SQL statements, and Row Based
Replication (RBR), which replicates only the changed rows.  You can also
use a third variety, Mixed Based Replication (MBR). For more information
on the different replication formats, see replication-formats.

Replication is controlled through a number of different options and
variables.  For more information, see replication-options.

You can use replication to solve a number of different problems,
including performance, supporting the backup of different databases, and
as part of a larger solution to alleviate system failures.  For
information on how to address these issues, see
replication-solutions.

For notes and tips on how different data types and statements are
treated during replication, including details of replication features,
version compatibility, upgrades, and potential problems and their
resolution, see replication-notes.  For answers to some
questions often asked by those who are new to MySQL Replication, see
faqs-replication.

For detailed information on the implementation of replication, how
replication works, the process and contents of the binary log,
background threads and the rules used to decide how statements are
recorded and replicated, see replication-implementation.

16.1 Configuring Replication
============================

This section describes how to configure the different types of
replication available in MySQL and includes the setup and configuration
required for a replication environment, including step-by-step
instructions for creating a new replication environment.  The major
components of this section are:

   * For a guide to setting up two or more servers for replication using
     binary log file positions, see replication-howto, deals with
     the configuration of the servers and provides methods for copying
     data between the master and slaves.

   * For a guide to setting up two or more servers for replication using
     GTID transactions, see replication-gtids, deals with the
     configuration of the servers.

   * Events in the binary log are recorded using a number of formats.
     These are referred to as statement-based replication (SBR) or
     row-based replication (RBR). A third type, mixed-format replication
     (MIXED), uses SBR or RBR replication automatically to take
     advantage of the benefits of both SBR and RBR formats when
     appropriate.  The different formats are discussed in
     replication-formats.

   * Detailed information on the different configuration options and
     variables that apply to replication is provided in
     replication-options.

   * Once started, the replication process should require little
     administration or monitoring.  However, for advice on common tasks
     that you may want to execute, see
     replication-administration.

16.1.1 Binary Log File Position Based Replication Configuration Overview
------------------------------------------------------------------------

This section describes replication between MySQL servers based on the
binary log file position method, where the MySQL instance operating as
the master (the source of the database changes) writes updates and
changes as 'events' to the binary log.  The information in the binary
log is stored in different logging formats according to the database
changes being recorded.  Slaves are configured to read the binary log
from the master and to execute the events in the binary log on the
slave's local database.

Each slave receives a copy of the entire contents of the binary log.  It
is the responsibility of the slave to decide which statements in the
binary log should be executed.  Unless you specify otherwise, all events
in the master binary log are executed on the slave.  If required, you
can configure the slave to process only events that apply to particular
databases or tables.

*Important*:

You cannot configure the master to log only certain events.

Each slave keeps a record of the binary log coordinates: the file name
and position within the file that it has read and processed from the
master.  This means that multiple slaves can be connected to the master
and executing different parts of the same binary log.  Because the
slaves control this process, individual slaves can be connected and
disconnected from the server without affecting the master's operation.
Also, because each slave records the current position within the binary
log, it is possible for slaves to be disconnected, reconnect and then
resume processing.

The master and each slave must be configured with a unique ID (using the
'server-id' option).  In addition, each slave must be configured with
information about the master host name, log file name, and position
within that file.  These details can be controlled from within a MySQL
session using the 'CHANGE MASTER TO' statement
on the slave.  The details are stored within the slave's master info
repository, which can be either a file or a table (see
slave-logs).

16.1.2 Setting Up Binary Log File Position Based Replication
------------------------------------------------------------

This section describes how to set up a MySQL server to use binary log
file position based replication.  There are a number of different
methods for setting up replication, and the exact method to use depends
on how you are setting up replication, and whether you already have data
within your master database.

There are some generic tasks that are common to all setups:

   * On the master, you must enable binary logging and configure a
     unique server ID. This might require a server restart.  See
     replication-howto-masterbaseconfig.

   * On each slave that you want to connect to the master, you must
     configure a unique server ID. This might require a server restart.
     See replication-howto-slavebaseconfig.

   * Optionally, create a separate user for your slaves to use during
     authentication with the master when reading the binary log for
     replication.  See replication-howto-repuser.

   * Before creating a data snapshot or starting the replication
     process, on the master you should record the current position in
     the binary log.  You need this information when configuring the
     slave so that the slave knows where within the binary log to start
     executing events.  See replication-howto-masterstatus.

   * If you already have data on the master and want to use it to
     synchronize the slave, you need to create a data snapshot to copy
     the data to the slave.  The storage engine you are using has an
     impact on how you create the snapshot.  When you are using
     'MyISAM', you must stop processing
     statements on the master to obtain a read-lock, then obtain its
     current binary log coordinates and dump its data, before permitting
     the master to continue executing statements.  If you do not stop
     the execution of statements, the data dump and the master status
     information will not match, resulting in inconsistent or corrupted
     databases on the slaves.  For more information on replicating a
     'MyISAM' master, see
     replication-howto-masterstatus.  If you are using 'InnoDB',
     you do not need a read-lock and a
     transaction that is long enough to transfer the data snapshot is
     sufficient.  For more information, see
     innodb-and-mysql-replication.

   * Configure the slave with settings for connecting to the master,
     such as the host name, login credentials, and binary log file name
     and position.  See replication-howto-slaveinit.

*Note*:

Certain steps within the setup process require the 'SUPER' privilege.
If you do not have this privilege, it might not be possible to enable
replication.

After configuring the basic options, select your scenario:

   * To set up replication for a fresh installation of a master and
     slaves that contain no data, see
     replication-howto-newservers.

   * To set up replication of a new master using the data from an
     existing MySQL server, see replication-howto-existingdata.

   * To add replication slaves to an existing replication environment,
     see replication-howto-additionalslaves.

Before administering MySQL replication servers, read this entire chapter
and try all statements mentioned in replication-master-sql, and
replication-slave-sql.  Also familiarize yourself with the
replication startup options described in replication-options.

16.1.2.1 Setting the Replication Master Configuration
.....................................................

To configure a master to use binary log file position based replication,
you must enable binary logging and establish a unique server ID. If this
has not already been done, a server restart is required.

Binary logging _must_ be enabled on the master because the binary log is
the basis for replicating changes from the master to its slaves.  If
binary logging is not enabled on the master using the 'log-bin' option,
replication is not possible.

Each server within a replication group must be configured with a unique
server ID. This ID is used to identify individual servers within the
group, and must be a positive integer between 1 and (2^32)−1.  How you
organize and select the numbers is your choice.

To configure the binary log and server ID options, shut down the MySQL
server and edit the 'my.cnf' or 'my.ini' file.  Within the '[mysqld]'
section of the configuration file, add the 'log-bin' and 'server-id'
options.  If these options already exist, but are commented out,
uncomment the options and alter them according to your needs.  For
example, to enable binary logging using a log file name prefix of
'mysql-bin', and configure a server ID of 1, use these lines:

     [mysqld]
     log-bin=mysql-bin
     server-id=1

After making the changes, restart the server.

*Note*:

The following options have an impact on this procedure:

   * if you omit 'server-id' (or set it explicitly to its default value
     of 0), the master refuses any connections from slaves.

   * For the greatest possible durability and consistency in a
     replication setup using 'InnoDB' with
     transactions, you should use 'innodb_flush_log_at_trx_commit=1' and
     'sync_binlog=1' in the master 'my.cnf' file.

   * Ensure that the 'skip-networking' option is not enabled on your
     replication master.  If networking has been disabled, the slave
     cannot communicate with the master and replication fails.

16.1.2.2 Creating a User for Replication
........................................

Each slave connects to the master using a MySQL user name and password,
so there must be a user account on the master that the slave can use to
connect.  The user name is specified by the 'MASTER_USER' option on the
'CHANGE MASTER TO' command when you set up a replication slave.  Any
account can be used for this operation, providing it has been granted
the 'REPLICATION SLAVE' privilege.  You can choose to create a different
account for each slave, or connect to the master using the same account
for each slave.

Although you do not have to create an account specifically for
replication, you should be aware that the replication user name and
password are stored in plain text in the master info repository file or
table (see slave-logs-status).  Therefore, you may want to
create a separate account that has privileges only for the replication
process, to minimize the possibility of compromise to other accounts.

To create a new account, use 'CREATE USER'.  To grant
this account the privileges required for replication, use the
'GRANT' statement.  If you create an account solely for the
purposes of replication, that account needs only the 'REPLICATION SLAVE'
privilege.  For example, to set up a new user, 'repl', that can connect
for replication from any host within the 'example.com' domain, issue
these statements on the master:

     mysql> CREATE USER 'repl'@'%.example.com' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT REPLICATION SLAVE ON *.* TO 'repl'@'%.example.com';

See account-management-sql, for more information on statements
for manipulation of user accounts.

16.1.2.3 Obtaining the Replication Master Binary Log Coordinates
................................................................

To configure the slave to start the replication process at the correct
point, you need the master's current coordinates within its binary log.

If the master has been running previously without binary logging
enabled, the log file name and position values displayed by 'SHOW MASTER STATUS'
or 'mysqldump --master-data'
are empty.  In that case, the values that you need to use
later when specifying the slave's log file and position are the empty
string ('''') and '4'.

If the master has been binary logging previously, use this procedure to
obtain the master binary log coordinates:

*Warning*:

This procedure uses 'FLUSH TABLES WITH READ LOCK', which blocks
'COMMIT' operations for 'InnoDB'.
tables.

  1. Start a session on the master by connecting to it with the
     command-line client, and flush all tables and block write
     statements by executing the 'FLUSH TABLES WITH READ LOCK'
     statement:

          mysql> FLUSH TABLES WITH READ LOCK;

     *Warning*:

     Leave the client from which you issued the 'FLUSH TABLES' statement
     running so that the read lock remains in effect.  If you exit the
     client, the lock is released.

  2. In a different session on the master, use the 'SHOW MASTER STATUS'
     statement to determine the current
     binary log file name and position:

          mysql > SHOW MASTER STATUS;
          +------------------+----------+--------------+------------------+
          | File             | Position | Binlog_Do_DB | Binlog_Ignore_DB |
          +------------------+----------+--------------+------------------+
          | mysql-bin.000003 | 73       | test         | manual,mysql     |
          +------------------+----------+--------------+------------------+

     The 'File' column shows the name of the log file and the 'Position'
     column shows the position within the file.  In this example, the
     binary log file is 'mysql-bin.000003' and the position is 73.
     Record these values.  You need them later when you are setting up
     the slave.  They represent the replication coordinates at which the
     slave should begin processing new updates from the master.

You now have the information you need to enable the slave to start
reading from the binary log in the correct place to start replication.

The next step depends on whether you have existing data on the master.
Choose one of the following options:

   * If you have existing data that needs be to synchronized with the
     slave before you start replication, leave the client running so
     that the lock remains in place.  This prevents any further changes
     being made, so that the data copied to the slave is in synchrony
     with the master.  Proceed to replication-snapshot-method.

   * If you are setting up a new master and slave replication group, you
     can exit the first session to release the read lock.  See
     replication-howto-newservers for how to proceed.

16.1.2.4 Choosing a Method for Data Snapshots
.............................................

If the master database contains existing data it is necessary to copy
this data to each slave.  There are different ways to dump the data from
the master database.  The following sections describe possible options.

To select the appropriate method of dumping the database, choose between
these options:

   * Use the 'mysqldump' tool to create a dump of all
     the databases you want to replicate.  This is the recommended
     method, especially when using 'InnoDB'.

   * If your database is stored in binary portable files, you can copy
     the raw data files to a slave.  This can be more efficient than
     using 'mysqldump' and importing the file on each
     slave, because it skips the overhead of updating indexes as the
     'INSERT' statements are replayed.  With storage engines such as
     'InnoDB' this is not recommended.

16.1.2.5 Creating a Data Snapshot Using mysqldump
.................................................

To create a snapshot of the data in an existing master database, use the
'mysqldump' tool.  Once the data dump has been
completed, import this data into the slave before starting the
replication process.

The following example dumps all databases to a file named 'dbdump.db',
and includes the '--master-data' option which automatically appends the
'CHANGE MASTER TO' statement required on the
slave to start the replication process:

     shell> mysqldump --all-databases --master-data > dbdump.db

*Note*:

If you do not use '--master-data', then it is necessary to lock all
tables in a separate session manually.  See
replication-howto-masterstatus.

It is possible to exclude certain databases from the dump using the
'mysqldump' tool.  If you want to choose which
databases to include in the dump, do not use '--all-databases'.  Choose
one of these options:

   * Exclude all the tables in the database using '--ignore-table'
     option.

   * Name only those databases which you want dumped using the
     '--databases' option.

For more information, see mysqldump.

To import the data, either copy the dump file to the slave, or access
the file from the master when connecting remotely to the slave.

16.1.2.6 Creating a Data Snapshot Using Raw Data Files
......................................................

This section describes how to create a data snapshot using the raw files
which make up the database.

Employing this method with a table using a storage engine that has
complex caching or logging algorithms requires extra steps to produce a
perfect 'point in time' snapshot: the initial copy command could leave
out cache information and logging updates, even if you have acquired a
global read lock.  How the storage engine responds to this depends on
its crash recovery abilities.

If you use 'InnoDB' tables, you can use
the 'mysqlbackup' command from the MySQL Enterprise Backup component to
produce a consistent snapshot.  This command records the log name and
offset corresponding to the snapshot to be used on the slave.  MySQL
Enterprise Backup is a commercial product that is included as part of a
MySQL Enterprise subscription.  See mysql-enterprise-backup for
detailed information.

This method also does not work reliably if the master and slave have
different values for 'ft_stopword_file', 'ft_min_word_len', or
'ft_max_word_len' and you are copying tables having full-text indexes.

Assuming the above exceptions do not apply to your database, use the
cold backup technique to obtain a reliable binary snapshot of 'InnoDB'
tables: do a slow shutdown of the MySQL Server, then copy the data files
manually.

To create a raw data snapshot of 'MyISAM'.
tables when your MySQL data files exist on a single file system, you can
use standard file copy tools such as 'cp' or 'copy', a remote copy tool
such as 'scp' or 'rsync', an archiving tool such as 'zip' or 'tar', or a
file system snapshot tool such as 'dump'.  If you are replicating only
certain databases, copy only those files that relate to those tables.
For 'InnoDB', all tables in all databases are stored in the system
tablespace files, unless you have the 'innodb_file_per_table' option
enabled.

The following files are not required for replication:

   * Files relating to the 'mysql' database.

   * The master info repository file, if used (see slave-logs).

   * The master's binary log files.

   * Any relay log files.

Depending on whether you are using 'InnoDB' tables or not, choose one of
the following:

If you are using 'InnoDB' tables, and also
to get the most consistent results with a raw data snapshot, shut down
the master server during the process, as follows:

  1. Acquire a read lock and get the master's status.  See
     replication-howto-masterstatus.

  2. In a separate session, shut down the master server:

          shell> mysqladmin shutdown

  3. Make a copy of the MySQL data files.  The following examples show
     common ways to do this.  You need to choose only one of them:

          shell> tar cf /TMP/DB.TAR ./DATA
          shell> zip -r /TMP/DB.ZIP ./DATA
          shell> rsync --recursive ./DATA /TMP/DBDATA

  4. Restart the master server.

If you are not using 'InnoDB' tables, you
can get a snapshot of the system from a master without shutting down the
server as described in the following steps:

  1. Acquire a read lock and get the master's status.  See
     replication-howto-masterstatus.

  2. Make a copy of the MySQL data files.  The following examples show
     common ways to do this.  You need to choose only one of them:

          shell> tar cf /TMP/DB.TAR ./DATA
          shell> zip -r /TMP/DB.ZIP ./DATA
          shell> rsync --recursive ./DATA /TMP/DBDATA

  3. In the client where you acquired the read lock, release the lock:

          mysql> UNLOCK TABLES;

Once you have created the archive or copy of the database, copy the
files to each slave before starting the slave replication process.

16.1.2.7 Setting Up Replication Slaves
......................................

The following sections describe how to set up slaves.  Before you
proceed, ensure that you have:

   * Configured the MySQL master with the necessary configuration
     properties.  See replication-howto-masterbaseconfig.

   * Obtained the master status information.  See
     replication-howto-masterstatus.

   * On the master, released the read lock:

          mysql> UNLOCK TABLES;

16.1.2.8 Setting the Replication Slave Configuration
....................................................

Each replication slave _must_ have a unique server ID. If this has not
already been done, this part of slave setup requires a server restart.

If the slave server ID is not already set, or the current value
conflicts with the value that you have chosen for the master server,
shut down the slave server and edit the '[mysqld]' section of the
configuration file to specify a unique server ID. For example:

     [mysqld]
     server-id=2

After making the changes, restart the server.

If you are setting up multiple slaves, each one must have a unique
'server-id' value that differs from that of the master and from any of
the other slaves.

*Note*:

If you omit 'server-id' (or set it explicitly to its default value of
0), the slave refuses to connect to a master.

You do not have to enable binary logging on the slave for replication to
be set up.  However, if you enable binary logging on the slave, you can
use the slave's binary log for data backups and crash recovery, and also
use the slave as part of a more complex replication topology.  For
example, where this slave then acts as a master to other slaves.

16.1.2.9 Setting the Master Configuration on the Slave
......................................................

To set up the slave to communicate with the master for replication,
configure the slave with the necessary connection information.  To do
this, execute the following statement on the slave, replacing the option
values with the actual values relevant to your system:

     mysql> CHANGE MASTER TO
         ->     MASTER_HOST='MASTER_HOST_NAME',
         ->     MASTER_USER='REPLICATION_USER_NAME',
         ->     MASTER_PASSWORD='REPLICATION_PASSWORD',
         ->     MASTER_LOG_FILE='RECORDED_LOG_FILE_NAME',
         ->     MASTER_LOG_POS=RECORDED_LOG_POSITION;

*Note*:

Replication cannot use Unix socket files.  You must be able to connect
to the master MySQL server using TCP/IP.

The 'CHANGE MASTER TO' statement has other
options as well.  For example, it is possible to set up secure
replication using SSL. For a full list of options, and information about
the maximum permissible length for the string-valued options, see
change-master-to.

The next steps depend on whether you have existing data to import to the
slave or not.  See replication-snapshot-method for more
information.  Choose one of the following:

   * If you do not have a snapshot of a database to import, see
     replication-howto-newservers.

   * If you have a snapshot of a database to import, see
     replication-howto-existingdata.

16.1.2.10 Setting Up Replication between a New Master and Slaves
................................................................

When there is no snapshot of a previous database to import, configure
the slave to start the replication from the new master.

To set up replication between a master and a new slave:

  1. Start up the MySQL slave and connect to it.

  2. Execute a 'CHANGE MASTER TO' statement to
     set the master replication server configuration.  See
     replication-howto-slaveinit.

Perform these slave setup steps on each slave.

This method can also be used if you are setting up new servers but have
an existing dump of the databases from a different server that you want
to load into your replication configuration.  By loading the data into a
new master, the data is automatically replicated to the slaves.

If you are setting up a new replication environment using the data from
a different existing database server to create a new master, run the
dump file generated from that server on the new master.  The database
updates are automatically propagated to the slaves:

     shell> mysql -h master < fulldb.dump

16.1.2.11 Setting Up Replication with Existing Data
...................................................

When setting up replication with existing data, transfer the snapshot
from the master to the slave before starting replication.  The process
for importing data to the slave depends on how you created the snapshot
of data on the master.

Choose one of the following:

If you used 'mysqldump'.:

  1. Start the slave, using the '--skip-slave-start' option so that
     replication does not start.

  2. Import the dump file:

          shell> mysql < fulldb.dump

If you created a snapshot using the raw data files:

  1. Extract the data files into your slave data directory.  For
     example:

          shell> tar xvf dbdump.tar

     You may need to set permissions and ownership on the files so that
     the slave server can access and modify them.

  2. Start the slave, using the '--skip-slave-start' option so that
     replication does not start.

  3. Configure the slave with the replication coordinates from the
     master.  This tells the slave the binary log file and position
     within the file where replication needs to start.  Also, configure
     the slave with the login credentials and host name of the master.
     For more information on the 'CHANGE MASTER TO'
     statement required, see
     replication-howto-slaveinit.

  4. Start the slave threads:

          mysql> START SLAVE;

After you have performed this procedure, the slave connects to the
master and replicates any updates that have occurred on the master since
the snapshot was taken.

If the 'server-id' option for the master is not correctly set, slaves
cannot connect to it.  Similarly, if you have not set the 'server-id'
option correctly for the slave, you get the following error in the
slave's error log:

     Warning: You should set server-id to a non-0 value if master_host
     is set; we will force server id to 2, but this MySQL server will
     not act as a slave.

You also find error messages in the slave's error log if it is not able
to replicate for any other reason.

The slave stores information about the master you have configured in its
master info repository.  The master info repository can be in the form
of files or a table, as determined by the value set for
'--master-info-repository'.  When a slave uses
'--master-info-repository=FILE', two files are stored in the data
directory, named 'master.info' and 'relay-log.info'.  If
'--master-info-repository=TABLE' instead, this information is saved in
the 'master_slave_info' table in the 'mysql' database.  In either case,
do _not_ remove or edit the files or table.  Always use the
'CHANGE MASTER TO' statement to change replication
parameters.  The slave can use the values specified in the statement to
update the status files automatically.  See slave-logs, for more
information.

*Note*:

The contents of the master info repository override some of the server
options specified on the command line or in 'my.cnf'.  See
replication-options, for more details.

A single snapshot of the master suffices for multiple slaves.  To set up
additional slaves, use the same master snapshot and follow the slave
portion of the procedure just described.

16.1.2.12 Adding Slaves to a Replication Environment
....................................................

You can add another slave to an existing replication configuration
without stopping the master.  Instead, set up the new slave by making a
copy of an existing slave, except that you configure the new slave with
a different 'server-id' value.

To duplicate an existing slave:

  1. Shut down the existing slave:

          shell> mysqladmin shutdown

  2. Copy the data directory from the existing slave to the new slave.
     You can do this by creating an archive using 'tar' or 'WinZip', or
     by performing a direct copy using a tool such as 'cp' or 'rsync'.
     Ensure that you also copy the log files and relay log files.

     A common problem that is encountered when adding new replication
     slaves is that the new slave fails with a series of warning and
     error messages like these:

          071118 16:44:10 [Warning] Neither --relay-log nor --relay-log-index were used; so
          replication may break when this MySQL server acts as a slave and has his hostname
          changed!! Please use '--relay-log=NEW_SLAVE_HOSTNAME-relay-bin' to avoid this problem.
          071118 16:44:10 [ERROR] Failed to open the relay log './OLD_SLAVE_HOSTNAME-relay-bin.003525'
          (relay_log_pos 22940879)
          071118 16:44:10 [ERROR] Could not find target log during relay log initialization
          071118 16:44:10 [ERROR] Failed to initialize the master info structure

     This situation can occur if the '--relay-log' option is not
     specified, as the relay log files contain the host name as part of
     their file names.  This is also true of the relay log index file if
     the '--relay-log-index' option is not used.  See
     replication-options, for more information about these options.

     To avoid this problem, use the same value for '--relay-log' on the
     new slave that was used on the existing slave.  If this option was
     not set explicitly on the existing slave, use
     'EXISTING_SLAVE_HOSTNAME-relay-bin'.  If this is not possible, copy
     the existing slave's relay log index file to the new slave and set
     the '--relay-log-index' option on the new slave to match what was
     used on the existing slave.  If this option was not set explicitly
     on the existing slave, use
     'EXISTING_SLAVE_HOSTNAME-relay-bin.index'.  Alternatively, if you
     have already tried to start the new slave after following the
     remaining steps in this section and have encountered errors like
     those described previously, then perform the following steps:

       1. If you have not already done so, issue a 'STOP SLAVE'
          on the new slave.

          If you have already started the existing slave again, issue a
          'STOP SLAVE' on the existing slave as well.

       2. Copy the contents of the existing slave's relay log index file
          into the new slave's relay log index file, making sure to
          overwrite any content already in the file.

       3. Proceed with the remaining steps in this section.

  3. Copy the master info and relay log info repositories (see
     slave-logs) from the existing slave to the new slave.  These hold
     the current log coordinates for the master's binary log and the
     slave's relay log.

  4. Start the existing slave.

  5. On the new slave, edit the configuration and give the new slave a
     unique 'server-id' not used by the master or any of the existing
     slaves.

  6. Start the new slave.  The slave uses the information in its master
     info repository to start the replication process.

16.1.3 Replication with Global Transaction Identifiers
------------------------------------------------------

This section explains transaction-based replication using _global
transaction identifiers_ (GTIDs).  When using GTIDs, each transaction
can be identified and tracked as it is committed on the originating
server and applied by any slaves; this means that it is not necessary
when using GTIDs to refer to log files or positions within those files
when starting a new slave or failing over to a new master, which greatly
simplifies these tasks.  Because GTID-based replication is completely
transaction-based, it is simple to determine whether masters and slaves
are consistent; as long as all transactions committed on a master are
also committed on a slave, consistency between the two is guaranteed.
You can use either statement-based or row-based replication with GTIDs
(see replication-formats); however, for best results, we
recommend that you use the row-based format.

GTIDs are always preserved between master and slave.  This means that
you can always determine the source for any transaction applied on any
slave by examining its binary log.  In addition, once a transaction with
a given GTID is committed on a given server, any subsequent transaction
having the same GTID is ignored by that server.  Thus, a transaction
committed on the master can be applied no more than once on the slave,
which helps to guarantee consistency.

This section discusses the following topics:

   * How GTIDs are defined and created, and how they are represented in
     the MySQL Server (see replication-gtids-concepts).

   * A general procedure for setting up and starting GTID-based
     replication (see replication-gtids-howto).

   * Suggested methods for provisioning new replication servers when
     using GTIDs (see replication-gtids-failover).

   * Restrictions and limitations that you should be aware of when using
     GTID-based replication (see
     replication-gtids-restrictions).

For information about MySQL Server options and variables relating to
GTID-based replication, see replication-options-gtids.  See also
gtid-functions, which describes SQL functions supported by MySQL
5.7 for use with GTIDs.

16.1.3.1 GTID Format and Storage
................................

A global transaction identifier (GTID) is a unique identifier created
and associated with each transaction committed on the server of origin
(master).  This identifier is unique not only to the server on which it
originated, but is unique across all servers in a given replication
topology.

GTID assignment distinguishes between client transactions, which are
committed on the master, and replicated transactions, which are
reproduced on a slave.  When a client transaction is committed on the
master, it is assigned a new GTID, provided that the transaction was
written to the binary log.  Client transactions are guaranteed to have
monotonically increasing GTIDs without gaps between the generated
numbers.  If a client transaction is not written to the binary log (for
example, because the transaction was filtered out, or the transaction
was read-only), it is not assigned a GTID on the server of origin.

Replicated transactions retain the same GTID that was assigned to the
transaction on the server of origin.  The GTID is present before the
replicated transaction begins to execute, and is persisted even if the
replicated transaction is not written to the binary log on the slave, or
is filtered out on the slave.  The MySQL system table
'mysql.gtid_executed' is used to preserve the assigned GTIDs of all the
transactions applied on a MySQL server, except those that are stored in
a currently active binary log file.

The auto-skip function for GTIDs means that a transaction committed on
the master can be applied no more than once on the slave, which helps to
guarantee consistency.  Once a transaction with a given GTID has been
committed on a given server, any attempt to execute a subsequent
transaction with the same GTID is ignored by that server.  No error is
raised, and no statement in the transaction is executed.

If a transaction with a given GTID has started to execute on a server,
but has not yet committed or rolled back, any attempt to start a
concurrent transaction on the server with the same GTID will block.  The
server neither begins to execute the concurrent transaction nor returns
control to the client.  Once the first attempt at the transaction
commits or rolls back, concurrent sessions that were blocking on the
same GTID may proceed.  If the first attempt rolled back, one concurrent
session proceeds to attempt the transaction, and any other concurrent
sessions that were blocking on the same GTID remain blocked.  If the
first attempt committed, all the concurrent sessions stop being blocked,
and auto-skip all the statements of the transaction.

A GTID is represented as a pair of coordinates, separated by a colon
character (':'), as shown here:

     GTID = SOURCE_ID:TRANSACTION_ID

The SOURCE_ID identifies the originating server.  Normally, the server's
'server_uuid' is used for this purpose.  The TRANSACTION_ID is a
sequence number determined by the order in which the transaction was
committed on this server; for example, the first transaction to be
committed has '1' as its TRANSACTION_ID, and the tenth transaction to be
committed on the same originating server is assigned a TRANSACTION_ID of
'10'.  It is not possible for a transaction to have '0' as a sequence
number in a GTID. For example, the twenty-third transaction to be
committed originally on the server with the UUID
'3E11FA47-71CA-11E1-9E33-C80AA9429562' has this GTID:

     3E11FA47-71CA-11E1-9E33-C80AA9429562:23

This format is used to represent GTIDs in the output of statements such
as 'SHOW SLAVE STATUS' as well as in the
binary log.  They can also be seen when viewing the log file with
'mysqlbinlog'. '--base64-output=DECODE-ROWS' or in the
output from 'SHOW BINLOG EVENTS'.

As written in the output of statements such as 'SHOW MASTER STATUS'
or 'SHOW SLAVE STATUS', a sequence of GTIDs
originating from the same server may be collapsed into a single
expression, as shown here.

     3E11FA47-71CA-11E1-9E33-C80AA9429562:1-5

The example just shown represents the first through fifth transactions
originating on the MySQL Server whose 'server_uuid' is
'3E11FA47-71CA-11E1-9E33-C80AA9429562'.

This format is also used to supply the argument required by the
'START SLAVE' options 'SQL_BEFORE_GTIDS' and
'SQL_AFTER_GTIDS'.

*GTID Sets*

A GTID set is a set of global transaction identifiers which is
represented as shown here:

     GTID_SET:
         UUID_SET [, UUID_SET] ...
         | ''

     UUID_SET:
         UUID:INTERVAL[:INTERVAL]...

     UUID:
         HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH

     H:
         [0-9|A-F]

     INTERVAL:
         N[-N]

         (N >= 1)

GTID sets are used in the MySQL Server in several ways.  For example,
the values stored by the 'gtid_executed' and 'gtid_purged' system
variables are represented as GTID sets.  In addition, the functions
'GTID_SUBSET()' and 'GTID_SUBTRACT()' require GTID sets as input.  When
GTID sets are returned from server variables, UUIDs are in alphabetical
order and numeric intervals are merged and in ascending order.

When GTIDs are in use, the slave has no need for any nonlocal data, such
as the name of a file on the master and a position within that file.
All necessary information for synchronizing with the master is obtained
directly from the replication data stream.  GTIDs replace the
file-offset pairs previously required to determine points for starting,
stopping, or resuming the flow of data between master and slave.
therefore, do not include 'MASTER_LOG_FILE' or 'MASTER_LOG_POS' options
in the 'CHANGE MASTER TO' statement used to
direct a slave to replicate from a given master; instead it is necessary
only to enable the 'MASTER_AUTO_POSITION' option.  For the exact steps
needed to configure and start masters and slaves using GTID-based
replication, see replication-gtids-howto.

The generation and life cycle of a GTID consist of the following steps:

  1. A transaction is executed and committed on the master.

     This transaction is assigned a GTID using the master's UUID and the
     smallest nonzero transaction sequence number not yet used on this
     server; the GTID is written to the master's binary log (immediately
     preceding the transaction itself in the log).

  2. After the binary log data is transmitted to the slave and stored in
     the slave's relay log (using established mechanisms for this
     process--see replication-implementation, for details), the
     slave reads the GTID and sets the value of its 'gtid_next' system
     variable as this GTID. This tells the slave that the next
     transaction must be logged using this GTID.

     It is important to note that the slave sets 'gtid_next' in a
     session context.

  3. The slave verifies that this GTID has not already been used to log
     a transaction in its own binary log.  If this GTID has not been
     used, the slave then writes the GTID, applies the transaction, and
     writes the transaction to its binary log.  By reading and checking
     the transaction's GTID first, before processing the transaction
     itself, the slave guarantees not only that no previous transaction
     having this GTID has been applied on the slave, but also that no
     other session has already read this GTID but has not yet committed
     the associated transaction.  In other words, multiple clients are
     not permitted to apply the same transaction concurrently.

  4. Because 'gtid_next' is not empty, the slave does not attempt to
     generate a GTID for this transaction but instead writes the GTID
     stored in this variable--that is, the GTID obtained from the
     master--immediately preceding the transaction in its binary log.

*mysql.gtid_executed Table*

Beginning with MySQL 5.7.5, GTIDs are stored in a table named
'gtid_executed', in the 'mysql' database.  A row in this table contains,
for each GTID or set of GTIDs that it represents, the UUID of the
originating server, and the starting and ending transaction IDs of the
set; for a row referencing only a single GTID, these last two values are
the same.

The 'mysql.gtid_executed' table is created (if it does not already
exist) when the MySQL Server is installed or upgraded, using a
'CREATE TABLE' statement similar to that shown here:

     CREATE TABLE gtid_executed (
         source_uuid CHAR(36) NOT NULL,
         interval_start BIGINT(20) NOT NULL,
         interval_end BIGINT(20) NOT NULL,
         PRIMARY KEY (source_uuid, interval_start)
     )

*Warning*:

As with other MySQL system tables, do not attempt to create or modify
this table yourself.

The 'mysql.gtid_executed' table enables a slave to use GTIDs when binary
logging is disabled on the slave, and it enables retention of the GTID
history when the binary logs have been lost.

GTIDs are stored in the 'mysql.gtid_executed' table only when
'gtid_mode' is 'ON' or 'ON_PERMISSIVE'.  The point at which GTIDs are
stored depends on whether binary logging is enabled or disabled:

   * If binary logging is disabled ('log_bin' is 'OFF'), or if
     'log_slave_updates' is disabled, the server stores the GTID
     belonging to each transaction together with the transaction in the
     table.  In addition, the table is compressed periodically at a
     user-configurable rate; see
     replication-gtids-gtid-executed-table-compression, for more
     information.  This situation can only apply on a replication slave
     where binary logging or slave update logging is disabled.  It does
     not apply on a replication master, because on a master, binary
     logging must be enabled for replication to take place.

   * If binary logging is enabled ('log_bin' is 'ON'), whenever the
     binary log is rotated or the server is shut down, the server writes
     GTIDs for all transactions that were written into the previous
     binary log into the 'mysql.gtid_executed' table.  This situation
     applies on a replication master, or a replication slave where
     binary logging is enabled.

     In the event of the server stopping unexpectedly, the set of GTIDs
     from the current binary log is not saved in the
     'mysql.gtid_executed' table.  In this case, these GTIDs are added
     to the table and to the set of GTIDs in the 'gtid_executed' system
     variable during recovery.

     When binary logging is enabled, the 'mysql.gtid_executed' table
     does not provide a complete record of the GTIDs for all executed
     transactions.  That information is provided by the global value of
     the 'gtid_executed' system variable.

The 'mysql.gtid_executed' table is reset by 'RESET MASTER'.

*mysql.gtid_executed Table Compression*

Over the course of time, the 'mysql.gtid_executed' table can become
filled with many rows referring to individual GTIDs that originate on
the same server, and whose transaction IDs make up a sequence, similar
to what is shown here:

     mysql> SELECT * FROM mysql.gtid_executed;
     +--------------------------------------+----------------+--------------+
     | source_uuid                          | interval_start | interval_end |
     |--------------------------------------+----------------+--------------|
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 37             | 37           |
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 38             | 38           |
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 39             | 39           |
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 40             | 40           |
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 41             | 41           |
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 42             | 42           |
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 43             | 43           |
     ...

Considerable space can be saved if this table is compressed periodically
by replacing each such set of rows with a single row that spans the
entire interval of transaction identifiers, like this:

     +--------------------------------------+----------------+--------------+
     | source_uuid                          | interval_start | interval_end |
     |--------------------------------------+----------------+--------------|
     | 3E11FA47-71CA-11E1-9E33-C80AA9429562 | 37             | 43           |
     ...

When GTIDs are enabled, the server performs this type of compression on
the 'mysql.gtid_executed' table periodically.  You can control the
number of transactions that are allowed to elapse before the table is
compressed, and thus the compression rate, by setting the
'gtid_executed_compression_period' system variable.  This variable's
default value is 1000; this means that, by default, compression of the
table is performed after each 1000 transactions.  Setting
'gtid_executed_compression_period' to 0 prevents the compression from
being performed at all; however, you should be prepared for a
potentially large increase in the amount of disk space that may be
required by the 'gtid_executed' table if you do this.

*Note*:

When binary logging is enabled, the value of
'gtid_executed_compression_period' is _not_ used and the
'mysql.gtid_executed' table is compressed on each binary log rotation.

Compression of the 'mysql.gtid_executed' table is performed by a
dedicated foreground thread named 'thread/sql/compress_gtid_table'.
This thread is not listed in the output of 'SHOW PROCESSLIST',
but it can be viewed as a row in the 'threads'
table, as shown here:

     mysql> SELECT * FROM performance_schema.threads WHERE NAME LIKE '%gtid%'\G
     *************************** 1. row ***************************
               THREAD_ID: 26
                    NAME: thread/sql/compress_gtid_table
                    TYPE: FOREGROUND
          PROCESSLIST_ID: 1
        PROCESSLIST_USER: NULL
        PROCESSLIST_HOST: NULL
          PROCESSLIST_DB: NULL
     PROCESSLIST_COMMAND: Daemon
        PROCESSLIST_TIME: 1509
       PROCESSLIST_STATE: Suspending
        PROCESSLIST_INFO: NULL
        PARENT_THREAD_ID: 1
                    ROLE: NULL
            INSTRUMENTED: YES
                 HISTORY: YES
         CONNECTION_TYPE: NULL
            THREAD_OS_ID: 18677

The 'thread/sql/compress_gtid_table' thread normally sleeps until
'gtid_executed_compression_period' transactions have been executed, then
wakes up to perform compression of the 'mysql.gtid_executed' table as
described previously.  It then sleeps until another
'gtid_executed_compression_period' transactions have taken place, then
wakes up to perform the compression again, repeating this loop
indefinitely.  Setting this value to 0 when binary logging is disabled
means that the thread always sleeps and never wakes up.

16.1.3.2 Setting Up Replication Using GTIDs
...........................................

This section describes a process for configuring and starting GTID-based
replication in MySQL 5.7.  This is a 'cold start' procedure that assumes
either that you are starting the replication master for the first time,
or that it is possible to stop it; for information about provisioning
replication slaves using GTIDs from a running master, see
replication-gtids-failover.  For information about changing GTID mode
on servers online, see replication-mode-change-online.

The key steps in this startup process for the simplest possible GTID
replication topology--consisting of one master and one slave--are as
follows:

  1. If replication is already running, synchronize both servers by
     making them read-only.

  2. Stop both servers.

  3. Restart both servers with GTIDs enabled and the correct options
     configured.

     The 'mysqld' options necessary to start the servers
     as described are discussed in the example that follows later in
     this section.

     *Note*:

     'server_uuid' must exist for GTIDs to function correctly.

  4. Instruct the slave to use the master as the replication data source
     and to use auto-positioning.  The SQL statements needed to
     accomplish this step are described in the example that follows
     later in this section.

  5. Take a new backup.  Binary logs containing transactions without
     GTIDs cannot be used on servers where GTIDs are enabled, so backups
     taken before this point cannot be used with your new configuration.

  6. Start the slave, then disable read-only mode again on both servers,
     so that they can accept updates.

In the following example, two servers are already running as master and
slave, using MySQL's binary log position-based replication protocol.  If
you are starting with new servers, see replication-howto-repuser
for information about adding a specific user for replication connections
and replication-howto-masterbaseconfig for information about
setting the 'server_id' variable.  The following examples show how to
store 'mysqld' startup options in server's option file,
see option-files for more information.  Alternatively you can
use startup options when running 'mysqld'.

Most of the steps that follow require the use of the MySQL 'root'
account or another MySQL user account that has the 'SUPER' privilege.
See 'mysqladmin'. 'shutdown' requires either the 'SUPER'
privilege or the 'SHUTDOWN' privilege.

Step 1: Synchronize the servers

This step is only required when working with servers which are already
replicating without using GTIDs.  For new servers proceed to Step 3.
Make the servers read-only by setting the 'read_only' system variable to
'ON' on each server by issuing the following:

     mysql> SET @@global.read_only = ON;

Wait for all ongoing transactions to commit or roll back.  Then, allow
the slave to catch up with the master.  _It is extremely important that
you make sure the slave has processed all updates before continuing_.

If you use binary logs for anything other than replication, for example
to do point in time backup and restore, wait until you do not need the
old binary logs containing transactions without GTIDs.  Ideally, wait
for the server to purge all binary logs, and wait for any existing
backup to expire.

*Important*:

It is important to understand that logs containing transactions without
GTIDs cannot be used on servers where GTIDs are enabled.  Before
proceeding, you must be sure that transactions without GTIDs do not
exist anywhere in the topology.

Step 2: Stop both servers

Stop each server using 'mysqladmin' as shown here,
where USERNAME is the user name for a MySQL user having sufficient
privileges to shut down the server:

     shell> mysqladmin -uUSERNAME -p shutdown

Then supply this user's password at the prompt.

Step 3: Start both servers with GTIDs enabled

To enable GTID-based replication, each server must be started with GTID
mode enabled by setting the 'gtid_mode' variable to 'ON', and with the
'enforce_gtid_consistency' variable enabled to ensure that only
statements which are safe for GTID-based replication are logged.  In
addition, you should start slaves with the '--skip-slave-start' option
before configuring the slave settings.  For more information on GTID
related options and variables, see replication-options-gtids.

It is not mandatory to have binary logging enabled in order to use GTIDs
due to the addition of the replication-gtids-gtid-executed-table
in MySQL 5.7.5.  This means that you can have slave servers using GTIDs
but without binary logging.  Masters _must_ always have binary logging
enabled in order to be able to replicate.  For example, to start a slave
with GTIDs enabled but without binary logging, configure these variables
in the server's option file:

     gtid_mode=ON
     enforce-gtid-consistency=true

Depending on your configuration, supply additional options to
'mysqld'.

Step 4: Configure the slave to use GTID-based auto-positioning

Tell the slave to use the master with GTID based transactions as the
replication data source, and to use GTID-based auto-positioning rather
than file-based positioning.  Issue a 'CHANGE MASTER TO'
statement on the slave, including the
'MASTER_AUTO_POSITION' option in the statement to tell the slave that
the master's transactions are identified by GTIDs.

You may also need to supply appropriate values for the master's host
name and port number as well as the user name and password for a
replication user account which can be used by the slave to connect to
the master; if these have already been set prior to Step 1 and no
further changes need to be made, the corresponding options can safely be
omitted from the statement shown here.

     mysql> CHANGE MASTER TO
          >     MASTER_HOST = HOST,
          >     MASTER_PORT = PORT,
          >     MASTER_USER = USER,
          >     MASTER_PASSWORD = PASSWORD,
          >     MASTER_AUTO_POSITION = 1;

Neither the 'MASTER_LOG_FILE' option nor the 'MASTER_LOG_POS' option may
be used with 'MASTER_AUTO_POSITION' set equal to 1.  Attempting to do so
causes the 'CHANGE MASTER TO' statement to fail
with an error.

Step 5: Take a new backup

Existing backups that were made before you enabled GTIDs can no longer
be used on these servers now that you have enabled GTIDs.  Take a new
backup at this point, so that you are not left without a usable backup.

For instance, you can execute 'FLUSH LOGS' on the server where you are
taking backups.  Then either explicitly take a backup or wait for the
next iteration of any periodic backup routine you may have set up.

Step 6: Start the slave and disable read-only mode

Start the slave like this:

     mysql> START SLAVE;

The following step is only necessary if you configured a server to be
read-only in Step 1.  To allow the server to begin accepting updates
again, issue the following statement:

     mysql> SET @@global.read_only = OFF;

GTID-based replication should now be running, and you can begin (or
resume) activity on the master as before.  See
replication-gtids-failover, discusses creation of new slaves when
using GTIDs.

16.1.3.3 Using GTIDs for Failover and Scaleout
..............................................

There are a number of techniques when using MySQL Replication with
Global Transaction Identifiers (GTIDs) for provisioning a new slave
which can then be used for scaleout, being promoted to master as
necessary for failover.  This section describes the following
techniques:

   * replication-gtids-failover-replicate

   * replication-gtids-failover-copy

   * replication-gtids-failover-empty

   * replication-gtids-failover-gtid-purged

   * replication-gtids-restoring-mysqlbinlog

Global transaction identifiers were added to MySQL Replication for the
purpose of simplifying in general management of the replication data
flow and of failover activities in particular.  Each identifier uniquely
identifies a set of binary log events that together make up a
transaction.  GTIDs play a key role in applying changes to the database:
the server automatically skips any transaction having an identifier
which the server recognizes as one that it has processed before.  This
behavior is critical for automatic replication positioning and correct
failover.

The mapping between identifiers and sets of events comprising a given
transaction is captured in the binary log.  This poses some challenges
when provisioning a new server with data from another existing server.
To reproduce the identifier set on the new server, it is necessary to
copy the identifiers from the old server to the new one, and to preserve
the relationship between the identifiers and the actual events.  This is
neccessary for restoring a slave that is immediately available as a
candidate to become a new master on failover or switchover.

Simple replication

The easiest way to reproduce all identifiers and transactions on a new
server is to make the new server into the slave of a master that has the
entire execution history, and enable global transaction identifiers on
both servers.  See replication-gtids-howto, for more
information.

Once replication is started, the new server copies the entire binary log
from the master and thus obtains all information about all GTIDs.

This method is simple and effective, but requires the slave to read the
binary log from the master; it can sometimes take a comparatively long
time for the new slave to catch up with the master, so this method is
not suitable for fast failover or restoring from backup.  This section
explains how to avoid fetching all of the execution history from the
master by copying binary log files to the new server.

Copying data and transactions to the slave

Executing the entire transaction history can be time-consuming when the
source server has processed a large number of transactions previously,
and this can represent a major bottleneck when setting up a new
replication slave.  To eliminate this requirement, a snapshot of the
data set, the binary logs and the global transaction information the
source server contains can be imported to the new slave.  The source
server can be either the master or the slave, you must ensure that the
source has processed all required transactions before copying the data.

There are several variants of this method, the difference being in the
manner in which data dumps and transactions from binary logs are
transfered to the slave, as outlined here:

Data Set                             Transaction History

   * Use the 'mysql'.      * Import the binary log from
     client to import a dump file         the source server to the new
     created with slave using *note 'mysqldump'.
     On          'mysqlbinlog': mysqlbinlog,
     the source server use the            with the
     '--master-data' option to            '--read-from-remote-server'
     include binary logging               and
     information and                      '--read-from-remote-master'
     '--set-gtid-purged' to 'AUTO'        options.
     (the default) or 'ON', to
     include information about          * Copy the source's binary log
     executed transactions in the         files to the slave.  You can
     dump.                                make copies from the slave
                                          using 'mysqlbinlog',
   copy         mysqlbinlog.
     the contents of the sources's        '--read-from-remote-server'
     data directory to the new            '--raw'.  These can be read
     slave's data directory, then         in to the slave in either of
     restart the slave.  The slave        the following ways:
     must be configured for
     GTID-based replication, in              * Update the slave's
     other words 'gtid_mode=ON'.               'binlog.index' file to
                                               point to the copied log
                                               files.  Then execute a
                                               'CHANGE MASTER TO'.
                                               statement in the
                                               'mysql' client
                                               to point to the first
                                               log file, and
                                               'START SLAVE'
                                        to read
                                               them.

                                             * Use 'mysqlbinlog'.
                                        '>' 'FILE'
                                               (without the '--raw'
                                               option) to export the
                                               binary log files to SQL
                                               files that can be
                                               processed by the
                                               'mysql' client.

See also mysqlbinlog-backup.

This method has the advantage that a new server is available almost
immediately; only those transactions that were committed while the
snapshot or dump file was being replayed still need to be obtained from
the existing master.  This means that the slave's availability is not
instantanteous--but only a relatively short amount of time should be
required for the slave to catch up with these few remaining
transactions.

Copying over binary logs to the target server in advance is usually
faster than reading the entire transaction execution history from the
master in real time.  However, it may not always be feasible to move
these files to the target when required, due to size or other
considerations.  The two remaining methods for provisioning a new slave
discussed in this section use other means to transfer information about
transactions to the new slave.

Injecting empty transactions

The master's global 'gtid_executed' variable contains the set of all
transactions executed on the master.  Rather than copy the binary logs
when taking a snapshot to provision a new server, you can instead note
the content of 'gtid_executed' on the server from which the snapshot was
taken.  Before adding the new server to the replication chain, simply
commit an empty transaction on the new server for each transaction
identifier contained in the master's 'gtid_executed', like this:

     SET GTID_NEXT='aaa-bbb-ccc-ddd:N';

     BEGIN;
     COMMIT;

     SET GTID_NEXT='AUTOMATIC';

Once all transaction identifiers have been reinstated in this way using
empty transactions, you must flush and purge the slave's binary logs, as
shown here, where N is the nonzero suffix of the current binary log file
name:

     FLUSH LOGS;
     PURGE BINARY LOGS TO 'master-bin.00000N';

You should do this to prevent this server from flooding the replication
stream with false transactions in the event that it is later promoted to
master.  (The 'FLUSH LOGS' statement forces the creation of a new binary
log file; see 'PURGE BINARY LOGS' purges the empty
transactions, but retains their identifiers.)

This method creates a server that is essentially a snapshot, but in time
is able to become a master as its binary log history converges with that
of the replication stream (that is, as it catches up with the master or
masters).  This outcome is similar in effect to that obtained using the
remaining provisioning method, which we discuss in the next few
paragraphs.

Excluding transactions with gtid_purged

The master's global 'gtid_purged' variable contains the set of all
transactions that have been purged from the master's binary log.  As
with the method discussed previously (see
replication-gtids-failover-empty), you can record the value of
'gtid_executed' on the server from which the snapshot was taken (in
place of copying the binary logs to the new server).  Unlike the
previous method, there is no need to commit empty transactions (or to
issue 'PURGE BINARY LOGS'); instead, you can
set 'gtid_purged' on the slave directly, based on the value of
'gtid_executed' on the server from which the backup or snapshot was
taken.

As with the method using empty transactions, this method creates a
server that is functionally a snapshot, but in time is able to become a
master as its binary log history converges with that of the replication
master or group.

Restoring GTID mode slaves

When restoring a slave in a GTID based replication setup that has
encountered an error, injecting an empty transaction may not solve the
problem because an event does not have a GTID.

Use 'mysqlbinlog' to find the next transaction,
which is probably the first transaction in the next log file after the
event.  Copy everything up to the 'COMMIT' for that
transaction, being sure to include the 'SET @@SESSION.GTID_NEXT'.  Even
if you are not using row-based replication, you can still run binary log
row events in the command line client.

Stop the slave and run the transaction you copied.  The
'mysqlbinlog' output sets the delimiter to '/*!*/;', so
set it back:

     mysql> DELIMITER ;

Restart replication from the correct position automatically:

     mysql> SET GTID_NEXT=automatic;
     mysql> RESET SLAVE;
     mysql> START SLAVE;

16.1.3.4 Restrictions on Replication with GTIDs
...............................................

Because GTID-based replication is dependent on transactions, some
features otherwise available in MySQL are not supported when using it.
This section provides information about restrictions on and limitations
of replication with GTIDs.

Updates involving nontransactional storage engines

When using GTIDs, updates to tables using nontransactional storage
engines such as 'MyISAM' cannot be made in
the same statement or transaction as updates to tables using
transactional storage engines such as 'InnoDB'.

This restriction is due to the fact that updates to tables that use a
nontransactional storage engine mixed with updates to tables that use a
transactional storage engine within the same transaction can result in
multiple GTIDs being assigned to the same transaction.

Such problems can also occur when the master and the slave use different
storage engines for their respective versions of the same table, where
one storage engine is transactional and the other is not.

In any of the cases just mentioned, the one-to-one correspondence
between transactions and GTIDs is broken, with the result that
GTID-based replication cannot function correctly.

CREATE TABLE ...  SELECT statements

'CREATE TABLE ... SELECT' is not safe for
statement-based replication.  When using row-based replication, this
statement is actually logged as two separate events--one for the
creation of the table, and another for the insertion of rows from the
source table into the new table just created.  When this statement is
executed within a transaction, it is possible in some cases for these
two events to receive the same transaction identifier, which means that
the transaction containing the inserts is skipped by the slave.
Therefore, 'CREATE TABLE ... SELECT' is not supported when using
GTID-based replication.

Temporary tables

'CREATE TEMPORARY TABLE' and 'DROP TEMPORARY TABLE'
statements are not supported inside transactions
when using GTIDs (that is, when the server was started with the
'--enforce-gtid-consistency' option).  It is possible to use these
statements with GTIDs enabled, but only outside of any transaction, and
only with 'autocommit=1'.

Preventing execution of unsupported statements

To prevent execution of statements that would cause GTID-based
replication to fail, all servers must be started with the
'--enforce-gtid-consistency' option when enabling GTIDs.  This causes
statements of any of the types discussed previously in this section to
fail with an error.

Note that '--enforce-gtid-consistency' only takes effect if binary
logging takes place for a statement.  If binary logging is disabled on
the server, or if statements are not written to the binary log because
they are removed by a filter, GTID consistency is not checked or
enforced for the statements that are not logged.

For information about other required startup options when enabling
GTIDs, see replication-gtids-howto.

'sql_slave_skip_counter' is not supported when using GTIDs.  If you need
to skip transactions, use the value of the master's 'gtid_executed'
variable instead; see replication-gtids-failover-empty, for more
information.

GTID mode and mysqldump

It is possible to import a dump made using 'mysqldump'.
into a MySQL Server running with GTID mode enabled, provided that there
are no GTIDs in the target server's binary log.

GTID mode and mysql_upgrade

When the server is running with global transaction identifiers (GTIDs)
enabled ('gtid_mode=ON'), do not enable binary logging by
'mysql_upgrade'. (the '--write-binlog' option).

16.1.4 MySQL Multi-Source Replication
-------------------------------------

This section describes MySQL Multi-Source Replication, which enables you
to replicate from multiple immediate masters in parallel.  This section
describes multi-source replication, and how to configure, monitor and
troubleshoot it.

16.1.4.1 MySQL Multi-Source Replication Overview
................................................

MySQL Multi-Source Replication enables a replication slave to receive
transactions from multiple sources simultaneously.  Multi-source
replication can be used to back up multiple servers to a single server,
to merge table shards, and consolidate data from multiple servers to a
single server.  Multi-source replication does not implement any conflict
detection or resolution when applying the transactions, and those tasks
are left to the application if required.  In a multi-source replication
topology, a slave creates a replication channel for each master that it
should receive transactions from.  See replication-channels.
The following sections describe how to set up multi-source replication.

16.1.4.2 Multi-Source Replication Tutorials
...........................................

This section provides tutorials on how to configure masters and slaves
for multi-source replication, and how to start, stop and reset
multi-source slaves.

16.1.4.3 Configuring Multi-Source Replication
.............................................

This section explains how to configure a multi-source replication
topology, and provides details about configuring masters and slaves.
Such a topology requires at least two masters and one slave configured.

Masters in a multi-source replication topology can be configured to use
either global transaction identifier (GTID) based replication, or binary
log position-based replication.  See replication-gtids-howto for
how to configure a master using GTID based replication.  See
replication-howto-masterbaseconfig for how to configure a master using
file position based replication.

Slaves in a multi-source replication topology require 'TABLE' based
repositories.  Multi-source replication is not compatible with 'FILE'
based repositories.  The type of repository being used by
'mysqld' can be configured either at startup, or dynamically.

To configure the type of repository used by a replication slave at
startup, start 'mysqld' with the following options:

     --master-info-repository=TABLE --relay-log-info-repository=TABLE

To modify an existing replication slave that is using a 'FILE'
repository to use 'TABLE' repositories, convert the existing replication
repositories dynamically by running the following commands:

     STOP SLAVE;
     SET GLOBAL master_info_repository = 'TABLE';
     SET GLOBAL relay_log_info_repository = 'TABLE';

16.1.4.4 Adding a GTID Based Master to a Multi-Source Replication Slave
.......................................................................

This section assumes you have enabled GTID based transactions on the
master using 'gtid_mode=ON', enabled a replication user, and ensured
that the slave is using 'TABLE' based replication repositories.  Use the
'CHANGE MASTER TO' statement to add a new
master to a channel by using a 'FOR CHANNEL CHANNEL' clause.  For more
information on replication channels, see replication-channels

For example, to add a new master with the host name MASTER1 using port
3451 to a channel called MASTER-1:

     CHANGE MASTER TO MASTER_HOST='master1', MASTER_USER='rpl', MASTER_PORT=3451, MASTER_PASSWORD='', \
     MASTER_AUTO_POSITION = 1 FOR CHANNEL 'master-1';

Multi-source replication is compatible with auto-positioning.  See
change-master-to for more information.

Repeat this process for each extra master that you want to add to a
channel, changing the host name, port and channel as appropriate.

16.1.4.5 Adding a Binary Log Based Master to a Multi-Source Replication Slave
.............................................................................

This section assumes you have enabled binary logging on the master using
'--log-bin', enabled a replication user, noted the current binary log
position, and ensured that the slave is using 'TABLE' based replication
repositories.  You need to know the current 'MASTER_LOG_FILE' and
'MASTER_LOG_POSITION'.  Use the 'CHANGE MASTER TO'
statement to add a new master to a channel by
specifying a 'FOR CHANNEL CHANNEL' clause.  For example, to add a new
master with the host name MASTER1 using port 3451 to a channel called
MASTER-1:

     CHANGE MASTER TO MASTER_HOST='master1', MASTER_USER='rpl', MASTER_PORT=3451, MASTER_PASSWORD='' \
     MASTER_LOG_FILE='master1-bin.000006', MASTER_LOG_POS=628 FOR CHANNEL 'master-1';

Repeat this process for each extra master that you want to add to a
channel, changing the host name, port and channel as appropriate.

16.1.4.6 Starting Multi-Source Replication Slaves
.................................................

Once you have added all of the channels you want to use as replication
masters, use a 'START SLAVE THREAD_TYPES' statement to start
replication.  When you have enabled multiple channels on a slave, you
can choose to either start all channels, or select a specific channel to
start.

   * To start all currently configured replication channels:

          START SLAVE THREAD_TYPES;

   * To start only a named channel, use a 'FOR CHANNEL CHANNEL' clause:

          START SLAVE THREAD_TYPES FOR CHANNEL CHANNEL;

Use the THREAD_TYPES option to choose specific threads you want the
above statements to start on the slave.  See start-slave for
more information.

16.1.4.7 Stopping Multi-Source Replication Slaves
.................................................

The 'STOP SLAVE' statement can be used to stop a multi-source
replication slave.  By default, if you use the 'STOP SLAVE' statement on
a multi-source replication slave all channels are stopped.  Optionally,
use the 'FOR CHANNEL CHANNEL' clause to stop only a specific channel.

   * To stop all currently configured replication channels:

          STOP SLAVE THREAD_TYPES;

   * To stop only a named channel, use a 'FOR CHANNEL CHANNEL' clause:

          STOP SLAVE THREAD_TYPES FOR CHANNEL CHANNEL;

Use the THREAD_TYPES option to choose specific threads you want the
above statements to stop on the slave.  See stop-slave for more
information.

16.1.4.8 Resetting Multi-Source Replication Slaves
..................................................

The 'RESET SLAVE' statement can be used to reset a multi-source
replication slave.  By default, if you use the 'RESET SLAVE' statement
on a multi-source replication slave all channels are reset.  Optionally,
use the 'FOR CHANNEL CHANNEL' clause to reset only a specific channel.

   * To reset all currently configured replication channels:

          RESET SLAVE;

   * To reset only a named channel, use a 'FOR CHANNEL CHANNEL' clause:

          RESET SLAVE FOR CHANNEL CHANNEL;

See reset-slave for more information.

16.1.4.9 Multi-Source Replication Monitoring
............................................

To monitor the status of replication channels the following options
exist:

   * Using the replication Performance Schema tables.  The first column
     of these tables is 'Channel_Name'.  This enables you to write
     complex queries based on 'Channel_Name' as a key.  See
     performance-schema-replication-tables.

   * Using 'SHOW SLAVE STATUS FOR CHANNEL CHANNEL'.  By default, if the
     'FOR CHANNEL CHANNEL' clause is not used, this statement shows the
     slave status for all channels with one row per channel.  The
     identifier 'Channel_name' is added as a column in the result set.
     If a 'FOR CHANNEL CHANNEL' clause is provided, the results show the
     status of only the named replication channel.

*Note*:

The 'SHOW VARIABLES' statement does not work with
multiple replication channels.  The information that was available
through these variables has been migrated to the replication performance
tables.  Using a 'SHOW VARIABLES' statement in a
topology with multiple channels shows the status of only the default
channel.

16.1.4.10 Monitoring Channels Using Performance Schema Tables
.............................................................

This section explains how to use the replication Performance Schema
tables to monitor channels.  You can choose to monitor all channels, or
a subset of the existing channels.

To monitor the connection status of all channels:

     mysql> SELECT * FROM replication_connection_status\G;
     *************************** 1. row ***************************
     CHANNEL_NAME: master1
     GROUP_NAME:
     SOURCE_UUID: 046e41f8-a223-11e4-a975-0811960cc264
     THREAD_ID: 24
     SERVICE_STATE: ON
     COUNT_RECEIVED_HEARTBEATS: 0
     LAST_HEARTBEAT_TIMESTAMP: 0000-00-00 00:00:00
     RECEIVED_TRANSACTION_SET: 046e41f8-a223-11e4-a975-0811960cc264:4-37
     LAST_ERROR_NUMBER: 0
     LAST_ERROR_MESSAGE:
     LAST_ERROR_TIMESTAMP: 0000-00-00 00:00:00
     *************************** 2. row ***************************
     CHANNEL_NAME: master2
     GROUP_NAME:
     SOURCE_UUID: 7475e474-a223-11e4-a978-0811960cc264
     THREAD_ID: 26
     SERVICE_STATE: ON
     COUNT_RECEIVED_HEARTBEATS: 0
     LAST_HEARTBEAT_TIMESTAMP: 0000-00-00 00:00:00
     RECEIVED_TRANSACTION_SET: 7475e474-a223-11e4-a978-0811960cc264:4-6
     LAST_ERROR_NUMBER: 0
     LAST_ERROR_MESSAGE:
     LAST_ERROR_TIMESTAMP: 0000-00-00 00:00:00
     2 rows in set (0.00 sec)

In the above output there are two channels enabled, and as shown by the
'CHANNEL_NAME' field they are called 'master1' and 'master2'.

The addition of the 'CHANNEL_NAME' field enables you to query the
Performance Schema tables for a specific channel.  To monitor the
connection status of a named channel, use a 'WHERE CHANNEL_NAME=CHANNEL'
clause:

     mysql> SELECT * FROM replication_connection_status WHERE CHANNEL_NAME='master1'\G
     *************************** 1. row ***************************
     CHANNEL_NAME: master1
     GROUP_NAME:
     SOURCE_UUID: 046e41f8-a223-11e4-a975-0811960cc264
     THREAD_ID: 24
     SERVICE_STATE: ON
     COUNT_RECEIVED_HEARTBEATS: 0
     LAST_HEARTBEAT_TIMESTAMP: 0000-00-00 00:00:00
     RECEIVED_TRANSACTION_SET: 046e41f8-a223-11e4-a975-0811960cc264:4-37
     LAST_ERROR_NUMBER: 0
     LAST_ERROR_MESSAGE:
     LAST_ERROR_TIMESTAMP: 0000-00-00 00:00:00
     1 row in set (0.00 sec)

Similarly, the 'WHERE CHANNEL_NAME=CHANNEL' clause can be used to
monitor the other replication Performance Schema tables for a specific
channel.  For more information, see
performance-schema-replication-tables.

16.1.4.11 Multi-Source Replication Error Messages
.................................................

Error codes and messages provide information about errors encountered in
a multi-source replication topology.  These error codes and messages are
only emitted when multi-source replication is enabled, and provide
information related to the channel which generated the error.  For
example:

'Slave is already running' and 'Slave is already stopped ' have been
replaced with 'Replication thread(s) for channel CHANNEL_NAME are
already running' and 'Replication threads(s) for channel CHANNEL_NAME
are already stopped' respectively.

The server log messages have also been changed to indicate which channel
the log messages relate to.  This makes debugging and tracing easier.

16.1.5 Changing Replication Modes on Online Servers
---------------------------------------------------

This section describes how to change the mode of replication being used
without having to take the server offline.

16.1.5.1 Replication Mode Concepts
..................................

To be able to safely configure the replication mode of an online server
it is important to understand some key concepts of replication.  This
section explains these concepts and is essential reading before
attempting to modify the replication mode of an online server.

The modes of replication available in MySQL rely on different techniques
for identifying transactions which are logged.  The types of
transactions used by replication are as follows:

   * GTID transactions are identified by a global transaction identifier
     (GTID) in the form 'UUID:NUMBER'.  Every GTID transaction in a log
     is always preceded by a 'Gtid_log_event'.  GTID transactions can be
     addressed using either the GTID or using the file name and
     position.

   * Anonymous transactions do not have a GTID assigned, and MySQL
     ensures that every anonymous transaction in a log is preceded by an
     'Anonymous_gtid_log_event'.  In previous versions, anonymous
     transactions were not preceded by any particular event.  Anonymous
     transactions can only be addressed using file name and position.

When using GTIDs you can take advantage of auto-positioning and
automatic fail-over, as well as use 'WAIT_FOR_EXECUTED_GTID_SET()',
'session_track_gtids', and monitor replicated transactions using
Performance Schema tables.  With GTIDs enabled you cannot use
'sql_slave_skip_counter', instead use empty transactions.

Transactions in a relay log that was received from a master running a
previous version of MySQL may not be preceded by any particular event at
all, but after being replayed and logged in the slave's binary log, they
are preceded with an 'Anonymous_gtid_log_event'.

The ability to configure the replication mode online means that the
'gtid_mode' and 'enforce_gtid_consistency' variables are now both
dynamic and can be set from a top-level statement by an account that has
the 'SUPER' privilege.  In previous versions, both of these variables
could only be configured using the appropriate option at server start,
meaning that changes to the replication mode required a server restart.
In all versions 'gtid_mode' could be set to 'ON' or 'OFF', which
corresponded to whether GTIDs were used to identify transactions or not.
When 'gtid_mode=ON' it is not possible to replicate anonymous
transactions, and when 'gtid_mode=OFF' only anonymous transactions can
be replicated.  As of MySQL 5.7.6, the 'gtid_mode' variable has two
additional states, 'OFF_PERMISSIVE' and 'ON_PERMISSIVE'.  When
'gtid_mode=OFF_PERMISSIVE' then _new_ transactions are anonymous while
permitting replicated transactions to be either GTID or anonymous
transactions.  When 'gtid_mode=ON_PERMISSIVE' then _new_ transactions
use GTIDs while permitting replicated transactions to be either GTID or
anonymous transactions.  This means it is possible to have a replication
topology that has servers using both anonymous and GTID transactions.
For example a master with 'gtid_mode=ON' could be replicating to a slave
with 'gtid_mode=ON_PERMISSIVE'.  The valid values for 'gtid_mode' are as
follows and in this order:

   * 'OFF'

   * 'OFF_PERMISSIVE'

   * 'ON_PERMISSIVE'

   * 'ON'

It is important to note that the state of 'gtid_mode' can only be
changed by one step at a time based on the above order.  For example, if
'gtid_mode' is currently set to 'OFF_PERMISSIVE', it is possible to
change to 'OFF' or 'ON_PERMISSIVE' but not to 'ON'.  This is to ensure
that the process of changing from anonymous transactions to GTID
transactions online is correctly handled by the server.  When you switch
between 'gtid_mode=ON' and 'gtid_mode=OFF', the GTID state (in other
words the value of 'gtid_executed') is persistent.  This ensures that
the GTID set that has been applied by the server is always retained,
regardless of changes between types of 'gtid_mode'.

As part of the changes introduced by MySQL 5.7.6, the fields related to
GTIDs have been modified so that they display the correct information
regardless of the currently selected 'gtid_mode'.  This means that
fields which display GTID sets, such as 'gtid_executed', 'gtid_purged',
'RECEIVED_TRANSACTION_SET' in the 'replication_connection_status'.
Performance Schema table, and the
GTID related results of 'SHOW SLAVE STATUS',
now return the empty string when there are no GTIDs present.  Fields
that display a single GTID, such as 'CURRENT_TRANSACTION' in the
'replication_applier_status_by_worker '.
Performance Schema table,
now display 'ANONYMOUS' when GTID transactions are not being used.

Replication from a master using 'gtid_mode=ON' provides the ability to
use auto-positioning, configured using the 'CHANGE MASTER TO
MASTER_AUTO_POSITION = 1;' statement.  The replication topology being
used impacts on whether it is possible to enable auto-positioning or
not, as this feature relies on GTIDs and is not compatible with
anonymous transactions.  An error is generated if auto-positioning is
enabled and an anonymous transaction is encountered.  It is strongly
recommended to ensure there are no anonymous transactions remaining in
the topology before enabling auto-positioning, see
replication-mode-change-online-enable-gtids.  The valid combinations
of 'gtid_mode' and auto-positioning on master and slave are shown in the
following table, where the master's 'gtid_mode' is shown on the
horizontal and the slave's 'gtid_mode' is on the vertical:

*Valid Combinations of Master and Slave gtid_mode*

Master/Slave   '>OFF'  '>OFF_PERMISSIVE''>ON_PERMISSIVE''>ON'
'gtid_mode'

'>OFF'         Y       Y              N       N

'>OFF_PERMISSIVE'Y     Y              Y       Y*

'>ON_PERMISSIVE'Y      Y              Y       Y*

'>ON'          N       N              Y       Y*

In the above table, the entries are:

   * 'Y': the 'gtid_mode' of master and slave is compatible

   * 'N': the 'gtid_mode' of master and slave is not compatible

   * '*': auto-positioning can be used

The currently selected 'gtid_mode' also impacts on the 'gtid_next'
variable.  The following table shows the behavior of the server for the
different values of 'gtid_mode' and 'gtid_next'.

*Valid Combinations of gtid_mode and gtid_next*

'gtid_next'    AUTOMATICAUTOMATIC     ANONYMOUSUUID:NUMBER

               binary  binary log
               log     off
               on

                                      ANONYMOUS
'>OFF'         ANONYMOUSANONYMOUS             Error

'>OFF_PERMISSIVE'ANONYMOUSANONYMOUS   ANONYMOUSUUID:NUMBER

'>ON_PERMISSIVE'New    ANONYMOUS      ANONYMOUSUUID:NUMBER
               GTID

'>ON'          New     ANONYMOUS      Error   UUID:NUMBER
               GTID

In the above table, the entries are:

   * 'ANONYMOUS': generate an anonymous transaction.

   * 'Error': generate an error and fail to execute 'SET GTID_NEXT'.

   * 'UUID:NUMBER': generate a GTID with the specified UUID:NUMBER.

   * 'New GTID': generate a GTID with an automatically generated number.

When the binary log is off and 'gtid_next' is set to 'AUTOMATIC', then
no GTID is generated.  This is consistent with the behavior of previous
versions.

16.1.5.2 Enabling GTID Transactions Online
..........................................

This section describes how to enable GTID transactions, and optionally
auto-positioning, on servers that are already online and using anonymous
transactions.  This procedure does not require taking the server offline
and is suited to use in production.  However, if you have the
possibility to take the servers offline when enabling GTID transactions
that process is easier.

Before you start, ensure that the servers meet the following
pre-conditions:

   * _All_ servers in your topology must use MySQL 5.7.6 or later.  You
     cannot enable GTID transactions online on any single server unless
     _all_ servers which are in the topology are using this version.

   * All servers have 'gtid_mode' set to the default value 'OFF'.

The following procedure can be paused at any time and later resumed
where it was, or reversed by jumping to the corresponding step of
replication-mode-change-online-disable-gtids, the online procedure to
disable GTIDs.  This makes the procedure fault-tolerant because any
unrelated issues that may appear in the middle of the procedure can be
handled as usual, and then the procedure continued where it was left
off.

*Note*:

It is crucial that you complete every step before continuing to the next
step.

To enable GTID transactions:

  1. On each server, execute:

          SET @@GLOBAL.ENFORCE_GTID_CONSISTENCY = WARN;

     Let the server run for a while with your normal workload and
     monitor the logs.  If this step causes any warnings in the log,
     adjust your application so that it only uses GTID-compatible
     features and does not generate any warnings.

     *Important*:

     This is the first important step.  You must ensure that no warnings
     are being generated in the error logs before going to the next
     step.

  2. On each server, execute:

          SET @@GLOBAL.ENFORCE_GTID_CONSISTENCY = ON;

  3. On each server, execute:

          SET @@GLOBAL.GTID_MODE = OFF_PERMISSIVE;

     It does not matter which server executes this statement first, but
     it is important that all servers complete this step before any
     server begins the next step.

  4. On each server, execute:

          SET @@GLOBAL.GTID_MODE = ON_PERMISSIVE;

     It does not matter which server executes this statement first.

  5. On each server, wait until the status variable
     'ONGOING_ANONYMOUS_TRANSACTION_COUNT' is zero.  This can be checked
     using:

          SHOW STATUS LIKE 'ONGOING_ANONYMOUS_TRANSACTION_COUNT';

     *Note*:

     On a replication slave, it is theoretically possible that this
     shows zero and then nonzero again.  This is not a problem, it
     suffices that it shows zero once.

  6. Wait for all transactions generated up to step 5 to replicate to
     all servers.  You can do this without stopping updates: the only
     important thing is that all anonymous transactions get replicated.

     See replication-mode-change-online-verify-transactions for
     one method of checking that all anonymous transactions have
     replicated to all servers.

  7. If you use binary logs for anything other than replication, for
     example point in time backup and restore, wait until you do not
     need the old binary logs having transactions without GTIDs.

     For instance, after step 6 has completed, you can execute 'FLUSH
     LOGS' on the server where you are taking backups.  Then either
     explicitly take a backup or wait for the next iteration of any
     periodic backup routine you may have set up.

     Ideally, wait for the server to purge all binary logs that existed
     when step 6 was completed.  Also wait for any backup taken before
     step 6 to expire.

     *Important*:

     This is the second important point.  It is vital to understand that
     binary logs containing anonymous transactions, without GTIDs cannot
     be used after the next step.  After this step, you must be sure
     that transactions without GTIDs do not exist anywhere in the
     topology.

  8. On each server, execute:

          SET @@GLOBAL.GTID_MODE = ON;

  9. On each server, add 'gtid-mode=ON' to 'my.cnf'.

     You are now guaranteed that all transactions have a GTID (except
     transactions generated in step 5 or earlier, which have already
     been processed).  To start using the GTID protocol so that you can
     later perform automatic fail-over, execute the following on each
     slave.  Optionally, if you use multi-source replication, do this
     for each channel and include the 'FOR CHANNEL CHANNEL' clause:

          STOP SLAVE [FOR CHANNEL 'channel'];
          CHANGE MASTER TO MASTER_AUTO_POSITION = 1 [FOR CHANNEL 'channel'];
          START SLAVE [FOR CHANNEL 'channel'];

16.1.5.3 Disabling GTID Transactions Online
...........................................

This section describes how to disable GTID transactions on servers that
are already online.  This procedure does not require taking the server
offline and is suited to use in production.  However, if you have the
possibility to take the servers offline when disabling GTIDs mode that
process is easier.

The process is similar to enabling GTID transactions while the server is
online, but reversing the steps.  The only thing that differs is the
point at which you wait for logged transactions to replicate.

Before you start, ensure that the servers meet the following
pre-conditions:

   * _All_ servers in your topology must use MySQL 5.7.6 or later.  You
     cannot disable GTID transactions online on any single server unless
     _all_ servers which are in the topology are using this version.

   * All servers have 'gtid_mode' set to 'ON'.

  1. Execute the following on each slave, and if you using multi-source
     replication, do it for each channel and include the 'FOR CHANNEL'
     channel clause:

          STOP SLAVE [FOR CHANNEL 'channel'];
          CHANGE MASTER TO MASTER_AUTO_POSITION = 0, MASTER_LOG_FILE = file, \
          MASTER_LOG_POS = position [FOR CHANNEL 'channel'];
          START SLAVE [FOR CHANNEL 'channel'];

  2. On each server, execute:

          SET @@GLOBAL.GTID_MODE = ON_PERMISSIVE;

  3. On each server, execute:

          SET @@GLOBAL.GTID_MODE = OFF_PERMISSIVE;

  4. On each server, wait until the variable @@GLOBAL.GTID_OWNED is
     equal to the empty string.  This can be checked using:

          SELECT @@GLOBAL.GTID_OWNED;

     On a replication slave, it is theoretically possible that this is
     empty and then nonempty again.  This is not a problem, it suffices
     that it is empty once.

  5. Wait for all transactions that currently exist in any binary log to
     replicate to all slaves.  See
     replication-mode-change-online-verify-transactions for one method
     of checking that all anonymous transactions have replicated to all
     servers.

  6. If you use binary logs for anything else than replication, for
     example to do point in time backup or restore: wait until you do
     not need the old binary logs having GTID transactions.

     For instance, after step 5 has completed, you can execute 'FLUSH
     LOGS' on the server where you are taking the backup.  Then either
     explicitly take a backup or wait for the next iteration of any
     periodic backup routine you may have set up.

     Ideally, wait for the server to purge all binary logs that existed
     when step 5 was completed.  Also wait for any backup taken before
     step 5 to expire.

     *Important*:

     This is the one important point during this procedure.  It is
     important to understand that logs containing GTID transactions
     cannot be used after the next step.  Before proceeding you must be
     sure that GTID transactions do not exist anywhere in the topology.

  7. On each server, execute:

          SET @@GLOBAL.GTID_MODE = OFF;

  8. On each server, set 'gtid-mode=OFF' in 'my.cnf'.

     If you want to set 'enforce_gtid_consistency=OFF', you can do so
     now.  After setting it, you should add
     'enforce_gtid_consistency=OFF' to your configuration file.

If you want to downgrade to an earlier version of MySQL, you can do so
now, using the normal downgrade procedure.

16.1.5.4 Verifying Replication of Anonymous Transactions
........................................................

This section explains how to monitor a replication topology and verify
that all anonymous transactions have been replicated.  This is helpful
when changing the replication mode online as you can verify that it is
safe to change to GTID transactions.

There are several possible ways to wait for transactions to replicate:

The simplest method, which works regardless of your topology but relies
on timing is as follows: if you are sure that the slave never lags more
than N seconds, just wait for a bit more than N seconds.  Or wait for a
day, or whatever time period you consider safe for your deployment.

A safer method in the sense that it does not depend on timing: if you
only have a master with one or more slaves, do the following:

  1. On the master, execute:

          SHOW MASTER STATUS;

     Note down the values in the 'File' and 'Position' column.

  2. On every slave, use the file and position information from the
     master to execute:

          SELECT MASTER_POS_WAIT(file, position);

If you have a master and multiple levels of slaves, or in other words
you have slaves of slaves, repeat step 2 on each level, starting from
the master, then all the direct slaves, then all the slaves of slaves,
and so on.

If you use a circular replication topology where multiple servers may
have write clients, perform step 2 for each master-slave connection,
until you have completed the full circle.  Repeat the whole process so
that you do the full circle _twice_.

For example, suppose you have three servers A, B, and C, replicating in
a circle so that A -> B -> C -> A. The procedure is then:

   * Do step 1 on A and step 2 on B.

   * Do step 1 on B and step 2 on C.

   * Do step 1 on C and step 2 on A.

   * Do step 1 on A and step 2 on B.

   * Do step 1 on B and step 2 on C.

   * Do step 1 on C and step 2 on A.

16.1.6 Replication and Binary Logging Options and Variables
-----------------------------------------------------------

The following sections contain information about 'mysqld'.
options and server variables that are used in replication and for
controlling the binary log.  Options and variables for use on
replication masters and replication slaves are covered separately, as
are options and variables relating to binary logging and global
transaction identifiers (GTIDs).  A set of quick-reference tables
providing basic information about these options and variables is also
included.

Of particular importance is the '--server-id' option.

Property                             Value

*Command-Line Format*                '--server-id=#'

*System Variable*                    'server_id'

*Scope*                              Global

*Dynamic*                            Yes

*Type*                               integer

*Default Value*                      '0'

*Minimum Value*                      '0'

*Maximum Value*                      '4294967295'

This option is common to both master and slave replication servers, and
is used in replication to enable master and slave servers to identify
themselves uniquely.  For additional information, see
replication-options-master, and replication-options-slave.

On the master and each slave, you _must_ use the '--server-id' option to
establish a unique replication ID in the range from 1 to 2^32 − 1.
'Unique', means that each ID must be different from every other ID in
use by any other replication master or slave.  For example,
'server-id=3'.

The '--server-id' option must be specified if binary logging is enabled,
otherwise the server is not allowed to start.  If the server ID is set
to 0, binary logging takes place, but a master with a server ID of 0
refuses any connections from slaves, and a slave with a server ID of 0
refuses to connect to a master.  (Bug #11763963, Bug #56739)

For more information, see replication-howto-slavebaseconfig.

'server_uuid'

In MySQL 5.7, the server generates a true UUID in addition to the
'--server-id' supplied by the user.  This is available as the global,
read-only variable 'server_uuid'.

*Note*:

The presence of the 'server_uuid' system variable in MySQL 5.7 does not
change the requirement for setting a unique '--server-id' for each MySQL
server as part of preparing and running MySQL replication, as described
earlier in this section.

Property                             Value

*System Variable*                    'server_uuid'

*Scope*                              Global

*Dynamic*                            No

*Type*                               string

When starting, the MySQL server automatically obtains a UUID as follows:

  1.
     Attempt to read and use the UUID written in the file
     'DATA_DIR/auto.cnf' (where DATA_DIR is the server's data
     directory).

  2. If 'DATA_DIR/auto.cnf' is not found, generate a new UUID and save
     it to this file, creating the file if necessary.

The 'auto.cnf' file has a format similar to that used for 'my.cnf' or
'my.ini' files.  In MySQL 5.7, 'auto.cnf' has only a single '[auto]'
section containing a single 'server_uuid' setting and value; the file's
contents appear similar to what is shown here:

     [auto]
     server_uuid=8a94f357-aab4-11df-86ab-c80aa9429562

*Important*:

The 'auto.cnf' file is automatically generated; do not attempt to write
or modify this file.

When using MySQL replication, masters and slaves know each other's
UUIDs.  The value of a slave's UUID can be seen in the output of
'SHOW SLAVE HOSTS'.  Once 'START SLAVE'
has been executed, the value of the master's UUID is
available on the slave in the output of 'SHOW SLAVE STATUS'.

*Note*:

Issuing a 'STOP SLAVE' or 'RESET SLAVE'
statement does _not_ reset the master's UUID as used on the
slave.

A server's 'server_uuid' is also used in GTIDs for transactions
originating on that server.  For more information, see
replication-gtids.

When starting, the slave I/O thread generates an error and aborts if its
master's UUID is equal to its own unless the
'--replicate-same-server-id' option has been set.  In addition, the
slave I/O thread generates a warning if either of the following is true:

   * No master having the expected 'server_uuid' exists.

   * The master's 'server_uuid' has changed, although no 'CHANGE MASTER TO'
     statement has ever been executed.

16.1.6.1 Replication and Binary Logging Option and Variable Reference
.....................................................................

The following lists provide basic information about the MySQL
command-line options and system variables applicable to replication and
the binary log.

   * 'abort-slave-event-count': DESCRIPTION: Option used by mysql-test
     for debugging and testing of replication

   * 'binlog_gtid_simple_recovery': DESCRIPTION: Controls how binary
     logs are iterated during GTID recovery

   * 'Com_change_master': DESCRIPTION: Count of CHANGE MASTER TO
     statements

   * 'Com_show_master_status': DESCRIPTION: Count of SHOW MASTER STATUS
     statements

   * 'Com_show_new_master': DESCRIPTION: Count of SHOW NEW MASTER
     statements

   * 'Com_show_slave_hosts': DESCRIPTION: Count of SHOW SLAVE HOSTS
     statements

   * 'Com_show_slave_status': DESCRIPTION: Count of SHOW SLAVE STATUS
     statements

   * 'Com_show_slave_status_nonblocking': DESCRIPTION: Count of SHOW
     SLAVE STATUS NONBLOCKING statements

   * 'Com_slave_start': DESCRIPTION: Count of START SLAVE statements

   * 'Com_slave_stop': DESCRIPTION: Count of STOP SLAVE statements

   * 'disconnect-slave-event-count': DESCRIPTION: Option used by
     mysql-test for debugging and testing of replication

   * 'enforce-gtid-consistency': DESCRIPTION: Prevents execution of
     statements that cannot be logged in a transactionally safe manner

   * 'enforce_gtid_consistency': DESCRIPTION: Prevents execution of
     statements that cannot be logged in a transactionally safe manner

   * 'executed-gtids-compression-period': DESCRIPTION: Deprecated and
     will be removed in a future version; use the renamed
     gtid-executed-compression-period instead

   * 'executed_gtids_compression_period': DESCRIPTION: Deprecated and
     will be removed in a future version; use the renamed
     gtid_executed_compression_period instead

   * 'gtid-executed-compression-period': DESCRIPTION: Compress
     gtid_executed table each time this many transactions have occurred.
     0 means never compress this table.  Applies only when binary
     logging is disabled.

   * 'gtid-mode': DESCRIPTION: Controls whether GTID based logging is
     enabled and what type of transactions the logs can contain

   * 'gtid_executed': DESCRIPTION: Global: All GTIDs in the binary log
     (global) or current transaction (session).  Read-only.

   * 'gtid_executed_compression_period': DESCRIPTION: Compress
     gtid_executed table each time this many transactions have occurred.
     0 means never compress this table.  Applies only when binary
     logging is disabled.

   * 'gtid_mode': DESCRIPTION: Controls whether GTID based logging is
     enabled and what type of transactions the logs can contain

   * 'gtid_next': DESCRIPTION: Specifies the GTID for the next statement
     to execute; see documentation for details

   * 'gtid_owned': DESCRIPTION: The set of GTIDs owned by this client
     (session), or by all clients, together with the thread ID of the
     owner (global).  Read-only.

   * 'gtid_purged': DESCRIPTION: The set of all GTIDs that have been
     purged from the binary log

   * 'init_slave': DESCRIPTION: Statements that are executed when a
     slave connects to a master

   * 'log-slave-updates': DESCRIPTION: Tells the slave to log the
     updates performed by its SQL thread to its own binary log

   * 'log_slave_updates': DESCRIPTION: Whether the slave should log the
     updates performed by its SQL thread to its own binary log.
     Read-only; set using the -log-slave-updates server option.

   * 'log_statements_unsafe_for_binlog': DESCRIPTION: Disables error
     1592 warnings being written to the error log

   * 'master-info-file': DESCRIPTION: The location and name of the file
     that remembers the master and where the I/O replication thread is
     in the master's binary logs

   * 'master-info-repository': DESCRIPTION: Whether to write master
     status information and replication I/O thread location in the
     master's binary logs to a file or table

   * 'master-retry-count': DESCRIPTION: Number of tries the slave makes
     to connect to the master before giving up

   * 'master_info_repository': DESCRIPTION: Whether to write master
     status information and replication I/O thread location in the
     master's binary logs to a file or table

   * 'relay-log': DESCRIPTION: The location and base name to use for
     relay logs

   * 'relay-log-index': DESCRIPTION: The location and name to use for
     the file that keeps a list of the last relay logs

   * 'relay-log-info-file': DESCRIPTION: The location and name of the
     file that remembers where the SQL replication thread is in the
     relay logs

   * 'relay-log-info-repository': DESCRIPTION: Whether to write the
     replication SQL thread's location in the relay logs to a file or a
     table

   * 'relay-log-recovery': DESCRIPTION: Enables automatic recovery of
     relay log files from master at startup

   * 'relay_log_basename': DESCRIPTION: Complete path to relay log,
     including filename

   * 'relay_log_index': DESCRIPTION: The name of the relay log index
     file

   * 'relay_log_info_file': DESCRIPTION: The name of the file in which
     the slave records information about the relay logs

   * 'relay_log_info_repository': DESCRIPTION: Whether to write the
     replication SQL thread's location in the relay logs to a file or a
     table

   * 'relay_log_purge': DESCRIPTION: Determines whether relay logs are
     purged

   * 'relay_log_recovery': DESCRIPTION: Whether automatic recovery of
     relay log files from master at startup is enabled; must be enabled
     for a crash-safe slave

   * 'relay_log_space_limit': DESCRIPTION: Maximum space to use for all
     relay logs

   * 'replicate-do-db': DESCRIPTION: Tells the slave SQL thread to
     restrict replication to the specified database

   * 'replicate-do-table': DESCRIPTION: Tells the slave SQL thread to
     restrict replication to the specified table

   * 'replicate-ignore-db': DESCRIPTION: Tells the slave SQL thread not
     to replicate to the specified database

   * 'replicate-ignore-table': DESCRIPTION: Tells the slave SQL thread
     not to replicate to the specified table

   * 'replicate-rewrite-db': DESCRIPTION: Updates to a database with a
     different name than the original

   * 'replicate-same-server-id': DESCRIPTION: In replication, if set to
     1, do not skip events having our server id

   * 'replicate-wild-do-table': DESCRIPTION: Tells the slave thread to
     restrict replication to the tables that match the specified
     wildcard pattern

   * 'replicate-wild-ignore-table': DESCRIPTION: Tells the slave thread
     not to replicate to the tables that match the given wildcard
     pattern

   * 'report-host': DESCRIPTION: Host name or IP of the slave to be
     reported to the master during slave registration

   * 'report-password': DESCRIPTION: An arbitrary password that the
     slave server should report to the master.  Not the same as the
     password for the MySQL replication user account.

   * 'report-port': DESCRIPTION: Port for connecting to slave reported
     to the master during slave registration

   * 'report-user': DESCRIPTION: An arbitrary user name that a slave
     server should report to the master.  Not the same as the name used
     with the MySQL replication user account.

   * 'Rpl_semi_sync_master_clients': DESCRIPTION: Number of
     semisynchronous slaves

   * 'rpl_semi_sync_master_enabled': DESCRIPTION: Whether
     semisynchronous replication is enabled on the master

   * 'Rpl_semi_sync_master_net_avg_wait_time': DESCRIPTION: The average
     time the master waited for a slave reply

   * 'Rpl_semi_sync_master_net_wait_time': DESCRIPTION: The total time
     the master waited for slave replies

   * 'Rpl_semi_sync_master_net_waits': DESCRIPTION: The total number of
     times the master waited for slave replies

   * 'Rpl_semi_sync_master_no_times': DESCRIPTION: Number of times the
     master turned off semisynchronous replication

   * 'Rpl_semi_sync_master_no_tx': DESCRIPTION: Number of commits not
     acknowledged successfully

   * 'Rpl_semi_sync_master_status': DESCRIPTION: Whether semisynchronous
     replication is operational on the master

   * 'Rpl_semi_sync_master_timefunc_failures': DESCRIPTION: Number of
     times the master failed when calling time functions

   * 'rpl_semi_sync_master_timeout': DESCRIPTION: Number of milliseconds
     to wait for slave acknowledgment

   * 'rpl_semi_sync_master_trace_level': DESCRIPTION: The
     semisynchronous replication debug trace level on the master

   * 'Rpl_semi_sync_master_tx_avg_wait_time': DESCRIPTION: The average
     time the master waited for each transaction

   * 'Rpl_semi_sync_master_tx_wait_time': DESCRIPTION: The total time
     the master waited for transactions

   * 'Rpl_semi_sync_master_tx_waits': DESCRIPTION: The total number of
     times the master waited for transactions

   * 'rpl_semi_sync_master_wait_for_slave_count': DESCRIPTION: How many
     slave acknowledgments the master must receive per transaction
     before proceeding

   * 'rpl_semi_sync_master_wait_no_slave': DESCRIPTION: Whether master
     waits for timeout even with no slaves

   * 'rpl_semi_sync_master_wait_point': DESCRIPTION: The wait point for
     slave transaction receipt acknowledgment

   * 'Rpl_semi_sync_master_wait_pos_backtraverse': DESCRIPTION: The
     total number of times the master waited for an event with binary
     coordinates lower than events waited for previously

   * 'Rpl_semi_sync_master_wait_sessions': DESCRIPTION: Number of
     sessions currently waiting for slave replies

   * 'Rpl_semi_sync_master_yes_tx': DESCRIPTION: Number of commits
     acknowledged successfully

   * 'rpl_semi_sync_slave_enabled': DESCRIPTION: Whether semisynchronous
     replication is enabled on slave

   * 'Rpl_semi_sync_slave_status': DESCRIPTION: Whether semisynchronous
     replication is operational on slave

   * 'rpl_semi_sync_slave_trace_level': DESCRIPTION: The semisynchronous
     replication debug trace level on the slave

   * 'rpl_stop_slave_timeout': DESCRIPTION: Set the number of seconds
     that STOP SLAVE waits before timing out

   * 'server_uuid': DESCRIPTION: The server's globally unique ID,
     automatically (re)generated at server start

   * 'show-slave-auth-info': DESCRIPTION: Show user name and password in
     SHOW SLAVE HOSTS on this master

   * 'simplified_binlog_gtid_recovery': DESCRIPTION: Controls how binary
     logs are iterated during GTID recovery

   * 'skip-slave-start': DESCRIPTION: If set, slave is not autostarted

   * 'slave-checkpoint-group': DESCRIPTION: Maximum number of
     transactions processed by a multi-threaded slave before a
     checkpoint operation is called to update progress status.  Not
     supported by NDB Cluster.

   * 'slave-checkpoint-period': DESCRIPTION: Update progress status of
     multi-threaded slave and flush relay log info to disk after this
     number of milliseconds.  Not supported by NDB Cluster.

   * 'slave-load-tmpdir': DESCRIPTION: The location where the slave
     should put its temporary files when replicating a LOAD DATA INFILE
     statement

   * 'slave-max-allowed-packet': DESCRIPTION: Maximum size, in bytes, of
     a packet that can be sent from a replication master to a slave;
     overrides max_allowed_packet

   * 'slave_net_timeout': DESCRIPTION: Number of seconds to wait for
     more data from a master/slave connection before aborting the read

   * 'slave-parallel-type': DESCRIPTION: Tells the slave to use
     timestamp information (LOGICAL_CLOCK) or database partioning
     (DATABASE) to parallelize transactions.  The default is
     LOGICAL_CLOCK.

   * 'slave-parallel-workers': DESCRIPTION: Number of applier threads
     for executing replication transactions in parallel.  The default is
     4 applier threads.  Set to 0 to disable slave multi-threading.  Not
     supported by MySQL Cluster.

   * 'slave-pending-jobs-size-max': DESCRIPTION: Maximum size of slave
     worker queues holding events not yet applied

   * 'slave-rows-search-algorithms': DESCRIPTION: Determines search
     algorithms used for slave update batching.  Any 2 or 3 from the
     list INDEX_SEARCH, TABLE_SCAN, HASH_SCAN

   * 'slave-skip-errors': DESCRIPTION: Tells the slave thread to
     continue replication when a query returns an error from the
     provided list

   * 'slave_checkpoint_group': DESCRIPTION: Maximum number of
     transactions processed by a multi-threaded slave before a
     checkpoint operation is called to update progress status.  Not
     supported by NDB Cluster.

   * 'slave_checkpoint_period': DESCRIPTION: Update progress status of
     multi-threaded slave and flush relay log info to disk after this
     number of milliseconds.  Not supported by NDB Cluster.

   * 'slave_compressed_protocol': DESCRIPTION: Use compression on
     master/slave protocol

   * 'slave_exec_mode': DESCRIPTION: Allows for switching the slave
     thread between IDEMPOTENT mode (key and some other errors
     suppressed) and STRICT mode; STRICT mode is the default, except for
     NDB Cluster, where IDEMPOTENT is always used

   * 'Slave_heartbeat_period': DESCRIPTION: The slave's replication
     heartbeat interval, in seconds

   * 'slave_max_allowed_packet': DESCRIPTION: Maximum size, in bytes, of
     a packet that can be sent from a replication master to a slave;
     overrides max_allowed_packet

   * 'Slave_open_temp_tables': DESCRIPTION: Number of temporary tables
     that the slave SQL thread currently has open

   * 'slave_parallel_type': DESCRIPTION: Tells the slave to use
     timestamp information (LOGICAL_CLOCK) or database partioning
     (DATABASE) to parallelize transactions.

   * 'slave_parallel_workers': DESCRIPTION: Number of applier threads
     for executing replication transactions in parallel.  A value of 0
     disables slave multi-threading.  Not supported by MySQL Cluster.

   * 'slave_pending_jobs_size_max': DESCRIPTION: Maximum size of slave
     worker queues holding events not yet applied

   * 'slave_preserve_commit_order': DESCRIPTION: Ensures that all
     commits by slave workers happen in the same order as on the master
     to maintain consistency when using parallel applier threads.

   * 'Slave_retried_transactions': DESCRIPTION: The total number of
     times since startup that the replication slave SQL thread has
     retried transactions

   * 'slave_rows_search_algorithms': DESCRIPTION: Determines search
     algorithms used for slave update batching.  Any 2 or 3 from the
     list INDEX_SEARCH, TABLE_SCAN, HASH_SCAN.

   * 'Slave_rows_last_search_algorithm_used': DESCRIPTION: Search
     algorithm most recently used by this slave to locate rows for
     row-based replication (index, table, or hash scan)

   * 'Slave_running': DESCRIPTION: The state of this server as a
     replication slave (slave I/O thread status)

   * 'slave_transaction_retries': DESCRIPTION: Number of times the slave
     SQL thread will retry a transaction in case it failed with a
     deadlock or elapsed lock wait timeout, before giving up and
     stopping

   * 'slave_type_conversions': DESCRIPTION: Controls type conversion
     mode on replication slave.  Value is a list of zero or more
     elements from the list: ALL_LOSSY, ALL_NON_LOSSY. Set to an empty
     string to disallow type conversions between master and slave.

   * 'sql_slave_skip_counter': DESCRIPTION: Number of events from the
     master that a slave server should skip.  Not compatible with GTID
     replication.

   * 'sync_binlog': DESCRIPTION: Synchronously flush binary log to disk
     after every #th event

   * 'sync_master_info': DESCRIPTION: Synchronize master.info to disk
     after every #th event

   * 'sync_relay_log': DESCRIPTION: Synchronize relay log to disk after
     every #th event

   * 'sync_relay_log_info': DESCRIPTION: Synchronize relay.info file to
     disk after every #th event

See replication-options-master, provides more detailed information
about options and variables relating to replication master servers.  For
more information about options and variables relating to replication
slaves, see replication-options-slave.

   * 'binlog-checksum': DESCRIPTION: Enable/disable binary log checksums

   * 'binlog-do-db': DESCRIPTION: Limits binary logging to specific
     databases

   * 'binlog_format': DESCRIPTION: Specifies the format of the binary
     log

   * 'binlog-ignore-db': DESCRIPTION: Tells the master that updates to
     the given database should not be logged to the binary log

   * 'binlog-row-event-max-size': DESCRIPTION: Binary log max event size

   * 'binlog-rows-query-log-events': DESCRIPTION: Enables logging of
     rows query log events when using row-based logging.  Disabled by
     default.  Do not enable when producing logs for pre-5.6
     slaves/readers.

   * 'Binlog_cache_disk_use': DESCRIPTION: Number of transactions that
     used a temporary file instead of the binary log cache

   * 'binlog_cache_size': DESCRIPTION: Size of the cache to hold the SQL
     statements for the binary log during a transaction

   * 'Binlog_cache_use': DESCRIPTION: Number of transactions that used
     the temporary binary log cache

   * 'binlog_checksum': DESCRIPTION: Enable/disable binary log checksums

   * 'binlog_direct_non_transactional_updates': DESCRIPTION: Causes
     updates using statement format to nontransactional engines to be
     written directly to binary log.  See documentation before using.

   * 'binlog_error_action': DESCRIPTION: Controls what happens when the
     server cannot write to the binary log

   * 'binlog_group_commit_sync_delay': DESCRIPTION: Sets the number of
     microseconds to wait before synchronizing transactions to disk

   * 'binlog_group_commit_sync_no_delay_count': DESCRIPTION: Sets the
     maximum number of transactions to wait for before aborting the
     current delay specified by binlog_group_commit_sync_delay

   * 'binlog_max_flush_queue_time': DESCRIPTION: How long to read
     transactions before flushing to binary log

   * 'binlog_order_commits': DESCRIPTION: Whether to commit in same
     order as writes to binary log

   * 'binlog_row_image': DESCRIPTION: Use full or minimal images when
     logging row changes

   * 'binlog_rows_query_log_events': DESCRIPTION: When TRUE, enables
     logging of rows query log events in row-based logging mode.  FALSE
     by default.  Do not enable when producing logs for pre-5.6
     replication slaves or other readers.

   * 'Binlog_stmt_cache_disk_use': DESCRIPTION: Number of
     nontransactional statements that used a temporary file instead of
     the binary log statement cache

   * 'binlog_stmt_cache_size': DESCRIPTION: Size of the cache to hold
     nontransactional statements for the binary log during a transaction

   * 'Binlog_stmt_cache_use': DESCRIPTION: Number of statements that
     used the temporary binary log statement cache

   * 'binlog_transaction_dependency_tracking': DESCRIPTION: Source of
     dependency information (commit timestamps or transaction write
     sets) from which to assess which transactions can be executed in
     parallel by slave's multi-threaded applier.

   * 'binlog_transaction_dependency_history_size': DESCRIPTION: Number
     of row hashes kept for looking up transaction that last updated
     some row.

   * 'binlogging_impossible_mode': DESCRIPTION: Deprecated and will be
     removed in a future version.  Use the renamed binlog_error_action
     instead.

   * 'Com_show_binlog_events': DESCRIPTION: Count of SHOW BINLOG EVENTS
     statements

   * 'Com_show_binlogs': DESCRIPTION: Count of SHOW BINLOGS statements

   * 'log-bin-use-v1-row-events': DESCRIPTION: Use version 1 binary log
     row events

   * 'log_bin_basename': DESCRIPTION: Path and base name for binary log
     files

   * 'log_bin_use_v1_row_events': DESCRIPTION: Shows whether server is
     using version 1 binary log row events

   * 'master-verify-checksum': DESCRIPTION: Cause master to examine
     checksums when reading from the binary log

   * 'master_verify_checksum': DESCRIPTION: Cause master to read
     checksums from binary log

   * 'max-binlog-dump-events': DESCRIPTION: Option used by mysql-test
     for debugging and testing of replication

   * 'max_binlog_cache_size': DESCRIPTION: Can be used to restrict the
     total size used to cache a multi-statement transaction

   * 'max_binlog_size': DESCRIPTION: Binary log will be rotated
     automatically when size exceeds this value

   * 'max_binlog_stmt_cache_size': DESCRIPTION: Can be used to restrict
     the total size used to cache all nontransactional statements during
     a transaction

   * 'slave-sql-verify-checksum': DESCRIPTION: Cause slave to examine
     checksums when reading from the relay log

   * 'slave_sql_verify_checksum': DESCRIPTION: Cause slave to examine
     checksums when reading from relay log

   * 'sporadic-binlog-dump-fail': DESCRIPTION: Option used by mysql-test
     for debugging and testing of replication

See replication-options-binary-log, provides more detailed
information about options and variables relating to binary logging.  For
additional general information about the binary log, see
binary-log.

For information about the 'sql_log_bin' and 'sql_log_off' variables, see
server-system-variables.

For a lsiting with _all_ command-line options, system and status
variables used with 'mysqld', see
mysqld-option-tables.

16.1.6.2 Replication Master Options and Variables
.................................................

This section describes the server options and system variables that you
can use on replication master servers.  You can specify the options
either on the command line or in an
option file.  You can specify system variable values using
'SET'.

On the master and each slave, you must use the 'server-id' option to
establish a unique replication ID. For each server, you should pick a
unique positive integer in the range from 1 to 2^32 − 1, and each ID
must be different from every other ID in use by any other replication
master or slave.  Example: 'server-id=3'.

For options used on the master for controlling binary logging, see
replication-options-binary-log.

*Startup Options for Replication Masters*

The following list describes startup options for controlling replication
master servers.  Replication-related system variables are discussed
later in this section.

   *
     '--show-slave-auth-info'

     Property                             Value

     *Command-Line Format*                '--show-slave-auth-info'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Display slave user names and passwords in the output of 'SHOW SLAVE HOSTS'
     on the master server for slaves
     started with the '--report-user' and '--report-password' options.

*System Variables Used on Replication Masters*

The following system variables are used to control replication masters:

   *
     'auto_increment_increment'

     Property                             Value

     *System Variable*                    'auto_increment_increment'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     'auto_increment_increment' and 'auto_increment_offset' are intended
     for use with master-to-master replication, and can be used to
     control the operation of 'AUTO_INCREMENT' columns.  Both variables
     have global and session values, and each can assume an integer
     value between 1 and 65,535 inclusive.  Setting the value of either
     of these two variables to 0 causes its value to be set to 1
     instead.  Attempting to set the value of either of these two
     variables to an integer greater than 65,535 or less than 0 causes
     its value to be set to 65,535 instead.  Attempting to set the value
     of 'auto_increment_increment' or 'auto_increment_offset' to a
     noninteger value produces an error, and the actual value of the
     variable remains unchanged.

     *Note*:

     'auto_increment_increment' is also supported for use with
     'NDB' tables.

     These two variables affect 'AUTO_INCREMENT' column behavior as
     follows:

        * 'auto_increment_increment' controls the interval between
          successive column values.  For example:

               mysql> SHOW VARIABLES LIKE 'auto_inc%';
               +--------------------------+-------+
               | Variable_name            | Value |
               +--------------------------+-------+
               | auto_increment_increment | 1     |
               | auto_increment_offset    | 1     |
               +--------------------------+-------+
               2 rows in set (0.00 sec)

               mysql> CREATE TABLE autoinc1
                   -> (col INT NOT NULL AUTO_INCREMENT PRIMARY KEY);
                 Query OK, 0 rows affected (0.04 sec)

               mysql> SET @@auto_increment_increment=10;
               Query OK, 0 rows affected (0.00 sec)

               mysql> SHOW VARIABLES LIKE 'auto_inc%';
               +--------------------------+-------+
               | Variable_name            | Value |
               +--------------------------+-------+
               | auto_increment_increment | 10    |
               | auto_increment_offset    | 1     |
               +--------------------------+-------+
               2 rows in set (0.01 sec)

               mysql> INSERT INTO autoinc1 VALUES (NULL), (NULL), (NULL), (NULL);
               Query OK, 4 rows affected (0.00 sec)
               Records: 4  Duplicates: 0  Warnings: 0

               mysql> SELECT col FROM autoinc1;
               +-----+
               | col |
               +-----+
               |   1 |
               |  11 |
               |  21 |
               |  31 |
               +-----+
               4 rows in set (0.00 sec)

        * 'auto_increment_offset' determines the starting point for the
          'AUTO_INCREMENT' column value.  Consider the following,
          assuming that these statements are executed during the same
          session as the example given in the description for
          'auto_increment_increment':

               mysql> SET @@auto_increment_offset=5;
               Query OK, 0 rows affected (0.00 sec)

               mysql> SHOW VARIABLES LIKE 'auto_inc%';
               +--------------------------+-------+
               | Variable_name            | Value |
               +--------------------------+-------+
               | auto_increment_increment | 10    |
               | auto_increment_offset    | 5     |
               +--------------------------+-------+
               2 rows in set (0.00 sec)

               mysql> CREATE TABLE autoinc2
                   -> (col INT NOT NULL AUTO_INCREMENT PRIMARY KEY);
               Query OK, 0 rows affected (0.06 sec)

               mysql> INSERT INTO autoinc2 VALUES (NULL), (NULL), (NULL), (NULL);
               Query OK, 4 rows affected (0.00 sec)
               Records: 4  Duplicates: 0  Warnings: 0

               mysql> SELECT col FROM autoinc2;
               +-----+
               | col |
               +-----+
               |   5 |
               |  15 |
               |  25 |
               |  35 |
               +-----+
               4 rows in set (0.02 sec)

          When the value of 'auto_increment_offset' is greater than that
          of 'auto_increment_increment', the value of
          'auto_increment_offset' is ignored.

     If either of these variables is changed, and then new rows inserted
     into a table containing an 'AUTO_INCREMENT' column, the results may
     seem counterintuitive because the series of 'AUTO_INCREMENT' values
     is calculated without regard to any values already present in the
     column, and the next value inserted is the least value in the
     series that is greater than the maximum existing value in the
     'AUTO_INCREMENT' column.  The series is calculated like this:

     'auto_increment_offset' + N x 'auto_increment_increment'

     where N is a positive integer value in the series [1, 2, 3, ...].
     For example:

          mysql> SHOW VARIABLES LIKE 'auto_inc%';
          +--------------------------+-------+
          | Variable_name            | Value |
          +--------------------------+-------+
          | auto_increment_increment | 10    |
          | auto_increment_offset    | 5     |
          +--------------------------+-------+
          2 rows in set (0.00 sec)

          mysql> SELECT col FROM autoinc1;
          +-----+
          | col |
          +-----+
          |   1 |
          |  11 |
          |  21 |
          |  31 |
          +-----+
          4 rows in set (0.00 sec)

          mysql> INSERT INTO autoinc1 VALUES (NULL), (NULL), (NULL), (NULL);
          Query OK, 4 rows affected (0.00 sec)
          Records: 4  Duplicates: 0  Warnings: 0

          mysql> SELECT col FROM autoinc1;
          +-----+
          | col |
          +-----+
          |   1 |
          |  11 |
          |  21 |
          |  31 |
          |  35 |
          |  45 |
          |  55 |
          |  65 |
          +-----+
          8 rows in set (0.00 sec)

     The values shown for 'auto_increment_increment' and
     'auto_increment_offset' generate the series 5 + N x 10, that is,
     [5, 15, 25, 35, 45, ...].  The highest value present in the 'col'
     column prior to the 'INSERT' is 31, and the next
     available value in the 'AUTO_INCREMENT' series is 35, so the
     inserted values for 'col' begin at that point and the results are
     as shown for the 'SELECT' query.

     It is not possible to restrict the effects of these two variables
     to a single table; these variables control the behavior of all
     'AUTO_INCREMENT' columns in _all_ tables on the MySQL server.  If
     the global value of either variable is set, its effects persist
     until the global value is changed or overridden by setting the
     session value, or until 'mysqld' is restarted.  If
     the local value is set, the new value affects 'AUTO_INCREMENT'
     columns for all tables into which new rows are inserted by the
     current user for the duration of the session, unless the values are
     changed during that session.

     The default value of 'auto_increment_increment' is 1.  See
     replication-features-auto-increment.

   *
     'auto_increment_offset'

     Property                             Value

     *System Variable*                    'auto_increment_offset'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     This variable has a default value of 1.  For more information, see
     the description for 'auto_increment_increment'.

     *Note*:

     'auto_increment_offset' is also supported for use with 'NDB'
     tables.

16.1.6.3 Replication Slave Options and Variables
................................................

This section explains the server options and system variables that apply
to slave replication servers and contains the following:

   * replication-optvars-slaves

   * replication-options-slave-log-tables

   * replication-sysvars-slaves

Specify the options either on the command line
or in an option file.  Many of
the options can be set while the server is running by using the
'CHANGE MASTER TO' statement.  Specify system
variable values using 'SET'.

Server ID

On the master and each slave, you must use the 'server-id' option to
establish a unique replication ID in the range from 1 to 2^32 − 1.
'Unique' means that each ID must be different from every other ID in use
by any other replication master or slave.  Example 'my.cnf' file:

     [mysqld]
     server-id=3

*Startup Options for Replication Slaves*

This section explains startup options for controlling replication slave
servers.  Many of these options can be set while the server is running
by using the 'CHANGE MASTER TO' statement.
Others, such as the '--replicate-*' options, can be set only when the
slave server starts.  Replication-related system variables are discussed
later in this section.

   *
     '--log-slave-updates'

     Property                             Value

     *Command-Line Format*                '--log-slave-updates'

     *System Variable*                    'log_slave_updates'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'OFF'

     Normally, a slave does not write any updates that are received from
     a master server to its own binary log.  This option causes the
     slave to write the updates performed by its SQL thread to its own
     binary log.  For this option to have any effect, the slave must
     also be started with the '--log-bin' option to enable binary
     logging.  '--log-slave-updates' is used when you want to chain
     replication servers.  For example, you might want to set up
     replication servers using this arrangement:

          A -> B -> C

     Here, 'A' serves as the master for the slave 'B', and 'B' serves as
     the master for the slave 'C'.  For this to work, 'B' must be both a
     master _and_ a slave.  You must start both 'A' and 'B' with
     '--log-bin' to enable binary logging, and 'B' with the
     '--log-slave-updates' option so that updates received from 'A' are
     logged by 'B' to its binary log.

   *
     '--log-slow-slave-statements'

     Property                             Value

     *Command-Line Format*                '--log-slow-slave-statements'
                                          (5.7.0)

     *Removed*                            5.7.1

     *Type*                               boolean

     *Default Value*                      'OFF'

     This command-line option was removed in MySQL 5.7.1 and replaced by
     the 'log_slow_slave_statements' system variable.  The system
     variable can be set on the command line or in option files the same
     way as the option, so there is no need for any changes at server
     startup, but the system variable also makes it possible to examine
     or set the value at runtime.

   *
     '--log-warnings[=LEVEL]'

     Property                             Value

     *Command-Line Format*                '--log-warnings[=#]'

     *Deprecated*                         5.7.2

     *System Variable*                    'log_warnings'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms,   '2'
     >= 5.7.2)

     *Default Value* (64-bit platforms,   '1'
     <= 5.7.1)

     *Default Value* (32-bit platforms,   '2'
     >= 5.7.2)

     *Default Value* (32-bit platforms,   '1'
     <= 5.7.1)

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     *Note*:

     The 'log_error_verbosity' system variable is preferred over, and
     should be used instead of, the '--log-warnings' option or
     'log_warnings' system variable.  For more information, see the
     descriptions of 'log_error_verbosity' and 'log_warnings'.  The
     '--log-warnings' command-line option and 'log_warnings' system
     variable are deprecated and will be removed in a future MySQL
     release.

     Causes the server to record more messages to the error log about
     what it is doing.  With respect to replication, the server
     generates warnings that it succeeded in reconnecting after a
     network or connection failure, and provides information about how
     each slave thread started.  This variable is set to 2 by default.
     To disable it, set it to 0.  The server logs messages about
     statements that are unsafe for statement-based logging if the value
     is greater than 0.  Aborted connections and access-denied errors
     for new connection attempts are logged if the value is greater than
     1.  See communication-errors.

     *Note*:

     The effects of this option are not limited to replication.  It
     affects diagnostic messages across a spectrum of server activities.

   *
     '--master-info-file=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--master-info-file=file_name'

     *Type*                               file name

     *Default Value*                      'master.info'

     The name to use for the file in which the slave records information
     about the master.  The default name is 'master.info' in the data
     directory.  For information about the format of this file, see
     slave-logs-status.

   *
     '--master-retry-count=COUNT'

     Property                             Value

     *Command-Line Format*                '--master-retry-count=#'

     *Deprecated*                         Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '86400'

     *Default Value* (32-bit platforms)   '86400'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The number of times that the slave tries to connect to the master
     before giving up.  Reconnects are attempted at intervals set by the
     'MASTER_CONNECT_RETRY' option of the 'CHANGE MASTER TO'
     statement (default 60).  Reconnects are triggered
     when data reads by the slave time out according to the
     '--slave-net-timeout' option.  The default value is 86400.  A value
     of 0 means 'infinite'; the slave attempts to connect forever.

     This option is deprecated and will be removed in a future MySQL
     release.  Applications should be updated to use the
     'MASTER_RETRY_COUNT' option of the 'CHANGE MASTER TO'
     statement instead.

   *
     '--max-relay-log-size=SIZE'

     Property                             Value

     *Command-Line Format*                '--max-relay-log-size=#'

     *System Variable*                    'max_relay_log_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1073741824'

     The size at which the server rotates relay log files automatically.
     If this value is nonzero, the relay log is rotated automatically
     when its size exceeds this value.  If this value is zero (the
     default), the size at which relay log rotation occurs is determined
     by the value of 'max_binlog_size'.  For more information, see
     slave-logs-relaylog.

   *
     '--relay-log=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--relay-log=file_name'

     *System Variable*                    'relay_log'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The base name for the relay log.  For the default replication
     channel, the default base name for relay logs is
     'HOST_NAME-relay-bin'.  For non-default replication channels, the
     default base name for relay logs is 'HOST_NAME-relay-bin-CHANNEL',
     where CHANNEL is the name of the replication channel recorded in
     this relay log.  The server writes the file in the data directory
     unless the base name is given with a leading absolute path name to
     specify a different directory.  The server creates relay log files
     in sequence by adding a numeric suffix to the base name.

     Due to the manner in which MySQL parses server options, if you
     specify this option, you must supply a value; _the default base
     name is used only if the option is not actually specified_.  If you
     use the '--relay-log' option without specifying a value, unexpected
     behavior is likely to result; this behavior depends on the other
     options used, the order in which they are specified, and whether
     they are specified on the command line or in an option file.  For
     more information about how MySQL handles server options, see
     program-options.

     If you specify this option, the value specified is also used as the
     base name for the relay log index file.  You can override this
     behavior by specifying a different relay log index file base name
     using the '--relay-log-index' option.

     When the server reads an entry from the index file, it checks
     whether the entry contains a relative path.  If it does, the
     relative part of the path is replaced with the absolute path set
     using the '--relay-log' option.  An absolute path remains
     unchanged; in such a case, the index must be edited manually to
     enable the new path or paths to be used.  Previously, manual
     intervention was required whenever relocating the binary log or
     relay log files.  (Bug #11745230, Bug #12133)

     You may find the '--relay-log' option useful in performing the
     following tasks:

        * Creating relay logs whose names are independent of host names.

        * If you need to put the relay logs in some area other than the
          data directory because your relay logs tend to be very large
          and you do not want to decrease 'max_relay_log_size'.

        * To increase speed by using load-balancing between disks.

     You can obtain the relay log file name (and path) from the
     'relay_log_basename' system variable.

   *
     '--relay-log-index=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--relay-log-index=file_name'

     *System Variable*                    'relay_log_index'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The name to use for the relay log index file.  The default name is
     'HOST_NAME-relay-bin.index' in the data directory, where HOST_NAME
     is the name of the server.  For the default replication channel,
     the default name is 'HOST_NAME-relay-bin.index'.  For non-default
     replication channels, the default name is
     'HOST_NAME-relay-bin-CHANNEL.index', where CHANNEL is the name of
     the replication channel recorded in this relay log index.

     Due to the manner in which MySQL parses server options, if you
     specify this option, you must supply a value; _the default base
     name is used only if the option is not actually specified_.  If you
     use the '--relay-log-index' option without specifying a value,
     unexpected behavior is likely to result; this behavior depends on
     the other options used, the order in which they are specified, and
     whether they are specified on the command line or in an option
     file.  For more information about how MySQL handles server options,
     see program-options.

   *
     '--relay-log-info-file=FILE_NAME'

     Property                             Value

     *Command-Line Format*                '--relay-log-info-file=file_name'

     *Type*                               file name

     *Default Value*                      'relay-log.info'

     The name to use for the file in which the slave records information
     about the relay logs.  The default name is 'relay-log.info' in the
     data directory.  For information about the format of this file, see
     slave-logs-status.

   *
     '--relay-log-purge={0|1}'

     Property                             Value

     *Command-Line Format*                '--relay-log-purge'

     *System Variable*                    'relay_log_purge'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Disable or enable automatic purging of relay logs as soon as they
     are no longer needed.  The default value is 1 (enabled).  This is a
     global variable that can be changed dynamically with 'SET GLOBAL
     relay_log_purge = N'.  Disabling purging of relay logs when using
     the '--relay-log-recovery' option puts data consistency at risk.

   *
     '--relay-log-recovery={0|1}'

     Property                             Value

     *Command-Line Format*                '--relay-log-recovery'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Enables automatic relay log recovery immediately following server
     startup.  The recovery process creates a new relay log file,
     initializes the SQL thread position to this new relay log, and
     initializes the I/O thread to the SQL thread position.  Reading of
     the relay log from the master then continues.  This should be used
     following an unexpected halt of a replication slave to ensure that
     no possibly corrupted relay logs are processed.  The default value
     is 0 (disabled).

     This variable can be set to 1 to make a slave resilient to
     unexpected halts, see
     replication-solutions-unexpected-slave-halt for more information.
     Enabling the '--relay-log-recovery' option when 'relay-log-purge'
     is disabled risks reading the relay log from files that were not
     purged, leading to data inconsistency.

     When using a multi-threaded slave (in other words
     'slave_parallel_workers' is greater than 0), inconsistencies such
     as gaps can occur in the sequence of transactions that have been
     executed from the relay log.  Enabling the '--relay-log-recovery'
     option when there are inconsistencies causes an error and the
     option has no effect.  The solution in this situation is to issue
     'START SLAVE UNTIL SQL_AFTER_MTS_GAPS', which
     brings the server to a more consistent state, then issue
     'RESET SLAVE' to remove the relay logs.  See
     replication-features-transaction-inconsistencies for more
     information.

   *
     '--relay-log-space-limit=SIZE'

     Property                             Value

     *Command-Line Format*                '--relay-log-space-limit=#'

     *System Variable*                    'relay_log_space_limit'

     *Scope*                              Global

     *Dynamic*                            No

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '0'

     *Default Value* (32-bit platforms)   '0'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     This option places an upper limit on the total size in bytes of all
     relay logs on the slave.  A value of 0 means 'no limit'.  This is
     useful for a slave server host that has limited disk space.  When
     the limit is reached, the I/O thread stops reading binary log
     events from the master server until the SQL thread has caught up
     and deleted some unused relay logs.  Note that this limit is not
     absolute: There are cases where the SQL thread needs more events
     before it can delete relay logs.  In that case, the I/O thread
     exceeds the limit until it becomes possible for the SQL thread to
     delete some relay logs because not doing so would cause a deadlock.
     You should not set '--relay-log-space-limit' to less than twice the
     value of '--max-relay-log-size' (or '--max-binlog-size' if
     '--max-relay-log-size' is 0).  In that case, there is a chance that
     the I/O thread waits for free space because
     '--relay-log-space-limit' is exceeded, but the SQL thread has no
     relay log to purge and is unable to satisfy the I/O thread.  This
     forces the I/O thread to ignore '--relay-log-space-limit'
     temporarily.

   *
     '--replicate-do-db=DB_NAME'

     Property                             Value

     *Command-Line Format*                '--replicate-do-db=name'

     *Type*                               string

     Creates a replication filter using the name of a database.  Such
     filters can also be created using 'CHANGE REPLICATION FILTER REPLICATE_DO_DB'.
     The precise effect of
     this filtering depends on whether statement-based or row-based
     replication is in use, and are described in the next several
     paragraphs.

     Statement-based replication

     Tell the slave SQL thread to restrict replication to statements
     where the default database (that is, the one selected by
     'USE') is DB_NAME.  To specify more than one database, use
     this option multiple times, once for each database; however, doing
     so does _not_ replicate cross-database statements such as 'UPDATE
     SOME_DB.SOME_TABLE SET foo='bar'' while a different database (or no
     database) is selected.

     *Warning*:

     To specify multiple databases you _must_ use multiple instances of
     this option.  Because database names can contain commas, if you
     supply a comma separated list then the list will be treated as the
     name of a single database.

     An example of what does not work as you might expect when using
     statement-based replication: If the slave is started with
     '--replicate-do-db=sales' and you issue the following statements on
     the master, the 'UPDATE' statement is _not_
     replicated:

          USE prices;
          UPDATE sales.january SET amount=amount+1000;

     The main reason for this 'check just the default database' behavior
     is that it is difficult from the statement alone to know whether it
     should be replicated (for example, if you are using multiple-table
     'DELETE' statements or multiple-table
     'UPDATE' statements that act across multiple databases).
     It is also faster to check only the default database rather than
     all databases if there is no need.

     Row-based replication

     Tells the slave SQL thread to restrict replication to database
     DB_NAME.  Only tables belonging to DB_NAME are changed; the current
     database has no effect on this.  Suppose that the slave is started
     with '--replicate-do-db=sales' and row-based replication is in
     effect, and then the following statements are run on the master:

          USE prices;
          UPDATE sales.february SET amount=amount+100;

     The 'february' table in the 'sales' database on the slave is
     changed in accordance with the 'UPDATE' statement;
     this occurs whether or not the 'USE' statement was
     issued.  However, issuing the following statements on the master
     has no effect on the slave when using row-based replication and
     '--replicate-do-db=sales':

          USE prices;
          UPDATE prices.march SET amount=amount-25;

     Even if the statement 'USE prices' were changed to 'USE sales', the
     'UPDATE' statement's effects would still not be
     replicated.

     Another important difference in how '--replicate-do-db' is handled
     in statement-based replication as opposed to row-based replication
     occurs with regard to statements that refer to multiple databases.
     Suppose that the slave is started with '--replicate-do-db=db1', and
     the following statements are executed on the master:

          USE db1;
          UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;

     If you are using statement-based replication, then both tables are
     updated on the slave.  However, when using row-based replication,
     only 'table1' is affected on the slave; since 'table2' is in a
     different database, 'table2' on the slave is not changed by the
     'UPDATE'.  Now suppose that, instead of the 'USE db1'
     statement, a 'USE db4' statement had been used:

          USE db4;
          UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;

     In this case, the 'UPDATE' statement would have no
     effect on the slave when using statement-based replication.
     However, if you are using row-based replication, the
     'UPDATE' would change 'table1' on the slave, but not
     'table2'--in other words, only tables in the database named by
     '--replicate-do-db' are changed, and the choice of default database
     has no effect on this behavior.

     If you need cross-database updates to work, use
     '--replicate-wild-do-table=DB_NAME.%' instead.  See
     replication-rules.

     *Note*:

     This option affects replication in the same manner that
     '--binlog-do-db' affects binary logging, and the effects of the
     replication format on how '--replicate-do-db' affects replication
     behavior are the same as those of the logging format on the
     behavior of '--binlog-do-db'.

     This option has no effect on 'BEGIN', 'COMMIT',
     or 'ROLLBACK' statements.

   *
     '--replicate-ignore-db=DB_NAME'

     Property                             Value

     *Command-Line Format*                '--replicate-ignore-db=name'

     *Type*                               string

     Creates a replication filter using the name of a database.  Such
     filters can also be created using 'CHANGE REPLICATION FILTER REPLICATE_IGNORE_DB'.
     As with
     '--replicate-do-db', the precise effect of this filtering depends
     on whether statement-based or row-based replication is in use, and
     are described in the next several paragraphs.

     Statement-based replication

     Tells the slave SQL thread not to replicate any statement where the
     default database (that is, the one selected by 'USE')
     is DB_NAME.

     Row-based replication

     Tells the slave SQL thread not to update any tables in the database
     DB_NAME.  The default database has no effect.

     When using statement-based replication, the following example does
     not work as you might expect.  Suppose that the slave is started
     with '--replicate-ignore-db=sales' and you issue the following
     statements on the master:

          USE prices;
          UPDATE sales.january SET amount=amount+1000;

     The 'UPDATE' statement _is_ replicated in such a
     case because '--replicate-ignore-db' applies only to the default
     database (determined by the 'USE' statement).  Because
     the 'sales' database was specified explicitly in the statement, the
     statement has not been filtered.  However, when using row-based
     replication, the 'UPDATE' statement's effects are
     _not_ propagated to the slave, and the slave's copy of the
     'sales.january' table is unchanged; in this instance,
     '--replicate-ignore-db=sales' causes _all_ changes made to tables
     in the master's copy of the 'sales' database to be ignored by the
     slave.

     To specify more than one database to ignore, use this option
     multiple times, once for each database.  Because database names can
     contain commas, if you supply a comma separated list then the list
     will be treated as the name of a single database.

     You should not use this option if you are using cross-database
     updates and you do not want these updates to be replicated.  See
     replication-rules.

     If you need cross-database updates to work, use
     '--replicate-wild-ignore-table=DB_NAME.%' instead.  See
     replication-rules.

     *Note*:

     This option affects replication in the same manner that
     '--binlog-ignore-db' affects binary logging, and the effects of the
     replication format on how '--replicate-ignore-db' affects
     replication behavior are the same as those of the logging format on
     the behavior of '--binlog-ignore-db'.

     This option has no effect on 'BEGIN', 'COMMIT',
     or 'ROLLBACK' statements.

   *
     '--replicate-do-table=DB_NAME.TBL_NAME'

     Property                             Value

     *Command-Line Format*                '--replicate-do-table=name'

     *Type*                               string

     Creates a replication filter by telling the slave SQL thread to
     restrict replication to a given table.  To specify more than one
     table, use this option multiple times, once for each table.  This
     works for both cross-database updates and default database updates,
     in contrast to '--replicate-do-db'.  See replication-rules.
     You can also create such a filter by issuing a 'CHANGE REPLICATION FILTER REPLICATE_DO_TABLE'.
     statement.

     This option affects only statements that apply to tables.  It does
     not affect statements that apply only to other database objects,
     such as stored routines.  To filter statements operating on stored
     routines, use one or more of the '--replicate-*-db' options.

   *
     '--replicate-ignore-table=DB_NAME.TBL_NAME'

     Property                             Value

     *Command-Line Format*                '--replicate-ignore-table=name'

     *Type*                               string

     Creates a replication filter by telling the slave SQL thread not to
     replicate any statement that updates the specified table, even if
     any other tables might be updated by the same statement.  To
     specify more than one table to ignore, use this option multiple
     times, once for each table.  This works for cross-database updates,
     in contrast to '--replicate-ignore-db'.  See
     replication-rules.  You can also create such a filter by issuing
     a 'CHANGE REPLICATION FILTER REPLICATE_IGNORE_TABLE'
     statement.

     This option affects only statements that apply to tables.  It does
     not affect statements that apply only to other database objects,
     such as stored routines.  To filter statements operating on stored
     routines, use one or more of the '--replicate-*-db' options.

   *
     '--replicate-rewrite-db=FROM_NAME->TO_NAME'

     Property                             Value

     *Command-Line Format*                '--replicate-rewrite-db=old_name->new_name'

     *Type*                               string

     Tells the slave to create a replication filter that translates the
     default database (that is, the one selected by 'USE')
     to TO_NAME if it was FROM_NAME on the master.  Only statements
     involving tables are affected (not statements such as 'CREATE DATABASE',
     see 'DROP DATABASE',
     and 'ALTER DATABASE'), and only if FROM_NAME
     is the default database on the master.  To specify multiple
     rewrites, use this option multiple times.  The server uses the
     first one with a FROM_NAME value that matches.  The database name
     translation is done _before_ the '--replicate-*' rules are tested.
     You can also create such a filter by issuing a 'CHANGE REPLICATION FILTER REPLICATE_REWRITE_DB'
     statement.

     Statements in which table names are qualified with database names
     when using this option do not work with table-level replication
     filtering options such as '--replicate-do-table'.  Suppose we have
     a database named 'a' on the master, one named 'b' on the slave,
     each containing a table 't', and have started the master with
     '--replicate-rewrite-db='a->b''.  At a later point in time, we
     execute 'DELETE FROM a.t'.  In this case, no relevant
     filtering rule works, for the reasons shown here:

       1. '--replicate-do-table=a.t' does not work because the slave has
          table 't' in database 'b'.

       2. '--replicate-do-table=b.t' does not match the original
          statement and so is ignored.

       3. '--replicate-do-table=*.t' is handled identically to
          '--replicate-do-table=a.t', and thus does not work, either.

     Similarly, the '--replication-rewrite-db' option does not work with
     cross-database updates.

     If you use this option on the command line and the '>' character is
     special to your command interpreter, quote the option value.  For
     example:

          shell> mysqld --replicate-rewrite-db="OLDDB->NEWDB"

   *
     '--replicate-same-server-id'

     Property                             Value

     *Command-Line Format*                '--replicate-same-server-id'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     To be used on slave servers.  Usually you should use the default
     setting of 0, to prevent infinite loops caused by circular
     replication.  If set to 1, the slave does not skip events having
     its own server ID. Normally, this is useful only in rare
     configurations.  Cannot be set to 1 if '--log-slave-updates' is
     used.  By default, the slave I/O thread does not write binary log
     events to the relay log if they have the slave's server ID (this
     optimization helps save disk usage).  If you want to use
     '--replicate-same-server-id', be sure to start the slave with this
     option before you make the slave read its own events that you want
     the slave SQL thread to execute.

   *
     '--replicate-wild-do-table=DB_NAME.TBL_NAME'

     Property                             Value

     *Command-Line Format*                '--replicate-wild-do-table=name'

     *Type*                               string

     Creates a replication filter by telling the slave thread to
     restrict replication to statements where any of the updated tables
     match the specified database and table name patterns.  Patterns can
     contain the '%' and '_' wildcard characters, which have the same
     meaning as for the 'LIKE' pattern-matching operator.  To specify
     more than one table, use this option multiple times, once for each
     table.  This works for cross-database updates.  See
     replication-rules.  You can also create such a filter by issuing
     a 'CHANGE REPLICATION FILTER REPLICATE_WILD_DO_TABLE'
     statement.

     This option applies to tables, views, and triggers.  It does not
     apply to stored procedures and functions, or events.  To filter
     statements operating on the latter objects, use one or more of the
     '--replicate-*-db' options.

     Example: '--replicate-wild-do-table=foo%.bar%' replicates only
     updates that use a table where the database name starts with 'foo'
     and the table name starts with 'bar'.

     If the table name pattern is '%', it matches any table name and the
     option also applies to database-level statements (see 'CREATE DATABASE',
     see 'DROP DATABASE',
     and 'ALTER DATABASE').  For example, if you
     use '--replicate-wild-do-table=foo%.%', database-level statements
     are replicated if the database name matches the pattern 'foo%'.

     To include literal wildcard characters in the database or table
     name patterns, escape them with a backslash.  For example, to
     replicate all tables of a database that is named 'my_own%db', but
     not replicate tables from the 'my1ownAABCdb' database, you should
     escape the '_' and '%' characters like this:
     '--replicate-wild-do-table=my\_own\%db'.  If you use the option on
     the command line, you might need to double the backslashes or quote
     the option value, depending on your command interpreter.  For
     example, with the 'bash' shell, you would need to type
     '--replicate-wild-do-table=my\\_own\\%db'.

   *
     '--replicate-wild-ignore-table=DB_NAME.TBL_NAME'

     Property                             Value

     *Command-Line Format*                '--replicate-wild-ignore-table=name'

     *Type*                               string

     Creates a replication filter which keeps the slave thread from
     replicating a statement in which any table matches the given
     wildcard pattern.  To specify more than one table to ignore, use
     this option multiple times, once for each table.  This works for
     cross-database updates.  See replication-rules.  You can
     also create such a filter by issuing a 'CHANGE REPLICATION FILTER REPLICATE_WILD_IGNORE_TABLE'.
     statement.

     Example: '--replicate-wild-ignore-table=foo%.bar%' does not
     replicate updates that use a table where the database name starts
     with 'foo' and the table name starts with 'bar'.

     For information about how matching works, see the description of
     the '--replicate-wild-do-table' option.  The rules for including
     literal wildcard characters in the option value are the same as for
     '--replicate-wild-ignore-table' as well.

   *
     '--report-host=HOST_NAME'

     Property                             Value

     *Command-Line Format*                '--report-host=host_name'

     *System Variable*                    'report_host'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The host name or IP address of the slave to be reported to the
     master during slave registration.  This value appears in the output
     of 'SHOW SLAVE HOSTS' on the master
     server.  Leave the value unset if you do not want the slave to
     register itself with the master.

     *Note*:

     It is not sufficient for the master to simply read the IP address
     of the slave from the TCP/IP socket after the slave connects.  Due
     to NAT and other routing issues, that IP may not be valid for
     connecting to the slave from the master or other hosts.

   *
     '--report-password=PASSWORD'

     Property                             Value

     *Command-Line Format*                '--report-password=name'

     *System Variable*                    'report_password'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The account password of the slave to be reported to the master
     during slave registration.  This value appears in the output of
     'SHOW SLAVE HOSTS' on the master server if
     the master was started with '--show-slave-auth-info'.

     Although the name of this option might imply otherwise,
     '--report-password' is not connected to the MySQL user privilege
     system and so is not necessarily (or even likely to be) the same as
     the password for the MySQL replication user account.

   *
     '--report-port=SLAVE_PORT_NUM'

     Property                             Value

     *Command-Line Format*                '--report-port=#'

     *System Variable*                    'report_port'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '[slave_port]'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     The TCP/IP port number for connecting to the slave, to be reported
     to the master during slave registration.  Set this only if the
     slave is listening on a nondefault port or if you have a special
     tunnel from the master or other clients to the slave.  If you are
     not sure, do not use this option.

     The default value for this option is the port number actually used
     by the slave (Bug #13333431).  This is also the default value
     displayed by 'SHOW SLAVE HOSTS'.

   *
     '--report-user=USER_NAME'

     Property                             Value

     *Command-Line Format*                '--report-user=name'

     *System Variable*                    'report_user'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     The account user name of the slave to be reported to the master
     during slave registration.  This value appears in the output of
     'SHOW SLAVE HOSTS' on the master server if
     the master was started with '--show-slave-auth-info'.

     Although the name of this option might imply otherwise,
     '--report-user' is not connected to the MySQL user privilege system
     and so is not necessarily (or even likely to be) the same as the
     name of the MySQL replication user account.

   *
     '--slave-checkpoint-group=#'

     Property                             Value

     *Command-Line Format*                '--slave-checkpoint-group=#'

     *Type*                               integer

     *Default Value*                      '512'

     *Minimum Value*                      '32'

     *Maximum Value*                      '524280'

     *Block Size*                         '8'

     Sets the maximum number of transactions that can be processed by a
     multi-threaded slave before a checkpoint operation is called to
     update its status as shown by 'SHOW SLAVE STATUS'.
     Setting this option has no effect on slaves for
     which multi-threading is not enabled.

     *Note*:

     Multi-threaded slaves are not currently supported by NDB Cluster,
     which silently ignores the setting for this option.  See
     mysql-cluster-replication-issues, for more information.

     This option works in combination with the
     '--slave-checkpoint-period' option in such a way that, when either
     limit is exceeded, the checkpoint is executed and the counters
     tracking both the number of transactions and the time elapsed since
     the last checkpoint are reset.

     The minimum allowed value for this option is 32, unless the server
     was built using '-DWITH_DEBUG', in which case the minimum value is
     1.  The effective value is always a multiple of 8; you can set it
     to a value that is not such a multiple, but the server rounds it
     down to the next lower multiple of 8 before storing the value.
     (_Exception_: No such rounding is performed by the debug server.)
     Regardless of how the server was built, the default value is 512,
     and the maximum allowed value is 524280.

   *
     '--slave-checkpoint-period=#'

     Property                             Value

     *Command-Line Format*                '--slave-checkpoint-period=#'

     *Type*                               integer

     *Default Value*                      '300'

     *Minimum Value*                      '1'

     *Maximum Value*                      '4G'

     Sets the maximum time (in milliseconds) that is allowed to pass
     before a checkpoint operation is called to update the status of a
     multi-threaded slave as shown by 'SHOW SLAVE STATUS'.
     Setting this option has no effect on slaves for
     which multi-threading is not enabled.

     *Note*:

     Multi-threaded slaves are not currently supported by NDB Cluster,
     which silently ignores the setting for this option.  See
     mysql-cluster-replication-issues, for more information.

     This option works in combination with the
     '--slave-checkpoint-group' option in such a way that, when either
     limit is exceeded, the checkpoint is executed and the counters
     tracking both the number of transactions and the time elapsed since
     the last checkpoint are reset.

     The minimum allowed value for this option is 1, unless the server
     was built using '-DWITH_DEBUG', in which case the minimum value is
     0.  Regardless of how the server was built, the default value is
     300, and the maximum possible value is 4294967296 (4GB).

   *
     '--slave-parallel-workers'

     Property                             Value

     *Command-Line Format*                '--slave-parallel-workers=#'

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1024'

     Sets the number of slave applier threads for executing replication
     transactions in parallel.  Setting this variable to a number
     greater than 0 creates a multi-threaded slave with this number of
     applier threads.  When set to 0 (the default) parallel execution is
     disabled and the slave uses a single applier thread.

     A multi-threaded slave provides parallel execution by using a
     coordinator thread and the number of applier threads configured by
     this option.  The way which transactions are distributed among
     applier threads is configured by '--slave-parallel-type'.  For more
     information about multi-threaded slaves see
     'slave-parallel-workers'.

     *Note*:

     Multi-threaded slaves are not currently supported by NDB Cluster,
     which silently ignores the setting for this option.  See
     mysql-cluster-replication-issues, for more information.

   *
     '--slave-pending-jobs-size-max=#'

     Property                             Value

     *Command-Line Format*                '--slave-pending-jobs-size-max=#'

     *Type*                               integer

     *Default Value*                      '16M'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '18EB'

     *Block Size*                         '1024'

     For multi-threaded slaves, this option sets the maximum amount of
     memory (in bytes) available to slave worker queues holding events
     not yet applied.  Setting this option has no effect on slaves for
     which multi-threading is not enabled.

     The minimum possible value for this option is 1024; the default is
     16MB. The maximum possible value is 18446744073709551615 (16
     exabytes).  Values that are not exact multiples of 1024 are rounded
     down to the next-highest multiple of 1024 prior to being stored.

     *Important*:

     The value for this option must not be less than the master's value
     for 'max_allowed_packet'; otherwise a slave worker queue may become
     full while there remain events coming from the master to be
     processed.

   *
     '--skip-slave-start'

     Property                             Value

     *Command-Line Format*                '--skip-slave-start'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Tells the slave server not to start the slave threads when the
     server starts.  To start the threads later, use a 'START SLAVE'
     statement.

   *
     '--slave_compressed_protocol={0|1}'

     Property                             Value

     *Command-Line Format*                '--slave-compressed-protocol'

     *System Variable*                    'slave_compressed_protocol'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     If this option is set to 1, use compression for the slave/master
     protocol if both the slave and the master support it.  The default
     is 0 (no compression).

   *
     '--slave-load-tmpdir=DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--slave-load-tmpdir=dir_name'

     *System Variable*                    'slave_load_tmpdir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     *Default Value*                      '/tmp'

     The name of the directory where the slave creates temporary files.
     This option is by default equal to the value of the 'tmpdir' system
     variable.  When the slave SQL thread replicates a 'LOAD DATA INFILE'
     statement, it extracts the file to be loaded
     from the relay log into temporary files, and then loads these into
     the table.  If the file loaded on the master is huge, the temporary
     files on the slave are huge, too.  Therefore, it might be advisable
     to use this option to tell the slave to put temporary files in a
     directory located in some file system that has a lot of available
     space.  In that case, the relay logs are huge as well, so you might
     also want to use the '--relay-log' option to place the relay logs
     in that file system.

     The directory specified by this option should be located in a
     disk-based file system (not a memory-based file system) because the
     temporary files used to replicate 'LOAD DATA INFILE'
     must survive machine restarts.  The directory also
     should not be one that is cleared by the operating system during
     the system startup process.

   *
     'slave-max-allowed-packet=BYTES'

     Property                             Value

     *Command-Line Format*                '--slave-max-allowed-packet=#'

     *Type*                               integer

     *Default Value*                      '1073741824'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '1073741824'

     This option sets the maximum packet size in bytes for the slave SQL
     and I/O threads, so that large updates using row-based replication
     do not cause replication to fail because an update exceeded
     'max_allowed_packet'.  (Bug #12400221, Bug #60926)

     The corresponding server variable 'slave_max_allowed_packet' always
     has a value that is a positive integer multiple of 1024; if you set
     it to some value that is not such a multiple, the value is
     automatically rounded down to the next highest multiple of 1024.
     (For example, if you start the server with
     '--slave-max-allowed-packet=10000', the value used is 9216; setting
     0 as the value causes 1024 to be used.)  A truncation warning is
     issued in such cases.

     The maximum (and default) value is 1073741824 (1 GB); the minimum
     is 1024.

   *
     '--slave-net-timeout=SECONDS'

     Property                             Value

     *Command-Line Format*                '--slave-net-timeout=#'

     *System Variable*                    'slave_net_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value* (>= 5.7.7)           '60'

     *Default Value* (<= 5.7.6)           '3600'

     *Minimum Value*                      '1'

     The number of seconds to wait for more data from the master before
     the slave considers the connection broken, aborts the read, and
     tries to reconnect.  The first retry occurs immediately after the
     timeout.  The interval between retries is controlled by the
     'MASTER_CONNECT_RETRY' option for the 'CHANGE MASTER TO'
     statement, and the number of reconnection
     attempts is limited by the '--master-retry-count' option.  Prior to
     MySQL 5.7.7, the default was 3600 seconds (one hour).  In MySQL
     5.7.7 and later the default is 60 seconds (one minute).

   *
     '--slave-parallel-type=TYPE'

     Property                             Value

     *Command-Line Format*                '--slave-parallel-type=type'

     *Introduced*                         5.7.2

     *Type*                               enumeration

     *Default Value*                      'DATABASE'

     *Valid Values*                       'DATABASE' 'LOGICAL_CLOCK'

     When using a multi-threaded slave ('slave_parallel_workers' is
     greater than 0), this option specifies the policy used to decide
     which transactions are allowed to execute in parallel on the slave.
     The possible values are:

        * 'DATABASE': Transactions that update different databases are
          applied in parallel.  This value is only appropriate if data
          is partitioned into multiple databases which are being updated
          independently and concurrently on the master.  Only
          recommended if there are no cross-database constraints, as
          such constraints may be violated on the slave.

        * 'LOGICAL_CLOCK': Transactions that are part of the same binary
          log group commit on a master are applied in parallel on a
          slave.  There are no cross-database constraints, and data does
          not need to be partitioned into multiple databases.

     Regardless of the value of this variable, there is no special
     configuration required on the master.  When
     'slave_preserve_commit_order=1', you can only use 'LOGICAL_CLOCK'.
     If your replication topology uses multiple levels of slaves,
     'LOGICAL_CLOCK' may achieve less parallelization for each level the
     slave is away from the master.

   *
     'slave-rows-search-algorithms=LIST'

     Property                             Value

     *Command-Line Format*                '--slave-rows-search-algorithms=list'

     *Type*                               set

     *Default Value*                      'TABLE_SCAN,INDEX_SCAN'

     *Valid Values*                       'TABLE_SCAN,INDEX_SCAN'
                                          'INDEX_SCAN,HASH_SCAN'
                                          'TABLE_SCAN,HASH_SCAN'
                                          'TABLE_SCAN,INDEX_SCAN,HASH_SCAN'
                                          (equivalent to
                                          INDEX_SCAN,HASH_SCAN)

     When preparing batches of rows for row-based logging and
     replication, this option controls how the rows are searched for
     matches--that is, whether or not hashing is used for searches using
     a primary or unique key, some other key, or no key at all.  The
     option sets the initial value for the
     'slave_rows_search_algorithms' system variable.

     Specify a comma-separated list of any 2 (or all 3) values from the
     list 'INDEX_SCAN', 'TABLE_SCAN', 'HASH_SCAN'.  The list need not be
     quoted, but must contain no spaces, whether or not quotes are used.
     Possible combinations (lists) and their effects are shown in the
     following table:

     Index used /       'INDEX_SCAN,HASH_SCAN''INDEX_SCAN,TABLE_SCAN''TABLE_SCAN,HASH_SCAN'
     option value       or
                        'INDEX_SCAN,TABLE_SCAN,HASH_SCAN'

     _Primary key or    Index scan         Index scan         Hash scan over
     unique key_                                              index

     _(Other) Key_      Hash scan over     Index scan         Hash scan over
                        index                                 index

     _No index_         Hash scan          Table scan         Hash scan

     The order in which the algorithms are specified in the list does
     not make any difference in the order in which they are displayed by
     a 'SELECT' or 'SHOW VARIABLES'
     statement (which is the same as that used in the
     table just shown previously).

        * The default value is 'TABLE_SCAN,INDEX_SCAN', which means that
          all searches that can use indexes do use them, and searches
          without any indexes use table scans.

        * To use hashing for any searches that do not use a primary or
          unique key, set this option to 'INDEX_SCAN,HASH_SCAN'.
          Specifying 'INDEX_SCAN,TABLE_SCAN,HASH_SCAN' has the same
          effect as specifying 'INDEX_SCAN,HASH_SCAN'.

        * To force hashing for _all_ searches, set this option to
          'TABLE_SCAN,HASH_SCAN'.

     It is possible to specify single values for this option, but this
     is not optimal, because setting a single value limits searches to
     using only that algorithm.  In particular, setting 'INDEX_SCAN'
     alone is not recommended, as in that case searches are unable to
     find rows at all if no index is present.

     *Note*:

     There is only a performance advantage for 'INDEX_SCAN' and
     'HASH_SCAN' if the row events are big enough.  The size of row
     events is configured using '--binlog-row-event-max-size'.  For
     example, suppose a 'DELETE' statement which deletes
     25,000 rows generates large 'Delete_row_event' events.  In this
     case if 'slave_rows_search_algorithms' is set to 'INDEX_SCAN' or
     'HASH_SCAN' there is a performance improvement.  However, if there
     are 25,000 'DELETE' statements and each is
     represented by a separate event then setting
     'slave_rows_search_algorithms' to 'INDEX_SCAN' or 'HASH_SCAN'
     provides no performance improvement while executing these separate
     events.

   *
     '--slave-skip-errors=[ERR_CODE1,ERR_CODE2,...|all|ddl_exist_errors]'

     Property                             Value

     *Command-Line Format*                '--slave-skip-errors=name'

     *System Variable*                    'slave_skip_errors'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'OFF'

     *Valid Values*                       'OFF' '[list of error codes]'
                                          'all' 'ddl_exist_errors'

     Normally, replication stops when an error occurs on the slave,
     which gives you the opportunity to resolve the inconsistency in the
     data manually.  This option causes the slave SQL thread to continue
     replication when a statement returns any of the errors listed in
     the option value.

     Do not use this option unless you fully understand why you are
     getting errors.  If there are no bugs in your replication setup and
     client programs, and no bugs in MySQL itself, an error that stops
     replication should never occur.  Indiscriminate use of this option
     results in slaves becoming hopelessly out of synchrony with the
     master, with you having no idea why this has occurred.

     For error codes, you should use the numbers provided by the error
     message in your slave error log and in the output of 'SHOW SLAVE STATUS'.
     See error-handling, lists
     server error codes.

     The shorthand value 'ddl_exist_errors' is equivalent to the error
     code list '1007,1008,1050,1051,1054,1060,1061,1068,1094,1146'.

     You can also (but should not) use the very nonrecommended value of
     'all' to cause the slave to ignore all error messages and keeps
     going regardless of what happens.  Needless to say, if you use
     'all', there are no guarantees regarding the integrity of your
     data.  Please do not complain (or file bug reports) in this case if
     the slave's data is not anywhere close to what it is on the master.
     _You have been warned_.

     Examples:

          --slave-skip-errors=1062,1053
          --slave-skip-errors=all
          --slave-skip-errors=ddl_exist_errors

   *
     '--slave-sql-verify-checksum={0|1}'

     Property                             Value

     *Command-Line Format*                '--slave-sql-verify-checksum=value'

     *Type*                               boolean

     *Default Value*                      '1'

     *Valid Values*                       '0' '1'

     When this option is enabled, the slave examines checksums read from
     the relay log, in the event of a mismatch, the slave stops with an
     error.

The following options are used internally by the MySQL test suite for
replication testing and debugging.  They are not intended for use in a
production setting.

   *
     '--abort-slave-event-count'

     Property                             Value

     *Command-Line Format*                '--abort-slave-event-count=#'

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     When this option is set to some positive integer VALUE other than 0
     (the default) it affects replication behavior as follows: After the
     slave SQL thread has started, VALUE log events are permitted to be
     executed; after that, the slave SQL thread does not receive any
     more events, just as if the network connection from the master were
     cut.  The slave thread continues to run, and the output from
     'SHOW SLAVE STATUS' displays 'Yes' in both the
     'Slave_IO_Running' and the 'Slave_SQL_Running' columns, but no
     further events are read from the relay log.

   *
     '--disconnect-slave-event-count'

     Property                             Value

     *Command-Line Format*                '--disconnect-slave-event-count=#'

     *Type*                               integer

     *Default Value*                      '0'

*Options for Logging Slave Status to Tables*

MySQL 5.7 supports logging of replication slave status information to
tables rather than files.  Writing of the master info log and the relay
log info log can be configured separately using the two server options
listed here:

   *
     '--master-info-repository={FILE|TABLE}'

     Property                             Value

     *Command-Line Format*                '--master-info-repository=FILE|TABLE'

     *Type*                               string

     *Default Value*                      'FILE'

     *Valid Values*                       'FILE' 'TABLE'

     This option causes the server to write its master info log to a
     file or a table.  The name of the file defaults to 'master.info';
     you can change the name of the file using the '--master-info-file'
     server option.

     The default value for this option is 'FILE'.  If you use 'TABLE',
     the log is written to the 'slave_master_info' table in the 'mysql'
     database.

   *
     '--relay-log-info-repository={FILE|TABLE}'

     Property                             Value

     *Command-Line Format*                '--relay-log-info-repository=FILE|TABLE'

     *Type*                               string

     *Default Value*                      'FILE'

     *Valid Values*                       'FILE' 'TABLE'

     This option causes the server to log its relay log info to a file
     or a table.  The name of the file defaults to 'relay-log.info'; you
     can change the name of the file using the '--relay-log-info-file'
     server option.

     The default value for this option is 'FILE'.  If you use 'TABLE',
     the log is written to the 'slave_relay_log_info' table in the
     'mysql' database.

These options can be used to make replication slaves resilient to
unexpected halts.  See
replication-solutions-unexpected-slave-halt, for more information.

The info log tables and their contents are considered local to a given
MySQL Server.  They are not replicated, and changes to them are not
written to the binary log.

For more information, see slave-logs.

*System Variables Used on Replication Slaves*

The following list describes system variables for controlling
replication slave servers.  They can be set at server startup and some
of them can be changed at runtime using 'SET'.
Server options used with replication slaves are listed earlier in this
section.

   *
     'init_slave'

     Property                             Value

     *Command-Line Format*                '--init-slave=name'

     *System Variable*                    'init_slave'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     This variable is similar to 'init_connect', but is a string to be
     executed by a slave server each time the SQL thread starts.  The
     format of the string is the same as for the 'init_connect'
     variable.  The setting of this variable takes effect for subsequent
     'START SLAVE' statements.

     *Note*:

     The SQL thread sends an acknowledgment to the client before it
     executes 'init_slave'.  Therefore, it is not guaranteed that
     'init_slave' has been executed when 'START SLAVE'
     returns.  See start-slave, for more
     information.

   *
     'log_slow_slave_statements'

     Property                             Value

     *Introduced*                         5.7.1

     *System Variable*                    'log_slow_slave_statements'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     When the slow query log is enabled, this variable enables logging
     for queries that have taken more than 'long_query_time' seconds to
     execute on the slave.  This variable was added in MySQL 5.7.1.
     Setting this variable has no immediate effect.  The state of the
     variable applies on all subsequent 'START SLAVE'
     statements.

     Note that all statements logged in row format in the master will
     not be logged in the slave's slow log, even if
     'log_slow_slave_statements' is enabled.

   *
     'master_info_repository'

     Property                             Value

     *Command-Line Format*                '--master-info-repository=FILE|TABLE'

     *System Variable*                    'master_info_repository'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'FILE'

     *Valid Values*                       'FILE' 'TABLE'

     The setting of this variable determines whether the slave logs
     master status and connection information to a 'FILE'
     ('master.info'), or to a 'TABLE' ('mysql.slave_master_info').  You
     can only change the value of this variable when no replication
     threads are executing.

     The setting of this variable also has a direct influence on the
     effect had by the setting of the 'sync_master_info' system
     variable; see that variable's description for further information.

     This variable must be set to 'TABLE' before configuring multiple
     replication channels.  If you are using multiple replication
     channels then you cannot set this variable back to 'FILE'.

   *
     'relay_log'

     Property                             Value

     *Command-Line Format*                '--relay-log=file_name'

     *System Variable*                    'relay_log'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The base name for relay log files, with no paths and no file
     extension.  For the default replication channel, the default base
     name for relay logs is 'HOST_NAME-relay-bin'.  For non-default
     replication channels, the default base name for relay logs is
     'HOST_NAME-relay-bin-CHANNEL', where CHANNEL is the name of the
     replication channel recorded in this relay log.

   *
     'relay_log_basename'

     Property                             Value

     *System Variable*                    'relay_log_basename'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'datadir + '/' + hostname +
                                          '-relay-bin''

     Holds the name and complete path to the relay log file.

   *
     'relay_log_index'

     Property                             Value

     *Command-Line Format*                '--relay-log-index'

     *System Variable*                    'relay_log_index'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      '*host_name*-relay-bin.index'

     The name of the relay log index file for the default replication
     channel.  The default name is 'HOST_NAME-relay-bin.index'.

   *
     'relay_log_info_file'

     Property                             Value

     *Command-Line Format*                '--relay-log-info-file=file_name'

     *System Variable*                    'relay_log_info_file'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     *Default Value*                      'relay-log.info'

     The name of the file in which the slave records information about
     the relay logs, when 'relay_log_info_repository=FILE'.  If
     'relay_log_info_repository=TABLE', it is the file name that would
     be used in case the repository was changed to 'FILE').  The default
     name is 'relay-log.info' in the data directory.

   *
     'relay_log_info_repository'

     Property                             Value

     *System Variable*                    'relay_log_info_repository'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'FILE'

     *Valid Values*                       'FILE' 'TABLE'

     This variable determines whether the slave's position in the relay
     logs is written to a 'FILE' ('relay-log.info') or to a 'TABLE'
     ('mysql.slave_relay_log_info').  You can only change the value of
     this variable when no replication threads are executing.

     The setting of this variable also has a direct influence on the
     effect had by the setting of the 'sync_relay_log_info' system
     variable; see that variable's description for further information.

     This variable must be set to 'TABLE' before configuring multiple
     replication channels.  If you are using multiple replication
     channels then you cannot set this variable back to 'FILE'.

   *
     'relay_log_recovery'

     Property                             Value

     *Command-Line Format*                '--relay-log-recovery'

     *System Variable*                    'relay_log_recovery'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Enables automatic relay log recovery immediately following server
     startup.  The recovery process creates a new relay log file,
     initializes the SQL thread position to this new relay log, and
     initializes the I/O thread to the SQL thread position.  Reading of
     the relay log from the master then continues.  This global variable
     is read-only; its value can be changed by starting the slave with
     the '--relay-log-recovery' option, which should be used following
     an unexpected halt of a replication slave to ensure that no
     possibly corrupted relay logs are processed.  See
     replication-solutions-unexpected-slave-halt for more information.

     This variable also interacts with 'relay-log-purge', which controls
     purging of logs when they are no longer needed.  Enabling the
     '--relay-log-recovery' option when 'relay-log-purge' is disabled
     risks reading the relay log from files that were not purged,
     leading to data inconsistency.

     When 'relay_log_recovery' is enabled and the slave has stopped due
     to errors encountered while running in multi-threaded mode, you can
     use 'START SLAVE UNTIL SQL_AFTER_MTS_GAPS' to
     ensure that all gaps are processed before switching back to
     single-threaded mode or executing a 'CHANGE MASTER TO' statement.

   *
     'rpl_stop_slave_timeout'

     Property                             Value

     *Command-Line Format*                '--rpl-stop-slave-timeout=seconds'

     *Introduced*                         5.7.2

     *System Variable*                    'rpl_stop_slave_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '31536000'

     *Minimum Value*                      '2'

     *Maximum Value*                      '31536000'

     You can control the length of time (in seconds) that 'STOP SLAVE'
     waits before timing out by setting this
     variable.  This can be used to avoid deadlocks between 'STOP SLAVE'
     and other slave SQL statements using different client connections
     to the slave.

     The maximum and default value of 'rpl_stop_slave_timeout' is
     31536000 seconds (1 year).  The minimum is 2 seconds.  Changes to
     this variable take effect for subsequent 'STOP SLAVE'
     statements.

     This variable affects only the client that issues a 'STOP SLAVE'
     statement.  When the timeout is reached, the issuing client returns
     an error message stating that the command execution is incomplete.
     The client then stops waiting for the slave threads to stop, but
     the slave threads continue to try to stop, and the 'STOP SLAVE'
     instruction remains in effect.  Once the slave threads are no
     longer busy, the 'STOP SLAVE' statement is executed and the slave
     stops.

   *
     'slave_checkpoint_group'

     Property                             Value

     *Command-Line Format*                '--slave-checkpoint-group=#'

     *System Variable*                    'slave_checkpoint_group=#'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '512'

     *Minimum Value*                      '32'

     *Maximum Value*                      '524280'

     *Block Size*                         '8'

     Sets the maximum number of transactions that can be processed by a
     multi-threaded slave before a checkpoint operation is called to
     update its status as shown by 'SHOW SLAVE STATUS'.
     Setting this variable has no effect on slaves
     for which multi-threading is not enabled.  Setting this variable
     has no immediate effect.  The state of the variable applies on all
     subsequent 'START SLAVE' commands.

     *Note*:

     Multi-threaded slaves are not currently supported by NDB Cluster,
     which silently ignores the setting for this variable.  See
     mysql-cluster-replication-issues, for more information.

     This variable works in combination with the
     'slave_checkpoint_period' system variable in such a way that, when
     either limit is exceeded, the checkpoint is executed and the
     counters tracking both the number of transactions and the time
     elapsed since the last checkpoint are reset.

     The minimum allowed value for this variable is 32, unless the
     server was built using '-DWITH_DEBUG', in which case the minimum
     value is 1.  The effective value is always a multiple of 8; you can
     set it to a value that is not such a multiple, but the server
     rounds it down to the next lower multiple of 8 before storing the
     value.  (_Exception_: No such rounding is performed by the debug
     server.)  Regardless of how the server was built, the default value
     is 512, and the maximum allowed value is 524280.

   *
     'slave_checkpoint_period'

     Property                             Value

     *Command-Line Format*                '--slave-checkpoint-period=#'

     *System Variable*                    'slave_checkpoint_period=#'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '300'

     *Minimum Value*                      '1'

     *Maximum Value*                      '4G'

     Sets the maximum time (in milliseconds) that is allowed to pass
     before a checkpoint operation is called to update the status of a
     multi-threaded slave as shown by 'SHOW SLAVE STATUS'.
     Setting this variable has no effect on slaves
     for which multi-threading is not enabled.  Setting this variable
     takes effect for all replication channels immediately, including
     running channels.

     *Note*:

     Multi-threaded slaves are not currently supported by NDB Cluster,
     which silently ignores the setting for this variable.  See
     mysql-cluster-replication-issues, for more information.

     This variable works in combination with the
     'slave_checkpoint_group' system variable in such a way that, when
     either limit is exceeded, the checkpoint is executed and the
     counters tracking both the number of transactions and the time
     elapsed since the last checkpoint are reset.

     The minimum allowed value for this variable is 1, unless the server
     was built using '-DWITH_DEBUG', in which case the minimum value is
     0.  Regardless of how the server was built, the default value is
     300, and the maximum possible value is 4294967296 (4GB).

   *
     'slave_compressed_protocol'

     Property                             Value

     *Command-Line Format*                '--slave-compressed-protocol'

     *System Variable*                    'slave_compressed_protocol'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether to use compression of the slave/master protocol if both the
     slave and the master support it.  Changes to this variable take
     effect on subsequent connection attempts; this includes after
     issuing a 'START SLAVE ' statement, as well as
     reconnections made by a running I/O thread (for example after
     issuing a 'CHANGE MASTER TO MASTER_RETRY_COUNT' statement).

   *
     'slave_exec_mode'

     Property                             Value

     *Command-Line Format*                '--slave-exec-mode=mode'

     *System Variable*                    'slave_exec_mode'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'IDEMPOTENT' (NDB) 'STRICT'
                                          (Other)

     *Valid Values*                       'IDEMPOTENT' 'STRICT'

     Controls how a slave thread resolves conflicts and errors during
     replication.  'IDEMPOTENT' mode causes suppression of duplicate-key
     and no-key-found errors; 'STRICT' means no such suppression takes
     place.

     'IDEMPOTENT' mode is intended for use in multi-master replication,
     circular replication, and some other special replication scenarios
     for NDB Cluster Replication.  (See
     mysql-cluster-replication-multi-master, and
     mysql-cluster-replication-conflict-resolution, for more
     information.)  NDB Cluster ignores any value explicitly set for
     'slave_exec_mode', and always treats it as 'IDEMPOTENT'.

     In MySQL Server 5.7, 'STRICT' mode is the default value.

     For storage engines other than 'NDB',
     _'IDEMPOTENT' mode should be used only when you are absolutely sure
     that duplicate-key errors and key-not-found errors can safely be
     ignored_.  It is meant to be used in fail-over scenarios for NDB
     Cluster where multi-master replication or circular replication is
     employed, and is not recommended for use in other cases.

   *
     'slave_load_tmpdir'

     Property                             Value

     *Command-Line Format*                '--slave-load-tmpdir=dir_name'

     *System Variable*                    'slave_load_tmpdir'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     *Default Value*                      '/tmp'

     The name of the directory where the slave creates temporary files
     for replicating 'LOAD DATA INFILE' statements.
     Setting this variable takes effect for all replication channels
     immediately, including running channels.

   *
     'slave_max_allowed_packet'

     Property                             Value

     *System Variable*                    'slave_max_allowed_packet'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1073741824'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '1073741824'

     This variable sets the maximum packet size for the slave SQL and
     I/O threads, so that large updates using row-based replication do
     not cause replication to fail because an update exceeded
     'max_allowed_packet'.  Setting this variable takes effect for all
     replication channels immediately, including running channels.

     This global variable always has a value that is a positive integer
     multiple of 1024; if you set it to some value that is not, the
     value is rounded down to the next highest multiple of 1024 for it
     is stored or used; setting 'slave_max_allowed_packet' to 0 causes
     1024 to be used.  (A truncation warning is issued in all such
     cases.)  The default and maximum value is 1073741824 (1 GB); the
     minimum is 1024.

     'slave_max_allowed_packet' can also be set at startup, using the
     '--slave-max-allowed-packet' option.

   *
     'slave_net_timeout'

     Property                             Value

     *Command-Line Format*                '--slave-net-timeout=#'

     *System Variable*                    'slave_net_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value* (>= 5.7.7)           '60'

     *Default Value* (<= 5.7.6)           '3600'

     *Minimum Value*                      '1'

     The number of seconds to wait for more data from a master/slave
     connection before aborting the read.  Setting this variable has no
     immediate effect.  The state of the variable applies on all
     subsequent 'START SLAVE' commands.

   *
     'slave_parallel_type=TYPE'

     Property                             Value

     *Command-Line Format*                '--slave-parallel-type=type'

     *Introduced*                         5.7.2

     *Type*                               enumeration

     *Default Value*                      'DATABASE'

     *Valid Values*                       'DATABASE' 'LOGICAL_CLOCK'

     When using a multi-threaded slave ('slave_parallel_workers' is
     greater than 0), this variable specifies the policy used to decide
     which transactions are allowed to execute in parallel on the slave.
     See '--slave-parallel-type' for more information.

   *
     'slave_parallel_workers'

     Property                             Value

     *Command-Line Format*                '--slave-parallel-workers=#'

     *System Variable*                    'slave_parallel_workers'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1024'

     Sets the number of slave applier threads for executing replication
     transactions in parallel.  Setting this variable to a number
     greater than 0 creates a multi-threaded slave with this number of
     applier threads.  When set to 0 (the default) parallel execution is
     disabled and the slave uses a single applier thread.  Setting
     'slave_parallel_workers' has no immediate effect.  The state of the
     variable applies on all subsequent 'START SLAVE'
     statements.

     *Note*:

     Multi-threaded slaves are not currently supported by NDB Cluster,
     which silently ignores the setting for this variable.  See
     mysql-cluster-replication-issues, for more information.

     A multi-threaded slave provides parallel execution by using a
     coordinator thread and the number of applier threads configured by
     this variable.  The way which transactions are distributed among
     applier threads is configured by 'slave_parallel_type'.  The
     transactions that the slave applies in parallel may commit out of
     order, unless 'slave_preserve_commit_order=1'.  Therefore, checking
     for the most recently executed transaction does not guarantee that
     all previous transactions from the master have been executed on the
     slave.  This has implications for logging and recovery when using a
     multi-threaded slave.  For example, on a multi-threaded slave the
     'START SLAVE UNTIL' statement only supports
     using 'SQL_AFTER_MTS_GAPS'.

     In MySQL 5.7.5 and later, retrying of transactions is supported
     when multi-threading is enabled on a slave.  In previous versions,
     'slave_transaction_retries' was treated as equal to 0 when using
     multi-threaded slaves.

   *
     'slave_pending_jobs_size_max'

     Property                             Value

     *System Variable*                    'slave_pending_jobs_size_max'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '16M'

     *Minimum Value*                      '1024'

     *Maximum Value*                      '18EB'

     *Block Size*                         '1024'

     For multi-threaded slaves, this variable sets the maximum amount of
     memory (in bytes) available to slave worker queues holding events
     not yet applied.  Setting this variable has no effect on slaves for
     which multi-threading is not enabled.  Setting this variable has no
     immediate effect.  The state of the variable applies on all
     subsequent 'START SLAVE' commands.

     The minimum possible value for this variable is 1024; the default
     is 16MB. The maximum possible value is 18446744073709551615 (16
     exabytes).  Values that are not exact multiples of 1024 are rounded
     down to the next-highest multiple of 1024 prior to being stored.

     *Important*:

     The value of this variable must not be less than the master's value
     for 'max_allowed_packet'; otherwise a slave worker queue may become
     full while there remain events coming from the master to be
     processed.

   *
     'slave_preserve_commit_order'

     Property                             Value

     *Command-Line Format*                '--slave-preserve-commit-order=value'

     *Introduced*                         5.7.5

     *System Variable*                    'slave_preserve_commit_order'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '0'

     *Valid Values*                       '0' '1'

     For multi-threaded slaves, enabling this variable ensures that
     transactions are externalized on the slave in the same order as
     they appear in the slave's relay log.  Setting this variable has no
     effect on slaves for which multi-threading is not enabled.  All
     replication threads (for all replication channels if you are using
     multiple replication channels) must be stopped before changing this
     variable.  '--log-bin' and '--log-slave-updates' must be enabled on
     the slave.  In addition '--slave-parallel-type' must be set to
     'LOGICAL_CLOCK'.

     Once a multi-threaded slave has been started, transactions can
     begin to execute in parallel.  With 'slave_preserve_commit_order'
     enabled, the executing thread waits until all previous transactions
     are committed before committing.  While the slave thread is waiting
     for other workers to commit their transactions it reports its
     status as 'Waiting for preceding transaction to commit'.  (Prior to
     MySQL 5.7.8, this was shown as 'Waiting for its turn to commit'.)
     Enabling this mode on a multi-threaded slave ensures that it never
     enters a state that the master was not in.  This makes it well
     suited to using replication for read scale-out.  See
     replication-solutions-scaleout.

     When using a multi-threaded slave, if 'slave_preserve_commit_order'
     is not enabled, there is a chance of gaps in the sequence of
     transactions that have been executed from the slave's relay log.
     When this option is enabled, there is not this chance of gaps, but
     'Exec_master_log_pos' may be behind the position up to which has
     been executed.  See
     replication-features-transaction-inconsistencies for more
     information.

   *
     'slave_rows_search_algorithms'

     Property                             Value

     *System Variable*                    'slave_rows_search_algorithms=list'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               set

     *Default Value*                      'TABLE_SCAN,INDEX_SCAN'

     *Valid Values*                       'TABLE_SCAN,INDEX_SCAN'
                                          'INDEX_SCAN,HASH_SCAN'
                                          'TABLE_SCAN,HASH_SCAN'
                                          'TABLE_SCAN,INDEX_SCAN,HASH_SCAN'
                                          (equivalent to
                                          INDEX_SCAN,HASH_SCAN)

     When preparing batches of rows for row-based logging and
     replication, this variable controls how the rows are searched for
     matches--that is, whether or not hashing is used for searches using
     a primary or unique key, some other key, or using no key at all.
     Setting this variable takes effect for all replication channels
     immediately, including running channels.  The initial setting for
     the system variable can be specified using the
     '--slave-rows-search-algorithms' option.

     Specify a comma-separated list of any 2 (or all 3) values from the
     list 'INDEX_SCAN', 'TABLE_SCAN', 'HASH_SCAN'.  The value is
     expected as a string, so the value must be quoted.  In addition,
     the value must not contain any spaces.  Possible combinations
     (lists) and their effects are shown in the following table:

     Index used /       'INDEX_SCAN,HASH_SCAN''INDEX_SCAN,TABLE_SCAN''TABLE_SCAN,HASH_SCAN'
     option value       or
                        'INDEX_SCAN,TABLE_SCAN,HASH_SCAN'

     _Primary key or    Index scan         Index scan         Hash scan over
     unique key_                                              index

     _(Other) Key_      Hash scan over     Index scan         Hash scan over
                        index                                 index

     _No index_         Hash scan          Table scan         Hash scan

     The order in which the algorithms are specified in the list does
     not make any difference in the order in which they are displayed by
     a 'SELECT' or 'SHOW VARIABLES'
     statement (which is the same as that used in the
     table just shown previously).

        * The default value is 'TABLE_SCAN,INDEX_SCAN', which means that
          all searches that can use indexes do use them, and searches
          without any indexes use table scans.

        * To use hashing for any searches that do not use a primary or
          unique key, set this option to 'INDEX_SCAN,HASH_SCAN'.
          Specifying 'INDEX_SCAN,TABLE_SCAN,HASH_SCAN' has the same
          effect as specifying 'INDEX_SCAN,HASH_SCAN'.

        * To force hashing for _all_ searches, set this option to
          'TABLE_SCAN,HASH_SCAN'.

     It is possible to specify single values for this option, but this
     is not optimal, because setting a single value limits searches to
     using only that algorithm.  In particular, setting 'INDEX_SCAN'
     alone is not recommended, as in that case searches are unable to
     find rows at all if no index is present.

     *Note*:

     There is only a performance advantage for 'INDEX_SCAN' and
     'HASH_SCAN' if the row events are big enough.  The size of row
     events is configured using '--binlog-row-event-max-size'.  For
     example, suppose a 'DELETE' statement which deletes
     25,000 rows generates large 'Delete_row_event' events.  In this
     case if 'slave_rows_search_algorithms' is set to 'INDEX_SCAN' or
     'HASH_SCAN' there is a performance improvement.  However, if there
     are 25,000 'DELETE' statements and each is
     represented by a separate event then setting
     'slave_rows_search_algorithms' to 'INDEX_SCAN' or 'HASH_SCAN'
     provides no performance improvement while executing these separate
     events.

   *
     'slave_skip_errors'

     Property                             Value

     *Command-Line Format*                '--slave-skip-errors=name'

     *System Variable*                    'slave_skip_errors'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      'OFF'

     *Valid Values*                       'OFF' '[list of error codes]'
                                          'all' 'ddl_exist_errors'

     Normally, replication stops when an error occurs on the slave,
     which gives you the opportunity to resolve the inconsistency in the
     data manually.  This variable causes the slave SQL thread to
     continue replication when a statement returns any of the errors
     listed in the variable value.

   *
     'slave_sql_verify_checksum'

     Property                             Value

     *System Variable*                    'slave_sql_verify_checksum'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      '1'

     *Valid Values*                       '0' '1'

     Cause the slave SQL thread to verify data using the checksums read
     from the relay log.  In the event of a mismatch, the slave stops
     with an error.  Setting this variable takes effect for all
     replication channels immediately, including running channels.

     *Note*:

     The slave I/O thread always reads checksums if possible when
     accepting events from over the network.

   *
     'slave_transaction_retries'

     Property                             Value

     *Command-Line Format*                '--slave-transaction-retries=#'

     *System Variable*                    'slave_transaction_retries'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '10'

     *Default Value* (32-bit platforms)   '10'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     If a replication slave SQL thread fails to execute a transaction
     because of an 'InnoDB' deadlock or
     because the transaction's execution time exceeded 'InnoDB'.'
     s 'innodb_lock_wait_timeout' or 'NDB'.'
     s 'TransactionDeadlockDetectionTimeout' or
     'TransactionInactiveTimeout', it automatically retries
     'slave_transaction_retries' times before stopping with an error.
     The default value is 10.  Setting this variable takes effect for
     all replication channels immediately, including running channels.

     As of MySQL 5.7.5, retrying of transactions is supported when
     multi-threading is enabled on a slave.  In previous versions,
     'slave_transaction_retries' was treated as equal to 0 when using
     multi-threaded slaves.

   *
     'slave_type_conversions'

     Property                             Value

     *Command-Line Format*                '--slave-type-conversions=set'

     *System Variable*                    'slave_type_conversions'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               set

     *Default Value*                      ''

     *Valid Values* (>= 5.7.2)            'ALL_LOSSY' 'ALL_NON_LOSSY'
                                          'ALL_SIGNED' 'ALL_UNSIGNED'

     *Valid Values* (<= 5.7.1)            'ALL_LOSSY' 'ALL_NON_LOSSY'

     Controls the type conversion mode in effect on the slave when using
     row-based replication.  In MySQL 5.7.2 and later, its value is a
     comma-delimited set of zero or more elements from the list:
     'ALL_LOSSY', 'ALL_NON_LOSSY', 'ALL_SIGNED', 'ALL_UNSIGNED'.  Set
     this variable to an empty string to disallow type conversions
     between the master and the slave.  Setting this variable takes
     effect for all replication channels immediately, including running
     channels.

     'ALL_SIGNED' and 'ALL_UNSIGNED' were added in MySQL 5.7.2
     (Bug#15831300).  For additional information on type conversion
     modes applicable to attribute promotion and demotion in row-based
     replication, see replication-features-attribute-promotion.

   *
     'sql_slave_skip_counter'

     Property                             Value

     *System Variable*                    'sql_slave_skip_counter'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     The number of events from the master that a slave server should
     skip.  Setting the option has no immediate effect.  The variable
     applies to the next 'START SLAVE' statement;
     the next 'START SLAVE' statement also changes
     the value back to 0.  When this variable is set to a nonzero value
     and there are multiple replication channels configured, the
     'START SLAVE' statement can only be used with the
     'FOR CHANNEL CHANNEL' clause.

     This option is incompatible with GTID-based replication, and must
     not be set to a nonzero value when '--gtid-mode=ON'.  If you need
     to skip transactions when employing GTIDs, use 'gtid_executed' from
     the master instead.  See replication-gtids-failover-empty,
     for information about how to do this.

     *Important*:

     If skipping the number of events specified by setting this variable
     would cause the slave to begin in the middle of an event group, the
     slave continues to skip until it finds the beginning of the next
     event group and begins from that point.  For more information, see
     set-global-sql-slave-skip-counter.

   *
     'sync_master_info'

     Property                             Value

     *Command-Line Format*                '--sync-master-info=#'

     *System Variable*                    'sync_master_info'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '10000'

     *Default Value* (32-bit platforms)   '10000'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The effects of this variable on a replication slave depend on
     whether the slave's 'master_info_repository' is set to 'FILE' or
     'TABLE', as explained in the following paragraphs.

     master_info_repository = FILE

     If the value of 'sync_master_info' is greater than 0, the slave
     synchronizes its 'master.info' file to disk (using 'fdatasync()')
     after every 'sync_master_info' events.  If it is 0, the MySQL
     server performs no synchronization of the 'master.info' file to
     disk; instead, the server relies on the operating system to flush
     its contents periodically as with any other file.

     master_info_repository = TABLE

     If the value of 'sync_master_info' is greater than 0, the slave
     updates its master info repository table after every
     'sync_master_info' events.  If it is 0, the table is never updated.

     The default value for 'sync_master_info' is 10000.  Setting this
     variable takes effect for all replication channels immediately,
     including running channels.

   *
     'sync_relay_log'

     Property                             Value

     *Command-Line Format*                '--sync-relay-log=#'

     *System Variable*                    'sync_relay_log'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '10000'

     *Default Value* (32-bit platforms)   '10000'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     If the value of this variable is greater than 0, the MySQL server
     synchronizes its relay log to disk (using 'fdatasync()') after
     every 'sync_relay_log' events are written to the relay log.
     Setting this variable takes effect for all replication channels
     immediately, including running channels.

     Setting 'sync_relay_log' to 0 causes no synchronization to be done
     to disk; in this case, the server relies on the operating system to
     flush the relay log's contents from time to time as for any other
     file.

     A value of 1 is the safest choice because in the event of a crash
     you lose at most one event from the relay log.  However, it is also
     the slowest choice (unless the disk has a battery-backed cache,
     which makes synchronization very fast).

   *
     'sync_relay_log_info'

     Property                             Value

     *Command-Line Format*                '--sync-relay-log-info=#'

     *System Variable*                    'sync_relay_log_info'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '10000'

     *Default Value* (32-bit platforms)   '10000'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The default value for 'sync_relay_log_info' is 10000.  Setting this
     variable takes effect for all replication channels immediately,
     including running channels.

     The effects of this variable on the replication slave depend on the
     server's 'relay_log_info_repository' setting ('FILE' or 'TABLE').
     If the setting is 'TABLE', the effects of the variable also depend
     on whether the storage engine used by the relay log info table is
     transactional (such as 'InnoDB') or
     not transactional (see 'MyISAM').  The
     effects of these factors on the behavior of the server for
     'sync_relay_log_info' values of zero and greater than zero are as
     follows:

       1. 'sync_relay_log_info = 0'

             * If 'relay_log_info_repository' is set to 'FILE', the
               MySQL server performs no synchronization of the
               'relay-log.info' file to disk; instead, the server relies
               on the operating system to flush its contents
               periodically as with any other file.

             * If 'relay_log_info_repository' is set to 'TABLE', and the
               storage engine for that table is transactional, the table
               is updated after each transaction.  (The
               'sync_relay_log_info' setting is effectively ignored in
               this case.)

             * If 'relay_log_info_repository' is set to 'TABLE', and the
               storage engine for that table is not transactional, the
               table is never updated.

       2. 'sync_relay_log_info = N > 0'

             * If 'relay_log_info_repository' is set to 'FILE', the
               slave synchronizes its 'relay-log.info' file to disk
               (using 'fdatasync()') after every N transactions.

             * If 'relay_log_info_repository' is set to 'TABLE', and the
               storage engine for that table is transactional, the table
               is updated after each transaction.  (The
               'sync_relay_log_info' setting is effectively ignored in
               this case.)

             * If 'relay_log_info_repository' is set to 'TABLE', and the
               storage engine for that table is not transactional, the
               table is updated after every N events.

16.1.6.4 Binary Logging Options and Variables
.............................................

   * replication-optvars-binlog

   * replication-sysvars-binlog

You can use the 'mysqld' options and system variables
that are described in this section to affect the operation of the binary
log as well as to control which statements are written to the binary
log.  For additional information about the binary log, see
binary-log.  For additional information about using MySQL server
options and system variables, see server-options, and
server-system-variables.

*Startup Options Used with Binary Logging*

The following list describes startup options for enabling and
configuring the binary log.  System variables used with binary logging
are discussed later in this section.

   *
     '--binlog-row-event-max-size=N'

     Property                             Value

     *Command-Line Format*                '--binlog-row-event-max-size=#'

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '8192'

     *Default Value* (32-bit platforms)   '8192'

     *Minimum Value* (64-bit platforms)   '256'

     *Minimum Value* (32-bit platforms)   '256'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     Specify the maximum size of a row-based binary log event, in bytes.
     Rows are grouped into events smaller than this size if possible.
     The value should be a multiple of 256.  The default is 8192.  See
     replication-formats.

   *
     '--binlog-rows-query-log-events'

     Property                             Value

     *Command-Line Format*                '--binlog-rows-query-log-events'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option enables 'binlog_rows_query_log_events', which causes
     the MySQL Server to write informational log events such as row
     query log events into its binary log.

   *
     '--log-bin[=BASE_NAME]'

     Property                             Value

     *Command-Line Format*                '--log-bin'

     *System Variable*                    'log_bin'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     Enables binary logging.  With binary logging enabled, the server
     logs all statements that change data to the binary log, which is
     used for backup and replication.  The binary log is a sequence of
     files with a base name and numeric extension.  For information on
     the format and management of the binary log, see
     binary-log.

     If you supply a value for the '--log-bin' option, the value is used
     as the base name for the log sequence.  The server creates binary
     log files in sequence by adding a numeric suffix to the base name.
     In MySQL 5.7, the base name defaults to 'HOST_NAME-bin', using the
     name of the host machine.  It is recommended that you specify a
     base name, so that you can continue to use the same binary log file
     names regardless of changes to the default name.

     The default location for binary log files is the data directory.
     You can use the '--log-bin' option to specify an alternative
     location, by adding a leading absolute path name to the base name
     to specify a different directory.  When the server reads an entry
     from the binary log index file, which tracks the binary log files
     that have been used, it checks whether the entry contains a
     relative path.  If it does, the relative part of the path is
     replaced with the absolute path set using the '--log-bin' option.
     An absolute path recorded in the binary log index file remains
     unchanged; in such a case, the index file must be edited manually
     to enable a new path or paths to be used.  (In older versions of
     MySQL, manual intervention was required whenever relocating the
     binary log or relay log files.)  (Bug #11745230, Bug #12133)

     Setting this option causes the 'log_bin' system variable to be set
     to 'ON' (or '1'), and not to the base name.  The binary log file
     base name and any specified path are available as the
     'log_bin_basename' system variable.

     If you specify the '--log-bin' option without also specifying a
     '--server-id', the server is not allowed to start.  (Bug #11763963,
     Bug #56739)

   *
     '--log-bin-index[=FILE_NAME]'

     Property                             Value

     *Command-Line Format*                '--log-bin-index=file_name'

     *Type*                               file name

     The index file for binary log file names.  See binary-log.
     If you omit the file name, and if you did not specify one with
     '--log-bin', MySQL uses 'HOST_NAME-bin.index' as the file name.

   *
     '--log-bin-trust-function-creators[={0|1}]'

     Property                             Value

     *Command-Line Format*                '--log-bin-trust-function-creators'

     *System Variable*                    'log_bin_trust_function_creators'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option sets the corresponding
     'log_bin_trust_function_creators' system variable.  If no argument
     is given, the option sets the variable to 1.
     'log_bin_trust_function_creators' affects how MySQL enforces
     restrictions on stored function and trigger creation.  See
     stored-programs-logging.

   *
     '--log-bin-use-v1-row-events[={0|1}]'

     Property                             Value

     *Command-Line Format*                '--log-bin-use-v1-row-events[={0|1}]'

     *System Variable*                    'log_bin_use_v1_row_events'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      '0'

     MySQL 5.7 uses Version 2 binary log row events, which cannot be
     read by MySQL Server releases prior to MySQL 5.6.6.  Setting this
     option to 1 causes 'mysqld' to write the binary log
     using Version 1 logging events, which is the only version of binary
     log events used in previous releases, and thus produce binary logs
     that can be read by older slaves.  Setting
     '--log-bin-use-v1-row-events' to 0 (the default) causes
     'mysqld' to use Version 2 binary log events.

     The value used for this option can be obtained from the read-only
     'log_bin_use_v1_row_events' system variable.

     '--log-bin-use-v1-row-events' is chiefly of interest when setting
     up replication conflict detection and resolution using
     'NDB$EPOCH_TRANS()' as the conflict detection function, which
     requires Version 2 binary log row events.  Thus, this option and
     '--ndb-log-transaction-id' are not compatible.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

Statement selection options

The options in the following list affect which statements are written to
the binary log, and thus sent by a replication master server to its
slaves.  There are also options for slave servers that control which
statements received from the master should be executed or ignored.  For
details, see replication-options-slave.

   *
     '--binlog-do-db=DB_NAME'

     Property                             Value

     *Command-Line Format*                '--binlog-do-db=name'

     *Type*                               string

     This option affects binary logging in a manner similar to the way
     that '--replicate-do-db' affects replication.

     The effects of this option depend on whether the statement-based or
     row-based logging format is in use, in the same way that the
     effects of '--replicate-do-db' depend on whether statement-based or
     row-based replication is in use.  You should keep in mind that the
     format used to log a given statement may not necessarily be the
     same as that indicated by the value of 'binlog_format'.  For
     example, DDL statements such as 'CREATE TABLE'.
     and 'ALTER TABLE' are always logged as
     statements, without regard to the logging format in effect, so the
     following statement-based rules for '--binlog-do-db' always apply
     in determining whether or not the statement is logged.

     Statement-based logging

     Only those statements are written to the binary log where the
     default database (that is, the one selected by 'USE')
     is DB_NAME.  To specify more than one database, use this option
     multiple times, once for each database; however, doing so does
     _not_ cause cross-database statements such as 'UPDATE
     SOME_DB.SOME_TABLE SET foo='bar'' to be logged while a different
     database (or no database) is selected.

     *Warning*:

     To specify multiple databases you _must_ use multiple instances of
     this option.  Because database names can contain commas, the list
     will be treated as the name of a single database if you supply a
     comma-separated list.

     An example of what does not work as you might expect when using
     statement-based logging: If the server is started with
     '--binlog-do-db=sales' and you issue the following statements, the
     'UPDATE' statement is _not_ logged:

          USE prices;
          UPDATE sales.january SET amount=amount+1000;

     The main reason for this 'just check the default database' behavior
     is that it is difficult from the statement alone to know whether it
     should be replicated (for example, if you are using multiple-table
     'DELETE' statements or multiple-table
     'UPDATE' statements that act across multiple databases).
     It is also faster to check only the default database rather than
     all databases if there is no need.

     Another case which may not be self-evident occurs when a given
     database is replicated even though it was not specified when
     setting the option.  If the server is started with
     '--binlog-do-db=sales', the following 'UPDATE'.
     statement is logged even though 'prices' was not included when
     setting '--binlog-do-db':

          USE sales;
          UPDATE prices.discounts SET percentage = percentage + 10;

     Because 'sales' is the default database when the 'UPDATE'
     statement is issued, the 'UPDATE' is logged.

     Row-based logging

     Logging is restricted to database DB_NAME.  Only changes to tables
     belonging to DB_NAME are logged; the default database has no effect
     on this.  Suppose that the server is started with
     '--binlog-do-db=sales' and row-based logging is in effect, and then
     the following statements are executed:

          USE prices;
          UPDATE sales.february SET amount=amount+100;

     The changes to the 'february' table in the 'sales' database are
     logged in accordance with the 'UPDATE' statement;
     this occurs whether or not the 'USE' statement was
     issued.  However, when using the row-based logging format and
     '--binlog-do-db=sales', changes made by the following
     'UPDATE' are not logged:

          USE prices;
          UPDATE prices.march SET amount=amount-25;

     Even if the 'USE prices' statement were changed to 'USE sales', the
     'UPDATE' statement's effects would still not be
     written to the binary log.

     Another important difference in '--binlog-do-db' handling for
     statement-based logging as opposed to the row-based logging occurs
     with regard to statements that refer to multiple databases.
     Suppose that the server is started with '--binlog-do-db=db1', and
     the following statements are executed:

          USE db1;
          UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;

     If you are using statement-based logging, the updates to both
     tables are written to the binary log.  However, when using the
     row-based format, only the changes to 'table1' are logged; 'table2'
     is in a different database, so it is not changed by the
     'UPDATE'.  Now suppose that, instead of the 'USE db1'
     statement, a 'USE db4' statement had been used:

          USE db4;
          UPDATE db1.table1 SET col1 = 10, db2.table2 SET col2 = 20;

     In this case, the 'UPDATE' statement is not written
     to the binary log when using statement-based logging.  However,
     when using row-based logging, the change to 'table1' is logged, but
     not that to 'table2'--in other words, only changes to tables in the
     database named by '--binlog-do-db' are logged, and the choice of
     default database has no effect on this behavior.

   *
     '--binlog-ignore-db=DB_NAME'

     Property                             Value

     *Command-Line Format*                '--binlog-ignore-db=name'

     *Type*                               string

     This option affects binary logging in a manner similar to the way
     that '--replicate-ignore-db' affects replication.

     The effects of this option depend on whether the statement-based or
     row-based logging format is in use, in the same way that the
     effects of '--replicate-ignore-db' depend on whether
     statement-based or row-based replication is in use.  You should
     keep in mind that the format used to log a given statement may not
     necessarily be the same as that indicated by the value of
     'binlog_format'.  For example, DDL statements such as 'CREATE TABLE'
     and 'ALTER TABLE' are
     always logged as statements, without regard to the logging format
     in effect, so the following statement-based rules for
     '--binlog-ignore-db' always apply in determining whether or not the
     statement is logged.

     Statement-based logging

     Tells the server to not log any statement where the default
     database (that is, the one selected by 'USE') is
     DB_NAME.

     Prior to MySQL 5.7.2, this option caused any statements containing
     fully qualified table names not to be logged if there was no
     default database specified (that is, when 'SELECT'.
     'DATABASE()' returned 'NULL').  In MySQL 5.7.2 and later, when
     there is no default database, no '--binlog-ignore-db' options are
     applied, and such statements are always logged.  (Bug #11829838,
     Bug #60188)

     Row-based format

     Tells the server not to log updates to any tables in the database
     DB_NAME.  The current database has no effect.

     When using statement-based logging, the following example does not
     work as you might expect.  Suppose that the server is started with
     '--binlog-ignore-db=sales' and you issue the following statements:

          USE prices;
          UPDATE sales.january SET amount=amount+1000;

     The 'UPDATE' statement _is_ logged in such a case
     because '--binlog-ignore-db' applies only to the default database
     (determined by the 'USE' statement).  Because the
     'sales' database was specified explicitly in the statement, the
     statement has not been filtered.  However, when using row-based
     logging, the 'UPDATE' statement's effects are _not_
     written to the binary log, which means that no changes to the
     'sales.january' table are logged; in this instance,
     '--binlog-ignore-db=sales' causes _all_ changes made to tables in
     the master's copy of the 'sales' database to be ignored for
     purposes of binary logging.

     To specify more than one database to ignore, use this option
     multiple times, once for each database.  Because database names can
     contain commas, the list will be treated as the name of a single
     database if you supply a comma-separated list.

     You should not use this option if you are using cross-database
     updates and you do not want these updates to be logged.

Checksum options

MySQL supports reading and writing of binary log checksums.  These are
enabled using the two options listed here:

   *
     '--binlog-checksum={NONE|CRC32}'

     Property                             Value

     *Command-Line Format*                '--binlog-checksum=type'

     *Type*                               string

     *Default Value*                      'CRC32'

     *Valid Values*                       'NONE' 'CRC32'

     Enabling this option causes the master to write checksums for
     events written to the binary log.  Set to 'NONE' to disable, or the
     name of the algorithm to be used for generating checksums;
     currently, only CRC32 checksums are supported, and CRC32 is the
     default.  You cannot change the setting for this option within a
     transaction.

   *
     '--master-verify-checksum={0|1}'

     Property                             Value

     *Command-Line Format*                '--master-verify-checksum=name'

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enabling this option causes the master to verify events from the
     binary log using checksums, and to stop with an error in the event
     of a mismatch.  Disabled by default.

To control reading of checksums by the slave (from the relay) log, use
the '--slave-sql-verify-checksum' option.

Testing and debugging options

The following binary log options are used in replication testing and
debugging.  They are not intended for use in normal operations.

   *
     '--max-binlog-dump-events=N'

     Property                             Value

     *Command-Line Format*                '--max-binlog-dump-events=#'

     *Type*                               integer

     *Default Value*                      '0'

     This option is used internally by the MySQL test suite for
     replication testing and debugging.

   *
     '--sporadic-binlog-dump-fail'

     Property                             Value

     *Command-Line Format*                '--sporadic-binlog-dump-fail'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option is used internally by the MySQL test suite for
     replication testing and debugging.

*System Variables Used with Binary Logging*

The following list describes system variables for controlling binary
logging.  They can be set at server startup and some of them can be
changed at runtime using 'SET'.  Server options used
to control binary logging are listed earlier in this section.  For
information about the 'sql_log_bin' and 'sql_log_off' variables, see
server-system-variables.

   *
     'binlog_cache_size'

     Property                             Value

     *Command-Line Format*                '--binlog-cache-size=#'

     *System Variable*                    'binlog_cache_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '32768'

     *Default Value* (32-bit platforms)   '32768'

     *Minimum Value* (64-bit platforms)   '4096'

     *Minimum Value* (32-bit platforms)   '4096'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The size of the cache to hold changes to the binary log during a
     transaction.  A binary log cache is allocated for each client if
     the server supports any transactional storage engines and if the
     server has the binary log enabled ('--log-bin' option).  If you
     often use large transactions, you can increase this cache size to
     get better performance.  The 'Binlog_cache_use' and
     'Binlog_cache_disk_use' status variables can be useful for tuning
     the size of this variable.  See binary-log.

     'binlog_cache_size' sets the size for the transaction cache only;
     the size of the statement cache is governed by the
     'binlog_stmt_cache_size' system variable.

   *
     'binlog_checksum'

     Property                             Value

     *System Variable*                    'binlog_checksum'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'CRC32'

     *Valid Values*                       'NONE' 'CRC32'

     When enabled, this variable causes the master to write a checksum
     for each event in the binary log.  'binlog_checksum' supports the
     values 'NONE' (disabled) and 'CRC32'.  The default is 'CRC32'.  You
     cannot change the value of 'binlog_checksum' within a transaction.

     When 'binlog_checksum' is disabled (value 'NONE'), the server
     verifies that it is writing only complete events to the binary log
     by writing and checking the event length (rather than a checksum)
     for each event.

     Changing the value of this variable causes the binary log to be
     rotated; checksums are always written to an entire binary log file,
     and never to only part of one.

     Setting this variable on the master to a value unrecognized by the
     slave causes the slave to set its own 'binlog_checksum' value to
     'NONE', and to stop replication with an error.  (Bug #13553750, Bug
     #61096) If backward compatibility with older slaves is a concern,
     you may want to set the value explicitly to 'NONE'.

   *
     'binlog_direct_non_transactional_updates'

     Property                             Value

     *Command-Line Format*                '--binlog-direct-non-transactional-updates[=value]'

     *System Variable*                    'binlog_direct_non_transactional_updates'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Due to concurrency issues, a slave can become inconsistent when a
     transaction contains updates to both transactional and
     nontransactional tables.  MySQL tries to preserve causality among
     these statements by writing nontransactional statements to the
     transaction cache, which is flushed upon commit.  However, problems
     arise when modifications done to nontransactional tables on behalf
     of a transaction become immediately visible to other connections
     because these changes may not be written immediately into the
     binary log.

     The 'binlog_direct_non_transactional_updates' variable offers one
     possible workaround to this issue.  By default, this variable is
     disabled.  Enabling 'binlog_direct_non_transactional_updates'
     causes updates to nontransactional tables to be written directly to
     the binary log, rather than to the transaction cache.

     _'binlog_direct_non_transactional_updates' works only for
     statements that are replicated using the statement-based binary
     logging format_; that is, it works only when the value of
     'binlog_format' is 'STATEMENT', or when 'binlog_format' is 'MIXED'
     and a given statement is being replicated using the statement-based
     format.  This variable has no effect when the binary log format is
     'ROW', or when 'binlog_format' is set to 'MIXED' and a given
     statement is replicated using the row-based format.

     *Important*:

     Before enabling this variable, you must make certain that there are
     no dependencies between transactional and nontransactional tables;
     an example of such a dependency would be the statement 'INSERT INTO
     myisam_table SELECT * FROM innodb_table'.  Otherwise, such
     statements are likely to cause the slave to diverge from the
     master.

     This variable has no effect when the binary log format is 'ROW' or
     'MIXED'.

   *
     'binlog_error_action'

     Property                             Value

     *Command-Line Format*                '--binlog-error-action[=value]'

     *Introduced*                         5.7.6

     *System Variable*                    'binlog_error_action'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value* (>= 5.7.7)           'ABORT_SERVER'

     *Default Value* (<= 5.7.6)           'IGNORE_ERROR'

     *Valid Values*                       'IGNORE_ERROR' 'ABORT_SERVER'

     Controls what happens when the server encounters an error such as
     not being able to write to, flush or synchronize the binary log,
     which can cause the master's log to become inconsistent and
     replication slaves to lose synchronization.

     In MySQL 5.7.7 and later, this variable defaults to 'ABORT_SERVER',
     which makes the server halt logging and shut down whenever it
     encounters such an error with the binary log.  Upon server restart,
     all of the previously prepared and binary logged transactions are
     committed, while any transactions which were prepared but not
     binary logged due to the error are aborted.

     When 'binlog_error_action' is set to 'IGNORE_ERROR', if the server
     encounters such an error it continues the ongoing transaction, logs
     the error then halts logging, and continues performing updates.  To
     resume binary logging 'log_bin' must be enabled again.  This
     provides backward compatibility with older versions of MySQL.

     In previous releases this variable was named
     'binlogging_impossible_mode'.

   *
     'binlog_format'

     Property                             Value

     *Command-Line Format*                '--binlog-format=format'

     *System Variable*                    'binlog_format'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value* (>= 5.7.7)           'ROW'

     *Default Value* (<= 5.7.6)           'STATEMENT'

     *Valid Values*                       'ROW' 'STATEMENT' 'MIXED'

     This variable sets the binary logging format, and can be any one of
     'STATEMENT', 'ROW', or 'MIXED'.  See replication-formats.
     'binlog_format' is set by the '--binlog-format' option at startup,
     or by the 'binlog_format' variable at runtime.

     *Note*:

     While you can change the logging format at runtime, it is _not_
     recommended that you change it while replication is ongoing.  This
     is due in part to the fact that slaves do not honor the master's
     'binlog_format' setting; a given MySQL Server can change only its
     own logging format.

     Prior to MySQL 5.7.7, the default format was 'STATEMENT'.  In MySQL
     5.7.7 and later the default is 'ROW'.  _Exception_: In NDB Cluster,
     the default is 'MIXED'; statement-based replication is not
     supported for NDB Cluster.

     You must have the 'SUPER' privilege to set either the global or
     session 'binlog_format' value.

     The rules governing when changes to this variable take effect and
     how long the effect lasts are the same as for other MySQL server
     system variables.  For more information, see set-variable.

     When 'MIXED' is specified, statement-based replication is used,
     except for cases where only row-based replication is guaranteed to
     lead to proper results.  For example, this happens when statements
     contain user-defined functions (UDF) or the 'UUID()' function.

     For details of how stored programs (stored procedures and
     functions, triggers, and events) are handled when each binary
     logging format is set, see stored-programs-logging.

     There are exceptions when you cannot switch the replication format
     at runtime:

        * From within a stored function or a trigger.

        * If the session is currently in row-based replication mode and
          has open temporary tables.

        * From within a transaction.

     Trying to switch the format in those cases results in an error.

     The binary log format affects the behavior of the following server
     options:

        * '--replicate-do-db'

        * '--replicate-ignore-db'

        * '--binlog-do-db'

        * '--binlog-ignore-db'

     These effects are discussed in detail in the descriptions of the
     individual options.

   *
     'binlog_group_commit_sync_delay'

     Property                             Value

     *Command-Line Format*                '--binlog-group-commit-sync-delay=#'

     *Introduced*                         5.7.5

     *System Variable*                    'binlog_group_commit_sync_delay'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1000000'

     Controls how many microseconds the binary log commit waits before
     synchronizing the binary log file to disk.  By default
     'binlog_group_commit_sync_delay' is set to 0, meaning that there is
     no delay.  Setting 'binlog_group_commit_sync_delay' to a
     microsecond delay enables more transactions to be synchronized
     together to disk at once, reducing the overall time to commit a
     group of transactions because the larger groups require fewer time
     units per group.

     When 'sync_binlog=0' or 'sync_binlog=1' is set, the delay specified
     by 'binlog_group_commit_sync_delay' is applied for every binary log
     commit group before synchronization (or in the case of
     'sync_binlog=0', before proceeding).  When 'sync_binlog' is set to
     a value _n_ greater than 1, the delay is applied after every _n_
     binary log commit groups.

     Setting 'binlog_group_commit_sync_delay' can increase the number of
     parallel committing transactions on any server that has (or might
     have after a failover) a replication slave, and therefore can
     increase parallel execution on the replication slaves.  To benefit
     from this effect, the slave servers must have
     'slave_parallel_type=LOGICAL_CLOCK' set.

     It is important to take into account both the master's throughput
     and the slaves' throughput when you are tuning the setting for
     'binlog_group_commit_sync_delay'.

     Setting 'binlog_group_commit_sync_delay' can also reduce the number
     of 'fsync()' calls to the binary log on any server (master or
     slave) that has a binary log.

     Note that setting 'binlog_group_commit_sync_delay' increases the
     latency of transactions on the server, which might affect client
     applications.  Also, on highly concurrent workloads, it is possible
     for the delay to increase contention and therefore reduce
     throughput.  Typically, the benefits of setting a delay outweigh
     the drawbacks, but tuning should always be carried out to determine
     the optimal setting.

   *
     'binlog_group_commit_sync_no_delay_count'

     Property                             Value

     *Command-Line Format*                '--binlog-group-commit-sync-no-delay-count=#'

     *Introduced*                         5.7.5

     *System Variable*                    'binlog_group_commit_sync_no_delay_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1000000'

     The maximum number of transactions to wait for before aborting the
     current delay as specified by 'binlog_group_commit_sync_delay'.  If
     'binlog_group_commit_sync_delay' is set to 0, then this option has
     no effect.

   *
     'binlogging_impossible_mode'

     Property                             Value

     *Command-Line Format*                '--binlogging-impossible-mode[=value]'

     *Introduced*                         5.7.5

     *Deprecated*                         Yes (removed in 5.7.6)

     *System Variable*                    'binlogging_impossible_mode'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'IGNORE_ERROR'

     *Valid Values*                       'IGNORE_ERROR' 'ABORT_SERVER'

     This option was removed in MySQL 5.7.6.  Use 'binlog_error_action'
     to control what happens when the server cannot write to the binary
     log.

   *
     'binlog_max_flush_queue_time'

     Property                             Value

     *Deprecated*                         5.7.9

     *System Variable*                    'binlog_max_flush_queue_time'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '100000'

     Formerly, this controlled the time in microseconds to continue
     reading transactions from the flush queue before proceeding with
     group commit.  In MySQL 5.7, this variable no longer has any
     effect.

     'binlog_max_flush_queue_time' is deprecated as of MySQL 5.7.9, and
     is marked for eventual removal in a future MySQL release.

   *
     'binlog_order_commits'

     Property                             Value

     *System Variable*                    'binlog_order_commits'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     When this variable is enabled on a master (the default),
     transactions are externalized in the same order as they are written
     to the binary log.  If disabled, transactions may be committed in
     parallel.  In some cases, disabling this variable might produce a
     performance increment.

   *
     'binlog_row_image'

     Property                             Value

     *Command-Line Format*                '--binlog-row-image=image_type'

     *System Variable*                    'binlog_row_image=image_type'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'full'

     *Valid Values*                       'full' (Log all columns) 'minimal'
                                          (Log only changed columns, and
                                          columns needed to identify rows)
                                          'noblob' (Log all columns, except
                                          for unneeded BLOB and TEXT
                                          columns)

     For MySQL row-based replication, this variable determines how row
     images are written to the binary log.

     In MySQL row-based replication, each row change event contains two
     images, a 'before' image whose columns are matched against when
     searching for the row to be updated, and an 'after' image
     containing the changes.  Normally, MySQL logs full rows (that is,
     all columns) for both the before and after images.  However, it is
     not strictly necessary to include every column in both images, and
     we can often save disk, memory, and network usage by logging only
     those columns which are actually required.

     *Note*:

     When deleting a row, only the before image is logged, since there
     are no changed values to propagate following the deletion.  When
     inserting a row, only the after image is logged, since there is no
     existing row to be matched.  Only when updating a row are both the
     before and after images required, and both written to the binary
     log.

     For the before image, it is necessary only that the minimum set of
     columns required to uniquely identify rows is logged.  If the table
     containing the row has a primary key, then only the primary key
     column or columns are written to the binary log.  Otherwise, if the
     table has a unique key all of whose columns are 'NOT NULL', then
     only the columns in the unique key need be logged.  (If the table
     has neither a primary key nor a unique key without any 'NULL'
     columns, then all columns must be used in the before image, and
     logged.)  In the after image, it is necessary to log only the
     columns which have actually changed.

     You can cause the server to log full or minimal rows using the
     'binlog_row_image' system variable.  This variable actually takes
     one of three possible values, as shown in the following list:

        * 'full': Log all columns in both the before image and the after
          image.

        * 'minimal': Log only those columns in the before image that are
          required to identify the row to be changed; log only those
          columns in the after image where a value was specified by the
          SQL statement, or generated by auto-increment.

        * 'noblob': Log all columns (same as 'full'), except for
          'BLOB' and 'TEXT' columns that are not
          required to identify rows, or that have not changed.

     *Note*:

     This variable is not supported by NDB Cluster; setting it has no
     effect on the logging of 'NDB' tables.

     The default value is 'full'.

     In MySQL 5.5 and earlier, full row images were always used for both
     before images and after images.  If you need to replicate from a
     newer master to a slave running MySQL 5.5 or earlier, the master
     should always use this value.

     When using 'minimal' or 'noblob', deletes and updates are
     guaranteed to work correctly for a given table if and only if the
     following conditions are true for both the source and destination
     tables:

        * All columns must be present and in the same order; each column
          must use the same data type as its counterpart in the other
          table.

        * The tables must have identical primary key definitions.

     (In other words, the tables must be identical with the possible
     exception of indexes that are not part of the tables' primary
     keys.)

     If these conditions are not met, it is possible that the primary
     key column values in the destination table may prove insufficient
     to provide a unique match for a delete or update.  In this event,
     no warning or error is issued; the master and slave silently
     diverge, thus breaking consistency.

     Setting this variable has no effect when the binary logging format
     is 'STATEMENT'.  When 'binlog_format' is 'MIXED', the setting for
     'binlog_row_image' is applied to changes that are logged using
     row-based format, but this setting no effect on changes logged as
     statements.

     Setting 'binlog_row_image' on either the global or session level
     does not cause an implicit commit; this means that this variable
     can be changed while a transaction is in progress without affecting
     the transaction.

   *
     'binlog_rows_query_log_events'

     Property                             Value

     *Command-Line Format*                '--binlog-rows-query-log-events'

     *System Variable*                    'binlog_rows_query_log_events'

     *Scope*                              Global, Session

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'FALSE'

     The 'binlog_rows_query_log_events' system variable affects
     row-based logging only.  When enabled, it causes the MySQL Server
     to write informational log events such as row query log events into
     its binary log.  This information can be used for debugging and
     related purposes; such as obtaining the original query issued on
     the master when it cannot be reconstructed from the row updates.

     These events are normally ignored by MySQL programs reading the
     binary log and so cause no issues when replicating or restoring
     from backup.  To view them, increase the verbosity level by using
     mysqlbinlog's '--verbose' option twice, either as '-vv' or
     '--verbose --verbose'.

   *
     'binlog_stmt_cache_size'

     Property                             Value

     *Command-Line Format*                '--binlog-stmt-cache-size=#'

     *System Variable*                    'binlog_stmt_cache_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '32768'

     *Default Value* (32-bit platforms)   '32768'

     *Minimum Value* (64-bit platforms)   '4096'

     *Minimum Value* (32-bit platforms)   '4096'

     *Maximum Value* (64-bit platforms)   '18446744073709551615'

     *Maximum Value* (32-bit platforms)   '4294967295'

     This variable determines the size of the cache for the binary log
     to hold nontransactional statements issued during a transaction.
     Separate binary log transaction and statement caches are allocated
     for each client if the server supports any transactional storage
     engines and if the server has the binary log enabled ('--log-bin'
     option).  If you often use large nontransactional statements during
     transactions, you can increase this cache size to get better
     performance.  The 'Binlog_stmt_cache_use' and
     'Binlog_stmt_cache_disk_use' status variables can be useful for
     tuning the size of this variable.  See binary-log.

     The 'binlog_cache_size' system variable sets the size for the
     transaction cache.

   *
     'binlog_transaction_dependency_tracking'

     Property                             Value

     *Command-Line Format*                '--binlog-transaction-dependency-tracking=value'

     *Introduced*                         5.7.22

     *System Variable*                    'binlog_transaction_dependency_tracking'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'COMMIT_ORDER'

     *Valid Values*                       'COMMIT_ORDER' 'WRITESET'
                                          'WRITESET_SESSION'

     The source of dependency information on the master used to
     determine which transactions can be executed in parallel by the
     slave's multi-threaded applier.  This variable can take one of the
     three values described in the following list:

        * 'COMMIT_ORDER': Dependency information is generated from the
          master's commit timestamps.  This is the default.  This mode
          is also used for any transactions without write sets, even if
          this variable's is 'WRITESET' or 'WRITESET_SESSION'; this is
          also the case for transactions updating tables without primary
          keys and transactions updating tables having foreign key
          constraints.

        * 'WRITESET': Dependency information is generated from the
          master's write set, and any transactions which write different
          tuples can be parallelized.

        * 'WRITESET_SESSION': Dependency information is generated from
          the master's write set, but no two updates from the same
          session can be reordered.

     'WRITESET' and 'WRITESET_SESSION' modes do not deliver any
     transaction dependencies that are newer than those that would have
     been returned in 'COMMIT_ORDER' mode.

     The value of this variable cannot be set to anything other than
     'COMMIT_ORDER' if 'transaction_write_set_extraction' is 'OFF'.  You
     should also note that the value of
     'transaction_write_set_extraction' cannot be changed if the current
     value of 'binlog_transaction_dependency_tracking' is 'WRITESET' or
     'WRITESET_SESSION'.

     The number of row hashes to be kept and checked for the latest
     transaction to have changed a given row is determined by the value
     of 'binlog_transaction_dependency_history_size'.

   *
     'binlog_transaction_dependency_history_size'

     Property                             Value

     *Command-Line Format*                '--binlog-transaction-dependency-history-size=#'

     *Introduced*                         5.7.22

     *System Variable*                    'binlog_transaction_dependency_history_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '25000'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1000000'

     Sets an upper limit on the number of row hashes which are kept in
     memory and used for looking up the transaction that last modified a
     given row.  Once this number of hashes has been reached, the
     history is purged.

   *
     'log_bin'

     Property                             Value

     *System Variable*                    'log_bin'

     *Scope*                              Global

     *Dynamic*                            No

     Whether the binary log is enabled.  If the '--log-bin' option is
     used, then the value of this variable is 'ON'; otherwise it is
     'OFF'.  This variable reports only on the status of binary logging
     (enabled or disabled); it does not actually report the value to
     which '--log-bin' is set.

     See binary-log.

   *
     'log_bin_basename'

     Property                             Value

     *System Variable*                    'log_bin_basename'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     Holds the base name and path for the binary log files, which can be
     set with the '--log-bin' server option.  In MySQL 5.7, the default
     base name is the name of the host machine with the suffix '-bin'.
     The default location is the data directory.

   *
     'log_bin_index'

     Property                             Value

     *System Variable*                    'log_bin_index'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     Holds the base name and path for the binary log index file, which
     can be set with the '--log-bin-index' server option.

   *
     'log_bin_use_v1_row_events'

     Property                             Value

     *Command-Line Format*                '--log-bin-use-v1-row-events[={0|1}]'

     *System Variable*                    'log_bin_use_v1_row_events'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      '0'

     Shows whether Version 2 binary logging is in use.  A value of 1
     shows that the server is writing the binary log using Version 1
     logging events (the only version of binary log events used in
     previous releases), and thus producing a binary log that can be
     read by older slaves.  0 indicates that Version 2 binary log events
     are in use.

     This variable is read-only.  To switch between Version 1 and
     Version 2 binary event binary logging, it is necessary to restart
     'mysqld' with the '--log-bin-use-v1-row-events'
     option.

     Other than when performing upgrades of NDB Cluster Replication,
     '--log-bin-use-v1-events' is chiefly of interest when setting up
     replication conflict detection and resolution using
     'NDB$EPOCH_TRANS()', which requires Version 2 binary row event
     logging.  Thus, this option and '--ndb-log-transaction-id' are not
     compatible.

     *Note*:

     MySQL NDB Cluster 7.5 uses Version 2 binary log row events by
     default.  You should keep this mind when planning upgrades or
     downgrades, and for setups using NDB Cluster Replication.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   *
     'log_slave_updates'

     Property                             Value

     *Command-Line Format*                '--log-slave-updates'

     *System Variable*                    'log_slave_updates'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Whether updates received by a slave server from a master server
     should be logged to the slave's own binary log.  Binary logging
     must be enabled on the slave for this variable to have any effect.
     See replication-options.

   *
     'log_statements_unsafe_for_binlog'

     Property                             Value

     *Introduced*                         5.7.11

     *System Variable*                    'log_statements_unsafe_for_binlog'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     If error 1592 is encountered, controls whether the generated
     warnings are added to the error log or not.

   *
     'master_verify_checksum'

     Property                             Value

     *System Variable*                    'master_verify_checksum'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enabling this variable causes the master to examine checksums when
     reading from the binary log.  'master_verify_checksum' is disabled
     by default; in this case, the master uses the event length from the
     binary log to verify events, so that only complete events are read
     from the binary log.

   *
     'max_binlog_cache_size'

     Property                             Value

     *Command-Line Format*                '--max-binlog-cache-size=#'

     *System Variable*                    'max_binlog_cache_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '18446744073709551615'

     *Minimum Value*                      '4096'

     *Maximum Value*                      '18446744073709551615'

     If a transaction requires more than this many bytes of memory, the
     server generates a 'Multi-statement transaction required more than
     'max_binlog_cache_size' bytes of storage' error.  The minimum value
     is 4096.  The maximum possible value is 16EB (exabytes).  The
     maximum recommended value is 4GB; this is due to the fact that
     MySQL currently cannot work with binary log positions greater than
     4GB.

     'max_binlog_cache_size' sets the size for the transaction cache
     only; the upper limit for the statement cache is governed by the
     'max_binlog_stmt_cache_size' system variable.

     The visibility to sessions of 'max_binlog_cache_size' matches that
     of the 'binlog_cache_size' system variable; in other words,
     changing its value affects only new sessions that are started after
     the value is changed.

   *
     'max_binlog_size'

     Property                             Value

     *Command-Line Format*                '--max-binlog-size=#'

     *System Variable*                    'max_binlog_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1073741824'

     *Minimum Value*                      '4096'

     *Maximum Value*                      '1073741824'

     If a write to the binary log causes the current log file size to
     exceed the value of this variable, the server rotates the binary
     logs (closes the current file and opens the next one).  The minimum
     value is 4096 bytes.  The maximum and default value is 1GB.

     A transaction is written in one chunk to the binary log, so it is
     never split between several binary logs.  Therefore, if you have
     big transactions, you might see binary log files larger than
     'max_binlog_size'.

     If 'max_relay_log_size' is 0, the value of 'max_binlog_size'
     applies to relay logs as well.

   *
     'max_binlog_stmt_cache_size'

     Property                             Value

     *Command-Line Format*                '--max-binlog-stmt-cache-size=#'

     *System Variable*                    'max_binlog_stmt_cache_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '18446744073709547520'

     *Minimum Value*                      '4096'

     *Maximum Value*                      '18446744073709547520'

     If nontransactional statements within a transaction require more
     than this many bytes of memory, the server generates an error.  The
     minimum value is 4096.  The maximum and default values are 4GB on
     32-bit platforms and 16EB (exabytes) on 64-bit platforms.

     'max_binlog_stmt_cache_size' sets the size for the statement cache
     only; the upper limit for the transaction cache is governed
     exclusively by the 'max_binlog_cache_size' system variable.

   *
     'sync_binlog'

     Property                             Value

     *Command-Line Format*                '--sync-binlog=#'

     *System Variable*                    'sync_binlog'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value* (>= 5.7.7)           '1'

     *Default Value* (<= 5.7.6)           '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     Controls the number of binary log commit groups to collect before
     synchronizing the binary log to disk.  When 'sync_binlog=0', the
     binary log is never synchronized to disk, and when 'sync_binlog' is
     set to a value greater than 0 this number of binary log commit
     groups is periodically synchronized to disk.  When 'sync_binlog=1',
     all transactions are synchronized to the binary log before they are
     committed.  Therefore, even in the event of an unexpected restart,
     any transactions that are missing from the binary log are only in
     prepared state.  This causes the server's automatic recovery
     routine to roll back those transactions.  This guarantees that no
     transaction is lost from the binary log, and is the safest option.
     However this can have a negative impact on performance because of
     an increased number of disk writes.  Using a higher value improves
     performance, but with the increased risk of data loss.

     When 'sync_binlog=0' or 'sync_binlog' is greater than 1,
     transactions are committed without having been synchronized to
     disk.  Therefore, in the event of a power failure or operating
     system crash, it is possible that the server has committed some
     transactions that have not been synchronized to the binary log.
     Therefore it is impossible for the recovery routine to recover
     these transactions and they will be lost from the binary log.

     Prior to MySQL 5.7.7, the default value of 'sync_binlog' was 0,
     which configures no synchronizing to disk--in this case, the server
     relies on the operating system to flush the binary log's contents
     from time to time as for any other file.  MySQL 5.7.7 and later use
     a default value of 1, which is the safest choice, but as noted
     above can impact performance.

16.1.6.5 Global Transaction ID Options and Variables
....................................................

   * replication-optvars-gtids

   * replication-sysvars-gtids

The MySQL Server options and system variables described in this section
are used to monitor and control Global Transaction Identifiers (GTIDs).

For additional information, see replication-gtids.

*Startup Options Used with GTID Replication*

The following server startup options are used with GTID-based
replication:

   *
     '--enforce-gtid-consistency'

     Property                             Value

     *Command-Line Format*                '--enforce-gtid-consistency[=value]'

     *System Variable*                    'enforce_gtid_consistency'

     *Scope*                              Global

     *Dynamic* (>= 5.7.6)                 Yes

     *Dynamic* (<= 5.7.5)                 No

     *Type* (>= 5.7.6)                    enumeration

     *Type* (<= 5.7.5)                    boolean

     *Default Value* (>= 5.7.6)           'OFF'

     *Default Value* (<= 5.7.5)           'false'

     *Valid Values* (>= 5.7.6)            'OFF' 'ON' 'WARN'

     When enabled, the server enforces GTID consistency by allowing
     execution of only statements that can be safely logged using a
     GTID. You _must_ set this option to 'ON' before enabling GTID based
     replication.

     The values that '--enforce-gtid-consistency' can be configured to
     are:

        * 'OFF': all transactions are allowed to violate GTID
          consistency.

        * 'ON': no transaction is allowed to violate GTID consistency.

        * 'WARN': all transactions are allowed to violate GTID
          consistency, but a warning is generated in this case.  'WARN'
          was added in MySQL 5.7.6.

     Setting '--enforce-gtid-consistency' without a value is an alias
     for '--enforce-gtid-consistency=ON'.  This impacts on the behavior
     of the variable, see 'enforce_gtid_consistency'.

     Only statements that can be logged using GTID safe statements can
     be logged when 'enforce-gtid-consistency' is set to 'ON', so the
     operations listed here cannot be used with this option:

        * 'CREATE TABLE ... SELECT'.
          statements

        * 'CREATE TEMPORARY TABLE' or 'DROP TEMPORARY TABLE'
          statements inside transactions

        * Transactions or statements that update both transactional and
          nontransactional tables.  There is an exception that
          nontransactional DML is allowed in the same transaction or in
          the same statement as transactional DML, if all
          _nontransactional_ tables are temporary.

     '--enforce-gtid-consistency' only takes effect if binary logging
     takes place for a statement.  If binary logging is disabled on the
     server, or if statements are not written to the binary log because
     they are removed by a filter, GTID consistency is not checked or
     enforced for the statements that are not logged.

     For more information, see replication-gtids-restrictions.

   *
     '--executed-gtids-compression-period'

     Property                             Value

     *Command-Line Format*                '--executed-gtids-compression-period=#'

     *Introduced*                         5.7.5

     *Deprecated*                         5.7.6

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     This option is deprecated and will be removed in a future MySQL
     release.  Use the renamed gtid_executed_compression_period to
     control how the gtid_executed table is compressed.

   *
     '--gtid-mode'

     Property                             Value

     *Command-Line Format*                '--gtid-mode=MODE'

     *System Variable*                    'gtid_mode'

     *Scope*                              Global

     *Dynamic* (>= 5.7.6)                 Yes

     *Dynamic* (<= 5.7.5)                 No

     *Type*                               enumeration

     *Default Value*                      'OFF'

     *Valid Values* (>= 5.7.6)            'OFF' 'OFF_PERMISSIVE'
                                          'ON_PERMISSIVE' 'ON'

     *Valid Values* (<= 5.7.5)            'OFF' 'UPGRADE_STEP_1'
                                          'UPGRADE_STEP_2' 'ON'

     This option specifies whether global transaction identifiers
     (GTIDs) are used to identify transactions.  Setting this option to
     '--gtid-mode=ON' requires that 'enforce-gtid-consistency' be set to
     'ON'.  Prior to MySQL 5.7.6 the 'gtid_mode' variable which this
     option controls could only be set at server startup.  In MySQL
     5.7.6 and later the 'gtid_mode' variable is dynamic and enables
     GTID based replication to be configured online.  Before using this
     feature, see replication-mode-change-online.

     Prior to MySQL 5.7.5, starting the server with '--gtid-mode=ON'
     required that the server also be started with the '--log-bin',
     '--log-slave-updates', options.  In versions of MySQL 5.7.5 and
     later this is not a requirement.  See
     replication-gtids-gtid-executed-table.

   *
     '--gtid-executed-compression-period '

     Property                             Value

     *Command-Line Format*                '--gtid-executed-compression-period=#'

     *Introduced*                         5.7.6

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     Compress the 'mysql.gtid_executed' table each time this many
     transactions have taken place.  A setting of 0 means that this
     table is not compressed.  No compression of the table occurs when
     binary logging is enabled, therefore the option has no effect
     unless 'log_bin' is 'OFF'.

     See replication-gtids-gtid-executed-table-compression, for
     more information.

     In MySQL version 5.7.5, this variable was added as
     'executed_gtids_compression_period' and in MySQL version 5.7.6 it
     was renamed to 'gtid_executed_compression_period'.

*System Variables Used with GTID Replication*

The following system variables are used with GTID-based replication:

   *
     'binlog_gtid_simple_recovery'

     Property                             Value

     *Command-Line Format*                '--binlog-gtid-simple-recovery'

     *Introduced*                         5.7.6

     *System Variable*                    'binlog_gtid_simple_recovery'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value* (>= 5.7.7)           'TRUE'

     *Default Value* (<= 5.7.6)           'FALSE'

     This variable controls how binary log files are iterated during the
     search for GTIDs when MySQL starts or restarts.  In MySQL version
     5.7.5, this variable was added as 'simplified_binlog_gtid_recovery'
     and in MySQL version 5.7.6 it was renamed to
     'binlog_gtid_simple_recovery'.

     When 'binlog_gtid_simple_recovery=FALSE', the method of iterating
     the binary log files is:

        * To initialize 'gtid_executed', binary log files are iterated
          from the newest file, stopping at the first binary log that
          has any 'Previous_gtids_log_event'.  All GTIDs from
          'Previous_gtids_log_event' and 'Gtid_log_events' are read from
          this binary log file.  This GTID set is stored internally and
          called 'gtids_in_binlog'.  The value of 'gtid_executed' is
          computed as the union of this set and the GTIDs stored in the
          'mysql.gtid_executed' table.

          This process could take a long time if you had a large number
          of binary log files without GTID events, for example created
          when 'gtid_mode=OFF'.

        * To initialize 'gtid_purged', binary log files are iterated
          from the oldest to the newest, stopping at the first binary
          log that contains either a 'Previous_gtids_log_event' that is
          nonempty (that has at least one GTID) or that has at least one
          'Gtid_log_event'.  From this binary log it reads
          'Previous_gtids_log_event'.  This GTID set is subtracted from
          'gtids_in_binlog' and the result stored in the internal
          variable 'gtids_in_binlog_not_purged'.  The value of
          'gtid_purged' is initialized to the value of 'gtid_executed',
          minus 'gtids_in_binlog_not_purged'.

     When 'binlog_gtid_simple_recovery=TRUE', which is the default in
     MySQL 5.7.7 and later, the server iterates only the oldest and the
     newest binary log files and the values of 'gtid_purged' and
     'gtid_executed' are computed based only on
     'Previous_gtids_log_event' or 'Gtid_log_event' found in these
     files.  This ensures only two binary log files are iterated during
     server restart or when binary logs are being purged.

     *Note*:

     If this option is enabled, 'gtid_executed' and 'gtid_purged' may be
     initialized incorrectly in the following situations:

        * The newest binary log was generated by MySQL 5.7.5 or older,
          and 'gtid_mode' was 'ON' for some binary logs but 'OFF' for
          the newest binary log.

        * A 'SET GTID_PURGED' statement was issued on a MySQL version
          prior to 5.7.7, and the binary log that was active at the time
          of the 'SET GTID_PURGED' has not yet been purged.

     If an incorrect GTID set is computed in either situation, it will
     remain incorrect even if the server is later restarted, regardless
     of the value of this option.

   *
     'enforce_gtid_consistency'

     Property                             Value

     *Command-Line Format*                '--enforce-gtid-consistency[=value]'

     *System Variable*                    'enforce_gtid_consistency'

     *Scope*                              Global

     *Dynamic* (>= 5.7.6)                 Yes

     *Dynamic* (<= 5.7.5)                 No

     *Type* (>= 5.7.6)                    enumeration

     *Type* (<= 5.7.5)                    boolean

     *Default Value* (>= 5.7.6)           'OFF'

     *Default Value* (<= 5.7.5)           'false'

     *Valid Values* (>= 5.7.6)            'OFF' 'ON' 'WARN'

     Depending on the value of this variable, the server enforces GTID
     consistency by allowing execution of only statements that can be
     safely logged using a GTID. You _must_ set this variable to 'ON'
     before enabling GTID based replication.

     The values that 'enforce_gtid_consistency' can be configured to
     are:

        * 'OFF': all transactions are allowed to violate GTID
          consistency.

        * 'ON': no transaction is allowed to violate GTID consistency.

        * 'WARN': all transactions are allowed to violate GTID
          consistency, but a warning is generated in this case.  'WARN'
          was added in MySQL 5.7.6.

     'enforce_gtid_consistency' only takes effect if binary logging
     takes place for a statement.  If binary logging is disabled on the
     server, or if statements are not written to the binary log because
     they are removed by a filter, GTID consistency is not checked or
     enforced for the statements that are not logged.

     For more information on statements that can be logged using GTID
     based replication, see '--enforce-gtid-consistency'.

     Prior to MySQL 5.7.6, the boolean 'enforce_gtid_consistency'
     defaulted to 'OFF'.  To maintain compatibility with previous
     releases, in MySQL 5.7.6 the enumeration defaults to 'OFF', and
     setting '--enforce-gtid-consistency' without a value is interpreted
     as setting the value to 'ON'.  The variable also has multiple
     textual aliases for the values: '0=OFF=FALSE',
     '1=ON=TRUE','2=WARN'.  This differs from other enumeration types
     but maintains compatibility with the boolean type used in previous
     versions.  These changes impact on what is returned by the
     variable.  Using 'SELECT @@ENFORCE_GTID_CONSISTENCY', 'SHOW
     VARIABLES LIKE 'ENFORCE_GTID_CONSISTENCY'', and 'SELECT * FROM
     INFORMATION_SCHEMA.VARIABLES WHERE 'VARIABLE_NAME' =
     'ENFORCE_GTID_CONSISTENCY'', all return the textual form, not the
     numeric form.  This is an incompatible change, since
     '@@ENFORCE_GTID_CONSISTENCY' returns the numeric form for booleans
     but returns the textual form for 'SHOW' and the Information Schema.

   *
     'executed_gtids_compression_period'

     Property                             Value

     *Introduced*                         5.7.5

     *Deprecated*                         5.7.6

     *System Variable* (>= 5.7.5)         'executed_gtids_compression_period'

     *Scope* (>= 5.7.5)                   Global

     *Dynamic* (>= 5.7.5)                 Yes

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     This option is deprecated and will be removed in a future MySQL
     release.  Use the renamed 'gtid_executed_compression_period' to
     control how the 'gtid_executed' table is compressed.

   *
     'gtid_executed'

     Property                             Value

     *System Variable* (>= 5.7.7)         'gtid_executed'

     *System Variable*                    'gtid_executed'

     *Scope* (>= 5.7.7)                   Global

     *Scope*                              Global, Session

     *Dynamic* (>= 5.7.7)                 No

     *Dynamic*                            No

     *Type*                               string

     When used with global scope, this variable contains a
     representation of the set of all transactions executed on the
     server and GTIDs that have been set by a 'SET'.
     'gtid_purged' statement.  This is the same as the value of the
     'Executed_Gtid_Set' column in the output of 'SHOW MASTER STATUS'
     and 'SHOW SLAVE STATUS'.
     The value of this variable is a GTID set, see
     replication-gtids-concepts-gtid-sets for more information.

     When the server starts, '@@global.gtid_executed' is initialized.
     See 'binlog_gtid_simple_recovery' for more information on how
     binary logs are iterated to populate 'gtid_executed'.  GTIDs are
     then added to the set as transactions are executed, or if any
     'SET'. 'gtid_purged' statement is executed.

     The set of transactions that can be found in the binary logs at any
     given time is equal to 'GTID_SUBTRACT(@@global.gtid_executed,
     @@global.gtid_purged)'; that is, to all transactions in the binary
     log that have not yet been purged.

     Issuing 'RESET MASTER' causes the global value
     (but not the session value) of this variable to be reset to an
     empty string.  GTIDs are not otherwise removed from this set other
     than when the set is cleared due to 'RESET MASTER'.

     Prior to MySQL 5.7.7, this variable could also be used with session
     scope, where it contained a representation of the set of
     transactions that are written to the cache in the current session.
     The session scope was deprecated in MySQL 5.7.7.

   *
     'gtid_executed_compression_period'

     Property                             Value

     *Introduced*                         5.7.6

     *System Variable* (>= 5.7.6)         'gtid_executed_compression_period'

     *Scope* (>= 5.7.6)                   Global

     *Dynamic* (>= 5.7.6)                 Yes

     *Type*                               integer

     *Default Value*                      '1000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     Compress the 'mysql.gtid_executed' table each time this many
     transactions have been processed.  A setting of 0 means that this
     table is not compressed.  Since no compression of the table occurs
     when using the binary log, setting the value of the variable has no
     effect unless binary logging is disabled.

     See replication-gtids-gtid-executed-table-compression, for
     more information.

     In MySQL version 5.7.5, this variable was added as
     'executed_gtids_compression_period' and in MySQL version 5.7.6 it
     was renamed to 'gtid_executed_compression_period'.

   *
     'gtid_mode'

     Property                             Value

     *System Variable*                    'gtid_mode'

     *Scope*                              Global

     *Dynamic* (>= 5.7.6)                 Yes

     *Dynamic* (<= 5.7.5)                 No

     *Type*                               enumeration

     *Default Value*                      'OFF'

     *Valid Values* (>= 5.7.6)            'OFF' 'OFF_PERMISSIVE'
                                          'ON_PERMISSIVE' 'ON'

     *Valid Values* (<= 5.7.5)            'OFF' 'UPGRADE_STEP_1'
                                          'UPGRADE_STEP_2' 'ON'

     Controls whether GTID based logging is enabled and what type of
     transactions the logs can contain.  Prior to MySQL 5.7.6 this
     variable was read-only and was set using the '--gtid-mode' option
     only.  MySQL 5.7.6 enables this variable to be set dynamically.
     You must have the 'SUPER' privilege to set this variable.
     'enforce_gtid_consistency' must be true before you can set
     'gtid_mode=ON'.  Before modifying this variable, see
     replication-mode-change-online.

     Transactions logged in MySQL 5.7.6 and later can be either
     anonymous or use GTIDs.  Anonymous transactions rely on binary log
     file and position to identify specific transactions.  GTID
     transactions have a unique identifier that is used to refer to
     transactions.  The 'OFF_PERMISSIVE' and 'ON_PERMISSIVE' modes added
     in MySQL 5.7.6 permit a mix of these transaction types in the
     topology.  The different modes are now:

        * 'OFF': Both new and replicated transactions must be anonymous.

        * 'OFF_PERMISSIVE': New transactions are anonymous.  Replicated
          transactions can be either anonymous or GTID transactions.

        * 'ON_PERMISSIVE': New transactions are GTID transactions.
          Replicated transactions can be either anonymous or GTID
          transactions.

        * 'ON': Both new and replicated transactions must be GTID
          transactions.

     Changes from one value to another can only be one step at a time.
     For example, if 'gtid_mode' is currently set to 'OFF_PERMISSIVE',
     it is possible to change to 'OFF' or 'ON_PERMISSIVE' but not to
     'ON'.

     In MySQL 5.7.6 and later, the values of 'gtid_purged' and
     'gtid_executed' are persistent regardless of the value of
     'gtid_mode'.  Therefore even after changing the value of
     'gtid_mode', these variables contain the correct values.  In MySQL
     5.7.5 and earlier, the values of 'gtid_purged' and 'gtid_executed'
     are not persistent while 'gtid_mode=OFF'.  Therefore, after
     changing 'gtid_mode' to 'OFF', once all binary logs containing
     GTIDs are purged, the values of these variables are lost.

   *
     'gtid_next'

     Property                             Value

     *System Variable*                    'gtid_next'

     *Scope*                              Session

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'AUTOMATIC'

     *Valid Values*                       'AUTOMATIC' 'ANONYMOUS'
                                          'UUID:NUMBER'

     This variable is used to specify whether and how the next GTID is
     obtained.  'gtid_next' can take any of the following values:

        * 'AUTOMATIC': Use the next automatically-generated global
          transaction ID.

        * 'ANONYMOUS': Transactions do not have global identifiers, and
          are identified by file and position only.

        * A global transaction ID in UUID:NUMBER format.

     Exactly which of the above options are valid depends on the setting
     of 'gtid_mode', see replication-mode-change-online-concepts
     for more information.  Setting this variable has no effect if
     'gtid_mode' is 'OFF'.

     After this variable has been set to UUID:NUMBER, and a transaction
     has been committed or rolled back, an explicit 'SET GTID_NEXT'
     statement must again be issued before any other statement.

     In MySQL 5.7.5 and later, 'DROP TABLE' or 'DROP TEMPORARY TABLE'
     fails with an explicit error when used on a combination of
     nontemporary tables with temporary tables, or of temporary tables
     using transactional storage engines with temporary tables using
     nontransactional storage engines.  Prior to MySQL 5.7.5, when GTIDs
     were enabled but 'gtid_next' was not 'AUTOMATIC', see 'DROP TABLE'
     did not work correctly when used with either of
     these combinations of tables.  (Bug #17620053)

     In MySQL 5.7.1, you cannot execute any of the statements
     'CHANGE MASTER TO', 'START SLAVE',
     see 'STOP SLAVE', 'REPAIR TABLE',
     see 'OPTIMIZE TABLE',
     'ANALYZE TABLE', 'CHECK TABLE',
     'CREATE SERVER', 'ALTER SERVER',
     see 'DROP SERVER', 'CACHE INDEX',
     see 'LOAD INDEX INTO CACHE',
     'FLUSH', or 'RESET' when 'gtid_next' is
     set to any value other than 'AUTOMATIC'; in such cases, the
     statement fails with an error.  Such statements are _not_
     disallowed in MySQL 5.7.2 and later.  (Bug #16062608, Bug
     #16715809, Bug #69045) (Bug #16062608)

   *
     'gtid_owned'

     Property                             Value

     *System Variable*                    'gtid_owned'

     *Scope*                              Global, Session

     *Dynamic*                            No

     *Type*                               string

     This read-only variable holds a list whose contents depend on its
     scope.  When used with session scope, the list holds all GTIDs that
     are owned by this client; when used with global scope, it holds a
     list of all GTIDs along with their owners.

   *
     'gtid_purged'

     Property                             Value

     *System Variable*                    'gtid_purged'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The set of all transactions that have been purged from the binary
     log.  This is a subset of the set of transactions in
     'gtid_executed'.  The value of this variable is a GTID set, see
     replication-gtids-concepts-gtid-sets for more information.

     When the server starts, the global value of 'gtid_purged' is
     initialized to a set of GTIDs.  See 'binlog_gtid_simple_recovery'
     for more information on how binary logs are iterated to populate
     'gtid_purged'.  Issuing 'RESET MASTER' causes
     the value of this variable to be reset to an empty string.

     It is possible to update the value of this variable, but only when
     'gtid_executed' is the empty string, and therefore 'gtid_purged' is
     the empty string.  This can occur either when replication has not
     been started previously, or when replication was not previously
     using GTIDs.  Prior to MySQL 5.7.6, this variable was settable only
     when 'gtid_mode=ON'.  In MySQL 5.7.6 and later, this variable is
     settable regardless of the value of 'gtid_mode'.

     If all existing binary logs were generated using MySQL 5.7.6 or
     later, after issuing a 'SET gtid_purged' statement,
     'binlog_gtid_simple_recovery=TRUE' (the default setting in MySQL
     5.7.7 and later) can safely be used.  If binary logs from MySQL
     5.7.7 or earlier exist, there is a chance that 'gtid_purged' may be
     computed incorrectly.  See 'binlog_gtid_simple_recovery' for more
     information.  If you are using MySQL 5.7.7 or earlier, after
     issuing a 'SET gtid_purged' statement note down the current binary
     log file name, which can be checked using 'SHOW MASTER STATUS'.
     If the server is restarted before
     this file has been purged, then you should use
     'binlog_gtid_simple_recovery=FALSE' to avoid 'gtid_purged' or
     'gtid_executed' being computed incorrectly.

   *
     'simplified_binlog_gtid_recovery'

     Property                             Value

     *Command-Line Format*                '--simplified-binlog-gtid-recovery'

     *Introduced*                         5.7.5

     *Deprecated*                         5.7.6

     *System Variable*                    'simplified_binlog_gtid_recovery'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option is deprecated and will be removed in a future MySQL
     release.  Use the renamed 'binlog_gtid_simple_recovery' to control
     how MySQL iterates through binary log files after a crash.

16.1.7 Common Replication Administration Tasks
----------------------------------------------

Once replication has been started it executes without requiring much
regular administration.  This section describes how to check the status
of replication and how to pause a slave.

16.1.7.1 Checking Replication Status
....................................

The most common task when managing a replication process is to ensure
that replication is taking place and that there have been no errors
between the slave and the master.

The 'SHOW SLAVE STATUS' statement, which you
must execute on each slave, provides information about the configuration
and status of the connection between the slave server and the master
server.  From MySQL 5.7, the Performance Schema has replication tables
that provide this information in a more accessible form.  See
performance-schema-replication-tables.

The 'SHOW STATUS' statement also provided some
information relating specifically to replication slaves.  As of MySQL
version 5.7.5, the following status variables previously monitored using
'SHOW STATUS' were deprecated and moved to the
Performance Schema replication tables:

   * 'Slave_retried_transactions'

   * 'Slave_last_heartbeat'

   * 'Slave_received_heartbeats'

   * 'Slave_heartbeat_period'

   * 'Slave_running'

The replication heartbeat information shown in the Performance Schema
replication tables lets you check that the replication connection is
active even if the master has not sent events to the slave recently.
The master sends a heartbeat signal to a slave if there are no updates
to, and no unsent events in, the binary log for a longer period than the
heartbeat interval.  The 'MASTER_HEARTBEAT_PERIOD' setting on the master
(set by the 'CHANGE MASTER TO' statement)
specifies the frequency of the heartbeat, which defaults to half of the
connection timeout interval for the slave ('slave_net_timeout').  The
'replication_connection_status'.
Performance Schema table shows when
the most recent heartbeat signal was received by a replication slave,
and how many heartbeat signals it has received.

If you are using the 'SHOW SLAVE STATUS'.
statement to check on the status of an individual slave, the statement
provides the following information:

     mysql> SHOW SLAVE STATUS\G
     *************************** 1. row ***************************
                    Slave_IO_State: Waiting for master to send event
                       Master_Host: master1
                       Master_User: root
                       Master_Port: 3306
                     Connect_Retry: 60
                   Master_Log_File: mysql-bin.000004
               Read_Master_Log_Pos: 931
                    Relay_Log_File: slave1-relay-bin.000056
                     Relay_Log_Pos: 950
             Relay_Master_Log_File: mysql-bin.000004
                  Slave_IO_Running: Yes
                 Slave_SQL_Running: Yes
                   Replicate_Do_DB:
               Replicate_Ignore_DB:
                Replicate_Do_Table:
            Replicate_Ignore_Table:
           Replicate_Wild_Do_Table:
       Replicate_Wild_Ignore_Table:
                        Last_Errno: 0
                        Last_Error:
                      Skip_Counter: 0
               Exec_Master_Log_Pos: 931
                   Relay_Log_Space: 1365
                   Until_Condition: None
                    Until_Log_File:
                     Until_Log_Pos: 0
                Master_SSL_Allowed: No
                Master_SSL_CA_File:
                Master_SSL_CA_Path:
                   Master_SSL_Cert:
                 Master_SSL_Cipher:
                    Master_SSL_Key:
             Seconds_Behind_Master: 0
     Master_SSL_Verify_Server_Cert: No
                     Last_IO_Errno: 0
                     Last_IO_Error:
                    Last_SQL_Errno: 0
                    Last_SQL_Error:
       Replicate_Ignore_Server_Ids: 0

The key fields from the status report to examine are:

   * 'Slave_IO_State': The current status of the slave.  See
     slave-io-thread-states, and slave-sql-thread-states, for
     more information.

   * 'Slave_IO_Running': Whether the I/O thread for reading the master's
     binary log is running.  Normally, you want this to be 'Yes' unless
     you have not yet started replication or have explicitly stopped it
     with 'STOP SLAVE'.

   * 'Slave_SQL_Running': Whether the SQL thread for executing events in
     the relay log is running.  As with the I/O thread, this should
     normally be 'Yes'.

   * 'Last_IO_Error', 'Last_SQL_Error': The last errors registered by
     the I/O and SQL threads when processing the relay log.  Ideally
     these should be blank, indicating no errors.

   * 'Seconds_Behind_Master': The number of seconds that the slave SQL
     thread is behind processing the master binary log.  A high number
     (or an increasing one) can indicate that the slave is unable to
     handle events from the master in a timely fashion.

     A value of 0 for 'Seconds_Behind_Master' can usually be interpreted
     as meaning that the slave has caught up with the master, but there
     are some cases where this is not strictly true.  For example, this
     can occur if the network connection between master and slave is
     broken but the slave I/O thread has not yet noticed this--that is,
     'slave_net_timeout' has not yet elapsed.

     It is also possible that transient values for
     'Seconds_Behind_Master' may not reflect the situation accurately.
     When the slave SQL thread has caught up on I/O,
     'Seconds_Behind_Master' displays 0; but when the slave I/O thread
     is still queuing up a new event, 'Seconds_Behind_Master' may show a
     large value until the SQL thread finishes executing the new event.
     This is especially likely when the events have old timestamps; in
     such cases, if you execute 'SHOW SLAVE STATUS'
     several times in a relatively short period, you
     may see this value change back and forth repeatedly between 0 and a
     relatively large value.

Several pairs of fields provide information about the progress of the
slave in reading events from the master binary log and processing them
in the relay log:

   * ('Master_Log_file', 'Read_Master_Log_Pos'): Coordinates in the
     master binary log indicating how far the slave I/O thread has read
     events from that log.

   * ('Relay_Master_Log_File', 'Exec_Master_Log_Pos'): Coordinates in
     the master binary log indicating how far the slave SQL thread has
     executed events received from that log.

   * ('Relay_Log_File', 'Relay_Log_Pos'): Coordinates in the slave relay
     log indicating how far the slave SQL thread has executed the relay
     log.  These correspond to the preceding coordinates, but are
     expressed in slave relay log coordinates rather than master binary
     log coordinates.

On the master, you can check the status of connected slaves using
'SHOW PROCESSLIST' to examine the list of running
processes.  Slave connections have 'Binlog Dump' in the 'Command' field:

     mysql> SHOW PROCESSLIST \G;
     *************************** 4. row ***************************
          Id: 10
        User: root
        Host: slave1:58371
          db: NULL
     Command: Binlog Dump
        Time: 777
       State: Has sent all binlog to slave; waiting for binlog to be updated
        Info: NULL

Because it is the slave that drives the replication process, very little
information is available in this report.

For slaves that were started with the '--report-host' option and are
connected to the master, the 'SHOW SLAVE HOSTS'.
statement on the master shows basic information about the slaves.  The
output includes the ID of the slave server, the value of the
'--report-host' option, the connecting port, and master ID:

     mysql> SHOW SLAVE HOSTS;
     +-----------+--------+------+-------------------+-----------+
     | Server_id | Host   | Port | Rpl_recovery_rank | Master_id |
     +-----------+--------+------+-------------------+-----------+
     |        10 | slave1 | 3306 |                 0 |         1 |
     +-----------+--------+------+-------------------+-----------+
     1 row in set (0.00 sec)

16.1.7.2 Pausing Replication on the Slave
.........................................

You can stop and start replication on the slave using the 'STOP SLAVE'
and 'START SLAVE' statements.

To stop processing of the binary log from the master, use 'STOP SLAVE'.:

     mysql> STOP SLAVE;

When replication is stopped, the slave I/O thread stops reading events
from the master binary log and writing them to the relay log, and the
SQL thread stops reading events from the relay log and executing them.
You can pause the I/O or SQL thread individually by specifying the
thread type:

     mysql> STOP SLAVE IO_THREAD;
     mysql> STOP SLAVE SQL_THREAD;

To start execution again, use the 'START SLAVE'.
statement:

     mysql> START SLAVE;

To start a particular thread, specify the thread type:

     mysql> START SLAVE IO_THREAD;
     mysql> START SLAVE SQL_THREAD;

For a slave that performs updates only by processing events from the
master, stopping only the SQL thread can be useful if you want to
perform a backup or other task.  The I/O thread will continue to read
events from the master but they are not executed.  This makes it easier
for the slave to catch up when you restart the SQL thread.

Stopping only the I/O thread enables the events in the relay log to be
executed by the SQL thread up to the point where the relay log ends.
This can be useful when you want to pause execution to catch up with
events already received from the master, when you want to perform
administration on the slave but also ensure that it has processed all
updates to a specific point.  This method can also be used to pause
event receipt on the slave while you conduct administration on the
master.  Stopping the I/O thread but permitting the SQL thread to run
helps ensure that there is not a massive backlog of events to be
executed when replication is started again.

16.2 Replication Implementation
===============================

Replication is based on the master server keeping track of all changes
to its databases (updates, deletes, and so on) in its binary log.  The
binary log serves as a written record of all events that modify database
structure or content (data) from the moment the server was started.
Typically, see 'SELECT' statements are not recorded because
they modify neither database structure nor content.

Each slave that connects to the master requests a copy of the binary
log.  That is, it pulls the data from the master, rather than the master
pushing the data to the slave.  The slave also executes the events from
the binary log that it receives.  This has the effect of repeating the
original changes just as they were made on the master.  Tables are
created or their structure modified, and data is inserted, deleted, and
updated according to the changes that were originally made on the
master.

Because each slave is independent, the replaying of the changes from the
master's binary log occurs independently on each slave that is connected
to the master.  In addition, because each slave receives a copy of the
binary log only by requesting it from the master, the slave is able to
read and update the copy of the database at its own pace and can start
and stop the replication process at will without affecting the ability
to update to the latest database status on either the master or slave
side.

For more information on the specifics of the replication implementation,
see replication-implementation-details.

Masters and slaves report their status in respect of the replication
process regularly so that you can monitor them.  See
thread-information, for descriptions of all replicated-related states.

The master binary log is written to a local relay log on the slave
before it is processed.  The slave also records information about the
current position with the master's binary log and the local relay log.
See slave-logs.

Database changes are filtered on the slave according to a set of rules
that are applied according to the various configuration options and
variables that control event evaluation.  For details on how these rules
are applied, see replication-rules.

16.2.1 Replication Formats
--------------------------

Replication works because events written to the binary log are read from
the master and then processed on the slave.  The events are recorded
within the binary log in different formats according to the type of
event.  The different replication formats used correspond to the binary
logging format used when the events were recorded in the master's binary
log.  The correlation between binary logging formats and the terms used
during replication are:

   * When using statement-based binary logging, the master writes SQL
     statements to the binary log.  Replication of the master to the
     slave works by executing the SQL statements on the slave.  This is
     called _statement-based replication_ (which can be abbreviated as
     _SBR_), which corresponds to the standard MySQL statement-based
     binary logging format.

   * When using row-based logging, the master writes _events_ to the
     binary log that indicate how individual table rows are changed.
     Replication of the master to the slave works by copying the events
     representing the changes to the table rows to the slave.  This is
     called _row-based replication_ (which can be abbreviated as _RBR_).

   * You can also configure MySQL to use a mix of both statement-based
     and row-based logging, depending on which is most appropriate for
     the change to be logged.  This is called _mixed-format logging_.
     When using mixed-format logging, a statement-based log is used by
     default.  Depending on certain statements, and also the storage
     engine being used, the log is automatically switched to row-based
     in particular cases.  Replication using the mixed format is
     referred to as _mixed-based replication_ or _mixed-format
     replication_.  For more information, see binary-log-mixed.

Prior to MySQL 5.7.7, statement-based format was the default.  In MySQL
5.7.7 and later, row-based format is the default.

NDB Cluster

The default binary logging format in MySQL NDB Cluster 7.5 is 'MIXED'.
You should note that NDB Cluster Replication always uses row-based
replication, and that the 'NDB' storage engine is
incompatible with statement-based replication.  See
mysql-cluster-replication-general, for more information.

When using 'MIXED' format, the binary logging format is determined in
part by the storage engine being used and the statement being executed.
For more information on mixed-format logging and the rules governing the
support of different logging formats, see binary-log-mixed.

The logging format in a running MySQL server is controlled by setting
the 'binlog_format' server system variable.  This variable can be set
with session or global scope.  The rules governing when and how the new
setting takes effect are the same as for other MySQL server system
variables.  Setting the variable for the current session lasts only
until the end of that session, and the change is not visible to other
sessions.  Setting the variable globally takes effect for clients that
connect after the change, but not for any current client sessions,
including the session where the variable setting was changed.  To make
the global system variable setting permanent so that it applies across
server restarts, you must set it in an option file.  For more
information, see set-variable.

There are conditions under which you cannot change the binary logging
format at runtime or doing so causes replication to fail.  See
binary-log-setting.

You must have the 'SUPER' privilege to set either the global or session
'binlog_format' value.

The statement-based and row-based replication formats have different
issues and limitations.  For a comparison of their relative advantages
and disadvantages, see replication-sbr-rbr.

With statement-based replication, you may encounter issues with
replicating stored routines or triggers.  You can avoid these issues by
using row-based replication instead.  For more information, see
stored-programs-logging.

16.2.1.1 Advantages and Disadvantages of Statement-Based and Row-Based Replication
..................................................................................

Each binary logging format has advantages and disadvantages.  For most
users, the mixed replication format should provide the best combination
of data integrity and performance.  If, however, you want to take
advantage of the features specific to the statement-based or row-based
replication format when performing certain tasks, you can use the
information in this section, which provides a summary of their relative
advantages and disadvantages, to determine which is best for your needs.

   * Advantages of statement-based replication

   * Disadvantages of statement-based replication

   * Advantages of row-based replication

   * Disadvantages of row-based replication

*Advantages of statement-based replication*

   * Proven technology.

   * Less data written to log files.  When updates or deletes affect
     many rows, this results in _much_ less storage space required for
     log files.  This also means that taking and restoring from backups
     can be accomplished more quickly.

   * Log files contain all statements that made any changes, so they can
     be used to audit the database.

*Disadvantages of statement-based replication*

   * Statements that are unsafe for SBR

     Not all statements which modify data (such as 'INSERT'.
     See 'DELETE', 'UPDATE', and
     'REPLACE' statements) can be replicated using
     statement-based replication.  Any nondeterministic behavior is
     difficult to replicate when using statement-based replication.
     Examples of such Data Modification Language (DML) statements
     include the following:

        * A statement that depends on a UDF or stored program that is
          nondeterministic, since the value returned by such a UDF or
          stored program or depends on factors other than the parameters
          supplied to it.  (Row-based replication, however, simply
          replicates the value returned by the UDF or stored program, so
          its effect on table rows and data is the same on both the
          master and slave.)  See replication-features-invoked,
          for more information.

        * 'DELETE' and 'UPDATE' statements
          that use a 'LIMIT' clause without an 'ORDER BY' are
          nondeterministic.  See replication-features-limit.

        * Deterministic UDFs must be applied on the slaves.

        * Statements using any of the following functions cannot be
          replicated properly using statement-based replication:

             * 'LOAD_FILE()'

             * 'UUID()', 'UUID_SHORT()'

             * 'USER()'

             * 'FOUND_ROWS()'

             * 'SYSDATE()' (unless both the master and the slave are
               started with the '--sysdate-is-now' option)

             * 'GET_LOCK()'

             * 'IS_FREE_LOCK()'

             * 'IS_USED_LOCK()'

             * 'MASTER_POS_WAIT()'

             * 'RAND()'

             * 'RELEASE_LOCK()'

             * 'SLEEP()'

             * 'VERSION()'

          However, all other functions are replicated correctly using
          statement-based replication, including 'NOW()' and so forth.

          For more information, see
          replication-features-functions.

     Statements that cannot be replicated correctly using
     statement-based replication are logged with a warning like the one
     shown here:

          [Warning] Statement is not safe to log in statement format.

     A similar warning is also issued to the client in such cases.  The
     client can display it using 'SHOW WARNINGS'.

   * 'INSERT ... SELECT' requires a greater number of
     row-level locks than with row-based replication.

   * 'UPDATE' statements that require a table scan
     (because no index is used in the 'WHERE' clause) must lock a
     greater number of rows than with row-based replication.

   * For 'InnoDB'.: An 'INSERT'
     statement that uses 'AUTO_INCREMENT' blocks other
     nonconflicting 'INSERT' statements.

   * For complex statements, the statement must be evaluated and
     executed on the slave before the rows are updated or inserted.
     With row-based replication, the slave only has to modify the
     affected rows, not execute the full statement.

   * If there is an error in evaluation on the slave, particularly when
     executing complex statements, statement-based replication may
     slowly increase the margin of error across the affected rows over
     time.  See replication-features-slaveerrors.

   * Stored functions execute with the same 'NOW()' value as the calling
     statement.  However, this is not true of stored procedures.

   * Deterministic UDFs must be applied on the slaves.

   * Table definitions must be (nearly) identical on master and slave.
     See replication-features-differing-tables, for more
     information.

*Advantages of row-based replication*

   * All changes can be replicated.  This is the safest form of
     replication.

     *Note*:

     Statements that update the information in the 'mysql'
     database--such as 'GRANT', 'REVOKE' and
     the manipulation of triggers, stored routines (including stored
     procedures), and views--are all replicated to slaves using
     statement-based replication.

     For statements such as 'CREATE TABLE ... SELECT',
     a 'CREATE' statement is generated from the table
     definition and replicated using statement-based format, while the
     row insertions are replicated using row-based format.

   * Fewer row locks are required on the master, which thus achieves
     higher concurrency, for the following types of statements:

        * 'INSERT ... SELECT'.

        * 'INSERT' statements with 'AUTO_INCREMENT'

        * 'UPDATE' or 'DELETE' statements
          with 'WHERE' clauses that do not use keys or do not change
          most of the examined rows.

   * Fewer row locks are required on the slave for any 'INSERT',
     see 'UPDATE', or 'DELETE'.
     statement.

*Disadvantages of row-based replication*

   * RBR can generate more data that must be logged.  To replicate a DML
     statement (such as an 'UPDATE' or 'DELETE'
     statement), statement-based replication writes only the
     statement to the binary log.  By contrast, row-based replication
     writes each changed row to the binary log.  If the statement
     changes many rows, row-based replication may write significantly
     more data to the binary log; this is true even for statements that
     are rolled back.  This also means that making and restoring a
     backup can require more time.  In addition, the binary log is
     locked for a longer time to write the data, which may cause
     concurrency problems.  Use 'binlog_row_image=minimal' to reduce the
     disadvantage considerably.

   * Deterministic UDFs that generate large 'BLOB' values
     take longer to replicate with row-based replication than with
     statement-based replication.  This is because the 'BLOB'
     column value is logged, rather than the statement generating
     the data.

   * You cannot see on the slave what statements were received from the
     master and executed.  However, you can see what data was changed
     using 'mysqlbinlog' with the options
     '--base64-output=DECODE-ROWS' and '--verbose'.

     Alternatively, use the 'binlog_rows_query_log_events' variable,
     which if enabled adds a 'Rows_query' event with the statement to
     'mysqlbinlog' output when the '-vv' option is
     used.

   * For tables using the 'MyISAM' storage
     engine, a stronger lock is required on the slave for
     'INSERT' statements when applying them as row-based events
     to the binary log than when applying them as statements.  This
     means that concurrent inserts on 'MyISAM'
     tables are not supported when using
     row-based replication.

16.2.1.2 Usage of Row-Based Logging and Replication
...................................................

MySQL uses statement-based logging (SBL), row-based logging (RBL) or
mixed-format logging.  The type of binary log used impacts the size and
efficiency of logging.Therefore the choice between row-based replication
(RBR) or statement-based replication (SBR) depends on your application
and environment.

This section describes known issues when using a row-based format log,
and describes some best practices using it in replication.

For additional information, see replication-formats, and
replication-sbr-rbr.

For information about issues specific to NDB Cluster Replication (which
depends on row-based replication), see
mysql-cluster-replication-issues.

   * Row-based logging of temporary tables

     As noted in replication-features-temptables, temporary
     tables are not replicated when using row-based format.  When using
     mixed format logging, 'safe' statements involving temporary tables
     are logged using statement-based format.  For more information, see
     replication-sbr-rbr.

     Temporary tables are not replicated when using row-based format
     because there is no need.  In addition, because temporary tables
     can be read only from the thread which created them, there is
     seldom if ever any benefit obtained from replicating them, even
     when using statement-based format.

     In MySQL 5.7, you can switch from statement-based to row-based
     binary logging mode even when temporary tables have been created.
     However, while using the row-based format, the MySQL server cannot
     determine the logging mode that was in effect when a given
     temporary table was created.  For this reason, the server in such
     cases logs a 'DROP TEMPORARY TABLE IF EXISTS'.
     statement for each temporary table that still exists for a given
     client session when that session ends.  While this means that it is
     possible that an unnecessary 'DROP TEMPORARY TABLE' statement might
     be logged in some cases, the statement is harmless, and does not
     cause an error even if the table does not exist, due to the
     presence of the 'IF EXISTS' option.

     Nontransactional DML statements involving temporary tables are
     allowed when using 'binlog_format=ROW', as long as any
     nontransactional tables affected by the statements are temporary
     tables (Bug #14272672).

   * RBL and synchronization of nontransactional tables

     When many rows are affected, the set of changes is split into
     several events; when the statement commits, all of these events are
     written to the binary log.  When executing on the slave, a table
     lock is taken on all tables involved, and then the rows are applied
     in batch mode.  Depending on the engine used for the slave's copy
     of the table, this may or may not be effective.

   * Latency and binary log size

     RBL writes changes for each row to the binary log and so its size
     can increase quite rapidly.  This can significantly increase the
     time required to make changes on the slave that match those on the
     master.  You should be aware of the potential for this delay in
     your applications.

   * Reading the binary log

     'mysqlbinlog' displays row-based events in the
     binary log using the 'BINLOG' statement (see binlog).  This
     statement displays an event as a base 64-encoded string, the
     meaning of which is not evident.  When invoked with the
     '--base64-output=DECODE-ROWS' and '--verbose' options, see
     'mysqlbinlog' formats the contents of the binary log
     to be human readable.  When binary log events were written in
     row-based format and you want to read or recover from a replication
     or database failure you can use this command to read contents of
     the binary log.  For more information, see
     mysqlbinlog-row-events.

   * Binary log execution errors and slave_exec_mode

     Using 'slave_exec_mode=IDEMPOTENT' is generally only useful with
     MySQL NDB Cluster replication, for which 'IDEMPOTENT' is the
     default value.  (See
     mysql-cluster-replication-multi-master).  When 'slave_exec_mode'
     is 'IDEMPOTENT', a failure to apply changes from RBL because the
     original row cannot be found does not trigger an error or cause
     replication to fail.  This means that it is possible that updates
     are not applied on the slave, so that the master and slave are no
     longer synchronized.  Latency issues and use of nontransactional
     tables with RBR when 'slave_exec_mode' is 'IDEMPOTENT' can cause
     the master and slave to diverge even further.  For more information
     about 'slave_exec_mode', see server-system-variables.

     For other scenarios, setting 'slave_exec_mode' to 'STRICT' is
     normally sufficient; this is the default value for storage engines
     other than 'NDB'.

   * Filtering based on server ID not supported

     You can filter based on server ID by using the 'IGNORE_SERVER_IDS'
     option for the 'CHANGE MASTER TO'.
     statement.  This option works with statement-based and row-based
     logging formats.  Another method to filter out changes on some
     slaves is to use a 'WHERE' clause that includes the relation
     '@@server_id <> ID_VALUE' clause with 'UPDATE' and
     'DELETE' statements.  For example, 'WHERE
     @@server_id <> 1'.  However, this does not work correctly with
     row-based logging.  To use the 'server_id' system variable for
     statement filtering, use statement-based logging.

   * Database-level replication options

     The effects of the '--replicate-do-db', '--replicate-ignore-db',
     and '--replicate-rewrite-db' options differ considerably depending
     on whether row-based or statement-based logging is used.
     Therefore, it is recommended to avoid database-level options and
     instead use table-level options such as '--replicate-do-table' and
     '--replicate-ignore-table'.  For more information about these
     options and the impact replication format has on how they operate,
     see replication-options.

   * RBL, nontransactional tables, and stopped slaves

     When using row-based logging, if the slave server is stopped while
     a slave thread is updating a nontransactional table, the slave
     database can reach an inconsistent state.  For this reason, it is
     recommended that you use a transactional storage engine such as
     'InnoDB' for all tables replicated
     using the row-based format.  Use of 'STOP SLAVE'.
     or 'STOP SLAVE SQL_THREAD' prior to shutting
     down the slave MySQL server helps prevent issues from occurring,
     and is always recommended regardless of the logging format or
     storage engine you use.

16.2.1.3 Determination of Safe and Unsafe Statements in Binary Logging
......................................................................

The 'safeness' of a statement in MySQL Replication, refers to whether
the statement and its effects can be replicated correctly using
statement-based format.  If this is true of the statement, we refer to
the statement as _safe_; otherwise, we refer to it as _unsafe_.

In general, a statement is safe if it deterministic, and unsafe if it is
not.  However, certain nondeterministic functions are _not_ considered
unsafe (see replication-rbr-safe-unsafe-not, later in this
section).  In addition, statements using results from floating-point
math functions--which are hardware-dependent--are always considered
unsafe (see replication-features-floatvalues).

Handling of safe and unsafe statements

A statement is treated differently depending on whether the statement is
considered safe, and with respect to the binary logging format (that is,
the current value of 'binlog_format').

   * When using row-based logging, no distinction is made in the
     treatment of safe and unsafe statements.

   * When using mixed-format logging, statements flagged as unsafe are
     logged using the row-based format; statements regarded as safe are
     logged using the statement-based format.

   * When using statement-based logging, statements flagged as being
     unsafe generate a warning to this effect.  Safe statements are
     logged normally.

Each statement flagged as unsafe generates a warning.  Formerly, if a
large number of such statements were executed on the master, this could
lead to excessively large error log files.  To prevent this, MySQL 5.7
provides a warning suppression mechanism, which behaves as follows:
Whenever the 50 most recent 'ER_BINLOG_UNSAFE_STATEMENT' warnings have
been generated more than 50 times in any 50-second period, warning
suppression is enabled.  When activated, this causes such warnings not
to be written to the error log; instead, for each 50 warnings of this
type, a note 'The last warning was repeated N times in last S seconds'
is written to the error log.  This continues as long as the 50 most
recent such warnings were issued in 50 seconds or less; once the rate
has decreased below this threshold, the warnings are once again logged
normally.  Warning suppression has no effect on how the safety of
statements for statement-based logging is determined, nor on how
warnings are sent to the client.  MySQL clients still receive one
warning for each such statement.

For more information, see replication-formats.

Statements considered unsafe

Statements with the following characteristics are considered unsafe:

   * Statements containing system functions that may return a different
     value on slave.

     These functions include 'FOUND_ROWS()', 'GET_LOCK()',
     'IS_FREE_LOCK()', 'IS_USED_LOCK()', 'LOAD_FILE()',
     'MASTER_POS_WAIT()', 'PASSWORD()', 'RAND()', 'RELEASE_LOCK()',
     'ROW_COUNT()', 'SESSION_USER()', 'SLEEP()', 'SYSDATE()',
     'SYSTEM_USER()', 'USER()', 'UUID()', and 'UUID_SHORT()'.

     Nondeterministic functions not considered unsafe

     Although these functions are not deterministic, they are treated as
     safe for purposes of logging and replication: 'CONNECTION_ID()',
     'CURDATE()', 'CURRENT_DATE()', 'CURRENT_TIME()',
     'CURRENT_TIMESTAMP()', 'CURTIME()',, 'LAST_INSERT_ID()',
     'LOCALTIME()', 'LOCALTIMESTAMP()', 'NOW()', 'UNIX_TIMESTAMP()',
     'UTC_DATE()', 'UTC_TIME()', and 'UTC_TIMESTAMP()'.

     For more information, see replication-features-functions.

   * References to system variables

     Most system variables are not replicated correctly using the
     statement-based format.  See
     replication-features-variables.  For exceptions, see
     binary-log-mixed.

   * UDFs

     Since we have no control over what a UDF does, we must assume that
     it is executing unsafe statements.

   * Fulltext plugin

     This plugin may behave differently on different MySQL servers;
     therefore, statements depending on it could have different results.
     For this reason, all statements relying on the fulltext plugin are
     treated as unsafe (Bug #11756280, Bug #48183).

   * Trigger or stored program updates a table having an AUTO_INCREMENT
     column

     This is unsafe because the order in which the rows are updated may
     differ on the master and the slave.

     In addition, an 'INSERT' into a table that has a
     composite primary key containing an 'AUTO_INCREMENT' column that is
     not the first column of this composite key is unsafe.

     For more information, see
     replication-features-auto-increment.

   * INSERT ...  ON DUPLICATE KEY UPDATE statements on tables with
     multiple primary or unique keys

     When executed against a table that contains more than one primary
     or unique key, this statement is considered unsafe, being sensitive
     to the order in which the storage engine checks the keys, which is
     not deterministic, and on which the choice of rows updated by the
     MySQL Server depends.

     An 'INSERT ... ON DUPLICATE KEY UPDATE'.
     statement against a table having more than one unique or primary
     key is marked as unsafe for statement-based replication.  (Bug
     #11765650, Bug #58637)

   * Updates using LIMIT

     The order in which rows are retrieved is not specified, and is
     therefore considered unsafe.  See
     replication-features-limit.

   * Accesses or references log tables

     The contents of the system log table may differ between master and
     slave.

   * Nontransactional operations after transactional operations

     Within a transaction, allowing any nontransactional reads or writes
     to execute after any transactional reads or writes is considered
     unsafe.

     For more information, see
     replication-features-transactions.

   * Accesses or references self-logging tables

     All reads and writes to self-logging tables are considered unsafe.
     Within a transaction, any statement following a read or write to
     self-logging tables is also considered unsafe.

   * LOAD DATA INFILE statements

     'LOAD DATA INFILE' is treated as unsafe and when
     'binlog_format=mixed' the statement is logged in row-based format.
     When 'binlog_format=statement' 'LOAD DATA INFILE'.
     does not generate a warning, unlike other unsafe statements.

   * XA transactions

     If two XA transactions committed in parallel on the master are
     being prepared on the slave in the inverse order, locking
     dependencies can occur with statement-based replication that cannot
     be safely resolved, and it is possible for replication to fail with
     deadlock on the slave.  When 'binlog_format=STATEMENT' is set, DML
     statements inside XA transactions are flagged as being unsafe and
     generate a warning.  When 'binlog_format=MIXED' or
     'binlog_format=ROW' is set, DML statements inside XA transactions
     are logged using row-based replication, and the potential issue is
     not present.

For additional information, see replication-features.

16.2.2 Replication Implementation Details
-----------------------------------------

MySQL replication capabilities are implemented using three threads, one
on the master server and two on the slave:

   * Binlog dump thread

     The master creates a thread to send the binary log contents to a
     slave when the slave connects.  This thread can be identified in
     the output of 'SHOW PROCESSLIST' on the
     master as the 'Binlog Dump' thread.

     The binary log dump thread acquires a lock on the master's binary
     log for reading each event that is to be sent to the slave.  As
     soon as the event has been read, the lock is released, even before
     the event is sent to the slave.

   * Slave I/O thread

     When a 'START SLAVE' statement is issued on a
     slave server, the slave creates an I/O thread, which connects to
     the master and asks it to send the updates recorded in its binary
     logs.

     The slave I/O thread reads the updates that the master's 'Binlog
     Dump' thread sends (see previous item) and copies them to local
     files that comprise the slave's relay log.

     The state of this thread is shown as 'Slave_IO_running' in the
     output of 'SHOW SLAVE STATUS' or as
     'Slave_running' in the output of 'SHOW STATUS'.

   * Slave SQL thread

     The slave creates an SQL thread to read the relay log that is
     written by the slave I/O thread and execute the events contained
     therein.

In the preceding description, there are three threads per master/slave
connection.  A master that has multiple slaves creates one binary log
dump thread for each currently connected slave, and each slave has its
own I/O and SQL threads.

A slave uses two threads to separate reading updates from the master and
executing them into independent tasks.  Thus, the task of reading
statements is not slowed down if statement execution is slow.  For
example, if the slave server has not been running for a while, its I/O
thread can quickly fetch all the binary log contents from the master
when the slave starts, even if the SQL thread lags far behind.  If the
slave stops before the SQL thread has executed all the fetched
statements, the I/O thread has at least fetched everything so that a
safe copy of the statements is stored locally in the slave's relay logs,
ready for execution the next time that the slave starts.

The 'SHOW PROCESSLIST' statement provides
information that tells you what is happening on the master and on the
slave regarding replication.  For information on master states, see
master-thread-states.  For slave states, see
slave-io-thread-states, and slave-sql-thread-states.

The following example illustrates how the three threads show up in the
output from 'SHOW PROCESSLIST'.

On the master server, the output from 'SHOW PROCESSLIST'
looks like this:

     mysql> SHOW PROCESSLIST\G
     *************************** 1. row ***************************
          Id: 2
        User: root
        Host: localhost:32931
          db: NULL
     Command: Binlog Dump
        Time: 94
       State: Has sent all binlog to slave; waiting for binlog to
              be updated
        Info: NULL

Here, thread 2 is a 'Binlog Dump' replication thread that services a
connected slave.  The 'State' information indicates that all outstanding
updates have been sent to the slave and that the master is waiting for
more updates to occur.  If you see no 'Binlog Dump' threads on a master
server, this means that replication is not running; that is, no slaves
are currently connected.

On a slave server, the output from 'SHOW PROCESSLIST'
looks like this:

     mysql> SHOW PROCESSLIST\G
     *************************** 1. row ***************************
          Id: 10
        User: system user
        Host:
          db: NULL
     Command: Connect
        Time: 11
       State: Waiting for master to send event
        Info: NULL
     *************************** 2. row ***************************
          Id: 11
        User: system user
        Host:
          db: NULL
     Command: Connect
        Time: 11
       State: Has read all relay log; waiting for the slave I/O
              thread to update it
        Info: NULL

The 'State' information indicates that thread 10 is the I/O thread that
is communicating with the master server, and thread 11 is the SQL thread
that is processing the updates stored in the relay logs.  At the time
that 'SHOW PROCESSLIST' was run, both threads
were idle, waiting for further updates.

The value in the 'Time' column can show how late the slave is compared
to the master.  See faqs-replication.  If sufficient time
elapses on the master side without activity on the 'Binlog Dump' thread,
the master determines that the slave is no longer connected.  As for any
other client connection, the timeouts for this depend on the values of
'net_write_timeout' and 'net_retry_count'; for more information about
these, see server-system-variables.

The 'SHOW SLAVE STATUS' statement provides
additional information about replication processing on a slave server.
See replication-administration-status.

16.2.3 Replication Channels
---------------------------

MySQL 5.7.6 introduces the concept of a replication channel, which
represents the path of transactions flowing from a master to a slave.
This section describes how channels can be used in a replication
topology, and the impact they have on single-source replication.

To provide compatibity with previous versions, the MySQL server
automatically creates on startup a default channel whose name is the
empty string ('""').  This channel is always present; it cannot be
created or destroyed by the user.  If no other channels (having nonempty
names) have been created, replication statements act on the default
channel only, so that all replication statements from older slaves
function as expected (see channels-with-prev-replication.
Statements applying to replication channels as described in this section
can be used only when there is at least one named channel.

A replication channel encompasses the path of transactions transmitted
from a master to a slave.  In multi-source replication a slave opens
multiple channels, one per master, and each channel has its own relay
log and applier (SQL) threads.  Once transactions are received by a
replication channel's receiver (I/O) thread, they are added to the
channel's relay log file and passed through to an applier thread.  This
enables channels to function independently.

A replication channel is also associated with a host name and port.  You
can assign multiple channels to the same combination of host name and
port; in MySQL 5.7, the maximum number of channels that can be added to
one slave in a multi-source replication topology is 256.  Each
replication channel must have a unique (nonempty) name (see
channels-naming-conventions).  Channels can be configured
independently.

16.2.3.1 Commands for Operations on a Single Channel
....................................................

To enable MySQL replication operations to act on individual replication
channels, use the 'FOR CHANNEL CHANNEL' clause with the following
replication statements:

   * 'CHANGE MASTER TO'.

   * 'START SLAVE'.

   * 'STOP SLAVE'.

   * 'SHOW RELAYLOG EVENTS'.

   * 'FLUSH RELAY LOGS'

   * 'SHOW SLAVE STATUS'.

   * 'RESET SLAVE'.

Similarly, an additional 'channel' parameter is introduced for the
following functions:

   * 'MASTER_POS_WAIT()'

   * 'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()'

Beginning with MySQL 5.7.9, the following statements are disallowed for
the 'group_replication_recovery' channel.

   * 'START SLAVE'.

   * 'STOP SLAVE'.

16.2.3.2 Compatibility with Previous Replication Statements
...........................................................

When a replication slave has multiple channels and a 'FOR CHANNEL
CHANNEL' option is not specified, a valid statement generally acts on
all available channels.

For example, the following statements behave as expected:

   * 'START SLAVE' starts replication threads for
     all channels, except the 'group_replication_recovery' channel.

   * 'STOP SLAVE' stops replication threads for all
     channels, except the 'group_replication_recovery' channel.

   * 'SHOW SLAVE STATUS' reports the status
     for all channels.

   * 'FLUSH RELAY LOGS' flushes the relay logs for all channels.

   * 'RESET SLAVE' resets all channels.

*Warning*:

Use 'RESET SLAVE' with caution as this statement deletes all existing
channels, purges their relay log files, and recreates only the default
channel.

Some replication statements cannot operate on all channels.  In this
case, error 1964 'Multiple channels exist on the slave. Please provide
channel name as an argument.' is generated.  The following statements
and functions generate this error when used in a multi-source
replication topology and a 'FOR CHANNEL CHANNEL' option is not used to
specify which channel to act on:

   * 'SHOW RELAYLOG EVENTS'.

   * 'CHANGE MASTER TO'.

   * 'MASTER_POS_WAIT()'

   * 'WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()'

   * 'WAIT_FOR_EXECUTED_GTID_SET()'

Note that a default channel always exists in a single source replication
topology, where statements and functions behave as in previous versions
of MySQL.

16.2.3.3 Startup Options and Replication Channels
.................................................

This section describes startup options which are impacted by the
addition of replication channels.

The following startup options _must_ be configured correctly to use
multi-source replication.

   * '--relay-log-info-repository'

     This must be set to 'TABLE'.  If this option is set to 'FILE',
     attempting to add more sources to a slave fails with
     'ER_SLAVE_NEW_CHANNEL_WRONG_REPOSITORY'.

   * '--master-info-repository'

     This must be set to 'TABLE'.  If this option is set to 'FILE',
     attempting to add more sources to a slave fails with
     'ER_SLAVE_NEW_CHANNEL_WRONG_REPOSITORY'.

The following startup options now affect _all_ channels in a replication
topology.

   * '--log-slave-updates'

     All transactions received by the slave (even from multiple sources)
     are written in the binary log.

   * '--relay-log-purge'

     When set, each channel purges its own relay log automatically.

   * '--slave_transaction_retries'

     Applier threads of all channels retry transactions.

   * '--skip-slave-start'

     No replication threads start on any channels.

   * '--slave-skip-errors'

     Execution continues and errors are skipped for all channels.

The values set for the following startup options apply on each channel;
since these are 'mysqld' startup options, they are
applied on every channel.

   * '--max-relay-log-size=SIZE'

     Maximum size of the individual relay log file for each channel;
     after reaching this limit, the file is rotated.

   * '--relay-log-space-limit=SIZE'

     Upper limit for the total size of all relay logs combined, for each
     individual channel.  For N channels, the combined size of these
     logs is limited to 'relay_log_space_limit * N'.

   * '--slave-parallel-workers=VALUE'

     Number of slave parallel workers per channel.

   * '--slave-checkpoint-group'

     Waiting time by an I/O thread for each source.

   * '--relay-log-index=filename'

     Base name for each channel's relay log index file.  See
     channels-naming-conventions.

   * '--relay-log=filename'

     Denotes the base name of each channel's relay log file.  See
     channels-naming-conventions.

   * '--slave_net-timeout=N'

     This value is set per channel, so that each channel waits for N
     seconds to check for a broken connection.

   * '--slave-skip-counter=N'

     This value is set per channel, so that each channel skips N events
     from its master.

16.2.3.4 Replication Channel Naming Conventions
...............................................

This section describes how naming conventions are impacted by
replication channels.

Each replication channel has a unique name which is a string with a
maximum length of 64 characters and is case insensitive.  Because
channel names are used in slave tables, the character set used for these
is always UTF-8.  Although you are generally free to use any name for
channels, the following names are reserved:

   * 'group_replication_applier'

   * 'group_replication_recovery'

The name you choose for a replication channel also influences the file
names used by a multi-source replication slave.  The relay log files and
index files for each channel are named
'RELAY_LOG_BASENAME-CHANNEL.xxxxxx', where RELAY_LOG_BASENAME is a base
name specified using the '--relay-log' option, and CHANNEL is the name
of the channel logged to this file.  If you do not specify the
'--relay-log' option, a default file name is used that also includes the
name of the channel.

16.2.4 Replication Relay and Status Logs
----------------------------------------

During replication, a slave server creates several logs that hold the
binary log events relayed from the master to the slave, and to record
information about the current status and location within the relay log.
There are three types of logs used in the process, listed here:

   * The _master info log_ contains status and current configuration
     information for the slave's connection to the master.  This log
     holds information on the master host name, login credentials, and
     coordinates indicating how far the slave has read from the master's
     binary log.

     This log can be written to the 'mysql.slave_master_info' table
     instead of a file, by starting the slave with
     '--master-info-repository=TABLE'.

   * The _relay log_ consists of the events read from the binary log of
     the master and written by the slave I/O thread.  Events in the
     relay log are executed on the slave as part of the SQL thread.

   * The _relay log info log_ holds status information about the
     execution point within the slave's relay log.

     This log can be written to the 'mysql.slave_relay_log_info' table
     instead of a file by starting the slave with
     '--relay-log-info-repository=TABLE'.

Setting 'relay_log_info_repository' and 'master_info_repository' to
'TABLE' can improve resilience to unexpected halts.  The master info log
stores information required for the recovery of the slave's I/O thread,
and the relay log info log stores information required for the recovery
of the SQL thread.  The updates to the tables are committed together
with the transaction, meaning that the information in them is always
consistent with what has been applied to the database, even in the event
of a server halt.  The '--relay-log-recovery' option must be enabled on
the slave to guarantee resilience.  For more details, see
replication-solutions-unexpected-slave-halt.

When tables are used for the slave status logs, a warning is given if
'mysqld' is unable to initialize the replication logging
tables, but the slave is allowed to continue starting.  This situation
is most likely to occur when upgrading from a version of MySQL that does
not support slave logging tables to one in which they are supported.

*Important*:

Do not attempt to update or insert rows in the 'slave_master_info' or
'slave_relay_log_info' table manually.  Doing so can cause undefined
behavior, and is not supported.

Execution of any statement requiring a write lock on either or both of
the 'slave_master_info' and 'slave_relay_log_info' tables is disallowed
while replication is ongoing, while statements that perform only reads
are permitted at any time.

16.2.4.1 The Slave Relay Log
............................

The relay log, like the binary log, consists of a set of numbered files
containing events that describe database changes, and an index file that
contains the names of all used relay log files.

The term 'relay log file' generally denotes an individual numbered file
containing database events.  The term 'relay log' collectively denotes
the set of numbered relay log files plus the index file.

Relay log files have the same format as binary log files and can be read
using 'mysqlbinlog'. (see mysqlbinlog).

By default, relay log file names have the form
'HOST_NAME-relay-bin.NNNNNN' in the data directory, where HOST_NAME is
the name of the slave server host and NNNNNN is a sequence number.
Successive relay log files are created using successive sequence
numbers, beginning with '000001'.  The slave uses an index file to track
the relay log files currently in use.  The default relay log index file
name is 'HOST_NAME-relay-bin.index' in the data directory.

The default relay log file and relay log index file names can be
overridden with, respectively, the '--relay-log' and '--relay-log-index'
server options (see replication-options).

If a slave uses the default host-based relay log file names, changing a
slave's host name after replication has been set up can cause
replication to fail with the errors 'Failed to open the relay log' and
'Could not find target log during relay log initialization'.  This is a
known issue (see Bug #2122).  If you anticipate that a slave's host name
might change in the future (for example, if networking is set up on the
slave such that its host name can be modified using DHCP), you can avoid
this issue entirely by using the '--relay-log' and '--relay-log-index'
options to specify relay log file names explicitly when you initially
set up the slave.  This will make the names independent of server host
name changes.

If you encounter the issue after replication has already begun, one way
to work around it is to stop the slave server, prepend the contents of
the old relay log index file to the new one, and then restart the slave.
On a Unix system, this can be done as shown here:

     shell> cat NEW_RELAY_LOG_NAME.index >> OLD_RELAY_LOG_NAME.index
     shell> mv OLD_RELAY_LOG_NAME.index NEW_RELAY_LOG_NAME.index

A slave server creates a new relay log file under the following
conditions:

   * Each time the I/O thread starts.

   * When the logs are flushed; for example, with 'FLUSH LOGS' or
     'mysqladmin flush-logs'.

   * When the size of the current relay log file becomes 'too large,'
     determined as follows:

        * If the value of 'max_relay_log_size' is greater than 0, that
          is the maximum relay log file size.

        * If the value of 'max_relay_log_size' is 0, 'max_binlog_size'
          determines the maximum relay log file size.

The SQL thread automatically deletes each relay log file after it has
executed all events in the file and no longer needs it.  There is no
explicit mechanism for deleting relay logs because the SQL thread takes
care of doing so.  However, 'FLUSH LOGS' rotates relay logs, which
influences when the SQL thread deletes them.

16.2.4.2 Slave Status Logs
..........................

A replication slave server creates two logs.  By default, these logs are
files named 'master.info' and 'relay-log.info' and created in the data
directory.  The names and locations of these files can be changed by
using the '--master-info-file' and '--relay-log-info-file' options,
respectively.  Either or both of these logs can also be written to
tables in the 'mysql' database by starting the server with the
appropriate option: use '--master-info-repository' to have the master
info log written to the 'mysql.slave_master_info' table, and use
'--relay-log-info-repository' to have the relay log info log written to
the 'mysql.slave_relay_log_info' table.  See
replication-options.

The two status logs contain information like that shown in the output of
the 'SHOW SLAVE STATUS' statement, which is
discussed in replication-slave-sql.  Because the status logs are
stored on disk, they survive a slave server's shutdown.  The next time
the slave starts up, it reads the two logs to determine how far it has
proceeded in reading binary logs from the master and in processing its
own relay logs.

The master info log file or table should be protected because it
contains the password for connecting to the master.  See
password-logging.

Setting 'relay_log_info_repository' and 'master_info_repository' to
'TABLE' can improve resilience to unexpected halts.  The master info log
stores information required for the recovery of the slave's I/O thread,
and the relay log info log stores information required for the recovery
of the SQL thread.  The updates to the tables are committed together
with the transaction, meaning that the information in them is always
consistent with what has been applied to the database, even in the event
of a server halt.  The '--relay-log-recovery' option must be enabled on
the slave to guarantee resilience.  For more details, see
replication-solutions-unexpected-slave-halt.

The slave I/O thread updates the master info log.  The following table
shows the correspondence between the lines in the 'master.info' file,
the columns in the 'mysql.slave_master_info' table, and the columns
displayed by 'SHOW SLAVE STATUS'.

'master.info''slave_master_info'    'SHOW SLAVE STATUS' Column    Description
File Line    Table Column

1            'Number_of_lines'      [None]                        Number of
                                                                  lines in
                                                                  the file,
                                                                  or columns
                                                                  in the
                                                                  table

2            'Master_log_name'      'Master_Log_File'             The name of
                                                                  the master
                                                                  binary log
                                                                  currently
                                                                  being read
                                                                  from the
                                                                  master

3            'Master_log_pos'       'Read_Master_Log_Pos'         The current
                                                                  position
                                                                  within the
                                                                  master
                                                                  binary log
                                                                  that have
                                                                  been read
                                                                  from the
                                                                  master

4            'Host'                 'Master_Host'                 The host
                                                                  name of the
                                                                  master

5            'User_name'            'Master_User'                 The user
                                                                  name used
                                                                  to connect
                                                                  to the
                                                                  master

6            'User_password'        Password (not shown by        The
                                    See 'SHOW SLAVE STATUS')
                                       used to
                                                                  connect to
                                                                  the master

7            'Port'                 'Master_Port'                 The network
                                                                  port used
                                                                  to connect
                                                                  to the
                                                                  master

8            'Connect_retry'        'Connect_Retry'               The period
                                                                  (in
                                                                  seconds)
                                                                  that the
                                                                  slave will
                                                                  wait before
                                                                  trying to
                                                                  reconnect
                                                                  to the
                                                                  master

9            'Enabled_ssl'          'Master_SSL_Allowed'          Indicates
                                                                  whether the
                                                                  server
                                                                  supports
                                                                  SSL
                                                                  connections

10           'Ssl_ca'               'Master_SSL_CA_File'          The file
                                                                  used for
                                                                  the
                                                                  Certificate
                                                                  Authority
                                                                  (CA)
                                                                  certificate

11           'Ssl_capath'           'Master_SSL_CA_Path'          The path to
                                                                  the
                                                                  Certificate
                                                                  Authority
                                                                  (CA)
                                                                  certificates

12           'Ssl_cert'             'Master_SSL_Cert'             The name of
                                                                  the SSL
                                                                  certificate
                                                                  file

13           'Ssl_cipher'           'Master_SSL_Cipher'           The list of
                                                                  possible
                                                                  ciphers
                                                                  used in the
                                                                  handshake
                                                                  for the SSL
                                                                  connection

14           'Ssl_key'              'Master_SSL_Key'              The name of
                                                                  the SSL key
                                                                  file

15           'Ssl_verify_server_cert''Master_SSL_Verify_Server_Cert'Whether to
                                                                  verify the
                                                                  server
                                                                  certificate

16           'Heartbeat'            [None]                        Interval
                                                                  between
                                                                  replication
                                                                  heartbeats,
                                                                  in seconds

17           'Bind'                 'Master_Bind'                 Which of
                                                                  the slave's
                                                                  network
                                                                  interfaces
                                                                  should be
                                                                  used for
                                                                  connecting
                                                                  to the
                                                                  master

18           'Ignored_server_ids'   'Replicate_Ignore_Server_Ids' The list of
                                                                  server IDs
                                                                  to be
                                                                  ignored.
                                                                  Note that
                                                                  for
                                                                  'Ignored_server_ids'
                                                                  the list of
                                                                  server IDs
                                                                  is preceded
                                                                  by the
                                                                  total
                                                                  number of
                                                                  server IDs
                                                                  to ignore.

19           'Uuid'                 'Master_UUID'                 The
                                                                  master's
                                                                  unique ID

20           'Retry_count'          'Master_Retry_Count'          Maximum
                                                                  number of
                                                                  reconnection
                                                                  attempts
                                                                  permitted

21           'Ssl_crl'              [None]                        Path to an
                                                                  ssl
                                                                  certificate
                                                                  revocation
                                                                  list file

22           'Ssl_crl_path'         [None]                        Path to a
                                                                  directory
                                                                  containing
                                                                  ssl
                                                                  certificate
                                                                  revocation
                                                                  list files

23           'Enabled_auto_position''Auto_position'               If
                                                                  autopositioning
                                                                  is in use
                                                                  or not

24           'Channel_name'         'Channel_name'                The name of
                                                                  the
                                                                  replication
                                                                  channel

25           'Tls_Version'          'Master_TLS_Version'          TLS version
                                                                  on master

The slave SQL thread updates the relay log info log.  The
'relay-log.info' file includes a line count and a replication delay
value.  The following table shows the correspondence between the lines
in the 'relay-log.info' file, the columns in the
'mysql.slave_relay_log_info' table, and the columns displayed by
'SHOW SLAVE STATUS'.

Line in     'slave_relay_log_info' 'SHOW SLAVE STATUS' Column    Description
'relay-log.info'Table Column

1           'Number_of_lines'      [None]                        Number of
                                                                 lines in the
                                                                 file or
                                                                 columns in
                                                                 the table

2           'Relay_log_name'       'Relay_Log_File'              The name of
                                                                 the current
                                                                 relay log
                                                                 file

3           'Relay_log_pos'        'Relay_Log_Pos'               The current
                                                                 position
                                                                 within the
                                                                 relay log
                                                                 file; events
                                                                 up to this
                                                                 position
                                                                 have been
                                                                 executed on
                                                                 the slave
                                                                 database

4           'Master_log_name'      'Relay_Master_Log_File'       The name of
                                                                 the master
                                                                 binary log
                                                                 file from
                                                                 which the
                                                                 events in
                                                                 the relay
                                                                 log file
                                                                 were read

5           'Master_log_pos'       'Exec_Master_Log_Pos'         The
                                                                 equivalent
                                                                 position
                                                                 within the
                                                                 master's
                                                                 binary log
                                                                 file of
                                                                 events that
                                                                 have already
                                                                 been
                                                                 executed

6           'Sql_delay'            'SQL_Delay'                   The number
                                                                 of seconds
                                                                 that the
                                                                 slave must
                                                                 lag the
                                                                 master

7           'Number_of_workers'    [None]                        The number
                                                                 of slave
                                                                 worker
                                                                 threads for
                                                                 executing
                                                                 replication
                                                                 events
                                                                 (transactions)
                                                                 in parallel

8           'Id'                   [None]                        ID used for
                                                                 internal
                                                                 purposes;
                                                                 currently
                                                                 this is
                                                                 always 1

9           'Channel_name'         Channel_name                  The name of
                                                                 the
                                                                 replication
                                                                 channel

In versions of MySQL prior to MySQL 5.6, the 'relay-log.info' file does
not include a line count or a delay value (and the
'slave_relay_log_info' table is not available).

Line        Status Column             Description

1           'Relay_Log_File'          The name of the current relay log
                                      file

2           'Relay_Log_Pos'           The current position within the
                                      relay log file; events up to this
                                      position have been executed on the
                                      slave database

3           'Relay_Master_Log_File'   The name of the master binary log
                                      file from which the events in the
                                      relay log file were read

4           'Exec_Master_Log_Pos'     The equivalent position within the
                                      master's binary log file of events
                                      that have already been executed

*Note*:

If you downgrade a slave server to a version older than MySQL 5.6, the
older server does not read the 'relay-log.info' file correctly.  To
address this, modify the file in a text editor by deleting the initial
line containing the number of lines.

The contents of the 'relay-log.info' file and the states shown by the
'SHOW SLAVE STATUS' statement might not match
if the 'relay-log.info' file has not been flushed to disk.  Ideally, you
should only view 'relay-log.info' on a slave that is offline (that is,
'mysqld' is not running).  For a running system, you can use 'SHOW SLAVE STATUS',
or query the 'slave_master_info' and
'slave_relay_log_info' tables if you are writing the status logs to
tables.

When you back up the slave's data, you should back up these two status
logs, along with the relay log files.  The status logs are needed to
resume replication after you restore the data from the slave.  If you
lose the relay logs but still have the relay log info log, you can check
it to determine how far the SQL thread has executed in the master binary
logs.  Then you can use 'CHANGE MASTER TO' with
the 'MASTER_LOG_FILE' and 'MASTER_LOG_POS' options to tell the slave to
re-read the binary logs from that point.  Of course, this requires that
the binary logs still exist on the master.

16.2.5 How Servers Evaluate Replication Filtering Rules
-------------------------------------------------------

If a master server does not write a statement to its binary log, the
statement is not replicated.  If the server does log the statement, the
statement is sent to all slaves and each slave determines whether to
execute it or ignore it.

On the master, you can control which databases to log changes for by
using the '--binlog-do-db' and '--binlog-ignore-db' options to control
binary logging.  For a description of the rules that servers use in
evaluating these options, see replication-rules-db-options.  You
should not use these options to control which databases and tables are
replicated.  Instead, use filtering on the slave to control the events
that are executed on the slave.

On the slave side, decisions about whether to execute or ignore
statements received from the master are made according to the
'--replicate-*' options that the slave was started with.  (See
replication-options.)  The filters governed by these options can also
be set dynamically using the 'CHANGE REPLICATION FILTER' statement.  The
rules governing such filters are the same whether they are created on
startup using '--replicate-*' options or while the slave server is
running by 'CHANGE REPLICATION FILTER'.

In the simplest case, when there are no '--replicate-*' options, the
slave executes all statements that it receives from the master.
Otherwise, the result depends on the particular options given.

Database-level options ('--replicate-do-db', '--replicate-ignore-db')
are checked first; see replication-rules-db-options, for a
description of this process.  If no database-level options are used,
option checking proceeds to any table-level options that may be in use
(see replication-rules-table-options, for a discussion of
these).  If one or more database-level options are used but none are
matched, the statement is not replicated.

For statements affecting databases only (that is, see 'CREATE DATABASE',
see 'DROP DATABASE', and
'ALTER DATABASE'), database-level options always
take precedence over any '--replicate-wild-do-table' options.  In other
words, for such statements, '--replicate-wild-do-table' options are
checked if and only if there are no database-level options that apply.
This is a change in behavior from previous versions of MySQL, where the
statement 'CREATE DATABASE dbx' was not
replicated if the slave had been started with '--replicate-do-db=dbx'
'--replicate-wild-do-table=db%.t1'.  (Bug #46110)

To make it easier to determine what effect an option set will have, it
is recommended that you avoid mixing 'do' and 'ignore' options, or
wildcard and nonwildcard options.

If any '--replicate-rewrite-db' options were specified, they are applied
before the '--replicate-*' filtering rules are tested.

*Note*:

All replication filtering options follow the same rules for case
sensitivity that apply to names of databases and tables elsewhere in the
MySQL server, including the effects of the 'lower_case_table_names'
system variable.

16.2.5.1 Evaluation of Database-Level Replication and Binary Logging Options
............................................................................

When evaluating replication options, the slave begins by checking to see
whether there are any '--replicate-do-db' or '--replicate-ignore-db'
options that apply.  When using '--binlog-do-db' or
'--binlog-ignore-db', the process is similar, but the options are
checked on the master.

The database that is checked for a match depends on the binary log
format of the statement that is being handled.  If the statement has
been logged using the row format, the database where data is to be
changed is the database that is checked.  If the statement has been
logged using the statement format, the default database (specified with
a 'USE' statement) is the database that is checked.

*Note*:

Only DML statements can be logged using the row format.  DDL statements
are always logged as statements, even when 'binlog_format=ROW'.  All DDL
statements are therefore always filtered according to the rules for
statement-based replication.  This means that you must select the
default database explicitly with a 'USE' statement in order
for a DDL statement to be applied.

For replication, the steps involved are listed here:

  1. Which logging format is used?

        * STATEMENT

          Test the default database.

        * ROW

          Test the database affected by the changes.

  2. Are there any '--replicate-do-db' options?

        * Yes

          Does the database match any of them?

             * Yes

               Continue to Step 4.

             * No

               Ignore the update and exit.

        * No

          Continue to step 3.

  3. Are there any '--replicate-ignore-db' options?

        * Yes

          Does the database match any of them?

             * Yes

               Ignore the update and exit.

             * No

               Continue to step 4.

        * No

          Continue to step 4.

  4. Proceed to checking the table-level replication options, if there
     are any.  For a description of how these options are checked, see
     replication-rules-table-options.

     *Important*:

     A statement that is still permitted at this stage is not yet
     actually executed.  The statement is not executed until all
     table-level options (if any) have also been checked, and the
     outcome of that process permits execution of the statement.

For binary logging, the steps involved are listed here:

  1. Are there any '--binlog-do-db' or '--binlog-ignore-db' options?

        * Yes

          Continue to step 2.

        * No

          Log the statement and exit.

  2. Is there a default database (has any database been selected by
     'USE')?

        * Yes

          Continue to step 3.

        * No

          Ignore the statement and exit.

  3. There is a default database.  Are there any '--binlog-do-db'
     options?

        * Yes

          Do any of them match the database?

             * Yes

               Log the statement and exit.

             * No

               Ignore the statement and exit.

        * No

          Continue to step 4.

  4. Do any of the '--binlog-ignore-db' options match the database?

        * Yes

          Ignore the statement and exit.

        * No

          Log the statement and exit.

*Important*:

For statement-based logging, an exception is made in the rules just
given for the 'CREATE DATABASE', 'ALTER DATABASE',
and 'DROP DATABASE'.
statements.  In those cases, the database being _created, altered, or
dropped_ replaces the default database when determining whether to log
or ignore updates.

'--binlog-do-db' can sometimes mean 'ignore other databases'.  For
example, when using statement-based logging, a server running with only
'--binlog-do-db=sales' does not write to the binary log statements for
which the default database differs from 'sales'.  When using row-based
logging with the same option, the server logs only those updates that
change data in 'sales'.

16.2.5.2 Evaluation of Table-Level Replication Options
......................................................

The slave checks for and evaluates table options only if either of the
following two conditions is true:

   * No matching database options were found.

   * One or more database options were found, and were evaluated to
     arrive at an 'execute' condition according to the rules described
     in the previous section (see replication-rules-db-options).

First, as a preliminary condition, the slave checks whether
statement-based replication is enabled.  If so, and the statement occurs
within a stored function, the slave executes the statement and exits.
If row-based replication is enabled, the slave does not know whether a
statement occurred within a stored function on the master, so this
condition does not apply.

*Note*:

For statement-based replication, replication events represent statements
(all changes making up a given event are associated with a single SQL
statement); for row-based replication, each event represents a change in
a single table row (thus a single statement such as 'UPDATE mytable SET
mycol = 1' may yield many row-based events).  When viewed in terms of
events, the process of checking table options is the same for both
row-based and statement-based replication.

Having reached this point, if there are no table options, the slave
simply executes all events.  If there are any '--replicate-do-table' or
'--replicate-wild-do-table' options, the event must match one of these
if it is to be executed; otherwise, it is ignored.  If there are any
'--replicate-ignore-table' or '--replicate-wild-ignore-table' options,
all events are executed except those that match any of these options.

The following steps describe this evaluation in more detail.  The
starting point is the end of the evaluation of the database-level
options, as described in replication-rules-db-options.

  1. Are there any table replication options?

        * Yes

          Continue to step 2.

        * No

          Execute the update and exit.

  2. Which logging format is used?

        * STATEMENT

          Carry out the remaining steps for each statement that performs
          an update.

        * ROW

          Carry out the remaining steps for each update of a table row.

  3. Are there any '--replicate-do-table' options?

        * Yes

          Does the table match any of them?

             * Yes

               Execute the update and exit.

             * No

               Continue to step 4.

        * No

          Continue to step 4.

  4. Are there any '--replicate-ignore-table' options?

        * Yes

          Does the table match any of them?

             * Yes

               Ignore the update and exit.

             * No

               Continue to step 5.

        * No

          Continue to step 5.

  5. Are there any '--replicate-wild-do-table' options?

        * Yes

          Does the table match any of them?

             * Yes

               Execute the update and exit.

             * No

               Continue to step 6.

        * No

          Continue to step 6.

  6. Are there any '--replicate-wild-ignore-table' options?

        * Yes

          Does the table match any of them?

             * Yes

               Ignore the update and exit.

             * No

               Continue to step 7.

        * No

          Continue to step 7.

  7. Is there another table to be tested?

        * Yes

          Go back to step 3.

        * No

          Continue to step 8.

  8. Are there any '--replicate-do-table' or '--replicate-wild-do-table'
     options?

        * Yes

          Ignore the update and exit.

        * No

          Execute the update and exit.

*Note*:

Statement-based replication stops if a single SQL statement operates on
both a table that is included by a '--replicate-do-table' or
'--replicate-wild-do-table' option, and another table that is ignored by
a '--replicate-ignore-table' or '--replicate-wild-ignore-table' option.
The slave must either execute or ignore the complete statement (which
forms a replication event), and it cannot logically do this.  This also
applies to row-based replication for DDL statements, because DDL
statements are always logged as statements, without regard to the
logging format in effect.  The only type of statement that can update
both an included and an ignored table and still be replicated
successfully is a DML statement that has been logged with
'binlog_format=ROW'.

16.2.5.3 Replication Rule Application
.....................................

This section provides additional explanation and examples of usage for
different combinations of replication filtering options.

Some typical combinations of replication filter rule types are given in
the following table:

Condition (Types of           Outcome
Options)

No '--replicate-*' options    The slave executes all events that it
at all:                       receives from the master.

'--replicate-*-db' options,   The slave accepts or ignores events using
but no table options:         the database options.  It executes all
                              events permitted by those options because
                              there are no table restrictions.

'--replicate-*-table'         All events are accepted at the
options, but no database      database-checking stage because there are
options:                      no database conditions.  The slave
                              executes or ignores events based solely
                              on the table options.

A combination of database     The slave accepts or ignores events using
and table options:            the database options.  Then it evaluates
                              all events permitted by those options
                              according to the table options.  This can
                              sometimes lead to results that seem
                              counterintuitive, and that may be
                              different depending on whether you are
                              using statement-based or row-based
                              replication; see the text for an example.

A more complex example follows, in which we examine the outcomes for
both statement-based and row-based settings.

Suppose that we have two tables 'mytbl1' in database 'db1' and 'mytbl2'
in database 'db2' on the master, and the slave is running with the
following options (and no other replication filtering options):

     replicate-ignore-db = db1
     replicate-do-table  = db2.tbl2

Now we execute the following statements on the master:

     USE db1;
     INSERT INTO db2.tbl2 VALUES (1);

The results on the slave vary considerably depending on the binary log
format, and may not match initial expectations in either case.

Statement-based replication

The 'USE' statement causes 'db1' to be the default database.  Thus the
'--replicate-ignore-db' option matches, _and the 'INSERT'.
statement is ignored_.  The table options are not checked.

Row-based replication

The default database has no effect on how the slave reads database
options when using row-based replication.  Thus, the 'USE'.
statement makes no difference in how the '--replicate-ignore-db' option
is handled: the database specified by this option does not match the
database where the 'INSERT' statement changes data, so
the slave proceeds to check the table options.  The table specified by
'--replicate-do-table' matches the table to be updated, _and the row is
inserted_.

16.3 Replication Solutions
==========================

Replication can be used in many different environments for a range of
purposes.  This section provides general notes and advice on using
replication for specific solution types.

For information on using replication in a backup environment, including
notes on the setup, backup procedure, and files to back up, see
replication-solutions-backups.

For advice and tips on using different storage engines on the master and
slaves, see replication-solutions-diffengines.

Using replication as a scale-out solution requires some changes in the
logic and operation of applications that use the solution.  See
replication-solutions-scaleout.

For performance or data distribution reasons, you may want to replicate
different databases to different replication slaves.  See
replication-solutions-partitioning

As the number of replication slaves increases, the load on the master
can increase and lead to reduced performance (because of the need to
replicate the binary log to each slave).  For tips on improving your
replication performance, including using a single secondary server as a
replication master, see replication-solutions-performance.

For guidance on switching masters, or converting slaves into masters as
part of an emergency failover solution, see
replication-solutions-switch.

To secure your replication communication, you can encrypt the
communication channel.  For step-by-step instructions, see
replication-solutions-encrypted-connections.

16.3.1 Using Replication for Backups
------------------------------------

To use replication as a backup solution, replicate data from the master
to a slave, and then back up the data slave.  The slave can be paused
and shut down without affecting the running operation of the master, so
you can produce an effective snapshot of 'live' data that would
otherwise require the master to be shut down.

How you back up a database depends on its size and whether you are
backing up only the data, or the data and the replication slave state so
that you can rebuild the slave in the event of failure.  There are
therefore two choices:

   * If you are using replication as a solution to enable you to back up
     the data on the master, and the size of your database is not too
     large, the 'mysqldump' tool may be suitable.  See
     replication-solutions-backups-mysqldump.

   * For larger databases, where 'mysqldump' would be
     impractical or inefficient, you can back up the raw data files
     instead.  Using the raw data files option also means that you can
     back up the binary and relay logs that will enable you to recreate
     the slave in the event of a slave failure.  For more information,
     see replication-solutions-backups-rawdata.

Another backup strategy, which can be used for either master or slave
servers, is to put the server in a read-only state.  The backup is
performed against the read-only server, which then is changed back to
its usual read/write operational status.  See
replication-solutions-backups-read-only.

16.3.1.1 Backing Up a Slave Using mysqldump
...........................................

Using 'mysqldump' to create a copy of a database
enables you to capture all of the data in the database in a format that
enables the information to be imported into another instance of MySQL
Server (see mysqldump).  Because the format of the information
is SQL statements, the file can easily be distributed and applied to
running servers in the event that you need access to the data in an
emergency.  However, if the size of your data set is very large, see
'mysqldump' may be impractical.

When using 'mysqldump', you should stop replication on
the slave before starting the dump process to ensure that the dump
contains a consistent set of data:

  1. Stop the slave from processing requests.  You can stop replication
     completely on the slave using 'mysqladmin'.:

          shell> mysqladmin stop-slave

     Alternatively, you can stop only the slave SQL thread to pause
     event execution:

          shell> mysql -e 'STOP SLAVE SQL_THREAD;'

     This enables the slave to continue to receive data change events
     from the master's binary log and store them in the relay logs using
     the I/O thread, but prevents the slave from executing these events
     and changing its data.  Within busy replication environments,
     permitting the I/O thread to run during backup may speed up the
     catch-up process when you restart the slave SQL thread.

  2. Run 'mysqldump' to dump your databases.  You may
     either dump all databases or select databases to be dumped.  For
     example, to dump all databases:

          shell> mysqldump --all-databases > fulldb.dump

  3. Once the dump has completed, start slave operations again:

          shell> mysqladmin start-slave

In the preceding example, you may want to add login credentials (user
name, password) to the commands, and bundle the process up into a script
that you can run automatically each day.

If you use this approach, make sure you monitor the slave replication
process to ensure that the time taken to run the backup does not affect
the slave's ability to keep up with events from the master.  See
replication-administration-status.  If the slave is unable to keep up,
you may want to add another slave and distribute the backup process.
For an example of how to configure this scenario, see
replication-solutions-partitioning.

16.3.1.2 Backing Up Raw Data from a Slave
.........................................

To guarantee the integrity of the files that are copied, backing up the
raw data files on your MySQL replication slave should take place while
your slave server is shut down.  If the MySQL server is still running,
background tasks may still be updating the database files, particularly
those involving storage engines with background processes such as
'InnoDB'.  With 'InnoDB', these problems should be resolved during crash
recovery, but since the slave server can be shut down during the backup
process without affecting the execution of the master it makes sense to
take advantage of this capability.

To shut down the server and back up the files:

  1. Shut down the slave MySQL server:

          shell> mysqladmin shutdown

  2. Copy the data files.  You can use any suitable copying or archive
     utility, including 'cp', 'tar' or 'WinZip'.  For example, assuming
     that the data directory is located under the current directory, you
     can archive the entire directory as follows:

          shell> tar cf /tmp/dbbackup.tar ./data

  3. Start the MySQL server again.  Under Unix:

          shell> mysqld_safe &

     Under Windows:

          C:\> "C:\Program Files\MySQL\MySQL Server 5.7\bin\mysqld"

Normally you should back up the entire data directory for the slave
MySQL server.  If you want to be able to restore the data and operate as
a slave (for example, in the event of failure of the slave), then in
addition to the slave's data, you should also back up the slave status
files, the master info and relay log info repositories, and the relay
log files.  These files are needed to resume replication after you
restore the slave's data.

If you lose the relay logs but still have the 'relay-log.info' file, you
can check it to determine how far the SQL thread has executed in the
master binary logs.  Then you can use 'CHANGE MASTER TO'
with the 'MASTER_LOG_FILE' and 'MASTER_LOG_POS'
options to tell the slave to re-read the binary logs from that point.
This requires that the binary logs still exist on the master server.

If your slave is replicating 'LOAD DATA INFILE'.
statements, you should also back up any 'SQL_LOAD-*' files that exist in
the directory that the slave uses for this purpose.  The slave needs
these files to resume replication of any interrupted 'LOAD DATA INFILE'
operations.  The location of this directory is the
value of the '--slave-load-tmpdir' option.  If the server was not
started with that option, the directory location is the value of the
'tmpdir' system variable.

16.3.1.3 Backing Up a Master or Slave by Making It Read Only
............................................................

It is possible to back up either master or slave servers in a
replication setup by acquiring a global read lock and manipulating the
'read_only' system variable to change the read-only state of the server
to be backed up:

  1. Make the server read-only, so that it processes only retrievals and
     blocks updates.

  2. Perform the backup.

  3. Change the server back to its normal read/write state.

*Note*:

The instructions in this section place the server to be backed up in a
state that is safe for backup methods that get the data from the server,
such as 'mysqldump'. (see mysqldump).  You
should not attempt to use these instructions to make a binary backup by
copying files directly because the server may still have modified data
cached in memory and not flushed to disk.

The following instructions describe how to do this for a master server
and for a slave server.  For both scenarios discussed here, suppose that
you have the following replication setup:

   * A master server M1

   * A slave server S1 that has M1 as its master

   * A client C1 connected to M1

   * A client C2 connected to S1

In either scenario, the statements to acquire the global read lock and
manipulate the 'read_only' variable are performed on the server to be
backed up and do not propagate to any slaves of that server.

*Scenario 1: Backup with a Read-Only Master*

Put the master M1 in a read-only state by executing these statements on
it:

     mysql> FLUSH TABLES WITH READ LOCK;
     mysql> SET GLOBAL read_only = ON;

While M1 is in a read-only state, the following properties are true:

   * Requests for updates sent by C1 to M1 will block because the server
     is in read-only mode.

   * Requests for query results sent by C1 to M1 will succeed.

   * Making a backup on M1 is safe.

   * Making a backup on S1 is not safe.  This server is still running,
     and might be processing the binary log or update requests coming
     from client C2

While M1 is read only, perform the backup.  For example, you can use
'mysqldump'.

After the backup operation on M1 completes, restore M1 to its normal
operational state by executing these statements:

     mysql> SET GLOBAL read_only = OFF;
     mysql> UNLOCK TABLES;

Although performing the backup on M1 is safe (as far as the backup is
concerned), it is not optimal for performance because clients of M1 are
blocked from executing updates.

This strategy applies to backing up a master server in a replication
setup, but can also be used for a single server in a nonreplication
setting.

*Scenario 2: Backup with a Read-Only Slave*

Put the slave S1 in a read-only state by executing these statements on
it:

     mysql> FLUSH TABLES WITH READ LOCK;
     mysql> SET GLOBAL read_only = ON;

While S1 is in a read-only state, the following properties are true:

   * The master M1 will continue to operate, so making a backup on the
     master is not safe.

   * The slave S1 is stopped, so making a backup on the slave S1 is
     safe.

These properties provide the basis for a popular backup scenario: Having
one slave busy performing a backup for a while is not a problem because
it does not affect the entire network, and the system is still running
during the backup.  In particular, clients can still perform updates on
the master server, which remains unaffected by backup activity on the
slave.

While S1 is read only, perform the backup.  For example, you can use
'mysqldump'.

After the backup operation on S1 completes, restore S1 to its normal
operational state by executing these statements:

     mysql> SET GLOBAL read_only = OFF;
     mysql> UNLOCK TABLES;

After the slave is restored to normal operation, it again synchronizes
to the master by catching up with any outstanding updates from the
binary log of the master.

16.3.2 Handling an Unexpected Halt of a Replication Slave
---------------------------------------------------------

In order for replication to be resilient to unexpected halts of the
server (sometimes described as crash-safe) it must be possible for the
slave to recover its state before halting.  This section describes the
impact of an unexpected halt of a slave during replication and how to
configure a slave for the best chance of recovery to continue
replication.

After an unexpected halt of a slave, upon restart the I/O thread must
recover the information about which transactions have been received, and
the SQL thread must recover which transactions have been executed
already.  For information on the slave logs required for recovery, see
slave-logs.

The information required for recovery was traditionally stored in files
in the data directory that were updated after the transaction had been
applied.  This held the risk of losing synchrony with the master
depending at which stage of processing a transaction the slave halted
at, or even corruption of the files themselves.  In MySQL 5.7 you can
instead use tables to store recovery information.  The updates to the
tables are committed together with the transaction, meaning that the
information in them is always consistent with what has been applied to
the database, even in the event of a server halt.  These tables are
created using 'InnoDB', and by using this
transactional storage engine the information is always recoverable upon
restart.

To configure MySQL 5.7 to store the replication information in tables,
set 'relay_log_info_repository' and 'master_info_repository' to 'TABLE'.
The server then stores information required for the recovery of the I/O
thread in the 'mysql.slave_master_info' table and information required
for the recovery of the SQL thread in the 'mysql.slave_relay_log_info'
table.

Exactly how a replication slave recovers from an unexpected halt is
influenced by the chosen method of replication, whether the slave is
single-threaded or multi-threaded, the setting of variables such as
'relay_log_recovery', and whether features such as
'MASTER_AUTO_POSITION' are being used.

The following table shows the impact of these different factors on how a
single-threaded slave recovers from an unexpected halt.

*Factors Influencing Single-threaded Replication Slave Recovery*

GTID    MASTER_AUTO_POSITION'relay_log_recovery''relay_log_info_repository'CrashRecoveryRelay
                                type    guaranteedlog
                                                impact

OFF     Any     1       TABLE   Server  Yes     Lost

OFF     Any     1       Any     OS      No      Lost

OFF     Any     0       TABLE   Server  Yes     Remains

OFF     Any     0       TABLE   OS      No      Remains

ON      ON      Any     Any     Any     Yes     Lost

ON      OFF     0       TABLE   Server  Yes     Remains

ON      OFF     0       Any     OS      No      Remains

As the table shows, when using a single-threaded slave the following
configurations are most resilient to unexpected halts:

   * When using GTIDs and 'MASTER_AUTO_POSITION', set
     'relay_log_recovery=1'.  With this configuration the setting of
     'relay_log_info_repository' and other variables does not impact on
     recovery.  Note that to guarantee recovery, 'sync_binlog=1' (which
     is the default) must also be set on the slave, so that the slave's
     binary log is synchronized to disk at each write.  Otherwise,
     committed transactions might not be present in the slave's binary
     log.

   * When using file position based replication, set
     'relay_log_recovery=1' and 'relay_log_info_repository=TABLE'.

     *Note*:

     During recovery the relay log is lost.

The following table shows the impact of these different factors on how a
multi-threaded slave recovers from an unexpected halt.

*Factors Influencing Multi-threaded Replication Slave Recovery*

GTID    'sync_relay_log''MASTER_AUTO_POSITION''relay_log_recovery''relay_log_info_repository'CrashRecoveryRelay
                                        type    guaranteedlog
                                                        impact

OFF     1       Any     1       TABLE   Any     Yes     Lost

OFF     >1      Any     1       TABLE   Server  Yes     Lost

OFF     >1      Any     1       Any     OS      No      Lost

OFF     1       Any     0       TABLE   Server  Yes     Remains

OFF     1       Any     0       TABLE   OS      No      Remains

        Any
ON              ON      Any     Any     Any     Yes     Lost

ON      1       OFF     0       TABLE   Server  Yes     Remains

ON      1       OFF     0       Any     OS      No      Remains

As the table shows, when using a multi-threaded slave the following
configurations are most resilient to unexpected halts:

   * When using GTIDs and 'MASTER_AUTO_POSITION', set
     'relay_log_recovery=1'.  With this configuration the setting of
     'relay_log_info_repository' and other variables does not impact on
     recovery.

   * When using file position based replication, set
     'relay_log_recovery=1', 'sync_relay_log=1', and
     'relay_log_info_repository=TABLE'.

     *Note*:

     During recovery the relay log is lost.

It is important to note the impact of 'sync_relay_log=1', which requires
a write of to the relay log per transaction.  Although this setting is
the most resilient to an unexpected halt, with at most one unwritten
transaction being lost, it also has the potential to greatly increase
the load on storage.  Without 'sync_relay_log=1', the effect of an
unexpected halt depends on how the relay log is handled by the operating
system.  Also note that when 'relay_log_recovery=0', the next time the
slave is started after an unexpected halt the relay log is processed as
part of recovery.  After this process completes, the relay log is
deleted.

An unexpected halt of a multi-threaded replication slave using the
recommended file position based replication configuration above may
result in a relay log with transaction inconsistencies (gaps in the
sequence of transactions) caused by the unexpected halt.  See
replication-features-transaction-inconsistencies.  In MySQL 5.7.13 and
later, if the relay log recovery process encounters such transaction
inconsistencies they are filled and the recovery process continues
automatically.  In MySQL versions prior to MySQL 5.7.13, this process
was not automatic and required starting the server with
'relay_log_recovery=0', starting the slave with 'START SLAVE UNTIL SQL_AFTER_MTS_GAPS'
to fix any transaction
inconsistencies, and then restarting the slave with
'relay_log_recovery=1'.

When you are using multi-source replication and 'relay_log_recovery=1',
after restarting due to an unexpected halt all replication channels go
through the relay log recovery process.  Any inconsistencies found in
the relay log due to an unexpected halt of a multi-threaded slave are
filled.

16.3.3 Using Replication with Different Master and Slave Storage Engines
------------------------------------------------------------------------

It does not matter for the replication process whether the source table
on the master and the replicated table on the slave use different engine
types.  In fact, the 'default_storage_engine' and 'storage_engine'
system variables are not replicated.

This provides a number of benefits in the replication process in that
you can take advantage of different engine types for different
replication scenarios.  For example, in a typical scale-out scenario
(see replication-solutions-scaleout), you want to use 'InnoDB'
tables on the master to take advantage of the transactional
functionality, but use 'MyISAM' on the slaves where transaction support
is not required because the data is only read.  When using replication
in a data-logging environment you may want to use the 'Archive' storage
engine on the slave.

Configuring different engines on the master and slave depends on how you
set up the initial replication process:

   * If you used 'mysqldump' to create the database
     snapshot on your master, you could edit the dump file text to
     change the engine type used on each table.

     Another alternative for 'mysqldump' is to disable
     engine types that you do not want to use on the slave before using
     the dump to build the data on the slave.  For example, you can add
     the '--skip-federated' option on your slave to disable the
     'FEDERATED' engine.  If a specific engine does not exist for a
     table to be created, MySQL will use the default engine type,
     usually 'MyISAM'.  (This requires that the 'NO_ENGINE_SUBSTITUTION'
     SQL mode is not enabled.)  If you want to disable additional
     engines in this way, you may want to consider building a special
     binary to be used on the slave that only supports the engines you
     want.

   * If you are using raw data files (a binary backup) to set up the
     slave, you will be unable to change the initial table format.
     Instead, use 'ALTER TABLE' to change the table
     types after the slave has been started.

   * For new master/slave replication setups where there are currently
     no tables on the master, avoid specifying the engine type when
     creating new tables.

If you are already running a replication solution and want to convert
your existing tables to another engine type, follow these steps:

  1. Stop the slave from running replication updates:

          mysql> STOP SLAVE;

     This will enable you to change engine types without interruptions.

  2. Execute an 'ALTER TABLE ... ENGINE='ENGINE_TYPE'' for each table to
     be changed.

  3. Start the slave replication process again:

          mysql> START SLAVE;

Although the 'default_storage_engine' variable is not replicated, be
aware that 'CREATE TABLE' and 'ALTER TABLE'
statements that include the engine specification will be
correctly replicated to the slave.  For example, if you have a CSV table
and you execute:

     mysql> ALTER TABLE csvtable Engine='MyISAM';

The above statement will be replicated to the slave and the engine type
on the slave will be converted to 'MyISAM', even if you have previously
changed the table type on the slave to an engine other than CSV. If you
want to retain engine differences on the master and slave, you should be
careful to use the 'default_storage_engine' variable on the master when
creating a new table.  For example, instead of:

     mysql> CREATE TABLE tablea (columna int) Engine=MyISAM;

Use this format:

     mysql> SET default_storage_engine=MyISAM;
     mysql> CREATE TABLE tablea (columna int);

When replicated, the 'default_storage_engine' variable will be ignored,
and the 'CREATE TABLE' statement will execute on
the slave using the slave's default engine.

16.3.4 Using Replication for Scale-Out
--------------------------------------

You can use replication as a scale-out solution; that is, where you want
to split up the load of database queries across multiple database
servers, within some reasonable limitations.

Because replication works from the distribution of one master to one or
more slaves, using replication for scale-out works best in an
environment where you have a high number of reads and low number of
writes/updates.  Most websites fit into this category, where users are
browsing the website, reading articles, posts, or viewing products.
Updates only occur during session management, or when making a purchase
or adding a comment/message to a forum.

Replication in this situation enables you to distribute the reads over
the replication slaves, while still enabling your web servers to
communicate with the replication master when a write is required.  You
can see a sample replication layout for this scenario in
figure_replication-scaleout.

FIGURE GOES HERE: Using Replication to Improve Performance During
Scale-Out

If the part of your code that is responsible for database access has
been properly abstracted/modularized, converting it to run with a
replicated setup should be very smooth and easy.  Change the
implementation of your database access to send all writes to the master,
and to send reads to either the master or a slave.  If your code does
not have this level of abstraction, setting up a replicated system gives
you the opportunity and motivation to clean it up.  Start by creating a
wrapper library or module that implements the following functions:

   * 'safe_writer_connect()'

   * 'safe_reader_connect()'

   * 'safe_reader_statement()'

   * 'safe_writer_statement()'

'safe_' in each function name means that the function takes care of
handling all error conditions.  You can use different names for the
functions.  The important thing is to have a unified interface for
connecting for reads, connecting for writes, doing a read, and doing a
write.

Then convert your client code to use the wrapper library.  This may be a
painful and scary process at first, but it pays off in the long run.
All applications that use the approach just described are able to take
advantage of a master/slave configuration, even one involving multiple
slaves.  The code is much easier to maintain, and adding troubleshooting
options is trivial.  You need modify only one or two functions; for
example, to log how long each statement took, or which statement among
those issued gave you an error.

If you have written a lot of code, you may want to automate the
conversion task by using the 'replace' utility
that comes with standard MySQL distributions, or write your own
conversion script.  Ideally, your code uses consistent programming style
conventions.  If not, then you are probably better off rewriting it
anyway, or at least going through and manually regularizing it to use a
consistent style.

16.3.5 Replicating Different Databases to Different Slaves
----------------------------------------------------------

There may be situations where you have a single master and want to
replicate different databases to different slaves.  For example, you may
want to distribute different sales data to different departments to help
spread the load during data analysis.  A sample of this layout is shown
in figure_replication-multi-db.

FIGURE GOES HERE: Using Replication to Replicate Databases to Separate
Replication Slaves

You can achieve this separation by configuring the master and slaves as
normal, and then limiting the binary log statements that each slave
processes by using the '--replicate-wild-do-table' configuration option
on each slave.

*Important*:

You should _not_ use '--replicate-do-db' for this purpose when using
statement-based replication, since statement-based replication causes
this option's affects to vary according to the database that is
currently selected.  This applies to mixed-format replication as well,
since this enables some updates to be replicated using the
statement-based format.

However, it should be safe to use '--replicate-do-db' for this purpose
if you are using row-based replication only, since in this case the
currently selected database has no effect on the option's operation.

For example, to support the separation as shown in
figure_replication-multi-db, you should configure each replication
slave as follows, before executing 'START SLAVE'.:

   * Replication slave 1 should use
     '--replicate-wild-do-table=databaseA.%'.

   * Replication slave 2 should use
     '--replicate-wild-do-table=databaseB.%'.

   * Replication slave 3 should use
     '--replicate-wild-do-table=databaseC.%'.

Each slave in this configuration receives the entire binary log from the
master, but executes only those events from the binary log that apply to
the databases and tables included by the '--replicate-wild-do-table'
option in effect on that slave.

If you have data that must be synchronized to the slaves before
replication starts, you have a number of choices:

   * Synchronize all the data to each slave, and delete the databases,
     tables, or both that you do not want to keep.

   * Use 'mysqldump' to create a separate dump file
     for each database and load the appropriate dump file on each slave.

   * Use a raw data file dump and include only the specific files and
     databases that you need for each slave.

     *Note*:

     This does not work with 'InnoDB'.
     databases unless you use 'innodb_file_per_table'.

16.3.6 Improving Replication Performance
----------------------------------------

As the number of slaves connecting to a master increases, the load,
although minimal, also increases, as each slave uses a client connection
to the master.  Also, as each slave must receive a full copy of the
master binary log, the network load on the master may also increase and
create a bottleneck.

If you are using a large number of slaves connected to one master, and
that master is also busy processing requests (for example, as part of a
scale-out solution), then you may want to improve the performance of the
replication process.

One way to improve the performance of the replication process is to
create a deeper replication structure that enables the master to
replicate to only one slave, and for the remaining slaves to connect to
this primary slave for their individual replication requirements.  A
sample of this structure is shown in
figure_replication-performance.

FIGURE GOES HERE: Using an Additional Replication Host to Improve
Performance

For this to work, you must configure the MySQL instances as follows:

   * Master 1 is the primary master where all changes and updates are
     written to the database.  Binary logging should be enabled on this
     machine.

   * Master 2 is the slave to the Master 1 that provides the replication
     functionality to the remainder of the slaves in the replication
     structure.  Master 2 is the only machine permitted to connect to
     Master 1.  Master 2 also has binary logging enabled, and the
     '--log-slave-updates' option so that replication instructions from
     Master 1 are also written to Master 2's binary log so that they can
     then be replicated to the true slaves.

   * Slave 1, Slave 2, and Slave 3 act as slaves to Master 2, and
     replicate the information from Master 2, which actually consists of
     the upgrades logged on Master 1.

The above solution reduces the client load and the network interface
load on the primary master, which should improve the overall performance
of the primary master when used as a direct database solution.

If your slaves are having trouble keeping up with the replication
process on the master, there are a number of options available:

   * If possible, put the relay logs and the data files on different
     physical drives.  To do this, use the '--relay-log' option to
     specify the location of the relay log.

   * If the slaves are significantly slower than the master, you may
     want to divide up the responsibility for replicating different
     databases to different slaves.  See
     replication-solutions-partitioning.

   * If your master makes use of transactions and you are not concerned
     about transaction support on your slaves, use 'MyISAM' or another
     nontransactional engine on the slaves.  See
     replication-solutions-diffengines.

   * If your slaves are not acting as masters, and you have a potential
     solution in place to ensure that you can bring up a master in the
     event of failure, then you can switch off '--log-slave-updates'.
     This prevents 'dumb' slaves from also logging events they have
     executed into their own binary log.

16.3.7 Switching Masters During Failover
----------------------------------------

When using replication with GTIDs (see replication-gtids), you
can provide failover between master and slaves in the event of a failure
using 'mysqlfailover', which is provided by the MySQL Utilities; see
'mysqlfailover' -- Automatic replication health monitoring and failover
(http://dev.mysql.com/doc/mysql-utilities/1.5/en/mysqlfailover.html),
for more information.  If you are not using GTIDs and therefore cannot
use 'mysqlfailover', you must set up a master and one or more slaves;
then, you need to write an application or script that monitors the
master to check whether it is up, and instructs the slaves and
applications to change to another master in case of failure.  This
section discusses some of the issues encountered when setting up
failover in this way.

You can tell a slave to change to a new master using the 'CHANGE MASTER TO'
statement.  The slave does not check
whether the databases on the master are compatible with those on the
slave; it simply begins reading and executing events from the specified
coordinates in the new master's binary log.  In a failover situation,
all the servers in the group are typically executing the same events
from the same binary log file, so changing the source of the events
should not affect the structure or integrity of the database, provided
that you exercise care in making the change.

Slaves should be run with the '--log-bin' option, and if not using GTIDs
then they should also be run without '--log-slave-updates'.  In this
way, the slave is ready to become a master without restarting the slave
'mysqld'.  Assume that you have the structure shown in
figure_replication-redundancy-before.

FIGURE GOES HERE: Redundancy Using Replication, Initial Structure

In this diagram, the 'MySQL Master' holds the master database, the
'MySQL Slave' hosts are replication slaves, and the 'Web Client'
machines are issuing database reads and writes.  Web clients that issue
only reads (and would normally be connected to the slaves) are not
shown, as they do not need to switch to a new server in the event of
failure.  For a more detailed example of a read/write scale-out
replication structure, see replication-solutions-scaleout.

Each MySQL Slave ('Slave 1', 'Slave 2', and 'Slave 3') is a slave
running with '--log-bin' and without '--log-slave-updates'.  Because
updates received by a slave from the master are not logged in the binary
log unless '--log-slave-updates' is specified, the binary log on each
slave is empty initially.  If for some reason 'MySQL Master' becomes
unavailable, you can pick one of the slaves to become the new master.
For example, if you pick 'Slave 1', all 'Web Clients' should be
redirected to 'Slave 1', which writes the updates to its binary log.
'Slave 2' and 'Slave 3' should then replicate from 'Slave 1'.

The reason for running the slave without '--log-slave-updates' is to
prevent slaves from receiving updates twice in case you cause one of the
slaves to become the new master.  If 'Slave 1' has '--log-slave-updates'
enabled, it writes any updates that it receives from 'Master' in its own
binary log.  This means that, when 'Slave 2' changes from 'Master' to
'Slave 1' as its master, it may receive updates from 'Slave 1' that it
has already received from 'Master'.

Make sure that all slaves have processed any statements in their relay
log.  On each slave, issue 'STOP SLAVE IO_THREAD', then check the output
of 'SHOW PROCESSLIST' until you see 'Has read
all relay log'.  When this is true for all slaves, they can be
reconfigured to the new setup.  On the slave 'Slave 1' being promoted to
become the master, issue 'STOP SLAVE' and
'RESET MASTER'.

On the other slaves 'Slave 2' and 'Slave 3', use 'STOP SLAVE'
and 'CHANGE MASTER TO MASTER_HOST='Slave1'' (where
''Slave1'' represents the real host name of 'Slave 1').  To use 'CHANGE
MASTER TO', add all information about how to connect to 'Slave 1' from
'Slave 2' or 'Slave 3' (USER, PASSWORD, PORT).  When issuing the 'CHANGE
MASTER TO' statement in this, there is no need to specify the name of
the 'Slave 1' binary log file or log position to read from, since the
first binary log file and position 4, are the defaults.  Finally,
execute 'START SLAVE' on 'Slave 2' and 'Slave 3'.

Once the new replication setup is in place, you need to tell each 'Web
Client' to direct its statements to 'Slave 1'.  From that point on, all
updates statements sent by 'Web Client' to 'Slave 1' are written to the
binary log of 'Slave 1', which then contains every update statement sent
to 'Slave 1' since 'Master' died.

The resulting server structure is shown in
figure_replication-redundancy-after.

FIGURE GOES HERE: Redundancy Using Replication, After Master Failure

When 'Master' becomes available again, you should make it a slave of
'Slave 1'.  To do this, issue on 'Master' the same 'CHANGE MASTER TO'
statement as that issued on 'Slave 2' and 'Slave
3' previously.  'Master' then becomes a slave of 'S1ave 1' and picks up
the 'Web Client' writes that it missed while it was offline.

To make 'Master' a master again, use the preceding procedure as if
'Slave 1' was unavailable and 'Master' was to be the new master.  During
this procedure, do not forget to run 'RESET MASTER'.
on 'Master' before making 'Slave 1', 'Slave 2', and 'Slave 3' slaves of
'Master'.  If you fail to do this, the slaves may pick up stale writes
from the 'Web Client' applications dating from before the point at which
'Master' became unavailable.

You should be aware that there is no synchronization between slaves,
even when they share the same master, and thus some slaves might be
considerably ahead of others.  This means that in some cases the
procedure outlined in the previous example might not work as expected.
In practice, however, relay logs on all slaves should be relatively
close together.

One way to keep applications informed about the location of the master
is to have a dynamic DNS entry for the master.  With 'bind' you can use
'nsupdate' to update the DNS dynamically.

16.3.8 Setting Up Replication to Use Encrypted Connections
----------------------------------------------------------

To use an encrypted connection for the transfer of the binary log
required during replication, both the master and the slave servers must
support encrypted network connections.  If either server does not
support encrypted connections (because it has not been compiled or
configured for them), replication through an encrypted connection is not
possible.

Setting up encrypted connections for replication is similar to doing so
for client/server connections.  You must obtain (or create) a suitable
security certificate that you can use on the master, and a similar
certificate (from the same certificate authority) on each slave.  You
must also obtain suitable key files.

For more information on setting up a server and client for encrypted
connections, see using-encrypted-connections.

To enable encrypted connections on the master, you must create or obtain
suitable certificate and key files, and then add the following
configuration options to the master's configuration within the
'[mysqld]' section of the master's 'my.cnf' file, changing the file
names as necessary:

     [mysqld]
     ssl-ca=cacert.pem
     ssl-cert=server-cert.pem
     ssl-key=server-key.pem

The paths to the files may be relative or absolute; we recommend that
you always use complete paths for this purpose.

The options are as follows:

   * '--ssl-ca': The path name of the Certificate Authority (CA)
     certificate file.  ('--ssl-capath' is similar but specifies the
     path name of a directory of CA certificate files.)

   * '--ssl-cert': The path name of the server public key certificate
     file.  This can be sent to the client and authenticated against the
     CA certificate that it has.

   * '--ssl-key': The path name of the server private key file.

To enable encrypted connections on the slave, use the 'CHANGE MASTER TO'
statement.  You can either name the slave
certificate and SSL private key files required for the encrypted
connection in the '[client]' section of the slave's 'my.cnf' file, or
you can explicitly specify that information using the 'CHANGE MASTER TO'
statement.  For more information on the
'CHANGE MASTER TO' statement, see
change-master-to.

   * To name the slave certificate and key files using an option file,
     add the following lines to the '[client]' section of the slave's
     'my.cnf' file, changing the file names as necessary:

          [client]
          ssl-ca=cacert.pem
          ssl-cert=client-cert.pem
          ssl-key=client-key.pem

   * Restart the slave server, using the '--skip-slave-start' option to
     prevent the slave from connecting to the master.  Use 'CHANGE MASTER TO'
     to specify the master configuration,
     and add the 'MASTER_SSL' option to connect using encryption:

          mysql> CHANGE MASTER TO
              -> MASTER_HOST='master_hostname',
              -> MASTER_USER='repl',
              -> MASTER_PASSWORD='PASSWORD',
              -> MASTER_SSL=1;

     Setting 'MASTER_SSL=1' for a replication connection and then
     setting no further 'MASTER_SSL_XXX' options corresponds to setting
     '--ssl-mode=REQUIRED' for the client, as described in
     encrypted-connection-options.  With 'MASTER_SSL=1', the
     connection attempt only succeeds if an encrypted connection can be
     established.  A replication connection does not fall back to an
     unencrypted connection, so there is no setting corresponding to the
     '--ssl-mode=PREFERRED' setting for replication.  If 'MASTER_SSL=0'
     is set, this corresponds to '--ssl-mode=DISABLED'.

   * To name the slave certificate and SSL private key files using the
     'CHANGE MASTER TO' statement, if you did
     not do this in the slave's 'my.cnf' file, add the appropriate
     'MASTER_SSL_XXX' options:

              -> MASTER_SSL_CA = 'ca_file_name',
              -> MASTER_SSL_CAPATH = 'ca_directory_name',
              -> MASTER_SSL_CERT = 'cert_file_name',
              -> MASTER_SSL_KEY = 'key_file_name',

     These options correspond to the '--ssl-XXX' options with the same
     names, as described in encrypted-connection-options.  For
     these options to take effect, 'MASTER_SSL=1' must also be set.  For
     a replication connection, specifying a value for either of '
     MASTER_SSL_CA' or 'MASTER_SSL_CAPATH', or specifying these options
     in the slave's 'my.cnf' file, corresponds to setting
     '--ssl-mode=VERIFY_CA'.  The connection attempt only succeeds if a
     valid matching Certificate Authority (CA) certificate is found
     using the specified information.

   * To activate host name identity verification, add the
     'MASTER_SSL_VERIFY_SERVER_CERT' option:

              -> MASTER_SSL_VERIFY_SERVER_CERT=1,

     This option corresponds to the '--ssl-verify-server-cert' option,
     which is deprecated as of MySQL 5.7.11 and is removed in MySQL 8.0.
     For a replication connection, specifying
     'MASTER_SSL_VERIFY_SERVER_CERT=1' corresponds to setting
     '--ssl-mode=VERIFY_IDENTITY', as described in
     encrypted-connection-options.  For this option to take effect,
     'MASTER_SSL=1' must also be set.  Host name identity verification
     does not work with self-signed certificates.

   * To activate certificate revocation list (CRL) checks, add the
     'MASTER_SSL_CRL' or 'MASTER_SSL_CRLPATH' option:

              -> MASTER_SSL_CRL = 'crl_file_name',
              -> MASTER_SSL_CRLPATH = 'crl_directory_name',

     These options correspond to the '--ssl-XXX' options with the same
     names, as described in encrypted-connection-options.  If
     they are not specified, no CRL checking takes place.

   * To specify lists of permitted ciphers and encryption protocols for
     the replication connection, add the 'MASTER_SSL_CIPHER' and
     'MASTER_TLS_VERSION' options:

              -> MASTER_SSL_CIPHER = 'cipher_list',
              -> MASTER_TLS_VERSION = 'protocol_list',

     The 'MASTER_TLS_VERSION' option specifies the encryption protocols
     permitted for the replication connection.  The format is like that
     for the 'tls_version' system variable, with one or more protocol
     names separated by commas.  The 'MASTER_SSL_CIPHER' option
     specifies the list of permitted ciphers for the replication
     connection, with one or more cipher names separated by colons.  The
     protocols and ciphers that you can use in these lists depend on the
     SSL library used to compile MySQL. For information on how to
     specify these options, see
     encrypted-connection-protocols-ciphers.

   * After the master information has been updated, start the slave
     replication process:

          mysql> START SLAVE;

     You can use the 'SHOW SLAVE STATUS'.
     statement to confirm that an encrypted connection was established
     successfully.

   * Requiring encrypted connections on the slave does not ensure that
     the master requires encrypted connections from slaves.  If you want
     to ensure that the master only accepts replication slaves that
     connect using encrypted connections, create a replication user
     account on the master using the 'REQUIRE SSL' option, then grant
     that user the 'REPLICATION SLAVE' privilege.  For example:

          mysql> CREATE USER 'repl'@'%.example.com' IDENTIFIED BY 'PASSWORD'
              -> REQUIRE SSL;
          mysql> GRANT REPLICATION SLAVE ON *.*
              -> TO 'repl'@'%.example.com';

     If you have an existing replication user account on the master, you
     can add 'REQUIRE SSL' to it with this statement:

          mysql> ALTER USER 'repl'@'%.example.com' REQUIRE SSL;

16.3.9 Semisynchronous Replication
----------------------------------

In addition to the built-in asynchronous replication, MySQL 5.7 supports
an interface to semisynchronous replication that is implemented by
plugins.  This section discusses what semisynchronous replication is and
how it works.  The following sections cover the administrative interface
to semisynchronous replication and how to install, configure, and
monitor it.

MySQL replication by default is asynchronous.  The master writes events
to its binary log but does not know whether or when a slave has
retrieved and processed them.  With asynchronous replication, if the
master crashes, transactions that it has committed might not have been
transmitted to any slave.  Consequently, failover from master to slave
in this case may result in failover to a server that is missing
transactions relative to the master.

Semisynchronous replication can be used as an alternative to
asynchronous replication:

   * A slave indicates whether it is semisynchronous-capable when it
     connects to the master.

   * If semisynchronous replication is enabled on the master side and
     there is at least one semisynchronous slave, a thread that performs
     a transaction commit on the master blocks and waits until at least
     one semisynchronous slave acknowledges that it has received all
     events for the transaction, or until a timeout occurs.

   * The slave acknowledges receipt of a transaction's events only after
     the events have been written to its relay log and flushed to disk.

   * If a timeout occurs without any slave having acknowledged the
     transaction, the master reverts to asynchronous replication.  When
     at least one semisynchronous slave catches up, the master returns
     to semisynchronous replication.

   * Semisynchronous replication must be enabled on both the master and
     slave sides.  If semisynchronous replication is disabled on the
     master, or enabled on the master but on no slaves, the master uses
     asynchronous replication.

While the master is blocking (waiting for acknowledgment from a slave),
it does not return to the session that performed the transaction.  When
the block ends, the master returns to the session, which then can
proceed to execute other statements.  At this point, the transaction has
committed on the master side, and receipt of its events has been
acknowledged by at least one slave.

The number of slave acknowledgments the master must receive per
transaction before proceeding is configurable using the
'rpl_semi_sync_master_wait_for_slave_count' system variable.  The
default value is 1.

Blocking also occurs after rollbacks that are written to the binary log,
which occurs when a transaction that modifies nontransactional tables is
rolled back.  The rolled-back transaction is logged even though it has
no effect for transactional tables because the modifications to the
nontransactional tables cannot be rolled back and must be sent to
slaves.

For statements that do not occur in transactional context (that is, when
no transaction has been started with 'START TRANSACTION'.
or 'SET autocommit = 0'), autocommit is enabled and
each statement commits implicitly.  With semisynchronous replication,
the master blocks for each such statement, just as it does for explicit
transaction commits.

To understand what the 'semi' in 'semisynchronous replication' means,
compare it with asynchronous and fully synchronous replication:

   * With asynchronous replication, the master writes events to its
     binary log and slaves request them when they are ready.  There is
     no guarantee that any event will ever reach any slave.

   * With fully synchronous replication, when a master commits a
     transaction, all slaves also will have committed the transaction
     before the master returns to the session that performed the
     transaction.  The drawback of this is that there might be a lot of
     delay to complete a transaction.

   * Semisynchronous replication falls between asynchronous and fully
     synchronous replication.  The master waits only until at least one
     slave has received and logged the events.  It does not wait for all
     slaves to acknowledge receipt, and it requires only receipt, not
     that the events have been fully executed and committed on the slave
     side.

Compared to asynchronous replication, semisynchronous replication
provides improved data integrity because when a commit returns
successfully, it is known that the data exists in at least two places.
Until a semisynchronous master receives acknowledgment from the number
of slaves configured by 'rpl_semi_sync_master_wait_for_slave_count', the
transaction is on hold and not committed.

Semisynchronous replication also places a rate limit on busy sessions by
constraining the speed at which binary log events can be sent from
master to slave.  When one user is too busy, this will slow it down,
which is useful in some deployment situations.

Semisynchronous replication does have some performance impact because
commits are slower due to the need to wait for slaves.  This is the
tradeoff for increased data integrity.  The amount of slowdown is at
least the TCP/IP roundtrip time to send the commit to the slave and wait
for the acknowledgment of receipt by the slave.  This means that
semisynchronous replication works best for close servers communicating
over fast networks, and worst for distant servers communicating over
slow networks.

The 'rpl_semi_sync_master_wait_point' system variable controls the point
at which a semisynchronous replication master waits for slave
acknowledgment of transaction receipt before returning a status to the
client that committed the transaction.  These values are permitted:

   * 'AFTER_SYNC' (the default): The master writes each transaction to
     its binary log and the slave, and syncs the binary log to disk.
     The master waits for slave acknowledgment of transaction receipt
     after the sync.  Upon receiving acknowledgment, the master commits
     the transaction to the storage engine and returns a result to the
     client, which then can proceed.

   * 'AFTER_COMMIT': The master writes each transaction to its binary
     log and the slave, syncs the binary log, and commits the
     transaction to the storage engine.  The master waits for slave
     acknowledgment of transaction receipt after the commit.  Upon
     receiving acknowledgment, the master returns a result to the
     client, which then can proceed.

The replication characteristics of these settings differ as follows:

   * With 'AFTER_SYNC', all clients see the committed transaction at the
     same time: After it has been acknowledged by the slave and
     committed to the storage engine on the master.  Thus, all clients
     see the same data on the master.

     In the event of master failure, all transactions committed on the
     master have been replicated to the slave (saved to its relay log).
     A crash of the master and failover to the slave is lossless because
     the slave is up to date.

   * With 'AFTER_COMMIT', the client issuing the transaction gets a
     return status only after the server commits to the storage engine
     and receives slave acknowledgment.  After the commit and before
     slave acknowledgment, other clients can see the committed
     transaction before the committing client.

     If something goes wrong such that the slave does not process the
     transaction, then in the event of a master crash and failover to
     the slave, it is possible that such clients will see a loss of data
     relative to what they saw on the master.

16.3.9.1 Semisynchronous Replication Administrative Interface
.............................................................

The administrative interface to semisynchronous replication has several
components:

   * Two plugins implement semisynchronous capability.  There is one
     plugin for the master side and one for the slave side.

   * System variables control plugin behavior.  Some examples:

        * 'rpl_semi_sync_master_enabled'

          Controls whether semisynchronous replication is enabled on the
          master.  To enable or disable the plugin, set this variable to
          1 or 0, respectively.  The default is 0 (off).

        * 'rpl_semi_sync_master_timeout'

          A value in milliseconds that controls how long the master
          waits on a commit for acknowledgment from a slave before
          timing out and reverting to asynchronous replication.  The
          default value is 10000 (10 seconds).

        * 'rpl_semi_sync_slave_enabled'

          Similar to 'rpl_semi_sync_master_enabled', but controls the
          slave plugin.

     All 'rpl_semi_sync_XXX' system variables are described at
     server-system-variables.

   * Status variables enable semisynchronous replication monitoring.
     Some examples:

        * 'Rpl_semi_sync_master_clients'

          The number of semisynchronous slaves.

        * 'Rpl_semi_sync_master_status'

          Whether semisynchronous replication currently is operational
          on the master.  The value is 1 if the plugin has been enabled
          and a commit acknowledgment has not occurred.  It is 0 if the
          plugin is not enabled or the master has fallen back to
          asynchronous replication due to commit acknowledgment timeout.

        * 'Rpl_semi_sync_master_no_tx'

          The number of commits that were not acknowledged successfully
          by a slave.

        * 'Rpl_semi_sync_master_yes_tx'

          The number of commits that were acknowledged successfully by a
          slave.

        * 'Rpl_semi_sync_slave_status'

          Whether semisynchronous replication currently is operational
          on the slave.  This is 1 if the plugin has been enabled and
          the slave I/O thread is running, 0 otherwise.

     All 'Rpl_semi_sync_XXX' status variables are described at
     server-status-variables.

The system and status variables are available only if the appropriate
master or slave plugin has been installed with 'INSTALL PLUGIN'.

16.3.9.2 Semisynchronous Replication Installation and Configuration
...................................................................

Semisynchronous replication is implemented using plugins, so the plugins
must be installed into the server to make them available.  After a
plugin has been installed, you control it by means of the system
variables associated with it.  These system variables are unavailable
until the associated plugin has been installed.

This section describes how to install the semisynchronous replication
plugins.  For general information about installing plugins, see
server-plugin-loading.

To use semisynchronous replication, the following requirements must be
satisfied:

   * MySQL 5.5 or higher must be installed.

   * The capability of installing plugins requires a MySQL server that
     supports dynamic loading.  To verify this, check that the value of
     the 'have_dynamic_loading' system variable is 'YES'.  Binary
     distributions should support dynamic loading.

   * Replication must already be working, see
     replication-configuration.

   * There must not be multiple replication channels configured.
     Semisynchronous replication is only compatible with the default
     replication channel.  See replication-channels.

To set up semisynchronous replication, use the following instructions.
The 'INSTALL PLUGIN', 'SET GLOBAL',
see 'STOP SLAVE', and 'START SLAVE'
statements mentioned here require the 'SUPER' privilege.

MySQL distributions include semisynchronous replication plugin files for
the master side and the slave side.

To be usable by a master or slave server, the appropriate plugin library
file must be located in the MySQL plugin directory (the directory named
by the 'plugin_dir' system variable).  If necessary, set the value of
'plugin_dir' at server startup to tell the server the plugin directory
location.

The plugin library file base names are 'semisync_master' and
'semisync_slave'.  The file name suffix differs per platform (for
example, '.so' for Unix and Unix-like systems, '.dll' for Windows).

The master plugin library file must be present in the plugin directory
of the master server.  The slave plugin library file must be present in
the plugin directory of each slave server.

To load the plugins, use the 'INSTALL PLUGIN'.
statement on the master and on each slave that is to be semisynchronous
(adjust the '.so' suffix for your platform as necessary).

On the master:

     INSTALL PLUGIN rpl_semi_sync_master SONAME 'semisync_master.so';

On each slave:

     INSTALL PLUGIN rpl_semi_sync_slave SONAME 'semisync_slave.so';

If an attempt to install a plugin results in an error on Linux similar
to that shown here, you must install 'libimf':

     mysql> INSTALL PLUGIN rpl_semi_sync_master SONAME 'semisync_master.so';
     ERROR 1126 (HY000): Can't open shared library
     '/usr/local/mysql/lib/plugin/semisync_master.so'
     (errno: 22 libimf.so: cannot open shared object file:
     No such file or directory)

You can obtain 'libimf' from
<http://dev.mysql.com/downloads/os-linux.html>.

To see which plugins are installed, use the 'SHOW PLUGINS'
statement, or query the
'INFORMATION_SCHEMA.PLUGINS' table.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE '%semi%';
     +----------------------+---------------+
     | PLUGIN_NAME          | PLUGIN_STATUS |
     +----------------------+---------------+
     | rpl_semi_sync_master | ACTIVE        |
     +----------------------+---------------+

If the plugin fails to initialize, check the server error log for
diagnostic messages.

After a semisynchronous replication plugin has been installed, it is
disabled by default.  The plugins must be enabled both on the master
side and the slave side to enable semisynchronous replication.  If only
one side is enabled, replication will be asynchronous.

To control whether an installed plugin is enabled, set the appropriate
system variables.  You can set these variables at runtime using
'SET GLOBAL', or at server startup on the command line or
in an option file.

At runtime, these master-side system variables are available:

     SET GLOBAL rpl_semi_sync_master_enabled = {0|1};
     SET GLOBAL rpl_semi_sync_master_timeout = N;

On the slave side, this system variable is available:

     SET GLOBAL rpl_semi_sync_slave_enabled = {0|1};

For 'rpl_semi_sync_master_enabled' or 'rpl_semi_sync_slave_enabled', the
value should be 1 to enable semisynchronous replication or 0 to disable
it.  By default, these variables are set to 0.

For 'rpl_semi_sync_master_timeout', the value N is given in
milliseconds.  The default value is 10000 (10 seconds).

If you enable semisynchronous replication on a slave at runtime, you
must also start the slave I/O thread (stopping it first if it is already
running) to cause the slave to connect to the master and register as a
semisynchronous slave:

     STOP SLAVE IO_THREAD;
     START SLAVE IO_THREAD;

If the I/O thread is already running and you do not restart it, the
slave continues to use asynchronous replication.

At server startup, the variables that control semisynchronous
replication can be set as command-line options or in an option file.  A
setting listed in an option file takes effect each time the server
starts.  For example, you can set the variables in 'my.cnf' files on the
master and slave sides as follows.

On the master:

     [mysqld]
     rpl_semi_sync_master_enabled=1
     rpl_semi_sync_master_timeout=1000 # 1 second

On each slave:

     [mysqld]
     rpl_semi_sync_slave_enabled=1

16.3.9.3 Semisynchronous Replication Monitoring
...............................................

The plugins for the semisynchronous replication capability expose
several system and status variables that you can examine to determine
its configuration and operational state.

The system variable reflect how semisynchronous replication is
configured.  To check their values, use 'SHOW VARIABLES'.:

     mysql> SHOW VARIABLES LIKE 'rpl_semi_sync%';

The status variables enable you to monitor the operation of
semisynchronous replication.  To check their values, use 'SHOW STATUS'.:

     mysql> SHOW STATUS LIKE 'Rpl_semi_sync%';

When the master switches between asynchronous or semisynchronous
replication due to commit-blocking timeout or a slave catching up, it
sets the value of the 'Rpl_semi_sync_master_status' status variable
appropriately.  Automatic fallback from semisynchronous to asynchronous
replication on the master means that it is possible for the
'rpl_semi_sync_master_enabled' system variable to have a value of 1 on
the master side even when semisynchronous replication is in fact not
operational at the moment.  You can monitor the
'Rpl_semi_sync_master_status' status variable to determine whether the
master currently is using asynchronous or semisynchronous replication.

To see how many semisynchronous slaves are connected, check
'Rpl_semi_sync_master_clients'.

The number of commits that have been acknowledged successfully or
unsuccessfully by slaves are indicated by the
'Rpl_semi_sync_master_yes_tx' and 'Rpl_semi_sync_master_no_tx'
variables.

On the slave side, 'Rpl_semi_sync_slave_status' indicates whether
semisynchronous replication currently is operational.

16.3.10 Delayed Replication
---------------------------

MySQL 5.7 supports delayed replication such that a slave server
deliberately lags behind the master by at least a specified amount of
time.  The default delay is 0 seconds.  Use the 'MASTER_DELAY' option
for 'CHANGE MASTER TO' to set the delay to N
seconds:

     CHANGE MASTER TO MASTER_DELAY = N;

An event received from the master is not executed until at least N
seconds later than its execution on the master.  The exceptions are that
there is no delay for format description events or log file rotation
events, which affect only the internal state of the SQL thread.

Delayed replication can be used for several purposes:

   * To protect against user mistakes on the master.  A DBA can roll
     back a delayed slave to the time just before the disaster.

   * To test how the system behaves when there is a lag.  For example,
     in an application, a lag might be caused by a heavy load on the
     slave.  However, it can be difficult to generate this load level.
     Delayed replication can simulate the lag without having to simulate
     the load.  It can also be used to debug conditions related to a
     lagging slave.

   * To inspect what the database looked like long ago, without having
     to reload a backup.  For example, if the delay is one week and the
     DBA needs to see what the database looked like before the last few
     days' worth of development, the delayed slave can be inspected.

'START SLAVE' and 'STOP SLAVE'.
take effect immediately and ignore any delay.  'RESET SLAVE'
resets the delay to 0.

'SHOW SLAVE STATUS' has three fields that
provide information about the delay:

   * 'SQL_Delay': A nonnegative integer indicating the number of seconds
     that the slave must lag the master.

   * 'SQL_Remaining_Delay': When 'Slave_SQL_Running_State' is 'Waiting
     until MASTER_DELAY seconds after master executed event', this field
     contains an integer indicating the number of seconds left of the
     delay.  At other times, this field is 'NULL'.

   * 'Slave_SQL_Running_State': A string indicating the state of the SQL
     thread (analogous to 'Slave_IO_State').  The value is identical to
     the 'State' value of the SQL thread as displayed by 'SHOW PROCESSLIST'.

When the slave SQL thread is waiting for the delay to elapse before
executing an event, see 'SHOW PROCESSLIST' displays
its 'State' value as 'Waiting until MASTER_DELAY seconds after master
executed event'.

16.4 Replication Notes and Tips
===============================

16.4.1 Replication Features and Issues
--------------------------------------

The following sections provide information about what is supported and
what is not in MySQL replication, and about specific issues and
situations that may occur when replicating certain statements.

Statement-based replication depends on compatibility at the SQL level
between the master and slave.  In other words, successful
statement-based replication requires that any SQL features used be
supported by both the master and the slave servers.  If you use a
feature on the master server that is available only in the current
version of MySQL, you cannot replicate to a slave that uses an earlier
version of MySQL. Such incompatibilities can also occur within a release
series as well as between versions.

If you are planning to use statement-based replication between MySQL 5.7
and a previous MySQL release series, it is a good idea to consult the
edition of the 'MySQL Reference Manual' corresponding to the earlier
release series for information regarding the replication characteristics
of that series.

With MySQL's statement-based replication, there may be issues with
replicating stored routines or triggers.  You can avoid these issues by
using MySQL's row-based replication instead.  For a detailed list of
issues, see stored-programs-logging.  For more information about
row-based logging and row-based replication, see
binary-log-formats, and replication-formats.

For additional information specific to replication and 'InnoDB', see
innodb-and-mysql-replication.  For information relating to
replication with NDB Cluster, see mysql-cluster-replication.

16.4.1.1 Replication and AUTO_INCREMENT
.......................................

Statement-based replication of 'AUTO_INCREMENT', 'LAST_INSERT_ID()', and
'TIMESTAMP' values is done correctly, subject to the
following exceptions:

   * When using statement-based replication prior to MySQL 5.7.1,
     'AUTO_INCREMENT' columns in tables on the slave must match the same
     columns on the master; that is, 'AUTO_INCREMENT' columns must be
     replicated to 'AUTO_INCREMENT' columns.

   * A statement invoking a trigger or function that causes an update to
     an 'AUTO_INCREMENT' column is not replicated correctly using
     statement-based replication.  These statements are marked as
     unsafe.  (Bug #45677)

   * An 'INSERT' into a table that has a composite
     primary key that includes an 'AUTO_INCREMENT' column that is not
     the first column of this composite key is not safe for
     statement-based logging or replication.  These statements are
     marked as unsafe.  (Bug #11754117, Bug #45670)

     This issue does not affect tables using the 'InnoDB'
     storage engine, since an 'InnoDB' table with
     an AUTO_INCREMENT column requires at least one key where the
     auto-increment column is the only or leftmost column.

   * Adding an 'AUTO_INCREMENT' column to a table with 'ALTER TABLE'
     might not produce the same ordering of the
     rows on the slave and the master.  This occurs because the order in
     which the rows are numbered depends on the specific storage engine
     used for the table and the order in which the rows were inserted.
     If it is important to have the same order on the master and slave,
     the rows must be ordered before assigning an 'AUTO_INCREMENT'
     number.  Assuming that you want to add an 'AUTO_INCREMENT' column
     to a table 't1' that has columns 'col1' and 'col2', the following
     statements produce a new table 't2' identical to 't1' but with an
     'AUTO_INCREMENT' column:

          CREATE TABLE t2 LIKE t1;
          ALTER TABLE t2 ADD id INT AUTO_INCREMENT PRIMARY KEY;
          INSERT INTO t2 SELECT * FROM t1 ORDER BY col1, col2;

     *Important*:

     To guarantee the same ordering on both master and slave, the 'ORDER
     BY' clause must name _all_ columns of 't1'.

     The instructions just given are subject to the limitations of
     'CREATE TABLE ... LIKE'.: Foreign key
     definitions are ignored, as are the 'DATA DIRECTORY' and 'INDEX
     DIRECTORY' table options.  If a table definition includes any of
     those characteristics, create 't2' using a 'CREATE TABLE'
     statement that is identical to the one used to create
     't1', but with the addition of the 'AUTO_INCREMENT' column.

     Regardless of the method used to create and populate the copy
     having the 'AUTO_INCREMENT' column, the final step is to drop the
     original table and then rename the copy:

          DROP t1;
          ALTER TABLE t2 RENAME t1;

     See also alter-table-problems.

16.4.1.2 Replication and BLACKHOLE Tables
.........................................

The 'BLACKHOLE' storage engine accepts
data but discards it and does not store it.  When performing binary
logging, all inserts to such tables are always logged, regardless of the
logging format in use.  Updates and deletes are handled differently
depending on whether statement based or row based logging is in use.
With the statement based logging format, all statements affecting
'BLACKHOLE' tables are logged, but their effects ignored.  When using
row-based logging, updates and deletes to such tables are simply
skipped--they are not written to the binary log.  A warning is logged
whenever this occurs (Bug #13004581).

For this reason we recommend when you replicate to tables using the
'BLACKHOLE' storage engine that you
have the 'binlog_format' server variable set to 'STATEMENT', and not to
either 'ROW' or 'MIXED'.

16.4.1.3 Replication and Character Sets
.......................................

The following applies to replication between MySQL servers that use
different character sets:

   * If the master has databases with a character set different from the
     global 'character_set_server' value, you should design your
     'CREATE TABLE' statements so that they do not
     implicitly rely on the database default character set.  A good
     workaround is to state the character set and collation explicitly
     in 'CREATE TABLE' statements.

16.4.1.4 Replication and CHECKSUM TABLE
.......................................

'CHECKSUM TABLE' returns a checksum that is
calculated row by row, using a method that depends on the table row
storage format.  The storage format is not guaranteed to remain the same
between MySQL versions, so the checksum value might change following an
upgrade.

16.4.1.5 Replication of CREATE ... IF NOT EXISTS Statements
...........................................................

MySQL applies these rules when various 'CREATE ... IF NOT EXISTS'
statements are replicated:

   * Every 'CREATE DATABASE IF NOT EXISTS'.
     statement is replicated, whether or not the database already exists
     on the master.

   * Similarly, every 'CREATE TABLE IF NOT EXISTS'.
     statement without a 'SELECT' is replicated, whether
     or not the table already exists on the master.  This includes
     'CREATE TABLE IF NOT EXISTS ... LIKE'.
     Replication of 'CREATE TABLE IF NOT EXISTS ... SELECT'
     follows somewhat different rules; see
     replication-features-create-select, for more information.

   * 'CREATE EVENT IF NOT EXISTS' is always
     replicated, whether or not the event named in the statement already
     exists on the master.

16.4.1.6 Replication of CREATE TABLE ... SELECT Statements
..........................................................

This section discusses how MySQL replicates 'CREATE TABLE ... SELECT'
statements.

MySQL 5.7 does not allow a 'CREATE TABLE ... SELECT'
statement to make any changes in tables other than
the table that is created by the statement.  Some older versions of
MySQL permitted these statements to do so; this means that, when using
statement-based replication between a MySQL 5.6 or later slave and a
master running a previous version of MySQL, a 'CREATE TABLE ... SELECT'
statement causing changes in other tables
on the master fails on the slave, causing replication to stop.  To
prevent this from happening, you should use row-based replication,
rewrite the offending statement before running it on the master, or
upgrade the master to MySQL 5.7.  (If you choose to upgrade the master,
keep in mind that such a 'CREATE TABLE ... SELECT'
statement fails following the upgrade unless it is
rewritten to remove any side effects on other tables.)  This is not an
issue when using row-based replication, because the statement is logged
as a 'CREATE TABLE' statement with any changes to
table data logged as row-insert events, rather than as the entire
'CREATE TABLE ... SELECT'.

These behaviors are not dependent on MySQL version:

   * 'CREATE TABLE ... SELECT' always
     performs an implicit commit (see implicit-commit).

   * If destination table does not exist, logging occurs as follows.  It
     does not matter whether 'IF NOT EXISTS' is present.

        * 'STATEMENT' or 'MIXED' format: The statement is logged as
          written.

        * 'ROW' format: The statement is logged as a 'CREATE TABLE'
          statement followed by a series of
          insert-row events.

   * If the statement fails, nothing is logged.  This includes the case
     that the destination table exists and 'IF NOT EXISTS' is not given.

When the destination table exists and 'IF NOT EXISTS' is given, MySQL
5.7 ignores the statement completely; nothing is inserted or logged.
The handling of such statements in this regard has changed considerably
in previous MySQL releases; if you are replicating from a MySQL 5.5.6 or
older master to a newer slave, see Replication of CREATE ...  IF NOT
EXISTS Statements
(http://dev.mysql.com/doc/refman/5.5/en/replication-features-create-if-not-exists.html),
for more information.

16.4.1.7 Replication of CREATE SERVER, ALTER SERVER, and DROP SERVER
....................................................................

The statements 'CREATE SERVER', 'ALTER SERVER',
and 'DROP SERVER' are not
written to the binary log, regardless of the binary logging format that
is in use.

16.4.1.8 Replication of CURRENT_USER()
......................................

The following statements support use of the 'CURRENT_USER()' function to
take the place of the name of (and, possibly, the host for) an affected
user or a definer; in such cases, 'CURRENT_USER()' is expanded where and
as needed:

   * 'DROP USER'.

   * 'RENAME USER'.

   * 'GRANT'.

   * 'REVOKE'.

   * 'CREATE FUNCTION'.

   * 'CREATE PROCEDURE'.

   * 'CREATE TRIGGER'.

   * 'CREATE EVENT'.

   * 'CREATE VIEW'.

   * 'ALTER EVENT'.

   * 'ALTER VIEW'.

   * 'SET PASSWORD'.

When 'CURRENT_USER()' or 'CURRENT_USER' is used as the definer in any of
the statements 'CREATE FUNCTION', 'CREATE PROCEDURE',
see 'CREATE TRIGGER',
'CREATE EVENT', 'CREATE VIEW', or
'ALTER VIEW' when binary logging is enabled, the
function reference is expanded before it is written to the binary log,
so that the statement refers to the same user on both the master and the
slave when the statement is replicated.  'CURRENT_USER()' or
'CURRENT_USER' is also expanded prior to being written to the binary log
when used in 'DROP USER', 'RENAME USER',
see 'GRANT', 'REVOKE', or
'ALTER EVENT'.

16.4.1.9 Replication of DROP ... IF EXISTS Statements
.....................................................

The 'DROP DATABASE IF EXISTS', 'DROP TABLE IF EXISTS',
and 'DROP VIEW IF EXISTS'.
statements are always replicated, even if the database, table, or view
to be dropped does not exist on the master.  This is to ensure that the
object to be dropped no longer exists on either the master or the slave,
once the slave has caught up with the master.

'DROP ... IF EXISTS' statements for stored programs (stored procedures
and functions, triggers, and events) are also replicated, even if the
stored program to be dropped does not exist on the master.

16.4.1.10 Replication with Differing Table Definitions on Master and Slave
..........................................................................

Source and target tables for replication do not have to be identical.  A
table on the master can have more or fewer columns than the slave's copy
of the table.  In addition, corresponding table columns on the master
and the slave can use different data types, subject to certain
conditions.

*Note*:

Replication between tables which are partitioned differently from one
another is not supported.  See
replication-features-partitioning.

In all cases where the source and target tables do not have identical
definitions, the database and table names must be the same on both the
master and the slave.  Additional conditions are discussed, with
examples, in the following two sections.

16.4.1.11 Replication with More Columns on Master or Slave
..........................................................

You can replicate a table from the master to the slave such that the
master and slave copies of the table have differing numbers of columns,
subject to the following conditions:

   * Columns common to both versions of the table must be defined in the
     same order on the master and the slave.

     (This is true even if both tables have the same number of columns.)

   * Columns common to both versions of the table must be defined before
     any additional columns.

     This means that executing an 'ALTER TABLE'.
     statement on the slave where a new column is inserted into the
     table within the range of columns common to both tables causes
     replication to fail, as shown in the following example:

     Suppose that a table 't', existing on the master and the slave, is
     defined by the following 'CREATE TABLE'.
     statement:

          CREATE TABLE t (
              c1 INT,
              c2 INT,
              c3 INT
          );

     Suppose that the 'ALTER TABLE' statement shown
     here is executed on the slave:

          ALTER TABLE t ADD COLUMN cnew1 INT AFTER c3;

     The previous 'ALTER TABLE' is permitted on the
     slave because the columns 'c1', 'c2', and 'c3' that are common to
     both versions of table 't' remain grouped together in both versions
     of the table, before any columns that differ.

     However, the following 'ALTER TABLE' statement
     cannot be executed on the slave without causing replication to
     break:

          ALTER TABLE t ADD COLUMN cnew2 INT AFTER c2;

     Replication fails after execution on the slave of the 'ALTER TABLE'
     statement just shown, because the new column
     'cnew2' comes between columns common to both versions of 't'.

   * Each 'extra' column in the version of the table having more columns
     must have a default value.

     A column's default value is determined by a number of factors,
     including its type, whether it is defined with a 'DEFAULT' option,
     whether it is declared as 'NULL', and the server SQL mode in effect
     at the time of its creation; for more information, see
     data-type-defaults).

In addition, when the slave's copy of the table has more columns than
the master's copy, each column common to the tables must use the same
data type in both tables.

Examples

The following examples illustrate some valid and invalid table
definitions:

More columns on the master

The following table definitions are valid and replicate correctly:

     master> CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);
     slave>  CREATE TABLE t1 (c1 INT, c2 INT);

The following table definitions would raise an error because the
definitions of the columns common to both versions of the table are in a
different order on the slave than they are on the master:

     master> CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);
     slave>  CREATE TABLE t1 (c2 INT, c1 INT);

The following table definitions would also raise an error because the
definition of the extra column on the master appears before the
definitions of the columns common to both versions of the table:

     master> CREATE TABLE t1 (c3 INT, c1 INT, c2 INT);
     slave>  CREATE TABLE t1 (c1 INT, c2 INT);

More columns on the slave

The following table definitions are valid and replicate correctly:

     master> CREATE TABLE t1 (c1 INT, c2 INT);
     slave>  CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);

The following definitions raise an error because the columns common to
both versions of the table are not defined in the same order on both the
master and the slave:

     master> CREATE TABLE t1 (c1 INT, c2 INT);
     slave>  CREATE TABLE t1 (c2 INT, c1 INT, c3 INT);

The following table definitions also raise an error because the
definition for the extra column in the slave's version of the table
appears before the definitions for the columns which are common to both
versions of the table:

     master> CREATE TABLE t1 (c1 INT, c2 INT);
     slave>  CREATE TABLE t1 (c3 INT, c1 INT, c2 INT);

The following table definitions fail because the slave's version of the
table has additional columns compared to the master's version, and the
two versions of the table use different data types for the common column
'c2':

     master> CREATE TABLE t1 (c1 INT, c2 BIGINT);
     slave>  CREATE TABLE t1 (c1 INT, c2 INT, c3 INT);

16.4.1.12 Replication of Columns Having Different Data Types
............................................................

Corresponding columns on the master's and the slave's copies of the same
table ideally should have the same data type.  However, this is not
always strictly enforced, as long as certain conditions are met.

It is usually possible to replicate from a column of a given data type
to another column of the same type and same size or width, where
applicable, or larger.  For example, you can replicate from a 'CHAR(10)'
column to another 'CHAR(10)', or from a 'CHAR(10)' column to a
'CHAR(25)' column without any problems.  In certain cases, it also
possible to replicate from a column having one data type (on the master)
to a column having a different data type (on the slave); when the data
type of the master's version of the column is promoted to a type that is
the same size or larger on the slave, this is known as _attribute
promotion_.

Attribute promotion can be used with both statement-based and row-based
replication, and is not dependent on the storage engine used by either
the master or the slave.  However, the choice of logging format does
have an effect on the type conversions that are permitted; the
particulars are discussed later in this section.

*Important*:

Whether you use statement-based or row-based replication, the slave's
copy of the table cannot contain more columns than the master's copy if
you wish to employ attribute promotion.

Statement-based replication

When using statement-based replication, a simple rule of thumb to follow
is, 'If the statement run on the master would also execute successfully
on the slave, it should also replicate successfully'.  In other words,
if the statement uses a value that is compatible with the type of a
given column on the slave, the statement can be replicated.  For
example, you can insert any value that fits in a 'TINYINT' column into a
'BIGINT' column as well; it follows that, even if you change the type of
a 'TINYINT' column in the slave's copy of a table to 'BIGINT', any
insert into that column on the master that succeeds should also succeed
on the slave, since it is impossible to have a legal 'TINYINT' value
that is large enough to exceed a 'BIGINT' column.

Prior to MySQL 5.7.1, when using statement-based replication,
'AUTO_INCREMENT' columns were required to be the same on both the master
and the slave; otherwise, updates could be applied to the wrong table on
the slave.  (Bug #12669186)

Row-based replication: attribute promotion and demotion

Row-based replication supports attribute promotion and demotion between
smaller data types and larger types.  It is also possible to specify
whether or not to permit lossy (truncated) or non-lossy conversions of
demoted column values, as explained later in this section.

Lossy and non-lossy conversions

In the event that the target type cannot represent the value being
inserted, a decision must be made on how to handle the conversion.  If
we permit the conversion but truncate (or otherwise modify) the source
value to achieve a 'fit' in the target column, we make what is known as
a _lossy conversion_.  A conversion which does not require truncation or
similar modifications to fit the source column value in the target
column is a _non-lossy_ conversion.

Type conversion modes (slave_type_conversions variable)

The setting of the 'slave_type_conversions' global server variable
controls the type conversion mode used on the slave.  This variable
takes a set of values from the following table, which shows the effects
of each mode on the slave's type-conversion behavior:

Mode                      Effect

'ALL_LOSSY'
                          In this mode, type conversions that would
                          mean loss of information are permitted.

                          This does not imply that non-lossy
                          conversions are permitted, merely that only
                          cases requiring either lossy conversions or
                          no conversion at all are permitted; for
                          example, enabling _only_ this mode permits an
                          'INT' column to be converted to 'TINYINT' (a
                          lossy conversion), but not a 'TINYINT' column
                          to an 'INT' column (non-lossy).  Attempting
                          the latter conversion in this case would
                          cause replication to stop with an error on
                          the slave.

'ALL_NON_LOSSY'
                          This mode permits conversions that do not
                          require truncation or other special handling
                          of the source value; that is, it permits
                          conversions where the target type has a wider
                          range than the source type.

                          Setting this mode has no bearing on whether
                          lossy conversions are permitted; this is
                          controlled with the 'ALL_LOSSY' mode.  If
                          only 'ALL_NON_LOSSY' is set, but not
                          'ALL_LOSSY', then attempting a conversion
                          that would result in the loss of data (such
                          as 'INT' to 'TINYINT', or 'CHAR(25)' to
                          'VARCHAR(20)') causes the slave to stop with
                          an error.

'ALL_LOSSY,ALL_NON_LOSSY'
                          When this mode is set, all supported type
                          conversions are permitted, whether or not
                          they are lossy conversions.

'ALL_SIGNED'
                          Treat promoted integer types as signed values
                          (the default behavior).

'ALL_UNSIGNED'
                          Treat promoted integer types as unsigned
                          values.

'ALL_SIGNED,ALL_UNSIGNED'
                          Treat promoted integer types as signed if
                          possible, otherwise as unsigned.

[_empty_]
                          When 'slave_type_conversions' is not set, no
                          attribute promotion or demotion is permitted;
                          this means that all columns in the source and
                          target tables must be of the same types.

                          This mode is the default.

When an integer type is promoted, its signedness is not preserved.  By
default, the slave treats all such values as signed.  Beginning with
MySQL 5.7.2, you can control this behavior using 'ALL_SIGNED',
'ALL_UNSIGNED', or both.  (Bug#15831300) 'ALL_SIGNED' tells the slave to
treat all promoted integer types as signed; 'ALL_UNSIGNED' instructs it
to treat these as unsigned.  Specifying both causes the slave to treat
the value as signed if possible, otherwise to treat it as unsigned; the
order in which they are listed is not significant.  Neither 'ALL_SIGNED'
nor 'ALL_UNSIGNED' has any effect if at least one of 'ALL_LOSSY' or
'ALL_NONLOSSY' is not also used.

Changing the type conversion mode requires restarting the slave with the
new 'slave_type_conversions' setting.

Supported conversions

Supported conversions between different but similar data types are shown
in the following list:

   * Between any of the integer types 'TINYINT',
     'SMALLINT', 'MEDIUMINT',
     'INT', and 'BIGINT'.

     This includes conversions between the signed and unsigned versions
     of these types.

     Lossy conversions are made by truncating the source value to the
     maximum (or minimum) permitted by the target column.  For ensuring
     non-lossy conversions when going from unsigned to signed types, the
     target column must be large enough to accommodate the range of
     values in the source column.  For example, you can demote 'TINYINT
     UNSIGNED' non-lossily to 'SMALLINT', but not to 'TINYINT'.

   * Between any of the decimal types 'DECIMAL',
     see 'FLOAT',
     'DOUBLE', and 'NUMERIC'.

     'FLOAT' to 'DOUBLE' is a non-lossy conversion; 'DOUBLE' to 'FLOAT'
     can only be handled lossily.  A conversion from 'DECIMAL(M,D)' to
     'DECIMAL(M',D')' where 'D' >= D' and '(M'-D') >= (M-D') is
     non-lossy; for any case where 'M' < M', 'D' < D', or both, only a
     lossy conversion can be made.

     For any of the decimal types, if a value to be stored cannot be fit
     in the target type, the value is rounded down according to the
     rounding rules defined for the server elsewhere in the
     documentation.  See precision-math-rounding, for
     information about how this is done for decimal types.

   * Between any of the string types 'CHAR',
     'VARCHAR', and 'TEXT', including conversions
     between different widths.

     Conversion of a 'CHAR', 'VARCHAR', or 'TEXT' to a 'CHAR',
     'VARCHAR', or 'TEXT' column the same size or larger is never lossy.
     Lossy conversion is handled by inserting only the first N
     characters of the string on the slave, where N is the width of the
     target column.

     *Important*:

     Replication between columns using different character sets is not
     supported.

   * Between any of the binary data types 'BINARY',
     see 'VARBINARY', and
     'BLOB', including conversions between different widths.

     Conversion of a 'BINARY', 'VARBINARY', or 'BLOB' to a 'BINARY',
     'VARBINARY', or 'BLOB' column the same size or larger is never
     lossy.  Lossy conversion is handled by inserting only the first N
     bytes of the string on the slave, where N is the width of the
     target column.

   * Between any 2 'BIT' columns of any 2 sizes.

     When inserting a value from a 'BIT(M)' column into a 'BIT(M')'
     column, where 'M' > M', the most significant bits of the 'BIT(M')'
     columns are cleared (set to zero) and the M bits of the 'BIT(M)'
     value are set as the least significant bits of the 'BIT(M')'
     column.

     When inserting a value from a source 'BIT(M)' column into a target
     'BIT(M')' column, where 'M' < M', the maximum possible value for
     the 'BIT(M')' column is assigned; in other words, an 'all-set'
     value is assigned to the target column.

Conversions between types not in the previous list are not permitted.

16.4.1.13 Replication and DIRECTORY Table Options
.................................................

If a 'DATA DIRECTORY' or 'INDEX DIRECTORY' table option is used in a
'CREATE TABLE' statement on the master server, the
table option is also used on the slave.  This can cause problems if no
corresponding directory exists in the slave host file system or if it
exists but is not accessible to the slave server.  This can be
overridden by using the 'NO_DIR_IN_CREATE' server SQL mode on the slave,
which causes the slave to ignore the 'DATA DIRECTORY' and 'INDEX
DIRECTORY' table options when replicating 'CREATE TABLE'
statements.  The result is that 'MyISAM' data and index
files are created in the table's database directory.

For more information, see sql-mode.

16.4.1.14 Replication and Floating-Point Values
...............................................

With statement-based replication, values are converted from decimal to
binary.  Because conversions between decimal and binary representations
of them may be approximate, comparisons involving floating-point values
are inexact.  This is true for operations that use floating-point values
explicitly, or that use values that are converted to floating-point
implicitly.  Comparisons of floating-point values might yield different
results on master and slave servers due to differences in computer
architecture, the compiler used to build MySQL, and so forth.  See
type-conversion, and problems-with-float.

16.4.1.15 Replication and Fractional Seconds Support
....................................................

MySQL 5.7 permits fractional seconds for 'TIME',
'DATETIME', and 'TIMESTAMP' values, with up
to microseconds (6 digits) precision.  See fractional-seconds.

There may be problems replicating from a master server that understands
fractional seconds to an older slave (MySQL 5.6.3 and earlier) that does
not:

   * For 'CREATE TABLE' statements containing
     columns that have an FSP (fractional seconds precision) value
     greater than 0, replication will fail due to parser errors.

   * Statements that use temporal data types with an FSP value of 0 will
     work for with statement-based logging but not row-based logging.
     In the latter case, the data types have binary formats and type
     codes on the master that differ from those on the slave.

   * Some expression results will differ on master and slave.  Examples:
     On the master, the 'timestamp' system variable returns a value that
     includes a microseconds fractional part; on the slave, it returns
     an integer.  On the master, functions that return a result that
     includes the current time (such as 'CURTIME()', 'SYSDATE()', or
     'UTC_TIMESTAMP()') interpret an argument as an FSP value and the
     return value includes a fractional seconds part of that many
     digits.  On the slave, these functions permit an argument but
     ignore it.

16.4.1.16 Replication and FLUSH
...............................

Some forms of the 'FLUSH' statement are not logged because
they could cause problems if replicated to a slave: 'FLUSH LOGS' and
'FLUSH TABLES WITH READ LOCK'.  For a syntax example, see flush.
The 'FLUSH TABLES', see 'ANALYZE TABLE',
'OPTIMIZE TABLE', and 'REPAIR TABLE'
statements are written to the binary log and thus
replicated to slaves.  This is not normally a problem because these
statements do not modify table data.

However, this behavior can cause difficulties under certain
circumstances.  If you replicate the privilege tables in the 'mysql'
database and update those tables directly without using 'GRANT',
you must issue a 'FLUSH PRIVILEGES' on the slaves to put the new
privileges into effect.  In addition, if you use 'FLUSH TABLES' when
renaming a 'MyISAM' table that is part of a 'MERGE' table, you must
issue 'FLUSH TABLES' manually on the slaves.  These statements are
written to the binary log unless you specify 'NO_WRITE_TO_BINLOG' or its
alias 'LOCAL'.

16.4.1.17 Replication and System Functions
..........................................

Certain functions do not replicate well under some conditions:

   * The 'USER()', 'CURRENT_USER()' (or 'CURRENT_USER'), 'UUID()',
     'VERSION()', and 'LOAD_FILE()' functions are replicated without
     change and thus do not work reliably on the slave unless row-based
     replication is enabled.  (See replication-formats.)

     'USER()' and 'CURRENT_USER()' are automatically replicated using
     row-based replication when using 'MIXED' mode, and generate a
     warning in 'STATEMENT' mode.  (See also
     replication-features-current-user.)  This is also true for
     'VERSION()' and 'RAND()'.

   * For 'NOW()', the binary log includes the timestamp.  This means
     that the value _as returned by the call to this function on the
     master_ is replicated to the slave.  To avoid unexpected results
     when replicating between MySQL servers in different time zones, set
     the time zone on both master and slave.  See also
     replication-features-timezone

     To explain the potential problems when replicating between servers
     which are in different time zones, suppose that the master is
     located in New York, the slave is located in Stockholm, and both
     servers are using local time.  Suppose further that, on the master,
     you create a table 'mytable', perform an 'INSERT'.
     statement on this table, and then select from the table, as shown
     here:

          mysql> CREATE TABLE mytable (mycol TEXT);
          Query OK, 0 rows affected (0.06 sec)

          mysql> INSERT INTO mytable VALUES ( NOW() );
          Query OK, 1 row affected (0.00 sec)

          mysql> SELECT * FROM mytable;
          +---------------------+
          | mycol               |
          +---------------------+
          | 2009-09-01 12:00:00 |
          +---------------------+
          1 row in set (0.00 sec)

     Local time in Stockholm is 6 hours later than in New York; so, if
     you issue 'SELECT NOW()' on the slave at that exact same instant,
     the value '2009-09-01 18:00:00' is returned.  For this reason, if
     you select from the slave's copy of 'mytable' after the
     'CREATE TABLE' and 'INSERT'.
     statements just shown have been replicated, you might expect
     'mycol' to contain the value '2009-09-01 18:00:00'.  However, this
     is not the case; when you select from the slave's copy of
     'mytable', you obtain exactly the same result as on the master:

          mysql> SELECT * FROM mytable;
          +---------------------+
          | mycol               |
          +---------------------+
          | 2009-09-01 12:00:00 |
          +---------------------+
          1 row in set (0.00 sec)

     Unlike 'NOW()', the 'SYSDATE()' function is not replication-safe
     because it is not affected by 'SET TIMESTAMP' statements in the
     binary log and is nondeterministic if statement-based logging is
     used.  This is not a problem if row-based logging is used.

     An alternative is to use the '--sysdate-is-now' option to cause
     'SYSDATE()' to be an alias for 'NOW()'.  This must be done on the
     master and the slave to work correctly.  In such cases, a warning
     is still issued by this function, but can safely be ignored as long
     as '--sysdate-is-now' is used on both the master and the slave.

     'SYSDATE()' is automatically replicated using row-based replication
     when using 'MIXED' mode, and generates a warning in 'STATEMENT'
     mode.

     See also replication-features-timezone.

   * _The following restriction applies to statement-based replication
     only, not to row-based replication._  The 'GET_LOCK()',
     'RELEASE_LOCK()', 'IS_FREE_LOCK()', and 'IS_USED_LOCK()' functions
     that handle user-level locks are replicated without the slave
     knowing the concurrency context on the master.  Therefore, these
     functions should not be used to insert into a master table because
     the content on the slave would differ.  For example, do not issue a
     statement such as 'INSERT INTO mytable VALUES(GET_LOCK(...))'.

     These functions are automatically replicated using row-based
     replication when using 'MIXED' mode, and generate a warning in
     'STATEMENT' mode.

As a workaround for the preceding limitations when statement-based
replication is in effect, you can use the strategy of saving the
problematic function result in a user variable and referring to the
variable in a later statement.  For example, the following single-row
'INSERT' is problematic due to the reference to the
'UUID()' function:

     INSERT INTO t VALUES(UUID());

To work around the problem, do this instead:

     SET @my_uuid = UUID();
     INSERT INTO t VALUES(@my_uuid);

That sequence of statements replicates because the value of '@my_uuid'
is stored in the binary log as a user-variable event prior to the
'INSERT' statement and is available for use in the
'INSERT'.

The same idea applies to multiple-row inserts, but is more cumbersome to
use.  For a two-row insert, you can do this:

     SET @my_uuid1 = UUID(); @my_uuid2 = UUID();
     INSERT INTO t VALUES(@my_uuid1),(@my_uuid2);

However, if the number of rows is large or unknown, the workaround is
difficult or impracticable.  For example, you cannot convert the
following statement to one in which a given individual user variable is
associated with each row:

     INSERT INTO t2 SELECT UUID(), * FROM t1;

Within a stored function, 'RAND()' replicates correctly as long as it is
invoked only once during the execution of the function.  (You can
consider the function execution timestamp and random number seed as
implicit inputs that are identical on the master and slave.)

The 'FOUND_ROWS()' and 'ROW_COUNT()' functions are not replicated
reliably using statement-based replication.  A workaround is to store
the result of the function call in a user variable, and then use that in
the 'INSERT' statement.  For example, if you wish to
store the result in a table named 'mytable', you might normally do so
like this:

     SELECT SQL_CALC_FOUND_ROWS FROM mytable LIMIT 1;
     INSERT INTO mytable VALUES( FOUND_ROWS() );

However, if you are replicating 'mytable', you should use 'SELECT ... INTO',
and then store the variable in the table, like
this:

     SELECT SQL_CALC_FOUND_ROWS INTO @found_rows FROM mytable LIMIT 1;
     INSERT INTO mytable VALUES(@found_rows);

In this way, the user variable is replicated as part of the context, and
applied on the slave correctly.

These functions are automatically replicated using row-based replication
when using 'MIXED' mode, and generate a warning in 'STATEMENT' mode.
(Bug #12092, Bug #30244)

Prior to MySQL 5.7.3, the value of 'LAST_INSERT_ID()' was not replicated
correctly if any filtering options such as '--replicate-ignore-db' and
'--replicate-do-table' were enabled on the slave.  (Bug #17234370, BUG#
69861)

16.4.1.18 Replication of Invoked Features
.........................................

Replication of invoked features such as user-defined functions (UDFs)
and stored programs (stored procedures and functions, triggers, and
events) provides the following characteristics:

   * The effects of the feature are always replicated.

   * The following statements are replicated using statement-based
     replication:

        * 'CREATE EVENT'.

        * 'ALTER EVENT'.

        * 'DROP EVENT'.

        * 'CREATE PROCEDURE'.

        * 'DROP PROCEDURE'.

        * 'CREATE FUNCTION'.

        * 'DROP FUNCTION'.

        * 'CREATE TRIGGER'.

        * 'DROP TRIGGER'.

     However, the _effects_ of features created, modified, or dropped
     using these statements are replicated using row-based replication.

     *Note*:

     Attempting to replicate invoked features using statement-based
     replication produces the warning 'Statement is not safe to log in
     statement format'.  For example, trying to replicate a UDF with
     statement-based replication generates this warning because it
     currently cannot be determined by the MySQL server whether the UDF
     is deterministic.  If you are absolutely certain that the invoked
     feature's effects are deterministic, you can safely disregard such
     warnings.

   *
     In the case of 'CREATE EVENT' and 'ALTER EVENT'.:

        * The status of the event is set to 'SLAVESIDE_DISABLED' on the
          slave regardless of the state specified (this does not apply
          to 'DROP EVENT').

        * The master on which the event was created is identified on the
          slave by its server ID. The 'ORIGINATOR' column in
          'INFORMATION_SCHEMA.EVENTS' and the
          'originator' column in 'mysql.event' store this information.
          See events-table, and show-events, for more
          information.

   * The feature implementation resides on the slave in a renewable
     state so that if the master fails, the slave can be used as the
     master without loss of event processing.

To determine whether there are any scheduled events on a MySQL server
that were created on a different server (that was acting as a
replication master), query the 'INFORMATION_SCHEMA.EVENTS'
table in a manner similar to what is shown here:

     SELECT EVENT_SCHEMA, EVENT_NAME
         FROM INFORMATION_SCHEMA.EVENTS
         WHERE STATUS = 'SLAVESIDE_DISABLED';

Alternatively, you can use the 'SHOW EVENTS'.
statement, like this:

     SHOW EVENTS
         WHERE STATUS = 'SLAVESIDE_DISABLED';

When promoting a replication slave having such events to a replication
master, you must enable each event using 'ALTER EVENT EVENT_NAME ENABLE',
where EVENT_NAME is the name of the event.

If more than one master was involved in creating events on this slave,
and you wish to identify events that were created only on a given master
having the server ID MASTER_ID, modify the previous query on the
'EVENTS' table to include the 'ORIGINATOR' column, as
shown here:

     SELECT EVENT_SCHEMA, EVENT_NAME, ORIGINATOR
         FROM INFORMATION_SCHEMA.EVENTS
         WHERE STATUS = 'SLAVESIDE_DISABLED'
         AND   ORIGINATOR = 'MASTER_ID'

You can employ 'ORIGINATOR' with the 'SHOW EVENTS'.
statement in a similar fashion:

     SHOW EVENTS
         WHERE STATUS = 'SLAVESIDE_DISABLED'
         AND   ORIGINATOR = 'MASTER_ID'

Before enabling events that were replicated from the master, you should
disable the MySQL Event Scheduler on the slave (using a statement such
as 'SET GLOBAL event_scheduler = OFF;'), run any necessary 'ALTER EVENT'
statements, restart the server, then re-enable the
Event Scheduler on the slave afterward (using a statement such as 'SET
GLOBAL event_scheduler = ON;')-

If you later demote the new master back to being a replication slave,
you must disable manually all events enabled by the 'ALTER EVENT'
statements.  You can do this by storing in a separate table
the event names from the 'SELECT' statement shown
previously, or using 'ALTER EVENT' statements to
rename the events with a common prefix such as 'replicated_' to identify
them.

If you rename the events, then when demoting this server back to being a
replication slave, you can identify the events by querying the
'EVENTS' table, as shown here:

     SELECT CONCAT(EVENT_SCHEMA, '.', EVENT_NAME) AS 'Db.Event'
           FROM INFORMATION_SCHEMA.EVENTS
           WHERE INSTR(EVENT_NAME, 'replicated_') = 1;

16.4.1.19 Replication and LIMIT
...............................

Statement-based replication of 'LIMIT' clauses in 'DELETE',
see 'UPDATE', and 'INSERT ... SELECT'
statements is unsafe since the order of the rows affected
is not defined.  (Such statements can be replicated correctly with
statement-based replication only if they also contain an 'ORDER BY'
clause.)  When such a statement is encountered:

   * When using 'STATEMENT' mode, a warning that the statement is not
     safe for statement-based replication is now issued.

     When using 'STATEMENT' mode, warnings are issued for DML statements
     containing 'LIMIT' even when they also have an 'ORDER BY' clause
     (and so are made deterministic).  This is a known issue.  (Bug
     #42851)

   * When using 'MIXED' mode, the statement is now automatically
     replicated using row-based mode.

16.4.1.20 Replication and LOAD DATA INFILE
..........................................

'LOAD DATA INFILE' is considered unsafe for
statement-based logging (see replication-rbr-safe-unsafe).  When
'binlog_format=MIXED' is set, the statement is logged in row-based
format.  When 'binlog_format=STATEMENT' is set, note that 'LOAD DATA INFILE'
does not generate a warning, unlike other
unsafe statements.

When 'mysqlbinlog' reads log events for 'LOAD DATA INFILE'
statements logged in statement-based format, a
generated local file is created in a temporary directory.  These
temporary files are not automatically removed by 'mysqlbinlog'
or any other MySQL program.  If you do use 'LOAD DATA INFILE'
statements with statement-based binary logging, you
should delete the temporary files yourself after you no longer need the
statement log.  For more information, see mysqlbinlog.

16.4.1.21 Replication and max_allowed_packet
............................................

'max_allowed_packet' sets an upper limit on the size of any single
message between the MySQL server and clients, including replication
slaves.  If you are replicating large column values (such as might be
found in 'TEXT' or 'BLOB' columns) and
'max_allowed_packet' is too small on the master, the master fails with
an error, and the slave shuts down the I/O thread.  If
'max_allowed_packet' is too small on the slave, this also causes the
slave to stop the I/O thread.

Row-based replication currently sends all columns and column values for
updated rows from the master to the slave, including values of columns
that were not actually changed by the update.  This means that, when you
are replicating large column values using row-based replication, you
must take care to set 'max_allowed_packet' large enough to accommodate
the largest row in any table to be replicated, even if you are
replicating updates only, or you are inserting only relatively small
values.

16.4.1.22 Replication and MEMORY Tables
.......................................

When a master server shuts down and restarts, its 'MEMORY'
tables become empty.  To replicate this effect to
slaves, the first time that the master uses a given 'MEMORY'
table after startup, it logs an event that
notifies slaves that the table must to be emptied by writing a
'DELETE' statement for that table to the binary log.

When a slave server shuts down and restarts, its 'MEMORY'
tables become empty.  This causes the slave to be
out of synchrony with the master and may lead to other failures or cause
the slave to stop:

   * Row-format updates and deletes received from the master may fail
     with 'Can't find record in 'MEMORY_TABLE''.

   * Statements such as 'INSERT INTO ... SELECT FROM MEMORY_TABLE'
     may insert a different set of rows on
     the master and slave.

The safe way to restart a slave that is replicating 'MEMORY'
tables is to first drop or delete all rows from
the 'MEMORY' tables on the master and wait
until those changes have replicated to the slave.  Then it is safe to
restart the slave.

An alternative restart method may apply in some cases.  When
'binlog_format=ROW', you can prevent the slave from stopping if you set
'slave_exec_mode=IDEMPOTENT' before you start the slave again.  This
allows the slave to continue to replicate, but its 'MEMORY'
tables will still be different from those on the
master.  This can be okay if the application logic is such that the
contents of 'MEMORY' tables can be safely
lost (for example, if the 'MEMORY' tables
are used for caching).  'slave_exec_mode=IDEMPOTENT' applies globally to
all tables, so it may hide other replication errors in non-see
'MEMORY' tables.

(The method just described is not applicable in NDB Cluster, where
'slave_exec_mode' is always 'IDEMPOTENT', and cannot be changed.)

The size of 'MEMORY' tables is limited by
the value of the 'max_heap_table_size' system variable, which is not
replicated (see replication-features-variables).  A change in
'max_heap_table_size' takes effect for 'MEMORY' tables that are created
or updated using 'ALTER TABLE ... ENGINE = MEMORY'.
or 'TRUNCATE TABLE' following the change, or for
all 'MEMORY' tables following a server
restart.  If you increase the value of this variable on the master
without doing so on the slave, it becomes possible for a table on the
master to grow larger than its counterpart on the slave, leading to
inserts that succeed on the master but fail on the slave with 'Table is
full' errors.  This is a known issue (Bug #48666).  In such cases, you
must set the global value of 'max_heap_table_size' on the slave as well
as on the master, then restart replication.  It is also recommended that
you restart both the master and slave MySQL servers, to insure that the
new value takes complete (global) effect on each of them.

See memory-storage-engine, for more information about
'MEMORY' tables.

16.4.1.23 Replication of the mysql System Database
..................................................

Data modification statements made to tables in the 'mysql' database are
replicated according to the value of 'binlog_format'; if this value is
'MIXED', these statements are replicated using row-based format.
However, statements that would normally update this information
indirectly--such 'GRANT', 'REVOKE', and
statements manipulating triggers, stored routines, and views--are
replicated to slaves using statement-based replication.

16.4.1.24 Replication and the Query Optimizer
.............................................

It is possible for the data on the master and slave to become different
if a statement is written in such a way that the data modification is
nondeterministic; that is, left up the query optimizer.  (In general,
this is not a good practice, even outside of replication.)  Examples of
nondeterministic statements include 'DELETE' or
'UPDATE' statements that use 'LIMIT' with no 'ORDER BY' clause;
see replication-features-limit, for a detailed discussion of
these.

16.4.1.25 Replication and Partitioning
......................................

Replication is supported between partitioned tables as long as they use
the same partitioning scheme and otherwise have the same structure
except where an exception is specifically allowed (see
replication-features-differing-tables).

Replication between tables having different partitioning is generally
not supported.  This because statements (such as 'ALTER TABLE ... DROP PARTITION')
acting directly on
partitions in such cases may produce different results on master and
slave.  In the case where a table is partitioned on the master but not
on the slave, any statements operating on partitions on the master's
copy of the slave fail on the slave.  When the slave's copy of the table
is partitioned but the master's copy is not, statements acting on
partitions cannot be run on the master without causing errors there.

Due to these dangers of causing replication to fail entirely (on account
of failed statements) and of inconsistencies (when the result of a
partition-level SQL statement produces different results on master and
slave), we recommend that insure that the partitioning of any tables to
be replicated from the master is matched by the slave's versions of
these tables.

16.4.1.26 Replication and REPAIR TABLE
......................................

When used on a corrupted or otherwise damaged table, it is possible for
the 'REPAIR TABLE' statement to delete rows that
cannot be recovered.  However, any such modifications of table data
performed by this statement are not replicated, which can cause master
and slave to lose synchronization.  For this reason, in the event that a
table on the master becomes damaged and you use 'REPAIR TABLE'
to repair it, you should first stop replication (if it is
still running) before using 'REPAIR TABLE', then
afterward compare the master's and slave's copies of the table and be
prepared to correct any discrepancies manually, before restarting
replication.

16.4.1.27 Replication and Reserved Words
........................................

You can encounter problems when you attempt to replicate from an older
master to a newer slave and you make use of identifiers on the master
that are reserved words in the newer MySQL version running on the slave.
An example of this is using a table column named 'virtual' on a 5.6
master that is replicating to a 5.7 or higher slave because 'VIRTUAL' is
a reserved word beginning in MySQL 5.7.  Replication can fail in such
cases with Error 1064 'You have an error in your SQL syntax...', _even
if a database or table named using the reserved word or a table having a
column named using the reserved word is excluded from replication_.
This is due to the fact that each SQL event must be parsed by the slave
prior to execution, so that the slave knows which database object or
objects would be affected; only after the event is parsed can the slave
apply any filtering rules defined by '--replicate-do-db',
'--replicate-do-table', '--replicate-ignore-db', and
'--replicate-ignore-table'.

To work around the problem of database, table, or column names on the
master which would be regarded as reserved words by the slave, do one of
the following:

   * Use one or more 'ALTER TABLE' statements on the
     master to change the names of any database objects where these
     names would be considered reserved words on the slave, and change
     any SQL statements that use the old names to use the new names
     instead.

   * In any SQL statements using these database object names, write the
     names as quoted identifiers using backtick characters ('`').

For listings of reserved words by MySQL version, see Reserved Words
(http://dev.mysql.com/doc/mysqld-version-reference/en/mysqld-version-reference-optvar.html),
in the 'MySQL Server Version Reference'.  For identifier quoting rules,
see identifiers.

16.4.1.28 Replication of Server-Side Help Tables
................................................

The server maintains tables in the 'mysql' database that store
information for the 'HELP' statement (see help.
These tables can be loaded manually as described at
server-side-help-support.

Help table content is derived from the MySQL Reference Manual.  There
are versions of the manual specific to each MySQL release series, so
help content is specific to each series as well.  Normally, you load a
version of help content that matches the server version.  This has
implications for replication.  For example, you would load MySQL 5.6
help content into a MySQL 5.6 master server, but not necessarily
replicate that content to a MySQL 5.7 slave server for which 5.7 help
content is more appropriate.

This section describes how to manage help table content upgrades when
your servers participate in replication.  Server versions are one factor
in this task.  Another is that the help table structure may differ
between the master and the slave.

Assume that help content is stored in a file named
'fill_help_tables.sql'.  In MySQL distributions, this file is located
under the 'share' or 'share/mysql' directory, and the most recent
version is always available for download from
<http://dev.mysql.com/doc/index-other.html>.

To upgrade help tables, using the following procedure.  Connection
parameters are not shown for the 'mysql' commands
discussed here; in all cases, connect to the server using an account
such as 'root' that has privileges for modifying tables in the 'mysql'
database.

  1. Upgrade your servers by running 'mysql_upgrade',
     first on the slaves and then on the master.  This is
     the usual principle of upgrading slaves first.

  2. Decide whether you want to replicate help table content from the
     master to its slaves.  If not, load the content on the master and
     each slave individually.  Otherwise, check for and resolve any
     incompatibilities between help table structure on the master and
     its slaves, then load the content into the master and let it
     replicate to the slaves.

     More detail about these two methods of loading help table content
     follows.

*Loading Help Table Content Without Replication to Slaves*

To load help table content without replication, run this command on the
master and each slave individually, using a 'fill_help_tables.sql' file
containing content appropriate to the server version (enter the command
on one line):

     mysql --init-command="SET sql_log_bin=0"
       mysql < fill_help_tables.sql

Use the '--init-command' option on each server, including the slaves, in
case a slave also acts as a master to other slaves in your replication
topology.  The 'SET' statement suppresses binary logging.  After the
command has been run on each server to be upgraded, you are done.

*Note*:

As of MySQL 5.7.5, the 'fill_help_tables.sql' file includes the 'SET'
statement to cause the file contents not to replicate.  Thus, for 5.7.5
and higher, the command is simpler:

     mysql mysql < fill_help_tables.sql

*Loading Help Table Content With Replication to Slaves*

*Note*:

As mentioned previously, 'fill_help_tables.sql' in MySQL 5.7.5 and later
includes a 'SET' statement to suppress binary logging of the file
contents.  If you want to replicate help table contents for MySQL 5.7.5
or later, you must edit 'fill_help_tables.sql' to remove the 'SET'
statement.  This should rarely be desireable because help table contents
are specific to the version of the server into which they are loaded,
which may differ for master and slave.

If you do want to replicate help table content, check for help table
incompatibilities between your master and its slaves.  The 'url' column
in the 'help_category' and 'help_topic' tables was originally
'CHAR(128)', but is 'TEXT' in newer MySQL versions to accommodate longer
URLs.  To check help table structure, use this statement:

     SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE
     FROM INFORMATION_SCHEMA.COLUMNS
     WHERE TABLE_SCHEMA = 'mysql'
     AND COLUMN_NAME = 'url';

For tables with the old structure, the statement produces this result:

     +---------------+-------------+-------------+
     | TABLE_NAME    | COLUMN_NAME | COLUMN_TYPE |
     +---------------+-------------+-------------+
     | help_category | url         | char(128)   |
     | help_topic    | url         | char(128)   |
     +---------------+-------------+-------------+

For tables with the new structure, the statement produces this result:

     +---------------+-------------+-------------+
     | TABLE_NAME    | COLUMN_NAME | COLUMN_TYPE |
     +---------------+-------------+-------------+
     | help_category | url         | text        |
     | help_topic    | url         | text        |
     +---------------+-------------+-------------+

If the master and slave both have the old structure or both have the new
structure, they are compatible and you can replicate help table content
by executing this command on the master:

     mysql mysql < fill_help_tables.sql

The table content will load into the master, then replicate to the
slaves.

If the master and slave have incompatible help tables (one server has
the old structure and the other has the new), you have a choice between
not replicating help table content after all, or making the table
structures compatible so that you can replicate the content.

   * If you decide not to replicate the content after all, upgrade the
     master and slaves individually using 'mysql' with the
     '--init-command' option, as described previously.

   * If instead you decide to make the table structures compatible,
     upgrade the tables on the server that has the old structure.
     Suppose that your master server has the old table structure.
     Upgrade its tables to the new structure manually by executing these
     statements (binary logging is disabled here to prevent replication
     of the changes to the slaves, which already have the new
     structure):

          SET sql_log_bin=0;
          ALTER TABLE mysql.help_category ALTER COLUMN url TEXT;
          ALTER TABLE mysql.help_topic ALTER COLUMN url TEXT;

     Then run this command on the master:

          mysql mysql < fill_help_tables.sql

     The table content will load into the master, then replicate to the
     slaves.

16.4.1.29 Replication and Master or Slave Shutdowns
...................................................

It is safe to shut down a master server and restart it later.  When a
slave loses its connection to the master, the slave tries to reconnect
immediately and retries periodically if that fails.  The default is to
retry every 60 seconds.  This may be changed with the 'CHANGE MASTER TO'
statement.  A slave also is able to deal
with network connectivity outages.  However, the slave notices the
network outage only after receiving no data from the master for
'slave_net_timeout' seconds.  If your outages are short, you may want to
decrease 'slave_net_timeout'.  See
replication-solutions-unexpected-slave-halt.

An unclean shutdown (for example, a crash) on the master side can result
in the master binary log having a final position less than the most
recent position read by the slave, due to the master binary log file not
being flushed.  This can cause the slave not to be able to replicate
when the master comes back up.  Setting 'sync_binlog=1' in the master
'my.cnf' file helps to minimize this problem because it causes the
master to flush its binary log more frequently.

Shutting down a slave cleanly is safe because it keeps track of where it
left off.  However, be careful that the slave does not have temporary
tables open; see replication-features-temptables.  Unclean
shutdowns might produce problems, especially if the disk cache was not
flushed to disk before the problem occurred:

   * For transactions, the slave commits and then updates
     'relay-log.info'.  If a crash occurs between these two operations,
     relay log processing will have proceeded further than the
     information file indicates and the slave will re-execute the events
     from the last transaction in the relay log after it has been
     restarted.

   * A similar problem can occur if the slave updates 'relay-log.info'
     but the server host crashes before the write has been flushed to
     disk.  To minimize the chance of this occurring, set
     'sync_relay_log_info=1' in the slave 'my.cnf' file.  Setting
     'sync_relay_log_info' to 0 causes no writes to be forced to disk
     and the server relies on the operating system to flush the file
     from time to time.

The fault tolerance of your system for these types of problems is
greatly increased if you have a good uninterruptible power supply.

16.4.1.30 Slave Errors During Replication
.........................................

If a statement produces the same error (identical error code) on both
the master and the slave, the error is logged, but replication
continues.

If a statement produces different errors on the master and the slave,
the slave SQL thread terminates, and the slave writes a message to its
error log and waits for the database administrator to decide what to do
about the error.  This includes the case that a statement produces an
error on the master or the slave, but not both.  To address the issue,
connect to the slave manually and determine the cause of the problem.
'SHOW SLAVE STATUS' is useful for this.  Then
fix the problem and run 'START SLAVE'.  For example,
you might need to create a nonexistent table before you can start the
slave again.

*Note*:

If a temporary error is recorded in the slave's error log, you do not
necessarily have to take any action suggested in the quoted error
message.  Temporary errors should be handled by the client retrying the
transaction.  For example, if the slave SQL thread records a temporary
error relating to a deadlock, you do not need to restart the transaction
manually on the slave, unless the slave SQL thread subsequently
terminates with a nontemporary error message.

If this error code validation behavior is not desirable, some or all
errors can be masked out (ignored) with the '--slave-skip-errors'
option.

For nontransactional storage engines such as 'MyISAM', it is possible to
have a statement that only partially updates a table and returns an
error code.  This can happen, for example, on a multiple-row insert that
has one row violating a key constraint, or if a long update statement is
killed after updating some of the rows.  If that happens on the master,
the slave expects execution of the statement to result in the same error
code.  If it does not, the slave SQL thread stops as described
previously.

If you are replicating between tables that use different storage engines
on the master and slave, keep in mind that the same statement might
produce a different error when run against one version of the table, but
not the other, or might cause an error for one version of the table, but
not the other.  For example, since 'MyISAM' ignores foreign key
constraints, an 'INSERT' or 'UPDATE'.
statement accessing an 'InnoDB' table on the master might cause a
foreign key violation but the same statement performed on a 'MyISAM'
version of the same table on the slave would produce no such error,
causing replication to stop.

16.4.1.31 Replication and Server SQL Mode
.........................................

Using different server SQL mode settings on the master and the slave may
cause the same 'INSERT' statements to be handled
differently on the master and the slave, leading the master and slave to
diverge.  For best results, you should always use the same server SQL
mode on the master and on the slave.  This advice applies whether you
are using statement-based or row-based replication.

If you are replicating partitioned tables, using different SQL modes on
the master and the slave is likely to cause issues.  At a minimum, this
is likely to cause the distribution of data among partitions to be
different in the master's and slave's copies of a given table.  It may
also cause inserts into partitioned tables that succeed on the master to
fail on the slave.

For more information, see sql-mode.  In particular, see
sql-mode-changes, which describes changes in MySQL 5.7, so that you
can assess whether your applications will be affected.

16.4.1.32 Replication and Temporary Tables
..........................................

The discussion in the following paragraphs does not apply when
'binlog_format=ROW' because, in that case, temporary tables are not
replicated; this means that there are never any temporary tables on the
slave to be lost in the event of an unplanned shutdown by the slave.
The remainder of this section applies only when using statement-based or
mixed-format replication.  Loss of replicated temporary tables on the
slave can be an issue, whenever 'binlog_format' is 'STATEMENT' or
'MIXED', for statements involving temporary tables that can be logged
safely using statement-based format.  For more information about
row-based replication and temporary tables, see
replication-rbr-usage-temptables.

Safe slave shutdown when using temporary tables

Temporary tables are replicated except in the case where you stop the
slave server (not just the slave threads) and you have replicated
temporary tables that are open for use in updates that have not yet been
executed on the slave.  If you stop the slave server, the temporary
tables needed by those updates are no longer available when the slave is
restarted.  To avoid this problem, do not shut down the slave while it
has temporary tables open.  Instead, use the following procedure:

  1. Issue a 'STOP SLAVE SQL_THREAD' statement.

  2. Use 'SHOW STATUS' to check the value of the
     'Slave_open_temp_tables' variable.

  3. If the value is not 0, restart the slave SQL thread with 'START
     SLAVE SQL_THREAD' and repeat the procedure later.

  4. When the value is 0, issue a 'mysqladmin shutdown'
     command to stop the slave.

Temporary tables and replication options

By default, all temporary tables are replicated; this happens whether or
not there are any matching '--replicate-do-db', '--replicate-do-table',
or '--replicate-wild-do-table' options in effect.  However, the
'--replicate-ignore-table' and '--replicate-wild-ignore-table' options
are honored for temporary tables.  The exception is that to enable
correct removal of temporary tables at the end of a session, a
replication slave always replicates a 'DROP TEMPORARY TABLE IF EXISTS'
statement, regardless of any exclusion rules that would normally apply
for the specified table.

A recommended practice when using statement-based or mixed-format
replication is to designate a prefix for exclusive use in naming
temporary tables that you do not want replicated, then employ a
'--replicate-wild-ignore-table' option to match that prefix.  For
example, you might give all such tables names beginning with 'norep'
(such as 'norepmytable', 'norepyourtable', and so on), then use
'--replicate-wild-ignore-table=norep%' to prevent them from being
replicated.

16.4.1.33 Replication Retries and Timeouts
..........................................

The global system variable 'slave_transaction_retries' affects
replication as follows: If the slave SQL thread fails to execute a
transaction because of an 'InnoDB' deadlock or because it exceeded the
'InnoDB' 'innodb_lock_wait_timeout' value, or the 'NDB'.
'TransactionDeadlockDetectionTimeout' or
'TransactionInactiveTimeout' value, the slave automatically retries the
transaction 'slave_transaction_retries' times before stopping with an
error.  The default value is 10.  The total retry count can be seen in
the output of 'SHOW STATUS'.; see
server-status-variables.

16.4.1.34 Replication and Time Zones
....................................

By default, master and slave servers assume that they are in the same
time zone.  If you are replicating between servers in different time
zones, the time zone must be set on both master and slave.  Otherwise,
statements depending on the local time on the master are not replicated
properly, such as statements that use the 'NOW()' or 'FROM_UNIXTIME()'
functions.  Set the time zone in which MySQL server runs by using the
'--timezone=TIMEZONE_NAME' option of the 'mysqld_safe' script or by
setting the 'TZ' environment variable.  See also
replication-features-functions.

16.4.1.35 Replication and Transaction Inconsistencies
.....................................................

Inconsistencies in the sequence of transactions that have been executed
from the relay log can occur depending on your replication
configuration.  This section explains how to avoid inconsistencies and
solve any problems they cause.

The following types of inconsistencies can exist:

   * _Half-applied transactions_.  A transaction which updates
     non-transactional tables has applied some but not all of its
     changes.

   * _Gaps_.  A gap is a transaction that has not been (fully) applied,
     even though some later transaction has been applied.  Gaps can only
     appear when using a multi-threaded slave.  To avoid gaps occurring,
     set 'slave_preserve_commit_order=1', which requires
     'slave_parallel_type=LOGICAL_CLOCK', and that 'log-bin' and
     'log-slave-updates' are also enabled.

   * _Gap-free low-watermark position_.  Even in the absence of gaps, it
     is possible that transactions after 'Exec_master_log_pos' have been
     applied.  That is, all transactions up to point 'N' have been
     applied, and no transactions after 'N' have been applied, but
     'Exec_master_log_pos' has a value smaller than 'N.' This can only
     happen on multi-threaded slaves.  Enabling
     'slave_preserve_commit_order' does _not_ prevent gap-free
     low-watermark positions.

The following scenarios are relevant to the existence of half-applied
transactions, gaps, and gap-free low-watermark position inconsistencies:

  1. While slave threads are running, there may be gaps and half-applied
     transactions.

  2. 'mysqld' shuts down.  Both clean and unclean
     shutdown abort ongoing transactions and may leave gaps and
     half-applied transactions.

  3. 'KILL' of replication threads (the SQL thread when
     using a single-threaded slave, the coordinator thread when using a
     multi-threaded slave).  This aborts ongoing transactions and may
     leave gaps and half-applied transactions.

  4. Error in applier threads.  This may leave gaps.  If the error is in
     a mixed transaction, that transaction is half-applied.  When using
     a multi-threaded slave, workers which have not received an error
     complete their queues, so it may take time to stop all threads.

  5. 'STOP SLAVE' when using a multi-threaded slave.
     After issuing 'STOP SLAVE', the slave waits for
     any gaps to be filled and then updates 'Exec_master_log_pos'.  This
     ensures it never leaves gaps or gap-free low-watermark positions,
     unless any of the cases above applies (in other words, before
     'STOP SLAVE' completes, either an error happens, or
     another thread issues 'KILL', or the server restarts.
     In these cases, see 'STOP SLAVE' returns
     successfully.)

  6. If the last transaction in the relay log is only half-received and
     the multi-threaded slave coordinator has started to schedule the
     transaction to a worker, then 'STOP SLAVE' waits
     up to 60 seconds for the transaction to be received.  After this
     timeout, the coordinator gives up and aborts the transaction.  If
     the transaction is mixed, it may be left half-completed.

  7. 'STOP SLAVE' when using a single-threaded slave.
     If the ongoing transaction only updates transactional tables, it is
     rolled back and 'STOP SLAVE' stops immediately.
     If the ongoing transaction is mixed, see 'STOP SLAVE'
     waits up to 60 seconds for the transaction to complete.
     After this timeout, it aborts the transaction, so it may be left
     half-completed.

The global variable 'rpl_stop_slave_timeout' is unrelated to the process
of stopping the replication threads.  It only makes the client that
issues 'STOP SLAVE' return to the client, but the
replication threads continue to try to stop.

If a replication channel has gaps, it has the following consequences:

  1. The slave database is in a state that may never have existed on the
     master.

  2. The field 'Exec_master_log_pos' in 'SHOW SLAVE STATUS'
     is only a "low-watermark".  In other words,
     transactions appearing before the position are guaranteed to have
     committed, but transactions after the position may have committed
     or not.

  3. 'CHANGE MASTER TO' statements for that
     channel fail with an error, unless the applier threads are running
     and the 'CHANGE MASTER TO' statement only
     sets receiver options.

  4. If 'mysqld' is started with '--relay-log-recovery',
     no recovery is done for that channel, and a warning is printed.

  5. If 'mysqldump' is used with '--dump-slave', it
     does not record the existence of gaps; thus it prints 'CHANGE MASTER TO'
     with 'RELAY_LOG_POS' set to the
     low-watermark position in 'Exec_master_log_pos'.

     After applying the dump on another server, and starting the
     replication threads, transactions appearing after the position are
     replicated again.  Note that this is harmless if GTIDs are enabled
     (however, in that case it is not recommended to use
     '--dump-slave').

If a replication channel has a gap-free low-watermark position, cases 2
to 5 above apply, but case 1 does not.

The gap-free low-watermark position information is persisted in binary
format in the internal table 'mysql.slave_worker_info'.  'START SLAVE [SQL_THREAD]'
always consults this information so
that it applies only the correct transactions.  This remains true even
if 'slave_parallel_workers' has been changed to 0 before 'START SLAVE',
and even if 'START SLAVE' is
used with 'UNTIL' clauses.  'START SLAVE UNTIL SQL_AFTER_MTS_GAPS'
only applies as many transactions as
needed in order to fill in the gaps.  If 'START SLAVE'
is used with 'UNTIL' clauses that tell it to stop before it
has consumed all the gaps, then it leaves remaining gaps.

*Warning*:

'RESET SLAVE' removes the relay logs and resets the
replication position.  Thus issuing 'RESET SLAVE' on
a slave with gaps means the slave loses any information about the gaps,
without correcting the gaps.

'slave-preserve-commit-order' ensures that there are no gaps.  However,
it is still possible that 'Exec_master_log_pos' is just a gap-free
low-watermark position in scenarios 1 to 4 above.  That is, there may be
transactions after 'Exec_master_log_pos' which have been applied.
Therefore the cases numbered 2 to 5 above (but not case 1) apply, even
when 'slave-preserve-commit-order' is enabled.

16.4.1.36 Replication and Transactions
......................................

Mixing transactional and nontransactional statements within the same
transaction

In general, you should avoid transactions that update both transactional
and nontransactional tables in a replication environment.  You should
also avoid using any statement that accesses both transactional (or
temporary) and nontransactional tables and writes to any of them.

The server uses these rules for binary logging:

   * If the initial statements in a transaction are nontransactional,
     they are written to the binary log immediately.  The remaining
     statements in the transaction are cached and not written to the
     binary log until the transaction is committed.  (If the transaction
     is rolled back, the cached statements are written to the binary log
     only if they make nontransactional changes that cannot be rolled
     back.  Otherwise, they are discarded.)

   * For statement-based logging, logging of nontransactional statements
     is affected by the 'binlog_direct_non_transactional_updates' system
     variable.  When this variable is 'OFF' (the default), logging is as
     just described.  When this variable is 'ON', logging occurs
     immediately for nontransactional statements occurring anywhere in
     the transaction (not just initial nontransactional statements).
     Other statements are kept in the transaction cache and logged when
     the transaction commits.  'binlog_direct_non_transactional_updates'
     has no effect for row-format or mixed-format binary logging.

Transactional, nontransactional, and mixed statements

To apply those rules, the server considers a statement nontransactional
if it changes only nontransactional tables, and transactional if it
changes only transactional tables.  A statement that references both
nontransactional and transactional tables and updates _any_ of the
tables involved, is considered a 'mixed' statement.  (In some past MySQL
versions, only a statement that updated _both_ nontransactional and
transactional tables was considered mixed.)  Mixed statements, like
transactional statements, are cached and logged when the transaction
commits.

A mixed statement that updates a transactional table is considered
unsafe if the statement also performs either of the following actions:

   * Updates or reads a temporary table

   * Reads a nontransactional table and the transaction isolation level
     is less than REPEATABLE_READ

A mixed statement following the update of a transactional table within a
transaction is considered unsafe if it performs either of the following
actions:

   * Updates any table and reads from any temporary table

   * Updates a nontransactional table and
     'binlog_direct_non_transactional_updates' is OFF

For more information, see replication-rbr-safe-unsafe.

*Note*:

A mixed statement is unrelated to mixed binary logging format.

In situations where transactions mix updates to transactional and
nontransactional tables, the order of statements in the binary log is
correct, and all needed statements are written to the binary log even in
case of a 'ROLLBACK'.  However, when a second connection
updates the nontransactional table before the first connection
transaction is complete, statements can be logged out of order because
the second connection update is written immediately after it is
performed, regardless of the state of the transaction being performed by
the first connection.

Using different storage engines on master and slave

It is possible to replicate transactional tables on the master using
nontransactional tables on the slave.  For example, you can replicate an
'InnoDB' master table as a 'MyISAM' slave table.  However, if you do
this, there are problems if the slave is stopped in the middle of a
'BEGIN'. ...  'COMMIT' block because the
slave restarts at the beginning of the 'BEGIN' block.

It is also safe to replicate transactions from 'MyISAM'
tables on the master to transactional
tables--such as tables that use the 'InnoDB'
storage engine--on the slave.  In such cases, an
'AUTOCOMMIT=1' statement issued on the master is replicated, thus
enforcing 'AUTOCOMMIT' mode on the slave.

When the storage engine type of the slave is nontransactional,
transactions on the master that mix updates of transactional and
nontransactional tables should be avoided because they can cause
inconsistency of the data between the master transactional table and the
slave nontransactional table.  That is, such transactions can lead to
master storage engine-specific behavior with the possible effect of
replication going out of synchrony.  MySQL does not issue a warning
about this currently, so extra care should be taken when replicating
transactional tables from the master to nontransactional tables on the
slaves.

Changing the binary logging format within transactions

The 'binlog_format' and 'binlog_checksum' system variables are read-only
as long as a transaction is in progress.

Every transaction (including 'autocommit' transactions) is recorded in
the binary log as though it starts with a 'BEGIN'.
statement, and ends with either a 'COMMIT' or a
'ROLLBACK' statement.  This is even true for statements
affecting tables that use a nontransactional storage engine (such as
'MyISAM').

*Note*:

For restrictions that apply specifically to XA transactions, see
xa-restrictions.

16.4.1.37 Replication and Triggers
..................................

With statement-based replication, triggers executed on the master also
execute on the slave.  With row-based replication, triggers executed on
the master do not execute on the slave.  Instead, the row changes on the
master resulting from trigger execution are replicated and applied on
the slave.

This behavior is by design.  If under row-based replication the slave
applied the triggers as well as the row changes caused by them, the
changes would in effect be applied twice on the slave, leading to
different data on the master and the slave.

If you want triggers to execute on both the master and the
slave--perhaps because you have different triggers on the master and
slave--you must use statement-based replication.  However, to enable
slave-side triggers, it is not necessary to use statement-based
replication exclusively.  It is sufficient to switch to statement-based
replication only for those statements where you want this effect, and to
use row-based replication the rest of the time.

A statement invoking a trigger (or function) that causes an update to an
'AUTO_INCREMENT' column is not replicated correctly using
statement-based replication.  MySQL 5.7 marks such statements as unsafe.
(Bug #45677)

A trigger can have triggers for different combinations of trigger event
(see 'INSERT', 'UPDATE', 'DELETE')
and action time ('BEFORE', 'AFTER'), but before MySQL 5.7.2
cannot have multiple triggers that have the same trigger event and
action time.  MySQL 5.7.2 lifts this limitation and multiple triggers
are permitted.  This change has replication implications for upgrades
and downgrades.

For brevity, 'multiple triggers' here is shorthand for 'multiple
triggers that have the same trigger event and action time.'

*Upgrades.*  Suppose that you upgrade an old server that does not
support multiple triggers to MySQL 5.7.2 or higher.  If the new server
is a replication master and has old slaves that do not support multiple
triggers, an error occurs on those slaves if a trigger is created on the
master for a table that already has a trigger with the same trigger
event and action time.  To avoid this problem, upgrade the slaves first,
then upgrade the master.

*Downgrades.*  If you downgrade a server that supports multiple triggers
to an older version that does not, the downgrade has these effects:

   * For each table that has triggers, all trigger definitions remain in
     the '.TRG' file for the table.  However, if there are multiple
     triggers with the same trigger event and action time, the server
     executes only one of them when the trigger event occurs.  For
     information about '.TRG' files, see Table Trigger Storage
     (http://dev.mysql.com/doc/dev/mysql-server/latest//stored_programs.html#sp_storage_trigger).

   * If triggers for the table are added or dropped subsequent to the
     downgrade, the server rewrites the table's '.TRG' file.  The
     rewritten file retains only one trigger per combination of trigger
     event and action time; the others are lost.

To avoid these problems, modify your triggers before downgrading.  For
each table that has multiple triggers per combination of trigger event
and action time, convert each such set of triggers to a single trigger
as follows:

  1. For each trigger, create a stored routine that contains all the
     code in the trigger.  Values accessed using 'NEW' and 'OLD' can be
     passed to the routine using parameters.  If the trigger needs a
     single result value from the code, you can put the code in a stored
     function and have the function return the value.  If the trigger
     needs multiple result values from the code, you can put the code in
     a stored procedure and return the values using 'OUT' parameters.

  2. Drop all triggers for the table.

  3. Create one new trigger for the table that invokes the stored
     routines just created.  The effect for this trigger is thus the
     same as the multiple triggers it replaces.

16.4.1.38 Replication and TRUNCATE TABLE
........................................

'TRUNCATE TABLE' is normally regarded as a DML
statement, and so would be expected to be logged and replicated using
row-based format when the binary logging mode is 'ROW' or 'MIXED'.
However this caused issues when logging or replicating, in 'STATEMENT'
or 'MIXED' mode, tables that used transactional storage engines such as
'InnoDB' when the transaction isolation
level was 'READ COMMITTED' or 'READ UNCOMMITTED', which precludes
statement-based logging.

'TRUNCATE TABLE' is treated for purposes of
logging and replication as DDL rather than DML so that it can be logged
and replicated as a statement.  However, the effects of the statement as
applicable to 'InnoDB' and other
transactional tables on replication slaves still follow the rules
described in truncate-table governing such tables.  (Bug #36763)

16.4.1.39 Replication and User Name Length
..........................................

The maximum length of MySQL user names was increased from 16 characters
to 32 characters in MySQL 5.7.8.  Replication of user names longer than
16 characters to a slave that supports only shorter user names will
fail.  However, this should occur only when replicating from a newer
master to an older slave, which is not a recommended configuration.

16.4.1.40 Replication and Variables
...................................

System variables are not replicated correctly when using 'STATEMENT'
mode, except for the following variables when they are used with session
scope:

   * 'auto_increment_increment'

   * 'auto_increment_offset'

   * 'character_set_client'

   * 'character_set_connection'

   * 'character_set_database'

   * 'character_set_server'

   * 'collation_connection'

   * 'collation_database'

   * 'collation_server'

   * 'foreign_key_checks'

   * 'identity'

   * 'last_insert_id'

   * 'lc_time_names'

   * 'pseudo_thread_id'

   * 'sql_auto_is_null'

   * 'time_zone'

   * 'timestamp'

   * 'unique_checks'

When 'MIXED' mode is used, the variables in the preceding list, when
used with session scope, cause a switch from statement-based to
row-based logging.  See binary-log-mixed.

'sql_mode' is also replicated except for the 'NO_DIR_IN_CREATE' mode;
the slave always preserves its own value for 'NO_DIR_IN_CREATE',
regardless of changes to it on the master.  This is true for all
replication formats.

However, when 'mysqlbinlog' parses a 'SET @@sql_mode
= MODE' statement, the full MODE value, including 'NO_DIR_IN_CREATE', is
passed to the receiving server.  For this reason, replication of such a
statement may not be safe when 'STATEMENT' mode is in use.

The 'default_storage_engine' and 'storage_engine' system variables are
not replicated, regardless of the logging mode; this is intended to
facilitate replication between different storage engines.

The 'read_only' system variable is not replicated.  In addition, the
enabling this variable has different effects with regard to temporary
tables, table locking, and the 'SET PASSWORD'.
statement in different MySQL versions.

The 'max_heap_table_size' system variable is not replicated.  Increasing
the value of this variable on the master without doing so on the slave
can lead eventually to 'Table is full' errors on the slave when trying
to execute 'INSERT' statements on a 'MEMORY'
table on the master that is thus permitted to
grow larger than its counterpart on the slave.  For more information,
see replication-features-memory.

In statement-based replication, session variables are not replicated
properly when used in statements that update tables.  For example, the
following sequence of statements will not insert the same data on the
master and the slave:

     SET max_join_size=1000;
     INSERT INTO mytable VALUES(@@max_join_size);

This does not apply to the common sequence:

     SET time_zone=...;
     INSERT INTO mytable VALUES(CONVERT_TZ(..., ..., @@time_zone));

Replication of session variables is not a problem when row-based
replication is being used, in which case, session variables are always
replicated safely.  See replication-formats.

The following session variables are written to the binary log and
honored by the replication slave when parsing the binary log, regardless
of the logging format:

   * 'sql_mode'

   * 'foreign_key_checks'

   * 'unique_checks'

   * 'character_set_client'

   * 'collation_connection'

   * 'collation_database'

   * 'collation_server'

   * 'sql_auto_is_null'

*Important*:

Even though session variables relating to character sets and collations
are written to the binary log, replication between different character
sets is not supported.

To help reduce possible confusion, we recommend that you always use the
same setting for the 'lower_case_table_names' system variable on both
master and slave, especially when you are running MySQL on platforms
with case-sensitive file systems.

16.4.1.41 Replication and Views
...............................

Views are always replicated to slaves.  Views are filtered by their own
name, not by the tables they refer to.  This means that a view can be
replicated to the slave even if the view contains a table that would
normally be filtered out by 'replication-ignore-table' rules.  Care
should therefore be taken to ensure that views do not replicate table
data that would normally be filtered for security reasons.

Replication from a table to a same-named view is supported using
statement-based logging, but not when using row-based logging.  Trying
to do so when row-based logging is in effect causes an error.  (Bug
#11752707, Bug #43975)

16.4.2 Replication Compatibility Between MySQL Versions
-------------------------------------------------------

MySQL supports replication from one release series to the next higher
release series.  For example, you can replicate from a master running
MySQL 5.5 to a slave running MySQL 5.6, from a master running MySQL 5.6
to a slave running MySQL 5.7, and so on.

However, you may encounter difficulties when replicating from an older
master to a newer slave if the master uses statements or relies on
behavior no longer supported in the version of MySQL used on the slave.
For example, in MySQL 5.5, see 'CREATE TABLE ... SELECT'
statements were permitted to change tables other
than the one being created, but were no longer allowed to do so in MySQL
5.6 (see replication-features-create-select).

The use of more than two MySQL Server versions is not supported in
replication setups involving multiple masters, regardless of the number
of master or slave MySQL servers.  This restriction applies not only to
release series, but to version numbers within the same release series as
well.  For example, if you are using a chained or circular replication
setup, you cannot use MySQL 5.7.1, MySQL 5.7.2, and MySQL 5.7.4
concurrently, although you could use any two of these releases together.

*Important*:

It is strongly recommended to use the most recent release available
within a given MySQL release series because replication (and other)
capabilities are continually being improved.  It is also recommended to
upgrade masters and slaves that use early releases of a release series
of MySQL to GA (production) releases when the latter become available
for that release series.

Replication from newer masters to older slaves may be possible, but is
generally not supported.  This is due to a number of factors:

   * Binary log format changes

     The binary log format can change between major releases.  While we
     attempt to maintain backward compatibility, this is not always
     possible.

     This also has significant implications for upgrading replication
     servers; see replication-upgrade, for more information.

   * For more information about row-based replication, see
     replication-formats.

   * SQL incompatibilities

     You cannot replicate from a newer master to an older slave using
     statement-based replication if the statements to be replicated use
     SQL features available on the master but not on the slave.

     However, if both the master and the slave support row-based
     replication, and there are no data definition statements to be
     replicated that depend on SQL features found on the master but not
     on the slave, you can use row-based replication to replicate the
     effects of data modification statements even if the DDL run on the
     master is not supported on the slave.

For more information on potential replication issues, see
replication-features.

16.4.3 Upgrading a Replication Setup
------------------------------------

When you upgrade servers that participate in a replication setup, the
procedure for upgrading depends on the current server versions and the
version to which you are upgrading.  This section provides information
about how upgrading affects replication.  For general information about
upgrading MySQL, see upgrading

When you upgrade a master to 5.7 from an earlier MySQL release series,
you should first ensure that all the slaves of this master are using the
same 5.7.x release.  If this is not the case, you should first upgrade
the slaves.  To upgrade each slave, shut it down, upgrade it to the
appropriate 5.7.x version, restart it, and restart replication.  Relay
logs created by the slave after the upgrade are in 5.7 format.

Changes affecting operations in strict SQL mode ('STRICT_TRANS_TABLES'
or 'STRICT_ALL_TABLES') may result in replication failure on an updated
slave.  For example, as of MySQL 5.7.2, the server restricts insertion
of a 'DEFAULT' value of 0 for temporal data types in strict mode.  If
you use statement-based logging ('binlog_format=STATEMENT'), if a slave
is upgraded before the master, the nonupgraded master will execute
statements without error that may fail on the slave and replication will
stop.  To deal with this, stop all new statements on the master and wait
until the slaves catch up.  Then upgrade the slaves.  Alternatively, if
you cannot stop new statements, temporarily change to row-based logging
on the master ('binlog_format=ROW') and wait until all slaves have
processed all binary logs produced up to the point of this change.  Then
upgrade the slaves.

After the slaves have been upgraded, shut down the master, upgrade it to
the same 5.7.x release as the slaves, and restart it.  If you had
temporarily changed the master to row-based logging, change it back to
statement-based logging.  The 5.7 master is able to read the old binary
logs written prior to the upgrade and to send them to the 5.7 slaves.
The slaves recognize the old format and handle it properly.  Binary logs
created by the master subsequent to the upgrade are in 5.7 format.
These too are recognized by the 5.7 slaves.

In other words, when upgrading to MySQL 5.7, the slaves must be MySQL
5.7 before you can upgrade the master to 5.7.  Note that downgrading
from 5.7 to older versions does not work so simply: You must ensure that
any 5.7 binary log or relay log has been fully processed, so that you
can remove it before proceeding with the downgrade.

Some upgrades may require that you drop and re-create database objects
when you move from one MySQL series to the next.  For example, collation
changes might require that table indexes be rebuilt.  Such operations,
if necessary, are detailed at upgrading-from-previous-series.
It is safest to perform these operations separately on the slaves and
the master, and to disable replication of these operations from the
master to the slave.  To achieve this, use the following procedure:

  1. Stop all the slaves and upgrade them.  Restart them with the
     '--skip-slave-start' option so that they do not connect to the
     master.  Perform any table repair or rebuilding operations needed
     to re-create database objects, such as use of 'REPAIR TABLE' or
     'ALTER TABLE', or dumping and reloading tables or triggers.

  2. Disable the binary log on the master.  To do this without
     restarting the master, execute a 'SET sql_log_bin = 0' statement.
     Alternatively, stop the master and restart it without the
     '--log-bin' option.  If you restart the master, you might also want
     to disallow client connections.  For example, if all clients
     connect using TCP/IP, use the '--skip-networking' option when you
     restart the master.

  3. With the binary log disabled, perform any table repair or
     rebuilding operations needed to re-create database objects.  The
     binary log must be disabled during this step to prevent these
     operations from being logged and sent to the slaves later.

  4. Re-enable the binary log on the master.  If you set 'sql_log_bin'
     to 0 earlier, execute a 'SET sql_log_bin = 1' statement.  If you
     restarted the master to disable the binary log, restart it with
     '--log-bin', and without '--skip-networking' so that clients and
     slaves can connect.

  5. Restart the slaves, this time without the '--skip-slave-start'
     option.

If you are upgrading an existing replication setup from a version of
MySQL that does not support global transaction identifiers to a version
that does, you should not enable GTIDs on either the master or the slave
before making sure that the setup meets all the requirements for
GTID-based replication.  For example 'server_uuid', which was added in
MySQL 5.6, must exist for GTIDs to function correctly.  See
replication-gtids-howto, which contains information about converting
existing replication setups to use GTID-based replication.

When the server is running with global transaction identifiers (GTIDs)
enabled ('gtid_mode=ON'), do not enable binary logging by
'mysql_upgrade'.

It is not recommended to load a dump file when GTIDs are enabled on the
server ('gtid_mode=ON'), if your dump file includes system tables.
'mysqldump' issues DML instructions for the system
tables which use the non-transactional MyISAM storage engine, and this
combination is not permitted when GTIDs are enabled.  Also be aware that
loading a dump file from a server with GTIDs enabled, into another
server with GTIDs enabled, causes different transaction identifiers to
be generated.

16.4.4 Troubleshooting Replication
----------------------------------

If you have followed the instructions but your replication setup is not
working, the first thing to do is _check the error log for messages_.
Many users have lost time by not doing this soon enough after
encountering problems.

If you cannot tell from the error log what the problem was, try the
following techniques:

   * Verify that the master has binary logging enabled by issuing a
     'SHOW MASTER STATUS' statement.  If
     logging is enabled, 'Position' is nonzero.  If binary logging is
     not enabled, verify that you are running the master with the
     '--log-bin' option.

   * Verify that the master and slave both were started with the
     '--server-id' option and that the ID value is unique on each
     server.

   * Verify that the slave is running.  Use 'SHOW SLAVE STATUS'
     to check whether the 'Slave_IO_Running' and
     'Slave_SQL_Running' values are both 'Yes'.  If not, verify the
     options that were used when starting the slave server.  For
     example, '--skip-slave-start' prevents the slave threads from
     starting until you issue a 'START SLAVE'.
     statement.

   * If the slave is running, check whether it established a connection
     to the master.  Use 'SHOW PROCESSLIST',
     find the I/O and SQL threads and check their 'State' column to see
     what they display.  See replication-implementation-details.
     If the I/O thread state says 'Connecting to master', check the
     following:

        * Verify the privileges for the user being used for replication
          on the master.

        * Check that the host name of the master is correct and that you
          are using the correct port to connect to the master.  The port
          used for replication is the same as used for client network
          communication (the default is '3306').  For the host name,
          ensure that the name resolves to the correct IP address.

        * Check that networking has not been disabled on the master or
          slave.  Look for the 'skip-networking' option in the
          configuration file.  If present, comment it out or remove it.

        * If the master has a firewall or IP filtering configuration,
          ensure that the network port being used for MySQL is not being
          filtered.

        * Check that you can reach the master by using 'ping' or
          'traceroute'/'tracert' to reach the host.

   * If the slave was running previously but has stopped, the reason
     usually is that some statement that succeeded on the master failed
     on the slave.  This should never happen if you have taken a proper
     snapshot of the master, and never modified the data on the slave
     outside of the slave thread.  If the slave stops unexpectedly, it
     is a bug or you have encountered one of the known replication
     limitations described in replication-features.  If it is a
     bug, see replication-bugs, for instructions on how to
     report it.

   * If a statement that succeeded on the master refuses to run on the
     slave, try the following procedure if it is not feasible to do a
     full database resynchronization by deleting the slave's databases
     and copying a new snapshot from the master:

       1. Determine whether the affected table on the slave is different
          from the master table.  Try to understand how this happened.
          Then make the slave's table identical to the master's and run
          'START SLAVE'.

       2. If the preceding step does not work or does not apply, try to
          understand whether it would be safe to make the update
          manually (if needed) and then ignore the next statement from
          the master.

       3. If you decide that the slave can skip the next statement from
          the master, issue the following statements:

               mysql> SET GLOBAL sql_slave_skip_counter = N;
               mysql> START SLAVE;

          The value of N should be 1 if the next statement from the
          master does not use 'AUTO_INCREMENT' or 'LAST_INSERT_ID()'.
          Otherwise, the value should be 2.  The reason for using a
          value of 2 for statements that use 'AUTO_INCREMENT' or
          'LAST_INSERT_ID()' is that they take two events in the binary
          log of the master.

          See also set-global-sql-slave-skip-counter.

       4. If you are sure that the slave started out perfectly
          synchronized with the master, and that no one has updated the
          tables involved outside of the slave thread, then presumably
          the discrepancy is the result of a bug.  If you are running
          the most recent version of MySQL, please report the problem.
          If you are running an older version, try upgrading to the
          latest production release to determine whether the problem
          persists.

16.4.5 How to Report Replication Bugs or Problems
-------------------------------------------------

When you have determined that there is no user error involved, and
replication still either does not work at all or is unstable, it is time
to send us a bug report.  We need to obtain as much information as
possible from you to be able to track down the bug.  Please spend some
time and effort in preparing a good bug report.

If you have a repeatable test case that demonstrates the bug, please
enter it into our bugs database using the instructions given in
bug-reports.  If you have a 'phantom' problem (one that you cannot
duplicate at will), use the following procedure:

  1. Verify that no user error is involved.  For example, if you update
     the slave outside of the slave thread, the data goes out of
     synchrony, and you can have unique key violations on updates.  In
     this case, the slave thread stops and waits for you to clean up the
     tables manually to bring them into synchrony.  _This is not a
     replication problem.  It is a problem of outside interference
     causing replication to fail._

  2. Run the slave with the '--log-slave-updates' and '--log-bin'
     options.  These options cause the slave to log the updates that it
     receives from the master into its own binary logs.

  3. Save all evidence before resetting the replication state.  If we
     have no information or only sketchy information, it becomes
     difficult or impossible for us to track down the problem.  The
     evidence you should collect is:

        * All binary log files from the master

        * All binary log files from the slave

        * The output of 'SHOW MASTER STATUS'.
          from the master at the time you discovered the problem

        * The output of 'SHOW SLAVE STATUS'.
          from the slave at the time you discovered the problem

        * Error logs from the master and the slave

  4. Use 'mysqlbinlog' to examine the binary logs.
     The following should be helpful to find the problem statement.
     LOG_FILE and LOG_POS are the 'Master_Log_File' and
     'Read_Master_Log_Pos' values from 'SHOW SLAVE STATUS'.

          shell> mysqlbinlog --start-position=LOG_POS LOG_FILE | head

After you have collected the evidence for the problem, try to isolate it
as a separate test case first.  Then enter the problem with as much
information as possible into our bugs database using the instructions at
bug-reports.

17 Group Replication
********************

This chapter explains MySQL Group Replication and how to install,
configure and monitor groups.  MySQL Group Replication is a MySQL Server
plugin that enables you to create elastic, highly-available,
fault-tolerant replication topologies.

Groups can operate in a single-primary mode with automatic primary
election, where only one server accepts updates at a time.
Alternatively, for more advanced users, groups can be deployed in
multi-primary mode, where all servers can accept updates, even if they
are issued concurrently.

There is a built-in group membership service that keeps the view of the
group consistent and available for all servers at any given point in
time.  Servers can leave and join the group and the view is updated
accordingly.  Sometimes servers can leave the group unexpectedly, in
which case the failure detection mechanism detects this and notifies the
group that the view has changed.  This is all automatic.

The chapter is structured as follows:

   * group-replication-background provides an introduction to
     groups and how Group Replication works.

   * group-replication-getting-started explains how to configure
     multiple MySQL Server instances to create a group.

   * group-replication-monitoring explains how to monitor a
     group.

   * group-replication-security explains how to secure a group.

   * group-replication-technical-details provides in-depth
     information about how Group Replication works.

17.1 Group Replication Background
=================================

This section provides background information on MySQL Group Replication.

The most common way to create a fault-tolerant system is to resort to
making components redundant, in other words the component can be removed
and the system should continue to operate as expected.  This creates a
set of challenges that raise complexity of such systems to a whole
different level.  Specifically, replicated databases have to deal with
the fact that they require maintenance and administration of several
servers instead of just one.  Moreover, as servers are cooperating
together to create the group several other classic distributed systems
problems have to be dealt with, such as network partitioning or split
brain scenarios.

Therefore, the ultimate challenge is to fuse the logic of the database
and data replication with the logic of having several servers
coordinated in a consistent and simple way.  In other words, to have
multiple servers agreeing on the state of the system and the data on
each and every change that the system goes through.  This can be
summarized as having servers reaching agreement on each database state
transition, so that they all progress as one single database or
alternatively that they eventually converge to the same state.  Meaning
that they need to operate as a (distributed) state machine.

MySQL Group Replication provides distributed state machine replication
with strong coordination between servers.  Servers coordinate themselves
automatically when they are part of the same group.  The group can
operate in a single-primary mode with automatic primary election, where
only one server accepts updates at a time.  Alternatively, for more
advanced users the group can be deployed in multi-primary mode, where
all servers can accept updates, even if they are issued concurrently.
This power comes at the expense of applications having to work around
the limitations imposed by such deployments.

There is a built-in group membership service that keeps the view of the
group consistent and available for all servers at any given point in
time.  Servers can leave and join the group and the view is updated
accordingly.  Sometimes servers can leave the group unexpectedly, in
which case the failure detection mechanism detects this and notifies the
group that the view has changed.  This is all automatic.

For a transaction to commit, the majority of the group have to agree on
the order of a given transaction in the global sequence of transactions.
Deciding to commit or abort a transaction is done by each server
individually, but all servers make the same decision.  If there is a
network partition, resulting in a split where members are unable to
reach agreement, then the system does not progress until this issue is
resolved.  Hence there is also a built-in, automatic, split-brain
protection mechanism.

All of this is powered by the provided Group Communication System (GCS)
protocols.  These provide a failure detection mechanism, a group
membership service, and safe and completely ordered message delivery.
All these properties are key to creating a system which ensures that
data is consistently replicated across the group of servers.  At the
very core of this technology lies an implementation of the Paxos
algorithm.  It acts as the group communication engine.

17.1.1 Replication Technologies
-------------------------------

Before getting into the details of MySQL Group Replication, this section
introduces some background concepts and an overview of how things work.
This provides some context to help understand what is required for Group
Replication and what the differences are between classic asynchronous
MySQL Replication and Group Replication.

17.1.1.1 Primary-Secondary Replication
......................................

Traditional MySQL Replication provides a simple Primary-Secondary
approach to replication.  There is a primary (master) and there is one
or more secondaries (slaves).  The primary executes transactions,
commits them and then they are later (thus asynchronously) sent to the
secondaries to be either re-executed (in statement-based replication) or
applied (in row-based replication).  It is a shared-nothing system,
where all servers have a full copy of the data by default.

FIGURE GOES HERE: MySQL Asynchronous Replication

There is also semisynchronous replication, which adds one
synchronization step to the protocol.  This means that the Primary
waits, at commit time, for the secondary to acknowledge that it has
_received_ the transaction.  Only then does the Primary resume the
commit operation.

FIGURE GOES HERE: MySQL Semisynchronous Replication

In the two pictures above, you can see a diagram of the classic
asynchronous MySQL Replication protocol (and its semisynchronous variant
as well).  Diagonal arrows represent messages exchanged between servers
or messages exchanged between servers and the client application.

17.1.1.2 Group Replication
..........................

Group Replication is a technique that can be used to implement
fault-tolerant systems.  The replication group is a set of servers that
interact with each other through message passing.  The communication
layer provides a set of guarantees such as atomic message and total
order message delivery.  These are very powerful properties that
translate into very useful abstractions that one can resort to build
more advanced database replication solutions.

MySQL Group Replication builds on top of such properties and
abstractions and implements a multi-master update everywhere replication
protocol.  In essence, a replication group is formed by multiple servers
and each server in the group may execute transactions independently.
But all read-write (RW) transactions commit only after they have been
approved by the group.  Read-only (RO) transactions need no coordination
within the group and thus commit immediately.  In other words, for any
RW transaction the group needs to decide whether it commits or not, thus
the commit operation is not a unilateral decision from the originating
server.  To be precise, when a transaction is ready to commit at the
originating server, the server atomically broadcasts the write values
(rows changed) and the correspondent write set (unique identifiers of
the rows that were updated).  Then a global total order is established
for that transaction.  Ultimately, this means that all servers receive
the same set of transactions in the same order.  As a consequence, all
servers apply the same set of changes in the same order, therefore they
remain consistent within the group.

However, there may be conflicts between transactions that execute
concurrently on different servers.  Such conflicts are detected by
inspecting the write sets of two different and concurrent transactions,
in a process called _certification_.  If two concurrent transactions,
that executed on different servers, update the same row, then there is a
conflict.  The resolution procedure states that the transaction that was
ordered first commits on all servers, whereas the transaction ordered
second aborts, and thus is rolled back on the originating server and
dropped by the other servers in the group.  This is in fact a
distributed first commit wins rule.

FIGURE GOES HERE: MySQL Group Replication Protocol

Finally, Group Replication is a shared-nothing replication scheme where
each server has its own entire copy of the data.

The figure above depicts the MySQL Group Replication protocol and by
comparing it to MySQL Replication (or even MySQL semisynchronous
replication) you can see some differences.  Note that some underlying
consensus and Paxos related messages are missing from this picture for
the sake of clarity.

17.1.2 Group Replication Use Cases
----------------------------------

Group Replication enables you to create fault-tolerant systems with
redundancy by replicating the system state throughout a set of servers.
Consequently, even if some of the servers fail, as long it is not all or
a

majority, the system is still available, and all it could have degraded
performance or scalability, it is still available.  Server failures are
isolated and independent.  They are tracked by a group membership
service which relies on a distributed failure detector that is able to
signal when any servers leave the group, either voluntarily or due to an
unexpected halt.  There is a distributed recovery procedure to ensure
that when servers join the group they are brought up to date
automatically.  There is no need for server fail-over, and the
multi-master update everywhere nature ensures that not even updates are
blocked in the event of a single server failure.  Therefore MySQL Group
Replication guarantees that the database service is continuously
available.

It is important to understand that although the database service is
available, in the event of a server crash, those clients connected to it
must be redirected, or failed over, to a different server.  This is not
something Group Replication attempts to resolve.  A connector, load
balancer, router, or some form of middleware are more suitable to deal
with this issue.

To summarize, MySQL Group Replication provides a highly available,
highly elastic, dependable MySQL service.

17.1.2.1 Examples of Use Case Scenarios
.......................................

The following examples are typical use cases for Group Replication.

   * _Elastic Replication_ - Environments that require a very fluid
     replication infrastructure, where the number of servers has to grow
     or shrink dynamically and with as few side-effects as possible.
     For instance, database services for the cloud.

   * _Highly Available Shards_ - Sharding is a popular approach to
     achieve write scale-out.  Use MySQL Group Replication to implement
     highly available shards, where each shard maps to a replication
     group.

   * _Alternative to Master-Slave replication_ - In certain situations,
     using a single master server makes it a single point of contention.
     Writing to an entire group may prove more scalable under certain
     circumstances.

   * _Autonomic Systems_ - Additionally, you can deploy MySQL Group
     Replication purely for the automation that is built into the
     replication protocol (described already in this and previous
     chapters).

17.1.3 Group Replication Details
--------------------------------

This section presents details about some of the services that Group
Replication builds on.

17.1.3.1 Failure Detection
..........................

There is a failure detection mechanism provided that is able to find and
report which servers are silent and as such assumed to be dead.  At a
high level, the failure detector is a distributed service that provides
information about which servers may be dead (suspicions).  Later if the
group agrees that the suspicions are probably true, then the group
decides that a given server has indeed failed.  This means that the
remaining members in the group take a coordinated decision to exclude a
given member.

Suspicions are triggered when servers go mute.  When server A does not
receive messages from server B during a given period, a timeout occurs
and a suspicion is raised.

If a server gets isolated from the rest of the group, then it suspects
that all others have failed.  Being unable to secure agreement with the
group (as it cannot secure a quorum), its suspicion does not have
consequences.  When a server is isolated from the group in this way, it
is unable to execute any local transactions.

17.1.3.2 Group Membership
.........................

MySQL Group Replication relies on a group membership service.  This is
built into the plugin.  It defines which servers are online and
participating in the group.  The list of online servers is often
referred to as a _view_.  Therefore, every server in the group has a
consistent view of which are the members participating actively in the
group at a given moment in time.

Servers have to agree not only on transaction commits, but also which is
the current view.  Therefore, if servers agree that a new server becomes
part of the group, then the group itself is reconfigured to integrate
that server in it, triggering a view change.  The opposite also happens,
if a server leaves the group, voluntarily or not, then the group
dynamically rearranges its configuration and a view change is triggered.

Note though that when a member leaves voluntarily, it first initiates a
dynamic group reconfiguration.  This triggers a procedure, where all
members have to agree on the new view without the leaving server.
However, if a member leaves involuntarily (for example it has stopped
unexpectedly or the network connection is down) then the failure
detection mechanism realizes this fact and a reconfiguration of the
group is proposed, this one without the failed member.  As mentioned
this requires agreement from the majority of servers in the group.  If
the group is not able to reach agreement (for example it partitioned in
such a way that there is no majority of servers online), then the system
is not be able to dynamically change the configuration and as such,
blocks to prevent a split-brain situation.  Ultimately, this means that
the administrator needs to step in and fix this.

17.1.3.3 Fault-tolerance
........................

MySQL Group Replication builds on an implementation of the Paxos
distributed algorithm to provide distributed coordination between
servers.  As such, it requires a majority of servers to be active to
reach quorum and thus make a decision.  This has direct impact on the
number of failures the system can tolerate without compromising itself
and its overall functionality.  The number of servers (n) needed to
tolerate 'f' failures is then 'n = 2 x f + 1'.

In practice this means that to tolerate one failure the group must have
three servers in it.  As such if one server fails, there are still two
servers to form a majority (two out of three) and allow the system to
continue to make decisions automatically and progress.  However, if a
second server fails _involuntarily_, then the group (with one server
left) blocks, because there is no majority to reach a decision.

The following is a small table illustrating the formula above.

GroupMajorityInstant
SizeFailures
  Tolerated

110

220

321

431

532

642

743

The next Chapter covers technical aspects of Group Replication.

17.2 Getting Started
====================

MySQL Group Replication is provided as a plugin to MySQL server, and
each server in a group requires configuration and installation of the
plugin.  This section provides a detailed tutorial with the steps
required to create a replication group with at least three servers.

17.2.1 Deploying Group Replication in Single-Primary Mode
---------------------------------------------------------

Each of the server instances in a group can run on an independent
physical machine, or on the same machine.  This section explains how to
create a replication group with three MySQL Server instances on one
physical machine.  This means that three data directories are needed,
one per server instance, and that you need to configure each instance
independently.

FIGURE GOES HERE: Group Architecture

This tutorial explains how to get and deploy MySQL Server with the Group
Replication plugin, how to configure each server instance before
creating a group, and how to use Performance Schema monitoring to verify
that everything is working correctly.

17.2.1.1 Deploying Instances for Group Replication
..................................................

The first step is to deploy three instances of MySQL Server.  Group
Replication is a built-in MySQL plugin provided with MySQL Server 5.7.17
and later.  For more background information on MySQL plugins, see
server-plugins.  This procedure assumes that MySQL Server was
downloaded and unpacked into the directory named 'mysql-5.7'.  The
following procedure uses one physical machine, therefore each MySQL
server instance requires a specific data directory for the instance.
Create the data directories in a directory named 'data' and initialize
each one.

     mkdir data
     mysql-5.7/bin/mysqld --initialize-insecure --basedir=$PWD/mysql-5.7 --datadir=$PWD/data/s1
     mysql-5.7/bin/mysqld --initialize-insecure --basedir=$PWD/mysql-5.7 --datadir=$PWD/data/s2
     mysql-5.7/bin/mysqld --initialize-insecure --basedir=$PWD/mysql-5.7 --datadir=$PWD/data/s3

Inside 'data/s1', 'data/s2', 'data/s3' is an initialized data directory,
containing the mysql system database and related tables and much more.
To learn more about the initialization procedure, see
data-directory-initialization-mysqld.

*Warning*:

Do not use '--initialize-insecure' in production environments, it is
only used here to simplify the tutorial.  For more information on
security settings, see group-replication-security.

17.2.1.2 Configuring an Instance for Group Replication
......................................................

This section explains the configuration settings required for MySQL
Server instances that you want to use for Group Replication.  For
background information, see group-replication-limitations.

*Group Replication Server Settings*

To install and use the Group Replication plugin you must configure the
MySQL Server instance correctly.  It is recommended to store the
configuration in the instance's configuration file.  See
option-files for more information.  Unless stated otherwise, what
follows is the configuration for the first instance in the group,
referred to as _s1_ in this procedure.  The following section shows an
example server configuration.

     [mysqld]

     # server configuration
     datadir=<full_path_to_data>/data/s1
     basedir=<full_path_to_bin>/mysql-5.7/

     port=24801
     socket=<full_path_to_sock_dir>/s1.sock

These settings configure MySQL server to use the data directory created
earlier and which port the server should open and start listening for
incoming connections.

*Note*:

The non-default port of 24801 is used because in this tutorial the three
server instances use the same hostname.  In a setup with three different
machines this would not be required.

Group Replication depends on a network connection between the members,
which means that each member must be able to resolve the network address
of all of the other members.  For example in this tutorial all three
instances run on one machine, so to ensure that the members can contact
each other you could add a line to the option file such as
'report_host=127.0.0.1'.

*Replication Framework*

The following settings configure replication according to the MySQL
Group Replication requirements.

     server_id=1
     gtid_mode=ON
     enforce_gtid_consistency=ON
     master_info_repository=TABLE
     relay_log_info_repository=TABLE
     binlog_checksum=NONE
     log_slave_updates=ON
     log_bin=binlog
     binlog_format=ROW

These settings configure the server to use the unique identifier number
1, to enable global transaction identifiers and to store replication
metadata in system tables instead of files.  Additionally, it instructs
the server to turn on binary logging, use row-based format and disable
binary log event checksums.  For more details see
group-replication-requirements.

*Group Replication Settings*

At this point the 'my.cnf' file ensures that the server is configured
and is instructed to instantiate the replication infrastructure under a
given configuration.  The following section configures the Group
Replication settings for the server.

     transaction_write_set_extraction=XXHASH64
     loose-group_replication_group_name="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
     loose-group_replication_start_on_boot=off
     loose-group_replication_local_address= "127.0.0.1:24901"
     loose-group_replication_group_seeds= "127.0.0.1:24901,127.0.0.1:24902,127.0.0.1:24903"
     loose-group_replication_bootstrap_group=off

*Note*:

The 'loose-' prefix used for the 'group_replication' variables above
instructs the server to continue to start if the Group Replication
plugin has not been loaded at the time the server is started.

   * Configuring 'transaction_write_set_extraction' instructs the server
     that for each transaction it has to collect the write set and
     encode it as a hash using the 'XXHASH64' hashing algorithm.

   * Configuring 'group_replication_group_name' tells the plugin that
     the group that it is joining, or creating, is named
     "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa".

   * Configuring 'group_replication_start_on_boot' instructs the plugin
     to not start operations automatically when the server starts.  This
     is important when setting up Group Replication as it ensures you
     can configure the server before manually starting the plugin.  Once
     the member is configured you can set
     'group_replication_start_on_boot' to on so that Group Replication
     starts automatically upon server boot.

   * Configuring 'group_replication_local_address' tells the plugin to
     use the network address 127.0.0.1 and port 24901 for internal
     communication with other members in the group.

     *Important*:

     Group Replication uses this address for internal member-to-member
     connections using XCom.  This address must be different to the
     hostname and port used for SQL and it must not be used for client
     applications.  It must be reserved for internal communication
     between the members of the group while running Group Replication.

     The network address configured by 'group_replication_local_address'
     must be resolvable by all group members.  For example, if each
     server instance is on a different machine with a fixed network
     address you could use the IP of the machine, such as 10.0.0.1.  If
     you use hostnames then you must use a fully qualified name and
     ensure it is resolvable through DNS, correctly configured
     '/etc/hosts' files, or other name resolution processes.  The
     recommended port for 'group_replication_local_address' is 33061.
     In this tutorial we use three server instances running on one
     machine, thus ports 24901 to 24903 are used for the internal
     communication network address.

   * Configuring 'group_replication_group_seeds' sets the hostname and
     port of the group members which are used by the new member to
     establish its connection to the group.  These members are called
     the seed members.  Once the connection is established, the group
     membership information is listed at
     'performance_schema.replication_group_members'.  Usually the
     'group_replication_group_seeds' list contains the 'hostname:port'
     of each of the group member's 'group_replication_local_address',
     but this is not obligatory and a subset of the group members can be
     chosen as seeds.

     *Important*:

     The 'hostname:port' listed in 'group_replication_group_seeds' is
     the seed member's internal network address, configured by
     'group_replication_local_address' and not the SQL 'hostname:port'
     used for client connections, and shown for example in
     'performance_schema.replication_group_members' table.

     The server that starts the group does not make use of this option,
     since it is the initial server and as such, it is in charge of
     bootstrapping the group.  In other words, any existing data which
     is on the server bootstrapping the group is what is used as the
     data for the next joining member.  The second server joining asks
     the one and only member in the group to join, any missing data on
     the second server is replicated from the donor data on the
     bootstrapping member, and then the group expands.  The third server
     joining can ask any of these two to join, data is synchronized to
     the new member, and then the group expands again.  Subsequent
     servers repeat this procedure when joining.

     *Warning*:

     When joining multiple servers at the same time, make sure that they
     point to seed members that are already in the group.  Do not use
     members that are also joining the group as as seeds, because they
     may not yet be in the group when contacted.

     It is good practice to start the bootstrap member first, and let it
     create the group.  Then make it the seed member for the rest of the
     members that are joining.  This ensures that there is a group
     formed when joining the rest of the members.

     Creating a group and joining multiple members at the same time is
     not supported.  It may work, but chances are that the operations
     race and then the act of joining the group ends up in an error or a
     time out.

   * Configuring 'group_replication_bootstrap_group' instructs the
     plugin whether to bootstrap the group or not.

     *Important*:

     This option must only be used on one server instance at any time,
     usually the first time you bootstrap the group (or in case the
     entire group is brought down and back up again).  If you bootstrap
     the group multiple times, for example when multiple server
     instances have this option set, then they could create an
     artificial split brain scenario, in which two distinct groups with
     the same name exist.  Disable this option after the first server
     instance comes online.

Configuration for all servers in the group is quite similar.  You need
to change the specifics about each server (for example 'server_id',
'datadir', 'group_replication_local_address').  This is illustrated
later in this tutorial.

17.2.1.3 User Credentials
.........................

Group Replication uses the asynchronous replication protocol to achieve
group-replication-distributed-recovery, synchronizing group
members before joining them to the group.  The distributed recovery
process relies on a replication channel named
'group_replication_recovery' which is used to transfer transactions from
donor members to members that join the group.  Therefore you need to set
up a replication user with the correct permissions so that Group
Replication can establish direct member-to-member recovery replication
channels.

Start the server using the options file:

     mysql-5.7/bin/mysqld --defaults-file=data/s1/s1.cnf

Create a MySQL user with the 'REPLICATION-SLAVE' privilege.  This
process should _not_ be captured in the binary log to avoid the changes
being propagated to other server instances.  Connect to server s1 and
issue the following statements:

     mysql> SET SQL_LOG_BIN=0;

In the following example the user RPL_USER with the password PASSWORD is
shown.  When configuring your servers use a suitable user name and
password.  Binary logging is enabled again once the user is created.

     mysql> CREATE USER RPL_USER@'%' IDENTIFIED BY 'PASSWORD';
     mysql> GRANT REPLICATION SLAVE ON *.* TO RPL_USER@'%';
     mysql> FLUSH PRIVILEGES;
     mysql> SET SQL_LOG_BIN=1;

Once the user has been configured, use the 'CHANGE MASTER TO'
statement to configure the server to use the given
credentials for the 'group_replication_recovery' replication channel the
next time it needs to recover its state from another member.  Issue the
following, replacing RPL_USER and PASSWORD with the values used when
creating the user.

     mysql> CHANGE MASTER TO MASTER_USER='RPL_USER', MASTER_PASSWORD='PASSWORD' \\
     		      FOR CHANNEL 'group_replication_recovery';

Distributed recovery is the first step taken by a server that joins the
group and does not have the same set of transactions as the group
members.  If these credentials are not set correctly for the
'group_replication_recovery' replication channel and the 'rpl_user' as
shown, the server cannot connect to the donor members and run the
distributed recovery process to gain synchrony with the other group
members, and hence ultimately cannot join the group.

Similarly, if the server cannot correctly identify the other members via
the server's 'hostname' the recovery process can fail.  It is
recommended that operating systems running MySQL have a properly
configured unique 'hostname', either using DNS or local settings.  This
'hostname' can be verified in the 'Member_host' column of the
'performance_schema.replication_group_members'
table.  If multiple group members
externalize a default 'hostname' set by the operating system, there is a
chance of the member not resolving to the correct member address and not
being able to join the group.  In such a situation use 'report_host' to
configure a unique 'hostname' to be externalized by each of the servers.

17.2.1.4 Launching Group Replication
....................................

Once server s1 has been configured and started, install the Group
Replication plugin.  Connect to the server and issue the following
command:

     INSTALL PLUGIN group_replication SONAME 'group_replication.so';

*Important*:

The 'mysql.session' user must exist before you can load Group
Replication.  'mysql.session' was added in MySQL version 5.7.19.  If
your data dictionary was initialized using an earlier version you must
run the 'mysql_upgrade' procedure.  If the upgrade
is not run, Group Replication fails to start with the error message '
There 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.'.

To check that the plugin was installed successfully, issue 'SHOW
PLUGINS;' and check the output.  It should show something like this:

     mysql> SHOW PLUGINS;
     +----------------------------+----------+--------------------+----------------------+-------------+
     | Name                       | Status   | Type               | Library              | License     |
     +----------------------------+----------+--------------------+----------------------+-------------+
     | binlog                     | ACTIVE   | STORAGE ENGINE     | NULL                 | PROPRIETARY |

     (...)

     | group_replication          | ACTIVE   | GROUP REPLICATION  | group_replication.so | PROPRIETARY |
     +----------------------------+----------+--------------------+----------------------+-------------+

To start the group, instruct server s1 to bootstrap the group and then
start Group Replication.  This bootstrap should only be done by a single
server, the one that starts the group and only once.  This is why the
value of the bootstrap configuration option was not saved in the
configuration file.  If it is saved in the configuration file, upon
restart the server automatically bootstraps a second group with the same
name.  This would result in two distinct groups with the same name.  The
same reasoning applies to stopping and restarting the plugin with this
option set to 'ON'.

     SET GLOBAL group_replication_bootstrap_group=ON;
     START GROUP_REPLICATION;
     SET GLOBAL group_replication_bootstrap_group=OFF;

Once the 'START GROUP_REPLICATION'.
statement returns, the group has been started.  You can check that the
group is now created and that there is one member in it:

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+---------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE  |
     +---------------------------+--------------------------------------+-------------+-------------+---------------+
     | group_replication_applier | ce9be252-2b71-11e6-b8f4-00212844f856 | myhost      |       24801 | ONLINE        |
     +---------------------------+--------------------------------------+-------------+-------------+---------------+

The information in this table confirms that there is a member in the
group with the unique identifier 'ce9be252-2b71-11e6-b8f4-00212844f856',
that it is 'ONLINE' and is at 'myhost' listening for client connections
on port '24801'.

For the purpose of demonstrating that the server is indeed in a group
and that it is able to handle load, create a table and add some content
to it.

     mysql> CREATE DATABASE test;
     mysql> USE test;
     mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY, c2 TEXT NOT NULL);
     mysql> INSERT INTO t1 VALUES (1, 'Luis');

Check the content of table 't1' and the binary log.

     mysql> SELECT * FROM t1;
     +----+------+
     | c1 | c2   |
     +----+------+
     |  1 | Luis |
     +----+------+

     mysql> SHOW BINLOG EVENTS;
     +---------------+-----+----------------+-----------+-------------+--------------------------------------------------------------------+
     | Log_name      | Pos | Event_type     | Server_id | End_log_pos | Info                                                               |
     +---------------+-----+----------------+-----------+-------------+--------------------------------------------------------------------+
     | binlog.000001 |   4 | Format_desc    |         1 |         123 | Server ver: 5.7.19-gr080-log, Binlog ver: 4                        |
     | binlog.000001 | 123 | Previous_gtids |         1 |         150 |                                                                    |
     | binlog.000001 | 150 | Gtid           |         1 |         211 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:1'  |
     | binlog.000001 | 211 | Query          |         1 |         270 | BEGIN                                                              |
     | binlog.000001 | 270 | View_change    |         1 |         369 | view_id=14724817264259180:1                                        |
     | binlog.000001 | 369 | Query          |         1 |         434 | COMMIT                                                             |
     | binlog.000001 | 434 | Gtid           |         1 |         495 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:2'  |
     | binlog.000001 | 495 | Query          |         1 |         585 | CREATE DATABASE test                                               |
     | binlog.000001 | 585 | Gtid           |         1 |         646 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:3'  |
     | binlog.000001 | 646 | Query          |         1 |         770 | use `test`; CREATE TABLE t1 (c1 INT PRIMARY KEY, c2 TEXT NOT NULL) |
     | binlog.000001 | 770 | Gtid           |         1 |         831 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:4'  |
     | binlog.000001 | 831 | Query          |         1 |         899 | BEGIN                                                              |
     | binlog.000001 | 899 | Table_map      |         1 |         942 | table_id: 108 (test.t1)                                            |
     | binlog.000001 | 942 | Write_rows     |         1 |         984 | table_id: 108 flags: STMT_END_F                                    |
     | binlog.000001 | 984 | Xid            |         1 |        1011 | COMMIT /* xid=38 */                                                |
     +---------------+-----+----------------+-----------+-------------+--------------------------------------------------------------------+

As seen above, the database and the table objects were created and their
corresponding DDL statements were written to the binary log.  Also, the
data was inserted into the table and written to the binary log.  The
importance of the binary log entries is illustrated in the following
section when the group grows and distributed recovery is executed as new
members try to catch up and become online.

17.2.1.5 Adding Instances to the Group
......................................

At this point, the group has one member in it, server s1, which has some
data in it.  It is now time to expand the group by adding the other two
servers configured previously.

17.2.1.6 Adding a Second Instance
.................................

In order to add a second instance, server s2, first create the
configuration file for it.  The configuration is similar to the one used
for server s1, except for things such as the location of the data
directory, the ports that s2 is going to be listening on or its
'server_id'.  These different lines are highlighted in the listing
below.

     [mysqld]

     # server configuration
     datadir=<full_path_to_data>/data/s2
     basedir=<full_path_to_bin>/mysql-5.7/

     port=24802
     socket=<full_path_to_sock_dir>/s2.sock

     #
     # Replication configuration parameters
     #
     server_id=2
     gtid_mode=ON
     enforce_gtid_consistency=ON
     master_info_repository=TABLE
     relay_log_info_repository=TABLE
     binlog_checksum=NONE
     log_slave_updates=ON
     log_bin=binlog
     binlog_format=ROW

     #
     # Group Replication configuration
     #
     transaction_write_set_extraction=XXHASH64
     loose-group_replication_group_name="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
     loose-group_replication_start_on_boot=off
     loose-group_replication_local_address= "127.0.0.1:24902"
     loose-group_replication_group_seeds= "127.0.0.1:24901,127.0.0.1:24902,127.0.0.1:24903"
     loose-group_replication_bootstrap_group= off

Similar to the procedure for server s1, with the option file in place
you launch the server.

     mysql-5.7/bin/mysqld --defaults-file=data/s2/s2.cnf

Then configure the recovery credentials as follows.  The commands are
the same as used when setting up server s1 as the user is shared within
the group.  Issue the following statements on s2.

     SET SQL_LOG_BIN=0;
     CREATE USER RPL_USER@'%' IDENTIFIED BY 'PASSWORD';
     GRANT REPLICATION SLAVE ON *.* TO RPL_USER@'%';
     SET SQL_LOG_BIN=1;
     CHANGE MASTER TO MASTER_USER='RPL_USER', MASTER_PASSWORD='PASSWORD' \\
     	FOR CHANNEL 'group_replication_recovery';

Install the Group Replication plugin and start the process of joining
the server to the group.  The following example installs the plugin in
the same way as used while deploying server s1.

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

Add server s2 to the group.

     mysql> START GROUP_REPLICATION;

Unlike the previous steps that were the same as those executed on s1,
here there is a difference in that you do _not_ issue 'SET GLOBAL
group_replication_bootstrap_group=ON;' before starting Group
Replication, because the group has already been created and bootstrapped
by server s1.  At this point server s2 only needs to be added to the
already existing group.

*Tip*:

When Group Replication starts successfully and the server joins the
group it checks the 'super_read_only' variable.  By setting
'super_read_only' to ON in the member's configuration file, you can
ensure that servers which fail when starting Group Replication for any
reason do not accept transactions.  If the server should join the group
as read-write instance, for example as the primary in a single-primary
group or as a member of a multi-primary group, when the
'super_read_only' variable is set to ON then it is set to OFF upon
joining the group.

Checking the 'performance_schema.replication_group_members' table again
shows that there are now two _ONLINE_ servers in the group.

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+---------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE  |
     +---------------------------+--------------------------------------+-------------+-------------+---------------+
     | group_replication_applier | 395409e1-6dfa-11e6-970b-00212844f856 | myhost      |       24801 | ONLINE        |
     | group_replication_applier | ac39f1e6-6dfa-11e6-a69d-00212844f856 | myhost      |       24802 | ONLINE        |
     +---------------------------+--------------------------------------+-------------+-------------+---------------+

As server s2 is also marked as ONLINE, it must have already caught up
with server s1 automatically.  Verify that it has indeed synchronized
with server s1 as follows.

     mysql> SHOW DATABASES LIKE 'test';
     +-----------------+
     | Database (test) |
     +-----------------+
     | test            |
     +-----------------+

     mysql> SELECT * FROM test.t1;
     +----+------+
     | c1 | c2   |
     +----+------+
     |  1 | Luis |
     +----+------+

     mysql> SHOW BINLOG EVENTS;
     +---------------+------+----------------+-----------+-------------+--------------------------------------------------------------------+
     | Log_name      | Pos  | Event_type     | Server_id | End_log_pos | Info                                                               |
     +---------------+------+----------------+-----------+-------------+--------------------------------------------------------------------+
     | binlog.000001 |    4 | Format_desc    |         2 |         123 | Server ver: 5.7.17-log, Binlog ver: 4                              |
     | binlog.000001 |  123 | Previous_gtids |         2 |         150 |                                                                    |
     | binlog.000001 |  150 | Gtid           |         1 |         211 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:1'  |
     | binlog.000001 |  211 | Query          |         1 |         270 | BEGIN                                                              |
     | binlog.000001 |  270 | View_change    |         1 |         369 | view_id=14724832985483517:1                                        |
     | binlog.000001 |  369 | Query          |         1 |         434 | COMMIT                                                             |
     | binlog.000001 |  434 | Gtid           |         1 |         495 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:2'  |
     | binlog.000001 |  495 | Query          |         1 |         585 | CREATE DATABASE test                                               |
     | binlog.000001 |  585 | Gtid           |         1 |         646 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:3'  |
     | binlog.000001 |  646 | Query          |         1 |         770 | use `test`; CREATE TABLE t1 (c1 INT PRIMARY KEY, c2 TEXT NOT NULL) |
     | binlog.000001 |  770 | Gtid           |         1 |         831 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:4'  |
     | binlog.000001 |  831 | Query          |         1 |         890 | BEGIN                                                              |
     | binlog.000001 |  890 | Table_map      |         1 |         933 | table_id: 108 (test.t1)                                            |
     | binlog.000001 |  933 | Write_rows     |         1 |         975 | table_id: 108 flags: STMT_END_F                                    |
     | binlog.000001 |  975 | Xid            |         1 |        1002 | COMMIT /* xid=30 */                                                |
     | binlog.000001 | 1002 | Gtid           |         1 |        1063 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:5'  |
     | binlog.000001 | 1063 | Query          |         1 |        1122 | BEGIN                                                              |
     | binlog.000001 | 1122 | View_change    |         1 |        1261 | view_id=14724832985483517:2                                        |
     | binlog.000001 | 1261 | Query          |         1 |        1326 | COMMIT                                                             |
     +---------------+------+----------------+-----------+-------------+--------------------------------------------------------------------+

As seen above, the second server has been added to the group and it has
replicated the changes from server s1 automatically.  According to the
distributed recovery procedure, this means that just after joining the
group and immediately before being declared online, server s2 has
connected to server s1 automatically and fetched the missing data from
it.  In other words, it copied transactions from the binary log of s1
that it was missing, up to the point in time that it joined the group.

17.2.1.7 Adding Additional Instances
....................................

Adding additional instances to the group is essentially the same
sequence of steps as adding the second server, except that the
configuration has to be changed as it had to be for server s2.  To
summarise the required commands:

_1.  Create the configuration file_

     [mysqld]

     # server configuration
     datadir=<full_path_to_data>/data/s3
     basedir=<full_path_to_bin>/mysql-5.7/

     port=24803
     socket=<full_path_to_sock_dir>/s3.sock

     #
     # Replication configuration parameters
     #
     server_id=3
     gtid_mode=ON
     enforce_gtid_consistency=ON
     master_info_repository=TABLE
     relay_log_info_repository=TABLE
     binlog_checksum=NONE
     log_slave_updates=ON
     log_bin=binlog
     binlog_format=ROW

     #
     # Group Replication configuration
     #
     transaction_write_set_extraction=XXHASH64
     loose-group_replication_group_name="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
     loose-group_replication_start_on_boot=off
     loose-group_replication_local_address= "127.0.0.1:24903"
     loose-group_replication_group_seeds= "127.0.0.1:24901,127.0.0.1:24902,127.0.0.1:24903"
     loose-group_replication_bootstrap_group= off

_2.  Start the server_

     mysql-5.7/bin/mysqld --defaults-file=data/s3/s3.cnf

_3.  Configure the recovery credentials for the
group_replication_recovery channel._

     SET SQL_LOG_BIN=0;
     CREATE USER RPL_USER@'%';
     GRANT REPLICATION SLAVE ON *.* TO RPL_USER@'%' IDENTIFIED BY 'PASSWORD';
     FLUSH PRIVILEGES;
     SET SQL_LOG_BIN=1;
     CHANGE MASTER TO MASTER_USER='RPL_USER', MASTER_PASSWORD='PASSWORD'  \\
     FOR CHANNEL 'group_replication_recovery';

_4.  Install the Group Replication plugin and start it._

     INSTALL PLUGIN group_replication SONAME 'group_replication.so';
     START GROUP_REPLICATION;

At this point server s3 is booted and running, has joined the group and
caught up with the other servers in the group.  Consulting the
'performance_schema.replication_group_members' table again confirms this
is the case.

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+---------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE  |
     +---------------------------+--------------------------------------+-------------+-------------+---------------+
     | group_replication_applier | 395409e1-6dfa-11e6-970b-00212844f856 | myhost      |       24801 | ONLINE        |
     | group_replication_applier | 7eb217ff-6df3-11e6-966c-00212844f856 | myhost      |       24803 | ONLINE        |
     | group_replication_applier | ac39f1e6-6dfa-11e6-a69d-00212844f856 | myhost      |       24802 | ONLINE        |
     +---------------------------+--------------------------------------+-------------+-------------+---------------+

Issuing this same query on server s2 or server s1 yields the same
result.  Also, you can verify that server s3 has also caught up:

     mysql> SHOW DATABASES LIKE 'test';
     +-----------------+
     | Database (test) |
     +-----------------+
     | test            |
     +-----------------+

     mysql> SELECT * FROM test.t1;
     +----+------+
     | c1 | c2   |
     +----+------+
     |  1 | Luis |
     +----+------+

     mysql> SHOW BINLOG EVENTS;
     +---------------+------+----------------+-----------+-------------+--------------------------------------------------------------------+
     | Log_name      | Pos  | Event_type     | Server_id | End_log_pos | Info                                                               |
     +---------------+------+----------------+-----------+-------------+--------------------------------------------------------------------+
     | binlog.000001 |    4 | Format_desc    |         3 |         123 | Server ver: 5.7.17-log, Binlog ver: 4                              |
     | binlog.000001 |  123 | Previous_gtids |         3 |         150 |                                                                    |
     | binlog.000001 |  150 | Gtid           |         1 |         211 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:1'  |
     | binlog.000001 |  211 | Query          |         1 |         270 | BEGIN                                                              |
     | binlog.000001 |  270 | View_change    |         1 |         369 | view_id=14724832985483517:1                                        |
     | binlog.000001 |  369 | Query          |         1 |         434 | COMMIT                                                             |
     | binlog.000001 |  434 | Gtid           |         1 |         495 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:2'  |
     | binlog.000001 |  495 | Query          |         1 |         585 | CREATE DATABASE test                                               |
     | binlog.000001 |  585 | Gtid           |         1 |         646 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:3'  |
     | binlog.000001 |  646 | Query          |         1 |         770 | use `test`; CREATE TABLE t1 (c1 INT PRIMARY KEY, c2 TEXT NOT NULL) |
     | binlog.000001 |  770 | Gtid           |         1 |         831 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:4'  |
     | binlog.000001 |  831 | Query          |         1 |         890 | BEGIN                                                              |
     | binlog.000001 |  890 | Table_map      |         1 |         933 | table_id: 108 (test.t1)                                            |
     | binlog.000001 |  933 | Write_rows     |         1 |         975 | table_id: 108 flags: STMT_END_F                                    |
     | binlog.000001 |  975 | Xid            |         1 |        1002 | COMMIT /* xid=29 */                                                |
     | binlog.000001 | 1002 | Gtid           |         1 |        1063 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:5'  |
     | binlog.000001 | 1063 | Query          |         1 |        1122 | BEGIN                                                              |
     | binlog.000001 | 1122 | View_change    |         1 |        1261 | view_id=14724832985483517:2                                        |
     | binlog.000001 | 1261 | Query          |         1 |        1326 | COMMIT                                                             |
     | binlog.000001 | 1326 | Gtid           |         1 |        1387 | SET @@SESSION.GTID_NEXT= 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:6'  |
     | binlog.000001 | 1387 | Query          |         1 |        1446 | BEGIN                                                              |
     | binlog.000001 | 1446 | View_change    |         1 |        1585 | view_id=14724832985483517:3                                        |
     | binlog.000001 | 1585 | Query          |         1 |        1650 | COMMIT                                                             |
     +---------------+------+----------------+-----------+-------------+--------------------------------------------------------------------+

17.3 Monitoring Group Replication
=================================

Use the Perfomance Schema tables to monitor Group Replication, assuming
that the Performance Schema is enabled.  Group Replication adds the
following tables:

   * 'performance_schema.replication_group_member_stats'

   * 'performance_schema.replication_group_members'

These Perfomance Schema replication tables also show information about
Group Replication:

   * 'performance_schema.replication_connection_status'

   * 'performance_schema.replication_applier_status'

The replication channels created by the Group Replication plugin are
named:

   * 'group_replication_recovery' - This channel is used for the
     replication changes that are related to the distributed recovery
     phase.

   * 'group_replication_applier' - This channel is used for the incoming
     changes from the group.  This is the channel used to apply
     transactions coming directly from the group.

The following sections describe the information available in each of
these tables.

17.3.1 Replication_group_member_stats
-------------------------------------

Each member in a replication group certifies and applies transactions
received by the group.  Statistics regarding the certifier and applier
procedures are useful to understand how the applier queue is growing,
how many conflicts have been found, how many transactions were checked,
which transactions are committed everywhere, and so on.

The 'performance_schema.replication_group_member_stats' table provides
information related to the certification process.  The information is
shared between all the server instances that are members of the
replication group, so information on all the group members can be
queried from any member.

*replication_group_member_stats*

Field                         Description

Channel_name                  The name of the Group Replication
                              channel.

Member_id                     The member server UUID. This has a
                              different value for each member in the
                              group.  This also serves as a key because
                              it is unique to each member.

Count_transactions_in_queue   The number of transactions in the queue
                              pending conflict detection checks.  Once
                              the transactions have been checked for
                              conflicts, if they pass the check, they
                              are queued to be applied as well.

Count_transactions_checked    The number of transactions that have been
                              checked for conflicts.

Count_conflicts_detected      The number of transactions that did not
                              pass the conflict detection check.

Count_transactions_rows_validatingThe current size of the conflict
                              detection database (against which each
                              transaction is certified).

Transactions_committed_all_membersThe transactions that have been
                              successfully committed on all members of
                              the replication group.  This is updated
                              at a fixed time interval.

Last_conflict_free_transactionThe transaction identifier of the last
                              conflict free transaction checked.

These fields are important for monitoring the performance of the members
connected in the group.  For example, suppose that one of the group's
members is delayed and is not able to keep up to date with the other
members of the group.  In this case you might see a large number of
transactions in the queue.  Based on this information, you could decide
to either remove the member from the group, or delay the processing of
transactions on the other members of the group in order to reduce the
number of queued transactions.  This information can also help you to
decide how to adjust the flow control of the Group Replication plugin.

17.3.2 Replication_group_members
--------------------------------

This table is used for monitoring the status of the different server
instances that are tracked in the current view, or in other words are
part of the group and as such are tracked by the membership service.

*replication_group_members*

Field                         Description

Channel_name                  The name of the Group Replication
                              channel.

Member_id                     The member server UUID.

Member_host                   The network address of the group member.

Member_port                   The MySQL connection port on which the
                              group member is listening.

Member_state                  The current state of the group member
                              (which can be 'ONLINE', 'ERROR',
                              'RECOVERING', 'OFFLINE' or
                              'UNREACHABLE').

For more information about the 'Member_host' value and its impact on the
distributed recovery process, see
group-replication-user-credentials.

17.3.3 Replication_connection_status
------------------------------------

When connected to a group, some fields in this table show information
regarding Group Replication.  For instance, the transactions that have
been received from the group and queued in the applier queue (the relay
log).

*replication_connection_status*

Field                         Description

Channel_name                  The name of the Group Replication
                              channel.

Group_name                    Shows the value of the name of the group.
                              It is always a valid UUID.

Source_UUID                   Shows the identifier for the group.  It
                              is similar to the group name and it is
                              used as the UUID for all the transactions
                              that are generated during group
                              replication.

Service_state                 Shows whether the member is a part of the
                              group or not.  The possible values of
                              service state can be {ON, OFF and
                              CONNECTING};

Received_transaction_set      Transactions in this GTID set have been
                              received by this member of the group.

17.3.4 Replication_applier_status
---------------------------------

The state of the Group Replication related channels and threads can be
observed using the regular replication_applier_status table as well.  If
there are many different worker threads applying transactions, then the
worker tables can also be used to monitor what each worker thread is
doing.

*replication_applier_status*

Field                         Description

Channel_name                  The name of the Group Replication
                              channel.

Service_state                 Shows whether the applier service is ON
                              or OFF.

Remaining_delay               Shows whether there is some applier delay
                              configured.

Count_transactions_retries    The number of retries performed while
                              applying a transaction.

Received_transaction_set      Transactions in this GTID set have been
                              received by this member of the group.

17.3.5 Group Replication Server States
--------------------------------------

The table 'replication_group_members' is updated whenever there is a
view change, for example when the configuration of the group is
dynamically changed.  At that point, servers exchange some of their
metadata to synchronize themselves and continue to cooperate together.

There are various states that a server instance can be in.  If servers
are communicating properly, all report the same states for all servers.
However, if there is a network partition, or a server leaves the group,
then different information may be reported, depending on which server is
queried.  Note that if the server has left the group then obviously it
cannot report updated information about other servers' state.  If there
is a partition, such that quorum is lost, servers are not able to
coordinate between themselves.  As a consequence, they cannot guess what
the status of different servers is.  Therefore, instead of guessing
their state they report that some servers are unreachable.

*Server State*

Field                       Description                          Group
                                                                 Synchronized

ONLINE                      The member is ready to serve as a    Yes
                            fully functional group member,
                            meaning that the client can
                            connect and start executing
                            transactions.

RECOVERING                  The member is in the process of      No
                            becoming an active member of the
                            group and is currently going
                            through the recovery process,
                            receiving state information from a
                            donor.

OFFLINE                     The plugin is loaded but the         No
                            member does not belong to any
                            group.

ERROR                       The state of the member.  Whenever   No
                            there is an error on the recovery
                            phase or while applying changes,
                            the server enters this state.

UNREACHABLE                 Whenever the local failure           No
                            detector suspects that a given
                            server is not reachable, because
                            maybe it has crashed or was
                            disconnected involuntarily, it
                            shows that server's state as
                            'unreachable'.

*Important*:

Once an instance enters 'ERROR' state, the 'super_read_only' option is
set to 'ON'.  To leave the 'ERROR' state you must manually configure the
instance with 'super_read_only=OFF'.

Note that Group Replication is _not_ synchronous, but eventually
synchronous.  More precisely, transactions are delivered to all group
members in the same order, but their execution is not synchronized,
meaning that after a transaction is accepted to be committed, each
member commits at its own pace.

17.4 Group Replication Operations
=================================

This section describes the different modes of deploying Group
Replication, explains common operations for managing groups and provides
information about how to tune your groups.

.

17.4.1 Deploying in Multi-Primary or Single-Primary Mode
--------------------------------------------------------

Group Replication operates in the following different modes:

   * single-primary mode

   * multi-primary mode

The default mode is single-primary.  It is not possible to have members
of the group deployed in different modes, for example one configured in
multi-primary mode while another one is in single-primary mode.  To
switch between modes, the group and not the server, needs to be
restarted with a different operating configuration.  Regardless of the
deployed mode, Group Replication does not handle client-side fail-over,
that must be handled by the application itself, a connector or a
middleware

framework such as a proxy or router.

When deployed in multi-primary mode, statements are checked to ensure
they are compatible with the mode.  The following checks are made when
Group Replication is deployed in multi-primary mode:

   * If a transaction is executed under the SERIALIZABLE isolation
     level, then its commit fails when synchronizing itself with the
     group.

   * If a transaction executes against a table that has foreign keys
     with cascading constraints, then the transaction fails to commit
     when synchronizing itself with the group.

These checks can be deactivated by setting the option
'group_replication_enforce_update_everywhere_checks' to 'FALSE'.  When
deploying in single-primary mode, this option _must_ be set to 'FALSE'.

17.4.1.1 Single-Primary Mode
............................

In this mode the group has a single-primary server that is set to
read-write mode.  All the other members in the group are set to
read-only mode (with 'super-read-only=ON'

).  This happens automatically.  The primary is typically the first
server to bootstrap the group, all other servers that join automatically
learn about the primary server and are set to read only.

FIGURE GOES HERE: New Primary Election

When in single-primary mode, some of the checks deployed in
multi-primary mode are disabled, because the system enforces that only a
single server writes to the group.  For example, changes to tables that
have cascading foreign keys are allowed, whereas in multi-primary mode
they are not.  Upon primary member failure, an automatic primary
election mechanism chooses the next primary member.  The method of
choosing the next primary depends on the server's 'server_uuid' variable
and the 'group_replication_member_weight' variable.

In the event that the primary member leaves a single-primary group, then
an election is performed and a new primary is chosen from the remaining
servers in the group.  This election is performed by looking at the new
view, and ordering the potential new primaries based on the value of
'group_replication_member_weight'.  Assuming the group is operating with
all members running the same MySQL version, then the member with the
highest value for 'group_replication_member_weight' is elected as the
new primary.  In the event that multiple servers have the same
'group_replication_member_weight', the servers are then prioritized
based on their 'server_uuid' in lexicographical order and by picking the
first one.  Once a new primary is elected, it is automatically set to
read-write and the other secondaries remain as secondaries, and as such,
read-only.

If the group is operating with members that are running different
versions of MySQL then the election process can be impacted.  For
example, if any member does not support
'group_replication_member_weight', then the primary is chosen based on
'server_uuid' order from the members of the lower major version.
Alternatively, if all members running different MySQL versions do
support 'group_replication_member_weight', the primary is chosen based
on 'group_replication_member_weight' from the members of the lower major
version.

It is a good practice to wait for the new primary to apply its
replication related relay-log before re-routing the client applications
to it.

17.4.1.2 Multi-Primary Mode
...........................

In multi-primary mode, there is no notion of a single primary.  There is
no need to engage an election procedure since there is no server playing
any special role.

FIGURE GOES HERE: Client Failover

All servers are set to read-write mode when joining the group.

17.4.1.3 Finding the Primary
............................

The following example shows how to find out which server is currently
the primary when deployed in single-primary mode.

     mysql> SELECT VARIABLE_VALUE FROM performance_schema.global_status WHERE VARIABLE_NAME= 'group_replication_primary_member';

17.4.2 Tuning Recovery
----------------------

Whenever a new member joins a replication group, it connects to a
suitable donor and fetches the data that it has missed up until the
point it is declared online.  This critical component in Group
Replication is fault tolerant and configurable.  The following section
explains how recovery works and how to tune the settings

*Donor Selection*

A random donor is selected from the existing online members in the
group.  This way there is a good chance that the same server is not
selected more than once when multiple members enter the group.

If the connection to the selected donor fails, a new connection is
automatically attempted to a new candidate donor.  Once the connection
retry limit is reached the recovery procedure terminates with an error.

*Note*:

A donor is picked randomly from the list of online members in the
current view.

*Enhanced Automatic Donor Switchover*

The other main point of concern in recovery as a whole is to make sure
that it copes with failures.  Hence, Group Replication provides robust
error detection mechanisms.  In earlier versions of Group Replication,
when reaching out to a donor, recovery could only detect connection
errors due to authentication issues or some other problem.  The reaction
to such problematic scenarios was to switch over to a new donor thus a
new connection attempt was made to a different member.

This behavior was extended to also cover other failure scenarios:

   * _Purged data scenarios_ - If the selected donor contains some
     purged data that is needed for the recovery process then an error
     occurs.  Recovery detects this error and a new donor is selected.

   * _Duplicated data_ - If a server joining the group already contains
     some data that conflicts with the data coming from the selected
     donor during recovery then an error occurs.  This could be caused
     by some errant transactions present in the server joining the
     group.

     One could argue that recovery should fail instead of switching over
     to another donor, but in heterogeneous groups there is chance that
     other members share the conflicting transactions and others do not.
     For that reason, upon error, recovery selects another donor from
     the group.

   * _Other errors_ - If any of the recovery threads fail (receiver or
     applier threads fail) then an error occurs and recovery switches
     over to a new donor.

*Note*:

In case of some persistent failures or even transient failures recovery
automatically retries connecting to the same or a new donor.

*Donor Connection Retries*

The recovery data transfer relies on the binary log and existing MySQL
replication framework, therefore it is possible that some transient
errors could cause errors in the receiver or applier threads.  In such
cases, the donor switch over process has retry functionality, similar to
that found in regular replication.

*Number of Attempts*

The number of attempts a server joining the group makes when trying to
connect to a donor from the pool of donors is 10.  This is configured
through the 'group_replication_recovery_retry_count' plugin variable .
The following command sets the maximum number of attempts to connect to
a donor to 10.

     mysql> SET GLOBAL group_replication_recovery_retry_count= 10;

Note that this accounts for the global number of attempts that the
server joining the group makes connecting to each one of the suitable
donors.

*Sleep Routines*

The 'group_replication_recovery_reconnect_interval' plugin variable
defines how much time the recovery process should sleep between donor
connection attempts.  This variable has its default set to 60 seconds
and you can change this value dynamically.  The following command sets
the recovery donor connection retry interval to 120 seconds.

     mysql> SET GLOBAL group_replication_recovery_reconnect_interval= 120;

Note, however, that recovery does not sleep after every donor connection
attempt.  As the server joining the group is connecting to different
servers and not to the same one over and over again, it can assume that
the problem that affects server A does not affect server B. As such,
recovery suspends only when it has gone through all the possible donors.
Once the server joining the group has tried to connect to all the
suitable donors in the group and none remains, the recovery process
sleeps for the number of seconds configured by the
'group_replication_recovery_reconnect_interval' variable.

17.4.3 Network Partitioning
---------------------------

The group needs to achieve consensus whenever a change that needs to be
replicated happens.  This is the case for regular transactions but is
also required for group membership changes and some internal messaging
that keeps the group consistent.  Consensus requires a majority of group
members to agree on a given decision.  When a majority of group members
is lost, the group is unable to progress and blocks because it cannot
secure majority or quorum.

Quorum may be lost when there are multiple involuntary failures, causing
a majority of servers to be removed abruptly from the group.  For
example in a group of 5 servers, if 3 of them become silent at once, the
majority is compromised and thus no quorum can be achieved.  In fact,
the remaining two are not able to tell if the other 3 servers have
crashed or whether a network partition has isolated these 2 alone and
therefore the group cannot be reconfigured automatically.

On the other hand, if servers exit the group voluntarily, they instruct
the group that it should reconfigure itself.  In practice, this means
that a server that is leaving tells others that it is going away.  This
means that other members can reconfigure the group properly, the
consistency of the membership is maintained and the majority is
recalculated.  For example, in the above scenario of 5 servers where 3
leave at once, if the 3 leaving servers warn the group that they are
leaving, one by one, then the membership is able to adjust itself from 5
to 2, and at the same time, securing quorum while that happens.

*Note*:

Loss of quorum is by itself a side-effect of bad planning.  Plan the
group size for the number of expected failures (regardless whether they
are consecutive, happen all at once or are sporadic).

The following sections explain what to do if the system partitions in
such a way that no quorum is automatically achieved by the servers in
the group.

*Tip*:

A primary that has been excluded from a group after a majority loss
followed by a reconfiguration can contain extra transactions that are
not included in the new group.  If this happens, the attempt to add back
the excluded member from the group results in an error with the message
'This member has more executed transactions than those present in the
group.'

*Detecting Partitions*

The 'replication_group_members' performance schema table presents the
status of each server in the current view from the perspective of this
server.  The majority of the time the system does not run into
partitioning, and therefore the table shows information that is
consistent across all servers in the group.  In other words, the status
of each server on this table is agreed by all in the current view.
However, if there is network partitioning, and quorum is lost, then the
table shows the status 'UNREACHABLE' for those servers that it cannot
contact.  This information is exported by the local failure detector
built into Group Replication.

FIGURE GOES HERE: Losing Quorum

To understand this type of network partition the following section
describes a scenario where there are initially 5 servers working
together correctly, and the changes that then happen to the group once
only 2 servers are online.  The scenario is depicted in the

figure.

As such, lets assume that there is a group with these 5 servers in it:

   * Server s1 with member identifier
     '199b2df7-4aaf-11e6-bb16-28b2bd168d07'

   * Server s2 with member identifier
     '199bb88e-4aaf-11e6-babe-28b2bd168d07'

   * Server s3 with member identifier
     '1999b9fb-4aaf-11e6-bb54-28b2bd168d07'

   * Server s4 with member identifier
     '19ab72fc-4aaf-11e6-bb51-28b2bd168d07'

   * Server s5 with member identifier
     '19b33846-4aaf-11e6-ba81-28b2bd168d07'

Initially the group is running fine and the servers are happily
communicating with each other.  You can verify this by logging into s1
and looking at its 'replication_group_members' performance schema table.
For example:

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | group_replication_applier | 1999b9fb-4aaf-11e6-bb54-28b2bd168d07 | 127.0.0.1   |       13002 | ONLINE       |
     | group_replication_applier | 199b2df7-4aaf-11e6-bb16-28b2bd168d07 | 127.0.0.1   |       13001 | ONLINE       |
     | group_replication_applier | 199bb88e-4aaf-11e6-babe-28b2bd168d07 | 127.0.0.1   |       13000 | ONLINE       |
     | group_replication_applier | 19ab72fc-4aaf-11e6-bb51-28b2bd168d07 | 127.0.0.1   |       13003 | ONLINE       |
     | group_replication_applier | 19b33846-4aaf-11e6-ba81-28b2bd168d07 | 127.0.0.1   |       13004 | ONLINE       |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+

However, moments later there is a catastrophic failure and servers s3,
s4 and s5 stop unexpectedly.  A few seconds after this, looking again at
the 'replication_group_members' table on s1 shows that it is still
online, but several others members are not.  In fact, as seen below they
are marked as 'UNREACHABLE'.  Moreover, the system could not reconfigure
itself to change the membership, because the majority has been lost.

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | group_replication_applier | 1999b9fb-4aaf-11e6-bb54-28b2bd168d07 | 127.0.0.1   |       13002 | UNREACHABLE  |
     | group_replication_applier | 199b2df7-4aaf-11e6-bb16-28b2bd168d07 | 127.0.0.1   |       13001 | ONLINE       |
     | group_replication_applier | 199bb88e-4aaf-11e6-babe-28b2bd168d07 | 127.0.0.1   |       13000 | ONLINE       |
     | group_replication_applier | 19ab72fc-4aaf-11e6-bb51-28b2bd168d07 | 127.0.0.1   |       13003 | UNREACHABLE  |
     | group_replication_applier | 19b33846-4aaf-11e6-ba81-28b2bd168d07 | 127.0.0.1   |       13004 | UNREACHABLE  |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+

The table shows that s1 is now in a group that has no means of
progressing without external intervention, because a majority of the
servers are unreachable.  In this particular case, the group membership
list needs to be reset to allow the system to proceed, which is
explained in this section.  Alternatively, you could also choose to stop
Group Replication on s1 and s2 (or stop completely s1 and s2), figure
out what happened with s3, s4 and s5 and then restart Group Replication
(or the servers).

*Unblocking a Partition*

Group replication enables you to reset the group membership list by
forcing a specific configuration.  For instance in the case above, where
s1 and s2 are the only servers online, you could chose to force a
membership configuration consisting of only s1 and s2.  This requires
checking some information about s1 and s2 and then using the
'group_replication_force_members' variable.

FIGURE GOES HERE: Forcing a New Membership

Suppose that you are back in the situation where s1 and s2 are the only
servers left in the group.  Servers s3, s4 and s5 have left the group
unexpectedly.  To make servers s1 and s2 continue, you want to force a
membership configuration that contains only s1 and s2.

*Warning*:

This procedure uses 'group_replication_force_members' and should be
considered a last resort remedy.  It _must_ be used with extreme care
and only for overriding loss of quorum.  If misused, it could create an
artificial split-brain scenario or block the entire system altogether.

Recall that the system is blocked and the current configuration is the
following (as perceived by the local failure detector on s1):

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | group_replication_applier | 1999b9fb-4aaf-11e6-bb54-28b2bd168d07 | 127.0.0.1   |       13002 | UNREACHABLE  |
     | group_replication_applier | 199b2df7-4aaf-11e6-bb16-28b2bd168d07 | 127.0.0.1   |       13001 | ONLINE       |
     | group_replication_applier | 199bb88e-4aaf-11e6-babe-28b2bd168d07 | 127.0.0.1   |       13000 | ONLINE       |
     | group_replication_applier | 19ab72fc-4aaf-11e6-bb51-28b2bd168d07 | 127.0.0.1   |       13003 | UNREACHABLE  |
     | group_replication_applier | 19b33846-4aaf-11e6-ba81-28b2bd168d07 | 127.0.0.1   |       13004 | UNREACHABLE  |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+

The first thing to do is to check what is the peer address (group
communication identifier) for s1 and s2.  Log in to s1 and s2 and get
that information as follows.

     mysql> SELECT @@group_replication_local_address;
     +-----------------------------------+
     | @@group_replication_local_address |
     +-----------------------------------+
     | 127.0.0.1:10000                   |
     +-----------------------------------+

Then log in to s2 and do the same thing:

     mysql> SELECT @@group_replication_local_address;
     +-----------------------------------+
     | @@group_replication_local_address |
     +-----------------------------------+
     | 127.0.0.1:10001                   |
     +-----------------------------------+

Once you know the group communication addresses of s1
('127.0.0.1:10000') and s2 ('127.0.0.1:10001'), you can use that on one
of the two servers to inject a new membership configuration, thus
overriding the existing one that has lost quorum.  To do that on s1:

     mysql> SET GLOBAL group_replication_force_members="127.0.0.1:10000,127.0.0.1:10001";

This unblocks the group by forcing a different configuration.  Check
'replication_group_members' on both s1 and s2 to verify the group
membership after this change.  First on s1.

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | group_replication_applier | b5ffe505-4ab6-11e6-b04b-28b2bd168d07 | 127.0.0.1   |       13000 | ONLINE       |
     | group_replication_applier | b60907e7-4ab6-11e6-afb7-28b2bd168d07 | 127.0.0.1   |       13001 | ONLINE       |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+

And then on s2.

     mysql> SELECT * FROM performance_schema.replication_group_members;
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | CHANNEL_NAME              | MEMBER_ID                            | MEMBER_HOST | MEMBER_PORT | MEMBER_STATE |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+
     | group_replication_applier | b5ffe505-4ab6-11e6-b04b-28b2bd168d07 | 127.0.0.1   |       13000 | ONLINE       |
     | group_replication_applier | b60907e7-4ab6-11e6-afb7-28b2bd168d07 | 127.0.0.1   |       13001 | ONLINE       |
     +---------------------------+--------------------------------------+-------------+-------------+--------------+

When forcing a new membership configuration, make sure that any servers
are going to be forced out of the group are indeed stopped.  In the
scenario depicted above, if s3, s4 and s5 are not really unreachable but
instead are online, they may have formed their own functional partition
(they are 3 out of 5, hence they have the majority).  In that case,
forcing a group membership list with s1 and s2 could create an
artificial split-brain situation.  Therefore it is important before
forcing a new membership configuration to ensure that the servers to be
excluded are indeed shutdown and if they are not, shut them down before
proceeding.

17.4.4 Using MySQL Enterprise Backup with Group Replication
-----------------------------------------------------------

This section explains how to back up and subsequently restore a Group
Replication member using MySQL Enterprise Backup; the same technique can
be used to quickly add a new member to a group.  Generally, backing up a
Group Replication member is no different to backing up a stand-alone
MySQL instance.  The recommended process is to use MySQL Enterprise
Backup image backups and a subsequent restore, for more information see
Backup Operations
(http://dev.mysql.com/doc/mysql-enterprise-backup/4.1/en/backup-commands-backup.html).

The required steps can be summarized as:

   * Use MySQL Enterprise Backup to create a backup of the source server
     instance with simple timestamps.

   * Copy the backup to the destination server instance.

   * Use MySQL Enterprise Backup to restore the backup to the
     destination server instance.

The following procedure demonstrates this process.  Consider the
following group:

     mysql> SELECT * member_host, member_port, member_state FROM performance_schema.replication_group_members;
     +-------------+-------------+--------------+
     | member_host | member_port | member_state |
     +-------------+-------------+--------------+
     | node1       |        3306 | ONLINE       |
     | node2       |        3306 | ONLINE       |
     | node3       |        3306 | ONLINE       |
     +-------------+-------------+--------------+

In this example the group is operating in single-primary mode and the
primary group member is 'node1'.  This means that 'node2' and 'node3'
are secondaries, operating in read-only mode ('super_read_only=ON').
Using MySQL Enterprise Backup, a recent backup has been taken of 'node2'
by issuing:

     mysqlbackup --defaults-file=/etc/my.cnf --backup-image=/backups/my.mbi_`date +%d%m_%H%M` /
     		      --backup-dir=/backups/backup_'date +%d%m_%H%M' --user=root -pmYsecr3t /
     		      --host=127.0.0.1 --no-history-logging backup-to-image

The '--no-history-logging' option is used because 'node2' is a
secondary, and because it is read-only MySQL Enterprise Backup cannot
write status and metadata tables to the instance.

Assume that the primary member, 'node1', encounters irreconcilable
corruption.  After a period of time the server instance is rebuilt but
all the data on the member was lost.  The most recent backup of member
'node2' can be used to rebuild 'node1'.  This requires copying the
backup files from 'node2' to 'node1' and then using MySQL Enterprise
Backup to restore the backup to 'node1'.  The exact way you copy the
backup files depends on the operating system and tools available to you.
In this example we assume Linux servers and use SCP to copy the files
between servers:

     node2/backups # scp my.mbi_2206_1429 node1:/backups

Connect to the destination server, in this case 'node1', and restore the
backup using MySQL Enterprise Backup by issuing:

     mysqlbackup --defaults-file=/etc/my.cnf --backup-image=/backups/`ls -1rt /backups|tail /
     		      -n 1` --backup-dir=/tmp/restore_`date +%d%m_%H%M` copy-back-and-apply-log

The backup is restored to the destination server.

If your group is using multi-primary mode, extra care must be taken to
prevent writes to the database during the MySQL Enterprise Backup
restore stage and the Group Replication recovery phase.  Depending on
how the group is accessed by clients, there is a possibility of DML
being executed on the newly joined instance the moment it is accessible
on the network, even prior to applying the binary log before rejoining
the group.  To avoid this, configure the member's option file with:

     group_replication_start_on_boot=OFF
     super_read_only=ON
     event_scheduler=OFF

This ensures that Group Replication is not started on boot, that the
member defaults to read-only and that the event_scheduler is turned off
while the member catches up with the group during the recovery phase.
Adequate error handling must be configured on the clients to recognise
that they are, temporarily, prevented from performing DML during this
period.

Start the server instance and connect an SQL client.  The restored
backup has old binary log files and related metadata that are specific
to the instance that was backed up.  To reset all of that issue:

     mysql> RESET MASTER;

The restored backup has the relay log files associated with the source
instance, in this case 'node2'.  Therefore reset the logs, metadata, and
configuration for all replication channels by issuing:

     mysql> RESET SLAVE ALL;

For the restored instance to be able to be able to recover automatically
using Group Replication's built-in distributed recovery (see
group-replication-distributed-recovery), configure the 'gtid_executed'
variable.  The MySQL Enterprise Backup backup from 'node2' includes the
'backup_gtid_executed.sql' file, usually at the path 'DATADIR/meta/',
which contains the information required to configure 'node1'.  Disable
binary logging and then use this file to configure the 'gtid_executed'
variable by issuing:

     mysql> SET SQL_LOG_BIN=OFF;
     mysql> SOURCE DATADIR/meta/backup_gtid_executed.sql
     mysql> SET SQL_LOG_BIN=ON;

Configure the group-replication-user-credentials and start Group
Replication, for example:

     mysql> CHANGE MASTER TO MASTER_USER='RPL_USER', MASTER_PASSWORD='PASSWORD' /
     		FOR CHANNEL 'group_replication_recovery';
     mysql> START GROUP_REPLICATION;

The instance attempts to join the group, executing the restored binary
logs from the correct location.  Once the instance gains synchrony with
the group, it joins as a secondary, with 'super_read_only=ON'.  Reset
the temporary configuration changes made during the restore.  Turn the
event scheduler back on in the running process:

     mysql> SET global event_scheduler=ON;

Edit the following system variables in the instance's option file:

     group_replication_start_on_boot=ON
     super_read_only=ON
     event_scheduler=ON

17.5 Group Replication Security
===============================

This section explains how to secure a group, securing the connections
between members of a group, or by establishing a security perimeter
using address whitelisting.

17.5.1 IP Address Whitelisting
------------------------------

The Group Replication plugin has a configuration option to determine
from which hosts an incoming Group Communication connection can be
accepted.  This option is called 'group_replication_ip_whitelist'.  If
you set this option on a server s1, then when server s2 is establishing
a connection to s1 for the purpose of engaging group communication, then
s1 first checks the whitelist before accepting the connection from s2.
If s2 is in the whitelist, then s1 accepts the connection, otherwise s1
rejects the connection attempt by s2.

If you do not specify a whitelist explicitly, the server automatically
sets the whitelist to the private networks that the server has an
interface on.  This means that a server, even if it has interfaces on
public IPs, does not by default allow connections from external hosts.

Whenever the IP whitelist is set to AUTOMATIC, an entry is added in the
error log, similar to:

     2017-10-07T06:40:49.320686Z 4 [Note] Plugin group_replication reported: '[GCS] Added automatically IP ranges 192.0.2.21/24,198.51.100.44,203.0.113.0/24,127.0.0.1/32 to the whitelist'

You can improve the security of the group further by manually setting
the list of hosts that are permitted to use group communication
connections.  You can specify host names (from MySQL 5.7.21), simple IP
addresses, or CIDR notation, in any combination.  A comma must separate
each entry.  For example:

     mysql> STOP GROUP_REPLICATION;
     mysql> SET GLOBAL group_replication_ip_whitelist="192.0.2.21/24,198.51.100.44,203.0.113.0/24,example.org,www.example.com/24";
     mysql> START GROUP_REPLICATION;

The localhost IP address (127.0.0.1) is always added to the whitelist.
If not explicitly, it is implicitly and automatically added.  IPv6
addresses, and host names that resolve to IPv6 addresses, are not
supported.

For host names, name resolution takes place only when a connection
request is made by another server.  A host name that cannot be resolved
is not considered for whitelist validation, and a warning message is
written to the error log.  Forward-confirmed reverse DNS (FCrDNS)
verification is carried out for resolved host names.

*Warning*:

Host names are inherently less secure than IP addresses in a whitelist.
FCrDNS verification provides a good level of protection, but can be
compromised by certain types of attack.  Specify host names in your
whitelist only when strictly necessary, and ensure that all components
used for name resolution, such as DNS servers, are maintained under your
control.  You can also implement name resolution locally using the hosts
file, to avoid the use of external components.

To join a replication group, a server only needs to be whitelisted on
the seed member to which it makes the request to join the group.
Typically, this would be the bootstrap member for the replication group,
but it can be any of the servers listed by the
'--loose-group_replication_group_seeds' option in the configuration for
the server joining the group.  However, note that when the replication
group is reconfigured, the group members re-establish connections
between themselves.  If a group member is only whitelisted by servers
that are no longer part of the replication group after the
reconfiguration, it is unable to reconnect to the remaining servers in
the replication group that do not whitelist it.  To avoid this scenario
entirely, specify the same whitelist for all servers that are members of
the replication group.

*Note*:

It is possible to configure different whitelists on different group
members according to your security requirements, for example, in order
to keep different subnets separate.  If you need to configure different
whitelists to meet your security requirements, ensure that there is
sufficient overlap between the whitelists in the replication group to
maximize the possibility of servers being able to reconnect in the
absence of their original seed member.

17.5.2 Secure Socket Layer Support (SSL)
----------------------------------------

MySQL Group Replication supports both OpenSSL and yaSSL builds of MySQL
Server.

Group communication connections as well as recovery connections, are
secured using SSL. The following sections explain how to configure
connections.

*Configuring SSL for Recovery*

Recovery is performed through a regular asynchronous replication
connection.  Once the donor is selected, the server joining the group
establishes an asynchronous replication connection.  This is all
automatic.

However, a user that requires an SSL connection must have been created
before the server joining the group connects to the donor.  Typically,
this is set up at the time one is provisioning a server to join the
group.

     donor> SET SQL_LOG_BIN=0;
     donor> CREATE USER 'rec_ssl_user'@'%' REQUIRE SSL;
     donor> GRANT replication slave ON *.* TO 'rec_ssl_user'@'%';
     donor> SET SQL_LOG_BIN=1;

Assuming that all servers already in the group have a replication user
set up to use SSL, you configure the server joining the group to use
those credentials when connecting to the donor.  That is done according
to the values of the SSL options provided for the Group Replication
plugin.

     new_member> SET GLOBAL group_replication_recovery_use_ssl=1;
     new_member> SET GLOBAL group_replication_recovery_ssl_ca= '.../cacert.pem';
     new_member> SET GLOBAL group_replication_recovery_ssl_cert= '.../client-cert.pem';
     new_member> SET GLOBAL group_replication_recovery_ssl_key= '.../client-key.pem';

And by configuring the recovery channel to use the credentials of the
user that requires an SSL connection.

     new_member> CHANGE MASTER TO MASTER_USER="rec_ssl_user" FOR CHANNEL "group_replication_recovery";
     new_member> START GROUP_REPLICATION;

*Configuring SSL for Group Communication*

Secure sockets can be used to establish communication between members in
a group.  The configuration for this depends on the server's SSL
configuration.  As such, if the server has SSL configured, the Group
Replication plugin also has SSL configured.  For more information on the
options for configuring the server SSL, see
encrypted-connection-options.  The options which configure Group
Replication are shown in the following table.

*SSL Options*

ServerPlugin
ConfigurationConfiguration
 Description

ssl_keyPath
 of
 key
 file.
 To
 be
 used
 as
 client
 and
 server
 certificate.

ssl_certPath
 of
 certificate
 file.
 To
 be
 used
 as
 client
 and
 server
 certificate.

ssl_caPath
 of
 file
 with
 SSL
 Certificate
 Authorities
 that
 are
 trusted.

ssl_capathPath
 of
 directory
 containing
 certificates
 for
 SSL
 Certificate
 Authorities
 that
 are
 trusted.

ssl_crlPath
 of
 file
 containing
 the
 certificate
 revocation
 lists.

ssl_crlpathPath
 of
 directory
 containing
 revoked
 certificate
 lists.

ssl_cipherPermitted
 ciphers
 to
 use
 while
 encrypting
 data
 over
 the
 connection.

tls_versionSecure
 communication
 will
 use
 this
 version
 and
 its
 protocols.

These options are MySQL Server configuration options which Group
Replication relies on for its configuration.  In addition there is the
following Group Replication specific option to configure SSL on the
plugin itself.

   * 'group_replication_ssl_mode' - specifies the security state of the
     connection between Group Replication members.

*group_replication_ssl_mode configuration values*

ValueDescription

_DISABLED_Establish
 an
 unencrypted
 connection
 (_default_).

REQUIREDEstablish
 a
 secure
 connection
 if
 the
 server
 supports
 secure
 connections.

VERIFY_CALike
 REQUIRED,
 but
 additionally
 verify
 the
 server
 TLS
 certificate
 against
 the
 configured
 Certificate
 Authority
 (CA)
 certificates.

VERIFY_IDENTITYLike
 VERIFY_CA,
 but
 additionally
 verify
 that
 the
 server
 certificate
 matches
 the
 host
 to
 which
 the
 connection
 is
 attempted.

The following example shows an example my.cnf file section used to
configure SSL on a server and how activate it for Group Replication.

     [mysqld]
     ssl_ca = "cacert.pem"
     ssl_capath = "/.../ca_directory"
     ssl_cert = "server-cert.pem"
     ssl_cipher = "DHE-RSA-AEs256-SHA"
     ssl_crl = "crl-server-revoked.crl"
     ssl_crlpath = "/.../crl_directory"
     ssl_key = "server-key.pem"
     group_replication_ssl_mode= REQUIRED

The only plugin specific configuration option that is listed is
'group_replication_ssl_mode'.  This option activates the SSL
communication between members of the group, by configuring the SSL
framework with the 'ssl_*' parameters that are provided to the server.

17.5.3 Virtual Private Networks (VPN)
-------------------------------------

There is nothing preventing Group Replication from operating over a
virtual private network.  At its core, it just relies on an IPv4 socket
to establish connections between servers for the purpose of propagating
messages between them.

17.6 Group Replication System Variables
=======================================

These are the system variables that are specific to the Group
Replication plugin.  Every configuration option is prefixed with
"group_replication".

*Important*:

Although most variables are described as dynamic and can be changed
while the server is running, most changes only take effect upon
restarting the Group Replication plugin.  Variables which can be changed
without requiring a restart of the plugin are specifically noted as such
in this section.

   *
     'group_replication_allow_local_disjoint_gtids_join'

     Property                             Value

     *Command-Line Format*                '--group-replication-allow-local-disjoint-gtids-join=value'

     *Introduced*                         5.7.17

     *Deprecated*                         5.7.21

     *System Variable*                    'group_replication_allow_local_disjoint_gtids_join'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Deprecated in version 5.7.21 and scheduled for removal in a future
     version.  Allow the current server to join the group even if it has
     transactions not present in the group.

     *Warning*:

     Use caution when enabling this option as incorrect usage could lead
     to inconsistencies in the group.

   *
     'group_replication_allow_local_lower_version_join'

     Property                             Value

     *Command-Line Format*                '--group-replication-allow-local-lower-version-join=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_allow_local_lower_version_join'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Allow the current server to join the group even if it has a lower
     plugin version than the group.

   *
     'group_replication_auto_increment_increment'

     Property                             Value

     *Command-Line Format*                '--group-replication-auto-increment-increment=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_auto_increment_increment'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '7'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     Determines the interval between successive column values for
     transactions that execute on this server instance.

   *
     'group_replication_bootstrap_group'

     Property                             Value

     *Command-Line Format*                '--group-replication-bootstrap-group=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_bootstrap_group'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Configure this server to bootstrap the group.  This option must
     only be set on one server and only when starting the group for the
     first time or restarting the entire group.  After the group has
     been bootstrapped, set this option to 'OFF'.  It should be set to
     'OFF' both dynamically and in the configuration files.  Starting
     two servers or restarting one server with this option set while the
     group is running may lead to an artificial split brain situation,
     where two independent groups with the same name are bootstrapped.

   *
     'group_replication_components_stop_timeout'

     Property                             Value

     *Command-Line Format*                '--group-replication-components-stop-timeout=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_components_stop_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '31536000'

     Timeout, in seconds, that Group Replication waits for each of the
     components when shutting down.

   *
     'group_replication_compression_threshold'

     Property                             Value

     *Command-Line Format*                '--group-replication-compression-threshold=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_compression_threshold'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1000000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967296'

     The value in bytes above which (LZ4) compression is enforced.  When
     set to zero, deactivates compression.

   *
     'group_replication_enforce_update_everywhere_checks'

     Property                             Value

     *Command-Line Format*                '--group-replication-enforce-update-everywhere-checks=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_enforce_update_everywhere_checks'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Enable or disable strict consistency checks for multi-primary
     update everywhere.

   *
     'group_replication_flow_control_applier_threshold'

     Property                             Value

     *Command-Line Format*                '--group-replication-flow-control-applier-threshold=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_flow_control_applier_threshold'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '25000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '2147483648'

     Specifies the number of waiting transactions in the applier queue
     that trigger flow control.  This variable can be changed without
     resetting Group Replication.

   *
     'group_replication_flow_control_certifier_threshold'

     Property                             Value

     *Command-Line Format*                '--group-replication-flow-control-certifier-threshold=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_flow_control_certifier_threshold'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '25000'

     *Minimum Value*                      '0'

     *Maximum Value*                      '2147483648'

     Specifies the number of waiting transactions in the certifier queue
     that trigger flow control.  This variable can be changed without
     resetting Group Replication.

   *
     'group_replication_flow_control_mode'

     Property                             Value

     *Command-Line Format*                '--group-replication-flow-control-mode=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_flow_control_mode'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'QUOTA'

     *Valid Values*                       'DISABLED' 'QUOTA'

     Specifies the mode used for flow control.  This variable can be
     changed without resetting Group Replication.

   *
     'group_replication_force_members'

     Property                             Value

     *Command-Line Format*                '--group-replication-force-members=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_force_members'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     A list of peer addresses as a comma separated list such as
     'host1:port1','host2:port2'.  This option is used to force a new
     group membership, in which the excluded members do not receive a
     new view and are blocked.  You need to manually kill the excluded
     servers.  Any invalid host names in the list could cause subsequent
     'START GROUP_REPLICATION'.
     statements to fail because they could block group membership.

   *
     'group_replication_group_name'

     Property                             Value

     *Command-Line Format*                '--group-replication-group-name=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_group_name'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The name of the group which this server instance belongs to.  Must
     be a valid UUID.

   *
     'group_replication_group_seeds'

     Property                             Value

     *Command-Line Format*                '--group-replication-group-seeds=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_group_seeds'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     A list of group members that provide a member which joins the group
     with the data required for the joining member to gain synchrony
     with the group.  The list consists of the seed member's network
     addresses specified as a comma separated list, such as
     'host1:port1','host2:port2'.  Ususally this list consists of all
     members of the group, but you can choose a subset of the group
     members to be seeds.  The list must contain at least one valid
     member address.  Each address is validated when starting Group
     Replication.  If the list does not contain any valid host names,
     issuing 'START GROUP_REPLICATION'.
     fails.

   *
     'group_replication_ip_whitelist'

     Property                             Value

     *Command-Line Format*                '--group-replication-ip-whitelist=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_ip_whitelist'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     *Default Value*                      'AUTOMATIC'

     Specifies which hosts are permitted to connect to the group.  By
     default, this system variable is set to 'AUTOMATIC', which permits
     connections from private subnetworks active on the host.  Active
     interfaces on the host are scanned and those with addresses on
     private subnetworks are automatically added to the permitted list.

     Alternatively, you can specify a whitelist of permitted hosts as a
     comma separated list of IPv4 addresses, subnet CIDR notation, or
     (from MySQL 5.7.21) host names, in any combination.  For example:

          192.0.2.22,198.51.100.0/24,example.org,www.example.com/24

     Address 127.0.0.1 is always permitted to connect, even when not
     specified explicitly.  IPv6 addresses, and host names that resolve
     to IPv6 addresses, are not supported.

     For host names, name resolution takes place only when a connection
     request is made by another server.  A host name that cannot be
     resolved is not considered for whitelist validation, and a warning
     message is written to the error log.  Forward-confirmed reverse DNS
     (FCrDNS) verification is carried out for resolved host names.

     *Warning*:

     Host names are inherently less secure than IP addresses in a
     whitelist.  FCrDNS verification provides a good level of
     protection, but can be compromised by certain types of attack.
     Specify host names in your whitelist only when strictly necessary,
     and ensure that all components used for name resolution, such as
     DNS servers, are maintained under your control.  You can also
     implement name resolution locally using the hosts file, to avoid
     the use of external components.

   *
     'group_replication_local_address'

     Property                             Value

     *Command-Line Format*                '--group-replication-local-address=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_local_address'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The network address which the member provides for connections from
     other members, specified as a 'host:port' formatted string.  This
     address must be reachable by all members of the group because it is
     used by XCOM, the internal group communication system.

     *Warning*:

     Do not use this address for communication with the member.

     Other Group Replication members contact this member through this
     'host:port' for all internal group communication.  This is not the
     MySQL server SQL protocol host and port.

   *
     'group_replication_member_weight'

     Property                             Value

     *Command-Line Format*                '--group-replication-member-weight=value'

     *Introduced*                         5.7.20

     *System Variable*                    'group_replication_member_weight'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '50'

     *Minimum Value*                      '0'

     *Maximum Value*                      '100'

     A percentage weight that can be assigned to members to influence
     the chance of the member being elected as primary in the event of
     failover, for example when the existing primary leaves a
     single-primary group.  Assign numeric weights to members to ensure
     that specific members are elected, for example during scheduled
     maintenance of the primary or to ensure certain hardware is
     prioritized in the event of failover.

     For a group with members configured as follows:

        * 'member-1': group_replication_member_weight=30,
          server_uuid=aaaa

        * 'member-2': group_replication_member_weight=40,
          server_uuid=bbbb

        * 'member-3': group_replication_member_weight=40,
          server_uuid=cccc

        * 'member-4': group_replication_member_weight=40,
          server_uuid=dddd

     during election of a new primary the members above would be sorted
     as 'member-2', 'member-3', 'member-4', and 'member-1'.  This
     results in 'member'-2 being chosen as the new primary in the event
     of failover.  For more information, see
     group-replication-single-primary-mode.

   *
     'group_replication_poll_spin_loops'

     Property                             Value

     *Command-Line Format*                '--group-replication-poll-spin-loops=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_poll_spin_loops'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '0'

     *Default Value* (32-bit platforms)   '0'

     *Minimum Value* (64-bit platforms)   '0'

     *Minimum Value* (32-bit platforms)   '0'

     *Maximum Value* (64-bit platforms)   '18446744073709547520'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The number of times the group communication thread waits for the
     communication engine mutex to be released before the thread waits
     for more incoming network messages.

   *
     'group_replication_recovery_retry_count'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-retry-count=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_retry_count'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '10'

     *Minimum Value*                      '0'

     *Maximum Value*                      '31536000'

     The number of times that the member that is joining tries to
     connect to the available donors before giving up.

   *
     'group_replication_recovery_reconnect_interval'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-reconnect-interval=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_reconnect_interval'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '60'

     *Minimum Value*                      '0'

     *Maximum Value*                      '0'

     The sleep time, in seconds, between reconnection attempts when no
     donor was found in the group.

   *
     'group_replication_recovery_use_ssl'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-use-ssl=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_use_ssl'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Whether Group Replication recovery connection should use SSL or
     not.

   *
     'group_replication_recovery_ssl_ca'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-ca=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_ca'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The path to a file that contains a list of trusted SSL certificate
     authorities.

   *
     'group_replication_recovery_ssl_capath'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-capath=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_capath'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The path to a directory that contains trusted SSL certificate
     authority certificates.

   *
     'group_replication_recovery_ssl_cert'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-cert=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_cert'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The name of the SSL certificate file to use for establishing a
     secure connection.

   *
     'group_replication_recovery_ssl_key'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-key=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_key'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The name of the SSL key file to use for establishing a secure
     connection.

   *
     'group_replication_recovery_ssl_cipher'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-cipher=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_cipher'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The list of permitted ciphers for SSL encryption.

   *
     'group_replication_recovery_ssl_crl'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-crl=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_crl'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The path to a directory that contains files containing certificate
     revocation lists.

   *
     'group_replication_recovery_ssl_crlpath'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-crlpath=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_crlpath'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               string

     The path to a directory that contains files containing certificate
     revocation lists.

   *
     'group_replication_recovery_ssl_verify_server_cert'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-ssl-verify-server-cert=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_ssl_verify_server_cert'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'OFF'

     Make the recovery process check the server's Common Name value in
     the donor sent certificate.

   *
     'group_replication_recovery_complete_at'

     Property                             Value

     *Command-Line Format*                '--group-replication-recovery-complete-at=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_recovery_complete_at'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'TRANSACTIONS_APPLIED'

     *Valid Values*                       'TRANSACTIONS_CERTIFIED'
                                          'TRANSACTIONS_APPLIED'

     Recovery policies when handling cached transactions after state
     transfer.  This option specifies whether a member is marked online
     after it has received all transactions that it missed before it
     joined the group ('TRANSACTIONS_CERTIFIED') or after it has
     received and applied them ('TRANSACTIONS_APPLIED').

   *
     'group_replication_gtid_assignment_block_size'

     Property                             Value

     *Command-Line Format*                '--group-replication-gtid-assignment-block-size=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_gtid_assignment_block_size'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (64-bit platforms)            integer

     *Type* (32-bit platforms)            integer

     *Default Value* (64-bit platforms)   '1000000'

     *Default Value* (32-bit platforms)   '1000000'

     *Minimum Value* (64-bit platforms)   '1'

     *Minimum Value* (32-bit platforms)   '1'

     *Maximum Value* (64-bit platforms)   '18446744073709547520'

     *Maximum Value* (32-bit platforms)   '4294967295'

     The number of consecutive GTIDs that are reserved for each member.
     Each member consumes its blocks and reserves more when needed.

   *
     'group_replication_single_primary_mode'

     Property                             Value

     *Command-Line Format*                '--group-replication-single-primary-mode=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_single_primary_mode'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Instructs the group to automatically pick a single server to be the
     one that handles read/write workload.  This server is the PRIMARY
     and all others are SECONDARIES.

   *
     'group_replication_ssl_mode'

     Property                             Value

     *Command-Line Format*                '--group-replication-ssl-mode=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_ssl_mode'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               enumeration

     *Default Value*                      'DISABLED'

     *Valid Values*                       'DISABLED' 'REQUIRED' 'VERIFY_CA'
                                          'VERIFY_IDENTITY'

     Specifies the security state of the connection between Group
     Replication members.

   *
     'group_replication_start_on_boot'

     Property                             Value

     *Command-Line Format*                '--group-replication-start-on-boot=value'

     *Introduced*                         5.7.17

     *System Variable*                    'group_replication_start_on_boot'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               boolean

     *Default Value*                      'ON'

     Whether the server should start Group Replication or not during
     server start.

   *
     'group_replication_transaction_size_limit'

     Property                             Value

     *Command-Line Format*                '--group-replication-transaction-size-limit=value'

     *Introduced*                         5.7.19

     *System Variable*                    'group_replication_transaction_size_limit'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type* (>= 5.7.19)                   integer

     *Default Value* (>= 5.7.19)          '0'

     *Minimum Value* (>= 5.7.19)          '0'

     *Maximum Value* (>= 5.7.19)          '2147483647'

     Configures the maximum transaction size in bytes which the group
     accepts.  Transactions larger than this size are rolled back.  Use
     this option to avoid large transactions causing the group to fail.
     A large transaction can cause problems for a group, either in terms
     of memory allocation or network bandwidth consumption, which may
     cause the failure detector to trigger because a given member is
     unreachable while it is busy processing the large transaction.
     When set to 0 there is no limit to the size of transactions the
     group accepts, and there may be the risk of large transactions
     causing the group to fail.  Adjust the value of this variable
     depending on the size of workload you require from the group.

   *
     'group_replication_unreachable_majority_timeout'

     Property                             Value

     *Command-Line Format*                '--group-replication-unreachable-majority-timeout=value'

     *Introduced*                         5.7.19

     *System Variable*                    'group_replication_unreachable_majority_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '31536000'

     Configures how long members that suffer a network partition and
     cannot connect to the majority wait before leaving the group.  By
     default set to 0, which means that members that find themselves in
     a minority due to a network partition wait forever to connect the
     group.  In a group of 5 servers (S1,S2,S3,S4,S5), if there is a
     disconnection between (S1,S2) and (S3,S4,S5) there is a network
     partition.  The first group (S1,S2) is now in a minority because it
     cannot contact more than half of the group.  While the majority
     group (S3,S4,S5) remains running, the minority group waits forever
     for a network reconnection.  Any transactions processed by the
     minority group are blocked until Group Replication is stopped using
     'STOP GROUP REPLICATION' on the
     members of the minority.

     If configured to a number of seconds, members wait for this amount
     of time after losing contact with the majority of members before
     leaving the group.  All pending transactions processed by the
     minority are rolled back and the servers in the minority partition
     move to the 'ERROR' state and set themselves to
     'super_read_only=ON' mode.

     *Warning*:

     When you have a symmetric group, with just two members for example
     (S0,S2), if there is a network partition and there is no majority,
     after the configured timeout all members shut down and enter
     'ERROR' state.

17.7 Requirements and Limitations
=================================

This section lists and explains the requirements and limitations of
Group Replication.

17.7.1 Group Replication Requirements
-------------------------------------

Server instances that you want to use for Group Replication must satisfy
the following requirements.

*Infrastructure*

   * InnoDB Storage Engine

     Data must be stored in the 'InnoDB'.
     transactional storage engine.  Transactions are executed
     optimistically and then, at commit time, are checked for conflicts.
     If there are conflicts, in order to maintain consistency across the
     group, some transactions are rolled back.  This means that a
     transactional storage engine is required.  Moreover, see
     'InnoDB' provides some additional
     functionality that enables better management and handling of
     conflicts when operating together with Group Replication.

   * Primary Keys

     Every table that is to be replicated by the group must have a
     defined primary key, or primary key equivalent where the equivalent
     is a non-null unique key.  Such keys are required as a unique
     identifier for every row within a table, enabling the system to
     determine which transactions conflict by identifying exactly which
     rows each transaction has modified.

   * IPv4 Network

     The group communication engine used by MySQL Group Replication only
     supports IPv4.  Therefore, Group Replication requires an IPv4
     network infrastructure.

   * Network Performance

     Group Replication is designed to be deployed in a cluster
     environment where server instances are very close to each other,
     and is impacted by both network latency as well as network
     bandwidth.

*Server Instance Configuration*

The following options must be configured on server instances that are
members of a group.

   * Binary Log Active

     Set '--log-bin[=log_file_name]'.  MySQL Group Replication
     replicates binary log contents, therefore the binary log needs to
     be on for it to operate.  This option is enabled by default.  See
     binary-log.

   * Slave Updates Logged

     Set '--log-slave-updates'.  Servers need to log binary logs that
     are applied through the replication applier.  Servers in the group
     need to log all transactions that they receive and apply from the
     group.  This is required because recovery is conducted by relying
     on binary logs form participants in the group.  Therefore, copies
     of each transaction need to exist on every server, even for those
     transactions that were not initiated on the server itself.

   * Binary Log Row Format

     Set '--binlog-format=row'.  Group Replication relies on row-based
     replication format to propagate changes consistently among the
     servers in the group.  It relies on row-based infrastructure to be
     able to extract the necessary information to detect conflicts among
     transactions that execute concurrently in different servers in the
     group.  See replication-formats.

   * Global Transaction Identifiers On

     Set ' --gtid-mode=ON'.  Group Replication uses global transaction
     identifiers to track exactly which transactions have been committed
     on every server instance and thus be able to infer which servers
     have executed transactions that could conflict with already
     committed transactions elsewhere.  In other words, explicit
     transaction identifiers are a fundamental part of the framework to
     be able to determine which transactions may conflict.  See
     replication-gtids.

   * Replication Information Repositories

     Set '--master-info-repository=TABLE' and
     '--relay-log-info-repository=TABLE'.  The replication applier needs
     to have the master information and relay log metadata written to
     the 'mysql.slave_master_info' and 'mysql.slave_relay_log_info'
     system tables.  This ensures the Group Replication plugin has
     consistent recoverability and transactional management of the
     replication metadata.  See slave-logs-status.

   * Transaction Write Set Extraction

     Set '--transaction-write-set-extraction=XXHASH64' so that while
     collecting rows to log them to the binary log, the server collects
     the write set as well.  The write set is based on the primary keys
     of each row and is a simplified and compact view of a tag that
     uniquely identifies the row that was changed.  This tag is then
     used for detecting conflicts.

   * Multi-threaded Appliers

     Group Replication members can be configured as multi-threaded
     appliers, enabling transactions to be applied in parallel.  Set
     '--slave-parallel-workers=N' (where 'N' is the number of parallel
     applier threads), '--slave-preserve-commit-order=1', and
     '--slave-parallel-type=LOGICAL_CLOCK'.  Setting
     '--slave-parallel-workers=N' enables the multi-threaded applier on
     the member.  Group Replication relies on consistency mechanisms
     built around the guarantee that all participating members receive
     and apply committed transaction in the same order, so you must also
     set '--slave-preserve-commit-order=1' to ensure that the final
     commit of parallel transactions is in the same order as the
     original transactions.  Finally, in order to determine which
     transactions can be executed in parallel, the relay log must
     contain transaction parent information generated with
     '--slave-parallel-type=LOGICAL_CLOCK'.  Attempting to add a member
     with '--slave-parallel-workers' set to greater than 0 without also
     setting the other two options, generates an error and the instance
     is prevented from joining.

17.7.2 Group Replication Limitations
------------------------------------

The following known limitations exist for Group Replication.

*Tip*:

Group Replication is built on GTID based replication, therefore you
should also be aware of replication-gtids-restrictions.

   * Replication Event Checksums

     Due to a design limitation of replication event checksums, Group
     Replication cannot currently make use of them.  Therefore set
     '--binlog-checksum=NONE'.

   * Gap Locks

     The certification process does not take into account gap locks, as
     information about gap locks is not available outside of
     'InnoDB'.  See innodb-gap-locks for
     more information.

     *Note*:

     Unless you rely on 'REPEATABLE READ' semantics in your
     applications, we recommend using the 'READ COMMITTED' isolation
     level with Group Replication.  InnoDB does not use gap locks in
     'READ COMMITTED', which aligns the local conflict detection within
     InnoDB with the distributed conflict detection performed by Group
     Replication.

   * Table Locks and Named Locks

     The certification process does not take into account table locks
     (see lock-tables) or named locks (see 'GET_LOCK()').

   * SERIALIZABLE Isolation Level

     'SERIALIZABLE' isolation level is not supported in multi-primary
     groups by default.  Setting a transaction isolation level to
     'SERIALIZABLE' configures Group Replication to refuse to commit the
     transaction.

   * Concurrent DDL versus DML Operations

     Concurrent data definition statements and data manipulation
     statements executing against the same object but on different
     servers is not supported when using multi-primary mode.  During
     execution of Data Definition Language (DDL) statements on an
     object, executing concurrent Data Manipulation Language (DML) on
     the same object but on a different server instance has the risk of
     conflicting DDL executing on different instances not being
     detected.

   * Foreign Keys with Cascading Constraints

     Multi-primary mode groups (members all configured with
     'group_replication_single_primary_mode=OFF') do not support tables
     with multi-level foreign key dependencies, specifically tables that
     have defined 'CASCADING' foreign key constraints.  This is because
     foreign key constraints that result in cascading operations
     executed by a multi-primary mode group can result in undetected
     conflicts and lead to inconsistent data across the members of the
     group.  Therefore we recommend setting
     'group_replication_enforce_update_everywhere_checks=ON' on server
     instances used in multi-primary mode groups to avoid undetected
     conflicts.

     In single-primary mode this is not a problem as it does not allow
     concurrent writes to multiple members of the group and thus there
     is no risk of undetected conflicts.

   * Very Large Transactions

     Individual transactions that result in GTID contents which are
     large enough that it cannot be copied between group members over
     the network within a 5 second window can cause failures in the
     group communication.  To avoid this issue try and limit the size of
     your transactions as much as possible.  For example, split up files
     used with 'LOAD DATA INFILE' into smaller chunks.

   * MySQL Enterprise Audit and MySQL Enterprise Firewall

     Prior to version 5.7.21 MySQL Enterprise Audit and MySQL Enterprise
     Firewall use 'MyISAM' tables in the 'mysql' system database.  Group
     Replication does not support 'MyISAM' tables.

17.8 Frequently Asked Questions
===============================

This section provides answers to frequently asked questions.

*What is the maximum number of MySQL servers in a group?*

A group can consist of maximum 9 servers.  Attempting to add another
server to a group with 9 members causes the request to join to be
refused.

*How are servers in a group connected?*

Servers in a group connect to the other servers in the group by opening
a peer-to-peer TCP connection.  These connections are only used for
internal communication and message passing between servers in the group.
This address is configured by the 'group_replication_local_address'
variable.

*What is the group_replication_bootstrap_group option used for?*

The bootstrap flag instructs a member to _create_ a group and act as the
initial seed server.  The second member joining the group needs to ask
the member that bootstrapped the group to dynamically change the
configuration in order for it to be added to the group.

A member needs to bootstrap the group in two scenarios.  When the group
is originally created, or when shutting down and restarting the entire
group.

*How do I set credentials for the recovery procedure?*

You pre-configure the Group Replication recovery channel credentials
using the 'CHANGE MASTER TO' statement.

*Can I scale-out my write-load using Group Replication?*

Not directly, but MySQL Group replication is a shared nothing full
replication solution, where all servers in the group replicate the same
amount of data.  Therefore if one member in the group writes N bytes to
storage as the result of a transaction commit operation, then roughly N
bytes are written to storage on other members as well, because the
transaction is replicated everywhere.

However, given that other members do not have to do the same amount of
processing that the original member had to do when it originally
executed the transaction, they apply the changes faster.  Transactions
are replicated in a format that is used to apply row transformations
only, without having to re-execute transactions again (row-based
format).

Furthermore, given that changes are propagated and applied in row-based
format, this means that they are received in an optimized and compact
format, and likely reducing the number of IO operations required when
compared to the originating member.

To summarize, you can scale-out processing, by spreading conflict free
transactions throughout different members in the group.  And you can
likely scale-out a small fraction of your IO operations, since remote
servers receive only the necessary changes to read-modify-write changes
to stable storage.

*Does Group Replication require more network bandwidth and CPU, when
compared to simple replication and under the same workload?*

Some additional load is expected because servers need to be constantly
interacting with each other for synchronization purposes.  It is
difficult to quantify how much more data.  It also depends on the size
of the group (three servers puts less stress on the bandwidth
requirements than nine servers in the group).

Also the memory and CPU footprint are larger, because more complex work
is done for the server synchronization part and for the group messaging.

*Can I deploy Group Replication across wide-area networks?*

Yes, but the network connection between each member _must_ be reliable
and have suitable perfomance.  Low latency, high bandwidth network
connections are a requirement for optimal performance.

If network bandwidth alone is an issue, then
group-replication-message-compression can be used to lower the
bandwidth required.  However, if the network drops packets, leading to
re-transmissions and higher end-to-end latency, throughput and latency
are both negatively affected.

*Warning*:

When the network round-trip time (RTT) between any group members is 2
seconds or more you could encounter problems as the built-in failure
detection mechanism could be incorrectly triggered.

*Do members automatically rejoin a group in case of temporary
connectivity problems?*

This depends on the reason for the connectivity problem.  If the
connectivity problem is transient and the reconnection is quick enough
that the failure detector is not aware of it, then the server may not be
removed from the group.  If it is a "long" connectivity problem, then
the failure detector eventually suspects a problem and the server is
removed from the group.

Once a server is removed from the group, you need to join it back again.
In other words, after a server is removed explicitly from the group you
need to rejoin it manually (or have a script doing it automatically).

*When is a member excluded from a group?*

If the member becomes silent, the other members remove it from the group
configuration.  In practice this may happen when the member has crashed
or there is a network disconnection.

The failure is detected after a given timeout elapses for a given member
and a new configuration without the silent member in it is created.

*What happens when one node is significantly lagging behind?*

There is no method for defining policies for when to expel members
automatically from the group.  You need to find out why a member is
lagging behind and fix that or remove the member from the group.
Otherwise, if the server is so slow that it triggers the flow control,
then the entire group slows down as well.  The flow control can be
configured according to the your needs.

*Upon suspicion of a problem in the group, is there a special member
responsible for triggering a reconfiguration?*

No, there is no special member in the group in charge of triggering a
reconfiguration.

Any member can suspect that there is a problem.  All members need to
(automatically) agree that a given member has failed.  One member is in
charge of expelling it from the group, by triggering a reconfiguration.
Which member is responsible for expelling the member is not something
you can control or set.

*Can I use Group Replication for sharding?*

Group Replication is designed to provide highly available replica sets;
data and writes are duplicated on each member in the group.  For scaling
beyond what a single system can provide, you need an orchestration and
sharding framework built around a number of Group Replication sets,
where each replica set maintains and manages a given shard or partition
of your total dataset.  This type of setup, often called a 'sharded
cluster', allows you to scale reads and writes linearly and without
limit.

*How do I use Group Replication with SELinux?*

If SELinux is enabled, which you can verify using 'sestatus -v', then
you need to enable the use of the Group Replication communication port,
configured by 'group_replication_local_address', for 'mysqld'
so that it can bind to it and listen there.  To see which ports
MySQL is currently allowed to use, issue 'semanage port -l | grep
mysqld'.  Assuming the port configured is 6606, add the necessary port
to those permitted by SELinux by issuing 'semanage port -a -t
mysqld_port_t -p tcp 6606'.

*How do I use Group Replication with iptables?*

If iptables is enabled, then you need to open up the Group Replication
port for communication between the machines.  To see the current rules
in place on each machine, issue 'iptables -L'.  Assuming the port
configured is 6606, enable communication over the necessary port by
issuing 'iptables -A INPUT -p tcp --dport 6606 -j ACCEPT'.

*How do I recover the relay log for a replication channel used by a
group member?*

The replication channels used by Group Replication behave in the same
way as replication channels used in master to slave replication, and as
such rely on the relay log.  In the event of a change of the 'relay_log'
variable, or when the option is not set and the host name changes, there
is a chance of errors.  See slave-logs-relaylog for a recovery
procedure in this situation.  Alternatively, another way of fixing the
issue specifically in Group Replication is to issue a 'STOP GROUP_REPLICATION'
statement and then a
'START GROUP_REPLICATION' statement to restart
the instance.  The Group Replication plugin creates the
'group_replication_applier' channel again.

*Why does Group Replication use two bind addresses?*

Group Replication uses two bind addresses in order to split network
traffic between the SQL address, used by clients to communicate with the
member, and the 'group_replication_local_address', used internally by
the group members to communicate.  For example, assume a server with two
network interfaces assigned to the network addresses '203.0.113.1' and
'198.51.100.179'.  In such a situation you could use '203.0.113.1:33061'
for the internal group network address by setting
'group_replication_local_address=203.0.113.1:33061'.  Then you could use
'198.51.100.179' for 'hostname' and '3306' for the 'port'.  Client SQL
applications would then connect to the member at '198.51.100.179:3306'.
This enables you to configure different rules on the different networks.
Similarly, the internal group communication can be separated from the
network connection used for client applications, for increased security.

*How does Group Replication use network addresses and hostnames?*

Group Replication uses network connections between members and therefore
its functionality is directly impacted by how you configure hostnames
and ports.  For example, the Group Replication recovery procedure is
based on asynchronous replication which uses the server's hostname and
port.  When a member joins a group it receives the group membership
information, using the network address information that is listed at
'performance_schema.replication_group_members'.  One of the members
listed in that table is selected as the donor of the missing data from
the group to the new member.

This means that any value you configure using a hostname, such as the
SQL network address or the group seeds address, must be a fully
qualified name and resolvable by each member of the group.  You can
ensure this for example through DNS, or correctly configured
'/etc/hosts' files, or other local processes.  If a you want to
configure the 'MEMBER_HOST' value on a server, specify it using the
'--report-host' option on the server before joining it to the group.

*Important*:

The assigned value is used directly and is not affected by the
'--skip-name-resolve' option.

To configure 'MEMBER_PORT' on a server, specify it using the
'--report-port' option.

17.9 Group Replication Technical Details
========================================

This section provides more technical details about MySQL Group
Replication.

17.9.1 Group Replication Plugin Architecture
--------------------------------------------

MySQL Group Replication is a MySQL plugin and it builds on the existing
MySQL replication infrastructure, taking advantage of features such as
the binary log, row-based logging, and global transaction identifiers.
It integrates with current MySQL frameworks, such as the performance
schema or plugin and service infrastructures.  The following figure
presents a block diagram depicting the overall architecture of MySQL
Group Replication.

FIGURE GOES HERE: Group Replication Plugin Block Diagram

The MySQL Group Replication plugin includes a set of APIs for capture,
apply, and lifecycle, which control how the plugin interacts with MySQL
Server.  There are interfaces to make information flow from the server
to the plugin and vice versa.  These interfaces isolate the MySQL Server
core from the Group Replication plugin, and are mostly hooks placed in
the transaction execution pipeline.  In one direction, from server to
the plugin, there are notifications for events such as the server
starting, the server recovering, the server being ready to accept
connections, and the server being about to commit a transaction.  In the
other direction, the plugin instructs the server to perform actions such
as committing or aborting ongoing transactions, or queuing transactions
in the relay log.

The next layer of the Group Replication plugin architecture is a set of
components that react when a notification is routed to them.  The
capture component is responsible for keeping track of context related to
transactions that are executing.  The applier component is responsible
for executing remote transactions on the database.  The recovery
component manages distributed recovery, and is responsible for getting a
server that is joining the group up to date by selecting the donor,
orchestrating the catch up procedure and reacting to donor failures.

Continuing down the stack, the replication protocol module contains the
specific logic of the replication protocol.  It handles conflict
detection, and receives and propagates transactions to the group.

The final two layers of the Group Replication plugin architecture are
the Group Communication System (GCS) API, and an implementation of a
Paxos-based group communication engine.  The GCS API is a high level API
that abstracts the properties required to build a replicated state
machine (see group-replication-background).  It therefore
decouples the implementation of the messaging layer from the remaining
upper layers of the plugin.  The group communication engine handles
communications with the members of the replication group.

17.9.2 The Group
----------------

In MySQL Group Replication, a set of servers forms a replication group.
A group has a name, which takes the form of a UUID. The group is dynamic
and servers can leave (either voluntarily or involuntarily) and join it
at any time.  The group adjusts itself whenever servers join or leave.

If a server joins the group, it automatically brings itself up to date
by fetching the missing state from an existing server.  This state is
transferred by means of Asynchronous MySQL replication.  If a server
leaves the group, for instance it was taken down for maintenance, the
remaining servers notice that it has left and reconfigure the group
automatically.  The group membership service described at
group-replication-group-membership powers all of this.

17.9.3 Data Manipulation Statements
-----------------------------------

As there are no primary servers (masters) for any particular data set,
every server in the group is allowed to execute transactions at any
time, even transactions that change state (RW transactions).

Any server may execute a transaction without any _a priori_

coordination.  But, at commit time, it coordinates with the rest of the
servers in the group to reach a decision on the fate of that
transaction.  This coordination serves two purposes: (i) check whether
the transaction should commit or not; (ii) and propagate the changes so
that other servers can apply the transaction as well.

As a transaction is sent through an atomic broadcast, either all servers
in the group receive the transaction or none do.  If they receive it,
then they all receive it in the same order with respect to other
transactions that were sent before.  Conflict detection is carried out
by inspecting and comparing write sets of transactions.  Thus, they are
detected at the row level.  Conflict resolution follows the first
committer wins rule.  If t1 and t2 execute concurrently at different
sites, because t2 is ordered before t1, and both changed the same row,
then t2 wins the conflict and t1 aborts.  In other words, t1 was trying
to change data that had been rendered stale by t2.

*Note*:

If two transactions are bound to conflict more often than not, then it
is a good practice to start them on the same server.  They then have a
chance to synchronize on the local lock manager instead of aborting
later in the replication protocol.

17.9.4 Data Definition Statements
---------------------------------

In a Group Replication topology, care needs to be taken when executing
data definition statements also commonly known as data definition
language (DDL). Given that MySQL does not support atomic or
transactional DDL, one cannot optimistically execute DDL statements and
later roll back if needs be.  Consequently, the lack of atomicity does
not fit directly into the optimistic replication paradigm that Group
Replication is based on.

Therefore, more care needs to be taken when replicating data definition
statements.  Schema changes and changes to the data that the object
contains need to be handled through the same server while the schema
operation has not yet completed and replicated everywhere.  Failure to
do so can result in data inconsistency.

*Note*:

If the group is deployed in single-primary mode, then this is not a
problem, because all changes are performed through the same server, the
primary.

*Warning*:

MySQL DDL execution is not atomic or transactional.  The server executes
and commits without securing group agreement first.  As such, you must
route DDL and DML for the same object through the same server, while the
DDL is executing and has not replicated everywhere yet.

17.9.5 Distributed Recovery
---------------------------

This section describes the process through which a member joining a
group catches up with the remaining servers in the group, called
distributed recovery.

17.9.5.1 Distributed Recovery Basics
....................................

This section is a high level summary.  The following sections provide
additional detail, by describing the phases of the procedure in more
detail.

Group Replication distributed recovery can be summarized as the process
through which a server gets missing transactions from the group so that
it can then join the group having processed the same set of transactions
as the other group members.  During distributed recovery, the server
joining the group buffers any transactions and membership events that
happen while the server joining the group is receiving the transactions
required from the group.  Once the server joining the group has received
all of the group's transactions, it applies the transactions that were
buffered during the recovery process.  At the end of this process the
server then joins the group as an online member.

*Phase 1*

In the first phase, the server joining the group selects one of the
online servers on the group to be the _donor_ of the state that it is
missing.  The donor is responsible for providing the server joining the
group all the data it is missing up to the moment it has joined the
group.  This is achieved by relying on a standard asynchronous
replication channel, established between the donor and the server
joining the group, see replication-channels.  Through this
replication channel, the donor's binary logs are replicated until the
point that the view change happened when the server joining the group
became part of the group.  The server joining the group applies the
donor's binary logs as it receives them.

While the binary log is being replicated, the server joining the group
also caches every transaction that is exchanged within the group.  In
other words it is listening for transactions that are happening after it
joined the group and while it is applying the missing state from the
donor.  When the first phase ends and the replication channel to the
donor is closed, the server joining the group then starts phase two: the
catch up.

*Phase 2*

In this phase, the server joining the group proceeds to the execution of
the cached transactions.  When the number of transactions queued for
execution finally reaches zero, the member is declared online.

*Resilience*

The recovery procedure withstands donor failures while the server
joining the group is fetching binary logs from it.  In such cases,
whenever a donor fails during phase 1, the server joining the group
fails over to a new donor and resumes from that one.  When that happens
the server joining the group closes the connection to the failed server
joining the group explicitly and opens a connection to a new donor.
This happens automatically.

17.9.5.2 Recovering From a Point-in-time
........................................

To synchronize the server joining the group with the donor up to a
specific point in time, the server joining the group and donor make use
of the MySQL Global Transaction Identifiers (GTIDs) mechanism.  See
replication-gtids.  However, GTIDS only provide a means to
realize which transactions the server joining the group is missing, they
do not help marking a specific point in time to which the server joining
the group must catch up, nor do they help conveying certification
information.  This is the job of binary log view markers, which mark
view changes in the binary log stream, and also contain additional
metadata information, provisioning the server joining the group with
missing certification related data.

*View and View Changes*

To explain the concept of view change markers, it is important to
understand what a view and a view change are.

A _view_ corresponds to a group of members participating actively in the
current configuration, in other words at a specific point in time.  They
are correct and online in the system.

A _view change_ occurs when a modification to the group configuration
happens, such as a member joining or leaving.  Any group membership
change results in an independent view change communicated to all members
at the same logical point in time.

A _view identifier_ uniquely identifies a view.  It is generated
whenever a view change happens

At the group communication layer, view changes with their associated
view ids are then boundaries between the data exchanged before and after
a member joins.  This concept is implemented through a new binary log
event: the"view change log event".  The view id thus becomes a marker as
well for transactions transmitted before and after changes happen in the
group membership.

The view identifier itself is built from two parts: _(i)_ one that is
randomly generated and _(ii)_ a monotonically increasing integer.  The
first part is generated when the group is created, and remains unchanged
while there is at least one member in the group.  The second part is
incremented every time a view change happens.

The reason for this heterogeneous pair that makes up the view id is the
need to unambiguously mark group changes whenever a member joins or
leaves but also whenever all members leave the group and no information
remains of what view the group was in.  In fact, the sole use of
monotonic increasing identifiers could lead to the reuse of the same id
after full group shutdowns, destroying the uniqueness of the binary log
data markers that recovery depends on.  To summarize, the first part
identifies whenever the group was started from the beginning and the
incremental part when the group changed from that point on.

17.9.5.3 View Changes
.....................

This section explains the process which controls how the view change
identifier is incorporated into a binary log event and written to the
log, The following steps are taken:

*Begin: Stable Group*

All servers are online and processing incoming transactions from the
group.  Some servers may be a little behind in terms of transactions
replicated, but eventually they converge.  The group acts as one
distributed and replicated database.

FIGURE GOES HERE: Stable Group

*View Change: a Member Joins*

Whenever a new member joins the group and therefore a view change is
performed, every online server queues a view change log event for
execution.  This is queued because before the view change, several
transactions can be queued on the server to be applied and as such,
these belong to the old view.  Queuing the view change event after them
guarantees a correct marking of when this happened.

Meanwhile, the server joining the group selects the donor from the list
of online servers as stated by the membership service through the view
abstraction.  A member joins on view 4 and the online members write a
View change event to the binary log.

FIGURE GOES HERE: A Member Joins

*State Transfer: Catching Up*

Once the server joining the group has chosen which server in the group
is to be the donor, a new asynchronous replication connection is
established between the two and the state transfer begins (phase 1).
This interaction with the donor continues until the server joining the
group's applier thread processes the view change log event that
corresponds to the view change triggered when the server joining the
group came into the group.  In other words, the server joining the group
replicates from the donor, until it gets to the marker with the view
identifier which matches the view marker it is already in.

FIGURE GOES HERE: State Transfer: Catching Up

As view identifiers are transmitted to all members in the group at the
same logical time, the server joining the group knows at which view
identifier it should stop replicating.  This avoids complex GTID set
calculations because the view id clearly marks which data belongs to
each group view.

While the server joining the group is replicating from the donor, it is
also caching incoming transactions from the group.  Eventually, it stops
replicating from the donor and switches to applying those that are
cached.

FIGURE GOES HERE: Queued Transactions

*Finish: Caught Up*

When the server joining the group recognizes a view change log event
with the expected view identifier, the connection to the donor is
terminated and it starts applying the cached transactions.  An important
point to understand is the final recovery procedure.  Although it acts
as a marker in the binary log, delimiting view changes, the view change
log event also plays another role.  It conveys the certification
information as perceived by all servers when the server joining the
group entered the group, in other words the last view change.  Without
it, the server joining the group would not have the necessary
information to be able to certify (detect conflicts) subsequent
transactions.

The duration of the catch up (phase 2) is not deterministic, because it
depends on the workload and the rate of incoming transactions to the
group.  This process is completely online and the server joining the
group does not block any other server in the group while it is catching
up.  Therefore the number of transactions the server joining the group
is behind when it moves to phase 2 can, for this reason, vary and thus
increase or decrease according to the workload.

When the server joining the group reaches zero queued transactions and
its stored data is equal to the other members, its public state changes
to online.

FIGURE GOES HERE: Instance Online

17.9.5.4 Usage Advice and Limitations of Distributed Recovery
.............................................................

Distributed recovery does have some limitations.  It is based on classic
asynchronous replication and as such it may be slow if the server
joining the group is not provisioned at all or is provisioned with a
very old backup image.  This means that if the data to transfer is too
big at phase 1, the server may take a very long time to recover.  As
such, the recommendation is that before adding a server to the group,
one should provision it with a fairly recent snapshot of a server
already in the group.  This minimizes the length of phase 1 and reduces
the impact on the donor server, since it has to save and transfer less
binary logs.

*Warning*:

It is recommended that a server is provisioned before it is added to a
group.  That way, one minimizes the time spent on the recovery step.

17.9.6 Observability
--------------------

There is a lot of automation built into the Group Replication plugin.
Nonetheless, you might sometimes need to understand what is happening
behind the scenes.  This is where the instrumentation of Group
Replication and Performance Schema becomes important.  The entire state
of the system (including the view, conflict statistics and service
states) can be queried through performance_schema tables.  The
distributed nature of the replication protocol and the fact that server
instances agree and thus synchronize on transactions and metadata makes
it simpler to inspect the state of the group.  For example, you can
connect to a single server in the group and obtain both local and global
information by issuing select statements on the Group Replication
related Performance Schema tables.  For more information, see
group-replication-monitoring.

17.9.7 Group Replication Performance
------------------------------------

This section explains how to use the available configuration options to
gain the best performance from your group.

17.9.7.1 Fine Tuning the Group Communication Thread
...................................................

The group communication thread (GCT) runs in a loop while the Group
Replication plugin is loaded.  The GCT receives messages from the group
and from the plugin, handles quorum and failure detection related tasks,
sends out some keep alive messages and also handles the incoming and
outgoing transactions from/to the server/group.  The GCT waits for
incoming messages in a queue.  When there are no messages, the GCT
waits.  By configuring this wait to be a little longer (doing an active
wait) before actually going to sleep can prove to be beneficial in some
cases.  This is because the alternative is for the operating system to
switch out the GCT from the processor and do a context switch.

To force the GCT do an active wait, use the
'group_replication_poll_spin_loops' option, which makes the GCT loop,
doing nothing relevant for the configured number of loops, before
actually polling the queue for the next message.

For example:

     mysql> SET GLOBAL group_replication_poll_spin_loops= 10000;

17.9.7.2 Message Compression
............................

When network bandwidth is a bottleneck, message compression can provide
up to 30-40% throughput improvement at the group communication level.
This is especially important within the context of large groups of
servers under load.

*LZ4 Compression Ratios for Different Binary Log Formats*

WorkloadRatioRatio
 forfor
 ROWSTMT

mysqlslapd4,54,1

sysbench3,42,9

The TCP peer-to-peer nature of the interconnections between _N_
participants on the group makes the sender send the same amount of data
_N_ times.  Furthermore, binary logs are likely to exhibit a high
compression ratio (see table above).  This makes compression a
compelling feature for workloads that contain large transaction.

FIGURE GOES HERE: Compression Support

Compression happens at the group communication engine level, before the
data is handed over to the group communication thread, so it happens
within the context of the mysql user session thread.  Transaction
payloads may be compressed before being sent out to the group and
decompressed when received.  Compression is conditional and depends on a
configured threshold.  By default compression is enabled.

In addition, there is no requirement that all servers in the group have
compression enabled to be able to work together.  Upon receiving a
message, the member checks the message envelope to verify whether it is
compressed or not.  If needed, then the member decompresses the
transaction, before delivering it to the upper layer.

The compression algorithm used is LZ4.  Compression is enabled by
default with threshold of 1000000 bytes.  The compression threshold, in
bytes, may be set to something larger than default.  In that case, only
transactions that have a payload larger than the threshold are
compressed.  Below is an example of how to set a compression threshold.

     STOP GROUP_REPLICATION;
     SET GLOBAL group_replication_compression_threshold= 2097152;
     START GROUP_REPLICATION;

This sets the compression threshold to 2MB. If a transaction generates a
replication message with a payload larger than 2MB, for example a binary
log transaction entry larger than 2MB, then it is compressed.  To
disable compression set threshold to 0.

17.9.7.3 Flow Control
.....................

Group Replication ensures that a transaction only commits after a
majority of the members in a group have received it and agreed on the
relative order between all transactions that were sent concurrently.

This approach works well if the total number of writes to the group does
not exceed the write capacity of any member in the group.  If it does
and some of the members have less write throughput than others,
particularly less than the writer members, those members can start
lagging behind of the writers.

Having some members lagging behind the group brings some problematic
consequences, particularly, the reads on such members may externalize
very old data.  Depending on why the member is lagging behind, other
members in the group may have to save more or less replication context
to be able to fulfil potential data transfer requests from the slow
member.

There is however a mechanism in the replication protocol to avoid having
too much distance, in terms of transactions applied, between fast and
slow members.  This is known as the flow control mechanism.  It tries to
address several goals:

  1. to keep the members close enough to make buffering and
     de-synchronization between members a small problem;

  2. to adapt quickly to changing conditions like different workloads or
     more writers in the group;

  3. to give each member a fair share of the available write capacity;

  4. to not reduce throughput more than strictly necessary to avoid
     wasting resources.

Given the design of Group Replication, the decision whether to throttle
or not may be decided taking into account two work queues: _(i)_ the
_certification_ queue; _(ii)_ and on the binary log _applier_ queue.
Whenever the size of one of these queues exceeds the user-defined
threshold, the throttling mechanism is triggered.  Only configure: _(i)_
whether to do flow control at the certifier or at the applier level, or
both; and _(ii)_ what is the threshold for each queue.

The flow control depends on two basic mechanisms:

  1. the monitoring of members to collect some statistics on throughput
     and queue sizes of all group members to make educated guesses on
     what is the maximum write pressure each member should be subjected
     to;

  2. the throttling of members that are trying to write beyond their
     fair-share of the available capacity at each moment in time.

17.9.7.4 Probes and Statistics
..............................

The monitoring mechanism works by having each member deploying a set of
probes to collect information about its work queues and throughput.  It
then propagates that information to the group periodically to share that
data with the other members.

Such probes are scattered throughout the plugin stack and allow one to
establish metrics, such as:

   * the certifier queue size;

   * the replication applier queue size;

   * the total number of transactions certified;

   * the total number of remote transactions applied in the member;

   * the total number of local transactions.

Once a member receives a message with statistics from another member, it
calculates additional metrics regarding how many transactions were
certified, applied and locally executed in the last monitoring period.

Monitoring data is shared with others in the group periodically.  The
monitoring period must be high enough to allow the other members to
decide on the current write requests, but low enough that it has minimal
impact on group bandwidth.  The information is shared every second, and
this period is sufficient to address both concerns.

17.9.7.5 Group Replication Throttling
.....................................

Based on the metrics gathered across all servers in the group, a
throttling mechanism kicks in and decides whether to limit the rate a
member is able to execute/commit new transactions.

Therefore, metrics acquired from all members are the basis for
calculating the capacity of each member: if a member has a large queue
(for certification or the applier thread), then the capacity to execute
new transactions should be close to ones certified or applied in the
last period.

The lowest capacity of all the members in the group determines the real
capacity of the group, while the number of local transactions determines
how many members are writing to it, and, consequently, how many members
should that available capacity be shared with.

This means that every member has an established write quota based on the
available capacity, in other words a number of transactions it can
safely issue for the next period.  The writer-quota will be enforced by
the throttling mechanism if the queue size of the certifier or the
binary log applier exceeds a user-defined threshold.

The quota is reduced by the number of transactions that were delayed in
the last period, and then also further reduced by 10% to allow the queue
that triggered the problem to reduce its size.  In order to avoid large
jumps in throughput once the queue size goes beyond the threshold, the
throughput is only allowed to grow by the same 10% per period after
that.

The current throttling mechanism does not penalize transactions below
quota, but delays finishing those transactions that exceed it until the
end of the monitoring period.  As a consequence, if the quota is very
small for the write requests issued some transactions may have latencies
close to the monitoring period.

18 MySQL Shell User Guide
*************************

This section provides user documentation for MySQL Shell, an advanced
client and code editor for MySQL Server.  In addition to the provided
SQL functionality, similar to 'mysql', MySQL Shell provides
scripting capabilities for JavaScript and Python and includes APIs for
working with MySQL. X DevAPI enables you to work with both relational
and document data, see document-store.  AdminAPI enables you to
work with InnoDB cluster, see mysql-innodb-cluster-userguide.

MySQL Shell enables you to prototype code using the X DevAPI to
communicate with a MySQL Server running the X Plugin.  The X Plugin is a
new MySQL Server feature available with MySQL Server 5.7.12 and higher.

MySQL Shell is an advanced command-line client and code editor for the
MySQL Server.  In addition to SQL, MySQL Shell also offers scripting
capabilities for JavaScript and Python.  When MySQL Shell is connected
to the MySQL Server through the X Protocol, the X DevAPI can be used to
work with both relational and document data.

18.1 MySQL Shell Features
=========================

The following features are available in MySQL Shell.

*Interactive Code Execution*

MySQL Shell provides an interactive code execution mode, where you type
code at the MySQL Shell prompt and each entered statement is processed,
with the result of the processing printed onscreen.

*Supported Languages*

MySQL Shell processes code in the following languages: JavaScript,
Python and SQL. Any entered code is processed as one of these languages,
based on the language that is currently active.  There are also specific
MySQL Shell commands, prefixed with '\', which enable you to configure
MySQL Shell regardless of the currently selected language.  For more
information see mysql-shell-commands.

*Batch Code Execution*

In addition to the interactive execution of code, MySQL Shell can also
take code from different sources and process it.  This method of
processing code in a non-interactive way is called _Batch Execution_.

As batch execution mode is intended for script processing of a single
language, it is limited to having minimal non-formatted output and
disabling the execution of commands.  To avoid these limitations, use
the '--interactive' command-line option, which tells MySQL Shell to
execute the input as if it were an interactive session.  In this mode
the input is processed _line by line_ just as if each line were typed in
an interactive session.  For more information see
mysql-shell-batch-mode-interactive.

*Output Formats*

MySQL Shell provides output in different formats depending on how it is
used: Tabbed, Table and JSON. For more information see
mysql-shell-output-formats.

*Multiple-line Support*

Multiple-line code can be written using a command, enabling MySQL Shell
to cache multiple lines and then execute them as a single statement.
For more information see mysql-shell-multiple-line-support.

*Application Log*

MySQL Shell can be configured to log information about the execution
process.  For more information see mysql-shell-application-log.

*Supported APIs*

MySQL Shell includes the following APIs implemented in JavaScript and
Python which you can use to develop code that interacts with MySQL.

   * The X DevAPI enables you to work with both relational and document
     data when MySQL Shell is connected to a MySQL server using the X
     Protocol.  For more information, see document-store.  For
     documentation on the concepts and usage of X DevAPI, see X DevAPI
     User Guide (http://dev.mysql.com/doc/x-devapi-userguide/en/).

   * The AdminAPI enables you to work with InnoDB cluster, which
     provides an integrated solution for high availability and
     scalability using InnoDB based MySQL databases, without requiring
     advanced MySQL expertise.  See
     mysql-innodb-cluster-userguide.

For specific documentation on the implementation of the APIs see
JavaScript (http://dev.mysql.com/doc/dev//mysqlsh-api-javascript/1.0/)
and Python (http://dev.mysql.com/doc/dev//mysqlsh-api-python/1.0/).

*X Protocol Support*

MySQL Shell is designed to provide an integrated command-line client for
all MySQL products which support X Protocol.  The development features
of MySQL Shell are designed for sessions using the X Protocol.  MySQL
Shell can also connect to MySQL Servers that do not support the X
Protocol using the legacy MySQL Protocol.  A minimal set of features
from the X DevAPI are available for sessions created using the legacy
MySQL protocol.

*Global Session*

Interaction with a MySQL Server is done through a Session object.  For
Python and JavaScript, a Session can be created through the 'getSession'
and 'getNodeSession' functions of the mysqlx module.  If a session is
created in JavaScript mode using any of these methods, it is available
only in JavaScript mode.  The same happens if the session is created in
Python mode.  None of these sessions can be used in SQL mode.

For SQL Mode, the concept of Global Session is supported by the MySQL
Shell.  A Global Session is created when the connection information is
passed to MySQL Shell using command-line options, or by using the
'\connect' command.

The Global Session is used to execute statements in SQL mode and the
same session is available in both Python or JavaScript modes.  When a
Global Session is created, a variable called 'session' is set in the
scripting languages, so you can execute code in the different languages
by switching the active mode.

For more information, see mysql-shell-sessions.

18.2 Getting Started with MySQL Shell
=====================================

This section describes how to get started with MySQL Shell, explaining
how to connect to a MySQL server instance, and how to choose a session
type.

18.2.1 MySQL Shell Connections
------------------------------

MySQL Shell can connect to MySQL Server using both the X Protocol and
the classic MySQL protocol.  The address of the MySQL Server which you
want to connect to can be specified using individual parameters, such as
user, hostname and port, or using a Uniform Resource Identifier (URI)
type string.  The following sections describe these connection methods.
See connecting for more background information.

You can configure the MySQL server instance that MySQL Shell is
connected to in the following ways:

   * When you start MySQL Shell using the command parameters.  See
     mysql-shell-connection-using-parameters.

   * When MySQL Shell is running using the '\connect' command.  See
     mysql-shell-commands.

   * When running Python or Java code using the
     'shell.connect('INSTANCE')' method.  See JavaScript
     (http://dev.mysql.com/doc/dev//mysqlsh-api-javascript/8.0/) and
     Python (http://dev.mysql.com/doc/dev//mysqlsh-api-python/8.0/).

These methods all support mysql-shell-connection-using-uri.

*Important*:

Regardless of the method you choose to connect it is important to
understand how passwords are handled by MySQL Shell.  By default
connections are assumed to require a password.  The password is
requested at the login prompt.  To specify a password-less account use
the '--password' option and do not specify a password, or use a ':'
after the 'user' in a URI type string and do not specify a password.

If you do not specify parameters for a connection the following defaults
are used:

   * user defaults to the current system user name

   * host defaults to localhost

   * port defaults to the X Plugin port 33060 when using an X Protocol
     session, and port 3306 when using a Classic session

MySQL Shell connections using X Protocol _always_ use TCP, using Unix
sockets is not supported.  MySQL Shell connections using MySQL Protocol
default to using Unix sockets when the following conditions are met:

   * A TCP port is not specified

   * A host name is not specified or it is equal to 'localhost'

   * A socket is provided with a path to a socket file

   * A classic session is specified

If a host name is specified but it is not 'localhost', a TCP connection
is established.  In this case, if a TCP port is not specified the
default value of 3306 is used.  If the conditions are met for a socket
connection but a path to a socket file is not specified then the default
socket is used.  See connecting.

18.2.1.1 Connecting using a URI String
......................................

You can configure the MySQL Server which MySQL Shell connects to by
passing the connection data in URI type string format.  Such strings can
be used with the '--uri' command option, the MySQL Shell '\connect'
command, and the 'shell.connect()' method.

The URI type string should use the following format:

     SCHEME://[USER[:[PASSWORD]]@]TARGET[:PORT][/SCHEMA][?ATTRIBUTE1=VALUE1&ATTRIBUTE2=VALUE2...

*Important*:

Percent encoding must be used for reserved characters in the elements of
the URI type string.  For example, if you specify a password that
includes the '@' character, the character must be replaced by '%40'.

The elements of a URI type string for a MySQL Shell connection are:

   * SCHEME: this element is required and specifies the connection
     protocol to use, currently either 'mysql' for classic connection
     protocol and 'mysqlx' for X Protocol.

   * USER: this element is optional and specifies the MySQL user account
     to be used for the authentication process.

   * PASSWORD: this element is optional and specifies the password to be
     used for the authentication process.

     *Warning*:

     Storing the password in the URI type string is insecure and not
     recommended.

   * TARGET: this element is required and specifies the server instance
     the connection refers to.  Can be either TCP connection
     information, a Unix socket path or a Windows named-pipe.  If not
     specified, _localhost_ is used by default.

        * TCP connection information can be either a host name, an IPv4
          address, or an IPv6 address.  Can include an optional port
          number in the format 'host:port', where PORT specifies a
          network port which the target MySQL server is listening on for
          connections.  If not specified, 33060 is used by default for X
          Protocol connections, and 3306 is the default for classic
          MySQL protocol connections.

        * Unix socket and Windows named-pipe values are local file
          paths.  There are two ways to specify such paths, using
          percent encoding or surrounding the path with parentheses,
          removing the need to percent encode characters such as the
          common directory separator '/'.  For example, to connect as
          'root@localhost' using the Unix socket '/tmp/mysqld.sock'
          either specify the path using parenthesis as
          'root@localhost?socket=(/tmp/mysqld.sock)' or using percent
          encoding as 'root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F'.

   * SCHEMA: this element is optional and specifies the database to be
     set as default when the connection is established.

   * ?ATTRIBUTE=VALUE: this element is optional and specifies a data
     dictionary that contains

     options.

If no password is specified using the URI type string, which is
recommended, then the password is prompted for.  The following examples
show how to specify URI type strings with the user name USER, in each
case the password is prompted for:

   * An X Protocol connection to a local server instance listening at
     port 33065.

          mysqlx://user@localhost:33065

   * A classic MySQL protocol X Protocol connection to a local server
     instance listening at port 3333.

          mysql://user@localhost:3333

   * An X Protocol connection to a remote server instance, using a host
     name, an IPv4 address and an IPv6 address.

          mysqlx://user@server.example.com/
          mysqlx://user@198.51.100.14:123
          mysqlx://user@[2001:db8:85a3:8d3:1319:8a2e:370:7348]

   * An optional path can be specified, which represents a database
     schema.

          mysqlx://user@198.51.100.1/world%5Fx
          mysqlx://user@198.51.100.2:33060/world

   * An optional query can be specified, consisting of values in the
     form of a 'key=value' pair or as a single 'key'.  The ',' character
     is used as a separator for values, a combination of multiple pairs
     and keys can be specified.  Values can be of type list, list values
     are ordered by appearance.  Strings must be percent encoded.

          ssluser@127.0.0.1?ssl-ca%3D%2Froot%2Fclientcert%2Fca-cert.pem%26ssl-cert%3D%2Fro\
          ot%2Fclientcert%2Fclient-cert.pem%26ssl-key%3D%2Froot%2Fclientcert%2Fclient-key
          .pem

Although using a password-less account is insecure and not recommended,
you can specify a user without a password using a : after the user name,
for example:

     mysqlx://user:@localhost

18.2.1.2 Connecting using Individual Parameters
...............................................

In addition to specifying connection parameters using a URI type string,
it is also possible to define the connection data when starting MySQL
Shell using separate command parameters for each value.  For a full
reference of MySQL Shell command options see mysqlsh.

Use the following connection related parameters:

   * '--dbuser' ('-u') VALUE

   * '--dbpassword' VALUE

   * '--host' ('-h') VALUE

   * '--port' ('-P') VALUE

   * '--schema' ('-D') VALUE

   * '--password' ('-p')

   * '--socket' ('-S')

The first 5 parameters match the elements used in the URI type string
format described at mysql-shell-connection-using-uri.

The '--password' parameter indicates the user should connect _without_ a
password.

For consistency, the following aliases are supported for some
parameters:

   * '--user' is equivalent to '--dbuser'

   * '--password' is equivalent to '--dbpassword'

   * '--database' is equivalent to '--schema'

When parameters are specified in multiple ways, for example using both
the '--uri' option and specifying individual parameters such as
'--user', the following rules apply:

   * If an argument is specified more than once the value of the last
     appearance is used.

   * If both individual connection arguments and '--uri' are specified,
     the value of '--uri' is taken as the base and the values of the
     individual arguments override the specific component from the base
     URI.

     For example to override USER from the URI:

          shell> mysqlsh --uri USER@localhost:33065 --user OTHERUSER

The following examples show how to use command parameters to specify
connections.  Attempt to establish an X Protocol connection with a
specified user at port 33065.

     shell> mysqlsh --mysqxl -u USER -h localhost -P 33065

Attempt to establish a classic MySQL protocol connection with a
specified user.

     shell> mysqlsh --mysql -u USER -h localhost

18.2.1.3 Using Encrypted Connections
....................................

Using encrypted connections is possible when connecting to a TLS
(sometimes referred to as SSL) enabled MySQL server.  Much of the
configuration of MySQL Shell is based on the options used by MySQL
server, see encrypted-connections for more information.

To configure an encrypted connection at startup of MySQL Shell, use the
following command options:

   * '--ssl' : Deprecated, to be removed in a future version.  This
     option enables or disables encrypted connections.

   * '--ssl-mode' : This option specifies the security state of the
     connection to the server.

   * '--ssl-ca=FILENAME': The path to a file in PEM format that contains
     a list of trusted SSL Certificate Authorities.

   * '--ssl-capath=DIRECTORY': The path to a directory that contains
     trusted SSL Certificate Authority certificates in PEM format.

   * '--ssl-cert=FILENAME': The name of the SSL certificate file in PEM
     format to use for establishing an encrypted connection.

   * '--ssl-cipher=NAME': The name of the SSL cipher to use for
     establishing an encrypted connection.

   * '--ssl-key=FILENAME': The name of the SSL key file in PEM format to
     use for establishing an encrypted connection.

   * '--ssl-crl=NAME': The path to a file containing certificate
     revocation lists in PEM format.

   * '--ssl-crlpath=DIRECTORY': The path to a directory that contains
     files containing certificate revocation lists in PEM format.

   * '--tls-version=VERSION': The TLS protocols permitted for encrypted
     connections.

Alternatively the SSL options can be encoded as part of a URI type
string as part of the query element.  The available SSL options are the
same as those listed above, but written without the proceeding hyphens.
For example 'ssl-ca' is the equivalent of '--ssl-ca'.

Paths specified in a URI type string must be percent encoded, for
example:

     ssluser@127.0.0.1?ssl-ca%3D%2Froot%2Fclientcert%2Fca-cert.pem%26ssl-cert%3D%2Fro\
     ot%2Fclientcert%2Fclient-cert.pem%26ssl-key%3D%2Froot%2Fclientcert%2Fclient-key
     .pem

See mysql-shell-connection-using-uri for more information.

18.2.1.4 Connections in JavaScript and Python
.............................................

When a connection is made using the command options or by using any of
the MySQL Shell commands, a global session object is created.  This
session is global because once created, it can be used in any of the
MySQL Shell execution modes.

Any global session object is available in JavaScript or Python modes
because a variable called _session_ holds a reference to it.

In addition to the global session object, sessions can be established
and assigned to a different variable by using the functions available in
the 'mysql' and 'mysqlx' JavaScript and Python modules.

For example, the following functions are provided by these modules:

   * 'mysqlx.getSession(connectionData[, password])'

     The returned object can be Session if the object was created or
     retrieved using a Session instance, and ClassicSession if the
     object was created or retrieved using a ClassicSession instance.

   * 'mysql.getClassicSession(connectionData[, password])'

     The returned object is a ClassicSession which uses the traditional
     MySQL protocol and has a limited development API.

'connectionData' can be either a URI type string as specified at
mysql-shell-connection-using-uri or a dictionary containing the
connection parameters.

The following example shows how to create a Session using the X
Protocol:

     mysql-js> var mysession1=mysqlx.getSession('root@localhost:33060', 'PASSWORD');
     mysql-js> session
     <Session:root@localhost>
     mysql-js>

The following example shows how to create a ClassicSession:

     mysql-js> var mysession2=mysql.getClassicSession('root@localhost:3306', 'PASSWORD');
     mysql-js> session
     <ClassicSession:root@localhost:3306>
     mysql-js>

18.2.1.5 Using Encrypted Connections in Code
............................................

To establish an encrypted connection, set the SSL information in the
'connectionData' dictionary.  For example:

     mysql-js> var session=mysqlx.getSession({host: 'localhost',
                                                  dbUser: 'root',
                                                  dbPassword: 'PASSWORD',
                                                  ssl_ca: "path_to_ca_file",
                                                  ssl_cert: "path_to_cert_file",
                                                  ssl_key: "path_to_key_file"});

18.2.2 MySQL Shell Sessions
---------------------------

This section explains the different types of sessions in MySQL Shell and
how to create and configure them.

18.2.2.1 MySQL Shell Sessions Explained
.......................................

MySQL Shell is a unified interface to operate MySQL Server through
scripting languages such as JavaScript or Python.  To maintain
compatibility with previous versions, SQL can also be executed in
certain modes.  A connection to a MySQL server is required.  In MySQL
Shell these connections are handled by a _Session_ object.

The following types of Session object are available:

   * _NodeSession_: Use this session type for new application
     development to communicate with MySQL server instances which have
     the X Protocol enabled.  It offers the best integration with MySQL
     Server, and therefore, it is used by default.

   * _ClassicSession_ Use this session type to interact with MySQL
     Servers that do not have the X Protocol enabled.  The development
     API available for this type of session is very limited.  For
     example, there are no CRUD operations, no collection handling, and
     binding is not supported.

*Choosing a MySQL Shell Session Type*

MySQL Shell creates a Session object by default.  You can either
configure the session type using MySQL Shell command options, the
'scheme' element of a URI type string, or provide an option to the
'\connect' command.  To choose which type of session should be created
when starting MySQL Shell, use one of these options:

   * '--sqln' creates a Node session, connected using X Protocol.

   * '--sqlc' creates a ClassicSession, connected using MySQL protocol.

To choose which type of session to use when defining a URI type string
use one of these options:

   * Specify 'mysqlx' to create an X Protocol session.  The X Plugin
     must be installed on the server instance, see
     document-store for more information.

   * Specify 'mysql' to create a classic MySQL protocol session.

For more information, see mysql-shell-connection-using-uri.

*Creating a Session Using Shell Commands*

If you open MySQL Shell without specifying connection parameters, MySQL
Shell opens without an established global session.  It is possible to
establish a global session once MySQL Shell has been started using the
MySQL Shell '\connect URI' command, where URI is a URI type string as
defined at mysql-shell-connection-using-uri.  For example:

   * '\connect URI': Creates a Node session.  Attempts to use X Protocol
     by default, and falls back to MySQL protocol.

   * '\connect -n URI': Creates a Node session.

   * '\connect -c URI': Creates a ClassicSession using MySQL protocol.

For example:

     	mysql-js> \connect mysqlx://user@localhost:33060

Alternatively, use the 'shell.connect('URI'' method.  For example this
is equivalent to the above '\connect>' command:

     mysql-js> shell.connect('mysqlx://user@localhost:33060')

18.2.3 MySQL Shell Global Variables
-----------------------------------

MySQL Shell reserves certain variables as global variables, which are
assigned to commonly used objects in scripting.  This section describes
the available global variables and provides examples of working with
them.  The global variables are:

   * 'session' represents the global session if one has been
     established.

   * 'db' represents a schema if one has been defined, for example by a
     URI type string.

   * 'dba' represents the AdminAPI, a component of InnoDB cluster which
     enables you to administer clusters of server instances.  See
     mysql-innodb-cluster-userguide.

   * 'shell' provides general purpose functions, for example to
     configure MySQL Shell.

*Important*:

These words are reserved and cannot be used, for example as names of
variables.

By using these global objects, MySQL Shell provides interactive error
resolution for common situations.  For example:

   * Attempting to use an undefined 'session' global variable.

   * Attempting to retrieve an nonexistent schema using 'session'.

   * Attempting to use an undefined 'db' global variable.

*Undefined Global Session*

The global 'session' variable is set when a global session is
established.  When a global session is established, issuing a 'session'
statement in MySQL Shell displays the session type and its URI as
follows:

     mysql-js> session
     <NodeSession:root@localhost:33060>
     mysql-js>

If no global session has been established, MySQL Shell displays the
following:

     mysql-js> session
     <Undefined>
     mysql-js>

If you attempt to use the 'session' variable when no global session is
established, interactive error resolution starts and you are prompted to
provide the required information to establish a global session.  If the
session is successfully established, it is assigned to the 'session'
variable.  The prompts are:

   * An initial prompt explains that no global session is established
     and asks if one should be established.

   * If you choose to set a global session, the session type is
     requested.

   * The URI type string to connect to the server instance is requested.
     See mysql-shell-connection-using-uri.

   * If required, a password is requested.

For example:

     mysql-js> session.uri
     The global session is not set, do you want to establish a session?

        1) MySQL Document Store Session through X Protocol
        2) Classic MySQL Session

     Please select the session type or ENTER to cancel: 2
     Please specify the MySQL server URI: root@localhost
     Enter password:
     root@localhost:
     mysql-js> session
     <ClassicSession:root@localhost:>

*Undefined db Variable*

The global 'db' variable is set when a global session is established and
a default schema is configured.  For example, using a URI type string
such as 'root@localhost/sakila' to establish a global session connected
to the MySQL Server at 'localhost', on port 33060, as the user 'root',
assigns the schema 'sakila' to the global variable 'db'.  Once a schema
is defined, issuing 'db' at the MySQL Shell prompt prints the schema
name as follows:

     mysql-js> db
     <Schema:world_x>
     mysql-js>

If there is no global session established, the following is displayed:

     mysql-js> db
     <Undefined>
     mysql-js>

If you attempt to use the 'db' variable when no global session has been
established, the following error is displayed:

     mysql-js> db.getCollections()
     LogicError: The db variable is not set, establish a global session first.
     at (shell):1:2
     in db.getCollections()
     ^

If a global session has been established but you attempt to use an
undefined 'db', interactive error resolution begins and you are prompted
to define an active schema by providing the schema name.  If this
succeeds the 'db' variable is set to the defined schema.  For example:

     mysql-js> db.getCollections()
     The db variable is not set, do you want to set the active schema? [y/N]:y
     Please specify the schema:world_x
     [
     <Collection:countryinfo>
     ]
     mysql-js> db
     <Schema:world_x>
     mysql-js>

*Retrieving an Nonexistent Schema*

If you attempt to use 'session' to retrieve an nonexistent schema,
interactive error resolution provides the option to create the schema.

     mysql-js> var mySchema = session.getSchema('my_test')
     The schema my_test does not exist, do you want to create it? [y/N]: y

     mysql-js> mySchema
     <Schema:my_test>
     mysql-js>

In all cases, if you do not provide the information required to resolve
each situation, a proper result of executing the requested statement on
an undefined variable is displayed.

18.3 MySQL Shell Code Execution
===============================

This section explains how code execution works in MySQL Shell.

18.3.1 Interactive Code Execution
---------------------------------

The default mode of MySQL Shell provides interactive execution of
database operations that you type at the command prompt.  These
operations can be written in JavaScript, Python or SQL depending on the
curent mysql-shell-active-language.  When executed, the results
of the operation are displayed on-screen.

As with any other language interpreter, MySQL Shell is very strict
regarding syntax.  For example, the following JavaScript snippet reads
and prints the documents in a collection:

     var mysqlx = require('mysqlx').mysqlx;
     var mySession = mysqlx.getSession('user:pwd@localhost');
     var result = mySession.world_x.countryinfo.find().execute();
     var record = result.fetchOne();
     while(record){
       print(record);
       record = result.fetchOne();
     }

As seen above, the call to 'find()' is followed by the 'execute()'
function.  CRUD database commands are only actually executed on the
MySQL Server when 'execute()' is called.  However, when working with
MySQL Shell interactively, 'execute()' is implicitly called whenever you
press 'Return' on a statement.  Then the results of the operation are
fetched and displayed on-screen.  The rules for when you need to call
'execute()' or not are as follows:

   * When using MySQL Shell in this way, calling 'execute()' becomes
     optional on:

        * 'Collection.add()'

        * 'Collection.find()'

        * 'Collection.remove()'

        * 'Collection.modify()'

        * 'Table.insert()'

        * 'Table.select()'

        * 'Table.delete()'

        * 'Table.update()'

        * 'NodeSession.sql()'

   * Automatic execution is disabled if the object is assigned to a
     variable.  In such a case calling 'execute()' is mandatory to
     perform the operation.

   * When a line is processed and the function returns any of the
     available 'Result' objects, the information contained in the Result
     object is automatically displayed on screen.  The functions that
     return a Result object include:

        * The SQL execution and CRUD operations (listed above)

        * Transaction handling and drop functions of the session objects
          in both mysql and mysqlx modules: -

             * 'startTransaction()'

             * 'commit()'

             * 'rollback()'

             * 'dropSchema()'

             * 'dropTable()'

             * 'dropCollection()'

             * 'dropView()'

             * 'ClassicSession.runSql()'

Based on the above rules, the statements needed in the MySQL Shell in
interactive mode to establish a session, query, and print the documents
in a collection are:

     mysql-js> var mysqlx = require('mysqlx').mysqlx;
     mysql-js> var mySession = mysqlx.getSession('user:pwd@localhost');

No call to 'execute()' is needed and the Result object is automatically
printed.

     mysql-js> mySession.world_x.countryinfo.find();

*Formatting Results Vertically*

When executing SQL using MySQL Shell you can display results in a
column-per-row format with the '\G' command, in a similar way to
'mysql'.  If a statement is terminated with '\G' instead of the
active delimiter (which defaults to ';'), it is executed by the server
and the results are displayed in vertical format, regardless of the
current default output format.  For example issuing a statement such as

     SELECT * FROM mysql.user \G

displays the results vertically.

Multiple SQL statements on the same line which are separated by '\G' are
executed separately as if they appeared one per line., for example

     select 1\Gselect 2\Gselect 3\G

In other words '\G' functions as a normal delimiter.

18.3.2 Batch Code Execution
---------------------------

As well as interactive code execution, MySQL Shell provides batch code
execution from:

   * A file loaded for processing.

   * A file containing code that is redirected to the standard input for
     execution.

   * Code from a different source that is redirected to the standard
     input for execution.

The input is processed based on the current programming language
selected in MySQL Shell, which defaults to JavaScript.  For example:

Loading JavaScript code from a file for batch processing.

     shell> mysqlsh --file code.js

Redirecting a JavaScript file to standard input for execution.

     shell> mysqlsh < code.js

Redirecting SQL to standard input for execution.

     shell> echo "show databases;" | mysqlsh --sql --uri root@198.51.100.141:33060

*Executable Scripts*

Starting with version 1.0.4, on Linux you can create executable scripts
that run with MySQL Shell by including a '#!' line as the first line of
the script.  This line should provide the full path to MySQL Shell and
include the '--file' option.  For example:

     #!/usr/local/mysql-shell/bin/mysqlsh --file
     print("Hello World\n");

The script file must be marked as executable in the filesystem.  Running
the script invokes MySQL Shell and it executes the contents of the
script.

18.3.3 Output Formats
---------------------

The output of the commands processed on the server can be formatted in
different ways.  This section details the different available output
formats.

18.3.3.1 Table Format
.....................

The table format is used by default when MySQL Shell is in interactive
mode.  The output is presented as a formatted table for a better view
and to aid analysis.

     mysql-sql> select * from sakila.actor limit 3;
     +----------+-------------+----------------+----------------------+
     | actor_id | first_name  | last_name      | last_update          |
     +----------+-------------+----------------+----------------------+
     |        1 | PENELOPE    | GUINESS        | 2006-02-15 4:34:33   |
     |        2 | NICK        | WAHLBERG       | 2006-02-15 4:34:33   |
     |        3 | ED          | CHASE          | 2006-02-15 4:34:33   |
     +----------+-------------+----------------+----------------------+
     3 rows in set (0.00 sec)

     mysql-sql>

To get this output format when running in batch mode, use the '--table'
command-line option.

18.3.3.2 Tab Separated Format
.............................

This format is used by default when running MySQL Shell in batch mode,
to have better output for automated analysis.

     >echo "select * from sakila.actor limit 3;" | mysqlsh --classic --uri root@198.51.100.141:33460
     actor_id        first_name      last_name       last_update
     1       PENELOPE        GUINESS 2006-02-15 4:34:33
     2       NICK    WAHLBERG        2006-02-15 4:34:33
     3       ED      CHASE   2006-02-15 4:34:33

18.3.3.3 JSON Format Output
...........................

MySQL Shell supports the JSON format for output and it is available both
in interactive and batch mode.  This output format can be enabled using
the '--json' command-line option:

_JSON Format in Batch Mode_

     shell>echo "select * from sakila.actor limit 3;" | mysqlsh --json --sqlc --uri root@198.51.100.141:3306
     {"duration":"0.00 sec","info":"","row_count":3,"rows":[[1,"PENELOPE","GUINESS",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[2,"NICK","WAHLBERG",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[3,"ED","CHASE",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}]],"warning_count":0}

     shell>echo "select * from sakila.actor limit 3;" | mysqlsh --json=raw --sqlc --uri root@198.51.100.141:3306
     {"duration":"0.00 sec","info":"","row_count":3,"rows":[[1,"PENELOPE","GUINESS",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[2,"NICK","WAHLBERG",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[3,"ED","CHASE",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}]],"warning_count":0}

     shell>echo "select * from sakila.actor limit 3;" | mysqlsh --json=pretty --sqlc --uri root@198.51.100.141:3306
     {
         "duration": "0.00 sec",
         "info": "",
         "row_count": 3,
         "rows": [
             [
                 1,
                 "PENELOPE",
                 "GUINESS",
                 {
                     "year": 2006,
                     "month": 1,
                     "day": 15,
                     "hour": 4,
                     "minute": 34,
                     "second": 33.0
                 }
             ],
             [
                 2,
                 "NICK",
                 "WAHLBERG",
                 {
                     "year": 2006,
                     "month": 1,
                     "day": 15,
                     "hour": 4,
                     "minute": 34,
                     "second": 33.0
                 }
             ],
             [
                 3,
                 "ED",
                 "CHASE",
                 {
                     "year": 2006,
                     "month": 1,
                     "day": 15,
                     "hour": 4,
                     "minute": 34,
                     "second": 33.0
                 }
             ]
         ],
         "warning_count": 0
     }
     shell>

_JSON Format in Interactive Mode (started with -json=raw)_

     mysql-sql> select * from sakila.actor limit 3;
     {"duration":"0.00 sec","info":"","row_count":3,"rows":[[1,"PENELOPE","GUINESS",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[2,"NICK","WAHLBERG",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[3,"ED","CHASE",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}]],"warning_count":0}

     mysql-sql>

_JSON Format in Interactive Mode (started with -json=pretty)_

     mysql-sql> select * from sakila.actor limit 3;
     {
         "duration": "0.00 sec",
         "info": "",
         "row_count": 3,
         "rows": [
             [
                 1,
                 "PENELOPE",
                 "GUINESS",
                 {
                     "year": 2006,
                     "month": 1,
                     "day": 15,
                     "hour": 4,
                     "minute": 34,
                     "second": 33.0
                 }
             ],
             [
                 2,
                 "NICK",
                 "WAHLBERG",
                 {
                     "year": 2006,
                     "month": 1,
                     "day": 15,
                     "hour": 4,
                     "minute": 34,
                     "second": 33.0
                 }
             ],
             [
                 3,
                 "ED",
                 "CHASE",
                 {
                     "year": 2006,
                     "month": 1,
                     "day": 15,
                     "hour": 4,
                     "minute": 34,
                     "second": 33.0
                 }
             ]
         ],
         "warning_count": 0
     }

     mysql-sql>

18.3.3.4 Result Metadata
........................

When an operation is executed, in addition to any results returned, some
additional information is available.  This includes information such as
the number of affected rows, warnings, duration, and so on, when any of
these conditions is true:

   * JSON format is being used for the output

   * MySQL Shell is running in interactive mode.

18.3.4 Active Language
----------------------

MySQL Shell can execute SQL, JavaScript or Python code, but only one
language can be active at a time.  The active mode determines how the
executed statements are processed:

   * If using SQL mode, statements are processed as SQL which means they
     are sent to the MySQL server for execution.

   * If using JavaScript mode, statements are processed as JavaScript
     code.

   * If using Python mode, statements are processed as Python code.

When running MySQL Shell in interactive mode, activate a specific
language by entering the commands: '\sql', '\js', '\py'.

When running MySQL Shell in batch mode, activate a specific language by
passing any of these command-line options: '--js', '--py' or '--sql'.
The default mode if none is specified is JavaScript.

Use MySQL Shell to execute the content of the file 'code.sql' as SQL.

     shell> mysqlsh --sql < code.sql

Use MySQL Shell to execute the content of the file 'code.js' as
JavaScript code.

     shell> mysqlsh < code.js

Use MySQL Shell to execute the content of the file 'code.py' as Python
code.

     shell> mysqlsh --py < code.py

18.3.5 Batch Mode Made Interactive
----------------------------------

This section describes code execution in batch mode.

   * In batch mode, all the command logic described above is not
     available, only valid code for the active language can be executed.

   * When processing SQL code, it is executed statement by statement
     using the following logic: read/process/print result.

   * When processing non-SQL code, it is loaded entirely from the input
     source and executed as a unit.

Use the '--interactive' (or '-i') command-line option to configure MySQL
Shell to process the input source as if it were being issued in
interactive mode; this enables all the features provided by the
Interactive mode to be used in batch processing.

*Note*:

In this case, whatever the source is, it is read line by line and
processed using the interactive pipeline.

18.3.5.1 Multiple-line Support
..............................

It is possible to specify statements over multiple lines.  When in
Python or JavaScript mode, multiple-line mode is automatically enabled
when a block of statements starts like in function definitions, if/then
statements, for loops, and so on.  In SQL mode multiple line mode starts
when the command '\' is issued.

Once multiple-line mode is started, the subsequently entered statements
are cached.

For example:

     mysql-sql> \
     ... create procedure get_actors()
     ... begin
     ...   select first_name from sakila.actor;
     ... end
     ...
     mysql-sql>

18.4 Configuring MySQL Shell
============================

This section explains how to configure MySQL Shell using commands
executable from the interactive code editor and command options.  For a
description of MySQL Shell command options, see mysqlsh.

18.4.1 MySQL Shell Commands
---------------------------

MySQL Shell provides commands which enable you to modify the execution
environment of the code editor, for example to configure the active
programming language or a MySQL Server connection.  The following table
lists the commands that are available regardless of the currently
selected language.  As commands need to be available independent of the
_execution mode_, they start with an escape sequence, the '\' character.

Command        Alias/Shortcut Description

'\help'        '\h' or '\?'   Prints help about MySQL Shell commands.

'\quit'        '\q' or        Exit MySQL Shell.
               '\exit'

'\'                           In SQL mode, begin multiple-line mode.
                              Code is cached and executed when an empty
                              line is entered.

'\status'      '\s'           Show the current MySQL Shell status.

'\js'                         Switch execution mode to JavaScript.

'\py'                         Switch execution mode to Python.

'\sql'                        Switch execution mode to SQL.

'\connect'     '\c'           Connect to a MySQL Server with a URI
                              using an Node session (X Protocol).

'\connect_node''\cn'          (Removed in version 1.0.4, use '\connect
                              -n') Connect to a MySQL Server with a URI
                              using a Node session.

'\connect_classic''\cc'       (Removed in version 1.0.4, use '\connect
                              -c') Connect to a MySQL Server with a URI
                              using a Classic session (MySQL Protocol).

'\use'                        Specify the schema to use.

'\source'      '\.'           Execute a script file using the active
                              language.

'\warnings'    '\W'           Show any warnings generated by a
                              statement.

'\nowarnings'  '\w'           Do not show any warnings generated by a
                              statement.

'\lsconn'      '\lsc'         Print the connection data for the stored
                              sessions.

'\saveconn'    '\savec'       Save connection data of a session,
                              optionaly use '-f' to force overwriting
                              an existing connection.

'\addconn'     '\addc'        (Removed in version 1.0.4, see
                              '\saveconn') Store the connection data of
                              a session.

'\rmconn'                     Removes a stored session.

'\chconn'                     (Removed in version 1.0.4, see
                              '\saveconn') Updates a stored session.

*Help Command*

The '\help' command can be used with or without parameters.  When used
without parameters a general help is printed including information
about:

   * Available commands.

   * Available commands for the active mode.

When used with a parameter, the parameter must be a valid command.  If
that is the case, help for that specific command is printed including:

   * Description

   * Supported aliases if any

   * Additional help if any

For example:

     \help connect

If the parameter is not a valid command, the general help is printed.

*Connect Command*

The '\connect' command is used to connect to a MySQL Server using an URI
type string.  See mysql-shell-connection-using-uri.

For example:

     \connect root@localhost:3306

If a password is required you are prompted for it.

Use the '-n' option to create a Node session, using the X Protocol to
connect to a single server.  For example:

     \connect -n root@localhost:3306

Use the '-c' option to create a Classic session, enabling you to use the
MySQL Protocol to issue SQL commands directly on a server.  For example:

     \connect -c root@localhost:3306

*Status Command*

The '\status' command displays information about the current global
connection.  This includes information about the server connected to,
the character set in use, uptime, and so on.

*Source Command*

The '\source' command is used to execute code from a script at a given
path.  For example:

     \source /tmp/mydata.sql

You can execute either SQL, JavaScript or Python code.  The code in the
file is executed using the active language, so to process SQL code the
MySQL Shell must be in SQL mode.

*Warning*:

As the code is executed using the active language, executing a script in
a different language than the currently selected execution mode language
could lead to unexpected results.

*Use Command*

The '\use' command enables you to choose which schema is active, for
example:

     \use SCHEMA_NAME

The '\use' command requires a global development session to be active.
The '\'use command sets the current schema to the specified SCHEMA_NAME
and updates the 'db' variable to the object that represents the selected
schema.

18.5 MySQL Shell Application Log
================================

This section explains the logging provided by MySQL Shell, where to find
logs and how to configure the level of logging.

MySQL Shell can be configured to generate an application log file with
information about issues of varying severity.  You can use this
information to verify the state of MySQL Shell while it is running.  The
log format is plain text and entries contain a timestamp and description
of the problem.  For example:

     2016-04-05 22:23:01: Error: Default Domain: (shell):1:8: MySQLError: You have an error
     in your SQL syntax; check the manual that corresponds to your MySQL server version for
     the right syntax to use near '' at line 1 (1064) in session.sql("select * from t
     limit").execute().all();

The amount of information to add to the log can be configured using
'--log-level'.  See mysql-shell-application-log-configure.

*MySQL Shell Log File Location*

The location of the log file is the user configuration path and the file
is named 'mysqlsh.log'.

*Log File on Windows*

On Windows, the default path to the log file is
'%APPDATA%\MySQL\mysqlsh\mysqlsh.log'

To find the location of '%APPDATA%' on your system, echo it from the
comand-line.  For example:

     C:>echo %APPDATA%
     C:\Users\exampleuser\AppData\Roaming

On Windows, the path is determined by the result of gathering the
'%APPDATA%' folder specific to that user, and then appending
'MySQL\mysqlsh'.  Using the above example results in
'C:\Users\exampleuser\AppData\Roaming\MySQL\mysqlsh\mysqlsh.log'.

*Log File on Unix-based Systems*

For a machine running Unix, the default path is '~/.mysqlsh/mysqlsh.log'
where '~' represents your home directory.  The environment variable HOME
also represents the home directory.  Appending '.mysqlsh' to the this
home directory determines the default path to the logs.  For example:

     shell>echo $HOME
     /home/exampleuser

Therefore the location of the MySQL Shell file on this system is
'/home/exampleuser/.mysqlsh/mysqlsh.log'.

These paths can be overridden on all platforms by defining the
environment variable 'MYSQL_USER_CONFIG_PATH'.  The value of this
variable replaces '%APPDATA%' in Windows or '$HOME' in Unix.

*Configuring Logging*

By default, logging is disabled in MySQL Shell.  To enable logging use
the '--log-level' command option when starting MySQL Shell.  The value
assigned to '--log-level' controls the level of detail in the log.  The
level of logging can be defined using either numeric levels from 1 to 8,
or equivalent named levels as shown in the following table.

Log Level Number         Log Level Name           Meaning

1                        none                     No logging, the
                                                  default

2                        internal                 Internal Error

3                        error                    Errors are logged

4                        warning                  Warnings are logged

5                        info                     Information is logged

6                        debug                    Debug information is
                                                  logged

7                        debug2                   Debug with more
                                                  information is logged

8                        debug3                   Debug with full
                                                  information is logged

The numeric and named levels are equivalent.  For example there is no
difference in logging when starting MySQL Shell in either of these ways:

     shell>mysqlsh --log-level=4
     shell>mysqlsh --log-level=warning

18.6 Customizing MySQL Shell
============================

MySQL Shell offers the ability to customize the behavior and code
execution environment through startup scripts, which are executed when
the application is first run.  Using such scripts enables you to:

   * Add additional search paths for Python or JavaScript modules.

   * Override the default prompt used by the Python and JavaScript
     modes.

   * Define global functions or variables.

   * Any other possible initialization through JavaScript or Python.

18.6.1 Working With Start-Up Scripts
------------------------------------

When MySQL Shell enters either into JavaScript or Python mode, it
searches for startup scripts to be executed.  The startup scripts are
JavaScript or Python specific scripts containing the instructions to be
executed when the corresponding mode is initialized.

Startup scripts must be named as follows:

   * For JavaScript mode: 'mysqlshrc.js'

   * For Python mode: 'mysqlshrc.py'

MySQL Shell searches the following paths for these files (in order of
execution).

On Windows:

  1. '%PROGRAMDATA%MySQLmysqlshmysqlshrc.[js|py]'

  2. '%MYSQLSH_HOME%sharedmysqlshmysqlshrc.[js|py]'

  3. '<mysqlsh binary path>mysqlshrc.[js|py]'

  4. '%APPDATA%MySQLmysqlshmysqlshrc.[js|py]'

On Linux and OSX:

  1. '/etc/mysql/mysqlsh/mysqlshrc.[js|py]'

  2. '$MYSQLSH_HOME/shared/mysqlsh/mysqlshrc.[js|py]'

  3. '<mysqlsh binary path>/mysqlshrc.[js|py]'

  4. '$HOME/.mysqlsh/mysqlshrc.[js|py]'

The environment variable 'MYSQLSH_HOME' defines the root folder of a
standard setup of MySQL Shell.  If 'MYSQLSH_HOME' is not defined it is
automatically calculated based on the location of the MySQL Shell
binary, therefore on many standard setups it is not required to define
'MYSQLSH_HOME'.

If 'MYSQLSH_HOME' is not defined and the MySQL Shell binary is not in a
standard install folder structure, then the path defined in option 3 in
the above lists is used.  If using a standard install or if
'MYSQLSH_HOME' points to a standard install folder structure, then the
path defined in option 3 is not used.

*Warning*:

The lists above also define the order of searching the paths, so if
something is defined in two different scripts, the script executed later
takes precedence.

18.6.2 Adding Module Search Paths
---------------------------------

There are two ways to add additional module search paths:

   * Through environment variables

   * Through startup scripts

18.6.2.1 Environment Variables
..............................

Python uses the 'PYTHONPATH' environment variable to allow extending the
search paths for python modules.  The value of this variable is a list
of paths separated by:

   * A colon character in Linux and OSX

   * A semicolon character in Windows

To achieve this in JavaScript, MySQL Shell supports defining additional
JavaScript module paths using the 'MYSQLSH_JS_MODULE_PATH' environment
variable.  The value of this variable is a list of semicolon separated
paths.

18.6.2.2 Startup Scripts
........................

The addition of module search paths can be achieved for both languages
through the corresponding startup script.

For Python modify the 'mysqlshrc.py' file and append the required paths
into the 'sys.path' array.

     # Import the sys module
     import sys

     # Append the additional module paths
     sys.path.append('~/custom/python')
     sys.path.append('~/other/custom/modules')

For JavaScript the same task is achieved by adding code into the
'mysqlshrc.js' file to append the required paths into the predefined
'shell.js_module_paths' array.

     // Append the additional module paths
     shell.js.module_paths[shell.js.module_paths.length] = '~/custom/js';
     shell.js.module_paths[shell.js.module_paths.length] = '~/other/custom/modules';

18.6.3 Overriding the Default Prompt
------------------------------------

MySQL Shell uses a default prompt for both Python ( 'mysql-py>' ) and
JavaScript ( 'mysql-js>' ).

You can customize the language specific prompt using the
'shell.custom_prompt()' function.  This function must return a string
that is used as the prompt.  To have a custom prompt when MySQL Shell
starts, define this function in a startup script.  The following example
shows how this functionality can be used.

In Python 'shell.custom_prompt()' could be defined as:

     # Import the sys module
     from time import gmtime, strftime

     def my_prompt():
       ret_val = strftime("%H:%M:%S", gmtime())

       if session and session.isOpen():
         data = shell.parseUri(session.getUri())

         ret_val = "%s-%s-%s-py> " % (ret_val, data.dbUser, data.host)
       else:
         ret_val = "%s-disconnected-py> " % ret_val

       return ret_val

     shell.custom_prompt = my_prompt

In JavaScript 'shell.custom_prompt()' could be defined as:

     shell.custom_prompt = function(){
       var now = new Date();

       var ret_val = now.getHours().toString()+ ":" + now.getMinutes().toString() + ":" + now.getSeconds().toString();

       if (session && session.isOpen()){
         var data = shell.parseUri(session.getUri());

         ret_val += "-" + data.dbUser + "-" + data.host + "-js> ";
       }
       else
         ret_val += "-disconnected-js> ";

       return ret_val;
     }

The following example demonstrates using the custom prompt functions
defined above in startup script.  The prompts show the current system
time, and if a session is open the current user and host:

     Welcome to MySQL Shell 1.0.4 Development Preview

     Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.

     Oracle is a registered trademark of Oracle Corporation and/or its
     affiliates. Other names may be trademarks of their respective
     owners.

     Type '\help', '\h' or '\?' for help.

     Currently in JavaScript mode. Use \sql to switch to SQL mode and execute queries.
     14:34:32-disconnected-js> \py
     Switching to Python mode...

     19:34:39-disconnected-py> \connect root:@localhost
     Creating an X Session to root@localhost:33060
     No default schema selected.

     19:34:50-root-localhost-py> \js
     Switching to JavaScript mode...
     14:34:57-root-localhost-js>

19 Using MySQL as a Document Store
**********************************

This chapter introduces an alternative way of working with MySQL as a
document store, sometimes referred to as 'using NoSQL'.  If your
intention is to use MySQL in a traditional (SQL) way, this chapter is
probably not relevant to you.

Using MySQL as a document store is currently a preproduction feature to
which this notice applies: document-store-legalnotice.

Relational databases such as MySQL usually required a document schema to
be defined before documents can be stored.  The features described in
this section enable you to use MySQL as a document store, which is a
schema-less, and therefore schema-flexible, storage system for
documents.  When using MySQL as a document store, to create documents
describing products you do not need to know and define all possible
attributes of any products before storing them and operating with them.
This differs from working with a relational database and storing
products in a table, when all columns of the table must be known and
defined before adding any products to the database.  The features
described in this chapter enable you to choose how you configure MySQL,
using only the document store model, or combining the flexibility of the
document store model with the power of the relational model.

These sections cover the usage of MySQL as a document store:

   * The document-store-concepts section covers concepts like
     Document, Collection, Session, and Schema to help you understand
     how to use MySQL as a document store.

   * The document-store-setting-up section explains how to
     configure X Plugin on a MySQL Server, so it can function as a
     document store, and how to install MySQL Shell to use as a client.

   * The MySQL Shell is an interactive interface to MySQL supporting
     JavaScript, Python, or SQL modes.  You can use the MySQL Shell to
     prototype applications, execute queries and update data.  The
     _quick-start guides (tutorials)_ help you to get started using
     MySQL Shell.

     The quick-start guide for JavaScript is here:
     mysql-shell-tutorial-javascript.

     The quick-start guide for Python is here:
     mysql-shell-tutorial-python.

   * mysql-shell provides more detailed information about using
     MySQL Shell.

   * _X DevAPI User guide._

     Clients that communicate with a MySQL Server using the X Protocol
     can use the X DevAPI to develop applications.  For example MySQL
     Shell and MySQL Connectors provide this ability by implementing the
     X DevAPI. X DevAPI offers a modern programming interface with a
     simple yet powerful design which provides support for established
     industry standard concepts.  See X DevAPI User Guide
     (http://dev.mysql.com/doc/x-devapi-userguide/en/) for in-depth
     tutorials on using X DevAPI.

   * The following MySQL Connectors support the X Protocol and enable
     you to use X DevAPI in your chosen language to develop applications
     that communicate with a MySQL Server functioning as a document
     store.

        * MySQL Shell X DevAPI and AdminAPI reference: JavaScript
          (http://dev.mysql.com/doc/dev//mysqlsh-api-javascript/1.0/)
          and Python
          (http://dev.mysql.com/doc/dev//mysqlsh-api-python/1.0/).

        * MySQL Connector/J X DevAPI Reference
          (http://dev.mysql.com/doc/dev/connector-j/)

        * MySQL Connector/Node.js X DevAPI Reference
          (http://dev.mysql.com/doc/dev/connector-nodejs/)

        * MySQL Connector/Net X DevAPI Reference
          (http://dev.mysql.com/doc/dev/connector-net/)

        * MySQL Connector/Python X DevAPI Reference
          (http://dev.mysql.com/doc/dev/connector-python/)

        * MySQL Connector/C++ X DevAPI and XAPI Reference
          (http://dev.mysql.com/doc/dev/connector-cpp/)

     Each implementation of X DevAPI provides library reference
     documentation, available at the above links.

19.1 Preproduction Status -- Legal Notice
=========================================

This documentation is in preproduction status and is intended for
demonstration and preliminary use only.  It may not be specific to the
hardware on which you are using the software.  Oracle Corporation and
its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to this documentation and will not
be responsible for any loss, costs, or damages incurred due to the use
of this documentation.

19.2 Key Concepts
=================

This section explains the concepts introduced as part of using MySQL as
a document store.

*Document*

A Document is a set of key and value pairs, as represented by a JSON
object.  A Document is represented internally using the MySQL binary
JSON object, through the JSON MySQL datatype.  The values of fields can
contain other documents, arrays, and lists of documents.

     {
         "GNP": .6,
         "IndepYear": 1967,
         "Name": "Sealand",
         "_id": "SEA",
         "demographics": {
             "LifeExpectancy": 79,
             "Population": 27
         },
         "geography": {
             "Continent": "Europe",
             "Region": "British Islands",
             "SurfaceArea": 193
         },
         "government": {
             "GovernmentForm": "Monarchy",
             "HeadOfState": "Michael Bates"
         }
     }

*Collection*

A Collection is a container that may be used to store Documents in a
MySQL database.

*CRUD Operations*

Create, Read, Update and Delete (CRUD) operations are the four basic
operations that can be performed on a database Collection or Table.  In
terms of MySQL this means:

   * Create a new entry (insertion or addition)

   * Read entries (queries)

   * Update entries

   * Delete entries

*X Plugin*

The MySQL Server plugin which enables communication using X Protocol.
Supports clients that implement X DevAPI and enables you to use MySQL as
a document store.

*X Protocol*

A protocol to communicate with a MySQL Server running X Plugin.  X
Protocol supports both CRUD and SQL operations, authentication via SASL,
allows streaming (pipelining) of commands and is extensible on the
protocol and the message layer.

19.3 Setting Up MySQL as a Document Store
=========================================

This section describes how to install the X Plugin to enable MySQL
Server to use the X Protocol and use MySQL Shell to act as a client to
the server.

The prerequisite for using MySQL as a document store is the X Plugin,
which implements the X Protocol.  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.

Setting up MySQL as a document store follows the steps outlined here:

  1. *Install or upgrade to MySQL 5.7.12 or higher.*

     When the installation or upgrade is done, start
     the server.  For server startup instructions, see
     starting-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 the 'Plugin and Extensions' screen, check
     mark the 'Enable 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 has 'INSERT' privilege for the
     'mysql.plugin' table.

     Always save your existing configuration settings before
     reconfiguring the server.

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

        * Using MySQL Installer for Windows.:

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

            2. Click the 'Reconfigure' quick action for MySQL Server.
               Use 'Next' and 'Back' to configure the following items:

                  * In 'Accounts and Roles', confirm the current 'root'
                    account password.

                  * In 'Plugin and Extensions', check mark the 'Enable X
                    Protocol/MySQL as a Document Store' check box.
                    MySQL Installer provides a default port number and
                    opens the firewall port for network access.

                  * In 'Apply Server Configuration', click 'Execute'.

                  * Click 'Finish' 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 -u USER -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 the 'mysql' command-line client:

                    mysql -u USER -p

            3. Issue the following statement:

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

               Replace 'mysqlx.so' with 'mysqlx.dll' for Windows.

               *Important*:

               The 'mysql.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 the 'mysql_upgrade'
               procedure.  If the upgrade is not run, X
               Plugin fails to start with the error message 'There 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 -u USER --sqlc -e "show plugins"

        * MySQL Client program command:

               mysql -u USER -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, see server-plugin-loading.

*'mysqlxsys@localhost' User Account*

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

The X Plugin installation process uses the MySQL 'root' user to create
an internal account for the 'mysqlxsys@localhost' user.  The
'mysqlxsys@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.  The 'mysqlxsys@localhost'
account is created as locked, so it cannot be used to log in by external
users.  If for some reason the MySQL 'root' account is not available,
before you start the X Plugin installation you must manually create the
'mysqlxsys@localhost' user by issuing the following statements in the
'mysql' command-line client:

     CREATE USER IF NOT EXISTS mysqlxsys@localhost IDENTIFIED WITH
     mysql_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 the 'mysql' 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.

19.3.1 Installing MySQL Shell
-----------------------------

This section describes how to download, install, and start MySQL Shell,
which is an interactive JavaScript, Python, or SQL interface supporting
development and administration for the MySQL Server.  MySQL Shell is a
component that you can install separately.

*Requirements*

MySQL Shell is available on Microsoft Windows, Linux, and OS X for
64-bit platforms.  MySQL Shell requires that the built-in X Plugin be
active.  You can install the server plugin before or after you install
MySQL Shell.  For instructions, see Installing the X Plugin.

19.3.1.1 Installing MySQL Shell on Microsoft Windows
....................................................

*Important*:

The Community version of MySQL Shell requires the Visual C++
Redistributable for Visual Studio 2013 (available at the Microsoft
Download Center (http://www.microsoft.com/en-us/download/default.aspx))
to work; make sure that is installed on your Windows system before
installing MySQL Shell.

*Note*:

MySQL Shell is currently not supplied with an MSI Installer.  See
installing-mysql-shell-binaries for the manual install procedure.

To install MySQL Shell on Microsoft Windows using the MSI Installer, do
the following:

  1. Download the *Windows (x86, 64-bit), MSI Installer* package from
     <http://dev.mysql.com/downloads/shell/>.

  2. When prompted, click 'Run'.

  3. Follow the steps in the Setup Wizard.

     FIGURE GOES HERE: Installation of MySQL Shell on Windows

If you have installed MySQL without enabling the X Plugin, then later on
decide you want to install the X Plugin, or if you are installing MySQL
_without_ using MySQL Installer, see Installing the X Plugin.

*Installing MySQL Shell Binaries*

To install MySQL Shell binaries:

  1. Unzip the content of the Zip file to the MySQL products directory,
     for example 'C:\Program Files\MySQL\'.

  2. To be able to start MySQL Shell from a command prompt add the bin
     directory 'C:\Program
     Files\MySQL\mysql-shell-1.0.8-rc-windows-x86-64bit\bin' to the
     'PATH' system variable.

19.3.1.2 Installing MySQL Shell on Linux
........................................

*Note*:

Installation packages for MySQL Shell are available only for a limited
number of Linux distributions, and only for 64-bit systems.

For supported Linux distributions, the easiest way to install MySQL
Shell on Linux is to use the MySQL APT repository
(http://dev.mysql.com/downloads/repo/apt/) or MySQL Yum repository
(http://dev.mysql.com/downloads/repo/yum/).  For systems not using the
MySQL repositories, MySQL Shell can also be downloaded and installed
directly.

*Installing MySQL Shell with the MySQL APT Repository*

For Linux distributions supported by the MySQL APT repository
(http://dev.mysql.com/downloads/repo/apt/), follow one of the paths
below:

   * If you do not yet have the MySQL APT repository
     (http://dev.mysql.com/downloads/repo/apt/) as a software repository
     on your system, do the following:

        * Follow the steps given in Adding the MySQL APT Repository
          (http://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/#apt-repo-setup),
          paying special attention to the following:

             * During the installation of the configuration package,
               when asked in the dialogue box to configure the
               repository, make sure you choose MySQL 5.7 (which is the
               default option) as the release series you want, and
               enable the 'MySQL Preview Packages' component.

             * Make sure you do not skip the step for updating package
               information for the MySQL APT repository:

                    sudo apt-get update

        * Install MySQL Shell with this command:

               sudo apt-get install mysql-shell

   * If you already have the MySQL APT repository
     (http://dev.mysql.com/downloads/repo/apt/) as a software repository
     on your system, do the following:

        * Update package information for the MySQL APT repository:

               sudo apt-get update

        * Update the MySQL APT repository configuration package with the
          following command:

               sudo apt-get install mysql-apt-config

          When asked in the dialogue box to configure the repository,
          make sure you choose MySQL 5.7 (which is the default option)
          as the release series you want, and enable the 'MySQL Preview
          Packages' component.

        * Install MySQL Shell with this command:

               sudo apt-get install mysql-shell

*Installing MySQL Shell with the MySQL Yum Repository*

For Linux distributions supported by the MySQL Yum repository
(http://dev.mysql.com/downloads/repo/yum/), follow these steps to
install MySQL Shell:

   * Do one of the following:

        * If you already have the MySQL Yum repository
          (http://dev.mysql.com/downloads/repo/yum/) as a software
          repository on your system and the repository was configured
          with the new release package 'mysql57-community-release', skip
          to the next step ('Enable the MySQL Tools Preview
          subrepository...').

        * If you already have the MySQL Yum repository
          (http://dev.mysql.com/downloads/repo/yum/) as a software
          repository on your system but have configured the repository
          with the old release package 'mysql-community-release', it is
          easiest to install MySQL Shell by first reconfiguring the
          MySQL Yum repository with the new 'mysql57-community-release'
          package.  To do so, you need to remove your old release
          package first, with the following command :

               sudo yum remove mysql-community-release

          For dnf-enabled systems, do this instead:

               sudo dnf erase mysql-community-release

          Then, follow the steps given in Adding the MySQL Yum
          Repository
          (http://dev.mysql.com/doc/mysql-yum-repo-quick-guide/en/#repo-qg-yum-repo-setup)
          to install the new release package,
          'mysql57-community-release'.

        * If you do not yet have the MySQL Yum repository
          (http://dev.mysql.com/downloads/repo/yum/) as a software
          repository on your system, follow the steps given in Adding
          the MySQL Yum Repository
          (http://dev.mysql.com/doc/mysql-yum-repo-quick-guide/en/#repo-qg-yum-repo-setup).

   * Enable the MySQL Tools Preview subrepository.  You can do that by
     editing manually the '/etc/yum.repos.d/mysql-community.repo' file.
     This is an example of the subrepository's default entry in the file
     (the 'baseurl' entry in your file might look different, depending
     on your Linux distribution):

          [mysql-tools-preview]
          name=MySQL Tools Preview
          baseurl=http://repo.mysql.com/yum/mysql-tools-preview/el/6/$basearch/
          enabled=0
          gpgcheck=1
          gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-mysql

     Change the entry 'enabled=0' to 'enabled=1' to enable the
     subrepository.

   * Install MySQL Shell with this command:

          sudo yum install mysql-shell

     For dnf-enabled systems, do this instead:

          sudo dnf install mysql-shell

*Installing MySQL Shell from Direct Downloads from the MySQL Developer
Zone*

RPM, Debian, and source packages for installing MySQL Shell are also
available for download at Download MySQL Shell
(http://dev.mysql.com/downloads/shell/).

19.3.1.3 Installing MySQL Shell on OS X
.......................................

To install MySQL Shell on OS X, do the following:

  1. Download the package from <http://dev.mysql.com/downloads/shell/>.

  2. Double-click the downloaded DMG to mount it.  Finder opens.

  3. Double-click the '.pkg' file shown in the Finder window.

  4. Follow the steps in the installation wizard.

     FIGURE GOES HERE: Installation of MySQL Shell on OS X

  5. When the installer finishes, eject the DMG. (It can be deleted.)

19.3.2 Starting MySQL Shell
---------------------------

You need an account name and password to establish a session using MySQL
Shell.  Replace USER with your account name.

On the same system where the server instance is running, open a terminal
window (command prompt on Windows) and start MySQL Shell with the
following command:

     mysqlsh --uri USER@localhost

You are prompted to input your password and then this establishes an X
Session.

For instructions to get you started using MySQL Shell and MySQL as a
document store, see the following quick-start guides:

   * Quick-Start Guide.

   * Quick-Start Guide.

19.4 Quick-Start Guide: MySQL Shell for JavaScript
==================================================

This quick-start guide provides instructions to begin prototyping
database applications interactively with MySQL Shell.  The guide
includes the following topics:

   * Introduction to MySQL functionality, MySQL Shell, and the 'world_x'
     database sample.

   * Operations to manage collections and documents.

   * Operations to manage relational tables.

   * Operations that apply to documents within tables.

*Available Quick-Start Guides*

   * MySQL Shell for Python.

   * MySQL for Visual Studio.

*Related Information*

   * mysql-shell provides more in-depth information about MySQL
     Shell.

   * X DevAPI User Guide
     (http://dev.mysql.com/doc/x-devapi-userguide/en/) provides more
     examples of using X DevAPI.

19.4.1 Introduction
-------------------

The MySQL Shell for JavaScript quick start provides a short but
comprehensive introduction to the database functionality including the
new X DevAPI, which offers a modern, integrative way to work with
relational and document data, without requiring SQL knowledge from
application developers.

In MySQL, tables are the native data storage container type and
collections are stored internally using tables.

*JSON Documents and Collections*

A JSON document is a data structure composed of field/value pairs stored
within a collection.  The values of fields often contain other
documents, arrays, and lists of documents.

     {
         "GNP": .6,
         "IndepYear": 1967,
         "Name": "Sealand",
         "_id": "SEA",
         "demographics": {
             "LifeExpectancy": 79,
             "Population": 27
         },
         "geography": {
             "Continent": "Europe",
             "Region": "British Islands",
             "SurfaceArea": 193
         },
         "government": {
             "GovernmentForm": "Monarchy",
             "HeadOfState": "Michael Bates"
         }
     }

*Relational Tables*

A table in
MySQL enables you to store data organized in rows and columns.  The
structure of a table is defined by one or more columns with user-defined
names and data types.  Every row stored in the table has the same
structure.

     +------+------------------+-------------+-----------------+------------------------+
     | ID   | Name             | CountryCode | District        | Info                   |
     +------+------------------+-------------+-----------------+------------------------+
     |    1 | Kabul            | AFG         | Kabol           |{"Population": 1780000} |
     |    2 | Qandahar         | AFG         | Qandahar        |{"Population": 237500}  |
     |    3 | Herat            | AFG         | Herat           |{"Population": 186800}  |
     |    4 | Mazar-e-Sharif   | AFG         | Balkh           |{"Population": 127800}  |
     |    5 | Amsterdam        | NLD         | Noord-Holland   |{"Population": 731200}  |
     |    6 | Rotterdam        | NLD         | Zuid-Holland    |{"Population": 593321}  |
     +------+------------------+-------------+-----------------+------------------------+

*Related Information*

   * mysql-shell provides a general overview.

   * See X DevAPI User Guide
     (http://dev.mysql.com/doc/x-devapi-userguide/en/) for development
     reference documentation.

19.4.2 Import Database Sample
-----------------------------

The 'world_x' database sample contains one JSON collection and a set of
three relational tables:

   * Collection

        * countryinfo: Information about countries in the world.

   * Tables

        * country: Minimal information about countries of the world.

        * city: Information about some of the cities in those countries.

        * countrylanguage: Languages spoken in each country.

*Requirements*

You must install MySQL Shell with the X Protocol enabled.  For
instructions, see document-store-setting-up.

Start the server before you load the 'world_x' database for this guide.

*Download world_x Database*

To prepare the 'world_x' database sample, follow these steps:

  1. Download world_x-db.zip
     (http://downloads.mysql.com/docs/world_x-db.zip).

  2. Extract the installation archive to a temporary location such as
     '/tmp/'.  Unpacking the archive results in a single file named
     'world_x.sql'.

  3. Create the schema with the following command:

          mysqlsh -u root --sql < /tmp/world_x-db/world_x.sql
          Enter password: ****

     Enter your password when prompted.  A non-root account can be used
     as long as the account has privileges to create new databases.

     Replace '/tmp/' with the path to the 'world_x.sql' file on your
     system.

*Related Information*

   * mysql-shell-sessions explains session types.

   * See installing for general installation assistance.

19.4.3 MySQL Shell
------------------

MySQL Shell is a unified scripting interface to MySQL Server.  It
supports scripting in JavaScript and Python.  JavaScript is the default
processing mode.  In most cases, you need an account to connect to the
local MySQL server instance.

*Start MySQL Shell*

After you have installed and started MySQL server, connect MySQL Shell
to the server instance.  By default, MySQL Shell connects using the X
Protocol.

On the same system where the server instance is running, open a terminal
window and start MySQL Shell with the following command:

     mysqlsh NAME@localhost/world_x
     Creating a Session to 'root@localhost/world_x'
     Enter password: ****

You may need to specify the path as appropriate.

In addition:

   * NAME represents the user name of your MySQL account.

   * MySQL Shell prompts you for your password.

   * The default schema for this session is the 'world_x' database.  For
     instructions on setting up the 'world_x' database sample, see
     mysql-shell-tutorial-javascript-download.

The 'mysql-js>' prompt indicates that the active language for this
session is JavaScript.

     mysql-js>

When you run 'mysqlsh' without the host argument, MySQL
Shell attempts to connect to the server instance running on the
localhost interface on port 33060.  To specify a different host or port
number, as well as other options, see the option descriptions at
mysqlsh.

MySQL Shell supports input-line editing as follows:

   * 'left-arrow' and 'right-arrow' keys move horizontally within the
     current input line.

   * 'up-arrow' and 'down-arrow' keys move up and down through the set
     of previously entered lines.

   * 'Backspace' deletes the character before the cursor and typing new
     characters enters them at the cursor position.

   * 'Enter' enters the current input line.

*Get Help for MySQL Shell*

Type 'mysqlsh --help' at the prompt of your command
interpreter for a list of command-line options.

     mysqlsh --help

Type '\help' at the MySQL Shell prompt for a list of available commands
and their descriptions.

     mysql-js> \help

Type '\help' followed by a command name for detailed help about an
individual MySQL Shell command.  For example, to view help on the
'\connect' command, type:

     mysql-js> \help \connect

*Quit MySQL Shell*

To quit MySQL Shell, type the following command:

     mysql-js> \quit

*Related Information*

   * See mysql-shell-interactive-code-execution for an
     explanation of how interactive code execution works in MySQL Shell.

   * See mysql-shell-getting-started to learn about session and
     connection alternatives.

19.4.4 Documents and Collections
--------------------------------

In MySQL, collections contain JSON documents that you can add, find,
update, and remove.  Collections are containers within a schema that you
create, list, and drop.

The examples in this section use the countryinfo collection in the
'world_x' database.  For instructions on setting up the 'world_x'
database sample, see mysql-shell-tutorial-javascript-download.

*Documents*

In MySQL, documents are represented as JSON objects.  Internally, they
are stored in an efficient binary format that enables fast lookups and
updates.

   * Simple document format for JavaScript:

          {field1: "value", field2 : 10, "field 3": null}

An array of documents consists of a set of documents separated by commas
and enclosed within '[' and ']' characters.

   * Simple array of documents for JavaScript:

          [{Name: "Aruba", _id: "ABW"}, {Name: "Angola", _id: "AGO"}]

MySQL supports the following JavaScript value types in JSON documents:

   * numbers (integer and floating point)

   * strings

   * boolean (false and true)

   * null

   * arrays of more JSON values

   * nested (or embedded) objects of more JSON values

*Collections*

Collections are containers for documents that share a purpose and
possibly share one or more indexes.  Each collection has a unique name
and exists within a single schema.

The term schema is equivalent to a database, which means a group of
database objects (as opposed to relational schema used to enforce
structure and constraints over data).  A schema does not enforce
conformity on the documents in a collection.

In this quick-start guide:

   * Basic objects include:

     Object form                   Description

     'db'                          'db' is a global variable assigned to the
                                   current active schema that you specified
                                   on the command line.  You can type 'db'
                                   in MySQL Shell to print a description of
                                   the object, which in this case will be
                                   the name of the schema it represents.

     'db.getCollections()'         db.getCollections() holds a list of
                                   collections in the schema.  Use the list
                                   to get references to collection objects,
                                   iterate over them, and so on.

   * Basic operations scoped by collections include:

     Operation form                Description

     'db.NAME.add()'               The add().
                                   method inserts one document or a list of
                                   documents into the named collection.

     'db.NAME.find()'              The find().
                                   method returns some or all documents in
                                   the named collection.

     'db.NAME.modify()'            The modify().
                                   method updates documents in the named
                                   collection.

     'db.NAME.remove()'            The remove().
                                   method deletes one document or a list of
                                   documents from the named collection.

*Related Information*

   * See Working with Collections
     (http://dev.mysql.com/doc/x-devapi-userguide/en/devapi-users-working-with-collections.html)
     for a general overview.

   * CRUD EBNF Definitions
     (http://dev.mysql.com/doc/x-devapi-userguide/en/mysql-x-crud-ebnf-definitions.html)
     provides a complete list of operations.

19.4.4.1 Create, List, and Drop Collections
...........................................

In MySQL Shell, you can create new collections, get a list of the
existing collections in a schema, and remove an existing collection from
a schema.  Collection names are case-sensitive and each collection name
must be unique.

*Confirm the Schema*

To show the value that is assigned to the schema variable, type 'db'.

     mysql-js> db

If the schema value is not 'Schema:world_x', then set the 'db' variable
as follows:

     mysql-js> \use world_x

*Create a Collection*

To create a new collection in an existing schema, use the
'createCollection()' method.  The following example creates in the
'world_x' database a collection called flags.

     mysql-js> db.createCollection("flags")

The method returns a collection object.

     <Collection:flags>

*List Collections*

To display all collections in the 'world_x' database, use the
'getCollections()' method on the schema object.  Collections returned by
the server appear between brackets.

     mysql-js> db.getCollections()
     [
         <Collection:countryinfo>,
         <Collection:flags>
     ]

*Drop a Collection*

To drop an existing collection from a database, use the
'dropCollection()' method on the session object.  For example, to drop
the flags collection from the 'world_x' database, type:

     mysql-js> session.dropCollection("world_x", "flags")
     Query OK (0.04 sec)

*Related Information*

   * See mysql-connections-in-javascript-and-python to learn
     more about the session object.

   * See Collection Objects
     (http://dev.mysql.com/doc/x-devapi-userguide/en/collection-objects.html)
     for more examples.

19.4.4.2 Add Documents
......................

You can use the 'add()' method to insert one document or a list
documents into an existing collection using MySQL Shell.  All examples
in this section use the countryinfo collection.

*Confirm the Schema*

To show the value that is assigned to the schema variable, type 'db'.

     mysql-js> db
     <Schema:world_x>

If the schema value is not 'Schema:world_x', then set the 'db' variable
as follows:

     mysql-js> \use world_x
     Schema `world_x` accessible through db.

*Add a Document*

Insert the following document into the countryinfo collection.  Press
'Enter' twice to insert the document.

     mysql-js> db.countryinfo.add(
      {
         GNP: .6,
         IndepYear: 1967,
         Name: "Sealand",
         _id: "SEA",
         demographics: {
             LifeExpectancy: 79,
             Population: 27
         },
         geography: {
             Continent: "Europe",
             Region: "British Islands",
             SurfaceArea: 193
         },
         government: {
             GovernmentForm: "Monarchy",
             HeadOfState: "Michael Bates"
         }
       }
     )
     Query OK, 1 item affected (0.02 sec)

The method returns the status of the operation.

Each document requires an identifier field called '_id'.  The value of
the '_id' field must be unique among all documents in the same
collection.  If the document passed to the 'add()' method does not
contain the '_id' field, MySQL Shell automatically inserts a field into
the document and sets the value to a generated universal unique
identifier (UUID).

*Related Information*

   * See CollectionAddFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionaddfunction)
     for the full syntax definition.

19.4.4.3 Find Documents
.......................

You can use the 'find()' method to query for and return documents from a
collection in a database.  MySQL Shell provides additional methods to
use with the 'find()' method to filter and sort the returned documents.

MySQL provides the following operators to specify search conditions:
'OR' ('||'), 'AND' ('&&'), 'XOR', 'IS', 'NOT', 'BETWEEN', 'IN', 'LIKE',
'!=', '<>', '>', '>=', '<', '<=', '&', '|', '<<', '>>', '+', '-', '*',
'/', '~', and '%'.

*Find All Documents in a Collection*

To return all documents in a collection, use the 'find()' method without
specifying search conditions.  For example, the following operation
returns all documents in the countryinfo collection.

     mysql-js> db.countryinfo.find()
     [
          {
               "GNP": 828,
               "IndepYear": null,
               "Name": "Aruba",
               "_id": "ABW",
               "demographics": {
                   "LifeExpectancy": 78.4000015258789,
                   "Population": 103000
               },
               "geography": {
                   "Continent": "North America",
                   "Region": "Caribbean",
                   "SurfaceArea": 193
               },
               "government": {
                   "GovernmentForm": "Nonmetropolitan Territory of The Netherlands",
                   "HeadOfState": "Beatrix"
               }
               ...
           }
      ]
     240 documents in set (0.00 sec)

The method produces results that contain operational information in
addition to all documents in the collection.

An empty set (no matching documents) returns the following information:

     Empty set (0.00 sec)

*Filter Searches*

You can include search conditions with the 'find()' method.  The syntax
for expressions that form a search condition is the same as that of
traditional MySQL.  You must enclose all expressions in
quotes.

All examples in this section use the countryinfo collection in the
'world_x' database.  For the sake of brevity, some of the examples do
not display output.

A simple search condition consists of the '_id' field and unique
identifier of a document.  The following example returns a single
document matching the identifier string:

     mysql-js> db.countryinfo.find("_id = 'AUS'")
     [
         {
             "GNP": 351182,
             "IndepYear": 1901,
             "Name": "Australia",
             "_id": "AUS",
             "demographics": {
                 "LifeExpectancy": 79.80000305175781,
                 "Population": 18886000
             },
             "geography": {
                 "Continent": "Oceania",
                 "Region": "Australia and New Zealand",
                 "SurfaceArea": 7741220
             },
             "government": {
                 "GovernmentForm": "Constitutional Monarchy, Federation",
                 "HeadOfState": "Elisabeth II"
             }
         }
     ]
     1 document in set (0.01 sec)

The following example searches for all countries that have a GNP higher
than $500 billion.  The countryinfo collection measures GNP in units of
million.

     mysql-js> db.countryinfo.find("GNP > 500000")
     ...[_output removed_]
     10 documents in set (0.00 sec)

The Population field in the following query is embedded within the
demographics object.  To access the embedded field, use a period between
demographics and Population to identify the relationship.  Document and
field names are case-sensitive.

     mysql-js> db.countryinfo.find("GNP > 500000 and demographics.Population < 100000000")
     ...[_output removed_]
     6 documents in set (0.00 sec)

Arithmetic operators in the following expression are used to query for
countries with a GNP per capita higher than $30000.  Search conditions
can include arithmetic operators and most MySQL functions.

*Note*:

Seven documents in the countryinfo collection have a population value of
zero.  Warning messages appear at the end of the output.

     mysql-js> db.countryinfo.find("GNP*1000000/demographics.Population > 30000")
     ...[_output removed_]
     9 documents in set, 7 warnings (0.00 sec)
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0

You can separate a value from the search condition by using the 'bind()'
method.  For example, instead of specifying a hard-coded country name as
the condition, substitute a named placeholder consisting of a colon
followed by a name that begins with a letter, such as _country_.  Then
include the placeholder and value in the 'bind()' method as follows:

     mysql-js> db.countryinfo.find("Name = :country").bind("country", "Italy")
     [
         {
             "GNP": 1161755,
             "IndepYear": 1861,
             "Name": "Italy",
             "_id": "ITA",
             "demographics": {
                 "LifeExpectancy": 79,
                 "Population": 57680000
             },
             "geography": {
                 "Continent": "Europe",
                 "Region": "Southern Europe",
                 "SurfaceArea": 301316
             },
             "government": {
                 "GovernmentForm": "Republic",
                 "HeadOfState": "Carlo Azeglio Ciampi"
             }
         }
     ]
     1 document in set (0.01 sec)

*Tip*:

Within a program, binding enables you to specify placeholders in your
expressions, which are filled in with values before execution and can
benefit from automatic escaping, as appropriate.

Always use binding to sanitize input.  Avoid introducing values in
queries using string concatenation, which can produce invalid input and,
in some cases, can cause security issues.

*Project Results*

You can return specific fields of a document, instead of returning all
the fields.  The following example returns the GNP and Name fields of
all documents in the countryinfo collection matching the search
conditions.

Use the 'fields()' method to pass the list of fields to return.

     mysql-js> db.countryinfo.find("GNP > 5000000").fields(["GNP", "Name"])
     [
         {
             "GNP": 8510700,
             "Name": "United States"
         }
     ]
     1 document in set (0.00 sec)

In addition, you can alter the returned documents--adding, renaming,
nesting and even computing new field values--with an expression that
describes the document to return.  For example, alter the names of the
fields with the following expression to return only two documents.

     mysql-js> db.countryinfo.find().
     fields(mysqlx.expr('{"Name": upper(Name), "GNPPerCapita": GNP*1000000/demographics.Population}')).
     limit(2)
     [
         {
             "GNPPerCapita": 8038.834951456311,
             "Name": "ARUBA"
         },
         {
             "GNPPerCapita": 263.0281690140845,
             "Name": "AFGHANISTAN"
         }
     ]
     2 documents in set (0.00 sec)

*Limit, Sort, and Skip Results*

You can apply the 'limit()', 'sort()', and 'skip()' methods to manage
the number and order of documents returned by the 'find()' method.

To specify the number of documents included in a result set, append the
'limit()' method with a value to the 'find()' method.  The following
query returns the first five documents in the countryinfo collection.

     mysql-js> db.countryinfo.find().limit(5)
     ... [_output removed_]
     5 documents in set (0.00 sec)

To specify an order for the results, append the 'sort()' method to the
'find()' method.  Pass to the 'sort()' method a list of one or more
fields to sort by and, optionally, the descending ('desc') or ascending
('asc') attribute as appropriate.  Ascending order is the default order
type.

For example, the following query sorts all documents by the IndepYear
field and then returns the first eight documents in descending order.

     mysql-js> db.countryinfo.find().sort(["IndepYear desc"]).limit(8)
     ... [_output removed_]
     8 documents in set (0.00 sec)

By default, the 'limit()' method starts from the first document in the
collection.  You can use the 'skip()' method to change the starting
document.  For example, to ignore the first document and return the next
eight documents matching the condition, pass to the 'skip()' method a
value of 1.

     mysql-js> db.countryinfo.find().sort(["IndepYear desc"]).limit(8).skip(1)
     ... [_output removed_]
     8 documents in set (0.00 sec)

*Related Information*

   * The MySQL Reference Manual provides detailed
     documentation on functions and operators.

   * See CollectionFindFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionfindfunction)
     for the full syntax definition.

19.4.4.4 Modify Documents
.........................

You can use the 'modify()' method to update one or more documents in a
collection.  The X DevAPI provides additional methods for use with the
'modify()' method to:

   * Set and unset fields within documents.

   * Append, insert, and delete arrays.

   * Bind, limit, and sort the documents to be modified.

*Set and Unset Fields*

The 'modify()' method works by filtering a collection to include only
the documents to be modified and then applying the operations that you
specify to those documents.

In the following example, the 'modify()' method uses the search
condition to identify the document to change and then the 'set()' method
replaces two values within the nested demographics object.

     mysql-js> db.countryinfo.modify("_id = 'SEA'").
     set("demographics", {LifeExpectancy: 78, Population: 28})
     Query OK, 1 item affected (0.04 sec)

After you modify a document, use the 'find()' method to verify the
change.

To remove content from a document, use the 'modify()' and 'unset()'
methods.  For example, the following query removes the GNP from a
document that matches the search condition.

     mysql-js> db.countryinfo.modify("Name = 'Sealand'").unset("GNP")
     Query OK, 1 item affected (0.01 sec)

Use the 'find()' method to verify the change.

     mysql-js> db.countryinfo.find("Name = 'Sealand'")
     [
         {
             "IndepYear": 1967,
             "Name": "Sealand",
             "_id": "SEA",
             "demographics": {
                 "LifeExpectancy": 78,
                 "Population": 28
             },
             "geography": {
                 "Continent": "Europe",
                 "Region": "British Islands",
                 "SurfaceArea": 193
             },
             "government": {
                 "GovernmentForm": "Monarchy",
                 "HeadOfState": "Michael Bates"
             }
         }
     ]
     1 document in set (0.00 sec)

*Append, Insert, and Delete Arrays*

To append an element to an array field, or insert, or delete elements in
an array, use the 'arrayAppend()', 'arrayInsert()', or 'arrayDelete()'
methods.  The following examples modify the countryinfo collection to
enable tracking of international airports.

The first example uses the 'modify()' and 'set()' methods to create a
new Airports field in all documents.

*Caution*:

Use care when you modify documents without specifying a search
condition.  This action will modify all documents in the collection.

     mysql-js> db.countryinfo.modify("true").set("Airports", [])
     Query OK, 240 items affected (0.07 sec)

With the Airports field added, the next example uses the 'arrayAppend()'
method to add a new airport to one of the documents.  _$.Airports_ in
the following example represents the Airports field of the current
document.

     mysql-js> db.countryinfo.modify("Name = 'France'").arrayAppend("$.Airports", "ORY")
     Query OK, 1 item affected (0.02 sec)

Use db.countryinfo.find("Name = 'France'") to see the change.

To insert an element at a different position in the array, use the
'arrayInsert()' method to specify which index to insert in the path
expression.  In this case, the index is 0, or the first element in the
array.

     mysql-js> db.countryinfo.modify("Name = 'France'").arrayInsert("$.Airports[0]", "CDG")
     Query OK, 1 item affected (0.04 sec)

To delete an element from the array, you must pass to the
'arrayDelete()' method the index of the element to be deleted.

     mysql-js> db.countryinfo.modify("Name = 'France'").arrayDelete("$.Airports[1]")
     Query OK, 1 item affected (0.03 sec)

*Related Information*

   * The MySQL Reference Manual provides instructions to help you search
     for and modify JSON values.

   * See CollectionModifyFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionmodifyfunction)
     for the full syntax definition.

19.4.4.5 Remove Documents
.........................

You can use the 'remove()' method to delete some or all documents from a
collection in a database.  The X DevAPI provides additional methods for
use with the 'remove()' method to filter and sort the documents to be
removed.

*Remove Documents Using Conditions*

The example that follows passes a search condition to the 'remove()'
method.  All documents matching the condition will be removed from the
countryinfo collection.  In this example, one document matches the
condition.

     mysql-js> db.countryinfo.remove("_id = 'SEA'")
     Query OK, 1 item affected (0.02 sec)

*Remove the First Document*

To remove the first document in the countryinfo collection, use the
'limit()' method with a value of 1.

     mysql-js> db.countryinfo.remove("true").limit(1)
     Query OK, 1 item affected (0.03 sec)

*Remove the Last Document in an Order*

The following example removes the last document in the countryinfo
collection by country name.

     mysql-js> db.countryinfo.remove("true").sort(["Name desc"]).limit(1)
     Query OK, 1 item affected (0.02 sec)

*Remove All Documents in a Collection*

You can remove all documents in a collection.  To do so, use the
'remove("true")' method without specifying any search condition.

*Caution*:

Use care when you remove documents without specifying a search
condition.  This action will delete all documents from the collection.

*Related Information*

   * See CollectionRemoveFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionremovefunction)
     for the full syntax definition.

   * See mysql-shell-tutorial-javascript-download for
     instructions to recreate the 'world_x' database.

19.4.4.6 Create and Drop Indexes
................................

Indexes are used to find documents with specific field values quickly.
Without an index, MySQL must begin with the first document and then read
through the entire collection to find the relevant fields.  The larger
the collection, the more this costs.  If a collection is large and
queries on a specific field are common, then consider creating an index
on a specific field inside a document.

For example, the following query will perform better with an index:

     mysql-js> db.countryinfo.find("demographics.Population < 100")
     ...[_output removed_]
     8 documents in set (0.00 sec)

The 'createIndex()' method creates an index that you can define as
nonunique or unique.  Use the 'field()' method to chain the fields that
should be indexed.  The 'execute()' method is required to create or drop
an index.

In MySQL, the '_id' field is equivalent to a primary key by default.

*Add a Nonunique Index*

To create a nonunique index, pass to the 'createIndex()' method an index
name.  Duplicate index names are prohibited.

In the following example, the first parameter of the 'field()' method
specifies the Population field inside the demographics object and the
next parameter indicates that the field should be indexed as an Integer
numeric value.  The last parameter indicates whether the field should
require the NOT NULL constraint.  If the value is 'false', the field can
contain 'NULL' values.

     mysql-js> db.countryinfo.createIndex("pop").
     field("demographics.Population", "INTEGER", false).execute()
     Query OK (0.04 sec)

*Add a Unique Index*

To create a unique index, pass to the 'createIndex()' method an index
name and the 'mysqlx.IndexType.UNIQUE' type.  Country '"Name"' is
another common field in the countryinfo collection to index.  In the
following example, '"Text(40)"' represents the number of characters to
index and 'true' indicates that the field cannot contain any 'NULL'
values.

     mysql-js> db.countryinfo.createIndex("name", mysqlx.IndexType.UNIQUE).
     field("Name", "TEXT(40)", true).execute()
     Query OK (0.04 sec)

*Drop an Index*

To drop an index, pass to the 'dropIndex()' method the name of the index
to drop.  For example, you can drop the 'pop' index as follows:

     mysql-js> db.countryinfo.dropIndex("pop").execute()
     Query OK (0.58 sec)

*Related Information*

   * See Collection Index Management Functions
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-index-management-functions.html)
     for the full syntax definition.

19.4.5 Relational Tables
------------------------

You can use MySQL Shell to manipulate not just JSON documents, but also
relational tables.

In MySQL, each relational table is associated with a particular storage
engine.  The examples in this section use 'InnoDB'
tables in the 'world_x' database.

*Confirm the Schema*

To show the value that is assigned to the schema variable, type 'db'.

     mysql-js> db

If the schema value is not 'Schema:world_x', then set the 'db' variable
as follows:

     mysql-js> \use world_x

*Show All Tables*

To display all relational tables in the 'world_x' database, use the
'getTables()' method on the schema object.

     mysql-js> db.getTables()
     {
         "city": <Table:city>,
         "country": <Table:country>,
         "countrylanguage": <Table:countrylanguage>
     }

*Basic Table Operations*

Basic operations scoped by tables include:

Operation form          Description

'db.NAME.insert()'      The insert().
                        method inserts one or more records into the
                        named table.

'db.NAME.select()'      The select().
                        method returns some or all records in the named
                        table.

'db.NAME.update()'      The update().
                        method updates records in the named table.

'db.NAME.delete()'      The delete().
                        method deletes one or more records from the
                        named table.

*Related Information*

   * See Working with Relational Tables
     (http://dev.mysql.com/doc/x-devapi-userguide/en/devapi-users-working-with-relational-tables.html)
     for a general overview.

   * CRUD EBNF Definitions
     (http://dev.mysql.com/doc/x-devapi-userguide/en/mysql-x-crud-ebnf-definitions.html)
     provides a complete list of operations.

   * See mysql-shell-tutorial-javascript-download for
     instructions on setting up the 'world_x' database sample.

19.4.5.1 Insert Records into Tables
...................................

You can use the 'insert()' method with the 'values()' method to insert
records into an existing relational table.  The 'insert()' method
accepts individual columns or all columns in the table.  Use one or more
'values()' methods to specify the values to be inserted.

*Insert a Complete Record*

To insert a complete record, pass to the 'insert()' method all columns
in the table.  Then pass to the 'values()' method one value for each
column in the table.  For example, to add a new record to the city table
in the 'world_x' database, insert the following record and press 'Enter'
twice.

     mysql-js> db.city.insert("ID", "Name", "CountryCode", "District", "Info").
     values(null, "Olympia", "USA", "Washington", '{"Population": 5000}')
     Query OK, 1 item affected (0.01 sec)

The city table has five columns: ID, Name, CountryCode, District, and
Info.  Each value must match the data type of the column it represents.

*Insert a Partial Record*

The following example inserts values into the ID, Name, and CountryCode
columns of the city table.

     mysql-js> db.city.insert("ID", "Name", "CountryCode").
     values(null, "Little Falls", "USA").values(null, "Happy Valley", "USA")
     Query OK, 2 item affected (0.03 sec)

When you specify columns using the 'insert()' method, the number of
values must match the number of columns.  In the previous example, you
must supply three values to match the three columns specified.

*Related Information*

   * See TableInsertFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tableinsertfunction)
     for the full syntax definition.

19.4.5.2 Select Tables
......................

You can use the 'select()' method to query for and return records from a
table in a database.  The X DevAPI provides additional methods to use
with the 'select()' method to filter and sort the returned records.

MySQL provides the following operators to specify search conditions:
'OR' ('||'), 'AND' ('&&'), 'XOR', 'IS', 'NOT', 'BETWEEN', 'IN', 'LIKE',
'!=', '<>', '>', '>=', '<', '<=', '&', '|', '<<', '>>', '+', '-', '*',
'/', '~', and '%'.

*Select All Records*

To issue a query that returns all records from an existing table, use
the 'select()' method without specifying search conditions.  The
following example selects all records from the city table in the
'world_x' database.

*Note*:

Limit the use of the empty 'select()' method to interactive statements.
Always use explicit column-name selections in your application code.

     mysql-js> db.city.select()
     +------+------------+-------------+------------+-------------------------+
     | ID   | Name       | CountryCode | District   | Info                    |
     +------+------------+-------------+------------+-------------------------+
     |    1 | Kabul      | AFG         | Kabol      |{"Population": 1780000}  |
     |    2 | Qandahar   | AFG         | Qandahar   |{"Population": 237500}   |
     |    3 | Herat      | AFG         | Herat      |{"Population": 186800}   |
     ...    ...          ...           ...          ...
     | 4079 | Rafah      | PSE         | Rafah      |{"Population": 92020}    |
     +------+------- ----+-------------+------------+-------------------------+
     4082 rows in set (0.01 sec)

An empty set (no matching records) returns the following information:

     Empty set (0.00 sec)

*Filter Searches*

To issue a query that returns a set of table columns, use the 'select()'
method and specify the columns to return between square brackets.  This
query returns the Name and CountryCode columns from the city table.

     mysql-js> db.city.select(["Name", "CountryCode"])
     +-------------------+-------------+
     | Name              | CountryCode |
     +-------------------+-------------+
     | Kabul             | AFG         |
     | Qandahar          | AFG         |
     | Herat             | AFG         |
     | Mazar-e-Sharif    | AFG         |
     | Amsterdam         | NLD         |
     ...                 ...
     | Rafah             | PSE         |
     | Olympia           | USA         |
     | Little Falls      | USA         |
     | Happy Valley      | USA         |
     +-------------------+-------------+
     4082 rows in set (0.00 sec)

To issue a query that returns rows matching specific search conditions,
use the 'where()' method to include those conditions.  For example, the
following example returns the names and country codes of the cities that
start with the letter Z.

     mysql-js> db.city.select(["Name", "CountryCode"]).where("Name like 'Z%'")
     +-------------------+-------------+
     | Name              | CountryCode |
     +-------------------+-------------+
     | Zaanstad          | NLD         |
     | Zoetermeer        | NLD         |
     | Zwolle            | NLD         |
     | Zenica            | BIH         |
     | Zagazig           | EGY         |
     | Zaragoza          | ESP         |
     | Zamboanga         | PHL         |
     | Zahedan           | IRN         |
     | Zanjan            | IRN         |
     | Zabol             | IRN         |
     | Zama              | JPN         |
     | Zhezqazghan       | KAZ         |
     | Zhengzhou         | CHN         |
     ...                 ...
     | Zeleznogorsk      | RUS         |
     +-------------------+-------------+
     59 rows in set (0.00 sec)

You can separate a value from the search condition by using the 'bind()'
method.  For example, instead of using "Name = 'Z%' " as the condition,
substitute a named placeholder consisting of a colon followed by a name
that begins with a letter, such as _name_.  Then include the placeholder
and value in the 'bind()' method as follows:

     mysql-js> db.city.select(["Name", "CountryCode"]).
                   where("Name like :name").bind("name", "Z%")

*Tip*:

Within a program, binding enables you to specify placeholders in your
expressions, which are filled in with values before execution and can
benefit from automatic escaping, as appropriate.

Always use binding to sanitize input.  Avoid introducing values in
queries using string concatenation, which can produce invalid input and,
in some cases, can cause security issues.

*Project Results*

To issue a query using the 'AND' operator, add the operator between
search conditions in the 'where()' method.

     mysql-js> db.city.select(["Name", "CountryCode"]).
                    where("Name like 'Z%' and CountryCode = 'CHN'")
     +----------------+-------------+
     | Name           | CountryCode |
     +----------------+-------------+
     | Zhengzhou      | CHN         |
     | Zibo           | CHN         |
     | Zhangjiakou    | CHN         |
     | Zhuzhou        | CHN         |
     | Zhangjiang     | CHN         |
     | Zigong         | CHN         |
     | Zaozhuang      | CHN         |
     ...              ...
     | Zhangjiagang   | CHN         |
     +----------------+-------------+
     22 rows in set (0.01 sec)

To specify multiple conditional operators, you can enclose the search
conditions in parenthesis to change the operator precedence.  The
following example demonstrates the placement of 'AND' and 'OR'
operators.

     mysql-js> db.city.select(["Name", "CountryCode"]).
     where("Name like 'Z%' and (CountryCode = 'CHN' or CountryCode = 'RUS')")
     +-------------------+-------------+
     | Name              | CountryCode |
     +-------------------+-------------+
     | Zhengzhou         | CHN         |
     | Zibo              | CHN         |
     | Zhangjiakou       | CHN         |
     | Zhuzhou           | CHN         |
     ...                 ...
     | Zeleznogorsk      | RUS         |
     +-------------------+-------------+
     29 rows in set (0.01 sec)

*Limit, Order, and Offset Results*

You can apply the 'limit()', 'orderBy()', and 'offSet()' methods to
manage the number and order of records returned by the 'select()'
method.

To specify the number of records included in a result set, append the
'limit()' method with a value to the 'select()' method.  For example,
the following query returns the first five records in the country table.

     mysql-js> db.country.select(["Code", "Name"]).limit(5)
     +------+-------------+
     | Code | Name        |
     +------+-------------+
     | ABW  | Aruba       |
     | AFG  | Afghanistan |
     | AGO  | Angola      |
     | AIA  | Anguilla    |
     | ALB  | Albania     |
     +------+-------------+
     5 rows in set (0.00 sec)

To specify an order for the results, append the 'orderBy()' method to
the 'select()' method.  Pass to the 'orderBy()' method a list of one or
more columns to sort by and, optionally, the descending ('desc') or
ascending ('asc') attribute as appropriate.  Ascending order is the
default order type.

For example, the following query sorts all records by the Name column
and then returns the first three records in descending order .

     mysql-js> db.country.select(["Code", "Name"]).orderBy(["Name desc"]).limit(3)
     +------+------------+
     | Code | Name       |
     +------+------------+
     | ZWE  | Zimbabwe   |
     | ZMB  | Zambia     |
     | YUG  | Yugoslavia |
     +------+------------+
     3 rows in set (0.00 sec)

By default, the 'limit()' method starts from the first record in the
table.  You can use the 'offset()' method to change the starting record.
For example, to ignore the first record and return the next three
records matching the condition, pass to the 'offset()' method a value of
1.

     mysql-js> db.country.select(["Code", "Name"]).orderBy(["Name desc"]).limit(3).offset(1)
     +------+------------+
     | Code | Name       |
     +------+------------+
     | ZMB  | Zambia     |
     | YUG  | Yugoslavia |
     | YEM  | Yemen      |
     +------+------------+
     3 rows in set (0.00 sec)

*Related Information*

   * The MySQL Reference Manual provides detailed
     documentation on functions and operators.

   * See TableSelectFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tableselectfunction)
     for the full syntax definition.

19.4.5.3 Update Tables
......................

You can use the 'update()' method to modify one or more records in a
table.  The 'update()' method works by filtering a query to include only
the records to be updated and then applying the operations you specify
to those records.

To replace a city name in the city table, pass to the 'set()' method the
new city name.  Then, pass to the 'where()' method the city name to
locate and replace.  The following example replaces the city Peking with
Beijing.

     mysql-js> db.city.update().set("Name", "Beijing").where("Name = 'Peking'")
     Query OK, 1 item affected (0.04 sec)

Use the 'select()' method to verify the change.

     mysql-js> db.city.select(["ID", "Name", "CountryCode", "District", "Info"]).where("Name = 'Beijing'")
     +------+-----------+-------------+----------+-----------------------------+
     | ID   | Name      | CountryCode | District | Info                        |
     +------+-----------+-------------+----------+-----------------------------+
     | 1891 | Beijing   | CHN         | Peking   | {"Population": 7472000}     |
     +------+-----------+-------------+----------+-----------------------------+
     1 row in set (0.00 sec)

*Related Information*

   * See TableUpdateFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tableupdatefunction)
     for the full syntax definition.

19.4.5.4 Delete Tables
......................

You can use the 'delete()' method to remove some or all records from a
table in a database.  The X DevAPI provides additional methods to use
with the 'delete()' method to filter and order the records to be
deleted.

*Delete Records Using Conditions*

The example that follows passes search conditions to the 'delete()'
method.  All records matching the condition will be deleted from the
city table.  In this example, one record matches the condition.

     mysql-js> db.city.delete().where("Name = 'Olympia'")
     Query OK, 1 item affected (0.01 sec)

*Delete the First Record*

To delete the first record in the city table, use the 'limit()' method
with a value of 1.

     mysql-js> db.city.delete().limit(1)
     Query OK, 1 item affected (0.02 sec)

*Delete All Records in a Table*

You can delete all records in a table.  To do so, use the 'delete()'
method without specifying a search condition.

*Caution*:

Use care when you delete records without specifying a search condition.
This action will delete all records from the table.

*Related Information*

   * See TableDeleteFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tabledeletefunction)
     for the full syntax definition.

   * See mysql-shell-tutorial-javascript-download for
     instructions to recreate the 'world_x' database.

19.4.6 Documents in Tables
--------------------------

In MySQL, a table may contain traditional relational data, JSON values,
or both.  You can combine traditional data with JSON documents by
storing the documents in columns having a native 'JSON'.
data type.

Examples in this section use the city table in the 'world_x' database.

*city Table Description*

The city table has five columns (or fields).

     +---------------+------------+-------+-------+---------+------------------+
     | Field         | Type       | Null  | Key   | Default | Extra            |
     +---------------+------------+-------+-------+---------+------------------+
     | ID            | int(11)    | NO    | PRI   | null    | auto_increment   |
     | Name          | char(35)   | NO    |       |         |                  |
     | CountryCode   | char(3)    | NO    |       |         |                  |
     | District      | char(20)   | NO    |       |         |                  |
     | Info          | json       | YES   |       | null    |                  |
     +---------------+------------+-------+-------+---------+------------------+

*Insert a Record*

To insert a document into the column of a table, pass to the 'values()'
method a well-formed JSON document in the correct order.  In the
following example, a document is passed as the final value to be
inserted into the Info column.

     mysql-js> db.city.insert().
     values(null, "San Francisco", "USA", "California", '{"Population":830000}')
     Query OK, 1 item affected (0.01 sec)

*Select a Record*

You can issue a query with a search condition that evaluates document
values in the expression.

     mysql-js> db.city.select(["ID", "Name", "CountryCode", "District", "Info"]).
       where("CountryCode = :country and Info->'$.Population' > 1000000").
       bind('country', 'USA')
     +------+----------------+-------------+----------------+-----------------------------+
     | ID   | Name           | CountryCode | District       | Info                        |
     +------+----------------+-------------+----------------+-----------------------------+
     | 3793 | New York       | USA         | New York       | {"Population": 8008278}     |
     | 3794 | Los Angeles    | USA         | California     | {"Population": 3694820}     |
     | 3795 | Chicago        | USA         | Illinois       | {"Population": 2896016}     |
     | 3796 | Houston        | USA         | Texas          | {"Population": 1953631}     |
     | 3797 | Philadelphia   | USA         | Pennsylvania   | {"Population": 1517550}     |
     | 3798 | Phoenix        | USA         | Arizona        | {"Population": 1321045}     |
     | 3799 | San Diego      | USA         | California     | {"Population": 1223400}     |
     | 3800 | Dallas         | USA         | Texas          | {"Population": 1188580}     |
     | 3801 | San Antonio    | USA         | Texas          | {"Population": 1144646}     |
     +------+----------------+-------------+----------------+-----------------------------+
     9 rows in set (0.01 sec)

*Related Information*

   * See Working with Relational Tables and Documents
     (http://dev.mysql.com/doc/x-devapi-userguide/en/devapi-users-working-with-relational-tables-and-documents.html)
     for a general overview.

   * See json for a detailed description of the data type.

19.5 Quick-Start Guide: MySQL Shell for Python
==============================================

This quick-start guide provides instructions to begin prototyping
database applications interactively with MySQL Shell.  The guide
includes the following topics:

   * Introduction to MySQL functionality, MySQL Shell, and the 'world_x'
     database sample.

   * Operations to manage collections and documents.

   * Operations to manage relational tables.

   * Operations that apply to documents within tables.

*Available Quick-Start Guides*

   * MySQL Shell for JavaScript.

   * MySQL for Visual Studio.

*Related Information*

   * mysql-shell provides more in-depth information about MySQL
     Shell.

   * X DevAPI User Guide
     (http://dev.mysql.com/doc/x-devapi-userguide/en/) provides more
     examples of using X DevAPI.

19.5.1 Introduction
-------------------

The MySQL Shell for Python quick start provides a short but
comprehensive introduction to the database functionality including the
new X DevAPI, which offers a modern, integrative way to work with
relational and document data, without requiring SQL knowledge from
application developers.

In MySQL, tables are the native data storage container type and
collections are stored internally using tables.

*JSON Documents and Collections*

A JSON document is a data structure composed of field/value pairs stored
within a collection.  The
values of fields often contain other documents, arrays, and lists of
documents.

     {
         "GNP": .6,
         "IndepYear": 1967,
         "Name": "Sealand",
         "_id": "SEA",
         "demographics": {
             "LifeExpectancy": 79,
             "Population": 27
         },
         "geography": {
             "Continent": "Europe",
             "Region": "British Islands",
             "SurfaceArea": 193
         },
         "government": {
             "GovernmentForm": "Monarchy",
             "HeadOfState": "Michael Bates"
         }
     }

*Relational Tables*

A table in MySQL
enables you to store data organized in rows and columns.  The structure
of a table is defined by one or more columns with user-defined names and
data types.  Every row stored in the table has the same structure.

     +------+------------------+-------------+-----------------+------------------------+
     | ID   | Name             | CountryCode | District        | Info                   |
     +------+------------------+-------------+-----------------+------------------------+
     |    1 | Kabul            | AFG         | Kabol           |{"Population": 1780000} |
     |    2 | Qandahar         | AFG         | Qandahar        |{"Population": 237500}  |
     |    3 | Herat            | AFG         | Herat           |{"Population": 186800}  |
     |    4 | Mazar-e-Sharif   | AFG         | Balkh           |{"Population": 127800}  |
     |    5 | Amsterdam        | NLD         | Noord-Holland   |{"Population": 731200}  |
     |    6 | Rotterdam        | NLD         | Zuid-Holland    |{"Population": 593321}  |
     +------+------------------+-------------+-----------------+------------------------+

*Related Information*

   * mysql-shell provides a general overview.

   * See X DevAPI User Guide
     (http://dev.mysql.com/doc/x-devapi-userguide/en/) for development
     reference documentation.

19.5.2 Import Database Sample
-----------------------------

The 'world_x' database sample contains one JSON collection and a set of
three relational tables:

   * Collection

        * countryinfo: Information about countries in the world.

   * Tables

        * country: Minimal information about countries of the world.

        * city: Information about some of the cities in those countries.

        * countrylanguage: Languages spoken in each country.

*Requirements*

You must install MySQL Shell with the X Protocol enabled.  For
instructions, see document-store-setting-up.

Start the server before you load the 'world_x' database for this guide.

*Download world_x Database*

To prepare the 'world_x' database sample, follow these steps:

  1. Download world_x-db.zip
     (http://downloads.mysql.com/docs/world_x-db.zip).

  2. Extract the installation archive to a temporary location such as
     '/tmp/'.  Unpacking the archive results in a single file named
     'world_x.sql'.

  3. Create the schema with the following command:

          mysqlsh -u root --sql < /tmp/world_x-db/world_x.sql
          Enter password: ****

     Enter your password when prompted.  A non-root account can be used
     as long as the account has privileges to create new databases.

     Replace '/tmp/' with the path to the 'world_x.sql' file on your
     system.

*Related Information*

   * mysql-shell-sessions explains session types.

   * See installing for general installation assistance.

19.5.3 MySQL Shell
------------------

MySQL Shell is a unified scripting interface to MySQL Server.  It
supports scripting in JavaScript and Python.  JavaScript is the default
processing mode.  In most cases, you need an account to connect to the
local MySQL server instance.

*Start MySQL Shell*

After you have installed and started MySQL server, connect MySQL Shell
to the server instance.  By default, MySQL Shell connects using the X
Protocol.

On the same system where the server instance is running, open a terminal
window and start MySQL Shell with the following command:

     mysqlsh NAME@localhost/world_x --py
     Creating a Session to NAME@localhost/world_x
     Enter password: ****

You may need to specify the path as appropriate.

In addition:

   * NAME represents the user name of your MySQL account.

   * MySQL Shell prompts you for your password.

   * The '--py' option starts MySQL Shell in Python mode.  If you omit
     '--py', MySQL Shell starts in JavaScript mode.

   * The default schema for this session is the 'world_x' database.  For
     instructions on setting up the 'world_x' database sample, see
     mysql-shell-tutorial-python-download.

The 'mysql-py>' prompt indicates that the active language for this
session is Python.

     mysql-py>

When you run 'mysqlsh' without the host argument, MySQL
Shell attempts to connect to the server instance running on the
localhost interface on port 33060.  To specify a different host or port
number, as well as other options, see the option descriptions at
mysqlsh.

MySQL Shell supports input-line editing as follows:

   * 'left-arrow' and 'right-arrow' keys move horizontally within the
     current input line.

   * 'up-arrow' and 'down-arrow' keys move up and down through the set
     of previously entered lines.

   * 'Backspace' deletes the character before the cursor and typing new
     characters enters them at the cursor position.

   * 'Enter' enters the current input line.

*Get Help for MySQL Shell*

Type 'mysqlsh --help' at the prompt of your command
interpreter for a list of command-line options.

     mysqlsh --help

Type '\help' at the MySQL Shell prompt for a list of available commands
and their descriptions.

     mysql-py> \help

Type '\help' followed by a command name for detailed help about an
individual MySQL Shell command.  For example, to view help on the
'\connect' command, type:

     mysql-py> \help \connect

*Quit MySQL Shell*

To quit MySQL Shell, type the following command:

     mysql-py> \quit

*Related Information*

   * See mysql-shell-interactive-code-execution for an
     explanation of how interactive code execution works in MySQL Shell.

   * See mysql-shell-getting-started to learn about session and
     connection alternatives.

19.5.4 Documents and Collections
--------------------------------

In MySQL, collections contain JSON documents that you can add, find,
update, and remove.  Collections are containers within a schema that you
create, list, and drop.

The examples in this section use the countryinfo collection in the
'world_x' database.  For instructions on setting up the 'world_x'
database sample, see mysql-shell-tutorial-python-download.

*Documents*

In MySQL, documents are represented as JSON objects.  Internally, they
are stored in an efficient binary format that enables fast lookups and
updates.

   * Simple document format for Python:

          {"field1": "value", "field2" : 10, "field 3": null}

An array of documents consists of a set of documents separated by commas
and enclosed within '[' and ']' characters.

   * Simple array of documents for Python:

          [{"Name": "Aruba", "_id": "ABW"}, {"Name": "Angola", "_id": "AGO"}]

MySQL supports the following Python value types in JSON documents:

   * numbers (integer and floating point)

   * strings

   * boolean (False and True)

   * None

   * arrays of more JSON values

   * nested (or embedded) objects of more JSON values

*Collections*

Collections are containers for documents that share a purpose and
possibly share one or more indexes.  Each collection has a unique name
and exists within a single schema.

The term schema is equivalent to a database, which means a group of
database objects (as opposed to relational schema used to enforce
structure and constraints over data).  A schema does not enforce
conformity on the documents in a collection.

In this quick-start guide:

   * Basic objects include:

     Object form                   Description

     'db'                          'db' is a global variable assigned to the
                                   current active schema that you specified on the
                                   command line.  You can type 'db' in MySQL Shell
                                   to print a description of the object, which in
                                   this case will be the name of the schema it
                                   represents.

     'db.get_collections()'        db.get_collections() holds a list of collections
                                   in the schema.  Use the list to get references
                                   to collection objects, iterate over them, and so
                                   on.

   * Basic operations scoped by collections include:

     Operation form                Description

     'db.NAME.add()'               The add().
                                   method inserts one document or a list of
                                   documents into the named collection.

     'db.NAME.find()'              The find().
                                   method returns some or all documents in the
                                   named collection.

     'db.NAME.modify()'            The modify().
                                   method updates documents in the named
                                   collection.

     'db.NAME.remove()'            The remove().
                                   method deletes one document or a list of
                                   documents from the named collection.

*Related Information*

   * See Working with Collections
     (http://dev.mysql.com/doc/x-devapi-userguide/en/devapi-users-working-with-collections.html)
     for a general overview.

   * CRUD EBNF Definitions
     (http://dev.mysql.com/doc/x-devapi-userguide/en/mysql-x-crud-ebnf-definitions.html)
     provides a complete list of operations.

19.5.4.1 Create, List, and Drop Collections
...........................................

In MySQL Shell, you can create new collections, get a list of the
existing collections in a schema, and remove an existing collection from
a schema.  Collection names are case-sensitive and each collection name
must be unique.

*Confirm the Schema*

To show the value that is assigned to the schema variable, type 'db'.

     mysql-py> db

If the schema value is not 'Schema:world_x', then set the 'db' variable
as follows:

     mysql-py> \use world_x

*Create a Collection*

To create a new collection in an existing schema, use the
'create_collection()' method.  The following example creates in the
'world_x' database a collection called flags.

     mysql-py> db.create_collection("flags")

The method returns a collection object.

     <Collection:flags>

*List Collections*

To display all collections in the 'world_x' database, use the
'get_collections()' method on the schema object.  Collections returned
by the server appear between brackets.

     mysql-py> db.get_collections()
     [
         <Collection:countryinfo>,
         <Collection:flags>
     ]

*Drop a Collection*

To drop an existing collection from a database, use the
'drop_collection()' method on the session object.  For example, to drop
the flags collection from the 'world_x' database, type:

     mysql-py> session.drop_collection("world_x", "flags")
     Query OK (0.04 sec)

*Related Information*

   * See mysql-connections-in-javascript-and-python to learn
     more about the session object.

   * See Collection Objects
     (http://dev.mysql.com/doc/x-devapi-userguide/en/collection-objects.html)
     for more examples.

19.5.4.2 Add Documents
......................

You can use the 'add()' method to insert one document or a list
documents into an existing collection using MySQL Shell.  All examples
in this section use the countryinfo collection.

*Confirm the Schema*

To show the value that is assigned to the schema variable, type'db'.

     mysql-py> db

If the schema value is not 'Schema:world_x', then set the 'db' variable
as follows:

     mysql-py> \use world_x

*Add a Document*

Insert the following document into the countryinfo collection.  Press
'Enter' twice to insert the document.

     mysql-py> db.countryinfo.add(
      {
         "GNP": .6,
         "IndepYear": 1967,
         "Name": "Sealand",
         "_id": "SEA",
         "demographics": {
             "LifeExpectancy": 79,
             "Population": 27
         },
         "geography": {
             "Continent": "Europe",
             "Region": "British Islands",
             "SurfaceArea": 193
         },
         "government": {
             "GovernmentForm": "Monarchy",
             "HeadOfState": "Michael Bates"
         }
       }
     )
     Query OK, 1 item affected (0.02 sec)

The method returns the status of the operation.

Each document requires an identifier field called '_id'.  The value of
the '_id' field must be unique among all documents in the same
collection.  If the document passed to the 'add()' method does not
contain the '_id' field, MySQL Shell automatically inserts a field into
the document and sets the value to a generated universal unique
identifier (UUID).

*Related Information*

   * See CollectionAddFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionaddfunction)
     for the full syntax definition.

19.5.4.3 Find Documents
.......................

You can use the 'find()' method to query for and return documents from a
collection in a database.  MySQL Shell provides additional methods to
use with the 'find()' method to filter and sort the returned documents.

MySQL provides the following operators to specify search conditions:
'OR' ('||'), 'AND' ('&&'), 'XOR', 'IS', 'NOT', 'BETWEEN', 'IN', 'LIKE',
'!=', '<>', '>', '>=', '<', '<=', '&', '|', '<<', '>>', '+', '-', '*',
'/', '~', and '%'.

*Find All Documents in a Collection*

To return all documents in a collection, use the 'find()' method without
specifying search conditions.  For example, the following operation
returns all documents in the countryinfo collection.

     mysql-py> db.countryinfo.find()
     [
          {
               "GNP": 828,
               "IndepYear": null,
               "Name": "Aruba",
               "_id": "ABW",
               "demographics": {
                   "LifeExpectancy": 78.4000015258789,
                   "Population": 103000
               },
               "geography": {
                   "Continent": "North America",
                   "Region": "Caribbean",
                   "SurfaceArea": 193
               },
               "government": {
                   "GovernmentForm": "Nonmetropolitan Territory of The Netherlands",
                   "HeadOfState": "Beatrix"
               }
               ...
           }
      ]
     240 documents in set (0.00 sec)

The method produces results that contain operational information in
addition to all documents in the collection.

An empty set (no matching documents) returns the following information:

     Empty set (0.00 sec)

*Filter Searches*

You can include search conditions with the 'find()' method.  The syntax
for expressions that form a search condition is the same as that of
traditional MySQL.  You must enclose all expressions in
quotes.

All examples in this section use the countryinfo collection in the
'world_x' database.  For the sake of brevity, some of the examples do
not display output.

A simple search condition consists of the '_id' field and unique
identifier of a document.  The following example returns a single
document matching the identifier string:

     mysql-py> db.countryinfo.find("_id = 'AUS'")
     [
         {
             "GNP": 351182,
             "IndepYear": 1901,
             "Name": "Australia",
             "_id": "AUS",
             "demographics": {
                 "LifeExpectancy": 79.80000305175781,
                 "Population": 18886000
             },
             "geography": {
                 "Continent": "Oceania",
                 "Region": "Australia and New Zealand",
                 "SurfaceArea": 7741220
             },
             "government": {
                 "GovernmentForm": "Constitutional Monarchy, Federation",
                 "HeadOfState": "Elisabeth II"
             }
         }
     ]
     1 document in set (0.01 sec)

The following example searches for all countries that have a GNP higher
than $500 billion.  The countryinfo collection measures GNP in units of
million.

     mysql-py> db.countryinfo.find("GNP > 500000")
     ...[_output removed_]
     10 documents in set (0.00 sec)

The Population field in the following query is embedded within the
demographics object.  To access the embedded field, use a period between
demographics and Population to identify the relationship.  Document and
field names are case-sensitive.

     mysql-py> db.countryinfo.find("GNP > 500000 and demographics.Population < 100000000")
     ...[_output removed_]
     6 documents in set (0.00 sec)

Arithmetic operators in the following expression are used to query for
countries with a GNP per capita higher than $30000.  Search conditions
can include arithmetic operators and most MySQL functions.

*Note*:

Seven documents in the countryinfo collection have a population value of
zero.  Warning messages appear at the end of the output.

     mysql-py> db.countryinfo.find("GNP*1000000/demographics.Population > 30000")
     ...[_output removed_]
     9 documents in set, 7 warnings (0.00 sec)
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0
     Warning (Code 1365): Division by 0

You can separate a value from the search condition by using the 'bind()'
method.  For example, instead of specifying a hard-coded country name as
the condition, substitute a named placeholder consisting of a colon
followed by a name that begins with a letter, such as _country_.  Then
include the placeholder and value in the 'bind()' method as follows:

     mysql-py> db.countryinfo.find("Name = :country").bind("country", "Italy")
     [
         {
             "GNP": 1161755,
             "IndepYear": 1861,
             "Name": "Italy",
             "_id": "ITA",
             "demographics": {
                 "LifeExpectancy": 79,
                 "Population": 57680000
             },
             "geography": {
                 "Continent": "Europe",
                 "Region": "Southern Europe",
                 "SurfaceArea": 301316
             },
             "government": {
                 "GovernmentForm": "Republic",
                 "HeadOfState": "Carlo Azeglio Ciampi"
             }
         }
     ]
     1 document in set (0.01 sec)

*Tip*:

Within a program, binding enables you to specify placeholders in your
expressions, which are filled in with values before execution and can
benefit from automatic escaping, as appropriate.

Always use binding to sanitize input.  Avoid introducing values in
queries using string concatenation, which can produce invalid input and,
in some cases, can cause security issues.

*Project Results*

You can return specific fields of a document, instead of returning all
the fields.  The following example returns the GNP and Name fields of
all documents in the countryinfo collection matching the search
conditions.

Use the 'fields()' method to pass the list of fields to return.

     mysql-py> db.countryinfo.find("GNP > 5000000").fields(["GNP", "Name"])
     [
         {
             "GNP": 8510700,
             "Name": "United States"
         }
     ]
     1 document in set (0.00 sec)

In addition, you can alter the returned documents--adding, renaming,
nesting and even computing new field values--with an expression that
describes the document to return.  For example, alter the names of the
fields with the following expression to return only two documents.

     mysql-py> db.countryinfo.find().\
     fields(mysqlx.expr('{"Name": upper(Name), "GNPPerCapita": GNP*1000000/demographics.Population}')).\
     limit(2)
     [
         {
             "GNPPerCapita": 8038.834951456311,
             "Name": "ARUBA"
         },
         {
             "GNPPerCapita": 263.0281690140845,
             "Name": "AFGHANISTAN"
         }
     ]
     2 documents in set (0.00 sec)

*Limit, Sort, and Skip Results*

You can apply the 'limit()', 'sort()', and 'skip()' methods to manage
the number and order of documents returned by the 'find()' method.

To specify the number of documents included in a result set, append the
'limit()' method with a value to the 'find()' method.  The following
query returns the first five documents in the countryinfo collection.

     mysql-py> db.countryinfo.find().limit(5)
     ... [_output removed_]
     5 documents in set (0.00 sec)

To specify an order for the results, append the 'sort()' method to the
'find()' method.  Pass to the 'sort()' method a list of one or more
fields to sort by and, optionally, the descending ('desc') or ascending
('asc') attribute as appropriate.  Ascending order is the default order
type.

For example, the following query sorts all documents by the IndepYear
field and then returns the first eight documents in descending order.

     mysql-py> db.countryinfo.find().sort(["IndepYear desc"]).limit(8)
     ... [_output removed_]
     8 documents in set (0.00 sec)

By default, the 'limit()' method starts from the first document in the
collection.  You can use the 'skip()' method to change the starting
document.  For example, to ignore the first document and return the next
eight documents matching the condition, pass to the 'skip()' method a
value of 1.

     mysql-py> db.countryinfo.find().sort(["IndepYear desc"]).limit(8).skip(1)
     ... [_output removed_]
     8 documents in set (0.00 sec)

*Related Information*

   * The MySQL Reference Manual provides detailed
     documentation on functions and operators.

   * See CollectionFindFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionfindfunction)
     for the full syntax definition.

19.5.4.4 Modify Documents
.........................

You can use the 'modify()' method to update one or more documents in a
collection.  The X DevAPI provides additional methods for use with the
'modify()' method to:

   * Set and unset fields within documents.

   * Append, insert, and delete arrays.

   * Bind, limit, and sort the documents to be modified.

*Set and Unset Fields*

The 'modify()' method works by filtering a collection to include only
the documents to be modified and then applying the operations that you
specify to those documents.

In the following example, the 'modify()' method uses the search
condition to identify the document to change and then the 'set()' method
replaces two values within the nested demographics object.

     mysql-py> db.countryinfo.modify("_id = 'SEA'").\
     set("demographics", {"LifeExpectancy": 78, "Population": 28})
     Query OK, 1 item affected (0.04 sec)

After you modify a document, use the 'find()' method to verify the
change.

To remove content from a document, use the 'modify()' and 'unset()'
methods.  For example, the following query removes the GNP from a
document that matches the search condition.

     mysql-py> db.countryinfo.modify("Name = 'Sealand'").unset("GNP")
     Query OK, 1 item affected (0.01 sec)

Use the 'find()' method to verify the change.

     mysql-py> db.countryinfo.find("Name = 'Sealand'")
     [
         {
             "IndepYear": 1967,
             "Name": "Sealand",
             "_id": "SEA",
             "demographics": {
                 "LifeExpectancy": 78,
                 "Population": 28
             },
             "geography": {
                 "Continent": "Europe",
                 "Region": "British Islands",
                 "SurfaceArea": 193
             },
             "government": {
                 "GovernmentForm": "Monarchy",
                 "HeadOfState": "Michael Bates"
             }
         }
     ]
     1 document in set (0.00 sec)

*Append, Insert, and Delete Arrays*

To append an element to an array field, or insert, or delete elements in
an array, use the 'array_append()', 'array_insert()', or
'array_delete()' methods.  The following examples modify the countryinfo
collection to enable tracking of international airports.

The first example uses the 'modify()' and 'set()' methods to create a
new Airports field in all documents.

*Caution*:

Use care when you modify documents without specifying a search
condition.  This action will modify all documents in the collection.

     mysql-py> db.countryinfo.modify("True").set("Airports", [])
     Query OK, 240 items affected (0.07 sec)

With the Airports field added, the next example uses the
'array_append()' method to add a new airport to one of the documents.
_$.Airports_ in the following example represents the Airports field of
the current document.

     mysql-py> db.countryinfo.modify("Name = 'France'").array_append("$.Airports", "ORY")
     Query OK, 1 item affected (0.02 sec)

Use db.countryinfo.find("Name = 'France'") to see the change.

To insert an element at a different position in the array, use the
'array_insert()' method to specify which index to insert in the path
expression.  In this case, the index is 0, or the first element in the
array.

     mysql-py> db.countryinfo.modify("Name = 'France'").array_insert("$.Airports[0]", "CDG")
     Query OK, 1 item affected (0.04 sec)

To delete an element from the array, you must pass to the
'array_delete()' method the index of the element to be deleted.

     mysql-py> db.countryinfo.modify("Name = 'France'").array_delete("$.Airports[1]")
     Query OK, 1 item affected (0.03 sec)

*Related Information*

   * The MySQL Reference Manual provides instructions to help you search
     for and modify JSON values.

   * See CollectionModifyFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionmodifyfunction)
     for the full syntax definition.

19.5.4.5 Remove Documents
.........................

You can use the 'remove()' method to delete some or all documents from a
collection in a database.  The X DevAPI provides additional methods for
use with the 'remove()' method to filter and sort the documents to be
removed.

*Remove Documents Using Conditions*

The example that follows passes a search condition to the 'remove()'
method.  All documents matching the condition will be removed from the
countryinfo collection.  In this example, one document matches the
condition.

     mysql-py> db.countryinfo.remove("_id = 'SEA'")
     Query OK, 1 item affected (0.02 sec)

*Remove the First Document*

To remove the first document in the countryinfo collection, use the
'limit()' method with a value of 1.

     mysql-py> db.countryinfo.remove("True").limit(1)
     Query OK, 1 item affected (0.03 sec)

*Remove the Last Document in an Order*

The following example removes the last document in the countryinfo
collection by country name.

     mysql-py> db.countryinfo.remove("True").sort(["Name desc"]).limit(1)
     Query OK, 1 item affected (0.02 sec)

*Remove All Documents in a Collection*

You can remove all documents in a collection.  To do so, use the
'remove("True")' method without specifying a search condition.

*Caution*:

Use care when you remove documents without specifying a search
condition.  This action will delete all documents from the collection.

*Related Information*

   * See CollectionRemoveFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-crud-functions.html#crud-ebnf-collectionremovefunction)
     for the full syntax definition.

   * See mysql-shell-tutorial-python-download for instructions
     to recreate the 'world_x' database.

19.5.4.6 Create and Drop Indexes
................................

Indexes are used to find documents with specific field values quickly.
Without an index, MySQL must begin with the first document and then read
through the entire collection to find the relevant fields.  The larger
the collection, the more this costs.  If a collection is large and
queries on a specific field are common, then consider creating an index
on a specific field inside a document.

For example, the following query will perform better with an index:

     mysql-js> db.countryinfo.find("demographics.Population < 100")
     ...[_output removed_]
     8 documents in set (0.00 sec)

The 'create_index()' method creates an index that you can define as
nonunique or unique.  Use the 'field()' method to chain the fields that
should be indexed.  The 'execute()' method is required to create or drop
an index.

In MySQL, the '_id' field is equivalent to a primary key by default.

*Add a Nonunique Index*

To create a nonunique index, pass to the 'create_index()' method an
index name.  Duplicate index names are prohibited.

In the following example, the first parameter of the 'field()' method
specifies the Population field inside the demographics object and the
next parameter indicates that the field should be indexed as an Integer
numeric value.  The last parameter indicates whether the field should
require the NOT NULL constraint.  If the value is 'False', the field can
contain 'NULL' values.

     mysql-js> db.countryinfo.create_index("pop").\
     field("demographics.Population", "INTEGER", False).execute()
     Query OK (0.04 sec)

*Add a Unique Index*

To create a unique index, pass to the 'create_index()' method an index
name and the 'mysqlx.IndexType.UNIQUE' type.  Country '"Name"' is
another common field in the countryinfo collection to index.  In the
following example, '"Text(40)"' represents the number of characters to
index and 'True' indicates that the field cannot contain any 'NULL'
values.

     mysql-js> db.countryinfo.create_index("name", mysqlx.IndexType.UNIQUE).\
     field("Name", "TEXT(40)", True).execute()
     Query OK (0.04 sec)

*Drop an Index*

To drop an index, pass to the 'drop_index()' method the name of the
index to drop.  For example, you can drop the 'pop' index as follows:

     mysql-js> db.countryinfo.drop_index("pop").execute()
     Query OK (0.58 sec)

*Related Information*

   * See Collection Index Management Functions
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-collection-index-management-functions.html)
     for the full syntax definition.

19.5.5 Relational Tables
------------------------

You can use MySQL Shell to manipulate not just JSON documents, but also
relational tables.

In MySQL, each relational table is associated with a particular storage
engine.  The examples in this section use 'InnoDB'
tables in the 'world_x' database.

*Confirm the Schema*

To show the value that is assigned to the schema variable, type 'db'.

     mysql-py> db

If the schema value is not the 'Schema:world_x' database, then set the
'db' variable as follows:

     mysql-py> \use world_x

*Show All Tables*

To display all relational tables in the 'world_x' database, use the
'get_tables()' method on the schema object.

     mysql-py> db.get_tables()
     {
         "city": <Table:city>,
         "country": <Table:country>,
         "countrylanguage": <Table:countrylanguage>
     }

*Basic Table Operations*

Basic operations scoped by tables include:

Operation form          Description

'db.NAME.insert()'      The insert().
                        method inserts one or more records into the
                        named table.

'db.NAME.select()'      The select().
                        method returns some or all records in the named
                        table.

'db.NAME.update()'      The update().
                        method updates records in the named table.

'db.NAME.delete()'      The delete().
                        method deletes one or more records from the
                        named table.

*Related Information*

   * See Working with Relational Tables
     (http://dev.mysql.com/doc/x-devapi-userguide/en/devapi-users-working-with-relational-tables.html)
     for a general overview.

   * CRUD EBNF Definitions
     (http://dev.mysql.com/doc/x-devapi-userguide/en/mysql-x-crud-ebnf-definitions.html)
     provides a complete list of operations.

   * See mysql-shell-tutorial-python-download for instructions
     on setting up the 'world_x' database sample.

19.5.5.1 Insert Records into Tables
...................................

You can use the 'insert()' method with the 'values()' method to insert
records into an existing relational table.  The 'insert()' method
accepts individual columns or all columns in the table.  Use one or more
'values()' methods to specify the values to be inserted.

*Insert a Complete Record*

To insert a complete record, pass to the 'insert()' method all columns
in the table.  Then pass to the 'values()' method one value for each
column.  For example, to add a new record to the city table in the
'world_x' database, insert the following record and press 'Enter' twice.

     mysql-py> db.city.insert("ID", "Name", "CountryCode", "District", "Info").\
     values(None, "Olympia", "USA", "Washington", '{"Population": 5000}')
     Query OK, 1 item affected (0.01 sec)

The city table has five columns: ID, Name, CountryCode, District, and
Info.  Each value must match the data type of the column it represents.

*Insert a Partial Record*

The following example inserts values into the ID, Name, and CountryCode
columns of the city table.

     mysql-py> db.city.insert("ID", "Name", "CountryCode").\
     values(None, "Little Falls", "USA").values(None, "Happy Valley", "USA")
     Query OK, 2 item affected (0.03 sec)

When you specify columns using the 'insert()' method, the number of
values must match the number of columns.  In the previous example, you
must supply three values to match the three columns specified.

*Related Information*

   * See TableInsertFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tableinsertfunction)
     for the full syntax definition.

19.5.5.2 Select Tables
......................

You can use the 'select()' method to query for and return records from a
table in a database.  The X DevAPI provides additional methods to use
with the 'select()' method to filter and sort the returned records.

MySQL provides the following operators to specify search conditions:
'OR' ('||'), 'AND' ('&&'), 'XOR', 'IS', 'NOT', 'BETWEEN', 'IN', 'LIKE',
'!=', '<>', '>', '>=', '<', '<=', '&', '|', '<<', '>>', '+', '-', '*',
'/', '~', and '%'.

*Select All Records*

To issue a query that returns all records from an existing table, use
the 'select()' method without specifying search conditions.  The
following example selects all records from the city table in the
'world_x' database.

*Note*:

Limit the use of the empty 'select()' method to interactive statements.
Always use explicit column-name selections in your application code.

     mysql-py> db.city.select()
     +------+------------+-------------+------------+-------------------------+
     | ID   | Name       | CountryCode | District   | Info                    |
     +------+------------+-------------+------------+-------------------------+
     |    1 | Kabul      | AFG         | Kabol      |{"Population": 1780000}  |
     |    2 | Qandahar   | AFG         | Qandahar   |{"Population": 237500}   |
     |    3 | Herat      | AFG         | Herat      |{"Population": 186800}   |
     ...    ...          ...           ...          ...
     | 4079 | Rafah      | PSE         | Rafah      |{"Population": 92020}    |
     +------+------- ----+-------------+------------+-------------------------+
     4082 rows in set (0.01 sec)

An empty set (no matching records) returns the following information:

     Empty set (0.00 sec)

*Filter Searches*

To issue a query that returns a set of table columns, use the 'select()'
method and specify the columns to return between square brackets.  This
query returns the Name and CountryCode columns from the city table.

     mysql-py> db.city.select(["Name", "CountryCode"])
     +-------------------+-------------+
     | Name              | CountryCode |
     +-------------------+-------------+
     | Kabul             | AFG         |
     | Qandahar          | AFG         |
     | Herat             | AFG         |
     | Mazar-e-Sharif    | AFG         |
     | Amsterdam         | NLD         |
     ...                 ...
     | Rafah             | PSE         |
     | Olympia           | USA         |
     | Little Falls      | USA         |
     | Happy Valley      | USA         |
     +-------------------+-------------+
     4082 rows in set (0.00 sec)

To issue a query that returns rows matching specific search conditions,
use the 'where()' method to include those conditions.  For example, the
following example returns the names and country codes of the cities that
start with the letter Z.

     mysql-py> db.city.select(["Name", "CountryCode"]).where("Name like 'Z%'")
     +-------------------+-------------+
     | Name              | CountryCode |
     +-------------------+-------------+
     | Zaanstad          | NLD         |
     | Zoetermeer        | NLD         |
     | Zwolle            | NLD         |
     | Zenica            | BIH         |
     | Zagazig           | EGY         |
     | Zaragoza          | ESP         |
     | Zamboanga         | PHL         |
     | Zahedan           | IRN         |
     | Zanjan            | IRN         |
     | Zabol             | IRN         |
     | Zama              | JPN         |
     | Zhezqazghan       | KAZ         |
     | Zhengzhou         | CHN         |
     ...                 ...
     | Zeleznogorsk      | RUS         |
     +-------------------+-------------+
     59 rows in set (0.00 sec)

You can separate a value from the search condition by using the 'bind()'
method.  For example, instead of using "Name = 'Z%' " as the condition,
substitute a named placeholder consisting of a colon followed by a name
that begins with a letter, such as _name_.  Then include the placeholder
and value in the 'bind()' method as follows:

     mysql-py> db.city.select(["Name", "CountryCode"]).\
                   where("Name like :name").bind("name", "Z%")

*Tip*:

Within a program, binding enables you to specify placeholders in your
expressions, which are filled in with values before execution and can
benefit from automatic escaping, as appropriate.

Always use binding to sanitize input.  Avoid introducing values in
queries using string concatenation, which can produce invalid input and,
in some cases, can cause security issues.

*Project Results*

To issue a query using the 'AND' operator, add the operator between
search conditions in the 'where()' method.

     mysql-py> db.city.select(["Name", "CountryCode"]).\
                    where("Name like 'Z%' and CountryCode = 'CHN'")
     +----------------+-------------+
     | Name           | CountryCode |
     +----------------+-------------+
     | Zhengzhou      | CHN         |
     | Zibo           | CHN         |
     | Zhangjiakou    | CHN         |
     | Zhuzhou        | CHN         |
     | Zhangjiang     | CHN         |
     | Zigong         | CHN         |
     | Zaozhuang      | CHN         |
     ...              ...
     | Zhangjiagang   | CHN         |
     +----------------+-------------+
     22 rows in set (0.01 sec)

To specify multiple conditional operators, you can enclose the search
conditions in parenthesis to change the operator precedence.  The
following example demonstrates the placement of 'AND' and 'OR'
operators.

     mysql-py> db.city.select(["Name", "CountryCode"]).\
     where("Name like 'Z%' and (CountryCode = 'CHN' or CountryCode = 'RUS')")
     +-------------------+-------------+
     | Name              | CountryCode |
     +-------------------+-------------+
     | Zhengzhou         | CHN         |
     | Zibo              | CHN         |
     | Zhangjiakou       | CHN         |
     | Zhuzhou           | CHN         |
     ...                 ...
     | Zeleznogorsk      | RUS         |
     +-------------------+-------------+
     29 rows in set (0.01 sec)

*Limit, Order, and Offset Results*

You can apply the 'limit()', 'order_by()', and 'offset()' methods to
manage the number and order of records returned by the 'select()'
method.

To specify the number of records included in a result set, append the
'limit()' method with a value to the 'select()' method.  For example,
the following query returns the first five records in the country table.

     mysql-py> db.country.select(["Code", "Name"]).limit(5)
     +------+-------------+
     | Code | Name        |
     +------+-------------+
     | ABW  | Aruba       |
     | AFG  | Afghanistan |
     | AGO  | Angola      |
     | AIA  | Anguilla    |
     | ALB  | Albania     |
     +------+-------------+
     5 rows in set (0.00 sec)

To specify an order for the results, append the 'order_by()' method to
the 'select()' method.  Pass to the 'order_by()' method a list of one or
more columns to sort by and, optionally, the descending ('desc') or
ascending ('asc') attribute as appropriate.  Ascending order is the
default order type.

For example, the following query sorts all records by the Name column
and then returns the first three records in descending order .

     mysql-py> db.country.select(["Code", "Name"]).order_by(["Name desc"]).limit(3)
     +------+------------+
     | Code | Name       |
     +------+------------+
     | ZWE  | Zimbabwe   |
     | ZMB  | Zambia     |
     | YUG  | Yugoslavia |
     +------+------------+
     3 rows in set (0.00 sec)

By default, the 'limit()' method starts from the first record in the
table.  You can use the 'offset()' method to change the starting record.
For example, to ignore the first record and return the next three
records matching the condition, pass to the 'offset()' method a value of
1.

     mysql-py> db.country.select(["Code", "Name"]).order_by(["Name desc"]).limit(3).offset(1)
     +------+------------+
     | Code | Name       |
     +------+------------+
     | ZMB  | Zambia     |
     | YUG  | Yugoslavia |
     | YEM  | Yemen      |
     +------+------------+
     3 rows in set (0.00 sec)

*Related Information*

   * The MySQL Reference Manual provides detailed
     documentation on functions and operators.

   * See TableSelectFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tableselectfunction)
     for the full syntax definition.

19.5.5.3 Update Tables
......................

You can use the 'update()' method to modify one or more records in a
table.  The 'update()' method works by filtering a query to include only
the records to be updated and then applying the operations you specify
to those records.

To replace a city name in the city table, pass to the 'set()' method the
new city name.  Then, pass to the 'where()' method the city name to
locate and replace.  The following example replaces the city Peking with
Beijing.

     mysql-py> db.city.update().set("Name", "Beijing").where("Name = 'Peking'")
     Query OK, 1 item affected (0.04 sec)

Use the 'select()' method to verify the change.

     mysql-py> db.city.select(["ID", "Name", "CountryCode", "District", "Info"]).where("Name = 'Beijing'")
     +------+-----------+-------------+----------+-----------------------------+
     | ID   | Name      | CountryCode | District | Info                        |
     +------+-----------+-------------+----------+-----------------------------+
     | 1891 | Beijing   | CHN         | Peking   | {"Population": 7472000}     |
     +------+-----------+-------------+----------+-----------------------------+
     1 row in set (0.00 sec)

*Related Information*

   * See TableUpdateFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tableupdatefunction)
     for the full syntax definition.

19.5.5.4 Delete Tables
......................

You can use the 'delete()' method to remove some or all records from a
table in a database.  The X DevAPI provides additional methods to use
with the 'delete()' method to filter and order the records to be
deleted.

*Delete Records Using Conditions*

The example that follows passes search conditions to the 'delete()'
method.  All records matching the condition will be deleted from the
city table.  In this example, one record matches the condition.

     mysql-py> db.city.delete().where("Name = 'Olympia'")
     Query OK, 1 item affected (0.01 sec)

*Delete the First Record*

To delete the first record in the city table, use the 'limit()' method
with a value of 1.

     mysql-py> db.city.delete().limit(1)
     Query OK, 1 item affected (0.02 sec)

*Delete All Records in a Table*

You can delete all records in a table.  To do so, use the 'delete()'
method without specifying a search condition.

*Caution*:

Use care when you delete records without specifying a search condition.
This action will delete all records from the table.

*Related Information*

   * See TableDeleteFunction
     (http://dev.mysql.com/doc/x-devapi-userguide/en/crud-ebnf-table-crud-functions.html#crud-ebnf-tabledeletefunction)
     for the full syntax definition.

   * See mysql-shell-tutorial-python-download for instructions
     to recreate the 'world_x' database.

19.5.6 Documents in Tables
--------------------------

In MySQL, a table may contain traditional relational data, JSON values,
or both.  You can combine traditional data with JSON documents by
storing the documents in columns having a native 'JSON'.
data type.

Examples in this section use the city table in the 'world_x' database.

*city Table Description*

The city table has five columns (or fields).

     +---------------+------------+-------+-------+---------+------------------+
     | Field         | Type       | Null  | Key   | Default | Extra            |
     +---------------+------------+-------+-------+---------+------------------+
     | ID            | int(11)    | NO    | PRI   | null    | auto_increment   |
     | Name          | char(35)   | NO    |       |         |                  |
     | CountryCode   | char(3)    | NO    |       |         |                  |
     | District      | char(20)   | NO    |       |         |                  |
     | Info          | json       | YES   |       | null    |                  |
     +---------------+------------+-------+-------+---------+------------------+

*Insert a Record*

To insert a document into the column of a table, pass to the 'values()'
method a well-formed JSON document in the correct order.  In the
following example, a document is passed as the final value to be
inserted into the Info column.

      mysql-py> db.city.insert().\
     values(None, "San Francisco", "USA", "California", '{"Population":830000}')
     Query OK, 1 item affected (0.01 sec)

*Select a Record*

You can issue a query with a search condition that evaluates document
values in the expression.

     mysql-py> db.city.select(["ID", "Name", "CountryCode", "District", "Info"]).\
       where("CountryCode = :country and Info->'$.Population' > 1000000").\
       bind('country', 'USA')
     +------+----------------+-------------+----------------+-----------------------------+
     | ID   | Name           | CountryCode | District       | Info                        |
     +------+----------------+-------------+----------------+-----------------------------+
     | 3793 | New York       | USA         | New York       | {"Population": 8008278}     |
     | 3794 | Los Angeles    | USA         | California     | {"Population": 3694820}     |
     | 3795 | Chicago        | USA         | Illinois       | {"Population": 2896016}     |
     | 3796 | Houston        | USA         | Texas          | {"Population": 1953631}     |
     | 3797 | Philadelphia   | USA         | Pennsylvania   | {"Population": 1517550}     |
     | 3798 | Phoenix        | USA         | Arizona        | {"Population": 1321045}     |
     | 3799 | San Diego      | USA         | California     | {"Population": 1223400}     |
     | 3800 | Dallas         | USA         | Texas          | {"Population": 1188580}     |
     | 3801 | San Antonio    | USA         | Texas          | {"Population": 1144646}     |
     +------+----------------+-------------+----------------+-----------------------------+
     9 rows in set (0.01 sec)

*Related Information*

   * See Working with Relational Tables and Documents
     (http://dev.mysql.com/doc/x-devapi-userguide/en/devapi-users-working-with-relational-tables-and-documents.html)
     for a general overview.

   * See json for a detailed description of the data type.

19.6 Quick-Start Guide: MySQL for Visual Studio
===============================================

This section explains how to use MySQL Shell to script a server using
MySQL for Visual Studio.

*Introduction*

MySQL for Visual Studio provides access to MySQL objects and data
without forcing developers to leave Visual Studio.  Designed and
developed as a Visual Studio package, MySQL for Visual Studio integrates
directly into Server Explorer providing a seamless experience for
setting up new connections and working with database objects.

The following MySQL for Visual Studio features are available as of
version 2.0.2:

   * JavaScript and Python code editors, where scripts in those
     languages can be executed to query data from a MySQL database.

   * Better integration with the Server Explorer to open MySQL,
     JavaScript, and Python code editors directly from a connected MySQL
     instance.

   * A newer user interface for displaying query results, where
     different views are presented from result sets returned by a MySQL
     Server like:

        * Multiple tabs for each result set returned by an executed
          query.

        * Results view, where the information can be seen in grid, tree,
          or text representation for JSON results.

        * Field types view, where information about the columns of a
          result set is shown, such as names, data types, character
          sets, and more.

        * Query statistics view, displaying information about the
          executed query such as execution times, processed rows, index
          and temporary tables usage, and more.

        * Execution plan view, displaying an explanation of the query
          execution done internally by the MySQL Server.

*Getting Started*

The requirements are MySQL for Visual Studio 2.0.2 or higher, and Visual
Studio 2010 or higher.  X DevAPI support requires MySQL Server 5.7.12 or
higher with the X plugin enabled.

*Opening a Code Editor*

Before opening a code editor that can execute queries against a MySQL
server, a connection needs to be established:

  1. Open the Server Explorer pane through the View menu, or with
     'Control' + 'W', 'K'.

  2. Right-click on the Data Connections node, select 'Add
     Connection...'.

  3. In the 'Add Connection' dialog, make sure the MySQL Data Provider
     is being used and fill in all the information.

     *Note*:

     To enter the port number, click 'Advanced...' and set the Port
     among the list of connection properties.

  4. Click 'Test Connection' to ensure you have a valid connection, then
     click 'OK'.

  5. Right-click your newly created connection, select 'New MySQL
     Script' and then the language for the code editor you want to open.

For existing MySQL connections, to create a new editor you need only to
do the last step.

*Using the Code Editor*

The MySQL script editors have a toolbar at the top where information
about the session is displayed, along with the actions that can be
executed.

*Note*:

Note the first two buttons in the toolbar represent a way to connect or
disconnect from a MySQL server.  If the editor was opened from the
Server Explorer, the connection will be already established for the new
editor window.

The third button is the 'Run' button, the script contained in the editor
window is executed by clicking it and results from the script execution
are displayed below the script window.

*Note*:

Some commands in the MySQL Shell can be executed without appending
'execute()' while in interactive mode.  In MySQL for Visual Studio,
these commands do require 'execute()'.  In other words, append
".execute()" to execute commands.

19.7 X Plugin
=============

This section explains how to configure and monitor the X Plugin.

19.7.1 Using Secure Connections with X Plugin
---------------------------------------------

This section explains how to configure X Plugin to use secure
connections.  For more background information, see
encrypted-connections.

X Plugin has its own SSL settings which can differ from those used with
MySQL Server.  This means that X Plugin can be configured with a
different SSL key, certificate, and certificate authorities file than
MySQL Server.  Similarly, X Plugin has its own SSL status variables
calculated independently from the MySQL Server SSL related variables.
By default the X Plugin SSL configuration is taken from the
'mysqlx_ssl_*' variables, described at
x-plugin-system-variables-options.  If no configuration is provided
using the 'mysqlx_ssl_*' variables, X Plugin falls back to using the
MySQL Server SSL system variables.  This means you can choose to either
have separate SSL configurations for MySQL Protocol and X Protocol
connections by configuring each separately, or share the SSL
configuration between MySQL Protocol and X Protocol connections by only
configuring the 'ssl-*' variables.

On a server with X Plugin installed, to configure MySQL Protocol and X
Protocol connections with separate SSL configurations use both the
'ssl-*' and 'mysqlx-ssl-*' variables in 'my.cnf':

     [mysqld]
     ssl-ca=ca1.pem
     ssl-cert=server-cert1.pem
     ssl-key=server-key1.pem

     mysqlx-ssl-ca=ca2.pem
     mysqlx-ssl-cert=server-cert2.pem
     mysqlx-ssl-key=server-key2.pem

The available 'mysqlx_ssl_*' variables mirror the SSL variables in MySQL
Server, so the files and techniques described for configuring MySQL
Server to use SSL at using-encrypted-connections are relevant to
configuring X Plugin to use secure connections.  An exception to this
rule is the 'mysqlx_ssl' variable, which defaults to '1' whenever any of
the other X Protocol SSL related variables is configured.  In other
words, if you configure any of the 'mysqlx_ssl_*' variables there is no
need to configure 'mysqlx_ssl'.

You can configure the TLS versions used by X Protocol SSL connections
using the 'tls_version' system variable.  The TLS version used by MySQL
Protocol and X Protocol connections is therefore the same TLS version.

Encryption per connection is optional, but a specific user can be forced
to use encryption for X Protocol and MySQL Protocol connections.  You
configure such a user by issuing a 'GRANT' statement with
the 'REQUIRE' option.  For more details see grant.
Alternatively all X Protocol and MySQL Protocol connections can be
forced to use encryption by setting 'require_secure_transport'.

19.7.2 X Plugin Options and Variables
-------------------------------------

This section describes the command options and system variables which
configure X Plugin.  If values specified at startup time are incorrect,
X Plugin could fail to initialize properly and the server does not load
it.  In this case, the server could also produce error messages for
other X Plugin settings because it cannot recognize them.

19.7.2.1 X Plugin Option and Variable Reference
...............................................

This table provides an overview of the command options, and system and
status variables provided by X Plugin.

*X Plugin Option and Variable Reference*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

Mysqlx_aborted_clients                             Yes         Global      No

Mysqlx_address                                     Yes         Global      No

mysqlx-bind-addressYes     Yes         Yes                     Global      No

mysqlx_bind_addressYes     Yes         Yes                     Global      No

Mysqlx_bytes_received                              Yes         Both        No

Mysqlx_bytes_sent                                  Yes         Both        No

mysqlx-connect-timeoutYes  Yes         Yes                     Global      Yes

mysqlx_connect_timeoutYes  Yes         Yes                     Global      Yes

Mysqlx_connection_accept_errors                    Yes         Both        No

Mysqlx_connection_errors                           Yes         Both        No

Mysqlx_connections_accepted                        Yes         Global      No

Mysqlx_connections_closed                          Yes         Global      No

Mysqlx_connections_rejected                        Yes         Global      No

Mysqlx_crud_create_view                            Yes         Both        No

Mysqlx_crud_delete                                 Yes         Both        No

Mysqlx_crud_drop_view                              Yes         Both        No

Mysqlx_crud_find                                   Yes         Both        No

Mysqlx_crud_insert                                 Yes         Both        No

Mysqlx_crud_modify_view                            Yes         Both        No

Mysqlx_crud_update                                 Yes         Both        No

Mysqlx_errors_sent                                 Yes         Both        No

Mysqlx_errors_unknown_message_type                 Yes         Both        No

Mysqlx_expect_close                                Yes         Both        No

Mysqlx_expect_open                                 Yes         Both        No

mysqlx-idle-worker-thread-timeoutYesYesYes                     Global      Yes

mysqlx_idle_worker_thread_timeoutYesYesYes                     Global      Yes

Mysqlx_init_error                                  Yes         Both        No

mysqlx-max-allowed-packetYesYes        Yes                     Global      Yes

mysqlx_max_allowed_packetYesYes        Yes                     Global      Yes

mysqlx-max-connectionsYes  Yes         Yes                     Global      Yes

mysqlx_max_connectionsYes  Yes         Yes                     Global      Yes

mysqlx-min-worker-threadsYesYes        Yes                     Global      Yes

mysqlx_min_worker_threadsYesYes        Yes                     Global      Yes

Mysqlx_notice_other_sent                           Yes         Both        No

Mysqlx_notice_warning_sent                         Yes         Both        No

Mysqlx_port                                        Yes         Global      No

mysqlx-port    Yes         Yes         Yes                     Global      No

mysqlx_port    Yes         Yes         Yes                     Global      No

mysqlx-port-open-timeoutYesYes         Yes                     Global      No

mysqlx_port_open_timeoutYesYes         Yes                     Global      No

Mysqlx_rows_sent                                   Yes         Both        No

Mysqlx_sessions                                    Yes         Global      No

Mysqlx_sessions_accepted                           Yes         Global      No

Mysqlx_sessions_closed                             Yes         Global      No

Mysqlx_sessions_fatal_error                        Yes         Global      No

Mysqlx_sessions_killed                             Yes         Global      No

Mysqlx_sessions_rejected                           Yes         Global      No

Mysqlx_socket                                      Yes         Global      No

mysqlx-socket  Yes         Yes         Yes                     Global      No

mysqlx_socket  Yes         Yes         Yes                     Global      No

mysqlx-ssl     Yes         Yes         Yes                     Global      No

Mysqlx_ssl_accept_renegotiates                     Yes         Global      No

Mysqlx_ssl_accepts                                 Yes         Global      No

Mysqlx_ssl_active                                  Yes         Both        No

mysqlx-ssl-ca  Yes         Yes         Yes                     Global      No

mysqlx-ssl-capathYes       Yes         Yes                     Global      No

mysqlx-ssl-certYes         Yes         Yes                     Global      No

Mysqlx_ssl_cipher                                  Yes         Both        No

mysqlx-ssl-cipherYes       Yes

Mysqlx_ssl_cipher_list                             Yes         Both        No

mysqlx-ssl-crl Yes         Yes         Yes                     Global      No

mysqlx-ssl-crlpathYes      Yes         Yes                     Global      No

Mysqlx_ssl_ctx_verify_depth                        Yes         Both        No

Mysqlx_ssl_ctx_verify_mode                         Yes         Both        No

Mysqlx_ssl_finished_accepts                        Yes         Global      No

mysqlx-ssl-key Yes         Yes         Yes                     Global      No

Mysqlx_ssl_server_not_after                        Yes         Global      No

Mysqlx_ssl_server_not_before                       Yes         Global      No

Mysqlx_ssl_verify_depth                            Yes         Global      No

Mysqlx_ssl_verify_mode                             Yes         Global      No

Mysqlx_ssl_version                                 Yes         Both        No

Mysqlx_stmt_create_collection                      Yes         Both        No

Mysqlx_stmt_create_collection_index                Yes         Both        No

Mysqlx_stmt_disable_notices                        Yes         Both        No

Mysqlx_stmt_drop_collection                        Yes         Both        No

Mysqlx_stmt_drop_collection_index                  Yes         Both        No

Mysqlx_stmt_enable_notices                         Yes         Both        No

Mysqlx_stmt_ensure_collection                      Yes         Both        No

Mysqlx_stmt_execute_mysqlx                         Yes         Both        No

Mysqlx_stmt_execute_sql                            Yes         Both        No

Mysqlx_stmt_execute_xplugin                        Yes         Both        No

Mysqlx_stmt_kill_client                            Yes         Both        No

Mysqlx_stmt_list_clients                           Yes         Both        No

Mysqlx_stmt_list_notices                           Yes         Both        No

Mysqlx_stmt_list_objects                           Yes         Both        No

Mysqlx_stmt_ping                                   Yes         Both        No

Mysqlx_worker_threads                              Yes         Global      No

Mysqlx_worker_threads_active                       Yes         Global      No

19.7.2.2 X Plugin System Variables and Options
..............................................

The following command options configure X Plugin:

   *
     '--mysqlx-bind-address[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-bind-address=#'

     *Introduced*                         5.7.17

     *System Variable*                    'mysqlx_bind_address'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      '*'

     Specifies the network address which X Plugin uses for connections.
     The equivalent of 'bind_address' for X Plugin.

     By default X Plugin listens for connections on a single IPv4 TCP/IP
     network socket.  Use this option to configure where X Plugin
     listens for connections, such as binding to an IPv6 address, all
     IPv4 and IPv6 addresses or a default IPv6 address with a fallback
     IPv4 address.

     X Plugin treats different types of addresses as follows:

        * If the address is '*', X Plugin accepts TCP/IP connections on
          all server host IPv6 and IPv4 interfaces if the server host
          supports IPv6, or accepts TCP/IP connections on all IPv4
          addresses otherwise.  Use this address to permit both IPv4 and
          IPv6 connections on all server interfaces.  This value is the
          default.

        * If the address is '0.0.0.0', X Plugin accepts TCP/IP
          connections on all server host IPv4 interfaces.  This value is
          the default.

        * If the address is '::', X Plugin accepts TCP/IP connections on
          all server host IPv4 and IPv6 interfaces.

        * If the address is '*', X Plugin accepts TCP/IP connections on
          all server host IPv6 and IPv4 interfaces if the server host
          supports IPv6, or accepts TCP/IP connections on all IPv4
          addresses otherwise.  Use this address to permit both IPv4 and
          IPv6 connections for X Plugin.

        * If the address is an IPv4-mapped address, X Plugin accepts
          TCP/IP connections for that address, in either IPv4 or IPv6
          format.  For example, if X Plugin is bound to
          '::ffff:127.0.0.1', a client such as MySQL Shell can connect
          using '--host=127.0.0.1' or '--host=::ffff:127.0.0.1'.

        * If the address is a 'regular' IPv4 or IPv6 address (such as
          '127.0.0.1' or '::1'), X Plugin accepts TCP/IP connections
          only for that IPv4 or IPv6 address.

   *
     '--mysqlx-connect-timeout[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-connect-timeout=#'

     *System Variable*                    'mysqlx_connect_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '30'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1000000000'

     Number of seconds X Plugin waits for the first packet to be
     received from newly connected clients.  The X Plugin equivalent of
     'connect_timeout'.

   *
     '--mysqlx-idle-worker-thread-timeout[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-idle-worker-thread-timeout=#'

     *System Variable*                    'mysqlx_idle_worker_thread_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '60'

     *Minimum Value*                      '0'

     *Maximum Value*                      '3600'

     Time in seconds after which an idle worker thread is terminated.

   *
     '--mysqlx-max-allowed-packet[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-max-allowed-packet=#'

     *System Variable*                    'mysqlx_max_allowed_packet'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1048576'

     *Minimum Value*                      '512'

     *Maximum Value*                      '1073741824'

     Maxmum size of a network packet that X Plugin can process.

   *
     '--mysqlx-max-connections[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-max-connections=#'

     *System Variable*                    'mysqlx_max_connections'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '100'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     Maximum number of concurrent client connections the X Plugin can
     accept.  When modifying this variable, if the new value is smaller
     than the current number of connections, the new limit is only taken
     into account for new connections.

   *
     '--mysqlx-min-worker-threads[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-min-worker-threads=value'

     *Introduced*                         5.7.12

     *System Variable*                    'mysqlx_min_worker_threads'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '2'

     *Minimum Value*                      '1'

     *Maximum Value*                      '100'

     The minimum number of worker threads the X Plugin uses for handling
     client requests.

   *
     '--mysqlx-port[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-port=#'

     *System Variable*                    'mysqlx_port'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '33060'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     Specifies the port where the X Plugin listens for connections.  The
     equivalent of 'port' for X Plugin.

   *
     '--mysqlx-port-open-timeout[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-port-open-timeout=#'

     *Introduced*                         5.7.17

     *System Variable*                    'mysqlx_port_open_timeout'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '1'

     *Maximum Value*                      '120'

     The amount of time in seconds which X Plugin waits for a TCP/IP
     port to become free.

   *
     '--mysqlx-socket[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-socket=file_name'

     *Introduced*                         5.7.15

     *System Variable*                    'mysqlx_socket'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      '/tmp/mysqlx.sock'

     The path to a Unix socket file which X Plugin uses for connections.
     Only used by MySQL Server when running on Unix operating systems.
     Clients can then use this socket to connect to MySQL Server using
     the X Plugin.

     The value of 'mysqlx_socket' depends on the value of 'socket'.  By
     default 'socket' is '/tmp/mysql.sock' and therefore 'mysqlx_socket'
     is '/tmp/mysqlx.sock'.  If 'socket' is set to '/sockets/mysql.sock'
     and 'mysqlx_socket' has not been manually configured, then
     'mysqlx_socket' is set to '/sockets/mysqlx.sock'.  In other words
     the path and filename of 'socket' is used and an 'x' is appended to
     the filename, this enables you to conveniently store the sockets
     used by MySQL server at a single path.  To define separate paths or
     unique filenames for the MySQL and X Plugin sockets, configure both
     the 'socket' and the 'mysqlx_socket' system variables.  For example
     in a configuration file:

          socket=/home/sockets/mysqld/mysql.sock
          mysqlx_socket=/home/sockets/xplugin/xplugin.sock

     Alternatively, X Plugin can be configured at compile time to use a
     specific socket with the 'MYSQLX_UNIX_ADDR' option.  If the X
     Plugin 'MYSQLX_UNIX_ADDR' compile option is not set, the value is
     based on the 'MYSQL_UNIX_ADDR' and adds an 'x' to the file name,
     for example resulting in '/tmp/mysqlx.sock'.

   *
     '--mysqlx-ssl[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl=#'

     *System Variable*                    'mysqlx_ssl'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     The equivalent of 'ssl' for X Plugin, see that variable for more
     information.

   *
     '--mysqlx-ssl-ca[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl-ca=file-name'

     *System Variable*                    'mysqlx_ssl_ca'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The equivalent of 'ssl_ca' for X Plugin, see that variable for more
     information.

   *
     '--mysqlx-ssl-capath[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl-capath=dir_name'

     *System Variable*                    'mysqlx_ssl_capath'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The equivalent of 'ssl_capath' for X Plugin, see that variable for
     more information.

   *
     '--mysqlx-ssl-cert[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl-cert=name'

     *System Variable*                    'mysqlx_ssl_cert'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The equivalent of 'ssl_cert' for X Plugin, see that variable for
     more information.

   *
     '--mysqlx-ssl-cipher[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl-cipher=name'

     *Type*                               string

     The equivalent of 'ssl_cipher' for X Plugin, see that variable for
     more information.

   *
     '--mysqlx-ssl-crl[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl-crl=file_name'

     *System Variable*                    'mysqlx_ssl_crl'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The equivalent of 'ssl_crl' for X Plugin, see that variable for
     more information.

   *
     '--mysqlx-ssl-crlpath[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl-crlpath=directory_name'

     *System Variable*                    'mysqlx_ssl_crlpath'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               directory name

     The equivalent of 'ssl_crlpath' for X Plugin, see that variable for
     more information.

   *
     '--mysqlx-ssl-key[=VALUE]'

     Property                             Value

     *Command-Line Format*                '--mysqlx-ssl-key=file-name'

     *System Variable*                    'mysqlx_ssl_key'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               file name

     The equivalent of 'ssl_key' for X Plugin, see that variable for
     more information.

When X Plugin is running the following system variables are available.

   *
     'mysqlx_bind_address'

     Property                             Value

     *Command-Line Format*                '--mysqlx-bind-address=value'

     *System Variable*                    'mysqlx_bind_address'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      '*'

     The network address which X Plugin uses for connections.  The
     equivalent of 'bind_address' for X Plugin, see that variable for
     more information.  This variable is not dynamic and can only be
     configured at start up.

   *
     'mysqlx_connect_timeout'

     Property                             Value

     *Command-Line Format*                '--mysqlx-connect-timeout=value'

     *System Variable*                    'mysqlx_connect_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '30'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1000000000'

     Number of seconds X Plugin waits for the first packet to be
     received from newly connected clients.  The equivalent of
     'connect_timeout' for X Plugin.

   *
     'mysqlx_idle_worker_thread_timeout'

     Property                             Value

     *Command-Line Format*                '--mysqlx-idle-worker-thread-timeout=value'

     *System Variable*                    'mysqlx_idle_worker_thread_timeout'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '60'

     *Minimum Value*                      '0'

     *Maximum Value*                      '3600'

     Number of seconds after which an idle worker thread is terminated.

   * 'mysqlx_max_allowed_packet'

     Property                             Value

     *Command-Line Format*                '--mysqlx-max-allowed-packet=value'

     *Introduced*                         5.7.12

     *System Variable*                    'mysqlx_max_allowed_packet'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '1048576'

     *Minimum Value*                      '512'

     *Maximum Value*                      '1073741824'

     Maximum size of a network packet that can be received by X Plugin.
     The X Plugin equivalent of 'max_allowed_packet'.

   * 'mysqlx_min_worker_threads'

     Property                             Value

     *Command-Line Format*                '--mysqlx-min-worker-threads=value'

     *System Variable*                    'mysqlx_min_worker_threads'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '2'

     *Minimum Value*                      '1'

     *Maximum Value*                      '100'

     Minimum number of worker threads the X Plugin uses for handling
     client requests.

   * 'mysqlx_max_connections'

     Property                             Value

     *Command-Line Format*                '--mysqlx-max-connections=value'

     *System Variable*                    'mysqlx_max_connections'

     *Scope*                              Global

     *Dynamic*                            Yes

     *Type*                               integer

     *Default Value*                      '100'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     Maximum number of concurrent client connections X Plugin can
     accept.  The X Plugin equivalent of 'max_connections'.

   * 'mysqlx_port'

     Property                             Value

     *Command-Line Format*                '--mysqlx-port=value'

     *Introduced*                         5.7.12

     *System Variable*                    'mysqlx_port'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '33060'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     The network port which X Plugin uses for connections.  The X Plugin
     equivalent of 'port'.

   * 'mysqlx_port_open_timeout'

     Property                             Value

     *Command-Line Format*                '--mysqlx-port-open-timeout=value'

     *Introduced*                         5.7.12

     *System Variable*                    'mysqlx_port_open_timeout'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '100'

     The amount of time in seconds which X Plugin waits for a TCP/IP
     port to become free.

   * 'mysqlx_socket'

     Property                             Value

     *Command-Line Format*                '--mysqlx-socket=file_name'

     *Introduced*                         5.7.15

     *System Variable*                    'mysqlx_socket'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               string

     *Default Value*                      '/tmp/mysqlx.sock'

     The socket where X Plugin listens for connections.

19.7.3 Monitoring X Plugin
--------------------------

This section describes how to monitor X Plugin.  There are two available
methods of monitoring, using Performance Schema tables or status
variables.

19.7.3.1 Status Variables for X Plugin
......................................

The status variables have the following meanings.

   * 'Mysqlx_address'

     The network address which X Plugin is bound to.  If the bind has
     failed, or if the 'skip_networking' option has been used, the value
     shows 'UNDEFINED'.

   * 'Mysqlx_bytes_sent'

     The number of bytes sent through the network.

   * 'Mysqlx_bytes_received'

     The number of bytes received through the network.

   * 'Mysqlx_stmt_execute_sql'

     The number of StmtExecute requests received for the SQL namespace.

   * 'Mysqlx_stmt_execute_xplugin'

     The number of StmtExecute requests received for the X Plugin
     namespace.

   * 'Mysqlx_stmt_create_collection'

     The number of create collection statements received.

   * 'Mysqlx_stmt_create_collection_index'

     The number of create collection index statements received.

   * 'Mysqlx_stmt_drop_collection'

     The number of drop collection statements received.

   * 'Mysqlx_stmt_drop_collection_index'

     The number of drop collection index statements received.

   * 'Mysqlx_stmt_ensure_collection'

     The number of ensure collection statements received.

   * 'Mysqlx_stmt_execute_mysqlx'

     The number of StmtExecute messages received with namespace set to
     'mysqlx'.

   * 'Mysqlx_stmt_list_objects'

     The number of list object statements received.

   * 'Mysqlx_stmt_enable_notices'

     The number of enable notice statements received.

   * 'Mysqlx_stmt_disable_notices'

     The number of disable notice statements received.

   * 'Mysqlx_stmt_list_notices'

     The number of list notice statements received.

   * 'Mysqlx_stmt_list_clients'

     The number of list client statements received.

   * 'Mysqlx_stmt_kill_client'

     The number of kill client statements received.

   * 'Mysqlx_stmt_ping'

     The number of ping statements received.

   * 'Mysqlx_crud_insert'

     The number of insert requests received.

   * 'Mysqlx_crud_update'

     The number of update requests received.

   * 'Mysqlx_crud_create_view'

     The number of create view requests received.

   * 'Mysqlx_crud_drop_view'

     The number of drop view requests received.

   * 'Mysqlx_crud_modify_view'

     The number of modify view requests received.

   * 'Mysqlx_crud_delete'

     The number of delete requests received.

   * 'Mysqlx_crud_find'

     The number of find requests received.

   * 'Mysqlx_expect_open'

     The number of expectation blocks opened.

   * 'Mysqlx_expect_close'

     The number of expectation blocks closed.

   * 'Mysqlx_rows_sent'

     The number of rows sent back to clients.

   * 'Mysqlx_notice_warning_sent'

     The number of warning notices sent back to clients.

   * 'Mysqlx_notice_other_sent'

     The number of other types of notices sent back to clients.

   * 'Mysqlx_port'

     The TCP port which X Plugin is listening to.  If a network bind has
     failed, or if the '--skip-networking' option has been used, the
     value shows 'UNDEFINED'.

   * 'Mysqlx_socket'

     The Unix socket which X Plugin is listening to.

   * 'Mysqlx_ssl_cipher'

     The current SSL cipher (empty for non-SSL connections).

   * 'Mysqlx_ssl_cipher_list'

     A list of possible SSL ciphers (empty for non-SSL connections).

   * 'Mysqlx_ssl_verify_depth'

     The certificate verification depth for SSL connections.

   * 'Mysqlx_ssl_verify_mode'

     The certificate verification mode for SSL connections.

   * 'Mysqlx_ssl_version'

     The name of the protocol used for SSL connections.

   * 'Mysqlx_sessions'

     The number of sessions that have been opened.

   * 'Mysqlx_sessions_closed'

     The number of sessions that have been closed.

   * 'Mysqlx_sessions_fatal_error'

     The number of sessions that have closed with a fatal error.

   * 'Mysqlx_init_error'

     The number of errors during initialisation.

   * 'Mysqlx_sessions_accepted'

     The number of session attempts which have been accepted.

   * 'Mysqlx_sessions_rejected'

     The number of session attempts which have been rejected.

   * 'Mysqlx_sessions_killed'

     The number of sessions which have been killed.

   * 'Mysqlx_connections_closed'

     The number of connections which have been closed.

   * 'Mysqlx_connections_accepted'

     The number of connections which have been accepted.

   * 'Mysqlx_connections_rejected'

     The number of connections which have been rejected.

   * 'Mysqlx_connection_accept_errors'

     The number of connections which have caused accept errors.

   * 'Mysqlx_connection_errors'

     The number of connections which have caused errors.

   * 'Mysqlx_worker_threads'

     The number of worker threads available.

   * 'Mysqlx_worker_threads_active'

     The number of worker threads currently used.

   * 'Mysqlx_ssl_active'

     If SSL is active.

   * 'Mysqlx_ssl_ctx_verify_depth'

     The certificate verification depth limit currently set in ctx.

   * 'Mysqlx_ssl_ctx_verify_mode'

     The certificate verification mode currently set in ctx.

   * 'Mysqlx_ssl_finished_accepts'

     The number of successful SSL connections to the server.

   * 'Mysqlx_ssl_accepts'

     The number of accepted SSL connections.

   * 'Mysqlx_ssl_server_not_after'

     The last date for which the SSL certificate is valid.

   * 'Mysqlx_ssl_server_not_before'

     The first date for which the SSL certificate is valid.

   * 'Mysqlx_ssl_accept_renegotiates'

     The number of negotiations needed to establish the connection.

   * 'Mysqlx_errors_sent'

     The number of errors sent to clients.

20 InnoDB Cluster
*****************

This chapter covers MySQL InnoDB cluster, which combines MySQL
technologies to enable you to create highly available clusters of MySQL
server instances.

20.1 Introducing InnoDB Cluster
===============================

MySQL InnoDB cluster provides a complete high availability solution for
MySQL. MySQL Shell includes AdminAPI which enables
you to easily configure and administer a group of at least three MySQL
server instances to function as an InnoDB cluster.  Each MySQL server
instance runs MySQL Group Replication, which provides the mechanism to
replicate data within InnoDB clusters, with built-in failover.  AdminAPI
removes the need to work directly with Group Replication in InnoDB
clusters, but for more information see group-replication which
explains the details.  MySQL Router
(http://dev.mysql.com/doc/mysql-router/2.1/en/) can automatically
configure itself based on the cluster you deploy, connecting client
applications transparently to the server instances.  In the event of an
unexpected failure of a server instance the cluster reconfigures
automatically.  In the default single-primary mode, an InnoDB cluster
has a single read-write server instance - the primary.  Multiple
secondary server instances are replicas of the primary.  If the primary
fails, a secondary is automatically promoted to the role of primary.
MySQL Router detects this and forwards client applications to the new
primary.  Advanced users can also configure a cluster to have
multiple-primaries.

*Important*:

InnoDB cluster does not provide support for MySQL NDB Cluster.  NDB
Cluster depends on the 'NDB' storage engine as
well as a number of programs specific to NDB Cluster which are not
furnished with MySQL Server 5.7; 'NDB' is available only as part of the
MySQL NDB Cluster distribution.  In addition, the MySQL server binary
(see 'mysqld') that is supplied with MySQL Server 5.7 cannot
be used with NDB Cluster.  For more information about MySQL NDB Cluster,
see mysql-cluster.  See mysql-cluster-compared, provides
information about the differences between the 'InnoDB' and 'NDB' storage
engines.

The following diagram shows an overview of how these technologies work
together:

FIGURE GOES HERE: InnoDB cluster overview

*Using AdminAPI*

MySQL Shell includes the AdminAPI, which is accessed through the 'dba'
global variable and its associated methods.  The 'dba' variable's
methods enable you to deploy, configure, and administer InnoDB clusters.
For example, use the 'dba.createCluster()' method to create an InnoDB
cluster.

*Important*:

MySQL Shell enables you to connect to servers over a socket connection,
but AdminAPI requires TCP connections to a server instance.  Do not use
socket based connections with AdminAPI.

MySQL Shell provides online help for the AdminAPI. To list all available
'dba' commands, use the 'dba.help()' method.  For online help on a
specific method, use the general format 'object.help('methodname')'.
For example:

     mysql-js> dba.help('getCluster')

     Retrieves a cluster from the Metadata Store.

     SYNTAX
       <Dba>.getCluster([name])

     WHERE
       name: Parameter to specify the name of the cluster to be returned.

     DESCRIPTION

     If name is not specified, the default cluster will be returned.

     If name is specified, and no cluster with the indicated name is found, an error
     will be raised.

20.2 Creating an InnoDB Cluster
===============================

This section explains the different ways you can create an InnoDB
cluster, the requirements for server instances and the software you need
to install to deploy a cluster.

20.2.1 Deployment Scenarios
---------------------------

InnoDB cluster supports the following deployment scenarios:

   * _Sandbox deployment:_ if you want to test out InnoDB cluster before
     committing to a full production deployment, the provided sandbox
     feature enables you to quickly set up a cluster on your local
     machine.  Sandbox server instances are created with the required
     configuration and you can experiment with InnoDB cluster to become
     familiar with the technologies employed.  See
     mysql-innodb-cluster-sandbox-deployment for instructions.

   * _Production deployment:_ if you want to use InnoDB cluster in a
     full production environment you need to configure the required
     number of machines and then deploy your server instances to the
     machines.  A production deployment enables you to exploit the high
     availability features of InnoDB cluster to their full potential.
     See mysql-innodb-cluster-production-deployment for
     instructions.

*Important*:

A sandbox deployment is not suitable for use in a full production
environment.

20.2.2 InnoDB Cluster Requirements
----------------------------------

Before installing a production deployment of InnoDB cluster, ensure that
the server instances you intend to use meet the following requirements.

   * InnoDB cluster uses Group Replication and therefore your server
     instances must meet the same requirements.  See
     group-replication-requirements.  AdminAPI provides the
     'dba.checkInstanceConfiguration()' method to verify that an
     instance meets the Group Replication requirements, and the
     'dba.configureLocalInstance()' method to configure an instance to
     meet the requirements.

     *Note*:

     When using a sandbox deployment the instances are configured to
     meet these requirements automatically.

   * The provisioning scripts that MySQL Shell uses to configure servers
     for use in InnoDB cluster require access to Python version 2.7.
     For a sandbox deployment Python is required on the single machine
     used for the deployment, production deployments require Python on
     each server instance.

     On Windows MySQL Shell includes Python and no user configuration is
     required.  On Unix Python must be found as part of the shell
     environment.  To check that your system has Python configured
     correctly issue:

          $ /usr/bin/env python

     If a Python interpreter starts, no further action is required.  If
     the previous command fails, create a soft link between
     '/usr/bin/python' and your chosen Python binary.

20.2.3 Methods of Installing
----------------------------

The method you use to install InnoDB cluster depends on the type of
deployment you intend to use.  For a sandbox deployment install the
components of InnoDB cluster to a single machine.  A sandbox deployment
is local to a single machine, therefore the install needs to only be
done once on the local machine.  Similarly there is no need to connect
to the instances individually for configuration, the sandbox instances
are local.  For a production deployment install the components to each
machine that you intend to add to your cluster.  A production deployment
uses multiple remote host machines running MySQL server instances, so
you need to connect to each machine using a tool such as SSH or Windows
remote desktop to carry out tasks such as installing components and
configuring the server instance.  The following methods of installing
InnoDB cluster are available:

   * Downloading and installing the components using the following
     documentation:

        * MySQL Server - see installing.

        * MySQL Shell - see document-store-shell-install.

        * MySQL Router - see Installing MySQL Router
          (http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-installation.html).

   * On Windows you can use the MySQL Installer for Windows for a
     sandbox deployment.  For details, see
     mysql-installer-workflow-innodb-cluster.

Once you have installed the software required by InnoDB cluster choose
to follow either mysql-innodb-cluster-sandbox-deployment or
mysql-innodb-cluster-production-deployment.

20.2.4 Sandbox Deployment of InnoDB Cluster
-------------------------------------------

This section explains how to set up a sandbox InnoDB cluster deployment.
You create and administer your InnoDB clusters using MySQL Shell with
the included AdminAPI. This section assumes familiarity with MySQL
Shell, see mysql-shell for further information.

Initially deploying and using local sandbox instances of MySQL is a good
way to start your exploration of InnoDB cluster.  You can fully test out
InnoDB cluster locally, prior to deployment on your production servers.
MySQL Shell has built-in functionality for creating sandbox instances
that are correctly configured to work with Group Replication in a
locally deployed scenario.

*Important*:

Sandbox instances are only suitable for deploying and running on your
local machine for testing purposes.  In a production environment the
MySQL Server instances are deployed to various host machines on the
network.  See mysql-innodb-cluster-production-deployment for
more information.

This tutorial shows how to use MySQL Shell to create an InnoDB cluster
consisting of three MySQL server instances.

   * deploy-sandbox-instances

   * create-innodb-cluster

   * add-instances-innodb-cluster

   * persist-configuration-innodb-cluster

*Deploying Sandbox Instances*

MySQL Shell includes the AdminAPI that adds the 'dba' global variable,
which provides functions for administration of sandbox instances.  In
this example setup, you create three sandbox instances using
'dba.deploySandboxInstance()'.

Start MySQL Shell from a command prompt by issuing the command:

     shell> mysqlsh

MySQL Shell provides two scripting language modes, JavaScript and
Python, in addition to a native SQL mode.  Throughout this guide MySQL
Shell is used primarily in JavaScript mode

.  When MySQL Shell starts it is in JavaScript mode by default.  Switch
modes by issuing '\js' for JavaScript mode, '\py' for Python mode, and
'\sql' for SQL mode.  Ensure you are in JavaScript mode by issuing the
'\js' command, then execute:

     mysql-js> dba.deploySandboxInstance(3310)

*Note*:

Terminating commands with a semi-colon is not required in JavaScript and
Python modes.

The argument passed to 'deploySandboxInstance()' is the TCP port number
where the MySQL Server instance listens for connections.  By default the
sandbox is created in a directory named '$HOME/mysql-sandboxes/PORT' on
Unix systems.  For Microsoft Windows systems the directory is
'%userprofile%\MySQL\mysql-sandboxes\PORT'.

The root password for the instance is prompted for.

*Important*:

Each instance has its own password.  Defining the same password for all
sandboxes in this tutorial makes it easier, but remember to use
different passwords for each instance in production deployments.

To deploy further sandbox server instances, repeat the steps followed
for the sandbox instance at port 3310, choosing different port numbers.
For each additional sandbox instance issue:

     mysql-js> dba.deploySandboxInstance(PORT_NUMBER)

To follow this tutorial, use port numbers 3310, 3320 and 3330 for the
three sandbox server instances.  Issue:

     mysql-js> dba.deploySandboxInstance(3320)
     mysql-js> dba.deploySandboxInstance(3330)

*Creating the Sandbox InnoDB Cluster*

The next step is to create the InnoDB cluster while connected to the
seed MySQL Server instance.  The seed instance contains the data that
you want to replicate to the other instances.  In this example the
sandbox instances are blank, therefore we can choose any instance.

Connect MySQL Shell to the seed instance, in this case the one at port
3310:

     mysql-js> \connect root@localhost:3310

The '\connect' MySQL Shell command is a shortcut for the
'shell.connect()' method:

     mysql-js> shell.connect('root@localhost:3310')

Once you have connected, AdminAPI can write to the local instance's
option file.  This is different to working with a production deployment,
where you would need to connect to the remote instance and run the MySQL
Shell application locally on the instance before AdminAPI can write to
the instance's option file.

Use the 'dba.createCluster()' method to create the InnoDB cluster with
the currently connected instance as the seed:

     mysql-js> var cluster = dba.createCluster('testCluster')

The 'createCluster()' method deploys the InnoDB cluster metadata to the
selected instance, and adds the instance you are currently connected to
as the seed instance.  The 'createCluster()' method returns the created
cluster, in the example above this is assigned to the 'cluster'
variable.  The parameter passed to the 'createCluster()' method is a
symbolic name given to this InnoDB cluster, in this case 'testCluster'.

*Tip*:

If the instance has 'super_read_only=ON' then you might need to confirm
that AdminAPI can set 'super_read_only=OFF'.  See
super-read-only-on-instance for more information.

*Adding Instances to an InnoDB Cluster*

The next step is to add more instances to the InnoDB cluster.  Any
transactions that were executed by the seed instance are re-executed by
each secondary instance as it is added.  This tutorial uses the sandbox
instances that were created earlier at ports 3320 and 3330.

The seed instance in this example was recently created, so it is nearly
empty.  Therefore, there is little data that needs to be replicated from
the seed instance to the secondary instances.  In a production
environment, where you have an existing database on the seed instance,
you could use a tool such as MySQL Enterprise Backup to ensure that the
secondaries have matching data before replication starts.  This avoids
the possibility of lengthy delays while data replicates from the primary
to the secondaries.  See group-replication-enterprise-backup.

Add the second instance to the InnoDB cluster:

     mysql-js> cluster.addInstance('root@localhost:3320')

The root user's password is prompted for.

Add the third instance:

     mysql-js> cluster.addInstance('root@localhost:3330')

The root user's password is prompted for.

At this point you have created a cluster with three instances: a
primary, and two secondaries.

*Tip*:

You can only specify 'localhost' in 'addInstance()' if the instance is a
sandbox instance.  This also applies to the implicit 'addInstance()'
after issuing 'createCluster()'.

*Persisting the Configuration*

Once the sandbox instances have been added to the cluster, the
configuration required for InnoDB cluster must be persisted to each of
the instance's option files.  Connect to each instance.

     mysql-js> \connect INSTANCE

Issue 'dba.configureLocalInstance(INSTANCE)'.

     mysql-js> dba.configureLocalInstance('INSTANCE')

You are prompted for the instance's password.  The configuration changes
are persisted to the instance.

*Important*:

If 'dba.configureLocalInstance()' is not issued when connected to the
instance, the configuration is not persisted to the option file.  This
does not stop the instance from initially joining a cluster, but it does
mean that the instance cannot rejoin the cluster automatically, for
example after being stopped.

Repeat the process of connecting to each sandbox instance you added to
the cluster and persisting the configuration.  For this example we added
sandbox instances at ports 3310, 3320 and 3330.  Therefore issue this
for ports 3320 and 3330:

     mysql-js> \connect root@localhost:PORT_NUMBER)
     mysql-js> dba.configureLocalInstance('root@localhost:PORT_NUMBER)

To check the cluster has been created, use the cluster instance's
'status()' function.  See check-innodb-cluster-status.

Once you have your cluster deployed you can configure MySQL Router to
provide high availability, see
mysql-innodb-cluster-using-router.

20.2.5 Production Deployment of InnoDB Cluster
----------------------------------------------

When working in a production environment, the MySQL server instances
which make up an InnoDB cluster run on multiple host machines as part of
a network

rather than on single machine as described in
mysql-innodb-cluster-sandbox-deployment.  Before proceeding with these
instructions you must install the required software to each machine that
you intend to add as a server instance to your cluster, see
mysql-innodb-cluster-methods-installing.

The following diagram illustrates the scenario you work with in this
section:

FIGURE GOES HERE: Production Deployment

*Important*:

Unlike a sandbox deployment, where all instances are deployed locally to
one machine, for a production deployment you must connect to each
machine and run MySQL Shell locally before issuing
'dba.configureLocalInstance()' on the instance.  This ensures that any
configuration changes are persisted into the option file on the
instance.  This also requires that you have access to the server and the
required permissions to execute MySQL Shell.

To pass a server's connection information to AdminAPI use URI type
strings.  See mysql-shell-connection-using-uri for more
information.

*User Privileges*

The user account used to administer an instance does not have to be the
root account, however the user needs to be assigned full read and write
privileges on the InnoDB cluster metadata tables in addition to full
MySQL administrator privileges ('SUPER', 'GRANT OPTION', 'CREATE',
'DROP' and so on).  To give the user YOUR_USER the privileges needed to
administer InnoDB cluster issue:

     GRANT ALL PRIVILEGES ON mysql_innodb_cluster_metadata.* TO your_user@'%' WITH GRANT OPTION;
     GRANT RELOAD, SHUTDOWN, PROCESS, FILE, SUPER, REPLICATION SLAVE, REPLICATION CLIENT, \
     CREATE USER ON *.* TO your_user@'%' WITH GRANT OPTION;
     GRANT SELECT ON *.* TO your_user@'%' WITH GRANT OPTION;

If only read operations are needed (such as for monitoring purposes), an
account with more restricted privileges can be used.  To give the user
YOUR_USER the privileges needed to monitor InnoDB cluster issue:

     GRANT SELECT ON mysql_innodb_cluster_metadata.* TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.global_status TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_applier_configuration TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_applier_status TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_applier_status_by_coordinator TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_applier_status_by_worker TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_connection_configuration TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_connection_status TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_group_member_stats TO YOUR_USER@'%';
     GRANT SELECT ON performance_schema.replication_group_members TO YOUR_USER@'%';

In this procedure the user 'ic' is used in examples.

*Configuring Hostname*

The production instances which make up a cluster run on separate
machines, therefore each machine must have a unique host name and be
able to resolve the host names of the other machines which run server
instances in the cluster.  If this is not the case, you can:

   * configure each machine to map the IP of each other machine to a
     hostname.  See your operating system documentation for details.
     This is the recommended solution.

   * set up a DNS service

   * configure the 'report_host' variable in the MySQL configuration of
     each instance

In this procedure the host name 'ic-NUMBER' is used in examples.

*Verbose Logging*

When working with a production deployment it can be useful to configure
verbose logging for MySQL Shell, the information in the log can help you
to find and resolve any issues that might occur when you are preparing
server instances to work as part of InnoDB cluster.  To start MySQL
Shell with a verbose logging level use the '--log-level' option:

     shell> mysqlsh --log-level=DEBUG3

The 'DEBUG3' is recommended, see '--log-level' for more information.
When 'DEBUG3' is set the MySQL Shell log file contains lines such as
'Debug: execute_sql( ... )' which contain the SQL queries that are
executed as part of each AdminAPI call.  The log file generated by MySQL
Shell is located in '~/.mysqlsh/mysqlsh.log' for Unix-based systems; on
Microsoft Windows systems it is located in
'%APPDATA%\MySQL\mysqlsh\mysqlsh.log'.  See
mysql-shell-application-log for more information.

In addition to enabling the MySQL Shell log level, you can configure the
amount of output AdminAPI provides in MySQL Shell after each call to the
API. To enable the amount of AdminAPI output, in MySQL Shell issue:

     mysql-js> dba.verbose=2

This enables the maximum output from AdminAPI calls.  The available
levels of output are:

   * 0 or OFF is the default.  This provides minimal output and is the
     recommended level when not troubleshooting.

   * 1 or ON adds verbose output from each call to the AdminAPI.

   * 2 adds debug output to the verbose output providing full
     information about what each call to AdminAPI executes.

*Checking Instance Configuration*

Before creating a production deployment from server instances you need
to check that MySQL on each instance is correctly configured by using
the 'dba.checkInstanceConfiguration()' function.  This ensures that the
instance satisfies the mysql-innodb-cluster-requirements.  This
does not check any data that is on the instance, see
check-instance-state for more information.  The following demonstrates
issuing this in a running MySQL Shell:

     mysql-js> dba.checkInstanceConfiguration('ic@ic-1:3306')

     Please provide the password for 'ic@ic-1:3306':
     Validating instance...

     The instance 'ic-1:3306' is not valid for Cluster usage.

     The following issues were encountered:

     - Some configuration options need to be fixed.

     +----------------------------------+---------------+----------------+--------------------------------------------------+
     | Variable                         | Current Value | Required Value | Note                                             |
     +----------------------------------+---------------+----------------+--------------------------------------------------+
     | binlog_checksum                  | CRC32         | NONE           | Update the server variable or restart the server |
     | enforce_gtid_consistency         | OFF           | ON             | Restart the server                               |
     | gtid_mode                        | OFF           | ON             | Restart the server                               |
     | log_bin                          | 0             | 1              | Restart the server                               |
     | log_slave_updates                | 0             | ON             | Restart the server                               |
     | master_info_repository           | FILE          | TABLE          | Restart the server                               |
     | relay_log_info_repository        | FILE          | TABLE          | Restart the server                               |
     | transaction_write_set_extraction | OFF           | XXHASH64       | Restart the server                               |
     +----------------------------------+---------------+----------------+--------------------------------------------------+

     Please fix these issues , restart the server and try again.

     {
       "config_errors": [
         {
           "action": "server_update",
           "current": "CRC32",
           "option": "binlog_checksum",
           "required": "NONE"
         },
         {
           "action": "restart",
           "current": "OFF",
           "option": "enforce_gtid_consistency",
           "required": "ON"
         },
         {
           "action": "restart",
           "current": "OFF",
           "option": "gtid_mode",
           "required": "ON"
         },
         {
           "action": "restart",
           "current": "0",
           "option": "log_bin",
           "required": "1"
         },
         {
           "action": "restart",
           "current": "0",
           "option": "log_slave_updates",
           "required": "ON"
         },
         {
           "action": "restart",
           "current": "FILE",
           "option": "master_info_repository",
           "required": "TABLE"
         },
         {
           "action": "restart",
           "current": "FILE",
           "option": "relay_log_info_repository",
           "required": "TABLE"
         },
         {
           "action": "restart",
           "current": "OFF",
           "option": "transaction_write_set_extraction",
           "required": "XXHASH64"
         }
       ],
       "errors": [],
       "restart_required": true,
       "status": "error"
     }
     mysql-js>

Repeat this process for each server instance that you plan to use as
part of your cluster.  The reports generated after running
'dba.checkInstanceConfiguration()' provide information about any
configuration changes required before you can proceed.  The
'restart_required' field in the final part of the report tells you
whether MySQL on the instance requires a restart to detect any change
made to the configuration file.

*Configuring the Instance*

If configuration issues have been identified in the report generated by
running 'dba.checkInstanceConfiguration()' against the instance, it does
not satisfy the mysql-innodb-cluster-requirements.  Therefore
you need to connect to the machine and reconfigure the server instance.
AdminAPI provides the 'dba.configureLocalInstance()' function that finds
the MySQL server's option file and modifies it to ensure that the
instance is correctly configured for InnoDB cluster.  Alternatively make
the changes to the instance's option file manually based on the
information in the report.  See option-files for more
information.  Regardless of the way you make the configuration changes,
you might have to restart MySQL to ensure the configuration changes are
detected.

The recommended method is to log in to the remote machine, run MySQL
Shell as the root user and then connect to the local MySQL server:

     shell> sudo -i mysqlsh --log-level=DEBUG3

The 'dba.configureLocalInstance()' method verifies that a suitable user
is available for cluster usage, which is used for connections between
members of the cluster.

The root user cannot do remote logins by default, therefore you have
three options to continue with the configuration: enable remote
connections for the root user

, create a new user or neither of these two previous options.  The
following example demonstrates the second option, creating a new user
for cluster usage.

The format of the user names accepted follows the standard MySQL account
name format, see account-names.

     mysql-js> dba.configureLocalInstance('root@localhost:3306')

     Please provide the password for 'root@localhost:3306':

     Please specify the path to the MySQL configuration file: /etc/mysql/mysql.conf.d/mysqld.cnf
     Validating instance...

     The configuration has been updated but it is required to restart the server.
     {
       "config_errors": [
         {
           "action": "restart",
           "current": "OFF",
           "option": "enforce_gtid_consistency",
           "required": "ON"
         },
         {
           "action": "restart",
           "current": "OFF",
           "option": "gtid_mode",
           "required": "ON"
           },
         {
           "action": "restart",
           "current": "0",
           "option": "log_bin",
           "required": "1"
         },
         {
           "action": "restart",
           "current": "0",
           "option": "log_slave_updates",
           "required": "ON"
         },
         {
           "action": "restart",
           "current": "FILE",
           "option": "master_info_repository",
           "required": "TABLE"
         },
         {
           "action": "restart",
           "current": "FILE",
           "option": "relay_log_info_repository",
           "required": "TABLE"
         },
         {
           "action": "restart",
           "current": "OFF",
           "option": "transaction_write_set_extraction",
           "required": "XXHASH64"
         }
       ],
       "errors": [],
       "restart_required": true,
       "status": "error"
     }
     mysql-js>

*Tip*:

If the instance has 'super_read_only=ON' then you might need to confirm
that AdminAPI can set 'super_read_only=OFF'.  See
super-read-only-on-instance for more information.

As with 'dba.checkInstanceConfiguration()', the configuration
requirements are identified, but this time the chosen configuration file
is modified.  For the configuration changes to take effect you might
need to restart the MySQL Server.

The 'dba.configureLocalInstance()' function also accepts the
'clusterAdmin' and 'clusterAdminPassword' options, which enable you to
configure the cluster user and password when calling the function.
'clusterAdmin' supports identifiers or strings for the user name and
host name.  By default if unquoted it assumes input is a string.  For
example:

     mysql-js> dba.configureLocalInstance('ic@ic-1:3306', \
	           {clusterAdmin: 'icadmin@ic-1%',clusterAdminPassword: 'secret'});

This user is granted the privileges for an administrative user described
at mysql-innodb-cluster-user-privileges.

*Creating the Cluster*

Once you have prepared your instances, use the 'dba.createCluster()'
function to create the cluster.  The machine which you are running MySQL
Shell on is used as the seed instance for the cluster.  The seed
instance is replicated to the other instances which you add to the
cluster, making them replicas of the seed instance.

Log in to the instance and run MySQL Shell locally.

     shell> mysqlsh --uri ic@ic-1:3306

     Creating a Session to 'ic@ic-1:3306'
     Enter password: *********
     Classic Session successfully established. No default schema selected.

MySQL Shell must be connected to an instance before you can create a
cluster because when you issue 'dba.createCluster(NAME)' MySQL Shell
creates a MySQL protocol session to the server instance connected to the
MySQL Shell's current global session.  Use the 'dba.createCluster(NAME)'
function to create the cluster and assign the returned cluster to a
variable called 'cluster':

     mysql-js> var cluster = dba.createCluster('prodCluster')

           A new InnoDB cluster will be created on instance 'ic@ic-1:3306'.

           Creating InnoDB cluster 'prodCluster' on 'ic@ic-1:3306'...
           Adding Seed Instance...

           Cluster successfully created. Use Cluster.addInstance() to add MySQL instances.
           At least 3 instances are needed for the cluster to be able to withstand up to
           one server failure.

*Tip*:

If the instance has 'super_read_only=ON' then you might need to confirm
that AdminAPI can set 'super_read_only=OFF'.  See
super-read-only-on-instance for more information.

*Note*:

If you encounter an error related to metadata being inaccessible you
might have the loopback network interface configured.  For correct
InnoDB cluster usage disable the loopback interface.

To check the cluster has been created, use the cluster instance's
'status()' function.  See check-innodb-cluster-status.

*Tip*:

Once server instances belong to a cluster it is important to only
administer them using MySQL Shell and AdminAPI. Attempting to manually
change the configuration of Group Replication on an instance once it has
been added to a cluster is not supported.  Similarly, modifying server
variables critical to InnoDB cluster, such as 'server_uuid' after an
instance is configured using AdminAPI is not supported.

Use the 'cluster.addInstance(INSTANCE)' function to add more instances
to the cluster, where INSTANCE is a URI type string to connect to the
local instance.  The instances must have been configured for cluster
usage.  You need a minimum of three instances in the cluster to make it
tolerant to the failure of one instance.  Adding further instances
increases the tolerance to failure of an instance.  To add an instance
to the cluster issue:

     mysql-js> cluster.addInstance('ic@ic-2:3306');

To verify the instance has been added, use the cluster instance's
'status()' function.

*Important*:

At this stage, the server instances have been added to the cluster but
the changes to the InnoDB cluster metadata have only been made on the
instance which you are currently connected to.  To make the
configuration changes persistent for all instances in the cluster, you
must connect to each instance and issue 'dba.configureLocalInstance()'
locally on each instance you have added.  This is essential to ensure
that instances rejoin the cluster in the event of leaving the cluster.

To persist the InnoDB cluster metadata for all instances, log in to each
instance that you added to the cluster and run MySQL Shell locally.

     shell> mysqlsh

Use the '\connect' command to log in to MySQL server.  Execute the
'dba.configureLocalInstance('INSTANCE')' function, where INSTANCE is a
URI type string to connect to the local instance.  For example:

     mysql-js> dba.configureLocalInstance('ic@ic-2:3306')

*Tip*:

If the instance has 'super_read_only=ON' then you might need to confirm
that AdminAPI can set 'super_read_only=OFF'.  See
super-read-only-on-instance for more information.

Repeat this process for each server instance that you added to the
cluster.  Similarly if you modify the cluster structure, for example
changing the number of instances, you need to repeat this process for
each server instance to update the InnoDB cluster metadata accordingly
for each instance in the cluster.

Once you have your cluster deployed you can configure MySQL Router to
provide high availability, see
mysql-innodb-cluster-using-router.

20.2.6 Adopting a Group Replication Deployment
----------------------------------------------

If you have an existing deployment of Group Replication and you want to
use it to create a cluster, pass the 'adoptFromGR' option to the
'dba.createCluster()' function.  The created InnoDB cluster matches
whether the replication group is running as single-primary or
multi-primary.

*Tip*:

Group Replication members might contain 'MyISAM'
tables.  Convert all such tables to
'InnoDB' before adopting the group to an InnoDB
cluster.

To adopt an existing Group Replication group, connect to a group member
using MySQL Shell.  In the following example a single-primary group is
adopted.  We connect to 'gr-member-2', a secondary instance, while
'gr-member-1' is functioning as the group's primary.  Create a cluster
using 'dba.createCluster()', passing in the 'adoptFromGR' option.  For
example:

     mysql-js> var cluster = dba.createCluster('prodCluster', {adoptFromGR: true});

     A new InnoDB cluster will be created on instance 'root@gr-member-2:3306'.

     Creating InnoDB cluster 'prodCluster' on 'root@gr-member-2:3306'...
     Adding Seed Instance...

     Cluster successfully created. Use cluster.addInstance() to add MySQL instances.
     At least 3 instances are needed for the cluster to be able to withstand up to
     one server failure.

*Tip*:

If the instance has 'super_read_only=ON' then you might need to confirm
that AdminAPI can set 'super_read_only=OFF'.  See
super-read-only-on-instance for more information.

The new cluster matches the mode of the group.  If the adopted group was
running in single-primary mode then a single-primary cluster is created.
If the adopted group was running in multi-primary mode then a
multi-primary cluster is created.  For example:

     mysql-js> cluster.status();

     {
         "clusterName": "prodCluster",
         "defaultReplicaSet": {
             "name": "default",
             "primary": "gr-member-1:3306",
             "ssl": "REQUIRED",
             "status": "OK",
             "statusText": "Cluster is ONLINE and can tolerate up to ONE failure.",
             "topology": {
                 "gr-member-2:3306": {
                     "address": "gr-member-2:3306",
                     "mode": "R/O",
                     "readReplicas": {},
                     "role": "HA",
                     "status": "ONLINE"
                 },
                 "gr-member-1:3306": {
                     "address": "gr-member-1:3306",
                     "mode": "R/W",
                     "readReplicas": {},
                     "role": "HA",
                     "status": "ONLINE"
                 },
                 "gr-member-3:3306": {
                     "address": "gr-member-3:3306",
                     "mode": "R/O",
                     "readReplicas": {},
                     "role": "HA",
                     "status": "ONLINE"
                 }
             }
         }
     }

As seen above, the newly created cluster is single-primary and uses
'gr-member-1' as the primary.

20.3 Using MySQL Router with InnoDB Cluster
===========================================

This section describes how to use MySQL Router with InnoDB cluster to
achieve high availability.  Regardless of whether you have deployed a
sandbox or production cluster, MySQL Router can configure itself based
on the InnoDB cluster's metadata using the '--bootstrap'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysqlrouter.html#option_mysqlrouter_bootstrap)
option.  This configures MySQL Router automatically to route connections
to the cluster's server instances.  Client applications connect to the
ports MySQL Router provides, without any need to be aware of the InnoDB
cluster topology.  In the event of a unexpected failure, the InnoDB
cluster adjusts itself automatically and MySQL Router detects the
change.  This removes the need for your client application to handle
failover.  For more information, see Routing for MySQL InnoDB cluster
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-innodb-cluster.html).

*Note*:

Do not attempt to configure MySQL Router manually to redirect to the
ports of an InnoDB cluster.  Always use the '--bootstrap'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysqlrouter.html#option_mysqlrouter_bootstrap)
option as this ensures that MySQL Router takes its configuration from
the InnoDB cluster's metadata.  See Cluster Metadata and State
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-general-metadata.html).

The recommended deployment of MySQL Router is on the same host as the
application.  When using a sandbox deployment, everything is running on
a single host, therefore you deploy MySQL Router to the same host.  When
using a production deployment, we recommend deploying one MySQL Router
instance to each machine used to host one of your client applications.
It is also possible to deploy MySQL Router to a common machine through
which your application instances connect.  You need the MASTER key of
the InnoDB cluster to auto-configure MySQL Router.

Assuming MySQL Router is already installed (see Installing MySQL Router
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-installation.html)),
use the '--bootstrap'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysqlrouter.html#option_mysqlrouter_bootstrap)
option to provide the location of a server instance that belongs to the
InnoDB cluster.  MySQL Router uses the included metadata cache

plugin to retrieve the InnoDB cluster's metadata, consisting of a list
of server instance addresses which make up the InnoDB cluster and their
role in the cluster.  You pass the URI type string of the server that
MySQL Router should retrieve the InnoDB cluster metadata from.  For
example:

     shell> mysqlrouter --bootstrap ic@ic-1:3306 --user=mysqlrouter

You are prompted for the instance password and encryption key for MySQL
Router to use.  This encryption key is used to encrypt the instance
password used by MySQL Router to connect to the cluster.  The ports you
can use to connect to the InnoDB cluster are also displayed.  The MySQL
Router bootstrap process creates a 'mysqlrouter.conf' file, with the
settings based on the cluster metadata retrieved from the address passed
to the '--bootstrap'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysqlrouter.html#option_mysqlrouter_bootstrap)
option, in the above example 'ic@ic-1:3306'.  Based on the InnoDB
cluster metadata retrieved, MySQL Router automatically creates a
configuration file, including a 'metadata_cache' section with
'bootstrap_server_addresses'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-conf-options.html#option_mysqlrouter_bootstrap_server_addresses)
containing the addresses for all server instances in the cluster.  For
example:

     [metadata_cache:prodCluster]
     router_id=1
     bootstrap_server_addresses=mysql://ic@ic-1:3306,mysql://ic@ic-2:3306,mysql://ic@ic-3:3306
     user=mysql_router1_jy95yozko3k2
     metadata_cluster=prodCluster
     ttl=300

*Tip*:

When you change the topology of a cluster by adding another server
instance after you have bootstrapped MySQL Router, you need to update
'bootstrap_server_addresses'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-conf-options.html#option_mysqlrouter_bootstrap_server_addresses)
based on the updated metadata.  Either restart MySQL Router using the
'--bootstrap'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysqlrouter.html#option_mysqlrouter_bootstrap)
option, or manually edit the 'bootstrap_server_addresses'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-conf-options.html#option_mysqlrouter_bootstrap_server_addresses)
section of the 'mysqlrouter.conf' file and restart MySQL Router.

The generated MySQL Router configuration creates TCP ports which you use
to connect to the cluster.  Ports for communicating with the cluster
using both Classic MySQL protocol and X Protocol are created.  To use X
Protocol the server instances must have X Plugin installed and
configured.  For a sandbox deployment, instances have X Plugin set up
automatically.  For a production deployment, if you want to use X
Protocol you need to install and configure X Plugin on each instance,
see document-store-setting-up.  The default available TCP ports
are:

   * '6446' - for Classic MySQL protocol read-write sessions, which
     MySQL Router redirects incoming connections to primary server
     instances.

   * '6447' - for Classic MySQL protocol read-only sessions, which MySQL
     Router redirects incoming connections to one of the secondary
     server instances.

   * '64460' - for X Protocol read-write sessions, which MySQL Router
     redirects incoming connections to primary server instances.

   * '64470' - for X Protocol read-only sessions, which MySQL Router
     redirects incoming connections to one of the secondary server
     instances.

Depending on your MySQL Router configuration the port numbers might be
different to the above.  For example if you use the '--conf-base-port'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysqlrouter.html#option_mysqlrouter_conf-base-port)
option, or the 'group_replication_single_primary_mode' variable.  The
exact ports are listed when you start MySQL Router.

The way incoming connections are redirected depends on the type of
cluster being used.  When using a single-primary cluster, read-write
sessions are redirected to the single primary, with a multi-primary
cluster read-write sessions are redirected to one of the primary
instances.

For incoming read-only connections MySQL Router redirects connections to
one of the secondary instances in a round-robin fashion.

Once bootstrapped and configured, start MySQL Router:

     shell> mysqlrouter &

Alternatively set up a service to start MySQL Router automatically when
the system boots, see Starting MySQL Router
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysql-router-server-starting.html).
You can now connect a MySQL client, such as MySQL Shell to one of the
incoming MySQL Router ports as described above and see how the client
gets transparently connected to one of the InnoDB cluster instances.

     shell> mysqlsh --uri root@localhost:6442

To verify which instance you are actually connected to, simply issue an
SQL query against the 'port' status variable.

     mysql-js> \sql
     Switching to SQL mode... Commands end with ;
     mysql-sql> select @@port;
     +--------+
     | @@port |
     +--------+
     |   3310 |
     +--------+

*Testing High Availability*

To test if high availability works, simulate an unexpected halt by
killing an instance.  The cluster detects the fact that the instance
left the cluster and reconfigures itself.  Exactly how the cluster
reconfigures itself depends on whether you are using a single-primary or
multi-primary cluster, and the role the instance serves within the
cluster.

In single-primary mode:

   * If the current primary leaves the cluster, one of the secondary
     instances is elected as the new primary, with instances prioritized
     by the lowest 'server_uuid'.  MySQL Router redirects read-write
     connections to the newly elected primary.

   * If a current secondary leaves the cluster, MySQL Router stops
     redirecting read-only connections to the instance.

For more information see group-replication-single-primary-mode.

In multi-primary mode:

   * If a current "R/W" instance leaves the cluster, MySQL Router
     redirects read-write connections to other primaries.

   * If a current "R/O" instance leaves the cluster,

For more information see group-replication-multi-primary-mode.

There are various ways to simulate an instance leaving a cluster, for
example you can forcibly stop the MySQL server on an instance, or use
the AdminAPI 'dba.killSandboxInstance()' if testing a sandbox
deployment.  In this example assume there is a single-primary sandbox
cluster deployment with three server instances and the instance
listening at port 3310 is the current primary.  Simulate the instance
leaving the cluster unexpectedly:

     mysql-js> dba.killSandboxInstance(3310)

Switch to SQL mode in MySQL Shell using the '\sql' command and verify
the 'port' variable to check which instance you are connected to.

Notice that the first 'SELECT' statement fails as the
connection to the original primary was lost.  This means the current
session has been closed, MySQL Shell automatically reconnects for you
and when you issue the command again the new port is confirmed.

     mysql-js> \sql
     Switching to SQL mode... Commands end with ;
     mysql-sql> SELECT @@port;
     ERROR: 2013 (HY000): Lost connection to MySQL server during query
     The global session got disconnected.
     Attempting to reconnect to 'root@localhost:6446'...
     The global session was successfully reconnected.
     mysql-sql> SELECT @@port;
     +--------+
     | @@port |
     +--------+
     |   3330 |
     +--------+
     1 row in set (0.00 sec)

This shows that the InnoDB cluster provided us with automatic failover,
that MySQL Router has automatically reconnected us to the new primary
instance, and that we have high availability.

*MySQL Router and Metadata Servers*

When MySQL Router is bootstrapped against a cluster, it records the
server instance's addresses in its configuration file.  If any
additional instances are added to the cluster after bootstrapping the
MySQL Router, they are not automatically detected and therefore are
_not_ used for connection routing.

To ensure that newly added instances are routed to correctly you must
bootstrap MySQL Router against the cluster to read the updated metadata.
This means that you must restart MySQL Router and include the
'--bootstrap'
(http://dev.mysql.com/doc/mysql-router/2.1/en/mysqlrouter.html#option_mysqlrouter_bootstrap)
option.

20.4 Working with InnoDB Cluster
================================

This section explains how to work with InnoDB cluster, and how to handle
common administration tasks.

   * retrieving-an-innodb-cluster

   * check-innodb-cluster-status

   * describe-structure-innodb-cluster

   * super-read-only-on-instance

   * manage-sandbox-instances

   * remove-instances-from-innodb-cluster

   * customize-your-cluster

   * rejoin-cluster

   * restore-cluster-from-quorum-loss

   * reboot-outage

   * rescan-cluster

   * check-instance-state

   * dissolve-innodb-cluster

   * mysql-innodb-cluster-securing

   * create-whitelist-servers

   * use-mysql-shell-execute-script

*Retrieving an InnoDB cluster*

When you create a cluster using 'dba.createCluster()', the operation
returns a Cluster object which can be assigned to a variable.  You use
this object to work with the cluster, for example to add instances or
check the cluster's status.  If you want to retrieve a cluster again at
a later date, for example after restarting MySQL Shell, use the
'dba.getCluster(NAME, [OPTIONS])' function.  For example:

     mysql-js> var cluster1 = dba.getCluster()

If you do not specify a cluster NAME then the default cluster is
returned.  If there is more than one cluster stored in the InnoDB
cluster metadata of the server instance which the MySQL Shell global
session is currently connected to, specify the NAME of the cluster you
want to retrieve.

*Checking the InnoDB Cluster Status*

Cluster objects provide the 'status()' method that enables you to check
how a cluster is running.  Before you can check the status of the InnoDB
cluster, you need to get a reference to the InnoDB cluster object by
connecting to any of its instances.  However, if you want to make
changes to the configuration of the cluster, you must connect to a "R/W"
instance.  Issuing 'status()' retrieves the status of the cluster based
on the view of the cluster which the server instance you are connected
to is aware of and outputs a status report.

*Important*:

The instance's state in the cluster directly influences the information
provided in the status report.  An instance which has left the cluster
provides a different view of the cluster compared to a instance which
belongs to the cluster.  Therefore ensure the instance you are connected
to has a status of 'ONLINE'.

For information about how the InnoDB cluster is running, use the
cluster's 'status()' method:

     mysql-js> var cluster = dba.getCluster()
     mysql-js> cluster.status()
     {
         "clusterName": "testCluster",
         "defaultReplicaSet": {
             "name": "default",
             "primary": "localhost:3320",
     	"ssl": "REQUIRED",
             "status": "OK",
             "statusText": "Cluster is ONLINE and can tolerate up to ONE failure.",
             "topology": {
                 "localhost:3310": {
                     "address": "localhost:3310",
                     "mode": "R/O",
                     "readReplicas": {},
                     "role": "HA",
                     "status": "ONLINE"
                 },
                 "localhost:3320": {
                     "address": "localhost:3320",
                     "mode": "R/W",
                     "readReplicas": {},
                     "role": "HA",
                     "status": "ONLINE"
                 },
                 "localhost:3330": {
                     "address": "localhost:3330",
                     "mode": "R/O",
                     "readReplicas": {},
                     "role": "HA",
                     "status": "ONLINE"
                 }
             }
         }
     }

The information output by 'cluster.status()' provides the following
information:

   * clusterName: name assigned to this cluster during
     'dba.createCluster()'.

   * defaultReplicaSet: the server instances which belong to an InnoDB
     cluster and contain the data set.

   * primary: displayed when the cluster is operating in single-primary
     mode only.  Shows the address of the current primary instance.  If
     this field is not displayed, the cluster is operating in
     multi-primary mode.

   * ssl: whether secure connections are used by the cluster or not.
     Shows values of 'REQUIRED' or 'DISABLED', depending on how the
     'memberSslMode' option was configured during either
     'createCluster()' or 'addInstance()'.  The value returned by this
     parameter corresponds to the value of the
     'group_replication_ssl_mode' server variable on the instance.  See
     mysql-innodb-cluster-securing.

   * status: The status of this element of the cluster.  For the overall
     cluster this describes the high availability provided by this
     cluster.  The status is one of the following:

        * 'ONLINE': The instance is online and participating in the
          cluster.

        * 'OFFLINE': The instance has lost connection to the other
          instances.

        * 'RECOVERING': The instance is attempting to synchronize with
          the cluster by retrieving transactions it needs before it can
          become an 'ONLINE' member.

        * 'UNREACHABLE': The instance has lost communication with the
          cluster.

        * 'ERROR': The instance has encountered an error during the
          recovery phase or while applying a transaction.

          *Important*:

          Once an instance enters 'ERROR' state, the 'super_read_only'
          option is set to 'ON'.  To leave the 'ERROR' state you must
          manually configure the instance with 'super_read_only=OFF'.

        * '(MISSING)': The state of an instance which is part of the
          configured cluster, but is currently unavailable.

          *Note*:

          The 'MISSING' state is specific to InnoDB cluster, it is not a
          state generated by Group Replication.  MySQL Shell uses this
          state to indicate instances that are registered in the
          metadata, but cannot be found in the live cluster view.

   * topology: The instances which have been added to the cluster.

   * Host name of instance: The host name of an instance, for example
     localhost:3310.

   * role: what function this instance provides in the cluster.
     Currently only HA, for high availability.

   * mode: whether the server is read-write ("R/W") or read-only
     ("R/O"). The mode indicates either 'R/W' (read and writable) or
     'R/O' (read only).  In single-primary mode, only the one instance
     marked "R/W" can execute transactions that update the database, so
     it is the primary.  If that instance becomes unreachable for any
     reason (like an unexpected halt), one of the remaining "R/O"
     instances automatically takes over its place and becomes the new
     "R/W" primary.  In multi-primary mode, all instances are marked as
     "R/W" and there is no single elected primary.

*Describing the Structure of the InnoDB Cluster*

To get information about the structure of the InnoDB cluster itself, use
the 'cluster.describe()' function:

     mysql-js> cluster.describe();
     {
         "clusterName": "test",
         "adminType": "local",
         "defaultReplicaSet": {
             "name": "default",
             "instances": [
                 {
                     "name": "localhost:3310",
                     "host": "localhost:3310",
                     "role": "HA"
                 },
                 {
                     "name": "localhost:3320",
                     "host": "localhost:3320",
                     "role": "HA"
                 },
                 {
                     "name": "localhost:3330",
                     "host": "localhost:3330",
                     "role": "HA"
                 }
             ]
         }
     }

The output from this function shows the structure of the InnoDB cluster
including all of its configuration information, and so on.

*Super Read-only and Instances*

Whenever Group Replication stops, the 'super_read_only' variable is set
to 'ON' to ensure no writes are made to the instance.  When you try to
use such an instance with the following AdminAPI commands you are given
the choice to set 'super_read_only=OFF' on the instance:

   * 'dba.configureLocalInstance()'

   * 'dba.createCluster()'

   * 'dba.rebootClusterFromCompleteOutage()'

   * 'dba.dropMetadataSchema()'

When AdminAPI encounters an instance which has 'super_read_only=ON', in
interactive mode you are given the choice to set 'super_read_only=OFF'.
For example:

     mysql-js> var myCluster = dba.createCluster('testCluster')
     A new InnoDB cluster will be created on instance 'ic@ic-1:3306'.

     The MySQL instance at 'ic@ic-1:3306' currently has the super_read_only
     system variable set to protect it from inadvertent updates from applications.
     You must first unset it to be able to perform any changes to this instance.
     For more information see: https://dev.mysql.com/doc/refman/en/server-system-variables.html#sysvar_super_read_only.

     Note: there are open sessions to 'ic@ic-1:3306'.
     You may want to kill these sessions to prevent them from performing unexpected updates:

     1 open session(s) of 'ic@ic-1:3306'.

     Do you want to disable super_read_only and continue? [y|N]:

The number of current active sessions to the instance is shown.  You
must ensure that no applications might write to the instance
inadvertently.  By answering 'y' you confirm that AdminAPI can write to
the instance.  If there is more than one open session to the instance
listed, exercise caution before permitting AdminAPI to set
'super_read_only=OFF'.

To force the function to set 'super_read_only=OFF' in a script, pass the
'clearReadOnly' option set to 'true'.  For example
'dba.configureLocalInstance(instance, {clearReadOnly: true}).'

*Managing Sandbox Instances*

Once a sandbox instance is running, it is possible to change its status
at any time using the following:

   * To stop a sandbox instance use 'dba.stopSandboxInstance(INSTANCE)'.
     This stops the instance gracefully, unlike
     'dba.killSandboxInstance(INSTANCE)'.

   * To start a sandbox instance use
     'dba.startSandboxInstance(INSTANCE)'.

   * To kill a sandbox instance use 'dba.killSandboxInstance(INSTANCE)'.
     This stops the instance without gracefully stopping it and is
     useful in simulating unexpected halts.

   * To delete a sandbox instance use
     'dba.deleteSandboxInstance(INSTANCE)'.  This completely removes the
     sandbox instance from your file system.

*Removing Instances from the InnoDB Cluster*

You can remove an instance from a cluster at any time should you wish to
do so.  This can be done with the 'removeInstance()' method, as in the
following example:

     mysql-js> cluster.removeInstance('root@localhost:3310')

*Customizing InnoDB clusters*

When you create a cluster and add instances to it, values such as the
group name, the local address, and the seed instances are configured
automatically by AdminAPI. These default values are recommended for most
deployments, but advanced users can override these defaults by passing
the following options to the 'dba.createCluster()' and
'cluster.addInstance()'.

To customize the name of the replication group created by InnoDB
cluster, pass the 'groupName' option to the 'dba.createCluster()'
command.  This sets the 'group_replication_group_name' system variable.
The name must be a valid UUID.

To customize the address which an instance provides for connections from
other instances, pass the 'localAddress' option to the
'dba.createCluster()' and 'cluster.addInstance()' commands.  Specify the
address in the format 'HOST:PORT'.  This sets the
'group_replication_local_address' system variable on the instance.  The
address must be accessible to all instances in the cluster, and must be
reserved for internal cluster communication only.  In other words do not
use this address for communication with the instance.

To customize the instances used as seeds when an instance joins the
cluster, pass the 'groupSeeds' option to the 'dba.createCluster()' and
'cluster.addInstance()' commands.  Seed instances are contacted when a
new instance joins a cluster and used to provide data to the new
instance.  The addresses are specified as a comma separated list such as
'host1:port1','host2:port2'.  This configures the
'group_replication_group_seeds' system variable.

For more information see the documentation of the system variables
configured by these AdminAPI options.

*Rejoining a Cluster*

If an instance leaves the cluster, for example because it lost
connection and did not or could not automatically rejoin the cluster, it
might be necessary to rejoin it to the cluster at a later stage.  To
rejoin an instance to a cluster issue 'cluster.rejoinInstance()'.

In the case where an instance has not had it's configuration persisted,
for example when you have not issued 'dba.configureLocalInstance()'
_locally_ on the instance but it has been added to a cluster, upon
restart the instance does not rejoin the cluster automatically.  The
solution is to issue 'cluster.rejoinInstance()' so that the instance is
added to the cluster again.  Then connect to the instance, run MySQL
Shell locally and issue 'dba.configureLocalInstance()'.  This ensures
the InnoDB cluster configuration is persisted to the instance's option
file to enable it to rejoin the cluster automatically.

*Tip*:

If the instance has 'super_read_only=ON' then you might need to confirm
that AdminAPI can set 'super_read_only=OFF'.  See
super-read-only-on-instance for more information.

*Restoring a Cluster from Quorum Loss*

If a instance (or instances) fail, then a cluster can lose its quorum,
which is the ability to vote in a new primary.  In this case you can
re-establish quorum using the method
'cluster.forceQuorumUsingPartitionOf()', as shown in the following MySQL
Shell example:

       // open session to a cluster

     mysql-js> cluster = dba.getCluster("prodCluster")

       // The cluster lost its quorum and its status shows
       // "status": "NO_QUORUM"

     mysql-js> cluster.forceQuorumUsingPartitionOf("localhost:3310")

       Restoring replicaset 'default' from loss of quorum, by using the partition composed of [localhost:3310]

       Please provide the password for 'root@localhost:3310': ******
       Restoring the InnoDB cluster ...

       The InnoDB cluster was successfully restored using the partition from the instance 'root@localhost:3310'.

       WARNING: To avoid a split-brain scenario, ensure that all other members of the replicaset
       are removed or joined back to the group that was restored.

*Rebooting a Cluster from a Major Outage*

If your cluster suffers from a complete outage, you can ensure it is
reconfigured correctly using 'dba.rebootClusterFromCompleteOutage()'.
In the event that a cluster has completely stopped, the instances must
be started and only then can the cluster be started.  For example if the
machine a sandbox cluster was running on has been restarted, and the
instances were at ports 3310, 3320 and 3330, issue:

     mysql-js> dba.startSandboxInstance(3310)
     mysql-js> dba.startSandboxInstance(3320)
     mysql-js> dba.startSandboxInstance(3330)

This ensures the sandbox instances are running.  In the case of a
production deployment you would have to start the instances outside of
MySQL Shell.  Once the instances have started, connect to an instance
and run MySQL Shell.  Then restart the cluster by issuing:

     mysql-js> shell.connect('root@localhost:3310');
     mysql-js> var cluster = dba.rebootClusterFromCompleteOutage();

*Tip*:

If the instance has 'super_read_only=ON' then you might need to confirm
that AdminAPI can set 'super_read_only=OFF'.  See
super-read-only-on-instance for more information.

This ensures the cluster is correctly reconfigured after a complete
outage.  It uses the instance that MySQL Shell is connected to as the
new seed instance and recovers the cluster based on the existing
metadata of that instance.

If this process fails, and the cluster metadata has become badly
corrupted, you might need to drop the metadata and create the cluster
again from scratch.  You can drop the cluster metadata using
'dba.dropMetadataSchema()'.

*Warning*:

The 'dba.dropMetadataSchema()' method should only be used as a last
resort, when it is not possible to restore the cluster.  It cannot be
undone.

*Rescanning a Cluster*

If changes to an instance's configuration are made without using
AdminAPI, you need to rescan the cluster to update the InnoDB cluster
metadata.  For example, if you manually add a new instance to the Group
Replication group, the InnoDB cluster metadata is not modified based on
this change to the cluster because MySQL Shell was not used.  In such a
scenario it is necessary to rescan the cluster with 'cluster.rescan()'
to update the InnoDB cluster metadata.

After the command 'cluster.rescan()' has been run, instances are
identified that are newly discovered instances.  You are prompted to add
each of these newly discovered instances into your cluster as required,
or you can choose to ignore them.

Instances that no longer belong to the cluster or which are unavailable
are also reported.  In this case you are prompted to remove the
instance, or you can later attempt to add it back into the cluster using
a command such as 'cluster.rejoin('ic@ic-4:3306')'.

*Checking Instance State*

The 'cluster.checkInstanceState()' function can be used to to verify the
existing data on an instance does not prevent it from joining a cluster.
This process works by validating the instance's global transaction
identifier (GTID) state compared to the GTIDs already processed by the
cluster.  For more information on GTIDs see
replication-gtids-concepts.  This check enables you to determine if an
instance which has processed transactions can be added to the cluster.

The following demonstrates issuing this in a running MySQL Shell:

     mysql-js> cluster.checkInstanceState('ic@ic-4:3306')

The output of this function can be one of the following:

   * OK new: the instance has not executed any GTID transactions,
     therefore it cannot conflict with the GTIDs executed by the cluster

   * OK recoverable: the instance has executed GTIDs which do not
     conflict with the executed GTIDs of the cluster seed instances

   * ERROR diverged: the instance has executed GTIDs which diverge with
     the executed GTIDs of the cluster seed instances

   * ERROR lost_transactions: the instance has more executed GTIDs than
     the executed GTIDs of the cluster seed instances

Instances with an OK status can be added to the cluster because any data
on the instance is consistent with the cluster.  In other words the
instance being checked has not executed any transactions which conflict
with the GTIDs executed by the cluster, and can be recovered to the same
state as the rest of the cluster instances.

*Dissolving an InnoDB Cluster*

To dissolve an InnoDB cluster you connect to a read-write instance, for
example the primary in a single-primary cluster, and use the
'Cluster.dissolve()' command.  This removes all metadata and
configuration associated with the cluster, and disables Group
Replication on the instances.  Any data that was replicated between the
instances is not removed.  There is no way to undo the dissolving of a
cluster, therefore you must pass 'force: true' to confirm you want to
dissolve the cluster.  For example: to create it again use
'dba.createCluster()'.

     mysql-js> session
     <ClassicSession:root@localhost:3310>
     mysql-js> cluster.dissolve({force:true})
     The cluster was successfully dissolved.
     Replication was disabled but user data was left intact.

*Note*:

After issuing 'cluster.dissolve()', any variable assigned to the
'Cluster' object is no longer valid.

*Securing your Cluster*

Server instances can be configured to use secure connections.  For
general information on using SSL with MySQL see
encrypted-connections.  This section explains how to configure a
cluster to use SSL. An additional security possibility is to configure
which servers can access the cluster, see
create-whitelist-servers.

*Important*:

Once you have configured a cluster to use SSL you must add the servers
to the 'ipWhitelist'.

When using 'dba.createCluster()' to set up a cluster, if the server
instance provides SSL encryption then it is automatically enabled on the
seed instance.  Pass the 'memberSslMode' option to the
'dba.createCluster()' method to specify a different SSL mode.  The SSL
mode of a cluster can only be set at the time of creation.  The
'memberSslMode' option is a string that configures the SSL mode to be
used, it defaults to 'AUTO'.  The permitted values are 'DISABLED',
'REQUIRED', and 'AUTO'.  These modes are defined as:

   * Setting 'createCluster({memberSslMode:'DISABLED'})' ensures SSL
     encryption is disabled for the seed instance in the cluster.

   * Setting 'createCluster({memberSslMode:'REQUIRED'})' then SSL
     encryption is enabled for the seed instance in the cluster.  If it
     cannot be enabled an error is raised.

   * Setting 'createCluster({memberSslMode:'AUTO'})' (the default) then
     SSL encryption is automatically enabled if the server instance
     supports it, or disabled if the server does not support it.

*Note*:

When using the commercial version of MySQL, SSL is enabled by default
and you might need to configure the whitelist for all instances.  See
create-whitelist-servers.

When you issue the 'cluster.addInstance()' and
'cluster.rejoinInstance()' commands, SSL encryption on the instance is
enabled or disabled based on the setting found for the seed instance.
For more control, the 'cluster.addInstance()', and
'cluster.rejoinInstance()' commands accept the 'memberSslMode' option.
This can be used to test the SSL settings of the cluster when instances
join.  The behavior of the commands in this case is:

   * Setting 'memberSslMode:'DISABLED'' ensures SSL encryption is
     disabled for the instance in the cluster.

   * Setting 'memberSslMode:'REQUIRED'' forces SSL encryption to be
     enabled for the instance in the cluster.

   * Setting 'memberSslMode:'AUTO'' (the default) then SSL encryption is
     automatically enabled or disabled based on the setting used by the
     seed instance (other members of the cluster) and the available SSL
     support provided by the instance itself.

When using 'createCluster()' with the 'adoptFromGR' option to adopt an
existing Group Replication group, no SSL settings are changed on the
adopted cluster:

   * 'memberSslMode' cannot be used with 'adoptFromGR'.

   * If the SSL settings of the adopted cluster are different from the
     ones supported by the MySQL Shell, in other words SSL for Group
     Replication recovery and Group Communication, both settings are not
     modified.  This means you are not be able to add new instances to
     the cluster, unless you change the settings manually for the
     adopted cluster.

MySQL Shell always enables or disables SSL for the cluster for both
Group Replication recovery and Group Communication, see
group-replication-secure-socket-layer-support-ssl.  A verification is
performed and an error issued in case those settings are different for
the seed instance (for example as the result of a 'dba.createCluster()'
using 'adoptFromGR') when adding a new instance to the cluster.  SSL
encryption must be enabled or disabled for all instances in the cluster.
Verifications are performed to ensure that this invariant holds when
adding a new instance to the cluster.

The 'deploySandboxInstance()' command attempts to deploy sandbox
instances with SSL encryption support by default.  If it is not
possible, the server instance is deployed without SSL support.  Use the
'ignoreSslError' option set to false to ensure that sandbox instances
are deployed with SSL support, issuing an error if SSL support cannot be
provided.  When 'ignoreSslError' is true, which is the default, no error
is issued during the operation if the SSL support cannot be provided and
the server instance is deployed without SSL support.

*Creating a Whitelist of Servers*

When using a cluster's 'createCluster()', 'addInstance()', and
'rejoinInstance()' methods you can optionally specify a list of approved
servers that belong to the cluster, referred to as a whitelist.  By
specifying the whitelist explicitly in this way you can increase the
security of your cluster because only servers in the whitelist can
connect to the cluster.

By default, if not specified explicitly, the whitelist is automatically
set to the private network addresses that the server has network
interfaces on.  To configure the whitelist, specify the servers to add
with the 'ipWhitelist' option when using the method.  Pass the servers
as a comma separated list, surrounded by quotes.  Using the
'ipWhitelist' option configures the 'group_replication_ip_whitelist'
system variable on the instance.  For example:

     mysql-js> cluster.addInstance("ic@ic-3:3306", {ipWhitelist: "203.0.113.0/24, 198.51.100.110"})

This configures the instance to only accept connections from servers at
addresses '203.0.113.0/24' and '198.51.100.110'.  From MySQL 5.7.21, the
whitelist can also include host names, which are resolved only when a
connection request is made by another server.

*Warning*:

Host names are inherently less secure than IP addresses in a whitelist.
MySQL carries out FCrDNS verification, which provides a good level of
protection, but can be compromised by certain types of attack.  Specify
host names in your whitelist only when strictly necessary, and ensure
that all components used for name resolution, such as DNS servers, are
maintained under your control.  You can also implement name resolution
locally using the hosts file, to avoid the use of external components.

*Using MySQL Shell to Execute a Script*

You can automate cluster configuration with scripts.  For example:

     shell> mysqlsh -f SETUP-INNODB-CLUSTER.JS

*Note*:

Any command line options specified after the script file name are passed
to the script and _not_ to MySQL Shell.  You can access those options
using the 'os.argv' array in JavaScript, or the 'sys.argv' array in
Python.  In both cases, the first option picked up in the array is the
script name.

The contents of an example script file is shown here:

       print('MySQL InnoDB cluster sandbox set up\n');
       print('==================================\n');
       print('Setting up a MySQL InnoDB cluster with 3 MySQL Server sandbox instances.\n');
       print('The instances will be installed in ~/mysql-sandboxes.\n');
       print('They will run on ports 3310, 3320 and 3330.\n\n');

       var dbPass = shell.prompt('Please enter a password for the MySQL root account: ', {type:"password"});

       try {
          print('\nDeploying the sandbox instances.');
          dba.deploySandboxInstance(3310, {password: dbPass});
          print('.');
          dba.deploySandboxInstance(3320, {password: dbPass});
          print('.');
          dba.deploySandboxInstance(3330, {password: dbPass});
          print('.\nSandbox instances deployed successfully.\n\n');

          print('Setting up InnoDB cluster...\n');
          shell.connect('root@localhost:3310', dbPass);

          var cluster = dba.createCluster("prodCluster");

          print('Adding instances to the cluster.');
          cluster.addInstance({user: "root", host: "localhost", port: 3320, password: dbPass});
          print('.');
          cluster.addInstance({user: "root", host: "localhost", port: 3330, password: dbPass});
          print('.\nInstances successfully added to the cluster.');

          print('\nInnoDB cluster deployed successfully.\n');
       } catch(e) {
          print('\nThe InnoDB cluster could not be created.\n\nError: ' +
          + e.message + '\n');
       }

20.5 Known Limitations
======================

This section describes the known limitations of InnoDB cluster.  As
InnoDB cluster uses Group Replication, you should also be aware of its
limitations, see group-replication-limitations.

   * The formatting of results which contain multi-byte characters
     sometimes do not have correctly aligned columns.  Similarly,
     non-standard character sets are being corrupted in results.

   * AdminAPI does not support Unix socket connections.  MySQL Shell
     currently does not prevent you from attempting to use socket
     connections to a cluster, and attempting to use a socket connection
     to a cluster can cause unexpected results.

   * The MySQL Shell help describes an invalid URI:

          USER[:PASS]@::SOCKET[/DB].

     This is invalid because the '@' symbol can not be present if no
     user information is provided.

   * If a session type is not specified when creating the global
     session, MySQL Shell provides automatic protocol detection which
     attempts to first create a NodeSession and if that fails it tries
     to create a ClassicSession.  With an InnoDB cluster that consists
     of three server instances, where there is one read-write port and
     two read-only ports, this can cause MySQL Shell to only connect to
     one of the read-only instances.  Therefore it is recommended to
     always specify the session type when creating the global session.

   * When adding non-sandbox server instances (instances which you have
     configured manually rather than using 'dba.deploySandboxInstance()'
     ) to a cluster, MySQL Shell is not able to persist any
     configuration changes in the instance's configuration file.  This
     leads to one or both of the following scenarios:

       1. The Group Replication configuration is not persisted in the
          instance's configuration file and upon restart the instance
          does not rejoin the cluster.

       2. The instance is not valid for cluster usage.  Although the
          instance can be verified with
          'dba.checkInstanceConfiguration()', and MySQL Shell makes the
          required configuration changes in order to make the instance
          ready for cluster usage, those changes are not persisted in
          the configuration file and so are lost once a restart happens.

     If only 'a' happens, the instance does not rejoin the cluster after
     a restart.

     If 'b' also happens, and you observe that the instance did not
     rejoin the cluster after a restart, you cannot use the recommended
     'dba.rebootClusterFromCompleteOutage()' in this situation to get
     the cluster back online.  This is because the instance loses any
     configuration changes made by MySQL Shell, and because they were
     not persisted, the instance reverts to the previous state before
     being configured for the cluster.  This causes Group Replication to
     stop responding, and eventually the command times out.

     To avoid this problem it is strongly recommended to use
     'dba.configureLocalInstance()' before adding instances to a cluster
     in order to persist the configuration changes.

   * Using MySQL server instances configured with the validate_password
     plugin and password policy set to 'STRONG' causes InnoDB cluster
     'createCluster()' and MySQL Router bootstrap operations to fail.
     This is because the internal user required for access to the server
     instance can not be validated.

   * The MySQL Router '--bootstrap' command line option does not accept
     IPv6 addresses.

   * The commercial version of MySQL Router does not have the correct
     setting for AppArmor.  A work around is to edit the AppArmor
     profile configuration file '/etc/apparmor.d/usr.sbin.mysqlrouter'
     and modify the line containing '/usr/sbin/mysqld' to use the path
     to MySQL Router, for example '/usr/sbin/mysqlrouter'.

   * Using the 'adoptFromGR' option with the 'dba.createCluster()'
     function to create a cluster based on an existing deployment of
     Group Replication fails with an error that the instance is already
     part of a replication group.  This happens in MySQL Shell's default
     wizard mode only.  A workaround is to disable wizard mode by
     launching 'mysqlsh' with the '--no-wizard' command
     option.

   * The use of the '--defaults-extra-file' option to specify an option
     file is not supported by InnoDB cluster server instances.

21 MySQL NDB Cluster 7.5 and NDB Cluster 7.6
********************************************

MySQL _NDB Cluster_ is a high-availability, high-redundancy version of
MySQL adapted for the distributed computing environment.  Recent NDB
Cluster release series use version 7 of the 'NDB'.
storage engine (also known as 'NDBCLUSTER') to
enable running several computers with MySQL servers and other software
in a cluster.  NDB Cluster 7.5, now available as a General Availability
(GA) release beginning with version 7.5.4, incorporates version 7.5 of
the 'NDB' storage engine.  NDB Cluster 7.6, which uses version 7.6 of
the 'NDB' storage engine, is also now available as a developer preview.
Previous GA releases still available for production, NDB 7.3 and NDB
Cluster 7.4, incorporate 'NDB' versions 7.3 and 7.4, respectively.

Support for the 'NDB' storage engine is not
included in standard MySQL Server 5.7 binaries built by Oracle.
Instead, users of NDB Cluster binaries from Oracle should upgrade to the
most recent binary release of NDB Cluster for supported platforms--these
include RPMs that should work with most Linux distributions.  NDB
Cluster users who build from source should use the sources provided for
NDB Cluster.  (Locations where the sources can be obtained are listed
later in this section.)

*Important*:

MySQL NDB Cluster does not support InnoDB cluster, which must be
deployed using MySQL Server 5.7 with the 'InnoDB'
storage engine as well as additional applications
that are not included in the NDB Cluster distribution.  MySQL Server 5.7
binaries cannot be used with MySQL NDB Cluster.  For more information
about deploying and using InnoDB cluster, see
mysql-innodb-cluster-userguide.  See mysql-cluster-compared,
discusses differences between the 'NDB' and 'InnoDB' storage engines.

This chapter contains information about NDB Cluster 7.5 releases through
5.7.22-ndb-7.5.11 and NDB Cluster 7.6 releases through 5.7.22-ndb-7.6.5.
NDB Cluster 7.5 is available as a General Availability release, and
recommended for new deployments.  NDB Cluster 7.6 is currently in
development, and is available as a developer preview for pre-production
evaluation and testing.  The NDB Cluster 7.4 and NDB Cluster 7.3 release
series are previous GA releases still supported in production.  NDB
Cluster 7.2 is a previous GA release series which is still supported.
We currently recommend that new deployments for production use NDB
Cluster 7.5.  For more information about NDB Cluster 7.4 and NDB Cluster
7.3, see MySQL NDB Cluster 7.3 and NDB Cluster 7.4
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster.html).  For
information about NDB Cluster 7.2, see MySQL NDB Cluster 7.2
(http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster.html).

Supported Platforms

NDB Cluster is currently available and supported on a number of
platforms.  For exact levels of support available for on specific
combinations of operating system versions, operating system
distributions, and hardware platforms, please refer to
<http://www.mysql.com/support/supportedplatforms/cluster.html>.

Availability

NDB Cluster binary and source packages are available for supported
platforms from <http://dev.mysql.com/downloads/cluster/>.

NDB Cluster release numbers

NDB Cluster follows a somewhat different release pattern from the
mainline MySQL Server 5.7 series of releases.  In this 'Manual' and
other MySQL documentation, we identify these and later NDB Cluster
releases employing a version number that begins with 'NDB'.  This
version number is that of the 'NDBCLUSTER' storage
engine used in the release, and not of the MySQL server version on which
the NDB Cluster release is based.

Version strings used in NDB Cluster software

The version string displayed by NDB Cluster programs uses this format:

     mysql-MYSQL_SERVER_VERSION-ndb-NDB_ENGINE_VERSION

MYSQL_SERVER_VERSION represents the version of the MySQL Server on which
the NDB Cluster release is based.  For all NDB Cluster 7.5 and NDB
Cluster 7.6 releases, this is '5.7'.  NDB_ENGINE_VERSION is the version
of the 'NDB' storage engine used by this release
of the NDB Cluster software.  You can see this format used in the
'mysql' client, as shown here:

     shell> mysql
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 2
     Server version: 5.7.22-ndb-7.5.11 Source distribution

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql> SELECT VERSION()\G
     *************************** 1. row ***************************
     VERSION(): 5.7.22-ndb-7.5.11
     1 row in set (0.00 sec)

This version string is also displayed in the output of the 'SHOW'
command in the 'ndb_mgm' client:

     ndb_mgm> SHOW
     Connected to Management Server at: localhost:1186
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     2 node(s)
     id=1    @10.0.10.6  (5.7.22-ndb-7.5.11, Nodegroup: 0, *)
     id=2    @10.0.10.8  (5.7.22-ndb-7.5.11, Nodegroup: 0)

     [ndb_mgmd(MGM)] 1 node(s)
     id=3    @10.0.10.2  (5.7.22-ndb-7.5.11)

     [mysqld(API)]   2 node(s)
     id=4    @10.0.10.10  (5.7.22-ndb-7.5.11)
     id=5 (not connected, accepting connect from any host)

The version string identifies the mainline MySQL version from which the
NDB Cluster release was branched and the version of the 'NDB'
storage engine used.  For example, the full version
string for NDB 7.5.4 (the first NDB 7.5 GA release) was
'mysql-5.7.16-ndb-7.5.4'.  From this we can determine the following:

   * Since the portion of the version string preceding '-ndb-' is the
     base MySQL Server version, this means that NDB 7.5.4 derived from
     MySQL 5.7.16, and contained all feature enhancements and bug fixes
     from MySQL 5.7 up to and including MySQL 5.7.16.

   * Since the portion of the version string following '-ndb-'
     represents the version number of the 'NDB'.
     (or 'NDBCLUSTER') storage engine, NDB 7.5.4
     used version 7.5.4 of the 'NDBCLUSTER'.
     storage engine.

New NDB Cluster releases are numbered according to updates in the 'NDB'
storage engine, and do not necessarily correspond in a one-to-one
fashion with mainline MySQL Server releases.  For example, NDB 7.5.4 (as
previously noted) was based on MySQL 5.7.16, while NDB 7.5.3 was based
on MySQL 5.7.13 (version string: 'mysql-5.7.13-ndb-7.5.3').

Compatibility with standard MySQL 5.7 releases

While many standard MySQL schemas and applications can work using NDB
Cluster, it is also true that unmodified applications and database
schemas may be slightly incompatible or have suboptimal performance when
run using NDB Cluster (see mysql-cluster-limitations).  Most of
these issues can be overcome, but this also means that you are very
unlikely to be able to switch an existing application datastore--that
currently uses, for example, see 'MyISAM' or
'InnoDB'.--to use the 'NDB'
storage engine without allowing for the possibility of
changes in schemas, queries, and applications.  In addition, the MySQL
Server and NDB Cluster codebases diverge considerably, so that the
standard 'mysqld' cannot function as a drop-in
replacement for the version of 'mysqld' supplied with NDB
Cluster.

NDB Cluster development source trees

NDB Cluster development trees can also be accessed from
<https://github.com/mysql/mysql-server>.

The NDB Cluster development sources maintained at
<https://github.com/mysql/mysql-server> are licensed under the GPL. For
information about obtaining MySQL sources using Git and building them
yourself, see installing-development-tree.

*Note*:

As with MySQL Server 5.7, NDB Cluster 7.5 and NDB Cluster 7.6 releases
are built using 'CMake'.

NDB Cluster 7.5 is available as a General Availability (GA) release, and
recommended for new deployments beginning with version 7.5.4.  NDB
Cluster 7.6, currently in developement, is available for evaluation as a
Developer Milestone release.  NDB Cluster 7.4 and NDB Cluster 7.3 are
previous GA releases which are still supported in production.  NDB 7.2
is a previous GA release series which is still supported, although it is
no longer recommended for new deployments.  We currently recommend that
new deployments for production use NDB 7.5.  For an overview of major
features added in NDB 7.4, see What is New in NDB Cluster 7.4
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-what-is-new-7-4.html).
For similar information about NDB Cluster 7.3, see What is New in NDB
Cluster 7.3
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-what-is-new-7-3.html).
For an overview of major features added in previous NDB Cluster
releases, see What is New in MySQL NDB Cluster 7.2
(http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster-what-is-new.html).
NDB 7.1 and earlier versions of NDB Cluster are no longer being
developed or maintained.

The contents of this chapter are subject to revision as NDB Cluster
continues to evolve.  Additional information regarding NDB Cluster can
be found on the MySQL website at
<http://www.mysql.com/products/cluster/>.

Additional Resources

More information about NDB Cluster can be found in the following places:

   * For answers to some commonly asked questions about NDB Cluster, see
     faqs-mysql-cluster.

   * The NDB Cluster mailing list: <http://lists.mysql.com/cluster>.

   * The NDB Cluster Forum: <http://forums.mysql.com/list.php?25>.

   * Many NDB Cluster users and developers blog about their experiences
     with NDB Cluster, and make feeds of these available through
     PlanetMySQL (http://www.planetmysql.org/).

21.1 NDB Cluster Overview
=========================

_NDB Cluster_ is a technology that enables clustering of in-memory
databases in a shared-nothing system.  The shared-nothing architecture
enables the system to work with very inexpensive hardware, and with a
minimum of specific requirements for hardware or software.

NDB Cluster is designed not to have any single point of failure.  In a
shared-nothing system, each component is expected to have its own memory
and disk, and the use of shared storage mechanisms such as network
shares, network file systems, and SANs is not recommended or supported.

NDB Cluster integrates the standard MySQL server with an in-memory
clustered storage engine called 'NDB'. (which
stands for '_N_etwork _D_ata_B_ase').  In our documentation, the term
'NDB' refers to the part of the setup that is
specific to the storage engine, whereas 'MySQL NDB Cluster' refers to
the combination of one or more MySQL servers with the 'NDB'
storage engine.

An NDB Cluster consists of a set of computers, known as _hosts_, each
running one or more processes.  These processes, known as _nodes_, may
include MySQL servers (for access to NDB data), data nodes (for storage
of the data), one or more management servers, and possibly other
specialized data access programs.  The relationship of these components
in an NDB Cluster is shown here:

FIGURE GOES HERE: NDB Cluster Components

All these programs work together to form an NDB Cluster (see
mysql-cluster-programs.  When data is stored by the 'NDB'
storage engine, the tables (and table data) are stored in
the data nodes.  Such tables are directly accessible from all other
MySQL servers (SQL nodes) in the cluster.  Thus, in a payroll
application storing data in a cluster, if one application updates the
salary of an employee, all other MySQL servers that query this data can
see this change immediately.

Although an NDB Cluster SQL node uses the 'mysqld' server
daemon, it differs in a number of critical respects from the
'mysqld' binary supplied with the MySQL 5.7 distributions, and
the two versions of 'mysqld' are not interchangeable.

In addition, a MySQL server that is not connected to an NDB Cluster
cannot use the 'NDB' storage engine and cannot
access any NDB Cluster data.

The data stored in the data nodes for NDB Cluster can be mirrored; the
cluster can handle failures of individual data nodes with no other
impact than that a small number of transactions are aborted due to
losing the transaction state.  Because transactional applications are
expected to handle transaction failure, this should not be a source of
problems.

Individual nodes can be stopped and restarted, and can then rejoin the
system (cluster).  Rolling restarts (in which all nodes are restarted in
turn) are used in making configuration changes and software upgrades
(see mysql-cluster-rolling-restart).  Rolling restarts are also
used as part of the process of adding new data nodes online (see
mysql-cluster-online-add-node).  For more information about data
nodes, how they are organized in an NDB Cluster, and how they handle and
store NDB Cluster data, see mysql-cluster-nodes-groups.

Backing up and restoring NDB Cluster databases can be done using the
'NDB'-native functionality found in the NDB Cluster management client
and the 'ndb_restore' program
included in the NDB Cluster distribution.  For more information, see
mysql-cluster-backup, and
mysql-cluster-programs-ndb-restore.  You can also use the standard
MySQL functionality provided for this purpose in 'mysqldump'
and the MySQL server.  See mysqldump, for more
information.

NDB Cluster nodes can employ different transport mechanisms for
inter-node communications; TCP/IP over standard 100 Mbps or faster
Ethernet hardware is used in most real-world deployments.

21.1.1 NDB Cluster Core Concepts
--------------------------------

_See 'NDBCLUSTER'._ (also known as 'NDB')
is an in-memory storage engine offering
high-availability and data-persistence features.

The 'NDBCLUSTER' storage engine can be configured
with a range of failover and load-balancing options, but it is easiest
to start with the storage engine at the cluster level.  NDB Cluster's
'NDB' storage engine contains a complete set of
data, dependent only on other data within the cluster itself.

The 'Cluster' portion of NDB Cluster is configured independently of the
MySQL servers.  In an NDB Cluster, each part of the cluster is
considered to be a _node_.

*Note*:

In many contexts, the term 'node' is used to indicate a computer, but
when discussing NDB Cluster it means a _process_.  It is possible to run
multiple nodes on a single computer; for a computer on which one or more
cluster nodes are being run we use the term _cluster host_.

There are three types of cluster nodes, and in a minimal NDB Cluster
configuration, there will be at least three nodes, one of each of these
types:

   * _Management node_: The role of this type of node is to manage the
     other nodes within the NDB Cluster, performing such functions as
     providing configuration data, starting and stopping nodes, and
     running backups.  Because this node type manages the configuration
     of the other nodes, a node of this type should be started first,
     before any other node.  An MGM node is started with the command
     'ndb_mgmd'.

   * _Data node_: This type of node stores cluster data.  There are as
     many data nodes as there are replicas, times the number of
     fragments (see mysql-cluster-nodes-groups).  For example,
     with two replicas, each having two fragments, you need four data
     nodes.  One replica is sufficient for data storage, but provides no
     redundancy; therefore, it is recommended to have 2 (or more)
     replicas to provide redundancy, and thus high availability.  A data
     node is started with the command 'ndbd'.
     (see
     mysql-cluster-programs-ndbd) or 'ndbmtd'.
     (see
     mysql-cluster-programs-ndbmtd).

     NDB Cluster tables are normally stored completely in memory rather
     than on disk (this is why we refer to NDB Cluster as an _in-memory_
     database).  However, some NDB Cluster data can be stored on disk;
     see mysql-cluster-disk-data, for more information.

   * _SQL node_: This is a node that accesses the cluster data.  In the
     case of NDB Cluster, an SQL node is a traditional MySQL server that
     uses the 'NDBCLUSTER' storage engine.  An SQL
     node is a 'mysqld' process started with the
     '--ndbcluster' and '--ndb-connectstring' options, which are
     explained elsewhere in this chapter, possibly with additional MySQL
     server options as well.

     An SQL node is actually just a specialized type of _API node_,
     which designates any application which accesses NDB Cluster data.
     Another example of an API node is the 'ndb_restore'
     utility that is used to restore
     a cluster backup.  It is possible to write such applications using
     the NDB API. For basic information about the NDB API, see Getting
     Started with the NDB API
     (http://dev.mysql.com/doc/ndbapi/en/ndb-getting-started.html).

*Important*:

It is not realistic to expect to employ a three-node setup in a
production environment.  Such a configuration provides no redundancy; to
benefit from NDB Cluster's high-availability features, you must use
multiple data and SQL nodes.  The use of multiple management nodes is
also highly recommended.

For a brief introduction to the relationships between nodes, node
groups, replicas, and partitions in NDB Cluster, see
mysql-cluster-nodes-groups.

Configuration of a cluster involves configuring each individual node in
the cluster and setting up individual communication links between nodes.
NDB Cluster is currently designed with the intention that data nodes are
homogeneous in terms of processor power, memory space, and bandwidth.
In addition, to provide a single point of configuration, all
configuration data for the cluster as a whole is located in one
configuration file.

The management server manages the cluster configuration file and the
cluster log.  Each node in the cluster retrieves the configuration data
from the management server, and so requires a way to determine where the
management server resides.  When interesting events occur in the data
nodes, the nodes transfer information about these events to the
management server, which then writes the information to the cluster log.

In addition, there can be any number of cluster client processes or
applications.  These include standard MySQL clients, 'NDB'-specific API
programs, and management clients.  These are described in the next few
paragraphs.

Standard MySQL clients

NDB Cluster can be used with existing MySQL applications written in PHP,
Perl, C, C++, Java, Python, Ruby, and so on.  Such client applications
send SQL statements to and receive responses from MySQL servers acting
as NDB Cluster SQL nodes in much the same way that they interact with
standalone MySQL servers.

MySQL clients using an NDB Cluster as a data source can be modified to
take advantage of the ability to connect with multiple MySQL servers to
achieve load balancing and failover.  For example, Java clients using
Connector/J 5.0.6 and later can use 'jdbc:mysql:loadbalance://' URLs
(improved in Connector/J 5.1.7) to achieve load balancing transparently;
for more information about using Connector/J with NDB Cluster, see Using
Connector/J with NDB Cluster
(http://dev.mysql.com/doc/ndbapi/en/mccj-using-connectorj.html).

NDB client programs

Client programs can be written that access NDB Cluster data directly
from the 'NDBCLUSTER' storage engine, bypassing any MySQL Servers that
may be connected to the cluster, using the _NDB API_, a high-level C++
API. Such applications may be useful for specialized purposes where an
SQL interface to the data is not needed.  For more information, see The
NDB API (http://dev.mysql.com/doc/ndbapi/en/ndbapi.html).

'NDB'-specific Java applications can also be written for NDB Cluster
using the _NDB Cluster Connector for Java_.  This NDB Cluster Connector
includes _ClusterJ_, a high-level database API similar to
object-relational mapping persistence frameworks such as Hibernate and
JPA that connect directly to 'NDBCLUSTER', and so does not require
access to a MySQL Server.  Support is also provided in NDB Cluster for
_ClusterJPA_, an OpenJPA implementation for NDB Cluster that leverages
the strengths of ClusterJ and JDBC; ID lookups and other fast operations
are performed using ClusterJ (bypassing the MySQL Server), while more
complex queries that can benefit from MySQL's query optimizer are sent
through the MySQL Server, using JDBC. See Java and NDB Cluster
(http://dev.mysql.com/doc/ndbapi/en/mccj-overview-java.html), and The
ClusterJ API and Data Object Model
(http://dev.mysql.com/doc/ndbapi/en/mccj-overview-clusterj-object-models.html),
for more information.

NDB Cluster also supports applications written in JavaScript using
Node.js.  The MySQL Connector for JavaScript includes adapters for
direct access to the 'NDB' storage engine and as well as for the MySQL
Server.  Applications using this Connector are typically event-driven
and use a domain object model similar in many ways to that employed by
ClusterJ. For more information, see MySQL NoSQL Connector for JavaScript
(http://dev.mysql.com/doc/ndbapi/en/ndb-nodejs.html).

The Memcache API for NDB Cluster, implemented as the loadable
_ndbmemcache_ storage engine for memcached version 1.6 and later, can be
used to provide a persistent NDB Cluster data store, accessed using the
memcache protocol.

The standard 'memcached' caching engine is included in the NDB Cluster
7.5 distribution.  Each 'memcached' server has direct access to data
stored in NDB Cluster, but is also able to cache data locally and to
serve (some) requests from this local cache.

For more information, see ndbmemcache--Memcache API for NDB Cluster
(http://dev.mysql.com/doc/ndbapi/en/ndbmemcache.html).

Management clients

These clients connect to the management server and provide commands for
starting and stopping nodes gracefully, starting and stopping message
tracing (debug versions only), showing node versions and status,
starting and stopping backups, and so on.  An example of this type of
program is the 'ndb_mgm'.
management client supplied with NDB Cluster (see
mysql-cluster-programs-ndb-mgm).  Such applications can be written
using the _MGM API_, a C-language API that communicates directly with
one or more NDB Cluster management servers.  For more information, see
The MGM API (http://dev.mysql.com/doc/ndbapi/en/mgm-api.html).

Oracle also makes available MySQL Cluster Manager, which provides an
advanced command-line interface simplifying many complex NDB Cluster
management tasks, such restarting an NDB Cluster with a large number of
nodes.  The MySQL Cluster Manager client also supports commands for
getting and setting the values of most node configuration parameters as
well as 'mysqld' server options and variables relating to
NDB Cluster.  See MySQL(tm) Cluster Manager 1.4.4 User Manual
(http://dev.mysql.com/doc/mysql-cluster-manager/1.4/en/), for more
information.

Event logs

NDB Cluster logs events by category (startup, shutdown, errors,
checkpoints, and so on), priority, and severity.  A complete listing of
all reportable events may be found in
mysql-cluster-event-reports.  Event logs are of the two types listed
here:

   * _Cluster log_: Keeps a record of all desired reportable events for
     the cluster as a whole.

   * _Node log_: A separate log which is also kept for each individual
     node.

*Note*:

Under normal circumstances, it is necessary and sufficient to keep and
examine only the cluster log.  The node logs need be consulted only for
application development and debugging purposes.

Checkpoint

Generally speaking, when data is saved to disk, it is said that a
_checkpoint_ has been reached.  More specific to NDB Cluster, a
checkpoint is a point in time where all committed transactions are
stored on disk.  With regard to the 'NDB' storage
engine, there are two types of checkpoints which work together to ensure
that a consistent view of the cluster's data is maintained.  These are
shown in the following list:

   * _Local Checkpoint (LCP)_: This is a checkpoint that is specific to
     a single node; however, LCPs take place for all nodes in the
     cluster more or less concurrently.  An LCP usually occurs every few
     minutes; the precise interval varies, and depends upon the amount
     of data stored by the node, the level of cluster activity, and
     other factors.

     Prior to NDB 7.6.4, an LCP involved saving all of a node's data to
     disk.  NDB 7.6.4 introduces support for partial LCPs, which can
     significantly improve performance under some conditions.  See
     mysql-cluster-what-is-new-7-6, for more information, as well as
     the descriptions of the 'EnablePartialLcp' and 'RecoveryWork'
     configuration parameters which enable partial LCPs and control the
     amount of storage they use.

   * _Global Checkpoint (GCP)_: A GCP occurs every few seconds, when
     transactions for all nodes are synchronized and the redo-log is
     flushed to disk.

For more information about the files and directories created by local
checkpoints and global checkpoints, see NDB Cluster Data Node File
System Directory Files
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndbd-filesystemdir-files.html).

21.1.2 NDB Cluster Nodes, Node Groups, Replicas, and Partitions
---------------------------------------------------------------

This section discusses the manner in which NDB Cluster divides and
duplicates data for storage.

A number of concepts central to an understanding of this topic are
discussed in the next few paragraphs.

Data node

An 'ndbd' or 'ndbmtd'
process, which stores one or more
_replicas_--that is, copies of the _partitions_ (discussed later in this
section) assigned to the node group of which the node is a member.

Each data node should be located on a separate computer.  While it is
also possible to host multiple data node processes on a single computer,
such a configuration is not usually recommended.

It is common for the terms 'node' and 'data node' to be used
interchangeably when referring to an 'ndbd'
or 'ndbmtd'
process; where mentioned, management
nodes (see 'ndb_mgmd' processes) and
SQL nodes (see 'mysqld' processes) are specified as such in
this discussion.

Node group

A node group consists of one or more nodes, and stores partitions, or
sets of _replicas_ (see next item).

The number of node groups in an NDB Cluster is not directly
configurable; it is a function of the number of data nodes and of the
number of replicas ('NoOfReplicas' configuration parameter), as shown
here:

     [# of node groups] = [# of data nodes] / NoOfReplicas

Thus, an NDB Cluster with 4 data nodes has 4 node groups if
'NoOfReplicas' is set to 1 in the 'config.ini' file, 2 node groups if
'NoOfReplicas' is set to 2, and 1 node group if 'NoOfReplicas' is set to
4.  Replicas are discussed later in this section; for more information
about 'NoOfReplicas', see mysql-cluster-ndbd-definition.

*Note*:

All node groups in an NDB Cluster must have the same number of data
nodes.

You can add new node groups (and thus new data nodes) online, to a
running NDB Cluster; see mysql-cluster-online-add-node, for more
information.

Partition

This is a portion of the data stored by the cluster.  Each node is
responsible for keeping at least one copy of any partitions assigned to
it (that is, at least one replica) available to the cluster.

The number of partitions used by default by NDB Cluster depends on the
number of data nodes and the number of LDM threads in use by the data
nodes, as shown here:

     [# of partitions] = [# of data nodes] * [# of LDM threads]

When using data nodes running 'ndbmtd',
the number of LDM threads is controlled
by the setting for 'MaxNoOfExecutionThreads'.  When using 'ndbd'
there is a single LDM thread, which means
that there are as many cluster partitions as nodes participating in the
cluster.  This is also the case when using 'ndbmtd'
with 'MaxNoOfExecutionThreads' set to 3
or less.  (You should be aware that the number of LDM threads increases
with the value of this parameter, but not in a strictly linear fashion,
and that there are additional constraints on setting it; see the
description of 'MaxNoOfExecutionThreads' for more information.)

NDB and user-defined partitioning

NDB Cluster normally partitions 'NDBCLUSTER'.
tables automatically.  However, it is also possible to employ
user-defined partitioning with 'NDBCLUSTER'.
tables.  This is subject to the following limitations:

  1. Only the 'KEY' and 'LINEAR KEY' partitioning schemes are supported
     in production with 'NDB' tables.

  2. The maximum number of partitions that may be defined explicitly for
     any 'NDB' table is '8 *
     MaxNoOfExecutionThreads * [NUMBER OF NODE GROUPS]', the number of
     node groups in an NDB Cluster being determined as discussed
     previously in this section.  When using 'ndbd'
     for data node processes, setting
     'MaxNoOfExecutionThreads' has no effect; in such a case, it can be
     treated as though it were equal to 1 for purposes of performing
     this calculation.

     See mysql-cluster-programs-ndbmtd, for more information.

For more information relating to NDB Cluster and user-defined
partitioning, see mysql-cluster-limitations, and
partitioning-limitations-storage-engines.

Replica

This is a copy of a cluster partition.  Each node in a node group stores
a replica.  Also sometimes known as a _partition replica_.  The number
of replicas is equal to the number of nodes per node group.

A replica belongs entirely to a single node; a node can (and usually
does) store several replicas.

The following diagram illustrates an NDB Cluster with four data nodes
running 'ndbd', arranged in two node
groups of two nodes each; nodes 1 and 2 belong to node group 0, and
nodes 3 and 4 belong to node group 1.

*Note*:

Only data nodes are shown here; although a working NDB Cluster requires
an 'ndb_mgmd' process for
cluster management and at least one SQL node to access the data stored
by the cluster, these have been omitted from the figure for clarity.

FIGURE GOES HERE: NDB Cluster with Two Node Groups

The data stored by the cluster is divided into four partitions, numbered
0, 1, 2, and 3.  Each partition is stored--in multiple copies--on the
same node group.  Partitions are stored on alternate node groups as
follows:

   * Partition 0 is stored on node group 0; a _primary replica_ (primary
     copy) is stored on node 1, and a _backup replica_ (backup copy of
     the partition) is stored on node 2.

   * Partition 1 is stored on the other node group (node group 1); this
     partition's primary replica is on node 3, and its backup replica is
     on node 4.

   * Partition 2 is stored on node group 0.  However, the placing of its
     two replicas is reversed from that of Partition 0; for Partition 2,
     the primary replica is stored on node 2, and the backup on node 1.

   * Partition 3 is stored on node group 1, and the placement of its two
     replicas are reversed from those of partition 1.  That is, its
     primary replica is located on node 4, with the backup on node 3.

What this means regarding the continued operation of an NDB Cluster is
this: so long as each node group participating in the cluster has at
least one node operating, the cluster has a complete copy of all data
and remains viable.  This is illustrated in the next diagram.

FIGURE GOES HERE: Nodes Required for a 2x2 NDB Cluster

In this example, the cluster consists of two node groups each consisting
of two data nodes.  Each data node is running an instance of
'ndbd'.  Any combination of at least one
node from node group 0 and at least one node from node group 1 is
sufficient to keep the cluster 'alive'.  However, if both nodes from a
single node group fail, the combination consisting of the remaining two
nodes in the other node group is not sufficient.  In this situation, the
cluster has lost an entire partition and so can no longer provide access
to a complete set of all NDB Cluster data.

In NDB 7.5.4 and later, the maximum number of node groups supported for
a single NDB Cluster instance is 48 (Bug#80845, Bug #22996305).

21.1.3 NDB Cluster Hardware, Software, and Networking Requirements
------------------------------------------------------------------

One of the strengths of NDB Cluster is that it can be run on commodity
hardware and has no unusual requirements in this regard, other than for
large amounts of RAM, due to the fact that all live data storage is done
in memory.  (It is possible to reduce this requirement using Disk Data
tables--see mysql-cluster-disk-data, for more information about
these.)  Naturally, multiple and faster CPUs can enhance performance.
Memory requirements for other NDB Cluster processes are relatively
small.

The software requirements for NDB Cluster are also modest.  Host
operating systems do not require any unusual modules, services,
applications, or configuration to support NDB Cluster.  For supported
operating systems, a standard installation should be sufficient.  The
MySQL software requirements are simple: all that is needed is a
production release of NDB Cluster.  It is not strictly necessary to
compile MySQL yourself merely to be able to use NDB Cluster.  We assume
that you are using the binaries appropriate to your platform, available
from the NDB Cluster software downloads page at
<http://dev.mysql.com/downloads/cluster/>.

For communication between nodes, NDB Cluster supports TCP/IP networking
in any standard topology, and the minimum expected for each host is a
standard 100 Mbps Ethernet card, plus a switch, hub, or router to
provide network connectivity for the cluster as a whole.  We strongly
recommend that an NDB Cluster be run on its own subnet which is not
shared with machines not forming part of the cluster for the following
reasons:

   * Security

     Communications between NDB Cluster nodes are not encrypted or
     shielded in any way.  The only means of protecting transmissions
     within an NDB Cluster is to run your NDB Cluster on a protected
     network.  If you intend to use NDB Cluster for Web applications,
     the cluster should definitely reside behind your firewall and not
     in your network's De-Militarized Zone (DMZ
     (http://compnetworking.about.com/cs/networksecurity/g/bldef_dmz.htm))
     or elsewhere.

     See mysql-cluster-security-networking-issues, for more
     information.

   * Efficiency

     Setting up an NDB Cluster on a private or protected network enables
     the cluster to make exclusive use of bandwidth between cluster
     hosts.  Using a separate switch for your NDB Cluster not only helps
     protect against unauthorized access to NDB Cluster data, it also
     ensures that NDB Cluster nodes are shielded from interference
     caused by transmissions between other computers on the network.
     For enhanced reliability, you can use dual switches and dual cards
     to remove the network as a single point of failure; many device
     drivers support failover for such communication links.

Network communication and latency

NDB Cluster requires communication between data nodes and API nodes
(including SQL nodes), as well as between data nodes and other data
nodes, to execute queries and updates.  Communication latency between
these processes can directly affect the observed performance and latency
of user queries.  In addition, to maintain consistency and service
despite the silent failure of nodes, NDB Cluster uses heartbeating and
timeout mechanisms which treat an extended loss of communication from a
node as node failure.  This can lead to reduced redundancy.  Recall
that, to maintain data consistency, an NDB Cluster shuts down when the
last node in a node group fails.  Thus, to avoid increasing the risk of
a forced shutdown, breaks in communication between nodes should be
avoided wherever possible.

The failure of a data or API node results in the abort of all
uncommitted transactions involving the failed node.  Data node recovery
requires synchronization of the failed node's data from a surviving data
node, and re-establishment of disk-based redo and checkpoint logs,
before the data node returns to service.  This recovery can take some
time, during which the Cluster operates with reduced redundancy.

Heartbeating relies on timely generation of heartbeat signals by all
nodes.  This may not be possible if the node is overloaded, has
insufficient machine CPU due to sharing with other programs, or is
experiencing delays due to swapping.  If heartbeat generation is
sufficiently delayed, other nodes treat the node that is slow to respond
as failed.

This treatment of a slow node as a failed one may or may not be
desirable in some circumstances, depending on the impact of the node's
slowed operation on the rest of the cluster.  When setting timeout
values such as 'HeartbeatIntervalDbDb' and 'HeartbeatIntervalDbApi' for
NDB Cluster, care must be taken care to achieve quick detection,
failover, and return to service, while avoiding potentially expensive
false positives.

Where communication latencies between data nodes are expected to be
higher than would be expected in a LAN environment (on the order of 100
µs), timeout parameters must be increased to ensure that any allowed
periods of latency periods are well within configured timeouts.
Increasing timeouts in this way has a corresponding effect on the
worst-case time to detect failure and therefore time to service
recovery.

LAN environments can typically be configured with stable low latency,
and such that they can provide redundancy with fast failover.
Individual link failures can be recovered from with minimal and
controlled latency visible at the TCP level (where NDB Cluster normally
operates).  WAN environments may offer a range of latencies, as well as
redundancy with slower failover times.  Individual link failures may
require route changes to propagate before end-to-end connectivity is
restored.  At the TCP level this can appear as large latencies on
individual channels.  The worst-case observed TCP latency in these
scenarios is related to the worst-case time for the IP layer to reroute
around the failures.

SCI support

It is also possible to use the high-speed Scalable Coherent Interface
(SCI) with NDB Cluster, but this is not a requirement.  See
mysql-cluster-interconnects, for more about this protocol and its use
with NDB Cluster.

21.1.4 What is New in NDB Cluster
---------------------------------

The following sections describe changes in the implementation of NDB
Cluster in MySQL NDB Cluster 7.5 and NDB Cluster 7.6 as compared to
earlier release series.  NDB Cluster 7.5 is available as a General
Availability release beginning with NDB 7.5.4, and is recommended for
new deployments.  NDB Cluster 7.6 is available as a Developer Milestone
release.  For information about additions and other changes in NDB
Cluster 7.5, see mysql-cluster-what-is-new-7-5; for information
about new features and other changes in NDB Cluster 7.6, see
mysql-cluster-what-is-new-7-6.

NDB Cluster 7.4 is a recent General Availability release still supported
for new deployments.  NDB Cluster 7.3, is a previous GA release, still
supported in production for existing deployments.  NDB Cluster 7.2 is
also a previous GA release series which is still supported in
production.  NDB 7.1 and earlier releases series are no longer
maintained or supported in production.  We recommend that new
deployments use NDB Cluster 7.4 or NDB Cluster 7.5, which is the latest
GA release.  For information about features added in NDB 7.4, see What
is New in NDB Cluster 7.4
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-what-is-new-7-4.html);
What is New in NDB Cluster 7.3
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-what-is-new-7-3.html)
contains information about features added in NDB 7.3.  For information
about NDB Cluster 7.2 and previous NDB Cluster releases, see What is New
in MySQL NDB Cluster 7.2
(http://dev.mysql.com/doc/refman/5.5/en/mysql-cluster-what-is-new.html).

21.1.4.1 What is New in NDB Cluster 7.5
.......................................

Major changes and new features in NDB Cluster 7.5 which are likely to be
of interest are shown in the following list:

   * ndbinfo Enhancements

     A number of changes are made in the 'ndbinfo'
     database, chief of which is that it now
     provides detailed information about NDB Cluster node configuration
     parameters.

     The 'config_params'.
     table has been made read-only, and has been enhanced with
     additional columns providing information about each configuration
     parameter, including the parameter's type, default value, maximum
     and minimum values (where applicable), a brief description of the
     parameter, and whether the parameter is required.  This table also
     provides each parameter with a unique 'param_number'.

     A row in the 'config_values'
     table shows the current value
     of a given parameter on the node having a specified ID. The
     parameter is identified by the value of the 'config_param' column,
     which maps to the 'config_params' table's 'param_number'.

     Using this relationship you can write a join on these two tables to
     obtain the default, maximum, minimum, and current values for one or
     more NDB Cluster configuration parameters by name.  An example SQL
     statement using such a join is shown here:

          SELECT  p.param_name AS Name,
                  v.node_id AS Node,
                  p.param_type AS Type,
                  p.param_default AS 'Default',
                  p.param_min AS Minimum,
                  p.param_max AS Maximum,
                  CASE p.param_mandatory WHEN 1 THEN 'Y' ELSE 'N' END AS 'Required',
                  v.config_value AS Current
          FROM    config_params p
          JOIN    config_values v
          ON      p.param_number = v.config_param
          WHERE   p. param_name IN ('NodeId', 'HostName','DataMemory', 'IndexMemory');

     For more information about these changes, see
     mysql-cluster-ndbinfo-config-params.  See
     mysql-cluster-ndbinfo-config-values, for further information and
     examples.

     In addition, the 'ndbinfo' database no longer depends on the
     'MyISAM' storage engine.  All 'ndbinfo' tables and views now use
     'NDB' (shown as 'NDBINFO').

     Several new 'ndbinfo' tables were introduced in NDB 7.5.4.  These
     tables are listed here, with brief descriptions:

        * 'dict_obj_info'.
          provides the names and types of database objects in 'NDB', as
          well as information about parent obejcts where applicable

        * 'table_distribution_status'
          provides
          'NDB' table distribution status information

        * 'table_fragments'
          provides information
          about the distribution of 'NDB' table fragments

        * 'table_info' provides
          information about logging, checkpointing, storage, and other
          options in force for each 'NDB' table

        * 'table_replicas'.
          provides information about fragment replicas

     See the descriptions of the individual tables for more information.

   * Default row and column format changes

     Starting with NDB 7.5.1, the default value for both the
     'ROW_FORMAT' option and the 'COLUMN_FORMAT' option for
     'CREATE TABLE' can be set to 'DYNAMIC' rather than
     'FIXED', using a new MySQL server variable
     'ndb_default_column_format' is added as part of this change; set
     this to 'FIXED' or 'DYNAMIC' (or start 'mysqld' with
     the equivalent option '--ndb-default-column-format=FIXED') to force
     this value to be used for 'COLUMN_FORMAT' and 'ROW_FORMAT'.  Prior
     to NDB 7.5.4, the default for this variable was 'DYNAMIC'; in this
     and later versions, the default is 'FIXED', which provides
     backwards compatibility with prior releases (Bug #24487363).

     The row format and column format used by existing table columns are
     unaffected by this change.  New columns added to such tables use
     the new defaults for these (possibly overridden by
     'ndb_default_column_format'), and existing columns are changed to
     use these as well, provided that the 'ALTER TABLE'
     statement performing this operation specifies
     'ALGORITHM=COPY'.

     *Note*:

     A copying 'ALTER TABLE' cannot be done implicitly if
     'mysqld' is run with
     '--ndb-allow-copying-alter-table=FALSE'.

   * ndb_binlog_index no longer dependent on MyISAM

     As of NDB 7.5.2, the 'ndb_binlog_index' table employed in NDB
     Cluster Replication now uses the 'InnoDB'
     storage engine instead of 'MyISAM'.  When
     upgrading, you can run 'mysql_upgrade' with
     '--force' '--upgrade-system-tables' to cause it to execute
     'ALTER TABLE ... ENGINE=INNODB' on this table.  Use
     of 'MyISAM' for this table remains supported for backward
     compatibility.

     A benefit of this change is that it makes it possible to depend on
     transactional behavior and lock-free reads for this table, which
     can help alleviate concurrency issues during purge operations and
     log rotation, and improve the availability of this table.

   * ALTER TABLE changes

     NDB Cluster formerly supported an alternative syntax for online
     'ALTER TABLE'.  This is no longer supported in
     NDB Cluster 7.5, which makes exclusive use of 'ALGORITHM =
     DEFAULT|COPY|INPLACE' for table DDL, as in the standard MySQL
     Server.

     Another change affecting the use of this statement is that 'ALTER
     TABLE ... ALGORITHM=INPLACE RENAME' may now contain DDL operations
     in addition to the renaming.

   * ExecuteOnComputer parameter deprecated

     The 'ExecuteOnComputer' configuration parameter for management
     nodes, data nodes, and API nodes has been deprecated and is now
     subject to removal in a future release of NDB Cluster.  You should
     use the equivalent 'HostName' parameter for all three types of
     nodes.

   * records-per-key optimization

     The NDB handler now uses the records-per-key interface for index
     statistics implemented for the optimizer in MySQL 5.7.5.  Some of
     the benefits from this change include those listed here:

        * The optimizer now chooses better execution plans in many cases
          where a less optimal join index or table join order would
          previously have been chosen

        * Row estimates shown by 'EXPLAIN' are more
          accurate

        * Cardinality estimates shown by 'SHOW INDEX'.
          are improved

   * Connection pool node IDs

     NDB 7.5.0 adds the 'mysqld'.
     '--ndb-cluster-connection-pool-nodeids' option, which allows a set
     of node IDs to be set for the connection pool.  This setting
     overrides '--ndb-nodeid', which means that it also overrides both
     the '--ndb-connectstring' option and the 'NDB_CONNECTSTRING'
     environment variable.

     *Note*:

     You can set the size for the connection pool using the
     '--ndb-cluster-connection-pool' option for 'mysqld'.

   * create_old_temporals removed

     The 'create_old_temporals' system variable was deprecated in NDB
     Cluster 7.4, and has now been removed.

   * ndb_mgm Client PROMPT command

     NDB Cluster 7.5 adds a new command for setting the client's
     command-line prompt.  The following example illustrates the use of
     the 'PROMPT' command:

          ndb_mgm> PROMPT mgm#1:
          mgm#1: SHOW
          Cluster Configuration
          ---------------------
          [ndbd(NDB)]     4 node(s)
          id=5    @10.100.1.1  (mysql-5.7.22-ndb-7.5.11, Nodegroup: 0, *)
          id=6    @10.100.1.3  (mysql-5.7.22-ndb-7.5.11, Nodegroup: 0)
          id=7    @10.100.1.9  (mysql-5.7.22-ndb-7.5.11, Nodegroup: 1)
          id=8    @10.100.1.11  (mysql-5.7.22-ndb-7.5.11, Nodegroup: 1)

          [ndb_mgmd(MGM)] 1 node(s)
          id=50   @10.100.1.8  (mysql-5.7.22-ndb-7.5.11)

          [mysqld(API)]   2 node(s)
          id=100  @10.100.1.8  (5.7.22-ndb-7.5.11)
          id=101  @10.100.1.10  (5.7.22-ndb-7.5.11)

          mgm#1: PROMPT
          ndb_mgm> EXIT
          jon@valhaj:/usr/local/mysql/bin>

     For additional information and examples, see
     mysql-cluster-mgm-client-commands.

   * Increased FIXED column storage per fragment

     NDB Cluster 7.5 and later supports a maximum of 128 TB per fragment
     of data in 'FIXED' columns.  In NDB Cluster 7.4 and earlier, this
     was 16 GB per fragment.

   * Deprecated parameters removed

     The following NDB Cluster data node configuration parameters were
     deprecated in previous releases of NDB Cluster, and were removed in
     NDB 7.5.0:

        * 'Id': deprecated in NDB 7.1.9; replaced by 'NodeId'.

        * 'NoOfDiskPagesToDiskDuringRestartTUP',
          'NoOfDiskPagesToDiskDuringRestartACC': both deprecated, had no
          effect; replaced in MySQL 5.1.6 by
          'DiskCheckpointSpeedInRestart', which itself was later
          deprecated (in NDB 7.4.1) and is now also removed.

        * 'NoOfDiskPagesToDiskAfterRestartACC',
          'NoOfDiskPagesToDiskAfterRestartTUP': both deprecated, and had
          no effect; replaced in MySQL 5.1.6 by 'DiskCheckpointSpeed',
          which itself was later deprecated (in NDB 7.4.1) and is now
          also removed.

        * 'ReservedSendBufferMemory': deprecated in NDB 7.2.5; no longer
          had any effect.

        * 'MaxNoOfIndexes': archaic (pre-MySQL 4.1), had no effect; long
          since replaced by 'MaxNoOfOrderedIndexes' or
          'MaxNoOfUniqueHashIndexes'.

        * 'Discless': archaic (pre-MySQL 4.1) synonym for and long since
          replaced by 'Diskless'.

     The archaic and unused (and for this reason also previously
     undocumented) 'ByteOrder' computer configuration parameter was also
     removed in NDB 7.5.0.

     The parameters just described are not supported in NDB 7.5.
     Attempting to use any of these parameters in an NDB Cluster
     configuration file now results in an error.

   * DBTC scan enhancements

     Scans have been improved by reducing the number of signals used for
     communication between the 'DBTC' and 'DBDIH' kernel blocks in
     'NDB', enabling higher scalability of data nodes
     when used for scan operations by decreasing the use of CPU
     resources for scan operations, in some cases by an estimated five
     percent.

     Also as result of these changes response times should be greatly
     improved, which could help prevent issues with overload of the main
     threads.  In addition, scans made in the 'BACKUP' kernel block have
     also been improved and made more efficient than in previous
     releases.

   * JSON column support

     NDB 7.5.2 and later supports the 'JSON' column type
     for 'NDB' tables and the JSON functions found in the MySQL Server,
     subject to the limitation that an 'NDB' table can have at most 3
     'JSON' columns.

   * Read from any replica; specify number of hashmap partition
     fragments

     Previously, all reads were directed towards the primary replica
     except for simple reads.  (A simple read is a read that locks the
     row while reading it.)  Beginning with NDB 7.5.2, it is possible to
     enable reads from any replica.  This is disabled by default but can
     be enabled for a given SQL node using the 'ndb_read_backup' system
     variable added in this release.

     Previously, it was possible to define tables with only one type of
     partition mapping, with one primary partition on each LDM in each
     node, but in NDB 7.5.2 it becomes possible to be more flexible
     about the assignment of partitions by setting a partition balance
     (fragment count type).  Possible balance schemes are one per node,
     one per node group, one per LDM per node, and one per LDM per node
     group.

     This setting can be controlled for individual tables by means of a
     'PARTITION_BALANCE' option (renamed from 'FRAGMENT_COUNT_TYPE' in
     NDB 7.5.4) embedded in 'NDB_TABLE' comments in 'CREATE TABLE'
     or 'ALTER TABLE'.
     statements.  Settings for table-level 'READ_BACKUP' are also
     supported using this syntax.  For more information and examples,
     see create-table-ndb-table-comment-options.

     In NDB API applications, a table's partition balance can also be
     get and set using methods supplied for this purpose; see
     Table::getPartitionBalance()
     (http://dev.mysql.com/doc/ndbapi/en/ndb-table-getpartitionbalance.html),
     and Table::setPartitionBalance()
     (http://dev.mysql.com/doc/ndbapi/en/ndb-table-setpartitionbalance.html),
     as well as Object::PartitionBalance
     (http://dev.mysql.com/doc/ndbapi/en/ndb-object-partitionbalance.html),
     for more information about these.

     As part of this work, NDB 7.5.2 also introduces the
     'ndb_data_node_neighbour' system variable.  This is intended for
     use, in transaction hinting, to provide a 'nearby' data node to
     this SQL node.

     In addition, when restoring table schemas, see 'ndb_restore'.
     '--restore_meta' now uses the
     target cluster's default partitioning, rather than using the same
     number of partitions as the original cluster from which the backup
     was taken.  See ndb-restore-to-more-nodes, for more
     information and an example.

     NDB 7.5.3 adds a further enhancement to 'READ_BACKUP': In this and
     later versions, it is possible to set 'READ_BACKUP' for a given
     table online as part of 'ALTER TABLE ... ALGORITHM=INPLACE ...'.

   * ThreadConfig improvements

     A number of enhancements and feature additions are implemented in
     NDB 7.5.2 for the 'ThreadConfig' multithreaded data node (see
     'ndbmtd') configuration parameter,
     including support for an increased number of platforms.  These
     changes are described in the next few paragraphs.

     Non-exclusive CPU locking is now supported on FreeBSD and Windows,
     using 'cpubind' and 'cpuset'.  Exclusive CPU locking is now
     supported on Solaris (only) using the 'cpubind_exclusive' and
     'cpuset_exclusive' parameters which are introduced in this release.

     Thread prioritzation is now available, controlled by the new
     'thread_prio' parameter.  'thread_prio' is supported on Linux,
     FreeBSD, Windows, and Solaris, and varies somewhat by platform.
     For more information, see the description of 'ThreadConfig'.

     The 'realtime' parameter is now supported on Windows platforms.

   * Partitions larger than 16 GB

     Due to an improvement in the hash index implementation used by NDB
     Cluster data nodes, partitions of 'NDB' tables may now contain more
     than 16 GB of data for fixed columns, and the maximum partition
     size for fixed columns is now raised to 128 TB. The previous
     limitation was due to the fact that the 'DBACC' block in the 'NDB'
     kernel used only 32-bit references to the fixed-size part of a row
     in the 'DBTUP' block, although 45-bit references to this data are
     used in 'DBTUP' itself and elsewhere in the kernel outside 'DBACC';
     all such references in to the data handled in the 'DBACC' block now
     use 45 bits instead.

   * Print SQL statements from ndb_restore

     NDB 7.5.4 adds the '--print-sql-log' option for the
     'ndb_restore' utility provided
     with the NDB Cluster distribution.  This option enables SQL logging
     to 'stdout'.  *Important*: Every table to be restored using this
     option must have an explicitly defined primary key.

     See mysql-cluster-programs-ndb-restore, for more
     information.

   * Organization of RPM packages

     Beginning with NDB 7.5.4, the naming and organization of RPM
     packages provided for NDB Cluster align more closely with those
     released for the MySQL server.  The names of all NDB Cluster RPMs
     are now prefixed with 'mysql-cluster'.  Data nodes are now
     installed using the 'data-node' package; management nodes are now
     installed from the 'management-server' package; and SQL nodes
     require the 'server' and 'common' packages.  MySQL and 'NDB' client
     programs, including the 'mysql' client and the
     'ndb_mgm' management client, are
     now included in the 'client' RPM.

     For a detailed listing of NDB Cluster RPMs and other information,
     see mysql-cluster-install-linux-rpm.

   * ndbinfo processes and config_nodes tables

     NDB 7.5.7 adds two tables to the 'ndbinfo'
     information database to provide information
     about cluster nodes; these tables are listed here:

        * 'config_nodes'.:
          This table provides the node ID, process type, and host name
          for each node listed in an NDB cluster's configuration file.

        * The 'processes' shows
          information about nodes currently connected to the cluster;
          this information includes the process name and system process
          ID; for each data node and SQL node, it also shows the process
          ID of the node's angel process.  In addition, the table shows
          a service address for each connected node; this address can be
          set in NDB API applications using the
          'Ndb_cluster_connection::set_service_uri()'
          (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-set-service-uri.html)
          method, which is also added in NDB 7.5.7.

   * System name

     The system name of an NDB cluster can be used to identify a
     specific cluster.  Beginning with NDB 7.5.7, the MySQL Server shows
     this name as the value of the 'Ndb_system_name' status variable;
     NDB API applications can use the
     'Ndb_cluster_connection::get_system_name()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-get-system-name.html)
     method which is added in the same release.

     A system name based on the time the management server was started
     is generated automatically; you can override this value by adding a
     '[system]' section to the cluster's configuration file and setting
     the 'Name' parameter to a value of your choice in this section,
     prior to starting the management server.

NDB Cluster 7.5 is also supported by MySQL Cluster Manager, which
provides an advanced command-line interface that can simplify many
complex NDB Cluster management tasks.  See MySQL(tm) Cluster Manager
1.4.4 User Manual
(http://dev.mysql.com/doc/mysql-cluster-manager/1.4/en/), for more
information.

21.1.4.2 What is New in NDB Cluster 7.6
.......................................

New features and other important changes in NDB Cluster 7.6 which are
likely to be of interest are shown in the following list:

   * New Disk Data table file format

     A new file format was introduced in NDB 7.6.2 for NDB Disk Data
     tables, which makes it possible for each Disk Data table to be
     uniquely identified without reusing any table IDs.  The format was
     improved further in NDB 7.6.4.  This should help resolve issues
     with page and extent handling that were visible to the user as
     problems with rapid creating and dropping of Disk Data tables, and
     for which the old format did not provide a ready means to fix.

     The new format is now used whenever new undo log file groups and
     tablespace data files are created.  Files relating to existing Disk
     Data tables continue to use the old format until their tablespaces
     and undo log file groups are re-created.

     *Important*:

     The old and new formats are not compatible; different data files or
     undo log files that are used by the same Disk Data table or
     tablespace cannot use a mix of formats.

     To avoid problems relating to the changes in format, you should
     re-create any existing tablespaces and undo log file groups when
     upgrading to NDB 7.6.2 or NDB 7.6.4.  You can do this by performing
     an initial restart of each data node (that is, using the
     '--initial' option) as part of the upgrade process.  You can expect
     this step to be made mandatory as part of upgrading from NDB 7.5 or
     an earlier release series to NDB 7.6 or later.

     If you are using Disk Data tables, a downgrade from _any_ NDB 7.6
     release--without regard to release status--to any NDB 7.5 or
     earlier release requires that you restart all data nodes with
     '--initial' as part of the downgrade process.  This is because NDB
     7.5 and earlier release series are not able to read the new Disk
     Data file format.

     For more information, see mysql-cluster-upgrade-downgrade.

   * Data memory pooling and dynamic index memory

     Memory required for indexes on 'NDB' table columns is now allocated
     dynamically from that allocated for 'DataMemory'.  For this reason,
     the 'IndexMemory' configuration parameter is now deprecated, and
     subject to removal in a future release series.

     *Important*:

     Starting with NDB 7.6.2, if 'IndexMemory' is set in the
     'config.ini' file, the management server issues the warning
     'IndexMemory is deprecated, use Number bytes on each ndbd(DB) node
     allocated for storing indexes instead' on startup, and any memory
     assigned to this parameter is automatically added to 'DataMemory'.

     In addition, the default value for 'DataMemory' has been increased
     to 98M; the default for 'IndexMemory' has been decreased to 0.

     The pooling together of index memory with data memory simplifies
     the configuration of 'NDB'; a further benefit of these changes is
     that scaling up by increasing the number of LDM threads is no
     longer limited by having set an insufficiently large value for
     'IndexMemory'.This is because index memory is no longer a static
     quantity which is allocated only once (when the cluster starts),
     but can now be allocated and deallocated as required.  Previously,
     it was sometimes the case that increasing the number of LDM threads
     could lead to index memory exhaustion while large amounts of
     'DataMemory' remained available.

     As part of this work, a number of instances of 'DataMemory' usage
     not directly related to storage of table data now use transaction
     memory instead.

     For this reason, it may be necessary on some systems to increase
     'SharedGlobalMemory' to allow transaction memory to increase when
     needed, such as when using NDB Cluster Replication, which requires
     a great deal of buffering on the data nodes.  On systems performing
     initial bulk loads of data, it may be necessary to break up very
     large transactions into smaller parts.

     In addition, data nodes now generate 'MemoryUsage' events (see
     mysql-cluster-log-events) and write appropriate messages in
     the cluster log when resource usage reaches 99%, as well as when it
     reaches 80%, 90%, or 100%, as before.

     Other related changes are listed here:

        * 'IndexMemory' is no longer one of the values displayed in the
          'ndbinfo.memoryusage'
          table's 'memory_type'
          column; is also no longer displayed in the output of
          'ndb_config'.

        * 'REPORT MEMORYUSAGE' and other commands which expose memory
          consumption now shows index memory consumption using 32K pages
          (previously these were 8K pages).

        * The 'ndbinfo.resources'
          table now shows the
          'DISK_OPERATIONS' resource as 'TRANSACTION_MEMORY', and the
          'RESERVED' resource has been removed.

   * ndbinfo processes and config_nodes tables

     NDB 7.6.2 adds two tables to the 'ndbinfo'
     information database to provide information
     about cluster nodes; these tables are listed here:

        * 'config_nodes'.:
          This table the node ID, process type, and host name for each
          node listed in an NDB cluster's configuration file.

        * The 'processes' shows
          information about nodes currently connected to the cluster;
          this information includes the process name and system process
          ID; for each data node and SQL node, it also shows the process
          ID of the node's angel process.  In addition, the table shows
          a service address for each connected node; this address can be
          set in NDB API applications using the
          'Ndb_cluster_connection::set_service_uri()'
          (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-set-service-uri.html)
          method, which is also added in NDB 7.6.2.

   * System name

     The system name of an NDB cluster can be used to identify a
     specific cluster.  Beginning with NDB 7.6.2, the MySQL Server shows
     this name as the value of the 'Ndb_system_name' status variable;
     NDB API applications can use the
     'Ndb_cluster_connection::get_system_name()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-get-system-name.html)
     method which is added in the same release.

     A system name based on the time the management server was started
     is generated automatically>; you can override this value by adding
     a '[system]' section to the cluster's configuration file and
     setting the 'Name' parameter to a value of your choice in this
     section, prior to starting the management server.

   * ndb_import CSV import tool

     See 'ndb_import', added in in
     NDB Cluster 7.6.2, loads CSV-formatted data directly into an
     'NDB' table using the NDB API (a MySQL server is
     needed only to create the table and database in which it is
     located).  See 'ndb_import'.
     can be regarded as an analog of 'mysqlimport'.
     or the 'LOAD DATA INFILE'. SQL statement, and
     supports many of the same or similar options for formatting of the
     data.

     Assuming that the database and target 'NDB' table exist, see
     'ndb_import' needs only a
     connection to the cluster's management server (see 'ndb_mgmd')
     to perform the importation; for
     this reason, there must be an '[api]' slot available to the tool in
     the cluster's 'config.ini' file purpose.

     See mysql-cluster-programs-ndb-import, for more
     information.

   * ndb_top monitoring tool

     Added the 'ndb_top' utility,
     which shows CPU load and usage information for an 'NDB' data node
     in real time.  This information can be displayed in text format, as
     an ASCII graph, or both.  The graph can be shown in color, or using
     grayscale.

     'ndb_top' connects to an NDB
     Cluster SQL node (that is, a MySQL Server).  For this reason, the
     program must be able to connect as a MySQL user having the 'SELECT'
     privilege on tables in the 'ndbinfo'.
     database.

     'ndb_top' is available for
     Linux, Solaris, and Mac OS X platforms beginning with NDB 7.6.3.
     It is not currently available for Windows platforms.

     For more information, see mysql-cluster-programs-ndb-top.

   * Code cleanup

     A significant number of debugging statements and printouts not
     necessary for normal operations have been moved into code used only
     when testing or debugging 'NDB', or dispensed with altogether.
     This removal of overhead should result in a noticeable improvement
     in the performance of LDM and TC threads on the order of 10% in
     many cases.

   * LDM thread and LCP improvements

     Previously, when a local data mangement thread experienced I/O lag,
     it wrote to local checkpoints more slowly.  This could happen, for
     example, during a disk overload condition.  Problems could occur
     because other LDM threads did not always observe this state, or do
     likewise.  'NDB' now tracks I/O lag mode globally, so that this
     state is reported as soon as at least one thread is writing in I/O
     lag mode; it then makes sure that the reduced write speed for this
     LCP is enforced for all LDM threads for the duration of the
     slowdown condition.  Because the reduction in write speed is now
     observed by other LDM instances, overall capacity is increased;
     this enables the disk overload (or other condition inducing I/O
     lag) to be overcome more quickly in such cases than it was
     previously.

   * NDB error identification

     Error messages and information can be obtained using the
     'mysql' client in NDB 7.6.4 and later from a new
     'error_messages' table in
     the 'ndbinfo' information database.
     In addition, the 7.6.4 release introduces a command-line client
     'ndb_perror' for
     obtaining information from NDB error codes; this replaces using
     'perror' with '--ndb', which is now deprecated and
     subject to removal in a future release.

     For more information, see
     mysql-cluster-ndbinfo-error-messages, and
     mysql-cluster-programs-ndb-perror.

   * SPJ improvements

     When executing a scan as a pushed join (that is, the root of the
     query is a scan), the 'DBTC' block sends an SPJ request to a
     'DBSPJ' instance on the same node as the fragment to be scanned.
     Formerly, one such request was sent for each of the node's
     fragments.  As the number of 'DBTC' and 'DBSPJ' instances is
     normally set less than the number of LDM instances, this means that
     all SPJ instances were involved in the execution of a single query,
     and, in fact, some SPJ instances could (and did) receive multiple
     requests from the same query.  In NDB 7.6.4, it becomes possible
     for a single SPJ request to handle a set of root fragments to be
     scanned, so that only a single SPJ request ('SCAN_FRAGREQ') needs
     to be sent to any given SPJ instance ('DBSPJ' block) on each node.

     Since 'DBSPJ' consumes a relatively small amount of the total CPU
     used when evaluating a pushed join, unlike the LDM block (which is
     repsonsible for the majority of the CPU usage), introducing
     multiple SPJ blocks adds some parallelism, but the additional
     overhead also increases.  By enabling a single SPJ request to
     handle a set of root fragments to be scanned, such that only a
     single SPJ request is sent to each 'DBSPJ' instance on each node
     and batch sizes are allocated per fragment, the multi-fragment scan
     can obtain a larger total batch size, allowing for some scheduling
     optimizations to be done within the SPJ block, which can scan a
     single fragment at at a time (giving it the total batch size
     allocation), scan all fragments in parallel using smaller
     sub-batches, or some combination of the two.

     This work is expected to increase performance of pushed-down joins
     for the following reasons:

        * Since multiple root fragments can be scanned for each SPJ
          request, it is necessary to request fewer SPJ instances when
          executing a pushed join

        * Increased available batch size allocation, and for each
          fragment, should also in most cases result in fewer requests
          being needed to complete a join

   * Improved O_DIRECT handling for redo logs

     NDB 7.6.4 implements a new data node configuration parameter
     'ODirectSyncFlag' which causes completed redo log writes using
     'O_DIRECT' to be handled as 'fsync' calls.  'ODirectSyncFlag' is
     disabled by default; to enable it, set it to 'true'.

     You should bear in mind that the setting for this parameter is
     ignored when at least one of the following conditions is true:

        * 'ODirect' is not enabled.

        * 'InitFragmentLogFiles' is set to 'SPARSE'.

   * Locking of CPUs to offline index build threads

     In NDB 7.6.4 and later, offline index builds by default use all
     cores available to 'ndbmtd',
     instead of being limited to the single core reserved for the I/O
     thread.  It also becomes possible to specify a desired set of cores
     to be used for I/O threads performing offline multithreaded builds
     of ordered indexes.  This can improve restart and restore times and
     performance, as well as availability.

     *Note*:

     'Offline' as used here refers to an ordered index build that takes
     place while a given table is not being written to.  Such index
     builds occur during a node or system restart, or when restoring a
     cluster from backup using 'ndb_restore'.
     '--rebuild-indexes'.

     This improvement involves several related changes.  The first of
     these is to change the default value for the 'BuildIndexThreads'
     configuration parameter (from 0 to 128), means that offline ordered
     index builds are now multithreaded by default.  The default value
     for the 'TwoPassInitialNodeRestartCopy' is also changed (from
     'false' to 'true'), so that an initial node restart first copies
     all data without any creation of indexes from a 'live' node to the
     node which is being started, builds the ordered indexes offline
     after the data has been copied, then again synchronizes with the
     live node; this can significantly reduce the time required for
     building indexes.  In addition, to facilitate explicit locking of
     offline index build threads to specific CPUs, a new thread type
     ('idxbld') is defined for the 'ThreadConfig' configuration
     parameter.

     As part of this work, 'NDB' can now distinguish between execution
     thread types and other types of threads, and between types of
     threads which are permanently assigned to specific tasks, and those
     whose assignments are merely temporary.

     NDB 7.6.4 also introduces the 'nosend' parameter for
     'ThreadCOnfig'.  By setting this to 1, you can keep a 'main',
     'ldm', 'rep', or 'tc' thread from assisting the send threads.  This
     parameter is 0 by default, and cannot be used with I/O threads,
     send threads, index build threads, or watchdog threads.

     For additonal information, see the descriptions of the parameters.

   * Variable batch sizes for DDL bulk data operations

     As part of work ongoing to optimize bulk DDL performance by
     'ndbmtd', it is now possible to
     obtain performance improvements by increasing the batch size for
     the bulk data parts of DDL operations processing data using scans.
     Batch sizes are now made configurable for unique index builds,
     foreign key builds, and online reorganization, by setting the
     respective data node configuration parameters listed here:

        * 'MaxUIBuildBatchSize': Maximum scan batch size used for
          building unique keys.

        * 'MaxFKBuildBatchSize': Maximum scan batch size used for
          building foreign keys.

        * 'MaxReorgBuildBatchSize': Maximum scan batch size used for
          reorganization of table partitions.

     For each of the parameters just listed, the default value is 64,
     the minimum is 16, and the maximum is 512.

     Increasing the appropriate batch size or sizes can help amortize
     inter-thread and inter-node latencies and make use of more parallel
     resources (local and remote) to help scale DDL performance.  In
     each case there can be a tradeoff with ongoing traffic.

   * Partial LCPs

     NDB 7.6.4 implements partial local checkpoints.  Formerly, an LCP
     always made a copy of the entire database.  When working with
     terabytes of data this process could require a great deal of time,
     with an adverse impact on node and cluster restarts especially, as
     well as more space for the redo logs.  It is now no longer strictly
     necessary for LCPs to do this--instead, an LCP now by default saves
     only the records that have changed since the last LCP plus one
     fourth of all records.

     As part of this change, two new data node configuration parameters
     are inroduced in this release: 'EnablePartialLcp' (default 'true',
     or enabled) enables partial LCPs.  'RecoveryWork' controls the
     percentage of space given over to LCPs; it increases with the
     amount of work which must be performed on LCPs during restarts as
     opposed to that performed during normal operations.  Raising this
     value causes LCPs during normal operations to require writing fewer
     records and so decreases the usual workload.  Raising this value
     also means that restarts can take longer.

     You must disable partial LCPs explicitly by setting
     'EnablePartialLcp=false'.  This uses the least amount of disk, but
     also tends to maximize the write load for LCPs.  To optimize for
     the lowest workload on LCPs during normal operation, use
     'EnablePartialLcp=true' and 'RecoveryWork=100'.  To use the least
     disk space for partial LCPs, but with bounded writes, use
     'EnablePartialLcp=true' and 'RecoveryWork=25', which is the minimum
     for 'RecoveryWork'.  The default is 'EnablePartialLcp=true' with
     'RecoveryWork=50', which means LCP files require approximately 1.5
     times 'DataMemory'; using 'CompressedLcp=1', this can be further
     reduced by half.  Recovery times using the default settings should
     also be much faster than when 'EnablePartialLcp' is set to 'false'.

     In addition the data node configuration parameters
     'BackupDataBufferSize', 'BackupWriteSize', and 'BackupMaxWriteSize'
     are all now deprecated, and subject to removal in a future release
     of MySQL NDB Cluster.

     As part of this enhancement, work has been done to correct several
     issues with node restarts wherein it was possible to run out of
     undo log in various situations, most often when restoring a node
     that had been down for a long time during a period of intensive
     write activity.

     Additional work was done to improve data node survival of long
     periods of synchronization without timing out, by updating the LCP
     watchdog during this process, and keeping better track of the
     progress of disk data synchronization.  Previously, there was the
     possibility of spurious warnings or even node failures if
     synchronization took longer than the LCP watchdog timeout.

     You should keep in mind, when planning for disk usage by partial
     LCPs, that during recovery it remains necessary to restore the
     database fully.  This means that an initial node restart still
     requires a complete LCP; partial LCPs cannot be used for this
     purpose.

     *Important*:

     When upgrading an NDB Cluster that uses disk data tables to NDB
     7.6.4 or downgrading it from NDB 7.6.4, it is necessary to restart
     all data nodes with '--initial'.

   * Parallel undo log record processing

     Formerly, the data node 'LGMAN' kernel block processed undo log
     records serially; now this is done in parallel.  The rep thread,
     which hands off undo records to LDM threads, waited for an LDM to
     finish applying a record before fetching the next one; now the rep
     thread no longer waits, but proceeds immediately to the next record
     and LDM.

     A count of the number of outstanding log records for each LDM in
     'LGMAN' is kept, and decremented whenever an LDM has completed the
     execution of a record.  All the records belonging to a page are
     sent to the same LDM thread but are not guaranteed to be processed
     in order, so a hash map of pages that have outstanding records
     maintains a queue for each of these pages.  When the page is
     available in the page cache, all records pending in the queue are
     applied in order.

     A few types of records continue to be processed serially:
     'UNDO_LCP', 'UNDO_LCP_FIRST', 'UNDO_LOCAL_LCP',
     'UNDO_LOCAL_LCP_FIRST', 'UNDO_DROP', and 'UNDO_END'.

     There are no user-visible changes in functionality directly
     associated with this performance enhancement; it is part of the
     work being done to improve undo long handling in support of partial
     local checkpoints in NDB Cluster 7.6.4.

   * Reading table and fragment IDs from extent for undo log applier

     When applying an undo log, it is necessary to obtain the table ID
     and fragment ID from the page ID. This was done previously by
     reading the page from the 'PGMAN' kernel block using an extra
     'PGMAN' worker thread, but when applying the undo log it was
     necessary to read the page again.

     when using 'O_DIRECT' this was very inefficient since the page was
     not cached in the OS kernel.  To correct this issue, mapping from
     page ID to table ID and fragment ID is now done using information
     from the extent header the table IDs and fragment IDs for the pages
     used within a given extent.  The extent pages are always present in
     the page cache, so no extra reads from disk are required for
     performing the mapping.  In addition, the information can already
     be read, using existing 'TSMAN' kernel block data structures.

     See the description of the 'ODirect' data node configuration
     parameter, for more information.

   * NDB Cluster Auto-Installer improvements

     In NDB 7.6.4, node configuration parameters, their default values,
     and their documentation as found in the Auto-Installer have been
     better aligned with those found in NDB Cluster software releases.
     SSH support and configuration have also been improved.  In
     addition, HTTPS is now used by default for Web connections, and
     cookies are no longer employed as a persistent data storage
     mechanism.  More information about these and other changes in the
     Auto-Installer is given in the next several paragraphs.

     The Auto-Installer now implements a mechanism for setting
     configuration parameters that take discrete values.  For example,
     the data node parameter 'Arbitration' must now be set to one of its
     allowed values 'Default', 'Disabled', or 'WaitExternal'.

     The Auto-Installer also now gets and shows the amount of disk space
     available per host to the cluster (as 'DiskFree'), using this
     information to obtain realistic values for configuration parameters
     that depend on it.

     Secure connection support in the MySQL NDB Cluster Auto-Installer
     has been updated or improved in NDB Cluster 7.6.4 as follows:

        * Added a mechanism for setting SSH membership for each host.

        * Updated the Paramiko Python module to the latest available
          version (2.6.1).

        * Provided a place in the GUI for encrypted private key
          passwords, and discontinued use of hardcoded passwords such as
          'Password=None'.

     Other enhancements relating to data security that are implemented
     in NDB 7.6.4 include the following:

        * Discontinued use of cookies as a persistent store of NDB
          Cluster configuration information; these were not secure and
          came with a hard upper limit on storage.  Now the
          Auto-Installer uses an encrypted file for this purpose.

        * In order to secure data transfer between the JavaScript front
          end in the user's web browser and the Python web server on the
          back end, the default communications protocol for this has
          been switched from HTTP to HTTPS.

     See mysql-cluster-install-auto, for more information.

21.1.5 MySQL Server Using InnoDB Compared with NDB Cluster
----------------------------------------------------------

MySQL Server offers a number of choices in storage engines.  Since both
'NDB' and 'InnoDB'.
can serve as transactional MySQL storage engines, users of MySQL Server
sometimes become interested in NDB Cluster.  They see 'NDB'
as a possible alternative or upgrade to the default
'InnoDB' storage engine in MySQL 5.7.  While
'NDB' and 'InnoDB'.
share common characteristics, there are differences in architecture and
implementation, so that some existing MySQL Server applications and
usage scenarios can be a good fit for NDB Cluster, but not all of them.

In this section, we discuss and compare some characteristics of the
'NDB' storage engine used by NDB 7.5 with
'InnoDB' used in MySQL 5.7.  The next few
sections provide a technical comparison.  In many instances, decisions
about when and where to use NDB Cluster must be made on a case-by-case
basis, taking all factors into consideration.  While it is beyond the
scope of this documentation to provide specifics for every conceivable
usage scenario, we also attempt to offer some very general guidance on
the relative suitability of some common types of applications for
'NDB' as opposed to 'InnoDB'
back ends.

NDB Cluster 7.5 uses a 'mysqld' based on MySQL 5.7,
including support for 'InnoDB'. 1.1.  While
it is possible to use 'InnoDB' tables with NDB Cluster, such tables are
not clustered.  It is also not possible to use programs or libraries
from an NDB Cluster 7.5 distribution with MySQL Server 5.7, or the
reverse.

While it is also true that some types of common business applications
can be run either on NDB Cluster or on MySQL Server (most likely using
the 'InnoDB' storage engine), there are
some important architectural and implementation differences.  See
mysql-cluster-ndb-innodb-engines, provides a summary of the these
differences.  Due to the differences, some usage scenarios are clearly
more suitable for one engine or the other; see
mysql-cluster-ndb-innodb-workloads.  This in turn has an impact on the
types of applications that better suited for use with 'NDB'
or 'InnoDB'.  See
mysql-cluster-ndb-innodb-usage, for a comparison of the relative
suitability of each for use in common types of database applications.

For information about the relative characteristics of the 'NDB'
and 'MEMORY' storage
engines, see memory-storage-engine-compared-cluster.

See storage-engines, for additional information about MySQL
storage engines.

21.1.5.1 Differences Between the NDB and InnoDB Storage Engines
...............................................................

The 'NDB' storage engine is implemented using a
distributed, shared-nothing architecture, which causes it to behave
differently from 'InnoDB' in a number of
ways.  For those unaccustomed to working with 'NDB',
unexpected behaviors can arise due to its distributed
nature with regard to transactions, foreign keys, table limits, and
other characteristics.  These are shown in the following table:

* Differences between InnoDB and NDB storage engines *

Feature                  'InnoDB' (MySQL 5.7)     'NDB' 7.5/7.6

_MySQL Server Version_   5.7                      5.7

_See 'InnoDB'.
innodb-storage-engine.   innodb-storage-engine.
Version _                5.7.23                   5.7.23

_NDB Cluster Version_    N/A                      'NDB'.
                                                  7.5.11/7.6.5

_Storage Limits_         64TB                     128TB (as of NDB
                                                  7.5.2)

_Foreign Keys_           Yes                      Yes

_Transactions_           All standard types       'READ COMMITTED'

_MVCC_                   Yes                      No

_Data Compression_       Yes                      No (NDB checkpoint and
                                                  backup files can be
                                                  compressed)

_Large Row Support (>    Supported for Supported for *note 14K)_ 'VARBINARY'
and
                         binary-varbinary,        see 'TEXT'.
                         See 'VARCHAR',   columns only (Using
                         'BLOB',      these types to store
                         and 'TEXT'
                         columns            data can lower NDB
                                                  performance)

_Replication Support_    Asynchronous and         Automatic synchronous
                         semisynchronous          replication within an
                         replication using        NDB Cluster;
                         MySQL Replication;       asynchronous
                         MySQL Group replication between Replication,
                         using
                         group-replication.       MySQL Replication
                                                  (Semisynchronous
                                                  replication is not
                                                  supported)

_Scaleout for Read       Yes (MySQL               Yes (Automatic
Operations_              Replication)             partitioning in NDB
                                                  Cluster; NDB Cluster
                                                  Replication)

_Scaleout for Write      Requires                 Yes (Automatic
Operations_              application-level        partitioning in NDB
                         partitioning             Cluster is transparent
                         (sharding)               to applications)

_High Availability       Built-in, from InnoDB    Yes (Designed for
(HA)_                    cluster                  99.999% uptime)

_Node Failure Recovery   From MySQL Group         Automatic (Key element
and Failover_            Replication              in NDB architecture)

_Time for Node Failure   30 seconds or longer     Typically < 1 second
Recovery_

_Real-Time               No                       Yes
Performance_

_In-Memory Tables_       No                       Yes (Some data can
                                                  optionally be stored
                                                  on disk; both
                                                  in-memory and disk
                                                  data storage are
                                                  durable)

_NoSQL Access to         Yes                      Yes (Multiple APIs,
Storage Engine_                                   including Memcached,
                                                  Node.js/JavaScript,
                                                  Java, JPA, C++, and
                                                  HTTP/REST)

_Concurrent and          Yes                      Up to 48 writers,
Parallel Writes_                                  optimized for
                                                  concurrent writes

_Conflict Detection      Yes (MySQL Group         Yes
and Resolution           Replication)
(Multiple Replication
Masters)_

_Hash Indexes_           No                       Yes

_Online Addition of      Read/write replicas      Yes (all node types)
Nodes_                   using MySQL Group
                         Replication

_Online Upgrades_        Yes (using               Yes
                         replication)

_Online Schema           Yes, as part of MySQL    Yes
Modifications_           5.7

21.1.5.2 NDB and InnoDB Workloads
.................................

NDB Cluster has a range of unique attributes that make it ideal to serve
applications requiring high availability, fast failover, high
throughput, and low latency.  Due to its distributed architecture and
multi-node implementation, NDB Cluster also has specific constraints
that may keep some workloads from performing well.  A number of major
differences in behavior between the 'NDB' and
'InnoDB' storage engines with regard to
some common types of database-driven application workloads are shown in
the following table::

*Differences between InnoDB and NDB storage engines, common types of
data-driven application workloads.*

Workload                 'InnoDB'.
                         'NDB': mysql-cluster.)

_High-Volume OLTP        Yes                      Yes
Applications_

_DSS Applications        Yes                      Limited (Join
(data marts,                                      operations across OLTP
analytics)_                                       datasets not exceeding
                                                  3TB in size)

_Custom Applications_    Yes                      Yes

_Packaged                Yes                      Limited (should be
Applications_                                     mostly primary key
                                                  access); NDB Cluster
                                                  7.5 supports foreign
                                                  keys

_In-Network Telecoms     No                       Yes
Applications (HLR,
HSS, SDP)_

_Session Management      Yes                      Yes
and Caching_

_E-Commerce              Yes                      Yes
Applications_

_User Profile            Yes                      Yes
Management, AAA
Protocol_

21.1.5.3 NDB and InnoDB Feature Usage Summary
.............................................

When comparing application feature requirements to the capabilities of
'InnoDB' with 'NDB',
some are clearly more compatible with one storage engine than the other.

The following table lists supported application features according to
the storage engine to which each feature is typically better suited.

*Supported application features according to the storage engine to which
each feature is typically better suited*

Preferred application requirements   Preferred application requirements
for 'InnoDB'.
innodb-storage-engine.

   * Foreign keys                       * Write scaling

     *Note*:                            * 99.999% uptime

     NDB Cluster 7.5 supports           * Online addition of nodes and
     foreign keys                         online schema operations

   * Full table scans                   * Multiple SQL and NoSQL APIs
                                          (see NDB Cluster APIs:
   * Very large databases, rows,          Overview and Concepts
     or transactions                      (http://dev.mysql.com/doc/ndbapi/en/mysql-cluster-api-overview.html))

   * Transactions other than 'READ      * Real-time performance
     COMMITTED'
                                        * Limited use of 'BLOB'
                                        columns

                                        * Foreign keys are supported,
                                          although their use may have
                                          an impact on performance at
                                          high throughput

21.1.6 Known Limitations of NDB Cluster
---------------------------------------

In the sections that follow, we discuss known limitations in current
releases of NDB Cluster as compared with the features available when
using the 'MyISAM' and 'InnoDB' storage engines.  If you check the
'Cluster' category in the MySQL bugs database at
<http://bugs.mysql.com>, you can find known bugs in the following
categories under 'MySQL Server:' in the MySQL bugs database at
<http://bugs.mysql.com>, which we intend to correct in upcoming releases
of NDB Cluster:

   * NDB Cluster

   * Cluster Direct API (NDBAPI)

   * Cluster Disk Data

   * Cluster Replication

   * ClusterJ

This information is intended to be complete with respect to the
conditions just set forth.  You can report any discrepancies that you
encounter to the MySQL bugs database using the instructions given in
bug-reports.  If we do not plan to fix the problem in NDB
Cluster 7.5, we will add it to the list.

See Previous NDB Cluster Issues Resolved in NDB Cluster 7.3
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-limitations-resolved.html)
for a list of issues in earlier releases that have been resolved in NDB
Cluster 7.5.

*Note*:

Limitations and other issues specific to NDB Cluster Replication are
described in mysql-cluster-replication-issues.

21.1.6.1 Noncompliance with SQL Syntax in NDB Cluster
.....................................................

Some SQL statements relating to certain MySQL features produce errors
when used with 'NDB' tables, as described in the
following list:

   * Temporary tables

     Temporary tables are not supported.  Trying either to create a
     temporary table that uses the 'NDB' storage
     engine or to alter an existing temporary table to use 'NDB'
     fails with the error 'Table storage engine
     'ndbcluster' does not support the create option 'TEMPORARY''.

   * Indexes and keys in NDB tables

     Keys and indexes on NDB Cluster tables are subject to the following
     limitations:

        * Column width

          Attempting to create an index on an 'NDB' table column whose
          width is greater than 3072 bytes succeeds, but only the first
          3072 bytes are actually used for the index.  In such cases, a
          warning 'Specified key was too long; max key length is 3072
          bytes' is issued, and a 'SHOW CREATE TABLE'
          statement shows the length of the index as
          3072.

        * TEXT and BLOB columns

          You cannot create indexes on 'NDB' table
          columns that use any of the 'TEXT' or
          'BLOB' data types.

        * FULLTEXT indexes

          The 'NDB' storage engine does not
          support 'FULLTEXT' indexes, which are possible for
          'MyISAM' and 'InnoDB'
          tables only.

          However, you can create indexes on 'VARCHAR'.
          columns of 'NDB' tables.

        * USING HASH keys and NULL

          Using nullable columns in unique keys and primary keys means
          that queries using these columns are handled as full table
          scans.  To work around this issue, make the column 'NOT NULL',
          or re-create the index without the 'USING HASH' option.

        * Prefixes

          There are no prefix indexes; only entire columns can be
          indexed.  (The size of an 'NDB' column index is always the
          same as the width of the column in bytes, up to and including
          3072 bytes, as described earlier in this section.  Also see
          mysql-cluster-limitations-unsupported, for additional
          information.)

        * BIT columns

          A 'BIT' column cannot be a primary key,
          unique key, or index, nor can it be part of a composite
          primary key, unique key, or index.

        * AUTO_INCREMENT columns

          Like other MySQL storage engines, the 'NDB'
          storage engine can handle a maximum of one
          'AUTO_INCREMENT' column per table.  However, in the case of an
          NDB table with no explicit primary key, an 'AUTO_INCREMENT'
          column is automatically defined and used as a 'hidden' primary
          key.  For this reason, you cannot define a table that has an
          explicit 'AUTO_INCREMENT' column unless that column is also
          declared using the 'PRIMARY KEY' option.  Attempting to create
          a table with an 'AUTO_INCREMENT' column that is not the
          table's primary key, and using the 'NDB'.
          storage engine, fails with an error.

   * Restrictions on foreign keys

     Support for foreign key constraints in NDB 7.5 is comparable to
     that provided by 'InnoDB', subject to
     the following restrictions:

        * Every column referenced as a foreign key requires an explicit
          unique key, if it is not the table's primary key.

        * 'ON UPDATE CASCADE' is not supported when the reference is to
          the parent table's primary key.

          This is because an update of a primary key is implemented as a
          delete of the old row (containing the old primary key) plus an
          insert of the new row (with a new primary key).  This is not
          visible to the 'NDB' kernel, which views these two rows as
          being the same, and thus has no way of knowing that this
          update should be cascaded.

        * 'SET DEFAULT' is not supported.  (Also not supported by
          'InnoDB')

        * The 'NO ACTION' keywords are accepted but treated as
          'RESTRICT'.  (Also the same as with 'InnoDB'.)

        * In earlier versions of NDB Cluster, when creating a table with
          foreign key referencing an index in another table, it
          sometimes appeared possible to create the foreign key even if
          the order of the columns in the indexes did not match, due to
          the fact that an appropriate error was not always returned
          internally.  A partial fix for this issue improved the error
          used internally to work in most cases; however, it remains
          possible for this situation to occur in the event that the
          parent index is a unique index.  (Bug #18094360)

        * Prior to NDB 7.5.6, when adding or dropping a foreign key
          using 'ALTER TABLE', the parent table's
          metadata is not updated, which makes it possible subsequently
          to execute 'ALTER TABLE' statements on the parent that should
          be invalid.  To work around this issue, execute 'SHOW CREATE TABLE'
          on the parent table
          immediately after adding or dropping the foreign key; this
          forces the parent's metadata to be reloaded.

          This issue is fixed in NDB 7.5.6.  (Bug #82989, Bug #24666177)

     For more information, see create-table-foreign-keys, and
     constraint-foreign-key.

   * NDB Cluster and geometry data types

     Geometry data types ('WKT' and 'WKB') are supported for
     'NDB' tables.  However, spatial indexes are not
     supported.

   * Character sets and binary log files

     Currently, the 'ndb_apply_status' and 'ndb_binlog_index' tables are
     created using the 'latin1' (ASCII) character set.  Because names of
     binary logs are recorded in this table, binary log files named
     using non-Latin characters are not referenced correctly in these
     tables.  This is a known issue, which we are working to fix.  (Bug
     #50226)

     To work around this problem, use only Latin-1 characters when
     naming binary log files or setting any the '--basedir',
     '--log-bin', or '--log-bin-index' options.

   * Creating NDB tables with user-defined partitioning

     Support for user-defined partitioning in NDB Cluster is restricted
     to ['LINEAR'] 'KEY' partitioning.  Using any other partitioning
     type with 'ENGINE=NDB' or 'ENGINE=NDBCLUSTER' in a 'CREATE TABLE'
     statement results in an error.

     It is possible to override this restriction, but doing so is not
     supported for use in production settings.  For details, see
     partitioning-limitations-ndb.

     Default partitioning scheme

     All NDB Cluster tables are by default partitioned by 'KEY' using
     the table's primary key as the partitioning key.  If no primary key
     is explicitly set for the table, the 'hidden' primary key
     automatically created by the 'NDB' storage
     engine is used instead.  For additional discussion of these and
     related issues, see partitioning-key.

     'CREATE TABLE' and 'ALTER TABLE'
     statements that would cause a user-partitioned
     'NDBCLUSTER' table not to meet either or both of
     the following two requirements are not permitted, and fail with an
     error:

       1. The table must have an explicit primary key.

       2. All columns listed in the table's partitioning expression must
          be part of the primary key.

     Exception

     If a user-partitioned 'NDBCLUSTER' table is
     created using an empty column-list (that is, using 'PARTITION BY
     [LINEAR] KEY()'), then no explicit primary key is required.

     Maximum number of partitions for NDBCLUSTER tables

     The maximum number of partitions that can defined for a
     'NDBCLUSTER' table when employing user-defined
     partitioning is 8 per node group.  (See
     mysql-cluster-nodes-groups, for more information about NDB
     Cluster node groups.

     DROP PARTITION not supported

     It is not possible to drop partitions from 'NDB'
     tables using 'ALTER TABLE ... DROP PARTITION'.  The
     other partitioning extensions to 'ALTER TABLE'.
     --'ADD PARTITION', 'REORGANIZE PARTITION', and
     'COALESCE PARTITION'--are supported for NDB tables, but use copying
     and so are not optimized.  See
     partitioning-management-range-list and alter-table.

   * Row-based replication

     When using row-based replication with NDB Cluster, binary logging
     cannot be disabled.  That is, the 'NDB'.
     storage engine ignores the value of 'sql_log_bin'.

   * JSON data type

     The MySQL 'JSON' data type is supported for 'NDB'
     tables in the 'mysqld' supplied with NDB 7.5.2 and
     later.

     An 'NDB' table can have a maximum of 3 'JSON' columns.

     The NDB API has no special provision for working with 'JSON' data,
     which it views simply as 'BLOB' data.  Handling data as 'JSON' must
     be performed by the application.

   * CPU and thread info ndbinfo tables

     NDB 7.5.2 adds several new tables to the 'ndbinfo'
     information database providing information
     about CPU and thread activity by node, thread ID, and thread type.
     The tables are listed here:

        * 'cpustat'.: Provides
          per-second, per-thread CPU statistics

        * 'cpustat_50ms'.: Raw
          per-thread CPU statistics data, gathered every 50ms

        * 'cpustat_1sec'.: Raw
          per-thread CPU statistics data, gathered each second

        * 'cpustat_20sec'.:
          Raw per-thread CPU statistics data, gathered every 20 seconds

        * 'threads'.: Names and
          descriptions of thread types

     For more information about these tables, see
     mysql-cluster-ndbinfo.

   * Lock info ndbinfo tables

     NDB 7.5.3 adds new tables to the 'ndbinfo'
     information database providing information
     about locks and lock attempts in a running NDB Cluster.  These
     tables are listed here:

        * 'cluster_locks'.:
          Current lock requests which are waiting for or holding locks;
          this information can be useful when investigating stalls and
          deadlocks.  Analogous to 'cluster_operations'.

        * 'locks_per_fragment'.:
          Counts of lock
          claim requests, and their outcomes per fragment, as well as
          total time spent waiting for locks successfully and
          unsuccessfully.  Analogous to 'operations_per_fragment'
          and
          'memory_per_fragment'.

        * 'server_locks'.:
          Subset of cluster transactions--those running on the local
          'mysqld', showing a connection id per
          transaction.  Analogous to 'server_operations'.

21.1.6.2 Limits and Differences of NDB Cluster from Standard MySQL Limits
.........................................................................

In this section, we list limits found in NDB Cluster that either differ
from limits found in, or that are not found in, standard MySQL.

Memory usage and recovery

Memory consumed when data is inserted into an 'NDB'
table is not automatically recovered when deleted, as it
is with other storage engines.  Instead, the following rules hold true:

   * A 'DELETE' statement on an 'NDB'
     table makes the memory formerly used by the deleted
     rows available for re-use by inserts on the same table only.
     However, this memory can be made available for general re-use by
     performing 'OPTIMIZE TABLE'.

     A rolling restart of the cluster also frees any memory used by
     deleted rows.  See mysql-cluster-rolling-restart.

   * A 'DROP TABLE' or 'TRUNCATE TABLE'
     operation on an 'NDB' table
     frees the memory that was used by this table for re-use by any
     'NDB' table, either by the same table or by
     another 'NDB' table.

     *Note*:

     Recall that 'TRUNCATE TABLE' drops and
     re-creates the table.  See truncate-table.

   * Limits imposed by the cluster's configuration

     A number of hard limits exist which are configurable, but available
     main memory in the cluster sets limits.  See the complete list of
     configuration parameters in mysql-cluster-config-file.
     Most configuration parameters can be upgraded online.  These hard
     limits include:

        * Database memory size and index memory size ('DataMemory' and
          'IndexMemory', respectively).

          'DataMemory' is allocated as 32KB pages.  As each 'DataMemory'
          page is used, it is assigned to a specific table; once
          allocated, this memory cannot be freed except by dropping the
          table.

          See mysql-cluster-ndbd-definition, for more
          information.

        * The maximum number of operations that can be performed per
          transaction is set using the configuration parameters
          'MaxNoOfConcurrentOperations' and 'MaxNoOfLocalOperations'.

          *Note*:

          Bulk loading, see 'TRUNCATE TABLE', and
          'ALTER TABLE' are handled as special cases
          by running multiple transactions, and so are not subject to
          this limitation.

        * Different limits related to tables and indexes.  For example,
          the maximum number of ordered indexes in the cluster is
          determined by 'MaxNoOfOrderedIndexes', and the maximum number
          of ordered indexes per table is 16.

   * Node and data object maximums

     The following limits apply to numbers of cluster nodes and metadata
     objects:

        * The maximum number of data nodes is 48.

          A data node must have a node ID in the range of 1 to 48,
          inclusive.  (Management and API nodes may use node IDs in the
          range 1 to 255, inclusive.)

        * The total maximum number of nodes in an NDB Cluster is 255.
          This number includes all SQL nodes (MySQL Servers), API nodes
          (applications accessing the cluster other than MySQL servers),
          data nodes, and management servers.

        * The maximum number of metadata objects in current versions of
          NDB Cluster is 20320.  This limit is hard-coded.

     See Previous NDB Cluster Issues Resolved in NDB Cluster 7.3
     (http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-limitations-resolved.html),
     for more information.

21.1.6.3 Limits Relating to Transaction Handling in NDB Cluster
...............................................................

A number of limitations exist in NDB Cluster with regard to the handling
of transactions.  These include the following:

   * Transaction isolation level

     The 'NDBCLUSTER' storage engine supports only
     the 'READ COMMITTED' transaction isolation level.  ('InnoDB', for
     example, supports 'READ COMMITTED', 'READ UNCOMMITTED', 'REPEATABLE
     READ', and 'SERIALIZABLE'.)  You should keep in mind that 'NDB'
     implements 'READ COMMITTED' on a per-row basis; when a read request
     arrives at the data node storing the row, what is returned is the
     last committed version of the row at that time.

     Uncommitted data is never returned, but when a transaction
     modifying a number of rows commits concurrently with a transaction
     reading the same rows, the transaction performing the read can
     observe 'before' values, 'after' values, or both, for different
     rows among these, due to the fact that a given row read request can
     be processed either before or after the commit of the other
     transaction.

     To ensure that a given transaction reads only before or after
     values, you can impose row locks using 'SELECT ... LOCK IN SHARE MODE'.
     In such cases, the lock is held until the
     owning transaction is committed.  Using row locks can also cause
     the following issues:

        * Increased frequency of lock wait timeout errors, and reduced
          concurrency

        * Increased transaction processing overhead due to reads
          requiring a commit phase

        * Possibility of exhausting the available number of concurrent
          locks, which is limited by 'MaxNoOfConcurrentOperations'

     'NDB' uses 'READ COMMITTED' for all reads unless a modifier such as
     'LOCK IN SHARE MODE' or 'FOR UPDATE' is used.  'LOCK IN SHARE MODE'
     causes shared row locks to be used; 'FOR UPDATE' causes exclusive
     row locks to be used.  Unique key reads have their locks upgraded
     automatically by 'NDB' to ensure a self-consistent read; 'BLOB'
     reads also employ extra locking for consistency.

     See mysql-cluster-backup-troubleshooting, for information
     on how NDB Cluster's implementation of transaction isolation level
     can affect backup and restoration of 'NDB' databases.

   * Transactions and BLOB or TEXT columns

     'NDBCLUSTER' stores only part of a column
     value that uses any of MySQL's 'BLOB' or 'TEXT'
     data types in the table visible to MySQL; the remainder of
     the 'BLOB' or 'TEXT' is stored in a
     separate internal table that is not accessible to MySQL. This gives
     rise to two related issues of which you should be aware whenever
     executing 'SELECT' statements on tables that contain
     columns of these types:

       1. For any 'SELECT' from an NDB Cluster table: If
          the 'SELECT' includes a 'BLOB' or
          'TEXT' column, the 'READ COMMITTED' transaction
          isolation level is converted to a read with read lock.  This
          is done to guarantee consistency.

       2. For any 'SELECT' which uses a unique key lookup
          to retrieve any columns that use any of the 'BLOB'
          or 'TEXT' data types and that is executed
          within a transaction, a shared read lock is held on the table
          for the duration of the transaction--that is, until the
          transaction is either committed or aborted.

          This issue does not occur for queries that use index or table
          scans, even against 'NDB' tables having
          'BLOB' or 'TEXT' columns.

          For example, consider the table 't' defined by the following
          'CREATE TABLE' statement:

               CREATE TABLE t (
                   a INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
                   b INT NOT NULL,
                   c INT NOT NULL,
                   d TEXT,
                   INDEX i(b),
                   UNIQUE KEY u(c)
               ) ENGINE = NDB,

          Either of the following queries on 't' causes a shared read
          lock, because the first query uses a primary key lookup and
          the second uses a unique key lookup:

               SELECT * FROM t WHERE a = 1;

               SELECT * FROM t WHERE c = 1;

          However, none of the four queries shown here causes a shared
          read lock:

               SELECT * FROM t WHERE b = 1;

               SELECT * FROM t WHERE d = '1';

               SELECT * FROM t;

               SELECT b,c WHERE a = 1;

          This is because, of these four queries, the first uses an
          index scan, the second and third use table scans, and the
          fourth, while using a primary key lookup, does not retrieve
          the value of any 'BLOB' or 'TEXT'.
          columns.

          You can help minimize issues with shared read locks by
          avoiding queries that use unique key lookups that retrieve
          'BLOB' or 'TEXT' columns, or, in
          cases where such queries are not avoidable, by committing
          transactions as soon as possible afterward.

   * Rollbacks

     There are no partial transactions, and no partial rollbacks of
     transactions.  A duplicate key or similar error causes the entire
     transaction to be rolled back.

     This behavior differs from that of other transactional storage
     engines such as 'InnoDB' that may
     roll back individual statements.

   * Transactions and memory usage

     As noted elsewhere in this chapter, NDB Cluster does not handle
     large transactions well; it is better to perform a number of small
     transactions with a few operations each than to attempt a single
     large transaction containing a great many operations.  Among other
     considerations, large transactions require very large amounts of
     memory.  Because of this, the transactional behavior of a number of
     MySQL statements is affected as described in the following list:

        * 'TRUNCATE TABLE' is not transactional
          when used on 'NDB' tables.  If a
          'TRUNCATE TABLE' fails to empty the table,
          then it must be re-run until it is successful.

        * 'DELETE FROM' (even with no 'WHERE' clause) _is_
          transactional.  For tables containing a great many rows, you
          may find that performance is improved by using several 'DELETE
          FROM ... LIMIT ...' statements to 'chunk' the delete
          operation.  If your objective is to empty the table, then you
          may wish to use 'TRUNCATE TABLE'.
          instead.

        * LOAD DATA statements

          'LOAD DATA INFILE' is not transactional when
          used on 'NDB' tables.

          *Important*:

          When executing a 'LOAD DATA INFILE'.
          statement, the 'NDB' engine performs
          commits at irregular intervals that enable better utilization
          of the communication network.  It is not possible to know
          ahead of time when such commits take place.

        * ALTER TABLE and transactions

          When copying an 'NDB' table as part of
          an 'ALTER TABLE', the creation of the copy
          is nontransactional.  (In any case, this operation is rolled
          back when the copy is deleted.)

   * Transactions and the COUNT() function

     When using NDB Cluster Replication, it is not possible to guarantee
     the transactional consistency of the 'COUNT()' function on the
     slave.  In other words, when performing on the master a series of
     statements (see 'INSERT', 'DELETE', or
     both) that changes the number of rows in a table within a single
     transaction, executing 'SELECT COUNT(*) FROM TABLE' queries on the
     slave may yield intermediate results.  This is due to the fact that
     'SELECT COUNT(...)' may perform dirty reads, and is not a bug in
     the 'NDB' storage engine.  (See Bug #31321
     for more information.)

21.1.6.4 NDB Cluster Error Handling
...................................

Starting, stopping, or restarting a node may give rise to temporary
errors causing some transactions to fail.  These include the following
cases:

   * Temporary errors

     When first starting a node, it is possible that you may see Error
     1204 'Temporary failure, distribution changed' and similar
     temporary errors.

   * Errors due to node failure

     The stopping or failure of any data node can result in a number of
     different node failure errors.  (However, there should be no
     aborted transactions when performing a planned shutdown of the
     cluster.)

In either of these cases, any errors that are generated must be handled
within the application.  This should be done by retrying the
transaction.

See also mysql-cluster-limitations-limits.

21.1.6.5 Limits Associated with Database Objects in NDB Cluster
...............................................................

Some database objects such as tables and indexes have different
limitations when using the 'NDBCLUSTER' storage
engine:

   * Database and table names

     When using the 'NDB' storage engine, the maximum allowed length
     both for database names and for table names is 63 characters.  A
     statement using a database name or table name longer than this
     limit fails with an appropriate error.

   * Number of database objects

     The maximum number of _all_ 'NDB' database
     objects in a single NDB Cluster--including databases, tables, and
     indexes--is limited to 20320.

   * Attributes per table

     The maximum number of attributes (that is, columns and indexes)
     that can belong to a given table is 512.

   * Attributes per key

     The maximum number of attributes per key is 32.

   * Row size

     The maximum permitted size of any one row is 14000 bytes.  Each
     'BLOB' or 'TEXT' column contributes 256 +
     8 = 264 bytes to this total.

   * BIT column storage per table

     The maximum combined width for all 'BIT' columns
     used in a given 'NDB' table is 4096.

   * FIXED column storage

     NDB Cluster 7.5 and later supports a maximum of 128 TB per fragment
     of data in 'FIXED' columns.  (Previously, this was 16 GB.)

21.1.6.6 Unsupported or Missing Features in NDB Cluster
.......................................................

A number of features supported by other storage engines are not
supported for 'NDB' tables.  Trying to use any of
these features in NDB Cluster does not cause errors in or of itself;
however, errors may occur in applications that expects the features to
be supported or enforced.  Statements referencing such features, even if
effectively ignored by 'NDB', must be syntactically and otherwise valid.

   * Index prefixes

     Prefixes on indexes are not supported for 'NDB' tables.  If a
     prefix is used as part of an index specification in a statement
     such as 'CREATE TABLE', 'ALTER TABLE',
     or 'CREATE INDEX', the prefix is
     not created by 'NDB'.

     A statement containing an index prefix, and creating or modifying
     an 'NDB' table, must still be syntactically valid.  For example,
     the following statement always fails with Error 1089 'Incorrect
     prefix key; the used key part isn't a string, the used length is
     longer than the key part, or the storage engine doesn't support
     unique prefix keys', regardless of storage engine:

          CREATE TABLE t1 (
              c1 INT NOT NULL,
              _c2 VARCHAR(100),
              INDEX i1 (c2(500))_
          );

     This happens on account of the SQL syntax rule that no index may
     have a prefix larger than itself.

   * Savepoints and rollbacks

     Savepoints and rollbacks to savepoints are ignored as in
     'MyISAM'.

   * Durability of commits

     There are no durable commits on disk.  Commits are replicated, but
     there is no guarantee that logs are flushed to disk on commit.

   * Replication

     Statement-based replication is not supported.  Use
     '--binlog-format=ROW' (or '--binlog-format=MIXED') when setting up
     cluster replication.  See mysql-cluster-replication, for
     more information.

     Replication using global transaction identifiers (GTIDs) is not
     compatible with NDB Cluster, and is not supported in NDB Cluster
     7.5 or NDB CLuster 7.6.  Do not enable GTIDs when using the 'NDB'
     storage engine, as this is very likely to cause problems up to and
     including failure of NDB Cluster Replication.

     Semisynchronous replication is not supported in NDB Cluster.

   * Generated columns

     The 'NDB' storage engine does not support indexes on virtual
     generated columns.

     As with other storage engines, you can create an index on a stored
     generated column, but you should bear in mind that 'NDB' uses
     'DataMemory' for storage of the generated column as well as
     'IndexMemory' for the index.  See
     json-column-indirect-index-mysql-cluster, for an example.

     NDB Cluster writes changes in stored generated columns to the
     binary log, but does log not those made to virtual columns.  This
     should not effect NDB Cluster Replication or replication between
     'NDB' and other MySQL storage engines.

*Note*:

See mysql-cluster-limitations-transactions, for more information
relating to limitations on transaction handling in 'NDB'.

21.1.6.7 Limitations Relating to Performance in NDB Cluster
...........................................................

The following performance issues are specific to or especially
pronounced in NDB Cluster:

   * Range scans

     There are query performance issues due to sequential access to the
     'NDB' storage engine; it is also relatively
     more expensive to do many range scans than it is with either
     'MyISAM' or 'InnoDB'.

   * Reliability of Records in range

     The 'Records in range' statistic is available but is not completely
     tested or officially supported.  This may result in nonoptimal
     query plans in some cases.  If necessary, you can employ 'USE
     INDEX' or 'FORCE INDEX' to alter the execution plan.  See
     index-hints, for more information on how to do this.

   * Unique hash indexes

     Unique hash indexes created with 'USING HASH' cannot be used for
     accessing a table if 'NULL' is given as part of the key.

21.1.6.8 Issues Exclusive to NDB Cluster
........................................

The following are limitations specific to the 'NDB'
storage engine:

   * Machine architecture

     All machines used in the cluster must have the same architecture.
     That is, all machines hosting nodes must be either big-endian or
     little-endian, and you cannot use a mixture of both.  For example,
     you cannot have a management node running on a PowerPC which
     directs a data node that is running on an x86 machine.  This
     restriction does not apply to machines simply running
     'mysql' or other clients that may be accessing the
     cluster's SQL nodes.

   * Binary logging

     NDB Cluster has the following limitations or restrictions with
     regard to binary logging:

        * 'sql_log_bin' has no effect on data operations; however, it is
          supported for schema operations.

        * NDB Cluster cannot produce a binary log for tables having
          'BLOB' columns but no primary key.

        * Only the following schema operations are logged in a cluster
          binary log which is _not_ on the 'mysqld'.
          executing the statement:

             * 'CREATE TABLE'.

             * 'ALTER TABLE'.

             * 'DROP TABLE'.

             * 'CREATE DATABASE'. / see 'CREATE SCHEMA'.

             * 'DROP DATABASE'. / see 'DROP SCHEMA'.

             * 'CREATE TABLESPACE'.

             * 'ALTER TABLESPACE'.

             * 'DROP TABLESPACE'.

             * 'CREATE LOGFILE GROUP'.

             * 'ALTER LOGFILE GROUP'.

             * 'DROP LOGFILE GROUP'.

   * Schema operations (DDL statements) are rejected while any data node
     restarts.

   * Number of replicas

     The number of replicas, as determined by the 'NoOfReplicas' data
     node configuration parameter, is the number of copies of all data
     stored by NDB Cluster.  Setting this parameter to 1 means there is
     only a single copy; in this case, no redundancy is provided, and
     the loss of a data node entails loss of data.  To guarantee
     redundancy, and thus preservation of data even if a data node
     fails, set this parameter to 2, which is the default and
     recommended value in production.

     Setting 'NoOfReplicas' to a value greater than 2 is possible (to a
     maximum of 4) but unnecessary to guard against loss of data.  In
     addition, _values greater than 2 for this parameter are not
     supported in production_.

See also mysql-cluster-limitations-multiple-nodes.

21.1.6.9 Limitations Relating to NDB Cluster Disk Data Storage
..............................................................

Disk Data object maximums and minimums

Disk data objects are subject to the following maximums and minimums:

   * Maximum number of tablespaces: 2^32 (4294967296)

   * Maximum number of data files per tablespace: 2^16 (65536)

   * The minimum and maximum possible sizes of extents for tablespace
     data files are 32K and 2G, respectively.  See
     create-tablespace, for more information.

In addition, when working with NDB Disk Data tables, you should be aware
of the following issues regarding data files and extents:

   * Data files use 'DataMemory'.  Usage is the same as for in-memory
     data.

   * Data files use file descriptors.  It is important to keep in mind
     that data files are always open, which means the file descriptors
     are always in use and cannot be re-used for other system tasks.

   * Extents require sufficient 'DiskPageBufferMemory'; you must reserve
     enough for this parameter to account for all memory used by all
     extents (number of extents times size of extents).

Disk Data tables and diskless mode

Use of Disk Data tables is not supported when running the cluster in
diskless mode.

21.1.6.10 Limitations Relating to Multiple NDB Cluster Nodes
............................................................

Multiple SQL nodes

The following are issues relating to the use of multiple MySQL servers
as NDB Cluster SQL nodes, and are specific to the 'NDBCLUSTER'
storage engine:

   * No distributed table locks

     A 'LOCK TABLES' works only for the SQL node on
     which the lock is issued; no other SQL node in the cluster 'sees'
     this lock.  This is also true for a lock issued by any statement
     that locks tables as part of its operations.  (See next item for an
     example.)

   * ALTER TABLE operations

     'ALTER TABLE' is not fully locking when running
     multiple MySQL servers (SQL nodes).  (As discussed in the previous
     item, NDB Cluster does not support distributed table locks.)

Multiple management nodes

When using multiple management servers:

   * If any of the management servers are running on the same host, you
     must give nodes explicit IDs in connection strings because
     automatic allocation of node IDs does not work across multiple
     management servers on the same host.  This is not required if every
     management server resides on a different host.

   * When a management server starts, it first checks for any other
     management server in the same NDB Cluster, and upon successful
     connection to the other management server uses its configuration
     data.  This means that the management server '--reload' and
     '--initial' startup options are ignored unless the management
     server is the only one running.  It also means that, when
     performing a rolling restart of an NDB Cluster with multiple
     management nodes, the management server reads its own configuration
     file if (and only if) it is the only management server running in
     this NDB Cluster.  See mysql-cluster-rolling-restart, for
     more information.

Multiple network addresses

Multiple network addresses per data node are not supported.  Use of
these is liable to cause problems: In the event of a data node failure,
an SQL node waits for confirmation that the data node went down but
never receives it because another route to that data node remains open.
This can effectively make the cluster inoperable.

*Note*:

It is possible to use multiple network hardware _interfaces_ (such as
Ethernet cards) for a single data node, but these must be bound to the
same address.  This also means that it not possible to use more than one
'[tcp]' section per connection in the 'config.ini' file.  See
mysql-cluster-tcp-definition, for more information.

21.2 NDB Cluster Installation
=============================

This section describes the basics for planning, installing, configuring,
and running an NDB Cluster.  Whereas the examples in
mysql-cluster-configuration provide more in-depth information on a
variety of clustering options and configuration, the result of following
the guidelines and procedures outlined here should be a usable NDB
Cluster which meets the _minimum_ requirements for availability and
safeguarding of data.

For information about upgrading or downgrading an NDB Cluster between
release versions, see mysql-cluster-upgrade-downgrade.

This section covers hardware and software requirements; networking
issues; installation of NDB Cluster; basic configuration issues;
starting, stopping, and restarting the cluster; loading of a sample
database; and performing queries.

NDB Cluster 7.5 and later also provides an NDB Cluster Auto-Installer, a
web-based graphical installer, as part of the NDB Cluster distribution.
The Auto-Installer can be used to perform basic installation and setup
of an NDB Cluster on one (for testing) or more host computers.  See
mysql-cluster-install-auto, for more information.

Assumptions

The following sections make a number of assumptions regarding the
cluster's physical and network configuration.  These assumptions are
discussed in the next few paragraphs.

Cluster nodes and host computers

The cluster consists of four nodes, each on a separate host computer,
and each with a fixed network address on a typical Ethernet network as
shown here:

*Network addresses of nodes in example cluster*

Node                                 IP Address

Management node ('mgmd')             198.51.100.10

SQL node (see 'mysqld')   198.51.100.20

Data node "A" (see 'ndbd'.51.100.30
mysql-cluster-programs-ndbd.)

Data node "B" (see 'ndbd'.51.100.40
mysql-cluster-programs-ndbd.)

This setup is also shown in the following diagram:

FIGURE GOES HERE: NDB Cluster Multi-Computer Setup

Network addressing

In the interest of simplicity (and reliability), this 'How-To' uses only
numeric IP addresses.  However, if DNS resolution is available on your
network, it is possible to use host names in lieu of IP addresses in
configuring Cluster.  Alternatively, you can use the 'hosts' file
(typically '/etc/hosts' for Linux and other Unix-like operating systems,
'C:\WINDOWS\system32\drivers\etc\hosts' on Windows, or your operating
system's equivalent) for providing a means to do host lookup if such is
available.

Potential hosts file issues

A common problem when trying to use host names for Cluster nodes arises
because of the way in which some operating systems (including some Linux
distributions) set up the system's own host name in the '/etc/hosts'
during installation.  Consider two machines with the host names 'ndb1'
and 'ndb2', both in the 'cluster' network domain.  Red Hat Linux
(including some derivatives such as CentOS and Fedora) places the
following entries in these machines' '/etc/hosts' files:

     #  ndb1 /etc/hosts:
     127.0.0.1   ndb1.cluster ndb1 localhost.localdomain localhost

     #  ndb2 /etc/hosts:
     127.0.0.1   ndb2.cluster ndb2 localhost.localdomain localhost

SUSE Linux (including OpenSUSE) places these entries in the machines'
'/etc/hosts' files:

     #  ndb1 /etc/hosts:
     127.0.0.1       localhost
     127.0.0.2       ndb1.cluster ndb1

     #  ndb2 /etc/hosts:
     127.0.0.1       localhost
     127.0.0.2       ndb2.cluster ndb2

In both instances, 'ndb1' routes 'ndb1.cluster' to a loopback IP
address, but gets a public IP address from DNS for 'ndb2.cluster', while
'ndb2' routes 'ndb2.cluster' to a loopback address and obtains a public
address for 'ndb1.cluster'.  The result is that each data node connects
to the management server, but cannot tell when any other data nodes have
connected, and so the data nodes appear to hang while starting.

*Caution*:

You cannot mix 'localhost' and other host names or IP addresses in
'config.ini'.  For these reasons, the solution in such cases (other than
to use IP addresses for _all_ 'config.ini' 'HostName' entries) is to
remove the fully qualified host names from '/etc/hosts' and use these in
'config.ini' for all cluster hosts.

Host computer type

Each host computer in our installation scenario is an Intel-based
desktop PC running a supported operating system installed to disk in a
standard configuration, and running no unnecessary services.  The core
operating system with standard TCP/IP networking capabilities should be
sufficient.  Also for the sake of simplicity, we also assume that the
file systems on all hosts are set up identically.  In the event that
they are not, you should adapt these instructions accordingly.

Network hardware

Standard 100 Mbps or 1 gigabit Ethernet cards are installed on each
machine, along with the proper drivers for the cards, and that all four
hosts are connected through a standard-issue Ethernet networking
appliance such as a switch.  (All machines should use network cards with
the same throughput.  That is, all four machines in the cluster should
have 100 Mbps cards _or_ all four machines should have 1 Gbps cards.)
NDB Cluster works in a 100 Mbps network; however, gigabit Ethernet
provides better performance.

*Important*:

NDB Cluster is _not_ intended for use in a network for which throughput
is less than 100 Mbps or which experiences a high degree of latency.
For this reason (among others), attempting to run an NDB Cluster over a
wide area network such as the Internet is not likely to be successful,
and is not supported in production.

Sample data

We use the 'world' database which is available for download from the
MySQL website (see <http://dev.mysql.com/doc/index-other.html>).  We
assume that each machine has sufficient memory for running the operating
system, required NDB Cluster processes, and (on the data nodes) storing
the database.

For general information about installing MySQL, see installing.
For information about installation of NDB Cluster on Linux and other
Unix-like operating systems, see mysql-cluster-install-linux.
For information about installation of NDB Cluster on Windows operating
systems, see mysql-cluster-install-windows.

For general information about NDB Cluster hardware, software, and
networking requirements, see
mysql-cluster-overview-requirements.

21.2.1 The NDB Cluster Auto-Installer
-------------------------------------

   * mysql-cluster-install-auto-requirements

   * mysql-cluster-install-auto-overview

   * mysql-cluster-install-auto-using

This section describes the web-based graphical configuration installer
included as part of the NDB Cluster distribution.  Topics discussed
include an overview of the installer and its parts, software and other
requirements for running the installer, navigating the GUI, and using
the installer to set up and start or stop an NDB Cluster on one or more
host computers.

21.2.1.1 NDB Cluster Auto-Installer Requirements
................................................

This section provides information on supported operating platforms and
software, required software, and other prerequisites for running the NDB
Cluster Auto-Installer.

Supported platforms

The NDB Cluster Auto-Installer is available with most NDB 7.5.2 and
later NDB Cluster distributions for recent versions of Linux, Windows,
Solaris, and MacOS X. For more detailed information about platform
support for NDB Cluster and the NDB Cluster Auto-Installer, see
<http://www.mysql.com/support/supportedplatforms/cluster.html>.

The NDB Cluster Auto-Installer is not supported with NDB 7.5.0 or 7.5.1
(Bug #79853, Bug #22502247).

Supported Web browsers

The Web-based installer is supported with recent versions of Firefox and
Microsoft Internet Explorer.  It should also work with recent versions
of Opera, Safari, and Chrome, although we have not thoroughly tested for
compability with these browsers.

Required software--setup host

The following software must be installed on the host where the
Auto-Installer is run:

   * Python 2.6 or higher

     The Auto-Installer requires the Python interpreter and standard
     libraries.  If these are not already installed on the system, you
     may be able to add them using the system's package manager.
     Otherwise, they can be downloaded from
     <http://python.org/download/>.

   * Paramiko 1.7.7.1 or higher

     This is required to communicate with remote hosts using SSH. You
     can download it from <http://www.lag.net/paramiko/>.  Paramiko may
     also be available from your system's package manager.

   * Pycrypto version 2.6 or higher

     This cryptography module is required by Paramiko.  If it is not
     available using your system's package manage, you can download it
     from <https://www.dlitz.net/software/pycrypto/>.

All of the software in the preceding list is included in the Windows
version of the configuration tool, and does not need to be installed
separately.

The Paramiko and Pycrypto libraries are required only if you intend to
deploy NDB Cluster nodes on remote hosts, and are not needed if all
nodes are on the same host where the installer is run.

Required software--remote hosts

The only software required for remote hosts where you wish to deploy NDB
Cluster nodes is the SSH server, which is usually installed by default
on Linux and Solaris systems.  Several alternatives are available for
Windows; for an overview of these, see
<http://en.wikipedia.org/wiki/Comparison_of_SSH_servers>.

An additional requirement when using multiple hosts is that it is
possible to authenticate to any of the remote hosts using SSH and the
proper keys or user credentials, as discussed in the next few
paragraphs:

Authentication and security

Three basic security or authentication mechanisms for remote access are
available to the Auto-Installer, which we list and describe here:

   * SSH

     A secure shell connection is used to enable the back end to perform
     actions on remote hosts.  For this reason, an SSH server must be
     running on the remote host.  In addition, the system user running
     the installer must have access to the remote server, either with a
     user name and password, or by using public and private keys.

     *Important*:

     You should never use the system 'root' account for remote access,
     as this is extremely insecure.  In addition, see 'mysqld'
     cannot normally be started by system 'root'.  For these and
     other reasons, you should provide SSH credentials for a regular
     user account on the target system, and not for system 'root'.  For
     more information about this issue, see changing-mysql-user.

   * HTTPS

     Remote communication between the Web browser front end and the back
     end is not encrypted by default, which means that information such
     as the user's SSH password is transmitted in clear text that is
     readable to anyone.  For communication from a remote client to be
     encrypted, the back end must have a certificate, and the front end
     must communicate with the back end using HTTPS rather than HTTP.
     Enabling HTTPS is accomplished most easily through issuing a
     self-signed certificate.  Once the certificate is issued, you must
     make sure that it is used.  You can do this by starting
     'ndb_setup.py' from the
     command line with the '--use-https' and '--cert-file' options.

   * Certificate-based authentication

     The back end 'ndb_setup.py'
     process can execute commands
     on the local host as well as remote hosts.  This means that anyone
     connecting to the back end can take charge of how commands are
     executed.  To reject unwanted connections to the back end, a
     certificate may be required for authentication of the client.  In
     this case, a certificate must be issued by the user, installed in
     the browser, and made available to the back end for authentication
     purposes.  You can enact this requirement (together with or in
     place of password or key authentication) by starting
     'ndb_setup.py' with the
     '--ca-certs-file' option.

There is no need or requirement for secure authentication when the
client browser is running on the same host as the Auto-Installer back
end.

See also mysql-cluster-security, which discusses security
considerations to take into account when deploying NDB Cluster, as well
as security, for more general MySQL security information.

21.2.1.2 NDB Cluster Auto-Installer Overview
............................................

The NDB Cluster Auto-Installer is made up of two components.  The front
end is a GUI client implemented as a Web page that loads and runs in a
standard Web browser such as Firefox or Microsoft Internet Explorer (see
mysql-cluster-install-auto-requirements).  The back end is a
server process (see 'ndb_setup.py')
that runs on the local machine or
on another host to which you have access.

These two components (client and server) communicate with each other
using standard HTTP requests and responses.  The back end can manage NDB
Cluster software programs on any host where the back end user has
granted access.  If the NDB Cluster software is on a different host, the
back end relies on SSH for access, using the Paramiko library for
executing commands remotely (see
mysql-cluster-install-auto-requirements).

The remainder of this section is concerned primarily with the Web
client.  For more information about using the command-line tool, see
mysql-cluster-programs-ndb-setup-py.

NDB Cluster Auto-Installer Interface

This section describes the layout and navigation of the NDB Cluster
Auto-Installer, whose Welcome screen looks similar to what is shown here
when it is first opened in the Web browser:

FIGURE GOES HERE: Welcome Screen For NDB Cluster Auto-Installer

You can access the installer UI by selecting either of the options
*Create New NDB Cluster* or *Continue Previous Cluster Configuration*.
A typical screen in the Auto-Installer includes the following elements:

  1. Display panel

     The central area where data regarding configuration settings and
     controls for changing them are displayed.

  2. Breadcrumb navigation

     Located in the top left and top center of the GUI, the breadcrumb
     navigation bar consists of a series of titles linking to screens
     that correspond to steps in the configuration of an NDB Cluster.
     The breadcrumb allows you to jump between these stages in
     arbritrary order.

  3. Sequential navigation

     This consists of a set of buttons labelled 'Previous', 'Next', and
     'Finished', and can be found in the lower right-hand corner of the
     GUI. The sequential navigation is used to move between steps in the
     suggested order.

  4. Settings and Help menus

     These menus can be found in the top right corner of the GUI (to the
     right of the breadcrumb navigation bar).  'Settings' provides a way
     check and possibly alter configuration settings for the
     Auto-Installer; 'Help' can be used to access the installer's
     built-in help files.

The locations of the elements just described are shown here in a typical
page in the Auto-Installer; the numbers superimposed thereupon
correspond to those used in the preceding list.

FIGURE GOES HERE: Layout of the NDB Cluster Auto-Installer GUI

All of these elements except for the display panel are described in
greater detail in the remainder of this section.  See
mysql-cluster-install-auto-using, describes the panels shown in the
display area as well as the functionality of each panel and the controls
it contains.

Arbitrary and sequential navigation

The Auto-Installer can display any of a number of pages covering
different stages in the setup and configuration of an NDB Cluster
deployment.  You can navigate between pages in either of two ways.  The
first of these is the breadcrumb trail navigation toolbar displaying the
titles of the various pages (in which the title of the current page is
highlighted and disabled).  From these, any desired page, in any desired
order, can be reached by selecting the title of the corresponding page.
This toolbar is shown here:

FIGURE GOES HERE: Detail of NDB Cluster Auto-Installer breadcrumb
navigation, showing page titles/links

The second navigation mechanism provided by the Auto-Installer consists
of the 'Next', 'Previous', and 'Finish' sequential navigation buttons at
the bottom right of the page.  These can be used to move to the next or
previous page in predetermined order, or to go to the very last page.
The buttons are enabled and disabled as needed, so that you cannot, for
example, advance beyond the last page.

Settings and Help menus

These menus are positioned adjacent to one another in the top right
corner of the GUI, as shown earlier in this section.  The 'Settings'
menu is shown here in more detail:

FIGURE GOES HERE: NDB Cluster Auto-Installer Settings menu detail

The entries in the 'Settings' menu are described here, in the following
list:

   * 'Clear configuration and restart': Remove all hosts and processes;
     reset all parameter values to their defaults; start the installer
     over at the first page.

   * 'Automatically save configuration as cookies': Save your
     configuration information--such as host names, process data, and
     parameter values--as a cookie in the browser.  When this option is
     chosen, all information except any SSH password is saved.  This
     means that you can quit and restart the browser, and continue
     working on the same configuration from where you left off at the
     end of the previous session).

     Since the SSH password is never saved, you must supply this once
     again at the beginning of a new session, if one is used.

   * 'Show advanced configuration options': Show advanced configuration
     parameters in the Auto-Installer and make these settable by the
     user.

     Once set, the advanced parameters continue to be used in the
     configuration file until they are explicitly changed or reset.
     This is regardless of whether the advanced parameters are currently
     visible in the installer; in other words, disabling the menu item
     does not reset the values of any of these parameters.

   * 'Automatically get resource information for new hosts': Query new
     hosts automatically for hardware resource information to
     pre-populate a number of configuration options and values.  In this
     case, the suggested values are not mandatory, but they are used
     unless explicitly changed using the appropriate editing options in
     the installer.

As with the installer's navigation elements, one or more of the entries
in the 'Settings' menu may be disabled due to choices you have made
previously.

The 'Help' menu is shown here, as it appears when expanded:

FIGURE GOES HERE: The NDB Cluster Auto-Installer Help menu, expanded

The 'Help' menu provides several options, described in the following
list:

   * 'Contents': Show the built-in user guide.  This is opened in a
     separate browser window, so that it can be used simultaneously with
     the installer without interrupting workflow.

   * 'Current page': Open the built-in user guide to the section
     describing the page currently displayed in the installer.

   * 'About': This will show a small dialog displaying the installer
     name and the version number of the NDB Cluster distribution it was
     supplied with, similar to what is shown here:

     FIGURE GOES HERE: The NDB Cluster Auto-Installer About dialog

The Auto-Installer also provides context-sensitive help in the form of
tooltips for most input widgets.  One of these tooltips is displayed
when the mouse hovers over a widget or the small question mark which can
sometimes appear next to a widget label.

In addition, the names of NDB Cluster configuration parameters are
linked to their descriptions in the online NDB Cluster documentation, so
that if you click on the name of a given parameter, the documentation
for that parameter is shown in a separate window.

21.2.1.3 Using the NDB Cluster Auto-Installer
.............................................

   * mysql-cluster-install-auto-using-starting

   * mysql-cluster-install-auto-using-welcome

   * mysql-cluster-install-auto-using-define-cluster

   * mysql-cluster-install-auto-using-define-hosts

   * mysql-cluster-install-auto-using-define-processes

   * mysql-cluster-install-auto-using-define-attributes

   * mysql-cluster-install-auto-using-deploy-cluster

The NDB Cluster Auto-Installer consists of several pages, each
corresponding to a step in the process used to configure and deploy an
NDB Cluster, and listed here:

   * *Welcome*: Begin using the Auto-Installer by choosing either to
     configure a new NDB Cluster, or to continue configuring an existing
     one.

   * *Define Cluster*: Set basic information about the cluster as a
     whole, such as name, hosts, and load type.  Here you can also set
     the SSH authentication type for accessing remote hosts, if needed.

   * *Define Hosts*: Identify the hosts where you intend to run NDB
     Cluster processes.

   * *Define Processes*: Assign one or more processes of a given type or
     types to each cluster host.

   * *Define Attributes*: Set configuration attributes for processes or
     types of processes.

   * *Deploy Cluster*: Deploy the cluster with the configuration set
     previously; start and stop the deployed cluster.

The following sections describe in greater detail the purpose and
function of each of these pages, in the order just listed.

*Starting the NDB Cluster Auto-Installer*

The Auto-Installer is provided together with the NDB Cluster software.
(See mysql-cluster-installation.)  The present section explains
how to start the installer.  You can do by invoking the
'ndb_setup.py' executable.

*Important*:

You should run the 'ndb_setup.py'
as a normal user; no special
privileges are needed to do so.  You should _not_ run this program as
the 'mysql' user, or using the system 'root' or Administrator account;
doing so may cause the installation to fail.

'ndb_setup.py' is found in
the 'bin' within the NDB Cluster installation directory; a typical
location might be '/usr/local/mysql/bin' on a Linux system or
'C:\Program Files\MySQL\MySQL Server 5.6\bin' on a Windows system, but
this can vary according to where the NDB Cluster software is installed
on your system.

On Windows, you can also start the installer by running 'setup.bat' in
the NDB Cluster installation directory.  When invoked from the command
line, it accepts the same options as does 'ndb_setup.py'.

'ndb_setup.py' can be
started with any of several options that affect its operation, but it is
usually sufficient to allow the default settings be used, in which case
you can start 'ndb_setup.py'.
by either of the following two methods:

  1. Navigate to the NDB Cluster 'bin' directory in a terminal and
     invoke it from the command line, without any additional arguments
     or options, like this:

          shell> ndb_setup

     This works regardless of operating platform.

  2. Navigate to the NDB Cluster 'bin' directory in a file browser (such
     Windows Explorer on Windows, or Konqueror, Dolphin, or Nautilus on
     Linux) and activate (usually by double-clicking) the 'ndb_setup.py'
     file icon.  This works on Windows, and should work with most common
     Linux desktops as well.

     On Windows, you can also navigate to the NDB Cluster installation
     directory and activate the 'setup.bat' file icon.

In either case, once 'ndb_setup.py'
is invoked, the Auto-Installer's
*Welcome* screen should open in the system's default Web browser.

In some cases, you may wish to use non-default settings for the
installer, such as specifying a different port for the Auto-Installer's
included Web server to run on, in which case you must invoke
'ndb_setup.py' with one or more
startup options with values overriding the necessary defaults.  The same
startup options can be used on Windows systems with the 'setup.bat' file
supplied for such platforms in the NDB Cluster software distribution.
This can be done using the command line, but if you want or need to
start the installer from a desktop or file browser while emplying one or
more of these options, it is also possible to create a script or batch
file containing the proper invocation, then to double-click its file
icon in the file browser to start the installer.  (On Linux systems, you
might also need to make the script file executable first.)  For
information about advanced startup options for the NDB Cluster
Auto-Installer, see mysql-cluster-programs-ndb-setup-py.

*NDB Cluster Auto-Installer Welcome Screen*

The *Welcome* screen is loaded in the default browser when
'ndb_setup.py' is invoked, as
shown here:

FIGURE GOES HERE: The NDB Cluster Auto-Installer Welcome screen
(Closeup)

This screen provides the following two choices for entering the
installer, one of which must be selected to continue:

  1. 'Create New NDB Cluster': Start the Auto-Installer with a
     completely new cluster to be set up and deployed.

  2. 'Continue Previous Cluster Configuration': Start the Auto-Installer
     at the same point where the previous session ended, with all
     previous settings preserved.

The second option requires that the browser be able to access its
cookies from the previous session, as these provide the mechanism by
which configuration and other information generated during a session is
stored.  In other words, to continue the previous session with the
Auto-Installer, you must use the same web browser running on the same
host as you did for the previous session.

*NDB Cluster Auto-Installer Define Cluster Screen*

The *Define Cluster* screen is the first screen to appear following the
choice made in the *Welcome* screen, and is used for setting general
properties of the cluster.  The layout of the *Define Cluster* screen is
shown here:

FIGURE GOES HERE: The NDB Cluster Auto-Installer Define Cluster screen

The *Define Cluster* screen allows you to set a number of general
properties for the cluster, as described in this list:

   * 'Cluster name': A name that identifies the cluster.  The default is
     'MyCluster'.

   * 'Host list': A comma-delimited list of one or more hosts where
     cluster processes should run.  By default, this is '127.0.0.1'.  If
     you add remote hosts to the list, you must be able to connect to
     them using the 'SSH Credentials' supplied.

   * 'Application type': Choose one of the following:

       1. 'Simple testing': Minimal resource usage for small-scale
          testing.  This the default.  _Not intended for production
          environments_.

       2. 'Web': Maximize performance for the given hardware.

       3. 'Real-time': Maximize performance while maximizing sensitivity
          to timeouts in order to minimize the time needed to detect
          failed cluster processes.

   * 'Write load': Choose a level for the anticipated number of writes
     for the cluster as a whole.  You can choose any one of the
     following levels:

       1. 'Low': The expected load includes fewer than 100 write
          transactions for second.

       2. 'Medium': The expected load includes 100 to 1000 write
          transactions per second.

       3. 'High': The expected load includes more than 1000 write
          transactions per second.

   * 'SSH Credentials': Choose 'Key-Based SSH' or enter 'User' and
     'Password' credentials.  The SSH key or a user name with password
     is required for connecting to any remote hosts specified in the
     'Host list'.  By default, 'Key-Based SSH' is selected, and the
     'User' and 'Password' fileds are blank.

*NDB Cluster Auto-Installer Define Hosts Screen*

The *Define Hosts* screen, shown here, provides a means of viewing and
specifying several key properties of each cluster host:

FIGURE GOES HERE: NDB Cluster Define Hosts screen

The hosts currently entered are displayed in the grid with various
pieces of information.  You can add hosts by clicking the 'Add hosts'
button and entering a list of one or more comma-separated host names, IP
addresses, or both (as when editing the host list on the *Define
Cluster* screen).

Similarly, you can remove one or more hosts using the button labelled
'Remove selected host(s)'.  When you remove a host in this fashion, any
process which was configured for that host is also removed.

If 'Automatically get resource information for new hosts' is checked in
the 'Settings' menu, the
Auto-Installer attempts to retrieve the platform name, amount of memory,
and number of CPU cores and to fill these in automatically.  The status
of this is displayed in the _Resource info_ column.  Fetching the
information from remote hosts is not instantaneous and may take some
time, particularly from remote hosts running Windows.

If the SSH user credentials on the _Define Cluster_ screen are changed,
the tool tries to refresh the hardware information from any hosts for
which information is missing.  However, if a given field has already
been edited, the user-supplied information is _not_ overwritten by any
value fetched from that host.

The hardware resource information, platform name, installation
directory, and data directory can be edited by the user by clicking the
corresponding cell in the grid, by selecting one or more hosts and
clicking the button labelled 'Edit selected host(s)'.  This causes a
dialog box to appear, in which these fields can be edited, as shown
here:

FIGURE GOES HERE: NDB Cluster Auto-Installer Edit Hosts dialog

When more than one host is selected, any edited values are applied to
all selected hosts.

*NDB Cluster Auto-Installer Define Processes Screen*

The *Define Processes* screen, shown here, provides a way to assign NDB
Cluster processes (nodes) to cluster hosts:

FIGURE GOES HERE: NDB Cluster Auto-Installer Define Processes dialog

The left-hand portion of this screen contains a process tree showing
cluster hosts and processes set up to run on each one.  On the right is
a panel which displays information about the item currently selected in
the tree.

When this screen is accessed for the first time for a given cluster, a
default set of processes is defined for you, based on the number of
hosts.  If you later return to the *Define Hosts* screen, remove all
hosts, and add new hosts, this also causes a new default set of
processes to be defined.

NDB Cluster processes are of the following types:

   * Management node

     Performs administrative tasks such as stopping individual data
     nodes, querying node and cluster status, and making backups.
     Executable: 'ndb_mgmd'.

   * Single-threaded data node

     Stores data and executes queries.  Executable: 'ndbd'.

   * Multi threaded data node

     Stores data and executes queries with multiple worker threads
     executing in parallel.  Executable: 'ndbmtd'.

   * SQL node

     MySQL server for executing SQL queries against 'NDB'.
     Executable: 'mysqld'.

   * API node

     A client accessing data in 'NDB' by means of
     the NDB API or other low-level client API, rather than by using
     SQL. See MySQL NDB Cluster API Developer Guide
     (http://dev.mysql.com/doc/ndbapi/en/), for more information.

For more information about process (node) types, see
mysql-cluster-basics.

Processes shown in the tree are numbered sequentially by type, for each
host--for example, 'SQL node 1', 'SQL node 2', and so on--to simplify
identification.

Each management node, data node, or SQL process must be assigned to a
specific host, and is not allowed to run on any other host.  An API node
_may_ be assigned to a single host, but this is not required.  Instead,
you can assign it to the special 'Any host' entry which the tree also
contains in addition to any other hosts, and which acts as a placeholder
for processes that are allowed to run on any host.  _Only API processes
may use this 'Any host' entry_.

Adding processes

To add a new process to a given host, either right-click that host's
entry in the tree, then select the 'Add process' popup when it appears,
or select a host in the process tree, and press the 'Add process' button
below the process tree.  Performing either of these actions opens the
add process dialog, as shown here:

FIGURE GOES HERE: NDB Cluster Auto-Installer Add Process Dialog

Here you can select from among the available process types described
earlier this section; you can also enter an arbitrary process name to
take the place of the suggested value, if desired.

Removing processes

To delete a process, right-click on a process in the tree and select
'delete process' from the pop up menu that appears, or select a process,
then use the 'delete process' button below the process tree.

When a process is selected in the process tree, information about that
process is displayed in the panel to the right of the tree, where you
can change the process name and possibly its type.  _Important_:
Currently, you can change a single-threaded data node (see 'ndbd')
to a multi-threaded data node (see
'ndbmtd'), or the reverse, only; no
other process type changes are allowed.  If you want to make a change
between any other process types, you must delete the original process
first, then add a new process of the desired type.

*NDB Cluster Auto-Installer Define Attributes Screen*

This screen has a layout similar to that of the *Define Processes*
screen, with a process tree at the left.  Unlike that screen's tree, the
*Define Attributes* process tree is organized by process or node type,
with single-threaded and multi-threaded data nodes considered to be of
the same type for this purpose, in groups labelled 'Management Layer',
'Data Layer', 'SQL Layer', and 'API Layer'.  A panel to the right of
this tree displays information regarding the item currently selected.
The *Define Attributes* screen is shown here:

FIGURE GOES HERE: NDB Cluster Auto-Installer Define Attributes screen

A checkbox labelled 'Show advanced configuration' is located below the
process tree.  Checking this box makes advanced options visible in the
information pane.  These options are set and used whether or not they
are visible.

You can edit attributes for a single process by selecting that process
from the tree, or for all processes of the same type in the cluster by
selecting one of the 'Layer' folders.  A per-process value set for a
given attribute overrides any per-group setting for that attribute that
would otherwise apply to the process in question.  An example of such an
information panel (for an SQL process) is shown here:

FIGURE GOES HERE: Define Attributes Detail With SQL Process Attributes

For some of the attributes shown in the information panel, a button
bearing a plus sign is displayed to the right, which means that the
value of this attribute can be overridden.  This '+' button activates an
input widget for the attribute, enabling you to change its value.  When
the value has been overridden, this button changes into a button showing
an 'X', as shown here:

FIGURE GOES HERE: Define Attributes Detail, Overriding Attribute Default
Value

Clicking the 'X' button next to an attribute undoes any changes made to
it; it immediately reverts to the predefined value.

All configuration attributes have predefined values calculated by the
installer, based such factors as host name, node ID, node type, and so
on.  In most cases, these values may be left as they are.  If you are
not familiar with it already, it is highly recommended that you read the
applicable documentation before making changes to any of the attribute
values.  To make finding this information easier, each attribute name
shown in the information panel is linked to its description in the
online NDB Cluster documentation.

*NDB Cluster Auto-Installer Deploy Cluster Screen*

This screen allows you to perform the following tasks:

   * Review process startup commands and configuration files to be
     applied

   * Distribute configuration files by creating any necessary files and
     directories on all cluster hosts--that is, _deploy_ the cluster as
     presently configured

   * Start and stop the cluster

The *Deploy Cluster* screen is shown here:

FIGURE GOES HERE: NDB Cluster Auto-Installer Deploy Cluster
Configuration screen

Like the *Define Attributes* screen, this screens features a process
tree, organized by process type, on the left hand side.  Next to each
process is a status icon whose color indicates the current status of the
process: green if it is running; yellow if it is starting or stopping;
red if the process is stopped.

To the right of the process tree are two information panels, the upper
panel showing the startup command or commands needed to start the
selected process.  (For some processes, more than one command may be
required--for example, if initialization is necessary.)  The lower panel
shows the contents of the configuration file, if any, for the given
process; currently, the management node process is only type of process
having a configuration file.  Other process types are configured using
command-line parameters when starting the process, or by obtaining
configuration information from the management nodes as needed in real
time.

Three buttons are located immediately below the process tree.  These are
labelled as and perform the functions described in the following list:

   * 'Deploy cluster': Verify that the configuration is valid.  Create
     any directories required on the cluster hosts, and distribute the
     configuration files onto the hosts.  A progress bar shows how far
     the deployment has proceeded.

   * 'Start cluster': The cluster is deployed as with 'Deploy cluster',
     after which all cluster processes are started in the correct order.

     Starting these processes may take some time.  If the estimated time
     to completion is too large, the installer provides an opportunity
     to cancel or to continue of the startup procedure.  A progress bar
     indicates the current status of the startup procedure, as shown
     here:

     FIGURE GOES HERE: Progress Bar With Status of Node Startup Process

     The process status icons adjoining the process tree mentioned
     previously also update with the status of each process.

   * 'Stop cluster': After the cluster has been started, you can stop it
     using the this.  As with starting the cluster, cluster shutdown is
     not instantaneous, and may require some time complete.  A progress
     bar, similar to that displayed during cluster startup, shows the
     approximate current status of the cluster shutdown procedure, as do
     the process status icons adjoining the process tree.

The Auto-Installer generates a 'my.cnf' file containing the appropriate
options for each 'mysqld' process in the cluster.

21.2.2 Installation of NDB Cluster on Linux
-------------------------------------------

This section covers installation methods for NDB Cluster on Linux and
other Unix-like operating systems.  While the next few sections refer to
a Linux operating system, the instructions and procedures given there
should be easily adaptable to other supported Unix-like platforms.  For
manual installation and setup instructions specific to Windows systems,
see mysql-cluster-install-windows.

Each NDB Cluster host computer must have the correct executable programs
installed.  A host running an SQL node must have installed on it a MySQL
Server binary (see 'mysqld').  Management nodes require the
management server daemon (see 'ndb_mgmd');
data nodes require the data node
daemon (see 'ndbd' or 'ndbmtd').
It is not necessary to install the
MySQL Server binary on management node hosts and data node hosts.  It is
recommended that you also install the management client (see
'ndb_mgm') on the management server
host.

Installation of NDB Cluster on Linux can be done using precompiled
binaries from Oracle (downloaded as a .tar.gz archive), with RPM
packages (also available from Oracle), or from source code.  All three
of these installation methods are described in the section that follow.

Regardless of the method used, it is still necessary following
installation of the NDB Cluster binaries to create configuration files
for all cluster nodes, before you can start the cluster.  See
mysql-cluster-install-configuration.

21.2.2.1 Installing an NDB Cluster Binary Release on Linux
..........................................................

This section covers the steps necessary to install the correct
executables for each type of Cluster node from precompiled binaries
supplied by Oracle.

For setting up a cluster using precompiled binaries, the first step in
the installation process for each cluster host is to download the binary
archive from the NDB Cluster downloads page
(http://dev.mysql.com/downloads/cluster/).  (For the most recent 64-bit
NDB 7.5 release, this is
'mysql-cluster-gpl-7.5.11-linux-glibc2.12-x86_64.tar.gz'.)  We assume
that you have placed this file in each machine's '/var/tmp' directory.

If you require a custom binary, see installing-development-tree.

*Note*:

After completing the installation, do not yet start any of the binaries.
We show you how to do so following the configuration of the nodes (see
mysql-cluster-install-configuration).

SQL nodes

On each of the machines designated to host SQL nodes, perform the
following steps as the system 'root' user:

  1. Check your '/etc/passwd' and '/etc/group' files (or use whatever
     tools are provided by your operating system for managing users and
     groups) to see whether there is already a 'mysql' group and 'mysql'
     user on the system.  Some OS distributions create these as part of
     the operating system installation process.  If they are not already
     present, create a new 'mysql' user group, and then add a 'mysql'
     user to this group:

          shell> groupadd mysql
          shell> useradd -g mysql -s /bin/false mysql

     The syntax for 'useradd' and 'groupadd' may differ slightly on
     different versions of Unix, or they may have different names such
     as 'adduser' and 'addgroup'.

  2. Change location to the directory containing the downloaded file,
     unpack the archive, and create a symbolic link named 'mysql' to the
     'mysql' directory.

     *Note*:

     The actual file and directory names vary according to the NDB
     Cluster version number.

          shell> cd /var/tmp
          shell> tar -C /usr/local -xzvf mysql-cluster-gpl-7.5.11-linux-glibc2.12-x86_64.tar.gz
          shell> ln -s /usr/local/mysql-cluster-gpl-7.5.11-linux-glibc2.12-x86_64 /usr/local/mysql

  3. Change location to the 'mysql' directory and set up the system
     databases using 'mysqld'. '--initialize' as shown
     here:

          shell> cd mysql
          shell> mysqld --initialize

     This generates a random password for the MySQL 'root' account.  If
     you do _not_ want the random password to be generated, you can
     substitute the '--initialize-insecure' option for '--initialize'.
     In either case, you should review
     data-directory-initialization-mysqld, for additional information
     before performing this step.  See also
     mysql-secure-installation.

     Alternatively, you can change location to the 'mysql' directory and
     run 'mysql_install_db' to create the
     system databases:

          shell> cd mysql
          shell> scripts/mysql_install_db --user=mysql

     However, this method is not recommended, due to the fact that
     'mysql_install_db' is deprecated, and thus
     subject to removal in a future release.

  4. Set the necessary permissions for the MySQL server and data
     directories:

          shell> chown -R root .
          shell> chown -R mysql data
          shell> chgrp -R mysql .

  5. Copy the MySQL startup script to the appropriate directory, make it
     executable, and set it to start when the operating system is booted
     up:

          shell> cp support-files/mysql.server /etc/rc.d/init.d/
          shell> chmod +x /etc/rc.d/init.d/mysql.server
          shell> chkconfig --add mysql.server

     (The startup scripts directory may vary depending on your operating
     system and version--for example, in some Linux distributions, it is
     '/etc/init.d'.)

     Here we use Red Hat's 'chkconfig' for creating links to the startup
     scripts; use whatever means is appropriate for this purpose on your
     platform, such as 'update-rc.d' on Debian.

Remember that the preceding steps must be repeated on each machine where
an SQL node is to reside.

Data nodes

Installation of the data nodes does not require the 'mysqld'
binary.  Only the NDB Cluster data node executable 'ndbd'.
(single-threaded) or 'ndbmtd'.
(multi-threaded) is required.  These
binaries can also be found in the '.tar.gz' archive.  Again, we assume
that you have placed this archive in '/var/tmp'.

As system 'root' (that is, after using 'sudo', 'su root', or your
system's equivalent for temporarily assuming the system administrator
account's privileges), perform the following steps to install the data
node binaries on the data node hosts:

  1. Change location to the '/var/tmp' directory, and extract the
     'ndbd' and 'ndbmtd'
     binaries from the archive into a
     suitable directory such as '/usr/local/bin':

          shell> cd /var/tmp
          shell> tar -zxvf mysql-cluster-gpl-7.5.11-linux-glibc2.12-x86_64.tar.gz
          shell> cd mysql-cluster-gpl-7.5.11-linux-glibc2.12-x86_64
          shell> cp bin/ndbd /usr/local/bin/ndbd
          shell> cp bin/ndbmtd /usr/local/bin/ndbmtd

     (You can safely delete the directory created by unpacking the
     downloaded archive, and the files it contains, from '/var/tmp' once
     'ndb_mgm' and
     'ndb_mgmd' have been copied to
     the executables directory.)

  2. Change location to the directory into which you copied the files,
     and then make both of them executable:

          shell> cd /usr/local/bin
          shell> chmod +x ndb*

The preceding steps should be repeated on each data node host.

Although only one of the data node executables is required to run an NDB
Cluster data node, we have shown you how to install both 'ndbd'
and 'ndbmtd'
in the preceding instructions.  We
recommend that you do this when installing or upgrading NDB Cluster,
even if you plan to use only one of them, since this will save time and
trouble in the event that you later decide to change from one to the
other.

*Note*:

The data directory on each machine hosting a data node is
'/usr/local/mysql/data'.  This piece of information is essential when
configuring the management node.  (See
mysql-cluster-install-configuration.)

Management nodes

Installation of the management node does not require the 'mysqld'
binary.  Only the NDB Cluster management server (see
'ndb_mgmd') is required; you most
likely want to install the management client (see 'ndb_mgm')
as well.  Both of these binaries also
be found in the '.tar.gz' archive.  Again, we assume that you have
placed this archive in '/var/tmp'.

As system 'root', perform the following steps to install
'ndb_mgmd' and 'ndb_mgm'
on the management node host:

  1. Change location to the '/var/tmp' directory, and extract the
     'ndb_mgm' and 'ndb_mgmd'
     from the archive into a suitable
     directory such as '/usr/local/bin':

          shell> cd /var/tmp
          shell> tar -zxvf mysql-cluster-gpl-7.5.11-linux-glibc2.12-x86_64.tar.gz
          shell> cd mysql-cluster-gpl-7.5.11-linux-glibc2.12-x86_64
          shell> cp bin/ndb_mgm* /usr/local/bin

     (You can safely delete the directory created by unpacking the
     downloaded archive, and the files it contains, from '/var/tmp' once
     'ndb_mgm' and
     'ndb_mgmd' have been copied to
     the executables directory.)

  2. Change location to the directory into which you copied the files,
     and then make both of them executable:

          shell> cd /usr/local/bin
          shell> chmod +x ndb_mgm*

In mysql-cluster-install-configuration, we create configuration
files for all of the nodes in our example NDB Cluster.

21.2.2.2 Installing NDB Cluster from RPM
........................................

This section covers the steps necessary to install the correct
executables for each type of NDB Cluster node using RPM packages
supplied by Oracle beginning with NDB 7.5.4.  For information about RPMs
for previous versions of NDB Cluster, see
mysql-cluster-install-linux-rpm-old.

As an alternative to the method described in this section, Oracle
provides MySQL Repositories for NDB Cluster 7.5.6 and later that are
compatible with many common Linux distributions.  Two repostories,
listed here, are available for RPM-based distributions:

   * For distributions using 'yum' or 'dnf', you can use the MySQL Yum
     Repository for NDB Cluster.  See 'Installing MySQL NDB Cluster
     Using the Yum Repository'
     (http://dev.mysql.com/doc/mysql-yum-repo-quick-guide/en/#repo-qg-yum-fresh-cluster-install),
     for instructions and additional information.

   * For SLES, you can use the MySQL SLES Repository for NDB Cluster.
     See 'Installing MySQL NDB Cluster Using the SLES Repository'
     (http://dev.mysql.com/doc/mysql-sles-repo-quick-guide/en/#repo-qg-sles-fresh-cluster-install),
     for instructions and additional information.

RPMs are available for both 32-bit and 64-bit Linux platforms.  The
filenames for these RPMs use the following pattern:

     mysql-cluster-community-data-node-7.5.8-1.el7.x86_64.rpm
     mysql-cluster-LICENSE-COMPONENT-VER-REV.DISTRO.ARCH.rpm

         LICENSE:= {commercial | community}

         COMPONENT: {management-server | data-node | server | client | OTHER---SEE TEXT}

         VER: MAJOR.MINOR.RELEASE

         REV: MAJOR[.MINOR]

         DISTRO: {el6 | el7 | sles12}

         ARCH: {i686 | x86_64}

LICENSE indicates whether the RPM is part of a Commercial or Community
release of NDB Cluster.  In the remainder of this section, we assume for
the examples that you are installing a Community release.

Possible values for COMPONENT, with descriptions, can be found in the
following table:

*Components of the NDB Cluster RPM distribution*

Component                            Description

'auto-installer'                     NDB Cluster Auto Installer
                                     program; see
                                     mysql-cluster-install-auto, for
                                     usage

'client'                             MySQL and 'NDB' client programs;
                                     includes 'mysql'.
                                     client, see 'ndb_mgm'.
                                     client, and other client tools

'common'                             Character set and error message
                                     information needed by the MySQL
                                     server

'data-node'                          'ndbd'
                                     and
                                     'ndbmtd'.
                                     data node binaries

'devel'                              Headers and library files needed
                                     for MySQL client development

'embedded'                           Embedded MySQL server

'embedded-compat'                    Backwards-compatible embedded
                                     MySQL server

'embedded-devel'                     Header and library files for
                                     developing applications for
                                     embedded MySQL

'java'                               JAR files needed for support of
                                     ClusterJ applications

'libs'                               MySQL client libraries

'libs-compat'                        Backwards-compatible MySQL client
                                     libraries

'management-server'                  The NDB Cluster management server
                                     (see 'ndb_mgmd')

'memcached'                          Files needed to support
                                     'ndbmemcache'

'ndbclient'                          'NDB' client library for running
                                     NDB API and MGM API applications
                                     ('libndbclient')

'ndbclient-devel'                    Header and other files needed for
                                     developing NDB API and MGM API
                                     applications

'nodejs'                             Files needed to set up Node.JS
                                     support for NDB Cluster

'server'                             The MySQL server (see 'mysqld')
                                     with 'NDB' storage engine
                                     support included, and associated
                                     MySQL server programs

'test'                               'mysqltest', other MySQL test
                                     programs, and support files

A single bundle ('.tar' file) of all NDB Cluster RPMs for a given
platform and architecture is also available.  The name of this file
follows the pattern shown here:

     mysql-cluster-LICENSE-VER-REV.DISTRO.ARCH.rpm-bundle.tar

You can extract the individual RPM files from this file using 'tar' or
your preferred tool for extracting archives.

The components required to install the three major types of NDB Cluster
nodes are given in the following list:

   * _Management node_: 'management-server'

   * _Data node_: 'data-node'

   * _SQL node_: 'server' and 'common'

In addition, the 'client' RPM should be installed to provide the
'ndb_mgm' management client on at least
one management node.  You may also wish to install it on SQL nodes, to
have 'mysql' and other MySQL client programs available on
these.  We discuss installation of nodes by type later in this section.

VER represents the three-part 'NDB' storage engine version number in
7.5.X format, shown as '7.5.11' in the examples.  'rev' provides the RPM
revision number in MAJOR.MINOR format.  In the examples shown in this
section, we use '1.1' for this value.

The DISTRO (Linux distribution) is one of 'rhel5' (Oracle Linux 5, Red
Hat Enterprise Linux 4 and 5), 'el6' (Oracle Linux 6, Red Hat Enterprise
Linux 6), 'el7' (Oracle Linux 7, Red Hat Enterprise Linux 7), or
'sles12' (SUSE Enterprise Linux 12).  For the examples in this section,
we assume that the host runs Oracle Linux 7, Red Hat Enterprise Linux 7,
or the equivalent ('el7').

ARCH is 'i686' for 32-bit RPMs and 'x86_64' for 64-bit versions.  In the
examples shown here, we assume a 64-bit platform.

The NDB Cluster version number in the RPM file names (shown here as
'7.5.11') can vary according to the version which you are actually
using.  _It is very important that all of the Cluster RPMs to be
installed have the same version number_.  The architecture should also
be appropriate to the machine on which the RPM is to be installed; in
particular, you should keep in mind that 64-bit RPMs ('x86_64') cannot
be used with 32-bit operating systems (use 'i686' for the latter).

Data nodes

On a computer that is to host an NDB Cluster data node it is necessary
to install only the 'data-node' RPM. To do so, copy this RPM to the data
node host, and run the following command as the system root user,
replacing the name shown for the RPM as necessary to match that of the
RPM downloaded from the MySQL website:

     shell> rpm -Uhv mysql-cluster-community-data-node-7.5.11-1.el7.x86_64.rpm

This installs the 'ndbd' and
'ndbmtd' data node binaries in
'/usr/sbin'.  Either of these can be used to run a data node process on
this host.

SQL nodes

Copy the 'server' and 'common' RPMs to each machine to be used for
hosting an NDB Cluster SQL node ('server' requires 'common').  Install
the 'server' RPM by executing the following command as the system root
user, replacing the name shown for the RPM as necessary to match the
name of the RPM downloaded from the MySQL website:

     shell> rpm -Uhv mysql-cluster-community-server-7.5.11-1.el7.x86_64.rpm

This installs the MySQL server binary (see 'mysqld'), with
'NDB' storage engine support, in the '/usr/sbin' directory.  It also
installs all needed MySQL Server support files and useful MySQL server
programs, including the 'mysql.server' and
'mysqld_safe' startup scripts (in '/usr/share/mysql' and
'/usr/bin', respectively).  The RPM installer should take care of
general configuration issues (such as creating the 'mysql' user and
group, if needed) automatically.

*Important*:

You must use the versions of these RPMs released for NDB Cluster ; those
released for the standard MySQL server do not provide support for the
'NDB' storage engine.

To administer the SQL node (MySQL server), you should also install the
'client' RPM, as shown here:

     shell> rpm -Uhv mysql-cluster-community-client-7.5.11-1.el7.x86_64.rpm

This installs the 'mysql' client and other MySQL client
programs, such as 'mysqladmin' and 'mysqldump',
to '/usr/bin'.

Management nodes

To install the NDB Cluster management server, it is necessary only to
use the 'management-server' RPM. Copy this RPM to the computer intended
to host the management node, and then install it by running the
following command as the system root user (replace the name shown for
the RPM as necessary to match that of the 'management-server' RPM
downloaded from the MySQL website):

     shell> rpm -Uhv mysql-cluster-commercial-management-server-7.5.11-1.el7.x86_64.rpm

This RPM installs the management server binary 'ndb_mgmd'
in the '/usr/sbin' directory.  While
this is the only program actually required for running a management
node, it is also a good idea to have the 'ndb_mgm'.
NDB Cluster management client available
as well.  You can obtain this program, as well as other 'NDB' client
programs such as 'ndb_desc' and
'ndb_config', by installing the
'client' RPM as described previously.

*Note*:

Previously, see 'ndb_mgm' was
installed by the same RPM used to install the management server.  In NDB
7.5.4 and later, all 'NDB' client programs are obtained from the same
'client' RPM that installs 'mysql' and other MySQL
clients.

See linux-installation-rpm, for general information about
installing MySQL using RPMs supplied by Oracle.

After installing from RPM, you still need to configure the cluster; see
mysql-cluster-install-configuration, for the relevant
information.

Installation using old-style RPMs (NDB 7.5.3 and earlier)

_The information in the remainder of this section applies only to NDB
7.5.3 and earlier_, and provides the steps necessary to install the
correct executables for each type of NDB Cluster node using 'old-style'
RPM packages as supplied by Oracle prior to NDB 7.5.4.  The filenames
for these 'old-style' RPMs use the following pattern:

     MySQL-Cluster-COMPONENT-PRODUCTTYPE-NDBVERSION-REVISION.DISTRIBUTION.ARCHITECTURE.rpm

     COMPONENT:= {server | client [| OTHER]}

     PRODUCTTYPE:= {gpl | advanced}

     NDBVERSION:= MAJOR.MINOR.RELEASE

     DISTRIBUTION:= {sles11 | rhel5 | el6}

     ARCHITECTURE:= {i386 | x86_64}

The COMPONENT can be 'server' or 'client'.  (Other values are possible,
but since only the 'server' and 'client' components are required for a
working NDB Cluster installation, we do not discuss them here.)  The
PRODUCTTYPE for Community RPMs downloaded from
<http://dev.mysql.com/downloads/cluster/> is always 'gpl'; 'advanced' is
used to indicate commercial releases.  NDBVERSION represents the
three-part 'NDB' storage engine version number in 7.5.X format; we use
'7.5.3' throughout the rest of this section.  The RPM REVISION is shown
as '1' in the examples following.  The DISTRIBUTION can be one of
'sles12' (SUSE Enterprise Linux 12), 'rhel6' (Oracle Linux 6, Red Hat
Enterprise Linux 6), or 'el7' (Oracle Linux 7, Red Hat Enterprise Linux
7).  The ARCHITECTURE is 'i386' for 32-bit RPMs and 'x86_64' for 64-bit
versions.

For an NDB Cluster, one and possibly two RPMs are required:

   * The 'server' RPM (for example,
     'MySQL-Cluster-server-gpl-7.5.3-1.sles11.i386.rpm'), which supplies
     the core files needed to run a MySQL Server with
     'NDBCLUSTER' storage engine support (that is, as an
     NDB Cluster SQL node) as well as all NDB Cluster executables,
     including the management node, data node, and 'ndb_mgm'
     client binaries.  This RPM is
     always required for installing NDB Cluster.

   * If you do not have your own client application capable of
     administering a MySQL server, you should also obtain and install
     the 'client' RPM (for example,
     'MySQL-Cluster-client-gpl-7.5.3-1.sles11.i386.rpm'), which supplies
     the 'mysql' client

_It is very important that all of the Cluster RPMs to be installed have
the same version number_.  The ARCHITECTURE designation should also be
appropriate to the machine on which the RPM is to be installed; in
particular, you should keep in mind that 64-bit RPMs cannot be used with
32-bit operating systems.

Data nodes

On a computer that is to host a cluster data node it is necessary to
install only the 'server' RPM. To do so, copy this RPM to the data node
host, and run the following command as the system root user, replacing
the name shown for the RPM as necessary to match that of the RPM
downloaded from the MySQL website:

     shell> rpm -Uhv MySQL-Cluster-server-gpl-7.5.11-1.sles11.i386.rpm

Although this installs all NDB Cluster binaries, only the program
'ndbd' or 'ndbmtd'.
(both in '/usr/sbin') is actually needed
to run an NDB Cluster data node.

SQL nodes

On each machine to be used for hosting a cluster SQL node, install the
'server' RPM by executing the following command as the system root user,
replacing the name shown for the RPM as necessary to match the name of
the RPM downloaded from the MySQL website:

     shell> rpm -Uhv MySQL-Cluster-server-gpl-7.5.11-1.sles11.i386.rpm

This installs the MySQL server binary (see 'mysqld') with
'NDB' storage engine support in the '/usr/sbin'
directory, as well as all needed MySQL Server support files.  It also
installs the 'mysql.server' and
'mysqld_safe' startup scripts (in '/usr/share/mysql' and
'/usr/bin', respectively).  The RPM installer should take care of
general configuration issues (such as creating the 'mysql' user and
group, if needed) automatically.

To administer the SQL node (MySQL server), you should also install the
'client' RPM, as shown here:

     shell> rpm -Uhv MySQL-Cluster-client-gpl-7.5.11-1.sles11.i386.rpm

This installs the 'mysql' client program.

Management nodes

To install the NDB Cluster management server, it is necessary only to
use the 'server' RPM. Copy this RPM to the computer intended to host the
management node, and then install it by running the following command as
the system root user (replace the name shown for the RPM as necessary to
match that of the 'server' RPM downloaded from the MySQL website):

     shell> rpm -Uhv MySQL-Cluster-server-gpl-7.3.22-1.sles11.i386.rpm

Although this RPM installs many other files, only the management server
binary 'ndb_mgmd'. (in the
'/usr/sbin' directory) is actually required for running a management
node.  The 'server' RPM also installs 'ndb_mgm',
the 'NDB'.
management client.

See linux-installation-rpm, for general information about
installing MySQL using RPMs supplied by Oracle.  See
mysql-cluster-install-configuration, for information about required
post-installation configuration.

21.2.2.3 Installing NDB Cluster Using .deb Files
................................................

The section provides information about installing NDB Cluster on Debian
and related Linux distributions such Ubuntu using the '.deb' files
supplied by Oracle for this purpose.

For NDB Cluster 7.5.6 and later, Oracle also provides an APT repository
for Debian and other distributions.  See 'Installing MySQL NDB Cluster
Using the APT Repository'
(http://dev.mysql.com/doc/mysql-apt-repo-quick-guide/en/#repo-qg-apt-cluster-install),
for instructions and additional information.

Oracle provides '.deb' installer files for NDB Cluster 7.5 for 32-bit
and 64-bit platforms.  For a Debian-based system, only a single
installer file is necessary.  This file is named using the pattern shown
here, according to the applicable NDB Cluster version, Debian version,
and architecture:

     mysql-cluster-gpl-NDBVER-debianDEBIANVER-ARCH.deb

Here, NDBVER is the 3-part 'NDB' engine version number, DEBIANVER is the
major version of Debian ('8' or '9'), and ARCH is one of 'i686' or
'x86_64'.  In the examples that follow, we assume you wish to install
NDB 7.5.11 on a 64-bit Debian 9 system; in this case, the installer file
is named 'mysql-cluster-gpl-7.5.11-debian9-x86_64.deb-bundle.tar'.

Once you have downloaded the appropriate '.deb' file, you can untar it,
and then install it from the command line using 'dpkg', like this:

     shell> dpkg -i mysql-cluster-gpl-7.5.11-debian9-i686.deb

You can also remove it using 'dpkg' as shown here:

     shell> dpkg -r mysql

The installer file should also be compatible with most graphical package
managers that work with '.deb' files, such as 'GDebi' for the Gnome
desktop.

The '.deb' file installs NDB Cluster under '/opt/mysql/server-VERSION/',
where VERSION is the 2-part release series version for the included
MySQL server.  For NDB 7.5, this is always '5.7'.  The directory layout
is the same as that for the generic Linux binary distribution (see
binary-installation-layout), with the exception that startup scripts
and configuration files are found in 'support-files' instead of 'share'.
All NDB Cluster executables, such as 'ndb_mgm',
see 'ndbd',
and 'ndb_mgmd',
are placed in the 'bin' directory.

21.2.2.4 Building NDB Cluster from Source on Linux
..................................................

This section provides information about compiling NDB Cluster on Linux
and other Unix-like platforms.  Building NDB Cluster from source is
similar to building the standard MySQL Server, although it differs in a
few key respects discussed here.  For general information about building
MySQL from source, see source-installation.  For information
about compiling NDB Cluster on Windows platforms, see
mysql-cluster-install-windows-source.

Building NDB Cluster requires using the NDB Cluster sources.  These are
available from the NDB Cluster downloads page at
<http://dev.mysql.com/downloads/cluster/>.  The archived source file
should have a name similar to 'mysql-cluster-gpl-7.5.11.tar.gz'.  You
can also obtain MySQL development sources from <launchpad.net>.
_Building NDB Cluster from standard MySQL Server 5.7 sources is not
supported_.

The 'WITH_NDBCLUSTER_STORAGE_ENGINE' option for 'CMake' causes the
binaries for the management nodes, data nodes, and other NDB Cluster
programs to be built; it also causes 'mysqld' to be
compiled with 'NDB' storage engine support.  This
option (or its alias 'WITH_NDBCLUSTER') is required when building NDB
Cluster.

*Important*:

The 'WITH_NDB_JAVA' option is enabled by default.  This means that, by
default, if 'CMake' cannot find the location of Java on your system, the
configuration process fails; if you do not wish to enable Java and
ClusterJ support, you must indicate this explicitly by configuring the
build using '-DWITH_NDB_JAVA=OFF'.  Use 'WITH_CLASSPATH' to provide the
Java classpath if needed.

For more information about 'CMake' options specific to building NDB
Cluster, see Options for Compiling NDB Cluster.

After you have run 'make && make install' (or your system's equivalent),
the result is similar to what is obtained by unpacking a precompiled
binary to the same location.

Management nodes

When building from source and running the default 'make install', the
management server and management client binaries (see 'ndb_mgmd'
and 'ndb_mgm')
can be found in '/usr/local/mysql/bin'.
Only 'ndb_mgmd' is required to
be present on a management node host; however, it is also a good idea to
have 'ndb_mgm' present on the
same host machine.  Neither of these executables requires a specific
location on the host machine's file system.

Data nodes

The only executable required on a data node host is the data node binary
'ndbd' or 'ndbmtd'.
(see 'mysqld', for example,
does not have to be present on the host machine.)  By default, when
building from source, this file is placed in the directory
'/usr/local/mysql/bin'.  For installing on multiple data node hosts,
only 'ndbd' or 'ndbmtd'
need be copied to the other host machine
or machines.  (This assumes that all data node hosts use the same
architecture and operating system; otherwise you may need to compile
separately for each different platform.)  The data node binary need not
be in any particular location on the host's file system, as long as the
location is known.

When compiling NDB Cluster from source, no special options are required
for building multi-threaded data node binaries.  Configuring the build
with 'NDB' storage engine support causes
'ndbmtd' to be built automatically;
'make install' places the 'ndbmtd'.
binary in the installation 'bin' directory along with 'mysqld',
see 'ndbd', and 'ndb_mgm'.

SQL nodes

If you compile MySQL with clustering support, and perform the default
installation (using 'make install' as the system 'root' user), see
'mysqld' is placed in '/usr/local/mysql/bin'.  Follow the steps
given in source-installation to make 'mysqld'.
ready for use.  If you want to run multiple SQL nodes, you can use a
copy of the same 'mysqld' executable and its associated
support files on several machines.  The easiest way to do this is to
copy the entire '/usr/local/mysql' directory and all directories and
files contained within it to the other SQL node host or hosts, then
repeat the steps from source-installation on each machine.  If
you configure the build with a nondefault 'PREFIX' option, you must
adjust the directory accordingly.

In mysql-cluster-install-configuration, we create configuration
files for all of the nodes in our example NDB Cluster.

21.2.3 Installing NDB Cluster on Windows
----------------------------------------

This section describes installation procedures for NDB Cluster on
Windows hosts.  NDB Cluster 7.5 binaries for Windows can be obtained
from <http://dev.mysql.com/downloads/cluster/>.  For information about
installing NDB Cluster on Windows from a binary release provided by
Oracle, see mysql-cluster-install-windows-binary.

It is also possible to compile and install NDB Cluster from source on
Windows using Microsoft Visual Studio.  For more information, see
mysql-cluster-install-windows-source.

21.2.3.1 Installing NDB Cluster on Windows from a Binary Release
................................................................

This section describes a basic installation of NDB Cluster on Windows
using a binary 'no-install' NDB Cluster release provided by Oracle,
using the same 4-node setup outlined in the beginning of this section
(see mysql-cluster-installation), as shown in the following
table:

*Network addresses of nodes in example cluster*

Node                                 IP Address

Management node ('mgmd')             198.51.100.10

SQL node (see 'mysqld')   198.51.100.20

Data node "A" (see 'ndbd'.51.100.30
mysql-cluster-programs-ndbd.)

Data node "B" (see 'ndbd'.51.100.40
mysql-cluster-programs-ndbd.)

As on other platforms, the NDB Cluster host computer running an SQL node
must have installed on it a MySQL Server binary (see 'mysqld.exe').
You should also have the MySQL client (see 'mysql.exe')
on this host.  For management nodes and data nodes, it is not
necessary to install the MySQL Server binary; however, each management
node requires the management server daemon (see 'ndb_mgmd.exe');
each data node requires the data node
daemon (see 'ndbd.exe' or
'ndbmtd.exe').  For this example, we
refer to 'ndbd.exe' as the data node
executable, but you can install 'ndbmtd.exe',
the multi-threaded version of this
program, instead, in exactly the same way.  You should also install the
management client (see 'ndb_mgm.exe')
on the management server host.  This section covers the steps necessary
to install the correct Windows binaries for each type of NDB Cluster
node.

*Note*:

As with other Windows programs, NDB Cluster executables are named with
the '.exe' file extension.  However, it is not necessary to include the
'.exe' extension when invoking these programs from the command line.
Therefore, we often simply refer to these programs in this documentation
as 'mysqld', 'mysql', 'ndb_mgmd',
and so on.  You should understand that,
whether we refer (for example) to 'mysqld' or
'mysqld.exe', either name means the same thing (the MySQL Server
program).

For setting up an NDB Cluster using Oracles's 'no-install' binaries, the
first step in the installation process is to download the latest NDB
Cluster Windows ZIP binary archive from
<http://dev.mysql.com/downloads/cluster/>.  This archive has a filename
of the 'mysql-cluster-gpl-VER-winARCH.zip', where VER is the 'NDB'
storage engine version (such as '7.5.11'), and ARCH is the architecture
('32' for 32-bit binaries, and '64' for 64-bit binaries).  For example,
the NDB Cluster 7.5.11 archive for 64-bit Windows systems is named
'mysql-cluster-gpl-7.5.11-win64.zip'.

You can run 32-bit NDB Cluster binaries on both 32-bit and 64-bit
versions of Windows; however, 64-bit NDB Cluster binaries can be used
only on 64-bit versions of Windows.  If you are using a 32-bit version
of Windows on a computer that has a 64-bit CPU, then you must use the
32-bit NDB Cluster binaries.

To minimize the number of files that need to be downloaded from the
Internet or copied between machines, we start with the computer where
you intend to run the SQL node.

SQL node

We assume that you have placed a copy of the archive in the directory
'C:\Documents and Settings\USERNAME\My Documents\Downloads' on the
computer having the IP address 198.51.100.20, where USERNAME is the name
of the current user.  (You can obtain this name using 'ECHO %USERNAME%'
on the command line.)  To install and run NDB Cluster executables as
Windows services, this user should be a member of the 'Administrators'
group.

Extract all the files from the archive.  The Extraction Wizard
integrated with Windows Explorer is adequate for this task.  (If you use
a different archive program, be sure that it extracts all files and
directories from the archive, and that it preserves the archive's
directory structure.)  When you are asked for a destination directory,
enter 'C:\', which causes the Extraction Wizard to extract the archive
to the directory 'C:\mysql-cluster-gpl-VER-winARCH'.  Rename this
directory to 'C:\mysql'.

It is possible to install the NDB Cluster binaries to directories other
than 'C:\mysql\bin'; however, if you do so, you must modify the paths
shown in this procedure accordingly.  In particular, if the MySQL Server
(SQL node) binary is installed to a location other than 'C:\mysql' or
'C:\Program Files\MySQL\MySQL Server 5.7', or if the SQL node's data
directory is in a location other than 'C:\mysql\data' or 'C:\Program
Files\MySQL\MySQL Server 5.7\data', extra configuration options must be
used on the command line or added to the 'my.ini' or 'my.cnf' file when
starting the SQL node.  For more information about configuring a MySQL
Server to run in a nonstandard location, see
windows-install-archive.

For a MySQL Server with NDB Cluster support to run as part of an NDB
Cluster, it must be started with the options '--ndbcluster' and
'--ndb-connectstring'.  While you can specify these options on the
command line, it is usually more convenient to place them in an option
file.  To do this, create a new text file in Notepad or another text
editor.  Enter the following configuration information into this file:

     [mysqld]
     # Options for mysqld process:
     ndbcluster                       # run NDB storage engine
     ndb-connectstring=198.51.100.10  # location of management server

You can add other options used by this MySQL Server if desired (see
windows-create-option-file), but the file must contain the
options shown, at a minimum.  Save this file as 'C:\mysql\my.ini'.  This
completes the installation and setup for the SQL node.

Data nodes

An NDB Cluster data node on a Windows host requires only a single
executable, one of either 'ndbd.exe'.
or 'ndbmtd.exe'.  For this example,
we assume that you are using 'ndbd.exe',
but the same instructions apply when using
'ndbmtd.exe'.  On each computer
where you wish to run a data node (the computers having the IP addresses
198.51.100.30 and 198.51.100.40), create the directories 'C:\mysql',
'C:\mysql\bin', and 'C:\mysql\cluster-data'; then, on the computer where
you downloaded and extracted the 'no-install' archive, locate 'ndbd.exe'
in the 'C:\mysql\bin' directory.  Copy this file to the 'C:\mysql\bin'
directory on each of the two data node hosts.

To function as part of an NDB Cluster, each data node must be given the
address or hostname of the management server.  You can supply this
information on the command line using the '--ndb-connectstring' or '-c'
option when starting each data node process.  However, it is usually
preferable to put this information in an option file.  To do this,
create a new text file in Notepad or another text editor and enter the
following text:

     [mysql_cluster]
     # Options for data node process:
     ndb-connectstring=198.51.100.10  # location of management server

Save this file as 'C:\mysql\my.ini' on the data node host.  Create
another text file containing the same information and save it on as
'C:mysql\my.ini' on the other data node host, or copy the my.ini file
from the first data node host to the second one, making sure to place
the copy in the second data node's 'C:\mysql' directory.  Both data node
hosts are now ready to be used in the NDB Cluster, which leaves only the
management node to be installed and configured.

Management node

The only executable program required on a computer used for hosting an
NDB Cluster management node is the management server program
'ndb_mgmd.exe'.  However, in order to
administer the NDB Cluster once it has been started, you should also
install the NDB Cluster management client program 'ndb_mgm.exe'
on the same machine as the management
server.  Locate these two programs on the machine where you downloaded
and extracted the 'no-install' archive; this should be the directory
'C:\mysql\bin' on the SQL node host.  Create the directory
'C:\mysql\bin' on the computer having the IP address 198.51.100.10, then
copy both programs to this directory.

You should now create two configuration files for use by 'ndb_mgmd.exe':

  1. A local configuration file to supply configuration data specific to
     the management node itself.  Typically, this file needs only to
     supply the location of the NDB Cluster global configuration file
     (see item 2).

     To create this file, start a new text file in Notepad or another
     text editor, and enter the following information:

          [mysql_cluster]
          # Options for management node process
          config-file=C:/mysql/bin/config.ini

     Save this file as the text file 'C:\mysql\bin\my.ini'.

  2. A global configuration file from which the management node can
     obtain configuration information governing the NDB Cluster as a
     whole.  At a minimum, this file must contain a section for each
     node in the NDB Cluster, and the IP addresses or hostnames for the
     management node and all data nodes ('HostName' configuration
     parameter).  It is also advisable to include the following
     additional information:

        * The IP address or hostname of any SQL nodes

        * The data memory and index memory allocated to each data node
          ('DataMemory' and 'IndexMemory' configuration parameters)

        * The number of replicas, using the 'NoOfReplicas' configuration
          parameter (see mysql-cluster-nodes-groups)

        * The directory where each data node stores it data and log
          file, and the directory where the management node keeps its
          log files (in both cases, the 'DataDir' configuration
          parameter)

     Create a new text file using a text editor such as Notepad, and
     input the following information:

          [ndbd default]
          # Options affecting ndbd processes on all data nodes:
          NoOfReplicas=2                      # Number of replicas
          DataDir=C:/mysql/cluster-data       # Directory for each data node's data files
                                              # Forward slashes used in directory path,
                                              # rather than backslashes. This is correct;
                                              # see *Important* note in text
          DataMemory=80M    # Memory allocated to data storage
          IndexMemory=18M   # Memory allocated to index storage
                            # For DataMemory and IndexMemory, we have used the
                            # default values. Since the "world" database takes up
                            # only about 500KB, this should be more than enough for
                            # this example Cluster setup.

          [ndb_mgmd]
          # Management process options:
          HostName=198.51.100.10              # Hostname or IP address of management node
          DataDir=C:/mysql/bin/cluster-logs   # Directory for management node log files

          [ndbd]
          # Options for data node "A":
                                          # (one [ndbd] section per data node)
          HostName=198.51.100.30          # Hostname or IP address

          [ndbd]
          # Options for data node "B":
          HostName=198.51.100.40          # Hostname or IP address

          [mysqld]
          # SQL node options:
          HostName=198.51.100.20          # Hostname or IP address

     Save this file as the text file 'C:\mysql\bin\config.ini'.

*Important*:

A single backslash character ('\') cannot be used when specifying
directory paths in program options or configuration files used by NDB
Cluster on Windows.  Instead, you must either escape each backslash
character with a second backslash ('\\'), or replace the backslash with
a forward slash character ('/').  For example, the following line from
the '[ndb_mgmd]' section of an NDB Cluster 'config.ini' file does not
work:

     DataDir=C:\mysql\bin\cluster-logs

Instead, you may use either of the following:

     DataDir=C:\\mysql\\bin\\cluster-logs  # Escaped backslashes

     DataDir=C:/mysql/bin/cluster-logs     # Forward slashes

For reasons of brevity and legibility, we recommend that you use forward
slashes in directory paths used in NDB Cluster program options and
configuration files on Windows.

21.2.3.2 Compiling and Installing NDB Cluster from Source on Windows
....................................................................

Oracle provides precompiled NDB Cluster binaries for Windows which
should be adequate for most users.  However, if you wish, it is also
possible to compile NDB Cluster for Windows from source code.  The
procedure for doing this is almost identical to the procedure used to
compile the standard MySQL Server binaries for Windows, and uses the
same tools.  However, there are two major differences:

   * To build NDB Cluster, you must use the NDB Cluster sources, which
     you can obtain from <http://dev.mysql.com/downloads/cluster/>.

     Attempting to build NDB Cluster from the source code for the
     standard MySQL Server is likely not to be successful, and is not
     supported by Oracle.

   * You must configure the build using the
     'WITH_NDBCLUSTER_STORAGE_ENGINE' or 'WITH_NDBCLUSTER' option in
     addition to any other build options you wish to use with 'CMake'.
     ('WITH_NDBCLUSTER' is supported as an alias for
     'WITH_NDBCLUSTER_STORAGE_ENGINE', and works in exactly the same
     way.)

*Important*:

The 'WITH_NDB_JAVA' option is enabled by default.  This means that, by
default, if 'CMake' cannot find the location of Java on your system, the
configuration process fails; if you do not wish to enable Java and
ClusterJ support, you must indicate this explicitly by configuring the
build using '-DWITH_NDB_JAVA=OFF'.  (Bug #12379735) Use 'WITH_CLASSPATH'
to provide the Java classpath if needed.

For more information about 'CMake' options specific to building NDB
Cluster, see Options for Compiling NDB Cluster.

Once the build process is complete, you can create a Zip archive
containing the compiled binaries; see installing-source-distribution
provides the commands needed to perform this task on Windows systems.
The NDB Cluster binaries can be found in the 'bin' directory of the
resulting archive, which is equivalent to the 'no-install' archive, and
which can be installed and configured in the same manner.  For more
information, see mysql-cluster-install-windows-binary.

21.2.3.3 Initial Startup of NDB Cluster on Windows
..................................................

Once the NDB Cluster executables and needed configuration files are in
place, performing an initial start of the cluster is simply a matter of
starting the NDB Cluster executables for all nodes in the cluster.  Each
cluster node process must be started separately, and on the host
computer where it resides.  The management node should be started first,
followed by the data nodes, and then finally by any SQL nodes.

  1. On the management node host, issue the following command from the
     command line to start the management node process.  The output
     should appear similar to what is shown here:

          C:\mysql\bin> ndb_mgmd
          2010-06-23 07:53:34 [MgmtSrvr] INFO -- NDB Cluster Management Server. mysql-5.7.22-ndb-7.5.11
          2010-06-23 07:53:34 [MgmtSrvr] INFO -- Reading cluster configuration from 'config.ini'

     The management node process continues to print logging output to
     the console.  This is normal, because the management node is not
     running as a Windows service.  (If you have used NDB Cluster on a
     Unix-like platform such as Linux, you may notice that the
     management node's default behavior in this regard on Windows is
     effectively the opposite of its behavior on Unix systems, where it
     runs by default as a Unix daemon process.  This behavior is also
     true of NDB Cluster data node processes running on Windows.)  For
     this reason, do not close the window in which 'ndb_mgmd.exe'
     is running; doing so kills the
     management node process.  (See
     mysql-cluster-install-windows-service, where we show how to
     install and run NDB Cluster processes as Windows services.)

     The required '-f' option tells the management node where to find
     the global configuration file ('config.ini').  The long form of
     this option is '--config-file'.

     *Important*:

     An NDB Cluster management node caches the configuration data that
     it reads from 'config.ini'; once it has created a configuration
     cache, it ignores the 'config.ini' file on subsequent starts unless
     forced to do otherwise.  This means that, if the management node
     fails to start due to an error in this file, you must make the
     management node re-read 'config.ini' after you have corrected any
     errors in it.  You can do this by starting 'ndb_mgmd.exe'
     with the '--reload' or '--initial'
     option on the command line.  Either of these options works to
     refresh the configuration cache.

     It is not necessary or advisable to use either of these options in
     the management node's 'my.ini' file.

     For additional information about options which can be used with
     'ndb_mgmd', see
     mysql-cluster-programs-ndb-mgmd, as well as
     mysql-cluster-program-options-common.

  2. On each of the data node hosts, run the command shown here to start
     the data node processes:

          C:\mysql\bin> ndbd
          2010-06-23 07:53:46 [ndbd] INFO -- Configuration fetched from 'localhost:1186', generation: 1

     In each case, the first line of output from the data node process
     should resemble what is shown in the preceding example, and is
     followed by additional lines of logging output.  As with the
     management node process, this is normal, because the data node is
     not running as a Windows service.  For this reason, do not close
     the console window in which the data node process is running; doing
     so kills 'ndbd.exe'.  (For more
     information, see mysql-cluster-install-windows-service.)

  3. Do not start the SQL node yet; it cannot connect to the cluster
     until the data nodes have finished starting, which may take some
     time.  Instead, in a new console window on the management node
     host, start the NDB Cluster management client 'ndb_mgm.exe',
     which should be in 'C:\mysql\bin'
     on the management node host.  (Do not try to re-use the console
     window where 'ndb_mgmd.exe'.
     is running by typing 'CTRL'+'C', as this kills the management
     node.)  The resulting output should look like this:

          C:\mysql\bin> ndb_mgm
          -- NDB Cluster -- Management Client --
          ndb_mgm>

     When the prompt 'ndb_mgm>' appears, this indicates that the
     management client is ready to receive NDB Cluster management
     commands.  You can observe the status of the data nodes as they
     start by entering 'ALL STATUS' at the management client prompt.
     This command causes a running report of the data nodes's startup
     sequence, which should look something like this:

          ndb_mgm> ALL STATUS
          Connected to Management Server at: localhost:1186
          Node 2: starting (Last completed phase 3) (mysql-5.7.22-ndb-7.5.11)
          Node 3: starting (Last completed phase 3) (mysql-5.7.22-ndb-7.5.11)

          Node 2: starting (Last completed phase 4) (mysql-5.7.22-ndb-7.5.11)
          Node 3: starting (Last completed phase 4) (mysql-5.7.22-ndb-7.5.11)

          Node 2: Started (version 7.5.11)
          Node 3: Started (version 7.5.11)

          ndb_mgm>

     *Note*:

     Commands issued in the management client are not case-sensitive; we
     use uppercase as the canonical form of these commands, but you are
     not required to observe this convention when inputting them into
     the 'ndb_mgm' client.  For
     more information, see mysql-cluster-mgm-client-commands.

     The output produced by 'ALL STATUS' is likely to vary from what is
     shown here, according to the speed at which the data nodes are able
     to start, the release version number of the NDB Cluster software
     you are using, and other factors.  What is significant is that,
     when you see that both data nodes have started, you are ready to
     start the SQL node.

     You can leave 'ndb_mgm.exe'.
     running; it has no negative impact on the performance of the NDB
     Cluster, and we use it in the next step to verify that the SQL node
     is connected to the cluster after you have started it.

  4. On the computer designated as the SQL node host, open a console
     window and navigate to the directory where you unpacked the NDB
     Cluster binaries (if you are following our example, this is
     'C:\mysql\bin').

     Start the SQL node by invoking 'mysqld.exe' from the
     command line, as shown here:

          C:\mysql\bin> mysqld --console

     The '--console' option causes logging information to be written to
     the console, which can be helpful in the event of problems.  (Once
     you are satisfied that the SQL node is running in a satisfactory
     manner, you can stop it and restart it out without the '--console'
     option, so that logging is performed normally.)

     In the console window where the management client (see
     'ndb_mgm.exe') is running on the
     management node host, enter the 'SHOW' command, which should
     produce output similar to what is shown here:

          ndb_mgm> SHOW
          Connected to Management Server at: localhost:1186
          Cluster Configuration
          ---------------------
          [ndbd(NDB)]     2 node(s)
          id=2    @198.51.100.30  (Version: 5.7.22-ndb-7.5.11, Nodegroup: 0, *)
          id=3    @198.51.100.40  (Version: 5.7.22-ndb-7.5.11, Nodegroup: 0)

          [ndb_mgmd(MGM)] 1 node(s)
          id=1    @198.51.100.10  (Version: 5.7.22-ndb-7.5.11)

          [mysqld(API)]   1 node(s)
          id=4    @198.51.100.20  (Version: 5.7.22-ndb-7.5.11)

     You can also verify that the SQL node is connected to the NDB
     Cluster in the 'mysql' client (see 'mysql.exe')
     using the 'SHOW ENGINE NDB STATUS' statement.

You should now be ready to work with database objects and data using NDB
Cluster 's 'NDBCLUSTER' storage engine.  See
mysql-cluster-install-example-data, for more information and examples.

You can also install 'ndb_mgmd.exe',
see 'ndbd.exe',
and 'ndbmtd.exe'
as Windows services.  For information on
how to do this, see mysql-cluster-install-windows-service).

21.2.3.4 Installing NDB Cluster Processes as Windows Services
.............................................................

Once you are satisfied that NDB Cluster is running as desired, you can
install the management nodes and data nodes as Windows services, so that
these processes are started and stopped automatically whenever Windows
is started or stopped.  This also makes it possible to control these
processes from the command line with the appropriate 'NET START' or 'NET
STOP' command, or using the Windows graphical 'Services' utility.

Installing programs as Windows services usually must be done using an
account that has Administrator rights on the system.

To install the management node as a service on Windows, invoke
'ndb_mgmd.exe' from the command line
on the machine hosting the management node, using the '--install'
option, as shown here:

     C:\> C:\mysql\bin\ndb_mgmd.exe --install
     Installing service 'NDB Cluster Management Server'
       as '"C:\mysql\bin\ndbd.exe" "--service=ndb_mgmd"'
     Service successfully installed.

*Important*:

When installing an NDB Cluster program as a Windows service, you should
always specify the complete path; otherwise the service installation may
fail with the error 'The system cannot find the file specified'.

The '--install' option must be used first, ahead of any other options
that might be specified for 'ndb_mgmd.exe'.
However, it is preferable to specify
such options in an options file instead.  If your options file is not in
one of the default locations as shown in the output of
'ndb_mgmd.exe'. '--help', you can
specify the location using the '--config-file' option.

Now you should be able to start and stop the management server like
this:

     C:\> NET START ndb_mgmd
     The NDB Cluster Management Server service is starting.
     The NDB Cluster Management Server service was started successfully.

     C:\> NET STOP ndb_mgmd
     The NDB Cluster Management Server service is stopping..
     The NDB Cluster Management Server service was stopped successfully.

You can also start or stop the management server as a Windows service
using the descriptive name, as shown here:

     C:\> NET START 'NDB Cluster Management Server'
     The NDB Cluster Management Server service is starting.
     The NDB Cluster Management Server service was started successfully.

     C:\> NET STOP  'NDB Cluster Management Server'
     The NDB Cluster Management Server service is stopping..
     The NDB Cluster Management Server service was stopped successfully.

However, it is usually simpler to specify a short service name or to
permit the default service name to be used when installing the service,
and then reference that name when starting or stopping the service.  To
specify a service name other than 'ndb_mgmd', append it to the
'--install' option, as shown in this example:

     C:\> C:\mysql\bin\ndb_mgmd.exe --install=mgmd1
     Installing service 'NDB Cluster Management Server'
       as '"C:\mysql\bin\ndb_mgmd.exe" "--service=mgmd1"'
     Service successfully installed.

Now you should be able to start or stop the service using the name you
have specified, like this:

     C:\> NET START mgmd1
     The NDB Cluster Management Server service is starting.
     The NDB Cluster Management Server service was started successfully.

     C:\> NET STOP mgmd1
     The NDB Cluster Management Server service is stopping..
     The NDB Cluster Management Server service was stopped successfully.

To remove the management node service, invoke 'ndb_mgmd.exe'
with the '--remove' option, as shown
here:

     C:\> C:\mysql\bin\ndb_mgmd.exe --remove
     Removing service 'NDB Cluster Management Server'
     Service successfully removed.

If you installed the service using a service name other than the
default, you can remove the service by passing this name as the value of
the '--remove' option, like this:

     C:\> C:\mysql\bin\ndb_mgmd.exe --remove=mgmd1
     Removing service 'mgmd1'
     Service successfully removed.

Installation of an NDB Cluster data node process as a Windows service
can be done in a similar fashion, using the '--install' option for
'ndbd.exe'. (or 'ndbmtd.exe'),
as shown here:

     C:\> C:\mysql\bin\ndbd.exe --install
     Installing service 'NDB Cluster Data Node Daemon' as '"C:\mysql\bin\ndbd.exe" "--service=ndbd"'
     Service successfully installed.

Now you can start or stop the data node using either the default service
name or the descriptive name with 'net start' or 'net stop', as shown in
the following example:

     C:\> NET START ndbd
     The NDB Cluster Data Node Daemon service is starting.
     The NDB Cluster Data Node Daemon service was started successfully.

     C:\> NET STOP ndbd
     The NDB Cluster Data Node Daemon service is stopping..
     The NDB Cluster Data Node Daemon service was stopped successfully.

     C:\> NET START 'NDB Cluster Data Node Daemon'
     The NDB Cluster Data Node Daemon service is starting.
     The NDB Cluster Data Node Daemon service was started successfully.

     C:\> NET STOP 'NDB Cluster Data Node Daemon'
     The NDB Cluster Data Node Daemon service is stopping..
     The NDB Cluster Data Node Daemon service was stopped successfully.

To remove the data node service, invoke 'ndbd.exe'
with the '--remove' option, as shown here:

     C:\> C:\mysql\bin\ndbd.exe --remove
     Removing service 'NDB Cluster Data Node Daemon'
     Service successfully removed.

As with 'ndb_mgmd.exe'. (and
'mysqld.exe'), when installing 'ndbd.exe'
as a Windows service, you can also specify
a name for the service as the value of '--install', and then use it when
starting or stopping the service, like this:

     C:\> C:\mysql\bin\ndbd.exe --install=dnode1
     Installing service 'dnode1' as '"C:\mysql\bin\ndbd.exe" "--service=dnode1"'
     Service successfully installed.

     C:\> NET START dnode1
     The NDB Cluster Data Node Daemon service is starting.
     The NDB Cluster Data Node Daemon service was started successfully.

     C:\> NET STOP dnode1
     The NDB Cluster Data Node Daemon service is stopping..
     The NDB Cluster Data Node Daemon service was stopped successfully.

If you specified a service name when installing the data node service,
you can use this name when removing it as well, by passing it as the
value of the '--remove' option, as shown here:

     C:\> C:\mysql\bin\ndbd.exe --remove=dnode1
     Removing service 'dnode1'
     Service successfully removed.

Installation of the SQL node as a Windows service, starting the service,
stopping the service, and removing the service are done in a similar
fashion, using 'mysqld'. '--install', 'NET START', 'NET
STOP', and 'mysqld'. '--remove'.  For additional
information, see windows-start-service.

21.2.4 Initial Configuration of NDB Cluster
-------------------------------------------

In this section, we discuss manual configuration of an installed NDB
Cluster by creating and editing configuration files.

NDB Cluster also provides a GUI installer which can be used to perform
the configuration without the need to edit text files in a separate
application.  For more information, see
mysql-cluster-install-auto.

For our four-node, four-host NDB Cluster (see
mysql-cluster-install-nodes-hosts), it is necessary to write four
configuration files, one per node host.

   * Each data node or SQL node requires a 'my.cnf' file that provides
     two pieces of information: a _connection string_ that tells the
     node where to find the management node, and a line telling the
     MySQL server on this host (the machine hosting the data node) to
     enable the 'NDBCLUSTER' storage engine.

     For more information on connection strings, see
     mysql-cluster-connection-strings.

   * The management node needs a 'config.ini' file telling it how many
     replicas to maintain, how much memory to allocate for data and
     indexes on each data node, where to find the data nodes, where to
     save data to disk on each data node, and where to find any SQL
     nodes.

Configuring the data nodes and SQL nodes

The 'my.cnf' file needed for the data nodes is fairly simple.  The
configuration file should be located in the '/etc' directory and can be
edited using any text editor.  (Create the file if it does not exist.)
For example:

     shell> vi /etc/my.cnf

*Note*:

We show 'vi' being used here to create the file, but any text editor
should work just as well.

For each data node and SQL node in our example setup, 'my.cnf' should
look like this:

     [mysqld]
     # Options for mysqld process:
     ndbcluster                      # run NDB storage engine

     [mysql_cluster]
     # Options for NDB Cluster processes:
     ndb-connectstring=198.51.100.10  # location of management server

After entering the preceding information, save this file and exit the
text editor.  Do this for the machines hosting data node 'A', data node
'B', and the SQL node.

*Important*:

Once you have started a 'mysqld' process with the
'ndbcluster' and 'ndb-connectstring' parameters in the '[mysqld]' and
'[mysql_cluster]' sections of the 'my.cnf' file as shown previously, you
cannot execute any 'CREATE TABLE' or 'ALTER TABLE'
statements without having actually started the
cluster.  Otherwise, these statements will fail with an error.  This is
by design.

Configuring the management node

The first step in configuring the management node is to create the
directory in which the configuration file can be found and then to
create the file itself.  For example (running as 'root'):

     shell> mkdir /var/lib/mysql-cluster
     shell> cd /var/lib/mysql-cluster
     shell> vi config.ini

For our representative setup, the 'config.ini' file should read as
follows:

     [ndbd default]
     # Options affecting ndbd processes on all data nodes:
     NoOfReplicas=2    # Number of replicas
     DataMemory=80M    # How much memory to allocate for data storage
     IndexMemory=18M   # How much memory to allocate for index storage
                       # For DataMemory and IndexMemory, we have used the
                       # default values. Since the "world" database takes up
                       # only about 500KB, this should be more than enough for
                       # this example NDB Cluster setup.
     ServerPort=2202   # This the default value; however, you can use any
                       # port that is free for all the hosts in the cluster
                       # Note1: It is recommended that you do not specify the port
                       # number at all and simply allow the default value to be used
                       # instead
                       # Note2: The port was formerly specified using the PortNumber
                       # TCP parameter; this parameter is no longer available in NDB
                       # Cluster 7.5.

     [ndb_mgmd]
     # Management process options:
     HostName=198.51.100.10          # Hostname or IP address of MGM node
     DataDir=/var/lib/mysql-cluster  # Directory for MGM node log files

     [ndbd]
     # Options for data node "A":
                                     # (one [ndbd] section per data node)
     HostName=198.51.100.30          # Hostname or IP address
     NodeId=2                        # Node ID for this data node
     DataDir=/usr/local/mysql/data   # Directory for this data node's data files

     [ndbd]
     # Options for data node "B":
     HostName=198.51.100.40          # Hostname or IP address
     NodeId=3                        # Node ID for this data node
     DataDir=/usr/local/mysql/data   # Directory for this data node's data files

     [mysqld]
     # SQL node options:
     HostName=198.51.100.20          # Hostname or IP address
                                     # (additional mysqld connections can be
                                     # specified for this node for various
                                     # purposes such as running ndb_restore)

*Note*:

The 'world' database can be downloaded from
<http://dev.mysql.com/doc/index-other.html>.

After all the configuration files have been created and these minimal
options have been specified, you are ready to proceed with starting the
cluster and verifying that all processes are running.  We discuss how
this is done in mysql-cluster-install-first-start.

For more detailed information about the available NDB Cluster
configuration parameters and their uses, see
mysql-cluster-config-file, and mysql-cluster-configuration.
For configuration of NDB Cluster as relates to making backups, see
mysql-cluster-backup-configuration.

*Note*:

The default port for Cluster management nodes is 1186; the default port
for data nodes is 2202.  However, the cluster can automatically allocate
ports for data nodes from those that are already free.

21.2.5 Initial Startup of NDB Cluster
-------------------------------------

Starting the cluster is not very difficult after it has been configured.
Each cluster node process must be started separately, and on the host
where it resides.  The management node should be started first, followed
by the data nodes, and then finally by any SQL nodes:

  1. On the management host, issue the following command from the system
     shell to start the management node process:

          shell> ndb_mgmd -f /var/lib/mysql-cluster/config.ini

     The first time that it is started, see 'ndb_mgmd'
     must be told where to find its
     configuration file, using the '-f' or '--config-file' option.  (See
     mysql-cluster-programs-ndb-mgmd, for details.)

     For additional options which can be used with 'ndb_mgmd',
     see
     mysql-cluster-program-options-common.

  2. On each of the data node hosts, run this command to start the
     'ndbd' process:

          shell> ndbd

  3. If you used RPM files to install MySQL on the cluster host where
     the SQL node is to reside, you can (and should) use the supplied
     startup script to start the MySQL server process on the SQL node.

If all has gone well, and the cluster has been set up correctly, the
cluster should now be operational.  You can test this by invoking the
'ndb_mgm' management node client.
The output should look like that shown here, although you might see some
slight differences in the output depending upon the exact version of
MySQL that you are using:

     shell> ndb_mgm
     -- NDB Cluster -- Management Client --
     ndb_mgm> SHOW
     Connected to Management Server at: localhost:1186
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     2 node(s)
     id=2    @198.51.100.30  (Version: 5.7.22-ndb-7.5.11, Nodegroup: 0, *)
     id=3    @198.51.100.40  (Version: 5.7.22-ndb-7.5.11, Nodegroup: 0)

     [ndb_mgmd(MGM)] 1 node(s)
     id=1    @198.51.100.10  (Version: 5.7.22-ndb-7.5.11)

     [mysqld(API)]   1 node(s)
     id=4    @198.51.100.20  (Version: 5.7.22-ndb-7.5.11)

The SQL node is referenced here as '[mysqld(API)]', which reflects the
fact that the 'mysqld' process is acting as an NDB
Cluster API node.

*Note*:

The IP address shown for a given NDB Cluster SQL or other API node in
the output of 'SHOW' is the address used by the SQL or API node to
connect to the cluster data nodes, and not to any management node.

You should now be ready to work with databases, tables, and data in NDB
Cluster.  See mysql-cluster-install-example-data, for a brief
discussion.

21.2.6 NDB Cluster Example with Tables and Data
-----------------------------------------------

*Note*:

The information in this section applies to NDB Cluster running on both
Unix and Windows platforms.

Working with database tables and data in NDB Cluster is not much
different from doing so in standard MySQL. There are two key points to
keep in mind:

   * For a table to be replicated in the cluster, it must use the
     'NDBCLUSTER' storage engine.  To specify this, use
     the 'ENGINE=NDBCLUSTER' or 'ENGINE=NDB' option when creating the
     table:

          CREATE TABLE TBL_NAME (COL_NAME COLUMN_DEFINITIONS) ENGINE=NDBCLUSTER;

     Alternatively, for an existing table that uses a different storage
     engine, use 'ALTER TABLE' to change the table
     to use 'NDBCLUSTER'.:

          ALTER TABLE TBL_NAME ENGINE=NDBCLUSTER;

   * Every 'NDBCLUSTER' table has a primary key.
     If no primary key is defined by the user when a table is created,
     the 'NDBCLUSTER' storage engine automatically
     generates a hidden one.  Such a key takes up space just as does any
     other table index.  (It is not uncommon to encounter problems due
     to insufficient memory for accommodating these automatically
     created indexes.)

If you are importing tables from an existing database using the output
of 'mysqldump', you can open the SQL script in a text
editor and add the 'ENGINE' option to any table creation statements, or
replace any existing 'ENGINE' options.  Suppose that you have the
'world' sample database on another MySQL server that does not support
NDB Cluster, and you want to export the 'City' table:

     shell> mysqldump --add-drop-table world City > city_table.sql

The resulting 'city_table.sql' file will contain this table creation
statement (and the 'INSERT' statements necessary to
import the table data):

     DROP TABLE IF EXISTS `City`;
     CREATE TABLE `City` (
       `ID` int(11) NOT NULL auto_increment,
       `Name` char(35) NOT NULL default '',
       `CountryCode` char(3) NOT NULL default '',
       `District` char(20) NOT NULL default '',
       `Population` int(11) NOT NULL default '0',
       PRIMARY KEY  (`ID`)
     ) ENGINE=MyISAM DEFAULT CHARSET=latin1;

     INSERT INTO `City` VALUES (1,'Kabul','AFG','Kabol',1780000);
     INSERT INTO `City` VALUES (2,'Qandahar','AFG','Qandahar',237500);
     INSERT INTO `City` VALUES (3,'Herat','AFG','Herat',186800);
     (REMAINING INSERT STATEMENTS OMITTED)

You need to make sure that MySQL uses the 'NDBCLUSTER'
storage engine for this table.  There are two ways that
this can be accomplished.  One of these is to modify the table
definition _before_ importing it into the Cluster database.  Using the
'City' table as an example, modify the 'ENGINE' option of the definition
as follows:

     DROP TABLE IF EXISTS `City`;
     CREATE TABLE `City` (
       `ID` int(11) NOT NULL auto_increment,
       `Name` char(35) NOT NULL default '',
       `CountryCode` char(3) NOT NULL default '',
       `District` char(20) NOT NULL default '',
       `Population` int(11) NOT NULL default '0',
       PRIMARY KEY  (`ID`)
     ) *ENGINE=NDBCLUSTER* DEFAULT CHARSET=latin1;

     INSERT INTO `City` VALUES (1,'Kabul','AFG','Kabol',1780000);
     INSERT INTO `City` VALUES (2,'Qandahar','AFG','Qandahar',237500);
     INSERT INTO `City` VALUES (3,'Herat','AFG','Herat',186800);
     (REMAINING INSERT STATEMENTS OMITTED)

This must be done for the definition of each table that is to be part of
the clustered database.  The easiest way to accomplish this is to do a
search-and-replace on the file that contains the definitions and replace
all instances of 'TYPE=ENGINE_NAME' or 'ENGINE=ENGINE_NAME' with
'ENGINE=NDBCLUSTER'.  If you do not want to modify the file, you can use
the unmodified file to create the tables, and then use 'ALTER TABLE'
to change their storage engine.  The particulars
are given later in this section.

Assuming that you have already created a database named 'world' on the
SQL node of the cluster, you can then use the 'mysql'.
command-line client to read 'city_table.sql', and create and populate
the corresponding table in the usual manner:

     shell> mysql world < city_table.sql

It is very important to keep in mind that the preceding command must be
executed on the host where the SQL node is running (in this case, on the
machine with the IP address '198.51.100.20').

To create a copy of the entire 'world' database on the SQL node, use
'mysqldump' on the noncluster server to export the
database to a file named 'world.sql'; for example, in the '/tmp'
directory.  Then modify the table definitions as just described and
import the file into the SQL node of the cluster like this:

     shell> mysql world < /tmp/world.sql

If you save the file to a different location, adjust the preceding
instructions accordingly.

Running 'SELECT' queries on the SQL node is no different
from running them on any other instance of a MySQL server.  To run
queries from the command line, you first need to log in to the MySQL
Monitor in the usual way (specify the 'root' password at the 'Enter
password:' prompt):

     shell> mysql -u root -p
     Enter password:
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 1 to server version: 5.7.22-ndb-7.5.11

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql>

We simply use the MySQL server's 'root' account and assume that you have
followed the standard security precautions for installing a MySQL
server, including setting a strong 'root' password.  For more
information, see default-privileges.

It is worth taking into account that Cluster nodes do _not_ make use of
the MySQL privilege system when accessing one another.  Setting or
changing MySQL user accounts (including the 'root' account) effects only
applications that access the SQL node, not interaction between nodes.
See mysql-cluster-security-mysql-privileges, for more
information.

If you did not modify the 'ENGINE' clauses in the table definitions
prior to importing the SQL script, you should run the following
statements at this point:

     mysql> USE world;
     mysql> ALTER TABLE City ENGINE=NDBCLUSTER;
     mysql> ALTER TABLE Country ENGINE=NDBCLUSTER;
     mysql> ALTER TABLE CountryLanguage ENGINE=NDBCLUSTER;

Selecting a database and running a 'SELECT' query against a table in
that database is also accomplished in the usual manner, as is exiting
the MySQL Monitor:

     mysql> USE world;
     mysql> SELECT Name, Population FROM City ORDER BY Population DESC LIMIT 5;
     +-----------+------------+
     | Name      | Population |
     +-----------+------------+
     | Bombay    |   10500000 |
     | Seoul     |    9981619 |
     | Sa~o Paulo |    9968485 |
     | Shanghai  |    9696300 |
     | Jakarta   |    9604900 |
     +-----------+------------+
     5 rows in set (0.34 sec)

     mysql> \q
     Bye

     shell>

Applications that use MySQL can employ standard APIs to access
'NDB' tables.  It is important to remember that your
application must access the SQL node, and not the management or data
nodes.  This brief example shows how we might execute the
'SELECT' statement just shown by using the PHP 5.X 'mysqli'
extension running on a Web server elsewhere on the network:

     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
       "http://www.w3.org/TR/html4/loose.dtd">
     <html>
     <head>
       <meta http-equiv="Content-Type"
                content="text/html; charset=iso-8859-1">
       <title>SIMPLE mysqli SELECT</title>
     </head>
     <body>
     <?php
       # connect to SQL node:
       $link = new mysqli('198.51.100.20', 'root', 'ROOT_PASSWORD', 'world');
       # parameters for mysqli constructor are:
       #   host, user, password, database

       if( mysqli_connect_errno() )
         die("Connect failed: " . mysqli_connect_error());

       $query = "SELECT Name, Population
                 FROM City
                 ORDER BY Population DESC
                 LIMIT 5";

       # if no errors...
       if( $result = $link->query($query) )
       {
     ?>
     <table border="1" width="40%" cellpadding="4" cellspacing ="1">
       <tbody>
       <tr>
         <th width="10%">City</th>
         <th>Population</th>
       </tr>
     <?
         # then display the results...
         while($row = $result->fetch_object())
           printf("<tr>\n  <td align=\"center\">%s</td><td>%d</td>\n</tr>\n",
                   $row->Name, $row->Population);
     ?>
       </tbody
     </table>
     <?
       # ...and verify the number of rows that were retrieved
         printf("<p>Affected rows: %d</p>\n", $link->affected_rows);
       }
       else
         # otherwise, tell us what went wrong
         echo mysqli_error();

       # free the result set and the mysqli connection object
       $result->close();
       $link->close();
     ?>
     </body>
     </html>

We assume that the process running on the Web server can reach the IP
address of the SQL node.

In a similar fashion, you can use the MySQL C API, Perl-DBI,
Python-mysql, or MySQL Connectors to perform the tasks of data
definition and manipulation just as you would normally with MySQL.

21.2.7 Safe Shutdown and Restart of NDB Cluster
-----------------------------------------------

To shut down the cluster, enter the following command in a shell on the
machine hosting the management node:

     shell> ndb_mgm -e shutdown

The '-e' option here is used to pass a command to the 'ndb_mgm'
client from the shell.  (See
mysql-cluster-program-options-common, for more information about this
option.)  The command causes the 'ndb_mgm',
see 'ndb_mgmd',
and any 'ndbd'
or 'ndbmtd'
processes to terminate gracefully.  Any
SQL nodes can be terminated using 'mysqladmin shutdown'
and other means.  On Windows platforms, assuming that you
have installed the SQL node as a Windows service, you can use 'NET STOP
MYSQL'.

To restart the cluster on Unix platforms, run these commands:

   * On the management host ('198.51.100.10' in our example setup):

          shell> ndb_mgmd -f /var/lib/mysql-cluster/config.ini

   * On each of the data node hosts ('198.51.100.30' and
     '198.51.100.40'):

          shell> ndbd

   * Use the 'ndb_mgm' client to
     verify that both data nodes have started successfully.

   * On the SQL host ('198.51.100.20'):

          shell> mysqld_safe &

On Windows platforms, assuming that you have installed all NDB Cluster
processes as Windows services using the default service names (see
mysql-cluster-install-windows-service), you can restart the cluster as
follows:

   * On the management host ('198.51.100.10' in our example setup),
     execute the following command:

          C:\> NET START ndb_mgmd

   * On each of the data node hosts ('198.51.100.30' and
     '198.51.100.40'), execute the following command:

          C:\> NET START ndbd

   * On the management node host, use the 'ndb_mgm'
     client to verify that the
     management node and both data nodes have started successfully (see
     mysql-cluster-install-windows-initial-start).

   * On the SQL node host ('198.51.100.20'), execute the following
     command:

          C:\> NET START mysql

In a production setting, it is usually not desirable to shut down the
cluster completely.  In many cases, even when making configuration
changes, or performing upgrades to the cluster hardware or software (or
both), which require shutting down individual host machines, it is
possible to do so without shutting down the cluster as a whole by
performing a _rolling restart_ of the cluster.  For more information
about doing this, see mysql-cluster-rolling-restart.

21.2.8 Upgrading and Downgrading NDB Cluster
--------------------------------------------

This section provides information about NDB Cluster software and table
file compatibility between different NDB Cluster 7.5 releases with
regard to performing upgrades and downgrades as well as compatibility
matrices and notes.  You are expected already to be familiar with
installing and configuring an NDB Cluster prior to attempting an upgrade
or downgrade.  See mysql-cluster-configuration.

*Important*:

Only compatibility between MySQL versions with regard to
'NDBCLUSTER' is taken into account in this section, and
there are likely other issues to be considered.  _As with any other
MySQL software upgrade or downgrade, you are strongly encouraged to
review the relevant portions of the MySQL Manual for the MySQL versions
from which and to which you intend to migrate, before attempting an
upgrade or downgrade of the NDB Cluster software_.  See
upgrading.

The table shown here provides information on NDB Cluster upgrade and
downgrade compatibility among different releases of NDB 7.5.  Additional
notes about upgrades and downgrades to, from, or within the NDB Cluster
7.5 release series can be found following the table.

*Upgrades and Downgrades, NDB Cluster 7.5*

FIGURE GOES HERE: NDB Cluster Upgrade and Downgrade Compatibility, MySQL
NDB Cluster 7.5

Version support

The following versions of NDB Cluster are supported for upgrades to GA
releases of NDB Cluster 7.5 (7.5.4 and later):

   * NDB Cluster 7.4 GA releases (7.4.4 and later)

   * NDB Cluster 7.3 GA releases (7.3.2 and later)

   * NDB Cluster 7.2 GA releases (7.2.4 and later)

Known Issues - NDB 7.5

The following issues are known to occur when upgrading to or between NDB
7.5 releases:

   * When upgrading from NDB 7.5.2 or 7.5.3 to a later version, the use
     of 'mysqld' with the '--initialize' and
     '--ndbcluster' options together caused problems later running
     'mysql_upgrade'.

     When run with '--initialize', the server does not require
     'NDB' support; having 'NDB' enabled at this time
     can cause problems with 'ndbinfo'.
     tables.  To keep this from happening, the '--initialize' option now
     causes 'mysqld' to ignore the '--ndbcluster' option
     if the latter is also specified.

     A workaround for an upgrade that has failed for these reasons can
     be accomplished as follows:

       1. Perform a rolling restart of the entire cluster

       2. Delete all '.frm' files in the 'data/ndbinfo' directory

       3. Run 'mysql_upgrade'.

     (Bug #81689, Bug #82724, Bug #24521927, Bug #23518923)

   * During an online upgrade from an NDB Cluster 7.3 release to an NDB
     7.4 (or later) release, the failures of several data nodes running
     the lower version during local checkpoints (LCPs), and just prior
     to upgrading these nodes, led to additional node failures following
     the upgrade.  This was due to lingering elements of the 'EMPTY_LCP'
     protocol initiated by the older nodes as part of an
     LCP-plus-restart sequence, and which is no longer used in NDB 7.4
     and later due to LCP optimizations implemented in those versions.
     This issue was fixed in NDB 7.5.4.  (Bug #23129433)

   * Beginning with NDB 7.5.2, the 'ndb_binlog_index' table uses the
     'InnoDB' storage engine.  (Use of the
     'MyISAM' storage engine for this table continues to be supported
     for backward compatibility.)

     When upgrading a previous release to NDB 7.5.2 or later, you can
     use the '--force' '--upgrade-system-tables' options with
     'mysql_upgrade' so that it performs 'ALTER TABLE ... ENGINE=INNODB'
     on the 'ndb_binlog_index'
     table.

     For more information, see mysql-cluster-replication-schema.

   * Online upgrades from previous versions of NDB Cluster to NDB 7.5.1
     were not possible due to missing entries in the matrix used to test
     upgrade compatibility between versions.  (Bug #22024947)

     Also in NDB 7.5.1, see 'mysql_upgrade' failed to
     upgrade the 'sys' schema if a 'sys' database directory existed but
     was empty.  (Bug #81352, Bug #23249846, Bug #22875519)

Known issues - NDB 7.6

The following issues are known to occur when upgrading to or between NDB
7.6 releases:

Changes in Disk Data file format

Due to changes in disk format, upgrading to or downgrading from either
of the versions listed here requires an initial node restart of each
data node:

   * NDB 7.6.2

   * NDB 7.6.4

To avoid problems relating to the old format, you should re-create any
existing tablespaces and undo log file groups when upgrading.  You can
do this by performing an initial restart of each data node (that is,
using the '--initial' option) as part of the upgrade process.

If you are using Disk Data tables, a downgrade from _any_ NDB 7.6
release to any NDB 7.5 or earlier release requires that you restart all
data nodes with '--initial' as part of the downgrade process.  This is
because NDB 7.5 and earlier release series are not able to read the new
Disk Data file format.

*Important*:

Upgrading to NDB 7.6.4 or later from an earlier release, or downgrading
from NDB 7.6.4 or later to an earlier release, requires purging then
re-creating the 'NDB' data node file system, which means that each data
node must be restarted using the '--initial' option as part of the
rolling restart or system restart normally required.  (Starting a data
node with no file system is already equivalent to an initial restart; in
such cases, '--initial' is implied and not required.  This is unchanged
from previous releases of NDB Cluster.)

When such a restart is performed as part of an upgrade to NDB 7.6.4 or
later, any existing LCP files are checked for the presence of the LCP
'sysfile', indicating that the existing data node file system was
written using NDB 7.6.4 or later.  If such a node file system exists,
but does not contain the 'sysfile', and if any data nodes are restarted
without the '--initial' option, 'NDB' causes the restart to fail with an
appropriate error message.

You should also be aware that no such protection is possible when
downgrading from NDB 7.6.4 or later to a release previous to to NDB
7.6.4.

21.3 Configuration of NDB Cluster
=================================

A MySQL server that is part of an NDB Cluster differs in one chief
respect from a normal (nonclustered) MySQL server, in that it employs
the 'NDB' storage engine.  This engine is also
referred to sometimes as 'NDBCLUSTER', although
'NDB' is preferred.

To avoid unnecessary allocation of resources, the server is configured
by default with the 'NDB' storage engine disabled.
To enable 'NDB', you must modify the server's
'my.cnf' configuration file, or start the server with the '--ndbcluster'
option.

This MySQL server is a part of the cluster, so it also must know how to
access a management node to obtain the cluster configuration data.  The
default behavior is to look for the management node on 'localhost'.
However, should you need to specify that its location is elsewhere, this
can be done in 'my.cnf', or with the 'mysql' client.
Before the 'NDB' storage engine can be used, at
least one management node must be operational, as well as any desired
data nodes.

For more information about '--ndbcluster' and other 'mysqld'
options specific to NDB Cluster, see
mysql-cluster-program-options-mysqld.

You can use also the NDB Cluster Auto-Installer to set up and deploy an
NDB Cluster on one or more hosts using a browser-based GUI. For more
information, see mysql-cluster-install-auto.

For general information about installing NDB Cluster, see
mysql-cluster-installation.

21.3.1 Quick Test Setup of NDB Cluster
--------------------------------------

To familiarize you with the basics, we will describe the simplest
possible configuration for a functional NDB Cluster.  After this, you
should be able to design your desired setup from the information
provided in the other relevant sections of this chapter.

First, you need to create a configuration directory such as
'/var/lib/mysql-cluster', by executing the following command as the
system 'root' user:

     shell> mkdir /var/lib/mysql-cluster

In this directory, create a file named 'config.ini' that contains the
following information.  Substitute appropriate values for 'HostName' and
'DataDir' as necessary for your system.

     # file "config.ini" - showing minimal setup consisting of 1 data node,
     # 1 management server, and 3 MySQL servers.
     # The empty default sections are not required, and are shown only for
     # the sake of completeness.
     # Data nodes must provide a hostname but MySQL Servers are not required
     # to do so.
     # If you don't know the hostname for your machine, use localhost.
     # The DataDir parameter also has a default value, but it is recommended to
     # set it explicitly.
     # Note: [db], [api], and [mgm] are aliases for [ndbd], [mysqld], and [ndb_mgmd],
     # respectively. [db] is deprecated and should not be used in new installations.

     [ndbd default]
     NoOfReplicas= 1

     [mysqld  default]
     [ndb_mgmd default]
     [tcp default]

     [ndb_mgmd]
     HostName= myhost.example.com

     [ndbd]
     HostName= myhost.example.com
     DataDir= /var/lib/mysql-cluster

     [mysqld]
     [mysqld]
     [mysqld]

You can now start the 'ndb_mgmd'.
management server.  By default, it attempts to read the 'config.ini'
file in its current working directory, so change location into the
directory where the file is located and then invoke 'ndb_mgmd'.:

     shell> cd /var/lib/mysql-cluster
     shell> ndb_mgmd

Then start a single data node by running 'ndbd'.:

     shell> ndbd

For command-line options which can be used when starting 'ndbd',
see
mysql-cluster-program-options-common.

By default, see 'ndbd' looks for the
management server at 'localhost' on port 1186.

*Note*:

If you have installed MySQL from a binary tarball, you will need to
specify the path of the 'ndb_mgmd'
and 'ndbd'
servers explicitly.  (Normally, these will
be found in '/usr/local/mysql/bin'.)

Finally, change location to the MySQL data directory (usually
'/var/lib/mysql' or '/usr/local/mysql/data'), and make sure that the
'my.cnf' file contains the option necessary to enable the NDB storage
engine:

     [mysqld]
     ndbcluster

You can now start the MySQL server as usual:

     shell> mysqld_safe --user=mysql &

Wait a moment to make sure the MySQL server is running properly.  If you
see the notice 'mysql ended', check the server's '.err' file to find out
what went wrong.

If all has gone well so far, you now can start using the cluster.
Connect to the server and verify that the 'NDBCLUSTER'
storage engine is enabled:

     shell> mysql
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 1 to server version: 5.7.23

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql> SHOW ENGINES\G
     ...
     *************************** 12. row ***************************
     Engine: NDBCLUSTER
     Support: YES
     Comment: Clustered, fault-tolerant, memory-based tables
     *************************** 13. row ***************************
     Engine: NDB
     Support: YES
     Comment: Alias for NDBCLUSTER
     ...

The row numbers shown in the preceding example output may be different
from those shown on your system, depending upon how your server is
configured.

Try to create an 'NDBCLUSTER' table:

     shell> mysql
     mysql> USE test;
     Database changed

     mysql> CREATE TABLE ctest (i INT) ENGINE=NDBCLUSTER;
     Query OK, 0 rows affected (0.09 sec)

     mysql> SHOW CREATE TABLE ctest \G
     *************************** 1. row ***************************
            Table: ctest
     Create Table: CREATE TABLE `ctest` (
       `i` int(11) default NULL
     ) ENGINE=ndbcluster DEFAULT CHARSET=latin1
     1 row in set (0.00 sec)

To check that your nodes were set up properly, start the management
client:

     shell> ndb_mgm

Use the 'SHOW' command from within the management client to obtain a
report on the cluster's status:

     ndb_mgm> SHOW
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     1 node(s)
     id=2    @127.0.0.1  (Version: 5.7.22-ndb-7.5.11, Nodegroup: 0, *)

     [ndb_mgmd(MGM)] 1 node(s)
     id=1    @127.0.0.1  (Version: 5.7.22-ndb-7.5.11)

     [mysqld(API)]   3 node(s)
     id=3    @127.0.0.1  (Version: 5.7.22-ndb-7.5.11)
     id=4 (not connected, accepting connect from any host)
     id=5 (not connected, accepting connect from any host)

At this point, you have successfully set up a working NDB Cluster .  You
can now store data in the cluster by using any table created with
'ENGINE=NDBCLUSTER' or its alias 'ENGINE=NDB'.

21.3.2 Overview of NDB Cluster Configuration Parameters, Options, and Variables
-------------------------------------------------------------------------------

The next several sections provide summary tables of NDB Cluster node
configuration parameters used in the 'config.ini' file to govern various
aspects of node behavior, as well as of options and variables read by
'mysqld' from a 'my.cnf' file or from the command line
when run as an NDB Cluster process.  Each of the node parameter tables
lists the parameters for a given type ('ndbd', 'ndb_mgmd', 'mysqld',
'computer', 'tcp', 'shm', or 'sci').  All tables include the data type
for the parameter, option, or variable, as well as its default, mimimum,
and maximum values as applicable.

Considerations when restarting nodes

For node parameters, these tables also indicate what type of restart is
required (node restart or system restart)--and whether the restart must
be done with '--initial'--to change the value of a given configuration
parameter.  When performing a node restart or an initial node restart,
all of the cluster's data nodes must be restarted in turn (also referred
to as a _rolling restart_).  It is possible to update cluster
configuration parameters marked as 'node' online--that is, without
shutting down the cluster--in this fashion.  An initial node restart
requires restarting each 'ndbd'.
process with the '--initial' option.

A system restart requires a complete shutdown and restart of the entire
cluster.  An initial system restart requires taking a backup of the
cluster, wiping the cluster file system after shutdown, and then
restoring from the backup following the restart.

In any cluster restart, all of the cluster's management servers must be
restarted for them to read the updated configuration parameter values.

*Important*:

Values for numeric cluster parameters can generally be increased without
any problems, although it is advisable to do so progressively, making
such adjustments in relatively small increments.  Many of these can be
increased online, using a rolling restart.

However, decreasing the values of such parameters--whether this is done
using a node restart, node initial restart, or even a complete system
restart of the cluster--is not to be undertaken lightly; it is
recommended that you do so only after careful planning and testing.
This is especially true with regard to those parameters that relate to
memory usage and disk space, such as 'MaxNoOfTables',
'MaxNoOfOrderedIndexes', and 'MaxNoOfUniqueHashIndexes'.  In addition,
it is the generally the case that configuration parameters relating to
memory and disk usage can be raised using a simple node restart, but
they require an initial node restart to be lowered.

Because some of these parameters can be used for configuring more than
one type of cluster node, they may appear in more than one of the
tables.

*Note*:

'4294967039' often appears as a maximum value in these tables.  This
value is defined in the 'NDBCLUSTER' sources as
'MAX_INT_RNIL' and is equal to '0xFFFFFEFF', or '2^32 − 2^8 − 1'.

21.3.2.1 NDB Cluster Data Node Configuration Parameters
.......................................................

The listings in this section provide information about parameters used
in the '[ndbd]' or '[ndbd default]' sections of a 'config.ini' file for
configuring NDB Cluster data nodes.  For detailed descriptions and other
additional information about each of these parameters, see
mysql-cluster-ndbd-definition.

These parameters also apply to 'ndbmtd',
the multi-threaded version of
'ndbd'.  For more information, see
mysql-cluster-programs-ndbmtd.

   * 'Arbitration': How arbitration should be performed to avoid
     split-brain issues in the event of node failure.

   * 'ArbitrationTimeout': Maximum time (milliseconds) database
     partition waits for arbitration signal

   * 'BackupDataBufferSize': Default size of databuffer for a backup (in
     bytes)

   * 'BackupDataDir': Path to where to store backups.  Note that the
     string '/BACKUP' is always appended to this setting, so that the
     *effective* default is FileSystemPath/BACKUP.

   * 'BackupDiskWriteSpeedPct': Sets the percentage of the data node's
     allocated maximum write speed (MaxDiskWriteSpeed) to reserve for
     LCPs when starting abackup.

   * 'BackupLogBufferSize': Default size of log buffer for a backup (in
     bytes)

   * 'BackupMaxWriteSize': Maximum size of file system writes made by
     backup (in bytes)

   * 'BackupMemory': Total memory allocated for backups per node (in
     bytes)

   * 'BackupReportFrequency': Frequency of backup status reports during
     backup in seconds

   * 'BackupWriteSize': Default size of file system writes made by
     backup (in bytes)

   * 'BatchSizePerLocalScan': Used to calculate the number of lock
     records for scan with hold lock

   * 'BuildIndexThreads': Number of threads to use for building ordered
     indexes during a system or node restart.  Also applies when running
     ndb_restore -rebuild-indexes.  Setting this parameter to 0 disables
     multi-threaded building of ordered indexes.

   * 'CompressedBackup': Use zlib to compress backups as they are
     written

   * 'CompressedLCP': Write compressed LCPs using zlib

   * 'ConnectCheckIntervalDelay': Time between data node connectivity
     check stages.  Data node is considered suspect after 1 interval and
     dead after 2 intervals with no response.

   * 'CrashOnCorruptedTuple': When enabled, forces node to shut down
     whenever it detects a corrupted tuple.

   * 'DataDir': Data directory for this node

   * 'DataMemory': Number of bytes on each data node allocated for
     storing data; subject to available system RAM and size of
     IndexMemory.

   * 'DefaultHashMapSize': Set size (in buckets) to use for table hash
     maps.  Three values are supported: 0, 240, and 3840.  Intended
     primarily for upgrades and downgrades to and from NDB 7.2.7+; see
     the documentation before attempting to use.

   * 'DictTrace': Enable DBDICT debugging; for NDB development

   * 'DiskIOThreadPool': Number of unbound threads for file access
     (currently only for Disk Data); known as IOThreadPool before MySQL
     Cluster NDB 6.4.3.

   * 'Diskless': Run without using the disk

   * 'DiskPageBufferEntries': Number of 32K page entries to allocate in
     DiskPageBufferMemory.  Very large disk transactions may require
     increasing this value.

   * 'DiskPageBufferMemory': Number of bytes on each data node allocated
     for the disk page buffer cache

   * 'DiskSyncSize': Amount of data written to file before a synch is
     forced

   * 'ExecuteOnComputer': String referencing an earlier defined COMPUTER

   * 'ExtraSendBufferMemory': Memory to use for send buffers in addition
     to any allocated by TotalSendBufferMemory or SendBufferMemory.
     Default (0) allows up to 16MB.

   * 'FileSystemPath': Path to directory where the data node stores its
     data (directory must exist)

   * 'FileSystemPathDataFiles': Path to directory where the data node
     stores its Disk Data files.  The default value is FilesystemPathDD,
     if set; otherwise, FilesystemPath is used if it is set; otherwise,
     the value of DataDir is used.

   * 'FileSystemPathDD': Path to directory where the data node stores
     its Disk Data and undo files.  The default value is FileSystemPath,
     if set; otherwise, the value of DataDir is used.

   * 'FileSystemPathUndoFiles': Path to directory where the data node
     stores its undo files for Disk Data.  The default value is
     FilesystemPathDD, if set; otherwise, FilesystemPath is used if it
     is set; otherwise, the value of DataDir is used.

   * 'FragmentLogFileSize': Size of each redo log file

   * 'HeartbeatIntervalDbApi': Time between API node-data node
     heartbeats.  (API connection closed after 3 missed heartbeats)

   * 'HeartbeatIntervalDbDb': Time between data node-to-data node
     heartbeats; data node considered dead after 3 missed heartbeats

   * 'HeartbeatOrder': Sets the order in which data nodes check each
     others' heartbeats for determining whether a given node is still
     active and connected to the cluster.  Must be zero for all data
     nodes or distinct nonzero values for all data nodes; see
     documentation for further guidance.

   * 'HostName': Host name or IP address for this data node.

   * 'IndexMemory': Number of bytes on each data node allocated for
     storing indexes; subject to available system RAM and size of
     DataMemory.

   * 'IndexStatAutoCreate': Enable/disable automatic statistics
     collection when indexes are created.

   * 'IndexStatAutoUpdate': Monitor indexes for changes and trigger
     automatic statistics updates

   * 'IndexStatSaveScale': Scaling factor used in determining size of
     stored index statistics.

   * 'IndexStatSaveSize': Maximum size in bytes for saved statistics per
     index.

   * 'IndexStatTriggerPct': Threshold percent change in DML operations
     for index statistics updates.  The value is scaled down by
     IndexStatTriggerScale.

   * 'IndexStatTriggerScale': Scale down IndexStatTriggerPct by this
     amount, multiplied by the base 2 logarithm of the index size, for a
     large index.  Set to 0 to disable scaling.

   * 'IndexStatUpdateDelay': Minimum delay between automatic index
     statistics updates for a given index.  0 means no delay.

   * 'InitFragmentLogFiles': Initialize fragment logfiles (sparse/full)

   * 'InitialLogFileGroup': Describes a log file group that is created
     during an initial start.  See documentation for format.

   * 'InitialNoOfOpenFiles': Initial number of files open per data node.
     (One thread is created per file)

   * 'InitialTablespace': Describes a tablespace that is created during
     an initial start.  See documentation for format.

   * 'LateAlloc': Allocate memory after the connection to the management
     server has been established.

   * 'LcpScanProgressTimeout': Maximum time that local checkpoint
     fragment scan can be stalled before node is shut down to ensure
     systemwide LCP progress.  Use 0 to disable.

   * 'LockExecuteThreadToCPU': In NDB 6.3, the ID of the CPU to run the
     execution thread; in NDB 7.0 and later, a comma-delimited list of
     CPU IDs

   * 'LockMaintThreadsToCPU': CPU ID indicating which CPU runs the
     maintenance threads

   * 'LockPagesInMainMemory': Previously: If set to true/1, then NDB
     Cluster data is not swapped out to disk.  In MySQL 5.0.36/5.1.15
     and later: 0=disable locking, 1=lock after memory allocation,
     2=lock before memory allocation

   * 'LogLevelCheckpoint': Log level of local and global checkpoint
     information printed to stdout

   * 'LogLevelCongestion': Level of congestion information printed to
     stdout

   * 'LogLevelConnection': Level of node connect/disconnect information
     printed to stdout

   * 'LogLevelError': Transporter, heartbeat errors printed to stdout

   * 'LogLevelInfo': Heartbeat and log information printed to stdout

   * 'LogLevelNodeRestart': Level of node restart and node failure
     information printed to stdout

   * 'LogLevelShutdown': Level of node shutdown information printed to
     stdout

   * 'LogLevelStartup': Level of node startup information printed to
     stdout

   * 'LogLevelStatistic': Level of transaction, operation, and
     transporter information printed to stdout

   * 'LongMessageBuffer': Number of bytes allocated on each data node
     for internal long messages

   * 'MaxAllocate': Maximum size of allocation to use when allocating
     memory for tables

   * 'MaxBufferedEpochs': Allowed numbered of epochs that a subscribing
     node can lag behind (unprocessed epochs).  Exceeding will cause
     lagging subscribers to be disconnected.

   * 'MaxBufferedEpochBytes': Total number of bytes allocated for
     buffering epochs.

   * 'MaxDiskWriteSpeed': Maximum number of bytes per second that can be
     written by LCP and backup when no restarts are ongoing.

   * 'MaxDiskWriteSpeedOtherNodeRestart': Maximum number of bytes per
     second that can be written by LCP and backup when another node is
     restarting.

   * 'MaxDiskWriteSpeedOwnRestart': Maximum number of bytes per second
     that can be written by LCP and backup when this node is restarting.

   * 'MaxFKBuildBatchSize': Maximum scan batch size to use for building
     foreign keys.  Increasing this value may speed up builds of foreign
     keys but impacts ongoing traffic as well.

   * 'MaxDMLOperationsPerTransaction': Limit size of a transaction;
     aborts the transaction if it requires more than this many DML
     operations.  Set to 0 to disable.

   * 'MaxLCPStartDelay': Time in seconds that LCP polls for checkpoint
     mutex (to allow other data nodes to complete metadata
     synchronization), before putting itself in lock queue for parallel
     recovery of table data.

   * 'MaxNoOfAttributes': Suggests a total number of attributes stored
     in database (sum over all tables)

   * 'MaxNoOfConcurrentIndexOperations': Total number of index
     operations that can execute simultaneously on one data node

   * 'MaxNoOfConcurrentOperations': Maximum number of operation records
     in transaction coordinator

   * 'MaxNoOfConcurrentScans': Maximum number of scans executing
     concurrently on the data node

   * 'MaxNoOfConcurrentSubOperations': Maximum number of concurrent
     subscriber operations

   * 'MaxNoOfConcurrentTransactions': Maximum number of transactions
     executing concurrently on this data node, the total number of
     transactions that can be executed concurrently is this value times
     the number of data nodes in the cluster.

   * 'MaxNoOfFiredTriggers': Total number of triggers that can fire
     simultaneously on one data node

   * 'MaxNoOfLocalOperations': Maximum number of operation records
     defined on this data node

   * 'MaxNoOfLocalScans': Maximum number of fragment scans in parallel
     on this data node

   * 'MaxNoOfOpenFiles': Maximum number of files open per data node.(One
     thread is created per file)

   * 'MaxNoOfOrderedIndexes': Total number of ordered indexes that can
     be defined in the system

   * 'MaxNoOfSavedMessages': Maximum number of error messages to write
     in error log and maximum number of trace files to retain

   * 'MaxNoOfSubscribers': Maximum number of subscribers (default 0 =
     MaxNoOfTables * 2)

   * 'MaxNoOfSubscriptions': Maximum number of subscriptions (default 0
     = MaxNoOfTables)

   * 'MaxNoOfTables': Suggests a total number of NDB tables stored in
     the database

   * 'MaxNoOfTriggers': Total number of triggers that can be defined in
     the system

   * 'MaxNoOfUniqueHashIndexes': Total number of unique hash indexes
     that can be defined in the system

   * 'MaxParallelCopyInstances': Number of parallel copies during node
     restarts.  Default is 0, which uses number of LDMs on both nodes,
     to a maximum of 16.

   * 'MaxParallelScansPerFragment': Maximum number of parallel scans per
     fragment.  Once this limit is reached, scans are serialized.

   * 'MaxReorgBuildBatchSize': Maximum scan batch size to use for
     reorganization of table partitions.  Increasing this value may
     speed up table partition reorganization but impacts ongoing traffic
     as well.

   * 'MaxStartFailRetries': Maximum retries when data node fails on
     startup, requires StopOnError = 0.  Setting to 0 causes start
     attempts to continue indefinitely.

   * 'MaxUIBuildBatchSize': Maximum scan batch size to use for building
     unique keys.  Increasing this value may speed up builds of unique
     keys but impacts ongoing traffic as well.

   * 'MemReportFrequency': Frequency of mem reports in seconds, 0 = only
     when passing %-limits

   * 'MinDiskWriteSpeed': Minimum number of bytes per second that can be
     written by LCP and backup.

   * 'MinFreePct': The percentage of memory resources to keep in reserve
     for restarts.

   * 'NodeGroup': Node group to which the data node belongs; used only
     during initial start of cluster.

   * 'NodeId': Number uniquely identifying the data node among all nodes
     in the cluster.

   * 'NoOfFragmentLogFiles': Number of 16 MB redo log files in each of 4
     file sets belonging to the data node

   * 'NoOfReplicas': Number of copies of all data in database;
     recommended value is 2 (default).  Values greater than 2 are not
     supported in production.

   * 'Numa': (Linux only; requires libnuma) Controls NUMA support.
     Setting to 0 permits system to determine use of interleaving by
     data node process; 1 means that it is determined by data node.

   * 'ODirect': Use O_DIRECT file reads and writes when possible.

   * 'ODirectSyncFlag': O_DIRECT writes are treated as synchronized
     writes; ignored when ODirect is not enabled, InitFragmentLogFiles
     is set to SPARSE, or both.

   * 'RealtimeScheduler': When true, data node threads are scheduled as
     real-time threads.  Default is false.

   * 'RedoBuffer': Number bytes on each data node allocated for writing
     redo logs

   * 'RedoOverCommitCounter': When RedoOverCommitLimit has been exceeded
     this many times, transactions are aborted, and operations are
     handled as specified by DefaultOperationRedoProblemAction.

   * 'RedoOverCommitLimit': Each time that flushing the current redo
     buffer takes longer than this many seconds, the number of times
     that this has happened is compared to RedoOverCommitCounter.

   * 'RestartOnErrorInsert': Control the type of restart caused by
     inserting an error (when StopOnError is enabled)

   * 'SchedulerExecutionTimer': Number of microseconds to execute in
     scheduler before sending

   * 'SchedulerResponsiveness': Set NDB scheduler response optimization
     0-10; higher values provide better response time but lower
     throughput

   * 'SchedulerSpinTimer': Number of microseconds to execute in
     scheduler before sleeping

   * 'ServerPort': Port used to set up transporter for incoming
     connections from API nodes

   * 'SharedGlobalMemory': Total number of bytes on each data node
     allocated for any use

   * 'StartFailRetryDelay': Delay in seconds after start failure prior
     to retry; requires StopOnError = 0.

   * 'StartFailureTimeout': Milliseconds to wait before terminating.
     (0=Wait forever)

   * 'StartNoNodeGroupTimeout': Time to wait for nodes without a
     nodegroup before trying to start (0=forever)

   * 'StartPartialTimeout': Milliseconds to wait before trying to start
     without all nodes.  (0=Wait forever)

   * 'StartPartitionedTimeout': Milliseconds to wait before trying to
     start partitioned.  (0=Wait forever)

   * 'StartupStatusReportFrequency': Frequency of status reports during
     startup

   * 'StopOnError': When set to 0, the data node automatically restarts
     and recovers following node failures

   * 'StringMemory': Default size of string memory (0 to 100 = % of
     maximum, 101+ = actual bytes)

   * 'TcpBind_INADDR_ANY': Bind IP_ADDR_ANY so that connections can be
     made from anywhere (for autogenerated connections)

   * 'TimeBetweenEpochs': Time between epochs (synchronization used for
     replication)

   * 'TimeBetweenEpochsTimeout': Timeout for time between epochs.
     Exceeding will cause node shutdown.

   * 'TimeBetweenGlobalCheckpoints': Time between doing group commit of
     transactions to disk

   * 'TimeBetweenGlobalCheckpointsTimeout': Minimum timeout for group
     commit of transactions to disk

   * 'TimeBetweenInactiveTransactionAbortCheck': Time between checks for
     inactive transactions

   * 'TimeBetweenLocalCheckpoints': Time between taking snapshots of the
     database (expressed in base-2 logarithm of bytes)

   * 'TimeBetweenWatchDogCheck': Time between execution checks inside a
     data node

   * 'TimeBetweenWatchDogCheckInitial': Time between execution checks
     inside a data node (early start phases when memory is allocated)

   * 'TotalSendBufferMemory': Total memory to use for all transporter
     send buffers.

   * 'TransactionBufferMemory': Dynamic buffer space (in bytes) for key
     and attribute data allocated for each data node

   * 'TransactionDeadlockDetectionTimeout': Time transaction can spend
     executing within a data node.  This is the time that the
     transaction coordinator waits for each data node participating in
     the transaction to execute a request.  If the data node takes more
     than this amount of time, the transaction is aborted.  Prior to
     MySQL Cluster NDB 6.2.18/6.3.24/7.0.5, values between 50 and 100
     were possible, but were treated as 100.

   * 'TransactionInactiveTimeout': Milliseconds that the application
     waits before executing another part of the transaction.  This is
     the time the transaction coordinator waits for the application to
     execute or send another part (query, statement) of the transaction.
     If the application takes too much time, then the transaction is
     aborted.  Timeout = 0 means that the application never times out.

   * 'TwoPassInitialNodeRestartCopy': Copy data in 2 passes during
     initial node restart, which enables multi-threaded building of
     ordered indexes for such restarts.

   * 'UndoDataBuffer': Number of bytes on each data node allocated for
     writing data undo logs

   * 'UndoIndexBuffer': Number of bytes on each data node allocated for
     writing index undo logs

The following parameters are specific to 'ndbmtd'.:

   * 'MaxNoOfExecutionThreads': For ndbmtd only, specify maximum number
     of execution threads

   * 'NoOfFragmentLogParts': Number of redo log file groups belonging to
     this data node; value must be an even multiple of 4.

   * 'ThreadConfig': Used for configuration of multi-threaded data nodes
     (ndbmtd).  Default is an empty string; see documentation for syntax
     and other information.

21.3.2.2 NDB Cluster Management Node Configuration Parameters
.............................................................

The listing in this section provides information about parameters used
in the '[ndb_mgmd]' or '[mgm]' section of a 'config.ini' file for
configuring NDB Cluster management nodes.  For detailed descriptions and
other additional information about each of these parameters, see
mysql-cluster-mgm-definition.

   * 'ArbitrationDelay': When asked to arbitrate, arbitrator waits this
     long before voting (milliseconds)

   * 'ArbitrationRank': If 0, then management node is not arbitrator.
     Kernel selects arbitrators in order 1, 2

   * 'DataDir': Data directory for this node

   * 'ExecuteOnComputer': String referencing an earlier defined COMPUTER

   * 'HeartbeatIntervalMgmdMgmd': Time between management
     node-to-management node heartbeats; the connection between
     management node is considered lost after 3 missed heartbeats.

   * 'HeartbeatThreadPriority': Set heartbeat thread policy and priority
     for management nodes; see manual for allowed values

   * 'HostName': Host name or IP address for this management node.

   * 'Id': Number identifying the management node (Id).  Now deprecated;
     use NodeId instead.

   * 'LogDestination': Where to send log messages: console, system log,
     or specified log file

   * 'NodeId': Number uniquely identifying the management node among all
     nodes in the cluster.

   * 'PortNumber': Port number to send commands to and fetch
     configuration from management server

   * 'PortNumberStats': Port number used to get statistical information
     from a management server

   * 'TotalSendBufferMemory': Total memory to use for all transporter
     send buffers

   * 'wan': Use WAN TCP setting as default

*Note*:

After making changes in a management node's configuration, it is
necessary to perform a rolling restart of the cluster for the new
configuration to take effect.  See mysql-cluster-mgm-definition,
for more information.

To add new management servers to a running NDB Cluster, it is also
necessary perform a rolling restart of all cluster nodes after modifying
any existing 'config.ini' files.  For more information about issues
arising when using multiple management nodes, see
mysql-cluster-limitations-multiple-nodes.

21.3.2.3 NDB Cluster SQL Node and API Node Configuration Parameters
...................................................................

The listing in this section provides information about parameters used
in the '[mysqld]' and '[api]' sections of a 'config.ini' file for
configuring NDB Cluster SQL nodes and API nodes.  For detailed
descriptions and other additional information about each of these
parameters, see mysql-cluster-api-definition.

   * 'ApiVerbose': Enable NDB API debugging; for NDB development

   * 'ArbitrationDelay': When asked to arbitrate, arbitrator waits this
     many milliseconds before voting

   * 'ArbitrationRank': If 0, then API node is not arbitrator.  Kernel
     selects arbitrators in order 1, 2

   * 'AutoReconnect': Specifies whether an API node should reconnect
     fully when disconnected from the cluster

   * 'BatchByteSize': The default batch size in bytes

   * 'BatchSize': The default batch size in number of records

   * 'ConnectBackoffMaxTime': Specifies longest time in milliseconds
     (~100ms resolution) to allow between connection attempts to any
     given data node by this API node.  Excludes time elapsed while
     connection attempts are ongoing, which in worst case can take
     several seconds.  Disable by setting to 0.  If no data nodes are
     currently connected to this API node, StartConnectBackoffMaxTime is
     used instead.

   * 'ConnectionMap': Specifies which data nodes to connect

   * 'DefaultHashMapSize': Set size (in buckets) to use for table hash
     maps.  Three values are supported: 0, 240, and 3840.  Intended
     primarily for upgrades and downgrades to and from NDB 7.2.7+; see
     the documentation before attempting to use.

   * 'DefaultOperationRedoProblemAction': How operations are handled in
     the event that RedoOverCommitCounter is exceeded

   * 'EventLogBufferSize': Size of circular buffer for NDB log events
     within data nodes.

   * 'ExecuteOnComputer': String referencing an earlier defined COMPUTER

   * 'ExtraSendBufferMemory': Memory to use for send buffers in addition
     to any allocated by TotalSendBufferMemory or SendBufferMemory.
     Default (0) allows up to 16MB.

   * 'HeartbeatThreadPriority': Set heartbeat thread policy and priority
     for API nodes; see manual for allowed values

   * 'HostName': Host name or IP address for this SQL or API node.

   * 'Id': Number identifying MySQL server or API node (Id).  Now
     deprecated; use NodeId instead.

   * 'MaxScanBatchSize': The maximum collective batch size for one scan

   * 'NodeId': Number uniquely identifying the SQL node or API node
     among all nodes in the cluster.

   * 'StartConnectBackoffMaxTime': Same as ConnectBackoffMaxTime except
     that this parameter is used in its place if no data nodes are
     connected to this API node.

   * 'TotalSendBufferMemory': Total memory to use for all transporter
     send buffers

   * 'wan': Use WAN TCP setting as default

For a discussion of MySQL server options for NDB Cluster, see
mysql-cluster-program-options-mysqld; for information about MySQL
server system variables relating to NDB Cluster, see
mysql-cluster-system-variables.

*Note*:

To add new SQL or API nodes to the configuration of a running NDB
Cluster, it is necessary to perform a rolling restart of all cluster
nodes after adding new '[mysqld]' or '[api]' sections to the
'config.ini' file (or files, if you are using more than one management
server).  This must be done before the new SQL or API nodes can connect
to the cluster.

It is _not_ necessary to perform any restart of the cluster if new SQL
or API nodes can employ previously unused API slots in the cluster
configuration to connect to the cluster.

21.3.2.4 Other NDB Cluster Configuration Parameters
...................................................

The listings in this section provide information about parameters used
in the '[computer]', '[tcp]', '[shm]', and '[sci]' sections of a
'config.ini' file for configuring NDB Cluster.  For detailed
descriptions and additional information about individual parameters, see
mysql-cluster-tcp-definition,
mysql-cluster-shm-definition, or mysql-cluster-sci-definition,
as appropriate.

The following parameters apply to the 'config.ini' file's '[computer]'
section:

   * 'HostName': Host name or IP address of this computer.

   * 'Id': A unique identifier for this computer.

The following parameters apply to the 'config.ini' file's '[tcp]'
section:

   * 'Checksum': If checksum is enabled, all signals between nodes are
     checked for errors

   * 'Group': Used for group proximity; smaller value is interpreted as
     being closer

   * 'NodeId1': ID of node (data node, API node, or management node) on
     one side of the connection

   * 'NodeId2': ID of node (data node, API node, or management node) on
     one side of the connection

   * 'NodeIdServer':

   * 'OverloadLimit': When more than this many unsent bytes are in the
     send buffer, the connection is considered overloaded.

   * 'PortNumber': Port used for this transporter (DEPRECATED)

   * 'Proxy':

   * 'ReceiveBufferMemory': Bytes of buffer for signals received by this
     node

   * 'SendBufferMemory': Bytes of buffer for signals sent from this node

   * 'SendSignalId': Sends ID in each signal.  Used in trace files.
     Defaults to true in debug builds.

   * 'TCP_MAXSEG_SIZE': Value used for TCP_MAXSEG

   * 'TCP_RCV_BUF_SIZE': Value used for SO_RCVBUF

   * 'TCP_SND_BUF_SIZE': Value used for SO_SNDBUF

   * 'TcpBind_INADDR_ANY': Bind InAddrAny instead of host name for
     server part of connection

The following parameters apply to the 'config.ini' file's '[shm]'
section:

   * 'Checksum': If checksum is enabled, all signals between nodes are
     checked for errors

   * 'Group':

   * 'NodeId1': ID of node (data node, API node, or management node) on
     one side of the connection

   * 'NodeId2': ID of node (data node, API node, or management node) on
     one side of the connection

   * 'NodeIdServer':

   * 'OverloadLimit': When more than this many unsent bytes are in the
     send buffer, the connection is considered overloaded.

   * 'PortNumber': Port used for this transporter (DEPRECATED)

   * 'SendSignalId': Sends ID in each signal.  Used in trace files.

   * 'ShmKey': A shared memory key

   * 'ShmSize': Size of shared memory segment

   * 'Signum': Signal number to be used for signalling

The following parameters apply to the 'config.ini' file's '[sci]'
section:

   * 'Checksum': If checksum is enabled, all signals between nodes are
     checked for errors

   * 'Group':

   * 'Host1SciId0': SCI-node ID for adapter 0 on Host1 (a computer can
     have two adapters)

   * 'Host1SciId1': SCI-node ID for adapter 1 on Host1 (a computer can
     have two adapters)

   * 'Host2SciId0': SCI-node ID for adapter 0 on Host2 (a computer can
     have two adapters)

   * 'Host2SciId1': SCI-node ID for adapter 1 on Host2 (a computer can
     have two adapters)

   * 'NodeId1': ID of node (data node, API node, or management node) on
     one side of the connection

   * 'NodeId2': ID of node (data node, API node, or management node) on
     one side of the connection

   * 'NodeIdServer':

   * 'OverloadLimit': When more than this many unsent bytes are in the
     send buffer, the connection is considered overloaded.

   * 'PortNumber': Port used for this transporter (DEPRECATED)

   * 'SendLimit': Transporter send buffer contents are sent when this
     number of bytes is buffered

   * 'SendSignalId': Sends ID in each signal.  Used in trace files.

   * 'SharedBufferSize': Size of shared memory segment

21.3.2.5 NDB Cluster mysqld Option and Variable Reference
.........................................................

The following table provides a list of the command-line options, server
and status variables applicable within 'mysqld' when it is running as an
SQL node in an NDB Cluster.  For a table showing _all_ command-line
options, server and status variables available for use with
'mysqld', see mysqld-option-tables.

   * 'Com_show_ndb_status': Count of SHOW NDB STATUS statements

   * 'Handler_discover': Number of times that tables have been
     discovered

   * 'ndb-batch-size': Size (in bytes) to use for NDB transaction
     batches

   * 'ndb-blob-read-batch-bytes': Specifies size in bytes that large
     BLOB reads should be batched into.  0 = no limit.

   * 'ndb-blob-write-batch-bytes': Specifies size in bytes that large
     BLOB writes should be batched into.  0 = no limit.

   * 'ndb-cluster-connection-pool': Number of connections to the cluster
     used by MySQL

   * 'ndb-cluster-connection-pool-nodeids': Comma-separated list of node
     IDs for connections to the cluster used by MySQL; the number of
     nodes in the list must be the same as the value set for
     -ndb-cluster-connection-pool

   * 'ndb-connectstring': Point to the management server that
     distributes the cluster configuration

   * 'ndb-default-column-format': Use this value (FIXED or DYNAMIC) by
     default for COLUMN_FORMAT and ROW_FORMAT options when creating or
     adding columns to a table.

   * 'ndb-deferred-constraints': Specifies that constraint checks on
     unique indexes (where these are supported) should be deferred until
     commit time.  Not normally needed or used; for testing purposes
     only.

   * 'ndb-distribution': Default distribution for new tables in
     NDBCLUSTER (KEYHASH or LINHASH, default is KEYHASH)

   * 'ndb-log-apply-status': Cause a MySQL server acting as a slave to
     log mysql.ndb_apply_status updates received from its immediate
     master in its own binary log, using its own server ID. Effective
     only if the server is started with the -ndbcluster option.

   * 'ndb-log-empty-epochs': When enabled, causes epochs in which there
     were no changes to be written to the ndb_apply_status and
     ndb_binlog_index tables, even when -log-slave-updates is enabled.

   * 'ndb-log-empty-update': When enabled, causes updates that produced
     no changes to be written to the ndb_apply_status and
     ndb_binlog_index tables, even when -log-slave-updates is enabled.

   * 'ndb-log-exclusive-reads': Log primary key reads with exclusive
     locks; allow conflict resolution based on read conflicts

   * 'ndb-log-orig': Log originating server id and epoch in
     mysql.ndb_binlog_index table

   * 'ndb-log-transaction-id': Write NDB transaction IDs in the binary
     log.  Requires -log-bin-v1-events=OFF.

   * 'ndb-mgmd-host': Set the host (and port, if desired) for connecting
     to management server

   * 'ndb-nodeid': NDB Cluster node ID for this MySQL server

   * 'ndb-recv-thread-activation-threshold': Activation threshold when
     receive thread takes over the polling of the cluster connection
     (measured in concurrently active threads)

   * 'ndb-recv-thread-cpu-mask': CPU mask for locking receiver threads
     to specific CPUs; specified as hexadecimal.  See documentation for
     details.

   * 'ndb-transid-mysql-connection-map': Enable or disable the
     ndb_transid_mysql_connection_map plugin; that is, enable or disable
     the INFORMATION_SCHEMA table having that name

   * 'ndb-wait-connected': Time (in seconds) for the MySQL server to
     wait for connection to cluster management and data nodes before
     accepting MySQL client connections

   * 'ndb-wait-setup': Time (in seconds) for the MySQL server to wait
     for NDB engine setup to complete

   * 'ndb-allow-copying-alter-table': Set to OFF to keep ALTER TABLE
     from using copying operations on NDB tables

   * 'Ndb_api_bytes_received_count': Amount of data (in bytes) received
     from the data nodes by this MySQL Server (SQL node)

   * 'Ndb_api_bytes_received_count_session': Amount of data (in bytes)
     received from the data nodes in this client session

   * 'Ndb_api_bytes_received_count_slave': Amount of data (in bytes)
     received from the data nodes by this slave

   * 'Ndb_api_bytes_sent_count': Amount of data (in bytes) sent to the
     data nodes by this MySQL Server (SQL node)

   * 'Ndb_api_bytes_sent_count_slave': Amount of data (in bytes) sent to
     the data nodes by this slave

   * 'Ndb_api_event_bytes_count_injector': Number of bytes of events
     received by the NDB binary log injector thread

   * 'Ndb_api_event_data_count_injector': Number of row change events
     received by the NDB binary log injector thread

   * 'Ndb_api_event_nondata_count_injector': Number of events received,
     other than row change events, by the NDB binary log injector thread

   * 'Ndb_api_pk_op_count': Number of operations based on or using
     primary keys by this MySQL Server (SQL node)

   * 'Ndb_api_pk_op_count_session': Number of operations based on or
     using primary keys in this client session

   * 'Ndb_api_pk_op_count_slave': Number of operations based on or using
     primary keys by this slave

   * 'Ndb_api_pruned_scan_count': Number of scans that have been pruned
     to a single partition by this MySQL Server (SQL node)

   * 'Ndb_api_pruned_scan_count_session': Number of scans that have been
     pruned to a single partition in this client session

   * 'Ndb_api_range_scan_count_slave': Number of range scans that have
     been started by this slave

   * 'Ndb_api_read_row_count': Total number of rows that have been read
     by this MySQL Server (SQL node)

   * 'Ndb_api_read_row_count_session': Total number of rows that have
     been read in this client session

   * 'Ndb_api_scan_batch_count_slave': Number of batches of rows
     received by this slave

   * 'Ndb_api_table_scan_count': Number of table scans that have been
     started, including scans of internal tables, by this MySQL Server
     (SQL node)

   * 'Ndb_api_table_scan_count_session': Number of table scans that have
     been started, including scans of internal tables, in this client
     session

   * 'Ndb_api_trans_abort_count': Number of transactions aborted by this
     MySQL Server (SQL node)

   * 'Ndb_api_trans_abort_count_session': Number of transactions aborted
     in this client session

   * 'Ndb_api_trans_abort_count_slave': Number of transactions aborted
     by this slave

   * 'Ndb_api_trans_close_count': Number of transactions aborted (may be
     greater than the sum of TransCommitCount and TransAbortCount) by
     this MySQL Server (SQL node)

   * 'Ndb_api_trans_close_count_session': Number of transactions aborted
     (may be greater than the sum of TransCommitCount and
     TransAbortCount) in this client session

   * 'Ndb_api_trans_close_count_slave': Number of transactions aborted
     (may be greater than the sum of TransCommitCount and
     TransAbortCount) by this slave

   * 'Ndb_api_trans_commit_count': Number of transactions committed by
     this MySQL Server (SQL node)

   * 'Ndb_api_trans_commit_count_session': Number of transactions
     committed in this client session

   * 'Ndb_api_trans_commit_count_slave': Number of transactions
     committed by this slave

   * 'Ndb_api_trans_local_read_row_count_slave': Total number of rows
     that have been read by this slave

   * 'Ndb_api_trans_start_count': Number of transactions started by this
     MySQL Server (SQL node)

   * 'Ndb_api_trans_start_count_session': Number of transactions started
     in this client session

   * 'Ndb_api_trans_start_count_slave': Number of transactions started
     by this slave

   * 'Ndb_api_uk_op_count': Number of operations based on or using
     unique keys by this MySQL Server (SQL node)

   * 'Ndb_api_uk_op_count_slave': Number of operations based on or using
     unique keys by this slave

   * 'Ndb_api_wait_exec_complete_count': Number of times thread has been
     blocked while waiting for execution of an operation to complete by
     this MySQL Server (SQL node)

   * 'Ndb_api_wait_exec_complete_count_session': Number of times thread
     has been blocked while waiting for execution of an operation to
     complete in this client session

   * 'Ndb_api_wait_exec_complete_count_slave': Number of times thread
     has been blocked while waiting for execution of an operation to
     complete by this slave

   * 'Ndb_api_wait_meta_request_count': Number of times thread has been
     blocked waiting for a metadata-based signal by this MySQL Server
     (SQL node)

   * 'Ndb_api_wait_meta_request_count_session': Number of times thread
     has been blocked waiting for a metadata-based signal in this client
     session

   * 'Ndb_api_wait_nanos_count': Total time (in nanoseconds) spent
     waiting for some type of signal from the data nodes by this MySQL
     Server (SQL node)

   * 'Ndb_api_wait_nanos_count_session': Total time (in nanoseconds)
     spent waiting for some type of signal from the data nodes in this
     client session

   * 'Ndb_api_wait_nanos_count_slave': Total time (in nanoseconds) spent
     waiting for some type of signal from the data nodes by this slave

   * 'Ndb_api_wait_scan_result_count': Number of times thread has been
     blocked while waiting for a scan-based signal by this MySQL Server
     (SQL node)

   * 'Ndb_api_wait_scan_result_count_session': Number of times thread
     has been blocked while waiting for a scan-based signal in this
     client session

   * 'Ndb_api_wait_scan_result_count_slave': Number of times thread has
     been blocked while waiting for a scan-based signal by this slave

   * 'ndb_autoincrement_prefetch_sz': NDB auto-increment prefetch size

   * 'ndb_cache_check_time': Number of milliseconds between checks of
     cluster SQL nodes made by the MySQL query cache

   * 'ndb_clear_apply_status': Causes RESET SLAVE to clear all rows from
     the ndb_apply_status table; ON by default

   * 'Ndb_cluster_node_id': If the server is acting as an NDB Cluster
     node, then the value of this variable its node ID in the cluster

   * 'Ndb_config_from_host': The host name or IP address of the Cluster
     management server Formerly Ndb_connected_host

   * 'Ndb_config_from_port': The port for connecting to Cluster
     management server.  Formerly Ndb_connected_port

   * 'Ndb_conflict_fn_epoch_trans': Number of rows that have been found
     in conflict by the NDB$EPOCH_TRANS() conflict detection function

   * 'Ndb_conflict_fn_max': If the server is part of an NDB Cluster
     involved in cluster replication, the value of this variable
     indicates the number of times that conflict resolution based on
     "greater timestamp wins" has been applied

   * 'Ndb_conflict_fn_old': If the server is part of an NDB Cluster
     involved in cluster replication, the value of this variable
     indicates the number of times that "same timestamp wins" conflict
     resolution has been applied

   * 'Ndb_conflict_trans_detect_iter_count': Number of internal
     iterations required to commit an epoch transaction.  Should be
     (slightly) greater than or equal to
     Ndb_conflict_trans_conflict_commit_count

   * 'Ndb_conflict_trans_row_reject_count': Total number of rows
     realigned after being found in conflict by a transactional conflict
     function.  Includes Ndb_conflict_trans_row_conflict_count and any
     rows included in or dependent on conflicting transactions.

   * 'ndb_data_node_neighbour': Specifies cluster data node "closest" to
     this MySQL Server, for transaction hinting and fully replicated
     tables

   * 'ndb_default_column_format': Sets default row format and column
     format (FIXED or DYNAMIC) used for new NDB tables

   * 'ndb_deferred_constraints': Specifies that constraint checks should
     be deferred (where these are supported).  Not normally needed or
     used; for testing purposes only.

   * 'ndb_distribution': Default distribution for new tables in
     NDBCLUSTER (KEYHASH or LINHASH, default is KEYHASH)

   * 'ndb_eventbuffer_free_percent': Percentage of free memory that
     should be available in event buffer before resumption of buffering,
     after reaching limit set by ndb_eventbuffer_max_alloc

   * 'ndb_eventbuffer_max_alloc': Maximum memory that can be allocated
     for buffering events by the NDB API. Defaults to 0 (no limit).

   * 'ndb_extra_logging': Controls logging of NDB Cluster schema,
     connection, and data distribution events in the MySQL error log

   * 'ndb_force_send': Forces sending of buffers to NDB immediately,
     without waiting for other threads

   * 'ndb_fully_replicated': Whether new NDB tables are fully replicated

   * 'ndb_index_stat_enable': Use NDB index statistics in query
     optimization

   * 'ndb_index_stat_option': Comma-separated list of tunable options
     for NDB index statistics; the list should contain no spaces

   * 'ndb_join_pushdown': Enables pushing down of joins to data nodes

   * 'ndb_log_apply_status': Whether or not a MySQL server acting as a
     slave logs mysql.ndb_apply_status updates received from its
     immediate master in its own binary log, using its own server ID

   * 'ndb_log_bin': Write updates to NDB tables in the binary log.
     Effective only if binary logging is enabled with -log-bin.

   * 'ndb_log_binlog_index': Insert mapping between epochs and binary
     log positions into the ndb_binlog_index table.  Defaults to ON.
     Effective only if binary logging is enabled on the server.

   * 'ndb_log_empty_epochs': When enabled, epochs in which there were no
     changes are written to the ndb_apply_status and ndb_binlog_index
     tables, even when log_slave_updates is enabled

   * 'ndb_log_empty_update': When enabled, updates which produce no
     changes are written to the ndb_apply_status and ndb_binlog_index
     tables, even when log_slave_updates is enabled

   * 'ndb_log_exclusive_reads': Log primary key reads with exclusive
     locks; allow conflict resolution based on read conflicts

   * 'ndb_log_orig': Whether the id and epoch of the originating server
     are recorded in the mysql.ndb_binlog_index table.  Set using the
     -ndb-log-orig option when starting mysqld.

   * 'ndb_log_transaction_id': Whether NDB transaction IDs are written
     into the binary log (Read-only.)

   * 'ndb-log-update-minimal': Log updates in a minimal format.

   * 'ndb_log_updated_only': Log complete rows (ON) or updates only
     (OFF)

   * 'Ndb_number_of_data_nodes': If the server is part of an NDB
     Cluster, the value of this variable is the number of data nodes in
     the cluster

   * 'ndb_optimization_delay': Sets the number of milliseconds to wait
     between processing sets of rows by OPTIMIZE TABLE on NDB tables

   * 'ndb_optimized_node_selection': Determines how an SQL node chooses
     a cluster data node to use as transaction coordinator

   * 'Ndb_pushed_queries_defined': Number of joins that API nodes have
     attempted to push down to the data nodes

   * 'Ndb_pushed_queries_executed': Number of joins successfully pushed
     down and executed on the data nodes

   * 'ndb_read_backup': Enable read from any replica

   * 'ndb_recv_thread_activation_threshold': Activation threshold when
     receive thread takes over the polling of the cluster connection
     (measured in concurrently active threads)

   * 'ndb_recv_thread_cpu_mask': CPU mask for locking receiver threads
     to specific CPUs; specified as hexadecimal.  See documentation for
     details.

   * 'ndb_report_thresh_binlog_epoch_slip': NDB 7.5.4 and later:
     Threshold for number of epochs completely buffered, but not yet
     consumed by binlog injector thread which when exceeded generates
     BUFFERED_EPOCHS_OVER_THRESHOLD event buffer status message; prior
     to NDB 7.5.4: Threshold for number of epochs to lag behind before
     reporting binary log status

   * 'ndb_report_thresh_binlog_mem_usage': This is a threshold on the
     percentage of free memory remaining before reporting binary log
     status

   * 'Ndb_scan_count': The total number of scans executed by NDB since
     the cluster was last started

   * 'ndb_show_foreign_key_mock_tables': Show the mock tables used to
     support foreign_key_checks=0

   * 'ndb_slave_conflict_role': Role for slave to play in conflict
     detection and resolution.  Value is one of PRIMARY, SECONDARY,
     PASS, or NONE (default).  Can be changed only when slave SQL thread
     is stopped.  See documentation for further information.

   * 'Ndb_slave_max_replicated_epoch': The most recently committed NDB
     epoch on this slave.  When this value is greater than or equal to
     Ndb_conflict_last_conflict_epoch, no conflicts have yet been
     detected.

   * 'Ndb_system_name': Configured cluster system name; empty if server
     not connected to NDB

   * 'ndb_table_no_logging': NDB tables created when this setting is
     enabled are not checkpointed to disk (although table schema files
     are created).  The setting in effect when the table is created with
     or altered to use NDBCLUSTER persists for the lifetime of the
     table.

   * 'ndb_table_temporary': NDB tables are not persistent on disk: no
     schema files are created and the tables are not logged

   * 'ndb_use_exact_count': Use exact row count when planning queries

   * 'ndb_use_transactions': Forces NDB to use a count of records during
     SELECT COUNT(*) query planning to speed up this type of query

   * 'ndb_version': Shows build and NDB engine version as an integer

   * 'ndb_version_string': Shows build information including NDB engine
     version in ndb-x.y.z format

   * 'ndbcluster': Enable NDB Cluster (if this version of MySQL supports
     it) Disabled by '--skip-ndbcluster'

   * 'ndbinfo_database': The name used for the NDB information database;
     read only

   * 'ndbinfo_max_bytes': Used for debugging only

   * 'ndbinfo_max_rows': Used for debugging only

   * 'ndbinfo_offline': Put the ndbinfo database into offline mode, in
     which no rows are returned from tables or views

   * 'ndbinfo_show_hidden': Whether to show ndbinfo internal base tables
     in the mysql client.  The default is OFF.

   * 'ndbinfo_table_prefix': The prefix to use for naming ndbinfo
     internal base tables

   * 'ndbinfo_version': The version of the ndbinfo engine; read only

   * 'server-id-bits': Sets the number of least significant bits in the
     server_id actually used for identifying the server, permitting NDB
     API applications to store application data in the most significant
     bits.  server_id must be less than 2 to the power of this value.

   * 'server_id_bits': The effective value of server_id if the server
     was started with the -server-id-bits option set to a nondefault
     value

   * 'slave_allow_batching': Turns update batching on and off for a
     replication slave

   * 'transaction_allow_batching': Allows batching of statements within
     a transaction.  Disable AUTOCOMMIT to use.

21.3.3 NDB Cluster Configuration Files
--------------------------------------

Configuring NDB Cluster requires working with two files:

   * 'my.cnf': Specifies options for all NDB Cluster executables.  This
     file, with which you should be familiar with from previous work
     with MySQL, must be accessible by each executable running in the
     cluster.

   * 'config.ini': This file, sometimes known as the _global
     configuration file_, is read only by the NDB Cluster management
     server, which then distributes the information contained therein to
     all processes participating in the cluster.  'config.ini' contains
     a description of each node involved in the cluster.  This includes
     configuration parameters for data nodes and configuration
     parameters for connections between all nodes in the cluster.  For a
     quick reference to the sections that can appear in this file, and
     what sorts of configuration parameters may be placed in each
     section, see Sections of the 'config.ini' File.

Caching of configuration data

'NDB' uses _stateful configuration_.  Rather than reading the global
configuration file every time the management server is restarted, the
management server caches the configuration the first time it is started,
and thereafter, the global configuration file is read only when one of
the following conditions is true:

   * The management server is started using the -initial option

     When '--initial' is used, the global configuration file is re-read,
     any existing cache files are deleted, and the management server
     creates a new configuration cache.

   * The management server is started using the -reload option

     The '--reload' option causes the management server to compare its
     cache with the global configuration file.  If they differ, the
     management server creates a new configuration cache; any existing
     configuration cache is preserved, but not used.  If the management
     server's cache and the global configuration file contain the same
     configuration data, then the existing cache is used, and no new
     cache is created.

   * The management server is started using -config-cache=FALSE

     This disables '--config-cache' (enabled by default), and can be
     used to force the management server to bypass configuration caching
     altogether.  In this case, the management server ignores any
     configuration files that may be present, always reading its
     configuration data from the 'config.ini' file instead.

   * No configuration cache is found

     In this case, the management server reads the global configuration
     file and creates a cache containing the same configuration data as
     found in the file.

Configuration cache files

The management server by default creates configuration cache files in a
directory named 'mysql-cluster' in the MySQL installation directory.
(If you build NDB Cluster from source on a Unix system, the default
location is '/usr/local/mysql-cluster'.)  This can be overridden at
runtime by starting the management server with the '--configdir' option.
Configuration cache files are binary files named according to the
pattern 'ndb_NODE_ID_config.bin.SEQ_ID', where NODE_ID is the management
server's node ID in the cluster, and SEQ_ID is a cache idenitifer.
Cache files are numbered sequentially using SEQ_ID, in the order in
which they are created.  The management server uses the latest cache
file as determined by the SEQ_ID.

*Note*:

It is possible to roll back to a previous configuration by deleting
later configuration cache files, or by renaming an earlier cache file so
that it has a higher SEQ_ID.  However, since configuration cache files
are written in a binary format, you should not attempt to edit their
contents by hand.

For more information about the '--configdir', '--config-cache',
'--initial', and '--reload' options for the NDB Cluster management
server, see mysql-cluster-programs-ndb-mgmd.

We are continuously making improvements in Cluster configuration and
attempting to simplify this process.  Although we strive to maintain
backward compatibility, there may be times when introduce an
incompatible change.  In such cases we will try to let Cluster users
know in advance if a change is not backward compatible.  If you find
such a change and we have not documented it, please report it in the
MySQL bugs database using the instructions given in bug-reports.

21.3.3.1 NDB Cluster Configuration: Basic Example
.................................................

To support NDB Cluster, you will need to update 'my.cnf' as shown in the
following example.  You may also specify these parameters on the command
line when invoking the executables.

*Note*:

The options shown here should not be confused with those that are used
in 'config.ini' global configuration files.  Global configuration
options are discussed later in this section.

     # my.cnf
     # example additions to my.cnf for NDB Cluster
     # (valid in MySQL 5.7)

     # enable ndbcluster storage engine, and provide connection string for
     # management server host (default port is 1186)
     [mysqld]
     ndbcluster
     ndb-connectstring=ndb_mgmd.mysql.com

     # provide connection string for management server host (default port: 1186)
     [ndbd]
     connect-string=ndb_mgmd.mysql.com

     # provide connection string for management server host (default port: 1186)
     [ndb_mgm]
     connect-string=ndb_mgmd.mysql.com

     # provide location of cluster configuration file
     [ndb_mgmd]
     config-file=/etc/config.ini

(For more information on connection strings, see
mysql-cluster-connection-strings.)

     # my.cnf
     # example additions to my.cnf for NDB Cluster
     # (will work on all versions)

     # enable ndbcluster storage engine, and provide connection string for management
     # server host to the default port 1186
     [mysqld]
     ndbcluster
     ndb-connectstring=ndb_mgmd.mysql.com:1186

*Important*:

Once you have started a 'mysqld' process with the
'NDBCLUSTER' and 'ndb-connectstring' parameters in the
'[mysqld]' in the 'my.cnf' file as shown previously, you cannot execute
any 'CREATE TABLE' or 'ALTER TABLE'
statements without having actually started the cluster.
Otherwise, these statements will fail with an error.  _This is by
design_.

You may also use a separate '[mysql_cluster]' section in the cluster
'my.cnf' file for settings to be read and used by all executables:

     # cluster-specific settings
     [mysql_cluster]
     ndb-connectstring=ndb_mgmd.mysql.com:1186

For additional 'NDB' variables that can be set in
the 'my.cnf' file, see mysql-cluster-system-variables.

The NDB Cluster global configuration file is by convention named
'config.ini' (but this is not required).  If needed, it is read by
'ndb_mgmd' at startup and can be
placed in any location that can be read by it.  The location and name of
the configuration are specified using '--config-file=PATH_NAME' with
'ndb_mgmd' on the command line.
This option has no default value, and is ignored if 'ndb_mgmd'
uses the configuration cache.

The global configuration file for NDB Cluster uses INI format, which
consists of sections preceded by section headings (surrounded by square
brackets), followed by the appropriate parameter names and values.  One
deviation from the standard INI format is that the parameter name and
value can be separated by a colon (':') as well as the equal sign ('=');
however, the equal sign is preferred.  Another deviation is that
sections are not uniquely identified by section name.  Instead, unique
sections (such as two different nodes of the same type) are identified
by a unique ID specified as a parameter within the section.

Default values are defined for most parameters, and can also be
specified in 'config.ini'.  To create a default value section, simply
add the word 'default' to the section name.  For example, an '[ndbd]'
section contains parameters that apply to a particular data node,
whereas an '[ndbd default]' section contains parameters that apply to
all data nodes.  Suppose that all data nodes should use the same data
memory size.  To configure them all, create an '[ndbd default]' section
that contains a 'DataMemory' line to specify the data memory size.

*Note*:

In some older releases of NDB Cluster, there was no default value for
'NoOfReplicas', which always had to be specified explicitly in the
'[ndbd default]' section.  Although this parameter now has a default
value of 2, which is the recommended setting in most common usage
scenarios, it is still recommended practice to set this parameter
explicitly.

The global configuration file must define the computers and nodes
involved in the cluster and on which computers these nodes are located.
An example of a simple configuration file for a cluster consisting of
one management server, two data nodes and two MySQL servers is shown
here:

     # file "config.ini" - 2 data nodes and 2 SQL nodes
     # This file is placed in the startup directory of ndb_mgmd (the
     # management server)
     # The first MySQL Server can be started from any host. The second
     # can be started only on the host mysqld_5.mysql.com

     [ndbd default]
     NoOfReplicas= 2
     DataDir= /var/lib/mysql-cluster

     [ndb_mgmd]
     Hostname= ndb_mgmd.mysql.com
     DataDir= /var/lib/mysql-cluster

     [ndbd]
     HostName= ndbd_2.mysql.com

     [ndbd]
     HostName= ndbd_3.mysql.com

     [mysqld]
     [mysqld]
     HostName= mysqld_5.mysql.com

*Note*:

The preceding example is intended as a minimal starting configuration
for purposes of familiarization with NDB Cluster , and is almost certain
not to be sufficient for production settings.  See
mysql-cluster-config-starting, which provides a more complete example
starting configuration.

Each node has its own section in the 'config.ini' file.  For example,
this cluster has two data nodes, so the preceding configuration file
contains two '[ndbd]' sections defining these nodes.

*Note*:

Do not place comments on the same line as a section heading in the
'config.ini' file; this causes the management server not to start
because it cannot parse the configuration file in such cases.

*Sections of the config.ini File*

There are six different sections that you can use in the 'config.ini'
configuration file, as described in the following list:

   * '[computer]': Defines cluster hosts.  This is not required to
     configure a viable NDB Cluster, but be may used as a convenience
     when setting up a large cluster.  See
     mysql-cluster-computer-definition, for more information.

   * '[ndbd]': Defines a cluster data node (see 'ndbd'
     process).  See
     mysql-cluster-ndbd-definition, for details.

   * '[mysqld]': Defines the cluster's MySQL server nodes (also called
     SQL or API nodes).  For a discussion of SQL node configuration, see
     mysql-cluster-api-definition.

   * '[mgm]' or '[ndb_mgmd]': Defines a cluster management server (MGM)
     node.  For information concerning the configuration of management
     nodes, see mysql-cluster-mgm-definition.

   * '[tcp]': Defines a TCP/IP connection between cluster nodes, with
     TCP/IP being the default connection protocol.  Normally, '[tcp]' or
     '[tcp default]' sections are not required to set up an NDB Cluster,
     as the cluster handles this automatically; however, it may be
     necessary in some situations to override the defaults provided by
     the cluster.  See mysql-cluster-tcp-definition, for
     information about available TCP/IP configuration parameters and how
     to use them.  (You may also find
     mysql-cluster-tcp-definition-direct to be of interest in some
     cases.)

   * '[shm]': Defines shared-memory connections between nodes.  In MySQL
     5.7, it is enabled by default, but should still be considered
     experimental.  For a discussion of SHM interconnects, see
     mysql-cluster-shm-definition.

   * '[sci]': Defines Scalable Coherent Interface connections between
     cluster data nodes.  Not supported in NDB 7.2 or later.

You can define 'default' values for each section.  NDB Cluster parameter
names are case-insensitive, unless specified in MySQL Server 'my.cnf' or
'my.ini' files.

21.3.3.2 Recommended Starting Configuration for NDB Cluster
...........................................................

Achieving the best performance from an NDB Cluster depends on a number
of factors including the following:

   * NDB Cluster software version

   * Numbers of data nodes and SQL nodes

   * Hardware

   * Operating system

   * Amount of data to be stored

   * Size and type of load under which the cluster is to operate

Therefore, obtaining an optimum configuration is likely to be an
iterative process, the outcome of which can vary widely with the
specifics of each NDB Cluster deployment.  Changes in configuration are
also likely to be indicated when changes are made in the platform on
which the cluster is run, or in applications that use the NDB Cluster 's
data.  For these reasons, it is not possible to offer a single
configuration that is ideal for all usage scenarios.  However, in this
section, we provide a recommended base configuration.

Starting config.ini file

The following 'config.ini' file is a recommended starting point for
configuring a cluster running NDB Cluster 7.5:

     # TCP PARAMETERS

     [tcp default]
     SendBufferMemory=2M
     ReceiveBufferMemory=2M

     # Increasing the sizes of these 2 buffers beyond the default values
     # helps prevent bottlenecks due to slow disk I/O.

     # MANAGEMENT NODE PARAMETERS

     [ndb_mgmd default]
     DataDir=PATH/TO/MANAGEMENT/SERVER/DATA/DIRECTORY

     # It is possible to use a different data directory for each management
     # server, but for ease of administration it is preferable to be
     # consistent.

     [ndb_mgmd]
     HostName=MANAGEMENT-SERVER-A-HOSTNAME
     # NodeId=MANAGEMENT-SERVER-A-NODEID

     [ndb_mgmd]
     HostName=MANAGEMENT-SERVER-B-HOSTNAME
     # NodeId=MANAGEMENT-SERVER-B-NODEID

     # Using 2 management servers helps guarantee that there is always an
     # arbitrator in the event of network partitioning, and so is
     # recommended for high availability. Each management server must be
     # identified by a HostName. You may for the sake of convenience specify
     # a NodeId for any management server, although one will be allocated
     # for it automatically; if you do so, it must be in the range 1-255
     # inclusive and must be unique among all IDs specified for cluster
     # nodes.

     # DATA NODE PARAMETERS

     [ndbd default]
     NoOfReplicas=2

     # Using 2 replicas is recommended to guarantee availability of data;
     # using only 1 replica does not provide any redundancy, which means
     # that the failure of a single data node causes the entire cluster to
     # shut down. We do not recommend using more than 2 replicas, since 2 is
     # sufficient to provide high availability, and we do not currently test
     # with greater values for this parameter.

     LockPagesInMainMemory=1

     # On Linux and Solaris systems, setting this parameter locks data node
     # processes into memory. Doing so prevents them from swapping to disk,
     # which can severely degrade cluster performance.

     DataMemory=3072M
     IndexMemory=384M

     # The values provided for DataMemory and IndexMemory assume 4 GB RAM
     # per data node. However, for best results, you should first calculate
     # the memory that would be used based on the data you actually plan to
     # store (you may find the ndb_size.pl utility helpful in estimating
     # this), then allow an extra 20% over the calculated values. Naturally,
     # you should ensure that each data node host has at least as much
     # physical memory as the sum of these two values.

     # ODirect=1

     # Enabling this parameter causes NDBCLUSTER to try using O_DIRECT
     # writes for local checkpoints and redo logs; this can reduce load on
     # CPUs. We recommend doing so when using NDB Cluster on systems running
     # Linux kernel 2.6 or later.

     NoOfFragmentLogFiles=300
     DataDir=PATH/TO/DATA/NODE/DATA/DIRECTORY
     MaxNoOfConcurrentOperations=100000

     SchedulerSpinTimer=400
     SchedulerExecutionTimer=100
     RealTimeScheduler=1
     # Setting these parameters allows you to take advantage of real-time scheduling
     # of NDB threads to achieve increased throughput when using ndbd. They
     # are not needed when using ndbmtd.; in particular, you should not set
     # RealTimeScheduler for ndbmtd data nodes.

     TimeBetweenGlobalCheckpoints=1000
     TimeBetweenEpochs=200
     RedoBuffer=32M

     # CompressedLCP=1
     # CompressedBackup=1
     # Enabling CompressedLCP and CompressedBackup causes, respectively, local
     checkpoint files and backup files to be compressed, which can result in a space
     savings of up to 50% over noncompressed LCPs and backups.

     # MaxNoOfLocalScans=64
     MaxNoOfTables=1024
     MaxNoOfOrderedIndexes=256

     [ndbd]
     HostName=DATA-NODE-A-HOSTNAME
     # NodeId=DATA-NODE-A-NODEID

     LockExecuteThreadToCPU=1
     LockMaintThreadsToCPU=0
     # On systems with multiple CPUs, these parameters can be used to lock NDBCLUSTER
     # threads to specific CPUs

     [ndbd]
     HostName=DATA-NODE-B-HOSTNAME
     # NodeId=DATA-NODE-B-NODEID

     LockExecuteThreadToCPU=1
     LockMaintThreadsToCPU=0

     # You must have an [ndbd] section for every data node in the cluster;
     # each of these sections must include a HostName. Each section may
     # optionally include a NodeId for convenience, but in most cases, it is
     # sufficient to allow the cluster to allocate node IDs dynamically. If
     # you do specify the node ID for a data node, it must be in the range 1
     # to 48 inclusive and must be unique among all IDs specified for
     # cluster nodes.

     # SQL NODE / API NODE PARAMETERS

     [mysqld]
     # HostName=SQL-NODE-A-HOSTNAME
     # NodeId=SQL-NODE-A-NODEID

     [mysqld]

     [mysqld]

     # Each API or SQL node that connects to the cluster requires a [mysqld]
     # or [api] section of its own. Each such section defines a connection
     # 'slot'; you should have at least as many of these sections in the
     # config.ini file as the total number of API nodes and SQL nodes that
     # you wish to have connected to the cluster at any given time. There is
     # no performance or other penalty for having extra slots available in
     # case you find later that you want or need more API or SQL nodes to
     # connect to the cluster at the same time.
     # If no HostName is specified for a given [mysqld] or [api] section,
     # then _any_ API or SQL node may use that slot to connect to the
     # cluster. You may wish to use an explicit HostName for one connection slot
     # to guarantee that an API or SQL node from that host can always
     # connect to the cluster. If you wish to prevent API or SQL nodes from
     # connecting from other than a desired host or hosts, then use a
     # HostName for every [mysqld] or [api] section in the config.ini file.
     # You can if you wish define a node ID (NodeId parameter) for any API or
     # SQL node, but this is not necessary; if you do so, it must be in the
     # range 1 to 255 inclusive and must be unique among all IDs specified
     # for cluster nodes.

Recommended my.cnf options for SQL nodes

MySQL Servers acting as NDB Cluster SQL nodes must always be started
with the '--ndbcluster' and '--ndb-connectstring' options, either on the
command line or in 'my.cnf'.  In addition, set the following options for
all 'mysqld' processes in the cluster, unless your setup
requires otherwise:

   * '--ndb-use-exact-count=0'

   * '--ndb-index-stat-enable=0'

   * '--ndb-force-send=1'

   * '--engine-condition-pushdown=1'

21.3.3.3 NDB Cluster Connection Strings
.......................................

With the exception of the NDB Cluster management server (see
'ndb_mgmd'), each node that is part of
an NDB Cluster requires a _connection string_ that points to the
management server's location.  This connection string is used in
establishing a connection to the management server as well as in
performing other tasks depending on the node's role in the cluster.  The
syntax for a connection string is as follows:

     [nodeid=NODE_ID, ]HOST-DEFINITION[, HOST-DEFINITION[, ...]]

     HOST-DEFINITION:
         HOST_NAME[:PORT_NUMBER]

'node_id' is an integer greater than or equal to 1 which identifies a
node in 'config.ini'.  HOST_NAME is a string representing a valid
Internet host name or IP address.  PORT_NUMBER is an integer referring
to a TCP/IP port number.

     example 1 (long):    "nodeid=2,myhost1:1100,myhost2:1100,198.51.100.3:1200"
     example 2 (short):   "myhost1"

'localhost:1186' is used as the default connection string value if none
is provided.  If PORT_NUM is omitted from the connection string, the
default port is 1186.  This port should always be available on the
network because it has been assigned by IANA for this purpose (see
<http://www.iana.org/assignments/port-numbers> for details).

By listing multiple host definitions, it is possible to designate
several redundant management servers.  An NDB Cluster data or API node
attempts to contact successive management servers on each host in the
order specified, until a successful connection has been established.

It is also possible to specify in a connection string one or more bind
addresses to be used by nodes having multiple network interfaces for
connecting to management servers.  A bind address consists of a hostname
or network address and an optional port number.  This enhanced syntax
for connection strings is shown here:

     [nodeid=NODE_ID, ]
         [bind-address=HOST-DEFINITION, ]
         HOST-DEFINITION[; bind-address=HOST-DEFINITION]
         HOST-DEFINITION[; bind-address=HOST-DEFINITION]
         [, ...]]

     HOST-DEFINITION:
         HOST_NAME[:PORT_NUMBER]

If a single bind address is used in the connection string _prior_ to
specifying any management hosts, then this address is used as the
default for connecting to any of them (unless overridden for a given
management server; see later in this section for an example).  For
example, the following connection string causes the node to use
'198.51.100.242' regardless of the management server to which it
connects:

     bind-address=198.51.100.242, poseidon:1186, perch:1186

If a bind address is specified _following_ a management host definition,
then it is used only for connecting to that management node.  Consider
the following connection string:

     poseidon:1186;bind-address=localhost, perch:1186;bind-address=198.51.100.242

In this case, the node uses 'localhost' to connect to the management
server running on the host named 'poseidon' and '198.51.100.242' to
connect to the management server running on the host named 'perch'.

You can specify a default bind address and then override this default
for one or more specific management hosts.  In the following example,
'localhost' is used for connecting to the management server running on
host 'poseidon'; since '198.51.100.242' is specified first (before any
management server definitions), it is the default bind address and so is
used for connecting to the management servers on hosts 'perch' and
'orca':

     bind-address=198.51.100.242,poseidon:1186;bind-address=localhost,perch:1186,orca:2200

There are a number of different ways to specify the connection string:

   * Each executable has its own command-line option which enables
     specifying the management server at startup.  (See the
     documentation for the respective executable.)

   * It is also possible to set the connection string for all nodes in
     the cluster at once by placing it in a '[mysql_cluster]' section in
     the management server's 'my.cnf' file.

   * For backward compatibility, two other options are available, using
     the same syntax:

       1. Set the 'NDB_CONNECTSTRING' environment variable to contain
          the connection string.

       2. Write the connection string for each executable into a text
          file named 'Ndb.cfg' and place this file in the executable's
          startup directory.

     However, these are now deprecated and should not be used for new
     installations.

The recommended method for specifying the connection string is to set it
on the command line or in the 'my.cnf' file for each executable.

21.3.3.4 Defining Computers in an NDB Cluster
.............................................

The '[computer]' section has no real significance other than serving as
a way to avoid the need of defining host names for each node in the
system.  All parameters mentioned here are required.

   * 'Id'

     *This table provides type and value information for the Id computer
     configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      string

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     This is a unique identifier, used to refer to the host computer
     elsewhere in the configuration file.

     *Important*:

     The computer ID is _not_ the same as the node ID used for a
     management, API, or data node.  Unlike the case with node IDs, you
     cannot use 'NodeId' in place of 'Id' in the '[computer]' section of
     the 'config.ini' file.

   * 'HostName'

     *This table provides type and value information for the HostName
     computer configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     This is the computer's hostname or IP address.

21.3.3.5 Defining an NDB Cluster Management Server
..................................................

The '[ndb_mgmd]' section is used to configure the behavior of the
management server.  If multiple management servers are employed, you can
specify parameters common to all of them in an '[ndb_mgmd default]'
section.  '[mgm]' and '[mgm default]' are older aliases for these,
supported for backward compatibility.

All parameters in the following list are optional and assume their
default values if omitted.

*Note*:

If neither the 'ExecuteOnComputer' nor the 'HostName' parameter is
present, the default value 'localhost' will be assumed for both.

   *
     'Id'

     *This table provides type and value information for the Id
     management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              1 - 255

     *Restart Type.
     *

     Each node in the cluster has a unique identity.  For a management
     node, this is represented by an integer value in the range 1 to
     255, inclusive.  This ID is used by all internal cluster messages
     for addressing the node, and so must be unique for each NDB Cluster
     node, regardless of the type of node.

     *Note*:

     Data node IDs must be less than 49.  If you plan to deploy a large
     number of data nodes, it is a good idea to limit the node IDs for
     management nodes (and API nodes) to values greater than 48.

     The use of the 'Id' parameter for identifying management nodes is
     deprecated in favor of 'NodeId'.  Although 'Id' continues to be
     supported for backward compatibility, it now generates a warning
     and is subject to removal in a future version of NDB Cluster.

   *
     'NodeId'

     *This table provides type and value information for the NodeId
     management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              1 - 255

     *Restart Type.
     *

     Each node in the cluster has a unique identity.  For a management
     node, this is represented by an integer value in the range 1 to 255
     inclusive.  This ID is used by all internal cluster messages for
     addressing the node, and so must be unique for each NDB Cluster
     node, regardless of the type of node.

     *Note*:

     Data node IDs must be less than 49.  If you plan to deploy a large
     number of data nodes, it is a good idea to limit the node IDs for
     management nodes (and API nodes) to values greater than 48.

     'NodeId' is the preferred parameter name to use when identifying
     management nodes.  Although the older 'Id' continues to be
     supported for backward compatibility, it is now deprecated and
     generates a warning when used; it is also subject to removal in a
     future NDB Cluster release.

   *
     'ExecuteOnComputer'

     *This table provides type and value information for the
     ExecuteOnComputer management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     This refers to the 'Id' set for one of the computers defined in a
     '[computer]' section of the 'config.ini' file.

     *Important*:

     This parameter is deprecated as of NDB 7.5.0, and is subject to
     removal in a future release.  Use the 'HostName' parameter instead.

   *
     'PortNumber'

     *This table provides type and value information for the PortNumber
     management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            1186

     *Range*                              0 - 64K

     *Restart Type.
     *

     This is the port number on which the management server listens for
     configuration requests and management commands.

   *
     'HostName'

     *This table provides type and value information for the HostName
     management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     Specifying this parameter defines the hostname of the computer on
     which the management node is to reside.  To specify a hostname
     other than 'localhost', either this parameter or
     'ExecuteOnComputer' is required.

   *
     'LocationDomainId'

     *This table provides type and value information for the
     LocationDomainId management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 16

     *Restart Type.
     *

     Assigns a management node to a specific availability domain
     (https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm)
     (also known as an availability zone) within a cloud.  By informing
     'NDB' which nodes are in which availability domains, performance
     can be improved in a cloud environment in the following ways:

        * If requested data is not found on the same node, reads can be
          directed to another node in the same availability domain.

        * Communication between nodes in different availability domains
          are guaranteed to use 'NDB' transporters' WAN support without
          any further manual intervention.

        * The transporter's group number can be based on which
          availability domain is used, such that also SQL and other API
          nodes communicate with local data nodes in the same
          availability domain whenever possible.

        * The arbitrator can be selected from an availability domain in
          which no data nodes are present, or, if no such availability
          domain can be found, from a third availability domain.

     'LocationDomainId' takes an integer value between 0 and 16
     inclusive, with 0 being the default; using 0 is the same as leaving
     the parameter unset.

   *
     'LogDestination'

     *This table provides type and value information for the
     LogDestination management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      {CONSOLE|SYSLOG|FILE}

     *Default*                            [see text]

     *Range*                              ...

     *Restart Type.
     *

     This parameter specifies where to send cluster logging information.
     There are three options in this regard--'CONSOLE', 'SYSLOG', and
     'FILE'--with 'FILE' being the default:

        * 'CONSOLE' outputs the log to 'stdout':

               CONSOLE

        * 'SYSLOG' sends the log to a 'syslog' facility, possible values
          being one of 'auth', 'authpriv', 'cron', 'daemon', 'ftp',
          'kern', 'lpr', 'mail', 'news', 'syslog', 'user', 'uucp',
          'local0', 'local1', 'local2', 'local3', 'local4', 'local5',
          'local6', or 'local7'.

          *Note*:

          Not every facility is necessarily supported by every operating
          system.

               SYSLOG:facility=syslog

        * 'FILE' pipes the cluster log output to a regular file on the
          same machine.  The following values can be specified:

             * 'filename': The name of the log file.

               The default log file name used in such cases is
               'ndb_NODEID_cluster.log'.

             * 'maxsize': The maximum size (in bytes) to which the file
               can grow before logging rolls over to a new file.  When
               this occurs, the old log file is renamed by appending .N
               to the file name, where N is the next number not yet used
               with this name.

             * 'maxfiles': The maximum number of log files.

               FILE:filename=cluster.log,maxsize=1000000,maxfiles=6

          The default value for the 'FILE' parameter is
          'FILE:filename=ndb_NODE_ID_cluster.log,maxsize=1000000,maxfiles=6',
          where NODE_ID is the ID of the node.

     It is possible to specify multiple log destinations separated by
     semicolons as shown here:

          CONSOLE;SYSLOG:facility=local0;FILE:filename=/var/log/mgmd

   *
     'ArbitrationRank'

     *This table provides type and value information for the
     ArbitrationRank management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      0-2

     *Default*                            1

     *Range*                              0 - 2

     *Restart Type.
     *

     This parameter is used to define which nodes can act as
     arbitrators.  Only management nodes and SQL nodes can be
     arbitrators.  'ArbitrationRank' can take one of the following
     values:

        * '0': The node will never be used as an arbitrator.

        * '1': The node has high priority; that is, it will be preferred
          as an arbitrator over low-priority nodes.

        * '2': Indicates a low-priority node which be used as an
          arbitrator only if a node with a higher priority is not
          available for that purpose.

     Normally, the management server should be configured as an
     arbitrator by setting its 'ArbitrationRank' to 1 (the default for
     management nodes) and those for all SQL nodes to 0 (the default for
     SQL nodes).

     You can disable arbitration completely either by setting
     'ArbitrationRank' to 0 on all management and SQL nodes, or by
     setting the 'Arbitration' parameter in the '[ndbd default]' section
     of the 'config.ini' global configuration file.  Setting
     'Arbitration' causes any settings for 'ArbitrationRank' to be
     disregarded.

   *
     'ArbitrationDelay'

     *This table provides type and value information for the
     ArbitrationDelay management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     An integer value which causes the management server's responses to
     arbitration requests to be delayed by that number of milliseconds.
     By default, this value is 0; it is normally not necessary to change
     it.

   *
     'DataDir'

     *This table provides type and value information for the DataDir
     management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      path

     *Default*                            .

     *Range*                              ...

     *Restart Type.
     *

     This specifies the directory where output files from the management
     server will be placed.  These files include cluster log files,
     process output files, and the daemon's process ID (PID) file.  (For
     log files, this location can be overridden by setting the 'FILE'
     parameter for 'LogDestination' as discussed previously in this
     section.)

     The default value for this parameter is the directory in which
     'ndb_mgmd' is located.

   *
     'PortNumberStats'

     *This table provides type and value information for the
     PortNumberStats management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              0 - 64K

     *Restart Type.
     *

     This parameter specifies the port number used to obtain statistical
     information from an NDB Cluster management server.  It has no
     default value.

   *
     'Wan'

     *This table provides type and value information for the wan
     management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     Use WAN TCP setting as default.

   *
     'HeartbeatThreadPriority'

     *This table provides type and value information for the
     HeartbeatThreadPriority management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      string

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     Set the scheduling policy and priority of heartbeat threads for
     management and API nodes.

     The syntax for setting this parameter is shown here:

          HeartbeatThreadPriority = POLICY[, PRIORITY]

          POLICY:
            {FIFO | RR}

     When setting this parameter, you must specify a policy.  This is
     one of 'FIFO' (first in, first out) or 'RR' (round robin).  The
     policy value is followed optionally by the priority (an integer).

   *
     'TotalSendBufferMemory'

     *This table provides type and value information for the
     TotalSendBufferMemory management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            0

     *Range*                              256K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter is used to determine the total amount of memory to
     allocate on this node for shared send buffer memory among all
     configured transporters.

     If this parameter is set, its minimum permitted value is 256KB; 0
     indicates that the parameter has not been set.  For more detailed
     information, see mysql-cluster-config-send-buffers.

   *
     'HeartbeatIntervalMgmdMgmd'

     *This table provides type and value information for the
     HeartbeatIntervalMgmdMgmd management node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            1500

     *Range*                              100 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Specify the interval between heartbeat messages used to determine
     whether another management node is on contact with this one.  The
     management node waits after 3 of these intervals to declare the
     connection dead; thus, the default setting of 1500 milliseconds
     causes the management node to wait for approximately 1600 ms before
     timing out.

*Note*:

After making changes in a management node's configuration, it is
necessary to perform a rolling restart of the cluster for the new
configuration to take effect.

To add new management servers to a running NDB Cluster, it is also
necessary to perform a rolling restart of all cluster nodes after
modifying any existing 'config.ini' files.  For more information about
issues arising when using multiple management nodes, see
mysql-cluster-limitations-multiple-nodes.

21.3.3.6 Defining NDB Cluster Data Nodes
........................................

The '[ndbd]' and '[ndbd default]' sections are used to configure the
behavior of the cluster's data nodes.

'[ndbd]' and '[ndbd default]' are always used as the section names
whether you are using 'ndbd' or
'ndbmtd' binaries for the data
node processes.

There are many parameters which control buffer sizes, pool sizes,
timeouts, and so forth.  The only mandatory parameter is either one of
'ExecuteOnComputer' or 'HostName'; this must be defined in the local
'[ndbd]' section.

The parameter 'NoOfReplicas' should be defined in the '[ndbd default]'
section, as it is common to all Cluster data nodes.  It is not strictly
necessary to set 'NoOfReplicas', but it is good practice to set it
explicitly.

Most data node parameters are set in the '[ndbd default]' section.  Only
those parameters explicitly stated as being able to set local values are
permitted to be changed in the '[ndbd]' section.  Where present,
'HostName', 'NodeId' and 'ExecuteOnComputer' _must_ be defined in the
local '[ndbd]' section, and not in any other section of 'config.ini'.
In other words, settings for these parameters are specific to one data
node.

For those parameters affecting memory usage or buffer sizes, it is
possible to use 'K', 'M', or 'G' as a suffix to indicate units of 1024,
1024x1024, or 1024x1024x1024.  (For example, '100K' means 100 x 1024 =
102400.)

Parameter names and values are case-insensitive, unless used in a MySQL
Server 'my.cnf' or 'my.ini' file, in which case they are case sensitive.

Information about configuration parameters specific to NDB Cluster Disk
Data tables can be found later in this section (see
mysql-cluster-ndbd-definition-disk-data-parameters).

All of these parameters also apply to 'ndbmtd'.
(the multi-threaded version of
'ndbd').  Three additional data node
configuration parameters--'MaxNoOfExecutionThreads', 'ThreadConfig', and
'NoOfFragmentLogParts'--apply to 'ndbmtd'
only; these have no effect when used with
'ndbd'.  For more information, see
mysql-cluster-ndbd-definition-ndbmtd-parameters.  See also
mysql-cluster-programs-ndbmtd.

Identifying data nodes

The 'NodeId' or 'Id' value (that is, the data node identifier) can be
allocated on the command line when the node is started or in the
configuration file.

   *
     'NodeId'

     *This table provides type and value information for the NodeId data
     node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              1 - 48

     *Restart Type.
     *

     A unique node ID is used as the node's address for all cluster
     internal messages.  For data nodes, this is an integer in the range
     1 to 48 inclusive.  Each node in the cluster must have a unique
     identifier.

     'NodeId' is the only supported parameter name to use when
     identifying data nodes.  ('Id' was removed in NDB 7.5.0.)

   *
     'ExecuteOnComputer'

     *This table provides type and value information for the
     ExecuteOnComputer data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     This refers to the 'Id' set for one of the computers defined in a
     '[computer]' section.

     *Important*:

     This parameter is deprecated as of NDB 7.5.0, and is subject to
     removal in a future release.  Use the 'HostName' parameter instead.

   *
     'HostName'

     *This table provides type and value information for the HostName
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            localhost

     *Range*                              ...

     *Restart Type.
     *

     Specifying this parameter defines the hostname of the computer on
     which the data node is to reside.  To specify a hostname other than
     'localhost', either this parameter or 'ExecuteOnComputer' is
     required.

   *
     'ServerPort'

     *This table provides type and value information for the ServerPort
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              1 - 64K

     *Restart Type.
     *

     Each node in the cluster uses a port to connect to other nodes.  By
     default, this port is allocated dynamically in such a way as to
     ensure that no two nodes on the same host computer receive the same
     port number, so it should normally not be necessary to specify a
     value for this parameter.

     However, if you need to be able to open specific ports in a
     firewall to permit communication between data nodes and API nodes
     (including SQL nodes), you can set this parameter to the number of
     the desired port in an '[ndbd]' section or (if you need to do this
     for multiple data nodes) the '[ndbd default]' section of the
     'config.ini' file, and then open the port having that number for
     incoming connections from SQL nodes, API nodes, or both.

     *Note*:

     Connections from data nodes to management nodes is done using the
     'ndb_mgmd' management port
     (the management server's 'PortNumber') so outgoing connections to
     that port from any data nodes should always be permitted.

   * 'TcpBind_INADDR_ANY'

     Setting this parameter to 'TRUE' or '1' binds 'IP_ADDR_ANY' so that
     connections can be made from anywhere (for autogenerated
     connections).  The default is 'FALSE' ('0').

   *
     'NodeGroup'

     *This table provides type and value information for the NodeGroup
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*

     *Default*                            [none]

     *Range*                              0 - 65536

     *Restart Type.
     *

     This parameter can be used to assign a data node to a specific node
     group.  It is read only when the cluster is started for the first
     time, and cannot be used to reassign a data node to a different
     node group online.  It is generally not desirable to use this
     parameter in the '[ndbd default]' section of the 'config.ini' file,
     and care must be taken not to assign nodes to node groups in such a
     way that an invalid numbers of nodes are assigned to any node
     groups.

     The 'NodeGroup' parameter is chiefly intended for use in adding a
     new node group to a running NDB Cluster without having to perform a
     rolling restart.  For this purpose, you should set it to 65536 (the
     maximum value).  You are not required to set a 'NodeGroup' value
     for all cluster data nodes, only for those nodes which are to be
     started and added to the cluster as a new node group at a later
     time.  For more information, see
     mysql-cluster-online-add-node-example.

   *
     'LocationDomainId'

     *This table provides type and value information for the
     LocationDomainId data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 16

     *Restart Type.
     *

     Assigns a data node to a specific availability domain
     (https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm)
     (also known as an availability zone) within a cloud.  By informing
     'NDB' which nodes are in which availability domains, performance
     can be improved in a cloud environment in the following ways:

        * If requested data is not found on the same node, reads can be
          directed to another node in the same availability domain.

        * Communication between nodes in different availability domains
          are guaranteed to use 'NDB' transporters' WAN support without
          any further manual intervention.

        * The transporter's group number can be based on which
          availability domain is used, such that also SQL and other API
          nodes communicate with local data nodes in the same
          availability domain whenever possible.

        * The arbitrator can be selected from an availability domain in
          which no data nodes are present, or, if no such availability
          domain can be found, from a third availability domain.

     'LocationDomainId' takes an integer value between 0 and 16
     inclusive, with 0 being the default; using 0 is the same as leaving
     the parameter unset.

   *
     'NoOfReplicas'

     *This table provides type and value information for the
     NoOfReplicas data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            2

     *Range*                              1 - 4

     *Restart Type.
     *

     This global parameter can be set only in the '[ndbd default]'
     section, and defines the number of replicas for each table stored
     in the cluster.  This parameter also specifies the size of node
     groups.  A node group is a set of nodes all storing the same
     information.

     Node groups are formed implicitly.  The first node group is formed
     by the set of data nodes with the lowest node IDs, the next node
     group by the set of the next lowest node identities, and so on.  By
     way of example, assume that we have 4 data nodes and that
     'NoOfReplicas' is set to 2.  The four data nodes have node IDs 2,
     3, 4 and 5.  Then the first node group is formed from nodes 2 and
     3, and the second node group by nodes 4 and 5.  It is important to
     configure the cluster in such a manner that nodes in the same node
     groups are not placed on the same computer because a single
     hardware failure would cause the entire cluster to fail.

     If no node IDs are provided, the order of the data nodes will be
     the determining factor for the node group.  Whether or not explicit
     assignments are made, they can be viewed in the output of the
     management client's 'SHOW' command.

     The default value for 'NoOfReplicas' is 2.  _This is the
     recommended value for most production environments_.

     *Important*:

     While the maximum _possible_ value for this parameter is 4,
     *setting 'NoOfReplicas' to a value greater than 2 is not supported
     in production*.

     *Warning*:

     Setting 'NoOfReplicas' to 1 means that there is only a single copy
     of all Cluster data; in this case, the loss of a single data node
     causes the cluster to fail because there are no additional copies
     of the data stored by that node.

     The value for this parameter must divide evenly into the number of
     data nodes in the cluster.  For example, if there are two data
     nodes, then 'NoOfReplicas' must be equal to either 1 or 2, since
     2/3 and 2/4 both yield fractional values; if there are four data
     nodes, then 'NoOfReplicas' must be equal to 1, 2, or 4.

   *
     'DataDir'

     *This table provides type and value information for the DataDir
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      path

     *Default*                            .

     *Range*                              ...

     *Restart Type.
     *

     This parameter specifies the directory where trace files, log
     files, pid files and error logs are placed.

     The default is the data node process working directory.

   *
     'FileSystemPath'

     *This table provides type and value information for the
     FileSystemPath data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      path

     *Default*                            DataDir

     *Range*                              ...

     *Restart Type.
     *

     This parameter specifies the directory where all files created for
     metadata, REDO logs, UNDO logs (for Disk Data tables), and data
     files are placed.  The default is the directory specified by
     'DataDir'.

     *Note*:

     This directory must exist before the 'ndbd'
     process is initiated.

     The recommended directory hierarchy for NDB Cluster includes
     '/var/lib/mysql-cluster', under which a directory for the node's
     file system is created.  The name of this subdirectory contains the
     node ID. For example, if the node ID is 2, this subdirectory is
     named 'ndb_2_fs'.

   *
     'BackupDataDir'

     *This table provides type and value information for the
     BackupDataDir data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      path

     *Default*                            [see text]

     *Range*                              ...

     *Restart Type.
     *

     This parameter specifies the directory in which backups are placed.

     *Important*:

     The string ''/BACKUP'' is always appended to this value.  For
     example, if you set the value of 'BackupDataDir' to
     '/var/lib/cluster-data', then all backups are stored under
     '/var/lib/cluster-data/BACKUP'.  This also means that the
     _effective_ default backup location is the directory named 'BACKUP'
     under the location specified by the 'FileSystemPath' parameter.

*Data Memory, Index Memory, and String Memory*

'DataMemory' and 'IndexMemory' are '[ndbd]' parameters specifying the
size of memory segments used to store the actual records and their
indexes.  In setting values for these, it is important to understand how
'DataMemory' and 'IndexMemory' are used, as they usually need to be
updated to reflect actual usage by the cluster.

*Note*:

'IndexMemory' is deprecated in NDB 7.6, and subject to removal in a
future version of NDB Cluster.  See the descriptions that follow for
further information.

   *
     'DataMemory'

     *This table provides type and value information for the DataMemory
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            80M

     *Range*                              1M - 1T

     *Restart Type.
     *

     *Version (or later)*                 NDB 7.6.2

     *Type or units*                      bytes

     *Default*                            98M

     *Range*                              1M - 1T

     *Restart Type.
     *

     This parameter defines the amount of space (in bytes) available for
     storing database records.  The entire amount specified by this
     value is allocated in memory, so it is extremely important that the
     machine has sufficient physical memory to accommodate it.

     The memory allocated by 'DataMemory' is used to store both the
     actual records and indexes.  There is a 16-byte overhead on each
     record; an additional amount for each record is incurred because it
     is stored in a 32KB page with 128 byte page overhead (see below).
     There is also a small amount wasted per page due to the fact that
     each record is stored in only one page.

     For variable-size table attributes, the data is stored on separate
     data pages, allocated from 'DataMemory'.  Variable-length records
     use a fixed-size part with an extra overhead of 4 bytes to
     reference the variable-size part.  The variable-size part has 2
     bytes overhead plus 2 bytes per attribute.

     The maximum record size is 14000 bytes.

     In NDB 7.5 (and earlier), the memory space defined by 'DataMemory'
     is also used to store ordered indexes, which use about 10 bytes per
     record.  Each table row is represented in the ordered index.  A
     common error among users is to assume that all indexes are stored
     in the memory allocated by 'IndexMemory', but this is not the case:
     Only primary key and unique hash indexes use this memory; ordered
     indexes use the memory allocated by 'DataMemory'.  However,
     creating a primary key or unique hash index also creates an ordered
     index on the same keys, unless you specify 'USING HASH' in the
     index creation statement.  This can be verified by running
     'ndb_desc -d DB_NAME TABLE_NAME'.

     In NDB 7.6, resources assigned to 'DataMemory' are used for storing
     _all_ data and indexes; any memory configured as 'IndexMemory' is
     automatically added to that used by 'DataMemory' to form a common
     resource pool.

     Currently, NDB Cluster can use a maximum of 512 MB for hash indexes
     per partition, which means in some cases it is possible to get
     'Table is full' errors in MySQL client applications even when
     'ndb_mgm -e "ALL REPORT MEMORYUSAGE"'
     shows significant free
     'DataMemory'.  This can also pose a problem with data node restarts
     on nodes that are heavily loaded with data.

     In NDB 7.5.4 and later, you can control the number of partitions
     per local data manager for a given table by setting the 'NDB_TABLE'
     option 'PARTITION_BALANCE' to one of the values 'FOR_RA_BY_LDM',
     'FOR_RA_BY_LDM_X_2', 'FOR_RA_BY_LDM_X_3', or 'FOR_RA_BY_LDM_X_4',
     for 1, 2, 3, or 4 partitions per LDM, respectively, when creating
     the table (see create-table-ndb-table-comment-options).

     *Note*:

     In previous versions of NDB Cluster it was possible to create extra
     partitions for NDB Cluster tables and thus have more memory
     available for hash indexes by using the 'MAX_ROWS' option for
     'CREATE TABLE'.  While still supported for backward
     compatibility, using 'MAX_ROWS' for this purpose is deprecated
     beginning with NDB 7.5.4, where you should use 'PARTITION_BALANCE'
     instead.

     You can also use the 'MinFreePct' configuration parameter to help
     avoid problems with node restarts.

     The memory space allocated by 'DataMemory' consists of 32KB pages,
     which are allocated to table fragments.  Each table is normally
     partitioned into the same number of fragments as there are data
     nodes in the cluster.  Thus, for each node, there are the same
     number of fragments as are set in 'NoOfReplicas'.

     Once a page has been allocated, it is currently not possible to
     return it to the pool of free pages, except by deleting the table.
     (This also means that 'DataMemory' pages, once allocated to a given
     table, cannot be used by other tables.)  Performing a data node
     recovery also compresses the partition because all records are
     inserted into empty partitions from other live nodes.

     The 'DataMemory' memory space also contains UNDO information: For
     each update, a copy of the unaltered record is allocated in the
     'DataMemory'.  There is also a reference to each copy in the
     ordered table indexes.  Unique hash indexes are updated only when
     the unique index columns are updated, in which case a new entry in
     the index table is inserted and the old entry is deleted upon
     commit.  For this reason, it is also necessary to allocate enough
     memory to handle the largest transactions performed by applications
     using the cluster.  In any case, performing a few large
     transactions holds no advantage over using many smaller ones, for
     the following reasons:

        * Large transactions are not any faster than smaller ones

        * Large transactions increase the number of operations that are
          lost and must be repeated in event of transaction failure

        * Large transactions use more memory

     In NDB 7.5 (and earlier), the default value for 'DataMemory' is
     80MB; beginning with NDB 7.6.2, this is 98MB. The minimum value is
     1MB. There is no maximum size, but in reality the maximum size has
     to be adapted so that the process does not start swapping when the
     limit is reached.  This limit is determined by the amount of
     physical RAM available on the machine and by the amount of memory
     that the operating system may commit to any one process.  32-bit
     operating systems are generally limited to 2−4GB per process;
     64-bit operating systems can use more.  For large databases, it may
     be preferable to use a 64-bit operating system for this reason.

   *
     'IndexMemory'

     *This table provides type and value information for the IndexMemory
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            18M

     *Range*                              1M - 1T

     *Restart Type.
     *

     *Version (or later)*                 NDB 7.6.2

     *Type or units*                      bytes

     *Default*                            0

     *Range*                              1M - 1T

     *Restart Type.
     *

     In NDB 7.5 and earlier, this parameter controls the amount of
     storage used for hash indexes in NDB Cluster.  Hash indexes are
     always used for primary key indexes, unique indexes, and unique
     constraints.  When defining a primary key or a unique index, two
     indexes are created, one of which is a hash index used for all
     tuple accesses as well as lock handling.  This index is also used
     to enforce unique constraints.

     Beginning with NDB 7.6.2, the 'IndexMemory' parameter is deprecated
     (and subject to future removal); any any memory assigned to
     'IndexMemory' is allocated instead to the same pool as
     'DataMemory', which becomes solely responsible for all resources
     needed for storing data and indexes in memory.  In NDB 7.6.2 and
     later, the use of 'IndexMemory' in the cluster configuration file
     triggers a warning from the management server.

     You can estimate the size of a hash index using this formula:

            size  = ( (FRAGMENTS * 32K) + (ROWS * 18) )
                    * REPLICAS

     FRAGMENTS is the number of fragments, REPLICAS is the number of
     replicas (normally 2), and ROWS is the number of rows.  If a table
     has one million rows, 8 fragments, and 2 replicas, the expected
     index memory usage is calculated as shown here:

            ((8 * 32K) + (1000000 * 18)) * 2 = ((8 * 32768) + (1000000 * 18)) * 2
            = (262144 + 18000000) * 2
            = 18262144 * 2 = 36524288 bytes = ~35MB

     Index statistics for ordered indexes (when these are enabled) are
     stored in the 'mysql.ndb_index_stat_sample' table.  Since this
     table has a hash index, this adds to index memory usage.  An upper
     bound to the number of rows for a given ordered index can be
     calculated as follows:

            sample_size= key_size + ((key_attributes + 1) * 4)

            sample_rows = IndexStatSaveSize
                          * ((0.01 * IndexStatSaveScale * log2(rows * sample_size)) + 1)
                          / sample_size

     In the preceding formula, KEY_SIZE is the size of the ordered index
     key in bytes, KEY_ATTRIBUTES is the number ot attributes in the
     ordered index key, and ROWS is the number of rows in the base
     table.

     Assume that table 't1' has 1 million rows and an ordered index
     named 'ix1' on two four-byte integers.  Assume in addition that
     'IndexStatSaveSize' and 'IndexStatSaveScale' are set to their
     default values (32K and 100, respectively).  Using the previous 2
     formulas, we can calculate as follows:

            sample_size = 8  + ((1 + 2) * 4) = 20 bytes

            sample_rows = 32K
                          * ((0.01 * 100 * log2(1000000*20)) + 1)
                          / 20
                          = 32768 * ( (1 * ~16.811) +1) / 20
                          = 32768 * ~17.811 / 20
                          = ~29182 rows

     The expected index memory usage is thus 2 * 18 * 29182 = ~1050550
     bytes.

     Prior to NDB 7.6.2, the default value for 'IndexMemory' is 18MB and
     the minimum is 1 MB; in NDB 7.6.2 and later, the minimum and
     default vaue for this parameter is 0 (zero).

   *
     'StringMemory'

     *This table provides type and value information for the
     StringMemory data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      % or bytes

     *Default*                            25

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter determines how much memory is allocated for strings
     such as table names, and is specified in an '[ndbd]' or '[ndbd
     default]' section of the 'config.ini' file.  A value between '0'
     and '100' inclusive is interpreted as a percent of the maximum
     default value, which is calculated based on a number of factors
     including the number of tables, maximum table name size, maximum
     size of '.FRM' files, 'MaxNoOfTriggers', maximum column name size,
     and maximum default column value.

     A value greater than '100' is interpreted as a number of bytes.

     The default value is 25--that is, 25 percent of the default
     maximum.

     Under most circumstances, the default value should be sufficient,
     but when you have a great many 'NDB' tables (1000 or more), it is
     possible to get Error 773 'Out of string memory, please modify
     StringMemory config parameter: Permanent error: Schema error', in
     which case you should increase this value.  '25' (25 percent) is
     not excessive, and should prevent this error from recurring in all
     but the most extreme conditions.

The following example illustrates how memory is used for a table.
Consider this table definition:

     CREATE TABLE example (
       a INT NOT NULL,
       b INT NOT NULL,
       c INT NOT NULL,
       PRIMARY KEY(a),
       UNIQUE(b)
     ) ENGINE=NDBCLUSTER;

For each record, there are 12 bytes of data plus 12 bytes overhead.
Having no nullable columns saves 4 bytes of overhead.  In addition, we
have two ordered indexes on columns 'a' and 'b' consuming roughly 10
bytes each per record.  There is a primary key hash index on the base
table using roughly 29 bytes per record.  The unique constraint is
implemented by a separate table with 'b' as primary key and 'a' as a
column.  This other table consumes an additional 29 bytes of index
memory per record in the 'example' table as well 8 bytes of record data
plus 12 bytes of overhead.

Thus, for one million records, we need 58MB for index memory to handle
the hash indexes for the primary key and the unique constraint.  We also
need 64MB for the records of the base table and the unique index table,
plus the two ordered index tables.

You can see that hash indexes takes up a fair amount of memory space;
however, they provide very fast access to the data in return.  They are
also used in NDB Cluster to handle uniqueness constraints.

Currently, the only partitioning algorithm is hashing and ordered
indexes are local to each node.  Thus, ordered indexes cannot be used to
handle uniqueness constraints in the general case.

An important point for both 'IndexMemory' and 'DataMemory' is that the
total database size is the sum of all data memory and all index memory
for each node group.  Each node group is used to store replicated
information, so if there are four nodes with two replicas, there will be
two node groups.  Thus, the total data memory available is 2 x
'DataMemory' for each data node.

It is highly recommended that 'DataMemory' and 'IndexMemory' be set to
the same values for all nodes.  Data distribution is even over all nodes
in the cluster, so the maximum amount of space available for any node
can be no greater than that of the smallest node in the cluster.

'DataMemory' and 'IndexMemory' can be changed, but decreasing either of
these can be risky; doing so can easily lead to a node or even an entire
NDB Cluster that is unable to restart due to there being insufficient
memory space.  Increasing these values should be acceptable, but it is
recommended that such upgrades are performed in the same manner as a
software upgrade, beginning with an update of the configuration file,
and then restarting the management server followed by restarting each
data node in turn.

MinFreePct

A proportion (5% by default) of data node resources including
'DataMemory' and 'IndexMemory' is kept in reserve to insure that the
data node does not exhaust its memory when performing a restart.  This
can be adjusted using the 'MinFreePct' data node configuration parameter
(default 5).

*This table provides type and value information for the MinFreePct data
node configuration parameter*

Property                             Value

*Version (or later)*                 NDB 7.5.0

*Type or units*                      unsigned

*Default*                            5

*Range*                              0 - 100

*Restart Type.
*

Updates do not increase the amount of index memory used.  Inserts take
effect immediately; however, rows are not actually deleted until the
transaction is committed.

Transaction parameters

The next few '[ndbd]' parameters that we discuss are important because
they affect the number of parallel transactions and the sizes of
transactions that can be handled by the system.
'MaxNoOfConcurrentTransactions' sets the number of parallel transactions
possible in a node.  'MaxNoOfConcurrentOperations' sets the number of
records that can be in update phase or locked simultaneously.

Both of these parameters (especially 'MaxNoOfConcurrentOperations') are
likely targets for users setting specific values and not using the
default value.  The default value is set for systems using small
transactions, to ensure that these do not use excessive memory.

'MaxDMLOperationsPerTransaction' sets the maximum number of DML
operations that can be performed in a given transaction.

   *
     'MaxNoOfConcurrentTransactions'

     *This table provides type and value information for the
     MaxNoOfConcurrentTransactions data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            4096

     *Range*                              32 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Each cluster data node requires a transaction record for each
     active transaction in the cluster.  The task of coordinating
     transactions is distributed among all of the data nodes.  The total
     number of transaction records in the cluster is the number of
     transactions in any given node times the number of nodes in the
     cluster.

     Transaction records are allocated to individual MySQL servers.
     Each connection to a MySQL server requires at least one transaction
     record, plus an additional transaction object per table accessed by
     that connection.  This means that a reasonable minimum for the
     total number of transactions in the cluster can be expressed as

          TotalNoOfConcurrentTransactions =
              (maximum number of tables accessed in any single transaction + 1)
              * number of SQL nodes

     Suppose that there are 10 SQL nodes using the cluster.  A single
     join involving 10 tables requires 11 transaction records; if there
     are 10 such joins in a transaction, then 10 * 11 = 110 transaction
     records are required for this transaction, per MySQL server, or 110
     * 10 = 1100 transaction records total.  Each data node can be
     expected to handle TotalNoOfConcurrentTransactions / number of data
     nodes.  For an NDB Cluster having 4 data nodes, this would mean
     setting 'MaxNoOfConcurrentTransactions' on each data node to 1100 /
     4 = 275.  In addition, you should provide for failure recovery by
     ensuring that a single node group can accommodate all concurrent
     transactions; in other words, that each data node's
     MaxNoOfConcurrentTransactions is sufficient to cover a number of
     transactions equal to TotalNoOfConcurrentTransactions / number of
     node groups.  If this cluster has a single node group, then
     'MaxNoOfConcurrentTransactions' should be set to 1100 (the same as
     the total number of concurrent transactions for the entire
     cluster).

     In addition, each transaction involves at least one operation; for
     this reason, the value set for 'MaxNoOfConcurrentTransactions'
     should always be no more than the value of
     'MaxNoOfConcurrentOperations'.

     This parameter must be set to the same value for all cluster data
     nodes.  This is due to the fact that, when a data node fails, the
     oldest surviving node re-creates the transaction state of all
     transactions that were ongoing in the failed node.

     It is possible to change this value using a rolling restart, but
     the amount of traffic on the cluster must be such that no more
     transactions occur than the lower of the old and new levels while
     this is taking place.

     The default value is 4096.

   *
     'MaxNoOfConcurrentOperations'

     *This table provides type and value information for the
     MaxNoOfConcurrentOperations data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            32K

     *Range*                              32 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     It is a good idea to adjust the value of this parameter according
     to the size and number of transactions.  When performing
     transactions which involve only a few operations and records, the
     default value for this parameter is usually sufficient.  Performing
     large transactions involving many records usually requires that you
     increase its value.

     Records are kept for each transaction updating cluster data, both
     in the transaction coordinator and in the nodes where the actual
     updates are performed.  These records contain state information
     needed to find UNDO records for rollback, lock queues, and other
     purposes.

     This parameter should be set at a minimum to the number of records
     to be updated simultaneously in transactions, divided by the number
     of cluster data nodes.  For example, in a cluster which has four
     data nodes and which is expected to handle one million concurrent
     updates using transactions, you should set this value to 1000000 /
     4 = 250000.  To help provide resiliency against failures, it is
     suggested that you set this parameter to a value that is high
     enough to permit an individual data node to handle the load for its
     node group.  In other words, you should set the value equal to
     'total number of concurrent operations / number of node groups'.
     (In the case where there is a single node group, this is the same
     as the total number of concurrent operations for the entire
     cluster.)

     Because each transaction always involves at least one operation,
     the value of 'MaxNoOfConcurrentOperations' should always be greater
     than or equal to the value of 'MaxNoOfConcurrentTransactions'.

     Read queries which set locks also cause operation records to be
     created.  Some extra space is allocated within individual nodes to
     accommodate cases where the distribution is not perfect over the
     nodes.

     When queries make use of the unique hash index, there are actually
     two operation records used per record in the transaction.  The
     first record represents the read in the index table and the second
     handles the operation on the base table.

     The default value is 32768.

     This parameter actually handles two values that can be configured
     separately.  The first of these specifies how many operation
     records are to be placed with the transaction coordinator.  The
     second part specifies how many operation records are to be local to
     the database.

     A very large transaction performed on an eight-node cluster
     requires as many operation records in the transaction coordinator
     as there are reads, updates, and deletes involved in the
     transaction.  However, the operation records of the are spread over
     all eight nodes.  Thus, if it is necessary to configure the system
     for one very large transaction, it is a good idea to configure the
     two parts separately.  'MaxNoOfConcurrentOperations' will always be
     used to calculate the number of operation records in the
     transaction coordinator portion of the node.

     It is also important to have an idea of the memory requirements for
     operation records.  These consume about 1KB per record.

   *
     'MaxNoOfLocalOperations'

     *This table provides type and value information for the
     MaxNoOfLocalOperations data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            UNDEFINED

     *Range*                              32 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     By default, this parameter is calculated as 1.1 x
     'MaxNoOfConcurrentOperations'.  This fits systems with many
     simultaneous transactions, none of them being very large.  If there
     is a need to handle one very large transaction at a time and there
     are many nodes, it is a good idea to override the default value by
     explicitly specifying this parameter.

   *
     'MaxDMLOperationsPerTransaction'

     *This table provides type and value information for the
     MaxDMLOperationsPerTransaction data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      operations (DML)

     *Default*                            4294967295

     *Range*                              32 - 4294967295

     *Restart Type.
     *

     This parameter limits the size of a transaction.  The transaction
     is aborted if it requires more than this many DML operations.  The
     minimum number of operations per transaction is 32; however, you
     can set 'MaxDMLOperationsPerTransaction' to 0 to disable any
     limitation on the number of DML operations per transaction.  The
     maximum (and default) is 4294967295.

Transaction temporary storage

The next set of '[ndbd]' parameters is used to determine temporary
storage when executing a statement that is part of a Cluster
transaction.  All records are released when the statement is completed
and the cluster is waiting for the commit or rollback.

The default values for these parameters are adequate for most
situations.  However, users with a need to support transactions
involving large numbers of rows or operations may need to increase these
values to enable better parallelism in the system, whereas users whose
applications require relatively small transactions can decrease the
values to save memory.

   *
     'MaxNoOfConcurrentIndexOperations'

     *This table provides type and value information for the
     MaxNoOfConcurrentIndexOperations data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            8K

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     For queries using a unique hash index, another temporary set of
     operation records is used during a query's execution phase.  This
     parameter sets the size of that pool of records.  Thus, this record
     is allocated only while executing a part of a query.  As soon as
     this part has been executed, the record is released.  The state
     needed to handle aborts and commits is handled by the normal
     operation records, where the pool size is set by the parameter
     'MaxNoOfConcurrentOperations'.

     The default value of this parameter is 8192.  Only in rare cases of
     extremely high parallelism using unique hash indexes should it be
     necessary to increase this value.  Using a smaller value is
     possible and can save memory if the DBA is certain that a high
     degree of parallelism is not required for the cluster.

   *
     'MaxNoOfFiredTriggers'

     *This table provides type and value information for the
     MaxNoOfFiredTriggers data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            4000

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     The default value of 'MaxNoOfFiredTriggers' is 4000, which is
     sufficient for most situations.  In some cases it can even be
     decreased if the DBA feels certain the need for parallelism in the
     cluster is not high.

     A record is created when an operation is performed that affects a
     unique hash index.  Inserting or deleting a record in a table with
     unique hash indexes or updating a column that is part of a unique
     hash index fires an insert or a delete in the index table.  The
     resulting record is used to represent this index table operation
     while waiting for the original operation that fired it to complete.
     This operation is short-lived but can still require a large number
     of records in its pool for situations with many parallel write
     operations on a base table containing a set of unique hash indexes.

   *
     'TransactionBufferMemory'

     *This table provides type and value information for the
     TransactionBufferMemory data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            1M

     *Range*                              1K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     The memory affected by this parameter is used for tracking
     operations fired when updating index tables and reading unique
     indexes.  This memory is used to store the key and column
     information for these operations.  It is only very rarely that the
     value for this parameter needs to be altered from the default.

     The default value for 'TransactionBufferMemory' is 1MB.

     Normal read and write operations use a similar buffer, whose usage
     is even more short-lived.  The compile-time parameter
     'ZATTRBUF_FILESIZE' (found in
     'ndb/src/kernel/blocks/Dbtc/Dbtc.hpp') set to 4000 x 128 bytes
     (500KB). A similar buffer for key information, 'ZDATABUF_FILESIZE'
     (also in 'Dbtc.hpp') contains 4000 x 16 = 62.5KB of buffer space.
     'Dbtc' is the module that handles transaction coordination.

Scans and buffering

There are additional '[ndbd]' parameters in the 'Dblqh' module (in
'ndb/src/kernel/blocks/Dblqh/Dblqh.hpp') that affect reads and updates.
These include 'ZATTRINBUF_FILESIZE', set by default to 10000 x 128 bytes
(1250KB) and 'ZDATABUF_FILE_SIZE', set by default to 10000*16 bytes
(roughly 156KB) of buffer space.  To date, there have been neither any
reports from users nor any results from our own extensive tests
suggesting that either of these compile-time limits should be increased.

   *
     'BatchSizePerLocalScan'

     *This table provides type and value information for the
     BatchSizePerLocalScan data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            256

     *Range*                              1 - 992

     *Restart Type.
     *

     This parameter is used to calculate the number of lock records used
     to handle concurrent scan operations.

     'BatchSizePerLocalScan' has a strong connection to the 'BatchSize'
     defined in the SQL nodes.

   *
     'LongMessageBuffer'

     *This table provides type and value information for the
     LongMessageBuffer data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            64M

     *Range*                              512K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This is an internal buffer used for passing messages within
     individual nodes and between nodes.  The default is 64MB.

     This parameter seldom needs to be changed from the default.

   *
     'MaxFKBuildBatchSize'

     *This table provides type and value information for the
     MaxFKBuildBatchSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      integer

     *Default*                            64

     *Range*                              16 - 512

     *Restart Type.
     *

     Maximum scan batch size used for building foreign keys.  Increasing
     the value set for this parameter may speed up building of foreign
     key builds at the expense of greater impact to ongoing traffic.

     Added in NDB 7.6.4

   *
     'MaxNoOfConcurrentScans'

     *This table provides type and value information for the
     MaxNoOfConcurrentScans data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            256

     *Range*                              2 - 500

     *Restart Type.
     *

     This parameter is used to control the number of parallel scans that
     can be performed in the cluster.  Each transaction coordinator can
     handle the number of parallel scans defined for this parameter.
     Each scan query is performed by scanning all partitions in
     parallel.  Each partition scan uses a scan record in the node where
     the partition is located, the number of records being the value of
     this parameter times the number of nodes.  The cluster should be
     able to sustain 'MaxNoOfConcurrentScans' scans concurrently from
     all nodes in the cluster.

     Scans are actually performed in two cases.  The first of these
     cases occurs when no hash or ordered indexes exists to handle the
     query, in which case the query is executed by performing a full
     table scan.  The second case is encountered when there is no hash
     index to support the query but there is an ordered index.  Using
     the ordered index means executing a parallel range scan.  The order
     is kept on the local partitions only, so it is necessary to perform
     the index scan on all partitions.

     The default value of 'MaxNoOfConcurrentScans' is 256.  The maximum
     value is 500.

   *
     'MaxNoOfLocalScans'

     *This table provides type and value information for the
     MaxNoOfLocalScans data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            [see text]

     *Range*                              32 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Specifies the number of local scan records if many scans are not
     fully parallelized.  When the number of local scan records is not
     provided, it is calculated as shown here:

          4 * MaxNoOfConcurrentScans * [# data nodes] + 2

     The minimum value is 32.

   *
     'MaxParallelCopyInstances'

     *This table provides type and value information for the
     MaxParallelCopyInstances data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 64

     *Restart Type.
     *

     This parameter sets the parallelization used in the copy phase of a
     node restart or system restart, when a node that is currently just
     starting is synchronised with a node that already has current data
     by copying over any changed records from the node that is up to
     date.  Because full parallelism in such cases can lead to overload
     situations, 'MaxParallelCopyInstances' provides a means to decrease
     it.  This parameter's default value 0.  This value means that the
     effective parallelism is equal to the number of LDM instances in
     the node just starting as well as the node updating it.

   *
     'MaxParallelScansPerFragment'

     *This table provides type and value information for the
     MaxParallelScansPerFragment data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            256

     *Range*                              1 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     It is possible to configure the maximum number of parallel scans
     ('TUP' scans and 'TUX' scans) allowed before they begin queuing for
     serial handling.  You can increase this to take advantage of any
     unused CPU when performing large number of scans in parallel and
     improve their performance.

     The default value for this parameter is 256.

   *
     'MaxReorgBuildBatchSize'

     *This table provides type and value information for the
     MaxReorgBuildBatchSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      integer

     *Default*                            64

     *Range*                              16 - 512

     *Restart Type.
     *

     Maximum scan batch size used for reorganization of table
     partitions.  Increasing the value set for this parameter may speed
     up reorganization at the expense of greater impact to ongoing
     traffic.

     Added in NDB 7.6.4

   *
     'MaxUIBuildBatchSize'

     *This table provides type and value information for the
     MaxUIBuildBatchSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      integer

     *Default*                            64

     *Range*                              16 - 512

     *Restart Type.
     *

     Maximum scan batch size used for building unique keys.  Increasing
     the value set for this parameter may speed up such builds at the
     expense of greater impact to ongoing traffic.

     Added in NDB 7.6.4

*Memory Allocation*

'MaxAllocate'

*This table provides type and value information for the MaxAllocate data
node configuration parameter*

Property                             Value

*Version (or later)*                 NDB 7.5.0

*Type or units*                      unsigned

*Default*                            32M

*Range*                              1M - 1G

*Restart Type.
*

This is the maximum size of the memory unit to use when allocating
memory for tables.  In cases where 'NDB' gives
'Out of memory' errors, but it is evident by examining the cluster logs
or the output of 'DUMP 1000'
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-dump-commands.html)
that all available memory has not yet been used, you can increase the
value of this parameter (or 'MaxNoOfTables', or both) to cause
'NDB' to make sufficient memory available.

*Hash Map Size*

'DefaultHashMapSize'

*This table provides type and value information for the
DefaultHashMapSize data node configuration parameter*

Property                             Value

*Version (or later)*                 NDB 7.5.0

*Type or units*                      LDM threads

*Default*                            3840

*Range*                              0 - 3840

*Restart Type.
*

The size of the table hash maps used by 'NDB' is
configurable using this parameter.  'DefaultHashMapSize' can take any of
three possible values (0, 240, 3840).  These values and their effects
are described in the following table:

*DefaultHashMapSize parameters*

Value          Description / Effect

'0'            Use the lowest value set, if any, for this parameter
               among all data nodes and API nodes in the cluster; if it
               is not set on any data or API node, use the default
               value.

'240'          Original hash map size (used by default in all NDB
               Cluster releases prior to NDB 7.2.7)

'3840'         Larger hash map size (used by default beginning with NDB
               7.2.7)

The original intended use for this parameter was to facilitate upgrades
and especially downgrades to and from very old releases with differing
default hash map sizes.  This is not an issue when upgrading from NDB
Cluster 7.4 to NDB Cluster 7.5.

Logging and checkpointing

The following '[ndbd]' parameters control log and checkpoint behavior.

   *
     'FragmentLogFileSize'

     *This table provides type and value information for the
     FragmentLogFileSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            16M

     *Range*                              4M - 1G

     *Restart Type.
     *

     Setting this parameter enables you to control directly the size of
     redo log files.  This can be useful in situations when NDB Cluster
     is operating under a high load and it is unable to close fragment
     log files quickly enough before attempting to open new ones (only 2
     fragment log files can be open at one time); increasing the size of
     the fragment log files gives the cluster more time before having to
     open each new fragment log file.  The default value for this
     parameter is 16M.

     For more information about fragment log files, see the description
     for 'NoOfFragmentLogFiles'.

   *
     'InitialNoOfOpenFiles'

     *This table provides type and value information for the
     InitialNoOfOpenFiles data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      files

     *Default*                            27

     *Range*                              20 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets the initial number of internal threads to
     allocate for open files.

     The default value is 27.

   *
     'InitFragmentLogFiles'

     *This table provides type and value information for the
     InitFragmentLogFiles data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      [see values]

     *Default*                            SPARSE

     *Range*                              SPARSE, FULL

     *Restart Type.
     *

     By default, fragment log files are created sparsely when performing
     an initial start of a data node--that is, depending on the
     operating system and file system in use, not all bytes are
     necessarily written to disk.  However, it is possible to override
     this behavior and force all bytes to be written, regardless of the
     platform and file system type being used, by means of this
     parameter.  'InitFragmentLogFiles' takes either of two values:

        * 'SPARSE'.  Fragment log files are created sparsely.  This is
          the default value.

        * 'FULL'.  Force all bytes of the fragment log file to be
          written to disk.

     Depending on your operating system and file system, setting
     'InitFragmentLogFiles=FULL' may help eliminate I/O errors on writes
     to the REDO log.

   *
     'EnablePartialLcp'

     When 'true', enable partial local checkpoints: This means that each
     LCP records only part of the full database, plus any records
     containing rows changed since the last LCP; if no rows have
     changed, the LCP updates only the LCP control file and does not
     update any data files.

     If 'EnablePartialLcp' is disabled ('false'), each LCP uses only a
     single file and writes a full checkpoint; this requires the least
     amount of disk space for LCPs, but increases the write load for
     each LCP. The default value is enabled ('true').  The proportion of
     space used by partiaL LCPS can be modified by the setting for the
     'RecoveryWork' configuration parameter.

   *
     'LcpScanProgressTimeout'

     *This table provides type and value information for the
     LcpScanProgressTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      second

     *Default*                            60

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     A local checkpoint fragment scan watchdog checks periodically for
     no progress in each fragment scan performed as part of a local
     checkpoint, and shuts down the node if there is no progress after a
     given amount of time has elapsed.  This interval can be set using
     the 'LcpScanProgressTimeout' data node configuration parameter,
     which sets the maximum time for which the local checkpoint can be
     stalled before the LCP fragment scan watchdog shuts down the node.

     The default value is 60 seconds (providing compatibility with
     previous releases).  Setting this parameter to 0 disables the LCP
     fragment scan watchdog altogether.

   *
     'MaxNoOfOpenFiles'

     *This table provides type and value information for the
     MaxNoOfOpenFiles data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              20 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets a ceiling on how many internal threads to
     allocate for open files.  _Any situation requiring a change in this
     parameter should be reported as a bug_.

     The default value is 0.  However, the minimum value to which this
     parameter can be set is 20.

   *
     'MaxNoOfSavedMessages'

     *This table provides type and value information for the
     MaxNoOfSavedMessages data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            25

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets the maximum number of errors written in the
     error log as well as the maximum number of trace files that are
     kept before overwriting the existing ones.  Trace files are
     generated when, for whatever reason, the node crashes.

     The default is 25, which sets these maximums to 25 error messages
     and 25 trace files.

   *
     'MaxLCPStartDelay'

     *This table provides type and value information for the
     MaxLCPStartDelay data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      seconds

     *Default*                            0

     *Range*                              0 - 600

     *Restart Type.
     *

     In parallel data node recovery, only table data is actually copied
     and synchronized in parallel; synchronization of metadata such as
     dictionary and checkpoint information is done in a serial fashion.
     In addition, recovery of dictionary and checkpoint information
     cannot be executed in parallel with performing of local
     checkpoints.  This means that, when starting or restarting many
     data nodes concurrently, data nodes may be forced to wait while a
     local checkpoint is performed, which can result in longer node
     recovery times.

     It is possible to force a delay in the local checkpoint to permit
     more (and possibly all) data nodes to complete metadata
     synchronization; once each data node's metadata synchronization is
     complete, all of the data nodes can recover table data in parallel,
     even while the local checkpoint is being executed.  To force such a
     delay, set 'MaxLCPStartDelay', which determines the number of
     seconds the cluster can wait to begin a local checkpoint while data
     nodes continue to synchronize metadata.  This parameter should be
     set in the '[ndbd default]' section of the 'config.ini' file, so
     that it is the same for all data nodes.  The maximum value is 600;
     the default is 0.

   *
     'NoOfFragmentLogFiles'

     *This table provides type and value information for the
     NoOfFragmentLogFiles data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            16

     *Range*                              3 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets the number of REDO log files for the node, and
     thus the amount of space allocated to REDO logging.  Because the
     REDO log files are organized in a ring, it is extremely important
     that the first and last log files in the set (sometimes referred to
     as the 'head' and 'tail' log files, respectively) do not meet.
     When these approach one another too closely, the node begins
     aborting all transactions encompassing updates due to a lack of
     room for new log records.

     A 'REDO' log record is not removed until both required local
     checkpoints have been completed since that log record was inserted.
     Checkpointing frequency is determined by its own set of
     configuration parameters discussed elsewhere in this chapter.

     The default parameter value is 16, which by default means 16 sets
     of 4 16MB files for a total of 1024MB. The size of the individual
     log files is configurable using the 'FragmentLogFileSize'
     parameter.  In scenarios requiring a great many updates, the value
     for 'NoOfFragmentLogFiles' may need to be set as high as 300 or
     even higher to provide sufficient space for REDO logs.

     If the checkpointing is slow and there are so many writes to the
     database that the log files are full and the log tail cannot be cut
     without jeopardizing recovery, all updating transactions are
     aborted with internal error code 410 ('Out of log file space
     temporarily').  This condition prevails until a checkpoint has
     completed and the log tail can be moved forward.

     *Important*:

     This parameter cannot be changed 'on the fly'; you must restart the
     node using '--initial'.  If you wish to change this value for all
     data nodes in a running cluster, you can do so using a rolling node
     restart (using '--initial' when starting each data node).

   *
     'RecoveryWork'

     This parameter has an effect only when 'EnablePartialLcp' is true,
     that is, only when partial local checkpoints are enabled.  A higher
     value means:

        * Fewer records are written for each LCP, LCPs use more space

        * More work is needed during restarts

     A lower value for 'RecoveryWork' means:

        * More records are written during each LCP, but LCPs require
          less space on disk.

        * Less work during restart and thus faster restarts, at the
          expense of more work during normal operations

Metadata objects

The next set of '[ndbd]' parameters defines pool sizes for metadata
objects, used to define the maximum number of attributes, tables,
indexes, and trigger objects used by indexes, events, and replication
between clusters.

*Note*:

These act merely as 'suggestions' to the cluster, and any that are not
specified revert to the default values shown.

   *
     'MaxNoOfAttributes'

     *This table provides type and value information for the
     MaxNoOfAttributes data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            1000

     *Range*                              32 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets a suggested maximum number of attributes that
     can be defined in the cluster; like 'MaxNoOfTables', it is not
     intended to function as a hard upper limit.

     (In older NDB Cluster releases, this parameter was sometimes
     treated as a hard limit for certain operations.  This caused
     problems with NDB Cluster Replication, when it was possible to
     create more tables than could be replicated, and sometimes led to
     confusion when it was possible [or not possible, depending on the
     circumstances] to create more than 'MaxNoOfAttributes' attributes.)

     The default value is 1000, with the minimum possible value being
     32.  The maximum is 4294967039.  Each attribute consumes around 200
     bytes of storage per node due to the fact that all metadata is
     fully replicated on the servers.

     When setting 'MaxNoOfAttributes', it is important to prepare in
     advance for any 'ALTER TABLE' statements that
     you might want to perform in the future.  This is due to the fact,
     during the execution of 'ALTER TABLE' on a
     Cluster table, 3 times the number of attributes as in the original
     table are used, and a good practice is to permit double this
     amount.  For example, if the NDB Cluster table having the greatest
     number of attributes (GREATEST_NUMBER_OF_ATTRIBUTES) has 100
     attributes, a good starting point for the value of
     'MaxNoOfAttributes' would be '6 * GREATEST_NUMBER_OF_ATTRIBUTES =
     600'.

     You should also estimate the average number of attributes per table
     and multiply this by 'MaxNoOfTables'.  If this value is larger than
     the value obtained in the previous paragraph, you should use the
     larger value instead.

     Assuming that you can create all desired tables without any
     problems, you should also verify that this number is sufficient by
     trying an actual 'ALTER TABLE' after
     configuring the parameter.  If this is not successful, increase
     'MaxNoOfAttributes' by another multiple of 'MaxNoOfTables' and test
     it again.

   *
     'MaxNoOfTables'

     *This table provides type and value information for the
     MaxNoOfTables data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            128

     *Range*                              8 - 20320

     *Restart Type.
     *

     A table object is allocated for each table and for each unique hash
     index in the cluster.  This parameter sets a suggested maximum
     number of table objects for the cluster as a whole; like
     'MaxNoOfAttributes', it is not intended to function as a hard upper
     limit.

     (In older NDB Cluster releases, this parameter was sometimes
     treated as a hard limit for certain operations.  This caused
     problems with NDB Cluster Replication, when it was possible to
     create more tables than could be replicated, and sometimes led to
     confusion when it was possible [or not possible, depending on the
     circumstances] to create more than 'MaxNoOfTables' tables.)

     For each attribute that has a 'BLOB' data type an
     extra table is used to store most of the 'BLOB' data.
     These tables also must be taken into account when defining the
     total number of tables.

     The default value of this parameter is 128.  The minimum is 8 and
     the maximum is 20320.  Each table object consumes approximately
     20KB per node.

     *Note*:

     The sum of 'MaxNoOfTables', 'MaxNoOfOrderedIndexes', and
     'MaxNoOfUniqueHashIndexes' must not exceed '2^32 − 2'
     (4294967294).

   *
     'MaxNoOfOrderedIndexes'

     *This table provides type and value information for the
     MaxNoOfOrderedIndexes data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            128

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     For each ordered index in the cluster, an object is allocated
     describing what is being indexed and its storage segments.  By
     default, each index so defined also defines an ordered index.  Each
     unique index and primary key has both an ordered index and a hash
     index.  'MaxNoOfOrderedIndexes' sets the total number of ordered
     indexes that can be in use in the system at any one time.

     The default value of this parameter is 128.  Each index object
     consumes approximately 10KB of data per node.

     *Note*:

     The sum of 'MaxNoOfTables', 'MaxNoOfOrderedIndexes', and
     'MaxNoOfUniqueHashIndexes' must not exceed '2^32 − 2'
     (4294967294).

   *
     'MaxNoOfUniqueHashIndexes'

     *This table provides type and value information for the
     MaxNoOfUniqueHashIndexes data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            64

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     For each unique index that is not a primary key, a special table is
     allocated that maps the unique key to the primary key of the
     indexed table.  By default, an ordered index is also defined for
     each unique index.  To prevent this, you must specify the 'USING
     HASH' option when defining the unique index.

     The default value is 64.  Each index consumes approximately 15KB
     per node.

     *Note*:

     The sum of 'MaxNoOfTables', 'MaxNoOfOrderedIndexes', and
     'MaxNoOfUniqueHashIndexes' must not exceed '2^32 − 2'
     (4294967294).

   *
     'MaxNoOfTriggers'

     *This table provides type and value information for the
     MaxNoOfTriggers data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            768

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Internal update, insert, and delete triggers are allocated for each
     unique hash index.  (This means that three triggers are created for
     each unique hash index.)  However, an _ordered_ index requires only
     a single trigger object.  Backups also use three trigger objects
     for each normal table in the cluster.

     Replication between clusters also makes use of internal triggers.

     This parameter sets the maximum number of trigger objects in the
     cluster.

     The default value is 768.

   *
     'MaxNoOfSubscriptions'

     *This table provides type and value information for the
     MaxNoOfSubscriptions data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Each 'NDB' table in an NDB Cluster requires a
     subscription in the NDB kernel.  For some NDB API applications, it
     may be necessary or desirable to change this parameter.  However,
     for normal usage with MySQL servers acting as SQL nodes, there is
     not any need to do so.

     The default value for 'MaxNoOfSubscriptions' is 0, which is treated
     as equal to 'MaxNoOfTables'.  Each subscription consumes 108 bytes.

   *
     'MaxNoOfSubscribers'

     *This table provides type and value information for the
     MaxNoOfSubscribers data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter is of interest only when using NDB Cluster
     Replication.  The default value is 0, which is treated as '2 *
     MaxNoOfTables'; that is, there is one subscription per 'NDB'
     table for each of two MySQL servers (one acting as
     the replication master and the other as the slave).  Each
     subscriber uses 16 bytes of memory.

     When using circular replication, multi-master replication, and
     other replication setups involving more than 2 MySQL servers, you
     should increase this parameter to the number of 'mysqld'
     processes included in replication (this is often, but not
     always, the same as the number of clusters).  For example, if you
     have a circular replication setup using three NDB Cluster s, with
     one 'mysqld' attached to each cluster, and each of
     these 'mysqld' processes acts as a master and as a
     slave, you should set 'MaxNoOfSubscribers' equal to '3 *
     MaxNoOfTables'.

     For more information, see mysql-cluster-replication.

   *
     'MaxNoOfConcurrentSubOperations'

     *This table provides type and value information for the
     MaxNoOfConcurrentSubOperations data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            256

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets a ceiling on the number of operations that can
     be performed by all API nodes in the cluster at one time.  The
     default value (256) is sufficient for normal operations, and might
     need to be adjusted only in scenarios where there are a great many
     API nodes each performing a high volume of operations concurrently.

Boolean parameters

The behavior of data nodes is also affected by a set of '[ndbd]'
parameters taking on boolean values.  These parameters can each be
specified as 'TRUE' by setting them equal to '1' or 'Y', and as 'FALSE'
by setting them equal to '0' or 'N'.

   *
     'LateAlloc'

     *This table provides type and value information for the LateAlloc
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            1

     *Range*                              0 - 1

     *Restart Type.
     *

     Allocate memory for this data node after a connection to the
     management server has been established.  Enabled by default.

   *
     'LockPagesInMainMemory'

     *This table provides type and value information for the
     LockPagesInMainMemory data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            0

     *Range*                              0 - 2

     *Restart Type.
     *

     For a number of operating systems, including Solaris and Linux, it
     is possible to lock a process into memory and so avoid any swapping
     to disk.  This can be used to help guarantee the cluster's
     real-time characteristics.

     This parameter takes one of the integer values '0', '1', or '2',
     which act as shown in the following list:

        * '0': Disables locking.  This is the default value.

        * '1': Performs the lock after allocating memory for the
          process.

        * '2': Performs the lock before memory for the process is
          allocated.

     If the operating system is not configured to permit unprivileged
     users to lock pages, then the data node process making use of this
     parameter may have to be run as system root.
     ('LockPagesInMainMemory' uses the 'mlockall' function.  From Linux
     kernel 2.6.9, unprivileged users can lock memory as limited by 'max
     locked memory'.  For more information, see 'ulimit -l' and
     <http://linux.die.net/man/2/mlock>).

     *Note*:

     In older NDB Cluster releases, this parameter was a Boolean.  '0'
     or 'false' was the default setting, and disabled locking.  '1' or
     'true' enabled locking of the process after its memory was
     allocated.  NDB Cluster 7.5 treats 'true' or 'false' for the value
     of this parameter as an error.

     *Important*:

     Beginning with 'glibc' 2.10, 'glibc' uses per-thread arenas to
     reduce lock contention on a shared pool, which consumes real
     memory.  In general, a data node process does not need per-thread
     arenas, since it does not perform any memory allocation after
     startup.  (This difference in allocators does not appear to affect
     performance significantly.)

     The 'glibc' behavior is intended to be configurable via the
     'MALLOC_ARENA_MAX' environment variable, but a bug in this
     mechanism prior to 'glibc' 2.16 meant that this variable could not
     be set to less than 8, so that the wasted memory could not be
     reclaimed.  (Bug #15907219; see also
     <http://sourceware.org/bugzilla/show_bug.cgi?id=13137> for more
     information concerning this issue.)

     One possible workaround for this problem is to use the 'LD_PRELOAD'
     environment variable to preload a 'jemalloc' memory allocation
     library to take the place of that supplied with 'glibc'.

   *
     'StopOnError'

     *This table provides type and value information for the StopOnError
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            1

     *Range*                              0, 1

     *Restart Type.
     *

     This parameter specifies whether a data node process should exit or
     perform an automatic restart when an error condition is
     encountered.

     This parameter's default value is 1; this means that, by default,
     an error causes the data node process to halt.

     When an error is encountered and 'StopOnError' is 0, the data node
     process is restarted.

     Prior to NDB Cluster 7.5.5, if the data node process exits in an
     uncontrolled fashion (due, for example, to performing 'kill -9'
     on the data node process while performing a query, or to
     a segmentation fault), and 'StopOnError' is set to 0, the angel
     process attempts to restart it in exactly the same way as it was
     started previously--that is, using the same startup options that
     were employed the last time the node was started.  Thus, if the
     data node process was originally started using the '--initial'
     option, it is also restarted with '--initial'.  This means that, in
     such cases, if the failure occurs on a sufficient number of data
     nodes in a very short interval, the effect is the same as if you
     had performed an initial restart of the entire cluster, leading to
     loss of all data.  This issue is resolved in NDB Cluster 7.5.5 and
     later NDB 7.5 releases (Bug #83510, Bug #24945638).

     Users of MySQL Cluster Manager should note that, when 'StopOnError'
     equals 1, this prevents the MySQL Cluster Manager agent from
     restarting any data nodes after it has performed its own restart
     and recovery.  See Starting and Stopping the Agent on Linux
     (http://dev.mysql.com/doc/mysql-cluster-manager/1.4/en/mcm-using-start-stop-agent-linux.html),
     for more information.

   *
     'CrashOnCorruptedTuple'

     *This table provides type and value information for the
     CrashOnCorruptedTuple data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            true

     *Range*                              true, false

     *Restart Type.
     *

     When this parameter is enabled, it forces a data node to shut down
     whenever it encounters a corrupted tuple.  In NDB 7.5, it is
     enabled by default.

   *
     'Diskless'

     *This table provides type and value information for the Diskless
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      true|false (1|0)

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     It is possible to specify NDB Cluster tables as _diskless_, meaning
     that tables are not checkpointed to disk and that no logging
     occurs.  Such tables exist only in main memory.  A consequence of
     using diskless tables is that neither the tables nor the records in
     those tables survive a crash.  However, when operating in diskless
     mode, it is possible to run 'ndbd'
     on a diskless computer.

     *Important*:

     This feature causes the _entire_ cluster to operate in diskless
     mode.

     When this feature is enabled, Cluster online backup is disabled.
     In addition, a partial start of the cluster is not possible.

     'Diskless' is disabled by default.

   *
     'ODirect'

     *This table provides type and value information for the ODirect
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     Enabling this parameter causes 'NDB' to
     attempt using 'O_DIRECT' writes for LCP, backups, and redo logs,
     often lowering 'kswapd' and CPU usage.  When using NDB Cluster on
     Linux, enable 'ODirect' if you are using a 2.6 or later kernel.

     'ODirect' is disabled by default.

   *
     'ODirectSyncFlag'

     *This table provides type and value information for the
     ODirectSyncFlag data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     When this parameter is enabled, redo log writes are performed such
     that each completed file system write is handled as a call to
     'fsync'.  The setting for this parameter is ignored if at least one
     of the following conditions is true:

        * 'ODirect' is not enabled.

        * 'InitFragmentLogFiles' is set to 'SPARSE'.

     Disabled by default.

   *
     'RestartOnErrorInsert'

     *This table provides type and value information for the
     RestartOnErrorInsert data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      error code

     *Default*                            2

     *Range*                              0 - 4

     *Restart Type.
     *

     This feature is accessible only when building the debug version
     where it is possible to insert errors in the execution of
     individual blocks of code as part of testing.

     This feature is disabled by default.

   *
     'CompressedBackup'

     *This table provides type and value information for the
     CompressedBackup data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     Enabling this parameter causes backup files to be compressed.  The
     compression used is equivalent to 'gzip --fast', and can save 50%
     or more of the space required on the data node to store
     uncompressed backup files.  Compressed backups can be enabled for
     individual data nodes, or for all data nodes (by setting this
     parameter in the '[ndbd default]' section of the 'config.ini'
     file).

     *Important*:

     You cannot restore a compressed backup to a cluster running a MySQL
     version that does not support this feature.

     The default value is '0' (disabled).

   *
     'CompressedLCP'

     *This table provides type and value information for the
     CompressedLCP data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     Setting this parameter to '1' causes local checkpoint files to be
     compressed.  The compression used is equivalent to 'gzip --fast',
     and can save 50% or more of the space required on the data node to
     store uncompressed checkpoint files.  Compressed LCPs can be
     enabled for individual data nodes, or for all data nodes (by
     setting this parameter in the '[ndbd default]' section of the
     'config.ini' file).

     *Important*:

     You cannot restore a compressed local checkpoint to a cluster
     running a MySQL version that does not support this feature.

     The default value is '0' (disabled).

*Controlling Timeouts, Intervals, and Disk Paging*

There are a number of '[ndbd]' parameters specifying timeouts and
intervals between various actions in Cluster data nodes.  Most of the
timeout values are specified in milliseconds.  Any exceptions to this
are mentioned where applicable.

   *
     'TimeBetweenWatchDogCheck'

     *This table provides type and value information for the
     TimeBetweenWatchDogCheck data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            6000

     *Range*                              70 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     To prevent the main thread from getting stuck in an endless loop at
     some point, a 'watchdog' thread checks the main thread.  This
     parameter specifies the number of milliseconds between checks.  If
     the process remains in the same state after three checks, the
     watchdog thread terminates it.

     This parameter can easily be changed for purposes of
     experimentation or to adapt to local conditions.  It can be
     specified on a per-node basis although there seems to be little
     reason for doing so.

     The default timeout is 6000 milliseconds (6 seconds).

   *
     'TimeBetweenWatchDogCheckInitial'

     *This table provides type and value information for the
     TimeBetweenWatchDogCheckInitial data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            6000

     *Range*                              70 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This is similar to the 'TimeBetweenWatchDogCheck' parameter, except
     that 'TimeBetweenWatchDogCheckInitial' controls the amount of time
     that passes between execution checks inside a storage node in the
     early start phases during which memory is allocated.

     The default timeout is 6000 milliseconds (6 seconds).

   *
     'StartPartialTimeout'

     *This table provides type and value information for the
     StartPartialTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            30000

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter specifies how long the Cluster waits for all data
     nodes to come up before the cluster initialization routine is
     invoked.  This timeout is used to avoid a partial Cluster startup
     whenever possible.

     This parameter is overridden when performing an initial start or
     initial restart of the cluster.

     The default value is 30000 milliseconds (30 seconds).  0 disables
     the timeout, in which case the cluster may start only if all nodes
     are available.

   *
     'StartPartitionedTimeout'

     *This table provides type and value information for the
     StartPartitionedTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            60000

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     If the cluster is ready to start after waiting for
     'StartPartialTimeout' milliseconds but is still possibly in a
     partitioned state, the cluster waits until this timeout has also
     passed.  If 'StartPartitionedTimeout' is set to 0, the cluster
     waits indefinitely.

     This parameter is overridden when performing an initial start or
     initial restart of the cluster.

     The default timeout is 60000 milliseconds (60 seconds).

   *
     'StartFailureTimeout'

     *This table provides type and value information for the
     StartFailureTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     If a data node has not completed its startup sequence within the
     time specified by this parameter, the node startup fails.  Setting
     this parameter to 0 (the default value) means that no data node
     timeout is applied.

     For nonzero values, this parameter is measured in milliseconds.
     For data nodes containing extremely large amounts of data, this
     parameter should be increased.  For example, in the case of a data
     node containing several gigabytes of data, a period as long as
     10−15 minutes (that is, 600000 to 1000000 milliseconds) might be
     required to perform a node restart.

   *
     'StartNoNodeGroupTimeout'

     *This table provides type and value information for the
     StartNoNodeGroupTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            15000

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When a data node is configured with 'Nodegroup = 65536', is
     regarded as not being assigned to any node group.  When that is
     done, the cluster waits 'StartNoNodegroupTimeout' milliseconds,
     then treats such nodes as though they had been added to the list
     passed to the '--nowait-nodes' option, and starts.  The default
     value is '15000' (that is, the management server waits 15 seconds).
     Setting this parameter equal to '0' means that the cluster waits
     indefinitely.

     'StartNoNodegroupTimeout' must be the same for all data nodes in
     the cluster; for this reason, you should always set it in the
     '[ndbd default]' section of the 'config.ini' file, rather than for
     individual data nodes.

     See mysql-cluster-online-add-node, for more information.

   *
     'HeartbeatIntervalDbDb'

     *This table provides type and value information for the
     HeartbeatIntervalDbDb data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            5000

     *Range*                              10 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     One of the primary methods of discovering failed nodes is by the
     use of heartbeats.  This parameter states how often heartbeat
     signals are sent and how often to expect to receive them.
     Heartbeats cannot be disabled.

     After missing four heartbeat intervals in a row, the node is
     declared dead.  Thus, the maximum time for discovering a failure
     through the heartbeat mechanism is five times the heartbeat
     interval.

     The default heartbeat interval is 5000 milliseconds (5 seconds).
     This parameter must not be changed drastically and should not vary
     widely between nodes.  If one node uses 5000 milliseconds and the
     node watching it uses 1000 milliseconds, obviously the node will be
     declared dead very quickly.  This parameter can be changed during
     an online software upgrade, but only in small increments.

     See also mysql-cluster-network-latency-issues, as well as
     the description of the 'ConnectCheckIntervalDelay' configuration
     parameter.

   *
     'HeartbeatIntervalDbApi'

     *This table provides type and value information for the
     HeartbeatIntervalDbApi data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            1500

     *Range*                              100 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Each data node sends heartbeat signals to each MySQL server (SQL
     node) to ensure that it remains in contact.  If a MySQL server
     fails to send a heartbeat in time it is declared 'dead,' in which
     case all ongoing transactions are completed and all resources
     released.  The SQL node cannot reconnect until all activities
     initiated by the previous MySQL instance have been completed.  The
     three-heartbeat criteria for this determination are the same as
     described for 'HeartbeatIntervalDbDb'.

     The default interval is 1500 milliseconds (1.5 seconds).  This
     interval can vary between individual data nodes because each data
     node watches the MySQL servers connected to it, independently of
     all other data nodes.

     For more information, see
     mysql-cluster-network-latency-issues.

   *
     'HeartbeatOrder'

     *This table provides type and value information for the
     HeartbeatOrder data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            0

     *Range*                              0 - 65535

     *Restart Type.
     *

     Data nodes send heartbeats to one another in a circular fashion
     whereby each data node monitors the previous one.  If a heartbeat
     is not detected by a given data node, this node declares the
     previous data node in the circle 'dead' (that is, no longer
     accessible by the cluster).  The determination that a data node is
     dead is done globally; in other words; once a data node is declared
     dead, it is regarded as such by all nodes in the cluster.

     It is possible for heartbeats between data nodes residing on
     different hosts to be too slow compared to heartbeats between other
     pairs of nodes (for example, due to a very low heartbeat interval
     or temporary connection problem), such that a data node is declared
     dead, even though the node can still function as part of the
     cluster.  .

     In this type of situation, it may be that the order in which
     heartbeats are transmitted between data nodes makes a difference as
     to whether or not a particular data node is declared dead.  If this
     declaration occurs unnecessarily, this can in turn lead to the
     unnecessary loss of a node group and as thus to a failure of the
     cluster.

     Consider a setup where there are 4 data nodes A, B, C, and D
     running on 2 host computers 'host1' and 'host2', and that these
     data nodes make up 2 node groups, as shown in the following table:

     *Four data nodes A, B, C, D running on two host computers host1,
     host2; each data node belongs to one of two node groups.*

     Node Group               Nodes Running on         Nodes Running on
                              'host1'                  'host2'

     _Node Group 0_:          Node A                   Node B

     _Node Group 1_:          Node C                   Node D

     Suppose the heartbeats are transmitted in the order A->B->C->D->A.
     In this case, the loss of the heartbeat between the hosts causes
     node B to declare node A dead and node C to declare node B dead.
     This results in loss of Node Group 0, and so the cluster fails.  On
     the other hand, if the order of transmission is A->B->D->C->A (and
     all other conditions remain as previously stated), the loss of the
     heartbeat causes nodes A and D to be declared dead; in this case,
     each node group has one surviving node, and the cluster survives.

     The 'HeartbeatOrder' configuration parameter makes the order of
     heartbeat transmission user-configurable.  The default value for
     'HeartbeatOrder' is zero; allowing the default value to be used on
     all data nodes causes the order of heartbeat transmission to be
     determined by 'NDB'.  If this parameter is used, it must be set to
     a nonzero value (maximum 65535) for every data node in the cluster,
     and this value must be unique for each data node; this causes the
     heartbeat transmission to proceed from data node to data node in
     the order of their 'HeartbeatOrder' values from lowest to highest
     (and then directly from the data node having the highest
     'HeartbeatOrder' to the data node having the lowest value, to
     complete the circle).  The values need not be consecutive; for
     example, to force the heartbeat transmission order A->B->D->C->A in
     the scenario outlined previously, you could set the
     'HeartbeatOrder' values as shown here:

     *HeartbeatOrder values to force a heartbeat transition order of
     A->B->D->C->A.*

     Node                                 'HeartbeatOrder' Value

     A                                    10

     B                                    20

     C                                    30

     D                                    25

     To use this parameter to change the heartbeat transmission order in
     a running NDB Cluster, you must first set 'HeartbeatOrder' for each
     data node in the cluster in the global configuration ('config.ini')
     file (or files).  To cause the change to take effect, you must
     perform either of the following:

        * A complete shutdown and restart of the entire cluster.

        * 2 rolling restarts of the cluster in succession.  _All nodes
          must be restarted in the same order in both rolling restarts_.

     You can use 'DUMP 908'
     (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-dump-commands.html)
     to observe the effect of this parameter in the data node logs.

   *
     'ConnectCheckIntervalDelay'

     *This table provides type and value information for the
     ConnectCheckIntervalDelay data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter enables connection checking between data nodes after
     one of them has failed heartbeat checks for 5 intervals of up to
     'HeartbeatIntervalDbDb' milliseconds.

     Such a data node that further fails to respond within an interval
     of 'ConnectCheckIntervalDelay' milliseconds is considered suspect,
     and is considered dead after two such intervals.  This can be
     useful in setups with known latency issues.

     The default value for this parameter is 0 (disabled).

   *
     'TimeBetweenLocalCheckpoints'

     *This table provides type and value information for the
     TimeBetweenLocalCheckpoints data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      number of 4-byte words, as a
                                          base-2 logarithm

     *Default*                            20

     *Range*                              0 - 31

     *Restart Type.
     *

     This parameter is an exception in that it does not specify a time
     to wait before starting a new local checkpoint; rather, it is used
     to ensure that local checkpoints are not performed in a cluster
     where relatively few updates are taking place.  In most clusters
     with high update rates, it is likely that a new local checkpoint is
     started immediately after the previous one has been completed.

     The size of all write operations executed since the start of the
     previous local checkpoints is added.  This parameter is also
     exceptional in that it is specified as the base-2 logarithm of the
     number of 4-byte words, so that the default value 20 means 4MB (4 x
     2^20) of write operations, 21 would mean 8MB, and so on up to a
     maximum value of 31, which equates to 8GB of write operations.

     All the write operations in the cluster are added together.
     Setting 'TimeBetweenLocalCheckpoints' to 6 or less means that local
     checkpoints will be executed continuously without pause,
     independent of the cluster's workload.

   *
     'TimeBetweenGlobalCheckpoints'

     *This table provides type and value information for the
     TimeBetweenGlobalCheckpoints data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            2000

     *Range*                              20 - 32000

     *Restart Type.
     *

     When a transaction is committed, it is committed in main memory in
     all nodes on which the data is mirrored.  However, transaction log
     records are not flushed to disk as part of the commit.  The
     reasoning behind this behavior is that having the transaction
     safely committed on at least two autonomous host machines should
     meet reasonable standards for durability.

     It is also important to ensure that even the worst of cases--a
     complete crash of the cluster--is handled properly.  To guarantee
     that this happens, all transactions taking place within a given
     interval are put into a global checkpoint, which can be thought of
     as a set of committed transactions that has been flushed to disk.
     In other words, as part of the commit process, a transaction is
     placed in a global checkpoint group.  Later, this group's log
     records are flushed to disk, and then the entire group of
     transactions is safely committed to disk on all computers in the
     cluster.

     This parameter defines the interval between global checkpoints.
     The default is 2000 milliseconds.

   *
     'TimeBetweenGlobalCheckpointsTimeout'

     *This table provides type and value information for the
     TimeBetweenGlobalCheckpointsTimeout data node configuration
     parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            120000

     *Range*                              10 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter defines the minimum timeout between global
     checkpoints.  The default is 120000 milliseconds.

   *
     'TimeBetweenEpochs'

     *This table provides type and value information for the
     TimeBetweenEpochs data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            100

     *Range*                              0 - 32000

     *Restart Type.
     *

     This parameter defines the interval between synchronization epochs
     for NDB Cluster Replication.  The default value is 100
     milliseconds.

     'TimeBetweenEpochs' is part of the implementation of 'micro-GCPs',
     which can be used to improve the performance of NDB Cluster
     Replication.

   *
     'TimeBetweenEpochsTimeout'

     *This table provides type and value information for the
     TimeBetweenEpochsTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            0

     *Range*                              0 - 256000

     *Restart Type.
     *

     This parameter defines a timeout for synchronization epochs for NDB
     Cluster Replication.  If a node fails to participate in a global
     checkpoint within the time determined by this parameter, the node
     is shut down.  The default value is 0; in other words, the timeout
     is disabled.

     'TimeBetweenEpochsTimeout' is part of the implementation of
     'micro-GCPs', which can be used to improve the performance of NDB
     Cluster Replication.

     The current value of this parameter and a warning are written to
     the cluster log whenever a GCP save takes longer than 1 minute or a
     GCP commit takes longer than 10 seconds.

     Setting this parameter to zero has the effect of disabling GCP
     stops caused by save timeouts, commit timeouts, or both.  The
     maximum possible value for this parameter is 256000 milliseconds.

   *
     'MaxBufferedEpochs'

     *This table provides type and value information for the
     MaxBufferedEpochs data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      epochs

     *Default*                            100

     *Range*                              0 - 100000

     *Restart Type.
     *

     The number of unprocessed epochs by which a subscribing node can
     lag behind.  Exceeding this number causes a lagging subscriber to
     be disconnected.

     The default value of 100 is sufficient for most normal operations.
     If a subscribing node does lag enough to cause disconnections, it
     is usually due to network or scheduling issues with regard to
     processes or threads.  (In rare circumstances, the problem may be
     due to a bug in the 'NDB' client.)  It may be
     desirable to set the value lower than the default when epochs are
     longer.

     Disconnection prevents client issues from affecting the data node
     service, running out of memory to buffer data, and eventually
     shutting down.  Instead, only the client is affected as a result of
     the disconnect (by, for example gap events in the binary log),
     forcing the client to reconnect or restart the process.

   *
     'MaxBufferedEpochBytes'

     *This table provides type and value information for the
     MaxBufferedEpochBytes data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            26214400

     *Range*                              26214400 (0x01900000) - 4294967039
                                          (0xFFFFFEFF)

     *Restart Type.
     *

     The total number of bytes allocated for buffering epochs by this
     node.

   *
     'TimeBetweenInactiveTransactionAbortCheck'

     *This table provides type and value information for the
     TimeBetweenInactiveTransactionAbortCheck data node configuration
     parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            1000

     *Range*                              1000 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Timeout handling is performed by checking a timer on each
     transaction once for every interval specified by this parameter.
     Thus, if this parameter is set to 1000 milliseconds, every
     transaction will be checked for timing out once per second.

     The default value is 1000 milliseconds (1 second).

   *
     'TransactionInactiveTimeout'

     *This table provides type and value information for the
     TransactionInactiveTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            [see text]

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter states the maximum time that is permitted to lapse
     between operations in the same transaction before the transaction
     is aborted.

     The default for this parameter is '4G' (also the maximum).  For a
     real-time database that needs to ensure that no transaction keeps
     locks for too long, this parameter should be set to a relatively
     small value.  Setting it to 0 means that the application never
     times out.  The unit is milliseconds.

   *
     'TransactionDeadlockDetectionTimeout'

     *This table provides type and value information for the
     TransactionDeadlockDetectionTimeout data node configuration
     parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            1200

     *Range*                              50 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When a node executes a query involving a transaction, the node
     waits for the other nodes in the cluster to respond before
     continuing.  This parameter sets the amount of time that the
     transaction can spend executing within a data node, that is, the
     time that the transaction coordinator waits for each data node
     participating in the transaction to execute a request.

     A failure to respond can occur for any of the following reasons:

        * The node is 'dead'

        * The operation has entered a lock queue

        * The node requested to perform the action could be heavily
          overloaded.

     This timeout parameter states how long the transaction coordinator
     waits for query execution by another node before aborting the
     transaction, and is important for both node failure handling and
     deadlock detection.

     The default timeout value is 1200 milliseconds (1.2 seconds).

     The minimum for this parameter is 50 milliseconds.

   *
     'DiskSyncSize'

     *This table provides type and value information for the
     DiskSyncSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            4M

     *Range*                              32K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This is the maximum number of bytes to store before flushing data
     to a local checkpoint file.  This is done to prevent write
     buffering, which can impede performance significantly.  This
     parameter is _not_ intended to take the place of
     'TimeBetweenLocalCheckpoints'.

     *Note*:

     When 'ODirect' is enabled, it is not necessary to set
     'DiskSyncSize'; in fact, in such cases its value is simply ignored.

     The default value is 4M (4 megabytes).

   *
     'MaxDiskWriteSpeed'

     *This table provides type and value information for the
     MaxDiskWriteSpeed data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            20M

     *Range*                              1M - 1024G

     *Restart Type.
     *

     Set the maximum rate for writing to disk, in bytes per second, by
     local checkpoints and backup operations when no restarts (by this
     data node or any other data node) are taking place in this NDB
     Cluster.

     For setting the maximum rate of disk writes allowed while this data
     node is restarting, use 'MaxDiskWriteSpeedOwnRestart'.  For setting
     the maximum rate of disk writes allowed while other data nodes are
     restarting, use 'MaxDiskWriteSpeedOtherNodeRestart'.  The minimum
     speed for disk writes by all LCPs and backup operations can be
     adjusted by setting 'MinDiskWriteSpeed'.

   *
     'MaxDiskWriteSpeedOtherNodeRestart'

     *This table provides type and value information for the
     MaxDiskWriteSpeedOtherNodeRestart data node configuration
     parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            50M

     *Range*                              1M - 1024G

     *Restart Type.
     *

     Set the maximum rate for writing to disk, in bytes per second, by
     local checkpoints and backup operations when one or more data nodes
     in this NDB Cluster are restarting, other than this node.

     For setting the maximum rate of disk writes allowed while this data
     node is restarting, use 'MaxDiskWriteSpeedOwnRestart'.  For setting
     the maximum rate of disk writes allowed when no data nodes are
     restarting anywhere in the cluster, use 'MaxDiskWriteSpeed'.  The
     minimum speed for disk writes by all LCPs and backup operations can
     be adjusted by setting 'MinDiskWriteSpeed'.

   *
     'MaxDiskWriteSpeedOwnRestart'

     *This table provides type and value information for the
     MaxDiskWriteSpeedOwnRestart data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            200M

     *Range*                              1M - 1024G

     *Restart Type.
     *

     Set the maximum rate for writing to disk, in bytes per second, by
     local checkpoints and backup operations while this data node is
     restarting.

     For setting the maximum rate of disk writes allowed while other
     data nodes are restarting, use 'MaxDiskWriteSpeedOtherNodeRestart'.
     For setting the maximum rate of disk writes allowed when no data
     nodes are restarting anywhere in the cluster, use
     'MaxDiskWriteSpeed'.  The minimum speed for disk writes by all LCPs
     and backup operations can be adjusted by setting
     'MinDiskWriteSpeed'.

   *
     'MinDiskWriteSpeed'

     *This table provides type and value information for the
     MinDiskWriteSpeed data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            10M

     *Range*                              1M - 1024G

     *Restart Type.
     *

     Set the minimum rate for writing to disk, in bytes per second, by
     local checkpoints and backup operations.

     The maximum rates of disk writes allowed for LCPs and backups under
     various conditions are adjustable using the parameters
     'MaxDiskWriteSpeed', 'MaxDiskWriteSpeedOwnRestart', and
     'MaxDiskWriteSpeedOtherNodeRestart'.  See the descriptions of these
     parameters for more information.

   *
     'ArbitrationTimeout'

     *This table provides type and value information for the
     ArbitrationTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            7500

     *Range*                              10 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter specifies how long data nodes wait for a response
     from the arbitrator to an arbitration message.  If this is
     exceeded, the network is assumed to have split.

     The default value is 7500 milliseconds (7.5 seconds).

   *
     'Arbitration'

     *This table provides type and value information for the Arbitration
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      enumeration

     *Default*                            Default

     *Range*                              Default, Disabled, WaitExternal

     *Restart Type.
     *

     The 'Arbitration' parameter enables a choice of arbitration
     schemes, corresponding to one of 3 possible values for this
     parameter:

        * Default

          This enables arbitration to proceed normally, as determined by
          the 'ArbitrationRank' settings for the management and API
          nodes.  This is the default value.

        * Disabled

          Setting 'Arbitration = Disabled' in the '[ndbd default]'
          section of the 'config.ini' file to accomplishes the same task
          as setting 'ArbitrationRank' to 0 on all management and API
          nodes.  When 'Arbitration' is set in this way, any
          'ArbitrationRank' settings are ignored.

        * WaitExternal

          The 'Arbitration' parameter also makes it possible to
          configure arbitration in such a way that the cluster waits
          until after the time determined by 'ArbitrationTimeout' has
          passed for an external cluster manager application to perform
          arbitration instead of handling arbitration internally.  This
          can be done by setting 'Arbitration = WaitExternal' in the
          '[ndbd default]' section of the 'config.ini' file.  For best
          results with the 'WaitExternal' setting, it is recommended
          that 'ArbitrationTimeout' be 2 times as long as the interval
          required by the external cluster manager to perform
          arbitration.

     *Important*:

     This parameter should be used only in the '[ndbd default]' section
     of the cluster configuration file.  The behavior of the cluster is
     unspecified when 'Arbitration' is set to different values for
     individual data nodes.

   *
     'RestartSubscriberConnectTimeout'

     *This table provides type and value information for the
     RestartSubscriberConnectTimeout data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      ms

     *Default*                            12000

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter determines the time that a data node waits for
     subscribing API nodes to connect.  Once this timeout expires, any
     'missing' API nodes are disconnected from the cluster.  To disable
     this timeout, set 'RestartSubscriberConnectTimeout' to 0.

     While this parameter is specified in milliseconds, the timeout
     itself is resolved to the next-greatest whole second.

Buffering and logging

Several '[ndbd]' configuration parameters enable the advanced user to
have more control over the resources used by node processes and to
adjust various buffer sizes at need.

These buffers are used as front ends to the file system when writing log
records to disk.  If the node is running in diskless mode, these
parameters can be set to their minimum values without penalty due to the
fact that disk writes are 'faked' by the 'NDB'.
storage engine's file system abstraction layer.

   *
     'UndoIndexBuffer'

     *This table provides type and value information for the
     UndoIndexBuffer data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            2M

     *Range*                              1M - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     The UNDO index buffer, whose size is set by this parameter, is used
     during local checkpoints.  The 'NDB' storage
     engine uses a recovery scheme based on checkpoint consistency in
     conjunction with an operational REDO log.  To produce a consistent
     checkpoint without blocking the entire system for writes, UNDO
     logging is done while performing the local checkpoint.  UNDO
     logging is activated on a single table fragment at a time.  This
     optimization is possible because tables are stored entirely in main
     memory.

     The UNDO index buffer is used for the updates on the primary key
     hash index.  Inserts and deletes rearrange the hash index; the NDB
     storage engine writes UNDO log records that map all physical
     changes to an index page so that they can be undone at system
     restart.  It also logs all active insert operations for each
     fragment at the start of a local checkpoint.

     Reads and updates set lock bits and update a header in the hash
     index entry.  These changes are handled by the page-writing
     algorithm to ensure that these operations need no UNDO logging.

     This buffer is 2MB by default.  The minimum value is 1MB, which is
     sufficient for most applications.  For applications doing extremely
     large or numerous inserts and deletes together with large
     transactions and large primary keys, it may be necessary to
     increase the size of this buffer.  If this buffer is too small, the
     NDB storage engine issues internal error code 677 ('Index UNDO
     buffers overloaded').

     *Important*:

     It is not safe to decrease the value of this parameter during a
     rolling restart.

   *
     'UndoDataBuffer'

     *This table provides type and value information for the
     UndoDataBuffer data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            16M

     *Range*                              1M - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets the size of the UNDO data buffer, which
     performs a function similar to that of the UNDO index buffer,
     except the UNDO data buffer is used with regard to data memory
     rather than index memory.  This buffer is used during the local
     checkpoint phase of a fragment for inserts, deletes, and updates.

     Because UNDO log entries tend to grow larger as more operations are
     logged, this buffer is also larger than its index memory
     counterpart, with a default value of 16MB.

     This amount of memory may be unnecessarily large for some
     applications.  In such cases, it is possible to decrease this size
     to a minimum of 1MB.

     It is rarely necessary to increase the size of this buffer.  If
     there is such a need, it is a good idea to check whether the disks
     can actually handle the load caused by database update activity.  A
     lack of sufficient disk space cannot be overcome by increasing the
     size of this buffer.

     If this buffer is too small and gets congested, the NDB storage
     engine issues internal error code 891 ('Data UNDO buffers
     overloaded').

     *Important*:

     It is not safe to decrease the value of this parameter during a
     rolling restart.

   *
     'RedoBuffer'

     *This table provides type and value information for the RedoBuffer
     data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            32M

     *Range*                              1M - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     All update activities also need to be logged.  The REDO log makes
     it possible to replay these updates whenever the system is
     restarted.  The NDB recovery algorithm uses a 'fuzzy' checkpoint of
     the data together with the UNDO log, and then applies the REDO log
     to play back all changes up to the restoration point.

     'RedoBuffer' sets the size of the buffer in which the REDO log is
     written.  The default value is 32MB; the minimum value is 1MB.

     If this buffer is too small, the 'NDB'.
     storage engine issues error code 1221 ('REDO log buffers
     overloaded').  For this reason, you should exercise care if you
     attempt to decrease the value of 'RedoBuffer' as part of an online
     change in the cluster's configuration.

     'ndbmtd' allocates a separate
     buffer for each LDM thread (see 'ThreadConfig').  For example, with
     4 LDM threads, an 'ndbmtd'.
     data node actually has 4 buffers and allocates 'RedoBuffer' bytes
     to each one, for a total of '4 * RedoBuffer' bytes.

   *
     'EventLogBufferSize'

     *This table provides type and value information for the
     EventLogBufferSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            8192

     *Range*                              0 - 64K

     *Restart Type.
     *

     Controls the size of the circular buffer used for NDB log events
     within data nodes.

Controlling log messages

In managing the cluster, it is very important to be able to control the
number of log messages sent for various event types to 'stdout'.  For
each event category, there are 16 possible event levels (numbered 0
through 15).  Setting event reporting for a given event category to
level 15 means all event reports in that category are sent to 'stdout';
setting it to 0 means that there will be no event reports made in that
category.

By default, only the startup message is sent to 'stdout', with the
remaining event reporting level defaults being set to 0.  The reason for
this is that these messages are also sent to the management server's
cluster log.

An analogous set of levels can be set for the management client to
determine which event levels to record in the cluster log.

   *
     'LogLevelStartup'

     *This table provides type and value information for the
     LogLevelStartup data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            1

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated during startup of the
     process.

     The default level is 1.

   *
     'LogLevelShutdown'

     *This table provides type and value information for the
     LogLevelShutdown data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated as part of graceful
     shutdown of a node.

     The default level is 0.

   *
     'LogLevelStatistic'

     *This table provides type and value information for the
     LogLevelStatistic data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for statistical events such as number of
     primary key reads, number of updates, number of inserts,
     information relating to buffer usage, and so on.

     The default level is 0.

   *
     'LogLevelCheckpoint'

     *This table provides type and value information for the
     LogLevelCheckpoint data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      log level

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated by local and global
     checkpoints.

     The default level is 0.

   *
     'LogLevelNodeRestart'

     *This table provides type and value information for the
     LogLevelNodeRestart data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated during node restart.

     The default level is 0.

   *
     'LogLevelConnection'

     *This table provides type and value information for the
     LogLevelConnection data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated by connections between
     cluster nodes.

     The default level is 0.

   *
     'LogLevelError'

     *This table provides type and value information for the
     LogLevelError data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated by errors and warnings by
     the cluster as a whole.  These errors do not cause any node failure
     but are still considered worth reporting.

     The default level is 0.

   *
     'LogLevelCongestion'

     *This table provides type and value information for the
     LogLevelCongestion data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      level

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated by congestion.  These
     errors do not cause node failure but are still considered worth
     reporting.

     The default level is 0.

   *
     'LogLevelInfo'

     *This table provides type and value information for the
     LogLevelInfo data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 15

     *Restart Type.
     *

     The reporting level for events generated for information about the
     general state of the cluster.

     The default level is 0.

   *
     'MemReportFrequency'

     *This table provides type and value information for the
     MemReportFrequency data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter controls how often data node memory usage reports
     are recorded in the cluster log; it is an integer value
     representing the number of seconds between reports.

     Each data node's data memory and index memory usage is logged as
     both a percentage and a number of 32 KB pages of the 'DataMemory'
     and 'IndexMemory', respectively, set in the 'config.ini' file.  For
     example, if 'DataMemory' is equal to 100 MB, and a given data node
     is using 50 MB for data memory storage, the corresponding line in
     the cluster log might look like this:

          2006-12-24 01:18:16 [MgmSrvr] INFO -- Node 2: Data usage is 50%(1280 32K pages of total 2560)

     'MemReportFrequency' is not a required parameter.  If used, it can
     be set for all cluster data nodes in the '[ndbd default]' section
     of 'config.ini', and can also be set or overridden for individual
     data nodes in the corresponding '[ndbd]' sections of the
     configuration file.  The minimum value--which is also the default
     value--is 0, in which case memory reports are logged only when
     memory usage reaches certain percentages (80%, 90%, and 100%), as
     mentioned in the discussion of statistics events in
     mysql-cluster-log-events.

   *
     'StartupStatusReportFrequency'

     *This table provides type and value information for the
     StartupStatusReportFrequency data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      seconds

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When a data node is started with the '--initial', it initializes
     the redo log file during Start Phase 4 (see
     mysql-cluster-start-phases).  When very large values are set for
     'NoOfFragmentLogFiles', 'FragmentLogFileSize', or both, this
     initialization can take a long time.You can force reports on the
     progress of this process to be logged periodically, by means of the
     'StartupStatusReportFrequency' configuration parameter.  In this
     case, progress is reported in the cluster log, in terms of both the
     number of files and the amount of space that have been initialized,
     as shown here:

          2009-06-20 16:39:23 [MgmSrvr] INFO -- Node 1: Local redo log file initialization status:
          #Total files: 80, Completed: 60
          #Total MBytes: 20480, Completed: 15557
          2009-06-20 16:39:23 [MgmSrvr] INFO -- Node 2: Local redo log file initialization status:
          #Total files: 80, Completed: 60
          #Total MBytes: 20480, Completed: 15570

     These reports are logged each 'StartupStatusReportFrequency'
     seconds during Start Phase 4.  If 'StartupStatusReportFrequency' is
     0 (the default), then reports are written to the cluster log only
     when at the beginning and at the completion of the redo log file
     initialization process.

Data Node Debugging Parameters

It is also possible to cause logging of traces for events generated by
creating and dropping tables using 'DictTrace'.  This parameter is
useful only in debugging NDB kernel code.  'DictTrace' takes an integer
value.  0 (default - no logging) and 1 (logging enabled) are the only
supported values prior to NDB 7.5.2.  In NDB 7.5.2 and later, setting
this parameter to 2 enables logging of additional 'DBDICT' debugging
output (Bug #20368450).

Backup parameters

The '[ndbd]' parameters discussed in this section define memory buffers
set aside for execution of online backups.

   *
     'BackupDataBufferSize'

     *This table provides type and value information for the
     BackupDataBufferSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            16M

     *Range*                              512K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            16M

     *Range*                              2M - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     *Version (or later)*                 NDB 7.5.1

     *Type or units*                      bytes

     *Default*                            16M

     *Range*                              512K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     In creating a backup, there are two buffers used for sending data
     to the disk.  The backup data buffer is used to fill in data
     recorded by scanning a node's tables.  Once this buffer has been
     filled to the level specified as 'BackupWriteSize', the pages are
     sent to disk.  While flushing data to disk, the backup process can
     continue filling this buffer until it runs out of space.  When this
     happens, the backup process pauses the scan and waits until some
     disk writes have completed freeing up memory so that scanning may
     continue.

     The default value for this parameter is 16MB. The minimum was
     changed from 2M to 512K in NDB 7.5.1.  (Bug #22749509)

   *
     'BackupDiskWriteSpeedPct'

     *This table provides type and value information for the
     BackupDiskWriteSpeedPct data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      percent

     *Default*                            50

     *Range*                              0 - 90

     *Restart Type.
     *

     During normal operation, data nodes attempt to maximize the disk
     write speed used for local checkpoints and backups while remaining
     within the bounds set by 'MinDiskWriteSpeed' and
     'MaxDiskWriteSpeed'.  Disk write throttling gives each LDM thread
     an equal share of the total budget.  This allows parallel LCPs to
     take place without exceeding the disk I/O budget.  Because a backup
     is executed by only one LDM thread, this effectively caused a
     budget cut, resulting in longer backup completion times, and--if
     the rate of change is sufficiently high--in failure to complete the
     backup when the backup log buffer fill rate is higher than the
     achievable write rate.

     This problem can be addressed by using the
     'BackupDiskWriteSpeedPct' configuration parameter, which takes a
     value in the range 0-90 (inclusive) which is interpreted as the
     percentage of the node's maximum write rate budget that is reserved
     prior to sharing out the remainder of the budget among LDM threads
     for LCPs.  The LDM thread running the backup receives the whole
     write rate budget for the backup, plus its (reduced) share of the
     write rate budget for local checkpoints.  (This makes the disk
     write rate budget behave similarly to how it was handled in NDB
     Cluster 7.3 and earlier.)

     The default value for this parameter is 50 (interpreted as 50%).

   *
     'BackupLogBufferSize'

     *This table provides type and value information for the
     BackupLogBufferSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            16M

     *Range*                              2M - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     The backup log buffer fulfills a role similar to that played by the
     backup data buffer, except that it is used for generating a log of
     all table writes made during execution of the backup.  The same
     principles apply for writing these pages as with the backup data
     buffer, except that when there is no more space in the backup log
     buffer, the backup fails.  For that reason, the size of the backup
     log buffer must be large enough to handle the load caused by write
     activities while the backup is being made.  See
     mysql-cluster-backup-configuration.

     The default value for this parameter should be sufficient for most
     applications.  In fact, it is more likely for a backup failure to
     be caused by insufficient disk write speed than it is for the
     backup log buffer to become full.  If the disk subsystem is not
     configured for the write load caused by applications, the cluster
     is unlikely to be able to perform the desired operations.

     It is preferable to configure cluster nodes in such a manner that
     the processor becomes the bottleneck rather than the disks or the
     network connections.

     The default value for this parameter is 16MB.

   *
     'BackupMemory'

     *This table provides type and value information for the
     BackupMemory data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            32M

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter is deprecated, and subject to removal in a future
     version of NDB Cluster.  Any setting made for it is ignored.

   *
     'BackupReportFrequency'

     *This table provides type and value information for the
     BackupReportFrequency data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      seconds

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter controls how often backup status reports are issued
     in the management client during a backup, as well as how often such
     reports are written to the cluster log (provided cluster event
     logging is configured to permit it--see
     mysql-cluster-logging-and-checkpointing).
     'BackupReportFrequency' represents the time in seconds between
     backup status reports.

     The default value is 0.

   *
     'BackupWriteSize'

     *This table provides type and value information for the
     BackupWriteSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            256K

     *Range*                              32K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter specifies the default size of messages written to
     disk by the backup log and backup data buffers.

     The default value for this parameter is 256KB.

   *
     'BackupMaxWriteSize'

     *This table provides type and value information for the
     BackupMaxWriteSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            1M

     *Range*                              256K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter specifies the maximum size of messages written to
     disk by the backup log and backup data buffers.

     The default value for this parameter is 1MB.

*Note*:

The location of the backup files is determined by the 'BackupDataDir'
data node configuration parameter.

Additional requirements

When specifying these parameters, the following relationships must hold
true.  Otherwise, the data node will be unable to start.

   * 'BackupDataBufferSize >= BackupWriteSize + 188KB'

   * 'BackupLogBufferSize >= BackupWriteSize + 16KB'

   * 'BackupMaxWriteSize >= BackupWriteSize'

*NDB Cluster Realtime Performance Parameters*

The '[ndbd]' parameters discussed in this section are used in scheduling
and locking of threads to specific CPUs on multiprocessor data node
hosts.

*Note*:

To make use of these parameters, the data node process must be run as
system root.

   *
     'LockExecuteThreadToCPU'

     *This table provides type and value information for the
     LockExecuteThreadToCPU data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      set of CPU IDs

     *Default*                            0

     *Range*                              ...

     *Restart Type.
     *

     When used with 'ndbd', this
     parameter (now a string) specifies the ID of the CPU assigned to
     handle the 'NDBCLUSTER' execution thread.
     When used with 'ndbmtd', the
     value of this parameter is a comma-separated list of CPU IDs
     assigned to handle execution threads.  Each CPU ID in the list
     should be an integer in the range 0 to 65535 (inclusive).

     The number of IDs specified should match the number of execution
     threads determined by 'MaxNoOfExecutionThreads'.  However, there is
     no guarantee that threads are assigned to CPUs in any given order
     when using this parameter.  You can obtain more finely-grained
     control of this type using 'ThreadConfig'.

     'LockExecuteThreadToCPU' has no default value.

   *
     'LockMaintThreadsToCPU'

     *This table provides type and value information for the
     LockMaintThreadsToCPU data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      CPU ID

     *Default*                            0

     *Range*                              0 - 64K

     *Restart Type.
     *

     This parameter specifies the ID of the CPU assigned to handle
     'NDBCLUSTER' maintenance threads.

     The value of this parameter is an integer in the range 0 to 65535
     (inclusive).  _There is no default value_.

   *
     'RealtimeScheduler'

     *This table provides type and value information for the
     RealtimeScheduler data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     Setting this parameter to 1 enables real-time scheduling of data
     node threads.

     The default is 0 (scheduling disabled).

   *
     'SchedulerExecutionTimer'

     *This table provides type and value information for the
     SchedulerExecutionTimer data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      µs

     *Default*                            50

     *Range*                              0 - 11000

     *Restart Type.
     *

     This parameter specifies the time in microseconds for threads to be
     executed in the scheduler before being sent.  Setting it to 0
     minimizes the response time; to achieve higher throughput, you can
     increase the value at the expense of longer response times.

     The default is 50 μsec, which our testing shows to increase
     throughput slightly in high-load cases without materially delaying
     requests.

   *
     'SchedulerResponsiveness'

     *This table provides type and value information for the
     SchedulerResponsiveness data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            5

     *Range*                              0 - 10

     *Restart Type.
     *

     Set the balance in the 'NDB' scheduler between speed and
     throughput.  This parameter takes an integer whose value is in the
     range 0-10 inclusive, with 5 as the default.  Higher values provide
     better response times relative to throughput.  Lower values provide
     increased throughput at the expense of longer response times.

   *
     'SchedulerSpinTimer'

     *This table provides type and value information for the
     SchedulerSpinTimer data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      µs

     *Default*                            0

     *Range*                              0 - 500

     *Restart Type.
     *

     This parameter specifies the time in microseconds for threads to be
     executed in the scheduler before sleeping.

     The default value is 0.

   *
     'BuildIndexThreads'

     *This table provides type and value information for the
     BuildIndexThreads data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            0

     *Range*                              0 - 128

     *Restart Type.
     *

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      numeric

     *Default*                            128

     *Range*                              0 - 128

     *Restart Type.
     *

     This parameter determines the number of threads to create when
     rebuilding ordered indexes during a system or node start, as well
     as when running 'ndb_restore'.
     '--rebuild-indexes'.  It is
     supported only when there is more than one fragment for the table
     per data node (for example, when
     'COMMENT="NDB_TABLE=PARTITION_BALANCE=FOR_RA_BY_LDM_X_2"' is used
     with 'CREATE TABLE').

     Setting this parameter to 0 (the default) disables multi-threaded
     building of ordered indexes.

     This parameter is supported when using 'ndbd'
     or 'ndbmtd'.

     You can enable multi-threaded builds during data node initial
     restarts by setting the 'TwoPassInitialNodeRestartCopy' data node
     configuration parameter to 'TRUE'.

   *
     'TwoPassInitialNodeRestartCopy'

     *This table provides type and value information for the
     TwoPassInitialNodeRestartCopy data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      boolean

     *Default*                            true

     *Range*                              true, false

     *Restart Type.
     *

     Multi-threaded building of ordered indexes can be enabled for
     initial restarts of data nodes by setting this configuration
     parameter to 'true', which enables two-pass copying of data during
     initial node restarts.  Beginning with NDB 7.6.4, this is the
     default value (Bug #26704312, Bug #27109117).

     You must also set 'BuildIndexThreads' to a nonzero value.

   *
     'Numa'

     *This table provides type and value information for the Numa data
     node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            1

     *Range*                              ...

     *Restart Type.
     *

     This parameter determines whether Non-Uniform Memory Access (NUMA)
     is controlled by the operating or by the data node process, whether
     the data node uses 'ndbd' or
     'ndbmtd'.  By default, 'NDB'
     attempts to use an interleaved NUMA memory allocation policy on any
     data node where the host operating system provides NUMA support.

     Setting 'Numa = 0' means that the datanode process does not itself
     attempt to set a policy for memory allocation, and permits this
     behavior to be determined by the operating system, which may be
     further guided by the separate 'numactl' tool.  That is, 'Numa = 0'
     yields the system default behavior, which can be customised by
     'numactl'.  For many Linux systems, the system default behavior is
     to allocate socket-local memory to any given process at allocation
     time.  This can be problematic when using 'ndbmtd'.;
     this is because 'nbdmtd' allocates
     all memory at startup, leading to an imbalance, giving different
     access speeds for different sockets, especially when locking pages
     in main memory.

     Setting 'Numa = 1' means that the data node process uses 'libnuma'
     to request interleaved memory allocation.  (This can also be
     accomplished manually, on the operating system level, using
     'numactl'.)  Using interleaved allocation in effect tells the data
     node process to ignore non-uniform memory access but does not
     attempt to take any advantage of fast local memory; instead, the
     data node process tries to avoid imbalances due to slow remote
     memory.  If interleaved allocation is not desired, set 'Numa' to 0
     so that the desired behavior can be determined on the operating
     system level.

     The 'Numa' configuration parameter is supported only on Linux
     systems where 'libnuma.so' is available.

Multi-Threading Configuration Parameters (ndbmtd)

'ndbmtd' runs by default as a
single-threaded process and must be configured to use multiple threads,
using either of two methods, both of which require setting configuration
parameters in the 'config.ini' file.  The first method is simply to set
an appropriate value for the 'MaxNoOfExecutionThreads' configuration
parameter.  A second method, makes it possible to set up more complex
rules for 'ndbmtd' multi-threading
using 'ThreadConfig'.  The next few paragraphs provide information about
these parameters and their use with multi-threaded data nodes.

   *
     'MaxNoOfExecutionThreads'

     *This table provides type and value information for the
     MaxNoOfExecutionThreads multi-threaded data node configuration
     parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            2

     *Range*                              2 - 72

     *Restart Type.
     *

     This parameter directly controls the number of execution threads
     used by 'ndbmtd', up to a
     maximum of 72.  Although this parameter is set in '[ndbd]' or
     '[ndbd default]' sections of the 'config.ini' file, it is exclusive
     to 'ndbmtd' and does not
     apply to 'ndbd'.

     Setting 'MaxNoOfExecutionThreads' sets the number of threads for
     each type as determined by a matrix in the file
     'storage/ndb/src/kernel/vm/mt_thr_config.cpp'.  This table shows
     these numbers of threads for possible values of
     'MaxNoOfExecutionThreads'.

     *MaxNoOfExecutionThreads values and the corresponding number of
     threads by thread type (LQH, TC, Send, Receive).*

     'MaxNoOfExecutionThreads' Value       LDM       TC        Send      Receive
                                           Threads   Threads   Threads   Threads

     0 ..  3                               1         0         0         1

     4 ..  6                               2         0         0         1

     7 ..  8                               4         0         0         1

     9                                     4         2         0         1

     10                                    4         2         1         1

     11                                    4         3         1         1

     12                                    6         2         1         1

     13                                    6         3         1         1

     14                                    6         3         1         2

     15                                    6         3         2         2

     16                                    8         3         1         2

     17                                    8         4         1         2

     18                                    8         4         2         2

     19                                    8         5         2         2

     20                                    10        4         2         2

     21                                    10        5         2         2

     22                                    10        5         2         3

     23                                    10        6         2         3

     24                                    12        5         2         3

     25                                    12        6         2         3

     26                                    12        6         3         3

     27                                    12        7         3         3

     28                                    12        7         3         4

     29                                    12        8         3         4

     30                                    12        8         4         4

     31                                    12        9         4         4

     32                                    16        8         3         3

     33                                    16        8         3         4

     34                                    16        8         4         4

     35                                    16        9         4         4

     36                                    16        10        4         4

     37                                    16        10        4         5

     38                                    16        11        4         5

     39                                    16        11        5         5

     40                                    20        10        4         4

     41                                    20        10        4         5

     42                                    20        11        4         5

     43                                    20        11        5         5

     44                                    20        12        5         5

     45                                    20        12        5         6

     46                                    20        13        5         6

     47                                    20        13        6         6

     48                                    24        12        5         5

     49                                    24        12        5         6

     50                                    24        13        5         6

     51                                    24        13        6         6

     52                                    24        14        6         6

     53                                    24        14        6         7

     54                                    24        15        6         7

     55                                    24        15        7         7

     56                                    24        16        7         7

     57                                    24        16        7         8

     58                                    24        17        7         8

     59                                    24        17        8         8

     60                                    24        18        8         8

     61                                    24        18        8         9

     62                                    24        19        8         9

     63                                    24        19        9         9

     64                                    32        16        7         7

     65                                    32        16        7         8

     66                                    32        17        7         8

     67                                    32        17        8         8

     68                                    32        18        8         8

     69                                    32        18        8         9

     70                                    32        19        8         9

     71                                    32        20        8         9

     72                                    32        20        8         10

     There is always one SUMA (replication) thread.

     'NoOfFragmentLogParts' should be set equal to the number of LDM
     threads used by 'ndbmtd', as
     determined by the setting for this parameter.  This ratio should
     not be any greater than 4:1; beginning with NDB 7.5.7 and NDB
     7.6.3, a configuration in which this is the case is specifically
     disallowed.  (Bug #25333414)

     The number of LDM threads also determines the number of partitions
     used by an 'NDB' table that is not explicitly partitioned; this is
     the number of LDM threads times the number of data nodes in the
     cluster.  (If 'ndbd' is used on
     the data nodes rather than 'ndbmtd',
     then there is always a single LDM
     thread; in this case, the number of partitions created
     automatically is simply equal to the number of data nodes.  See
     mysql-cluster-nodes-groups, for more information.

     Adding large tablespaces for Disk Data tables when using more than
     the default number of LDM threads may cause issues with resource
     and CPU usage if the disk page buffer is insufficiently large; see
     the description of the 'DiskPageBufferMemory' configuration
     parameter, for more information.

     The thread types are described later in this section (see
     'ThreadConfig').

     Setting this parameter outside the permitted range of values causes
     the management server to abort on startup with the error 'Error
     line NUMBER: Illegal value VALUE for parameter
     MaxNoOfExecutionThreads'.

     For 'MaxNoOfExecutionThreads', a value of 0 or 1 is rounded up
     internally by 'NDB' to 2, so that 2 is
     considered this parameter's default and minimum value.

     'MaxNoOfExecutionThreads' is generally intended to be set equal to
     the number of CPU threads available, and to allocate a number of
     threads of each type suitable to typical workloads.  It does not
     assign particular threads to specified CPUs.  For cases where it is
     desirable to vary from the settings provided, or to bind threads to
     CPUs, you should use 'ThreadConfig' instead, which allows you to
     allocate each thread directly to a desired type, CPU, or both.

     The multi-threaded data node process always spawns, at a minimum,
     the threads listed here:

        * 1 local query handler (LDM) thread

        * 1 receive thread

        * 1 subscription manager (SUMA or replication) thread

     For a 'MaxNoOfExecutionThreads' value of 8 or less, no TC threads
     are created, and TC handling is instead performed by the main
     thread.

     Changing the number of LDM threads always requires a system
     restart, whether it is changed using this parameter or
     'ThreadConfig'.

     Prior to NDB 7.6, if the cluster's 'IndexMemory' usage is greater
     than 50%, changing this requires an initial restart of the cluster.
     (A maximum of 30-35% 'IndexMemory' usage is recommended in such
     cases.)  Otherwise, resource usage and LDM thread allocation cannot
     be balanced between nodes, which can result in underutilized and
     overutilized LDM threads, and ultimately data node failures.  In
     NDB 7.6 and later, an initial restart is _not_ required to effect a
     change in this parameter.

   *
     'NoOfFragmentLogParts'

     *This table provides type and value information for the
     NoOfFragmentLogParts multi-threaded data node configuration
     parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            4

     *Range*                              4, 8, 12, 16, 24, 32

     *Restart Type.
     *

     Set the number of log file groups for redo logs belonging to this
     'ndbmtd'.  The maximum value
     is 32; the value set must be an even multiple of 4.

     'NoOfFragmentLogParts' should be set equal to the number of LDM
     threads used by 'ndbmtd' as
     determined by the setting for 'MaxNoOfExecutionThreads'.  Beginning
     with NDB 7.5.7 and NDB 7.6.3, a configuration where this number is
     any greater than 4 is disallowed.  (Bug #25333414)

     See the description of 'MaxNoOfExecutionThreads' for more
     information.

   *
     'ThreadConfig'

     *This table provides type and value information for the
     ThreadConfig multi-threaded data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      string

     *Default*                            "

     *Range*                              ...

     *Restart Type.
     *

     This parameter is used with 'ndbmtd'
     to assign threads of different types
     to different CPUs.  Its value is a string whose format has the
     following syntax:

          ThreadConfig := ENTRY[,ENTRY[,...]]

          ENTRY := TYPE={PARAM[,PARAM[,...]]}

          TYPE := ldm | main | recv | send | rep | io | tc | watchdog | idxbld

          PARAM := count=NUMBER
            | cpubind=CPU_LIST
            | cpuset=CPU_LIST
            | spintime=NUMBER
            | realtime={0|1}
            | nosend={0|1}
            | thread_prio={0..10}
            | cpubind_exclusive=CPU_LIST
            | cpuset_exclusive=CPU_LIST

     The curly braces ('{'...'}') surrounding the list of parameters are
     required, even if there is only one parameter in the list.

     A PARAM (parameter) specifies any or all of the following
     information:

        * The number of threads of the given type ('count').

        * The set of CPUs to which the threads of the given type are to
          be nonexclusively bound.  This is determined by either one of
          'cpubind' or 'cpuset').  'cpubind' causes each thread to be
          bound (nonexclusively) to a CPU in the set; 'cpuset' means
          that each thread is bound (nonexclusively) to the set of CPUs
          specified.

          On Solaris, you can instead specify a set of CPUs to which the
          threads of the given type are to be bound exclusively.
          'cpubind_exclusive' causes each thread to be bound exclusively
          to a CPU in the set; 'cpuset_exclsuive' means that each thread
          is bound exclusively to the set of CPUs specified.

          Only one of 'cpubind', 'cpuset', 'cpubind_exclusive', or
          'cpuset_exclusive' can be provided in a single configuration.

        * 'spintime' determines the wait time in microseconds the thread
          spins before going to sleep.

          The default value for 'spintime' is the value of the
          'SchedulerSpinTimer' data node configuration parameter.

          'spintime' does not apply to I/O threads, watchdog, or offline
          index build threads, and so cannot be set for these thread
          types.

        * 'realtime' can be set to 0 or 1.  If it is set to 1, the
          threads run with real-time priority.  This also means that
          'thread_prio' cannot be set.

          The 'realtime' parameter is set by default to the value of the
          'RealtimeScheduler' data node configuration parameter.

          'realtime' cannot be set for offline index build threads.

        * By setting 'nosend' to 1, you can prevent a 'main', 'ldm',
          'rep', or 'tc' thread from assisting the send threads.  This
          parameter is 0 by default, and cannot be used with other types
          of threads.

          'nosend' was added in NDB 7.6.4.

        * 'thread_prio' is a thread priority level that can be set from
          0 to 10, with 10 representing the greatest priority.  The
          default is 5.  The precise effects of this parameter are
          platform-specific, and are described later in this section.

          The thread priority level cannot be set for offline index
          build threads.

     thread_prio settings and effects by platform

     The implementation of 'thread_prio' differs between Linux/FreeBSD,
     Solaris, and Windows.  In the following list, we discuss its
     effects on each of these platforms in turn:

        * _Linux and FreeBSD_: We map 'thread_prio' to a value to be
          supplied to the 'nice' system call.  Since a lower niceness
          value for a process indicates a higher process priority,
          increasing 'thread_prio' has the effect of lowering the 'nice'
          value.

          *Mapping of thread_prio to nice values on Linux and FreeBSD*

          'thread_prio' value                  'nice' value

          0                                    19

          1                                    16

          2                                    12

          3                                    8

          4                                    4

          5                                    0

          6                                    -4

          7                                    -8

          8                                    -12

          9                                    -16

          10                                   -20

          Some operating systems may provide for a maximum process
          niceness level of 20, but this is not supported by all
          targeted versions; for this reason, we choose 19 as the
          maximum 'nice' value that can be set.

        * _Solaris_: Setting 'thread_prio' on Solaris sets the Solaris
          FX priority, with mappings as shown in the following table:

          *Mapping of thread_prio to FX priority on Solaris*

          'thread_prio' value                  Solaris 'FX' priority

          0                                    15

          1                                    20

          2                                    25

          3                                    30

          4                                    35

          5                                    40

          6                                    45

          7                                    50

          8                                    55

          9                                    59

          10                                   60

          A 'thread_prio' setting of 9 is mapped on Solaris to the
          special FX priority value 59, which means that the operating
          system also attempts to force the thread to run alone on its
          own CPU core.

        * _Windows_: We map 'thread_prio' to a Windows thread priority
          value passed to the Windows API 'SetThreadPriority()'
          function.  This mapping is shown in the following table:

          *Mapping of thread_prio to Windows thread priority*

          'thread_prio' value                  Windows thread priority

          0 - 1                                'THREAD_PRIORITY_LOWEST'

          2 - 3                                'THREAD_PRIORITY_BELOW_NORMAL'

          4 - 5                                'THREAD_PRIORITY_NORMAL'

          6 - 7                                'THREAD_PRIORITY_ABOVE_NORMAL'

          8 - 10                               'THREAD_PRIORITY_HIGHEST'

     The TYPE attribute represents an NDB thread type.  The thread types
     supported, and the range of permitted 'count' values for each, are
     provided in the following list:

        * 'ldm': Local query handler ('DBLQH' kernel block) that handles
          data.  The more LDM threads that are used, the more highly
          partitioned the data becomes.  Each LDM thread maintains its
          own sets of data and index partitions, as well as its own redo
          log.  The value set for 'ldm' must be one of the values 1, 2,
          4, 6, 8, 12, 16, 24, or 32.

          Changing the number of LDM threads requires a system restart
          to be effective and safe for cluster operations.  (This is
          also true when this is done using 'MaxNoOfExecutionThreads'.)
          If 'IndexMemory' usage is in excess of 50%, an initial restart
          of the cluster is required; a maximum of 30-35% 'IndexMemory'
          usage is recommended in such cases.  Otherwise, allocation of
          memory and LDM threads cannot be balanced between nodes, which
          can ultimately lead to data node failures.

          Adding large tablespaces (hundreds of gigabytes or more) for
          Disk Data tables when using more than the default number of
          LDMs may cause issues with resource and CPU usage if
          'DiskPageBufferMemory' is not sufficiently large.

        * 'tc': Transaction coordinator thread ('DBTC' kernel block)
          containing the state of an ongoing transaction.  The maximum
          number of TC threads is 32.

          Optimally, every new transaction can be assigned to a new TC
          thread.  In most cases 1 TC thread per 2 LDM threads is
          sufficient to guarantee that this can happen.  In cases where
          the number of writes is relatively small when compared to the
          number of reads, it is possible that only 1 TC thread per 4
          LQH threads is required to maintain transaction states.
          Conversely, in applications that perform a great many updates,
          it may be necessary for the ratio of TC threads to LDM threads
          to approach 1 (for example, 3 TC threads to 4 LDM threads).

          Setting 'tc' to 0 causes TC handling to be done by the main
          thread.  In most cases, this is effectively the same as
          setting it to 1.

          Range: 0 - 32

        * 'main': Data dictionary and transaction coordinator ('DBDIH'
          and 'DBTC' kernel blocks), providing schema management.  This
          is always handled by a single dedicated thread.

          Range: 1 only.

        * 'recv': Receive thread ('CMVMI' kernel block).  Each receive
          thread handles one or more sockets for communicating with
          other nodes in an NDB Cluster, with one socket per node.  NDB
          Cluster supports multiple receive threads; the maximum is 16
          such threads.

          Range: 1 - 16

        * 'send': Send thread ('CMVMI' kernel block).  To increase
          throughput, it is possible to perform sends from one or more
          separate, dedicated threads (maximum 8).

          Previously, all threads handled their own sending directly;
          this can still be made to happen by setting the number of send
          threads to 0 (this also happens when 'MaxNoOfExecutionThreads'
          is set less than 10).  While doing so can have an adeverse
          impact on throughput, it can also in some cases provide
          decreased latency.

          Range: 0 - 16

        * 'rep': Replication thread ('SUMA' kernel block).  Asynchronous
          replication operations are always handled by a single,
          dedicated thread.

          Range: 1 only.

        * 'io': File system and other miscellaneous operations.  These
          are not demanding tasks, and are always handled as a group by
          a single, dedicated I/O thread.

          Range: 1 only.

        * 'watchdog': Parameters settings associated with this type are
          actually applied to several threads, each having a specific
          use.  These threads include the 'SocketServer' thread, which
          receives connection setups from other nodes; the
          'SocketClient' thread, which attempts to set up connections to
          other nodes; and the thread watchdog thread that checks that
          threads are progressing.

          Range: 1 only.

        * 'idxbld': Offline index build threads.  Unlike the other
          thread types listed previously, which are permanent, these are
          temporary threads which are created and used only during node
          or system restarts, or when running 'ndb_restore'.
          '--rebuild-indexes'.  They
          may be bound to CPU sets which overlap with CPU sets bound to
          permanent thread types.

          'thread_prio', 'realtime', and 'spintime' values cannot be set
          for offline index build threads.  In addition, 'count' is
          ignored for this type of thread.

          If 'idxbld' is not specified, the default behavior is as
          follows:

             * Offline index build threads are not bound if the I/O
               thread is also not bound, and these threads use any
               available cores.

             * If the I/O thread is bound, then the offline index build
               threads are bound to the entire set of bound threads, due
               to the fact that there should be no other tasks for these
               threads to perform.

          Range: 0 - 1.

          This thread type was added in NDB 7.6.4.  (Bug #25835748, Bug
          #26928111)

Prior to NDB 7.6, changing 'ThreadCOnfig' also requires an initial
restart of the cluster.  Beginning with NDB 7.6.1, an initial restart is
no longer required.  A system restart is always required to effect a
change in 'ThreadConfig', irrespective of 'NDB' version.

NDB 7.6.4 and later can distinguish between thread types by both of the
following criteria:

   * Whether the thread is an execution thread.  Threads of type 'main',
     'ldm', 'recv', 'rep', 'tc', and 'send' are execution threads; 'io',
     'watchdog', and 'idxbld' threads are not considered execution
     threads.

   * Whether the allocation of threads to a given task is permanent or
     temporary.  Currently all thread types except 'idxbld' are
     considered permanent; 'idxbld' threads are regarded as temporary
     threads.

Simple examples:

     # Example 1.

     ThreadConfig=ldm={count=2,cpubind=1,2},main={cpubind=12},rep={cpubind=11}

     # Example 2.

     Threadconfig=main={cpubind=0},ldm={count=4,cpubind=1,2,5,6},io={cpubind=3}

It is usually desirable when configuring thread usage for a data node
host to reserve one or more number of CPUs for operating system and
other tasks.  Thus, for a host machine with 24 CPUs, you might want to
use 20 CPU threads (leaving 4 for other uses), with 8 LDM threads, 4 TC
threads (half the number of LDM threads), 3 send threads, 3 receive
threads, and 1 thread each for schema management, asynchronous
replication, and I/O operations.  (This is almost the same distribution
of threads used when 'MaxNoOfExecutionThreads' is set equal to 20.)  The
following 'ThreadConfig' setting performs these assignments,
additionally binding all of these threads to specific CPUs:

     ThreadConfig=ldm{count=8,cpubind=1,2,3,4,5,6,7,8},main={cpubind=9},io={cpubind=9}, \
     rep={cpubind=10},tc{count=4,cpubind=11,12,13,14},recv={count=3,cpubind=15,16,17}, \
     send{count=3,cpubind=18,19,20}

It should be possible in most cases to bind the main (schema management)
thread and the I/O thread to the same CPU, as we have done in the
example just shown.

The following example incorporates groups of CPUs defined using both
'cpuset' and 'cpubind', as well as use of thread prioritization.

     ThreadConfig=ldm={count=4,cpuset=0-3,thread_prio=8,spintime=200}, \
     ldm={count=4,cpubind=4-7,thread_prio=8,spintime=200}, \
     tc={count=4,cpuset=8-9,thread_prio=6},send={count=2,thread_prio=10,cpubind=10-11}, \
     main={count=1,cpubind=10},rep={count=1,cpubind=11}

In this case we create two LDM groups; the first uses 'cpubind' and the
second uses 'cpuset'.  'thread_prio' and 'spintime' are set to the same
values for each group.  This means there are eight LDM threads in total.
(You should ensure that 'NoOfFragmentLogParts' is also set to 8.)  The
four TC threads use only two CPUs; it is possible when using 'cpuset' to
specify fewer CPUs than threads in the group.  (This is not true for
'cpubind'.)  The send threads use two threads using 'cpubind' to bind
these threads to CPUs 10 and 11.  The main and rep threads can reuse
these CPUs.

This example shows how 'ThreadConfig' and 'NoOfFragmentLogParts' might
be set up for a 24-CPU host with hyperthreading, leaving CPUs 10, 11,
22, and 23 available for operating system functions and interrupts:

     NoOfFragmentLogParts=10
     ThreadConfig=ldm={count=10,cpubind=0-4,12-16,thread_prio=9,spintime=200}, \
     tc={count=4,cpuset=6-7,18-19,thread_prio=8},send={count=1,cpuset=8}, \
     recv={count=1,cpuset=20},main={count=1,cpuset=9,21},rep={count=1,cpuset=9,21}, \
     io={count=1,cpuset=9,21,thread_prio=8},watchdog={count=1,cpuset=9,21,thread_prio=9}

The next few examples include settings for 'idxbld'.  The first two of
of these demonstrate how a CPU set defined for 'idxbld' can overlap
those specified for other (permanent) thread types, the first using
'cpuset' and the second using 'cpubind':

     ThreadConfig=main,ldm={count=4,cpuset=1-4},tc={count=4,cpuset=5,6,7}, \
     io={cpubind=8},idxbld={cpuset=1-8}

     ThreadConfig=main,ldm={count=1,cpubind=1},idxbld={count=1,cpubind=1}

The next example specifies a CPU for the I/O thread, but not for the
index build threads:

     ThreadConfig=main,ldm={count=4,cpuset=1-4},tc={count=4,cpuset=5,6,7}, \
     io={cpubind=8}

Since the 'ThreadConfig' setting just shown locks threads to eight cores
numbered 1 through 8, it is equivalent to the setting shown here:

     ThreadConfig=main,ldm={count=4,cpuset=1-4},tc={count=4,cpuset=5,6,7}, \
     io={cpubind=8},idxbld={cpuset=1,2,3,4,5,6,7,8}

In order to take advantage of the enhanced stability that the use of
'ThreadConfig' offers, it is necessary to insure that CPUs are isolated,
and that they not subject to interrupts, or to being scheduled for other
tasks by the operating system.  On many Linux systems, you can do this
by setting 'IRQBALANCE_BANNED_CPUS' in '/etc/sysconfig/irqbalance' to
'0xFFFFF0', and by using the 'isolcpus' boot option in 'grub.conf'.  For
specific information, see your operating system or platform
documentation.

Disk Data Configuration Parameters

Configuration parameters affecting Disk Data behavior include the
following:

   *
     'DiskPageBufferEntries'

     *This table provides type and value information for the
     DiskPageBufferEntries data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      32K pages

     *Default*                            10

     *Range*                              1 - 1000

     *Restart Type.
     *

     This is the number of page entries (page references) to allocate.
     It is specified as a number of 32K pages in 'DiskPageBufferMemory'.
     The default is sufficient for most cases but you may need to
     increase the value of this parameter if you encounter problems with
     very large transactions on Disk Data tables.  Each page entry
     requires approximately 100 bytes.

   *
     'DiskPageBufferMemory'

     *This table provides type and value information for the
     DiskPageBufferMemory data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            64M

     *Range*                              4M - 1T

     *Restart Type.
     *

     This determines the amount of space used for caching pages on disk,
     and is set in the '[ndbd]' or '[ndbd default]' section of the
     'config.ini' file.  It is measured in bytes.  Each page takes up 32
     KB. This means that NDB Cluster Disk Data storage always uses N *
     32 KB memory where N is some nonnegative integer.

     The default value for this parameter is '64M' (2000 pages of 32 KB
     each).

     If the value for 'DiskPageBufferMemory' is set too low in
     conjunction with using more than the default number of LDM threads
     in 'ThreadConfig' (for example '{ldm=6...}'), problems can arise
     when trying to add a large (for example 500G) data file to a
     disk-based 'NDB' table, wherein the process takes indefinitely long
     while occupying one of the CPU cores.

     This is due to the fact that, as part of adding a data file to a
     tablespace, extent pages are locked into memory in an extra PGMAN
     worker thread, for quick metadata access.  When adding a large
     file, this worker has insufficient memory for all of the data file
     metadata.  In such cases, you should either increase
     'DiskPageBufferMemory', or add smaller tablespace files.  You may
     also need to adjust 'DiskPageBufferEntries'.

     You can query the 'ndbinfo.diskpagebuffer'
     table to help determine
     whether the value for this parameter should be increased to
     minimize unnecessary disk seeks.  See
     mysql-cluster-ndbinfo-diskpagebuffer, for more information.

   *
     'SharedGlobalMemory'

     *This table provides type and value information for the
     SharedGlobalMemory data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            128M

     *Range*                              0 - 64T

     *Restart Type.
     *

     This parameter determines the amount of memory that is used for log
     buffers, disk operations (such as page requests and wait queues),
     and metadata for tablespaces, log file groups, 'UNDO' files, and
     data files.  The shared global memory pool also provides memory
     used for satisfying the memory requirements of the
     'UNDO_BUFFER_SIZE' option used with 'CREATE LOGFILE GROUP'
     and 'ALTER LOGFILE GROUP'
     statements, including any default value
     implied for this options by the setting of the
     'InitialLogFileGroup' data node configuration parameter.
     'SharedGlobalMemory' can be set in the '[ndbd]' or '[ndbd default]'
     section of the 'config.ini' configuration file, and is measured in
     bytes.

     The default value is '128M'.

   *
     'DiskIOThreadPool'

     *This table provides type and value information for the
     DiskIOThreadPool data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      threads

     *Default*                            2

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter determines the number of unbound threads used for
     Disk Data file access.  Before 'DiskIOThreadPool' was introduced,
     exactly one thread was spawned for each Disk Data file, which could
     lead to performance issues, particularly when using very large data
     files.  With 'DiskIOThreadPool', you can--for example--access a
     single large data file using several threads working in parallel.

     This parameter applies to Disk Data I/O threads only.

     The optimum value for this parameter depends on your hardware and
     configuration, and includes these factors:

        * Physical distribution of Disk Data files

          You can obtain better performance by placing data files, undo
          log files, and the data node file system on separate physical
          disks.  If you do this with some or all of these sets of
          files, then you can set 'DiskIOThreadPool' higher to enable
          separate threads to handle the files on each disk.

        * Disk performance and types

          The number of threads that can be accommodated for Disk Data
          file handling is also dependent on the speed and throughput of
          the disks.  Faster disks and higher throughput allow for more
          disk I/O threads.  Our test results indicate that solid-state
          disk drives can handle many more disk I/O threads than
          conventional disks, and thus higher values for
          'DiskIOThreadPool'.

     The default value for this parameter is 2.

   * Disk Data file system parameters

     The parameters in the following list make it possible to place NDB
     Cluster Disk Data files in specific directories without the need
     for using symbolic links.

        *
          'FileSystemPathDD'

          *This table provides type and value information for the
          FileSystemPathDD data node configuration parameter*

          Property                             Value

          *Version (or later)*                 NDB 7.5.0

          *Type or units*                      filename

          *Default*                            [see text]

          *Range*                              ...

          *Restart Type.
          *

          If this parameter is specified, then NDB Cluster Disk Data
          data files and undo log files are placed in the indicated
          directory.  This can be overridden for data files, undo log
          files, or both, by specifying values for
          'FileSystemPathDataFiles', 'FileSystemPathUndoFiles', or both,
          as explained for these parameters.  It can also be overridden
          for data files by specifying a path in the 'ADD DATAFILE'
          clause of a 'CREATE TABLESPACE' or
          'ALTER TABLESPACE' statement, and for
          undo log files by specifying a path in the 'ADD UNDOFILE'
          clause of a 'CREATE LOGFILE GROUP'
          or 'ALTER LOGFILE GROUP'
          statement.  If 'FileSystemPathDD' is not
          specified, then 'FileSystemPath' is used.

          If a 'FileSystemPathDD' directory is specified for a given
          data node (including the case where the parameter is specified
          in the '[ndbd default]' section of the 'config.ini' file),
          then starting that data node with '--initial' causes all files
          in the directory to be deleted.

        *
          'FileSystemPathDataFiles'

          *This table provides type and value information for the
          FileSystemPathDataFiles data node configuration parameter*

          Property                             Value

          *Version (or later)*                 NDB 7.5.0

          *Type or units*                      filename

          *Default*                            [see text]

          *Range*                              ...

          *Restart Type.
          *

          If this parameter is specified, then NDB Cluster Disk Data
          data files are placed in the indicated directory.  This
          overrides any value set for 'FileSystemPathDD'.  This
          parameter can be overridden for a given data file by
          specifying a path in the 'ADD DATAFILE' clause of a
          'CREATE TABLESPACE' or 'ALTER TABLESPACE'
          statement used to create that
          data file.  If 'FileSystemPathDataFiles' is not specified,
          then 'FileSystemPathDD' is used (or 'FileSystemPath', if
          'FileSystemPathDD' has also not been set).

          If a 'FileSystemPathDataFiles' directory is specified for a
          given data node (including the case where the parameter is
          specified in the '[ndbd default]' section of the 'config.ini'
          file), then starting that data node with '--initial' causes
          all files in the directory to be deleted.

        *
          'FileSystemPathUndoFiles'

          *This table provides type and value information for the
          FileSystemPathUndoFiles data node configuration parameter*

          Property                             Value

          *Version (or later)*                 NDB 7.5.0

          *Type or units*                      filename

          *Default*                            [see text]

          *Range*                              ...

          *Restart Type.
          *

          If this parameter is specified, then NDB Cluster Disk Data
          undo log files are placed in the indicated directory.  This
          overrides any value set for 'FileSystemPathDD'.  This
          parameter can be overridden for a given data file by
          specifying a path in the 'ADD UNDO' clause of a 'CREATE LOGFILE GROUP'
          or 'ALTER LOGFILE GROUP'
          statement used to create that
          data file.  If 'FileSystemPathUndoFiles' is not specified,
          then 'FileSystemPathDD' is used (or 'FileSystemPath', if
          'FileSystemPathDD' has also not been set).

          If a 'FileSystemPathUndoFiles' directory is specified for a
          given data node (including the case where the parameter is
          specified in the '[ndbd default]' section of the 'config.ini'
          file), then starting that data node with '--initial' causes
          all files in the directory to be deleted.

     For more information, see mysql-cluster-disk-data-objects.

   * Disk Data object creation parameters

     The next two parameters enable you--when starting the cluster for
     the first time--to cause a Disk Data log file group, tablespace, or
     both, to be created without the use of SQL statements.

        *
          'InitialLogFileGroup'

          *This table provides type and value information for the
          InitialLogFileGroup data node configuration parameter*

          Property                             Value

          *Version (or later)*                 NDB 7.5.0

          *Type or units*                      string

          *Default*                            [see text]

          *Range*                              ...

          *Restart Type.
          *

          This parameter can be used to specify a log file group that is
          created when performing an initial start of the cluster.
          'InitialLogFileGroup' is specified as shown here:

               InitialLogFileGroup = [name=NAME;] [undo_buffer_size=SIZE;] FILE-SPECIFICATION-LIST

               FILE-SPECIFICATION-LIST:
                   FILE-SPECIFICATION[; FILE-SPECIFICATION[; ...]]

               FILE-SPECIFICATION:
                   FILENAME:SIZE

          The 'name' of the log file group is optional and defaults to
          'DEFAULT-LG'.  The 'undo_buffer_size' is also optional; if
          omitted, it defaults to '64M'.  Each FILE-SPECIFICATION
          corresponds to an undo log file, and at least one must be
          specified in the FILE-SPECIFICATION-LIST.  Undo log files are
          placed according to any values that have been set for
          'FileSystemPath', 'FileSystemPathDD', and
          'FileSystemPathUndoFiles', just as if they had been created as
          the result of a 'CREATE LOGFILE GROUP'
          or 'ALTER LOGFILE GROUP'
          statement.

          Consider the following:

               InitialLogFileGroup = name=LG1; undo_buffer_size=128M; undo1.log:250M; undo2.log:150M

          This is equivalent to the following SQL statements:

               CREATE LOGFILE GROUP LG1
                   ADD UNDOFILE 'undo1.log'
                   INITIAL_SIZE 250M
                   UNDO_BUFFER_SIZE 128M
                   ENGINE NDBCLUSTER;

               ALTER LOGFILE GROUP LG1
                   ADD UNDOFILE 'undo2.log'
                   INITIAL_SIZE 150M
                   ENGINE NDBCLUSTER;

          This logfile group is created when the data nodes are started
          with '--initial'.

          Resources for the initial log file group are added to the
          global memory pool along with those indicated by the value of
          'SharedGlobalMemory'.

          This parameter, if used, should always be set in the '[ndbd
          default]' section of the 'config.ini' file.  The behavior of
          an NDB Cluster when different values are set on different data
          nodes is not defined.

        *
          'InitialTablespace'

          *This table provides type and value information for the
          InitialTablespace data node configuration parameter*

          Property                             Value

          *Version (or later)*                 NDB 7.5.0

          *Type or units*                      string

          *Default*                            [see text]

          *Range*                              ...

          *Restart Type.
          *

          This parameter can be used to specify an NDB Cluster Disk Data
          tablespace that is created when performing an initial start of
          the cluster.  'InitialTablespace' is specified as shown here:

               InitialTablespace = [name=NAME;] [extent_size=SIZE;] FILE-SPECIFICATION-LIST

          The 'name' of the tablespace is optional and defaults to
          'DEFAULT-TS'.  The 'extent_size' is also optional; it defaults
          to '1M'.  The FILE-SPECIFICATION-LIST uses the same syntax as
          shown with the 'InitialLogfileGroup' parameter, the only
          difference being that each FILE-SPECIFICATION used with
          'InitialTablespace' corresponds to a data file.  At least one
          must be specified in the FILE-SPECIFICATION-LIST.  Data files
          are placed according to any values that have been set for
          'FileSystemPath', 'FileSystemPathDD', and
          'FileSystemPathDataFiles', just as if they had been created as
          the result of a 'CREATE TABLESPACE'.
          or 'ALTER TABLESPACE' statement.

          For example, consider the following line specifying
          'InitialTablespace' in the '[ndbd default]' section of the
          'config.ini' file (as with 'InitialLogfileGroup', this
          parameter should always be set in the '[ndbd default]'
          section, as the behavior of an NDB Cluster when different
          values are set on different data nodes is not defined):

               InitialTablespace = name=TS1; extent_size=8M; data1.dat:2G; data2.dat:4G

          This is equivalent to the following SQL statements:

               CREATE TABLESPACE TS1
                   ADD DATAFILE 'data1.dat'
                   EXTENT_SIZE 8M
                   INITIAL_SIZE 2G
                   ENGINE NDBCLUSTER;

               ALTER TABLESPACE TS1
                   ADD DATAFILE 'data2.dat'
                   INITIAL_SIZE 4G
                   ENGINE NDBCLUSTER;

          This tablespace is created when the data nodes are started
          with '--initial', and can be used whenever creating NDB
          Cluster Disk Data tables thereafter.

Disk Data and GCP Stop errors

Errors encountered when using Disk Data tables such as 'Node NODEID
killed this node because GCP stop was detected' (error 2303) are often
referred to as 'GCP stop errors'.  Such errors occur when the redo log
is not flushed to disk quickly enough; this is usually due to slow disks
and insufficient disk throughput.

You can help prevent these errors from occurring by using faster disks,
and by placing Disk Data files on a separate disk from the data node
file system.  Reducing the value of 'TimeBetweenGlobalCheckpoints' tends
to decrease the amount of data to be written for each global checkpoint,
and so may provide some protection against redo log buffer overflows
when trying to write a global checkpoint; however, reducing this value
also permits less time in which to write the GCP, so this must be done
with caution.

In addition to the considerations given for 'DiskPageBufferMemory' as
explained previously, it is also very important that the
'DiskIOThreadPool' configuration parameter be set correctly; having
'DiskIOThreadPool' set too high is very likely to cause GCP stop errors
(Bug #37227).

GCP stops can be caused by save or commit timeouts; the
'TimeBetweenEpochsTimeout' data node configuration parameter determines
the timeout for commits.  However, it is possible to disable both types
of timeouts by setting this parameter to 0.

Parameters for configuring send buffer memory allocation

Send buffer memory is allocated dynamically from a memory pool shared
between all transporters, which means that the size of the send buffer
can be adjusted as necessary.  (Previously, the NDB kernel used a
fixed-size send buffer for every node in the cluster, which was
allocated when the node started and could not be changed while the node
was running.)  The 'TotalSendBufferMemory' and 'OverLoadLimit' data node
configuration parameters permit the setting of limits on this memory
allocation.  For more information about the use of these parameters (as
well as 'SendBufferMemory'), see
mysql-cluster-config-send-buffers.

   *
     'ExtraSendBufferMemory'

     This parameter specifies the amount of transporter send buffer
     memory to allocate in addition to any set using
     'TotalSendBufferMemory', 'SendBufferMemory', or both.

   *
     'TotalSendBufferMemory'

     This parameter is used to determine the total amount of memory to
     allocate on this node for shared send buffer memory among all
     configured transporters.

     If this parameter is set, its minimum permitted value is 256KB; 0
     indicates that the parameter has not been set.  For more detailed
     information, see mysql-cluster-config-send-buffers.

See also mysql-cluster-online-add-node.

Redo log over-commit handling

It is possible to control a data node's handling of operations when too
much time is taken flushing redo logs to disk.  This occurs when a given
redo log flush takes longer than 'RedoOverCommitLimit' seconds, more
than 'RedoOverCommitCounter' times, causing any pending transactions to
be aborted.  When this happens, the API node that sent the transaction
can handle the operations that should have been committed either by
queuing the operations and re-trying them, or by aborting them, as
determined by 'DefaultOperationRedoProblemAction'.  The data node
configuration parameters for setting the timeout and number of times it
may be exceeded before the API node takes this action are described in
the following list:

   *
     'RedoOverCommitCounter'

     *This table provides type and value information for the
     RedoOverCommitCounter data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            3

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When 'RedoOverCommitLimit' is exceeded when trying to write a given
     redo log to disk this many times or more, any transactions that
     were not committed as a result are aborted, and an API node where
     any of these transactions originated handles the operations making
     up those transactions according to its value for
     'DefaultOperationRedoProblemAction' (by either queuing the
     operations to be re-tried, or aborting them).

     'RedoOverCommitCounter' defaults to 3.  Set it to 0 to disable the
     limit.

   *
     'RedoOverCommitLimit'

     *This table provides type and value information for the
     RedoOverCommitLimit data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      seconds

     *Default*                            20

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter sets an upper limit in seconds for trying to write a
     given redo log to disk before timing out.  The number of times the
     data node tries to flush this redo log, but takes longer than
     'RedoOverCommitLimit', is kept and compared with
     'RedoOverCommitCounter', and when flushing takes too long more
     times than the value of that parameter, any transactions that were
     not committed as a result of the flush timeout are aborted.  When
     this occurs, the API node where any of these transactions
     originated handles the operations making up those transactions
     according to its 'DefaultOperationRedoProblemAction' setting (it
     either queues the operations to be re-tried, or aborts them).

     By default, 'RedoOverCommitLimit' is 20 seconds.  Set to 0 to
     disable checking for redo log flush timeouts.

Controlling restart attempts

It is possible to exercise finely-grained control over restart attempts
by data nodes when they fail to start using the 'MaxStartFailRetries'
and 'StartFailRetryDelay' data node configuration parameters.

'MaxStartFailRetries' limits the total number of retries made before
giving up on starting the data node, 'StartFailRetryDelay' sets the
number of seconds between retry attempts.  These parameters are listed
here:

   *
     'StartFailRetryDelay'

     *This table provides type and value information for the
     StartFailRetryDelay data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Use this parameter to set the number of seconds between restart
     attempts by the data node in the event on failure on startup.  The
     default is 0 (no delay).

     Both this parameter and 'MaxStartFailRetries' are ignored unless
     'StopOnError' is equal to 0.

   *
     'MaxStartFailRetries'

     *This table provides type and value information for the
     MaxStartFailRetries data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            3

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Use this parameter to limit the number restart attempts made by the
     data node in the event that it fails on startup.  The default is 3
     attempts.

     Both this parameter and 'StartFailRetryDelay' are ignored unless
     'StopOnError' is equal to 0.

NDB index statistics parameters

The parameters in the following list relate to NDB index statistics
generation.

   *
     'IndexStatAutoCreate'

     *This table provides type and value information for the
     IndexStatAutoCreate data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              false, true

     *Restart Type.
     *

     Enable or disable automatic statistics collection when indexes are
     created.  Disabled by default.

   *
     'IndexStatAutoUpdate'

     *This table provides type and value information for the
     IndexStatAutoUpdate data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              false, true

     *Restart Type.
     *

     Enable or disable monitoring of indexes for changes and trigger
     automatic statistics updates these are detected.  The amount and
     degree of change needed to trigger the updates are determined by
     the settings for the 'IndexStatTriggerPct' and
     'IndexStatTriggerScale' options.

   *
     'IndexStatSaveSize'

     *This table provides type and value information for the
     IndexStatSaveSize data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            32768

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Maximum space in bytes allowed for the saved statistics of any
     given index in the 'NDB' system tables and in
     the 'mysqld' memory cache.  This consumes
     'IndexMemory'.

     At least one sample is always produced, regardless of any size
     limit.  This size is scaled by 'IndexStatSaveScale'.

     The size specified by 'IndexStatSaveSize' is scaled by the value of
     'IndexStatTriggerPct' for a large index, times 0.01.  This is
     further multiplied by the logarithm to the base 2 of the index
     size.  Setting 'IndexStatTriggerPct' equal to 0 disables the
     scaling effect.

   *
     'IndexStatSaveScale'

     *This table provides type and value information for the
     IndexStatSaveScale data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      percentage

     *Default*                            100

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     The size specified by 'IndexStatSaveSize' is scaled by the value of
     'IndexStatTriggerPct' for a large index, times 0.01.  This is
     further multiplied by the logarithm to the base 2 of the index
     size.  Setting 'IndexStatTriggerPct' equal to 0 disables the
     scaling effect.

   *
     'IndexStatTriggerPct'

     *This table provides type and value information for the
     IndexStatTriggerPct data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      percentage

     *Default*                            100

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Percentage change in updates that triggers an index statistics
     update.  The value is scaled by 'IndexStatTriggerScale'.  You can
     disable this trigger altogether by setting 'IndexStatTriggerPct' to
     0.

   *
     'IndexStatTriggerScale'

     *This table provides type and value information for the
     IndexStatTriggerScale data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      percentage

     *Default*                            100

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Scale 'IndexStatTriggerPct' by this amount times 0.01 for a large
     index.  A value of 0 disables scaling.

   *
     'IndexStatUpdateDelay'

     *This table provides type and value information for the
     IndexStatUpdateDelay data node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      seconds

     *Default*                            60

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Minimum delay in seconds between automatic index statistics updates
     for a given index.  Setting this variable to 0 disables any delay.
     The default is 60 seconds.

21.3.3.7 Defining SQL and Other API Nodes in an NDB Cluster
...........................................................

The '[mysqld]' and '[api]' sections in the 'config.ini' file define the
behavior of the MySQL servers (SQL nodes) and other applications (API
nodes) used to access cluster data.  None of the parameters shown is
required.  If no computer or host name is provided, any host can use
this SQL or API node.

Generally speaking, a '[mysqld]' section is used to indicate a MySQL
server providing an SQL interface to the cluster, and an '[api]' section
is used for applications other than 'mysqld' processes
accessing cluster data, but the two designations are actually
synonymous; you can, for instance, list parameters for a MySQL server
acting as an SQL node in an '[api]' section.

*Note*:

For a discussion of MySQL server options for NDB Cluster, see
mysql-cluster-program-options-mysqld; for information about MySQL
server system variables relating to NDB Cluster, see
mysql-cluster-system-variables.

   *
     'Id'

     *This table provides type and value information for the Id API node
     configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              1 - 255

     *Restart Type.
     *

     The 'Id' is an integer value used to identify the node in all
     cluster internal messages.  The permitted range of values is 1 to
     255 inclusive.  This value must be unique for each node in the
     cluster, regardless of the type of node.

     *Note*:

     Data node IDs must be less than 49, regardless of the NDB Cluster
     version used.  If you plan to deploy a large number of data nodes,
     it is a good idea to limit the node IDs for API nodes (and
     management nodes) to values greater than 48.

     'NodeId' is the preferred parameter name to use when identifying
     API nodes.  ('Id' continues to be supported for backward
     compatibility, but is now deprecated and generates a warning when
     used.  It is also subject to future removal.)

   *
     'ConnectionMap'

     *This table provides type and value information for the
     ConnectionMap API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      string

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     Specifies which data nodes to connect.

   *
     'NodeId'

     *This table provides type and value information for the NodeId API
     node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              1 - 255

     *Restart Type.
     *

     The 'NodeId' is an integer value used to identify the node in all
     cluster internal messages.  The permitted range of values is 1 to
     255 inclusive.  This value must be unique for each node in the
     cluster, regardless of the type of node.

     *Note*:

     Data node IDs must be less than 49, regardless of the NDB Cluster
     version used.  If you plan to deploy a large number of data nodes,
     it is a good idea to limit the node IDs for API nodes (and
     management nodes) to values greater than 48.

     'NodeId' is the preferred parameter name to use when identifying
     management nodes.  An alias, 'Id', was used for this purpose in
     very old versions of NDB Cluster, and continues to be supported for
     backward compatibility; it is now deprecated and generates a
     warning when used, and is subject to removal in a future release of
     NDB Cluster.

   *
     'ExecuteOnComputer'

     *This table provides type and value information for the
     ExecuteOnComputer API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     This refers to the 'Id' set for one of the computers (hosts)
     defined in a '[computer]' section of the configuration file.

     *Important*:

     This parameter is deprecated as of NDB 7.5.0, and is subject to
     removal in a future release.  Use the 'HostName' parameter instead.

   *
     'HostName'

     *This table provides type and value information for the HostName
     API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     Specifying this parameter defines the hostname of the computer on
     which the SQL node (API node) is to reside.  To specify a hostname,
     either this parameter or 'ExecuteOnComputer' is required.

     If no 'HostName' or 'ExecuteOnComputer' is specified in a given
     '[mysql]' or '[api]' section of the 'config.ini' file, then an SQL
     or API node may connect using the corresponding 'slot' from any
     host which can establish a network connection to the management
     server host machine.  _This differs from the default behavior for
     data nodes, where 'localhost' is assumed for 'HostName' unless
     otherwise specified_.

   *
     'LocationDomainId'

     *This table provides type and value information for the
     LocationDomainId API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.6.4

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 16

     *Restart Type.
     *

     Assigns an SQL or other API node to a specific availability domain
     (https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm)
     (also known as an availability zone) within a cloud.  By informing
     'NDB' which nodes are in which availability domains, performance
     can be improved in a cloud environment in the following ways:

        * If requested data is not found on the same node, reads can be
          directed to another node in the same availability domain.

        * Communication between nodes in different availability domains
          are guaranteed to use 'NDB' transporters' WAN support without
          any further manual intervention.

        * The transporter's group number can be based on which
          availability domain is used, such that also SQL and other API
          nodes communicate with local data nodes in the same
          availability domain whenever possible.

        * The arbitrator can be selected from an availability domain in
          which no data nodes are present, or, if no such availability
          domain can be found, from a third availability domain.

     'LocationDomainId' takes an integer value between 0 and 16
     inclusive, with 0 being the default; using 0 is the same as leaving
     the parameter unset.

   *
     'ArbitrationRank'

     *This table provides type and value information for the
     ArbitrationRank API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      0-2

     *Default*                            0

     *Range*                              0 - 2

     *Restart Type.
     *

     This parameter defines which nodes can act as arbitrators.  Both
     management nodes and SQL nodes can be arbitrators.  A value of 0
     means that the given node is never used as an arbitrator, a value
     of 1 gives the node high priority as an arbitrator, and a value of
     2 gives it low priority.  A normal configuration uses the
     management server as arbitrator, setting its 'ArbitrationRank' to 1
     (the default for management nodes) and those for all SQL nodes to 0
     (the default for SQL nodes).

     By setting 'ArbitrationRank' to 0 on all management and SQL nodes,
     you can disable arbitration completely.  You can also control
     arbitration by overriding this parameter; to do so, set the
     'Arbitration' parameter in the '[ndbd default]' section of the
     'config.ini' global configuration file.

   *
     'ArbitrationDelay'

     *This table provides type and value information for the
     ArbitrationDelay API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      milliseconds

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Setting this parameter to any other value than 0 (the default)
     means that responses by the arbitrator to arbitration requests will
     be delayed by the stated number of milliseconds.  It is usually not
     necessary to change this value.

   *
     'BatchByteSize'

     *This table provides type and value information for the
     BatchByteSize API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            16K

     *Range*                              1K - 1M

     *Restart Type.
     *

     For queries that are translated into full table scans or range
     scans on indexes, it is important for best performance to fetch
     records in properly sized batches.  It is possible to set the
     proper size both in terms of number of records ('BatchSize') and in
     terms of bytes ('BatchByteSize').  The actual batch size is limited
     by both parameters.

     The speed at which queries are performed can vary by more than 40%
     depending upon how this parameter is set.

     This parameter is measured in bytes.  The default value is 16K.

   *
     'BatchSize'

     *This table provides type and value information for the BatchSize
     API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      records

     *Default*                            256

     *Range*                              1 - 992

     *Restart Type.
     *

     This parameter is measured in number of records and is by default
     set to 256.  The maximum size is 992.

   *
     'ExtraSendBufferMemory'

     *This table provides type and value information for the
     ExtraSendBufferMemory API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter specifies the amount of transporter send buffer
     memory to allocate in addition to any that has been set using
     'TotalSendBufferMemory', 'SendBufferMemory', or both.

   *
     'HeartbeatThreadPriority'

     *This table provides type and value information for the
     HeartbeatThreadPriority API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      string

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     Use this parameter to set the scheduling policy and priority of
     heartbeat threads for management and API nodes.  The syntax for
     setting this parameter is shown here:

          HeartbeatThreadPriority = POLICY[, PRIORITY]

          POLICY:
            {FIFO | RR}

     When setting this parameter, you must specify a policy.  This is
     one of 'FIFO' (first in, first in) or 'RR' (round robin).  This
     followed optionally by the priority (an integer).

   *
     'MaxScanBatchSize'

     *This table provides type and value information for the
     MaxScanBatchSize API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            256K

     *Range*                              32K - 16M

     *Restart Type.
     *

     The batch size is the size of each batch sent from each data node.
     Most scans are performed in parallel to protect the MySQL Server
     from receiving too much data from many nodes in parallel; this
     parameter sets a limit to the total batch size over all nodes.

     The default value of this parameter is set to 256KB. Its maximum
     size is 16MB.

   *
     'TotalSendBufferMemory'

     *This table provides type and value information for the
     TotalSendBufferMemory API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            0

     *Range*                              256K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This parameter is used to determine the total amount of memory to
     allocate on this node for shared send buffer memory among all
     configured transporters.

     If this parameter is set, its minimum permitted value is 256KB; 0
     indicates that the parameter has not been set.  For more detailed
     information, see mysql-cluster-config-send-buffers.

   *
     'AutoReconnect'

     *This table provides type and value information for the
     AutoReconnect API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     This parameter is 'false' by default.  This forces disconnected API
     nodes (including MySQL Servers acting as SQL nodes) to use a new
     connection to the cluster rather than attempting to re-use an
     existing one, as re-use of connections can cause problems when
     using dynamically-allocated node IDs.  (Bug #45921)

     *Note*:

     This parameter can be overridden using the NDB API. For more
     information, see Ndb_cluster_connection::set_auto_reconnect()
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-set-auto-reconnect.html),
     and Ndb_cluster_connection::get_auto_reconnect()
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-get-auto-reconnect.html).

   *
     'DefaultOperationRedoProblemAction'

     *This table provides type and value information for the
     DefaultOperationRedoProblemAction API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      enumeration

     *Default*                            QUEUE

     *Range*                              ABORT, QUEUE

     *Restart Type.
     *

     This parameter (along with 'RedoOverCommitLimit' and
     'RedoOverCommitCounter') controls the data node's handling of
     operations when too much time is taken flushing redo logs to disk.
     This occurs when a given redo log flush takes longer than
     'RedoOverCommitLimit' seconds, more than 'RedoOverCommitCounter'
     times, causing any pending transactions to be aborted.

     When this happens, the node can respond in either of two ways,
     according to the value of 'DefaultOperationRedoProblemAction',
     listed here:

        * 'ABORT': Any pending operations from aborted transactions are
          also aborted.

        * 'QUEUE': Pending operations from transactions that were
          aborted are queued up to be re-tried.  This the default.
          Pending operations are still aborted when the redo log runs
          out of space--that is, when P_TAIL_PROBLEM errors occur.

   *
     'DefaultHashMapSize'

     *This table provides type and value information for the
     DefaultHashMapSize API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      buckets

     *Default*                            3840

     *Range*                              0 - 3840

     *Restart Type.
     *

     The size of the table hash maps used by 'NDB'.
     is configurable using this parameter.  'DefaultHashMapSize' can
     take any of three possible values (0, 240, 3840).  These values and
     their effects are described in the following table.

     *DefaultHashMapSize parameter values*

     Value          Description / Effect

     '0'            Use the lowest value set, if any, for this parameter
                    among all data nodes and API nodes in the cluster; if it
                    is not set on any data or API node, use the default
                    value.

     '240'          Original hash map size (used by default prior to NDB
                    7.2.7.

     '3840'         Larger hash map size as (used by default in NDB 7.2.7
                    and later

     The original intended use for this parameter was to facilitate
     upgrades and downgrades to and from older NDB Cluster versions, in
     which the hash map size differed, due to the fact that this change
     was not otherwise backward compatible.  This is not an issue when
     upgrading or downgrading from NDB Cluster 7.5.

   *
     'Wan'

     *This table provides type and value information for the wan API
     node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     Use WAN TCP setting as default.

   *
     'ConnectBackoffMaxTime'

     *This table provides type and value information for the
     ConnectBackoffMaxTime API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     In an NDB Cluster with many unstarted data nodes, the value of this
     parameter can be raised to circumvent connection attempts to data
     nodes which have not yet begun to function in the cluster, as well
     as moderate high traffic to management nodes.  As long as the API
     node is not connected to any new data nodes, the value of the
     'StartConnectBackoffMaxTime' parameter is applied; otherwise,
     'ConnectBackoffMaxTime' is used to determine the length of time in
     milliseconds to wait between connection attempts.

     Time elapsed _during_ node connection attempts is not taken into
     account when calculating elapsed time for this parameter.  The
     timeout is applied with approximately 100 ms resolution, starting
     with a 100 ms delay; for each subsequent attempt, the length of
     this period is doubled until it reaches 'ConnectBackoffMaxTime'
     milliseconds, up to a maximum of 100000 ms (100s).

     Once the API node is connected to a data node and that node reports
     (in a heartbeat message) that it has connected to other data nodes,
     connection attempts to those data nodes are no longer affected by
     this parameter, and are made every 100 ms thereafter until
     connected.  Once a data node has started, it can take up
     'HeartbeatIntervalDbApi' for the API node to be notified that this
     has occurred.

   *
     'StartConnectBackoffMaxTime'

     *This table provides type and value information for the
     StartConnectBackoffMaxTime API node configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      integer

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     In an NDB Cluster with many unstarted data nodes, the value of this
     parameter can be raised to circumvent connection attempts to data
     nodes which have not yet begun to function in the cluster, as well
     as moderate high traffic to management nodes.  As long as the API
     node is not connected to any new data nodes, the value of the
     'StartConnectBackoffMaxTime' parameter is applied; otherwise,
     'ConnectBackoffMaxTime' is used to determine the length of time in
     milliseconds to wait between connection attempts.

     Time elapsed _during_ node connection attempts is not taken into
     account when calculating elapsed time for this parameter.  The
     timeout is applied with approximately 100 ms resolution, starting
     with a 100 ms delay; for each subsequent attempt, the length of
     this period is doubled until it reaches
     'StartConnectBackoffMaxTime' milliseconds, up to a maximum of
     100000 ms (100s).

     Once the API node is connected to a data node and that node reports
     (in a heartbeat message) that it has connected to other data nodes,
     connection attempts to those data nodes are no longer affected by
     this parameter, and are made every 100 ms thereafter until
     connected.  Once a data node has started, it can take up
     'HeartbeatIntervalDbApi' for the API node to be notified that this
     has occurred.

API Node Debugging Parameters

Beginning with NDB 7.5.2, you can use the 'ApiVerbose' configuration
parameter to enable debugging output from a given API node.  This
parameter takes an integer value.  0 is the default, and disables such
debugging; 1 enables debugging output to the cluster log; 2 adds
'DBDICT' debugging output as well.  (Bug #20638450) See also DUMP 1229
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-dump-command-1229.html).

You can also obtain information from a MySQL server running as an NDB
Cluster SQL node using 'SHOW STATUS' in the
'mysql' client, as shown here:

     mysql> SHOW STATUS LIKE 'ndb%';
     +-----------------------------+----------------+
     | Variable_name               | Value          |
     +-----------------------------+----------------+
     | Ndb_cluster_node_id         | 5              |
     | Ndb_config_from_host        | 198.51.100.112 |
     | Ndb_config_from_port        | 1186           |
     | Ndb_number_of_storage_nodes | 4              |
     +-----------------------------+----------------+
     4 rows in set (0.02 sec)

For information about the status variables appearing in the output from
this statement, see mysql-cluster-status-variables.

*Note*:

To add new SQL or API nodes to the configuration of a running NDB
Cluster, it is necessary to perform a rolling restart of all cluster
nodes after adding new '[mysqld]' or '[api]' sections to the
'config.ini' file (or files, if you are using more than one management
server).  This must be done before the new SQL or API nodes can connect
to the cluster.

It is _not_ necessary to perform any restart of the cluster if new SQL
or API nodes can employ previously unused API slots in the cluster
configuration to connect to the cluster.

21.3.3.8 Defining the System
............................

The '[system]' section is used for parameters applying to the cluster as
a whole.  The 'Name' system parameter is used with MySQL Enterprise
Monitor; 'ConfigGenerationNumber' and 'PrimaryMGMNode' are not used in
production environments.  Except when using NDB Cluster with MySQL
Enterprise Monitor, is not necessary to have a '[system]' section in the
'config.ini' file.

More information about these parameters can be found in the following
list:

   *
     'ConfigGenerationNumber'

     *This table provides type and value information for the
     ConfigGenerationNumber system configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Configuration generation number.  This parameter is currently
     unused.

   *
     'Name'

     *This table provides type and value information for the Name system
     configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      string

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     Set a name for the cluster.  This parameter is required for
     deployments with MySQL Enterprise Monitor; it is otherwise unused.

   *
     'PrimaryMGMNode'

     *This table provides type and value information for the
     PrimaryMGMNode system configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Node ID of the primary management node.  This parameter is
     currently unused.

21.3.3.9 MySQL Server Options and Variables for NDB Cluster
...........................................................

This section provides information about MySQL server options, server and
status variables that are specific to NDB Cluster.  For general
information on using these, and for other options and variables not
specific to NDB Cluster, see mysqld-server.

For NDB Cluster configuration parameters used in the cluster
configuration file (usually named 'config.ini'), see
mysql-cluster-configuration.

21.3.3.10 MySQL Server Options for NDB Cluster
..............................................

This section provides descriptions of 'mysqld' server
options relating to NDB Cluster.  For information about 'mysqld'
options not specific to NDB Cluster, and for general information
about the use of options with 'mysqld', see
server-options.

For information about command-line options used with other NDB Cluster
processes (see 'ndbd', 'ndb_mgmd',
and 'ndb_mgm'),
see
mysql-cluster-program-options-common.  For information about
command-line options used with 'NDB' utility
programs (such as 'ndb_desc',
'ndb_size.pl', and
'ndb_show_tables'), see
mysql-cluster-programs.

   *
     '--ndbcluster'

     * Type and value information for ndbcluster*

     Property                  Value

     Name                      'ndbcluster'

     Command Line              Yes

     System Variable           No

     Status Variable           No

     Option File               Yes

     Scope

     Dynamic                   No

     Type

     Default, Range            FALSE (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Enable NDB Cluster (if this
                               version of MySQL supports it)

                               Disabled by '--skip-ndbcluster'.

     The 'NDBCLUSTER' storage engine is necessary
     for using NDB Cluster.  If a 'mysqld' binary
     includes support for the 'NDBCLUSTER' storage
     engine, the engine is disabled by default.  Use the '--ndbcluster'
     option to enable it.  Use '--skip-ndbcluster' to explicitly disable
     the engine.

     It is not necessary or desirable to use this option together with
     '--initialize'.  Beginning with NDB 7.5.4, '--ndbcluster' is
     ignored (and the 'NDB' storage engine is _not_ enabled) if
     '--initialize' is also used.  (Bug #81689, Bug #23518923)

   *
     '--ndb-allow-copying-alter-table=[ON|OFF]'

     * Type and value information for ndb-allow-copying-alter-table*

     Property                  Value

     Name                      'ndb-allow-copying-alter-table'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            ON (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Set to OFF to keep ALTER TABLE
                               from using copying operations on NDB tables

     Let 'ALTER TABLE' and other DDL statements use
     copying operations on 'NDB' tables.  Set to 'OFF' to keep this from
     happening; doing so may improve performance of critical
     applications.

   *
     '--ndb-batch-size=#'

     * Type and value information for ndb-batch-size*

     Property                  Value

     Name                      'ndb-batch-size'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            32768 / 0 - 31536000 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Size (in bytes) to use for NDB
                               transaction batches

     This sets the size in bytes that is used for NDB transaction
     batches.

   *
     '--ndb-cluster-connection-pool=#'

     * Type and value information for ndb-cluster-connection-pool*

     Property                  Value

     Name                      'ndb-cluster-connection-pool'

     Command Line              Yes

     System Variable           Yes

     Status Variable           Yes

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            1 / 1 - 63 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Number of connections to the
                               cluster used by MySQL

     By setting this option to a value greater than 1 (the default), a
     'mysqld' process can use multiple connections to the
     cluster, effectively mimicking several SQL nodes.  Each connection
     requires its own '[api]' or '[mysqld]' section in the cluster
     configuration ('config.ini') file, and counts against the maximum
     number of API connections supported by the cluster.

     Suppose that you have 2 cluster host computers, each running an SQL
     node whose 'mysqld' process was started with
     '--ndb-cluster-connection-pool=4'; this means that the cluster must
     have 8 API slots available for these connections (instead of 2).
     All of these connections are set up when the SQL node connects to
     the cluster, and are allocated to threads in a round-robin fashion.

     This option is useful only when running 'mysqld' on
     host machines having multiple CPUs, multiple cores, or both.  For
     best results, the value should be smaller than the total number of
     cores available on the host machine.  Setting it to a value greater
     than this is likely to degrade performance severely.

     *Important*:

     Because each SQL node using connection pooling occupies multiple
     API node slots--each slot having its own node ID in the
     cluster--you must _not_ use a node ID as part of the cluster
     connection string when starting any 'mysqld' process
     that employs connection pooling.

     Setting a node ID in the connection string when using the
     '--ndb-cluster-connection-pool' option causes node ID allocation
     errors when the SQL node attempts to connect to the cluster.

   *
     '--ndb-cluster-connection-pool-nodeids=LIST'

     * Type and value information for
     ndb-cluster-connection-pool-nodeids*

     Property                  Value

     Name                      'ndb-cluster-connection-pool-nodeids'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            / (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Comma-separated list of node IDs
                               for connections to the cluster used by MySQL;
                               the number of nodes in the list must be the
                               same as the value set for
                               -ndb-cluster-connection-pool

     Specifies a comma-separated list of node IDs for connections to the
     cluster used by an SQL node.  The number of nodes in this list must
     be the same as the value set for the
     '--ndb-cluster-connection-pool' option.

     '--ndb-cluster-connection-pool-nodeids' was added in NDB 7.5.0.

   *
     '--ndb-blob-read-batch-bytes=BYTES'

     * Type and value information for ndb-blob-read-batch-bytes*

     Property                  Value

     Name                      'ndb-blob-read-batch-bytes'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            65536 / 0 - 4294967295 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Specifies size in bytes that
                               large BLOB reads should be batched into.  0 =
                               no limit.

     This option can be used to set the size (in bytes) for batching of
     'BLOB' data reads in NDB Cluster applications.  When
     this batch size is exceeded by the amount of 'BLOB'.
     data to be read within the current transaction, any pending
     'BLOB' read operations are immediately executed.

     The maximum value for this option is 4294967295; the default is
     65536.  Setting it to 0 has the effect of disabling 'BLOB'
     read batching.

     *Note*:

     In NDB API applications, you can control 'BLOB' write
     batching with the 'setMaxPendingBlobReadBytes()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-setmaxpendingblobreadbytes.html)
     and 'getMaxPendingBlobReadBytes()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-getmaxpendingblobreadbytes.html)
     methods.

   *
     '--ndb-blob-write-batch-bytes=BYTES'

     * Type and value information for ndb-blob-write-batch-bytes*

     Property                  Value

     Name                      'ndb-blob-write-batch-bytes'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            65536 / 0 - 4294967295 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Specifies size in bytes that
                               large BLOB writes should be batched into.  0
                               = no limit.

     This option can be used to set the size (in bytes) for batching of
     'BLOB' data writes in NDB Cluster applications.  When
     this batch size is exceeded by the amount of 'BLOB'.
     data to be written within the current transaction, any pending
     'BLOB' write operations are immediately executed.

     The maximum value for this option is 4294967295; the default is
     65536.  Setting it to 0 has the effect of disabling 'BLOB'
     write batching.

     *Note*:

     In NDB API applications, you can control 'BLOB' write
     batching with the 'setMaxPendingBlobWriteBytes()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-setmaxpendingblobwritebytes.html)
     and 'getMaxPendingBlobWriteBytes()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-getmaxpendingblobwritebytes.html)
     methods.

   *
     '--ndb-connectstring=CONNECTION_STRING'

     * Type and value information for ndb-connectstring*

     Property                  Value

     Name                      'ndb-connectstring'

     Command Line              Yes

     System Variable           No

     Status Variable           No

     Option File               Yes

     Scope

     Dynamic                   No

     Type

     Default, Range            (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Point to the management server
                               that distributes the cluster configuration

     When using the 'NDBCLUSTER' storage engine,
     this option specifies the management server that distributes
     cluster configuration data.  See
     mysql-cluster-connection-strings, for syntax.

   *
     '--ndb-default-column-format=[FIXED|DYNAMIC]'

     * Type and value information for ndb-default-column-format*

     Property                  Value

     Name                      'ndb-default-column-format'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            DYNAMIC / FIXED, DYNAMIC (Version:
                               5.7.11-ndb-7.5.1)

     Default, Range            FIXED / FIXED, DYNAMIC (Version:
                               5.7.16-ndb-7.5.4)

     Notes
                               DESCRIPTION: Use this value (FIXED or
                               DYNAMIC) by default for COLUMN_FORMAT and
                               ROW_FORMAT options when creating or adding
                               columns to a table.

     In NDB 7.5.1 and later, sets the default 'COLUMN_FORMAT' and
     'ROW_FORMAT' for new tables (see create-table).

     In NDB 7.5.1, the default for this option was 'DYNAMIC'; in NDB
     7.5.4, the default was changed to 'FIXED' to maintain backwards
     compatibility with older release series (Bug #24487363).

   *
     '--ndb-deferred-constraints=[0|1]'

     * Type and value information for ndb-deferred-constraints*

     Property                  Value

     Name                      'ndb-deferred-constraints'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            0 / 0 - 1 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Specifies that constraint checks
                               on unique indexes (where these are supported)
                               should be deferred until commit time.  Not
                               normally needed or used; for testing purposes
                               only.

     Controls whether or not constraint checks on unique indexes are
     deferred until commit time, where such checks are supported.  '0'
     is the default.

     This option is not normally needed for operation of NDB Cluster or
     NDB Cluster Replication, and is intended primarily for use in
     testing.

   *
     '--ndb-distribution=[KEYHASH|LINHASH]'

     * Type and value information for ndb-distribution*

     Property                  Value

     Name                      'ndb-distribution'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            KEYHASH / LINHASH, KEYHASH (Version: NDB
                               7.5-7.6)

     Notes
                               DESCRIPTION: Default distribution for new
                               tables in NDBCLUSTER (KEYHASH or LINHASH,
                               default is KEYHASH)

     Controls the default distribution method for 'NDB'
     tables.  Can be set to either of 'KEYHASH' (key
     hashing) or 'LINHASH' (linear hashing).  'KEYHASH' is the default.

   *
     '--ndb-log-apply-status'

     * Type and value information for ndb-log-apply-status*

     Property                  Value

     Name                      'ndb-log-apply-status'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Cause a MySQL server acting as a
                               slave to log mysql.ndb_apply_status updates
                               received from its immediate master in its own
                               binary log, using its own server ID.
                               Effective only if the server is started with
                               the -ndbcluster option.

     Causes a slave 'mysqld' to log any updates received
     from its immediate master to the 'mysql.ndb_apply_status' table in
     its own binary log using its own server ID rather than the server
     ID of the master.  In a circular or chain replication setting, this
     allows such updates to propagate to the 'mysql.ndb_apply_status'
     tables of any MySQL servers configured as slaves of the current
     'mysqld'.

     In a chain replication setup, using this option allows downstream
     (slave) clusters to be aware of their positions relative to all of
     their upstream contributors (masters).

     In a circular replication setup, this option causes changes to
     'ndb_apply_status' tables to complete the entire circuit,
     eventually propagating back to the originating NDB Cluster.  This
     also allows a cluster acting as a master to see when its changes
     (epochs) have been applied to the other clusters in the circle.

     This option has no effect unless the MySQL server is started with
     the '--ndbcluster' option.

   *
     '--ndb-log-empty-epochs=[ON|OFF]'

     * Type and value information for ndb-log-empty-epochs*

     Property                  Value

     Name                      'ndb-log-empty-epochs'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: When enabled, causes epochs in
                               which there were no changes to be written to
                               the ndb_apply_status and ndb_binlog_index
                               tables, even when -log-slave-updates is
                               enabled.

     Causes epochs during which there were no changes to be written to
     the 'ndb_apply_status' and 'ndb_binlog_index' tables, even when
     '--log-slave-updates' is enabled.

     By default this option is disabled.  Disabling
     '--ndb-log-empty-epochs' causes epoch transactions with no changes
     not to be written to the binary log, although a row is still
     written even for an empty epoch in 'ndb_binlog_index'.

     Because '--ndb-log-empty-epochs=1' causes the size of the
     'ndb_binlog_index' table to increase independently of the size of
     the binary log, users should be prepared to manage the growth of
     this table, even if they expect the cluster to be idle a large part
     of the time.

   *
     '--ndb-log-empty-update=[ON|OFF]'

     * Type and value information for ndb-log-empty-update*

     Property                  Value

     Name                      'ndb-log-empty-update'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: When enabled, causes updates
                               that produced no changes to be written to the
                               ndb_apply_status and ndb_binlog_index tables,
                               even when -log-slave-updates is enabled.

     Causes updates that produced no changes to be written to the
     'ndb_apply_status' and 'ndb_binlog_index' tables, even when
     '--log-slave-updates' is enabled.

     By default this option is disabled ('OFF').  Disabling
     '--ndb-log-empty-update' causes updates with no changes not to be
     written to the binary log.

   *
     '--ndb-log-exclusive-reads=[0|1]'

     * Type and value information for ndb-log-exclusive-reads*

     Property                  Value

     Name                      'ndb-log-exclusive-reads'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            0 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Log primary key reads with
                               exclusive locks; allow conflict resolution
                               based on read conflicts

     Starting the server with this option causes primary key reads to be
     logged with exclusive locks, which allows for NDB Cluster
     Replication conflict detection and resolution based on read
     conflicts.  You can also enable and disable these locks at runtime
     by setting the value of the 'ndb_log_exclusive_reads' system
     variable to 1 or 0, respectively.  0 (disable locking) is the
     default.

     For more information, see
     mysql-cluster-replication-examples-read-conflicts.

   *
     '--ndb-log-orig'

     * Type and value information for ndb-log-orig*

     Property                  Value

     Name                      'ndb-log-orig'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Log originating server id and
                               epoch in mysql.ndb_binlog_index table

     Log the originating server ID and epoch in the 'ndb_binlog_index'
     table.

     *Note*:

     This makes it possible for a given epoch to have multiple rows in
     'ndb_binlog_index', one for each originating epoch.

     For more information, see mysql-cluster-replication-schema.

   *
     '--ndb-log-transaction-id'

     * Type and value information for ndb-log-transaction-id*

     Property                  Value

     Name                      'ndb-log-transaction-id'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Write NDB transaction IDs in the
                               binary log.  Requires -log-bin-v1-events=OFF.

     Causes a slave 'mysqld' to write the NDB transaction
     ID in each row of the binary log.  Such logging requires the use of
     the Version 2 event format for the binary log; thus,
     '--log-bin-use-v1-row-events' must be set to 'FALSE' in order to
     use this option.

     This option is not supported in mainline MySQL Server 5.7.  It is
     required to enable NDB Cluster Replication conflict detection and
     resolution using the 'NDB$EPOCH_TRANS()' function (see
     mysql-cluster-replication-ndb-epoch-trans).

     The default value is 'FALSE'.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   *
     '--ndb-log-update-minimal'

     * Type and value information for ndb-log-update-minimal*

     Property                  Value

     Name                      'ndb-log-update-minimal'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: 5.6.36-ndb-7.4.16)

     Default, Range            OFF (Version: 5.7.18-ndb-7.5.7)

     Default, Range            OFF (Version: 5.7.18-ndb-7.6.3)

     Notes
                               DESCRIPTION: Log updates in a minimal format.

     Log updates in a minimal fashion, by writing only the primary key
     values in the before image, and only the changed columns in the
     after image.  This may cause compatibility problems if replicating
     to storage engines other than 'NDB'.

   *
     '--ndb-mgmd-host=HOST[:PORT]'

     * Type and value information for ndb-mgmd-host*

     Property                  Value

     Name                      'ndb-mgmd-host'

     Command Line              Yes

     System Variable           No

     Status Variable           No

     Option File               Yes

     Scope

     Dynamic                   No

     Type

     Default, Range            localhost:1186 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Set the host (and port, if
                               desired) for connecting to management server

     Can be used to set the host and port number of a single management
     server for the program to connect to.  If the program requires node
     IDs or references to multiple management servers (or both) in its
     connection information, use the '--ndb-connectstring' option
     instead.

   *
     '--ndb-nodeid=#'

     * Type and value information for ndb-nodeid*

     Property                  Value

     Name                      'ndb-nodeid'

     Command Line              Yes

     System Variable           No

     Status Variable           Yes

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            / 1 - 63 (Version: 5.0.45)

     Default, Range            / 1 - 255 (Version: 5.1.5)

     Notes
                               DESCRIPTION: NDB Cluster node ID for this
                               MySQL server

     Set this MySQL server's node ID in an NDB Cluster.

     The '--ndb-nodeid' option overrides any node ID set with
     '--ndb-connectstring', regardless of the order in which the two
     options are used.

     In addition, if '--ndb-nodeid' is used, then either a matching node
     ID must be found in a '[mysqld]' or '[api]' section of
     'config.ini', or there must be an 'open' '[mysqld]' or '[api]'
     section in the file (that is, a section without a 'NodeId' or 'Id'
     parameter specified).  This is also true if the node ID is
     specified as part of the connection string.

     Regardless of how the node ID is determined, its is shown as the
     value of the global status variable 'Ndb_cluster_node_id' in the
     output of 'SHOW STATUS', and as
     'cluster_node_id' in the 'connection' row of the output of
     'SHOW ENGINE NDBCLUSTER STATUS'.

     For more information about node IDs for NDB Cluster SQL nodes, see
     mysql-cluster-api-definition.

   * '--ndb_optimization_delay=MILLISECONDS'

     * Type and value information for ndb_optimization_delay*

     Property                  Value

     Name                      'ndb_optimization_delay'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            10 / 0 - 100000 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Sets the number of milliseconds
                               to wait between processing sets of rows by
                               OPTIMIZE TABLE on NDB tables

     Set the number of milliseconds to wait between sets of rows by
     'OPTIMIZE TABLE' statements on 'NDB'
     tables.  The default is 10.

   * '--ndb-recv-thread-activation-threshold=THRESHOLD'

     * Type and value information for
     ndb-recv-thread-activation-threshold*

     Property                  Value

     Name                      'ndb-recv-thread-activation-threshold'

     Command Line              Yes

     System Variable           No

     Status Variable           No

     Option File               Yes

     Scope

     Dynamic                   No

     Type

     Default, Range            8 / 0 (MIN_ACTIVATION_THRESHOLD) - 16
                               (MAX_ACTIVATION_THRESHOLD) (Version:
                               5.6.10-ndb-7.3.1)

     Notes
                               DESCRIPTION: Activation threshold when
                               receive thread takes over the polling of the
                               cluster connection (measured in concurrently
                               active threads)

     When this number of concurrently active threads is reached, the
     receive thread takes over polling of the cluster connection.

   * '--ndb-recv-thread-cpu-mask=BITMASK'

     * Type and value information for ndb-recv-thread-cpu-mask*

     Property                  Value

     Name                      'ndb-recv-thread-cpu-mask'

     Command Line              Yes

     System Variable           No

     Status Variable           No

     Option File               Yes

     Scope

     Dynamic                   No

     Type

     Default, Range            [empty] (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: CPU mask for locking receiver
                               threads to specific CPUs; specified as
                               hexadecimal.  See documentation for details.

     Set a CPU mask for locking receiver threads to specific CPUs.  This
     is specified as a hexadecimal bitmask; for example, '0x33' means
     that one CPU is used per receiver thread.  An empty string (no
     locking of receiver threads) is the default.

   * 'ndb-transid-mysql-connection-map=STATE'

     * Type and value information for ndb-transid-mysql-connection-map*

     Property                  Value

     Name                      'ndb-transid-mysql-connection-map'

     Command Line              Yes

     System Variable           No

     Status Variable           No

     Option File               No

     Scope

     Dynamic                   No

     Type

     Default, Range            ON / ON, OFF, FORCE (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Enable or disable the
                               ndb_transid_mysql_connection_map plugin; that
                               is, enable or disable the INFORMATION_SCHEMA
                               table having that name

     Enables or disables the plugin that handles the
     'ndb_transid_mysql_connection_map'
     table in the
     'INFORMATION_SCHEMA' database.  Takes one of the values 'ON',
     'OFF', or 'FORCE'.  'ON' (the default) enables the plugin.  'OFF'
     disables the plugin, which makes 'ndb_transid_mysql_connection_map'
     inaccessible.  'FORCE' keeps the MySQL Server from starting if the
     plugin fails to load and start.

     You can see whether the 'ndb_transid_mysql_connection_map'
     table plugin is running by
     checking the output of 'SHOW PLUGINS'.

   * '--ndb-wait-connected=SECONDS'

     * Type and value information for ndb-wait-connected*

     Property                  Value

     Name                      'ndb-wait-connected'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            0 / 0 - 31536000 (Version: NDB 7.5-7.6)

     Default, Range            30 / 0 - 31536000 (Version:
                               5.1.56-ndb-7.0.27)

     Default, Range            0 / 0 - 31536000 (Version: NDB 7.5-7.6)

     Default, Range            30 / 0 - 31536000 (Version:
                               5.1.56-ndb-7.1.16)

     Notes
                               DESCRIPTION: Time (in seconds) for the MySQL
                               server to wait for connection to cluster
                               management and data nodes before accepting
                               MySQL client connections

     This option sets the period of time that the MySQL server waits for
     connections to NDB Cluster management and data nodes to be
     established before accepting MySQL client connections.  The time is
     specified in seconds.  The default value is '30'.

   * '--ndb-wait-setup=SECONDS'

     * Type and value information for ndb-wait-setup*

     Property                  Value

     Name                      'ndb-wait-setup'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            15 / 0 - 31536000 (Version:
                               5.1.39-ndb-6.2.19)

     Default, Range            15 / 0 - 31536000 (Version:
                               5.1.39-ndb-6.3.28)

     Default, Range            15 / 0 - 31536000 (Version: 5.1.39-ndb-7.0.9)

     Default, Range            30 / 0 - 31536000 (Version:
                               5.1.56-ndb-7.0.27)

     Default, Range            15 / 0 - 31536000 (Version: 5.1.39-ndb-7.1.0)

     Default, Range            30 / 0 - 31536000 (Version:
                               5.1.56-ndb-7.1.16)

     Notes
                               DESCRIPTION: Time (in seconds) for the MySQL
                               server to wait for NDB engine setup to
                               complete

     This variable shows the period of time that the MySQL server waits
     for the 'NDB' storage engine to complete
     setup before timing out and treating 'NDB' as
     unavailable.  The time is specified in seconds.  The default value
     is '30'.

   *
     '--server-id-bits=#'

     * Type and value information for server-id-bits*

     Property                  Value

     Name                      'server-id-bits'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            32 / 7 - 32 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Sets the number of least
                               significant bits in the server_id actually
                               used for identifying the server, permitting
                               NDB API applications to store application
                               data in the most significant bits.  server_id
                               must be less than 2 to the power of this
                               value.

     This option indicates the number of least significant bits within
     the 32-bit 'server_id' which actually identify the server.
     Indicating that the server is actually identified by fewer than 32
     bits makes it possible for some of the remaining bits to be used
     for other purposes, such as storing user data generated by
     applications using the NDB API's Event API within the 'AnyValue' of
     an 'OperationOptions'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-operationoptions.html)
     structure (NDB Cluster uses the 'AnyValue' to store the server ID).

     When extracting the effective server ID from 'server_id' for
     purposes such as detection of replication loops, the server ignores
     the remaining bits.  The '--server-id-bits' option is used to mask
     out any irrelevant bits of 'server_id' in the IO and SQL threads
     when deciding whether an event should be ignored based on the
     server ID.

     This data can be read from the binary log by 'mysqlbinlog',
     provided that it is run with its own
     '--server-id-bits' option set to 32 (the default).

     The value of 'server_id' must be less than 2 ^ 'server_id_bits';
     otherwise, see 'mysqld' refuses to start.

     This system variable is supported only by NDB Cluster.  It is not
     supported in the standard MySQL 5.7 Server.

   *
     '--skip-ndbcluster'

     * Type and value information for skip-ndbcluster*

     Property                  Value

     Name                      'skip-ndbcluster'

     Command Line              Yes

     System Variable           No

     Status Variable           No

     Option File               Yes

     Scope

     Dynamic                   No

     Type

     Notes                     DESCRIPTION: Disable the NDB Cluster storage
                               engine

     Disable the 'NDBCLUSTER' storage engine.
     This is the default for binaries that were built with
     'NDBCLUSTER' storage engine support; the server
     allocates memory and other resources for this storage engine only
     if the '--ndbcluster' option is given explicitly.  See
     mysql-cluster-quick, for an example.

21.3.3.11 NDB Cluster System Variables
......................................

This section provides detailed information about MySQL server system
variables that are specific to NDB Cluster and the 'NDB'
storage engine.  For system variables not specific to NDB
Cluster, see server-system-variables.  For general information
on using system variables, see using-system-variables.

   * 'ndb_autoincrement_prefetch_sz'

     * Type and value information for ndb_autoincrement_prefetch_sz*

     Property                  Value

     Name                      'ndb_autoincrement_prefetch_sz'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            32 / 1 - 256 (Version: NDB 7.5-7.6)

     Default, Range            1 / 1 - 256 (Version: 5.0.56)

     Default, Range            32 / 1 - 256 (Version: 5.1.1)

     Default, Range            1 / 1 - 256 (Version: 5.1.23)

     Default, Range            32 / 1 - 256 (Version: 5.1.16-ndb-6.2.0)

     Default, Range            1 / 1 - 256 (Version: 5.1.23-ndb-6.2.10)

     Default, Range            32 / 1 - 256 (Version: 5.1.19-ndb-6.3.0)

     Default, Range            1 / 1 - 256 (Version: 5.1.23-ndb-6.3.7)

     Default, Range            1 / 1 - 65536 (Version: 5.1.41-ndb-6.3.31)

     Default, Range            32 / 1 - 256 (Version: 5.1.30-ndb-6.4.0)

     Default, Range            1 / 1 - 65536 (Version: 5.1.41-ndb-7.0.11)

     Default, Range            1 / 1 - 65536 (Version: 5.5.15-ndb-7.2.1)

     Notes
                               DESCRIPTION: NDB auto-increment prefetch size

     Determines the probability of gaps in an autoincremented column.
     Set it to '1' to minimize this.  Setting it to a high value for
     optimization makes inserts faster, but decreases the likelihood
     that consecutive autoincrement numbers will be used in a batch of
     inserts.  The mininum and default value is 1.  The maximum value
     for 'ndb_autoincrement_prefetch_sz' is 65536.

     This variable affects only the number of 'AUTO_INCREMENT' IDs that
     are fetched between statements; within a given statement, at least
     32 IDs are obtained at a time.  The default value is 1.

     *Important*:

     This variable does not affect inserts performed using 'INSERT ... SELECT'.

   * 'ndb_cache_check_time'

     * Type and value information for ndb_cache_check_time*

     Property                  Value

     Name                      'ndb_cache_check_time'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            0 / - (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Number of milliseconds between
                               checks of cluster SQL nodes made by the MySQL
                               query cache

     The number of milliseconds that elapse between checks of NDB
     Cluster SQL nodes by the MySQL query cache.  Setting this to 0 (the
     default and minimum value) means that the query cache checks for
     validation on every query.

     The recommended maximum value for this variable is 1000, which
     means that the check is performed once per second.  A larger value
     means that the check is performed and possibly invalidated due to
     updates on different SQL nodes less often.  It is generally not
     desirable to set this to a value greater than 2000.

     *Note*:

     The query cache is deprecated as of MySQL 5.7.20, and is removed in
     MySQL 8.0.  Deprecation includes 'ndb_cache_check_time'.

   * 'ndb_clear_apply_status'

     * Type and value information for ndb_clear_apply_status*

     Property                  Value

     Name                      'ndb_clear_apply_status'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            ON (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Causes RESET SLAVE to clear all
                               rows from the ndb_apply_status table; ON by
                               default

     By the default, executing 'RESET SLAVE' causes
     an NDB Cluster replication slave to purge all rows from its
     'ndb_apply_status' table.  You can disable this by setting
     'ndb_clear_apply_status=OFF'.

   * 'ndb_data_node_neighbour'

     * Type and value information for ndb_data_node_neighbour*

     Property                  Value

     Name                      'ndb_data_node_neighbour'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            0 / 0 - 255 (Version: 5.7.12-ndb-7.5.2)

     Notes
                               DESCRIPTION: Specifies cluster data node
                               "closest" to this MySQL Server, for
                               transaction hinting and fully replicated
                               tables

     Sets the ID of a 'nearest' data node--that is, a preferred nonlocal
     data node is chosen to execute the transaction, rather than one
     running on the same host as the SQL or API node.  This used to
     ensure that when a fully replicated table is accessed, we access it
     on this data node, to ensure that the local copy of the table is
     always used whenever possible.  This can also be used for providing
     hints for transactions.

     This can improve data access times in the case of a node that is
     physically closer than and thus has higher network throughput than
     others on the same host.

     See create-table-ndb-table-comment-options, for further
     information.

     Added in NDB 7.5.2.

     *Note*:

     An equivalent method 'set_data_node_neighbour()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-set-data-node-neighbour.html)
     is provided for use in NDB API applications.

   * 'ndb_default_column_format'

     * Type and value information for ndb_default_column_format*

     Property                  Value

     Name                      'ndb_default_column_format'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            DYNAMIC / FIXED, DYNAMIC (Version:
                               5.7.11-ndb-7.5.1)

     Default, Range            FIXED / FIXED, DYNAMIC (Version:
                               5.7.16-ndb-7.5.4)

     Notes
                               DESCRIPTION: Sets default row format and
                               column format (FIXED or DYNAMIC) used for new
                               NDB tables

     In NDB 7.5.1 and later, sets the default 'COLUMN_FORMAT' and
     'ROW_FORMAT' for new tables (see create-table).

     In NDB 7.5.1, the default for this variable was 'DYNAMIC'; in NDB
     7.5.4, the default was changed to 'FIXED' to maintain backwards
     compatibility with older release series (Bug #24487363).

   * 'ndb_deferred_constraints'

     * Type and value information for ndb_deferred_constraints*

     Property                  Value

     Name                      'ndb_deferred_constraints'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            0 / 0 - 1 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Specifies that constraint checks
                               should be deferred (where these are
                               supported).  Not normally needed or used; for
                               testing purposes only.

     Controls whether or not constraint checks are deferred, where these
     are supported.  '0' is the default.

     This variable is not normally needed for operation of NDB Cluster
     or NDB Cluster Replication, and is intended primarily for use in
     testing.

   * 'ndb_distribution'

     * Type and value information for ndb_distribution*

     Property                  Value

     Name                      'ndb_distribution'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            KEYHASH / LINHASH, KEYHASH (Version: NDB
                               7.5-7.6)

     Notes
                               DESCRIPTION: Default distribution for new
                               tables in NDBCLUSTER (KEYHASH or LINHASH,
                               default is KEYHASH)

     Controls the default distribution method for 'NDB'
     tables.  Can be set to either of 'KEYHASH' (key
     hashing) or 'LINHASH' (linear hashing).  'KEYHASH' is the default.

   * 'ndb_eventbuffer_free_percent'

     * Type and value information for ndb_eventbuffer_free_percent*

     Property                  Value

     Name                      'ndb_eventbuffer_free_percent'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            20 / 1 - 99 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Percentage of free memory that
                               should be available in event buffer before
                               resumption of buffering, after reaching limit
                               set by ndb_eventbuffer_max_alloc

     Sets the percentage of the maximum memory allocated to the event
     buffer (ndb_eventbuffer_max_alloc) that should be available in
     event buffer after reaching the maximum, before starting to buffer
     again.

   * 'ndb_eventbuffer_max_alloc'

     * Type and value information for ndb_eventbuffer_max_alloc*

     Property                  Value

     Name                      'ndb_eventbuffer_max_alloc'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            0 / 0 - 4294967295 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Maximum memory that can be
                               allocated for buffering events by the NDB
                               API. Defaults to 0 (no limit).

     Sets the maximum amount memory (in bytes) that can be allocated for
     buffering events by the NDB API. 0 means that no limit is imposed,
     and is the default.

   * 'ndb_extra_logging'

     * Type and value information for ndb_extra_logging*

     Property                  Value

     Name                      'ndb_extra_logging'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            0 / - (Version: NDB 7.5-7.6)

     Default, Range            1 / - (Version: 5.1.19-ndb-6.3.0)

     Notes
                               DESCRIPTION: Controls logging of NDB Cluster
                               schema, connection, and data distribution
                               events in the MySQL error log

     This variable enables recording in the MySQL error log of
     information specific to the 'NDB' storage
     engine.

     When this variable is set to 0, the only information specific to
     'NDB' that is written to the MySQL error log relates to transaction
     handling.  If it set to a value greater than 0 but less than 10,
     'NDB' table schema and connection events are also logged, as well
     as whether or not conflict resolution is in use, and other 'NDB'
     errors and information.  If the value is set to 10 or more,
     information about 'NDB' internals, such as the progress of data
     distribution among cluster nodes, is also written to the MySQL
     error log.  The default is 1.

   * 'ndb_force_send'

     * Type and value information for ndb_force_send*

     Property                  Value

     Name                      'ndb_force_send'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            TRUE (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Forces sending of buffers to NDB
                               immediately, without waiting for other
                               threads

     Forces sending of buffers to 'NDB'.
     immediately, without waiting for other threads.  Defaults to 'ON'.

   * 'ndb_fully_replicated'

     * Type and value information for ndb_fully_replicated*

     Property                  Value

     Name                      'ndb_fully_replicated'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: 5.7.12-ndb-7-5-2)

     Notes
                               DESCRIPTION: Whether new NDB tables are fully
                               replicated

     Determines whether new 'NDB' tables are fully replicated.  This
     setting can be overridden for an individual table using
     'COMMENT="NDB_TABLE=FULLY_REPLICATED=..."' in a 'CREATE TABLE'
     or 'ALTER TABLE'.
     statement; see create-table-ndb-table-comment-options, for
     syntax and other information.

     Added in NDB 7.5.2.

   * 'ndb_index_stat_enable'

     * Type and value information for ndb_index_stat_enable*

     Property                  Value

     Name                      'ndb_index_stat_enable'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Default, Range            ON (Version: 5.5.15-ndb-7.2.1)

     Notes
                               DESCRIPTION: Use NDB index statistics in
                               query optimization

     Use 'NDB' index statistics in query
     optimization.  The default is 'ON'.

   * 'ndb_index_stat_option'

     * Type and value information for ndb_index_stat_option*

     Property                  Value

     Name                      'ndb_index_stat_option'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            loop_enable=1000ms,loop_idle=1000ms,loop_busy=100ms,
                               update_batch=1,read_batch=4,idle_batch=32,check_batch=8,
                               check_delay=10m,delete_batch=8,
                               clean_delay=1m,error_batch=4,
                               error_delay=1m,evict_batch=8,evict_delay=1m,cache_limit=32M,
                               cache_lowpct=90,zero_total=0 (Version: NDB
                               7.5-7.6)

     Default, Range            loop_checkon=1000ms,loop_idle=1000ms,loop_busy=100ms,
                               update_batch=1,read_batch=4,idle_batch=32,check_batch=32,
                               check_delay=1m,delete_batch=8,clean_delay=0,error_batch=4,
                               error_delay=1m,evict_batch=8,evict_delay=1m,cache_limit=32M,
                               cache_lowpct=90 (Version: 5.1.56-ndb-7.1.17)

     Notes
                               DESCRIPTION: Comma-separated list of tunable
                               options for NDB index statistics; the list
                               should contain no spaces

     This variable is used for providing tuning options for NDB index
     statistics generation.  The list consist of comma-separated
     name-value pairs of option names and values, and this list must not
     contain any space characters.

     Options not used when setting 'ndb_index_stat_option' are not
     changed from their default values.  For example, you can set
     'ndb_index_stat_option = 'loop_idle=1000ms,cache_limit=32M''.

     Time values can be optionally suffixed with 'h' (hours), 'm'
     (minutes), or 's' (seconds).  Millisecond values can optionally be
     specified using 'ms'; millisecond values cannot be specified using
     'h', 'm', or 's'.)  Integer values can be suffixed with 'K', 'M',
     or 'G'.

     The names of the options that can be set using this variable are
     shown in the table that follows.  The table also provides brief
     descriptions of the options, their default values, and (where
     applicable) their minimum and maximum values.

     *ndb_index_stat_option options and values*

     Name               Description        Default/Units      Minimum/Maximum

     'loop_enable'                         1000 ms            0/4G

     'loop_idle'        Time to sleep      1000 ms            0/4G
                        when idle

     'loop_busy'        Time to sleep      100 ms             0/4G
                        when more work
                        is waiting

     'update_batch'                        1                  0/4G

     'read_batch'                          4                  1/4G

     'idle_batch'                          32                 1/4G

     'check_batch'                         8                  1/4G

     'check_delay'      How often to       10 m               1/4G
                        check for new
                        statistics

     'delete_batch'                        8                  0/4G

     'clean_delay'                         1 m                0/4G

     'error_batch'                         4                  1/4G

     'error_delay'                         1 m                1/4G

     'evict_batch'                         8                  1/4G

     'evict_delay'      Clean LRU cache,   1 m                0/4G
                        from read time

     'cache_limit'      Maximum amount     32 M               0/4G
                        of memory in
                        bytes used for
                        cached index
                        statistics by
                        this
                        'mysqld'.;
                        clean
                        up the cache
                        when this is
                        exceeded.

     'cache_lowpct'                        90                 0/100

     'zero_total'       Setting this to    0                  0/1
                        1 resets all
                        accumulating
                        counters in
                        'ndb_index_stat_status'
                        to 0.  This
                        option value is
                        also reset to 0
                        when this is
                        done.

   * 'ndb_join_pushdown'

     * Type and value information for ndb_join_pushdown*

     Property                  Value

     Name                      'ndb_join_pushdown'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            TRUE (Version: 5.1.51-ndb-7.2.0)

     Notes
                               DESCRIPTION: Enables pushing down of joins to
                               data nodes

     This variable controls whether joins on 'NDB'.
     tables are pushed down to the NDB kernel (data nodes).  Previously,
     a join was handled using multiple accesses of 'NDB'
     by the SQL node; however, when 'ndb_join_pushdown'
     is enabled, a pushable join is sent in its entirety to the data
     nodes, where it can be distributed among the data nodes and
     executed in parallel on multiple copies of the data, with a single,
     merged result being returned to 'mysqld'.  This can
     reduce greatly the number of round trips between an SQL node and
     the data nodes required to handle such a join.

     By default, 'ndb_join_pushdown' is enabled.

     Conditions for NDB pushdown joins

     In order for a join to be pushable, it must meet the following
     conditions:

       1. Only columns can be compared, and all columns to be joined
          must use _exactly_ the same data type.

          This means that expressions such as 't1.a = t2.a + CONSTANT'
          cannot be pushed down, and that (for example) a join on an
          'INT' column and a 'BIGINT'
          column also cannot be pushed down.

       2. Queries referencing 'BLOB' or 'TEXT'.
          columns are not supported.

       3. Explicit locking is not supported; however, the 'NDB'
          storage engine's characteristic implicit
          row-based locking is enforced.

          This means that a join using 'FOR UPDATE' cannot be pushed
          down.

       4. In order for a join to be pushed down, child tables in the
          join must be accessed using one of the 'ref', 'eq_ref', or
          'const' access methods, or some combination of these methods.

          Outer joined child tables can only be pushed using 'eq_ref'.

          If the root of the pushed join is an 'eq_ref' or 'const', only
          child tables joined by 'eq_ref' can be appended.  (A table
          joined by 'ref' is likely to become the root of another pushed
          join.)

          If the query optimizer decides on 'Using join cache' for a
          candidate child table, that table cannot be pushed as a child.
          However, it may be the root of another set of pushed tables.

       5. Joins referencing tables explicitly partitioned by '[LINEAR]
          HASH', 'LIST', or 'RANGE' currently cannot be pushed down.

     You can see whether a given join can be pushed down by checking it
     with 'EXPLAIN'.; when the join can be pushed down,
     you can see references to the 'pushed join' in the 'Extra' column
     of the output, as shown in this example:

          mysql> EXPLAIN
              ->     SELECT e.first_name, e.last_name, t.title, d.dept_name
              ->         FROM employees e
              ->         JOIN dept_emp de ON e.emp_no=de.emp_no
              ->         JOIN departments d ON d.dept_no=de.dept_no
              ->         JOIN titles t ON e.emp_no=t.emp_no\G
          *************************** 1. row ***************************
                     id: 1
            select_type: SIMPLE
                  table: d
                   type: ALL
          possible_keys: PRIMARY
                    key: NULL
                key_len: NULL
                    ref: NULL
                   rows: 9
                  Extra: Parent of 4 pushed join@1
          *************************** 2. row ***************************
                     id: 1
            select_type: SIMPLE
                  table: de
                   type: ref
          possible_keys: PRIMARY,emp_no,dept_no
                    key: dept_no
                key_len: 4
                    ref: employees.d.dept_no
                   rows: 5305
                  Extra: Child of 'd' in pushed join@1
          *************************** 3. row ***************************
                     id: 1
            select_type: SIMPLE
                  table: e
                   type: eq_ref
          possible_keys: PRIMARY
                    key: PRIMARY
                key_len: 4
                    ref: employees.de.emp_no
                   rows: 1
                  Extra: Child of 'de' in pushed join@1
          *************************** 4. row ***************************
                     id: 1
            select_type: SIMPLE
                  table: t
                   type: ref
          possible_keys: PRIMARY,emp_no
                    key: emp_no
                key_len: 4
                    ref: employees.de.emp_no
                   rows: 19
                  Extra: Child of 'e' in pushed join@1
          4 rows in set (0.00 sec)

     *Note*:

     If inner joined child tables are joined by 'ref', _and_ the result
     is ordered or grouped by a sorted index, this index cannot provide
     sorted rows, which forces writing to a sorted tempfile.

     Two additional sources of information about pushed join performance
     are available:

       1. The status variables 'Ndb_pushed_queries_defined',
          'Ndb_pushed_queries_dropped', 'Ndb_pushed_queries_executed',
          and 'Ndb_pushed_reads'.

       2. The counters in the 'ndbinfo.counters'
          table that belong to the
          'DBSPJ' kernel block.  See
          mysql-cluster-ndbinfo-counters, for information about these
          counters.  See also The DBSPJ Block
          (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks-dbspj.html),
          in the 'NDB Cluster API Developer Guide'.

   * 'ndb_log_apply_status'

     * Type and value information for ndb_log_apply_status*

     Property                  Value

     Name                      'ndb_log_apply_status'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Whether or not a MySQL server
                               acting as a slave logs mysql.ndb_apply_status
                               updates received from its immediate master in
                               its own binary log, using its own server ID

     A read-only variable which shows whether the server was started
     with the '--ndb-log-apply-status' option.

   * 'ndb_log_bin'

     * Type and value information for ndb_log_bin*

     Property                  Value

     Name                      'ndb_log_bin'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            ON (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Write updates to NDB tables in
                               the binary log.  Effective only if binary
                               logging is enabled with -log-bin.

     Causes updates to 'NDB' tables to be written to the binary log.
     Setting this variable has no effect if binary logging is not
     already enabled for the server using 'log_bin'.  'ndb_log_bin'
     defaults to 1 (ON); normally, there is never any need to change
     this value in a production environment.

   * 'ndb_log_binlog_index'

     * Type and value information for ndb_log_binlog_index*

     Property                  Value

     Name                      'ndb_log_binlog_index'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            ON (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Insert mapping between epochs
                               and binary log positions into the
                               ndb_binlog_index table.  Defaults to ON.
                               Effective only if binary logging is enabled
                               on the server.

     Causes a mapping of epochs to positions in the binary log to be
     inserted into the 'ndb_binlog_index' table.  Setting this variable
     has no effect if binary logging is not already enabled for the
     server using 'log_bin'.  (In addition, 'ndb_log_bin' must not be
     disabled.)  'ndb_log_binlog_index' defaults to '1' ('ON');
     normally, there is never any need to change this value in a
     production environment.

   *
     'ndb_log_empty_epochs'

     * Type and value information for ndb_log_empty_epochs*

     Property                  Value

     Name                      'ndb_log_empty_epochs'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: When enabled, epochs in which
                               there were no changes are written to the
                               ndb_apply_status and ndb_binlog_index tables,
                               even when log_slave_updates is enabled

     When this variable is set to 0, epoch transactions with no changes
     are not written to the binary log, although a row is still written
     even for an empty epoch in 'ndb_binlog_index'.

   *
     'ndb_log_empty_update'

     * Type and value information for ndb_log_empty_update*

     Property                  Value

     Name                      'ndb_log_empty_update'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: When enabled, updates which
                               produce no changes are written to the
                               ndb_apply_status and ndb_binlog_index tables,
                               even when log_slave_updates is enabled

     When this variable is set to 'ON' ('1'), update transactions with
     no changes are written to the binary log, even when
     '--log-slave-updates' is enabled.

   *
     'ndb_log_exclusive_reads'

     * Type and value information for ndb_log_exclusive_reads*

     Property                  Value

     Name                      'ndb_log_exclusive_reads'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            0 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Log primary key reads with
                               exclusive locks; allow conflict resolution
                               based on read conflicts

     This variable determines whether primary key reads are logged with
     exclusive locks, which allows for NDB Cluster Replication conflict
     detection and resolution based on read conflicts.  To enable these
     locks, set the value of 'ndb_log_exclusive_reads' to 1.  0, which
     disables such locking, is the default.

     For more information, see
     mysql-cluster-replication-examples-read-conflicts.

   *
     'ndb_log_orig'

     * Type and value information for ndb_log_orig*

     Property                  Value

     Name                      'ndb_log_orig'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Whether the id and epoch of the
                               originating server are recorded in the
                               mysql.ndb_binlog_index table.  Set using the
                               -ndb-log-orig option when starting mysqld.

     Shows whether the originating server ID and epoch are logged in the
     'ndb_binlog_index' table.  Set using the '--ndb-log-orig' server
     option.

   *
     'ndb_log_transaction_id'

     * Type and value information for ndb_log_transaction_id*

     Property                  Value

     Name                      'ndb_log_transaction_id'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Whether NDB transaction IDs are
                               written into the binary log (Read-only.)

     This read-only, Boolean system variable shows whether a slave
     'mysqld' writes NDB transaction IDs in the binary log
     (required to use 'active-active' NDB Cluster Replication with
     'NDB$EPOCH_TRANS()' conflict detection).  To change the setting,
     use the '--ndb-log-transaction-id' option.

     'ndb_log_transaction_id' is not supported in mainline MySQL Server
     5.7.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'ndb_optimized_node_selection'

     * Type and value information for ndb_optimized_node_selection*

     Property                  Value

     Name                      'ndb_optimized_node_selection'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            ON (Version: NDB 7.5-7.6)

     Default, Range            3 / 0 - 3 (Version: 5.1.22-ndb-6.3.4)

     Notes
                               DESCRIPTION: Determines how an SQL node
                               chooses a cluster data node to use as
                               transaction coordinator

     There are two forms of optimized node selection, described here:

       1. The SQL node uses _promixity_ to determine the transaction
          coordinator; that is, the 'closest' data node to the SQL node
          is chosen as the transaction coordinator.  For this purpose, a
          data node having a shared memory connection with the SQL node
          is considered to be 'closest' to the SQL node; the next
          closest (in order of decreasing proximity) are: TCP connection
          to 'localhost'; SCI connection; TCP connection from a host
          other than 'localhost'.

       2. The SQL thread uses _distribution awareness_ to select the
          data node.  That is, the data node housing the cluster
          partition accessed by the first statement of a given
          transaction is used as the transaction coordinator for the
          entire transaction.  (This is effective only if the first
          statement of the transaction accesses no more than one cluster
          partition.)

     This option takes one of the integer values '0', '1', '2', or '3'.
     '3' is the default.  These values affect node selection as follows:

        * '0': Node selection is not optimized.  Each data node is
          employed as the transaction coordinator 8 times before the SQL
          thread proceeds to the next data node.

        * '1': Proximity to the SQL node is used to determine the
          transaction coordinator.

        * '2': Distribution awareness is used to select the transaction
          coordinator.  However, if the first statement of the
          transaction accesses more than one cluster partition, the SQL
          node reverts to the round-robin behavior seen when this option
          is set to '0'.

        * '3': If distribution awareness can be employed to determine
          the transaction coordinator, then it is used; otherwise
          proximity is used to select the transaction coordinator.
          (This is the default behavior.)

     Proximity is determined as follows:

       1. Start with the value set for the 'Group' parameter (default
          55).

       2. For an API node sharing the same host with other API nodes,
          decrement the value by 1.  Assuming the default value for
          'Group', the effective value for data nodes on same host as
          the API node is 54, and for remote data nodes 55.

       3. (_NDB 7.5.2 and later:_) Setting 'ndb_data_node_neighbour'
          further decreases the effective 'Group' value by 50, causing
          this node to be regarded as the nearest node.  This is needed
          only when all data nodes are on hosts other than that hosts
          the API node and it is desirable to dedicate one of them to
          the API node.  In normal cases, the default adjustment
          described previously is sufficient.

     Frequent changes in 'ndb_data_node_neighbour' are not advisable,
     since this changes the state of the cluster connection and thus may
     disrupt the selection algorithm for new transactions from each
     thread until it stablilizes.

   * 'ndb_read_backup'

     * Type and value information for ndb_read_backup*

     Property                  Value

     Name                      'ndb_read_backup'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: 5.7.12-ndb-7.5.2)

     Notes
                               DESCRIPTION: Enable read from any replica

     Enable read from any replica for any 'NDB' table subsequently
     created.

     Added in NDB 7.5.2.

   * 'ndb_recv_thread_activation_threshold'

     * Type and value information for
     ndb_recv_thread_activation_threshold*

     Property                  Value

     Name                      'ndb_recv_thread_activation_threshold'

     Command Line              No

     System Variable           No

     Status Variable           No

     Option File               No

     Scope

     Dynamic                   No

     Type

     Default, Range            8 / 0 (MIN_ACTIVATION_THRESHOLD) - 16
                               (MAX_ACTIVATION_THRESHOLD) (Version:
                               5.6.10-ndb-7.3.1)

     Notes
                               DESCRIPTION: Activation threshold when
                               receive thread takes over the polling of the
                               cluster connection (measured in concurrently
                               active threads)

     When this number of concurrently active threads is reached, the
     receive thread takes over polling of the cluster connection.

     This variable is global in scope.  It can also be set on startup
     using the '--ndb-recv-thread-activation-threshold' option.

   * 'ndb_recv_thread_cpu_mask'

     * Type and value information for ndb_recv_thread_cpu_mask*

     Property                  Value

     Name                      'ndb_recv_thread_cpu_mask'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            [empty] (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: CPU mask for locking receiver
                               threads to specific CPUs; specified as
                               hexadecimal.  See documentation for details.

     CPU mask for locking receiver threads to specific CPUs.  This is
     specified as a hexadecimal bitmask; for example, '0x33' means that
     one CPU is used per receiver thread.  An empty string is the
     default; setting 'ndb_recv_thread_cpu_mask' to this value removes
     any receiver thread locks previously set.

     This variable is global in scope.  It can also be set on startup
     using the '--ndb-recv-thread-cpu-mask' option.

   * 'ndb_report_thresh_binlog_epoch_slip'

     * Type and value information for
     ndb_report_thresh_binlog_epoch_slip*

     Property                  Value

     Name                      'ndb_report_thresh_binlog_epoch_slip'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            3 / 0 - 256 (Version: NDB 7.5-7.6)

     Default, Range            10 / 0 - 256 (Version: 5.7.16-ndb-7.5.4)

     Notes
                               DESCRIPTION: NDB 7.5.4 and later: Threshold
                               for number of epochs completely buffered, but
                               not yet consumed by binlog injector thread
                               which when exceeded generates
                               BUFFERED_EPOCHS_OVER_THRESHOLD event buffer
                               status message; prior to NDB 7.5.4: Threshold
                               for number of epochs to lag behind before
                               reporting binary log status

     In NDB 7.5.4 and later, this represents the threshold for the
     number of epochs completely buffered in the event buffer, but not
     yet consumed by the binlog injector thread.  When this degree of
     slippage (lag) is exceeded, an event buffer status message is
     reported, with 'BUFFERED_EPOCHS_OVER_THRESHOLD' supplied as the
     reason (see mysql-cluster-logs-event-buffer).  Slip is
     increased when an epoch is received from data nodes and buffered
     completely in the event buffer; it is decreased when an epoch is
     consumed by the binlog injector thread, it is reduced.  Empty
     epochs are buffered and queued, and so included in this calculation
     only when this is enabled using the
     'Ndb::setEventBufferQueueEmptyEpoch()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-seteventbufferqueueemptyepoch.html)
     method from the NDB API.

     Prior to NDB 7.5.4, the value of this vairable served as a
     threshold for the number of epochs to be behind before reporting
     binary log status.  In these previous releases, a value of '3'--the
     default--means that if the difference between which epoch has been
     received from the storage nodes and which epoch has been applied to
     the binary log is 3 or more, a status message is then sent to the
     cluster log.

   * 'ndb_report_thresh_binlog_mem_usage'

     * Type and value information for
     ndb_report_thresh_binlog_mem_usage*

     Property                  Value

     Name                      'ndb_report_thresh_binlog_mem_usage'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            10 / 0 - 10 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: This is a threshold on the
                               percentage of free memory remaining before
                               reporting binary log status

     This is a threshold on the percentage of free memory remaining
     before reporting binary log status.  For example, a value of '10'
     (the default) means that if the amount of available memory for
     receiving binary log data from the data nodes falls below 10%, a
     status message is sent to the cluster log.

   * 'slave_allow_batching'

     * Type and value information for slave_allow_batching*

     Property                  Value

     Name                      'slave_allow_batching'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            off (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Turns update batching on and off
                               for a replication slave

     Whether or not batched updates are enabled on NDB Cluster
     replication slaves.

     Setting this variable has an effect only when using replication
     with the 'NDB' storage engine; in MySQL Server 5.7, it is present
     but does nothing.  For more information, see
     mysql-cluster-replication-starting.

   * 'ndb_show_foreign_key_mock_tables'

     * Type and value information for ndb_show_foreign_key_mock_tables*

     Property                  Value

     Name                      'ndb_show_foreign_key_mock_tables'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Show the mock tables used to
                               support foreign_key_checks=0

     Show the mock tables used by 'NDB' to support
     'foreign_key_checks=0'.  When this is enabled, extra warnings are
     shown when creating and dropping the tables.  The real (internal)
     name of the table can be seen in the output of 'SHOW CREATE TABLE'.

   * 'ndb_slave_conflict_role'

     * Type and value information for ndb_slave_conflict_role*

     Property                  Value

     Name                      'ndb_slave_conflict_role'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            NONE / NONE, PRIMARY, SECONDARY, PASS
                               (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Role for slave to play in
                               conflict detection and resolution.  Value is
                               one of PRIMARY, SECONDARY, PASS, or NONE
                               (default).  Can be changed only when slave
                               SQL thread is stopped.  See documentation for
                               further information.

     Determine the role of this SQL node (and NDB Cluster) in a circular
     ('active-active') replication setup.  'ndb_slave_conflict_role' can
     take any one of the values 'PRIMARY', 'SECONDARY', 'PASS', or
     'NULL' (the default).  The slave SQL thread must be stopped before
     you can change 'ndb_slave_conflict_role'.  In addition, it is not
     possible to change directly between 'PASS' and either of 'PRIMARY'
     or 'SECONDARY' directly; in such cases, you must ensure that the
     SQL thread is stopped, then execute 'SET @@GLOBAL.ndb_slave_conflict_role = 'NONE''
     first.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'ndb_table_no_logging'

     * Type and value information for ndb_table_no_logging*

     Property                  Value

     Name                      'ndb_table_no_logging'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Session

     Dynamic                   Yes

     Type

     Default, Range            FALSE (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: NDB tables created when this
                               setting is enabled are not checkpointed to
                               disk (although table schema files are
                               created).  The setting in effect when the
                               table is created with or altered to use
                               NDBCLUSTER persists for the lifetime of the
                               table.

     When this variable is set to 'ON' or '1', it causes 'NDB'
     tables not to be checkpointed to disk.  More
     specifically, this setting applies to tables which are created or
     altered using 'ENGINE NDB' when 'ndb_table_no_logging' is enabled,
     and continues to apply for the lifetime of the table, even if
     'ndb_table_no_logging' is later changed.  Suppose that 'A', 'B',
     'C', and 'D' are tables that we create (and perhaps also alter),
     and that we also change the setting for 'ndb_table_no_logging' as
     shown here:

          SET @@ndb_table_no_logging = 1;

          CREATE TABLE A ... ENGINE NDB;

          CREATE TABLE B ... ENGINE MYISAM;
          CREATE TABLE C ... ENGINE MYISAM;

          ALTER TABLE B ENGINE NDB;

          SET @@ndb_table_no_logging = 0;

          CREATE TABLE D ... ENGINE NDB;
          ALTER TABLE C ENGINE NDB;

          SET @@ndb_table_no_logging = 1;

     After the previous sequence of events, tables 'A' and 'B' are not
     checkpointed; 'A' was created with 'ENGINE NDB' and B was altered
     to use 'NDB', both while 'ndb_table_no_logging' was enabled.
     However, tables 'C' and 'D' are logged; 'C' was altered to use
     'NDB' and 'D' was created using 'ENGINE NDB',
     both while 'ndb_table_no_logging' was disabled.  Setting
     'ndb_table_no_logging' back to '1' or 'ON' does _not_ cause table
     'C' or 'D' to be checkpointed.

     *Note*:

     'ndb_table_no_logging' has no effect on the creation of
     'NDB' table schema files; to suppress these, use
     'ndb_table_temporary' instead.

   * 'ndb_table_temporary'

     * Type and value information for ndb_table_temporary*

     Property                  Value

     Name                      'ndb_table_temporary'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Session

     Dynamic                   Yes

     Type

     Default, Range            FALSE (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: NDB tables are not persistent on
                               disk: no schema files are created and the
                               tables are not logged

     When set to 'ON' or '1', this variable causes 'NDB'
     tables not to be written to disk: This means that no
     table schema files are created, and that the tables are not logged.

     *Note*:

     Setting this variable currently has no effect.  This is a known
     issue; see Bug #34036.

   * 'ndb_use_copying_alter_table'

     * Type and value information for ndb_use_copying_alter_table*

     Property                  Value

     Name                      'ndb_use_copying_alter_table'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   No

     Type

     Notes                     DESCRIPTION: Use copying ALTER TABLE
                               operations in NDB Cluster

     Forces 'NDB' to use copying of tables in the
     event of problems with online 'ALTER TABLE'.
     operations.  The default value is 'OFF'.

   * 'ndb_use_exact_count'

     * Type and value information for ndb_use_exact_count*

     Property                  Value

     Name                      'ndb_use_exact_count'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            ON (Version: NDB 7.5-7.6)

     Default, Range            OFF (Version: 5.1.47-ndb-7.1.8)

     Notes
                               DESCRIPTION: Use exact row count when
                               planning queries

     Forces 'NDB' to use a count of records during
     'SELECT COUNT(*)' query planning to speed up this type of query.
     The default value is 'OFF', which allows for faster queries
     overall.

   * 'ndb_use_transactions'

     * Type and value information for ndb_use_transactions*

     Property                  Value

     Name                      'ndb_use_transactions'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            ON (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Forces NDB to use a count of
                               records during SELECT COUNT(*) query planning
                               to speed up this type of query

     You can disable 'NDB' transaction support by
     setting this variable's values to 'OFF' (not recommended).  The
     default is 'ON'.

   * 'ndb_version'

     * Type and value information for ndb_version*

     Property                  Value

     Name                      'ndb_version'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Shows build and NDB engine
                               version as an integer

     'NDB' engine version, as a composite integer.

   * 'ndb_version_string'

     * Type and value information for ndb_version_string*

     Property                  Value

     Name                      'ndb_version_string'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Shows build information
                               including NDB engine version in ndb-x.y.z
                               format

     'NDB' engine version in 'ndb-X.Y.Z' format.

   *
     'server_id_bits'

     * Type and value information for server_id_bits*

     Property                  Value

     Name                      'server_id_bits'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               Yes

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            32 / 7 - 32 (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: The effective value of server_id
                               if the server was started with the
                               -server-id-bits option set to a nondefault
                               value

     The effective value of 'server_id' if the server was started with
     the '--server-id-bits' option set to a nondefault value.

     If the value of 'server_id' greater than or equal to 2 to the power
     of 'server_id_bits', see 'mysqld' refuses to start.

     This system variable is supported only by NDB Cluster.
     'server_id_bits' is not supported by the standard MySQL Server.

   *
     'transaction_allow_batching'

     * Type and value information for transaction_allow_batching*

     Property                  Value

     Name                      'transaction_allow_batching'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Session

     Dynamic                   Yes

     Type

     Default, Range            FALSE (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Allows batching of statements
                               within a transaction.  Disable AUTOCOMMIT to
                               use.

     When set to '1' or 'ON', this variable enables batching of
     statements within the same transaction.  To use this variable,
     'autocommit' must first be disabled by setting it to '0' or 'OFF';
     otherwise, setting 'transaction_allow_batching' has no effect.

     It is safe to use this variable with transactions that performs
     writes only, as having it enabled can lead to reads from the
     'before' image.  You should ensure that any pending transactions
     are committed (using an explicit 'COMMIT' if
     desired) before issuing a 'SELECT'.

     *Important*:

     'transaction_allow_batching' should not be used whenever there is
     the possibility that the effects of a given statement depend on the
     outcome of a previous statement within the same transaction.

     This variable is currently supported for NDB Cluster only.

The system variables in the following list all relate to the
'ndbinfo' information database.

   * 'ndbinfo_database'

     * Type and value information for ndbinfo_database*

     Property                  Value

     Name                      'ndbinfo_database'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            ndbinfo (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: The name used for the NDB
                               information database; read only

     Shows the name used for the 'NDB' information database; the default
     is 'ndbinfo'.  This is a read-only variable whose value is
     determined at compile time; you can set it by starting the server
     using '--ndbinfo-database=NAME', which sets the value shown for
     this variable but does not actually change the name used for the
     NDB information database.

   * 'ndbinfo_max_bytes'

     * Type and value information for ndbinfo_max_bytes*

     Property                  Value

     Name                      'ndbinfo_max_bytes'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            0 / - (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Used for debugging only

     Used in testing and debugging only.

   * 'ndbinfo_max_rows'

     * Type and value information for ndbinfo_max_rows*

     Property                  Value

     Name                      'ndbinfo_max_rows'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            10 / - (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Used for debugging only

     Used in testing and debugging only.

   * 'ndbinfo_offline'

     * Type and value information for ndbinfo_offline*

     Property                  Value

     Name                      'ndbinfo_offline'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Put the ndbinfo database into
                               offline mode, in which no rows are returned
                               from tables or views

     Place the 'ndbinfo' database into
     offline mode, in which tables and views can be opened even when
     they do not actually exist, or when they exist but have different
     definitions in 'NDB'.  No rows are returned
     from such tables (or views).

   * 'ndbinfo_show_hidden'

     * Type and value information for ndbinfo_show_hidden*

     Property                  Value

     Name                      'ndbinfo_show_hidden'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            OFF (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: Whether to show ndbinfo internal
                               base tables in the mysql client.  The default
                               is OFF.

     Whether or not the 'ndbinfo'.
     database's underlying internal tables are shown in the 'mysql'
     client.  The default is 'OFF'.

   * 'ndbinfo_table_prefix'

     * Type and value information for ndbinfo_table_prefix*

     Property                  Value

     Name                      'ndbinfo_table_prefix'

     Command Line              Yes

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Both

     Dynamic                   Yes

     Type

     Default, Range            ndb$ (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: The prefix to use for naming
                               ndbinfo internal base tables

     The prefix used in naming the ndbinfo database's base tables
     (normally hidden, unless exposed by setting 'ndbinfo_show_hidden').
     This is a read-only variable whose default value is 'ndb$'.  You
     can start the server with the '--ndbinfo-table-prefix' option, but
     this merely sets the variable and does not change the actual prefix
     used to name the hidden base tables; the prefix itself is
     determined at compile time.

   * 'ndbinfo_version'

     * Type and value information for ndbinfo_version*

     Property                  Value

     Name                      'ndbinfo_version'

     Command Line              No

     System Variable           Yes

     Status Variable           No

     Option File               No

     Scope                     Global

     Dynamic                   No

     Type

     Default, Range            (Version: NDB 7.5-7.6)

     Notes
                               DESCRIPTION: The version of the ndbinfo
                               engine; read only

     Shows the version of the 'ndbinfo'.
     engine in use; read-only.

21.3.3.12 NDB Cluster Status Variables
......................................

This section provides detailed information about MySQL server status
variables that relate to NDB Cluster and the 'NDB'.
storage engine.  For status variables not specific to NDB Cluster, and
for general information on using status variables, see
server-status-variables.

   * 'Handler_discover'

     The MySQL server can ask the 'NDBCLUSTER'.
     storage engine if it knows about a table with a given name.  This
     is called discovery.  'Handler_discover' indicates the number of
     times that tables have been discovered using this mechanism.

   * 'Ndb_api_bytes_sent_count_session'

     Amount of data (in bytes) sent to the data nodes in this client
     session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_bytes_sent_count_slave'

     Amount of data (in bytes) sent to the data nodes by this slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_bytes_sent_count'

     Amount of data (in bytes) sent to the data nodes by this MySQL
     Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_bytes_received_count_session'

     Amount of data (in bytes) received from the data nodes in this
     client session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_bytes_received_count_slave'

     Amount of data (in bytes) received from the data nodes by this
     slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_bytes_received_count'

     Amount of data (in bytes) received from the data nodes by this
     MySQL Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_event_data_count_injector'

     The number of row change events received by the NDB binlog injector
     thread.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_event_data_count'

     The number of row change events received by this MySQL Server (SQL
     node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_event_nondata_count_injector'

     The number of events received, other than row change events, by the
     NDB binary log injector thread.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_event_nondata_count'

     The number of events received, other than row change events, by
     this MySQL Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_event_bytes_count_injector'

     The number of bytes of events received by the NDB binlog injector
     thread.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_event_bytes_count'

     The number of bytes of events received by this MySQL Server (SQL
     node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_pk_op_count_session'

     The number of operations in this client session based on or using
     primary keys.  This includes operations on blob tables, implicit
     unlock operations, and auto-increment operations, as well as
     user-visible primary key operations.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_pk_op_count_slave'

     The number of operations by this slave based on or using primary
     keys.  This includes operations on blob tables, implicit unlock
     operations, and auto-increment operations, as well as user-visible
     primary key operations.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_pk_op_count'

     The number of operations by this MySQL Server (SQL node) based on
     or using primary keys.  This includes operations on blob tables,
     implicit unlock operations, and auto-increment operations, as well
     as user-visible primary key operations.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_pruned_scan_count_session'

     The number of scans in this client session that have been pruned to
     a single partition.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_pruned_scan_count_slave'

     The number of scans by this slave that have been pruned to a single
     partition.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_pruned_scan_count'

     The number of scans by this MySQL Server (SQL node) that have been
     pruned to a single partition.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_range_scan_count_session'

     The number of range scans that have been started in this client
     session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_range_scan_count_slave'

     The number of range scans that have been started by this slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_range_scan_count'

     The number of range scans that have been started by this MySQL
     Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_read_row_count_session'

     The total number of rows that have been read in this client
     session.  This includes all rows read by any primary key, unique
     key, or scan operation made in this client session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_read_row_count_slave'

     The total number of rows that have been read by this slave.  This
     includes all rows read by any primary key, unique key, or scan
     operation made by this slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_read_row_count'

     The total number of rows that have been read by this MySQL Server
     (SQL node).  This includes all rows read by any primary key, unique
     key, or scan operation made by this MySQL Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_scan_batch_count_session'

     The number of batches of rows received in this client session.  1
     batch is defined as 1 set of scan results from a single fragment.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_scan_batch_count_slave'

     The number of batches of rows received by this slave.  1 batch is
     defined as 1 set of scan results from a single fragment.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_scan_batch_count'

     The number of batches of rows received by this MySQL Server (SQL
     node).  1 batch is defined as 1 set of scan results from a single
     fragment.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_table_scan_count_session'

     The number of table scans that have been started in this client
     session, including scans of internal tables,.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_table_scan_count_slave'

     The number of table scans that have been started by this slave,
     including scans of internal tables,.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_table_scan_count'

     The number of table scans that have been started by this MySQL
     Server (SQL node), including scans of internal tables,.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_abort_count_session'

     The number of transactions aborted in this client session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_abort_count_slave'

     The number of transactions aborted by this slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_abort_count'

     The number of transactions aborted by this MySQL Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_close_count_session'

     The number of transactions closed in this client session.  This
     value may be greater than the sum of
     'Ndb_api_trans_commit_count_session' and
     'Ndb_api_trans_abort_count_session', since some transactions may
     have been rolled back.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_close_count_slave'

     The number of transactions closed by this slave.  This value may be
     greater than the sum of 'Ndb_api_trans_commit_count_slave' and
     'Ndb_api_trans_abort_count_slave', since some transactions may have
     been rolled back.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_close_count'

     The number of transactions closed by this MySQL Server (SQL node).
     This value may be greater than the sum of
     'Ndb_api_trans_commit_count' and 'Ndb_api_trans_abort_count', since
     some transactions may have been rolled back.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_commit_count_session'

     The number of transactions committed in this client session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_commit_count_slave'

     The number of transactions committed by this slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_commit_count'

     The number of transactions committed by this MySQL Server (SQL
     node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_local_read_row_count_session'

     The total number of rows that have been read in this client
     session.  This includes all rows read by any primary key, unique
     key, or scan operation made in this client session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_local_read_row_count_slave'

     The total number of rows that have been read by this slave.  This
     includes all rows read by any primary key, unique key, or scan
     operation made by this slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_local_read_row_count'

     The total number of rows that have been read by this MySQL Server
     (SQL node).  This includes all rows read by any primary key, unique
     key, or scan operation made by this MySQL Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_start_count_session'

     The number of transactions started in this client session.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_start_count_slave'

     The number of transactions started by this slave.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_trans_start_count'

     The number of transactions started by this MySQL Server (SQL node).

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_uk_op_count_session'

     The number of operations in this client session based on or using
     unique keys.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_uk_op_count_slave'

     The number of operations by this slave based on or using unique
     keys.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_uk_op_count'

     The number of operations by this MySQL Server (SQL node) based on
     or using unique keys.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_exec_complete_count_session'

     The number of times a thread has been blocked in this client
     session while waiting for execution of an operation to complete.
     This includes all 'execute()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-execute.html)
     calls as well as implicit implicit executes for blob and
     auto-increment operations not visible to clients.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_exec_complete_count_slave'

     The number of times a thread has been blocked by this slave while
     waiting for execution of an operation to complete.  This includes
     all 'execute()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-execute.html)
     calls as well as implicit implicit executes for blob and
     auto-increment operations not visible to clients.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_exec_complete_count'

     The number of times a thread has been blocked by this MySQL Server
     (SQL node) while waiting for execution of an operation to complete.
     This includes all 'execute()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-execute.html)
     calls as well as implicit implicit executes for blob and
     auto-increment operations not visible to clients.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_meta_request_count_session'

     The number of times a thread has been blocked in this client
     session waiting for a metadata-based signal, such as is expected
     for DDL requests, new epochs, and seizure of transaction records.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_meta_request_count_slave'

     The number of times a thread has been blocked by this slave waiting
     for a metadata-based signal, such as is expected for DDL requests,
     new epochs, and seizure of transaction records.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_meta_request_count'

     The number of times a thread has been blocked by this MySQL Server
     (SQL node) waiting for a metadata-based signal, such as is expected
     for DDL requests, new epochs, and seizure of transaction records.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_nanos_count_session'

     Total time (in nanoseconds) spent in this client session waiting
     for any type of signal from the data nodes.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_nanos_count_slave'

     Total time (in nanoseconds) spent by this slave waiting for any
     type of signal from the data nodes.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_nanos_count'

     Total time (in nanoseconds) spent by this MySQL Server (SQL node)
     waiting for any type of signal from the data nodes.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_scan_result_count_session'

     The number of times a thread has been blocked in this client
     session while waiting for a scan-based signal, such as when waiting
     for more results from a scan, or when waiting for a scan to close.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it relates to the current session only, and is not affected by any
     other clients of this 'mysqld'.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_scan_result_count_slave'

     The number of times a thread has been blocked by this slave while
     waiting for a scan-based signal, such as when waiting for more
     results from a scan, or when waiting for a scan to close.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.  If this MySQL server does not
     act as a replication slave, or does not use NDB tables, this value
     is always 0.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_api_wait_scan_result_count'

     The number of times a thread has been blocked by this MySQL Server
     (SQL node) while waiting for a scan-based signal, such as when
     waiting for more results from a scan, or when waiting for a scan to
     close.

     Although this variable can be read using either 'SHOW GLOBAL STATUS'
     or 'SHOW SESSION STATUS',
     it is effectively global in scope.

     For more information, see mysql-cluster-ndb-api-statistics.

   * 'Ndb_cluster_node_id'

     If the server is acting as an NDB Cluster node, then the value of
     this variable its node ID in the cluster.

     If the server is not part of an NDB Cluster, then the value of this
     variable is 0.

   * 'Ndb_config_from_host'

     If the server is part of an NDB Cluster, the value of this variable
     is the host name or IP address of the Cluster management server
     from which it gets its configuration data.

     If the server is not part of an NDB Cluster, then the value of this
     variable is an empty string.

   * 'Ndb_config_from_port'

     If the server is part of an NDB Cluster, the value of this variable
     is the number of the port through which it is connected to the
     Cluster management server from which it gets its configuration
     data.

     If the server is not part of an NDB Cluster, then the value of this
     variable is 0.

   * 'Ndb_conflict_fn_max_del_win'

     Shows the number of times that a row was rejected on the current
     SQL node due to NDB Cluster Replication conflict resolution using
     'NDB$MAX_DELETE_WIN()', since the last time that this
     'mysqld' was started.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_fn_max'

     Used in NDB Cluster Replication conflict resolution, this variable
     shows the number of times that a row was not applied on the current
     SQL node due to 'greatest timestamp wins' conflict resolution since
     the last time that this 'mysqld' was started.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_fn_old'

     Used in NDB Cluster Replication conflict resolution, this variable
     shows the number of times that a row was not applied as the result
     of 'same timestamp wins' conflict resolution on a given
     'mysqld' since the last time it was restarted.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_fn_epoch'

     Used in NDB Cluster Replication conflict resolution, this variable
     shows the number of rows found to be in conflict using
     'NDB$EPOCH()' conflict resolution on a given 'mysqld'
     since the last time it was restarted.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_fn_epoch2'

     Shows the number of rows found to be in conflict in NDB Cluster
     Replication conflict resolution, when using 'NDB$EPOCH2()', on the
     master designated as the primary since the last time it was
     restarted.

     For more information, see
     mysql-cluster-replication-ndb-epoch2.

   * 'Ndb_conflict_fn_epoch_trans'

     Used in NDB Cluster Replication conflict resolution, this variable
     shows the number of rows found to be in conflict using
     'NDB$EPOCH_TRANS()' conflict resolution on a given 'mysqld'
     since the last time it was restarted.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_fn_epoch2_trans'

     Used in NDB Cluster Replication conflict resolution, this variable
     shows the number of rows found to be in conflict using
     'NDB$EPOCH_TRANS2()' conflict resolution on a given 'mysqld'
     since the last time it was restarted.

     For more information, see
     mysql-cluster-replication-ndb-epoch2-trans.

   * 'Ndb_conflict_last_conflict_epoch'

     The most recent epoch in which a conflict was detected on this
     slave.  You can compare this value with
     'Ndb_slave_max_replicated_epoch'; if
     'Ndb_slave_max_replicated_epoch' is greater than
     'Ndb_conflict_last_conflict_epoch', no conflicts have yet been
     detected.

     See mysql-cluster-replication-conflict-resolution, for more
     information.

   * 'Ndb_conflict_reflected_op_discard_count'

     When using NDB Cluster Replication conflict resolution, this is the
     number of reflected operations that were not applied on the
     secondary, due to encountering an error during execution.

     See mysql-cluster-replication-conflict-resolution, for more
     information.

   * 'Ndb_conflict_reflected_op_prepare_count'

     When using conflict resolution with NDB Cluster Replication, this
     status variable contains the number of reflected operations that
     have been defined (that is, prepared for execution on the
     secondary).

     See mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_refresh_op_count'

     When using conflict resolution with NDB Cluster Replication, this
     gives the number of refresh operations that have been prepared for
     execution on the secondary.

     See mysql-cluster-replication-conflict-resolution, for more
     information.

   * 'Ndb_conflict_last_stable_epoch'

     Number of rows found to be in conflict by a transactional conflict
     function

     See mysql-cluster-replication-conflict-resolution, for more
     information.

   * 'Ndb_conflict_trans_row_conflict_count'

     Used in NDB Cluster Replication conflict resolution, this status
     variable shows the number of rows found to be directly in-conflict
     by a transactional conflict function on a given 'mysqld'
     since the last time it was restarted.

     Currently, the only transactional conflict detection function
     supported by NDB Cluster is NDB$EPOCH_TRANS(), so this status
     variable is effectively the same as 'Ndb_conflict_fn_epoch_trans'.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_trans_row_reject_count'

     Used in NDB Cluster Replication conflict resolution, this status
     variable shows the total number of rows realigned due to being
     determined as conflicting by a transactional conflict detection
     function.  This includes not only
     'Ndb_conflict_trans_row_conflict_count', but any rows in or
     dependent on conflicting transactions.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_trans_reject_count'

     Used in NDB Cluster Replication conflict resolution, this status
     variable shows the number of transactions found to be in conflict
     by a transactional conflict detection function.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_trans_detect_iter_count'

     Used in NDB Cluster Replication conflict resolution, this shows the
     number of internal iterations required to commit an epoch
     transaction.  Should be (slightly) greater than or equal to
     'Ndb_conflict_trans_conflict_commit_count'.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_conflict_trans_conflict_commit_count'

     Used in NDB Cluster Replication conflict resolution, this shows the
     number of epoch transactions committed after they required
     transactional conflict handling.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_epoch_delete_delete_count'

     When using delete-delete conflict detection, this is the number of
     delete-delete conflicts detected, where a delete operation is
     applied, but the indicated row does not exist.

   * 'Ndb_execute_count'

     Provides the number of round trips to the 'NDB'
     kernel made by operations.

   * 'Ndb_last_commit_epoch_server'

     The epoch most recently committed by 'NDB'.

   * 'Ndb_last_commit_epoch_session'

     The epoch most recently committed by this 'NDB' client.

   * 'Ndb_number_of_data_nodes'

     If the server is part of an NDB Cluster, the value of this variable
     is the number of data nodes in the cluster.

     If the server is not part of an NDB Cluster, then the value of this
     variable is 0.

   * 'Ndb_pushed_queries_defined'

     The total number of joins pushed down to the NDB kernel for
     distributed handling on the data nodes.

     *Note*:

     Joins tested using 'EXPLAIN' that can be pushed
     down contribute to this number.

   * 'Ndb_pushed_queries_dropped'

     The number of joins that were pushed down to the NDB kernel but
     that could not be handled there.

   * 'Ndb_pushed_queries_executed'

     The number of joins successfully pushed down to 'NDB'
     and executed there.

   * 'Ndb_pushed_reads'

     The number of rows returned to 'mysqld' from the NDB
     kernel by joins that were pushed down.

     *Note*:

     Executing 'EXPLAIN' on joins that can be pushed
     down to 'NDB' does not add to this number.

   * 'Ndb_pruned_scan_count'

     This variable holds a count of the number of scans executed by
     'NDBCLUSTER' since the NDB Cluster was last
     started where 'NDBCLUSTER' was able to use
     partition pruning.

     Using this variable together with 'Ndb_scan_count' can be helpful
     in schema design to maximize the ability of the server to prune
     scans to a single table partition, thereby involving only a single
     data node.

   * 'Ndb_scan_count'

     This variable holds a count of the total number of scans executed
     by 'NDBCLUSTER' since the NDB Cluster was
     last started.

   * 'Ndb_slave_max_replicated_epoch'

     The most recently committed epoch on this slave.  You can compare
     this value with 'Ndb_conflict_last_conflict_epoch'; if
     'Ndb_slave_max_replicated_epoch' is the greater of the two, no
     conflicts have yet been detected.

     For more information, see
     mysql-cluster-replication-conflict-resolution.

   * 'Ndb_system_name'

     If this MySQL Server is connected to an NDB cluster, this read-only
     variable shows the cluster system name.  Otherwise, the value is an
     empty string.

21.3.3.13 NDB Cluster TCP/IP Connections
........................................

TCP/IP is the default transport mechanism for all connections between
nodes in an NDB Cluster.  Normally it is not necessary to define TCP/IP
connections; NDB Cluster automatically sets up such connections for all
data nodes, management nodes, and SQL or API nodes.

*Note*:

For an exception to this rule, see
mysql-cluster-tcp-definition-direct.

To override the default connection parameters, it is necessary to define
a connection using one or more '[tcp]' sections in the 'config.ini'
file.  Each '[tcp]' section explicitly defines a TCP/IP connection
between two NDB Cluster nodes, and must contain at a minimum the
parameters 'NodeId1' and 'NodeId2', as well as any connection parameters
to override.

It is also possible to change the default values for these parameters by
setting them in the '[tcp default]' section.

*Important*:

Any '[tcp]' sections in the 'config.ini' file should be listed _last_,
following all other sections in the file.  However, this is not required
for a '[tcp default]' section.  This requirement is a known issue with
the way in which the 'config.ini' file is read by the NDB Cluster
management server.

Connection parameters which can be set in '[tcp]' and '[tcp default]'
sections of the 'config.ini' file are listed here:

   *
     'NodeId1'

     *This table provides type and value information for the NodeId1 TCP
     configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     To identify a connection between two nodes it is necessary to
     provide their node IDs in the '[tcp]' section of the configuration
     file as the values of 'NodeId1' and 'NodeId2'.  These are the same
     unique 'Id' values for each of these nodes as described in
     mysql-cluster-api-definition.

   *
     'NodeId2'

     *This table provides type and value information for the NodeId2 TCP
     configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     To identify a connection between two nodes it is necessary to
     provide their node IDs in the '[tcp]' section of the configuration
     file as the values of 'NodeId1' and 'NodeId2'.  These are the same
     unique 'Id' values for each of these nodes as described in
     mysql-cluster-api-definition.

   *
     'HostName1'

     *This table provides type and value information for the HostName1
     TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     The 'HostName1' and 'HostName2' parameters can be used to specify
     specific network interfaces to be used for a given TCP connection
     between two nodes.  The values used for these parameters can be
     host names or IP addresses.

   *
     'HostName2'

     *This table provides type and value information for the HostName1
     TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     The 'HostName1' and 'HostName2' parameters can be used to specify
     specific network interfaces to be used for a given TCP connection
     between two nodes.  The values used for these parameters can be
     host names or IP addresses.

   *
     'OverloadLimit'

     *This table provides type and value information for the
     OverloadLimit TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When more than this many unsent bytes are in the send buffer, the
     connection is considered overloaded.

     This parameter can be used to determine the amount of unsent data
     that must be present in the send buffer before the connection is
     considered overloaded.  See
     mysql-cluster-config-send-buffers, for more information.

   *
     'SendBufferMemory'

     *This table provides type and value information for the
     SendBufferMemory TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            2M

     *Range*                              256K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     TCP transporters use a buffer to store all messages before
     performing the send call to the operating system.  When this buffer
     reaches 64KB its contents are sent; these are also sent when a
     round of messages have been executed.  To handle temporary overload
     situations it is also possible to define a bigger send buffer.

     If this parameter is set explicitly, then the memory is not
     dedicated to each transporter; instead, the value used denotes the
     hard limit for how much memory (out of the total available
     memory--that is, 'TotalSendBufferMemory') that may be used by a
     single transporter.  For more information about configuring dynamic
     transporter send buffer memory allocation in NDB Cluster, see
     mysql-cluster-config-send-buffers.

     The default size of the send buffer is 2MB, which is the size
     recommended in most situations.  The minimum size is 64 KB; the
     theoretical maximum is 4 GB.

   *
     'SendSignalId'

     *This table provides type and value information for the
     SendSignalId TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            [see text]

     *Range*                              true, false

     *Restart Type.
     *

     To be able to retrace a distributed message datagram, it is
     necessary to identify each message.  When this parameter is set to
     'Y', message IDs are transported over the network.  This feature is
     disabled by default in production builds, and enabled in '-debug'
     builds.

   *
     'Checksum'

     *This table provides type and value information for the Checksum
     TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     This parameter is a boolean parameter (enabled by setting it to 'Y'
     or '1', disabled by setting it to 'N' or '0').  It is disabled by
     default.  When it is enabled, checksums for all messages are
     calculated before they placed in the send buffer.  This feature
     ensures that messages are not corrupted while waiting in the send
     buffer, or by the transport mechanism.

   *
     'PortNumber' (_OBSOLETE_)

     This parameter formerly specified the port number to be used for
     listening for connections from other nodes.  It is now deprecated
     (and removed in NDB Cluster 7.5); use the 'ServerPort' data node
     configuration parameter for this purpose instead (Bug #77405, Bug
     #21280456).

   *
     'ReceiveBufferMemory'

     *This table provides type and value information for the
     ReceiveBufferMemory TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            2M

     *Range*                              16K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Specifies the size of the buffer used when receiving data from the
     TCP/IP socket.

     The default value of this parameter is 2MB. The minimum possible
     value is 16KB; the theoretical maximum is 4GB.

   *
     'TCP_RCV_BUF_SIZE'

     *This table provides type and value information for the
     TCP_RCV_BUF_SIZE TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 2G

     *Restart Type.
     *

     Determines the size of the receive buffer set during TCP
     transporter initialization.  The default and minimum value is 0,
     which allows the operating system or platform to set this value.
     The default is recommended for most common usage cases.

   *
     'TCP_SND_BUF_SIZE'

     *This table provides type and value information for the
     TCP_SND_BUF_SIZE TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 2G

     *Restart Type.
     *

     Determines the size of the send buffer set during TCP transporter
     initialization.  The default and minimum value is 0, which allows
     the operating system or platform to set this value.  The default is
     recommended for most common usage cases.

   *
     'TCP_MAXSEG_SIZE'

     *This table provides type and value information for the
     TCP_MAXSEG_SIZE TCP configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 2G

     *Restart Type.
     *

     Determines the size of the memory set during TCP transporter
     initialization.  The default is recommended for most common usage
     cases.

   * 'TcpBind_INADDR_ANY'

     Setting this parameter to 'TRUE' or '1' binds 'IP_ADDR_ANY' so that
     connections can be made from anywhere (for autogenerated
     connections).  The default is 'FALSE' ('0').

   * 'Group'

     When 'ndb_optimized_node_selection' is enabled, node proximity is
     used in some cases to select which node to connect to.  This
     parameter can be used to influence proximity by setting it to a
     lower value, which is interpreted as 'closer'.  See the description
     of the system variable for more information.

21.3.3.14 NDB Cluster TCP/IP Connections Using Direct Connections
.................................................................

Setting up a cluster using direct connections between data nodes
requires specifying explicitly the crossover IP addresses of the data
nodes so connected in the '[tcp]' section of the cluster 'config.ini'
file.

In the following example, we envision a cluster with at least four
hosts, one each for a management server, an SQL node, and two data
nodes.  The cluster as a whole resides on the '172.23.72.*' subnet of a
LAN. In addition to the usual network connections, the two data nodes
are connected directly using a standard crossover cable, and communicate
with one another directly using IP addresses in the '1.1.0.*' address
range as shown:

     # Management Server
     [ndb_mgmd]
     Id=1
     HostName=172.23.72.20

     # SQL Node
     [mysqld]
     Id=2
     HostName=172.23.72.21

     # Data Nodes
     [ndbd]
     Id=3
     HostName=172.23.72.22

     [ndbd]
     Id=4
     HostName=172.23.72.23

     # TCP/IP Connections
     [tcp]
     NodeId1=3
     NodeId2=4
     HostName1=1.1.0.1
     HostName2=1.1.0.2

The 'HostName1' and 'HostName2' parameters are used only when specifying
direct connections.

The use of direct TCP connections between data nodes can improve the
cluster's overall efficiency by enabling the data nodes to bypass an
Ethernet device such as a switch, hub, or router, thus cutting down on
the cluster's latency.

*Note*:

To take the best advantage of direct connections in this fashion with
more than two data nodes, you must have a direct connection between each
data node and every other data node in the same node group.

21.3.3.15 NDB Cluster Shared-Memory Connections
...............................................

NDB Cluster attempts to use the shared memory transporter and configure
it automatically where possible.  '[shm]' sections in the 'config.ini'
file explicitly define shared-memory connections between nodes in the
cluster.  When explicitly defining shared memory as the connection
method, it is necessary to define at least 'NodeId1', 'NodeId2', and
'ShmKey'.  All other parameters have default values that should work
well in most cases.

*Important*:

_SHM functionality is considered experimental only_.  It is not
officially supported in any current NDB Cluster release, and testing
results indicate that SHM performance is not appreciably greater than
when using TCP/IP for the transporter.

For these reasons, you must determine for yourself or by using our free
resources (forums, mailing lists) whether SHM can be made to work
correctly in your specific case.

   *
     'NodeId1'

     *This table provides type and value information for the NodeId1
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     To identify a connection between two nodes it is necessary to
     provide node identifiers for each of them, as 'NodeId1' and
     'NodeId2'.

   *
     'NodeId2'

     *This table provides type and value information for the NodeId2
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     To identify a connection between two nodes it is necessary to
     provide node identifiers for each of them, as 'NodeId1' and
     'NodeId2'.

   *
     'HostName1'

     *This table provides type and value information for the HostName1
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     The 'HostName1' and 'HostName2' parameters can be used to specify
     specific network interfaces to be used for a given SHM connection
     between two nodes.  The values used for these parameters can be
     host names or IP addresses.

   *
     'HostName2'

     *This table provides type and value information for the HostName1
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     The 'HostName1' and 'HostName2' parameters can be used to specify
     specific network interfaces to be used for a given SHM connection
     between two nodes.  The values used for these parameters can be
     host names or IP addresses.

   *
     'OverloadLimit'

     *This table provides type and value information for the
     OverloadLimit shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When more than this many unsent bytes are in the send buffer, the
     connection is considered overloaded.

     This parameter can be used to determine the amount of unsent data
     that must be present in the send buffer before the connection is
     considered overloaded.  See
     mysql-cluster-config-send-buffers, and
     mysql-cluster-ndbinfo-transporters, for more information.

   *
     'ShmKey'

     *This table provides type and value information for the ShmKey
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When setting up shared memory segments, a node ID, expressed as an
     integer, is used to identify uniquely the shared memory segment to
     use for the communication.  There is no default value.

   *
     'ShmSize'

     *This table provides type and value information for the ShmSize
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            1M

     *Range*                              64K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Each SHM connection has a shared memory segment where messages
     between nodes are placed by the sender and read by the reader.  The
     size of this segment is defined by 'ShmSize'.  The default value is
     1MB.

   *
     'SendSignalId'

     *This table provides type and value information for the
     SendSignalId shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     To retrace the path of a distributed message, it is necessary to
     provide each message with a unique identifier.  Setting this
     parameter to 'Y' causes these message IDs to be transported over
     the network as well.  This feature is disabled by default in
     production builds, and enabled in '-debug' builds.

   *
     'Checksum'

     *This table provides type and value information for the Checksum
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            true

     *Range*                              true, false

     *Restart Type.
     *

     This parameter is a boolean ('Y'/'N') parameter which is disabled
     by default.  When it is enabled, checksums for all messages are
     calculated before being placed in the send buffer.

     This feature prevents messages from being corrupted while waiting
     in the send buffer.  It also serves as a check against data being
     corrupted during transport.

   *
     'SigNum'

     *This table provides type and value information for the Signum
     shared memory configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When using the shared memory transporter, a process sends an
     operating system signal to the other process when there is new data
     available in the shared memory.  Should that signal conflict with
     an existing signal, this parameter can be used to change it.  This
     is a possibility when using SHM due to the fact that different
     operating systems use different signal numbers.

     The default value of 'SigNum' is 0; therefore, it must be set to
     avoid errors in the cluster log when using the shared memory
     transporter.  Typically, this parameter is set to 10 in the '[shm
     default]' section of the 'config.ini' file.

21.3.3.16 SCI Transport Connections in NDB Cluster
..................................................

'[sci]' sections in the 'config.ini' file explicitly define SCI
(Scalable Coherent Interface) connections between cluster nodes.  Using
SCI transporters in NDB Cluster requires specialized hardware as well as
specially-built MySQL binaries; compiling such binaries is not supported
using an NDB 7.2 or later distribution.

The following parameters are present in 'NDB' source code as well as the
output of 'ndb_config' and
other 'NDB' programs, but are nonfunctional in NDB 7.2 and later.

   *
     'NodeId1'

     *This table provides type and value information for the NodeId1 SCI
     configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     To identify a connection between two nodes it is necessary to
     provide node identifiers for each of them, as 'NodeId1' and
     'NodeId2'.

   *
     'NodeId2'

     *This table provides type and value information for the NodeId2 SCI
     configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      numeric

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     To identify a connection between two nodes it is necessary to
     provide node identifiers for each of them, as 'NodeId1' and
     'NodeId2'.

   *
     'Host1SciId0'

     *This table provides type and value information for the Host1SciId0
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This identifies the SCI node ID on the first Cluster node
     (identified by 'NodeId1').

   * 'Host1SciId1'

     *This table provides type and value information for the Host1SciId1
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     It is possible to set up SCI Transporters for failover between two
     SCI cards which then should use separate networks between the
     nodes.  This identifies the node ID and the second SCI card to be
     used on the first node.

   * 'Host2SciId0'

     *This table provides type and value information for the Host2SciId0
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            [none]

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     This identifies the SCI node ID on the second Cluster node
     (identified by 'NodeId2').

   * 'Host2SciId1'

     *This table provides type and value information for the Host2SciId1
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When using two SCI cards to provide failover, this parameter
     identifies the second SCI card to be used on the second node.

   *
     'HostName1'

     *This table provides type and value information for the HostName1
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     The 'HostName1' and 'HostName2' parameters can be used to specify
     specific network interfaces to be used for a given SCI connection
     between two nodes.  The values used for these parameters can be
     host names or IP addresses.

   *
     'HostName2'

     *This table provides type and value information for the HostName1
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      name or IP address

     *Default*                            [none]

     *Range*                              ...

     *Restart Type.
     *

     The 'HostName1' and 'HostName2' parameters can be used to specify
     specific network interfaces to be used for a given SCI connection
     between two nodes.  The values used for these parameters can be
     host names or IP addresses.

   *
     'SharedBufferSize'

     *This table provides type and value information for the
     SharedBufferSize SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            10M

     *Range*                              64K - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     Each SCI transporter has a shared memory segment used for
     communication between the two nodes.  Setting the size of this
     segment to the default value of 1MB should be sufficient for most
     applications.  Using a smaller value can lead to problems when
     performing many parallel inserts; if the shared buffer is too
     small, this can also result in a crash of the 'ndbd'
     process.

   * 'SendLimit'

     *This table provides type and value information for the SendLimit
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      unsigned

     *Default*                            8K

     *Range*                              128 - 32K

     *Restart Type.
     *

     A small buffer in front of the SCI media stores messages before
     transmitting them over the SCI network.  By default, this is set to
     8KB. Our benchmarks show that performance is best at 64KB but 16KB
     reaches within a few percent of this, and there was little if any
     advantage to increasing it beyond 8KB.

   *
     'SendSignalId'

     *This table provides type and value information for the
     SendSignalId SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            true

     *Range*                              true, false

     *Restart Type.
     *

     To trace a distributed message it is necessary to identify each
     message uniquely.  When this parameter is set to 'Y', message IDs
     are transported over the network.  This feature is disabled by
     default in production builds, and enabled in '-debug' builds.

   *
     'Checksum'

     *This table provides type and value information for the Checksum
     SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      boolean

     *Default*                            false

     *Range*                              true, false

     *Restart Type.
     *

     This parameter is a boolean value, and is disabled by default.
     When 'Checksum' is enabled, checksums are calculated for all
     messages before they are placed in the send buffer.  This feature
     prevents messages from being corrupted while waiting in the send
     buffer.  It also serves as a check against data being corrupted
     during transport.

   *
     'OverloadLimit'

     *This table provides type and value information for the
     OverloadLimit SCI configuration parameter*

     Property                             Value

     *Version (or later)*                 NDB 7.5.0

     *Type or units*                      bytes

     *Default*                            0

     *Range*                              0 - 4294967039 (0xFFFFFEFF)

     *Restart Type.
     *

     When more than this many unsent bytes are in the send buffer, the
     connection is considered overloaded.  See
     mysql-cluster-config-send-buffers, for more information.

21.3.3.17 Configuring NDB Cluster Send Buffer Parameters
........................................................

The 'NDB' kernel employs a unified send buffer whose memory is allocated
dynamically from a pool shared by all transporters.  This means that the
size of the send buffer can be adjusted as necessary.  Configuration of
the unified send buffer can accomplished by setting the following
parameters:

   * TotalSendBufferMemory

     This parameter can be set for all types of NDB Cluster nodes--that
     is, it can be set in the '[ndbd]', '[mgm]', and '[api]' (or
     '[mysql]') sections of the 'config.ini' file.  It represents the
     total amount of memory (in bytes) to be allocated by each node for
     which it is set for use among all configured transporters.  If set,
     its minimum is 256KB; the maximum is 4294967039.

     To be backward-compatible with existing configurations, this
     parameter takes as its default value the sum of the maximum send
     buffer sizes of all configured transporters, plus an additional
     32KB (one page) per transporter.  The maximum depends on the type
     of transporter, as shown in the following table:

     *Transporter types with maximum send buffer sizes*

     Transporter            Maximum Send Buffer Size (bytes)

     TCP                    'SendBufferMemory' (default = 2M)

     SCI                    'SendLimit' (default = 8K) plus 16K

     SHM                    20K

     This enables existing configurations to function in close to the
     same way as they did with NDB Cluster 6.3 and earlier, with the
     same amount of memory and send buffer space available to each
     transporter.  However, memory that is unused by one transporter is
     not available to other transporters.

   * OverloadLimit

     This parameter is used in the 'config.ini' file '[tcp]' section,
     and denotes the amount of unsent data (in bytes) that must be
     present in the send buffer before the connection is considered
     overloaded.  When such an overload condition occurs, transactions
     that affect the overloaded connection fail with NDB API Error 1218
     ('Send Buffers overloaded in NDB kernel') until the overload status
     passes.  The default value is 0, in which case the effective
     overload limit is calculated as 'SendBufferMemory * 0.8' for a
     given connection.  The maximum value for this parameter is 4G.

   * SendBufferMemory

     This value denotes a hard limit for the amount of memory that may
     be used by a single transporter out of the entire pool specified by
     'TotalSendBufferMemory'.  However, the sum of 'SendBufferMemory'
     for all configured transporters may be greater than the
     'TotalSendBufferMemory' that is set for a given node.  This is a
     way to save memory when many nodes are in use, as long as the
     maximum amount of memory is never required by all transporters at
     the same time.

   * ReservedSendBufferMemory

     Removed in NDB 7.5.2.

     Prior to NDB 7.5.2, this data node parameter was present, but was
     not actually used (Bug #77404, Bug #21280428).

You can use the 'ndbinfo.transporters'
table to monitor send buffer memory
usage, and to detect slowdown and overload conditions that can adversely
affect performance.

21.3.4 Using High-Speed Interconnects with NDB Cluster
------------------------------------------------------

Even before design of 'NDBCLUSTER' began in 1996,
it was evident that one of the major problems to be encountered in
building parallel databases would be communication between the nodes in
the network.  For this reason, see 'NDBCLUSTER' was
designed from the very beginning to permit the use of a number of
different data transport mechanisms.  In this Manual, we use the term
_transporter_ for these.

The NDB Cluster codebase provides for four different transporters:

   * _TCP/IP using 100 Mbps or gigabit Ethernet_, as discussed in
     mysql-cluster-tcp-definition.

   * _Direct (machine-to-machine) TCP/IP_; although this transporter
     uses the same TCP/IP protocol as mentioned in the previous item, it
     requires setting up the hardware differently and is configured
     differently as well.  For this reason, it is considered a separate
     transport mechanism for NDB Cluster.  See
     mysql-cluster-tcp-definition-direct, for details.

   * _Shared memory (SHM)_. For more information about SHM, see
     mysql-cluster-shm-definition.

     *Note*:

     SHM is considered experimental only, and is not officially
     supported.

   * _Scalable Coherent Interface (SCI)_. For more information about
     SHM, see mysql-cluster-sci-definition.

     *Note*:

     Using SCI transporters in NDB Cluster requires specialized
     hardware, software, and MySQL binaries not available using an NDB
     7.2 or later distribution.

Most users today employ TCP/IP over Ethernet because it is ubiquitous.
TCP/IP is also by far the best-tested transporter for use with NDB
Cluster.

We are working to make sure that communication with the 'ndbd'
process is made in 'chunks' that are as
large as possible because this benefits all types of data transmission.

21.4 NDB Cluster Programs
=========================

Using and managing an NDB Cluster requires several specialized programs,
which we describe in this chapter.  We discuss the purposes of these
programs in an NDB Cluster, how to use the programs, and what startup
options are available for each of them.

These programs include the NDB Cluster data, management, and SQL node
processes (see 'ndbd', 'ndbmtd',
see 'ndb_mgmd',
and 'mysqld') and the
management client (see 'ndb_mgm').

Information about the program 'ndb_setup.py',
used to start the NDB Cluster
Auto-Installer, is also included in this section.  You should be aware
that mysql-cluster-programs-ndb-setup-py, contains information
about the command-line client only; for information about using the GUI
installer spawned by this program to configure and deploy an NDB
Cluster, see mysql-cluster-install-auto.

For information about using 'mysqld' as an NDB Cluster
process, see mysql-cluster-mysqld.

Other 'NDB' utility, diagnostic, and example
programs are included with the NDB Cluster distribution.  These include
'ndb_restore',
'ndb_show_tables', and
'ndb_config'.  These programs are
also covered in this section.

The final portion of this section contains tables of options that are
common to all the various NDB Cluster programs.

21.4.1 'ndbd' -- The NDB Cluster Data Node Daemon
-------------------------------------------------

'ndbd' is the process that is used
to handle all the data in tables using the NDB Cluster storage engine.
This is the process that empowers a data node to accomplish distributed
transaction handling, node recovery, checkpointing to disk, online
backup, and related tasks.

In an NDB Cluster, a set of 'ndbd'.
processes cooperate in handling data.  These processes can execute on
the same computer (host) or on different computers.  The correspondences
between data nodes and Cluster hosts is completely configurable.

The following table includes command options specific to the NDB Cluster
data node program 'ndbd'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndbd'), see
mysql-cluster-program-options-common.

*Command-line options for the ndbd program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Local bind address
' --bind-address=name                             All MySQL 5.7 based
'                                                 releases

                         Time to wait between
' --connect-delay=# '    attempts to contact a    All MySQL 5.7 based
                         management server, in    releases
                         seconds; 0 means do
                         not wait between
                         attempts

                         Set the number of
' --connect-retries=#    times to retry a         All MySQL 5.7 based
'                        connection before        releases
                         giving up; 0 means 1
                         attempt only (and no
                         retries)

                         Time to wait between
'                        attempts to contact a    All MySQL 5.7 based
--connect-retry-delay=#  management server, in    releases
'                        seconds; 0 means do
                         not wait between
                         attempts

                         Start ndbd as daemon
'--daemon',              (default); override      All MySQL 5.7 based
                         with -nodaemon           releases
' -d '

' --foreground '         Run ndbd in              All MySQL 5.7 based
                         foreground, provided     releases
                         for debugging purposes
                         (implies -nodaemon)

                         Perform initial start
' --initial '            of ndbd, including       All MySQL 5.7 based
                         cleaning the file        releases
                         system.  Consult the
                         documentation before
                         using this option

                         Perform partial
' --initial-start '      initial start            All MySQL 5.7 based
                         (requires                releases
                         -nowait-nodes)

                         Used to install the
' --install[=name] '     data node process as a   All MySQL 5.7 based
                         Windows service.  Does   releases
                         not apply on
                         non-Windows platforms.

                         Control size of log
' --logbuffer-size=# '   buffer.  For use when    ADDED: NDB 7.6.5
                         debugging with many
                         log messages being
                         generated; default is
                         sufficient for normal
                         operations.

                         Don't start ndbd
'--nostart',             immediately; ndbd        All MySQL 5.7 based
                         waits for command to     releases
' -n '                   start from ndb_mgmd

                         Do not start ndbd as
' --nodaemon '           daemon; provided for     All MySQL 5.7 based
                         testing purposes         releases

                         Do not wait for these
' --nowait-nodes=list    data nodes to start      All MySQL 5.7 based
'                        (takes comma-separated   releases
                         list of node IDs).
                         Also requires
                         -ndb-nodeid to be
                         used.

                         Used to remove a data
' --remove[=name] '      node process that was    All MySQL 5.7 based
                         previously installed     releases
                         as a Windows service.
                         Does not apply on
                         non-Windows platforms.

                         Causes the data log to
'--verbose',             write extra debugging    All MySQL 5.7 based
                         information to the       releases
' -v '                   node log.

*Note*:

All of these options also apply to the multi-threaded version of this
program (see 'ndbmtd') and you may
substitute ''ndbmtd'.' for '
'ndbd'.' wherever the latter occurs in this
section.

   * '--bind-address'

     Property                             Value

     *Command-Line Format*                '--bind-address=name'

     *Type*                               string

     *Default Value*                      ''

     Causes 'ndbd' to bind to a
     specific network interface (host name or IP address).  This option
     has no default value.

   * '--daemon', '-d'

     Property                             Value

     *Command-Line Format*                '--daemon'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Instructs 'ndbd' or
     'ndbmtd' to execute as a daemon
     process.  This is the default behavior.  '--nodaemon' can be used
     to prevent the process from running as a daemon.

     This option has no effect when running 'ndbd'
     or 'ndbmtd'
     on Windows platforms.

   * '--nodaemon'

     Property                             Value

     *Command-Line Format*                '--nodaemon'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Prevents 'ndbd' or
     'ndbmtd' from executing as a daemon
     process.  This option overrides the '--daemon' option.  This is
     useful for redirecting output to the screen when debugging the
     binary.

     The default behavior for 'ndbd'.
     and 'ndbmtd' on Windows is to
     run in the foreground, making this option unnecessary on Windows
     platforms, where it has no effect.

   * '--foreground'

     Property                             Value

     *Command-Line Format*                '--foreground'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Causes 'ndbd' or
     'ndbmtd' to execute as a foreground
     process, primarily for debugging purposes.  This option implies the
     '--nodaemon' option.

     This option has no effect when running 'ndbd'
     or 'ndbmtd'
     on Windows platforms.

   *
     '--initial'

     Property                             Value

     *Command-Line Format*                '--initial'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Instructs 'ndbd' to perform an
     initial start.  An initial start erases any files created for
     recovery purposes by earlier instances of 'ndbd'.
     It also re-creates recovery log
     files.  On some operating systems, this process can take a
     substantial amount of time.

     An '--initial' start is to be used _only_ when starting the
     'ndbd' process under very special
     circumstances; this is because this option causes all files to be
     removed from the NDB Cluster file system and all redo log files to
     be re-created.  These circumstances are listed here:

        * When performing a software upgrade which has changed the
          contents of any files.

        * When restarting the node with a new version of 'ndbd'.

        * As a measure of last resort when for some reason the node
          restart or system restart repeatedly fails.  In this case, be
          aware that this node can no longer be used to restore data due
          to the destruction of the data files.

     *Warning*:

     To avoid the possibility of eventual data loss, it is recommended
     that you _not_ use the '--initial' option together with
     'StopOnError = 0'.  Instead, set 'StopOnError' to 0 in 'config.ini'
     only after the cluster has been started, then restart the data
     nodes normally--that is, without the '--initial' option.  See the
     description of the 'StopOnError' parameter for a detailed
     explanation of this issue.  (Bug #24945638)

     Use of this option prevents the 'StartPartialTimeout' and
     'StartPartitionedTimeout' configuration parameters from having any
     effect.

     *Important*:

     This option does _not_ affect either of the following types of
     files:

        * Backup files that have already been created by the affected
          node

        * NDB Cluster Disk Data files (see
          mysql-cluster-disk-data).

     This option also has no effect on recovery of data by a data node
     that is just starting (or restarting) from data nodes that are
     already running.  This recovery of data occurs automatically, and
     requires no user intervention in an NDB Cluster that is running
     normally.

     It is permissible to use this option when starting the cluster for
     the very first time (that is, before any data node files have been
     created); however, it is _not_ necessary to do so.

   *
     '--initial-start'

     Property                             Value

     *Command-Line Format*                '--initial-start'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option is used when performing a partial initial start of the
     cluster.  Each node should be started with this option, as well as
     '--nowait-nodes'.

     Suppose that you have a 4-node cluster whose data nodes have the
     IDs 2, 3, 4, and 5, and you wish to perform a partial initial start
     using only nodes 2, 4, and 5--that is, omitting node 3:

          shell> ndbd --ndb-nodeid=2 --nowait-nodes=3 --initial-start
          shell> ndbd --ndb-nodeid=4 --nowait-nodes=3 --initial-start
          shell> ndbd --ndb-nodeid=5 --nowait-nodes=3 --initial-start

     When using this option, you must also specify the node ID for the
     data node being started with the '--ndb-nodeid' option.

     *Important*:

     Do not confuse this option with the '--nowait-nodes' option for
     'ndb_mgmd', which can be
     used to enable a cluster configured with multiple management
     servers to be started without all management servers being online.

   *
     '--logbuffer-size=#'

     Property                             Value

     *Command-Line Format*                '--logbuffer-size=#'

     *Introduced*                         5.7.21-ndb-7.6.5

     *Type*                               integer

     *Default Value*                      '32768'

     *Minimum Value*                      '2048'

     *Maximum Value*                      '4294967295'

     Sets the size of the data node log buffer.  When debugging with
     high amounts of extra logging, it is possible for the log buffer to
     run out of space if there are too many log messages, in which case
     some log messages can be lost.  This should not occur during normal
     operations.

   *
     '--nowait-nodes=NODE_ID_1[, NODE_ID_2[, ...]]'

     Property                             Value

     *Command-Line Format*                '--nowait-nodes=list'

     *Type*                               string

     *Default Value*                      ''

     This option takes a list of data nodes which for which the cluster
     will not wait for before starting.

     This can be used to start the cluster in a partitioned state.  For
     example, to start the cluster with only half of the data nodes
     (nodes 2, 3, 4, and 5) running in a 4-node cluster, you can start
     each 'ndbd' process with
     '--nowait-nodes=3,5'.  In this case, the cluster starts as soon as
     nodes 2 and 4 connect, and does _not_ wait
     'StartPartitionedTimeout' milliseconds for nodes 3 and 5 to connect
     as it would otherwise.

     If you wanted to start up the same cluster as in the previous
     example without one 'ndbd'.
     (say, for example, that the host machine for node 3 has suffered a
     hardware failure) then start nodes 2, 4, and 5 with
     '--nowait-nodes=3'.  Then the cluster will start as soon as nodes
     2, 4, and 5 connect and will not wait for node 3 to start.

   *
     '--nostart', '-n'

     Property                             Value

     *Command-Line Format*                '--nostart'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Instructs 'ndbd' not to start
     automatically.  When this option is used, see 'ndbd'
     connects to the management server,
     obtains configuration data from it, and initializes communication
     objects.  However, it does not actually start the execution engine
     until specifically requested to do so by the management server.
     This can be accomplished by issuing the proper 'START' command in
     the management client (see
     mysql-cluster-mgm-client-commands).

   *
     '--install[=NAME]'

     Property                             Value

     *Command-Line Format*                '--install[=name]'

     *Platform Specific*                  Windows

     *Type*                               string

     *Default Value*                      'ndbd'

     Causes 'ndbd' to be installed
     as a Windows service.  Optionally, you can specify a name for the
     service; if not set, the service name defaults to 'ndbd'.  Although
     it is preferable to specify other 'ndbd'
     program options in a 'my.ini' or
     'my.cnf' configuration file, it is possible to use together with
     '--install'.  However, in such cases, the '--install' option must
     be specified first, before any other options are given, for the
     Windows service installation to succeed.

     It is generally not advisable to use this option together with the
     '--initial' option, since this causes the data node file system to
     be wiped and rebuilt every time the service is stopped and started.
     Extreme care should also be taken if you intend to use any of the
     other 'ndbd' options that
     affect the starting of data nodes--including '--initial-start',
     '--nostart', and '--nowait-nodes'--together with '--install', and
     you should make absolutely certain you fully understand and allow
     for any possible consequences of doing so.

     The '--install' option has no effect on non-Windows platforms.

   *
     '--remove[=NAME]'

     Property                             Value

     *Command-Line Format*                '--remove[=name]'

     *Platform Specific*                  Windows

     *Type*                               string

     *Default Value*                      'ndbd'

     Causes an 'ndbd' process that
     was previously installed as a Windows service to be removed.
     Optionally, you can specify a name for the service to be
     uninstalled; if not set, the service name defaults to 'ndbd'.

     The '--remove' option has no effect on non-Windows platforms.

   *
     '--verbose', '-v'

     Causes extra debug output to be written to the node log.

     In NDB 7.6.4 and later, you can also use 'NODELOG DEBUG ON' and
     'NODELOG DEBUG OFF' to enable and disable this extra logging while
     the data node is running.

   *
     '--connect-retries=#'

     Property                             Value

     *Command-Line Format*                '--connect-retries=#'

     *Type*                               numeric

     *Default Value*                      '12'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     Set the number of times to retry a connection before giving up; 0
     means 1 attempt only (and no retries).  The default is 12 attempts.
     The time to wait between attempts is controlled by the
     '--connect-retry-delay' option.

   *
     '--connect-delay=#'

     Property                             Value

     *Command-Line Format*                '--connect-delay=#'

     *Deprecated*                         5.6.28-ndb-7.4.9

     *Type*                               numeric

     *Default Value*                      '5'

     *Minimum Value*                      '0'

     *Maximum Value*                      '3600'

     Determines the time to wait between attempts to contact a
     management server when starting (the number of attempts is
     controlled by the '--connect-retries' option).  The default is 5
     seconds.

     This option is deprecated, and is subject to removal in a future
     release of NDB Cluster.  Use '--connect-retry-delay' instead.

   *
     '--connect-retry-delay=#'

     Property                             Value

     *Command-Line Format*                '--connect-retry-delay=#'

     *Type*                               numeric

     *Default Value*                      '5'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     Determines the time to wait between attempts to contact a
     management server when starting (the time between attempts is
     controlled by the '--connect-retries' option).  The default is 5
     seconds.

     This option takes the place of the '--connect-delay' option, which
     is now deprecated and subject to removal in a future release of NDB
     Cluster.

'ndbd' generates a set of log files
which are placed in the directory specified by 'DataDir' in the
'config.ini' configuration file.

These log files are listed below.  NODE_ID is and represents the node's
unique identifier.  For example, 'ndb_2_error.log' is the error log
generated by the data node whose node ID is '2'.

   *
     'ndb_NODE_ID_error.log' is a file containing records of all crashes
     which the referenced 'ndbd'.
     process has encountered.  Each record in this file contains a brief
     error string and a reference to a trace file for this crash.  A
     typical entry in this file might appear as shown here:

          Date/Time: Saturday 30 July 2004 - 00:20:01
          Type of error: error
          Message: Internal program error (failed ndbrequire)
          Fault ID: 2341
          Problem data: DbtupFixAlloc.cpp
          Object of reference: DBTUP (Line: 173)
          ProgramName: NDB Kernel
          ProcessID: 14909
          TraceFile: ndb_2_trace.log.2
          ***EOM***

     Listings of possible 'ndbd'.
     exit codes and messages generated when a data node process shuts
     down prematurely can be found in Data Node Error Messages
     (http://dev.mysql.com/doc/ndb-internals/en/ndb-node-error-messages.html).

     *Important*:

     _The last entry in the error log file is not necessarily the newest
     one_ (nor is it likely to be).  Entries in the error log are _not_
     listed in chronological order; rather, they correspond to the order
     of the trace files as determined in the
     'ndb_NODE_ID_trace.log.next' file (see below).  Error log entries
     are thus overwritten in a cyclical and not sequential fashion.

   *
     'ndb_NODE_ID_trace.log.TRACE_ID' is a trace file describing exactly
     what happened just before the error occurred.  This information is
     useful for analysis by the NDB Cluster development team.

     It is possible to configure the number of these trace files that
     will be created before old files are overwritten.  TRACE_ID is a
     number which is incremented for each successive trace file.

   * 'ndb_NODE_ID_trace.log.next' is the file that keeps track of the
     next trace file number to be assigned.

   * 'ndb_NODE_ID_out.log' is a file containing any data output by the
     'ndbd' process.  This file is
     created only if 'ndbd' is
     started as a daemon, which is the default behavior.

   * 'ndb_NODE_ID.pid' is a file containing the process ID of the
     'ndbd' process when started as a
     daemon.  It also functions as a lock file to avoid the starting of
     nodes with the same identifier.

   * 'ndb_NODE_ID_signal.log' is a file used only in debug versions of
     'ndbd', where it is possible to
     trace all incoming, outgoing, and internal messages with their data
     in the 'ndbd' process.

It is recommended not to use a directory mounted through NFS because in
some environments this can cause problems whereby the lock on the '.pid'
file remains in effect even after the process has terminated.

To start 'ndbd', it may also be
necessary to specify the host name of the management server and the port
on which it is listening.  Optionally, one may also specify the node ID
that the process is to use.

     shell> ndbd --connect-string="nodeid=2;host=ndb_mgmd.mysql.com:1186"

See mysql-cluster-connection-strings, for additional information
about this issue.  See mysql-cluster-program-options-common,
describes other command-line options which can be used with
'ndbd'.  For information about data node
configuration parameters, see mysql-cluster-ndbd-definition.

When 'ndbd' starts, it actually
initiates two processes.  The first of these is called the 'angel
process'; its only job is to discover when the execution process has
been completed, and then to restart the 'ndbd'
process if it is configured to do so.
Thus, if you attempt to kill 'ndbd'.
using the Unix 'kill' command, it is necessary to kill both
processes, beginning with the angel process.  The preferred method of
terminating an 'ndbd' process is to
use the management client and stop the process from there.

The execution process uses one thread for reading, writing, and scanning
data, as well as all other activities.  This thread is implemented
asynchronously so that it can easily handle thousands of concurrent
actions.  In addition, a watch-dog thread supervises the execution
thread to make sure that it does not hang in an endless loop.  A pool of
threads handles file I/O, with each thread able to handle one open file.
Threads can also be used for transporter connections by the transporters
in the 'ndbd' process.  In a
multi-processor system performing a large number of operations
(including updates), the 'ndbd'.
process can consume up to 2 CPUs if permitted to do so.

For a machine with many CPUs it is possible to use several 'ndbd'
processes which belong to different node
groups; however, such a configuration is still considered experimental
and is not supported for MySQL 5.7 in a production setting.  See
mysql-cluster-limitations.

21.4.2 'ndbinfo_select_all' -- Select From ndbinfo Tables
---------------------------------------------------------

See 'ndbinfo_select_all'.
is a client program that selects all rows and columns from one or more
tables in the 'ndbinfo' database

Not all 'ndbinfo' tables available in the 'mysql' client
can be read by this program.  In addition, see 'ndbinfo_select_all'
can show information about
some tables internal to 'ndbinfo' which cannot be accessed using SQL,
including the 'tables' and 'columns' metadata tables.

To select from one or more 'ndbinfo' tables using
'ndbinfo_select_all', it is
necessary to supply the names of the tables when invoking the program as
shown here:

     shell> ndbinfo_select_all TABLE_NAME1  [TABLE_NAME2] [...]

For example:

     shell> ndbinfo_select_all logbuffers logspaces
     == logbuffers ==
     node_id log_type        log_id  log_part        total   used    high
     5       0       0       0       33554432        262144  0
     6       0       0       0       33554432        262144  0
     7       0       0       0       33554432        262144  0
     8       0       0       0       33554432        262144  0
     == logspaces ==
     node_id log_type        log_id  log_part        total   used    high
     5       0       0       0       268435456       0       0
     5       0       0       1       268435456       0       0
     5       0       0       2       268435456       0       0
     5       0       0       3       268435456       0       0
     6       0       0       0       268435456       0       0
     6       0       0       1       268435456       0       0
     6       0       0       2       268435456       0       0
     6       0       0       3       268435456       0       0
     7       0       0       0       268435456       0       0
     7       0       0       1       268435456       0       0
     7       0       0       2       268435456       0       0
     7       0       0       3       268435456       0       0
     8       0       0       0       268435456       0       0
     8       0       0       1       268435456       0       0
     8       0       0       2       268435456       0       0
     8       0       0       3       268435456       0       0
     shell>

The following table includes options that are specific to
'ndbinfo_select_all'.
Additional descriptions follow the table.  For options common to most
NDB Cluster programs (including 'ndbinfo_select_all'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndbinfo_select_all program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Set the delay in
' --delay=# '            seconds between loops.   All MySQL 5.7 based
                         Default is 5.            releases

                         Set the number of
'--loops=#',             times to perform the     All MySQL 5.7 based
                         select.  Default is 1.   releases
' -l '

'--database=db_name',    Name of the database     All MySQL 5.7 based
                         where the table          releases
' -d '                   located.

                         Set the degree of
'--parallelism=#',       parallelism.             All MySQL 5.7 based
                                                  releases
' -p '

   *
     '--delay=seconds'

     Property                             Value

     *Command-Line Format*                '--delay=#'

     *Type*                               numeric

     *Default Value*                      '5'

     *Minimum Value*                      '0'

     *Maximum Value*                      'MAX_INT'

     This option sets the number of seconds to wait between executing
     loops.  Has no effect if '--loops' is set to 0 or 1.

   *
     '--loops=number', '-l NUMBER'

     Property                             Value

     *Command-Line Format*                '--loops=#'

     *Type*                               numeric

     *Default Value*                      '1'

     *Minimum Value*                      '0'

     *Maximum Value*                      'MAX_INT'

     This option sets the number of times to execute the select.  Use
     '--delay' to set the time between loops.

21.4.3 'ndbmtd' -- The NDB Cluster Data Node Daemon (Multi-Threaded)
--------------------------------------------------------------------

'ndbmtd' is a multi-threaded
version of 'ndbd', the process that
is used to handle all the data in tables using the 'NDBCLUSTER'
storage engine.  'ndbmtd'
is intended for use on host computers
having multiple CPU cores.  Except where otherwise noted, see
'ndbmtd' functions in the same way as
'ndbd'.; therefore, in this section,
we concentrate on the ways in which 'ndbmtd'
differs from 'ndbd',
and you should consult
mysql-cluster-programs-ndbd, for additional information about running
NDB Cluster data nodes that apply to both the single-threaded and
multi-threaded versions of the data node process.

Command-line options and configuration parameters used with
'ndbd' also apply to 'ndbmtd'.
For more information about these options
and parameters, see mysql-cluster-programs-ndbd, and
mysql-cluster-ndbd-definition, respectively.

'ndbmtd' is also file
system-compatible with 'ndbd'.  In
other words, a data node running 'ndbd'
can be stopped, the binary replaced with
'ndbmtd', and then restarted
without any loss of data.  (However, when doing this, you must make sure
that 'MaxNoOfExecutionThreads' is set to an apppriate value before
restarting the node if you wish for 'ndbmtd'
to run in multi-threaded fashion.)
Similarly, an 'ndbmtd' binary can
be replaced with 'ndbd' simply by
stopping the node and then starting 'ndbd'
in place of the multi-threaded binary.  It
is not necessary when switching between the two to start the data node
binary using '--initial'.

Using 'ndbmtd' differs from using
'ndbd' in two key respects:

  1. Because 'ndbmtd' runs by
     default in single-threaded mode (that is, it behaves like
     'ndbd'), you must configure it to use
     multiple threads.  This can be done by setting an appropriate value
     in the 'config.ini' file for the 'MaxNoOfExecutionThreads'
     configuration parameter or the 'ThreadConfig' configuration
     parameter.  Using 'MaxNoOfExecutionThreads' is simpler, but
     'ThreadConfig' offers more flexibility.  For more information about
     these configuration parameters and their use, see
     mysql-cluster-ndbd-definition-ndbmtd-parameters.

  2. Trace files are generated by critical errors in 'ndbmtd'
     processes in a somewhat different
     fashion from how these are generated by 'ndbd'
     failures.  These differences are
     discussed in more detail in the next few paragraphs.

Like 'ndbd', 'ndbmtd'
generates a set of log files which are
placed in the directory specified by 'DataDir' in the 'config.ini'
configuration file.  Except for trace files, these are generated in the
same way and have the same names as those generated by 'ndbd'.

In the event of a critical error, see 'ndbmtd'
generates trace files describing what
happened just prior to the error' occurrence.  These files, which can be
found in the data node's 'DataDir', are useful for analysis of problems
by the NDB Cluster Development and Support teams.  One trace file is
generated for each 'ndbmtd'.
thread.  The names of these files have the following pattern:

     ndb_NODE_ID_trace.log.TRACE_ID_tTHREAD_ID,

In this pattern, NODE_ID stands for the data node's unique node ID in
the cluster, TRACE_ID is a trace sequence number, and THREAD_ID is the
thread ID. For example, in the event of the failure of an
'ndbmtd' process running as an NDB
Cluster data node having the node ID 3 and with
'MaxNoOfExecutionThreads' equal to 4, four trace files are generated in
the data node's data directory.  If the is the first time this node has
failed, then these files are named 'ndb_3_trace.log.1_t1',
'ndb_3_trace.log.1_t2', 'ndb_3_trace.log.1_t3', and
'ndb_3_trace.log.1_t4'.  Internally, these trace files follow the same
format as 'ndbd' trace files.

The 'ndbd' exit codes and messages
that are generated when a data node process shuts down prematurely are
also used by 'ndbmtd'.  See Data
Node Error Messages
(http://dev.mysql.com/doc/ndb-internals/en/ndb-node-error-messages.html),
for a listing of these.

*Note*:

It is possible to use 'ndbd' and
'ndbmtd' concurrently on different
data nodes in the same NDB Cluster.  However, such configurations have
not been tested extensively; thus, we cannot recommend doing so in a
production setting at this time.

21.4.4 'ndb_mgmd' -- The NDB Cluster Management Server Daemon
-------------------------------------------------------------

The management server is the process that reads the cluster
configuration file and distributes this information to all nodes in the
cluster that request it.  It also maintains a log of cluster activities.
Management clients can connect to the management server and check the
cluster's status.

The following table includes options that are specific to the NDB
Cluster management server program 'ndb_mgmd'.
Additional descriptions follow the
table.  For options common to most NDB Cluster programs (including
'ndb_mgmd'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_mgmd program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Specify the cluster
'--config-file=file'     configuration file; in   All MySQL 5.7 based
(>=),                    NDB-6.4.0 and later,     releases
                         needs -reload or
'-f' (>=)                -initial to override
                         configuration cache if
                         present

                         Specify the cluster
'--configdir=directory', management server's      All MySQL 5.7 based
                         configuration cache      releases
'--config-dir=directory' directory
(>=7.0.8)

' --bind-address=host    Local bind address       All MySQL 5.7 based
'                                                 releases

                         Print full
'--print-full-config',   configuration and exit   All MySQL 5.7 based
                                                  releases
' -P '

'--daemon',              Run ndb_mgmd in daemon   All MySQL 5.7 based
                         mode (default)           releases
' -d '

' --nodaemon '           Do not run ndb_mgmd as   All MySQL 5.7 based
                         a daemon                 releases

                         Run ndb_mgmd in
' --interactive '        interactive mode (not    All MySQL 5.7 based
                         officially supported     releases
                         in production; for
                         testing purposes only)

                         A name to use when
' --log-name=name '      writing messages         All MySQL 5.7 based
                         applying to this node    releases
                         in the cluster log.

                         Do not provide any
' --no-nodeid-checks '   node id checks           All MySQL 5.7 based
                                                  releases

                         Read cluster
' --mycnf '              configuration data       All MySQL 5.7 based
                         from the my.cnf file     releases

                         Causes the management
' --reload '             server to compare the    All MySQL 5.7 based
                         configuration file       releases
                         with its configuration
                         cache

                         Causes the management
' --initial '            server reload its        All MySQL 5.7 based
                         configuration data       releases
                         from the configuration
                         file, bypassing the
                         configuration cache

                         Do not wait for these
' --nowait-nodes=list    management nodes when    All MySQL 5.7 based
'                        starting this            releases
                         management server.
                         Also requires
                         -ndb-nodeid to be
                         used.

                         Enable the management
'                        server configuration     All MySQL 5.7 based
--config-cache[=TRUE|FALSE]cache; TRUE by         releases
'                        default.

                         Used to install the
' --install[=name] '     management server        All MySQL 5.7 based
                         process as a Windows     releases
                         service.  Does not
                         apply on non-Windows
                         platforms.

                         Used to remove a
' --remove[=name] '      management server        All MySQL 5.7 based
                         process that was         releases
                         previously installed
                         as a Windows service,
                         optionally specifying
                         the name of the
                         service to be removed.
                         Does not apply on
                         non-Windows platforms.

   *
     '--bind-address=HOST'

     Property                             Value

     *Command-Line Format*                '--bind-address=host'

     *Type*                               string

     *Default Value*                      '[none]'

     Causes the management server to bind to a specific network
     interface (host name or IP address).  This option has no default
     value.

   *
     '--no-nodeid-checks'

     Property                             Value

     *Command-Line Format*                '--no-nodeid-checks'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Do not perform any checks of node IDs.

   *
     '--configdir=DIR_NAME'

     Property                             Value

     *Command-Line Format*                '--configdir=directory'
                                          '--config-dir=directory'

     *Type*                               file name

     *Default Value*                      '$INSTALLDIR/mysql-cluster'

     Specifies the cluster management server's configuration cache
     directory.  '--config-dir' is an alias for this option.

   *
     '--config-cache'

     Property                             Value

     *Command-Line Format*                '--config-cache[=TRUE|FALSE]'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     This option, whose default value is '1' (or 'TRUE', or 'ON'), can
     be used to disable the management server's configuration cache, so
     that it reads its configuration from 'config.ini' every time it
     starts (see mysql-cluster-config-file).  You can do this by
     starting the 'ndb_mgmd'.
     process with any one of the following options:

        * '--config-cache=0'

        * '--config-cache=FALSE'

        * '--config-cache=OFF'

        * '--skip-config-cache'

     Using one of the options just listed is effective only if the
     management server has no stored configuration at the time it is
     started.  If the management server finds any configuration cache
     files, then the '--config-cache' option or the
     '--skip-config-cache' option is ignored.  Therefore, to disable
     configuration caching, the option should be used the _first_ time
     that the management server is started.  Otherwise--that is, if you
     wish to disable configuration caching for a management server that
     has _already_ created a configuration cache--you must stop the
     management server, delete any existing configuration cache files
     manually, then restart the management server with
     '--skip-config-cache' (or with '--config-cache' set equal to 0,
     'OFF', or 'FALSE').

     Configuration cache files are normally created in a directory named
     'mysql-cluster' under the installation directory (unless this
     location has been overridden using the '--configdir' option).  Each
     time the management server updates its configuration data, it
     writes a new cache file.  The files are named sequentially in order
     of creation using the following format:

          ndb_NODE-ID_config.bin.SEQ-NUMBER

     NODE-ID is the management server's node ID; SEQ-NUMBER is a
     sequence number, beginning with 1.  For example, if the management
     server's node ID is 5, then the first three configuration cache
     files would, when they are created, be named 'ndb_5_config.bin.1',
     'ndb_5_config.bin.2', and 'ndb_5_config.bin.3'.

     If your intent is to purge or reload the configuration cache
     without actually disabling caching, you should start
     'ndb_mgmd' with one of the
     options '--reload' or '--initial' instead of '--skip-config-cache'.

     To re-enable the configuration cache, simply restart the management
     server, but without the '--config-cache' or '--skip-config-cache'
     option that was used previously to disable the configuration cache.

     'ndb_mgmd' does not check
     for the configuration directory ('--configdir') or attempts to
     create one when '--skip-config-cache' is used.  (Bug #13428853)

   *
     '--config-file=FILENAME', '-f FILENAME'

     Property                             Value

     *Command-Line Format*                '--config-file=file'

     *Type*                               file name

     *Default Value*                      '[none]'

     Instructs the management server as to which file it should use for
     its configuration file.  By default, the management server looks
     for a file named 'config.ini' in the same directory as the
     'ndb_mgmd' executable; otherwise
     the file name and location must be specified explicitly.

     This option has no default value, and is ignored unless the
     management server is forced to read the configuration file, either
     because 'ndb_mgmd' was
     started with the '--reload' or '--initial' option, or because the
     management server could not find any configuration cache.  This
     option is also read if 'ndb_mgmd'
     was started with
     '--config-cache=OFF'.  See mysql-cluster-config-file, for
     more information.

   *
     '--mycnf'

     Property                             Value

     *Command-Line Format*                '--mycnf'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Read configuration data from the 'my.cnf' file.

   *
     '--daemon', '-d'

     Property                             Value

     *Command-Line Format*                '--daemon'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Instructs 'ndb_mgmd' to
     start as a daemon process.  This is the default behavior.

     This option has no effect when running 'ndb_mgmd'
     on Windows platforms.

   *
     '--interactive'

     Property                             Value

     *Command-Line Format*                '--interactive'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Starts 'ndb_mgmd' in
     interactive mode; that is, an 'ndb_mgm'
     client session is started as soon
     as the management server is running.  This option does not start
     any other NDB Cluster nodes.

   *
     '--initial'

     Property                             Value

     *Command-Line Format*                '--initial'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Configuration data is cached internally, rather than being read
     from the cluster global configuration file each time the management
     server is started (see mysql-cluster-config-file).  Using
     the '--initial' option overrides this behavior, by forcing the
     management server to delete any existing cache files, and then to
     re-read the configuration data from the cluster configuration file
     and to build a new cache.

     This differs in two ways from the '--reload' option.  First,
     '--reload' forces the server to check the configuration file
     against the cache and reload its data only if the contents of the
     file are different from the cache.  Second, '--reload' does not
     delete any existing cache files.

     If 'ndb_mgmd' is invoked
     with '--initial' but cannot find a global configuration file, the
     management server cannot start.

     When a management server starts, it checks for another management
     server in the same NDB Cluster and tries to use the other
     management server's configuration data; see 'ndb_mgmd'
     ignores '--initial' unless it is
     the only management server running.  This behavior also has
     implications when performing a rolling restart of an NDB Cluster
     with multiple management nodes.  See
     mysql-cluster-rolling-restart, for more information.

     When used together with the '--config-file' option, the cache is
     cleared only if the configuration file is actually found.

   *
     '--log-name=NAME'

     Property                             Value

     *Command-Line Format*                '--log-name=name'

     *Type*                               string

     *Default Value*                      'MgmtSrvr'

     Provides a name to be used for this node in the cluster log.

   *
     '--nodaemon'

     Property                             Value

     *Command-Line Format*                '--nodaemon'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Instructs 'ndb_mgmd' not to
     start as a daemon process.

     The default behavior for 'ndb_mgmd'
     on Windows is to run in the
     foreground, making this option unnecessary on Windows platforms.

   *
     '--print-full-config', '-P'

     Property                             Value

     *Command-Line Format*                '--print-full-config'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Shows extended information regarding the configuration of the
     cluster.  With this option on the command line the
     'ndb_mgmd' process prints
     information about the cluster setup including an extensive list of
     the cluster configuration sections as well as parameters and their
     values.  Normally used together with the '--config-file' ('-f')
     option.

   *
     '--reload'

     Property                             Value

     *Command-Line Format*                '--reload'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     NDB Cluster configuration data is stored internally rather than
     being read from the cluster global configuration file each time the
     management server is started (see
     mysql-cluster-config-file).  Using this option forces the
     management server to check its internal data store against the
     cluster configuration file and to reload the configuration if it
     finds that the configuration file does not match the cache.
     Existing configuration cache files are preserved, but not used.

     This differs in two ways from the '--initial' option.  First,
     '--initial' causes all cache files to be deleted.  Second,
     '--initial' forces the management server to re-read the global
     configuration file and construct a new cache.

     If the management server cannot find a global configuration file,
     then the '--reload' option is ignored.

     When a management server starts, it checks for another management
     server in the same NDB Cluster and tries to use the other
     management server's configuration data; see 'ndb_mgmd'
     ignores '--reload' unless it is
     the only management server running.  This behavior also has
     implications when performing a rolling restart of an NDB Cluster
     with multiple management nodes.  See
     mysql-cluster-rolling-restart, for more information.

   *
     '--nowait-nodes'

     Property                             Value

     *Command-Line Format*                '--nowait-nodes=list'

     *Type*                               numeric

     *Default Value*                      ''

     *Minimum Value*                      '1'

     *Maximum Value*                      '255'

     When starting an NDB Cluster is configured with two management
     nodes, each management server normally checks to see whether the
     other 'ndb_mgmd' is also
     operational and whether the other management server's configuration
     is identical to its own.  However, it is sometimes desirable to
     start the cluster with only one management node (and perhaps to
     allow the other 'ndb_mgmd'.
     to be started later).  This option causes the management node to
     bypass any checks for any other management nodes whose node IDs are
     passed to this option, permitting the cluster to start as though
     configured to use only the management node that was started.

     For purposes of illustration, consider the following portion of a
     'config.ini' file (where we have omitted most of the configuration
     parameters that are not relevant to this example):

          [ndbd]
          NodeId = 1
          HostName = 198.51.100.101

          [ndbd]
          NodeId = 2
          HostName = 198.51.100.102

          [ndbd]
          NodeId = 3
          HostName = 198.51.100.103

          [ndbd]
          NodeId = 4
          HostName = 198.51.100.104

          [ndb_mgmd]
          NodeId = 10
          HostName = 198.51.100.150

          [ndb_mgmd]
          NodeId = 11
          HostName = 198.51.100.151

          [api]
          NodeId = 20
          HostName = 198.51.100.200

          [api]
          NodeId = 21
          HostName = 198.51.100.201

     Assume that you wish to start this cluster using only the
     management server having node ID '10' and running on the host
     having the IP address 198.51.100.150.  (Suppose, for example, that
     the host computer on which you intend to the other management
     server is temporarily unavailable due to a hardware failure, and
     you are waiting for it to be repaired.)  To start the cluster in
     this way, use a command line on the machine at 198.51.100.150 to
     enter the following command:

          shell> ndb_mgmd --ndb-nodeid=10 --nowait-nodes=11

     As shown in the preceding example, when using '--nowait-nodes', you
     must also use the '--ndb-nodeid' option to specify the node ID of
     this 'ndb_mgmd' process.

     You can then start each of the cluster's data nodes in the usual
     way.  If you wish to start and use the second management server in
     addition to the first management server at a later time without
     restarting the data nodes, you must start each data node with a
     connection string that references both management servers, like
     this:

          shell> ndbd -c 198.51.100.150,198.51.100.151

     The same is true with regard to the connection string used with any
     'mysqld' processes that you wish to start as NDB
     Cluster SQL nodes connected to this cluster.  See
     mysql-cluster-connection-strings, for more information.

     When used with 'ndb_mgmd',
     this option affects the behavior of the management node with regard
     to other management nodes only.  Do not confuse it with the
     '--nowait-nodes' option used with 'ndbd'
     or 'ndbmtd'
     to permit a cluster to start with
     fewer than its full complement of data nodes; when used with data
     nodes, this option affects their behavior only with regard to other
     data nodes.

     Multiple management node IDs may be passed to this option as a
     comma-separated list.  Each node ID must be no less than 1 and no
     greater than 255.  In practice, it is quite rare to use more than
     two management servers for the same NDB Cluster (or to have any
     need for doing so); in most cases you need to pass to this option
     only the single node ID for the one management server that you do
     not wish to use when starting the cluster.

     *Note*:

     When you later start the 'missing' management server, its
     configuration must match that of the management server that is
     already in use by the cluster.  Otherwise, it fails the
     configuration check performed by the existing management server,
     and does not start.

It is not strictly necessary to specify a connection string when
starting the management server.  However, if you are using more than one
management server, a connection string should be provided and each node
in the cluster should specify its node ID explicitly.

See mysql-cluster-connection-strings, for information about
using connection strings.  See mysql-cluster-programs-ndb-mgmd,
describes other options for 'ndb_mgmd'.

The following files are created or used by 'ndb_mgmd'
in its starting directory, and are
placed in the 'DataDir' as specified in the 'config.ini' configuration
file.  In the list that follows, NODE_ID is the unique node identifier.

   *
     'config.ini' is the configuration file for the cluster as a whole.
     This file is created by the user and read by the management server.
     See mysql-cluster-configuration, discusses how to set up this
     file.

   * 'ndb_NODE_ID_cluster.log' is the cluster events log file.  Examples
     of such events include checkpoint startup and completion, node
     startup events, node failures, and levels of memory usage.  A
     complete listing of cluster events with descriptions may be found
     in mysql-cluster-management.

     By default, when the size of the cluster log reaches one million
     bytes, the file is renamed to 'ndb_NODE_ID_cluster.log.SEQ_ID',
     where SEQ_ID is the sequence number of the cluster log file.  (For
     example: If files with the sequence numbers 1, 2, and 3 already
     exist, the next log file is named using the number '4'.)  You can
     change the size and number of files, and other characteristics of
     the cluster log, using the 'LogDestination' configuration
     parameter.

   * 'ndb_NODE_ID_out.log' is the file used for 'stdout' and 'stderr'
     when running the management server as a daemon.

   * 'ndb_NODE_ID.pid' is the process ID file used when running the
     management server as a daemon.

   *
     '--install[=NAME]'

     Property                             Value

     *Command-Line Format*                '--install[=name]'

     *Platform Specific*                  Windows

     *Type*                               string

     *Default Value*                      'ndb_mgmd'

     Causes 'ndb_mgmd' to be
     installed as a Windows service.  Optionally, you can specify a name
     for the service; if not set, the service name defaults to
     'ndb_mgmd'.  Although it is preferable to specify other
     'ndb_mgmd' program options in a
     'my.ini' or 'my.cnf' configuration file, it is possible to use them
     together with '--install'.  However, in such cases, the '--install'
     option must be specified first, before any other options are given,
     for the Windows service installation to succeed.

     It is generally not advisable to use this option together with the
     '--initial' option, since this causes the configuration cache to be
     wiped and rebuilt every time the service is stopped and started.
     Care should also be taken if you intend to use any other
     'ndb_mgmd' options that affect
     the starting of the management server, and you should make
     absolutely certain you fully understand and allow for any possible
     consequences of doing so.

     The '--install' option has no effect on non-Windows platforms.

   *
     '--remove[=NAME]'

     Property                             Value

     *Command-Line Format*                '--remove[=name]'

     *Platform Specific*                  Windows

     *Type*                               string

     *Default Value*                      'ndb_mgmd'

     Causes an 'ndb_mgmd'.
     process that was previously installed as a Windows service to be
     removed.  Optionally, you can specify a name for the service to be
     uninstalled; if not set, the service name defaults to 'ndb_mgmd'.

     The '--remove' option has no effect on non-Windows platforms.

21.4.5 'ndb_mgm' -- The NDB Cluster Management Client
-----------------------------------------------------

The 'ndb_mgm' management client
process is actually not needed to run the cluster.  Its value lies in
providing a set of commands for checking the cluster's status, starting
backups, and performing other administrative functions.  The management
client accesses the management server using a C API. Advanced users can
also employ this API for programming dedicated management processes to
perform tasks similar to those performed by 'ndb_mgm'.

To start the management client, it is necessary to supply the host name
and port number of the management server:

     shell> ndb_mgm [HOST_NAME [PORT_NUM]]

For example:

     shell> ndb_mgm ndb_mgmd.mysql.com 1186

The default host name and port number are 'localhost' and 1186,
respectively.

The following table includes options that are specific to the NDB
Cluster management client program 'ndb_mgm'.
Additional descriptions follow the
table.  For options common to most NDB Cluster programs (including
'ndb_mgm'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_mgm program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Set the number of
'--try-reconnect=#',     times to retry a         All MySQL 5.7 based
                         connection before        releases
' -t '                   giving up; synonym for
                         -connect-retries

                         Execute command and
'--execute=name',        exit                     All MySQL 5.7 based
                                                  releases
' -e '

   *
     '--connect-retries=#'

     Property                             Value

     *Command-Line Format*                '--connect-retries=#'

     *Type*                               numeric

     *Default Value*                      '3'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     This option specifies the number of times following the first
     attempt to retry a connection before giving up (the client always
     tries the connection at least once).  The length of time to wait
     per attempt is set using '--connect-retry-delay'.

     This option is synonymous with the '--try-reconnect' option, which
     is now deprecated.

     The default for this option this option differs from its default
     when used with other 'NDB' programs.  See
     mysql-cluster-program-options-common, for more information.

   *
     '--execute=command', '-e command'

     Property                             Value

     *Command-Line Format*                '--execute=name'

     This option can be used to send a command to the NDB Cluster
     management client from the system shell.  For example, either of
     the following is equivalent to executing 'SHOW' in the management
     client:

          shell> ndb_mgm -e "SHOW"

          shell> ndb_mgm --execute="SHOW"

     This is analogous to how the '--execute' or '-e' option works with
     the 'mysql' command-line client.  See
     command-line-options.

     *Note*:

     If the management client command to be passed using this option
     contains any space characters, then the command _must_ be enclosed
     in quotation marks.  Either single or double quotation marks may be
     used.  If the management client command contains no space
     characters, the quotation marks are optional.

   * '--try-reconnect=NUMBER'

     Property                             Value

     *Command-Line Format*                '--try-reconnect=#'

     *Deprecated*                         5.6.28-ndb-7.4.9

     *Type* (>= 5.7.10-ndb-7.5.0)         numeric

     *Type*                               integer

     *Default Value* (>=                  '12'
     5.7.10-ndb-7.5.0)

     *Default Value*                      '3'

     *Minimum Value* (>=                  '0'
     5.7.10-ndb-7.5.0)

     *Minimum Value*                      '0'

     *Maximum Value* (>=                  '4294967295'
     5.7.10-ndb-7.5.0)

     *Maximum Value*                      '4294967295'

     If the connection to the management server is broken, the node
     tries to reconnect to it every 5 seconds until it succeeds.  By
     using this option, it is possible to limit the number of attempts
     to NUMBER before giving up and reporting an error instead.

     This option is deprecated and subject to removal in a future
     release.  Use '--connect-retries', instead.

Additional information about using 'ndb_mgm'
can be found in
mysql-cluster-mgm-client-commands.

21.4.6 'ndb_blob_tool' -- Check and Repair BLOB and TEXT columns of NDB Cluster Tables
--------------------------------------------------------------------------------------

This tool can be used to check for and remove orphaned BLOB column parts
from 'NDB' tables, as well as to generate a file
listing any orphaned parts.  It is sometimes useful in diagnosing and
repairing corrupted or damaged 'NDB' tables containing 'BLOB'
or 'TEXT' columns.

The basic syntax for 'ndb_blob_tool'
is shown here:

     ndb_blob_tool [OPTIONS] TABLE [COLUMN, ...]

Unless you use the '--help' option, you must specify an action to be
performed by including one or more of the options '--check-orphans',
'--delete-orphans', or '--dump-file'.  These options cause
'ndb_blob_tool' to check for
orphaned BLOB parts, remove any orphaned BLOB parts, and generate a dump
file listing orphaned BLOB parts, respectively, and are described in
more detail later in this section.

You must also specify the name of a table when invoking
'ndb_blob_tool'.  In addition, you
can optionally follow the table name with the (comma-separated) names of
one or more 'BLOB' or 'TEXT' columns from that
table.  If no columns are listed, the tool works on all of the table's
'BLOB' and 'TEXT' columns.  If you need to
specify a database, use the '--database' ('-d') option.

The '--verbose' option provides additional information in the output
about the tool's progress.

The following table includes options that are specific to
'ndb_blob_tool'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndb_blob_tool'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_blob_tool program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Check for orphan blob
' --check-orphans '      parts                    All MySQL 5.7 based
                                                  releases

                         Database to find the
'--database=db_name',    table in.                All MySQL 5.7 based
                                                  releases
' -d '

' --delete-orphans '     Delete orphan blob       All MySQL 5.7 based
                         parts                    releases

                         Write orphan keys to
' --dump-file=file '     specified file           All MySQL 5.7 based
                                                  releases

                         Verbose output
'--verbose',                                      All MySQL 5.7 based
                                                  releases
' -v '

   *
     '--check-orphans'

     Property                             Value

     *Command-Line Format*                '--check-orphans'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Check for orphaned BLOB parts in NDB Cluster tables.

   *
     '--database=DB_NAME', '-d'

     Property                             Value

     *Command-Line Format*                '--database=db_name'

     *Type*                               string

     *Default Value*                      '[none]'

     Specify the database to find the table in.

   *
     '--delete-orphans'

     Property                             Value

     *Command-Line Format*                '--delete-orphans'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Remove orphaned BLOB parts from NDB Cluster tables.

   *
     '--dump-file=FILE'

     Property                             Value

     *Command-Line Format*                '--dump-file=file'

     *Type*                               file name

     *Default Value*                      '[none]'

     Writes a list of orphaned BLOB column parts to FILE.  The
     information written to the file includes the table key and BLOB
     part number for each orphaned BLOB part.

   *
     '--verbose'

     Property                             Value

     *Command-Line Format*                '--verbose'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Provide extra information in the tool's output regarding its
     progress.

*Example*

First we create an 'NDB' table in the 'test' database, using the
'CREATE TABLE' statement shown here:

     USE test;

     CREATE TABLE btest (
         c0 BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
         c1 TEXT,
         c2 BLOB
     )   ENGINE=NDB;

Then we insert a few rows into this table, using a series of statements
similar to this one:

     INSERT INTO btest VALUES (NULL, 'x', REPEAT('x', 1000));

When run with '--check-orphans' against this table, see
'ndb_blob_tool' generates the
following output:

     shell> ndb_blob_tool --check-orphans --verbose -d test btest
     connected
     processing 2 blobs
     processing blob #0 c1 NDB$BLOB_19_1
     NDB$BLOB_19_1: nextResult: res=1
     total parts: 0
     orphan parts: 0
     processing blob #1 c2 NDB$BLOB_19_2
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=0
     NDB$BLOB_19_2: nextResult: res=1
     total parts: 10
     orphan parts: 0
     disconnected

     NDBT_ProgramExit: 0 - OK

The tool reports that there are no 'NDB' BLOB column parts associated
with column 'c1', even though 'c1' is a 'TEXT' column.
This is due to the fact that, in an 'NDB' table,
only the first 256 bytes of a 'BLOB' or 'TEXT'.
column value are stored inline, and only the excess, if any, is stored
separately; thus, if there are no values using more than 256 bytes in a
given column of one of these types, no 'BLOB' column parts are created
by 'NDB' for this column.  See storage-requirements, for more
information.

21.4.7 'ndb_config' -- Extract NDB Cluster Configuration Information
--------------------------------------------------------------------

This tool extracts current configuration information for data nodes, SQL
nodes, and API nodes from one of a number of sources: an NDB Cluster
management node, or its 'config.ini' or 'my.cnf' file.  By default, the
management node is the source for the configuration data; to override
the default, execute ndb_config with the '--config-file' or '--mycnf'
option.  It is also possible to use a data node as the source by
specifying its node ID with '--config_from_node=NODE_ID'.

'ndb_config' can also provide
an offline dump of all configuration parameters which can be used, along
with their default, maximum, and minimum values and other information.
The dump can be produced in either text or XML format; for more
information, see the discussion of the '--configinfo' and '--xml'
options later in this section).

You can filter the results by section ('DB', 'SYSTEM', or 'CONNECTIONS')
using one of the options '--nodes', '--system', or '--connections'.

The following table includes options that are specific to
'ndb_config'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndb_config'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_config program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Set the path to
'                        config.ini file          All MySQL 5.7 based
--config-file=file_name                           releases
'

' --config_from_node=#   Obtain configuration     All MySQL 5.7 based
'                        data from the node       releases
                         having this ID (must
                         be a data node).

                         Dumps information
' --configinfo '         about all NDB            All MySQL 5.7 based
                         configuration            releases
                         parameters in text
                         format with default,
                         maximum, and minimum
                         values.  Use with -xml
                         to obtain XML output.

                         Print connections
' --connections '        information ([tcp],      All MySQL 5.7 based
                         [tcp default], [sci],    releases
                         [sci default], [shm],
                         or [shm default]
                         sections of cluster
                         configuration file)
                         only.  Cannot be used
                         with -system or
                         -nodes.

                         Print only
' --diff-default '       configuration            ADDED: NDB 7.5.7, NDB
                         parameters that have     7.6.3
                         non-default values

                         Field separator
'--fields=string',                                All MySQL 5.7 based
                                                  releases
' -f '

' --host=name '          Specify host             All MySQL 5.7 based
                                                  releases

                         Read configuration
' --mycnf '              data from my.cnf file    All MySQL 5.7 based
                                                  releases

                         Get configuration of
'--nodeid',              node with this ID        All MySQL 5.7 based
                                                  releases
' --id '

' --nodes '              Print node information   All MySQL 5.7 based
                         ([ndbd] or [ndbd         releases
                         default] section of
                         cluster configuration
                         file) only.  Cannot be
                         used with -system or
                         -connections.

                         Short form for
' -c '                   -ndb-connectstring       All MySQL 5.7 based
                                                  releases

                         One or more query
'--query=string',        options (attributes)     All MySQL 5.7 based
                                                  releases
' -q '

'--query-all',           Dumps all parameters     ADDED: NDB 7.4.16, NDB
                         and values to a single   7.5.7
' -a '                   comma-delimited
                         string.

                         Row separator
'--rows=string',                                  All MySQL 5.7 based
                                                  releases
' -r '

' --system '             Print SYSTEM section     All MySQL 5.7 based
                         information only (see    releases
                         ndb_config -configinfo
                         output).  Cannot be
                         used with -nodes or
                         -connections.

                         Specify node type
' --type=name '                                   All MySQL 5.7 based
                                                  releases

                         Use -xml with
' --configinfo --xml '   -configinfo to obtain    All MySQL 5.7 based
                         a dump of all NDB        releases
                         configuration
                         parameters in XML
                         format with default,
                         maximum, and minimum
                         values.

   *
     '--configinfo'

     The '--configinfo' option causes 'ndb_config'
     to dump a list of each NDB
     Cluster configuration parameter supported by the NDB Cluster
     distribution of which 'ndb_config'
     is a part, including the
     following information:

        * A brief description of each parameter's purpose, effects, and
          usage

        * The section of the 'config.ini' file where the parameter may
          be used

        * The parameter's data type or unit of measurement

        * Where applicable, the parameter's default, minimum, and
          maximum values

        * NDB Cluster release version and build information

     By default, this output is in text format.  Part of this output is
     shown here:

          shell> ndb_config --configinfo

          ****** SYSTEM ******

          Name (String)
          Name of system (NDB Cluster)
          MANDATORY

          PrimaryMGMNode (Non-negative Integer)
          Node id of Primary ndb_mgmd(MGM) node
          Default: 0 (Min: 0, Max: 4294967039)

          ConfigGenerationNumber (Non-negative Integer)
          Configuration generation number
          Default: 0 (Min: 0, Max: 4294967039)

          ****** DB ******

          MaxNoOfSubscriptions (Non-negative Integer)
          Max no of subscriptions (default 0 == MaxNoOfTables)
          Default: 0 (Min: 0, Max: 4294967039)

          MaxNoOfSubscribers (Non-negative Integer)
          Max no of subscribers (default 0 == 2 * MaxNoOfTables)
          Default: 0 (Min: 0, Max: 4294967039)

          ...

     Use this option together with the '--xml' option to obtain output
     in XML format.

   *
     '--config-file=PATH-TO-FILE'

     Property                             Value

     *Command-Line Format*                '--config-file=file_name'

     *Type*                               file name

     *Default Value*                      ''

     Gives the path to the management server's configuration file
     ('config.ini').  This may be a relative or absolute path.  If the
     management node resides on a different host from the one on which
     'ndb_config' is invoked,
     then an absolute path must be used.

   *
     '--config_from_node=#'

     Property                             Value

     *Command-Line Format*                '--config-from-node=#'

     *Type*                               numeric

     *Default Value*                      'none'

     *Minimum Value*                      '1'

     *Maximum Value*                      '48'

     Obtain the cluster's configuration data from the data node that has
     this ID.

     If the node having this ID is not a data node, see 'ndb_config'
     fails with an error.  (To obtain
     configuration data from the management node instead, simply omit
     this option.)

   *
     '--connections'

     Property                             Value

     *Command-Line Format*                '--connections'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Tells 'ndb_config' to
     print 'CONNECTIONS' information only--that is, information about
     parameters found in the '[tcp]', '[tcp default]', '[sci]', '[sci
     default]', '[shm]', or '[shm default]' sections of the cluster
     configuration file (see mysql-cluster-tcp-definition,
     mysql-cluster-sci-definition, and
     mysql-cluster-shm-definition, for more information).

     This option is mutually exclusive with '--nodes' and '--system';
     only one of these 3 options can be used.

   *
     '--diff-default'

     Property                             Value

     *Command-Line Format*                '--diff-default'

     *Introduced*                         5.7.18-ndb-7.6.3

     *Type* (>= 5.7.18-ndb-7.6.3)         boolean

     *Type* (>= 5.7.18-ndb-7.5.7)         boolean

     *Type*                               boolean

     *Default Value* (>=                  'FALSE'
     5.7.18-ndb-7.6.3)

     *Default Value* (>=                  'FALSE'
     5.7.18-ndb-7.5.7)

     *Default Value*                      'FALSE'

     Print only configuration parameters that have non-default values.

   *
     '--fields=DELIMITER', '-f' DELIMITER

     Property                             Value

     *Command-Line Format*                '--fields=string'

     *Type*                               string

     *Default Value*                      ''

     Specifies a DELIMITER string used to separate the fields in the
     result.  The default is ',' (the comma character).

     *Note*:

     If the DELIMITER contains spaces or escapes (such as '\n' for the
     linefeed character), then it must be quoted.

   *
     '--host=HOSTNAME'

     Property                             Value

     *Command-Line Format*                '--host=name'

     *Type*                               string

     *Default Value*                      ''

     Specifies the host name of the node for which configuration
     information is to be obtained.

     *Note*:

     While the hostname 'localhost' usually resolves to the IP address
     '127.0.0.1', this may not necessarily be true for all operating
     platforms and configurations.  This means that it is possible, when
     'localhost' is used in 'config.ini', for 'ndb_config --host=localhost'
     to fail if
     'ndb_config' is run on a
     different host where 'localhost' resolves to a different address
     (for example, on some versions of SUSE Linux, this is '127.0.0.2').
     In general, for best results, you should use numeric IP addresses
     for all NDB Cluster configuration values relating to hosts, or
     verify that all NDB Cluster hosts handle 'localhost' in the same
     fashion.

   *
     '--mycnf'

     Property                             Value

     *Command-Line Format*                '--mycnf'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Read configuration data from the 'my.cnf' file.

   *
     '--ndb-connectstring=CONNECTION_STRING', '-c CONNECTION_STRING'

     Property                             Value

     *Command-Line Format*                '--ndb-connectstring=connectstring'
                                          '--connect-string=connectstring'

     *Type*                               string

     *Default Value*                      'localhost:1186'

     Specifies the connection string to use in connecting to the
     management server.  The format for the connection string is the
     same as described in mysql-cluster-connection-strings, and
     defaults to 'localhost:1186'.

   *
     '--nodeid=NODE_ID', '--id=NODE_ID'

     Property                             Value

     *Command-Line Format*                '--ndb-nodeid=#'

     *Type*                               numeric

     *Default Value*                      '0'

     Specify the node ID of the node for which configuration information
     is to be obtained.  '--nodeid' is the preferred form.

   *
     '--nodes'

     Property                             Value

     *Command-Line Format*                '--nodes'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Tells 'ndb_config' to
     print information relating only to parameters defined in an
     '[ndbd]' or '[ndbd default]' section of the cluster configuration
     file (see mysql-cluster-ndbd-definition).

     This option is mutually exclusive with '--connections' and
     '--system'; only one of these 3 options can be used.

   *
     '--query=QUERY-OPTIONS', '-q' QUERY-OPTIONS

     Property                             Value

     *Command-Line Format*                '--query=string'

     *Type*                               string

     *Default Value*                      ''

     This is a comma-delimited list of _query options_--that is, a list
     of one or more node attributes to be returned.  These include 'id'
     (node ID), type (node type--that is, 'ndbd', 'mysqld', or
     'ndb_mgmd'), and any configuration parameters whose values are to
     be obtained.

     For example,

     '--query=nodeid,type,indexmemory,datamemory' returns the node ID,
     node type, 'DataMemory', and 'IndexMemory' for each node.

     *Note*:

     If a given parameter is not applicable to a certain type of node,
     than an empty string is returned for the corresponding value.  See
     the examples later in this section for more information.

   *
     '--query-all', '-a'

     Property                             Value

     *Command-Line Format*                '--query-all'

     *Introduced*                         5.7.18-ndb-7.5.7

     *Type* (>=                           string
     5.7.18-ndb-7.4.16,5.7.18-ndb-7.5.7)

     *Default Value* (>=                  ''
     5.7.18-ndb-7.4.16,5.7.18-ndb-7.5.7)

     Returns a comma-delimited list of all query options (node
     attributes; note that this list is a single string.

     This option was introduced in NDB 7.5.7 (Bug #60095, Bug
     #11766869).

   *
     '--rows=SEPARATOR', '-r' SEPARATOR

     Property                             Value

     *Command-Line Format*                '--rows=string'

     *Type*                               string

     *Default Value*                      ''

     Specifies a SEPARATOR string used to separate the rows in the
     result.  The default is a space character.

     *Note*:

     If the SEPARATOR contains spaces or escapes (such as '\n' for the
     linefeed character), then it must be quoted.

   *
     '--system'

     Property                             Value

     *Command-Line Format*                '--system'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Tells 'ndb_config' to
     print 'SYSTEM' information only.  This consists of system variables
     that cannot be changed at run time; thus, there is no corresponding
     section of the cluster configuration file for them.  They can be
     seen (prefixed with '****** SYSTEM ******') in the output of
     'ndb_config'. '--configinfo'.

     This option is mutually exclusive with '--nodes' and
     '--connections'; only one of these 3 options can be used.

   *
     '--type=NODE_TYPE'

     Property                             Value

     *Command-Line Format*                '--type=name'

     *Type*                               enumeration

     *Default Value*                      '[none]'

     *Valid Values*                       'ndbd' 'mysqld' 'ndb_mgmd'

     Filters results so that only configuration values applying to nodes
     of the specified NODE_TYPE ('ndbd', 'mysqld', or 'ndb_mgmd') are
     returned.

   *
     '--usage', '--help', or '-?'

     Property                             Value

     *Command-Line Format*                '--help' '--usage'

     Causes 'ndb_config' to
     print a list of available options, and then exit.

   *
     '--version', '-V'

     Property                             Value

     *Command-Line Format*                '--version'

     Causes 'ndb_config' to
     print a version information string, and then exit.

   *
     '--configinfo' '--xml'

     Property                             Value

     *Command-Line Format*                '--configinfo --xml'

     *Type*                               boolean

     *Default Value*                      'false'

     Cause 'ndb_config'.
     '--configinfo' to provide output as XML by adding this option.  A
     portion of such output is shown in this example:

          shell> ndb_config --configinfo --xml

          <configvariables protocolversion="1" ndbversionstring="5.7.22-ndb-7.5.11"
                              ndbversion="460032" ndbversionmajor="7" ndbversionminor="5"
                              ndbversionbuild="0">
            <section name="SYSTEM">
              <param name="Name" comment="Name of system (NDB Cluster)" type="string"
                        mandatory="true"/>
              <param name="PrimaryMGMNode" comment="Node id of Primary ndb_mgmd(MGM) node"
                        type="unsigned" default="0" min="0" max="4294967039"/>
              <param name="ConfigGenerationNumber" comment="Configuration generation number"
                        type="unsigned" default="0" min="0" max="4294967039"/>
            </section>
            <section name="MYSQLD" primarykeys="NodeId">
              <param name="wan" comment="Use WAN TCP setting as default" type="bool"
                        default="false"/>
              <param name="HostName" comment="Name of computer for this node"
                        type="string" default=""/>
              <param name="Id" comment="NodeId" type="unsigned" mandatory="true"
                        min="1" max="255" deprecated="true"/>
              <param name="NodeId" comment="Number identifying application node (mysqld(API))"
                        type="unsigned" mandatory="true" min="1" max="255"/>
              <param name="ExecuteOnComputer" comment="HostName" type="string"
                        deprecated="true"/>

              ...

            </section>

            ...

          </configvariables>

     *Note*:

     Normally, the XML output produced by 'ndb_config'.
     '--configinfo' '--xml' is
     formatted using one line per element; we have added extra
     whitespace in the previous example, as well as the next one, for
     reasons of legibility.  This should not make any difference to
     applications using this output, since most XML processors either
     ignore nonessential whitespace as a matter of course, or can be
     instructed to do so.

     The XML output also indicates when changing a given parameter
     requires that data nodes be restarted using the '--initial' option.
     This is shown by the presence of an 'initial="true"' attribute in
     the corresponding '<param>' element.  In addition, the restart type
     ('system' or 'node') is also shown; if a given parameter requires a
     system restart, this is indicated by the presence of a
     'restart="system"' attribute in the corresponding '<param>'
     element.  For example, changing the value set for the 'Diskless'
     parameter requires a system initial restart, as shown here (with
     the 'restart' and 'initial' attributes highlighted for visibility):

          <param name="Diskless" comment="Run wo/ disk" type="bool" default="false"
                    _restart="system" initial="true"_/>

     Currently, no 'initial' attribute is included in the XML output for
     '<param>' elements corresponding to parameters which do not require
     initial restarts; in other words, 'initial="false"' is the default,
     and the value 'false' should be assumed if the attribute is not
     present.  Similarly, the default restart type is 'node' (that is,
     an online or 'rolling' restart of the cluster), but the 'restart'
     attribute is included only if the restart type is 'system' (meaning
     that all cluster nodes must be shut down at the same time, then
     restarted).

     Deprecated parameters are indicated in the XML output by the
     'deprecated' attribute, as shown here:

          <param name="NoOfDiskPagesToDiskAfterRestartACC" comment="DiskCheckpointSpeed"
                 type="unsigned" default="20" min="1" max="4294967039" _deprecated="true"_/>

     In such cases, the 'comment' refers to one or more parameters that
     supersede the deprecated parameter.  Similarly to 'initial', the
     'deprecated' attribute is indicated only when the parameter is
     deprecated, with 'deprecated="true"', and does not appear at all
     for parameters which are not deprecated.  (Bug #21127135)

     Beginning with NDB 7.5.0, parameters that are required are
     indicated with 'mandatory="true"', as shown here:

          <param name="NodeId"
                    comment="Number identifying application node (mysqld(API))"
                    type="unsigned" _mandatory="true"_ min="1" max="255"/>

     In much the same way that the 'initial' or 'deprecated' attribute
     is displayed only for a parameter that requires an intial restart
     or that is deprecated, the 'mandatory' attribute is included only
     if the given parameter is actually required.

     *Important*:

     The '--xml' option can be used only with the '--configinfo' option.
     Using '--xml' without '--configinfo' fails with an error.

     Unlike the options used with this program to obtain current
     configuration data, '--configinfo' and '--xml' use information
     obtained from the NDB Cluster sources when 'ndb_config'
     was compiled.  For this reason,
     no connection to a running NDB Cluster or access to a 'config.ini'
     or 'my.cnf' file is required for these two options.

Combining other 'ndb_config'.
options (such as '--query' or '--type') with '--configinfo' (with or
without the '--xml' option is not supported.  Currently, if you attempt
to do so, the usual result is that all other options besides
'--configinfo' or '--xml' are simply ignored.  _However, this behavior
is not guaranteed and is subject to change at any time_.  In addition,
since 'ndb_config', when used
with the '--configinfo' option, does not access the NDB Cluster or read
any files, trying to specify additional options such as
'--ndb-connectstring' or '--config-file' with '--configinfo' serves no
purpose.

*Examples*

  1. To obtain the node ID and type of each node in the cluster:

          shell> ./ndb_config --query=id,type --fields=':' --rows='\n'
          1:ndbd
          2:ndbd
          3:ndbd
          4:ndbd
          5:ndb_mgmd
          6:mysqld
          7:mysqld
          8:mysqld
          9:mysqld

     In this example, we used the '--fields' options to separate the ID
     and type of each node with a colon character (':'), and the
     '--rows' options to place the values for each node on a new line in
     the output.

  2. To produce a connection string that can be used by data, SQL, and
     API nodes to connect to the management server:

          shell> ./ndb_config --config-file=usr/local/mysql/cluster-data/config.ini \
          --query=hostname,portnumber --fields=: --rows=, --type=ndb_mgmd
          198.51.100.179:1186

  3. This invocation of 'ndb_config'
     checks only data nodes (using
     the '--type' option), and shows the values for each node's ID and
     host name, as well as the values set for its 'DataMemory',
     'IndexMemory', and 'DataDir' parameters:

          shell> ./ndb_config --type=ndbd --query=id,host,datamemory,indexmemory,datadir -f ' : ' -r '\n'
          1 : 198.51.100.193 : 83886080 : 18874368 : /usr/local/mysql/cluster-data
          2 : 198.51.100.112 : 83886080 : 18874368 : /usr/local/mysql/cluster-data
          3 : 198.51.100.176 : 83886080 : 18874368 : /usr/local/mysql/cluster-data
          4 : 198.51.100.119 : 83886080 : 18874368 : /usr/local/mysql/cluster-data

     In this example, we used the short options '-f' and '-r' for
     setting the field delimiter and row separator, respectively.

  4. To exclude results from any host except one in particular, use the
     '--host' option:

          shell> ./ndb_config --host=198.51.100.176 -f : -r '\n' -q id,type
          3:ndbd
          5:ndb_mgmd

     In this example, we also used the short form '-q' to determine the
     attributes to be queried.

     Similarly, you can limit results to a node with a specific ID using
     the '--nodeid' option.

21.4.8 'ndb_cpcd' -- Automate Testing for NDB Development
---------------------------------------------------------

A utility having this name was formerly part of an internal automated
test framework used in testing and debugging NDB Cluster.  It is no
longer included in NDB Cluster distributions provided by Oracle.

21.4.9 'ndb_delete_all' -- Delete All Rows from an NDB Table
------------------------------------------------------------

'ndb_delete_all' deletes
all rows from the given 'NDB' table.  In some
cases, this can be much faster than 'DELETE' or even
'TRUNCATE TABLE'.

*Usage*

     ndb_delete_all -c CONNECTION_STRING TBL_NAME -d DB_NAME

This deletes all rows from the table named TBL_NAME in the database
named DB_NAME.  It is exactly equivalent to executing 'TRUNCATE
DB_NAME.TBL_NAME' in MySQL.

The following table includes options that are specific to
'ndb_delete_all'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndb_delete_all'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_delete_all program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Name of the database
'--database=dbname',     in which the table is    All MySQL 5.7 based
                         found                    releases
'-d'

'--transactional',       Perform the delete in    All MySQL 5.7 based
                         a single transaction     releases
' -t '                   (may run out of
                         operations)

                         Run tup scan
'--tupscan'                                       All MySQL 5.7 based
                                                  releases

                         Run disk scan
'--diskscan'                                      All MySQL 5.7 based
                                                  releases

   *
     '--transactional', '-t'

     Use of this option causes the delete operation to be performed as a
     single transaction.

     *Warning*:

     With very large tables, using this option may cause the number of
     operations available to the cluster to be exceeded.

21.4.10 'ndb_desc' -- Describe NDB Tables
-----------------------------------------

'ndb_desc' provides a detailed
description of one or more 'NDB' tables.

*Usage*

     ndb_desc -c CONNECTION_STRING TBL_NAME -d DB_NAME [OPTIONS]

     ndb_desc -c CONNECTION_STRING INDEX_NAME -d DB_NAME -t TBL_NAME

Additional options that can be used with 'ndb_desc'
are listed later in this section.

*Sample Output*

MySQL table creation and population statements:

     USE test;

     CREATE TABLE fish (
         id INT(11) NOT NULL AUTO_INCREMENT,
         name VARCHAR(20) NOT NULL,
         length_mm INT(11) NOT NULL,
         weight_gm INT(11) NOT NULL,

         PRIMARY KEY pk (id),
         UNIQUE KEY uk (name)
     ) ENGINE=NDB;

     INSERT INTO fish VALUES
         (NULL, 'guppy', 35, 2), (NULL, 'tuna', 2500, 150000),
         (NULL, 'shark', 3000, 110000), (NULL, 'manta ray', 1500, 50000),
         (NULL, 'grouper', 900, 125000), (NULL ,'puffer', 250, 2500);

Output from 'ndb_desc'.:

     shell> ./ndb_desc -c localhost fish -d test -p
     -- fish --
     Version: 2
     Fragment type: HashMapPartition
     K Value: 6
     Min load factor: 78
     Max load factor: 80
     Temporary table: no
     Number of attributes: 4
     Number of primary keys: 1
     Length of frm data: 337
     Max Rows: 0
     Row Checksum: 1
     Row GCI: 1
     SingleUserMode: 0
     ForceVarPart: 1
     PartitionCount: 2
     FragmentCount: 2
     PartitionBalance: FOR_RP_BY_LDM
     ExtraRowGciBits: 0
     ExtraRowAuthorBits: 0
     TableStatus: Retrieved
     Table options:
     HashMap: DEFAULT-HASHMAP-3840-2
     -- Attributes --
     id Int PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
     name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY DYNAMIC
     length_mm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
     weight_gm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
     -- Indexes --
     PRIMARY KEY(id) - UniqueHashIndex
     PRIMARY(id) - OrderedIndex
     uk(name) - OrderedIndex
     uk$unique(name) - UniqueHashIndex
     -- Per partition info --
     Partition       Row count       Commit count    Frag fixed memory       Frag varsized memory    Extent_space    Free extent_space
     0               2               2               32768                   32768                   0               0
     1               4               4               32768                   32768                   0               0

     NDBT_ProgramExit: 0 - OK

Information about multiple tables can be obtained in a single invocation
of 'ndb_desc' by using their
names, separated by spaces.  All of the tables must be in the same
database.

You can obtain additional information about a specific index using the
'--table' (short form: '-t') option and supplying the name of the index
as the first argument to 'ndb_desc',
as shown here:

     shell> ./ndb_desc uk -d test -t fish
     -- uk --
     Version: 2
     Base table: fish
     Number of attributes: 1
     Logging: 0
     Index type: OrderedIndex
     Index status: Retrieved
     -- Attributes --
     name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
     -- IndexTable 10/uk --
     Version: 2
     Fragment type: FragUndefined
     K Value: 6
     Min load factor: 78
     Max load factor: 80
     Temporary table: yes
     Number of attributes: 2
     Number of primary keys: 1
     Length of frm data: 0
     Max Rows: 0
     Row Checksum: 1
     Row GCI: 1
     SingleUserMode: 2
     ForceVarPart: 0
     PartitionCount: 2
     FragmentCount: 2
     FragmentCountType: ONE_PER_LDM_PER_NODE
     ExtraRowGciBits: 0
     ExtraRowAuthorBits: 0
     TableStatus: Retrieved
     Table options:
     -- Attributes --
     name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
     NDB$TNODE Unsigned [64] PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY
     -- Indexes --
     PRIMARY KEY(NDB$TNODE) - UniqueHashIndex

     NDBT_ProgramExit: 0 - OK

When an index is specified in this way, the '--extra-partition-info' and
'--extra-node-info' options have no effect.

The 'Version' column in the output contains the table's schema object
version.  For information about interpreting this value, see NDB Schema
Object Versions
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-schema-object-versions.html).

Three of the table properties that can be set using 'NDB_TABLE' comments
embedded in 'CREATE TABLE' and 'ALTER TABLE'
statements are also visible in 'ndb_desc'
output.  The table's
'FRAGMENT_COUNT_TYPE' is always shown in the 'FragmentCountType' column.
'READ_ONLY' and 'FULLY_REPLICATED', if set to 1, are shown in the 'Table
options' column.  You can see this after executing the following
'ALTER TABLE' statement in the 'mysql'.
client:

     mysql> ALTER TABLE fish COMMENT='NDB_TABLE=READ_ONLY=1,FULLY_REPLICATED=1';
     1 row in set, 1 warning (0.00 sec)

     mysql> SHOW WARNINGS\G
     +---------+------+---------------------------------------------------------------------------------------------------------+
     | Level   | Code | Message                                                                                                 |
     +---------+------+---------------------------------------------------------------------------------------------------------+
     | Warning | 1296 | Got error 4503 'Table property is FRAGMENT_COUNT_TYPE=ONE_PER_LDM_PER_NODE but not in comment' from NDB |
     +---------+------+---------------------------------------------------------------------------------------------------------+
     1 row in set (0.00 sec)

The warning is issued because 'READ_ONLY=1' requires that the table's
fragment count type is (or be set to) 'ONE_PER_LDM_PER_NODE_GROUP';
'NDB' sets this automatically in such cases.  You can check that the
'ALTER TABLE' statement has the desired effect using 'SHOW CREATE TABLE'.:

     mysql> SHOW CREATE TABLE fish\G
     *************************** 1. row ***************************
            Table: fish
     Create Table: CREATE TABLE `fish` (
       `id` int(11) NOT NULL AUTO_INCREMENT,
       `name` varchar(20) NOT NULL,
       `length_mm` int(11) NOT NULL,
       `weight_gm` int(11) NOT NULL,
       PRIMARY KEY (`id`),
       UNIQUE KEY `uk` (`name`)
     ) ENGINE=ndbcluster DEFAULT CHARSET=latin1
     COMMENT='NDB_TABLE=READ_BACKUP=1,FULLY_REPLICATED=1'
     1 row in set (0.01 sec)

Because 'FRAGMENT_COUNT_TYPE' was not set explicitly, its value is not
shown in the comment text printed by 'SHOW CREATE TABLE'.  See
'ndb_desc', however, displays the
updated value for this attribute.  The 'Table options' column shows the
binary properties just enabled.  You can see this in the output shown
here (emphasized text):

     shell> ./ndb_desc -c localhost fish -d test -p
     -- fish --
     Version: 4
     Fragment type: HashMapPartition
     K Value: 6
     Min load factor: 78
     Max load factor: 80
     Temporary table: no
     Number of attributes: 4
     Number of primary keys: 1
     Length of frm data: 380
     Max Rows: 0
     Row Checksum: 1
     Row GCI: 1
     SingleUserMode: 0
     ForceVarPart: 1
     PartitionCount: 1
     FragmentCount: 1
     _FragmentCountType: ONE_PER_LDM_PER_NODE_GROUP_
     ExtraRowGciBits: 0
     ExtraRowAuthorBits: 0
     TableStatus: Retrieved
     _Table options: readbackup, fullyreplicated_
     HashMap: DEFAULT-HASHMAP-3840-1
     -- Attributes --
     id Int PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
     name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY DYNAMIC
     length_mm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
     weight_gm Int NOT NULL AT=FIXED ST=MEMORY DYNAMIC
     -- Indexes --
     PRIMARY KEY(id) - UniqueHashIndex
     PRIMARY(id) - OrderedIndex
     uk(name) - OrderedIndex
     uk$unique(name) - UniqueHashIndex
     -- Per partition info --
     Partition       Row count       Commit count    Frag fixed memory       Frag varsized memory    Extent_space    Free extent_space

     NDBT_ProgramExit: 0 - OK

For more information about these table properties, see
create-table-ndb-table-comment-options.

The 'Extent_space' and 'Free extent_space' columns are applicable only
to 'NDB' tables having columns on disk; for tables having only in-memory
columns, these columns always contain the value '0'.

To illustrate their use, we modify the previous example.  First, we must
create the necessary Disk Data objects, as shown here:

     CREATE LOGFILE GROUP lg_1
         ADD UNDOFILE 'undo_1.log'
         INITIAL_SIZE 16M
         UNDO_BUFFER_SIZE 2M
         ENGINE NDB;

     ALTER LOGFILE GROUP lg_1
         ADD UNDOFILE 'undo_2.log'
         INITIAL_SIZE 12M
         ENGINE NDB;

     CREATE TABLESPACE ts_1
         ADD DATAFILE 'data_1.dat'
         USE LOGFILE GROUP lg_1
         INITIAL_SIZE 32M
         ENGINE NDB;

     ALTER TABLESPACE ts_1
         ADD DATAFILE 'data_2.dat'
         INITIAL_SIZE 48M
         ENGINE NDB;

(For more information on the statements just shown and the objects
created by them, see mysql-cluster-disk-data-objects, as well as
create-logfile-group, and create-tablespace.)

Now we can create and populate a version of the 'fish' table that stores
2 of its columns on disk (deleting the previous version of the table
first, if it already exists):

     CREATE TABLE fish (
         id INT(11) NOT NULL AUTO_INCREMENT,
         name VARCHAR(20) NOT NULL,
         length_mm INT(11) NOT NULL,
         weight_gm INT(11) NOT NULL,

         PRIMARY KEY pk (id),
         UNIQUE KEY uk (name)
     ) TABLESPACE ts_1 STORAGE DISK
     ENGINE=NDB;

     INSERT INTO fish VALUES
         (NULL, 'guppy', 35, 2), (NULL, 'tuna', 2500, 150000),
         (NULL, 'shark', 3000, 110000), (NULL, 'manta ray', 1500, 50000),
         (NULL, 'grouper', 900, 125000), (NULL ,'puffer', 250, 2500);

When run against this version of the table, see 'ndb_desc'
displays the following output:

     shell> ./ndb_desc -c localhost fish -d test -p
     -- fish --
     Version: 1
     Fragment type: HashMapPartition
     K Value: 6
     Min load factor: 78
     Max load factor: 80
     Temporary table: no
     Number of attributes: 4
     Number of primary keys: 1
     Length of frm data: 346
     Max Rows: 0
     Row Checksum: 1
     Row GCI: 1
     SingleUserMode: 0
     ForceVarPart: 1
     PartitionCount: 2
     FragmentCount: 2
     FragmentCountType: ONE_PER_LDM_PER_NODE
     ExtraRowGciBits: 0
     ExtraRowAuthorBits: 0
     TableStatus: Retrieved
     Table options:
     HashMap: DEFAULT-HASHMAP-3840-2
     -- Attributes --
     id Int PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
     name Varchar(20;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
     length_mm Int NOT NULL AT=FIXED ST=DISK
     weight_gm Int NOT NULL AT=FIXED ST=DISK
     -- Indexes --
     PRIMARY KEY(id) - UniqueHashIndex
     PRIMARY(id) - OrderedIndex
     uk(name) - OrderedIndex
     uk$unique(name) - UniqueHashIndex
     -- Per partition info --
     Partition       Row count       Commit count    Frag fixed memory       Frag varsized memory    Extent_space    Free extent_space
     0               2               2               32768                   32768                   1048576         1044440
     1               4               4               32768                   32768                   1048576         1044400

     NDBT_ProgramExit: 0 - OK

This means that 1048576 bytes are allocated from the tablespace for this
table on each partition, of which 1044440 bytes remain free for
additional storage.  In other words, 1048576 - 1044440 = 4136 bytes per
partition is currently being used to store the data from this table's
disk-based columns.  The number of bytes shown as 'Free extent_space' is
available for storing on-disk column data from the 'fish' table only;
for this reason, it is not visible when selecting from the
'INFORMATION_SCHEMA.FILES' table.

For fully replicated tables, see 'ndb_desc'
shows only the nodes holding primary
partition fragment replicas; nodes with copy fragment replicas (only)
are ignored.  Beginning with NDB 7.5.4, you can obtain such information,
using the 'mysql' client, from the
'table_distribution_status',
see
'table_fragments',
'table_info', and
'table_replicas' tables in the
'ndbinfo' database.

The following table includes options that are specific to
'ndb_desc'.  Additional descriptions
follow the table.  For options common to most NDB Cluster programs
(including 'ndb_desc'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_desc program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Include partition
'--blob-info',           information for BLOB     All MySQL 5.7 based
                         tables in output.        releases
' -b '                   Requires that the -p
                         option also be used

                         Name of database
'--database=dbname',     containing table         All MySQL 5.7 based
                                                  releases
' -d '

'--extra-node-info',     Include                  All MySQL 5.7 based
                         partition-to-data-node   releases
' -n '                   mappings in output.
                         Requires that the -p
                         option also be used

                         Display information
'--extra-partition-info',about partitions         All MySQL 5.7 based
                                                  releases
' -p '

'--retries=#',           Number of times to       All MySQL 5.7 based
                         retry the connection     releases
' -r '                   (once per second)

                         Specify the table in
'--table=tbl_name',      which to find an         All MySQL 5.7 based
                         index.  When this        releases
' -t '                   option is used, -p and
                         -n have no effect and
                         are ignored.

                         Use unqualified table
'--unqualified',         names                    All MySQL 5.7 based
                                                  releases
' -u '

   *
     '--blob-info', '-b'

     Include information about subordinate 'BLOB' and
     'TEXT' columns.

     Use of this option also requires the use of the
     '--extra-partition-info' ('-p') option.

   *
     '--database=DB_NAME', '-d'

     Specify the database in which the table should be found.

   *
     '--extra-node-info', '-n'

     Include information about the mappings between table partitions and
     the data nodes upon which they reside.  This information can be
     useful for verifying distribution awareness mechanisms and
     supporting more efficient application access to the data stored in
     NDB Cluster.

     Use of this option also requires the use of the
     '--extra-partition-info' ('-p') option.

   *
     '--extra-partition-info', '-p'

     Print additional information about the table's partitions.

   *
     '--retries=#', '-r'

     Try to connect this many times before giving up.  One connect
     attempt is made per second.

   *
     '--table=TBL_NAME', '-t'

     Specify the table in which to look for an index.

   *
     '--unqualified', '-u'

     Use unqualified table names.

In NDB 7.5.3 and later, table indexes listed in the output are ordered
by ID. Previously, this was not deterministic and could vary between
platforms.  (Bug #81763, Bug #23547742)

21.4.11 'ndb_drop_index' -- Drop Index from an NDB Table
--------------------------------------------------------

'ndb_drop_index' drops the
specified index from an 'NDB' table.  _It is
recommended that you use this utility only as an example for writing NDB
API applications_--see the Warning later in this section for details.

*Usage*

     ndb_drop_index -c CONNECTION_STRING TABLE_NAME INDEX -d DB_NAME

The statement shown above drops the index named INDEX from the TABLE in
the DATABASE.

The following table includes options that are specific to
'ndb_drop_index'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndb_drop_index'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_drop_index program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Name of the database
'--database=dbname',     in which the table is    All MySQL 5.7 based
                         found                    releases
'-d'

*Warning*:

_Operations performed on Cluster table indexes using the NDB API are not
visible to MySQL and make the table unusable by a MySQL server_.  If you
use this program to drop an index, then try to access the table from an
SQL node, an error results, as shown here:

     shell> ./ndb_drop_index -c localhost dogs ix -d ctest1
     Dropping index dogs/idx...OK

     NDBT_ProgramExit: 0 - OK

     shell> ./mysql -u jon -p ctest1
     Enter password: *******
     Reading table information for completion of table and column names
     You can turn off this feature to get a quicker startup with -A

     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 7 to server version: 5.7.22-ndb-7.5.11

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql> SHOW TABLES;
     +------------------+
     | Tables_in_ctest1 |
     +------------------+
     | a                |
     | bt1              |
     | bt2              |
     | dogs             |
     | employees        |
     | fish             |
     +------------------+
     6 rows in set (0.00 sec)

     mysql> SELECT * FROM dogs;
     ERROR 1296 (HY000): Got error 4243 'Index not found' from NDBCLUSTER

In such a case, your _only_ option for making the table available to
MySQL again is to drop the table and re-create it.  You can use either
the SQL statement'DROP TABLE' or the
'ndb_drop_table' utility (see
mysql-cluster-programs-ndb-drop-table) to drop the table.

21.4.12 'ndb_drop_table' -- Drop an NDB Table
---------------------------------------------

'ndb_drop_table' drops the
specified 'NDB' table.  (If you try to use this on
a table created with a storage engine other than 'NDB',
the attempt fails with the error '723: No such table
exists'.)  This operation is extremely fast; in some cases, it can be an
order of magnitude faster than using a MySQL 'DROP TABLE'
statement on an 'NDB' table.

*Usage*

     ndb_drop_table -c CONNECTION_STRING TBL_NAME -d DB_NAME

The following table includes options that are specific to
'ndb_drop_table'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndb_drop_table'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_drop_table program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Name of the database
'--database=dbname',     in which the table is    All MySQL 5.7 based
                         found                    releases
'-d'

21.4.13 'ndb_error_reporter' -- NDB Error-Reporting Utility
-----------------------------------------------------------

See 'ndb_error_reporter'.
creates an archive from data node and management node log files that can
be used to help diagnose bugs or other problems with a cluster.  _It is
highly recommended that you make use of this utility when filing reports
of bugs in NDB Cluster_.

The following table includes command options specific to the NDB Cluster
program 'ndb_error_reporter'.
Additional descriptions
follow the table.  For options common to most NDB Cluster programs
(including 'ndb_error_reporter'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_error_reporter program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Number of seconds to
'                        wait when connecting     All MySQL 5.7 based
--connection-timeout=timeoutto nodes before timingreleases
'                        out.

                         Disable scp with
' --dry-scp '            remote hosts; used       All MySQL 5.7 based
                         only for testing.        releases

                         Include file system
' --fs '                 data in error report;    All MySQL 5.7 based
                         can use a large amount   releases
                         of disk space

                         Skip all nodes in the
'                        node group having this   All MySQL 5.7 based
--skip-nodegroup=nodegroup_idID.                  releases
'

*Usage*

     ndb_error_reporter PATH/TO/CONFIG-FILE [USERNAME] [OPTIONS]

This utility is intended for use on a management node host, and requires
the path to the management host configuration file (usually named
'config.ini').  Optionally, you can supply the name of a user that is
able to access the cluster's data nodes using SSH, to copy the data node
log files.  'ndb_error_reporter'
then includes all of these
files in archive that is created in the same directory in which it is
run.  The archive is named 'ndb_error_report_YYYYMMDDHHMMSS.tar.bz2',
where YYYYMMDDHHMMSS is a datetime string.

See 'ndb_error_reporter'.
also accepts the options listed here:

   *
     '--connection-timeout=TIMEOUT'

     Property                             Value

     *Command-Line Format*                '--connection-timeout=timeout'

     *Type*                               integer

     *Default Value*                      '0'

     Wait this many seconds when trying to connect to nodes before
     timing out.

   *
     '--dry-scp'

     Property                             Value

     *Command-Line Format*                '--dry-scp'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Run 'ndb_error_reporter'
     without using scp from
     remote hosts.  Used for testing only.

   *
     '--fs'

     Property                             Value

     *Command-Line Format*                '--fs'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Copy the data node file systems to the management host and include
     them in the archive.

     Because data node file systems can be extremely large, even after
     being compressed, we ask that you please do _not_ send archives
     created using this option to Oracle unless you are specifically
     requested to do so.

   *
     '--skip-nodegroup=NODEGROUP_ID'

     Property                             Value

     *Command-Line Format*                '--connection-timeout=timeout'

     *Type*                               integer

     *Default Value*                      '0'

     Skip all nodes belong to the node group having the supplied node
     group ID.

21.4.14 'ndb_import' -- Import CSV Data Into NDB
------------------------------------------------

'ndb_import' imports
CSV-formatted data into 'NDB' using the NDB API, which requires a
connection to an NDB management server.  A connection to a MySQL Server
is not required.

*Usage*

     ndb_import DB_NAME FILE_NAME OPTIONS

'ndb_import' requires two
arguments.  DB_NAME is the name of the database in which the database
where the table into which to import the data is found; FILE_NAME is the
name of the CSV file from which to read the data, including the path to
this file if it is not in the current directory.  The name of the file
must match the name of the table; the file's extention, if any, is not
taken into consdieration.  Additional arguments (described later in this
section) are supported, including options for specifying field
separators, escapes, and line terminators.  'ndb_import'
must be able to connect to an NDB
Cluster management server; for this reason, there must be an unused
'[api]' slot in the 'config.ini' file.

To duplicate an existing table that uses a different storage engine,
such as 'InnoDB', as an 'NDB' table, use
the 'mysql' client to perform a 'SELECT INTO OUTFILE'
statement to export the existing table to a CSV
file, then to execute a 'CREATE TABLE LIKE'.
statement to create a new table having the same structure as the
existing table, then perform 'ALTER TABLE ... ENGINE=NDB'
on the new table; after this, from the system shell, invoke
'ndb_import' to load the data
into the new 'NDB' table.  For example, an existing 'InnoDB' table named
'myinnodb_table' in a database named 'myinnodb' can be exported into an
'NDB' table named 'myndb_table' in a database named 'myndb' as shown
here, assuming that you are already logged in as a MySQL user with the
appropriate privileges:

  1. In the 'mysql' client:

          mysql> USE myinnodb;

          mysql> SELECT * INTO OUTFILE '/tmp/myndb_table.csv'
               >  FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\\'
               >  LINES TERMINATED BY '\n'
               >  FROM myinnodbtable;

          mysql> CREATE DATABASE myndb;

          mysql> USE myndb;

          mysql> CREATE TABLE myndb_table LIKE myinnodb.myinnodb_table;

          mysql> ALTER TABLE myndb_table ENGINE=NDB;

          mysql> EXIT;
          Bye
          shell>

     Once the target database and table have been created, a running
     'mysqld' is no longer required.  You can stop it
     using 'mysqladmin shutdown' or another method
     before proceeding, if you wish.

  2. In the system shell:

          # if you are not already in the MySQL bin directory:
          shell> cd PATH-TO-MYSQL-BIN-DIR

          shell> ndb_import myndb /tmp/myndb_table.csv --fields-optionally-enclosed-by='"' \
              --fields-terminated-by="," --fields-escaped-by='\\'

     The output should resemble what is shown here:

          job-1 import myndb.myndb_table from /tmp/myndb_table.csv
          job-1 [running] import myndb.myndb_table from /tmp/myndb_table.csv
          job-1 [success] import myndb.myndb_table from /tmp/myndb_table.csv
          job-1 imported 19984 rows in 0h0m9s at 2277 rows/s
          jobs summary: defined: 1 run: 1 with success: 1 with failure: 0
          shell>

The following table includes options that are specific to
'ndb_import'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndb_import'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_import program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Dump core on any fatal
' --abort-on-error '     error; used for          ADDED: NDB 7.6.2
                         debugging

                         For table with hidden
' --ai-increment=# '     PK, specify              ADDED: NDB 7.6.2
                         autoincrement
                         increment.  See mysqld

                         For table with hidden
' --ai-offset=# '        PK, specify              ADDED: NDB 7.6.2
                         autoincrement offset.
                         See mysqld

                         For table with hidden
' --ai-prefetch-sz=# '   PK, specify number of    ADDED: NDB 7.6.2
                         autoincrement values
                         that are prefetched.
                         See mysqld

                         Number of cluster
' --connections=# '      connections to create    ADDED: NDB 7.6.2

                         When job fails,
' --continue '           continue to next job     ADDED: NDB 7.6.2

                         Number of threads, per
' --db-workers=# '       data node, executing     ADDED: NDB 7.6.2
                         database operations

                         Error insert type, for
' --errins-type=name '   testing purposes; use    ADDED: NDB 7.6.2
                         "list" to obtain all
                         possible values

                         Error insert delay in
' --errins-delay=# '     milliseconds; random     ADDED: NDB 7.6.2
                         variation is added

                         Same as FIELDS
'                        ENCLOSED BY option for   ADDED: NDB 7.6.2
--fields-enclosed-by=charLOAD DATA statements.
'                        For CSV input this is
                         same as using
                         -fields-optionally-enclosed-by

                         Same as FIELDS ESCAPED
'                        BY option for LOAD       ADDED: NDB 7.6.2
--fields-escaped-by=name DATA statements
'

'                        Same as FIELDS           ADDED: NDB 7.6.2
--fields-optionally-enclosed-by=charOPTIONALLY ENCLOSED BY
'                        option for LOAD DATA
                         statements

                         Same as FIELDS
'                        TERMINATED BY option     ADDED: NDB 7.6.2
--fields-terminated-by=charfor LOAD DATA
'                        statements.

                         Number of milliseconds
' --idlesleep=# '        to sleep waiting for     ADDED: NDB 7.6.2
                         more to do

                         Number of times to
' --idlespin=# '         re-try before            ADDED: NDB 7.6.2
                         idlesleep

                         Ignore first # lines
' --ignore-lines=# '     in input file.  Used     ADDED: NDB 7.6.2
                         to skip a non-data
                         header.

                         Input type: random or
' --input-type=name '    csv                      ADDED: NDB 7.6.2

                         Number of threads
' --input-workers=# '    processing input.        ADDED: NDB 7.6.2
                         Must be 2 or more if
                         -input-type is csv.

                         Same as LINES
'                        TERMINATED BY option     ADDED: NDB 7.6.2
--lines-terminated-by=namefor LOAD DATA
'                        statements

                         Import only this
' --max-rows=# '         number of input data     ADDED: NDB 7.6.2
                         rows; default is 0,
                         which imports all rows

                         Periodically print
' --monitor=# '          status of running job    ADDED: NDB 7.6.2
                         if something has
                         changed (status,
                         rejected rows,
                         temporary errors).
                         Value 0 disables.
                         Value 1 prints any
                         change seen.  Higher
                         values reduce status
                         printing exponentially
                         up to some pre-defined
                         limit.

                         Run database
' --no-asynch '          operations as batches,   ADDED: NDB 7.6.2
                         in single transactions

                         Do not use
' --no-hint '            distribution key hint    ADDED: NDB 7.6.2
                         to select data node
                         (TC)

                         A db execution batch
' --opbatch=# '          is a set of              ADDED: NDB 7.6.2
                         transactions and
                         operations sent to NDB
                         kernel.  This option
                         limits NDB operations
                         (including blob
                         operations) in a db
                         execution batch.
                         Therefore it also
                         limits number of
                         asynch transactions.
                         Value 0 is not valid

                         Limit bytes in
' --opbytes=# '          execution batch          ADDED: NDB 7.6.2
                         (default 0 = no limit)

                         Output type: ndb is
' --output-type=name '   default, null used for   ADDED: NDB 7.6.2
                         testing

                         Number of threads
' --output-workers=# '   processing output or     ADDED: NDB 7.6.2
                         relaying database
                         operations

                         Align I/O buffers to
' --pagesize=# '         given size               ADDED: NDB 7.6.2

                         Size of I/O buffers as
' --pagecnt=# '          multiple of page size.   ADDED: NDB 7.6.2
                         CSV input worker
                         allocates a
                         double-sized buffer

                         Timeout per poll for
' --polltimeout=# '      completed asynchonous    ADDED: NDB 7.6.2
                         transactions; polling
                         continues until all
                         polls are completed,
                         or error occurs

                         Limit number of
' --rejects=# '          rejected rows (rows      ADDED: NDB 7.6.2
                         with permanent error)
                         in data load.  Default
                         is 0 which means that
                         any rejected row
                         causes a fatal error.
                         The row exceeding the
                         limit is also added to
                         *.rej

                         If job aborted
' --resume '             (temporary error, user   ADDED: NDB 7.6.2
                         interrupt), resume
                         with rows not yet
                         processed

                         Limit rows in row
' --rowbatch=# '         queues (default 0 = no   ADDED: NDB 7.6.2
                         limit); must be 1 or
                         more if -input-type is
                         random

                         Limit bytes in row
' --rowbytes=# '         queues (0 = no limit)    ADDED: NDB 7.6.2

                         Where to write state
' --state-dir=name '     files; currect           ADDED: NDB 7.6.2
                         directory is default

                         Number of milliseconds
' --tempdelay=# '        to sleep between         ADDED: NDB 7.6.2
                         temporary errors

                         Number of times a
' --temperrors=# '       transaction can fail     ADDED: NDB 7.6.2
                         due to a temporary
                         error, per execution
                         batch; 0 means any
                         temporary error is
                         fatal.  Such errors do
                         not cause any rows to
                         be written to .rej
                         file

                         Verbosity level for
'--verbose=#',           debug messages           ADDED: NDB 7.6.2
                         (maximum is 4 for
' -v '                   debug builds)

   *
     '--abort-on-error'

     Property                             Value

     *Command-Line Format*                '--abort-on-error'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         boolean

     *Default Value* (>=                  'FALSE'
     5.7.18-ndb-7.6.2)

     Dump core on any fatal error; used for debugging only.

   *
     '--ai-increment'=#

     Property                             Value

     *Command-Line Format*                '--ai-increment=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     For a table with a hidden primary key, specify the autoincrement
     increment, like the the 'auto_increment_increment' system variable
     does in the MySQL Server.

   *
     '--ai-offset'=#

     Property                             Value

     *Command-Line Format*                '--ai-offset=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     For a table with hidden primary key, specify the autoincrement
     offset.  Similar to the 'auto_increment_offset' system variable.

   *
     '--ai-prefetch-sz'=#

     Property                             Value

     *Command-Line Format*                '--ai-prefetch-sz=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1024'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     For a table with a hidden primary key, specify the number of
     autoincrement values that are prefetched.  Behaves like the
     'ndb_autoincrement_prefetch_sz' system variable does in the MySQL
     Server.

   *
     '--connections'=#

     Property                             Value

     *Command-Line Format*                '--connections=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Number of cluster connections to create.

   *
     '--continue'

     Property                             Value

     *Command-Line Format*                '--continue'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         boolean

     *Default Value* (>=                  'FALSE'
     5.7.18-ndb-7.6.2)

     When a job fails, continue to the next job.

   *
     '--db-workers'=#

     Property                             Value

     *Command-Line Format*                '--db-workers=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Number of threads, per data node, executing database operations.

   *
     '--errins-type'=NAME

     Property                             Value

     *Command-Line Format*                '--errins-type=name'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         enumeration

     *Default Value* (>=                  '[none]'
     5.7.18-ndb-7.6.2)

     *Valid Values* (>=                   'stopjob' 'stopall' 'sighup'
     5.7.18-ndb-7.6.2)                    'sigint' 'list'

     Error insert type; use 'list' as the NAME value to obtain all
     possible values.  This option is used for testing purposes only.

   *
     '--errins-delay'=#

     Property                             Value

     *Command-Line Format*                '--errins-delay=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1000'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Error insert delay in milliseconds; random variation is added.
     This option is used for testing purposes only.

   *
     '--fields-enclosed-by'=CHAR

     Property                             Value

     *Command-Line Format*                '--fields-enclosed-by=char'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         string

     *Default Value* (>=                  '[none]'
     5.7.18-ndb-7.6.2)

     This works in the same way as the 'FIELDS ENCLOSED BY' option does
     for the 'LOAD DATA' statement, specifying a
     character to be interpeted as quoting field values.  For CSV input,
     this is the same as '--fields-optionally-enclosed-by'.

   *
     '--fields-escaped-by'=NAME

     Property                             Value

     *Command-Line Format*                '--fields-escaped-by=name'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         string

     *Default Value* (>=                  '\'
     5.7.18-ndb-7.6.2)

     Specify an escape character in the same way as the 'FIELDS ESCAPED
     BY' option does for the SQL 'LOAD DATA'.
     statement.

   *
     '--fields-optionally-enclosed-by'=CHAR

     Property                             Value

     *Command-Line Format*                '--fields-optionally-enclosed-by=char'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         string

     *Default Value* (>=                  '[none]'
     5.7.18-ndb-7.6.2)

     This works in the same way as the 'FIELDS OPTIONALLY ENCLOSED BY'
     option does for the 'LOAD DATA' statement,
     specifying a character to be interpeted as optionally quoting field
     values.  For CSV input, this is the same as '--fields-enclosed-by'.

   *
     '--fields-terminated-by'=CHAR

     Property                             Value

     *Command-Line Format*                '--fields-terminated-by=char'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         string

     *Default Value* (>=                  '\t'
     5.7.18-ndb-7.6.2)

     This works in the same way as the 'FIELDS TERMINATED BY' option
     does for the 'LOAD DATA' statement, specifying a
     character to be interpeted as the field separator.

   *
     '--idlesleep'=#

     Property                             Value

     *Command-Line Format*                '--idlesleep=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Number of milliseconds to sleep waiting for more work to perform.

   *
     '--idlespin'=#

     Property                             Value

     *Command-Line Format*                '--idlespin=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Number of times to retry before sleeping.

   *
     '--ignore-lines'=#

     Property                             Value

     *Command-Line Format*                '--ignore-lines=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Cause ndb_import to ignore the first # lines of the input file.
     This can be employed to skip a file header that does not contain
     any data.

   *
     '--input-type'=NAME

     Property                             Value

     *Command-Line Format*                '--input-type=name'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         enumeration

     *Default Value* (>=                  'csv'
     5.7.18-ndb-7.6.2)

     *Valid Values* (>=                   'random' 'csv'
     5.7.18-ndb-7.6.2)

     Set the type of input type.  The default is 'csv'; 'random' is
     intended for testing purposes only.  .

   *
     '--input-workers'=#

     Property                             Value

     *Command-Line Format*                '--input-workers=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '2'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set the number of threads processing input.

   *
     '--lines-terminated-by'=NAME

     Property                             Value

     *Command-Line Format*                '--lines-terminated-by=name'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         string

     *Default Value* (>=                  '\n'
     5.7.18-ndb-7.6.2)

     This works in the same way as the 'LINES TERMINATED BY' option does
     for the 'LOAD DATA' statement, specifying a
     character to be interpeted as end-of-line.

   *
     '--max-rows'=#

     Property                             Value

     *Command-Line Format*                '--max-rows=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Import only this number of input data rows; the default is 0, which
     imports all rows.

   *
     '--monitor'=#

     Property                             Value

     *Command-Line Format*                '--monitor=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '2'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Periodically print the status of a running job if something has
     changed (status, rejected rows, temporary errors).  Set to 0 to
     disable this reporting.  Setting to 1 prints any change that is
     seen.  Higher values reduce the frequency of this status reporting.

   *
     '--no-asynch'

     Property                             Value

     *Command-Line Format*                '--no-asynch'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         boolean

     *Default Value* (>=                  'FALSE'
     5.7.18-ndb-7.6.2)

     Run database operations as batches, in single transactions.

   *
     '--no-hint'

     Property                             Value

     *Command-Line Format*                '--no-hint'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         boolean

     *Default Value* (>=                  'FALSE'
     5.7.18-ndb-7.6.2)

     Do not use distribution key hinting to select a data node.

   *
     '--opbatch'=#

     Property                             Value

     *Command-Line Format*                '--opbatch=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '256'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set a limit on the number of operations (including blob
     operations), and thus the number of asynchronous transactions, per
     execution batch.

   *
     '--opbytes'=#

     Property                             Value

     *Command-Line Format*                '--opbytes=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set a limit on the number of bytes per execution batch.  Use 0 for
     no limit.

   *
     '--output-type'=NAME

     Property                             Value

     *Command-Line Format*                '--output-type=name'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         enumeration

     *Default Value* (>=                  'ndb'
     5.7.18-ndb-7.6.2)

     *Valid Values* (>=                   'null'
     5.7.18-ndb-7.6.2)

     Set the output type.  'ndb' is the default.  'null' is used only
     for testing.

   *
     '--output-workers'=#

     Property                             Value

     *Command-Line Format*                '--output-workers=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '2'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set the number of threads processing output or relaying database
     operations.

   *
     '--pagesize'=#

     Property                             Value

     *Command-Line Format*                '--pagesize=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '4096'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Align I/O buffers to the given size.

   *
     '--pagecnt'=#

     Property                             Value

     *Command-Line Format*                '--pagecnt=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '64'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set the size of I/O buffers as multiple of page size.  The CSV
     input worker allocates buffer that is doubled in size.

   *
     '--polltimeout'=#

     Property                             Value

     *Command-Line Format*                '--polltimeout=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '1000'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '1'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set a timeout per poll for completed asynchonous transactions;
     polling continues until all polls are completed, or until an error
     occurs.

   *
     '--rejects'=#

     Property                             Value

     *Command-Line Format*                '--rejects=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Limit the number of rejected rows (rows with permanent errors) in
     the data load.  The default is 0, which means that any rejected row
     causes a fatal error.  The row causing the limit to be exceeded is
     added to the '.rej' file.

   *
     '--resume'

     Property                             Value

     *Command-Line Format*                '--resume'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         boolean

     *Default Value* (>=                  'FALSE'
     5.7.18-ndb-7.6.2)

     If a job is aborted (due to a temporary db error or when
     interrupted by the user), resume with any rows not yet processed.

   *
     '--rowbatch'=#

     Property                             Value

     *Command-Line Format*                '--rowbatch=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set a limit on the number of rows per row queue.  Use 0 for no
     limit.

   *
     '--rowbytes'=#

     Property                             Value

     *Command-Line Format*                '--rowbytes=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '262144'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Set a limit on the number of bytes per row queue.  Use 0 for no
     limit.

   *
     ' --state-dir'=NAME

     Property                             Value

     *Command-Line Format*                '--state-dir=name'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         string

     *Default Value* (>=                  '.'
     5.7.18-ndb-7.6.2)

     Where to write the state files ('TBL_NAME.map', 'TBL_NAME.rej',
     'TBL_NAME.res', and 'TBL_NAME.stt') produced by a run of the
     program; the default is the current directory.

   *
     '--tempdelay'=#

     Property                             Value

     *Command-Line Format*                '--tempdelay=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '10'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Number of milliseconds to sleep between temporary errors.

   *
     '--temperrors'=#

     Property                             Value

     *Command-Line Format*                '--temperrors=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '4294967295'
     5.7.18-ndb-7.6.2)

     Number of times a transaction can fail due to a temporary error,
     per execution batch.  The default is 0, which means that any
     temporary error is fatal.  Temporary errors do not cause any rows
     to be added to the '.rej' file.

   *
     '--verbose'=#, '-v'

     Property                             Value

     *Command-Line Format*                '--verbose=#'

     *Introduced*                         5.7.18-ndb-7.6.2

     *Type* (>= 5.7.18-ndb-7.6.2)         integer

     *Default Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Minimum Value* (>=                  '0'
     5.7.18-ndb-7.6.2)

     *Maximum Value* (>=                  '2'
     5.7.18-ndb-7.6.2)

     Verbosity level for debugging messages.

As with 'LOAD DATA INFILE', options for field and line formatting much
match those used to create the CSV file, whether this was done using
'SELECT INTO OUTFILE', or by some other means.  There is no equivalent
to the 'LOAD DATA INFILE' statement's 'STARTING WITH' option.

'ndb_import' was added in NDB
7.6.2.

21.4.15 'ndb_index_stat' -- NDB Index Statistics Utility
--------------------------------------------------------

'ndb_index_stat' provides
per-fragment statistical information about indexes on 'NDB' tables.
This includes cache version and age, number of index entries per
partition, and memory consumption by indexes.

*Usage*

To obtain basic index statistics about a given 'NDB'
table, invoke 'ndb_index_stat'
as shown here, with the name of
the table as the first argument and the name of the database containing
this table specified immediately following it, using the '--database'
('-d') option:

     ndb_index_stat TABLE -d DATABASE

In this example, we use 'ndb_index_stat'
to obtain such information about
an 'NDB' table named 'mytable' in the 'test' database:

     shell> ndb_index_stat -d test mytable
     table:City index:PRIMARY fragCount:2
     sampleVersion:3 loadTime:1399585986 sampleCount:1994 keyBytes:7976
     query cache: valid:1 sampleCount:1994 totalBytes:27916
     times in ms: save: 7.133 sort: 1.974 sort per sample: 0.000

     NDBT_ProgramExit: 0 - OK

'sampleVersion' is the version number of the cache from which the
statistics data is taken.  Running 'ndb_index_stat'
with the '--update' option causes
sampleVersion to be incremented.

'loadTime' shows when the cache was last updated.  This is expressed as
seconds since the Unix Epoch.

'sampleCount' is the number of index entries found per partition.  You
can estimate the total number of entries by multiplying this by the
number of fragments (shown as 'fragCount').

'sampleCount' can be compared with the cardinality of 'SHOW INDEX'
or 'INFORMATION_SCHEMA.STATISTICS',
although the latter two provide a view of the table as
a whole, while 'ndb_index_stat'
provides a per-fragment average.

'keyBytes' is the number of bytes used by the index.  In this example,
the primary key is an integer, which requires four bytes for each index,
so 'keyBytes' can be calculated in this case as shown here:

         keyBytes = sampleCount * (4 bytes per index) = 1994 * 4 = 7976

This information can also be obtained using the corresponding column
definitions from 'INFORMATION_SCHEMA.COLUMNS'.
(this requires a MySQL Server and a MySQL client application).

'totalBytes' is the total memory consumed by all indexes on the table,
in bytes.

Timings shown in the preceding examples are specific to each invocation
of 'ndb_index_stat'.

The '--verbose' option provides some additional output, as shown here:

     shell> ndb_index_stat -d test mytable --verbose
     random seed 1337010518
     connected
     loop 1 of 1
     table:mytable index:PRIMARY fragCount:4
     sampleVersion:2 loadTime:1336751773 sampleCount:0 keyBytes:0
     read stats
     query cache created
     query cache: valid:1 sampleCount:0 totalBytes:0
     times in ms: save: 20.766 sort: 0.001
     disconnected

     NDBT_ProgramExit: 0 - OK

     shell>

If the only output from the program is 'NDBT_ProgramExit: 0 - OK', this
may indicate that no statistics yet exist.  To force them to be created
(or updated if they already exist), invoke 'ndb_index_stat'
with the '--update' option, or
execute 'ANALYZE TABLE' on the table in the
'mysql' client.

*Options*

The following table includes options that are specific to the NDB
Cluster 'ndb_index_stat'.
utility.  Additional descriptions are listed following the table.  For
options common to most NDB Cluster programs (including
'ndb_index_stat'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_index_stat program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Name of the database
'--database=name',       containing the table.    All MySQL 5.7 based
                                                  releases
' -d '

' --delete '             Delete index             All MySQL 5.7 based
                         statistics for the       releases
                         given table, stopping
                         any auto-update
                         previously configured.

                         Update index
' --update '             statistics for the       All MySQL 5.7 based
                         given table,             releases
                         restarting any
                         auto-update previously
                         configured.

                         Print the query cache.
' --dump '                                        All MySQL 5.7 based
                                                  releases

                         Perform a number of
' --query=# '            random range queries     All MySQL 5.7 based
                         on first key attr        releases
                         (must be int
                         unsigned).

                         Drop any statistics
' --sys-drop '           tables and events in     All MySQL 5.7 based
                         NDB kernel (all          releases
                         statistics are lost)

                         Create all statistics
' --sys-create '         tables and events in     All MySQL 5.7 based
                         NDB kernel, if none of   releases
                         them already exist

                         Create any statistics
'                        tables and events in     All MySQL 5.7 based
--sys-create-if-not-existNDB kernel that do not   releases
'                        already exist.

                         Create any statistics
'                        tables or events that    All MySQL 5.7 based
--sys-create-if-not-validdo not already exist     releases
'                        in the NDB kernel.
                         after dropping any
                         that are invalid.

                         Verify that NDB system
' --sys-check '          index statistics and     All MySQL 5.7 based
                         event tables exist.      releases

                         Do not apply sys-*
' --sys-skip-tables '    options to tables.       All MySQL 5.7 based
                                                  releases

                         Do not apply sys-*
' --sys-skip-events '    options to events.       All MySQL 5.7 based
                                                  releases

                         Turn on verbose output
'--verbose',                                      All MySQL 5.7 based
                                                  releases
' -v '

' --loops=# '            Set the number of        All MySQL 5.7 based
                         times to perform a       releases
                         given command.
                         Default is 0.

ndb_index_stat statistics options

The following options are used to generate index statistics.  They work
with a given table and database.  They cannot be mixed with system
options (see ndb-index-stat-options-system).

   *
     '--database=NAME', '-d NAME'

     Property                             Value

     *Command-Line Format*                '--database=name'

     *Type*                               string

     *Default Value*                      '[none]'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     The name of the database that contains the table being queried.

   *
     '--delete'

     Property                             Value

     *Command-Line Format*                '--delete'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Delete the index statistics for the given table, stopping any
     auto-update that was previously configured.

   *
     '--update'

     Property                             Value

     *Command-Line Format*                '--update'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Update the index statistics for the given table, and restart any
     auto-update that was previously configured.

   *
     '--dump'

     Property                             Value

     *Command-Line Format*                '--dump'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Dump the contents of the query cache.

   *
     '--query=#'

     Property                             Value

     *Command-Line Format*                '--query=#'

     *Type*                               numeric

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      'MAX_INT'

     Perform random range queries on first key attribute (must be int
     unsigned).

ndb_index_stat system options

The following options are used to generate and update the statistics
tables in the NDB kernel.  None of these options can be mixed with
statistics options (see ndb-index-stat-options-statistics).

   *
     '--sys-drop'

     Property                             Value

     *Command-Line Format*                '--sys-drop'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Drop all statistics tables and events in the NDB kernel.  _This
     causes all statistics to be lost_.

   *
     '--sys-create'

     Property                             Value

     *Command-Line Format*                '--sys-create'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Create all statistics tables and events in the NDB kernel.  This
     works only if none of them exist previously.

   *
     'sys-create-if-not-exist'

     Property                             Value

     *Command-Line Format*                '--sys-create-if-not-exist'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Create any NDB system statistics tables or events (or both) that do
     not already exist when the program is invoked.

   *
     '--sys-create-if-not-valid'

     Property                             Value

     *Command-Line Format*                '--sys-create-if-not-valid'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Create any NDB system statistics tables or events that do not
     already exist, after dropping any that are invalid.

   *
     '--sys-check'

     Property                             Value

     *Command-Line Format*                '--sys-check'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Verify that all required system statistics tables and events exist
     in the NDB kernel.

   *
     '--sys-skip-tables'

     Property                             Value

     *Command-Line Format*                '--sys-skip-tables'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Do not apply any '--sys-*' options to any statistics tables.

   *
     '--sys-skip-events'

     Property                             Value

     *Command-Line Format*                '--sys-skip-events'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Do not apply any '--sys-*' options to any events.

   *
     '--verbose'

     Property                             Value

     *Command-Line Format*                '--verbose'

     *Type*                               boolean

     *Default Value*                      'false'

     *Minimum Value*                      ''

     *Maximum Value*                      ''

     Turn on verbose output.

   *
     '--loops=#'

     Property                             Value

     *Command-Line Format*                '--loops=#'

     *Type*                               numeric

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      'MAX_INT'

     Repeat commands this number of times (for use in testing).

21.4.16 'ndb_move_data' -- NDB Data Copy Utility
------------------------------------------------

'ndb_move_data' copies data
from one NDB table to another.

*Usage*

The program is invoked with the names of the source and target tables;
either or both of these may be qualified optionally with the database
name.  Both tables must use the NDB storage engine.

     ndb_move_data OPTIONS SOURCE TARGET

The following table includes options that are specific to
'ndb_move_data'.  Additional
descriptions follow the table.  For options common to most NDB Cluster
programs (including 'ndb_move_data'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_move_data program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Dump core on permanent
' --abort-on-error '     error (debug option)     All MySQL 5.7 based
                                                  releases

                         Directory where
'                        character sets are       All MySQL 5.7 based
--character-sets-dir=name                         releases
'

'--database=dbname',     Name of the database     All MySQL 5.7 based
                         in which the table is    releases
' -d '                   found

                         Drop source table
' --drop-source '        after all rows have      All MySQL 5.7 based
                         been moved               releases

                         Insert random
' --error-insert '       temporary errors         All MySQL 5.7 based
                         (testing option)         releases

                         Ignore extra columns
'                        in source or target      All MySQL 5.7 based
--exclude-missing-columnstable                    releases
'

'--lossy-conversions',   Allow attribute data     All MySQL 5.7 based
                         to be truncated when     releases
' -l '                   converted to a smaller
                         type

                         Allow attribute data
'--promote-attributes',  to be converted to a     All MySQL 5.7 based
                         larger type              releases
' -A '

'                        Specify tries on         All MySQL 5.7 based
--staging-tries=x[,y[,z]]temporary errors.        releases
'                        Format is x[,y[,z]]
                         where x=max tries
                         (0=no limit), y=min
                         delay (ms), z=max
                         delay (ms)

                         Enable verbose
' --verbose '            messages                 All MySQL 5.7 based
                                                  releases

   *
     '--abort-on-error'

     Property                             Value

     *Command-Line Format*                '--abort-on-error'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Dump core on permanent error (debug option).

   *
     '--character-sets-dir'=NAME

     Property                             Value

     *Command-Line Format*                '--character-sets-dir=name'

     *Type*                               string

     *Default Value*                      '[none]'

     Directory where character sets are.

   *
     '--database'=DBNAME, '-d'

     Property                             Value

     *Command-Line Format*                '--database=dbname'

     *Type*                               string

     *Default Value*                      'TEST_DB'

     Name of the database in which the table is found.

   *
     '--drop-source'

     Property                             Value

     *Command-Line Format*                '--drop-source'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Drop source table after all rows have been moved.

   *
     '--error-insert'

     Property                             Value

     *Command-Line Format*                '--error-insert'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Insert random temporary errors (testing option).

   *
     '--exclude-missing-columns'

     Property                             Value

     *Command-Line Format*                '--exclude-missing-columns'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Ignore extra columns in source or target table.

   *
     '--lossy-conversions', '-l'

     Property                             Value

     *Command-Line Format*                '--lossy-conversions'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Allow attribute data to be truncated when converted to a smaller
     type.

   *
     '--promote-attributes', '-A'

     Property                             Value

     *Command-Line Format*                '--promote-attributes'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Allow attribute data to be converted to a larger type.

   *
     '--staging-tries'=X[,Y[,Z]]

     Property                             Value

     *Command-Line Format*                '--staging-tries=x[,y[,z]]'

     *Type*                               string

     *Default Value*                      '0,1000,60000'

     Specify tries on temporary errors.  Format is x[,y[,z]] where x=max
     tries (0=no limit), y=min delay (ms), z=max delay (ms).

   *
     '--verbose'

     Property                             Value

     *Command-Line Format*                '--verbose'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Enable verbose messages.

21.4.17 'ndb_perror' -- Obtain NDB error message information
------------------------------------------------------------

'ndb_perror' shows information
about an NDB error, given its error code.  This includes the error
message, the type of error, and whether the error is permanent or
temporary.  Added to the MySQL NDB Cluster distribution in NDB 7.6.4, it
is intended as a drop-in replacement for 'perror'.
'--ndb'.

*Usage*

     ndb_perror [OPTIONS] ERROR_CODE

'ndb_perror' does not need to
access a running NDB Cluster, or any nodes (including SQL nodes).  To
view information about a given NDB error, invoke the program, using the
error code as an argument, like this:

     shell> ndb_perror 323
     NDB error code 323: Invalid nodegroup id, nodegroup already existing: Permanent error: Application error

To display only the error message, invoke 'ndb_perror'
with the '--silent' option (short
form '-s'), as shown here:

     shell> ndb_perror -s 323
     Invalid nodegroup id, nodegroup already existing: Permanent error: Application error

Like 'perror', 'ndb_perror'
accepts multiple error codes:

     shell> ndb_perror 321 1001
     NDB error code 321: Invalid nodegroup id: Permanent error: Application error
     NDB error code 1001: Illegal connect string

Additional program options for 'ndb_perror'
are described later in this section.

'ndb_perror' replaces
'perror'. '--ndb', which is deprecated as of NDB 7.6.4 and
subject to removal in a future release of MySQL NDB Cluster.  To make
substitution easier in scripts and other applications that might depend
on 'perror' for obtaining NDB error information, see
'ndb_perror' supports its own
'dummy' '--ndb' option, which does nothing.

The following table includes all options that are specific to the NDB
Cluster program 'ndb_perror'.
Additional descriptions follow the table.

*Command-line options for the ndb_perror program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Display help text
'--help',                                         ADDED: NDB 7.6.4

' -? '

' --ndb '                For compatibility with   ADDED: NDB 7.6.4
                         applications depending
                         on old versions of
                         perror; does nothing

                         Show error message
'--silent',              only                     ADDED: NDB 7.6.4

' -s '

'--version',             Print program version    ADDED: NDB 7.6.4
                         information and exit
' -V '

'--verbose',             Verbose output;          ADDED: NDB 7.6.4
                         disable with -silent
' -v '

*Additional Options*

   *
     '--help', '-?'

     Property                             Value

     *Command-Line Format*                '--help'

     *Introduced*                         5.7.19-ndb-7.6.4

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Display program help text and exit.

   *
     '--ndb'

     Property                             Value

     *Command-Line Format*                '--ndb'

     *Introduced*                         5.7.19-ndb-7.6.4

     *Type*                               boolean

     *Default Value*                      'TRUE'

     For compatibility with applications depending on old versions of
     'perror' that use that program's '--ndb' option.
     The option when used with 'ndb_perror'
     does nothing, and is ignored by
     it.

   *
     '--silent', '-s'

     Property                             Value

     *Command-Line Format*                '--silent'

     *Introduced*                         5.7.19-ndb-7.6.4

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Show error message only.

   *
     '--version', '-V'

     Property                             Value

     *Command-Line Format*                '--version'

     *Introduced*                         5.7.19-ndb-7.6.4

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Print program version information and exit.

   *
     '--verbose', '-v'

     Property                             Value

     *Command-Line Format*                '--verbose'

     *Introduced*                         5.7.19-ndb-7.6.4

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Verbose output; disable with '--silent'.

21.4.18 'ndb_print_backup_file' -- Print NDB Backup File Contents
-----------------------------------------------------------------

'ndb_print_backup_file'
obtains diagnostic
information from a cluster backup file.

*Usage*

     ndb_print_backup_file FILE_NAME

FILE_NAME is the name of a cluster backup file.  This can be any of the
files ('.Data', '.ctl', or '.log' file) found in a cluster backup
directory.  These files are found in the data node's backup directory
under the subdirectory 'BACKUP-#', where # is the sequence number for
the backup.  For more information about cluster backup files and their
contents, see mysql-cluster-backup-concepts.

Like 'ndb_print_schema_file'
and
'ndb_print_sys_file'. (and
unlike most of the other 'NDB' utilities that are
intended to be run on a management server host or to connect to a
management server) 'ndb_print_backup_file'
must be run on a cluster
data node, since it accesses the data node file system directly.
Because it does not make use of the management server, this utility can
be used when the management server is not running, and even when the
cluster has been completely shut down.

*Additional Options*

None.

21.4.19 'ndb_print_file' -- Print NDB Disk Data File Contents
-------------------------------------------------------------

'ndb_print_file' obtains
information from an NDB Cluster Disk Data file.

*Usage*

     ndb_print_file [-v] [-q] FILE_NAME+

FILE_NAME is the name of an NDB Cluster Disk Data file.  Multiple
filenames are accepted, separated by spaces.

Like 'ndb_print_schema_file'
and
'ndb_print_sys_file'. (and
unlike most of the other 'NDB' utilities that are
intended to be run on a management server host or to connect to a
management server) 'ndb_print_file'
must be run on an NDB Cluster
data node, since it accesses the data node file system directly.
Because it does not make use of the management server, this utility can
be used when the management server is not running, and even when the
cluster has been completely shut down.

*Additional Options*

'ndb_print_file' supports
the following options:

   * '-v': Make output verbose.

   * '-q': Suppress output (quiet mode).

   * '--help', '-h', '-?': Print help message.

For more information, see mysql-cluster-disk-data.

21.4.20 'ndb_print_frag_file' -- Print NDB Fragment List File Contents
----------------------------------------------------------------------

See 'ndb_print_frag_file'.
obtains information from a cluster fragment list file.  It is intended
for use in helping to diagnose issues with data node restarts.

*Usage*

     ndb_print_frag_file FILE_NAME

FILE_NAME is the name of a cluster fragment list file, which matches the
pattern 'SX.FragList', where X is a digit in the range 2-9 inclusive,
and are found in the data node file system of the data node having the
node ID NODEID, in directories named 'ndb_NODEID_fs/DN/DBDIH/', where N
is '1' or '2'.  Each fragment file contains records of the fragments
belonging to each 'NDB' table.  For more information about cluster
fragment files, see NDB Cluster Data Node File System Directory Files
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndbd-filesystemdir-files.html).

Like 'ndb_print_backup_file',
see
'ndb_print_sys_file', and
'ndb_print_schema_file'.
(and unlike most of the
other 'NDB' utilities that are intended to be run
on a management server host or to connect to a management server), see
'ndb_print_frag_file' must
be run on a cluster data node, since it accesses the data node file
system directly.  Because it does not make use of the management server,
this utility can be used when the management server is not running, and
even when the cluster has been completely shut down.

*Additional Options*

None.

*Sample Output*

     shell> ndb_print_frag_file /usr/local/mysqld/data/ndb_3_fs/D1/DBDIH/S2.FragList
     Filename: /usr/local/mysqld/data/ndb_3_fs/D1/DBDIH/S2.FragList with size 8192
     noOfPages = 1 noOfWords = 182
     Table Data
     ----------
     Num Frags: 2 NoOfReplicas: 2 hashpointer: 4294967040
     kvalue: 6 mask: 0x00000000 method: HashMap
     Storage is on Logged and checkpointed, survives SR
     ------ Fragment with FragId: 0 --------
     Preferred Primary: 2 numStoredReplicas: 2 numOldStoredReplicas: 0 distKey: 0 LogPartId: 0
     -------Stored Replica----------
     Replica node is: 2 initialGci: 2 numCrashedReplicas = 0 nextLcpNo = 1
     LcpNo[0]: maxGciCompleted: 1 maxGciStarted: 2 lcpId: 1 lcpStatus: valid
     LcpNo[1]: maxGciCompleted: 0 maxGciStarted: 0 lcpId: 0 lcpStatus: invalid
     -------Stored Replica----------
     Replica node is: 3 initialGci: 2 numCrashedReplicas = 0 nextLcpNo = 1
     LcpNo[0]: maxGciCompleted: 1 maxGciStarted: 2 lcpId: 1 lcpStatus: valid
     LcpNo[1]: maxGciCompleted: 0 maxGciStarted: 0 lcpId: 0 lcpStatus: invalid
     ------ Fragment with FragId: 1 --------
     Preferred Primary: 3 numStoredReplicas: 2 numOldStoredReplicas: 0 distKey: 0 LogPartId: 1
     -------Stored Replica----------
     Replica node is: 3 initialGci: 2 numCrashedReplicas = 0 nextLcpNo = 1
     LcpNo[0]: maxGciCompleted: 1 maxGciStarted: 2 lcpId: 1 lcpStatus: valid
     LcpNo[1]: maxGciCompleted: 0 maxGciStarted: 0 lcpId: 0 lcpStatus: invalid
     -------Stored Replica----------
     Replica node is: 2 initialGci: 2 numCrashedReplicas = 0 nextLcpNo = 1
     LcpNo[0]: maxGciCompleted: 1 maxGciStarted: 2 lcpId: 1 lcpStatus: valid
     LcpNo[1]: maxGciCompleted: 0 maxGciStarted: 0 lcpId: 0 lcpStatus: invalid

21.4.21 'ndb_print_schema_file' -- Print NDB Schema File Contents
-----------------------------------------------------------------

'ndb_print_schema_file'
obtains diagnostic
information from a cluster schema file.

*Usage*

     ndb_print_schema_file FILE_NAME

FILE_NAME is the name of a cluster schema file.  For more information
about cluster schema files, see NDB Cluster Data Node File System
Directory Files
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndbd-filesystemdir-files.html).

Like 'ndb_print_backup_file'
and
'ndb_print_sys_file'. (and
unlike most of the other 'NDB' utilities that are
intended to be run on a management server host or to connect to a
management server) 'ndb_print_schema_file'
must be run on a cluster
data node, since it accesses the data node file system directly.
Because it does not make use of the management server, this utility can
be used when the management server is not running, and even when the
cluster has been completely shut down.

*Additional Options*

None.

21.4.22 'ndb_print_sys_file' -- Print NDB System File Contents
--------------------------------------------------------------

See 'ndb_print_sys_file'.
obtains diagnostic information from an NDB Cluster system file.

*Usage*

     ndb_print_sys_file FILE_NAME

FILE_NAME is the name of a cluster system file (sysfile).  Cluster
system files are located in a data node's data directory ('DataDir');
the path under this directory to system files matches the pattern
'ndb_#_fs/D#/DBDIH/P#.sysfile'.  In each case, the # represents a number
(not necessarily the same number).  For more information, see NDB
Cluster Data Node File System Directory Files
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndbd-filesystemdir-files.html).

Like 'ndb_print_backup_file'
and
'ndb_print_schema_file'.
(and unlike most of the other 'NDB' utilities that
are intended to be run on a management server host or to connect to a
management server) 'ndb_print_backup_file'
must be run on a cluster
data node, since it accesses the data node file system directly.
Because it does not make use of the management server, this utility can
be used when the management server is not running, and even when the
cluster has been completely shut down.

*Additional Options*

None.

21.4.23 'ndb_redo_log_reader' -- Check and Print Content of Cluster Redo Log
----------------------------------------------------------------------------

Reads a redo log file, checking it for errors, printing its contents in
a human-readable format, or both.  'ndb_redo_log_reader'
is intended for use
primarily by NDB Cluster developers and Support personnel in debugging
and diagnosing problems.

This utility remains under development, and its syntax and behavior are
subject to change in future NDB Cluster releases.

*Note*:

Prior to NDB 7.2, this utility was named 'ndbd_redo_log_reader'.

The C++ source files for 'ndb_redo_log_reader'
can be found in the
directory '/storage/ndb/src/kernel/blocks/dblqh/redoLogReader'.

The following table includes options that are specific to the NDB
Cluster program 'ndb_redo_log_reader'.
Additional descriptions
follow the table.  For options common to most NDB Cluster programs
(including 'ndb_redo_log_reader'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_redo_log_reader program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Print dump info
' -dump '                                         All MySQL 5.7 based
                                                  releases

                         Print file descriptors
' -filedescriptors '     only                     All MySQL 5.7 based
                                                  releases

                         Print usage
' --help '               information              All MySQL 5.7 based
                                                  releases

                         Provide lap info, with
' -lap '                 max GCI started and      All MySQL 5.7 based
                         completed                releases

                         Starting megabyte
' -mbyte # '                                      All MySQL 5.7 based
                                                  releases

                         Show only the first
' -mbyteheaders '        page header of every     All MySQL 5.7 based
                         megabyte in the file     releases

                         Do not check records
' -nocheck '             for errors               All MySQL 5.7 based
                                                  releases

                         Do not print records
' -noprint '                                      All MySQL 5.7 based
                                                  releases

                         Start with this page
' -page # '                                       All MySQL 5.7 based
                                                  releases

                         Show page headers only
' -pageheaders '                                  All MySQL 5.7 based
                                                  releases

                         Start with this page
' -pageindex # '         index                    All MySQL 5.7 based
                                                  releases

                         Bit-shifted dump
' -twiddle '                                      All MySQL 5.7 based
                                                  releases

*Usage*

     ndb_redo_log_reader FILE_NAME [OPTIONS]

FILE_NAME is the name of a cluster redo log file.  redo log files are
located in the numbered directories under the data node's data directory
('DataDir'); the path under this directory to the redo log files matches
the pattern 'ndb_NODEID_fs/D#/DBLQH/S#.FragLog'.  NODEID is the data
node's node ID. The two instances of # each represent a number (not
necessarily the same number); the number following 'D' is in the range
8-39 inclusive; the range of the number following 'S' varies according
to the value of the 'NoOfFragmentLogFiles' configuration parameter,
whose default value is 16; thus, the default range of the number in the
file name is 0-15 inclusive.  For more information, see NDB Cluster Data
Node File System Directory Files
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndbd-filesystemdir-files.html).

The name of the file to be read may be followed by one or more of the
options listed here:

   *
     '-dump'

     Property                             Value

     *Command-Line Format*                '-dump'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Print dump info.

   *
     Property                             Value

     *Command-Line Format*                '-filedescriptors'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     '-filedescriptors': Print file descriptors only.

   *
     Property                             Value

     *Command-Line Format*                '--help'

     '--help': Print usage information.

   *
     '-lap'

     Property                             Value

     *Command-Line Format*                '-lap'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Provide lap info, with max GCI started and completed.

   *
     Property                             Value

     *Command-Line Format*                '-mbyte #'

     *Type*                               numeric

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '15'

     '-mbyte #': Starting megabyte.

     # is an integer in the range 0 to 15, inclusive.

   *
     Property                             Value

     *Command-Line Format*                '-mbyteheaders'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     '-mbyteheaders': Show only the first page header of every megabyte
     in the file.

   *
     Property                             Value

     *Command-Line Format*                '-noprint'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     '-noprint': Do not print the contents of the log file.

   *
     Property                             Value

     *Command-Line Format*                '-nocheck'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     '-nocheck': Do not check the log file for errors.

   *
     Property                             Value

     *Command-Line Format*                '-page #'

     *Type*                               integer

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '31'

     '-page #': Start at this page.

     # is an integer in the range 0 to 31, inclusive.

   *
     Property                             Value

     *Command-Line Format*                '-pageheaders'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     '-pageheaders': Show page headers only.

   *
     Property                             Value

     *Command-Line Format*                '-pageindex #'

     *Type*                               integer

     *Default Value*                      '12'

     *Minimum Value*                      '12'

     *Maximum Value*                      '8191'

     '-pageindex #': Start at this page index.

     # is an integer between 12 and 8191, inclusive.

   *
     '-twiddle'

     Property                             Value

     *Command-Line Format*                '-twiddle'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Bit-shifted dump.

Like 'ndb_print_backup_file'
and
'ndb_print_schema_file'.
(and unlike most of the 'NDB' utilities that are
intended to be run on a management server host or to connect to a
management server) 'ndb_redo_log_reader'
must be run on a cluster
data node, since it accesses the data node file system directly.
Because it does not make use of the management server, this utility can
be used when the management server is not running, and even when the
cluster has been completely shut down.

21.4.24 'ndb_restore' -- Restore an NDB Cluster Backup
------------------------------------------------------

The cluster restoration program is implemented as a separate
command-line utility 'ndb_restore',
which can normally be found in the
MySQL 'bin' directory.  This program reads the files created as a result
of the backup and inserts the stored information into the database.

'ndb_restore' must be
executed once for each of the backup files that were created by the
'START BACKUP'.
command used to create the backup (see
mysql-cluster-backup-using-management-client).  This is equal to the
number of data nodes in the cluster at the time that the backup was
created.

*Note*:

Before using 'ndb_restore', it
is recommended that the cluster be running in single user mode, unless
you are restoring multiple data nodes in parallel.  See
mysql-cluster-single-user-mode, for more information.

The following table includes options that are specific to the NDB
Cluster native backup restoration program 'ndb_restore'.
Additional descriptions follow the
table.  For options common to most NDB Cluster programs (including
'ndb_restore'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_restore program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Append data to a
' --append '             tab-delimited file       All MySQL 5.7 based
                                                  releases

                         Path to backup files
'                        directory                All MySQL 5.7 based
--backup_path=dir_name                            releases
'

'--backupid=#',          Restore from the         All MySQL 5.7 based
                         backup with the given    releases
' -b '                   ID

                         Alias for
'--connect',             -connectstring.          All MySQL 5.7 based
                                                  releases
' -c '

' --disable-indexes '    Causes indexes from a    All MySQL 5.7 based
                         backup to be ignored;    releases
                         may decrease time
                         needed to restore
                         data.

                         Do not ignore system
'--dont_ignore_systab_0',table during restore.    All MySQL 5.7 based
                         Experimental only; not   releases
' -f '                   for production use

                         List of one or more
'                        databases to exclude     All MySQL 5.7 based
--exclude-databases=db-list(includes those not    releases
'                        named)

                         If TRUE (the default),
'                        do not restore any       All MySQL 5.7 based
--exclude-intermediate-sql-tables[=TRUE|FALSE]intermediate tablesreleases
'                        (having names prefixed
                         with '#sql-') that
                         were left over from
                         copying ALTER TABLE
                         operations.

                         Causes columns from
'                        the backup version of    All MySQL 5.7 based
--exclude-missing-columnsa table that are         releases
'                        missing from the
                         version of the table
                         in the database to be
                         ignored.

                         Causes tables from the
'                        backup that are          All MySQL 5.7 based
--exclude-missing-tables missing from the         releases
'                        database to be
                         ignored.

                         List of one or more
'                        tables to exclude        All MySQL 5.7 based
--exclude-tables=table-list(includes those in the releases
'                        same database that are
                         not named); each table
                         reference must include
                         the database name

                         Fields are enclosed
'                        with the indicated       All MySQL 5.7 based
--fields-enclosed-by=charcharacter                releases
'

'                        Fields are optionally    All MySQL 5.7 based
--fields-optionally-enclosed-byenclosed with the  releases
'                        indicated character

                         Fields are terminated
'                        by the indicated         All MySQL 5.7 based
--fields-terminated-by=charcharacter              releases
'

' --hex '                Print binary types in    All MySQL 5.7 based
                         hexadecimal format       releases

                         List of one or more
'                        databases to restore     All MySQL 5.7 based
--include-databases=db-list(excludes those not    releases
'                        named)

                         List of one or more
'                        tables to restore        All MySQL 5.7 based
--include-tables=table-list(excludes those in     releases
'                        same database that are
                         not named); each table
                         reference must include
                         the database name

                         Lines are terminated
'                        by the indicated         All MySQL 5.7 based
--lines-terminated-by=charcharacter               releases
'

'--lossy-conversions',   Allow lossy              All MySQL 5.7 based
                         conversions of column    releases
' -L '                   values (type demotions
                         or changes in sign)
                         when restoring data
                         from backup

                         If a mysqld is
' --no-binlog '          connected and using      All MySQL 5.7 based
                         binary logging, do not   releases
                         log the restored data

                         Do not restore objects
'--no-restore-disk-objects',relating to Disk Data All MySQL 5.7 based
                                                  releases
' -d '

'--no-upgrade',          Do not upgrade array     All MySQL 5.7 based
                         type for varsize         releases
' -u '                   attributes which do
                         not already resize VAR
                         data, and do not
                         change column
                         attributes

                         Nodegroup map for
'--ndb-nodegroup-map=map',NDBCLUSTER storage      All MySQL 5.7 based
                         engine.  Syntax: list    releases
' -z '                   of (source_nodegroup,
                         destination_nodegroup)

                         ID of node where
'--nodeid=#',            backup was taken         All MySQL 5.7 based
                                                  releases
' -n '

'--parallelism=#',       Number of parallel       All MySQL 5.7 based
                         transactions to use      releases
' -p '                   while restoring data

                         Allow preservation of
'--preserve-trailing-spaces',trailing spaces      All MySQL 5.7 based
                         (including padding)      releases
' -P '                   when promoting
                         fixed-width string
                         types to
                         variable-width types

                         Print metadata, data
' --print '              and log to stdout        All MySQL 5.7 based
                         (equivalent to           releases
                         -print_meta
                         -print_data
                         -print_log)

                         Print data to stdout
' --print_data '                                  All MySQL 5.7 based
                                                  releases

                         Print to stdout
' --print_log '                                   All MySQL 5.7 based
                                                  releases

                         Print metadata to
' --print_meta '         stdout                   All MySQL 5.7 based
                                                  releases

                         Write SQL log to
' print-sql-log '        stdout; default is       ADDED: NDB 7.5.4
                         FALSE

                         Print status of
'                        restoration each given   All MySQL 5.7 based
--progress-frequency=#   number of seconds        releases
'

'--promote-attributes',  Allow attributes to be   All MySQL 5.7 based
                         promoted when            releases
' -A '                   restoring data from
                         backup

                         Causes multi-threaded
' --rebuild-indexes '    rebuilding of ordered    All MySQL 5.7 based
                         indexes found in the     releases
                         backup.  Number of
                         threads used is
                         determined by setting
                         BuildIndexThreads
                         parameter.

                         Restore table data and
'--restore_data',        logs into NDB Cluster    All MySQL 5.7 based
                         using the NDB API        releases
' -r '

'--restore_epoch',       Restore epoch info       All MySQL 5.7 based
                         into the status table.   releases
' -e '                   Convenient on a MySQL
                         Cluster replication
                         slave for starting
                         replication.  The row
                         in
                         mysql.ndb_apply_status
                         with id 0 will be
                         updated/inserted.

                         Restore metadata to
'--restore_meta',        NDB Cluster using the    All MySQL 5.7 based
                         NDB API                  releases
' -m '

'                        Restore MySQL            All MySQL 5.7 based
--restore-privilege-tablesprivilege tables that   releases
'                        were previously moved
                         to NDB.

                         Restores to a database
'                        with a different name    All MySQL 5.7 based
--rewrite-database=olddb,newdbthan the original   releases
'

'                        Causes missing blob      All MySQL 5.7 based
--skip-broken-objects    tables in the backup     releases
'                        file to be ignored.

                         Skip table structure
'--skip-table-check',    check during restoring   All MySQL 5.7 based
                         of data                  releases
' -s '

'                        Causes schema objects    All MySQL 5.7 based
--skip-unknown-objects   not recognized by        releases
'                        ndb_restore to be
                         ignored when restoring
                         a backup made from a
                         newer MySQL Cluster
                         version to an older
                         version.

                         Creates a
'--tab=dir_name',        tab-separated .txt       All MySQL 5.7 based
                         file for each table in   releases
' -T dir_name '          the given path

                         Level of verbosity in
' --verbose=# '          output                   All MySQL 5.7 based
                                                  releases

Typical options for this utility are shown here:

     ndb_restore [-c CONNECTION_STRING] -n NODE_ID -b BACKUP_ID \
           [-m] -r --backup_path=/PATH/TO/BACKUP/FILES

Normally, when restoring from an NDB Cluster backup, see
'ndb_restore' requires at a minimum
the '--nodeid' (short form: '-n'), '--backupid' (short form: '-b'), and
'--backup_path' options.  In addition, when 'ndb_restore'
is used to restore any tables
containing unique indexes, you must include '--disable-indexes' or
'--rebuild-indexes'.  (Bug #57782, Bug #11764893)

The '-c' option is used to specify a connection string which tells
'ndb_restore' where to locate the cluster management server (see
mysql-cluster-connection-strings).  If this option is not used, then
'ndb_restore' attempts to
connect to a management server on 'localhost:1186'.  This utility acts
as a cluster API node, and so requires a free connection 'slot' to
connect to the cluster management server.  This means that there must be
at least one '[api]' or '[mysqld]' section that can be used by it in the
cluster 'config.ini' file.  It is a good idea to keep at least one empty
'[api]' or '[mysqld]' section in 'config.ini' that is not being used for
a MySQL server or other application for this reason (see
mysql-cluster-api-definition).

You can verify that 'ndb_restore'
is connected to the cluster by using
the 'SHOW' command in the 'ndb_mgm'
management client.  You can also
accomplish this from a system shell, as shown here:

     shell> ndb_mgm -e "SHOW"

More detailed information about all options used by ndb_restore can be
found in the following list:

   *
     '--append'

     Property                             Value

     *Command-Line Format*                '--append'

     When used with the '--tab' and '--print_data' options, this causes
     the data to be appended to any existing files having the same
     names.

   *
     '--backup_path'=DIR_NAME

     Property                             Value

     *Command-Line Format*                '--backup-path=dir_name'

     *Type*                               directory name

     *Default Value*                      './'

     The path to the backup directory is required; this is supplied to
     'ndb_restore' using the
     '--backup_path' option, and must include the subdirectory
     corresponding to the ID backup of the backup to be restored.  For
     example, if the data node's 'DataDir' is '/var/lib/mysql-cluster',
     then the backup directory is '/var/lib/mysql-cluster/BACKUP', and
     the backup files for the backup with the ID 3 can be found in
     '/var/lib/mysql-cluster/BACKUP/BACKUP-3'.  The path may be absolute
     or relative to the directory in which the 'ndb_restore'
     executable is located, and may
     be optionally prefixed with 'backup_path='.

     It is possible to restore a backup to a database with a different
     configuration than it was created from.  For example, suppose that
     a backup with backup ID '12', created in a cluster with two storage
     nodes having the node IDs '2' and '3', is to be restored to a
     cluster with four nodes.  Then 'ndb_restore'
     must be run twice--once for
     each storage node in the cluster where the backup was taken.
     However, see 'ndb_restore'.
     cannot always restore backups made from a cluster running one
     version of MySQL to a cluster running a different MySQL version.
     See mysql-cluster-upgrade-downgrade, for more information.

     *Important*:

     It is not possible to restore a backup made from a newer version of
     NDB Cluster using an older version of 'ndb_restore'.
     You can restore a backup made
     from a newer version of MySQL to an older cluster, but you must use
     a copy of 'ndb_restore'.
     from the newer NDB Cluster version to do so.

     For example, to restore a cluster backup taken from a cluster
     running NDB Cluster 7.5.11 to a cluster running NDB Cluster 7.4.21,
     you must use the 'ndb_restore'
     that comes with the NDB Cluster
     7.5.11 distribution.

     For more rapid restoration, the data may be restored in parallel,
     provided that there is a sufficient number of cluster connections
     available.  That is, when restoring to multiple nodes in parallel,
     you must have an '[api]' or '[mysqld]' section in the cluster
     'config.ini' file available for each concurrent
     'ndb_restore' process.
     However, the data files must always be applied before the logs.

   *
     '--backupid'=#, '-b'

     Property                             Value

     *Command-Line Format*                '--backupid=#'

     *Type*                               numeric

     *Default Value*                      'none'

     This option is used to specify the ID or sequence number of the
     backup, and is the same number shown by the management client in
     the 'Backup BACKUP_ID completed' message displayed upon completion
     of a backup.  (See
     mysql-cluster-backup-using-management-client.)

     *Important*:

     When restoring cluster backups, you must be sure to restore all
     data nodes from backups having the same backup ID. Using files from
     different backups will at best result in restoring the cluster to
     an inconsistent state, and may fail altogether.

   *
     '--connect', '-c'

     Property                             Value

     *Command-Line Format*                '--connect'

     *Type*                               string

     *Default Value*                      'localhost:1186'

     Alias for '--ndb-connectstring'.

   *
     '--disable-indexes'

     Property                             Value

     *Command-Line Format*                '--disable-indexes'

     Disable restoration of indexes during restoration of the data from
     a native 'NDB' backup.  Afterwards, you can restore indexes for all
     tables at once with multi-threaded building of indexes using
     '--rebuild-indexes', which should be faster than rebuilding indexes
     concurrently for very large tables.

   *
     '--dont_ignore_systab_0', '-f'

     Property                             Value

     *Command-Line Format*                '--dont-ignore-systab-0'

     Normally, when restoring table data and metadata, see
     'ndb_restore' ignores the copy
     of the 'NDB' system table that is present in
     the backup.  '--dont_ignore_systab_0' causes the system table to be
     restored.  _This option is intended for experimental and
     development use only, and is not recommended in a production
     environment_.

   *
     '--exclude-databases'=DB-LIST

     Property                             Value

     *Command-Line Format*                '--exclude-databases=db-list'

     *Type*                               string

     *Default Value*                      ''

     Comma-delimited list of one or more databases which should not be
     restored.

     This option is often used in combination with '--exclude-tables';
     see that option's description for further information and examples.

   *
     '--exclude-intermediate-sql-tables['=TRUE|FALSE]

     Property                             Value

     *Command-Line Format*                '--exclude-intermediate-sql-tables[=TRUE|FALSE]'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     When performing copying 'ALTER TABLE'.
     operations, see 'mysqld' creates intermediate tables
     (whose names are prefixed with '#sql-').  When 'TRUE', the
     '--exclude-intermediate-sql-tables' option keeps
     'ndb_restore' from restoring
     such tables that may have been left over from these operations.
     This option is 'TRUE' by default.

   *
     '--exclude-missing-columns'

     Property                             Value

     *Command-Line Format*                '--exclude-missing-columns'

     It is possible to restore only selected table columns using this
     option, which causes 'ndb_restore'
     to ignore any columns missing
     from tables being restored as compared to the versions of those
     tables found in the backup.  This option applies to all tables
     being restored.  If you wish to apply this option only to selected
     tables or databases, you can use it in combination with one or more
     of the '--include-*' or '--exclude-*' options described elsewhere
     in this section to do so, then restore data to the remaining tables
     using a complementary set of these options.

   *
     '--exclude-missing-tables'

     Property                             Value

     *Command-Line Format*                '--exclude-missing-tables'

     It is possible to restore only selected tables using this option,
     which causes 'ndb_restore'
     to ignore any tables from the
     backup that are not found in the target database.

   *
     '--exclude-tables'=TABLE-LIST

     Property                             Value

     *Command-Line Format*                '--exclude-tables=table-list'

     *Type*                               string

     *Default Value*                      ''

     List of one or more tables to exclude; each table reference must
     include the database name.  Often used together with
     '--exclude-databases'.

     When '--exclude-databases' or '--exclude-tables' is used, only
     those databases or tables named by the option are excluded; all
     other databases and tables are restored by 'ndb_restore'.

     This table shows several invocations of 'ndb_restore'
     usng '--exclude-*' options
     (other options possibly required have been omitted for clarity),
     and the effects these options have on restoring from an NDB Cluster
     backup:

     *Several invocations of ndb_restore using -exclude-* options, and
     the effects these options have on restoring from an NDB Cluster
     backup.*

     Option                               Result

     '--exclude-databases=db1'            All tables in all databases except
                                          'db1' are restored; no tables in
                                          'db1' are restored

     '--exclude-databases=db1,db2' (or    All tables in all databases except
     '--exclude-databases=db1'            'db1' and 'db2' are restored; no
     '--exclude-databases=db2')           tables in 'db1' or 'db2' are
                                          restored

     '--exclude-tables=db1.t1'            All tables except 't1' in database
                                          'db1' are restored; all other
                                          tables in 'db1' are restored; all
                                          tables in all other databases are
                                          restored

     '--exclude-tables=db1.t2,db2.t1'     All tables in database 'db1'
     (or '--exclude-tables=db1.t2'        except for 't2' and all tables in
     '--exclude-tables=db2.t1)'           database 'db2' except for table
                                          't1' are restored; no other tables
                                          in 'db1' or 'db2' are restored;
                                          all tables in all other databases
                                          are restored

     You can use these two options together.  For example, the following
     causes all tables in all databases _except for_ databases 'db1' and
     'db2', and tables 't1' and 't2' in database 'db3', to be restored:

          shell> ndb_restore [...] --exclude-databases=db1,db2 --exclude-tables=db3.t1,db3.t2

     (Again, we have omitted other possibly necessary options in the
     interest of clarity and brevity from the example just shown.)

     You can use '--include-*' and '--exclude-*' options together,
     subject to the following rules:

        * The actions of all '--include-*' and '--exclude-*' options are
          cumulative.

        * All '--include-*' and '--exclude-*' options are evaluated in
          the order passed to ndb_restore, from right to left.

        * In the event of conflicting options, the first (rightmost)
          option takes precedence.  In other words, the first option
          (going from right to left) that matches against a given
          database or table 'wins'.

     For example, the following set of options causes
     'ndb_restore' to restore all
     tables from database 'db1' except 'db1.t1', while restoring no
     other tables from any other databases:

          --include-databases=db1 --exclude-tables=db1.t1

     However, reversing the order of the options just given simply
     causes all tables from database 'db1' to be restored (including
     'db1.t1', but no tables from any other database), because the
     '--include-databases' option, being farthest to the right, is the
     first match against database 'db1' and thus takes precedence over
     any other option that matches 'db1' or any tables in 'db1':

          --exclude-tables=db1.t1 --include-databases=db1

   *
     '--fields-enclosed-by'=CHAR

     Property                             Value

     *Command-Line Format*                '--fields-enclosed-by=char'

     *Type*                               string

     *Default Value*                      ''

     Each column value is enclosed by the string passed to this option
     (regardless of data type; see the description of
     '--fields-optionally-enclosed-by').

   *
     '--fields-optionally-enclosed-by'

     Property                             Value

     *Command-Line Format*                '--fields-optionally-enclosed-by'

     *Type*                               string

     *Default Value*                      ''

     The string passed to this option is used to enclose column values
     containing character data (such as 'CHAR',
     'VARCHAR', 'BINARY', 'TEXT',
     or 'ENUM').

   *
     '--fields-terminated-by'=CHAR

     Property                             Value

     *Command-Line Format*                '--fields-terminated-by=char'

     *Type*                               string

     *Default Value*                      '\t (tab)'

     The string passed to this option is used to separate column values.
     The default value is a tab character ('\t').

   *
     '--hex'

     Property                             Value

     *Command-Line Format*                '--hex'

     If this option is used, all binary values are output in hexadecimal
     format.

   *
     '--include-databases'=DB-LIST

     Property                             Value

     *Command-Line Format*                '--include-databases=db-list'

     *Type*                               string

     *Default Value*                      ''

     Comma-delimited list of one or more databases to restore.  Often
     used together with '--include-tables'; see the description of that
     option for further information and examples.

   *
     '--include-tables'=TABLE-LIST

     Property                             Value

     *Command-Line Format*                '--include-tables=table-list'

     *Type*                               string

     *Default Value*                      ''

     Comma-delimited list of tables to restore; each table reference
     must include the database name.

     When '--include-databases' or '--include-tables' is used, only
     those databases or tables named by the option are restored; all
     other databases and tables are excluded by 'ndb_restore',
     and are not restored.

     The following table shows several invocations of
     'ndb_restore' using
     '--include-*' options (other options possibly required have been
     omitted for clarity), and the effects these have on restoring from
     an NDB Cluster backup:

     *Several invocations of ndb_restore using -include-* options, and
     their effects on restoring from an NDB Cluster backup.*

     Option                               Result

     '--include-databases=db1'            Only tables in database 'db1' are
                                          restored; all tables in all other
                                          databases are ignored

     '--include-databases=db1,db2' (or    Only tables in databases 'db1' and
     '--include-databases=db1'            'db2' are restored; all tables in
     '--include-databases=db2')           all other databases are ignored

     '--include-tables=db1.t1'            Only table 't1' in database 'db1'
                                          is restored; no other tables in
                                          'db1' or in any other database are
                                          restored

     '--include-tables=db1.t2,db2.t1'     Only the table 't2' in database
     (or '--include-tables=db1.t2'        'db1' and the table 't1' in
     '--include-tables=db2.t1')           database 'db2' are restored; no
                                          other tables in 'db1', 'db2', or
                                          any other database are restored

     You can also use these two options together.  For example, the
     following causes all tables in databases 'db1' and 'db2', together
     with the tables 't1' and 't2' in database 'db3', to be restored
     (and no other databases or tables):

          shell> ndb_restore [...] --include-databases=db1,db2 --include-tables=db3.t1,db3.t2

     (Again we have omitted other, possibly required, options in the
     example just shown.)

     It also possible to restore only selected databases, or selected
     tables from a single database, without any '--include-*' (or
     '--exclude-*') options, using the syntax shown here:

          ndb_restore OTHER_OPTIONS DB_NAME,[DB_NAME[,...] | TBL_NAME[,TBL_NAME][,...]]

     In other words, you can specify either of the following to be
     restored:

        * All tables from one or more databases

        * One or more tables from a single database

   *
     '--lines-terminated-by'=CHAR

     Property                             Value

     *Command-Line Format*                '--lines-terminated-by=char'

     *Type*                               string

     *Default Value*                      '\n (linebreak)'

     Specifies the string used to end each line of output.  The default
     is a linefeed character ('\n').

   *
     '--lossy-conversions', '-L'

     Property                             Value

     *Command-Line Format*                '--lossy-conversions'

     *Type*                               boolean

     *Default Value*                      'FALSE' (If option is not used)

     This option is intended to complement the '--promote-attributes'
     option.  Using '--lossy-conversions' allows lossy conversions of
     column values (type demotions or changes in sign) when restoring
     data from backup.  With some exceptions, the rules governing
     demotion are the same as for MySQL replication; see
     replication-features-different-data-types, for information about
     specific type conversions currently supported by attribute
     demotion.

     'ndb_restore' reports
     any truncation of data that it performs during lossy conversions
     once per attribute and column.

   *
     '--no-binlog'

     Property                             Value

     *Command-Line Format*                '--no-binlog'

     This option prevents any connected SQL nodes from writing data
     restored by 'ndb_restore'
     to their binary logs.

   *
     '--no-restore-disk-objects', '-d'

     Property                             Value

     *Command-Line Format*                '--no-restore-disk-objects'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option stops 'ndb_restore'
     from restoring any NDB Cluster
     Disk Data objects, such as tablespaces and log file groups; see
     mysql-cluster-disk-data, for more information about these.

   *
     '--no-upgrade', '-u'

     Property                             Value

     *Command-Line Format*                '--no-upgrade'

     When using 'ndb_restore'.
     to restore a backup, see 'VARCHAR' columns created using
     the old fixed format are resized and recreated using the
     variable-width format now employed.  This behavior can be
     overridden by specifying '--no-upgrade'.

   *
     '--ndb-nodegroup-map'=MAP, '-z'

     Property                             Value

     *Command-Line Format*                '--ndb-nodegroup-map=map'

     This option can be used to restore a backup taken from one node
     group to a different node group.  Its argument is a list of the
     form 'SOURCE_NODE_GROUP, TARGET_NODE_GROUP'.

   *
     '--nodeid'=#, '-n'

     Property                             Value

     *Command-Line Format*                '--nodeid=#'

     *Type*                               numeric

     *Default Value*                      'none'

     Specify the node ID of the data node on which the backup was taken.

     When restoring to a cluster with different number of data nodes
     from that where the backup was taken, this information helps
     identify the correct set or sets of files to be restored to a given
     node.  (In such cases, multiple files usually need to be restored
     to a single data node.)  See
     ndb-restore-different-number-nodes, for additional information
     and examples.

   *
     '--parallelism'=#, '-p'

     Property                             Value

     *Command-Line Format*                '--parallelism=#'

     *Type*                               numeric

     *Default Value*                      '128'

     *Minimum Value*                      '1'

     *Maximum Value*                      '1024'

     'ndb_restore' uses
     single-row transactions to apply many rows concurrently.  This
     parameter determines the number of parallel transactions
     (concurrent rows) that an instance of 'ndb_restore'
     tries to use.  By default, this
     is 128; the minimum is 1, and the maximum is 1024.

     The work of performing the inserts is parallelized across the
     threads in the data nodes involved.  This mechanism is employed for
     restoring bulk data from the '.Data' file--that is, the fuzzy
     snapshot of the data; it is not used for building or rebuilding
     indexes.  The change log is applied serially; index drops and
     builds are DDL operations and handled separately.  There is no
     thread-level parallelism on the client side of the restore.

   *
     '--preserve-trailing-spaces', '-P'

     Property                             Value

     *Command-Line Format*                '--preserve-trailing-spaces'

     Cause trailing spaces to be preserved when promoting a fixed-width
     character data type to its variable-width equivalent--that is, when
     promoting a 'CHAR' column value to 'VARCHAR',
     or a 'BINARY' column value to 'VARBINARY'.
     Otherwise, any trailing spaces are dropped from
     such column values when they are inserted into the new columns.

     *Note*:

     Although you can promote 'CHAR' columns to
     'VARCHAR' and 'BINARY' columns to 'VARBINARY',
     you cannot promote 'VARCHAR' columns
     to 'CHAR' or 'VARBINARY'.
     columns to 'BINARY'.

   *
     '--print'

     Property                             Value

     *Command-Line Format*                '--print'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Causes 'ndb_restore' to
     print all data, metadata, and logs to 'stdout'.  Equivalent to
     using the '--print_data', '--print_meta', and '--print_log' options
     together.

     *Note*:

     Use of '--print' or any of the '--print_*' options is in effect
     performing a dry run.  Including one or more of these options
     causes any output to be redirected to 'stdout'; in such cases,
     see 'ndb_restore' makes no
     attempt to restore data or metadata to an NDB Cluster.

   *
     '--print_data'

     Property                             Value

     *Command-Line Format*                '--print-data'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Cause 'ndb_restore' to
     direct its output to 'stdout'.  Often used together with one or
     more of '--tab', '--fields-enclosed-by',
     '--fields-optionally-enclosed-by', '--fields-terminated-by',
     '--hex', and '--append'.

     'TEXT' and 'BLOB' column values are
     always truncated.  Such values are truncated to the first 256 bytes
     in the output.  This cannot currently be overridden when using
     '--print_data'.

   *
     '--print_log'

     Property                             Value

     *Command-Line Format*                '--print-log'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Cause 'ndb_restore' to
     output its log to 'stdout'.

   *
     '--print_meta'

     Property                             Value

     *Command-Line Format*                '--print-meta'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Print all metadata to 'stdout'.

   *
     'print-sql-log'

     Property                             Value

     *Command-Line Format*                'print-sql-log'

     *Introduced*                         5.7.16-ndb-7.5.4

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Log SQL statements to 'stdout'.  Use the option to enable; normally
     this behavior is disabled.  The option checks before attempting to
     log whether all the tables being restored have explicitly defined
     primary keys; queries on a table having only the hidden primary key
     implemented by 'NDB' cannot be converted to valid SQL.

     The '--print-sql-log' option was added in NDB 7.5.4.  (Bug
     #13511949)

   *
     '--progress-frequency'=N

     Property                             Value

     *Command-Line Format*                '--progress-frequency=#'

     *Type*                               numeric

     *Default Value*                      '0'

     *Minimum Value*                      '0'

     *Maximum Value*                      '65535'

     Print a status report each N seconds while the backup is in
     progress.  0 (the default) causes no status reports to be printed.
     The maximum is 65535.

   *
     '--promote-attributes', '-A'

     Property                             Value

     *Command-Line Format*                '--promote-attributes'

     'ndb_restore' supports
     limited _attribute promotion_ in much the same way that it is
     supported by MySQL replication; that is, data backed up from a
     column of a given type can generally be restored to a column using
     a 'larger, similar' type.  For example, data from a 'CHAR(20)'
     column can be restored to a column declared as 'VARCHAR(20)',
     'VARCHAR(30)', or 'CHAR(30)'; data from a 'MEDIUMINT'
     column can be restored to a column of type
     'INT' or 'BIGINT'.  See
     replication-features-different-data-types, for a table of type
     conversions currently supported by attribute promotion.

     Attribute promotion by 'ndb_restore'
     must be enabled explicitly, as
     follows:

       1. Prepare the table to which the backup is to be restored.
          See 'ndb_restore'.
          cannot be used to re-create the table with a different
          definition from the original; this means that you must either
          create the table manually, or alter the columns which you wish
          to promote using 'ALTER TABLE' after
          restoring the table metadata but before restoring the data.

       2. Invoke 'ndb_restore'
          with the
          '--promote-attributes' option (short form '-A') when restoring
          the table data.  Attribute promotion does not occur if this
          option is not used; instead, the restore operation fails with
          an error.

     When converting between character data types and 'TEXT' or 'BLOB',
     only conversions between character types (see 'CHAR' and
     'VARCHAR') and binary types (see 'BINARY'
     and 'VARBINARY') can be
     performed at the same time.  For example, you cannot promote an
     'INT' column to 'BIGINT'
     while promoting a 'VARCHAR' column to 'TEXT' in the
     same invocation of 'ndb_restore'.

     Converting between 'TEXT' columns using different
     character sets is not supported, and is expressly disallowed.

     When performing conversions of character or binary types to 'TEXT'
     or 'BLOB' with 'ndb_restore',
     you may notice that it creates
     and uses one or more staging tables named 'TABLE_NAME$STNODE_ID'.
     These tables are not needed afterwards, and are normally deleted by
     'ndb_restore' following
     a successful restoration.

   *
     '--rebuild-indexes'

     Property                             Value

     *Command-Line Format*                '--rebuild-indexes'

     Enable multi-threaded rebuilding of the ordered indexes while
     restoring a native 'NDB' backup.  The number of threads used for
     building ordered indexes by 'ndb_restore'
     with this option is controlled
     by the 'BuildIndexThreads' data node configuration parameter and
     the number of LDMs.

     It is necessary to use this option only for the first run of
     'ndb_restore'.; this causes all
     ordered indexes to be rebuilt without using '--rebuild-indexes'
     again when restoring subsequent nodes.  You should use this option
     prior to inserting new rows into the database; otherwise, it is
     possible for a row to be inserted that later causes a unique
     constraint violation when trying to rebuild the indexes.

     Building of ordered indices is parallelized with the number of LDMs
     by default.  Offline index builds performed during node and system
     restarts can be made faster using the 'BuildIndexThreads' data node
     configuration parameter; this parameter has no effect on dropping
     and rebuilding of indexes by 'ndb_restore',
     which is performed online.

     Rebuilding of unique indexes uses disk write bandwidth for redo
     logging and local checkpointing.  An insufficient amount of this
     bandwith can lead to redo buffer overload or log overload errors.
     In such cases you can run 'ndb_restore'.
     '--rebuild-indexes' again; the
     process resumes at the point where the error occurred.  You can
     also do this when you have encountered temporary errors.  You can
     repeat execution of 'ndb_restore'.
     '--rebuild-indexes'
     indefinitely; you may be able to stop such errors by reducing the
     value of '--parallelism'.  If the problem is insufficient space,
     you can increase the size of the redo log ('FragmentLogFileSize'
     node configuration parameter), or you can increase the speed at
     which LCPs are performed ('MaxDiskWriteSpeed' and related
     parameters), in order to free space more quickly.

   *
     '--restore_data', '-r'

     Property                             Value

     *Command-Line Format*                '--restore-data'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Output 'NDB' table data and logs.

   *
     '--restore_epoch', '-e'

     Property                             Value

     *Command-Line Format*                '--restore-epoch'

     Add (or restore) epoch information to the cluster replication
     status table.  This is useful for starting replication on an NDB
     Cluster replication slave.  When this option is used, the row in
     the 'mysql.ndb_apply_status' having '0' in the 'id' column is
     updated if it already exists; such a row is inserted if it does not
     already exist.  (See mysql-cluster-replication-backups.)

   *
     '--restore_meta', '-m'

     Property                             Value

     *Command-Line Format*                '--restore-meta'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     This option causes 'ndb_restore'
     to print 'NDB'
     table metadata.

     The first time you run the 'ndb_restore'
     restoration program, you also
     need to restore the metadata.  In other words, you must re-create
     the database tables--this can be done by running it with the
     '--restore_meta' ('-m') option.  Restoring the metadata need be
     done only on a single data node; this is sufficient to restore it
     to the entire cluster.

     In older versions of NDB Cluster, tables whose schemas were
     restored using this option used the same number of partitions as
     they did on the original cluster, even if it had a differing number
     of data nodes from the new cluster.  In NDB 7.5.2 and later, when
     restoring metadata, this is no longer an issue; see
     'ndb_restore' now uses the
     default number of partitions for the target cluster, unless the
     number of local data manager threads is also changed from what it
     was for data nodes in the original cluster.

     *Note*:

     The cluster should have an empty database when starting to restore
     a backup.  (In other words, you should start the data nodes with
     '--initial' prior to performing the restore.)

   *
     '--restore-privilege-tables'

     Property                             Value

     *Command-Line Format*                '--restore-privilege-tables'

     *Type*                               boolean

     *Default Value*                      'FALSE' (If option is not used)

     'ndb_restore' does not
     by default restore distributed MySQL privilege tables.  This option
     causes 'ndb_restore' to
     restore the privilege tables.

     This works only if the privilege tables were converted to
     'NDB' before the backup was taken.  For more
     information, see mysql-cluster-privilege-distribution.

   *
     '--rewrite-database'=OLDDB,NEWDB

     Property                             Value

     *Command-Line Format*                '--rewrite-database=olddb,newdb'

     *Type*                               string

     *Default Value*                      'none'

     This option makes it possible to restore to a database having a
     different name from that used in the backup.  For example, if a
     backup is made of a database named 'products', you can restore the
     data it contains to a database named 'inventory', use this option
     as shown here (omitting any other options that might be required):

          shell> ndb_restore --rewrite-database=product,inventory

     The option can be employed multiple times in a single invocation of
     'ndb_restore'.  Thus it
     is possible to restore simultaneously from a database named 'db1'
     to a database named 'db2' and from a database named 'db3' to one
     named 'db4' using '--rewrite-database=db1,db2
     --rewrite-database=db3,db4'.  Other 'ndb_restore'
     options may be used between
     multiple occurrences of '--rewrite-database'.

     In the event of conflicts between multiple '--rewrite-database'
     options, the last '--rewrite-database' option used, reading from
     left to right, is the one that takes effect.  For example, if
     '--rewrite-database=db1,db2 --rewrite-database=db1,db3' is used,
     only '--rewrite-database=db1,db3' is honored, and
     '--rewrite-database=db1,db2' is ignored.  It is also possible to
     restore from multiple databases to a single database, so that
     '--rewrite-database=db1,db3 --rewrite-database=db2,db3' restores
     all tables and data from databases 'db1' and 'db2' into database
     'db3'.

     *Important*:

     When restoring from multiple backup databases into a single target
     database using '--rewrite-database', no check is made for
     collisions between table or other object names, and the order in
     which rows are restored is not guaranteed.  This means that it is
     possible in such cases for rows to be overwritten and updates to be
     lost.

   *
     '--skip-broken-objects'

     Property                             Value

     *Command-Line Format*                '--skip-broken-objects'

     This option causes 'ndb_restore'
     to ignore corrupt tables while
     reading a native 'NDB' backup, and to
     continue restoring any remaining tables (that are not also
     corrupted).  Currently, the '--skip-broken-objects' option works
     only in the case of missing blob parts tables.

   *
     '--skip-table-check', '-s'

     Property                             Value

     *Command-Line Format*                '--skip-table-check'

     It is possible to restore data without restoring table metadata.
     By default when doing this, see 'ndb_restore'
     fails with an error if a
     mismatch is found between the table data and the table schema; this
     option overrides that behavior.

     Some of the restrictions on mismatches in column definitions when
     restoring data using 'ndb_restore'
     are relaxed; when one of these
     types of mismatches is encountered, see 'ndb_restore'
     does not stop with an error as
     it did previously, but rather accepts the data and inserts it into
     the target table while issuing a warning to the user that this is
     being done.  This behavior occurs whether or not either of the
     options '--skip-table-check' or '--promote-attributes' is in use.
     These differences in column definitions are of the following types:

        * Different 'COLUMN_FORMAT' settings ('FIXED', 'DYNAMIC',
          'DEFAULT')

        * Different 'STORAGE' settings ('MEMORY', 'DISK')

        * Different default values

        * Different distribution key settings

   *
     '--skip-unknown-objects'

     Property                             Value

     *Command-Line Format*                '--skip-unknown-objects'

     This option causes 'ndb_restore'
     to ignore any schema objects it
     does not recognize while reading a native 'NDB'
     backup.  This can be used for restoring a backup
     made from a cluster running (for example) NDB 7.6 to a cluster
     running NDB Cluster 7.5.

   *
     '--tab'=DIR_NAME, '-T' DIR_NAME

     Property                             Value

     *Command-Line Format*                '--tab=dir_name'

     *Type*                               directory name

     Causes '--print_data' to create dump files, one per table, each
     named 'TBL_NAME.txt'.  It requires as its argument the path to the
     directory where the files should be saved; use '.' for the current
     directory.

   *
     '--verbose'=#

     Property                             Value

     *Command-Line Format*                '--verbose=#'

     *Type*                               numeric

     *Default Value*                      '1'

     *Minimum Value*                      '0'

     *Maximum Value*                      '255'

     Sets the level for the verbosity of the output.  The minimum is 0;
     the maximum is 255.  The default value is 1.

Error reporting

'ndb_restore' reports both
temporary and permanent errors.  In the case of temporary errors, it may
able to recover from them, and reports 'Restore successful, but
encountered temporary error, please look at configuration' in such
cases.

*Important*:

After using 'ndb_restore' to
initialize an NDB Cluster for use in circular replication, binary logs
on the SQL node acting as the replication slave are not automatically
created, and you must cause them to be created manually.  To cause the
binary logs to be created, issue a 'SHOW TABLES'.
statement on that SQL node before running 'START SLAVE'.
This is a known issue in NDB Cluster.

21.4.24.1 Restoring to a different number of data nodes
.......................................................

It is possible to restore from an NDB backup to a cluster having a
different number of data nodes than the original from which the backup
was taken.  The following two sections discuss, respectively, the cases
where the target cluster has a lesser or greater number of data nodes
than the source of the backup.

21.4.24.2 Restoring to Fewer Nodes Than the Original
....................................................

You can restore to a cluster having fewer data nodes than the original
provided that the larger number of nodes is an even multiple of the
smaller number.  In the following example, we use a backup taken on a
cluster having four data nodes to a cluster having two data nodes.

  1. The management server for the original cluster is on host 'host10'.
     The original cluster has four data nodes, with the node IDs and
     host names shown in the following extract from the management
     server's 'config.ini' file:

          [ndbd]
          NodeId=2
          HostName=host2

          [ndbd]
          NodeId=4
          HostName=host4

          [ndbd]
          NodeId=6
          HostName=host6

          [ndbd]
          NodeId=8
          HostName=host8

     We assume that each data node was originally started with
     'ndbmtd'.
     '--ndb-connectstring=host10' or the equivalent.

  2. Perform a backup in the normal manner.  See
     mysql-cluster-backup-using-management-client, for information
     about how to do this.

  3. The files created by the backup on each data node are listed here,
     where N is the node ID and B is the backup ID.

        * 'BACKUP-B-0.N.Data'

        * 'BACKUP-B.N.ctl'

        * 'BACKUP-B.N.log'

     These files are found under 'BackupDataDir''/BACKUP/BACKUP-B', on
     each data node.  For the rest of this example, we assume that the
     backup ID is 1.

     Have all of these files available for later copying to the new data
     nodes (where they can be accessed on the data node's local file
     system by 'ndb_restore').
     It is simplest to copy them
     all to a single location; we assume that this is what you have
     done.

  4. The management server for the target cluster is on host 'host20',
     and the target has two data nodes, with the node IDs and host names
     shown, from the management server 'config.ini' file on 'host20':

          [ndbd]
          NodeId=3
          hostname=host3

          [ndbd]
          NodeId=5
          hostname=host5

     Each of the data node processes on 'host3' and 'host5' should be
     started with 'ndbmtd'. '-c
     host20' '--initial' or the equivalent, so that the new (target)
     cluster starts with clean data node file systems.

  5. Copy two different sets of two backup files to each of the target
     data nodes.  For this example, copy the backup files from nodes 2
     and 6 from the original cluster to node 3 in the target cluster.
     These files are listed here:

        * 'BACKUP-1-0.2.Data'

        * 'BACKUP-1.2.ctl'

        * 'BACKUP-1.2.log'

        * 'BACKUP-1-0.6.Data'

        * 'BACKUP-1.6.ctl'

        * 'BACKUP-1.6.log'

     Then copy the backup files from nodes 4 and 8 to node 5; these
     files are shown in the following list:

        * 'BACKUP-1-0.4.Data'

        * 'BACKUP-1.4.ctl'

        * 'BACKUP-1.4.log'

        * 'BACKUP-1-0.8.Data'

        * 'BACKUP-1.8.ctl'

        * 'BACKUP-1.8.log'

     For the remainder of this example, we assume that the respective
     backup files have been saved to the directory '/BACKUP-1' on each
     of nodes 3 and 5.

  6. On each of the two target data nodes, you must restore from both
     sets of backups.  First, restore the backups from nodes 2 and 6 to
     node 3 by invoking 'ndb_restore'
     on 'host3' as shown here:

          shell> ndb_restore -c host20 --nodeid=2 --backupid=1 --restore_data --backup_path=/BACKUP-1

          shell> ndb_restore -c host20 --nodeid=4 --backupid=1 --restore_data --backup_path=/BACKUP-1

     Then restore the backups from nodes 4 and 8 to node 5 by invoking
     'ndb_restore' on
     'host5', like this:

          shell> ndb_restore -c host20 --nodeid=6 --backupid=1 --restore_data --backup_path=/BACKUP-1

          shell> ndb_restore -c host20 --nodeid=8 --backupid=1 --restore_data --backup_path=/BACKUP-1

21.4.24.3 Restoring to More Nodes Than the Original
...................................................

The node ID specified for a given 'ndb_restore'
command is that of the node in the
original backup and not that of the data node to restore it to.  When
performing a backup using the method described in this section, see
'ndb_restore' connects to the
management server and obtains a list of data nodes in the cluster the
backup is being restored to.  The restored data is distributed
accordingly, so that the number of nodes in the target cluster does not
need to be to be known or calculated when performing the backup.

*Note*:

When changing the total number of LCP threads or LQH threads per node
group, you should recreate the schema from backup created using
'mysqldump'.

  1. _Create the backup of the data_.  You can do this by invoking the
     'ndb_mgm' client 'START
     BACKUP' command from the system shell, like this:

          shell> ndb_mgm -e "START BACKUP 1"

     This assumes that the desired backup ID is 1.

  2. Create a backup of the schema.  In NDB 7.5.2 and later, this step
     is necessary only if the total number of LCP threads or LQH threads
     per node group is changed.

          shell> mysqldump --no-data --routines --events --triggers --databases > myschema.sql

     *Important*:

     Once you have created the 'NDB' native backup using
     'ndb_mgm', you must not make any
     schema changes before creating the backup of the schema, if you do
     so.

  3. Copy the backup directory to the new cluster.  For example if the
     backup you want to restore has ID 1 and 'BackupDataDir' =
     '/backups/node_NODEID', then the path to the backup on this node is
     '/backups/node_1/BACKUP/BACKUP-1'.  Inside this directory there are
     three files, listed here:

        * 'BACKUP-1-0.1.Data'

        * 'BACKUP-1.1.ctl'

        * 'BACKUP-1.1.log'

     You should copy the entire directory to the new node.

     If you needed to create a schema file, copy this to a location on
     an SQL node where it can be read by 'mysqld'.

There is no requirement for the backup to be restored from a specific
node or nodes.

To restore from the backup just created, perform the following steps:

  1. _Restore the schema_.

        * If you created a separate schema backup file using
          'mysqldump', import this file using the
          'mysql' client, similar to what is shown here:

               shell> mysql < myschema.sql

          When importing the schema file, you may need to specify the
          '--user' and '--password' options (and possibly others) in
          addition to what is shown, in order for the 'mysql'
          client to be able to connect to the MySQL server.

        * If you did _not_ need to create a schema file, you can
          re-create the schema using 'ndb_restore'.
          '--restore_meta' (short
          form '-m'), similar to what is shown here:

               shell> ndb_restore --nodeid=1 --backupid=1 --restore_meta --backup-path=/backups/node_1/BACKUP/BACKUP-1

          'ndb_restore' must
          be able to contact the management server; add the
          '--ndb-connectstring' option if and as needed to make this
          possible.

  2. _Restore the data_.  This needs to be done once for each data node
     in the original cluster, each time using that data node's node ID.
     Assuming that there were 4 data nodes originally, the set of
     commands required would look something like this:

          ndb_restore --nodeid=1 --backupid=1 --restore_data --backup_path=/backups/node_1/BACKUP/BACKUP-1 --disable-indexes
          ndb_restore --nodeid=2 --backupid=1 --restore_data --backup_path=/backups/node_2/BACKUP/BACKUP-1 --disable-indexes
          ndb_restore --nodeid=3 --backupid=1 --restore_data --backup_path=/backups/node_3/BACKUP/BACKUP-1 --disable-indexes
          ndb_restore --nodeid=4 --backupid=1 --restore_data --backup_path=/backups/node_4/BACKUP/BACKUP-1 --disable-indexes

     These can be run in parallel.

     Be sure to add the '--ndb-connectstring' option as needed.

  3. _Rebuild the indexes_.  These were disabled by the
     '--disable-indexes' option used in the commands just shown.
     Recreating the indexes avoids errors due to the restore not being
     consistent at all points.  Rebuilding the indexes can also improve
     performance in some cases.  To rebuild the indexes, execute the
     following command once, on a single node:

          shell> ndb_restore --nodeid=1 --backupid=1 --backup_path=/backups/node_1/BACKUP/BACKUP-1 --rebuild-indexes

     As mentioned previously, you may need to add the
     '--ndb-connectstring' option, so that 'ndb_restore'
     can contact the management
     server.

21.4.25 'ndb_select_all' -- Print Rows from an NDB Table
--------------------------------------------------------

'ndb_select_all' prints
all rows from an 'NDB' table to 'stdout'.

*Usage*

     ndb_select_all -c CONNECTION_STRING TBL_NAME -d DB_NAME [> FILE_NAME]

The following table includes options that are specific to the NDB
Cluster native backup restoration program 'ndb_select_all'.
Additional descriptions follow
the table.  For options common to most NDB Cluster programs (including
'ndb_select_all'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_select_all program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Name of the database
'--database=dbname',     in which the table is    All MySQL 5.7 based
                         found                    releases
' -d '

'--parallelism=#',       Degree of parallelism    All MySQL 5.7 based
                                                  releases
' -p '

'--lock=#',              Lock type                All MySQL 5.7 based
                                                  releases
' -l '

'--order=index',         Sort resultset           All MySQL 5.7 based
                         according to index       releases
' -o '                   whose name is supplied

                         Sort resultset in
'--descending',          descending order         All MySQL 5.7 based
                         (requires order flag)    releases
' -z '

'--header',              Print header (set to     All MySQL 5.7 based
                         0|FALSE to disable       releases
' -h '                   headers in output)

                         Output numbers in
'--useHexFormat',        hexadecimal format       All MySQL 5.7 based
                                                  releases
' -x '

'--delimiter=char',      Set a column delimiter   All MySQL 5.7 based
                                                  releases
' -D '

' --disk '               Print disk references    All MySQL 5.7 based
                         (useful only for Disk    releases
                         Data tables having
                         nonindexed columns)

                         Print rowid
' --rowid '                                       All MySQL 5.7 based
                                                  releases

                         Include GCI in output
' --gci '                                         All MySQL 5.7 based
                                                  releases

                         Include GCI and row
' --gci64 '              epoch in output          All MySQL 5.7 based
                                                  releases

                         Scan in tup order
'--tupscan',                                      All MySQL 5.7 based
                                                  releases
' -t '

' --nodata '             Do not print table       All MySQL 5.7 based
                         column data              releases

   *
     '--database=DBNAME', '-d' DBNAME

     Name of the database in which the table is found.  The default
     value is 'TEST_DB'.

   *
     'parallelism=#', '-p' #

     Specifies the degree of parallelism.

   *
     '--lock=LOCK_TYPE', '-l LOCK_TYPE'

     Employs a lock when reading the table.  Possible values for
     LOCK_TYPE are:

        * '0': Read lock

        * '1': Read lock with hold

        * '2': Exclusive read lock

     There is no default value for this option.

   *
     '--order=INDEX_NAME', '-o INDEX_NAME'

     Orders the output according to the index named INDEX_NAME.

     *Note*:

     This is the name of an index, not of a column; the index must have
     been explicitly named when created.

   *
     '--descending', '-z'

     Sorts the output in descending order.  This option can be used only
     in conjunction with the '-o' ('--order') option.

   *
     '--header=FALSE'

     Excludes column headers from the output.

   *
     '--useHexFormat' '-x'

     Causes all numeric values to be displayed in hexadecimal format.
     This does not affect the output of numerals contained in strings or
     datetime values.

   *
     '--delimiter=CHARACTER', '-D CHARACTER'

     Causes the CHARACTER to be used as a column delimiter.  Only table
     data columns are separated by this delimiter.

     The default delimiter is the tab character.

   *
     '--disk'

     Adds a disk reference column to the output.  The column is nonempty
     only for Disk Data tables having nonindexed columns.

   *
     '--rowid'

     Adds a 'ROWID' column providing information about the fragments in
     which rows are stored.

   *
     '--gci'

     Adds a 'GCI' column to the output showing the global checkpoint at
     which each row was last updated.  See
     mysql-cluster-overview, and mysql-cluster-log-events, for
     more information about checkpoints.

   *
     '--gci64'

     Adds a 'ROW$GCI64' column to the output showing the global
     checkpoint at which each row was last updated, as well as the
     number of the epoch in which this update occurred.

   *
     '--tupscan', '-t'

     Scan the table in the order of the tuples.

   *
     '--nodata'

     Causes any table data to be omitted.

*Sample Output*

Output from a MySQL 'SELECT' statement:

     mysql> SELECT * FROM ctest1.fish;
     +----+-----------+
     | id | name      |
     +----+-----------+
     |  3 | shark     |
     |  6 | puffer    |
     |  2 | tuna      |
     |  4 | manta ray |
     |  5 | grouper   |
     |  1 | guppy     |
     +----+-----------+
     6 rows in set (0.04 sec)

Output from the equivalent invocation of 'ndb_select_all'.:

     shell> ./ndb_select_all -c localhost fish -d ctest1
     id      name
     3       [shark]
     6       [puffer]
     2       [tuna]
     4       [manta ray]
     5       [grouper]
     1       [guppy]
     6 rows returned

     NDBT_ProgramExit: 0 - OK

All string values are enclosed by square brackets ('['...']')  in the
output of 'ndb_select_all'.
For another example, consider the table created and populated as shown
here:

     CREATE TABLE dogs (
         id INT(11) NOT NULL AUTO_INCREMENT,
         name VARCHAR(25) NOT NULL,
         breed VARCHAR(50) NOT NULL,
         PRIMARY KEY pk (id),
         KEY ix (name)
     )
     TABLESPACE ts STORAGE DISK
     ENGINE=NDBCLUSTER;

     INSERT INTO dogs VALUES
         ('', 'Lassie', 'collie'),
         ('', 'Scooby-Doo', 'Great Dane'),
         ('', 'Rin-Tin-Tin', 'Alsatian'),
         ('', 'Rosscoe', 'Mutt');

This demonstrates the use of several additional 'ndb_select_all'
options:

     shell> ./ndb_select_all -d ctest1 dogs -o ix -z --gci --disk
     GCI     id name          breed        DISK_REF
     834461  2  [Scooby-Doo]  [Great Dane] [ m_file_no: 0 m_page: 98 m_page_idx: 0 ]
     834878  4  [Rosscoe]     [Mutt]       [ m_file_no: 0 m_page: 98 m_page_idx: 16 ]
     834463  3  [Rin-Tin-Tin] [Alsatian]   [ m_file_no: 0 m_page: 34 m_page_idx: 0 ]
     835657  1  [Lassie]      [Collie]     [ m_file_no: 0 m_page: 66 m_page_idx: 0 ]
     4 rows returned

     NDBT_ProgramExit: 0 - OK

21.4.26 'ndb_select_count' -- Print Row Counts for NDB Tables
-------------------------------------------------------------

See 'ndb_select_count'.
prints the number of rows in one or more 'NDB'.
tables.  With a single table, the result is equivalent to that obtained
by using the MySQL statement 'SELECT COUNT(*) FROM TBL_NAME'.

*Usage*

     ndb_select_count [-c CONNECTION_STRING] -dDB_NAME TBL_NAME[, TBL_NAME2[, ...]]

The following table includes options that are specific to the NDB
Cluster native backup restoration program 'ndb_select_count'.
Additional descriptions follow
the table.  For options common to most NDB Cluster programs (including
'ndb_select_count'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_select_count program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Name of the database
'--database=dbname',     in which the table is    All MySQL 5.7 based
                         found                    releases
'-d'

'--parallelism=#',       Degree of parallelism    All MySQL 5.7 based
                                                  releases
'-p'

'--lock=#',              Lock type                All MySQL 5.7 based
                                                  releases
'-l'

You can obtain row counts from multiple tables in the same database by
listing the table names separated by spaces when invoking this command,
as shown under *Sample Output*.

*Sample Output*

     shell> ./ndb_select_count -c localhost -d ctest1 fish dogs
     6 records in table fish
     4 records in table dogs

     NDBT_ProgramExit: 0 - OK

21.4.27 'ndb_setup.py' -- Start browser-based Auto-Installer for NDB Cluster
----------------------------------------------------------------------------

'ndb_setup.py' starts the
NDB Cluster Auto-Installer and opens the installer's Start page in the
default Web browser.

*Important*:

This program is intended to be invoked as a normal user, and not with
the 'mysql', system 'root' or other administrative account.

This section describes usage of and program options for the command-line
tool only.  For information about using the Auto-Installer GUI that is
spawned when 'ndb_setup.py'.
is invoked, see mysql-cluster-install-auto.

*Usage*

All platforms:

     ndb_setup.py [OPTIONS]

Additionally, on Windows platforms only:

     setup.bat [OPTIONS]

The following table includes all options that are supported by the NDB
Cluster installation and configuration program 'ndb_setup.py'.
Additional descriptions follow the
table.

*Command-line options for the ndb_setup.py program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Page that the web
'--browser-start-page=filename',browser opens whenAll MySQL 5.7 based
                         starting.                releases
' -s '

'--ca-certs-file=filename',File containing list   All MySQL 5.7 based
                         of client certificates   releases
' -a '                   allowed to connect to
                         the server

                         File containing X509
'--cert-file=filename',  certificate that         All MySQL 5.7 based
                         identifies the server.   releases
' -c '                   (Default: cfg.pem)

                         Python logging module
'--debug-level=level',   debug level.  One of     All MySQL 5.7 based
                         DEBUG, INFO, WARNING     releases
' -d '                   (default), ERROR, or
                         CRITICAL.

                         Print help message
'--help',                                         All MySQL 5.7 based
                                                  releases
' -h '

'--key-file=file',       Specify file             All MySQL 5.7 based
                         containing private key   releases
' -k '                   (if not included in
                         -cert-file)

                         Do not open the start
'--no-browser',          page in a browser,       All MySQL 5.7 based
                         merely start the tool    releases
' -n '

'--port=#',              Specify the port used    All MySQL 5.7 based
                         by the web server        releases
' -p '

'--server-log-file=file',Log requests to this     All MySQL 5.7 based
                         file.  Use '-' to        releases
' o '                    force logging to
                         stderr instead.

                         The name of the server
'--server-name=name',    to connect with          All MySQL 5.7 based
                                                  releases
' -N '

'--use-https',           Use encrypted (HTTPS)    All MySQL 5.7 based
                         client/server            releases
' -S '                   connection

   *
     '--browser-start-page=FILE', '-s'

     Property                             Value

     *Command-Line Format*                '--browser-start-page=filename'

     *Type*                               string

     *Default Value*                      'index.html'

     Specify the file to open in the browser as the installation and
     configuration Start page.  The default is 'index.html'.

   *
     '--ca-certs-file=FILE', '-a'

     Property                             Value

     *Command-Line Format*                '--ca-certs-file=filename'

     *Type*                               file name

     *Default Value*                      '[none]'

     Specify a file containing a list of client certificates which are
     allowed to connect to the server.  The default is an empty string,
     which means that no client authentication is used.

   *
     '--cert-file=FILE', '-c'

     Property                             Value

     *Command-Line Format*                '--cert-file=filename'

     *Type*                               file name

     *Default Value*                      'cfg.pem'

     Specify a file containing an X509 certificate which identifies the
     server.  It is possible for the certificate to be self-signed.  The
     default is 'cfg.pem'.

   *
     '--debug-level=LEVEL', '-d'

     Property                             Value

     *Command-Line Format*                '--debug-level=level'

     *Type*                               enumeration

     *Default Value*                      'WARNING'

     *Valid Values*                       'WARNING' 'DEBUG' 'INFO' 'ERROR'
                                          'CRITICAL'

     Set the Python logging module debug level.  This is one of 'DEBUG',
     'INFO', 'WARNING', 'ERROR', or 'CRITICAL'.  'WARNING' is the
     default.

   *
     '--help', '-h'

     Property                             Value

     *Command-Line Format*                '--help'

     Print a help message.

   *
     '--key-file=FILE', '-d'

     Property                             Value

     *Command-Line Format*                '--key-file=file'

     *Type*                               file name

     *Default Value*                      '[none]'

     Specify a file containing the private key if this is not included
     in the X509 certificate file ('--cert-file').  The default is an
     empty string, which means that no such file is used.

   *
     '--no-browser', '-n'

     Property                             Value

     *Command-Line Format*                '--no-browser'

     Start the installation and configuration tool, but do not open the
     Start page in a browser.

   *
     '--port=#', '-p'

     Property                             Value

     *Command-Line Format*                '--port=#'

     *Type*                               numeric

     *Default Value*                      '8081'

     *Minimum Value*                      '1'

     *Maximum Value*                      '65535'

     Set the port used by the web server.  The default is 8081.

   *
     '--server-log-file=FILE', '-o'

     Property                             Value

     *Command-Line Format*                '--server-log-file=file' 'o'

     *Type*                               file name

     *Default Value*                      'ndb_setup.log'

     *Valid Values*                       'ndb_setup.log' '-' (Log to
                                          stderr)

     Log requests to this file.  The default is 'ndb_setup.log'.  To
     specify logging to 'stderr', rather than to a file, use a '-' (dash
     character) for the file name.

   *
     '--server-name=HOST', '-N'

     Property                             Value

     *Command-Line Format*                '--server-name=name'

     *Type*                               string

     *Default Value*                      'localhost'

     Specify the host name or IP address for the browser to use when
     connecting.  The default is 'localhost'.

   *
     '--use-https', '-S'

     Property                             Value

     *Command-Line Format*                '--use-https'

     Make the browser use a secure (HTTPS) connection with the server.

21.4.28 'ndb_show_tables' -- Display List of NDB Tables
-------------------------------------------------------

See 'ndb_show_tables'.
displays a list of all 'NDB' database objects in
the cluster.  By default, this includes not only both user-created
tables and 'NDB' system tables, but 'NDB'.
-specific indexes, internal triggers, and NDB Cluster Disk
Data objects as well.

The following table includes options that are specific to the NDB
Cluster native backup restoration program 'ndb_show_tables'.
Additional descriptions follow
the table.  For options common to most NDB Cluster programs (including
'ndb_show_tables'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_show_tables program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Specifies the database
'--database=string',     in which the table is    All MySQL 5.7 based
                         found                    releases
' -d '

'--loops=#',             Number of times to       All MySQL 5.7 based
                         repeat output            releases
' -l '

'--parsable',            Return output suitable   All MySQL 5.7 based
                         for MySQL LOAD DATA      releases
' -p '                   INFILE statement

                         Show table temporary
' --show-temp-status '   flag                     All MySQL 5.7 based
                                                  releases

                         Limit output to
'--type=#',              objects of this type     All MySQL 5.7 based
                                                  releases
' -t '

'--unqualified',         Do not qualify table     All MySQL 5.7 based
                         names                    releases
' -u '

*Usage*

     ndb_show_tables [-c CONNECTION_STRING]

   *
     '--database', '-d'

     Specifies the name of the database in which the tables are found.
     If this option has not been specified, and no tables are found in
     the 'TEST_DB' database, see 'ndb_show_tables'
     issues a warning.

   *
     '--loops', '-l'

     Specifies the number of times the utility should execute.  This is
     1 when this option is not specified, but if you do use the option,
     you must supply an integer argument for it.

   *
     '--parsable', '-p'

     Using this option causes the output to be in a format suitable for
     use with 'LOAD DATA INFILE'.

   *
     '--show-temp-status'

     If specified, this causes temporary tables to be displayed.

   *
     '--type', '-t'

     Can be used to restrict the output to one type of object, specified
     by an integer type code as shown here:

        * '1': System table

        * '2': User-created table

        * '3': Unique hash index

     Any other value causes all 'NDB' database
     objects to be listed (the default).

   *
     '--unqualified', '-u'

     If specified, this causes unqualified object names to be displayed.

*Note*:

Only user-created NDB Cluster tables may be accessed from MySQL; system
tables such as 'SYSTAB_0' are not visible to 'mysqld'.
However, you can examine the contents of system tables using
'NDB'. API applications such as 'ndb_select_all'.
(see
mysql-cluster-programs-ndb-select-all).

21.4.29 'ndb_size.pl' -- NDBCLUSTER Size Requirement Estimator
--------------------------------------------------------------

This is a Perl script that can be used to estimate the amount of space
that would be required by a MySQL database if it were converted to use
the 'NDBCLUSTER' storage engine.  Unlike the other
utilities discussed in this section, it does not require access to an
NDB Cluster (in fact, there is no reason for it to do so).  However, it
does need to access the MySQL server on which the database to be tested
resides.

*Requirements*

   * A running MySQL server.  The server instance does not have to
     provide support for NDB Cluster.

   * A working installation of Perl.

   * The 'DBI' module, which can be obtained from CPAN if it is not
     already part of your Perl installation.  (Many Linux and other
     operating system distributions provide their own packages for this
     library.)

   * A MySQL user account having the necessary privileges.  If you do
     not wish to use an existing account, then creating one using 'GRANT
     USAGE ON DB_NAME.*'--where DB_NAME is the name of the database to
     be examined--is sufficient for this purpose.

'ndb_size.pl' can also be found in the MySQL sources in
'storage/ndb/tools'.

The following table includes options that are specific to the NDB
Cluster program 'ndb_size.pl'.
Additional descriptions follow the table.  For options common to most
NDB Cluster programs (including 'ndb_size.pl'),
see
mysql-cluster-program-options-common.

*Command-line options for the ndb_size.pl program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         The database or
' --database=dbname '    databases to examine;    All MySQL 5.7 based
                         accepts a                releases
                         comma-delimited list;
                         the default is ALL
                         (use all databases
                         found on the server)

                         Specify host and
' --hostname[:port] '    optional port as         All MySQL 5.7 based
                         host[:port]              releases

                         Specify a socket to
' --socket=file_name '   connect to               All MySQL 5.7 based
                                                  releases

                         Specify a MySQL user
' --user=string '        name                     All MySQL 5.7 based
                                                  releases

                         Specify a MySQL user
' --password=string '    password                 All MySQL 5.7 based
                                                  releases

                         Set output format
' --format=string '      (text or HTML)           All MySQL 5.7 based
                                                  releases

                         Skip any tables in a
'                        comma-separated list     All MySQL 5.7 based
--excludetables=tbl_list of tables                releases
'

' --excludedbs=db_list   Skip any databases in    All MySQL 5.7 based
'                        a comma-separated list   releases
                         of databases

                         Saves all queries to
' --savequeries=file '   the database into the    All MySQL 5.7 based
                         file specified           releases

                         Loads all queries from
' --loadqueries=file '   the file specified;      All MySQL 5.7 based
                         does not connect to a    releases
                         database

                         Designates a table to
'                        handle unique index      All MySQL 5.7 based
--real_table_name=table  size calculations        releases
'

*Usage*

     perl ndb_size.pl [--database={DB_NAME|ALL}] [--hostname=HOST[:PORT]] [--socket=SOCKET] \
           [--user=USER] [--password=PASSWORD]  \
           [--help|-h] [--format={html|text}] \
           [--loadqueries=FILE_NAME] [--savequeries=FILE_NAME]

By default, this utility attempts to analyze all databases on the
server.  You can specify a single database using the '--database'
option; the default behavior can be made explicit by using 'ALL' for the
name of the database.  You can also exclude one or more databases by
using the '--excludedbs' option with a comma-separated list of the names
of the databases to be skipped.  Similarly, you can cause specific
tables to be skipped by listing their names, separated by commas,
following the optional '--excludetables' option.  A host name can be
specified using '--hostname'; the default is 'localhost'.  You can
specify a port in addition to the host using HOST:PORT format for the
value of '--hostname'.  The default port number is 3306.  If necessary,
you can also specify a socket; the default is '/var/lib/mysql.sock'.  A
MySQL user name and password can be specified the corresponding options
shown.  It also possible to control the format of the output using the
'--format' option; this can take either of the values 'html' or 'text',
with 'text' being the default.  An example of the text output is shown
here:

     shell> ndb_size.pl --database=test --socket=/tmp/mysql.sock
     ndb_size.pl report for database: 'test' (1 tables)
     --------------------------------------------------
     Connected to: DBI:mysql:host=localhost;mysql_socket=/tmp/mysql.sock

     Including information for versions: 4.1, 5.0, 5.1

     test.t1
     -------

     DataMemory for Columns (* means varsized DataMemory):
              Column Name            Type  Varsized   Key  4.1  5.0   5.1
          HIDDEN_NDB_PKEY          bigint             PRI    8    8     8
                       c2     varchar(50)         Y         52   52    4*
                       c1         int(11)                    4    4     4
                                                            --   --    --
     Fixed Size Columns DM/Row                              64   64    12
        Varsize Columns DM/Row                               0    0     4

     DataMemory for Indexes:
        Index Name                 Type        4.1        5.0        5.1
           PRIMARY                BTREE         16         16         16
                                                --         --         --
            Total Index DM/Row                  16         16         16

     IndexMemory for Indexes:
                    Index Name        4.1        5.0        5.1
                       PRIMARY         33         16         16
                                       --         --         --
                Indexes IM/Row         33         16         16

     Summary (for THIS table):
                                      4.1        5.0        5.1
         Fixed Overhead DM/Row         12         12         16
                NULL Bytes/Row          4          4          4
                DataMemory/Row         96         96         48
                         (Includes overhead, bitmap and indexes)

       Varsize Overhead DM/Row          0          0          8
        Varsize NULL Bytes/Row          0          0          4
            Avg Varside DM/Row          0          0         16

                      No. Rows          0          0          0

             Rows/32kb DM Page        340        340        680
     Fixedsize DataMemory (KB)          0          0          0

     Rows/32kb Varsize DM Page          0          0       2040
       Varsize DataMemory (KB)          0          0          0

              Rows/8kb IM Page        248        512        512
              IndexMemory (KB)          0          0          0

     Parameter Minimum Requirements
     ------------------------------
     * indicates greater than default

                     Parameter     Default        4.1         5.0         5.1
               DataMemory (KB)       81920          0           0           0
            NoOfOrderedIndexes         128          1           1           1
                    NoOfTables         128          1           1           1
              IndexMemory (KB)       18432          0           0           0
         NoOfUniqueHashIndexes          64          0           0           0
                NoOfAttributes        1000          3           3           3
                  NoOfTriggers         768          5           5           5

For debugging purposes, the Perl arrays containing the queries run by
this script can be read from the file specified using can be saved to a
file using '--savequeries'; a file containing such arrays to be read in
during script execution can be specified using '--loadqueries'.  Neither
of these options has a default value.

To produce output in HTML format, use the '--format' option and redirect
the output to a file, as shown here:

     shell> ndb_size.pl --database=test --socket=/tmp/mysql.sock --format=html > ndb_size.html

(Without the redirection, the output is sent to 'stdout'.)

The output from this script includes the following information:

   * Minimum values for the 'DataMemory', 'IndexMemory',
     'MaxNoOfTables', 'MaxNoOfAttributes', 'MaxNoOfOrderedIndexes', and
     'MaxNoOfTriggers' configuration parameters required to accommodate
     the tables analyzed.

   * Memory requirements for all of the tables, attributes, ordered
     indexes, and unique hash indexes defined in the database.

   * The 'IndexMemory' and 'DataMemory' required per table and table
     row.

21.4.30 'ndb_top' -- View CPU usage information for NDB threads
---------------------------------------------------------------

'ndb_top' displays running
information in the terminal about CPU usage by NDB threads on an NDB
Cluster data node.  Each thread is represented by two rows in the
output, the first showing system statistics, the second showing the
measured statistics for the thread.

'ndb_top' is available beginning
with MySQL NDB Cluster 7.6.3.

*Usage*

     ndb_top [-h HOSTNAME] [-t PORT] [-u USER] [-p PASS] [-n NODE_ID]

'ndb_top' connects to a MySQL
Server running as an SQL node of the cluster.  By default, it attempts
to connect to a 'mysqld' running on 'localhost' and port
3306, as the MySQL 'root' user with no password specified.  You can
override the default host and port using, respectively, '--host' ('-h')
and '--port' ('-t').  To specify a MySQL user and password, use the
'--user' ('-u') and '--passwd' ('-p') options.  This user must be able
to read tables in the 'ndbinfo' database
(see 'ndb_top' uses information from
'ndbinfo.cpustat' and related
tables).

For more information about MySQL user accounts and passwords, see
user-account-management, as well as privilege-system.

Output is available as plain text or an ASCII graph; you can specify
this using the '--text' ('-x') and '--graph' ('-g') options,
respectively.  These two display modes provide the same information;
they can be used concurrently.  At least one display mode must be in
use.

Color display of the graph is supported and enabled by default
('--color' or '-c' option).  With color support enabled, the graph
display shows OS user time in blue, OS system time in green, and idle
time as blank.  For measured load, blue is used for execution time,
yellow for send time, red for time spent in send buffer full waits, and
blank spaces for idle time.  The percentage shown in the graph display
is the sum of percentages for all threads which are not idle.  Colors
are not currently configurable; you can use grayscale instead by using
'--skip-color'.

The sorted view ('--sort', '-r') is based on the maximum of the measured
load and the load reported by the OS. Display of these can be enabled
and disabled using the '--measured-load' ('-m') and '--os-load' ('-o')
options.  Display of at least one of these loads must be enabled.

The program tries to obtain statistics from a data node having the node
ID given by the '--node-id' ('-n') option; if unspecified, this is 1.
'ndb_top' cannot provide
information about other types of nodes.

The view adjusts itself to the height and width of the terminal window;
the minimum supported width is 76 characters.

Once started, see 'ndb_top' runs
continuously until forced to exit; you can quit the program using
'Ctrl-C'.  The display updates once per second; to set a different delay
interval, use '--sleep-time' ('-s').

*Note*:

'ndb_top' is available on Mac OS
X, Linux, and Solaris.  It is not currently supported on Windows
platforms.

The following table includes all options that are specific to the NDB
Cluster program 'ndb_top'.
Additional descriptions follow the table.

*Command-line options for the ndb_top program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Show ASCII graphs in
'--color',               color; use               ADDED: NDB 7.6.3
                         -skip-colors to
' -c '                   disable

                         Display data using
'--graph',               graphs; use              ADDED: NDB 7.6.3
                         -skip-graphs to
' -g '                   disable

                         Show program usage
'--help',                information              ADDED: NDB 7.6.3

' -? '

'--host[=name]',         Host name or IP          ADDED: NDB 7.6.3
                         address of MySQL
' -h '                   Server to connect to

                         Show measured load by
'--measured-load',       thread                   ADDED: NDB 7.6.3

' -m '

'--node-id[=#]',         Watch node having this   ADDED: NDB 7.6.3
                         node ID
' -n '

'--os-load',             Show load measured by    ADDED: NDB 7.6.3
                         operating system
' -o '

'--passwd[=password]',   Connect using this       ADDED: NDB 7.6.3
                         password
' -p '                                            REMOVED: NDB 7.6.4

                         Connect using this
'--password[=password]', password                 ADDED: NDB 7.6.5

' -p '

'--port[=#]',            Port number to use       ADDED: NDB 7.6.3
                         when connecting to
'-t' (<=7.6.4),          MySQL Server

'-P' (>=7.6.5)

'--sleep-time[=seconds]',Time to wait between     ADDED: NDB 7.6.3
                         display refreshes, in
' -s '                   seconds

                         Sort threads by usage;
'--sort',                use -skip-sort to        ADDED: NDB 7.6.3
                         disable
' -r '

'--text',                Display data using       ADDED: NDB 7.6.3
                         text
'-x' (<=7.6.4),

'-t' (>=7.6.5)

'--user[=name]',         Connect as this MySQL    ADDED: NDB 7.6.3
                         user
' -u '

*Additional Options*

   *
     '--color', '-c'

     Property                             Value

     *Command-Line Format*                '--color'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Show ASCII graphs in color; use '--skip-colors' to disable.

   *
     '--graph', '-g'

     Property                             Value

     *Command-Line Format*                '--graph'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Display data using graphs; use '--skip-graphs' to disable.  This
     option or '--text' must be true; both options may be true.

   *
     '--help', '-?'

     Property                             Value

     *Command-Line Format*                '--help'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Show program usage information.

   *
     '--host['=NAME], '-h'

     Property                             Value

     *Command-Line Format*                '--host[=name]'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               string

     *Default Value*                      'localhost'

     Host name or IP address of MySQL Server to connect to.

   *
     '--measured-load', '-m'

     Property                             Value

     *Command-Line Format*                '--measured-load'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Show measured load by thread.  This option or '--os-load' must be
     true; both options may be true.

   *
     '--node-id['=#], '-n'

     Property                             Value

     *Command-Line Format*                '--node-id[=#]'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               integer

     *Default Value*                      '1'

     Watch the data node having this node ID.

   *
     '--os-load', '-o'

     Property                             Value

     *Command-Line Format*                '--os-load'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Show load measured by operating system.  This option or
     '--measured-load' must be true; both options may be true.

   *
     '--passwd['=PASSWORD], '-p'

     Property                             Value

     *Command-Line Format*                '--passwd[=password]'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Removed*                            5.7.20-ndb-7.6.4

     *Type*                               boolean

     *Default Value*                      'NULL'

     Connect using this password.

     This option is deprecated in NDB 7.6.4.  It is removed in NDB
     7.6.5, where it is replaced by the '--password' option.  (Bug
     #26907833)

   *
     '--password['=PASSWORD], '-p'

     Property                             Value

     *Command-Line Format*                '--password[=password]'

     *Introduced*                         5.7.21-ndb-7.6.5

     *Type*                               boolean

     *Default Value*                      'NULL'

     Connect using this password.

     This option was added in NDB 7.6.5 as a replacement for the
     '--passwd' option used previously.  (Bug #26907833)

   *
     '--port['=#], '-t' (NDB 7.6.5 and later: '-P')

     Property                             Value

     *Command-Line Format*                '--port[=#]'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               integer

     *Default Value*                      '3306'

     Port number to use when connecting to MySQL Server.

     Beginning with NDB 7.6.5, the short form for this option is '-P',
     and '-t' is repurposed as the short form for the '--text' option.
     (Bug #26907833)

   *
     '--sleep-time['=SECONDS], '-s'

     Property                             Value

     *Command-Line Format*                '--sleep-time[=seconds]'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               integer

     *Default Value*                      '1'

     Time to wait between display refreshes, in seconds.

   *
     '--sort', '-r'

     Property                             Value

     *Command-Line Format*                '--sort'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Sort threads by usage; use '--skip-sort' to disable.

   *
     '--text', '-x' (NDB 7.6.5 and later: '-t')

     Property                             Value

     *Command-Line Format*                '--text'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Display data using text.  This option or '--graph' must be true;
     both options may be true.

     Beginning with NDB 7.6.5, the short form for this option is '-t'
     and support for '-x' is removed.  (Bug #26907833)

   *
     '--user['=NAME], '-u'

     Property                             Value

     *Command-Line Format*                '--user[=name]'

     *Introduced*                         5.7.19-ndb-7.6.3

     *Type*                               string

     *Default Value*                      'root'

     Connect as this MySQL user.

Sample Output

The next figure shows 'ndb_top'.
running in a terminal window on a Linux system with an 'ndbmtd'
data node under a moderate load.  Here,
the program has been invoked using 'ndb_top'.
'-n8' '-x' to provide both text and
graph output:

FIGURE GOES HERE: ndb_top Running in Terminal

21.4.31 'ndb_waiter' -- Wait for NDB Cluster to Reach a Given Status
--------------------------------------------------------------------

'ndb_waiter' repeatedly (each
100 milliseconds) prints out the status of all cluster data nodes until
either the cluster reaches a given status or the '--timeout' limit is
exceeded, then exits.  By default, it waits for the cluster to achieve
'STARTED' status, in which all nodes have started and connected to the
cluster.  This can be overridden using the '--no-contact' and
'--not-started' options.

The node states reported by this utility are as follows:

   * 'NO_CONTACT': The node cannot be contacted.

   * 'UNKNOWN': The node can be contacted, but its status is not yet
     known.  Usually, this means that the node has received a 'START' or
     'RESTART' command from the management server, but has not yet acted
     on it.

   * 'NOT_STARTED': The node has stopped, but remains in contact with
     the cluster.  This is seen when restarting the node using the
     management client's 'RESTART' command.

   * 'STARTING': The node's 'ndbd'.
     process has started, but the node has not yet joined the cluster.

   * 'STARTED': The node is operational, and has joined the cluster.

   * 'SHUTTING_DOWN': The node is shutting down.

   * 'SINGLE USER MODE': This is shown for all cluster data nodes when
     the cluster is in single user mode.

The following table includes options that are specific to the NDB
Cluster native backup restoration program 'ndb_waiter'.
Additional descriptions follow the
table.  For options common to most NDB Cluster programs (including
'ndb_waiter'), see
mysql-cluster-program-options-common.

*Command-line options for the ndb_waiter program*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Wait for cluster to
'--no-contact',          reach NO CONTACT state   All MySQL 5.7 based
                                                  releases
' -n '

' --not-started '        Wait for cluster to      All MySQL 5.7 based
                         reach NOT STARTED        releases
                         state

                         Wait for cluster to
' --single-user '        enter single user mode   All MySQL 5.7 based
                                                  releases

                         Wait this many
'--timeout=#',           seconds, then exit       All MySQL 5.7 based
                         whether or not cluster   releases
' -t '                   has reached desired
                         state; default is 2
                         minutes (120 seconds)

                         List of nodes not to
' --nowait-nodes=list    be waited for.           All MySQL 5.7 based
'                                                 releases

                         List of nodes to be
'--wait-nodes=list',     waited for.              All MySQL 5.7 based
                                                  releases
' -w '

*Usage*

     ndb_waiter [-c CONNECTION_STRING]

*Additional Options*

   *
     '--no-contact', '-n'

     Instead of waiting for the 'STARTED' state, see 'ndb_waiter'
     continues running until the
     cluster reaches 'NO_CONTACT' status before exiting.

   *
     '--not-started'

     Instead of waiting for the 'STARTED' state, see 'ndb_waiter'
     continues running until the
     cluster reaches 'NOT_STARTED' status before exiting.

   *
     '--timeout=SECONDS', '-t SECONDS'

     Time to wait.  The program exits if the desired state is not
     achieved within this number of seconds.  The default is 120 seconds
     (1200 reporting cycles).

   *
     '--single-user'

     The program waits for the cluster to enter single user mode.

   *
     '--nowait-nodes=LIST'

     When this option is used, ndb_waiter does not wait for the nodes
     whose IDs are listed.  The list is comma-delimited; ranges can be
     indicated by dashes, as shown here:

          shell> ndb_waiter --nowait-nodes=1,3,7-9

     *Important*:

     Do _not_ use this option together with the '--wait-nodes' option.

   *
     '--wait-nodes=LIST', '-w LIST'

     When this option is used, see 'ndb_waiter'
     waits only for the nodes whose
     IDs are listed.  The list is comma-delimited; ranges can be
     indicated by dashes, as shown here:

          shell> ndb_waiter --wait-nodes=2,4-6,10

     *Important*:

     Do _not_ use this option together with the '--nowait-nodes' option.

Sample Output

Shown here is the output from 'ndb_waiter'
when run against a 4-node cluster in
which two nodes have been shut down and then started again manually.
Duplicate reports (indicated by '...') are omitted.

     shell> ./ndb_waiter -c localhost

     Connecting to mgmsrv at (localhost)
     State node 1 STARTED
     State node 2 NO_CONTACT
     State node 3 STARTED
     State node 4 NO_CONTACT
     Waiting for cluster enter state STARTED

     ...

     State node 1 STARTED
     State node 2 UNKNOWN
     State node 3 STARTED
     State node 4 NO_CONTACT
     Waiting for cluster enter state STARTED

     ...

     State node 1 STARTED
     State node 2 STARTING
     State node 3 STARTED
     State node 4 NO_CONTACT
     Waiting for cluster enter state STARTED

     ...

     State node 1 STARTED
     State node 2 STARTING
     State node 3 STARTED
     State node 4 UNKNOWN
     Waiting for cluster enter state STARTED

     ...

     State node 1 STARTED
     State node 2 STARTING
     State node 3 STARTED
     State node 4 STARTING
     Waiting for cluster enter state STARTED

     ...

     State node 1 STARTED
     State node 2 STARTED
     State node 3 STARTED
     State node 4 STARTING
     Waiting for cluster enter state STARTED

     ...

     State node 1 STARTED
     State node 2 STARTED
     State node 3 STARTED
     State node 4 STARTED
     Waiting for cluster enter state STARTED

     NDBT_ProgramExit: 0 - OK

*Note*:

If no connection string is specified, then 'ndb_waiter'
tries to connect to a management on
'localhost', and reports 'Connecting to mgmsrv at (null)'.

21.4.32 Options Common to NDB Cluster Programs -- Options Common to NDB Cluster Programs
----------------------------------------------------------------------------------------

All NDB Cluster programs accept the options described in this section,
with the following exceptions:

   * 'mysqld'.

   * 'ndb_print_backup_file'.

   * 'ndb_print_schema_file'.

   * 'ndb_print_sys_file'.

*Note*:

Users of earlier NDB Cluster versions should note that some of these
options have been changed to make them consistent with one another, and
also with 'mysqld'.  You can use the '--help' option with
any NDB Cluster program--with the exception of
'ndb_print_backup_file',
'ndb_print_schema_file',
and
'ndb_print_sys_file'.--to
view a list of the options which the program supports.

The options in the following table are common to all NDB Cluster
executables (except those noted previously in this section).

*Command-line options common to all MySQL NDB Cluster programs*

Format                   Description              Added, Deprecated, or
                                                  Removed

                         Directory where
'                        character sets are       All MySQL 5.7 based
--character-sets-dir=dir_nameinstalled            releases
'

' --connect-retries=#    Set the number of        All MySQL 5.7 based
'                        times to retry a         releases
                         connection before
                         giving up

                         Time to wait between
'                        attempts to contact a    All MySQL 5.7 based
--connect-retry-delay=#  management server, in    releases
'                        seconds

                         Write core on errors
' --core-file '          (defaults to TRUE in     All MySQL 5.7 based
                         debug builds)            releases

                         Enable output from
' --debug=options '      debug calls.  Can be     All MySQL 5.7 based
                         used only for versions   releases
                         compiled with
                         debugging enabled

                         Read this file after
'                        global option files      All MySQL 5.7 based
--defaults-extra-file=filenameare read            releases
'

'                        Read default options     All MySQL 5.7 based
--defaults-file=filename from this file           releases
'

'                        Also read groups with    All MySQL 5.7 based
--defaults-group-suffix  names ending in this     releases
'                        suffix

                         Display help message
'--help',                and exit                 All MySQL 5.7 based
                                                  releases
'--usage',

' -? '

' --login-path=path '    Read this path from      All MySQL 5.7 based
                         the login file           releases

                         Set connection string
'--ndb-connectstring=connectstring',for connecting toAll MySQL 5.7 based
                         ndb_mgmd.  Syntax:       releases
'--connect-string=connectstring',[nodeid=<id>;][host=]<hostname>[:<port>].
                         Overrides entries
' -c '                   specified in
                         NDB_CONNECTSTRING or
                         my.cnf.

                         Set the host (and
'                        port, if desired) for    All MySQL 5.7 based
--ndb-mgmd-host=host[:port]connecting to          releases
'                        management server

                         Set node id for this
' --ndb-nodeid=# '       node                     All MySQL 5.7 based
                                                  releases

                         Select nodes for
'                        transactions in a more   All MySQL 5.7 based
--ndb-optimized-node-selectionoptimal way         releases
'

' --no-defaults '        Do not read default      All MySQL 5.7 based
                         options from any         releases
                         option file other than
                         login file

                         Print the program
' --print-defaults '     argument list and exit   All MySQL 5.7 based
                                                  releases

                         Output version
'--version',             information and exit     All MySQL 5.7 based
                                                  releases
' -V '

For options specific to individual NDB Cluster programs, see
mysql-cluster-programs.

See mysql-cluster-program-options-mysqld, for 'mysqld'
options relating to NDB Cluster.

   *
     '--character-sets-dir=NAME'

     Property                             Value

     *Command-Line Format*                '--character-sets-dir=dir_name'

     *Type*                               directory name

     *Default Value*                      ''

     Tells the program where to find character set information.

   *
     '--connect-retries=#'

     Property                             Value

     *Command-Line Format*                '--connect-retries=#'

     *Type*                               numeric

     *Default Value*                      '12'

     *Minimum Value*                      '0'

     *Maximum Value*                      '4294967295'

     This option specifies the number of times following the first
     attempt to retry a connection before giving up (the client always
     tries the connection at least once).  The length of time to wait
     per attempt is set using '--connect-retry-delay'.

     *Note*:

     When used with 'ndb_mgm',
     this option has 3 as its default.  See
     mysql-cluster-programs-ndb-mgm, for more information.

   *
     '--connect-retry-delay=#'

     Property                             Value

     *Command-Line Format*                '--connect-retry-delay=#'

     *Type* (>= 5.7.10-ndb-7.5.0)         numeric

     *Type*                               numeric

     *Default Value* (>=                  '5'
     5.7.10-ndb-7.5.0)

     *Default Value*                      '5'

     *Minimum Value* (>=                  '1'
     5.7.10-ndb-7.5.0)

     *Minimum Value*                      '0'

     *Maximum Value* (>=                  '4294967295'
     5.7.10-ndb-7.5.0)

     *Maximum Value*                      '4294967295'

     This option specifies the length of time to wait per attempt a
     connection before giving up.  The number of times to try connecting
     is set by '--connect-retries'.

   *
     '--core-file'

     Property                             Value

     *Command-Line Format*                '--core-file'

     *Type*                               boolean

     *Default Value*                      'FALSE'

     Write a core file if the program dies.  The name and location of
     the core file are system-dependent.  (For NDB Cluster programs
     nodes running on Linux, the default location is the program's
     working directory--for a data node, this is the node's 'DataDir'.)
     For some systems, there may be restrictions or limitations; for
     example, it might be necessary to execute 'ulimit -c unlimited'
     before starting the server.  Consult your system documentation for
     detailed information.

     If NDB Cluster was built using the '--debug' option for
     'configure', then '--core-file' is enabled by default.  For regular
     builds, '--core-file' is disabled by default.

   *
     '--debug[=OPTIONS]'

     Property                             Value

     *Command-Line Format*                '--debug=options'

     *Type*                               string

     *Default Value*                      'd:t:O,/tmp/ndb_restore.trace'

     This option can be used only for versions compiled with debugging
     enabled.  It is used to enable output from debug calls in the same
     manner as for the 'mysqld' process.

   *
     '--defaults-extra-file'=FILENAME

     Property                             Value

     *Command-Line Format*                '--defaults-extra-file=filename'

     *Type*                               string

     *Default Value*                      '[none]'

     Read this file after global option files are read.

   *
     '--defaults-file'=FILENAME

     Property                             Value

     *Command-Line Format*                '--defaults-file=filename'

     *Type*                               string

     *Default Value*                      '[none]'

     Read default options from this file.

   *
     '--defaults-group-suffix'

     Property                             Value

     *Command-Line Format*                '--defaults-group-suffix'

     *Type*                               string

     *Default Value*                      '[none]'

     Also read groups with names ending in this suffix.

   *
     '--help', '--usage', '-?'

     Property                             Value

     *Command-Line Format*                '--help' '--usage'

     Prints a short list with descriptions of the available command
     options.

   *
     '--login-path'=PATH

     Property                             Value

     *Command-Line Format*                '--login-path=path'

     *Type*                               string

     *Default Value*                      '[none]'

     Read this path from the login file.

   *
     '--ndb-connectstring=CONNECTION_STRING',
     '--connect-string=CONNECTION_STRING', '-c CONNECTION_STRING'

     Property                             Value

     *Command-Line Format*                '--ndb-connectstring=connectstring'
                                          '--connect-string=connectstring'

     *Type*                               string

     *Default Value*                      'localhost:1186'

     This option takes an NDB Cluster connection string that specifies
     the management server for the application to connect to, as shown
     here:

          shell> ndbd --ndb-connectstring="nodeid=2;host=ndb_mgmd.mysql.com:1186"

     For more information, see mysql-cluster-connection-strings.

   *
     '--ndb-mgmd-host=HOST[:PORT]'

     Property                             Value

     *Command-Line Format*                '--ndb-mgmd-host=host[:port]'

     *Type*                               string

     *Default Value*                      'localhost:1186'

     Can be used to set the host and port number of a single management
     server for the program to connect to.  If the program requires node
     IDs or references to multiple management servers (or both) in its
     connection information, use the '--ndb-connectstring' option
     instead.

   *
     '--ndb-nodeid=#'

     Property                             Value

     *Command-Line Format*                '--ndb-nodeid=#'

     *Type*                               numeric

     *Default Value*                      '0'

     Sets this node's NDB Cluster node ID. _The range of permitted
     values depends on the node's type (data, management, or API) and
     the NDB Cluster software version_.  See
     mysql-cluster-limitations-limits, for more information.

   *
     '--no-defaults'

     Property                             Value

     *Command-Line Format*                '--no-defaults'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Do not read default options from any option file other than login
     file.

   *
     '--ndb-optimized-node-selection'

     Property                             Value

     *Command-Line Format*                '--ndb-optimized-node-selection'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Optimize selection of nodes for transactions.  Enabled by default.

   *
     '--print-defaults'

     Property                             Value

     *Command-Line Format*                '--print-defaults'

     *Type*                               boolean

     *Default Value*                      'TRUE'

     Print the program argument list and exit.

   *
     '--version', '-V'

     Property                             Value

     *Command-Line Format*                '--version'

     Prints the NDB Cluster version number of the executable.  The
     version number is relevant because not all versions can be used
     together, and the NDB Cluster startup process verifies that the
     versions of the binaries being used can co-exist in the same
     cluster.  This is also important when performing an online
     (rolling) software upgrade or downgrade of NDB Cluster.

     See mysql-cluster-rolling-restart), for more information.

21.5 Management of NDB Cluster
==============================

Managing an NDB Cluster involves a number of tasks, the first of which
is to configure and start NDB Cluster.  This is covered in
mysql-cluster-configuration, and mysql-cluster-programs.

The next few sections cover the management of a running NDB Cluster.

For information about security issues relating to management and
deployment of an NDB Cluster, see mysql-cluster-security.

There are essentially two methods of actively managing a running NDB
Cluster.  The first of these is through the use of commands entered into
the management client whereby cluster status can be checked, log levels
changed, backups started and stopped, and nodes stopped and started.
The second method involves studying the contents of the cluster log
'ndb_NODE_ID_cluster.log'; this is usually found in the management
server's 'DataDir' directory, but this location can be overridden using
the 'LogDestination' option.  (Recall that NODE_ID represents the unique
identifier of the node whose activity is being logged.)  The cluster log
contains event reports generated by 'ndbd'.
It is also possible to send cluster log
entries to a Unix system log.

Some aspects of the cluster's operation can be also be monitored from an
SQL node using the 'SHOW ENGINE NDB STATUS'.
statement.

More detailed information about NDB Cluster operations is available in
real time through an SQL interface using the 'ndbinfo'
database.  For more information, see
mysql-cluster-ndbinfo.

NDB statistics counters provide improved monitoring using the
'mysql' client.  These counters, implemented in the NDB kernel,
relate to operations performed by or affecting 'Ndb'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) objects, such as
starting, closing, and aborting transactions; primary key and unique key
operations; table, range, and pruned scans; blocked threads waiting for
various operations to complete; and data and events sent and received by
NDB Cluster.  The counters are incremented by the NDB kernel whenever
NDB API calls are made or data is sent to or received by the data nodes.

'mysqld' exposes the NDB API statistics counters as
system status variables, which can be identified from the prefix common
to all of their names ('Ndb_api_').  The values of these variables can
be read in the 'mysql' client from the output of a
'SHOW STATUS' statement, or by querying either the
'SESSION_STATUS' table or the 'GLOBAL_STATUS'
table (in the 'INFORMATION_SCHEMA' database).  By
comparing the values of the status variables before and after the
execution of an SQL statement that acts on 'NDB'.
tables, you can observe the actions taken on the NDB API level that
correspond to this statement, which can be beneficial for monitoring and
performance tuning of NDB Cluster.

MySQL Cluster Manager provides an advanced command-line interface that
simplifies many otherwise complex NDB Cluster management tasks, such as
starting, stopping, or restarting an NDB Cluster with a large number of
nodes.  The MySQL Cluster Manager client also supports commands for
getting and setting the values of most node configuration parameters as
well as 'mysqld' server options and variables relating to
NDB Cluster.  See MySQL(tm) Cluster Manager 1.4.4 User Manual
(http://dev.mysql.com/doc/mysql-cluster-manager/1.4/en/), for more
information.

21.5.1 Summary of NDB Cluster Start Phases
------------------------------------------

This section provides a simplified outline of the steps involved when
NDB Cluster data nodes are started.  More complete information can be
found in NDB Cluster Start Phases
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-start-phases.html),
in the ''NDB' Internals Guide'.

These phases are the same as those reported in the output from the
'NODE_ID STATUS' command in the management client (see
mysql-cluster-mgm-client-commands).  These start phases are also
reported in the 'start_phase' column of the 'ndbinfo.nodes'
table.

Start types

There are several different startup types and modes, as shown in the
following list:

   * Initial start

     The cluster starts with a clean file system on all data nodes.
     This occurs either when the cluster started for the very first
     time, or when all data nodes are restarted using the '--initial'
     option.

     *Note*:

     Disk Data files are not removed when restarting a node using
     '--initial'.

   * System restart

     The cluster starts and reads data stored in the data nodes.  This
     occurs when the cluster has been shut down after having been in
     use, when it is desired for the cluster to resume operations from
     the point where it left off.

   * Node restart

     This is the online restart of a cluster node while the cluster
     itself is running.

   * Initial node restart

     This is the same as a node restart, except that the node is
     reinitialized and started with a clean file system.

Setup and initialization (phase -1)

Prior to startup, each data node (see 'ndbd'
process) must be initialized.
Initialization consists of the following steps:

  1. Obtain a node ID

  2. Fetch configuration data

  3. Allocate ports to be used for inter-node communications

  4. Allocate memory according to settings obtained from the
     configuration file

When a data node or SQL node first connects to the management node, it
reserves a cluster node ID. To make sure that no other node allocates
the same node ID, this ID is retained until the node has managed to
connect to the cluster and at least one 'ndbd'
reports that this node is connected.  This
retention of the node ID is guarded by the connection between the node
in question and 'ndb_mgmd'.

After each data node has been initialized, the cluster startup process
can proceed.  The stages which the cluster goes through during this
process are listed here:

   * Phase 0

     The 'NDBFS' and 'NDBCNTR' blocks start (see NDB Kernel Blocks
     (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks.html)).
     Data node file systems are cleared on those data nodes that were
     started with '--initial' option.

   * Phase 1

     In this stage, all remaining 'NDB' kernel
     blocks are started.  NDB Cluster connections are set up,
     inter-block communications are established, and heartbeats are
     started.  In the case of a node restart, API node connections are
     also checked.

     *Note*:

     When one or more nodes hang in Phase 1 while the remaining node or
     nodes hang in Phase 2, this often indicates network problems.  One
     possible cause of such issues is one or more cluster hosts having
     multiple network interfaces.  Another common source of problems
     causing this condition is the blocking of TCP/IP ports needed for
     communications between cluster nodes.  In the latter case, this is
     often due to a misconfigured firewall.

   * Phase 2

     The 'NDBCNTR' kernel block checks the states of all existing nodes.
     The master node is chosen, and the cluster schema file is
     initialized.

   * Phase 3

     The 'DBLQH' and 'DBTC' kernel blocks set up communications between
     them.  The startup type is determined; if this is a restart, the
     'DBDIH' block obtains permission to perform the restart.

   * Phase 4

     For an initial start or initial node restart, the redo log files
     are created.  The number of these files is equal to
     'NoOfFragmentLogFiles'.

     For a system restart:

        * Read schema or schemas.

        * Read data from the local checkpoint.

        * Apply all redo information until the latest restorable global
          checkpoint has been reached.

     For a node restart, find the tail of the redo log.

   * Phase 5

     Most of the database-related portion of a data node start is
     performed during this phase.  For an initial start or system
     restart, a local checkpoint is executed, followed by a global
     checkpoint.  Periodic checks of memory usage begin during this
     phase, and any required node takeovers are performed.

   * Phase 6

     In this phase, node groups are defined and set up.

   * Phase 7

     The arbitrator node is selected and begins to function.  The next
     backup ID is set, as is the backup disk write speed.  Nodes
     reaching this start phase are marked as 'Started'.  It is now
     possible for API nodes (including SQL nodes) to connect to the
     cluster.

   * Phase 8

     If this is a system restart, all indexes are rebuilt (by 'DBDIH').

   * Phase 9

     The node internal startup variables are reset.

   * Phase 100 (OBSOLETE)

     Formerly, it was at this point during a node restart or initial
     node restart that API nodes could connect to the node and begin to
     receive events.  Currently, this phase is empty.

   * Phase 101

     At this point in a node restart or initial node restart, event
     delivery is handed over to the node joining the cluster.  The
     newly-joined node takes over responsibility for delivering its
     primary data to subscribers.  This phase is also referred to as
     _'SUMA' handover phase_.

After this process is completed for an initial start or system restart,
transaction handling is enabled.  For a node restart or initial node
restart, completion of the startup process means that the node may now
act as a transaction coordinator.

21.5.2 Commands in the NDB Cluster Management Client
----------------------------------------------------

In addition to the central configuration file, a cluster may also be
controlled through a command-line interface available through the
management client 'ndb_mgm'.  This
is the primary administrative interface to a running cluster.

Commands for the event logs are given in
mysql-cluster-event-reports; commands for creating backups and
restoring from them are provided in mysql-cluster-backup.

Using ndb_mgm with MySQL Cluster Manager

MySQL Cluster Manager handles starting and stopping processes and tracks
their states internally, so it is not necessary to use 'ndb_mgm'
for these tasks for an NDB Cluster that
is under MySQL Cluster Manager control.  it is recommended _not_ to use
the 'ndb_mgm' command-line client
that comes with the NDB Cluster distribution to perform operations that
involve starting or stopping nodes.  These include but are not limited
to the 'START', 'STOP', 'RESTART', and 'SHUTDOWN' commands.  For more
information, see MySQL Cluster Manager Process Commands
(http://dev.mysql.com/doc/mysql-cluster-manager/1.4/en/mcm-process-commands.html).

The management client has the following basic commands.  In the listing
that follows, NODE_ID denotes either a data node ID or the keyword
'ALL', which indicates that the command should be applied to all of the
cluster's data nodes.

   *
     'HELP'

     Displays information on all available commands.

   *
     'CONNECT CONNECTION-STRING'

     Connects to the management server indicated by the connection
     string.  If the client is already connected to this server, the
     client reconnects.

   *
     'SHOW'

     Displays information on the cluster's status.  Possible node status
     values include 'UNKNOWN', 'NO_CONTACT', 'NOT_STARTED', 'STARTING',
     'STARTED', 'SHUTTING_DOWN', and 'RESTARTING'.  The output from this
     command also indicates when the cluster is in single user mode
     (status 'SINGLE USER MODE').

   *
     'NODE_ID START'

     Brings online the data node identified by NODE_ID (or all data
     nodes).

     'ALL START' works on all data nodes only, and does not affect
     management nodes.

     *Important*:

     To use this command to bring a data node online, the data node must
     have been started using '--nostart' or '-n'.

   *
     'NODE_ID STOP [-a] [-f]'

     Stops the data or management node identified by NODE_ID.

     *Note*:

     'ALL STOP' works to stop all data nodes only, and does not affect
     management nodes.

     A node affected by this command disconnects from the cluster, and
     its associated 'ndbd' or
     'ndb_mgmd' process terminates.

     The '-a' option causes the node to be stopped immediately, without
     waiting for the completion of any pending transactions.

     Normally, 'STOP' fails if the result would cause an incomplete
     cluster.  The '-f' option forces the node to shut down without
     checking for this.  If this option is used and the result is an
     incomplete cluster, the cluster immediately shuts down.

     *Warning*:

     Use of the '-a' option also disables the safety check otherwise
     performed when 'STOP' is invoked to insure that stopping the node
     does not cause an incomplete cluster.  In other words, you should
     exercise extreme care when using the '-a' option with the 'STOP'
     command, due to the fact that this option makes it possible for the
     cluster to undergo a forced shutdown because it no longer has a
     complete copy of all data stored in 'NDB'.

   *
     'NODE_ID RESTART [-n] [-i] [-a] [-f]'

     Restarts the data node identified by NODE_ID (or all data nodes).

     Using the '-i' option with 'RESTART' causes the data node to
     perform an initial restart; that is, the node's file system is
     deleted and recreated.  The effect is the same as that obtained
     from stopping the data node process and then starting it again
     using 'ndbd'. '--initial' from
     the system shell.

     *Note*:

     Backup files and Disk Data files are not removed when this option
     is used.

     Using the '-n' option causes the data node process to be restarted,
     but the data node is not actually brought online until the
     appropriate 'START' command is issued.  The effect of this option
     is the same as that obtained from stopping the data node and then
     starting it again using 'ndbd'.
     '--nostart' or 'ndbd'. '-n' from
     the system shell.

     Using the '-a' causes all current transactions relying on this node
     to be aborted.  No GCP check is done when the node rejoins the
     cluster.

     Normally, 'RESTART' fails if taking the node offline would result
     in an incomplete cluster.  The '-f' option forces the node to
     restart without checking for this.  If this option is used and the
     result is an incomplete cluster, the entire cluster is restarted.

   *
     'NODE_ID STATUS'

     Displays status information for the data node identified by NODE_ID
     (or for all data nodes).

     The output from this command also indicates when the cluster is in
     single user mode.

   *
     'NODE_ID REPORT REPORT-TYPE'

     Displays a report of type REPORT-TYPE for the data node identified
     by NODE_ID, or for all data nodes using 'ALL'.

     Currently, there are three accepted values for REPORT-TYPE:

        * 'BackupStatus' provides a status report on a cluster backup in
          progress

        * 'MemoryUsage' displays how much data memory and index memory
          is being used by each data node as shown in this example:

               ndb_mgm> ALL REPORT MEMORY

               Node 1: Data usage is 5%(177 32K pages of total 3200)
               Node 1: Index usage is 0%(108 8K pages of total 12832)
               Node 2: Data usage is 5%(177 32K pages of total 3200)
               Node 2: Index usage is 0%(108 8K pages of total 12832)

          This information is also available from the
          'ndbinfo.memoryusage'.
          table.

        * 'EventLog' reports events from the event log buffers of one or
          more data nodes.

     REPORT-TYPE is case-insensitive and 'fuzzy'; for 'MemoryUsage', you
     can use 'MEMORY' (as shown in the prior example), 'memory', or even
     simply 'MEM' (or 'mem').  You can abbreviate 'BackupStatus' in a
     similar fashion.

   *
     'ENTER SINGLE USER MODE NODE_ID'

     Enters single user mode, whereby only the MySQL server identified
     by the node ID NODE_ID is permitted to access the database.

     Currently, it is not possible for data nodes to join an NDB Cluster
     while it is running in single user mode.  (Bug #20395)

   *
     'EXIT SINGLE USER MODE'

     Exits single user mode, enabling all SQL nodes (that is, all
     running 'mysqld' processes) to access the database.

     *Note*:

     It is possible to use 'EXIT SINGLE USER MODE' even when not in
     single user mode, although the command has no effect in this case.

   *
     'QUIT', 'EXIT'

     Terminates the management client.

     This command does not affect any nodes connected to the cluster.

   *
     'SHUTDOWN'

     Shuts down all cluster data nodes and management nodes.  To exit
     the management client after this has been done, use 'EXIT' or
     'QUIT'.

     This command does _not_ shut down any SQL nodes or API nodes that
     are connected to the cluster.

   *
     'CREATE NODEGROUP NODEID[, NODEID, ...]'

     Creates a new NDB Cluster node group and causes data nodes to join
     it.

     This command is used after adding new data nodes online to an NDB
     Cluster, and causes them to join a new node group and thus to begin
     participating fully in the cluster.  The command takes as its sole
     parameter a comma-separated list of node IDs--these are the IDs of
     the nodes just added and started that are to join the new node
     group.  The number of nodes must be the same as the number of nodes
     in each node group that is already part of the cluster (each NDB
     Cluster node group must have the same number of nodes).  In other
     words, if the NDB Cluster has 2 node groups of 2 data nodes each,
     then the new node group must also have 2 data nodes.

     The node group ID of the new node group created by this command is
     determined automatically, and always the next highest unused node
     group ID in the cluster; it is not possible to set it manually.

     For more information, see mysql-cluster-online-add-node.

   *
     'DROP NODEGROUP NODEGROUP_ID'

     Drops the NDB Cluster node group with the given NODEGROUP_ID.

     This command can be used to drop a node group from an NDB Cluster.
     'DROP NODEGROUP' takes as its sole argument the node group ID of
     the node group to be dropped.

     'DROP NODEGROUP' acts only to remove the data nodes in the effected
     node group from that node group.  It does not stop data nodes,
     assign them to a different node group, or remove them from the
     cluster's configuration.  A data node that does not belong to a
     node group is indicated in the output of the management client
     'SHOW' command with 'no nodegroup' in place of the node group ID,
     like this (indicated using bold text):

          id=3    @10.100.2.67  (5.7.22-ndb-7.5.11, *no nodegroup*)

     'DROP NODEGROUP' works only when all data nodes in the node group
     to be dropped are completely empty of any table data and table
     definitions.  Since there is currently no way using
     'ndb_mgm' or the 'mysql'
     client to remove all data from a specific data node or node
     group, this means that the command succeeds only in the two
     following cases:

       1. After issuing 'CREATE NODEGROUP' in the 'ndb_mgm'
          client, but before issuing any
          'ALTER TABLE ... REORGANIZE PARTITION'.
          statements in the 'mysql' client.

       2. After dropping all 'NDBCLUSTER' tables
          using 'DROP TABLE'.

          'TRUNCATE TABLE' does not work for this
          purpose because this removes only the table data; the data
          nodes continue to store an 'NDBCLUSTER'.
          table's definition until a 'DROP TABLE'.
          statement is issued that causes the table metadata to be
          dropped.

     For more information about 'DROP NODEGROUP', see
     mysql-cluster-online-add-node.

   *
     'PROMPT [PROMPT]'

     Changes the prompt shown by 'ndb_mgm'
     to the string literal PROMPT.

     PROMPT should not be quoted (unless you want the prompt to include
     the quotation marks).  Unlike the case with the 'mysql'
     client, special character sequences and escapes are not
     recognized.  If called without an argument, the command resets the
     prompt to the default value ('ndb_mgm>').

     Some examples are shown here:

          ndb_mgm> PROMPT mgm#1:
          mgm#1: SHOW
          Cluster Configuration
          ...
          mgm#1: PROMPT mymgm >
          mymgm > PROMPT 'mymgm:'
          'mymgm:' PROMPT  mymgm:
          mymgm: PROMPT
          ndb_mgm> EXIT
          jon@valhaj:~/bin>

     Note that leading spaces and spaces within the PROMPT string are
     not trimmed.  Trailing spaces are removed.

     The 'PROMPT' command was added in NDB 7.5.0.

   *
     'NODE_ID NODELOG DEBUG {ON|OFF}'

     Toggles debug logging in the node log, as though the effected data
     node or nodes had been started with the '--verbose' option.
     'NODELOG DEBUG ON' starts debug logging; 'NODELOG DEBUG OFF'
     switches debug logging off.

     This command was added in NDB 7.6.4.

Additional commands

A number of other commands available in the 'ndb_mgm'
client are described elsewhere, as shown
in the following list:

   * 'START BACKUP'.
     is used to perform an online backup in the 'ndb_mgm'
     client; the 'ABORT BACKUP' command
     is used to cancel a backup already in progress.  For more
     information, see mysql-cluster-backup.

   * The 'CLUSTERLOG'.
     command is used to perform various logging functions.  See
     mysql-cluster-event-reports, for more information and examples.
     NDB 7.6.4 adds NODELOG DEBUG to activate or deactivate debug
     printouts in node logs, as described previously in this section.

   * For testing and diagnostics work, the client supports a 'DUMP'
     (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-dump-commands.html)
     command which can be used to execute internal commands on the
     cluster.  It should never be used in a production setting unless
     directed to do so by MySQL Support.  For more information, see
     MySQL NDB Cluster Internals Manual
     (http://dev.mysql.com/doc/ndb-internals/en/).

21.5.3 Online Backup of NDB Cluster
-----------------------------------

The next few sections describe how to prepare for and then to create an
NDB Cluster backup using the functionality for this purpose found in the
'ndb_mgm' management client.  To
distinguish this type of backup from a backup made using
'mysqldump', we sometimes refer to it as a 'native' NDB
Cluster backup.  (For information about the creation of backups with
'mysqldump', see mysqldump.)  Restoration of
NDB Cluster backups is done using the 'ndb_restore'
utility provided with the NDB
Cluster distribution; for information about 'ndb_restore'
and its use in restoring NDB Cluster
backups, see mysql-cluster-programs-ndb-restore.

21.5.3.1 NDB Cluster Backup Concepts
....................................

A backup is a snapshot of the database at a given time.  The backup
consists of three main parts:

   * Metadata

     The names and definitions of all database tables

   * Table records

     The data actually stored in the database tables at the time that
     the backup was made

   * Transaction log

     A sequential record telling how and when data was stored in the
     database

Each of these parts is saved on all nodes participating in the backup.
During backup, each node saves these three parts into three files on
disk:

   * 'BACKUP-BACKUP_ID.NODE_ID.ctl'

     A control file containing control information and metadata.  Each
     node saves the same table definitions (for all tables in the
     cluster) to its own version of this file.

   * 'BACKUP-BACKUP_ID-0.NODE_ID.data'

     A data file containing the table records, which are saved on a
     per-fragment basis.  That is, different nodes save different
     fragments during the backup.  The file saved by each node starts
     with a header that states the tables to which the records belong.
     Following the list of records there is a footer containing a
     checksum for all records.

   * 'BACKUP-BACKUP_ID.NODE_ID.log'

     A log file containing records of committed transactions.  Only
     transactions on tables stored in the backup are stored in the log.
     Nodes involved in the backup save different records because
     different nodes host different database fragments.

In the listing just shown, BACKUP_ID stands for the backup identifier
and NODE_ID is the unique identifier for the node creating the file.

The location of the backup files is determined by the 'BackupDataDir'
parameter.

21.5.3.2 Using The NDB Cluster Management Client to Create a Backup
...................................................................

Before starting a backup, make sure that the cluster is properly
configured for performing one.  (See
mysql-cluster-backup-configuration.)

The 'START BACKUP' command is used to create a backup:

     START BACKUP [BACKUP_ID] [WAIT_OPTION] [SNAPSHOT_OPTION]

     WAIT_OPTION:
     WAIT {STARTED | COMPLETED} | NOWAIT

     SNAPSHOT_OPTION:
     SNAPSHOTSTART | SNAPSHOTEND

Successive backups are automatically identified sequentially, so the
BACKUP_ID, an integer greater than or equal to 1, is optional; if it is
omitted, the next available value is used.  If an existing BACKUP_ID
value is used, the backup fails with the error 'Backup failed: file
already exists'.  If used, the BACKUP_ID must follow 'START BACKUP'
immediately, before any other options are used.

The WAIT_OPTION can be used to determine when control is returned to the
management client after a 'START BACKUP' command is issued, as shown in
the following list:

   *
     If 'NOWAIT' is specified, the management client displays a prompt
     immediately, as seen here:

          ndb_mgm> START BACKUP NOWAIT
          ndb_mgm>

     In this case, the management client can be used even while it
     prints progress information from the backup process.

   *
     With 'WAIT STARTED' the management client waits until the backup
     has started before returning control to the user, as shown here:

          ndb_mgm> START BACKUP WAIT STARTED
          Waiting for started, this may take several minutes
          Node 2: Backup 3 started from node 1
          ndb_mgm>

   *
     WAIT COMPLETED causes the management client to wait until the
     backup process is complete before returning control to the user.

'WAIT COMPLETED' is the default.

A SNAPSHOT_OPTION can be used to determine whether the backup matches
the state of the cluster when 'START BACKUP' was issued, or when it was
completed.  'SNAPSHOTSTART' causes the backup to match the state of the
cluster when the backup began; 'SNAPSHOTEND' causes the backup to
reflect the state of the cluster when the backup was finished.
'SNAPSHOTEND' is the default, and matches the behavior found in previous
NDB Cluster releases.

*Note*:

If you use the 'SNAPSHOTSTART' option with 'START BACKUP', and the
'CompressedBackup' parameter is enabled, only the data and control files
are compressed--the log file is not compressed.

If both a WAIT_OPTION and a SNAPSHOT_OPTION are used, they may be
specified in either order.  For example, all of the following commands
are valid, assuming that there is no existing backup having 4 as its ID:

     START BACKUP WAIT STARTED SNAPSHOTSTART
     START BACKUP SNAPSHOTSTART WAIT STARTED
     START BACKUP 4 WAIT COMPLETED SNAPSHOTSTART
     START BACKUP SNAPSHOTEND WAIT COMPLETED
     START BACKUP 4 NOWAIT SNAPSHOTSTART

The procedure for creating a backup consists of the following steps:

  1. Start the management client (see 'ndb_mgm'),
     if it not running already.

  2. Execute the START BACKUP command.  This produces several lines of
     output indicating the progress of the backup, as shown here:

          ndb_mgm> START BACKUP
          Waiting for completed, this may take several minutes
          Node 2: Backup 1 started from node 1
          Node 2: Backup 1 started from node 1 completed
           StartGCP: 177 StopGCP: 180
           #Records: 7362 #LogRecords: 0
           Data: 453648 bytes Log: 0 bytes
          ndb_mgm>

  3.
     When the backup has started the management client displays this
     message:

          Backup BACKUP_ID started from node NODE_ID

     BACKUP_ID is the unique identifier for this particular backup.
     This identifier is saved in the cluster log, if it has not been
     configured otherwise.  NODE_ID is the identifier of the management
     server that is coordinating the backup with the data nodes.  At
     this point in the backup process the cluster has received and
     processed the backup request.  It does not mean that the backup has
     finished.  An example of this statement is shown here:

          Node 2: Backup 1 started from node 1

  4. The management client indicates with a message like this one that
     the backup has started:

          Backup BACKUP_ID started from node NODE_ID completed

     As is the case for the notification that the backup has started,
     BACKUP_ID is the unique identifier for this particular backup, and
     NODE_ID is the node ID of the management server that is
     coordinating the backup with the data nodes.  This output is
     accompanied by additional information including relevant global
     checkpoints, the number of records backed up, and the size of the
     data, as shown here:

          Node 2: Backup 1 started from node 1 completed
           StartGCP: 177 StopGCP: 180
           #Records: 7362 #LogRecords: 0
           Data: 453648 bytes Log: 0 bytes

It is also possible to perform a backup from the system shell by
invoking 'ndb_mgm' with the '-e'
or '--execute' option, as shown in this example:

     shell> ndb_mgm -e "START BACKUP 6 WAIT COMPLETED SNAPSHOTSTART"

When using 'START BACKUP' in this way, you must specify the backup ID.

Cluster backups are created by default in the 'BACKUP' subdirectory of
the 'DataDir' on each data node.  This can be overridden for one or more
data nodes individually, or for all cluster data nodes in the
'config.ini' file using the 'BackupDataDir' configuration parameter.
The backup files created for a backup with a given BACKUP_ID are stored
in a subdirectory named 'BACKUP-BACKUP_ID' in the backup directory.

Cancelling backups

To cancel or abort a backup that is already in progress, perform the
following steps:

  1. Start the management client.

  2. Execute this command:

          ndb_mgm> ABORT BACKUP BACKUP_ID

     The number BACKUP_ID is the identifier of the backup that was
     included in the response of the management client when the backup
     was started (in the message 'Backup BACKUP_ID started from node
     MANAGEMENT_NODE_ID').

  3. The management client will acknowledge the abort request with
     'Abort of backup BACKUP_ID ordered'.

     *Note*:

     At this point, the management client has not yet received a
     response from the cluster data nodes to this request, and the
     backup has not yet actually been aborted.

  4. After the backup has been aborted, the management client will
     report this fact in a manner similar to what is shown here:

          Node 1: Backup 3 started from 5 has been aborted.
            Error: 1321 - Backup aborted by user request: Permanent error: User defined error
          Node 3: Backup 3 started from 5 has been aborted.
            Error: 1323 - 1323: Permanent error: Internal error
          Node 2: Backup 3 started from 5 has been aborted.
            Error: 1323 - 1323: Permanent error: Internal error
          Node 4: Backup 3 started from 5 has been aborted.
            Error: 1323 - 1323: Permanent error: Internal error

     In this example, we have shown sample output for a cluster with 4
     data nodes, where the sequence number of the backup to be aborted
     is '3', and the management node to which the cluster management
     client is connected has the node ID '5'.  The first node to
     complete its part in aborting the backup reports that the reason
     for the abort was due to a request by the user.  (The remaining
     nodes report that the backup was aborted due to an unspecified
     internal error.)

     *Note*:

     There is no guarantee that the cluster nodes respond to an 'ABORT
     BACKUP' command in any particular order.

     The 'Backup BACKUP_ID started from node MANAGEMENT_NODE_ID has been
     aborted' messages mean that the backup has been terminated and that
     all files relating to this backup have been removed from the
     cluster file system.

It is also possible to abort a backup in progress from a system shell
using this command:

     shell> ndb_mgm -e "ABORT BACKUP BACKUP_ID"

*Note*:

If there is no backup having the ID BACKUP_ID running when an 'ABORT
BACKUP' is issued, the management client makes no response, nor is it
indicated in the cluster log that an invalid abort command was sent.

21.5.3.3 Configuration for NDB Cluster Backups
..............................................

Five configuration parameters are essential for backup:

   *
     'BackupDataBufferSize'

     The amount of memory used to buffer data before it is written to
     disk.

   *
     'BackupLogBufferSize'

     The amount of memory used to buffer log records before these are
     written to disk.

   *
     'BackupMemory'

     The total memory allocated in a data node for backups.  This should
     be the sum of the memory allocated for the backup data buffer and
     the backup log buffer.

   *
     'BackupWriteSize'

     The default size of blocks written to disk.  This applies for both
     the backup data buffer and the backup log buffer.

   *
     'BackupMaxWriteSize'

     The maximum size of blocks written to disk.  This applies for both
     the backup data buffer and the backup log buffer.

More detailed information about these parameters can be found in Backup
Parameters.

You can also set a location for the backup files using the
'BackupDataDir' configuration parameter.  The default is
'FileSystemPath''/BACKUP/BACKUP-BACKUP_ID'.

21.5.3.4 NDB Cluster Backup Troubleshooting
...........................................

If an error code is returned when issuing a backup request, the most
likely cause is insufficient memory or disk space.  You should check
that there is enough memory allocated for the backup.

*Important*:

If you have set 'BackupDataBufferSize' and 'BackupLogBufferSize' and
their sum is greater than 4MB, then you must also set 'BackupMemory' as
well.

You should also make sure that there is sufficient space on the hard
drive partition of the backup target.

'NDB' does not support repeatable reads, which can
cause problems with the restoration process.  Although the backup
process is 'hot', restoring an NDB Cluster from backup is not a 100%
'hot' process.  This is due to the fact that, for the duration of the
restore process, running transactions get nonrepeatable reads from the
restored data.  This means that the state of the data is inconsistent
while the restore is in progress.

21.5.4 MySQL Server Usage for NDB Cluster
-----------------------------------------

'mysqld' is the traditional MySQL server process.  To be
used with NDB Cluster, see 'mysqld' needs to be built with
support for the 'NDB' storage engine, as it is in
the precompiled binaries available from
<http://dev.mysql.com/downloads/>.  If you build MySQL from source, you
must invoke 'CMake' with the '-DWITH_NDBCLUSTER=1' option to include
support for 'NDB'.

For more information about compiling NDB Cluster from source, see
mysql-cluster-install-linux-source, and
mysql-cluster-install-windows-source.

(For information about 'mysqld' options and variables, in
addition to those discussed in this section, which are relevant to NDB
Cluster, see mysql-cluster-options-variables.)

If the 'mysqld' binary has been built with Cluster
support, the 'NDBCLUSTER' storage engine is still
disabled by default.  You can use either of two possible options to
enable this engine:

   * Use '--ndbcluster' as a startup option on the command line when
     starting 'mysqld'.

   * Insert a line containing 'ndbcluster' in the '[mysqld]' section of
     your 'my.cnf' file.

An easy way to verify that your server is running with the
'NDBCLUSTER' storage engine enabled is to issue the
'SHOW ENGINES' statement in the MySQL Monitor
(see 'mysql').  You should see the value 'YES' as the
'Support' value in the row for 'NDBCLUSTER'.  If
you see 'NO' in this row or if there is no such row displayed in the
output, you are not running an 'NDB'.-enabled
version of MySQL. If you see 'DISABLED' in this row, you need to enable
it in either one of the two ways just described.

To read cluster configuration data, the MySQL server requires at a
minimum three pieces of information:

   * The MySQL server's own cluster node ID

   * The host name or IP address for the management server (MGM node)

   * The number of the TCP/IP port on which it can connect to the
     management server

Node IDs can be allocated dynamically, so it is not strictly necessary
to specify them explicitly.

The 'mysqld' parameter 'ndb-connectstring' is used to
specify the connection string either on the command line when starting
'mysqld' or in 'my.cnf'.  The connection string contains
the host name or IP address where the management server can be found, as
well as the TCP/IP port it uses.

In the following example, 'ndb_mgmd.mysql.com' is the host where the
management server resides, and the management server listens for cluster
messages on port 1186:

     shell> mysqld --ndbcluster --ndb-connectstring=ndb_mgmd.mysql.com:1186

See mysql-cluster-connection-strings, for more information on
connection strings.

Given this information, the MySQL server will be a full participant in
the cluster.  (We often refer to a 'mysqld' process
running in this manner as an SQL node.)  It will be fully aware of all
cluster data nodes as well as their status, and will establish
connections to all data nodes.  In this case, it is able to use any data
node as a transaction coordinator and to read and update node data.

You can see in the 'mysql' client whether a MySQL server
is connected to the cluster using 'SHOW PROCESSLIST'.
If the MySQL server is connected to the cluster, and
you have the 'PROCESS' privilege, then the first row of the output is as
shown here:

     mysql> SHOW PROCESSLIST \G
     *************************** 1. row ***************************
          Id: 1
        User: system user
        Host:
          db:
     Command: Daemon
        Time: 1
       State: Waiting for event from ndbcluster
        Info: NULL

*Important*:

To participate in an NDB Cluster, the 'mysqld' process
must be started with _both_ the options '--ndbcluster' and
'--ndb-connectstring' (or their equivalents in 'my.cnf').  If
'mysqld' is started with only the '--ndbcluster' option, or if
it is unable to contact the cluster, it is not possible to work with
'NDB' tables, _nor is it possible to create any
new tables regardless of storage engine_.  The latter restriction is a
safety measure intended to prevent the creation of tables having the
same names as 'NDB' tables while the SQL node is
not connected to the cluster.  If you wish to create tables using a
different storage engine while the 'mysqld' process is
not participating in an NDB Cluster, you must restart the server
_without_ the '--ndbcluster' option.

21.5.5 Performing a Rolling Restart of an NDB Cluster
-----------------------------------------------------

This section discusses how to perform a _rolling restart_ of an NDB
Cluster installation, so called because it involves stopping and
starting (or restarting) each node in turn, so that the cluster itself
remains operational.  This is often done as part of a _rolling upgrade_
or _rolling downgrade_, where high availability of the cluster is
mandatory and no downtime of the cluster as a whole is permissible.
Where we refer to upgrades, the information provided here also generally
applies to downgrades as well.

There are a number of reasons why a rolling restart might be desirable.
These are described in the next few paragraphs.

Configuration change

To make a change in the cluster's configuration, such as adding an SQL
node to the cluster, or setting a configuration parameter to a new
value.

NDB Cluster software upgrade or downgrade

To upgrade the cluster to a newer version of the NDB Cluster software
(or to downgrade it to an older version).  This is usually referred to
as a 'rolling upgrade' (or 'rolling downgrade', when reverting to an
older version of NDB Cluster).

Change on node host

To make changes in the hardware or operating system on which one or more
NDB Cluster node processes are running.

System reset (cluster reset)

To reset the cluster because it has reached an undesirable state.  In
such cases it is often desirable to reload the data and metadata of one
or more data nodes.  This can be done in any of three ways:

   * Start each data node process (see 'ndbd'
     or possibly 'ndbmtd')
     with the '--initial' option, which
     forces the data node to clear its file system and to reload all NDB
     Cluster data and metadata from the other data nodes.

   * Create a backup using the 'ndb_mgm'
     client 'START BACKUP'
     command prior to
     performing the restart.  Following the upgrade, restore the node or
     nodes using 'ndb_restore'.

     See mysql-cluster-backup, and
     mysql-cluster-programs-ndb-restore, for more information.

   * Use 'mysqldump' to create a backup prior to the
     upgrade; afterward, restore the dump using 'LOAD DATA INFILE'.

Resource Recovery

To free memory previously allocated to a table by successive
'INSERT' and 'DELETE' operations, for re-use by
other NDB Cluster tables.

The process for performing a rolling restart may be generalized as
follows:

  1. Stop all cluster management nodes (see 'ndb_mgmd'
     processes), reconfigure them, then
     restart them.  (See
     mysql-cluster-rolling-restart-multiple-ndb-mgmd.)

  2. Stop, reconfigure, then restart each cluster data node (see
     'ndbd' process) in turn.

     Some node configuration parameters can be updated by issuing
     'RESTART' for each of the data nodes in the 'ndb_mgm'
     client following the previous step;
     others require that the data node be stopped completely using a
     shell command (such as 'kill' on most Unix systems) or
     the management client 'STOP' command, then started again from a
     system shell by invoking the 'ndbd'
     or 'ndbmtd'
     executable as appropriate.

     *Note*:

     On Windows, you can also use the system 'NET STOP' and 'NET START'
     commands or the Windows Service Manager to stop and start nodes
     which have been installed as Windows services (see
     mysql-cluster-install-windows-service).

     The type of restart required is indicated in the documentation for
     each node configuration parameter.  See
     mysql-cluster-config-file.

  3. Stop, reconfigure, then restart each cluster SQL node (see
     'mysqld' process) in turn.

NDB Cluster supports a somewhat flexible order for upgrading nodes.
When upgrading an NDB Cluster, you may upgrade API nodes (including SQL
nodes) before upgrading the management nodes, data nodes, or both.  In
other words, you are permitted to upgrade the API and SQL nodes in any
order.  This is subject to the following provisions:

   * This functionality is intended for use as part of an online upgrade
     only.  A mix of node binaries from different NDB Cluster releases
     is neither intended nor supported for continuous, long-term use in
     a production setting.

   * All management nodes must be upgraded before any data nodes are
     upgraded.  This remains true regardless of the order in which you
     upgrade the cluster's API and SQL nodes.

   * Features specific to the 'new' version must not be used until all
     management nodes and data nodes have been upgraded.

     This also applies to any MySQL Server version change that may
     apply, in addition to the NDB engine version change, so do not
     forget to take this into account when planning the upgrade.  (This
     is true for online upgrades of NDB Cluster in general.)

See also Bug #48528 and Bug #49163.

*Note*:

It is not possible for any API node to perform schema operations (such
as data definition statements) during a node restart.

Rolling restarts with multiple management servers

When performing a rolling restart of an NDB Cluster with multiple
management nodes, you should keep in mind that 'ndb_mgmd'
checks to see if any other management
node is running, and, if so, tries to use that node's configuration
data.  To keep this from occurring, and to force 'ndb_mgmd'
to reread its configuration file,
perform the following steps:

  1. Stop all NDB Cluster 'ndb_mgmd'
     processes.

  2. Update all 'config.ini' files.

  3. Start a single 'ndb_mgmd'.
     with '--reload', '--initial', or both options as desired.

  4. If you started the first 'ndb_mgmd'
     with the '--initial' option, you
     must also start any remaining 'ndb_mgmd'
     processes using '--initial'.

     Regardless of any other options used when starting the first
     'ndb_mgmd', you should not start
     any remaining 'ndb_mgmd'.
     processes after the first one using '--reload'.

  5. Complete the rolling restarts of the data nodes and API nodes as
     normal.

When performing a rolling restart to update the cluster's configuration,
you can use the 'config_generation' column of the 'ndbinfo.nodes'
table to keep track of which data nodes
have been successfully restarted with the new configuration.  See
mysql-cluster-ndbinfo-nodes.

21.5.6 Event Reports Generated in NDB Cluster
---------------------------------------------

In this section, we discuss the types of event logs provided by NDB
Cluster, and the types of events that are logged.

NDB Cluster provides two types of event log:

   * The _cluster log_, which includes events generated by all cluster
     nodes.  The cluster log is the log recommended for most uses
     because it provides logging information for an entire cluster in a
     single location.

     By default, the cluster log is saved to a file named
     'ndb_NODE_ID_cluster.log', (where NODE_ID is the node ID of the
     management server) in the management server's 'DataDir'.

     Cluster logging information can also be sent to 'stdout' or a
     'syslog' facility in addition to or instead of being saved to a
     file, as determined by the values set for the 'DataDir' and
     'LogDestination' configuration parameters.  See
     mysql-cluster-mgm-definition, for more information about these
     parameters.

   * _Node logs_ are local to each node.

     Output generated by node event logging is written to the file
     'ndb_NODE_ID_out.log' (where NODE_ID is the node's node ID) in the
     node's 'DataDir'.  Node event logs are generated for both
     management nodes and data nodes.

     Node logs are intended to be used only during application
     development, or for debugging application code.

Both types of event logs can be set to log different subsets of events.

Each reportable event can be distinguished according to three different
criteria:

   * _Category_: This can be any one of the following values: 'STARTUP',
     'SHUTDOWN', 'STATISTICS', 'CHECKPOINT', 'NODERESTART',
     'CONNECTION', 'ERROR', or 'INFO'.

   * _Priority_: This is represented by one of the numbers from 0 to 15
     inclusive, where 0 indicates 'most important' and 15 'least
     important.'

   * _Severity Level_: This can be any one of the following values:
     'ALERT', 'CRITICAL', 'ERROR', 'WARNING', 'INFO', or 'DEBUG'.

Both the cluster log and the node log can be filtered on these
properties.

The format used in the cluster log is as shown here:

     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 1: Data usage is 2%(60 32K pages of total 2560)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 1: Index usage is 1%(24 8K pages of total 2336)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 1: Resource 0 min: 0 max: 639 curr: 0
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 2: Data usage is 2%(76 32K pages of total 2560)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 2: Index usage is 1%(24 8K pages of total 2336)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 2: Resource 0 min: 0 max: 639 curr: 0
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 3: Data usage is 2%(58 32K pages of total 2560)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 3: Index usage is 1%(25 8K pages of total 2336)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 3: Resource 0 min: 0 max: 639 curr: 0
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 4: Data usage is 2%(74 32K pages of total 2560)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 4: Index usage is 1%(25 8K pages of total 2336)
     2007-01-26 19:35:55 [MgmSrvr] INFO     -- Node 4: Resource 0 min: 0 max: 639 curr: 0
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 4: Node 9 Connected
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 1: Node 9 Connected
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 1: Node 9: API 5.7.22-ndb-7.5.11
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 2: Node 9 Connected
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 2: Node 9: API 5.7.22-ndb-7.5.11
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 3: Node 9 Connected
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 3: Node 9: API 5.7.22-ndb-7.5.11
     2007-01-26 19:39:42 [MgmSrvr] INFO     -- Node 4: Node 9: API 5.7.22-ndb-7.5.11
     2007-01-26 19:59:22 [MgmSrvr] ALERT    -- Node 2: Node 7 Disconnected
     2007-01-26 19:59:22 [MgmSrvr] ALERT    -- Node 2: Node 7 Disconnected

Each line in the cluster log contains the following information:

   * A timestamp in 'YYYY-MM-DD HH:MM:SS' format.

   * The type of node which is performing the logging.  In the cluster
     log, this is always '[MgmSrvr]'.

   * The severity of the event.

   * The ID of the node reporting the event.

   * A description of the event.  The most common types of events to
     appear in the log are connections and disconnections between
     different nodes in the cluster, and when checkpoints occur.  In
     some cases, the description may contain status information.

21.5.6.1 NDB Cluster Logging Management Commands
................................................

'ndb_mgm' supports a number of
management commands related to the cluster log and node logs.  In the
listing that follows, NODE_ID denotes either a storage node ID or the
keyword 'ALL', which indicates that the command should be applied to all
of the cluster's data nodes.

   * 'CLUSTERLOG ON'

     Turns the cluster log on.

   * 'CLUSTERLOG OFF'

     Turns the cluster log off.

   * 'CLUSTERLOG INFO'

     Provides information about cluster log settings.

   * 'NODE_ID CLUSTERLOG CATEGORY=THRESHOLD'

     Logs CATEGORY events with priority less than or equal to THRESHOLD
     in the cluster log.

   * 'CLUSTERLOG FILTER SEVERITY_LEVEL'

     Toggles cluster logging of events of the specified SEVERITY_LEVEL.

The following table describes the default setting (for all data nodes)
of the cluster log category threshold.  If an event has a priority with
a value lower than or equal to the priority threshold, it is reported in
the cluster log.

*Note*:

Events are reported per data node, and that the threshold can be set to
different values on different nodes.

*Cluster log categories, with default threshold setting*

Category               Default threshold (All data nodes)

'STARTUP'              *7*

'SHUTDOWN'             *7*

'STATISTICS'           *7*

'CHECKPOINT'           *7*

'NODERESTART'          *7*

'CONNECTION'           *7*

'ERROR'                *15*

'INFO'                 *7*

The 'STATISTICS' category can provide a great deal of useful data.  See
mysql-cluster-log-statistics, for more information.

Thresholds are used to filter events within each category.  For example,
a 'STARTUP' event with a priority of 3 is not logged unless the
threshold for 'STARTUP' is set to 3 or higher.  Only events with
priority 3 or lower are sent if the threshold is 3.

The following table shows the event severity levels.

*Note*:

These correspond to Unix 'syslog' levels, except for 'LOG_EMERG' and
'LOG_NOTICE', which are not used or mapped.

*Event severity levels*

Severity       Severity       Description
Level Value

*1*            'ALERT'        A condition that should be corrected
                              immediately, such as a corrupted system
                              database

*2*            'CRITICAL'     Critical conditions, such as device
                              errors or insufficient resources

*3*            'ERROR'        Conditions that should be corrected, such
                              as configuration errors

*4*            'WARNING'      Conditions that are not errors, but that
                              might require special handling

*5*            'INFO'         Informational messages

*6*            'DEBUG'        Debugging messages used for
                              'NDBCLUSTER' development

Event severity levels can be turned on or off (using 'CLUSTERLOG
FILTER'--see above).  If a severity level is turned on, then all events
with a priority less than or equal to the category thresholds are
logged.  If the severity level is turned off then no events belonging to
that severity level are logged.

*Important*:

Cluster log levels are set on a per 'ndb_mgmd',
per subscriber basis.  This means that,
in an NDB Cluster with multiple management servers, using a 'CLUSTERLOG'
command in an instance of 'ndb_mgm'
connected to one management server
affects only logs generated by that management server but not by any of
the others.  This also means that, should one of the management servers
be restarted, only logs generated by that management server are affected
by the resetting of log levels caused by the restart.

21.5.6.2 NDB Cluster Log Events
...............................

An event report reported in the event logs has the following format:

     DATETIME [STRING] SEVERITY -- MESSAGE

For example:

     09:19:30 2005-07-24 [NDB] INFO -- Node 4 Start phase 4 completed

This section discusses all reportable events, ordered by category and
severity level within each category.

In the event descriptions, GCP and LCP mean 'Global Checkpoint' and
'Local Checkpoint', respectively.

*CONNECTION Events*

These events are associated with connections between Cluster nodes.

*Events associated with connections between cluster nodes*

Event                     PrioritySeverityDescription
                                  Level

'Connected'               8       'INFO'  Data nodes connected

'Disconnected'            8       'ALERT' Data nodes disconnected

'CommunicationClosed'     8       'INFO'  SQL node or data node
                                          connection closed

'CommunicationOpened'     8       'INFO'  SQL node or data node
                                          connection open

'ConnectedApiVersion'     8       'INFO'  Connection using API version

*CHECKPOINT Events*

The logging messages shown here are associated with checkpoints.

*Events associated with checkpoints*

Event                     PrioritySeverityDescription
                                  Level

'GlobalCheckpointStarted' 9       'INFO'  Start of GCP: REDO log is
                                          written to disk

'GlobalCheckpointCompleted'10     'INFO'  GCP finished

'LocalCheckpointStarted'  7       'INFO'  Start of LCP: data written to
                                          disk

'LocalCheckpointCompleted'7       'INFO'  LCP completed normally

'LCPStoppedInCalcKeepGci' 0       'ALERT' LCP stopped

'LCPFragmentCompleted'    11      'INFO'  LCP on a fragment has been
                                          completed

'UndoLogBlocked'          7       'INFO'  UNDO logging blocked; buffer
                                          near overflow

'RedoStatus'              7       'INFO'  Redo status

*STARTUP Events*

The following events are generated in response to the startup of a node
or of the cluster and of its success or failure.  They also provide
information relating to the progress of the startup process, including
information concerning logging activities.

*Events relating to the startup of a node or cluster*

Event                     PrioritySeverityDescription
                                  Level

'NDBStartStarted'         1       'INFO'  Data node start phases
                                          initiated (all nodes starting)

'NDBStartCompleted'       1       'INFO'  Start phases completed, all
                                          data nodes

'STTORRYRecieved'         15      'INFO'  Blocks received after
                                          completion of restart

'StartPhaseCompleted'     4       'INFO'  Data node start phase X
                                          completed

'CM_REGCONF'              3       'INFO'  Node has been successfully
                                          included into the cluster;
                                          shows the node, managing node,
                                          and dynamic ID

'CM_REGREF'               8       'INFO'  Node has been refused for
                                          inclusion in the cluster;
                                          cannot be included in cluster
                                          due to misconfiguration,
                                          inability to establish
                                          communication, or other
                                          problem

'FIND_NEIGHBOURS'         8       'INFO'  Shows neighboring data nodes

'NDBStopStarted'          1       'INFO'  Data node shutdown initiated

'NDBStopCompleted'        1       'INFO'  Data node shutdown complete

'NDBStopForced'           1       'ALERT' Forced shutdown of data node

'NDBStopAborted'          1       'INFO'  Unable to shut down data node
                                          normally

'StartREDOLog'            4       'INFO'  New redo log started; GCI keep
                                          X, newest restorable GCI Y

'StartLog'                10      'INFO'  New log started; log part X,
                                          start MB Y, stop MB Z

'UNDORecordsExecuted'     15      'INFO'  Undo records executed

'StartReport'             4       'INFO'  Report started

'LogFileInitStatus'       7       'INFO'  Log file initialization status

'LogFileInitCompStatus'   7       'INFO'  Log file completion status

'StartReadLCP'            10      'INFO'  Start read for local
                                          checkpoint

'ReadLCPComplete'         10      'INFO'  Read for local checkpoint
                                          completed

'RunRedo'                 8       'INFO'  Running the redo log

'RebuildIndex'            10      'INFO'  Rebuilding indexes

*NODERESTART Events*

The following events are generated when restarting a node and relate to
the success or failure of the node restart process.

*Events relating to restarting a node*

Event                     PrioritySeverityDescription
                                  Level

'NR_CopyDict'             7       'INFO'  Completed copying of
                                          dictionary information

'NR_CopyDistr'            7       'INFO'  Completed copying distribution
                                          information

'NR_CopyFragsStarted'     7       'INFO'  Starting to copy fragments

'NR_CopyFragDone'         10      'INFO'  Completed copying a fragment

'NR_CopyFragsCompleted'   7       'INFO'  Completed copying all
                                          fragments

'NodeFailCompleted'       8       'ALERT' Node failure phase completed

'NODE_FAILREP'            8       'ALERT' Reports that a node has failed

'ArbitState'              6       'INFO'  Report whether an arbitrator
                                          is found or not; there are
                                          seven different possible
                                          outcomes when seeking an
                                          arbitrator, listed here:

                                             * Management server
                                               restarts arbitration
                                               thread [state=X]

                                             * Prepare arbitrator node X
                                               [ticket=Y]

                                             * Receive arbitrator node X
                                               [ticket=Y]

                                             * Started arbitrator node X
                                               [ticket=Y]

                                             * Lost arbitrator node X -
                                               process failure [state=Y]

                                             * Lost arbitrator node X -
                                               process exit [state=Y]

                                             * Lost arbitrator node X
                                               <error msg> [state=Y]

'ArbitResult'             2       'ALERT' Report arbitrator results;
                                          there are eight different
                                          possible results for
                                          arbitration attempts, listed
                                          here:

                                             * Arbitration check failed:
                                               less than 1/2 nodes left

                                             * Arbitration check
                                               succeeded: node group
                                               majority

                                             * Arbitration check failed:
                                               missing node group

                                             * Network partitioning:
                                               arbitration required

                                             * Arbitration succeeded:
                                               affirmative response from
                                               node X

                                             * Arbitration failed:
                                               negative response from
                                               node X

                                             * Network partitioning: no
                                               arbitrator available

                                             * Network partitioning: no
                                               arbitrator configured

'GCP_TakeoverStarted'     7       'INFO'  GCP takeover started

'GCP_TakeoverCompleted'   7       'INFO'  GCP takeover complete

'LCP_TakeoverStarted'     7       'INFO'  LCP takeover started

'LCP_TakeoverCompleted'   7       'INFO'  LCP takeover complete (state =
                                          X)

'ConnectCheckStarted'     6       'INFO'  Connection check started

'ConnectCheckCompleted'   6       'INFO'  Connection check completed

'NodeFailRejected'        6       'ALERT' Node failure phase failed

*STATISTICS Events*

The following events are of a statistical nature.  They provide
information such as numbers of transactions and other operations, amount
of data sent or received by individual nodes, and memory usage.

*Events of a statistical nature*

Event                     PrioritySeverityDescription
                                  Level

'TransReportCounters'     8       'INFO'  Report transaction statistics,
                                          including numbers of
                                          transactions, commits, reads,
                                          simple reads, writes,
                                          concurrent operations,
                                          attribute information, and
                                          aborts

'OperationReportCounters' 8       'INFO'  Number of operations

'TableCreated'            7       'INFO'  Report number of tables
                                          created

'JobStatistic'            9       'INFO'  Mean internal job scheduling
                                          statistics

'ThreadConfigLoop'        9       'INFO'  Number of thread configuration
                                          loops

'SendBytesStatistic'      9       'INFO'  Mean number of bytes sent to
                                          node X

'ReceiveBytesStatistic'   9       'INFO'  Mean number of bytes received
                                          from node X

'MemoryUsage'             5       'INFO'  Data and index memory usage
                                          (80%, 90%, and 100%)

'MTSignalStatistics'      9       'INFO'  Multi-threaded signals

*SCHEMA Events*

These events relate to NDB Cluster schema operations.

*Events relating to NDB Cluster schema operations*

Event                     PrioritySeverityDescription
                                  Level

'CreateSchemaObject'      8       'INFO'  Schema objected created

'AlterSchemaObject'       8       'INFO'  Schema object updated

'DropSchemaObject'        8       'INFO'  Schema object dropped

*ERROR Events*

These events relate to Cluster errors and warnings.  The presence of one
or more of these generally indicates that a major malfunction or failure
has occurred.

*Events relating to cluster errors and warnings*

Event                     PrioritySeverityDescription
                                  Level

'TransporterError'        2       'ERROR' Transporter error

'TransporterWarning'      8       'WARNING'Transporter warning

'MissedHeartbeat'         8       'WARNING'Node X missed heartbeat number
                                          Y

'DeadDueToHeartbeat'      8       'ALERT' Node X declared 'dead' due to
                                          missed heartbeat

'WarningEvent'            2       'WARNING'General warning event

'SubscriptionStatus'      4       'WARNING'Change in subscription status

*INFO Events*

These events provide general information about the state of the cluster
and activities associated with Cluster maintenance, such as logging and
heartbeat transmission.

*Information events*

Event                     PrioritySeverityDescription
                                  Level

'SentHeartbeat'           12      'INFO'  Sent heartbeat

'CreateLogBytes'          11      'INFO'  Create log: Log part, log
                                          file, size in MB

'InfoEvent'               2       'INFO'  General informational event

'EventBufferStatus'       7       'INFO'  Event buffer status

'EventBufferStatus2'      7       'INFO'  Improved event buffer status
                                          information; added in NDB
                                          7.5.1

*Note*:

'SentHeartbeat' events are available only if NDB Cluster was compiled
with 'VM_TRACE' enabled.

*SINGLEUSER Events*

These events are associated with entering and exiting single user mode.

*Events relating to single user mode*

Event                     PrioritySeverityDescription
                                  Level

'SingleUser'              7       'INFO'  Entering or exiting single
                                          user mode

*BACKUP Events*

These events provide information about backups being created or
restored.

*Backup events*

Event                     PrioritySeverityDescription
                                  Level

'BackupStarted'           7       'INFO'  Backup started

'BackupStatus'            7       'INFO'  Backup status

'BackupCompleted'         7       'INFO'  Backup completed

'BackupFailedToStart'     7       'ALERT' Backup failed to start

'BackupAborted'           7       'ALERT' Backup aborted by user

'RestoreStarted'          7       'INFO'  Started restoring from backup

'RestoreMetaData'         7       'INFO'  Restoring metadata

'RestoreData'             7       'INFO'  Restoring data

'RestoreLog'              7       'INFO'  Restoring log files

'RestoreCompleted'        7       'INFO'  Completed restoring from
                                          backup

'SavedEvent'              7       'INFO'  Event saved

21.5.6.3 Using CLUSTERLOG STATISTICS in the NDB Cluster Management Client
.........................................................................

The 'NDB' management client's 'CLUSTERLOG STATISTICS'
command can
provide a number of useful statistics in its output.  Counters providing
information about the state of the cluster are updated at 5-second
reporting intervals by the transaction coordinator (TC) and the local
query handler (LQH), and written to the cluster log.

Transaction coordinator statistics

Each transaction has one transaction coordinator, which is chosen by one
of the following methods:

   * In a round-robin fashion

   * By communication proximity

   * By supplying a data placement hint when the transaction is started

*Note*:

You can determine which TC selection method is used for transactions
started from a given SQL node using the 'ndb_optimized_node_selection'
system variable.

All operations within the same transaction use the same transaction
coordinator, which reports the following statistics:

   * Trans count

     This is the number transactions started in the last interval using
     this TC as the transaction coordinator.  Any of these transactions
     may have committed, have been aborted, or remain uncommitted at the
     end of the reporting interval.

     *Note*:

     Transactions do not migrate between TCs.

   * Commit count

     This is the number of transactions using this TC as the transaction
     coordinator that were committed in the last reporting interval.
     Because some transactions committed in this reporting interval may
     have started in a previous reporting interval, it is possible for
     'Commit count' to be greater than 'Trans count'.

   * Read count

     This is the number of primary key read operations using this TC as
     the transaction coordinator that were started in the last reporting
     interval, including simple reads.  This count also includes reads
     performed as part of unique index operations.  A unique index read
     operation generates 2 primary key read operations--1 for the hidden
     unique index table, and 1 for the table on which the read takes
     place.

   * Simple read count

     This is the number of simple read operations using this TC as the
     transaction coordinator that were started in the last reporting
     interval.

   * Write count

     This is the number of primary key write operations using this TC as
     the transaction coordinator that were started in the last reporting
     interval.  This includes all inserts, updates, writes and deletes,
     as well as writes performed as part of unique index operations.

     *Note*:

     A unique index update operation can generate multiple PK read and
     write operations on the index table and on the base table.

   * AttrInfoCount

     This is the number of 32-bit data words received in the last
     reporting interval for primary key operations using this TC as the
     transaction coordinator.  For reads, this is proportional to the
     number of columns requested.  For inserts and updates, this is
     proportional to the number of columns written, and the size of
     their data.  For delete operations, this is usually zero.

     Unique index operations generate multiple PK operations and so
     increase this count.  However, data words sent to describe the PK
     operation itself, and the key information sent, are _not_ counted
     here.  Attribute information sent to describe columns to read for
     scans, or to describe ScanFilters, is also not counted in
     'AttrInfoCount'.

   * Concurrent Operations

     This is the number of primary key or scan operations using this TC
     as the transaction coordinator that were started during the last
     reporting interval but that were not completed.  Operations
     increment this counter when they are started and decrement it when
     they are completed; this occurs after the transaction commits.
     Dirty reads and writes--as well as failed operations--decrement
     this counter.

     The maximum value that 'Concurrent Operations' can have is the
     maximum number of operations that a TC block can support;
     currently, this is '(2 * MaxNoOfConcurrentOperations) + 16 +
     MaxNoOfConcurrentTransactions'.  (For more information about these
     configuration parameters, see the 'Transaction Parameters' section
     of mysql-cluster-ndbd-definition.)

   * Abort count

     This is the number of transactions using this TC as the transaction
     coordinator that were aborted during the last reporting interval.
     Because some transactions that were aborted in the last reporting
     interval may have started in a previous reporting interval, 'Abort
     count' can sometimes be greater than 'Trans count'.

   * Scans

     This is the number of table scans using this TC as the transaction
     coordinator that were started during the last reporting interval.
     This does not include range scans (that is, ordered index scans).

   * Range scans

     This is the number of ordered index scans using this TC as the
     transaction coordinator that were started in the last reporting
     interval.

   * Local reads

     This is the number of primary-key read operations performed using a
     transaction coordinator on a node that also holds the primary
     replica of the record.  This count can also be obtained from the
     'LOCAL_READS' counter in the 'ndbinfo.counters'
     table.

   * Local writes

     This contains the number of primary-key read operations that were
     performed using a transaction coordinator on a node that also holds
     the primary replica of the record.  This count can also be obtained
     from the 'LOCAL_WRITES' counter in the 'ndbinfo.counters'
     table.

Local query handler statistics (Operations)

There is 1 cluster event per local query handler block (that is, 1 per
data node process).  Operations are recorded in the LQH where the data
they are operating on resides.

*Note*:

A single transaction may operate on data stored in multiple LQH blocks.

The 'Operations' statistic provides the number of local operations
performed by this LQH block in the last reporting interval, and includes
all types of read and write operations (insert, update, write, and
delete operations).  This also includes operations used to replicate
writes.  For example, in a 2-replica cluster, the write to the primary
replica is recorded in the primary LQH, and the write to the backup will
be recorded in the backup LQH. Unique key operations may result in
multiple local operations; however, this does _not_ include local
operations generated as a result of a table scan or ordered index scan,
which are not counted.

Process scheduler statistics

In addition to the statistics reported by the transaction coordinator
and local query handler, each 'ndbd'.
process has a scheduler which also provides useful metrics relating to
the performance of an NDB Cluster.  This scheduler runs in an infinite
loop; during each loop the scheduler performs the following tasks:

  1. Read any incoming messages from sockets into a job buffer.

  2. Check whether there are any timed messages to be executed; if so,
     put these into the job buffer as well.

  3. Execute (in a loop) any messages in the job buffer.

  4. Send any distributed messages that were generated by executing the
     messages in the job buffer.

  5. Wait for any new incoming messages.

Process scheduler statistics include the following:

   * Mean Loop Counter

     This is the number of loops executed in the third step from the
     preceding list.  This statistic increases in size as the
     utilization of the TCP/IP buffer improves.  You can use this to
     monitor changes in performance as you add new data node processes.

   * Mean send size and Mean receive size

     These statistics enable you to gauge the efficiency of,
     respectively writes and reads between nodes.  The values are given
     in bytes.  Higher values mean a lower cost per byte sent or
     received; the maximum value is 64K.

To cause all cluster log statistics to be logged, you can use the
following command in the 'NDB' management client:

     ndb_mgm> ALL CLUSTERLOG STATISTICS=15

*Note*:

Setting the threshold for 'STATISTICS' to 15 causes the cluster log to
become very verbose, and to grow quite rapidly in size, in direct
proportion to the number of cluster nodes and the amount of activity in
the NDB Cluster.

For more information about NDB Cluster management client commands
relating to logging and reporting, see
mysql-cluster-logging-management-commands.

21.5.7 NDB Cluster Log Messages
-------------------------------

This section contains information about the messages written to the
cluster log in response to different cluster log events.  It provides
additional, more specific information on 'NDB'.
transporter errors.

21.5.7.1 NDB Cluster: Messages in the Cluster Log
.................................................

The following table lists the most common 'NDB'.
cluster log messages.  For information about the cluster log, log
events, and event types, see mysql-cluster-event-reports.  These
log messages also correspond to log event types in the MGM API; see The
Ndb_logevent_type Type
(http://dev.mysql.com/doc/ndbapi/en/mgm-ndb-logevent-type.html), for
related information of interest to Cluster API developers.

*Common NDB cluster log messages*

Log Message    Description    Event Name         Event       PrioritySeverity
                                                 Type

'Node          The data       'Connected'        'Connection'8       'INFO'
MGM_NODE_ID:   node having
Node           node ID
DATA_NODE_ID   NODE_ID has
Connected'     connected to
               the
               management
               server (node
               MGM_NODE_ID).

'Node          The data       'Disconnected'     'Connection'8       'ALERT'
MGM_NODE_ID:   node having
Node           node ID
DATA_NODE_ID   DATA_NODE_ID
Disconnected'  has
               disconnected
               from the
               management
               server (node
               MGM_NODE_ID).

'Node          The API node   'CommunicationClosed''Connection'8     'INFO'
DATA_NODE_ID:  or SQL node
Communication  having node
to Node        ID
API_NODE_ID    API_NODE_ID
closed'        is no longer
               communicating
               with data
               node
               DATA_NODE_ID.

'Node          The API node   'CommunicationOpened''Connection'8     'INFO'
DATA_NODE_ID:  or SQL node
Communication  having node
to Node        ID
API_NODE_ID    API_NODE_ID
opened'        is now
               communicating
               with data
               node
               DATA_NODE_ID.

'Node          The API node   'ConnectedApiVersion''Connection'8     'INFO'
MGM_NODE_ID:   having node
Node           ID
API_NODE_ID:   API_NODE_ID
API VERSION'   has
               connected to
               management
               node
               MGM_NODE_ID
               using
               'NDB'.
               API version
               VERSION
               (generally
               the same as
               the MySQL
               version
               number).

'Node          A global       'GlobalCheckpointStarted''Checkpoint'9 'INFO'
NODE_ID:       checkpoint
Global         with the ID
checkpoint     GCI has been
GCI started'   started;
               node NODE_ID
               is the
               master
               responsible
               for this
               global
               checkpoint.

'Node          The global     'GlobalCheckpointCompleted''Checkpoint'10'INFO'
NODE_ID:       checkpoint
Global         having the
checkpoint     ID GCI has
GCI            been
completed'     completed;
               node NODE_ID
               was the
               master
               responsible
               for this
               global
               checkpoint.

'Node          The local      'LocalCheckpointStarted''Checkpoint'7  'INFO'
NODE_ID:       checkpoint
Local          having
checkpoint     sequence ID
LCP started.   LCP has been
Keep GCI =     started on
CURRENT_GCI    node
oldest         NODE_ID.
restorable     The most
GCI =          recent GCI
OLD_GCI'       that can be
               used has the
               index
               CURRENT_GCI,
               and the
               oldest GCI
               from which
               the cluster
               can be
               restored has
               the index
               OLD_GCI.

'Node          The local      'LocalCheckpointCompleted''Checkpoint'8'INFO'
NODE_ID:       checkpoint
Local          having
checkpoint     sequence ID
LCP            LCP on node
completed'     NODE_ID has
               been
               completed.

'Node          The node was   'LCPStoppedInCalcKeepGci''Checkpoint'0 'ALERT'
NODE_ID:       unable to
Local          determine
Checkpoint     the most
stopped in     recent
CALCULATED_KEEP_GCI'usable GCI.

'Node          A table        'LCPFragmentCompleted''Checkpoint'11   'INFO'
NODE_ID:       fragment has
Table ID =     been
TABLE_ID,      checkpointed
fragment ID    to disk on
=              node
FRAGMENT_ID    NODE_ID.
has            The GCI in
completed      progress has
LCP on Node    the index
NODE_ID        STARTED_GCI,
maxGciStarted: and the most
STARTED_GCI    recent GCI
maxGciCompleted:to have been
COMPLETED_GCI' completed
               has the
               index
               COMPLETED_GCI.

'Node          Undo logging   'UndoLogBlocked'   'Checkpoint'7       'INFO'
NODE_ID: ACC   is blocked
Blocked        because the
NUM_1 and      log buffer
TUP Blocked    is close to
NUM_2 times    overflowing.
last second'

'Node          Data node      'NDBStartStarted'  'StartUp'   1       'INFO'
NODE_ID:       NODE_ID,
Start          running
initiated      'NDB'.
               version
               VERSION, is
               beginning
               its startup
               process.

'Node          Data node      'NDBStartCompleted''StartUp'   1       'INFO'
NODE_ID:       NODE_ID,
Started        running
VERSION'       'NDB'.
               version
               VERSION, has
               started
               successfully.

'Node          The node has   'STTORRYRecieved'  'StartUp'   15      'INFO'
NODE_ID:       received a
STTORRY        signal
received       indicating
after          that a
restart        cluster
finished'      restart has
               completed.

'Node          The node has   'StartPhaseCompleted''StartUp' 4       'INFO'
NODE_ID:       completed
Start phase    start phase
PHASE          PHASE of a
completed      TYPE start.
(TYPE)'        For a
               listing of
               start
               phases, see

               mysql-cluster-start-phases.
               (TYPE is one
               of
               'initial',
               'system',
               'node',
               'initial
               node', or
               '<Unknown>'.)

'Node          Node           'CM_REGCONF'       'StartUp'   3       'INFO'
NODE_ID:       PRESIDENT_ID
CM_REGCONF     has been
president =    selected as
PRESIDENT_ID,  'president'.
own Node =     OWN_ID and
OWN_ID, our    DYNAMIC_ID
dynamic id =   should
DYNAMIC_ID'    always be
               the same as
               the ID
               (NODE_ID) of
               the
               reporting
               node.

'Node          The            'CM_REGREF'        'StartUp'   8       'INFO'
NODE_ID:       reporting
CM_REGREF      node (ID
from Node      NODE_ID) was
PRESIDENT_ID   unable to
to our Node    accept node
NODE_ID.       PRESIDENT_ID
Cause =        as
CAUSE'         president.
               The CAUSE of
               the problem
               is given as
               one of
               'Busy',
               'Election
               with wait =
               false', 'Not
               president',
               'Election
               without
               selecting
               new
               candidate',
               or 'No such
               cause'.

'Node          The node has   'FIND_NEIGHBOURS'  'StartUp'   8       'INFO'
NODE_ID: We    discovered
are Node       its
OWN_ID with    neighboring
dynamic ID     nodes in the
DYNAMIC_ID,    cluster
our left       (node ID_1
neighbor is    and node
Node ID_1,     ID_2).
our right is   NODE_ID,
Node ID_2'     OWN_ID, and
               DYNAMIC_ID
               should
               always be
               the same; if
               they are
               not, this
               indicates a
               serious
               misconfiguration
               of the
               cluster
               nodes.

'Node          The node has   'NDBStopStarted'   'StartUp'   1       'INFO'
NODE_ID:       received a
TYPE           shutdown
shutdown       signal.  The
initiated'     TYPE of
               shutdown is
               either
               'Cluster' or
               'Node'.

'Node          The node has   'NDBStopCompleted' 'StartUp'   1       'INFO'
NODE_ID:       been shut
Node           down.  This
shutdown       report may
completed      include an
'[',           ACTION,
ACTION']       which if
['Initiated    present is
by signal      one of
SIGNAL.']      'restarting',
               'no start',
               or
               'initial'.
               The report
               may also
               include a
               reference to
               an
               'NDB'.
               Protocol
               SIGNAL; for
               possible
               signals,
               refer to
               Operations
               and Signals
               (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndb-protocol-operations-signals.html).

'Node          The node has   'NDBStopForced'    'StartUp'   1       'ALERT'
NODE_ID:       been
Forced node    forcibly
shutdown       shut down.
completed      The ACTION
'[',           (one of
action']'.'    'restarting',
['Occurred     'no start',
during         or
startphase     'initial')
START_PHASE.'] subsequently
[' Initiated   being taken,
by SIGNAL.']   if any, is
['Caused by    also
error          reported.
ERROR_CODE:    If the
'ERROR_MESSAGE(ERROR_CLASSIFICATION).shutdown
ERROR_STATUS'.'occurred
['(extra       while the
info           node was
EXTRA_CODE)']] starting,
               the report
               includes the
               START_PHASE
               during which
               the node
               failed.  If
               this was a
               result of a
               SIGNAL sent
               to the node,
               this
               information
               is also
               provided
               (see
               Operations
               and Signals
               (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndb-protocol-operations-signals.html),
               for more
               information).
               If the error
               causing the
               failure is
               known, this
               is also
               included;
               for more
               information
               about
               'NDB'.
               error
               messages and
               classifications,
               see NDB
               Cluster API
               Errors
               (http://dev.mysql.com/doc/ndb-internals/en/ndb-errors.html).

'Node          The node       'NDBStopAborted'   'StartUp'   1       'INFO'
NODE_ID:       shutdown
Node           process was
shutdown       aborted by
aborted'       the user.

'Node          This reports   'StartREDOLog'     'StartUp'   4       'INFO'
NODE_ID:       global
StartLog:      checkpoints
[GCI Keep:     referenced
KEEP_POS       during a
LastCompleted: node start.
LAST_POS       The redo log
NewestRestorable:prior to
RESTORE_POS]'  KEEP_POS is
               dropped.
               LAST_POS is
               the last
               global
               checkpoint
               in which
               data node
               the
               participated;
               RESTORE_POS
               is the
               global
               checkpoint
               which is
               actually
               used to
               restore all
               data nodes.

STARTUP_MESSAGEThere are a    'StartReport'      'StartUp'   4       'INFO'
[_Listed       number of
separately;    possible
see below._]   startup
               messages
               that can be
               logged under
               different
               circumstances.
               These are
               listed
               separately;
               see
               mysql-cluster-log-startup-messages.

'Node          Copying of     'NR_CopyDict'      'NodeRestart'8      'INFO'
NODE_ID:       data
Node restart   dictionary
completed      information
copy of        to the
dictionary     restarted
information'   node has
               been
               completed.

'Node          Copying of     'NR_CopyDistr'     'NodeRestart'8      'INFO'
NODE_ID:       data
Node restart   distribution
completed      information
copy of        to the
distribution   restarted
information'   node has
               been
               completed.

'Node          Copy of        'NR_CopyFragsStarted''NodeRestart'8    'INFO'
NODE_ID:       fragments to
Node restart   starting
starting to    data node
copy the       NODE_ID has
fragments to   begun
Node
NODE_ID'

'Node          Fragment       'NR_CopyFragDone'  'NodeRestart'10     'INFO'
NODE_ID:       FRAGMENT_ID
Table ID =     from table
TABLE_ID,      TABLE_ID has
fragment ID    been copied
=              to data node
FRAGMENT_ID    NODE_ID
have been
copied to
Node
NODE_ID'

'Node          Copying of     'NR_CopyFragsCompleted''NodeRestart'8  'INFO'
NODE_ID:       all table
Node restart   fragments to
completed      restarting
copying the    data node
fragments to   NODE_ID has
Node           been
NODE_ID'       completed

'Node          Data node      'NodeFailCompleted''NodeRestart'8      'ALERT'
NODE_ID:       NODE1_ID has
Node           detected the
NODE1_ID       failure of
completed      data node
failure of     NODE2_ID
Node
NODE2_ID'

'All nodes     All            'NodeFailCompleted''NodeRestart'8      'ALERT'
completed      (remaining)
failure of     data nodes
Node           have
NODE_ID'       detected the
               failure of
               data node
               NODE_ID

'Node          The failure    'NodeFailCompleted''NodeRestart'8      'ALERT'
failure of     of data node
NODE_IDBLOCK   NODE_ID has
completed'     been
               detected in
               the
               BLOCK
               'NDB'.
               kernel
               block, where
               block is 1
               of 'DBTC',
               'DBDICT',
               'DBDIH', or
               'DBLQH'; for
               more
               information,
               see NDB
               Kernel
               Blocks
               (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks.html)

'Node          A data node    'NODE_FAILREP'     'NodeRestart'8      'ALERT'
MGM_NODE_ID:   has failed.
Node           Its state at
DATA_NODE_ID   the time of
has failed.    failure is
The Node       described by
state at       an
failure was    arbitration
STATE_CODE'    state code
               STATE_CODE:
               possible
               state code
               values can
               be found in
               the file
               'include/kernel/signaldata/ArbitSignalData.hpp'.

'President     This is a      'ArbitState'       'NodeRestart'6      'INFO'
restarts       report on
arbitration    the current
thread         state and
[state=STATE_CODE]'progress of
or 'Prepare    arbitration
arbitrator     in the
node NODE_ID   cluster.
[ticket=TICKET_ID]'NODE_ID is
or 'Receive    the node ID
arbitrator     of the
node NODE_ID   management
[ticket=TICKET_ID]'node or SQL
or 'Started    node
arbitrator     selected as
node NODE_ID   the
[ticket=TICKET_ID]'arbitrator.
or 'Lost       STATE_CODE
arbitrator     is an
node NODE_ID   arbitration
- process      state code,
failure        as found in
[state=STATE_CODE]''include/kernel/signaldata/ArbitSignalData.hpp'.
or 'Lost       When an
arbitrator     error has
node NODE_ID   occurred, an
- process      ERROR_MESSAGE,
exit           also defined
[state=STATE_CODE]'in
or 'Lost       'ArbitSignalData.hpp',
arbitrator     is provided.
node NODE_ID   TICKET_ID is
-              a unique
ERROR_MESSAGE  identifier
[state=STATE_CODE]'handed out
               by the
               arbitrator
               when it is
               selected to
               all the
               nodes that
               participated
               in its
               selection;
               this is used
               to ensure
               that each
               node
               requesting
               arbitration
               was one of
               the nodes
               that took
               part in the
               selection
               process.

'Arbitration   This message   'ArbitResult'      'NodeRestart'2      'ALERT'
check lost -   reports on
less than      the result
1/2 nodes      of
left' or       arbitration.
'Arbitration   In the event
check won -    of
all node       arbitration
groups and     failure, an
more than      ERROR_MESSAGE
1/2 nodes      and an
left' or       arbitration
'Arbitration   STATE_CODE
check won -    are
node group     provided;
majority' or   definitions
'Arbitration   for both of
check lost -   these are
missing node   found in
group' or      'include/kernel/signaldata/ArbitSignalData.hpp'.
'Network
partitioning
-
arbitration
required' or
'Arbitration
won -
positive
reply from
node
NODE_ID' or
'Arbitration
lost -
negative
reply from
node
NODE_ID' or
'Network
partitioning
- no
arbitrator
available'
or 'Network
partitioning
- no
arbitrator
configured'
or
'Arbitration
failure -
ERROR_MESSAGE
[state=STATE_CODE]'

'Node          This node is   'GCP_TakeoverStarted''NodeRestart'7    'INFO'
NODE_ID: GCP   attempting
Take over      to assume
started'       responsibility
               for the next
               global
               checkpoint
               (that is, it
               is becoming
               the master
               node)

'Node          This node      'GCP_TakeoverCompleted''NodeRestart'7  'INFO'
NODE_ID: GCP   has become
Take over      the master,
completed'     and has
               assumed
               responsibility
               for the next
               global
               checkpoint

'Node          This node is   'LCP_TakeoverStarted''NodeRestart'7    'INFO'
NODE_ID: LCP   attempting
Take over      to assume
started'       responsibility
               for the next
               set of local
               checkpoints
               (that is, it
               is becoming
               the master
               node)

'Node          This node      'LCP_TakeoverCompleted''NodeRestart'7  'INFO'
NODE_ID: LCP   has become
Take over      the master,
completed'     and has
               assumed
               responsibility
               for the next
               set of local
               checkpoints

'Node          This report    'TransReportCounters''Statistic'8      'INFO'
NODE_ID:       of
Trans. Count   transaction
=              activity is
TRANSACTIONS,  given
Commit Count   approximately
= COMMITS,     once every
Read Count =   10 seconds
READS,
Simple Read
Count =
SIMPLE_READS,
Write Count
= WRITES,
AttrInfo
Count =
ATTRINFO_OBJECTS,
Concurrent
Operations =
CONCURRENT_OPERATIONS,
Abort Count
= ABORTS,
Scans =
SCANS, Range
scans =
RANGE_SCANS'

'Node          Number of      'OperationReportCounters''Statistic'8  'INFO'
NODE_ID:       operations
Operations=OPERATIONS'performed by
               this node,
               provided
               approximately
               once every
               10 seconds

'Node          A table        'TableCreated'     'Statistic' 7       'INFO'
NODE_ID:       having the
Table with     table ID
ID =           shown has
TABLE_ID       been created
created'

'Node                         'JobStatistic'     'Statistic' 9       'INFO'
NODE_ID:
Mean loop
Counter in
doJob last
8192 times =
COUNT'

'Mean send     This node is   'SendBytesStatistic''Statistic'9       'INFO'
size to Node   sending an
= NODE_ID      average of
last 4096      BYTES bytes
sends =        per send to
BYTES bytes'   node NODE_ID

'Mean          This node is   'ReceiveBytesStatistic''Statistic'9    'INFO'
receive size   receiving an
to Node =      average of
NODE_ID last   BYTES of
4096 sends =   data each
BYTES bytes'   time it
               receives
               data from
               node NODE_ID

'Node          This report    'MemoryUsage'      'Statistic' 5       'INFO'
NODE_ID:       is generated
Data usage     when a 'DUMP
is             1000'
DATA_MEMORY_PERCENTAGE%(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-dump-commands.html)
(DATA_PAGES_USEDcommand is
32K pages of   issued in
total          the cluster
DATA_PAGES_TOTAL)'management
/ 'Node        client; for
NODE_ID:       more
Index usage    information,
is             see DUMP
INDEX_MEMORY_PERCENTAGE%1000
(INDEX_PAGES_USED(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-dump-command-1000.html),
8K pages of    in MySQL NDB
total          Cluster
INDEX_PAGES_TOTAL)Internals
'              Manual
               (http://dev.mysql.com/doc/ndb-internals/en/)

'Node          A              'TransporterError' 'Error'     2       'ERROR'
NODE1_ID:      transporter
Transporter    error
to node        occurred
NODE2_ID       while
reported       communicating
error          with node
ERROR_CODE:    NODE2_ID;
ERROR_MESSAGE' for a
               listing of
               transporter
               error codes
               and
               messages,
               see NDB
               Transporter
               Errors
               (http://dev.mysql.com/doc/ndb-internals/en/ndb-transporter-errors.html),
               in MySQL NDB
               Cluster
               Internals
               Manual
               (http://dev.mysql.com/doc/ndb-internals/en/)

'Node          A warning of   'TransporterWarning''Error'    8       'WARNING'
NODE1_ID:      a potential
Transporter    transporter
to node        problem
NODE2_ID       while
reported       communicating
error          with node
ERROR_CODE:    NODE2_ID;
ERROR_MESSAGE' for a
               listing of
               transporter
               error codes
               and
               messages,
               see NDB
               Transporter
               Errors
               (http://dev.mysql.com/doc/ndb-internals/en/ndb-transporter-errors.html),
               for more
               information

'Node          This node      'MissedHeartbeat'  'Error'     8       'WARNING'
NODE1_ID:      missed a
Node           heartbeat
NODE2_ID       from node
missed         NODE2_ID
heartbeat
HEARTBEAT_ID'

'Node          This node      'DeadDueToHeartbeat''Error'    8       'ALERT'
NODE1_ID:      has missed
Node           at least 3
NODE2_ID       heartbeats
declared       from node
dead due to    NODE2_ID,
missed         and so has
heartbeat'     declared
               that node
               'dead'

'Node          This node      'SentHeartbeat'    'Info'      12      'INFO'
NODE1_ID:      has sent a
Node Sent      heartbeat to
Heartbeat to   node
node =         NODE2_ID
NODE2_ID'

(_NDB 7.5.0    This report    'EventBufferStatus''Info'      7       'INFO'
and            is seen
earlier_:)     during heavy
'Node          event buffer
NODE_ID:       usage, for
Event buffer   example,
status:        when many
used=BYTES_USEDupdates are
(PERCENT_USED%)being
alloc=BYTES_ALLOCATEDapplied in a
(PERCENT_AVAILABLE%)relatively
max=BYTES_AVAILABLEshort period
apply_epoch=LATEST_RESTORABLE_EPOCHof time; the
latest_epoch=LATEST_EPOCH'report shows
               the number
               of bytes and
               the
               percentage
               of event
               buffer
               memory used,
               the bytes
               allocated
               and
               percentage
               still
               available,
               and the
               latest and
               latest
               restorable
               epochs

(_NDB 7.5.1    This report    'EventBufferStatus2''Info'     7       'INFO'
and later_:)   is seen
'Node          during heavy
NODE_ID:       event buffer
Event buffer   usage, for
status         example,
(OBJECT_ID):   when many
used=BYTES_USEDupdates are
(PERCENT_USED% being
of alloc)      applied in a
alloc=BYTES_ALLOCATEDrelatively
max=BYTES_AVAILABLEshort period
latest_consumed_epoch=LATEST_CONSUMED_EPOCHof time; the
latest_buffered_epoch=LATEST_BUFFERED_EPOCHreport shows
report_reason=REPORT_REASON'the number
               of bytes and
               the
               percentage
               of event
               buffer
               memory used,
               the bytes
               allocated
               and
               percentage
               still
               available,
               and the
               latest
               buffered and
               consumed
               epochs; for
               more
               information,
               see
               mysql-cluster-logs-event-buffer

'Node          These          'SingleUser'       'Info'      7       'INFO'
NODE_ID:       reports are
Entering       written to
single user    the cluster
mode', 'Node   log when
NODE_ID:       entering and
Entered        exiting
single user    single user
mode Node      mode;
API_NODE_ID    API_NODE_ID
has            is the node
exclusive      ID of the
access',       API or SQL
'Node          having
NODE_ID:       exclusive
Entering       access to
single user    the cluster
mode'          (for more
               information,
               see
               mysql-cluster-single-user-mode);
               the message
               'Unknown
               single user
               report
               API_NODE_ID'
               indicates an
               error has
               taken place
               and should
               never be
               seen in
               normal
               operation

'Node          A backup has   'BackupStarted'    'Backup'    7       'INFO'
NODE_ID:       been started
Backup         using the
BACKUP_ID      management
started from   node having
node           MGM_NODE_ID;
MGM_NODE_ID'   this message
               is also
               displayed in
               the cluster
               management
               client when
               the
               'START BACKUP'.
               command is
               issued; for
               more
               information,
               see
               mysql-cluster-backup-using-management-client

'Node          The backup     'BackupCompleted'  'Backup'    7       'INFO'
NODE_ID:       having the
Backup         ID BACKUP_ID
BACKUP_ID      has been
started from   completed;
node           for more
MGM_NODE_ID    information,
completed.     see *note
StartGCP:      mysql-cluster-backup-using-management-client::
START_GCP
StopGCP:
STOP_GCP
#Records:
RECORDS
#LogRecords:
LOG_RECORDS
Data:
DATA_BYTES
bytes Log:
LOG_BYTES
bytes'

'Node          The backup     'BackupFailedToStart''Backup'  7       'ALERT'
NODE_ID:       failed to
Backup         start; for
request from   error codes,
MGM_NODE_ID    see MGM API
failed to      Errors
start.         (http://dev.mysql.com/doc/ndbapi/en/mgm-errors.html)
Error:
ERROR_CODE'

'Node          The backup     'BackupAborted'    'Backup'    7       'ALERT'
NODE_ID:       was
Backup         terminated
BACKUP_ID      after
started from   starting,
MGM_NODE_ID    possibly due
has been       to user
aborted.       intervention
Error:
ERROR_CODE'

21.5.7.2 NDB Cluster Log Startup Messages
.........................................

Possible startup messages with descriptions are provided in the
following list:

   * 'Initial start, waiting for %s to connect, nodes [ all: %s
     connected: %s no-wait: %s ]'

   * 'Waiting until nodes: %s connects, nodes [ all: %s connected: %s
     no-wait: %s ]'

   * 'Waiting %u sec for nodes %s to connect, nodes [ all: %s connected:
     %s no-wait: %s ]'

   * 'Waiting for non partitioned start, nodes [ all: %s connected: %s
     missing: %s no-wait: %s ]'

   * 'Waiting %u sec for non partitioned start, nodes [ all: %s
     connected: %s missing: %s no-wait: %s ]'

   * 'Initial start with nodes %s [ missing: %s no-wait: %s ]'

   * 'Start with all nodes %s'

   * 'Start with nodes %s [ missing: %s no-wait: %s ]'

   * 'Start potentially partitioned with nodes %s [ missing: %s no-wait:
     %s ]'

   * 'Unknown startreport: 0x%x [ %s %s %s %s ]'

21.5.7.3 Event Buffer Reporting in the Cluster Log
..................................................

'NDB' uses one or more memory buffers for events received from the data
nodes.  There is one such buffer for each 'Ndb'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) object subscribing to
table events, which means that there are usually two buffers for each
'mysqld' performing binary logging (one buffer for schema
events, and one for data events).  Each buffer contains epochs made up
of events.  These events consist of operation types (insert, update,
delete) and row data (before and after images plus metadata).

'NDB' generates messages in the cluster log to describe the state of
these buffers.  Although these reports appear in the cluster log, they
refer to buffers on API nodes (unlike most other cluster log messages,
which are generated by data nodes).  These messages and the data
structures underlying them were changed significantly in NDB 7.5.1, with
the addition of the 'NDB_LE_EventBufferStatus2' event type and the
'ndb_logevent_EventBufferStatus2' data structure (see The
Ndb_logevent_type Type
(http://dev.mysql.com/doc/ndbapi/en/mgm-ndb-logevent-type.html)).  The
remainder of this discussion focuses on the implementation based on
'NDB_LE_EventBufferStatus2'.

Event buffer logging reports in the cluster log use the format shown
here:

     Node NODE_ID: Event buffer status (OBJECT_ID):
     used=BYTES_USED (PERCENT_USED% of alloc)
     alloc=BYTES_ALLOCATED (PERCENT_ALLOC% of max) max=BYTES_AVAILABLE
     latest_consumed_epoch=LATEST_CONSUMED_EPOCH
     latest_buffered_epoch=LATEST_BUFFERED_EPOCH
     report_reason=REPORT_REASON

The fields making up this report are listed here, with descriptions:

   * NODE_ID: ID of the node where the report originated.

   * OBJECT_ID: ID of the 'Ndb'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) object where the
     report originated.

   * BYTES_USED: Number of bytes used by the buffer.

   * PERCENT_USED: Percentage of allocated bytes used.

   * BYTES_ALLOCATED: Number of bytes allocated to this buffer.

   * PERCENT_ALLOC: Percentage of available bytes used; not printed if
     'ndb_eventbuffer_max_alloc' is equal to 0 (unlimited).

   * BYTES_AVAILABLE: Number of bytes available; this is 0 if
     'ndb_eventbuffer_max_alloc' is 0 (unlimited).

   * LATEST_CONSUMED_EPOCH: The epoch most recently consumed to
     completion.  (In NDB API applications, this is done by calling
     'nextEvent()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-nextevent.html).)

   * LATEST_BUFFERED_EPOCH: The epoch most recently buffered
     (completely) in the event buffer.

   * REPORT_REASON: The reason for making the report.  Possible reasons
     are shown later in this section.

The 'latest_consumed_epoch' and 'latest_buffered_epoch' fields
correspond, respectively, to the 'apply_gci' and 'latest_gci' fields of
the old-style event buffer logging messages used prior to NDB 7.5.1.

Possible reasons for reporting are described in the following list:

   * 'ENOUGH_FREE_EVENTBUFFER': The event buffer has sufficient space.

     'LOW_FREE_EVENTBUFFER': The event buffer is running low on free
     space.

     The threshold free percentage level triggering these reports can be
     adjusted by setting the 'ndb_report_thresh_binlog_mem_usage' server
     variable.

   * 'BUFFERED_EPOCHS_OVER_THRESHOLD': Whether the number of buffered
     epochs has exceeded the configured threshold.  This number is the
     difference between the latest epoch that has been received in its
     entirety and the epoch that has most recently been consumed (in NDB
     API applications, this is done by calling 'nextEvent()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-nextevent.html) or
     'nextEvent2()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-nextevent2.html)).  The
     report is generated every second until the number of buffered
     epochs goes below the threshold, which can be adjusted by setting
     the 'ndb_report_thresh_binlog_epoch_slip' server variable.  You can
     also adjust the threshold in NDB API applications by calling
     'setEventBufferQueueEmptyEpoch()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-seteventbufferqueueemptyepoch.html).

   * 'PARTIALLY_DISCARDING': Event buffer memory is exhausted--that is,
     100% of 'ndb_eventbuffer_max_alloc' has been used.  Any partially
     buffered epoch is buffered to completion even is usage exceeds
     100%, but any new epochs received are discarded.  This means that a
     gap has occurred in the event stream.

   * 'COMPLETELY_DISCARDING': No epochs are buffered.

   * 'PARTIALLY_BUFFERING': The buffer free percentage following the gap
     has risen to the threshold, which can be set in the 'mysql'
     client using the 'ndb_eventbuffer_free_percent' server
     system variable or in NDB API applications by calling
     'set_eventbuffer_free_percent()'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-set-eventbuffer-free-percent.html).
     New epochs are buffered.  Epochs that could not be completed due to
     the gap are discarded.

   * 'COMPLETELY_BUFFERING': All epochs received are being buffered,
     which means that there is sufficient event buffer memory.  The gap
     in the event stream has been closed.

21.5.7.4 NDB Cluster: NDB Transporter Errors
............................................

This section lists error codes, names, and messages that are written to
the cluster log in the event of transporter errors.

*Error codes generated by transporter errors*

Error   Error Name                                  Error Text
Code

0x00    TE_NO_ERROR                                 'No error'

0x01    TE_ERROR_CLOSING_SOCKET                     'Error found during
                                                    closing of socket'

0x02    TE_ERROR_IN_SELECT_BEFORE_ACCEPT            'Error found before
                                                    accept. The
                                                    transporter will
                                                    retry'

0x03    TE_INVALID_MESSAGE_LENGTH                   'Error found in
                                                    message (invalid
                                                    message length)'

0x04    TE_INVALID_CHECKSUM                         'Error found in
                                                    message (checksum)'

0x05    TE_COULD_NOT_CREATE_SOCKET                  'Error found while
                                                    creating
                                                    socket(can't create
                                                    socket)'

0x06    TE_COULD_NOT_BIND_SOCKET                    'Error found while
                                                    binding server
                                                    socket'

0x07    TE_LISTEN_FAILED                            'Error found while
                                                    listening to server
                                                    socket'

0x08    TE_ACCEPT_RETURN_ERROR                      'Error found during
                                                    accept(accept return
                                                    error)'

0x0b    TE_SHM_DISCONNECT                           'The remote node has
                                                    disconnected'

0x0c    TE_SHM_IPC_STAT                             'Unable to check shm
                                                    segment'

0x0d    TE_SHM_UNABLE_TO_CREATE_SEGMENT             'Unable to create
                                                    shm segment'

0x0e    TE_SHM_UNABLE_TO_ATTACH_SEGMENT             'Unable to attach
                                                    shm segment'

0x0f    TE_SHM_UNABLE_TO_REMOVE_SEGMENT             'Unable to remove
                                                    shm segment'

0x10    TE_TOO_SMALL_SIGID                          'Sig ID too small'

0x11    TE_TOO_LARGE_SIGID                          'Sig ID too large'

0x12    TE_WAIT_STACK_FULL                          'Wait stack was
                                                    full'

0x13    TE_RECEIVE_BUFFER_FULL                      'Receive buffer was
                                                    full'

0x14    TE_SIGNAL_LOST_SEND_BUFFER_FULL             'Send buffer was
                                                    full,and trying to
                                                    force send fails'

0x15    TE_SIGNAL_LOST                              'Send failed for
                                                    unknown
                                                    reason(signal lost)'

0x16    TE_SEND_BUFFER_FULL                         'The send buffer was
                                                    full, but sleeping
                                                    for a while solved'

0x0017  TE_SCI_LINK_ERROR                           'There is no link
                                                    from this node to
                                                    the switch'

0x18    TE_SCI_UNABLE_TO_START_SEQUENCE             'Could not start a
                                                    sequence, because
                                                    system resources are
                                                    exumed or no
                                                    sequence has been
                                                    created'

0x19    TE_SCI_UNABLE_TO_REMOVE_SEQUENCE            'Could not remove a
                                                    sequence'

0x1a    TE_SCI_UNABLE_TO_CREATE_SEQUENCE            'Could not create a
                                                    sequence, because
                                                    system resources are
                                                    exempted. Must
                                                    reboot'

0x1b    TE_SCI_UNRECOVERABLE_DATA_TFX_ERROR         'Tried to send data
                                                    on redundant link
                                                    but failed'

0x1c    TE_SCI_CANNOT_INIT_LOCALSEGMENT             'Cannot initialize
                                                    local segment'

0x1d    TE_SCI_CANNOT_MAP_REMOTESEGMENT             'Cannot map remote
                                                    segment'

0x1e    TE_SCI_UNABLE_TO_UNMAP_SEGMENT              'Cannot free the
                                                    resources used by
                                                    this segment (step
                                                    1)'

0x1f    TE_SCI_UNABLE_TO_REMOVE_SEGMENT             'Cannot free the
                                                    resources used by
                                                    this segment (step
                                                    2)'

0x20    TE_SCI_UNABLE_TO_DISCONNECT_SEGMENT         'Cannot disconnect
                                                    from a remote
                                                    segment'

0x21    TE_SHM_IPC_PERMANENT                        'Shm ipc Permanent
                                                    error'

0x22    TE_SCI_UNABLE_TO_CLOSE_CHANNEL              'Unable to close the
                                                    sci channel and the
                                                    resources allocated'

21.5.8 NDB Cluster Single User Mode
-----------------------------------

_Single user mode_ enables the database administrator to restrict access
to the database system to a single API node, such as a MySQL server (SQL
node) or an instance of 'ndb_restore'.
When entering single user mode,
connections to all other API nodes are closed gracefully and all running
transactions are aborted.  No new transactions are permitted to start.

Once the cluster has entered single user mode, only the designated API
node is granted access to the database.

You can use the 'ALL STATUS' command in the 'ndb_mgm'
client to see when the cluster has
entered single user mode.  You can also check the 'status' column of the
'ndbinfo.nodes' table (see
mysql-cluster-ndbinfo-nodes, for more information).

Example:

     ndb_mgm> ENTER SINGLE USER MODE 5

After this command has executed and the cluster has entered single user
mode, the API node whose node ID is '5' becomes the cluster's only
permitted user.

The node specified in the preceding command must be an API node;
attempting to specify any other type of node will be rejected.

*Note*:

When the preceding command is invoked, all transactions running on the
designated node are aborted, the connection is closed, and the server
must be restarted.

The command 'EXIT SINGLE USER MODE' changes the state of the cluster's
data nodes from single user mode to normal mode.  API nodes--such as
MySQL Servers--waiting for a connection (that is, waiting for the
cluster to become ready and available), are again permitted to connect.
The API node denoted as the single-user node continues to run (if still
connected) during and after the state change.

Example:

     ndb_mgm> EXIT SINGLE USER MODE

There are two recommended ways to handle a node failure when running in
single user mode:

   * Method 1:

       1. Finish all single user mode transactions

       2. Issue the 'EXIT SINGLE USER MODE' command

       3. Restart the cluster's data nodes

   * Method 2:

     Restart storage nodes prior to entering single user mode.

21.5.9 Quick Reference: NDB Cluster SQL Statements
--------------------------------------------------

This section discusses several SQL statements that can prove useful in
managing and monitoring a MySQL server that is connected to an NDB
Cluster, and in some cases provide information about the cluster itself.

   * 'SHOW ENGINE NDB STATUS', 'SHOW ENGINE NDBCLUSTER STATUS'.

     The output of this statement contains information about the
     server's connection to the cluster, creation and usage of NDB
     Cluster objects, and binary logging for NDB Cluster replication.

     See show-engine, for a usage example and more detailed
     information.

   *
     'SHOW ENGINES'.

     This statement can be used to determine whether or not clustering
     support is enabled in the MySQL server, and if so, whether it is
     active.

     See show-engines, for more detailed information.

     *Note*:

     This statement does not support a 'LIKE' clause.  However, you can
     use 'LIKE' to filter queries against the
     'INFORMATION_SCHEMA.ENGINES' table, as discussed in
     the next item.

   *
     'SELECT * FROM INFORMATION_SCHEMA.ENGINES [WHERE ENGINE LIKE
     'NDB%']'

     This is the equivalent of 'SHOW ENGINES', but
     uses the 'ENGINES' table of the
     'INFORMATION_SCHEMA' database.  Unlike the case with the
     'SHOW ENGINES' statement, it is possible to filter
     the results using a 'LIKE' clause, and to select specific columns
     to obtain information that may be of use in scripts.  For example,
     the following query shows whether the server was built with
     'NDB' support and, if so, whether it is enabled:

          mysql> SELECT SUPPORT FROM INFORMATION_SCHEMA.ENGINES
              ->   WHERE ENGINE LIKE 'NDB%';
          +---------+
          | support |
          +---------+
          | ENABLED |
          +---------+

     See engines-table, for more information.

   *
     'SHOW VARIABLES LIKE 'NDB%''

     This statement provides a list of most server system variables
     relating to the 'NDB' storage engine, and
     their values, as shown here:

          mysql> SHOW VARIABLES LIKE 'NDB%';
          +-------------------------------------+-------+
          | Variable_name                       | Value |
          +-------------------------------------+-------+
          | ndb_autoincrement_prefetch_sz       | 32    |
          | ndb_cache_check_time                | 0     |
          | ndb_extra_logging                   | 0     |
          | ndb_force_send                      | ON    |
          | ndb_index_stat_cache_entries        | 32    |
          | ndb_index_stat_enable               | OFF   |
          | ndb_index_stat_update_freq          | 20    |
          | ndb_report_thresh_binlog_epoch_slip | 3     |
          | ndb_report_thresh_binlog_mem_usage  | 10    |
          | ndb_use_copying_alter_table         | OFF   |
          | ndb_use_exact_count                 | ON    |
          | ndb_use_transactions                | ON    |
          +-------------------------------------+-------+

     See server-system-variables, for more information.

   *
     'SELECT * FROM INFORMATION_SCHEMA.GLOBAL_VARIABLES WHERE
     VARIABLE_NAME LIKE 'NDB%';'

     This statement is the equivalent of the 'SHOW' command described in
     the previous item, and provides almost identical output, as shown
     here:

          mysql> SELECT * FROM INFORMATION_SCHEMA.GLOBAL_VARIABLES
              ->   WHERE VARIABLE_NAME LIKE 'NDB%';
          +-------------------------------------+----------------+
          | VARIABLE_NAME                       | VARIABLE_VALUE |
          +-------------------------------------+----------------+
          | NDB_AUTOINCREMENT_PREFETCH_SZ       | 32             |
          | NDB_CACHE_CHECK_TIME                | 0              |
          | NDB_EXTRA_LOGGING                   | 0              |
          | NDB_FORCE_SEND                      | ON             |
          | NDB_INDEX_STAT_CACHE_ENTRIES        | 32             |
          | NDB_INDEX_STAT_ENABLE               | OFF            |
          | NDB_INDEX_STAT_UPDATE_FREQ          | 20             |
          | NDB_REPORT_THRESH_BINLOG_EPOCH_SLIP | 3              |
          | NDB_REPORT_THRESH_BINLOG_MEM_USAGE  | 10             |
          | NDB_USE_COPYING_ALTER_TABLE         | OFF            |
          | NDB_USE_EXACT_COUNT                 | ON             |
          | NDB_USE_TRANSACTIONS                | ON             |
          +-------------------------------------+----------------+

     Unlike the case with the 'SHOW' command, it is possible to select
     individual columns.  For example:

          mysql> SELECT VARIABLE_VALUE
              ->   FROM INFORMATION_SCHEMA.GLOBAL_VARIABLES
              ->   WHERE VARIABLE_NAME = 'ndb_force_send';
          +----------------+
          | VARIABLE_VALUE |
          +----------------+
          | ON             |
          +----------------+

     See variables-table, and server-system-variables,
     for more information.

   *
     'SHOW STATUS LIKE 'NDB%''

     This statement shows at a glance whether or not the MySQL server is
     acting as a cluster SQL node, and if so, it provides the MySQL
     server's cluster node ID, the host name and port for the cluster
     management server to which it is connected, and the number of data
     nodes in the cluster, as shown here:

          mysql> SHOW STATUS LIKE 'NDB%';
          +--------------------------+----------------+
          | Variable_name            | Value          |
          +--------------------------+----------------+
          | Ndb_cluster_node_id      | 10             |
          | Ndb_config_from_host     | 198.51.100.103 |
          | Ndb_config_from_port     | 1186           |
          | Ndb_number_of_data_nodes | 4              |
          +--------------------------+----------------+

     If the MySQL server was built with clustering support, but it is
     not connected to a cluster, all rows in the output of this
     statement contain a zero or an empty string:

          mysql> SHOW STATUS LIKE 'NDB%';
          +--------------------------+-------+
          | Variable_name            | Value |
          +--------------------------+-------+
          | Ndb_cluster_node_id      | 0     |
          | Ndb_config_from_host     |       |
          | Ndb_config_from_port     | 0     |
          | Ndb_number_of_data_nodes | 0     |
          +--------------------------+-------+

     See also show-status.

   *
     'SELECT * FROM INFORMATION_SCHEMA.GLOBAL_STATUS WHERE VARIABLE_NAME
     LIKE 'NDB%';'

     This statement provides similar output to the 'SHOW' command
     discussed in the previous item.  However, unlike the case with
     'SHOW STATUS', it is possible using the
     'SELECT' to extract values in SQL for use in scripts for
     monitoring and automation purposes.

     See status-table, for more information.

You can also query the tables in the 'ndbinfo'
information database for real-time data about
many NDB Cluster operations.  See mysql-cluster-ndbinfo.

21.5.10 ndbinfo: The NDB Cluster Information Database
-----------------------------------------------------

'ndbinfo' is a database containing information specific to NDB Cluster.

This database contains a number of tables, each providing a different
sort of data about NDB Cluster node status, resource usage, and
operations.  You can find more detailed information about each of these
tables in the next several sections.

'ndbinfo' is included with NDB Cluster support in the MySQL Server; no
special compilation or configuration steps are required; the tables are
created by the MySQL Server when it connects to the cluster.  You can
verify that 'ndbinfo' support is active in a given MySQL Server instance
using 'SHOW PLUGINS'.; if 'ndbinfo' support is
enabled, you should see a row containing 'ndbinfo' in the 'Name' column
and 'ACTIVE' in the 'Status' column, as shown here (emphasized text):

     mysql> SHOW PLUGINS;
     +----------------------------------+--------+--------------------+---------+---------+
     | Name                             | Status | Type               | Library | License |
     +----------------------------------+--------+--------------------+---------+---------+
     | binlog                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | mysql_native_password            | ACTIVE | AUTHENTICATION     | NULL    | GPL     |
     | sha256_password                  | ACTIVE | AUTHENTICATION     | NULL    | GPL     |
     | MRG_MYISAM                       | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | MEMORY                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | CSV                              | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | MyISAM                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | InnoDB                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | INNODB_TRX                       | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_LOCKS                     | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_LOCK_WAITS                | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMP                       | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMP_RESET                 | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMPMEM                    | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMPMEM_RESET              | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMP_PER_INDEX             | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMP_PER_INDEX_RESET       | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_BUFFER_PAGE               | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_BUFFER_PAGE_LRU           | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_BUFFER_POOL_STATS         | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_TEMP_TABLE_INFO           | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_METRICS                   | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_FT_DEFAULT_STOPWORD       | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_FT_DELETED                | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_FT_BEING_DELETED          | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_FT_CONFIG                 | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_FT_INDEX_CACHE            | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_FT_INDEX_TABLE            | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_TABLES                | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_TABLESTATS            | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_INDEXES               | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_COLUMNS               | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_FIELDS                | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_FOREIGN               | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_FOREIGN_COLS          | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_TABLESPACES           | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_DATAFILES             | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_SYS_VIRTUAL               | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | PERFORMANCE_SCHEMA               | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | ndbCluster                      | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     _| ndbinfo                          | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |_
     | ndb_transid_mysql_connection_map | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | BLACKHOLE                        | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | ARCHIVE                          | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | partition                        | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | ngram                            | ACTIVE | FTPARSER           | NULL    | GPL     |
     +----------------------------------+--------+--------------------+---------+---------+
     46 rows in set (0.00 sec)

You can also do this by checking the output of 'SHOW ENGINES'
for a line including 'ndbinfo' in the 'Engine' column and
'YES' in the 'Support' column, as shown here (emphasized text):

     mysql> SHOW ENGINES\G
     *************************** 1. row ***************************
           Engine: ndbcluster
          Support: YES
          Comment: Clustered, fault-tolerant tables
     Transactions: YES
               XA: NO
       Savepoints: NO
     *************************** 2. row ***************************
           Engine: CSV
          Support: YES
          Comment: CSV storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 3. row ***************************
           Engine: InnoDB
          Support: DEFAULT
          Comment: Supports transactions, row-level locking, and foreign keys
     Transactions: YES
               XA: YES
       Savepoints: YES
     *************************** 4. row ***************************
           Engine: BLACKHOLE
          Support: YES
          Comment: /dev/null storage engine (anything you write to it disappears)
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 5. row ***************************
           Engine: MyISAM
          Support: YES
          Comment: MyISAM storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 6. row ***************************
           Engine: MRG_MYISAM
          Support: YES
          Comment: Collection of identical MyISAM tables
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 7. row ***************************
           Engine: ARCHIVE
          Support: YES
          Comment: Archive storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO
     _*************************** 8. row ***************************
           Engine: ndbinfo
          Support: YES
          Comment: NDB Cluster system information storage engine
     Transactions: NO
               XA: NO
       Savepoints: NO_
     *************************** 9. row ***************************
           Engine: PERFORMANCE_SCHEMA
          Support: YES
          Comment: Performance Schema
     Transactions: NO
               XA: NO
       Savepoints: NO
     *************************** 10. row ***************************
           Engine: MEMORY
          Support: YES
          Comment: Hash based, stored in memory, useful for temporary tables
     Transactions: NO
               XA: NO
       Savepoints: NO
     10 rows in set (0.00 sec)

If 'ndbinfo' support is enabled, then you can access 'ndbinfo' using SQL
statements in 'mysql' or another MySQL client.  For
example, you can see 'ndbinfo' listed in the output of 'SHOW DATABASES',
as shown here (emphasized text):

     mysql> SHOW DATABASES;
     +--------------------+
     | Database           |
     +--------------------+
     | information_schema |
     | mysql              |
     _| ndbinfo            |_
     | performance_schema |
     | sys                |
     +--------------------+
     5 rows in set (0.04 sec)

If the 'mysqld' process was not started with the
'--ndbcluster' option, 'ndbinfo' is not available and is not displayed
by 'SHOW DATABASES'.  If 'mysqld'.
was formerly connected to an NDB Cluster but the cluster becomes
unavailable (due to events such as cluster shutdown, loss of network
connectivity, and so forth), 'ndbinfo' and its tables remain visible,
but an attempt to access any tables (other than 'blocks' or
'config_params') fails with 'Got error 157 'Connection to NDB failed'
from NDBINFO'.

With the exception of the 'blocks' and 'config_params' tables, what we
refer to as 'ndbinfo' 'tables' are actually views generated from
internal 'NDB' tables not normally visible to the
MySQL Server.

All 'ndbinfo' tables are read-only, and are generated on demand when
queried.  Because many of them are generated in parallel by the data
nodes while other are specific to a given SQL node, they are not
guaranteed to provide a consistent snapshot.

In addition, pushing down of joins is not supported on 'ndbinfo' tables;
so joining large 'ndbinfo' tables can require transfer of a large amount
of data to the requesting API node, even when the query makes use of a
'WHERE' clause.

'ndbinfo' tables are not included in the query cache.  (Bug #59831)

You can select the 'ndbinfo' database with a 'USE'.
statement, and then issue a 'SHOW TABLES' statement
to obtain a list of tables, just as for any other database, like this:

     mysql> USE ndbinfo;
     Database changed

     mysql> SHOW TABLES;
     +---------------------------------+
     | Tables_in_ndbinfo               |
     +---------------------------------+
     | arbitrator_validity_detail      |
     | arbitrator_validity_summary     |
     | blocks                          |
     | cluster_locks                   |
     | cluster_operations              |
     | cluster_transactions            |
     | config_nodes                    |
     | config_params                   |
     | config_values                   |
     | counters                        |
     | cpustat                         |
     | cpustat_1sec                    |
     | cpustat_20sec                   |
     | cpustat_50ms                    |
     | dict_obj_info                   |
     | dict_obj_types                  |
     | disk_write_speed_aggregate      |
     | disk_write_speed_aggregate_node |
     | disk_write_speed_base           |
     | diskpagebuffer                  |
     | error_messages                  |
     | locks_per_fragment              |
     | logbuffers                      |
     | logspaces                       |
     | membership                      |
     | memory_per_fragment             |
     | memoryusage                     |
     | nodes                           |
     | operations_per_fragment         |
     | processes                       |
     | resources                       |
     | restart_info                    |
     | server_locks                    |
     | server_operations               |
     | server_transactions             |
     | table_distribution_status       |
     | table_fragments                 |
     | table_info                      |
     | table_replicas                  |
     | tc_time_track_stats             |
     | threadblocks                    |
     | threads                         |
     | threadstat                      |
     | transporters                    |
     +---------------------------------+
     44 rows in set (0.00 sec)

In NDB 7.5.0 (and later), all 'ndbinfo' tables use the 'NDB' storage
engine; however, an 'ndbinfo' entry still appears in the output of
'SHOW ENGINES' and 'SHOW PLUGINS' as
described previously.

The 'config_values' table
was added in NDB 7.5.0.

The 'cpustat',
'cpustat_50ms',
'cpustat_1sec',
'cpustat_20sec', and
'threads' tables were added in NDB
7.5.2.

The 'cluster_locks',
'locks_per_fragment', and
'server_locks' tables were
added in NDB 7.5.3.

The 'dict_obj_info',
'table_distribution_status',
see
'table_fragments',
'table_info', and
'table_replicas' tables were
added in NDB 7.5.4.

The 'config_nodes' and
'processes' tables were added in NDB
7.5.7 and NDB 7.6.2.

The 'error_messages' table
was added in NDB 7.6.4.

You can execute 'SELECT' statements against these tables,
just as you would normally expect:

     mysql> SELECT * FROM memoryusage;
     +---------+---------------------+--------+------------+------------+-------------+
     | node_id | memory_type         | used   | used_pages | total      | total_pages |
     +---------+---------------------+--------+------------+------------+-------------+
     |       5 | Data memory         | 753664 |         23 | 1073741824 |       32768 |
     |       5 | Index memory        | 163840 |         20 | 1074003968 |      131104 |
     |       5 | Long message buffer |   2304 |          9 |   67108864 |      262144 |
     |       6 | Data memory         | 753664 |         23 | 1073741824 |       32768 |
     |       6 | Index memory        | 163840 |         20 | 1074003968 |      131104 |
     |       6 | Long message buffer |   2304 |          9 |   67108864 |      262144 |
     +---------+---------------------+--------+------------+------------+-------------+
     6 rows in set (0.02 sec)

More complex queries, such as the two following 'SELECT'.
statements using the 'memoryusage'
table, are possible:

     mysql> SELECT SUM(used) as 'Data Memory Used, All Nodes'
          >     FROM memoryusage
          >     WHERE memory_type = 'Data memory';
     +-----------------------------+
     | Data Memory Used, All Nodes |
     +-----------------------------+
     |                        6460 |
     +-----------------------------+
     1 row in set (0.37 sec)

     mysql> SELECT SUM(max) as 'Total IndexMemory Available'
          >     FROM memoryusage
          >     WHERE memory_type = 'Index memory';
     +-----------------------------+
     | Total IndexMemory Available |
     +-----------------------------+
     |                       25664 |
     +-----------------------------+
     1 row in set (0.33 sec)

'ndbinfo' table and column names are case sensitive (as is the name of
the 'ndbinfo' database itself).  These identifiers are in lowercase.
Trying to use the wrong lettercase results in an error, as shown in this
example:

     mysql> SELECT * FROM nodes;
     +---------+--------+---------+-------------+
     | node_id | uptime | status  | start_phase |
     +---------+--------+---------+-------------+
     |       1 |  13602 | STARTED |           0 |
     |       2 |     16 | STARTED |           0 |
     +---------+--------+---------+-------------+
     2 rows in set (0.04 sec)

     mysql> SELECT * FROM Nodes;
     ERROR 1146 (42S02): Table 'ndbinfo.Nodes' doesn't exist

'mysqldump' ignores the 'ndbinfo' database entirely,
and excludes it from any output.  This is true even when using the
'--databases' or '--all-databases' option.

NDB Cluster also maintains tables in the 'INFORMATION_SCHEMA'
information database, including the 'FILES' table
which contains information about files used for NDB Cluster Disk Data
storage, and the 'ndb_transid_mysql_connection_map'
table, which shows the
relationships between transactions, transaction coordinators, and NDB
Cluster API nodes.  For more information, see the descriptions of the
tables or mysql-cluster-i_s-tables.

21.5.10.1 The ndbinfo arbitrator_validity_detail Table
......................................................

The 'arbitrator_validity_detail' table shows the view that each data
node in the cluster has of the arbitrator.  It is a subset of the
'membership' table.

The following table provides information about the columns in the
'arbitrator_validity_detail' table.  For each column, the table shows
the name, data type, and a brief description.  Additional information
can be found in the notes following the table.

*Columns of the arbitrator_validity_detail table*

Column Name            Type               Description

'node_id'              integer            This node's node ID

'arbitrator'           integer            Node ID of arbitrator

'arb_ticket'           string             Internal identifier used to
                                          track arbitration

'arb_connected'        'Yes' or 'No'      Whether this node is connected
                                          to the arbitrator

'arb_state'            Enumeration (see   Arbitration state
                       text)

The node ID is the same as that reported by 'ndb_mgm -e "SHOW"'.

All nodes should show the same 'arbitrator' and 'arb_ticket' values as
well as the same 'arb_state' value.  Possible 'arb_state' values are
'ARBIT_NULL', 'ARBIT_INIT', 'ARBIT_FIND', 'ARBIT_PREP1', 'ARBIT_PREP2',
'ARBIT_START', 'ARBIT_RUN', 'ARBIT_CHOOSE', 'ARBIT_CRASH', and
'UNKNOWN'.

'arb_connected' shows whether the current node is connected to the
'arbitrator'.

21.5.10.2 The ndbinfo arbitrator_validity_summary Table
.......................................................

The 'arbitrator_validity_summary' table provides a composite view of the
arbitrator with regard to the cluster's data nodes.

The following table provides information about the columns in the
'arbitrator_validity_summary' table.  For each column, the table shows
the name, data type, and a brief description.  Additional information
can be found in the notes following the table.

*Columns of the arbitrator_validity_summary table*

Column Name            Type               Description

'arbitrator'           integer            Node ID of arbitrator

'arb_ticket'           string             Internal identifier used to
                                          track arbitration

'arb_connected'        'Yes' or 'No'      Whether this arbitrator is
                                          connected to the cluster

'consensus_count'      integer            Number of data nodes that see
                                          this node as arbitrator

In normal operations, this table should have only 1 row for any
appreciable length of time.  If it has more than 1 row for longer than a
few moments, then either not all nodes are connected to the arbitrator,
or all nodes are connected, but do not agree on the same arbitrator.

The 'arbitrator' column shows the arbitrator's node ID.

'arb_ticket' is the internal identifier used by this arbitrator.

'arb_connected' shows whether this node is connected to the cluster as
an arbitrator.

21.5.10.3 The ndbinfo blocks Table
..................................

The 'blocks' table is a static table which simply contains the names and
internal IDs of all NDB kernel blocks (see NDB Kernel Blocks
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks.html)).
It is for use by the other 'ndbinfo'.
tables (most of which are actually views) in mapping block numbers to
block names for producing human-readable output.

The following table provides information about the columns in the
'blocks' table.  For each column, the table shows the name, data type,
and a brief description.  Additional information can be found in the
notes following the table.

*Columns of the blocks table*

Column Name            Type               Description

'block_number'         integer            Block number

'block_name'           string             Block name

To obtain a list of all block names, simply execute 'SELECT block_name
FROM ndbinfo.blocks'.  Although this is a static table, its content can
vary between different NDB Cluster releases.

21.5.10.4 The ndbinfo cluster_locks Table
.........................................

The 'cluster_locks' table provides information about current lock
requests holding and waiting for locks on 'NDB' tables in an NDB
Cluster, and is intended as a companion table to
'cluster_operations'.
Information obtain from the 'cluster_locks' table may be useful in
investigating stalls and deadlocks.

The following table provides information about the columns in the
'cluster_locks' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the cluster_locks table*

Column Name            Type               Description

'node_id'              integer            ID of reporting node

'block_instance'       integer            ID of reporting LDM instance

'tableid'              integer            ID of table containing this
                                          row

'fragmentid'           integer            ID of fragment containing
                                          locked row

'rowid'                integer            ID of locked row

'transid'              integer            Transaction ID

'mode'                 string             Lock request mode

'state'                string             Lock state

'detail'               string             Whether this is first holding
                                          lock in row lock queue

'op'                   string             Operation type

'duration_millis'      integer            Milliseconds spent waiting or
                                          holding lock

'lock_num'             integer            ID of lock object

'waiting_for'          integer            Waiting for lock with this ID

The table ID ('tableid' column) is assigned internally, and is the same
as that used in other 'ndbinfo' tables.  It is also shown in the output
of 'ndb_show_tables'.

The transaction ID ('transid' column) is the identifier generated by the
NDB API for the transaction requesting or holding the current lock.

The 'mode' column shows the lock mode; this is always one of 'S'
(indicating a shared lock) or 'X' (an exclusive lock).  If a transaction
holds an exclusive lock on a given row, all other locks on that row have
the same transaction ID.

The 'state' column shows the lock state.  Its value is always one of 'H'
(holding) or 'W' (waiting).  A waiting lock request waits for a lock
held by a different transaction.

When the 'detail' column contains a '*' (asterisk character), this means
that this lock is the first holding lock in the affected row's lock
queue; otherwise, this column is empty.  This information can be used to
help identify the unique entries in a list of lock requests.

The 'op' column shows the type of operation requesting the lock.  This
is always one of the values 'READ', 'INSERT', 'UPDATE', 'DELETE',
'SCAN', or 'REFRESH'.

The 'duration_millis' column shows the number of milliseconds for which
this lock request has been waiting or holding the lock.  This is reset
to 0 when a lock is granted for a waiting request.

The lock ID ('lockid' column) is unique to this node and block instance.

The lock state is shown in the 'lock_state' column; if this is 'W', the
lock is waiting to be granted, and the 'waiting_for' column shows the
lock ID of the lock object this request is waiting for.  Otherwise, the
'waiting_for' column is empty.  'waiting_for' can refer only to locks on
the same row, as identified by 'node_id', 'block_instance', 'tableid',
'fragmentid', and 'rowid'.

The 'cluster_locks' table was added in NDB 7.5.3.

21.5.10.5 The ndbinfo cluster_operations Table
..............................................

The 'cluster_operations' table provides a per-operation (stateful
primary key op) view of all activity in the NDB Cluster from the point
of view of the local data management (LQH) blocks (see The DBLQH Block
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks-dblqh.html)).

The following table provides information about the columns in the
'cluster_operations' table.  For each column, the table shows the name,
data type, and a brief description.  Additional information can be found
in the notes following the table.

*Columns of the cluster_operations table*

Column Name            Type               Description

'node_id'              integer            Node ID of reporting LQH block

'block_instance'       integer            LQH block instance

'transid'              integer            Transaction ID

'operation_type'       string             Operation type (see text for
                                          possible values)

'state'                string             Operation state (see text for
                                          possible values)

'tableid'              integer            Table ID

'fragmentid'           integer            Fragment ID

'client_node_id'       integer            Client node ID

'client_block_ref'     integer            Client block reference

'tc_node_id'           integer            Transaction coordinator node
                                          ID

'tc_block_no'          integer            Transaction coordinator block
                                          number

'tc_block_instance'    integer            Transaction coordinator block
                                          instance

The transaction ID is a unique 64-bit number which can be obtained using
the NDB API's 'getTransactionId()'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-gettransactionid.html)
method.  (Currently, the MySQL Server does not expose the NDB API
transaction ID of an ongoing transaction.)

The 'operation_type' column can take any one of the values 'READ',
'READ-SH', 'READ-EX', 'INSERT', 'UPDATE', 'DELETE', 'WRITE', 'UNLOCK',
'REFRESH', 'SCAN', 'SCAN-SH', 'SCAN-EX', or '<unknown>'.

The 'state' column can have any one of the values 'ABORT_QUEUED',
'ABORT_STOPPED', 'COMMITTED', 'COMMIT_QUEUED', 'COMMIT_STOPPED',
'COPY_CLOSE_STOPPED', 'COPY_FIRST_STOPPED', 'COPY_STOPPED',
'COPY_TUPKEY', 'IDLE', 'LOG_ABORT_QUEUED', 'LOG_COMMIT_QUEUED',
'LOG_COMMIT_QUEUED_WAIT_SIGNAL', 'LOG_COMMIT_WRITTEN',
'LOG_COMMIT_WRITTEN_WAIT_SIGNAL', 'LOG_QUEUED', 'PREPARED',
'PREPARED_RECEIVED_COMMIT', 'SCAN_CHECK_STOPPED', 'SCAN_CLOSE_STOPPED',
'SCAN_FIRST_STOPPED', 'SCAN_RELEASE_STOPPED', 'SCAN_STATE_USED',
'SCAN_STOPPED', 'SCAN_TUPKEY', 'STOPPED', 'TC_NOT_CONNECTED',
'WAIT_ACC', 'WAIT_ACC_ABORT', 'WAIT_AI_AFTER_ABORT', 'WAIT_ATTR',
'WAIT_SCAN_AI', 'WAIT_TUP', 'WAIT_TUPKEYINFO', 'WAIT_TUP_COMMIT', or
'WAIT_TUP_TO_ABORT'.  (If the MySQL Server is running with
'ndbinfo_show_hidden' enabled, you can view this list of states by
selecting from the 'ndb$dblqh_tcconnect_state' table, which is normally
hidden.)

You can obtain the name of an 'NDB' table from its table ID by checking
the output of 'ndb_show_tables'.

The 'fragid' is the same as the partition number seen in the output of
'ndb_desc'.
'--extra-partition-info' (short form '-p').

In 'client_node_id' and 'client_block_ref', 'client' refers to an NDB
Cluster API or SQL node (that is, an NDB API client or a MySQL Server
attached to the cluster).

The 'block_instance' and 'tc_block_instance' column provide,
respectively, the 'DBLQH' and 'DBTC' block instance numbers.  You can
use these along with the block names to obtain information about
specific threads from the 'threadblocks'
table.

21.5.10.6 The ndbinfo cluster_transactions Table
................................................

The 'cluster_transactions' table shows information about all ongoing
transactions in an NDB Cluster.

The following table provides information about the columns in the
'cluster_transactions' table.  For each column, the table shows the
name, data type, and a brief description.  Additional information can be
found in the notes following the table.

*Columns of the cluster_transactions table*

Column Name            Type               Description

'node_id'              integer            Node ID of transaction
                                          coordinator

'block_instance'       integer            TC block instance

'transid'              integer            Transaction ID

'state'                string             Operation state (see text for
                                          possible values)

'count_operations'     integer            Number of stateful primary key
                                          operations in transaction
                                          (includes reads with locks, as
                                          well as DML operations)

'outstanding_operations'integer           Operations still being
                                          executed in local data
                                          management blocks

'inactive_seconds'     integer            Time spent waiting for API

'client_node_id'       integer            Client node ID

'client_block_ref'     integer            Client block reference

The transaction ID is a unique 64-bit number which can be obtained using
the NDB API's 'getTransactionId()'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-gettransactionid.html)
method.  (Currently, the MySQL Server does not expose the NDB API
transaction ID of an ongoing transaction.)

'block_instance' refers to an instance of a kernel block.  Together with
the block name, this number can be used to look up a given instance in
the 'threadblocks' table.

The 'state' column can have any one of the values 'CS_ABORTING',
'CS_COMMITTING', 'CS_COMMIT_SENT', 'CS_COMPLETE_SENT', 'CS_COMPLETING',
'CS_CONNECTED', 'CS_DISCONNECTED', 'CS_FAIL_ABORTED',
'CS_FAIL_ABORTING', 'CS_FAIL_COMMITTED', 'CS_FAIL_COMMITTING',
'CS_FAIL_COMPLETED', 'CS_FAIL_PREPARED', 'CS_PREPARE_TO_COMMIT',
'CS_RECEIVING', 'CS_REC_COMMITTING', 'CS_RESTART',
'CS_SEND_FIRE_TRIG_REQ', 'CS_STARTED', 'CS_START_COMMITTING',
'CS_START_SCAN', 'CS_WAIT_ABORT_CONF', 'CS_WAIT_COMMIT_CONF',
'CS_WAIT_COMPLETE_CONF', 'CS_WAIT_FIRE_TRIG_REQ'.  (If the MySQL Server
is running with 'ndbinfo_show_hidden' enabled, you can view this list of
states by selecting from the 'ndb$dbtc_apiconnect_state' table, which is
normally hidden.)

In 'client_node_id' and 'client_block_ref', 'client' refers to an NDB
Cluster API or SQL node (that is, an NDB API client or a MySQL Server
attached to the cluster).

The 'tc_block_instance' column provides the 'DBTC' block instance
number.  You can use this along with the block name to obtain
information about specific threads from the 'threadblocks'
table.

21.5.10.7 The ndbinfo config_nodes Table
........................................

The 'config_nodes' table shows nodes configured in an NDB Cluster
'config.ini' file.  For each node, the table displays a row containing
the node ID, the type of node (management node, data node, or API node),
and the name or IP address of the host on which the node is configured
to run.

This table does not indicate whether a given node is actually running,
or whether it is currently connected to the cluster.  Information about
nodes connected to an NDB Cluster can be obtained from the
'nodes' and 'processes'
table.

The following table provides information about the columns in the
'config_nodes' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the config_params table*

Column Name            Type               Description

'node_id'              integer            The node's ID

'node_type'            string             The type of node

'node_hostname'        string             The name or IP address of the
                                          host on which the node resides

The 'node_id' column shows the node ID used in the 'config.ini' file for
this node; if none is specified, the node ID that would be assigned
automatically to this node is displayed.

The 'node_type' column displays one of the following three values:

   * 'MGM': Management node.

   * 'NDB': Data node.

   * 'API': API node; this includes SQL nodes.

The 'node_hostname' column shows the node host as specified in the
'config.ini' file.  This can be empty for an API node, if 'HostName' has
not been set in the cluster configuration file.  If 'HostName' has not
been set for a data node in the configuration file, 'localhost' is used
here.  'localhost' is also used if 'HostName' has not been specified for
a management node.

The 'config_nodes' table was added in NDB 7.5.7 and NDB 7.6.2.

21.5.10.8 The ndbinfo config_params Table
.........................................

The 'config_params' table is a static table which provides the names and
internal ID numbers of and other information about NDB Cluster
configuration parameters.

The following table provides information about the columns in the
'config_params' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.  This table can also be used in
conjunction with the 'config_values'
table for obtaining realtime
information about node configuration parameters.

*Columns of the config_params table*

Column Name            Type               Description

'param_number'         integer            The parameter's internal ID
                                          number

'param_name'           string             The name of the parameter

'param_description'    string             A brief description of the
                                          parameter

'param_type'           string             The parameter's data type

'param_default'        string             The parameter's default value,
                                          if any

'param_min'            string             The parameter's maximum value,
                                          if any

'param_max'            string             The parameter's minimum value,
                                          if any

'param_mandatory'      integer            This is 1 if the parameter is
                                          required, otherwise 0

'param_status'         string             Currently unused

In NDB Cluster 7.5 (and later), this table is read-only.  The
'param_description', 'param_type', 'param_default', 'param_min',
'param_max', 'param_mandatory', and 'param_status' columns were all
added in NDB 7.5.0.

Although this is a static table, its content can vary between NDB
Cluster installations, since supported parameters can vary due to
differences between software releases, cluster hardware configurations,
and other factors.

21.5.10.9 The ndbinfo config_values Table
.........................................

The 'config_values' table, implemented in NDB 7.5.0, provides
information about the current state of node configuration parameter
values.  Each row in the table corresponds to the current value of a
parameter on a given node.

*Columns of the config_params table*

Column Name            Type               Description

'node_id'              integer            ID of the node in the cluster

'config_param'         integer            The parameter's internal ID
                                          number

'config_value'         string             Current value of the parameter

This table's 'config_param' column and the 'config_params'
table's 'param_number' column use
the same parameter identifiers.  By joining the two tables on these
columns, you can obtain detailed information about desired node
configuration parameters.  The query shown here provides the current
values for all parameters on each data node in the cluster, ordered by
node ID and parameter name:

     SELECT    v.node_id AS 'Node Id',
               p.param_name AS 'Parameter',
               v.config_value AS 'Value'
     FROM      config_values v
     JOIN      config_params p
     ON        v.config_param=p.param_number
     WHERE     p.param_name NOT LIKE '\_\_%'
     ORDER BY  v.node_id, p.param_name;

Partial output from the previous query when run on a small example
cluster used for simple testing:

     +---------+------------------------------------------+----------------+
     | Node Id | Parameter                                | Value          |
     +---------+------------------------------------------+----------------+
     |       2 | Arbitration                              | 1              |
     |       2 | ArbitrationTimeout                       | 7500           |
     |       2 | BackupDataBufferSize                     | 16777216       |
     |       2 | BackupDataDir                            | /home/jon/data |
     |       2 | BackupDiskWriteSpeedPct                  | 50             |
     |       2 | BackupLogBufferSize                      | 16777216       |

     ...

     |       3 | TotalSendBufferMemory                    | 0              |
     |       3 | TransactionBufferMemory                  | 1048576        |
     |       3 | TransactionDeadlockDetectionTimeout      | 1200           |
     |       3 | TransactionInactiveTimeout               | 4294967039     |
     |       3 | TwoPassInitialNodeRestartCopy            | 0              |
     |       3 | UndoDataBuffer                           | 16777216       |
     |       3 | UndoIndexBuffer                          | 2097152        |
     +---------+------------------------------------------+----------------+
     248 rows in set (0.02 sec)

The 'WHERE' clause filters out parameters whose names begin with a
double underscore ('__'); these parameters are reserved for testing and
other internal uses by the NDB developers, and are not intended for use
in a production NDB Cluster.

You can obtain output that is more specific, more detailed, or both by
issuing the proper queries.  This example provides all types of
available information about the 'NodeId', 'NoOfReplicas', 'HostName',
'DataMemory', 'IndexMemory', and 'TotalSendBufferMemory' parameters as
currently set for all data nodes in the cluster:

     SELECT  p.param_name AS Name,
             v.node_id AS Node,
             p.param_type AS Type,
             p.param_default AS 'Default',
             p.param_min AS Minimum,
             p.param_max AS Maximum,
             CASE p.param_mandatory WHEN 1 THEN 'Y' ELSE 'N' END AS 'Required',
             v.config_value AS Current
     FROM    config_params p
     JOIN    config_values v
     ON      p.param_number = v.config_param
     WHERE   p. param_name
       IN ('NodeId', 'NoOfReplicas', 'HostName',
           'DataMemory', 'IndexMemory', 'TotalSendBufferMemory')\G

The output from this query when run on a small NDB Cluster with 2 data
nodes used for simple testing is shown here:

     *************************** 1. row ***************************
         Name: NodeId
         Node: 2
         Type: unsigned
      Default:
      Minimum: 1
      Maximum: 48
     Required: Y
      Current: 2
     *************************** 2. row ***************************
         Name: HostName
         Node: 2
         Type: string
      Default: localhost
      Minimum:
      Maximum:
     Required: N
      Current: 127.0.0.1
     *************************** 3. row ***************************
         Name: TotalSendBufferMemory
         Node: 2
         Type: unsigned
      Default: 0
      Minimum: 262144
      Maximum: 4294967039
     Required: N
      Current: 0
     *************************** 4. row ***************************
         Name: NoOfReplicas
         Node: 2
         Type: unsigned
      Default: 2
      Minimum: 1
      Maximum: 4
     Required: N
      Current: 2
     *************************** 5. row ***************************
         Name: DataMemory
         Node: 2
         Type: unsigned
      Default: 102760448
      Minimum: 1048576
      Maximum: 1099511627776
     Required: N
      Current: 524288000
     *************************** 6. row ***************************
         Name: NodeId
         Node: 3
         Type: unsigned
      Default:
      Minimum: 1
      Maximum: 48
     Required: Y
      Current: 3
     *************************** 7. row ***************************
         Name: HostName
         Node: 3
         Type: string
      Default: localhost
      Minimum:
      Maximum:
     Required: N
      Current: 127.0.0.1
     *************************** 8. row ***************************
         Name: TotalSendBufferMemory
         Node: 3
         Type: unsigned
      Default: 0
      Minimum: 262144
      Maximum: 4294967039
     Required: N
      Current: 0
     *************************** 9. row ***************************
         Name: NoOfReplicas
         Node: 3
         Type: unsigned
      Default: 2
      Minimum: 1
      Maximum: 4
     Required: N
      Current: 2
     *************************** 10. row ***************************
         Name: DataMemory
         Node: 3
         Type: unsigned
      Default: 102760448
      Minimum: 1048576
      Maximum: 1099511627776
     Required: N
      Current: 524288000
     10 rows in set (0.01 sec)

21.5.10.10 The ndbinfo counters Table
.....................................

The 'counters' table provides running totals of events such as reads and
writes for specific kernel blocks and data nodes.  Counts are kept from
the most recent node start or restart; a node start or restart resets
all counters on that node.  Not all kernel blocks have all types of
counters.

The following table provides information about the columns in the
'counters' table.  For each column, the table shows the name, data type,
and a brief description.  Additional information can be found in the
notes following the table.

*Columns of the counters table*

Column Name            Type               Description

'node_id'              integer            The data node ID

'block_name'           string             Name of the associated NDB
                                          kernel block (see NDB Kernel
                                          Blocks
                                          (http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks.html)).

'block_instance'       integer            Block instance

'counter_id'           integer            The counter's internal ID
                                          number; normally an integer
                                          between 1 and 10, inclusive.

'counter_name'         string             The name of the counter.  See
                                          text for names of individual
                                          counters and the NDB kernel
                                          block with which each counter
                                          is associated.

'val'                  integer            The counter's value

Each counter is associated with a particular NDB kernel block.

The 'OPERATIONS' counter is associated with the 'DBLQH' (local query
handler) kernel block (see The DBLQH Block
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks-dblqh.html)).
A primary-key read counts as one operation, as does a primary-key
update.  For reads, there is one operation in 'DBLQH' per operation in
'DBTC'.  For writes, there is one operation counted per replica.

The 'ATTRINFO', 'TRANSACTIONS', 'COMMITS', 'READS', 'LOCAL_READS',
'SIMPLE_READS', 'WRITES', 'LOCAL_WRITES', 'ABORTS', 'TABLE_SCANS', and
'RANGE_SCANS' counters are associated with the DBTC (transaction
co-ordinator) kernel block (see The DBTC Block
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks-dbtc.html)).

'LOCAL_WRITES' and 'LOCAL_READS' are primary-key operations using a
transaction coordinator in a node that also holds the primary replica of
the record.

The 'READS' counter includes all reads.  'LOCAL_READS' includes only
those reads of the primary replica on the same node as this transaction
coordinator.  'SIMPLE_READS' includes only those reads in which the read
operation is the beginning and ending operation for a given transaction.
Simple reads do not hold locks but are part of a transaction, in that
they observe uncommitted changes made by the transaction containing them
but not of any other uncommitted transactions.  Such reads are 'simple'
from the point of view of the TC block; since they hold no locks they
are not durable, and once 'DBTC' has routed them to the relevant LQH
block, it holds no state for them.

'ATTRINFO' keeps a count of the number of times an interpreted program
is sent to the data node.  See NDB Protocol Messages
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndb-protocol-messages.html),
for more information about 'ATTRINFO' messages in the 'NDB' kernel.

The 'LOCAL_TABLE_SCANS_SENT', 'READS_RECEIVED',
'PRUNED_RANGE_SCANS_RECEIVED', 'RANGE_SCANS_RECEIVED',
'LOCAL_READS_SENT', 'CONST_PRUNED_RANGE_SCANS_RECEIVED',
'LOCAL_RANGE_SCANS_SENT', 'REMOTE_READS_SENT',
'REMOTE_RANGE_SCANS_SENT', 'READS_NOT_FOUND', 'SCAN_BATCHES_RETURNED',
'TABLE_SCANS_RECEIVED', and 'SCAN_ROWS_RETURNED' counters are associated
with the 'DBSPJ' (select push-down join) kernel block (see The DBSPJ
Block
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks-dbspj.html)).

The 'block_name' and 'block_instance' columns provide, respectively, the
applicable NDB kernel block name and instance number.  You can use these
to obtain information about specific threads from the
'threadblocks' table.

A number of counters provide information about transporter overload and
send buffer sizing when troubleshooting such issues.  For each LQH
instance, there is one instance of each counter in the following list:

   * 'LQHKEY_OVERLOAD': Number of primary key requests rejected at the
     LQH block instance due to transporter overload

   * 'LQHKEY_OVERLOAD_TC': Count of instances of 'LQHKEY_OVERLOAD' where
     the TC node transporter was overloaded

   * 'LQHKEY_OVERLOAD_READER': Count of instances of 'LQHKEY_OVERLOAD'
     where the API reader (reads only) node was overloaded.

   * 'LQHKEY_OVERLOAD_NODE_PEER': Count of instances of
     'LQHKEY_OVERLOAD' where the next backup data node (writes only) was
     overloaded

   * 'LQHKEY_OVERLOAD_SUBSCRIBER': Count of instances of
     'LQHKEY_OVERLOAD' where a event subscriber (writes only) was
     overloaded.

   * 'LQHSCAN_SLOWDOWNS': Count of instances where a fragment scan batch
     size was reduced due to scanning API transporter overload.

21.5.10.11 The ndbinfo cpustat Table
....................................

The 'cpustat' table provides per-thread CPU statistics gathered each
second, for each thread running in the 'NDB' kernel.

The following table provides information about the columns in the
'cpustat' table.  For each column, the table shows the name, data type,
and a brief description.  Additional information can be found in the
notes following the table.

*Columns of the cpustat table*

Column Name            Type               Description

'node_id'              integer            ID of the node where the
                                          thread is running

'thr_no'               integer            Thread ID (specific to this
                                          node)

'OS_user'              integer            OS user time

'OS_system'            integer            OS system time

'OS_idle'              integer            OS idle time

'thread_exec'          integer            Thread execution time

'thread_sleeping'      integer            Thread sleep time

'thread_send'          integer            Thread send time

'thread_buffer_full'   integer            Thread buffer full time

'elapsed_time'         integer            Elapsed time

This table was added in NDB 7.5.2.

21.5.10.12 The ndbinfo cpustat_50ms Table
.........................................

The 'cpustat_50ms' table provides raw, per-thread CPU data obtained each
50 milliseconds for each thread running in the 'NDB' kernel.

Like 'cpustat_1sec' and
'cpustat_20sec', this table shows
20 measurement sets per thread, each referencing a period of the named
duration.  Thus, 'cpsustat_50ms' provides 1 second of history.

The following table provides information about the columns in the
'cpustat_50ms' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the cpustat_50ms table*

Column Name            Type               Description

'node_id'              integer            ID of the node where the
                                          thread is running

'thr_no'               integer            Thread ID (specific to this
                                          node)

'OS_user_time'         integer            OS user time

'OS_system_time'       integer            OS system time

'OS_idle_time'         integer            OS idle time

'exec_time'            integer            Thread execution time

'sleep_time'           integer            Thread sleep time

'send_time'            integer            Thread send time

'buffer_full_time'     integer            Thread buffer full time

'elapsed_time'         integer            Elapsed time

This table was added in NDB 7.5.2.

21.5.10.13 The ndbinfo cpustat_1sec Table
.........................................

The 'cpustat-1sec' table provides raw, per-thread CPU data obtained each
second for each thread running in the 'NDB' kernel.

Like 'cpustat_50ms' and
'cpustat_20sec', this table shows
20 measurement sets per thread, each referencing a period of the named
duration.  Thus, 'cpsustat_1sec' provides 20 seconds of history.

The following table provides information about the columns in the
'cpustat_1sec' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the cpustat_1sec table*

Column Name            Type               Description

'node_id'              integer            ID of the node where the
                                          thread is running

'thr_no'               integer            Thread ID (specific to this
                                          node)

'OS_user_time'         integer            OS user time

'OS_system_time'       integer            OS system time

'OS_idle_time'         integer            OS idle time

'exec_time'            integer            Thread execution time

'sleep_time'           integer            Thread sleep time

'send_time'            integer            Thread send time

'buffer_full_time'     integer            Thread buffer full time

'elapsed_time'         integer            Elapsed time

This table was added in NDB 7.5.2.

21.5.10.14 The ndbinfo cpustat_20sec Table
..........................................

The 'cpustat_20sec' table provides raw, per-thread CPU data obtained
each 20 seconds, for each thread running in the 'NDB' kernel.

Like 'cpustat_50ms' and
'cpustat_1sec', this table shows 20
measurement sets per thread, each referencing a period of the named
duration.  Thus, 'cpsustat_20sec' provides 400 seconds of history.

The following table provides information about the columns in the
'cpustat_20sec' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the cpustat_20sec table*

Column Name            Type               Description

'node_id'              integer            ID of the node where the
                                          thread is running

'thr_no'               integer            Thread ID (specific to this
                                          node)

'OS_user_time'         integer            OS user time

'OS_system_time'       integer            OS system time

'OS_idle_time'         integer            OS idle time

'exec_time'            integer            Thread execution time

'sleep_time'           integer            Thread sleep time

'send_time'            integer            Thread send time

'buffer_full_time'     integer            Thread buffer full time

'elapsed_time'         integer            Elapsed time

This table was added in NDB 7.5.2.

21.5.10.15 The ndbinfo dict_obj_info Table
..........................................

The 'dict_obj_info' table provides information about 'NDB' data
dictionary ('DICT') objects such as tables and indexes.  (The
'dict_obj_types' table can be
queried for a list of all the types.)  This information includes the
object's type, state, parent object (if any), and fully qualified name.

The following table provides information about the columns in the
'dict_obj_info' table.  For each column, the table shows the name, data
type, and a brief description.

*Columns of the dict_obj_info table*

Column Name            Type               Description

'type'                 integer            Type of 'DICT' object; join on
                                          See 'dict_obj_types'.
                                          to obtain the name

'id'                   integer            Object identifier

'version'              integer            Object version

'state'                integer            Object state

'parent_obj_type'      integer            Parent object's type (a
                                          'dict_obj_types' type ID); 0
                                          indicates that the object has
                                          no parent

'parent_obj_id'        integer            Parent object ID (such as a
                                          base table); 0 indicates that
                                          the object has no parent

'fq_name'              string             Fully qualified object name;
                                          for a table, this has the form
                                          'DATABASE_NAME/def/TABLE_NAME',
                                          for a primary key, the form is
                                          'sys/def/TABLE_ID/PRIMARY',
                                          and for a unique key it is
                                          'sys/def/TABLE_ID/UK_NAME$unique'

This table was added in NDB 7.5.4.

21.5.10.16 The ndbinfo dict_obj_types Table
...........................................

The 'dict_obj_types' table is a static table listing possible dictionary
object types used in the NDB kernel.  These are the same types defined
by 'Object::Type'
(http://dev.mysql.com/doc/ndbapi/en/ndb-object-type.html) in the NDB
API.

The following table provides information about the columns in the
'dict_obj_types' table.  For each column, the table shows the name, data
type, and a brief description.

*Columns of the dict_obj_types table*

Column Name            Type               Description

'type_id'              integer            The type ID for this type

'type_name'            string             The name of this type

21.5.10.17 The ndbinfo disk_write_speed_base Table
..................................................

The 'disk_write_speed_base' table provides base information about the
speed of disk writes during LCP, backup, and restore operations.

The following table provides information about the columns in the
'disk_write_speed_base' table.  For each column, the table shows the
name, data type, and a brief description.  Additional information can be
found in the notes following the table.

*Columns of the disk_write_speed_base table*

Column Name            Type               Description

node_id                integer            Node ID of this node

thr_no                 integer            Thread ID of this LDM thread

millis_ago             integer            Milliseconds since this
                                          reporting period ended

millis_passed          integer            Milliseconds elapsed in this
                                          reporting period

backup_lcp_bytes_writteninteger           Number of bytes written to
                                          disk by local checkpoints and
                                          backup processes during this
                                          period

redo_bytes_written     integer            Number of bytes written to
                                          REDO log during this period

target_disk_write_speedinteger            Actual speed of disk writes
                                          per LDM thread (base data)

21.5.10.18 The ndbinfo disk_write_speed_aggregate Table
.......................................................

The 'disk_write_speed_aggregate' table provides aggregated information
about the speed of disk writes during LCP, backup, and restore
operations.

The following table provides information about the columns in the
'disk_write_speed_aggregate' table.  For each column, the table shows
the name, data type, and a brief description.  Additional information
can be found in the notes following the table.

*Columns in the disk_write_speed_aggregate table*

Column Name            Type               Description

node_id                integer            Node ID of this node

thr_no                 integer            Thread ID of this LDM thread

backup_lcp_speed_last_secinteger          Number of bytes written to
                                          disk by backup and LCP
                                          processes in the last second

redo_speed_last_sec    integer            Number of bytes written to
                                          REDO log in the last second

backup_lcp_speed_last_10secinteger        Number of bytes written to
                                          disk by backup and LCP
                                          processes per second, averaged
                                          over the last 10 seconds

redo_speed_last_10sec  integer            Number of bytes written to
                                          REDO log per second, averaged
                                          over the last 10 seconds

std_dev_backup_lcp_speed_last_10secintegerStandard deviation in number
                                          of bytes written to disk by
                                          backup and LCP processes per
                                          second, averaged over the last
                                          10 seconds

std_dev_redo_speed_last_10secinteger      Standard deviation in number
                                          of bytes written to REDO log
                                          per second, averaged over the
                                          last 10 seconds

backup_lcp_speed_last_60secinteger        Number of bytes written to
                                          disk by backup and LCP
                                          processes per second, averaged
                                          over the last 60 seconds

redo_speed_last_60sec  integer            Number of bytes written to
                                          REDO log per second, averaged
                                          over the last 10 seconds

std_dev_backup_lcp_speed_last_60secintegerStandard deviation in number
                                          of bytes written to disk by
                                          backup and LCP processes per
                                          second, averaged over the last
                                          60 seconds

std_dev_redo_speed_last_60secinteger      Standard deviation in number
                                          of bytes written to REDO log
                                          per second, averaged over the
                                          last 60 seconds

slowdowns_due_to_io_laginteger            Number of seconds since last
                                          node start that disk writes
                                          were slowed due to REDO log
                                          I/O lag

slowdowns_due_to_high_cpuinteger          Number of seconds since last
                                          node start that disk writes
                                          were slowed due to high CPU
                                          usage

disk_write_speed_set_to_mininteger        Number of seconds since last
                                          node start that disk write
                                          speed was set to minimum

current_target_disk_write_speedinteger    Actual speed of disk writes
                                          per LDM thread (aggregated)

21.5.10.19 The ndbinfo disk_write_speed_aggregate_node Table
............................................................

The 'disk_write_speed_aggregate_node' table provides aggregated
information per node about the speed of disk writes during LCP, backup,
and restore operations.

The following table provides information about the columns in the
'disk_write_speed_aggregate_node' table.  For each column, the table
shows the name, data type, and a brief description.  Additional
information can be found in the notes following the table.

*Columns of the disk_write_speed_aggregate_node table*

Column Name            Type               Description

node_id                integer            Node ID of this node

backup_lcp_speed_last_secinteger          Number of bytes written to
                                          disk by backup and LCP
                                          processes in the last second

redo_speed_last_sec    integer            Number of bytes written to
                                          REDO log in the last second

backup_lcp_speed_last_10secinteger        Number of bytes written to
                                          disk by backup and LCP
                                          processes per second, averaged
                                          over the last 10 seconds

redo_speed_last_10sec  integer            Number of bytes written to
                                          REDO log per second, averaged
                                          over the last 10 seconds

backup_lcp_speed_last_60secinteger        Number of bytes written to
                                          disk by backup and LCP
                                          processes per second, averaged
                                          over the last 60 seconds

redo_speed_last_60sec  integer            Number of bytes written to
                                          disk by backup and LCP
                                          processes per second, averaged
                                          over the last 60 seconds

21.5.10.20 The ndbinfo diskpagebuffer Table
...........................................

The 'diskpagebuffer' table provides statistics about disk page buffer
usage by NDB Cluster Disk Data tables.

The following table provides information about the columns in the
'diskpagebuffer' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the diskpagebuffer table*

Column Name            Type               Description

'node_id'              integer            The data node ID

'block_instance'       integer            Block instance

'pages_written'        integer            Number of pages written to
                                          disk.

'pages_written_lcp'    integer            Number of pages written by
                                          local checkpoints.

'pages_read'           integer            Number of pages read from disk

'log_waits'            integer            Number of page writes waiting
                                          for log to be written to disk

'page_requests_direct_return'integer      Number of requests for pages
                                          that were available in buffer

'page_requests_wait_queue'integer         Number of requests that had to
                                          wait for pages to become
                                          available in buffer

'page_requests_wait_io'integer            Number of requests that had to
                                          be read from pages on disk
                                          (pages were unavailable in
                                          buffer)

You can use this table with NDB Cluster Disk Data tables to determine
whether 'DiskPageBufferMemory' is sufficiently large to allow data to be
read from the buffer rather from disk; minimizing disk seeks can help
improve performance of such tables.

You can determine the proportion of reads from 'DiskPageBufferMemory' to
the total number of reads using a query such as this one, which obtains
this ratio as a percentage:

     SELECT
       node_id,
       100 * page_requests_direct_return /
         (page_requests_direct_return + page_requests_wait_io)
           AS hit_ratio
     FROM ndbinfo.diskpagebuffer;

The result from this query should be similar to what is shown here, with
one row for each data node in the cluster (in this example, the cluster
has 4 data nodes):

     +---------+-----------+
     | node_id | hit_ratio |
     +---------+-----------+
     |       5 |   97.6744 |
     |       6 |   97.6879 |
     |       7 |   98.1776 |
     |       8 |   98.1343 |
     +---------+-----------+
     4 rows in set (0.00 sec)

'hit_ratio' values approaching 100% indicate that only a very small
number of reads are being made from disk rather than from the buffer,
which means that Disk Data read performance is approaching an optimum
level.  If any of these values are less than 95%, this is a strong
indicator that the setting for 'DiskPageBufferMemory' needs to be
increased in the 'config.ini' file.

*Note*:

A change in 'DiskPageBufferMemory' requires a rolling restart of all of
the cluster's data nodes before it takes effect.

'block_instance' refers to an instance of a kernel block.  Together with
the block name, this number can be used to look up a given instance in
the 'threadblocks' table.
Using this information, you can obtain information about disk page
buffer metrics relating to individual threads; an example query using
'LIMIT 1' to limit the output to a single thread is shown here:

     mysql> SELECT
          >   node_id, thr_no, block_name, thread_name, pages_written,
          >   pages_written_lcp, pages_read, log_waits,
          >   page_requests_direct_return, page_requests_wait_queue,
          >   page_requests_wait_io
          > FROM ndbinfo.diskpagebuffer
          >   INNER JOIN ndbinfo.threadblocks USING (node_id, block_instance)
          >   INNER JOIN ndbinfo.threads USING (node_id, thr_no)
          > WHERE block_name = 'PGMAN' LIMIT 1\G
     *************************** 1. row ***************************
                         node_id: 1
                          thr_no: 1
                      block_name: PGMAN
                     thread_name: rep
                   pages_written: 0
               pages_written_lcp: 0
                      pages_read: 1
                       log_waits: 0
     page_requests_direct_return: 4
        page_requests_wait_queue: 0
           page_requests_wait_io: 1
     1 row in set (0.01 sec)

21.5.10.21 The ndbinfo error_messages Table
...........................................

The 'error_messages' table provides information about

The following table provides information about the columns in the
'error_messages' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the error_messages table*

Column Name            Type               Description

'error_code'           integer            Numeric error code

'error_description'    string             Description of error

'error_status'         string             Error status code

'error_classification' integer            Error classification code

'error_code' is a numeric NDB error code.  This is the same error code
that can be supplied to 'ndb_perror'
or 'perror'. '--ndb'.

'error_description' provides a basic description of the condition
causing the error.

The 'error_status' column provides status information relating to the
error.  Possible values for this column are listed here:

   * 'No error'

   * 'Illegal connect string'

   * 'Illegal server handle'

   * 'Illegal reply from server'

   * 'Illegal number of nodes'

   * 'Illegal node status'

   * 'Out of memory'

   * 'Management server not connected'

   * 'Could not connect to socket'

   * 'Start failed'

   * 'Stop failed'

   * 'Restart failed'

   * 'Could not start backup'

   * 'Could not abort backup'

   * 'Could not enter single user mode'

   * 'Could not exit single user mode'

   * 'Failed to complete configuration change'

   * 'Failed to get configuration'

   * 'Usage error'

   * 'Success'

   * 'Permanent error'

   * 'Temporary error'

   * 'Unknown result'

   * 'Temporary error, restart node'

   * 'Permanent error, external action needed'

   * 'Ndbd file system error, restart node initial'

   * 'Unknown'

The error_classification column shows the error classification.  See NDB
Error Classifications
(http://dev.mysql.com/doc/ndbapi/en/ndb-error-classifications.html), for
information about classification codes and their meanings.

The 'error_messages' table was added in NDB 7.6.4.

21.5.10.22 The ndbinfo locks_per_fragment Table
...............................................

The 'locks_per_fragment' table provides information about counts of lock
claim requests, and the outcomes of these requests on a per-fragment
basis, serving as a companion table to 'operations_per_fragment'
and
'memory_per_fragment'.  This
table also shows the total time spent waiting for locks successfully and
unsuccessfully since fragment or table creation, or since the most
recent restart.

The following table provides information about the columns in the
'locks_per_fragment' table.  For each column, the table shows the name,
data type, and a brief description.  Additional information can be found
in the notes following the table.

*Columns of the locks_per_fragment table*

Column Name            Type               Description

'fq_name'              string             Fully qualified table name

'parent_fq_name'       string             Fully qualified name of parent
                                          object

'type'                 string             Table type; see text for
                                          possible values

'table_id'             integer            Table ID

'node_id'              integer            Reporting node ID

'block_instance'       integer            LDM instance ID

'fragment_num'         integer            Fragment identifier

'ex_req'               integer            Exclusive lock requests
                                          started

'ex_imm_ok'            integer            Exclusive lock requests
                                          immediately granted

'ex_wait_ok'           integer            Exclusive lock requests
                                          granted following wait

'ex_wait_fail'         integer            Exclusive lock requests not
                                          granted

'sh_req'               integer            Shared lock requests started

'sh_imm_ok'            integer            Shared lock requests
                                          immediately granted

'sh_wait_ok'           integer            Shared lock requests granted
                                          following wait

'sh_wait_fail'         integer            Shared lock requests not
                                          granted

'wait_ok_millis'       integer            Time spent waiting for lock
                                          requests that were granted, in
                                          milliseconds

'wait_fail_millis'     integer            Time spent waiting for lock
                                          requests that failed, in
                                          milliseconds

'block_instance' refers to an instance of a kernel block.  Together with
the block name, this number can be used to look up a given instance in
the 'threadblocks' table.

'fq_name' is a fully qualified database object name in
DATABASE/SCHEMA/NAME format, such as 'test/def/t1' or
'sys/def/10/b$unique'.

'parent_fq_name' is the fully qualified name of this object's parent
object (table).

'table_id' is the table's internal ID generated by 'NDB'.  This is the
same internal table ID shown in other 'ndbinfo' tables; it is also
visible in the output of 'ndb_show_tables'.

The 'type' column shows the type of table.  This is always one of
'System table', 'User table', 'Unique hash index', 'Hash index', 'Unique
ordered index', 'Ordered index', 'Hash index trigger', 'Subscription
trigger', 'Read only constraint', 'Index trigger', 'Reorganize trigger',
'Tablespace', 'Log file group', 'Data file', 'Undo file', 'Hash map',
'Foreign key definition', 'Foreign key parent trigger', 'Foreign key
child trigger', or 'Schema transaction'.

The values shown in all of the columns 'ex_req', 'ex_req_imm_ok',
'ex_wait_ok', 'ex_wait_fail', 'sh_req', 'sh_req_imm_ok', 'sh_wait_ok',
and 'sh_wait_fail' represent cumulative numbers of requests since the
table or fragment was created, or since the last restart of this node,
whichever of these occurred later.  This is also true for the time
values shown in the 'wait_ok_millis' and 'wait_fail_millis' columns.

Every lock request is considered either to be in progress, or to have
completed in some way (that is, to have succeeded or failed).  This
means that the following relationships are true:

     ex_req >= (ex_req_imm_ok + ex_wait_ok + ex_wait_fail)

     sh_req >= (sh_req_imm_ok + sh_wait_ok + sh_wait_fail)

The number of requests currently in progress is the current number of
incomplete requests, which can be found as shown here:

     [exclusive lock requests in progress] =
         ex_req - (ex_req_imm_ok + ex_wait_ok + ex_wait_fail)

     [shared lock requests in progress] =
         sh_req - (sh_req_imm_ok + sh_wait_ok + sh_wait_fail)

A failed wait indicates an aborted transaction, but the abort may or may
not be caused by a lock wait timeout.  You can obtain the total number
of aborts while waiting for locks as shown here:

     [aborts while waiting for locks] = ex_wait_fail + sh_wait_fail

The 'locks_per_fragment' table was added in NDB 7.5.3.

21.5.10.23 The ndbinfo logbuffers Table
.......................................

The 'logbuffer' table provides information on NDB Cluster log buffer
usage.

The following table provides information about the columns in the
'logbuffers' table.  For each column, the table shows the name, data
type, and a brief description.

*Columns in the logbuffers table*

Column Name            Type               Description

'node_id'              integer            The ID of this data node.

'log_type'             string             Type of log.  Prior to NDB
                                          7.6.5, one of: 'REDO' or
                                          'DD-UNDO'.  In NDB 7.6.5 or
                                          later, one of: 'REDO',
                                          'DD-UNDO', 'BACKUP-DATA', or
                                          'BACKUP-LOG'.

'log_id'               integer            The log ID.

'log_part'             integer            The log part number.

'total'                integer            Total space available for this
                                          log.

'used'                 integer            Space used by this log.

Beginning with NDB 7.6.5, 'logbuffers' table rows reflecting two
additional log types are available when performing an NDB backup.  One
of these rows has the log type 'BACKUP-DATA', which shows the amount of
data buffer used during backup to copy fragments to backup files.  The
other row has the log type 'BACKUP-LOG', which displays the amount of
log buffer used during the backup to record changes made after the
backup has started.  One each of these 'log_type' rows is shown in the
'logbuffers' table for each data node in the cluster.  These rows are
not present unless an NDB backup is currently being performed.  (Bug
#25822988)

21.5.10.24 The ndbinfo logspaces Table
......................................

This table provides information about NDB Cluster log space usage.

The following table provides information about the columns in the
'logspaces' table.  For each column, the table shows the name, data
type, and a brief description.

*Columns in the logspaces table*

Column Name            Type               Description

'node_id'              integer            The ID of this data node.

'log_type'             string             Type of log; one of: 'REDO' or
                                          'DD-UNDO'.

'log_id'               integer            The log ID.

'log_part'             integer            The log part number.

'total'                integer            Total space available for this
                                          log.

'used'                 integer            Space used by this log.

21.5.10.25 The ndbinfo membership Table
.......................................

The 'membership' table describes the view that each data node has of all
the others in the cluster, including node group membership, president
node, arbitrator, arbitrator successor, arbitrator connection states,
and other information.

The following table provides information about the columns in the
'membership' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the membership table*

Column Name            Type               Description

'node_id'              integer            This node's node ID

'group_id'             integer            Node group to which this node
                                          belongs

'left node'            integer            Node ID of the previous node

'right_node'           integer            Node ID of the next node

'president'            integer            President's node ID

'successor'            integer            Node ID of successor to
                                          president

'succession_order'     integer            Order in which this node
                                          succeeds to presidency

'Conf_HB_order'        integer            -

'arbitrator'           integer            Node ID of arbitrator

'arb_ticket'           string             Internal identifier used to
                                          track arbitration

'arb_state'            Enumeration (see   Arbitration state
                       text)

'arb_connected'        'Yes' or 'No'      Whether this node is connected
                                          to the arbitrator

'connected_rank1_arbs' List of node IDs   Connected arbitrators of rank
                                          1

'connected_rank2_arbs' List of node IDs   Connected arbitrators of rank
                                          1

The node ID and node group ID are the same as reported by 'ndb_mgm -e "SHOW"'.

'left_node' and 'right_node' are defined in terms of a model that
connects all data nodes in a circle, in order of their node IDs, similar
to the ordering of the numbers on a clock dial, as shown here:

FIGURE GOES HERE: Circular Arrangement of NDB Cluster Nodes

In this example, we have 8 data nodes, numbered 5, 6, 7, 8, 12, 13, 14,
and 15, ordered clockwise in a circle.  We determine 'left' and 'right'
from the interior of the circle.  The node to the left of node 5 is node
15, and the node to the right of node 5 is node 6.  You can see all
these relationships by running the following query and observing the
output:

     mysql> SELECT node_id,left_node,right_node
         -> FROM ndbinfo.membership;
     +---------+-----------+------------+
     | node_id | left_node | right_node |
     +---------+-----------+------------+
     |       5 |        15 |          6 |
     |       6 |         5 |          7 |
     |       7 |         6 |          8 |
     |       8 |         7 |         12 |
     |      12 |         8 |         13 |
     |      13 |        12 |         14 |
     |      14 |        13 |         15 |
     |      15 |        14 |          5 |
     +---------+-----------+------------+
     8 rows in set (0.00 sec)

The designations 'left' and 'right' are used in the event log in the
same way.

The 'president' node is the node viewed by the current node as
responsible for setting an arbitrator (see NDB Cluster Start Phases
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-start-phases.html)).
If the president fails or becomes disconnected, the current node expects
the node whose ID is shown in the 'successor' column to become the new
president.  The 'succession_order' column shows the place in the
succession queue that the current node views itself as having.

In a normal NDB Cluster, all data nodes should see the same node as
'president', and the same node (other than the president) as its
'successor'.  In addition, the current president should see itself as
'1' in the order of succession, the 'successor' node should see itself
as '2', and so on.

All nodes should show the same 'arb_ticket' values as well as the same
'arb_state' values.  Possible 'arb_state' values are 'ARBIT_NULL',
'ARBIT_INIT', 'ARBIT_FIND', 'ARBIT_PREP1', 'ARBIT_PREP2', 'ARBIT_START',
'ARBIT_RUN', 'ARBIT_CHOOSE', 'ARBIT_CRASH', and 'UNKNOWN'.

'arb_connected' shows whether this node is connected to the node shown
as this node's 'arbitrator'.

The 'connected_rank1_arbs' and 'connected_rank2_arbs' columns each
display a list of 0 or more arbitrators having an 'ArbitrationRank'
equal to 1, or to 2, respectively.

*Note*:

Both management nodes and API nodes are eligible to become arbitrators.

21.5.10.26 The ndbinfo memoryusage Table
........................................

Querying this table provides information similar to that provided by the
'ALL REPORT MemoryUsage' command in the 'ndb_mgm'
client, or logged by 'ALL DUMP 1000'
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-dump-commands.html).

The following table provides information about the columns in the
'memoryusage' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the memoryusage table*

Column Name            Type               Description

'node_id'              integer            The node ID of this data node.

'memory_type'          string             One of 'Data memory', 'Index
                                          memory', or 'Long message
                                          buffer'.

'used'                 integer            Number of bytes currently used
                                          for data memory or index
                                          memory by this data node.

'used_pages'           integer            Number of pages currently used
                                          for data memory or index
                                          memory by this data node; see
                                          text.

'total'                integer            Total number of bytes of data
                                          memory or index memory
                                          available for this data node;
                                          see text.

'total_pages'          integer            Total number of memory pages
                                          available for data memory or
                                          index memory on this data
                                          node; see text.

The 'total' column represents the total amount of memory in bytes
available for the given resource (data memory or index memory) on a
particular data node.  This number should be approximately equal to the
setting of the corresponding configuration parameter in the 'config.ini'
file.

Suppose that the cluster has 2 data nodes having node IDs '5' and '6',
and the 'config.ini' file contains the following:

     [ndbd default]
     DataMemory = 1G
     IndexMemory = 1G

Suppose also that the value of the 'LongMessageBuffer' configuration
parameter is allowed to assume its default (64 MB).

The following query shows approximately the same values:

     mysql> SELECT node_id, memory_type, total
          > FROM ndbinfo.memoryusage;
     +---------+---------------------+------------+
     | node_id | memory_type         | total      |
     +---------+---------------------+------------+
     |       5 | Data memory         | 1073741824 |
     |       5 | Index memory        | 1074003968 |
     |       5 | Long message buffer |   67108864 |
     |       6 | Data memory         | 1073741824 |
     |       6 | Index memory        | 1074003968 |
     |       6 | Long message buffer |   67108864 |
     +---------+---------------------+------------+
     6 rows in set (0.00 sec)

In this case, the 'total' column values for index memory are slightly
higher than the value set of 'IndexMemory' due to internal rounding.

For the 'used_pages' and 'total_pages' columns, resources are measured
in pages, which are 32K in size for 'DataMemory' and 8K for
'IndexMemory'.  For long message buffer memory, the page size is 256
bytes.

21.5.10.27 The ndbinfo memory_per_fragment Table
................................................

The 'memory_per_fragment' table provides information about the usage of
memory by individual fragments.

The following table provides information about the columns in the
'memory_per_fragment' table.  For each column, the table shows the name,
data type, and a brief description.  Additional information can be found
in the notes following the table.

*Columns of the memory_per_fragment table*

Column Name            Type               Description

fq_name                string             Name of this fragment

parent_fq_name         string             Name of this fragment's parent

type                   string             Type of object; see text for
                                          possible values

table_id               integer            Table ID for this table

node_id                integer            Node ID for this node

block_instance         integer            Kernel block instance ID

fragment_num           integer            Fragment ID (number)

fixed_elem_alloc_bytes integer            Number of bytes allocated for
                                          fixed-sized elements

fixed_elem_free_bytes  integer            Free bytes remaining in pages
                                          allocated to fixed-size
                                          elements

fixed_elem_size_bytes  integer            Length of each fixed-size
                                          element in bytes

fixed_elem_count       integer            Number of fixed-size elements

fixed_elem_free_count  decimal            Number of free rows for
                                          fixed-size elements

var_elem_alloc_bytes   integer            Number of bytes allocated for
                                          variable-size elements

var_elem_free_bytes    integer            Free bytes remaining in pages
                                          allocated to variable-size
                                          elements

var_elem_count         integer            Number of variable-size
                                          elements

hash_index_alloc_bytes integer            Number of bytes allocated to
                                          hash indexes

The 'type' column from this table shows the dictionary object type used
for this fragment ('Object::Type'
(http://dev.mysql.com/doc/ndbapi/en/ndb-object-type.html), in the NDB
API), and can take any one of the values shown in the following list:

   * System table

   * User table

   * Unique hash index

   * Hash index

   * Unique ordered index

   * Ordered index

   * Hash index trigger

   * Subscription trigger

   * Read only constraint

   * Index trigger

   * Reorganize trigger

   * Tablespace

   * Log file group

   * Data file

   * Undo file

   * Hash map

   * Foreign key definition

   * Foreign key parent trigger

   * Foreign key child trigger

   * Schema transaction

You can also obtain this list by executing 'SELECT * FROM'.
'ndbinfo.dict_obj_types'
in the 'mysql'.
client.

The 'block_instance' column provides the NDB kernel block instance
number.  You can use this to obtain information about specific threads
from the 'threadblocks'.
table.

21.5.10.28 The ndbinfo nodes Table
..................................

This table contains information on the status of data nodes.  For each
data node that is running in the cluster, a corresponding row in this
table provides the node's node ID, status, and uptime.  For nodes that
are starting, it also shows the current start phase.

The following table provides information about the columns in the
'nodes' table.  For each column, the table shows the name, data type,
and a brief description.  Additional information can be found in the
notes following the table.

*Columns of the nodes table*

Column Name            Type               Description

'node_id'              integer            The data node's unique node ID
                                          in the cluster.

'uptime'               integer            Time since the node was last
                                          started, in seconds.

'status'               string             Current status of the data
                                          node; see text for possible
                                          values.

'start_phase'          integer            If the data node is starting,
                                          the current start phase.

'config_generation'    integer            The version of the cluster
                                          configuration file in use on
                                          this data node.

The 'uptime' column shows the time in seconds that this node has been
running since it was last started or restarted.  This is a
'BIGINT' value.  This figure includes the time actually
needed to start the node; in other words, this counter starts running
the moment that 'ndbd' or
'ndbmtd' is first invoked; thus, even
for a node that has not yet finished starting, 'uptime' may show a
nonzero value.

The 'status' column shows the node's current status.  This is one of:
'NOTHING', 'CMVMI', 'STARTING', 'STARTED', 'SINGLEUSER', 'STOPPING_1',
'STOPPING_2', 'STOPPING_3', or 'STOPPING_4'.  When the status is
'STARTING', you can see the current start phase in the 'start_phase'
column (see later in this section).  'SINGLEUSER' is displayed in the
'status' column for all data nodes when the cluster is in single user
mode (see mysql-cluster-single-user-mode).  Seeing one of the
'STOPPING' states does not necessarily mean that the node is shutting
down but can mean rather that it is entering a new state; for example,
if you put the cluster in single user mode, you can sometimes see data
nodes report their state briefly as 'STOPPING_2' before the status
changes to 'SINGLEUSER'.

The 'start_phase' column uses the same range of values as those used in
the output of the 'ndb_mgm'.
client 'NODE_ID STATUS' command (see
mysql-cluster-mgm-client-commands).  If the node is not currently
starting, then this column shows '0'.  For a listing of NDB Cluster
start phases with descriptions, see mysql-cluster-start-phases.

The 'config_generation' column shows which version of the cluster
configuration is in effect on each data node.  This can be useful when
performing a rolling restart of the cluster in order to make changes in
configuration parameters.  For example, from the output of the following
'SELECT' statement, you can see that node 3 is not yet
using the latest version of the cluster configuration ('6') although
nodes 1, 2, and 4 are doing so:

     mysql> USE ndbinfo;
     Database changed
     mysql> SELECT * FROM nodes;
     +---------+--------+---------+-------------+-------------------+
     | node_id | uptime | status  | start_phase | config_generation |
     +---------+--------+---------+-------------+-------------------+
     |       1 |  10462 | STARTED |           0 |                 6 |
     |       2 |  10460 | STARTED |           0 |                 6 |
     |       3 |  10457 | STARTED |           0 |                 5 |
     |       4 |  10455 | STARTED |           0 |                 6 |
     +---------+--------+---------+-------------+-------------------+
     2 rows in set (0.04 sec)

Therefore, for the case just shown, you should restart node 3 to
complete the rolling restart of the cluster.

Nodes that are stopped are not accounted for in this table.  Suppose
that you have an NDB Cluster with 4 data nodes (node IDs 1, 2, 3 and 4),
and all nodes are running normally, then this table contains 4 rows, 1
for each data node:

     mysql> USE ndbinfo;
     Database changed
     mysql> SELECT * FROM nodes;
     +---------+--------+---------+-------------+-------------------+
     | node_id | uptime | status  | start_phase | config_generation |
     +---------+--------+---------+-------------+-------------------+
     |       1 |  11776 | STARTED |           0 |                 6 |
     |       2 |  11774 | STARTED |           0 |                 6 |
     |       3 |  11771 | STARTED |           0 |                 6 |
     |       4 |  11769 | STARTED |           0 |                 6 |
     +---------+--------+---------+-------------+-------------------+
     4 rows in set (0.04 sec)

If you shut down one of the nodes, only the nodes that are still running
are represented in the output of this 'SELECT' statement,
as shown here:

     ndb_mgm> 2 STOP
     Node 2: Node shutdown initiated
     Node 2: Node shutdown completed.
     Node 2 has shutdown.

     mysql> SELECT * FROM nodes;
     +---------+--------+---------+-------------+-------------------+
     | node_id | uptime | status  | start_phase | config_generation |
     +---------+--------+---------+-------------+-------------------+
     |       1 |  11807 | STARTED |           0 |                 6 |
     |       3 |  11802 | STARTED |           0 |                 6 |
     |       4 |  11800 | STARTED |           0 |                 6 |
     +---------+--------+---------+-------------+-------------------+
     3 rows in set (0.02 sec)

21.5.10.29 The ndbinfo operations_per_fragment Table
....................................................

The 'operations_per_fragment' table provides information about the
operations performed on individual fragments and fragment replicas, as
well as about some of the results from these operations.

The following table provides information about the columns in the
'operations_per_fragment' table.  For each column, the table shows the
name, data type, and a brief description.  Additional information can be
found in the notes following the table.

*Columns of the operations_per_fragment table*

Column Name            Type               Description

fq_name                string             Name of this fragment

parent_fq_name         string             Name of this fragment's parent

type                   string             Type of object; see text for
                                          possible values

table_id               integer            Table ID for this table

node_id                integer            Node ID for this node

block_instance         integer            Kernel block instance ID

fragment_num           integer            Fragment ID (number)

tot_key_reads          integer            Total number of key reads for
                                          this fragment replica

tot_key_inserts        integer            Total number of key inserts
                                          for this fragment replica

tot_key_updates        integer            total number of key updates
                                          for this fragment replica

tot_key_writes         integer            Total number of key writes for
                                          this fragment replica

tot_key_deletes        integer            Total number of key deletes
                                          for this fragment replica

tot_key_refs           integer            Number of key operations
                                          refused

tot_key_attrinfo_bytes integer            Total size of all 'attrinfo'
                                          attributes

tot_key_keyinfo_bytes  integer            Total size of all 'keyinfo'
                                          attributes

tot_key_prog_bytes     integer            Total size of all interpreted
                                          programs carried by 'attrinfo'
                                          attributes

tot_key_inst_exec      integer            Total number of instructions
                                          executed by interpreted
                                          programs for key operations

tot_key_bytes_returned integer            Total size of all data and
                                          metadata returned from key
                                          read operations

tot_frag_scans         integer            Total number of scans
                                          performed on this fragment
                                          replica

tot_scan_rows_examined integer            Total number of rows examined
                                          by scans

tot_scan_rows_returned integer            Total number of rows returned
                                          to client

tot_scan_bytes_returnedinteger            Total size of data and
                                          metadata returned to the
                                          client

tot_scan_prog_bytes    integer            Total size of interpreted
                                          programs for scan operations

tot_scan_bound_bytes   integer            Total size of all bounds used
                                          in ordered index scans

tot_scan_inst_exec     integer            Total number of instructions
                                          executed for scans

tot_qd_frag_scans      integer            Number of times that scans of
                                          this fragment replica have
                                          been queued

conc_frag_scans        integer            Number of scans currently
                                          active on this fragment
                                          replica (excluding queued
                                          scans)

conc_qd_frag_scans     integer            Number of scans currently
                                          queued for this fragment
                                          replica

tot_commits            integer            Total number of row changes
                                          committed to this fragment
                                          replica

The 'fq_name' contains the fully qualified name of the schema object to
which this fragment replica belongs.  This currently has the following
formats:

   * Base table: - 'DBNAME/def/TBLNAME'

   * 'BLOB' table: - 'DBNAME/def/NDB$BLOB_BASETBLID_COLNO'

   * Ordered index: - 'sys/def/BASETBLID/INDEXNAME'

   * Unique index: - 'sys/def/BASETBLID/INDEXNAME$unique'

The '$unique' suffix shown for unique indexes is added by
'mysqld'.; for an index created by a different NDB API client
application, this may differ, or not be present.

The syntax just shown for fully qualified object names is an internal
interface which is subject to change in future releases.

Consider a table 't1' created and modified by the following SQL
statements:

     CREATE DATABASE mydb;

     USE mydb;

     CREATE TABLE t1 (
       a INT NOT NULL,
       b INT NOT NULL,
       t TEXT NOT NULL,
       PRIMARY KEY (b)
     ) ENGINE=ndbcluster;

     CREATE UNIQUE INDEX ix1 ON t1(b) USING HASH;

If 't1' is assigned table ID 11, this yields the 'fq_name' values shown
here:

   * Base table: 'mydb/def/t1'

   * 'BLOB' table: 'mydb/def/NDB$BLOB_11_2'

   * Ordered index (primary key): 'sys/def/11/PRIMARY'

   * Unique index: 'sys/def/11/ix1$unique'

For indexes or 'BLOB' tables, the 'parent_fq_name' column contains the
'fq_name' of the corresponding base table.  For base tables, this column
is always 'NULL'.

The 'type' column shows the schema object type used for this fragment,
which can take any one of the values 'System table', 'User table',
'Unique hash index', or 'Ordered index'.  'BLOB' tables are shown as
'User table'.

The 'table_id' column value is unique at any given time, but can be
reused if the corresponding object has been deleted.  The same ID can be
seen using the 'ndb_show_tables'
utility.

The 'block_instance' column shows which LDM instance this fragment
replica belongs to.  You can use this to obtain information about
specific threads from the 'threadblocks'
table.  The first such instance is
always numbered 0.

Since there are typically two replicas, and assuming that this is so,
each 'fragment_num' value should appear twice in the table, on two
different data nodes from the same node group.

Since 'NDB' does not use single-key access for ordered indexes, the
counts for 'tot_key_reads', 'tot_key_inserts', 'tot_key_updates',
'tot_key_writes', and 'tot_key_deletes' are not incremented by ordered
index operations.

*Note*:

When using 'tot_key_writes', you should keep in mind that a write
operation in this context updates the row if the key exists, and inserts
a new row otherwise.  (One use of this is in the 'NDB' implementation of
the 'REPLACE'. SQL statement.)

The 'tot_key_refs' column shows the number of key operations refused by
the LDM. Generally, such a refusal is due to duplicate keys (inserts),
'Key not found' errors (updates, deletes, and reads), or the operation
was rejected by an interpreted program used as a predicate on the row
matching the key.

The 'attrinfo' and 'keyinfo' attributes counted by the
'tot_key_attrinfo_bytes' and 'tot_key_keyinfo_bytes' columns are
attributes of an 'LQHKEYREQ' signal (see The NDB Communication Protocol
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-ndb-protocol.html))
used to initiate a key operation by the LDM. An 'attrinfo' typically
contains tuple field values (inserts and updates) or projection
specifications (for reads); 'keyinfo' contains the primary or unique key
needed to locate a given tuple in this schema object.

The value shown by 'tot_frag_scans' includes both full scans (that
examine every row) and scans of subsets.  Unique indexes and 'BLOB'
tables are never scanned, so this value, like other scan-related counts,
is 0 for fragment replicas of these.

'tot_scan_rows_examined' may display less than the total number of rows
in a given fragment replica, since ordered index scans can limited by
bounds.  In addition, a client may choose to end a scan before all
potentially matching rows have been examined; this occurs when using an
SQL statement containing a 'LIMIT' or 'EXISTS' clause, for example.
'tot_scan_rows_returned' is always less than or equal to
'tot_scan_rows_examined'.

'tot_scan_bytes_returned' includes, in the case of pushed joins,
projections returned to the 'DBSPJ' block in the NDB kernel.

'tot_qd_frag_scans' can be effected by the setting for the
'MaxParallelScansPerFragment' data node configuration parameter, which
limits the number of scans that may execute concurrently on a single
fragment replica.

21.5.10.30 The ndbinfo processes Table
......................................

This table contains information about NDB Cluster node processes; each
node is represented by the row in the table.  Only nodes that are
connected to the cluster are shown in this table.  You can obtain
information about nodes that are configured but not connected to the
cluster from the 'nodes' and
'config_nodes' tables.

The following table provides information about the columns in the
'processes' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the nodes table*

Column Name            Type               Description

'node_id'              integer            The node's unique node ID in
                                          the cluster

'node_type'            string             Type of node (management,
                                          data, or API node; see text)

'node_version'         string             Version of the 'NDB' software
                                          program running on this node.

'process_id'           integer            This node's process ID

'angel_process_id'     integer            Process ID of this node's
                                          angel process

'process_name'         string             Name of the executable

'service_URI'          string             Service URI of this node (see
                                          text)

'node_id' is the ID assigned to this node in the cluster.

The 'node_type' column displays one of the following three values:

   * 'MGM': Management node.

   * 'NDB': Data node.

   * 'API': API or SQL node.

For an executable shipped with the NDB Cluster distribution,
'node_version' shows the two-part MySQL NDB Cluster version string, such
as '5.7.22-ndb-7.5.11' or '5.7.22-ndb-7.6.5', that it was compiled with.
See mysql-cluster-version-strings, for more information.

'process_id' is the node executable's process ID as shown by the host
operating system using a process display application such as 'top' on
Linux, or the Task Manager on Windows platforms.

'angel_process_id' is the system process ID for the node's angel
process, which ensures that a data node or SQL is automatically
restarted in cases of failures.  For management nodes and API nodes
other than SQL nodes, the value of this column is 'NULL'.

The 'process_name' column shows the name of the running executable.  For
management nodes, this is 'ndb_mgmd'.  For data nodes, this is 'ndbd'
(single-threaded) or 'ndbmtd' (multi-threaded).  For SQL nodes, this is
'mysqld'.  For other types of API nodes, it is the name of the
executable program connected to the cluster; NDB API applications can
set a custom value for this using 'Ndb_cluster_connection::set_name()'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection-set-name.html).

'service_URI' shows the service network address.  For management nodes
and data nodes, the scheme used is 'ndb://'.  For SQL nodes, this is
'mysql://'.  By default, API nodes other than SQL nodes use 'ndb://' for
the scheme; NDB API applications can set this to a custom value using
'Ndb_cluster_connection::set_service_uri()'.  regardless of the node
type, the scheme is followed by the IP address used by the NDB
transporter for the node in question.  For management nodes and SQL
nodes, this address includes the port number (usually 1186 for
management nodes and 3306 for SQL nodes).  If the SQL node was started
with '--bind-address', this address is used instead of the transporter
address, unless the bind address is set to '*', '0.0.0.0', or '::'.

Additional path information may be included in the 'service_URI' value
for an SQL node reflecting various configuration options; for example,
'mysql://198.51.100.3/tmp/mysql.sock' indicates that the SQL node was
started with '--skip-networking', and
'mysql://198.51.100.3:3306/?server-id=1' shows that replication is
enabled for this SQL node.

The 'processes' table was added in NDB 7.5.7 and NDB 7.6.2.

21.5.10.31 The ndbinfo resources Table
......................................

This table provides information about data node resource availability
and usage.

These resources are sometimes known as _super-pools_.

The following table provides information about the columns in the
'resources' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the resources table*

Column Name            Type               Description

'node_id'              integer            The unique node ID of this
                                          data node.

'resource_name'        string             Name of the resource; see
                                          text.

'reserved'             integer            The amount reserved for this
                                          resource.

'used'                 integer            The amount actually used by
                                          this resource.

'max'                  integer            The maximum amount of this
                                          resource used, since the node
                                          was last started.

The 'resource_name' can be one of the names shown in the following
table:

*ndbinfo.resources table resource names and descriptions*

Resource name      Description

'RESERVED'         Reserved by the system; cannot be overridden.

'DISK_OPERATIONS'  If a log file group is allocated, the size of the
                   undo log buffer is used to set the size of this
                   resource.  This resource is used only to allocate
                   the undo log buffer for an undo log file group;
                   there can only be one such group.  Overallocation
                   occurs as needed by 'CREATE LOGFILE GROUP'.

'DISK_RECORDS'     Records allocated for Disk Data operations.

'DATA_MEMORY'      Used for main memory tuples, indexes, and hash
                   indexes.  Sum of DataMemory and IndexMemory, plus 8
                   pages of 32 KB each if IndexMemory has been set.
                   Cannot be overallocated.

'JOBBUFFER'        Used for allocating job buffers by the NDB
                   scheduler; cannot be overallocated.  This is
                   approximately 2 MB per thread plus a 1 MB buffer in
                   both directions for all threads that can
                   communicate.  For large configurations this consume
                   several GB.

'FILE_BUFFERS'     Used by the redo log handler in the 'DBLQH' kernel
                   block; cannot be overallocated.  Size is
                   'NoOfFragmentLogParts' * 'RedoBuffer', plus 1 MB per
                   log file part.

'TRANSPORTER_BUFFERS'Used for send buffers by 'ndbmtd'.;
                   the sum of
                   'TotalSendBufferMemory' and 'ExtraSendBufferMemory'.
                   This resource that can be overallocated by up to 25
                   percent.  'TotalSendBufferMemory' is calculated by
                   summing the send buffer memory per node, the default
                   value of which is 2 MB. Thus, in a system having
                   four data nodes and eight API nodes, the data nodes
                   have 12 * 2 MB send buffer memory.
                   'ExtraSendBufferMemory' is used by 'ndbmtd'
                   and amounts to 2 MB
                   extra memory per thread.  Thus, with 4 LDM threads,
                   2 TC threads, 1 main thread, 1 replication thread,
                   and 2 receive threads, 'ExtraSendBufferMemory' is 10
                   * 2 MB. Overallocation of this resource can be
                   performed by setting the 'SharedGlobalMemory' data
                   node configuration parameter.

'DISK_PAGE_BUFFER' Used for the disk page buffer; determined by the
                   'DiskPageBufferMemory' configuration parameter.
                   Cannot be overallocated.

'QUERY_MEMORY'     Used by the 'DBSPJ' kernel block.

'SCHEMA_TRANS_MEMORY'Minimum is 2 MB; can be overallocated to use any
                   remaining available memory.

21.5.10.32 The ndbinfo restart_info Table
.........................................

The 'restart_info' table contains information about node restart
operations.  Each entry in the table corresponds to a node restart
status report in real time from a data node with the given node ID. Only
the most recent report for any given node is shown.

The following table provides information about the columns in the
'restart_info' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the restart_info table*

Column Name            Type               Description

'node_id'              integer            Node ID in the cluster

'node_restart_status'  VARCHAR(256)       Node status; see text for
                                          values.  Each of these
                                          corresponds to a possible
                                          value of
                                          'node_restart_status_int'.

'node_restart_status_int'integer          Node status code; see text for
                                          values.

'secs_to_complete_node_failure'integer    Time in seconds to complete
                                          node failure handling

'secs_to_allocate_node_id'integer         Time in seconds from node
                                          failure completion to
                                          allocation of node ID

'secs_to_include_in_heartbeat_protocol'integerTime in seconds from
                                          allocation of node ID to
                                          inclusion in heartbeat
                                          protocol

'secs_until_wait_for_ndbcntr_master'integerTime in seconds from being
                                          included in heartbeat protocol
                                          until waiting for 'NDBCNTR'
                                          master began

'secs_wait_for_ndbcntr_master'integer     Time in seconds spent waiting
                                          to be accepted by 'NDBCNTR'
                                          master for starting

'secs_to_get_start_permitted'integer      Time in seconds elapsed from
                                          receiving of permission for
                                          start from master until all
                                          nodes have accepted start of
                                          this node

'secs_to_wait_for_lcp_for_copy_meta_data'integerTime in seconds spent waiting
                                          for LCP completion before
                                          copying meta data

'secs_to_copy_meta_data'integer           Time in seconds required to
                                          copy metadata from master to
                                          newly starting node

'secs_to_include_node' integer            Time in seconds waited for GCP
                                          and inclusion of all nodes
                                          into protocols

'secs_starting_node_to_request_local_recovery'integerTime in seconds that the node
                                          just starting spent waiting to
                                          request local recovery

'secs_for_local_recovery'integer          Time in seconds required for
                                          local recovery by node just
                                          starting

'secs_restore_fragments'integer           Time in seconds required to
                                          restore fragments from LCP
                                          files

'secs_undo_disk_data'  integer            Time in seconds required to
                                          execute undo log on disk data
                                          part of records

'secs_exec_redo_log'   integer            Time in seconds required to
                                          execute redo log on all
                                          restored fragments

'secs_index_rebuild'   integer            Time in seconds required to
                                          rebuild indexes on restored
                                          fragments

'secs_to_synchronize_starting_node'integerTime in seconds required to
                                          synchronize starting node from
                                          live nodes

'secs_wait_lcp_for_restart'integer        Time in seconds required for
                                          LCP start and completion
                                          before restart was completed

'secs_wait_subscription_handover'integer  Time in seconds spent waiting
                                          for handover of replication
                                          subscriptions

'total_restart_secs'   integer            Total number of seconds from
                                          node failure until node is
                                          started again

Defined values for 'node_restart_status_int' and corresponding status
names and messages ('node_restart_status') are shown in the following
table:

*Status codes and messages used in the restart_info table*

Column Name            Type               Description

0                      'ALLOCATED_NODE_ID''Allocated node id'

1                      'INCLUDED_IN_HB_PROTOCOL''Included in heartbeat
                                          protocol'

2                      'NDBCNTR_START_WAIT''Wait for NDBCNTR master to
                                          permit us to start'

3                      'NDBCNTR_STARTED'  'NDBCNTR master permitted us
                                          to start'

4                      'START_PERMITTED'  'All nodes permitted us to
                                          start'

5                      'WAIT_LCP_TO_COPY_DICT''Wait for LCP completion to
                                          start copying metadata'

6                      'COPY_DICT_TO_STARTING_NODE''Copying metadata to starting
                                          node'

7                      'INCLUDE_NODE_IN_LCP_AND_GCP''Include node in LCP and GCP
                                          protocols'

8                      'LOCAL_RECOVERY_STARTED''Restore fragments ongoing'

9                      'COPY_FRAGMENTS_STARTED''Synchronizing starting node
                                          with live nodes'

10                     'WAIT_LCP_FOR_RESTART''Wait for LCP to ensure
                                          durability'

11                     'WAIT_SUMA_HANDOVER''Wait for handover of
                                          subscriptions'

12                     'RESTART_COMPLETED''Restart completed'

13                     'NODE_FAILED'      'Node failed, failure handling
                                          in progress'

14                     'NODE_FAILURE_COMPLETED''Node failure handling
                                          completed'

15                     'NODE_GETTING_PERMIT''All nodes permitted us to
                                          start'

16                     'NODE_GETTING_INCLUDED''Include node in LCP and GCP
                                          protocols'

17                     'NODE_GETTING_SYNCHED''Synchronizing starting node
                                          with live nodes'

18                     'NODE_GETTING_LCP_WAITED'[none]

19                     'NODE_ACTIVE'      'Restart completed'

20                     'NOT_DEFINED_IN_CLUSTER'[none]

21                     'NODE_NOT_RESTARTED_YET''Initial state'

Status numbers 0 through 12 apply on master nodes only; the remainder of
those shown in the table apply to all restarting data nodes.  Status
numbers 13 and 14 define node failure states; 20 and 21 occur when no
information about the restart of a given node is available.

See also mysql-cluster-start-phases.

21.5.10.33 The ndbinfo server_locks Table
.........................................

The 'server_locks' table is similar in structure to the 'cluster_locks'
table, and provides a subset of the information found in the latter
table, but which is specific to the SQL node (MySQL server) where it
resides.  (The 'cluster_locks' table provides information about all
locks in the cluster.)  More precisely, 'server_locks' contains
information about locks requested by threads belonging to the current
'mysqld' instance, and serves as a companion table to
'server_operations'.
This may be useful for correlating locking patterns with specific MySQL
user sessions, queries, or use cases.

The following table provides information about the columns in the
'server_locks' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the server_locks table*

Column Name            Type               Description

'mysql_connection_id'  integer            MySQL connection ID

'node_id'              integer            ID of reporting node

'block_instance'       integer            ID of reporting LDM instance

'tableid'              integer            ID of table containing this
                                          row

'fragmentid'           integer            ID of fragment containing
                                          locked row

'rowid'                integer            ID of locked row

'transid'              integer            Transaction ID

'mode'                 string             Lock request mode

'state'                string             Lock state

'detail'               string             Whether this is first holding
                                          lock in row lock queue

'op'                   string             Operation type

'duration_millis'      integer            Milliseconds spent waiting or
                                          holding lock

'lock_num'             integer            ID of lock object

'waiting_for'          integer            Waiting for lock with this ID

The 'mysql_connection_id' column shows the MySQL connection or thread ID
as shown by 'SHOW PROCESSLIST'.

'block_instance' refers to an instance of a kernel block.  Together with
the block name, this number can be used to look up a given instance in
the 'threadblocks' table.

The 'tableid' is assigned to the table by 'NDB'; the same ID is used for
this table in other 'ndbinfo' tables, as well as in the output of
'ndb_show_tables'.

The transaction ID shown in the 'transid' column is the identifier
generated by the NDB API for the transaction requesting or holding the
current lock.

The 'mode' column shows the lock mode, which is always one of 'S'
(shared lock) or 'X' (exclusive lock).  If a transaction has an
exclusive lock on a given row, all other locks on that row have the same
transaction ID.

The 'state' column shows the lock state.  Its value is always one of 'H'
(holding) or 'W' (waiting).  A waiting lock request waits for a lock
held by a different transaction.

The 'detail' column indicates whether this lock is the first holding
lock in the affected row's lock queue, in which case it contains a '*'
(asterisk character); otherwise, this column is empty.  This information
can be used to help identify the unique entries in a list of lock
requests.

The 'op' column shows the type of operation requesting the lock.  This
is always one of the values 'READ', 'INSERT', 'UPDATE', 'DELETE',
'SCAN', or 'REFRESH'.

The 'duration_millis' column shows the number of milliseconds for which
this lock request has been waiting or holding the lock.  This is reset
to 0 when a lock is granted for a waiting request.

The lock ID ('lockid' column) is unique to this node and block instance.

If the 'lock_state' column's value is 'W', this lock is waiting to be
granted, and the 'waiting_for' column shows the lock ID of the lock
object this request is waiting for.  Otherwise, 'waiting_for' is empty.
'waiting_for' can refer only to locks on the same row (as identified by
'node_id', 'block_instance', 'tableid', 'fragmentid', and 'rowid').

The 'server_locks' table was added in NDB 7.5.3.

21.5.10.34 The ndbinfo server_operations Table
..............................................

The 'server_operations' table contains entries for all ongoing
'NDB' operations that the current SQL node (MySQL
Server) is currently involved in.  It effectively is a subset of the
'cluster_operations'.
table, in which operations for other SQL and API nodes are not shown.

The following table provides information about the columns in the
'server_operations' table.  For each column, the table shows the name,
data type, and a brief description.  Additional information can be found
in the notes following the table.

*Columns of the server_operations table*

Column Name            Type               Description

'mysql_connection_id'  integer            MySQL Server connection ID

'node_id'              integer            Node ID

'block_instance'       integer            Block instance

'transid'              integer            Transaction ID

'operation_type'       string             Operation type (see text for
                                          possible values)

'state'                string             Operation state (see text for
                                          possible values)

'tableid'              integer            Table ID

'fragmentid'           integer            Fragment ID

'client_node_id'       integer            Client node ID

'client_block_ref'     integer            Client block reference

'tc_node_id'           integer            Transaction coordinator node
                                          ID

'tc_block_no'          integer            Transaction coordinator block
                                          number

'tc_block_instance'    integer            Transaction coordinator block
                                          instance

The 'mysql_connection_id' is the same as the connection or session ID
shown in the output of 'SHOW PROCESSLIST'.  It
is obtained from the 'INFORMATION_SCHEMA' table
'NDB_TRANSID_MYSQL_CONNECTION_MAP'.

'block_instance' refers to an instance of a kernel block.  Together with
the block name, this number can be used to look up a given instance in
the 'threadblocks' table.

The transaction ID ('transid') is a unique 64-bit number which can be
obtained using the NDB API's 'getTransactionId()'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-gettransactionid.html)
method.  (Currently, the MySQL Server does not expose the NDB API
transaction ID of an ongoing transaction.)

The 'operation_type' column can take any one of the values 'READ',
'READ-SH', 'READ-EX', 'INSERT', 'UPDATE', 'DELETE', 'WRITE', 'UNLOCK',
'REFRESH', 'SCAN', 'SCAN-SH', 'SCAN-EX', or '<unknown>'.

The 'state' column can have any one of the values 'ABORT_QUEUED',
'ABORT_STOPPED', 'COMMITTED', 'COMMIT_QUEUED', 'COMMIT_STOPPED',
'COPY_CLOSE_STOPPED', 'COPY_FIRST_STOPPED', 'COPY_STOPPED',
'COPY_TUPKEY', 'IDLE', 'LOG_ABORT_QUEUED', 'LOG_COMMIT_QUEUED',
'LOG_COMMIT_QUEUED_WAIT_SIGNAL', 'LOG_COMMIT_WRITTEN',
'LOG_COMMIT_WRITTEN_WAIT_SIGNAL', 'LOG_QUEUED', 'PREPARED',
'PREPARED_RECEIVED_COMMIT', 'SCAN_CHECK_STOPPED', 'SCAN_CLOSE_STOPPED',
'SCAN_FIRST_STOPPED', 'SCAN_RELEASE_STOPPED', 'SCAN_STATE_USED',
'SCAN_STOPPED', 'SCAN_TUPKEY', 'STOPPED', 'TC_NOT_CONNECTED',
'WAIT_ACC', 'WAIT_ACC_ABORT', 'WAIT_AI_AFTER_ABORT', 'WAIT_ATTR',
'WAIT_SCAN_AI', 'WAIT_TUP', 'WAIT_TUPKEYINFO', 'WAIT_TUP_COMMIT', or
'WAIT_TUP_TO_ABORT'.  (If the MySQL Server is running with
'ndbinfo_show_hidden' enabled, you can view this list of states by
selecting from the 'ndb$dblqh_tcconnect_state' table, which is normally
hidden.)

You can obtain the name of an 'NDB' table from its table ID by checking
the output of 'ndb_show_tables'.

The 'fragid' is the same as the partition number seen in the output of
'ndb_desc'.
'--extra-partition-info' (short form '-p').

In 'client_node_id' and 'client_block_ref', 'client' refers to an NDB
Cluster API or SQL node (that is, an NDB API client or a MySQL Server
attached to the cluster).

The 'block_instance' and 'tc_block_instance' column provide NDB kernel
block instance numbers.  You can use these to obtain information about
specific threads from the 'threadblocks'
table.

21.5.10.35 The ndbinfo server_transactions Table
................................................

The 'server_transactions' table is subset of the
'cluster_transactions'.
table, but includes only those transactions in which the current SQL
node (MySQL Server) is a participant, while including the relevant
connection IDs.

The following table provides information about the columns in the
'server_transactions' table.  For each column, the table shows the name,
data type, and a brief description.  Additional information can be found
in the notes following the table.

*Columns of the server_transactions table*

Column Name            Type               Description

'mysql_connection_id'  integer            MySQL Server connection ID

'node_id'              integer            Transaction coordinator node
                                          ID

'block_instance'       integer            Transaction coordinator block
                                          instance

'transid'              integer            Transaction ID

'state'                string             Operation state (see text for
                                          possible values)

'count_operations'     integer            Number of stateful operations
                                          in the transaction

'outstanding_operations'integer           Operations still being
                                          executed by local data
                                          management layer (LQH blocks)

'inactive_seconds'     integer            Time spent waiting for API

'client_node_id'       integer            Client node ID

'client_block_ref'     integer            Client block reference

The 'mysql_connection_id' is the same as the connection or session ID
shown in the output of 'SHOW PROCESSLIST'.  It
is obtained from the 'INFORMATION_SCHEMA' table
'NDB_TRANSID_MYSQL_CONNECTION_MAP'.

'block_instance' refers to an instance of a kernel block.  Together with
the block name, this number can be used to look up a given instance in
the 'threadblocks' table.

The transaction ID ('transid') is a unique 64-bit number which can be
obtained using the NDB API's 'getTransactionId()'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-gettransactionid.html)
method.  (Currently, the MySQL Server does not expose the NDB API
transaction ID of an ongoing transaction.)

The 'state' column can have any one of the values 'CS_ABORTING',
'CS_COMMITTING', 'CS_COMMIT_SENT', 'CS_COMPLETE_SENT', 'CS_COMPLETING',
'CS_CONNECTED', 'CS_DISCONNECTED', 'CS_FAIL_ABORTED',
'CS_FAIL_ABORTING', 'CS_FAIL_COMMITTED', 'CS_FAIL_COMMITTING',
'CS_FAIL_COMPLETED', 'CS_FAIL_PREPARED', 'CS_PREPARE_TO_COMMIT',
'CS_RECEIVING', 'CS_REC_COMMITTING', 'CS_RESTART',
'CS_SEND_FIRE_TRIG_REQ', 'CS_STARTED', 'CS_START_COMMITTING',
'CS_START_SCAN', 'CS_WAIT_ABORT_CONF', 'CS_WAIT_COMMIT_CONF',
'CS_WAIT_COMPLETE_CONF', 'CS_WAIT_FIRE_TRIG_REQ'.  (If the MySQL Server
is running with 'ndbinfo_show_hidden' enabled, you can view this list of
states by selecting from the 'ndb$dbtc_apiconnect_state' table, which is
normally hidden.)

In 'client_node_id' and 'client_block_ref', 'client' refers to an NDB
Cluster API or SQL node (that is, an NDB API client or a MySQL Server
attached to the cluster).

The 'block_instance' column provides the 'DBTC' kernel block instance
number.  You can use this to obtain information about specific threads
from the 'threadblocks'.
table.

21.5.10.36 The ndbinfo table_distribution_status Table
......................................................

The 'table_distribution_status' table provides information about the
progress of table distribution for 'NDB' tables.

The following table provides information about the columns in
'table_distribution_status'.  For each column, the table shows the name,
data type, and a brief description.

*Columns of the table_distribution_status table*

Column Name            Type               Description

'node_id'              integer            Node id

'table_id'             integer            Table ID

'tab_copy_status'      string             Status of copying of table
                                          distribution data to disk; one
                                          of 'IDLE',
                                          'SR_PHASE1_READ_PAGES',
                                          'SR_PHASE2_READ_TABLE',
                                          'SR_PHASE3_COPY_TABLE',
                                          'REMOVE_NODE',
                                          'LCP_READ_TABLE',
                                          'COPY_TAB_REQ',
                                          'COPY_NODE_STATE',
                                          'ADD_TABLE_MASTER',
                                          'ADD_TABLE_SLAVE',
                                          'INVALIDATE_NODE_LCP',
                                          'ALTER_TABLE', 'COPY_TO_SAVE',
                                          or 'GET_TABINFO'

'tab_update_status'    string             Status of updating of table
                                          distribution data; one of
                                          'IDLE', 'LOCAL_CHECKPOINT',
                                          'LOCAL_CHECKPOINT_QUEUED',
                                          'REMOVE_NODE', 'COPY_TAB_REQ',
                                          'ADD_TABLE_MASTER',
                                          'ADD_TABLE_SLAVE',
                                          'INVALIDATE_NODE_LCP', or
                                          'CALLBACK'

'tab_lcp_status'       string             Status of table LCP; one of
                                          'ACTIVE' (waiting for local
                                          checkpoint to be performed),
                                          'WRITING_TO_FILE' (checkpoint
                                          performed but not yet written
                                          to disk), or 'COMPLETED'
                                          (checkpoint performed and
                                          persisted to disk)

'tab_status'           string             Table internal status; one of
                                          'ACTIVE' (table exists),
                                          'CREATING' (table is being
                                          created), or 'DROPPING' (table
                                          is being dropped)

'tab_storage'          string             Table recoverability; one of
                                          'NORMAL' (fully recoverable
                                          with redo logging and
                                          checkpointing), 'NOLOGGING'
                                          (recoverable from node crash,
                                          empty following cluster
                                          crash), or 'TEMPORARY' (not
                                          recoverable)

'tab_partitions'       integer            Number of partitions in table

'tab_fragments'        integer            Number of fragments in table;
                                          normally same as
                                          'tab_partitions'; for fully
                                          replicated tables equal to
                                          'tab_partitions * [number of
                                          node groups]'

'current_scan_count'   integer            Current number of active scans

'scan_count_wait'      integer            Current number of scans
                                          waiting to be performed before
                                          'ALTER TABLE' can complete.

'is_reorg_ongoing'     integer            Whether table is currently
                                          being reorganized (1 if true)

The 'table_distribution_status' table was added in NDB 7.5.4.

21.5.10.37 The ndbinfo table_fragments Table
............................................

The 'table_fragments' table provides information about the
fragmentation, partitioning, distribution, and (internal) replication of
'NDB' tables.

The following table provides information about the columns in
'table_fragments'.  For each column, the table shows the name, data
type, and a brief description.

*Columns of the table_fragments table*

Column Name            Type               Description

'node_id'              integer            Node ID ('DIH' master)

'table_id'             integer            Table ID

'partition_id'         integer            Partition ID

'fragment_id'          integer            Fragment ID (same as partition
                                          ID unless table is fully
                                          replicated)

'partition_order'      integer            Order of fragment in partition

'log_part_id'          integer            Log part ID of fragment

'no_of_replicas'       integer            Number of replicas

'current_primary'      integer            Current primary node ID

'preferred_primary'    integer            Preferred primary node ID

'current_first_backup' integer            Current first backup node ID

'current_second_backup'integer            Current second backup node ID

'current_third_backup' integer            Current third backup node ID

'num_alive_replicas'   integer            Current number of live
                                          replicas

'num_dead_replicas'    integer            Current number of dead
                                          replicas

'num_lcp_replicas'     integer            Number of replicas remaining
                                          to be checkpointed

The 'table_fragments' table was added in NDB 7.5.4.

21.5.10.38 The ndbinfo table_info Table
.......................................

The 'table_info' table provides information about logging,
checkpointing, distribution, and storage options in effect for
individual 'NDB' tables.

The following table provides information about the columns in
'table_info'.  For each column, the table shows the name, data type, and
a brief description.

*Columns of the table_info table*

Column Name            Type               Description

'table_id'             integer            Table ID

'logged_table'         integer            Whether table is logged (1) or
                                          not (0)

'row_contains_gci'     integer            Whether table rows contain GCI
                                          (1 true, 0 false)

'row_contains_checksum'integer            Whether table rows contain
                                          checksum (1 true, 0 false)

'read_backup'          integer            If backup replicas are read
                                          this is 1, otherwise 0

'fully_replicated'     integer            If table is fully replicated
                                          this is 1, otherwise 0

'storage_type'         string             Table storage type; one of
                                          'MEMORY' or 'DISK'

'hashmap_id'           integer            Hashmap ID

'partition_balance'    string             Partition balance (fragment
                                          count type) used for table;
                                          one of 'FOR_RP_BY_NODE',
                                          'FOR_RA_BY_NODE',
                                          'FOR_RP_BY_LDM', or
                                          'FOR_RA_BY_LDM'

'create_gci'           integer            GCI in which table was created

The 'table_info' table was added in NDB 7.5.4.

21.5.10.39 The ndbinfo table_replicas Table
...........................................

The 'table_replicas' table provides information about the copying,
distribution, and checkpointing of 'NDB' table fragments and fragment
replicas.

The following table provides information about the columns in
'table_replicas'.  For each column, the table shows the name, data type,
and a brief description.

*Columns of the table_replicas table*

Column Name            Type               Description

'node_id'              integer            ID of the node from which data
                                          is fetched ('DIH' master)

'table_id'             integer            Table ID

'fragment_id'          integer            Fragment ID

'initial_gci'          integer            Initial GCI for table

'replica_node_id'      integer            ID of node where replica is
                                          stored

'is_lcp_ongoing'       integer            Is 1 if LCP is ongoing on this
                                          fragment, 0 otherwise

'num_crashed_replicas' integer            Number of crashed replica
                                          instances

'last_max_gci_started' integer            Highest GCI started in most
                                          recent LCP

'last_max_gci_completed'integer           Highest GCI completed in most
                                          recent LCP

'last_lcp_id'          integer            ID of most recent LCP

'prev_lcp_id'          integer            ID of previous LCP

'prev_max_gci_started' integer            Highest GCI started in
                                          previous LCP

'prev_max_gci_completed'integer           Highest GCI completed in
                                          previous LCP

'last_create_gci'      integer            Last Create GCI of last
                                          crashed replica instance

'last_replica_gci'     integer            Last GCI of last crashed
                                          replica instance

'is_replica_alive'     integer            1 if this replica is alive, 0
                                          otherwise

The 'table_replicas' table was added in NDB 7.5.4.

21.5.10.40 The ndbinfo tc_time_track_stats Table
................................................

The 'tc_time_track_stats' table provides time-tracking information
obtained from the 'DBTC' block (TC) instances in the data nodes, through
API nodes access 'NDB'.  Each TC instance tracks latencies for a set of
activities it undertakes on behalf of API nodes or other data nodes;
these activities include transactions, transaction errors, key reads,
key writes, unique index operations, failed key operations of any type,
scans, failed scans, fragment scans, and failed fragment scans.

A set of counters is maintained for each activity, each counter covering
a range of latencies less than or equal to an upper bound.  At the
conclusion of each activity, its latency is determined and the
appropriate counter incremented.  'tc_time_track_stats' presents this
information as rows, with a row for each instance of the following:

   * Data node, using its ID

   * TC block instance

   * Other communicating data node or API node, using its ID

   * Upper bound value

Each row contains a value for each activity type.  This is the number of
times that this activity occurred with a latency within the range
specified by the row (that is, where the latency does not exceed the
upper bound).

The following table provides information about the columns in
'tc_time_track_stats'.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the tc_time_track_stats table*

Column Name            Type               Description

'node_id'              integer            Requesting node ID

'block_number'         integer            TC block number

'block_instance'       integer            TC block instance number

'comm_node_id'         integer            Node ID of communicating API
                                          or data node

'upper_bound'          integer            Upper bound of interval (in
                                          microseconds)

'scans'                integer            Based on duration of
                                          successful scans from opening
                                          to closing, tracked against
                                          the API or data nodes
                                          requesting them.

'scan_errors'          integer            Based on duration of failed
                                          scans from opening to closing,
                                          tracked against the API or
                                          data nodes requesting them.

'scan_fragments'       integer            Based on duration of
                                          successful fragment scans from
                                          opening to closing, tracked
                                          against the data nodes
                                          executing them

'scan_fragment_errors' integer            Based on duration of failed
                                          fragment scans from opening to
                                          closing, tracked against the
                                          data nodes executing them

'transactions'         integer            Based on duration of
                                          successful transactions from
                                          beginning until sending of
                                          commit 'ACK', tracked against
                                          the API or data nodes
                                          requesting them.  Stateless
                                          transactions are not included.

'transaction_errors'   integer            Based on duration of failing
                                          transactions from start to
                                          point of failure, tracked
                                          against the API or data nodes
                                          requesting them.

'read_key_ops'         integer            Based on duration of
                                          successful primary key reads
                                          with locks.  Tracked against
                                          both the API or data node
                                          requesting them and the data
                                          node executing them.

'write_key_ops'        integer            Based on duration of
                                          successful primary key writes,
                                          tracked against both the API
                                          or data node requesting them
                                          and the data node executing
                                          them.

'index_key_ops'        integer            Based on duration of
                                          successful unique index key
                                          operations, tracked against
                                          both the API or data node
                                          requesting them and the data
                                          node executing reads of base
                                          tables.

'key_op_errors'        integer            Based on duration of all
                                          unsuccessful key read or write
                                          operations, tracked against
                                          both the API or data node
                                          requesting them and the data
                                          node executing them.

The 'block_instance' column provides the 'DBTC' kernel block instance
number.  You can use this together with the block name to obtain
information about specific threads from the 'threadblocks'
table.

The 'tc_time_track_stats' table was added in NDB 4.7.9 (Bug #78533, Bug
#21889652).

21.5.10.41 The ndbinfo threadblocks Table
.........................................

The 'threadblocks' table associates data nodes, threads, and instances
of 'NDB' kernel blocks.

The following table provides information about the columns in the
'threadblocks' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the threadblocks table*

Column Name            Type               Description

'node_id'              integer            Node ID

'thr_no'               integer            Thread ID

'block_name'           string             Block name

'block_instance'       integer            Block instance number

The value of the 'block_name' in this table is one of the values found
in the 'block_name' column when selecting from the
'ndbinfo.blocks' table.  Although the
list of possible values is static for a given NDB Cluster release, the
list may vary between releases.

The 'block_instance' column provides the kernel block instance number.

21.5.10.42 The ndbinfo threads Table
....................................

The 'threads' table provides information about threads running in the
'NDB' kernel.

The following table provides information about the columns in the
'threads' table.  For each column, the table shows the name, data type,
and a brief description.  Additional information can be found in the
notes following the table.

*Columns of the threads table*

Column Name            Type               Description

'node_id'              integer            ID of the node where the
                                          thread is running

'thr_no'               integer            Thread ID (specific to this
                                          node)

'thread_name'          string             Thread name (type of thread)

'thread_description'   string             Thread (type) description

Sample output from a 2-node example cluster, including thread
descriptions, is shown here:

     mysql> SELECT * FROM threads;
     +---------+--------+-------------+------------------------------------------------------------------+
     | node_id | thr_no | thread_name | thread_description                                               |
     +---------+--------+-------------+------------------------------------------------------------------+
     |       5 |      0 | main        | main thread, schema and distribution handling                    |
     |       5 |      1 | rep         | rep thread, asynch replication and proxy block handling          |
     |       5 |      2 | ldm         | ldm thread, handling a set of data partitions                    |
     |       5 |      3 | recv        | receive thread, performing receive and polling for new receives |
     |       6 |      0 | main        | main thread, schema and distribution handling                    |
     |       6 |      1 | rep         | rep thread, asynch replication and proxy block handling          |
     |       6 |      2 | ldm         | ldm thread, handling a set of data partitions                    |
     |       6 |      3 | recv        | receive thread, performing receive and polling for new receives |
     +---------+--------+-------------+------------------------------------------------------------------+
     8 rows in set (0.01 sec)

This table was added in NDB 7.5.2.

21.5.10.43 The ndbinfo threadstat Table
.......................................

The 'threadstat' table provides a rough snapshot of statistics for
threads running in the 'NDB' kernel.

The following table provides information about the columns in the
'threadstat' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the threadstat table*

Column Name            Type               Description

'node_id'              integer            Node ID

'thr_no'               integer            Thread ID

'thr_nm'               string             Thread name

'c_loop'               string             Number of loops in main loop

'c_exec'               string             Number of signals executed

'c_wait'               string             Number of times waiting for
                                          additional input

'c_l_sent_prioa'       integer            Number of priority A signals
                                          sent to own node

'c_l_sent_priob'       integer            Number of priority B signals
                                          sent to own node

'c_r_sent_prioa'       integer            Number of priority A signals
                                          sent to remote node

'c_r_sent_priob'       integer            Number of priority B signals
                                          sent to remote node

'os_tid'               integer            OS thread ID

'os_now'               integer            OS time (ms)

'os_ru_utime'          integer            OS user CPU time (µs)

'os_ru_stime'          integer            OS system CPU time (µs)

'os_ru_minflt'         integer            OS page reclaims (soft page
                                          faults)

'os_ru_majflt'         integer            OS page faults (hard page
                                          faults)

'os_ru_nvcsw'          integer            OS voluntary context switches

'os_ru_nivcsw'         integer            OS involuntary context
                                          switches

'os_time' uses the system 'gettimeofday()' call.

The values of the 'os_ru_utime', 'os_ru_stime', 'os_ru_minflt',
'os_ru_majflt', 'os_ru_nvcsw', and 'os_ru_nivcsw' columns are obtained
using the system 'getrusage()' call, or the equivalent.

Since this table contains counts taken at a given point in time, for
best results it is necessary to query this table periodically and store
the results in an intermediate table or tables.  The MySQL Server's
Event Scheduler can be employed to automate such monitoring.  For more
information, see event-scheduler.

21.5.10.44 The ndbinfo transporters Table
.........................................

This table contains information about NDB transporters.

The following table provides information about the columns in the
'transporters' table.  For each column, the table shows the name, data
type, and a brief description.  Additional information can be found in
the notes following the table.

*Columns of the transporters table*

Column Name            Type               Description

'node_id'              integer            This data node's unique node
                                          ID in the cluster

'remote_node_id'       integer            The remote data node's node ID

'status'               string             Status of the connection

'remote_address'       string             Name or IP address of the
                                          remote host

'bytes_sent'           integer            Number of bytes sent using
                                          this connection

'bytes_received'       integer            Number of bytes received using
                                          this connection

'connect_count'        integer            Number of times connection
                                          established on this
                                          transporter

'overloaded'           boolean (0 or 1)   1 if this transporter is
                                          currently overloaded,
                                          otherwise 0

'overload_count'       integer            Number of times this
                                          transporter has entered
                                          overload state since
                                          connecting

'slowdown'             boolean (0 or 1)   1 if this transporter is in
                                          slowdown state, otherwise 0

'slowdown_count'       integer            Number of times this
                                          transporter has entered
                                          slowdown state since
                                          connecting

For each running data node in the cluster, the 'transporters' table
displays a row showing the status of each of that node's connections
with all nodes in the cluster, _including itself_.  This information is
shown in the table's _status_ column, which can have any one of the
following values: 'CONNECTING', 'CONNECTED', 'DISCONNECTING', or
'DISCONNECTED'.

Connections to API and management nodes which are configured but not
currently connected to the cluster are shown with status 'DISCONNECTED'.
Rows where the 'node_id' is that of a data node which is not currently
connected are not shown in this table.  (This is similar omission of
disconnected nodes in the 'ndbinfo.nodes'
table.

The 'remote_address' is the host name or address for the node whose ID
is shown in the 'remote_node_id' column.  The 'bytes_sent' from this
node and 'bytes_received' by this node are the numbers, respectively, of
bytes sent and received by the node using this connection since it was
established.  For nodes whose status is 'CONNECTING' or 'DISCONNECTED',
these columns always display '0'.

Assume you have a 5-node cluster consisting of 2 data nodes, 2 SQL
nodes, and 1 management node, as shown in the output of the 'SHOW'
command in the 'ndb_mgm' client:

     ndb_mgm> SHOW
     Connected to Management Server at: localhost:1186
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     2 node(s)
     id=1    @10.100.10.1  (5.7.22-ndb-7.5.11, Nodegroup: 0, *)
     id=2    @10.100.10.2  (5.7.22-ndb-7.5.11, Nodegroup: 0)

     [ndb_mgmd(MGM)] 1 node(s)
     id=10   @10.100.10.10  (5.7.22-ndb-7.5.11)

     [mysqld(API)]   2 node(s)
     id=20   @10.100.10.20  (5.7.22-ndb-7.5.11)
     id=21   @10.100.10.21  (5.7.22-ndb-7.5.11)

There are 10 rows in the 'transporters' table--5 for the first data
node, and 5 for the second--assuming that all data nodes are running, as
shown here:

     mysql> SELECT node_id, remote_node_id, status
         ->   FROM ndbinfo.transporters;
     +---------+----------------+---------------+
     | node_id | remote_node_id | status        |
     +---------+----------------+---------------+
     |       1 |              1 | DISCONNECTED  |
     |       1 |              2 | CONNECTED     |
     |       1 |             10 | CONNECTED     |
     |       1 |             20 | CONNECTED     |
     |       1 |             21 | CONNECTED     |
     |       2 |              1 | CONNECTED     |
     |       2 |              2 | DISCONNECTED  |
     |       2 |             10 | CONNECTED     |
     |       2 |             20 | CONNECTED     |
     |       2 |             21 | CONNECTED     |
     +---------+----------------+---------------+
     10 rows in set (0.04 sec)

If you shut down one of the data nodes in this cluster using the command
'2 STOP' in the 'ndb_mgm' client,
then repeat the previous query (again using the 'mysql'.
client), this table now shows only 5 rows--1 row for each connection
from the remaining management node to another node, including both
itself and the data node that is currently offline--and displays
'CONNECTING' for the status of each remaining connection to the data
node that is currently offline, as shown here:

     mysql> SELECT node_id, remote_node_id, status
         ->   FROM ndbinfo.transporters;
     +---------+----------------+---------------+
     | node_id | remote_node_id | status        |
     +---------+----------------+---------------+
     |       1 |              1 | DISCONNECTED  |
     |       1 |              2 | CONNECTING    |
     |       1 |             10 | CONNECTED     |
     |       1 |             20 | CONNECTED     |
     |       1 |             21 | CONNECTED     |
     +---------+----------------+---------------+
     5 rows in set (0.02 sec)

The 'connect_count', 'overloaded', 'overload_count', 'slowdown', and
'slowdown_count' counters are reset on connection, and retain their
values after the remote node disconnects.  The 'bytes_sent' and
'bytes_received' counters are also reset on connection, and so retain
their values following disconnection (until the next connection resets
them).

The _overload_ state referred to by the 'overloaded' and
'overload_count' columns occurs when this transporter's send buffer
contains more than 'OVerloadLimit' bytes (default is 80% of
'SendBufferMemory', that is, 0.8 * 2097152 = 1677721 bytes).  When a
given transporter is in a state of overload, any new transaction that
tries to use this transporter fails with Error 1218 ('Send Buffers
overloaded in NDB kernel').  This affects both scans and primary key
operations.

The _slowdown_ state referenced by the 'slowdown' and 'slowdown_count'
columns of this table occurs when the transporter's send buffer contains
more than 60% of the overload limit (equal to 0.6 * 2097152 = 1258291
bytes by default).  In this state, any new scan using this transporter
has its batch size reduced to minimize the load on the transporter.

Common causes of send buffer slowdown or overloading include the
following:

   * Data size, in particular the quantity of data stored in
     'TEXT' columns or 'BLOB' columns (or both types
     of columns)

   * Having a data node (ndbd or ndbmtd) on the same host as an SQL node
     that is engaged in binary logging

   * Large number of rows per transaction or transaction batch

   * Configuration issues such as insufficient 'SendBufferMemory'

   * Hardware issues such as insufficient RAM or poor network
     connectivity

See also mysql-cluster-config-send-buffers.

21.5.11 INFORMATION_SCHEMA Tables for NDB Cluster
-------------------------------------------------

Two 'INFORMATION_SCHEMA' tables provide
information that is of particular use when managing an NDB Cluster .
The 'FILES' table provides information about NDB
Cluster Disk Data files.  The 'ndb_transid_mysql_connection_map'
table provides a mapping between
transactions, transaction coordinators, and API nodes.

Additional statistical and other data about NDB Cluster transactions,
operations, threads, blocks, and other aspects of performance can be
obtained from the tables in the 'ndbinfo'.
database.  For information about these tables, see
mysql-cluster-ndbinfo.

21.5.12 NDB Cluster Security Issues
-----------------------------------

This section discusses security considerations to take into account when
setting up and running NDB Cluster.

Topics covered in this section include the following:

   * NDB Cluster and network security issues

   * Configuration issues relating to running NDB Cluster securely

   * NDB Cluster and the MySQL privilege system

   * MySQL standard security procedures as applicable to NDB Cluster

21.5.12.1 NDB Cluster Security and Networking Issues
....................................................

In this section, we discuss basic network security issues as they relate
to NDB Cluster.  It is extremely important to remember that NDB Cluster
'out of the box' is not secure; you or your network administrator must
take the proper steps to ensure that your cluster cannot be compromised
over the network.

Cluster communication protocols are inherently insecure, and no
encryption or similar security measures are used in communications
between nodes in the cluster.  Because network speed and latency have a
direct impact on the cluster's efficiency, it is also not advisable to
employ SSL or other encryption to network connections between nodes, as
such schemes will effectively slow communications.

It is also true that no authentication is used for controlling API node
access to an NDB Cluster.  As with encryption, the overhead of imposing
authentication requirements would have an adverse impact on Cluster
performance.

In addition, there is no checking of the source IP address for either of
the following when accessing the cluster:

   * SQL or API nodes using 'free slots' created by empty '[mysqld]' or
     '[api]' sections in the 'config.ini' file

     This means that, if there are any empty '[mysqld]' or '[api]'
     sections in the 'config.ini' file, then any API nodes (including
     SQL nodes) that know the management server's host name (or IP
     address) and port can connect to the cluster and access its data
     without restriction.  (See
     mysql-cluster-security-mysql-privileges, for more information
     about this and related issues.)

     *Note*:

     You can exercise some control over SQL and API node access to the
     cluster by specifying a 'HostName' parameter for all '[mysqld]' and
     '[api]' sections in the 'config.ini' file.  However, this also
     means that, should you wish to connect an API node to the cluster
     from a previously unused host, you need to add an '[api]' section
     containing its host name to the 'config.ini' file.

     More information is available elsewhere in this chapter about the
     'HostName' parameter.  Also see mysql-cluster-quick, for
     configuration examples using 'HostName' with API nodes.

   * Any 'ndb_mgm' client

     This means that any cluster management client that is given the
     management server's host name (or IP address) and port (if not the
     standard port) can connect to the cluster and execute any
     management client command.  This includes commands such as 'ALL
     STOP' and 'SHUTDOWN'.

For these reasons, it is necessary to protect the cluster on the network
level.  The safest network configuration for Cluster is one which
isolates connections between Cluster nodes from any other network
communications.  This can be accomplished by any of the following
methods:

  1. Keeping Cluster nodes on a network that is physically separate from
     any public networks.  This option is the most dependable; however,
     it is the most expensive to implement.

     We show an example of an NDB Cluster setup using such a physically
     segregated network here:

     FIGURE GOES HERE: NDB Cluster with Hardware Firewall

     This setup has two networks, one private (solid box) for the
     Cluster management servers and data nodes, and one public (dotted
     box) where the SQL nodes reside.  (We show the management and data
     nodes connected using a gigabit switch since this provides the best
     performance.)  Both networks are protected from the outside by a
     hardware firewall, sometimes also known as a _network-based
     firewall_.

     This network setup is safest because no packets can reach the
     cluster's management or data nodes from outside the network--and
     none of the cluster's internal communications can reach the
     outside--without going through the SQL nodes, as long as the SQL
     nodes do not permit any packets to be forwarded.  This means, of
     course, that all SQL nodes must be secured against hacking
     attempts.

     *Important*:

     With regard to potential security vulnerabilities, an SQL node is
     no different from any other MySQL server.  See
     security-against-attack, for a description of techniques you can
     use to secure MySQL servers.

  2.
     Using one or more software firewalls (also known as _host-based
     firewalls_) to control which packets pass through to the cluster
     from portions of the network that do not require access to it.  In
     this type of setup, a software firewall must be installed on every
     host in the cluster which might otherwise be accessible from
     outside the local network.

     The host-based option is the least expensive to implement, but
     relies purely on software to provide protection and so is the most
     difficult to keep secure.

     This type of network setup for NDB Cluster is illustrated here:

     FIGURE GOES HERE: NDB Cluster with Software Firewalls

     Using this type of network setup means that there are two zones of
     NDB Cluster hosts.  Each cluster host must be able to communicate
     with all of the other machines in the cluster, but only those
     hosting SQL nodes (dotted box) can be permitted to have any contact
     with the outside, while those in the zone containing the data nodes
     and management nodes (solid box) must be isolated from any machines
     that are not part of the cluster.  Applications using the cluster
     and user of those applications must _not_ be permitted to have
     direct access to the management and data node hosts.

     To accomplish this, you must set up software firewalls that limit
     the traffic to the type or types shown in the following table,
     according to the type of node that is running on each cluster host
     computer:

     *Node types in a host-based firewall cluster configuration*

     Node Type          Permitted Traffic

     SQL or API node
                           * It originates from the IP address of a
                             management or data node (using any TCP or UDP
                             port).

                           * It originates from within the network in which
                             the cluster resides and is on the port that
                             your application is using.

     Data node or
     Management node       * It originates from the IP address of a
                             management or data node (using any TCP or UDP
                             port).

                           * It originates from the IP address of an SQL or
                             API node.

     Any traffic other than that shown in the table for a given node
     type should be denied.

     The specifics of configuring a firewall vary from firewall
     application to firewall application, and are beyond the scope of
     this Manual.  'iptables' is a very common and reliable firewall
     application, which is often used with 'APF' as a front end to make
     configuration easier.  You can (and should) consult the
     documentation for the software firewall that you employ, should you
     choose to implement an NDB Cluster network setup of this type, or
     of a 'mixed' type as discussed under the next item.

  3.
     It is also possible to employ a combination of the first two
     methods, using both hardware and software to secure the
     cluster--that is, using both network-based and host-based
     firewalls.  This is between the first two schemes in terms of both
     security level and cost.  This type of network setup keeps the
     cluster behind the hardware firewall, but permits incoming packets
     to travel beyond the router connecting all cluster hosts to reach
     the SQL nodes.

     One possible network deployment of an NDB Cluster using hardware
     and software firewalls in combination is shown here:

     FIGURE GOES HERE: NDB Cluster with a Combination of Hardware and
     Software Firewalls

     In this case, you can set the rules in the hardware firewall to
     deny any external traffic except to SQL nodes and API nodes, and
     then permit traffic to them only on the ports required by your
     application.

Whatever network configuration you use, remember that your objective
from the viewpoint of keeping the cluster secure remains the same--to
prevent any unessential traffic from reaching the cluster while ensuring
the most efficient communication between the nodes in the cluster.

Because NDB Cluster requires large numbers of ports to be open for
communications between nodes, the recommended option is to use a
segregated network.  This represents the simplest way to prevent
unwanted traffic from reaching the cluster.

*Note*:

If you wish to administer an NDB Cluster remotely (that is, from outside
the local network), the recommended way to do this is to use 'ssh' or
another secure login shell to access an SQL node host.  From this host,
you can then run the management client to access the management server
safely, from within the Cluster's own local network.

Even though it is possible to do so in theory, it is _not_ recommended
to use 'ndb_mgm' to manage a
Cluster directly from outside the local network on which the Cluster is
running.  Since neither authentication nor encryption takes place
between the management client and the management server, this represents
an extremely insecure means of managing the cluster, and is almost
certain to be compromised sooner or later.

21.5.12.2 NDB Cluster and MySQL Privileges
..........................................

In this section, we discuss how the MySQL privilege system works in
relation to NDB Cluster and the implications of this for keeping an NDB
Cluster secure.

Standard MySQL privileges apply to NDB Cluster tables.  This includes
all MySQL privilege types ('SELECT' privilege, 'UPDATE' privilege,
'DELETE' privilege, and so on) granted on the database, table, and
column level.  As with any other MySQL Server, user and privilege
information is stored in the 'mysql' system database.  The SQL
statements used to grant and revoke privileges on 'NDB'
tables, databases containing such tables, and columns
within such tables are identical in all respects with the 'GRANT'
and 'REVOKE' statements used in connection with
database objects involving any (other) MySQL storage engine.  The same
thing is true with respect to the 'CREATE USER' and
'DROP USER' statements.

It is important to keep in mind that, by default, the MySQL grant tables
use the 'MyISAM' storage engine.  Because
of this, those tables are not normally duplicated or shared among MySQL
servers acting as SQL nodes in an NDB Cluster.  In other words, changes
in users and their privileges do not automatically propagate between SQL
nodes by default.  If you wish, you can enable automatic distribution of
MySQL users and privileges across NDB Cluster SQL nodes; see
mysql-cluster-privilege-distribution, for details.

Conversely, because there is no way in MySQL to deny privileges
(privileges can either be revoked or not granted in the first place, but
not denied as such), there is no special protection for 'NDB'
tables on one SQL node from users that have privileges on
another SQL node; (This is true even if you are not using automatic
distribution of user privileges.  The definitive example of this is the
MySQL 'root' account, which can perform any action on any database
object.  In combination with empty '[mysqld]' or '[api]' sections of the
'config.ini' file, this account can be especially dangerous.  To
understand why, consider the following scenario:

   * The 'config.ini' file contains at least one empty '[mysqld]' or
     '[api]' section.  This means that the NDB Cluster management server
     performs no checking of the host from which a MySQL Server (or
     other API node) accesses the NDB Cluster.

   * There is no firewall, or the firewall fails to protect against
     access to the NDB Cluster from hosts external to the network.

   * The host name or IP address of the NDB Cluster management server is
     known or can be determined from outside the network.

If these conditions are true, then anyone, anywhere can start a MySQL
Server with '--ndbcluster' '--ndb-connectstring=MANAGEMENT_HOST' and
access this NDB Cluster.  Using the MySQL 'root' account, this person
can then perform the following actions:

   * Execute metadata statements such as 'SHOW DATABASES'
     statement (to obtain a list of all 'NDB'
     databases on the server) or 'SHOW TABLES FROM SOME_NDB_DATABASE'
     statement to obtain a list of all
     'NDB' tables in a given database

   *
     Run any legal MySQL statements on any of the discovered tables,
     such as:

        * 'SELECT * FROM SOME_TABLE' to read all the data from any table

        * 'DELETE FROM SOME_TABLE' to delete all the data from a table

        * 'DESCRIBE SOME_TABLE' or 'SHOW CREATE TABLE SOME_TABLE' to
          determine the table schema

        * 'UPDATE SOME_TABLE SET COLUMN1 = SOME_VALUE' to fill a table
          column with 'garbage' data; this could actually cause much
          greater damage than simply deleting all the data

          More insidious variations might include statements like these:

               UPDATE SOME_TABLE SET AN_INT_COLUMN = AN_INT_COLUMN + 1

          or

               UPDATE SOME_TABLE SET A_VARCHAR_COLUMN = REVERSE(A_VARCHAR_COLUMN)

          Such malicious statements are limited only by the imagination
          of the attacker.

     The only tables that would be safe from this sort of mayhem would
     be those tables that were created using storage engines other than
     'NDB', and so not visible to a 'rogue' SQL
     node.

     A user who can log in as 'root' can also access the
     'INFORMATION_SCHEMA' database and its tables, and so obtain
     information about databases, tables, stored routines, scheduled
     events, and any other database objects for which metadata is stored
     in 'INFORMATION_SCHEMA'.

     It is also a very good idea to use different passwords for the
     'root' accounts on different NDB Cluster SQL nodes unless you are
     using distributed privileges.

In sum, you cannot have a safe NDB Cluster if it is directly accessible
from outside your local network.

*Important*:

_Never leave the MySQL root account password empty_.  This is just as
true when running MySQL as an NDB Cluster SQL node as it is when running
it as a standalone (non-Cluster) MySQL Server, and should be done as
part of the MySQL installation process before configuring the MySQL
Server as an SQL node in an NDB Cluster.

If you wish to employ NDB Cluster's distributed privilege capabilities,
you should not simply convert the system tables in the 'mysql' database
to use the 'NDB' storage engine manually.  Use the
stored procedure provided for this purpose instead; see
mysql-cluster-privilege-distribution.

Otherwise, if you need to synchronize 'mysql' system tables between SQL
nodes, you can use standard MySQL replication to do so, or employ a
script to copy table entries between the MySQL servers.

Summary

The most important points to remember regarding the MySQL privilege
system with regard to NDB Cluster are listed here:

  1. Users and privileges established on one SQL node do not
     automatically exist or take effect on other SQL nodes in the
     cluster.  Conversely, removing a user or privilege on one SQL node
     in the cluster does not remove the user or privilege from any other
     SQL nodes.

  2. You can distribute MySQL users and privileges among SQL nodes using
     the SQL script, and the stored procedures it contains, that are
     supplied for this purpose in the NDB Cluster distribution.

  3. Once a MySQL user is granted privileges on an 'NDB'
     table from one SQL node in an NDB Cluster, that user
     can 'see' any data in that table regardless of the SQL node from
     which the data originated, even if you are not using privilege
     distribution.

21.5.12.3 NDB Cluster and MySQL Security Procedures
...................................................

In this section, we discuss MySQL standard security procedures as they
apply to running NDB Cluster.

In general, any standard procedure for running MySQL securely also
applies to running a MySQL Server as part of an NDB Cluster.  First and
foremost, you should always run a MySQL Server as the 'mysql' system
user; this is no different from running MySQL in a standard
(non-Cluster) environment.  The 'mysql' system account should be
uniquely and clearly defined.  Fortunately, this is the default behavior
for a new MySQL installation.  You can verify that the 'mysqld'
process is running as the system user 'mysql' by using the
system command such as the one shown here:

     shell> ps aux | grep mysql
     root     10467  0.0  0.1   3616  1380 pts/3    S    11:53   0:00 \
       /bin/sh ./mysqld_safe --ndbcluster --ndb-connectstring=localhost:1186
     mysql    10512  0.2  2.5  58528 26636 pts/3    Sl   11:53   0:00 \
       /usr/local/mysql/libexec/mysqld --basedir=/usr/local/mysql \
       --datadir=/usr/local/mysql/var --user=mysql --ndbcluster \
       --ndb-connectstring=localhost:1186 --pid-file=/usr/local/mysql/var/mothra.pid \
       --log-error=/usr/local/mysql/var/mothra.err
     jon      10579  0.0  0.0   2736   688 pts/0    S+   11:54   0:00 grep mysql

If the 'mysqld' process is running as any other user than
'mysql', you should immediately shut it down and restart it as the
'mysql' user.  If this user does not exist on the system, the 'mysql'
user account should be created, and this user should be part of the
'mysql' user group; in this case, you should also make sure that the
MySQL data directory on this system (as set using the '--datadir' option
for 'mysqld') is owned by the 'mysql' user, and that the
SQL node's 'my.cnf' file includes 'user=mysql' in the '[mysqld]'
section.  Alternatively, you can start the MySQL server process with
'--user=mysql' on the command line, but it is preferable to use the
'my.cnf' option, since you might forget to use the command-line option
and so have 'mysqld' running as another user
unintentionally.  The 'mysqld_safe' startup script
forces MySQL to run as the 'mysql' user.

*Important*:

Never run 'mysqld' as the system root user.  Doing so
means that potentially any file on the system can be read by MySQL, and
thus--should MySQL be compromised--by an attacker.

As mentioned in the previous section (see
mysql-cluster-security-mysql-privileges), you should always set a root
password for the MySQL Server as soon as you have it running.  You
should also delete the anonymous user account that is installed by
default.  You can accomplish these tasks using the following statements:

     shell> mysql -u root

     mysql> UPDATE mysql.user
         ->     SET Password=PASSWORD('SECURE_PASSWORD')
         ->     WHERE User='root';

     mysql> DELETE FROM mysql.user
         ->     WHERE User='';

     mysql> FLUSH PRIVILEGES;

Be very careful when executing the 'DELETE' statement not
to omit the 'WHERE' clause, or you risk deleting _all_ MySQL users.  Be
sure to run the 'FLUSH PRIVILEGES' statement as soon as you have
modified the 'mysql.user' table, so that the changes take immediate
effect.  Without 'FLUSH PRIVILEGES', the changes do not take effect
until the next time that the server is restarted.

*Note*:

Many of the NDB Cluster utilities such as 'ndb_show_tables',
see 'ndb_desc',
and 'ndb_select_all'
also work without authentication
and can reveal table names, schemas, and data.  By default these are
installed on Unix-style systems with the permissions 'wxr-xr-x' (755),
which means they can be executed by any user that can access the
'mysql/bin' directory.

See mysql-cluster-programs, for more information about these
utilities.

21.5.13 NDB Cluster Disk Data Tables
------------------------------------

It is possible to store the nonindexed columns of 'NDB'
tables on disk, rather than in RAM.

As part of implementing NDB Cluster Disk Data work, a number of
improvements were made in NDB Cluster for the efficient handling of very
large amounts (terabytes) of data during node recovery and restart.
These include a 'no-steal' algorithm for synchronizing a starting node
with very large data sets.  For more information, see the paper
'Recovery Principles of NDB Cluster 5.1
(http://www.vldb2005.org/program/paper/wed/p1108-ronstrom.pdf)', by NDB
Cluster developers Mikael Ronstro"m and Jonas Oreland.

NDB Cluster Disk Data performance can be influenced by a number of
configuration parameters.  For information about these parameters and
their effects, see 'NDB Cluster Disk Data configuration parameters' and
'NDB Cluster Disk Data storage and 'GCP Stop' errors'

The performance of an NDB Cluster that uses Disk Data storage can also
be greatly improved by separating data node file systems from undo log
files and tablespace data files, which can be done using symbolic links.
For more information, see mysql-cluster-disk-data-symlinks.

21.5.13.1 NDB Cluster Disk Data Objects
.......................................

NDB Cluster Disk Data storage is implemented using a number of _Disk
Data objects_.  These include the following:

   * _Tablespaces_ act as containers for other Disk Data objects.

   * _Undo log files_ undo information required for rolling back
     transactions.

   * One or more undo log files are assigned to a _log file group_,
     which is then assigned to a tablespace.

   * _Data files_ store Disk Data table data.  A data file is assigned
     directly to a tablespace.

Undo log files and data files are actual files in the file system of
each data node; by default they are placed in 'ndb_NODE_ID_fs' in the
DATADIR specified in the NDB Cluster 'config.ini' file, and where
NODE_ID is the data node's node ID. It is possible to place these
elsewhere by specifying either an absolute or relative path as part of
the filename when creating the undo log or data file.  Statements that
create these files are shown later in this section.

NDB Cluster tablespaces and log file groups are not implemented as
files.

*Important*:

Although not all Disk Data objects are implemented as files, they all
share the same namespace.  This means that _each Disk Data object_ must
be uniquely named (and not merely each Disk Data object of a given
type).  For example, you cannot have a tablespace and a log file group
both named 'dd1'.

Assuming that you have already set up an NDB Cluster with all nodes
(including management and SQL nodes), the basic steps for creating an
NDB Cluster table on disk are as follows:

  1. Create a log file group, and assign one or more undo log files to
     it (an undo log file is also sometimes referred to as an
     _undofile_).

     *Note*:

     Undo log files are necessary only for Disk Data tables; they are
     not used for 'NDBCLUSTER' tables that are
     stored only in memory.

  2. Create a tablespace; assign the log file group, as well as one or
     more data files, to the tablespace.

  3. Create a Disk Data table that uses this tablespace for data
     storage.

Each of these tasks can be accomplished using SQL statements in the
'mysql' client or other MySQL client application, as shown
in the example that follows.

  1.
     We create a log file group named 'lg_1' using 'CREATE LOGFILE GROUP'.
     This log file group is to be made up
     of two undo log files, which we name 'undo_1.log' and 'undo_2.log',
     whose initial sizes are 16 MB and 12 MB, respectively.  (The
     default initial size for an undo log file is 128 MB.) Optionally,
     you can also specify a size for the log file group's undo buffer,
     or permit it to assume the default value of 8 MB. In this example,
     we set the UNDO buffer's size at 2 MB. A log file group must be
     created with an undo log file; so we add 'undo_1.log' to 'lg_1' in
     this 'CREATE LOGFILE GROUP' statement:

          CREATE LOGFILE GROUP lg_1
              ADD UNDOFILE 'undo_1.log'
              INITIAL_SIZE 16M
              UNDO_BUFFER_SIZE 2M
              ENGINE NDBCLUSTER;

     To add 'undo_2.log' to the log file group, use the following
     'ALTER LOGFILE GROUP' statement:

          ALTER LOGFILE GROUP lg_1
              ADD UNDOFILE 'undo_2.log'
              INITIAL_SIZE 12M
              ENGINE NDBCLUSTER;

     Some items of note:

        * The '.log' file extension used here is not required.  We use
          it merely to make the log files easily recognizable.

        * Every 'CREATE LOGFILE GROUP' and
          'ALTER LOGFILE GROUP' statement
          must include an 'ENGINE' option.  The only permitted values
          for this option are 'NDBCLUSTER' and
          'NDB'.

          *Important*:

          There can exist at most one log file group in the same NDB
          Cluster at any given time.

        * When you add an undo log file to a log file group using 'ADD
          UNDOFILE 'FILENAME'', a file with the name FILENAME is created
          in the 'ndb_NODE_ID_fs' directory within the 'DataDir' of each
          data node in the cluster, where NODE_ID is the node ID of the
          data node.  Each undo log file is of the size specified in the
          SQL statement.  For example, if an NDB Cluster has 4 data
          nodes, then the 'ALTER LOGFILE GROUP'
          statement just shown creates 4 undo log
          files, 1 each on in the data directory of each of the 4 data
          nodes; each of these files is named 'undo_2.log' and each file
          is 12 MB in size.

        * 'UNDO_BUFFER_SIZE' is limited by the amount of system memory
          available.

        * For more information about the 'CREATE LOGFILE GROUP'
          statement, see
          create-logfile-group.  For more information about
          'ALTER LOGFILE GROUP', see
          alter-logfile-group.

  2.
     Now we can create a tablespace, which contains files to be used by
     NDB Cluster Disk Data tables for storing their data.  A tablespace
     is also associated with a particular log file group.  When creating
     a new tablespace, you must specify the log file group which it is
     to use for undo logging; you must also specify a data file.  You
     can add more data files to the tablespace after the tablespace is
     created; it is also possible to drop data files from a tablespace
     (an example of dropping data files is provided later in this
     section).

     Assume that we wish to create a tablespace named 'ts_1' which uses
     'lg_1' as its log file group.  This tablespace is to contain two
     data files named 'data_1.dat' and 'data_2.dat', whose initial sizes
     are 32 MB and 48 MB, respectively.  (The default value for
     'INITIAL_SIZE' is 128 MB.) We can do this using two SQL statements,
     as shown here:

          CREATE TABLESPACE ts_1
              ADD DATAFILE 'data_1.dat'
              USE LOGFILE GROUP lg_1
              INITIAL_SIZE 32M
              ENGINE NDBCLUSTER;

          ALTER TABLESPACE ts_1
              ADD DATAFILE 'data_2.dat'
              INITIAL_SIZE 48M
              ENGINE NDBCLUSTER;

     The 'CREATE TABLESPACE' statement creates
     a tablespace 'ts_1' with the data file 'data_1.dat', and associates
     'ts_1' with log file group 'lg_1'.  The 'ALTER TABLESPACE'
     adds the second data file ('data_2.dat').

     Some items of note:

        * As is the case with the '.log' file extension used in this
          example for undo log files, there is no special significance
          for the '.dat' file extension; it is used merely for easy
          recognition of data files.

        * When you add a data file to a tablespace using 'ADD DATAFILE
          'FILENAME'', a file with the name FILENAME is created in the
          'ndb_NODE_ID_fs' directory within the 'DataDir' of each data
          node in the cluster, where NODE_ID is the node ID of the data
          node.  Each data file is of the size specified in the SQL
          statement.  For example, if an NDB Cluster has 4 data nodes,
          then the 'ALTER TABLESPACE' statement
          just shown creates 4 data files, 1 each in the data directory
          of each of the 4 data nodes; each of these files is named
          'data_2.dat' and each file is 48 MB in size.

        * All 'CREATE TABLESPACE' and
          'ALTER TABLESPACE' statements must contain
          an 'ENGINE' clause; only tables using the same storage engine
          as the tablespace can be created in the tablespace.  For NDB
          Cluster tablespaces, the only permitted values for this option
          are 'NDBCLUSTER' and 'NDB'.

        * For more information about the 'CREATE TABLESPACE'
          and 'ALTER TABLESPACE'
          statements, see create-tablespace,
          and alter-tablespace.

  3.
     Now it is possible to create a table whose nonindexed columns are
     stored on disk in the tablespace 'ts_1':

          CREATE TABLE dt_1 (
              member_id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
              last_name VARCHAR(50) NOT NULL,
              first_name VARCHAR(50) NOT NULL,
              dob DATE NOT NULL,
              joined DATE NOT NULL,
              INDEX(last_name, first_name)
              )
              TABLESPACE ts_1 STORAGE DISK
              ENGINE NDBCLUSTER;

     The 'TABLESPACE ... STORAGE DISK' option tells the
     'NDBCLUSTER' storage engine to use tablespace
     'ts_1' for disk data storage.

     Once table 'ts_1' has been created as shown, you can perform
     'INSERT', 'SELECT', 'UPDATE',
     and 'DELETE' statements on it just as you would with
     any other MySQL table.

     It is also possible to specify whether an individual column is
     stored on disk or in memory by using a 'STORAGE' clause as part of
     the column's definition in a 'CREATE TABLE' or
     'ALTER TABLE' statement.  'STORAGE DISK' causes
     the column to be stored on disk, and 'STORAGE MEMORY' causes
     in-memory storage to be used.  See create-table, for more
     information.

Indexing of columns implicitly stored on disk

For table 'dt_1' as defined in the example just shown, only the 'dob'
and 'joined' columns are stored on disk.  This is because there are
indexes on the 'id', 'last_name', and 'first_name' columns, and so data
belonging to these columns is stored in RAM. Only nonindexed columns can
be held on disk; indexes and indexed column data continue to be stored
in memory.  This tradeoff between the use of indexes and conservation of
RAM is something you must keep in mind as you design Disk Data tables.

You cannot add an index to a column that has been explicitly declared
'STORAGE DISK', without first changing its storage type to 'MEMORY'; any
attempt to do so fails with an error.  A column which _implicitly_ uses
disk storage can be indexed; when this is done, the column's storage
type is changed to 'MEMORY' automatically.  By 'implicitly', we mean a
column whose storage type is not declared, but which is which inherited
from the parent table.  In the following CREATE TABLE statement (using
the tablespace 'ts_1' defined previously), columns 'c2' and 'c3' use
disk storage implicitly:

     mysql> CREATE TABLE ti (
         ->     c1 INT PRIMARY KEY,
         ->     c2 INT,
         ->     c3 INT,
         ->     c4 INT
         -> )
         ->     STORAGE DISK
         ->     TABLESPACE ts_1
         ->     ENGINE NDBCLUSTER;
     Query OK, 0 rows affected (1.31 sec)

Because 'c2', 'c3', and 'c4' are themselves not declared with 'STORAGE
DISK', it is possible to index them.  Here, we add indexes to 'c2' and
'c3', using, respectively, 'CREATE INDEX' and 'ALTER TABLE':

     mysql> CREATE INDEX i1 ON ti(c2);
     Query OK, 0 rows affected (2.72 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> ALTER TABLE ti ADD INDEX i2(c3);
     Query OK, 0 rows affected (0.92 sec)
     Records: 0  Duplicates: 0  Warnings: 0

'SHOW CREATE TABLE' confirms that the indexes
were added.

     mysql> SHOW CREATE TABLE ti\G
     *************************** 1. row ***************************
            Table: ti
     Create Table: CREATE TABLE `ti` (
       `c1` int(11) NOT NULL,
       `c2` int(11) DEFAULT NULL,
       `c3` int(11) DEFAULT NULL,
       `c4` int(11) DEFAULT NULL,
       PRIMARY KEY (`c1`),
       KEY `i1` (`c2`),
       KEY `i2` (`c3`)
     ) /*!50100 TABLESPACE `ts_1` STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1
     1 row in set (0.00 sec)

You can see using 'ndb_desc'.
that the indexed columns (emphasized text) now use in-memory rather than
on-disk storage:

     shell> ./ndb_desc -d test t1
     -- t1 --
     Version: 33554433
     Fragment type: HashMapPartition
     K Value: 6
     Min load factor: 78
     Max load factor: 80
     Temporary table: no
     Number of attributes: 4
     Number of primary keys: 1
     Length of frm data: 317
     Max Rows: 0
     Row Checksum: 1
     Row GCI: 1
     SingleUserMode: 0
     ForceVarPart: 1
     PartitionCount: 4
     FragmentCount: 4
     PartitionBalance: FOR_RP_BY_LDM
     ExtraRowGciBits: 0
     ExtraRowAuthorBits: 0
     TableStatus: Retrieved
     Table options:
     HashMap: DEFAULT-HASHMAP-3840-4
     -- Attributes --
     c1 Int PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY
     _c2 Int NULL AT=FIXED ST=MEMORY
     c3 Int NULL AT=FIXED ST=MEMORY_
     c4 Int NULL AT=FIXED ST=DISK
     -- Indexes --
     PRIMARY KEY(c1) - UniqueHashIndex
     i2(c3) - OrderedIndex
     PRIMARY(c1) - OrderedIndex
     i1(c2) - OrderedIndex

     NDBT_ProgramExit: 0 - OK

Performance note

The performance of a cluster using Disk Data storage is greatly improved
if Disk Data files are kept on a separate physical disk from the data
node file system.  This must be done for each data node in the cluster
to derive any noticeable benefit.

You may use absolute and relative file system paths with 'ADD UNDOFILE'
and 'ADD DATAFILE'.  Relative paths are calculated relative to the data
node's data directory.  You may also use symbolic links; see
mysql-cluster-disk-data-symlinks, for more information and examples.

A log file group, a tablespace, and any Disk Data tables using these
must be created in a particular order.  The same is true for dropping
any of these objects:

   * A log file group cannot be dropped as long as any tablespaces are
     using it.

   * A tablespace cannot be dropped as long as it contains any data
     files.

   * You cannot drop any data files from a tablespace as long as there
     remain any tables which are using the tablespace.

   * It is not possible to drop files created in association with a
     different tablespace than the one with which the files were
     created.  (Bug #20053)

For example, to drop all the objects created so far in this section, you
would use the following statements:

     mysql> DROP TABLE dt_1;

     mysql> ALTER TABLESPACE ts_1
         -> DROP DATAFILE 'data_2.dat'
         -> ENGINE NDBCLUSTER;

     mysql> ALTER TABLESPACE ts_1
         -> DROP DATAFILE 'data_1.dat'
         -> ENGINE NDBCLUSTER;

     mysql> DROP TABLESPACE ts_1
         -> ENGINE NDBCLUSTER;

     mysql> DROP LOGFILE GROUP lg_1
         -> ENGINE NDBCLUSTER;

These statements must be performed in the order shown, except that the
two 'ALTER TABLESPACE ... DROP DATAFILE' statements may be executed in
either order.

You can obtain information about data files used by Disk Data tables by
querying the 'FILES' table in the
'INFORMATION_SCHEMA' database.  An extra ''NULL' row' provides
additional information about undo log files.  For more information and
examples, see files-table.

21.5.13.2 Using Symbolic Links with Disk Data Objects
.....................................................

The performance of an NDB Cluster that uses Disk Data storage can be
greatly improved by separating data node file systems from undo log
files and tablespace data files and placing these on different disks.
In early versions of NDB Cluster, there was no direct support for this
in NDB Cluster, but it was possible to achieve this separation using
symbolic links as described in this section.  NDB Cluster supports the
data node configuration parameters 'FileSystemPathDD',
'FileSystemPathDataFiles', and 'FileSystemPathUndoFiles', which make the
use of symbolic links for this purpose unnecessary.  For more
information about these parameters, see
mysql-cluster-ndbd-disk-data-filesystem-parameters.

Each data node in the cluster creates a file system in the directory
named 'ndb_NODE_ID_fs' under the data node's 'DataDir' as defined in the
'config.ini' file.  In this example, we assume that each data node host
has 3 disks, aliased as '/data0', '/data1', and '/data2', and that the
cluster's 'config.ini' includes the following:

     [ndbd default]
     DataDir= /data0

Our objective is to place all Disk Data log files in '/data1', and all
Disk Data data files in '/data2', on each data node host.

*Note*:

In this example, we assume that the cluster's data node hosts are all
using Linux operating systems.  For other platforms, you may need to
substitute you operating system's commands for those shown here.

To accomplish this, perform the following steps:

   * Under the data node file system create symbolic links pointing to
     the other drives:

          shell> cd /data0/ndb_2_fs
          shell> ls
          D1  D10  D11  D2  D8  D9  LCP
          shell> ln -s /data0 dnlogs
          shell> ln -s /data1 dndata

     You should now have two symbolic links:

          shell> ls -l --hide=D*
          lrwxrwxrwx 1 user group   30 2007-03-19 13:58 dndata -> /data1
          lrwxrwxrwx 1 user group   30 2007-03-19 13:59 dnlogs -> /data2

     We show this only for the data node with node ID 2; however, you
     must do this for _each_ data node.

   * Now, in the 'mysql' client, create a log file group
     and tablespace using the symbolic links, as shown here:

          mysql> CREATE LOGFILE GROUP lg1
              ->    ADD UNDOFILE 'dnlogs/undo1.log'
              ->    INITIAL_SIZE 150M
              ->    UNDO_BUFFER_SIZE = 1M
              ->    ENGINE=NDBCLUSTER;

          mysql> CREATE TABLESPACE ts1
              ->    ADD DATAFILE 'dndata/data1.log'
              ->    USE LOGFILE GROUP lg1
              ->    INITIAL_SIZE 1G
              ->    ENGINE=NDBCLUSTER;

     Verify that the files were created and placed correctly as shown
     here:

          shell> cd /data1
          shell> ls -l
          total 2099304
          -rw-rw-r--  1 user group 157286400 2007-03-19 14:02 undo1.dat

          shell> cd /data2
          shell> ls -l
          total 2099304
          -rw-rw-r--  1 user group 1073741824 2007-03-19 14:02 data1.dat

   * If you are running multiple data nodes on one host, you must take
     care to avoid having them try to use the same space for Disk Data
     files.  You can make this easier by creating a symbolic link in
     each data node file system.  Suppose you are using '/data0' for
     both data node file systems, but you wish to have the Disk Data
     files for both nodes on '/data1'.  In this case, you can do
     something similar to what is shown here:

          shell> cd /data0
          shell> ln -s /data1/dn2 ndb_2_fs/dd
          shell> ln -s /data1/dn3 ndb_3_fs/dd
          shell> ls -l --hide=D* ndb_2_fs
          lrwxrwxrwx 1 user group   30 2007-03-19 14:22 dd -> /data1/dn2
          shell> ls -l --hide=D* ndb_3_fs
          lrwxrwxrwx 1 user group   30 2007-03-19 14:22 dd -> /data1/dn3

   * Now you can create a logfile group and tablespace using the
     symbolic link, like this:

          mysql> CREATE LOGFILE GROUP lg1
              ->    ADD UNDOFILE 'dd/undo1.log'
              ->    INITIAL_SIZE 150M
              ->    UNDO_BUFFER_SIZE = 1M
              ->    ENGINE=NDBCLUSTER;

          mysql> CREATE TABLESPACE ts1
              ->    ADD DATAFILE 'dd/data1.log'
              ->    USE LOGFILE GROUP lg1
              ->    INITIAL_SIZE 1G
              ->    ENGINE=NDBCLUSTER;

     Verify that the files were created and placed correctly as shown
     here:

          shell> cd /data1
          shell> ls
          dn2        dn3
          shell> ls dn2
          undo1.log        data1.log
          shell> ls dn3
          undo1.log        data1.log

21.5.13.3 NDB Cluster Disk Data Storage Requirements
....................................................

The following items apply to Disk Data storage requirements:

   * Variable-length columns of Disk Data tables take up a fixed amount
     of space.  For each row, this is equal to the space required to
     store the largest possible value for that column.

     For general information about calculating these values, see
     storage-requirements.

     You can obtain an estimate the amount of space available in data
     files and undo log files by querying the
     'INFORMATION_SCHEMA.FILES' table.  For more
     information and examples, see files-table.

     *Note*:

     The 'OPTIMIZE TABLE' statement does not have
     any effect on Disk Data tables.

   * In a Disk Data table, the first 256 bytes of a 'TEXT'.
     or 'BLOB' column are stored in memory; only the
     remainder is stored on disk.

   * Each row in a Disk Data table uses 8 bytes in memory to point to
     the data stored on disk.  This means that, in some cases,
     converting an in-memory column to the disk-based format can
     actually result in greater memory usage.  For example, converting a
     'CHAR(4)' column from memory-based to disk-based format increases
     the amount of 'DataMemory' used per row from 4 to 8 bytes.

*Important*:

Starting the cluster with the '--initial' option does _not_ remove Disk
Data files.  You must remove these manually prior to performing an
initial restart of the cluster.

Performance of Disk Data tables can be improved by minimizing the number
of disk seeks by making sure that 'DiskPageBufferMemory' is of
sufficient size.  You can query the 'diskpagebuffer'
table to help determine whether
the value for this parameter needs to be increased.

21.5.14 Adding NDB Cluster Data Nodes Online
--------------------------------------------

This section describes how to add NDB Cluster data nodes 'online'--that
is, without needing to shut down the cluster completely and restart it
as part of the process.

*Important*:

Currently, you must add new data nodes to an NDB Cluster as part of a
new node group.  In addition, it is not possible to change the number of
replicas (or the number of nodes per node group) online.

21.5.14.1 Adding NDB Cluster Data Nodes Online: General Issues
..............................................................

This section provides general information about the behavior of and
current limitations in adding NDB Cluster nodes online.

Redistribution of Data

The ability to add new nodes online includes a means to reorganize
'NDBCLUSTER' table data and indexes so that they are
distributed across all data nodes, including the new ones, by means of
the 'ALTER TABLE ... REORGANIZE PARTITION'
statement.  Table reorganization of
both in-memory and Disk Data tables is supported.  This redistribution
does not currently include unique indexes (only ordered indexes are
redistributed).

The redistribution for 'NDBCLUSTER' tables already
existing before the new data nodes were added is not automatic, but can
be accomplished using simple SQL statements in 'mysql' or
another MySQL client application.  However, all data and indexes added
to tables created after a new node group has been added are distributed
automatically among all cluster data nodes, including those added as
part of the new node group.

Partial starts

It is possible to add a new node group without all of the new data nodes
being started.  It is also possible to add a new node group to a
degraded cluster--that is, a cluster that is only partially started, or
where one or more data nodes are not running.  In the latter case, the
cluster must have enough nodes running to be viable before the new node
group can be added.

Effects on ongoing operations

Normal DML operations using NDB Cluster data are not prevented by the
creation or addition of a new node group, or by table reorganization.
However, it is not possible to perform DDL concurrently with table
reorganization--that is, no other DDL statements can be issued while an
'ALTER TABLE ... REORGANIZE PARTITION' statement is
executing.  In addition, during the execution of 'ALTER TABLE ...
REORGANIZE PARTITION' (or the execution of any other DDL statement), it
is not possible to restart cluster data nodes.

Failure handling

Failures of data nodes during node group creation and table
reorganization are handled as shown in the following table:

*Data node failure handling during node group creation and table
reorganization*

Failure during     Failure in 'Old'   Failure in 'New'   System Failure
                   data node          data node

Node group
creation              * If a node        * If a node        * If the
                        other than         other than         execution
                        the master         the master         of CREATE
                        fails:             fails:             NODEGROUP
                                                              has reached
                        The                The                the
                        creation of        creation of        internal
                        the node           the node           commit
                        group is           group is           point:
                        always             always
                        rolled             rolled             When
                        forward.           forward.           restarted,
                                                              the cluster
                      * If the           * If the             includes
                        master             master             the new
                        fails:             fails:             node group.
                                                              Otherwise
                           * If the           * If the        it without.
                             internal           internal
                             commit             commit      * If the
                             point              point         execution
                             has                has           of CREATE
                             been               been          NODEGROUP
                             reached:           reached:      has not yet
                                                              reached the
                             The                The           internal
                             creation           creation      commit
                             of the             of the        point:
                             node               node
                             group              group         When
                             is                 is            restarted,
                             rolled             rolled        the cluster
                             forward.           forward.      does not
                                                              include the
                           * If the           * If the        new node
                             internal           internal      group.
                             commit             commit
                             point              point
                             has                has
                             not                not
                             yet                yet
                             been               been
                             reached            reached

                             The                The
                             creation           creation
                             of the             of the
                             node               node
                             group              group
                             is                 is
                             rolled             rolled
                             back               back

Table
reorganization        * If a node        * If a node        * If the
                        other than         other than         execution
                        the master         the master         of an ALTER
                        fails:             fails:             TABLE ...
                                                              REORGANIZE
                        The table          The table          PARTITION
                        reorganization     reorganization     statement
                        is always          is always          has reached
                        rolled             rolled             the
                        forward.           forward.           internal
                                                              commit
                      * If the           * If the             point:
                        master             master
                        fails:             fails:             When the
                                                              cluster is
                           * If the           * If the        restarted,
                             internal           internal      the data
                             commit             commit        and indexes
                             point              point         belonging
                             has                has           to TABLE
                             been               been          are
                             reached:           reached:      distributed
                                                              using the
                             The                The           'new' data
                             table              table         nodes.
                             reorganization          reorganization
                             is                 is          * If the
                             rolled             rolled        execution
                             forward.           forward.      of an ALTER
                                                              TABLE ...
                           * If the           * If the        REORGANIZE
                             internal           internal      PARTITION
                             commit             commit        statement
                             point              point         has not yet
                             has                has           reached the
                             not                not           internal
                             yet                yet           commit
                             been               been          point:
                             reached            reached
                                                              When the
                             The                The           cluster is
                             table              table         restarted,
                             reorganization          reorganization     the data
                             is                 is            and indexes
                             rolled             rolled        belonging
                             back.              back.         to TABLE
                                                              are
                                                              distributed
                                                              using only
                                                              the 'old'
                                                              data nodes.

Dropping node groups

The 'ndb_mgm' client supports a
'DROP NODEGROUP' command, but it is possible to drop a node group only
when no data nodes in the node group contain any data.  Since there is
currently no way to 'empty' a specific data node or node group, this
command works only the following two cases:

  1. After issuing 'CREATE NODEGROUP' in the 'ndb_mgm'
     client, but before issuing any
     'ALTER TABLE ... REORGANIZE PARTITION'.
     statements in the 'mysql' client.

  2. After dropping all 'NDBCLUSTER' tables using
     'DROP TABLE'.

     'TRUNCATE TABLE' does not work for this
     purpose because the data nodes continue to store the table
     definitions.

21.5.14.2 Adding NDB Cluster Data Nodes Online: Basic procedure
...............................................................

In this section, we list the basic steps required to add new data nodes
to an NDB Cluster.  This procedure applies whether you are using
'ndbd' or 'ndbmtd'
binaries for the data node processes.
For a more detailed example, see
mysql-cluster-online-add-node-example.

Assuming that you already have a running NDB Cluster, adding data nodes
online requires the following steps:

  1. Edit the cluster configuration 'config.ini' file, adding new
     '[ndbd]' sections corresponding to the nodes to be added.  In the
     case where the cluster uses multiple management servers, these
     changes need to be made to all 'config.ini' files used by the
     management servers.

     You must be careful that node IDs for any new data nodes added in
     the 'config.ini' file do not overlap node IDs used by existing
     nodes.  In the event that you have API nodes using dynamically
     allocated node IDs and these IDs match node IDs that you want to
     use for new data nodes, it is possible to force any such API nodes
     to 'migrate', as described later in this procedure.

  2. Perform a rolling restart of all NDB Cluster management servers.

     *Important*:

     All management servers must be restarted with the '--reload' or
     '--initial' option to force the reading of the new configuration.

  3. Perform a rolling restart of all existing NDB Cluster data nodes.
     It is not necessary (or usually even desirable) to use '--initial'
     when restarting the existing data nodes.

     If you are using API nodes with dynamically allocated IDs matching
     any node IDs that you wish to assign to new data nodes, you must
     restart all API nodes (including SQL nodes) before restarting any
     of the data nodes processes in this step.  This causes any API
     nodes with node IDs that were previously not explicitly assigned to
     relinquish those node IDs and acquire new ones.

  4. Perform a rolling restart of any SQL or API nodes connected to the
     NDB Cluster.

  5. Start the new data nodes.

     The new data nodes may be started in any order.  They can also be
     started concurrently, as long as they are started after the rolling
     restarts of all existing data nodes have been completed, and before
     proceeding to the next step.

  6. Execute one or more 'CREATE NODEGROUP' commands in the NDB Cluster
     management client to create the new node group or node groups to
     which the new data nodes will belong.

  7. Redistribute the cluster's data among all data nodes, including the
     new ones.  Normally this is done by issuing an 'ALTER TABLE ... ALGORITHM=INPLACE, REORGANIZE PARTITION'.
     statement in the 'mysql' client for each
     'NDBCLUSTER' table.

     _Exception_: For tables created using the 'MAX_ROWS' option, this
     statement does not work; instead, use 'ALTER TABLE ...
     ALGORITHM=INPLACE MAX_ROWS=...' to reorganize such tables.  You
     should also bear in mind that using 'MAX_ROWS' to set the number of
     partitions in this fashion is deprecated in NDB 7.5.4 and later,
     where you should use 'PARTITION_BALANCE' instead; see
     create-table-ndb-table-comment-options, for more information.

     *Note*:

     This needs to be done only for tables already existing at the time
     the new node group is added.  Data in tables created after the new
     node group is added is distributed automatically; however, data
     added to any given table 'tbl' that existed before the new nodes
     were added is not distributed using the new nodes until that table
     has been reorganized.

  8. 'ALTER TABLE ... REORGANIZE PARTITION ALGORITHM=INPLACE'
     reorganizes partitions but does not reclaim the space freed on the
     'old' nodes.  You can do this by issuing, for each
     'NDBCLUSTER' table, an 'OPTIMIZE TABLE'
     statement in the 'mysql' client.

     This works for space used by variable-width columns of in-memory
     'NDB' tables.  'OPTIMIZE TABLE' is not supported for fixed-width
     columns of in-memory tables; it is also not supported for Disk Data
     tables.

You can add all the nodes desired, then issue several 'CREATE NODEGROUP'
commands in succession to add the new node groups to the cluster.

21.5.14.3 Adding NDB Cluster Data Nodes Online: Detailed Example
................................................................

In this section we provide a detailed example illustrating how to add
new NDB Cluster data nodes online, starting with an NDB Cluster having 2
data nodes in a single node group and concluding with a cluster having 4
data nodes in 2 node groups.

Starting configuration

For purposes of illustration, we assume a minimal configuration, and
that the cluster uses a 'config.ini' file containing only the following
information:

     [ndbd default]
     DataMemory = 100M
     IndexMemory = 100M
     NoOfReplicas = 2
     DataDir = /usr/local/mysql/var/mysql-cluster

     [ndbd]
     Id = 1
     HostName = 198.51.100.1

     [ndbd]
     Id = 2
     HostName = 198.51.100.2

     [mgm]
     HostName = 198.51.100.10
     Id = 10

     [api]
     Id=20
     HostName = 198.51.100.20

     [api]
     Id=21
     HostName = 198.51.100.21

*Note*:

We have left a gap in the sequence between data node IDs and other
nodes.  This make it easier later to assign node IDs that are not
already in use to data nodes which are newly added.

We also assume that you have already started the cluster using the
appropriate command line or 'my.cnf' options, and that running 'SHOW' in
the management client produces output similar to what is shown here:

     -- NDB Cluster -- Management Client --
     ndb_mgm> SHOW
     Connected to Management Server at: 198.51.100.10:1186
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     2 node(s)
     id=1    @198.51.100.1  (5.7.22-ndb-7.5.11, Nodegroup: 0, *)
     id=2    @198.51.100.2  (5.7.22-ndb-7.5.11, Nodegroup: 0)

     [ndb_mgmd(MGM)] 1 node(s)
     id=10   @198.51.100.10  (5.7.22-ndb-7.5.11)

     [mysqld(API)]   2 node(s)
     id=20   @198.51.100.20  (5.7.22-ndb-7.5.11)
     id=21   @198.51.100.21  (5.7.22-ndb-7.5.11)

Finally, we assume that the cluster contains a single
'NDBCLUSTER' table created as shown here:

     USE n;

     CREATE TABLE ips (
         id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         country_code CHAR(2) NOT NULL,
         type CHAR(4) NOT NULL,
         ip_address VARCHAR(15) NOT NULL,
         addresses BIGINT UNSIGNED DEFAULT NULL,
         date BIGINT UNSIGNED DEFAULT NULL
     )   ENGINE NDBCLUSTER;

The memory usage and related information shown later in this section was
generated after inserting approximately 50000 rows into this table.

*Note*:

In this example, we show the single-threaded 'ndbd'
being used for the data node processes.
You can also apply this example, if you are using the multi-threaded
'ndbmtd' by substituting
'ndbmtd' for 'ndbd'
wherever it appears in the steps that
follow.

Step 1: Update configuration file

Open the cluster global configuration file in a text editor and add
'[ndbd]' sections corresponding to the 2 new data nodes.  (We give these
data nodes IDs 3 and 4, and assume that they are to be run on host
machines at addresses 198.51.100.3 and 198.51.100.4, respectively.)
After you have added the new sections, the contents of the 'config.ini'
file should look like what is shown here, where the additions to the
file are shown in bold type:

     [ndbd default]
     DataMemory = 100M
     IndexMemory = 100M
     NoOfReplicas = 2
     DataDir = /usr/local/mysql/var/mysql-cluster

     [ndbd]
     Id = 1
     HostName = 198.51.100.1

     [ndbd]
     Id = 2
     HostName = 198.51.100.2

     *[ndbd]
     Id = 3
     HostName = 198.51.100.3

     [ndbd]
     Id = 4
     HostName = 198.51.100.4*

     [mgm]
     HostName = 198.51.100.10
     Id = 10

     [api]
     Id=20
     HostName = 198.51.100.20

     [api]
     Id=21
     HostName = 198.51.100.21

Once you have made the necessary changes, save the file.

Step 2: Restart the management server

Restarting the cluster management server requires that you issue
separate commands to stop the management server and then to start it
again, as follows:

  1. Stop the management server using the management client 'STOP'
     command, as shown here:

          ndb_mgm> 10 STOP
          Node 10 has shut down.
          Disconnecting to allow Management Server to shutdown

          shell>

  2. Because shutting down the management server causes the management
     client to terminate, you must start the management server from the
     system shell.  For simplicity, we assume that 'config.ini' is in
     the same directory as the management server binary, but in
     practice, you must supply the correct path to the configuration
     file.  You must also supply the '--reload' or '--initial' option so
     that the management server reads the new configuration from the
     file rather than its configuration cache.  If your shell's current
     directory is also the same as the directory where the management
     server binary is located, then you can invoke the management server
     as shown here:

          shell> ndb_mgmd -f config.ini --reload
          2008-12-08 17:29:23 [MgmSrvr] INFO     -- NDB Cluster Management Server. 5.7.22-ndb-7.5.11
          2008-12-08 17:29:23 [MgmSrvr] INFO     -- Reading cluster configuration from 'config.ini'

If you check the output of 'SHOW' in the management client after
restarting the 'ndb_mgm' process,
you should now see something like this:

     -- NDB Cluster -- Management Client --
     ndb_mgm> SHOW
     Connected to Management Server at: 198.51.100.10:1186
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     2 node(s)
     id=1    @198.51.100.1  (5.7.22-ndb-7.5.11, Nodegroup: 0, *)
     id=2    @198.51.100.2  (5.7.22-ndb-7.5.11, Nodegroup: 0)
     id=3 (not connected, accepting connect from 198.51.100.3)
     id=4 (not connected, accepting connect from 198.51.100.4)

     [ndb_mgmd(MGM)] 1 node(s)
     id=10   @198.51.100.10  (5.7.22-ndb-7.5.11)

     [mysqld(API)]   2 node(s)
     id=20   @198.51.100.20  (5.7.22-ndb-7.5.11)
     id=21   @198.51.100.21  (5.7.22-ndb-7.5.11)

Step 3: Perform a rolling restart of the existing data nodes

This step can be accomplished entirely within the cluster management
client using the 'RESTART' command, as shown here:

     ndb_mgm> 1 RESTART
     Node 1: Node shutdown initiated
     Node 1: Node shutdown completed, restarting, no start.
     Node 1 is being restarted

     ndb_mgm> Node 1: Start initiated (version 7.5.11)
     Node 1: Started (version 7.5.11)

     ndb_mgm> 2 RESTART
     Node 2: Node shutdown initiated
     Node 2: Node shutdown completed, restarting, no start.
     Node 2 is being restarted

     ndb_mgm> Node 2: Start initiated (version 7.5.11)

     ndb_mgm> Node 2: Started (version 7.5.11)

*Important*:

After issuing each 'X RESTART' command, wait until the management client
reports 'Node X: Started (version ...)' _before_ proceeding any further.

You can verify that all existing data nodes were restarted using the
updated configuration by checking the 'ndbinfo.nodes'
table in the 'mysql' client.

Step 4: Perform a rolling restart of all cluster API nodes

Shut down and restart each MySQL server acting as an SQL node in the
cluster using 'mysqladmin shutdown' followed by
'mysqld_safe'. (or another startup script).  This should be
similar to what is shown here, where PASSWORD is the MySQL 'root'
password for a given MySQL server instance:

     shell> mysqladmin -uroot -pPASSWORD shutdown
     081208 20:19:56 mysqld_safe mysqld from pid file
     /usr/local/mysql/var/tonfisk.pid ended
     shell> mysqld_safe --ndbcluster --ndb-connectstring=198.51.100.10 &
     081208 20:20:06 mysqld_safe Logging to '/usr/local/mysql/var/tonfisk.err'.
     081208 20:20:06 mysqld_safe Starting mysqld daemon with databases
     from /usr/local/mysql/var

Of course, the exact input and output depend on how and where MySQL is
installed on the system, as well as which options you choose to start it
(and whether or not some or all of these options are specified in a
'my.cnf' file).

Step 5: Perform an initial start of the new data nodes

From a system shell on each of the hosts for the new data nodes, start
the data nodes as shown here, using the '--initial' option:

     shell> ndbd -c 198.51.100.10 --initial

*Note*:

Unlike the case with restarting the existing data nodes, you can start
the new data nodes concurrently; you do not need to wait for one to
finish starting before starting the other.

_Wait until both of the new data nodes have started before proceeding
with the next step_.  Once the new data nodes have started, you can see
in the output of the management client 'SHOW' command that they do not
yet belong to any node group (as indicated with bold type here):

     ndb_mgm> SHOW
     Connected to Management Server at: 198.51.100.10:1186
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     2 node(s)
     id=1    @198.51.100.1  (5.7.22-ndb-7.5.11, Nodegroup: 0, *)
     id=2    @198.51.100.2  (5.7.22-ndb-7.5.11, Nodegroup: 0)
     id=3    @198.51.100.3  (5.7.22-ndb-7.5.11, *no nodegroup*)
     id=4    @198.51.100.4  (5.7.22-ndb-7.5.11, *no nodegroup*)

     [ndb_mgmd(MGM)] 1 node(s)
     id=10   @198.51.100.10  (5.7.22-ndb-7.5.11)

     [mysqld(API)]   2 node(s)
     id=20   @198.51.100.20  (5.7.22-ndb-7.5.11)
     id=21   @198.51.100.21  (5.7.22-ndb-7.5.11)

Step 6: Create a new node group

You can do this by issuing a 'CREATE NODEGROUP' command in the cluster
management client.  This command takes as its argument a comma-separated
list of the node IDs of the data nodes to be included in the new node
group, as shown here:

     ndb_mgm> CREATE NODEGROUP 3,4
     Nodegroup 1 created

By issuing 'SHOW' again, you can verify that data nodes 3 and 4 have
joined the new node group (again indicated in bold type):

     ndb_mgm> SHOW
     Connected to Management Server at: 198.51.100.10:1186
     Cluster Configuration
     ---------------------
     [ndbd(NDB)]     2 node(s)
     id=1    @198.51.100.1  (5.7.22-ndb-7.5.11, Nodegroup: 0, *)
     id=2    @198.51.100.2  (5.7.22-ndb-7.5.11, Nodegroup: 0)
     id=3    @198.51.100.3  (5.7.22-ndb-7.5.11, *Nodegroup: 1*)
     id=4    @198.51.100.4  (5.7.22-ndb-7.5.11, *Nodegroup: 1*)

     [ndb_mgmd(MGM)] 1 node(s)
     id=10   @198.51.100.10  (5.7.22-ndb-7.5.11)

     [mysqld(API)]   2 node(s)
     id=20   @198.51.100.20  (5.7.22-ndb-7.5.11)
     id=21   @198.51.100.21  (5.7.22-ndb-7.5.11)

Step 7: Redistribute cluster data

When a node group is created, existing data and indexes are not
automatically distributed to the new node group's data nodes, as you can
see by issuing the appropriate 'REPORT' command in the management
client:

     ndb_mgm> ALL REPORT MEMORY

     Node 1: Data usage is 5%(177 32K pages of total 3200)
     Node 1: Index usage is 0%(108 8K pages of total 12832)
     Node 2: Data usage is 5%(177 32K pages of total 3200)
     Node 2: Index usage is 0%(108 8K pages of total 12832)
     *Node 3: Data usage is 0%(0 32K pages of total 3200)
     Node 3: Index usage is 0%(0 8K pages of total 12832)
     Node 4: Data usage is 0%(0 32K pages of total 3200)
     Node 4: Index usage is 0%(0 8K pages of total 12832)*

By using 'ndb_desc' with the
'-p' option, which causes the output to include partitioning
information, you can see that the table still uses only 2 partitions (in
the 'Per partition info' section of the output, shown here in bold
text):

     shell> ndb_desc -c 198.51.100.10 -d n ips -p
     -- ips --
     Version: 1
     Fragment type: 9
     K Value: 6
     Min load factor: 78
     Max load factor: 80
     Temporary table: no
     Number of attributes: 6
     Number of primary keys: 1
     Length of frm data: 340
     Row Checksum: 1
     Row GCI: 1
     SingleUserMode: 0
     ForceVarPart: 1
     FragmentCount: 2
     TableStatus: Retrieved
     -- Attributes --
     id Bigint PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
     country_code Char(2;latin1_swedish_ci) NOT NULL AT=FIXED ST=MEMORY
     type Char(4;latin1_swedish_ci) NOT NULL AT=FIXED ST=MEMORY
     ip_address Varchar(15;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
     addresses Bigunsigned NULL AT=FIXED ST=MEMORY
     date Bigunsigned NULL AT=FIXED ST=MEMORY

     -- Indexes --
     PRIMARY KEY(id) - UniqueHashIndex
     PRIMARY(id) - OrderedIndex

     *-- Per partition info --
     Partition   Row count   Commit count  Frag fixed memory   Frag varsized memory
     0           26086       26086         1572864             557056
     1           26329       26329         1605632             557056*

     NDBT_ProgramExit: 0 - OK

You can cause the data to be redistributed among all of the data nodes
by performing, for each 'NDB' table, an
'ALTER TABLE ... ALGORITHM=INPLACE, REORGANIZE PARTITION'.
statement in the 'mysql' client.

*Important*:

'ALTER TABLE ... ALGORITHM=INPLACE, REORGANIZE PARTITION' does not work
on tables that were created with the 'MAX_ROWS' option.  Instead, use
'ALTER TABLE ... ALGORITHM=INPLACE, MAX_ROWS=...' to reorganize such
tables.

Keep in mind that using 'MAX_ROWS' to set the number of partitions per
table is deprecated in NDB 7.5.4 and later, where you should use
'PARTITION_BALANCE' instead; see
create-table-ndb-table-comment-options, for more information.

After issuing the statement 'ALTER TABLE ips ALGORITHM=INPLACE,
REORGANIZE PARTITION', you can see using 'ndb_desc'
that the data for this table is now
stored using 4 partitions, as shown here (with the relevant portions of
the output in bold type):

     shell> ndb_desc -c 198.51.100.10 -d n ips -p
     -- ips --
     Version: 16777217
     Fragment type: 9
     K Value: 6
     Min load factor: 78
     Max load factor: 80
     Temporary table: no
     Number of attributes: 6
     Number of primary keys: 1
     Length of frm data: 341
     Row Checksum: 1
     Row GCI: 1
     SingleUserMode: 0
     ForceVarPart: 1
     FragmentCount: 4
     TableStatus: Retrieved
     -- Attributes --
     id Bigint PRIMARY KEY DISTRIBUTION KEY AT=FIXED ST=MEMORY AUTO_INCR
     country_code Char(2;latin1_swedish_ci) NOT NULL AT=FIXED ST=MEMORY
     type Char(4;latin1_swedish_ci) NOT NULL AT=FIXED ST=MEMORY
     ip_address Varchar(15;latin1_swedish_ci) NOT NULL AT=SHORT_VAR ST=MEMORY
     addresses Bigunsigned NULL AT=FIXED ST=MEMORY
     date Bigunsigned NULL AT=FIXED ST=MEMORY

     -- Indexes --
     PRIMARY KEY(id) - UniqueHashIndex
     PRIMARY(id) - OrderedIndex

     *-- Per partition info --
     Partition   Row count   Commit count  Frag fixed memory   Frag varsized memory
     0           12981       52296         1572864             557056
     1           13236       52515         1605632             557056
     2           13105       13105         819200              294912
     3           13093       13093         819200              294912*

     NDBT_ProgramExit: 0 - OK

*Note*:

Normally, see 'ALTER TABLE TABLE_NAME [ALGORITHM=INPLACE,] REORGANIZE PARTITION'
is used with a list of partition identifiers
and a set of partition definitions to create a new partitioning scheme
for a table that has already been explicitly partitioned.  Its use here
to redistribute data onto a new NDB Cluster node group is an exception
in this regard; when used in this way, no other keywords or identifiers
follow 'REORGANIZE PARTITION'.

For more information, see alter-table.

In addition, for each table, the 'ALTER TABLE'.
statement should be followed by an 'OPTIMIZE TABLE'
to reclaim wasted space.  You can obtain a list of all
'NDBCLUSTER' tables using the following query
against the 'INFORMATION_SCHEMA.TABLES' table:

     SELECT TABLE_SCHEMA, TABLE_NAME
         FROM INFORMATION_SCHEMA.TABLES
         WHERE ENGINE = 'NDBCLUSTER';

*Note*:

The 'INFORMATION_SCHEMA.TABLES.ENGINE' value for an NDB Cluster table is
always 'NDBCLUSTER', regardless of whether the
'CREATE TABLE' statement used to create the table (or 'ALTER TABLE'
statement used to convert an existing table from a
different storage engine) used 'NDB' or
'NDBCLUSTER' in its 'ENGINE' option.

You can see after performing these statements in the output of 'ALL
REPORT MEMORY' that the data and indexes are now redistributed between
all cluster data nodes, as shown here:

     ndb_mgm> ALL REPORT MEMORY

     Node 1: Data usage is 5%(176 32K pages of total 3200)
     Node 1: Index usage is 0%(76 8K pages of total 12832)
     Node 2: Data usage is 5%(176 32K pages of total 3200)
     Node 2: Index usage is 0%(76 8K pages of total 12832)
     Node 3: Data usage is 2%(80 32K pages of total 3200)
     Node 3: Index usage is 0%(51 8K pages of total 12832)
     Node 4: Data usage is 2%(80 32K pages of total 3200)
     Node 4: Index usage is 0%(50 8K pages of total 12832)

*Note*:

Since only one DDL operation on 'NDBCLUSTER'.
tables can be executed at a time, you must wait for each 'ALTER TABLE ... REORGANIZE PARTITION'
statement to finish before
issuing the next one.

It is not necessary to issue 'ALTER TABLE ... REORGANIZE PARTITION'
statements for 'NDBCLUSTER'
tables created _after_ the new data nodes have been
added; data added to such tables is distributed among all data nodes
automatically.  However, in 'NDBCLUSTER' tables
that existed _prior to_ the addition of the new nodes, neither existing
nor new data is distributed using the new nodes until these tables have
been reorganized using 'ALTER TABLE ... REORGANIZE PARTITION'.

Alternative procedure, without rolling restart

It is possible to avoid the need for a rolling restart by configuring
the extra data nodes, but not starting them, when first starting the
cluster.  We assume, as before, that you wish to start with two data
nodes--nodes 1 and 2--in one node group and later to expand the cluster
to four data nodes, by adding a second node group consisting of nodes 3
and 4:

     [ndbd default]
     DataMemory = 100M
     IndexMemory = 100M
     NoOfReplicas = 2
     DataDir = /usr/local/mysql/var/mysql-cluster

     [ndbd]
     Id = 1
     HostName = 198.51.100.1

     [ndbd]
     Id = 2
     HostName = 198.51.100.2

     [ndbd]
     Id = 3
     HostName = 198.51.100.3
     Nodegroup = 65536

     [ndbd]
     Id = 4
     HostName = 198.51.100.4
     Nodegroup = 65536

     [mgm]
     HostName = 198.51.100.10
     Id = 10

     [api]
     Id=20
     HostName = 198.51.100.20

     [api]
     Id=21
     HostName = 198.51.100.21

The data nodes to be brought online at a later time (nodes 3 and 4) can
be configured with 'NodeGroup = 65536', in which case nodes 1 and 2 can
each be started as shown here:

     shell> ndbd -c 198.51.100.10 --initial

The data nodes configured with 'NodeGroup = 65536' are treated by the
management server as though you had started nodes 1 and 2 using
'--nowait-nodes=3,4' after waiting for a period of time determined by
the setting for the 'StartNoNodeGroupTimeout' data node configuration
parameter.  By default, this is 15 seconds (15000 milliseconds).

*Note*:

'StartNoNodegroupTimeout' must be the same for all data nodes in the
cluster; for this reason, you should always set it in the '[ndbd
default]' section of the 'config.ini' file, rather than for individual
data nodes.

When you are ready to add the second node group, you need only perform
the following additional steps:

  1. Start data nodes 3 and 4, invoking the data node process once for
     each new node:

          shell> ndbd -c 198.51.100.10 --initial

  2. Issue the appropriate 'CREATE NODEGROUP' command in the management
     client:

          ndb_mgm> CREATE NODEGROUP 3,4

  3. In the 'mysql' client, issue 'ALTER TABLE ... REORGANIZE PARTITION'
     and 'OPTIMIZE TABLE'
     statements for each existing 'NDBCLUSTER'
     table.  (As noted elsewhere in this section,
     existing NDB Cluster tables cannot use the new nodes for data
     distribution until this has been done.)

21.5.15 Distributed MySQL Privileges for NDB Cluster
----------------------------------------------------

NDB Cluster supports distribution of MySQL users and privileges across
all SQL nodes in an NDB Cluster.  This support is not enabled by
default; you should follow the procedure outlined in this section in
order to do so.

Normally, each MySQL server's user privilege tables in the 'mysql'
database must use the 'MyISAM' storage
engine, which means that a user account and its associated privileges
created on one SQL node are not available on the cluster's other SQL
nodes.  An SQL file 'ndb_dist_priv.sql' provided with the NDB Cluster
distribution can be found in the 'share' directory in the MySQL
installation directory.

The first step in enabling distributed privileges is to load this script
into a MySQL Server that functions as an SQL node (which we refer to
after this as the _target_ SQL node or MySQL Server).  You can do this
by executing the following command from the system shell on the target
SQL node after changing to its MySQL installation directory (where
OPTIONS stands for any additional options needed to connect to this SQL
node):

     shell> mysql OPTIONS -uroot < share/ndb_dist_priv.sql

Importing 'ndb_dist_priv.sql' creates a number of stored routines (six
stored procedures and one stored function) in the 'mysql' database on
the target SQL node.  After connecting to the SQL node in the
'mysql' client (as the MySQL 'root' user), you can verify that
these were created as shown here:

     mysql> SELECT ROUTINE_NAME, ROUTINE_SCHEMA, ROUTINE_TYPE
         ->     FROM INFORMATION_SCHEMA.ROUTINES
         ->     WHERE ROUTINE_NAME LIKE 'mysql_cluster%'
         ->     ORDER BY ROUTINE_TYPE;
     +---------------------------------------------+----------------+--------------+
     | ROUTINE_NAME                                | ROUTINE_SCHEMA | ROUTINE_TYPE |
     +---------------------------------------------+----------------+--------------+
     | mysql_cluster_privileges_are_distributed    | mysql          | FUNCTION     |
     | mysql_cluster_backup_privileges             | mysql          | PROCEDURE    |
     | mysql_cluster_move_grant_tables             | mysql          | PROCEDURE    |
     | mysql_cluster_move_privileges               | mysql          | PROCEDURE    |
     | mysql_cluster_restore_local_privileges      | mysql          | PROCEDURE    |
     | mysql_cluster_restore_privileges            | mysql          | PROCEDURE    |
     | mysql_cluster_restore_privileges_from_local | mysql          | PROCEDURE    |
     +---------------------------------------------+----------------+--------------+
     7 rows in set (0.01 sec)

The stored procedure named 'mysql_cluster_move_privileges' creates
backup copies of the existing privilege tables, then converts them to
'NDB'.

'mysql_cluster_move_privileges' performs the backup and conversion in
two steps.  The first step is to call 'mysql_cluster_backup_privileges',
which creates two sets of copies in the 'mysql' database:

   * A set of local copies that use the 'MyISAM'
     storage engine.  Their names are generated
     by adding the suffix '_backup' to the original privilege table
     names.

   * A set of distributed copies that use the 'NDBCLUSTER'
     storage engine.  These tables are named by prefixing
     'ndb_' and appending '_backup' to the names of the original tables.

After the copies are created, 'mysql_cluster_move_privileges' invokes
'mysql_cluster_move_grant_tables', which contains the 'ALTER TABLE ... ENGINE = NDB'
statements that convert the mysql system
tables to 'NDB'.

Normally, you should not invoke either 'mysql_cluster_backup_privileges'
or 'mysql_cluster_move_grant_tables' manually; these stored procedures
are intended only for use by 'mysql_cluster_move_privileges'.

Although the original privilege tables are backed up automatically, it
is always a good idea to create backups manually of the existing
privilege tables on all affected SQL nodes before proceeding.  You can
do this using 'mysqldump' in a manner similar to what
is shown here:

     shell> mysqldump OPTIONS -uroot \
         mysql user db tables_priv columns_priv procs_priv proxies_priv > BACKUP_FILE

To perform the conversion, you must be connected to the target SQL node
using the 'mysql' client (again, as the MySQL 'root'
user).  Invoke the stored procedure like this:

     mysql> CALL mysql.mysql_cluster_move_privileges();
     Query OK, 0 rows affected (22.32 sec)

Depending on the number of rows in the privilege tables, this procedure
may take some time to execute.  If some of the privilege tables are
empty, you may see one or more 'No data - zero rows fetched, selected,
or processed' warnings when 'mysql_cluster_move_privileges' returns.  In
such cases, the warnings may be safely ignored.  To verify that the
conversion was successful, you can use the stored function
'mysql_cluster_privileges_are_distributed' as shown here:

     mysql> SELECT CONCAT(
         ->    'Conversion ',
         ->    IF(mysql.mysql_cluster_privileges_are_distributed(), 'succeeded', 'failed'),
         ->    '.')
         ->    AS Result;
     +-----------------------+
     | Result                |
     +-----------------------+
     | Conversion succeeded. |
     +-----------------------+
     1 row in set (0.00 sec)

'mysql_cluster_privileges_are_distributed' checks for the existence of
the distributed privilege tables and returns '1' if all of the privilege
tables are distributed; otherwise, it returns '0'.

You can verify that the backups have been created using a query such as
this one:

     mysql> SELECT TABLE_NAME, ENGINE FROM INFORMATION_SCHEMA.TABLES
         ->     WHERE TABLE_SCHEMA = 'mysql' AND TABLE_NAME LIKE '%backup'
         ->     ORDER BY ENGINE;
     +-------------------------+------------+
     | TABLE_NAME              | ENGINE     |
     +-------------------------+------------+
     | db_backup               | MyISAM     |
     | user_backup             | MyISAM     |
     | columns_priv_backup     | MyISAM     |
     | tables_priv_backup      | MyISAM     |
     | proxies_priv_backup     | MyISAM     |
     | procs_priv_backup       | MyISAM     |
     | ndb_columns_priv_backup | ndbcluster |
     | ndb_user_backup         | ndbcluster |
     | ndb_tables_priv_backup  | ndbcluster |
     | ndb_proxies_priv_backup | ndbcluster |
     | ndb_procs_priv_backup   | ndbcluster |
     | ndb_db_backup           | ndbcluster |
     +-------------------------+------------+
     12 rows in set (0.00 sec)

Once the conversion to distributed privileges has been made, any time a
MySQL user account is created, dropped, or has its privileges updated on
any SQL node, the changes take effect immediately on all other MySQL
servers attached to the cluster.  Once privileges are distributed, any
new MySQL Servers that connect to the cluster automatically participate
in the distribution.

*Note*:

For clients connected to SQL nodes at the time that
'mysql_cluster_move_privileges' is executed, you may need to execute
'FLUSH PRIVILEGES' on those SQL nodes, or to disconnect and then
reconnect the clients, in order for those clients to be able to see the
changes in privileges.

All MySQL user privileges are distributed across all connected MySQL
Servers.  This includes any privileges associated with views and stored
routines, even though distribution of views and stored routines
themselves is not currently supported.

In the event that an SQL node becomes disconnected from the cluster
while 'mysql_cluster_move_privileges' is running, you must drop its
privilege tables after reconnecting to the cluster, using a statement
such as 'DROP TABLE IF EXISTS mysql.user mysql.db mysql.tables_priv mysql.columns_priv mysql.procs_priv'.
This causes the SQL node to use the shared privilege tables rather than
its own local versions of them.  This is not needed when connecting a
new SQL node to the cluster for the first time.

In the event of an initial restart of the entire cluster (all data nodes
shut down, then started again with '--initial'), the shared privilege
tables are lost.  If this happens, you can restore them using the
original target SQL node either from the backups made by
'mysql_cluster_move_privileges' or from a dump file created with
'mysqldump'.  If you need to use a new MySQL Server to
perform the restoration, you should start it with '--skip-grant-tables'
when connecting to the cluster for the first time; after this, you can
restore the privilege tables locally, then distribute them again using
'mysql_cluster_move_privileges'.  After restoring and distributing the
tables, you should restart this MySQL Server without the
'--skip-grant-tables' option.

You can also restore the distributed tables using 'ndb_restore'.
'--restore-privilege-tables' from a
backup made using 'START BACKUP'
in the 'ndb_mgm'
client.  (The 'MyISAM'
tables created by 'mysql_cluster_move_privileges'
are not backed up by the 'START BACKUP' command.)  'ndb_restore'
does not restore the privilege
tables by default; the '--restore-privilege-tables' option causes it to
do so.

You can restore the SQL node's local privileges using either of two
procedures.  'mysql_cluster_restore_privileges' works as follows:

  1. If copies of the 'mysql.ndb_*_backup' tables are available, attempt
     to restore the system tables from these.

  2. Otherwise, attempt to restore the system tables from the local
     backups named '*_backup' (without the 'ndb_' prefix).

The other procedure, named 'mysql_cluster_restore_local_privileges',
restores the system tables from the local backups only, without checking
the 'ndb_*' backups.

The system tables re-created by 'mysql_cluster_restore_privileges' or
'mysql_cluster_restore_local_privileges' use the MySQL server default
storage engine; they are not shared or distributed in any way, and do
not use NDB Cluster's 'NDB' storage engine.

The additional stored procedure
'mysql_cluster_restore_privileges_from_local' is intended for the use of
'mysql_cluster_restore_privileges' and
'mysql_cluster_restore_local_privileges'.  It should not be invoked
directly.

*Important*:

Applications that access NDB Cluster data directly, including NDB API
and ClusterJ applications, are not subject to the MySQL privilege
system.  This means that, once you have distributed the grant tables,
they can be freely accessed by such applications, just as they can any
other 'NDB' tables.  In particular, you should
keep in mind that _NDB API and ClusterJ applications can read and write
user names, host names, password hashes, and any other contents of the
distributed grant tables without any restrictions_.

21.5.16 NDB API Statistics Counters and Variables
-------------------------------------------------

A number of types of statistical counters relating to actions performed
by or affecting 'Ndb' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html)
objects are available.  Such actions include starting and closing (or
aborting) transactions; primary key and unique key operations; table,
range, and pruned scans; threads blocked while waiting for the
completion of various operations; and data and events sent and received
by 'NDBCLUSTER'.  The counters are incremented inside the NDB kernel
whenever NDB API calls are made or data is sent to or received by the
data nodes.  'mysqld' exposes these counters as system
status variables; their values can be read in the output of 'SHOW STATUS',
or by querying the
'INFORMATION_SCHEMA.SESSION_STATUS' or
'INFORMATION_SCHEMA.GLOBAL_STATUS' table.  By comparing
the values before and after statements operating on 'NDB'
tables, you can observe the corresponding actions taken
on the API level, and thus the cost of performing the statement.

You can list all of these status variables using the following
'SHOW STATUS' statement:

     mysql> SHOW STATUS LIKE 'ndb_api%';
     +--------------------------------------------+----------+
     | Variable_name                              | Value    |
     +--------------------------------------------+----------+
     | Ndb_api_wait_exec_complete_count_session   | 0        |
     | Ndb_api_wait_scan_result_count_session     | 0        |
     | Ndb_api_wait_meta_request_count_session    | 0        |
     | Ndb_api_wait_nanos_count_session           | 0        |
     | Ndb_api_bytes_sent_count_session           | 0        |
     | Ndb_api_bytes_received_count_session       | 0        |
     | Ndb_api_trans_start_count_session          | 0        |
     | Ndb_api_trans_commit_count_session         | 0        |
     | Ndb_api_trans_abort_count_session          | 0        |
     | Ndb_api_trans_close_count_session          | 0        |
     | Ndb_api_pk_op_count_session                | 0        |
     | Ndb_api_uk_op_count_session                | 0        |
     | Ndb_api_table_scan_count_session           | 0        |
     | Ndb_api_range_scan_count_session           | 0        |
     | Ndb_api_pruned_scan_count_session          | 0        |
     | Ndb_api_scan_batch_count_session           | 0        |
     | Ndb_api_read_row_count_session             | 0        |
     | Ndb_api_trans_local_read_row_count_session | 0        |
     | Ndb_api_event_data_count_injector          | 0        |
     | Ndb_api_event_nondata_count_injector       | 0        |
     | Ndb_api_event_bytes_count_injector         | 0        |
     | Ndb_api_wait_exec_complete_count_slave     | 0        |
     | Ndb_api_wait_scan_result_count_slave       | 0        |
     | Ndb_api_wait_meta_request_count_slave      | 0        |
     | Ndb_api_wait_nanos_count_slave             | 0        |
     | Ndb_api_bytes_sent_count_slave             | 0        |
     | Ndb_api_bytes_received_count_slave         | 0        |
     | Ndb_api_trans_start_count_slave            | 0        |
     | Ndb_api_trans_commit_count_slave           | 0        |
     | Ndb_api_trans_abort_count_slave            | 0        |
     | Ndb_api_trans_close_count_slave            | 0        |
     | Ndb_api_pk_op_count_slave                  | 0        |
     | Ndb_api_uk_op_count_slave                  | 0        |
     | Ndb_api_table_scan_count_slave             | 0        |
     | Ndb_api_range_scan_count_slave             | 0        |
     | Ndb_api_pruned_scan_count_slave            | 0        |
     | Ndb_api_scan_batch_count_slave             | 0        |
     | Ndb_api_read_row_count_slave               | 0        |
     | Ndb_api_trans_local_read_row_count_slave   | 0        |
     | Ndb_api_wait_exec_complete_count           | 2        |
     | Ndb_api_wait_scan_result_count             | 3        |
     | Ndb_api_wait_meta_request_count            | 27       |
     | Ndb_api_wait_nanos_count                   | 45612023 |
     | Ndb_api_bytes_sent_count                   | 992      |
     | Ndb_api_bytes_received_count               | 9640     |
     | Ndb_api_trans_start_count                  | 2        |
     | Ndb_api_trans_commit_count                 | 1        |
     | Ndb_api_trans_abort_count                  | 0        |
     | Ndb_api_trans_close_count                  | 2        |
     | Ndb_api_pk_op_count                        | 1        |
     | Ndb_api_uk_op_count                        | 0        |
     | Ndb_api_table_scan_count                   | 1        |
     | Ndb_api_range_scan_count                   | 0        |
     | Ndb_api_pruned_scan_count                  | 0        |
     | Ndb_api_scan_batch_count                   | 0        |
     | Ndb_api_read_row_count                     | 1        |
     | Ndb_api_trans_local_read_row_count         | 1        |
     | Ndb_api_event_data_count                   | 0        |
     | Ndb_api_event_nondata_count                | 0        |
     | Ndb_api_event_bytes_count                  | 0        |
     +--------------------------------------------+----------+
     60 rows in set (0.02 sec)

These status variables are also available from the
'SESSION_STATUS' and 'GLOBAL_STATUS'.
tables of the 'INFORMATION_SCHEMA' database, as shown here:

     mysql> SELECT * FROM INFORMATION_SCHEMA.SESSION_STATUS
         ->   WHERE VARIABLE_NAME LIKE 'ndb_api%';
     +--------------------------------------------+----------------+
     | VARIABLE_NAME                              | VARIABLE_VALUE |
     +--------------------------------------------+----------------+
     | NDB_API_WAIT_EXEC_COMPLETE_COUNT_SESSION   | 2              |
     | NDB_API_WAIT_SCAN_RESULT_COUNT_SESSION     | 0              |
     | NDB_API_WAIT_META_REQUEST_COUNT_SESSION    | 1              |
     | NDB_API_WAIT_NANOS_COUNT_SESSION           | 8144375        |
     | NDB_API_BYTES_SENT_COUNT_SESSION           | 68             |
     | NDB_API_BYTES_RECEIVED_COUNT_SESSION       | 84             |
     | NDB_API_TRANS_START_COUNT_SESSION          | 1              |
     | NDB_API_TRANS_COMMIT_COUNT_SESSION         | 1              |
     | NDB_API_TRANS_ABORT_COUNT_SESSION          | 0              |
     | NDB_API_TRANS_CLOSE_COUNT_SESSION          | 1              |
     | NDB_API_PK_OP_COUNT_SESSION                | 1              |
     | NDB_API_UK_OP_COUNT_SESSION                | 0              |
     | NDB_API_TABLE_SCAN_COUNT_SESSION           | 0              |
     | NDB_API_RANGE_SCAN_COUNT_SESSION           | 0              |
     | NDB_API_PRUNED_SCAN_COUNT_SESSION          | 0              |
     | NDB_API_SCAN_BATCH_COUNT_SESSION           | 0              |
     | NDB_API_READ_ROW_COUNT_SESSION             | 1              |
     | NDB_API_TRANS_LOCAL_READ_ROW_COUNT_SESSION | 1              |
     | NDB_API_EVENT_DATA_COUNT_INJECTOR          | 0              |
     | NDB_API_EVENT_NONDATA_COUNT_INJECTOR       | 0              |
     | NDB_API_EVENT_BYTES_COUNT_INJECTOR         | 0              |
     | NDB_API_WAIT_EXEC_COMPLETE_COUNT_SLAVE     | 0              |
     | NDB_API_WAIT_SCAN_RESULT_COUNT_SLAVE       | 0              |
     | NDB_API_WAIT_META_REQUEST_COUNT_SLAVE      | 0              |
     | NDB_API_WAIT_NANOS_COUNT_SLAVE             | 0              |
     | NDB_API_BYTES_SENT_COUNT_SLAVE             | 0              |
     | NDB_API_BYTES_RECEIVED_COUNT_SLAVE         | 0              |
     | NDB_API_TRANS_START_COUNT_SLAVE            | 0              |
     | NDB_API_TRANS_COMMIT_COUNT_SLAVE           | 0              |
     | NDB_API_TRANS_ABORT_COUNT_SLAVE            | 0              |
     | NDB_API_TRANS_CLOSE_COUNT_SLAVE            | 0              |
     | NDB_API_PK_OP_COUNT_SLAVE                  | 0              |
     | NDB_API_UK_OP_COUNT_SLAVE                  | 0              |
     | NDB_API_TABLE_SCAN_COUNT_SLAVE             | 0              |
     | NDB_API_RANGE_SCAN_COUNT_SLAVE             | 0              |
     | NDB_API_PRUNED_SCAN_COUNT_SLAVE            | 0              |
     | NDB_API_SCAN_BATCH_COUNT_SLAVE             | 0              |
     | NDB_API_READ_ROW_COUNT_SLAVE               | 0              |
     | NDB_API_TRANS_LOCAL_READ_ROW_COUNT_SLAVE   | 0              |
     | NDB_API_WAIT_EXEC_COMPLETE_COUNT           | 4              |
     | NDB_API_WAIT_SCAN_RESULT_COUNT             | 3              |
     | NDB_API_WAIT_META_REQUEST_COUNT            | 28             |
     | NDB_API_WAIT_NANOS_COUNT                   | 53756398       |
     | NDB_API_BYTES_SENT_COUNT                   | 1060           |
     | NDB_API_BYTES_RECEIVED_COUNT               | 9724           |
     | NDB_API_TRANS_START_COUNT                  | 3              |
     | NDB_API_TRANS_COMMIT_COUNT                 | 2              |
     | NDB_API_TRANS_ABORT_COUNT                  | 0              |
     | NDB_API_TRANS_CLOSE_COUNT                  | 3              |
     | NDB_API_PK_OP_COUNT                        | 2              |
     | NDB_API_UK_OP_COUNT                        | 0              |
     | NDB_API_TABLE_SCAN_COUNT                   | 1              |
     | NDB_API_RANGE_SCAN_COUNT                   | 0              |
     | NDB_API_PRUNED_SCAN_COUNT                  | 0              |
     | NDB_API_SCAN_BATCH_COUNT                   | 0              |
     | NDB_API_READ_ROW_COUNT                     | 2              |
     | NDB_API_TRANS_LOCAL_READ_ROW_COUNT         | 2              |
     | NDB_API_EVENT_DATA_COUNT                   | 0              |
     | NDB_API_EVENT_NONDATA_COUNT                | 0              |
     | NDB_API_EVENT_BYTES_COUNT                  | 0              |
     +--------------------------------------------+----------------+
     60 rows in set (0.00 sec)

     mysql> SELECT * FROM INFORMATION_SCHEMA.GLOBAL_STATUS
         ->     WHERE VARIABLE_NAME LIKE 'ndb_api%';
     +--------------------------------------------+----------------+
     | VARIABLE_NAME                              | VARIABLE_VALUE |
     +--------------------------------------------+----------------+
     | NDB_API_WAIT_EXEC_COMPLETE_COUNT_SESSION   | 2              |
     | NDB_API_WAIT_SCAN_RESULT_COUNT_SESSION     | 0              |
     | NDB_API_WAIT_META_REQUEST_COUNT_SESSION    | 1              |
     | NDB_API_WAIT_NANOS_COUNT_SESSION           | 8144375        |
     | NDB_API_BYTES_SENT_COUNT_SESSION           | 68             |
     | NDB_API_BYTES_RECEIVED_COUNT_SESSION       | 84             |
     | NDB_API_TRANS_START_COUNT_SESSION          | 1              |
     | NDB_API_TRANS_COMMIT_COUNT_SESSION         | 1              |
     | NDB_API_TRANS_ABORT_COUNT_SESSION          | 0              |
     | NDB_API_TRANS_CLOSE_COUNT_SESSION          | 1              |
     | NDB_API_PK_OP_COUNT_SESSION                | 1              |
     | NDB_API_UK_OP_COUNT_SESSION                | 0              |
     | NDB_API_TABLE_SCAN_COUNT_SESSION           | 0              |
     | NDB_API_RANGE_SCAN_COUNT_SESSION           | 0              |
     | NDB_API_PRUNED_SCAN_COUNT_SESSION          | 0              |
     | NDB_API_SCAN_BATCH_COUNT_SESSION           | 0              |
     | NDB_API_READ_ROW_COUNT_SESSION             | 1              |
     | NDB_API_TRANS_LOCAL_READ_ROW_COUNT_SESSION | 1              |
     | NDB_API_EVENT_DATA_COUNT_INJECTOR          | 0              |
     | NDB_API_EVENT_NONDATA_COUNT_INJECTOR       | 0              |
     | NDB_API_EVENT_BYTES_COUNT_INJECTOR         | 0              |
     | NDB_API_WAIT_EXEC_COMPLETE_COUNT_SLAVE     | 0              |
     | NDB_API_WAIT_SCAN_RESULT_COUNT_SLAVE       | 0              |
     | NDB_API_WAIT_META_REQUEST_COUNT_SLAVE      | 0              |
     | NDB_API_WAIT_NANOS_COUNT_SLAVE             | 0              |
     | NDB_API_BYTES_SENT_COUNT_SLAVE             | 0              |
     | NDB_API_BYTES_RECEIVED_COUNT_SLAVE         | 0              |
     | NDB_API_TRANS_START_COUNT_SLAVE            | 0              |
     | NDB_API_TRANS_COMMIT_COUNT_SLAVE           | 0              |
     | NDB_API_TRANS_ABORT_COUNT_SLAVE            | 0              |
     | NDB_API_TRANS_CLOSE_COUNT_SLAVE            | 0              |
     | NDB_API_PK_OP_COUNT_SLAVE                  | 0              |
     | NDB_API_UK_OP_COUNT_SLAVE                  | 0              |
     | NDB_API_TABLE_SCAN_COUNT_SLAVE             | 0              |
     | NDB_API_RANGE_SCAN_COUNT_SLAVE             | 0              |
     | NDB_API_PRUNED_SCAN_COUNT_SLAVE            | 0              |
     | NDB_API_SCAN_BATCH_COUNT_SLAVE             | 0              |
     | NDB_API_READ_ROW_COUNT_SLAVE               | 0              |
     | NDB_API_TRANS_LOCAL_READ_ROW_COUNT_SLAVE   | 0              |
     | NDB_API_WAIT_EXEC_COMPLETE_COUNT           | 4              |
     | NDB_API_WAIT_SCAN_RESULT_COUNT             | 3              |
     | NDB_API_WAIT_META_REQUEST_COUNT            | 28             |
     | NDB_API_WAIT_NANOS_COUNT                   | 53756398       |
     | NDB_API_BYTES_SENT_COUNT                   | 1060           |
     | NDB_API_BYTES_RECEIVED_COUNT               | 9724           |
     | NDB_API_TRANS_START_COUNT                  | 3              |
     | NDB_API_TRANS_COMMIT_COUNT                 | 2              |
     | NDB_API_TRANS_ABORT_COUNT                  | 0              |
     | NDB_API_TRANS_CLOSE_COUNT                  | 3              |
     | NDB_API_PK_OP_COUNT                        | 2              |
     | NDB_API_UK_OP_COUNT                        | 0              |
     | NDB_API_TABLE_SCAN_COUNT                   | 1              |
     | NDB_API_RANGE_SCAN_COUNT                   | 0              |
     | NDB_API_PRUNED_SCAN_COUNT                  | 0              |
     | NDB_API_SCAN_BATCH_COUNT                   | 0              |
     | NDB_API_READ_ROW_COUNT                     | 2              |
     | NDB_API_TRANS_LOCAL_READ_ROW_COUNT         | 2              |
     | NDB_API_EVENT_DATA_COUNT                   | 0              |
     | NDB_API_EVENT_NONDATA_COUNT                | 0              |
     | NDB_API_EVENT_BYTES_COUNT                  | 0              |
     +--------------------------------------------+----------------+
     60 rows in set (0.00 sec)

Each 'Ndb' (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) object has
its own counters.  NDB API applications can read the values of the
counters for use in optimization or monitoring.  For multi-threaded
clients which use more than one 'Ndb'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) object concurrently,
it is also possible to obtain a summed view of counters from all 'Ndb'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) objects belonging to a
given 'Ndb_cluster_connection'
(http://dev.mysql.com/doc/ndbapi/en/ndb-ndb-cluster-connection.html).

Four sets of these counters are exposed.  One set applies to the current
session only; the other 3 are global.  _This is in spite of the fact
that their values can be obtained as either session or global status
variables in the 'mysql' client_.  This means that
specifying the 'SESSION' or 'GLOBAL' keyword with 'SHOW STATUS'
has no effect on the values reported for NDB API statistics
status variables, and the value for each of these variables is the same
whether the value is obtained from the equivalent column of the
'SESSION_STATUS' or the 'GLOBAL_STATUS'
table.

   * _Session counters (session specific)_

     Session counters relate to the 'Ndb'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) objects in use by
     (only) the current session.  Use of such objects by other MySQL
     clients does not influence these counts.

     In order to minimize confusion with standard MySQL session
     variables, we refer to the variables that correspond to these NDB
     API session counters as ''_session' variables', with a leading
     underscore.

   * _Slave counters (global)_

     This set of counters relates to the 'Ndb'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) objects used by
     the replication slave SQL thread, if any.  If this 'mysqld'
     does not act as a replication slave, or does not use
     'NDB' tables, then all of these counts are 0.

     We refer to the related status variables as ''_slave' variables'
     (with a leading underscore).

   * _Injector counters (global)_

     Injector counters relate to the 'Ndb'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) object used to
     listen to cluster events by the binary log injector thread.  Even
     when not writing a binary log, see 'mysqld' processes
     attached to an NDB Cluster continue to listen for some events, such
     as schema changes.

     We refer to the status variables that correspond to NDB API
     injector counters as ''_injector' variables' (with a leading
     underscore).

   * _Server (Global) counters (global)_

     This set of counters relates to all 'Ndb'
     (http://dev.mysql.com/doc/ndbapi/en/ndb-ndb.html) objects currently
     used by this 'mysqld'.  This includes all MySQL
     client applications, the slave SQL thread (if any), the binlog
     injector, and the 'NDB' utility thread.

     We refer to the status variables that correspond to these counters
     as 'global variables' or ''mysqld'.-level variables'.

You can obtain values for a particular set of variables by additionally
filtering for the substring 'session', 'slave', or 'injector' in the
variable name (along with the common prefix 'Ndb_api').  For '_session'
variables, this can be done as shown here:

     mysql> SHOW STATUS LIKE 'ndb_api%session';
     +--------------------------------------------+---------+
     | Variable_name                              | Value   |
     +--------------------------------------------+---------+
     | Ndb_api_wait_exec_complete_count_session   | 2       |
     | Ndb_api_wait_scan_result_count_session     | 0       |
     | Ndb_api_wait_meta_request_count_session    | 1       |
     | Ndb_api_wait_nanos_count_session           | 8144375 |
     | Ndb_api_bytes_sent_count_session           | 68      |
     | Ndb_api_bytes_received_count_session       | 84      |
     | Ndb_api_trans_start_count_session          | 1       |
     | Ndb_api_trans_commit_count_session         | 1       |
     | Ndb_api_trans_abort_count_session          | 0       |
     | Ndb_api_trans_close_count_session          | 1       |
     | Ndb_api_pk_op_count_session                | 1       |
     | Ndb_api_uk_op_count_session                | 0       |
     | Ndb_api_table_scan_count_session           | 0       |
     | Ndb_api_range_scan_count_session           | 0       |
     | Ndb_api_pruned_scan_count_session          | 0       |
     | Ndb_api_scan_batch_count_session           | 0       |
     | Ndb_api_read_row_count_session             | 1       |
     | Ndb_api_trans_local_read_row_count_session | 1       |
     +--------------------------------------------+---------+
     18 rows in set (0.50 sec)

To obtain a listing of the NDB API 'mysqld'.-level status
variables, filter for variable names beginning with 'ndb_api' and ending
in '_count', like this:

     mysql> SELECT * FROM INFORMATION_SCHEMA.SESSION_STATUS
         ->     WHERE VARIABLE_NAME LIKE 'ndb_api%count';
     +------------------------------------+----------------+
     | VARIABLE_NAME                      | VARIABLE_VALUE |
     +------------------------------------+----------------+
     | NDB_API_WAIT_EXEC_COMPLETE_COUNT   | 4              |
     | NDB_API_WAIT_SCAN_RESULT_COUNT     | 3              |
     | NDB_API_WAIT_META_REQUEST_COUNT    | 28             |
     | NDB_API_WAIT_NANOS_COUNT           | 53756398       |
     | NDB_API_BYTES_SENT_COUNT           | 1060           |
     | NDB_API_BYTES_RECEIVED_COUNT       | 9724           |
     | NDB_API_TRANS_START_COUNT          | 3              |
     | NDB_API_TRANS_COMMIT_COUNT         | 2              |
     | NDB_API_TRANS_ABORT_COUNT          | 0              |
     | NDB_API_TRANS_CLOSE_COUNT          | 3              |
     | NDB_API_PK_OP_COUNT                | 2              |
     | NDB_API_UK_OP_COUNT                | 0              |
     | NDB_API_TABLE_SCAN_COUNT           | 1              |
     | NDB_API_RANGE_SCAN_COUNT           | 0              |
     | NDB_API_PRUNED_SCAN_COUNT          | 0              |
     | NDB_API_SCAN_BATCH_COUNT           | 0              |
     | NDB_API_READ_ROW_COUNT             | 2              |
     | NDB_API_TRANS_LOCAL_READ_ROW_COUNT | 2              |
     | NDB_API_EVENT_DATA_COUNT           | 0              |
     | NDB_API_EVENT_NONDATA_COUNT        | 0              |
     | NDB_API_EVENT_BYTES_COUNT          | 0              |
     +------------------------------------+----------------+
     21 rows in set (0.09 sec)

Not all counters are reflected in all 4 sets of status variables.  For
the event counters 'DataEventsRecvdCount', 'NondataEventsRecvdCount',
and 'EventBytesRecvdCount', only '_injector' and 'mysqld'.
-level NDB API status variables are available:

     mysql> SHOW STATUS LIKE 'ndb_api%event%';
     +--------------------------------------+-------+
     | Variable_name                        | Value |
     +--------------------------------------+-------+
     | Ndb_api_event_data_count_injector    | 0     |
     | Ndb_api_event_nondata_count_injector | 0     |
     | Ndb_api_event_bytes_count_injector   | 0     |
     | Ndb_api_event_data_count             | 0     |
     | Ndb_api_event_nondata_count          | 0     |
     | Ndb_api_event_bytes_count            | 0     |
     +--------------------------------------+-------+
     6 rows in set (0.00 sec)

'_injector' status variables are not implemented for any other NDB API
counters, as shown here:

     mysql> SHOW STATUS LIKE 'ndb_api%injector%';
     +--------------------------------------+-------+
     | Variable_name                        | Value |
     +--------------------------------------+-------+
     | Ndb_api_event_data_count_injector    | 0     |
     | Ndb_api_event_nondata_count_injector | 0     |
     | Ndb_api_event_bytes_count_injector   | 0     |
     +--------------------------------------+-------+
     3 rows in set (0.00 sec)

The names of the status variables can easily be associated with the
names of the corresponding counters.  Each NDB API statistics counter is
listed in the following table with a description as well as the names of
any MySQL server status variables corresponding to this counter.

*NDB API statistics counters*

Counter Name           Description               Status Variables (by
                                                 statistic type):

                                                    * Session

                                                    * Slave

                                                    * Injector

                                                    * Server

'WaitExecCompleteCount'Number of times thread
                       has been blocked while       *
                       waiting for execution          'Ndb_api_wait_exec_complete_count_session'
                       of an operation to
                       complete.  Includes all      *
                       'execute()'                    'Ndb_api_wait_exec_complete_count_slave'
                       (http://dev.mysql.com/doc/ndbapi/en/ndb-ndbtransaction-execute.html)
                       calls as well as             * [none]
                       implicit executes for
                       blob operations and          *
                       auto-increment not             'Ndb_api_wait_exec_complete_count'
                       visible to clients.

'WaitScanResultCount'  Number of times thread
                       has been blocked while       *
                       waiting for a                  'Ndb_api_wait_scan_result_count_session'
                       scan-based signal, such
                       waiting for additional       *
                       results, or for a scan         'Ndb_api_wait_scan_result_count_slave'
                       to close.
                                                    * [none]

                                                    *
                                                      'Ndb_api_wait_scan_result_count'

'WaitMetaRequestCount' Number of times thread
                       has been blocked             *
                       waiting for a                  'Ndb_api_wait_meta_request_count_session'
                       metadata-based signal;
                       this can occur when          *
                       waiting for a DDL              'Ndb_api_wait_meta_request_count_slave'
                       operation or for an
                       epoch to be started (or      * [none]
                       ended).
                                                    *
                                                      'Ndb_api_wait_meta_request_count'

'WaitNanosCount'       Total time (in
                       nanoseconds) spent           *
                       waiting for some type          'Ndb_api_wait_nanos_count_session'
                       of signal from the data
                       nodes.                       *
                                                      'Ndb_api_wait_nanos_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_wait_nanos_count'

'BytesSentCount'       Amount of data (in
                       bytes) sent to the data      *
                       nodes                          'Ndb_api_bytes_sent_count_session'

                                                    *
                                                      'Ndb_api_bytes_sent_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_bytes_sent_count'

'BytesRecvdCount'      Amount of data (in
                       bytes) received from         *
                       the data nodes                 'Ndb_api_bytes_received_count_session'

                                                    *
                                                      'Ndb_api_bytes_received_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_bytes_received_count'

'TransStartCount'      Number of transactions
                       started.                     *
                                                      'Ndb_api_trans_start_count_session'

                                                    *
                                                      'Ndb_api_trans_start_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_trans_start_count'

'TransCommitCount'     Number of transactions
                       committed.                   *
                                                      'Ndb_api_trans_commit_count_session'

                                                    *
                                                      'Ndb_api_trans_commit_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_trans_commit_count'

'TransAbortCount'      Number of transactions
                       aborted.                     *
                                                      'Ndb_api_trans_abort_count_session'

                                                    *
                                                      'Ndb_api_trans_abort_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_trans_abort_count'

'TransCloseCount'      Number of transactions
                       aborted.  (This value        *
                       may be greater than the        'Ndb_api_trans_close_count_session'
                       sum of
                       'TransCommitCount' and       *
                       'TransAbortCount'.)            'Ndb_api_trans_close_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_trans_close_count'

'PkOpCount'            Number of operations
                       based on or using            *
                       primary keys.  This            'Ndb_api_pk_op_count_session'
                       count includes
                       blob-part table              *
                       operations, implicit           'Ndb_api_pk_op_count_slave'
                       unlocking operations,
                       and auto-increment           * [none]
                       operations, as well as
                       primary key operations       * 'Ndb_api_pk_op_count'
                       normally visible to
                       MySQL clients.

'UkOpCount'            Number of operations
                       based on or using            *
                       unique keys.                   'Ndb_api_uk_op_count_session'

                                                    *
                                                      'Ndb_api_uk_op_count_slave'

                                                    * [none]

                                                    * 'Ndb_api_uk_op_count'

'TableScanCount'       Number of table scans
                       that have been started.      *
                       This includes scans of         'Ndb_api_table_scan_count_session'
                       internal tables.
                                                    *
                                                      'Ndb_api_table_scan_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_table_scan_count'

'RangeScanCount'       Number of range scans
                       that have been started.      *
                                                      'Ndb_api_range_scan_count_session'

                                                    *
                                                      'Ndb_api_range_scan_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_range_scan_count'

'PrunedScanCount'      Number of scans that
                       have been pruned to a        *
                       single partition.              'Ndb_api_pruned_scan_count_session'

                                                    *
                                                      'Ndb_api_pruned_scan_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_pruned_scan_count'

'ScanBatchCount'       Number of batches of
                       rows received.  (A           *
                       _batch_ in this context        'Ndb_api_scan_batch_count_session'
                       is a set of scan
                       results from a single        *
                       fragment.)                     'Ndb_api_scan_batch_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_scan_batch_count'

'ReadRowCount'         Total number of rows
                       that have been read.         *
                       Includes rows read             'Ndb_api_read_row_count_session'
                       using primary key,
                       unique key, and scan         *
                       operations.                    'Ndb_api_read_row_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_read_row_count'

'TransLocalReadRowCount'Number of rows read
                       from the data same node      *
                       on which the                   'Ndb_api_trans_local_read_row_count_session'
                       transaction was being
                       run.                         *
                                                      'Ndb_api_trans_local_read_row_count_slave'

                                                    * [none]

                                                    *
                                                      'Ndb_api_trans_local_read_row_count'

'DataEventsRecvdCount' Number of row change
                       events received.             * [none]

                                                    * [none]

                                                    *
                                                      'Ndb_api_event_data_count_injector'

                                                    *
                                                      'Ndb_api_event_data_count'

'NondataEventsRecvdCount'Number of events
                       received, other than         * [none]
                       row change events.
                                                    * [none]

                                                    *
                                                      'Ndb_api_event_nondata_count_injector'

                                                    *
                                                      'Ndb_api_event_nondata_count'

'EventBytesRecvdCount' Number of bytes of
                       events received.             * [none]

                                                    * [none]

                                                    *
                                                      'Ndb_api_event_bytes_count_injector'

                                                    *
                                                      'Ndb_api_event_bytes_count'

To see all counts of committed transactions--that is, all
'TransCommitCount' counter status variables--you can filter the results
of 'SHOW STATUS' for the substring
'trans_commit_count', like this:

     mysql> SHOW STATUS LIKE '%trans_commit_count%';
     +------------------------------------+-------+
     | Variable_name                      | Value |
     +------------------------------------+-------+
     | Ndb_api_trans_commit_count_session | 1     |
     | Ndb_api_trans_commit_count_slave   | 0     |
     | Ndb_api_trans_commit_count         | 2     |
     +------------------------------------+-------+
     3 rows in set (0.00 sec)

From this you can determine that 1 transaction has been committed in the
current 'mysql' client session, and 2 transactions have
been committed on this 'mysqld' since it was last
restarted.

You can see how various NDB API counters are incremented by a given SQL
statement by comparing the values of the corresponding '_session' status
variables immediately before and after performing the statement.  In
this example, after getting the initial values from 'SHOW STATUS',
we create in the 'test' database an 'NDB'
table, named 't', that has a single column:

     mysql> SHOW STATUS LIKE 'ndb_api%session%';
     +--------------------------------------------+--------+
     | Variable_name                              | Value  |
     +--------------------------------------------+--------+
     | Ndb_api_wait_exec_complete_count_session   | 2      |
     | Ndb_api_wait_scan_result_count_session     | 0      |
     | Ndb_api_wait_meta_request_count_session    | 3      |
     | Ndb_api_wait_nanos_count_session           | 820705 |
     | Ndb_api_bytes_sent_count_session           | 132    |
     | Ndb_api_bytes_received_count_session       | 372    |
     | Ndb_api_trans_start_count_session          | 1      |
     | Ndb_api_trans_commit_count_session         | 1      |
     | Ndb_api_trans_abort_count_session          | 0      |
     | Ndb_api_trans_close_count_session          | 1      |
     | Ndb_api_pk_op_count_session                | 1      |
     | Ndb_api_uk_op_count_session                | 0      |
     | Ndb_api_table_scan_count_session           | 0      |
     | Ndb_api_range_scan_count_session           | 0      |
     | Ndb_api_pruned_scan_count_session          | 0      |
     | Ndb_api_scan_batch_count_session           | 0      |
     | Ndb_api_read_row_count_session             | 1      |
     | Ndb_api_trans_local_read_row_count_session | 1      |
     +--------------------------------------------+--------+
     18 rows in set (0.00 sec)

     mysql> USE test;
     Database changed
     mysql> CREATE TABLE t (c INT) ENGINE NDBCLUSTER;
     Query OK, 0 rows affected (0.85 sec)

Now you can execute a new 'SHOW STATUS' statement
and observe the changes, as shown here (with the changed rows
highlighted in the output):

     mysql> SHOW STATUS LIKE 'ndb_api%session%';
     +--------------------------------------------+-----------+
     | Variable_name                              | Value     |
     +--------------------------------------------+-----------+_
     | Ndb_api_wait_exec_complete_count_session   | 8         |_
     | Ndb_api_wait_scan_result_count_session     | 0         |
     _| Ndb_api_wait_meta_request_count_session    | 17        |_
     _| Ndb_api_wait_nanos_count_session           | 706871709 |_
     _| Ndb_api_bytes_sent_count_session           | 2376      |_
     _| Ndb_api_bytes_received_count_session       | 3844      |_
     _| Ndb_api_trans_start_count_session          | 4         |_
     _| Ndb_api_trans_commit_count_session         | 4         |_
     | Ndb_api_trans_abort_count_session          | 0         |
     _| Ndb_api_trans_close_count_session          | 4         |_
     _| Ndb_api_pk_op_count_session                | 6         |_
     | Ndb_api_uk_op_count_session                | 0         |
     | Ndb_api_table_scan_count_session           | 0         |
     | Ndb_api_range_scan_count_session           | 0         |
     | Ndb_api_pruned_scan_count_session          | 0         |
     | Ndb_api_scan_batch_count_session           | 0         |
     _| Ndb_api_read_row_count_session             | 2         |_
     | Ndb_api_trans_local_read_row_count_session | 1         |
     +--------------------------------------------+-----------+
     18 rows in set (0.00 sec)

Similarly, you can see the changes in the NDB API statistics counters
caused by inserting a row into 't': Insert the row, then run the same
'SHOW STATUS' statement used in the previous
example, as shown here:

     mysql> INSERT INTO t VALUES (100);
     Query OK, 1 row affected (0.00 sec)

     mysql> SHOW STATUS LIKE 'ndb_api%session%';
     +--------------------------------------------+-----------+
     | Variable_name                              | Value     |
     +--------------------------------------------+-----------+
     _| Ndb_api_wait_exec_complete_count_session   | 11        |_
     _| Ndb_api_wait_scan_result_count_session     | 6         |_
     _| Ndb_api_wait_meta_request_count_session    | 20        |_
     _| Ndb_api_wait_nanos_count_session           | 707370418 |_
     _| Ndb_api_bytes_sent_count_session           | 2724      |_
     _| Ndb_api_bytes_received_count_session       | 4116      |_
     _| Ndb_api_trans_start_count_session          | 7         |_
     _| Ndb_api_trans_commit_count_session         | 6         |_
     | Ndb_api_trans_abort_count_session          | 0         |
     _| Ndb_api_trans_close_count_session          | 7         |_
     _| Ndb_api_pk_op_count_session                | 8         |_
     | Ndb_api_uk_op_count_session                | 0         |
     _| Ndb_api_table_scan_count_session           | 1         |_
     | Ndb_api_range_scan_count_session           | 0         |
     | Ndb_api_pruned_scan_count_session          | 0         |
     | Ndb_api_scan_batch_count_session           | 0         |
     _| Ndb_api_read_row_count_session             | 3         |_
     _| Ndb_api_trans_local_read_row_count_session | 2         |_
     +--------------------------------------------+-----------+
     18 rows in set (0.00 sec)

We can make a number of observations from these results:

   * Although we created 't' with no explicit primary key, 5 primary key
     operations were performed in doing so (the difference in the
     'before' and 'after' values of 'Ndb_api_pk_op_count_session', or 6
     minus 1).  This reflects the creation of the hidden primary key
     that is a feature of all tables using the 'NDB'
     storage engine.

   * By comparing successive values for
     'Ndb_api_wait_nanos_count_session', we can see that the NDB API
     operations implementing the 'CREATE TABLE'.
     statement waited much longer (706871709 - 820705 = 706051004
     nanoseconds, or approximately 0.7 second) for responses from the
     data nodes than those executed by the 'INSERT'.
     (707370418 - 706871709 = 498709 ns or roughly .0005 second).  The
     execution times reported for these statements in the 'mysql'
     client correlate roughly with these figures.

     On platforms without sufficient (nanosecond) time resolution, small
     changes in the value of the 'WaitNanosCount' NDB API counter due to
     SQL statements that execute very quickly may not always be visible
     in the values of 'Ndb_api_wait_nanos_count_session',
     'Ndb_api_wait_nanos_count_slave', or 'Ndb_api_wait_nanos_count'.

   * The 'INSERT' statement incremented both the
     'ReadRowCount' and 'TransLocalReadRowCount' NDB API statistics
     counters, as reflected by the increased values of
     'Ndb_api_read_row_count_session' and
     'Ndb_api_trans_local_read_row_count_session'.

21.6 NDB Cluster Replication
============================

NDB Cluster supports _asynchronous replication_, more usually referred
to simply as 'replication'.  This section explains how to set up and
manage a configuration in which one group of computers operating as an
NDB Cluster replicates to a second computer or group of computers.  We
assume some familiarity on the part of the reader with standard MySQL
replication as discussed elsewhere in this Manual.  (See
replication).

*Note*:

NDB Cluster does not support replication using GTIDs; semisynchronous
replication is also not supported by the 'NDB' storage engine.

Normal (non-clustered) replication involves a 'master' server and a
'slave' server, the master being the source of the operations and data
to be replicated and the slave being the recipient of these.  In NDB
Cluster, replication is conceptually very similar but can be more
complex in practice, as it may be extended to cover a number of
different configurations including replicating between two complete
clusters.  Although an NDB Cluster itself depends on the 'NDB'
storage engine for clustering functionality, it is not
necessary to use 'NDB' as the storage engine for
the slave's copies of the replicated tables (see
mysql-cluster-replication-ndb-to-non-ndb).  However, for maximum
availability, it is possible (and preferable) to replicate from one NDB
Cluster to another, and it is this scenario that we discuss, as shown in
the following figure:

FIGURE GOES HERE: NDB Cluster-to-Cluster Replication Layout

In this scenario, the replication process is one in which successive
states of a master cluster are logged and saved to a slave cluster.
This process is accomplished by a special thread known as the NDB binary
log injector thread, which runs on each MySQL server and produces a
binary log ('binlog').  This thread ensures that all changes in the
cluster producing the binary log--and not just those changes that are
effected through the MySQL Server--are inserted into the binary log with
the correct serialization order.  We refer to the MySQL replication
master and replication slave servers as replication servers or
replication nodes, and the data flow or line of communication between
them as a _replication channel_.

For information about performing point-in-time recovery with NDB Cluster
and NDB Cluster Replication, see mysql-cluster-replication-pitr.

NDB API _slave status variables

NDB API counters can provide enhanced monitoring capabilities on NDB
Cluster replication slaves.  These are implemented as NDB statistics
'_slave' status variables, as seen in the output of 'SHOW STATUS',
or in the results of queries against the
'SESSION_STATUS' or 'GLOBAL_STATUS'.
table in a 'mysql' client session connected to a MySQL
Server that is acting as a slave in NDB Cluster Replication.  By
comparing the values of these status variables before and after the
execution of statements affecting replicated 'NDB'.
tables, you can observe the corresponding actions taken on the NDB API
level by the slave, which can be useful when monitoring or
troubleshooting NDB Cluster Replication.  See
mysql-cluster-ndb-api-statistics, provides additional information.

Replication from NDB to non-NDB tables

It is possible to replicate 'NDB' tables from an
NDB Cluster acting as the master to tables using other MySQL storage
engines such as 'InnoDB' or
'MyISAM' on a slave 'mysqld'.
This is subject to a number of conditions; see
mysql-cluster-replication-ndb-to-non-ndb, and
mysql-cluster-replication-ndb-to-nontransactional, for more
information.

21.6.1 NDB Cluster Replication: Abbreviations and Symbols
---------------------------------------------------------

Throughout this section, we use the following abbreviations or symbols
for referring to the master and slave clusters, and to processes and
commands run on the clusters or cluster nodes:

*Abbreviations used throughout this section referring to master and
slave clusters, and to processes and commands run on nodes*

Symbol or          Description (Refers to...)
Abbreviation

M                  The cluster serving as the (primary) replication
                   master

S                  The cluster acting as the (primary) replication
                   slave

'shellM>'          Shell command to be issued on the master cluster

'mysqlM>'          MySQL client command issued on a single MySQL server
                   running as an SQL node on the master cluster

'mysqlM*>'         MySQL client command to be issued on all SQL nodes
                   participating in the replication master cluster

'shellS>'          Shell command to be issued on the slave cluster

'mysqlS>'          MySQL client command issued on a single MySQL server
                   running as an SQL node on the slave cluster

'mysqlS*>'         MySQL client command to be issued on all SQL nodes
                   participating in the replication slave cluster

C                  Primary replication channel

C'                 Secondary replication channel

M'                 Secondary replication master

S'                 Secondary replication slave

21.6.2 General Requirements for NDB Cluster Replication
-------------------------------------------------------

A replication channel requires two MySQL servers acting as replication
servers (one each for the master and slave).  For example, this means
that in the case of a replication setup with two replication channels
(to provide an extra channel for redundancy), there will be a total of
four replication nodes, two per cluster.

Replication of an NDB Cluster as described in this section and those
following is dependent on row-based replication.  This means that the
replication master MySQL server must be running with
'--binlog-format=ROW' or '--binlog-format=MIXED', as described in
mysql-cluster-replication-starting.  For general information about
row-based replication, see replication-formats.

*Important*:

If you attempt to use NDB Cluster Replication with
'--binlog-format=STATEMENT', replication fails to work properly because
the 'ndb_binlog_index' table on the master and the 'epoch' column of the
'ndb_apply_status' table on the slave are not updated (see
mysql-cluster-replication-schema).  Instead, only updates on the MySQL
server acting as the replication master propagate to the slave, and no
updates from any other SQL nodes on the master cluster are replicated.

The default value for the '--binlog-format' option in NDB 7.5 is
'MIXED'.

Each MySQL server used for replication in either cluster must be
uniquely identified among all the MySQL replication servers
participating in either cluster (you cannot have replication servers on
both the master and slave clusters sharing the same ID). This can be
done by starting each SQL node using the '--server-id=ID' option, where
ID is a unique integer.  Although it is not strictly necessary, we will
assume for purposes of this discussion that all NDB Cluster binaries are
of the same release version.

It is generally true in MySQL Replication that both MySQL servers (see
'mysqld' processes) involved must be compatible with one
another with respect to both the version of the replication protocol
used and the SQL feature sets which they support (see
replication-compatibility).  It is due to such differences between the
binaries in the NDB Cluster and MySQL Server 5.7 distributions that NDB
Cluster Replication has the additional requirement that both
'mysqld' binaries come from an NDB Cluster distribution.  The
simplest and easiest way to assure that the 'mysqld'.
servers are compatible is to use the same NDB Cluster distribution for
all master and slave 'mysqld' binaries.

We assume that the slave server or cluster is dedicated to replication
of the master, and that no other data is being stored on it.

All 'NDB' tables being replicated must be created using a MySQL server
and client.  Tables and other database objects created using the NDB API
(with, for example, 'Dictionary::createTable()'
(http://dev.mysql.com/doc/ndbapi/en/ndb-dictionary-createtable.html))
are not visible to a MySQL server and so are not replicated.  Updates by
NDB API applications to existing tables that were created using a MySQL
server can be replicated.

*Note*:

It is possible to replicate an NDB Cluster using statement-based
replication.  However, in this case, the following restrictions apply:

   * All updates to data rows on the cluster acting as the master must
     be directed to a single MySQL server.

   * It is not possible to replicate a cluster using multiple
     simultaneous MySQL replication processes.

   * Only changes made at the SQL level are replicated.

These are in addition to the other limitations of statement-based
replication as opposed to row-based replication; see
replication-sbr-rbr, for more specific information concerning the
differences between the two replication formats.

21.6.3 Known Issues in NDB Cluster Replication
----------------------------------------------

This section discusses known problems or issues when using replication
with NDB Cluster 7.5.

Loss of master-slave connection

A loss of connection can occur either between the replication master SQL
node and the replication slave SQL node, or between the replication
master SQL node and the data nodes in the master cluster.  In the latter
case, this can occur not only as a result of loss of physical connection
(for example, a broken network cable), but due to the overflow of data
node event buffers; if the SQL node is too slow to respond, it may be
dropped by the cluster (this is controllable to some degree by adjusting
the 'MaxBufferedEpochs' and 'TimeBetweenEpochs' configuration
parameters).  If this occurs, _it is entirely possible for new data to
be inserted into the master cluster without being recorded in the
replication master's binary log_.  For this reason, to guarantee high
availability, it is extremely important to maintain a backup replication
channel, to monitor the primary channel, and to fail over to the
secondary replication channel when necessary to keep the slave cluster
synchronized with the master.  NDB Cluster is not designed to perform
such monitoring on its own; for this, an external application is
required.

The replication master issues a 'gap' event when connecting or
reconnecting to the master cluster.  (A gap event is a type of 'incident
event,' which indicates an incident that occurs that affects the
contents of the database but that cannot easily be represented as a set
of changes.  Examples of incidents are server crashes, database
resynchronization, (some) software updates, and (some) hardware
changes.)  When the slave encounters a gap in the replication log, it
stops with an error message.  This message is available in the output of
'SHOW SLAVE STATUS', and indicates that the SQL
thread has stopped due to an incident registered in the replication
stream, and that manual intervention is required.  See
mysql-cluster-replication-failover, for more information about what to
do in such circumstances.

*Important*:

Because NDB Cluster is not designed on its own to monitor replication
status or provide failover, if high availability is a requirement for
the slave server or cluster, then you must set up multiple replication
lines, monitor the master 'mysqld' on the primary
replication line, and be prepared fail over to a secondary line if and
as necessary.  This must be done manually, or possibly by means of a
third-party application.  For information about implementing this type
of setup, see mysql-cluster-replication-two-channels, and
mysql-cluster-replication-failover.

However, if you are replicating from a standalone MySQL server to an NDB
Cluster, one channel is usually sufficient.

Circular replication

NDB Cluster Replication supports circular replication, as shown in the
next example.  The replication setup involves three NDB Clusters
numbered 1, 2, and 3, in which Cluster 1 acts as the replication master
for Cluster 2, Cluster 2 acts as the master for Cluster 3, and Cluster 3
acts as the master for Cluster 1, thus completing the circle.  Each NDB
Cluster has two SQL nodes, with SQL nodes A and B belonging to Cluster
1, SQL nodes C and D belonging to Cluster 2, and SQL nodes E and F
belonging to Cluster 3.

Circular replication using these clusters is supported as long as the
following conditions are met:

   * The SQL nodes on all masters and slaves are the same

   * All SQL nodes acting as replication masters and slaves are started
     using the '--log-slave-updates' option

This type of circular replication setup is shown in the following
diagram:

FIGURE GOES HERE: NDB Cluster Circular Replication With All Masters As
Slaves

In this scenario, SQL node A in Cluster 1 replicates to SQL node C in
Cluster 2; SQL node C replicates to SQL node E in Cluster 3; SQL node E
replicates to SQL node A. In other words, the replication line
(indicated by the red arrows in the diagram) directly connects all SQL
nodes used as replication masters and slaves.

It should also be possible to set up circular replication in which not
all master SQL nodes are also slaves, as shown here:

FIGURE GOES HERE: NDB Cluster Circular Replication Where Not All Masters
Are Slaves

In this case, different SQL nodes in each cluster are used as
replication masters and slaves.  However, you must _not_ start any of
the SQL nodes using '--log-slave-updates'.  This type of circular
replication scheme for NDB Cluster, in which the line of replication
(again indicated by the red arrows in the diagram) is discontinuous,
should be possible, but it should be noted that it has not yet been
thoroughly tested and must therefore still be considered experimental.

*Note*:

The 'NDB' storage engine uses _idempotent
execution mode_, which suppresses duplicate-key and other errors that
otherwise break circular replication of NDB Cluster.  This is equivalent
to setting the global 'slave_exec_mode' system variable to 'IDEMPOTENT',
although this is not necessary in NDB Cluster replication, since NDB
Cluster sets this variable automatically and ignores any attempts to set
it explicitly.

NDB Cluster replication and primary keys

In the event of a node failure, errors in replication of 'NDB'
tables without primary keys can still occur, due to the
possibility of duplicate rows being inserted in such cases.  For this
reason, it is highly recommended that all 'NDB'.
tables being replicated have primary keys.

NDB Cluster Replication and Unique Keys

In older versions of NDB Cluster, operations that updated values of
unique key columns of 'NDB' tables could result in
duplicate-key errors when replicated.  This issue is solved for
replication between 'NDB' tables by deferring
unique key checks until after all table row updates have been performed.

Deferring constraints in this way is currently supported only by
'NDB'.  Thus, updates of unique keys when replicating
from 'NDB' to a different storage engine such as
'MyISAM' or 'InnoDB'
are still not supported.

The problem encountered when replicating without deferred checking of
unique key updates can be illustrated using 'NDB'.
table such as 't', is created and populated on the master (and
replicated to a slave that does not support deferred unique key updates)
as shown here:

     CREATE TABLE t (
         p INT PRIMARY KEY,
         c INT,
         UNIQUE KEY u (c)
     )   ENGINE NDB;

     INSERT INTO t
         VALUES (1,1), (2,2), (3,3), (4,4), (5,5);

The following 'UPDATE' statement on 't' succeeded on the
master, since the rows affected are processed in the order determined by
the 'ORDER BY' option, performed over the entire table:

     UPDATE t SET c = c - 1 ORDER BY p;

However, the same statement failed with a duplicate key error or other
constraint violation on the slave, because the ordering of the row
updates was done for one partition at a time, rather than for the table
as a whole.

*Note*:

Every 'NDB' table is implicitly partitioned by key
when it is created.  See partitioning-key, for more information.

GTIDs not supported

Replication using global transaction IDs is not compatible with the
'NDB' storage engine, and is not supported.  Enabling GTIDs is likely to
cause NDB Cluster Replication to fail.

Multi-threaded slaves not supported

NDB Cluster does not support multi-threaded slaves, and setting related
system variables such as 'slave_parallel_workers',
'slave_checkpoint_group', and 'slave_checkpoint_group' (or the
equivalent 'mysqld' startup options) has no effect.

This is because the slave may not be able to separate transactions
occurring in one database from those in another if they are written
within the same epoch.  In addition, every transaction handled by the
'NDB' storage engine involves at least two
databases--the target database and the 'mysql' system database--due to
the requirement for updating the 'mysql.ndb_apply_status' table (see
mysql-cluster-replication-schema).  This in turn breaks the
requirement for multi-threading that the transaction is specific to a
given database.

Restarting with -initial

Restarting the cluster with the '--initial' option causes the sequence
of GCI and epoch numbers to start over from '0'.  (This is generally
true of NDB Cluster and not limited to replication scenarios involving
Cluster.)  The MySQL servers involved in replication should in this case
be restarted.  After this, you should use the 'RESET MASTER'
and 'RESET SLAVE' statements to clear
the invalid 'ndb_binlog_index' and 'ndb_apply_status' tables,
respectively.

Replication from NDB to other storage engines

It is possible to replicate an 'NDB' table on the
master to a table using a different storage engine on the slave, taking
into account the restrictions listed here:

   * Multi-master and circular replication are not supported (tables on
     both the master and the slave must use the 'NDB'
     storage engine for this to work).

   * Using a storage engine which does not perform binary logging for
     slave tables requires special handling.

   * Use of a nontransactional storage engine for slave tables also
     requires special handling.

   * The master 'mysqld' must be started with
     '--ndb-log-update-as-write=0' or '--ndb-log-update-as-write=OFF'.

The next few paragraphs provide additional information about each of the
issues just described.

Multiple masters not supported when replicating NDB to other storage
engines

For replication from 'NDB' to a different storage
engine, the relationship between the two databases must be a simple
master-slave one.  This means that circular or master-master replication
is not supported between NDB Cluster and other storage engines.

In addition, it is not possible to configure more than one replication
channel when replicating between 'NDB' and a
different storage engine.  (However, an NDB Cluster database _can_
simultaneously replicate to multiple slave NDB Cluster databases.)  If
the master uses 'NDB' tables, it is still possible
to have more than one MySQL Server maintain a binary log of all changes;
however, for the slave to change masters (fail over), the new
master-slave relationship must be explicitly defined on the slave.

Replicating NDB to a slave storage engine that does not perform binary
logging

If you attempt to replicate from an NDB Cluster to a slave that uses a
storage engine that does not handle its own binary logging, the
replication process aborts with the error 'Binary logging not possible
... Statement cannot be written atomically since more than one engine
involved and at least one engine is self-logging' (Error 1595).  It is
possible to work around this issue in one of the following ways:

   * Turn off binary logging on the slave

     This can be accomplished by setting 'sql_log_bin = 0'.

   * Change the storage engine used for the mysql.ndb_apply_status table

     Causing this table to use an engine that does not handle its own
     binary logging can also eliminate the conflict.  This can be done
     by issuing a statement such as 'ALTER TABLE mysql.ndb_apply_status ENGINE=MyISAM'
     on the slave.
     It is safe to do this when using a non-see 'NDB'.
     storage engine on the slave, since you do not then need to worry
     about keeping multiple slave SQL nodes synchronized.

   * Filter out changes to the mysql.ndb_apply_status table on the slave

     This can be done by starting the slave SQL node with
     '--replicate-ignore-table=mysql.ndb_apply_status'.  If you need for
     other tables to be ignored by replication, you might wish to use an
     appropriate '--replicate-wild-ignore-table' option instead.

*Important*:

You should _not_ disable replication or binary logging of
'mysql.ndb_apply_status' or change the storage engine used for this
table when replicating from one NDB Cluster to another.  See
mysql-cluster-replication-issues-filtering, for details.

Replication from NDB to a nontransactional storage engine

When replicating from 'NDB' to a nontransactional
storage engine such as 'MyISAM', you may
encounter unnecessary duplicate key errors when replicating
'INSERT ... ON DUPLICATE KEY UPDATE' statements.
You can suppress these by using '--ndb-log-update-as-write=0', which
forces updates to be logged as writes (rather than as updates).

Replication and binary log filtering rules with replication between NDB
Clusters

If you are using any of the options '--replicate-do-*',
'--replicate-ignore-*', '--binlog-do-db', or '--binlog-ignore-db' to
filter databases or tables being replicated, care must be taken not to
block replication or binary logging of the 'mysql.ndb_apply_status',
which is required for replication between NDB Clusters to operate
properly.  In particular, you must keep in mind the following:

  1. Using '--replicate-do-db=DB_NAME' (and no other '--replicate-do-*'
     or '--replicate-ignore-*' options) means that _only_ tables in
     database DB_NAME are replicated.  In this case, you should also use
     '--replicate-do-db=mysql', '--binlog-do-db=mysql', or
     '--replicate-do-table=mysql.ndb_apply_status' to ensure that
     'mysql.ndb_apply_status' is populated on slaves.

     Using '--binlog-do-db=DB_NAME' (and no other '--binlog-do-db'
     options) means that changes _only_ to tables in database DB_NAME
     are written to the binary log.  In this case, you should also use
     '--replicate-do-db=mysql', '--binlog-do-db=mysql', or
     '--replicate-do-table=mysql.ndb_apply_status' to ensure that
     'mysql.ndb_apply_status' is populated on slaves.

  2. Using '--replicate-ignore-db=mysql' means that no tables in the
     'mysql' database are replicated.  In this case, you should also use
     '--replicate-do-table=mysql.ndb_apply_status' to ensure that
     'mysql.ndb_apply_status' is replicated.

     Using '--binlog-ignore-db=mysql' means that no changes to tables in
     the 'mysql' database are written to the binary log.  In this case,
     you should also use '--replicate-do-table=mysql.ndb_apply_status'
     to ensure that 'mysql.ndb_apply_status' is replicated.

You should also remember that each replication rule requires the
following:

  1. Its own '--replicate-do-*' or '--replicate-ignore-*' option, and
     that multiple rules cannot be expressed in a single replication
     filtering option.  For information about these rules, see
     replication-options.

  2. Its own '--binlog-do-db' or '--binlog-ignore-db' option, and that
     multiple rules cannot be expressed in a single binary log filtering
     option.  For information about these rules, see binary-log.

If you are replicating an NDB Cluster to a slave that uses a storage
engine other than 'NDB', the considerations just
given previously may not apply, as discussed elsewhere in this section.

NDB Cluster Replication and IPv6

Currently, the NDB API and MGM API do not support IPv6.  However, MySQL
Servers--including those acting as SQL nodes in an NDB Cluster --can use
IPv6 to contact other MySQL Servers.  This means that you can replicate
between NDB Clusters using IPv6 to connect the master and slave SQL
nodes as shown by the dotted arrow in the following diagram:

FIGURE GOES HERE: Replication Between SQL Nodes Connected Using IPv6

However, all connections originating _within_ the NDB Cluster
--represented in the preceding diagram by solid arrows--must use IPv4.
In other words, all NDB Cluster data nodes, management servers, and
management clients must be accessible from one another using IPv4.  In
addition, SQL nodes must use IPv4 to communicate with the cluster.

Since there is currently no support in the NDB and MGM APIs for IPv6,
any applications written using these APIs must also make all connections
using IPv4.

Attribute promotion and demotion

NDB Cluster Replication includes support for attribute promotion and
demotion.  The implementation of the latter distinguishes between lossy
and non-lossy type conversions, and their use on the slave can be
controlled by setting the 'slave_type_conversions' global server system
variable.

For more information about attribute promotion and demotion in NDB
Cluster, see replication-features-attribute-promotion.

'NDB', unlike 'InnoDB' or 'MyISAM',
does not write changes to virtual columns to the
binary log; however, this has no detrimental effects on NDB Cluster
Replication or replication between 'NDB' and other storage engines.
Changes to stored generated columns are logged.

21.6.4 NDB Cluster Replication Schema and Tables
------------------------------------------------

Replication in NDB Cluster makes use of a number of dedicated tables in
the 'mysql' database on each MySQL Server instance acting as an SQL node
in both the cluster being replicated and the replication slave (whether
the slave is a single server or a cluster).  These tables are created
during the MySQL installation process by the 'mysql_install_db'
script, and include a table for storing the binary
log's indexing data.  Since the 'ndb_binlog_index' table is local to
each MySQL server and does not participate in clustering, it uses the
'InnoDB' storage engine.  This means that it must be created separately
on each 'mysqld' participating in the master cluster.
(However, the binary log itself contains updates from all MySQL servers
in the cluster to be replicated.)  This table is defined as follows:

     CREATE TABLE `ndb_binlog_index` (
         `Position` BIGINT(20) UNSIGNED NOT NULL,
         `File` VARCHAR(255) NOT NULL,
         `epoch` BIGINT(20) UNSIGNED NOT NULL,
         `inserts` INT(10) UNSIGNED NOT NULL,
         `updates` INT(10) UNSIGNED NOT NULL,
         `deletes` INT(10) UNSIGNED NOT NULL,
         `schemaops` INT(10) UNSIGNED NOT NULL,
         `orig_server_id` INT(10) UNSIGNED NOT NULL,
         `orig_epoch` BIGINT(20) UNSIGNED NOT NULL,
         `gci` INT(10) UNSIGNED NOT NULL,
         `next_position` bigint(20) unsigned NOT NULL,
         `next_file` varchar(255) NOT NULL,
         PRIMARY KEY (`epoch`,`orig_server_id`,`orig_epoch`)
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1;

*Note*:

Prior to NDB 7.5.2, this table always used the 'MyISAM'
storage engine.  If you are upgrading from an
earlier release, you can use 'mysql_upgrade' with
the '--force' and '--upgrade-system-tables' options to cause it to
execute an 'ALTER TABLE ... ENGINE=INNODB' statement
on this table.  Use of the 'MyISAM' storage engine for this table
continues to be supported in NDB 7.5.2 and later for backward
compatibility.

'ndb_binlog_index' may require additional disk space after being
converted to 'InnoDB'.  If this becomes an issue, you may be able to
conserve space by using an 'InnoDB' tablespace for this table, changing
its 'ROW_FORMAT' to 'COMPRESSED', or both.  For more information, see
create-tablespace, and create-table, as well as
innodb-tablespace.

The size of this table is dependent on the number of epochs per binary
log file and the number of binary log files.  The number of epochs per
binary log file normally depends on the amount of binary log generated
per epoch and the size of the binary log file, with smaller epochs
resulting in more epochs per file.  You should be aware that empty
epochs produce inserts to the 'ndb_binlog_index' table, even when the
'--ndb-log-empty-epochs' option is 'OFF', meaning that the number of
entries per file depends on the length of time that the file is in use;
that is,

     [number of epochs per file] = [time spent per file] / TimeBetweenEpochs

A busy NDB Cluster writes to the binary log regularly and presumably
rotates binary log files more quickly than a quiet one.  This means that
a 'quiet' NDB Cluster with '--ndb-log-empty-epochs=ON' can actually have
a much higher number of 'ndb_binlog_index' rows per file than one with a
great deal of activity.

When 'mysqld' is started with the '--ndb-log-orig'
option, the 'orig_server_id' and 'orig_epoch' columns store,
respectively, the ID of the server on which the event originated and the
epoch in which the event took place on the originating server, which is
useful in NDB Cluster replication setups employing multiple masters.
The 'SELECT' statement used to find the closest binary
log position to the highest applied epoch on the slave in a multi-master
setup (see mysql-cluster-replication-multi-master) employs these
two columns, which are not indexed.  This can lead to performance issues
when trying to fail over, since the query must perform a table scan,
especially when the master has been running with
'--ndb-log-empty-epochs=ON'.  You can improve multi-master failover
times by adding an index to these columns, as shown here:

     ALTER TABLE mysql.ndb_binlog_index
         ADD INDEX orig_lookup USING BTREE (orig_server_id, orig_epoch);

Adding this index provides no benefit when replicating from a single
master to a single slave, since the query used to get the binary log
position in such cases makes no use of 'orig_server_id' or 'orig_epoch'.

See mysql-cluster-replication-failover, for more information
about using the 'next_position' and 'next_file' columns.

The following figure shows the relationship of the NDB Cluster
replication master server, its binary log injector thread, and the
'mysql.ndb_binlog_index' table.

FIGURE GOES HERE: The Replication Master Cluster

An additional table, named 'ndb_apply_status', is used to keep a record
of the operations that have been replicated from the master to the
slave.  Unlike the case with 'ndb_binlog_index', the data in this table
is not specific to any one SQL node in the (slave) cluster, and so
'ndb_apply_status' can use the 'NDBCLUSTER' storage engine, as shown
here:

     CREATE TABLE `ndb_apply_status` (
         `server_id`   INT(10) UNSIGNED NOT NULL,
         `epoch`       BIGINT(20) UNSIGNED NOT NULL,
         `log_name`    VARCHAR(255) CHARACTER SET latin1 COLLATE latin1_bin NOT NULL,
         `start_pos`   BIGINT(20) UNSIGNED NOT NULL,
         `end_pos`     BIGINT(20) UNSIGNED NOT NULL,
         PRIMARY KEY (`server_id`) USING HASH
     ) ENGINE=NDBCLUSTER   DEFAULT CHARSET=latin1;

The 'ndb_apply_status' table is populated only on slaves, which means
that, on the master, this table never contains any rows; thus, there is
no need to allow for 'DataMemory' or 'IndexMemory' to be allotted to
'ndb_apply_status' there.

Because this table is populated from data originating on the master, it
should be allowed to replicate; any replication filtering or binary log
filtering rules that inadvertently prevent the slave from updating
'ndb_apply_status' or the master from writing into the binary log may
prevent replication between clusters from operating properly.  For more
information about potential problems arising from such filtering rules,
see mysql-cluster-replication-issues-filtering.

The 'ndb_binlog_index' and 'ndb_apply_status' tables are created in the
'mysql' database because they should not be explicitly replicated by the
user.  User intervention is normally not required to create or maintain
either of these tables, since both 'ndb_binlog_index' and the
'ndb_apply_status' are maintained by the 'NDB'.
binary log (binlog) injector thread.  This keeps the master
'mysqld' process updated to changes performed by the
'NDB' storage engine.  The 'NDB'.
_binlog injector thread_ receives events directly from the 'NDB'
storage engine.  The 'NDB' injector
is responsible for capturing all the data events within the cluster, and
ensures that all events which change, insert, or delete data are
recorded in the 'ndb_binlog_index' table.  The slave I/O thread
transfers the events from the master's binary log to the slave's relay
log.

However, it is advisable to check for the existence and integrity of
these tables as an initial step in preparing an NDB Cluster for
replication.  It is possible to view event data recorded in the binary
log by querying the 'mysql.ndb_binlog_index' table directly on the
master.  This can be also be accomplished using the 'SHOW BINLOG EVENTS'
statement on either the replication master
or slave MySQL servers.  (See show-binlog-events.)

You can also obtain useful information from the output of 'SHOW ENGINE NDB STATUS'.

The 'ndb_schema' table is used to track schema changes made to
'NDB' tables.  It is defined as shown here:

     CREATE TABLE ndb_schema (
         `db` VARBINARY(63) NOT NULL,
         `name` VARBINARY(63) NOT NULL,
         `slock` BINARY(32) NOT NULL,
         `query` BLOB NOT NULL,
         `node_id` INT UNSIGNED NOT NULL,
         `epoch` BIGINT UNSIGNED NOT NULL,
         `id` INT UNSIGNED NOT NULL,
         `version` INT UNSIGNED NOT NULL,
         `type` INT UNSIGNED NOT NULL,
         PRIMARY KEY USING HASH (db,name)
     ) ENGINE=NDB   DEFAULT CHARSET=latin1;

Unlike the two tables previously mentioned in this section, the
'ndb_schema' table is not visible either to MySQL 'SHOW'.
statements, or in any 'INFORMATION_SCHEMA' tables; however, it can be
seen in the output of 'ndb_show_tables',
as shown here:

     shell> ndb_show_tables -t 2
     id    type                 state    logging database     schema   name
     4     UserTable            Online   Yes     mysql        def      ndb_apply_status
     5     UserTable            Online   Yes     ndbworld     def      city
     6     UserTable            Online   Yes     ndbworld     def      country
     3     UserTable            Online   Yes     mysql        def      NDB$BLOB_2_3
     7     UserTable            Online   Yes     ndbworld     def      countrylanguage
     _2     UserTable            Online   Yes     mysql        def      ndb_schema_

     NDBT_ProgramExit: 0 - OK

It is also possible to 'SELECT' from this table in
'mysql' and other MySQL client applications, as shown here:

     mysql> SELECT * FROM mysql.ndb_schema WHERE name='city' \G
     *************************** 1. row ***************************
          db: ndbworld
        name: city
       slock:
       query: alter table City engine=ndb
     node_id: 4
       epoch: 0
          id: 0
     version: 0
        type: 7
     1 row in set (0.00 sec)

This can sometimes be useful when debugging applications.

*Note*:

When performing schema changes on 'NDB' tables,
applications should wait until the 'ALTER TABLE'.
statement has returned in the MySQL client connection that issued the
statement before attempting to use the updated definition of the table.

If the 'ndb_apply_status' table or the 'ndb_schema' table does not exist
on the slave, see 'ndb_restore'.
re-creates the missing table or tables (Bug #14612).

Conflict resolution for NDB Cluster Replication requires the presence of
an additional 'mysql.ndb_replication' table.  Currently, this table must
be created manually.  For information about how to do this, see
mysql-cluster-replication-conflict-resolution.

21.6.5 Preparing the NDB Cluster for Replication
------------------------------------------------

Preparing the NDB Cluster for replication consists of the following
steps:

  1. Check all MySQL servers for version compatibility (see
     mysql-cluster-replication-general).

  2. Create a slave account on the master Cluster with the appropriate
     privileges:

          mysqlM> GRANT REPLICATION SLAVE
               -> ON *.* TO 'SLAVE_USER'@'SLAVE_HOST'
               -> IDENTIFIED BY 'SLAVE_PASSWORD';

     In the previous statement, SLAVE_USER is the slave account user
     name, SLAVE_HOST is the host name or IP address of the replication
     slave, and SLAVE_PASSWORD is the password to assign to this
     account.

     For example, to create a slave user account with the name
     'myslave', logging in from the host named 'rep-slave', and using
     the password '53cr37', use the following 'GRANT'.
     statement:

          mysqlM> GRANT REPLICATION SLAVE
               -> ON *.* TO 'myslave'@'rep-slave'
               -> IDENTIFIED BY '53cr37';

     For security reasons, it is preferable to use a unique user
     account--not employed for any other purpose--for the replication
     slave account.

  3.
     Configure the slave to use the master.  Using the MySQL Monitor,
     this can be accomplished with the 'CHANGE MASTER TO'
     statement:

          mysqlS> CHANGE MASTER TO
               -> MASTER_HOST='MASTER_HOST',
               -> MASTER_PORT=MASTER_PORT,
               -> MASTER_USER='SLAVE_USER',
               -> MASTER_PASSWORD='SLAVE_PASSWORD';

     In the previous statement, MASTER_HOST is the host name or IP
     address of the replication master, MASTER_PORT is the port for the
     slave to use for connecting to the master, SLAVE_USER is the user
     name set up for the slave on the master, and SLAVE_PASSWORD is the
     password set for that user account in the previous step.

     For example, to tell the slave to replicate from the MySQL server
     whose host name is 'rep-master', using the replication slave
     account created in the previous step, use the following statement:

          mysqlS> CHANGE MASTER TO
               -> MASTER_HOST='rep-master',
               -> MASTER_PORT=3306,
               -> MASTER_USER='myslave',
               -> MASTER_PASSWORD='53cr37';

     For a complete list of options that can be used with this
     statement, see change-master-to.

     To provide replication backup capability, you also need to add an
     '--ndb-connectstring' option to the slave's 'my.cnf' file prior to
     starting the replication process.  See
     mysql-cluster-replication-backups, for details.

     For additional options that can be set in 'my.cnf' for replication
     slaves, see replication-options.

  4. If the master cluster is already in use, you can create a backup of
     the master and load this onto the slave to cut down on the amount
     of time required for the slave to synchronize itself with the
     master.  If the slave is also running NDB Cluster, this can be
     accomplished using the backup and restore procedure described in
     mysql-cluster-replication-backups.

          ndb-connectstring=MANAGEMENT_HOST[:PORT]

     In the event that you are _not_ using NDB Cluster on the
     replication slave, you can create a backup with this command on the
     replication master:

          shellM> mysqldump --master-data=1

     Then import the resulting data dump onto the slave by copying the
     dump file over to the slave.  After this, you can use the
     'mysql' client to import the data from the dumpfile into
     the slave database as shown here, where DUMP_FILE is the name of
     the file that was generated using 'mysqldump' on
     the master, and DB_NAME is the name of the database to be
     replicated:

          shellS> mysql -u root -p DB_NAME < DUMP_FILE

     For a complete list of options to use with 'mysqldump',
     see mysqldump.

     *Note*:

     If you copy the data to the slave in this fashion, you should make
     sure that the slave is started with the '--skip-slave-start' option
     on the command line, or else include 'skip-slave-start' in the
     slave's 'my.cnf' file to keep it from trying to connect to the
     master to begin replicating before all the data has been loaded.
     Once the data loading has completed, follow the additional steps
     outlined in the next two sections.

  5. Ensure that each MySQL server acting as a replication master is
     configured with a unique server ID, and with binary logging
     enabled, using the row format.  (See replication-formats.)
     These options can be set either in the master server's 'my.cnf'
     file, or on the command line when starting the master
     'mysqld' process.  See
     mysql-cluster-replication-starting, for information regarding the
     latter option.

21.6.6 Starting NDB Cluster Replication (Single Replication Channel)
--------------------------------------------------------------------

This section outlines the procedure for starting NDB Cluster replication
using a single replication channel.

  1. Start the MySQL replication master server by issuing this command:

          shellM> mysqld --ndbcluster --server-id=ID \
                  --log-bin &

     In the previous statement, ID is this server's unique ID (see
     mysql-cluster-replication-general).  This starts the server's
     'mysqld' process with binary logging enabled using
     the proper logging format.

     *Note*:

     You can also start the master with '--binlog-format=MIXED', in
     which case row-based replication is used automatically when
     replicating between clusters.  'STATEMENT' based binary logging is
     not supported for NDB Cluster Replication (see
     mysql-cluster-replication-general).

  2. Start the MySQL replication slave server as shown here:

          shellS> mysqld --ndbcluster --server-id=ID &

     In the command just shown, ID is the slave server's unique ID. It
     is not necessary to enable logging on the replication slave.

     *Note*:

     You should use the '--skip-slave-start' option with this command or
     else you should include 'skip-slave-start' in the slave server's
     'my.cnf' file, unless you want replication to begin immediately.
     With the use of this option, the start of replication is delayed
     until the appropriate 'START SLAVE' statement
     has been issued, as explained in Step 4 below.

  3. It is necessary to synchronize the slave server with the master
     server's replication binary log.  If binary logging has not
     previously been running on the master, run the following statement
     on the slave:

          mysqlS> CHANGE MASTER TO
               -> MASTER_LOG_FILE='',
               -> MASTER_LOG_POS=4;

     This instructs the slave to begin reading the master's binary log
     from the log's starting point.  Otherwise--that is, if you are
     loading data from the master using a backup--see
     mysql-cluster-replication-failover, for information on how to
     obtain the correct values to use for 'MASTER_LOG_FILE' and
     'MASTER_LOG_POS' in such cases.

  4. Finally, you must instruct the slave to begin applying replication
     by issuing this command from the 'mysql' client on
     the replication slave:

          mysqlS> START SLAVE;

     This also initiates the transmission of replication data from the
     master to the slave.

It is also possible to use two replication channels, in a manner similar
to the procedure described in the next section; the differences between
this and using a single replication channel are covered in
mysql-cluster-replication-two-channels.

It is also possible to improve cluster replication performance by
enabling _batched updates_.  This can be accomplished by setting the
'slave_allow_batching' system variable on the slave 'mysqld'
processes.  Normally, updates are applied as soon as they are
received.  However, the use of batching causes updates to be applied in
32 KB batches, which can result in higher throughput and less CPU usage,
particularly where individual updates are relatively small.

*Note*:

Slave batching works on a per-epoch basis; updates belonging to more
than one transaction can be sent as part of the same batch.

All outstanding updates are applied when the end of an epoch is reached,
even if the updates total less than 32 KB.

Batching can be turned on and off at runtime.  To activate it at
runtime, you can use either of these two statements:

     SET GLOBAL slave_allow_batching = 1;
     SET GLOBAL slave_allow_batching = ON;

If a particular batch causes problems (such as a statement whose effects
do not appear to be replicated correctly), slave batching can be
deactivated using either of the following statements:

     SET GLOBAL slave_allow_batching = 0;
     SET GLOBAL slave_allow_batching = OFF;

You can check whether slave batching is currently being used by means of
an appropriate 'SHOW VARIABLES' statement, like
this one:

     mysql> SHOW VARIABLES LIKE 'slave%';
     +---------------------------+-------+
     | Variable_name             | Value |
     +---------------------------+-------+
     | slave_allow_batching      | ON    |
     | slave_compressed_protocol | OFF   |
     | slave_load_tmpdir         | /tmp  |
     | slave_net_timeout         | 3600  |
     | slave_skip_errors         | OFF   |
     | slave_transaction_retries | 10    |
     +---------------------------+-------+
     6 rows in set (0.00 sec)

21.6.7 Using Two Replication Channels for NDB Cluster Replication
-----------------------------------------------------------------

In a more complete example scenario, we envision two replication
channels to provide redundancy and thereby guard against possible
failure of a single replication channel.  This requires a total of four
replication servers, two masters for the master cluster and two slave
servers for the slave cluster.  For purposes of the discussion that
follows, we assume that unique identifiers are assigned as shown here:

*NDB Cluster replication servers described in the text*

Server ID          Description

1                  Master - primary replication channel (_M_)

2                  Master - secondary replication channel (_M'_)

3                  Slave - primary replication channel (_S_)

4                  Slave - secondary replication channel (_S'_)

Setting up replication with two channels is not radically different from
setting up a single replication channel.  First, the 'mysqld'
processes for the primary and secondary replication masters must
be started, followed by those for the primary and secondary slaves.
Then the replication processes may be initiated by issuing the
'START SLAVE' statement on each of the slaves.  The
commands and the order in which they need to be issued are shown here:

  1. Start the primary replication master:

          shellM> mysqld --ndbcluster --server-id=1 \
                         --log-bin &

  2. Start the secondary replication master:

          shellM'> mysqld --ndbcluster --server-id=2 \
                         --log-bin &

  3. Start the primary replication slave server:

          shellS> mysqld --ndbcluster --server-id=3 \
                         --skip-slave-start &

  4. Start the secondary replication slave:

          shellS'> mysqld --ndbcluster --server-id=4 \
                          --skip-slave-start &

  5. Finally, initiate replication on the primary channel by executing
     the 'START SLAVE' statement on the primary
     slave as shown here:

          mysqlS> START SLAVE;

     *Warning*:

     Only the primary channel is to be started at this point.  The
     secondary replication channel is to be started only in the event
     that the primary replication channel fails, as described in
     mysql-cluster-replication-failover.  Running multiple replication
     channels simultaneously can result in unwanted duplicate records
     being created on the replication slaves.

As mentioned previously, it is not necessary to enable binary logging on
replication slaves.

21.6.8 Implementing Failover with NDB Cluster Replication
---------------------------------------------------------

In the event that the primary Cluster replication process fails, it is
possible to switch over to the secondary replication channel.  The
following procedure describes the steps required to accomplish this.

  1.
     Obtain the time of the most recent global checkpoint (GCP). That
     is, you need to determine the most recent epoch from the
     'ndb_apply_status' table on the slave cluster, which can be found
     using the following query:

          mysqlS'> SELECT @latest:=MAX(epoch)
                ->        FROM mysql.ndb_apply_status;

     In a circular replication topology, with a master and a slave
     running on each host, when you are using 'ndb_log_apply_status=1',
     NDB Cluster epochs are written in the slave binary logs.  This
     means that the 'ndb_apply_status' table contains information for
     the slave on this host as well as for any other host which acts as
     a slave of the master running on this host.

     In this case, you need to determine the latest epoch on this slave
     to the exclusion of any epochs from any other slaves in this
     slave's binary log that were not listed in the 'IGNORE_SERVER_IDS'
     options of the 'CHANGE MASTER TO'.
     statement used to set up this slave.  The reason for excluding such
     epochs is that rows in the 'mysql.ndb_apply_status' table whose
     server IDs have a match in the 'IGNORE_SERVER_IDS' list used with
     the CHANGE MASTER TO statement used to prepare this slave's master
     are also considered to be from local servers, in addition to those
     having the slave's own server ID. You can retrieve this list as
     'Replicate_Ignore_Server_Ids' from the output of 'SHOW SLAVE STATUS'.
     We assume that you have obtained this
     list and are substituting it for IGNORE_SERVER_IDS in the query
     shown here, which like the previous version of the query, selects
     the greatest epoch into a variable named '@latest':

          mysqlS'> SELECT @latest:=MAX(epoch)
                ->        FROM mysql.ndb_apply_status
                ->        WHERE server_id NOT IN (IGNORE_SERVER_IDS);

     In some cases, it may be simpler or more efficient (or both) to use
     a list of the server IDs to be included and 'server_id IN
     SERVER_ID_LIST' in the 'WHERE' condition of the preceding query.

  2.
     Using the information obtained from the query shown in Step 1,
     obtain the corresponding records from the 'ndb_binlog_index' table
     on the master cluster.

     You can use the following query to obtain the needed records from
     the master's 'ndb_binlog_index' table:

          mysqlM'> SELECT
                ->     @file:=SUBSTRING_INDEX(next_file, '/', -1),
                ->     @pos:=next_position
                -> FROM mysql.ndb_binlog_index
                -> WHERE epoch >= @latest
                -> ORDER BY epoch ASC LIMIT 1;

     These are the records saved on the master since the failure of the
     primary replication channel.  We have employed a user variable
     '@latest' here to represent the value obtained in Step 1.  Of
     course, it is not possible for one 'mysqld' instance
     to access user variables set on another server instance directly.
     These values must be 'plugged in' to the second query manually or
     in application code.

     *Important*:

     You must ensure that the slave 'mysqld' is started
     with '--slave-skip-errors=ddl_exist_errors' before executing
     'START SLAVE'.  Otherwise, replication may stop with
     duplicate DDL errors.

  3. Now it is possible to synchronize the secondary channel by running
     the following query on the secondary slave server:

          mysqlS'> CHANGE MASTER TO
                ->     MASTER_LOG_FILE='@file',
                ->     MASTER_LOG_POS=@pos;

     Again we have employed user variables (in this case '@file' and
     '@pos') to represent the values obtained in Step 2 and applied in
     Step 3; in practice these values must be inserted manually or using
     application code that can access both of the servers involved.

     *Note*:

     '@file' is a string value such as
     ''/var/log/mysql/replication-master-bin.00001'', and so must be
     quoted when used in SQL or application code.  However, the value
     represented by '@pos' must _not_ be quoted.  Although MySQL
     normally attempts to convert strings to numbers, this case is an
     exception.

  4. You can now initiate replication on the secondary channel by
     issuing the appropriate command on the secondary slave
     'mysqld'.:

          mysqlS'> START SLAVE;

Once the secondary replication channel is active, you can investigate
the failure of the primary and effect repairs.  The precise actions
required to do this will depend upon the reasons for which the primary
channel failed.

*Warning*:

The secondary replication channel is to be started only if and when the
primary replication channel has failed.  Running multiple replication
channels simultaneously can result in unwanted duplicate records being
created on the replication slaves.

If the failure is limited to a single server, it should (in theory) be
possible to replicate from M to S', or from M' to S; however, this has
not yet been tested.

21.6.9 NDB Cluster Backups With NDB Cluster Replication
-------------------------------------------------------

This section discusses making backups and restoring from them using NDB
Cluster replication.  We assume that the replication servers have
already been configured as covered previously (see
mysql-cluster-replication-preparation, and the sections immediately
following).  This having been done, the procedure for making a backup
and then restoring from it is as follows:

  1. There are two different methods by which the backup may be started.

        * Method A

          This method requires that the cluster backup process was
          previously enabled on the master server, prior to starting the
          replication process.  This can be done by including the
          following line in a '[mysql_cluster]' section in the 'my.cnf
          file', where MANAGEMENT_HOST is the IP address or host name of
          the 'NDB' management server for the
          master cluster, and PORT is the management server's port
          number:

               ndb-connectstring=MANAGEMENT_HOST[:PORT]

          *Note*:

          The port number needs to be specified only if the default port
          (1186) is not being used.  See
          mysql-cluster-install-configuration, for more information
          about ports and port allocation in NDB Cluster.

          In this case, the backup can be started by executing this
          statement on the replication master:

               shellM> ndb_mgm -e "START BACKUP"

        * Method B

          If the 'my.cnf' file does not specify where to find the
          management host, you can start the backup process by passing
          this information to the 'NDB' management
          client as part of the 'START BACKUP'
          command.  This
          can be done as shown here, where MANAGEMENT_HOST and PORT are
          the host name and port number of the management server:

               shellM> ndb_mgm MANAGEMENT_HOST:PORT -e "START BACKUP"

          In our scenario as outlined earlier (see
          mysql-cluster-replication-preparation), this would be
          executed as follows:

               shellM> ndb_mgm rep-master:1186 -e "START BACKUP"

  2. Copy the cluster backup files to the slave that is being brought on
     line.  Each system running an 'ndbd'
     process for the master cluster will
     have cluster backup files located on it, and _all_ of these files
     must be copied to the slave to ensure a successful restore.  The
     backup files can be copied into any directory on the computer where
     the slave management host resides, so long as the MySQL and NDB
     binaries have read permissions in that directory.  In this case, we
     will assume that these files have been copied into the directory
     '/var/BACKUPS/BACKUP-1'.

     It is not necessary that the slave cluster have the same number of
     'ndbd' processes (data nodes)
     as the master; however, it is highly recommended this number be the
     same.  It _is_ necessary that the slave be started with the
     '--skip-slave-start' option, to prevent premature startup of the
     replication process.

  3. Create any databases on the slave cluster that are present on the
     master cluster that are to be replicated to the slave.

     *Important*:

     A 'CREATE DATABASE'. (or 'CREATE SCHEMA')
     statement corresponding to each database
     to be replicated must be executed on each SQL node in the slave
     cluster.

  4. Reset the slave cluster using this statement in the MySQL Monitor:

          mysqlS> RESET SLAVE;

  5. You can now start the cluster restoration process on the
     replication slave using the 'ndb_restore'
     command for each backup file in
     turn.  For the first of these, it is necessary to include the '-m'
     option to restore the cluster metadata:

          shellS> ndb_restore -c SLAVE_HOST:PORT -n NODE-ID \
                  -b BACKUP-ID -m -r DIR

     DIR is the path to the directory where the backup files have been
     placed on the replication slave.  For the 'ndb_restore'
     commands corresponding to the
     remaining backup files, the '-m' option should _not_ be used.

     For restoring from a master cluster with four data nodes (as shown
     in the figure in mysql-cluster-replication) where the
     backup files have been copied to the directory
     '/var/BACKUPS/BACKUP-1', the proper sequence of commands to be
     executed on the slave might look like this:

          shellS> ndb_restore -c rep-slave:1186 -n 2 -b 1 -m \
                  -r ./var/BACKUPS/BACKUP-1
          shellS> ndb_restore -c rep-slave:1186 -n 3 -b 1 \
                  -r ./var/BACKUPS/BACKUP-1
          shellS> ndb_restore -c rep-slave:1186 -n 4 -b 1 \
                  -r ./var/BACKUPS/BACKUP-1
          shellS> ndb_restore -c rep-slave:1186 -n 5 -b 1 -e \
                  -r ./var/BACKUPS/BACKUP-1

     *Important*:

     The '-e' (or '--restore_epoch') option in the final invocation of
     'ndb_restore' in this
     example is required in order that the epoch is written to the slave
     'mysql.ndb_apply_status'.  Without this information, the slave will
     not be able to synchronize properly with the master.  (See
     mysql-cluster-programs-ndb-restore.)

  6. Now you need to obtain the most recent epoch from the
     'ndb_apply_status' table on the slave (as discussed in
     mysql-cluster-replication-failover):

          mysqlS> SELECT @latest:=MAX(epoch)
                  FROM mysql.ndb_apply_status;

  7. Using '@latest' as the epoch value obtained in the previous step,
     you can obtain the correct starting position '@pos' in the correct
     binary log file '@file' from the master's 'mysql.ndb_binlog_index'
     table using the query shown here:

          mysqlM> SELECT
               ->     @file:=SUBSTRING_INDEX(File, '/', -1),
               ->     @pos:=Position
               -> FROM mysql.ndb_binlog_index
               -> WHERE epoch >= @latest
               -> ORDER BY epoch ASC LIMIT 1;

     In the event that there is currently no replication traffic, you
     can get this information by running 'SHOW MASTER STATUS'
     on the master and using the value in the
     'Position' column for the file whose name has the suffix with the
     greatest value for all files shown in the 'File' column.  However,
     in this case, you must determine this and supply it in the next
     step manually or by parsing the output with a script.

  8. Using the values obtained in the previous step, you can now issue
     the appropriate 'CHANGE MASTER TO'.
     statement in the slave's 'mysql' client:

          mysqlS> CHANGE MASTER TO
               ->     MASTER_LOG_FILE='@file',
               ->     MASTER_LOG_POS=@pos;

  9. Now that the slave 'knows' from what point in which binary log file
     to start reading data from the master, you can cause the slave to
     begin replicating with this standard MySQL statement:

          mysqlS> START SLAVE;

To perform a backup and restore on a second replication channel, it is
necessary only to repeat these steps, substituting the host names and
IDs of the secondary master and slave for those of the primary master
and slave replication servers where appropriate, and running the
preceding statements on them.

For additional information on performing Cluster backups and restoring
Cluster from backups, see mysql-cluster-backup.

21.6.9.1 NDB Cluster Replication: Automating Synchronization of the Replication Slave to the Master Binary Log
..............................................................................................................

It is possible to automate much of the process described in the previous
section (see mysql-cluster-replication-backups).  The following
Perl script 'reset-slave.pl' serves as an example of how you can do
this.

     #!/user/bin/perl -w

     #  file: reset-slave.pl

     #  Copyright (C)2005 MySQL AB

     #  This program is free software; you can redistribute it and/or modify
     #  it under the terms of the GNU General Public License as published by
     #  the Free Software Foundation; either version 2 of the License, or
     #  (at your option) any later version.

     #  This program is distributed in the hope that it will be useful,
     #  but WITHOUT ANY WARRANTY; without even the implied warranty of
     #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     #  GNU General Public License for more details.

     #  You should have received a copy of the GNU General Public License
     #  along with this program; if not, write to:
     #  Free Software Foundation, Inc.
     #  59 Temple Place, Suite 330
     #  Boston, MA 02111-1307 USA
     #
     #  Version 1.1

     ######################## Includes ###############################

     use DBI;

     ######################## Globals ################################

     my  $m_host='';
     my  $m_port='';
     my  $m_user='';
     my  $m_pass='';
     my  $s_host='';
     my  $s_port='';
     my  $s_user='';
     my  $s_pass='';
     my  $dbhM='';
     my  $dbhS='';

     ####################### Sub Prototypes ##########################

     sub CollectCommandPromptInfo;
     sub ConnectToDatabases;
     sub DisconnectFromDatabases;
     sub GetSlaveEpoch;
     sub GetMasterInfo;
     sub UpdateSlave;

     ######################## Program Main ###########################

     CollectCommandPromptInfo;
     ConnectToDatabases;
     GetSlaveEpoch;
     GetMasterInfo;
     UpdateSlave;
     DisconnectFromDatabases;

     ################## Collect Command Prompt Info ##################

     sub CollectCommandPromptInfo
     {
       ### Check that user has supplied correct number of command line args
       die "Usage:\n
            reset-slave >master MySQL host< >master MySQL port< \n
                        >master user< >master pass< >slave MySQL host< \n
                        >slave MySQL port< >slave user< >slave pass< \n
            All 8 arguments must be passed. Use BLANK for NULL passwords\n"
            unless @ARGV == 8;

       $m_host  =  $ARGV[0];
       $m_port  =  $ARGV[1];
       $m_user  =  $ARGV[2];
       $m_pass  =  $ARGV[3];
       $s_host  =  $ARGV[4];
       $s_port  =  $ARGV[5];
       $s_user  =  $ARGV[6];
       $s_pass  =  $ARGV[7];

       if ($m_pass eq "BLANK") { $m_pass = '';}
       if ($s_pass eq "BLANK") { $s_pass = '';}
     }

     ###############  Make connections to both databases #############

     sub ConnectToDatabases
     {
       ### Connect to both master and slave cluster databases

       ### Connect to master
       $dbhM
         = DBI->connect(
         "dbi:mysql:database=mysql;host=$m_host;port=$m_port",
         "$m_user", "$m_pass")
           or die "Can't connect to Master Cluster MySQL process!
                   Error: $DBI::errstr\n";

       ### Connect to slave
       $dbhS
         = DBI->connect(
               "dbi:mysql:database=mysql;host=$s_host",
               "$s_user", "$s_pass")
         or die "Can't connect to Slave Cluster MySQL process!
                 Error: $DBI::errstr\n";
     }

     ################  Disconnect from both databases ################

     sub DisconnectFromDatabases
     {
       ### Disconnect from master

       $dbhM->disconnect
       or warn " Disconnection failed: $DBI::errstr\n";

       ### Disconnect from slave

       $dbhS->disconnect
       or warn " Disconnection failed: $DBI::errstr\n";
     }

     ######################  Find the last good GCI ##################

     sub GetSlaveEpoch
     {
       $sth = $dbhS->prepare("SELECT MAX(epoch)
                              FROM mysql.ndb_apply_status;")
           or die "Error while preparing to select epoch from slave: ",
                  $dbhS->errstr;

       $sth->execute
           or die "Selecting epoch from slave error: ", $sth->errstr;

       $sth->bind_col (1, \$epoch);
       $sth->fetch;
       print "\tSlave Epoch =  $epoch\n";
       $sth->finish;
     }

     #######  Find the position of the last GCI in the binary log ########

     sub GetMasterInfo
     {
       $sth = $dbhM->prepare("SELECT
                                SUBSTRING_INDEX(File, '/', -1), Position
                              FROM mysql.ndb_binlog_index
                              WHERE epoch > $epoch
                              ORDER BY epoch ASC LIMIT 1;")
           or die "Prepare to select from master error: ", $dbhM->errstr;

       $sth->execute
           or die "Selecting from master error: ", $sth->errstr;

       $sth->bind_col (1, \$binlog);
       $sth->bind_col (2, \$binpos);
       $sth->fetch;
       print "\tMaster binary log =  $binlog\n";
       print "\tMaster binary log position =  $binpos\n";
       $sth->finish;
     }

     ##########  Set the slave to process from that location #########

     sub UpdateSlave
     {
       $sth = $dbhS->prepare("CHANGE MASTER TO
                              MASTER_LOG_FILE='$binlog',
                              MASTER_LOG_POS=$binpos;")
           or die "Prepare to CHANGE MASTER error: ", $dbhS->errstr;

       $sth->execute
            or die "CHANGE MASTER on slave error: ", $sth->errstr;
       $sth->finish;
       print "\tSlave has been updated. You may now start the slave.\n";
     }

     # end reset-slave.pl

21.6.9.2 Point-In-Time Recovery Using NDB Cluster Replication
.............................................................

_Point-in-time_ recovery--that is, recovery of data changes made since a
given point in time--is performed after restoring a full backup that
returns the server to its state when the backup was made.  Performing
point-in-time recovery of NDB Cluster tables with NDB Cluster and NDB
Cluster Replication can be accomplished using a native 'NDB'
data backup (taken by issuing 'CREATE BACKUP' in the
'ndb_mgm' client) and restoring
the 'ndb_binlog_index' table (from a dump made using 'mysqldump').

To perform point-in-time recovery of NDB Cluster, it is necessary to
follow the steps shown here:

  1. Back up all 'NDB' databases in the cluster, using the 'START BACKUP'
     command in
     the 'ndb_mgm' client (see
     mysql-cluster-backup).

  2. At some later point, prior to restoring the cluster, make a backup
     of the 'mysql.ndb_binlog_index' table.  It is probably simplest to
     use 'mysqldump' for this task.  Also back up the
     binary log files at this time.

     This backup should be updated regularly--perhaps even
     hourly--depending on your needs.

  3. (_Catastrophic failure or error occurs_.)

  4. Locate the last known good backup.

  5. Clear the data node file systems (using 'ndbd'.
     '--initial' or 'ndbmtd'.
     '--initial').

     *Note*:

     NDB Cluster Disk Data tablespace and log files are not removed by
     '--initial'.  You must delete these manually.

  6. Use 'DROP TABLE' or 'TRUNCATE TABLE'
     with the 'mysql.ndb_binlog_index' table.

  7. Execute 'ndb_restore',
     restoring all data.  You must include the '--restore_epoch' option
     when you run 'ndb_restore',
     so that the 'ndb_apply_status'
     table is populated correctly.  (See
     mysql-cluster-programs-ndb-restore, for more information.)

  8. Restore the 'ndb_binlog_index' table from the output of
     'mysqldump' and restore the binary log files from
     backup, if necessary.

  9. Find the epoch applied most recently--that is, the maximum 'epoch'
     column value in the 'ndb_apply_status' table--as the user variable
     '@LATEST_EPOCH' (emphasized):

          SELECT _@LATEST_EPOCH_:=MAX(epoch)
              FROM mysql.ndb_apply_status;

  10. Find the latest binary log file ('@FIRST_FILE') and position
     ('Position' column value) within this file that correspond to
     '@LATEST_EPOCH' in the 'ndb_binlog_index' table:

          SELECT Position, _@FIRST_FILE_:=File
              FROM mysql.ndb_binlog_index
              WHERE epoch > _@LATEST_EPOCH_ ORDER BY epoch ASC LIMIT 1;

  11. Using 'mysqlbinlog', replay the binary log
     events from the given file and position up to the point of the
     failure.  (See mysqlbinlog.)

See also point-in-time-recovery, for more information about the
binary log, replication, and incremental recovery.

21.6.10 NDB Cluster Replication: Multi-Master and Circular Replication
----------------------------------------------------------------------

It is possible to use NDB Cluster in multi-master replication, including
circular replication between a number of NDB Clusters.

Circular replication example

In the next few paragraphs we consider the example of a replication
setup involving three NDB Clusters numbered 1, 2, and 3, in which
Cluster 1 acts as the replication master for Cluster 2, Cluster 2 acts
as the master for Cluster 3, and Cluster 3 acts as the master for
Cluster 1.  Each cluster has two SQL nodes, with SQL nodes A and B
belonging to Cluster 1, SQL nodes C and D belonging to Cluster 2, and
SQL nodes E and F belonging to Cluster 3.

Circular replication using these clusters is supported as long as the
following conditions are met:

   * The SQL nodes on all masters and slaves are the same

   * All SQL nodes acting as replication masters and slaves are started
     using the '--log-slave-updates' option

This type of circular replication setup is shown in the following
diagram:

FIGURE GOES HERE: NDB Cluster Circular Replication with All Masters As
Slaves

In this scenario, SQL node A in Cluster 1 replicates to SQL node C in
Cluster 2; SQL node C replicates to SQL node E in Cluster 3; SQL node E
replicates to SQL node A. In other words, the replication line
(indicated by the red arrows in the diagram) directly connects all SQL
nodes used as replication masters and slaves.

It is also possible to set up circular replication in such a way that
not all master SQL nodes are also slaves, as shown here:

FIGURE GOES HERE: NDB Cluster Circular Replication Where Not All Masters
Are Slaves

In this case, different SQL nodes in each cluster are used as
replication masters and slaves.  However, you must _not_ start any of
the SQL nodes using '--log-slave-updates'.  This type of circular
replication scheme for NDB Cluster, in which the line of replication
(again indicated by the red arrows in the diagram) is discontinuous,
should be possible, but it should be noted that it has not yet been
thoroughly tested and must therefore still be considered experimental.

Using NDB-native backup and restore to initialize a slave NDB Cluster

When setting up circular replication, it is possible to initialize the
slave cluster by using the management client 'BACKUP' command on one NDB
Cluster to create a backup and then applying this backup on another NDB
Cluster using 'ndb_restore'.
However, this does not automatically create binary logs on the second
NDB Cluster 's SQL node acting as the replication slave.  In order to
cause the binary logs to be created, you must issue a 'SHOW TABLES'
statement on that SQL node; this should be done
prior to running 'START SLAVE'.

This is a known issue which we intend to address in a future release.

Multi-master failover example

In this section, we discuss failover in a multi-master NDB Cluster
replication setup with three NDB Clusters having server IDs 1, 2, and 3.
In this scenario, Cluster 1 replicates to Clusters 2 and 3; Cluster 2
also replicates to Cluster 3.  This relationship is shown here:

FIGURE GOES HERE: NDB Cluster Multi-Master Replication With 3 Masters

In other words, data replicates from Cluster 1 to Cluster 3 through 2
different routes: directly, and by way of Cluster 2.

Not all MySQL servers taking part in multi-master replication must act
as both master and slave, and a given NDB Cluster might use different
SQL nodes for different replication channels.  Such a case is shown
here:

FIGURE GOES HERE: NDB Cluster Multi-Master Replication, With MySQL
Servers

MySQL servers acting as replication slaves must be run with the
'--log-slave-updates' option.  Which 'mysqld' processes
require this option is also shown in the preceding diagram.

*Note*:

Using the '--log-slave-updates' option has no effect on servers not
being run as replication slaves.

The need for failover arises when one of the replicating clusters goes
down.  In this example, we consider the case where Cluster 1 is lost to
service, and so Cluster 3 loses 2 sources of updates from Cluster 1.
Because replication between NDB Clusters is asynchronous, there is no
guarantee that Cluster 3's updates originating directly from Cluster 1
are more recent than those received through Cluster 2.  You can handle
this by ensuring that Cluster 3 catches up to Cluster 2 with regard to
updates from Cluster 1.  In terms of MySQL servers, this means that you
need to replicate any outstanding updates from MySQL server C to server
F.

On server C, perform the following queries:

     mysqlC> SELECT @latest:=MAX(epoch)
          ->     FROM mysql.ndb_apply_status
          ->     WHERE server_id=1;

     mysqlC> SELECT
          ->     @file:=SUBSTRING_INDEX(File, '/', -1),
          ->     @pos:=Position
          ->     FROM mysql.ndb_binlog_index
          ->     WHERE orig_epoch >= @latest
          ->     AND orig_server_id = 1
          ->     ORDER BY epoch ASC LIMIT 1;

*Note*:

You can improve the performance of this query, and thus likely speed up
failover times significantly, by adding the appropriate index to the
'ndb_binlog_index' table.  See mysql-cluster-replication-schema,
for more information.

Copy over the values for @FILE and @POS manually from server C to server
F (or have your application perform the equivalent).  Then, on server F,
execute the following 'CHANGE MASTER TO'.
statement:

     mysqlF> CHANGE MASTER TO
          ->     MASTER_HOST = 'serverC'
          ->     MASTER_LOG_FILE='@file',
          ->     MASTER_LOG_POS=@pos;

Once this has been done, you can issue a 'START SLAVE'
statement on MySQL server F, and any missing updates
originating from server B will be replicated to server F.

The 'CHANGE MASTER TO' statement also supports
an 'IGNORE_SERVER_IDS' option which takes a comma-separated list of
server IDs and causes events originating from the corresponding servers
to be ignored.  For more information, see change-master-to, and
show-slave-status.  For information about how this option
intereacts with the 'ndb_log_apply_status' variable, see
mysql-cluster-replication-failover.

21.6.11 NDB Cluster Replication Conflict Resolution
---------------------------------------------------

When using a replication setup involving multiple masters (including
circular replication), it is possible that different masters may try to
update the same row on the slave with different data.  Conflict
resolution in NDB Cluster Replication provides a means of resolving such
conflicts by permitting a user-defined resolution column to be used to
determine whether or not an update on a given master should be applied
on the slave.

Some types of conflict resolution supported by NDB Cluster ('NDB$OLD()',
'NDB$MAX()', 'NDB$MAX_DELETE_WIN()') implement this user-defined column
as a 'timestamp' column (although its type cannot be 'TIMESTAMP',
as explained later in this section).  These types of conflict
resolution are always applied a row-by-row basis rather than a
transactional basis.  The epoch-based conflict resolution functions
'NDB$EPOCH()' and 'NDB$EPOCH_TRANS()' compare the order in which epochs
are replicated (and thus these functions are transactional).  Different
methods can be used to compare resolution column values on the slave
when conflicts occur, as explained later in this section; the method
used can be set on a per-table basis.

You should also keep in mind that it is the application's responsibility
to ensure that the resolution column is correctly populated with
relevant values, so that the resolution function can make the
appropriate choice when determining whether to apply an update.

Requirements

Preparations for conflict resolution must be made on both the master and
the slave.  These tasks are described in the following list:

   * On the master writing the binary logs, you must determine which
     columns are sent (all columns or only those that have been
     updated).  This is done for the MySQL Server as a whole by applying
     the 'mysqld' startup option '--ndb-log-updated-only'
     (described later in this section) or on a per-table basis by
     entries in the 'mysql.ndb_replication' table (see
     mysql-cluster-ndb-replication-table).

     *Note*:

     If you are replicating tables with very large columns (such as
     'TEXT' or 'BLOB' columns),
     '--ndb-log-updated-only' can also be useful for reducing the size
     of the master and slave binary logs and avoiding possible
     replication failures due to exceeding 'max_allowed_packet'.

     See replication-features-max-allowed-packet, for more
     information about this issue.

   * On the slave, you must determine which type of conflict resolution
     to apply ('latest timestamp wins', 'same timestamp wins', 'primary
     wins', 'primary wins, complete transaction', or none).  This is
     done using the 'mysql.ndb_replication' system table, on a per-table
     basis (see mysql-cluster-ndb-replication-table).

   * NDB Cluster also supports read conflict detection, that is,
     detecting conflicts between reads of a given row in one cluster and
     updates or deletes of the same row in another cluster.  This
     requires exclusive read locks obtained by setting
     'ndb_log_exclusive_reads' equal to 1 on the slave.  All rows read
     by a conflicting read are logged in the exceptions table.  For more
     information, see
     mysql-cluster-replication-examples-read-conflicts.

When using the functions 'NDB$OLD()', 'NDB$MAX()', and
'NDB$MAX_DELETE_WIN()' for timestamp-based conflict resolution, we often
refer to the column used for determining updates as a 'timestamp'
column.  However, the data type of this column is never
'TIMESTAMP'.; instead, its data type should be 'INT'.
(see 'INTEGER') or 'BIGINT'.
The 'timestamp' column should also be 'UNSIGNED' and
'NOT NULL'.

The 'NDB$EPOCH()' and 'NDB$EPOCH_TRANS()' functions discussed later in
this section work by comparing the relative order of replication epochs
applied on a primary and secondary NDB Cluster, and do not make use of
timestamps.

Master column control

We can see update operations in terms of 'before' and 'after'
images--that is, the states of the table before and after the update is
applied.  Normally, when updating a table with a primary key, the
'before' image is not of great interest; however, when we need to
determine on a per-update basis whether or not to use the updated values
on a replication slave, we need to make sure that both images are
written to the master's binary log.  This is done with the
'--ndb-log-update-as-write' option for 'mysqld', as
described later in this section.

*Important*:

Whether logging of complete rows or of updated columns only is done is
decided when the MySQL server is started, and cannot be changed online;
you must either restart 'mysqld', or start a new
'mysqld' instance with different logging options.

*Logging Full or Partial Rows (-ndb-log-updated-only Option)*

Property                             Value

*Command-Line Format*                '--ndb-log-updated-only'

*System Variable*                    'ndb_log_updated_only'

*Scope*                              Global

*Dynamic*                            Yes

*Type*                               boolean

*Default Value*                      'ON'

For purposes of conflict resolution, there are two basic methods of
logging rows, as determined by the setting of the
'--ndb-log-updated-only' option for 'mysqld'.:

   * Log complete rows

   * Log only column data that has been updated--that is, column data
     whose value has been set, regardless of whether or not this value
     was actually changed.  This is the default behavior.

It is usually sufficient--and more efficient--to log updated columns
only; however, if you need to log full rows, you can do so by setting
'--ndb-log-updated-only' to '0' or 'OFF'.

*-ndb-log-update-as-write Option: Logging Changed Data as Updates*

Property                             Value

*Command-Line Format*                '--ndb-log-update-as-write'

*System Variable*                    'ndb_log_update_as_write'

*Scope*                              Global

*Dynamic*                            Yes

*Type*                               boolean

*Default Value*                      'ON'

The setting of the MySQL Server's '--ndb-log-update-as-write' option
determines whether logging is performed with or without the 'before'
image.  Because conflict resolution is done in the MySQL Server's update
handler, it is necessary to control logging on the master such that
updates are updates and not writes; that is, such that updates are
treated as changes in existing rows rather than the writing of new rows
(even though these replace existing rows).  This option is turned on by
default; in other words, updates are treated as writes.  (That is,
updates are by default written as 'write_row' events in the binary log,
rather than as 'update_row' events.)

To turn off the option, start the master 'mysqld' with
'--ndb-log-update-as-write=0' or '--ndb-log-update-as-write=OFF'.  You
must do this when replicating from NDB tables to tables using a
different storage engine; see
mysql-cluster-replication-ndb-to-non-ndb, and
mysql-cluster-replication-ndb-to-nontransactional, for more
information.

Conflict resolution control

Conflict resolution is usually enabled on the server where conflicts can
occur.  Like logging method selection, it is enabled by entries in the
'mysql.ndb_replication' table.

The ndb_replication system table

To enable conflict resolution, it is necessary to create an
'ndb_replication' table in the 'mysql' system database on the master,
the slave, or both, depending on the conflict resolution type and method
to be employed.  This table is used to control logging and conflict
resolution functions on a per-table basis, and has one row per table
involved in replication.  'ndb_replication' is created and filled with
control information on the server where the conflict is to be resolved.
In a simple master-slave setup where data can also be changed locally on
the slave this will typically be the slave.  In a more complex
master-master (2-way) replication schema this will usually be all of the
masters involved.  Each row in 'mysql.ndb_replication' corresponds to a
table being replicated, and specifies how to log and resolve conflicts
(that is, which conflict resolution function, if any, to use) for that
table.  The definition of the 'mysql.ndb_replication' table is shown
here:

     CREATE TABLE mysql.ndb_replication  (
         db VARBINARY(63),
         table_name VARBINARY(63),
         server_id INT UNSIGNED,
         binlog_type INT UNSIGNED,
         conflict_fn VARBINARY(128),
         PRIMARY KEY USING HASH (db, table_name, server_id)
     )   ENGINE=NDB
     PARTITION BY KEY(db,table_name);

The columns in this table are described in the next few paragraphs.

db

The name of the database containing the table to be replicated.  You may
employ either or both of the wildcards '_' and '%' as part of the
database name.  Matching is similar to what is implemented for the
'LIKE' operator.

table_name

The name of the table to be replicated.  The table name may include
either or both of the wildcards '_' and '%'.  Matching is similar to
what is implemented for the 'LIKE' operator.

server_id

The unique server ID of the MySQL instance (SQL node) where the table
resides.

binlog_type

The type of binary logging to be employed.  This is determined as shown
in the following table:

*binlog_type values, with internal values and descriptions*

Value          Internal       Description
               Value

0              'NBT_DEFAULT'  Use server default

1              'NBT_NO_LOGGING'Do not log this table in the binary log

2              'NBT_UPDATED_ONLY'Only updated attributes are logged

3              'NBT_FULL'     Log full row, even if not updated (MySQL
                              server default behavior)

4              'NBT_USE_UPDATE'(For generating
                              'NBT_UPDATED_ONLY_USE_UPDATE' and
                              'NBT_FULL_USE_UPDATE' values only--not
                              intended for separate use)

5              [_Not used_]   --

6              'NBT_UPDATED_ONLY_USE_UPDATE'Use updated attributes, even if values
               (equal to      are unchanged
               'NBT_UPDATED_ONLY
               |
               NBT_USE_UPDATE')

7              'NBT_FULL_USE_UPDATE'Use full row, even if values are
               (equal to      unchanged
               'NBT_FULL |
               NBT_USE_UPDATE')

conflict_fn

The conflict resolution function to be applied.  This function must be
specified as one of those shown in the following list:

   * mysql-cluster-replication-ndb-old

   * mysql-cluster-replication-ndb-max

   * mysql-cluster-replication-ndb-max-delete-win

   * mysql-cluster-replication-ndb-epoch

   * mysql-cluster-replication-ndb-epoch-trans

   * mysql-cluster-replication-ndb-epoch2

   * mysql-cluster-replication-ndb-epoch2-trans

   * 'NULL': Indicates that conflict resolution is not to be used for
     the corresponding table.

These functions are described in the next few paragraphs.

NDB$OLD(column_name)

If the value of COLUMN_NAME is the same on both the master and the
slave, then the update is applied; otherwise, the update is not applied
on the slave and an exception is written to the log.  This is
illustrated by the following pseudocode:

     if (MASTER_OLD_COLUMN_VALUE == SLAVE_CURRENT_COLUMN_VALUE)
       apply_update();
     else
       log_exception();

This function can be used for 'same value wins' conflict resolution.
This type of conflict resolution ensures that updates are not applied on
the slave from the wrong master.

*Important*:

The column value from the master's 'before' image is used by this
function.

NDB$MAX(column_name)

If the 'timestamp' column value for a given row coming from the master
is higher than that on the slave, it is applied; otherwise it is not
applied on the slave.  This is illustrated by the following pseudocode:

     if (MASTER_NEW_COLUMN_VALUE > SLAVE_CURRENT_COLUMN_VALUE)
       apply_update();

This function can be used for 'greatest timestamp wins' conflict
resolution.  This type of conflict resolution ensures that, in the event
of a conflict, the version of the row that was most recently updated is
the version that persists.

*Important*:

The column value from the master's 'after' image is used by this
function.

NDB$MAX_DELETE_WIN()

This is a variation on 'NDB$MAX()'.  Due to the fact that no timestamp
is available for a delete operation, a delete using 'NDB$MAX()' is in
fact processed as 'NDB$OLD'.  However, for some use cases, this is not
optimal.  For 'NDB$MAX_DELETE_WIN()', if the 'timestamp' column value
for a given row adding or updating an existing row coming from the
master is higher than that on the slave, it is applied.  However, delete
operations are treated as always having the higher value.  This is
illustrated in the following pseudocode:

     if ( (MASTER_NEW_COLUMN_VALUE > SLAVE_CURRENT_COLUMN_VALUE)
             ||
           OPERATION.TYPE == "delete")
       apply_update();

This function can be used for 'greatest timestamp, delete wins' conflict
resolution.  This type of conflict resolution ensures that, in the event
of a conflict, the version of the row that was deleted or (otherwise)
most recently updated is the version that persists.

*Note*:

As with 'NDB$MAX()', the column value from the master's 'after' image is
the value used by this function.

NDB$EPOCH() and NDB$EPOCH_TRANS()

The 'NDB$EPOCH()' function tracks the order in which replicated epochs
are applied on a slave NDB Cluster relative to changes originating on
the slave.  This relative ordering is used to determine whether changes
originating on the slave are concurrent with any changes that originate
locally, and are therefore potentially in conflict.

Most of what follows in the description of 'NDB$EPOCH()' also applies to
'NDB$EPOCH_TRANS()'.  Any exceptions are noted in the text.

'NDB$EPOCH()' is asymmetric, operating on one NDB Cluster in a
two-cluster circular replication configuration (sometimes referred to as
'active-active' replication).  We refer here to cluster on which it
operates as the primary, and the other as the secondary.  The slave on
the primary is responsible for detecting and handling conflicts, while
the slave on the secondary is not involved in any conflict detection or
handling.

When the slave on the primary detects conflicts, it injects events into
its own binary log to compensate for these; this ensures that the
secondary NDB Cluster eventually realigns itself with the primary and so
keeps the primary and secondary from diverging.  This compensation and
realignment mechanism requires that the primary NDB Cluster always wins
any conflicts with the secondary--that is, that the primary's changes
are always used rather than those from the secondary in event of a
conflict.  This 'primary always wins' rule has the following
implications:

   * Operations that change data, once committed on the primary, are
     fully persistent and will not be undone or rolled back by conflict
     detection and resolution.

   * Data read from the primary is fully consistent.  Any changes
     committed on the Primary (locally or from the slave) will not be
     reverted later.

   * Operations that change data on the secondary may later be reverted
     if the primary determines that they are in conflict.

   * Individual rows read on the secondary are self-consistent at all
     times, each row always reflecting either a state committed by the
     secondary, or one committed by the primary.

   * Sets of rows read on the secondary may not necessarily be
     consistent at a given single point in time.  For
     'NDB$EPOCH_TRANS()', this is a transient state; for 'NDB$EPOCH()',
     it can be a persistent state.

   * Assuming a period of sufficient length without any conflicts, all
     data on the secondary NDB Cluster (eventually) becomes consistent
     with the primary's data.

'NDB$EPOCH()' and 'NDB$EPOCH_TRANS()' do not require any user schema
modifications, or application changes to provide conflict detection.
However, careful thought must be given to the schema used, and the
access patterns used, to verify that the complete system behaves within
specified limits.

Each of the 'NDB$EPOCH()' and 'NDB$EPOCH_TRANS()' functions can take an
optional parameter; this is the number of bits to use to represent the
lower 32 bits of the epoch, and should be set to no less than

     CEIL( LOG2( TimeBetweenGlobalCheckpoints / TimeBetweenEpochs ), 1)

For the default values of these configuration parameters (2000 and 100
milliseconds, respectively), this gives a value of 5 bits, so the
default value (6) should be sufficient, unless other values are used for
'TimeBetweenGlobalCheckpoints', 'TimeBetweenEpochs', or both.  A value
that is too small can result in false positives, while one that is too
large could lead to excessive wasted space in the database.

Both 'NDB$EPOCH()' and 'NDB$EPOCH_TRANS()' insert entries for
conflicting rows into the relevant exceptions tables, provided that
these tables have been defined according to the same exceptions table
schema rules as described elsewhere in this section (see
mysql-cluster-replication-ndb-old).  You need to create any exceptions
table before creating the table with which it is to be used.

As with the other conflict detection functions discussed in this
section, 'NDB$EPOCH()' and 'NDB$EPOCH_TRANS()' are activated by
including relevant entries in the 'mysql.ndb_replication' table (see
mysql-cluster-ndb-replication-table).  The roles of the primary
and secondary NDB Clusters in this scenario are fully determined by
'mysql.ndb_replication' table entries.

Because the conflict detection algorithms employed by 'NDB$EPOCH()' and
'NDB$EPOCH_TRANS()' are asymmetric, you must use different values for
the primary slave's and secondary slave's 'server_id' entries.

A conflict between 'DELETE' operations alone is not sufficient to
trigger a conflict using 'NDB$EPOCH()' or 'NDB$EPOCH_TRANS()', and the
relative placement within epochs does not matter.  (Bug #18459944)

Conflict detection status variables

Several status variables can be used to monitor conflict detection.  You
can see how many rows have been found in conflict by 'NDB$EPOCH()' since
this slave was last restarted from the current value of the
'Ndb_conflict_fn_epoch' system status variable.

'Ndb_conflict_fn_epoch_trans' provides the number of rows that have been
found directly in conflict by 'NDB$EPOCH_TRANS()'.
'Ndb_conflict_fn_epoch2' and 'Ndb_conflict_fn_epoch2_trans' show the
number of rows found in conflict by 'NDB$EPOCH2()' and
'NDB$EPOCH2_TRANS()', respectively.  The number of rows actually
realigned, including those affected due to their membership in or
dependency on the same transactions as other conflicting rows, is given
by 'Ndb_conflict_trans_row_reject_count'.

For more information, see mysql-cluster-status-variables.

Limitations on NDB$EPOCH()

The following limitations currently apply when using 'NDB$EPOCH()' to
perform conflict detection:

   * Conflicts are detected using NDB Cluster epoch boundaries, with
     granularity proportional to 'TimeBetweenEpochs' (default: 100
     milliseconds).  The minimum conflict window is the minimum time
     during which concurrent updates to the same data on both clusters
     always report a conflict.  This is always a nonzero length of time,
     and is roughly proportional to '2 * (latency + queueing +
     TimeBetweenEpochs)'.  This implies that--assuming the default for
     'TimeBetweenEpochs' and ignoring any latency between clusters (as
     well as any queuing delays)--the minimum conflict window size is
     approximately 200 milliseconds.  This minimum window should be
     considered when looking at expected application 'race' patterns.

   * Additional storage is required for tables using the 'NDB$EPOCH()'
     and 'NDB$EPOCH_TRANS()' functions; from 1 to 32 bits extra space
     per row is required, depending on the value passed to the function.

   * Conflicts between delete operations may result in divergence
     between the primary and secondary.  When a row is deleted on both
     clusters concurrently, the conflict can be detected, but is not
     recorded, since the row is deleted.  This means that further
     conflicts during the propagation of any subsequent realignment
     operations will not be detected, which can lead to divergence.

     Deletes should be externally serialized, or routed to one cluster
     only.  Alternatively, a separate row should be updated
     transactionally with such deletes and any inserts that follow them,
     so that conflicts can be tracked across row deletes.  This may
     require changes in applications.

   * Only two NDB Clusters in a circular 'active-active' configuration
     are currently supported when using 'NDB$EPOCH()' or
     'NDB$EPOCH_TRANS()' for conflict detection.

   * Tables having 'BLOB' or 'TEXT' columns
     are not currently supported with 'NDB$EPOCH()' or
     'NDB$EPOCH_TRANS()'.

NDB$EPOCH_TRANS()

'NDB$EPOCH_TRANS()' extends the 'NDB$EPOCH()' function.  Conflicts are
detected and handled in the same way using the 'primary wins all' rule
(see mysql-cluster-replication-ndb-epoch) but with the extra
condition that any other rows updated in the same transaction in which
the conflict occurred are also regarded as being in conflict.  In other
words, where 'NDB$EPOCH()' realigns individual conflicting rows on the
secondary, 'NDB$EPOCH_TRANS()' realigns conflicting transactions.

In addition, any transactions which are detectably dependent on a
conflicting transaction are also regarded as being in conflict, these
dependencies being determined by the contents of the secondary cluster's
binary log.  Since the binary log contains only data modification
operations (inserts, updates, and deletes), only overlapping data
modifications are used to determine dependencies between transactions.

'NDB$EPOCH_TRANS()' is subject to the same conditions and limitations as
'NDB$EPOCH()', and in addition requires that Version 2 binary log row
events are used ('--log-bin-use-v1-row-events' equal to 0), which adds a
storage overhead of 2 bytes per event in the binary log.  In addition,
all transaction IDs must be recorded in the secondary's binary log
('--ndb-log-transaction-id' option), which adds a further variable
overhead (up to 13 bytes per row).

See mysql-cluster-replication-ndb-epoch.

Status information

A server status variable 'Ndb_conflict_fn_max' provides a count of the
number of times that a row was not applied on the current SQL node due
to 'greatest timestamp wins' conflict resolution since the last time
that 'mysqld' was started.

The number of times that a row was not applied as the result of 'same
timestamp wins' conflict resolution on a given 'mysqld'.
since the last time it was restarted is given by the global status
variable 'Ndb_conflict_fn_old'.  In addition to incrementing
'Ndb_conflict_fn_old', the primary key of the row that was not used is
inserted into an _exceptions table_, as explained later in this section.

NDB$EPOCH2()

The 'NDB$EPOCH2()' function is similar to 'NDB$EPOCH()', except that
'NDB$EPOCH2()' provides for delete-delete handling with a circular
replication ('master-master') topology.  In this scenario, primary and
secondary roles are assigned to the two masters by setting the
'ndb_slave_conflict_role' system variable to the appropriate value on
each master (usually one each of 'PRIMARY', 'SECONDARY').  When this is
done, modifications made by the secondary are reflected by the primary
back to the secondary which then conditionally applies them.

NDB$EPOCH2_TRANS()

'NDB$EPOCH2_TRANS()' extends the 'NDB$EPOCH2()' function.  Conflicts are
detected and handled in the same way, and assigning primary and
secondary roles to the replicating clusters, but with the extra
condition that any other rows updated in the same transaction in which
the conflict occurred are also regarded as being in conflict.  That is,
'NDB$EPOCH2()' realigns individual conflicting rows on the secondary,
while 'NDB$EPOCH_TRANS()' realigns conflicting transactions.

Where 'NDB$EPOCH()' and 'NDB$EPOCH_TRANS()' use metadata that is
specified per row, per last modified epoch, to determine on the primary
whether an incoming replicated row change from the secondary is
concurrent with a locally committed change; concurrent changes are
regarded as conflicting, with subesequent exceptions table updates and
realignment of the secondary.  A problem arises when a row is deleted on
the primary so there is no longer any last-modified epoch available to
determine whether any replicated operations conflict, which means that
conflicting delete operationss are not detected.  This can result in
divergence, an example being a delete on one cluster which is concurrent
with a delete and insert on the other; this why delete operations can be
routed to only one cluster when using 'NDB$EPOCH()' and
'NDB$EPOCH_TRANS()'.

'NDB$EPOCH2()' bypasses the issue just described--storing information
about deleted rows on the PRIMARY--by ignoring any delete-delete
conflict, and by avoiding any potential resultant divergence as well.
This is accomplished by reflecting any operation successfully applied on
and replicated from the secondary back to the secondary.  On its return
to the secondary, it can be used to reapply an operation on the
secondary which was deleted by an operation originating from the
primary.

When using 'NDB$EPOCH2()', you should keep in mind that the secondary
applies the delete from the primary, removing the new row until it is
restored by a reflected operation.  In theory, the subsequent insert or
update on the secondary conflicts with the delete from the primary, but
in this case, we choose to ignore this and allow the secondary to 'win',
in the interest of preventing divergence between the clusters.  In other
words, after a delete, the primary does not detect conflicts, and
instead adopts the secondary's following changes immediately.  Because
of this, the secondary's state can revisit multiple previous committed
states as it progresses to a final (stable) state, and some of these may
be visible.

You should also be aware that reflecting all operations from the
secondary back to the primary increases the size of the primary's
logbinary log, as well as demands on bandwidth, CPU usage, and disk I/O.

Application of reflected operations on the secondary depends on the
state of the target row on the secondary.  Whether or not reflected
changes are applied on the secondary can be tracked by checking the
'Ndb_conflict_reflected_op_prepare_count' and
'Ndb_conflict_reflected_op_discard_count' status variables.  The number
of changes applied is simply the difference between these two values
(note that 'Ndb_conflict_reflected_op_prepare_count' is always greater
than or equal to 'Ndb_conflict_reflected_op_discard_count').

Events are applied if and only if both of the following conditions are
true:

   * The existence of the row--that is, whether or not it exists--is in
     accordance with the type of event.  For delete and update
     operations, the row must already exist; for insert operations, the
     row must _not_ exist.

   * The row was last modified by the primary.  It is possible that the
     modification was accomplished through the execution of a reflected
     operation.

If both of the conditions are not met, the reflected operation is
discarded by the secondary.

Conflict resolution exceptions table

To use the 'NDB$OLD()' conflict resolution function, it is also
necessary to create an exceptions table corresponding to each
'NDB' table for which this type of conflict resolution
is to be employed.  This is also true when using 'NDB$EPOCH()' or
'NDB$EPOCH_TRANS()'.  The name of this table is that of the table for
which conflict resolution is to be applied, with the string '$EX'
appended.  (For example, if the name of the original table is 'mytable',
the name of the corresponding exceptions table name should be
'mytable$EX'.)  The syntax for creating the exceptions table is as shown
here:

     CREATE TABLE ORIGINAL_TABLE$EX  (
         [NDB$]server_id INT UNSIGNED,
         [NDB$]master_server_id INT UNSIGNED,
         [NDB$]master_epoch BIGINT UNSIGNED,
         [NDB$]count INT UNSIGNED,

         [NDB$OP_TYPE ENUM('WRITE_ROW','UPDATE_ROW', 'DELETE_ROW',
           'REFRESH_ROW', 'READ_ROW') NOT NULL,]
         [NDB$CFT_CAUSE ENUM('ROW_DOES_NOT_EXIST', 'ROW_ALREADY_EXISTS',
           'DATA_IN_CONFLICT', 'TRANS_IN_CONFLICT') NOT NULL,]
         [NDB$ORIG_TRANSID BIGINT UNSIGNED NOT NULL,]

         ORIGINAL_TABLE_PK_COLUMNS,

         [ORIG_TABLE_COLUMN|ORIG_TABLE_COLUMN$OLD|ORIG_TABLE_COLUMN$NEW,]

         [ADDITIONAL_COLUMNS,]

         PRIMARY KEY([NDB$]server_id, [NDB$]master_server_id, [NDB$]master_epoch, [NDB$]count)
     ) ENGINE=NDB;

The first four columns are required.  The names of the first four
columns and the columns matching the original table's primary key
columns are not critical; however, we suggest for reasons of clarity and
consistency, that you use the names shown here for the 'server_id',
'master_server_id', 'master_epoch', and 'count' columns, and that you
use the same names as in the original table for the columns matching
those in the original table's primary key.

If the exceptions table uses one or more of the optional columns
'NDB$OP_TYPE', 'NDB$CFT_CAUSE', or 'NDB$ORIG_TRANSID' discussed later in
this section, then each of the required columns must also be named using
the prefix 'NDB$'.  If desired, you can use the 'NDB$' prefix to name
the required columns even if you do not define any optional columns, but
in this case, all four of the required columns must be named using the
prefix.

Following these columns, the columns making up the original table's
primary key should be copied in the order in which they are used to
define the primary key of the original table.  The data types for the
columns duplicating the primary key columns of the original table should
be the same as (or larger than) those of the original columns.  A subset
of the primary key columns may be used.

Regardless of the NDB Cluster version employed, the exceptions table
must use the 'NDB' storage engine.  (An example
that uses 'NDB$OLD()' with an exceptions table is shown later in this
section.)

Additional columns may optionally be defined following the copied
primary key columns, but not before any of them; any such extra columns
cannot be 'NOT NULL'.  NDB Cluster supports three additional, predefined
optional columns 'NDB$OP_TYPE', 'NDB$CFT_CAUSE', and 'NDB$ORIG_TRANSID',
which are described in the next few paragraphs.

'NDB$OP_TYPE': This column can be used to obtain the type of operation
causing the conflict.  If you use this column, define it as shown here:

     NDB$OP_TYPE ENUM('WRITE_ROW', 'UPDATE_ROW', 'DELETE_ROW',
         'REFRESH_ROW', 'READ_ROW') NOT NULL

The 'WRITE_ROW', 'UPDATE_ROW', and 'DELETE_ROW' operation types
represent user-initiated operations.  'REFRESH_ROW' operations are
operations generated by conflict resolution in compensating transactions
sent back to the originating cluster from the cluster that detected the
conflict.  'READ_ROW' operations are user-initiated read tracking
operations defined with exclusive row locks.

'NDB$CFT_CAUSE': You can define an optional column 'NDB$CFT_CAUSE' which
provides the cause of the registered conflict.  This column, if used, is
defined as shown here:

     NDB$CFT_CAUSE ENUM('ROW_DOES_NOT_EXIST', 'ROW_ALREADY_EXISTS',
         'DATA_IN_CONFLICT', 'TRANS_IN_CONFLICT') NOT NULL

'ROW_DOES_NOT_EXIST' can be reported as the cause for 'UPDATE_ROW' and
'WRITE_ROW' operations; 'ROW_ALREADY_EXISTS' can be reported for
'WRITE_ROW' events.  'DATA_IN_CONFLICT' is reported when a row-based
conflict function detects a conflict; 'TRANS_IN_CONFLICT' is reported
when a transactional conflict function rejects all of the operations
belonging to a complete transaction.

'NDB$ORIG_TRANSID': The 'NDB$ORIG_TRANSID' column, if used, contains the
ID of the originating transaction.  This column should be defined as
follows:

     NDB$ORIG_TRANSID BIGINT UNSIGNED NOT NULL

'NDB$ORIG_TRANSID' is a 64-bit value generated by 'NDB'.  This value can
be used to correlate multiple exceptions table entries belonging to the
same conflicting transaction from the same or different exceptions
tables.

Additional reference columns which are not part of the original table's
primary key can be named 'COLNAME$OLD' or 'COLNAME$NEW'.  'COLNAME$OLD'
references old values in update and delete operations--that is,
operations containing 'DELETE_ROW' events.  'COLNAME$NEW' can be used to
reference new values in insert and update operations--in other words,
operations using 'WRITE_ROW' events, 'UPDATE_ROW' events, or both types
of events.  Where a conflicting operation does not supply a value for a
given non-primary-key reference column, the exceptions table row
contains either 'NULL', or a defined default value for that column.

*Important*:

The 'mysql.ndb_replication' table is read when a data table is set up
for replication, so the row corresponding to a table to be replicated
must be inserted into 'mysql.ndb_replication' _before_ the table to be
replicated is created.

*Examples*

The following examples assume that you have already a working NDB
Cluster replication setup, as described in
mysql-cluster-replication-preparation, and
mysql-cluster-replication-starting.

NDB$MAX() example

Suppose you wish to enable 'greatest timestamp wins' conflict resolution
on table 'test.t1', using column 'mycol' as the 'timestamp'.  This can
be done using the following steps:

  1. Make sure that you have started the master 'mysqld'.
     with '--ndb-log-update-as-write=OFF'.

  2. On the master, perform this 'INSERT' statement:

          INSERT INTO mysql.ndb_replication
              VALUES ('test', 't1', 0, NULL, 'NDB$MAX(mycol)');

     Inserting a 0 into the 'server_id' indicates that all SQL nodes
     accessing this table should use conflict resolution.  If you want
     to use conflict resolution on a specific 'mysqld'.
     only, use the actual server ID.

     Inserting 'NULL' into the 'binlog_type' column has the same effect
     as inserting 0 ('NBT_DEFAULT'); the server default is used.

  3. Create the 'test.t1' table:

          CREATE TABLE test.t1 (
              COLUMNS
              mycol INT UNSIGNED,
              COLUMNS
          ) ENGINE=NDB;

     Now, when updates are done on this table, conflict resolution is
     applied, and the version of the row having the greatest value for
     'mycol' is written to the slave.

*Note*:

Other 'binlog_type' options--such as 'NBT_UPDATED_ONLY_USE_UPDATE'
should be used to control logging on the master using the
'ndb_replication' table rather than by using command-line options.

NDB$OLD() example

Suppose an 'NDB' table such as the one defined
here is being replicated, and you wish to enable 'same timestamp wins'
conflict resolution for updates to this table:

     CREATE TABLE test.t2  (
         a INT UNSIGNED NOT NULL,
         b CHAR(25) NOT NULL,
         COLUMNS,
         mycol INT UNSIGNED NOT NULL,
         COLUMNS,
         PRIMARY KEY pk (a, b)
     )   ENGINE=NDB;

The following steps are required, in the order shown:

  1. First--and _prior_ to creating 'test.t2'--you must insert a row
     into the 'mysql.ndb_replication' table, as shown here:

          INSERT INTO mysql.ndb_replication
              VALUES ('test', 't2', 0, NULL, 'NDB$OLD(mycol)');

     Possible values for the 'binlog_type' column are shown earlier in
     this section.  The value ''NDB$OLD(mycol)'' should be inserted into
     the 'conflict_fn' column.

  2. Create an appropriate exceptions table for 'test.t2'.  The table
     creation statement shown here includes all required columns; any
     additional columns must be declared following these columns, and
     before the definition of the table's primary key.

          CREATE TABLE test.t2$EX  (
              server_id INT UNSIGNED,
              master_server_id INT UNSIGNED,
              master_epoch BIGINT UNSIGNED,
              count INT UNSIGNED,
              a INT UNSIGNED NOT NULL,
              b CHAR(25) NOT NULL,

              [ADDITIONAL_COLUMNS,]

              PRIMARY KEY(server_id, master_server_id, master_epoch, count)
          )   ENGINE=NDB;

     We can include additional columns for information about the type,
     cause, and originating transaction ID for a given conflict.  We are
     also not required to supply matching columns for all primary key
     columns in the original table.  This means you can create the
     exceptions table like this:

          CREATE TABLE test.t2$EX  (
              NDB$server_id INT UNSIGNED,
              NDB$master_server_id INT UNSIGNED,
              NDB$master_epoch BIGINT UNSIGNED,
              NDB$count INT UNSIGNED,
              a INT UNSIGNED NOT NULL,

              NDB$OP_TYPE ENUM('WRITE_ROW','UPDATE_ROW', 'DELETE_ROW',
                'REFRESH_ROW', 'READ_ROW') NOT NULL,
              NDB$CFT_CAUSE ENUM('ROW_DOES_NOT_EXIST', 'ROW_ALREADY_EXISTS',
                'DATA_IN_CONFLICT', 'TRANS_IN_CONFLICT') NOT NULL,
              NDB$ORIG_TRANSID BIGINT UNSIGNED NOT NULL,

              [ADDITIONAL_COLUMNS,]

              PRIMARY KEY(NDB$server_id, NDB$master_server_id, NDB$master_epoch, NDB$count)
          )   ENGINE=NDB;

     *Note*:

     The 'NDB$' prefix is required for the four required columns since
     we included at least one of the columns 'NDB$OP_TYPE',
     'NDB$CFT_CAUSE', or 'NDB$ORIG_TRANSID' in the table definition.

  3. Create the table 'test.t2' as shown previously.

These steps must be followed for every table for which you wish to
perform conflict resolution using 'NDB$OLD()'.  For each such table,
there must be a corresponding row in 'mysql.ndb_replication', and there
must be an exceptions table in the same database as the table being
replicated.

Read conflict detection and resolution

NDB Cluster also supports tracking of read operations, which makes it
possible in circular replication setups to manage conflicts between
reads of a given row in one cluster and updates or deletes of the same
row in another.  This example uses 'employee' and 'department' tables to
model a scenario in which an employee is moved from one department to
another on the master cluster (which we refer to hereafter as cluster
_A_) while the slave cluster (hereafter _B_) updates the employee count
of the employee's former department in an interleaved transaction.

The data tables have been created using the following SQL statements:

     # Employee table
     CREATE TABLE employee (
         id INT PRIMARY KEY,
         name VARCHAR(2000),
         dept INT NOT NULL
     )   ENGINE=NDB;

     # Department table
     CREATE TABLE department (
         id INT PRIMARY KEY,
         name VARCHAR(2000),
         members INT
     )   ENGINE=NDB;

The contents of the two tables include the rows shown in the (partial)
output of the following 'SELECT' statements:

     mysql> SELECT id, name, dept FROM employee;
     +---------------+------+
     | id   | name   | dept |
     +------+--------+------+
     ...
     | 998  |  Mike  | 3    |
     | 999  |  Joe   | 3    |
     | 1000 |  Mary  | 3    |
     ...
     +------+--------+------+

     mysql> SELECT id, name, members FROM department;
     +-----+-------------+---------+
     | id  | name        | members |
     +-----+-------------+---------+
     ...
     | 3   | Old project | 24      |
     ...
     +-----+-------------+---------+

We assume that we are already using an exceptions table that includes
the four required columns (and these are used for this table's primary
key), the optional columns for operation type and cause, and the
original table's primary key column, created using the SQL statement
shown here:

     CREATE TABLE employee$EX  (
         NDB$server_id INT UNSIGNED,
         NDB$master_server_id INT UNSIGNED,
         NDB$master_epoch BIGINT UNSIGNED,
         NDB$count INT UNSIGNED,

         NDB$OP_TYPE ENUM( 'WRITE_ROW','UPDATE_ROW', 'DELETE_ROW',
                           'REFRESH_ROW','READ_ROW') NOT NULL,
         NDB$CFT_CAUSE ENUM( 'ROW_DOES_NOT_EXIST',
                             'ROW_ALREADY_EXISTS',
                             'DATA_IN_CONFLICT',
                             'TRANS_IN_CONFLICT') NOT NULL,

         id INT NOT NULL,

         PRIMARY KEY(NDB$server_id, NDB$master_server_id, NDB$master_epoch, NDB$count)
     )   ENGINE=NDB;

Suppose there occur the two simultaneous transactions on the two
clusters.  On cluster _A_, we create a new department, then move
employee number 999 into that department, using the following SQL
statements:

     BEGIN.;
       INSERT. INTO department VALUES (4, "New project", 1);
       _UPDATE employee SET dept = 4 WHERE id = 999;_
     COMMIT;

At the same time, on cluster _B_, another transaction reads from
'employee', as shown here:

     BEGIN;
       _SELECT name FROM employee WHERE id = 999;_
       UPDATE department SET members = members - 1  WHERE id = 3;
     commit;

The conflicting transactions are not normally detected by the conflict
resolution mechanism, since the conflict is between a read ('SELECT')
and an update operation.  You can circumvent this issue by executing
'SET'. 'ndb_log_exclusive_reads' '= 1' on the slave
cluster.  Acquiring exclusive read locks in this way causes any rows
read on the master to be flagged as needing conflict resolution on the
slave cluster.  If we enable exclusive reads in this way prior to the
logging of these transactions, the read on cluster _B_ is tracked and
sent to cluster _A_ for resolution; the conflict on the employee row
will be detected and the transaction on cluster _B_ is aborted.

The conflict is registered in the exceptions table (on cluster _A_) as a
'READ_ROW' operation (see
mysql-cluster-replication-exceptions-table, for a description of
operation types), as shown here:

     mysql> SELECT id, NDB$OP_TYPE, NDB$CFT_CAUSE FROM employee$EX;
     +-------+-------------+-------------------+
     | id    | NDB$OP_TYPE | NDB$CFT_CAUSE     |
     +-------+-------------+-------------------+
     ...
     | 999   | READ_ROW    | TRANS_IN_CONFLICT |
     +-------+-------------+-------------------+

Any existing rows found in the read operation are flagged.  This means
that multiple rows resulting from the same conflict may be logged in the
exception table, as shown by examining the effects a conflict between an
update on cluster _A_ and a read of multiple rows on cluster _B_ from
the same table in simultaneous transactions.  The transaction executed
on cluster _A_ is shown here:

     BEGIN;
       INSERT INTO department VALUES (4, "New project", 0);
       _UPDATE employee SET dept = 4 WHERE dept = 3;_
       SELECT COUNT(*) INTO @count FROM employee WHERE dept = 4;
       UPDATE department SET members = @count WHERE id = 4;
     COMMIT;

Concurrently a transaction containing the statements shown here runs on
cluster _B_:

     SET ndb_log_exclusive_reads = 1;  # Must be set if not already enabled
     ...
     BEGIN;
       _SELECT COUNT(*) INTO @count FROM employee WHERE dept = 3 FOR UPDATE;_
       UPDATE department SET members = @count WHERE id = 3;
     COMMIT;

In this case, all three rows matching the 'WHERE' condition in the
second transaction's 'SELECT' are read, and are thus flagged in the
exceptions table, as shown here:

     mysql> SELECT id, NDB$OP_TYPE, NDB$CFT_CAUSE FROM employee$EX;
     +-------+-------------+-------------------+
     | id    | NDB$OP_TYPE | NDB$CFT_CAUSE     |
     +-------+-------------+-------------------+
     ...
     | 998   | READ_ROW    | TRANS_IN_CONFLICT |
     | 999   | READ_ROW    | TRANS_IN_CONFLICT |
     | 1000  | READ_ROW    | TRANS_IN_CONFLICT |
     ...
     +-------+-------------+-------------------+

Read tracking is performed on the basis of existing rows only.  A read
based on a given condition track conflicts only of any rows that are
_found_ and not of any rows that are inserted in an interleaved
transaction.  This is similar to how exclusive row locking is performed
in a single instance of NDB Cluster.

21.7 NDB Cluster Release Notes
==============================

Changes in NDB Cluster releases are documented separately from this
reference manual; you can find release notes for the changes in each NDB
Cluster 7.5 release at NDB 7.5 Release Notes
(http://dev.mysql.com/doc/relnotes/mysql-cluster/7.5/en/), and for each
NDB Cluster 7.6 release at NDB 7.6 Release Notes
(http://dev.mysql.com/doc/relnotes/mysql-cluster/7.6/en/).

You can obtain release notes for older versions of NDB Cluster from NDB
Cluster Release Notes
(http://dev.mysql.com/doc/index-cluster.html#cluster-relnotes).

22 Partitioning
***************

This chapter discusses MySQL's implementation of _user-defined
partitioning_.

*Note*:

As of MySQL 5.7.17, the generic partitioning handler in the MySQL server
is deprecated, and is removed in MySQL 8.0, when the storage engine used
for a given table is expected to provide its own ('native') partitioning
handler.  Currently, only the 'InnoDB' and
'NDB' storage engines do this.

Use of tables with nonnative partitioning results in an
'ER_WARN_DEPRECATED_SYNTAX' warning.  In MySQL 5.7.17 through 5.7.20,
the server automatically performs a check at startup to identify tables
that use nonnative partitioning; for any that are found, the server
writes a message to its error log.  To disable this check, use the
'--disable-partition-engine-check' option.  In MySQL 5.7.21 and later,
this check is _not_ performed; in these versions, you must start the
server with '--disable-partition-engine-check=false', if you wish for
the server to check for tables using the generic partitioning handler
(Bug #85830, Bug #25846957).

To prepare for migration to MySQL 8.0, any table with nonnative
partitioning should be changed to use an engine that provides native
partitioning, or be made nonpartitioned.  For example, to change a table
to 'InnoDB', execute this statement:

     ALTER TABLE TABLE_NAME ENGINE = INNODB;

You can determine whether your MySQL Server supports partitioning by
checking the output of the 'SHOW PLUGINS'.
statement, like this:

     mysql> SHOW PLUGINS;
     +------------+----------+----------------+---------+---------+
     | Name       | Status   | Type           | Library | License |
     +------------+----------+----------------+---------+---------+
     | binlog     | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     *| partition  | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |*
     | ARCHIVE    | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     | BLACKHOLE  | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     | CSV        | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     | FEDERATED  | DISABLED | STORAGE ENGINE | NULL    | GPL     |
     | MEMORY     | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     | InnoDB     | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     | MRG_MYISAM | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     | MyISAM     | ACTIVE   | STORAGE ENGINE | NULL    | GPL     |
     | ndbcluster | DISABLED | STORAGE ENGINE | NULL    | GPL     |
     +------------+----------+----------------+---------+---------+
     11 rows in set (0.00 sec)

You can also check the 'INFORMATION_SCHEMA.PLUGINS'
table with a query similar to this one:

     mysql> SELECT
         ->     PLUGIN_NAME as Name,
         ->     PLUGIN_VERSION as Version,
         ->     PLUGIN_STATUS as Status
         -> FROM INFORMATION_SCHEMA.PLUGINS
         -> WHERE PLUGIN_TYPE='STORAGE ENGINE';
     +--------------------+---------+--------+
     | Name               | Version | Status |
     +--------------------+---------+--------+
     | binlog             | 1.0     | ACTIVE |
     | CSV                | 1.0     | ACTIVE |
     | MEMORY             | 1.0     | ACTIVE |
     | MRG_MYISAM         | 1.0     | ACTIVE |
     | MyISAM             | 1.0     | ACTIVE |
     | PERFORMANCE_SCHEMA | 0.1     | ACTIVE |
     | BLACKHOLE          | 1.0     | ACTIVE |
     | ARCHIVE            | 3.0     | ACTIVE |
     | InnoDB             | 5.7     | ACTIVE |
     *| partition          | 1.0     | ACTIVE |*
     +--------------------+---------+--------+
     10 rows in set (0.00 sec)

In either case, if you do not see the 'partition' plugin listed with the
value 'ACTIVE' for the 'Status' column in the output (shown in bold text
in each of the examples just given), then your version of MySQL was not
built with partitioning support.

MySQL 5.7 Community binaries provided by Oracle include partitioning
support.  For information about partitioning support offered in MySQL
Enterprise Edition binaries, see mysql-enterprise.

To enable partitioning if you are compiling MySQL 5.7 from source, the
build must be configured with the '-DWITH_PARTITION_STORAGE_ENGINE'
option.  For more information, see source-installation.

If your MySQL binary is built with partitioning support, nothing further
needs to be done to enable it (for example, no special entries are
required in your 'my.cnf' file).

If you want to disable partitioning support, you can start the MySQL
Server with the '--skip-partition' option.  When partitioning support is
disabled, you can see any existing partitioned tables and drop them
(although doing this is not advised), but you cannot otherwise
manipulate them or access their data.

See partitioning-overview, for an introduction to partitioning
and partitioning concepts.

MySQL supports several types of partitioning as well as subpartitioning;
see partitioning-types, and partitioning-subpartitions.

See partitioning-management, covers methods of adding, removing, and
altering partitions in existing partitioned tables.

See partitioning-maintenance, discusses table maintenance commands
for use with partitioned tables.

The 'PARTITIONS' table in the
'INFORMATION_SCHEMA' database provides information about partitions and
partitioned tables.  See partitions-table, for more information;
for some examples of queries against this table, see
partitioning-handling-nulls.

For known issues with partitioning in MySQL 5.7, see
partitioning-limitations.

You may also find the following resources to be useful when working with
partitioned tables.

Additional Resources

Other sources of information about user-defined partitioning in MySQL
include the following:

   * MySQL Partitioning Forum (http://forums.mysql.com/list.php?106)

     This is the official discussion forum for those interested in or
     experimenting with MySQL Partitioning technology.  It features
     announcements and updates from MySQL developers and others.  It is
     monitored by members of the Partitioning Development and
     Documentation Teams.

   * Mikael Ronstro"m's Blog (http://mikaelronstrom.blogspot.com/)

     MySQL Partitioning Architect and Lead Developer Mikael Ronstro"m
     frequently posts articles here concerning his work with MySQL
     Partitioning and NDB Cluster.

   * PlanetMySQL (http://www.planetmysql.org/)

     A MySQL news site featuring MySQL-related blogs, which should be of
     interest to anyone using my MySQL. We encourage you to check here
     for links to blogs kept by those working with MySQL Partitioning,
     or to have your own blog added to those covered.

MySQL 5.7 binaries are available from
<http://dev.mysql.com/downloads/mysql/5.7.html>.  However, for the
latest partitioning bugfixes and feature additions, you can obtain the
source from our GitHub repository.  To enable partitioning, the build
must be configured with the '-DWITH_PARTITION_STORAGE_ENGINE' option.
For more information about building MySQL, see
source-installation.  If you have problems compiling a
partitioning-enabled MySQL 5.7 build, check the MySQL Partitioning Forum
(http://forums.mysql.com/list.php?106) and ask for assistance there if
you do not find a solution to your problem already posted.

22.1 Overview of Partitioning in MySQL
======================================

This section provides a conceptual overview of partitioning in MySQL
5.7.

For information on partitioning restrictions and feature limitations,
see partitioning-limitations.

The SQL standard does not provide much in the way of guidance regarding
the physical aspects of data storage.  The SQL language itself is
intended to work independently of any data structures or media
underlying the schemas, tables, rows, or columns with which it works.
Nonetheless, most advanced database management systems have evolved some
means of determining the physical location to be used for storing
specific pieces of data in terms of the file system, hardware or even
both.  In MySQL, the 'InnoDB' storage engine has long supported the
notion of a tablespace, and the MySQL Server, even prior to the
introduction of partitioning, could be configured to employ different
physical directories for storing different databases (see
symbolic-links, for an explanation of how this is done).

_Partitioning_ takes this notion a step further, by enabling you to
distribute portions of individual tables across a file system according
to rules which you can set largely as needed.  In effect, different
portions of a table are stored as separate tables in different
locations.  The user-selected rule by which the division of data is
accomplished is known as a _partitioning function_, which in MySQL can
be the modulus, simple matching against a set of ranges or value lists,
an internal hashing function, or a linear hashing function.  The
function is selected according to the partitioning type specified by the
user, and takes as its parameter the value of a user-supplied
expression.  This expression can be a column value, a function acting on
one or more column values, or a set of one or more column values,
depending on the type of partitioning that is used.

In the case of 'RANGE', 'LIST', and ['LINEAR'] 'HASH' partitioning, the
value of the partitioning column is passed to the partitioning function,
which returns an integer value representing the number of the partition
in which that particular record should be stored.  This function must be
nonconstant and nonrandom.  It may not contain any queries, but may use
an SQL expression that is valid in MySQL, as long as that expression
returns either 'NULL' or an integer INTVAL such that

     -MAXVALUE <= INTVAL <= MAXVALUE

('MAXVALUE' is used to represent the least upper bound for the type of
integer in question.  '-MAXVALUE' represents the greatest lower bound.)

For ['LINEAR'] 'KEY', 'RANGE COLUMNS', and 'LIST COLUMNS' partitioning,
the partitioning expression consists of a list of one or more columns.

For ['LINEAR'] 'KEY' partitioning, the partitioning function is supplied
by MySQL.

For more information about permitted partitioning column types and
partitioning functions, see partitioning-types, as well as
create-table, which provides partitioning syntax descriptions and
additional examples.  For information about restrictions on partitioning
functions, see partitioning-limitations-functions.

This is known as _horizontal partitioning_--that is, different rows of a
table may be assigned to different physical partitions.  MySQL 5.7 does
not support _vertical partitioning_, in which different columns of a
table are assigned to different physical partitions.  There are no plans
at this time to introduce vertical partitioning into MySQL.

For information about determining whether your MySQL Server binary
supports user-defined partitioning, see partitioning.

For creating partitioned tables, you can use most storage engines that
are supported by your MySQL server; the MySQL partitioning engine runs
in a separate layer and can interact with any of these.  In MySQL 5.7,
all partitions of the same partitioned table must use the same storage
engine; for example, you cannot use 'MyISAM' for one partition and
'InnoDB' for another.  However, there is nothing preventing you from
using different storage engines for different partitioned tables on the
same MySQL server or even in the same database.

MySQL partitioning cannot be used with the 'MERGE', 'CSV', or
'FEDERATED' storage engines.

Partitioning by 'KEY' or 'LINEAR KEY' is possible with 'NDB',
but other types of user-defined partitioning are not
supported for tables using this storage engine.  In addition, an
'NDB' table that employs user-defined partitioning must
have an explicit primary key, and any columns referenced in the table's
partitioning expression must be part of the primary key.  However, if no
columns are listed in the 'PARTITION BY KEY' or 'PARTITION BY LINEAR
KEY' clause of the 'CREATE TABLE' or 'ALTER TABLE'
statement used to create or
modify a user-partitioned 'NDB' table, then the
table is not required to have an explicit primary key.  For more
information, see mysql-cluster-limitations-syntax.

To employ a particular storage engine for a partitioned table, it is
necessary only to use the '[STORAGE] ENGINE' option just as you would
for a nonpartitioned table.  However, you should keep in mind that
'[STORAGE] ENGINE' (and other table options) need to be listed _before_
any partitioning options are used in a 'CREATE TABLE'
statement.  This example shows how to create a table that
is partitioned by hash into 6 partitions and which uses the 'InnoDB'
storage engine:

     CREATE TABLE ti (id INT, amount DECIMAL(7,2), tr_date DATE)
         ENGINE=INNODB
         PARTITION BY HASH( MONTH(tr_date) )
         PARTITIONS 6;

Each 'PARTITION' clause can include a '[STORAGE] ENGINE' option, but in
MySQL 5.7 this has no effect.

*Important*:

Partitioning applies to all data and indexes of a table; you cannot
partition only the data and not the indexes, or vice versa, nor can you
partition only a portion of the table.

Data and indexes for each partition can be assigned to a specific
directory using the 'DATA DIRECTORY' and 'INDEX DIRECTORY' options for
the 'PARTITION' clause of the 'CREATE TABLE'.
statement used to create the partitioned table.

'DATA DIRECTORY' and 'INDEX DIRECTORY' are not supported for individual
partitions or subpartitions of 'MyISAM' tables on Windows.  They are
supported for individual partitions and subpartitions of 'InnoDB' tables
(as on all platforms).

All columns used in the table's partitioning expression must be part of
every unique key that the table may have, including any primary key.
This means that a table such as this one, created by the following SQL
statement, cannot be partitioned:

     CREATE TABLE tnp (
         id INT NOT NULL AUTO_INCREMENT,
         ref BIGINT NOT NULL,
         name VARCHAR(255),
         PRIMARY KEY pk (id),
         UNIQUE KEY uk (name)
     );

Because the keys 'pk' and 'uk' have no columns in common, there are no
columns available for use in a partitioning expression.  Possible
workarounds in this situation include adding the 'name' column to the
table's primary key, adding the 'id' column to 'uk', or simply removing
the unique key altogether.  See
partitioning-limitations-partitioning-keys-unique-keys, for more
information.

In addition, 'MAX_ROWS' and 'MIN_ROWS' can be used to determine the
maximum and minimum numbers of rows, respectively, that can be stored in
each partition.  See partitioning-management, for more
information on these options.

The 'MAX_ROWS' option can also be useful for creating NDB Cluster tables
with extra partitions, thus allowing for greater storage of hash
indexes.  See the documentation for the 'DataMemory' data node
configuration parameter, as well as mysql-cluster-nodes-groups,
for more information.

Some advantages of partitioning are listed here:

   * Partitioning makes it possible to store more data in one table than
     can be held on a single disk or file system partition.

   * Data that loses its usefulness can often be easily removed from a
     partitioned table by dropping the partition (or partitions)
     containing only that data.  Conversely, the process of adding new
     data can in some cases be greatly facilitated by adding one or more
     new partitions for storing specifically that data.

   * Some queries can be greatly optimized in virtue of the fact that
     data satisfying a given 'WHERE' clause can be stored only on one or
     more partitions, which automatically excludes any remaining
     partitions from the search.  Because partitions can be altered
     after a partitioned table has been created, you can reorganize your
     data to enhance frequent queries that may not have been often used
     when the partitioning scheme was first set up.  This ability to
     exclude non-matching partitions (and thus any rows they contain) is
     often referred to as _partition pruning_.  For more information,
     see partitioning-pruning.

     In addition, MySQL 5.7 supports explicit partition selection for
     queries.  For example, see 'SELECT * FROM t PARTITION (p0,p1) WHERE c < 5'
     selects only those rows in partitions 'p0'
     and 'p1' that match the 'WHERE' condition.  In this case, MySQL
     does not check any other partitions of table 't'; this can greatly
     speed up queries when you already know which partition or
     partitions you wish to examine.  Partition selection is also
     supported for the data modification statements 'DELETE',
     see 'INSERT', 'REPLACE',
     'UPDATE', and 'LOAD DATA', 'LOAD XML'.
     See the descriptions of these statements for more
     information and examples.

Other benefits usually associated with partitioning include those in the
following list.  These features are not currently implemented in MySQL
Partitioning, but are high on our list of priorities.

   * Queries involving aggregate functions such as 'SUM()' and 'COUNT()'
     can easily be parallelized.  A simple example of such a query might
     be 'SELECT salesperson_id, COUNT(orders) as order_total FROM sales
     GROUP BY salesperson_id;'.  By 'parallelized,' we mean that the
     query can be run simultaneously on each partition, and the final
     result obtained merely by summing the results obtained for all
     partitions.

   * Achieving greater query throughput in virtue of spreading data
     seeks over multiple disks.

Be sure to check this section and chapter frequently for updates as
MySQL Partitioning development continues.

22.2 Partitioning Types
=======================

This section discusses the types of partitioning which are available in
MySQL 5.7.  These include the types listed here:

   * RANGE partitioning

     This type of partitioning assigns rows to partitions based on
     column values falling within a given range.  See
     partitioning-range.  For information about an extension to this
     type, 'RANGE COLUMNS', see partitioning-columns-range.

   * LIST partitioning

     Similar to partitioning by 'RANGE', except that the partition is
     selected based on columns matching one of a set of discrete values.
     See partitioning-list.  For information about an extension
     to this type, 'LIST COLUMNS', see
     partitioning-columns-list.

   * HASH partitioning

     With this type of partitioning, a partition is selected based on
     the value returned by a user-defined expression that operates on
     column values in rows to be inserted into the table.  The function
     may consist of any expression valid in MySQL that yields a
     nonnegative integer value.  An extension to this type, 'LINEAR
     HASH', is also available.  See partitioning-hash.

   * KEY partitioning

     This type of partitioning is similar to partitioning by 'HASH',
     except that only one or more columns to be evaluated are supplied,
     and the MySQL server provides its own hashing function.  These
     columns can contain other than integer values, since the hashing
     function supplied by MySQL guarantees an integer result regardless
     of the column data type.  An extension to this type, 'LINEAR KEY',
     is also available.  See partitioning-key.

A very common use of database partitioning is to segregate data by date.
Some database systems support explicit date partitioning, which MySQL
does not implement in 5.7.  However, it is not difficult in MySQL to
create partitioning schemes based on 'DATE',
'TIME', or 'DATETIME' columns, or based on
expressions making use of such columns.

When partitioning by 'KEY' or 'LINEAR KEY', you can use a 'DATE',
see 'TIME', or 'DATETIME' column as
the partitioning column without performing any modification of the
column value.  For example, this table creation statement is perfectly
valid in MySQL:

     CREATE TABLE members (
         firstname VARCHAR(25) NOT NULL,
         lastname VARCHAR(25) NOT NULL,
         username VARCHAR(16) NOT NULL,
         email VARCHAR(35),
         joined DATE NOT NULL
     )
     PARTITION BY KEY(joined)
     PARTITIONS 6;

In MySQL 5.7, it is also possible to use a 'DATE' or
'DATETIME' column as the partitioning column using
'RANGE COLUMNS' and 'LIST COLUMNS' partitioning.

MySQL's other partitioning types, however, require a partitioning
expression that yields an integer value or 'NULL'.  If you wish to use
date-based partitioning by 'RANGE', 'LIST', 'HASH', or 'LINEAR HASH',
you can simply employ a function that operates on a 'DATE',
see 'TIME', or 'DATETIME' column and
returns such a value, as shown here:

     CREATE TABLE members (
         firstname VARCHAR(25) NOT NULL,
         lastname VARCHAR(25) NOT NULL,
         username VARCHAR(16) NOT NULL,
         email VARCHAR(35),
         joined DATE NOT NULL
     )
     PARTITION BY RANGE( YEAR(joined) ) (
         PARTITION p0 VALUES LESS THAN (1960),
         PARTITION p1 VALUES LESS THAN (1970),
         PARTITION p2 VALUES LESS THAN (1980),
         PARTITION p3 VALUES LESS THAN (1990),
         PARTITION p4 VALUES LESS THAN MAXVALUE
     );

Additional examples of partitioning using dates may be found in the
following sections of this chapter:

   * partitioning-range

   * partitioning-hash

   * partitioning-linear-hash

For more complex examples of date-based partitioning, see the following
sections:

   * partitioning-pruning

   * partitioning-subpartitions

MySQL partitioning is optimized for use with the 'TO_DAYS()', 'YEAR()',
and 'TO_SECONDS()' functions.  However, you can use other date and time
functions that return an integer or 'NULL', such as 'WEEKDAY()',
'DAYOFYEAR()', or 'MONTH()'.  See date-and-time-functions, for
more information about such functions.

It is important to remember--regardless of the type of partitioning that
you use--that partitions are always numbered automatically and in
sequence when created, starting with '0'.  When a new row is inserted
into a partitioned table, it is these partition numbers that are used in
identifying the correct partition.  For example, if your table uses 4
partitions, these partitions are numbered '0', '1', '2', and '3'.  For
the 'RANGE' and 'LIST' partitioning types, it is necessary to ensure
that there is a partition defined for each partition number.  For 'HASH'
partitioning, the user-supplied expression must evaluate to an integer
value greater than '0'.  For 'KEY' partitioning, this issue is taken
care of automatically by the hashing function which the MySQL server
employs internally.

Names of partitions generally follow the rules governing other MySQL
identifiers, such as those for tables and databases.  However, you
should note that partition names are not case-sensitive.  For example,
the following 'CREATE TABLE' statement fails as
shown:

     mysql> CREATE TABLE t2 (val INT)
         -> PARTITION BY LIST(val)(
         ->     PARTITION mypart VALUES IN (1,3,5),
         ->     PARTITION MyPart VALUES IN (2,4,6)
         -> );
     ERROR 1488 (HY000): Duplicate partition name mypart

Failure occurs because MySQL sees no difference between the partition
names 'mypart' and 'MyPart'.

When you specify the number of partitions for the table, this must be
expressed as a positive, nonzero integer literal with no leading zeros,
and may not be an expression such as '0.8E+01' or '6-2', even if it
evaluates to an integer value.  Decimal fractions are not permitted.

In the sections that follow, we do not necessarily provide all possible
forms for the syntax that can be used for creating each partition type;
this information may be found in create-table.

22.2.1 RANGE Partitioning
-------------------------

A table that is partitioned by range is partitioned in such a way that
each partition contains rows for which the partitioning expression value
lies within a given range.  Ranges should be contiguous but not
overlapping, and are defined using the 'VALUES LESS THAN' operator.  For
the next few examples, suppose that you are creating a table such as the
following to hold personnel records for a chain of 20 video stores,
numbered 1 through 20:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT NOT NULL,
         store_id INT NOT NULL
     );

*Note*:

The 'employees' table used here has no primary or unique keys.  While
the examples work as shown for purposes of the present discussion, you
should keep in mind that tables are extremely likely in practice to have
primary keys, unique keys, or both, and that allowable choices for
partitioning columns depend on the columns used for these keys, if any
are present.  For a discussion of these issues, see
partitioning-limitations-partitioning-keys-unique-keys.

This table can be partitioned by range in a number of ways, depending on
your needs.  One way would be to use the 'store_id' column.  For
instance, you might decide to partition the table 4 ways by adding a
'PARTITION BY RANGE' clause as shown here:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT NOT NULL,
         store_id INT NOT NULL
     )
     PARTITION BY RANGE (store_id) (
         PARTITION p0 VALUES LESS THAN (6),
         PARTITION p1 VALUES LESS THAN (11),
         PARTITION p2 VALUES LESS THAN (16),
         PARTITION p3 VALUES LESS THAN (21)
     );

In this partitioning scheme, all rows corresponding to employees working
at stores 1 through 5 are stored in partition 'p0', to those employed at
stores 6 through 10 are stored in partition 'p1', and so on.  Note that
each partition is defined in order, from lowest to highest.  This is a
requirement of the 'PARTITION BY RANGE' syntax; you can think of it as
being analogous to a series of 'if ... elseif ...' statements in C or
Java in this regard.

It is easy to determine that a new row containing the data '(72,
'Mitchell', 'Wilson', '1998-06-25', NULL, 13)' is inserted into
partition 'p2', but what happens when your chain adds a 21^st store?
Under this scheme, there is no rule that covers a row whose 'store_id'
is greater than 20, so an error results because the server does not know
where to place it.  You can keep this from occurring by using a
'catchall' 'VALUES LESS THAN' clause in the 'CREATE TABLE'
statement that provides for all values greater than the
highest value explicitly named:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT NOT NULL,
         store_id INT NOT NULL
     )
     PARTITION BY RANGE (store_id) (
         PARTITION p0 VALUES LESS THAN (6),
         PARTITION p1 VALUES LESS THAN (11),
         PARTITION p2 VALUES LESS THAN (16),
         _PARTITION p3 VALUES LESS THAN MAXVALUE_
     );

*Note*:

Another way to avoid an error when no matching value is found is to use
the 'IGNORE' keyword as part of the 'INSERT' statement.
For an example, see partitioning-list.  Also see insert,
for general information about 'IGNORE'.

'MAXVALUE' represents an integer value that is always greater than the
largest possible integer value (in mathematical language, it serves as a
_least upper bound_).  Now, any rows whose 'store_id' column value is
greater than or equal to 16 (the highest value defined) are stored in
partition 'p3'.  At some point in the future--when the number of stores
has increased to 25, 30, or more--you can use an 'ALTER TABLE'
statement to add new partitions for
stores 21-25, 26-30, and so on (see partitioning-management, for
details of how to do this).

In much the same fashion, you could partition the table based on
employee job codes--that is, based on ranges of 'job_code' column
values.  For example--assuming that two-digit job codes are used for
regular (in-store) workers, three-digit codes are used for office and
support personnel, and four-digit codes are used for management
positions--you could create the partitioned table using the following
statement:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT NOT NULL,
         store_id INT NOT NULL
     )
     PARTITION BY RANGE (job_code) (
         PARTITION p0 VALUES LESS THAN (100),
         PARTITION p1 VALUES LESS THAN (1000),
         PARTITION p2 VALUES LESS THAN (10000)
     );

In this instance, all rows relating to in-store workers would be stored
in partition 'p0', those relating to office and support staff in 'p1',
and those relating to managers in partition 'p2'.

It is also possible to use an expression in 'VALUES LESS THAN' clauses.
However, MySQL must be able to evaluate the expression's return value as
part of a 'LESS THAN' ('<') comparison.

Rather than splitting up the table data according to store number, you
can use an expression based on one of the two 'DATE'.
columns instead.  For example, let us suppose that you wish to partition
based on the year that each employee left the company; that is, the
value of 'YEAR(separated)'.  An example of a 'CREATE TABLE'
statement that implements such a partitioning scheme is
shown here:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT,
         store_id INT
     )
     PARTITION BY RANGE ( YEAR(separated) ) (
         PARTITION p0 VALUES LESS THAN (1991),
         PARTITION p1 VALUES LESS THAN (1996),
         PARTITION p2 VALUES LESS THAN (2001),
         PARTITION p3 VALUES LESS THAN MAXVALUE
     );

In this scheme, for all employees who left before 1991, the rows are
stored in partition 'p0'; for those who left in the years 1991 through
1995, in 'p1'; for those who left in the years 1996 through 2000, in
'p2'; and for any workers who left after the year 2000, in 'p3'.

It is also possible to partition a table by 'RANGE', based on the value
of a 'TIMESTAMP' column, using the 'UNIX_TIMESTAMP()'
function, as shown in this example:

     CREATE TABLE quarterly_report_status (
         report_id INT NOT NULL,
         report_status VARCHAR(20) NOT NULL,
         report_updated TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
     )
     PARTITION BY RANGE ( UNIX_TIMESTAMP(report_updated) ) (
         PARTITION p0 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-01-01 00:00:00') ),
         PARTITION p1 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-04-01 00:00:00') ),
         PARTITION p2 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-07-01 00:00:00') ),
         PARTITION p3 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-10-01 00:00:00') ),
         PARTITION p4 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-01-01 00:00:00') ),
         PARTITION p5 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-04-01 00:00:00') ),
         PARTITION p6 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-07-01 00:00:00') ),
         PARTITION p7 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-10-01 00:00:00') ),
         PARTITION p8 VALUES LESS THAN ( UNIX_TIMESTAMP('2010-01-01 00:00:00') ),
         PARTITION p9 VALUES LESS THAN (MAXVALUE)
     );

Any other expressions involving 'TIMESTAMP' values are
not permitted.  (See Bug #42849.)

Range partitioning is particularly useful when one or more of the
following conditions is true:

   * You want or need to delete 'old' data.  If you are using the
     partitioning scheme shown previously for the 'employees' table, you
     can simply use 'ALTER TABLE employees DROP PARTITION p0;' to delete
     all rows relating to employees who stopped working for the firm
     prior to 1991.  (See alter-table, and
     partitioning-management, for more information.)  For a table with
     a great many rows, this can be much more efficient than running a
     'DELETE' query such as 'DELETE FROM employees WHERE
     YEAR(separated) <= 1990;'.

   * You want to use a column containing date or time values, or
     containing values arising from some other series.

   * You frequently run queries that depend directly on the column used
     for partitioning the table.  For example, when executing a query
     such as *note 'EXPLAIN SELECT COUNT(*) FROM employees WHERE
     separated BETWEEN '2000-01-01' AND '2000-12-31' GROUP BY
     store_id;': explain, MySQL can quickly determine that only
     partition 'p2' needs to be scanned because the remaining partitions
     cannot contain any records satisfying the 'WHERE' clause.  See
     partitioning-pruning, for more information about how this
     is accomplished.

A variant on this type of partitioning is 'RANGE COLUMNS' partitioning.
Partitioning by 'RANGE COLUMNS' makes it possible to employ multiple
columns for defining partitioning ranges that apply both to placement of
rows in partitions and for determining the inclusion or exclusion of
specific partitions when performing partition pruning.  See
partitioning-columns-range, for more information.

Partitioning schemes based on time intervals

If you wish to implement a partitioning scheme based on ranges or
intervals of time in MySQL 5.7, you have two options:

  1. Partition the table by 'RANGE', and for the partitioning
     expression, employ a function operating on a 'DATE',
     see 'TIME', or 'DATETIME' column
     and returning an integer value, as shown here:

          CREATE TABLE members (
              firstname VARCHAR(25) NOT NULL,
              lastname VARCHAR(25) NOT NULL,
              username VARCHAR(16) NOT NULL,
              email VARCHAR(35),
              joined DATE NOT NULL
          )
          PARTITION BY RANGE( YEAR(joined) ) (
              PARTITION p0 VALUES LESS THAN (1960),
              PARTITION p1 VALUES LESS THAN (1970),
              PARTITION p2 VALUES LESS THAN (1980),
              PARTITION p3 VALUES LESS THAN (1990),
              PARTITION p4 VALUES LESS THAN MAXVALUE
          );

     In MySQL 5.7, it is also possible to partition a table by 'RANGE'
     based on the value of a 'TIMESTAMP' column, using
     the 'UNIX_TIMESTAMP()' function, as shown in this example:

          CREATE TABLE quarterly_report_status (
              report_id INT NOT NULL,
              report_status VARCHAR(20) NOT NULL,
              report_updated TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
          )
          PARTITION BY RANGE ( UNIX_TIMESTAMP(report_updated) ) (
              PARTITION p0 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-01-01 00:00:00') ),
              PARTITION p1 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-04-01 00:00:00') ),
              PARTITION p2 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-07-01 00:00:00') ),
              PARTITION p3 VALUES LESS THAN ( UNIX_TIMESTAMP('2008-10-01 00:00:00') ),
              PARTITION p4 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-01-01 00:00:00') ),
              PARTITION p5 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-04-01 00:00:00') ),
              PARTITION p6 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-07-01 00:00:00') ),
              PARTITION p7 VALUES LESS THAN ( UNIX_TIMESTAMP('2009-10-01 00:00:00') ),
              PARTITION p8 VALUES LESS THAN ( UNIX_TIMESTAMP('2010-01-01 00:00:00') ),
              PARTITION p9 VALUES LESS THAN (MAXVALUE)
          );

     In MySQL 5.7, any other expressions involving 'TIMESTAMP'
     values are not permitted.  (See Bug #42849.)

     *Note*:

     It is also possible in MySQL 5.7 to use
     'UNIX_TIMESTAMP(timestamp_column)' as a partitioning expression for
     tables that are partitioned by 'LIST'.  However, it is usually not
     practical to do so.

  2. Partition the table by 'RANGE COLUMNS', using a 'DATE'
     or 'DATETIME' column as the partitioning
     column.  For example, the 'members' table could be defined using
     the 'joined' column directly, as shown here:

          CREATE TABLE members (
              firstname VARCHAR(25) NOT NULL,
              lastname VARCHAR(25) NOT NULL,
              username VARCHAR(16) NOT NULL,
              email VARCHAR(35),
              joined DATE NOT NULL
          )
          PARTITION BY RANGE COLUMNS(joined) (
              PARTITION p0 VALUES LESS THAN ('1960-01-01'),
              PARTITION p1 VALUES LESS THAN ('1970-01-01'),
              PARTITION p2 VALUES LESS THAN ('1980-01-01'),
              PARTITION p3 VALUES LESS THAN ('1990-01-01'),
              PARTITION p4 VALUES LESS THAN MAXVALUE
          );

*Note*:

The use of partitioning columns employing date or time types other than
'DATE' or 'DATETIME' is not supported
with 'RANGE COLUMNS'.

22.2.2 LIST Partitioning
------------------------

List partitioning in MySQL is similar to range partitioning in many
ways.  As in partitioning by 'RANGE', each partition must be explicitly
defined.  The chief difference between the two types of partitioning is
that, in list partitioning, each partition is defined and selected based
on the membership of a column value in one of a set of value lists,
rather than in one of a set of contiguous ranges of values.  This is
done by using 'PARTITION BY LIST(EXPR)' where EXPR is a column value or
an expression based on a column value and returning an integer value,
and then defining each partition by means of a 'VALUES IN (VALUE_LIST)',
where VALUE_LIST is a comma-separated list of integers.

*Note*:

In MySQL 5.7, it is possible to match against only a list of integers
(and possibly 'NULL'--see partitioning-handling-nulls) when
partitioning by 'LIST'.

However, other column types may be used in value lists when employing
'LIST COLUMN' partitioning, which is described later in this section.

Unlike the case with partitions defined by range, list partitions do not
need to be declared in any particular order.  For more detailed
syntactical information, see create-table.

For the examples that follow, we assume that the basic definition of the
table to be partitioned is provided by the 'CREATE TABLE'
statement shown here:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT,
         store_id INT
     );

(This is the same table used as a basis for the examples in
partitioning-range.)

Suppose that there are 20 video stores distributed among 4 franchises as
shown in the following table.

Region                 Store ID Numbers

North                  3, 5, 6, 9, 17

East                   1, 2, 10, 11, 19, 20

West                   4, 12, 13, 14, 18

Central                7, 8, 15, 16

To partition this table in such a way that rows for stores belonging to
the same region are stored in the same partition, you could use the
'CREATE TABLE' statement shown here:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT,
         store_id INT
     )
     PARTITION BY LIST(store_id) (
         PARTITION pNorth VALUES IN (3,5,6,9,17),
         PARTITION pEast VALUES IN (1,2,10,11,19,20),
         PARTITION pWest VALUES IN (4,12,13,14,18),
         PARTITION pCentral VALUES IN (7,8,15,16)
     );

This makes it easy to add or drop employee records relating to specific
regions to or from the table.  For instance, suppose that all stores in
the West region are sold to another company.  In MySQL 5.7, all rows
relating to employees working at stores in that region can be deleted
with the query 'ALTER TABLE employees TRUNCATE PARTITION pWest', which
can be executed much more efficiently than the equivalent
'DELETE' statement 'DELETE FROM employees WHERE store_id IN
(4,12,13,14,18);'.  (Using 'ALTER TABLE employees DROP PARTITION pWest'
would also delete all of these rows, but would also remove the partition
'pWest' from the definition of the table; you would need to use an
'ALTER TABLE ... ADD PARTITION' statement to restore the table's
original partitioning scheme.)

As with 'RANGE' partitioning, it is possible to combine 'LIST'
partitioning with partitioning by hash or key to produce a composite
partitioning (subpartitioning).  See partitioning-subpartitions.

Unlike the case with 'RANGE' partitioning, there is no 'catch-all' such
as 'MAXVALUE'; all expected values for the partitioning expression
should be covered in 'PARTITION ... VALUES IN (...)' clauses.  An
'INSERT' statement containing an unmatched partitioning column
value fails with an error, as shown in this example:

     mysql> CREATE TABLE h2 (
         ->   c1 INT,
         ->   c2 INT
         -> )
         -> PARTITION BY LIST(c1) (
         ->   PARTITION p0 VALUES IN (1, 4, 7),
         ->   PARTITION p1 VALUES IN (2, 5, 8)
         -> );
     Query OK, 0 rows affected (0.11 sec)

     mysql> INSERT INTO h2 VALUES (3, 5);
     ERROR 1525 (HY000): Table has no partition for value 3

When inserting multiple rows using a single 'INSERT'.
statement the behavior depends on whether the table uses a transactional
storage engine.  For an 'InnoDB' table,
the statement is considered a single transaction, so the presence of any
unmatched values causes the statement to fail completely, and no rows
are inserted.  For a table using a nontransactional storage engine such
as 'MyISAM', any rows coming before the row
containing the unmatched value are inserted, but any coming after it are
not.

You can cause this type of error to be ignored by using the 'IGNORE'
keyword.  If you do so, rows containing unmatched partitioning column
values are not inserted, but any rows with matching values _are_
inserted, and no errors are reported:

     mysql> TRUNCATE h2;
     Query OK, 1 row affected (0.00 sec)

     mysql> SELECT * FROM h2;
     Empty set (0.00 sec)

     mysql> INSERT IGNORE INTO h2 VALUES (2, 5), (6, 10), (7, 5), (3, 1), (1, 9);
     Query OK, 3 rows affected (0.00 sec)
     Records: 5  Duplicates: 2  Warnings: 0

     mysql> SELECT * FROM h2;
     +------+------+
     | c1   | c2   |
     +------+------+
     |    7 |    5 |
     |    1 |    9 |
     |    2 |    5 |
     +------+------+
     3 rows in set (0.00 sec)

MySQL 5.7 provides support for 'LIST COLUMNS' partitioning.  This is a
variant of 'LIST' partitioning that enables you to use columns of types
other than integer types for partitioning columns, as well as to use
multiple columns as partitioning keys.  For more information, see
partitioning-columns-list.

22.2.3 COLUMNS Partitioning
---------------------------

The next two sections discuss _'COLUMNS' partitioning_, which are
variants on 'RANGE' and 'LIST' partitioning.  'COLUMNS' partitioning
enables the use of multiple columns in partitioning keys.  All of these
columns are taken into account both for the purpose of placing rows in
partitions and for the determination of which partitions are to be
checked for matching rows in partition pruning.

In addition, both 'RANGE COLUMNS' partitioning and 'LIST COLUMNS'
partitioning support the use of non-integer columns for defining value
ranges or list members.  The permitted data types are shown in the
following list:

   * All integer types: 'TINYINT',
     'SMALLINT', 'MEDIUMINT',
     'INT'. (see 'INTEGER'), and
     'BIGINT'.  (This is the same as with partitioning by
     'RANGE' and 'LIST'.)

     Other numeric data types (such as 'DECIMAL'
     or 'FLOAT') are not
     supported as partitioning columns.

   * 'DATE' and 'DATETIME'.

     Columns using other data types relating to dates or times are not
     supported as partitioning columns.

   * The following string types: 'CHAR', 'VARCHAR',
     see 'BINARY', and 'VARBINARY'.

     'TEXT' and 'BLOB' columns are not
     supported as partitioning columns.

The discussions of 'RANGE COLUMNS' and 'LIST COLUMNS' partitioning in
the next two sections assume that you are already familiar with
partitioning based on ranges and lists as supported in MySQL 5.1 and
later; for more information about these, see partitioning-range,
and partitioning-list, respectively.

22.2.3.1 RANGE COLUMNS partitioning
...................................

Range columns partitioning is similar to range partitioning, but enables
you to define partitions using ranges based on multiple column values.
In addition, you can define the ranges using columns of types other than
integer types.

'RANGE COLUMNS' partitioning differs significantly from 'RANGE'
partitioning in the following ways:

   * 'RANGE COLUMNS' does not accept expressions, only names of columns.

   * 'RANGE COLUMNS' accepts a list of one or more columns.

     'RANGE COLUMNS' partitions are based on comparisons between
     _tuples_ (lists of column values) rather than comparisons between
     scalar values.  Placement of rows in 'RANGE COLUMNS' partitions is
     also based on comparisons between tuples; this is discussed further
     later in this section.

   * 'RANGE COLUMNS' partitioning columns are not restricted to integer
     columns; string, see 'DATE' and 'DATETIME'
     columns can also be used as partitioning columns.  (See
     partitioning-columns, for details.)

The basic syntax for creating a table partitioned by 'RANGE COLUMNS' is
shown here:

     CREATE TABLE TABLE_NAME
     PARTITIONED BY RANGE COLUMNS(COLUMN_LIST) (
         PARTITION PARTITION_NAME VALUES LESS THAN (VALUE_LIST)[,
         PARTITION PARTITION_NAME VALUES LESS THAN (VALUE_LIST)][,
         ...]
     )

     COLUMN_LIST:
         COLUMN_NAME[, COLUMN_NAME][, ...]

     VALUE_LIST:
         VALUE[, VALUE][, ...]

*Note*:

Not all 'CREATE TABLE' options that can be used
when creating partitioned tables are shown here.  For complete
information, see create-table.

In the syntax just shown, COLUMN_LIST is a list of one or more columns
(sometimes called a _partitioning column list_), and VALUE_LIST is a
list of values (that is, it is a _partition definition value list_).  A
VALUE_LIST must be supplied for each partition definition, and each
VALUE_LIST must have the same number of values as the COLUMN_LIST has
columns.  Generally speaking, if you use N columns in the 'COLUMNS'
clause, then each 'VALUES LESS THAN' clause must also be supplied with a
list of N values.

The elements in the partitioning column list and in the value list
defining each partition must occur in the same order.  In addition, each
element in the value list must be of the same data type as the
corresponding element in the column list.  However, the order of the
column names in the partitioning column list and the value lists does
not have to be the same as the order of the table column definitions in
the main part of the 'CREATE TABLE' statement.  As
with table partitioned by 'RANGE', you can use 'MAXVALUE' to represent a
value such that any legal value inserted into a given column is always
less than this value.  Here is an example of a 'CREATE TABLE'
statement that helps to illustrate all of these points:

     mysql> CREATE TABLE rcx (
         ->     a INT,
         ->     b INT,
         ->     c CHAR(3),
         ->     d INT
         -> )
         -> PARTITION BY RANGE COLUMNS(a,d,c) (
         ->     PARTITION p0 VALUES LESS THAN (5,10,'ggg'),
         ->     PARTITION p1 VALUES LESS THAN (10,20,'mmm'),
         ->     PARTITION p2 VALUES LESS THAN (15,30,'sss'),
         ->     PARTITION p3 VALUES LESS THAN (MAXVALUE,MAXVALUE,MAXVALUE)
         -> );
     Query OK, 0 rows affected (0.15 sec)

Table 'rcx' contains the columns 'a', 'b', 'c', 'd'.  The partitioning
column list supplied to the 'COLUMNS' clause uses 3 of these columns, in
the order 'a', 'd', 'c'.  Each value list used to define a partition
contains 3 values in the same order; that is, each value list tuple has
the form ('INT', 'INT', 'CHAR(3)'), which corresponds to the data types
used by columns 'a', 'd', and 'c' (in that order).

Placement of rows into partitions is determined by comparing the tuple
from a row to be inserted that matches the column list in the 'COLUMNS'
clause with the tuples used in the 'VALUES LESS THAN' clauses to define
partitions of the table.  Because we are comparing tuples (that is,
lists or sets of values) rather than scalar values, the semantics of
'VALUES LESS THAN' as used with 'RANGE COLUMNS' partitions differs
somewhat from the case with simple 'RANGE' partitions.  In 'RANGE'
partitioning, a row generating an expression value that is equal to a
limiting value in a 'VALUES LESS THAN' is never placed in the
corresponding partition; however, when using 'RANGE COLUMNS'
partitioning, it is sometimes possible for a row whose partitioning
column list's first element is equal in value to the that of the first
element in a 'VALUES LESS THAN' value list to be placed in the
corresponding partition.

Consider the 'RANGE' partitioned table created by this statement:

     CREATE TABLE r1 (
         a INT,
         b INT
     )
     PARTITION BY RANGE (a)  (
         PARTITION p0 VALUES LESS THAN (5),
         PARTITION p1 VALUES LESS THAN (MAXVALUE)
     );

If we insert 3 rows into this table such that the column value for 'a'
is '5' for each row, all 3 rows are stored in partition 'p1' because the
'a' column value is in each case not less than 5, as we can see by
executing the proper query against the
'INFORMATION_SCHEMA.PARTITIONS' table:

     mysql> INSERT INTO r1 VALUES (5,10), (5,11), (5,12);
     Query OK, 3 rows affected (0.00 sec)
     Records: 3  Duplicates: 0  Warnings: 0

     mysql> SELECT PARTITION_NAME,TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'r1';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |          0 |
     | p1             |          3 |
     +----------------+------------+
     2 rows in set (0.00 sec)

Now consider a similar table 'rc1' that uses 'RANGE COLUMNS'
partitioning with both columns 'a' and 'b' referenced in the 'COLUMNS'
clause, created as shown here:

     CREATE TABLE rc1 (
         a INT,
         b INT
     )
     PARTITION BY RANGE COLUMNS(a, b) (
         PARTITION p0 VALUES LESS THAN (5, 12),
         PARTITION p3 VALUES LESS THAN (MAXVALUE, MAXVALUE)
     );

If we insert exactly the same rows into 'rc1' as we just inserted into
'r1', the distribution of the rows is quite different:

     mysql> INSERT INTO rc1 VALUES (5,10), (5,11), (5,12);
     Query OK, 3 rows affected (0.00 sec)
     Records: 3  Duplicates: 0  Warnings: 0

     mysql> SELECT PARTITION_NAME,TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'rc1';
     +--------------+----------------+------------+
     | TABLE_SCHEMA | PARTITION_NAME | TABLE_ROWS |
     +--------------+----------------+------------+
     | p            | p0             |          2 |
     | p            | p1             |          1 |
     +--------------+----------------+------------+
     2 rows in set (0.00 sec)

This is because we are comparing rows rather than scalar values.  We can
compare the row values inserted with the limiting row value from the
'VALUES THAN LESS THAN' clause used to define partition 'p0' in table
'rc1', like this:

     mysql> SELECT (5,10) < (5,12), (5,11) < (5,12), (5,12) < (5,12);
     +-----------------+-----------------+-----------------+
     | (5,10) < (5,12) | (5,11) < (5,12) | (5,12) < (5,12) |
     +-----------------+-----------------+-----------------+
     |               1 |               1 |               0 |
     +-----------------+-----------------+-----------------+
     1 row in set (0.00 sec)

The 2 tuples '(5,10)' and '(5,11)' evaluate as less than '(5,12)', so
they are stored in partition 'p0'.  Since 5 is not less than 5 and 12 is
not less than 12, '(5,12)' is considered not less than '(5,12)', and is
stored in partition 'p1'.

The 'SELECT' statement in the preceding example could
also have been written using explicit row constructors, like this:

     SELECT ROW(5,10) < ROW(5,12), ROW(5,11) < ROW(5,12), ROW(5,12) < ROW(5,12);

For more information about the use of row constructors in MySQL, see
row-subqueries.

For a table partitioned by 'RANGE COLUMNS' using only a single
partitioning column, the storing of rows in partitions is the same as
that of an equivalent table that is partitioned by 'RANGE'.  The
following 'CREATE TABLE' statement creates a table partitioned by 'RANGE
COLUMNS' using 1 partitioning column:

     CREATE TABLE rx (
         a INT,
         b INT
     )
     PARTITION BY RANGE COLUMNS (a)  (
         PARTITION p0 VALUES LESS THAN (5),
         PARTITION p1 VALUES LESS THAN (MAXVALUE)
     );

If we insert the rows '(5,10)', '(5,11)', and '(5,12)' into this table,
we can see that their placement is the same as it is for the table 'r'
we created and populated earlier:

     mysql> INSERT INTO rx VALUES (5,10), (5,11), (5,12);
     Query OK, 3 rows affected (0.00 sec)
     Records: 3  Duplicates: 0  Warnings: 0

     mysql> SELECT PARTITION_NAME,TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'rx';
     +--------------+----------------+------------+
     | TABLE_SCHEMA | PARTITION_NAME | TABLE_ROWS |
     +--------------+----------------+------------+
     | p            | p0             |          0 |
     | p            | p1             |          3 |
     +--------------+----------------+------------+
     2 rows in set (0.00 sec)

It is also possible to create tables partitioned by 'RANGE COLUMNS'
where limiting values for one or more columns are repeated in successive
partition definitions.  You can do this as long as the tuples of column
values used to define the partitions are strictly increasing.  For
example, each of the following 'CREATE TABLE'.
statements is valid:

     CREATE TABLE rc2 (
         a INT,
         b INT
     )
     PARTITION BY RANGE COLUMNS(a,b) (
         PARTITION p0 VALUES LESS THAN (0,10),
         PARTITION p1 VALUES LESS THAN (10,20),
         PARTITION p2 VALUES LESS THAN (10,30),
         PARTITION p3 VALUES LESS THAN (MAXVALUE,MAXVALUE)
      );

     CREATE TABLE rc3 (
         a INT,
         b INT
     )
     PARTITION BY RANGE COLUMNS(a,b) (
         PARTITION p0 VALUES LESS THAN (0,10),
         PARTITION p1 VALUES LESS THAN (10,20),
         PARTITION p2 VALUES LESS THAN (10,30),
         PARTITION p3 VALUES LESS THAN (10,35),
         PARTITION p4 VALUES LESS THAN (20,40),
         PARTITION p5 VALUES LESS THAN (MAXVALUE,MAXVALUE)
      );

The following statement also succeeds, even though it might appear at
first glance that it would not, since the limiting value of column 'b'
is 25 for partition 'p0' and 20 for partition 'p1', and the limiting
value of column 'c' is 100 for partition 'p1' and 50 for partition 'p2':

     CREATE TABLE rc4 (
         a INT,
         b INT,
         c INT
     )
     PARTITION BY RANGE COLUMNS(a,b,c) (
         PARTITION p0 VALUES LESS THAN (0,25,50),
         PARTITION p1 VALUES LESS THAN (10,20,100),
         PARTITION p2 VALUES LESS THAN (10,30,50)
         PARTITION p3 VALUES LESS THAN (MAXVALUE,MAXVALUE,MAXVALUE)
      );

When designing tables partitioned by 'RANGE COLUMNS', you can always
test successive partition definitions by comparing the desired tuples
using the 'mysql' client, like this:

     mysql> SELECT (0,25,50) < (10,20,100), (10,20,100) < (10,30,50);
     +-------------------------+--------------------------+
     | (0,25,50) < (10,20,100) | (10,20,100) < (10,30,50) |
     +-------------------------+--------------------------+
     |                       1 |                        1 |
     +-------------------------+--------------------------+
     1 row in set (0.00 sec)

If a 'CREATE TABLE' statement contains partition
definitions that are not in strictly increasing order, it fails with an
error, as shown in this example:

     mysql> CREATE TABLE rcf (
         ->     a INT,
         ->     b INT,
         ->     c INT
         -> )
         -> PARTITION BY RANGE COLUMNS(a,b,c) (
         ->     PARTITION p0 VALUES LESS THAN (0,25,50),
         ->     PARTITION p1 VALUES LESS THAN (20,20,100),
         ->     PARTITION p2 VALUES LESS THAN (10,30,50),
         ->     PARTITION p3 VALUES LESS THAN (MAXVALUE,MAXVALUE,MAXVALUE)
         ->  );
     ERROR 1493 (HY000): VALUES LESS THAN value must be strictly increasing for each partition

When you get such an error, you can deduce which partition definitions
are invalid by making 'less than' comparisons between their column
lists.  In this case, the problem is with the definition of partition
'p2' because the tuple used to define it is not less than the tuple used
to define partition 'p3', as shown here:

     mysql> SELECT (0,25,50) < (20,20,100), (20,20,100) < (10,30,50);
     +-------------------------+--------------------------+
     | (0,25,50) < (20,20,100) | (20,20,100) < (10,30,50) |
     +-------------------------+--------------------------+
     |                       1 |                        0 |
     +-------------------------+--------------------------+
     1 row in set (0.00 sec)

It is also possible for 'MAXVALUE' to appear for the same column in more
than one 'VALUES LESS THAN' clause when using 'RANGE COLUMNS'.  However,
the limiting values for individual columns in successive partition
definitions should otherwise be increasing, there should be no more than
one partition defined where 'MAXVALUE' is used as the upper limit for
all column values, and this partition definition should appear last in
the list of 'PARTITION ... VALUES LESS THAN' clauses.  In addition, you
cannot use 'MAXVALUE' as the limiting value for the first column in more
than one partition definition.

As stated previously, it is also possible with 'RANGE COLUMNS'
partitioning to use non-integer columns as partitioning columns.  (See
partitioning-columns, for a complete listing of these.)
Consider a table named 'employees' (which is not partitioned), created
using the following statement:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT NOT NULL,
         store_id INT NOT NULL
     );

Using 'RANGE COLUMNS' partitioning, you can create a version of this
table that stores each row in one of four partitions based on the
employee's last name, like this:

     CREATE TABLE employees_by_lname (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT NOT NULL,
         store_id INT NOT NULL
     )
     PARTITION BY RANGE COLUMNS (lname)  (
         PARTITION p0 VALUES LESS THAN ('g'),
         PARTITION p1 VALUES LESS THAN ('m'),
         PARTITION p2 VALUES LESS THAN ('t'),
         PARTITION p3 VALUES LESS THAN (MAXVALUE)
     );

Alternatively, you could cause the 'employees' table as created
previously to be partitioned using this scheme by executing the
following 'ALTER TABLE'.
statement:

     ALTER TABLE employees PARTITION BY RANGE COLUMNS (lname)  (
         PARTITION p0 VALUES LESS THAN ('g'),
         PARTITION p1 VALUES LESS THAN ('m'),
         PARTITION p2 VALUES LESS THAN ('t'),
         PARTITION p3 VALUES LESS THAN (MAXVALUE)
     );

*Note*:

Because different character sets and collations have different sort
orders, the character sets and collations in use may effect which
partition of a table partitioned by 'RANGE COLUMNS' a given row is
stored in when using string columns as partitioning columns.  In
addition, changing the character set or collation for a given database,
table, or column after such a table is created may cause changes in how
rows are distributed.  For example, when using a case-sensitive
collation, ''and'' sorts before ''Andersen'', but when using a collation
that is case insensitive, the reverse is true.

For information about how MySQL handles character sets and collations,
see charset.

Similarly, you can cause the 'employees' table to be partitioned in such
a way that each row is stored in one of several partitions based on the
decade in which the corresponding employee was hired using the
'ALTER TABLE' statement shown here:

     ALTER TABLE employees PARTITION BY RANGE COLUMNS (hired)  (
         PARTITION p0 VALUES LESS THAN ('1970-01-01'),
         PARTITION p1 VALUES LESS THAN ('1980-01-01'),
         PARTITION p2 VALUES LESS THAN ('1990-01-01'),
         PARTITION p3 VALUES LESS THAN ('2000-01-01'),
         PARTITION p4 VALUES LESS THAN ('2010-01-01'),
         PARTITION p5 VALUES LESS THAN (MAXVALUE)
     );

See create-table, for additional information about 'PARTITION BY
RANGE COLUMNS' syntax.

22.2.3.2 LIST COLUMNS partitioning
..................................

MySQL 5.7 provides support for 'LIST COLUMNS' partitioning.  This is a
variant of 'LIST' partitioning that enables the use of multiple columns
as partition keys, and for columns of data types other than integer
types to be used as partitioning columns; you can use string types,
see 'DATE', and 'DATETIME' columns.  (For
more information about permitted data types for 'COLUMNS' partitioning
columns, see partitioning-columns.)

Suppose that you have a business that has customers in 12 cities which,
for sales and marketing purposes, you organize into 4 regions of 3
cities each as shown in the following table:

Region                               Cities

1                                    Oskarshamn, Ho"gsby, Mo"nsteraas

2                                    Vimmerby, Hultsfred, Va"stervik

3                                    Na"ssjo", Eksjo", Vetlanda

4                                    Uppvidinge, Alvesta, Va"xjo

With 'LIST COLUMNS' partitioning, you can create a table for customer
data that assigns a row to any of 4 partitions corresponding to these
regions based on the name of the city where a customer resides, as shown
here:

     CREATE TABLE customers_1 (
         first_name VARCHAR(25),
         last_name VARCHAR(25),
         street_1 VARCHAR(30),
         street_2 VARCHAR(30),
         city VARCHAR(15),
         renewal DATE
     )
     PARTITION BY LIST COLUMNS(city) (
         PARTITION pRegion_1 VALUES IN('Oskarshamn', 'Ho"gsby', 'Mo"nsteraas'),
         PARTITION pRegion_2 VALUES IN('Vimmerby', 'Hultsfred', 'Va"stervik'),
         PARTITION pRegion_3 VALUES IN('Na"ssjo"', 'Eksjo"', 'Vetlanda'),
         PARTITION pRegion_4 VALUES IN('Uppvidinge', 'Alvesta', 'Va"xjo')
     );

As with partitioning by 'RANGE COLUMNS', you do not need to use
expressions in the 'COLUMNS()' clause to convert column values into
integers.  (In fact, the use of expressions other than column names is
not permitted with 'COLUMNS()'.)

It is also possible to use 'DATE' and 'DATETIME'
columns, as shown in the following example that uses the same
name and columns as the 'customers_1' table shown previously, but
employs 'LIST COLUMNS' partitioning based on the 'renewal' column to
store rows in one of 4 partitions depending on the week in February 2010
the customer's account is scheduled to renew:

     CREATE TABLE customers_2 (
         first_name VARCHAR(25),
         last_name VARCHAR(25),
         street_1 VARCHAR(30),
         street_2 VARCHAR(30),
         city VARCHAR(15),
         renewal DATE
     )
     PARTITION BY LIST COLUMNS(renewal) (
         PARTITION pWeek_1 VALUES IN('2010-02-01', '2010-02-02', '2010-02-03',
             '2010-02-04', '2010-02-05', '2010-02-06', '2010-02-07'),
         PARTITION pWeek_2 VALUES IN('2010-02-08', '2010-02-09', '2010-02-10',
             '2010-02-11', '2010-02-12', '2010-02-13', '2010-02-14'),
         PARTITION pWeek_3 VALUES IN('2010-02-15', '2010-02-16', '2010-02-17',
             '2010-02-18', '2010-02-19', '2010-02-20', '2010-02-21'),
         PARTITION pWeek_4 VALUES IN('2010-02-22', '2010-02-23', '2010-02-24',
             '2010-02-25', '2010-02-26', '2010-02-27', '2010-02-28')
     );

This works, but becomes cumbersome to define and maintain if the number
of dates involved grows very large; in such cases, it is usually more
practical to employ 'RANGE' or 'RANGE COLUMNS' partitioning instead.  In
this case, since the column we wish to use as the partitioning key is a
'DATE' column, we use 'RANGE COLUMNS' partitioning, as
shown here:

     CREATE TABLE customers_3 (
         first_name VARCHAR(25),
         last_name VARCHAR(25),
         street_1 VARCHAR(30),
         street_2 VARCHAR(30),
         city VARCHAR(15),
         renewal DATE
     )
     PARTITION BY RANGE COLUMNS(renewal) (
         PARTITION pWeek_1 VALUES LESS THAN('2010-02-09'),
         PARTITION pWeek_2 VALUES LESS THAN('2010-02-15'),
         PARTITION pWeek_3 VALUES LESS THAN('2010-02-22'),
         PARTITION pWeek_4 VALUES LESS THAN('2010-03-01')
     );

See partitioning-columns-range, for more information.

In addition (as with 'RANGE COLUMNS' partitioning), you can use multiple
columns in the 'COLUMNS()' clause.

See create-table, for additional information about 'PARTITION BY
LIST COLUMNS()' syntax.

22.2.4 HASH Partitioning
------------------------

Partitioning by 'HASH' is used primarily to ensure an even distribution
of data among a predetermined number of partitions.  With range or list
partitioning, you must specify explicitly into which partition a given
column value or set of column values is to be stored; with hash
partitioning, MySQL takes care of this for you, and you need only
specify a column value or expression based on a column value to be
hashed and the number of partitions into which the partitioned table is
to be divided.

To partition a table using 'HASH' partitioning, it is necessary to
append to the 'CREATE TABLE' statement a 'PARTITION
BY HASH (EXPR)' clause, where EXPR is an expression that returns an
integer.  This can simply be the name of a column whose type is one of
MySQL's integer types.  In addition, you most likely want to follow this
with 'PARTITIONS NUM', where NUM is a positive integer representing the
number of partitions into which the table is to be divided.

*Note*:

For simplicity, the tables in the examples that follow do not use any
keys.  You should be aware that, if a table has any unique keys, every
column used in the partitioning expression for this table must be part
of every unique key, including the primary key.  See
partitioning-limitations-partitioning-keys-unique-keys, for more
information.

The following statement creates a table that uses hashing on the
'store_id' column and is divided into 4 partitions:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT,
         store_id INT
     )
     PARTITION BY HASH(store_id)
     PARTITIONS 4;

If you do not include a 'PARTITIONS' clause, the number of partitions
defaults to '1'.

Using the 'PARTITIONS' keyword without a number following it results in
a syntax error.

You can also use an SQL expression that returns an integer for EXPR.
For instance, you might want to partition based on the year in which an
employee was hired.  This can be done as shown here:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT,
         store_id INT
     )
     PARTITION BY HASH( YEAR(hired) )
     PARTITIONS 4;

EXPR must return a nonconstant, nonrandom integer value (in other words,
it should be varying but deterministic), and must not contain any
prohibited constructs as described in partitioning-limitations.
You should also keep in mind that this expression is evaluated each time
a row is inserted or updated (or possibly deleted); this means that very
complex expressions may give rise to performance issues, particularly
when performing operations (such as batch inserts) that affect a great
many rows at one time.

The most efficient hashing function is one which operates upon a single
table column and whose value increases or decreases consistently with
the column value, as this allows for 'pruning' on ranges of partitions.
That is, the more closely that the expression varies with the value of
the column on which it is based, the more efficiently MySQL can use the
expression for hash partitioning.

For example, where 'date_col' is a column of type 'DATE',
then the expression 'TO_DAYS(date_col)' is said to vary
directly with the value of 'date_col', because for every change in the
value of 'date_col', the value of the expression changes in a consistent
manner.  The variance of the expression 'YEAR(date_col)' with respect to
'date_col' is not quite as direct as that of 'TO_DAYS(date_col)',
because not every possible change in 'date_col' produces an equivalent
change in 'YEAR(date_col)'.  Even so, 'YEAR(date_col)' is a good
candidate for a hashing function, because it varies directly with a
portion of 'date_col' and there is no possible change in 'date_col' that
produces a disproportionate change in 'YEAR(date_col)'.

By way of contrast, suppose that you have a column named 'int_col' whose
type is 'INT'.  Now consider the expression
'POW(5-int_col,3) + 6'.  This would be a poor choice for a hashing
function because a change in the value of 'int_col' is not guaranteed to
produce a proportional change in the value of the expression.  Changing
the value of 'int_col' by a given amount can produce widely differing
changes in the value of the expression.  For example, changing 'int_col'
from '5' to '6' produces a change of '-1' in the value of the
expression, but changing the value of 'int_col' from '6' to '7' produces
a change of '-7' in the expression value.

In other words, the more closely the graph of the column value versus
the value of the expression follows a straight line as traced by the
equation 'y=Cx' where C is some nonzero constant, the better the
expression is suited to hashing.  This has to do with the fact that the
more nonlinear an expression is, the more uneven the distribution of
data among the partitions it tends to produce.

In theory, pruning is also possible for expressions involving more than
one column value, but determining which of such expressions are suitable
can be quite difficult and time-consuming.  For this reason, the use of
hashing expressions involving multiple columns is not particularly
recommended.

When 'PARTITION BY HASH' is used, MySQL determines which partition of
NUM partitions to use based on the modulus of the result of the
expression.  In other words, for a given expression EXPR, the partition
in which the record is stored is partition number N, where 'N =
MOD(EXPR, NUM)'.  Suppose that table 't1' is defined as follows, so that
it has 4 partitions:

     CREATE TABLE t1 (col1 INT, col2 CHAR(5), col3 DATE)
         PARTITION BY HASH( YEAR(col3) )
         PARTITIONS 4;

If you insert a record into 't1' whose 'col3' value is ''2005-09-15'',
then the partition in which it is stored is determined as follows:

     MOD(YEAR('2005-09-01'),4)
     =  MOD(2005,4)
     =  1

MySQL 5.7 also supports a variant of 'HASH' partitioning known as
_linear hashing_ which employs a more complex algorithm for determining
the placement of new rows inserted into the partitioned table.  See
partitioning-linear-hash, for a description of this algorithm.

The user-supplied expression is evaluated each time a record is inserted
or updated.  It may also--depending on the circumstances--be evaluated
when records are deleted.

22.2.4.1 LINEAR HASH Partitioning
.................................

MySQL also supports linear hashing, which differs from regular hashing
in that linear hashing utilizes a linear powers-of-two algorithm whereas
regular hashing employs the modulus of the hashing function's value.

Syntactically, the only difference between linear-hash partitioning and
regular hashing is the addition of the 'LINEAR' keyword in the
'PARTITION BY' clause, as shown here:

     CREATE TABLE employees (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30),
         hired DATE NOT NULL DEFAULT '1970-01-01',
         separated DATE NOT NULL DEFAULT '9999-12-31',
         job_code INT,
         store_id INT
     )
     PARTITION BY LINEAR HASH( YEAR(hired) )
     PARTITIONS 4;

Given an expression EXPR, the partition in which the record is stored
when linear hashing is used is partition number N from among NUM
partitions, where N is derived according to the following algorithm:

  1. Find the next power of 2 greater than NUM.  We call this value V;
     it can be calculated as:

          V = POWER(2, CEILING(LOG(2, NUM)))

     (Suppose that NUM is 13.  Then 'LOG(2,13)' is 3.7004397181411.
     'CEILING(3.7004397181411)' is 4, and V = 'POWER(2,4)', which is
     16.)

  2. Set N = F(COLUMN_LIST) & (V - 1).

  3. While N >= NUM:

        * Set V = V / 2

        * Set N = N & (V - 1)

Suppose that the table 't1', using linear hash partitioning and having 6
partitions, is created using this statement:

     CREATE TABLE t1 (col1 INT, col2 CHAR(5), col3 DATE)
         PARTITION BY LINEAR HASH( YEAR(col3) )
         PARTITIONS 6;

Now assume that you want to insert two records into 't1' having the
'col3' column values ''2003-04-14'' and ''1998-10-19''.  The partition
number for the first of these is determined as follows:

     V = POWER(2, CEILING( LOG(2,6) )) = 8
     N = YEAR('2003-04-14') & (8 - 1)
        = 2003 & 7
        = 3

     (_3 >= 6 is FALSE: record stored in partition #3_)

The number of the partition where the second record is stored is
calculated as shown here:

     V = 8
     N = YEAR('1998-10-19') & (8 - 1)
       = 1998 & 7
       = 6

     (_6 >= 6 is TRUE: additional step required_)

     N = 6 & ((8 / 2) - 1)
       = 6 & 3
       = 2

     (_2 >= 6 is FALSE: record stored in partition #2_)

The advantage in partitioning by linear hash is that the adding,
dropping, merging, and splitting of partitions is made much faster,
which can be beneficial when dealing with tables containing extremely
large amounts (terabytes) of data.  The disadvantage is that data is
less likely to be evenly distributed between partitions as compared with
the distribution obtained using regular hash partitioning.

22.2.5 KEY Partitioning
-----------------------

Partitioning by key is similar to partitioning by hash, except that
where hash partitioning employs a user-defined expression, the hashing
function for key partitioning is supplied by the MySQL server.  NDB
Cluster uses 'MD5()' for this purpose; for tables using other storage
engines, the server employs its own internal hashing function which is
based on the same algorithm as 'PASSWORD()'.

The syntax rules for 'CREATE TABLE ... PARTITION BY KEY' are similar to
those for creating a table that is partitioned by hash.  The major
differences are listed here:

   * 'KEY' is used rather than 'HASH'.

   * 'KEY' takes only a list of zero or more column names.  Any columns
     used as the partitioning key must comprise part or all of the
     table's primary key, if the table has one.  Where no column name is
     specified as the partitioning key, the table's primary key is used,
     if there is one.  For example, the following 'CREATE TABLE'
     statement is valid in MySQL 5.7:

          CREATE TABLE k1 (
              id INT NOT NULL PRIMARY KEY,
              name VARCHAR(20)
          )
          PARTITION BY KEY()
          PARTITIONS 2;

     If there is no primary key but there is a unique key, then the
     unique key is used for the partitioning key:

          CREATE TABLE k1 (
              id INT NOT NULL,
              name VARCHAR(20),
              UNIQUE KEY (id)
          )
          PARTITION BY KEY()
          PARTITIONS 2;

     However, if the unique key column were not defined as 'NOT NULL',
     then the previous statement would fail.

     In both of these cases, the partitioning key is the 'id' column,
     even though it is not shown in the output of 'SHOW CREATE TABLE'
     or in the 'PARTITION_EXPRESSION' column
     of the 'INFORMATION_SCHEMA.PARTITIONS'.
     table.

     Unlike the case with other partitioning types, columns used for
     partitioning by 'KEY' are not restricted to integer or 'NULL'
     values.  For example, the following 'CREATE TABLE'
     statement is valid:

          CREATE TABLE tm1 (
              s1 CHAR(32) PRIMARY KEY
          )
          PARTITION BY KEY(s1)
          PARTITIONS 10;

     The preceding statement would _not_ be valid, were a different
     partitioning type to be specified.  (In this case, simply using
     'PARTITION BY KEY()' would also be valid and have the same effect
     as 'PARTITION BY KEY(s1)', since 's1' is the table's primary key.)

     For additional information about this issue, see
     partitioning-limitations.

     *Note*:

     Tables using the 'NDB' storage engine are
     implicitly partitioned by 'KEY', again using the table's primary
     key as the partitioning key.  In the event that the NDB Cluster
     table has no explicit primary key, the 'hidden' primary key
     generated by the 'NDB' storage engine for
     each NDB Cluster table is used as the partitioning key.

     If you define an explicit partitioning scheme for an 'NDB'
     table, the table must have an explicit primary key,
     and any columns used in the partitioning expression must be part of
     this key.  However, if the table uses an 'empty' partitioning
     expression--that is, 'PARTITION BY KEY()' with no column
     references--then no explicit primary key is required.

     You can observe this partitioning using the 'ndb_desc'
     utility (with the '-p' option).

     *Important*:

     For a key-partitioned table, you cannot execute an 'ALTER TABLE
     DROP PRIMARY KEY', as doing so generates the error 'ERROR 1466
     (HY000): Field in list of fields for partition function not found
     in table'.  This is not an issue for NDB Cluster tables which are
     partitioned by 'KEY'; in such cases, the table is reorganized using
     the 'hidden' primary key as the table's new partitioning key.  See
     mysql-cluster.

It is also possible to partition a table by linear key.  Here is a
simple example:

     CREATE TABLE tk (
         col1 INT NOT NULL,
         col2 CHAR(5),
         col3 DATE
     )
     PARTITION BY LINEAR KEY (col1)
     PARTITIONS 3;

Using 'LINEAR' has the same effect on 'KEY' partitioning as it does on
'HASH' partitioning, with the partition number being derived using a
powers-of-two algorithm rather than modulo arithmetic.  See
partitioning-linear-hash, for a description of this algorithm and its
implications.

22.2.6 Subpartitioning
----------------------

Subpartitioning--also known as _composite partitioning_--is the further
division of each partition in a partitioned table.  Consider the
following 'CREATE TABLE' statement:

     CREATE TABLE ts (id INT, purchased DATE)
         PARTITION BY RANGE( YEAR(purchased) )
         SUBPARTITION BY HASH( TO_DAYS(purchased) )
         SUBPARTITIONS 2 (
             PARTITION p0 VALUES LESS THAN (1990),
             PARTITION p1 VALUES LESS THAN (2000),
             PARTITION p2 VALUES LESS THAN MAXVALUE
         );

Table 'ts' has 3 'RANGE' partitions.  Each of these partitions--'p0',
'p1', and 'p2'--is further divided into 2 subpartitions.  In effect, the
entire table is divided into '3 * 2 = 6' partitions.  However, due to
the action of the 'PARTITION BY RANGE' clause, the first 2 of these
store only those records with a value less than 1990 in the 'purchased'
column.

In MySQL 5.7, it is possible to subpartition tables that are partitioned
by 'RANGE' or 'LIST'.  Subpartitions may use either 'HASH' or 'KEY'
partitioning.  This is also known as _composite partitioning_.

*Note*:

'SUBPARTITION BY HASH' and 'SUBPARTITION BY KEY' generally follow the
same syntax rules as 'PARTITION BY HASH' and 'PARTITION BY KEY',
respectively.  An exception to this is that 'SUBPARTITION BY KEY'
(unlike 'PARTITION BY KEY') does not currently support a default column,
so the column used for this purpose must be specified, even if the table
has an explicit primary key.  This is a known issue which we are working
to address; see partitioning-limitations-subpartitions, for more
information and an example.

It is also possible to define subpartitions explicitly using
'SUBPARTITION' clauses to specify options for individual subpartitions.
For example, a more verbose fashion of creating the same table 'ts' as
shown in the previous example would be:

     CREATE TABLE ts (id INT, purchased DATE)
         PARTITION BY RANGE( YEAR(purchased) )
         SUBPARTITION BY HASH( TO_DAYS(purchased) ) (
             PARTITION p0 VALUES LESS THAN (1990) (
                 SUBPARTITION s0,
                 SUBPARTITION s1
             ),
             PARTITION p1 VALUES LESS THAN (2000) (
                 SUBPARTITION s2,
                 SUBPARTITION s3
             ),
             PARTITION p2 VALUES LESS THAN MAXVALUE (
                 SUBPARTITION s4,
                 SUBPARTITION s5
             )
         );

Some syntactical items of note are listed here:

   * Each partition must have the same number of subpartitions.

   * If you explicitly define any subpartitions using 'SUBPARTITION' on
     any partition of a partitioned table, you must define them all.  In
     other words, the following statement will fail:

          CREATE TABLE ts (id INT, purchased DATE)
              PARTITION BY RANGE( YEAR(purchased) )
              SUBPARTITION BY HASH( TO_DAYS(purchased) ) (
                  PARTITION p0 VALUES LESS THAN (1990) (
                      SUBPARTITION s0,
                      SUBPARTITION s1
                  ),
                  PARTITION p1 VALUES LESS THAN (2000),
                  PARTITION p2 VALUES LESS THAN MAXVALUE (
                      SUBPARTITION s2,
                      SUBPARTITION s3
                  )
              );

     This statement would still fail even if it included a
     'SUBPARTITIONS 2' clause.

   * Each 'SUBPARTITION' clause must include (at a minimum) a name for
     the subpartition.  Otherwise, you may set any desired option for
     the subpartition or allow it to assume its default setting for that
     option.

   * Subpartition names must be unique across the entire table.  For
     example, the following 'CREATE TABLE'.
     statement is valid in MySQL 5.7:

          CREATE TABLE ts (id INT, purchased DATE)
              PARTITION BY RANGE( YEAR(purchased) )
              SUBPARTITION BY HASH( TO_DAYS(purchased) ) (
                  PARTITION p0 VALUES LESS THAN (1990) (
                      SUBPARTITION s0,
                      SUBPARTITION s1
                  ),
                  PARTITION p1 VALUES LESS THAN (2000) (
                      SUBPARTITION s2,
                      SUBPARTITION s3
                  ),
                  PARTITION p2 VALUES LESS THAN MAXVALUE (
                      SUBPARTITION s4,
                      SUBPARTITION s5
                  )
              );

Subpartitions can be used with especially large 'MyISAM'
tables to distribute data and indexes across many
disks.  Suppose that you have 6 disks mounted as '/disk0', '/disk1',
'/disk2', and so on.  Now consider the following example:

     CREATE TABLE ts (id INT, purchased DATE)
         ENGINE = MYISAM
         PARTITION BY RANGE( YEAR(purchased) )
         SUBPARTITION BY HASH( TO_DAYS(purchased) ) (
             PARTITION p0 VALUES LESS THAN (1990) (
                 SUBPARTITION s0
                     DATA DIRECTORY = '/disk0/data'
                     INDEX DIRECTORY = '/disk0/idx',
                 SUBPARTITION s1
                     DATA DIRECTORY = '/disk1/data'
                     INDEX DIRECTORY = '/disk1/idx'
             ),
             PARTITION p1 VALUES LESS THAN (2000) (
                 SUBPARTITION s2
                     DATA DIRECTORY = '/disk2/data'
                     INDEX DIRECTORY = '/disk2/idx',
                 SUBPARTITION s3
                     DATA DIRECTORY = '/disk3/data'
                     INDEX DIRECTORY = '/disk3/idx'
             ),
             PARTITION p2 VALUES LESS THAN MAXVALUE (
                 SUBPARTITION s4
                     DATA DIRECTORY = '/disk4/data'
                     INDEX DIRECTORY = '/disk4/idx',
                 SUBPARTITION s5
                     DATA DIRECTORY = '/disk5/data'
                     INDEX DIRECTORY = '/disk5/idx'
             )
         );

In this case, a separate disk is used for the data and for the indexes
of each 'RANGE'.  Many other variations are possible; another example
might be:

     CREATE TABLE ts (id INT, purchased DATE)
         ENGINE = MYISAM
         PARTITION BY RANGE(YEAR(purchased))
         SUBPARTITION BY HASH( TO_DAYS(purchased) ) (
             PARTITION p0 VALUES LESS THAN (1990) (
                 SUBPARTITION s0a
                     DATA DIRECTORY = '/disk0'
                     INDEX DIRECTORY = '/disk1',
                 SUBPARTITION s0b
                     DATA DIRECTORY = '/disk2'
                     INDEX DIRECTORY = '/disk3'
             ),
             PARTITION p1 VALUES LESS THAN (2000) (
                 SUBPARTITION s1a
                     DATA DIRECTORY = '/disk4/data'
                     INDEX DIRECTORY = '/disk4/idx',
                 SUBPARTITION s1b
                     DATA DIRECTORY = '/disk5/data'
                     INDEX DIRECTORY = '/disk5/idx'
             ),
             PARTITION p2 VALUES LESS THAN MAXVALUE (
                 SUBPARTITION s2a,
                 SUBPARTITION s2b
             )
         );

Here, the storage is as follows:

   * Rows with 'purchased' dates from before 1990 take up a vast amount
     of space, so are split up 4 ways, with a separate disk dedicated to
     the data and to the indexes for each of the two subpartitions
     ('s0a' and 's0b') making up partition 'p0'.  In other words:

        * The data for subpartition 's0a' is stored on '/disk0'.

        * The indexes for subpartition 's0a' are stored on '/disk1'.

        * The data for subpartition 's0b' is stored on '/disk2'.

        * The indexes for subpartition 's0b' are stored on '/disk3'.

   * Rows containing dates ranging from 1990 to 1999 (partition 'p1') do
     not require as much room as those from before 1990.  These are
     split between 2 disks ('/disk4' and '/disk5') rather than 4 disks
     as with the legacy records stored in 'p0':

        * Data and indexes belonging to 'p1''s first subpartition
          ('s1a') are stored on '/disk4'--the data in '/disk4/data', and
          the indexes in '/disk4/idx'.

        * Data and indexes belonging to 'p1''s second subpartition
          ('s1b') are stored on '/disk5'--the data in '/disk5/data', and
          the indexes in '/disk5/idx'.

   * Rows reflecting dates from the year 2000 to the present (partition
     'p2') do not take up as much space as required by either of the two
     previous ranges.  Currently, it is sufficient to store all of these
     in the default location.

     In future, when the number of purchases for the decade beginning
     with the year 2000 grows to a point where the default location no
     longer provides sufficient space, the corresponding rows can be
     moved using an 'ALTER TABLE ... REORGANIZE PARTITION' statement.
     See partitioning-management, for an explanation of how this
     can be done.

The 'DATA DIRECTORY' and 'INDEX DIRECTORY' options are not permitted in
partition definitions when the 'NO_DIR_IN_CREATE' server SQL mode is in
effect.  In MySQL 5.7, these options are also not permitted when
defining subpartitions (Bug #42954).

22.2.7 How MySQL Partitioning Handles NULL
------------------------------------------

Partitioning in MySQL does nothing to disallow 'NULL' as the value of a
partitioning expression, whether it is a column value or the value of a
user-supplied expression.  Even though it is permitted to use 'NULL' as
the value of an expression that must otherwise yield an integer, it is
important to keep in mind that 'NULL' is not a number.  MySQL's
partitioning implementation treats 'NULL' as being less than any
non-'NULL' value, just as 'ORDER BY' does.

This means that treatment of 'NULL' varies between partitioning of
different types, and may produce behavior which you do not expect if you
are not prepared for it.  This being the case, we discuss in this
section how each MySQL partitioning type handles 'NULL' values when
determining the partition in which a row should be stored, and provide
examples for each.

Handling of NULL with RANGE partitioning

If you insert a row into a table partitioned by 'RANGE' such that the
column value used to determine the partition is 'NULL', the row is
inserted into the lowest partition.  Consider these two tables in a
database named 'p', created as follows:

     mysql> CREATE TABLE t1 (
         ->     c1 INT,
         ->     c2 VARCHAR(20)
         -> )
         -> PARTITION BY RANGE(c1) (
         ->     PARTITION p0 VALUES LESS THAN (0),
         ->     PARTITION p1 VALUES LESS THAN (10),
         ->     PARTITION p2 VALUES LESS THAN MAXVALUE
         -> );
     Query OK, 0 rows affected (0.09 sec)

     mysql> CREATE TABLE t2 (
         ->     c1 INT,
         ->     c2 VARCHAR(20)
         -> )
         -> PARTITION BY RANGE(c1) (
         ->     PARTITION p0 VALUES LESS THAN (-5),
         ->     PARTITION p1 VALUES LESS THAN (0),
         ->     PARTITION p2 VALUES LESS THAN (10),
         ->     PARTITION p3 VALUES LESS THAN MAXVALUE
         -> );
     Query OK, 0 rows affected (0.09 sec)

You can see the partitions created by these two 'CREATE TABLE'
statements using the following query against the
'PARTITIONS' table in the 'INFORMATION_SCHEMA'
database:

     mysql> SELECT TABLE_NAME, PARTITION_NAME, TABLE_ROWS, AVG_ROW_LENGTH, DATA_LENGTH
          >   FROM INFORMATION_SCHEMA.PARTITIONS
          >   WHERE TABLE_SCHEMA = 'p' AND TABLE_NAME LIKE 't_';
     +------------+----------------+------------+----------------+-------------+
     | TABLE_NAME | PARTITION_NAME | TABLE_ROWS | AVG_ROW_LENGTH | DATA_LENGTH |
     +------------+----------------+------------+----------------+-------------+
     | t1         | p0             |          0 |              0 |           0 |
     | t1         | p1             |          0 |              0 |           0 |
     | t1         | p2             |          0 |              0 |           0 |
     | t2         | p0             |          0 |              0 |           0 |
     | t2         | p1             |          0 |              0 |           0 |
     | t2         | p2             |          0 |              0 |           0 |
     | t2         | p3             |          0 |              0 |           0 |
     +------------+----------------+------------+----------------+-------------+
     7 rows in set (0.00 sec)

(For more information about this table, see partitions-table.)
Now let us populate each of these tables with a single row containing a
'NULL' in the column used as the partitioning key, and verify that the
rows were inserted using a pair of 'SELECT' statements:

     mysql> INSERT INTO t1 VALUES (NULL, 'mothra');
     Query OK, 1 row affected (0.00 sec)

     mysql> INSERT INTO t2 VALUES (NULL, 'mothra');
     Query OK, 1 row affected (0.00 sec)

     mysql> SELECT * FROM t1;
     +------+--------+
     | id   | name   |
     +------+--------+
     | NULL | mothra |
     +------+--------+
     1 row in set (0.00 sec)

     mysql> SELECT * FROM t2;
     +------+--------+
     | id   | name   |
     +------+--------+
     | NULL | mothra |
     +------+--------+
     1 row in set (0.00 sec)

You can see which partitions are used to store the inserted rows by
rerunning the previous query against
'INFORMATION_SCHEMA.PARTITIONS' and inspecting the
output:

     mysql> SELECT TABLE_NAME, PARTITION_NAME, TABLE_ROWS, AVG_ROW_LENGTH, DATA_LENGTH
          >   FROM INFORMATION_SCHEMA.PARTITIONS
          >   WHERE TABLE_SCHEMA = 'p' AND TABLE_NAME LIKE 't_';
     +------------+----------------+------------+----------------+-------------+
     | TABLE_NAME | PARTITION_NAME | TABLE_ROWS | AVG_ROW_LENGTH | DATA_LENGTH |
     +------------+----------------+------------+----------------+-------------+
     _| t1         | p0             |          1 |             20 |          20 |_
     | t1         | p1             |          0 |              0 |           0 |
     | t1         | p2             |          0 |              0 |           0 |
     _| t2         | p0             |          1 |             20 |          20 |_
     | t2         | p1             |          0 |              0 |           0 |
     | t2         | p2             |          0 |              0 |           0 |
     | t2         | p3             |          0 |              0 |           0 |
     +------------+----------------+------------+----------------+-------------+
     7 rows in set (0.01 sec)

You can also demonstrate that these rows were stored in the lowest
partition of each table by dropping these partitions, and then
re-running the 'SELECT' statements:

     mysql> ALTER TABLE t1 DROP PARTITION p0;
     Query OK, 0 rows affected (0.16 sec)

     mysql> ALTER TABLE t2 DROP PARTITION p0;
     Query OK, 0 rows affected (0.16 sec)

     mysql> SELECT * FROM t1;
     Empty set (0.00 sec)

     mysql> SELECT * FROM t2;
     Empty set (0.00 sec)

(For more information on 'ALTER TABLE ... DROP PARTITION', see
alter-table.)

'NULL' is also treated in this way for partitioning expressions that use
SQL functions.  Suppose that we define a table using a 'CREATE TABLE'
statement such as this one:

     CREATE TABLE tndate (
         id INT,
         dt DATE
     )
     PARTITION BY RANGE( YEAR(dt) ) (
         PARTITION p0 VALUES LESS THAN (1990),
         PARTITION p1 VALUES LESS THAN (2000),
         PARTITION p2 VALUES LESS THAN MAXVALUE
     );

As with other MySQL functions, 'YEAR(NULL)' returns 'NULL'.  A row with
a 'dt' column value of 'NULL' is treated as though the partitioning
expression evaluated to a value less than any other value, and so is
inserted into partition 'p0'.

Handling of NULL with LIST partitioning

A table that is partitioned by 'LIST' admits 'NULL' values if and only
if one of its partitions is defined using that value-list that contains
'NULL'.  The converse of this is that a table partitioned by 'LIST'
which does not explicitly use 'NULL' in a value list rejects rows
resulting in a 'NULL' value for the partitioning expression, as shown in
this example:

     mysql> CREATE TABLE ts1 (
         ->     c1 INT,
         ->     c2 VARCHAR(20)
         -> )
         -> PARTITION BY LIST(c1) (
         ->     PARTITION p0 VALUES IN (0, 3, 6),
         ->     PARTITION p1 VALUES IN (1, 4, 7),
         ->     PARTITION p2 VALUES IN (2, 5, 8)
         -> );
     Query OK, 0 rows affected (0.01 sec)

     mysql> INSERT INTO ts1 VALUES (9, 'mothra');
     ERROR 1504 (HY000): Table has no partition for value 9

     mysql> INSERT INTO ts1 VALUES (NULL, 'mothra');
     ERROR 1504 (HY000): Table has no partition for value NULL

Only rows having a 'c1' value between '0' and '8' inclusive can be
inserted into 'ts1'.  'NULL' falls outside this range, just like the
number '9'.  We can create tables 'ts2' and 'ts3' having value lists
containing 'NULL', as shown here:

     mysql> CREATE TABLE ts2 (
         ->     c1 INT,
         ->     c2 VARCHAR(20)
         -> )
         -> PARTITION BY LIST(c1) (
         ->     PARTITION p0 VALUES IN (0, 3, 6),
         ->     PARTITION p1 VALUES IN (1, 4, 7),
         ->     PARTITION p2 VALUES IN (2, 5, 8),
         ->     PARTITION p3 VALUES IN (NULL)
         -> );
     Query OK, 0 rows affected (0.01 sec)

     mysql> CREATE TABLE ts3 (
         ->     c1 INT,
         ->     c2 VARCHAR(20)
         -> )
         -> PARTITION BY LIST(c1) (
         ->     PARTITION p0 VALUES IN (0, 3, 6),
         ->     PARTITION p1 VALUES IN (1, 4, 7, NULL),
         ->     PARTITION p2 VALUES IN (2, 5, 8)
         -> );
     Query OK, 0 rows affected (0.01 sec)

When defining value lists for partitioning, you can (and should) treat
'NULL' just as you would any other value.  For example, both 'VALUES IN
(NULL)' and 'VALUES IN (1, 4, 7, NULL)' are valid, as are 'VALUES IN (1,
NULL, 4, 7)', 'VALUES IN (NULL, 1, 4, 7)', and so on.  You can insert a
row having 'NULL' for column 'c1' into each of the tables 'ts2' and
'ts3':

     mysql> INSERT INTO ts2 VALUES (NULL, 'mothra');
     Query OK, 1 row affected (0.00 sec)

     mysql> INSERT INTO ts3 VALUES (NULL, 'mothra');
     Query OK, 1 row affected (0.00 sec)

By issuing the appropriate query against
'INFORMATION_SCHEMA.PARTITIONS', you can determine
which partitions were used to store the rows just inserted (we assume,
as in the previous examples, that the partitioned tables were created in
the 'p' database):

     mysql> SELECT TABLE_NAME, PARTITION_NAME, TABLE_ROWS, AVG_ROW_LENGTH, DATA_LENGTH
          >   FROM INFORMATION_SCHEMA.PARTITIONS
          >   WHERE TABLE_SCHEMA = 'p' AND TABLE_NAME LIKE 'ts_';
     +------------+----------------+------------+----------------+-------------+
     | TABLE_NAME | PARTITION_NAME | TABLE_ROWS | AVG_ROW_LENGTH | DATA_LENGTH |
     +------------+----------------+------------+----------------+-------------+
     | ts2        | p0             |          0 |              0 |           0 |
     | ts2        | p1             |          0 |              0 |           0 |
     | ts2        | p2             |          0 |              0 |           0 |
     _| ts2        | p3             |          1 |             20 |          20 |_
     | ts3        | p0             |          0 |              0 |           0 |
     _| ts3        | p1             |          1 |             20 |          20 |_
     | ts3        | p2             |          0 |              0 |           0 |
     +------------+----------------+------------+----------------+-------------+
     7 rows in set (0.01 sec)

As shown earlier in this section, you can also verify which partitions
were used for storing the rows by deleting these partitions and then
performing a 'SELECT'.

Handling of NULL with HASH and KEY partitioning

'NULL' is handled somewhat differently for tables partitioned by 'HASH'
or 'KEY'.  In these cases, any partition expression that yields a 'NULL'
value is treated as though its return value were zero.  We can verify
this behavior by examining the effects on the file system of creating a
table partitioned by 'HASH' and populating it with a record containing
appropriate values.  Suppose that you have a table 'th' (also in the 'p'
database) created using the following statement:

     mysql> CREATE TABLE th (
         ->     c1 INT,
         ->     c2 VARCHAR(20)
         -> )
         -> PARTITION BY HASH(c1)
         -> PARTITIONS 2;
     Query OK, 0 rows affected (0.00 sec)

The partitions belonging to this table can be viewed using the query
shown here:

     mysql> SELECT TABLE_NAME,PARTITION_NAME,TABLE_ROWS,AVG_ROW_LENGTH,DATA_LENGTH
          >   FROM INFORMATION_SCHEMA.PARTITIONS
          >   WHERE TABLE_SCHEMA = 'p' AND TABLE_NAME ='th';
     +------------+----------------+------------+----------------+-------------+
     | TABLE_NAME | PARTITION_NAME | TABLE_ROWS | AVG_ROW_LENGTH | DATA_LENGTH |
     +------------+----------------+------------+----------------+-------------+
     | th         | p0             |          0 |              0 |           0 |
     | th         | p1             |          0 |              0 |           0 |
     +------------+----------------+------------+----------------+-------------+
     2 rows in set (0.00 sec)

'TABLE_ROWS' for each partition is 0.  Now insert two rows into 'th'
whose 'c1' column values are 'NULL' and 0, and verify that these rows
were inserted, as shown here:

     mysql> INSERT INTO th VALUES (NULL, 'mothra'), (0, 'gigan');
     Query OK, 1 row affected (0.00 sec)

     mysql> SELECT * FROM th;
     +------+---------+
     | c1   | c2      |
     +------+---------+
     | NULL | mothra  |
     +------+---------+
     |    0 | gigan   |
     +------+---------+
     2 rows in set (0.01 sec)

Recall that for any integer N, the value of 'NULL MOD N' is always
'NULL'.  For tables that are partitioned by 'HASH' or 'KEY', this result
is treated for determining the correct partition as '0'.  Checking the
'INFORMATION_SCHEMA.PARTITIONS' table once
again, we can see that both rows were inserted into partition 'p0':

     mysql> SELECT TABLE_NAME, PARTITION_NAME, TABLE_ROWS, AVG_ROW_LENGTH, DATA_LENGTH
          >   FROM INFORMATION_SCHEMA.PARTITIONS
          >   WHERE TABLE_SCHEMA = 'p' AND TABLE_NAME ='th';
     +------------+----------------+------------+----------------+-------------+
     | TABLE_NAME | PARTITION_NAME | TABLE_ROWS | AVG_ROW_LENGTH | DATA_LENGTH |
     +------------+----------------+------------+----------------+-------------+
     _| th         | p0             |          2 |             20 |          20 |_
     | th         | p1             |          0 |              0 |           0 |
     +------------+----------------+------------+----------------+-------------+
     2 rows in set (0.00 sec)

By repeating the last example using 'PARTITION BY KEY' in place of
'PARTITION BY HASH' in the definition of the table, you can verify that
'NULL' is also treated like 0 for this type of partitioning.

22.3 Partition Management
=========================

MySQL 5.7 provides a number of ways to modify partitioned tables.  It is
possible to add, drop, redefine, merge, or split existing partitions.
All of these actions can be carried out using the partitioning
extensions to the 'ALTER TABLE'.
statement.  There are also ways to obtain information about partitioned
tables and partitions.  We discuss these topics in the sections that
follow.

   * For information about partition management in tables partitioned by
     'RANGE' or 'LIST', see partitioning-management-range-list.

   * For a discussion of managing 'HASH' and 'KEY' partitions, see
     partitioning-management-hash-key.

   * See partitioning-info, for a discussion of mechanisms
     provided in MySQL 5.7 for obtaining information about partitioned
     tables and partitions.

   * For a discussion of performing maintenance operations on
     partitions, see partitioning-maintenance.

*Note*:

In MySQL 5.7, all partitions of a partitioned table must have the same
number of subpartitions, and it is not possible to change the
subpartitioning once the table has been created.

To change a table's partitioning scheme, it is necessary only to use the
'ALTER TABLE' statement with a
PARTITION_OPTIONS clause.  This clause has the same syntax as that as
used with 'CREATE TABLE' for creating a partitioned
table, and always begins with the keywords 'PARTITION BY'.  Suppose that
you have a table partitioned by range using the following 'CREATE TABLE'
statement:

     CREATE TABLE trb3 (id INT, name VARCHAR(50), purchased DATE)
         PARTITION BY RANGE( YEAR(purchased) ) (
             PARTITION p0 VALUES LESS THAN (1990),
             PARTITION p1 VALUES LESS THAN (1995),
             PARTITION p2 VALUES LESS THAN (2000),
             PARTITION p3 VALUES LESS THAN (2005)
         );

To repartition this table so that it is partitioned by key into two
partitions using the 'id' column value as the basis for the key, you can
use this statement:

     ALTER TABLE trb3 PARTITION BY KEY(id) PARTITIONS 2;

This has the same effect on the structure of the table as dropping the
table and re-creating it using 'CREATE TABLE trb3 PARTITION BY KEY(id)
PARTITIONS 2;'.

'ALTER TABLE ... ENGINE = ...' changes only the storage engine used by
the table, and leaves the table's partitioning scheme intact.  Use
'ALTER TABLE ... REMOVE PARTITIONING' to remove a table's partitioning.
See alter-table.

*Important*:

Only a single 'PARTITION BY', 'ADD PARTITION', 'DROP PARTITION',
'REORGANIZE PARTITION', or 'COALESCE PARTITION' clause can be used in a
given 'ALTER TABLE' statement.
If you (for example) wish to drop a partition and reorganize a table's
remaining partitions, you must do so in two separate 'ALTER TABLE'
statements (one using 'DROP
PARTITION' and then a second one using 'REORGANIZE PARTITION').

In MySQL 5.7, it is possible to delete all rows from one or more
selected partitions using 'ALTER TABLE ... TRUNCATE PARTITION'.

22.3.1 Management of RANGE and LIST Partitions
----------------------------------------------

Adding and dropping of range and list partitions are handled in a
similar fashion, so we discuss the management of both sorts of
partitioning in this section.  For information about working with tables
that are partitioned by hash or key, see
partitioning-management-hash-key.

Dropping a partition from a table that is partitioned by either 'RANGE'
or by 'LIST' can be accomplished using the 'ALTER TABLE'
statement with the 'DROP PARTITION'
option.  Suppose that you have created a table that is partitioned by
range and then populated with 10 records using the following
'CREATE TABLE' and 'INSERT' statements:

     mysql> CREATE TABLE tr (id INT, name VARCHAR(50), purchased DATE)
         ->     PARTITION BY RANGE( YEAR(purchased) ) (
         ->         PARTITION p0 VALUES LESS THAN (1990),
         ->         PARTITION p1 VALUES LESS THAN (1995),
         ->         PARTITION p2 VALUES LESS THAN (2000),
         ->         PARTITION p3 VALUES LESS THAN (2005),
         ->         PARTITION p4 VALUES LESS THAN (2010),
         ->         PARTITION p5 VALUES LESS THAN (2015)
         ->     );
     Query OK, 0 rows affected (0.28 sec)

     mysql> INSERT INTO tr VALUES
         ->     (1, 'desk organiser', '2003-10-15'),
         ->     (2, 'alarm clock', '1997-11-05'),
         ->     (3, 'chair', '2009-03-10'),
         ->     (4, 'bookcase', '1989-01-10'),
         ->     (5, 'exercise bike', '2014-05-09'),
         ->     (6, 'sofa', '1987-06-05'),
         ->     (7, 'espresso maker', '2011-11-22'),
         ->     (8, 'aquarium', '1992-08-04'),
         ->     (9, 'study desk', '2006-09-16'),
         ->     (10, 'lava lamp', '1998-12-25');
     Query OK, 10 rows affected (0.05 sec)
     Records: 10  Duplicates: 0  Warnings: 0

You can see which items should have been inserted into partition 'p2' as
shown here:

     mysql> SELECT * FROM tr
         ->     WHERE purchased BETWEEN '1995-01-01' AND '1999-12-31';
     +------+-------------+------------+
     | id   | name        | purchased  |
     +------+-------------+------------+
     |    2 | alarm clock | 1997-11-05 |
     |   10 | lava lamp   | 1998-12-25 |
     +------+-------------+------------+
     2 rows in set (0.00 sec)

You can also get this information using partition selection, as shown
here:

     mysql> SELECT * FROM tr PARTITION (p2);
     +------+-------------+------------+
     | id   | name        | purchased  |
     +------+-------------+------------+
     |    2 | alarm clock | 1997-11-05 |
     |   10 | lava lamp   | 1998-12-25 |
     +------+-------------+------------+
     2 rows in set (0.00 sec)

See partitioning-selection, for more information.

To drop the partition named 'p2', execute the following command:

     mysql> ALTER TABLE tr DROP PARTITION p2;
     Query OK, 0 rows affected (0.03 sec)

*Note*:

The 'NDBCLUSTER' storage engine does not support
'ALTER TABLE ... DROP PARTITION'.  It does, however, support the other
partitioning-related extensions to 'ALTER TABLE'
that are described in this chapter.

It is very important to remember that, _when you drop a partition, you
also delete all the data that was stored in that partition_.  You can
see that this is the case by re-running the previous 'SELECT'
query:

     mysql> SELECT * FROM tr WHERE purchased
         -> BETWEEN '1995-01-01' AND '1999-12-31';
     Empty set (0.00 sec)

Because of this, you must have the 'DROP' privilege for a table before
you can execute 'ALTER TABLE ... DROP PARTITION' on that table.

If you wish to drop all data from all partitions while preserving the
table definition and its partitioning scheme, use the 'TRUNCATE TABLE'
statement.  (See truncate-table.)

If you intend to change the partitioning of a table _without_ losing
data, use 'ALTER TABLE ... REORGANIZE PARTITION' instead.  See below or
in alter-table, for information about 'REORGANIZE PARTITION'.

If you now execute a 'SHOW CREATE TABLE'.
statement, you can see how the partitioning makeup of the table has been
changed:

     mysql> SHOW CREATE TABLE tr\G
     *************************** 1. row ***************************
            Table: tr
     Create Table: CREATE TABLE `tr` (
       `id` int(11) DEFAULT NULL,
       `name` varchar(50) DEFAULT NULL,
       `purchased` date DEFAULT NULL
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1
     /*!50100 PARTITION BY RANGE ( YEAR(purchased))
     (PARTITION p0 VALUES LESS THAN (1990) ENGINE = InnoDB,
      PARTITION p1 VALUES LESS THAN (1995) ENGINE = InnoDB,
      PARTITION p3 VALUES LESS THAN (2005) ENGINE = InnoDB,
      PARTITION p4 VALUES LESS THAN (2010) ENGINE = InnoDB,
      PARTITION p5 VALUES LESS THAN (2015) ENGINE = InnoDB) */
     1 row in set (0.00 sec)

When you insert new rows into the changed table with 'purchased' column
values between ''1995-01-01'' and ''2004-12-31'' inclusive, those rows
will be stored in partition 'p3'.  You can verify this as follows:

     mysql> INSERT INTO tr VALUES (11, 'pencil holder', '1995-07-12');
     Query OK, 1 row affected (0.00 sec)

     mysql> SELECT * FROM tr WHERE purchased
         -> BETWEEN '1995-01-01' AND '2004-12-31';
     +------+----------------+------------+
     | id   | name           | purchased  |
     +------+----------------+------------+
     |    1 | desk organiser | 2003-10-15 |
     |   11 | pencil holder  | 1995-07-12 |
     +------+----------------+------------+
     2 rows in set (0.00 sec)

     mysql> ALTER TABLE tr DROP PARTITION p3;
     Query OK, 0 rows affected (0.03 sec)

     mysql> SELECT * FROM tr WHERE purchased
         -> BETWEEN '1995-01-01' AND '2004-12-31';
     Empty set (0.00 sec)

The number of rows dropped from the table as a result of 'ALTER TABLE
... DROP PARTITION' is not reported by the server as it would be by the
equivalent 'DELETE' query.

Dropping 'LIST' partitions uses exactly the same 'ALTER TABLE ... DROP
PARTITION' syntax as used for dropping 'RANGE' partitions.  However,
there is one important difference in the effect this has on your use of
the table afterward: You can no longer insert into the table any rows
having any of the values that were included in the value list defining
the deleted partition.  (See partitioning-list, for an example.)

To add a new range or list partition to a previously partitioned table,
use the 'ALTER TABLE ... ADD PARTITION' statement.  For tables which are
partitioned by 'RANGE', this can be used to add a new range to the end
of the list of existing partitions.  Suppose that you have a partitioned
table containing membership data for your organization, which is defined
as follows:

     CREATE TABLE members (
         id INT,
         fname VARCHAR(25),
         lname VARCHAR(25),
         dob DATE
     )
     PARTITION BY RANGE( YEAR(dob) ) (
         PARTITION p0 VALUES LESS THAN (1980),
         PARTITION p1 VALUES LESS THAN (1990),
         PARTITION p2 VALUES LESS THAN (2000)
     );

Suppose further that the minimum age for members is 16.  As the calendar
approaches the end of 2015, you realize that you will soon be admitting
members who were born in 2000 (and later).  You can modify the 'members'
table to accommodate new members born in the years 2000 to 2010 as shown
here:

     ALTER TABLE members ADD PARTITION (PARTITION p3 VALUES LESS THAN (2010));

With tables that are partitioned by range, you can use 'ADD PARTITION'
to add new partitions to the high end of the partitions list only.
Trying to add a new partition in this manner between or before existing
partitions results in an error as shown here:

     mysql> ALTER TABLE members
          >     ADD PARTITION (
          >     PARTITION n VALUES LESS THAN (1970));
     ERROR 1463 (HY000): VALUES LESS THAN value must be strictly »
        increasing for each partition

You can work around this problem by reorganizing the first partition
into two new ones that split the range between them, like this:

     ALTER TABLE members
         REORGANIZE PARTITION p0 INTO (
             PARTITION n0 VALUES LESS THAN (1970),
             PARTITION n1 VALUES LESS THAN (1980)
     );

Using 'SHOW CREATE TABLE' you can see that the
'ALTER TABLE' statement has had the desired effect:

     mysql> SHOW CREATE TABLE members\G
     *************************** 1. row ***************************
            Table: members
     Create Table: CREATE TABLE `members` (
       `id` int(11) DEFAULT NULL,
       `fname` varchar(25) DEFAULT NULL,
       `lname` varchar(25) DEFAULT NULL,
       `dob` date DEFAULT NULL
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1
     /*!50100 PARTITION BY RANGE ( YEAR(dob))
     (PARTITION n0 VALUES LESS THAN (1970) ENGINE = InnoDB,
      PARTITION n1 VALUES LESS THAN (1980) ENGINE = InnoDB,
      PARTITION p1 VALUES LESS THAN (1990) ENGINE = InnoDB,
      PARTITION p2 VALUES LESS THAN (2000) ENGINE = InnoDB,
      PARTITION p3 VALUES LESS THAN (2010) ENGINE = InnoDB) */
     1 row in set (0.00 sec)

See also alter-table-partition-operations.

You can also use 'ALTER TABLE ... ADD PARTITION' to add new partitions
to a table that is partitioned by 'LIST'.  Suppose a table 'tt' is
defined using the following 'CREATE TABLE'.
statement:

     CREATE TABLE tt (
         id INT,
         data INT
     )
     PARTITION BY LIST(data) (
         PARTITION p0 VALUES IN (5, 10, 15),
         PARTITION p1 VALUES IN (6, 12, 18)
     );

You can add a new partition in which to store rows having the 'data'
column values '7', '14', and '21' as shown:

     ALTER TABLE tt ADD PARTITION (PARTITION p2 VALUES IN (7, 14, 21));

Keep in mind that you _cannot_ add a new 'LIST' partition encompassing
any values that are already included in the value list of an existing
partition.  If you attempt to do so, an error will result:

     mysql> ALTER TABLE tt ADD PARTITION
          >     (PARTITION np VALUES IN (4, 8, 12));
     ERROR 1465 (HY000): Multiple definition of same constant »
                         in list partitioning

Because any rows with the 'data' column value '12' have already been
assigned to partition 'p1', you cannot create a new partition on table
'tt' that includes '12' in its value list.  To accomplish this, you
could drop 'p1', and add 'np' and then a new 'p1' with a modified
definition.  However, as discussed earlier, this would result in the
loss of all data stored in 'p1'--and it is often the case that this is
not what you really want to do.  Another solution might appear to be to
make a copy of the table with the new partitioning and to copy the data
into it using 'CREATE TABLE ... SELECT ...', then
drop the old table and rename the new one, but this could be very
time-consuming when dealing with a large amounts of data.  This also
might not be feasible in situations where high availability is a
requirement.

You can add multiple partitions in a single 'ALTER TABLE ... ADD
PARTITION' statement as shown here:

     CREATE TABLE employees (
       id INT NOT NULL,
       fname VARCHAR(50) NOT NULL,
       lname VARCHAR(50) NOT NULL,
       hired DATE NOT NULL
     )
     PARTITION BY RANGE( YEAR(hired) ) (
       PARTITION p1 VALUES LESS THAN (1991),
       PARTITION p2 VALUES LESS THAN (1996),
       PARTITION p3 VALUES LESS THAN (2001),
       PARTITION p4 VALUES LESS THAN (2005)
     );

     ALTER TABLE employees ADD PARTITION (
         PARTITION p5 VALUES LESS THAN (2010),
         PARTITION p6 VALUES LESS THAN MAXVALUE
     );

Fortunately, MySQL's partitioning implementation provides ways to
redefine partitions without losing data.  Let us look first at a couple
of simple examples involving 'RANGE' partitioning.  Recall the 'members'
table which is now defined as shown here:

     mysql> SHOW CREATE TABLE members\G
     *************************** 1. row ***************************
            Table: members
     Create Table: CREATE TABLE `members` (
       `id` int(11) DEFAULT NULL,
       `fname` varchar(25) DEFAULT NULL,
       `lname` varchar(25) DEFAULT NULL,
       `dob` date DEFAULT NULL
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1
     /*!50100 PARTITION BY RANGE ( YEAR(dob))
     (PARTITION n0 VALUES LESS THAN (1970) ENGINE = InnoDB,
      PARTITION n1 VALUES LESS THAN (1980) ENGINE = InnoDB,
      PARTITION p1 VALUES LESS THAN (1990) ENGINE = InnoDB,
      PARTITION p2 VALUES LESS THAN (2000) ENGINE = InnoDB,
      PARTITION p3 VALUES LESS THAN (2010) ENGINE = InnoDB) */
     1 row in set (0.00 sec)

Suppose that you would like to move all rows representing members born
before 1960 into a separate partition.  As we have already seen, this
cannot be done using 'ALTER TABLE ... ADD PARTITION'.
However, you can use another
partition-related extension to 'ALTER TABLE'
to accomplish this:

     ALTER TABLE members REORGANIZE PARTITION n0 INTO (
         PARTITION s0 VALUES LESS THAN (1960),
         PARTITION s1 VALUES LESS THAN (1970)
     );

In effect, this command splits partition 'p0' into two new partitions
's0' and 's1'.  It also moves the data that was stored in 'p0' into the
new partitions according to the rules embodied in the two 'PARTITION ...
VALUES ...' clauses, so that 's0' contains only those records for which
'YEAR(dob)' is less than 1960 and 's1' contains those rows in which
'YEAR(dob)' is greater than or equal to 1960 but less than 1970.

A 'REORGANIZE PARTITION' clause may also be used for merging adjacent
partitions.  You can reverse the effect of the previous statement on the
'members' table as shown here:

     ALTER TABLE members REORGANIZE PARTITION s0,s1 INTO (
         PARTITION p0 VALUES LESS THAN (1970)
     );

No data is lost in splitting or merging partitions using 'REORGANIZE
PARTITION'.  In executing the above statement, MySQL moves all of the
records that were stored in partitions 's0' and 's1' into partition
'p0'.

The general syntax for 'REORGANIZE PARTITION' is shown here:

     ALTER TABLE TBL_NAME
         REORGANIZE PARTITION PARTITION_LIST
         INTO (PARTITION_DEFINITIONS);

Here, TBL_NAME is the name of the partitioned table, and PARTITION_LIST
is a comma-separated list of names of one or more existing partitions to
be changed.  PARTITION_DEFINITIONS is a comma-separated list of new
partition definitions, which follow the same rules as for the
PARTITION_DEFINITIONS list used in 'CREATE TABLE'.
You are not limited to merging several partitions into one, or to
splitting one partition into many, when using 'REORGANIZE PARTITION'.
For example, you can reorganize all four partitions of the 'members'
table into two, like this:

     ALTER TABLE members REORGANIZE PARTITION p0,p1,p2,p3 INTO (
         PARTITION m0 VALUES LESS THAN (1980),
         PARTITION m1 VALUES LESS THAN (2000)
     );

You can also use 'REORGANIZE PARTITION' with tables that are partitioned
by 'LIST'.  Let us return to the problem of adding a new partition to
the list-partitioned 'tt' table and failing because the new partition
had a value that was already present in the value-list of one of the
existing partitions.  We can handle this by adding a partition that
contains only nonconflicting values, and then reorganizing the new
partition and the existing one so that the value which was stored in the
existing one is now moved to the new one:

     ALTER TABLE tt ADD PARTITION (PARTITION np VALUES IN (4, 8));
     ALTER TABLE tt REORGANIZE PARTITION p1,np INTO (
         PARTITION p1 VALUES IN (6, 18),
         PARTITION np VALUES in (4, 8, 12)
     );

Here are some key points to keep in mind when using 'ALTER TABLE ...
REORGANIZE PARTITION' to repartition tables that are partitioned by
'RANGE' or 'LIST':

   * The 'PARTITION' options used to determine the new partitioning
     scheme are subject to the same rules as those used with a
     'CREATE TABLE' statement.

     A new 'RANGE' partitioning scheme cannot have any overlapping
     ranges; a new 'LIST' partitioning scheme cannot have any
     overlapping sets of values.

   * The combination of partitions in the PARTITION_DEFINITIONS list
     should account for the same range or set of values overall as the
     combined partitions named in the PARTITION_LIST.

     For example, partitions 'p1' and 'p2' together cover the years 1980
     through 1999 in the 'members' table used as an example in this
     section.  Any reorganization of these two partitions should cover
     the same range of years overall.

   * For tables partitioned by 'RANGE', you can reorganize only adjacent
     partitions; you cannot skip over range partitions.

     For instance, you could not reorganize the example 'members' table
     using a statement beginning with 'ALTER TABLE members REORGANIZE
     PARTITION p0,p2 INTO ...' because 'p0' covers the years prior to
     1970 and 'p2' the years from 1990 through 1999 inclusive, so these
     are not adjacent partitions.  (You cannot skip partition 'p1' in
     this case.)

   * You cannot use 'REORGANIZE PARTITION' to change the type of
     partitioning used by the table; for example, you cannot change
     'RANGE' partitions to 'HASH' partitions or the reverse.  You also
     cannot use this statement to change the partitioning expression or
     column.  To accomplish either of these tasks without dropping and
     re-creating the table, you can use 'ALTER TABLE ... PARTITION BY ...',
     as shown here:

          ALTER TABLE members
              PARTITION BY HASH( YEAR(dob) )
              PARTITIONS 8;

22.3.2 Management of HASH and KEY Partitions
--------------------------------------------

Tables which are partitioned by hash or by key are very similar to one
another with regard to making changes in a partitioning setup, and both
differ in a number of ways from tables which have been partitioned by
range or list.  For that reason, this section addresses the modification
of tables partitioned by hash or by key only.  For a discussion of
adding and dropping of partitions of tables that are partitioned by
range or list, see partitioning-management-range-list.

You cannot drop partitions from tables that are partitioned by 'HASH' or
'KEY' in the same way that you can from tables that are partitioned by
'RANGE' or 'LIST'.  However, you can merge 'HASH' or 'KEY' partitions
using the 'ALTER TABLE ... COALESCE PARTITION' statement.  Suppose that
you have a table containing data about clients, which is divided into
twelve partitions.  The 'clients' table is defined as shown here:

     CREATE TABLE clients (
         id INT,
         fname VARCHAR(30),
         lname VARCHAR(30),
         signed DATE
     )
     PARTITION BY HASH( MONTH(signed) )
     PARTITIONS 12;

To reduce the number of partitions from twelve to eight, execute the
following 'ALTER TABLE'.
command:

     mysql> ALTER TABLE clients COALESCE PARTITION 4;
     Query OK, 0 rows affected (0.02 sec)

'COALESCE' works equally well with tables that are partitioned by
'HASH', 'KEY', 'LINEAR HASH', or 'LINEAR KEY'.  Here is an example
similar to the previous one, differing only in that the table is
partitioned by 'LINEAR KEY':

     mysql> CREATE TABLE clients_lk (
         ->     id INT,
         ->     fname VARCHAR(30),
         ->     lname VARCHAR(30),
         ->     signed DATE
         -> )
         -> PARTITION BY LINEAR KEY(signed)
         -> PARTITIONS 12;
     Query OK, 0 rows affected (0.03 sec)

     mysql> ALTER TABLE clients_lk COALESCE PARTITION 4;
     Query OK, 0 rows affected (0.06 sec)
     Records: 0  Duplicates: 0  Warnings: 0

The number following 'COALESCE PARTITION' is the number of partitions to
merge into the remainder--in other words, it is the number of partitions
to remove from the table.

If you attempt to remove more partitions than the table has, the result
is an error like the one shown:

     mysql> ALTER TABLE clients COALESCE PARTITION 18;
     ERROR 1478 (HY000): Cannot remove all partitions, use DROP TABLE instead

To increase the number of partitions for the 'clients' table from 12 to
18.  use 'ALTER TABLE ... ADD PARTITION' as shown here:

     ALTER TABLE clients ADD PARTITION PARTITIONS 6;

22.3.3 Exchanging Partitions and Subpartitions with Tables
----------------------------------------------------------

In MySQL 5.7, it is possible to exchange a table partition or
subpartition with a table using 'ALTER TABLE PT EXCHANGE PARTITION P
WITH TABLE NT', where PT is the partitioned table and P is the partition
or subpartition of PT to be exchanged with unpartitioned table NT,
provided that the following statements are true:

  1. Table NT is not itself partitioned.

  2. Table NT is not a temporary table.

  3. The structures of tables PT and NT are otherwise identical.

  4. Table 'nt' contains no foreign key references, and no other table
     has any foreign keys that refer to 'nt'.

  5. There are no rows in NT that lie outside the boundaries of the
     partition definition for P.  This condition does not apply if the
     'WITHOUT VALIDATION' option is used.  The '[{WITH|WITHOUT}
     VALIDATION]' option was added in MySQL 5.7.5.

In addition to the 'ALTER', 'INSERT', and 'CREATE' privileges usually
required for 'ALTER TABLE' statements, you must have
the 'DROP' privilege to perform 'ALTER TABLE ... EXCHANGE PARTITION'.

You should also be aware of the following effects of 'ALTER TABLE ... EXCHANGE PARTITION'.:

   * Executing 'ALTER TABLE ... EXCHANGE PARTITION'.
     does not invoke any triggers on either the partitioned table or the
     table to be exchanged.

   * Any 'AUTO_INCREMENT' columns in the exchanged table are reset.

   * The 'IGNORE' keyword has no effect when used with 'ALTER TABLE ...
     EXCHANGE PARTITION'.

The syntax of the 'ALTER TABLE ... EXCHANGE PARTITION'
statement is shown here, where PT is the partitioned table,
P is the partition or subpartition to be exchanged, and NT is the
nonpartitioned table to be exchanged with P:

     ALTER TABLE PT
         EXCHANGE PARTITION P
         WITH TABLE NT;

Optionally, you can append a 'WITH VALIDATION' or 'WITHOUT VALIDATION'
clause.  When 'WITHOUT VALIDATION' is specified, the 'ALTER TABLE ... EXCHANGE PARTITION'
operation does not perform
row-by-row validation when exchanging a partition a nonpartitioned
table, allowing database administrators to assume responsibility for
ensuring that rows are within the boundaries of the partition
definition.  'WITH VALIDATION' is the default behavior and need not be
specified explicitly.  The '[{WITH|WITHOUT} VALIDATION]' option was
added in MySQL 5.7.5.

One and only one partition or subpartition may be exchanged with one and
only one nonpartitioned table in a single 'ALTER TABLE EXCHANGE PARTITION'
statement.  To exchange multiple partitions or
subpartitions, use multiple 'ALTER TABLE EXCHANGE PARTITION'
statements.  'EXCHANGE PARTITION' may not be combined with
other 'ALTER TABLE' options.  The partitioning and
(if applicable) subpartitioning used by the partitioned table may be of
any type or types supported in MySQL 5.7.

*Exchanging a Partition with a Nonpartitioned Table*

Suppose that a partitioned table 'e' has been created and populated
using the following SQL statements:

     CREATE TABLE e (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30)
     )
         PARTITION BY RANGE (id) (
             PARTITION p0 VALUES LESS THAN (50),
             PARTITION p1 VALUES LESS THAN (100),
             PARTITION p2 VALUES LESS THAN (150),
             PARTITION p3 VALUES LESS THAN (MAXVALUE)
     );

     INSERT INTO e VALUES
         (1669, "Jim", "Smith"),
         (337, "Mary", "Jones"),
         (16, "Frank", "White"),
         (2005, "Linda", "Black");

Now we create a nonpartitioned copy of 'e' named 'e2'.  This can be done
using the 'mysql' client as shown here:

     mysql> CREATE TABLE e2 LIKE e;
     Query OK, 0 rows affected (1.34 sec)

     mysql> ALTER TABLE e2 REMOVE PARTITIONING;
     Query OK, 0 rows affected (0.90 sec)
     Records: 0  Duplicates: 0  Warnings: 0

You can see which partitions in table 'e' contain rows by querying the
'INFORMATION_SCHEMA.PARTITIONS' table, like
this:

     mysql> SELECT PARTITION_NAME, TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |          1 |
     | p1             |          0 |
     | p2             |          0 |
     | p3             |          3 |
     +----------------+------------+
     4 rows in set (0.00 sec)

*Note*:

For partitioned 'InnoDB' tables, the row count given in the 'TABLE_ROWS'
column of the 'INFORMATION_SCHEMA.PARTITIONS'.
table is only an estimated value used in SQL optimization, and is not
always exact.

To exchange partition 'p0' in table 'e' with table 'e2', you can use the
'ALTER TABLE' statement shown
here:

     mysql> ALTER TABLE e EXCHANGE PARTITION p0 WITH TABLE e2;
     Query OK, 0 rows affected (0.28 sec)

More precisely, the statement just issued causes any rows found in the
partition to be swapped with those found in the table.  You can observe
how this has happened by querying the
'INFORMATION_SCHEMA.PARTITIONS' table, as before.
The table row that was previously found in partition 'p0' is no longer
present:

     mysql> SELECT PARTITION_NAME, TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |          0 |
     | p1             |          0 |
     | p2             |          0 |
     | p3             |          3 |
     +----------------+------------+
     4 rows in set (0.00 sec)

If you query table 'e2', you can see that the 'missing' row can now be
found there:

     mysql> SELECT * FROM e2;
     +----+-------+-------+
     | id | fname | lname |
     +----+-------+-------+
     | 16 | Frank | White |
     +----+-------+-------+
     1 row in set (0.00 sec)

The table to be exchanged with the partition does not necessarily have
to be empty.  To demonstrate this, we first insert a new row into table
'e', making sure that this row is stored in partition 'p0' by choosing
an 'id' column value that is less than 50, and verifying this afterward
by querying the 'PARTITIONS' table:

     mysql> INSERT INTO e VALUES (41, "Michael", "Green");
     Query OK, 1 row affected (0.05 sec)

     mysql> SELECT PARTITION_NAME, TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |          1 |
     | p1             |          0 |
     | p2             |          0 |
     | p3             |          3 |
     +----------------+------------+
     4 rows in set (0.00 sec)

Now we once again exchange partition 'p0' with table 'e2' using the same
'ALTER TABLE' statement as
previously:

     mysql> ALTER TABLE e EXCHANGE PARTITION p0 WITH TABLE e2;
     Query OK, 0 rows affected (0.28 sec)

The output of the following queries shows that the table row that was
stored in partition 'p0' and the table row that was stored in table
'e2', prior to issuing the 'ALTER TABLE'
statement, have now switched places:

     mysql> SELECT * FROM e;
     +------+-------+-------+
     | id   | fname | lname |
     +------+-------+-------+
     |   16 | Frank | White |
     | 1669 | Jim   | Smith |
     |  337 | Mary  | Jones |
     | 2005 | Linda | Black |
     +------+-------+-------+
     4 rows in set (0.00 sec)

     mysql> SELECT PARTITION_NAME, TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |          1 |
     | p1             |          0 |
     | p2             |          0 |
     | p3             |          3 |
     +----------------+------------+
     4 rows in set (0.00 sec)

     mysql> SELECT * FROM e2;
     +----+---------+-------+
     | id | fname   | lname |
     +----+---------+-------+
     | 41 | Michael | Green |
     +----+---------+-------+
     1 row in set (0.00 sec)

*Nonmatching Rows*

You should keep in mind that any rows found in the nonpartitioned table
prior to issuing the 'ALTER TABLE ... EXCHANGE PARTITION'
statement must meet the conditions required for them to be
stored in the target partition; otherwise, the statement fails.  To see
how this occurs, first insert a row into 'e2' that is outside the
boundaries of the partition definition for partition 'p0' of table 'e'.
For example, insert a row with an 'id' column value that is too large;
then, try to exchange the table with the partition again:

     mysql> INSERT INTO e2 VALUES (51, "Ellen", "McDonald");
     Query OK, 1 row affected (0.08 sec)

     mysql> ALTER TABLE e EXCHANGE PARTITION p0 WITH TABLE e2;
     ERROR 1707 (HY000): Found row that does not match the partition

Only the 'WITHOUT VALIDATION' option would permit this operation to
succeed:

     mysql> ALTER TABLE e EXCHANGE PARTITION p0 WITH TABLE e2 WITHOUT VALIDATION;
     Query OK, 0 rows affected (0.02 sec)

When a partition is exchanged with a table that contains rows that do
not match the partition definition, it is the responsibility of the
database administrator to fix the non-matching rows, which can be
performed using 'REPAIR TABLE' or 'ALTER TABLE ... REPAIR PARTITION'.

*Exchanging Partitions Without Row-By-Row Validation*

To avoid time consuming validation when exchanging a partition with a
table that has many rows, it is possible to skip the row-by-row
validation step by appending 'WITHOUT VALIDATION' to the 'ALTER TABLE ... EXCHANGE PARTITION'.
statement.

The following example compares the difference between execution times
when exchanging a partition with a nonpartitioned table, with and
without validation.  The partitioned table (table 'e') contains two
partitions of 1 million rows each.  The rows in p0 of table e are
removed and p0 is exchanged with a nonpartitioned table of 1 million
rows.  The 'WITH VALIDATION' operation takes 0.74 seconds.  By
comparison, the 'WITHOUT VALIDATION' operation takes 0.01 seconds.

     # Create a partitioned table with 1 million rows in each partition

     CREATE TABLE e (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30)
     )
         PARTITION BY RANGE (id) (
             PARTITION p0 VALUES LESS THAN (1000001),
             PARTITION p1 VALUES LESS THAN (2000001),
     );

     SELECT COUNT(*) FROM e;
     | COUNT(*) |
     +----------+
     |  2000000 |
     +----------+
     1 row in set (0.27 sec)

     # View the rows in each partition

     SELECT PARTITION_NAME, TABLE_ROWS FROM INFORMATION_SCHEMA.PARTITIONS WHERE TABLE_NAME = 'e';
     +----------------+-------------+
     | PARTITION_NAME | TABLE_ROWS  |
     +----------------+-------------+
     | p0             |     1000000 |
     | p1             |     1000000 |
     +----------------+-------------+
     2 rows in set (0.00 sec)

     # Create a nonpartitioned table of the same structure and populate it with 1 million rows

     CREATE TABLE e2 (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30)
     );

     mysql> SELECT COUNT(*) FROM e2;
     +----------+
     | COUNT(*) |
     +----------+
     |  1000000 |
     +----------+
     1 row in set (0.24 sec)

     # Create another nonpartitioned table of the same structure and populate it with 1 million rows

     CREATE TABLE e3 (
         id INT NOT NULL,
         fname VARCHAR(30),
         lname VARCHAR(30)
     );

     mysql> SELECT COUNT(*) FROM e3;
     +----------+
     | COUNT(*) |
     +----------+
     |  1000000 |
     +----------+
     1 row in set (0.25 sec)

     # Drop the rows from p0 of table e

     mysql> DELETE FROM e WHERE id < 1000001;
     Query OK, 1000000 rows affected (5.55 sec)

     # Confirm that there are no rows in partition p0

     mysql> SELECT PARTITION_NAME, TABLE_ROWS FROM INFORMATION_SCHEMA.PARTITIONS WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |          0 |
     | p1             |    1000000 |
     +----------------+------------+
     2 rows in set (0.00 sec)

     # Exchange partition p0 of table e with the table e2 'WITH VALIDATION'

     mysql> ALTER TABLE e EXCHANGE PARTITION p0 WITH TABLE e2 WITH VALIDATION;
     Query OK, 0 rows affected (0.74 sec)

     # Confirm that the partition was exchanged with table e2

     mysql> SELECT PARTITION_NAME, TABLE_ROWS FROM INFORMATION_SCHEMA.PARTITIONS WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |    1000000 |
     | p1             |    1000000 |
     +----------------+------------+
     2 rows in set (0.00 sec)

     # Once again, drop the rows from p0 of table e

     mysql> DELETE FROM e WHERE id < 1000001;
     Query OK, 1000000 rows affected (5.55 sec)

     # Confirm that there are no rows in partition p0

     mysql> SELECT PARTITION_NAME, TABLE_ROWS FROM INFORMATION_SCHEMA.PARTITIONS WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |          0 |
     | p1             |    1000000 |
     +----------------+------------+
     2 rows in set (0.00 sec)

     # Exchange partition p0 of table e with the table e3 'WITHOUT VALIDATION'

     mysql> ALTER TABLE e EXCHANGE PARTITION p0 WITH TABLE e3 WITHOUT VALIDATION;
     Query OK, 0 rows affected (0.01 sec)

     # Confirm that the partition was exchanged with table e3

     mysql> SELECT PARTITION_NAME, TABLE_ROWS FROM INFORMATION_SCHEMA.PARTITIONS WHERE TABLE_NAME = 'e';
     +----------------+------------+
     | PARTITION_NAME | TABLE_ROWS |
     +----------------+------------+
     | p0             |    1000000 |
     | p1             |    1000000 |
     +----------------+------------+
     2 rows in set (0.00 sec)

If a partition is exchanged with a table that contains rows that do not
match the partition definition, it is the responsibility of the database
administrator to fix the non-matching rows, which can be performed using
'REPAIR TABLE' or 'ALTER TABLE ... REPAIR PARTITION'.

*Exchanging a Subpartition with a Nonpartitioned Table*

You can also exchange a subpartition of a subpartitioned table (see
partitioning-subpartitions) with a nonpartitioned table using an
'ALTER TABLE ... EXCHANGE PARTITION' statement.  In
the following example, we first create a table 'es' that is partitioned
by 'RANGE' and subpartitioned by 'KEY', populate this table as we did
table 'e', and then create an empty, nonpartitioned copy 'es2' of the
table, as shown here:

     mysql> CREATE TABLE es (
         ->     id INT NOT NULL,
         ->     fname VARCHAR(30),
         ->     lname VARCHAR(30)
         -> )
         ->     PARTITION BY RANGE (id)
         ->     SUBPARTITION BY KEY (lname)
         ->     SUBPARTITIONS 2 (
         ->         PARTITION p0 VALUES LESS THAN (50),
         ->         PARTITION p1 VALUES LESS THAN (100),
         ->         PARTITION p2 VALUES LESS THAN (150),
         ->         PARTITION p3 VALUES LESS THAN (MAXVALUE)
         ->     );
     Query OK, 0 rows affected (2.76 sec)

     mysql> INSERT INTO es VALUES
         ->     (1669, "Jim", "Smith"),
         ->     (337, "Mary", "Jones"),
         ->     (16, "Frank", "White"),
         ->     (2005, "Linda", "Black");
     Query OK, 4 rows affected (0.04 sec)
     Records: 4  Duplicates: 0  Warnings: 0

     mysql> CREATE TABLE es2 LIKE es;
     Query OK, 0 rows affected (1.27 sec)

     mysql> ALTER TABLE es2 REMOVE PARTITIONING;
     Query OK, 0 rows affected (0.70 sec)
     Records: 0  Duplicates: 0  Warnings: 0

Although we did not explicitly name any of the subpartitions when
creating table 'es', we can obtain generated names for these by
including the 'SUBPARTITION_NAME' of the 'PARTITIONS'
table from 'INFORMATION_SCHEMA' when selecting from
that table, as shown here:

     mysql> SELECT PARTITION_NAME, SUBPARTITION_NAME, TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'es';
     +----------------+-------------------+------------+
     | PARTITION_NAME | SUBPARTITION_NAME | TABLE_ROWS |
     +----------------+-------------------+------------+
     | p0             | p0sp0             |          1 |
     | p0             | p0sp1             |          0 |
     | p1             | p1sp0             |          0 |
     | p1             | p1sp1             |          0 |
     | p2             | p2sp0             |          0 |
     | p2             | p2sp1             |          0 |
     | p3             | p3sp0             |          3 |
     | p3             | p3sp1             |          0 |
     +----------------+-------------------+------------+
     8 rows in set (0.00 sec)

The following 'ALTER TABLE'.
statement exchanges subpartition 'p3sp0' table 'es' with the
nonpartitioned table 'es2':

     mysql> ALTER TABLE es EXCHANGE PARTITION p3sp0 WITH TABLE es2;
     Query OK, 0 rows affected (0.29 sec)

You can verify that the rows were exchanged by issuing the following
queries:

     mysql> SELECT PARTITION_NAME, SUBPARTITION_NAME, TABLE_ROWS
         ->     FROM INFORMATION_SCHEMA.PARTITIONS
         ->     WHERE TABLE_NAME = 'es';
     +----------------+-------------------+------------+
     | PARTITION_NAME | SUBPARTITION_NAME | TABLE_ROWS |
     +----------------+-------------------+------------+
     | p0             | p0sp0             |          1 |
     | p0             | p0sp1             |          0 |
     | p1             | p1sp0             |          0 |
     | p1             | p1sp1             |          0 |
     | p2             | p2sp0             |          0 |
     | p2             | p2sp1             |          0 |
     | p3             | p3sp0             |          0 |
     | p3             | p3sp1             |          0 |
     +----------------+-------------------+------------+
     8 rows in set (0.00 sec)

     mysql> SELECT * FROM es2;
     +------+-------+-------+
     | id   | fname | lname |
     +------+-------+-------+
     | 1669 | Jim   | Smith |
     |  337 | Mary  | Jones |
     | 2005 | Linda | Black |
     +------+-------+-------+
     3 rows in set (0.00 sec)

If a table is subpartitioned, you can exchange only a subpartition of
the table--not an entire partition--with an unpartitioned table, as
shown here:

     mysql> ALTER TABLE es EXCHANGE PARTITION p3 WITH TABLE es2;
     ERROR 1704 (HY000): Subpartitioned table, use subpartition instead of partition

The comparison of table structures used by MySQL is very strict.  The
number, order, names, and types of columns and indexes of the
partitioned table and the nonpartitioned table must match exactly.  In
addition, both tables must use the same storage engine:

     mysql> CREATE TABLE es3 LIKE e;
     Query OK, 0 rows affected (1.31 sec)

     mysql> ALTER TABLE es3 REMOVE PARTITIONING;
     Query OK, 0 rows affected (0.53 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> SHOW CREATE TABLE es3\G
     *************************** 1. row ***************************
            Table: es3
     Create Table: CREATE TABLE `es3` (
       `id` int(11) NOT NULL,
       `fname` varchar(30) DEFAULT NULL,
       `lname` varchar(30) DEFAULT NULL
     ) ENGINE=InnoDB DEFAULT CHARSET=latin1
     1 row in set (0.00 sec)

     mysql> ALTER TABLE es3 ENGINE = MyISAM;
     Query OK, 0 rows affected (0.15 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     mysql> ALTER TABLE es EXCHANGE PARTITION p3sp0 WITH TABLE es3;
     ERROR 1497 (HY000): The mix of handlers in the partitions is not allowed in this version of MySQL

22.3.4 Maintenance of Partitions
--------------------------------

A number of table and partition maintenance tasks can be carried out
using SQL statements intended for such purposes on partitioned tables in
MySQL 5.7.

Table maintenance of partitioned tables can be accomplished using the
statements 'CHECK TABLE', 'OPTIMIZE TABLE',
see 'ANALYZE TABLE', and 'REPAIR TABLE',
which are supported for partitioned tables.

You can use a number of extensions to 'ALTER TABLE'
for performing operations of this type
on one or more partitions directly, as described in the following list:

   * Rebuilding partitions

     Rebuilds the partition; this has the same effect as dropping all
     records stored in the partition, then reinserting them.  This can
     be useful for purposes of defragmentation.

     Example:

          ALTER TABLE t1 REBUILD PARTITION p0, p1;

   * Optimizing partitions

     If you have deleted a large number of rows from a partition or if
     you have made many changes to a partitioned table with
     variable-length rows (that is, having 'VARCHAR',
     'BLOB', or 'TEXT' columns), you can use
     'ALTER TABLE ... OPTIMIZE PARTITION'
     to reclaim any unused space and
     to defragment the partition data file.

     Example:

          ALTER TABLE t1 OPTIMIZE PARTITION p0, p1;

     Using 'OPTIMIZE PARTITION' on a given partition is equivalent to
     running 'CHECK PARTITION', 'ANALYZE PARTITION', and 'REPAIR
     PARTITION' on that partition.

     Some MySQL storage engines, including 'InnoDB',
     do not support per-partition optimization;
     in these cases, see 'ALTER TABLE ... OPTIMIZE PARTITION'
     analyzes and rebuilds the entire
     table, and causes an appropriate warning to be issued.  (Bug
     #11751825, Bug #42822) Use 'ALTER TABLE ... REBUILD PARTITION' and
     'ALTER TABLE ... ANALYZE PARTITION' instead, to avoid this issue.

   * Analyzing partitions

     This reads and stores the key distributions for partitions.

     Example:

          ALTER TABLE t1 ANALYZE PARTITION p3;

   * Repairing partitions

     This repairs corrupted partitions.

     Example:

          ALTER TABLE t1 REPAIR PARTITION p0,p1;

     Normally, 'REPAIR PARTITION' fails when the partition contains
     duplicate key errors.  In MySQL 5.7.2 and later, you can use
     'ALTER IGNORE TABLE' with this
     option, in which case all rows that cannot be moved due to the
     presence of duplicate keys are removed from the partition (Bug
     #16900947).

   * Checking partitions

     You can check partitions for errors in much the same way that you
     can use 'CHECK TABLE' with nonpartitioned tables.

     Example:

          ALTER TABLE trb3 CHECK PARTITION p1;

     This command will tell you if the data or indexes in partition 'p1'
     of table 't1' are corrupted.  If this is the case, use 'ALTER TABLE ... REPAIR PARTITION'
     to
     repair the partition.

     Normally, 'CHECK PARTITION' fails when the partition contains
     duplicate key errors.  In MySQL 5.7.2 and later, you can use
     'ALTER IGNORE TABLE' with this
     option, in which case the statement returns the contents of each
     row in the partition where a duplicate key violation is found.
     Only the values for the columns in the partitioning expression for
     the table are reported.  (Bug #16900947)

Each of the statements in the list just shown also supports the keyword
'ALL' in place of the list of partition names.  Using 'ALL' causes the
statement to act on all partitions in the table.

The use of 'mysqlcheck' and 'myisamchk'
is not supported with partitioned tables.

In MySQL 5.7, you can also truncate partitions using 'ALTER TABLE ... TRUNCATE PARTITION'.
This statement can be used to
delete all rows from one or more partitions in much the same way that
'TRUNCATE TABLE' deletes all rows from a table.

'ALTER TABLE ... TRUNCATE PARTITION ALL' truncates
all partitions in the table.

Prior to MySQL 5.7.2, 'ANALYZE', 'CHECK', 'OPTIMIZE', 'REBUILD',
'REPAIR', and 'TRUNCATE' operations were not permitted on subpartitions
(Bug #14028340, Bug #65184).

22.3.5 Obtaining Information About Partitions
---------------------------------------------

This section discusses obtaining information about existing partitions,
which can be done in a number of ways.  Methods of obtaining such
information include the following:

   * Using the 'SHOW CREATE TABLE' statement
     to view the partitioning clauses used in creating a partitioned
     table.

   * Using the 'SHOW TABLE STATUS' statement
     to determine whether a table is partitioned.

   * Querying the 'INFORMATION_SCHEMA.PARTITIONS'
     table.

   * Using the statement 'EXPLAIN SELECT' to see which
     partitions are used by a given 'SELECT'.

As discussed elsewhere in this chapter, see 'SHOW CREATE TABLE'
includes in its output the 'PARTITION BY' clause used
to create a partitioned table.  For example:

     mysql> SHOW CREATE TABLE trb3\G
     *************************** 1. row ***************************
            Table: trb3
     Create Table: CREATE TABLE `trb3` (
       `id` int(11) default NULL,
       `name` varchar(50) default NULL,
       `purchased` date default NULL
     ) ENGINE=MyISAM DEFAULT CHARSET=latin1
     PARTITION BY RANGE (YEAR(purchased)) (
       PARTITION p0 VALUES LESS THAN (1990) ENGINE = MyISAM,
       PARTITION p1 VALUES LESS THAN (1995) ENGINE = MyISAM,
       PARTITION p2 VALUES LESS THAN (2000) ENGINE = MyISAM,
       PARTITION p3 VALUES LESS THAN (2005) ENGINE = MyISAM
     )
     1 row in set (0.00 sec)

The output from 'SHOW TABLE STATUS' for
partitioned tables is the same as that for nonpartitioned tables, except
that the 'Create_options' column contains the string 'partitioned'.  The
'Engine' column contains the name of the storage engine used by all
partitions of the table.  (See show-table-status, for more
information about this statement.)

You can also obtain information about partitions from
'INFORMATION_SCHEMA', which contains a 'PARTITIONS'
table.  See partitions-table.

It is possible to determine which partitions of a partitioned table are
involved in a given 'SELECT' query using 'EXPLAIN'.
The 'partitions' column in the 'EXPLAIN'.
output lists the partitions from which records would be matched by the
query.

Suppose that you have a table 'trb1' created and populated as follows:

     CREATE TABLE trb1 (id INT, name VARCHAR(50), purchased DATE)
         PARTITION BY RANGE(id)
         (
             PARTITION p0 VALUES LESS THAN (3),
             PARTITION p1 VALUES LESS THAN (7),
             PARTITION p2 VALUES LESS THAN (9),
             PARTITION p3 VALUES LESS THAN (11)
         );

     INSERT INTO trb1 VALUES
         (1, 'desk organiser', '2003-10-15'),
         (2, 'CD player', '1993-11-05'),
         (3, 'TV set', '1996-03-10'),
         (4, 'bookcase', '1982-01-10'),
         (5, 'exercise bike', '2004-05-09'),
         (6, 'sofa', '1987-06-05'),
         (7, 'popcorn maker', '2001-11-22'),
         (8, 'aquarium', '1992-08-04'),
         (9, 'study desk', '1984-09-16'),
         (10, 'lava lamp', '1998-12-25');

You can see which partitions are used in a query such as 'SELECT * FROM
trb1;', as shown here:

     mysql> EXPLAIN SELECT * FROM trb1\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: trb1
        partitions: p0,p1,p2,p3
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: 10
             Extra: Using filesort

In this case, all four partitions are searched.  However, when a
limiting condition making use of the partitioning key is added to the
query, you can see that only those partitions containing matching values
are scanned, as shown here:

     mysql> EXPLAIN SELECT * FROM trb1 WHERE id < 5\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: trb1
        partitions: p0,p1
              type: ALL
     possible_keys: NULL
               key: NULL
           key_len: NULL
               ref: NULL
              rows: 10
             Extra: Using where

'EXPLAIN ' also provides information about keys used and
possible keys:

     mysql> ALTER TABLE trb1 ADD PRIMARY KEY (id);
     Query OK, 10 rows affected (0.03 sec)
     Records: 10  Duplicates: 0  Warnings: 0

     mysql> EXPLAIN SELECT * FROM trb1 WHERE id < 5\G
     *************************** 1. row ***************************
                id: 1
       select_type: SIMPLE
             table: trb1
        partitions: p0,p1
              type: range
     possible_keys: PRIMARY
               key: PRIMARY
           key_len: 4
               ref: NULL
              rows: 7
             Extra: Using where

If 'EXPLAIN PARTITIONS' is used to examine a query
against a nonpartitioned table, no error is produced, but the value of
the 'partitions' column is always 'NULL'.

The 'rows' column of 'EXPLAIN' output displays the total
number of rows in the table.

See also explain.

22.4 Partition Pruning
======================

This section discusses an optimization known as _partition pruning_.
The core concept behind partition pruning is relatively simple, and can
be described as 'Do not scan partitions where there can be no matching
values'.  Suppose that you have a partitioned table 't1' defined by this
statement:

     CREATE TABLE t1 (
         fname VARCHAR(50) NOT NULL,
         lname VARCHAR(50) NOT NULL,
         region_code TINYINT UNSIGNED NOT NULL,
         dob DATE NOT NULL
     )
     PARTITION BY RANGE( region_code ) (
         PARTITION p0 VALUES LESS THAN (64),
         PARTITION p1 VALUES LESS THAN (128),
         PARTITION p2 VALUES LESS THAN (192),
         PARTITION p3 VALUES LESS THAN MAXVALUE
     );

Consider the case where you wish to obtain results from a
'SELECT' statement such as this one:

     SELECT fname, lname, region_code, dob
         FROM t1
         WHERE region_code > 125 AND region_code < 130;

It is easy to see that none of the rows which ought to be returned will
be in either of the partitions 'p0' or 'p3'; that is, we need to search
only in partitions 'p1' and 'p2' to find matching rows.  By doing so, it
is possible to expend much less time and effort in finding matching rows
than would be required to scan all partitions in the table.  This
'cutting away' of unneeded partitions is known as _pruning_.  When the
optimizer can make use of partition pruning in performing this query,
execution of the query can be an order of magnitude faster than the same
query against a nonpartitioned table containing the same column
definitions and data.

*Note*:

When pruning is performed on a partitioned 'MyISAM'
table, all partitions are opened, whether or not
they are examined, due to the design of the 'MyISAM' storage engine.
This means that you must have a sufficient number of file descriptors
available to cover all partitions of the table.  See
partitioning-limitations-myisam-file-descriptors.

This limitation does not apply to partitioned tables using other MySQL
storage engines such as 'InnoDB'.

The optimizer can perform pruning whenever a 'WHERE' condition can be
reduced to either one of the following two cases:

   * 'PARTITION_COLUMN = CONSTANT'

   * 'PARTITION_COLUMN IN (CONSTANT1, CONSTANT2, ..., CONSTANTN)'

In the first case, the optimizer simply evaluates the partitioning
expression for the value given, determines which partition contains that
value, and scans only this partition.  In many cases, the equal sign can
be replaced with another arithmetic comparison, including '<', '>',
'<=', '>=', and '<>'.  Some queries using 'BETWEEN' in the 'WHERE'
clause can also take advantage of partition pruning.  See the examples
later in this section.

In the second case, the optimizer evaluates the partitioning expression
for each value in the list, creates a list of matching partitions, and
then scans only the partitions in this partition list.

MySQL can apply partition pruning to 'SELECT',
'DELETE', and 'UPDATE' statements.
'INSERT' statements currently cannot be pruned.

Pruning can also be applied to short ranges, which the optimizer can
convert into equivalent lists of values.  For instance, in the previous
example, the 'WHERE' clause can be converted to 'WHERE region_code IN
(126, 127, 128, 129)'.  Then the optimizer can determine that the first
two values in the list are found in partition 'p1', the remaining two
values in partition 'p2', and that the other partitions contain no
relevant values and so do not need to be searched for matching rows.

The optimizer can also perform pruning for 'WHERE' conditions that
involve comparisons of the preceding types on multiple columns for
tables that use 'RANGE COLUMNS' or 'LIST COLUMNS' partitioning.

This type of optimization can be applied whenever the partitioning
expression consists of an equality or a range which can be reduced to a
set of equalities, or when the partitioning expression represents an
increasing or decreasing relationship.  Pruning can also be applied for
tables partitioned on a 'DATE' or 'DATETIME'
column when the partitioning expression uses the 'YEAR()' or
'TO_DAYS()' function.  In addition, in MySQL 5.7, pruning can be applied
for such tables when the partitioning expression uses the 'TO_SECONDS()'
function.

Suppose that table 't2', defined as shown here, is partitioned on a
'DATE' column:

     CREATE TABLE t2 (
         fname VARCHAR(50) NOT NULL,
         lname VARCHAR(50) NOT NULL,
         region_code TINYINT UNSIGNED NOT NULL,
         dob DATE NOT NULL
     )
     PARTITION BY RANGE( YEAR(dob) ) (
         PARTITION d0 VALUES LESS THAN (1970),
         PARTITION d1 VALUES LESS THAN (1975),
         PARTITION d2 VALUES LESS THAN (1980),
         PARTITION d3 VALUES LESS THAN (1985),
         PARTITION d4 VALUES LESS THAN (1990),
         PARTITION d5 VALUES LESS THAN (2000),
         PARTITION d6 VALUES LESS THAN (2005),
         PARTITION d7 VALUES LESS THAN MAXVALUE
     );

The following statements using 't2' can make of use partition pruning:

     SELECT * FROM t2 WHERE dob = '1982-06-23';

     UPDATE t2 SET region_code = 8 WHERE dob BETWEEN '1991-02-15' AND '1997-04-25';

     DELETE FROM t2 WHERE dob >= '1984-06-21' AND dob <= '1999-06-21'

In the case of the last statement, the optimizer can also act as
follows:

  1. _Find the partition containing the low end of the range_.

     'YEAR('1984-06-21')' yields the value '1984', which is found in
     partition 'd3'.

  2. _Find the partition containing the high end of the range_.

     'YEAR('1999-06-21')' evaluates to '1999', which is found in
     partition 'd5'.

  3. _Scan only these two partitions and any partitions that may lie
     between them_.

     In this case, this means that only partitions 'd3', 'd4', and 'd5'
     are scanned.  The remaining partitions may be safely ignored (and
     are ignored).

*Important*:

Invalid 'DATE' and 'DATETIME' values referenced in the 'WHERE' condition
of a statement against a partitioned table are treated as 'NULL'.  This
means that a query such as 'SELECT * FROM PARTITIONED_TABLE WHERE
DATE_COLUMN < '2008-12-00'' does not return any values (see Bug #40972).

So far, we have looked only at examples using 'RANGE' partitioning, but
pruning can be applied with other partitioning types as well.

Consider a table that is partitioned by 'LIST', where the partitioning
expression is increasing or decreasing, such as the table 't3' shown
here.  (In this example, we assume for the sake of brevity that the
'region_code' column is limited to values between 1 and 10 inclusive.)

     CREATE TABLE t3 (
         fname VARCHAR(50) NOT NULL,
         lname VARCHAR(50) NOT NULL,
         region_code TINYINT UNSIGNED NOT NULL,
         dob DATE NOT NULL
     )
     PARTITION BY LIST(region_code) (
         PARTITION r0 VALUES IN (1, 3),
         PARTITION r1 VALUES IN (2, 5, 8),
         PARTITION r2 VALUES IN (4, 9),
         PARTITION r3 VALUES IN (6, 7, 10)
     );

For a statement such as 'SELECT * FROM t3 WHERE region_code BETWEEN 1
AND 3', the optimizer determines in which partitions the values 1, 2,
and 3 are found ('r0' and 'r1') and skips the remaining ones ('r2' and
'r3').

For tables that are partitioned by 'HASH' or '[LINEAR] KEY', partition
pruning is also possible in cases in which the 'WHERE' clause uses a
simple '=' relation against a column used in the partitioning
expression.  Consider a table created like this:

     CREATE TABLE t4 (
         fname VARCHAR(50) NOT NULL,
         lname VARCHAR(50) NOT NULL,
         region_code TINYINT UNSIGNED NOT NULL,
         dob DATE NOT NULL
     )
     PARTITION BY KEY(region_code)
     PARTITIONS 8;

A statement that compares a column value with a constant can be pruned:

     UPDATE t4 WHERE region_code = 7;

Pruning can also be employed for short ranges, because the optimizer can
turn such conditions into 'IN' relations.  For example, using the same
table 't4' as defined previously, queries such as these can be pruned:

     SELECT * FROM t4 WHERE region_code > 2 AND region_code < 6;

     SELECT * FROM t4 WHERE region_code BETWEEN 3 AND 5;

In both these cases, the 'WHERE' clause is transformed by the optimizer
into 'WHERE region_code IN (3, 4, 5)'.

*Important*:

This optimization is used only if the range size is smaller than the
number of partitions.  Consider this statement:

     DELETE FROM t4 WHERE region_code BETWEEN 4 AND 12;

The range in the 'WHERE' clause covers 9 values (4, 5, 6, 7, 8, 9, 10,
11, 12), but 't4' has only 8 partitions.  This means that the 'DELETE'
cannot be pruned.

When a table is partitioned by 'HASH' or '[LINEAR] KEY', pruning can be
used only on integer columns.  For example, this statement cannot use
pruning because 'dob' is a 'DATE' column:

     SELECT * FROM t4 WHERE dob >= '2001-04-14' AND dob <= '2005-10-15';

However, if the table stores year values in an 'INT'
column, then a query having 'WHERE year_col >= 2001 AND
year_col <= 2005' can be pruned.

Prior to MySQL 5.7.1, partition pruning was disabled for all tables
using a storage engine that provides automatic partitioning, such as the
'NDB' storage engine used by NDB Cluster.  (Bug #14672885) Beginning
with MySQL 5.7.1, such tables can be pruned if they are explicitly
partitioned.  (Bug #14827952)

22.5 Partition Selection
========================

MySQL 5.7 supports explicit selection of partitions and subpartitions
that, when executing a statement, should be checked for rows matching a
given 'WHERE' condition.  Partition selection is similar to partition
pruning, in that only specific partitions are checked for matches, but
differs in two key respects:

  1. The partitions to be checked are specified by the issuer of the
     statement, unlike partition pruning, which is automatic.

  2. Whereas partition pruning applies only to queries, explicit
     selection of partitions is supported for both queries and a number
     of DML statements.

SQL statements supporting explicit partition selection are listed here:

   * 'SELECT'.

   * 'DELETE'.

   * 'INSERT'.

   * 'REPLACE'.

   * 'UPDATE'.

   * 'LOAD DATA'.

   * 'LOAD XML'.

The remainder of this section discusses explicit partition selection as
it applies generally to the statements just listed, and provides some
examples.

Explicit partition selection is implemented using a 'PARTITION' option.
For all supported statements, this option uses the syntax shown here:

           PARTITION (PARTITION_NAMES)

           PARTITION_NAMES:
               PARTITION_NAME, ...

This option always follows the name of the table to which the partition
or partitions belong.  PARTITION_NAMES is a comma-separated list of
partitions or subpartitions to be used.  Each name in this list must be
the name of an existing partition or subpartition of the specified
table; if any of the partitions or subpartitions are not found, the
statement fails with an error ('partition 'PARTITION_NAME' doesn't
exist').  Partitions and subpartitions named in PARTITION_NAMES may be
listed in any order, and may overlap.

When the 'PARTITION' option is used, only the partitions and
subpartitions listed are checked for matching rows.  This option can be
used in a 'SELECT' statement to determine which rows
belong to a given partition.  Consider a partitioned table named
'employees', created and populated using the statements shown here:

     SET @@SQL_MODE = '';

     CREATE TABLE employees  (
         id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         fname VARCHAR(25) NOT NULL,
         lname VARCHAR(25) NOT NULL,
         store_id INT NOT NULL,
         department_id INT NOT NULL
     )
         PARTITION BY RANGE(id)  (
             PARTITION p0 VALUES LESS THAN (5),
             PARTITION p1 VALUES LESS THAN (10),
             PARTITION p2 VALUES LESS THAN (15),
             PARTITION p3 VALUES LESS THAN MAXVALUE
     );

     INSERT INTO employees VALUES
         ('', 'Bob', 'Taylor', 3, 2), ('', 'Frank', 'Williams', 1, 2),
         ('', 'Ellen', 'Johnson', 3, 4), ('', 'Jim', 'Smith', 2, 4),
         ('', 'Mary', 'Jones', 1, 1), ('', 'Linda', 'Black', 2, 3),
         ('', 'Ed', 'Jones', 2, 1), ('', 'June', 'Wilson', 3, 1),
         ('', 'Andy', 'Smith', 1, 3), ('', 'Lou', 'Waters', 2, 4),
         ('', 'Jill', 'Stone', 1, 4), ('', 'Roger', 'White', 3, 2),
         ('', 'Howard', 'Andrews', 1, 2), ('', 'Fred', 'Goldberg', 3, 3),
         ('', 'Barbara', 'Brown', 2, 3), ('', 'Alice', 'Rogers', 2, 2),
         ('', 'Mark', 'Morgan', 3, 3), ('', 'Karen', 'Cole', 3, 2);

You can see which rows are stored in partition 'p1' like this:

     mysql> SELECT * FROM employees PARTITION (p1);
     +----+-------+--------+----------+---------------+
     | id | fname | lname  | store_id | department_id |
     +----+-------+--------+----------+---------------+
     |  5 | Mary  | Jones  |        1 |             1 |
     |  6 | Linda | Black  |        2 |             3 |
     |  7 | Ed    | Jones  |        2 |             1 |
     |  8 | June  | Wilson |        3 |             1 |
     |  9 | Andy  | Smith  |        1 |             3 |
     +----+-------+--------+----------+---------------+
     5 rows in set (0.00 sec)

The result is the same as obtained by the query 'SELECT * FROM employees
WHERE id BETWEEN 5 AND 9'.

To obtain rows from multiple partitions, supply their names as a
comma-delimited list.  For example, 'SELECT * FROM employees PARTITION
(p1, p2)' returns all rows from partitions 'p1' and 'p2' while excluding
rows from the remaining partitions.

Any valid query against a partitioned table can be rewritten with a
'PARTITION' option to restrict the result to one or more desired
partitions.  You can use 'WHERE' conditions, 'ORDER BY' and 'LIMIT'
options, and so on.  You can also use aggregate functions with 'HAVING'
and 'GROUP BY' options.  Each of the following queries produces a valid
result when run on the 'employees' table as previously defined:

     mysql> SELECT * FROM employees PARTITION (p0, p2)
         ->     WHERE lname LIKE 'S%';
     +----+-------+-------+----------+---------------+
     | id | fname | lname | store_id | department_id |
     +----+-------+-------+----------+---------------+
     |  4 | Jim   | Smith |        2 |             4 |
     | 11 | Jill  | Stone |        1 |             4 |
     +----+-------+-------+----------+---------------+
     2 rows in set (0.00 sec)

     mysql> SELECT id, CONCAT(fname, ' ', lname) AS name
         ->     FROM employees PARTITION (p0) ORDER BY lname;
     +----+----------------+
     | id | name           |
     +----+----------------+
     |  3 | Ellen Johnson  |
     |  4 | Jim Smith      |
     |  1 | Bob Taylor     |
     |  2 | Frank Williams |
     +----+----------------+
     4 rows in set (0.06 sec)

     mysql> SELECT store_id, COUNT(department_id) AS c
         ->     FROM employees PARTITION (p1,p2,p3)
         ->     GROUP BY store_id HAVING c > 4;
     +---+----------+
     | c | store_id |
     +---+----------+
     | 5 |        2 |
     | 5 |        3 |
     +---+----------+
     2 rows in set (0.00 sec)

Statements using partition selection can be employed with tables using
any of the partitioning types supported in MySQL 5.7.  When a table is
created using '[LINEAR] HASH' or '[LINEAR] KEY' partitioning and the
names of the partitions are not specified, MySQL automatically names the
partitions 'p0', 'p1', 'p2', ..., 'pN-1', where N is the number of
partitions.  For subpartitions not explicitly named, MySQL assigns
automatically to the subpartitions in each partition 'pX' the names
'pXsp0', 'pXsp1', 'pXsp2', ..., 'pXspM-1', where M is the number of
subpartitions.  When executing against this table a 'SELECT'.
(or other SQL statement for which explicit partition selection
is allowed), you can use these generated names in a 'PARTITION' option,
as shown here:

     mysql> CREATE TABLE employees_sub  (
         ->     id INT NOT NULL AUTO_INCREMENT,
         ->     fname VARCHAR(25) NOT NULL,
         ->     lname VARCHAR(25) NOT NULL,
         ->     store_id INT NOT NULL,
         ->     department_id INT NOT NULL,
         ->     PRIMARY KEY pk (id, lname)
         -> )
         ->     PARTITION BY RANGE(id)
         ->     SUBPARTITION BY KEY (lname)
         ->     SUBPARTITIONS 2 (
         ->         PARTITION p0 VALUES LESS THAN (5),
         ->         PARTITION p1 VALUES LESS THAN (10),
         ->         PARTITION p2 VALUES LESS THAN (15),
         ->         PARTITION p3 VALUES LESS THAN MAXVALUE
         -> );
     Query OK, 0 rows affected (1.14 sec)

     mysql> INSERT INTO employees_sub   # re-use data in employees table
         ->     SELECT * FROM employees;
     Query OK, 18 rows affected (0.09 sec)
     Records: 18  Duplicates: 0  Warnings: 0

     mysql> SELECT id, CONCAT(fname, ' ', lname) AS name
         ->     FROM employees_sub PARTITION (p2sp1);
     +----+---------------+
     | id | name          |
     +----+---------------+
     | 10 | Lou Waters    |
     | 14 | Fred Goldberg |
     +----+---------------+
     2 rows in set (0.00 sec)

You may also use a 'PARTITION' option in the 'SELECT'.
portion of an 'INSERT ... SELECT' statement, as
shown here:

     mysql> CREATE TABLE employees_copy LIKE employees;
     Query OK, 0 rows affected (0.28 sec)

     mysql> INSERT INTO employees_copy
         ->     SELECT * FROM employees PARTITION (p2);
     Query OK, 5 rows affected (0.04 sec)
     Records: 5  Duplicates: 0  Warnings: 0

     mysql> SELECT * FROM employees_copy;
     +----+--------+----------+----------+---------------+
     | id | fname  | lname    | store_id | department_id |
     +----+--------+----------+----------+---------------+
     | 10 | Lou    | Waters   |        2 |             4 |
     | 11 | Jill   | Stone    |        1 |             4 |
     | 12 | Roger  | White    |        3 |             2 |
     | 13 | Howard | Andrews  |        1 |             2 |
     | 14 | Fred   | Goldberg |        3 |             3 |
     +----+--------+----------+----------+---------------+
     5 rows in set (0.00 sec)

Partition selection can also be used with joins.  Suppose we create and
populate two tables using the statements shown here:

     CREATE TABLE stores (
         id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         city VARCHAR(30) NOT NULL
     )
         PARTITION BY HASH(id)
         PARTITIONS 2;

     INSERT INTO stores VALUES
         ('', 'Nambucca'), ('', 'Uranga'),
         ('', 'Bellingen'), ('', 'Grafton');

     CREATE TABLE departments  (
         id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(30) NOT NULL
     )
         PARTITION BY KEY(id)
         PARTITIONS 2;

     INSERT INTO departments VALUES
         ('', 'Sales'), ('', 'Customer Service'),
         ('', 'Delivery'), ('', 'Accounting');

You can explicitly select partitions (or subpartitions, or both) from
any or all of the tables in a join.  (The 'PARTITION' option used to
select partitions from a given table immediately follows the name of the
table, before all other options, including any table alias.)  For
example, the following query gets the name, employee ID, department, and
city of all employees who work in the Sales or Delivery department
(partition 'p1' of the 'departments' table) at the stores in either of
the cities of Nambucca and Bellingen (partition 'p0' of the 'stores'
table):

     mysql> SELECT
         ->     e.id AS 'Employee ID', CONCAT(e.fname, ' ', e.lname) AS Name,
         ->     s.city AS City, d.name AS department
         -> FROM employees AS e
         ->     JOIN stores PARTITION (p1) AS s ON e.store_id=s.id
         ->     JOIN departments PARTITION (p0) AS d ON e.department_id=d.id
         -> ORDER BY e.lname;
     +-------------+---------------+-----------+------------+
     | Employee ID | Name          | City      | department |
     +-------------+---------------+-----------+------------+
     |          14 | Fred Goldberg | Bellingen | Delivery   |
     |           5 | Mary Jones    | Nambucca  | Sales      |
     |          17 | Mark Morgan   | Bellingen | Delivery   |
     |           9 | Andy Smith    | Nambucca  | Delivery   |
     |           8 | June Wilson   | Bellingen | Sales      |
     +-------------+---------------+-----------+------------+
     5 rows in set (0.00 sec)

For general information about joins in MySQL, see join.

When the 'PARTITION' option is used with 'DELETE'.
statements, only those partitions (and subpartitions, if any) listed
with the option are checked for rows to be deleted.  Any other
partitions are ignored, as shown here:

     mysql> SELECT * FROM employees WHERE fname LIKE 'j%';
     +----+-------+--------+----------+---------------+
     | id | fname | lname  | store_id | department_id |
     +----+-------+--------+----------+---------------+
     |  4 | Jim   | Smith  |        2 |             4 |
     |  8 | June  | Wilson |        3 |             1 |
     | 11 | Jill  | Stone  |        1 |             4 |
     +----+-------+--------+----------+---------------+
     3 rows in set (0.00 sec)

     mysql> DELETE FROM employees PARTITION (p0, p1)
         ->     WHERE fname LIKE 'j%';
     Query OK, 2 rows affected (0.09 sec)

     mysql> SELECT * FROM employees WHERE fname LIKE 'j%';
     +----+-------+-------+----------+---------------+
     | id | fname | lname | store_id | department_id |
     +----+-------+-------+----------+---------------+
     | 11 | Jill  | Stone |        1 |             4 |
     +----+-------+-------+----------+---------------+
     1 row in set (0.00 sec)

Only the two rows in partitions 'p0' and 'p1' matching the 'WHERE'
condition were deleted.  As you can see from the result when the
'SELECT' is run a second time, there remains a row in the table
matching the 'WHERE' condition, but residing in a different partition
('p2').

'UPDATE' statements using explicit partition selection
behave in the same way; only rows in the partitions referenced by the
'PARTITION' option are considered when determining the rows to be
updated, as can be seen by executing the following statements:

     mysql> UPDATE employees PARTITION (p0)
         ->     SET store_id = 2 WHERE fname = 'Jill';
     Query OK, 0 rows affected (0.00 sec)
     Rows matched: 0  Changed: 0  Warnings: 0

     mysql> SELECT * FROM employees WHERE fname = 'Jill';
     +----+-------+-------+----------+---------------+
     | id | fname | lname | store_id | department_id |
     +----+-------+-------+----------+---------------+
     | 11 | Jill  | Stone |        1 |             4 |
     +----+-------+-------+----------+---------------+
     1 row in set (0.00 sec)

     mysql> UPDATE employees PARTITION (p2)
         ->     SET store_id = 2 WHERE fname = 'Jill';
     Query OK, 1 row affected (0.09 sec)
     Rows matched: 1  Changed: 1  Warnings: 0

     mysql> SELECT * FROM employees WHERE fname = 'Jill';
     +----+-------+-------+----------+---------------+
     | id | fname | lname | store_id | department_id |
     +----+-------+-------+----------+---------------+
     | 11 | Jill  | Stone |        2 |             4 |
     +----+-------+-------+----------+---------------+
     1 row in set (0.00 sec)

In the same way, when 'PARTITION' is used with 'DELETE',
only rows in the partition or partitions named in the partition list are
checked for deletion.

For statements that insert rows, the behavior differs in that failure to
find a suitable partition causes the statement to fail.  This is true
for both 'INSERT' and 'REPLACE'.
statements, as shown here:

     mysql> INSERT INTO employees PARTITION (p2) VALUES (20, 'Jan', 'Jones', 1, 3);
     ERROR 1729 (HY000): Found a row not matching the given partition set
     mysql> INSERT INTO employees PARTITION (p3) VALUES (20, 'Jan', 'Jones', 1, 3);
     Query OK, 1 row affected (0.07 sec)

     mysql> REPLACE INTO employees PARTITION (p0) VALUES (20, 'Jan', 'Jones', 3, 2);
     ERROR 1729 (HY000): Found a row not matching the given partition set

     mysql> REPLACE INTO employees PARTITION (p3) VALUES (20, 'Jan', 'Jones', 3, 2);
     Query OK, 2 rows affected (0.09 sec)

For statements that write multiple rows to a partitioned table that uses
the 'InnoDB' storage engine: If any row in
the list following 'VALUES' cannot be written to one of the partitions
specified in the PARTITION_NAMES list, the entire statement fails and no
rows are written.  This is shown for 'INSERT' statements
in the following example, reusing the 'employees' table created
previously:

     mysql> ALTER TABLE employees
         ->     REORGANIZE PARTITION p3 INTO (
         ->         PARTITION p3 VALUES LESS THAN (20),
         ->         PARTITION p4 VALUES LESS THAN (25),
         ->         PARTITION p5 VALUES LESS THAN MAXVALUE
         ->     );
     Query OK, 6 rows affected (2.09 sec)
     Records: 6  Duplicates: 0  Warnings: 0

     mysql> SHOW CREATE TABLE employees\G
     *************************** 1. row ***************************
            Table: employees
     Create Table: CREATE TABLE `employees` (
       `id` int(11) NOT NULL AUTO_INCREMENT,
       `fname` varchar(25) NOT NULL,
       `lname` varchar(25) NOT NULL,
       `store_id` int(11) NOT NULL,
       `department_id` int(11) NOT NULL,
       PRIMARY KEY (`id`)
     ) ENGINE=InnoDB AUTO_INCREMENT=27 DEFAULT CHARSET=latin1
     /*!50100 PARTITION BY RANGE (id)
     (PARTITION p0 VALUES LESS THAN (5) ENGINE = InnoDB,
      PARTITION p1 VALUES LESS THAN (10) ENGINE = InnoDB,
      PARTITION p2 VALUES LESS THAN (15) ENGINE = InnoDB,
      PARTITION p3 VALUES LESS THAN (20) ENGINE = InnoDB,
      PARTITION p4 VALUES LESS THAN (25) ENGINE = InnoDB,
      PARTITION p5 VALUES LESS THAN MAXVALUE ENGINE = InnoDB) */
     1 row in set (0.00 sec)

     mysql> INSERT INTO employees PARTITION (p3, p4) VALUES
         ->     (24, 'Tim', 'Greene', 3, 1),  (26, 'Linda', 'Mills', 2, 1);
     ERROR 1729 (HY000): Found a row not matching the given partition set

     mysql> INSERT INTO employees PARTITION (p3, p4. p5) VALUES
         ->     (24, 'Tim', 'Greene', 3, 1),  (26, 'Linda', 'Mills', 2, 1);
     Query OK, 2 rows affected (0.06 sec)
     Records: 2  Duplicates: 0  Warnings: 0

The preceding is true for both 'INSERT' statements and
'REPLACE' statements that write multiple rows.

In MySQL 5.7.1 and later, partition selection is disabled for tables
employing a storage engine that supplies automatic partitioning, such as
'NDB'.  (Bug #14827952)

22.6 Restrictions and Limitations on Partitioning
=================================================

This section discusses current restrictions and limitations on MySQL
partitioning support.

Prohibited constructs

The following constructs are not permitted in partitioning expressions:

   * Stored procedures, stored functions, UDFs, or plugins.

   * Declared variables or user variables.

For a list of SQL functions which are permitted in partitioning
expressions, see partitioning-limitations-functions.

Arithmetic and logical operators

Use of the arithmetic operators '+', '-', and '*' is permitted in
partitioning expressions.  However, the result must be an integer value
or 'NULL' (except in the case of '[LINEAR] KEY' partitioning, as
discussed elsewhere in this chapter; see partitioning-types, for
more information).

The 'DIV' operator is also supported, and the '/' operator is not
permitted.  (Bug #30188, Bug #33182)

The bit operators '|', '&', '^', '<<', '>>', and '~' are not permitted
in partitioning expressions.

HANDLER statements

Previously, the 'HANDLER' statement was not supported
with partitioned tables.  This limitation is removed beginning with
MySQL 5.7.1.

Server SQL mode

Tables employing user-defined partitioning do not preserve the SQL mode
in effect at the time that they were created.  As discussed in
sql-mode, the results of many MySQL functions and operators may change
according to the server SQL mode.  Therefore, a change in the SQL mode
at any time after the creation of partitioned tables may lead to major
changes in the behavior of such tables, and could easily lead to
corruption or loss of data.  For these reasons, _it is strongly
recommended that you never change the server SQL mode after creating
partitioned tables_.

Examples

The following examples illustrate some changes in behavior of
partitioned tables due to a change in the server SQL mode:

  1. Error handling

     Suppose that you create a partitioned table whose partitioning
     expression is one such as 'COLUMN DIV 0' or 'COLUMN MOD 0', as
     shown here:

          mysql> CREATE TABLE tn (c1 INT)
              ->     PARTITION BY LIST(1 DIV c1) (
              ->       PARTITION p0 VALUES IN (NULL),
              ->       PARTITION p1 VALUES IN (1)
              -> );
          Query OK, 0 rows affected (0.05 sec)

     The default behavior for MySQL is to return 'NULL' for the result
     of a division by zero, without producing any errors:

          mysql> SELECT @@sql_mode;
          +------------+
          | @@sql_mode |
          +------------+
          |            |
          +------------+
          1 row in set (0.00 sec)

          mysql> INSERT INTO tn VALUES (NULL), (0), (1);
          Query OK, 3 rows affected (0.00 sec)
          Records: 3  Duplicates: 0  Warnings: 0

     However, changing the server SQL mode to treat division by zero as
     an error and to enforce strict error handling causes the same
     'INSERT' statement to fail, as shown here:

          mysql> SET sql_mode='STRICT_ALL_TABLES,ERROR_FOR_DIVISION_BY_ZERO';
          Query OK, 0 rows affected (0.00 sec)

          mysql> INSERT INTO tn VALUES (NULL), (0), (1);
          ERROR 1365 (22012): Division by 0

  2. Table accessibility

     Sometimes a change in the server SQL mode can make partitioned
     tables unusable.  The following 'CREATE TABLE'.
     statement can be executed successfully only if the
     'NO_UNSIGNED_SUBTRACTION' mode is in effect:

          mysql> SELECT @@sql_mode;
          +------------+
          | @@sql_mode |
          +------------+
          |            |
          +------------+
          1 row in set (0.00 sec)

          mysql> CREATE TABLE tu (c1 BIGINT UNSIGNED)
              ->   PARTITION BY RANGE(c1 - 10) (
              ->     PARTITION p0 VALUES LESS THAN (-5),
              ->     PARTITION p1 VALUES LESS THAN (0),
              ->     PARTITION p2 VALUES LESS THAN (5),
              ->     PARTITION p3 VALUES LESS THAN (10),
              ->     PARTITION p4 VALUES LESS THAN (MAXVALUE)
              -> );
          ERROR 1563 (HY000): Partition constant is out of partition function domain

          mysql> SET sql_mode='NO_UNSIGNED_SUBTRACTION';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT @@sql_mode;
          +-------------------------+
          | @@sql_mode              |
          +-------------------------+
          | NO_UNSIGNED_SUBTRACTION |
          +-------------------------+
          1 row in set (0.00 sec)

          mysql> CREATE TABLE tu (c1 BIGINT UNSIGNED)
              ->   PARTITION BY RANGE(c1 - 10) (
              ->     PARTITION p0 VALUES LESS THAN (-5),
              ->     PARTITION p1 VALUES LESS THAN (0),
              ->     PARTITION p2 VALUES LESS THAN (5),
              ->     PARTITION p3 VALUES LESS THAN (10),
              ->     PARTITION p4 VALUES LESS THAN (MAXVALUE)
              -> );
          Query OK, 0 rows affected (0.05 sec)

     If you remove the 'NO_UNSIGNED_SUBTRACTION' server SQL mode after
     creating 'tu', you may no longer be able to access this table:

          mysql> SET sql_mode='';
          Query OK, 0 rows affected (0.00 sec)

          mysql> SELECT * FROM tu;
          ERROR 1563 (HY000): Partition constant is out of partition function domain
          mysql> INSERT INTO tu VALUES (20);
          ERROR 1563 (HY000): Partition constant is out of partition function domain

     See also sql-mode.

Server SQL modes also impact replication of partitioned tables.
Disparate SQL modes on master and slave can lead to partitioning
expressions being evaluated differently; this can cause the distribution
of data among partitions to be different in the master's and slave's
copies of a given table, and may even cause inserts into partitioned
tables that succeed on the master to fail on the slave.  For best
results, you should always use the same server SQL mode on the master
and on the slave.

Performance considerations

Some effects of partitioning operations on performance are given in the
following list:

   * File system operations

     Partitioning and repartitioning operations (such as 'ALTER TABLE'
     with 'PARTITION BY ...',
     'REORGANIZE PARTITION', or 'REMOVE PARTITIONING') depend on file
     system operations for their implementation.  This means that the
     speed of these operations is affected by such factors as file
     system type and characteristics, disk speed, swap space, file
     handling efficiency of the operating system, and MySQL server
     options and variables that relate to file handling.  In particular,
     you should make sure that 'large_files_support' is enabled and that
     'open_files_limit' is set properly.  For partitioned tables using
     the 'MyISAM' storage engine, increasing 'myisam_max_sort_file_size'
     may improve performance; partitioning and repartitioning operations
     involving 'InnoDB' tables may be made more efficient by enabling
     'innodb_file_per_table'.

     See also partitioning-limitations-max-partitions.

   * MyISAM and partition file descriptor usage

     For a partitioned 'MyISAM' table,
     MySQL uses 2 file descriptors for each partition, for each such
     table that is open.  This means that you need many more file
     descriptors to perform operations on a partitioned 'MyISAM' table
     than on a table which is identical to it except that the latter
     table is not partitioned, particularly when performing 'ALTER TABLE'
     operations.

     Assume a 'MyISAM' table 't' with 100 partitions, such as the table
     created by this SQL statement:

          CREATE TABLE t (c1 VARCHAR(50))
          PARTITION BY KEY (c1) PARTITIONS 100
          ENGINE=MYISAM;

     *Note*:

     For brevity, we use 'KEY' partitioning for the table shown in this
     example, but file descriptor usage as described here applies to all
     partitioned 'MyISAM' tables, regardless of the type of partitioning
     that is employed.  Partitioned tables using other storage engines
     such as 'InnoDB' are not affected by
     this issue.

     Now assume that you wish to repartition 't' so that it has 101
     partitions, using the statement shown here:

          ALTER TABLE t PARTITION BY KEY (c1) PARTITIONS 101;

     To process this 'ALTER TABLE' statement, MySQL uses 402 file
     descriptors--that is, two for each of the 100 original partitions,
     plus two for each of the 101 new partitions.  This is because all
     partitions (old and new) must be opened concurrently during the
     reorganization of the table data.  It is recommended that, if you
     expect to perform such operations, you should make sure that
     '--open-files-limit' is not set too low to accommodate them.

   * Table locks

     Generally, the process executing a partitioning operation on a
     table takes a write lock on the table.  Reads from such tables are
     relatively unaffected; pending 'INSERT' and
     'UPDATE' operations are performed as soon as the
     partitioning operation has completed.  For 'InnoDB'-specific
     exceptions to this limitation, see online-ddl-partitioning.

   * Storage engine

     Partitioning operations, queries, and update operations generally
     tend to be faster with 'MyISAM' tables than with 'InnoDB' or
     'NDB' tables.

   * Indexes; partition pruning

     As with nonpartitioned tables, proper use of indexes can speed up
     queries on partitioned tables significantly.  In addition,
     designing partitioned tables and queries on these tables to take
     advantage of _partition pruning_ can improve performance
     dramatically.  See partitioning-pruning, for more
     information.

     Previously, index condition pushdown was not supported for
     partitioned tables.  This limitation was removed in MySQL 5.7.3.
     See index-condition-pushdown-optimization.

   * Performance with LOAD DATA

     In MySQL 5.7, see 'LOAD DATA' uses buffering to
     improve performance.  You should be aware that the buffer uses 130
     KB memory per partition to achieve this.

Maximum number of partitions

The maximum possible number of partitions for a given table not using
the 'NDB' storage engine is 8192.  This number
includes subpartitions.

The maximum possible number of user-defined partitions for a table using
the 'NDB' storage engine is determined according
to the version of the NDB Cluster software being used, the number of
data nodes, and other factors.  See
mysql-cluster-nodes-groups-user-partitioning, for more information.

If, when creating tables with a large number of partitions (but less
than the maximum), you encounter an error message such as 'Got error ...
from storage engine: Out of resources when opening file', you may be
able to address the issue by increasing the value of the
'open_files_limit' system variable.  However, this is dependent on the
operating system, and may not be possible or advisable on all platforms;
see not-enough-file-handles, for more information.  In some
cases, using large numbers (hundreds) of partitions may also not be
advisable due to other concerns, so using more partitions does not
automatically lead to better results.

See also partitioning-limitations-file-system-ops.

Query cache not supported

The query cache is not supported for partitioned tables, and is
automatically disabled for queries involving partitioned tables.  The
query cache cannot be enabled for such queries.

Per-partition key caches

In MySQL 5.7, key caches are supported for partitioned 'MyISAM'
tables, using the 'CACHE INDEX'
and 'LOAD INDEX INTO CACHE' statements.
Key caches may be defined for one, several, or all partitions, and
indexes for one, several, or all partitions may be preloaded into key
caches.

Foreign keys not supported for partitioned InnoDB tables

Partitioned tables using the 'InnoDB'.
storage engine do not support foreign keys.  More specifically, this
means that the following two statements are true:

  1. No definition of an 'InnoDB' table employing user-defined
     partitioning may contain foreign key references; no 'InnoDB' table
     whose definition contains foreign key references may be
     partitioned.

  2. No 'InnoDB' table definition may contain a foreign key reference to
     a user-partitioned table; no 'InnoDB' table with user-defined
     partitioning may contain columns referenced by foreign keys.

The scope of the restrictions just listed includes all tables that use
the 'InnoDB' storage engine.  'CREATE TABLE'
and 'ALTER TABLE'.
statements that would result in tables violating these restrictions are
not allowed.

ALTER TABLE ...  ORDER BY

An 'ALTER TABLE ... ORDER BY COLUMN' statement run against a partitioned
table causes ordering of rows only within each partition.

Effects on REPLACE statements by modification of primary keys

It can be desirable in some cases (see
partitioning-limitations-partitioning-keys-unique-keys) to modify a
table's primary key.  Be aware that, if your application uses
'REPLACE' statements and you do this, the results of these
statements can be drastically altered.  See replace, for more
information and an example.

FULLTEXT indexes

Partitioned tables do not support 'FULLTEXT' indexes or searches, even
for partitioned tables employing the 'InnoDB'
or 'MyISAM' storage
engine.

Spatial columns

Columns with spatial data types such as 'POINT' or 'GEOMETRY' cannot be
used in partitioned tables.

Temporary tables

Temporary tables cannot be partitioned.  (Bug #17497)

Log tables

It is not possible to partition the log tables; an 'ALTER TABLE ... PARTITION BY ...'
statement on
such a table fails with an error.

Data type of partitioning key

A partitioning key must be either an integer column or an expression
that resolves to an integer.  Expressions employing 'ENUM'.
columns cannot be used.  The column or expression value may also be
'NULL'.  (See partitioning-handling-nulls.)

There are two exceptions to this restriction:

  1. When partitioning by ['LINEAR'] 'KEY', it is possible to use
     columns of any valid MySQL data type other than 'TEXT'.
     or 'BLOB' as partitioning keys, because MySQL's
     internal key-hashing functions produce the correct data type from
     these types.  For example, the following two 'CREATE TABLE'
     statements are valid:

          CREATE TABLE tkc (c1 CHAR)
          PARTITION BY KEY(c1)
          PARTITIONS 4;

          CREATE TABLE tke
              ( c1 ENUM('red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet') )
          PARTITION BY LINEAR KEY(c1)
          PARTITIONS 6;

  2. When partitioning by 'RANGE COLUMNS' or 'LIST COLUMNS', it is
     possible to use string, see 'DATE', and
     'DATETIME' columns.  For example, each of the following
     'CREATE TABLE' statements is valid:

          CREATE TABLE rc (c1 INT, c2 DATE)
          PARTITION BY RANGE COLUMNS(c2) (
              PARTITION p0 VALUES LESS THAN('1990-01-01'),
              PARTITION p1 VALUES LESS THAN('1995-01-01'),
              PARTITION p2 VALUES LESS THAN('2000-01-01'),
              PARTITION p3 VALUES LESS THAN('2005-01-01'),
              PARTITION p4 VALUES LESS THAN(MAXVALUE)
          );

          CREATE TABLE lc (c1 INT, c2 CHAR(1))
          PARTITION BY LIST COLUMNS(c2) (
              PARTITION p0 VALUES IN('a', 'd', 'g', 'j', 'm', 'p', 's', 'v', 'y'),
              PARTITION p1 VALUES IN('b', 'e', 'h', 'k', 'n', 'q', 't', 'w', 'z'),
              PARTITION p2 VALUES IN('c', 'f', 'i', 'l', 'o', 'r', 'u', 'x', NULL)
          );

Neither of the preceding exceptions applies to 'BLOB' or
'TEXT' column types.

Subqueries

A partitioning key may not be a subquery, even if that subquery resolves
to an integer value or 'NULL'.

Issues with subpartitions

Subpartitions must use 'HASH' or 'KEY' partitioning.  Only 'RANGE' and
'LIST' partitions may be subpartitioned; 'HASH' and 'KEY' partitions
cannot be subpartitioned.

'SUBPARTITION BY KEY' requires that the subpartitioning column or
columns be specified explicitly, unlike the case with 'PARTITION BY
KEY', where it can be omitted (in which case the table's primary key
column is used by default).  Consider the table created by this
statement:

     CREATE TABLE ts (
         id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(30)
     );

You can create a table having the same columns, partitioned by 'KEY',
using a statement such as this one:

     CREATE TABLE ts (
         id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(30)
     )
     PARTITION BY KEY()
     PARTITIONS 4;

The previous statement is treated as though it had been written like
this, with the table's primary key column used as the partitioning
column:

     CREATE TABLE ts (
         id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(30)
     )
     PARTITION BY KEY(id)
     PARTITIONS 4;

However, the following statement that attempts to create a
subpartitioned table using the default column as the subpartitioning
column fails, and the column must be specified for the statement to
succeed, as shown here:

     mysql> CREATE TABLE ts (
         ->     id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         ->     name VARCHAR(30)
         -> )
         -> PARTITION BY RANGE(id)
         -> SUBPARTITION BY KEY()
         -> SUBPARTITIONS 4
         -> (
         ->     PARTITION p0 VALUES LESS THAN (100),
         ->     PARTITION p1 VALUES LESS THAN (MAXVALUE)
         -> );
     ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that
     corresponds to your MySQL server version for the right syntax to use near ')

     mysql> CREATE TABLE ts (
         ->     id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
         ->     name VARCHAR(30)
         -> )
         -> PARTITION BY RANGE(id)
         -> SUBPARTITION BY KEY(id)
         -> SUBPARTITIONS 4
         -> (
         ->     PARTITION p0 VALUES LESS THAN (100),
         ->     PARTITION p1 VALUES LESS THAN (MAXVALUE)
         -> );
     Query OK, 0 rows affected (0.07 sec)

This is a known issue (see Bug #51470).

DATA DIRECTORY and INDEX DIRECTORY options

'DATA DIRECTORY' and 'INDEX DIRECTORY' are subject to the following
restrictions when used with partitioned tables:

   * Table-level 'DATA DIRECTORY' and 'INDEX DIRECTORY' options are
     ignored (see Bug #32091).

   * On Windows, the 'DATA DIRECTORY' and 'INDEX DIRECTORY' options are
     not supported for individual partitions or subpartitions of
     'MyISAM' tables.  However, you can use
     'DATA DIRECTORY' for individual partitions or subpartitions of
     'InnoDB' tables.

Repairing and rebuilding partitioned tables

The statements 'CHECK TABLE', 'OPTIMIZE TABLE',
see 'ANALYZE TABLE', and 'REPAIR TABLE'
are supported for partitioned tables.

In addition, you can use 'ALTER TABLE ... REBUILD PARTITION' to rebuild
one or more partitions of a partitioned table; 'ALTER TABLE ...
REORGANIZE PARTITION' also causes partitions to be rebuilt.  See
alter-table, for more information about these two statements.

Starting in MySQL 5.7.2, 'ANALYZE', 'CHECK', 'OPTIMIZE', 'REPAIR', and
'TRUNCATE' operations are supported with subpartitions.  'REBUILD' was
also accepted syntax prior to MySQL 5.7.5, although this had no effect.
(Bug #19075411, Bug #73130) See also
alter-table-partition-operations.

See 'mysqlcheck', 'myisamchk', and
'myisampack' are not supported with partitioned tables.

FOR EXPORT option (FLUSH TABLES)

The 'FLUSH TABLES' statement's 'FOR EXPORT' option is not supported for
partitioned 'InnoDB' tables in MySQL 5.7.4 and earlier.  (Bug #16943907)

22.6.1 Partitioning Keys, Primary Keys, and Unique Keys
-------------------------------------------------------

This section discusses the relationship of partitioning keys with
primary keys and unique keys.  The rule governing this relationship can
be expressed as follows: All columns used in the partitioning expression
for a partitioned table must be part of every unique key that the table
may have.

In other words, _every unique key on the table must use every column in
the table's partitioning expression_.  (This also includes the table's
primary key, since it is by definition a unique key.  This particular
case is discussed later in this section.)  For example, each of the
following table creation statements is invalid:

     CREATE TABLE t1 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         UNIQUE KEY (col1, col2)
     )
     PARTITION BY HASH(col3)
     PARTITIONS 4;

     CREATE TABLE t2 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         UNIQUE KEY (col1),
         UNIQUE KEY (col3)
     )
     PARTITION BY HASH(col1 + col3)
     PARTITIONS 4;

In each case, the proposed table would have at least one unique key that
does not include all columns used in the partitioning expression.

Each of the following statements is valid, and represents one way in
which the corresponding invalid table creation statement could be made
to work:

     CREATE TABLE t1 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         UNIQUE KEY (col1, col2, col3)
     )
     PARTITION BY HASH(col3)
     PARTITIONS 4;

     CREATE TABLE t2 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         UNIQUE KEY (col1, col3)
     )
     PARTITION BY HASH(col1 + col3)
     PARTITIONS 4;

This example shows the error produced in such cases:

     mysql> CREATE TABLE t3 (
         ->     col1 INT NOT NULL,
         ->     col2 DATE NOT NULL,
         ->     col3 INT NOT NULL,
         ->     col4 INT NOT NULL,
         ->     UNIQUE KEY (col1, col2),
         ->     UNIQUE KEY (col3)
         -> )
         -> PARTITION BY HASH(col1 + col3)
         -> PARTITIONS 4;
     ERROR 1491 (HY000): A PRIMARY KEY must include all columns in the table's partitioning function

The 'CREATE TABLE' statement fails because both
'col1' and 'col3' are included in the proposed partitioning key, but
neither of these columns is part of both of unique keys on the table.
This shows one possible fix for the invalid table definition:

     mysql> CREATE TABLE t3 (
         ->     col1 INT NOT NULL,
         ->     col2 DATE NOT NULL,
         ->     col3 INT NOT NULL,
         ->     col4 INT NOT NULL,
         ->     UNIQUE KEY (col1, col2, col3),
         ->     UNIQUE KEY (col3)
         -> )
         -> PARTITION BY HASH(col3)
         -> PARTITIONS 4;
     Query OK, 0 rows affected (0.05 sec)

In this case, the proposed partitioning key 'col3' is part of both
unique keys, and the table creation statement succeeds.

The following table cannot be partitioned at all, because there is no
way to include in a partitioning key any columns that belong to both
unique keys:

     CREATE TABLE t4 (
         col1 INT NOT NULL,
         col2 INT NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         UNIQUE KEY (col1, col3),
         UNIQUE KEY (col2, col4)
     );

Since every primary key is by definition a unique key, this restriction
also includes the table's primary key, if it has one.  For example, the
next two statements are invalid:

     CREATE TABLE t5 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         PRIMARY KEY(col1, col2)
     )
     PARTITION BY HASH(col3)
     PARTITIONS 4;

     CREATE TABLE t6 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         PRIMARY KEY(col1, col3),
         UNIQUE KEY(col2)
     )
     PARTITION BY HASH( YEAR(col2) )
     PARTITIONS 4;

In both cases, the primary key does not include all columns referenced
in the partitioning expression.  However, both of the next two
statements are valid:

     CREATE TABLE t7 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         PRIMARY KEY(col1, col2)
     )
     PARTITION BY HASH(col1 + YEAR(col2))
     PARTITIONS 4;

     CREATE TABLE t8 (
         col1 INT NOT NULL,
         col2 DATE NOT NULL,
         col3 INT NOT NULL,
         col4 INT NOT NULL,
         PRIMARY KEY(col1, col2, col4),
         UNIQUE KEY(col2, col1)
     )
     PARTITION BY HASH(col1 + YEAR(col2))
     PARTITIONS 4;

If a table has no unique keys--this includes having no primary key--then
this restriction does not apply, and you may use any column or columns
in the partitioning expression as long as the column type is compatible
with the partitioning type.

For the same reason, you cannot later add a unique key to a partitioned
table unless the key includes all columns used by the table's
partitioning expression.  Consider the partitioned table created as
shown here:

     mysql> CREATE TABLE t_no_pk (c1 INT, c2 INT)
         ->     PARTITION BY RANGE(c1) (
         ->         PARTITION p0 VALUES LESS THAN (10),
         ->         PARTITION p1 VALUES LESS THAN (20),
         ->         PARTITION p2 VALUES LESS THAN (30),
         ->         PARTITION p3 VALUES LESS THAN (40)
         ->     );
     Query OK, 0 rows affected (0.12 sec)

It is possible to add a primary key to 't_no_pk' using either of these
'ALTER TABLE' statements:

     #  possible PK
     mysql> ALTER TABLE t_no_pk ADD PRIMARY KEY(c1);
     Query OK, 0 rows affected (0.13 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     # drop this PK
     mysql> ALTER TABLE t_no_pk DROP PRIMARY KEY;
     Query OK, 0 rows affected (0.10 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     #  use another possible PK
     mysql> ALTER TABLE t_no_pk ADD PRIMARY KEY(c1, c2);
     Query OK, 0 rows affected (0.12 sec)
     Records: 0  Duplicates: 0  Warnings: 0

     # drop this PK
     mysql> ALTER TABLE t_no_pk DROP PRIMARY KEY;
     Query OK, 0 rows affected (0.09 sec)
     Records: 0  Duplicates: 0  Warnings: 0

However, the next statement fails, because 'c1' is part of the
partitioning key, but is not part of the proposed primary key:

     #  fails with error 1503
     mysql> ALTER TABLE t_no_pk ADD PRIMARY KEY(c2);
     ERROR 1503 (HY000): A PRIMARY KEY must include all columns in the table's partitioning function

Since 't_no_pk' has only 'c1' in its partitioning expression, attempting
to adding a unique key on 'c2' alone fails.  However, you can add a
unique key that uses both 'c1' and 'c2'.

These rules also apply to existing nonpartitioned tables that you wish
to partition using 'ALTER TABLE ... PARTITION BY'.
Consider a table 'np_pk' created as
shown here:

     mysql> CREATE TABLE np_pk (
         ->     id INT NOT NULL AUTO_INCREMENT,
         ->     name VARCHAR(50),
         ->     added DATE,
         ->     PRIMARY KEY (id)
         -> );
     Query OK, 0 rows affected (0.08 sec)

The following 'ALTER TABLE'.
statement fails with an error, because the 'added' column is not part of
any unique key in the table:

     mysql> ALTER TABLE np_pk
         ->     PARTITION BY HASH( TO_DAYS(added) )
         ->     PARTITIONS 4;
     ERROR 1503 (HY000): A PRIMARY KEY must include all columns in the table's partitioning function

However, this statement using the 'id' column for the partitioning
column is valid, as shown here:

     mysql> ALTER TABLE np_pk
         ->     PARTITION BY HASH(id)
         ->     PARTITIONS 4;
     Query OK, 0 rows affected (0.11 sec)
     Records: 0  Duplicates: 0  Warnings: 0

In the case of 'np_pk', the only column that may be used as part of a
partitioning expression is 'id'; if you wish to partition this table
using any other column or columns in the partitioning expression, you
must first modify the table, either by adding the desired column or
columns to the primary key, or by dropping the primary key altogether.

22.6.2 Partitioning Limitations Relating to Storage Engines
-----------------------------------------------------------

The following limitations apply to the use of storage engines with
user-defined partitioning of tables.

MERGE storage engine

User-defined partitioning and the 'MERGE' storage engine are not
compatible.  Tables using the 'MERGE' storage engine cannot be
partitioned.  Partitioned tables cannot be merged.

FEDERATED storage engine

Partitioning of 'FEDERATED' tables is not supported; it is not possible
to create partitioned 'FEDERATED' tables.

CSV storage engine

Partitioned tables using the 'CSV' storage engine are not supported; it
is not possible to create partitioned 'CSV' tables.

InnoDB storage engine

'InnoDB' foreign keys and MySQL
partitioning are not compatible.  Partitioned 'InnoDB' tables cannot
have foreign key references, nor can they have columns referenced by
foreign keys.  'InnoDB' tables which have or which are referenced by
foreign keys cannot be partitioned.

'InnoDB' does not support the use of multiple disks for subpartitions.
(This is currently supported only by 'MyISAM'.)

In addition, see 'ALTER TABLE ... OPTIMIZE PARTITION'
does not work correctly with
partitioned tables that use the 'InnoDB' storage engine.  Use 'ALTER
TABLE ... REBUILD PARTITION' and 'ALTER TABLE ... ANALYZE PARTITION',
instead, for such tables.  For more information, see
alter-table-partition-operations.

User-defined partitioning and the NDB storage engine (NDB Cluster)

Partitioning by 'KEY' (including 'LINEAR KEY') is the only type of
partitioning supported for the 'NDB' storage
engine.  It is not possible under normal circumstances in NDB Cluster to
create an NDB Cluster table using any partitioning type other than
['LINEAR'] 'KEY', and attempting to do so fails with an error.

_Exception (not for production)_: It is possible to override this
restriction by setting the 'new' system variable on NDB Cluster SQL
nodes to 'ON'.  If you choose to do this, you should be aware that
tables using partitioning types other than '[LINEAR] KEY' are not
supported in production.  _In such cases, you can create and use tables
with partitioning types other than 'KEY' or 'LINEAR KEY', but you do
this entirely at your own risk_.

The maximum number of partitions that can be defined for an 'NDB'
table depends on the number of data nodes and node groups
in the cluster, the version of the NDB Cluster software in use, and
other factors.  See
mysql-cluster-nodes-groups-user-partitioning, for more information.

As of MySQL NDB Cluster 7.5.2, the maximum amount of fixed-size data
that can be stored per partition in an 'NDB' table is 128 TB.
Previously, this was 16 GB.

'CREATE TABLE' and 'ALTER TABLE'
statements that would cause a
user-partitioned 'NDB' table not to meet either or
both of the following two requirements are not permitted, and fail with
an error:

  1. The table must have an explicit primary key.

  2. All columns listed in the table's partitioning expression must be
     part of the primary key.

Exception

If a user-partitioned 'NDB' table is created using
an empty column-list (that is, using 'PARTITION BY KEY()' or 'PARTITION
BY LINEAR KEY()'), then no explicit primary key is required.

Upgrading partitioned tables

When performing an upgrade, tables which are partitioned by 'KEY' and
which use any storage engine other than 'NDB' must
be dumped and reloaded.

Same storage engine for all partitions

All partitions of a partitioned table must use the same storage engine
and it must be the same storage engine used by the table as a whole.  In
addition, if one does not specify an engine on the table level, then one
must do either of the following when creating or altering a partitioned
table:

   * Do _not_ specify any engine for _any_ partition or subpartition

   * Specify the engine for _all_ partitions or subpartitions

22.6.3 Partitioning Limitations Relating to Functions
-----------------------------------------------------

This section discusses limitations in MySQL Partitioning relating
specifically to functions used in partitioning expressions.

Only the MySQL functions shown in the following list are allowed in
partitioning expressions:

   * 'ABS()'

   * 'CEILING()' (see partitioning-limitations-ceiling-floor)

   * 'DATEDIFF()'

   * 'DAY()'

   * 'DAYOFMONTH()'

   * 'DAYOFWEEK()'

   * 'DAYOFYEAR()'

   * 'EXTRACT()' (see partitioning-limitations-extract)

   * 'FLOOR()' (see partitioning-limitations-ceiling-floor)

   * 'HOUR()'

   * 'MICROSECOND()'

   * 'MINUTE()'

   * 'MOD()'

   * 'MONTH()'

   * 'QUARTER()'

   * 'SECOND()'

   * 'TIME_TO_SEC()'

   * 'TO_DAYS()'

   * 'TO_SECONDS()'

   * 'UNIX_TIMESTAMP()' (with 'TIMESTAMP' columns)

   * 'WEEKDAY()'

   * 'YEAR()'

   * 'YEARWEEK()'

In MySQL 5.7, partition pruning is supported for the 'TO_DAYS()',
'TO_SECONDS()', 'YEAR()', and 'UNIX_TIMESTAMP()' functions.  See
partitioning-pruning, for more information.

CEILING() and FLOOR()

Each of these functions returns an integer only if it is passed an
argument of an exact numeric type, such as one of the 'INT'
types or 'DECIMAL'.  This means,
for example, that the following 'CREATE TABLE'.
statement fails with an error, as shown here:

     mysql> CREATE TABLE t (c FLOAT) PARTITION BY LIST( FLOOR(c) )(
         ->     PARTITION p0 VALUES IN (1,3,5),
         ->     PARTITION p1 VALUES IN (2,4,6)
         -> );
     ERROR 1490 (HY000): The PARTITION function returns the wrong type

EXTRACT() function with WEEK specifier

The value returned by the 'EXTRACT()' function, when used as
'EXTRACT(WEEK FROM COL)', depends on the value of the
'default_week_format' system variable.  For this reason, 'EXTRACT()' is
not permitted as a partitioning function when it specifies the unit as
'WEEK'.  (Bug #54483)

See mathematical-functions, for more information about the
return types of these functions, as well as numeric-types.

22.6.4 Partitioning and Locking
-------------------------------

For storage engines such as 'MyISAM' that
actually execute table-level locks when executing DML or DDL statements,
such a statement in older versions of MySQL (5.6.5 and earlier) that
affected a partitioned table imposed a lock on the table as a whole;
that is, all partitions were locked until the statement was finished.
In MySQL 5.7, _partition lock pruning_ eliminates unneeded locks in many
cases, and most statements reading from or updating a partitioned
'MyISAM' table cause only the effected partitions to be locked.  For
example, a 'SELECT' from a partitioned 'MyISAM' table
locks only those partitions actually containing rows that satisfy the
'SELECT' statement's 'WHERE' condition are locked.

For statements affecting partitioned tables using storage engines such
as 'InnoDB', that employ row-level locking
and do not actually perform (or need to perform) the locks prior to
partition pruning, this is not an issue.

The next few paragraphs discuss the effects of partition lock pruning
for various MySQL statements on tables using storage engines that employ
table-level locks.

*Effects on DML statements*

'SELECT' statements (including those containing unions or
joins) lock only those partitions that actually need to be read.  This
also applies to 'SELECT ... PARTITION'.

An 'UPDATE' prunes locks only for tables on which no
partitioning columns are updated.

'REPLACE' and 'INSERT' lock only those
partitions having rows to be inserted or replaced.  However, if an
'AUTO_INCREMENT' value is generated for any partitioning column then all
partitions are locked.

'INSERT ... ON DUPLICATE KEY UPDATE' is
pruned as long as no partitioning column is updated.

'INSERT ... SELECT' locks only those partitions in
the source table that need to be read, although all partitions in the
target table are locked.

Locks imposed by 'LOAD DATA' statements on partitioned
tables cannot be pruned.

The presence of 'BEFORE INSERT' or 'BEFORE UPDATE' triggers using any
partitioning column of a partitioned table means that locks on 'INSERT'
and 'UPDATE' statements updating this table cannot be pruned, since the
trigger can alter its values: A 'BEFORE INSERT' trigger on any of the
table's partitioning columns means that locks set by 'INSERT' or
'REPLACE' cannot be pruned, since the 'BEFORE INSERT' trigger may change
a row's partitioning columns before the row is inserted, forcing the row
into a different partition than it would be otherwise.  A 'BEFORE
UPDATE' trigger on a partitioning column means that locks imposed by
'UPDATE' or 'INSERT ... ON DUPLICATE KEY UPDATE' cannot be pruned.

*Affected DDL statements*

'CREATE VIEW' does not cause any locks.

'ALTER TABLE ... EXCHANGE PARTITION'
prunes locks; only the exchanged table
and the exchanged partition are locked.

'ALTER TABLE ... TRUNCATE PARTITION'
prunes locks; only the partitions to
be emptied are locked.

In addition, see 'ALTER TABLE' statements take metadata
locks on the table level.

*Other statements*

'LOCK TABLES' cannot prune partition locks.

'CALL stored_procedure(EXPR)' supports lock pruning, but
evaluating EXPR does not.

'DO' and 'SET' statements do not support
partitioning lock pruning.

23 Stored Programs and Views
****************************

This chapter discusses stored programs and views, which are database
objects defined in terms of SQL code that is stored on the server for
later execution.

Stored programs include these objects:

   * Stored routines, that is, stored procedures and functions.  A
     stored procedure is invoked using the 'CALL'.
     statement.  A procedure does not have a return value but can modify
     its parameters for later inspection by the caller.  It can also
     generate result sets to be returned to the client program.  A
     stored function is used much like a built-in function.  you invoke
     it in an expression and it returns a value during expression
     evaluation.

   * Triggers.  A trigger is a named database object that is associated
     with a table and that is activated when a particular event occurs
     for the table, such as an insert or update.

   * Events.  An event is a task that the server runs according to
     schedule.

Views are stored queries that when referenced produce a result set.  A
view acts as a virtual table.

This chapter describes how to use stored programs and views.  The
following sections provide additional information about SQL syntax for
statements related to these objects:

   * For each object type, there are 'CREATE', 'ALTER', and 'DROP'
     statements that control which objects exist and how they are
     defined.  See sql-syntax-data-definition.

   * The 'CALL' statement is used to invoke stored
     procedures.  See call.

   * Stored program definitions include a body that may use compound
     statements, loops, conditionals, and declared variables.  See
     sql-syntax-compound-statements.

In MySQL, metadata changes to objects referred to by stored programs are
detected and cause automatic reparsing of the affected statements when
the program is next executed.  For more information, see
statement-caching.

23.1 Defining Stored Programs
=============================

Each stored program contains a body that consists of an SQL statement.
This statement may be a compound statement made up of several statements
separated by semicolon (';') characters.  For example, the following
stored procedure has a body made up of a 'BEGIN ... END'
block that contains a 'SET' statement
and a 'REPEAT' loop that itself contains another
'SET' statement:

     CREATE PROCEDURE dorepeat(p1 INT)
     BEGIN
       SET @x = 0;
       REPEAT SET @x = @x + 1; UNTIL @x > p1 END REPEAT;
     END;

If you use the 'mysql' client program to define a stored
program containing semicolon characters, a problem arises.  By default,
see 'mysql' itself recognizes the semicolon as a statement
delimiter, so you must redefine the delimiter temporarily to cause
'mysql' to pass the entire stored program definition to the
server.

To redefine the 'mysql' delimiter, use the 'delimiter'
command.  The following example shows how to do this for the
'dorepeat()' procedure just shown.  The delimiter is changed to '//' to
enable the entire definition to be passed to the server as a single
statement, and then restored to ';' before invoking the procedure.  This
enables the ';' delimiter used in the procedure body to be passed
through to the server rather than being interpreted by 'mysql'
itself.

     mysql> delimiter //

     mysql> CREATE PROCEDURE dorepeat(p1 INT)
         -> BEGIN
         ->   SET @x = 0;
         ->   REPEAT SET @x = @x + 1; UNTIL @x > p1 END REPEAT;
         -> END
         -> //
     Query OK, 0 rows affected (0.00 sec)

     mysql> delimiter ;

     mysql> CALL dorepeat(1000);
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT @x;
     +------+
     | @x   |
     +------+
     | 1001 |
     +------+
     1 row in set (0.00 sec)

You can redefine the delimiter to a string other than '//', and the
delimiter can consist of a single character or multiple characters.  You
should avoid the use of the backslash ('\') character because that is
the escape character for MySQL.

The following is an example of a function that takes a parameter,
performs an operation using an SQL function, and returns the result.  In
this case, it is unnecessary to use 'delimiter' because the function
definition contains no internal ';' statement delimiters:

     mysql> CREATE FUNCTION hello (s CHAR(20))
     mysql> RETURNS CHAR(50) DETERMINISTIC
         -> RETURN CONCAT('Hello, ',s,'!');
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT hello('world');
     +----------------+
     | hello('world') |
     +----------------+
     | Hello, world!  |
     +----------------+
     1 row in set (0.00 sec)

23.2 Using Stored Routines (Procedures and Functions)
=====================================================

MySQL supports stored routines (procedures and functions).  A stored
routine is a set of SQL statements that can be stored in the server.
Once this has been done, clients don't need to keep reissuing the
individual statements but can refer to the stored routine instead.

Stored routines require the 'proc' table in the 'mysql' database.  This
table is created during the MySQL installation procedure.  If you are
upgrading to MySQL 5.7 from an earlier version, be sure to update your
grant tables to make sure that the 'proc' table exists.  See
mysql-upgrade.

Stored routines can be particularly useful in certain situations:

   * When multiple client applications are written in different
     languages or work on different platforms, but need to perform the
     same database operations.

   * When security is paramount.  Banks, for example, use stored
     procedures and functions for all common operations.  This provides
     a consistent and secure environment, and routines can ensure that
     each operation is properly logged.  In such a setup, applications
     and users would have no access to the database tables directly, but
     can only execute specific stored routines.

Stored routines can provide improved performance because less
information needs to be sent between the server and the client.  The
tradeoff is that this does increase the load on the database server
because more of the work is done on the server side and less is done on
the client (application) side.  Consider this if many client machines
(such as Web servers) are serviced by only one or a few database
servers.

Stored routines also enable you to have libraries of functions in the
database server.  This is a feature shared by modern application
languages that enable such design internally (for example, by using
classes).  Using these client application language features is
beneficial for the programmer even outside the scope of database use.

MySQL follows the SQL:2003 syntax for stored routines, which is also
used by IBM's DB2.  All syntax described here is supported and any
limitations and extensions are documented where appropriate.

*Additional Resources*

   * You may find the Stored Procedures User Forum
     (http://forums.mysql.com/list.php?98) of use when working with
     stored procedures and functions.

   * For answers to some commonly asked questions regarding stored
     routines in MySQL, see faqs-stored-procs.

   * There are some restrictions on the use of stored routines.  See
     stored-program-restrictions.

   * Binary logging for stored routines takes place as described in
     stored-programs-logging.

23.2.1 Stored Routine Syntax
----------------------------

A stored routine is either a procedure or a function.  Stored routines
are created with the 'CREATE PROCEDURE' and
'CREATE FUNCTION' statements (see
create-procedure).  A procedure is invoked using a 'CALL'.
statement (see call), and can only pass back values using output
variables.  A function can be called from inside a statement just like
any other function (that is, by invoking the function's name), and can
return a scalar value.  The body of a stored routine can use compound
statements (see sql-syntax-compound-statements).

Stored routines can be dropped with the 'DROP PROCEDURE'
and 'DROP FUNCTION' statements
(see drop-procedure), and altered with the 'ALTER PROCEDURE'
and 'ALTER FUNCTION'.
statements (see alter-procedure).

A stored procedure or function is associated with a particular database.
This has several implications:

   * When the routine is invoked, an implicit 'USE DB_NAME' is performed
     (and undone when the routine terminates).  See 'USE'.
     statements within stored routines are not permitted.

   * You can qualify routine names with the database name.  This can be
     used to refer to a routine that is not in the current database.
     For example, to invoke a stored procedure 'p' or function 'f' that
     is associated with the 'test' database, you can say 'CALL test.p()'
     or 'test.f()'.

   * When a database is dropped, all stored routines associated with it
     are dropped as well.

Stored functions cannot be recursive.

Recursion in stored procedures is permitted but disabled by default.  To
enable recursion, set the 'max_sp_recursion_depth' server system
variable to a value greater than zero.  Stored procedure recursion
increases the demand on thread stack space.  If you increase the value
of 'max_sp_recursion_depth', it may be necessary to increase thread
stack size by increasing the value of 'thread_stack' at server startup.
See server-system-variables, for more information.

MySQL supports a very useful extension that enables the use of regular
'SELECT' statements (that is, without using cursors or
local variables) inside a stored procedure.  The result set of such a
query is simply sent directly to the client.  Multiple 'SELECT'
statements generate multiple result sets, so the client must use
a MySQL client library that supports multiple result sets.  This means
the client must use a client library from a version of MySQL at least as
recent as 4.1.  The client should also specify the
'CLIENT_MULTI_RESULTS' option when it connects.  For C programs, this
can be done with the 'mysql_real_connect()'. C
API function.  See mysql-real-connect, and
c-api-multiple-queries.

23.2.2 Stored Routines and MySQL Privileges
-------------------------------------------

The MySQL grant system takes stored routines into account as follows:

   * The 'CREATE ROUTINE' privilege is needed to create stored routines.

   * The 'ALTER ROUTINE' privilege is needed to alter or drop stored
     routines.  This privilege is granted automatically to the creator
     of a routine if necessary, and dropped from the creator when the
     routine is dropped.

   * The 'EXECUTE' privilege is required to execute stored routines.
     However, this privilege is granted automatically to the creator of
     a routine if necessary (and dropped from the creator when the
     routine is dropped).  Also, the default 'SQL SECURITY'
     characteristic for a routine is 'DEFINER', which enables users who
     have access to the database with which the routine is associated to
     execute the routine.

   * If the 'automatic_sp_privileges' system variable is 0, the
     'EXECUTE' and 'ALTER ROUTINE' privileges are not automatically
     granted to and dropped from the routine creator.

   * The creator of a routine is the account used to execute the
     'CREATE' statement for it.  This might not be the same as the
     account named as the 'DEFINER' in the routine definition.

The server manipulates the 'mysql.proc' table in response to statements
that create, alter, or drop stored routines.  It is not supported that
the server will notice manual manipulation of this table.

23.2.3 Stored Routine Metadata
------------------------------

Metadata about stored routines can be obtained as follows:

   * Query the 'ROUTINES' table of the
     'INFORMATION_SCHEMA' database.  See routines-table.

   * Use the 'SHOW CREATE PROCEDURE' and
     'SHOW CREATE FUNCTION' statements to
     see routine definitions.  See show-create-procedure.

   * Use the 'SHOW PROCEDURE STATUS' and
     'SHOW FUNCTION STATUS' statements to
     see routine characteristics.  See show-procedure-status.

23.2.4 Stored Procedures, Functions, Triggers, and LAST_INSERT_ID()
-------------------------------------------------------------------

Within the body of a stored routine (procedure or function) or a
trigger, the value of 'LAST_INSERT_ID()' changes the same way as for
statements executed outside the body of these kinds of objects (see
information-functions).  The effect of a stored routine or
trigger upon the value of 'LAST_INSERT_ID()' that is seen by following
statements depends on the kind of routine:

   * If a stored procedure executes statements that change the value of
     'LAST_INSERT_ID()', the changed value is seen by statements that
     follow the procedure call.

   * For stored functions and triggers that change the value, the value
     is restored when the function or trigger ends, so following
     statements do not see a changed value.

23.3 Using Triggers
===================

A trigger is a named database object that is associated with a table,
and that activates when a particular event occurs for the table.  Some
uses for triggers are to perform checks of values to be inserted into a
table or to perform calculations on values involved in an update.

A trigger is defined to activate when a statement inserts, updates, or
deletes rows in the associated table.  These row operations are trigger
events.  For example, rows can be inserted by 'INSERT' or
'LOAD DATA' statements, and an insert trigger
activates for each inserted row.  A trigger can be set to activate
either before or after the trigger event.  For example, you can have a
trigger activate before each row that is inserted into a table or after
each row that is updated.

*Important*:

MySQL triggers activate only for changes made to tables by SQL
statements.  This includes changes to base tables that underlie
updatable views.  Triggers do not activate for changes to tables made by
APIs that do not transmit SQL statements to the MySQL Server.  This
means that triggers are not activated by updates made using the
'NDB'. API.

Triggers are not activated by changes in 'INFORMATION_SCHEMA' or
'performance_schema' tables.  Those tables are actually views and
triggers are not permitted on views.

The following sections describe the syntax for creating and dropping
triggers, show some examples of how to use them, and indicate how to
obtain trigger metadata.

*Additional Resources*

   * You may find the Triggers User Forum
     (http://forums.mysql.com/list.php?100) of use when working with
     triggers.

   * For answers to commonly asked questions regarding triggers in
     MySQL, see faqs-triggers.

   * There are some restrictions on the use of triggers; see
     stored-program-restrictions.

   * Binary logging for triggers takes place as described in
     stored-programs-logging.

23.3.1 Trigger Syntax and Examples
----------------------------------

To create a trigger or drop a trigger, use the 'CREATE TRIGGER'
or 'DROP TRIGGER' statement,
described in create-trigger, and drop-trigger.

Here is a simple example that associates a trigger with a table, to
activate for 'INSERT' operations.  The trigger acts as an
accumulator, summing the values inserted into one of the columns of the
table.

     mysql> CREATE TABLE account (acct_num INT, amount DECIMAL(10,2));
     Query OK, 0 rows affected (0.03 sec)

     mysql> CREATE TRIGGER ins_sum BEFORE INSERT ON account
            FOR EACH ROW SET @sum = @sum + NEW.amount;
     Query OK, 0 rows affected (0.01 sec)

The 'CREATE TRIGGER' statement creates a trigger
named 'ins_sum' that is associated with the 'account' table.  It also
includes clauses that specify the trigger action time, the triggering
event, and what to do when the trigger activates:

   * The keyword 'BEFORE' indicates the trigger action time.  In this
     case, the trigger activates before each row inserted into the
     table.  The other permitted keyword here is 'AFTER'.

   * The keyword 'INSERT' indicates the trigger event; that is, the type
     of operation that activates the trigger.  In the example, see
     'INSERT' operations cause trigger activation.  You can
     also create triggers for 'DELETE' and
     'UPDATE' operations.

   * The statement following 'FOR EACH ROW' defines the trigger body;
     that is, the statement to execute each time the trigger activates,
     which occurs once for each row affected by the triggering event.
     In the example, the trigger body is a simple 'SET'
     that accumulates into a user variable the values
     inserted into the 'amount' column.  The statement refers to the
     column as 'NEW.amount' which means 'the value of the 'amount'
     column to be inserted into the new row.'

To use the trigger, set the accumulator variable to zero, execute an
'INSERT' statement, and then see what value the variable
has afterward:

     mysql> SET @sum = 0;
     mysql> INSERT INTO account VALUES(137,14.98),(141,1937.50),(97,-100.00);
     mysql> SELECT @sum AS 'Total amount inserted';
     +-----------------------+
     | Total amount inserted |
     +-----------------------+
     |               1852.48 |
     +-----------------------+

In this case, the value of '@sum' after the 'INSERT'.
statement has executed is '14.98 + 1937.50 - 100', or '1852.48'.

To destroy the trigger, use a 'DROP TRIGGER'.
statement.  You must specify the schema name if the trigger is not in
the default schema:

     mysql> DROP TRIGGER test.ins_sum;

If you drop a table, any triggers for the table are also dropped.

Trigger names exist in the schema namespace, meaning that all triggers
must have unique names within a schema.  Triggers in different schemas
can have the same name.

As of MySQL 5.7.2, it is possible to define multiple triggers for a
given table that have the same trigger event and action time.  For
example, you can have two 'BEFORE UPDATE' triggers for a table.  By
default, triggers that have the same trigger event and action time
activate in the order they were created.  To affect trigger order,
specify a clause after 'FOR EACH ROW' that indicates 'FOLLOWS' or
'PRECEDES' and the name of an existing trigger that also has the same
trigger event and action time.  With 'FOLLOWS', the new trigger
activates after the existing trigger.  With 'PRECEDES', the new trigger
activates before the existing trigger.

For example, the following trigger definition defines another 'BEFORE
INSERT' trigger for the 'account' table:

     mysql> CREATE TRIGGER ins_transaction BEFORE INSERT ON account
            FOR EACH ROW PRECEDES ins_sum
            SET
            @deposits = @deposits + IF(NEW.amount>0,NEW.amount,0),
            @withdrawals = @withdrawals + IF(NEW.amount<0,-NEW.amount,0);
     Query OK, 0 rows affected (0.01 sec)

This trigger, 'ins_transaction', is similar to 'ins_sum' but accumulates
deposits and withdrawals separately.  It has a 'PRECEDES' clause that
causes it to activate before 'ins_sum'; without that clause, it would
activate after 'ins_sum' because it is created after 'ins_sum'.

Before MySQL 5.7.2, there cannot be multiple triggers for a given table
that have the same trigger event and action time.  For example, you
cannot have two 'BEFORE UPDATE' triggers for a table.  To work around
this, you can define a trigger that executes multiple statements by
using the 'BEGIN ... END' compound statement construct
after 'FOR EACH ROW'.  (An example appears later in this section.)

Within the trigger body, the 'OLD' and 'NEW' keywords enable you to
access columns in the rows affected by a trigger.  'OLD' and 'NEW' are
MySQL extensions to triggers; they are not case-sensitive.

In an 'INSERT' trigger, only 'NEW.COL_NAME' can be used; there is no old
row.  In a 'DELETE' trigger, only 'OLD.COL_NAME' can be used; there is
no new row.  In an 'UPDATE' trigger, you can use 'OLD.COL_NAME' to refer
to the columns of a row before it is updated and 'NEW.COL_NAME' to refer
to the columns of the row after it is updated.

A column named with 'OLD' is read only.  You can refer to it (if you
have the 'SELECT' privilege), but not modify it.  You can
refer to a column named with 'NEW' if you have the 'SELECT' privilege
for it.  In a 'BEFORE' trigger, you can also change its value with 'SET
NEW.COL_NAME = VALUE' if you have the 'UPDATE' privilege for it.  This
means you can use a trigger to modify the values to be inserted into a
new row or used to update a row.  (Such a 'SET' statement has no effect
in an 'AFTER' trigger because the row change will have already
occurred.)

In a 'BEFORE' trigger, the 'NEW' value for an 'AUTO_INCREMENT' column is
0, not the sequence number that is generated automatically when the new
row actually is inserted.

By using the 'BEGIN ... END' construct, you can define
a trigger that executes multiple statements.  Within the 'BEGIN' block,
you also can use other syntax that is permitted within stored routines
such as conditionals and loops.  However, just as for stored routines,
if you use the 'mysql' program to define a trigger that
executes multiple statements, it is necessary to redefine the
'mysql' statement delimiter so that you can use the ';'
statement delimiter within the trigger definition.  The following
example illustrates these points.  It defines an 'UPDATE' trigger that
checks the new value to be used for updating each row, and modifies the
value to be within the range from 0 to 100.  This must be a 'BEFORE'
trigger because the value must be checked before it is used to update
the row:

     mysql> delimiter //
     mysql> CREATE TRIGGER upd_check BEFORE UPDATE ON account
            FOR EACH ROW
            BEGIN
                IF NEW.amount < 0 THEN
                    SET NEW.amount = 0;
                ELSEIF NEW.amount > 100 THEN
                    SET NEW.amount = 100;
                END IF;
            END;//
     mysql> delimiter ;

It can be easier to define a stored procedure separately and then invoke
it from the trigger using a simple 'CALL' statement.  This
is also advantageous if you want to execute the same code from within
several triggers.

There are limitations on what can appear in statements that a trigger
executes when activated:

   * The trigger cannot use the 'CALL' statement to invoke
     stored procedures that return data to the client or that use
     dynamic SQL. (Stored procedures are permitted to return data to the
     trigger through 'OUT' or 'INOUT' parameters.)

   * The trigger cannot use statements that explicitly or implicitly
     begin or end a transaction, such as 'START TRANSACTION',
     see 'COMMIT', or 'ROLLBACK'.
     (see 'ROLLBACK to SAVEPOINT' is permitted because it
     does not end a transaction.).

See also stored-program-restrictions.

MySQL handles errors during trigger execution as follows:

   * If a 'BEFORE' trigger fails, the operation on the corresponding row
     is not performed.

   * A 'BEFORE' trigger is activated by the _attempt_ to insert or
     modify the row, regardless of whether the attempt subsequently
     succeeds.

   * An 'AFTER' trigger is executed only if any 'BEFORE' triggers and
     the row operation execute successfully.

   * An error during either a 'BEFORE' or 'AFTER' trigger results in
     failure of the entire statement that caused trigger invocation.

   * For transactional tables, failure of a statement should cause
     rollback of all changes performed by the statement.  Failure of a
     trigger causes the statement to fail, so trigger failure also
     causes rollback.  For nontransactional tables, such rollback cannot
     be done, so although the statement fails, any changes performed
     prior to the point of the error remain in effect.

Triggers can contain direct references to tables by name, such as the
trigger named 'testref' shown in this example:

     CREATE TABLE test1(a1 INT);
     CREATE TABLE test2(a2 INT);
     CREATE TABLE test3(a3 INT NOT NULL AUTO_INCREMENT PRIMARY KEY);
     CREATE TABLE test4(
       a4 INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
       b4 INT DEFAULT 0
     );

     delimiter |

     CREATE TRIGGER testref BEFORE INSERT ON test1
       FOR EACH ROW
       BEGIN
         INSERT INTO test2 SET a2 = NEW.a1;
         DELETE FROM test3 WHERE a3 = NEW.a1;
         UPDATE test4 SET b4 = b4 + 1 WHERE a4 = NEW.a1;
       END;
     |

     delimiter ;

     INSERT INTO test3 (a3) VALUES
       (NULL), (NULL), (NULL), (NULL), (NULL),
       (NULL), (NULL), (NULL), (NULL), (NULL);

     INSERT INTO test4 (a4) VALUES
       (0), (0), (0), (0), (0), (0), (0), (0), (0), (0);

Suppose that you insert the following values into table 'test1' as shown
here:

     mysql> INSERT INTO test1 VALUES
            (1), (3), (1), (7), (1), (8), (4), (4);
     Query OK, 8 rows affected (0.01 sec)
     Records: 8  Duplicates: 0  Warnings: 0

As a result, the four tables contain the following data:

     mysql> SELECT * FROM test1;
     +------+
     | a1   |
     +------+
     |    1 |
     |    3 |
     |    1 |
     |    7 |
     |    1 |
     |    8 |
     |    4 |
     |    4 |
     +------+
     8 rows in set (0.00 sec)

     mysql> SELECT * FROM test2;
     +------+
     | a2   |
     +------+
     |    1 |
     |    3 |
     |    1 |
     |    7 |
     |    1 |
     |    8 |
     |    4 |
     |    4 |
     +------+
     8 rows in set (0.00 sec)

     mysql> SELECT * FROM test3;
     +----+
     | a3 |
     +----+
     |  2 |
     |  5 |
     |  6 |
     |  9 |
     | 10 |
     +----+
     5 rows in set (0.00 sec)

     mysql> SELECT * FROM test4;
     +----+------+
     | a4 | b4   |
     +----+------+
     |  1 |    3 |
     |  2 |    0 |
     |  3 |    1 |
     |  4 |    2 |
     |  5 |    0 |
     |  6 |    0 |
     |  7 |    1 |
     |  8 |    1 |
     |  9 |    0 |
     | 10 |    0 |
     +----+------+
     10 rows in set (0.00 sec)

23.3.2 Trigger Metadata
-----------------------

Metadata about triggers can be obtained as follows:

   * Query the 'TRIGGERS' table of the
     'INFORMATION_SCHEMA' database.  See triggers-table.

   * Use the 'SHOW CREATE TRIGGER'.
     statement.  See show-create-trigger.

   * Use the 'SHOW TRIGGERS' statement.  See
     show-triggers.

23.4 Using the Event Scheduler
==============================

The _MySQL Event Scheduler_ manages the scheduling and execution of
events, that is, tasks that run according to a schedule.  The following
discussion covers the Event Scheduler and is divided into the following
sections:

   * events-overview, provides an introduction to and conceptual
     overview of MySQL Events.

   * events-syntax, discusses the SQL statements for creating,
     altering, and dropping MySQL Events.

   * events-metadata, shows how to obtain information about
     events and how this information is stored by the MySQL Server.

   * events-privileges, discusses the privileges required to
     work with events and the ramifications that events have with regard
     to privileges when executing.

Stored routines require the 'event' table in the 'mysql' database.  This
table is created during the MySQL 5.7 installation procedure.  If you
are upgrading to MySQL 5.7 from an earlier version, be sure to update
your grant tables to make sure that the 'event' table exists.  See
mysql-upgrade.

*Additional Resources*

   * You may find the MySQL Event Scheduler User Forum
     (http://forums.mysql.com/list.php?119) of use when working with
     scheduled events.

   * There are some restrictions on the use of events; see
     stored-program-restrictions.

   * Binary logging for events takes place as described in
     stored-programs-logging.

23.4.1 Event Scheduler Overview
-------------------------------

MySQL Events are tasks that run according to a schedule.  Therefore, we
sometimes refer to them as _scheduled_ events.  When you create an
event, you are creating a named database object containing one or more
SQL statements to be executed at one or more regular intervals,
beginning and ending at a specific date and time.  Conceptually, this is
similar to the idea of the Unix 'crontab' (also known as a 'cron job')
or the Windows Task Scheduler.

Scheduled tasks of this type are also sometimes known as 'temporal
triggers', implying that these are objects that are triggered by the
passage of time.  While this is essentially correct, we prefer to use
the term _events_ to avoid confusion with triggers of the type discussed
in triggers.  Events should more specifically not be confused
with 'temporary triggers'.  Whereas a trigger is a database object whose
statements are executed in response to a specific type of event that
occurs on a given table, a (scheduled) event is an object whose
statements are executed in response to the passage of a specified time
interval.

While there is no provision in the SQL Standard for event scheduling,
there are precedents in other database systems, and you may notice some
similarities between these implementations and that found in the MySQL
Server.

MySQL Events have the following major features and properties:

   * In MySQL, an event is uniquely identified by its name and the
     schema to which it is assigned.

   * An event performs a specific action according to a schedule.  This
     action consists of an SQL statement, which can be a compound
     statement in a 'BEGIN ... END' block if desired
     (see sql-syntax-compound-statements).  An event's timing
     can be either _one-time_ or _recurrent_.  A one-time event executes
     one time only.  A recurrent event repeats its action at a regular
     interval, and the schedule for a recurring event can be assigned a
     specific start day and time, end day and time, both, or neither.
     (By default, a recurring event's schedule begins as soon as it is
     created, and continues indefinitely, until it is disabled or
     dropped.)

     If a repeating event does not terminate within its scheduling
     interval, the result may be multiple instances of the event
     executing simultaneously.  If this is undesirable, you should
     institute a mechanism to prevent simultaneous instances.  For
     example, you could use the 'GET_LOCK()' function, or row or table
     locking.

   * Users can create, modify, and drop scheduled events using SQL
     statements intended for these purposes.  Syntactically invalid
     event creation and modification statements fail with an appropriate
     error message.  _A user may include statements in an event's action
     which require privileges that the user does not actually have_.
     The event creation or modification statement succeeds but the
     event's action fails.  See events-privileges for details.

   * Many of the properties of an event can be set or modified using SQL
     statements.  These properties include the event's name, timing,
     persistence (that is, whether it is preserved following the
     expiration of its schedule), status (enabled or disabled), action
     to be performed, and the schema to which it is assigned.  See
     alter-event.

     The default definer of an event is the user who created the event,
     unless the event has been altered, in which case the definer is the
     user who issued the last 'ALTER EVENT'.
     statement affecting that event.  An event can be modified by any
     user having the 'EVENT' privilege on the database for which the
     event is defined.  See events-privileges.

   * An event's action statement may include most SQL statements
     permitted within stored routines.  For restrictions, see
     stored-program-restrictions.

23.4.2 Event Scheduler Configuration
------------------------------------

Events are executed by a special _event scheduler thread_; when we refer
to the Event Scheduler, we actually refer to this thread.  When running,
the event scheduler thread and its current state can be seen by users
having the 'PROCESS' privilege in the output of 'SHOW PROCESSLIST',
as shown in the discussion that follows.

The global 'event_scheduler' system variable determines whether the
Event Scheduler is enabled and running on the server.  It has one of
these 3 values, which affect event scheduling as described here:

   * 'OFF': The Event Scheduler is stopped.  The event scheduler thread
     does not run, is not shown in the output of 'SHOW PROCESSLIST',
     and no scheduled events are
     executed.  'OFF' is the default value for 'event_scheduler'.

     When the Event Scheduler is stopped ('event_scheduler' is 'OFF'),
     it can be started by setting the value of 'event_scheduler' to
     'ON'.  (See next item.)

   * 'ON': The Event Scheduler is started; the event scheduler thread
     runs and executes all scheduled events.

     When the Event Scheduler is 'ON', the event scheduler thread is
     listed in the output of 'SHOW PROCESSLIST'.
     as a daemon process, and its state is represented as shown here:

          mysql> SHOW PROCESSLIST\G
          *************************** 1. row ***************************
               Id: 1
             User: root
             Host: localhost
               db: NULL
          Command: Query
             Time: 0
            State: NULL
             Info: show processlist
          *************************** 2. row ***************************
               Id: 2
             User: event_scheduler
             Host: localhost
               db: NULL
          Command: Daemon
             Time: 3
            State: Waiting for next activation
             Info: NULL
          2 rows in set (0.00 sec)

     Event scheduling can be stopped by setting the value of
     'event_scheduler' to 'OFF'.

   * 'DISABLED': This value renders the Event Scheduler nonoperational.
     When the Event Scheduler is 'DISABLED', the event scheduler thread
     does not run (and so does not appear in the output of 'SHOW PROCESSLIST').
     In addition, the Event Scheduler
     state cannot be changed at runtime.

If the Event Scheduler status has not been set to 'DISABLED',
'event_scheduler' can be toggled between 'ON' and 'OFF' (using
'SET').  It is also possible to use '0' for 'OFF', and
'1' for 'ON' when setting this variable.  Thus, any of the following 4
statements can be used in the 'mysql' client to turn on
the Event Scheduler:

     SET GLOBAL event_scheduler = ON;
     SET @@global.event_scheduler = ON;
     SET GLOBAL event_scheduler = 1;
     SET @@global.event_scheduler = 1;

Similarly, any of these 4 statements can be used to turn off the Event
Scheduler:

     SET GLOBAL event_scheduler = OFF;
     SET @@global.event_scheduler = OFF;
     SET GLOBAL event_scheduler = 0;
     SET @@global.event_scheduler = 0;

Although 'ON' and 'OFF' have numeric equivalents, the value displayed
for 'event_scheduler' by 'SELECT' or 'SHOW VARIABLES'
is always one of 'OFF', 'ON', or 'DISABLED'.
_'DISABLED' has no numeric equivalent_.  For this reason, 'ON' and 'OFF'
are usually preferred over '1' and '0' when setting this variable.

Note that attempting to set 'event_scheduler' without specifying it as a
global variable causes an error:

     mysql< SET @@event_scheduler = OFF;
     ERROR 1229 (HY000): Variable 'event_scheduler' is a GLOBAL
     variable and should be set with SET GLOBAL

*Important*:

It is possible to set the Event Scheduler to 'DISABLED' only at server
startup.  If 'event_scheduler' is 'ON' or 'OFF', you cannot set it to
'DISABLED' at runtime.  Also, if the Event Scheduler is set to
'DISABLED' at startup, you cannot change the value of 'event_scheduler'
at runtime.

To disable the event scheduler, use one of the following two methods:

   * As a command-line option when starting the server:

          --event-scheduler=DISABLED

   * In the server configuration file ('my.cnf', or 'my.ini' on Windows
     systems), include the line where it will be read by the server (for
     example, in a '[mysqld]' section):

          event_scheduler=DISABLED

To enable the Event Scheduler, restart the server without the
'--event-scheduler=DISABLED' command-line option, or after removing or
commenting out the line containing 'event-scheduler=DISABLED' in the
server configuration file, as appropriate.  Alternatively, you can use
'ON' (or '1') or 'OFF' (or '0') in place of the 'DISABLED' value when
starting the server.

*Note*:

You can issue event-manipulation statements when 'event_scheduler' is
set to 'DISABLED'.  No warnings or errors are generated in such cases
(provided that the statements are themselves valid).  However, scheduled
events cannot execute until this variable is set to 'ON' (or '1').  Once
this has been done, the event scheduler thread executes all events whose
scheduling conditions are satisfied.

Starting the MySQL server with the '--skip-grant-tables' option causes
'event_scheduler' to be set to 'DISABLED', overriding any other value
set either on the command line or in the 'my.cnf' or 'my.ini' file (Bug
#26807).

For SQL statements used to create, alter, and drop events, see
events-syntax.

MySQL provides an 'EVENTS' table in the
'INFORMATION_SCHEMA' database.  This table can be queried to obtain
information about scheduled events which have been defined on the
server.  See events-metadata, and events-table, for more
information.

For information regarding event scheduling and the MySQL privilege
system, see events-privileges.

23.4.3 Event Syntax
-------------------

MySQL provides several SQL statements for working with scheduled events:

   * New events are defined using the 'CREATE EVENT'
     statement.  See create-event.

   * The definition of an existing event can be changed by means of the
     'ALTER EVENT' statement.  See
     alter-event.

   * When a scheduled event is no longer wanted or needed, it can be
     deleted from the server by its definer using the 'DROP EVENT'
     statement.  See drop-event.  Whether an
     event persists past the end of its schedule also depends on its 'ON
     COMPLETION' clause, if it has one.  See create-event.

     An event can be dropped by any user having the 'EVENT' privilege
     for the database on which the event is defined.  See
     events-privileges.

23.4.4 Event Metadata
---------------------

Metadata about events can be obtained as follows:

   * Query the 'event' table of the 'mysql' database.

   * Query the 'EVENTS' table of the
     'INFORMATION_SCHEMA' database.  See events-table.

   * Use the 'SHOW CREATE EVENT' statement.
     See show-create-event.

   * Use the 'SHOW EVENTS' statement.  See
     show-events.

*Event Scheduler Time Representation*

Each session in MySQL has a session time zone (STZ). This is the session
'time_zone' value that is initialized from the server's global
'time_zone' value when the session begins but may be changed during the
session.

The session time zone that is current when a 'CREATE EVENT'
or 'ALTER EVENT' statement executes is
used to interpret times specified in the event definition.  This becomes
the event time zone (ETZ); that is, the time zone that is used for event
scheduling and is in effect within the event as it executes.

For representation of event information in the 'mysql.event' table, the
'execute_at', 'starts', and 'ends' times are converted to UTC and stored
along with the event time zone.  This enables event execution to proceed
as defined regardless of any subsequent changes to the server time zone
or daylight saving time effects.  The 'last_executed' time is also
stored in UTC.

If you select information from 'mysql.event', the times just mentioned
are retrieved as UTC values.  These times can also be obtained by
selecting from the 'INFORMATION_SCHEMA.EVENTS'.
table or from 'SHOW EVENTS', but they are reported as
ETZ values.  Other times available from these sources indicate when an
event was created or last altered; these are displayed as STZ values.
The following table summarizes representation of event times.

Value              'mysql.event'      *note 'SHOW 'INFORMATION_SCHEMA.EVENTS'.
                                      show-events.

Execute at         UTC                ETZ                ETZ

Starts             UTC                ETZ                ETZ

Ends               UTC                ETZ                ETZ

Last executed      UTC                ETZ                n/a

Created            STZ                STZ                n/a

Last altered       STZ                STZ                n/a

23.4.5 Event Scheduler Status
-----------------------------

The Event Scheduler writes information about event execution that
terminates with an error or warning to the MySQL Server's error log.
See events-privileges for an example.

To obtain information about the state of the Event Scheduler for
debugging and troubleshooting purposes, run 'mysqladmin debug'.
(see mysqladmin); after running this command, the
server's error log contains output relating to the Event Scheduler,
similar to what is shown here:

     Events status:
     LLA = Last Locked At  LUA = Last Unlocked At
     WOC = Waiting On Condition  DL = Data Locked

     Event scheduler status:
     State      : INITIALIZED
     Thread id  : 0
     LLA        : init_scheduler:313
     LUA        : init_scheduler:318
     WOC        : NO
     Workers    : 0
     Executed   : 0
     Data locked: NO

     Event queue status:
     Element count   : 1
     Data locked     : NO
     Attempting lock : NO
     LLA             : init_queue:148
     LUA             : init_queue:168
     WOC             : NO
     Next activation : 0000-00-00 00:00:00

In statements that occur as part of events executed by the Event
Scheduler, diagnostics messages (not only errors, but also warnings) are
written to the error log, and, on Windows, to the application event log.
For frequently executed events, it is possible for this to result in
many logged messages.  For example, for 'SELECT ... INTO VAR_LIST'
statements, if the query returns no rows, a warning with error code 1329
occurs ('No data'), and the variable values remain unchanged.  If the
query returns multiple rows, error 1172 occurs ('Result consisted of
more than one row').  For either condition, you can avoid having the
warnings be logged by declaring a condition handler; see
declare-handler.  For statements that may retrieve multiple rows,
another strategy is to use 'LIMIT 1' to limit the result set to a single
row.

23.4.6 The Event Scheduler and MySQL Privileges
-----------------------------------------------

To enable or disable the execution of scheduled events, it is necessary
to set the value of the global 'event_scheduler' system variable.  This
requires the 'SUPER' privilege.

The 'EVENT' privilege governs the creation, modification, and deletion
of events.  This privilege can be bestowed using 'GRANT'.
For example, this 'GRANT' statement confers the 'EVENT'
privilege for the schema named 'myschema' on the user 'jon@ghidora':

     GRANT EVENT ON myschema.* TO jon@ghidora;

(We assume that this user account already exists, and that we wish for
it to remain unchanged otherwise.)

To grant this same user the 'EVENT' privilege on all schemas, use the
following statement:

     GRANT EVENT ON *.* TO jon@ghidora;

The 'EVENT' privilege has global or schema-level scope.  Therefore,
trying to grant it on a single table results in an error as shown:

     mysql> GRANT EVENT ON myschema.mytable TO jon@ghidora;
     ERROR 1144 (42000): Illegal GRANT/REVOKE command; please
     consult the manual to see which privileges can be used

It is important to understand that an event is executed with the
privileges of its definer, and that it cannot perform any actions for
which its definer does not have the requisite privileges.  For example,
suppose that 'jon@ghidora' has the 'EVENT' privilege for 'myschema'.
Suppose also that this user has the 'SELECT' privilege for 'myschema',
but no other privileges for this schema.  It is possible for
'jon@ghidora' to create a new event such as this one:

     CREATE EVENT e_store_ts
         ON SCHEDULE
           EVERY 10 SECOND
         DO
           INSERT INTO myschema.mytable VALUES (UNIX_TIMESTAMP());

The user waits for a minute or so, and then performs a 'SELECT * FROM
mytable;' query, expecting to see several new rows in the table.
Instead, the table is empty.  Since the user does not have the 'INSERT'
privilege for the table in question, the event has no effect.

If you inspect the MySQL error log ('HOSTNAME.err'), you can see that
the event is executing, but the action it is attempting to perform
fails:

     2013-09-24T12:41:31.261992Z 25 [ERROR] Event Scheduler:
     [jon@ghidora][cookbook.e_store_ts] INSERT command denied to user
     'jon'@'ghidora' for table 'mytable'
     2013-09-24T12:41:31.262022Z 25 [Note] Event Scheduler:
     [jon@ghidora].[myschema.e_store_ts] event execution failed.
     2013-09-24T12:41:41.271796Z 26 [ERROR] Event Scheduler:
     [jon@ghidora][cookbook.e_store_ts] INSERT command denied to user
     'jon'@'ghidora' for table 'mytable'
     2013-09-24T12:41:41.272761Z 26 [Note] Event Scheduler:
     [jon@ghidora].[myschema.e_store_ts] event execution failed.

Since this user very likely does not have access to the error log, it is
possible to verify whether the event's action statement is valid by
executing it directly:

     mysql> INSERT INTO myschema.mytable VALUES (UNIX_TIMESTAMP());
     ERROR 1142 (42000): INSERT command denied to user
     'jon'@'ghidora' for table 'mytable'

Inspection of the 'INFORMATION_SCHEMA.EVENTS' table
shows that 'e_store_ts' exists and is enabled, but its 'LAST_EXECUTED'
column is 'NULL':

     mysql> SELECT * FROM INFORMATION_SCHEMA.EVENTS
          >     WHERE EVENT_NAME='e_store_ts'
          >     AND EVENT_SCHEMA='myschema'\G
     *************************** 1. row ***************************
        EVENT_CATALOG: NULL
         EVENT_SCHEMA: myschema
           EVENT_NAME: e_store_ts
              DEFINER: jon@ghidora
           EVENT_BODY: SQL
     EVENT_DEFINITION: INSERT INTO myschema.mytable VALUES (UNIX_TIMESTAMP())
           EVENT_TYPE: RECURRING
           EXECUTE_AT: NULL
       INTERVAL_VALUE: 5
       INTERVAL_FIELD: SECOND
             SQL_MODE: NULL
               STARTS: 0000-00-00 00:00:00
                 ENDS: 0000-00-00 00:00:00
               STATUS: ENABLED
        ON_COMPLETION: NOT PRESERVE
              CREATED: 2006-02-09 22:36:06
         LAST_ALTERED: 2006-02-09 22:36:06
        LAST_EXECUTED: NULL
        EVENT_COMMENT:
     1 row in set (0.00 sec)

To rescind the 'EVENT' privilege, use the 'REVOKE'.
statement.  In this example, the 'EVENT' privilege on the schema
'myschema' is removed from the 'jon@ghidora' user account:

     REVOKE EVENT ON myschema.* FROM jon@ghidora;

*Important*:

Revoking the 'EVENT' privilege from a user does not delete or disable
any events that may have been created by that user.

An event is not migrated or dropped as a result of renaming or dropping
the user who created it.

Suppose that the user 'jon@ghidora' has been granted the 'EVENT' and
'INSERT' privileges on the 'myschema' schema.  This user then creates
the following event:

     CREATE EVENT e_insert
         ON SCHEDULE
           EVERY 7 SECOND
         DO
           INSERT INTO myschema.mytable;

After this event has been created, 'root' revokes the 'EVENT' privilege
for 'jon@ghidora'.  However, 'e_insert' continues to execute, inserting
a new row into 'mytable' each seven seconds.  The same would be true if
'root' had issued either of these statements:

   * 'DROP USER jon@ghidora;'

   * 'RENAME USER jon@ghidora TO someotherguy@ghidora;'

You can verify that this is true by examining the 'mysql.event' table
(discussed later in this section) or the
'INFORMATION_SCHEMA.EVENTS' table (see
events-table) before and after issuing a 'DROP USER'.
or 'RENAME USER' statement.

Event definitions are stored in the 'mysql.event' table.  To drop an
event created by another user account, the MySQL 'root' user (or another
user with the necessary privileges) can delete rows from this table.
For example, to remove the event 'e_insert' shown previously, 'root' can
use the following statement:

     DELETE FROM mysql.event
         WHERE db = 'myschema'
           AND definer = 'jon@ghidora'
           AND name = 'e_insert';

It is very important to match the event name, database schema name, and
user account when deleting rows from the 'mysql.event' table.  This is
because the same user can create different events of the same name in
different schemas.

Users' 'EVENT' privileges are stored in the 'Event_priv' columns of the
'mysql.user' and 'mysql.db' tables.  In both cases, this column holds
one of the values ''Y'' or ''N''.  ''N'' is the default.
'mysql.user.Event_priv' is set to ''Y'' for a given user only if that
user has the global 'EVENT' privilege (that is, if the privilege was
bestowed using 'GRANT EVENT ON *.*').  For a schema-level 'EVENT'
privilege, see 'GRANT' creates a row in 'mysql.db' and sets
that row's 'Db' column to the name of the schema, the 'User' column to
the name of the user, and the 'Event_priv' column to ''Y''.  There
should never be any need to manipulate these tables directly, since the
'GRANT EVENT' and 'REVOKE EVENT' statements perform the
required operations on them.

Five status variables provide counts of event-related operations (but
_not_ of statements executed by events; see
stored-program-restrictions).  These are:

   * 'Com_create_event': The number of 'CREATE EVENT'
     statements executed since the last server restart.

   * 'Com_alter_event': The number of 'ALTER EVENT'.
     statements executed since the last server restart.

   * 'Com_drop_event': The number of 'DROP EVENT'.
     statements executed since the last server restart.

   * 'Com_show_create_event': The number of 'SHOW CREATE EVENT'
     statements executed since the last server
     restart.

   * 'Com_show_events': The number of 'SHOW EVENTS'.
     statements executed since the last server restart.

You can view current values for all of these at one time by running the
statement 'SHOW STATUS LIKE '%event%';'.

23.5 Using Views
================

MySQL supports views, including updatable views.  Views are stored
queries that when invoked produce a result set.  A view acts as a
virtual table.

The following discussion describes the syntax for creating and dropping
views, and shows some examples of how to use them.

*Additional Resources*

   * You may find the Views User Forum
     (http://forums.mysql.com/list.php?100) of use when working with
     views.

   * For answers to some commonly asked questions regarding views in
     MySQL, see faqs-views.

   * There are some restrictions on the use of views; see
     view-restrictions.

23.5.1 View Syntax
------------------

The 'CREATE VIEW' statement creates a new view (see
create-view).  To alter the definition of a view or drop a view,
use 'ALTER VIEW'. (see alter-view), or
'DROP VIEW'. (see drop-view).

A view can be created from many kinds of 'SELECT'.
statements.  It can refer to base tables or other views.  It can use
joins, see 'UNION', and subqueries.  The 'SELECT'
need not even refer to any tables.  The following example
defines a view that selects two columns from another table, as well as
an expression calculated from those columns:

     mysql> CREATE TABLE t (qty INT, price INT);
     mysql> INSERT INTO t VALUES(3, 50), (5, 60);
     mysql> CREATE VIEW v AS SELECT qty, price, qty*price AS value FROM t;
     mysql> SELECT * FROM v;
     +------+-------+-------+
     | qty  | price | value |
     +------+-------+-------+
     |    3 |    50 |   150 |
     |    5 |    60 |   300 |
     +------+-------+-------+
     mysql> SELECT * FROM v WHERE qty = 5;
     +------+-------+-------+
     | qty  | price | value |
     +------+-------+-------+
     |    5 |    60 |   300 |
     +------+-------+-------+

23.5.2 View Processing Algorithms
---------------------------------

The optional 'ALGORITHM' clause for 'CREATE VIEW' or
'ALTER VIEW' is a MySQL extension to standard SQL. It
affects how MySQL processes the view.  'ALGORITHM' takes three values:
'MERGE', 'TEMPTABLE', or 'UNDEFINED'.

   * For 'MERGE', the text of a statement that refers to the view and
     the view definition are merged such that parts of the view
     definition replace corresponding parts of the statement.

   * For 'TEMPTABLE', the results from the view are retrieved into a
     temporary table, which then is used to execute the statement.

   * For 'UNDEFINED', MySQL chooses which algorithm to use.  It prefers
     'MERGE' over 'TEMPTABLE' if possible, because 'MERGE' is usually
     more efficient and because a view cannot be updatable if a
     temporary table is used.

   * If no 'ALGORITHM' clause is present, 'UNDEFINED' is the default
     algorithm prior to MySQL 5.7.6.  As of 5.7.6, the default algorithm
     is determined by the value of the 'derived_merge' flag of the
     'optimizer_switch' system variable.  For additional discussion, see
     derived-table-optimization.

A reason to specify 'TEMPTABLE' explicitly is that locks can be released
on underlying tables after the temporary table has been created and
before it is used to finish processing the statement.  This might result
in quicker lock release than the 'MERGE' algorithm so that other clients
that use the view are not blocked as long.

A view algorithm can be 'UNDEFINED' for three reasons:

   * No 'ALGORITHM' clause is present in the 'CREATE VIEW'
     statement.

   * The 'CREATE VIEW' statement has an explicit
     'ALGORITHM = UNDEFINED' clause.

   * 'ALGORITHM = MERGE' is specified for a view that can be processed
     only with a temporary table.  In this case, MySQL generates a
     warning and sets the algorithm to 'UNDEFINED'.

As mentioned earlier, 'MERGE' is handled by merging corresponding parts
of a view definition into the statement that refers to the view.  The
following examples briefly illustrate how the 'MERGE' algorithm works.
The examples assume that there is a view 'v_merge' that has this
definition:

     CREATE ALGORITHM = MERGE VIEW v_merge (vc1, vc2) AS
     SELECT c1, c2 FROM t WHERE c3 > 100;

Example 1: Suppose that we issue this statement:

     SELECT * FROM v_merge;

MySQL handles the statement as follows:

   * 'v_merge' becomes 't'

   * '*' becomes 'vc1, vc2', which corresponds to 'c1, c2'

   * The view 'WHERE' clause is added

The resulting statement to be executed becomes:

     SELECT c1, c2 FROM t WHERE c3 > 100;

Example 2: Suppose that we issue this statement:

     SELECT * FROM v_merge WHERE vc1 < 100;

This statement is handled similarly to the previous one, except that
'vc1 < 100' becomes 'c1 < 100' and the view 'WHERE' clause is added to
the statement 'WHERE' clause using an 'AND' connective (and parentheses
are added to make sure the parts of the clause are executed with correct
precedence).  The resulting statement to be executed becomes:

     SELECT c1, c2 FROM t WHERE (c3 > 100) AND (c1 < 100);

Effectively, the statement to be executed has a 'WHERE' clause of this
form:

     WHERE (select WHERE) AND (view WHERE)

If the 'MERGE' algorithm cannot be used, a temporary table must be used
instead.  Constructs that prevent merging are the same as those that
prevent merging in derived tables.  Examples are 'SELECT DISTINCT' or
'LIMIT' in the subquery.  For details, see
derived-table-optimization.

23.5.3 Updatable and Insertable Views
-------------------------------------

Some views are updatable and references to them can be used to specify
tables to be updated in data change statements.  That is, you can use
them in statements such as 'UPDATE', 'DELETE',
or 'INSERT' to update the contents of the
underlying table.  Derived tables can also be specified in
multiple-table 'UPDATE' and 'DELETE'.
statements, but can only be used for reading data to specify rows to be
updated or deleted.  Generally, the view references must be updatable,
meaning that they may be merged and not materialized.  Composite views
have more complex rules.

For a view to be updatable, there must be a one-to-one relationship
between the rows in the view and the rows in the underlying table.
There are also certain other constructs that make a view nonupdatable.
To be more specific, a view is not updatable if it contains any of the
following:

   * Aggregate functions ('SUM()', 'MIN()', 'MAX()', 'COUNT()', and so
     forth)

   * 'DISTINCT'

   * 'GROUP BY'

   * 'HAVING'

   * 'UNION' or 'UNION ALL'.

   * Subquery in the select list

     Before MySQL 5.7.11, subqueries in the select list fail for
     'INSERT', but are okay for 'UPDATE',
     'DELETE'.  As of MySQL 5.7.11, that is still true for
     nondependent subqueries.  For dependent subqueries in the select
     list, no data change statements are permitted.

   * Certain joins (see additional join discussion later in this
     section)

   * Reference to nonupdatable view in the 'FROM' clause

   * Subquery in the 'WHERE' clause that refers to a table in the 'FROM'
     clause

   * Refers only to literal values (in this case, there is no underlying
     table to update)

   * 'ALGORITHM = TEMPTABLE' (use of a temporary table always makes a
     view nonupdatable)

   * Multiple references to any column of a base table (fails for
     'INSERT', okay for 'UPDATE', 'DELETE')

A generated column in a view is considered updatable because it is
possible to assign to it.  However, if such a column is updated
explicitly, the only permitted value is 'DEFAULT'.  For information
about generated columns, see create-table-generated-columns.

It is sometimes possible for a multiple-table view to be updatable,
assuming that it can be processed with the 'MERGE' algorithm.  For this
to work, the view must use an inner join (not an outer join or a
'UNION').  Also, only a single table in the view definition can
be updated, so the 'SET' clause must name only columns from one of the
tables in the view.  Views that use 'UNION ALL' are not
permitted even though they might be theoretically updatable.

With respect to insertability (being updatable with 'INSERT'
statements), an updatable view is insertable if it also
satisfies these additional requirements for the view columns:

   * There must be no duplicate view column names.

   * The view must contain all columns in the base table that do not
     have a default value.

   * The view columns must be simple column references.  They must not
     be expressions, such as these:

          3.14159
          col1 + 3
          UPPER(col2)
          col3 / col4
          (SUBQUERY)

MySQL sets a flag, called the view updatability flag, at 'CREATE VIEW'
time.  The flag is set to 'YES' (true) if
'UPDATE' and 'DELETE'. (and similar operations)
are legal for the view.  Otherwise, the flag is set to 'NO' (false).
The 'IS_UPDATABLE' column in the 'INFORMATION_SCHEMA.VIEWS'
table displays the status of this flag.

If a view is not updatable, statements such 'UPDATE',
'DELETE', and 'INSERT' are illegal and are
rejected.  (Note that even if a view is updatable, it might not be
possible to insert into it, as described elsewhere in this section.)

The 'IS_UPDATABLE' flag may be unreliable if a view depends on one or
more other views, and one of these underlying views is updated.
Regardless of the 'IS_UPDATABLE' value, the server keeps track of the
updatability of a view and correctly rejects data change operations to
views that are not updatable.  If the 'IS_UPDATABLE' value for a view
has become inaccurate to due to changes to underlying views, the value
can be updated by deleting and recreating the view.

The updatability of views may be affected by the value of the
'updatable_views_with_limit' system variable.  See
server-system-variables.

For the following discussion, suppose that these tables and views exist:

     CREATE TABLE t1 (x INTEGER);
     CREATE TABLE t2 (c INTEGER);
     CREATE VIEW vmat AS SELECT SUM(x) AS s FROM t1;
     CREATE VIEW vup AS SELECT * FROM t2;
     CREATE VIEW vjoin AS SELECT * FROM vmat JOIN vup ON vmat.s=vup.c;

See 'INSERT', 'UPDATE', and 'DELETE'
statements are permitted as follows:

   * 'INSERT'.: The insert table of an 'INSERT'
     statement may be a view reference that is merged.  If the
     view is a join view, all components of the view must be updatable
     (not materialized).  For a multiple-table updatable view, see
     'INSERT' can work if it inserts into a single table.

     This statement is invalid because one component of the join view is
     nonupdatable:

          INSERT INTO vjoin (c) VALUES (1);

     This statement is valid; the view contains no materialized
     components:

          INSERT INTO vup (c) VALUES (1);

   * 'UPDATE'.: The table or tables to be updated in an
     'UPDATE' statement may be view references that are
     merged.  If a view is a join view, at least one component of the
     view must be updatable (this differs from 'INSERT').

     In a multiple-table 'UPDATE' statement, the updated
     table references of the statement must be base tables or updatable
     view references.  Nonupdated table references may be materialized
     views or derived tables.

     This statement is valid; column 'c' is from the updatable part of
     the join view:

          UPDATE vjoin SET c=c+1;

     This statement is invalid; column 'x' is from the nonupdatable
     part:

          UPDATE vjoin SET x=x+1;

     This statement is valid; the updated table reference of the
     multiple-table 'UPDATE' is an updatable view
     ('vup'):

          UPDATE vup JOIN (SELECT SUM(x) AS s FROM t1) AS dt ON ...
          SET c=c+1;

     This statement is invalid; it tries to update a materialized
     derived table:

          UPDATE vup JOIN (SELECT SUM(x) AS s FROM t1) AS dt ON ...
          SET s=s+1;

   * 'DELETE'.: The table or tables to be deleted from in
     a 'DELETE' statement must be merged views.  Join
     views are not allowed (this differs from 'INSERT'.
     and 'UPDATE').

     This statement is invalid because the view is a join view:

          DELETE vjoin WHERE ...;

     This statement is valid because the view is a merged (updatable)
     view:

          DELETE vup WHERE ...;

     This statement is valid because it deletes from a merged
     (updatable) view:

          DELETE vup FROM vup JOIN (SELECT SUM(x) AS s FROM t1) AS dt ON ...;

Additional discussion and examples follow.

Earlier discussion in this section pointed out that a view is not
insertable if not all columns are simple column references (for example,
if it contains columns that are expressions or composite expressions).
Although such a view is not insertable, it can be updatable if you
update only columns that are not expressions.  Consider this view:

     CREATE VIEW v AS SELECT col1, 1 AS col2 FROM t;

This view is not insertable because 'col2' is an expression.  But it is
updatable if the update does not try to update 'col2'.  This update is
permissible:

     UPDATE v SET col1 = 0;

This update is not permissible because it attempts to update an
expression column:

     UPDATE v SET col2 = 0;

If a table contains an 'AUTO_INCREMENT' column, inserting into an
insertable view on the table that does not include the 'AUTO_INCREMENT'
column does not change the value of 'LAST_INSERT_ID()', because the side
effects of inserting default values into columns not part of the view
should not be visible.

23.5.4 The View WITH CHECK OPTION Clause
----------------------------------------

The 'WITH CHECK OPTION' clause can be given for an updatable view to
prevent inserts to rows for which the 'WHERE' clause in the
SELECT_STATEMENT is not true.  It also prevents updates to rows for
which the 'WHERE' clause is true but the update would cause it to be not
true (in other words, it prevents visible rows from being updated to
nonvisible rows).

In a 'WITH CHECK OPTION' clause for an updatable view, the 'LOCAL' and
'CASCADED' keywords determine the scope of check testing when the view
is defined in terms of another view.  When neither keyword is given, the
default is 'CASCADED'.

Before MySQL 5.7.6, 'WITH CHECK OPTION' testing works like this:

   * With 'LOCAL', the view 'WHERE' clause is checked, but no underlying
     views are checked.

   * With 'CASCADED', the view 'WHERE' clause is checked, then checking
     recurses to underlying views, adds 'WITH CASCADED CHECK OPTION' to
     them (for purposes of the check; their definitions remain
     unchanged), and applies the same rules.

   * With no check option, the view 'WHERE' clause is not checked, and
     no underlying views are checked.

As of MySQL 5.7.6, 'WITH CHECK OPTION' testing is standard-compliant
(with changed semantics from previously for 'LOCAL' and no check
clause):

   * With 'LOCAL', the view 'WHERE' clause is checked, then checking
     recurses to underlying views and applies the same rules.

   * With 'CASCADED', the view 'WHERE' clause is checked, then checking
     recurses to underlying views, adds 'WITH CASCADED CHECK OPTION' to
     them (for purposes of the check; their definitions remain
     unchanged), and applies the same rules.

   * With no check option, the view 'WHERE' clause is not checked, then
     checking recurses to underlying views, and applies the same rules.

Consider the definitions for the following table and set of views:

     CREATE TABLE t1 (a INT);
     CREATE VIEW v1 AS SELECT * FROM t1 WHERE a < 2
     WITH CHECK OPTION;
     CREATE VIEW v2 AS SELECT * FROM v1 WHERE a > 0
     WITH LOCAL CHECK OPTION;
     CREATE VIEW v3 AS SELECT * FROM v1 WHERE a > 0
     WITH CASCADED CHECK OPTION;

Here the 'v2' and 'v3' views are defined in terms of another view, 'v1'.
Before MySQL 5.7.6, because 'v2' has a 'LOCAL' check option, inserts are
tested only against the 'v2' check.  'v3' has a 'CASCADED' check option,
so inserts are tested not only against the 'v3' check, but against those
of underlying views.  The following statements illustrate these
differences:

     mysql> INSERT INTO v2 VALUES (2);
     Query OK, 1 row affected (0.00 sec)
     mysql> INSERT INTO v3 VALUES (2);
     ERROR 1369 (HY000): CHECK OPTION failed 'test.v3'

As of MySQL 5.7.6, the semantics for 'LOCAL' differ from previously:
Inserts for 'v2' are checked against its 'LOCAL' check option, then
(unlike before 5.7.6), the check recurses to 'v1' and the rules are
applied again.  The rules for 'v1' cause a check failure.  The check for
'v3' fails as before:

     mysql> INSERT INTO v2 VALUES (2);
     ERROR 1369 (HY000): CHECK OPTION failed 'test.v2'
     mysql> INSERT INTO v3 VALUES (2);
     ERROR 1369 (HY000): CHECK OPTION failed 'test.v3'

23.5.5 View Metadata
--------------------

Metadata about views can be obtained as follows:

   * Query the 'VIEWS' table of the
     'INFORMATION_SCHEMA' database.  See views-table.

   * Use the 'SHOW CREATE VIEW' statement.  See
     show-create-view.

23.6 Access Control for Stored Programs and Views
=================================================

Stored programs and views are defined prior to use and, when referenced,
execute within a security context that determines their privileges.
These privileges are controlled by their 'DEFINER' attribute, and, if
there is one, their 'SQL SECURITY' characteristic.

All stored programs (procedures, functions, triggers, and events) and
views can have a 'DEFINER' attribute that names a MySQL account.  If the
'DEFINER' attribute is omitted from a stored program or view definition,
the default account is the user who creates the object.

In addition, stored routines (procedures and functions) and views can
have an 'SQL SECURITY' characteristic with a value of 'DEFINER' or
'INVOKER' to specify whether the object executes in definer or invoker
context.  If the 'SQL SECURITY' characteristic is omitted, the default
is definer context.

Triggers and events have no 'SQL SECURITY' characteristic and always
execute in definer context.  The server invokes these objects
automatically as necessary, so there is no invoking user.

Definer and invoker security contexts differ as follows:

   * A stored program or view that executes in definer security context
     executes with the privileges of the account named by its 'DEFINER'
     attribute.  These privileges may be entirely different from those
     of the invoking user.  The invoker must have appropriate privileges
     to reference the object (for example, 'EXECUTE' to call a stored
     procedure or 'SELECT' to select from a view), but when the object
     executes, the invoker's privileges are ignored and only the
     'DEFINER' account privileges matter.  If this account has few
     privileges, the object is correspondingly limited in the operations
     it can perform.  If the 'DEFINER' account is highly privileged
     (such as a 'root' account), the object can perform powerful
     operations _no matter who invokes it._

   * A stored routine or view that executes in invoker security context
     can perform only operations for which the invoker has privileges.
     The 'DEFINER' attribute can be specified but has no effect for
     objects that execute in invoker context.

Consider the following stored procedure:

     CREATE DEFINER = 'admin'@'localhost' PROCEDURE p1()
     SQL SECURITY DEFINER
     BEGIN
       UPDATE t1 SET counter = counter + 1;
     END;

Any user who has the 'EXECUTE' privilege for 'p1' can invoke it with a
'CALL' statement.  However, when 'p1' executes, it does so
in definer security context and thus executes with the privileges of
''admin'@'localhost'', the account named in the 'DEFINER' attribute.
This account must have the 'EXECUTE' privilege for 'p1' as well as the
'UPDATE' privilege for the table 't1'.  Otherwise, the procedure fails.

Now consider this stored procedure, which is identical to 'p1' except
that its 'SQL SECURITY' characteristic is 'INVOKER':

     CREATE DEFINER = 'admin'@'localhost' PROCEDURE p2()
     SQL SECURITY INVOKER
     BEGIN
       UPDATE t1 SET counter = counter + 1;
     END;

'p2', unlike 'p1', executes in invoker security context.  The 'DEFINER'
attribute is irrelevant and 'p2' executes with the privileges of the
invoking user.  'p2' fails if the invoker lacks the 'EXECUTE' privilege
for 'p2' or the 'UPDATE' privilege for the table 't1'.

MySQL uses the following rules to control which accounts a user can
specify in an object 'DEFINER' attribute:

   * You can specify a 'DEFINER' value other than your own account only
     if you have the 'SUPER' privilege.

   * If you do not have the 'SUPER' privilege, the only legal user value
     is your own account, either specified literally or by using
     'CURRENT_USER'.  You cannot set the definer to some other account.

To minimize the risk potential for stored program and view creation and
use, follow these guidelines:

   * For a stored routine or view, use 'SQL SECURITY INVOKER' in the
     object definition when possible so that it can be used only by
     users with permissions appropriate for the operations performed by
     the object.

   * If you create definer-context stored programs or views while using
     an account that has the 'SUPER' privilege, specify an explicit
     'DEFINER' attribute that names an account possessing only the
     privileges required for the operations performed by the object.
     Specify a highly privileged 'DEFINER' account only when absolutely
     necessary.

   * Administrators can prevent users from specifying highly privileged
     'DEFINER' accounts by not granting them the 'SUPER' privilege.

   * Definer-context objects should be written keeping in mind that they
     may be able to access data for which the invoking user has no
     privileges.  In some cases, you can prevent reference to these
     objects by not granting unauthorized users particular privileges:

        * A stored procedure or function cannot be referenced by a user
          who does not have the 'EXECUTE' privilege for it.

        * A view cannot be referenced by a user who does not have the
          appropriate privilege for it ('SELECT' to select from it,
          'INSERT' to insert into it, and so forth).

     However, no such control exists for triggers because users do not
     reference them directly.  A trigger always executes in definer
     context and is activated by access to the table with which it is
     associated, even ordinary table accesses by users with no special
     privileges.  If the 'DEFINER' account is highly privileged, the
     trigger can perform sensitive or dangerous operations.  This
     remains true if the 'SUPER' and 'TRIGGER' privileges needed to
     create the trigger are revoked from the account of the user who
     created it.  Administrators should be especially careful about
     granting users that combination of privileges.

23.7 Binary Logging of Stored Programs
======================================

The binary log contains information about SQL statements that modify
database contents.  This information is stored in the form of 'events'
that describe the modifications.  The binary log has two important
purposes:

   * For replication, the binary log is used on master replication
     servers as a record of the statements to be sent to slave servers.
     The master server sends the events contained in its binary log to
     its slaves, which execute those events to make the same data
     changes that were made on the master.  See
     replication-implementation.

   * Certain data recovery operations require use of the binary log.
     After a backup file has been restored, the events in the binary log
     that were recorded after the backup was made are re-executed.
     These events bring databases up to date from the point of the
     backup.  See recovery-from-backups.

However, if logging occurs at the statement level, there are certain
binary logging issues with respect to stored programs (stored procedures
and functions, triggers, and events):

   * In some cases, a statement might affect different sets of rows on
     master and slave.

   * Replicated statements executed on a slave are processed by the
     slave SQL thread, which has full privileges.  It is possible for a
     procedure to follow different execution paths on master and slave
     servers, so a user can write a routine containing a dangerous
     statement that will execute only on the slave where it is processed
     by a thread that has full privileges.

   * If a stored program that modifies data is nondeterministic, it is
     not repeatable.  This can result in different data on master and
     slave, or cause restored data to differ from the original data.

This section describes how MySQL handles binary logging for stored
programs.  It states the current conditions that the implementation
places on the use of stored programs, and what you can do to avoid
logging problems.  It also provides additional information about the
reasons for these conditions.

In general, the issues described here result when binary logging occurs
at the SQL statement level (statement-based binary logging).  If you use
row-based binary logging, the log contains changes made to individual
rows as a result of executing SQL statements.  When routines or triggers
execute, row changes are logged, not the statements that make the
changes.  For stored procedures, this means that the 'CALL'.
statement is not logged.  For stored functions, row changes made within
the function are logged, not the function invocation.  For triggers, row
changes made by the trigger are logged.  On the slave side, only the row
changes are seen, not the stored program invocation.

Mixed format binary logging ('binlog_format=MIXED') uses statement-based
binary logging, except for cases where only row-based binary logging is
guaranteed to lead to proper results.  With mixed format, when a stored
function, stored procedure, trigger, event, or prepared statement
contains anything that is not safe for statement-based binary logging,
the entire statement is marked as unsafe and logged in row format.  The
statements used to create and drop procedures, functions, triggers, and
events are always safe, and are logged in statement format.  For more
information about row-based, mixed, and statement-based logging, and how
safe and unsafe statements are determined, see
replication-formats.

Unless noted otherwise, the remarks here assume that binary logging is
enabled on the server (see binary-log.)  If the binary log is
not enabled, replication is not possible, nor is the binary log
available for data recovery.

The conditions on the use of stored functions in MySQL can be summarized
as follows.  These conditions do not apply to stored procedures or Event
Scheduler events and they do not apply unless binary logging is enabled.

   * To create or alter a stored function, you must have the 'SUPER'
     privilege, in addition to the 'CREATE ROUTINE' or 'ALTER ROUTINE'
     privilege that is normally required.  (Depending on the 'DEFINER'
     value in the function definition, 'SUPER' might be required
     regardless of whether binary logging is enabled.  See
     create-procedure.)

   * When you create a stored function, you must declare either that it
     is deterministic or that it does not modify data.  Otherwise, it
     may be unsafe for data recovery or replication.

     By default, for a 'CREATE FUNCTION'.
     statement to be accepted, at least one of 'DETERMINISTIC', 'NO
     SQL', or 'READS SQL DATA' must be specified explicitly.  Otherwise
     an error occurs:

          ERROR 1418 (HY000): This function has none of DETERMINISTIC, NO SQL,
          or READS SQL DATA in its declaration and binary logging is enabled
          (you *might* want to use the less safe log_bin_trust_function_creators
          variable)

     This function is deterministic (and does not modify data), so it is
     safe:

          CREATE FUNCTION f1(i INT)
          RETURNS INT
          DETERMINISTIC
          READS SQL DATA
          BEGIN
            RETURN i;
          END;

     This function uses 'UUID()', which is not deterministic, so the
     function also is not deterministic and is not safe:

          CREATE FUNCTION f2()
          RETURNS CHAR(36) CHARACTER SET utf8
          BEGIN
            RETURN UUID();
          END;

     This function modifies data, so it may not be safe:

          CREATE FUNCTION f3(p_id INT)
          RETURNS INT
          BEGIN
            UPDATE t SET modtime = NOW() WHERE id = p_id;
            RETURN ROW_COUNT();
          END;

     Assessment of the nature of a function is based on the 'honesty' of
     the creator.  MySQL does not check that a function declared
     'DETERMINISTIC' is free of statements that produce nondeterministic
     results.

   * When you attempt to execute a stored function, if
     'binlog_format=STATEMENT' is set, the 'DETERMINISTIC' keyword must
     be specified in the function definition.  If this is not the case,
     an error is generated and the function does not run, unless
     'log_bin_trust_function_creators=1' is specified to override this
     check (see below).  For recursive function calls, the
     'DETERMINISTIC' keyword is required on the outermost call only.  If
     row-based or mixed binary logging is in use, the statement is
     accepted and replicated even if the function was defined without
     the 'DETERMINISTIC' keyword.

   * Because MySQL does not check if a function really is deterministic
     at creation time, the invocation of a stored function with the
     'DETERMINISTIC' keyword might carry out an action that is unsafe
     for statement-based logging, or invoke a function or procedure
     containing unsafe statements.  If this occurs when
     'binlog_format=STATEMENT' is set, a warning message is issued.  If
     row-based or mixed binary logging is in use, no warning is issued,
     and the statement is replicated in row-based format.

   * To relax the preceding conditions on function creation (that you
     must have the 'SUPER' privilege and that a function must be
     declared deterministic or to not modify data), set the global
     'log_bin_trust_function_creators' system variable to 1.  By
     default, this variable has a value of 0, but you can change it like
     this:

          mysql> SET GLOBAL log_bin_trust_function_creators = 1;

     You can also set this variable by using the
     '--log-bin-trust-function-creators=1' option when starting the
     server.

     If binary logging is not enabled, 'log_bin_trust_function_creators'
     does not apply.  'SUPER' is not required for function creation
     unless, as described previously, the 'DEFINER' value in the
     function definition requires it.

   * For information about built-in functions that may be unsafe for
     replication (and thus cause stored functions that use them to be
     unsafe as well), see replication-features.

Triggers are similar to stored functions, so the preceding remarks
regarding functions also apply to triggers with the following exception:
'CREATE TRIGGER' does not have an optional
'DETERMINISTIC' characteristic, so triggers are assumed to be always
deterministic.  However, this assumption might be invalid in some cases.
For example, the 'UUID()' function is nondeterministic (and does not
replicate).  Be careful about using such functions in triggers.

Triggers can update tables, so error messages similar to those for
stored functions occur with 'CREATE TRIGGER' if
you do not have the required privileges.  On the slave side, the slave
uses the trigger 'DEFINER' attribute to determine which user is
considered to be the creator of the trigger.

The rest of this section provides additional detail about the logging
implementation and its implications.  You need not read it unless you
are interested in the background on the rationale for the current
logging-related conditions on stored routine use.  This discussion
applies only for statement-based logging, and not for row-based logging,
with the exception of the first item: 'CREATE' and 'DROP' statements are
logged as statements regardless of the logging mode.

   * The server writes 'CREATE EVENT', 'CREATE PROCEDURE',
     see 'CREATE FUNCTION',
     see 'ALTER EVENT', 'ALTER PROCEDURE',
     see 'ALTER FUNCTION',
     see 'DROP EVENT', 'DROP PROCEDURE',
     and 'DROP FUNCTION'
     statements to the binary log.

   * A stored function invocation is logged as a 'SELECT'.
     statement if the function changes data and occurs within a
     statement that would not otherwise be logged.  This prevents
     nonreplication of data changes that result from use of stored
     functions in nonlogged statements.  For example, see 'SELECT'
     statements are not written to the binary log, but a
     'SELECT' might invoke a stored function that makes
     changes.  To handle this, a 'SELECT FUNC_NAME()' statement is
     written to the binary log when the given function makes a change.
     Suppose that the following statements are executed on the master:

          CREATE FUNCTION f1(a INT) RETURNS INT
          BEGIN
            IF (a < 3) THEN
              INSERT INTO t2 VALUES (a);
            END IF;
            RETURN 0;
          END;

          CREATE TABLE t1 (a INT);
          INSERT INTO t1 VALUES (1),(2),(3);

          SELECT f1(a) FROM t1;

     When the 'SELECT' statement executes, the function
     'f1()' is invoked three times.  Two of those invocations insert a
     row, and MySQL logs a 'SELECT' statement for each of
     them.  That is, MySQL writes the following statements to the binary
     log:

          SELECT f1(1);
          SELECT f1(2);

     The server also logs a 'SELECT' statement for a
     stored function invocation when the function invokes a stored
     procedure that causes an error.  In this case, the server writes
     the 'SELECT' statement to the log along with the
     expected error code.  On the slave, if the same error occurs, that
     is the expected result and replication continues.  Otherwise,
     replication stops.

   * Logging stored function invocations rather than the statements
     executed by a function has a security implication for replication,
     which arises from two factors:

        * It is possible for a function to follow different execution
          paths on master and slave servers.

        * Statements executed on a slave are processed by the slave SQL
          thread which has full privileges.

     The implication is that although a user must have the 'CREATE
     ROUTINE' privilege to create a function, the user can write a
     function containing a dangerous statement that will execute only on
     the slave where it is processed by a thread that has full
     privileges.  For example, if the master and slave servers have
     server ID values of 1 and 2, respectively, a user on the master
     server could create and invoke an unsafe function 'unsafe_func()'
     as follows:

          mysql> delimiter //
          mysql> CREATE FUNCTION unsafe_func () RETURNS INT
              -> BEGIN
              ->   IF @@server_id=2 THEN DANGEROUS_STATEMENT; END IF;
              ->   RETURN 1;
              -> END;
              -> //
          mysql> delimiter ;
          mysql> INSERT INTO t VALUES(unsafe_func());

     The 'CREATE FUNCTION' and 'INSERT'
     statements are written to the binary log, so the slave will
     execute them.  Because the slave SQL thread has full privileges, it
     will execute the dangerous statement.  Thus, the function
     invocation has different effects on the master and slave and is not
     replication-safe.

     To guard against this danger for servers that have binary logging
     enabled, stored function creators must have the 'SUPER' privilege,
     in addition to the usual 'CREATE ROUTINE' privilege that is
     required.  Similarly, to use 'ALTER FUNCTION',
     you must have the 'SUPER' privilege in addition to
     the 'ALTER ROUTINE' privilege.  Without the 'SUPER' privilege, an
     error will occur:

          ERROR 1419 (HY000): You do not have the SUPER privilege and
          binary logging is enabled (you *might* want to use the less safe
          log_bin_trust_function_creators variable)

     If you do not want to require function creators to have the 'SUPER'
     privilege (for example, if all users with the 'CREATE ROUTINE'
     privilege on your system are experienced application developers),
     set the global 'log_bin_trust_function_creators' system variable to
     1.  You can also set this variable by using the
     '--log-bin-trust-function-creators=1' option when starting the
     server.  If binary logging is not enabled,
     'log_bin_trust_function_creators' does not apply.  'SUPER' is not
     required for function creation unless, as described previously, the
     'DEFINER' value in the function definition requires it.

   * If a function that performs updates is nondeterministic, it is not
     repeatable.  This can have two undesirable effects:

        * It will make a slave different from the master.

        * Restored data will be different from the original data.

     To deal with these problems, MySQL enforces the following
     requirement: On a master server, creation and alteration of a
     function is refused unless you declare the function to be
     deterministic or to not modify data.  Two sets of function
     characteristics apply here:

        * The 'DETERMINISTIC' and 'NOT DETERMINISTIC' characteristics
          indicate whether a function always produces the same result
          for given inputs.  The default is 'NOT DETERMINISTIC' if
          neither characteristic is given.  To declare that a function
          is deterministic, you must specify 'DETERMINISTIC' explicitly.

        * The 'CONTAINS SQL', 'NO SQL', 'READS SQL DATA', and 'MODIFIES
          SQL DATA' characteristics provide information about whether
          the function reads or writes data.  Either 'NO SQL' or 'READS
          SQL DATA' indicates that a function does not change data, but
          you must specify one of these explicitly because the default
          is 'CONTAINS SQL' if no characteristic is given.

     By default, for a 'CREATE FUNCTION'.
     statement to be accepted, at least one of 'DETERMINISTIC', 'NO
     SQL', or 'READS SQL DATA' must be specified explicitly.  Otherwise
     an error occurs:

          ERROR 1418 (HY000): This function has none of DETERMINISTIC, NO SQL,
          or READS SQL DATA in its declaration and binary logging is enabled
          (you *might* want to use the less safe log_bin_trust_function_creators
          variable)

     If you set 'log_bin_trust_function_creators' to 1, the requirement
     that functions be deterministic or not modify data is dropped.

   * Stored procedure calls are logged at the statement level rather
     than at the 'CALL' level.  That is, the server does
     not log the 'CALL' statement, it logs those statements
     within the procedure that actually execute.  As a result, the same
     changes that occur on the master will be observed on slave servers.
     This prevents problems that could result from a procedure having
     different execution paths on different machines.

     In general, statements executed within a stored procedure are
     written to the binary log using the same rules that would apply
     were the statements to be executed in standalone fashion.  Some
     special care is taken when logging procedure statements because
     statement execution within procedures is not quite the same as in
     nonprocedure context:

        *
          A statement to be logged might contain references to local
          procedure variables.  These variables do not exist outside of
          stored procedure context, so a statement that refers to such a
          variable cannot be logged literally.  Instead, each reference
          to a local variable is replaced by this construct for logging
          purposes:

               NAME_CONST(VAR_NAME, VAR_VALUE)

          VAR_NAME is the local variable name, and VAR_VALUE is a
          constant indicating the value that the variable has at the
          time the statement is logged.  'NAME_CONST()' has a value of
          VAR_VALUE, and a 'name' of VAR_NAME.  Thus, if you invoke this
          function directly, you get a result like this:

               mysql> SELECT NAME_CONST('myname', 14);
               +--------+
               | myname |
               +--------+
               |     14 |
               +--------+

          'NAME_CONST()' enables a logged standalone statement to be
          executed on a slave with the same effect as the original
          statement that was executed on the master within a stored
          procedure.

          The use of 'NAME_CONST()' can result in a problem for
          'CREATE TABLE ... SELECT' statements when the
          source column expressions refer to local variables.
          Converting these references to 'NAME_CONST()' expressions can
          result in column names that are different on the master and
          slave servers, or names that are too long to be legal column
          identifiers.  A workaround is to supply aliases for columns
          that refer to local variables.  Consider this statement when
          'myvar' has a value of 1:

               CREATE TABLE t1 SELECT myvar;

          That will be rewritten as follows:

               CREATE TABLE t1 SELECT NAME_CONST(myvar, 1);

          To ensure that the master and slave tables have the same
          column names, write the statement like this:

               CREATE TABLE t1 SELECT myvar AS myvar;

          The rewritten statement becomes:

               CREATE TABLE t1 SELECT NAME_CONST(myvar, 1) AS myvar;

        * A statement to be logged might contain references to
          user-defined variables.  To handle this, MySQL writes a
          'SET' statement to the binary log to make sure
          that the variable exists on the slave with the same value as
          on the master.  For example, if a statement refers to a
          variable '@my_var', that statement will be preceded in the
          binary log by the following statement, where VALUE is the
          value of '@my_var' on the master:

               SET @my_var = VALUE;

        * Procedure calls can occur within a committed or rolled-back
          transaction.  Transactional context is accounted for so that
          the transactional aspects of procedure execution are
          replicated correctly.  That is, the server logs those
          statements within the procedure that actually execute and
          modify data, and also logs 'BEGIN',
          'COMMIT', and 'ROLLBACK' statements as
          necessary.  For example, if a procedure updates only
          transactional tables and is executed within a transaction that
          is rolled back, those updates are not logged.  If the
          procedure occurs within a committed transaction, see
          'BEGIN' and 'COMMIT' statements are
          logged with the updates.  For a procedure that executes within
          a rolled-back transaction, its statements are logged using the
          same rules that would apply if the statements were executed in
          standalone fashion:

             * Updates to transactional tables are not logged.

             * Updates to nontransactional tables are logged because
               rollback does not cancel them.

             * Updates to a mix of transactional and nontransactional
               tables are logged surrounded by 'BEGIN'.
               and 'ROLLBACK' so that slaves will make
               the same changes and rollbacks as on the master.

   * A stored procedure call is _not_ written to the binary log at the
     statement level if the procedure is invoked from within a stored
     function.  In that case, the only thing logged is the statement
     that invokes the function (if it occurs within a statement that is
     logged) or a 'DO' statement (if it occurs within a
     statement that is not logged).  For this reason, care should be
     exercised in the use of stored functions that invoke a procedure,
     even if the procedure is otherwise safe in itself.

24 INFORMATION_SCHEMA Tables
****************************

'INFORMATION_SCHEMA' provides access to database _metadata_, information
about the MySQL server such as the name of a database or table, the data
type of a column, or access privileges.  Other terms that are sometimes
used for this information are _data dictionary_ and _system catalog_.

*INFORMATION_SCHEMA Usage Notes*

'INFORMATION_SCHEMA' is a database within each MySQL instance, the place
that stores information about all the other databases that the MySQL
server maintains.  The 'INFORMATION_SCHEMA' database contains several
read-only tables.  They are actually views, not base tables, so there
are no files associated with them, and you cannot set triggers on them.
Also, there is no database directory with that name.

Although you can select 'INFORMATION_SCHEMA' as the default database
with a 'USE' statement, you can only read the contents of
tables, not perform 'INSERT', 'UPDATE', or
'DELETE' operations on them.

*Example*

Here is an example of a statement that retrieves information from
'INFORMATION_SCHEMA':

     mysql> SELECT table_name, table_type, engine
            FROM information_schema.tables
            WHERE table_schema = 'db5'
            ORDER BY table_name;
     +------------+------------+--------+
     | table_name | table_type | engine |
     +------------+------------+--------+
     | fk         | BASE TABLE | InnoDB |
     | fk2        | BASE TABLE | InnoDB |
     | goto       | BASE TABLE | MyISAM |
     | into       | BASE TABLE | MyISAM |
     | k          | BASE TABLE | MyISAM |
     | kurs       | BASE TABLE | MyISAM |
     | loop       | BASE TABLE | MyISAM |
     | pk         | BASE TABLE | InnoDB |
     | t          | BASE TABLE | MyISAM |
     | t2         | BASE TABLE | MyISAM |
     | t3         | BASE TABLE | MyISAM |
     | t7         | BASE TABLE | MyISAM |
     | tables     | BASE TABLE | MyISAM |
     | v          | VIEW       | NULL   |
     | v2         | VIEW       | NULL   |
     | v3         | VIEW       | NULL   |
     | v56        | VIEW       | NULL   |
     +------------+------------+--------+
     17 rows in set (0.01 sec)

Explanation: The statement requests a list of all the tables in database
'db5', showing just three pieces of information: the name of the table,
its type, and its storage engine.

*Character Set Considerations*

The definition for character columns (for example, 'TABLES.TABLE_NAME')
is generally 'VARCHAR(N) CHARACTER SET utf8' where N is at least 64.
MySQL uses the default collation for this character set
('utf8_general_ci') for all searches, sorts, comparisons, and other
string operations on such columns.

Because some MySQL objects are represented as files, searches in
'INFORMATION_SCHEMA' string columns can be affected by file system case
sensitivity.  For more information, see
charset-collation-information-schema.

*INFORMATION_SCHEMA as Alternative to SHOW Statements*

The 'SELECT ... FROM INFORMATION_SCHEMA' statement is intended as a more
consistent way to provide access to the information provided by the
various 'SHOW' statements that MySQL supports (see 'SHOW DATABASES',
see 'SHOW TABLES', and so
forth).  Using 'SELECT' has these advantages, compared to
'SHOW'.:

   * It conforms to Codd's rules, because all access is done on tables.

   * You can use the familiar syntax of the 'SELECT'.
     statement, and only need to learn some table and column names.

   * The implementor need not worry about adding keywords.

   * You can filter, sort, concatenate, and transform the results from
     'INFORMATION_SCHEMA' queries into whatever format your application
     needs, such as a data structure or a text representation to parse.

   * This technique is more interoperable with other database systems.
     For example, Oracle Database users are familiar with querying
     tables in the Oracle data dictionary.

Because 'SHOW' is familiar and widely used, the
'SHOW' statements remain as an alternative.  In fact, along with
the implementation of 'INFORMATION_SCHEMA', there are enhancements to
'SHOW' as described in extended-show.

*Privileges*

Each MySQL user has the right to access these tables, but can see only
the rows in the tables that correspond to objects for which the user has
the proper access privileges.  In some cases (for example, the
'ROUTINE_DEFINITION' column in the 'INFORMATION_SCHEMA.ROUTINES'
table), users who have insufficient privileges see
'NULL'.  These restrictions do not apply for 'InnoDB'
tables; you can see them with only the 'PROCESS'
privilege.

The same privileges apply to selecting information from
'INFORMATION_SCHEMA' and viewing the same information through
'SHOW' statements.  In either case, you must have some privilege
on an object to see information about it.

*Performance Considerations*

'INFORMATION_SCHEMA' queries that search for information from more than
one database might take a long time and impact performance.  To check
the efficiency of a query, you can use 'EXPLAIN'.  For
information about using 'EXPLAIN' output to tune
'INFORMATION_SCHEMA' queries, see
information-schema-optimization.

*Standards Considerations*

The implementation for the 'INFORMATION_SCHEMA' table structures in
MySQL follows the ANSI/ISO SQL:2003 standard Part 11 'Schemata'.  Our
intent is approximate compliance with SQL:2003 core feature F021 'Basic
information schema'.

Users of SQL Server 2000 (which also follows the standard) may notice a
strong similarity.  However, MySQL has omitted many columns that are not
relevant for our implementation, and added columns that are
MySQL-specific.  One such column is the 'ENGINE' column in the
'INFORMATION_SCHEMA.TABLES' table.

Although other DBMSs use a variety of names, like 'syscat' or 'system',
the standard name is 'INFORMATION_SCHEMA'.

To avoid using any name that is reserved in the standard or in DB2, SQL
Server, or Oracle, we changed the names of some columns marked 'MySQL
extension'.  (For example, we changed 'COLLATION' to 'TABLE_COLLATION'
in the 'TABLES' table.)  See the list of reserved
words near the end of this article:
<https://web.archive.org/web/20070428032454/http://www.dbazine.com/db2/db2-disarticles/gulutzan5>.

*Conventions in the INFORMATION_SCHEMA Reference Sections*

The following sections describe each of the tables and columns in
'INFORMATION_SCHEMA'.  For each column, there are three pieces of
information:

   * ''INFORMATION_SCHEMA' Name' indicates the name for the column in
     the 'INFORMATION_SCHEMA' table.  This corresponds to the standard
     SQL name unless the 'Remarks' field says 'MySQL extension.'

   * ''SHOW'. Name' indicates the equivalent field name in
     the closest 'SHOW' statement, if there is one.

   * 'Remarks' provides additional information where applicable.  If
     this field is 'NULL', it means that the value of the column is
     always 'NULL'.  If this field says 'MySQL extension,' the column is
     a MySQL extension to standard SQL.

Many sections indicate what 'SHOW' statement is equivalent
to a 'SELECT' that retrieves information from
'INFORMATION_SCHEMA'.  For 'SHOW' statements that display
information for the default database if you omit a 'FROM DB_NAME'
clause, you can often select information for the default database by
adding an 'AND TABLE_SCHEMA = SCHEMA()' condition to the 'WHERE' clause
of a query that retrieves information from an 'INFORMATION_SCHEMA'
table.

*Related Information*

These sections discuss additional 'INFORMATION_SCHEMA'-related topics:

   * information about 'INFORMATION_SCHEMA' tables specific to the
     'InnoDB' storage engine:
     innodb-i_s-tables

   * information about 'INFORMATION_SCHEMA' tables specific to the
     thread pool plugin: thread-pool-i_s-tables

   * Answers to questions that are often asked concerning the
     'INFORMATION_SCHEMA' database: faqs-information-schema

   * 'INFORMATION_SCHEMA' queries and the optimizer:
     information-schema-optimization

   * The effect of collation on 'INFORMATION_SCHEMA' comparisons:
     charset-collation-information-schema

24.1 The INFORMATION_SCHEMA CHARACTER_SETS Table
================================================

The 'CHARACTER_SETS' table provides
information about available character sets.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'CHARACTER_SET_NAME'          'Charset'

'DEFAULT_COLLATE_NAME'        'Default collation'

'DESCRIPTION'                 'Description'          MySQL extension

'MAXLEN'                      'Maxlen'               MySQL extension

The following statements are equivalent:

     SELECT * FROM INFORMATION_SCHEMA.CHARACTER_SETS
       [WHERE CHARACTER_SET_NAME LIKE 'WILD']

     SHOW CHARACTER SET
       [LIKE 'WILD']

24.2 The INFORMATION_SCHEMA COLLATIONS Table
============================================

The 'COLLATIONS' table provides information
about collations for each character set.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'COLLATION_NAME'              'Collation'

'CHARACTER_SET_NAME'          'Charset'              MySQL extension

'ID'                          'Id'                   MySQL extension

'IS_DEFAULT'                  'Default'              MySQL extension

'IS_COMPILED'                 'Compiled'             MySQL extension

'SORTLEN'                     'Sortlen'              MySQL extension

   * 'COLLATION_NAME' is the collation name.

   * 'CHARACTER_SET_NAME' is the name of the character set with which
     the collation is associated.

   * 'ID' is the collation ID.

   * 'IS_DEFAULT' indicates whether the collation is the default for its
     character set.

   * 'IS_COMPILED' indicates whether the character set is compiled into
     the server.

   * 'SORTLEN' is related to the amount of memory required to sort
     strings expressed in the character set.

Collation information is also available from the 'SHOW COLLATION'
statement.  The following statements are equivalent:

     SELECT COLLATION_NAME FROM INFORMATION_SCHEMA.COLLATIONS
       [WHERE COLLATION_NAME LIKE 'WILD']

     SHOW COLLATION
       [LIKE 'WILD']

24.3 The INFORMATION_SCHEMA COLLATION_CHARACTER_SET_APPLICABILITY Table
=======================================================================

The 'COLLATION_CHARACTER_SET_APPLICABILITY'
table indicates what
character set is applicable for what collation.  The columns are
equivalent to the first two display fields that we get from 'SHOW COLLATION'.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'COLLATION_NAME'              'Collation'

'CHARACTER_SET_NAME'          'Charset'

24.4 The INFORMATION_SCHEMA COLUMNS Table
=========================================

The 'COLUMNS' table provides information about
columns in tables.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'TABLE_CATALOG'                                      'def'

'TABLE_SCHEMA'

'TABLE_NAME'

'COLUMN_NAME'                 'Field'

'ORDINAL_POSITION'                                   see notes

'COLUMN_DEFAULT'              'Default'

'IS_NULLABLE'                 'Null'

'DATA_TYPE'                   'Type'

'CHARACTER_MAXIMUM_LENGTH'    'Type'

'CHARACTER_OCTET_LENGTH'

'NUMERIC_PRECISION'           'Type'

'NUMERIC_SCALE'               'Type'

'DATETIME_PRECISION'          'Type'

'CHARACTER_SET_NAME'

'COLLATION_NAME'              'Collation'

'COLUMN_TYPE'                 'Type'                 MySQL extension

'COLUMN_KEY'                  'Key'                  MySQL extension

'EXTRA'                       'Extra'                MySQL extension

'PRIVILEGES'                  'Privileges'           MySQL extension

'COLUMN_COMMENT'              'Comment'              MySQL extension

'GENERATION_EXPRESSION'                              MySQL extension

*Notes*:

   * In 'SHOW', the 'Type' display includes values from
     several different 'COLUMNS' columns.

   * 'ORDINAL_POSITION' is necessary because you might want to say
     'ORDER BY ORDINAL_POSITION'.  Unlike 'SHOW',
     'SELECT' does not have automatic ordering.

   * 'CHARACTER_OCTET_LENGTH' should be the same as
     'CHARACTER_MAXIMUM_LENGTH', except for multibyte character sets.

   * 'CHARACTER_SET_NAME' can be derived from 'Collation'.  For example,
     if you say 'SHOW FULL COLUMNS FROM t', and you see in the
     'Collation' column a value of 'latin1_swedish_ci', the character
     set is what is before the first underscore: 'latin1'.

   * 'GENERATION_EXPRESSION' is nonempty for generated columns and
     displays the expression used to compute column values.  For
     information about generated columns, see
     create-table-generated-columns.

   * The 'EXTRA' column contains 'VIRTUAL GENERATED' or 'VIRTUAL STORED'
     for generated columns.

The following statements are nearly equivalent:

     SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_DEFAULT
       FROM INFORMATION_SCHEMA.COLUMNS
       WHERE table_name = 'TBL_NAME'
       [AND table_schema = 'DB_NAME']
       [AND column_name LIKE 'WILD']

     SHOW COLUMNS
       FROM TBL_NAME
       [FROM DB_NAME]
       [LIKE 'WILD']

24.5 The INFORMATION_SCHEMA COLUMN_PRIVILEGES Table
===================================================

The 'COLUMN_PRIVILEGES' table provides
information about column privileges.  This information comes from the
'mysql.columns_priv' grant table.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'GRANTEE'                                            ''USER_NAME'@'HOST_NAME''
                                                     value

'TABLE_CATALOG'                                      'def'

'TABLE_SCHEMA'

'TABLE_NAME'

'COLUMN_NAME'

'PRIVILEGE_TYPE'

'IS_GRANTABLE'

*Notes*:

   * In the output from 'SHOW FULL COLUMNS', the
     privileges are all in one field and in lowercase, for example,
     'select,insert,update,references'.  In 'COLUMN_PRIVILEGES',
     there is one privilege per row, in
     uppercase.

   * 'PRIVILEGE_TYPE' can contain one (and only one) of these values:
     'SELECT', 'INSERT', 'UPDATE', 'REFERENCES'.

   * If the user has 'GRANT OPTION' privilege, 'IS_GRANTABLE' should be
     'YES'.  Otherwise, 'IS_GRANTABLE' should be 'NO'.  The output does
     not list 'GRANT OPTION' as a separate privilege.

The following statements are _not_ equivalent:

     SELECT ... FROM INFORMATION_SCHEMA.COLUMN_PRIVILEGES

     SHOW GRANTS ...

24.6 The INFORMATION_SCHEMA ENGINES Table
=========================================

The 'ENGINES' table provides information about
storage engines.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'ENGINE'                      'Engine'               MySQL extension

'SUPPORT'                     'Support'              MySQL extension

'COMMENT'                     'Comment'              MySQL extension

'TRANSACTIONS'                'Transactions'         MySQL extension

'XA'                          'XA'                   MySQL extension

'SAVEPOINTS'                  'Savepoints'           MySQL extension

*Notes*:

   * The 'ENGINES' table is a nonstandard table.
     Its contents correspond to the columns of the 'SHOW ENGINES'
     statement.  For descriptions of its columns, see
     show-engines.

See also show-engines.

24.7 The INFORMATION_SCHEMA EVENTS Table
========================================

The 'EVENTS' table provides information about
scheduled events, which are discussed in event-scheduler.  The
'SHOW Name' values correspond to column names of the 'SHOW EVENTS'
statement.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'EVENT_CATALOG'                                      'def', MySQL
                                                     extension

'EVENT_SCHEMA'                'Db'                   MySQL extension

'EVENT_NAME'                  'Name'                 MySQL extension

'DEFINER'                     'Definer'              MySQL extension

'TIME_ZONE'                   'Time zone'            MySQL extension

'EVENT_BODY'                                         MySQL extension

'EVENT_DEFINITION'                                   MySQL extension

'EVENT_TYPE'                  'Type'                 MySQL extension

'EXECUTE_AT'                  'Execute at'           MySQL extension

'INTERVAL_VALUE'              'Interval value'       MySQL extension

'INTERVAL_FIELD'              'Interval field'       MySQL extension

'SQL_MODE'                                           MySQL extension

'STARTS'                      'Starts'               MySQL extension

'ENDS'                        'Ends'                 MySQL extension

'STATUS'                      'Status'               MySQL extension

'ON_COMPLETION'                                      MySQL extension

'CREATED'                                            MySQL extension

'LAST_ALTERED'                                       MySQL extension

'LAST_EXECUTED'                                      MySQL extension

'EVENT_COMMENT'                                      MySQL extension

'ORIGINATOR'                  'Originator'           MySQL extension

'CHARACTER_SET_CLIENT'        'character_set_client' MySQL extension

'COLLATION_CONNECTION'        'collation_connection' MySQL extension

'DATABASE_COLLATION'          'Database Collation'   MySQL extension

*Notes*:

   * The 'EVENTS' table is a nonstandard table.

   * 'EVENT_CATALOG': The value of this column is always 'def'.

   * 'EVENT_SCHEMA': The name of the schema (database) to which this
     event belongs.

   * 'EVENT_NAME': The name of the event.

   * 'DEFINER': The account of the user who created the event, in
     ''USER_NAME'@'HOST_NAME'' format.

   * 'TIME_ZONE': The event time zone, which is the time zone used for
     scheduling the event and that is in effect within the event as it
     executes.  The default value is 'SYSTEM'.

   * 'EVENT_BODY': The language used for the statements in the event's
     'DO' clause; in MySQL 5.7, this is always 'SQL'.

     This column is not to be confused with the column of the same name
     (now named 'EVENT_DEFINITION') that existed in earlier MySQL
     versions.

   * 'EVENT_DEFINITION': The text of the SQL statement making up the
     event's 'DO' clause; in other words, the statement
     executed by this event.

   * 'EVENT_TYPE': The event repetition type, either 'ONE TIME'
     (transient) or 'RECURRING' (repeating).

   * 'EXECUTE_AT': For a one-time event, this is the 'DATETIME'
     value specified in the 'AT' clause of the 'CREATE EVENT'
     statement used to create the event, or of the
     last 'ALTER EVENT' statement that modified the
     event.  The value shown in this column reflects the addition or
     subtraction of any 'INTERVAL' value included in the event's 'AT'
     clause.  For example, if an event is created using 'ON SCHEDULE AT
     CURRENT_TIMESTAMP + '1:6' DAY_HOUR', and the event was created at
     2006-02-09 14:05:30, the value shown in this column would be
     ''2006-02-10 20:05:30''.

     If the event's timing is determined by an 'EVERY' clause instead of
     an 'AT' clause (that is, if the event is recurring), the value of
     this column is 'NULL'.

   * 'INTERVAL_VALUE': For recurring events, this column contains the
     numeric portion of the event's 'EVERY' clause.

     For a one-time event (that is, an event whose timing is determined
     by an 'AT' clause), this column is 'NULL'.

   * 'INTERVAL_FIELD': For recurring events, this column contains the
     units portion of the 'EVERY' clause governing the timing of the
     event.  Thus, this column contains a value such as ''YEAR'.',
     ''QUARTER'', ''DAY'', and so on.

     For a one-time event (that is, an event whose timing is determined
     by an 'AT' clause), this column is 'NULL'.

   * 'SQL_MODE': The SQL mode in effect when the event was created or
     altered, and under which the event executes.  For the permitted
     values, see sql-mode.

   * 'STARTS': For a recurring event whose definition includes a
     'STARTS' clause, this column contains the corresponding
     'DATETIME' value.  As with the 'EXECUTE_AT' column, this
     value resolves any expressions used.

     If there is no 'STARTS' clause affecting the timing of the event,
     this column is 'NULL'

   * 'ENDS': For a recurring event whose definition includes a 'ENDS'
     clause, this column contains the corresponding 'DATETIME'
     value.  As with the 'EXECUTE_AT' column, this value
     resolves any expressions used.

     If there is no 'ENDS' clause affecting the timing of the event,
     this column is 'NULL'.

   * 'STATUS': One of the three values 'ENABLED', 'DISABLED', or
     'SLAVESIDE_DISABLED'.

     'SLAVESIDE_DISABLED' indicates that the creation of the event
     occurred on another MySQL server acting as a replication master and
     was replicated to the current MySQL server which is acting as a
     slave, but the event is not presently being executed on the slave.
     See replication-features-invoked, for more information.

   * 'ON_COMPLETION': One of the two values 'PRESERVE' or 'NOT
     PRESERVE'.

   * 'CREATED': The date and time when the event was created.  This is a
     'TIMESTAMP' value.

   * 'LAST_ALTERED': The date and time when the event was last modified.
     This is a 'TIMESTAMP' value.  If the event has not
     been modified since its creation, this column holds the same value
     as the 'CREATED' column.

   * 'LAST_EXECUTED': The date and time when the event last executed.  A
     'DATETIME' value.  If the event has never
     executed, this column is 'NULL'.

     'LAST_EXECUTED' indicates when the event started.  As a result, the
     'ENDS' column is never less than 'LAST_EXECUTED'.

   * 'EVENT_COMMENT': The text of a comment, if the event has one.  If
     not, the value of this column is an empty string.

   * 'ORIGINATOR': The server ID of the MySQL server on which the event
     was created; used in replication.  The default value is 0.

   * 'CHARACTER_SET_CLIENT': The session value of the
     'character_set_client' system variable when the event was created.

   * 'COLLATION_CONNECTION': The session value of the
     'collation_connection' system variable when the event was created.

   * 'DATABASE_COLLATION': The collation of the database with which the
     event is associated.

*Example*: Suppose that the user 'jon@ghidora' creates an event named
'e_daily', and then modifies it a few minutes later using an
'ALTER EVENT' statement, as shown here:

     DELIMITER |

     CREATE EVENT e_daily
         ON SCHEDULE
           EVERY 1 DAY
         COMMENT 'Saves total number of sessions then clears the table each day'
         DO
           BEGIN
             INSERT INTO site_activity.totals (time, total)
               SELECT CURRENT_TIMESTAMP, COUNT(*)
                 FROM site_activity.sessions;
             DELETE FROM site_activity.sessions;
           END |

     DELIMITER ;

     ALTER EVENT e_daily
         ENABLE;

(Note that comments can span multiple lines.)

This user can then run the following 'SELECT' statement,
and obtain the output shown:

     mysql> SELECT * FROM INFORMATION_SCHEMA.EVENTS
          > WHERE EVENT_NAME = 'e_daily'
          > AND EVENT_SCHEMA = 'myschema'\G
     *************************** 1. row ***************************
            EVENT_CATALOG: def
             EVENT_SCHEMA: test
               EVENT_NAME: e_daily
                  DEFINER: me@localhost
                TIME_ZONE: SYSTEM
               EVENT_BODY: SQL
         EVENT_DEFINITION: BEGIN
             INSERT INTO site_activity.totals (time, total)
               SELECT CURRENT_TIMESTAMP, COUNT(*)
                 FROM site_activity.sessions;
             DELETE FROM site_activity.sessions;
           END
               EVENT_TYPE: RECURRING
               EXECUTE_AT: NULL
           INTERVAL_VALUE: 1
           INTERVAL_FIELD: DAY
                 SQL_MODE:
                   STARTS: 2008-09-03 12:13:39
                     ENDS: NULL
                   STATUS: ENABLED
            ON_COMPLETION: NOT PRESERVE
                  CREATED: 2008-09-03 12:13:39
             LAST_ALTERED: 2008-09-03 12:13:39
            LAST_EXECUTED: NULL
            EVENT_COMMENT: Saves total number of sessions then clears the
                           table each day
               ORIGINATOR: 1
     CHARACTER_SET_CLIENT: latin1
     COLLATION_CONNECTION: latin1_swedish_ci
       DATABASE_COLLATION: latin1_swedish_ci

Times in the 'EVENTS' table are displayed using the
event time zone or the current session time zone, as described in
events-metadata.

See also show-events.

24.8 The INFORMATION_SCHEMA FILES Table
=======================================

The 'FILES' table provides information about the
files in which MySQL tablespace data is stored.

'INFORMATION_SCHEMA.FILES' provides information
about 'InnoDB' data files.  In NDB Cluster this table also provides
information about the files in which NDB Cluster Disk Data tables are
stored.  For information specific to 'InnoDB', see
files-table-innodb-notes, later in this section; for information
specific to NDB Cluster, see files-table-ndb-notes.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'FILE_ID'                                            MySQL extension

'FILE_NAME'                                          MySQL extension

'FILE_TYPE'                                          MySQL extension

'TABLESPACE_NAME'                                    MySQL extension

'TABLE_CATALOG'                                      MySQL extension

'TABLE_SCHEMA'                                       MySQL extension

'TABLE_NAME'                                         MySQL extension

'LOGFILE_GROUP_NAME'                                 MySQL extension

'LOGFILE_GROUP_NUMBER'                               MySQL extension

'ENGINE'                                             MySQL extension

'FULLTEXT_KEYS'                                      MySQL extension

'DELETED_ROWS'                                       MySQL extension

'UPDATE_COUNT'                                       MySQL extension

'FREE_EXTENTS'                                       MySQL extension

'TOTAL_EXTENTS'                                      MySQL extension

'EXTENT_SIZE'                                        MySQL extension

'INITIAL_SIZE'                                       MySQL extension

'MAXIMUM_SIZE'                                       MySQL extension

'AUTOEXTEND_SIZE'                                    MySQL extension

'CREATION_TIME'                                      MySQL extension

'LAST_UPDATE_TIME'                                   MySQL extension

'LAST_ACCESS_TIME'                                   MySQL extension

'RECOVER_TIME'                                       MySQL extension

'TRANSACTION_COUNTER'                                MySQL extension

'VERSION'                                            MySQL extension

'ROW_FORMAT'                                         MySQL extension

'TABLE_ROWS'                                         MySQL extension

'AVG_ROW_LENGTH'                                     MySQL extension

'DATA_LENGTH'                                        MySQL extension

'MAX_DATA_LENGTH'                                    MySQL extension

'INDEX_LENGTH'                                       MySQL extension

'DATA_FREE'                                          MySQL extension

'CREATE_TIME'                                        MySQL extension

'UPDATE_TIME'                                        MySQL extension

'CHECK_TIME'                                         MySQL extension

'CHECKSUM'                                           MySQL extension

'STATUS'                                             MySQL extension

'EXTRA'                                              MySQL extension

*InnoDB Notes*

The following notes apply to 'InnoDB' data files.
'INFORMATION_SCHEMA.FILES' fields that are not described
below are not applicable to 'InnoDB' and report a 'NULL' value.

   * Data reported by 'INFORMATION_SCHEMA.FILES' is
     reported from the 'InnoDB' in-memory cache for open files.  By
     comparison, see 'INFORMATION_SCHEMA.INNODB_SYS_DATAFILES'
     reports data from the 'InnoDB'
     'SYS_DATAFILES' internal data dictionary table.

   * The data reported by 'INFORMATION_SCHEMA.FILES'.
     includes temporary tablespace data.  This data is not available in
     the internal 'SYS_DATAFILES' data dictionary table, and is
     therefore not reported by 'INNODB_SYS_DATAFILES'.

   * Undo tablespace data is reported by
     'INFORMATION_SCHEMA.FILES'.

   * 'FILE_ID' is the tablespace ID, also referred to as the 'space_id'
     or 'fil_space_t::id'.

   * 'FILE_NAME' is the name of the data file.  File-per-table and
     general tablespaces have a '.ibd' file name extension.  Undo
     tablespaces are prefixed by 'undo'.  The system tablespace is
     prefixed by 'ibdata'.  Temporary tablespaces are prefixed by
     'ibtmp'.  The file name includes the file path, which may be
     relative to the MySQL data directory ('datadir').

   * 'FILE_TYPE' is the tablespace file type.  There are three possible
     file types for 'InnoDB' files.  'TABLESPACE' is the file type for
     any system, general, or file-per-table tablespace file that holds
     tables, indexes, or other forms of user data.  'TEMPORARY' is the
     file type for temporary tablespaces.  'UNDO LOG' is the file type
     for undo tablespaces, which hold undo records.

   * 'TABLESPACE_NAME' is the SQL name for the tablespace.  A general
     tablespace name is the 'SYS_TABLESPACES.NAME' value.  For other
     tablespace files, names start with 'innodb_', such as
     'innodb_system', 'innodb_undo', and 'innodb_file_per_table'.  The
     file-per-table tablespace name format is
     'innodb_file_per_table_##', where ## is the tablespace ID.

   * 'ENGINE' is the storage engine.  For 'InnoDB' files, the value is
     always 'InnoDB'.

   * 'FREE_EXTENTS' is the number of fully free extents in the current
     data file.

   * 'TOTAL_EXTENTS' is the number of full extents used in the current
     data file.  Any partial extent at the end of the file is not
     counted.

   * 'EXTENT_SIZE' is 1048576 (1MB) for files with a 4k, 8k, or 16k page
     size.  Extent size is 2097152 bytes (2MB) for files with a 32k page
     size, and 4194304 (4MB) for files with a 64k page size.
     'INFORMATION_SCHEMA.FILES' does not report 'InnoDB'
     page size.  Page size is defined by the 'innodb_page_size' option.
     Extent size information can also be retrieved from
     'INNODB_SYS_TABLESPACES' where
     'FILES.FILE_ID = INNODB_SYS_TABLESPACES.SPACE_ID'.

   * 'INITIAL_SIZE' is the initial size of the file, in bytes.

   * 'MAXIMUM_SIZE' is the maximum number of bytes allowed in the file.
     The value is 'NULL' for all data files except for predefined system
     tablespace data files.  Maximum system tablespace file size is
     defined by 'innodb_data_file_path'.  Maximum temporary tablespace
     file size is defined by 'innodb_temp_data_file_path'.  A 'NULL'
     value for a predefined system tablespace data file indicates that a
     file size limit was not defined explicitly.

   * 'AUTOEXTEND_SIZE' is the auto-extend size defined by
     'innodb_data_file_path' for the system tablespace, or defined by
     'innodb_temp_data_file_path' for temporary tablespaces.

   * 'DATA_FREE' is the total amount of free space (in bytes) for the
     entire tablespace.  Predefined system tablespaces, which include
     the system tablespace and temporary table tablespaces, may have one
     or more data files.

   * 'STATUS' is 'NORMAL' by default.  'InnoDB' file-per-table
     tablespaces may report 'IMPORTING', which indicates that the
     tablespace is not yet available.

   * The following query returns all data pertinent to 'InnoDB'
     tablespaces.

          mysql>SELECT FILE_ID, FILE_NAME, FILE_TYPE, TABLESPACE_NAME, FREE_EXTENTS, TOTAL_EXTENTS,
          EXTENT_SIZE, INITIAL_SIZE, MAXIMUM_SIZE, AUTOEXTEND_SIZE, DATA_FREE, STATUS ENGINE
          FROM INFORMATION_SCHEMA.FILES \G

*NDB Notes*

   * The 'FILES' table provides information about Disk Data _files_
     only; you cannot use it for determining disk space allocation or
     availability for individual 'NDB' tables.  However, it is possible
     to see how much space is allocated for each 'NDB'
     table having data stored on disk--as well as how
     much remains available for storage of data on disk for that
     table--using 'ndb_desc'.
     For more information, see mysql-cluster-programs-ndb-desc.

   * 'FILE_ID' column values are auto-generated.

   * 'FILE_NAME' is the name of an 'UNDO' log file created by
     'CREATE LOGFILE GROUP' or 'ALTER LOGFILE GROUP',
     or of a data file created by
     'CREATE TABLESPACE' or 'ALTER TABLESPACE'.

   * 'FILE_TYPE' is one of the values 'UNDOFILE', 'DATAFILE', or
     'TABLESPACE'.

   * 'TABLESPACE_NAME' is the name of the tablespace with which the file
     is associated.

   * Currently, the value of the 'TABLESPACE_CATALOG' column is always
     'NULL'.

   * 'TABLE_NAME' is the name of the Disk Data table with which the file
     is associated, if any.

   * The 'LOGFILE_GROUP_NAME' column gives the name of the log file
     group to which the log file or data file belongs.

   * For an 'UNDO' log file, the 'LOGFILE_GROUP_NUMBER' contains the
     auto-generated ID number of the log file group to which the log
     file belongs.

   * For an NDB Cluster Disk Data log file or data file, the value of
     the 'ENGINE' column is always 'NDB' or
     'NDBCLUSTER'.

   * For an NDB Cluster Disk Data log file or data file, the value of
     the 'FULLTEXT_KEYS' column is always empty.

   * The 'FREE EXTENTS' column displays the number of extents which have
     not yet been used by the file.  The 'TOTAL EXTENTS' column show the
     total number of extents allocated to the file.

     The difference between these two columns is the number of extents
     currently in use by the file:

          SELECT TOTAL_EXTENTS - FREE_EXTENTS AS extents_used
              FROM INFORMATION_SCHEMA.FILES
              WHERE FILE_NAME = 'myfile.dat';

     You can approximate the amount of disk space in use by the file by
     multiplying this difference by the value of the 'EXTENT_SIZE'
     column, which gives the size of an extent for the file in bytes:

          SELECT (TOTAL_EXTENTS - FREE_EXTENTS) * EXTENT_SIZE AS bytes_used
              FROM INFORMATION_SCHEMA.FILES
              WHERE FILE_NAME = 'myfile.dat';

     Similarly, you can estimate the amount of space that remains
     available in a given file by multiplying 'FREE_EXTENTS' by
     'EXTENT_SIZE':

          SELECT FREE_EXTENTS * EXTENT_SIZE AS bytes_free
              FROM INFORMATION_SCHEMA.FILES
              WHERE FILE_NAME = 'myfile.dat';

     *Important*:

     The byte values produced by the preceding queries are
     approximations only, and their precision is inversely proportional
     to the value of 'EXTENT_SIZE'.  That is, the larger 'EXTENT_SIZE'
     becomes, the less accurate the approximations are.

     It is also important to remember that once an extent is used, it
     cannot be freed again without dropping the data file of which it is
     a part.  This means that deletes from a Disk Data table do _not_
     release disk space.

     The extent size can be set in a 'CREATE TABLESPACE'
     statement.  See create-tablespace, for
     more information.

   * The 'INITIAL_SIZE' column shows the size in bytes of the file.
     This is the same value that was used in the 'INITIAL_SIZE' clause
     of the 'CREATE LOGFILE GROUP',
     'ALTER LOGFILE GROUP', 'CREATE TABLESPACE',
     or 'ALTER TABLESPACE'
     statement used to create the file.

     For NDB Cluster Disk Data files, the value of the 'MAXIMUM_SIZE'
     column is always the same as 'INITIAL_SIZE', and the
     'AUTOEXTEND_SIZE' column is always empty.

   * The 'CREATION_TIME' column shows the date and time when the file
     was created.  The 'LAST_UPDATE_TIME' column displays the date and
     time when the file was last modified.  The 'LAST_ACCESSED' column
     provides the date and time when the file was last accessed by the
     server.

     Currently, the values of these columns are as reported by the
     operating system, and are not supplied by the 'NDB'
     storage engine.  Where no value is provided by the
     operating system, these columns display '0000-00-00 00:00:00'.

   * For NDB Cluster Disk Data files, the value of the 'RECOVER_TIME'
     and 'TRANSACTION_COUNTER' columns is always '0'.

   * For NDB Cluster Disk Data files, the following columns are always
     'NULL':

        * 'VERSION'

        * 'ROW_FORMAT'

        * 'TABLE_ROWS'

        * 'AVG_ROW_LENGTH'

        * 'DATA_LENGTH'

        * 'MAX_DATA_LENGTH'

        * 'INDEX_LENGTH'

        * 'DATA_FREE'

        * 'CREATE_TIME'

        * 'UPDATE_TIME'

        * 'CHECK_TIME'

        * 'CHECKSUM'

   * For NDB Cluster Disk Data files, the value of the 'STATUS' column
     is always 'NORMAL'.

   * For NDB Cluster Disk Data files, the 'EXTRA' column shows which
     data node the file belongs to, as each data node has its own copy
     of the file.  Suppose that you use this statement on an NDB Cluster
     with four data nodes:

          CREATE LOGFILE GROUP mygroup
              ADD UNDOFILE 'new_undo.dat'
              INITIAL_SIZE 2G
              ENGINE NDB;

     After running the 'CREATE LOGFILE GROUP'
     statement successfully, you should see a
     result similar to the one shown here for this query against the
     'FILES' table:

          mysql> SELECT LOGFILE_GROUP_NAME, FILE_TYPE, EXTRA
              ->     FROM INFORMATION_SCHEMA.FILES
              ->     WHERE FILE_NAME = 'new_undo.dat';
          +--------------------+-------------+----------------+
          | LOGFILE_GROUP_NAME | FILE_TYPE   | EXTRA          |
          +--------------------+-------------+----------------+
          | mygroup            | UNDO FILE   | CLUSTER_NODE=3 |
          | mygroup            | UNDO FILE   | CLUSTER_NODE=4 |
          | mygroup            | UNDO FILE   | CLUSTER_NODE=5 |
          | mygroup            | UNDO FILE   | CLUSTER_NODE=6 |
          +--------------------+-------------+----------------+
          4 rows in set (0.01 sec)

   * The 'FILES' table is a nonstandard table.

   * An additional row is present in the 'FILES'.
     table following the creation of a logfile group.  This row has
     'NULL' for the value of the 'FILE_NAME' column.  For this row, the
     value of the 'FILE_ID' column is always '0', that of the
     'FILE_TYPE' column is always 'UNDO FILE', and that of the 'STATUS'
     column is always 'NORMAL'.  Currently, the value of the 'ENGINE'
     column is always 'NDBCLUSTER'.

     The 'FREE_EXTENTS' column in this row shows the total number of
     free extents available to all undo files belonging to a given log
     file group whose name and number are shown in the
     'LOGFILE_GROUP_NAME' and 'LOGFILE_GROUP_NUMBER' columns,
     respectively.

     Suppose there are no existing log file groups on your NDB Cluster,
     and you create one using the following statement:

          mysql> CREATE LOGFILE GROUP lg1
              ->   ADD UNDOFILE 'undofile.dat'
              ->   INITIAL_SIZE = 16M
              ->   UNDO_BUFFER_SIZE = 1M
              ->   ENGINE = NDB;
          Query OK, 0 rows affected (3.81 sec)

     You can now see this 'NULL' row when you query the 'FILES'
     table:

          mysql> SELECT DISTINCT
              ->   FILE_NAME AS File,
              ->   FREE_EXTENTS AS Free,
              ->   TOTAL_EXTENTS AS Total,
              ->   EXTENT_SIZE AS Size,
              ->   INITIAL_SIZE AS Initial
              ->   FROM INFORMATION_SCHEMA.FILES;
          +--------------+---------+---------+------+----------+
          | File         | Free    | Total   | Size | Initial  |
          +--------------+---------+---------+------+----------+
          | undofile.dat |    NULL | 4194304 |    4 | 16777216 |
          | NULL         | 4184068 |    NULL |    4 |     NULL |
          +--------------+---------+---------+------+----------+
          2 rows in set (0.01 sec)

     The total number of free extents available for undo logging is
     always somewhat less than the sum of the 'TOTAL_EXTENTS' column
     values for all undo files in the log file group due to overhead
     required for maintaining the undo files.  This can be seen by
     adding a second undo file to the log file group, then repeating the
     previous query against the 'FILES' table:

          mysql> ALTER LOGFILE GROUP lg1
              ->   ADD UNDOFILE 'undofile02.dat'
              ->   INITIAL_SIZE = 4M
              ->   ENGINE = NDB;
          Query OK, 0 rows affected (1.02 sec)

          mysql> SELECT DISTINCT
              ->   FILE_NAME AS File,
              ->   FREE_EXTENTS AS Free,
              ->   TOTAL_EXTENTS AS Total,
              ->   EXTENT_SIZE AS Size,
              ->   INITIAL_SIZE AS Initial
              ->   FROM INFORMATION_SCHEMA.FILES;
          +----------------+---------+---------+------+----------+
          | File           | Free    | Total   | Size | Initial  |
          +----------------+---------+---------+------+----------+
          | undofile.dat   |    NULL | 4194304 |    4 | 16777216 |
          | undofile02.dat |    NULL | 1048576 |    4 |  4194304 |
          | NULL           | 5223944 |    NULL |    4 |     NULL |
          +----------------+---------+---------+------+----------+
          3 rows in set (0.01 sec)

     The amount of free space in bytes which is available for undo
     logging by Disk Data tables using this log file group can be
     approximated by multiplying the number of free extents by the
     initial size:

          mysql> SELECT
              ->   FREE_EXTENTS AS 'Free Extents',
              ->   FREE_EXTENTS * EXTENT_SIZE AS 'Free Bytes'
              ->   FROM INFORMATION_SCHEMA.FILES
              ->   WHERE LOGFILE_GROUP_NAME = 'lg1'
              ->   AND FILE_NAME IS NULL;
          +--------------+------------+
          | Free Extents | Free Bytes |
          +--------------+------------+
          |      5223944 |   20895776 |
          +--------------+------------+
          1 row in set (0.02 sec)

     If you create an NDB Cluster Disk Data table and then insert some
     rows into it, you can see approximately how much space remains for
     undo logging afterward, for example:

          mysql> CREATE TABLESPACE ts1
              ->   ADD DATAFILE 'data1.dat'
              ->   USE LOGFILE GROUP lg1
              ->   INITIAL_SIZE 512M
              ->   ENGINE = NDB;
          Query OK, 0 rows affected (8.71 sec)

          mysql> CREATE TABLE dd (
              ->   c1 INT NOT NULL PRIMARY KEY,
              ->   c2 INT,
              ->   c3 DATE
              ->   )
              ->   TABLESPACE ts1 STORAGE DISK
              ->   ENGINE = NDB;
          Query OK, 0 rows affected (2.11 sec)

          mysql> INSERT INTO dd VALUES
              ->   (NULL, 1234567890, '2007-02-02'),
              ->   (NULL, 1126789005, '2007-02-03'),
              ->   (NULL, 1357924680, '2007-02-04'),
              ->   (NULL, 1642097531, '2007-02-05');
          Query OK, 4 rows affected (0.01 sec)

          mysql> SELECT
              ->   FREE_EXTENTS AS 'Free Extents',
              ->   FREE_EXTENTS * EXTENT_SIZE AS 'Free Bytes'
              ->   FROM INFORMATION_SCHEMA.FILES
              ->   WHERE LOGFILE_GROUP_NAME = 'lg1'
              ->   AND FILE_NAME IS NULL;
          +--------------+------------+
          | Free Extents | Free Bytes |
          +--------------+------------+
          |      5207565 |   20830260 |
          +--------------+------------+
          1 row in set (0.01 sec)

   * An additional row is present in the 'FILES'.
     table for any NDB Cluster tablespace, whether or not any data files
     are associated with the tablespace.  This row has 'NULL' for the
     value of the 'FILE_NAME' column.  For this row, the value of the
     'FILE_ID' column is always '0', that of the 'FILE_TYPE' column is
     always 'TABLESPACE', and that of the 'STATUS' column is always
     'NORMAL'.  Currently, the value of the 'ENGINE' column is always
     'NDBCLUSTER'.

   * There are no 'SHOW' statements associated with the
     'FILES' table.

   * For additional information, and examples of creating and dropping
     NDB Cluster Disk Data objects, see mysql-cluster-disk-data.

24.9 The INFORMATION_SCHEMA GLOBAL_STATUS and SESSION_STATUS Tables
===================================================================

*Note*:

As of MySQL 5.7.6, the value of the 'show_compatibility_56' system
variable affects the information available from the tables described
here.  For details, see the description of that variable in
server-system-variables.

*Note*:

As of MySQL 5.7.6, information available from the tables described here
is also available from the Performance Schema.  The 'INFORMATION_SCHEMA'
tables are deprecated in preference to the Performance Schema tables and
will be removed in a future MySQL release.  For advice on migrating away
from the 'INFORMATION_SCHEMA' tables to the Performance Schema tables,
see performance-schema-variable-table-migration.

The 'GLOBAL_STATUS' and 'SESSION_STATUS'
tables provide information about server status variables.
Their contents correspond to the information produced by the 'SHOW GLOBAL STATUS'
and 'SHOW SESSION STATUS'
statements (see show-status).

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

VARIABLE_NAME                 Variable_name

VARIABLE_VALUE                Value

*Notes*:

   * The 'VARIABLE_VALUE' column for each of these tables is defined as
     'VARCHAR(1024)'.

24.10 The INFORMATION_SCHEMA GLOBAL_VARIABLES and SESSION_VARIABLES Tables
==========================================================================

*Note*:

As of MySQL 5.7.6, the value of the 'show_compatibility_56' system
variable affects the information available from the tables described
here.  For details, see the description of that variable in
server-system-variables.

*Note*:

As of MySQL 5.7.6, information available from the tables described here
is also available from the Performance Schema.  The 'INFORMATION_SCHEMA'
tables are deprecated in preference to the Performance Schema tables and
will be removed in a future MySQL release.  For advice on migrating away
from the 'INFORMATION_SCHEMA' tables to the Performance Schema tables,
see performance-schema-variable-table-migration.

The 'GLOBAL_VARIABLES' and
'SESSION_VARIABLES' tables provide information about
server status variables.  Their contents correspond to the information
produced by the 'SHOW GLOBAL VARIABLES' and
'SHOW SESSION VARIABLES' statements (see
show-variables).

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

VARIABLE_NAME                 Variable_name

VARIABLE_VALUE                Value

*Notes*:

   * The 'VARIABLE_VALUE' column for each of these tables is defined as
     'VARCHAR(1024)'.  For variables with very long values that are not
     completely displayed, use 'SELECT' as a workaround.
     For example:

          SELECT @@GLOBAL.innodb_data_file_path;

24.11 The INFORMATION_SCHEMA KEY_COLUMN_USAGE Table
===================================================

The 'KEY_COLUMN_USAGE' table describes
which key columns have constraints.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'CONSTRAINT_CATALOG'                                 'def'

'CONSTRAINT_SCHEMA'

'CONSTRAINT_NAME'

'TABLE_CATALOG'                                      'def'

'TABLE_SCHEMA'

'TABLE_NAME'

'COLUMN_NAME'

'ORDINAL_POSITION'

'POSITION_IN_UNIQUE_CONSTRAINT'

'REFERENCED_TABLE_SCHEMA'

'REFERENCED_TABLE_NAME'

'REFERENCED_COLUMN_NAME'

*Notes*:

   * If the constraint is a foreign key, then this is the column of the
     foreign key, not the column that the foreign key references.

   * The value of 'ORDINAL_POSITION' is the column's position within the
     constraint, not the column's position within the table.  Column
     positions are numbered beginning with 1.

   * The value of 'POSITION_IN_UNIQUE_CONSTRAINT' is 'NULL' for unique
     and primary-key constraints.  For foreign-key constraints, it is
     the ordinal position in key of the table that is being referenced.

     Suppose that there are two tables name 't1' and 't3' that have the
     following definitions:

          CREATE TABLE t1
          (
              s1 INT,
              s2 INT,
              s3 INT,
              PRIMARY KEY(s3)
          ) ENGINE=InnoDB;

          CREATE TABLE t3
          (
              s1 INT,
              s2 INT,
              s3 INT,
              KEY(s1),
              CONSTRAINT CO FOREIGN KEY (s2) REFERENCES t1(s3)
          ) ENGINE=InnoDB;

     For those two tables, the 'KEY_COLUMN_USAGE'
     table has two rows:

        * One row with 'CONSTRAINT_NAME' = ''PRIMARY'', 'TABLE_NAME' =
          ''t1'', 'COLUMN_NAME' = ''s3'', 'ORDINAL_POSITION' = '1',
          'POSITION_IN_UNIQUE_CONSTRAINT' = 'NULL'.

        * One row with 'CONSTRAINT_NAME' = ''CO'', 'TABLE_NAME' =
          ''t3'', 'COLUMN_NAME' = ''s2'', 'ORDINAL_POSITION' = '1',
          'POSITION_IN_UNIQUE_CONSTRAINT' = '1'.

24.12 The INFORMATION_SCHEMA ndb_transid_mysql_connection_map Table
===================================================================

The 'ndb_transid_mysql_connection_map' table provides a mapping between
'NDB' transactions, 'NDB' transaction coordinators, and MySQL Servers
attached to an NDB Cluster as API nodes.  This information is used when
populating the 'server_operations'
and
'server_transactions' tables
of the 'ndbinfo'. NDB Cluster information
database.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'mysql_connection_id'                                MySQL Server
                                                     connection ID

'node_id'                                            Transaction
                                                     coordinator node ID

'ndb_transid'                                        'NDB'.
                                                     transaction ID

The 'mysql_connection_id' is the same as the connection or session ID
shown in the output of 'SHOW PROCESSLIST'.

There are no 'SHOW' statements associated with this table.

This is a nonstandard table, specific to NDB Cluster.  It is implemented
as an 'INFORMATION_SCHEMA' plugin; you can verify that it is supported
by checking the output of 'SHOW PLUGINS'.  If
'ndb_transid_mysql_connection_map' support is enabled, the output from
this statement includes a plugin having this name, of type 'INFORMATION
SCHEMA', and having status 'ACTIVE', as shown here (using emphasized
text):

     mysql> SHOW PLUGINS;
     +----------------------------------+--------+--------------------+---------+---------+
     | Name                             | Status | Type               | Library | License |
     +----------------------------------+--------+--------------------+---------+---------+
     | binlog                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | mysql_native_password            | ACTIVE | AUTHENTICATION     | NULL    | GPL     |
     | CSV                              | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | MEMORY                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | MRG_MYISAM                       | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | MyISAM                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | PERFORMANCE_SCHEMA               | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | BLACKHOLE                        | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | ARCHIVE                          | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | ndbcluster                       | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | ndbinfo                          | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     _| ndb_transid_mysql_connection_map | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |_
     | InnoDB                           | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     | INNODB_TRX                       | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_LOCKS                     | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_LOCK_WAITS                | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMP                       | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMP_RESET                 | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMPMEM                    | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | INNODB_CMPMEM_RESET              | ACTIVE | INFORMATION SCHEMA | NULL    | GPL     |
     | partition                        | ACTIVE | STORAGE ENGINE     | NULL    | GPL     |
     +----------------------------------+--------+--------------------+---------+---------+
     22 rows in set (0.00 sec)

The plugin is enabled by default.  You can disable it (or force the
server not to run unless the plugin starts) by starting the server with
the '--ndb-transid-mysql-connection-map' option.  If the plugin is
disabled, the status is shown by 'SHOW PLUGINS' as
'DISABLED'.  The plugin cannot be enabled or disabled at runtime.

Although the names of this table and its columns are displayed using
lowercase, you can use uppercase or lowercase when referring to them in
SQL statements.

For this table to be created, the MySQL Server must be a binary supplied
with the NDB Cluster distribution, or one built from the NDB Cluster
sources with 'NDB' storage engine support enabled.
It is not available in the standard MySQL 5.7 Server.

24.13 The INFORMATION_SCHEMA OPTIMIZER_TRACE Table
==================================================

The 'OPTIMIZER_TRACE' table provides
information produced by the optimizer tracing capability.  To enable
tracking, use the 'optimizer_trace' system variable.  For details, see
MySQL Internals: Tracing the Optimizer
(http://dev.mysql.com/doc/internals/en/optimizer-tracing.html).

24.14 The INFORMATION_SCHEMA PARAMETERS Table
=============================================

The 'PARAMETERS' table provides information
about stored procedure and function parameters, and about return values
for stored functions.  Parameter information is similar to the contents
of the 'param_list' column in the 'mysql.proc' table.

'INFORMATION_SCHEMA' Name     'mysql.proc' Name      Remarks

'SPECIFIC_CATALOG'                                   'def'

'SPECIFIC_SCHEMA'             'db'                   routine database

'SPECIFIC_NAME'               'name'                 routine name

'ORDINAL_POSITION'                                   1, 2, 3, ...  for
                                                     parameters, 0 for
                                                     function 'RETURNS'
                                                     clause

'PARAMETER_MODE'                                     'IN', 'OUT', 'INOUT'
                                                     ('NULL' for
                                                     'RETURNS')

'PARAMETER_NAME'                                     parameter name
                                                     ('NULL' for
                                                     'RETURNS')

'DATA_TYPE'                                          same as for
                                                     'COLUMNS'
                                        table

'CHARACTER_MAXIMUM_LENGTH'                           same as for
                                                     'COLUMNS'
                                        table

'CHARACTER_OCTET_LENGTH'                             same as for
                                                     'COLUMNS'
                                        table

'NUMERIC_PRECISION'                                  same as for
                                                     'COLUMNS'
                                        table

'NUMERIC_SCALE'                                      same as for
                                                     'COLUMNS'
                                        table

'DATETIME_PRECISION'                                 same as for
                                                     'COLUMNS'
                                        table

'CHARACTER_SET_NAME'                                 same as for
                                                     'COLUMNS'
                                        table

'COLLATION_NAME'                                     same as for
                                                     'COLUMNS'
                                        table

'DTD_IDENTIFIER'                                     same as for
                                                     'COLUMNS'
                                        table

'ROUTINE_TYPE'                type                   same as for
                                                     'ROUTINES'.
                                                     table

*Notes*:

   * For successive parameters of a stored procedure or function, the
     'ORDINAL_POSITION' values are 1, 2, 3, and so forth.  For a stored
     function, there is also a row that describes the data type for the
     'RETURNS' clause.  The return value is not a true parameter, so the
     row that describes it has these unique characteristics:

        * The 'ORDINAL_POSITION' value is 0.

        * The 'PARAMETER_NAME' and 'PARAMETER_MODE' values are 'NULL'
          because the return value has no name and the mode does not
          apply.

24.15 The INFORMATION_SCHEMA PARTITIONS Table
=============================================

The 'PARTITIONS' table provides information
about table partitions.  See partitioning, for more information
about partitioning tables.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'TABLE_CATALOG'                                      MySQL extension

'TABLE_SCHEMA'                                       MySQL extension

'TABLE_NAME'                                         MySQL extension

'PARTITION_NAME'                                     MySQL extension

'SUBPARTITION_NAME'                                  MySQL extension

'PARTITION_ORDINAL_POSITION'                         MySQL extension

'SUBPARTITION_ORDINAL_POSITION'                      MySQL extension

'PARTITION_METHOD'                                   MySQL extension

'SUBPARTITION_METHOD'                                MySQL extension

'PARTITION_EXPRESSION'                               MySQL extension

'SUBPARTITION_EXPRESSION'                            MySQL extension

'PARTITION_DESCRIPTION'                              MySQL extension

'TABLE_ROWS'                                         MySQL extension

'AVG_ROW_LENGTH'                                     MySQL extension

'DATA_LENGTH'                                        MySQL extension

'MAX_DATA_LENGTH'                                    MySQL extension

'INDEX_LENGTH'                                       MySQL extension

'DATA_FREE'                                          MySQL extension

'CREATE_TIME'                                        MySQL extension

'UPDATE_TIME'                                        MySQL extension

'CHECK_TIME'                                         MySQL extension

'CHECKSUM'                                           MySQL extension

'PARTITION_COMMENT'                                  MySQL extension

'NODEGROUP'                                          MySQL extension

'TABLESPACE_NAME'                                    MySQL extension

*Notes*:

   * The 'PARTITIONS' table is a nonstandard
     table.

     Each record in this table corresponds to an individual partition or
     subpartition of a partitioned table.

   * 'TABLE_CATALOG': This column is always 'def'.

   * 'TABLE_SCHEMA': This column contains the name of the database to
     which the table belongs.

   * 'TABLE_NAME': This column contains the name of the table containing
     the partition.

   * 'PARTITION_NAME': The name of the partition.

   * 'SUBPARTITION_NAME': If the 'PARTITIONS'.
     table record represents a subpartition, then this column contains
     the name of subpartition; otherwise it is 'NULL'.

   * 'PARTITION_ORDINAL_POSITION': All partitions are indexed in the
     same order as they are defined, with '1' being the number assigned
     to the first partition.  The indexing can change as partitions are
     added, dropped, and reorganized; the number shown is this column
     reflects the current order, taking into account any indexing
     changes.

   * 'SUBPARTITION_ORDINAL_POSITION': Subpartitions within a given
     partition are also indexed and reindexed in the same manner as
     partitions are indexed within a table.

   * 'PARTITION_METHOD': One of the values 'RANGE', 'LIST', 'HASH',
     'LINEAR HASH', 'KEY', or 'LINEAR KEY'; that is, one of the
     available partitioning types as discussed in
     partitioning-types.

   * 'SUBPARTITION_METHOD': One of the values 'HASH', 'LINEAR HASH',
     'KEY', or 'LINEAR KEY'; that is, one of the available
     subpartitioning types as discussed in
     partitioning-subpartitions.

   * 'PARTITION_EXPRESSION': This is the expression for the partitioning
     function used in the 'CREATE TABLE' or
     'ALTER TABLE' statement that created the table's
     current partitioning scheme.

     For example, consider a partitioned table created in the 'test'
     database using this statement:

          CREATE TABLE tp (
              c1 INT,
              c2 INT,
              c3 VARCHAR(25)
          )
          PARTITION BY HASH(c1 + c2)
          PARTITIONS 4;

     The 'PARTITION_EXPRESSION' column in a PARTITIONS table record for
     a partition from this table displays 'c1 + c2', as shown here:

          mysql> SELECT DISTINCT PARTITION_EXPRESSION
               >     FROM INFORMATION_SCHEMA.PARTITIONS
               >     WHERE TABLE_NAME='tp' AND TABLE_SCHEMA='test';
          +----------------------+
          | PARTITION_EXPRESSION |
          +----------------------+
          | c1 + c2              |
          +----------------------+
          1 row in set (0.09 sec)

   * 'SUBPARTITION_EXPRESSION': This works in the same fashion for the
     subpartitioning expression that defines the subpartitioning for a
     table as 'PARTITION_EXPRESSION' does for the partitioning
     expression used to define a table's partitioning.

     If the table has no subpartitions, then this column is 'NULL'.

   * 'PARTITION_DESCRIPTION': This column is used for RANGE and LIST
     partitions.  For a 'RANGE' partition, it contains the value set in
     the partition's 'VALUES LESS THAN' clause, which can be either an
     integer or 'MAXVALUE'.  For a 'LIST' partition, this column
     contains the values defined in the partition's 'VALUES IN' clause,
     which is a comma-separated list of integer values.

     For partitions whose 'PARTITION_METHOD' is other than 'RANGE' or
     'LIST', this column is always 'NULL'.

   * 'TABLE_ROWS': The number of table rows in the partition.

     For partitioned 'InnoDB' tables, the
     row count given in the 'TABLE_ROWS' column is only an estimated
     value used in SQL optimization, and may not always be exact.

   * 'AVG_ROW_LENGTH': The average length of the rows stored in this
     partition or subpartition, in bytes.

     This is the same as 'DATA_LENGTH' divided by 'TABLE_ROWS'.

   * 'DATA_LENGTH': The total length of all rows stored in this
     partition or subpartition, in bytes--that is, the total number of
     bytes stored in the partition or subpartition.

   * 'MAX_DATA_LENGTH': The maximum number of bytes that can be stored
     in this partition or subpartition.

   * 'INDEX_LENGTH': The length of the index file for this partition or
     subpartition, in bytes.

   * 'DATA_FREE': The number of bytes allocated to the partition or
     subpartition but not used.

   * 'CREATE_TIME': The time of the partition's or subpartition's
     creation.

   * 'UPDATE_TIME': The time that the partition or subpartition was last
     modified.

   * 'CHECK_TIME': The last time that the table to which this partition
     or subpartition belongs was checked.

     For partitioned 'InnoDB' tables, this
     column is always 'NULL'.

   * 'CHECKSUM': The checksum value, if any; otherwise, this column is
     'NULL'.

   * 'PARTITION_COMMENT': This column contains the text of any comment
     made for the partition.

     In MySQL 5.7, the maximum length for a partition comment is defined
     as 1024 characters, and the display width of the
     'PARTITION_COMMENT' column is also 1024, characters to match this
     limit (Bug #11748924, Bug #37728).

     The default value for this column is an empty string.

   * 'NODEGROUP': This is the nodegroup to which the partition belongs.
     This is relevant only to NDB Cluster tables; otherwise the value of
     this column is always '0'.

   * 'TABLESPACE_NAME': This column contains the name of the tablespace
     to which the partition belongs.  The value of this column is always
     'DEFAULT'.

   * A nonpartitioned table has one record in
     'INFORMATION_SCHEMA.PARTITIONS'.; however, the
     values of the 'PARTITION_NAME', 'SUBPARTITION_NAME',
     'PARTITION_ORDINAL_POSITION', 'SUBPARTITION_ORDINAL_POSITION',
     'PARTITION_METHOD', 'SUBPARTITION_METHOD', 'PARTITION_EXPRESSION',
     'SUBPARTITION_EXPRESSION', and 'PARTITION_DESCRIPTION' columns are
     all 'NULL'.  (The 'PARTITION_COMMENT' column in this case is
     blank.)

24.16 The INFORMATION_SCHEMA PLUGINS Table
==========================================

The 'PLUGINS' table provides information about
server plugins.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'PLUGIN_NAME'                 'Name'                 MySQL extension

'PLUGIN_VERSION'                                     MySQL extension

'PLUGIN_STATUS'               'Status'               MySQL extension

'PLUGIN_TYPE'                 'Type'                 MySQL extension

'PLUGIN_TYPE_VERSION'                                MySQL extension

'PLUGIN_LIBRARY'              'Library'              MySQL extension

'PLUGIN_LIBRARY_VERSION'                             MySQL extension

'PLUGIN_AUTHOR'                                      MySQL extension

'PLUGIN_DESCRIPTION'                                 MySQL extension

'PLUGIN_LICENSE'              'License'              MySQL extension

'LOAD_OPTION'                                        MySQL extension

*Notes*:

   * The 'PLUGINS' table is a nonstandard table.

   * 'PLUGIN_NAME' is the name used to refer to the plugin in statements
     such as 'INSTALL PLUGIN' and
     'UNINSTALL PLUGIN'.

   * 'PLUGIN_VERSION' is the version from the plugin's general type
     descriptor.

   * 'PLUGIN_STATUS' indicates the plugin status, one of 'ACTIVE',
     'INACTIVE', 'DISABLED', or 'DELETED'.

   * 'PLUGIN_TYPE' indicates the type of plugin, such as 'STORAGE
     ENGINE', 'INFORMATION_SCHEMA', or 'AUTHENTICATION'.

   * 'PLUGIN_TYPE_VERSION' is the version from the plugin's
     type-specific descriptor.

   * 'PLUGIN_LIBRARY' is the name of the plugin shared library file.
     This is the name used to refer to the plugin file in statements
     such as 'INSTALL PLUGIN' and
     'UNINSTALL PLUGIN'.  This file is located in the
     directory named by the 'plugin_dir' system variable.  If the
     library name is 'NULL', the plugin is compiled in and cannot be
     uninstalled with 'UNINSTALL PLUGIN'.

   * 'PLUGIN_LIBRARY_VERSION' indicates the plugin API interface
     version.

   * 'PLUGIN_AUTHOR' names the plugin author.

   * 'PLUGIN_DESCRIPTION' provides a short description of the plugin.

   * 'PLUGIN_LICENSE' indicates how the plugin is licensed; for example,
     'GPL'.

   * 'LOAD_OPTION' indicates how the plugin was loaded.  The value is
     'OFF', 'ON', 'FORCE', or 'FORCE_PLUS_PERMANENT'.  See
     server-plugin-loading.

For plugins installed with 'INSTALL PLUGIN', the
'PLUGIN_NAME' and 'PLUGIN_LIBRARY' values are also registered in the
'mysql.plugin' table.

These statements are equivalent:

     SELECT
       PLUGIN_NAME, PLUGIN_STATUS, PLUGIN_TYPE,
       PLUGIN_LIBRARY, PLUGIN_LICENSE
     FROM INFORMATION_SCHEMA.PLUGINS;

     SHOW PLUGINS;

For information about plugin data structures that form the basis of the
information in the 'PLUGINS' table, see
plugin-api.

Plugin information is also available using the 'SHOW PLUGINS'
statement.  See show-plugins.

24.17 The INFORMATION_SCHEMA PROCESSLIST Table
==============================================

The 'PROCESSLIST' table provides information
about which threads are running.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'ID'                          'Id'                   MySQL extension

'USER'                        'User'                 MySQL extension

'HOST'                        'Host'                 MySQL extension

'DB'                          'db'                   MySQL extension

'COMMAND'                     'Command'              MySQL extension

'TIME'                        'Time'                 MySQL extension

'STATE'                       'State'                MySQL extension

'INFO'                        'Info'                 MySQL extension

For an extensive description of the table columns, see
show-processlist.

*Notes*:

   * The 'PROCESSLIST' table is a nonstandard
     table.

   * Like the output from the corresponding 'SHOW'.
     statement, the 'PROCESSLIST' table will
     only show information about your own threads, unless you have the
     'PROCESS' privilege, in which case you will see information about
     other threads, too.  As an anonymous user, you cannot see any rows
     at all.

   * If an SQL statement refers to
     'INFORMATION_SCHEMA.PROCESSLIST', MySQL
     populates the entire table once, when statement execution begins,
     so there is read consistency during the statement.  There is no
     read consistency for a multi-statement transaction, though.

   * Process information is also available from the
     'performance_schema.threads' table.  However,
     access to 'threads' does not require a mutex
     and has minimal impact on server performance.
     'INFORMATION_SCHEMA.PROCESSLIST' and
     'SHOW PROCESSLIST' have negative performance
     consequences because they require a mutex.  'threads'
     also shows information about background threads,
     which 'INFORMATION_SCHEMA.PROCESSLIST'.
     and 'SHOW PROCESSLIST' do not.  This means
     that 'threads' can be used to monitor
     activity the other thread information sources cannot.

The following statements are equivalent:

     SELECT * FROM INFORMATION_SCHEMA.PROCESSLIST

     SHOW FULL PROCESSLIST

24.18 The INFORMATION_SCHEMA PROFILING Table
============================================

The 'PROFILING' table provides statement
profiling information.  Its contents correspond to the information
produced by the 'SHOW PROFILES' and 'SHOW PROFILE'
statements (see show-profiles).  The
table is empty unless the 'profiling' session variable is set to 1.

*Note*:

This table is deprecated as of MySQL 5.7.2 and will be removed in a
future MySQL release.  Use the Performance Schema instead; see
performance-schema.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'QUERY_ID'                    'Query_ID'

'SEQ'                         ''

'STATE'                       'Status'

'DURATION'                    'Duration'

'CPU_USER'                    'CPU_user'

'CPU_SYSTEM'                  'CPU_system'

'CONTEXT_VOLUNTARY'           'Context_voluntary'

'CONTEXT_INVOLUNTARY'         'Context_involuntary'

'BLOCK_OPS_IN'                'Block_ops_in'

'BLOCK_OPS_OUT'               'Block_ops_out'

'MESSAGES_SENT'               'Messages_sent'

'MESSAGES_RECEIVED'           'Messages_received'

'PAGE_FAULTS_MAJOR'           'Page_faults_major'

'PAGE_FAULTS_MINOR'           'Page_faults_minor'

'SWAPS'                       'Swaps'

'SOURCE_FUNCTION'             'Source_function'

'SOURCE_FILE'                 'Source_file'

'SOURCE_LINE'                 'Source_line'

*Notes*:

   * 'QUERY_ID' is a numeric statement identifier.

   * 'SEQ' is a sequence number indicating the display order for rows
     with the same 'QUERY_ID' value.

   * 'STATE' is the profiling state to which the row measurements apply.

   * 'DURATION' indicates how long statement execution remained in the
     given state, in seconds.

   * 'CPU_USER' and 'CPU_SYSTEM' indicate user and system CPU use, in
     seconds.

   * 'CONTEXT_VOLUNTARY' and 'CONTEXT_INVOLUNTARY' indicate how many
     voluntary and involuntary context switches occurred.

   * 'BLOCK_OPS_IN' and 'BLOCK_OPS_OUT' indicate the number of block
     input and output operations.

   * 'MESSAGES_SENT' and 'MESSAGES_RECEIVED' indicate the number of
     communication messages sent and received.

   * 'PAGE_FAULTS_MAJOR' and 'PAGE_FAULTS_MINOR' indicate the number of
     major and minor page faults.

   * 'SWAPS' indicates how many swaps occurred.

   * 'SOURCE_FUNCTION', 'SOURCE_FILE', and 'SOURCE_LINE' provide
     information indicating where in the source code the profiled state
     executes.

24.19 The INFORMATION_SCHEMA REFERENTIAL_CONSTRAINTS Table
==========================================================

The 'REFERENTIAL_CONSTRAINTS'.
table provides information about foreign keys.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

CONSTRAINT_CATALOG                                   def

CONSTRAINT_SCHEMA

CONSTRAINT_NAME

UNIQUE_CONSTRAINT_CATALOG                            def

UNIQUE_CONSTRAINT_SCHEMA

UNIQUE_CONSTRAINT_NAME

MATCH_OPTION

UPDATE_RULE

DELETE_RULE

TABLE_NAME

REFERENCED_TABLE_NAME

*Notes*:

   * 'TABLE_NAME' has the same value as 'TABLE_NAME' in
     'INFORMATION_SCHEMA.TABLE_CONSTRAINTS'.

   * 'CONSTRAINT_SCHEMA' and 'CONSTRAINT_NAME' identify the foreign key.

   * 'UNIQUE_CONSTRAINT_SCHEMA', 'UNIQUE_CONSTRAINT_NAME', and
     'REFERENCED_TABLE_NAME' identify the referenced key.

   * The only valid value at this time for 'MATCH_OPTION' is 'NONE'.

   * The possible values for 'UPDATE_RULE' or 'DELETE_RULE' are
     'CASCADE', 'SET NULL', 'SET DEFAULT', 'RESTRICT', 'NO ACTION'.

24.20 The INFORMATION_SCHEMA ROUTINES Table
===========================================

The 'ROUTINES' table provides information about
stored routines (both procedures and functions).  The 'ROUTINES'
table does not include user-defined functions (UDFs).

The column named ''mysql.proc' Name' indicates the 'mysql.proc' table
column that corresponds to the 'INFORMATION_SCHEMA.ROUTINES'
table column, if any.

'INFORMATION_SCHEMA' Name     'mysql.proc' Name      Remarks

'SPECIFIC_NAME'               'specific_name'

'ROUTINE_CATALOG'                                    'def'

'ROUTINE_SCHEMA'              'db'

'ROUTINE_NAME'                'name'

'ROUTINE_TYPE'                'type'                 '{PROCEDURE|FUNCTION}'

'DATA_TYPE'                                          same as for
                                                     'COLUMNS'
                                        table

'CHARACTER_MAXIMUM_LENGTH'                           same as for
                                                     'COLUMNS'
                                        table

'CHARACTER_OCTET_LENGTH'                             same as for
                                                     'COLUMNS'
                                        table

'NUMERIC_PRECISION'                                  same as for
                                                     'COLUMNS'
                                        table

'NUMERIC_SCALE'                                      same as for
                                                     'COLUMNS'
                                        table

'DATETIME_PRECISION'                                 same as for
                                                     'COLUMNS'
                                        table

'CHARACTER_SET_NAME'                                 same as for
                                                     'COLUMNS'
                                        table

'COLLATION_NAME'                                     same as for
                                                     'COLUMNS'
                                        table

'DTD_IDENTIFIER'                                     data type descriptor

'ROUTINE_BODY'                                       'SQL'

'ROUTINE_DEFINITION'          'body_utf8'

'EXTERNAL_NAME'                                      'NULL'

'EXTERNAL_LANGUAGE'           'language'             'NULL'

'PARAMETER_STYLE'                                    'SQL'

'IS_DETERMINISTIC'            'is_deterministic'

'SQL_DATA_ACCESS'             'sql_data_access'

'SQL_PATH'                                           'NULL'

'SECURITY_TYPE'               'security_type'

'CREATED'                     'created'

'LAST_ALTERED'                'modified'

'SQL_MODE'                    'sql_mode'             MySQL extension

'ROUTINE_COMMENT'             'comment'              MySQL extension

'DEFINER'                     'definer'              MySQL extension

'CHARACTER_SET_CLIENT'                               MySQL extension

'COLLATION_CONNECTION'                               MySQL extension

'DATABASE_COLLATION'                                 MySQL extension

*Notes*:

   * MySQL calculates 'EXTERNAL_LANGUAGE' thus:

        * If 'mysql.proc.language='SQL'', 'EXTERNAL_LANGUAGE' is 'NULL'

        * Otherwise, 'EXTERNAL_LANGUAGE' is what is in
          'mysql.proc.language'.  However, we do not have external
          languages yet, so it is always 'NULL'.

   * 'CREATED': The date and time when the routine was created.  This is
     a 'TIMESTAMP' value.

   * 'LAST_ALTERED': The date and time when the routine was last
     modified.  This is a 'TIMESTAMP' value.  If the
     routine has not been modified since its creation, this column holds
     the same value as the 'CREATED' column.

   * 'SQL_MODE': The SQL mode in effect when the routine was created or
     altered, and under which the routine executes.  For the permitted
     values, see sql-mode.

   * 'CHARACTER_SET_CLIENT': The session value of the
     'character_set_client' system variable when the routine was
     created.

   * 'COLLATION_CONNECTION': The session value of the
     'collation_connection' system variable when the routine was
     created.

   * 'DATABASE_COLLATION': The collation of the database with which the
     routine is associated.

   * The 'DATA_TYPE', 'CHARACTER_MAXIMUM_LENGTH',
     'CHARACTER_OCTET_LENGTH', 'NUMERIC_PRECISION', 'NUMERIC_SCALE',
     'DATETIME_PRECISION', 'CHARACTER_SET_NAME', and 'COLLATION_NAME'
     columns provide information about the data type for the 'RETURNS'
     clause of stored functions.  If a stored routine is a stored
     procedure, these columns all are 'NULL'.

   * Information about stored function 'RETURNS' data types is also
     available in the 'PARAMETERS' table.  The
     return value data type row for a function can be identified as the
     row that has an 'ORDINAL_POSITION' value of 0.

24.21 The INFORMATION_SCHEMA SCHEMATA Table
===========================================

A schema is a database, so the 'SCHEMATA' table
provides information about databases.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'CATALOG_NAME'                                       'def'

'SCHEMA_NAME'                 Database

'DEFAULT_CHARACTER_SET_NAME'

'DEFAULT_COLLATION_NAME'

'SQL_PATH'                                           'NULL'

The following statements are equivalent:

     SELECT SCHEMA_NAME AS `Database`
       FROM INFORMATION_SCHEMA.SCHEMATA
       [WHERE SCHEMA_NAME LIKE 'WILD']

     SHOW DATABASES
       [LIKE 'WILD']

24.22 The INFORMATION_SCHEMA SCHEMA_PRIVILEGES Table
====================================================

The 'SCHEMA_PRIVILEGES' table provides
information about schema (database) privileges.  This information comes
from the 'mysql.db' grant table.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'GRANTEE'                                            ''USER_NAME'@'HOST_NAME''
                                                     value, MySQL
                                                     extension

'TABLE_CATALOG'                                      'def', MySQL
                                                     extension

'TABLE_SCHEMA'                                       MySQL extension

'PRIVILEGE_TYPE'                                     MySQL extension

'IS_GRANTABLE'                                       MySQL extension

*Notes*:

   * This is a nonstandard table.  It takes its values from the
     'mysql.db' table.

24.23 The INFORMATION_SCHEMA STATISTICS Table
=============================================

The 'STATISTICS' table provides information
about table indexes.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'TABLE_CATALOG'                                      'def'

'TABLE_SCHEMA'                                       = Database

'TABLE_NAME'                  'Table'

'NON_UNIQUE'                  'Non_unique'

'INDEX_SCHEMA'                                       = Database

'INDEX_NAME'                  'Key_name'

'SEQ_IN_INDEX'                'Seq_in_index'

'COLUMN_NAME'                 'Column_name'

'COLLATION'                   'Collation'

'CARDINALITY'                 'Cardinality'

'SUB_PART'                    'Sub_part'             MySQL extension

'PACKED'                      'Packed'               MySQL extension

'NULLABLE'                    'Null'                 MySQL extension

'INDEX_TYPE'                  'Index_type'           MySQL extension

'COMMENT'                     'Comment'              MySQL extension

'INDEX_COMMENT'               'Index_comment'        MySQL extension

*Notes*:

   * There is no standard table for indexes.  The preceding list is
     similar to what SQL Server 2000 returns for 'sp_statistics', except
     that we replaced the name 'QUALIFIER' with 'CATALOG' and we
     replaced the name 'OWNER' with 'SCHEMA'.

     Clearly, the preceding table and the output from 'SHOW INDEX'
     are derived from the same parent.  So the
     correlation is already close.

The following statements are equivalent:

     SELECT * FROM INFORMATION_SCHEMA.STATISTICS
       WHERE table_name = 'TBL_NAME'
       AND table_schema = 'DB_NAME'

     SHOW INDEX
       FROM TBL_NAME
       FROM DB_NAME

24.24 The INFORMATION_SCHEMA TABLES Table
=========================================

The 'TABLES' table provides information about
tables in databases.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'TABLE_CATALOG'                                      'def'

'TABLE_SCHEMA'                'Table_'...

'TABLE_NAME'                  'Table_'...

'TABLE_TYPE'

'ENGINE'                      'Engine'               MySQL extension

'VERSION'                     'Version'              The version number
                                                     of the table's
                                                     '.frm' file, MySQL
                                                     extension

'ROW_FORMAT'                  'Row_format'           MySQL extension

'TABLE_ROWS'                  'Rows'                 MySQL extension

'AVG_ROW_LENGTH'              'Avg_row_length'       MySQL extension

'DATA_LENGTH'                 'Data_length'          MySQL extension

'MAX_DATA_LENGTH'             'Max_data_length'      MySQL extension

'INDEX_LENGTH'                'Index_length'         MySQL extension

'DATA_FREE'                   'Data_free'            MySQL extension

'AUTO_INCREMENT'              'Auto_increment'       MySQL extension

'CREATE_TIME'                 'Create_time'          MySQL extension

'UPDATE_TIME'                 'Update_time'          MySQL extension

'CHECK_TIME'                  'Check_time'           MySQL extension

'TABLE_COLLATION'             'Collation'            MySQL extension

'CHECKSUM'                    'Checksum'             MySQL extension

'CREATE_OPTIONS'              'Create_options'       MySQL extension

'TABLE_COMMENT'               'Comment'              MySQL extension

*Notes*:

   * Refer to 'SHOW TABLE STATUS' for field
     descriptions.

   * 'TABLE_SCHEMA' and 'TABLE_NAME' are a single field in a
     'SHOW' display, for example 'Table_in_db1'.

   * 'TABLE_TYPE' should be 'BASE TABLE' or 'VIEW'.  The 'TABLES'
     table does not list 'TEMPORARY' tables.

   * For partitioned tables, the 'ENGINE' column shows the name of the
     storage engine used by all partitions.  (Previously, this column
     showed 'PARTITION' for such tables.)

   * The 'TABLE_ROWS' column is 'NULL' if the table is in the
     'INFORMATION_SCHEMA' database.

     For 'InnoDB' tables, the row count is
     only a rough estimate used in SQL optimization.  (This is also true
     if the 'InnoDB' table is
     partitioned.)

   * The 'DATA_FREE' column shows the free space in bytes for 'InnoDB'
     tables.

   * 'UPDATE_TIME' displays a timestamp value for the last
     'UPDATE', 'INSERT', or 'DELETE'
     performed on 'InnoDB' tables that are not partitioned.  For
     MVCC, the timestamp value reflects the 'COMMIT'.
     time, which is considered the last update time.  Timestamps are not
     persisted when the server is restarted or when the table is evicted
     from the 'InnoDB' data dictionary cache.

     The 'UPDATE_TIME' column also shows this information for
     partitioned 'InnoDB' tables.

   * For partitioned 'InnoDB' tables, the
     'CHECK_TIME' column is always 'NULL'.

   * We have nothing for the table's default character set.
     'TABLE_COLLATION' is close, because collation names begin with a
     character set name.

   * The 'CREATE_OPTIONS' column shows 'partitioned' if the table is
     partitioned.

The following statements are equivalent:

     SELECT table_name FROM INFORMATION_SCHEMA.TABLES
       WHERE table_schema = 'DB_NAME'
       [AND table_name LIKE 'WILD']

     SHOW TABLES
       FROM DB_NAME
       [LIKE 'WILD']

24.25 The INFORMATION_SCHEMA TABLESPACES Table
==============================================

The 'TABLESPACES' table provides information
about active tablespaces.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'TABLESPACE_NAME'                                    MySQL extension

'ENGINE'                                             MySQL extension

'TABLESPACE_TYPE'                                    MySQL extension

'LOGFILE_GROUP_NAME'                                 MySQL extension

'EXTENT_SIZE'                                        MySQL extension

'AUTOEXTEND_SIZE'                                    MySQL extension

'MAXIMUM_SIZE'                                       MySQL extension

'NODEGROUP_ID'                                       MySQL extension

'TABLESPACE_COMMENT'                                 MySQL extension

*Notes*:

The 'INFORMATION_SCHEMA.TABLESPACES' table does not provide information
about 'InnoDB' tablespaces.  For 'InnoDB' tablespace metadata, see
'INNODB_SYS_TABLESPACES' and
'INNODB_SYS_DATAFILES'.  As of MySQL 5.7.8,
the 'INFORMATION_SCHEMA.FILES' table also provides
metadata for 'InnoDB' tablespaces.

24.26 The INFORMATION_SCHEMA TABLE_CONSTRAINTS Table
====================================================

The 'TABLE_CONSTRAINTS' table describes
which tables have constraints.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'CONSTRAINT_CATALOG'                                 'def'

'CONSTRAINT_SCHEMA'

'CONSTRAINT_NAME'

'TABLE_SCHEMA'

'TABLE_NAME'

'CONSTRAINT_TYPE'

*Notes*:

   * The 'CONSTRAINT_TYPE' value can be 'UNIQUE', 'PRIMARY KEY', or
     'FOREIGN KEY'.

   * The 'UNIQUE' and 'PRIMARY KEY' information is about the same as
     what you get from the 'Key_name' field in the output from
     'SHOW INDEX' when the 'Non_unique' field is '0'.

   * The 'CONSTRAINT_TYPE' column can contain one of these values:
     'UNIQUE', 'PRIMARY KEY', 'FOREIGN KEY', 'CHECK'.  This is a
     'CHAR'. (not 'ENUM') column.  The 'CHECK' value
     is not available until we support 'CHECK'.

24.27 The INFORMATION_SCHEMA TABLE_PRIVILEGES Table
===================================================

The 'TABLE_PRIVILEGES' table provides
information about table privileges.  This information comes from the
'mysql.tables_priv' grant table.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'GRANTEE'                                            ''USER_NAME'@'HOST_NAME''
                                                     value

'TABLE_CATALOG'                                      'def'

'TABLE_SCHEMA'

'TABLE_NAME'

'PRIVILEGE_TYPE'

'IS_GRANTABLE'

*Notes*:

   * 'PRIVILEGE_TYPE' can contain one (and only one) of these values:
     'SELECT', 'INSERT', 'UPDATE', 'REFERENCES', 'ALTER', 'INDEX',
     'DROP', 'CREATE VIEW'.

The following statements are _not_ equivalent:

     SELECT ... FROM INFORMATION_SCHEMA.TABLE_PRIVILEGES

     SHOW GRANTS ...

24.28 The INFORMATION_SCHEMA TRIGGERS Table
===========================================

The 'TRIGGERS' table provides information about
triggers.  To see information about a table's triggers, you must have
the 'TRIGGER' privilege for the table.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'TRIGGER_CATALOG'                                    'def'

'TRIGGER_SCHEMA'

'TRIGGER_NAME'                'Trigger'

'EVENT_MANIPULATION'          'Event'

'EVENT_OBJECT_CATALOG'                               'def'

'EVENT_OBJECT_SCHEMA'

'EVENT_OBJECT_TABLE'          'Table'

'ACTION_ORDER'

'ACTION_CONDITION'                                   'NULL'

'ACTION_STATEMENT'            'Statement'

'ACTION_ORIENTATION'                                 'ROW'

'ACTION_TIMING'               'Timing'

'ACTION_REFERENCE_OLD_TABLE'                         'NULL'

'ACTION_REFERENCE_NEW_TABLE'                         'NULL'

'ACTION_REFERENCE_OLD_ROW'                           'OLD'

'ACTION_REFERENCE_NEW_ROW'                           'NEW'

'CREATED'                     'Created'

'SQL_MODE'                    'sql_mode'             MySQL extension

'DEFINER'                     'Definer'              MySQL extension

'CHARACTER_SET_CLIENT'        'character_set_client' MySQL extension

'COLLATION_CONNECTION'        'collation_connection' MySQL extension

'DATABASE_COLLATION'          'Database Collation'   MySQL extension

*Notes*:

   * The names in the ''SHOW'. Name' column refer to the
     'SHOW TRIGGERS' statement, not 'SHOW CREATE TRIGGER'.
     See show-triggers.

   * 'TRIGGER_SCHEMA' and 'TRIGGER_NAME': The name of the database in
     which the trigger occurs and the trigger name, respectively.

   * 'EVENT_MANIPULATION': The trigger event.  This is the type of
     operation on the associated table for which the trigger activates.
     The value is ''INSERT'' (a row was inserted), ''DELETE'' (a row was
     deleted), or ''UPDATE'' (a row was modified).

   * 'EVENT_OBJECT_SCHEMA' and 'EVENT_OBJECT_TABLE': As noted in
     triggers, every trigger is associated with exactly one table.
     These columns indicate the database in which this table occurs, and
     the table name, respectively.

   * 'ACTION_ORDER': The ordinal position of the trigger's action within
     the list of triggers on the same table with the same
     'EVENT_MANIPULATION' and 'ACTION_TIMING' values.  Before MySQL
     5.7.2, this value is always '0' because it is not possible for a
     table to have more than one trigger with the same
     'EVENT_MANIPULATION' and 'ACTION_TIMING' values.

   * 'ACTION_STATEMENT': The trigger body; that is, the statement
     executed when the trigger activates.  This text uses UTF-8
     encoding.

   * 'ACTION_ORIENTATION': Always contains the value ''ROW''.

   * 'ACTION_TIMING': Whether the trigger activates before or after the
     triggering event.  The value is ''BEFORE'' or ''AFTER''.

   * 'ACTION_REFERENCE_OLD_ROW' and 'ACTION_REFERENCE_NEW_ROW': The old
     and new column identifiers, respectively.  This means that
     'ACTION_REFERENCE_OLD_ROW' always contains the value ''OLD'' and
     'ACTION_REFERENCE_NEW_ROW' always contains the value ''NEW''.

   * 'CREATED': The date and time when the trigger was created.  This is
     a 'TIMESTAMP(2)' value (with a fractional part in hundredths of
     seconds) for triggers created in MySQL 5.7.2 or later, 'NULL' for
     triggers created prior to 5.7.2.

   * 'SQL_MODE': The SQL mode in effect when the trigger was created,
     and under which the trigger executes.  For the permitted values,
     see sql-mode.

   * 'DEFINER': The account of the user who created the trigger, in
     ''USER_NAME'@'HOST_NAME'' format.

   * 'CHARACTER_SET_CLIENT': The session value of the
     'character_set_client' system variable when the trigger was
     created.

   * 'COLLATION_CONNECTION': The session value of the
     'collation_connection' system variable when the trigger was
     created.

   * 'DATABASE_COLLATION': The collation of the database with which the
     trigger is associated.

   * The following columns currently always contain 'NULL':
     'ACTION_CONDITION', 'ACTION_REFERENCE_OLD_TABLE', and
     'ACTION_REFERENCE_NEW_TABLE'.

Example, using the 'ins_sum' trigger defined in triggers:

     mysql> SELECT * FROM INFORMATION_SCHEMA.TRIGGERS
            WHERE TRIGGER_SCHEMA='test' AND TRIGGER_NAME='ins_sum'\G
     *************************** 1. row ***************************
                TRIGGER_CATALOG: def
                 TRIGGER_SCHEMA: test
                   TRIGGER_NAME: ins_sum
             EVENT_MANIPULATION: INSERT
           EVENT_OBJECT_CATALOG: def
            EVENT_OBJECT_SCHEMA: test
             EVENT_OBJECT_TABLE: account
                   ACTION_ORDER: 1
               ACTION_CONDITION: NULL
               ACTION_STATEMENT: SET @sum = @sum + NEW.amount
             ACTION_ORIENTATION: ROW
                  ACTION_TIMING: BEFORE
     ACTION_REFERENCE_OLD_TABLE: NULL
     ACTION_REFERENCE_NEW_TABLE: NULL
       ACTION_REFERENCE_OLD_ROW: OLD
       ACTION_REFERENCE_NEW_ROW: NEW
                        CREATED: 2013-07-05 07:41:21.26
                       SQL_MODE: NO_ENGINE_SUBSTITUTION
                        DEFINER: me@localhost
           CHARACTER_SET_CLIENT: utf8
           COLLATION_CONNECTION: utf8_general_ci
             DATABASE_COLLATION: latin1_swedish_ci

24.29 The INFORMATION_SCHEMA USER_PRIVILEGES Table
==================================================

The 'USER_PRIVILEGES' table provides
information about global privileges.  This information comes from the
'mysql.user' grant table.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'GRANTEE'                                            ''USER_NAME'@'HOST_NAME''
                                                     value, MySQL
                                                     extension

'TABLE_CATALOG'                                      'def', MySQL
                                                     extension

'PRIVILEGE_TYPE'                                     MySQL extension

'IS_GRANTABLE'                                       MySQL extension

*Notes*:

   * This is a nonstandard table.  It takes its values from the
     'mysql.user' table.

24.30 The INFORMATION_SCHEMA VIEWS Table
========================================

The 'VIEWS' table provides information about views
in databases.  You must have the 'SHOW VIEW' privilege to access this
table.

'INFORMATION_SCHEMA' Name     'SHOW'.    Remarks
                              Name

'TABLE_CATALOG'                                      'def'

'TABLE_SCHEMA'

'TABLE_NAME'

'VIEW_DEFINITION'

'CHECK_OPTION'

'IS_UPDATABLE'

'DEFINER'

'SECURITY_TYPE'

'CHARACTER_SET_CLIENT'                               MySQL extension

'COLLATION_CONNECTION'                               MySQL extension

*Notes*:

   * The 'VIEW_DEFINITION' column has most of what you see in the
     'Create Table' field that 'SHOW CREATE VIEW'
     produces.  Skip the words before 'SELECT'
     and skip the words 'WITH CHECK OPTION'.  Suppose that the
     original statement was:

          CREATE VIEW v AS
            SELECT s2,s1 FROM t
            WHERE s1 > 5
            ORDER BY s1
            WITH CHECK OPTION;

     Then the view definition looks like this:

          SELECT s2,s1 FROM t WHERE s1 > 5 ORDER BY s1

   * The 'CHECK_OPTION' column has a value of 'NONE', 'CASCADE', or
     'LOCAL'.

   * MySQL sets a flag, called the view updatability flag, at
     'CREATE VIEW' time.  The flag is set to 'YES' (true)
     if 'UPDATE' and 'DELETE'. (and similar
     operations) are legal for the view.  Otherwise, the flag is set to
     'NO' (false).  The 'IS_UPDATABLE' column in the 'VIEWS'
     table displays the status of this flag.

     If a view is not updatable, statements such 'UPDATE',
     'DELETE', and 'INSERT' are illegal and
     will be rejected.  (Note that even if a view is updatable, it might
     not be possible to insert into it; for details, refer to
     view-updatability.)

     The 'IS_UPDATABLE' flag may be unreliable if a view depends on one
     or more other views, and one of these underlying views is updated.
     Regardless of the 'IS_UPDATABLE' value, the server keeps track of
     the updatability of a view and correctly rejects data change
     operations to views that are not updatable.  If the 'IS_UPDATABLE'
     value for a view has become inaccurate to due to changes to
     underlying views, the value can be updated by deleting and
     recreating the view.

   * 'DEFINER': The account of the user who created the view, in
     ''USER_NAME'@'HOST_NAME'' format.  'SECURITY_TYPE' has a value of
     'DEFINER' or 'INVOKER'.

   * 'CHARACTER_SET_CLIENT': The session value of the
     'character_set_client' system variable when the view was created.

   * 'COLLATION_CONNECTION': The session value of the
     'collation_connection' system variable when the view was created.

MySQL lets you use different 'sql_mode' settings to tell the server the
type of SQL syntax to support.  For example, you might use the 'ANSI'
SQL mode to ensure MySQL correctly interprets the standard SQL
concatenation operator, the double bar ('||'), in your queries.  If you
then create a view that concatenates items, you might worry that
changing the 'sql_mode' setting to a value different from 'ANSI' could
cause the view to become invalid.  But this is not the case.  No matter
how you write out a view definition, MySQL always stores it the same
way, in a canonical form.  Here is an example that shows how the server
changes a double bar concatenation operator to a 'CONCAT()' function:

     mysql> SET sql_mode = 'ANSI';
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE VIEW test.v AS SELECT 'a' || 'b' as col1;
     Query OK, 0 rows affected (0.00 sec)

     mysql> SELECT VIEW_DEFINITION FROM INFORMATION_SCHEMA.VIEWS
            WHERE TABLE_SCHEMA = 'test' AND TABLE_NAME = 'v';
     +----------------------------------+
     | VIEW_DEFINITION                  |
     +----------------------------------+
     | select concat('a','b') AS `col1` |
     +----------------------------------+
     1 row in set (0.00 sec)

The advantage of storing a view definition in canonical form is that
changes made later to the value of 'sql_mode' will not affect the
results from the view.  However an additional consequence is that
comments prior to 'SELECT' are stripped from the
definition by the server.

24.31 InnoDB INFORMATION_SCHEMA Tables
======================================

This section provides table definitions for 'InnoDB'
'INFORMATION_SCHEMA' tables.  For related information and examples, see
innodb-information-schema.

'InnoDB' 'INFORMATION_SCHEMA' tables can be used to monitor ongoing
'InnoDB' activity, to detect inefficiencies before they turn into
issues, or to troubleshoot performance and capacity issues.  As your
database becomes bigger and busier, running up against the limits of
your hardware capacity, you monitor and tune these aspects to keep the
database running smoothly.

24.31.1 The INFORMATION_SCHEMA INNODB_BUFFER_PAGE Table
-------------------------------------------------------

The 'INNODB_BUFFER_PAGE' table holds information about each page in the
'InnoDB' buffer pool.

For related usage information and examples, see
innodb-information-schema-buffer-pool-tables.

*Warning*:

Querying the 'INNODB_BUFFER_PAGE' table can introduce significant
performance overhead.  Do not query this table on a production system
unless you are aware of the performance impact that your query may have,
and have determined it to be acceptable.  To avoid impacting
performance, reproduce the issue you want to investigate on a test
instance and query the 'INNODB_BUFFER_PAGE' table on the test instance.

*INNODB_BUFFER_PAGE Columns*

Column name            Description

'POOL_ID'              Buffer Pool ID. An identifier to distinguish between
                       multiple buffer pool instances.

'BLOCK_ID'             Buffer Pool Block ID.

'SPACE'                Tablespace ID. Uses the same value as in
                       'INNODB_SYS_TABLES.SPACE'.

'PAGE_NUMBER'          Page number.

'PAGE_TYPE'            Page type.  Permitted values are: 'ALLOCATED' (Freshly
                       allocated page), 'INDEX' (B-tree node), 'UNDO_LOG' (Undo
                       log page), 'INODE' (Index node), 'IBUF_FREE_LIST'
                       (Insert buffer free list), 'IBUF_BITMAP' (Insert buffer
                       bitmap), 'SYSTEM' (System page), 'TRX_SYSTEM'
                       (Transaction system data), 'FILE_SPACE_HEADER' (File
                       space header), 'EXTENT_DESCRIPTOR' (Extent descriptor
                       page), 'BLOB' (Uncompressed BLOB page),
                       'COMPRESSED_BLOB' (First compressed BLOB page),
                       'COMPRESSED_BLOB2' (Subsequent comp BLOB page),
                       'IBUF_INDEX' (Insert buffer index), 'RTREE_INDEX'
                       (R-tree index), 'UNKNOWN' (unknown).

'FLUSH_TYPE'           Flush type.

'FIX_COUNT'            Number of threads using this block within the buffer
                       pool.  When zero, the block is eligible to be evicted.

'IS_HASHED'            Whether hash index has been built on this page.

'NEWEST_MODIFICATION'  Log Sequence Number of the youngest modification.

'OLDEST_MODIFICATION'  Log Sequence Number of the oldest modification.

'ACCESS_TIME'          An abstract number used to judge the first access time
                       of the page.

'TABLE_NAME'           Name of the table the page belongs to.  This column is
                       only applicable to pages of type 'INDEX'.

'INDEX_NAME'           Name of the index the page belongs to.  It can be the
                       name of a clustered index or a secondary index.  This
                       column is only applicable to pages of type 'INDEX'.

'NUMBER_RECORDS'       Number of records within the page.

'DATA_SIZE'            Sum of the sizes of the records.  This column is only
                       applicable to pages of type 'INDEX'.

'COMPRESSED_SIZE'      Compressed page size.  Null for pages that are not
                       compressed.

'PAGE_STATE'           Page state.  Possible values include: 'NULL' (clean
                       compressed pages, compressed pages in the flush list,
                       pages used as buffer pool watch sentinels), 'NOT_USED'
                       (in the free list), 'READY_FOR_USE' (a free page),
                       'FILE_PAGE' (a buffered file page), 'MEMORY' (contains a
                       main memory object), 'REMOVE_HASH' (hash index should be
                       removed before placing in the free list).

'IO_FIX'               Specifies whether any I/O is pending for this page:
                       'IO_NONE' = no pending I/O, 'IO_READ' = read pending,
                       'IO_WRITE' = write pending.

'IS_OLD'               Specifies whether or not the block is in the sublist of
                       old blocks in the LRU list.

'FREE_PAGE_CLOCK'      The value of the 'freed_page_clock' counter when the
                       block was the last placed at the head of the LRU list.
                       The 'freed_page_clock' counter tracks the number of
                       blocks removed from the end of the LRU list.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE LIMIT 1\G
     *************************** 1. row ***************************
                 POOL_ID: 0
                BLOCK_ID: 0
                   SPACE: 97
             PAGE_NUMBER: 2473
               PAGE_TYPE: INDEX
              FLUSH_TYPE: 1
               FIX_COUNT: 0
               IS_HASHED: YES
     NEWEST_MODIFICATION: 733855581
     OLDEST_MODIFICATION: 0
             ACCESS_TIME: 3378385672
              TABLE_NAME: `employees`.`salaries`
              INDEX_NAME: PRIMARY
          NUMBER_RECORDS: 468
               DATA_SIZE: 14976
         COMPRESSED_SIZE: 0
              PAGE_STATE: FILE_PAGE
                  IO_FIX: IO_NONE
                  IS_OLD: YES
         FREE_PAGE_CLOCK: 66

*Notes*:

   * This table is primarily useful for expert-level performance
     monitoring, or when developing performance-related extensions for
     MySQL.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * When tables, table rows, partitions, or indexes are deleted,
     associated pages remain in the buffer pool until space is required
     for other data.  The 'INNODB_BUFFER_PAGE' table reports information
     about these pages until they are evicted from the buffer pool.  For
     more information about how the 'InnoDB' manages buffer pool data,
     see innodb-buffer-pool.

24.31.2 The INFORMATION_SCHEMA INNODB_BUFFER_PAGE_LRU Table
-----------------------------------------------------------

The 'INNODB_BUFFER_PAGE_LRU' table holds information about the pages in
the 'InnoDB' buffer pool, in particular how they are ordered in the LRU
list that determines which pages to evict from the buffer pool when it
becomes full.

The 'INNODB_BUFFER_PAGE_LRU' table
has the same columns as the 'INNODB_BUFFER_PAGE'
table, except that the
'INNODB_BUFFER_PAGE_LRU' table has an
'LRU_POSITION' column instead of a 'BLOCK_ID' column.

For related usage information and examples, see
innodb-information-schema-buffer-pool-tables.

*Warning*:

Querying the 'INNODB_BUFFER_PAGE_LRU' table can introduce significant
performance overhead.  Do not query this table on a production system
unless you are aware of the performance impact that your query may have,
and have determined it to be acceptable.  To avoid impacting
performance, reproduce the issue you want to investigate on a test
instance and query the 'INNODB_BUFFER_PAGE_LRU' table on the test
instance.

*INNODB_BUFFER_PAGE_LRU Columns*

Column name            Description

'POOL_ID'              Buffer Pool ID. An identifier to distinguish between
                       multiple buffer pool instances.

'LRU_POSITION'         The position of the page in the LRU list.

'SPACE'                Tablespace ID. Uses the same value as in
                       'INNODB_SYS_TABLES.SPACE'.

'PAGE_NUMBER'          Page number.

'PAGE_TYPE'            Page type.  Permitted values are: 'ALLOCATED' (Freshly
                       allocated page), 'INDEX' (B-tree node), 'UNDO_LOG' (Undo
                       log page), 'INODE' (Index node), 'IBUF_FREE_LIST'
                       (Insert buffer free list), 'IBUF_BITMAP' (Insert buffer
                       bitmap), 'SYSTEM' (System page), 'TRX_SYSTEM'
                       (Transaction system data), 'FILE_SPACE_HEADER' (File
                       space header), 'EXTENT_DESCRIPTOR' (Extent descriptor
                       page), 'BLOB' (Uncompressed BLOB page),
                       'COMPRESSED_BLOB' (First compressed BLOB page),
                       'COMPRESSED_BLOB2' (Subsequent comp BLOB page),
                       'IBUF_INDEX' (Insert buffer index), 'RTREE_INDEX'
                       (R-tree index), 'UNKNOWN' (unknown).

'FLUSH_TYPE'           Flush type.

'FIX_COUNT'            Number of threads using this block within the buffer
                       pool.  When zero, the block is eligible to be evicted.

'IS_HASHED'            Whether hash index has been built on this page.

'NEWEST_MODIFICATION'  Log Sequence Number of the youngest modification.

'OLDEST_MODIFICATION'  Log Sequence Number of the oldest modification.

'ACCESS_TIME'          An abstract number used to judge the first access time
                       of the page.

'TABLE_NAME'           Name of the table the page belongs to.  This column is
                       only applicable to pages of type 'INDEX'.

'INDEX_NAME'           Name of the index the page belongs to.  It can be the
                       name of a clustered index or a secondary index.  This
                       column is only applicable to pages of type 'INDEX'.

'NUMBER_RECORDS'       Number of records within the page.

'DATA_SIZE'            Sum of the sizes of the records.  This column is only
                       applicable to pages of type 'INDEX'.

'COMPRESSED_SIZE'      Compressed page size.  Null for pages that are not
                       compressed.

'PAGE_STATE'           Page state.  Possible values include: 'NULL' (clean
                       compressed pages, compressed pages in the flush list,
                       pages used as buffer pool watch sentinels), 'NOT_USED'
                       (in the free list), 'READY_FOR_USE' (a free page),
                       'FILE_PAGE' (a buffered file page), 'MEMORY' (contains a
                       main memory object), 'REMOVE_HASH' (hash index should be
                       removed before placing in the free list).

'IO_FIX'               Specifies whether any I/O is pending for this page:
                       'IO_NONE' = no pending I/O, 'IO_READ' = read pending,
                       'IO_WRITE' = write pending.

'IS_OLD'               Specifies whether or not the block is in the sublist of
                       old blocks in the LRU list.

'FREE_PAGE_CLOCK'      The value of the 'freed_page_clock' counter when the
                       block was the last placed at the head of the LRU list.
                       The 'freed_page_clock' counter tracks the number of
                       blocks removed from the end of the LRU list.

*Example*

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_BUFFER_PAGE_LRU LIMIT 1\G
     *************************** 1. row ***************************
                 POOL_ID: 0
            LRU_POSITION: 0
                   SPACE: 97
             PAGE_NUMBER: 1984
               PAGE_TYPE: INDEX
              FLUSH_TYPE: 1
               FIX_COUNT: 0
               IS_HASHED: YES
     NEWEST_MODIFICATION: 719490396
     OLDEST_MODIFICATION: 0
             ACCESS_TIME: 3378383796
              TABLE_NAME: `employees`.`salaries`
              INDEX_NAME: PRIMARY
          NUMBER_RECORDS: 468
               DATA_SIZE: 14976
         COMPRESSED_SIZE: 0
              COMPRESSED: NO
                  IO_FIX: IO_NONE
                  IS_OLD: YES
         FREE_PAGE_CLOCK: 0

*Notes*

   * This table is primarily useful for expert-level performance
     monitoring, or when developing performance-related extensions for
     MySQL.

   * You must have the 'PROCESS' privilege to query this table.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * Querying this table can require MySQL to allocate a large block of
     contiguous memory, more than 64 bytes time the number of active
     pages in the buffer pool.  This allocation could potentially cause
     an out-of-memory error, especially for systems with multi-gigabyte
     buffer pools.

   * Querying this table requires MySQL to lock the data structure
     representing the buffer pool while traversing the LRU list, which
     can reduce concurrency, especially for systems with multi-gigabyte
     buffer pools.

   * When tables, table rows, partitions, or indexes are deleted,
     associated pages remain in the buffer pool until space is required
     for other data.  The 'INNODB_BUFFER_PAGE_LRU' table reports
     information about these pages until they are evicted from the
     buffer pool.  For more information about how the 'InnoDB' manages
     buffer pool data, see innodb-buffer-pool.

24.31.3 The INFORMATION_SCHEMA INNODB_BUFFER_POOL_STATS Table
-------------------------------------------------------------

The 'INNODB_BUFFER_POOL_STATS' table provides much of the same buffer
pool information provided in 'SHOW ENGINE INNODB STATUS' output.  Much
of the same information may also be obtained using 'InnoDB' buffer pool
server status variables.

The idea of making pages in the buffer pool 'young' or 'not young'
refers to transferring them between the sublists at the head and tail of
the buffer pool data structure.  Pages made 'young' take longer to age
out of the buffer pool, while pages made 'not young' are moved much
closer to the point of eviction.

For related usage information and examples, see
innodb-information-schema-buffer-pool-tables.

*INNODB_BUFFER_POOL_STATS Columns*

Column name            Description

'POOL_ID'              Buffer Pool ID. A unique identifier to distinguish
                       between multiple buffer pool instances.

'POOL_SIZE'            The 'InnoDB' buffer pool size in pages.

'FREE_BUFFERS'         The number of free pages in the 'InnoDB' buffer pool

'DATABASE_PAGES'       The number of pages in the 'InnoDB' buffer pool
                       containing data.  The number includes both dirty and
                       clean pages.

'OLD_DATABASE_PAGES'   The number of pages in the 'old' buffer pool sublist.

'MODIFIED_DATABASE_PAGES'The number of modified (dirty) database pages

'PENDING_DECOMPRESS'   The number of pages pending decompression

'PENDING_READS'        The number of pending reads

'PENDING_FLUSH_LRU'    The number of pages pending flush in the LRU

'PENDING_FLUSH_LIST'   The number of pages pending flush in the flush list

'PAGES_MADE_YOUNG'     The number of pages made young

'PAGES_NOT_MADE_YOUNG' The number of pages not made young

'PAGES_MADE_YOUNG_RATE'The number of pages made young per second (pages made
                       young since the last printout / time elapsed)

'PAGES_MADE_NOT_YOUNG_RATE'The number of pages not made per second (pages not made
                       young since the last printout / time elapsed)

'NUMBER_PAGES_READ'    The number of pages read

'NUMBER_PAGES_CREATED' The number of pages created

'NUMBER_PAGES_WRITTEN' The number of pages written

'PAGES_READ_RATE'      The number of pages read per second (pages read since
                       the last printout / time elapsed)

'PAGES_CREATE_RATE'    The number of pages created per second (pages created
                       since the last printout / time elapsed)

'PAGES_WRITTEN_RATE'   The number of pages written per second (pages written
                       since the last printout / time elapsed)

'NUMBER_PAGES_GET'     The number of logical read requests.

'HIT_RATE'             The buffer pool hit rate

'YOUNG_MAKE_PER_THOUSAND_GETS'The number of pages made young per thousand gets

'NOT_YOUNG_MAKE_PER_THOUSAND_GETS'The number of pages not made young per thousand gets

'NUMBER_PAGES_READ_AHEAD'The number of pages read ahead

'NUMBER_READ_AHEAD_EVICTED'The number of pages read into the 'InnoDB' buffer pool
                       by the read-ahead background thread that were
                       subsequently evicted without having been accessed by
                       queries.

'READ_AHEAD_RATE'      The read ahead rate per second (pages read ahead since
                       the last printout / time elapsed)

'READ_AHEAD_EVICTED_RATE'The number of read ahead pages evicted without access
                       per second (read ahead pages not accessed since the last
                       printout / time elapsed)

'LRU_IO_TOTAL'         LRU IO total

'LRU_IO_CURRENT'       LRU IO for the current interval

'UNCOMPRESS_TOTAL'     Total number of pages decompressed

'UNCOMPRESS_CURRENT'   The number of pages decompressed in the current interval

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_BUFFER_POOL_STATS\G
     *************************** 1. row ***************************
                              POOL_ID: 0
                            POOL_SIZE: 8192
                         FREE_BUFFERS: 1
                       DATABASE_PAGES: 8085
                   OLD_DATABASE_PAGES: 2964
              MODIFIED_DATABASE_PAGES: 0
                   PENDING_DECOMPRESS: 0
                        PENDING_READS: 0
                    PENDING_FLUSH_LRU: 0
                   PENDING_FLUSH_LIST: 0
                     PAGES_MADE_YOUNG: 22821
                 PAGES_NOT_MADE_YOUNG: 3544303
                PAGES_MADE_YOUNG_RATE: 357.62602199870594
            PAGES_MADE_NOT_YOUNG_RATE: 0
                    NUMBER_PAGES_READ: 2389
                 NUMBER_PAGES_CREATED: 12385
                 NUMBER_PAGES_WRITTEN: 13111
                      PAGES_READ_RATE: 0
                    PAGES_CREATE_RATE: 0
                   PAGES_WRITTEN_RATE: 0
                     NUMBER_PAGES_GET: 33322210
                             HIT_RATE: 1000
         YOUNG_MAKE_PER_THOUSAND_GETS: 18
     NOT_YOUNG_MAKE_PER_THOUSAND_GETS: 0
              NUMBER_PAGES_READ_AHEAD: 2024
            NUMBER_READ_AHEAD_EVICTED: 0
                      READ_AHEAD_RATE: 0
              READ_AHEAD_EVICTED_RATE: 0
                         LRU_IO_TOTAL: 0
                       LRU_IO_CURRENT: 0
                     UNCOMPRESS_TOTAL: 0
                   UNCOMPRESS_CURRENT: 0

*Notes*:

   * This table is primarily useful for expert-level performance
     monitoring, or when developing performance-related extensions for
     MySQL.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.4 The INFORMATION_SCHEMA INNODB_CMP and INNODB_CMP_RESET Tables
---------------------------------------------------------------------

The 'INNODB_CMP' and 'INNODB_CMP_RESET' tables contain status
information on operations related to compressed 'InnoDB' tables.

*Columns of INNODB_CMP and INNODB_CMP_RESET*

Column name                   Description

'PAGE_SIZE'                   Compressed
                              page
                              size
                              in
                              bytes.

'COMPRESS_OPS'                Number
                              of
                              times
                              a
                              B-tree
                              page
                              of the
                              size
                              'PAGE_SIZE'
                              has
                              been
                              compressed.
                              Pages
                              are
                              compressed
                              whenever
                              an
                              empty
                              page
                              is
                              created
                              or the
                              space
                              for
                              the
                              uncompressed
                              modification
                              log
                              runs
                              out.

'COMPRESS_OPS_OK'             Number
                              of
                              times
                              a
                              B-tree
                              page
                              of the
                              size
                              'PAGE_SIZE'
                              has
                              been
                              successfully
                              compressed.
                              This
                              count
                              should
                              never
                              exceed
                              'COMPRESS_OPS'.

'COMPRESS_TIME'               Total
                              time
                              in
                              seconds
                              spent
                              in
                              attempts
                              to
                              compress
                              B-tree
                              pages
                              of the
                              size
                              'PAGE_SIZE'.

'UNCOMPRESS_OPS'              Number
                              of
                              times
                              a
                              B-tree
                              page
                              of the
                              size
                              'PAGE_SIZE'
                              has
                              been
                              uncompressed.
                              B-tree
                              pages
                              are
                              uncompressed
                              whenever
                              compression
                              fails
                              or at
                              first
                              access
                              when
                              the
                              uncompressed
                              page
                              does
                              not
                              exist
                              in the
                              buffer
                              pool.

'UNCOMPRESS_TIME'             Total
                              time
                              in
                              seconds
                              spent
                              in
                              uncompressing
                              B-tree
                              pages
                              of the
                              size
                              'PAGE_SIZE'.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_CMP\G
     *************************** 1. row ***************************
           page_size: 1024
        compress_ops: 0
     compress_ops_ok: 0
       compress_time: 0
      uncompress_ops: 0
     uncompress_time: 0
     *************************** 2. row ***************************
           page_size: 2048
        compress_ops: 0
     compress_ops_ok: 0
       compress_time: 0
      uncompress_ops: 0
     uncompress_time: 0
     *************************** 3. row ***************************
           page_size: 4096
        compress_ops: 0
     compress_ops_ok: 0
       compress_time: 0
      uncompress_ops: 0
     uncompress_time: 0
     *************************** 4. row ***************************
           page_size: 8192
        compress_ops: 86955
     compress_ops_ok: 81182
       compress_time: 27
      uncompress_ops: 26828
     uncompress_time: 5
     *************************** 5. row ***************************
           page_size: 16384
        compress_ops: 0
     compress_ops_ok: 0
       compress_time: 0
      uncompress_ops: 0
     uncompress_time: 0

*Notes*:

   * Use these tables to measure the effectiveness of 'InnoDB' table
     compression in your database.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     these tables including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For usage information, see
     innodb-compression-tuning-monitoring and
     innodb-information-schema-examples-compression-sect.  For general
     information about 'InnoDB' table compression, see
     innodb-compression.

24.31.5 The INFORMATION_SCHEMA INNODB_CMPMEM and INNODB_CMPMEM_RESET Tables
---------------------------------------------------------------------------

The 'INNODB_CMPMEM' and 'INNODB_CMPMEM_RESET' tables contain status
information on compressed pages within the 'InnoDB' buffer pool.

*Columns of INNODB_CMPMEM and INNODB_CMPMEM_RESET*

Column name                   Description

'PAGE_SIZE'                   Block
                              size
                              in
                              bytes.
                              Each
                              record
                              of
                              this
                              table
                              describes
                              blocks
                              of
                              this
                              size.

'BUFFER_POOL_INSTANCE'        A
                              unique
                              identifier
                              for
                              the
                              buffer
                              pool
                              instance.

'PAGES_USED'                  Number
                              of
                              blocks
                              of the
                              size
                              'PAGE_SIZE'
                              that
                              are
                              currently
                              in
                              use.

'PAGES_FREE'                  Number
                              of
                              blocks
                              of the
                              size
                              'PAGE_SIZE'
                              that
                              are
                              currently
                              available
                              for
                              allocation.
                              This
                              column
                              shows
                              the
                              external
                              fragmentation
                              in the
                              memory
                              pool.
                              Ideally,
                              these
                              numbers
                              should
                              be at
                              most
                              1.

'RELOCATION_OPS'              Number
                              of
                              times
                              a
                              block
                              of the
                              size
                              'PAGE_SIZE'
                              has
                              been
                              relocated.
                              The
                              buddy
                              system
                              can
                              relocate
                              the
                              allocated
                              'buddy
                              neighbor'
                              of a
                              freed
                              block
                              when
                              it
                              tries
                              to
                              form a
                              bigger
                              freed
                              block.
                              Reading
                              from
                              the
                              table
                              'INNODB_CMPMEM_RESET'
                              resets
                              this
                              count.

'RELOCATION_TIME'             Total
                              time
                              in
                              microseconds
                              spent
                              in
                              relocating
                              blocks
                              of the
                              size
                              'PAGE_SIZE'.
                              Reading
                              from
                              the
                              table
                              'INNODB_CMPMEM_RESET'
                              resets
                              this
                              count.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_CMPMEM\G
     *************************** 1. row ***************************
                page_size: 1024
     buffer_pool_instance: 0
               pages_used: 0
               pages_free: 0
           relocation_ops: 0
          relocation_time: 0
     *************************** 2. row ***************************
                page_size: 2048
     buffer_pool_instance: 0
               pages_used: 0
               pages_free: 0
           relocation_ops: 0
          relocation_time: 0
     *************************** 3. row ***************************
                page_size: 4096
     buffer_pool_instance: 0
               pages_used: 0
               pages_free: 0
           relocation_ops: 0
          relocation_time: 0
     *************************** 4. row ***************************
                page_size: 8192
     buffer_pool_instance: 0
               pages_used: 7673
               pages_free: 15
           relocation_ops: 4638
          relocation_time: 0
     *************************** 5. row ***************************
                page_size: 16384
     buffer_pool_instance: 0
               pages_used: 0
               pages_free: 0
           relocation_ops: 0
          relocation_time: 0

*Notes*:

   * Use these tables to measure the effectiveness of 'InnoDB' table
     compression in your database.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     these tables including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For usage information, see
     innodb-compression-tuning-monitoring and
     innodb-information-schema-examples-compression-sect.  For general
     information about 'InnoDB' table compression, see
     innodb-compression.

24.31.6 The INFORMATION_SCHEMA INNODB_CMP_PER_INDEX and INNODB_CMP_PER_INDEX_RESET Tables
-----------------------------------------------------------------------------------------

The 'INNODB_CMP_PER_INDEX' and 'INNODB_CMP_PER_INDEX_RESET' tables
contain status information on operations related to compressed 'InnoDB'
tables and indexes, with separate statistics for each combination of
database, table, and index, to help you evaluate the performance and
usefulness of compression for specific tables.

For a compressed 'InnoDB' table, both the table data and all the
secondary indexes are compressed.  In this context, the table data is
treated as just another index, one that happens to contain all the
columns: the clustered index.

*Columns of INNODB_CMP_PER_INDEX and INNODB_CMP_PER_INDEX_RESET*

Column name                   Description

'DATABASE_NAME'               Database
                              containing
                              the
                              applicable
                              table.

'TABLE_NAME'                  Table
                              to
                              monitor
                              for
                              compression
                              statistics.

'INDEX_NAME'                  Index
                              to
                              monitor
                              for
                              compression
                              statistics.

'COMPRESS_OPS'                Number
                              of
                              compression
                              operations
                              attempted.
                              Pages
                              are
                              compressed
                              whenever
                              an
                              empty
                              page
                              is
                              created
                              or the
                              space
                              for
                              the
                              uncompressed
                              modification
                              log
                              runs
                              out.

'COMPRESS_OPS_OK'             Number
                              of
                              successful
                              compression
                              operations.
                              Subtract
                              from
                              the
                              'COMPRESS_OPS'
                              value
                              to get
                              the
                              number
                              of
                              compression
                              failures.
                              Divide
                              by the
                              'COMPRESS_OPS'
                              value
                              to get
                              the
                              percentage
                              of
                              compression
                              failures.

'COMPRESS_TIME'               Total
                              amount
                              of CPU
                              time,
                              in
                              seconds,
                              used
                              for
                              compressing
                              data
                              in
                              this
                              index.

'UNCOMPRESS_OPS'              Number
                              of
                              uncompression
                              operations
                              performed.
                              Compressed
                              'InnoDB'
                              pages
                              are
                              uncompressed
                              whenever
                              compression
                              fails,
                              or the
                              first
                              time a
                              compressed
                              page
                              is
                              accessed
                              in the
                              buffer
                              pool
                              and
                              the
                              uncompressed
                              page
                              does
                              not
                              exist.

'UNCOMPRESS_TIME'             Total
                              amount
                              of CPU
                              time,
                              in
                              seconds,
                              used
                              for
                              uncompressing
                              data
                              in
                              this
                              index.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_CMP_PER_INDEX\G
     *************************** 1. row ***************************
       database_name: employees
          table_name: salaries
          index_name: PRIMARY
        compress_ops: 0
     compress_ops_ok: 0
       compress_time: 0
      uncompress_ops: 23451
     uncompress_time: 4
     *************************** 2. row ***************************
       database_name: employees
          table_name: salaries
          index_name: emp_no
        compress_ops: 0
     compress_ops_ok: 0
       compress_time: 0
      uncompress_ops: 1597
     uncompress_time: 0

*Notes*:

   * Use these tables to measure the effectiveness of 'InnoDB' table
     compression for specific tables, indexes, or both.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     these tables including data types and default values.

   * You must have the 'PROCESS' privilege to query these tables.

   * Because collecting separate measurements for every index imposes
     substantial performance overhead, 'INNODB_CMP_PER_INDEX' and
     'INNODB_CMP_PER_INDEX_RESET' statistics are not gathered by
     default.  You must enable the 'innodb_cmp_per_index_enabled'
     configuration option before performing the operations on compressed
     tables that you want to monitor.

   * For usage information, see
     innodb-compression-tuning-monitoring and
     innodb-information-schema-examples-compression-sect.  For general
     information about 'InnoDB' table compression, see
     innodb-compression.

24.31.7 The INFORMATION_SCHEMA INNODB_FT_BEING_DELETED Table
------------------------------------------------------------

The 'INNODB_FT_BEING_DELETED' table is a snapshot of the
'INNODB_FT_DELETED' table that is only used
during an 'OPTIMIZE TABLE' maintenance operation.
When 'OPTIMIZE TABLE' is run, the
'INNODB_FT_BEING_DELETED' table is emptied, and DOC_IDs are removed from
the 'INNODB_FT_DELETED' table.  Because
the contents of 'INNODB_FT_BEING_DELETED' typically have a short
lifetime, this table has limited utility for monitoring or debugging.
For information about running 'OPTIMIZE TABLE' on
tables with 'FULLTEXT' indexes, see fulltext-fine-tuning.

This table initially appears empty, until you set the value of the
configuration variable 'innodb_ft_aux_table'.  The output appears
similar to the example provided for the 'INNODB_FT_DELETED'
table.

For related usage information and examples, see
innodb-information-schema-fulltext_index-tables.

*INNODB_FT_BEING_DELETED Columns*

Column name            Description

'DOC_ID'               The document ID of the row that is in the process of
                       being deleted.  This value might reflect the value of an
                       ID column that you defined for the underlying table, or
                       it can be a sequence value generated by 'InnoDB' when
                       the table does not contain a suitable column.  This
                       value is used to skip rows in the
                       'innodb_ft_index_table'.
                       table, when you do text searches before data for deleted
                       rows is physically removed from the 'FULLTEXT' index by
                       an 'OPTIMIZE TABLE' statement.
                       See fulltext-optimize for more information.

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For more information about 'InnoDB' 'FULLTEXT' search, see
     innodb-fulltext-index, and fulltext-search.

24.31.8 The INFORMATION_SCHEMA INNODB_FT_CONFIG Table
-----------------------------------------------------

The 'INNODB_FT_CONFIG' table displays metadata about the 'FULLTEXT'
index and associated processing for an 'InnoDB' table.

Before you query this table, set the configuration variable
'innodb_ft_aux_table' to the name (including the database name) of the
table that contains the 'FULLTEXT' index, for example 'test/articles'.

For related usage information and examples, see
innodb-information-schema-fulltext_index-tables.

*INNODB_FT_CONFIG Columns*

Column name            Description

'KEY'                  The name designating an item of metadata for an 'InnoDB'
                       table containing a 'FULLTEXT' index.

'VALUE'                The value associated with the corresponding 'KEY'
                       column, reflecting some limit or current value for an
                       aspect of a 'FULLTEXT' index for an 'InnoDB' table.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_CONFIG;
     +---------------------------+-------------------+
     | KEY                       | VALUE             |
     +---------------------------+-------------------+
     | optimize_checkpoint_limit | 180               |
     | synced_doc_id             | 0                 |
     | stopword_table_name       | test/my_stopwords |
     | use_stopword              | 1                 |
     +---------------------------+-------------------+

*Notes*:

   * This table is only intended for internal configuration.  It is not
     intended for statistical information purposes.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * The values for the 'KEY' column might evolve depending on the needs
     for performance tuning and debugging for 'InnoDB' full-text
     processing.  The key values include:

        * 'optimize_checkpoint_limit': The number of seconds after which
          an 'OPTIMIZE TABLE' run will stop.

        * 'synced_doc_id': The next 'DOC_ID' to be issued.

        * 'stopword_table_name': The DATABASE/TABLE name for a user
          defined stopword table.  This field appears empty if there is
          no user-defined stopword table.

        * 'use_stopword': Indicates whether or not a stopword table is
          used, which is defined when the 'FULLTEXT' index is created.

   * For more information about 'InnoDB' 'FULLTEXT' search, see
     innodb-fulltext-index, and fulltext-search.

24.31.9 The INFORMATION_SCHEMA INNODB_FT_DEFAULT_STOPWORD Table
---------------------------------------------------------------

The 'INNODB_FT_DEFAULT_STOPWORD' table holds a list of stopwords that
are used by default when creating a 'FULLTEXT' index on an 'InnoDB'
table.  For information about the default 'InnoDB' stopword list and how
to define your own stopword lists, see fulltext-stopwords.

For related usage information and examples, see
innodb-information-schema-fulltext_index-tables.

*INNODB_FT_DEFAULT_STOPWORD Columns*

Column name            Description

'value'                A word that is used by default as a stopword for
                       'FULLTEXT' indexes on 'InnoDB' tables.  Not used if you
                       override the default stopword processing with either the
                       'innodb_ft_server_stopword_table' or the
                       'innodb_ft_user_stopword_table' option.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_DEFAULT_STOPWORD;
     +-------+
     | value |
     +-------+
     | a     |
     | about |
     | an    |
     | are   |
     | as    |
     | at    |
     | be    |
     | by    |
     | com   |
     | de    |
     | en    |
     | for   |
     | from  |
     | how   |
     | i     |
     | in    |
     | is    |
     | it    |
     | la    |
     | of    |
     | on    |
     | or    |
     | that  |
     | the   |
     | this  |
     | to    |
     | was   |
     | what  |
     | when  |
     | where |
     | who   |
     | will  |
     | with  |
     | und   |
     | the   |
     | www   |
     +-------+
     36 rows in set (0.00 sec)

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For more information about 'InnoDB' 'FULLTEXT' search, see
     innodb-fulltext-index, and fulltext-search.

24.31.10 The INFORMATION_SCHEMA INNODB_FT_DELETED Table
-------------------------------------------------------

The 'INNODB_FT_DELETED' table records rows that are deleted from the
'FULLTEXT' index for an 'InnoDB' table.  To avoid expensive index
reorganization during DML operations for an 'InnoDB' 'FULLTEXT' index,
the information about newly deleted words is stored separately, filtered
out of search results when you do a text search, and removed from the
main search index only when you issue the 'OPTIMIZE TABLE'
statement for the 'InnoDB' table.  See
fulltext-optimize for more information.

This table initially appears empty, until you set the value of the
configuration variable 'innodb_ft_aux_table' to the name (including the
database name) of the table that contains the 'FULLTEXT' index, for
example 'test/articles'.

For related usage information and examples, see
innodb-information-schema-fulltext_index-tables.

*INNODB_FT_DELETED Columns*

Column name            Description

'DOC_ID'               The document ID of the newly deleted row.  This value
                       might reflect the value of an ID column that you defined
                       for the underlying table, or it can be a sequence value
                       generated by 'InnoDB' when the table does not contain a
                       suitable column.  This value is used to skip rows in the
                       'innodb_ft_index_table'
                       table, when you do text
                       searches before data for deleted rows is physically
                       removed from the 'FULLTEXT' index by an 'OPTIMIZE TABLE'
                       statement.  See
                       fulltext-optimize for more information.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_FT_DELETED;
     +--------+
     | DOC_ID |
     +--------+
     |      6 |
     |      7 |
     |      8 |
     +--------+

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For more information about 'InnoDB' 'FULLTEXT' search, see
     innodb-fulltext-index, and fulltext-search.

24.31.11 The INFORMATION_SCHEMA INNODB_FT_INDEX_CACHE Table
-----------------------------------------------------------

'INNODB_FT_INDEX_CACHE': Contains token information about newly inserted
rows in a 'FULLTEXT' index.  To avoid expensive index reorganization
during DML operations, the information about newly indexed words is
stored separately, and combined with the main search index only when
'OPTIMIZE TABLE' is run, when the server is shut
down, or when the cache size exceeds a limit defined by
'innodb_ft_cache_size' or 'innodb_ft_total_cache_size'.

Before you query this table, set the configuration variable
'innodb_ft_aux_table' to the name (including the database name) of the
table that contains the 'FULLTEXT' index, for example 'test/articles'.

For related usage information and examples, see
innodb-information-schema-fulltext_index-tables.

*INNODB_FT_INDEX_CACHE Columns*

Column name            Description

'WORD'                 A word extracted from the text of a newly inserted row.

'FIRST_DOC_ID'         The first document ID that this word appears in the
                       'FULLTEXT' index.

'LAST_DOC_ID'          The last document ID that this word appears in the
                       'FULLTEXT' index.

'DOC_COUNT'            The number of rows this word appears in the 'FULLTEXT'
                       index.  The same word can occur several times within the
                       cache table, once for each combination of 'DOC_ID' and
                       'POSITION' values.

'DOC_ID'               The document ID of the newly inserted row.  This value
                       might reflect the value of an ID column that you defined
                       for the underlying table, or it can be a sequence value
                       generated by 'InnoDB' when the table does not contain a
                       suitable column.

'POSITION'             The position of this particular instance of the word
                       within the relevant document identified by the 'DOC_ID'
                       value.  The value does not represent an absolute
                       position; it is an offset added to the 'POSITION' of the
                       previous instance of that word.

*Notes*:

   * This table initially appears empty, until you set the value of the
     configuration variable 'innodb_ft_aux_table'.  The following
     example demonstrates how to use the 'innodb_ft_aux_table' option to
     show information about a 'FULLTEXT' index for a specified table.

          mysql> USE test;

          mysql> CREATE TABLE articles (
                id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
                title VARCHAR(200),
                body TEXT,
                FULLTEXT (title,body)
              ) ENGINE=InnoDB;

          mysql> INSERT INTO articles (title,body) VALUES
              ('MySQL Tutorial','DBMS stands for DataBase ...'),
              ('How To Use MySQL Well','After you went through a ...'),
              ('Optimizing MySQL','In this tutorial we will show ...'),
              ('1001 MySQL Tricks','1. Never run mysqld as root. 2. ...'),
              ('MySQL vs. YourSQL','In the following database comparison ...'),
              ('MySQL Security','When configured properly, MySQL ...');

          mysql> SET GLOBAL innodb_ft_aux_table = 'test/articles';
          Query OK, 0 rows affected (0.00 sec)

          mysql> USE INFORMATION_SCHEMA;

          mysql> SELECT word, doc_count, doc_id, position FROM INNODB_FT_INDEX_CACHE LIMIT 5;
          +------------+-----------+--------+----------+
          | word       | doc_count | doc_id | position |
          +------------+-----------+--------+----------+
          | 1001       |         1 |      4 |        0 |
          | after      |         1 |      2 |       22 |
          | comparison |         1 |      5 |       44 |
          | configured |         1 |      6 |       20 |
          | database   |         2 |      1 |       31 |
          +------------+-----------+--------+----------+

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For more information about 'InnoDB' 'FULLTEXT' search, see
     innodb-fulltext-index, and fulltext-search.

24.31.12 The INFORMATION_SCHEMA INNODB_FT_INDEX_TABLE Table
-----------------------------------------------------------

The 'INNODB_FT_INDEX_TABLE' table displays information about the
inverted index used to process text searches against the 'FULLTEXT'
index of an 'InnoDB' table.

For related usage information and examples, see
innodb-information-schema-fulltext_index-tables.

Before you query this table, set the configuration variable
'innodb_ft_aux_table' to the name (including the database name) of the
table that contains the 'FULLTEXT' index, for example 'test/articles'.

*INNODB_FT_INDEX_TABLE Columns*

Column name            Description

'WORD'                 A word extracted from the text of the columns that are
                       part of a 'FULLTEXT'.

'FIRST_DOC_ID'         The first document ID that this word appears in the
                       'FULLTEXT' index.

'LAST_DOC_ID'          The last document ID that this word appears in the
                       'FULLTEXT' index.

'DOC_COUNT'            The number of rows this word appears in the 'FULLTEXT'
                       index.  The same word can occur several times within the
                       cache table, once for each combination of 'DOC_ID' and
                       'POSITION' values.

'DOC_ID'               The document ID of the row containing the word.  This
                       value might reflect the value of an ID column that you
                       defined for the underlying table, or it can be a
                       sequence value generated by 'InnoDB' when the table does
                       not contain a suitable column.

'POSITION'             The position of this particular instance of the word
                       within the relevant document identified by the 'DOC_ID'
                       value.

*Notes*:

   * This table initially appears empty, until you set the value of the
     configuration variable 'innodb_ft_aux_table'.  The following
     example demonstrates how to use the 'innodb_ft_aux_table' option to
     show information about a 'FULLTEXT' index for a specified table.
     Before information for newly inserted rows appears in
     'INNODB_FT_INDEX_TABLE', the 'FULLTEXT' index cache must be flushed
     to disk.  This is accomplished by running an 'OPTIMIZE TABLE'
     operation on the indexed table with
     'innodb_optimize_fulltext_only=ON'.

          mysql> USE test;

          mysql> CREATE TABLE articles (
                id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
                title VARCHAR(200),
                body TEXT,
                FULLTEXT (title,body)
              ) ENGINE=InnoDB;

          mysql> INSERT INTO articles (title,body) VALUES
              ('MySQL Tutorial','DBMS stands for DataBase ...'),
              ('How To Use MySQL Well','After you went through a ...'),
              ('Optimizing MySQL','In this tutorial we will show ...'),
              ('1001 MySQL Tricks','1. Never run mysqld as root. 2. ...'),
              ('MySQL vs. YourSQL','In the following database comparison ...'),
              ('MySQL Security','When configured properly, MySQL ...');

          mysql> SET GLOBAL innodb_optimize_fulltext_only=ON;
          Query OK, 0 rows affected (0.00 sec)

          mysql> OPTIMIZE TABLE articles;
          +---------------+----------+----------+----------+
          | Table         | Op       | Msg_type | Msg_text |
          +---------------+----------+----------+----------+
          | test.articles | optimize | status   | OK       |
          +---------------+----------+----------+----------+

          mysql> SET GLOBAL innodb_ft_aux_table = 'test/articles';
          Query OK, 0 rows affected (0.00 sec)

          mysql> USE INFORMATION_SCHEMA;

          mysql> SELECT word, doc_count, doc_id, position FROM INNODB_FT_INDEX_TABLE LIMIT 5;
          +------------+-----------+--------+----------+
          | word       | doc_count | doc_id | position |
          +------------+-----------+--------+----------+
          | 1001       |         1 |      4 |        0 |
          | after      |         1 |      2 |       22 |
          | comparison |         1 |      5 |       44 |
          | configured |         1 |      6 |       20 |
          | database   |         2 |      1 |       31 |
          +------------+-----------+--------+----------+

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For more information about 'InnoDB' 'FULLTEXT' search, see
     innodb-fulltext-index, and fulltext-search.

24.31.13 The INFORMATION_SCHEMA INNODB_LOCKS Table
--------------------------------------------------

The 'INNODB_LOCKS' table contains information about each lock that an
'InnoDB' transaction has requested but not yet acquired, and each lock
that a transaction holds that is blocking another transaction.

*Note*:

This table is deprecated as of MySQL 5.7.14 and is removed in MySQL 8.0.

*INNODB_LOCKS Columns*

Column  Description
name

'LOCK_ID'Unique lock ID number,
        internal to 'InnoDB'.
        Treat it as an opaque
        string.  Although 'LOCK_ID'
        currently contains
        'TRX_ID', the format of the
        data in 'LOCK_ID' is
        subject to change at any
        time.  Do not write
        applications that parse the
        'LOCK_ID' value.

'LOCK_TRX_ID'ID of the transaction
        holding the lock.  To
        obtain details about the
        transaction, join this
        column with the 'TRX_ID'
        column of the
        'INNODB_TRX'
        table.

'LOCK_MODE'How the lock is requested.
        Permitted values are
        'S[,GAP]', 'X[,GAP]',
        'IS[,GAP]', 'IX[,GAP]',
        'AUTO_INC', and 'UNKNOWN'.
        Lock modes other than
        'AUTO_INC' and 'UNKNOWN'
        indicate gap locks, if
        present.  For information
        about 'S', 'X', 'IS', 'IX',
        and gap locks, refer to
        innodb-locking.

'LOCK_TYPE'The type of lock.
        Permitted values are
        'RECORD' for a row-level
        lock, 'TABLE' for a
        table-level lock.

'LOCK_TABLE'Name of the table that has
        been locked or contains
        locked records.

'LOCK_INDEX'Name of the index, if
        'LOCK_TYPE' is 'RECORD';
        otherwise 'NULL'.

'LOCK_SPACE'Tablespace ID of the locked
        record, if 'LOCK_TYPE' is
        'RECORD'; otherwise 'NULL'.

'LOCK_PAGE'Page number of the locked
        record, if 'LOCK_TYPE' is
        'RECORD'; otherwise 'NULL'.

'LOCK_REC'Heap number of the locked
        record within the page, if
        'LOCK_TYPE' is 'RECORD';
        otherwise 'NULL'.

'LOCK_DATA'The data associated with
        the lock, if any.  Values
        are primary key values of
        the locked record if
        'LOCK_TYPE' is 'RECORD',
        otherwise 'NULL'.  This
        column contains the values
        of the primary key columns
        in the locked row,
        formatted as a valid SQL
        string (ready to be copied
        to SQL statements).  If
        there is no primary key,
        'LOCK_DATA' is the unique
        'InnoDB' internal row ID
        number.  If a gap lock is
        taken for key values or
        ranges above the largest
        value in the index,
        'LOCK_DATA' reports
        'supremum pseudo-record'.
        When the page containing
        the locked record is not in
        the buffer pool (in the
        case that it was paged out
        to disk while the lock was
        held), 'InnoDB' does not
        fetch the page from disk,
        to avoid unnecessary disk
        operations.  Instead,
        'LOCK_DATA' is set to
        'NULL'.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_LOCKS\G
     *************************** 1. row ***************************
         lock_id: 3723:72:3:2
     lock_trx_id: 3723
       lock_mode: X
       lock_type: RECORD
      lock_table: `mysql`.`t`
      lock_index: PRIMARY
      lock_space: 72
       lock_page: 3
        lock_rec: 2
       lock_data: 1, 9
     *************************** 2. row ***************************
         lock_id: 3722:72:3:2
     lock_trx_id: 3722
       lock_mode: S
       lock_type: RECORD
      lock_table: `mysql`.`t`
      lock_index: PRIMARY
      lock_space: 72
       lock_page: 3
        lock_rec: 2
       lock_data: 1, 9

*Notes*:

   * Use this table to help diagnose performance problems that occur
     during times of heavy concurrent load.  Its contents are updated as
     described in innodb-information-schema-internal-data.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For usage information, see
     innodb-information-schema-examples.

24.31.14 The INFORMATION_SCHEMA INNODB_LOCK_WAITS Table
-------------------------------------------------------

The 'INNODB_LOCK_WAITS' table contains one or more rows for each blocked
'InnoDB' transaction, indicating the lock it has requested and any locks
that are blocking that request.

*Note*:

This table is deprecated as of MySQL 5.7.14 and is removed in MySQL 8.0.

*INNODB_LOCK_WAITS Columns*

Column name            Description

'REQUESTING_TRX_ID'    ID of the requesting (blocked) transaction.

'REQUESTED_LOCK_ID'    ID of the lock for which a transaction is waiting.  To
                       obtain details about the lock, join this column with the
                       'LOCK_ID' column of the 'INNODB_LOCKS'
                       table.

'BLOCKING_TRX_ID'      ID of the blocking transaction.

'BLOCKING_LOCK_ID'     ID of a lock held by a transaction blocking another
                       transaction from proceeding.  To obtain details about
                       the lock, join this column with the 'LOCK_ID' column of
                       the 'INNODB_LOCKS' table.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_LOCK_WAITS\G
     *************************** 1. row ***************************
     requesting_trx_id: 3396
     requested_lock_id: 3396:91:3:2
       blocking_trx_id: 3395
      blocking_lock_id: 3395:91:3:2

*Notes*:

   * Use this table to help diagnose performance problems that occur
     during times of heavy concurrent load.  Its contents are updated as
     described in innodb-information-schema-internal-data.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For usage information, see
     innodb-information-schema-examples.

24.31.15 The INFORMATION_SCHEMA INNODB_METRICS Table
----------------------------------------------------

This 'INFORMATION_SCHEMA' table presents a wide variety of 'InnoDB'
performance information, complementing the specific focus areas of the
'PERFORMANCE_SCHEMA' tables for 'InnoDB'.  With simple queries, you can
check the overall health of the system.  With more detailed queries, you
can diagnose issues such as performance bottlenecks, resource shortages,
and application issues.

Each monitor represents a point within the 'InnoDB' source code that is
instrumented to gather counter information.  Each counter can be
started, stopped, and reset.  You can also perform these actions for a
group of counters using their common module name.

By default, relatively little data is collected.  To start, stop, and
reset counters, you set one of the configuration options
'innodb_monitor_enable', 'innodb_monitor_disable',
'innodb_monitor_reset', or 'innodb_monitor_reset_all', using the name of
the counter, the name of the module, a wildcard match for such a name
using the '%' character, or the special keyword 'all'.

For usage information, see
innodb-information-schema-metrics-table.

*INNODB_METRICS Columns*

Column name            Description

'NAME'                 Unique name for the counter.

'SUBSYSTEM'            The aspect of 'InnoDB' that the metric applies to.  See
                       the list following the table for the corresponding
                       module names to use with the 'SET GLOBAL' syntax.

'COUNT'                Value since the counter is enabled.

'MAX_COUNT'            Maximum value since the counter is enabled.

'MIN_COUNT'            Minimum value since the counter is enabled.

'AVG_COUNT'            Average value since the counter is enabled.

'COUNT_RESET'          Counter value since it was last reset.  (The '_RESET'
                       fields act like the lap counter on a stopwatch: you can
                       measure the activity during some time interval, while
                       the cumulative figures are still available in the
                       'COUNT', 'MAX_COUNT', and so on fields.)

'MAX_COUNT_RESET'      Maximum counter value since it was last reset.

'MIN_COUNT_RESET'      Minimum counter value since it was last reset.

'AVG_COUNT_RESET'      Average counter value since it was last reset.

'TIME_ENABLED'         Timestamp of last start.

'TIME_DISABLED'        Timestamp of last stop.

'TIME_ELAPSED'         Elapsed time in seconds since the counter started.

'TIME_RESET'           Timestamp of last stop.

'STATUS'               Whether the counter is still running ('enabled') or
                       stopped ('disabled').

'TYPE'                 Whether the item is a cumulative counter, or measures
                       the current value of some resource.

'COMMENT'              Counter description.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_METRICS WHERE NAME="dml_inserts"\G
     *************************** 1. row ***************************
                NAME: dml_inserts
           SUBSYSTEM: dml
               COUNT: 3
           MAX_COUNT: 3
           MIN_COUNT: NULL
           AVG_COUNT: 0.046153846153846156
         COUNT_RESET: 3
     MAX_COUNT_RESET: 3
     MIN_COUNT_RESET: NULL
     AVG_COUNT_RESET: NULL
        TIME_ENABLED: 2014-12-04 14:18:28
       TIME_DISABLED: NULL
        TIME_ELAPSED: 65
          TIME_RESET: NULL
              STATUS: enabled
                TYPE: status_counter
             COMMENT: Number of rows inserted

*Notes*:

   * You must have the 'PROCESS' privilege to query this table.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

24.31.16 The INFORMATION_SCHEMA INNODB_SYS_COLUMNS Table
--------------------------------------------------------

The 'INNODB_SYS_COLUMNS' table provides metadata about 'InnoDB' table
columns, equivalent to the information from the 'SYS_COLUMNS' table in
the 'InnoDB' data dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*INNODB_SYS_COLUMNS Columns*

Column name            Description

'TABLE_ID'             An identifier representing the table associated with the
                       column; the same value from
                       'INNODB_SYS_TABLES.TABLE_ID'.

'NAME'                 The name of each column in each table.  These names can
                       be uppercase or lowercase depending on the
                       'lower_case_table_names' setting.  There are no special
                       system-reserved names for columns.

'POS'                  The ordinal position of the column within the table,
                       starting from 0 and incrementing sequentially.  When a
                       column is dropped, the remaining columns are reordered
                       so that the sequence has no gaps.  The 'POS' value for a
                       virtual generated column encodes the column sequence
                       number and ordinal position of the column.  For more
                       information, see the 'POS' column description in
                       innodb-sys-virtual-table.

'MTYPE'                Stands for 'main type'.  A numeric identifier for the
                       column type.  1 = 'VARCHAR', 2 = 'CHAR', 3 =
                       'FIXBINARY', 4 = 'BINARY', 5 = 'BLOB', 6 = 'INT', 7 =
                       'SYS_CHILD', 8 = 'SYS', 9 = 'FLOAT', 10 = 'DOUBLE', 11 =
                       'DECIMAL', 12 = 'VARMYSQL', 13 = 'MYSQL', 14 =
                       'GEOMETRY'.

'PRTYPE'               The 'InnoDB' 'precise type', a binary value with bits
                       representing MySQL data type, character set code, and
                       nullability.

'LEN'                  The column length, for example 4 for 'INT' and 8 for
                       'BIGINT'.  For character columns in multibyte character
                       sets, this length value is the maximum length in bytes
                       needed to represent a definition such as 'VARCHAR(N)';
                       that is, it might be '2*N', '3*N', and so on depending
                       on the character encoding.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_COLUMNS where TABLE_ID = 71\G
     *************************** 1. row ***************************
     TABLE_ID: 71
         NAME: col1
          POS: 0
        MTYPE: 6
       PRTYPE: 1027
          LEN: 4
     *************************** 2. row ***************************
     TABLE_ID: 71
         NAME: col2
          POS: 1
        MTYPE: 2
       PRTYPE: 524542
          LEN: 10
     *************************** 3. row ***************************
     TABLE_ID: 71
         NAME: col3
          POS: 2
        MTYPE: 1
       PRTYPE: 524303
          LEN: 10

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.17 The INFORMATION_SCHEMA INNODB_SYS_DATAFILES Table
----------------------------------------------------------

The 'INNODB_SYS_DATAFILES' table provides data file path information for
'InnoDB' file-per-table and general tablespaces, equivalent to the
information in the 'SYS_DATAFILES' table in the 'InnoDB' data
dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*Note*:

The 'INFORMATION_SCHEMA.FILES' table reports
metadata for all 'InnoDB' tablespace types including file-per-table
tablespaces, general tablespaces, the system tablespace, the temporary
tablespace, and undo tablespaces, if present.

*INNODB_SYS_DATAFILES Columns*

Column name            Description

'SPACE'                The tablespace Space ID.

'PATH'                 The tablespace data file path.  If a file-per-table
                       tablespace is created in a location outside the MySQL
                       data directory, the path value is a fully qualified
                       directory path.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_DATAFILES WHERE SPACE = 57\G
     *************************** 1. row ***************************
     SPACE: 57
      PATH: ./test/t1.ibd

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.18 The INFORMATION_SCHEMA INNODB_SYS_FIELDS Table
-------------------------------------------------------

The 'INNODB_SYS_FIELDS' table provides metadata about the key columns
(fields) of 'InnoDB' indexes, equivalent to the information from the
'SYS_FIELDS' table in the 'InnoDB' data dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*INNODB_SYS_FIELDS Columns*

Column name            Description

'INDEX_ID'             An identifier for the index associated with this key
                       field, using the same value as in
                       'INNODB_SYS_INDEXES.INDEX_ID'.

'NAME'                 The name of the original column from the table, using
                       the same value as in 'INNODB_SYS_COLUMNS.NAME'.

'POS'                  The ordinal position of the key field within the index,
                       starting from 0 and incrementing sequentially.  When a
                       column is dropped, the remaining columns are reordered
                       so that the sequence has no gaps.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_FIELDS WHERE INDEX_ID = 117\G
     *************************** 1. row ***************************
     INDEX_ID: 117
         NAME: col1
          POS: 0

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.19 The INFORMATION_SCHEMA INNODB_SYS_FOREIGN Table
--------------------------------------------------------

The 'INNODB_SYS_FOREIGN' table provides metadata about 'InnoDB' foreign
keys, equivalent to the information from the 'SYS_FOREIGN' table in the
'InnoDB' data dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*INNODB_SYS_FOREIGN Columns*

Column name            Description

'ID'                   The name (not a numeric value) of the foreign key index.
                       Preceded by the database name, for example,
                       'test/products_fk'.

'FOR_NAME'             The name of the child table in this foreign key
                       relationship.

'REF_NAME'             The name of the parent table in this foreign key
                       relationship.

'N_COLS'               The number of columns in the foreign key index.

'TYPE'                 A collection of bit flags with information about the
                       foreign key column, ORed together.  1 = 'ON DELETE
                       CASCADE', 2 = 'ON UPDATE SET' NULL, 4 = 'ON UPDATE
                       CASCADE', 8 = 'ON UPDATE SET' NULL, 16 = 'ON DELETE NO'
                       ACTION, 32 = 'ON UPDATE NO' ACTION.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_FOREIGN\G
     *************************** 1. row ***************************
           ID: test/fk1
     FOR_NAME: test/child
     REF_NAME: test/parent
       N_COLS: 1
         TYPE: 1

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.20 The INFORMATION_SCHEMA INNODB_SYS_FOREIGN_COLS Table
-------------------------------------------------------------

The 'INNODB_SYS_FOREIGN_COLS' table provides status information about
the columns of 'InnoDB' foreign keys, equivalent to the information from
the 'SYS_FOREIGN_COLS' table in the 'InnoDB' data dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*INNODB_SYS_FOREIGN_COLS Columns*

Column name            Description

'ID'                   The foreign key index associated with this index key
                       field, using the same value as 'INNODB_SYS_FOREIGN.ID'.

'FOR_COL_NAME'         The name of the associated column in the child table.

'REF_COL_NAME'         The name of the associated column in the parent table.

'POS'                  The ordinal position of this key field within the
                       foreign key index, starting from 0.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_FOREIGN_COLS WHERE ID = 'test/fk1'\G
     *************************** 1. row ***************************
               ID: test/fk1
     FOR_COL_NAME: parent_id
     REF_COL_NAME: id
              POS: 0

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.21 The INFORMATION_SCHEMA INNODB_SYS_INDEXES Table
--------------------------------------------------------

The 'INNODB_SYS_INDEXES' table provides metadata about 'InnoDB' indexes,
equivalent to the information in the internal 'SYS_INDEXES' table in the
'InnoDB' data dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*INNODB_SYS_INDEXES Columns*

Column name            Description

'INDEX_ID'             An identifier for each index that is unique across all
                       the databases in an instance.

'NAME'                 The name of the index.  Most indexes created implicitly
                       by 'InnoDB' have consistent names but the index names
                       are not necessarily unique.  For example, 'PRIMARY' for
                       a primary key index, 'GEN_CLUST_INDEX' for the index
                       representing a primary key when one is not specified,
                       and 'ID_IND', 'FOR_IND', and 'REF_IND' for foreign key
                       constraints.

'TABLE_ID'             An identifier representing the table associated with the
                       index; the same value from 'INNODB_SYS_TABLES.TABLE_ID'.

'TYPE'                 A numeric identifier signifying the kind of index.  0 =
                       Secondary Index, 1 = Clustered Index, 2 = Unique Index,
                       3 = Primary Index, 32 = Full-text Index, 64 = Spatial
                       Index, 128 = A secondary index that includes a virtual
                       generated column.

'N_FIELDS'             The number of columns in the index key.  For the
                       'GEN_CLUST_INDEX' indexes, this value is 0 because the
                       index is created using an artificial value rather than a
                       real table column.

'PAGE_NO'              The root page number of the index B-tree.  For full-text
                       indexes, the 'PAGE_NO' field is unused and set to -1
                       ('FIL_NULL') because the full-text index is laid out in
                       several B-trees (auxiliary tables).

'SPACE'                An identifier for the tablespace where the index
                       resides.  0 means the 'InnoDB' system tablespace.  Any
                       other number represents a table created in
                       file-per-table mode with a separate '.ibd' file.  This
                       identifier stays the same after a 'TRUNCATE TABLE'
                       statement.  Because all indexes
                       for a table reside in the same tablespace as the table,
                       this value is not necessarily unique.

'MERGE_THRESHOLD'      The merge threshold value for index pages.  If the
                       amount of data in an index page falls below the
                       MERGE_THRESHOLD value when
                       a row is deleted or when a row is shortened by an update
                       operation, 'InnoDB' attempts to merge the index page
                       with the neighboring index page.  The default threshold
                       value is 50%.  For more information, see
                       index-page-merge-threshold.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_INDEXES WHERE TABLE_ID = 34\G
     *************************** 1. row ***************************
            INDEX_ID: 39
                NAME: GEN_CLUST_INDEX
            TABLE_ID: 34
                TYPE: 1
            N_FIELDS: 0
             PAGE_NO: 3
               SPACE: 23
     MERGE_THRESHOLD: 50
     *************************** 2. row ***************************
            INDEX_ID: 40
                NAME: i1
            TABLE_ID: 34
                TYPE: 0
            N_FIELDS: 1
             PAGE_NO: 4
               SPACE: 23
     MERGE_THRESHOLD: 50

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.22 The INFORMATION_SCHEMA INNODB_SYS_TABLES Table
-------------------------------------------------------

The 'INNODB_SYS_TABLES' table provides metadata about 'InnoDB' tables,
equivalent to the information from the 'SYS_TABLES' table in the
'InnoDB' data dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*INNODB_SYS_TABLES Columns*

Column name            Description

'TABLE_ID'             An identifier for each 'InnoDB' table that is unique
                       across all databases in the instance.

'NAME'                 The name of the table.  Preceded by the database name
                       where appropriate, for example 'test/t1'.  Names of
                       databases and user tables are in the same case as they
                       were originally defined, possibly influenced by the
                       'lower_case_table_names' setting.

'FLAG'                 Bit-level data about table format and storage
                       characteristics including row format, compressed page
                       size (if applicable), and whether or not the 'DATA
                       DIRECTORY' clause was used with 'CREATE TABLE'
                       or 'ALTER TABLE'.

'N_COLS'               The number of columns in the table.  The number reported
                       includes three hidden columns that are created by
                       'InnoDB' ('DB_ROW_ID', 'DB_TRX_ID', and 'DB_ROLL_PTR').
                       The number reported also includes virtual generated
                       columns, if present.

'SPACE'                An identifier for the tablespace where the table
                       resides.  0 means the 'InnoDB' system tablespace.  Any
                       other number represents either a file-per-table
                       tablespace or a general tablespace.  This identifier
                       stays the same after a 'TRUNCATE TABLE'
                       statement.  For file-per-table
                       tablespaces, this identifier is unique for tables across
                       all databases in the instance.

'FILE_FORMAT'          The table's file format (Antelope or Barracuda).

'ROW_FORMAT'           The table's row format (Compact, Redundant, Dynamic, or
                       Compressed).

'ZIP_PAGE_SIZE'        The zip page size.  Only applies to tables that use the
                       Compressed row format.

'SPACE_TYPE'           The type of tablespace to which the table belongs.
                       Possible values include 'System' for the system
                       tablespace, 'General' for general tablespaces, and
                       'Single' for file-per-table tablespaces.  Tables
                       assigned to the system tablespace using 'CREATE TABLE'
                       or 'ALTER TABLE'.
                       'TABLESPACE=innodb_system' have a 'General'
                       'SPACE_TYPE'.  For more information, see 'CREATE TABLESPACE'.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE TABLE_ID = 214\G
     *************************** 1. row ***************************
          TABLE_ID: 214
              NAME: test/t1
              FLAG: 129
            N_COLS: 4
             SPACE: 233
       FILE_FORMAT: Antelope
        ROW_FORMAT: Compact
     ZIP_PAGE_SIZE: 0
        SPACE_TYPE: General

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

*Interpreting the INNODB_SYS_TABLES.FLAG Column Value*:

The 'INNODB_SYS_TABLES.FLAG' column provides bit-level information about
the table's format and storage characteristics.  You can interpret the
'FLAG' column value by adding together the applicable decimal numeric
values that are provided in the following table.

*Bit Position Values for Interpreting INNODB_SYS_TABLES FLAG Column
Data*

Bit Position   Description                   Decimal Numeric Value

0              This bit is set if the row
               format is not 'REDUNDANT'.       * 0 - 'REDUNDANT'
               In other words, it is set
               if the row format is             * 1 - 'COMPACT',
               'COMPACT', 'DYNAMIC' or            'DYNAMIC' or
               'COMPRESSED'.                      'COMPRESSED'

1-4            These four bits contain a
               small number that                * 0 - Not Compressed
               represents the compressed
               page size of the table.          * 2 - 1024 Byte
               The                                Compressed Page Size
               'INNODB_SYS_TABLES.ZIP_PAGE_SIZE'
               field also reports the           * 4 - 2048 Byte
               compressed page size, if           Compressed Page Size
               applicable.
                                                * 6 - 4096 Byte
                                                  Compressed Page Size

                                                * 8 - 8192 Byte
                                                  Compressed Page Size

                                                * 10 - 16384 Byte
                                                  Compressed Page Size

5              This bit is set if the row
               format is 'DYNAMIC' or           * 0 - 'REDUNDANT' or
               'COMPRESSED'.                      'COMPACT'

                                                * 32 - 'DYNAMIC' or
                                                  'COMPRESSED'

6              This bit is set if the
               'DATA DIRECTORY' option is       * 0 - Not a remote
               used with 'CREATE file-per-table TABLE'
               or           tablespace
               'ALTER TABLE'.
               This bit is        * 64 - A remote
               set for file-per-table             file-per-table
               tablespaces that are               tablespace
               located in directories
               other than the default data
               directory ('datadir').  For
               these tables, a
               'TABLENAME.isl' file is
               present in the same
               location as the
               'TABLENAME.frm' file.  The
               'TABLENAME.isl' file stores
               the actual directory path
               to the 'TABLENAME.ibd'
               file-per-table tablespace
               file.

7              This bit is set if the
               table is assigned to a           * 0 - Table is located
               shared tablespace (either a        in a default location
               general tablespace or a            depending on the value
               system tablespace) using           of the
               the 'CREATE TABLE'.
               create-table. or
               'ALTER TABLE'.      * 128 - The table is
               'TABLESPACE=TABLESPACE_NAME'       explicitly assigned to
               option.                            a shared tablespace.

In the following, table 't1' uses 'ROW_FORMAT=DYNAMIC' and has a 'FLAG'
value of 33.  Based on the information in the preceding table, we can
see that bit position 0 would be set to 1, and bit position 5 would be
set to 32 for a table with a 'DYNAMIC' row format.  These values add up
to a 'FLAG' value of 33.

     mysql> USE test;
     Database changed

     mysql> SET GLOBAL innodb_file_format=Barracuda;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t1 (c1 int) ROW_FORMAT=DYNAMIC;
     Query OK, 0 rows affected (0.02 sec)

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME LIKE 'test/t1'\G
     *************************** 1. row ***************************
          TABLE_ID: 89
              NAME: test/t1
              FLAG: 33
            N_COLS: 4
             SPACE: 75
       FILE_FORMAT: Barracuda
        ROW_FORMAT: Dynamic
     ZIP_PAGE_SIZE: 0
     1 row in set (0.00 sec)

24.31.23 The INFORMATION_SCHEMA INNODB_SYS_TABLESPACES Table
------------------------------------------------------------

The 'INNODB_SYS_TABLESPACES' table provides metadata about 'InnoDB'
file-per-table and general tablespaces, equivalent to the information in
the 'SYS_TABLESPACES' table in the 'InnoDB' data dictionary.

For related usage information and examples, see
innodb-information-schema-system-tables.

*Note*:

The 'INFORMATION_SCHEMA.FILES' table reports
metadata for all 'InnoDB' tablespace types including file-per-table
tablespaces, general tablespaces, the system tablespace, the temporary
tablespace, and undo tablespaces, if present.

*INNODB_SYS_TABLESPACES Columns*

Column name            Description

'SPACE'                Tablespace Space ID.

'NAME'                 The database and table name.

'FLAG'                 Bit-level data about tablespace format and storage
                       characteristics.

'FILE_FORMAT'          The tablespace file format.  For example, Antelope,
                       Barracuda, or 'Any' (general tablespaces support any row
                       format).  The data in this field is interpreted from the
                       tablespace flags information that resides in the .ibd
                       file.  For more information about 'InnoDB' file formats,
                       see innodb-file-format.

'ROW_FORMAT'           The tablespace row format (Compact or Redundant,
                       Dynamic, or Compressed).  The data in this field is
                       interpreted from the tablespace flags information that
                       resides in the .ibd file.

'PAGE_SIZE'            The tablespace page size.  The data in this field is
                       interpreted from the tablespace flags information that
                       resides in the .ibd file.

'ZIP_PAGE_SIZE'        The tablespace zip page size.  The data in this field is
                       interpreted from the tablespace flags information that
                       resides in the .ibd file.

'SPACE_TYPE'           The type of tablespace.  Possible values include
                       'General' for general tablespaces and 'Single' for
                       file-per-table tablespaces.

'FS_BLOCK_SIZE'        The file system block size, which is the unit size used
                       for hole punching.  This column was added with the
                       introduction of the 'InnoDB' transparent page compression
                       feature.

'FILE_SIZE'            The apparent size of the file, which represents the
                       maximum size of the file, uncompressed.  This column was
                       added with the introduction of the 'InnoDB'
                       transparent page compression.
                       feature.

'ALLOCATED_SIZE'       The actual size of the file, which is the amount of
                       space allocated on disk.  This column was added with the
                       introduction of the 'InnoDB' transparent page compression
                       feature.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES WHERE SPACE = 26\G
     *************************** 1. row ***************************
              SPACE: 26
               NAME: test/t1
               FLAG: 0
        FILE_FORMAT: Antelope
         ROW_FORMAT: Compact or Redundant
          PAGE_SIZE: 16384
      ZIP_PAGE_SIZE: 0
         SPACE_TYPE: Single
      FS_BLOCK_SIZE: 4096
          FILE_SIZE: 98304
     ALLOCATED_SIZE: 65536

*Notes*:

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * Because tablespace flags are always zero for all Antelope file
     formats (unlike table flags), there is no way to determine from
     this flag integer if the tablespace row format is Redundant or
     Compact.  As a result, the possible values for the 'ROW_FORMAT'
     field are 'Compact or Redundant', 'Compressed', or 'Dynamic.'

   * With the introduction of general tablespaces, 'InnoDB' system
     tablespace data (for SPACE 0) is exposed in
     'INNODB_SYS_TABLESPACES'.

*Interpreting the INNODB_SYS_TABLESPACES.FLAG Column Value*:

The 'INNODB_SYS_TABLESPACES.FLAG' column provides bit-level information
about tablespace format and storage characteristics.

Until MySQL 5.6, table and tablespace flags were the same except for the
bit position 0 settings.  In MySQL 5.6, support was added for 4K and 8K
pages, which required an additional 4 bits to hold the logical page
size.  Also in MySQL 5.6, support was added for the 'CREATE TABLE'
and 'ALTER TABLE'. 'DATA
DIRECTORY' clause, which allows file-per-table tablespaces to be stored
in a location outside of the MySQL data directory.  This feature
required an additional bit for both table and tablespace flags, but not
at the same position.

You can interpret the tablespace 'FLAG' column value by adding together
the applicable decimal numeric values that are provided in the following
table.

*Bit Position Values for Interpreting INNODB_SYS_TABLESPACES FLAG Column
Data*

Bit Position   Description                          Decimal Numeric
                                                    Value

0              This bit is set if the row format
               of tables in the tablespace is          * 0 - 'REDUNDANT'
               'DYNAMIC' or 'COMPRESSED'.  This          or 'COMPACT'
               information can help you                  ('FILE_FORMAT=Antelope')
               distinguish between Antelope and
               Barracuda file formats but not          * 1 - 'DYNAMIC'
               between 'REDUNDANT' and 'COMPACT'         or 'COMPRESSED'
               file formats ('DYNAMIC' and               ('FILE_FORMAT=Barracuda')
               'COMPRESSED' row formats require
               the Barracuda file format).  If it
               is a file-per-table tablespace,
               you must query 'INNODB_SYS_TABLES'
               to determine which of the two
               Antelope row formats is used
               ('REDUNDANT' or 'COMPACT').

1-4            These four bits contain a small
               number that represents the              * 0 - Not
               compressed page size (the                 Compressed
               'KEY_BLOCK_SIZE' or 'physical
               block size') of the tablespace.         * 2 - 1024 Byte
                                                         Compressed Page
                                                         Size

                                                       * 4 - 2048 Byte
                                                         Compressed Page
                                                         Size

                                                       * 6 - 4096 Byte
                                                         Compressed Page
                                                         Size

                                                       * 8 - 8192 Byte
                                                         Compressed Page
                                                         Size

                                                       * 10 - 16384 Byte
                                                         Compressed Page
                                                         Size

                                                       * 12 - 32768 Byte
                                                         Compressed Page
                                                         Size

                                                       * 14 - 65536 Byte
                                                         Compressed Page
                                                         Size

5              This bit is set for file-per-table
               tablespaces if the row format of        * 0 - 'REDUNDANT'
               the table is 'DYNAMIC' or                 or 'COMPACT'
               'COMPRESSED'.  General tablespaces
               that do not contain compressed          * 32 - 'DYNAMIC'
               tables will have the first 6 bits         or 'COMPRESSED'
               set to zero, including this bit,
               making it appear to be the
               Antelope file format.  But
               actually, general tablespaces may
               contain any combination of
               'REDUNDANT', 'COMPACT' and
               'DYNAMIC' tables.  For more
               information about general
               tablespaces, see 'CREATE TABLESPACE'.

6-9            These four bits contain a small
               number that represents the              * 192 - 4096 Byte
               uncompressed page size (logical           Logical/Uncompressed
               page size) of the tablespace.  The        Page Size
               setting is zero if the logical
               page size is the original 'InnoDB'      * 256 - 8192 Byte
               default page size of 16K.                 Logical/Uncompressed
                                                         Page Size

                                                       * 0 - 16384 Byte
                                                         Logical/Uncompressed
                                                         Page size

                                                       * 384 - 32768
                                                         Byte
                                                         Logical/Uncompressed
                                                         Page Size

                                                       * 448 - 65536
                                                         Byte
                                                         Logical/Uncompressed
                                                         Page Size

10             This bit is set if the 'DATA
               DIRECTORY' option is used with          * 0 - Not a
               'CREATE TABLE'
               or 'ALTER file-per-table TABLE'.
               This bit is         tablespace
               set for file-per-table tablespaces
               that are located in directories         * 1024 - A remote
               other than the default data               file-per-table
               directory ('datadir').  For these         tablespace
               tables, a 'TABLENAME.isl' file is
               present in the same location as
               the 'TABLENAME.frm' file.  The
               'TABLENAME.isl' file stores the
               actual directory path to the
               'TABLENAME.ibd' file-per-table
               tablespace file.

11             This bit is set if the tablespace
               is a shared general tablespace          * 0 - Table is
               created using 'CREATE located in a TABLESPACE'.
                  default
                                                         location
                                                         depending on
                                                         the value of
                                                         the
                                                         'innodb_file_per_table'
                                                         setting.

                                                       * 2048 - The
                                                         table was
                                                         explicitly
                                                         assigned to a
                                                         shared
                                                         tablespace.

12             This bit is set if the tablespace
               is dedicated to temporary tables.       * 0 - The
               In MySQL 5.7, only the predefined         tablespace does
               'ibtmp1' tablespace uses this             not contain
               flag.                                     temporary
                                                         tables, so it
                                                         is not
                                                         recreated upon
                                                         startup.

                                                       * 4096 - The
                                                         tablespace
                                                         contains
                                                         temporary
                                                         tables and is
                                                         recreated on
                                                         startup.

In the following example, table 't1' is created with
'innodb_file_per_table=ON', which creates table 't1' in its own
tablespace.  When querying 'INNODB_SYS_TABLESPACES',
we see that the tablespace has a 'FLAG'
value of 33.  To determine how this value is arrived at, review the bit
values described in the preceding table.  Bit 0 has a value of 1 because
table 't1' uses the 'DYNAMIC' row format.  Bit 5 has a value of 32
because the tablespace is a file-per-table tablespace that uses a
'DYNAMIC' row format.  Bit position 6-9 is 0 because 'innodb_page_size'
is set to the default 16K value.  The other bit values are not
applicable and are therefore set to 0.  The values for bit position 0
and bit position 5 add up to a 'FLAG' value of 33.

     mysql> USE test;
     Database changed

     mysql> SHOW VARIABLES LIKE 'innodb_file_per_table';
     +-----------------------+-------+
     | Variable_name         | Value |
     +-----------------------+-------+
     | innodb_file_per_table | ON    |
     +-----------------------+-------+
     1 row in set (0.00 sec)

     mysql> SHOW VARIABLES LIKE 'innodb_page_size';
     +------------------+-------+
     | Variable_name    | Value |
     +------------------+-------+
     | innodb_page_size | 16384 |
     +------------------+-------+
     1 row in set (0.00 sec)

     mysql> SET GLOBAL innodb_file_format=Barracuda;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CREATE TABLE t1 (c1 int) ROW_FORMAT=DYNAMIC;
     Query OK, 0 rows affected (0.02 sec)

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES WHERE NAME LIKE 'test/t1'\G
     *************************** 1. row ***************************
             SPACE: 75
              NAME: test/t1
              FLAG: 33
       FILE_FORMAT: Barracuda
        ROW_FORMAT: Dynamic
         PAGE_SIZE: 16384
     ZIP_PAGE_SIZE: 0
     1 row in set (0.00 sec)

24.31.24 The INFORMATION_SCHEMA INNODB_SYS_TABLESTATS View
----------------------------------------------------------

The 'INNODB_SYS_TABLESTATS' provides a view of low-level status
information about 'InnoDB' tables.  This data is used by the MySQL
optimizer to calculate which index to use when querying an 'InnoDB'
table.  This information is derived from in-memory data structures
rather than corresponding to data stored on disk.  There is no
corresponding internal 'InnoDB' system table.

'InnoDB' tables are represented in this view if they have been opened
since the last server restart, and not aged out of the table cache.
Tables for which persistent stats are available are always represented
in this view.

Table statistics are only updated for 'DELETE' or
'UPDATE' operations that modify indexed columns.  Statistics
are not updated by operations that only modify non-indexed columns.

For related usage information and examples, see
innodb-information-schema-system-tables.

*INNODB_SYS_TABLESTATS Columns*

Column name            Description

'TABLE_ID'             An identifier representing the table for which
                       statistics are available, using the same value as
                       'INNODB_SYS_TABLES.TABLE_ID'.

'NAME'                 The name of the table, using the same value as
                       'INNODB_SYS_TABLES.NAME'.

'STATS_INITIALIZED'    The value is 'Initialized' if the statistics are already
                       collected, 'Uninitialized' if not.

'NUM_ROWS'             The current estimated number of rows in the table.
                       Updated after each DML operation.  Could be imprecise if
                       uncommitted transactions are inserting into or deleting
                       from the table.

'CLUST_INDEX_SIZE'     Number of pages on disk that store the clustered index,
                       which holds the 'InnoDB' table data in primary key
                       order.  This value might be null if no statistics are
                       collected yet for the table.

'OTHER_INDEX_SIZE'     Number of pages on disk that store all secondary indexes
                       for the table.  This value might be null if no
                       statistics are collected yet for the table.

'MODIFIED_COUNTER'     The number of rows modified by DML operations, such as
                       'INSERT', 'UPDATE', 'DELETE', and also cascade
                       operations from foreign keys.  This column is reset each
                       time table statistics are recalculated

'AUTOINC'              The next number to be issued for any
                       auto-increment-based operation.  The rate at which the
                       'AUTOINC' value changes depends on how many times
                       auto-increment numbers have been requested and how many
                       numbers are granted per request.

'REF_COUNT'            When this counter reaches zero, the table metadata can
                       be evicted from the table cache.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_TABLESTATS where TABLE_ID = 71\G
     *************************** 1. row ***************************
              TABLE_ID: 71
                  NAME: test/t1
     STATS_INITIALIZED: Initialized
              NUM_ROWS: 1
      CLUST_INDEX_SIZE: 1
      OTHER_INDEX_SIZE: 0
      MODIFIED_COUNTER: 1
               AUTOINC: 0
             REF_COUNT: 1

*Notes*:

   * This table is primarily useful for expert-level performance
     monitoring, or when developing performance-related extensions for
     MySQL.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.25 The INFORMATION_SCHEMA INNODB_SYS_VIRTUAL Table
--------------------------------------------------------

The 'INNODB_SYS_VIRTUAL' table provides metadata about 'InnoDB' virtual
generated columns and columns upon which virtual generated columns are
based, equivalent to information in the 'SYS_VIRTUAL' table in the
'InnoDB' data dictionary.

A row appears in the 'INNODB_SYS_VIRTUAL' table for each column upon
which a virtual generated column is based.

*INNODB_SYS_VIRTUAL Columns*

Column name            Description

'TABLE_ID'             An identifier representing the table associated with the
                       virtual column; the same value as
                       'INNODB_SYS_TABLES.TABLE_ID'.

'POS'                  The position value of the virtual generated column.  The
                       value is large because it encodes the column sequence
                       number and ordinal position.  The formula used to
                       calculate the value uses a bitwise operation.  The
                       formula is '((nth virtual generated column for the
                       InnoDB instance + 1) << 16) + the ordinal position of
                       the virtual generated column'.  For example, if the
                       first virtual generated column in the 'InnoDB' instance
                       is the third column of the table, the formula is (0 + 1)
                       << 16) + 2.  The first virtual generated column in the
                       'InnoDB' instance is always number 0.  As the third
                       column in the table, the ordinal position of the virtual
                       generated column is 2.  Ordinal positions are counted
                       from 0.

'BASE_POS'             The ordinal position of the columns upon which a virtual
                       generated column is based.

*Example*:

     mysql> CREATE TABLE `t1` (
              `a` int(11) DEFAULT NULL,
              `b` int(11) DEFAULT NULL,
              `c` int(11) GENERATED ALWAYS AS (a+b) VIRTUAL,
              `h` varchar(10) DEFAULT NULL
            ) ENGINE=InnoDB DEFAULT CHARSET=latin1;
     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_SYS_VIRTUAL
            WHERE TABLE_ID IN (SELECT TABLE_ID FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME LIKE "test/t1");
     +----------+-------+----------+
     | TABLE_ID | POS   | BASE_POS |
     +----------+-------+----------+
     |       95 | 65538 |        0 |
     |       95 | 65538 |        1 |
     +----------+-------+----------+

*Notes*:

   * If a constant value is assigned to a virtual generated column, as
     in the following example, an entry for the column does not appear
     in the 'INNODB_SYS_VIRTUAL' table.  For an entry to appear, a
     virtual generated column must have a base column.

          mysql> CREATE TABLE `t1` (
                   `a` int(11) DEFAULT NULL,
                   `b` int(11) DEFAULT NULL,
                   `c` int(11) GENERATED ALWAYS AS (5) VIRTUAL
                 ) ENGINE=InnoDB DEFAULT CHARSET=latin1;

     However, metadata for such a column appears in the
     'INNODB_SYS_COLUMNS' table.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.26 The INFORMATION_SCHEMA INNODB_TEMP_TABLE_INFO Table
------------------------------------------------------------

'INNODB_TEMP_TABLE_INFO' provides information about user-created
'InnoDB' temporary tables that are currently active within the 'InnoDB'
instance.  It does not provide information about internal 'InnoDB'
temporary tables that are used by the optimizer.  The
'INNODB_TEMP_TABLE_INFO' table is created when it is first queried and
only exists in memory.  It is not persisted to disk.

For usage information and examples, see
innodb-information-schema-temp-table-info.

*INNODB_TEMP_TABLE_INFO Columns*

Column name            Description

'TABLE_ID'             The table ID of the active temporary table.

'NAME'                 The name of the active temporary table.

'N_COLS'               The number of columns in the temporary table.  The
                       number always includes three hidden columns created by
                       'InnoDB' (DB_ROW_ID, DB_TRX_ID, and DB_ROLL_PTR).

'SPACE'                The tablespace identifier (a numerical value) for the
                       tablespace where the temporary table resides.  In 5.7,
                       all non-compressed 'InnoDB' temporary tables reside in a
                       shared temporary tablespace.  The data file for the
                       shared temporary tablespace is defined by the
                       'innodb_temp_data_file_path' configuration option.  By
                       default, there is a single data file for the shared
                       temporary tablespace named 'ibtmp1', which is located in
                       the 'data' directory.  Compressed temporary tables
                       reside in separate file-per-table tablespaces located in
                       the temporary file directory, as defined by 'tmpdir'.
                       The 'SPACE' ID for the temporary tablespace is always a
                       nonzero value and is dynamically generated on server
                       restart.

'PER_TABLE_SPACE'      A value of 'TRUE' indicates that the temporary table
                       resides in a separate file-per-table tablespace.  A
                       value of 'FALSE' indicates that the temporary table
                       resides in the shared temporary tablespace.

'IS_COMPRESSED'        A value of 'TRUE' indicates that the temporary table is
                       compressed.

*Example*:

     mysql> CREATE TEMPORARY TABLE t1 (c1 INT PRIMARY KEY) ENGINE=INNODB;
     Query OK, 0 rows affected (0.01 sec)

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_TEMP_TABLE_INFO\G
     *************************** 1. row ***************************
                 TABLE_ID: 38
                     NAME: #sql26cf_6_0
                   N_COLS: 4
                    SPACE: 52
     PER_TABLE_TABLESPACE: FALSE
            IS_COMPRESSED: FALSE
     1 row in set (0.00 sec)

*Notes*:

   * This table is primarily useful for expert level monitoring.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

24.31.27 The INFORMATION_SCHEMA INNODB_TRX Table
------------------------------------------------

The 'INNODB_TRX' table contains information about every transaction
(excluding read-only transactions) currently executing inside 'InnoDB',
including whether the transaction is waiting for a lock, when the
transaction started, and the SQL statement the transaction is executing,
if any.

*INNODB_TRX Columns*

Column  Description
name

'TRX_ID'Unique
        transaction
        ID number,
        internal to
        'InnoDB'.
        These IDs
        are not
        created for
        transactions
        that are
        read only
        and
        nonlocking.
        See
        innodb-performance-ro-txn
        for details.

'TRX_WEIGHT'The weight
        of a
        transaction,
        reflecting
        (but not
        necessarily
        the exact
        count of)
        the number
        of rows
        altered and
        the number
        of rows
        locked by
        the
        transaction.
        To resolve a
        deadlock,
        'InnoDB'
        selects the
        transaction
        with the
        smallest
        weight as
        the 'victim'
        to roll
        back.
        Transactions
        that have
        changed
        non-transactional
        tables are
        considered
        heavier than
        others,
        regardless
        of the
        number of
        altered and
        locked rows.

'TRX_STATE'Transaction
        execution
        state.
        Permitted
        values are
        'RUNNING',
        'LOCK WAIT',
        'ROLLING
        BACK', and
        'COMMITTING'.

'TRX_STARTED'Transaction
        start time.

'TRX_REQUESTED_LOCK_ID'ID of the
        lock the
        transaction
        is currently
        waiting for,
        if
        'TRX_STATE'
        is 'LOCK
        WAIT';
        otherwise
        'NULL'.  To
        obtain
        details
        about the
        lock, join
        this column
        with the
        'LOCK_ID'
        column of
        the
        'INNODB_LOCKS'.
        table.

'TRX_WAIT_STARTED'Time when
        the
        transaction
        started
        waiting on
        the lock, if
        'TRX_STATE'
        is 'LOCK
        WAIT';
        otherwise
        'NULL'.

'TRX_MYSQL_THREAD_ID'MySQL thread
        ID. To
        obtain
        details
        about the
        thread, join
        this column
        with the
        'ID' column
        of the
        'INFORMATION_SCHEMA'

        'PROCESSLIST'.
        table, but
        see
        innodb-information-schema-internal-data.

'TRX_QUERY'The SQL
        statement
        that is
        being
        executed by
        the
        transaction.

'TRX_OPERATION_STATE'The
        transaction's
        current
        operation,
        if any;
        otherwise
        'NULL'.

'TRX_TABLES_IN_USE'The number
        of 'InnoDB'
        tables used
        while
        processing
        the current
        SQL
        statement of
        this
        transaction.

'TRX_TABLES_LOCKED'Number of
        'InnoDB'
        tables that
        the current
        SQL
        statement
        has row
        locks on.
        (Because
        these are
        row locks,
        not table
        locks, the
        tables can
        usually
        still be
        read from
        and written
        to by
        multiple
        transactions,
        despite some
        rows being
        locked.)

'TRX_LOCK_STRUCTS'The number
        of locks
        reserved by
        the
        transaction.

'TRX_LOCK_MEMORY_BYTES'Total size
        taken up by
        the lock
        structures
        of this
        transaction
        in memory.

'TRX_ROWS_LOCKED'Approximate
        number or
        rows locked
        by this
        transaction.
        The value
        might
        include
        delete-marked
        rows that
        are
        physically
        present but
        not visible
        to the
        transaction.

'TRX_ROWS_MODIFIED'The number
        of modified
        and inserted
        rows in this
        transaction.

'TRX_CONCURRENCY_TICKETS'A value
        indicating
        how much
        work the
        current
        transaction
        can do
        before being
        swapped out,
        as specified
        by the
        'innodb_concurrency_tickets'
        system
        variable.

'TRX_ISOLATION_LEVEL'The
        isolation
        level of the
        current
        transaction.

'TRX_UNIQUE_CHECKS'Whether
        unique
        checks are
        turned on or
        off for the
        current
        transaction.
        For example,
        they might
        be turned
        off during a
        bulk data
        load.

'TRX_FOREIGN_KEY_CHECKS'Whether
        foreign key
        checks are
        turned on or
        off for the
        current
        transaction.
        For example,
        they might
        be turned
        off during a
        bulk data
        load.

'TRX_LAST_FOREIGN_KEY_ERROR'Detailed
        error
        message for
        the last
        foreign key
        error, if
        any;
        otherwise
        'NULL'.

'TRX_ADAPTIVE_HASH_LATCHED'Whether the
        adaptive
        hash index
        is locked by
        the current
        transaction.
        When the
        adaptive
        hash index
        search
        system is
        partitioned,
        a single
        transaction
        does not
        lock the
        entire
        adaptive
        hash index.
        Adaptive
        hash index
        partitioning
        is
        controlled
        by
        'innodb_adaptive_hash_index_parts',
        which is set
        to 8 by
        default.

'TRX_ADAPTIVE_HASH_TIMEOUT'Whether to
        relinquish
        the search
        latch
        immediately
        for the
        adaptive
        hash index,
        or reserve
        it across
        calls from
        MySQL. When
        there is no
        adaptive
        hash index
        contention,
        this value
        remains zero
        and
        statements
        reserve the
        latch until
        they finish.
        During times
        of
        contention,
        it counts
        down to
        zero, and
        statements
        release the
        latch
        immediately
        after each
        row lookup.
        When the
        adaptive
        hash index
        search
        system is
        partitioned
        (controlled
        by
        'innodb_adaptive_hash_index_parts'),
        the value
        remains 0.

'TRX_IS_READ_ONLY'A value of 1
        indicates
        the
        transaction
        is read
        only.

'TRX_AUTOCOMMIT_NON_LOCKING'A value of 1
        indicates
        the
        transaction
        is a
        'SELECT'.
        statement
        that does
        not use the
        'FOR UPDATE'
        or 'LOCK IN
        SHARED MODE'
        clauses, and
        is executing
        with
        'autocommit'
        enabled so
        that the
        transaction
        will only
        contain this
        one
        statement.
        When this
        column and
        'TRX_IS_READ_ONLY'
        are both 1,
        'InnoDB'
        optimizes
        the
        transaction
        to reduce
        the overhead
        associated
        with
        transactions
        that change
        table data.

*Example*:

     mysql> SELECT * FROM INFORMATION_SCHEMA.INNODB_TRX\G
     *************************** 1. row ***************************
                         trx_id: 1510
                      trx_state: RUNNING
                    trx_started: 2014-11-19 13:24:40
          trx_requested_lock_id: NULL
               trx_wait_started: NULL
                     trx_weight: 586739
            trx_mysql_thread_id: 2
                      trx_query: DELETE FROM employees.salaries WHERE salary > 65000
            trx_operation_state: updating or deleting
              trx_tables_in_use: 1
              trx_tables_locked: 1
               trx_lock_structs: 3003
          trx_lock_memory_bytes: 450768
                trx_rows_locked: 1407513
              trx_rows_modified: 583736
        trx_concurrency_tickets: 0
            trx_isolation_level: REPEATABLE READ
              trx_unique_checks: 1
         trx_foreign_key_checks: 1
     trx_last_foreign_key_error: NULL
      trx_adaptive_hash_latched: 0
      trx_adaptive_hash_timeout: 10000
               trx_is_read_only: 0
     trx_autocommit_non_locking: 0

*Notes*:

   * Use this table to help diagnose performance problems that occur
     during times of heavy concurrent load.  Its contents are updated as
     described in innodb-information-schema-internal-data.

   * Use 'DESCRIBE' or 'SHOW COLUMNS'
     to view additional information about the columns of
     this table including data types and default values.

   * You must have the 'PROCESS' privilege to query this table.

   * For usage information, see
     innodb-information-schema-examples.

24.32 Thread Pool INFORMATION_SCHEMA Tables
===========================================

The following sections describe the 'INFORMATION_SCHEMA' tables
associated with the thread pool plugin.  They provide information about
thread pool operation:

   * 'TP_THREAD_GROUP_STATE'.:
     Information about thread pool thread group states

   * 'TP_THREAD_GROUP_STATS'.: Thread
     group statistics

   * 'TP_THREAD_STATE'.: Information about
     thread pool thread states

Rows in these tables represent snapshots in time.  In the case of
'TP_THREAD_STATE', all rows for a thread group
comprise a snapshot in time.  Thus, the MySQL server holds the mutex of
the thread group while producing the snapshot.  But it does not hold
mutexes on all thread groups at the same time, to prevent a statement
against 'TP_THREAD_STATE' from blocking
the entire MySQL server.

The thread pool 'INFORMATION_SCHEMA' tables are implemented by
individual plugins and the decision whether to load one can be made
independently of the others (see thread-pool-installation).
However, the content of all the tables depends on the thread pool plugin
being enabled.  If a table plugin is enabled but the thread pool plugin
is not, the table becomes visible and can be accessed but will be empty.

24.32.1 The INFORMATION_SCHEMA TP_THREAD_GROUP_STATE Table
----------------------------------------------------------

This table has one row per thread group in the thread pool.  Each row
provides information about the current state of a group.  The table has
these columns:

   * 'TP_GROUP_ID'

     The thread group ID. This is a unique key within the table.

   * 'CONSUMER THREADS'

     The number of consumer threads.  There is at most one thread ready
     to start executing if the active threads become stalled or blocked.

   * 'RESERVE_THREADS'

     The number of threads in the reserved state.  This means that they
     will not be started until there is a need to wake a new thread and
     there is no consumer thread.  This is where most threads end up
     when the thread group has created more threads than needed for
     normal operation.  Often a thread group needs additional threads
     for a short while and then does not need them again for a while.
     In this case, they go into the reserved state and remain until
     needed again.  They take up some extra memory resources, but no
     extra computing resources.

   * 'CONNECT_THREAD_COUNT'

     The number of threads that are processing or waiting to process
     connection initialization and authentication.  There can be a
     maximum of four connection threads per thread group; these threads
     expire after a period of inactivity.

     This column was added in MySQL 5.7.18.

   * 'CONNECTION_COUNT'

     The number of connections using this thread group.

   * 'QUEUED_QUERIES'

     The number of statements waiting in the high-priority queue.

   * 'QUEUED_TRANSACTIONS'

     The number of statements waiting in the low-priority queue.  These
     are the initial statements for transactions that have not started,
     so they also represent queued transactions.

   * 'STALL_LIMIT'

     The value of the 'thread_pool_stall_limit' variable on the thread
     group.  This is the same value for all thread groups.

   * 'PRIO_KICKUP_TIMER'

     The value of the 'thread_pool_prio_kickup_timer' on the thread
     group.  This is the same value for all thread groups.

   * 'ALGORITHM'

     The value of the 'thread_pool_algorithm' on the thread group.  This
     is the same value for all thread groups.

   * 'THREAD_COUNT'

     The number of threads started in the thread pool as part of this
     thread group.

   * 'ACTIVE_THREAD_COUNT'

     The number of threads active executing statements.

   * 'MAX_THREAD_IDS_IN_GROUP'

     The maximum thread ID of the threads in the group.  This is the
     same as 'MAX(TP_THREAD_NUMBER)' for the threads when selected from
     the 'TP_THREAD_GROUP_STATE'.
     table.  That is, these two queries are equivalent:

          SELECT TP_GROUP_ID, MAX_THREAD_IDS_IN_GROUP
          FROM TP_THREAD_GROUP_STATE;

          SELECT TP_GROUP_ID, MAX(TP_THREAD_NUMBER)
          FROM TP_THREAD_STATE GROUP BY TP_GROUP_ID;

   * 'STALLED_THREAD_COUNT'

     The number of stalled statements in the thread group.  A stalled
     statement could be executing, but from a thread pool perspective it
     is stalled and making no progress.  A long-running statement
     quickly ends up in this category.

   * 'WAITING_THREAD_NUMBER'

     If there is a thread handling the polling of statements in the
     thread group, this specifies the thread number within this thread
     group.  It is possible that this thread could be executing a
     statement.

   * 'OLDEST_QUEUED'

     How long in milliseconds the oldest queued statement has been
     waiting for execution.

24.32.2 The INFORMATION_SCHEMA TP_THREAD_GROUP_STATS Table
----------------------------------------------------------

This table reports statistics per thread group.  There is one row per
group.  The table has these columns:

   * 'TP_GROUP_ID'

     The thread group ID. This is a unique key within the table.

   * 'CONNECTIONS_STARTED'

     The number of connections started.

   * 'CONNECTIONS_CLOSED'

     The number of connections closed.

   * 'QUERIES_EXECUTED'

     The number of statements executed.  This number is incremented when
     a statement starts executing, not when it finishes.

   * 'QUERIES_QUEUED'

     The number of statements received that were queued for execution.
     This does not count statements that the thread group was able to
     begin executing immediately without queuing, which can happen under
     the conditions described in thread-pool-operation.

   * 'THREADS_STARTED'

     The number of threads started.

   * 'PRIO_KICKUPS'

     The number of statements that have been moved from low-priority
     queue to high-priority queue based on the value of the
     'thread_pool_prio_kickup_timer' system variable.  If this number
     increases quickly, consider increasing the value of that variable.
     A quickly increasing counter means that the priority system is not
     keeping transactions from starting too early.  For 'InnoDB',
     this most likely means deteriorating
     performance due to too many concurrent transactions..

   * 'STALLED_QUERIES_EXECUTED'

     The number of statements that have become defined as stalled due to
     executing for a time longer than the value of the
     'thread_pool_stall_limit' system variable.

   * 'BECOME_CONSUMER_THREAD'

     The number of times thread have been assigned the consumer thread
     role.

   * 'BECOME_RESERVE_THREAD'

     The number of times threads have been assigned the reserve thread
     role.

   * 'BECOME_WAITING_THREAD'

     The number of times threads have been assigned the waiter thread
     role.  When statements are queued, this happens very often, even in
     normal operation, so rapid increases in this value are normal in
     the case of a highly loaded system where statements are queued up.

   * 'WAKE_THREAD_STALL_CHECKER'

     The number of times the stall check thread decided to wake or
     create a thread to possibly handle some statements or take care of
     the waiter thread role.

   * 'SLEEP_WAITS'

     The number of 'THD_WAIT_SLEEP' waits.  These occur when threads go
     to sleep; for example, by calling the 'SLEEP()' function.

   * 'DISK_IO_WAITS'

     The number of 'THD_WAIT_DISKIO' waits.  These occur when threads
     perform disk I/O that is likely to not hit the file system cache.
     Such waits occur when the buffer pool reads and writes data to
     disk, not for normal reads from and writes to files.

   * 'ROW_LOCK_WAITS'

     The number of 'THD_WAIT_ROW_LOCK' waits for release of a row lock
     by another transaction.

   * 'GLOBAL_LOCK_WAITS'

     The number of 'THD_WAIT_GLOBAL_LOCK' waits for a global lock to be
     released.

   * 'META_DATA_LOCK_WAITS'

     The number of 'THD_WAIT_META_DATA_LOCK' waits for a metadata lock
     to be released.

   * 'TABLE_LOCK_WAITS'

     The number of 'THD_WAIT_TABLE_LOCK' waits for a table to be
     unlocked that the statement needs to access.

   * 'USER_LOCK_WAITS'

     The number of 'THD_WAIT_USER_LOCK' waits for a special lock
     constructed by the user thread.

   * 'BINLOG_WAITS'

     The number of 'THD_WAIT_BINLOG_WAITS' waits for the binary log to
     become free.

   * 'GROUP_COMMIT_WAITS'

     The number of 'THD_WAIT_GROUP_COMMIT' waits.  These occur when a
     group commit must wait for the other parties to complete their part
     of a transaction.

   * 'FSYNC_WAITS'

     The number of 'THD_WAIT_SYNC' waits for a file sync operation.

24.32.3 The INFORMATION_SCHEMA TP_THREAD_STATE Table
----------------------------------------------------

This table has one row per thread created by the thread pool to handle
connections.  The table has these columns:

   * 'TP_GROUP_ID'

     The thread group ID.

   * 'TP_THREAD_NUMBER'

     The ID of the thread within its thread group.  'TP_GROUP_ID' and
     'TP_THREAD_NUMBER' together provide a unique key within the table.

   * 'PROCESS_COUNT'

     The 10ms interval in which the statement that uses this thread is
     currently executing.  0 means no statement is executing, 1 means it
     is in the first 10ms, and so forth.

   * 'WAIT_TYPE'

     The type of wait for the thread.  'NULL' means the thread is not
     blocked.  Otherwise, the thread is blocked by a call to
     'thd_wait_begin()' and the value specifies the type of wait.  The
     'XXX_WAIT' columns of the 'TP_THREAD_GROUP_STATS'
     table accumulate counts for each wait
     type.

     The 'WAIT_TYPE' value is a string that describes the type of wait,
     as shown in the following table.

     *WAIT_TYPE Values*

     Wait Type                 Meaning

     'THD_WAIT_SLEEP'          Waiting for sleep

     'THD_WAIT_DISKIO'         Waiting for Disk IO

     'THD_WAIT_ROW_LOCK'       Waiting for row lock

     'THD_WAIT_GLOBAL_LOCK'    Waiting for global lock

     'THD_WAIT_META_DATA_LOCK' Waiting for metadata lock

     'THD_WAIT_TABLE_LOCK'     Waiting for table lock

     'THD_WAIT_USER_LOCK'      Waiting for user lock

     'THD_WAIT_BINLOG'         Waiting for binlog

     'THD_WAIT_GROUP_COMMIT'   Waiting for group commit

     'THD_WAIT_SYNC'           Waiting for fsync

24.33 Connection-Control INFORMATION_SCHEMA Tables
==================================================

The following sections describe the 'INFORMATION_SCHEMA' tables
associated with the 'CONNECTION_CONTROL' plugin.

24.33.1 The INFORMATION_SCHEMA CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS Table
-----------------------------------------------------------------------------

This table provides information about the current number of consecutive
failed connection attempts per client user/host combination.  The table
was added in MySQL 5.7.17.

'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS'
has these columns:

   * 'USERHOST'

     The user/host combination of a client that has failed connection
     attempts, in ''USER_NAME'@'HOST_NAME'' format.

   * 'FAILED_ATTEMPTS'

     The current number of consecutive failed connection attempts for
     the 'USERHOST' value.  This counts all failed attempts, regardless
     of whether they were delayed.  The number of attempts for which the
     server added a delay to its response is the difference between the
     'FAILED_ATTEMPTS' value and the
     'connection_control_failed_connections_threshold' system variable
     value.

*Notes*:

   * The 'CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS' plugin must be
     activated for this table to be available, and the
     'CONNECTION_CONTROL' plugin must be activated or the table contents
     will always be empty.  See connection-control.

   * The table contains rows only for clients that have had one or more
     consecutive failed connection attempts without a subsequent
     successful attempt.  When a client connects successfully, its
     failed-connection count is reset to zero and the server removes any
     row corresponding to the client.

   * Assigning a value to the
     'connection_control_failed_connections_threshold' system variable
     at runtime resets all accumulated failed-connection counters to
     zero, which causes the table to become empty.

24.34 Extensions to SHOW Statements
===================================

Some extensions to 'SHOW' statements accompany the
implementation of 'INFORMATION_SCHEMA':

   * 'SHOW' can be used to get information about the
     structure of 'INFORMATION_SCHEMA' itself.

   * Several 'SHOW' statements accept a 'WHERE' clause that
     provides more flexibility in specifying which rows to display.

'INFORMATION_SCHEMA' is an information database, so its name is included
in the output from 'SHOW DATABASES'.  Similarly,
see 'SHOW TABLES' can be used with 'INFORMATION_SCHEMA'
to obtain a list of its tables:

     mysql> SHOW TABLES FROM INFORMATION_SCHEMA;
     +---------------------------------------+
     | Tables_in_INFORMATION_SCHEMA          |
     +---------------------------------------+
     | CHARACTER_SETS                        |
     | COLLATIONS                            |
     | COLLATION_CHARACTER_SET_APPLICABILITY |
     | COLUMNS                               |
     | COLUMN_PRIVILEGES                     |
     | ENGINES                               |
     | EVENTS                                |
     | FILES                                 |
     | GLOBAL_STATUS                         |
     | GLOBAL_VARIABLES                      |
     | KEY_COLUMN_USAGE                      |
     | PARTITIONS                            |
     | PLUGINS                               |
     | PROCESSLIST                           |
     | REFERENTIAL_CONSTRAINTS               |
     | ROUTINES                              |
     | SCHEMATA                              |
     | SCHEMA_PRIVILEGES                     |
     | SESSION_STATUS                        |
     | SESSION_VARIABLES                     |
     | STATISTICS                            |
     | TABLES                                |
     | TABLE_CONSTRAINTS                     |
     | TABLE_PRIVILEGES                      |
     | TRIGGERS                              |
     | USER_PRIVILEGES                       |
     | VIEWS                                 |
     +---------------------------------------+

'SHOW COLUMNS' and 'DESCRIBE' can
display information about the columns in individual 'INFORMATION_SCHEMA'
tables.

'SHOW' statements that accept a 'LIKE' clause to limit the
rows displayed also permit a 'WHERE' clause that specifies more general
conditions that selected rows must satisfy:

     SHOW CHARACTER SET
     SHOW COLLATION
     SHOW COLUMNS
     SHOW DATABASES
     SHOW FUNCTION STATUS
     SHOW INDEX
     SHOW OPEN TABLES
     SHOW PROCEDURE STATUS
     SHOW STATUS
     SHOW TABLE STATUS
     SHOW TABLES
     SHOW TRIGGERS
     SHOW VARIABLES

The 'WHERE' clause, if present, is evaluated against the column names
displayed by the 'SHOW' statement.  For example, the
'SHOW CHARACTER SET' statement produces these
output columns:

     mysql> SHOW CHARACTER SET;
     +----------+-----------------------------+---------------------+--------+
     | Charset  | Description                 | Default collation   | Maxlen |
     +----------+-----------------------------+---------------------+--------+
     | big5     | Big5 Traditional Chinese    | big5_chinese_ci     |      2 |
     | dec8     | DEC West European           | dec8_swedish_ci     |      1 |
     | cp850    | DOS West European           | cp850_general_ci    |      1 |
     | hp8      | HP West European            | hp8_english_ci      |      1 |
     | koi8r    | KOI8-R Relcom Russian       | koi8r_general_ci    |      1 |
     | latin1   | cp1252 West European        | latin1_swedish_ci   |      1 |
     | latin2   | ISO 8859-2 Central European | latin2_general_ci   |      1 |
     ...

To use a 'WHERE' clause with 'SHOW CHARACTER SET',
you would refer to those column names.  As an
example, the following statement displays information about character
sets for which the default collation contains the string ''japanese'':

     mysql> SHOW CHARACTER SET WHERE `Default collation` LIKE '%japanese%';
     +---------+---------------------------+---------------------+--------+
     | Charset | Description               | Default collation   | Maxlen |
     +---------+---------------------------+---------------------+--------+
     | ujis    | EUC-JP Japanese           | ujis_japanese_ci    |      3 |
     | sjis    | Shift-JIS Japanese        | sjis_japanese_ci    |      2 |
     | cp932   | SJIS for Windows Japanese | cp932_japanese_ci   |      2 |
     | eucjpms | UJIS for Windows Japanese | eucjpms_japanese_ci |      3 |
     +---------+---------------------------+---------------------+--------+

This statement displays the multibyte character sets:

     mysql> SHOW CHARACTER SET WHERE Maxlen > 1;
     +---------+---------------------------+---------------------+--------+
     | Charset | Description               | Default collation   | Maxlen |
     +---------+---------------------------+---------------------+--------+
     | big5    | Big5 Traditional Chinese  | big5_chinese_ci     |      2 |
     | ujis    | EUC-JP Japanese           | ujis_japanese_ci    |      3 |
     | sjis    | Shift-JIS Japanese        | sjis_japanese_ci    |      2 |
     | euckr   | EUC-KR Korean             | euckr_korean_ci     |      2 |
     | gb2312  | GB2312 Simplified Chinese | gb2312_chinese_ci   |      2 |
     | gbk     | GBK Simplified Chinese    | gbk_chinese_ci      |      2 |
     | utf8    | UTF-8 Unicode             | utf8_general_ci     |      3 |
     | ucs2    | UCS-2 Unicode             | ucs2_general_ci     |      2 |
     | cp932   | SJIS for Windows Japanese | cp932_japanese_ci   |      2 |
     | eucjpms | UJIS for Windows Japanese | eucjpms_japanese_ci |      3 |
     +---------+---------------------------+---------------------+--------+

25 MySQL Performance Schema
***************************

The MySQL Performance Schema is a feature for monitoring MySQL Server
execution at a low level.  The Performance Schema has these
characteristics:

   * The Performance Schema provides a way to inspect internal execution
     of the server at runtime.  It is implemented using the
     'PERFORMANCE_SCHEMA' storage engine and the
     'performance_schema' database.  The Performance Schema focuses
     primarily on performance data.  This differs from
     'INFORMATION_SCHEMA', which serves for inspection of metadata.

   * The Performance Schema monitors server events.  An 'event' is
     anything the server does that takes time and has been instrumented
     so that timing information can be collected.  In general, an event
     could be a function call, a wait for the operating system, a stage
     of an SQL statement execution such as parsing or sorting, or an
     entire statement or group of statements.  Event collection provides
     access to information about synchronization calls (such as for
     mutexes) file and table I/O, table locks, and so forth for the
     server and for several storage engines.

   * Performance Schema events are distinct from events written to the
     server's binary log (which describe data modifications) and Event
     Scheduler events (which are a type of stored program).

   * Performance Schema events are specific to a given instance of the
     MySQL Server.  Performance Schema tables are considered local to
     the server, and changes to them are not replicated or written to
     the binary log.

   * Current events are available, as well as event histories and
     summaries.  This enables you to determine how many times
     instrumented activities were performed and how much time they took.
     Event information is available to show the activities of specific
     threads, or activity associated with particular objects such as a
     mutex or file.

   * The 'PERFORMANCE_SCHEMA' storage engine
     collects event data using 'instrumentation points' in server source
     code.

   * Collected events are stored in tables in the 'performance_schema'
     database.  These tables can be queried using 'SELECT'
     statements like other tables.

   * Performance Schema configuration can be modified dynamically by
     updating tables in the 'performance_schema' database through SQL
     statements.  Configuration changes affect data collection
     immediately.

   * Tables in the Performance Schema are in-memory tables that use no
     persistent on-disk storage.  The contents are repopulated beginning
     at server startup and discarded at server shutdown.

   * Monitoring is available on all platforms supported by MySQL.

     Some limitations might apply: The types of timers might vary per
     platform.  Instruments that apply to storage engines might not be
     implemented for all storage engines.  Instrumentation of each
     third-party engine is the responsibility of the engine maintainer.
     See also performance-schema-restrictions.

   * Data collection is implemented by modifying the server source code
     to add instrumentation.  There are no separate threads associated
     with the Performance Schema, unlike other features such as
     replication or the Event Scheduler.

The Performance Schema is intended to provide access to useful
information about server execution while having minimal impact on server
performance.  The implementation follows these design goals:

   * Activating the Performance Schema causes no changes in server
     behavior.  For example, it does not cause thread scheduling to
     change, and it does not cause query execution plans (as shown by
     'EXPLAIN') to change.

   * Server monitoring occurs continuously and unobtrusively with very
     little overhead.  Activating the Performance Schema does not make
     the server unusable.

   * The parser is unchanged.  There are no new keywords or statements.

   * Execution of server code proceeds normally even if the Performance
     Schema fails internally.

   * When there is a choice between performing processing during event
     collection initially or during event retrieval later, priority is
     given to making collection faster.  This is because collection is
     ongoing whereas retrieval is on demand and might never happen at
     all.

   * It is easy to add new instrumentation points.

   * Instrumentation is versioned.  If the instrumentation
     implementation changes, previously instrumented code will continue
     to work.  This benefits developers of third-party plugins because
     it is not necessary to upgrade each plugin to stay synchronized
     with the latest Performance Schema changes.

*Note*:

The MySQL 'sys' schema is a set of objects that provides convenient
access to data collected by the Performance Schema.  The 'sys' schema is
installed by default.  For usage instructions, see sys-schema.

25.1 Performance Schema Quick Start
===================================

This section briefly introduces the Performance Schema with examples
that show how to use it.  For additional examples, see
performance-schema-examples.

The Performance Schema is enabled by default.  To enable or disable it
explicitly, start the server with the 'performance_schema' variable set
to an appropriate value.  For example, use these lines in your 'my.cnf'
file:

     [mysqld]
     performance_schema=ON

When the server starts, it sees 'performance_schema' and attempts to
initialize the Performance Schema.  To verify successful initialization,
use this statement:

     mysql> SHOW VARIABLES LIKE 'performance_schema';
     +--------------------+-------+
     | Variable_name      | Value |
     +--------------------+-------+
     | performance_schema | ON    |
     +--------------------+-------+

A value of 'ON' means that the Performance Schema initialized
successfully and is ready for use.  A value of 'OFF' means that some
error occurred.  Check the server error log for information about what
went wrong.

The Performance Schema is implemented as a storage engine.  If this
engine is available (which you should already have checked earlier), you
should see it listed with a 'SUPPORT' value of 'YES' in the output from
the 'INFORMATION_SCHEMA.ENGINES' table or the
'SHOW ENGINES' statement:

     mysql> SELECT * FROM INFORMATION_SCHEMA.ENGINES
            WHERE ENGINE='PERFORMANCE_SCHEMA'\G
     *************************** 1. row ***************************
           ENGINE: PERFORMANCE_SCHEMA
          SUPPORT: YES
          COMMENT: Performance Schema
     TRANSACTIONS: NO
               XA: NO
       SAVEPOINTS: NO

     mysql> SHOW ENGINES\G
     ...
           Engine: PERFORMANCE_SCHEMA
          Support: YES
          Comment: Performance Schema
     Transactions: NO
               XA: NO
       Savepoints: NO
     ...

The 'PERFORMANCE_SCHEMA' storage engine
operates on tables in the 'performance_schema' database.  You can make
'performance_schema' the default database so that references to its
tables need not be qualified with the database name:

     mysql> USE performance_schema;

Many examples in this chapter assume 'performance_schema' as the default
database.

Performance Schema tables are stored in the 'performance_schema'
database.  Information about the structure of this database and its
tables can be obtained, as for any other database, by selecting from the
'INFORMATION_SCHEMA' database or by using 'SHOW'.
statements.  For example, use either of these statements to see what
Performance Schema tables exist:

     mysql> SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
            WHERE TABLE_SCHEMA = 'performance_schema';
     +------------------------------------------------------+
     | TABLE_NAME                                           |
     +------------------------------------------------------+
     | accounts                                             |
     | cond_instances                                       |
     ...
     | events_stages_current                                |
     | events_stages_history                                |
     | events_stages_history_long                           |
     | events_stages_summary_by_account_by_event_name       |
     | events_stages_summary_by_host_by_event_name          |
     | events_stages_summary_by_thread_by_event_name        |
     | events_stages_summary_by_user_by_event_name          |
     | events_stages_summary_global_by_event_name           |
     | events_statements_current                            |
     | events_statements_history                            |
     | events_statements_history_long                       |
     ...
     | file_instances                                       |
     | file_summary_by_event_name                           |
     | file_summary_by_instance                             |
     | host_cache                                           |
     | hosts                                                |
     | memory_summary_by_account_by_event_name              |
     | memory_summary_by_host_by_event_name                 |
     | memory_summary_by_thread_by_event_name               |
     | memory_summary_by_user_by_event_name                 |
     | memory_summary_global_by_event_name                  |
     | metadata_locks                                       |
     | mutex_instances                                      |
     | objects_summary_global_by_type                       |
     | performance_timers                                   |
     | replication_connection_configuration                 |
     | replication_connection_status                        |
     | replication_applier_configuration                    |
     | replication_applier_status                           |
     | replication_applier_status_by_coordinator            |
     | replication_applier_status_by_worker                 |
     | rwlock_instances                                     |
     | session_account_connect_attrs                        |
     | session_connect_attrs                                |
     | setup_actors                                         |
     | setup_consumers                                      |
     | setup_instruments                                    |
     | setup_objects                                        |
     | setup_timers                                         |
     | socket_instances                                     |
     | socket_summary_by_event_name                         |
     | socket_summary_by_instance                           |
     | table_handles                                        |
     | table_io_waits_summary_by_index_usage                |
     | table_io_waits_summary_by_table                      |
     | table_lock_waits_summary_by_table                    |
     | threads                                              |
     | users                                                |
     +------------------------------------------------------+

     mysql> SHOW TABLES FROM performance_schema;
     +------------------------------------------------------+
     | Tables_in_performance_schema                         |
     +------------------------------------------------------+
     | accounts                                             |
     | cond_instances                                       |
     | events_stages_current                                |
     | events_stages_history                                |
     | events_stages_history_long                           |
     ...

The number of Performance Schema tables increases over time as
implementation of additional instrumentation proceeds.

The name of the 'performance_schema' database is lowercase, as are the
names of tables within it.  Queries should specify the names in
lowercase.

To see the structure of individual tables, use 'SHOW CREATE TABLE'.:

     mysql> SHOW CREATE TABLE setup_consumers\G
     *************************** 1. row ***************************
            Table: setup_consumers
     Create Table: CREATE TABLE `setup_consumers` (
       `NAME` varchar(64) NOT NULL,
       `ENABLED` enum('YES','NO') NOT NULL,
       PRIMARY KEY (`NAME`)
     ) ENGINE=PERFORMANCE_SCHEMA DEFAULT CHARSET=utf8

Table structure is also available by selecting from tables such as
'INFORMATION_SCHEMA.COLUMNS' or by using statements such
as 'SHOW COLUMNS'.

Tables in the 'performance_schema' database can be grouped according to
the type of information in them: Current events, event histories and
summaries, object instances, and setup (configuration) information.  The
following examples illustrate a few uses for these tables.  For detailed
information about the tables in each group, see
performance-schema-table-descriptions.

Initially, not all instruments and consumers are enabled, so the
performance schema does not collect all events.  To turn all of these on
and enable event timing, execute two statements (the row counts may
differ depending on MySQL version):

     mysql> UPDATE setup_instruments SET ENABLED = 'YES', TIMED = 'YES';
     Query OK, 560 rows affected (0.04 sec)
     mysql> UPDATE setup_consumers SET ENABLED = 'YES';
     Query OK, 10 rows affected (0.00 sec)

To see what the server is doing at the moment, examine the
'events_waits_current' table.  It contains
one row per thread showing each thread's most recent monitored event:

     mysql> SELECT * FROM events_waits_current\G
     *************************** 1. row ***************************
                 THREAD_ID: 0
                  EVENT_ID: 5523
              END_EVENT_ID: 5523
                EVENT_NAME: wait/synch/mutex/mysys/THR_LOCK::mutex
                    SOURCE: thr_lock.c:525
               TIMER_START: 201660494489586
                 TIMER_END: 201660494576112
                TIMER_WAIT: 86526
                     SPINS: NULL
             OBJECT_SCHEMA: NULL
               OBJECT_NAME: NULL
                INDEX_NAME: NULL
               OBJECT_TYPE: NULL
     OBJECT_INSTANCE_BEGIN: 142270668
          NESTING_EVENT_ID: NULL
        NESTING_EVENT_TYPE: NULL
                 OPERATION: lock
           NUMBER_OF_BYTES: NULL
                     FLAGS: 0
     ...

This event indicates that thread 0 was waiting for 86,526 picoseconds to
acquire a lock on 'THR_LOCK::mutex', a mutex in the 'mysys' subsystem.
The first few columns provide the following information:

   * The ID columns indicate which thread the event comes from and the
     event number.

   * 'EVENT_NAME' indicates what was instrumented and 'SOURCE' indicates
     which source file contains the instrumented code.

   * The timer columns show when the event started and stopped and how
     long it took.  If an event is still in progress, the 'TIMER_END'
     and 'TIMER_WAIT' values are 'NULL'.  Timer values are approximate
     and expressed in picoseconds.  For information about timers and
     event time collection, see performance-schema-timing.

The history tables contain the same kind of rows as the current-events
table but have more rows and show what the server has been doing
'recently' rather than 'currently.' The 'events_waits_history'
and 'events_waits_history_long'
tables contain the most recent 10
events per thread and most recent 10,000 events, respectively.  For
example, to see information for recent events produced by thread 13, do
this:

     mysql> SELECT EVENT_ID, EVENT_NAME, TIMER_WAIT
            FROM events_waits_history WHERE THREAD_ID = 13
            ORDER BY EVENT_ID;
     +----------+-----------------------------------------+------------+
     | EVENT_ID | EVENT_NAME                              | TIMER_WAIT |
     +----------+-----------------------------------------+------------+
     |       86 | wait/synch/mutex/mysys/THR_LOCK::mutex  |     686322 |
     |       87 | wait/synch/mutex/mysys/THR_LOCK_malloc  |     320535 |
     |       88 | wait/synch/mutex/mysys/THR_LOCK_malloc  |     339390 |
     |       89 | wait/synch/mutex/mysys/THR_LOCK_malloc  |     377100 |
     |       90 | wait/synch/mutex/sql/LOCK_plugin        |     614673 |
     |       91 | wait/synch/mutex/sql/LOCK_open          |     659925 |
     |       92 | wait/synch/mutex/sql/THD::LOCK_thd_data |     494001 |
     |       93 | wait/synch/mutex/mysys/THR_LOCK_malloc  |     222489 |
     |       94 | wait/synch/mutex/mysys/THR_LOCK_malloc  |     214947 |
     |       95 | wait/synch/mutex/mysys/LOCK_alarm       |     312993 |
     +----------+-----------------------------------------+------------+

As new events are added to a history table, older events are discarded
if the table is full.

Summary tables provide aggregated information for all events over time.
The tables in this group summarize event data in different ways.  To see
which instruments have been executed the most times or have taken the
most wait time, sort the
'events_waits_summary_global_by_event_name' table
on the 'COUNT_STAR' or 'SUM_TIMER_WAIT' column, which correspond to a
'COUNT(*)' or 'SUM(TIMER_WAIT)' value, respectively, calculated over all
events:

     mysql> SELECT EVENT_NAME, COUNT_STAR
            FROM events_waits_summary_global_by_event_name
            ORDER BY COUNT_STAR DESC LIMIT 10;
     +---------------------------------------------------+------------+
     | EVENT_NAME                                        | COUNT_STAR |
     +---------------------------------------------------+------------+
     | wait/synch/mutex/mysys/THR_LOCK_malloc            |       6419 |
     | wait/io/file/sql/FRM                              |        452 |
     | wait/synch/mutex/sql/LOCK_plugin                  |        337 |
     | wait/synch/mutex/mysys/THR_LOCK_open              |        187 |
     | wait/synch/mutex/mysys/LOCK_alarm                 |        147 |
     | wait/synch/mutex/sql/THD::LOCK_thd_data           |        115 |
     | wait/io/file/myisam/kfile                         |        102 |
     | wait/synch/mutex/sql/LOCK_global_system_variables |         89 |
     | wait/synch/mutex/mysys/THR_LOCK::mutex            |         89 |
     | wait/synch/mutex/sql/LOCK_open                    |         88 |
     +---------------------------------------------------+------------+

     mysql> SELECT EVENT_NAME, SUM_TIMER_WAIT
            FROM events_waits_summary_global_by_event_name
            ORDER BY SUM_TIMER_WAIT DESC LIMIT 10;
     +----------------------------------------+----------------+
     | EVENT_NAME                             | SUM_TIMER_WAIT |
     +----------------------------------------+----------------+
     | wait/io/file/sql/MYSQL_LOG             |     1599816582 |
     | wait/synch/mutex/mysys/THR_LOCK_malloc |     1530083250 |
     | wait/io/file/sql/binlog_index          |     1385291934 |
     | wait/io/file/sql/FRM                   |     1292823243 |
     | wait/io/file/myisam/kfile              |      411193611 |
     | wait/io/file/myisam/dfile              |      322401645 |
     | wait/synch/mutex/mysys/LOCK_alarm      |      145126935 |
     | wait/io/file/sql/casetest              |      104324715 |
     | wait/synch/mutex/sql/LOCK_plugin       |       86027823 |
     | wait/io/file/sql/pid                   |       72591750 |
     +----------------------------------------+----------------+

These results show that the 'THR_LOCK_malloc' mutex is 'hot,' both in
terms of how often it is used and amount of time that threads wait
attempting to acquire it.

*Note*:

The 'THR_LOCK_malloc' mutex is used only in debug builds.  In production
builds it is not hot because it is nonexistent.

Instance tables document what types of objects are instrumented.  An
instrumented object, when used by the server, produces an event.  These
tables provide event names and explanatory notes or status information.
For example, the 'file_instances' table
lists instances of instruments for file I/O operations and their
associated files:

     mysql> SELECT * FROM file_instances\G
     *************************** 1. row ***************************
      FILE_NAME: /opt/mysql-log/60500/binlog.000007
     EVENT_NAME: wait/io/file/sql/binlog
     OPEN_COUNT: 0
     *************************** 2. row ***************************
      FILE_NAME: /opt/mysql/60500/data/mysql/tables_priv.MYI
     EVENT_NAME: wait/io/file/myisam/kfile
     OPEN_COUNT: 1
     *************************** 3. row ***************************
      FILE_NAME: /opt/mysql/60500/data/mysql/columns_priv.MYI
     EVENT_NAME: wait/io/file/myisam/kfile
     OPEN_COUNT: 1
     ...

Setup tables are used to configure and display monitoring
characteristics.  For example, see 'setup_instruments'
lists the set of instruments for which events
can be collected and shows which of them are enabled:

     mysql> SELECT * FROM setup_instruments;
     +---------------------------------------------------+---------+-------+
     | NAME                                              | ENABLED | TIMED |
     +---------------------------------------------------+---------+-------+
     ...
     | stage/sql/end                                     | NO      | NO    |
     | stage/sql/executing                               | NO      | NO    |
     | stage/sql/init                                    | NO      | NO    |
     | stage/sql/insert                                  | NO      | NO    |
     ...
     | statement/sql/load                                | YES     | YES   |
     | statement/sql/grant                               | YES     | YES   |
     | statement/sql/check                               | YES     | YES   |
     | statement/sql/flush                               | YES     | YES   |
     ...
     | wait/synch/mutex/sql/LOCK_global_read_lock        | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_global_system_variables | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_lock_db                 | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_manager                 | YES     | YES   |
     ...
     | wait/synch/rwlock/sql/LOCK_grant                  | YES     | YES   |
     | wait/synch/rwlock/sql/LOGGER::LOCK_logger         | YES     | YES   |
     | wait/synch/rwlock/sql/LOCK_sys_init_connect       | YES     | YES   |
     | wait/synch/rwlock/sql/LOCK_sys_init_slave         | YES     | YES   |
     ...
     | wait/io/file/sql/binlog                           | YES     | YES   |
     | wait/io/file/sql/binlog_index                     | YES     | YES   |
     | wait/io/file/sql/casetest                         | YES     | YES   |
     | wait/io/file/sql/dbopt                            | YES     | YES   |
     ...

To understand how to interpret instrument names, see
performance-schema-instrument-naming.

To control whether events are collected for an instrument, set its
'ENABLED' value to 'YES' or 'NO'.  For example:

     mysql> UPDATE setup_instruments SET ENABLED = 'NO'
            WHERE NAME = 'wait/synch/mutex/sql/LOCK_mysql_create_db';

The Performance Schema uses collected events to update tables in the
'performance_schema' database, which act as 'consumers' of event
information.  The 'setup_consumers' table
lists the available consumers and which are enabled:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | events_stages_current            | NO      |
     | events_stages_history            | NO      |
     | events_stages_history_long       | NO      |
     | events_statements_current        | YES     |
     | events_statements_history        | YES     |
     | events_statements_history_long   | NO      |
     | events_transactions_current      | NO      |
     | events_transactions_history      | NO      |
     | events_transactions_history_long | NO      |
     | events_waits_current             | NO      |
     | events_waits_history             | NO      |
     | events_waits_history_long        | NO      |
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | statements_digest                | YES     |
     +----------------------------------+---------+

To control whether the Performance Schema maintains a consumer as a
destination for event information, set its 'ENABLED' value.

For more information about the setup tables and how to use them to
control event collection, see performance-schema-filtering.

There are some miscellaneous tables that do not fall into any of the
previous groups.  For example, see 'performance_timers'
lists the available event timers and their
characteristics.  For information about timers, see
performance-schema-timing.

25.2 Performance Schema Build Configuration
===========================================

The Performance Schema is mandatory and always compiled in.  It is
possible to exclude certain parts of the Performance Schema
instrumentation.  For example, to exclude stage and statement
instrumentation, do this:

     shell> cmake . \
             -DDISABLE_PSI_STAGE=1 \
             -DDISABLE_PSI_STATEMENT=1

For more information, see the descriptions of the 'DISABLE_PSI_XXX'
'CMake' options in source-configuration-options.

If you install MySQL over a previous installation that was configured
without the Performance Schema (or with an older version of the
Performance Schema that may not have all the current tables), run
'mysql_upgrade' after starting the server to ensure that
the 'performance_schema' database exists with all current tables.  Then
restart the server.  One indication that you need to do this is the
presence of messages such as the following in the error log:

     [ERROR] Native table 'performance_schema'.'events_waits_history'
     has the wrong structure
     [ERROR] Native table 'performance_schema'.'events_waits_history_long'
     has the wrong structure
     ...

To verify whether a server was built with Performance Schema support,
check its help output.  If the Performance Schema is available, the
output will mention several variables with names that begin with
'performance_schema':

     shell> mysqld --verbose --help
     ...
       --performance_schema
                           Enable the performance schema.
       --performance_schema_events_waits_history_long_size=#
                           Number of rows in events_waits_history_long.
     ...

You can also connect to the server and look for a line that names the
'PERFORMANCE_SCHEMA' storage engine in the
output from 'SHOW ENGINES'.:

     mysql> SHOW ENGINES\G
     ...
           Engine: PERFORMANCE_SCHEMA
          Support: YES
          Comment: Performance Schema
     Transactions: NO
               XA: NO
       Savepoints: NO
     ...

If the Performance Schema was not configured into the server at build
time, no row for 'PERFORMANCE_SCHEMA' will
appear in the output from 'SHOW ENGINES'.  You might
see 'performance_schema' listed in the output from 'SHOW DATABASES',
but it will have no tables and you will not
be able to use it.

A line for 'PERFORMANCE_SCHEMA' in the
'SHOW ENGINES' output means that the Performance Schema
is available, not that it is enabled.  To enable it, you must do so at
server startup, as described in the next section.

25.3 Performance Schema Startup Configuration
=============================================

To use the MySQL Performance Schema, it must be enabled at server
startup to enable event collection to occur.

Assuming that the Performance Schema is available, it is enabled by
default.  To enable or disable it explicitly, start the server with the
'performance_schema' variable set to an appropriate value.  For example,
use these lines in your 'my.cnf' file:

     [mysqld]
     performance_schema=ON

If the server is unable to allocate any internal buffer during
Performance Schema initialization, the Performance Schema disables
itself and sets 'performance_schema' to 'OFF', and the server runs
without instrumentation.

The Performance Schema also permits instrument and consumer
configuration at server startup.

To control an instrument at server startup, use an option of this form:

     --performance-schema-instrument='INSTRUMENT_NAME=VALUE'

Here, INSTRUMENT_NAME is an instrument name such as
'wait/synch/mutex/sql/LOCK_open', and VALUE is one of these values:

   * 'OFF', 'FALSE', or '0': Disable the instrument

   * 'ON', 'TRUE', or '1': Enable and time the instrument

   * 'COUNTED': Enable and count (rather than time) the instrument

Each '--performance-schema-instrument' option can specify only one
instrument name, but multiple instances of the option can be given to
configure multiple instruments.  In addition, patterns are permitted in
instrument names to configure instruments that match the pattern.  To
configure all condition synchronization instruments as enabled and
counted, use this option:

     --performance-schema-instrument='wait/synch/cond/%=COUNTED'

To disable all instruments, use this option:

     --performance-schema-instrument='%=OFF'

Exception: The 'memory/performance_schema/%' instruments are built in
and cannot be disabled at startup.

Longer instrument name strings take precedence over shorter pattern
names, regardless of order.  For information about specifying patterns
to select instruments, see performance-schema-filtering-names.

An unrecognized instrument name is ignored.  It is possible that a
plugin installed later may create the instrument, at which time the name
is recognized and configured.

To control a consumer at server startup, use an option of this form:

     --performance-schema-consumer-CONSUMER_NAME=VALUE

Here, CONSUMER_NAME is a consumer name such as 'events_waits_history',
and VALUE is one of these values:

   * 'OFF', 'FALSE', or '0': Do not collect events for the consumer

   * 'ON', 'TRUE', or '1': Collect events for the consumer

For example, to enable the 'events_waits_history' consumer, use this
option:

     --performance-schema-consumer-events-waits-history=ON

The permitted consumer names can be found by examining the
'setup_consumers' table.  Patterns are not
permitted.  Consumer names in the 'setup_consumers'
table use underscores, but for consumers set at
startup, dashes and underscores within the name are equivalent.

The Performance Schema includes several system variables that provide
configuration information:

     mysql> SHOW VARIABLES LIKE 'perf%';
     +--------------------------------------------------------+---------+
     | Variable_name                                          | Value   |
     +--------------------------------------------------------+---------+
     | performance_schema                                     | ON      |
     | performance_schema_accounts_size                       | 100     |
     | performance_schema_digests_size                        | 200     |
     | performance_schema_events_stages_history_long_size     | 10000   |
     | performance_schema_events_stages_history_size          | 10      |
     | performance_schema_events_statements_history_long_size | 10000   |
     | performance_schema_events_statements_history_size      | 10      |
     | performance_schema_events_waits_history_long_size      | 10000   |
     | performance_schema_events_waits_history_size           | 10      |
     | performance_schema_hosts_size                          | 100     |
     | performance_schema_max_cond_classes                    | 80      |
     | performance_schema_max_cond_instances                  | 1000    |
     ...

The 'performance_schema' variable is 'ON' or 'OFF' to indicate whether
the Performance Schema is enabled or disabled.  The other variables
indicate table sizes (number of rows) or memory allocation values.

*Note*:

With the Performance Schema enabled, the number of Performance Schema
instances affects the server memory footprint, perhaps to a large
extent.  The Performance Schema autoscales many parameters to use memory
only as required; see performance-schema-memory-model.

To change the value of Performance Schema system variables, set them at
server startup.  For example, put the following lines in a 'my.cnf' file
to change the sizes of the history tables for wait events:

     [mysqld]
     performance_schema
     performance_schema_events_waits_history_size=20
     performance_schema_events_waits_history_long_size=15000

The Performance Schema automatically sizes the values of several of its
parameters at server startup if they are not set explicitly.  For
example, it sizes the parameters that control the sizes of the events
waits tables this way.  the Performance Schema allocates memory
incrementally, scaling its memory use to actual server load, instead of
allocating all the memory it needs during server startup.  Consequently,
many sizing parameters need not be set at all.  To see which parameters
are autosized or autoscaled, use 'mysqld --verbose --help'
and examine the option descriptions, or see
performance-schema-system-variables.

For each autosized parameter that is not set at server startup (or is
set to −1), the Performance Schema determines how to set its value
based on the value of the following system values, which are considered
as 'hints' about how you have configured your MySQL server:

     max_connections
     open_files_limit
     table_definition_cache
     table_open_cache

To override autosizing or autoscaling for a given parameter, set it to a
value other than −1 at startup.  In this case, the Performance Schema
assigns it the specified value.

At runtime, see 'SHOW VARIABLES' displays the actual
values that autosized parameters were set to.  Autoscaled parameters
display with a value of −1.

If the Performance Schema is disabled, its autosized and autoscaled
parameters remain set to −1 and 'SHOW VARIABLES'
displays −1.

25.4 Performance Schema Runtime Configuration
=============================================

Specific Performance Schema features can be enabled at runtime to
control which types of event collection occur.

Performance Schema setup tables contain information about monitoring
configuration:

     mysql> SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
            WHERE TABLE_SCHEMA = 'performance_schema'
            AND TABLE_NAME LIKE 'setup%';
     +-------------------+
     | TABLE_NAME        |
     +-------------------+
     | setup_actors      |
     | setup_consumers   |
     | setup_instruments |
     | setup_objects     |
     | setup_timers      |
     +-------------------+

You can examine the contents of these tables to obtain information about
Performance Schema monitoring characteristics.  If you have the 'UPDATE'
privilege, you can change Performance Schema operation by modifying
setup tables to affect how monitoring occurs.  For additional details
about these tables, see performance-schema-setup-tables.

To see which event timers are selected, query the 'setup_timers'
tables:

     mysql> SELECT * FROM setup_timers;
     +-------------+-------------+
     | NAME        | TIMER_NAME  |
     +-------------+-------------+
     | idle        | MICROSECOND |
     | wait        | CYCLE       |
     | stage       | NANOSECOND  |
     | statement   | NANOSECOND  |
     | transaction | NANOSECOND  |
     +-------------+-------------+

The 'NAME' value indicates the type of instrument to which the timer
applies, and 'TIMER_NAME' indicates which timer applies to those
instruments.  The timer applies to instruments where their name begins
with a component matching the 'NAME' value.

To change the timer, update the 'NAME' value.  For example, to use the
'NANOSECOND' timer for the 'wait' timer:

     mysql> UPDATE setup_timers SET TIMER_NAME = 'NANOSECOND'
            WHERE NAME = 'wait';
     mysql> SELECT * FROM setup_timers;
     +-------------+-------------+
     | NAME        | TIMER_NAME  |
     +-------------+-------------+
     | idle        | MICROSECOND |
     | wait        | NANOSECOND  |
     | stage       | NANOSECOND  |
     | statement   | NANOSECOND  |
     | transaction | NANOSECOND  |
     +-------------+-------------+

For discussion of timers, see performance-schema-timing.

The 'setup_instruments' and
'setup_consumers' tables list the instruments
for which events can be collected and the types of consumers for which
event information actually is collected, respectively.  Other setup
tables enable further modification of the monitoring configuration.
See performance-schema-filtering, discusses how you can modify these
tables to affect event collection.

If there are Performance Schema configuration changes that must be made
at runtime using SQL statements and you would like these changes to take
effect each time the server starts, put the statements in a file and
start the server with the '--init-file=FILE_NAME' option.  This strategy
can also be useful if you have multiple monitoring configurations, each
tailored to produce a different kind of monitoring, such as casual
server health monitoring, incident investigation, application behavior
troubleshooting, and so forth.  Put the statements for each monitoring
configuration into their own file and specify the appropriate file as
the '--init-file' argument when you start the server.

25.4.1 Performance Schema Event Timing
--------------------------------------

Events are collected by means of instrumentation added to the server
source code.  Instruments time events, which is how the Performance
Schema provides an idea of how long events take.  It is also possible to
configure instruments not to collect timing information.  This section
discusses the available timers and their characteristics, and how timing
values are represented in events.

*Performance Schema Timers*

Two Performance Schema tables provide timer information:

   * 'performance_timers' lists the
     available timers and their characteristics.

   * 'setup_timers' indicates which timers
     are used for which instruments.

Each timer row in 'setup_timers' must refer
to one of the timers listed in 'performance_timers'.

Timers vary in precision and amount of overhead.  To see what timers are
available and their characteristics, check the
'performance_timers' table:

     mysql> SELECT * FROM performance_timers;
     +-------------+-----------------+------------------+----------------+
     | TIMER_NAME  | TIMER_FREQUENCY | TIMER_RESOLUTION | TIMER_OVERHEAD |
     +-------------+-----------------+------------------+----------------+
     | CYCLE       |      2389029850 |                1 |             72 |
     | NANOSECOND  |      1000000000 |                1 |            112 |
     | MICROSECOND |         1000000 |                1 |            136 |
     | MILLISECOND |            1036 |                1 |            168 |
     | TICK        |             105 |                1 |           2416 |
     +-------------+-----------------+------------------+----------------+

If the values associated with a given timer name are 'NULL', that timer
is not supported on your platform.  The rows that do not contain 'NULL'
indicate which timers you can use in 'setup_timers'.

The columns have these meanings:

   * The 'TIMER_NAME' column shows the names of the available timers.
     'CYCLE' refers to the timer that is based on the CPU (processor)
     cycle counter.  The timers in 'setup_timers'
     that you can use are those that do not have
     'NULL' in the other columns.  If the values associated with a given
     timer name are 'NULL', that timer is not supported on your
     platform.

   * 'TIMER_FREQUENCY' indicates the number of timer units per second.
     For a cycle timer, the frequency is generally related to the CPU
     speed.  The value shown was obtained on a system with a 2.4GHz
     processor.  The other timers are based on fixed fractions of
     seconds.  For 'TICK', the frequency may vary by platform (for
     example, some use 100 ticks/second, others 1000 ticks/second).

   * 'TIMER_RESOLUTION' indicates the number of timer units by which
     timer values increase at a time.  If a timer has a resolution of
     10, its value increases by 10 each time.

   * 'TIMER_OVERHEAD' is the minimal number of cycles of overhead to
     obtain one timing with the given timer.  The overhead per event is
     twice the value displayed because the timer is invoked at the
     beginning and end of the event.

To see which timers are in effect or to change timers, access the
'setup_timers' table:

     mysql> SELECT * FROM setup_timers;
     +-------------+-------------+
     | NAME        | TIMER_NAME  |
     +-------------+-------------+
     | idle        | MICROSECOND |
     | wait        | CYCLE       |
     | stage       | NANOSECOND  |
     | statement   | NANOSECOND  |
     | transaction | NANOSECOND  |
     +-------------+-------------+

     mysql> UPDATE setup_timers SET TIMER_NAME = 'MICROSECOND'
            WHERE NAME = 'idle';
     mysql> SELECT * FROM setup_timers;
     +-------------+-------------+
     | NAME        | TIMER_NAME  |
     +-------------+-------------+
     | idle        | MICROSECOND |
     | wait        | CYCLE       |
     | stage       | NANOSECOND  |
     | statement   | NANOSECOND  |
     | transaction | NANOSECOND  |
     +-------------+-------------+

By default, the Performance Schema uses the best timer available for
each instrument type, but you can select a different one.

To time wait events, the most important criterion is to reduce overhead,
at the possible expense of the timer accuracy, so using the 'CYCLE'
timer is the best.

The time a statement (or stage) takes to execute is in general orders of
magnitude larger than the time it takes to execute a single wait.  To
time statements, the most important criterion is to have an accurate
measure, which is not affected by changes in processor frequency, so
using a timer which is not based on cycles is the best.  The default
timer for statements is 'NANOSECOND'.  The extra 'overhead' compared to
the 'CYCLE' timer is not significant, because the overhead caused by
calling a timer twice (once when the statement starts, once when it
ends) is orders of magnitude less compared to the CPU time used to
execute the statement itself.  Using the 'CYCLE' timer has no benefit
here, only drawbacks.

The precision offered by the cycle counter depends on processor speed.
If the processor runs at 1 GHz (one billion cycles/second) or higher,
the cycle counter delivers sub-nanosecond precision.  Using the cycle
counter is much cheaper than getting the actual time of day.  For
example, the standard 'gettimeofday()' function can take hundreds of
cycles, which is an unacceptable overhead for data gathering that may
occur thousands or millions of times per second.

Cycle counters also have disadvantages:

   * End users expect to see timings in wall-clock units, such as
     fractions of a second.  Converting from cycles to fractions of
     seconds can be expensive.  For this reason, the conversion is a
     quick and fairly rough multiplication operation.

   * Processor cycle rate might change, such as when a laptop goes into
     power-saving mode or when a CPU slows down to reduce heat
     generation.  If a processor's cycle rate fluctuates, conversion
     from cycles to real-time units is subject to error.

   * Cycle counters might be unreliable or unavailable depending on the
     processor or the operating system.  For example, on Pentiums, the
     instruction is 'RDTSC' (an assembly-language rather than a C
     instruction) and it is theoretically possible for the operating
     system to prevent user-mode programs from using it.

   * Some processor details related to out-of-order execution or
     multiprocessor synchronization might cause the counter to seem fast
     or slow by up to 1000 cycles.

MySQL works with cycle counters on x386 (Windows, macOS, Linux, Solaris,
and other Unix flavors), PowerPC, and IA-64.

*Performance Schema Timer Representation in Events*

Rows in Performance Schema tables that store current events and
historical events have three columns to represent timing information:
'TIMER_START' and 'TIMER_END' indicate when an event started and
finished, and 'TIMER_WAIT' indicates event duration.

The 'setup_instruments' table has an
'ENABLED' column to indicate the instruments for which to collect
events.  The table also has a 'TIMED' column to indicate which
instruments are timed.  If an instrument is not enabled, it produces no
events.  If an enabled instrument is not timed, events produced by the
instrument have 'NULL' for the 'TIMER_START', 'TIMER_END', and
'TIMER_WAIT' timer values.  This in turn causes those values to be
ignored when calculating aggregate time values in summary tables (sum,
minimum, maximum, and average).

Internally, times within events are stored in units given by the timer
in effect when event timing begins.  For display when events are
retrieved from Performance Schema tables, times are shown in picoseconds
(trillionths of a second) to normalize them to a standard unit,
regardless of which timer is selected.

Modifications to the 'setup_timers' table
affect monitoring immediately.  Events already in progress may use the
original timer for the begin time and the new timer for the end time.
To avoid unpredictable results after you make timer changes, use
'TRUNCATE TABLE' to reset Performance Schema
statistics.

The timer baseline ('time zero') occurs at Performance Schema
initialization during server startup.  'TIMER_START' and 'TIMER_END'
values in events represent picoseconds since the baseline.  'TIMER_WAIT'
values are durations in picoseconds.

Picosecond values in events are approximate.  Their accuracy is subject
to the usual forms of error associated with conversion from one unit to
another.  If the 'CYCLE' timer is used and the processor rate varies,
there might be drift.  For these reasons, it is not reasonable to look
at the 'TIMER_START' value for an event as an accurate measure of time
elapsed since server startup.  On the other hand, it is reasonable to
use 'TIMER_START' or 'TIMER_WAIT' values in 'ORDER BY' clauses to order
events by start time or duration.

The choice of picoseconds in events rather than a value such as
microseconds has a performance basis.  One implementation goal was to
show results in a uniform time unit, regardless of the timer.  In an
ideal world this time unit would look like a wall-clock unit and be
reasonably precise; in other words, microseconds.  But to convert cycles
or nanoseconds to microseconds, it would be necessary to perform a
division for every instrumentation.  Division is expensive on many
platforms.  Multiplication is not expensive, so that is what is used.
Therefore, the time unit is an integer multiple of the highest possible
'TIMER_FREQUENCY' value, using a multiplier large enough to ensure that
there is no major precision loss.  The result is that the time unit is
'picoseconds.' This precision is spurious, but the decision enables
overhead to be minimized.

While a wait, stage, statement, or transaction event is executing, the
respective current-event tables display current-event timing
information:

     events_waits_current
     events_stages_current
     events_statements_current
     events_transactions_current

To make it possible to determine how how long a not-yet-completed event
has been running, the timer columns are set as follows:

   * 'TIMER_START' is populated.

   * 'TIMER_END' is populated with the current timer value.

   * 'TIMER_WAIT' is populated with the time elapsed so far ('TIMER_END'
     − 'TIMER_START').

Events that have not yet completed have an 'END_EVENT_ID' value of
'NULL'.  To assess time elapsed so far for an event, use the
'TIMER_WAIT' column.  Therefore, to identify events that have not yet
completed and have taken longer than N picoseconds thus far, monitoring
applications can use this expression in queries:

     WHERE END_EVENT_ID IS NULL AND TIMER_WAIT > N

Event identification as just described assumes that the corresponding
instruments have 'ENABLED' and 'TIMED' set to 'YES' and that the
relevant consumers are enabled.

25.4.2 Performance Schema Event Filtering
-----------------------------------------

Events are processed in a producer/consumer fashion:

   * Instrumented code is the source for events and produces events to
     be collected.  The 'setup_instruments'
     table lists the instruments for which
     events can be collected, whether they are enabled, and (for enabled
     instruments) whether to collect timing information:

          mysql> SELECT * FROM setup_instruments;
          +---------------------------------------------------+---------+-------+
          | NAME                                              | ENABLED | TIMED |
          +---------------------------------------------------+---------+-------+
          ...
          | wait/synch/mutex/sql/LOCK_global_read_lock        | YES     | YES   |
          | wait/synch/mutex/sql/LOCK_global_system_variables | YES     | YES   |
          | wait/synch/mutex/sql/LOCK_lock_db                 | YES     | YES   |
          | wait/synch/mutex/sql/LOCK_manager                 | YES     | YES   |
          ...

     The 'setup_instruments' table
     provides the most basic form of control over event production.  To
     further refine event production based on the type of object or
     thread being monitored, other tables may be used as described in
     performance-schema-pre-filtering.

   * Performance Schema tables are the destinations for events and
     consume events.  The 'setup_consumers'
     table lists the types of consumers to which
     event information can be sent and whether they are enabled:

          mysql> SELECT * FROM setup_consumers;
          +----------------------------------+---------+
          | NAME                             | ENABLED |
          +----------------------------------+---------+
          | events_stages_current            | NO      |
          | events_stages_history            | NO      |
          | events_stages_history_long       | NO      |
          | events_statements_current        | YES     |
          | events_statements_history        | YES     |
          | events_statements_history_long   | NO      |
          | events_transactions_current      | NO      |
          | events_transactions_history      | NO      |
          | events_transactions_history_long | NO      |
          | events_waits_current             | NO      |
          | events_waits_history             | NO      |
          | events_waits_history_long        | NO      |
          | global_instrumentation           | YES     |
          | thread_instrumentation           | YES     |
          | statements_digest                | YES     |
          +----------------------------------+---------+

Filtering can be done at different stages of performance monitoring:

   * Pre-filtering

     This is done by modifying Performance Schema configuration so that
     only certain types of events are collected from producers, and
     collected events update only certain consumers.  To do this, enable
     or disable instruments or consumers.  Pre-filtering is done by the
     Performance Schema and has a global effect that applies to all
     users.

     Reasons to use pre-filtering:

        * To reduce overhead.  Performance Schema overhead should be
          minimal even with all instruments enabled, but perhaps you
          want to reduce it further.  Or you do not care about timing
          events and want to disable the timing code to eliminate timing
          overhead.

        * To avoid filling the current-events or history tables with
          events in which you have no interest.  Pre-filtering leaves
          more 'room' in these tables for instances of rows for enabled
          instrument types.  If you enable only file instruments with
          pre-filtering, no rows are collected for nonfile instruments.
          With post-filtering, nonfile events are collected, leaving
          fewer rows for file events.

        * To avoid maintaining some kinds of event tables.  If you
          disable a consumer, the server does not spend time maintaining
          destinations for that consumer.  For example, if you do not
          care about event histories, you can disable the history table
          consumers to improve performance.

   * Post-filtering

     This involves the use of 'WHERE' clauses in queries that select
     information from Performance Schema tables, to specify which of the
     available events you want to see.  Post-filtering is performed on a
     per-user basis because individual users select which of the
     available events are of interest.

     Reasons to use post-filtering:

        * To avoid making decisions for individual users about which
          event information is of interest.

        * To use the Performance Schema to investigate a performance
          issue when the restrictions to impose using pre-filtering are
          not known in advance.

The following sections provide more detail about pre-filtering and
provide guidelines for naming instruments or consumers in filtering
operations.  For information about writing queries to retrieve
information (post-filtering), see performance-schema-queries.

25.4.3 Event Pre-Filtering
--------------------------

Pre-filtering is done by the Performance Schema and has a global effect
that applies to all users.  Pre-filtering can be applied to either the
producer or consumer stage of event processing:

   * To configure pre-filtering at the producer stage, several tables
     can be used:

        * 'setup_instruments' indicates
          which instruments are available.  An instrument disabled in
          this table produces no events regardless of the contents of
          the other production-related setup tables.  An instrument
          enabled in this table is permitted to produce events, subject
          to the contents of the other tables.

        * 'setup_objects' controls whether
          the Performance Schema monitors particular table and stored
          program objects.

        * 'threads' indicates whether monitoring
          is enabled for each server thread.

        * 'setup_actors' determines the
          initial monitoring state for new foreground threads.

   * To configure pre-filtering at the consumer stage, modify the
     'setup_consumers' table.  This determines
     the destinations to which events are sent.
     'setup_consumers' also implicitly affects
     event production.  If a given event will not be sent to any
     destination (that is, will not be consumed), the Performance Schema
     does not produce it.

Modifications to any of these tables affect monitoring immediately, with
some exceptions:

   * Modifications to some instruments in the 'setup_instruments'
     table are effective only at server
     startup; changing them at runtime has no effect.  This affects
     primarily mutexes, conditions, and rwlocks in the server, although
     there may be other instruments for which this is true.  This
     restriction is lifted as of MySQL 5.7.12.

   * Modifications to the 'setup_actors'.
     table affect only foreground threads created subsequent to the
     modification, not existing threads.

When you change the monitoring configuration, the Performance Schema
does not flush the history tables.  Events already collected remain in
the current-events and history tables until displaced by newer events.
If you disable instruments, you might need to wait a while before events
for them are displaced by newer events of interest.  Alternatively, use
'TRUNCATE TABLE' to empty the history tables.

After making instrumentation changes, you might want to truncate the
summary tables.  Generally, the effect is to reset the summary columns
to 0 or 'NULL', not to remove rows.  This enables you to clear collected
values and restart aggregation.  That might be useful, for example,
after you have made a runtime configuration change.  Exceptions to this
truncation behavior are noted in individual summary table sections.

The following sections describe how to use specific tables to control
Performance Schema pre-filtering.

25.4.4 Pre-Filtering by Instrument
----------------------------------

The 'setup_instruments' table lists the
available instruments:

     mysql> SELECT * FROM setup_instruments;
     +---------------------------------------------------+---------+-------+
     | NAME                                              | ENABLED | TIMED |
     +---------------------------------------------------+---------+-------+
     ...
     | stage/sql/end                                     | NO      | NO    |
     | stage/sql/executing                               | NO      | NO    |
     | stage/sql/init                                    | NO      | NO    |
     | stage/sql/insert                                  | NO      | NO    |
     ...
     | statement/sql/load                                | YES     | YES   |
     | statement/sql/grant                               | YES     | YES   |
     | statement/sql/check                               | YES     | YES   |
     | statement/sql/flush                               | YES     | YES   |
     ...
     | wait/synch/mutex/sql/LOCK_global_read_lock        | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_global_system_variables | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_lock_db                 | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_manager                 | YES     | YES   |
     ...
     | wait/synch/rwlock/sql/LOCK_grant                  | YES     | YES   |
     | wait/synch/rwlock/sql/LOGGER::LOCK_logger         | YES     | YES   |
     | wait/synch/rwlock/sql/LOCK_sys_init_connect       | YES     | YES   |
     | wait/synch/rwlock/sql/LOCK_sys_init_slave         | YES     | YES   |
     ...
     | wait/io/file/sql/binlog                           | YES     | YES   |
     | wait/io/file/sql/binlog_index                     | YES     | YES   |
     | wait/io/file/sql/casetest                         | YES     | YES   |
     | wait/io/file/sql/dbopt                            | YES     | YES   |
     ...

To control whether an instrument is enabled, set its 'ENABLED' column to
'YES' or 'NO'.  To configure whether to collect timing information for
an enabled instrument, set its 'TIMED' value to 'YES' or 'NO'.  Setting
the 'TIMED' column affects Performance Schema table contents as
described in performance-schema-timing.

Modifications to most 'setup_instruments'
rows affect monitoring immediately.  For some
instruments, modifications are effective only at server startup;
changing them at runtime has no effect.  This affects primarily mutexes,
conditions, and rwlocks in the server, although there may be other
instruments for which this is true.

The 'setup_instruments' table provides
the most basic form of control over event production.  To further refine
event production based on the type of object or thread being monitored,
other tables may be used as described in
performance-schema-pre-filtering.

The following examples demonstrate possible operations on the
'setup_instruments' table.  These changes,
like other pre-filtering operations, affect all users.  Some of these
queries use the 'LIKE' operator and a pattern match instrument names.
For additional information about specifying patterns to select
instruments, see performance-schema-filtering-names.

   * Disable all instruments:

          mysql> UPDATE setup_instruments SET ENABLED = 'NO';

     Now no events will be collected.

   * Disable all file instruments, adding them to the current set of
     disabled instruments:

          mysql> UPDATE setup_instruments SET ENABLED = 'NO'
                 WHERE NAME LIKE 'wait/io/file/%';

   * Disable only file instruments, enable all other instruments:

          mysql> UPDATE setup_instruments
                 SET ENABLED = IF(NAME LIKE 'wait/io/file/%', 'NO', 'YES');

   * Enable all but those instruments in the 'mysys' library:

          mysql> UPDATE setup_instruments
                 SET ENABLED = CASE WHEN NAME LIKE '%/mysys/%' THEN 'YES' ELSE 'NO' END;

   * Disable a specific instrument:

          mysql> UPDATE setup_instruments SET ENABLED = 'NO'
                 WHERE NAME = 'wait/synch/mutex/mysys/TMPDIR_mutex';

   * To toggle the state of an instrument, 'flip' its 'ENABLED' value:

          mysql> UPDATE setup_instruments
                 SET ENABLED = IF(ENABLED = 'YES', 'NO', 'YES')
                 WHERE NAME = 'wait/synch/mutex/mysys/TMPDIR_mutex';

   * Disable timing for all events:

          mysql> UPDATE setup_instruments SET TIMED = 'NO';

25.4.5 Pre-Filtering by Object
------------------------------

The 'setup_objects' table controls whether
the Performance Schema monitors particular table and stored program
objects.  The initial 'setup_objects'.
contents look like this:

     mysql> SELECT * FROM setup_objects;
     +-------------+--------------------+-------------+---------+-------+
     | OBJECT_TYPE | OBJECT_SCHEMA      | OBJECT_NAME | ENABLED | TIMED |
     +-------------+--------------------+-------------+---------+-------+
     | EVENT       | mysql              | %           | NO      | NO    |
     | EVENT       | performance_schema | %           | NO      | NO    |
     | EVENT       | information_schema | %           | NO      | NO    |
     | EVENT       | %                  | %           | YES     | YES   |
     | FUNCTION    | mysql              | %           | NO      | NO    |
     | FUNCTION    | performance_schema | %           | NO      | NO    |
     | FUNCTION    | information_schema | %           | NO      | NO    |
     | FUNCTION    | %                  | %           | YES     | YES   |
     | PROCEDURE   | mysql              | %           | NO      | NO    |
     | PROCEDURE   | performance_schema | %           | NO      | NO    |
     | PROCEDURE   | information_schema | %           | NO      | NO    |
     | PROCEDURE   | %                  | %           | YES     | YES   |
     | TABLE       | mysql              | %           | NO      | NO    |
     | TABLE       | performance_schema | %           | NO      | NO    |
     | TABLE       | information_schema | %           | NO      | NO    |
     | TABLE       | %                  | %           | YES     | YES   |
     | TRIGGER     | mysql              | %           | NO      | NO    |
     | TRIGGER     | performance_schema | %           | NO      | NO    |
     | TRIGGER     | information_schema | %           | NO      | NO    |
     | TRIGGER     | %                  | %           | YES     | YES   |
     +-------------+--------------------+-------------+---------+-------+

Modifications to the 'setup_objects' table
affect object monitoring immediately.

The 'OBJECT_TYPE' column indicates the type of object to which a row
applies.  'TABLE' filtering affects table I/O events
('wait/io/table/sql/handler' instrument) and table lock events
('wait/lock/table/sql/handler' instrument).

The 'OBJECT_SCHEMA' and 'OBJECT_NAME' columns should contain a literal
schema or object name, or ''%'' to match any name.

The 'ENABLED' column indicates whether matching objects are monitored,
and 'TIMED' indicates whether to collect timing information.  Setting
the 'TIMED' column affects Performance Schema table contents as
described in performance-schema-timing.

The effect of the default object configuration is to instrument all
objects except those in the 'mysql', 'INFORMATION_SCHEMA', and
'performance_schema' databases.  (Tables in the 'INFORMATION_SCHEMA'
database are not instrumented regardless of the contents of
'setup_objects'.; the row for
'information_schema.%' simply makes this default explicit.)

When the Performance Schema checks for a match in 'setup_objects',
it tries to find more specific matches first.  For
rows that match a given 'OBJECT_TYPE', the Performance Schema checks
rows in this order:

   * Rows with 'OBJECT_SCHEMA='LITERAL'' and 'OBJECT_NAME='LITERAL''.

   * Rows with 'OBJECT_SCHEMA='LITERAL'' and 'OBJECT_NAME='%''.

   * Rows with 'OBJECT_SCHEMA='%'' and 'OBJECT_NAME='%''.

For example, with a table 'db1.t1', the Performance Schema looks in
'TABLE' rows for a match for ''db1'' and ''t1'', then for ''db1'' and
''%'', then for ''%'' and ''%''.  The order in which matching occurs
matters because different matching 'setup_objects'
rows can have different 'ENABLED' and 'TIMED'
values.

For table-related events, the Performance Schema combines the contents
of 'setup_objects' with
'setup_instruments' to determine whether to
enable instruments and whether to time enabled instruments:

   * For tables that match a row in 'setup_objects',
     table instruments produce events only if
     'ENABLED' is 'YES' in both 'setup_instruments'
     and 'setup_objects'.

   * The 'TIMED' values in the two tables are combined, so that timing
     information is collected only when both values are 'YES'.

For stored program objects, the Performance Schema takes the 'ENABLED'
and 'TIMED' columns directly from the 'setup_objects'
row.  There is no combining of values with
'setup_instruments'.

Suppose that 'setup_objects' contains the
following 'TABLE' rows that apply to 'db1', 'db2', and 'db3':

     +-------------+---------------+-------------+---------+-------+
     | OBJECT_TYPE | OBJECT_SCHEMA | OBJECT_NAME | ENABLED | TIMED |
     +-------------+---------------+-------------+---------+-------+
     | TABLE       | db1           | t1          | YES     | YES   |
     | TABLE       | db1           | t2          | NO      | NO    |
     | TABLE       | db2           | %           | YES     | YES   |
     | TABLE       | db3           | %           | NO      | NO    |
     | TABLE       | %             | %           | YES     | YES   |
     +-------------+---------------+-------------+---------+-------+

If an object-related instrument in 'setup_instruments'
has an 'ENABLED' value of 'NO', events for the
object are not monitored.  If the 'ENABLED' value is 'YES', event
monitoring occurs according to the 'ENABLED' value in the relevant
'setup_objects' row:

   * 'db1.t1' events are monitored

   * 'db1.t2' events are not monitored

   * 'db2.t3' events are monitored

   * 'db3.t4' events are not monitored

   * 'db4.t5' events are monitored

Similar logic applies for combining the 'TIMED' columns from the
'setup_instruments' and 'setup_objects'
tables to determine whether to collect event timing
information.

If a persistent table and a temporary table have the same name, matching
against 'setup_objects' rows occurs the same
way for both.  It is not possible to enable monitoring for one table but
not the other.  However, each table is instrumented separately.

25.4.6 Pre-Filtering by Thread
------------------------------

The 'threads' table contains a row for each server
thread.  Each row contains information about a thread and indicates
whether monitoring is enabled for it.  For the Performance Schema to
monitor a thread, these things must be true:

   * The 'thread_instrumentation' consumer in the
     'setup_consumers' table must be 'YES'.

   * The 'threads.INSTRUMENTED' column must be 'YES'.

   * Monitoring occurs only for those thread events produced from
     instruments that are enabled in the 'setup_instruments'
     table.

The 'threads' table also indicates for each server
thread whether to perform historical event logging.  This includes wait,
stage, statement, and transaction events and affects logging to these
tables:

     events_waits_history
     events_waits_history_long
     events_stages_history
     events_stages_history_long
     events_statements_history
     events_statements_history_long
     events_transactions_history
     events_transactions_history_long

For historical event logging to occur, these things must be true:

   * The appropriate history-related consumers in the
     'setup_consumers' table must be enabled.
     For example, wait event logging in the
     'events_waits_history' and
     'events_waits_history_long'.
     tables requires the corresponding 'events_waits_history' and
     'events_waits_history_long' consumers to be 'YES'.

   * The 'threads.HISTORY' column must be 'YES'.

   * Logging occurs only for those thread events produced from
     instruments that are enabled in the 'setup_instruments'
     table.

For foreground threads (resulting from client connections), the initial
values of the 'INSTRUMENTED' and 'HISTORY' columns in 'threads'
table rows are determined by whether the user account
associated with a thread matches any row in the 'setup_actors'
table.  The values come from the 'ENABLED' and
'HISTORY' columns of the matching 'setup_actors'
table row.

For background threads, there is no associated user.  'INSTRUMENTED' and
'HISTORY' are 'YES' by default and 'setup_actors'
is not consulted.

The initial 'setup_actors' contents look like
this:

     mysql> SELECT * FROM setup_actors;
     +------+------+------+---------+---------+
     | HOST | USER | ROLE | ENABLED | HISTORY |
     +------+------+------+---------+---------+
     | %    | %    | %    | YES     | YES     |
     +------+------+------+---------+---------+

The 'HOST' and 'USER' columns should contain a literal host or user
name, or ''%'' to match any name.

The 'ENABLED' and 'HISTORY' columns indicate whether to enable
instrumentation and historical event logging for matching threads,
subject to the other conditions described previously.

When the Performance Schema checks for a match for each new foreground
thread in 'setup_actors', it tries to find more specific matches first,
using the 'USER' and 'HOST' columns ('ROLE' is unused):

   * Rows with 'USER='LITERAL'' and 'HOST='LITERAL''.

   * Rows with 'USER='LITERAL'' and 'HOST='%''.

   * Rows with 'USER='%'' and 'HOST='LITERAL''.

   * Rows with 'USER='%'' and 'HOST='%''.

The order in which matching occurs matters because different matching
'setup_actors' rows can have different 'USER'
and 'HOST' values.  This enables instrumenting and historical event
logging to be applied selectively per host, user, or account (user and
host combination), based on the 'ENABLED' and 'HISTORY' column values:

   * When the best match is a row with 'ENABLED=YES', the 'INSTRUMENTED'
     value for the thread becomes 'YES'.  When the best match is a row
     with 'HISTORY=YES', the 'HISTORY' value for the thread becomes
     'YES'.

   * When the best match is a row with 'ENABLED=NO', the 'INSTRUMENTED'
     value for the thread becomes 'NO'.  When the best match is a row
     with 'HISTORY=NO', the 'HISTORY' value for the thread becomes 'NO'.

   * When no match is found, the 'INSTRUMENTED' and 'HISTORY' values for
     the thread become 'NO'.

The 'ENABLED' and 'HISTORY' columns in 'setup_actors'
rows can be set to 'YES' or 'NO' independent of one
another.  This means you can enable instrumentation separately from
whether you collect historical events.

By default, monitoring and historical event collection are enabled for
all new foreground threads because the 'setup_actors'
table initially contains a row with ''%'' for both
'HOST' and 'USER'.  To perform more limited matching such as to enable
monitoring only for some foreground threads, you must change this row
because it matches any connection, and add rows for more specific
'HOST'/'USER' combinations.

Suppose that you modify 'setup_actors' as
follows:

     UPDATE setup_actors SET ENABLED = 'NO', HISTORY = 'NO'
     WHERE HOST = '%' AND USER = '%';
     INSERT INTO setup_actors (HOST,USER,ROLE,ENABLED,HISTORY)
     VALUES('localhost','joe','%','YES','YES');
     INSERT INTO setup_actors (HOST,USER,ROLE,ENABLED,HISTORY)
     VALUES('hosta.example.com','joe','%','YES','NO');
     INSERT INTO setup_actors (HOST,USER,ROLE,ENABLED,HISTORY)
     VALUES('%','sam','%','NO','YES');

The 'UPDATE' statement changes the default match to
disable instrumentation and historical event collection.  The
'INSERT' statements add rows for more specific matches.

Now the Performance Schema determines how to set the 'INSTRUMENTED' and
'HISTORY' values for new connection threads as follows:

   * If 'joe' connects from the local host, the connection matches the
     first inserted row.  The 'INSTRUMENTED' and 'HISTORY' values for
     the thread become 'YES'.

   * If 'joe' connects from 'hosta.example.com', the connection matches
     the second inserted row.  The 'INSTRUMENTED' value for the thread
     becomes 'YES' and the 'HISTORY' value becomes 'NO'.

   * If 'joe' connects from any other host, there is no match.  The
     'INSTRUMENTED' and 'HISTORY' values for the thread become 'NO'.

   * If 'sam' connects from any host, the connection matches the third
     inserted row.  The 'INSTRUMENTED' value for the thread becomes 'NO'
     and the 'HISTORY' value becomes 'YES'.

   * For any other connection, the row with 'HOST' and 'USER' set to
     ''%'' matches.  This row now has 'ENABLED' and 'HISTORY' set to
     'NO', so the 'INSTRUMENTED' and 'HISTORY' values for the thread
     become 'NO'.

Modifications to the 'setup_actors' table
affect only foreground threads created subsequent to the modification,
not existing threads.  To affect existing threads, modify the
'INSTRUMENTED' and 'HISTORY' columns of 'threads'.
table rows.

25.4.7 Pre-Filtering by Consumer
--------------------------------

The 'setup_consumers' table lists the
available consumer types and which are enabled:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | events_stages_current            | NO      |
     | events_stages_history            | NO      |
     | events_stages_history_long       | NO      |
     | events_statements_current        | YES     |
     | events_statements_history        | YES     |
     | events_statements_history_long   | NO      |
     | events_transactions_current      | NO      |
     | events_transactions_history      | NO      |
     | events_transactions_history_long | NO      |
     | events_waits_current             | NO      |
     | events_waits_history             | NO      |
     | events_waits_history_long        | NO      |
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | statements_digest                | YES     |
     +----------------------------------+---------+

Modify the 'setup_consumers' table to
affect pre-filtering at the consumer stage and determine the
destinations to which events are sent.  To enable or disable a consumer,
set its 'ENABLED' value to 'YES' or 'NO'.

Modifications to the 'setup_consumers'.
table affect monitoring immediately.

If you disable a consumer, the server does not spend time maintaining
destinations for that consumer.  For example, if you do not care about
historical event information, disable the history consumers:

     mysql> UPDATE setup_consumers
            SET ENABLED = 'NO' WHERE NAME LIKE '%history%';

The consumer settings in the 'setup_consumers'
table form a hierarchy from higher levels to
lower.  The following principles apply:

   * Destinations associated with a consumer receive no events unless
     the Performance Schema checks the consumer and the consumer is
     enabled.

   * A consumer is checked only if all consumers it depends on (if any)
     are enabled.

   * If a consumer is not checked, or is checked but is disabled, other
     consumers that depend on it are not checked.

   * Dependent consumers may have their own dependent consumers.

   * If an event would not be sent to any destination, the Performance
     Schema does not produce it.

The following lists describe the available consumer values.  For
discussion of several representative consumer configurations and their
effect on instrumentation, see
performance-schema-consumer-configurations.

   * performance-schema-consumer-filtering-global-thread

   * performance-schema-consumer-filtering-wait-event

   * performance-schema-consumer-filtering-stage-event

   * performance-schema-consumer-filtering-statement-event

   * performance-schema-consumer-filtering-transaction-event

   * performance-schema-consumer-filtering-statement-digest

*Global and Thread Consumers*

   * 'global_instrumentation' is the highest level consumer.  If
     'global_instrumentation' is 'NO', it disables global
     instrumentation.  All other settings are lower level and are not
     checked; it does not matter what they are set to.  No global or per
     thread information is maintained and no individual events are
     collected in the current-events or event-history tables.  If
     'global_instrumentation' is 'YES', the Performance Schema maintains
     information for global states and also checks the
     'thread_instrumentation' consumer.

   * 'thread_instrumentation' is checked only if
     'global_instrumentation' is 'YES'.  Otherwise, if
     'thread_instrumentation' is 'NO', it disables thread-specific
     instrumentation and all lower-level settings are ignored.  No
     information is maintained per thread and no individual events are
     collected in the current-events or event-history tables.  If
     'thread_instrumentation' is 'YES', the Performance Schema maintains
     thread-specific information and also checks 'events_XXX_current'
     consumers.

*Wait Event Consumers*

These consumers require both 'global_instrumentation' and
'thread_instrumentation' to be 'YES' or they are not checked.  If
checked, they act as follows:

   * 'events_waits_current', if 'NO', disables collection of individual
     wait events in the 'events_waits_current'
     table.  If 'YES', it enables wait event
     collection and the Performance Schema checks the
     'events_waits_history' and 'events_waits_history_long' consumers.

   * 'events_waits_history' is not checked if 'event_waits_current' is
     'NO'.  Otherwise, an 'events_waits_history' value of 'NO' or 'YES'
     disables or enables collection of wait events in the
     'events_waits_history' table.

   * 'events_waits_history_long' is not checked if 'event_waits_current'
     is 'NO'.  Otherwise, an 'events_waits_history_long' value of 'NO'
     or 'YES' disables or enables collection of wait events in the
     'events_waits_history_long'.
     table.

*Stage Event Consumers*

These consumers require both 'global_instrumentation' and
'thread_instrumentation' to be 'YES' or they are not checked.  If
checked, they act as follows:

   * 'events_stages_current', if 'NO', disables collection of individual
     stage events in the 'events_stages_current'
     table.  If 'YES', it enables stage
     event collection and the Performance Schema checks the
     'events_stages_history' and 'events_stages_history_long' consumers.

   * 'events_stages_history' is not checked if 'event_stages_current' is
     'NO'.  Otherwise, an 'events_stages_history' value of 'NO' or 'YES'
     disables or enables collection of stage events in the
     'events_stages_history' table.

   * 'events_stages_history_long' is not checked if
     'event_stages_current' is 'NO'.  Otherwise, an
     'events_stages_history_long' value of 'NO' or 'YES' disables or
     enables collection of stage events in the
     'events_stages_history_long'.
     table.

*Statement Event Consumers*

These consumers require both 'global_instrumentation' and
'thread_instrumentation' to be 'YES' or they are not checked.  If
checked, they act as follows:

   * 'events_statements_current', if 'NO', disables collection of
     individual statement events in the
     'events_statements_current'.
     table.  If 'YES', it enables statement event collection and the
     Performance Schema checks the 'events_statements_history' and
     'events_statements_history_long' consumers.

   * 'events_statements_history' is not checked if
     'events_statements_current' is 'NO'.  Otherwise, an
     'events_statements_history' value of 'NO' or 'YES' disables or
     enables collection of statement events in the
     'events_statements_history'.
     table.

   * 'events_statements_history_long' is not checked if
     'events_statements_current' is 'NO'.  Otherwise, an
     'events_statements_history_long' value of 'NO' or 'YES' disables or
     enables collection of statement events in the
     'events_statements_history_long'
     table.

*Transaction Event Consumers*

These consumers require both 'global_instrumentation' and
'thread_instrumentation' to be 'YES' or they are not checked.  If
checked, they act as follows:

   * 'events_transactions_current', if 'NO', disables collection of
     individual transaction events in the
     'events_transactions_current'.
     table.  If 'YES', it enables transaction event collection and the
     Performance Schema checks the 'events_transactions_history' and
     'events_transactions_history_long' consumers.

   * 'events_transactions_history' is not checked if
     'events_transactions_current' is 'NO'.  Otherwise, an
     'events_transactions_history' value of 'NO' or 'YES' disables or
     enables collection of transaction events in the
     'events_transactions_history'.
     table.

   * 'events_transactions_history_long' is not checked if
     'events_transactions_current' is 'NO'.  Otherwise, an
     'events_transactions_history_long' value of 'NO' or 'YES' disables
     or enables collection of transaction events in the
     'events_transactions_history_long'
     table.

*Statement Digest Consumer*

The 'statements_digest' consumer requires 'global_instrumentation' to be
'YES' or it is not checked.  There is no dependency on the statement
event consumers, so you can obtain statistics per digest without having
to collect statistics in 'events_statements_current',
which is advantageous in terms of
overhead.  Conversely, you can get detailed statements in
'events_statements_current' without
digests (the 'DIGEST' and 'DIGEST_TEXT' columns will be 'NULL').

For more information about statement digesting, see
performance-schema-statement-digests.

25.4.8 Example Consumer Configurations
--------------------------------------

The consumer settings in the 'setup_consumers'
table form a hierarchy from higher levels to
lower.  The following discussion describes how consumers work, showing
specific configurations and their effects as consumer settings are
enabled progressively from high to low.  The consumer values shown are
representative.  The general principles described here apply to other
consumer values that may be available.

The configuration descriptions occur in order of increasing
functionality and overhead.  If you do not need the information provided
by enabling lower-level settings, disable them and the Performance
Schema will execute less code on your behalf and you will have less
information to sift through.

The 'setup_consumers' table contains the
following hierarchy of values:

     global_instrumentation
      thread_instrumentation
        events_waits_current
          events_waits_history
          events_waits_history_long
        events_stages_current
          events_stages_history
          events_stages_history_long
        events_statements_current
          events_statements_history
          events_statements_history_long
        events_transactions_current
          events_transactions_history
          events_transactions_history_long
      statements_digest

*Note*:

In the consumer hierarchy, the consumers for waits, stages, statements,
and transactions are all at the same level.  This differs from the event
nesting hierarchy, for which wait events nest within stage events, which
nest within statement events, which nest within transaction events.

If a given consumer setting is 'NO', the Performance Schema disables the
instrumentation associated with the consumer and ignores all lower-level
settings.  If a given setting is 'YES', the Performance Schema enables
the instrumentation associated with it and checks the settings at the
next lowest level.  For a description of the rules for each consumer,
see performance-schema-consumer-filtering.

For example, if 'global_instrumentation' is enabled,
'thread_instrumentation' is checked.  If 'thread_instrumentation' is
enabled, the 'events_XXX_current' consumers are checked.  If of these
'events_waits_current' is enabled, 'events_waits_history' and
'events_waits_history_long' are checked.

Each of the following configuration descriptions indicates which setup
elements the Performance Schema checks and which output tables it
maintains (that is, for which tables it collects information).

   *
     performance-schema-consumer-configurations-no-instrumentation

   *
     performance-schema-consumer-configurations-global-instrumentation-only

   *
     performance-schema-consumer-configurations-global-and-thread-instrumentation-only

   *
     performance-schema-consumer-configurations-global-thread-and-current-event-instrumentation

   *
     performance-schema-consumer-configurations-global-thread-current-event-and-event-history-instrumentation

*No Instrumentation*

Server configuration state:

     mysql> SELECT * FROM setup_consumers;
     +---------------------------+---------+
     | NAME                      | ENABLED |
     +---------------------------+---------+
     | global_instrumentation    | NO      |
     ...
     +---------------------------+---------+

In this configuration, nothing is instrumented.

Setup elements checked:

   * Table 'setup_consumers', consumer
     'global_instrumentation'

Output tables maintained:

   * None

*Global Instrumentation Only*

Server configuration state:

     mysql> SELECT * FROM setup_consumers;
     +---------------------------+---------+
     | NAME                      | ENABLED |
     +---------------------------+---------+
     | global_instrumentation    | YES     |
     | thread_instrumentation    | NO      |
     ...
     +---------------------------+---------+

In this configuration, instrumentation is maintained only for global
states.  Per-thread instrumentation is disabled.

Additional setup elements checked, relative to the preceding
configuration:

   * Table 'setup_consumers', consumer
     'thread_instrumentation'

   * Table 'setup_instruments'.

   * Table 'setup_objects'.

   * Table 'setup_timers'.

Additional output tables maintained, relative to the preceding
configuration:

   * 'mutex_instances'.

   * 'rwlock_instances'.

   * 'cond_instances'.

   * 'file_instances'.

   * 'users'.

   * 'hosts'.

   * 'accounts'.

   * 'socket_summary_by_event_name'.

   * 'file_summary_by_instance'.

   * 'file_summary_by_event_name'.

   * 'objects_summary_global_by_type'.

   * 'memory_summary_global_by_event_name'.

   * 'table_lock_waits_summary_by_table'.

   * 'table_io_waits_summary_by_index_usage'.

   * 'table_io_waits_summary_by_table'.

   * 'events_waits_summary_by_instance'.

   * 'events_waits_summary_global_by_event_name'.

   * 'events_stages_summary_global_by_event_name'.

   * 'events_statements_summary_global_by_event_name'.

   * 'events_transactions_summary_global_by_event_name'.

*Global and Thread Instrumentation Only*

Server configuration state:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | events_waits_current             | NO      |
     ...
     | events_stages_current            | NO      |
     ...
     | events_statements_current        | NO      |
     ...
     | events_transactions_current      | NO      |
     ...
     +----------------------------------+---------+

In this configuration, instrumentation is maintained globally and per
thread.  No individual events are collected in the current-events or
event-history tables.

Additional setup elements checked, relative to the preceding
configuration:

   * Table 'setup_consumers', consumers
     'events_XXX_current', where XXX is 'waits', 'stages', 'statements',
     'transactions'

   * Table 'setup_actors'.

   * Column 'threads.instrumented'

Additional output tables maintained, relative to the preceding
configuration:

   * 'events_XXX_summary_by_YYY_by_event_name', where XXX is 'waits',
     'stages', 'statements', 'transactions'; and YYY is 'thread',
     'user', 'host', 'account'

*Global, Thread, and Current-Event Instrumentation*

Server configuration state:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | events_waits_current             | YES     |
     | events_waits_history             | NO      |
     | events_waits_history_long        | NO      |
     | events_stages_current            | YES     |
     | events_stages_history            | NO      |
     | events_stages_history_long       | NO      |
     | events_statements_current        | YES     |
     | events_statements_history        | YES     |
     | events_statements_history_long   | NO      |
     | events_transactions_current      | YES     |
     | events_transactions_history      | YES     |
     | events_transactions_history_long | NO      |
     ...
     +----------------------------------+---------+

In this configuration, instrumentation is maintained globally and per
thread.  Individual events are collected in the current-events table,
but not in the event-history tables.

Additional setup elements checked, relative to the preceding
configuration:

   * Consumers 'events_XXX_history', where XXX is 'waits', 'stages',
     'statements', 'transactions'

   * Consumers 'events_XXX_history_long', where XXX is 'waits',
     'stages', 'statements', 'transactions'

Additional output tables maintained, relative to the preceding
configuration:

   * 'events_XXX_current', where XXX is 'waits', 'stages', 'statements',
     'transactions'

*Global, Thread, Current-Event, and Event-History instrumentation*

The preceding configuration collects no event history because the
'events_XXX_history' and 'events_XXX_history_long' consumers are
disabled.  Those consumers can be enabled separately or together to
collect event history per thread, globally, or both.

This configuration collects event history per thread, but not globally:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | events_waits_current             | YES     |
     | events_waits_history             | YES     |
     | events_waits_history_long        | NO      |
     | events_stages_current            | YES     |
     | events_stages_history            | YES     |
     | events_stages_history_long       | NO      |
     | events_statements_current        | YES     |
     | events_statements_history        | YES     |
     | events_statements_history_long   | NO      |
     | events_transactions_current      | YES     |
     | events_transactions_history      | YES     |
     | events_transactions_history_long | NO      |
     ...
     +----------------------------------+---------+

Event-history tables maintained for this configuration:

   * 'events_XXX_history', where XXX is 'waits', 'stages', 'statements',
     'transactions'

This configuration collects event history globally, but not per thread:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | events_waits_current             | YES     |
     | events_waits_history             | NO      |
     | events_waits_history_long        | YES     |
     | events_stages_current            | YES     |
     | events_stages_history            | NO      |
     | events_stages_history_long       | YES     |
     | events_statements_current        | YES     |
     | events_statements_history        | YES     |
     | events_statements_history_long   | YES     |
     | events_transactions_current      | YES     |
     | events_transactions_history      | YES     |
     | events_transactions_history_long | YES     |
     ...
     +----------------------------------+---------+

Event-history tables maintained for this configuration:

   * 'events_XXX_history_long', where XXX is 'waits', 'stages',
     'statements', 'transactions'

This configuration collects event history per thread and globally:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | events_waits_current             | YES     |
     | events_waits_history             | YES     |
     | events_waits_history_long        | YES     |
     | events_stages_current            | YES     |
     | events_stages_history            | YES     |
     | events_stages_history_long       | YES     |
     | events_statements_current        | YES     |
     | events_statements_history        | YES     |
     | events_statements_history_long   | YES     |
     | events_transactions_current      | YES     |
     | events_transactions_history      | YES     |
     | events_transactions_history_long | YES     |
     ...
     +----------------------------------+---------+

Event-history tables maintained for this configuration:

   * 'events_XXX_history', where XXX is 'waits', 'stages', 'statements',
     'transactions'

   * 'events_XXX_history_long', where XXX is 'waits', 'stages',
     'statements', 'transactions'

25.4.9 Naming Instruments or Consumers for Filtering Operations
---------------------------------------------------------------

Names given for filtering operations can be as specific or general as
required.  To indicate a single instrument or consumer, specify its name
in full:

     mysql> UPDATE setup_instruments
            SET ENABLED = 'NO'
            WHERE NAME = 'wait/synch/mutex/myisammrg/MYRG_INFO::mutex';

     mysql> UPDATE setup_consumers
            SET ENABLED = 'NO' WHERE NAME = 'events_waits_current';

To specify a group of instruments or consumers, use a pattern that
matches the group members:

     mysql> UPDATE setup_instruments
            SET ENABLED = 'NO'
            WHERE NAME LIKE 'wait/synch/mutex/%';

     mysql> UPDATE setup_consumers
            SET ENABLED = 'NO' WHERE NAME LIKE '%history%';

If you use a pattern, it should be chosen so that it matches all the
items of interest and no others.  For example, to select all file I/O
instruments, it is better to use a pattern that includes the entire
instrument name prefix:

     ... WHERE NAME LIKE 'wait/io/file/%';

A pattern of ''%/file/%'' will match other instruments that have a
component of ''/file/'' anywhere in the name.  Even less suitable is the
pattern ''%file%'' because it will match instruments with ''file''
anywhere in the name, such as 'wait/synch/mutex/innodb/file_open_mutex'.

To check which instrument or consumer names a pattern matches, perform a
simple test:

     mysql> SELECT NAME FROM setup_instruments WHERE NAME LIKE 'PATTERN';

     mysql> SELECT NAME FROM setup_consumers WHERE NAME LIKE 'PATTERN';

For information about the types of names that are supported, see
performance-schema-instrument-naming.

25.4.10 Determining What Is Instrumented
----------------------------------------

It is always possible to determine what instruments the Performance
Schema includes by checking the 'setup_instruments'
table.  For example, to see what file-related
events are instrumented for the 'InnoDB' storage engine, use this query:

     mysql> SELECT * FROM setup_instruments WHERE NAME LIKE 'wait/io/file/innodb/%';
     +--------------------------------------+---------+-------+
     | NAME                                 | ENABLED | TIMED |
     +--------------------------------------+---------+-------+
     | wait/io/file/innodb/innodb_data_file | YES     | YES   |
     | wait/io/file/innodb/innodb_log_file  | YES     | YES   |
     | wait/io/file/innodb/innodb_temp_file | YES     | YES   |
     +--------------------------------------+---------+-------+

An exhaustive description of precisely what is instrumented is not given
in this documentation, for several reasons:

   * What is instrumented is the server code.  Changes to this code
     occur often, which also affects the set of instruments.

   * It is not practical to list all the instruments because there are
     hundreds of them.

   * As described earlier, it is possible to find out by querying the
     'setup_instruments' table.  This
     information is always up to date for your version of MySQL, also
     includes instrumentation for instrumented plugins you might have
     installed that are not part of the core server, and can be used by
     automated tools.

25.5 Performance Schema Queries
===============================

Pre-filtering limits which event information is collected and is
independent of any particular user.  By contrast, post-filtering is
performed by individual users through the use of queries with
appropriate 'WHERE' clauses that restrict what event information to
select from the events available after pre-filtering has been applied.

In performance-schema-pre-filtering, an example showed how to
pre-filter for file instruments.  If the event tables contain both file
and nonfile information, post-filtering is another way to see
information only for file events.  Add a 'WHERE' clause to queries to
restrict event selection appropriately:

     mysql> SELECT THREAD_ID, NUMBER_OF_BYTES
            FROM events_waits_history
            WHERE EVENT_NAME LIKE 'wait/io/file/%'
            AND NUMBER_OF_BYTES IS NOT NULL;
     +-----------+-----------------+
     | THREAD_ID | NUMBER_OF_BYTES |
     +-----------+-----------------+
     |        11 |              66 |
     |        11 |              47 |
     |        11 |             139 |
     |         5 |              24 |
     |         5 |             834 |
     +-----------+-----------------+

25.6 Performance Schema Instrument Naming Conventions
=====================================================

An instrument name consists of a sequence of components separated by
''/'' characters.  Example names:

     wait/io/file/myisam/log
     wait/io/file/mysys/charset
     wait/lock/table/sql/handler
     wait/synch/cond/mysys/COND_alarm
     wait/synch/cond/sql/BINLOG::update_cond
     wait/synch/mutex/mysys/BITMAP_mutex
     wait/synch/mutex/sql/LOCK_delete
     wait/synch/rwlock/sql/Query_cache_query::lock
     stage/sql/closing tables
     stage/sql/Sorting result
     statement/com/Execute
     statement/com/Query
     statement/sql/create_table
     statement/sql/lock_tables

The instrument name space has a tree-like structure.  The components of
an instrument name from left to right provide a progression from more
general to more specific.  The number of components a name has depends
on the type of instrument.

The interpretation of a given component in a name depends on the
components to the left of it.  For example, 'myisam' appears in both of
the following names, but 'myisam' in the first name is related to file
I/O, whereas in the second it is related to a synchronization
instrument:

     wait/io/file/myisam/log
     wait/synch/cond/myisam/MI_SORT_INFO::cond

Instrument names consist of a prefix with a structure defined by the
Performance Schema implementation and a suffix defined by the developer
implementing the instrument code.  The top-level component of an
instrument prefix indicates the type of instrument.  This component also
determines which event timer in the 'setup_timers' table applies to the
instrument.  For the prefix part of instrument names, the top level
indicates the type of instrument.

The suffix part of instrument names comes from the code for the
instruments themselves.  Suffixes may include levels such as these:

   * A name for the major component (a server module such as 'myisam',
     'innodb', 'mysys', or 'sql') or a plugin name.

   * The name of a variable in the code, in the form XXX (a global
     variable) or 'CCC::MMM' (a member MMM in class CCC).  Examples:
     'COND_thread_cache', 'THR_LOCK_myisam', 'BINLOG::LOCK_index'.

   * performance-schema-top-level-instrument-components

   * performance-schema-idle-instrument-components

   * performance-schema-memory-instrument-components

   * performance-schema-stage-instrument-components

   * performance-schema-statement-instrument-components

   * performance-schema-wait-instrument-components

*Top-Level Instrument Components*

   * 'idle': An instrumented idle event.  This instrument has no further
     components.

   * 'memory': An instrumented memory event.

   * 'stage': An instrumented stage event.

   * 'statement': An instrumented statement event.

   * 'transaction': An instrumented transaction event.  This instrument
     has no further components.

   * 'wait': An instrumented wait event.

*Idle Instrument Components*

The 'idle' instrument is used for idle events, which The Performance
Schema generates as discussed in the description of the
'socket_instances.STATE' column in socket-instances-table.

*Memory Instrument Components*

Most memory instrumentation is disabled by default, and can be enabled
or disabled at startup, or dynamically at runtime by updating the
'ENABLED' column of the relevant instruments in the
'setup_instruments' table.  Memory instruments
have names of the form 'memory/CODE_AREA/INSTRUMENT_NAME' where
CODE_AREA is a value such as 'sql' or 'myisam', and INSTRUMENT_NAME is
the instrument detail.

Instruments named with the prefix 'memory/performance_schema/' expose
how much memory is allocated for internal buffers in the Performance
Schema.  The 'memory/performance_schema/' instruments are built in,
always enabled, and cannot be disabled at startup or runtime.  Built-in
memory instruments are displayed only in the
'memory_summary_global_by_event_name' table.
For more information, see performance-schema-memory-model.

*Stage Instrument Components*

Stage instruments have names of the form 'stage/CODE_AREA/STAGE_NAME',
where CODE_AREA is a value such as 'sql' or 'myisam', and STAGE_NAME
indicates the stage of statement processing, such as 'Sorting result' or
'Sending data'.  Stages correspond to the thread states displayed by
'SHOW PROCESSLIST' or that are visible in the
'INFORMATION_SCHEMA.PROCESSLIST' table.

*Statement Instrument Components*

   * 'statement/abstract/*': An abstract instrument for statement
     operations.  Abstract instruments are used during the early stages
     of statement classification before the exact statement type is
     known, then changed to a more specific statement instrument when
     the type is known.  For a description of this process, see
     performance-schema-statement-tables.

   * 'statement/com': An instrumented command operation.  These have
     names corresponding to 'COM_XXX' operations (see the 'mysql_com.h'
     header file and 'sql/sql_parse.cc'.  For example, the
     'statement/com/Connect' and 'statement/com/Init DB' instruments
     correspond to the 'COM_CONNECT' and 'COM_INIT_DB' commands.

   * 'statement/scheduler/event': A single instrument to track all
     events executed by the Event Scheduler.  This instrument comes into
     play when a scheduled event begins executing.

   * 'statement/sp': An instrumented internal instruction executed by a
     stored program.  For example, the 'statement/sp/cfetch' and
     'statement/sp/freturn' instruments are used cursor fetch and
     function return instructions.

   * 'statement/sql': An instrumented SQL statement operation.  For
     example, the 'statement/sql/create_db' and 'statement/sql/select'
     instruments are used for 'CREATE DATABASE'.
     and 'SELECT' statements.

*Wait Instrument Components*

   * 'wait/io'

     An instrumented I/O operation.

        * 'wait/io/file'

          An instrumented file I/O operation.  For files, the wait is
          the time waiting for the file operation to complete (for
          example, a call to 'fwrite()').  Due to caching, the physical
          file I/O on the disk might not happen within this call.

        * 'wait/io/socket'

          An instrumented socket operation.  Socket instruments have
          names of the form 'wait/io/socket/sql/SOCKET_TYPE'.  The
          server has a listening socket for each network protocol that
          it supports.  The instruments associated with listening
          sockets for TCP/IP or Unix socket file connections have a
          SOCKET_TYPE value of 'server_tcpip_socket' or
          'server_unix_socket', respectively.  When a listening socket
          detects a connection, the server transfers the connection to a
          new socket managed by a separate thread.  The instrument for
          the new connection thread has a SOCKET_TYPE value of
          'client_connection'.

        * 'wait/io/table'

          An instrumented table I/O operation.  These include row-level
          accesses to persistent base tables or temporary tables.
          Operations that affect rows are fetch, insert, update, and
          delete.  For a view, waits are associated with base tables
          referenced by the view.

          Unlike most waits, a table I/O wait can include other waits.
          For example, table I/O might include file I/O or memory
          operations.  Thus, see 'events_waits_current'
          for a table I/O wait usually has
          two rows.  For more information, see
          performance-schema-atom-molecule-events.

          Some row operations might cause multiple table I/O waits.  For
          example, an insert might activate a trigger that causes an
          update.

   * 'wait/lock'

     An instrumented lock operation.

        * 'wait/lock/table'

          An instrumented table lock operation.

        * 'wait/lock/metadata/sql/mdl'

          An instrumented metadata lock operation.

   * 'wait/synch'

     An instrumented synchronization object.  For synchronization
     objects, the 'TIMER_WAIT' time includes the amount of time blocked
     while attempting to acquire a lock on the object, if any.

        * 'wait/synch/cond'

          A condition is used by one thread to signal to other threads
          that something they were waiting for has happened.  If a
          single thread was waiting for a condition, it can wake up and
          proceed with its execution.  If several threads were waiting,
          they can all wake up and compete for the resource for which
          they were waiting.

        * 'wait/synch/mutex'

          A mutual exclusion object used to permit access to a resource
          (such as a section of executable code) while preventing other
          threads from accessing the resource.

        * 'wait/synch/rwlock'

          A read/write lock object used to lock a specific variable for
          access while preventing its use by other threads.  A shared
          read lock can be acquired simultaneously by multiple threads.
          An exclusive write lock can be acquired by only one thread at
          a time.

        * 'wait/synch/sxlock'

          A shared-exclusive (SX) lock is a type of rwlock lock object
          that provides write access to a common resource while
          permitting inconsistent reads by other threads.  'sxlocks'
          optimize concurrency and improve scalability for read-write
          workloads.

25.7 Performance Schema Status Monitoring
=========================================

There are several status variables associated with the Performance
Schema:

     mysql> SHOW STATUS LIKE 'perf%';
     +-----------------------------------------------+-------+
     | Variable_name                                 | Value |
     +-----------------------------------------------+-------+
     | Performance_schema_accounts_lost              | 0     |
     | Performance_schema_cond_classes_lost          | 0     |
     | Performance_schema_cond_instances_lost        | 0     |
     | Performance_schema_digest_lost                | 0     |
     | Performance_schema_file_classes_lost          | 0     |
     | Performance_schema_file_handles_lost          | 0     |
     | Performance_schema_file_instances_lost        | 0     |
     | Performance_schema_hosts_lost                 | 0     |
     | Performance_schema_locker_lost                | 0     |
     | Performance_schema_memory_classes_lost        | 0     |
     | Performance_schema_metadata_lock_lost         | 0     |
     | Performance_schema_mutex_classes_lost         | 0     |
     | Performance_schema_mutex_instances_lost       | 0     |
     | Performance_schema_nested_statement_lost      | 0     |
     | Performance_schema_program_lost               | 0     |
     | Performance_schema_rwlock_classes_lost        | 0     |
     | Performance_schema_rwlock_instances_lost      | 0     |
     | Performance_schema_session_connect_attrs_lost | 0     |
     | Performance_schema_socket_classes_lost        | 0     |
     | Performance_schema_socket_instances_lost      | 0     |
     | Performance_schema_stage_classes_lost         | 0     |
     | Performance_schema_statement_classes_lost     | 0     |
     | Performance_schema_table_handles_lost         | 0     |
     | Performance_schema_table_instances_lost       | 0     |
     | Performance_schema_thread_classes_lost        | 0     |
     | Performance_schema_thread_instances_lost      | 0     |
     | Performance_schema_users_lost                 | 0     |
     +-----------------------------------------------+-------+

The Performance Schema status variables provide information about
instrumentation that could not be loaded or created due to memory
constraints.  Names for these variables have several forms:

   * 'Performance_schema_XXX_classes_lost' indicates how many
     instruments of type XXX could not be loaded.

   * 'Performance_schema_XXX_instances_lost' indicates how many
     instances of object type XXX could not be created.

   * 'Performance_schema_XXX_handles_lost' indicates how many instances
     of object type XXX could not be opened.

   * 'Performance_schema_locker_lost' indicates how many events are
     'lost' or not recorded.

For example, if a mutex is instrumented in the server source but the
server cannot allocate memory for the instrumentation at runtime, it
increments 'Performance_schema_mutex_classes_lost'.  The mutex still
functions as a synchronization object (that is, the server continues to
function normally), but performance data for it will not be collected.
If the instrument can be allocated, it can be used for initializing
instrumented mutex instances.  For a singleton mutex such as a global
mutex, there will be only one instance.  Other mutexes have an instance
per connection, or per page in various caches and data buffers, so the
number of instances varies over time.  Increasing the maximum number of
connections or the maximum size of some buffers will increase the
maximum number of instances that might be allocated at once.  If the
server cannot create a given instrumented mutex instance, it increments
'Performance_schema_mutex_instances_lost'.

Suppose that the following conditions hold:

   * The server was started with the
     '--performance_schema_max_mutex_classes=200' option and thus has
     room for 200 mutex instruments.

   * 150 mutex instruments have been loaded already.

   * The plugin named 'plugin_a' contains 40 mutex instruments.

   * The plugin named 'plugin_b' contains 20 mutex instruments.

The server allocates mutex instruments for the plugins depending on how
many they need and how many are available, as illustrated by the
following sequence of statements:

     INSTALL PLUGIN plugin_a

The server now has 150+40 = 190 mutex instruments.

     UNINSTALL PLUGIN plugin_a;

The server still has 190 instruments.  All the historical data generated
by the plugin code is still available, but new events for the
instruments are not collected.

     INSTALL PLUGIN plugin_a;

The server detects that the 40 instruments are already defined, so no
new instruments are created, and previously assigned internal memory
buffers are reused.  The server still has 190 instruments.

     INSTALL PLUGIN plugin_b;

The server has room for 200-190 = 10 instruments (in this case, mutex
classes), and sees that the plugin contains 20 new instruments.  10
instruments are loaded, and 10 are discarded or 'lost.' The
'Performance_schema_mutex_classes_lost' indicates the number of
instruments (mutex classes) lost:

     mysql> SHOW STATUS LIKE "perf%mutex_classes_lost";
     +---------------------------------------+-------+
     | Variable_name                         | Value |
     +---------------------------------------+-------+
     | Performance_schema_mutex_classes_lost | 10    |
     +---------------------------------------+-------+
     1 row in set (0.10 sec)

The instrumentation still works and collects (partial) data for
'plugin_b'.

When the server cannot create a mutex instrument, these results occur:

   * No row for the instrument is inserted into the
     'setup_instruments' table.

   * 'Performance_schema_mutex_classes_lost' increases by 1.

   * 'Performance_schema_mutex_instances_lost' does not change.  (When
     the mutex instrument is not created, it cannot be used to create
     instrumented mutex instances later.)

The pattern just described applies to all types of instruments, not just
mutexes.

A value of 'Performance_schema_mutex_classes_lost' greater than 0 can
happen in two cases:

   * To save a few bytes of memory, you start the server with
     '--performance_schema_max_mutex_classes=N', where N is less than
     the default value.  The default value is chosen to be sufficient to
     load all the plugins provided in the MySQL distribution, but this
     can be reduced if some plugins are never loaded.  For example, you
     might choose not to load some of the storage engines in the
     distribution.

   * You load a third-party plugin that is instrumented for the
     Performance Schema but do not allow for the plugin's
     instrumentation memory requirements when you start the server.
     Because it comes from a third party, the instrument memory
     consumption of this engine is not accounted for in the default
     value chosen for 'performance_schema_max_mutex_classes'.

     If the server has insufficient resources for the plugin's
     instruments and you do not explicitly allocate more using
     '--performance_schema_max_mutex_classes=N', loading the plugin
     leads to starvation of instruments.

If the value chosen for 'performance_schema_max_mutex_classes' is too
small, no error is reported in the error log and there is no failure at
runtime.  However, the content of the tables in the 'performance_schema'
database will miss events.  The 'Performance_schema_mutex_classes_lost'
status variable is the only visible sign to indicate that some events
were dropped internally due to failure to create instruments.

If an instrument is not lost, it is known to the Performance Schema, and
is used when instrumenting instances.  For example,
'wait/synch/mutex/sql/LOCK_delete' is the name of a mutex instrument in
the 'setup_instruments' table.  This
single instrument is used when creating a mutex in the code (in
'THD::LOCK_delete') however many instances of the mutex are needed as
the server runs.  In this case, 'LOCK_delete' is a mutex that is per
connection ('THD'), so if a server has 1000 connections, there are 1000
threads, and 1000 instrumented 'LOCK_delete' mutex instances
('THD::LOCK_delete').

If the server does not have room for all these 1000 instrumented mutexes
(instances), some mutexes are created with instrumentation, and some are
created without instrumentation.  If the server can create only 800
instances, 200 instances are lost.  The server continues to run, but
increments 'Performance_schema_mutex_instances_lost' by 200 to indicate
that instances could not be created.

A value of 'Performance_schema_mutex_instances_lost' greater than 0 can
happen when the code initializes more mutexes at runtime than were
allocated for '--performance_schema_max_mutex_instances=N'.

The bottom line is that if 'SHOW STATUS LIKE 'perf%''
says that nothing was lost (all values are zero), the
Performance Schema data is accurate and can be relied upon.  If
something was lost, the data is incomplete, and the Performance Schema
could not record everything given the insufficient amount of memory it
was given to use.  In this case, the specific
'Performance_schema_XXX_lost' variable indicates the problem area.

It might be appropriate in some cases to cause deliberate instrument
starvation.  For example, if you do not care about performance data for
file I/O, you can start the server with all Performance Schema
parameters related to file I/O set to 0.  No memory will be allocated
for file-related classes, instances, or handles, and all file events
will be lost.

Use 'SHOW ENGINE PERFORMANCE_SCHEMA STATUS' to
inspect the internal operation of the Performance Schema code:

     mysql> SHOW ENGINE PERFORMANCE_SCHEMA STATUS\G
     ...
     *************************** 3. row ***************************
       Type: performance_schema
       Name: events_waits_history.size
     Status: 76
     *************************** 4. row ***************************
       Type: performance_schema
       Name: events_waits_history.count
     Status: 10000
     *************************** 5. row ***************************
       Type: performance_schema
       Name: events_waits_history.memory
     Status: 760000
     ...
     *************************** 57. row ***************************
       Type: performance_schema
       Name: performance_schema.memory
     Status: 26459600
     ...

This statement is intended to help the DBA understand the effects that
different Performance Schema options have on memory requirements.  For a
description of the field meanings, see show-engine.

25.8 Performance Schema Atom and Molecule Events
================================================

For a table I/O event, there are usually two rows in
'events_waits_current', not one.  For
example, a row fetch might result in rows like this:

     Row# EVENT_NAME                 TIMER_START TIMER_END
     ---- ----------                 ----------- ---------
        1 wait/io/file/myisam/dfile        10001 10002
        2 wait/io/table/sql/handler        10000 NULL

The row fetch causes a file read.  In the example, the table I/O fetch
event started before the file I/O event but has not finished (its
'TIMER_END' value is 'NULL').  The file I/O event is 'nested' within the
table I/O event.

This occurs because, unlike other 'atomic' wait events such as for
mutexes or file I/O, table I/O events are 'molecular' and include
(overlap with) other events.  In 'events_waits_current',
the table I/O event usually has two rows:

   * One row for the most recent table I/O wait event

   * One row for the most recent wait event of any kind

Usually, but not always, the 'of any kind' wait event differs from the
table I/O event.  As each subsidiary event completes, it disappears from
'events_waits_current'.  At this
point, and until the next subsidiary event begins, the table I/O wait is
also the most recent wait of any kind.

25.9 Performance Schema Statement Digests
=========================================

The MySQL server is capable of maintaining statement digest information.
The digesting process converts each SQL statement to normalized form
(the statement digest) and computes an MD5 hash value (the digest hash
value) from the normalized result.  Normalization permits statements
that are similar to be grouped and summarized to expose information
about the types of statements the server is executing and how often they
occur.  This section describes how statement digesting occurs and how it
can be useful.

Digesting occurs in the parser regardless of whether the Performance
Schema is available, so that other server components such as MySQL
Enterprise Firewall and query rewrite plugins have access to statement
digests.

   * statement-digests-general

   * statement-digests-performance-schema

   * statement-digests-memory-use

*Statement Digest General Concepts*

When the parser receives an SQL statement, it computes a statement
digest if that digest is needed, which is true if any of the following
conditions are true:

   * Performance Schema digest instrumentation is enabled

   * MySQL Enterprise Firewall is enabled

   * A Query Rewrite Plugin is enabled

The 'max_digest_length' system variable value determines the maximum
number of bytes available for computing normalized statement digests.
Once that amount of space is used during digest computation, truncation
occurs: no further tokens from a parsed statement are collected or
figure into its digest value.  Statements that differ only after that
many bytes of parsed tokens produce the same normalized statement digest
and are considered identical if compared or if aggregated for digest
statistics.

After the normalized statement has been computed, an MD5 hash value is
computed from it.  In addition:

   * If MySQL Enterprise Firewall is enabled, it is called and the
     digest as computed is available to it.

   * If any Query Rewrite Plugin is enabled, it is called and the
     statement digest and digest value are available to it.

   * If the Performance Schema has digest instrumentation enabled, it
     makes a copy of the normalized statement digest, allocating a
     maximum of 'performance_schema_max_digest_length' bytes for it.
     Consequently, if 'performance_schema_max_digest_length' is less
     than 'max_digest_length', the copy is truncated relative to the
     original.  The copy of the normalized statement digest is stored in
     the appropriate Performance Schema tables, along with the MD5 hash
     value computed from the original normalized statement.  (If the
     Performance Schema truncates its copy of the normalized statement
     digest relative to the original, it does not recompute the MD5 hash
     value.)

Statement normalization transforms the statement text to a more
standardized digest string representation that preserves the general
statement structure while removing information not essential to the
structure:

   * Object identifiers such as database and table names are preserved.

   * Literal values are converted to parameter markers.  A normalized
     statement does not retain information such as names, passwords,
     dates, and so forth.

   * Comments are removed and whitespace is adjusted.

Consider these statements:

     SELECT * FROM orders WHERE customer_id=10 AND quantity>20
     SELECT * FROM orders WHERE customer_id = 20 AND quantity > 100

To normalize these statements, the parser replaces data values by '?'
and adjusts whitespace.  Both statements yield the same normalized form
and thus are considered 'the same':

     SELECT * FROM orders WHERE customer_id = ? AND quantity > ?

The normalized statement contains less information but is still
representative of the original statement.  Other similar statements that
have different data values have the same normalized form.

Now consider these statements:

     SELECT * FROM customers WHERE customer_id = 1000
     SELECT * FROM orders WHERE customer_id = 1000

In this case, the normalized statements differ because the object
identifiers differ:

     SELECT * FROM customers WHERE customer_id = ?
     SELECT * FROM orders WHERE customer_id = ?

If normalization produces a statement that exceeds the space available
in the digest buffer (as determined by 'max_digest_length'), truncation
occurs and the text ends with '...'.  Long normalized statements that
differ only in the part that occurs following the '...' are considered
the same.  Consider these statements:

     SELECT * FROM mytable WHERE cola = 10 AND colb = 20
     SELECT * FROM mytable WHERE cola = 10 AND colc = 20

If the cutoff happens to be right after the 'AND', both statements have
this normalized form:

     SELECT * FROM mytable WHERE cola = ? AND ...

In this case, the difference in the second column name is lost and both
statements are considered the same.

*Statement Digests in the Performance Schema*

In the Performance Schema, statement digesting involves these
components:

   * A 'statements_digest' consumer in the 'setup_consumers'
     table controls whether the Performance
     Schema maintains digest information.  See
     performance-schema-consumer-filtering-statement-digest.

   * The statement event tables (see 'events_statements_current',
     see 'events_statements_history',
     and
     'events_statements_history_long')
     have columns for storing
     normalized statement digests and the corresponding digest MD5 hash
     values:

        * 'DIGEST_TEXT' is the text of the normalized statement digest.
          This is a copy of the original normalized statement that was
          computed to a maximum of 'max_digest_length' bytes, further
          truncated as necessary to
          'performance_schema_max_digest_length' bytes.

        * 'DIGEST' is the digest MD5 hash value computed from the
          original normalized statement.

     See performance-schema-statement-tables.

   * The 'events_statements_summary_by_digest'
     summary table provides aggregated
     statement digest information.  This table aggregates information
     for statements per 'SCHEMA_NAME' and 'DIGEST' combination.  The
     Performance Schema uses MD5 hash values for aggregation because
     they are fast to compute and have a favorable statistical
     distribution that minimizes collisions.  See
     statement-summary-tables.

The statement event tables also have an 'SQL_TEXT' column that contains
the original SQL statement.  The maximum space available for statement
display is 1024 bytes by default.  To change this value, set the
'performance_schema_max_sql_text_length' system variable at server
startup.

The 'performance_schema_max_digest_length' system variable determines
the maximum number of bytes available for digest value storage in the
Performance Schema.  However, the display length of statement digests
may be longer than the available buffer size due to internal encoding of
statement components such as keywords and literal values.  Consequently,
values selected from the 'DIGEST_TEXT' column of statement event tables
may appear to exceed the 'performance_schema_max_digest_length' value.

The 'events_statements_summary_by_digest'
summary table provides a profile of the
statements executed by the server.  It shows what kinds of statements an
application is executing and how often.  An application developer can
use this information together with other information in the table to
assess the application's performance characteristics.  For example,
table columns that show wait times, lock times, or index use may
highlight types of queries that are inefficient.  This gives the
developer insight into which parts of the application need attention.

The 'events_statements_summary_by_digest'
summary table has a fixed size.  By default
the Performance Schema estimates the size to use at startup.  To specify
the table size explicitly, set the 'performance_schema_digests_size'
system variable at server startup.  If the table becomes full, the
Performance Schema groups statements that have 'SCHEMA_NAME' and
'DIGEST' values not matching existing values in the table in a special
row with 'SCHEMA_NAME' and 'DIGEST' set to 'NULL'.  This permits all
statements to be counted.  However, if the special row accounts for a
significant percentage of the statements executed, it might be desirable
to increase the summary table size by increasing
'performance_schema_digests_size'.

*Statement Digest Memory Use*

For applications that generate very long statements that differ only at
the end, increasing 'max_digest_length' enables computation of digests
that distinguish statements that would otherwise aggregate to the same
digest.  Conversely, decreasing 'max_digest_length' causes the server to
devote less memory to digest storage but increases the likelihood of
longer statements aggregating to the same digest.  Administrators should
keep in mind that larger values result in correspondingly increased
memory requirements, particularly for workloads that involve large
numbers of simultaneous sessions (the server allocates
'max_digest_length' bytes per session).

As described previously, normalized statement digests as computed by the
parser are constrained to a maximum of 'max_digest_length' bytes,
whereas normalized statement digests stored in the Performance Schema
use 'performance_schema_max_digest_length' bytes.  The following
memory-use considerations apply regarding the relative values of
'max_digest_length' and 'performance_schema_max_digest_length':

   * If 'max_digest_length' is less than
     'performance_schema_max_digest_length':

        * Server components other than the Performance Schema use
          normalized statement digests that take up to
          'max_digest_length' bytes.

        * The Performance Schema does not further truncate normalized
          statement digests that it stores, but allocates more memory
          than 'max_digest_length' bytes per digest, which is
          unnecessary.

   * If 'max_digest_length' equals
     'performance_schema_max_digest_length':

        * Server components other than the Performance Schema use
          normalized statement digests that take up to
          'max_digest_length' bytes.

        * The Performance Schema does not further truncate normalized
          statement digests that it stores, and allocates the same
          amount of memory as 'max_digest_length' bytes per digest.

   * If 'max_digest_length' is greater than
     'performance_schema_max_digest_length':

        * Server components other than the Performance Schema use
          normalized statement digests that take up to
          'max_digest_length' bytes.

        * The Performance Schema further truncates normalized statement
          digests that it stores, and allocates less memory than
          'max_digest_length' bytes per digest.

Because the Performance Schema statement event tables might store many
digests, setting 'performance_schema_max_digest_length' smaller than
'max_digest_length' enables administrators to balance these factors:

   * The need to have long normalized statement digests available for
     server components outside the Performance Schema

   * Many concurrent sessions, each of which allocates
     digest-computation memory

   * The need to limit memory consumption by the Performance Schema
     statement event tables when storing many statement digests

To assess the amount of memory used for SQL statement storage and digest
computation, use the 'SHOW ENGINE PERFORMANCE_SCHEMA STATUS'
statement, or monitor these instruments:

     mysql> SELECT NAME FROM setup_instruments
            WHERE NAME LIKE '%.sqltext';
     +------------------------------------------------------------------+
     | NAME                                                             |
     +------------------------------------------------------------------+
     | memory/performance_schema/events_statements_history.sqltext      |
     | memory/performance_schema/events_statements_current.sqltext      |
     | memory/performance_schema/events_statements_history_long.sqltext |
     +------------------------------------------------------------------+

     mysql> SELECT NAME FROM setup_instruments
            WHERE NAME LIKE 'memory/performance_schema/%.tokens';
     +----------------------------------------------------------------------+
     | NAME                                                                 |
     +----------------------------------------------------------------------+
     | memory/performance_schema/events_statements_history.tokens           |
     | memory/performance_schema/events_statements_current.tokens           |
     | memory/performance_schema/events_statements_summary_by_digest.tokens |
     | memory/performance_schema/events_statements_history_long.tokens      |
     +----------------------------------------------------------------------+

25.10 Performance Schema General Table Characteristics
======================================================

The name of the 'performance_schema' database is lowercase, as are the
names of tables within it.  Queries should specify the names in
lowercase.

Many tables in the 'performance_schema' database are read only and
cannot be modified:

     mysql> TRUNCATE TABLE setup_instruments;
     ERROR 1683 (HY000): Invalid performance_schema usage.

Some of the setup tables have columns that can be modified to affect
Performance Schema operation; some also permit rows to be inserted or
deleted.  Truncation is permitted to clear collected events, so
'TRUNCATE TABLE' can be used on tables containing those
kinds of information, such as tables named with a prefix of
'events_waits_'.

Summary tables can be truncated with 'TRUNCATE TABLE'.
Generally, the effect is to reset the summary columns
to 0 or 'NULL', not to remove rows.  This enables you to clear collected
values and restart aggregation.  That might be useful, for example,
after you have made a runtime configuration change.  Exceptions to this
truncation behavior are noted in individual summary table sections.

Privileges are as for other databases and tables:

   * To retrieve from 'performance_schema' tables, you must have the
     'SELECT' privilege.

   * To change those columns that can be modified, you must have the
     'UPDATE' privilege.

   * To truncate tables that can be truncated, you must have the 'DROP'
     privilege.

Because only a limited set of privileges apply to Performance Schema
tables, attempts to use 'GRANT ALL' as shorthand for granting privileges
at the database or table leval fail with an error:

     mysql> GRANT ALL ON performance_schema.*
            TO 'u1'@'localhost';
     ERROR 1044 (42000): Access denied for user 'root'@'localhost'
     to database 'performance_schema'
     mysql> GRANT ALL ON performance_schema.setup_instruments
            TO 'u2'@'localhost';
     ERROR 1044 (42000): Access denied for user 'root'@'localhost'
     to database 'performance_schema'

Instead, grant exactly the desired privileges:

     mysql> GRANT SELECT ON performance_schema.*
            TO 'u1'@'localhost';
     Query OK, 0 rows affected (0.03 sec)

     mysql> GRANT SELECT, UPDATE ON performance_schema.setup_instruments
            TO 'u2'@'localhost';
     Query OK, 0 rows affected (0.02 sec)

25.11 Performance Schema Table Descriptions
===========================================

Tables in the 'performance_schema' database can be grouped as follows:

   * Setup tables.  These tables are used to configure and display
     monitoring characteristics.

   * Current events tables.  The 'events_waits_current'
     table contains the most recent event
     for each thread.  Other similar tables contain current events at
     different levels of the event hierarchy:
     'events_stages_current' for stage
     events, see 'events_statements_current'
     for statement events, and
     'events_transactions_current'.
     for transaction events.

   * History tables.  These tables have the same structure as the
     current events tables, but contain more rows.  For example, for
     wait events, see 'events_waits_history'
     table contains the most recent 10
     events per thread.  'events_waits_history_long'
     contains the most recent 10,000
     events.  Other similar tables exist for stage, statement, and
     transaction histories.

     To change the sizes of the history tables, set the appropriate
     system variables at server startup.  For example, to set the sizes
     of the wait event history tables, set
     'performance_schema_events_waits_history_size' and
     'performance_schema_events_waits_history_long_size'.

   * Summary tables.  These tables contain information aggregated over
     groups of events, including those that have been discarded from the
     history tables.

   * Instance tables.  These tables document what types of objects are
     instrumented.  An instrumented object, when used by the server,
     produces an event.  These tables provide event names and
     explanatory notes or status information.

   * Miscellaneous tables.  These do not fall into any of the other
     table groups.

25.11.1 Performance Schema Table Index
--------------------------------------

The following table lists each Performance Schema table and provides a
short description of each one.

*Performance Schema Tables*

Table Name                               Description

See 'accounts'.        Connection statistics per
                                         client account

See 'cond_instances'.
            instances

See 'events_stages_current'.

See 'events_stages_history'.
     each thread

See 'events_stages_history_long'.
overall

See Stage events per account and 'events_stages_summary_by_account_by_event_name'.

See Stage events per host name and 'events_stages_summary_by_host_by_event_name'.

See Stage waits per thread and 'events_stages_summary_by_thread_by_event_name'.

See Stage events per user name and 'events_stages_summary_by_user_by_event_name'.

See Stage waits per event name 'events_stages_summary_global_by_event_name'.

See 'events_statements_current'.

See 'events_statements_history'.
 for each thread

See Most recent statement events 'events_statements_history_long'.

See Statement events per account 'events_statements_summary_by_account_by_event_name'.

See Statement events per schema 'events_statements_summary_by_digest'.

See Statement events per host name 'events_statements_summary_by_host_by_event_name'.

See Statement events per stored 'events_statements_summary_by_program'.

See Statement events per thread 'events_statements_summary_by_thread_by_event_name'.

See Statement events per user name 'events_statements_summary_by_user_by_event_name'.

See Statement events per event 'events_statements_summary_global_by_event_name'.

See 'events_transactions_current'.

See 'events_transactions_history'.
for each thread

See Most recent transaction events 'events_transactions_history_long'.

See Transaction events per account 'events_transactions_summary_by_account_by_event_name'.

See Transaction events per host 'events_transactions_summary_by_host_by_event_name'.

See Transaction events per thread 'events_transactions_summary_by_thread_by_event_name'.

See Transaction events per user 'events_transactions_summary_by_user_by_event_name'.

See Transaction events per event 'events_transactions_summary_global_by_event_name'.

See 'events_waits_current'.

See 'events_waits_history'.
      each thread

See 'events_waits_history_long'.
 overall

See Wait events per account and 'events_waits_summary_by_account_by_event_name'.

See Wait events per host name and 'events_waits_summary_by_host_by_event_name'.

See Wait events per instance 'events_waits_summary_by_instance'.

See Wait events per thread and 'events_waits_summary_by_thread_by_event_name'.

See Wait events per user name and 'events_waits_summary_by_user_by_event_name'.

See Wait events per event name 'events_waits_summary_global_by_event_name'.

See 'file_instances'.

See 'file_summary_by_event_name'.

See 'file_summary_by_instance'.

See 'global_status'.

See 'global_variables'.

See 'host_cache'.    Information from the internal
                                         host cache

See 'hosts'.              Connection statistics per
                                         client host name

See Memory operations per account 'memory_summary_by_account_by_event_name'.

See Memory operations per host and 'memory_summary_by_host_by_event_name'.

See Memory operations per thread 'memory_summary_by_thread_by_event_name'.

See Memory operations per user and 'memory_summary_by_user_by_event_name'.

See Memory operations globally per 'memory_summary_global_by_event_name'.

See 'metadata_locks'.
            requests

See 'mutex_instances'.
           instances

See Object summaries 'objects_summary_global_by_type'.

See 'performance_timers'.
        available

See 'prepared_statements_instances'.
and statistics

Configuration parameters for 'replication_applier_configuration'
slave

See 'replication_applier_status'.
transaction applier on the
                                         slave

See SQL or coordinator thread 'replication_applier_status_by_coordinator'.

*note                                    Worker thread applier status
'replication_applier_status_by_worker':  (empty unless slave is
replication-applier-status-by-worker-table.multi-threaded)

See Configuration parameters for 'replication_connection_configuration'.

See 'replication_connection_status'.
connection to the master

See 'rwlock_instances'.
          instances

See 'session_account_connect_attrs'.
the current session

See 'session_connect_attrs'.
     sessions

See 'session_status'.
session

See 'session_variables'.
session

See 'setup_actors'.
              for new foreground threads

See 'setup_consumers'.
           information can be stored

See 'setup_instruments'.
         objects for which events can
                                         be collected

See 'setup_objects'.
             monitored

See 'setup_timers'.

See 'socket_instances'.

See 'socket_summary_by_event_name'.
           name

See 'socket_summary_by_instance'.
           instance

See 'status_by_account'.
account

See 'status_by_host'.
host name

See 'status_by_thread'.
session

See 'status_by_user'.
user name

See 'table_handles'.

See Table I/O waits per index 'table_io_waits_summary_by_index_usage'.

See Table I/O waits per table 'table_io_waits_summary_by_table'.

See Table lock waits per table 'table_lock_waits_summary_by_table'.

See 'threads'.          Information about server
                                         threads

'user_variables_by_thread'
thread

See 'users'.              Connection statistics per
                                         client user name

See 'variables_by_thread'.
session

25.11.2 Performance Schema Setup Tables
---------------------------------------

The setup tables provide information about the current instrumentation
and enable the monitoring configuration to be changed.  For this reason,
some columns in these tables can be changed if you have the 'UPDATE'
privilege.

The use of tables rather than individual variables for setup information
provides a high degree of flexibility in modifying Performance Schema
configuration.  For example, you can use a single statement with
standard SQL syntax to make multiple simultaneous configuration changes.

These setup tables are available:

   * 'setup_actors'.: How to initialize
     monitoring for new foreground threads

   * 'setup_consumers'.: The destinations
     to which event information can be sent and stored

   * 'setup_instruments'.: The classes of
     instrumented objects for which events can be collected

   * 'setup_objects'.: Which objects should
     be monitored

   * 'setup_timers'.: The current event timer

25.11.2.1 The setup_actors Table
................................

The 'setup_actors' table contains information
that determines whether to enable monitoring and historical event
logging for new foreground server threads (threads associated with
client connections).  This table has a maximum size of 100 rows by
default.  To change the table size, modify the
'performance_schema_setup_actors_size' system variable at server
startup.

For each new foreground thread, the Performance Schema matches the user
and host for the thread against the rows of the 'setup_actors'
table.  If a row from that table matches, its
'ENABLED' and 'HISTORY' column values are used to set the the
'INSTRUMENTED' and 'HISTORY' columns, respectively, of the
'threads' table row for the thread.  This enables
instrumenting and historical event logging to be applied selectively per
host, user, or account (user and host combination).  If there is no
match, the 'INSTRUMENTED' and 'HISTORY' columns for the thread are set
to 'NO'.

For background threads, there is no associated user.  'INSTRUMENTED' and
'HISTORY' are 'YES' by default and 'setup_actors'
is not consulted.

The initial contents of the 'setup_actors'.
table match any user and host combination, so monitoring and historical
event collection are enabled by default for all foreground threads:

     mysql> SELECT * FROM setup_actors;
     +------+------+------+---------+---------+
     | HOST | USER | ROLE | ENABLED | HISTORY |
     +------+------+------+---------+---------+
     | %    | %    | %    | YES     | YES     |
     +------+------+------+---------+---------+

For information about how to use the 'setup_actors'
table to affect event monitoring, see
performance-schema-thread-filtering.

Modifications to the 'setup_actors' table
affect only foreground threads created subsequent to the modification,
not existing threads.  To affect existing threads, modify the
'INSTRUMENTED' and 'HISTORY' columns of 'threads'.
table rows.

The 'setup_actors' table has these columns:

   * 'HOST'

     The host name.  This should be a literal name, or ''%'' to mean
     'any host.'

   * 'USER'

     The user name.  This should be a literal name, or ''%'' to mean
     'any user.'

   * 'ROLE'

     Unused.

   * 'ENABLED'

     Whether to enable instrumentation for foreground threads matched by
     the row.  The value is 'YES' or 'NO'.

   * 'HISTORY'

     Whether to log historical events for foreground threads matched by
     the row.  The value is 'YES' or 'NO'.

'TRUNCATE TABLE' is permitted for the
'setup_actors' table.  It removes the rows.

25.11.2.2 The setup_consumers Table
...................................

The 'setup_consumers' table lists the
types of consumers for which event information can be stored and which
are enabled:

     mysql> SELECT * FROM setup_consumers;
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | events_stages_current            | NO      |
     | events_stages_history            | NO      |
     | events_stages_history_long       | NO      |
     | events_statements_current        | YES     |
     | events_statements_history        | YES     |
     | events_statements_history_long   | NO      |
     | events_transactions_current      | NO      |
     | events_transactions_history      | NO      |
     | events_transactions_history_long | NO      |
     | events_waits_current             | NO      |
     | events_waits_history             | NO      |
     | events_waits_history_long        | NO      |
     | global_instrumentation           | YES     |
     | thread_instrumentation           | YES     |
     | statements_digest                | YES     |
     +----------------------------------+---------+

The consumer settings in the 'setup_consumers'
table form a hierarchy from higher levels to
lower.  For detailed information about the effect of enabling different
consumers, see performance-schema-consumer-filtering.

Modifications to the 'setup_consumers'.
table affect monitoring immediately.

The 'setup_consumers' table has these
columns:

   * 'NAME'

     The consumer name.

   * 'ENABLED'

     Whether the consumer is enabled.  The value is 'YES' or 'NO'.  This
     column can be modified.  If you disable a consumer, the server does
     not spend time adding event information to it.

'TRUNCATE TABLE' is not permitted for the
'setup_consumers' table.

25.11.2.3 The setup_instruments Table
.....................................

The 'setup_instruments' table lists
classes of instrumented objects for which events can be collected:

     mysql> SELECT * FROM setup_instruments;
     +---------------------------------------------------+---------+-------+
     | NAME                                              | ENABLED | TIMED |
     +---------------------------------------------------+---------+-------+
     ...
     | stage/sql/end                                     | NO      | NO    |
     | stage/sql/executing                               | NO      | NO    |
     | stage/sql/init                                    | NO      | NO    |
     | stage/sql/insert                                  | NO      | NO    |
     ...
     | statement/sql/load                                | YES     | YES   |
     | statement/sql/grant                               | YES     | YES   |
     | statement/sql/check                               | YES     | YES   |
     | statement/sql/flush                               | YES     | YES   |
     ...
     | wait/synch/mutex/sql/LOCK_global_read_lock        | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_global_system_variables | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_lock_db                 | YES     | YES   |
     | wait/synch/mutex/sql/LOCK_manager                 | YES     | YES   |
     ...
     | wait/synch/rwlock/sql/LOCK_grant                  | YES     | YES   |
     | wait/synch/rwlock/sql/LOGGER::LOCK_logger         | YES     | YES   |
     | wait/synch/rwlock/sql/LOCK_sys_init_connect       | YES     | YES   |
     | wait/synch/rwlock/sql/LOCK_sys_init_slave         | YES     | YES   |
     ...
     | wait/io/file/sql/binlog                           | YES     | YES   |
     | wait/io/file/sql/binlog_index                     | YES     | YES   |
     | wait/io/file/sql/casetest                         | YES     | YES   |
     | wait/io/file/sql/dbopt                            | YES     | YES   |
     ...

Each instrument added to the source code provides a row for the
'setup_instruments' table, even when the
instrumented code is not executed.  When an instrument is enabled and
executed, instrumented instances are created, which are visible in the
'XXX_instances' tables, such as 'file_instances'
or 'rwlock_instances'.

Modifications to most 'setup_instruments'
rows affect monitoring immediately.  For some
instruments, modifications are effective only at server startup;
changing them at runtime has no effect.  This affects primarily mutexes,
conditions, and rwlocks in the server, although there may be other
instruments for which this is true.

For more information about the role of the 'setup_instruments'
table in event filtering, see
performance-schema-pre-filtering.

The 'setup_instruments' table has these
columns:

   * 'NAME'

     The instrument name.  Instrument names may have multiple parts and
     form a hierarchy, as discussed in
     performance-schema-instrument-naming.  Events produced from
     execution of an instrument have an 'EVENT_NAME' value that is taken
     from the instrument 'NAME' value.  (Events do not really have a
     'name,' but this provides a way to associate events with
     instruments.)

   * 'ENABLED'

     Whether the instrument is enabled.  The value is 'YES' or 'NO'.  A
     disabled instrument produces no events.  This column can be
     modified, although setting 'ENABLED' has no effect for instruments
     that have already been created.

   * 'TIMED'

     Whether the instrument is timed.  The value is 'YES' or 'NO'.  This
     column can be modified, although setting 'TIMED' has no effect for
     instruments that have already been created.

     For memory instruments, the 'TIMED' column in
     'setup_instruments' is ignored because
     memory operations are not timed.

     If an enabled instrument is not timed, the instrument code is
     enabled, but the timer is not.  Events produced by the instrument
     have 'NULL' for the 'TIMER_START', 'TIMER_END', and 'TIMER_WAIT'
     timer values.  This in turn causes those values to be ignored when
     calculating the sum, minimum, maximum, and average time values in
     summary tables.

'TRUNCATE TABLE' is not permitted for the
'setup_instruments' table.

25.11.2.4 The setup_objects Table
.................................

The 'setup_objects' table controls whether
the Performance Schema monitors particular objects.  This table has a
maximum size of 100 rows by default.  To change the table size, modify
the 'performance_schema_setup_objects_size' system variable at server
startup.

The initial 'setup_objects' contents look
like this:

     mysql> SELECT * FROM setup_objects;
     +-------------+--------------------+-------------+---------+-------+
     | OBJECT_TYPE | OBJECT_SCHEMA      | OBJECT_NAME | ENABLED | TIMED |
     +-------------+--------------------+-------------+---------+-------+
     | EVENT       | mysql              | %           | NO      | NO    |
     | EVENT       | performance_schema | %           | NO      | NO    |
     | EVENT       | information_schema | %           | NO      | NO    |
     | EVENT       | %                  | %           | YES     | YES   |
     | FUNCTION    | mysql              | %           | NO      | NO    |
     | FUNCTION    | performance_schema | %           | NO      | NO    |
     | FUNCTION    | information_schema | %           | NO      | NO    |
     | FUNCTION    | %                  | %           | YES     | YES   |
     | PROCEDURE   | mysql              | %           | NO      | NO    |
     | PROCEDURE   | performance_schema | %           | NO      | NO    |
     | PROCEDURE   | information_schema | %           | NO      | NO    |
     | PROCEDURE   | %                  | %           | YES     | YES   |
     | TABLE       | mysql              | %           | NO      | NO    |
     | TABLE       | performance_schema | %           | NO      | NO    |
     | TABLE       | information_schema | %           | NO      | NO    |
     | TABLE       | %                  | %           | YES     | YES   |
     | TRIGGER     | mysql              | %           | NO      | NO    |
     | TRIGGER     | performance_schema | %           | NO      | NO    |
     | TRIGGER     | information_schema | %           | NO      | NO    |
     | TRIGGER     | %                  | %           | YES     | YES   |
     +-------------+--------------------+-------------+---------+-------+

Modifications to the 'setup_objects' table
affect object monitoring immediately.

For object types listed in 'setup_objects',
the Performance Schema uses the table to how to monitor them.  Object
matching is based on the 'OBJECT_SCHEMA' and 'OBJECT_NAME' columns.
Objects for which there is no match are not monitored.

The effect of the default object configuration is to instrument all
tables except those in the 'mysql', 'INFORMATION_SCHEMA', and
'performance_schema' databases.  (Tables in the 'INFORMATION_SCHEMA'
database are not instrumented regardless of the contents of
'setup_objects'.; the row for
'information_schema.%' simply makes this default explicit.)

When the Performance Schema checks for a match in 'setup_objects',
it tries to find more specific matches first.  For
example, with a table 'db1.t1', it looks for a match for ''db1'' and
''t1'', then for ''db1'' and ''%'', then for ''%'' and ''%''.  The order
in which matching occurs matters because different matching
'setup_objects' rows can have different 'ENABLED'
and 'TIMED' values.

Rows can be inserted into or deleted from 'setup_objects'
by users with the 'INSERT' or 'DELETE' privilege on
the table.  For existing rows, only the 'ENABLED' and 'TIMED' columns
can be modified, by users with the 'UPDATE' privilege on the table.

For more information about the role of the 'setup_objects'
table in event filtering, see
performance-schema-pre-filtering.

The 'setup_objects' table has these columns:

   * 'OBJECT_TYPE'

     The type of object to instrument.  The value is one of ''EVENT''
     (Event Scheduler event), ''FUNCTION'' (stored function),
     ''PROCEDURE'' (stored procedure), ''TABLE'' (base table), or
     ''TRIGGER'' (trigger).

     'TABLE' filtering affects table I/O events
     ('wait/io/table/sql/handler' instrument) and table lock events
     ('wait/lock/table/sql/handler' instrument).

   * 'OBJECT_SCHEMA'

     The schema that contains the object.  This should be a literal
     name, or ''%'' to mean 'any schema.'

   * 'OBJECT_NAME'

     The name of the instrumented object.  This should be a literal
     name, or ''%'' to mean 'any object.'

   * 'ENABLED'

     Whether events for the object are instrumented.  The value is 'YES'
     or 'NO'.  This column can be modified.

   * 'TIMED'

     Whether events for the object are timed.  The value is 'YES' or
     'NO'.  This column can be modified.

'TRUNCATE TABLE' is permitted for the
'setup_objects' table.  It removes the rows.

25.11.2.5 The setup_timers Table
................................

The 'setup_timers' table shows the currently
selected event timers:

     mysql> SELECT * FROM setup_timers;
     +-------------+-------------+
     | NAME        | TIMER_NAME  |
     +-------------+-------------+
     | idle        | MICROSECOND |
     | wait        | CYCLE       |
     | stage       | NANOSECOND  |
     | statement   | NANOSECOND  |
     | transaction | NANOSECOND  |
     +-------------+-------------+

*Note*:

As of MySQL 5.7.21, the Performance Schema 'setup_timers'
table is deprecated and is removed in MySQL 8.0, as
is the 'TICKS' row in the 'performance_timers'
table.

The 'setup_timers.TIMER_NAME' value can be changed to select a different
timer.  The value can be any of the values in the
'performance_timers.TIMER_NAME' column.  For an explanation of how event
timing occurs, see performance-schema-timing.

Modifications to the 'setup_timers' table
affect monitoring immediately.  Events already in progress may use the
original timer for the begin time and the new timer for the end time.
To avoid unpredictable results after you make timer changes, use
'TRUNCATE TABLE' to reset Performance Schema
statistics.

The 'setup_timers' table has these columns:

   * 'NAME'

     The type of instrument the timer is used for.

   * 'TIMER_NAME'

     The timer that applies to the instrument type.  This column can be
     modified.

'TRUNCATE TABLE' is not permitted for the
'setup_timers' table.

25.11.3 Performance Schema Instance Tables
------------------------------------------

Instance tables document what types of objects are instrumented.  They
provide event names and explanatory notes or status information:

   * 'cond_instances'.: Condition
     synchronization object instances

   * 'file_instances'.: File instances

   * 'mutex_instances'.: Mutex
     synchronization object instances

   * 'rwlock_instances'.: Lock
     synchronization object instances

   * 'socket_instances'.: Active
     connection instances

These tables list instrumented synchronization objects, files, and
connections.  There are three types of synchronization objects: 'cond',
'mutex', and 'rwlock'.  Each instance table has an 'EVENT_NAME' or
'NAME' column to indicate the instrument associated with each row.
Instrument names may have multiple parts and form a hierarchy, as
discussed in performance-schema-instrument-naming.

The 'mutex_instances.LOCKED_BY_THREAD_ID' and
'rwlock_instances.WRITE_LOCKED_BY_THREAD_ID' columns are extremely
important for investigating performance bottlenecks or deadlocks.  For
examples of how to use them for this purpose, see
performance-schema-examples

25.11.3.1 The cond_instances Table
..................................

The 'cond_instances' table lists all the
conditions seen by the Performance Schema while the server executes.  A
condition is a synchronization mechanism used in the code to signal that
a specific event has happened, so that a thread waiting for this
condition can resume work.

When a thread is waiting for something to happen, the condition name is
an indication of what the thread is waiting for, but there is no
immediate way to tell which other thread, or threads, will cause the
condition to happen.

The 'cond_instances' table has these
columns:

   * 'NAME'

     The instrument name associated with the condition.

   * 'OBJECT_INSTANCE_BEGIN'

     The address in memory of the instrumented condition.

'TRUNCATE TABLE' is not permitted for the
'cond_instances' table.

25.11.3.2 The file_instances Table
..................................

The 'file_instances' table lists all the
files seen by the Performance Schema when executing file I/O
instrumentation.  If a file on disk has never been opened, it will not
be in 'file_instances'.  When a file is
deleted from the disk, it is also removed from the
'file_instances' table.

The 'file_instances' table has these
columns:

   * 'FILE_NAME'

     The file name.

   * 'EVENT_NAME'

     The instrument name associated with the file.

   * 'OPEN_COUNT'

     The count of open handles on the file.  If a file was opened and
     then closed, it was opened 1 time, but 'OPEN_COUNT' will be 0.  To
     list all the files currently opened by the server, use 'WHERE
     OPEN_COUNT > 0'.

'TRUNCATE TABLE' is not permitted for the
'file_instances' table.

25.11.3.3 The mutex_instances Table
...................................

The 'mutex_instances' table lists all the
mutexes seen by the Performance Schema while the server executes.  A
mutex is a synchronization mechanism used in the code to enforce that
only one thread at a given time can have access to some common resource.
The resource is said to be 'protected' by the mutex.

When two threads executing in the server (for example, two user sessions
executing a query simultaneously) do need to access the same resource (a
file, a buffer, or some piece of data), these two threads will compete
against each other, so that the first query to obtain a lock on the
mutex will cause the other query to wait until the first is done and
unlocks the mutex.

The work performed while holding a mutex is said to be in a 'critical
section,' and multiple queries do execute this critical section in a
serialized way (one at a time), which is a potential bottleneck.

The 'mutex_instances' table has these
columns:

   * 'NAME'

     The instrument name associated with the mutex.

   * 'OBJECT_INSTANCE_BEGIN'

     The address in memory of the instrumented mutex.

   * 'LOCKED_BY_THREAD_ID'

     When a thread currently has a mutex locked, 'LOCKED_BY_THREAD_ID'
     is the 'THREAD_ID' of the locking thread, otherwise it is 'NULL'.

'TRUNCATE TABLE' is not permitted for the
'mutex_instances' table.

For every mutex instrumented in the code, the Performance Schema
provides the following information.

   * The 'setup_instruments' table lists
     the name of the instrumentation point, with the prefix
     'wait/synch/mutex/'.

   * When some code creates a mutex, a row is added to the
     'mutex_instances' table.  The
     'OBJECT_INSTANCE_BEGIN' column is a property that uniquely
     identifies the mutex.

   * When a thread attempts to lock a mutex, the
     'events_waits_current' table shows a
     row for that thread, indicating that it is waiting on a mutex (in
     the 'EVENT_NAME' column), and indicating which mutex is waited on
     (in the 'OBJECT_INSTANCE_BEGIN' column).

   * When a thread succeeds in locking a mutex:

        * 'events_waits_current'.
          shows that the wait on the mutex is completed (in the
          'TIMER_END' and 'TIMER_WAIT' columns)

        * The completed wait event is added to the
          'events_waits_history' and
          'events_waits_history_long'.
          tables

        * 'mutex_instances' shows that the
          mutex is now owned by the thread (in the 'THREAD_ID' column).

   * When a thread unlocks a mutex, see 'mutex_instances'
     shows that the mutex now has no owner (the
     'THREAD_ID' column is 'NULL').

   * When a mutex object is destroyed, the corresponding row is removed
     from 'mutex_instances'.

By performing queries on both of the following tables, a monitoring
application or a DBA can detect bottlenecks or deadlocks between threads
that involve mutexes:

   * 'events_waits_current', to see
     what mutex a thread is waiting for

   * 'mutex_instances', to see which other
     thread currently owns a mutex

25.11.3.4 The rwlock_instances Table
....................................

The 'rwlock_instances' table lists all
the rwlock (read write lock) instances seen by the Performance Schema
while the server executes.  An 'rwlock' is a synchronization mechanism
used in the code to enforce that threads at a given time can have access
to some common resource following certain rules.  The resource is said
to be 'protected' by the 'rwlock'.  The access is either shared (many
threads can have a read lock at the same time), exclusive (only one
thread can have a write lock at a given time), or shared-exclusive (a
thread can have a write lock while permitting inconsistent reads by
other threads).  Shared-exclusive access is otherwise known as an
'sxlock' and optimizes concurrency and improves scalability for
read-write workloads.

Depending on how many threads are requesting a lock, and the nature of
the locks requested, access can be either granted in shared mode,
exclusive mode, shared-exclusive mode or not granted at all, waiting for
other threads to finish first.

The 'rwlock_instances' table has these
columns:

   * 'NAME'

     The instrument name associated with the lock.

   * 'OBJECT_INSTANCE_BEGIN'

     The address in memory of the instrumented lock.

   * 'WRITE_LOCKED_BY_THREAD_ID'

     When a thread currently has an 'rwlock' locked in exclusive (write)
     mode, 'WRITE_LOCKED_BY_THREAD_ID' is the 'THREAD_ID' of the locking
     thread, otherwise it is 'NULL'.

   * 'READ_LOCKED_BY_COUNT'

     When a thread currently has an 'rwlock' locked in shared (read)
     mode, 'READ_LOCKED_BY_COUNT' is incremented by 1.  This is a
     counter only, so it cannot be used directly to find which thread
     holds a read lock, but it can be used to see whether there is a
     read contention on an 'rwlock', and see how many readers are
     currently active.

'TRUNCATE TABLE' is not permitted for the
'rwlock_instances' table.

By performing queries on both of the following tables, a monitoring
application or a DBA may detect some bottlenecks or deadlocks between
threads that involve locks:

   * 'events_waits_current', to see
     what 'rwlock' a thread is waiting for

   * 'rwlock_instances', to see which
     other thread currently owns an 'rwlock'

There is a limitation: The 'rwlock_instances'
can be used only to identify the thread holding
a write lock, but not the threads holding a read lock.

25.11.3.5 The socket_instances Table
....................................

The 'socket_instances' table provides a
real-time snapshot of the active connections to the MySQL server.  The
table contains one row per TCP/IP or Unix socket file connection.
Information available in this table provides a real-time snapshot of the
active connections to the server.  (Additional information is available
in socket summary tables, including network activity such as socket
operations and number of bytes transmitted and received; see
socket-summary-tables).

     mysql> SELECT * FROM socket_instances\G
     *************************** 1. row ***************************
                EVENT_NAME: wait/io/socket/sql/server_unix_socket
     OBJECT_INSTANCE_BEGIN: 4316619408
                 THREAD_ID: 1
                 SOCKET_ID: 16
                        IP:
                      PORT: 0
                     STATE: ACTIVE
     *************************** 2. row ***************************
                EVENT_NAME: wait/io/socket/sql/client_connection
     OBJECT_INSTANCE_BEGIN: 4316644608
                 THREAD_ID: 21
                 SOCKET_ID: 39
                        IP: 127.0.0.1
                      PORT: 55233
                     STATE: ACTIVE
     *************************** 3. row ***************************
                EVENT_NAME: wait/io/socket/sql/server_tcpip_socket
     OBJECT_INSTANCE_BEGIN: 4316699040
                 THREAD_ID: 1
                 SOCKET_ID: 14
                        IP: 0.0.0.0
                      PORT: 50603
                     STATE: ACTIVE

Socket instruments have names of the form
'wait/io/socket/sql/SOCKET_TYPE' and are used like this:

  1. The server has a listening socket for each network protocol that it
     supports.  The instruments associated with listening sockets for
     TCP/IP or Unix socket file connections have a SOCKET_TYPE value of
     'server_tcpip_socket' or 'server_unix_socket', respectively.

  2. When a listening socket detects a connection, the server transfers
     the connection to a new socket managed by a separate thread.  The
     instrument for the new connection thread has a SOCKET_TYPE value of
     'client_connection'.

  3. When a connection terminates, the row in 'socket_instances'
     corresponding to it is deleted.

The 'socket_instances' table has these
columns:

   * 'EVENT_NAME'

     The name of the 'wait/io/socket/*' instrument that produced the
     event.  This is a 'NAME' value from the 'setup_instruments'
     table.  Instrument names may have multiple
     parts and form a hierarchy, as discussed in
     performance-schema-instrument-naming.

   * 'OBJECT_INSTANCE_BEGIN'

     This column uniquely identifies the socket.  The value is the
     address of an object in memory.

   * 'THREAD_ID'

     The internal thread identifier assigned by the server.  Each socket
     is managed by a single thread, so each socket can be mapped to a
     thread which can be mapped to a server process.

   * 'SOCKET_ID'

     The internal file handle assigned to the socket.

   * 'IP'

     The client IP address.  The value may be either an IPv4 or IPv6
     address, or blank to indicate a Unix socket file connection.

   * 'PORT'

     The TCP/IP port number, in the range from 0 to 65535.

   * 'STATE'

     The socket status, either 'IDLE' or 'ACTIVE'.  Wait times for
     active sockets are tracked using the corresponding socket
     instrument.  Wait times for idle sockets are tracked using the
     'idle' instrument.

     A socket is idle if it is waiting for a request from the client.
     When a socket becomes idle, the event row in
     'socket_instances' that is tracking the
     socket switches from a status of 'ACTIVE' to 'IDLE'.  The
     'EVENT_NAME' value remains 'wait/io/socket/*', but timing for the
     instrument is suspended.  Instead, an event is generated in the
     'events_waits_current' table
     with an 'EVENT_NAME' value of 'idle'.

     When the next request is received, the 'idle' event terminates, the
     socket instance switches from 'IDLE' to 'ACTIVE', and timing of the
     socket instrument resumes.

'TRUNCATE TABLE' is not permitted for the
'socket_instances' table.

The 'IP:PORT' column combination value identifies the connection.  This
combination value is used in the 'OBJECT_NAME' column of the
'events_waits_XXX' tables, to identify the connection from which socket
events come:

   * For the Unix domain listener socket ('server_unix_socket'), the
     port is 0, and the IP is ''''.

   * For client connections via the Unix domain listener
     ('client_connection'), the port is 0, and the IP is ''''.

   * For the TCP/IP server listener socket ('server_tcpip_socket'), the
     port is always the master port (for example, 3306), and the IP is
     always '0.0.0.0'.

   * For client connections via the TCP/IP listener
     ('client_connection'), the port is whatever the server assigns, but
     never 0.  The IP is the IP of the originating host ('127.0.0.1' or
     '::1' for the local host)

25.11.4 Performance Schema Wait Event Tables
--------------------------------------------

The Performance Schema instruments waits, which are events that take
time.  Within the event hierarchy, wait events nest within stage events,
which nest within statement events, which nest within transaction
events.

These tables store wait events:

   * 'events_waits_current'.: Current
     wait events

   * 'events_waits_history'.: The most
     recent wait events per thread

   * 'events_waits_history_long'.:
     The most recent wait events
     globally (across all threads)

The following sections describe the wait event tables.  There are also
summary tables that aggregate information about wait events; see
wait-summary-tables.

*Wait Event Configuration*

To control collection of wait events, set the state of the relevant
instruments and consumers:

   * The 'setup_instruments' table
     contains instruments with names that begin with 'wait'.  Use these
     instruments to enable or disable collection of wait events.

   * The 'setup_consumers' table contains
     consumer values with names corresponding to the current and recent
     wait event table names.  Use these consumers to filter collection
     of wait events.

Some wait instruments are enabled by default; others are disabled.  For
example:

     mysql> SELECT * FROM setup_instruments
            WHERE NAME LIKE 'wait/io/file/innodb%';
     +--------------------------------------+---------+-------+
     | NAME                                 | ENABLED | TIMED |
     +--------------------------------------+---------+-------+
     | wait/io/file/innodb/innodb_data_file | YES     | YES   |
     | wait/io/file/innodb/innodb_log_file  | YES     | YES   |
     | wait/io/file/innodb/innodb_temp_file | YES     | YES   |
     +--------------------------------------+---------+-------+
     mysql> SELECT * FROM setup_instruments WHERE
            NAME LIKE 'wait/io/socket/%';
     +----------------------------------------+---------+-------+
     | NAME                                   | ENABLED | TIMED |
     +----------------------------------------+---------+-------+
     | wait/io/socket/sql/server_tcpip_socket | NO      | NO    |
     | wait/io/socket/sql/server_unix_socket  | NO      | NO    |
     | wait/io/socket/sql/client_connection   | NO      | NO    |
     +----------------------------------------+---------+-------+

The wait consumers are disabled by default:

     mysql> SELECT * FROM setup_consumers WHERE NAME LIKE '%waits%';
     +---------------------------+---------+
     | NAME                      | ENABLED |
     +---------------------------+---------+
     | events_waits_current      | NO      |
     | events_waits_history      | NO      |
     | events_waits_history_long | NO      |
     +---------------------------+---------+

To control wait event collection at server startup, use lines like these
in your 'my.cnf' file:

   * Enable:

          [mysqld]
          performance-schema-instrument='wait/%=ON'
          performance-schema-consumer-events-waits-current=ON
          performance-schema-consumer-events-waits-history=ON
          performance-schema-consumer-events-waits-history-long=ON

   * Disable:

          [mysqld]
          performance-schema-instrument='wait/%=OFF'
          performance-schema-consumer-events-waits-current=OFF
          performance-schema-consumer-events-waits-history=OFF
          performance-schema-consumer-events-waits-history-long=OFF

To control wait event collection at runtime, update the
'setup_instruments' and
'setup_consumers' tables:

   * Enable:

          UPDATE setup_instruments SET ENABLED = 'YES', TIMED = 'YES'
          WHERE NAME = 'wait/%';
          UPDATE setup_consumers SET ENABLED = 'YES'
          WHERE NAME LIKE '%waits%';

   * Disable:

          UPDATE setup_instruments SET ENABLED = 'NO', TIMED = 'NO'
          WHERE NAME = 'wait/%';
          UPDATE setup_consumers SET ENABLED = 'NO'
          WHERE NAME LIKE '%waits%';

To collect only specific wait events, enable only the corresponding wait
instruments.  To collect wait events only for specific wait event
tables, enable the wait instruments but only the wait consumers
corresponding to the desired tables.

The 'setup_timers' table contains a row with
a 'NAME' value of 'wait' that indicates the unit for wait event timing.
The default unit is 'CYCLE':

     mysql> SELECT * FROM setup_timers WHERE NAME = 'wait';
     +------+------------+
     | NAME | TIMER_NAME |
     +------+------------+
     | wait | CYCLE      |
     +------+------------+

To change the timing unit, modify the 'TIMER_NAME' value:

     UPDATE setup_timers SET TIMER_NAME = 'NANOSECOND'
     WHERE NAME = 'wait';

For additional information about configuring event collection, see
performance-schema-startup-configuration, and
performance-schema-runtime-configuration.

25.11.4.1 The events_waits_current Table
........................................

The 'events_waits_current' table
contains current wait events, one row per thread showing the current
status of the thread's most recent monitored wait event.

Of the tables that contain wait event rows, see
'events_waits_current' is the most
fundamental.  Other tables that contain wait event rows are logically
derived from the current events.  For example, the
'events_waits_history' and
'events_waits_history_long' tables are
collections of the most recent wait events, up to a fixed number of
rows.

For information about configuration of wait event collection, see
performance-schema-wait-tables.

The 'events_waits_current' table has
these columns:

   * 'THREAD_ID', 'EVENT_ID'

     The thread associated with the event and the thread current event
     number when the event starts.  The 'THREAD_ID' and 'EVENT_ID'
     values taken together uniquely identify the row.  No two rows have
     the same pair of values.

   * 'END_EVENT_ID'

     This column is set to 'NULL' when the event starts and updated to
     the thread current event number when the event ends.

   * 'EVENT_NAME'

     The name of the instrument that produced the event.  This is a
     'NAME' value from the 'setup_instruments'
     table.  Instrument names may have multiple
     parts and form a hierarchy, as discussed in
     performance-schema-instrument-naming.

   * 'SOURCE'

     The name of the source file containing the instrumented code that
     produced the event and the line number in the file at which the
     instrumentation occurs.  This enables you to check the source to
     determine exactly what code is involved.  For example, if a mutex
     or lock is being blocked, you can check the context in which this
     occurs.

   * 'TIMER_START', 'TIMER_END', 'TIMER_WAIT'

     Timing information for the event.  The unit for these values is
     picoseconds (trillionths of a second).  The 'TIMER_START' and
     'TIMER_END' values indicate when event timing started and ended.
     'TIMER_WAIT' is the event elapsed time (duration).

     If an event has not finished, 'TIMER_END' is the current timer
     value and 'TIMER_WAIT' is the time elapsed so far ('TIMER_END' −
     'TIMER_START').

     If an event is produced from an instrument that has 'TIMED = NO',
     timing information is not collected, and 'TIMER_START',
     'TIMER_END', and 'TIMER_WAIT' are all 'NULL'.

     For discussion of picoseconds as the unit for event times and
     factors that affect time values, see
     performance-schema-timing.

   * 'SPINS'

     For a mutex, the number of spin rounds.  If the value is 'NULL',
     the code does not use spin rounds or spinning is not instrumented.

   * 'OBJECT_SCHEMA', 'OBJECT_NAME', 'OBJECT_TYPE',
     'OBJECT_INSTANCE_BEGIN'

     These columns identify the object 'being acted on.' What that means
     depends on the object type.

     For a synchronization object ('cond', 'mutex', 'rwlock'):

        * 'OBJECT_SCHEMA', 'OBJECT_NAME', and 'OBJECT_TYPE' are 'NULL'.

        * 'OBJECT_INSTANCE_BEGIN' is the address of the synchronization
          object in memory.

     For a file I/O object:

        * 'OBJECT_SCHEMA' is 'NULL'.

        * 'OBJECT_NAME' is the file name.

        * 'OBJECT_TYPE' is 'FILE'.

        * 'OBJECT_INSTANCE_BEGIN' is an address in memory.

     For a socket object:

        * 'OBJECT_NAME' is the 'IP:PORT' value for the socket.

        * 'OBJECT_INSTANCE_BEGIN' is an address in memory.

     For a table I/O object:

        * 'OBJECT_SCHEMA' is the name of the schema that contains the
          table.

        * 'OBJECT_NAME' is the table name.

        * 'OBJECT_TYPE' is 'TABLE' for a persistent base table or
          'TEMPORARY TABLE' for a temporary table.

        * 'OBJECT_INSTANCE_BEGIN' is an address in memory.

     An 'OBJECT_INSTANCE_BEGIN' value itself has no meaning, except that
     different values indicate different objects.
     'OBJECT_INSTANCE_BEGIN' can be used for debugging.  For example, it
     can be used with 'GROUP BY OBJECT_INSTANCE_BEGIN' to see whether
     the load on 1,000 mutexes (that protect, say, 1,000 pages or blocks
     of data) is spread evenly or just hitting a few bottlenecks.  This
     can help you correlate with other sources of information if you see
     the same object address in a log file or another debugging or
     performance tool.

   * 'INDEX_NAME'

     The name of the index used.  'PRIMARY' indicates the table primary
     index.  'NULL' means that no index was used.

   * 'NESTING_EVENT_ID'

     The 'EVENT_ID' value of the event within which this event is
     nested.

   * 'NESTING_EVENT_TYPE'

     The nesting event type.  The value is 'TRANSACTION', 'STATEMENT',
     'STAGE', or 'WAIT'.

   * 'OPERATION'

     The type of operation performed, such as 'lock', 'read', or
     'write'.

   * 'NUMBER_OF_BYTES'

     The number of bytes read or written by the operation.  For table
     I/O waits (events for the 'wait/io/table/sql/handler' instrument),
     'NUMBER_OF_BYTES' indicates the number of rows.  If the value is
     greater than 1, the event is for a batch I/O operation.  The
     following discussion describes the difference between exclusively
     single-row reporting and reporting that reflects batch I/O.

     MySQL executes joins using a nested-loop implementation.  The job
     of the Performance Schema instrumentation is to provide row count
     and accumulated execution time per table in the join.  Assume a
     join query of the following form that is executed using a table
     join order of 't1', 't2', 't3':

          SELECT ... FROM t1 JOIN t2 ON ... JOIN t3 ON ...

     Table 'fanout' is the increase or decrease in number of rows from
     adding a table during join processing.  If the fanout for table
     't3' is greater than 1, the majority of row-fetch operations are
     for that table.  Suppose that the join accesses 10 rows from 't1',
     20 rows from 't2' per row from 't1', and 30 rows from 't3' per row
     of table 't2'.  With single-row reporting, the total number of
     instrumented operations is:

          10 + (10 * 20) + (10 * 20 * 30) = 6210

     A significant reduction in the number of instrumented operations is
     achievable by aggregating them per scan (that is, per unique
     combination of rows from 't1' and 't2').  With batch I/O reporting,
     the Performance Schema produces an event for each scan of the
     innermost table 't3' rather than for each row, and the number of
     instrumented row operations reduces to:

          10 + (10 * 20) + (10 * 20) = 410

     That is a reduction of 93%, illustrating how the batch-reporting
     strategy significantly reduces Performance Schema overhead for
     table I/O by reducing the number of reporting calls.  The tradeoff
     is lesser accuracy for event timing.  Rather than time for an
     individual row operation as in per-row reporting, timing for batch
     I/O includes time spent for operations such as join buffering,
     aggregation, and returning rows to the client.

     For batch I/O reporting to occur, these conditions must be true:

        * Query execution accesses the innermost table of a query block
          (for a single-table query, that table counts as innermost)

        * Query execution does not request a single row from the table
          (so, for example, 'eq_ref' access prevents use of batch
          reporting)

        * Query execution does not evaluate a subquery containing table
          access for the table

   * 'FLAGS'

     Reserved for future use.

'TRUNCATE TABLE' is permitted for the
'events_waits_current' table.  It removes
the rows.

25.11.4.2 The events_waits_history Table
........................................

The 'events_waits_history' table
contains the most recent N wait events per thread.  The value of N is
autosized at server startup.  To set the table size explicitly, set the
'performance_schema_events_waits_history_size' system variable at server
startup.  Wait events are not added to the table until they have ended.
As new events are added, older events are discarded if the table is
full.

The 'events_waits_history' table has
the same structure as 'events_waits_current'.
See events-waits-current-table.

'TRUNCATE TABLE' is permitted for the
'events_waits_history' table.  It removes
the rows.

For information about configuration of wait event collection, see
performance-schema-wait-tables.

25.11.4.3 The events_waits_history_long Table
.............................................

The 'events_waits_history_long'.
table contains the most recent N wait events.  The value of N is
autosized at server startup.  To set the table size explicitly, set the
'performance_schema_events_waits_history_long_size' system variable at
server startup.  Wait events are not added to the table until they have
ended.  As new events are added, older events are discarded if the table
is full.  When a thread ends, its rows are removed from the table.

The 'events_waits_history_long'.
table has the same structure as 'events_waits_current'.
See events-waits-current-table.

'TRUNCATE TABLE' is permitted for the
'events_waits_history_long' table.  It
removes the rows.

For information about configuration of wait event collection, see
performance-schema-wait-tables.

25.11.5 Performance Schema Stage Event Tables
---------------------------------------------

The Performance Schema instruments stages, which are steps during the
statement-execution process, such as parsing a statement, opening a
table, or performing a 'filesort' operation.  Stages correspond to the
thread states displayed by 'SHOW PROCESSLIST'.
or that are visible in the 'INFORMATION_SCHEMA.PROCESSLIST'
table.  Stages begin and end when state values
change.

Within the event hierarchy, wait events nest within stage events, which
nest within statement events, which nest within transaction events.

These tables store stage events:

   * 'events_stages_current'.:
     Current stage events

   * 'events_stages_history'.: The
     most recent stage events per thread

   * 'events_stages_history_long'.:
     The most recent stage events
     globally (across all threads)

The following sections describe the stage event tables.  There are also
summary tables that aggregate information about stage events; see
stage-summary-tables.

*Stage Event Configuration*

To control collection of stage events, set the state of the relevant
instruments and consumers:

   * The 'setup_instruments' table
     contains instruments with names that begin with 'stage'.  Use these
     instruments to enable or disable collection of stage events.

   * The 'setup_consumers' table contains
     consumer values with names corresponding to the current and recent
     stage event table names.  Use these consumers to filter collection
     of stage events.

Other than those instruments that provide statement progress
information, the stage instruments are disabled by default.  For
example:

     mysql> SELECT * FROM setup_instruments WHERE NAME RLIKE 'stage/sql/[a-c]';
     +----------------------------------------------------+---------+-------+
     | NAME                                               | ENABLED | TIMED |
     +----------------------------------------------------+---------+-------+
     | stage/sql/After create                             | NO      | NO    |
     | stage/sql/allocating local table                   | NO      | NO    |
     | stage/sql/altering table                           | NO      | NO    |
     | stage/sql/committing alter table to storage engine | NO      | NO    |
     | stage/sql/Changing master                          | NO      | NO    |
     | stage/sql/Checking master version                  | NO      | NO    |
     | stage/sql/checking permissions                     | NO      | NO    |
     | stage/sql/checking privileges on cached query      | NO      | NO    |
     | stage/sql/checking query cache for query           | NO      | NO    |
     | stage/sql/cleaning up                              | NO      | NO    |
     | stage/sql/closing tables                           | NO      | NO    |
     | stage/sql/Connecting to master                     | NO      | NO    |
     | stage/sql/converting HEAP to MyISAM                | NO      | NO    |
     | stage/sql/Copying to group table                   | NO      | NO    |
     | stage/sql/Copying to tmp table                     | NO      | NO    |
     | stage/sql/copy to tmp table                        | NO      | NO    |
     | stage/sql/Creating sort index                      | NO      | NO    |
     | stage/sql/creating table                           | NO      | NO    |
     | stage/sql/Creating tmp table                       | NO      | NO    |
     +----------------------------------------------------+---------+-------+

Stage event instruments that provide statement progress information are
enabled and timed by default:

     mysql> SELECT * FROM setup_instruments WHERE
            ENABLED='YES' AND NAME LIKE "stage/%";
     +------------------------------------------------------+---------+-------+
     | NAME                                                 | ENABLED | TIMED |
     +------------------------------------------------------+---------+-------+
     | stage/sql/copy to tmp table                          | YES     | YES   |
     | stage/innodb/alter table (end)                       | YES     | YES   |
     | stage/innodb/alter table (flush)                     | YES     | YES   |
     | stage/innodb/alter table (insert)                    | YES     | YES   |
     | stage/innodb/alter table (log apply index)           | YES     | YES   |
     | stage/innodb/alter table (log apply table)           | YES     | YES   |
     | stage/innodb/alter table (merge sort)                | YES     | YES   |
     | stage/innodb/alter table (read PK and internal sort) | YES     | YES   |
     | stage/innodb/buffer pool load                        | YES     | YES   |
     +------------------------------------------------------+---------+-------+

The stage consumers are disabled by default:

     mysql> SELECT * FROM setup_consumers WHERE NAME LIKE '%stages%';
     +----------------------------+---------+
     | NAME                       | ENABLED |
     +----------------------------+---------+
     | events_stages_current      | NO      |
     | events_stages_history      | NO      |
     | events_stages_history_long | NO      |
     +----------------------------+---------+

To control stage event collection at server startup, use lines like
these in your 'my.cnf' file:

   * Enable:

          [mysqld]
          performance-schema-instrument='stage/%=ON'
          performance-schema-consumer-events-stages-current=ON
          performance-schema-consumer-events-stages-history=ON
          performance-schema-consumer-events-stages-history-long=ON

   * Disable:

          [mysqld]
          performance-schema-instrument='stage/%=OFF'
          performance-schema-consumer-events-stages-current=OFF
          performance-schema-consumer-events-stages-history=OFF
          performance-schema-consumer-events-stages-history-long=OFF

To control stage event collection at runtime, update the
'setup_instruments' and
'setup_consumers' tables:

   * Enable:

          UPDATE setup_instruments SET ENABLED = 'YES', TIMED = 'YES'
          WHERE NAME = 'stage/%';
          UPDATE setup_consumers SET ENABLED = 'YES'
          WHERE NAME LIKE '%stages%';

   * Disable:

          UPDATE setup_instruments SET ENABLED = 'NO', TIMED = 'NO'
          WHERE NAME = 'stage/%';
          UPDATE setup_consumers SET ENABLED = 'NO'
          WHERE NAME LIKE '%stages%';

To collect only specific stage events, enable only the corresponding
stage instruments.  To collect stage events only for specific stage
event tables, enable the stage instruments but only the stage consumers
corresponding to the desired tables.

The 'setup_timers' table contains a row with
a 'NAME' value of 'stage' that indicates the unit for stage event
timing.  The default unit is 'NANOSECOND':

     mysql> SELECT * FROM setup_timers WHERE NAME = 'stage';
     +-------+------------+
     | NAME  | TIMER_NAME |
     +-------+------------+
     | stage | NANOSECOND |
     +-------+------------+

To change the timing unit, modify the 'TIMER_NAME' value:

     UPDATE setup_timers SET TIMER_NAME = 'MICROSECOND'
     WHERE NAME = 'stage';

For additional information about configuring event collection, see
performance-schema-startup-configuration, and
performance-schema-runtime-configuration.

*Stage Event Progress Information*

The Performance Schema stage event tables contain two columns that,
taken together, provide a stage progress indicator for each row:

   * 'WORK_COMPLETED': The number of work units completed for the stage

   * 'WORK_ESTIMATED': The number of work units expected for the stage

Each column is 'NULL' if no progress information is provided for an
instrument.  Interpretation of the information, if it is available,
depends entirely on the instrument implementation.  The Performance
Schema tables provide a container to store progress data, but make no
assumptions about the semantics of the metric itself:

   * A 'work unit' is an integer metric that increases over time during
     execution, such as the number of bytes, rows, files, or tables
     processed.  The definition of 'work unit' for a particular
     instrument is left to the instrumentation code providing the data.

   * The 'WORK_COMPLETED' value can increase one or many units at a
     time, depending on the instrumented code.

   * The 'WORK_ESTIMATED' value can change during the stage, depending
     on the instrumented code.

Instrumentation for a stage event progress indicator can implement any
of the following behaviors:

   * No progress instrumentation

     This is the most typical case, where no progress data is provided.
     The 'WORK_COMPLETED' and 'WORK_ESTIMATED' columns are both 'NULL'.

   * Unbounded progress instrumentation

     Only the 'WORK_COMPLETED' column is meaningful.  No data is
     provided for the 'WORK_ESTIMATED' column, which displays 0.

     By querying the 'events_stages_current'
     table for the monitored session, a
     monitoring application can report how much work has been performed
     so far, but cannot report whether the stage is near completion.
     Currently, no stages are instrumented like this.

   * Bounded progress instrumentation

     The 'WORK_COMPLETED' and 'WORK_ESTIMATED' columns are both
     meaningful.

     This type of progress indicator is appropriate for an an operation
     with a defined completion criterion, such as the table-copy
     instrument described later.  By querying the
     'events_stages_current' table for the
     monitored session, a monitoring application can report how much
     work has been performed so far, and can report the overall
     completion percentage for the stage, by computing the
     'WORK_COMPLETED' / 'WORK_ESTIMATED' ratio.

The 'stage/sql/copy to tmp table' instrument illustrates how progress
indicators work.  During execution of an 'ALTER TABLE'
statement, the 'stage/sql/copy to tmp table' stage is used,
and this stage can execute potentially for a long time, depending on the
size of the data to copy.

The table-copy task has a defined termination (all rows copied), and the
'stage/sql/copy to tmp table' stage is instrumented to provided bounded
progress information: The work unit used is number of rows copied,
'WORK_COMPLETED' and 'WORK_ESTIMATED' are both meaningful, and their
ratio indicates task percentage complete.

To enable the instrument and the relevant consumers, execute these
statements:

     UPDATE setup_instruments SET ENABLED='YES'
     WHERE NAME='stage/sql/copy to tmp table';
     UPDATE setup_consumers SET ENABLED='YES'
     WHERE NAME LIKE 'events_stages_%';

To see the progress of an ongoing 'ALTER TABLE'.
statement, select from the 'events_stages_current'
table.

25.11.5.1 The events_stages_current Table
.........................................

The 'events_stages_current' table
contains current stage events, one row per thread showing the current
status of the thread's most recent monitored stage event.

Of the tables that contain stage event rows, see
'events_stages_current' is the most
fundamental.  Other tables that contain stage event rows are logically
derived from the current events.  For example, the
'events_stages_history' and
'events_stages_history_long' tables
are collections of the most recent stage events, up to a fixed number of
rows.

For information about configuration of stage event collection, see
performance-schema-stage-tables.

The 'events_stages_current' table
has these columns:

   * 'THREAD_ID', 'EVENT_ID'

     The thread associated with the event and the thread current event
     number when the event starts.  The 'THREAD_ID' and 'EVENT_ID'
     values taken together uniquely identify the row.  No two rows have
     the same pair of values.

   * 'END_EVENT_ID'

     This column is set to 'NULL' when the event starts and updated to
     the thread current event number when the event ends.

   * 'EVENT_NAME'

     The name of the instrument that produced the event.  This is a
     'NAME' value from the 'setup_instruments'
     table.  Instrument names may have multiple
     parts and form a hierarchy, as discussed in
     performance-schema-instrument-naming.

   * 'SOURCE'

     The name of the source file containing the instrumented code that
     produced the event and the line number in the file at which the
     instrumentation occurs.  This enables you to check the source to
     determine exactly what code is involved.

   * 'TIMER_START', 'TIMER_END', 'TIMER_WAIT'

     Timing information for the event.  The unit for these values is
     picoseconds (trillionths of a second).  The 'TIMER_START' and
     'TIMER_END' values indicate when event timing started and ended.
     'TIMER_WAIT' is the event elapsed time (duration).

     If an event has not finished, 'TIMER_END' is the current timer
     value and 'TIMER_WAIT' is the time elapsed so far ('TIMER_END' −
     'TIMER_START').

     If an event is produced from an instrument that has 'TIMED = NO',
     timing information is not collected, and 'TIMER_START',
     'TIMER_END', and 'TIMER_WAIT' are all 'NULL'.

     For discussion of picoseconds as the unit for event times and
     factors that affect time values, see
     performance-schema-timing.

   * 'WORK_COMPLETED', 'WORK_ESTIMATED'

     These columns provide stage progress information, for instruments
     that have been implemented to produce such information.
     'WORK_COMPLETED' indicates how many work units have been completed
     for the stage, and 'WORK_ESTIMATED' indicates how many work units
     are expected for the stage.  For more information, see
     stage-event-progress.

   * 'NESTING_EVENT_ID'

     The 'EVENT_ID' value of the event within which this event is
     nested.  The nesting event for a stage event is usually a statement
     event.

   * 'NESTING_EVENT_TYPE'

     The nesting event type.  The value is 'TRANSACTION', 'STATEMENT',
     'STAGE', or 'WAIT'.

'TRUNCATE TABLE' is permitted for the
'events_stages_current' table.  It removes
the rows.

25.11.5.2 The events_stages_history Table
.........................................

The 'events_stages_history' table
contains the most recent N stage events per thread.  The value of N is
autosized at server startup.  To set the table size explicitly, set the
'performance_schema_events_stages_history_size' system variable at
server startup.  Stage events are not added to the table until they have
ended.  As new events are added, older events are discarded if the table
is full.

The 'events_stages_history' table
has the same structure as 'events_stages_current'.
See events-stages-current-table.

'TRUNCATE TABLE' is permitted for the
'events_stages_history' table.  It removes
the rows.

For information about configuration of stage event collection, see
performance-schema-stage-tables.

25.11.5.3 The events_stages_history_long Table
..............................................

The 'events_stages_history_long'
table contains the most recent N stage
events.  The value of N is autosized at server startup.  To set the
table size explicitly, set the
'performance_schema_events_stages_history_long_size' system variable at
server startup.  Stage events are not added to the table until they have
ended.  As new events are added, older events are discarded if the table
is full.  When a thread ends, its rows are removed from the table.

The 'events_stages_history_long'
table has the same structure as
'events_stages_current'.  See
events-stages-current-table.

'TRUNCATE TABLE' is permitted for the
'events_stages_history_long' table.
It removes the rows.

For information about configuration of stage event collection, see
performance-schema-stage-tables.

25.11.6 Performance Schema Statement Event Tables
-------------------------------------------------

The Performance Schema instruments statement execution.  Statement
events occur at a high level of the event hierarchy.  Within the event
hierarchy, wait events nest within stage events, which nest within
statement events, which nest within transaction events.

These tables store statement events:

   * 'events_statements_current'.:
     Current statement events

   * 'events_statements_history'.:
     The most recent statement events
     per thread

   * 'events_statements_history_long'.:
     The most recent statement
     events globally (across all threads)

   * 'prepared_statements_instances'.:
     Prepared statement instances
     and statistics

The following sections describe the statement event tables.  There are
also summary tables that aggregate information about statement events;
see statement-summary-tables.

*Statement Event Configuration*

To control collection of statement events, set the state of the relevant
instruments and consumers:

   * The 'setup_instruments' table
     contains instruments with names that begin with 'statement'.  Use
     these instruments to enable or disable collection of statement
     events.

   * The 'setup_consumers' table contains
     consumer values with names corresponding to the current and recent
     statement event table names, and the statement digest consumer.
     Use these consumers to filter collection of statement events and
     statement digesting.

The statement instruments are enabled by default, and the
'events_statements_current', 'events_statements_history', and
'statements_digest' statement consumers are enabled by default:

     mysql> SELECT * FROM setup_instruments WHERE NAME LIKE 'statement/%';
     +---------------------------------------------+---------+-------+
     | NAME                                        | ENABLED | TIMED |
     +---------------------------------------------+---------+-------+
     | statement/sql/select                        | YES     | YES   |
     | statement/sql/create_table                  | YES     | YES   |
     | statement/sql/create_index                  | YES     | YES   |
     ...
     | statement/sp/stmt                           | YES     | YES   |
     | statement/sp/set                            | YES     | YES   |
     | statement/sp/set_trigger_field              | YES     | YES   |
     | statement/scheduler/event                   | YES     | YES   |
     | statement/com/Sleep                         | YES     | YES   |
     | statement/com/Quit                          | YES     | YES   |
     | statement/com/Init DB                       | YES     | YES   |
     ...
     | statement/abstract/Query                    | YES     | YES   |
     | statement/abstract/new_packet               | YES     | YES   |
     | statement/abstract/relay_log                | YES     | YES   |
     +---------------------------------------------+---------+-------+

     mysql> SELECT * FROM setup_consumers WHERE NAME LIKE '%statements%';
     +--------------------------------+---------+
     | NAME                           | ENABLED |
     +--------------------------------+---------+
     | events_statements_current      | YES     |
     | events_statements_history      | YES     |
     | events_statements_history_long | NO      |
     | statements_digest              | YES     |
     +--------------------------------+---------+

To control statement event collection at server startup, use lines like
these in your 'my.cnf' file:

   * Enable:

          [mysqld]
          performance-schema-instrument='statement/%=ON'
          performance-schema-consumer-events-statements-current=ON
          performance-schema-consumer-events-statements-history=ON
          performance-schema-consumer-events-statements-history-long=ON
          performance-schema-consumer-statements-digest=ON

   * Disable:

          [mysqld]
          performance-schema-instrument='statement/%=OFF'
          performance-schema-consumer-events-statements-current=OFF
          performance-schema-consumer-events-statements-history=OFF
          performance-schema-consumer-events-statements-history-long=OFF
          performance-schema-consumer-statements-digest=OFF

To control statement event collection at runtime, update the
'setup_instruments' and
'setup_consumers' tables:

   * Enable:

          UPDATE setup_instruments SET ENABLED = 'YES', TIMED = 'YES'
          WHERE NAME LIKE 'statement/%';
          UPDATE setup_consumers SET ENABLED = 'YES'
          WHERE NAME LIKE '%statements%';

   * Disable:

          UPDATE setup_instruments SET ENABLED = 'NO', TIMED = 'NO'
          WHERE NAME LIKE 'statement/%';
          UPDATE setup_consumers SET ENABLED = 'NO'
          WHERE NAME LIKE '%statements%';

To collect only specific statement events, enable only the corresponding
statement instruments.  To collect statement events only for specific
statement event tables, enable the statement instruments but only the
statement consumers corresponding to the desired tables.

The 'setup_timers' table contains a row with
a 'NAME' value of 'statement' that indicates the unit for statement
event timing.  The default unit is 'NANOSECOND':

     mysql> SELECT * FROM setup_timers WHERE NAME = 'statement';
     +-----------+------------+
     | NAME      | TIMER_NAME |
     +-----------+------------+
     | statement | NANOSECOND |
     +-----------+------------+

To change the timing unit, modify the 'TIMER_NAME' value:

     UPDATE setup_timers SET TIMER_NAME = 'MICROSECOND'
     WHERE NAME = 'statement';

For additional information about configuring event collection, see
performance-schema-startup-configuration, and
performance-schema-runtime-configuration.

*Statement Monitoring*

Statement monitoring begins from the moment the server sees that
activity is requested on a thread, to the moment when all activity has
ceased.  Typically, this means from the time the server gets the first
packet from the client to the time the server has finished sending the
response.  Statements within stored programs are monitored like other
statements.

When the Performance Schema instruments a request (server command or SQL
statement), it uses instrument names that proceed in stages from more
general (or 'abstract') to more specific until it arrives at a final
instrument name.

Final instrument names correspond to server commands and SQL statements:

   * Server commands correspond to the 'COM_XXX codes' defined in the
     'mysql_com.h' header file and processed in 'sql/sql_parse.cc'.
     Examples are 'COM_PING' and 'COM_QUIT'.  Instruments for commands
     have names that begin with 'statement/com', such as
     'statement/com/Ping' and 'statement/com/Quit'.

   * SQL statements are expressed as text, such as 'DELETE FROM t1' or
     'SELECT * FROM t2'.  Instruments for SQL statements have names that
     begin with 'statement/sql', such as 'statement/sql/delete' and
     'statement/sql/select'.

Some final instrument names are specific to error handling:

   * 'statement/com/Error' accounts for messages received by the server
     that are out of band.  It can be used to detect commands sent by
     clients that the server does not understand.  This may be helpful
     for purposes such as identifying clients that are misconfigured or
     using a version of MySQL more recent than that of the server, or
     clients that are attempting to attack the server.

   * 'statement/sql/error' accounts for SQL statements that fail to
     parse.  It can be used to detect malformed queries sent by clients.
     A query that fails to parse differs from a query that parses but
     fails due to an error during execution.  For example, 'SELECT *
     FROM' is malformed, and the 'statement/sql/error' instrument is
     used.  By contrast, 'SELECT *' parses but fails with a 'No tables
     used' error.  In this case, 'statement/sql/select' is used and the
     statement event contains information to indicate the nature of the
     error.

A request can be obtained from any of these sources:

   * As a command or statement request from a client, which sends the
     request as packets

   * As a statement string read from the relay log on a replication
     slave

   * As an event from the Event Scheduler

The details for a request are not initially known and the Performance
Schema proceeds from abstract to specific instrument names in a sequence
that depends on the source of the request.

For a request received from a client:

  1. When the server detects a new packet at the socket level, a new
     statement is started with an abstract instrument name of
     'statement/abstract/new_packet'.

  2. When the server reads the packet number, it knows more about the
     type of request received, and the Performance Schema refines the
     instrument name.  For example, if the request is a 'COM_PING'
     packet, the instrument name becomes 'statement/com/Ping' and that
     is the final name.  If the request is a 'COM_QUERY' packet, it is
     known to correspond to an SQL statement but not the particular type
     of statement.  In this case, the instrument changes from one
     abstract name to a more specific but still abstract name,
     'statement/abstract/Query', and the request requires further
     classification.

  3. If the request is a statement, the statement text is read and given
     to the parser.  After parsing, the exact statement type is known.
     If the request is, for example, an 'INSERT'.
     statement, the Performance Schema refines the instrument name from
     'statement/abstract/Query' to 'statement/sql/insert', which is the
     final name.

For a request read as a statement from the relay log on a replication
slave:

  1. Statements in the relay log are stored as text and are read as
     such.  There is no network protocol, so the
     'statement/abstract/new_packet' instrument is not used.  Instead,
     the initial instrument is 'statement/abstract/relay_log'.

  2. When the statement is parsed, the exact statement type is known.
     If the request is, for example, an 'INSERT'.
     statement, the Performance Schema refines the instrument name from
     'statement/abstract/Query' to 'statement/sql/insert', which is the
     final name.

The preceding description applies only for statement-based replication.
For row-based replication, table I/O done on the slave as it processes
row changes can be instrumented, but row events in the relay log do not
appear as discrete statements.

For a request received from the Event Scheduler:

The event execution is instrumented using the name
'statement/scheduler/event'.  This is the final name.

Statements executed within the event body are instrumented using
'statement/sql/*' names, without use of any preceding abstract
instrument.  An event is a stored program, and stored programs are
precompiled in memory before execution.  Consequently, there is no
parsing at runtime and the type of each statement is known by the time
it executes.

Statements executed within the event body are child statements.  For
example, if an event executes an 'INSERT' statement,
execution of the event itself is the parent, instrumented using
'statement/scheduler/event', and the 'INSERT' is the
child, instrumented using 'statement/sql/insert'.  The parent/child
relationship holds _between_ separate instrumented operations.  This
differs from the sequence of refinement that occurs _within_ a single
instrumented operation, from abstract to final instrument names.

For statistics to be collected for statements, it is not sufficient to
enable only the final 'statement/sql/*' instruments used for individual
statement types.  The abtract 'statement/abstract/*' instruments must be
enabled as well.  This should not normally be an issue because all
statement instruments are enabled by default.  However, an application
that enables or disables statement instruments selectively must take
into account that disabling abstract instruments also disables
statistics collection for the individual statement instruments.  For
example, to collect statistics for 'INSERT' statements,
'statement/sql/insert' must be enabled, but also
'statement/abstract/new_packet' and 'statement/abstract/Query'.
Similarly, for replicated statements to be instrumented,
'statement/abstract/relay_log' must be enabled.

No statistics are aggregated for abstract instruments such as
'statement/abstract/Query' because no statement is ever classified with
an abstract instrument as the final statement name.

25.11.6.1 The events_statements_current Table
.............................................

The 'events_statements_current'.
table contains current statement events, one row per thread showing the
current status of the thread's most recent monitored statement event.

Of the tables that contain statement event rows, see
'events_statements_current' is the
most fundamental.  Other tables that contain statement event rows are
logically derived from the current events.  For example, the
'events_statements_history' and
'events_statements_history_long'.
tables are collections of the most recent statement events, up to a
fixed number of rows.

For information about configuration of statement event collection, see
performance-schema-statement-tables.

The 'events_statements_current'.
table has these columns:

   * 'THREAD_ID', 'EVENT_ID'

     The thread associated with the event and the thread current event
     number when the event starts.  The 'THREAD_ID' and 'EVENT_ID'
     values taken together uniquely identify the row.  No two rows have
     the same pair of values.

   * 'END_EVENT_ID'

     This column is set to 'NULL' when the event starts and updated to
     the thread current event number when the event ends.

   * 'EVENT_NAME'

     The name of the instrument from which the event was collected.
     This is a 'NAME' value from the 'setup_instruments'
     table.  Instrument names may have multiple
     parts and form a hierarchy, as discussed in
     performance-schema-instrument-naming.

     For SQL statements, the 'EVENT_NAME' value initially is
     'statement/com/Query' until the statement is parsed, then changes
     to a more appropriate value, as described in
     performance-schema-statement-tables.

   * 'SOURCE'

     The name of the source file containing the instrumented code that
     produced the event and the line number in the file at which the
     instrumentation occurs.  This enables you to check the source to
     determine exactly what code is involved.

   * 'TIMER_START', 'TIMER_END', 'TIMER_WAIT'

     Timing information for the event.  The unit for these values is
     picoseconds (trillionths of a second).  The 'TIMER_START' and
     'TIMER_END' values indicate when event timing started and ended.
     'TIMER_WAIT' is the event elapsed time (duration).

     If an event has not finished, 'TIMER_END' is the current timer
     value and 'TIMER_WAIT' is the time elapsed so far ('TIMER_END' −
     'TIMER_START').

     If an event is produced from an instrument that has 'TIMED = NO',
     timing information is not collected, and 'TIMER_START',
     'TIMER_END', and 'TIMER_WAIT' are all 'NULL'.

     For discussion of picoseconds as the unit for event times and
     factors that affect time values, see
     performance-schema-timing.

   * 'LOCK_TIME'

     The time spent waiting for table locks.  This value is computed in
     microseconds but normalized to picoseconds for easier comparison
     with other Performance Schema timers.

   * 'SQL_TEXT'

     The text of the SQL statement.  For a command not associated with
     an SQL statement, the value is 'NULL'.

     The maximum space available for statement display is 1024 bytes by
     default.  To change this value, set the
     'performance_schema_max_sql_text_length' system variable at server
     startup.

   * 'DIGEST'

     The statement digest MD5 value as a string of 32 hexadecimal
     characters, or 'NULL' if the 'statements_digest' consumer is 'no'.
     For more information about statement digesting, see
     performance-schema-statement-digests.

   * 'DIGEST_TEXT'

     The normalized statement digest text, or 'NULL' if the
     'statements_digest' consumer is 'no'.  For more information about
     statement digesting, see
     performance-schema-statement-digests.

     The 'performance_schema_max_digest_length' system variable
     determines the maximum number of bytes available for digest value
     storage.  However, the display length of statement digests may be
     longer than the available buffer size due to encoding of statement
     components such as keywords and literal values in digest buffer.
     Consequently, values selected from the 'DIGEST_TEXT' column of
     statement event tables may appear to exceed the
     'performance_schema_max_digest_length' value.

   * 'CURRENT_SCHEMA'

     The default database for the statement, 'NULL' if there is none.

   * 'OBJECT_SCHEMA', 'OBJECT_NAME', 'OBJECT_TYPE'

     For nested statements (stored programs), these columns contain
     information about the parent statement.  Otherwise they are 'NULL'.

   * 'OBJECT_INSTANCE_BEGIN'

     This column identifies the statement.  The value is the address of
     an object in memory.

   * 'MYSQL_ERRNO'

     The statement error number, from the statement diagnostics area.

   * 'RETURNED_SQLSTATE'

     The statement SQLSTATE value, from the statement diagnostics area.

   * 'MESSAGE_TEXT'

     The statement error message, from the statement diagnostics area.

   * 'ERRORS'

     Whether an error occurred for the statement.  The value is 0 if the
     SQLSTATE value begins with '00' (completion) or '01' (warning).
     The value is 1 is the SQLSTATE value is anything else.

   * 'WARNINGS'

     The number of warnings, from the statement diagnostics area.

   * 'ROWS_AFFECTED'

     The number of rows affected by the statement.  For a description of
     the meaning of 'affected,' see mysql-affected-rows.

   * 'ROWS_SENT'

     The number of rows returned by the statement.

   * 'ROWS_EXAMINED'

     The number of rows read from storage engines during statement
     execution.

   * 'CREATED_TMP_DISK_TABLES'

     Like the 'Created_tmp_disk_tables' status variable, but specific to
     the statement.

   * 'CREATED_TMP_TABLES'

     Like the 'Created_tmp_tables' status variable, but specific to the
     statement.

   * 'SELECT_FULL_JOIN'

     Like the 'Select_full_join' status variable, but specific to the
     statement.

   * 'SELECT_FULL_RANGE_JOIN'

     Like the 'Select_full_range_join' status variable, but specific to
     the statement.

   * 'SELECT_RANGE'

     Like the 'Select_range' status variable, but specific to the
     statement.

   * 'SELECT_RANGE_CHECK'

     Like the 'Select_range_check' status variable, but specific to the
     statement.

   * 'SELECT_SCAN'

     Like the 'Select_scan' status variable, but specific to the
     statement.

   * 'SORT_MERGE_PASSES'

     Like the 'Sort_merge_passes' status variable, but specific to the
     statement.

   * 'SORT_RANGE'

     Like the 'Sort_range' status variable, but specific to the
     statement.

   * 'SORT_ROWS'

     Like the 'Sort_rows' status variable, but specific to the
     statement.

   * 'SORT_SCAN'

     Like the 'Sort_scan' status variable, but specific to the
     statement.

   * 'NO_INDEX_USED'

     1 if the statement performed a table scan without using an index, 0
     otherwise.

   * 'NO_GOOD_INDEX_USED'

     1 if the server found no good index to use for the statement, 0
     otherwise.  For additional information, see the description of the
     'Extra' column from 'EXPLAIN' output for the 'Range checked for
     each record' value in explain-output.

   * 'NESTING_EVENT_ID', 'NESTING_EVENT_TYPE', 'NESTING_EVENT_LEVEL'

     These three columns are used with other columns to provide
     information as follows for top-level (unnested) statements and
     nested statements (executed within a stored program).

     For top level statements:

          OBJECT_TYPE = NULL
          OBJECT_SCHEMA = NULL
          OBJECT_NAME = NULL
          NESTING_EVENT_ID = NULL
          NESTING_EVENT_TYPE = NULL
          NESTING_LEVEL = 0

     For nested statements:

          OBJECT_TYPE = the parent statement object type
          OBJECT_SCHEMA = the parent statement object schema
          OBJECT_NAME = the parent statement object name
          NESTING_EVENT_ID = the parent statement EVENT_ID
          NESTING_EVENT_TYPE = 'STATEMENT'
          NESTING_LEVEL = the parent statement NESTING_LEVEL plus one

'TRUNCATE TABLE' is permitted for the
'events_statements_current' table.  It
removes the rows.

25.11.6.2 The events_statements_history Table
.............................................

The 'events_statements_history'.
table contains the most recent N statement events per thread.  The value
of N is autosized at server startup.  To set the table size explicitly,
set the 'performance_schema_events_statements_history_size' system
variable at server startup.  Statement events are not added to the table
until they have ended.  As new events are added, older events are
discarded if the table is full.

The 'events_statements_history'.
table has the same structure as 'events_statements_current'.
See
events-statements-current-table.

'TRUNCATE TABLE' is permitted for the
'events_statements_history' table.  It
removes the rows.

For information about configuration of statement event collection, see
performance-schema-statement-tables.

25.11.6.3 The events_statements_history_long Table
..................................................

The 'events_statements_history_long'
table contains the most recent N
statement events.  The value of N is autosized at server startup.  To
set the table size explicitly, set the
'performance_schema_events_statements_history_long_size' system variable
at server startup.  Statement events are not added to the table until
they have ended.  As new events are added, older events are discarded if
the table is full.  When a thread ends, its rows are removed from the
table.

The 'events_statements_history_long'
table has the same structure as
'events_statements_current'.  See
events-statements-current-table.

'TRUNCATE TABLE' is permitted for the
'events_statements_history_long'.
table.  It removes the rows.

For information about configuration of statement event collection, see
performance-schema-statement-tables.

25.11.6.4 The prepared_statements_instances Table
.................................................

The Performance Schema provides instrumentation for prepared statements,
for which there are two protocols:

   * The binary protocol.  This is accessed through the MySQL C API and
     maps onto underlying server commands as shown in the following
     table.

     C API Function                       Corresponding Server Command

     See 'mysql_stmt_prepare()'.

     See 'mysql_stmt_execute()'.

     See 'mysql_stmt_close()'.

   * The text protocol.  This is accessed using SQL statements and maps
     onto underlying server commands as shown in the following table.

     SQL Statement                        Corresponding Server Command

     See 'PREPARE'.            'SQLCOM_PREPARE'

     See 'EXECUTE'.            'SQLCOM_EXECUTE'

     See 'DEALLOCATE PREPARE',
     see 'DROP PREPARE'.

Performance Schema prepared statement instrumentation covers both
protocols.  The following discussion refers to the server commands
rather than the C API functions or SQL statements.

Information about prepared statements is available in the
'prepared_statements_instances'.
table.  This table enables inspection of prepared statements used in the
server and provides aggregated statistics about them.  To control the
size of this table, set the
'performance_schema_max_prepared_statements_instances' system variable
at server startup.

Collection of prepared statement information depends on the statement
instruments shown in the following table.  These instruments are enabled
by default.  To modify them, update the 'setup_instruments'
table.

Instrument                           Server Command

'statement/com/Prepare'              'COM_STMT_PREPARE'

'statement/com/Execute'              'COM_STMT_EXECUTE'

'statement/sql/prepare_sql'          'SQLCOM_PREPARE'

'statement/sql/execute_sql'          'SQLCOM_EXECUTE'

The Performance Schema manages the contents of the
'prepared_statements_instances'.
table as follows:

   * Statement preparation

     A 'COM_STMT_PREPARE' or 'SQLCOM_PREPARE' command creates a prepared
     statement in the server.  If the statement is successfully
     instrumented, a new row is added to the
     'prepared_statements_instances'
     table.  If the statement
     cannot be instrumented,
     'Performance_schema_prepared_statements_lost' status variable is
     incremented.

   * Prepared statement execution

     Execution of a 'COM_STMT_EXECUTE' or 'SQLCOM_PREPARE' command for
     an instrumented prepared statement instance updates the
     corresponding 'prepared_statements_instances'
     table row.

   * Prepared statement deallocation

     Execution of a 'COM_STMT_CLOSE' or 'SQLCOM_DEALLOCATE_PREPARE'
     command for an instrumented prepared statement instance removes the
     corresponding 'prepared_statements_instances'
     table row.  To avoid resource
     leaks, removal occurs even if the prepared statement instruments
     described previously are disabled.

The 'prepared_statements_instances'
table has these columns:

   * 'OBJECT_INSTANCE_BEGIN'

     The address in memory of the instrumented prepared statement.

   * 'STATEMENT_ID'

     The internal statement ID assigned by the server.  The text and
     binary protocols both use statement IDs.

   * 'STATEMENT_NAME'

     For the binary protocol, this column is 'NULL'.  For the text
     protocol, this column is the external statement name assigned by
     the user.  For example, for the following SQL statement, the name
     of the prepared statement is 'stmt':

          PREPARE stmt FROM 'SELECT 1';

   * 'SQL_TEXT'

     The prepared statement text, with '?' placeholder markers.

   * 'OWNER_THREAD_ID', 'OWNER_EVENT_ID'

     These columns indicate the event that created the prepared
     statement.

   * 'OWNER_OBJECT_TYPE', 'OWNER_OBJECT_SCHEMA', 'OWNER_OBJECT_NAME'

     For a prepared statement created by a client session, these columns
     are 'NULL'.  For a prepared statement created by a stored program,
     these columns point to the stored program.  A typical user error is
     forgetting to deallocate prepared statements.  These columns can be
     used to find stored programs that leak prepared statements:

          SELECT OWNER_OBJECT_TYPE, OWNER_OBJECT_SCHEMA, OWNER_OBJECT_NAME,
          STATEMENT_NAME, SQL_TEXT
          FROM performance_schema.prepared_statements_instances
          WHERE OWNER_OBJECT_TYPE IS NOT NULL;

   * 'TIMER_PREPARE'

     The time spent executing the statement preparation itself.

   * 'COUNT_REPREPARE'

     The number of times the statement was reprepared internally (see
     statement-caching).  Timing statistics for repreparation
     are not available because it is counted as part of statement
     execution, not as a separate operation.

   * 'COUNT_EXECUTE', 'SUM_TIMER_EXECUTE', 'MIN_TIMER_EXECUTE',
     'AVG_TIMER_EXECUTE', 'MAX_TIMER_EXECUTE'

     Aggregated statistics for executions of the prepared statement.

   * 'SUM_XXX'

     The remaining 'SUM_XXX' columns are the same as for the statement
     summary tables (see statement-summary-tables).

'TRUNCATE TABLE' resets the statistics columns of
the 'prepared_statements_instances'
table.

25.11.7 Performance Schema Transaction Tables
---------------------------------------------

The Performance Schema instruments transactions.  Within the event
hierarchy, wait events nest within stage events, which nest within
statement events, which nest within transaction events.

These tables store transaction events:

   * 'events_transactions_current'.:
     Current transaction events

   * 'events_transactions_history'.:
     The most recent transaction
     events per thread

   * 'events_transactions_history_long'.:
     The most recent
     transaction events globally (across all threads)

The following sections describe the transaction event tables.  There are
also summary tables that aggregate information about transaction events;
see transaction-summary-tables.

*Transaction Event Configuration*

To control collection of transaction events, set the state of the
relevant instruments and consumers:

   * The 'setup_instruments' table
     contains an instrument named 'transaction'.  Use this instrument to
     enable or disable collection of transaction events.

   * The 'setup_consumers' table contains
     consumer values with names corresponding to the current and recent
     transaction event table names.  Use these consumers to filter
     collection of transaction events.

The 'transaction' instrument and the transaction consumers are disabled
by default:

     mysql> SELECT * FROM setup_instruments WHERE NAME = 'transaction';
     +-------------+---------+-------+
     | NAME        | ENABLED | TIMED |
     +-------------+---------+-------+
     | transaction | NO      | NO    |
     +-------------+---------+-------+
     mysql> SELECT * FROM setup_consumers WHERE NAME LIKE '%transactions%';
     +----------------------------------+---------+
     | NAME                             | ENABLED |
     +----------------------------------+---------+
     | events_transactions_current      | NO      |
     | events_transactions_history      | NO      |
     | events_transactions_history_long | NO      |
     +----------------------------------+---------+

To control transaction event collection at server startup, use lines
like these in your 'my.cnf' file:

   * Enable:

          [mysqld]
          performance-schema-instrument='transaction=ON'
          performance-schema-consumer-events-transactions-current=ON
          performance-schema-consumer-events-transactions-history=ON
          performance-schema-consumer-events-transactions-history-long=ON

   * Disable:

          [mysqld]
          performance-schema-instrument='transaction=OFF'
          performance-schema-consumer-events-transactions-current=OFF
          performance-schema-consumer-events-transactions-history=OFF
          performance-schema-consumer-events-transactions-history-long=OFF

To control transaction event collection at runtime, update the
'setup_instruments' and
'setup_consumers' tables:

   * Enable:

          UPDATE setup_instruments SET ENABLED = 'YES', TIMED = 'YES'
          WHERE NAME = 'transaction';
          UPDATE setup_consumers SET ENABLED = 'YES'
          WHERE NAME LIKE '%transactions%';

   * Disable:

          UPDATE setup_instruments SET ENABLED = 'NO', TIMED = 'NO'
          WHERE NAME = 'transaction';
          UPDATE setup_consumers SET ENABLED = 'NO'
          WHERE NAME LIKE '%transactions%';

To collect transaction events only for specific transaction event
tables, enable the 'transaction' instrument but only the transaction
consumers corresponding to the desired tables.

The 'setup_timers' table contains a row with
a 'NAME' value of 'transaction' that indicates the unit for transaction
event timing.  The default unit is 'NANOSECOND':

     mysql> SELECT * FROM setup_timers WHERE NAME = 'transaction';
     +-------------+------------+
     | NAME        | TIMER_NAME |
     +-------------+------------+
     | transaction | NANOSECOND |
     +-------------+------------+

To change the timing unit, modify the 'TIMER_NAME' value:

     UPDATE setup_timers SET TIMER_NAME = 'MICROSECOND'
     WHERE NAME = 'transaction';

For additional information about configuring event collection, see
performance-schema-startup-configuration, and
performance-schema-runtime-configuration.

*Transaction Boundaries*

In MySQL Server, transactions start explicitly with these statements:

     START TRANSACTION | BEGIN | XA START | XA BEGIN

Transactions also start implicitly.  For example, when the 'autocommit'
system variable is enabled, the start of each statement starts a new
transaction.

When 'autocommit' is disabled, the first statement following a committed
transaction marks the start of a new transaction.  Subsequent statements
are part of the transaction until it is committed.

Transactions explicitly end with these statements:

     COMMIT | ROLLBACK | XA COMMIT | XA ROLLBACK

Transactions also end implicitly, by execution of DDL statements,
locking statements, and server administration statements.

In the following discussion, references to 'START TRANSACTION'
also apply to 'BEGIN', 'XA START',
and 'XA BEGIN'.  Similarly,
references to 'COMMIT' and 'ROLLBACK'.
apply to 'XA COMMIT' and 'XA ROLLBACK',
respectively.

The Performance Schema defines transaction boundaries similarly to that
of the server.  The start and end of a transaction event closely match
the corresponding state transitions in the server:

   * For an explicitly started transaction, the transaction event starts
     during processing of the 'START TRANSACTION'.
     statement.

   * For an implicitly started transaction, the transaction event starts
     on the first statement that uses a transactional engine after the
     previous transaction has ended.

   * For any transaction, whether explicitly or implicitly ended, the
     transaction event ends when the server transitions out of the
     active transaction state during the processing of 'COMMIT'
     or 'ROLLBACK'.

There are subtle implications to this approach:

   * Transaction events in the Performance Schema do not fully include
     the statement events associated with the corresponding 'START TRANSACTION',
     see 'COMMIT', or 'ROLLBACK'
     statements.  There is a trivial amount of timing overlap
     between the transaction event and these statements.

   * Statements that work with nontransactional engines have no effect
     on the transaction state of the connection.  For implicit
     transactions, the transaction event begins with the first statement
     that uses a transactional engine.  This means that statements
     operating exclusively on nontransactional tables are ignored, even
     following 'START TRANSACTION'.

To illustrate, consider the following scenario:

     1. SET autocommit = OFF;
     2. CREATE TABLE t1 (a INT) ENGINE = InnoDB;
     3. START TRANSACTION;                       -- Transaction 1 START
     4. INSERT INTO t1 VALUES (1), (2), (3);
     5. CREATE TABLE t2 (a INT) ENGINE = MyISAM; -- Transaction 1 COMMIT
                                                 -- (implicit; DDL forces commit)
     6. INSERT INTO t2 VALUES (1), (2), (3);     -- Update nontransactional table
     7. UPDATE t2 SET a = a + 1;                 -- ... and again
     8. INSERT INTO t1 VALUES (4), (5), (6);     -- Write to transactional table
                                                 -- Transaction 2 START (implicit)
     9. COMMIT;                                  -- Transaction 2 COMMIT

From the perspective of the server, Transaction 1 ends when table 't2'
is created.  Transaction 2 does not start until a transactional table is
accessed, despite the intervening updates to nontransactional tables.

From the perspective of the Performance Schema, Transaction 2 starts
when the server transitions into an active transaction state.
Statements 6 and 7 are not included within the boundaries of Transaction
2, which is consistent with how the server writes transactions to the
binary log.

*Transaction Instrumentation*

Three attributes define transactions:

   * Access mode (read only, read write)

   * Isolation level ('SERIALIZABLE', 'REPEATABLE READ', and so forth)

   * Implicit ('autocommit' enabled) or explicit ('autocommit' disabled)

To reduce complexity of the transaction instrumentation and to ensure
that the collected transaction data provides complete, meaningful
results, all transactions are instrumented independently of access mode,
isolation level, or autocommit mode.

To selectively examine transaction history, use the attribute columns in
the transaction event tables: 'ACCESS_MODE', 'ISOLATION_LEVEL', and
'AUTOCOMMIT'.

The cost of transaction instrumentation can be reduced various ways,
such as enabling or disabling transaction instrumentation according to
user, account, host, or thread (client connection).

*Transactions and Nested Events*

The parent of a transaction event is the event that initiated the
transaction.  For an explicitly started transaction, this includes the
'START TRANSACTION' and 'COMMIT AND CHAIN'.
statements.  For an implicitly started transaction, it is the first
statement that uses a transactional engine after the previous
transaction ends.

In general, a transaction is the top-level parent to all events
initiated during the transaction, including statements that explicitly
end the transaction such as 'COMMIT' and
'ROLLBACK'.  Exceptions are statements that implicitly end a
transaction, such as DDL statements, in which case the current
transaction must be committed before the new statement is executed.

*Transactions and Stored Programs*

Transactions and stored program events are related as follows:

   * Stored Procedures

     Stored procedures operate independently of transactions.  A stored
     procedure can be started within a transaction, and a transaction
     can be started or ended from within a stored procedure.  If called
     from within a transaction, a stored procedure can execute
     statements that force a commit of the parent transaction and then
     start a new transaction.

     If a stored procedure is started within a transaction, that
     transaction is the parent of the stored procedure event.

     If a transaction is started by a stored procedure, the stored
     procedure is the parent of the transaction event.

   * Stored Functions

     Stored functions are restricted from causing an explicit or
     implicit commit or rollback.  Stored function events can reside
     within a parent transaction event.

   * Triggers

     Triggers activate as part of a statement that accesses the table
     with which it is associated, so the parent of a trigger event is
     always the statement that activates it.

     Triggers cannot issue statements that cause an explicit or implicit
     commit or rollback of a transaction.

   * Scheduled Events

     The execution of the statements in the body of a scheduled event
     takes place in a new connection.  Nesting of a scheduled event
     within a parent transaction is not applicable.

*Transactions and Savepoints*

Savepoint statements are recorded as separate statement events.
Transaction events include separate counters for 'SAVEPOINT',
see 'ROLLBACK TO SAVEPOINT', and 'RELEASE SAVEPOINT'
statements issued during the transaction.

*Transactions and Errors*

Errors and warnings that occur within a transaction are recorded in
statement events, but not in the corresponding transaction event.  This
includes transaction-specific errors and warnings, such as a rollback on
a nontransactional table or GTID consistency errors.

25.11.7.1 The events_transactions_current Table
...............................................

The 'events_transactions_current'
table contains current transaction
events, one row per thread showing the current status of the thread's
most recent monitored transaction event.  For example:

     mysql> SELECT * FROM events_transactions_current LIMIT 1\G
     *************************** 1. row ***************************
                           THREAD_ID: 26
                            EVENT_ID: 7
                        END_EVENT_ID: NULL
                          EVENT_NAME: transaction
                               STATE: ACTIVE
                              TRX_ID: NULL
                                GTID: 3E11FA47-71CA-11E1-9E33-C80AA9429562:56
                                 XID: NULL
                            XA_STATE: NULL
                              SOURCE: transaction.cc:150
                         TIMER_START: 420833537900000
                           TIMER_END: NULL
                          TIMER_WAIT: NULL
                         ACCESS_MODE: READ WRITE
                     ISOLATION_LEVEL: REPEATABLE READ
                          AUTOCOMMIT: NO
                NUMBER_OF_SAVEPOINTS: 0
     NUMBER_OF_ROLLBACK_TO_SAVEPOINT: 0
         NUMBER_OF_RELEASE_SAVEPOINT: 0
               OBJECT_INSTANCE_BEGIN: NULL
                    NESTING_EVENT_ID: 6
                  NESTING_EVENT_TYPE: STATEMENT

Of the tables that contain transaction event rows, see
'events_transactions_current' is the
most fundamental.  Other tables that contain transaction event rows are
logically derived from the current events.  For example, the
'events_transactions_history' and
'events_transactions_history_long'
tables are collections of the
most recent transaction events, up to a fixed number of rows.

For information about configuration of transaction event collection, see
performance-schema-transaction-tables.

The 'events_transactions_current'
table has these columns:

   * 'THREAD_ID', 'EVENT_ID'

     The thread associated with the event and the thread current event
     number when the event starts.  The 'THREAD_ID' and 'EVENT_ID'
     values taken together uniquely identify the row.  No two rows have
     the same pair of values.

   * 'END_EVENT_ID'

     This column is set to 'NULL' when the event starts and updated to
     the thread current event number when the event ends.

   * 'EVENT_NAME'

     The name of the instrument from which the event was collected.
     This is a 'NAME' value from the 'setup_instruments'
     table.  Instrument names may have multiple
     parts and form a hierarchy, as discussed in
     performance-schema-instrument-naming.

   * 'STATE'

     The current transaction state.  The value is 'ACTIVE' (after
     'START TRANSACTION' or 'BEGIN'),
     'COMMITTED' (after 'COMMIT'), or 'ROLLED BACK'
     (after 'ROLLBACK').

   * 'TRX_ID'

     Unused.

   * 'GTID'

     The GTID column contains the value of 'gtid_next', which can be one
     of 'ANONYMOUS', 'AUTOMATIC', or a GTID using the format
     'UUID:NUMBER'.  For transactions that use 'gtid_next=AUTOMATIC',
     which is all normal client transactions, the GTID column changes
     when the transaction commits and the actual GTID is assigned.  If
     'gtid_mode' is either 'ON' or 'ON_PERMISSIVE', the GTID column
     changes to the transaction's GTID. If 'gtid_mode' is either 'OFF'
     or 'OFF_PERMISSIVE', the GTID column changes to 'ANONYMOUS'.

   * 'XID_FORMAT_ID', 'XID_GTRID', and 'XID_BQUAL'

     The components of the XA transaction identifier.  They have the
     format described in xa-statements.

   * 'XA_STATE'

     The state of the XA transaction.  The value is 'ACTIVE' (after
     'XA START'), 'IDLE' (after 'XA END'),
     'PREPARED' (after 'XA PREPARE'),
     'ROLLED BACK' (after 'XA ROLLBACK'),
     or 'COMMITTED' (after 'XA COMMIT').

     On a replication slave, the same XA transaction can appear in the
     'events_transactions_current'
     table with different states on
     different threads.  This is because immediately after the XA
     transaction is prepared, it is detached from the slave applier
     thread, and can be committed or rolled back by any thread on the
     slave.  The 'events_transactions_current'
     table displays the current
     status of the most recent monitored transaction event on the
     thread, and does not update this status when the thread is idle.
     So the XA transaction can still be displayed in the 'PREPARED'
     state for the original applier thread, after it has been processed
     by another thread.  To positively identify XA transactions that are
     still in the 'PREPARED' state and need to be recovered, use the
     'XA RECOVER' statement rather than the
     Performance Schema transaction tables.

   * 'SOURCE'

     The name of the source file containing the instrumented code that
     produced the event and the line number in the file at which the
     instrumentation occurs.  This enables you to check the source to
     determine exactly what code is involved.

   * 'TIMER_START', 'TIMER_END', 'TIMER_WAIT'

     Timing information for the event.  The unit for these values is
     picoseconds (trillionths of a second).  The 'TIMER_START' and
     'TIMER_END' values indicate when event timing started and ended.
     'TIMER_WAIT' is the event elapsed time (duration).

     If an event has not finished, 'TIMER_END' is the current timer
     value and 'TIMER_WAIT' is the time elapsed so far ('TIMER_END' −
     'TIMER_START').

     If an event is produced from an instrument that has 'TIMED = NO',
     timing information is not collected, and 'TIMER_START',
     'TIMER_END', and 'TIMER_WAIT' are all 'NULL'.

     For discussion of picoseconds as the unit for event times and
     factors that affect time values, see
     performance-schema-timing.

   * 'ACCESS_MODE'

     The transaction access mode.  The value is 'READ ONLY' or 'READ
     WRITE'.

   * 'ISOLATION_LEVEL'

     The transaction isolation level.  The value is 'REPEATABLE READ',
     'READ COMMITTED', 'READ UNCOMMITTED', or 'SERIALIZABLE'.

   * 'AUTOCOMMIT'

     Whether autcommit mode was enabled when the transaction started.

   * 'NUMBER_OF_SAVEPOINTS', 'NUMBER_OF_ROLLBACK_TO_SAVEPOINT',
     'NUMBER_OF_RELEASE_SAVEPOINT'

     The number of 'SAVEPOINT', 'ROLLBACK TO SAVEPOINT',
     and 'RELEASE SAVEPOINT'.
     statements issued during the transaction.

   * 'OBJECT_INSTANCE_BEGIN'

     Unused.

   * 'NESTING_EVENT_ID'

     The 'EVENT_ID' value of the event within which this event is
     nested.

   * 'NESTING_EVENT_TYPE'

     The nesting event type.  The value is 'TRANSACTION', 'STATEMENT',
     'STAGE', or 'WAIT'.  ('TRANSACTION' will not appear because
     transactions cannot be nested.)

'TRUNCATE TABLE' is permitted for the
'events_transactions_current' table.
It removes the rows.

25.11.7.2 The events_transactions_history Table
...............................................

The 'events_transactions_history'
table contains the most recent N
transaction events per thread.  The value of N is autosized at server
startup.  To set the table size explicitly, set the
'performance_schema_events_transactions_history_size' system variable at
server startup.  Transaction events are not added to the table until
they have ended.  As new events are added, older events are discarded if
the table is full.

The 'events_transactions_history'
table has the same structure as
'events_transactions_current'.  See
events-transactions-current-table.

'TRUNCATE TABLE' is permitted for the
'events_transactions_history' table.
It removes the rows.

For information about configuration of transaction event collection, see
performance-schema-transaction-tables.

25.11.7.3 The events_transactions_history_long Table
....................................................

The 'events_transactions_history_long'
table contains the most recent N
transaction events.  The value of N is autosized at server startup.  To
set the table size explicitly, set the
'performance_schema_events_transactions_history_long_size' system
variable at server startup.  Transaction events are not added to the
table until they have ended.  As new events are added, older events are
discarded if the table is full.  When a thread ends, its rows are
removed from the table.

The 'events_transactions_history_long'
table has the same structure as
'events_transactions_current'.
See events-transactions-current-table.

'TRUNCATE TABLE' is permitted for the
'events_transactions_history_long'
table.  It removes the rows.

For information about configuration of transaction event collection, see
performance-schema-transaction-tables.

25.11.8 Performance Schema Connection Tables
--------------------------------------------

When a client connects to the MySQL server, it does so under a
particular user name and from a particular host.  The Performance Schema
provides statistics about these connections, tracking them per account
(user and host combination) as well as separately per user name and host
name, using these tables:

   * 'accounts'.: Connection statistics per client
     account

   * 'hosts'.: Connection statistics per client host
     name

   * 'users'.: Connection statistics per client user
     name

The meaning of 'account' in the connection tables is similar to its
meaning in the MySQL grant tables in the 'mysql' system database, in the
sense that the term refers to a combination of user and host values.
They differ in that, for grant tables, the host part of an account can
be a pattern, whereas for Performance Schema tables, the host value is
always a specific nonpattern host name.

Each connection table has 'CURRENT_CONNECTIONS' and 'TOTAL_CONNECTIONS'
columns to track the current and total number of connections per
'tracking value' on which its statistics are based.  The tables differ
in what they use for the tracking value.  The 'accounts'
table has 'USER' and 'HOST' columns to track connections
per user and host combination.  The 'users' and
'hosts' tables have a 'USER' and 'HOST' column,
respectively, to track connections per user name and host name.

The Performance Schema also counts internal threads and threads for user
sessions that failed to authenticate, using rows with 'USER' and 'HOST'
column values of 'NULL'.

Suppose that clients named 'user1' and 'user2' each connect one time
from 'hosta' and 'hostb'.  The Performance Schema tracks the connections
as follows:

   * The 'accounts' table has four rows, for the
     'user1'/'hosta', 'user1'/'hostb', 'user2'/'hosta', and
     'user2'/'hostb' account values, each row counting one connection
     per account.

   * The 'hosts' table has two rows, for 'hosta' and
     'hostb', each row counting two connections per host name.

   * The 'users' table has two rows, for 'user1' and
     'user2', each row counting two connections per user name.

When a client connects, the Performance Schema determines which row in
each connection table applies, using the tracking value appropriate to
each table.  If there is no such row, one is added.  Then the
Performance Schema increments by one the 'CURRENT_CONNECTIONS' and
'TOTAL_CONNECTIONS' columns in that row.

When a client disconnects, the Performance Schema decrements by one the
'CURRENT_CONNECTIONS' column in the row and leaves the
'TOTAL_CONNECTIONS' column unchanged.

'TRUNCATE TABLE' is permitted for connection
tables.  It has these effects:

   * Rows are removed for accounts, hosts, or users that have no current
     connections (rows with 'CURRENT_CONNECTIONS = 0').

   * Nonremoved rows are reset to count only current connections: For
     rows with 'CURRENT_CONNECTIONS > 0', 'TOTAL_CONNECTIONS' is reset
     to 'CURRENT_CONNECTIONS'.

   * Summary tables that depend on the connection table are implicitly
     truncated, as described later in this section.

The Performance Schema maintains summary tables that aggregate
connection statistics for various event types by account, host, or user.
These tables have '_summary_by_account', '_summary_by_host', or
'_summary_by_user' in the name.  To identify them, use this query:

     mysql> SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
            WHERE TABLE_SCHEMA = 'performance_schema'
            AND TABLE_NAME REGEXP '_summary_by_(account|host|user)'
            ORDER BY TABLE_NAME;
     +------------------------------------------------------+
     | TABLE_NAME                                           |
     +------------------------------------------------------+
     | events_stages_summary_by_account_by_event_name       |
     | events_stages_summary_by_host_by_event_name          |
     | events_stages_summary_by_user_by_event_name          |
     | events_statements_summary_by_account_by_event_name   |
     | events_statements_summary_by_host_by_event_name      |
     | events_statements_summary_by_user_by_event_name      |
     | events_transactions_summary_by_account_by_event_name |
     | events_transactions_summary_by_host_by_event_name    |
     | events_transactions_summary_by_user_by_event_name    |
     | events_waits_summary_by_account_by_event_name        |
     | events_waits_summary_by_host_by_event_name           |
     | events_waits_summary_by_user_by_event_name           |
     | memory_summary_by_account_by_event_name              |
     | memory_summary_by_host_by_event_name                 |
     | memory_summary_by_user_by_event_name                 |
     +------------------------------------------------------+

For details about individual connection summary tables, consult the
section that describes tables for the summarized event type:

   * Wait event summaries: wait-summary-tables

   * Stage event summaries: stage-summary-tables

   * Statement event summaries: statement-summary-tables

   * Transaction event summaries: transaction-summary-tables

   * Memory event summaries: memory-summary-tables

'TRUNCATE TABLE' is permitted for connection
summary tables.  It removes rows for accounts, hosts, or users with no
connections, and resets the summary columns to zero for the remaining
rows.  In addition, each summary table that is aggregated by account,
host, user, or thread is implicitly truncated by truncation of the
connection table on which it depends.  The following table describes the
relationship between connection table truncation and implicitly
truncated tables.

*Implicit Effects of Connection Table Truncation*

Truncated Connection Table    Implicitly Truncated Summary Tables

'accounts'                    Tables with names containing
                              '_summary_by_account',
                              '_summary_by_thread'

'hosts'                       Tables with names containing
                              '_summary_by_account',
                              '_summary_by_host', '_summary_by_thread'

'users'                       Tables with names containing
                              '_summary_by_account',
                              '_summary_by_user', '_summary_by_thread'

Truncating a '_summary_global' summary table also implicitly truncates
its corresponding connection and thread summary tables.  For example,
truncating 'events_waits_summary_global_by_event_name'
implicitly truncates the wait event summary tables
that are aggregated by account, host, user, or thread.

25.11.8.1 The accounts Table
............................

The 'accounts' table contains a row for each
account that has connected to the MySQL server.  For each account, the
table counts the current and total number of connections.  The table
size is autosized at server startup.  To set the table size explicitly,
set the 'performance_schema_accounts_size' system variable at server
startup.  To disable account statistics, set this variable to 0.

The 'accounts' table has the following columns.
For a description of how the Performance Schema maintains rows in this
table, including the effect of 'TRUNCATE TABLE',
see performance-schema-connection-tables.

   * 'USER'

     The client user name for the connection.  This is 'NULL' for an
     internal thread, or for a user session that failed to authenticate.

   * 'HOST'

     The host from which the client connected.  This is 'NULL' for an
     internal thread, or for a user session that failed to authenticate.

   * 'CURRENT_CONNECTIONS'

     The current number of connections for the account.

   * 'TOTAL_CONNECTIONS'

     The total number of connections for the account.

25.11.8.2 The hosts Table
.........................

The 'hosts' table contains a row for each host from
which clients have connected to the MySQL server.  For each host name,
the table counts the current and total number of connections.  The table
size is autosized at server startup.  To set the table size explicitly,
set the 'performance_schema_hosts_size' system variable at server
startup.  To disable host statistics, set this variable to 0.

The 'hosts' table has the following columns.  For a
description of how the Performance Schema maintains rows in this table,
including the effect of 'TRUNCATE TABLE', see
performance-schema-connection-tables.

   * 'HOST'

     The host from which the client connected.  This is 'NULL' for an
     internal thread, or for a user session that failed to authenticate.

   * 'CURRENT_CONNECTIONS'

     The current number of connections for the host.

   * 'TOTAL_CONNECTIONS'

     The total number of connections for the host.

25.11.8.3 The users Table
.........................

The 'users' table contains a row for each user who
has connected to the MySQL server.  For each user name, the table counts
the current and total number of connections.  The table size is
autosized at server startup.  To set the table size explicitly, set the
'performance_schema_users_size' system variable at server startup.  To
disable user statistics, set this variable to 0.

The 'users' table has the following columns.  For a
description of how the Performance Schema maintains rows in this table,
including the effect of 'TRUNCATE TABLE', see
performance-schema-connection-tables.

   * 'USER'

     The client user name for the connection.  This is 'NULL' for an
     internal thread, or for a user session that failed to authenticate.

   * 'CURRENT_CONNECTIONS'

     The current number of connections for the user.

   * 'TOTAL_CONNECTIONS'

     The total number of connections for the user.

25.11.9 Performance Schema Connection Attribute Tables
------------------------------------------------------

Application programs can provide key/value pairs as connection
attributes to be passed to the server at connect time.  For the C API,
define the attribute set using the 'mysql_options()'
and 'mysql_options4()' functions.
Other MySQL Connectors may provide their own attribute-definition
methods.

These tables expose attribute information:

   * 'session_account_connect_attrs'.:
     Connection attributes for the
     current session, and other sessions associated with the session
     account

   * 'session_connect_attrs'.:
     Connection attributes for all sessions

Attribute names that begin with an underscore ('_') are reserved for
internal use and should not be created by application programs.  This
convention permits new attributes to be introduced by MySQL without
colliding with application attributes.

The set of connection attributes visible on a given connection varies
depending on your platform and MySQL Connector used to establish the
connection.

The 'libmysqlclient' client library (provided in MySQL and MySQL
Connector/C distributions) sets these attributes:

   * '_client_name': The client name ('libmysql' for the client library)

   * '_client_version': The client library version

   * '_os': The operating system (for example, 'Linux', 'Win64')

   * '_pid': The client process ID

   * '_platform': The machine platform (for example, 'x86_64')

   * '_thread': The client thread ID (Windows only)

Other MySQL Connectors may define their own connection attributes.

MySQL Connector/J defines these attributes:

   * '_client_license': The connector license type

   * '_runtime_vendor': The Java runtime environment (JRE) vendor

   * '_runtime_version': The Java runtime environment (JRE) version

MySQL Connector/Net defines these attributes:

   * '_client_version': The client library version

   * '_os': The operating system (for example, 'Linux', 'Win64')

   * '_pid': The client process ID

   * '_platform': The machine platform (for example, 'x86_64')

   * '_program_name': The client name

   * '_thread': The client thread ID (Windows only)

PHP defines attributes that depend on how it was compiled:

   * Compiled using 'libmysqlclient': The standard 'libmysqlclient'
     attributes, described previously

   * Compiled using 'mysqlnd': Only the '_client_name' attribute, with a
     value of 'mysqlnd'

Many MySQL client programs set a 'program_name' attribute with a value
equal to the client name.  For example, see 'mysqladmin'.
and 'mysqldump' set 'program_name' to 'mysqladmin' and
'mysqldump', respectively.

Some MySQL client programs define additional attributes:

   * 'mysqlbinlog' defines the '_client_role'
     attribute as 'binary_log_listener'.

   * Replication slave connections define 'program_name' as 'mysqld',
     '_client_role' as 'binary_log_listener', and
     '_client_replication_channel_name' as the channel name.

   * 'FEDERATED' storage engine
     connections define 'program_name' as 'mysqld' and '_client_role' as
     'federated_storage'.

There are limits on the amount of connection attribute data transmitted
from client to server: A fixed limit imposed by the client prior to
connect time; a fixed limit imposed by the server at connect time; and a
configurable limit imposed by the Performance Schema at connect time.

For connections initiated using the C API, the 'libmysqlclient' library
imposes a limit of 64KB on the aggregate size of connection attribute
data on the client side: Calls to 'mysql_options()'
that cause this limit to be exceeded produce a
'CR_INVALID_PARAMETER_NO' error.  Other MySQL Connectors may impose
their own client-side limits on how much connection attribute data can
be transmitted to the server.

On the server side, these size checks on connection attribute data
occur:

   * The server imposes a limit of 64KB on the aggregate size of
     connection attribute data it will accept.  If a client attempts to
     send more than 64KB of attribute data, the server rejects the
     connection.

   * For accepted connections, the Performance Schema checks aggregate
     attribute size against the value of the
     'performance_schema_session_connect_attrs_size' system variable.
     If attribute size exceeds this value, these actions take place:

        * The Performance Schema truncates the attribute data and
          increments the 'Performance_schema_session_connect_attrs_lost'
          status variable, which indicates the number of connections for
          which attribute truncation occurred.

        * The Performance Schema writes a message to the error log if
          the 'log_error_verbosity' system variable is greater than 1:

               [Warning] Connection attributes of length N were truncated

25.11.9.1 The session_account_connect_attrs Table
.................................................

Application programs can provide key/value connection attributes to be
passed to the server at connect time, using the 'mysql_options()'
and 'mysql_options4()'. C API
functions.  For descriptions of common attributes, see
performance-schema-connection-attribute-tables.

The 'session_account_connect_attrs'
table contains connection
attributes only for sessions for your own account.  To see connection
attributes for all sessions, look in the 'session_connect_attrs'
table.

The 'session_account_connect_attrs'
table contains these columns:

   * 'PROCESSLIST_ID'

     The connection identifier for the session.

   * 'ATTR_NAME'

     The attribute name.

   * 'ATTR_VALUE'

     The attribute value.

   * 'ORDINAL_POSITION'

     The order in which the attribute was added to the set of connection
     attributes.

'TRUNCATE TABLE' is not permitted for the
'session_account_connect_attrs'.
table.

25.11.9.2 The session_connect_attrs Table
.........................................

Application programs can provide key/value connection attributes to be
passed to the server at connect time, using the 'mysql_options()'
and 'mysql_options4()'. C API
functions.  For descriptions of common attributes, see
performance-schema-connection-attribute-tables.

The 'session_connect_attrs' table
contains connection attributes for all sessions.  To see connection
attributes only for sessions for your own account, look in the
'session_account_connect_attrs'.
table.

The 'session_connect_attrs' table
contains these columns:

   * 'PROCESSLIST_ID'

     The connection identifier for the session.

   * 'ATTR_NAME'

     The attribute name.

   * 'ATTR_VALUE'

     The attribute value.

   * 'ORDINAL_POSITION'

     The order in which the attribute was added to the set of connection
     attributes.

'TRUNCATE TABLE' is not permitted for the
'session_connect_attrs' table.

25.11.10 Performance Schema User Variable Tables
------------------------------------------------

The Performance Schema provides a 'user_variables_by_thread'
table that exposes user-defined
variables.  These are variables defined within a specific session and
include a '@' character preceding the name; see user-variables.

The 'user_variables_by_thread'
table contains these columns:

   * 'THREAD_ID'

     The thread identifier of the session in which the variable is
     defined.

   * 'VARIABLE_NAME'

     The variable name, without the leading '@' character.

   * 'VARIABLE_VALUE'

     The variable value.

'TRUNCATE TABLE' is not permitted for the
'user_variables_by_thread'.
table.

25.11.11 Performance Schema Replication Tables
----------------------------------------------

The Performance Schema provides tables that expose replication
information.  This is similar to the information available from the
'SHOW SLAVE STATUS' statement, but
representation in table form is more accessible and has usability
benefits:

   * 'SHOW SLAVE STATUS' output is useful for
     visual inspection, but not so much for programmatic use.  By
     contrast, using the Performance Schema tables, information about
     slave status can be searched using general 'SELECT'.
     queries, including complex 'WHERE' conditions, joins, and so forth.

   * Query results can be saved in tables for further analysis, or
     assigned to variables and thus used in stored procedures.

   * The replication tables provide better diagnostic information.  For
     multi-threaded slave operation, see 'SHOW SLAVE STATUS'
     reports all coordinator and worker thread errors
     using the 'Last_SQL_Errno' and 'Last_SQL_Error' fields, so only the
     most recent of those errors is visible and information can be lost.
     The replication tables store errors on a per-thread basis without
     loss of information.

   * The last seen transaction is visible in the replication tables on a
     per-worker basis.  This is information not avilable from
     'SHOW SLAVE STATUS'.

   * Developers familiar with the Performance Schema interface can
     extend the replication tables to provide additional information by
     adding rows to the tables.

*Replication Table Descriptions*

The Performance Schema provides the following replication-related
tables:

   * Tables that contain information about the connection of the slave
     server to the master server:

        * 'replication_connection_configuration'.:
          Configuration
          parameters for connecting to the master

        * 'replication_connection_status'.:
          Current status of the
          connection to the master

   * Tables that contain general (not thread-specific) information about
     the transaction applier:

        * 'replication_applier_configuration'.:
          Configuration
          parameters for the transaction applier on the slave.

        * 'replication_applier_status'.:
          Current status of the
          transaction applier on the slave.

   * Tables that contain information about specific threads responsible
     for applying transactions received from the master:

        * 'replication_applier_status_by_coordinator'.:
          Status of
          the coordinator thread (empty unless the slave is
          multi-threaded).

        * 'replication_applier_status_by_worker'.:
          Status of the
          applier thread or worker threads if the slave is
          multi-threaded.

   * Tables that contain information about replication group members:

        * 'replication_group_members'.:
          Provides network and status
          information for group members.

        * 'replication_group_member_stats'.:
          Provides statistical
          information about group members and transaction in which they
          participate.

The following sections describe each replication table in more detail,
including the correspondence between the columns produced by 'SHOW SLAVE STATUS'
and the replication table columns in
which the same information appears.

The remainder of this introduction to the replication tables describes
how the Performance Schema populates them and which fields from
'SHOW SLAVE STATUS' are not represented in the
tables.

*Replication Table Life Cycle*

The Performance Schema populates the replication tables as follows:

   * Prior to execution of 'CHANGE MASTER TO',
     the tables are empty.

   * After 'CHANGE MASTER TO', the configuration
     parameters can be seen in the tables.  At this time, there are no
     active slave threads, so the 'THREAD_ID' columns are 'NULL' and the
     'SERVICE_STATE' columns have a value of 'OFF'.

   * After 'START SLAVE', non-'NULL' 'THREAD_ID'
     values can be seen.  Threads that are idle or active have a
     'SERVICE_STATE' value of 'ON'.  The thread that connects to the
     master server has a value of 'CONNECTING' while it establishes the
     connection, and 'ON' thereafter as long as the connection lasts.

   * After 'STOP SLAVE', the 'THREAD_ID' columns
     become 'NULL' and the 'SERVICE_STATE' columns for threads that no
     longer exist have a value of 'OFF'.

   * The tables are preserved after 'STOP SLAVE' or
     threads dying due to an error.

   * The 'replication_applier_status_by_worker'
     table is nonempty only
     when the slave is operating in multi-threaded mode.  That is, if
     the 'slave_parallel_workers' system variable is greater than 0,
     this table is populated when 'START SLAVE' is
     executed, and the number of rows shows the number of workers.

*SHOW SLAVE STATUS Information Not In the Replication Tables*

The information in the Performance Schema replication tables differs
somewhat from the information available from 'SHOW SLAVE STATUS'
because the tables are oriented toward use of global
transaction identifiers (GTIDs), not file names and positions, and they
represent server UUID values, not server ID values.  Due to these
differences, several 'SHOW SLAVE STATUS'.
columns are not preserved in the Performance Schema replication tables,
or are represented a different way:

   * The following fields refer to file names and positions and are not
     preserved:

          Master_Log_File
          Read_Master_Log_Pos
          Relay_Log_File
          Relay_Log_Pos
          Relay_Master_Log_File
          Exec_Master_Log_Pos
          Until_Condition
          Until_Log_File
          Until_Log_Pos

   * The 'Master_Info_File' field is not preserved.  It refers to the
     'master.info' file, which has been superseded by crash-safe slave
     tables.

   * The following fields are based on 'server_id', not 'server_uuid',
     and are not preserved:

          Master_Server_Id
          Replicate_Ignore_Server_Ids

   * The 'Skip_Counter' field is based on event counts, not GTIDs, and
     is not preserved.

   * These error fields are aliases for 'Last_SQL_Errno' and
     'Last_SQL_Error', so they are not preserved:

          Last_Errno
          Last_Error

     In the Performance Schema, this error information is available in
     the 'LAST_ERROR_NUMBER' and 'LAST_ERROR_MESSAGE' columns of the
     'replication_applier_status_by_coordinator'
     table (and
     'replication_applier_status_by_worker'
     if the slave is
     multi-threaded).  Those tables provide more specific per-thread
     error information than is available from 'Last_Errno' and
     'Last_Error'.

   * Fields that provide information about command-line filtering
     options is not preserved:

          Replicate_Do_DB
          Replicate_Ignore_DB
          Replicate_Do_Table
          Replicate_Ignore_Table
          Replicate_Wild_Do_Table
          Replicate_Wild_Ignore_Table

   * The 'Slave_IO_State' and 'Slave_SQL_Running_State' fields are not
     preserved.  If needed, these values can be obtained from the
     process list by using the 'THREAD_ID' column of the appropriate
     replication table and joining it with the 'ID' column in the
     'INFORMATION_SCHEMA' 'PROCESSLIST' table
     to select the 'STATE' column of the latter table.

   * The 'Executed_Gtid_Set' field can show a large set with a great
     deal of text.  Instead, the Performance Schema tables show GTIDs of
     transactions that are currently being applied by the slave.
     Alternatively, the set of executed GTIDs can be obtained from the
     value of the 'gtid_executed' system variable.

   * The 'Seconds_Behind_Master' and 'Relay_Log_Space' fields are in
     to-be-decided status and are not preserved.

*Status Variables Moved to Replication Tables*

As of MySQL version 5.7.5, the following status variables (previously
monitored using 'SHOW STATUS') were moved to the
Perfomance Schema replication tables:

   * 'Slave_retried_transactions'

   * 'Slave_last_heartbeat'

   * 'Slave_received_heartbeats'

   * 'Slave_heartbeat_period'

   * 'Slave_running'

These status variables are now only relevant when a single replication
channel is being used because they _only_ report the status of the
default replication channel.  When multiple replication channels exist,
use the Performance Schema replication tables described in this section,
which report these variables for each existing replication channel.

*Replication Channels*

The first column of the replication Performance Schema tables is
'CHANNEL_NAME'.  This enables the tables to be viewed per replication
channel.  In a non-multisource replication setup there is a single
default replication channel.  When you are using multiple replication
channels on a slave, you can filter the tables per replication channel
to monitor a specific replication channel.  See
replication-channels and replication-multi-source-monitoring
for more information.

25.11.11.1 The replication_connection_configuration Table
.........................................................

This table shows the configuration parameters used by the slave server
for connecting to the master server.  Parameters stored in the table can
be changed at runtime with the 'CHANGE MASTER TO'
statement, as indicated in the column descriptions.

Compared to the 'replication_connection_status'
table, see
'replication_connection_configuration'
changes less frequently.  It
contains values that define how the slave connects to the master and
that remain constant during the connection, whereas
'replication_connection_status'.
contains values that change during the connection.

The 'replication_connection_configuration'
table has these columns:

   * 'CHANNEL_NAME'

     The replication channel which this row is displaying.  There is
     always a default replication channel, and more replication channels
     can be added.  See replication-channels for more
     information.

   * 'HOST'

     The master host that the slave is connected to.  ('CHANGE MASTER
     TO' option: 'MASTER_HOST')

   * 'PORT'

     The port used to connect to the master.  ('CHANGE MASTER TO'
     option: 'MASTER_PORT')

   * 'USER'

     The user name of the account used to connect to the master.
     ('CHANGE MASTER TO' option: 'MASTER_USER')

   * 'NETWORK_INTERFACE'

     The network interface that the slave is bound to, if any.  ('CHANGE
     MASTER TO' option: 'MASTER_BIND')

   * 'AUTO_POSITION'

     1 if autopositioning is in use; otherwise 0.  ('CHANGE MASTER TO'
     option: 'MASTER_AUTO_POSITION')

   * 'SSL_ALLOWED', 'SSL_CA_FILE', 'SSL_CA_PATH', 'SSL_CERTIFICATE',
     'SSL_CIPHER', 'SSL_KEY', 'SSL_VERIFY_SERVER_CERTIFICATE',
     'SSL_CRL_FILE', 'SSL_CRL_PATH'

     These columns show the SSL parameters used by the slave to connect
     to the master, if any.

     'SSL_ALLOWED' has these values:

        * 'Yes' if an SSL connection to the master is permitted

        * 'No' if an SSL connection to the master is not permitted

        * 'Ignored' if an SSL connection is permitted but the slave
          server does not have SSL support enabled

     'CHANGE MASTER TO' options for the other SSL columns:
     'MASTER_SSL_CA', 'MASTER_SSL_CAPATH', 'MASTER_SSL_CERT',
     'MASTER_SSL_CIPHER', 'MASTER_SSL_CRL', 'MASTER_SSL_CRLPATH',
     'MASTER_SSL_KEY', 'MASTER_SSL_VERIFY_SERVER_CERT'.

   * 'CONNECTION_RETRY_INTERVAL'

     The number of seconds between connect retries.  ('CHANGE MASTER TO'
     option: 'MASTER_CONNECT_RETRY')

   * 'CONNECTION_RETRY_COUNT'

     The number of times the slave can attempt to reconnect to the
     master in the event of a lost connection.  ('CHANGE MASTER TO'
     option: 'MASTER_RETRY_COUNT')

   * 'HEARTBEAT_INTERVAL'

     The replication heartbeat interval on a slave, measured in seconds.

   * 'TLS_VERSION'

     The TLS version used on the master.  For TLS version information,
     see encrypted-connection-protocols-ciphers.  This column
     was added in MySQL 5.7.10.

'TRUNCATE TABLE' is not permitted for the
'replication_connection_configuration'
table.

The following table shows the correspondence between
'replication_connection_configuration'
columns and 'SHOW SLAVE STATUS'
columns.

'replication_connection_configuration'      'SHOW SLAVE STATUS' Column
Column

'HOST'                                      'Master_Host'

'PORT'                                      'Master_Port'

'USER'                                      'Master_User'

'NETWORK_INTERFACE'                         'Master_Bind'

'AUTO_POSITION'                             'Auto_Position'

'SSL_ALLOWED'                               'Master_SSL_Allowed'

'SSL_CA_FILE'                               'Master_SSL_CA_File'

'SSL_CA_PATH'                               'Master_SSL_CA_Path'

'SSL_CERTIFICATE'                           'Master_SSL_Cert'

'SSL_CIPHER'                                'Master_SSL_Cipher'

'SSL_KEY'                                   'Master_SSL_Key'

'SSL_VERIFY_SERVER_CERTIFICATE'             'Master_SSL_Verify_Server_Cert'

'SSL_CRL_FILE'                              'Master_SSL_Crl'

'SSL_CRL_PATH'                              'Master_SSL_Crlpath'

'CONNECTION_RETRY_INTERVAL'                 'Connect_Retry'

'CONNECTION_RETRY_COUNT'                    'Master_Retry_Count'

25.11.11.2 The replication_connection_status Table
..................................................

This table shows the current status of the I/O thread that handles the
slave server connection to the master server.

Compared to the 'replication_connection_configuration'
table, see
'replication_connection_status'.
changes more frequently.  It contains values that change during the
connection, whereas 'replication_connection_configuration'
contains values which define
how the slave connects to the master and that remain constant during the
connection.

The 'replication_connection_status'
table has these columns:

   * 'CHANNEL_NAME'

     The replication channel which this row is displaying.  There is
     always a default replication channel, and more replication channels
     can be added.  See replication-channels for more
     information.

   * 'GROUP_NAME'

     If this server is a member of a group, shows the name of the group
     the server belongs to.

   * 'SOURCE_UUID'

     The 'server_uuid' value from the master.

   * 'THREAD_ID'

     The I/O thread ID.

   * 'SERVICE_STATE'

     'ON' (thread exists and is active or idle), 'OFF' (thread no longer
     exists), or 'CONNECTING' (thread exists and is connecting to the
     master).

   * 'RECEIVED_TRANSACTION_SET'

     The set of global transaction IDs (GTIDs) corresponding to all
     transactions received by this slave.  Empty if GTIDs are not in
     use.  See replication-gtids-concepts-gtid-sets for more
     information.

   * 'LAST_ERROR_NUMBER', 'LAST_ERROR_MESSAGE'

     The error number and error message of the most recent error that
     caused the I/O thread to stop.  An error number of 0 and message of
     the empty string mean 'no error.' If the 'LAST_ERROR_MESSAGE' value
     is not empty, the error values also appear in the slave's error
     log.

     Issuing 'RESET MASTER' or 'RESET SLAVE'
     resets the values shown in these columns.

   * 'LAST_ERROR_TIMESTAMP'

     A timestamp in 'YYMMDD HH:MM:SS' format that shows when the most
     recent I/O error took place.

   * 'LAST_HEARTBEAT_TIMESTAMP'

     A timestamp in 'YYMMDD HH:MM:SS' format that shows when the most
     recent heartbeat signal was received by a replication slave.

   * 'COUNT_RECEIVED_HEARTBEATS'

     The total number of heartbeat signals that a replication slave
     received since the last time it was restarted or reset, or a
     'CHANGE MASTER TO' statement was issued.

'TRUNCATE TABLE' is not permitted for the
'replication_connection_status'.
table.

The following table shows the correspondence between
'replication_connection_status'.
columns and 'SHOW SLAVE STATUS' columns.

'replication_connection_status' Column      'SHOW SLAVE STATUS' Column

'SOURCE_UUID'                               'Master_UUID'

'THREAD_ID'                                 None

'SERVICE_STATE'                             'Slave_IO_Running'

'RECEIVED_TRANSACTION_SET'                  'Retrieved_Gtid_Set'

'LAST_ERROR_NUMBER'                         'Last_IO_Errno'

'LAST_ERROR_MESSAGE'                        'Last_IO_Error'

'LAST_ERROR_TIMESTAMP'                      'Last_IO_Error_Timestamp'

25.11.11.3 The replication_applier_configuration Table
......................................................

This table shows the configuration parameters that affect transactions
applied by the slave server.  Parameters stored in the table can be
changed at runtime with the 'CHANGE MASTER TO'.
statement, as indicated in the column descriptions.

The 'replication_applier_configuration'
table has these columns:

   * 'CHANNEL_NAME'

     The replication channel which this row is displaying.  There is
     always a default replication channel, and more replication channels
     can be added.  See replication-channels for more
     information.

   * 'DESIRED_DELAY'

     The number of seconds that the slave must lag the master.  ('CHANGE
     MASTER TO' option: 'MASTER_DELAY')

'TRUNCATE TABLE' is not permitted for the
'replication_applier_configuration'
table.

The following table shows the correspondence between
'replication_applier_configuration '
columns and 'SHOW SLAVE STATUS'
columns.

'replication_applier_configuration'         'SHOW SLAVE STATUS' Column
Column

'DESIRED_DELAY'                             'SQL_Delay'

25.11.11.4 The replication_applier_status Table
...............................................

This table shows the current general transaction execution status on the
slave server.  The table provides information about general aspects of
transaction applier status that are not specific to any thread involved.
Thread-specific status information is available in the
'replication_applier_status_by_coordinator'
table (and
'replication_applier_status_by_worker'
if the slave is
multi-threaded).

The 'replication_applier_status'
table has these columns:

   * 'CHANNEL_NAME'

     The replication channel which this row is displaying.  There is
     always a default replication channel, and more replication channels
     can be added.  See replication-channels for more
     information.

   * 'SERVICE_STATE'

     Shows 'ON' when the replication channel's applier threads are
     active or idle, 'OFF' means that the applier threads are not
     active.

   * 'REMAINING_DELAY'

     If the slave is waiting for 'DESIRED_DELAY' seconds to pass since
     the master applied an event, this field contains the number of
     delay seconds remaining.  At other times, this field is 'NULL'.
     (The 'DESIRED_DELAY' value is stored in the
     'replication_applier_configuration'
     table.)

   * 'COUNT_TRANSACTIONS_RETRIES'

     Shows the number of retries that were made because the slave SQL
     thread failed to apply a transaction.

'TRUNCATE TABLE' is not permitted for the
'replication_applier_status' table.

The following table shows the correspondence between
'replication_applier_status' columns
and 'SHOW SLAVE STATUS' columns.

'replication_applier_status' Column         'SHOW SLAVE STATUS' Column

'SERVICE_STATE'                             None

'REMAINING_DELAY'                           'SQL_Remaining_Delay'

25.11.11.5 The replication_applier_status_by_coordinator Table
..............................................................

For a multi-threaded slave, the slave uses multiple worker threads and a
coordinator thread to manage them, and this table shows the status of
the coordinator thread.  For a single-threaded slave, this table is
empty.  For a multi-threaded slave, the
'replication_applier_status_by_worker'
table shows the status of
the worker threads.

The 'replication_applier_status_by_coordinator'
table has these
columns:

   * 'CHANNEL_NAME'

     The replication channel which this row is displaying.  There is
     always a default replication channel, and more replication channels
     can be added.  See replication-channels for more
     information.

   * 'THREAD_ID'

     The SQL/coordinator thread ID.

   * 'SERVICE_STATE'

     'ON' (thread exists and is active or idle) or 'OFF' (thread no
     longer exists).

   * 'LAST_ERROR_NUMBER', 'LAST_ERROR_MESSAGE'

     The error number and error message of the most recent error that
     caused the SQL/coordinator thread to stop.  An error number of 0
     and message which is an empty string means 'no error'.  If the
     'LAST_ERROR_MESSAGE' value is not empty, the error values also
     appear in the slave's error log.

     Issuing 'RESET MASTER' or 'RESET SLAVE'
     resets the values shown in these columns.

     All error codes and messages displayed in the 'LAST_ERROR_NUMBER'
     and 'LAST_ERROR_MESSAGE' columns correspond to error values listed
     in error-messages-server.

   * 'LAST_ERROR_TIMESTAMP'

     A timestamp in 'YYMMDD HH:MM:SS' format that shows when the most
     recent SQL/coordinator error occurred.

'TRUNCATE TABLE' is not permitted for the
'replication_applier_status_by_coordinator'
table.

The following table shows the correspondence between
'replication_applier_status_by_coordinator'
columns and 'SHOW SLAVE STATUS'
columns.

'replication_applier_status_by_coordinator' 'SHOW SLAVE STATUS' Column
Column

'THREAD_ID'                                 None

'SERVICE_STATE'                             'Slave_SQL_Running'

'LAST_ERROR_NUMBER'                         'Last_SQL_Errno'

'LAST_ERROR_MESSAGE'                        'Last_SQL_Error'

'LAST_ERROR_TIMESTAMP'                      'Last_SQL_Error_Timestamp'

25.11.11.6 The replication_applier_status_by_worker Table
.........................................................

If the slave is not multi-threaded, this table shows the status of the
applier thread.  Otherwise, the slave uses multiple worker threads and a
coordinator thread to manage them, and this table shows the status of
the worker threads.  For a multi-threaded slave, the
'replication_applier_status_by_coordinator'
table shows the status
of the coordinator thread.

The 'replication_applier_status_by_worker' table has these columns:

   * 'CHANNEL_NAME'

     The replication channel which this row is displaying.  There is
     always a default replication channel, and more replication channels
     can be added.  See replication-channels for more
     information.

   * 'WORKER_ID'

     The worker identifier (same value as the 'id' column in the
     'mysql.slave_worker_info' table).  After 'STOP SLAVE',
     the 'THREAD_ID' column becomes 'NULL', but the
     'WORKER_ID' value is preserved.

   * 'THREAD_ID'

     The worker thread identifier.

   * 'SERVICE_STATE'

     'ON' (thread exists and is active or idle) or 'OFF' (thread no
     longer exists).

   * 'LAST_SEEN_TRANSACTION'

     The transaction that the worker has last seen.  The worker has not
     necessarily applied this transaction because it could still be in
     the process of doing so.

     If the 'gtid_mode' system variable value is 'OFF', this column is
     'ANONYMOUS', indicating that transactions do not have global
     transaction identifiers (GTIDs) and are identified by file and
     position only.

     If 'gtid_mode' is 'ON', the column value is defined as follows:

        * If no transaction has executed, the column is empty.

        * When a transaction has executed, the column is set from
          'gtid_next' as soon as 'gtid_next' is set.  From this moment,
          the column always shows a GTID.

        * The GTID is preserved until the next transaction is executed.
          If an error occurs, the column value is the GTID of the
          transaction being executed by the worker when the error
          occurred.

        * When the next GTID log event is picked up by this worker
          thread, this column is updated from 'gtid_next' soon after
          'gtid_next' is set.

   * 'LAST_ERROR_NUMBER', 'LAST_ERROR_MESSAGE'

     The error number and error message of the most recent error that
     caused the worker thread to stop.  An error number of 0 and message
     of the empty string mean 'no error'.  If the 'LAST_ERROR_MESSAGE'
     value is not empty, the error values also appear in the slave's
     error log.

     Issuing 'RESET MASTER' or 'RESET SLAVE'
     resets the values shown in these columns.

     All error codes and messages displayed in the 'LAST_ERROR_NUMBER'
     and 'LAST_ERROR_MESSAGE' columns correspond to error values listed
     in error-messages-server.

   * 'LAST_ERROR_TIMESTAMP'

     A timestamp in 'YYMMDD HH:MM:SS' format that shows when the most
     recent worker error occurred.

'TRUNCATE TABLE' is not permitted for the
'replication_applier_status_by_worker'
table.

The following table shows the correspondence between
'replication_applier_status_by_worker' columns and 'SHOW SLAVE STATUS'
columns.

'replication_applier_status_by_worker'      'SHOW SLAVE STATUS' Column
Column

'WORKER_ID'                                 None

'THREAD_ID'                                 None

'SERVICE_STATE'                             None

'LAST_SEEN_TRANSACTION'                     None

'LAST_ERROR_NUMBER'                         'Last_SQL_Errno'

'LAST_ERROR_MESSAGE'                        'Last_SQL_Error'

'LAST_ERROR_TIMESTAMP'                      'Last_SQL_Error_Timestamp'

25.11.11.7 The replication_group_members Table
..............................................

This table shows network and status information for replication group
members.  The network addresses shown are the addresses used to connect
clients to the group, and should not be confused with the member's
internal group communication address specified by
'group_replication_local_address'.

The 'replication_group_members' table has the following columns:

   * 'CHANNEL_NAME'

     Name of the Group Replication channel.

   * 'MEMBER_ID'

     Identifier for this member; the same as the server UUID.

   * 'MEMBER_HOST'

     Network address of this member (host name or IP address).
     Retrieved from the member's 'hostname' variable.

   * 'MEMBER_PORT'

     Port on which the server is listening.  Retrieved from the member's
     'port' variable.

   * 'MEMBER_STATE'

     Current state of this member; can be any one of the following:

        * 'OFFLINE': The Group Replication plugin is installed but has
          not been started.

        * 'RECOVERING': The server has joined a group from which it is
          retrieving data.

        * 'ONLINE': The member is in a fully functioning state.

'TRUNCATE TABLE' is not permitted for the
'replication_group_members' table.

25.11.11.8 The replication_group_member_stats Table
...................................................

This table shows statistical information for MySQL Group Replication
members.  It is populated only when Group Replication is running.

The 'replication_group_member_stats' table has the following columns:

   * 'CHANNEL_NAME'

     Name of the Group Replication channel.

   * 'VIEW_ID'

     Current view identifier for this group.

   * 'MEMBER_ID'

     Identifier for this member; same as the server UUID.

   * 'COUNT_TRANSACTIONS_IN_QUEUE'

     Number of transactions pending certification.

   * 'COUNT_TRANSACTIONS_CHECKED'

     Number of transactions already certified by this member.

   * 'COUNT_CONFLICTS_DETECTED'

     Number of transactions that were negatively certified.

   * 'COUNT_TRANSACTIONS_ROWS_VALIDATING'

     Number of transaction rows available which could be used for
     certification, but which have not been garbage collected.

   * 'TRANSACTIONS_COMMITTED_ALL_MEMBERS'

     Set of stable group transactions.

   * 'LAST_CONFLICT_FREE_TRANSACTION'

     Latest transaction certified without conflicts.

'TRUNCATE TABLE' is not permitted for the
'replication_group_member_stats'.
table.

25.11.12 Performance Schema Lock Tables
---------------------------------------

The Performance Schema exposes lock information through these tables:

   * 'metadata_locks'.: Metadata locks held
     and requested

   * 'table_handles'.: Table locks held and
     requested

The following sections describe these tables in more detail.

25.11.12.1 The metadata_locks Table
...................................

The Performance Schema exposes metadata lock information through the
'metadata_locks' table:

   * Locks that have been granted (shows which sessions own which
     current metadata locks)

   * Locks that have been requested but not yet granted (shows which
     sessions are waiting for which metadata locks).

   * Lock requests that have been killed by the deadlock detector or
     timed out and are waiting for the requesting session's lock request
     to be discarded

This information enables you to understand metadata lock dependencies
between sessions.  You can see not only which lock a session is waiting
for, but which session currently holds that lock.

The 'metadata_locks' table is read only and
cannot be updated.  It is autosized by default; to configure the table
size, set the 'performance_schema_max_metadata_locks' system variable at
server startup.

Metadata lock instrumentation uses the 'wait/lock/metadata/sql/mdl'
instrument, which is disabled by default.

To control metadata lock instrumention state at server startup, use
lines like these in your 'my.cnf' file:

   * Enable:

          [mysqld]
          performance-schema-instrument='wait/lock/metadata/sql/mdl=ON'

   * Disable:

          [mysqld]
          performance-schema-instrument='wait/lock/metadata/sql/mdl=OFF'

To control metadata lock instrumention state at runtime, update the
'setup_instruments' table:

   * Enable:

          UPDATE setup_instruments SET ENABLED = 'YES', TIMED = 'YES'
          WHERE NAME = 'wait/lock/metadata/sql/mdl';

   * Disable:

          UPDATE setup_instruments SET ENABLED = 'NO', TIMED = 'NO'
          WHERE NAME = 'wait/lock/metadata/sql/mdl';

The Performance Schema maintains 'metadata_locks'
table content as follows, using the 'LOCK_STATUS'
column to indicate the status of each lock:

   * When a metadata lock is requested and obtained immediately, a row
     with a status of 'GRANTED' is inserted.

   * When a metadata lock is requested and not obtained immediately, a
     row with a status of 'PENDING' is inserted.

   * When a metadata lock previously requested is granted, its row
     status is updated to 'GRANTED'.

   * When a metadata lock is released, its row is deleted.

   * When a pending lock request is canceled by the deadlock detector to
     break a deadlock ('ER_LOCK_DEADLOCK'), its row status is updated
     from 'PENDING' to 'VICTIM'.

   * When a pending lock request times out ('ER_LOCK_WAIT_TIMEOUT'), its
     row status is updated from 'PENDING' to 'TIMEOUT'.

   * When granted lock or pending lock request is killed, its row status
     is updated from 'GRANTED' or 'PENDING' to 'KILLED'.

   * The 'VICTIM', 'TIMEOUT', and 'KILLED' status values are brief and
     signify that the lock row is about to be deleted.

   * The 'PRE_ACQUIRE_NOTIFY' and 'POST_RELEASE_NOTIFY' status values
     are brief and signify that the metadata locking subsubsystem is
     notifying interested storage engines while entering lock
     acquisition or leaving lock release operations.  These status
     values were added in MySQL 5.7.11.

The 'metadata_locks' table has these
columns:

   * 'OBJECT_TYPE'

     The type of lock used in the metadata lock subsystem: The value is
     one of 'GLOBAL', 'SCHEMA', 'TABLE', 'FUNCTION', 'PROCEDURE',
     'TRIGGER' (currently unused), 'EVENT', 'COMMIT', 'USER LEVEL LOCK',
     'TABLESPACE', or 'LOCKING SERVICE'.

     A value of 'USER LEVEL LOCK' indicates a lock acquired with
     'GET_LOCK()'.  A value of 'LOCKING SERVICE' indicates a lock
     acquired using the locking service described in
     locking-service.

   * 'OBJECT_SCHEMA'

     The schema that contains the object.

   * 'OBJECT_NAME'

     The name of the instrumented object.

   * 'OBJECT_INSTANCE_BEGIN'

     The address in memory of the instrumented object.

   * 'LOCK_TYPE'

     The lock type from the metadata lock subsystem.  The value is one
     of 'INTENTION_EXCLUSIVE', 'SHARED', 'SHARED_HIGH_PRIO',
     'SHARED_READ', 'SHARED_WRITE', 'SHARED_UPGRADABLE',
     'SHARED_NO_WRITE', 'SHARED_NO_READ_WRITE', or 'EXCLUSIVE'.

   * 'LOCK_DURATION'

     The lock duration from the metadata lock subsystem.  The value is
     one of 'STATEMENT', 'TRANSACTION', or 'EXPLICIT'.  The 'STATEMENT'
     and 'TRANSACTION' values signify locks that are released at
     statement or transaction end, respectively.  The 'EXPLICIT' value
     signifies locks that survive statement or transaction end and are
     released explicitly, such as global locks acquired with 'FLUSH
     TABLES WITH READ LOCK'.

   * 'LOCK_STATUS'

     The lock status from the metadata lock subsystem.  The value is one
     of 'PENDING', 'GRANTED', 'VICTIM', 'TIMEOUT', 'KILLED',
     'PRE_ACQUIRE_NOTIFY', or 'POST_RELEASE_NOTIFY'.  The Performance
     Schema assigns these values as described previously.

   * 'SOURCE'

     The name of the source file containing the instrumented code that
     produced the event and the line number in the file at which the
     instrumentation occurs.  This enables you to check the source to
     determine exactly what code is involved.

   * 'OWNER_THREAD_ID'

     The thread requesting a metadata lock.

   * 'OWNER_EVENT_ID'

     The event requesting a metadata lock.

'TRUNCATE TABLE' is not permitted for the
'metadata_locks' table.

25.11.12.2 The table_handles Table
..................................

The Performance Schema exposes table lock information through the
'table_handles' table to show the table locks
currently in effect for each opened table handle.
'table_handles' reports what is recorded by the
table lock instrumentation.  This information shows which table handles
the server has open, how they are locked, and by which sessions.

The 'table_handles' table is read only and
cannot be updated.  It is autosized by default; to configure the table
size, set the 'performance_schema_max_table_handles' system variable at
server startup.

The 'table_handles' table has these columns:

   * 'OBJECT_TYPE'

     The table opened by a table handle.

   * 'OBJECT_SCHEMA'

     The schema that contains the object.

   * 'OBJECT_NAME'

     The name of the instrumented object.

   * 'OBJECT_INSTANCE_BEGIN'

     The table handle address in memory.

   * 'OWNER_THREAD_ID'

     The thread owning the table handle.

   * 'OWNER_EVENT_ID'

     The event which caused the table handle to be opened.

   * 'INTERNAL_LOCK'

     The table lock used at the SQL level.  The value is one of 'READ',
     'READ WITH SHARED LOCKS', 'READ HIGH PRIORITY', 'READ NO INSERT',
     'WRITE ALLOW WRITE', 'WRITE CONCURRENT INSERT', 'WRITE LOW
     PRIORITY', or 'WRITE'.  For information about these lock types, see
     the 'include/thr_lock.h' source file.

   * 'EXTERNAL_LOCK'

     The table lock used at the storage engine level.  The value is one
     of 'READ EXTERNAL' or 'WRITE EXTERNAL'.

'TRUNCATE TABLE' is not permitted for the
'table_handles' table.

25.11.13 Performance Schema System Variable Tables
--------------------------------------------------

*Note*:

The value of the 'show_compatibility_56' system variable affects the
information available from the tables described here.  For details, see
the description of that variable in server-system-variables.

The MySQL server maintains many system variables that indicate how it is
configured (see server-system-variables).  System variable
information is available in these Performance Schema tables:

   * 'global_variables'.:
     Global system
     variables.  An application that wants only global values should use
     this table.

   * 'session_variables'.:
     System variables for
     the current session.  An application that wants all system variable
     values for its own session should use this table.  It includes the
     session variables for its session, as well as the values of global
     variables that have no session counterpart.

   * 'variables_by_thread'.:
     Session system
     variables for each active session.  An application that wants to
     know the session variable values for specific sessions should use
     this table.  It includes session variables only, identified by
     thread ID.

The session variable tables (see 'session_variables',
see 'variables_by_thread')
contain information only for
active sessions, not terminated sessions.

'TRUNCATE TABLE' is not supported for Performance
Schema system variable tables.

The 'global_variables'.
and 'session_variables'
tables have these columns:

   * 'VARIABLE_NAME'

     The system variable name.

   * 'VARIABLE_VALUE'

     The system variable value.  For 'global_variables',
     this column contains the
     global value.  For 'session_variables',
     this column contains the
     variable value in effect for the current session.

The 'variables_by_thread'
table has these columns:

   * 'THREAD_ID'

     The thread identifier of the session in which the system variable
     is defined.

   * 'VARIABLE_NAME'

     The system variable name.

   * 'VARIABLE_VALUE'

     The session variable value for the session named by the 'THREAD_ID'
     column.

The 'variables_by_thread'
table contains system
variable information only about foreground threads.  If not all threads
are instrumented by the Performance Schema, this table will miss some
rows.  In this case, the 'Performance_schema_thread_instances_lost'
status variable will be greater than zero.

25.11.14 Performance Schema Status Variable Tables
--------------------------------------------------

*Note*:

The value of the 'show_compatibility_56' system variable affects the
information available from the tables described here.  For details, see
the description of that variable in server-system-variables.

The MySQL server maintains many status variables that provide
information about its operation (see server-status-variables).
Status variable information is available in these Performance Schema
tables:

   * 'global_status'.:
     Global status variables.  An application that wants only global
     values should use this table.

   * 'session_status'.:
     Status variables for the current session.  An application that
     wants all status variable values for its own session should use
     this table.  It includes the session variables for its session, as
     well as the values of global variables that have no session
     counterpart.

   * 'status_by_thread'.:
     Session status
     variables for each active session.  An application that wants to
     know the session variable values for specific sessions should use
     this table.  It includes session variables only, identified by
     thread ID.

There are also summary tables that provide status variable information
aggregated by account, host name, and user name.  See
performance-schema-status-variable-summary-tables.

The session variable tables (see 'session_status',
see 'status_by_thread')
contain information only for
active sessions, not terminated sessions.

The Performance Schema collects statistics for global status variables
only for threads for which the 'INSTRUMENTED' value is 'YES' in the
'threads' table.  Statistics for session status
variables are always collected, regardless of the 'INSTRUMENTED' value.

The Performance Schema does not collect statistics for 'Com_XXX' status
variables in the status variable tables.  To obtain global and
per-session statement execution counts, use the
'events_statements_summary_global_by_event_name'
and
'events_statements_summary_by_thread_by_event_name'
tables, respectively.  For example:

     SELECT EVENT_NAME, COUNT_STAR
     FROM events_statements_summary_global_by_event_name
     WHERE EVENT_NAME LIKE 'statement/sql/%';

The 'global_status'.
and 'session_status'.
tables have these columns:

   * 'VARIABLE_NAME'

     The status variable name.

   * 'VARIABLE_VALUE'

     The status variable value.  For 'global_status',
     this column contains the
     global value.  For 'session_status',
     this column contains the
     variable value for the current session.

The 'status_by_thread'.
table contains the status of each active thread.  It has these columns:

   * 'THREAD_ID'

     The thread identifier of the session in which the status variable
     is defined.

   * 'VARIABLE_NAME'

     The status variable name.

   * 'VARIABLE_VALUE'

     The session variable value for the session named by the 'THREAD_ID'
     column.

The 'status_by_thread'.
table contains status variable information only about foreground
threads.  If the 'performance_schema_max_thread_instances' system
variable is not autoscaled (set to −1) and the maximum permitted
number of instrumented thread objects is not greater than the number of
background threads, the table will be empty.

The Performance Schema supports 'TRUNCATE TABLE'.
for status variable tables as follows:

   * 'global_status'.:
     Resets thread, account, host, and user status.  Resets global
     status variables except those that the server never resets.

   * 'session_status'.:
     Not supported.

   * 'status_by_thread'.:
     Aggregates status for
     all threads to the global status and account status, then resets
     thread status.  If account statistics are not collected, the
     session status is added to host and user status, if host and user
     status are collected.

     Account, host, and user statistics are not collected if the
     'performance_schema_accounts_size',
     'performance_schema_hosts_size', and
     'performance_schema_users_size' system variables, respectively, are
     set to 0.

'FLUSH STATUS' adds the session status from all active sessions to the
global status variables, resets the status of all active sessions, and
resets account, host, and user status values aggregated from
disconnected sessions.

25.11.15 Performance Schema Summary Tables
------------------------------------------

Summary tables provide aggregated information for terminated events over
time.  The tables in this group summarize event data in different ways.

*Wait Event Summaries*

   * 'events_waits_summary_by_account_by_event_name'.:
     Wait events per account and event name

   * 'events_waits_summary_by_host_by_event_name'.:
     Wait events per host name and event name

   * 'events_waits_summary_by_instance'.:
     Wait events per instance

   * 'events_waits_summary_by_thread_by_event_name'.:
     Wait events per thread and event name

   * 'events_waits_summary_by_user_by_event_name'.:
     Wait events per user name and event name

   * 'events_waits_summary_global_by_event_name'.:
     Wait events per event name

*Stage Summaries*

   * 'events_stages_summary_by_account_by_event_name'.:
     Stage events per account and event name

   * 'events_stages_summary_by_host_by_event_name'.:
     Stage events per host name and event name

   * 'events_stages_summary_by_thread_by_event_name'.:
     Stage waits per thread and event name

   * 'events_stages_summary_by_user_by_event_name'.:
     Stage events per user name and event name

   * 'events_stages_summary_global_by_event_name'.:
     Stage waits per event name

*Statement Summaries*

   * 'events_statements_summary_by_account_by_event_name'.:
     Statement events per account and event
     name

   * 'events_statements_summary_by_digest'.:
     Statement events per schema and digest
     value

   * 'events_statements_summary_by_host_by_event_name'.:
     Statement events per host name and event
     name

   * 'events_statements_summary_by_program'.:
     Statement events per stored program
     (stored procedures and functions, triggers, and events)

   * 'events_statements_summary_by_thread_by_event_name'.:
     Statement events per thread and event
     name

   * 'events_statements_summary_by_user_by_event_name'.:
     Statement events per user name and event
     name

   * 'events_statements_summary_global_by_event_name'.:
     Statement events per event name

   * 'prepared_statements_instances'.:
     Prepared statement instances
     and statistics

*Transaction Summaries*

   * 'events_transactions_summary_by_account_by_event_name'.:
     Transaction events per account and
     event name

   * 'events_transactions_summary_by_host_by_event_name'.:
     Transaction events per host name and
     event name

   * 'events_transactions_summary_by_thread_by_event_name'.:
     Transaction events per thread and
     event name

   * 'events_transactions_summary_by_user_by_event_name'.:
     Transaction events per user name and
     event name

   * 'events_transactions_summary_global_by_event_name'.:
     Transaction events per event name

*Object Wait Summaries*

   * 'objects_summary_global_by_type'.:
     Object summaries

*File I/O Summaries*

   * 'file_summary_by_event_name'.: File
     events per event name

   * 'file_summary_by_instance'.: File events
     per file instance

*Table I/O and Lock Wait Summaries*

   * 'table_io_waits_summary_by_index_usage'.:
     Table I/O waits per
     index

   * 'table_io_waits_summary_by_table'.:
     Table I/O waits per table

   * 'table_lock_waits_summary_by_table'.:
     Table lock waits per
     table

*Socket Summaries*

   * 'socket_summary_by_instance'.: Socket
     waits and I/O per instance

   * 'socket_summary_by_event_name'.:
     Socket waits and I/O per event name

*Memory Summaries*

   * 'memory_summary_by_account_by_event_name'.:
     Memory operations per account and event
     name

   * 'memory_summary_by_host_by_event_name'.:
     Memory operations per host and event name

   * 'memory_summary_by_thread_by_event_name'.:
     Memory operations per thread and event name

   * 'memory_summary_by_user_by_event_name'.:
     Memory operations per user and event name

   * 'memory_summary_global_by_event_name'.:
     Memory operations globally per event name

*Status Variable Summaries*

   * 'status_by_account'.:
     Status
     variables per account

   * 'status_by_host'.:
     Status
     variables per host name

   * 'status_by_user'.:
     Status
     variables per user name

Each summary table has grouping columns that determine how to group the
data to be aggregated, and summary columns that contain the aggregated
values.  Tables that summarize events in similar ways often have similar
sets of summary columns and differ only in the grouping columns used to
determine how events are aggregated.

Summary tables can be truncated with 'TRUNCATE TABLE'.
Generally, the effect is to reset the summary columns
to 0 or 'NULL', not to remove rows.  This enables you to clear collected
values and restart aggregation.  That might be useful, for example,
after you have made a runtime configuration change.  Exceptions to this
truncation behavior are noted in individual summary table sections.

25.11.15.1 Wait Event Summary Tables
....................................

The Performance Schema maintains tables for collecting current and
recent wait events, and aggregates that information in summary tables.
performance-schema-wait-tables describes the events on which
wait summaries are based.  See that discussion for information about the
content of wait events, the current and recent wait event tables, and
how to control wait event collection, which is disabled by default.

Example wait event summary information:

     mysql> SELECT * FROM events_waits_summary_global_by_event_name\G
     ...
     *************************** 6. row ***************************
         EVENT_NAME: wait/synch/mutex/sql/BINARY_LOG::LOCK_index
         COUNT_STAR: 8
     SUM_TIMER_WAIT: 2119302
     MIN_TIMER_WAIT: 196092
     AVG_TIMER_WAIT: 264912
     MAX_TIMER_WAIT: 569421
     ...
     *************************** 9. row ***************************
         EVENT_NAME: wait/synch/mutex/sql/hash_filo::lock
         COUNT_STAR: 69
     SUM_TIMER_WAIT: 16848828
     MIN_TIMER_WAIT: 0
     AVG_TIMER_WAIT: 244185
     MAX_TIMER_WAIT: 735345
     ...

Each wait event summary table has one or more grouping columns to
indicate how the table aggregates events.  Event names refer to names of
event instruments in the 'setup_instruments'
table:

   * 'events_waits_summary_by_account_by_event_name'
     has 'EVENT_NAME', 'USER', and 'HOST' columns.
     Each row summarizes events for a given account (user and host
     combination) and event name.

   * 'events_waits_summary_by_host_by_event_name'
     has 'EVENT_NAME' and 'HOST' columns.  Each
     row summarizes events for a given host and event name.

   * 'events_waits_summary_by_instance' has
     'EVENT_NAME' and 'OBJECT_INSTANCE_BEGIN' columns.  Each row
     summarizes events for a given event name and object.  If an
     instrument is used to create multiple instances, each instance has
     a unique 'OBJECT_INSTANCE_BEGIN' value and is summarized separately
     in this table.

   * 'events_waits_summary_by_thread_by_event_name'
     has 'THREAD_ID' and 'EVENT_NAME' columns.
     Each row summarizes events for a given thread and event name.

   * 'events_waits_summary_by_user_by_event_name'
     has 'EVENT_NAME' and 'USER' columns.  Each
     row summarizes events for a given user and event name.

   * 'events_waits_summary_global_by_event_name'
     has an 'EVENT_NAME' column.  Each row
     summarizes events for a given event name.  An instrument might be
     used to create multiple instances of the instrumented object.  For
     example, if there is an instrument for a mutex that is created for
     each connection, there are as many instances as there are
     connections.  The summary row for the instrument summarizes over
     all these instances.

Each wait event summary table has these summary columns containing
aggregated values:

   * 'COUNT_STAR'

     The number of summarized events.  This value includes all events,
     whether timed or nontimed.

   * 'SUM_TIMER_WAIT'

     The total wait time of the summarized timed events.  This value is
     calculated only for timed events because nontimed events have a
     wait time of 'NULL'.  The same is true for the other
     'XXX_TIMER_WAIT' values.

   * 'MIN_TIMER_WAIT'

     The minimum wait time of the summarized timed events.

   * 'AVG_TIMER_WAIT'

     The average wait time of the summarized timed events.

   * 'MAX_TIMER_WAIT'

     The maximum wait time of the summarized timed events.

'TRUNCATE TABLE' is permitted for wait summary
tables.  It has these effects:

   * For summary tables not aggregated by account, host, or user,
     truncation resets the summary columns to zero rather than removing
     rows.

   * For summary tables aggregated by account, host, or user, truncation
     removes rows for accounts, hosts, or users with no connections, and
     resets the summary columns to zero for the remaining rows.

In addition, each wait summary table that is aggregated by account,
host, user, or thread is implicitly truncated by truncation of the
connection table on which it depends, or truncation of
'events_waits_summary_global_by_event_name'.  For
details, see performance-schema-connection-tables.

25.11.15.2 Stage Summary Tables
...............................

The Performance Schema maintains tables for collecting current and
recent stage events, and aggregates that information in summary tables.
performance-schema-stage-tables describes the events on which
stage summaries are based.  See that discussion for information about
the content of stage events, the current and recent stage event tables,
and how to control stage event collection, which is disabled by default.

Example stage event summary information:

     mysql> SELECT * FROM events_stages_summary_global_by_event_name\G
     ...
     *************************** 5. row ***************************
         EVENT_NAME: stage/sql/checking permissions
         COUNT_STAR: 57
     SUM_TIMER_WAIT: 26501888880
     MIN_TIMER_WAIT: 7317456
     AVG_TIMER_WAIT: 464945295
     MAX_TIMER_WAIT: 12858936792
     ...
     *************************** 9. row ***************************
         EVENT_NAME: stage/sql/closing tables
         COUNT_STAR: 37
     SUM_TIMER_WAIT: 662606568
     MIN_TIMER_WAIT: 1593864
     AVG_TIMER_WAIT: 17907891
     MAX_TIMER_WAIT: 437977248
     ...

Each stage summary table has one or more grouping columns to indicate
how the table aggregates events.  Event names refer to names of event
instruments in the 'setup_instruments'.
table:

   * 'events_stages_summary_by_account_by_event_name'
     has 'EVENT_NAME', 'USER', and 'HOST' columns.
     Each row summarizes events for a given account (user and host
     combination) and event name.

   * 'events_stages_summary_by_host_by_event_name'
     has 'EVENT_NAME' and 'HOST' columns.  Each
     row summarizes events for a given host and event name.

   * 'events_stages_summary_by_thread_by_event_name'
     has 'THREAD_ID' and 'EVENT_NAME' columns.
     Each row summarizes events for a given thread and event name.

   * 'events_stages_summary_by_user_by_event_name'
     has 'EVENT_NAME' and 'USER' columns.  Each
     row summarizes events for a given user and event name.

   * 'events_stages_summary_global_by_event_name'
     has an 'EVENT_NAME' column.  Each row
     summarizes events for a given event name.

Each stage summary table has these summary columns containing aggregated
values: 'COUNT_STAR', 'SUM_TIMER_WAIT', 'MIN_TIMER_WAIT',
'AVG_TIMER_WAIT', and 'MAX_TIMER_WAIT'.  These columns are analogous to
the columns of the same names in the wait event summary tables (see
wait-summary-tables), except that the stage summary tables
aggregate events from 'events_stages_current'
rather than 'events_waits_current'.

'TRUNCATE TABLE' is permitted for stage summary
tables.  It has these effects:

   * For summary tables not aggregated by account, host, or user,
     truncation resets the summary columns to zero rather than removing
     rows.

   * For summary tables aggregated by account, host, or user, truncation
     removes rows for accounts, hosts, or users with no connections, and
     resets the summary columns to zero for the remaining rows.

In addition, each stage summary table that is aggregated by account,
host, user, or thread is implicitly truncated by truncation of the
connection table on which it depends, or truncation of
'events_stages_summary_global_by_event_name'.  For
details, see performance-schema-connection-tables.

25.11.15.3 Statement Summary Tables
...................................

The Performance Schema maintains tables for collecting current and
recent statement events, and aggregates that information in summary
tables.  performance-schema-statement-tables describes the
events on which statement summaries are based.  See that discussion for
information about the content of statement events, the current and
recent statement event tables, and how to control statement event
collection, which is partially disabled by default.

Example statement event summary information:

     mysql> SELECT * FROM events_statements_summary_global_by_event_name\G
     *************************** 1. row ***************************
                      EVENT_NAME: statement/sql/select
                      COUNT_STAR: 25
                  SUM_TIMER_WAIT: 1535983999000
                  MIN_TIMER_WAIT: 209823000
                  AVG_TIMER_WAIT: 61439359000
                  MAX_TIMER_WAIT: 1363397650000
                   SUM_LOCK_TIME: 20186000000
                      SUM_ERRORS: 0
                    SUM_WARNINGS: 0
               SUM_ROWS_AFFECTED: 0
                   SUM_ROWS_SENT: 388
               SUM_ROWS_EXAMINED: 370
     SUM_CREATED_TMP_DISK_TABLES: 0
          SUM_CREATED_TMP_TABLES: 0
            SUM_SELECT_FULL_JOIN: 0
      SUM_SELECT_FULL_RANGE_JOIN: 0
                SUM_SELECT_RANGE: 0
          SUM_SELECT_RANGE_CHECK: 0
                 SUM_SELECT_SCAN: 6
           SUM_SORT_MERGE_PASSES: 0
                  SUM_SORT_RANGE: 0
                   SUM_SORT_ROWS: 0
                   SUM_SORT_SCAN: 0
               SUM_NO_INDEX_USED: 6
          SUM_NO_GOOD_INDEX_USED: 0
     ...

Each statement summary table has one or more grouping columns to
indicate how the table aggregates events.  Event names refer to names of
event instruments in the 'setup_instruments'
table:

   * 'events_statements_summary_by_account_by_event_name'
     has 'EVENT_NAME', 'USER', and 'HOST'
     columns.  Each row summarizes events for a given account (user and
     host combination) and event name.

   * 'events_statements_summary_by_digest'
     has 'SCHEMA_NAME' and 'DIGEST' columns.
     Each row summarizes events per schema and digest value.  (The
     'DIGEST_TEXT' column contains the corresponding normalized
     statement digest text, but is neither a grouping nor a summary
     column.)

     The maximum number of rows in the table is autosized at server
     startup.  To set this maximum explicitly, set the
     'performance_schema_digests_size' system variable at server
     startup.

   * 'events_statements_summary_by_host_by_event_name'
     has 'EVENT_NAME' and 'HOST' columns.
     Each row summarizes events for a given host and event name.

   * 'events_statements_summary_by_program'
     has 'OBJECT_TYPE', 'OBJECT_SCHEMA', and
     'OBJECT_NAME' columns.  Each row summarizes events for a given
     stored program (stored procedure or function, trigger, or event).

   * 'events_statements_summary_by_thread_by_event_name'
     has 'THREAD_ID' and 'EVENT_NAME' columns.
     Each row summarizes events for a given thread and event name.

   * 'events_statements_summary_by_user_by_event_name'
     has 'EVENT_NAME' and 'USER' columns.
     Each row summarizes events for a given user and event name.

   * 'events_statements_summary_global_by_event_name'
     has an 'EVENT_NAME' column.  Each row
     summarizes events for a given event name.

   * 'prepared_statements_instances'
     has an 'OBJECT_INSTANCE_BEGIN'
     column.  Each row summarizes events for a given prepared statement.

Each statement summary table has these summary columns containing
aggregated values (with exceptions as noted):

   * 'COUNT_STAR', 'SUM_TIMER_WAIT', 'MIN_TIMER_WAIT', 'AVG_TIMER_WAIT',
     'MAX_TIMER_WAIT'

     These columns are analogous to the columns of the same names in the
     wait event summary tables (see wait-summary-tables), except
     that the statement summary tables aggregate events from
     'events_statements_current'.
     rather than 'events_waits_current'.

     The 'prepared_statements_instances'
     table does not have these
     columns.

   * 'SUM_XXX'

     The aggregate of the corresponding XXX column in the
     'events_statements_current'.
     table.  For example, the 'SUM_LOCK_TIME' and 'SUM_ERRORS' columns
     in statement summary tables are the aggregates of the 'LOCK_TIME'
     and 'ERRORS' columns in 'events_statements_current'
     table.

The 'events_statements_summary_by_digest'
table has these additional summary columns:

   * 'FIRST_SEEN', 'LAST_SEEN'

     Timestamps indicating when statements with the given digest value
     were first seen and most recently seen.

The 'events_statements_summary_by_program'
table has these additional summary columns:

   * 'COUNT_STATEMENTS', 'SUM_STATEMENTS_WAIT', 'MIN_STATEMENTS_WAIT',
     'AVG_STATEMENTS_WAIT', 'MAX_STATEMENTS_WAIT'

     Statistics about nested statements invoked during stored program
     execution.

The 'prepared_statements_instances'
table has these additional summary
columns:

   * 'COUNT_EXECUTE', 'SUM_TIMER_EXECUTE', 'MIN_TIMER_EXECUTE',
     'AVG_TIMER_EXECUTE', 'MAX_TIMER_EXECUTE'

     Aggregated statistics for executions of the prepared statement.

'TRUNCATE TABLE' is permitted for statement
summary tables.  It has these effects:

   * For 'events_statements_summary_by_digest',
     it removes the rows.

   * For other summary tables not aggregated by account, host, or user,
     truncation resets the summary columns to zero rather than removing
     rows.

   * For other summary tables aggregated by account, host, or user,
     truncation removes rows for accounts, hosts, or users with no
     connections, and resets the summary columns to zero for the
     remaining rows.

In addition, each statement summary table that is aggregated by account,
host, user, or thread is implicitly truncated by truncation of the
connection table on which it depends, or truncation of
'events_statements_summary_global_by_event_name'.
For details, see
performance-schema-connection-tables.

*Statement Digest Aggregation Rules*

If the 'statements_digest' consumer is enabled, aggregation into
'events_statements_summary_by_digest' occurs
as follows when a statement completes.  Aggregation is based on the
'DIGEST' value computed for the statement.

   * If a 'events_statements_summary_by_digest'
     row already exists with the digest value
     for the statement that just completed, statistics for the statement
     are aggregated to that row.  The 'LAST_SEEN' column is updated to
     the current time.

   * If no row has the digest value for the statement that just
     completed, and the table is not full, a new row is created for the
     statement.  The 'FIRST_SEEN' and 'LAST_SEEN' columns are
     initialized with the current time.

   * If no row has the statement digest value for the statement that
     just completed, and the table is full, the statistics for the
     statement that just completed are added to a special 'catch-all'
     row with 'DIGEST' = 'NULL', which is created if necessary.  If the
     row is created, the 'FIRST_SEEN' and 'LAST_SEEN' columns are
     initialized with the current time.  Otherwise, the 'LAST_SEEN'
     column is updated with the current time.

The row with 'DIGEST' = 'NULL' is maintained because Performance Schema
tables have a maximum size due to memory constraints.  The 'DIGEST' =
'NULL' row permits digests that do not match other rows to be counted
even if the summary table is full, using a common 'other' bucket.  This
row helps you estimate whether the digest summary is representative:

   * A 'DIGEST' = 'NULL' row that has a 'COUNT_STAR' value that
     represents 5% of all digests shows that the digest summary table is
     very representative; the other rows cover 95% of the statements
     seen.

   * A 'DIGEST' = 'NULL' row that has a 'COUNT_STAR' value that
     represents 50% of all digests shows that the digest summary table
     is not very representative; the other rows cover only half the
     statements seen.  Most likely the DBA should increase the maximum
     table size so that more of the rows counted in the 'DIGEST' =
     'NULL' row would be counted using more specific rows instead.  To
     do this, set the 'performance_schema_digests_size' system variable
     to a larger value at server startup.  The default size is 200.

*Stored Program Instrumentation Behavior*

For stored program types for which instrumentation is enabled in the
'setup_objects' table, see
'events_statements_summary_by_program'.
maintains statistics for stored programs as follows:

   * A row is added for an object when it is first used in the server.

   * The row for an object is removed when the object is dropped.

   * Statistics are aggregated in the row for an object as it executes.

See also performance-schema-pre-filtering.

25.11.15.4 Transaction Summary Tables
.....................................

The Performance Schema maintains tables for collecting current and
recent transaction events, and aggregates that information in summary
tables.  performance-schema-transaction-tables describes the
events on which transaction summaries are based.  See that discussion
for information about the content of transaction events, the current and
recent transaction event tables, and how to control transaction event
collection, which is disabled by default.

Example transaction event summary information:

     mysql> SELECT * FROM events_transactions_summary_global_by_event_name LIMIT 1\G
     *************************** 1. row ***************************
               EVENT_NAME: transaction
               COUNT_STAR: 5
           SUM_TIMER_WAIT: 19550092000
           MIN_TIMER_WAIT: 2954148000
           AVG_TIMER_WAIT: 3910018000
           MAX_TIMER_WAIT: 5486275000
         COUNT_READ_WRITE: 5
     SUM_TIMER_READ_WRITE: 19550092000
     MIN_TIMER_READ_WRITE: 2954148000
     AVG_TIMER_READ_WRITE: 3910018000
     MAX_TIMER_READ_WRITE: 5486275000
          COUNT_READ_ONLY: 0
      SUM_TIMER_READ_ONLY: 0
      MIN_TIMER_READ_ONLY: 0
      AVG_TIMER_READ_ONLY: 0
      MAX_TIMER_READ_ONLY: 0

Each transaction summary table has one or more grouping columns to
indicate how the table aggregates events.  Event names refer to names of
event instruments in the 'setup_instruments'
table:

   * 'events_transactions_summary_by_account_by_event_name'
     has 'USER', 'HOST', and 'EVENT_NAME'
     columns.  Each row summarizes events for a given account (user and
     host combination) and event name.

   * 'events_transactions_summary_by_host_by_event_name'
     has 'HOST' and 'EVENT_NAME' columns.
     Each row summarizes events for a given host and event name.

   * 'events_transactions_summary_by_thread_by_event_name'
     has 'THREAD_ID' and 'EVENT_NAME'
     columns.  Each row summarizes events for a given thread and event
     name.

   * 'events_transactions_summary_by_user_by_event_name'
     has 'USER' and 'EVENT_NAME' columns.
     Each row summarizes events for a given user and event name.

   * 'events_transactions_summary_global_by_event_name'
     has an 'EVENT_NAME' column.  Each row
     summarizes events for a given event name.

Each transaction summary table has these summary columns containing
aggregated values:

   * 'COUNT_STAR', 'SUM_TIMER_WAIT', 'MIN_TIMER_WAIT', 'AVG_TIMER_WAIT',
     'MAX_TIMER_WAIT'

     These columns are analogous to the columns of the same names in the
     wait event summary tables (see wait-summary-tables), except
     that the transaction summary tables aggregate events from
     'events_transactions_current'.
     rather than 'events_waits_current'.
     These columns summarize read-write and
     read-only transactions.

   * 'COUNT_READ_WRITE', 'SUM_TIMER_READ_WRITE', 'MIN_TIMER_READ_WRITE',
     'AVG_TIMER_READ_WRITE', 'MAX_TIMER_READ_WRITE'

     These are similar to the 'COUNT_STAR' and 'XXX_TIMER_WAIT' columns,
     but summarize read-write transactions only.

   * 'COUNT_READ_ONLY', 'SUM_TIMER_READ_ONLY', 'MIN_TIMER_READ_ONLY',
     'AVG_TIMER_READ_ONLY', 'MAX_TIMER_READ_ONLY'

     These are similar to the 'COUNT_STAR' and 'XXX_TIMER_WAIT' columns,
     but summarize read-only transactions only.

'TRUNCATE TABLE' is permitted for transaction
summary tables.  It has these effects:

   * For summary tables not aggregated by account, host, or user,
     truncation resets the summary columns to zero rather than removing
     rows.

   * For summary tables aggregated by account, host, or user, truncation
     removes rows for accounts, hosts, or users with no connections, and
     resets the summary columns to zero for the remaining rows.

In addition, each transaction summary table that is aggregated by
account, host, user, or thread is implicitly truncated by truncation of
the connection table on which it depends, or truncation of
'events_transactions_summary_global_by_event_name'.
For details, see
performance-schema-connection-tables.

*Transaction Aggregation Rules*

Transaction event collection occurs without regard to isolation level,
access mode, or autocommit mode.

Read-write transactions are generally more resource intensive than
read-only transactions, therefore transaction summary tables include
separate aggregate columns for read-write and read-only transactions.

Resource requirements may also vary with transaction isolation level.
However, presuming that only one isolation level would be used per
server, aggregation by isolation level is not provided.

25.11.15.5 Object Wait Summary Table
....................................

The Performance Schema maintains the
'objects_summary_global_by_type'.
table for aggregating object wait events.

Example object wait event summary information:

     mysql> SELECT * FROM objects_summary_global_by_type\G
     ...
     *************************** 3. row ***************************
        OBJECT_TYPE: TABLE
      OBJECT_SCHEMA: test
        OBJECT_NAME: t
         COUNT_STAR: 3
     SUM_TIMER_WAIT: 263126976
     MIN_TIMER_WAIT: 1522272
     AVG_TIMER_WAIT: 87708678
     MAX_TIMER_WAIT: 258428280
     ...
     *************************** 10. row ***************************
        OBJECT_TYPE: TABLE
      OBJECT_SCHEMA: mysql
        OBJECT_NAME: user
         COUNT_STAR: 14
     SUM_TIMER_WAIT: 365567592
     MIN_TIMER_WAIT: 1141704
     AVG_TIMER_WAIT: 26111769
     MAX_TIMER_WAIT: 334783032
     ...

The 'objects_summary_global_by_type'
table has these grouping columns
to indicate how the table aggregates events: 'OBJECT_TYPE',
'OBJECT_SCHEMA', and 'OBJECT_NAME'.  Each row summarizes events for the
given object.

'objects_summary_global_by_type'
has the same summary columns as
the 'events_waits_summary_by_XXX' tables.  See
wait-summary-tables.

'TRUNCATE TABLE' is permitted for the object
summary table.  It resets the summary columns to zero rather than
removing rows.

25.11.15.6 File I/O Summary Tables
..................................

The Performance Schema maintains file I/O summary tables that aggregate
information about I/O operations.

Example file I/O event summary information:

     mysql> SELECT * FROM file_summary_by_event_name\G
     ...
     *************************** 2. row ***************************
                    EVENT_NAME: wait/io/file/sql/binlog
                    COUNT_STAR: 31
                SUM_TIMER_WAIT: 8243784888
                MIN_TIMER_WAIT: 0
                AVG_TIMER_WAIT: 265928484
                MAX_TIMER_WAIT: 6490658832
     ...
     mysql> SELECT * FROM file_summary_by_instance\G
     ...
     *************************** 2. row ***************************
                     FILE_NAME: /var/mysql/share/english/errmsg.sys
                    EVENT_NAME: wait/io/file/sql/ERRMSG
                    EVENT_NAME: wait/io/file/sql/ERRMSG
         OBJECT_INSTANCE_BEGIN: 4686193384
                    COUNT_STAR: 5
                SUM_TIMER_WAIT: 13990154448
                MIN_TIMER_WAIT: 26349624
                AVG_TIMER_WAIT: 2798030607
                MAX_TIMER_WAIT: 8150662536
     ...

Each file I/O summary table has one or more grouping columns to indicate
how the table aggregates events.  Event names refer to names of event
instruments in the 'setup_instruments'.
table:

   * 'file_summary_by_event_name' has an
     'EVENT_NAME' column.  Each row summarizes events for a given event
     name.

   * 'file_summary_by_instance' has
     'FILE_NAME', 'EVENT_NAME', and 'OBJECT_INSTANCE_BEGIN' columns.
     Each row summarizes events for a given file and event name.

Each file I/O summary table has the following summary columns containing
aggregated values.  Some columns are more general and have values that
are the same as the sum of the values of more fine-grained columns.  In
this way, aggregations at higher levels are available directly without
the need for user-defined views that sum lower-level columns.

   * 'COUNT_STAR', 'SUM_TIMER_WAIT', 'MIN_TIMER_WAIT', 'AVG_TIMER_WAIT',
     'MAX_TIMER_WAIT'

     These columns aggregate all I/O operations.

   * 'COUNT_READ', 'SUM_TIMER_READ', 'MIN_TIMER_READ', 'AVG_TIMER_READ',
     'MAX_TIMER_READ', 'SUM_NUMBER_OF_BYTES_READ'

     These columns aggregate all read operations, including 'FGETS',
     'FGETC', 'FREAD', and 'READ'.

   * 'COUNT_WRITE', 'SUM_TIMER_WRITE', 'MIN_TIMER_WRITE',
     'AVG_TIMER_WRITE', 'MAX_TIMER_WRITE', 'SUM_NUMBER_OF_BYTES_WRITE'

     These columns aggregate all write operations, including 'FPUTS',
     'FPUTC', 'FPRINTF', 'VFPRINTF', 'FWRITE', and 'PWRITE'.

   * 'COUNT_MISC', 'SUM_TIMER_MISC', 'MIN_TIMER_MISC', 'AVG_TIMER_MISC',
     'MAX_TIMER_MISC'

     These columns aggregate all other I/O operations, including
     'CREATE', 'DELETE', 'OPEN', 'CLOSE', 'STREAM_OPEN', 'STREAM_CLOSE',
     'SEEK', 'TELL', 'FLUSH', 'STAT', 'FSTAT', 'CHSIZE', 'RENAME', and
     'SYNC'.  There are no byte counts for these operations.

'TRUNCATE TABLE' is permitted for file I/O
summary tables.  It resets the summary columns to zero rather than
removing rows.

The MySQL server uses several techniques to avoid I/O operations by
caching information read from files, so it is possible that statements
you might expect to result in I/O events will not.  You may be able to
ensure that I/O does occur by flushing caches or restarting the server
to reset its state.

25.11.15.7 Table I/O and Lock Wait Summary Tables
.................................................

The following sections describe the table I/O and lock wait summary
tables:

   * 'table_io_waits_summary_by_index_usage'.:
     Table I/O waits per
     index

   * 'table_io_waits_summary_by_table'.:
     Table I/O waits per table

   * 'table_lock_waits_summary_by_table'.:
     Table lock waits per
     table

25.11.15.8 The table_io_waits_summary_by_table Table
....................................................

The 'table_io_waits_summary_by_table'
table aggregates all table I/O
wait events, as generated by the 'wait/io/table/sql/handler' instrument.
The grouping is by table.

The 'table_io_waits_summary_by_table'
table has these grouping columns
to indicate how the table aggregates events: 'OBJECT_TYPE',
'OBJECT_SCHEMA', and 'OBJECT_NAME'.  These columns have the same meaning
as in the 'events_waits_current'.
table.  They identify the table to which the row applies.

'table_io_waits_summary_by_table'
has the following summary columns
containing aggregated values.  As indicated in the column descriptions,
some columns are more general and have values that are the same as the
sum of the values of more fine-grained columns.  For example, columns
that aggregate all writes hold the sum of the corresponding columns that
aggregate inserts, updates, and deletes.  In this way, aggregations at
higher levels are available directly without the need for user-defined
views that sum lower-level columns.

   * 'COUNT_STAR', 'SUM_TIMER_WAIT', 'MIN_TIMER_WAIT', 'AVG_TIMER_WAIT',
     'MAX_TIMER_WAIT'

     These columns aggregate all I/O operations.  They are the same as
     the sum of the corresponding 'XXX_READ' and 'XXX_WRITE' columns.

   * 'COUNT_READ', 'SUM_TIMER_READ', 'MIN_TIMER_READ', 'AVG_TIMER_READ',
     'MAX_TIMER_READ'

     These columns aggregate all read operations.  They are the same as
     the sum of the corresponding 'XXX_FETCH' columns.

   * 'COUNT_WRITE', 'SUM_TIMER_WRITE', 'MIN_TIMER_WRITE',
     'AVG_TIMER_WRITE', 'MAX_TIMER_WRITE'

     These columns aggregate all write operations.  They are the same as
     the sum of the corresponding 'XXX_INSERT', 'XXX_UPDATE', and
     'XXX_DELETE' columns.

   * 'COUNT_FETCH', 'SUM_TIMER_FETCH', 'MIN_TIMER_FETCH',
     'AVG_TIMER_FETCH', 'MAX_TIMER_FETCH'

     These columns aggregate all fetch operations.

   * 'COUNT_INSERT', 'SUM_TIMER_INSERT', 'MIN_TIMER_INSERT',
     'AVG_TIMER_INSERT', 'MAX_TIMER_INSERT'

     These columns aggregate all insert operations.

   * 'COUNT_UPDATE', 'SUM_TIMER_UPDATE', 'MIN_TIMER_UPDATE',
     'AVG_TIMER_UPDATE', 'MAX_TIMER_UPDATE'

     These columns aggregate all update operations.

   * 'COUNT_DELETE', 'SUM_TIMER_DELETE', 'MIN_TIMER_DELETE',
     'AVG_TIMER_DELETE', 'MAX_TIMER_DELETE'

     These columns aggregate all delete operations.

'TRUNCATE TABLE' is permitted for table I/O
summary tables.  It resets the summary columns to zero rather than
removing rows.  Truncating this table also truncates the
'table_io_waits_summary_by_index_usage'
table.

25.11.15.9 The table_io_waits_summary_by_index_usage Table
..........................................................

The 'table_io_waits_summary_by_index_usage'
table aggregates all table
index I/O wait events, as generated by the 'wait/io/table/sql/handler'
instrument.  The grouping is by table index.

The columns of 'table_io_waits_summary_by_index_usage'
are nearly identical to
'table_io_waits_summary_by_table'.
The only difference is the
additional group column, 'INDEX_NAME', which corresponds to the name of
the index that was used when the table I/O wait event was recorded:

   * A value of 'PRIMARY' indicates that table I/O used the primary
     index.

   * A value of 'NULL' means that table I/O used no index.

   * Inserts are counted against 'INDEX_NAME = NULL'.

'TRUNCATE TABLE' is permitted for table I/O
summary tables.  It resets the summary columns to zero rather than
removing rows.  This table is also truncated by truncation of the
'table_io_waits_summary_by_table'
table.  A DDL operation that
changes the index structure of a table may cause the per-index
statistics to be reset.

25.11.15.10 The table_lock_waits_summary_by_table Table
.......................................................

The 'table_lock_waits_summary_by_table'
table aggregates all table lock
wait events, as generated by the 'wait/lock/table/sql/handler'
instrument.  The grouping is by table.

This table contains information about internal and external locks:

   * An internal lock corresponds to a lock in the SQL layer.  This is
     currently implemented by a call to 'thr_lock()'.  In event rows,
     these locks are distinguished by the 'OPERATION' column, which has
     one of these values:

          read normal
          read with shared locks
          read high priority
          read no insert
          write allow write
          write concurrent insert
          write delayed
          write low priority
          write normal

   * An external lock corresponds to a lock in the storage engine layer.
     This is currently implemented by a call to
     'handler::external_lock()'.  In event rows, these locks are
     distinguished by the 'OPERATION' column, which has one of these
     values:

          read external
          write external

The 'table_lock_waits_summary_by_table'
table has these grouping
columns to indicate how the table aggregates events: 'OBJECT_TYPE',
'OBJECT_SCHEMA', and 'OBJECT_NAME'.  These columns have the same meaning
as in the 'events_waits_current'.
table.  They identify the table to which the row applies.

'table_lock_waits_summary_by_table'
has the following summary
columns containing aggregated values.  As indicated in the column
descriptions, some columns are more general and have values that are the
same as the sum of the values of more fine-grained columns.  For
example, columns that aggregate all locks hold the sum of the
corresponding columns that aggregate read and write locks.  In this way,
aggregations at higher levels are available directly without the need
for user-defined views that sum lower-level columns.

   * 'COUNT_STAR', 'SUM_TIMER_WAIT', 'MIN_TIMER_WAIT', 'AVG_TIMER_WAIT',
     'MAX_TIMER_WAIT'

     These columns aggregate all lock operations.  They are the same as
     the sum of the corresponding 'XXX_READ' and 'XXX_WRITE' columns.

   * 'COUNT_READ', 'SUM_TIMER_READ', 'MIN_TIMER_READ', 'AVG_TIMER_READ',
     'MAX_TIMER_READ'

     These columns aggregate all read-lock operations.  They are the
     same as the sum of the corresponding 'XXX_READ_NORMAL',
     'XXX_READ_WITH_SHARED_LOCKS', 'XXX_READ_HIGH_PRIORITY', and
     'XXX_READ_NO_INSERT' columns.

   * 'COUNT_WRITE', 'SUM_TIMER_WRITE', 'MIN_TIMER_WRITE',
     'AVG_TIMER_WRITE', 'MAX_TIMER_WRITE'

     These columns aggregate all write-lock operations.  They are the
     same as the sum of the corresponding 'XXX_WRITE_ALLOW_WRITE',
     'XXX_WRITE_CONCURRENT_INSERT', 'XXX_WRITE_LOW_PRIORITY', and
     'XXX_WRITE_NORMAL' columns.

   * 'COUNT_READ_NORMAL', 'SUM_TIMER_READ_NORMAL',
     'MIN_TIMER_READ_NORMAL', 'AVG_TIMER_READ_NORMAL',
     'MAX_TIMER_READ_NORMAL'

     These columns aggregate internal read locks.

   * 'COUNT_READ_WITH_SHARED_LOCKS', 'SUM_TIMER_READ_WITH_SHARED_LOCKS',
     'MIN_TIMER_READ_WITH_SHARED_LOCKS',
     'AVG_TIMER_READ_WITH_SHARED_LOCKS',
     'MAX_TIMER_READ_WITH_SHARED_LOCKS'

     These columns aggregate internal read locks.

   * 'COUNT_READ_HIGH_PRIORITY', 'SUM_TIMER_READ_HIGH_PRIORITY',
     'MIN_TIMER_READ_HIGH_PRIORITY', 'AVG_TIMER_READ_HIGH_PRIORITY',
     'MAX_TIMER_READ_HIGH_PRIORITY'

     These columns aggregate internal read locks.

   * 'COUNT_READ_NO_INSERT', 'SUM_TIMER_READ_NO_INSERT',
     'MIN_TIMER_READ_NO_INSERT', 'AVG_TIMER_READ_NO_INSERT',
     'MAX_TIMER_READ_NO_INSERT'

     These columns aggregate internal read locks.

   * 'COUNT_READ_EXTERNAL', 'SUM_TIMER_READ_EXTERNAL',
     'MIN_TIMER_READ_EXTERNAL', 'AVG_TIMER_READ_EXTERNAL',
     'MAX_TIMER_READ_EXTERNAL'

     These columns aggregate external read locks.

   * 'COUNT_WRITE_ALLOW_WRITE', 'SUM_TIMER_WRITE_ALLOW_WRITE',
     'MIN_TIMER_WRITE_ALLOW_WRITE', 'AVG_TIMER_WRITE_ALLOW_WRITE',
     'MAX_TIMER_WRITE_ALLOW_WRITE'

     These columns aggregate internal write locks.

   * 'COUNT_WRITE_CONCURRENT_INSERT',
     'SUM_TIMER_WRITE_CONCURRENT_INSERT',
     'MIN_TIMER_WRITE_CONCURRENT_INSERT',
     'AVG_TIMER_WRITE_CONCURRENT_INSERT',
     'MAX_TIMER_WRITE_CONCURRENT_INSERT'

     These columns aggregate internal write locks.

   * 'COUNT_WRITE_LOW_PRIORITY', 'SUM_TIMER_WRITE_LOW_PRIORITY',
     'MIN_TIMER_WRITE_LOW_PRIORITY', 'AVG_TIMER_WRITE_LOW_PRIORITY',
     'MAX_TIMER_WRITE_LOW_PRIORITY'

     These columns aggregate internal write locks.

   * 'COUNT_WRITE_NORMAL', 'SUM_TIMER_WRITE_NORMAL',
     'MIN_TIMER_WRITE_NORMAL', 'AVG_TIMER_WRITE_NORMAL',
     'MAX_TIMER_WRITE_NORMAL'

     These columns aggregate internal write locks.

   * 'COUNT_WRITE_EXTERNAL', 'SUM_TIMER_WRITE_EXTERNAL',
     'MIN_TIMER_WRITE_EXTERNAL', 'AVG_TIMER_WRITE_EXTERNAL',
     'MAX_TIMER_WRITE_EXTERNAL'

     These columns aggregate external write locks.

'TRUNCATE TABLE' is permitted for table lock
summary tables.  It resets the summary columns to zero rather than
removing rows.

25.11.15.11 Socket Summary Tables
.................................

These socket summary tables aggregate timer and byte count information
for socket operations:

   * 'socket_summary_by_event_name'.:
     Aggregate timer and byte count statistics generated by the
     'wait/io/socket/*' instruments for all socket I/O operations, per
     socket instrument.

   * 'socket_summary_by_instance'.:
     Aggregate timer and byte count statistics generated by the
     'wait/io/socket/*' instruments for all socket I/O operations, per
     socket instance.  When a connection terminates, the row in
     'socket_summary_by_instance' corresponding
     to it is deleted.

The socket summary tables do not aggregate waits generated by 'idle'
events while sockets are waiting for the next request from the client.
For 'idle' event aggregations, use the wait-event summary tables; see
wait-summary-tables.

Each socket summary table has one or more grouping columns to indicate
how the table aggregates events.  Event names refer to names of event
instruments in the 'setup_instruments'.
table:

   * 'socket_summary_by_event_name' has an
     'EVENT_NAME' column.  Each row summarizes events for a given event
     name.

   * 'socket_summary_by_instance' has an
     'OBJECT_INSTANCE_BEGIN' column.  Each row summarizes events for a
     given object.

Each socket summary table has these summary columns containing
aggregated values:

   * 'COUNT_STAR', 'SUM_TIMER_WAIT', 'MIN_TIMER_WAIT', 'AVG_TIMER_WAIT',
     'MAX_TIMER_WAIT'

     These columns aggregate all operations.

   * 'COUNT_READ', 'SUM_TIMER_READ', 'MIN_TIMER_READ', 'AVG_TIMER_READ',
     'MAX_TIMER_READ', 'SUM_NUMBER_OF_BYTES_READ'

     These columns aggregate all receive operations ('RECV', 'RECVFROM',
     and 'RECVMSG').

   * 'COUNT_WRITE', 'SUM_TIMER_WRITE', 'MIN_TIMER_WRITE',
     'AVG_TIMER_WRITE', 'MAX_TIMER_WRITE', 'SUM_NUMBER_OF_BYTES_WRITE'

     These columns aggregate all send operations ('SEND', 'SENDTO', and
     'SENDMSG').

   * 'COUNT_MISC', 'SUM_TIMER_MISC', 'MIN_TIMER_MISC', 'AVG_TIMER_MISC',
     'MAX_TIMER_MISC'

     These columns aggregate all other socket operations, such as
     'CONNECT', 'LISTEN', 'ACCEPT', 'CLOSE', and 'SHUTDOWN'.  There are
     no byte counts for these operations.

The 'socket_summary_by_instance' table
also has an 'EVENT_NAME' column that indicates the class of the socket:
'client_connection', 'server_tcpip_socket', 'server_unix_socket'.  This
column can be grouped on to isolate, for example, client activity from
that of the server listening sockets.

'TRUNCATE TABLE' is permitted for socket summary
tables.  Except for 'events_statements_summary_by_digest',
tt resets the summary columns to zero rather
than removing rows.

25.11.15.12 Memory Summary Tables
.................................

The Performance Schema instruments memory usage and aggregates memory
usage statistics, detailed by these factors:

   * Type of memory used (various caches, internal buffers, and so
     forth)

   * Thread, account, user, host indirectly performing the memory
     operation

The Performance Schema instruments the following aspects of memory use

   * Memory sizes used

   * Operation counts

   * Low and high water marks

Memory sizes help to understand or tune the memory consumption of the
server.

Operation counts help to understand or tune the overall pressure the
server is putting on the memory allocator, which has an impact on
performance.  Allocating a single byte one million times is not the same
as allocating one million bytes a single time; tracking both sizes and
counts can expose the difference.

Low and high water marks are critical to detect workload spikes, overall
workload stability, and possible memory leaks.

Memory summary tables do not contain timing information because memory
events are not timed.

For information about collecting memory usage data, see
memory-instrumentation-behavior.

Example memory event summary information:

     mysql> SELECT * FROM memory_summary_global_by_event_name
            WHERE EVENT_NAME = 'memory/sql/TABLE'\G
     *************************** 1. row ***************************
                       EVENT_NAME: memory/sql/TABLE
                      COUNT_ALLOC: 1381
                       COUNT_FREE: 924
        SUM_NUMBER_OF_BYTES_ALLOC: 2059873
         SUM_NUMBER_OF_BYTES_FREE: 1407432
                   LOW_COUNT_USED: 0
               CURRENT_COUNT_USED: 457
                  HIGH_COUNT_USED: 461
         LOW_NUMBER_OF_BYTES_USED: 0
     CURRENT_NUMBER_OF_BYTES_USED: 652441
        HIGH_NUMBER_OF_BYTES_USED: 669269

Each memory summary table has one or more grouping columns to indicate
how the table aggregates events.  Event names refer to names of event
instruments in the 'setup_instruments'.
table:

   * 'memory_summary_by_account_by_event_name'
     has 'USER', 'HOST', and 'EVENT_NAME'
     columns.  Each row summarizes events for a given account (user and
     host combination) and event name.

   * 'memory_summary_by_host_by_event_name'
     has 'HOST' and 'EVENT_NAME' columns.  Each
     row summarizes events for a given host and event name.

   * 'memory_summary_by_thread_by_event_name'
     has 'THREAD_ID' and 'EVENT_NAME' columns.
     Each row summarizes events for a given thread and event name.

   * 'memory_summary_by_user_by_event_name'
     has 'USER' and 'EVENT_NAME' columns.  Each
     row summarizes events for a given user and event name.

   * 'memory_summary_global_by_event_name'.
     has an 'EVENT_NAME' column.  Each row summarizes events for a given
     event name.

Each memory summary table has these summary columns containing
aggregated values:

   * 'COUNT_ALLOC', 'COUNT_FREE'

     The aggregated numbers of calls to memory-allocation and
     memory-free functions.

   * 'SUM_NUMBER_OF_BYTES_ALLOC', 'SUM_NUMBER_OF_BYTES_FREE'

     The aggregated sizes of allocated and freed memory blocks.

   * 'CURRENT_COUNT_USED'

     The aggregated number of currently allocated blocks that have not
     been freed yet.  This is a convenience column, equal to
     'COUNT_ALLOC' − 'COUNT_FREE'.

   * 'CURRENT_NUMBER_OF_BYTES_USED'

     The aggregated size of currently allocated memory blocks that have
     not been freed yet.  This is a convenience column, equal to
     'SUM_NUMBER_OF_BYTES_ALLOC' − 'SUM_NUMBER_OF_BYTES_FREE'.

   * 'LOW_COUNT_USED', 'HIGH_COUNT_USED'

     The low and high water marks corresponding to the
     'CURRENT_COUNT_USED' column.

   * 'LOW_NUMBER_OF_BYTES_USED', 'HIGH_NUMBER_OF_BYTES_USED'

     The low and high water marks corresponding to the
     'CURRENT_NUMBER_OF_BYTES_USED' column.

'TRUNCATE TABLE' is permitted for memory summary
tables.  It has these effects:

   * In general, truncation resets the baseline for statistics, but does
     not change the server state.  That is, truncating a memory table
     does not free memory.

   * 'COUNT_ALLOC' and 'COUNT_FREE' are reset to a new baseline, by
     reducing each counter by the same value.

   * Likewise, 'SUM_NUMBER_OF_BYTES_ALLOC' and
     'SUM_NUMBER_OF_BYTES_FREE' are reset to a new baseline.

   * 'LOW_COUNT_USED' and 'HIGH_COUNT_USED' are reset to
     'CURRENT_COUNT_USED'.

   * 'LOW_NUMBER_OF_BYTES_USED' and 'HIGH_NUMBER_OF_BYTES_USED' are
     reset to 'CURRENT_NUMBER_OF_BYTES_USED'.

In addition, each memory summary table that is aggregated by account,
host, user, or thread is implicitly truncated by truncation of the
connection table on which it depends, or truncation of
'memory_summary_global_by_event_name'.  For
details, see performance-schema-connection-tables.

*Memory Instrumentation Behavior*

Memory instruments are listed in the 'setup_instruments'
table and have names of the form
'memory/CODE_AREA/INSTRUMENT_NAME'.  Most memory instrumentation is
disabled by default.

Instruments named with the prefix 'memory/performance_schema/' expose
how much memory is allocated for internal buffers in the Performance
Schema itself.  The 'memory/performance_schema/' instruments are built
in, always enabled, and cannot be disabled at startup or runtime.
Built-in memory instruments are displayed only in the
'memory_summary_global_by_event_name' table.

To control memory instrumention state at server startup, use lines like
these in your 'my.cnf' file:

   * Enable:

          [mysqld]
          performance-schema-instrument='memory/%=ON'

   * Disable:

          [mysqld]
          performance-schema-instrument='memory/%=OFF'

To control memory instrumention state at runtime, update the 'ENABLED'
column of the relevant instruments in the 'setup_instruments'
table:

   * Enable:

          UPDATE setup_instruments SET ENABLED = 'YES'
          WHERE NAME LIKE 'memory/%';

   * Disable:

          UPDATE setup_instruments SET ENABLED = 'NO'
          WHERE NAME LIKE 'memory/%';

For memory instruments, the 'TIMED' column in 'setup_instruments'
is ignored because memory operations are not
timed.

*Note*:

If disabled memory instrumentation is later enabled, accounting may
result in an apparently negative allocation from missing an allocation
operation but counting a free operation.

When a thread in the server executes a memory allocation that has been
instrumented, these rules apply:

   * If the thread is not instrumented or the memory instrument is not
     enabled, the memory block allocated is not instrumented.

   * Otherwise (that is, both the thread and the instrument are
     enabled), the memory block allocated is instrumented.

For deallocation, these rules apply:

   * If a thread is instrumented, and a memory block is not
     instrumented, the free operation is not instrumented; no statistics
     are changed.

   * If a thread is not instrumented, and a memory block is
     instrumented, the free operation is instrumented, and statistics
     are changed.

For the per-thread statistics, the following rules apply.

When an instrumented memory block of size N is allocated, the
Performance Schema makes these updates to memory summary table columns:

   * 'COUNT_ALLOC': Increased by 1

   * 'CURRENT_COUNT_USED': Increased by 1

   * 'HIGH_COUNT_USED': Increased if 'CURRENT_COUNT_USED' is a new
     maximum

   * 'SUM_NUMBER_OF_BYTES_ALLOC': Increased by N

   * 'CURRENT_NUMBER_OF_BYTES_USED': Increased by N

   * 'HIGH_NUMBER_OF_BYTES_USED': Increased if
     'CURRENT_NUMBER_OF_BYTES_USED' is a new maximum

When an instrumented memory block is deallocated, the Performance Schema
makes these updates to memory summary table columns:

   * 'COUNT_FREE': Increased by 1

   * 'CURRENT_COUNT_USED': Decreased by 1

   * 'LOW_COUNT_USED': Decreased if 'CURRENT_COUNT_USED' is a new
     minimum

   * 'SUM_NUMBER_OF_BYTES_FREE': Increased by N

   * 'CURRENT_NUMBER_OF_BYTES_USED': Decreased by N

   * 'LOW_NUMBER_OF_BYTES_USED': Decreased if
     'CURRENT_NUMBER_OF_BYTES_USED' is a new minimum

For higher-level aggregates (global, by account, by user, by host), the
same rules apply as expected for low and high water marks.

   * 'LOW_COUNT_USED' and 'LOW_NUMBER_OF_BYTES_USED' are lower
     estimates.  The value reported by the Performance Schema is
     guaranteed to be less than or equal to the lowest count or size of
     memory effectively used at runtime.

   * 'HIGH_COUNT_USED' and 'HIGH_NUMBER_OF_BYTES_USED' are higher
     estimates.  The value reported by the Performance Schema is
     guaranteed to be greater than or equal to the highest count or size
     of memory effectively used at runtime.

For lower estimates in summary tables other than
'memory_summary_global_by_event_name', it is
possible for values to go negative if memory ownership is transferred
between threads.

Here is an example of estimate computation; but note that estimate
implementation is subject to change:

Thread 1 uses memory in the range from 1MB to 2MB during execution, as
reported by the 'LOW_NUMBER_OF_BYTES_USED' and
'HIGH_NUMBER_OF_BYTES_USED' columns of the
'memory_summary_by_thread_by_event_name' table.

Thread 2 uses memory in the range from 10MB to 12MB during execution, as
reported likewise.

When these two threads belong to the same user account, the per-account
summary estimates that this account used memory in the range from 11MB
to 14MB. That is, the 'LOW_NUMBER_OF_BYTES_USED' for the higher level
aggregate is the sum of each 'LOW_NUMBER_OF_BYTES_USED' (assuming the
worst case).  Likewise, the 'HIGH_NUMBER_OF_BYTES_USED' for the higher
level aggregate is the sum of each 'HIGH_NUMBER_OF_BYTES_USED' (assuming
the worst case).

11MB is a lower estimate that can occur only if both threads hit the low
usage mark at the same time.

14MB is a higher estimate that can occur only if both threads hit the
high usage mark at the same time.

The real memory usage for this account could have been in the range from
11.5MB to 13.5MB.

For capacity planning, reporting the worst case is actually the desired
behavior, as it shows what can potentially happen when sessions are
uncorrelated, which is typically the case.

25.11.15.13 Status Variable Summary Tables
..........................................

*Note*:

The value of the 'show_compatibility_56' system variable affects the
information available from the tables described here.  For details, see
the description of that variable in server-system-variables.

The Performance Schema makes status variable information available in
the tables described in
performance-schema-status-variable-tables.  It also makes aggregated
status variable information available in summary tables, described here.
Each status variable summary table has one or more grouping columns to
indicate how the table aggregates status values:

   * 'status_by_account'
     has 'USER',
     'HOST', and 'VARIABLE_NAME' columns to summarize status variables
     by account.

   * 'status_by_host'
     has 'HOST' and
     'VARIABLE_NAME' columns to summarize status variables by the host
     from which clients connected.

   * 'status_by_user'
     has 'USER' and
     'VARIABLE_NAME' columns to summarize status variables by client
     user name.

Each status variable summary table has this summary column containing
aggregated values:

   * 'VARIABLE_VALUE'

     The aggregated status variable value for active and terminated
     sessions.

The meaning of 'account' in these tables is similar to its meaning in
the MySQL grant tables in the 'mysql' system database, in the sense that
the term refers to a combination of user and host values.  They differ
in that, for grant tables, the host part of an account can be a pattern,
whereas for Performance Schema tables, the host value is always a
specific nonpattern host name.

Account status is collected when sessions terminate.  The session status
counters are added to the global status counters and the corresponding
account status counters.  If account statistics are not collected, the
session status is added to host and user status, if host and user status
are collected.

Account, host, and user statistics are not collected if the
'performance_schema_accounts_size', 'performance_schema_hosts_size', and
'performance_schema_users_size' system variables, respectively, are set
to 0.

The Performance Schema supports 'TRUNCATE TABLE'.
for status variable summary tables as follows; in all cases, status for
active sessions is unaffected:

   * 'status_by_account'.:
     Aggregates
     account status from terminated sessions to user and host status,
     then resets account status.

   * 'status_by_host'.:
     Resets
     aggregated host status from terminated sessions.

   * 'status_by_user'.:
     Resets
     aggregated user status from terminated sessions.

'FLUSH STATUS' adds the session status from all active sessions to the
global status variables, resets the status of all active sessions, and
resets account, host, and user status values aggregated from
disconnected sessions.

25.11.16 Performance Schema Miscellaneous Tables
------------------------------------------------

The following sections describe tables that do not fall into the table
categories discussed in the preceding sections:

   * 'host_cache'.: Information from the
     internal host cache

   * 'performance_timers'.: Which event
     timers are available

   * 'threads'.: Information about server threads

25.11.16.1 The host_cache Table
...............................

The 'host_cache' table provides access to the
contents of the host cache, which contains client host name and IP
address information and is used to avoid DNS lookups.  (See
host-cache.)  The 'host_cache' table exposes
the contents of the host cache so that it can be examined using
'SELECT' statements.  The Performance Schema must be enabled or
this table is empty.

The 'host_cache' table has these columns:

   * 'IP'

     The IP address of the client that connected to the server,
     expressed as a string.

   * 'HOST'

     The resolved DNS host name for that client IP, or 'NULL' if the
     name is unknown.

   * 'HOST_VALIDATED'

     Whether the IP-to-host name-to-IP DNS resolution was performed
     successfully for the client IP. If 'HOST_VALIDATED' is 'YES', the
     'HOST' column is used as the host name corresponding to the IP so
     that calls to DNS can be avoided.  While 'HOST_VALIDATED' is 'NO',
     DNS resolution is attempted again for each connect, until it
     eventually completes with either a valid result or a permanent
     error.  This information enables the server to avoid caching bad or
     missing host names during temporary DNS failures, which would
     affect clients forever.

   * 'SUM_CONNECT_ERRORS'

     The number of connection errors that are deemed 'blocking'
     (assessed against the 'max_connect_errors' system variable).  Only
     protocol handshake errors are counted, and only for hosts that
     passed validation ('HOST_VALIDATED = YES').

   * 'COUNT_HOST_BLOCKED_ERRORS'

     The number of connections that were blocked because
     'SUM_CONNECT_ERRORS' exceeded the value of the 'max_connect_errors'
     system variable.

   * 'COUNT_NAMEINFO_TRANSIENT_ERRORS'

     The number of transient errors during IP-to-host name DNS
     resolution.

   * 'COUNT_NAMEINFO_PERMANENT_ERRORS'

     The number of permanent errors during IP-to-host name DNS
     resolution.

   * 'COUNT_FORMAT_ERRORS'

     The number of host name format errors.  MySQL does not perform
     matching of 'Host' column values in the 'mysql.user' table against
     host names for which one or more of the initial components of the
     name are entirely numeric, such as '1.2.example.com'.  The client
     IP address is used instead.  For the rationale why this type of
     matching does not occur, see account-names.

   * 'COUNT_ADDRINFO_TRANSIENT_ERRORS'

     The number of transient errors during host name-to-IP reverse DNS
     resolution.

   * 'COUNT_ADDRINFO_PERMANENT_ERRORS'

     The number of permanent errors during host name-to-IP reverse DNS
     resolution.

   * 'COUNT_FCRDNS_ERRORS'

     The number of forward-confirmed reverse DNS errors.  These errors
     occur when IP-to-host name-to-IP DNS resolution produces an IP
     address that does not match the client originating IP address.

   * 'COUNT_HOST_ACL_ERRORS'

     The number of errors that occur because no user from the client
     host can possibly log in.  In such cases, the server returns
     'ER_HOST_NOT_PRIVILEGED' and does not even ask for a user name or
     password.

   * 'COUNT_NO_AUTH_PLUGIN_ERRORS'

     The number of errors due to requests for an unavailable
     authentication plugin.  A plugin can be unavailable if, for
     example, it was never loaded or a load attempt failed.

   * 'COUNT_AUTH_PLUGIN_ERRORS'

     The number of errors reported by authentication plugins.

     An authentication plugin can report different error codes to
     indicate the root cause of a failure.  Depending on the type of
     error, one of these columns is incremented:
     'COUNT_AUTHENTICATION_ERRORS', 'COUNT_AUTH_PLUGIN_ERRORS',
     'COUNT_HANDSHAKE_ERRORS'.  New return codes are an optional
     extension to the existing plugin API. Unknown or unexpected plugin
     errors are counted in the 'COUNT_AUTH_PLUGIN_ERRORS' column.

   * 'COUNT_HANDSHAKE_ERRORS'

     The number of errors detected at the wire protocol level.

   * 'COUNT_PROXY_USER_ERRORS'

     The number of errors detected when a proxy user A is proxied to
     another user B who does not exist.

   * 'COUNT_PROXY_USER_ACL_ERRORS'

     The number of errors detected when a proxy user A is proxied to
     another user B who does exist but for whom A does not have the
     'PROXY' privilege.

   * 'COUNT_AUTHENTICATION_ERRORS'

     The number of errors caused by failed authentication.

   * 'COUNT_SSL_ERRORS'

     The number of errors due to SSL problems.

   * 'COUNT_MAX_USER_CONNECTIONS_ERRORS'

     The number of errors caused by exceeding per-user connection
     quotas.  See user-resources.

   * 'COUNT_MAX_USER_CONNECTIONS_PER_HOUR_ERRORS'

     The number of errors caused by exceeding per-user
     connections-per-hour quotas.  See user-resources.

   * 'COUNT_DEFAULT_DATABASE_ERRORS'

     The number of errors related to the default database.  For example,
     the database did not exist or the user had no privileges for
     accessing it.

   * 'COUNT_INIT_CONNECT_ERRORS'

     The number of errors caused by execution failures of statements in
     the 'init_connect' system variable value.

   * 'COUNT_LOCAL_ERRORS'

     The number of errors local to the server implementation and not
     related to the network, authentication, or authorization.  For
     example, out-of-memory conditions fall into this category.

   * 'COUNT_UNKNOWN_ERRORS'

     The number of other, unknown errors not accounted for by other
     columns in this table.  This column is reserved for future use, in
     case new error conditions must be reported, and if preserving the
     backward compatibility and table structure of the
     'host_cache' table is required.

   * 'FIRST_SEEN'

     The timestamp of the first connection attempt seen from the client
     in the 'IP' column.

   * 'LAST_SEEN'

     The timestamp of the last connection attempt seen from the client
     in the 'IP' column.

   * 'FIRST_ERROR_SEEN'

     The timestamp of the first error seen from the client in the 'IP'
     column.

   * 'LAST_ERROR_SEEN'

     The timestamp of the last error seen from the client in the 'IP'
     column.

'FLUSH HOSTS' and 'TRUNCATE TABLE host_cache'.
have the same effect: They clear the host cache.  This also removes rows
from the 'host_cache' table (because it is the
visible representation of the cache) and unblocks any blocked hosts (see
blocked-host.)  'FLUSH HOSTS' requires the 'RELOAD' privilege.
'TRUNCATE TABLE' requires the 'DROP' privilege
for the 'host_cache' table.

25.11.16.2 The performance_timers Table
.......................................

The 'performance_timers' table shows
which event timers are available:

     mysql> SELECT * FROM performance_timers;
     +-------------+-----------------+------------------+----------------+
     | TIMER_NAME  | TIMER_FREQUENCY | TIMER_RESOLUTION | TIMER_OVERHEAD |
     +-------------+-----------------+------------------+----------------+
     | CYCLE       |      2389029850 |                1 |             72 |
     | NANOSECOND  |      1000000000 |                1 |            112 |
     | MICROSECOND |         1000000 |                1 |            136 |
     | MILLISECOND |            1036 |                1 |            168 |
     | TICK        |             105 |                1 |           2416 |
     +-------------+-----------------+------------------+----------------+

If the values associated with a given timer name are 'NULL', that timer
is not supported on your platform.  The rows that do not contain 'NULL'
indicate which timers you can use in 'setup_timers'.
For an explanation of how event timing occurs, see
performance-schema-timing.

*Note*:

As of MySQL 5.7.21, the Performance Schema 'setup_timers'
table is deprecated and is removed in MySQL 8.0, as
is the 'TICKS' row in the 'performance_timers'
table.

The 'performance_timers' table has
these columns:

   * 'TIMER_NAME'

     The name by which to refer to the timer when configuring the
     'setup_timers' table.

   * 'TIMER_FREQUENCY'

     The number of timer units per second.  For a cycle timer, the
     frequency is generally related to the CPU speed.  For example, on a
     system with a 2.4GHz processor, the 'CYCLE' may be close to
     2400000000.

   * 'TIMER_RESOLUTION'

     Indicates the number of timer units by which timer values increase.
     If a timer has a resolution of 10, its value increases by 10 each
     time.

   * 'TIMER_OVERHEAD'

     The minimal number of cycles of overhead to obtain one timing with
     the given timer.  The Performance Schema determines this value by
     invoking the timer 20 times during initialization and picking the
     smallest value.  The total overhead really is twice this amount
     because the instrumentation invokes the timer at the start and end
     of each event.  The timer code is called only for timed events, so
     this overhead does not apply for nontimed events.

'TRUNCATE TABLE' is not permitted for the
'performance_timers' table.

25.11.16.3 The threads Table
............................

The 'threads' table contains a row for each server
thread.  Each row contains information about a thread and indicates
whether monitoring and historical event logging are enabled for it:

     mysql> SELECT * FROM threads\G
     *************************** 1. row ***************************
               THREAD_ID: 1
                    NAME: thread/sql/main
                    TYPE: BACKGROUND
          PROCESSLIST_ID: NULL
        PROCESSLIST_USER: NULL
        PROCESSLIST_HOST: NULL
          PROCESSLIST_DB: NULL
     PROCESSLIST_COMMAND: NULL
        PROCESSLIST_TIME: 80284
       PROCESSLIST_STATE: NULL
        PROCESSLIST_INFO: NULL
        PARENT_THREAD_ID: NULL
                    ROLE: NULL
            INSTRUMENTED: YES
                 HISTORY: YES
         CONNECTION_TYPE: NULL
            THREAD_OS_ID: 489803
     ...
     *************************** 4. row ***************************
               THREAD_ID: 51
                    NAME: thread/sql/one_connection
                    TYPE: FOREGROUND
          PROCESSLIST_ID: 34
        PROCESSLIST_USER: isabella
        PROCESSLIST_HOST: localhost
          PROCESSLIST_DB: performance_schema
     PROCESSLIST_COMMAND: Query
        PROCESSLIST_TIME: 0
       PROCESSLIST_STATE: Sending data
        PROCESSLIST_INFO: SELECT * FROM threads
        PARENT_THREAD_ID: 1
                    ROLE: NULL
            INSTRUMENTED: YES
                 HISTORY: YES
         CONNECTION_TYPE: SSL/TLS
            THREAD_OS_ID: 755399
     ...

When the Performance Schema initializes, it populates the
'threads' table based on the threads in existence then.
Thereafter, a new row is added each time the server creates a thread.

The 'INSTRUMENTED' and 'HISTORY' column values for new threads are
determined by the contents of the 'setup_actors'
table.  For information about how to use the
'setup_actors' table to control these columns, see
performance-schema-thread-filtering.

Removal of rows from the 'threads' table occurs
when threads end.  For a thread associated with a client session,
removal occurs when the session ends.  If a client has auto-reconnect
enabled and the session reconnects after a disconnect, the session
becomes associated with a new row in the 'threads'.
table that has a different 'PROCESSLIST_ID' value.  The initial
'INSTRUMENTED' and 'HISTORY' values for the new thread may be different
from those of the original thread: The 'setup_actors'
table may have changed in the meantime, and if the
'INSTRUMENTED' or 'HISTORY' value for the original thread was changed
after the row was initialized, the change does not carry over to the new
thread.

The 'threads' table columns with names having a
prefix of 'PROCESSLIST_' provide information similar to that available
from the 'INFORMATION_SCHEMA.PROCESSLIST'.
table or the 'SHOW PROCESSLIST' statement.
Thus, all three sources provide thread-monitoring information.  Use of
'threads' differs from use of the other two
sources in these ways:

   * Access to 'threads' does not require a mutex
     and has minimal impact on server performance.
     'INFORMATION_SCHEMA.PROCESSLIST' and
     'SHOW PROCESSLIST' have negative performance
     consequences because they require a mutex.

   * 'threads' provides additional information for
     each thread, such as whether it is a foreground or background
     thread, and the location within the server associated with the
     thread.

   * 'threads' provides information about
     background threads, so it can be used to monitor activity the other
     thread information sources cannot.

   * You can enable or disable thread monitoring (that is, whether
     events executed by the thread are instrumented) and historical
     event logging.  To control the initial 'INSTRUMENTED' and 'HISTORY'
     values for new foreground threads, use the 'setup_actors'
     table.  To control these aspects of existing
     threads, set the 'INSTRUMENTED' and 'HISTORY' columns of
     'threads' table rows.  (For more information about
     the conditions under which thread monitoring and historical event
     logging occur, see the descriptions of the 'INSTRUMENTED' and
     'HISTORY' columns.)

For these reasons, DBAs who perform server monitoring using
'INFORMATION_SCHEMA.PROCESSLIST' or 'SHOW PROCESSLIST'
may wish to monitor using the
'threads' table instead.

*Note*:

For 'INFORMATION_SCHEMA.PROCESSLIST' and
'SHOW PROCESSLIST', information about threads for
other users is shown only if the current user has the 'PROCESS'
privilege.  That is not true of the 'threads'.
table; all rows are shown to any user who has the 'SELECT' privilege for
the table.  Users who should not be able to see threads for other users
should not be given that privilege.

The 'threads' table has these columns:

   * 'THREAD_ID'

     A unique thread identifier.

   * 'NAME'

     The name associated with the thread instrumentation code in the
     server.  For example, 'thread/sql/one_connection' corresponds to
     the thread function in the code responsible for handling a user
     connection, and 'thread/sql/main' stands for the 'main()' function
     of the server.

   * 'TYPE'

     The thread type, either 'FOREGROUND' or 'BACKGROUND'.  User
     connection threads are foreground threads.  Threads associated with
     internal server activity are background threads.  Examples are
     internal 'InnoDB' threads, 'binlog dump' threads sending
     information to slaves, and slave I/O and SQL threads.

   * 'PROCESSLIST_ID'

     For threads that are displayed in the
     'INFORMATION_SCHEMA.PROCESSLIST' table, this is
     the same value displayed in the 'ID' column of that table.  It is
     also the value displayed in the 'Id' column of 'SHOW PROCESSLIST'
     output, and the value that
     'CONNECTION_ID()' would return within that thread.

     For background threads (threads not associated with a user
     connection), 'PROCESSLIST_ID' is 'NULL', so the values are not
     unique.

   * 'PROCESSLIST_USER'

     The user associated with a foreground thread, 'NULL' for a
     background thread.

   * 'PROCESSLIST_HOST'

     The host name of the client associated with a foreground thread,
     'NULL' for a background thread.

     Unlike the 'HOST' column of the 'INFORMATION_SCHEMA'
     'PROCESSLIST' table or the 'Host' column of
     'SHOW PROCESSLIST' output, the
     'PROCESSLIST_HOST' column does not include the port number for
     TCP/IP connections.  To obtain this information from the
     Performance Schema, enable the socket instrumentation (which is not
     enabled by default) and examine the 'socket_instances'
     table:

          mysql> SELECT * FROM setup_instruments WHERE NAME LIKE 'wait/io/socket%';
          +----------------------------------------+---------+-------+
          | NAME                                   | ENABLED | TIMED |
          +----------------------------------------+---------+-------+
          | wait/io/socket/sql/server_tcpip_socket | NO      | NO    |
          | wait/io/socket/sql/server_unix_socket  | NO      | NO    |
          | wait/io/socket/sql/client_connection   | NO      | NO    |
          +----------------------------------------+---------+-------+
          3 rows in set (0.01 sec)

          mysql> UPDATE setup_instruments SET ENABLED='YES' WHERE NAME LIKE 'wait/io/socket%';
          Query OK, 3 rows affected (0.00 sec)
          Rows matched: 3  Changed: 3  Warnings: 0

          mysql> SELECT * FROM socket_instances\G
          *************************** 1. row ***************************
                     EVENT_NAME: wait/io/socket/sql/client_connection
          OBJECT_INSTANCE_BEGIN: 140612577298432
                      THREAD_ID: 31
                      SOCKET_ID: 53
                             IP: ::ffff:127.0.0.1
                           PORT: 55642
                          STATE: ACTIVE
          ...

   * 'PROCESSLIST_DB'

     The default database for the thread, or 'NULL' if there is none.

   * 'PROCESSLIST_COMMAND'

     For foreground threads, the type of command the thread is executing
     on behalf of the client, or 'Sleep' if the session is idle.  For
     descriptions of thread commands, see thread-information.
     The value of this column corresponds to the 'COM_XXX' commands of
     the client/server protocol and 'Com_XXX' status variables.  See
     server-status-variables

     Background threads do not execute commands on behalf of clients, so
     this column may be 'NULL'.

   * 'PROCESSLIST_TIME'

     The time in seconds that the thread has been in its current state.

   * 'PROCESSLIST_STATE'

     An action, event, or state that indicates what the thread is doing.
     For descriptions of 'PROCESSLIST_STATE' values, see
     thread-information.  If the value if 'NULL', the thread may
     correspond to an idle client session or the work it is doing is not
     instrumented with stages.

     Most states correspond to very quick operations.  If a thread stays
     in a given state for many seconds, there might be a problem that
     bears investigation.

   * 'PROCESSLIST_INFO'

     The statement the thread is executing, or 'NULL' if it is not
     executing any statement.  The statement might be the one sent to
     the server, or an innermost statement if the statement executes
     other statements.  For example, if a 'CALL' statement executes a
     stored procedure that is executing a 'SELECT'.
     statement, the 'PROCESSLIST_INFO' value shows the 'SELECT'
     statement.

   * 'PARENT_THREAD_ID'

     If this thread is a subthread (spawned by another thread), this is
     the 'THREAD_ID' value of the spawning thread.

   * 'ROLE'

     Unused.

   * 'INSTRUMENTED'

     Whether events executed by the thread are instrumented.  The value
     is 'YES' or 'NO'.

        * For foreground threads, the initial 'INSTRUMENTED' value is
          determined by whether the user account associated with the
          thread matches any row in the 'setup_actors'
          table.  Matching is based on the values of
          the 'PROCESSLIST_USER' and 'PROCESSLIST_HOST' columns.

          If the thread spawns a subthread, matching occurs again for
          the 'threads' table row created for the
          subthread.

        * For background threads, 'INSTRUMENTED' is 'YES' by default.
          'setup_actors' is not consulted
          because there is no associated user for background threads.

        * For any thread, its 'INSTRUMENTED' value can be changed during
          the lifetime of the thread.

     For monitoring of events executed by the thread to occur, these
     things must be true:

        * The 'thread_instrumentation' consumer in the
          'setup_consumers' table must be 'YES'.

        * The 'threads.INSTRUMENTED' column must be 'YES'.

        * Monitoring occurs only for those thread events produced from
          instruments that have the 'ENABLED' column set to 'YES' in the
          'setup_instruments' table.

   * 'HISTORY'

     Whether to log historical events for the thread.  The value is
     'YES' or 'NO'.

        * For foreground threads, the initial 'HISTORY' value is
          determined by whether the user account associated with the
          thread matches any row in the 'setup_actors'
          table.  Matching is based on the values of
          the 'PROCESSLIST_USER' and 'PROCESSLIST_HOST' columns.

          If the thread spawns a subthread, matching occurs again for
          the 'threads' table row created for the
          subthread.

        * For background threads, 'HISTORY' is 'YES' by default.
          'setup_actors' is not consulted because
          there is no associated user for background threads.

        * For any thread, its 'HISTORY' value can be changed during the
          lifetime of the thread.

     For historical event logging for the thread to occur, these things
     must be true:

        * The appropriate history-related consumers in the
          'setup_consumers' table must be
          enabled.  For example, wait event logging in the
          'events_waits_history' and
          'events_waits_history_long'.
          tables requires the corresponding 'events_waits_history' and
          'events_waits_history_long' consumers to be 'YES'.

        * The 'threads.HISTORY' column must be 'YES'.

        * Logging occurs only for those thread events produced from
          instruments that have the 'ENABLED' column set to 'YES' in the
          'setup_instruments' table.

   * 'CONNECTION_TYPE'

     The protocol used to establish the connection, or 'NULL' for
     background threads.  Permitted values are 'TCP/IP' (TCP/IP
     connection established without encryption), 'SSL/TLS' (TCP/IP
     connection established with encryption), 'Socket' (Unix socket file
     connection), 'Named Pipe' (Windows named pipe connection), and
     'Shared Memory' (Windows shared memory connection).

   * 'THREAD_OS_ID'

     The thread or task identifier as defined by the underlying
     operating system, if there is one:

        * When a MySQL thread is associated with the same operating
          system thread for its lifetime, 'THREAD_OS_ID' contains the
          operating system thread ID.

        * When a MySQL thread is not associated with the same operating
          system thread for its lifetime, 'THREAD_OS_ID' contains
          'NULL'.  This is typical for user sessions when the thread
          pool plugin is used (see thread-pool).

     For Windows, 'THREAD_OS_ID' corresponds to the thread ID visible in
     Process Explorer
     (<https://technet.microsoft.com/en-us/sysinternals/bb896653.aspx>).

     For Linux, 'THREAD_OS_ID' corresponds to the value of the
     'gettid()' function.  This value is exposed, for example, using the
     'perf' or 'ps -L' commands, or in the 'proc' file system
     ('/proc/[PID]/task/[TID]').  For more information, see the
     'perf-stat(1)', 'ps(1)', and 'proc(5)' man pages.

'TRUNCATE TABLE' is not permitted for the
'threads' table.

25.12 Performance Schema Option and Variable Reference
======================================================

*Performance Schema Variable Reference*

Name           Cmd-Line    Option      System      Status      Var Scope   Dynamic
                           File        Var         Var

performance_schemaYes      Yes         Yes                     Global      No

Performance_schema_accounts_lost                   Yes         Global      No

performance_schema_accounts_sizeYesYes Yes                     Global      No

Performance_schema_cond_classes_lost               Yes         Global      No

Performance_schema_cond_instances_lost             Yes         Global      No

performance-schema-consumer-events-stages-currentYesYes

performance-schema-consumer-events-stages-historyYesYes

performance-schema-consumer-events-stages-history-longYesYes

performance-schema-consumer-events-statements-currentYesYes

performance-schema-consumer-events-statements-historyYesYes

performance-schema-consumer-events-statements-history-longYesYes

performance-schema-consumer-events-transactions-currentYesYes

performance-schema-consumer-events-transactions-historyYesYes

performance-schema-consumer-events-transactions-history-longYesYes

performance-schema-consumer-events-waits-currentYesYes

performance-schema-consumer-events-waits-historyYesYes

performance-schema-consumer-events-waits-history-longYesYes

performance-schema-consumer-global-instrumentationYesYes

performance-schema-consumer-statements-digestYesYes

performance-schema-consumer-thread-instrumentationYesYes

Performance_schema_digest_lost                     Yes         Global      No

performance_schema_digests_sizeYesYes  Yes                     Global      No

performance_schema_events_stages_history_long_sizeYesYesYes    Global      No

performance_schema_events_stages_history_sizeYesYesYes         Global      No

performance_schema_events_statements_history_long_sizeYesYesYesGlobal      No

performance_schema_events_statements_history_sizeYesYesYes     Global      No

performance_schema_events_transactions_history_long_sizeYesYesYesGlobal    No

performance_schema_events_transactions_history_sizeYesYesYes   Global      No

performance_schema_events_waits_history_long_sizeYesYesYes     Global      No

performance_schema_events_waits_history_sizeYesYesYes          Global      No

Performance_schema_file_classes_lost               Yes         Global      No

Performance_schema_file_handles_lost               Yes         Global      No

Performance_schema_file_instances_lost             Yes         Global      No

Performance_schema_hosts_lost                      Yes         Global      No

performance_schema_hosts_sizeYesYes    Yes                     Global      No

performance-schema-instrumentYesYes

Performance_schema_locker_lost                     Yes         Global      No

performance_schema_max_cond_classesYesYesYes                   Global      No

performance_schema_max_cond_instancesYesYesYes                 Global      No

performance_schema_max_digest_lengthYesYesYes                  Global      No

performance_schema_max_file_classesYesYesYes                   Global      No

performance_schema_max_file_handlesYesYesYes                   Global      No

performance_schema_max_file_instancesYesYesYes                 Global      No

performance_schema_max_memory_classesYesYesYes                 Global      No

performance_schema_max_metadata_locksYesYesYes                 Global      No

performance_schema_max_mutex_classesYesYesYes                  Global      No

performance_schema_max_mutex_instancesYesYesYes                Global      No

performance_schema_max_prepared_statements_instancesYesYesYes  Global      No

performance_schema_max_program_instancesYesYesYes              Global      No

performance_schema_max_rwlock_classesYesYesYes                 Global      No

performance_schema_max_rwlock_instancesYesYesYes               Global      No

performance_schema_max_socket_classesYesYesYes                 Global      No

performance_schema_max_socket_instancesYesYesYes               Global      No

performance_schema_max_stage_classesYesYesYes                  Global      No

performance_schema_max_statement_classesYesYesYes              Global      No

performance_schema_max_statement_stackYesYesYes                Global      No

performance_schema_max_table_handlesYesYesYes                  Global      No

performance_schema_max_table_instancesYesYesYes                Global      No

performance_schema_max_thread_classesYesYesYes                 Global      No

performance_schema_max_thread_instancesYesYesYes               Global      No

Performance_schema_memory_classes_lost             Yes         Global      No

Performance_schema_metadata_lock_lost              Yes         Global      No

Performance_schema_mutex_classes_lost              Yes         Global      No

Performance_schema_mutex_instances_lost            Yes         Global      No

Performance_schema_nested_statement_lost           Yes         Global      No

Performance_schema_prepared_statements_lost        Yes         Global      No

Performance_schema_program_lost                    Yes         Global      No

Performance_schema_rwlock_classes_lost             Yes         Global      No

Performance_schema_rwlock_instances_lost           Yes         Global      No

Performance_schema_session_connect_attrs_lost      Yes         Global      No

performance_schema_session_connect_attrs_sizeYesYesYes         Global      No

performance_schema_setup_actors_sizeYesYesYes                  Global      No

performance_schema_setup_objects_sizeYesYesYes                 Global      No

Performance_schema_socket_classes_lost             Yes         Global      No

Performance_schema_socket_instances_lost           Yes         Global      No

Performance_schema_stage_classes_lost              Yes         Global      No

Performance_schema_statement_classes_lost          Yes         Global      No

Performance_schema_table_handles_lost              Yes         Global      No

Performance_schema_table_instances_lost            Yes         Global      No

Performance_schema_thread_classes_lost             Yes         Global      No

Performance_schema_thread_instances_lost           Yes         Global      No

Performance_schema_users_lost                      Yes         Global      No

performance_schema_users_sizeYesYes    Yes                     Global      No

25.13 Performance Schema Command Options
========================================

Performance Schema parameters can be specified at server startup on the
command line or in option files to configure Performance Schema
instruments and consumers.  Runtime configuration is also possible in
many cases (see performance-schema-runtime-configuration), but
startup configuration must be used when runtime configuration is too
late to affect instruments that have already been initialized during the
startup process.

Performance Schema consumers and instruments can be configured at
startup using the following syntax.  For additional details, see
performance-schema-startup-configuration.

   *
     '--performance-schema-consumer-CONSUMER_NAME=value'

     Configure a Performance Schema consumer.  Consumer names in the
     'setup_consumers' table use
     underscores, but for consumers set at startup, dashes and
     underscores within the name are equivalent.  Options for
     configuring individual consumers are detailed later in this
     section.

   *
     '--performance-schema-instrument=INSTRUMENT_NAME=value'

     Configure a Performance Schema instrument.  The name may be given
     as a pattern to configure instruments that match the pattern.

The following items configure individual consumers:

   *
     '--performance-schema-consumer-events-stages-current=value'

     Configure the 'events-stages-current' consumer.

   *
     '--performance-schema-consumer-events-stages-history=value'

     Configure the 'events-stages-history' consumer.

   *
     '--performance-schema-consumer-events-stages-history-long=value'

     Configure the 'events-stages-history-long' consumer.

   *
     '--performance-schema-consumer-events-statements-current=value'

     Configure the 'events-statements-current' consumer.

   *
     '--performance-schema-consumer-events-statements-history=value'

     Configure the 'events-statements-history' consumer.

   *
     '--performance-schema-consumer-events-statements-history-long=value'

     Configure the 'events-statements-history-long' consumer.

   *
     '--performance-schema-consumer-events-transactions-current=value'

     Configure the Performance Schema 'events-transactions-current'
     consumer.

   *
     '--performance-schema-consumer-events-transactions-history=value'

     Configure the Performance Schema 'events-transactions-history'
     consumer.

   *
     '--performance-schema-consumer-events-transactions-history-long=value'

     Configure the Performance Schema 'events-transactions-history-long'
     consumer.

   *
     '--performance-schema-consumer-events-waits-current=value'

     Configure the 'events-waits-current' consumer.

   *
     '--performance-schema-consumer-events-waits-history=value'

     Configure the 'events-waits-history' consumer.

   *
     '--performance-schema-consumer-events-waits-history-long=value'

     Configure the 'events-waits-history-long' consumer.

   *
     '--performance-schema-consumer-global-instrumentation=value'

     Configure the 'global-instrumentation' consumer.

   *
     '--performance-schema-consumer-statements-digest=value'

     Configure the 'statements-digest' consumer.

   *
     '--performance-schema-consumer-thread-instrumentation=value'

     Configure the 'thread-instrumentation' consumer.

25.14 Performance Schema System Variables
=========================================

The Performance Schema implements several system variables that provide
configuration information:

     mysql> SHOW VARIABLES LIKE 'perf%';
     +----------------------------------------------------------+-------+
     | Variable_name                                            | Value |
     +----------------------------------------------------------+-------+
     | performance_schema                                       | ON    |
     | performance_schema_accounts_size                         | -1    |
     | performance_schema_digests_size                          | 10000 |
     | performance_schema_events_stages_history_long_size       | 10000 |
     | performance_schema_events_stages_history_size            | 10    |
     | performance_schema_events_statements_history_long_size   | 10000 |
     | performance_schema_events_statements_history_size        | 10    |
     | performance_schema_events_transactions_history_long_size | 10000 |
     | performance_schema_events_transactions_history_size      | 10    |
     | performance_schema_events_waits_history_long_size        | 10000 |
     | performance_schema_events_waits_history_size             | 10    |
     | performance_schema_hosts_size                            | -1    |
     | performance_schema_max_cond_classes                      | 80    |
     | performance_schema_max_cond_instances                    | -1    |
     | performance_schema_max_digest_length                     | 1024  |
     | performance_schema_max_file_classes                      | 50    |
     | performance_schema_max_file_handles                      | 32768 |
     | performance_schema_max_file_instances                    | -1    |
     | performance_schema_max_index_stat                        | -1    |
     | performance_schema_max_memory_classes                    | 320   |
     | performance_schema_max_metadata_locks                    | -1    |
     | performance_schema_max_mutex_classes                     | 200   |
     | performance_schema_max_mutex_instances                   | -1    |
     | performance_schema_max_prepared_statements_instances     | -1    |
     | performance_schema_max_program_instances                 | -1    |
     | performance_schema_max_rwlock_classes                    | 40    |
     | performance_schema_max_rwlock_instances                  | -1    |
     | performance_schema_max_socket_classes                    | 10    |
     | performance_schema_max_socket_instances                  | -1    |
     | performance_schema_max_sql_text_length                   | 1024  |
     | performance_schema_max_stage_classes                     | 150   |
     | performance_schema_max_statement_classes                 | 192   |
     | performance_schema_max_statement_stack                   | 10    |
     | performance_schema_max_table_handles                     | -1    |
     | performance_schema_max_table_instances                   | -1    |
     | performance_schema_max_table_lock_stat                   | -1    |
     | performance_schema_max_thread_classes                    | 50    |
     | performance_schema_max_thread_instances                  | -1    |
     | performance_schema_session_connect_attrs_size            | 512   |
     | performance_schema_setup_actors_size                     | -1    |
     | performance_schema_setup_objects_size                    | -1    |
     | performance_schema_users_size                            | -1    |
     +----------------------------------------------------------+-------+

Performance Schema system variables can be set at server startup on the
command line or in option files, and many can be set at runtime.  See
performance-schema-option-variable-reference.

The Performance Schema automatically sizes the values of several of its
parameters at server startup if they are not set explicitly.  For more
information, see performance-schema-startup-configuration.

Performance Schema system variables have the following meanings:

   *
     'performance_schema'

     Property                             Value

     *Command-Line Format*                '--performance-schema=#'

     *System Variable*                    'performance_schema'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               boolean

     *Default Value*                      'ON'

     The value of this variable is 'ON' or 'OFF' to indicate whether the
     Performance Schema is enabled.  By default, the value is 'ON'.  At
     server startup, you can specify this variable with no value or a
     value of 'ON' or 1 to enable it, or with a value of 'OFF' or 0 to
     disable it.

     Even when the Performance Schema is disabled, it continues to
     populate the 'global_variables',
     see
     'session_variables',
     'global_status',
     and 'session_status'
     tables.  This occurs as
     necessary to permit the results for the 'SHOW VARIABLES'
     and 'SHOW STATUS' statements to
     be drawn from those tables, depending on the setting of the
     'show_compatibiliy_56' system variable.

   *
     'performance_schema_accounts_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-accounts-size=#'

     *System Variable*                    'performance_schema_accounts_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     *Minimum Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Minimum Value* (<= 5.7.5)           '-1 (autosized)'

     *Maximum Value*                      '1048576'

     The number of rows in the 'accounts' table.
     If this variable is 0, the Performance Schema does not maintain
     connection statistics in the 'accounts'.
     table or status variable information in the
     'status_by_account'
     table.

   *
     'performance_schema_digests_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-digests-size=#'

     *System Variable*                    'performance_schema_digests_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     *Minimum Value*                      '-1'

     *Maximum Value*                      '1048576'

     The maximum number of rows in the
     'events_statements_summary_by_digest'.
     table.  If this maximum is exceeded such that a digest cannot be
     instrumented, the Performance Schema increments the
     'Performance_schema_digest_lost' status variable.

     For more information about statement digesting, see
     performance-schema-statement-digests.

   *
     'performance_schema_events_stages_history_long_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-stages-history-long-size=#'

     *System Variable*                    'performance_schema_events_stages_history_long_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows in the 'events_stages_history_long'
     table.

   *
     'performance_schema_events_stages_history_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-stages-history-size=#'

     *System Variable*                    'performance_schema_events_stages_history_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows per thread in the 'events_stages_history'
     table.

   *
     'performance_schema_events_statements_history_long_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-statements-history-long-size=#'

     *System Variable*                    'performance_schema_events_statements_history_long_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows in the 'events_statements_history_long'
     table.

   *
     'performance_schema_events_statements_history_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-statements-history-size=#'

     *System Variable*                    'performance_schema_events_statements_history_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows per thread in the
     'events_statements_history'.
     table.

   *
     'performance_schema_events_transactions_history_long_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-transactions-history-long-size=#'

     *Introduced*                         5.7.3

     *System Variable*                    'performance_schema_events_transactions_history_long_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows in the 'events_transactions_history_long'
     table.

   *
     'performance_schema_events_transactions_history_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-transactions-history-size=#'

     *Introduced*                         5.7.3

     *System Variable*                    'performance_schema_events_transactions_history_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows per thread in the
     'events_transactions_history'.
     table.

   *
     'performance_schema_events_waits_history_long_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-waits-history-long-size=#'

     *System Variable*                    'performance_schema_events_waits_history_long_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows in the 'events_waits_history_long'
     table.

   *
     'performance_schema_events_waits_history_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-events-waits-history-size=#'

     *System Variable*                    'performance_schema_events_waits_history_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The number of rows per thread in the 'events_waits_history'
     table.

   *
     'performance_schema_hosts_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-hosts-size=#'

     *System Variable*                    'performance_schema_hosts_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     *Minimum Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Minimum Value* (<= 5.7.5)           '-1 (autosized)'

     *Maximum Value*                      '1048576'

     The number of rows in the 'hosts' table.  If
     this variable is 0, the Performance Schema does not maintain
     connection statistics in the 'hosts' table or
     status variable information in the 'status_by_host'
     table.

   *
     'performance_schema_max_cond_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-cond-classes=#'

     *System Variable*                    'performance_schema_max_cond_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '80'

     *Minimum Value*                      '0'

     *Maximum Value*                      '256'

     The maximum number of condition instruments.

   *
     'performance_schema_max_cond_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-cond-instances=#'

     *System Variable*                    'performance_schema_max_cond_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of instrumented condition objects.

   *
     'performance_schema_max_digest_length'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-digest-length=#'

     *Introduced*                         5.7.8

     *System Variable*                    'performance_schema_max_digest_length'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1048576'

     The maximum number of bytes available for storage of normalized
     statement digest values in the Performance Schema.  This variable
     is related to 'max_digest_length'; see the description of that
     variable in server-system-variables

     For more information about statement digesting, see
     performance-schema-statement-digests.

   *
     'performance_schema_max_file_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-file-classes=#'

     *System Variable*                    'performance_schema_max_file_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.9)           '80'

     *Default Value* (<= 5.7.8)           '50'

     *Minimum Value*                      '0'

     *Maximum Value*                      '256'

     The maximum number of file instruments.

   *
     'performance_schema_max_file_handles'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-file-handles=#'

     *System Variable*                    'performance_schema_max_file_handles'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '32768'

     The maximum number of opened file objects.

     The value of 'performance_schema_max_file_handles' should be
     greater than the value of 'open_files_limit': 'open_files_limit'
     affects the maximum number of open file handles the server can
     support and 'performance_schema_max_file_handles' affects how many
     of these file handles can be instrumented.

   *
     'performance_schema_max_file_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-file-instances=#'

     *System Variable*                    'performance_schema_max_file_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of instrumented file objects.

   *
     'performance_schema_max_index_stat'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-index-stat=#'

     *Introduced*                         5.7.6

     *System Variable*                    'performance_schema_max_index_stat'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The maximum number of indexes for which the Performance Schema
     maintains statistics.  If this maximum is exceeded such that index
     statistics are lost, the Performance Schema increments the
     'Performance_schema_index_stat_lost' status variable.  The default
     value is autosized using the value of
     'performance_schema_max_table_instances'.

   *
     'performance_schema_max_memory_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-memory-classes=#'

     *Introduced*                         5.7.2

     *System Variable*                    'performance_schema_max_memory_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.5)           '320'

     *Default Value* (<= 5.7.4)           '250'

     The maximum number of memory instruments.

   *
     'performance_schema_max_metadata_locks'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-metadata-locks=#'

     *Introduced*                         5.7.3

     *System Variable*                    'performance_schema_max_metadata_locks'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of metadata lock instruments.  This value
     controls the size of the 'metadata_locks'
     table.  If this maximum is exceeded such that
     a metadata lock cannot be instrumented, the Performance Schema
     increments the 'Performance_schema_metadata_lock_lost' status
     variable.

   *
     'performance_schema_max_mutex_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-mutex-classes=#'

     *System Variable*                    'performance_schema_max_mutex_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '200'

     *Minimum Value*                      '0'

     *Maximum Value*                      '256'

     The maximum number of mutex instruments.

   *
     'performance_schema_max_mutex_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-mutex-instances=#'

     *System Variable*                    'performance_schema_max_mutex_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of instrumented mutex objects.

   *
     'performance_schema_max_prepared_statements_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-prepared-statements-instances=#'

     *Introduced*                         5.7.4

     *System Variable*                    'performance_schema_max_prepared_statements_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of rows in the
     'prepared_statements_instances'
     table.  If this maximum is
     exceeded such that a prepared statement cannot be instrumented, the
     Performance Schema increments the
     'Performance_schema_prepared_statements_lost' status variable.  The
     default value of this variable is autosized based on the value of
     the 'max_prepared_stmt_count' system variable.

   *
     'performance_schema_max_rwlock_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-rwlock-classes=#'

     *System Variable*                    'performance_schema_max_rwlock_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.3)           '40'

     *Default Value* (<= 5.7.2)           '30'

     *Minimum Value*                      '0'

     *Maximum Value*                      '256'

     The maximum number of rwlock instruments.

   *
     'performance_schema_max_program_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-program-instances=#'

     *Introduced*                         5.7.2

     *System Variable*                    'performance_schema_max_program_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '5000'

     The maximum number of stored programs for which the Performance
     Schema maintains statistics.  If this maximum is exceeded, the
     Performance Schema increments the 'Performance_schema_program_lost'
     status variable.

   *
     'performance_schema_max_rwlock_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-rwlock-instances=#'

     *System Variable*                    'performance_schema_max_rwlock_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of instrumented rwlock objects.

   *
     'performance_schema_max_socket_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-socket-classes=#'

     *System Variable*                    'performance_schema_max_socket_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '10'

     *Minimum Value*                      '0'

     *Maximum Value*                      '256'

     The maximum number of socket instruments.

   *
     'performance_schema_max_socket_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-socket-instances=#'

     *System Variable*                    'performance_schema_max_socket_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of instrumented socket objects.

   *
     'performance_schema_max_sql_text_length'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-sql-text-length=#'

     *Introduced*                         5.7.6

     *System Variable*                    'performance_schema_max_sql_text_length'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '1024'

     *Minimum Value*                      '0'

     *Maximum Value*                      '1048576'

     The maximum number of bytes used to store SQL statements in the
     'SQL_TEXT' column of the 'events_statements_current',
     see 'events_statements_history',
     and
     'events_statements_history_long'
     statement event tables.  Any
     bytes in excess of 'performance_schema_max_sql_text_length' are
     discarded and do not appear in the 'SQL_TEXT' column.  Statements
     differing only after that many initial bytes are indistinguishable
     in this column.

     Decreasing the 'performance_schema_max_sql_text_length' value
     reduces memory use but causes more statements to become
     indistinguishable if they differ only at the end.  Increasing the
     value increases memory use but permits longer statements to be
     distinguished.

   *
     'performance_schema_max_stage_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-stage-classes=#'

     *System Variable*                    'performance_schema_max_stage_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '150'

     *Minimum Value*                      '0'

     *Maximum Value*                      '256'

     The maximum number of stage instruments.

   *
     'performance_schema_max_statement_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-statement-classes=#'

     *System Variable*                    'performance_schema_max_statement_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The maximum number of statement instruments.  The default value is
     calculated at server build time based on the number of commands in
     the client/server protocol and the number of SQL statement types
     supported by the server.

     This variable should not be changed, unless to set it to 0 to
     disable all statement instrumentation and save all memory
     associated with it.  Setting the variable to nonzero values other
     than the default has no benefit; in particular, values larger than
     the default cause more memory to be allocated then is needed.

   *
     'performance_schema_max_statement_stack'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-statement-stack=#'

     *Introduced*                         5.7.2

     *System Variable*                    'performance_schema_max_statement_stack'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '10'

     The maximum depth of nested stored program calls for which the
     Performance Schema maintains statistics.  When this maximum is
     exceeded, the Performance Schema increments the
     'Performance_schema_nested_statement_lost' status variable for each
     stored program statement executed.

   *
     'performance_schema_max_table_handles'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-table-handles=#'

     *System Variable*                    'performance_schema_max_table_handles'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of opened table objects.  This value controls
     the size of the 'table_handles' table.
     If this maximum is exceeded such that a table handle cannot be
     instrumented, the Performance Schema increments the
     'Performance_schema_table_handles_lost' status variable.

   *
     'performance_schema_max_table_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-table-instances=#'

     *System Variable*                    'performance_schema_max_table_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of instrumented table objects.

   *
     'performance_schema_max_table_lock_stat'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-table-lock-stat=#'

     *Introduced*                         5.7.6

     *System Variable*                    'performance_schema_max_table_lock_stat'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     The maximum number of tables for which the Performance Schema
     maintains lock statistics.  If this maximum is exceeded such that
     table lock statistics are lost, the Performance Schema increments
     the 'Performance_schema_table_lock_stat_lost' status variable.

   *
     'performance_schema_max_thread_classes'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-thread-classes=#'

     *System Variable*                    'performance_schema_max_thread_classes'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '50'

     *Minimum Value*                      '0'

     *Maximum Value*                      '256'

     The maximum number of thread instruments.

   *
     'performance_schema_max_thread_instances'

     Property                             Value

     *Command-Line Format*                '--performance-schema-max-thread-instances=#'

     *System Variable*                    'performance_schema_max_thread_instances'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     The maximum number of instrumented thread objects.  The value
     controls the size of the 'threads' table.  If
     this maximum is exceeded such that a thread cannot be instrumented,
     the Performance Schema increments the
     'Performance_schema_thread_instances_lost' status variable.

     The 'max_connections' system variable affects how many threads can
     run in the server.  'performance_schema_max_thread_instances'
     affects how many of these running threads can be instrumented.

     The 'variables_by_thread'
     and
     'status_by_thread'.
     tables contain system and status variable information information
     only about foreground threads.  If not all threads are instrumented
     by the Performance Schema, this table will miss some rows.  In this
     case, the 'Performance_schema_thread_instances_lost' status
     variable will be greater than zero.

   *
     'performance_schema_session_connect_attrs_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-session-connect-attrs-size=#'

     *System Variable*                    'performance_schema_session_connect_attrs_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value*                      '-1 (autosized)'

     *Minimum Value*                      '-1'

     *Maximum Value*                      '1048576'

     The amount of preallocated memory per thread reserved to hold
     connection attribute key/value pairs.  If the aggregate size of
     connection attribute data sent by a client is larger than this
     amount, the Performance Schema truncates the attribute data,
     increments the 'Performance_schema_session_connect_attrs_lost'
     status variable, and writes a message to the error log indicating
     that truncation occurred if the 'log_error_verbosity' system
     variable value is greater than 1.

     The default value of
     'performance_schema_session_connect_attrs_size' is autosized at
     server startup.  This value may be small, so if truncation occurs
     ('Performance_schema_session_connect_attrs_lost' becomes nonzero),
     you may wish to set 'performance_schema_session_connect_attrs_size'
     explicitly to a larger value.

     Although the maximum permitted
     'performance_schema_session_connect_attrs_size' value is 1MB, the
     effective maximum is 64KB because the server imposes a limit of
     64KB on the aggregate size of connection attribute data it will
     accept.  If a client attempts to send more than 64KB of attribute
     data, the server rejects the connection.  For more information, see
     performance-schema-connection-attribute-tables.

   *
     'performance_schema_setup_actors_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-setup-actors-size=#'

     *System Variable*                    'performance_schema_setup_actors_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '100'

     The number of rows in the 'setup_actors'.
     table.

   *
     'performance_schema_setup_objects_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-setup-objects-size=#'

     *System Variable*                    'performance_schema_setup_objects_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '100'

     The number of rows in the 'setup_objects'
     table.

   *
     'performance_schema_users_size'

     Property                             Value

     *Command-Line Format*                '--performance-schema-users-size=#'

     *System Variable*                    'performance_schema_users_size'

     *Scope*                              Global

     *Dynamic*                            No

     *Type*                               integer

     *Default Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Default Value* (<= 5.7.5)           '-1 (autosized)'

     *Minimum Value* (>= 5.7.6)           '-1 (autoscaled)'

     *Minimum Value* (<= 5.7.5)           '-1 (autosized)'

     *Maximum Value*                      '1048576'

     The number of rows in the 'users' table.  If
     this variable is 0, the Performance Schema does not maintain
     connection statistics in the 'users' table or
     status variable information in the 'status_by_user'
     table.

25.15 Performance Schema Status Variables
=========================================

The Performance Schema implements several status variables that provide
information about instrumentation that could not be loaded or created
due to memory constraints:

     mysql> SHOW STATUS LIKE 'perf%';
     +-------------------------------------------+-------+
     | Variable_name                             | Value |
     +-------------------------------------------+-------+
     | Performance_schema_accounts_lost          | 0     |
     | Performance_schema_cond_classes_lost      | 0     |
     | Performance_schema_cond_instances_lost    | 0     |
     | Performance_schema_file_classes_lost      | 0     |
     | Performance_schema_file_handles_lost      | 0     |
     | Performance_schema_file_instances_lost    | 0     |
     | Performance_schema_hosts_lost             | 0     |
     | Performance_schema_locker_lost            | 0     |
     | Performance_schema_mutex_classes_lost     | 0     |
     | Performance_schema_mutex_instances_lost   | 0     |
     | Performance_schema_rwlock_classes_lost    | 0     |
     | Performance_schema_rwlock_instances_lost  | 0     |
     | Performance_schema_socket_classes_lost    | 0     |
     | Performance_schema_socket_instances_lost  | 0     |
     | Performance_schema_stage_classes_lost     | 0     |
     | Performance_schema_statement_classes_lost | 0     |
     | Performance_schema_table_handles_lost     | 0     |
     | Performance_schema_table_instances_lost   | 0     |
     | Performance_schema_thread_classes_lost    | 0     |
     | Performance_schema_thread_instances_lost  | 0     |
     | Performance_schema_users_lost             | 0     |
     +-------------------------------------------+-------+

Performance Schema status variables have the following meanings:

   *
     'Performance_schema_accounts_lost'

     The number of times a row could not be added to the
     'accounts' table because it was full.

   *
     'Performance_schema_cond_classes_lost'

     How many condition instruments could not be loaded.

   *
     'Performance_schema_cond_instances_lost'

     How many condition instrument instances could not be created.

   *
     'Performance_schema_digest_lost'

     The number of digest instances that could not be instrumented in
     the 'events_statements_summary_by_digest'
     table.  This can be nonzero if the value
     of 'performance_schema_digests_size' is too small.

   *
     'Performance_schema_file_classes_lost'

     How many file instruments could not be loaded.

   *
     'Performance_schema_file_handles_lost'

     How many file instrument instances could not be opened.

   *
     'Performance_schema_file_instances_lost'

     How many file instrument instances could not be created.

   *
     'Performance_schema_hosts_lost'

     The number of times a row could not be added to the 'hosts'
     table because it was full.

   *
     'Performance_schema_index_stat_lost'

     The number of indexes for which statistics were lost.  This can be
     nonzero if the value of 'performance_schema_max_index_stat' is too
     small.

   *
     'Performance_schema_locker_lost'

     How many events are 'lost' or not recorded, due to the following
     conditions:

        * Events are recursive (for example, waiting for A caused a wait
          on B, which caused a wait on C).

        * The depth of the nested events stack is greater than the limit
          imposed by the implementation.

     Events recorded by the Performance Schema are not recursive, so
     this variable should always be 0.

   *
     'Performance_schema_memory_classes_lost'

     The number of times a memory instrument could not be loaded.

   *
     'Performance_schema_metadata_lock_lost'

     The number of metadata locks that could not be instrumented in the
     'metadata_locks' table.  This can be
     nonzero if the value of 'performance_schema_max_metadata_locks' is
     too small.

   *
     'Performance_schema_mutex_classes_lost'

     How many mutex instruments could not be loaded.

   *
     'Performance_schema_mutex_instances_lost'

     How many mutex instrument instances could not be created.

   *
     'Performance_schema_nested_statement_lost'

     The number of stored program statements for which statistics were
     lost.  This can be nonzero if the value of
     'performance_schema_max_statement_stack' is too small.

   *
     'Performance_schema_prepared_statements_lost'

     The number of prepared statements that could not be instrumented in
     the 'prepared_statements_instances'
     table.  This can be nonzero if
     the value of 'performance_schema_max_prepared_statements_instances'
     is too small.

   *
     'Performance_schema_program_lost'

     The number of stored programs for which statistics were lost.  This
     can be nonzero if the value of
     'performance_schema_max_program_instances' is too small.

   *
     'Performance_schema_rwlock_classes_lost'

     How many rwlock instruments could not be loaded.

   *
     'Performance_schema_rwlock_instances_lost'

     How many rwlock instrument instances could not be created.

   *
     'Performance_schema_session_connect_attrs_lost'

     The number of connections for which connection attribute truncation
     has occurred.  For a given connection, if the client sends
     connection attribute key/value pairs for which the aggregate size
     is larger than the reserved storage permitted by the value of the
     'performance_schema_session_connect_attrs_size' system variable,
     the Performance Schema truncates the attribute data and increments
     'Performance_schema_session_connect_attrs_lost'.  If this value is
     nonzero, you may wish to set
     'performance_schema_session_connect_attrs_size' to a larger value.

     For more information about connection attributes, see
     performance-schema-connection-attribute-tables.

   *
     'Performance_schema_socket_classes_lost'

     How many socket instruments could not be loaded.

   *
     'Performance_schema_socket_instances_lost'

     How many socket instrument instances could not be created.

   *
     'Performance_schema_stage_classes_lost'

     How many stage instruments could not be loaded.

   *
     'Performance_schema_statement_classes_lost'

     How many statement instruments could not be loaded.

   *
     'Performance_schema_table_handles_lost'

     How many table instrument instances could not be opened.  This can
     be nonzero if the value of 'performance_schema_max_table_handles'
     is too small.

   *
     'Performance_schema_table_instances_lost'

     How many table instrument instances could not be created.

   *
     'Performance_schema_table_lock_stat_lost'

     The number of tables for which lock statistics were lost.  This can
     be nonzero if the value of 'performance_schema_max_table_lock_stat'
     is too small.

   *
     'Performance_schema_thread_classes_lost'

     How many thread instruments could not be loaded.

   *
     'Performance_schema_thread_instances_lost'

     The number of thread instances that could not be instrumented in
     the 'threads' table.  This can be nonzero if
     the value of 'performance_schema_max_thread_instances' is too
     small.

   *
     'Performance_schema_users_lost'

     The number of times a row could not be added to the 'users'
     table because it was full.

For information on using these variables to check Performance Schema
status, see performance-schema-status-monitoring.

25.16 The Performance Schema Memory-Allocation Model
====================================================

The Performance Schema uses this memory allocation model:

   * May allocate memory at server startup

   * May allocate additional memory during server operation

   * Never free memory during server operation (although it might be
     recycled)

   * Free all memory used at shutdown

The result is to relax memory constraints so that the Performance Schema
can be used with less configuration, and to decrease the memory
footprint so that consumption scales with server load.  Memory used
depends on the load actually seen, not the load estimated or explicitly
configured for.

Several Performance Schema sizing parameters are autoscaled and need not
be configured explicitly unless you want to establish an explicit limit
on memory allocation:

     performance_schema_accounts_size
     performance_schema_hosts_size
     performance_schema_max_cond_instances
     performance_schema_max_file_instances
     performance_schema_max_index_stat
     performance_schema_max_metadata_locks
     performance_schema_max_mutex_instances
     performance_schema_max_prepared_statements_instances
     performance_schema_max_program_instances
     performance_schema_max_rwlock_instances
     performance_schema_max_socket_instances
     performance_schema_max_table_handles
     performance_schema_max_table_instances
     performance_schema_max_table_lock_stat
     performance_schema_max_thread_instances
     performance_schema_users_size

For an autoscaled parameter, configuration works like this:

   * With the value set to -1 (the default), the parameter is
     autoscaled:

        * The corresponding internal buffer is empty initially and no
          memory is allocated.

        * As the Performance Schema collects data, memory is allocated
          in the corresponding buffer.  The buffer size is unbounded,
          and may grow with the load.

   * With the value set to 0:

        * The corresponding internal buffer is empty initially and no
          memory is allocated.

   * With the value set to N > 0:

        * The corresponding internal buffer is empty initially and no
          memory is allocated.

        * As the Performance Schema collects data, memory is allocated
          in the corresponding buffer, until the buffer size reaches N.

        * Once the buffer size reaches N, no more memory is allocated.
          Data collected by the Performance Schema for this buffer is
          lost, and any corresponding 'lost instance' counters are
          incremented.

To see how much memory the Performance Schema is using, check the
instruments designed for that purpose.  The Performance Schema allocates
memory internally and associates each buffer with a dedicated instrument
so that memory consumption can be traced to individual buffers.
Instruments named with the prefix 'memory/performance_schema/' expose
how much memory is allocated for these internal buffers.  The buffers
are global to the server, so the instruments are displayed only in the
'memory_summary_global_by_event_name'.
table, and not in other 'memory_summary_by_XXX_by_event_name' tables.

This query shows the information associated with the memory instruments:

     SELECT * FROM memory_summary_global_by_event_name
     WHERE EVENT_NAME LIKE 'memory/performance_schema/%';

25.17 Performance Schema and Plugins
====================================

Removing a plugin with 'UNINSTALL PLUGIN' does
not affect information already collected for code in that plugin.  Time
spent executing the code while the plugin was loaded was still spent
even if the plugin is unloaded later.  The associated event information,
including aggregate information, remains readable in
'performance_schema' database tables.  For additional information about
the effect of plugin installation and removal, see
performance-schema-status-monitoring.

A plugin implementor who instruments plugin code should document its
instrumentation characteristics to enable those who load the plugin to
account for its requirements.  For example, a third-party storage engine
should include in its documentation how much memory the engine needs for
mutex and other instruments.

25.18 Using the Performance Schema to Diagnose Problems
=======================================================

The Performance Schema is a tool to help a DBA do performance tuning by
taking real measurements instead of 'wild guesses.' This section
demonstrates some ways to use the Performance Schema for this purpose.
The discussion here relies on the use of event filtering, which is
described in performance-schema-filtering.

The following example provides one methodology that you can use to
analyze a repeatable problem, such as investigating a performance
bottleneck.  To begin, you should have a repeatable use case where
performance is deemed 'too slow' and needs optimization, and you should
enable all instrumentation (no pre-filtering at all).

  1. Run the use case.

  2. Using the Performance Schema tables, analyze the root cause of the
     performance problem.  This analysis will rely heavily on
     post-filtering.

  3. For problem areas that are ruled out, disable the corresponding
     instruments.  For example, if analysis shows that the issue is not
     related to file I/O in a particular storage engine, disable the
     file I/O instruments for that engine.  Then truncate the history
     and summary tables to remove previously collected events.

  4. Repeat the process at step 1.

     At each iteration, the Performance Schema output, particularly the
     'events_waits_history_long'.
     table, will contain less and less 'noise' caused by nonsignificant
     instruments, and given that this table has a fixed size, will
     contain more and more data relevant to the analysis of the problem
     at hand.

     At each iteration, investigation should lead closer and closer to
     the root cause of the problem, as the 'signal/noise' ratio will
     improve, making analysis easier.

  5. Once a root cause of performance bottleneck is identified, take the
     appropriate corrective action, such as:

        * Tune the server parameters (cache sizes, memory, and so
          forth).

        * Tune a query by writing it differently,

        * Tune the database schema (tables, indexes, and so forth).

        * Tune the code (this applies to storage engine or server
          developers only).

  6. Start again at step 1, to see the effects of the changes on
     performance.

The 'mutex_instances.LOCKED_BY_THREAD_ID' and
'rwlock_instances.WRITE_LOCKED_BY_THREAD_ID' columns are extremely
important for investigating performance bottlenecks or deadlocks.  This
is made possible by Performance Schema instrumentation as follows:

  1. Suppose that thread 1 is stuck waiting for a mutex.

  2. You can determine what the thread is waiting for:

          SELECT * FROM events_waits_current WHERE THREAD_ID = THREAD_1;

     Say the query result identifies that the thread is waiting for
     mutex A, found in 'events_waits_current.OBJECT_INSTANCE_BEGIN'.

  3. You can determine which thread is holding mutex A:

          SELECT * FROM mutex_instances WHERE OBJECT_INSTANCE_BEGIN = MUTEX_A;

     Say the query result identifies that it is thread 2 holding mutex
     A, as found in 'mutex_instances.LOCKED_BY_THREAD_ID'.

  4. You can see what thread 2 is doing:

          SELECT * FROM events_waits_current WHERE THREAD_ID = THREAD_2;

25.18.1 Query Profiling Using Performance Schema
------------------------------------------------

The following example demonstrates how to use Performance Schema
statement events and stage events to retrieve data comparable to
profiling information provided by 'SHOW PROFILES'.
and 'SHOW PROFILE' statements.

The 'setup_actors' table can be used to limit
the collection of historical events by host, user, or account to reduce
runtime overhead and the amount of data collected in history tables.
The first step of the example shows how to limit collection of
historical events to a specific user.

Performance Schema displays event timer information in picoseconds
(trillionths of a second) to normalize timing data to a standard unit.
In the following example, 'TIMER_WAIT' values are divided by
1000000000000 to show data in units of seconds.  Values are also
truncated to 6 decimal places to display data in the same format as
'SHOW PROFILES' and 'SHOW PROFILE'
statements.

  1. Limit the collection of historical events to the user that will run
     the query.  By default, see 'setup_actors'.
     is configured to allow monitoring and historical event collection
     for all foreground threads:

          mysql> SELECT * FROM performance_schema.setup_actors;
          +------+------+------+---------+---------+
          | HOST | USER | ROLE | ENABLED | HISTORY |
          +------+------+------+---------+---------+
          | %    | %    | %    | YES     | YES     |
          +------+------+------+---------+---------+

     Update the default row in the 'setup_actors'
     table to disable historical event collection
     and monitoring for all foreground threads, and insert a new row
     that enables monitoring and historical event collection for the
     user that will run the query:

          mysql> UPDATE performance_schema.setup_actors SET ENABLED = 'NO', HISTORY = 'NO'
                 WHERE HOST = '%' AND USER = '%';

          mysql> INSERT INTO performance_schema.setup_actors (HOST,USER,ROLE,ENABLED,HISTORY)
                 VALUES('localhost','test_user','%','YES','YES');

     Data in the 'setup_actors' table should
     now appear similar to the following:

          mysql> SELECT * FROM performance_schema.setup_actors;
          +-----------+-----------+------+---------+---------+
          | HOST      | USER      | ROLE | ENABLED | HISTORY |
          +-----------+-----------+------+---------+---------+
          | %         | %         | %    | NO      | NO      |
          | localhost | test_user | %    | YES     | YES     |
          +-----------+-----------+------+---------+---------+

  2. Ensure that statement and stage instrumentation is enabled by
     updating the 'setup_instruments'.
     table.  Some instruments may already be enabled by default.

          mysql> UPDATE performance_schema.setup_instruments SET ENABLED = 'YES', TIMED = 'YES'
                 WHERE NAME LIKE '%statement/%';

          mysql> UPDATE performance_schema.setup_instruments SET ENABLED = 'YES', TIMED = 'YES'
                 WHERE NAME LIKE '%stage/%';

  3. Ensure that 'events_statements_*' and 'events_stages_*' consumers
     are enabled.  Some consumers may already be enabled by default.

          mysql> UPDATE performance_schema.setup_consumers SET ENABLED = 'YES'
                 WHERE NAME LIKE '%events_statements_%';

          mysql> UPDATE performance_schema.setup_consumers SET ENABLED = 'YES'
                 WHERE NAME LIKE '%events_stages_%';

  4. Under the user account you are monitoring, run the statement that
     you want to profile.  For example:

          mysql> SELECT * FROM employees.employees WHERE emp_no = 10001;
          +--------+------------+------------+-----------+--------+------------+
          | emp_no | birth_date | first_name | last_name | gender | hire_date |
          +--------+------------+------------+-----------+--------+------------+
          |  10001 | 1953-09-02 | Georgi     | Facello   | M      | 1986-06-26 |
          +--------+------------+------------+-----------+--------+------------+

  5. Identify the 'EVENT_ID' of the statement by querying the
     'events_statements_history_long'
     table.  This step is similar
     to running 'SHOW PROFILES' to identify the
     'Query_ID'.  The following query produces output similar to
     'SHOW PROFILES'.:

          mysql> SELECT EVENT_ID, TRUNCATE(TIMER_WAIT/1000000000000,6) as Duration, SQL_TEXT
                 FROM performance_schema.events_statements_history_long WHERE SQL_TEXT like '%10001%';
          +----------+----------+--------------------------------------------------------+
          | event_id | duration | sql_text                                               |
          +----------+----------+--------------------------------------------------------+
          |       31 | 0.028310 | SELECT * FROM employees.employees WHERE emp_no = 10001 |
          +----------+----------+--------------------------------------------------------+

  6. Query the 'events_stages_history_long'
     table to retrieve the statement's
     stage events.  Stages are linked to statements using event nesting.
     Each stage event record has a 'NESTING_EVENT_ID' column that
     contains the 'EVENT_ID' of the parent statement.

          mysql> SELECT event_name AS Stage, TRUNCATE(TIMER_WAIT/1000000000000,6) AS Duration
                 FROM performance_schema.events_stages_history_long WHERE NESTING_EVENT_ID=31;
          +--------------------------------+----------+
          | Stage                          | Duration |
          +--------------------------------+----------+
          | stage/sql/starting             | 0.000080 |
          | stage/sql/checking permissions | 0.000005 |
          | stage/sql/Opening tables       | 0.027759 |
          | stage/sql/init                 | 0.000052 |
          | stage/sql/System lock          | 0.000009 |
          | stage/sql/optimizing           | 0.000006 |
          | stage/sql/statistics           | 0.000082 |
          | stage/sql/preparing            | 0.000008 |
          | stage/sql/executing            | 0.000000 |
          | stage/sql/Sending data         | 0.000017 |
          | stage/sql/end                  | 0.000001 |
          | stage/sql/query end            | 0.000004 |
          | stage/sql/closing tables       | 0.000006 |
          | stage/sql/freeing items        | 0.000272 |
          | stage/sql/cleaning up          | 0.000001 |
          +--------------------------------+----------+

25.19 Migrating to Performance Schema System and Status Variable Tables
=======================================================================

The 'INFORMATION_SCHEMA' has tables that contain system and status
variable information (see variables-table, and
status-table).  The Performance Schema also contains system and status
variable tables (see performance-schema-system-variable-tables,
and performance-schema-status-variable-tables).  The Performance
Schema tables are intended to replace the 'INFORMATION_SCHEMA' tables,
which are deprecated as of MySQL 5.7.6 and will be removed in a future
MySQL release.

This section describes the intended migration path away from the
'INFORMATION_SCHEMA' system and status variable tables to the
corresponding Performance Schema tables.  Application developers should
use this information as guidance regarding the changes required to
access system and status variables in MySQL 5.7.6 and up as the
'INFORMATION_SCHEMA' tables become deprecated and eventually are
removed.

*MySQL 5.6*

In MySQL 5.6, system and status variable information is available from
these 'SHOW' statements:

     SHOW VARIABLES
     SHOW STATUS

And from these 'INFORMATION_SCHEMA' tables:

     INFORMATION_SCHEMA.GLOBAL_VARIABLES
     INFORMATION_SCHEMA.SESSION_VARIABLES

     INFORMATION_SCHEMA.GLOBAL_STATUS
     INFORMATION_SCHEMA.SESSION_STATUS

*MySQL 5.7*

As of MySQL 5.7.6, the Performance Schema includes these tables as new
sources of system and status variable information:

     performance_schema.global_variables
     performance_schema.session_variables
     performance_schema.variables_by_thread

     performance_schema.global_status
     performance_schema.session_status
     performance_schema.status_by_thread
     performance_schema.status_by_account
     performance_schema.status_by_host
     performance_schema.status_by_user

MySQL 5.7.6 also adds a 'show_compatibility_56' system variable to
control how the server makes system and status variable information
available.

When 'show_compatibility_56' is 'ON', compatibility with MySQL 5.6 is
enabled.  The older system and status variable sources ('SHOW'
statements, 'INFORMATION_SCHEMA' tables) are available with semantics
identical to MySQL 5.6.  Applications should run as is, with no code
changes, and should see the same variable names and values as in MySQL
5.6.  Warnings occur under these circumstances:

   * A deprecation warning is raised when selecting from the
     'INFORMATION_SCHEMA' tables.

   * In MySQL 5.7.6 and 5.7.7, a deprecation warning is raised when
     using a 'WHERE' clause with the 'SHOW' statements.  This behavior
     does not occur as of MySQL 5.7.8.

When 'show_compatibility_56' is 'OFF', compatibility with MySQL 5.6 is
disabled and several changes result.  Applications must be revised as
follows to run properly:

   * Selecting from the 'INFORMATION_SCHEMA' tables produces an error.
     Applications that access the 'INFORMATION_SCHEMA' tables should be
     revised to use the corresponding Performance Schema tables instead.

     Before MySQL 5.7.9, selecting from the 'INFORMATION_SCHEMA' tables
     produces an empty result set plus a deprecation warning.  This was
     not sufficient notice to signal the need to migrate to the
     corresponding Performance Schema system and status variable tables
     for the case that 'show_compatibility_56=OFF'.  Producing an error
     in MySQL 5.7.9 and higher makes it more evident that an application
     is operating under conditions that require modification, as well as
     where the problem lies.

     In MySQL 5.7.6 and 5.7.7, the Performance Schema
     'session_variables' and
     'session_status'.
     tables do not fully reflect all variable values in effect for the
     current session; they include no rows for global variables that
     have no session counterpart.  This is corrected in MySQL 5.7.8.

   * Output for the 'SHOW' statements is produced using the underlying
     Performance Schema tables.  Applications written to use these
     statements can still use them, but it is best to use MySQL 5.7.8 or
     higher.  In MySQL 5.7.6 and 5.7.7, the results may differ:

        * 'SHOW [SESSION] VARIABLES' output does not include global
          variables that have no session counterpart.

        * Using a 'WHERE' clause with the 'SHOW' statements produces an
          error.

   * These 'Slave_XXX' status variables become unavailable through
     'SHOW STATUS'.:

          Slave_heartbeat_period
          Slave_last_heartbeat
          Slave_received_heartbeats
          Slave_retried_transactions
          Slave_running

     Applications that use these status variables should be revised to
     obtain this information using the replication-related Performance
     Schema tables.  For details, see
     sysvar_show_compatibility_56_slave_status.

   * The Performance Schema does not collect statistics for 'Com_XXX'
     status variables in the status variable tables.  To obtain global
     and per-session statement execution counts, use the
     'events_statements_summary_global_by_event_name'
     and
     'events_statements_summary_by_thread_by_event_name'
     tables, respectively.

*Migration and Privileges*

Initially, with the introduction of Performance Schema system and status
variable tables in MySQL 5.7.6, access to those tables required the
'SELECT' privilege, just as for other Performance Schema tables.
However, this had the consequence that when 'show_compatibility_56=OFF',
the 'SHOW VARIABLES' and 'SHOW STATUS'
statements also required the 'SELECT' privilege: With
compatibility disabled, output for those statements was taken from the
Performance Schema 'global_variables',
see 'session_variables',
see 'global_status',
and 'session_status'
tables.

As of MySQL 5.7.9, those Performance Schema tables are world readable
and accessible without the 'SELECT' privilege.  Consequently, see
'SHOW VARIABLES' and 'SHOW STATUS'.
do not require privileges on the underlying Performance Schema tables
from which their output is produced when 'show_compatibility_56=OFF'.

*Beyond MySQL 5.7*

In a MySQL 8.0, the 'INFORMATION_SCHEMA' variable tables and the
'show_compatibility_56' system variable are removed, and output from the
'SHOW' statements is always based on the underlying Performance Schema
tables.

Applications that have been revised to work in MySQL 5.7 when
'show_compatibility_56=OFF' should work without further changes, except
that it will not be possible to test or set 'show_compatibility_56'
because it will not exist.

26 MySQL sys Schema
*******************

MySQL 5.7.7 and higher includes the 'sys' schema, a
set of objects that helps DBAs and developers interpret data collected
by the Performance Schema.  'sys' schema objects can
be used for typical tuning and diagnosis use cases.  Objects in this
schema include:

   * Views that summarize Performance Schema data into more easily
     understandable form.

   * Stored procedures that perform operations such as Performance
     Schema configuration and generating diagnostic reports.

   * Stored functions that query Performance Schema configuration and
     provide formatting services.

For new installations, the 'sys' schema is installed
by default during data directory initialization if you use
'mysqld' with the '--initialize' or '--initialize-insecure'
option, or if you use 'mysql_install_db'.  To
permit this behavior to be suppressed, see 'mysql_install_db'
has a '--skip-sys-schema' option.  'mysqld'
has no such option, but if you initialize the data directory
using 'mysqld --initialize'. (or '--initialize-insecure')
rather than 'mysql_install_db', you can drop the
'sys' schema manually after initialization if it is
unneeded.

For upgrades, see 'mysql_upgrade' installs the
'sys' schema if it is not installed, and upgrades it to the
current version otherwise.  To permit this behavior to be suppressed,
see 'mysql_upgrade' has a '--skip-sys-schema' option.

'mysql_upgrade' returns an error if a 'sys'
schema exists but has no 'version' view,
on the assumption that absence of this view indicates a user-created
'sys' schema.  To upgrade in this case, remove or rename the existing
'sys' schema first.

As of MySQL 5.7.9, see 'sys' schema objects have a
'DEFINER' of ''mysql.sys'@'localhost''.  (Before MySQL 5.7.9, the
'DEFINER' is ''root'@'localhost''.)  Use of the dedicated 'mysql.sys'
account avoids problems that occur if a DBA renames or removes the
'root' account.

26.1 Prerequisites for Using the sys Schema
===========================================

Before using the 'sys' schema, the prerequisites
described in this section must be satisfied.

Because the 'sys' schema provides an alternative
means of accessing the Performance Schema, the Performance Schema must
be enabled for the 'sys' schema to work.  See
performance-schema-startup-configuration.

For full access to the 'sys' schema, a user must have
these privileges:

   * 'SELECT' on all 'sys' tables and views

   * 'EXECUTE' on all 'sys' stored procedures and
     functions

   * 'INSERT' and 'UPDATE' for the 'sys_config'.
     table, if changes are to be made to it

   * Additional privileges for certain 'sys' schema
     stored procedures and functions, as noted in their descriptions;
     for example, the 'ps_setup_save()'.
     procedure

It is also necessary to have privileges for the objects underlying the
'sys' schema objects:

   * 'SELECT' on any Performance Schema tables accessed by 'sys'
     schema objects, and 'UPDATE' for any tables to be
     updated using 'sys' schema objects

   * 'PROCESS' for the 'INFORMATION_SCHEMA' 'INNODB_BUFFER_PAGE'
     table

Certain Performance Schema instruments and consumers must be enabled and
(for instruments) timed to take full advantage of 'sys'
schema capabilities:

   * All 'wait' instruments

   * All 'stage' instruments

   * All 'statement' instruments

   * 'XXX_current' and 'XXX_history_long' consumers for all events

You can use the 'sys' schema itself to enable all of
the additional instruments and consumers:

     CALL sys.ps_setup_enable_instrument('wait');
     CALL sys.ps_setup_enable_instrument('stage');
     CALL sys.ps_setup_enable_instrument('statement');
     CALL sys.ps_setup_enable_consumer('current');
     CALL sys.ps_setup_enable_consumer('history_long');

*Note*:

For many uses of the 'sys' schema, the default Performance Schema is
sufficient for data collection.  Enabling all the instruments and
consumers just mentioned has a performance impact, so it is preferable
to enable only the additional configuration you need.  Also, remember
that if you enable additional configuration, you can easily restore the
default configuration like this:

     CALL sys.ps_setup_reset_to_default(TRUE);

26.2 Using the sys Schema
=========================

You can make the 'sys' schema the default schema so
that references to its objects need not be qualified with the schema
name:

     mysql> USE sys;
     Database changed
     mysql> SELECT * FROM version;
     +-------------+-----------------+
     | sys_version | mysql_version   |
     +-------------+-----------------+
     | 1.5.0       | 5.7.9-debug-log |
     +-------------+-----------------+

(The 'version' view shows the 'sys'
schema and MySQL server versions.)

To access 'sys' schema objects while a different
schema is the default (or simply to be explicit), qualify object
references with the schema name:

     mysql> SELECT * FROM sys.version;
     +-------------+-----------------+
     | sys_version | mysql_version   |
     +-------------+-----------------+
     | 1.5.0       | 5.7.9-debug-log |
     +-------------+-----------------+

Examples in this chapter usually assume 'sys' as the
default schema.

The 'sys' schema contains many views that summarize Performance Schema
tables in various ways.  Most of these views come in pairs, such that
one member of the pair has the same name as the other member, plus a
'x$' prefix.  For example, the 'host_summary_by_file_io'
view summarizes file I/O grouped by host
and displays latencies converted from picoseconds to more readable
values (with units);

     mysql> SELECT * FROM host_summary_by_file_io;
     +------------+-------+------------+
     | host       | ios   | io_latency |
     +------------+-------+------------+
     | localhost  | 67570 | 5.38 s     |
     | background |  3468 | 4.18 s     |
     +------------+-------+------------+

The 'x$host_summary_by_file_io' view
summarizes the same data but displays unformatted picosecond latencies:

     mysql> SELECT * FROM x$host_summary_by_file_io;
     +------------+-------+---------------+
     | host       | ios   | io_latency    |
     +------------+-------+---------------+
     | localhost  | 67574 | 5380678125144 |
     | background |  3474 | 4758696829416 |
     +------------+-------+---------------+

The view without the 'x$' prefix is intended to provide output that is
more user friendly and easier for humans to read.  The view with the
'x$' prefix that displays the same values in raw form is intended more
for use with other tools that perform their own processing on the data.
For additional information about the differences between non-'x$' and
'x$' views, see sys-schema-views.

To examine 'sys' schema object definitions, use the
appropriate 'SHOW' statement or 'INFORMATION_SCHEMA'
query.  For example, to examine the definitions of
the 'session' view and 'format_bytes()'
function, use these statements:

     mysql> SHOW CREATE VIEW session;
     mysql> SHOW CREATE FUNCTION format_bytes;

However, those statements display the definitions in relatively
unformatted form.  To view object definitions with more readable
formatting, access the individual '.sql' files available from the
'sys' schema development website at
<https://github.com/mysql/mysql-sys>.

Neither 'mysqldump' nor 'mysqlpump'.
dump the 'sys' schema by default.  To generate a dump
file, name the 'sys' schema explicitly on the command
line using either of these commands:

     mysqldump --databases --routines sys > sys_dump.sql
     mysqlpump sys > sys_dump.sql

To reinstall the schema from the dump file, use this command:

     mysql < sys_dump.sql

26.3 sys Schema Progress Reporting
==================================

As of MySQL 5.7.9, the following 'sys' schema views
provide progress reporting for long-running transactions:

     processlist
     session
     x$processlist
     x$session

Assuming that the required instruments and consumers are enabled, the
'progress' column of these views shows the percentage of work completed
for stages that support progress reporting.

Stage progress reporting requires that the 'events_stages_current'
consumer be enabled, as well as the instruments for which progress
information is desired.  Instruments for these stages currently support
progress reporting:

     stage/sql/Copying to tmp table
     stage/innodb/alter table (end)
     stage/innodb/alter table (flush)
     stage/innodb/alter table (insert)
     stage/innodb/alter table (log apply index)
     stage/innodb/alter table (log apply table)
     stage/innodb/alter table (merge sort)
     stage/innodb/alter table (read PK and internal sort)
     stage/innodb/buffer pool load

For stages that do not support estimated and completed work reporting,
or if the required instruments or consumers are not enabled, the
'progress' column is 'NULL'.

26.4 sys Schema Object Reference
================================

The 'sys' schema includes tables and triggers, views,
and stored procedures and functions.  The following sections provide
details for each of these objects.

26.4.1 sys Schema Object Index
------------------------------

The following tables list 'sys' schema objects and
provide a short description of each one.

*sys Schema Tables and Triggers*

Table or Trigger Name                       Description

See 'sys_config'.         See 'sys'.
                                            schema configuration
                                            options

See 'sys_config_insert_set_user'.
     sys-sys-config. insert
                                            trigger

See 'sys_config_update_set_user'.
     sys-sys-config. update
                                            trigger

*sys Schema Views*

View Name                                   Description

See 'host_summary',     Statement activity, file
'x$host_summary'.   I/O, and connections,
                                            grouped by host

See 'host_summary_by_file_io', grouped by host
sys-host-summary-by-file-io, see
'x$host_summary_by_file_io'.

See 'host_summary_by_file_io_type', grouped by host
sys-host-summary-by-file-io-type, see and event type 'x$host_summary_by_file_io_type'.

See 'host_summary_by_stages', grouped
sys-host-summary-by-stages, see by host 'x$host_summary_by_stages'.

See Statement statistics, 'host_summary_by_statement_latency',

'x$host_summary_by_statement_latency'.

See 'host_summary_by_statement_type',
sys-host-summary-by-statement-type, see grouped by host and 'x$host_summary_by_statement_type'.

See 'innodb_buffer_stats_by_schema',
see information, grouped by 'x$innodb_buffer_stats_by_schema'.

See 'innodb_buffer_stats_by_table',
see information, grouped by 'x$innodb_buffer_stats_by_table'.

See 'innodb_lock_waits',
see
'x$innodb_lock_waits'.

See 'io_by_thread_by_latency', grouped by
sys-io-by-thread-by-latency, see thread 'x$io_by_thread_by_latency'.

See 'io_global_by_file_by_bytes',
sys-io-global-by-file-by-bytes, see grouped by file and bytes 'x$io_global_by_file_by_bytes'.

See 'io_global_by_file_by_latency',
sys-io-global-by-file-by-latency, see grouped by file and latency 'x$io_global_by_file_by_latency'.

See 'io_global_by_wait_by_bytes',
sys-io-global-by-wait-by-bytes, see grouped by bytes 'x$io_global_by_wait_by_bytes'.

See 'io_global_by_wait_by_latency',
sys-io-global-by-wait-by-latency, see grouped by latency 'x$io_global_by_wait_by_latency'.

See 'latest_file_io', grouped by
sys-latest-file-io, see file and thread 'x$latest_file_io'.

See 'memory_by_host_by_current_bytes', grouped by host
sys-memory-by-host-by-current-bytes,
see
'x$memory_by_host_by_current_bytes'.

See Memory use, grouped by 'memory_by_thread_by_current_bytes',

'x$memory_by_thread_by_current_bytes'.

See 'memory_by_user_by_current_bytes', grouped by user
sys-memory-by-user-by-current-bytes,
see
'x$memory_by_user_by_current_bytes'.

See 'memory_global_by_current_bytes', grouped by
sys-memory-global-by-current-bytes, see allocation type 'x$memory_global_by_current_bytes'.

See 'memory_global_total',
see
'x$memory_global_total'.

See 'metrics'.               Server metrics

See 'processlist',       Processlist information
'x$processlist'.

See 'ps_check_lost_instrumentation'.
  instruments

See 'schema_auto_increment_columns'.
  information

See 'schema_index_statistics',
see
'x$schema_index_statistics'.

See 'schema_object_overview'.
         each schema

See 'schema_redundant_indexes'.
       indexes

See 'schema_table_lock_waits',
see metadata locks 'x$schema_table_lock_waits'.

See 'schema_table_statistics',
see
'x$schema_table_statistics'.

See Table statistics, including 'schema_table_statistics_with_buffer',
statistics

'x$schema_table_statistics_with_buffer'.

See Tables being accessed with 'schema_tables_with_full_table_scans',

'x$schema_tables_with_full_table_scans'.

See 'schema_unused_indexes'.

See 'session', Processlist information for 'x$session'.
           user sessions

See 'session_ssl_status'.

See 'statement_analysis',
see statistics 'x$statement_analysis'.

See Statements that have 'statements_with_errors_or_warnings',

'x$statements_with_errors_or_warnings'.

See 'statements_with_full_table_scans',
full table scans

'x$statements_with_full_table_scans'.

See Statements with highest 'statements_with_runtimes_in_95th_percentile',

'x$statements_with_runtimes_in_95th_percentile'.

See 'statements_with_sorting',
see sorts 'x$statements_with_sorting'.

See 'statements_with_temp_tables',
see temporary tables 'x$statements_with_temp_tables'.

See 'user_summary',     User statement and
'x$user_summary'.   connection activity

See 'user_summary_by_file_io', grouped by user
sys-user-summary-by-file-io, see
'x$user_summary_by_file_io'.

See 'user_summary_by_file_io_type', grouped by user
sys-user-summary-by-file-io-type, see and event 'x$user_summary_by_file_io_type'.

See 'user_summary_by_stages', grouped by
sys-user-summary-by-stages, see user 'x$user_summary_by_stages'.

See Statement statistics, 'user_summary_by_statement_latency',

'x$user_summary_by_statement_latency'.

See 'user_summary_by_statement_type',
sys-user-summary-by-statement-type, see grouped by user and 'x$user_summary_by_statement_type'.

See 'version'.               Current 'sys'
                                        schema and
                                            MySQL server versions

See Wait class average latency, 'wait_classes_global_by_avg_latency',

'x$wait_classes_global_by_avg_latency'.

See 'wait_classes_global_by_latency',
sys-wait-classes-global-by-latency, see grouped by event class 'x$wait_classes_global_by_latency'.

See 'waits_by_host_by_latency', grouped by
sys-waits-by-host-by-latency, see host and event 'x$waits_by_host_by_latency'.

See 'waits_by_user_by_latency', grouped by
sys-waits-by-user-by-latency, see user and event 'x$waits_by_user_by_latency'.

See 'waits_global_by_latency', grouped by
sys-waits-global-by-latency, see event 'x$waits_global_by_latency'.

See Helper view for 'x$ps_digest_95th_percentile_by_avg_us'.

See Helper view for 'x$ps_digest_avg_latency_distribution'.

See 'x$ps_schema_table_statistics_io'.
        table-statistics views

See 'x$schema_flattened_keys'.
       'schema_redundant_indexes':
                                            sys-schema-redundant-indexes.

*sys Schema Stored Procedures*

Procedure Name                              Description

See 'create_synonym_db()'.

See 'diagnostics()'.     Collect system diagnostic
                                            information

See 'execute_prepared_stmt()'.

See Disable background thread 'ps_setup_disable_background_threads()'.

See 'ps_setup_disable_consumer()'.

See 'ps_setup_disable_instrument()'.

See 'ps_setup_disable_thread()'.
        thread

See Enable background thread 'ps_setup_enable_background_threads()'.

See 'ps_setup_enable_consumer()'.

See 'ps_setup_enable_instrument()'.

See 'ps_setup_enable_thread()'.
         thread

See 'ps_setup_reload_saved()'.
          Schema configuration

See 'ps_setup_reset_to_default()'.
      Schema configuration

See 'ps_setup_save()'.
                  configuration

See 'ps_setup_show_disabled()'.
         Performance Schema
                                            configuration

See Display disabled 'ps_setup_show_disabled_consumers()'.
consumers

See Display disabled 'ps_setup_show_disabled_instruments()'.
instruments

See 'ps_setup_show_enabled()'.
          Schema configuration

See Display enabled Performance 'ps_setup_show_enabled_consumers()'.

See Display enabled Performance 'ps_setup_show_enabled_instruments()'.

See Display statement latency 'ps_statement_avg_latency_histogram()'.

See 'ps_trace_statement_digest()'.
      instrumentation for digest

See 'ps_trace_thread()'.
                data for thread

See 'ps_truncate_all_tables()'.
         summary tables

See 'statement_performance_analyzer()'.
 running on server

See 'table_exists()'.   Whether a table exists

*sys Schema Stored Functions*

Function Name                               Description

See 'extract_schema_from_file_name()'.
  file path name

See 'extract_table_from_file_name()'.
   file path name

See 'format_bytes()'.   Convert byte value to value
                                            with units

See 'format_path()'.     Replace data and temp-file
                                            directories in path name
                                            with symbolic values

See 'format_statement()'.
               fixed length

See 'format_time()'.     Convert picoseconds value
                                            to value with units

See 'list_add()'.           Add item to list

See 'list_drop()'.         Remove item from list

See 'ps_is_account_enabled()'.
          instrumentation is enabled

See 'ps_is_consumer_enabled()'.
         enabled

See Check whether instrument is 'ps_is_instrument_default_enabled()'.

See 'ps_is_instrument_default_timed()'.
 timed

See 'ps_is_thread_instrumented()'.
      instrumented

See 'ps_thread_account()'.
              ID

See 'ps_thread_id()'.   Return thread ID for
                                            connection ID

See 'ps_thread_stack()'.
                for thread ID

See 'ps_thread_trx_info()'.
             information for thread ID

See 'quote_identifier()'.
               identifier

See 'sys_get_config()'.
                 sys-schema. schema
                                            configuration option

See 'version_major()'.
                  number

See 'version_minor()'.
                  number

See 'version_patch()'.
                  version number

26.4.2 sys Schema Tables and Triggers
-------------------------------------

The following sections describe 'sys' schema tables
and triggers.

26.4.2.1 The sys_config Table
.............................

This table contains 'sys' schema configuration
options, one row per option.  Configuration changes made by updating
this table persist across client sessions and server restarts.

The 'sys_config' table has these columns:

   * 'variable'

     The configuration option name.

   * 'value'

     The configuration option value.

   * 'set_time'

     The timestamp of the most recent modification to the row.

   * 'set_by'

     The account that made the most recent modification to the row.  The
     value is 'NULL' if the row has not been changed since the
     'sys' schema was installed.

As an efficiency measure to minimize the number of direct reads from the
'sys_config' table, see 'sys'.
schema functions that use a value from this table check for a
user-defined variable with a corresponding name, which is the
user-defined variable having the same name plus a '@sys.' prefix.  (For
example, the variable corresponding to the 'diagnostics.include_raw'
option is '@sys.diagnostics.include_raw'.)  If the user-defined variable
exists in the current session and is non-'NULL', the function uses its
value in preference to the value in the 'sys_config'
table.  Otherwise, the function reads and uses the value
from the table.  In the latter case, the calling function conventionally
also sets the corresponding user-defined variable to the table value so
that further references to the configuration option within the same
session use the variable and need not read the table again.

For example, the 'statement_truncate_len' option controls the maximum
length of statements returned by the 'format_statement()'
function.  The default is 64.  To temporarily
change the value to 32 for your current session, set the corresponding
'@sys.statement_truncate_len' user-defined variable:

     mysql> SET @stmt = 'SELECT variable, value, set_time, set_by FROM sys_config';
     mysql> SELECT format_statement(@stmt);
     +----------------------------------------------------------+
     | format_statement(@stmt)                                  |
     +----------------------------------------------------------+
     | SELECT variable, value, set_time, set_by FROM sys_config |
     +----------------------------------------------------------+
     mysql> SET @sys.statement_truncate_len = 32;
     mysql> SELECT format_statement(@stmt);
     +-----------------------------------+
     | format_statement(@stmt)           |
     +-----------------------------------+
     | SELECT variabl ... ROM sys_config |
     +-----------------------------------+

Subsequent invocations of 'format_statement()'
within the session continue to use the
user-defined variable value (32), rather than the value stored in the
table (64).

To stop using the user-defined variable and revert to using the value in
the table, set the variable to 'NULL' within your session:

     mysql> SET @sys.statement_truncate_len = NULL;
     mysql> SELECT format_statement(@stmt);
     +----------------------------------------------------------+
     | format_statement(@stmt)                                  |
     +----------------------------------------------------------+
     | SELECT variable, value, set_time, set_by FROM sys_config |
     +----------------------------------------------------------+

Alternatively, end your current session (causing the user-defined
variable to no longer exist) and begin a new session.

The conventional relationship just described between options in the
'sys_config' table and user-defined variables can
be exploited to make temporary configuration changes that end when your
session ends.  However, if you set a user-defined variable and then
subsequently change the corresponding table value within the same
session, the changed table value will not be used in that session as
long as the user-defined variable exists with a non-'NULL' value.  (The
changed table value _will_ be used in other sessions that do not have
the user-defined variable assigned.)

The following list describes the options in the 'sys_config'
table and the corresponding user-defined variables:

   * 'diagnostics.allow_i_s_tables', '@sys.diagnostics.allow_i_s_tables'

     If this option is 'ON', the 'diagnostics()'.
     procedure is permitted to perform table scans on the
     'INFORMATION_SCHEMA.TABLES' table.  This can be
     expensive if there are many tables.  The default is 'OFF'.

     This option was added in MySQL 5.7.9.

   * 'diagnostics.include_raw', '@sys.diagnostics.include_raw'

     If this option is 'ON', the 'diagnostics()'.
     procedure includes the raw output from querying the
     'metrics' view.  The default is 'OFF'.

     This option was added in MySQL 5.7.9.

   * 'ps_thread_trx_info.max_length',
     '@sys.ps_thread_trx_info.max_length'

     The maximum length for JSON output produced by the
     'ps_thread_trx_info()' function.  The
     default is 65535.

     This option was added in MySQL 5.7.9.

   * 'statement_performance_analyzer.limit',
     '@sys.statement_performance_analyzer.limit'

     The maximum number of rows to return for views that have no
     built-in limit.  (For example, the
     'statements_with_runtimes_in_95th_percentile'
     view has a
     built-in limit in the sense that it returns only statements with
     average execution time in the 95th percentile.)  The default is
     100.

     This option was added in MySQL 5.7.9.

   * 'statement_performance_analyzer.view',
     '@sys.statement_performance_analyzer.view'

     The custom query or view to be used by the
     'statement_performance_analyzer()'
     procedure (which is itself
     invoked by the 'diagnostics()' procedure).
     If the option value contains a space, it is interpreted as a query.
     Otherwise, it must be the name of an existing view that queries the
     Performance Schema 'events_statements_summary_by_digest'
     table.  There cannot be any 'LIMIT'
     clause in the query or view definition if the
     'statement_performance_analyzer.limit' configuration option is
     greater than 0.  The default is 'NULL' (no custom view defined).

     This option was added in MySQL 5.7.9.

   * 'statement_truncate_len', '@sys.statement_truncate_len'

     The maximum length of statements returned by the
     'format_statement()' function.  Longer
     statements are truncated to this length.  The default is 64.

Other options can be added to the 'sys_config'.
table.  For example, the 'diagnostics()' and
'execute_prepared_stmt()' procedures
use the 'debug' option if it exists, but this option is not part of the
'sys_config' table by default because debug
output normally is enabled only temporarily, by setting the
corresponding '@sys.debug' user-defined variable.  To enable debug
output without having to set that variable in individual sessions, add
the option to the table:

     mysql> INSERT INTO sys_config (variable, value) VALUES('debug', 'ON');

To change the debug setting in the table, do two things.  First, modify
the value in the table itself:

     mysql> UPDATE sys_config SET value = 'OFF' WHERE variable = 'debug';

Second, to also ensure that procedure invocations within the current
session use the changed value from the table, set the corresponding
user-defined variable to 'NULL':

     mysql> SET @sys.debug = NULL;

26.4.2.2 The sys_config_insert_set_user Trigger
...............................................

For rows added to the 'sys_config' table by
'INSERT' statements, the 'sys_config_insert_set_user'
trigger sets the 'set_by' column to the
current user.

26.4.2.3 The sys_config_update_set_user Trigger
...............................................

The 'sys_config_update_set_user'.
trigger for the 'sys_config' table is similar to
the 'sys_config_insert_set_user'.
trigger, but for 'UPDATE' statements.

26.4.3 sys Schema Views
-----------------------

The following sections describe 'sys' schema views.

The 'sys' schema contains many views that summarize Performance Schema
tables in various ways.  Most of these views come in pairs, such that
one member of the pair has the same name as the other member, plus a
'x$' prefix.  For example, the 'host_summary_by_file_io'
view summarizes file I/O grouped by host
and displays latencies converted from picoseconds to more readable
values (with units);

     mysql> SELECT * FROM host_summary_by_file_io;
     +------------+-------+------------+
     | host       | ios   | io_latency |
     +------------+-------+------------+
     | localhost  | 67570 | 5.38 s     |
     | background |  3468 | 4.18 s     |
     +------------+-------+------------+

The 'x$host_summary_by_file_io' view
summarizes the same data but displays unformatted picosecond latencies:

     mysql> SELECT * FROM x$host_summary_by_file_io;
     +------------+-------+---------------+
     | host       | ios   | io_latency    |
     +------------+-------+---------------+
     | localhost  | 67574 | 5380678125144 |
     | background |  3474 | 4758696829416 |
     +------------+-------+---------------+

The view without the 'x$' prefix is intended to provide output that is
more user friendly and easier to read.  The view with the 'x$' prefix
that displays the same values in raw form is intended more for use with
other tools that perform their own processing on the data.

Views without the 'x$' prefix differ from the corresponding 'x$' views
in these ways:

   * Byte values are formatted with size units using
     'format_bytes()'.

   * Time values are formatted with temporal units using
     'format_time()'.

   * SQL statements are truncated to a maximum display width using
     'format_statement()'.

   * Path name are shortened using 'format_path()'.

26.4.3.1 The host_summary and x$host_summary Views
..................................................

These views summarize statement activity, file I/O, and connections,
grouped by host.

The 'host_summary' and 'x$host_summary'
views have these columns:

   * 'host'

     The host from which the client connected.  Rows for which the
     'HOST' column in the underlying Performance Schema table is 'NULL'
     are assumed to be for background threads and are reported with a
     host name of 'background'.

   * 'statements'

     The total number of statements for the host.

   * 'statement_latency'

     The total wait time of timed statements for the host.

   * 'statement_avg_latency'

     The average wait time per timed statement for the host.

   * 'table_scans'

     The total number of table scans for the host.

   * 'file_ios'

     The total number of file I/O events for the host.

   * 'file_io_latency'

     The total wait time of timed file I/O events for the host.

   * 'current_connections'

     The current number of connections for the host.

   * 'total_connections'

     The total number of connections for the host.

   * 'unique_users'

     The number of distinct users for the host.

   * 'current_memory'

     The current amount of allocated memory for the host.

   * 'total_memory_allocated'

     The total amount of allocated memory for the host.

26.4.3.2 The host_summary_by_file_io and x$host_summary_by_file_io Views
........................................................................

These views summarize file I/O, grouped by host.  By default, rows are
sorted by descending total file I/O latency.

The 'host_summary_by_file_io' and
'x$host_summary_by_file_io' views
have these columns:

   * 'host'

     The host from which the client connected.  Rows for which the
     'HOST' column in the underlying Performance Schema table is 'NULL'
     are assumed to be for background threads and are reported with a
     host name of 'background'.

   * 'ios'

     The total number of file I/O events for the host.

   * 'io_latency'

     The total wait time of timed file I/O events for the host.

26.4.3.3 The host_summary_by_file_io_type and x$host_summary_by_file_io_type Views
..................................................................................

These views summarize file I/O, grouped by host and event type.  By
default, rows are sorted by host and descending total I/O latency.

The 'host_summary_by_file_io_type'
and
'x$host_summary_by_file_io_type'.
views have these columns:

   * 'host'

     The host from which the client connected.  Rows for which the
     'HOST' column in the underlying Performance Schema table is 'NULL'
     are assumed to be for background threads and are reported with a
     host name of 'background'.

   * 'event_name'

     The file I/O event name.

   * 'total'

     The total number of occurrences of the file I/O event for the host.

   * 'total_latency'

     The total wait time of timed occurrences of the file I/O event for
     the host.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the file I/O
     event for the host.

26.4.3.4 The host_summary_by_stages and x$host_summary_by_stages Views
......................................................................

These views summarize statement stages, grouped by host.  By default,
rows are sorted by host and descending total latency.

The 'host_summary_by_stages' and
'x$host_summary_by_stages' views have
these columns:

   * 'host'

     The host from which the client connected.  Rows for which the
     'HOST' column in the underlying Performance Schema table is 'NULL'
     are assumed to be for background threads and are reported with a
     host name of 'background'.

   * 'event_name'

     The stage event name.

   * 'total'

     The total number of occurrences of the stage event for the host.

   * 'total_latency'

     The total wait time of timed occurrences of the stage event for the
     host.

   * 'avg_latency'

     The average wait time per timed occurrence of the stage event for
     the host.

26.4.3.5 The host_summary_by_statement_latency and x$host_summary_by_statement_latency Views
............................................................................................

These views summarize overall statement statistics, grouped by host.  By
default, rows are sorted by descending total latency.

The 'host_summary_by_statement_latency'
and
'x$host_summary_by_statement_latency'
views have these columns:

   * 'host'

     The host from which the client connected.  Rows for which the
     'HOST' column in the underlying Performance Schema table is 'NULL'
     are assumed to be for background threads and are reported with a
     host name of 'background'.

   * 'total'

     The total number of statements for the host.

   * 'total_latency'

     The total wait time of timed statements for the host.

   * 'max_latency'

     The maximum single wait time of timed statements for the host.

   * 'lock_latency'

     The total time waiting for locks by timed statements for the host.

   * 'rows_sent'

     The total number of rows returned by statements for the host.

   * 'rows_examined'

     The total number of rows read from storage engines by statements
     for the host.

   * 'rows_affected'

     The total number of rows affected by statements for the host.

   * 'full_scans'

     The total number of full table scans by statements for the host.

26.4.3.6 The host_summary_by_statement_type and x$host_summary_by_statement_type Views
......................................................................................

These views summarize informaion about statements executed, grouped by
host and statement type.  By default, rows are sorted by host and
descending total latency.

The 'host_summary_by_statement_type'
and
'x$host_summary_by_statement_type'.
views have these columns:

   * 'host'

     The host from which the client connected.  Rows for which the
     'HOST' column in the underlying Performance Schema table is 'NULL'
     are assumed to be for background threads and are reported with a
     host name of 'background'.

   * 'statement'

     The final component of the statement event name.

   * 'total'

     The total number of occurrences of the statement event for the
     host.

   * 'total_latency'

     The total wait time of timed occurrences of the statement event for
     the host.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the statement
     event for the host.

   * 'lock_latency'

     The total time waiting for locks by timed occurrences of the
     statement event for the host.

   * 'rows_sent'

     The total number of rows returned by occurrences of the statement
     event for the host.

   * 'rows_examined'

     The total number of rows read from storage engines by occurrences
     of the statement event for the host.

   * 'rows_affected'

     The total number of rows affected by occurrences of the statement
     event for the host.

   * 'full_scans'

     The total number of full table scans by occurrences of the
     statement event for the host.

26.4.3.7 The innodb_buffer_stats_by_schema and x$innodb_buffer_stats_by_schema Views
....................................................................................

These views summarize the information in the 'INFORMATION_SCHEMA'
'INNODB_BUFFER_PAGE' table, grouped by
schema.  By default, rows are sorted by descending buffer size.

The 'innodb_buffer_stats_by_schema'
and
'x$innodb_buffer_stats_by_schema'.
views have these columns:

   * 'object_schema'

     The schema name for the object, or 'InnoDB System' if the table
     belongs to the 'InnoDB' storage engine.

   * 'allocated'

     The total number of bytes allocated for the schema.

   * 'data'

     The total number of data bytes allocated for the schema.

   * 'pages'

     The total number of pages allocated for the schema.

   * 'pages_hashed'

     The total number of hashed pages allocated for the schema.

   * 'pages_old'

     The total number of old pages allocated for the schema.

   * 'rows_cached'

     The total number of cached rows for the schema.

26.4.3.8 The innodb_buffer_stats_by_table and x$innodb_buffer_stats_by_table Views
..................................................................................

These views summarize the information in the 'INFORMATION_SCHEMA'
'INNODB_BUFFER_PAGE' table, grouped by schema
and table.  By default, rows are sorted by descending buffer size.

The 'innodb_buffer_stats_by_table'
and
'x$innodb_buffer_stats_by_table'.
views have these columns:

   * 'object_schema'

     The schema name for the object, or 'InnoDB System' if the table
     belongs to the 'InnoDB' storage engine.

   * 'object_name'

     The table name.

   * 'allocated'

     The total number of bytes allocated for the table.

   * 'data'

     The number of data bytes allocated for the table.

   * 'pages'

     The total number of pages allocated for the table.

   * 'pages_hashed'

     The number of hashed pages allocated for the table.

   * 'pages_old'

     The number of old pages allocated for the table.

   * 'rows_cached'

     The number of cached rows for the table.

26.4.3.9 The innodb_lock_waits and x$innodb_lock_waits Views
............................................................

These views summarize the 'InnoDB' locks that transactions are waiting
for.  By default, rows are sorted by descending lock age.

The 'innodb_lock_waits' and
'x$innodb_lock_waits' views have these columns:

   * 'wait_started'

     The time at which the lock wait started.

   * 'wait_age'

     How long the lock has been waited for, as a 'TIME'.
     value.

   * 'wait_age_secs'

     How long the lock has been waited for, in seconds.

     This column was added in MySQL 5.7.9.

   * 'locked_table'

     The name of the locked table.  This column contains combined
     schema/table name values.

   * 'locked_index'

     The name of the locked index.

   * 'locked_type'

     The type of the waiting lock.

   * 'waiting_trx_id'

     The ID of the waiting transaction.

   * 'waiting_trx_started'

     The time at which the waiting transaction started.

   * 'waiting_trx_age'

     How long the waiting transaction has been waiting, as a
     'TIME' value.

   * 'waiting_trx_rows_locked'

     The number of rows locked by the waiting transaction.

   * 'waiting_trx_rows_modified'

     The number of rows modified by the waiting transaction.

   * 'waiting_pid'

     The processlist ID of the waiting transaction.

   * 'waiting_query'

     The statement that is waiting for the lock.

   * 'waiting_lock_id'

     The ID of the waiting lock.

   * 'waiting_lock_mode'

     The mode of the waiting lock.

   * 'blocking_trx_id'

     The ID of the transaction that is blocking the waiting lock.

   * 'blocking_pid'

     The processlist ID of the blocking transaction.

   * 'blocking_query'

     The statement the blocking transaction is executing.  This field
     reports NULL if the session that issued the blocking query becomes
     idle.  For more information, see
     innodb-information-schema-examples-null-blocking-query.

   * 'blocking_lock_id'

     The ID of the lock that is blocking the waiting lock.

   * 'blocking_lock_mode'

     The mode of the lock that is blocking the waiting lock.

   * 'blocking_trx_started'

     The time at which the blocking transaction started.

   * 'blocking_trx_age'

     How long the blocking transaction has been executing, as a
     'TIME' value.

   * 'blocking_trx_rows_locked'

     The number of rows locked by the blocking transaction.

   * 'blocking_trx_rows_modified'

     The number of rows modified by the blocking transaction.

   * 'sql_kill_blocking_query'

     The 'KILL' statement to execute to kill the blocking
     statement.

     This column was added in MySQL 5.7.9.

   * 'sql_kill_blocking_connection'

     The 'KILL' statement to execute to kill the session
     running the blocking statement.

     This column was added in MySQL 5.7.9.

26.4.3.10 The io_by_thread_by_latency and x$io_by_thread_by_latency Views
.........................................................................

These views summarize I/O consumers to display time waiting for I/O,
grouped by thread.  By default, rows are sorted by descending total I/O
latency.

The 'io_by_thread_by_latency' and
'x$io_by_thread_by_latency' views
have these columns:

   * 'user'

     For foreground threads, the account associated with the thread.
     For background threads, the thread name.

   * 'total'

     The total number of I/O events for the thread.

   * 'total_latency'

     The total wait time of timed I/O events for the thread.

   * 'min_latency'

     The minimum single wait time of timed I/O events for the thread.

   * 'avg_latency'

     The average wait time per timed I/O event for the thread.

   * 'max_latency'

     The maximum single wait time of timed I/O events for the thread.

   * 'thread_id'

     The thread ID.

   * 'processlist_id'

     For foreground threads, the processlist ID of the thread.  For
     background threads, 'NULL'.

26.4.3.11 The io_global_by_file_by_bytes and x$io_global_by_file_by_bytes Views
...............................................................................

These views summarize global I/O consumers to display amount of I/O,
grouped by file.  By default, rows are sorted by descending total I/O
(bytes read and written).

The 'io_global_by_file_by_bytes'.
and 'x$io_global_by_file_by_bytes'
views have these columns:

   * 'file'

     The file path name.

   * 'count_read'

     The total number of read events for the file.

   * 'total_read'

     The total number of bytes read from the file.

   * 'avg_read'

     The average number of bytes per read from the file.

   * 'count_write'

     The total number of write events for the file.

   * 'total_written'

     The total number of bytes written to the file.

   * 'avg_write'

     The average number of bytes per write to the file.

   * 'total'

     The total number of bytes read and written for the file.

   * 'write_pct'

     The percentage of total bytes of I/O that were writes.

26.4.3.12 The io_global_by_file_by_latency and x$io_global_by_file_by_latency Views
...................................................................................

These views summarize global I/O consumers to display time waiting for
I/O, grouped by file.  By default, rows are sorted by descending total
latency.

The 'io_global_by_file_by_latency'
and
'x$io_global_by_file_by_latency'.
views have these columns:

   * 'file'

     The file path name.

   * 'total'

     The total number of I/O events for the file.

   * 'total_latency'

     The total wait time of timed I/O events for the file.

   * 'count_read'

     The total number of read I/O events for the file.

   * 'read_latency'

     The total wait time of timed read I/O events for the file.

   * 'count_write'

     The total number of write I/O events for the file.

   * 'write_latency'

     The total wait time of timed write I/O events for the file.

   * 'count_misc'

     The total number of other I/O events for the file.

   * 'misc_latency'

     The total wait time of timed other I/O events for the file.

26.4.3.13 The io_global_by_wait_by_bytes and x$io_global_by_wait_by_bytes Views
...............................................................................

These views summarize global I/O consumers to display amount of I/O and
time waiting for I/O, grouped by event.  By default, rows are sorted by
descending total I/O (bytes read and written).

The 'io_global_by_wait_by_bytes'.
and 'x$io_global_by_wait_by_bytes'
views have these columns:

   * 'event_name'

     The I/O event name, with the 'wait/io/file/' prefix stripped.

   * 'total'

     The total number of occurrences of the I/O event.

   * 'total_latency'

     The total wait time of timed occurrences of the I/O event.

   * 'min_latency'

     The minimum single wait time of timed occurrences of the I/O event.

   * 'avg_latency'

     The average wait time per timed occurrence of the I/O event.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the I/O event.

   * 'count_read'

     The number of read requests for the I/O event.

   * 'total_read'

     The number of bytes read for the I/O event.

   * 'avg_read'

     The average number of bytes per read for the I/O event.

   * 'count_write'

     The number of write requests for the I/O event.

   * 'total_written'

     The number of bytes written for the I/O event.

   * 'avg_written'

     The average number of bytes per write for the I/O event.

   * 'total_requested'

     The total number of bytes read and written for the I/O event.

26.4.3.14 The io_global_by_wait_by_latency and x$io_global_by_wait_by_latency Views
...................................................................................

These views summarize global I/O consumers to display amount of I/O and
time waiting for I/O, grouped by event.  By default, rows are sorted by
descending total latency.

The 'io_global_by_wait_by_latency'
and
'x$io_global_by_wait_by_latency'.
views have these columns:

   * 'event_name'

     The I/O event name, with the 'wait/io/file/' prefix stripped.

   * 'total'

     The total number of occurrences of the I/O event.

   * 'total_latency'

     The total wait time of timed occurrences of the I/O event.

   * 'avg_latency'

     The average wait time per timed occurrence of the I/O event.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the I/O event.

   * 'read_latency'

     The total wait time of timed read occurrences of the I/O event.

   * 'write_latency'

     The total wait time of timed write occurrences of the I/O event.

   * 'misc_latency'

     The total wait time of timed other occurrences of the I/O event.

   * 'count_read'

     The number of read requests for the I/O event.

   * 'total_read'

     The number of bytes read for the I/O event.

   * 'avg_read'

     The average number of bytes per read for the I/O event.

   * 'count_write'

     The number of write requests for the I/O event.

   * 'total_written'

     The number of bytes written for the I/O event.

   * 'avg_written'

     The average number of bytes per write for the I/O event.

26.4.3.15 The latest_file_io and x$latest_file_io Views
.......................................................

These views summarize file I/O activity, grouped by file and thread.  By
default, rows are sorted with most recent I/O first.

The 'latest_file_io' and
'x$latest_file_io' views have these columns:

   * 'thread'

     For foreground threads, the account associated with the thread (and
     port number for TCP/IP connections).  For background threads, the
     thread name and thread ID

   * 'file'

     The file path name.

   * 'latency'

     The wait time of the file I/O event.

   * 'operation'

     The type of operation.

   * 'requested'

     The number of data bytes requested for the file I/O event.

26.4.3.16 The memory_by_host_by_current_bytes and x$memory_by_host_by_current_bytes Views
.........................................................................................

These views summarize memory use, grouped by host.  By default, rows are
sorted by descending amount of memory used.

The 'memory_by_host_by_current_bytes'
and
'x$memory_by_host_by_current_bytes'
views have these columns:

   * 'host'

     The host from which the client connected.  Rows for which the
     'HOST' column in the underlying Performance Schema table is 'NULL'
     are assumed to be for background threads and are reported with a
     host name of 'background'.

   * 'current_count_used'

     The current number of allocated memory blocks that have not been
     freed yet for the host.

   * 'current_allocated'

     The current number of allocated bytes that have not been freed yet
     for the host.

   * 'current_avg_alloc'

     The current number of allocated bytes per memory block for the
     host.

   * 'current_max_alloc'

     The largest single current memory allocation in bytes for the host.

   * 'total_allocated'

     The total memory allocation in bytes for the host.

26.4.3.17 The memory_by_thread_by_current_bytes and x$memory_by_thread_by_current_bytes Views
.............................................................................................

These views summarize memory use, grouped by thread.  By default, rows
are sorted by descending amount of memory used.

The 'memory_by_thread_by_current_bytes'
and
'x$memory_by_thread_by_current_bytes'
views have these columns:

   * 'thread_id'

     The thread ID.

   * 'user'

     The thread user or thread name.

   * 'current_count_used'

     The current number of allocated memory blocks that have not been
     freed yet for the thread.

   * 'current_allocated'

     The current number of allocated bytes that have not been freed yet
     for the thread.

   * 'current_avg_alloc'

     The current number of allocated bytes per memory block for the
     thread.

   * 'current_max_alloc'

     The largest single current memory allocation in bytes for the
     thread.

   * 'total_allocated'

     The total memory allocation in bytes for the thread.

26.4.3.18 The memory_by_user_by_current_bytes and x$memory_by_user_by_current_bytes Views
.........................................................................................

These views summarize memory use, grouped by user.  By default, rows are
sorted by descending amount of memory used.

The 'memory_by_user_by_current_bytes'
and
'x$memory_by_user_by_current_bytes'
views have these columns:

   * 'user'

     The client user name.  Rows for which the 'USER' column in the
     underlying Performance Schema table is 'NULL' are assumed to be for
     background threads and are reported with a host name of
     'background'.

   * 'current_count_used'

     The current number of allocated memory blocks that have not been
     freed yet for the user.

   * 'current_allocated'

     The current number of allocated bytes that have not been freed yet
     for the user.

   * 'current_avg_alloc'

     The current number of allocated bytes per memory block for the
     user.

   * 'current_max_alloc'

     The largest single current memory allocation in bytes for the user.

   * 'total_allocated'

     The total memory allocation in bytes for the user.

26.4.3.19 The memory_global_by_current_bytes and x$memory_global_by_current_bytes Views
.......................................................................................

These views summarize memory use, grouped by allocation type (that is,
by event).  By default, rows are sorted by descending amount of memory
used.

The 'memory_global_by_current_bytes'
and
'x$memory_global_by_current_bytes'.
views have these columns:

   * 'event_name'

     The memory event name.

   * 'current_count'

     The total number of occurrences of the event.

   * 'current_alloc'

     The current number of allocated bytes that have not been freed yet
     for the event.

   * 'current_avg_alloc'

     The current number of allocated bytes per memory block for the
     event.

   * 'high_count'

     The high-water mark for number of memory blocks allocated for the
     event.

   * 'high_alloc'

     The high-water mark for number of bytes allocated for the event.

   * 'high_avg_alloc'

     The high-water mark for average number of bytes per memory block
     allocated for the event.

26.4.3.20 The memory_global_total and x$memory_global_total Views
.................................................................

These views summarize total memory use within the server.

The 'memory_global_total' and
'x$memory_global_total' views have these
columns:

   * 'total_allocated'

     The total bytes of memory allocated within the server.

26.4.3.21 The metrics View
..........................

This view summarizes MySQL server metrics to show variable names,
values, types, and whether they are enabled.  By default, rows are
sorted by variable type and name.

This view was added in MySQL 5.7.9.

The 'metrics' view includes this information:

   * Global status variables from the Performance Schema
     'global_status' table

   * 'InnoDB' metrics from the 'INFORMATION_SCHEMA'
     'INNODB_METRICS' table

   * Current and total memory allocation, based on the Performance
     Schema memory instrumentation

   * The current time (human readable and Unix timestamp formats)

There is some duplication of information between the
'global_status' and
'INNODB_METRICS' tables, which the
'metrics' view eliminates.

The 'metrics' view has these columns:

   * 'Variable_name'

     The metric name.  The metric type determines the source from which
     the name is taken:

        * For global status variables: The 'VARIABLE_NAME' column of the
          'global_status'
          table

        * For 'InnoDB' metrics: The 'NAME' column of the
          'INNODB_METRICS' table

        * For other metrics: A view-provided descriptive string

   * 'Variable_value'

     The metric value.  The metric type determines the source from which
     the value is taken:

        * For global status variables: The 'VARIABLE_VALUE' column of
          the 'global_status'
          table

        * For 'InnoDB' metrics: The 'COUNT' column of the
          'INNODB_METRICS' table

        * For memory metrics: The relevant column from the Performance
          Schema 'memory_summary_global_by_event_name'
          table

        * For the current time: The value of 'NOW(3)' or
          'UNIX_TIMESTAMP(NOW(3))'

   * 'Type'

     The metric type:

        * For global status variables: 'Global Status'

        * For 'InnoDB' metrics: 'InnoDB Metrics - %', where '%' is
          replaced by the value of the 'SUBSYSTEM' column of the
          'INNODB_METRICS' table

        * For memory metrics: 'Performance Schema'

        * For the current time: 'System Time'

   * 'Enabled'

     Whether the metric is enabled:

        * For global status variables: 'YES'

        * For 'InnoDB' metrics: 'YES' if the 'STATUS' column of the
          'INNODB_METRICS' table is
          'enabled', 'NO' otherwise

        * For memory metrics: 'NO', 'YES', or 'PARTIAL' (currently,
          'PARTIAL' occurs only for memory metrics and indicates that
          not all 'memory/%' instruments are enabled; Performance Schema
          memory instruments are always enabled)

        * For the current time: 'YES'

26.4.3.22 The processlist and x$processlist Views
.................................................

These views summarize processlist information.  They provide more
complete information than the 'SHOW PROCESSLIST'
statement and the 'INFORMATION_SCHEMA'
'PROCESSLIST' table, and are also nonblocking.  By
default, rows are sorted by descending process time and descending wait
time.

The column descriptions here are brief.  For additional information, see
the description of the Performance Schema 'threads'
table at threads-table.

The 'processlist' and 'x$processlist'
views have these columns:

   * 'thd_id'

     The thread ID.

   * 'conn_id'

     The connection ID.

   * 'user'

     The thread user or thread name.

   * 'db'

     The default database for the thread, or 'NULL' if there is none.

   * 'command'

     For foreground threads, the type of command the thread is executing
     on behalf of the client, or 'Sleep' if the session is idle.

   * 'state'

     An action, event, or state that indicates what the thread is doing.

   * 'time'

     The time in seconds that the thread has been in its current state.

   * 'current_statement'

     The statement the thread is executing, or 'NULL' if it is not
     executing any statement.

   * 'statement_latency'

     How long the statement has been executing.

     This column was added in MySQL 5.7.9.

   * 'progress'

     The percentage of work completed for stages that support progress
     reporting.  See sys-schema-progress-reporting.

     This column was added in MySQL 5.7.9.

   * 'lock_latency'

     The time spent waiting for locks by the current statement.

   * 'rows_examined'

     The number of rows read from storage engines by the current
     statement.

   * 'rows_sent'

     The number of rows returned by the current statement.

   * 'rows_affected'

     The number of rows affected by the current statement.

   * 'tmp_tables'

     The number of internal in-memory temporary tables created by the
     current statement.

   * 'tmp_disk_tables'

     The number of internal on-disk temporary tables created by the
     current statement.

   * 'full_scan'

     The number of full table scans performed by the current statement.

   * 'last_statement'

     The last statement executed by the thread, if there is no currently
     executing statement or wait.

   * 'last_statement_latency'

     How long the last statement executed.

   * 'current_memory'

     The number of bytes allocated by the thread.

   * 'last_wait'

     The name of the most recent wait event for the thread.

   * 'last_wait_latency'

     The wait time of the most recent wait event for the thread.

   * 'source'

     The source file and line number containing the instrumented code
     that produced the event.

   * 'trx_latency'

     The wait time of the current transaction for the thread.

     This column was added in MySQL 5.7.9.

   * 'trx_state'

     The state for the current transaction for the thread.

     This column was added in MySQL 5.7.9.

   * 'trx_autocommit'

     Whether autocommit mode was enabled when the current transaction
     started.

     This column was added in MySQL 5.7.9.

   * 'pid'

     The client process ID.

     This column was added in MySQL 5.7.9.

   * 'program_name'

     The client program name.

     This column was added in MySQL 5.7.9.

26.4.3.23 The ps_check_lost_instrumentation View
................................................

This view returns information about lost Performance Schema instruments,
to indicate whether the Performance Schema is unable to monitor all
runtime data.

The 'ps_check_lost_instrumentation'
view has these columns:

   * 'variable_name'

     The Performance Schema status variable name indicating which type
     of instrument was lost.

   * 'variable_value'

     The number of instruments lost.

26.4.3.24 The schema_auto_increment_columns View
................................................

This view indicates which tables have 'AUTO_INCREMENT' columns and
provides information about those columns, such as the current and
maximum column values and the usage ratio (ratio of used to possible
values).  By default, rows are sorted by descending usage ratio and
maximum column value.

Tables in these schemas are excluded from view output: 'mysql', 'sys',
'INFORMATION_SCHEMA', 'performance_schema'.

This view was added in MySQL 5.7.9.

The 'schema_auto_increment_columns'
view has these columns:

   * 'table_schema'

     The schema that contains the table.

   * 'table_name'

     The table that contains the 'AUTO_INCREMENT' column.

   * 'column_name'

     The name of the 'AUTO_INCREMENT' column.

   * 'data_type'

     The data type of the column.

   * 'column_type'

     The column type of the column, which is the data type plus possibly
     other information.  For example, for a column with a 'bigint(20)
     unsigned' column type, the data type is just 'bigint'.

   * 'is_signed'

     Whether the column type is signed.

   * 'is_unsigned'

     Whether the column type is unsigned.

   * 'max_value'

     The maximum permitted value for the column.

   * 'auto_increment'

     The current 'AUTO_INCREMENT' value for the column.

   * 'auto_increment_ratio'

     The ratio of used to permitted values for the column.  This
     indicates how much of the sequence of values is 'used up.'

26.4.3.25 The schema_index_statistics and x$schema_index_statistics Views
.........................................................................

These views provide index statistics.  By default, rows are sorted by
descending total index latency.

The 'schema_index_statistics' and
'x$schema_index_statistics' views
have these columns:

   * 'table_schema'

     The schema that contains the table.

   * 'table_name'

     The table that contains the index.

   * 'index_name'

     The name of the index.

   * 'rows_selected'

     The total number of rows read using the index.

   * 'select_latency'

     The total wait time of timed reads using the index.

   * 'rows_inserted'

     The total number of rows inserted into the index.

   * 'insert_latency'

     The total wait time of timed inserts into the index.

   * 'rows_updated'

     The total number of rows updated in the index.

   * 'update_latency'

     The total wait time of timed updates in the index.

   * 'rows_deleted'

     The total number of rows deleted from the index.

   * 'delete_latency'

     The total wait time of timed deletes from the index.

26.4.3.26 The schema_object_overview View
.........................................

This view summarizes the types of objects within each schema.  By
default, rows are sorted by schema and object type.

*Note*:

For MySQL instances with a large number of objects, this view might take
a long time to execute.

The 'schema_object_overview' view has
these columns:

   * 'db'

     The schema name.

   * 'object_type'

     The object type: 'BASE TABLE', 'INDEX (INDEX_TYPE)', 'EVENT',
     'FUNCTION', 'PROCEDURE', 'TRIGGER', 'VIEW'.

   * 'count'

     The number of objects in the schema of the given type.

26.4.3.27 The schema_redundant_indexes and x$schema_flattened_keys Views
........................................................................

The 'schema_redundant_indexes' view
displays indexes that duplicate other indexes or are made redundant by
them.  The 'x$schema_flattened_keys'
view is a helper view for
'schema_redundant_indexes'.

These views were added in MySQL 5.7.9.

In the following column descriptions, the dominant index is the one that
makes the redundant index redundant.

The 'schema_redundant_indexes' view
has these columns:

   * 'table_schema'

     The schema that contains the table.

   * 'table_name'

     The table that contains the index.

   * 'redundant_index_name'

     The name of the redundant index.

   * 'redundant_index_columns'

     The names of the columns in the redundant index.

   * 'redundant_index_non_unique'

     The number of nonunique columns in the redundant index.

   * 'dominant_index_name'

     The name of the dominant index.

   * 'dominant_index_columns'

     The names of the columns in the dominant index.

   * 'dominant_index_non_unique'

     The number of nonunique columns in the dominant index.

   * 'subpart_exists'

     Whether the index indexes only part of a column.

   * 'sql_drop_index'

     The statement to execute to drop the redundant index.

The 'x$schema_flattened_keys' view
has these columns:

   * 'table_schema'

     The schema that contains the table.

   * 'table_name'

     The table that contains the index.

   * 'index_name'

     An index name.

   * 'non_unique'

     The number of nonunique columns in the index.

   * 'subpart_exists'

     Whether the index indexes only part of a column.

   * 'index_columns'

     The name of the columns in the index.

26.4.3.28 The schema_table_lock_waits and x$schema_table_lock_waits Views
.........................................................................

These views display which sessions are blocked waiting on metadata
locks, and what is blocking them.

These views were added in MySQL 5.7.9.

The column descriptions here are brief.  For additional information, see
the description of the Performance Schema 'metadata_locks'
table at metadata-locks-table.

The 'schema_table_lock_waits' and
'x$schema_table_lock_waits' views
have these columns:

   * 'object_schema'

     The schema containing the object to be locked.

   * 'object_name'

     The name of the instrumented object.

   * 'waiting_thread_id'

     The thread ID of the thread that is waiting for the lock.

   * 'waiting_pid'

     The processlist ID of the thread that is waiting for the lock.

   * 'waiting_account'

     The account associated with the session that is waiting for the
     lock.

   * 'waiting_lock_type'

     The type of the waiting lock.

   * 'waiting_lock_duration'

     How long the waiting lock has been waiting.

   * 'waiting_query'

     The statement that is waiting for the lock.

   * 'waiting_query_secs'

     How long the statement has been waiting, in seconds.

   * 'waiting_query_rows_affected'

     The number of rows affected by the statement.

   * 'waiting_query_rows_examined'

     The number of rows read from storage engines by the statement.

   * 'blocking_thread_id'

     The thread ID of the thread that is blocking the waiting lock.

   * 'blocking_pid'

     The processlist ID of the thread that is blocking the waiting lock.

   * 'blocking_account'

     The account associated with the thread that is blocking the waiting
     lock.

   * 'blocking_lock_type'

     The type of lock that is blocking the waiting lock.

   * 'blocking_lock_duration'

     How long the blocking lock has been held.

   * 'sql_kill_blocking_query'

     The 'KILL' statement to execute to kill the blocking
     statement.

   * 'sql_kill_blocking_connection'

     The 'KILL' statement to execute to kill the session
     running the blocking statement.

26.4.3.29 The schema_table_statistics and x$schema_table_statistics Views
.........................................................................

These views summarize table statistics.  By default, rows are sorted by
descending total wait time (tables with most contention first).

These views user a helper view, 'x$ps_schema_table_statistics_io'.

The 'schema_table_statistics' and
'x$schema_table_statistics' views
have these columns:

   * 'table_schema'

     The schema that contains the table.

   * 'table_name'

     The table name.

   * 'total_latency'

     The total wait time of timed I/O events for the table.

   * 'rows_fetched'

     The total number of rows read from the table.

   * 'fetch_latency'

     The total wait time of timed read I/O events for the table.

   * 'rows_inserted'

     The total number of rows inserted into the table.

   * 'insert_latency'

     The total wait time of timed insert I/O events for the table.

   * 'rows_updated'

     The total number of rows updated in the table.

   * 'update_latency'

     The total wait time of timed update I/O events for the table.

   * 'rows_deleted'

     The total number of rows deleted from the table.

   * 'delete_latency'

     The total wait time of timed delete I/O events for the table.

   * 'io_read_requests'

     The total number of read requests for the table.

   * 'io_read'

     The total number of bytes read from the table.

   * 'io_read_latency'

     The total wait time of reads from the table.

   * 'io_write_requests'

     The total number of write requests for the table.

   * 'io_write'

     The total number of bytes written to the table.

   * 'io_write_latency'

     The total wait time of writes to the table.

   * 'io_misc_requests'

     The total number of miscellaneous I/O requests for the table.

   * 'io_misc_latency'

     The total wait time of miscellaneous I/O requests for the table.

26.4.3.30 The schema_table_statistics_with_buffer and x$schema_table_statistics_with_buffer Views
.................................................................................................

These views summarize table statistics, including 'InnoDB' buffer pool
statistics.  By default, rows are sorted by descending total wait time
(tables with most contention first).

These views user a helper view, 'x$ps_schema_table_statistics_io'.

The 'schema_table_statistics_with_buffer'
and
'x$schema_table_statistics_with_buffer'
views have these columns:

   * 'table_schema'

     The schema that contains the table.

   * 'table_name'

     The table name.

   * 'rows_fetched'

     The total number of rows read from the table.

   * 'fetch_latency'

     The total wait time of timed read I/O events for the table.

   * 'rows_inserted'

     The total number of rows inserted into the table.

   * 'insert_latency'

     The total wait time of timed insert I/O events for the table.

   * 'rows_updated'

     The total number of rows updated in the table.

   * 'update_latency'

     The total wait time of timed update I/O events for the table.

   * 'rows_deleted'

     The total number of rows deleted from the table.

   * 'delete_latency'

     The total wait time of timed delete I/O events for the table.

   * 'io_read_requests'

     The total number of read requests for the table.

   * 'io_read'

     The total number of bytes read from the table.

   * 'io_read_latency'

     The total wait time of reads from the table.

   * 'io_write_requests'

     The total number of write requests for the table.

   * 'io_write'

     The total number of bytes written to the table.

   * 'io_write_latency'

     The total wait time of writes to the table.

   * 'io_misc_requests'

     The total number of miscellaneous I/O requests for the table.

   * 'io_misc_latency'

     The total wait time of miscellaneous I/O requests for the table.

   * 'innodb_buffer_allocated'

     The total number of 'InnoDB' buffer bytes allocated for the table.

   * 'innodb_buffer_data'

     The total number of 'InnoDB' data bytes allocated for the table.

   * 'innodb_buffer_free'

     The total number of 'InnoDB' nondata bytes allocated for the table
     ('innodb_buffer_allocated' − 'innodb_buffer_data').

   * 'innodb_buffer_pages'

     The total number of 'InnoDB' pages allocated for the table.

   * 'innodb_buffer_pages_hashed'

     The total number of 'InnoDB' hashed pages allocated for the table.

   * 'innodb_buffer_pages_old'

     The total number of 'InnoDB' old pages allocated for the table.

   * 'innodb_buffer_rows_cached'

     The total number of 'InnoDB' cached rows for the table.

26.4.3.31 The schema_tables_with_full_table_scans and x$schema_tables_with_full_table_scans Views
.................................................................................................

These views display which tables are being accessed with full table
scans.  By default, rows are sorted by descending rows scanned.

The 'schema_tables_with_full_table_scans'
and
'x$schema_tables_with_full_table_scans'
views have these columns:

   * 'object_schema'

     The schema name.

   * 'object_name'

     The table name.

   * 'rows_full_scanned'

     The total number of rows scanned by full scans of the table.

   * 'latency'

     The total wait time of full scans of the table.

26.4.3.32 The schema_unused_indexes View
........................................

These views display indexes for which there are no events, which
indicates that they are not being used.  By default, rows are sorted by
schema and table.

This view is most useful when the server has been up and processing long
enough that its workload is representative.  Otherwise, presence of an
index in this view may not be meaningful.

The 'schema_unused_indexes' view has
these columns:

   * 'object_schema'

     The schema name.

   * 'object_name'

     The table name.

   * 'index_name'

     The unused index name.

26.4.3.33 The session and x$session Views
.........................................

These views are similar to 'processlist' and
'x$processlist', but they filter out background
processes to display only user sessions.  For descriptions of the
columns, see sys-processlist.

These views were added in MySQL 5.7.9.

26.4.3.34 The session_ssl_status View
.....................................

For each connection, this view displays the SSL version, cipher, and
count of reused SSL sessions.

This view was added in MySQL 5.7.9.

The 'session_ssl_status' view has these
columns:

   * 'thread_id'

     The thread ID for the connection.

   * 'ssl_version'

     The version of SSL used for the connection.

   * 'ssl_cipher'

     The SSL cipher used for the connection.

   * 'ssl_sessions_reused'

     The number of reused SSL sessions for the connection.

26.4.3.35 The statement_analysis and x$statement_analysis Views
...............................................................

These views list normalized statements with aggregated statistics.  The
content mimics the MySQL Enterprise Monitor Query Analysis view.  By
default, rows are sorted by descending total latency.

The 'statement_analysis' and
'x$statement_analysis' views have these
columns:

   * 'query'

     The normalized statement string.

   * 'db'

     The default database for the statement, or 'NULL' if there is none.

   * 'full_scan'

     The total number of full table scans performed by occurrences of
     the statement.

   * 'exec_count'

     The total number of times the statement has executed.

   * 'err_count'

     The total number of errors produced by occurrences of the
     statement.

   * 'warn_count'

     The total number of warnings produced by occurrences of the
     statement.

   * 'total_latency'

     The total wait time of timed occurrences of the statement.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the statement.

   * 'avg_latency'

     The average wait time per timed occurrence of the statement.

   * 'lock_latency'

     The total time waiting for locks by timed occurrences of the
     statement.

   * 'rows_sent'

     The total number of rows returned by occurrences of the statement.

   * 'rows_sent_avg'

     The average number of rows returned per occurrence of the
     statement.

   * 'rows_examined'

     The total number of rows read from storage engines by occurrences
     of the statement.

   * 'rows_examined_avg'

     The average number of rows read from storage engines per occurrence
     of the statement.

   * 'rows_affected'

     The total number of rows affected by occurrences of the statement.

   * 'rows_affected_avg'

     The average number of rows affected per occurrence of the
     statement.

   * 'tmp_tables'

     The total number of internal in-memory temporary tables created by
     occurrences of the statement.

   * 'tmp_disk_tables'

     The total number of internal on-disk temporary tables created by
     occurrences of the statement.

   * 'rows_sorted'

     The total number of rows sorted by occurrences of the statement.

   * 'sort_merge_passes'

     The total number of sort merge passes by occurrences of the
     statement.

   * 'digest'

     The statement digest.

   * 'first_seen'

     The time at which the statement was first seen.

   * 'last_seen'

     The time at which the statement was most recently seen.

26.4.3.36 The statements_with_errors_or_warnings and x$statements_with_errors_or_warnings Views
...............................................................................................

These views display normalized statements that have produced errors or
warnings.  By default, rows are sorted by descending error and warning
counts.

The 'statements_with_errors_or_warnings'
and
'x$statements_with_errors_or_warnings'
views have these columns:

   * 'query'

     The normalized statement string.

   * 'db'

     The default database for the statement, or 'NULL' if there is none.

   * 'exec_count'

     The total number of times the statement has executed.

   * 'errors'

     The total number of errors produced by occurrences of the
     statement.

   * 'error_pct'

     The percentage of statement occurrences that produced errors.

   * 'warnings'

     The total number of warnings produced by occurrences of the
     statement.

   * 'warning_pct'

     The percentage of statement occurrences that produced warnings.

   * 'first_seen'

     The time at which the statement was first seen.

   * 'last_seen'

     The time at which the statement was most recently seen.

   * 'digest'

     The statement digest.

26.4.3.37 The statements_with_full_table_scans and x$statements_with_full_table_scans Views
...........................................................................................

These views display normalized statements that have done full table
scans.  By default, rows are sorted by descending percentage of time a
full scan was done and descending total latency.

The 'statements_with_full_table_scans'
and
'x$statements_with_full_table_scans'
views have these columns:

   * 'query'

     The normalized statement string.

   * 'db'

     The default database for the statement, or 'NULL' if there is none.

   * 'exec_count'

     The total number of times the statement has executed.

   * 'total_latency'

     The total wait time of timed statement events for the statement.

   * 'no_index_used_count'

     The total number of times no index was used to scan the table.

   * 'no_good_index_used_count'

     The total number of times no good index was used to scan the table.

   * 'no_index_used_pct'

     The percentage of the time no index was used to scan the table.

   * 'rows_sent'

     The total number of rows returned from the table.

   * 'rows_examined'

     The total number of rows read from the storage engine for the
     table.

   * 'rows_sent_avg'

     The average number of rows returned from the table.

   * 'rows_examined_avg'

     The average number of rows read from the storage engine for the
     table.

   * 'first_seen'

     The time at which the statement was first seen.

   * 'last_seen'

     The time at which the statement was most recently seen.

   * 'digest'

     The statement digest.

26.4.3.38 The statements_with_runtimes_in_95th_percentile and x$statements_with_runtimes_in_95th_percentile Views
.................................................................................................................

These views list statements with runtimes in the 95th percentile.  By
default, rows are sorted by descending average latency.

Both views use two helper views, 'x$ps_digest_avg_latency_distribution'
and 'x$ps_digest_95th_percentile_by_avg_us'.

The 'statements_with_runtimes_in_95th_percentile'
and
'x$statements_with_runtimes_in_95th_percentile'
views have these
columns:

   * 'query'

     The normalized statement string.

   * 'db'

     The default database for the statement, or 'NULL' if there is none.

   * 'full_scan'

     The total number of full table scans performed by occurrences of
     the statement.

   * 'exec_count'

     The total number of times the statement has executed.

   * 'err_count'

     The total number of errors produced by occurrences of the
     statement.

   * 'warn_count'

     The total number of warnings produced by occurrences of the
     statement.

   * 'total_latency'

     The total wait time of timed occurrences of the statement.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the statement.

   * 'avg_latency'

     The average wait time per timed occurrence of the statement.

   * 'rows_sent'

     The total number of rows returned by occurrences of the statement.

   * 'rows_sent_avg'

     The average number of rows returned per occurrence of the
     statement.

   * 'rows_examined'

     The total number of rows read from storage engines by occurrences
     of the statement.

   * 'rows_examined_avg'

     The average number of rows read from storage engines per occurrence
     of the statement.

   * 'first_seen'

     The time at which the statement was first seen.

   * 'last_seen'

     The time at which the statement was most recently seen.

   * 'digest'

     The statement digest.

26.4.3.39 The statements_with_sorting and x$statements_with_sorting Views
.........................................................................

These views list normalized statements that have performed sorts.  By
default, rows are sorted by descending total latency.

The 'statements_with_sorting' and
'x$statements_with_sorting' views
have these columns:

   * 'query'

     The normalized statement string.

   * 'db'

     The default database for the statement, or 'NULL' if there is none.

   * 'exec_count'

     The total number of times the statement has executed.

   * 'total_latency'

     The total wait time of timed occurrences of the statement.

   * 'sort_merge_passes'

     The total number of sort merge passes by occurrences of the
     statement.

   * 'avg_sort_merges'

     The average number of sort merge passes per occurrence of the
     statement.

   * 'sorts_using_scans'

     The total number of sorts using table scans by occurrences of the
     statement.

   * 'sort_using_range'

     The total number of sorts using range accesses by occurrences of
     the statement.

   * 'rows_sorted'

     The total number of rows sorted by occurrences of the statement.

   * 'avg_rows_sorted'

     The average number of rows sorted per occurrence of the statement.

   * 'first_seen'

     The time at which the statement was first seen.

   * 'last_seen'

     The time at which the statement was most recently seen.

   * 'digest'

     The statement digest.

26.4.3.40 The statements_with_temp_tables and x$statements_with_temp_tables Views
.................................................................................

These views list normalized statements that have used temporary tables.
By default, rows are sorted by descending number of on-disk temporary
tables used and descending number of in-memory temporary tables used.

The 'statements_with_temp_tables'
and
'x$statements_with_temp_tables' views
have these columns:

   * 'query'

     The normalized statement string.

   * 'db'

     The default database for the statement, or 'NULL' if there is none.

   * 'exec_count'

     The total number of times the statement has executed.

   * 'total_latency'

     The total wait time of timed occurrences of the statement.

   * 'memory_tmp_tables'

     The total number of internal in-memory temporary tables created by
     occurrences of the statement.

   * 'disk_tmp_tables'

     The total number of internal on-disk temporary tables created by
     occurrences of the statement.

   * 'avg_tmp_tables_per_query'

     The average number of internal temporary tables created per
     occurrence of the statement.

   * 'tmp_tables_to_disk_pct'

     The percentage of internal in-memory temporary tables that were
     converted to on-disk tables.

   * 'first_seen'

     The time at which the statement was first seen.

   * 'last_seen'

     The time at which the statement was most recently seen.

   * 'digest'

     The statement digest.

26.4.3.41 The user_summary and x$user_summary Views
...................................................

These views summarize statement activity, file I/O, and connections,
grouped by user.  By default, rows are sorted by descending total
latency.

The 'user_summary' and 'x$user_summary'
views have these columns:

   * 'user'

     The client user name.  Rows for which the 'USER' column in the
     underlying Performance Schema table is 'NULL' are assumed to be for
     background threads and are reported with a host name of
     'background'.

   * 'statements'

     The total number of statements for the user.

   * 'statement_latency'

     The total wait time of timed statements for the user.

   * 'statement_avg_latency'

     The average wait time per timed statement for the user.

   * 'table_scans'

     The total number of table scans for the user.

   * 'file_ios'

     The total number of file I/O events for the user.

   * 'file_io_latency'

     The total wait time of timed file I/O events for the user.

   * 'current_connections'

     The current number of connections for the user.

   * 'total_connections'

     The total number of connections for the user.

   * 'unique_hosts'

     The number of distinct hosts from which connections for the user
     have originated.

   * 'current_memory'

     The current amount of allocated memory for the user.

   * 'total_memory_allocated'

     The total amount of allocated memory for the user.

26.4.3.42 The user_summary_by_file_io and x$user_summary_by_file_io Views
.........................................................................

These views summarize file I/O, grouped by user.  By default, rows are
sorted by descending total file I/O latency.

The 'user_summary_by_file_io' and
'x$user_summary_by_file_io' views
have these columns:

   * 'user'

     The client user name.  Rows for which the 'USER' column in the
     underlying Performance Schema table is 'NULL' are assumed to be for
     background threads and are reported with a host name of
     'background'.

   * 'ios'

     The total number of file I/O events for the user.

   * 'io_latency'

     The total wait time of timed file I/O events for the user.

26.4.3.43 The user_summary_by_file_io_type and x$user_summary_by_file_io_type Views
...................................................................................

These views summarize file I/O, grouped by user and event type.  By
default, rows are sorted by user and descending total latency.

The 'user_summary_by_file_io_type'
and
'x$user_summary_by_file_io_type'.
views have these columns:

   * 'user'

     The client user name.  Rows for which the 'USER' column in the
     underlying Performance Schema table is 'NULL' are assumed to be for
     background threads and are reported with a host name of
     'background'.

   * 'event_name'

     The file I/O event name.

   * 'total'

     The total number of occurrences of the file I/O event for the user.

   * 'latency'

     The total wait time of timed occurrences of the file I/O event for
     the user.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the file I/O
     event for the user.

26.4.3.44 The user_summary_by_stages and x$user_summary_by_stages Views
.......................................................................

These views summarize stages, grouped by user.  By default, rows are
sorted by user and descending total stage latency.

The 'user_summary_by_stages' and
'x$user_summary_by_stages' views have
these columns:

   * 'user'

     The client user name.  Rows for which the 'USER' column in the
     underlying Performance Schema table is 'NULL' are assumed to be for
     background threads and are reported with a host name of
     'background'.

   * 'event_name'

     The stage event name.

   * 'total'

     The total number of occurrences of the stage event for the user.

   * 'total_latency'

     The total wait time of timed occurrences of the stage event for the
     user.

   * 'avg_latency'

     The average wait time per timed occurrence of the stage event for
     the user.

26.4.3.45 The user_summary_by_statement_latency and x$user_summary_by_statement_latency Views
.............................................................................................

These views summarize overall statement statistics, grouped by user.  By
default, rows are sorted by descending total latency.

The 'user_summary_by_statement_latency'
and
'x$user_summary_by_statement_latency'
views have these columns:

   * 'user'

     The client user name.  Rows for which the 'USER' column in the
     underlying Performance Schema table is 'NULL' are assumed to be for
     background threads and are reported with a host name of
     'background'.

   * 'total'

     The total number of statements for the user.

   * 'total_latency'

     The total wait time of timed statements for the user.

   * 'max_latency'

     The maximum single wait time of timed statements for the user.

   * 'lock_latency'

     The total time waiting for locks by timed statements for the user.

   * 'rows_sent'

     The total number of rows returned by statements for the user.

   * 'rows_examined'

     The total number of rows read from storage engines by statements
     for the user.

   * 'rows_affected'

     The total number of rows affected by statements for the user.

   * 'full_scans'

     The total number of full table scans by statements for the user.

26.4.3.46 The user_summary_by_statement_type and x$user_summary_by_statement_type Views
.......................................................................................

These views summarize informaion about statements executed, grouped by
user and statement type.  By default, rows are sorted by user and
descending total latency.

The 'user_summary_by_statement_type'
and
'x$user_summary_by_statement_type'.
views have these columns:

   * 'user'

     The client user name.  Rows for which the 'USER' column in the
     underlying Performance Schema table is 'NULL' are assumed to be for
     background threads and are reported with a host name of
     'background'.

   * 'statement'

     The final component of the statement event name.

   * 'total'

     The total number of occurrences of the statement event for the
     user.

   * 'total_latency'

     The total wait time of timed occurrences of the statement event for
     the user.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the statement
     event for the user.

   * 'lock_latency'

     The total time waiting for locks by timed occurrences of the
     statement event for the user.

   * 'rows_sent'

     The total number of rows returned by occurrences of the statement
     event for the user.

   * 'rows_examined'

     The total number of rows read from storage engines by occurrences
     of the statement event for the user.

   * 'rows_affected'

     The total number of rows affected by occurrences of the statement
     event for the user.

   * 'full_scans'

     The total number of full table scans by occurrences of the
     statement event for the user.

26.4.3.47 The version View
..........................

This view provides the current 'sys' schema and MySQL
server versions.

The 'version' view has these columns:

   * 'sys_version'

     The 'sys' schema version.

   * 'mysql_version'

     The MySQL server version.

26.4.3.48 The wait_classes_global_by_avg_latency and x$wait_classes_global_by_avg_latency Views
...............................................................................................

These views summarize wait class average latencies, grouped by event
class.  By default, rows are sorted by descending average latency.  Idle
events are ignored.

An event class is determined by stripping from the event name everything
after the first three components.  For example, the class for
'wait/io/file/sql/slow_log' is 'wait/io/file'.

The 'wait_classes_global_by_avg_latency'
and
'x$wait_classes_global_by_avg_latency'
views have these columns:

   * 'event_class'

     The event class.

   * 'total'

     The total number of occurrences of events in the class.

   * 'total_latency'

     The total wait time of timed occurrences of events in the class.

   * 'min_latency'

     The minimum single wait time of timed occurrences of events in the
     class.

   * 'avg_latency'

     The average wait time per timed occurrence of events in the class.

   * 'max_latency'

     The maximum single wait time of timed occurrences of events in the
     class.

26.4.3.49 The wait_classes_global_by_latency and x$wait_classes_global_by_latency Views
.......................................................................................

These views summarize wait class total latencies, grouped by event
class.  By default, rows are sorted by descending total latency.  Idle
events are ignored.

An event class is determined by stripping from the event name everything
after the first three components.  For example, the class for
'wait/io/file/sql/slow_log' is 'wait/io/file'.

The 'wait_classes_global_by_latency'
and
'x$wait_classes_global_by_latency'.
views have these columns:

   * 'event_class'

     The event class.

   * 'total'

     The total number of occurrences of events in the class.

   * 'total_latency'

     The total wait time of timed occurrences of events in the class.

   * 'min_latency'

     The minimum single wait time of timed occurrences of events in the
     class.

   * 'avg_latency'

     The average wait time per timed occurrence of events in the class.

   * 'max_latency'

     The maximum single wait time of timed occurrences of events in the
     class.

26.4.3.50 The waits_by_host_by_latency and x$waits_by_host_by_latency Views
...........................................................................

These views summarize wait events, grouped by host and event.  By
default, rows are sorted by host and descending total latency.  Idle
events are ignored.

The 'waits_by_host_by_latency' and
'x$waits_by_host_by_latency' views
have these columns:

   * 'host'

     The host from which the connection originated.

   * 'event'

     The event name.

   * 'total'

     The total number of occurrences of the event for the host.

   * 'total_latency'

     The total wait time of timed occurrences of the event for the host.

   * 'avg_latency'

     The average wait time per timed occurrence of the event for the
     host.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the event for
     the host.

26.4.3.51 The waits_by_user_by_latency and x$waits_by_user_by_latency Views
...........................................................................

These views summarize wait events, grouped by user and event.  By
default, rows are sorted by user and descending total latency.  Idle
events are ignored.

The 'waits_by_user_by_latency' and
'x$waits_by_user_by_latency' views
have these columns:

   * 'user'

     The user associated with the connection.

   * 'event'

     The event name.

   * 'total'

     The total number of occurrences of the event for the user.

   * 'total_latency'

     The total wait time of timed occurrences of the event for the user.

   * 'avg_latency'

     The average wait time per timed occurrence of the event for the
     user.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the event for
     the user.

26.4.3.52 The waits_global_by_latency and x$waits_global_by_latency Views
.........................................................................

These views summarize wait events, grouped by event.  By default, rows
are sorted by descending total latency.  Idle events are ignored.

The 'waits_global_by_latency' and
'x$waits_global_by_latency' views
have these columns:

   * 'events'

     The event name.

   * 'total'

     The total number of occurrences of the event.

   * 'total_latency'

     The total wait time of timed occurrences of the event.

   * 'avg_latency'

     The average wait time per timed occurrence of the event.

   * 'max_latency'

     The maximum single wait time of timed occurrences of the event.

26.4.4 sys Schema Stored Procedures
-----------------------------------

The following sections describe 'sys' schema stored
procedures.

26.4.4.1 The create_synonym_db() Procedure
..........................................

Given a schema name, this procedure creates a synonym schema containing
views that refer to all the tables and views in the original schema.
This can be used, for example, to create a shorter name by which to
refer to a schema with a long name (such as 'info' rather than
'INFORMATION_SCHEMA').

*Parameters*

   * 'in_db_name VARCHAR(64)': The name of the schema for which to
     create the synonym.

   * 'in_synonym VARCHAR(64)': The name to use for the synonym schema.
     This schema must not already exist.

*Example*

     mysql> SHOW DATABASES;
     +--------------------+
     | Database           |
     +--------------------+
     | information_schema |
     | mysql              |
     | performance_schema |
     | sys                |
     | world              |
     +--------------------+
     mysql> CALL create_synonym_db('INFORMATION_SCHEMA', 'info');
     +---------------------------------------+
     | summary                               |
     +---------------------------------------+
     | Created 63 views in the info database |
     +---------------------------------------+
     mysql> SHOW DATABASES;
     +--------------------+
     | Database           |
     +--------------------+
     | information_schema |
     | info               |
     | mysql              |
     | performance_schema |
     | sys                |
     | world              |
     +--------------------+
     mysql> SHOW FULL TABLES FROM info;
     +---------------------------------------+------------+
     | Tables_in_info                        | Table_type |
     +---------------------------------------+------------+
     | character_sets                        | VIEW       |
     | collation_character_set_applicability | VIEW       |
     | collations                            | VIEW       |
     | column_privileges                     | VIEW       |
     | columns                               | VIEW       |
     ...

26.4.4.2 The diagnostics() Procedure
....................................

Creates a report of the current server status for diagnostic purposes.

This procedure requires the 'SUPER' privilege because it manipulates the
session 'sql_log_bin' system variable to disable binary logging during
its execution.

Data collected for 'diagnostics()' includes this
information:

   * Information from the 'metrics' view (see
     sys-metrics)

   * Information from other relevant 'sys' schema views, such as the one
     that detemines queries in the 95th percentile

   * Information from the 'ndbinfo' schema, if the MySQL server is part
     of NDB Cluster

   * Replication status (both master and slave)

Some of the sys schema views are calculated as initial (optional),
overall, and delta values:

   * The initial view is the content of the view at the start of the
     'diagnostics()' procedure.  This output is
     the same as the start values used for the delta view.  The initial
     view is included if the 'diagnostics.include_raw' configuration
     option is 'ON'.

   * The overall view is the content of the view at the end of the
     'diagnostics()' procedure.  This output is the
     same as the end values used for the delta view.  The overall view
     is always included.

   * The delta view is the difference from the beginning to the end of
     procedure execution.  The minimum and maximum values are the
     minimum and maximum values from the end view, respectively.  They
     do not necessarily reflect the minimum and maximum values in the
     monitored period.  Except for the 'metrics'.
     view, the delta is calculated only between the first and last
     outputs.

*Parameters*

   * 'in_max_runtime INT UNSIGNED': The maximum data collection time in
     seconds.  Use 'NULL' to collect data for the default of 60 seconds.
     Otherwise, use a value greater than 0.

   * 'in_interval INT UNSIGNED': The sleep time between data collections
     in seconds.  Use 'NULL' to sleep for the default of 30 seconds.
     Otherwise, use a value greater than 0.

   * 'in_auto_config ENUM('current', 'medium', 'full')': The Performance
     Schema configuration to use.  Permitted values are:

        * 'current': Use the current instrument and consumer settings.

        * 'medium': Enable some instruments and consumers.

        * 'full': Enable all instruments and consumers.

     *Note*:

     The more instruments and consumers enabled, the more impact on
     MySQL server performance.  Be careful with the 'medium' setting and
     especially the 'full' setting, which has a large performance
     impact.

     Use of the 'medium' or 'full' setting requires the 'SUPER'
     privilege.

     If a setting other than 'current' is chosen, the current settings
     are restored at the end of the procedure.

*Configuration Options*

'diagnostics()' operation can be modified using
the following configuration options or their corresponding user-defined
variables (see sys-sys-config):

   * 'debug', '@sys.debug'

     If this option is 'ON', produce debugging output.  The default is
     'OFF'.

   * 'diagnostics.allow_i_s_tables', '@sys.diagnostics.allow_i_s_tables'

     If this option is 'ON', the 'diagnostics()'.
     procedure is permitted to perform table scans on the
     'INFORMATION_SCHEMA.TABLES' table.  This can be
     expensive if there are many tables.  The default is 'OFF'.

   * 'diagnostics.include_raw', '@sys.diagnostics.include_raw'

     If this option is 'ON', the 'diagnostics()'.
     procedure output includes the raw output from querying the
     'metrics' view.  The default is 'OFF'.

   * 'statement_truncate_len', '@sys.statement_truncate_len'

     The maximum length of statements returned by the
     'format_statement()' function.  Longer
     statements are truncated to this length.  The default is 64.

*Example*

Create a diagnostics report that starts an iteration every 30 seconds
and runs for at most 120 seconds using the current Performance Schema
settings:

     mysql> CALL diagnostics(120, 30, 'current');

To capture the output from the 'diagnostics()' procedure in a file as it
runs, use the 'mysql' client 'tee filename' and 'notee'
commands (see mysql-commands):

     mysql> tee diag.out;
     mysql> CALL diagnostics(120, 30, 'current');
     mysql> notee;

26.4.4.3 The execute_prepared_stmt() Procedure
..............................................

Given an SQL statement as a string, executes it as a prepared statement.
The prepared statement is deallocated after execution, so it is not
subject to reuse.  Thus, this procedure is useful primarily for
executing dynamic statements on a one-time basis.

This procedure uses 'sys_execute_prepared_stmt' as the prepared
statement name.  If that statement name exists when the procedure is
called, its previous content is destroyed.

This procedure was added in MySQL 5.7.9.

*Parameters*

   * 'in_query LONGTEXT CHARACTER SET utf8': The statement string to
     execute.

*Configuration Options*

'execute_prepared_stmt()' operation
can be modified using the following configuration options or their
corresponding user-defined variables (see sys-sys-config):

   * 'debug', '@sys.debug'

     If this option is 'ON', produce debugging output.  The default is
     'OFF'.

*Example*

     mysql> CALL execute_prepared_stmt('SELECT COUNT(*) FROM mysql.user');
     +----------+
     | COUNT(*) |
     +----------+
     |       15 |
     +----------+

26.4.4.4 The ps_setup_disable_background_threads() Procedure
............................................................

Disables Performance Schema instrumentation for all background threads.
Produces a result set indicating how many background threads were
disabled.  Already disabled threads do not count.

*Parameters*

None.

*Example*

     mysql> CALL ps_setup_disable_background_threads();
     +--------------------------------+
     | summary                        |
     +--------------------------------+
     | Disabled 24 background threads |
     +--------------------------------+

26.4.4.5 The ps_setup_disable_consumer() Procedure
..................................................

Disables Performance Schema consumers with names that contain the
argument.  Produces a result set indicating how many consumers were
disabled.  Already disabled consumers do not count.

*Parameters*

   * 'consumer VARCHAR(128)': The value used to match consumer names,
     which are identified by using '%consumer%' as an operand for a
     'LIKE' pattern match.

     A value of '''' matches all consumers.

*Example*

Disable all statement consumers:

     mysql> CALL ps_setup_disable_consumer('statement');
     +----------------------+
     | summary              |
     +----------------------+
     | Disabled 4 consumers |
     +----------------------+

26.4.4.6 The ps_setup_disable_instrument() Procedure
....................................................

Disables Performance Schema instruments with names that contain the
argument.  Produces a result set indicating how many instruments were
disabled.  Already disabled instruments do not count.

*Parameters*

   * 'in_pattern VARCHAR(128)': The value used to match instrument
     names, which are identified by using '%in_pattern%' as an operand
     for a 'LIKE' pattern match.

     A value of '''' matches all instruments.

*Example*

Disable a specific instrument:

     mysql> CALL ps_setup_disable_instrument('wait/lock/metadata/sql/mdl');
     +-----------------------+
     | summary               |
     +-----------------------+
     | Disabled 1 instrument |
     +-----------------------+

Disable all mutex instruments:

     mysql> CALL ps_setup_disable_instrument('mutex');
     +--------------------------+
     | summary                  |
     +--------------------------+
     | Disabled 177 instruments |
     +--------------------------+

26.4.4.7 The ps_setup_disable_thread() Procedure
................................................

Given a connection ID, disables Performance Schema instrumentation for
the thread.  Produces a result set indicating how many threads were
disabled.  Already disabled threads do not count.

*Parameters*

   * 'in_connection_id BIGINT': The connection ID. This is a connection
     ID as given in the 'PROCESSLIST_ID' column of the Performance
     Schema 'threads' table or the 'Id' column of
     'SHOW PROCESSLIST' output.

*Example*

Disable a specific connection by its connection ID:

     mysql> CALL ps_setup_disable_thread(225);
     +-------------------+
     | summary           |
     +-------------------+
     | Disabled 1 thread |
     +-------------------+

Disable the current connection:

     mysql> CALL ps_setup_disable_thread(CONNECTION_ID());
     +-------------------+
     | summary           |
     +-------------------+
     | Disabled 1 thread |
     +-------------------+

26.4.4.8 The ps_setup_enable_background_threads() Procedure
...........................................................

Enables Performance Schema instrumentation for all background threads.
Produces a result set indicating how many background threads were
enabled.  Already enabled threads do not count.

*Parameters*

None.

*Example*

     mysql> CALL ps_setup_enable_background_threads();
     +-------------------------------+
     | summary                       |
     +-------------------------------+
     | Enabled 24 background threads |
     +-------------------------------+

26.4.4.9 The ps_setup_enable_consumer() Procedure
.................................................

Enables Performance Schema consumers with names that contain the
argument.  Produces a result set indicating how many consumers were
enabled.  Already enabled consumers do not count.

*Parameters*

   * 'consumer VARCHAR(128)': The value used to match consumer names,
     which are identified by using '%consumer%' as an operand for a
     'LIKE' pattern match.

     A value of '''' matches all consumers.

*Example*

Enable all statement consumers:

     mysql> CALL ps_setup_enable_consumer('statement');
     +---------------------+
     | summary             |
     +---------------------+
     | Enabled 4 consumers |
     +---------------------+

26.4.4.10 The ps_setup_enable_instrument() Procedure
....................................................

Enables Performance Schema instruments with names that contain the
argument.  Produces a result set indicating how many instruments were
enabled.  Already enabled instruments do not count.

*Parameters*

   * 'in_pattern VARCHAR(128)': The value used to match instrument
     names, which are identified by using '%in_pattern%' as an operand
     for a 'LIKE' pattern match.

     A value of '''' matches all instruments.

*Example*

Enable a specific instrument:

     mysql> CALL ps_setup_enable_instrument('wait/lock/metadata/sql/mdl');
     +----------------------+
     | summary              |
     +----------------------+
     | Enabled 1 instrument |
     +----------------------+

Enable all mutex instruments:

     mysql> CALL ps_setup_enable_instrument('mutex');
     +-------------------------+
     | summary                 |
     +-------------------------+
     | Enabled 177 instruments |
     +-------------------------+

26.4.4.11 The ps_setup_enable_thread() Procedure
................................................

Given a connection ID, enables Performance Schema instrumentation for
the thread.  Produces a result set indicating how many threads were
enabled.  Already enabled threads do not count.

*Parameters*

   * 'in_connection_id BIGINT': The connection ID. This is a connection
     ID as given in the 'PROCESSLIST_ID' column of the Performance
     Schema 'threads' table or the 'Id' column of
     'SHOW PROCESSLIST' output.

*Example*

Enable a specific connection by its connection ID:

     mysql> CALL ps_setup_enable_thread(225);
     +------------------+
     | summary          |
     +------------------+
     | Enabled 1 thread |
     +------------------+

Enable the current connection:

     mysql> CALL ps_setup_enable_thread(CONNECTION_ID());
     +------------------+
     | summary          |
     +------------------+
     | Enabled 1 thread |
     +------------------+

26.4.4.12 The ps_setup_reload_saved() Procedure
...............................................

Reloads a Performance Schema configuration saved earlier within the same
session using 'ps_setup_save()'.  For more
information, see the description of 'ps_setup_save()'.

This procedure requires the 'SUPER' privilege because it manipulates the
session 'sql_log_bin' system variable to disable binary logging during
its execution.

*Parameters*

None.

26.4.4.13 The ps_setup_reset_to_default() Procedure
...................................................

Resets the Performance Schema configuration to its default settings.

*Parameters*

   * 'in_verbose BOOLEAN': Whether to display information about each
     setup stage during procedure execution.  This includes the SQL
     statements executed.

*Example*

     mysql> CALL ps_setup_reset_to_default(TRUE)\G
     *************************** 1. row ***************************
     status: Resetting: setup_actors
     DELETE
     FROM performance_schema.setup_actors
     WHERE NOT (HOST = '%' AND USER = '%' AND ROLE = '%')

     *************************** 1. row ***************************
     status: Resetting: setup_actors
     INSERT IGNORE INTO performance_schema.setup_actors
     VALUES ('%', '%', '%')

     ...

26.4.4.14 The ps_setup_save() Procedure
.......................................

Saves the current Performance Schema configuration.  This enables you to
alter the configuration temporarily for debugging or other purposes,
then restore it to the previous state by invoking the
'ps_setup_reload_saved()' procedure.

To prevent other simultaneous calls to save the configuration, see
'ps_setup_save()' acquires an advisory lock named
'sys.ps_setup_save' by calling the 'GET_LOCK()' function.
'ps_setup_save()' takes a timeout parameter to
indicate how many seconds to wait if the lock already exists (which
indicates that some other session has a saved configuration
outstanding).  If the timeout expires without obtaining the lock, see
'ps_setup_save()' fails.

It is intended you call 'ps_setup_reload_saved()'
later within the _same_ session as
'ps_setup_save()' because the configuration is saved
in 'TEMPORARY' tables.  See 'ps_setup_save()'.
drops the temporary tables and releases the lock.  If you end your
session without invoking 'ps_setup_save()', the
tables and lock disappear automatically.

This procedure requires the 'SUPER' privilege because it manipulates the
session 'sql_log_bin' system variable to disable binary logging during
its execution.

*Parameters*

   * 'in_timeout INT': How many seconds to wait to obtain the
     'sys.ps_setup_save' lock.  A negative timeout value means infinite
     timeout.

*Example*

     mysql> CALL ps_setup_save(10);

     ... MAKE PERFORMANCE SCHEMA CONFIGURATION CHANGES ...

     mysql> CALL ps_setup_reload_saved();

26.4.4.15 The ps_setup_show_disabled() Procedure
................................................

Displays all currently disabled Performance Schema configuration.

*Parameters*

   * 'in_show_instruments BOOLEAN': Whether to display disabled
     instruments.  This might be a long list.

   * 'in_show_threads BOOLEAN': Whether to display disabled threads.

*Example*

     mysql> CALL ps_setup_show_disabled(TRUE, TRUE);
     +----------------------------+
     | performance_schema_enabled |
     +----------------------------+
     |                          1 |
     +----------------------------+

     +---------------+
     | enabled_users |
     +---------------+
     | '%'@'%'       |
     +---------------+

     +-------------+----------------------+---------+-------+
     | object_type | objects              | enabled | timed |
     +-------------+----------------------+---------+-------+
     | EVENT       | mysql.%              | NO      | NO    |
     | EVENT       | performance_schema.% | NO      | NO    |
     | EVENT       | information_schema.% | NO      | NO    |
     | FUNCTION    | mysql.%              | NO      | NO    |
     | FUNCTION    | performance_schema.% | NO      | NO    |
     | FUNCTION    | information_schema.% | NO      | NO    |
     | PROCEDURE   | mysql.%              | NO      | NO    |
     | PROCEDURE   | performance_schema.% | NO      | NO    |
     | PROCEDURE   | information_schema.% | NO      | NO    |
     | TABLE       | mysql.%              | NO      | NO    |
     | TABLE       | performance_schema.% | NO      | NO    |
     | TABLE       | information_schema.% | NO      | NO    |
     | TRIGGER     | mysql.%              | NO      | NO    |
     | TRIGGER     | performance_schema.% | NO      | NO    |
     | TRIGGER     | information_schema.% | NO      | NO    |
     +-------------+----------------------+---------+-------+

     ...

26.4.4.16 The ps_setup_show_disabled_consumers() Procedure
..........................................................

Displays all currently disabled Performance Schema consumers.

*Parameters*

None.

*Example*

     mysql> CALL ps_setup_show_disabled_consumers();
     +----------------------------------+
     | disabled_consumers               |
     +----------------------------------+
     | events_stages_current            |
     | events_stages_history            |
     | events_stages_history_long       |
     | events_statements_history        |
     | events_statements_history_long   |
     | events_transactions_history      |
     | events_transactions_history_long |
     | events_waits_current             |
     | events_waits_history             |
     | events_waits_history_long        |
     +----------------------------------+

26.4.4.17 The ps_setup_show_disabled_instruments() Procedure
............................................................

Displays all currently disabled Performance Schema instruments.  This
might be a long list.

*Parameters*

None.

*Example*

     mysql> CALL ps_setup_show_disabled_instruments()\G
     *************************** 1. row ***************************
     disabled_instruments: wait/synch/mutex/sql/TC_LOG_MMAP::LOCK_tc
                    timed: NO
     *************************** 2. row ***************************
     disabled_instruments: wait/synch/mutex/sql/THD::LOCK_query_plan
                    timed: NO
     *************************** 3. row ***************************
     disabled_instruments: wait/synch/mutex/sql/MYSQL_BIN_LOG::LOCK_commit
                    timed: NO
     ...

26.4.4.18 The ps_setup_show_enabled() Procedure
...............................................

Displays all currently enabled Performance Schema configuration.

*Parameters*

   * 'in_show_instruments BOOLEAN': Whether to display enabled
     instruments.  This might be a long list.

   * 'in_show_threads BOOLEAN': Whether to display enabled threads.

*Example*

     mysql> CALL ps_setup_show_enabled(FALSE, FALSE);
     +----------------------------+
     | performance_schema_enabled |
     +----------------------------+
     |                          1 |
     +----------------------------+
     1 row in set (0.00 sec)

     +---------------+
     | enabled_users |
     +---------------+
     | '%'@'%'       |
     +---------------+
     1 row in set (0.00 sec)

     +-------------+----------------------+---------+-------+
     | object_type | objects              | enabled | timed |
     +-------------+----------------------+---------+-------+
     | EVENT       | %.%                  | YES     | YES   |
     | FUNCTION    | %.%                  | YES     | YES   |
     | PROCEDURE   | %.%                  | YES     | YES   |
     | TABLE       | %.%                  | YES     | YES   |
     | TRIGGER     | %.%                  | YES     | YES   |
     +-------------+----------------------+---------+-------+
     5 rows in set (0.01 sec)

     +-----------------------------+
     | enabled_consumers           |
     +-----------------------------+
     | events_statements_current   |
     | events_transactions_current |
     | global_instrumentation      |
     | thread_instrumentation      |
     | statements_digest           |
     +-----------------------------+

26.4.4.19 The ps_setup_show_enabled_consumers() Procedure
.........................................................

Displays all currently enabled Performance Schema consumers.

*Parameters*

None.

*Example*

     mysql> CALL ps_setup_show_enabled_consumers();
     +-----------------------------+
     | enabled_consumers           |
     +-----------------------------+
     | events_statements_current   |
     | events_transactions_current |
     | global_instrumentation      |
     | thread_instrumentation      |
     | statements_digest           |
     +-----------------------------+

26.4.4.20 The ps_setup_show_enabled_instruments() Procedure
...........................................................

Displays all currently enabled Performance Schema instruments.  This
might be a long list.

*Parameters*

None.

*Example*

     mysql> CALL ps_setup_show_enabled_instruments()\G
     *************************** 1. row ***************************
     enabled_instruments: wait/io/file/sql/map
                   timed: YES
     *************************** 2. row ***************************
     enabled_instruments: wait/io/file/sql/binlog
                   timed: YES
     *************************** 3. row ***************************
     enabled_instruments: wait/io/file/sql/binlog_cache
                   timed: YES
     ...

26.4.4.21 The ps_statement_avg_latency_histogram() Procedure
............................................................

Displays a textual histogram graph of the average latency values across
all normalized statements tracked within the Performance Schema
'events_statements_summary_by_digest' table.

This procedure can be used to display a very high-level picture of the
latency distribution of statements running within this MySQL instance.

*Parameters*

None.

*Example*

The histogram output in statement units.  For example, '* = 2 units' in
the histogram legend means that each '*' character represents 2
statements.

     mysql> CALL ps_statement_avg_latency_histogram()\G
     *************************** 1. row ***************************
     Performance Schema Statement Digest Average Latency Histogram:

       . = 1 unit
       * = 2 units
       # = 3 units

     (0 - 66ms)     88  | #############################
     (66 - 133ms)   14  | ..............
     (133 - 199ms)  4   | ....
     (199 - 265ms)  5   | **
     (265 - 332ms)  1   | .
     (332 - 398ms)  0   |
     (398 - 464ms)  1   | .
     (464 - 531ms)  0   |
     (531 - 597ms)  0   |
     (597 - 663ms)  0   |
     (663 - 730ms)  0   |
     (730 - 796ms)  0   |
     (796 - 863ms)  0   |
     (863 - 929ms)  0   |
     (929 - 995ms)  0   |
     (995 - 1062ms) 0   |

       Total Statements: 114; Buckets: 16; Bucket Size: 66 ms;

26.4.4.22 The ps_trace_statement_digest() Procedure
...................................................

Traces all Performance Schema instrumentation for a specific statement
digest.

If you find a statement of interest within the Performance Schema
'events_statements_summary_by_digest' table,
specify its 'DIGEST' column MD5 value to this procedure and indicate the
polling duration and interval.  The result is a report of all statistics
tracked within Performance Schema for that digest for the interval.

The procedure also attempts to execute 'EXPLAIN' for the
longest running example of the digest during the interval.  This attempt
might fail because the Performance Schema truncates long 'SQL_TEXT'
values.  Consequently, see 'EXPLAIN' will fail due to parse
errors.

This procedure requires the 'SUPER' privilege because it manipulates the
session 'sql_log_bin' system variable to disable binary logging during
its execution.

*Parameters*

   * 'in_digest VARCHAR(32)': The statement digest identifier to
     analyze.

   * 'in_runtime INT': How long to run the analysis in seconds.

   * 'in_interval DECIMAL(2,2)': The analysis interval in seconds (which
     can be fractional) at which to try to take snapshots.

   * 'in_start_fresh BOOLEAN': Whether to truncate the Performance
     Schema 'events_statements_history_long'
     and
     'events_stages_history_long'.
     tables before starting.

   * 'in_auto_enable BOOLEAN': Whether to automatically enable required
     consumers.

*Example*

     mysql> CALL ps_trace_statement_digest('891ec6860f98ba46d89dd20b0c03652c', 10, 0.1, TRUE, TRUE);
     +--------------------+
     | SUMMARY STATISTICS |
     +--------------------+
     | SUMMARY STATISTICS |
     +--------------------+
     1 row in set (9.11 sec)

     +------------+-----------+-----------+-----------+---------------+------------+------------+
     | executions | exec_time | lock_time | rows_sent | rows_examined | tmp_tables | full_scans |
     +------------+-----------+-----------+-----------+---------------+------------+------------+
     |         21 | 4.11 ms   | 2.00 ms   |         0 |            21 |          0 |          0 |
     +------------+-----------+-----------+-----------+---------------+------------+------------+
     1 row in set (9.11 sec)

     +------------------------------------------+-------+-----------+
     | event_name                               | count | latency   |
     +------------------------------------------+-------+-----------+
     | stage/sql/checking query cache for query |    16 | 724.37 us |
     | stage/sql/statistics                     |    16 | 546.92 us |
     | stage/sql/freeing items                  |    18 | 520.11 us |
     | stage/sql/init                           |    51 | 466.80 us |
     ...
     | stage/sql/cleaning up                    |    18 | 11.92 us  |
     | stage/sql/executing                      |    16 | 6.95 us   |
     +------------------------------------------+-------+-----------+
     17 rows in set (9.12 sec)

     +---------------------------+
     | LONGEST RUNNING STATEMENT |
     +---------------------------+
     | LONGEST RUNNING STATEMENT |
     +---------------------------+
     1 row in set (9.16 sec)

     +-----------+-----------+-----------+-----------+---------------+------------+-----------+
     | thread_id | exec_time | lock_time | rows_sent | rows_examined | tmp_tables | full_scan |
     +-----------+-----------+-----------+-----------+---------------+------------+-----------+
     |    166646 | 618.43 us | 1.00 ms   |         0 |             1 |          0 |         0 |
     +-----------+-----------+-----------+-----------+---------------+------------+-----------+
     1 row in set (9.16 sec)

     # Truncated for clarity...
     +-----------------------------------------------------------------+
     | sql_text                                                        |
     +-----------------------------------------------------------------+
     | select hibeventhe0_.id as id1382_, hibeventhe0_.createdTime ... |
     +-----------------------------------------------------------------+
     1 row in set (9.17 sec)

     +------------------------------------------+-----------+
     | event_name                               | latency   |
     +------------------------------------------+-----------+
     | stage/sql/init                           | 8.61 us   |
     | stage/sql/Waiting for query cache lock   | 453.23 us |
     | stage/sql/init                           | 331.07 ns |
     | stage/sql/checking query cache for query | 43.04 us  |
     ...
     | stage/sql/freeing items                  | 30.46 us  |
     | stage/sql/cleaning up                    | 662.13 ns |
     +------------------------------------------+-----------+
     18 rows in set (9.23 sec)

     +----+-------------+--------------+-------+---------------+-----------+---------+-------------+------+-------+
     | id | select_type | table        | type  | possible_keys | key       | key_len | ref         | rows | Extra |
     +----+-------------+--------------+-------+---------------+-----------+---------+-------------+------+-------+
     |  1 | SIMPLE      | hibeventhe0_ | const | fixedTime     | fixedTime | 775     | const,const |    1 | NULL  |
     +----+-------------+--------------+-------+---------------+-----------+---------+-------------+------+-------+
     1 row in set (9.27 sec)

     Query OK, 0 rows affected (9.28 sec)

26.4.4.23 The ps_trace_thread() Procedure
.........................................

Dumps all Performance Schema data for an instrumented thread to a '.dot'
formatted graph file (for the DOT graph description language).  Each
result set returned from the procedure should be used for a complete
graph.

This procedure requires the 'SUPER' privilege because it manipulates the
session 'sql_log_bin' system variable to disable binary logging during
its execution.

*Parameters*

   * 'in_thread_id INT': The thread to trace.

   * 'in_outfile VARCHAR(255)': The name to use for the '.dot' output
     file.

   * 'in_max_runtime DECIMAL(20,2)': The maximum number of seconds
     (which can be fractional) to collect data.  Use 'NULL' to collect
     data for the default of 60 seconds.

   * 'in_interval DECIMAL(20,2)': The number of seconds (which can be
     fractional) to sleep between data collections.  Use 'NULL' to sleep
     for the default of 1 second.

   * 'in_start_fresh BOOLEAN': Whether to reset all Performance Schema
     data before tracing.

   * 'in_auto_setup BOOLEAN': Whether to disable all other threads and
     enable all instruments and consumers.  This also resets the
     settings at the end of the run.

   * 'in_debug BOOLEAN': Whether to include 'file:lineno' information in
     the graph.

*Example*

     mysql> CALL ps_trace_thread(25, CONCAT('/tmp/stack-', REPLACE(NOW(), ' ', '-'), '.dot'), NULL, NULL, TRUE, TRUE, TRUE);
     +-------------------+
     | summary           |
     +-------------------+
     | Disabled 1 thread |
     +-------------------+
     1 row in set (0.00 sec)

     +---------------------------------------------+
     | Info                                        |
     +---------------------------------------------+
     | Data collection starting for THREAD_ID = 25 |
     +---------------------------------------------+
     1 row in set (0.03 sec)

     +-----------------------------------------------------------+
     | Info                                                      |
     +-----------------------------------------------------------+
     | Stack trace written to /tmp/stack-2014-02-16-21:18:41.dot |
     +-----------------------------------------------------------+
     1 row in set (60.07 sec)

     +-------------------------------------------------------------------+
     | Convert to PDF                                                    |
     +-------------------------------------------------------------------+
     | dot -Tpdf -o /tmp/stack_25.pdf /tmp/stack-2014-02-16-21:18:41.dot |
     +-------------------------------------------------------------------+
     1 row in set (60.07 sec)

     +-------------------------------------------------------------------+
     | Convert to PNG                                                    |
     +-------------------------------------------------------------------+
     | dot -Tpng -o /tmp/stack_25.png /tmp/stack-2014-02-16-21:18:41.dot |
     +-------------------------------------------------------------------+
     1 row in set (60.07 sec)

     +------------------+
     | summary          |
     +------------------+
     | Enabled 1 thread |
     +------------------+
     1 row in set (60.32 sec)

26.4.4.24 The ps_truncate_all_tables() Procedure
................................................

Truncates all Performance Schema summary tables, resetting all
aggregated instrumentation as a snapshot.  Produces a result set
indicating how many tables were truncated.

*Parameters*

   * 'in_verbose BOOLEAN': Whether to display each 'TRUNCATE TABLE'
     statement before executing it.

*Example*

     mysql> CALL ps_truncate_all_tables(FALSE);
     +---------------------+
     | summary             |
     +---------------------+
     | Truncated 44 tables |
     +---------------------+

26.4.4.25 The statement_performance_analyzer() Procedure
........................................................

Creates a report of the statements running on the server.  The views are
calculated based on the overall and/or delta activity.

This procedure requires the 'SUPER' privilege because it manipulates the
session 'sql_log_bin' system variable to disable binary logging during
its execution.

This procedure was added in MySQL 5.7.9.

*Parameters*

   * 'in_action ENUM('snapshot', 'overall', 'delta', 'create_tmp',
     'create_table', 'save', 'cleanup')': The action to take.  These
     values are permitted:

        * 'snapshot': Store a snapshot.  The default is to make a
          snapshot of the current content of the Performance Schema
          'events_statements_summary_by_digest'
          table.  By setting 'in_table', this
          can be overwritten to copy the content of the specified table.
          The snapshot is stored in the 'sys' schema
          'tmp_digests' temporary table.

        * 'overall': Generate an analysis based on the content of the
          table specified by 'in_table'.  For the overall analysis,
          'in_table' can be 'NOW()' to use a fresh snapshot.  This
          overwrites an existing snapshot.  Use 'NULL' for 'in_table' to
          use the existing snapshot.  If 'in_table' is 'NULL' and no
          snapshot exists, a new snapshot is created.  The 'in_views'
          parameter and the 'statement_performance_analyzer.limit'
          configuration option affect the operation of this procedure.

        * 'delta': Generate a delta analysis.  The delta is calculated
          between the reference table specified by 'in_table' and the
          snapshot, which must exist.  This action uses the 'sys'
          schema 'tmp_digests_delta' temporary table.  The
          'in_views' parameter and the
          'statement_performance_analyzer.limit' configuration option
          affect the operation of this procedure.

        * 'create_table': Create a regular table suitable for storing
          the snapshot for later use (for example, for calculating
          deltas).

        * 'create_tmp': Create a temporary table suitable for storing
          the snapshot for later use (for example, for calculating
          deltas).

        * 'save': Save the snapshot in the table specified by
          'in_table'.  The table must exist and have the correct
          structure.  If no snapshot exists, a new snapshot is created.

        * 'cleanup': Remove the temporary tables used for the snapshot
          and delta.

   * 'in_table VARCHAR(129)': The table parameter used for some of the
     actions specified by the 'in_action' parameter.  Use the format
     DB_NAME.TBL_NAME or TBL_NAME without using any backtick ('`')
     identifier-quoting characters.  Periods ('.') are not supported in
     database and table names.

     The meaning of the 'in_table' value for each 'in_action' value is
     detailed in the individual 'in_action' value descriptions.

   * 'in_views SET ('with_runtimes_in_95th_percentile', 'analysis',
     'with_errors_or_warnings', 'with_full_table_scans', 'with_sorting',
     'with_temp_tables', 'custom')': Which views to include.  This
     parameter is a 'SET' value, so it can contain multiple view names,
     separated by commas.  The default is to include all views except
     'custom'.  The following values are permitted:

        * 'with_runtimes_in_95th_percentile': Use the
          'statements_with_runtimes_in_95th_percentile'
          view.

        * 'analysis': Use the 'statement_analysis'
          view.

        * 'with_errors_or_warnings': Use the
          'statements_with_errors_or_warnings'
          view.

        * 'with_full_table_scans': Use the
          'statements_with_full_table_scans'
          view.

        * 'with_sorting': Use the 'statements_with_sorting'
          view.

        * 'with_temp_tables': Use the
          'statements_with_temp_tables'
          view.

        * 'custom': Use a custom view.  This view must be specified
          using the 'statement_performance_analyzer.view' configuration
          option to name a query or an existing view.

*Configuration Options*

'statement_performance_analyzer()'
operation can be modified using the
following configuration options or their corresponding user-defined
variables (see sys-sys-config):

   * 'debug', '@sys.debug'

     If this option is 'ON', produce debugging output.  The default is
     'OFF'.

   * 'statement_performance_analyzer.limit',
     '@sys.statement_performance_analyzer.limit'

     The maximum number of rows to return for views that have no
     built-in limit.  The default is 100.

   * 'statement_performance_analyzer.view',
     '@sys.statement_performance_analyzer.view'

     The custom query or view to be used.  If the option value contains
     a space, it is interpreted as a query.  Otherwise, it must be the
     name of an existing view that queries the Performance Schema
     'events_statements_summary_by_digest'.
     table.  There cannot be any 'LIMIT' clause in the query or view
     definition if the 'statement_performance_analyzer.limit'
     configuration option is greater than 0.  If specifying a view, use
     the same format as for the 'in_table' parameter.  The default is
     'NULL' (no custom view defined).

     This option was added in MySQL 5.7.9.

*Example*

To create a report with the queries in the 95th percentile since the
last truncation of 'events_statements_summary_by_digest'
and with a one-minute delta period:

  1. Create a temporary table to store the initial snapshot.

  2. Create the initial snapshot.

  3. Save the initial snapshot in the temporary table.

  4. Wait one minute.

  5. Create a new snapshot.

  6. Perform analysis based on the new snapshot.

  7. Perform analysis based on the delta between the initial and new
     snapshots.

     mysql> CALL statement_performance_analyzer('create_tmp', 'mydb.tmp_digests_ini', NULL);
     Query OK, 0 rows affected (0.08 sec)

     mysql> CALL statement_performance_analyzer('snapshot', NULL, NULL);
     Query OK, 0 rows affected (0.02 sec)

     mysql> CALL statement_performance_analyzer('save', 'mydb.tmp_digests_ini', NULL);
     Query OK, 0 rows affected (0.00 sec)

     mysql> DO SLEEP(60);
     Query OK, 0 rows affected (1 min 0.00 sec)

     mysql> CALL statement_performance_analyzer('snapshot', NULL, NULL);
     Query OK, 0 rows affected (0.02 sec)

     mysql> CALL statement_performance_analyzer('overall', NULL, 'with_runtimes_in_95th_percentile');
     +-----------------------------------------+
     | Next Output                             |
     +-----------------------------------------+
     | Queries with Runtime in 95th Percentile |
     +-----------------------------------------+
     1 row in set (0.05 sec)

     ...

     mysql> CALL statement_performance_analyzer('delta', 'mydb.tmp_digests_ini', 'with_runtimes_in_95th_percentile');
     +-----------------------------------------+
     | Next Output                             |
     +-----------------------------------------+
     | Queries with Runtime in 95th Percentile |
     +-----------------------------------------+
     1 row in set (0.03 sec)

     ...

Create an overall report of the 95th percentile queries and the top 10
queries with full table scans:

     mysql> CALL statement_performance_analyzer('snapshot', NULL, NULL);
     Query OK, 0 rows affected (0.01 sec)

     mysql> SET @sys.statement_performance_analyzer.limit = 10;
     Query OK, 0 rows affected (0.00 sec)

     mysql> CALL statement_performance_analyzer('overall', NULL, 'with_runtimes_in_95th_percentile,with_full_table_scans');
     +-----------------------------------------+
     | Next Output                             |
     +-----------------------------------------+
     | Queries with Runtime in 95th Percentile |
     +-----------------------------------------+
     1 row in set (0.01 sec)

     ...

     +-------------------------------------+
     | Next Output                         |
     +-------------------------------------+
     | Top 10 Queries with Full Table Scan |
     +-------------------------------------+
     1 row in set (0.09 sec)

     ...

Use a custom view showing the top 10 queries sorted by total execution
time, refreshing the view every minute using the 'watch' command in
Linux:

     mysql> CREATE OR REPLACE VIEW mydb.my_statements AS
         -> SELECT sys.format_statement(DIGEST_TEXT) AS query,
         ->        SCHEMA_NAME AS db,
         ->        COUNT_STAR AS exec_count,
         ->        sys.format_time(SUM_TIMER_WAIT) AS total_latency,
         ->        sys.format_time(AVG_TIMER_WAIT) AS avg_latency,
         ->        ROUND(IFNULL(SUM_ROWS_SENT / NULLIF(COUNT_STAR, 0), 0)) AS rows_sent_avg,
         ->        ROUND(IFNULL(SUM_ROWS_EXAMINED / NULLIF(COUNT_STAR, 0), 0)) AS rows_examined_avg,
         ->        ROUND(IFNULL(SUM_ROWS_AFFECTED / NULLIF(COUNT_STAR, 0), 0)) AS rows_affected_avg,
         ->        DIGEST AS digest
         ->   FROM performance_schema.events_statements_summary_by_digest
         -> ORDER BY SUM_TIMER_WAIT DESC;
     Query OK, 0 rows affected (0.01 sec)

     mysql> CALL statement_performance_analyzer('create_table', 'mydb.digests_prev', NULL);
     Query OK, 0 rows affected (0.10 sec)

     shell> watch -n 60 "mysql sys --table -e \"
     > SET @sys.statement_performance_analyzer.view = 'mydb.my_statements';
     > SET @sys.statement_performance_analyzer.limit = 10;
     > CALL statement_performance_analyzer('snapshot', NULL, NULL);
     > CALL statement_performance_analyzer('delta', 'mydb.digests_prev', 'custom');
     > CALL statement_performance_analyzer('save', 'mydb.digests_prev', NULL);
     > \""

     Every 60.0s: mysql sys --table -e "        ...  Mon Dec 22 10:58:51 2014

     +----------------------------------+
     | Next Output                      |
     +----------------------------------+
     | Top 10 Queries Using Custom View |
     +----------------------------------+
     +-------------------+-------+------------+---------------+-------------+---------------+-------------------+-------------------+----------------------------------+
     | query             | db    | exec_count | total_latency | avg_latency | rows_sent_avg | rows_examined_avg | rows_affected_avg | digest                           |
     +-------------------+-------+------------+---------------+-------------+---------------+-------------------+-------------------+----------------------------------+
     ...

26.4.4.26 The table_exists() Procedure
......................................

Tests whether a given table exists as a regular table, a 'TEMPORARY'
table, or a view.  The procedure returns the table type in an 'OUT'
parameter.  If both a temporary and a permanent table exist with the
given name, 'TEMPORARY' is returned.

This procedure was added in MySQL 5.7.9.

*Parameters*

   * 'in_db VARCHAR(64)': The name of the database in which to check for
     table existance.

   * 'in_table VARCHAR(64)': The name of the table to check the
     existance of.

   * 'out_exists ENUM('', 'BASE TABLE', 'VIEW', 'TEMPORARY')': The
     return value.  This is an 'OUT' parameter, so it must be a variable
     into which the table type can be stored.  When the procedure
     returns, the variable has one of the following values to indicate
     whether the table exists:

        * '''': The table name does not exist as a base table,
          'TEMPORARY' table, or view.

        * 'BASE TABLE': The table name exists as a base (permanent)
          table.

        * 'VIEW': The table name exists as a view.

        * 'TEMPORARY': The table name exists as a 'TEMPORARY' table.

*Example*

     mysql> CREATE DATABASE db1;
     Query OK, 1 row affected (0.01 sec)

     mysql> USE db1;
     Database changed
     mysql> CREATE TABLE t1 (id INT PRIMARY KEY);
     Query OK, 0 rows affected (0.03 sec)

     mysql> CREATE TABLE t2 (id INT PRIMARY KEY);
     Query OK, 0 rows affected (0.20 sec)

     mysql> CREATE view v_t1 AS SELECT * FROM t1;
     Query OK, 0 rows affected (0.02 sec)

     mysql> CREATE TEMPORARY TABLE t1 (id INT PRIMARY KEY);
     Query OK, 0 rows affected (0.00 sec)

     mysql> CALL sys.table_exists('db1', 't1', @exists); SELECT @exists;
     Query OK, 0 rows affected (0.01 sec)

     +-----------+
     | @exists   |
     +-----------+
     | TEMPORARY |
     +-----------+
     1 row in set (0.00 sec)

     mysql> CALL sys.table_exists('db1', 't2', @exists); SELECT @exists;
     Query OK, 0 rows affected (0.02 sec)

     +------------+
     | @exists    |
     +------------+
     | BASE TABLE |
     +------------+
     1 row in set (0.00 sec)

     mysql> CALL sys.table_exists('db1', 'v_t1', @exists); SELECT @exists;
     Query OK, 0 rows affected (0.02 sec)

     +---------+
     | @exists |
     +---------+
     | VIEW    |
     +---------+
     1 row in set (0.00 sec)

     mysql> CALL sys.table_exists('db1', 't3', @exists); SELECT @exists;
     Query OK, 0 rows affected (0.00 sec)

     +---------+
     | @exists |
     +---------+
     |         |
     +---------+
     1 row in set (0.00 sec)

26.4.5 sys Schema Stored Functions
----------------------------------

The following sections describe 'sys' schema stored
functions.

26.4.5.1 The extract_schema_from_file_name() Function
.....................................................

Given a file path name, returns the path component that represents the
schema name.  This function assumes that the file name lies within the
schema directory.  For this reason, it will not work with partitions or
tables defined using their own 'DATA_DIRECTORY' table option.

This function is useful when extracting file I/O information from the
Performance Schema that includes file path names.  It provides a
convenient way to display schema names, which can be more easily
understood than full path names, and can be used in joins against object
schema names.

*Parameters*

   * 'path VARCHAR(512)': The full path to a data file from which to
     extract the schema name.

*Return Value*

A 'VARCHAR(64)' value.

*Example*

     mysql> SELECT extract_schema_from_file_name('/usr/local/mysql/data/world/City.ibd');
     +-----------------------------------------------------------------------+
     | extract_schema_from_file_name('/usr/local/mysql/data/world/City.ibd') |
     +-----------------------------------------------------------------------+
     | world                                                                 |
     +-----------------------------------------------------------------------+

26.4.5.2 The extract_table_from_file_name() Function
....................................................

Given a file path name, returns the path component that represents the
table name.

This function is useful when extracting file I/O information from the
Performance Schema that includes file path names.  It provides a
convenient way to display table names, which can be more easily
understood than full path names, and can be used in joins against object
table names.

*Parameters*

   * 'path VARCHAR(512)': The full path to a data file from which to
     extract the table name.

*Return Value*

A 'VARCHAR(64)' value.

*Example*

     mysql> SELECT extract_table_from_file_name('/usr/local/mysql/data/world/City.ibd');
     +----------------------------------------------------------------------+
     | extract_table_from_file_name('/usr/local/mysql/data/world/City.ibd') |
     +----------------------------------------------------------------------+
     | City                                                                 |
     +----------------------------------------------------------------------+

26.4.5.3 The format_bytes() Function
....................................

Given a value in bytes, converts it to human-readable format and returns
a string consisting of a value and a units indicator.  Depending on the
size of the value, the units part is 'bytes', 'KiB' (kibibytes), 'MiB'
(mebibytes), 'GiB' (gibibytes), 'TiB' (tebibytes), or 'PiB' (pebibytes).

*Parameters*

   * 'bytes TEXT': The bytes value to format.

*Return Value*

A 'TEXT' value.

*Example*

     mysql> SELECT format_bytes(512), format_bytes(18446644073709551615);
     +-------------------+------------------------------------+
     | format_bytes(512) | format_bytes(18446644073709551615) |
     +-------------------+------------------------------------+
     | 512 bytes         | 16383.91 PiB                       |
     +-------------------+------------------------------------+

26.4.5.4 The format_path() Function
...................................

Given a path name, returns the modified path name after replacing
subpaths that match the values of the following system variables, in
order:

     datadir
     tmpdir
     slave_load_tmpdir
     innodb_data_home_dir
     innodb_log_group_home_dir
     innodb_undo_directory
     basedir

A value that matches the value of system variable SYSVAR is replaced
with the string '@@global.SYSVAR'.

Prior to MySQL 5.7.14, backslashes in Windows path names are converted
to forward slashes in the result.

*Parameters*

   * 'path VARCHAR(512)': The path name to format.

*Return Value*

A 'VARCHAR(512) CHARACTER SET utf8' value.

*Example*

     mysql> SELECT format_path('/usr/local/mysql/data/world/City.ibd');
     +-----------------------------------------------------+
     | format_path('/usr/local/mysql/data/world/City.ibd') |
     +-----------------------------------------------------+
     | @@datadir/world/City.ibd                            |
     +-----------------------------------------------------+

26.4.5.5 The format_statement() Function
........................................

Given a string (normally representing an SQL statement), reduces it to
the length given by the 'statement_truncate_len' configuration option,
and returns the result.  No truncation occurs if the string is shorter
than 'statement_truncate_len'.  Otherwise, the middle part of the string
is replaced by an ellipsis ('...').

This function is useful for formatting possibly lengthy statements
retrieved from Performance Schema tables to a known fixed maximum
length.

*Parameters*

   * 'statement LONGTEXT': The statement to format.

*Configuration Options*

'format_statement()' operation can be
modified using the following configuration options or their
corresponding user-defined variables (see sys-sys-config):

   * 'statement_truncate_len', '@sys.statement_truncate_len'

     The maximum length of statements returned by the
     'format_statement()' function.  Longer
     statements are truncated to this length.  The default is 64.

*Return Value*

A 'LONGTEXT' value.

*Example*

By default, see 'format_statement()' truncates
statements to be no more than 64 characters.  Setting
'@sys.statement_truncate_len' changes the truncation length for the
current session:

     mysql> SET @stmt = 'SELECT variable, value, set_time, set_by FROM sys_config';
     mysql> SELECT format_statement(@stmt);
     +----------------------------------------------------------+
     | format_statement(@stmt)                                  |
     +----------------------------------------------------------+
     | SELECT variable, value, set_time, set_by FROM sys_config |
     +----------------------------------------------------------+
     mysql> SET @sys.statement_truncate_len = 32;
     mysql> SELECT format_statement(@stmt);
     +-----------------------------------+
     | format_statement(@stmt)           |
     +-----------------------------------+
     | SELECT variabl ... ROM sys_config |
     +-----------------------------------+

26.4.5.6 The format_time() Function
...................................

Given a Performance Schema latency or wait time in picoseconds, converts
it to human-readable format and returns a string consisting of a value
and a units indicator.  Depending on the size of the value, the units
part is 'ns' (nanoseconds), 'us' (microseconds), 'ms' (milliseconds),
's' (seconds), 'm' (minutes), 'h' (hours), 'd' (days), or 'w' (weeks).

*Parameters*

   * 'picoseconds TEXT': The picoseconds value to format.

*Return Value*

A 'TEXT' value.

*Example*

     mysql> SELECT format_time(3501), format_time(188732396662000);
     +-------------------+------------------------------+
     | format_time(3501) | format_time(188732396662000) |
     +-------------------+------------------------------+
     | 3.50 ns           | 3.15 m                       |
     +-------------------+------------------------------+

26.4.5.7 The list_add() Function
................................

Adds a value to a comma-separated list of values and returns the result.

This function and 'list_drop()' can be useful for
manipulating the value of system variables such as 'sql_mode' and
'optimizer_switch' that take a comma-separated list of values.

This function was added in MySQL 5.7.9.

*Parameters*

   * 'in_list TEXT': The list to be modified.

   * 'in_add_value TEXT': The value to add to the list.

*Return Value*

A 'TEXT' value.

*Example*

     mysql> SELECT @@sql_mode;
     +----------------------------------------+
     | @@sql_mode                             |
     +----------------------------------------+
     | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES |
     +----------------------------------------+
     mysql> SET @@sql_mode = list_add(@@sql_mode, 'NO_ENGINE_SUBSTITUTION');
     mysql> SELECT @@sql_mode;
     +---------------------------------------------------------------+
     | @@sql_mode                                                    |
     +---------------------------------------------------------------+
     | ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION |
     +---------------------------------------------------------------+
     mysql> SET @@sql_mode = list_drop(@@sql_mode, 'ONLY_FULL_GROUP_BY');
     mysql> SELECT @@sql_mode;
     +--------------------------------------------+
     | @@sql_mode                                 |
     +--------------------------------------------+
     | STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION |
     +--------------------------------------------+

26.4.5.8 The list_drop() Function
.................................

Removes a value from a comma-separated list of values and returns the
result.  For more information, see the description of
'list_add()'.

This function was added in MySQL 5.7.9.

*Parameters*

   * 'in_list TEXT': The list to be modified.

   * 'in_drop_value TEXT': The value to drop from the list.

*Return Value*

A 'TEXT' value.

26.4.5.9 The ps_is_account_enabled() Function
.............................................

Returns 'YES' or 'NO' to indicate whether Performance Schema
instrumentation for a given account is enabled.

*Parameters*

   * 'in_host VARCHAR(60)': The host name of the account to check.

   * 'in_user VARCHAR(32)': The user name of the account to check.

*Return Value*

An 'ENUM('YES','NO')' value.

*Example*

     mysql> SELECT ps_is_account_enabled('localhost', 'root');
     +--------------------------------------------+
     | ps_is_account_enabled('localhost', 'root') |
     +--------------------------------------------+
     | YES                                        |
     +--------------------------------------------+

26.4.5.10 The ps_is_consumer_enabled() Function
...............................................

Returns 'YES' or 'NO' to indicate whether a given Performance Schema
consumer is enabled, or 'NULL' if the argument is not a valid consumer
name.

This function accounts for the consumer hierarchy, so a consumer is not
considered enabled unless all consumers on which depends are also
enabled.  For information about the consumer hierarchy, see
performance-schema-consumer-filtering.

*Parameters*

   * 'in_consumer VARCHAR(64)': The name of the consumer to check.

*Return Value*

An 'ENUM('YES','NO')' value.

*Example*

     mysql> SELECT ps_is_consumer_enabled('thread_instrumentation');
     +--------------------------------------------------+
     | ps_is_consumer_enabled('thread_instrumentation') |
     +--------------------------------------------------+
     | YES                                              |
     +--------------------------------------------------+

26.4.5.11 The ps_is_instrument_default_enabled() Function
.........................................................

Returns 'YES' or 'NO' to indicate whether a given Performance Schema
instrument is enabled by default.

*Parameters*

   * 'in_instrument VARCHAR(128)': The name of the instrument to check.

*Return Value*

An 'ENUM('YES','NO')' value.

*Example*

     mysql> SELECT ps_is_instrument_default_enabled('memory/innodb/row_log_buf');
     +---------------------------------------------------------------+
     | ps_is_instrument_default_enabled('memory/innodb/row_log_buf') |
     +---------------------------------------------------------------+
     | NO                                                            |
     +---------------------------------------------------------------+
     mysql> SELECT ps_is_instrument_default_enabled('statement/sql/alter_user');
     +--------------------------------------------------------------+
     | ps_is_instrument_default_enabled('statement/sql/alter_user') |
     +--------------------------------------------------------------+
     | YES                                                          |
     +--------------------------------------------------------------+

26.4.5.12 The ps_is_instrument_default_timed() Function
.......................................................

Returns 'YES' or 'NO' to indicate whether a given Performance Schema
instrument is timed by default.

*Parameters*

   * 'in_instrument VARCHAR(128)': The name of the instrument to check.

*Return Value*

An 'ENUM('YES','NO')' value.

*Example*

     mysql> SELECT ps_is_instrument_default_timed('memory/innodb/row_log_buf');
     +-------------------------------------------------------------+
     | ps_is_instrument_default_timed('memory/innodb/row_log_buf') |
     +-------------------------------------------------------------+
     | NO                                                          |
     +-------------------------------------------------------------+
     mysql> SELECT ps_is_instrument_default_timed('statement/sql/alter_user');
     +------------------------------------------------------------+
     | ps_is_instrument_default_timed('statement/sql/alter_user') |
     +------------------------------------------------------------+
     | YES                                                        |
     +------------------------------------------------------------+

26.4.5.13 The ps_is_thread_instrumented() Function
..................................................

Returns 'YES' or 'NO' to indicate whether Performance Schema
instrumentation for a given connection ID is enabled, 'UNKNOWN' if the
ID is unknown, or 'NULL' if the ID is 'NULL'.

*Parameters*

   * 'in_connection_id BIGINT UNSIGNED': The connection ID. This is a
     connection ID as given in the 'PROCESSLIST_ID' column of the
     Performance Schema 'threads' table or the
     'Id' column of 'SHOW PROCESSLIST' output.

*Return Value*

An 'ENUM('YES','NO','UNKNOWN')' value.

*Example*

     mysql> SELECT ps_is_thread_instrumented(43);
     +-------------------------------+
     | ps_is_thread_instrumented(43) |
     +-------------------------------+
     | UNKNOWN                       |
     +-------------------------------+
     mysql> SELECT ps_is_thread_instrumented(CONNECTION_ID());
     +--------------------------------------------+
     | ps_is_thread_instrumented(CONNECTION_ID()) |
     +--------------------------------------------+
     | YES                                        |
     +--------------------------------------------+

26.4.5.14 The ps_thread_account() Function
..........................................

Given a Performance Schema thread ID, returns the 'USER_NAME@HOST_NAME'
account associated with the thread.

This function was added in MySQL 5.7.9.

*Parameters*

   * 'in_thread_id BIGINT UNSIGNED': The thread ID for which to return
     the account.  The value should match the 'THREAD_ID' column from
     some Performance Schema 'threads' table row.

*Return Value*

A 'TEXT' value.

*Example*

     mysql> SELECT ps_thread_account(ps_thread_id(CONNECTION_ID()));
     +--------------------------------------------------+
     | ps_thread_account(ps_thread_id(CONNECTION_ID())) |
     +--------------------------------------------------+
     | root@localhost                                   |
     +--------------------------------------------------+

26.4.5.15 The ps_thread_id() Function
.....................................

Returns the Performance Schema thread ID for a given connection ID, or
the thread ID for the current connection if the connection ID is 'NULL'.

*Parameters*

   * 'in_connection_id BIGINT UNSIGNED': The ID of the connection for
     which to return the thread ID. This is a connection ID as given in
     the 'PROCESSLIST_ID' column of the Performance Schema
     'threads' table or the 'Id' column of 'SHOW PROCESSLIST'
     output.

*Return Value*

A 'BIGINT UNSIGNED' value.

*Example*

     mysql> SELECT ps_thread_id(260);
     +-------------------+
     | ps_thread_id(260) |
     +-------------------+
     |               285 |
     +-------------------+

26.4.5.16 The ps_thread_stack() Function
........................................

Returns a JSON formatted stack of all statements, stages, and events
within the Performance Schema for a given thread ID.

*Parameters*

   * 'in_thread_id BIGINT': The ID of the thread to trace.  The value
     should match the 'THREAD_ID' column from some Performance Schema
     'threads' table row.

   * 'in_verbose BOOLEAN': Whether to include 'file:lineno' information
     in the events.

*Return Value*

A 'LONGTEXT CHARACTER SET latin1' value.

*Example*

     mysql> SELECT ps_thread_stack(37, FALSE) AS thread_stack\G
     *************************** 1. row ***************************
     thread_stack: {"rankdir": "LR","nodesep": "0.10",
     "stack_created": "2014-02-19 13:39:03", "mysql_version": "5.7.3-m13",
     "mysql_user": "root@localhost","events": [{"nesting_event_id": "0",
     "event_id": "10", "timer_wait": 256.35, "event_info": "sql/select",
     "wait_info": "select @@version_comment limit 1\nerrors: 0\nwarnings: 0\nlock time:
     ...

26.4.5.17 The ps_thread_trx_info() Function
...........................................

Returns a JSON object containing information about a given thread.  The
information includes the current transaction, and the statements it has
already executed, derived from the Performance Schema
'events_transactions_current' and
'events_statements_history'.
tables.  (The consumers for those tables must be enabled to obtain full
data in the JSON object.)

If the output exceeds the truncation length (65535 by default), a JSON
error object is returned, such as:

     { "error": "Trx info truncated: Row 6 was cut by GROUP_CONCAT()" }

Similar error objects are returned for other warnings and exceptions
raised during function execution.

This function was added in MySQL 5.7.9.

*Parameters*

   * 'in_thread_id BIGINT UNSIGNED': The thread ID for which to return
     transaction information.  The value should match the 'THREAD_ID'
     column from some Performance Schema 'threads'.
     table row.

*Configuration Options*

'ps_thread_trx_info()' operation can be
modified using the following configuration options or their
corresponding user-defined variables (see sys-sys-config):

   * 'ps_thread_trx_info.max_length',
     '@sys.ps_thread_trx_info.max_length'

     The maximum length of the output.  The default is 65535.

*Return Value*

A 'LONGTEXT' value.

*Example*

     mysql> SELECT ps_thread_trx_info(48)\G
     *************************** 1. row ***************************
     ps_thread_trx_info(48): [
       {
         "time": "790.70 us",
         "state": "COMMITTED",
         "mode": "READ WRITE",
         "autocommitted": "NO",
         "gtid": "AUTOMATIC",
         "isolation": "REPEATABLE READ",
         "statements_executed": [
           {
             "sql_text": "INSERT INTO info VALUES (1, \'foo\')",
             "time": "471.02 us",
             "schema": "trx",
             "rows_examined": 0,
             "rows_affected": 1,
             "rows_sent": 0,
             "tmp_tables": 0,
             "tmp_disk_tables": 0,
             "sort_rows": 0,
             "sort_merge_passes": 0
           },
           {
             "sql_text": "COMMIT",
             "time": "254.42 us",
             "schema": "trx",
             "rows_examined": 0,
             "rows_affected": 0,
             "rows_sent": 0,
             "tmp_tables": 0,
             "tmp_disk_tables": 0,
             "sort_rows": 0,
             "sort_merge_passes": 0
           }
         ]
       },
       {
         "time": "426.20 us",
         "state": "COMMITTED",
         "mode": "READ WRITE",
         "autocommitted": "NO",
         "gtid": "AUTOMATIC",
         "isolation": "REPEATABLE READ",
         "statements_executed": [
           {
             "sql_text": "INSERT INTO info VALUES (2, \'bar\')",
             "time": "107.33 us",
             "schema": "trx",
             "rows_examined": 0,
             "rows_affected": 1,
             "rows_sent": 0,
             "tmp_tables": 0,
             "tmp_disk_tables": 0,
             "sort_rows": 0,
             "sort_merge_passes": 0
           },
           {
             "sql_text": "COMMIT",
             "time": "213.23 us",
             "schema": "trx",
             "rows_examined": 0,
             "rows_affected": 0,
             "rows_sent": 0,
             "tmp_tables": 0,
             "tmp_disk_tables": 0,
             "sort_rows": 0,
             "sort_merge_passes": 0
           }
         ]
       }
     ]

26.4.5.18 The quote_identifier() Function
.........................................

Given a string argument, this function produces a quoted identifier
suitable for inclusion in SQL statements.  This is useful when a value
to be used as an identifier is a reserved word or contains backtick
('`') characters.  It was added in MySQL 5.7.14.

*Parameters*

'in_identifier TEXT': The identifier to quote.

*Return Value*

A 'TEXT' value.

*Example*

     mysql> SELECT quote_identifier('plain');
     +---------------------------+
     | quote_identifier('plain') |
     +---------------------------+
     | `plain`                   |
     +---------------------------+
     mysql> SELECT quote_identifier('trick`ier');
     +-------------------------------+
     | quote_identifier('trick`ier') |
     +-------------------------------+
     | `trick``ier`                  |
     +-------------------------------+
     mysql> SELECT quote_identifier('integer');
     +-----------------------------+
     | quote_identifier('integer') |
     +-----------------------------+
     | `integer`                   |
     +-----------------------------+

26.4.5.19 The sys_get_config() Function
.......................................

Given a configuration option name, returns the option value from the
'sys_config' table, or the provided default value
(which may be 'NULL') if the option does not exist in the table.

If 'sys_get_config()' returns the default
value and that value is 'NULL', it is expected that the caller is able
to handle 'NULL' for the given configuration option.

By convention, routines that call 'sys_get_config()'
first check whether the corresponding user-defined
variable exists and is non-'NULL'.  If so, the routine uses the variable
value without reading the 'sys_config' table.  If
the variable does not exist or is 'NULL', the routine reads the option
value from the table and sets the user-defined variable to that value.
For more information about the relationship between configuration
options and their corresponding user-defined variables, see
sys-sys-config.

If you want to check whether the configuration option has already been
set and, if not, use the return value of 'sys_get_config()', you can use
'IFNULL(...)' (see example later).  However, this should not be done
inside a loop (for example, for each row in a result set) because for
repeated calls where the assignment is needed only in the first
iteration, using 'IFNULL(...)' is expected to be significantly slower
than using an 'IF (...) THEN ... END IF;' block (see example later).

*Parameters*

   * 'in_variable_name VARCHAR(128)': The name of the configuration
     option for which to return the value.

   * 'in_default_value VARCHAR(128)': The default value to return if the
     configuration option is not found in the 'sys_config' table.

*Return Value*

A 'VARCHAR(128)' value.

*Example*

Get a configuration value from the 'sys_config'.
table, falling back to 128 as the default if the option is not present
in the table:

     mysql> SELECT sys.sys_get_config('statement_truncate_len', 128) AS Value;
     +-------+
     | Value |
     +-------+
     | 64    |
     +-------+

One-liner example: Check whether the option is already set; if not,
assign the 'IFNULL(...)' result (using the value from the
'sys_config' table):

     mysql> SET @sys.statement_truncate_len =
         -> IFNULL(@sys.statement_truncate_len,
         ->        sys.sys_get_config('statement_truncate_len', 64));

'IF (...) THEN ... END IF;' block example: Check whether the option is
already set; if not, assign the value from the 'sys_config'
table:

     IF (@sys.statement_truncate_len IS NULL) THEN
       SET @sys.statement_truncate_len = sys.sys_get_config('statement_truncate_len', 64);
     END IF;

26.4.5.20 The version_major() Function
......................................

This function returns the major version of the MySQL server.  It was
added in MySQL 5.7.9.

*Parameters*

None.

*Return Value*

A 'TINYINT UNSIGNED' value.

*Example*

     mysql> SELECT VERSION(), version_major();
     +-----------------+-----------------+
     | VERSION()       | version_major() |
     +-----------------+-----------------+
     | 5.7.9-debug-log |               5 |
     +-----------------+-----------------+

26.4.5.21 The version_minor() Function
......................................

This function returns the minor version of the MySQL server.  It was
added in MySQL 5.7.9.

*Parameters*

None.

*Return Value*

A 'TINYINT UNSIGNED' value.

*Example*

     mysql> SELECT VERSION(), version_minor();
     +-----------------+-----------------+
     | VERSION()       | version_minor() |
     +-----------------+-----------------+
     | 5.7.9-debug-log |               7 |
     +-----------------+-----------------+

26.4.5.22 The version_patch() Function
......................................

This function returns the patch release version of the MySQL server.  It
was added in MySQL 5.7.9.

*Parameters*

None.

*Return Value*

A 'TINYINT UNSIGNED' value.

*Example*

     mysql> SELECT VERSION(), version_patch();
     +-----------------+-----------------+
     | VERSION()       | version_patch() |
     +-----------------+-----------------+
     | 5.7.9-debug-log |               9 |
     +-----------------+-----------------+

27 Connectors and APIs
**********************

MySQL Connectors provide connectivity to the MySQL server for client
programs.  APIs provide low-level access to the MySQL protocol and MySQL
resources.  Both Connectors and the APIs enable you to connect and
execute MySQL statements from another language or environment, including
ODBC, Java (JDBC), Perl, Python, PHP, Ruby, and native C and embedded
MySQL instances.

*MySQL Connectors*

Oracle develops a number of connectors:

   * Connector/C (http://dev.mysql.com/doc/connector-c/en/) is a
     standalone replacement for the MySQL Client Library
     ('libmysqlclient'), to be used for C applications.

   * Connector/C++ (http://dev.mysql.com/doc/connector-cpp/en/) enables
     C++ applications to connect to MySQL.

   * Connector/J (http://dev.mysql.com/doc/connector-j/5.1/en/) provides
     driver support for connecting to MySQL from Java applications using
     the standard Java Database Connectivity (JDBC) API.

   * Connector/Net (http://dev.mysql.com/doc/connector-net/en/) enables
     developers to create .NET applications that connect to MySQL.
     Connector/Net implements a fully functional ADO.NET interface and
     provides support for use with ADO.NET aware tools.  Applications
     that use Connector/Net can be written in any supported .NET
     language.

     MySQL for Visual Studio
     (http://dev.mysql.com/doc/visual-studio/en/) works with
     Connector/Net and Microsoft Visual Studio 2012, 2013, 2015, and
     2017.  MySQL for Visual Studio provides access to MySQL objects and
     data from Visual Studio.  As a Visual Studio package, it integrates
     directly into Server Explorer providing the ability to create new
     connections and work with MySQL database objects.

   * Connector/ODBC (http://dev.mysql.com/doc/connector-odbc/en/)
     provides driver support for connecting to MySQL using the Open
     Database Connectivity (ODBC) API. Support is available for ODBC
     connectivity from Windows, Unix, and OS X platforms.

   * Connector/Python (http://dev.mysql.com/doc/connector-python/en/)
     provides driver support for connecting to MySQL from Python
     applications using an API that is compliant with the Python DB API
     version 2.0 (http://www.python.org/dev/peps/pep-0249/).  No
     additional Python modules or MySQL client libraries are required.

*The MySQL C API*

For direct access to using MySQL natively within a C application, there
are two methods:

   * The C API provides low-level access to the MySQL
     client/server protocol through the 'libmysqlclient' client library.
     This is the primary method used to connect to an instance of the
     MySQL server, and is used both by MySQL command-line clients and
     many of the MySQL Connectors and third-party APIs detailed here.

     'libmysqlclient' is included in MySQL distributions and in
     Connector/C distributions.

   * 'libmysqld' is an embedded MySQL server library that enables you to
     embed an instance of the MySQL server into your C applications.

     'libmysqld' is included in MySQL distributions, but not in
     Connector/C distributions.

     *Note*:

     The 'libmysqld' embedded server library is deprecated as of MySQL
     5.7.19 and will be removed in MySQL 8.0.

See also c-api-implementations.

To access MySQL from a C application, or to build an interface to MySQL
for a language not supported by the Connectors or APIs in this chapter,
the C API is where to start.  A number of programmer's
utilities are available to help with the process; see
programs-development.

*Third-Party MySQL APIs*

The remaining APIs described in this chapter provide an interface to
MySQL from specific application languages.  These third-party solutions
are not developed or supported by Oracle.  Basic information on their
usage and abilities is provided here for reference purposes only.

All the third-party language APIs are developed using one of two
methods, using 'libmysqlclient' or by implementing a _native driver_.
The two solutions offer different benefits:

   * Using _'libmysqlclient'_ offers complete compatibility with MySQL
     because it uses the same libraries as the MySQL client
     applications.  However, the feature set is limited to the
     implementation and interfaces exposed through 'libmysqlclient' and
     the performance may be lower as data is copied between the native
     language, and the MySQL API components.

   * _Native drivers_ are an implementation of the MySQL network
     protocol entirely within the host language or environment.  Native
     drivers are fast, as there is less copying of data between
     components, and they can offer advanced functionality not available
     through the standard MySQL API. Native drivers are also easier for
     end users to build and deploy because no copy of the MySQL client
     libraries is needed to build the native driver components.

connectors-apis-summary lists many of the libraries and
interfaces available for MySQL.

*MySQL APIs and Interfaces*

EnvironmentAPI                    Type        Notes

Ada     GNU Ada MySQL Bindings    'libmysqlclient'See MySQL Bindings for GNU
                                              Ada
                                              (http://gnade.sourceforge.net/)

C       C API                     'libmysqlclient'See c-api.

C       Connector/C               Replacement See MySQL Connector/C
                                  for         Developer Guide
                                  'libmysqlclient'(http://dev.mysql.com/doc/connector-c/en/).

C++     Connector/C++             'libmysqlclient'See MySQL Connector/C++
                                              Developer Guide
                                              (http://dev.mysql.com/doc/connector-cpp/en/).

        MySQL++                   'libmysqlclient'See MySQL++ website
                                              (http://tangentsoft.net/mysql++/doc/).

        MySQL wrapped             'libmysqlclient'See MySQL wrapped
                                              (http://www.alhem.net/project/mysql/).

Cocoa   MySQL-Cocoa               'libmysqlclient'Compatible with the
                                              Objective-C Cocoa
                                              environment.  See
                                              <http://mysql-cocoa.sourceforge.net/>

D       MySQL for D               'libmysqlclient'See MySQL for D
                                              (http://www.steinmole.de/d/).

Eiffel  Eiffel MySQL              'libmysqlclient'See apis-eiffel.

Erlang  'erlang-mysql-driver'     'libmysqlclient'See 'erlang-mysql-driver'.
                                              (http://code.google.com/p/erlang-mysql-driver/)

Haskell Haskell MySQL Bindings    Native      See Brian O'Sullivan's pure
                                  Driver      Haskell MySQL bindings
                                              (http://www.serpentine.com/blog/software/mysql/).

        'hsql-mysql'              'libmysqlclient'See MySQL driver for
                                              Haskell
                                              (http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hsql-mysql-1.7).

Java/JDBCConnector/J              Native      See MySQL Connector/J 5.1
                                  Driver      Developer Guide
                                              (http://dev.mysql.com/doc/connector-j/5.1/en/).

Kaya    MyDB                      'libmysqlclient'See MyDB
                                              (http://kayalang.org/library/latest/MyDB).

Lua     LuaSQL                    'libmysqlclient'See LuaSQL
                                              (http://keplerproject.github.io/luasql/doc/us/).

.NET/MonoConnector/Net            Native      See MySQL Connector/Net
                                  Driver      Developer Guide
                                              (http://dev.mysql.com/doc/connector-net/en/).

ObjectiveOBjective Caml MySQL     'libmysqlclient'See MySQL Bindings for
Caml    Bindings                              Objective Caml
                                              (http://raevnos.pennmush.org/code/ocaml-mysql/).

Octave  Database bindings for     'libmysqlclient'See Database bindings for
        GNU Octave                            GNU Octave
                                              (http://octave.sourceforge.net/database/index.html).

ODBC    Connector/ODBC            'libmysqlclient'See MySQL Connector/ODBC
                                              Developer Guide
                                              (http://dev.mysql.com/doc/connector-odbc/en/).

Perl    'DBI'/'DBD::mysql'        'libmysqlclient'See apis-perl.

        'Net::MySQL'              Native      See 'Net::MySQL'
                                  Driver      (http://search.cpan.org/dist/Net-MySQL/MySQL.pm)
                                              at CPAN

PHP     'mysql', 'ext/mysql'      'libmysqlclient'See Original MySQL API
        interface (deprecated)                (http://dev.mysql.com/doc/apis-php/en/apis-php-mysql.html).

        'mysqli', 'ext/mysqli'    'libmysqlclient'See MySQL Improved
        interface                             Extension
                                              (http://dev.mysql.com/doc/apis-php/en/apis-php-mysqli.html).

        'PDO_MYSQL'               'libmysqlclient'See MySQL Functions
                                              (PDO_MYSQL)
                                              (http://dev.mysql.com/doc/apis-php/en/apis-php-pdo-mysql.html).

        PDO mysqlnd               Native
                                  Driver

Python  Connector/Python          Native      See MySQL Connector/Python
                                  Driver      Developer Guide
                                              (http://dev.mysql.com/doc/connector-python/en/).

Python  Connector/Python C        'libmysqlclient'See MySQL Connector/Python
        Extension                             Developer Guide
                                              (http://dev.mysql.com/doc/connector-python/en/).

        MySQLdb                   'libmysqlclient'See apis-python.

Ruby    MySQL/Ruby                'libmysqlclient'Uses 'libmysqlclient'.  See

                                              apis-ruby-mysqlruby.

        Ruby/MySQL                Native      See
                                  Driver apis-ruby-rubymysql.

Scheme  'Myscsh'                  'libmysqlclient'See 'Myscsh'
                                              (https://github.com/aehrisch/myscsh).

SPL     'sql_mysql'               'libmysqlclient'See 'sql_mysql' for SPL
                                              (http://www.clifford.at/spl/spldoc/sql_mysql.html).

Tcl     MySQLtcl                  'libmysqlclient'See apis-tcl.

27.1 MySQL Connector/C
======================

The MySQL Connector/C manual is published in standalone form, not as
part of the MySQL Reference Manual.  For information, see these
documents:

   * Main manual: MySQL Connector/C Developer Guide
     (http://dev.mysql.com/doc/connector-c/en/)

   * Release notes: MySQL Connector/C Release Notes
     (http://dev.mysql.com/doc/relnotes/connector-c/en/)

27.2 MySQL Connector/C++
========================

The MySQL Connector/C++ manual is published in standalone form, not as
part of the MySQL Reference Manual.  For information, see these
documents:

   * Main manual: MySQL Connector/C++ Developer Guide
     (http://dev.mysql.com/doc/connector-cpp/en/)

   * Release notes: MySQL Connector/C++ Release Notes
     (http://dev.mysql.com/doc/relnotes/connector-cpp/en/)

27.3 MySQL Connector/J
======================

The MySQL Connector/J manual is published in standalone form, not as
part of the MySQL Reference Manual.  For information, see these
documents:

   * Main manual: MySQL Connector/J 5.1 Developer Guide
     (http://dev.mysql.com/doc/connector-j/5.1/en/)

   * Release notes: MySQL Connector/J Release Notes
     (http://dev.mysql.com/doc/relnotes/connector-j/en/)

27.4 MySQL Connector/Net
========================

The MySQL Connector/Net manual is published in standalone form, not as
part of the MySQL Reference Manual.  For information, see these
documents:

   * Main manual: MySQL Connector/Net Developer Guide
     (http://dev.mysql.com/doc/connector-net/en/)

   * Release notes: MySQL Connector/Net Release Notes
     (http://dev.mysql.com/doc/relnotes/connector-net/en/)

27.5 MySQL Connector/ODBC
=========================

The MySQL Connector/ODBC manual is published in standalone form, not as
part of the MySQL Reference Manual.  For information, see these
documents:

   * Main manual: MySQL Connector/ODBC Developer Guide
     (http://dev.mysql.com/doc/connector-odbc/en/)

   * Release notes: MySQL Connector/ODBC Release Notes
     (http://dev.mysql.com/doc/relnotes/connector-odbc/en/)

27.6 MySQL Connector/Python
===========================

The MySQL Connector/Python manual is published in standalone form, not
as part of the MySQL Reference Manual.  For information, see these
documents:

   * Main manual: MySQL Connector/Python Developer Guide
     (http://dev.mysql.com/doc/connector-python/en/)

   * Release notes: MySQL Connector/Python Release Notes
     (http://dev.mysql.com/doc/relnotes/connector-python/en/)

27.7 libmysqld, the Embedded MySQL Server Library
=================================================

The embedded MySQL server library makes it possible to run a
full-featured MySQL server inside a client application.  The main
benefits are increased speed and more simple management for embedded
applications.

*Note*:

The 'libmysqld' embedded server library is deprecated as of MySQL 5.7.19
and will be removed in MySQL 8.0.

The embedded server library is based on the client/server version of
MySQL, which is written in C/C++.  Consequently, the embedded server
also is written in C/C++.  There is no embedded server available in
other languages.

The API is identical for the embedded MySQL version and the
client/server version.  To change a threaded application to use the
embedded library, you normally only have to add calls to the following
functions.

*MySQL Embedded Server Library Functions*

Function               When to Call

See Call it before any other MySQL function is 'mysql_library_init()',
preferably early in the 'main()'
mysql-library-init.    function.

See Call it before your program exits. 'mysql_library_end()'.

See Call it in each thread you create that accesses 'mysql_thread_init()'.
mysql-thread-init.

See Call it before calling 'pthread_exit()'. 'mysql_thread_end()'.

Then, link your code with 'libmysqld.a' instead of 'libmysqlclient.a'.
To ensure binary compatibility between your application and the server
library, always compile your application against headers for the same
series of MySQL that was used to compile the server library.  For
example, if 'libmysqld' was compiled against MySQL 5.6 headers, do not
compile your application against MySQL 5.7 headers, or vice versa.

Because the 'mysql_library_XXX()' functions are also included in
'libmysqlclient.a', you can change between the embedded and the
client/server version by just linking your application with the right
library.  See mysql-library-init.

One difference between the embedded server and the standalone server is
that for the embedded server, authentication for connections is disabled
by default.

27.7.1 Compiling Programs with libmysqld
----------------------------------------

In precompiled binary MySQL distributions that include 'libmysqld', the
embedded server library, MySQL builds the library using the appropriate
vendor compiler if there is one.

To get a 'libmysqld' library if you build MySQL from source yourself,
you should configure MySQL with the '-DWITH_EMBEDDED_SERVER=1' option.
See source-configuration-options.

When you link your program with 'libmysqld', you must also include the
system-specific 'pthread' libraries and some libraries that the MySQL
server uses.  You can get the full list of libraries by executing
'mysql_config --libmysqld-libs'.

The correct flags for compiling and linking a threaded program must be
used, even if you do not directly call any thread functions in your
code.

To compile a C program to include the necessary files to embed the MySQL
server library into an executable version of a program, the compiler
will need to know where to find various files and need instructions on
how to compile the program.  The following example shows how a program
could be compiled from the command line, assuming that you are using
'gcc', use the GNU C compiler:

     gcc mysql_test.c -o mysql_test \
     `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`

Immediately following the 'gcc' command is the name of the C program
source file.  After it, the '-o' option is given to indicate that the
file name that follows is the name that the compiler is to give to the
output file, the compiled program.  The next line of code tells the
compiler to obtain the location of the include files and libraries and
other settings for the system on which it is compiled.  The
'mysql_config' command is contained in backticks, not
single quotation marks.

On some non-'gcc' platforms, the embedded library depends on C++ runtime
libraries and linking against the embedded library might result in
missing-symbol errors.  To solve this, link using a C++ compiler or
explicitly list the required libraries on the link command line.

27.7.2 Restrictions When Using the Embedded MySQL Server
--------------------------------------------------------

The embedded server has the following limitations:

   * No user-defined functions (UDFs).

   * No stack trace on core dump.

   * You cannot set this up as a master or a slave (no replication).

   * Very large result sets may be unusable on low memory systems.

   * You cannot connect to an embedded server from an outside process
     with sockets or TCP/IP. However, you can connect to an intermediate
     application, which in turn can connect to an embedded server on the
     behalf of a remote client or outside process.

   * 'InnoDB' is not reentrant in the embedded server and cannot be used
     for multiple connections, either successively or simultaneously.

   * The Event Scheduler is not available.  Because of this, the
     'event_scheduler' system variable is disabled.

   * The Performance Schema is not available.

   * The embedded server cannot share the same 'secure_file_priv'
     directory with another server.  As of MySQL 5.7.8, the default
     value for this directory can be set at build time with the
     'INSTALL_SECURE_FILE_PRIV_EMBEDDEDDIR' 'CMake' option.

Some of these limitations can be changed by editing the 'mysql_embed.h'
include file and recompiling MySQL.

27.7.3 Options with the Embedded Server
---------------------------------------

Any options that may be given with the 'mysqld' server
daemon, may be used with an embedded server library.  Server options may
be given in an array as an argument to the 'mysql_library_init()',
which initializes the server.  They also may be
given in an option file like 'my.cnf'.  To specify an option file for a
C program, use the '--defaults-file' option as one of the elements of
the second argument of the 'mysql_library_init()'
function.  See mysql-library-init, for more
information on the 'mysql_library_init()'.
function.

Using option files can make it easier to switch between a client/server
application and one where MySQL is embedded.  Put common options under
the '[server]' group.  These are read by both MySQL versions.
Client/server-specific options should go under the '[mysqld]' section.
Put options specific to the embedded MySQL server library in the
'[embedded]' section.  Options specific to applications go under section
labeled '[ApplicationName_SERVER]'.  See option-files.

27.7.4 Embedded Server Examples
-------------------------------

These two example programs should work without any changes on a Linux or
FreeBSD system.  For other operating systems, minor changes are needed,
mostly with file paths.  These examples are designed to give enough
details for you to understand the problem, without the clutter that is a
necessary part of a real application.  The first example is very
straightforward.  The second example is a little more advanced with some
error checking.  The first is followed by a command-line entry for
compiling the program.  The second is followed by a GNUmake file that
may be used for compiling instead.

*Example 1*

'test1_libmysqld.c'

     #include <stdio.h>
     #include <stdlib.h>
     #include <stdarg.h>
     #include "mysql.h"

     MYSQL *mysql;
     MYSQL_RES *results;
     MYSQL_ROW record;

     static char *server_options[] = \
            { "mysql_test", "--defaults-file=my.cnf", NULL };
     int num_elements = (sizeof(server_options) / sizeof(char *)) - 1;

     static char *server_groups[] = { "libmysqld_server",
                                      "libmysqld_client", NULL };

     int main(void)
     {
        mysql_library_init(num_elements, server_options, server_groups);
        mysql = mysql_init(NULL);
        mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
        mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);

        mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);

        mysql_query(mysql, "SELECT column1, column2 FROM table1");

        results = mysql_store_result(mysql);

        while((record = mysql_fetch_row(results))) {
           printf("%s - %s \n", record[0], record[1]);
        }

        mysql_free_result(results);
        mysql_close(mysql);
        mysql_library_end();

        return 0;
     }

Here is the command line for compiling the above program:

     gcc test1_libmysqld.c -o test1_libmysqld \
      `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`

*Example 2*

To try the example, create an 'test2_libmysqld' directory at the same
level as the MySQL source directory.  Save the 'test2_libmysqld.c'
source and the 'GNUmakefile' in the directory, and run GNU 'make' from
inside the 'test2_libmysqld' directory.

'test2_libmysqld.c'

     /*
      * A simple example client, using the embedded MySQL server library
     */

     #include <mysql.h>
     #include <stdarg.h>
     #include <stdio.h>
     #include <stdlib.h>

     MYSQL *db_connect(const char *dbname);
     void db_disconnect(MYSQL *db);
     void db_do_query(MYSQL *db, const char *query);

     const char *server_groups[] = {
       "test2_libmysqld_SERVER", "embedded", "server", NULL
     };

     int
     main(int argc, char **argv)
     {
       MYSQL *one, *two;

       /* mysql_library_init() must be called before any other mysql
        * functions.
        *
        * You can use mysql_library_init(0, NULL, NULL), and it
        * initializes the server using groups = {
        *   "server", "embedded", NULL
        *  }.
        *
        * In your $HOME/.my.cnf file, you probably want to put:

     [test2_libmysqld_SERVER]
     language = /path/to/source/of/mysql/sql/share/english

        * You could, of course, modify argc and argv before passing
        * them to this function.  Or you could create new ones in any
        * way you like.  But all of the arguments in argv (except for
        * argv[0], which is the program name) should be valid options
        * for the MySQL server.
        *
        * If you link this client against the normal mysqlclient
        * library, this function is just a stub that does nothing.
        */
       mysql_library_init(argc, argv, (char **)server_groups);

       one = db_connect("test");
       two = db_connect(NULL);

       db_do_query(one, "SHOW TABLE STATUS");
       db_do_query(two, "SHOW DATABASES");

       mysql_close(two);
       mysql_close(one);

       /* This must be called after all other mysql functions */
       mysql_library_end();

       exit(EXIT_SUCCESS);
     }

     static void
     die(MYSQL *db, char *fmt, ...)
     {
       va_list ap;
       va_start(ap, fmt);
       vfprintf(stderr, fmt, ap);
       va_end(ap);
       (void)putc('\n', stderr);
       if (db)
         db_disconnect(db);
       exit(EXIT_FAILURE);
     }

     MYSQL *
     db_connect(const char *dbname)
     {
       MYSQL *db = mysql_init(NULL);
       if (!db)
         die(db, "mysql_init failed: no memory");
       /*
        * Notice that the client and server use separate group names.
        * This is critical, because the server does not accept the
        * client's options, and vice versa.
        */
       mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
       if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
         die(db, "mysql_real_connect failed: %s", mysql_error(db));

       return db;
     }

     void
     db_disconnect(MYSQL *db)
     {
       mysql_close(db);
     }

     void
     db_do_query(MYSQL *db, const char *query)
     {
       if (mysql_query(db, query) != 0)
         goto err;

       if (mysql_field_count(db) > 0)
       {
         MYSQL_RES   *res;
         MYSQL_ROW    row, end_row;
         int num_fields;

         if (!(res = mysql_store_result(db)))
           goto err;
         num_fields = mysql_num_fields(res);
         while ((row = mysql_fetch_row(res)))
         {
           (void)fputs(">> ", stdout);
           for (end_row = row + num_fields; row < end_row; ++row)
             (void)printf("%s\t", row ? (char*)*row : "NULL");
           (void)fputc('\n', stdout);
         }
         (void)fputc('\n', stdout);
         mysql_free_result(res);
       }
       else
         (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));

       return;

     err:
       die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
     }

'GNUmakefile'

     # This assumes the MySQL software is installed in /usr/local/mysql
     inc      := /usr/local/mysql/include/mysql
     lib      := /usr/local/mysql/lib

     # If you have not installed the MySQL software yet, try this instead
     #inc      := $(HOME)/mysql-5.7/include
     #lib      := $(HOME)/mysql-5.7/libmysqld

     CC       := gcc
     CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
     CFLAGS   := -g -W -Wall
     LDFLAGS  := -static
     # You can change -lmysqld to -lmysqlclient to use the
     # client/server library
     LDLIBS    = -L$(lib) -lmysqld -lm -ldl -lcrypt

     ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null))
     # FreeBSD
     LDFLAGS += -pthread
     else
     # Assume Linux
     LDLIBS += -lpthread
     endif

     # This works for simple one-file test programs
     sources := $(wildcard *.c)
     objects := $(patsubst %c,%o,$(sources))
     targets := $(basename $(sources))

     all: $(targets)

     clean:
             rm -f $(targets) $(objects) *.core

27.8 MySQL C API
================

The C API provides low-level access to the MySQL client/server protocol
and enables C programs to access database contents.  The C API code is
distributed with MySQL and implemented in the 'libmysqlclient' library.
See c-api-implementations.

Most other client APIs use the 'libmysqlclient' library to communicate
with the MySQL server.  (Exceptions are Connector/J and Connector/Net.)
This means that, for example, you can take advantage of many of the same
environment variables that are used by other client programs because
they are referenced from the library.  For a list of these variables,
see programs-overview.

For instructions on building client programs using the C API, see
c-api-building-clients.  For programming with threads, see
c-api-threaded-clients.  To create a standalone application which
includes the "server" and "client" in the same program (and does not
communicate with an external MySQL server), see libmysqld.

*Note*:

If, after an upgrade, you experience problems with compiled client
programs, such as 'Commands out of sync' or unexpected core dumps, the
programs were probably compiled using old header or library files.  In
this case, check the date of the 'mysql.h' file and 'libmysqlclient.a'
library used for compilation to verify that they are from the new MySQL
distribution.  If not, recompile the programs with the new headers and
libraries.  Recompilation might also be necessary for programs compiled
against the shared client library if the library major version number
has changed (for example, from 'libmysqlclient.so.17' to
'libmysqlclient.so.18').  For additional compatibility information, see
c-api-running-clients.

Clients have a maximum communication buffer size.  The size of the
buffer that is allocated initially (16KB) is automatically increased up
to the maximum size (16MB by default).  Because buffer sizes are
increased only as demand warrants, simply increasing the maximum limit
does not in itself cause more resources to be used.  This size check is
mostly a precaution against erroneous statements and communication
packets.

The communication buffer must be large enough to contain a single SQL
statement (for client-to-server traffic) and one row of returned data
(for server-to-client traffic).  Each session's communication buffer is
dynamically enlarged to handle any query or row up to the maximum limit.
For example, if you have 'BLOB' values that contain up to
16MB of data, you must have a communication buffer limit of at least
16MB (in both server and client).  The default maximum built into the
client library is 1GB, but the default maximum in the server is 1MB. You
can increase this by changing the value of the 'max_allowed_packet'
parameter at server startup.  See server-configuration.

The MySQL server shrinks each communication buffer to
'net_buffer_length' bytes after each query.  For clients, the size of
the buffer associated with a connection is not decreased until the
connection is closed, at which time client memory is reclaimed.

27.8.1 MySQL C API Implementations
----------------------------------

The MySQL C API is a C-based API that client applications written in C
can use to communicate with MySQL Server.  Client programs refer to C
API header files at compile time and link to a C API library file at
link time.  The library comes in two versions, depending on how the
application is intended to communicate with the server:

   * 'libmysqlclient': The client version of the library, used for
     applications that communicate over a network connection as a client
     of a standalone server process.

   * 'libmysqld': The embedded server version of the library, used for
     applications intended to include an embedded MySQL server within
     the application itself.  The application communicates with its own
     private server instance.

     *Note*:

     The 'libmysqld' embedded server library is deprecated as of MySQL
     5.7.19 and will be removed in MySQL 8.0.

Both libraries have the same interface.  In terms of C API calls, an
application communicates with a standalone server the same way it
communicates with an embedded server.  A given client can be built to
communicate with a standalone or embedded server, depending on whether
it is linked against 'libmysqlclient' or 'libmysqld' at build time.

There are two ways to obtain the C API header and library files required
to build C API client programs:

   * Install a MySQL Server distribution.  Server distributions include
     both 'libmysqlclient' and 'libmysqld'.

   * Install a Connector/C distribution.  Connector/C distributions
     include only 'libmysqlclient'.  They do not include 'libmysqld'.

For both MySQL Server and Connector/C, you can install a binary
distribution that contains the C API files pre-built, or you can use a
source distribution and build the C API files yourself.

Normally, you install either a MySQL Server distribution or a
Connector/C distribution, but not both.  For information about issues
involved with simultaneous MySQL Server and Connector/C installations,
see c-api-multiple-installations.

The names of the library files to use when linking C API client
applications depend on the library type and platform for which a
distribution is built:

   * On Unix (and Unix-like) sytems, the static library is
     'libmysqlclient.a'.  The dynamic library is 'libmysqlclient.so' on
     most Unix systems and 'libmysqlclient.dylib' on OS X.

     For distributions that include embedded server libraries, the
     corresponding library names begin with 'libmysqld' rather than
     'libmysqlclient'.

   * On Windows, the static library is 'mysqlclient.lib' and the dynamic
     library is 'libmysql.dll'.  Windows distributions also include
     'libmysql.lib', a static import library needed for using the
     dynamic library.

     For distributions that include embedded server libraries, the
     corresponding library names are 'mysqlserver.lib', 'libmysqld.dll',
     and 'libmysqld.lib'.

     Windows distributions also include a set of debug libraries.  These
     have the same names as the nondebug libraries, but are located in
     the 'lib/debug' library.  You must use the debug libraries when
     compiling clients built using the debug C runtime.

On Unix, you may also see libraries that include '_r' in the names.
Before MySQL 5.5, these were built as thread-safe (re-entrant) libraries
separately from the non-'_r' libraries.  As of 5.5, both libraries are
the same and the '_r' names are symbolic links to the corresponding
non-'_r' names.  There is no need to use the '_r' libraries.  For
example, if you use 'mysql_config' to obtain linker
flags, you can use 'mysql_config --libs' in all
cases, even for threaded clients.  There is no need to use
'mysql_config --libs_r'.

27.8.2 Simultaneous MySQL Server and Connector/C Installations
--------------------------------------------------------------

MySQL Server and Connector/C installation packages both provide the
files needed to build and run MySQL C API client programs.  This section
discusses when it is possible to install both products on the same
system.  For some packaging formats, this is possible without conflict.
For others, both products cannot be installed at the same time.

This discussion assumes the use of similar package types for both
products (for example, RPM packages for both products).  It does not try
to describe coexistence between packaging types (for example, use of RPM
packages for one product and a 'tar' file package for the other).  Nor
does it describe coexistence of packages provided by Oracle and those
provided by third-party vendors.

If you install both products, it may be necessary to adjust your
development tools or runtime environment to choose one set of header
files and libraries over the other.  See c-api-building-clients,
and c-api-running-clients.

'tar' and Zip file packages install under the directory into which you
unpack them.  For example, you can unpack MySQL Server and Connector/C
'tar' packages under '/usr/local' and they will unpack into distinct
directory names without conflict.

Windows MSI installers use their own installation directory, so MySQL
Server and Connector/C installers do not conflict.

OS X DMG packages install under the same parent directory but in a
different subdirectory, so there is no conflict.  For example:

     /usr/local/mysql-5.6.11-osx10.7-x86_64/
     /usr/local/mysql-connector-c-6.1.0-osx10.7-x86/

Solaris PKG packages install under the same parent directory but in a
different subdirectory, so there is no conflict.  For example:

     /opt/mysql/mysql
     /opt/mysql/connector-c

The Solaris Connector/C installer does not create any symlinks from
system directories such as '/usr/bin' or '/usr/lib' into the
installation directory.  That must be done manually if desired after
installation.

For RPM installations, there are several types of RPM packages.  MySQL
Server 'shared' and 'devel' RPM packages are similar to the
corresponding Connector/C RPM packages.  These RPM package types cannot
coexist because the MySQL Server and Connector/C RPM packages use the
same installation locations for the client library-related files.  This
means the following conditions hold:

   * If MySQL Server 'shared' and 'devel' RPM packages are installed,
     they provide the C API headers and libraries, and there is no need
     to install the Connector/C RPM packages.  To install the
     Connector/C packages anyway, you must first remove the
     corresponding MySQL Server packages.

   * To install MySQL Server RPM packages if you already have
     Connector/C RPM packages installed, you must first remove the
     Connector/C RPM packages.

MySQL Server RPM packages other than 'shared' and 'devel' do not
conflict with Connector/C packages and can be installed if Connector/C
is installed.  This includes the main server RPM that includes the
'mysqld' server itself.

27.8.3 Example C API Client Programs
------------------------------------

Many of the clients in MySQL source distributions are written in C, such
as 'mysql', 'mysqladmin', and
'mysqlshow'.  If you are looking for examples that
demonstrate how to use the C API, take a look at these clients: Obtain a
source distribution and look in its 'client' directory.  See
getting-mysql.

27.8.4 Building and Running C API Client Programs
-------------------------------------------------

The following sections provide information on building client programs
that use the C API. Topics include compiling and linking clients,
writing threaded clients, and troubleshooting runtime problems.

27.8.4.1 Building C API Client Programs
.......................................

This section provides guidelines for compiling C programs that use the
MySQL C API.

*Compiling MySQL Clients on Unix*

The examples here use 'gcc' as the compiler.  A different compiler might
be appropriate on some systems (for example, 'clang' on OS X or FreeBSD,
or Sun Studio on Solaris).  Adjust the examples as necessary.

You may need to specify an '-I' option when you compile client programs
that use MySQL header files, so that the compiler can find them.  For
example, if the header files are installed in
'/usr/local/mysql/include', use this option in the compile command:

     -I/usr/local/mysql/include

MySQL clients must be linked using the '-lmysqlclient' option in the
link command.  You may also need to specify a '-L' option to tell the
linker where to find the library.  For example, if the library is
installed in '/usr/local/mysql/lib', use these options in the link
command:

     -L/usr/local/mysql/lib -lmysqlclient

The path names may differ on your system.  Adjust the '-I' and '-L'
options as necessary.

To make it simpler to compile MySQL programs on Unix, use the
'mysql_config' script.  See mysql-config.

'mysql_config' displays the options needed for
compiling or linking:

     shell> mysql_config --cflags
     shell> mysql_config --libs

You can run those commands to get the proper options and add them
manually to compilation or link commands.  Alternatively, include the
output from 'mysql_config' directly within command
lines using backticks:

     shell> gcc -c `mysql_config --cflags` progname.c
     shell> gcc -o progname progname.o `mysql_config --libs`

On Unix, linking uses dynamic libraries by default.  To link to the
static client library instead, add its path name to the link command.
For example, if the library is located in '/usr/local/mysql/lib', link
like this:

     shell> gcc -o progname progname.o /usr/local/mysql/lib/libmysqlclient.a

Or use 'mysql_config' to provide the library name:

     shell> gcc -o progname progname.o `mysql_config --variable=pkglibdir`/libmysqlclient.a

'mysql_config' does not currently provide a way to
list all libraries needed for static linking, so it might be necessary
to name additional libraries on the link command (for example, '-lnsl
-lsocket' on Solaris).  To get an idea which libraries to add, use
'mysql_config --libs' and 'ldd libmysqlclient.so' (or
'otool -L libmysqlclient.dylib' on OS X).

'pkg-config' can be used as an alternative to 'mysql_config'
for obtaining information such as compiler flags or link
libraries required to compile MySQL applications.  For example, the
following pairs of commands are equivalent:

     mysql_config --cflags
     pkg-config --cflags mysqlclient

     mysql_config --libs
     pkg-config --libs mysqlclient

To produce flags for static linking, use this command:

     pkg-config --static --libs mysqlclient

For more information, see c-api-building-clients-pkg-config.

*Compiling MySQL Clients on Microsoft Windows*

To specify header and library file locations, use the facilities
provided by your development environment.

To build C API clients on Windows, you must link in the C client
library, as well as the Windows ws2_32 sockets library and Secur32
security library.

You link your code with either the dynamic or static C client library.
On Windows, the static library is named 'mysqlclient.lib' and the
dynamic library is named 'libmysql.dll'.  In addition, the
'libmysql.lib' static import library is needed for using the dynamic
library.  If the static C client library is used, the client application
must be compiled with the same version of Visual Studio used to compile
the C client library (which is Visual Studio 2013 for the static C
client library built by Oracle).

*Note*:

The MySQL Connector/C (http://dev.mysql.com/doc/connector-c/en/) is a
standalone, drop-in replacement of the MySQL C client libraries that
come with the MySQL server distribution.  The Oracle-built MySQL
Connector/C (http://dev.mysql.com/doc/connector-c/en/) contains
currently two versions of the static client library, one built with
Visual Studio 2013 and the other one with Visual Studio 2015; use the
one that matches the Visual Studio version you use to compile your
application.

When using the Oracle-built MySQL C client library (or MySQL
Connector/C), following these rules when it comes to linking the C
runtime for your client application:

   * For the Community version of the MySQL C client library (or the
     Community version of MySQL Connector/C):

        * _For version 5.7.17 and before_ (or MySQL Connector/C
          Community 6.1.9 and before):

             * If linking to the static C client library, link
               statically to the C runtime (use the '/MT' compiler
               option).

             * If linking to the dynamic C client library, link either
               statically or dynamically to the C runtime (use either
               '/MT' or '/MD' compiler option).

        * _For version 5.7.18 and later_ (or MySQL Connector/C Community
          6.1.10 and later): Always link dynamically to the C runtime
          (use the '/MD' compiler option), whether you are linking to
          the static or dynamic C client library.  Also, target hosts
          running the client application need to have the Visual C++
          Redistributable for Visual Studio 2013
          (https://www.microsoft.com/en-us/download/details.aspx?id=40784)
          installed if you are using the C client libraries, or the
          Visual C++ Redistributable for Visual Studio 2015
          (https://www.microsoft.com/en-us/download/details.aspx?id=48145)
          installed if you are using MySQL Connector/C.

   * For the Commercial version of the MySQL C client library (or the
     Commercial version of MySQL Connector/C):

        * If linking to the static C client library, link statically to
          the C runtime (use the' /MT' compiler option).

        * If linking to the dynamic C client library, link either
          statically or dynamically to the C runtime (use either '/MT'
          or '/MD' compiler option).

In general, when linking to a static MySQL C client library, the client
library and the client application must use the same compiler option
when it comes to linking the C runtime--that is, if your C client
library is compiled with the '/MT' option, your client application
should also be compiled with the '/MT' option, and so on (see the MSDN
page describing the C library linking options
(http://msdn.microsoft.com/en-us/library/2kzt1wy3.aspx) for more
details).  Follow this rule when you are building your own static MySQL
C client library (or MySQL Connector/C) from source and linking you
client application to it.

*Note*:

_Debug Mode:_ Because of the above-mentioned rule, you cannot build your
application in debug mode (with the '/MTd' or '/MDd' compiler option)
and link it to the static C client library built by Oracle, which is
_not_ built with the debug options; instead, you will have to build the
static client library from source with the debug options.

*Troubleshooting Problems Linking to the MySQL Client Library*

The MySQL client library includes SSL support built in.  It is
unnecessary to specify either '-lssl' or '-lcrypto' at link time.  Doing
so may in fact result in problems at runtime.

If the linker cannot find the MySQL client library, you might get
undefined-reference errors for symbols that start with 'mysql_', such as
those shown here:

     /tmp/ccFKsdPa.o: In function `main':
     /tmp/ccFKsdPa.o(.text+0xb): undefined reference to `mysql_init'
     /tmp/ccFKsdPa.o(.text+0x31): undefined reference to `mysql_real_connect'
     /tmp/ccFKsdPa.o(.text+0x69): undefined reference to `mysql_error'
     /tmp/ccFKsdPa.o(.text+0x9a): undefined reference to `mysql_close'

You should be able to solve this problem by adding '-LDIR_PATH
-lmysqlclient' at the end of your link command, where DIR_PATH
represents the path name of the directory where the client library is
located.  To determine the correct directory, try this command:

     shell> mysql_config --libs

The output from 'mysql_config' might indicate other
libraries that should be specified on the link command as well.  You can
include 'mysql_config' output directly in your
compile or link command using backticks.  For example:

     shell> gcc -o progname progname.o `mysql_config --libs`

If an error occurs at link time that the 'floor' symbol is undefined,
link to the math library by adding '-lm' to the end of the compile/link
line.  Similarly, if you get undefined-reference errors for other
functions that should exist on your system, such as 'connect()', check
the manual page for the function in question to determine which
libraries you should add to the link command.

If you get undefined-reference errors such as the following for
functions that do not exist on your system, it usually means that your
MySQL client library was compiled on a system that is not 100%
compatible with yours:

     mf_format.o(.text+0x201): undefined reference to `__lxstat'

In this case, you should download the latest MySQL or Connector/C source
distribution and compile the MySQL client library yourself.  See
source-installation, and MySQL Connector/C Developer Guide
(http://dev.mysql.com/doc/connector-c/en/).

27.8.4.2 Building C API Client Programs Using pkg-config
........................................................

MySQL distributions contain a 'mysqlclient.pc' file that provides
information about MySQL configuration for use by the 'pkg-config'
command.  This enables 'pkg-config' to be used as an alternative to
'mysql_config' for obtaining information such as
compiler flags or link libraries required to compile MySQL applications.
For example, the following pairs of commands are equivalent:

     mysql_config --cflags
     pkg-config --cflags mysqlclient

     mysql_config --libs
     pkg-config --libs mysqlclient

The last 'pkg-config' command produces flags for dynamic linking.  To
produce flags for static linking, use this command:

     pkg-config --static --libs mysqlclient

On some platforms, the output with and without '--static' might be the
same.

*Note*:

If 'pkg-config' does not find MySQL information, it might be necessary
to set the 'PKG_CONFIG_PATH' environment variable to the directory in
which the 'mysqlclient.pc' file is located, which by default is usually
the 'pkgconfig' directory under the MySQL library directory.  For
example (adjust the location appropriately):

     export PKG_CONFIG_PATH=/usr/local/mysql/lib/pkgconfig # sh, bash, ...
     setenv PKG_CONFIG_PATH /usr/local/mysql/lib/pkgconfig # csh, tcsh, ...

The 'mysqlconfig.pc' installation location can be controlled using the
'INSTALL_PKGCONFIGDIR' 'CMake' option.  See
source-configuration-options.

The '--variable' option takes a configuration variable name and displays
the variable value:

     pkg-config --variable=prefix mysqlclient     # installation prefix directory
     pkg-config --variable=includedir mysqlclient # header file directory
     pkg-config --variable=libdir mysqlclient     # library directory

To see which variable values 'pkg-config' can display using the
'--variable' option, use this command:

     pkg-config --print-variables mysqlclient

You can use 'pkg-config' within a command line using backticks to
include the output that it produces for particular options.  For
example, to compile and link a MySQL client program, use 'pkg-config' as
follows:

     gcc -c `pkg-config --cflags mysqlclient` progname.c
     gcc -o progname progname.o `pkg-config --libs mysqlclient`

27.8.4.3 Writing C API Threaded Client Programs
...............................................

The client library is almost thread-safe.  The biggest problem is that
the subroutines in 'sql/net_serv.cc' that read from sockets are not
interrupt-safe.  This was done with the thought that you might want to
have your own alarm that can break a long read to a server.  If you
install interrupt handlers for the 'SIGPIPE' interrupt, socket handling
should be thread-safe.

To avoid aborting the program when a connection terminates, MySQL blocks
'SIGPIPE' on the first call to 'mysql_library_init()',
see 'mysql_init()', or
'mysql_connect()'.  To use your own 'SIGPIPE' handler,
first call 'mysql_library_init()', then
install your handler.

If 'undefined symbol' errors occur when linking against the
'libmysqlclient' client library, in most cases this is because you have
not included the thread libraries on the link/compile command.

The client library is thread-safe per connection.  You can let two
threads share the same connection with the following caveats:

   * Multiple threads cannot send a query to the MySQL server at the
     same time on the same connection.  In particular, you must ensure
     that between calls to 'mysql_query()' and
     'mysql_store_result()' in one thread, no other
     thread uses the same connection.  You must have a mutex lock around
     your pair of 'mysql_query()' and
     'mysql_store_result()' calls.  After
     'mysql_store_result()' returns, the lock can
     be released and other threads may query the same connection.

     If you use POSIX threads, you can use 'pthread_mutex_lock()' and
     'pthread_mutex_unlock()' to establish and release a mutex lock.

   * Many threads can access different result sets that are retrieved
     with 'mysql_store_result()'.

   * To use 'mysql_use_result()', you must
     ensure that no other thread is using the same connection until the
     result set is closed.  However, it really is best for threaded
     clients that share the same connection to use
     'mysql_store_result()'.

You need to know the following if you have a thread that did not create
the connection to the MySQL database but is calling MySQL functions:

When you call 'mysql_init()', MySQL creates a
thread-specific variable for the thread that is used by the debug
library (among other things).  If you call a MySQL function before the
thread has called 'mysql_init()', the thread does not
have the necessary thread-specific variables in place and you are likely
to end up with a core dump sooner or later.  To avoid problems, you must
do the following:

  1. Call 'mysql_library_init()' before any
     other MySQL functions.  It is not thread-safe, so call it before
     threads are created, or protect the call with a mutex.

  2. Arrange for 'mysql_thread_init()' to be
     called early in the thread handler before calling any MySQL
     function.  If you call 'mysql_init()', it will
     call 'mysql_thread_init()' for you.

  3. In the thread, call 'mysql_thread_end()'.
     before calling 'pthread_exit()'.  This frees the memory used by
     MySQL thread-specific variables.

The preceding notes regarding 'mysql_init()' also
apply to 'mysql_connect()', which calls
'mysql_init()'.

27.8.4.4 Running C API Client Programs
......................................

If, after an upgrade, you experience problems with compiled client
programs, such as 'Commands out of sync' or unexpected core dumps, the
programs were probably compiled using old header or library files.  In
this case, check the date of the 'mysql.h' file and 'libmysqlclient.a'
library used for compilation to verify that they are from the new MySQL
distribution.  If not, recompile the programs with the new headers and
libraries.  Recompilation might also be necessary for programs compiled
against the shared client library if the library major version number
has changed (for example, from 'libmysqlclient.so.17' to
'libmysqlclient.so.18').

The major client library version determines compatibility.  (For
example, for 'libmysqlclient.so.18.1.0', the major version is 18.)  For
this reason, the libraries shipped with newer versions of MySQL are
drop-in replacements for older versions that have the same major number.
As long as the major library version is the same, you can upgrade the
library and old applications should continue to work with it.

Undefined-reference errors might occur at runtime when you try to
execute a MySQL program.  If these errors specify symbols that start
with 'mysql_' or indicate that the 'libmysqlclient' library cannot be
found, it means that your system cannot find the shared
'libmysqlclient.so' library.  The solution to this problem is to tell
your system to search for shared libraries in the directory where that
library is located.  Use whichever of the following methods is
appropriate for your system:

   * Add the path of the directory where 'libmysqlclient.so' is located
     to the 'LD_LIBRARY_PATH' or 'LD_LIBRARY' environment variable.

   * On OS X, add the path of the directory where 'libmysqlclient.dylib'
     is located to the 'DYLD_LIBRARY_PATH' environment variable.

   * Copy the shared-library files (such as 'libmysqlclient.so') to some
     directory that is searched by your system, such as '/lib', and
     update the shared library information by executing 'ldconfig'.  Be
     sure to copy all related files.  A shared library might exist under
     several names, using symlinks to provide the alternate names.

If the application is linked to the embedded server library, runtime
error messages will indicate the 'libmysqld' rather than
'libmysqlclient' library, but the solution to the problem is the same as
just described.

27.8.4.5 C API Server and Client Library Versions
.................................................

The string and numeric forms of the MySQL server version are available
at compile time as the values of the 'MYSQL_SERVER_VERSION' and
'MYSQL_VERSION_ID' macros, and at runtime as the values of the
'mysql_get_server_info()' and
'mysql_get_server_version()' functions.

The MySQL client library version depends on the type of distribution
that provides the library:

   * For MySQL distributions, the client library version is the MySQL
     version.  The string and numeric forms of this version are
     available at compile time as the values of the
     'MYSQL_SERVER_VERSION' and 'MYSQL_VERSION_ID' macros, and at
     runtime as the values of the 'mysql_get_client_info()'
     and 'mysql_get_client_version()'
     functions.

     The 'LIBMYSQL_VERSION' and 'LIBMYSQL_VERSION_ID' macros have the
     same values as 'MYSQL_SERVER_VERSION' and 'MYSQL_VERSION_ID' and
     the two sets of macros can be used interchangeably.

   * For Connector/C distributions, the client library version is the
     Connector/C version.  The string and numeric forms of this version
     are available at compile time as the values of the
     'LIBMYSQL_VERSION' and 'LIBMYSQL_VERSION_ID' macros, and at runtime
     as the values of the 'mysql_get_client_info()'
     and 'mysql_get_client_version()'
     functions.

     The 'MYSQL_SERVER_VERSION' and 'MYSQL_VERSION_ID' macros indicate
     the string and numeric forms of the MySQL version on which the
     Connector/C distribution is based.

27.8.5 C API Data Structures
----------------------------

This section describes C API data structures other than those used for
prepared statements.  For information about the latter, see
c-api-prepared-statement-data-structures.

   *
     'MYSQL'

     This structure represents handler for one database connection.  It
     is used for almost all MySQL functions.  Do not try to make a copy
     of a 'MYSQL' structure.  There is no guarantee that such a copy
     will be usable.

   *
     'MYSQL_RES'

     This structure represents the result of a query that returns rows
     (see 'SELECT', 'SHOW', 'DESCRIBE',
     see 'EXPLAIN').  The information returned
     from a query is called the _result set_ in the remainder of this
     section.

   *
     'MYSQL_ROW'

     This is a type-safe representation of one row of data.  It is
     currently implemented as an array of counted byte strings.  (You
     cannot treat these as null-terminated strings if field values may
     contain binary data, because such values may contain null bytes
     internally.)  Rows are obtained by calling
     'mysql_fetch_row()'.

   *
     'MYSQL_FIELD'

     This structure contains metadata: information about a field, such
     as the field's name, type, and size.  Its members are described in
     more detail later in this section.  You may obtain the
     'MYSQL_FIELD' structures for each field by calling
     'mysql_fetch_field()' repeatedly.  Field values
     are not part of this structure; they are contained in a 'MYSQL_ROW'
     structure.

   *
     'MYSQL_FIELD_OFFSET'

     This is a type-safe representation of an offset into a MySQL field
     list.  (Used by 'mysql_field_seek()')
     Offsets are field numbers within a row, beginning at zero.

   *
     'my_ulonglong'

     The type used for the number of rows and for
     'mysql_affected_rows()',
     'mysql_num_rows()', and 'mysql_insert_id()'.
     This type provides a range of '0' to '1.84e19'.

     Some functions that return a row count using this type return -1 as
     an unsigned value to indicate an error or exceptional condition.
     You can check for -1 by comparing the return value to
     '(my_ulonglong)-1' (or to '(my_ulonglong)~0', which is equivalent).

     On some systems, attempting to print a value of type 'my_ulonglong'
     does not work.  To print such a value, convert it to 'unsigned
     long' and use a '%lu' print format.  Example:

          printf ("Number of rows: %lu\n",
                  (unsigned long) mysql_num_rows(result));

   *
     'my_bool'

     A boolean type, for values that are true (nonzero) or false (zero).

The 'MYSQL_FIELD' structure contains the members described in the
following list.  The definitions apply primarily for columns of result
sets such as those produced by 'SELECT' statements.
'MYSQL_FIELD' structures are also used to provide metadata for 'OUT' and
'INOUT' parameters returned from stored procedures executed using
prepared 'CALL' statements.  For such parameters, some of
the structure members have a meaning different from the meaning for
column values.

   * 'char * name'

     The name of the field, as a null-terminated string.  If the field
     was given an alias with an 'AS' clause, the value of 'name' is the
     alias.  For a procedure parameter, the parameter name.

   * 'char * org_name'

     The name of the field, as a null-terminated string.  Aliases are
     ignored.  For expressions, the value is an empty string.  For a
     procedure parameter, the parameter name.

   * 'char * table'

     The name of the table containing this field, if it is not a
     calculated field.  For calculated fields, the 'table' value is an
     empty string.  If the column is selected from a view, 'table' names
     the view.  If the table or view was given an alias with an 'AS'
     clause, the value of 'table' is the alias.  For a 'UNION',
     the value is the empty string.  For a procedure parameter,
     the procedure name.

   * 'char * org_table'

     The name of the table, as a null-terminated string.  Aliases are
     ignored.  If the column is selected from a view, 'org_table' names
     the view.  If the column is selected from a derived table,
     'org_table' names the base table.  If a derived table wraps a view,
     'org_table' still names the base table.  If the column is an
     expression, 'org_table' is the empty string.  For a 'UNION',
     the value is the empty string.  For a procedure parameter,
     the value is the procedure name.

   * 'char * db'

     The name of the database that the field comes from, as a
     null-terminated string.  If the field is a calculated field, 'db'
     is an empty string.  For a 'UNION', the value is the
     empty string.  For a procedure parameter, the name of the database
     containing the procedure.

   * 'char * catalog'

     The catalog name.  This value is always '"def"'.

   * 'char * def'

     The default value of this field, as a null-terminated string.  This
     is set only if you use 'mysql_list_fields()'.

   * 'unsigned long length'

     The width of the field.  This corresponds to the display length, in
     bytes.

     The server determines the 'length' value before it generates the
     result set, so this is the minimum length required for a data type
     capable of holding the largest possible value from the result
     column, without knowing in advance the actual values that will be
     produced by the query for the result set.

   * 'unsigned long max_length'

     The maximum width of the field for the result set (the length in
     bytes of the longest field value for the rows actually in the
     result set).  If you use 'mysql_store_result()'
     or 'mysql_list_fields()',
     this contains the maximum length for the field.
     If you use 'mysql_use_result()', the value
     of this variable is zero.

     The value of 'max_length' is the length of the string
     representation of the values in the result set.  For example, if
     you retrieve a 'FLOAT' column and the
     'widest' value is '-12.345', 'max_length' is 7 (the length of
     ''-12.345'').

     If you are using prepared statements, 'max_length' is not set by
     default because for the binary protocol the lengths of the values
     depend on the types of the values in the result set.  (See
     c-api-prepared-statement-data-structures.)  If you want the
     'max_length' values anyway, enable the
     'STMT_ATTR_UPDATE_MAX_LENGTH' option with
     'mysql_stmt_attr_set()' and the lengths will
     be set when you call 'mysql_stmt_store_result()'.
     (See mysql-stmt-attr-set, and
     mysql-stmt-store-result.)

   * 'unsigned int name_length'

     The length of 'name'.

   * 'unsigned int org_name_length'

     The length of 'org_name'.

   * 'unsigned int table_length'

     The length of 'table'.

   * 'unsigned int org_table_length'

     The length of 'org_table'.

   * 'unsigned int db_length'

     The length of 'db'.

   * 'unsigned int catalog_length'

     The length of 'catalog'.

   * 'unsigned int def_length'

     The length of 'def'.

   * 'unsigned int flags'

     Bit-flags that describe the field.  The 'flags' value may have zero
     or more of the bits set that are shown in the following table.

     Flag Value                    Flag Description

     'NOT_NULL_FLAG'               Field cannot be 'NULL'

     'PRI_KEY_FLAG'                Field is part of a primary key

     'UNIQUE_KEY_FLAG'             Field is part of a unique key

     'MULTIPLE_KEY_FLAG'           Field is part of a nonunique key

     'UNSIGNED_FLAG'               Field has the 'UNSIGNED' attribute

     'ZEROFILL_FLAG'               Field has the 'ZEROFILL' attribute

     'BINARY_FLAG'                 Field has the 'BINARY' attribute

     'AUTO_INCREMENT_FLAG'         Field has the 'AUTO_INCREMENT' attribute

     'ENUM_FLAG'                   Field is an 'ENUM'.

     'SET_FLAG'                    Field is a 'SET'.

     'BLOB_FLAG'                   Field is a 'BLOB' or
                                   'TEXT'. (deprecated)

     'TIMESTAMP_FLAG'              Field is a 'TIMESTAMP'.
                                   (deprecated)

     'NUM_FLAG'                    Field is numeric; see additional notes
                                   following table

     'NO_DEFAULT_VALUE_FLAG'       Field has no default value; see
                                   additional notes following table

     Some of these flags indicate data type information and are
     superseded by or used in conjunction with the 'MYSQL_TYPE_XXX'
     value in the 'field->type' member described later:

        * To check for 'BLOB' or 'TIMESTAMP'
          values, check whether 'type' is 'MYSQL_TYPE_BLOB' or
          'MYSQL_TYPE_TIMESTAMP'.  (The 'BLOB_FLAG' and 'TIMESTAMP_FLAG'
          flags are unneeded.)

        * 'ENUM' and 'SET' values are returned
          as strings.  For these, check that the 'type' value is
          'MYSQL_TYPE_STRING' and that the 'ENUM_FLAG' or 'SET_FLAG'
          flag is set in the 'flags' value.

     'NUM_FLAG' indicates that a column is numeric.  This includes
     columns with a type of 'MYSQL_TYPE_DECIMAL',
     'MYSQL_TYPE_NEWDECIMAL', 'MYSQL_TYPE_TINY', 'MYSQL_TYPE_SHORT',
     'MYSQL_TYPE_LONG', 'MYSQL_TYPE_FLOAT', 'MYSQL_TYPE_DOUBLE',
     'MYSQL_TYPE_NULL', 'MYSQL_TYPE_LONGLONG', 'MYSQL_TYPE_INT24', and
     'MYSQL_TYPE_YEAR'.

     'NO_DEFAULT_VALUE_FLAG' indicates that a column has no 'DEFAULT'
     clause in its definition.  This does not apply to 'NULL' columns
     (because such columns have a default of 'NULL'), or to
     'AUTO_INCREMENT' columns (which have an implied default value).

     The following example illustrates a typical use of the 'flags'
     value:

          if (field->flags & NOT_NULL_FLAG)
              printf("Field cannot be null\n");

     You may use the convenience macros shown in the following table to
     determine the boolean status of the 'flags' value.

     Flag Status                   Description

     'IS_NOT_NULL(flags)'          True if this field is defined as 'NOT
                                   NULL'

     'IS_PRI_KEY(flags)'           True if this field is a primary key

     'IS_BLOB(flags)'              True if this field is a 'BLOB'
                                   or 'TEXT'. (deprecated;
                                   test 'field->type' instead)

   * 'unsigned int decimals'

     The number of decimals for numeric fields, and the fractional
     seconds precision for temporal fields.

   * 'unsigned int charsetnr'

     An ID number that indicates the character set/collation pair for
     the field.

     Normally, character values in result sets are converted to the
     character set indicated by the 'character_set_results' system
     variable.  In this case, 'charsetnr' corresponds to the character
     set indicated by that variable.  Character set conversion can be
     suppressed by setting 'character_set_results' to 'NULL'.  In this
     case, 'charsetnr' corresponds to the character set of the original
     table column or expression.  See also charset-connection.

     To distinguish between binary and nonbinary data for string data
     types, check whether the 'charsetnr' value is 63.  If so, the
     character set is 'binary', which indicates binary rather than
     nonbinary data.  This enables you to distinguish 'BINARY'
     from 'CHAR', 'VARBINARY'
     from 'VARCHAR', and the 'BLOB'
     types from the 'TEXT' types.

     'charsetnr' values are the same as those displayed in the 'Id'
     column of the 'SHOW COLLATION' statement or
     the 'ID' column of the 'INFORMATION_SCHEMA' 'COLLATIONS'
     table.  You can use those information sources to
     see which character set and collation specific 'charsetnr' values
     indicate:

          mysql> SHOW COLLATION WHERE Id = 63;
          +-----------+---------+----+---------+----------+---------+
          | Collation | Charset | Id | Default | Compiled | Sortlen |
          +-----------+---------+----+---------+----------+---------+
          | binary    | binary  | 63 | Yes     | Yes      |       1 |
          +-----------+---------+----+---------+----------+---------+

          mysql> SELECT COLLATION_NAME, CHARACTER_SET_NAME
              -> FROM INFORMATION_SCHEMA.COLLATIONS WHERE ID = 33;
          +-----------------+--------------------+
          | COLLATION_NAME  | CHARACTER_SET_NAME |
          +-----------------+--------------------+
          | utf8_general_ci | utf8               |
          +-----------------+--------------------+

   * 'enum enum_field_types type'

     The type of the field.  The 'type' value may be one of the
     'MYSQL_TYPE_' symbols shown in the following table.

     Type Value                Type Description

     'MYSQL_TYPE_TINY'         'TINYINT' field

     'MYSQL_TYPE_SHORT'        'SMALLINT' field

     'MYSQL_TYPE_LONG'         'INTEGER' field

     'MYSQL_TYPE_INT24'        'MEDIUMINT' field

     'MYSQL_TYPE_LONGLONG'     'BIGINT' field

     'MYSQL_TYPE_DECIMAL'      'DECIMAL' or
                               'NUMERIC' field

     'MYSQL_TYPE_NEWDECIMAL'   Precision math 'DECIMAL'
                               or 'NUMERIC'.

     'MYSQL_TYPE_FLOAT'        'FLOAT' field

     'MYSQL_TYPE_DOUBLE'       'DOUBLE' or
                               'REAL' field

     'MYSQL_TYPE_BIT'          'BIT' field

     'MYSQL_TYPE_TIMESTAMP'    'TIMESTAMP' field

     'MYSQL_TYPE_DATE'         'DATE' field

     'MYSQL_TYPE_TIME'         'TIME' field

     'MYSQL_TYPE_DATETIME'     'DATETIME' field

     'MYSQL_TYPE_YEAR'         'YEAR' field

     'MYSQL_TYPE_STRING'       'CHAR' or 'BINARY'
                               field

     'MYSQL_TYPE_VAR_STRING'   'VARCHAR' or 'VARBINARY'
                               field

     'MYSQL_TYPE_BLOB'         'BLOB' or 'TEXT'.
                               field (use 'max_length' to determine the
                               maximum length)

     'MYSQL_TYPE_SET'          'SET' field

     'MYSQL_TYPE_ENUM'         'ENUM' field

     'MYSQL_TYPE_GEOMETRY'     Spatial field

     'MYSQL_TYPE_NULL'         'NULL'-type field

     The 'MYSQL_TYPE_TIME2', 'MYSQL_TYPE_DATETIME2', and
     'MYSQL_TYPE_TIMESTAMP2') type codes are used only on the server
     side.  Clients see the 'MYSQL_TYPE_TIME', 'MYSQL_TYPE_DATETIME',
     and 'MYSQL_TYPE_TIMESTAMP' codes.

     You can use the 'IS_NUM()' macro to test whether a field has a
     numeric type.  Pass the 'type' value to 'IS_NUM()' and it evaluates
     to TRUE if the field is numeric:

          if (IS_NUM(field->type))
              printf("Field is numeric\n");

     'ENUM' and 'SET' values are returned as
     strings.  For these, check that the 'type' value is
     'MYSQL_TYPE_STRING' and that the 'ENUM_FLAG' or 'SET_FLAG' flag is
     set in the 'flags' value.

27.8.6 C API Function Overview
------------------------------

The following list summarizes the functions available in the C API. For
greater detail, see the descriptions in c-api-functions.

   * 'my_init()'.: Initialize global variables, and
     thread handler in thread-safe programs

   * 'mysql_affected_rows()'.: Returns the
     number of rows changed/deleted/inserted by the last 'UPDATE',
     see 'DELETE', or 'INSERT' query

   * 'mysql_autocommit()'.: Toggles autocommit
     mode on/off

   * 'mysql_change_user()'.: Changes user and
     database on an open connection

   * 'mysql_character_set_name()'.:
     Return default character set name for current connection

   * 'mysql_client_find_plugin()'.:
     Return pointer to plugin

   * 'mysql_client_register_plugin()'.:
     Register a plugin

   * 'mysql_close()'.: Closes a server connection

   * 'mysql_commit()'.: Commits the transaction

   * 'mysql_connect()'.: Connects to a MySQL server
     (this function is deprecated; use 'mysql_real_connect()'
     instead)

   * 'mysql_create_db()'.: Creates a database
     (this function is deprecated; use the SQL statement 'CREATE DATABASE'
     instead)

   * 'mysql_data_seek()'.: Seeks to an arbitrary
     row number in a query result set

   * 'mysql_debug()'.: Does a 'DBUG_PUSH' with the
     given string

   * 'mysql_drop_db()'.: Drops a database (this
     function is deprecated; use the SQL statement 'DROP DATABASE'
     instead)

   * 'mysql_dump_debug_info()'.: Makes the
     server write debug information to the log

   * 'mysql_eof()'.: Determines whether the last row of
     a result set has been read (this function is deprecated; see
     'mysql_errno()' or 'mysql_error()'
     may be used instead)

   * 'mysql_errno()'.: Returns the error number for
     the most recently invoked MySQL function

   * 'mysql_error()'.: Returns the error message for
     the most recently invoked MySQL function

   * 'mysql_escape_string()'.: Escapes
     special characters in a string for use in an SQL statement

   * 'mysql_fetch_field()'.: Returns the type
     of the next table field

   * 'mysql_fetch_field_direct()'.:
     Returns the type of a table field, given a field number

   * 'mysql_fetch_fields()'.: Returns an array
     of all field structures

   * 'mysql_fetch_lengths()'.: Returns the
     lengths of all columns in the current row

   * 'mysql_fetch_row()'.: Fetches the next row
     from the result set

   * 'mysql_field_count()'.: Returns the number
     of result columns for the most recent statement

   * 'mysql_field_seek()'.: Puts the column
     cursor on a specified column

   * 'mysql_field_tell()'.: Returns the position
     of the field cursor used for the last 'mysql_fetch_field()'.

   * 'mysql_free_result()'.: Frees memory used
     by a result set

   * 'mysql_get_character_set_info()'.:
     Return information about default
     character set

   * 'mysql_get_client_info()'.: Returns
     client version information as a string

   * 'mysql_get_client_version()'.:
     Returns client version information as an integer

   * 'mysql_get_host_info()'.: Returns a
     string describing the connection

   * 'mysql_get_option()'.: Returns the value of
     a 'mysql_options()' option

   * 'mysql_get_proto_info()'.: Returns the
     protocol version used by the connection

   * 'mysql_get_server_info()'.: Returns
     the server version number

   * 'mysql_get_server_version()'.:
     Returns version number of server as an integer

   * 'mysql_get_ssl_cipher()'.: Return
     current SSL cipher

   * 'mysql_hex_string()'.: Encode string in
     hexadecimal format

   * 'mysql_info()'.: Returns information about the
     most recently executed query

   * 'mysql_init()'.: Gets or initializes a 'MYSQL'
     structure

   * 'mysql_insert_id()'.: Returns the ID
     generated for an 'AUTO_INCREMENT' column by the previous query

   * 'mysql_kill()'.: Kills a given thread

   * 'mysql_library_end()'.: Finalize the MySQL
     C API library

   * 'mysql_library_init()'.: Initialize the
     MySQL C API library

   * 'mysql_list_dbs()'.: Returns database names
     matching a simple regular expression

   * 'mysql_list_fields()'.: Returns field
     names matching a simple regular expression

   * 'mysql_list_processes()'.: Returns a
     list of the current server threads

   * 'mysql_list_tables()'.: Returns table
     names matching a simple regular expression

   * 'mysql_load_plugin()'.: Load a plugin

   * 'mysql_load_plugin_v()'.: Load a plugin

   * 'mysql_more_results()'.: Checks whether
     any more results exist

   * 'mysql_next_result()'.: Returns/initiates
     the next result in multiple-result executions

   * 'mysql_num_fields()'.: Returns the number
     of columns in a result set

   * 'mysql_num_rows()'.: Returns the number of
     rows in a result set

   * 'mysql_options()'.: Sets connect options for
     'mysql_real_connect()'.

   * 'mysql_options4()'.: Sets connect options for
     'mysql_real_connect()'.

   * 'mysql_ping()'.: Checks whether the connection to
     the server is working, reconnecting as necessary

   * 'mysql_plugin_options()'.: Set a plugin
     option

   * 'mysql_query()'.: Executes an SQL query
     specified as a null-terminated string

   * 'mysql_real_connect()'.: Connects to a
     MySQL server

   * 'mysql_real_escape_string()'.:
     Escapes special characters in a string for use in an SQL statement,
     taking into account the current character set of the connection

   * 'mysql_real_escape_string_quote()'.:
     Escapes special characters in a
     string for use in an SQL statement, taking into account the current
     character set of the connection and the quoting context

   * 'mysql_real_query()'.: Executes an SQL
     query specified as a counted string

   * 'mysql_refresh()'.: Flush or reset tables and
     caches

   * 'mysql_reload()'.: Tells the server to reload
     the grant tables

   * 'mysql_reset_connection()'.: Reset
     connection to clear session state

   * 'mysql_rollback()'.: Rolls back the
     transaction

   * 'mysql_row_seek()'.: Seeks to a row offset in
     a result set, using value returned from 'mysql_row_tell()'.

   * 'mysql_row_tell()'.: Returns the row cursor
     position

   * 'mysql_select_db()'.: Selects a database

   * 'mysql_server_end()'.: Finalize the MySQL C
     API library

   * 'mysql_server_init()'.: Initialize the
     MySQL C API library

   * 'mysql_session_track_get_first()'.:
     Get first part of session
     state-change information

   * 'mysql_session_track_get_next()'.:
     Get next part of session
     state-change information

   * 'mysql_set_character_set()'.: Set
     default character set for current connection

   * 'mysql_set_local_infile_default()'.:
     Set the 'LOAD DATA LOCAL INFILE'
     handler callbacks to their default values

   * 'mysql_set_local_infile_handler()'.:
     Install application-specific
     'LOAD DATA LOCAL INFILE' handler callbacks

   * 'mysql_set_server_option()'.: Sets
     an option for the connection (like 'multi-statements')

   * 'mysql_sqlstate()'.: Returns the SQLSTATE
     error code for the last error

   * 'mysql_shutdown()'.: Shuts down the database
     server

   * 'mysql_ssl_set()'.: Prepare to establish SSL
     connection to server

   * 'mysql_stat()'.: Returns the server status as a
     string

   * 'mysql_store_result()'.: Retrieves a
     complete result set to the client

   * 'mysql_thread_end()'.: Finalize thread
     handler

   * 'mysql_thread_id()'.: Returns the current
     thread ID

   * 'mysql_thread_init()'.: Initialize thread
     handler

   * 'mysql_thread_safe()'.: Returns 1 if the
     clients are compiled as thread-safe

   * 'mysql_use_result()'.: Initiates a
     row-by-row result set retrieval

   * 'mysql_warning_count()'.: Returns the
     warning count for the previous SQL statement

Application programs should use this general outline for interacting
with MySQL:

  1. Initialize the MySQL client library by calling
     'mysql_library_init()'.  This function exists
     in both the 'libmysqlclient' C client library and the 'libmysqld'
     embedded server library, so it is used whether you build a regular
     client program by linking with the '-libmysqlclient' flag, or an
     embedded server application by linking with the '-libmysqld' flag.

  2. Initialize a connection handler by calling 'mysql_init()'
     and connect to the server by calling
     'mysql_real_connect()'.

  3. Issue SQL statements and process their results.  (The following
     discussion provides more information about how to do this.)

  4. Close the connection to the MySQL server by calling
     'mysql_close()'.

  5. End use of the MySQL client library by calling
     'mysql_library_end()'.

The purpose of calling 'mysql_library_init()'.
and 'mysql_library_end()' is to provide proper
initialization and finalization of the MySQL client library.  For
applications that are linked with the client library, they provide
improved memory management.  If you do not call
'mysql_library_end()', a block of memory remains
allocated.  (This does not increase the amount of memory used by the
application, but some memory leak detectors will complain about it.)
For applications that are linked with the embedded server, these calls
start and stop the server.

In a nonmulti-threaded environment, the call to
'mysql_library_init()' may be omitted, because
'mysql_init()' will invoke it automatically as
necessary.  However, see 'mysql_library_init()'.
is not thread-safe in a multi-threaded environment, and thus neither is
'mysql_init()', which calls
'mysql_library_init()'.  You must either call
'mysql_library_init()' prior to spawning any
threads, or else use a mutex to protect the call, whether you invoke
'mysql_library_init()' or indirectly through
'mysql_init()'.  This should be done prior to any
other client library call.

To connect to the server, call 'mysql_init()' to
initialize a connection handler, then call 'mysql_real_connect()'
with that handler (along with other information such
as the host name, user name, and password).  Upon connection, see
'mysql_real_connect()' sets the 'reconnect' flag
(part of the 'MYSQL' structure) to a value of '1' in versions of the API
older than 5.0.3, or '0' in newer versions.  A value of '1' for this
flag indicates that if a statement cannot be performed because of a lost
connection, to try reconnecting to the server before giving up.  You can
use the 'MYSQL_OPT_RECONNECT' option to 'mysql_options()'
to control reconnection behavior.  When you are done with
the connection, call 'mysql_close()' to terminate
it.

While a connection is active, the client may send SQL statements to the
server using 'mysql_query()' or
'mysql_real_query()'.  The difference between the two
is that 'mysql_query()' expects the query to be
specified as a null-terminated string whereas
'mysql_real_query()' expects a counted string.  If
the string contains binary data (which may include null bytes), you must
use 'mysql_real_query()'.

For each non-see 'SELECT' query (for example, see 'INSERT',
see 'UPDATE', 'DELETE'), you can find
out how many rows were changed (affected) by calling
'mysql_affected_rows()'.

For 'SELECT' queries, you retrieve the selected rows as a
result set.  (Note that some statements are 'SELECT'.-like
in that they return rows.  These include 'SHOW',
'DESCRIBE', and 'EXPLAIN'.  Treat these
statements the same way as 'SELECT' statements.)

There are two ways for a client to process result sets.  One way is to
retrieve the entire result set all at once by calling
'mysql_store_result()'.  This function acquires from
the server all the rows returned by the query and stores them in the
client.  The second way is for the client to initiate a row-by-row
result set retrieval by calling 'mysql_use_result()'.
This function initializes the retrieval, but does not
actually get any rows from the server.

In both cases, you access rows by calling 'mysql_fetch_row()'.
With 'mysql_store_result()',
'mysql_fetch_row()' accesses rows that have
previously been fetched from the server.  With
'mysql_use_result()', 'mysql_fetch_row()'
actually retrieves the row from the server.
Information about the size of the data in each row is available by
calling 'mysql_fetch_lengths()'.

After you are done with a result set, call 'mysql_free_result()'
to free the memory used for it.

The two retrieval mechanisms are complementary.  Choose the approach
that is most appropriate for each client application.  In practice,
clients tend to use 'mysql_store_result()'.
more commonly.

An advantage of 'mysql_store_result()' is
that because the rows have all been fetched to the client, you not only
can access rows sequentially, you can move back and forth in the result
set using 'mysql_data_seek()' or
'mysql_row_seek()' to change the current row position
within the result set.  You can also find out how many rows there are by
calling 'mysql_num_rows()'.  On the other hand,
the memory requirements for 'mysql_store_result()'
may be very high for large result sets and you are
more likely to encounter out-of-memory conditions.

An advantage of 'mysql_use_result()' is that
the client requires less memory for the result set because it maintains
only one row at a time (and because there is less allocation overhead,
see 'mysql_use_result()' can be faster).
Disadvantages are that you must process each row quickly to avoid tying
up the server, you do not have random access to rows within the result
set (you can only access rows sequentially), and the number of rows in
the result set is unknown until you have retrieved them all.
Furthermore, you _must_ retrieve all the rows even if you determine in
mid-retrieval that you've found the information you were looking for.

The API makes it possible for clients to respond appropriately to
statements (retrieving rows only as necessary) without knowing whether
the statement is a 'SELECT'.  You can do this by calling
'mysql_store_result()' after each
'mysql_query()'. (or 'mysql_real_query()').
If the result set call succeeds, the statement was
a 'SELECT' and you can read the rows.  If the result set
call fails, call 'mysql_field_count()' to
determine whether a result was actually to be expected.  If
'mysql_field_count()' returns zero, the statement
returned no data (indicating that it was an 'INSERT',
'UPDATE', 'DELETE', and so forth), and was
not expected to return rows.  If 'mysql_field_count()'
is nonzero, the statement should have returned rows,
but did not.  This indicates that the statement was a 'SELECT'
that failed.  See the description for
'mysql_field_count()' for an example of how this can
be done.

Both 'mysql_store_result()' and
'mysql_use_result()' enable you to obtain information
about the fields that make up the result set (the number of fields,
their names and types, and so forth).  You can access field information
sequentially within the row by calling 'mysql_fetch_field()'
repeatedly, or by field number within the row by
calling 'mysql_fetch_field_direct()'.
The current field cursor position may be changed by calling
'mysql_field_seek()'.  Setting the field cursor
affects subsequent calls to 'mysql_fetch_field()'.
You can also get information for fields all at once
by calling 'mysql_fetch_fields()'.

For detecting and reporting errors, MySQL provides access to error
information by means of the 'mysql_errno()' and
'mysql_error()' functions.  These return the error
code or error message for the most recently invoked function that can
succeed or fail, enabling you to determine when an error occurred and
what it was.

27.8.7 C API Function Descriptions
----------------------------------

In the descriptions here, a parameter or return value of 'NULL' means
'NULL' in the sense of the C programming language, not a MySQL 'NULL'
value.

Functions that return a value generally return a pointer or an integer.
Unless specified otherwise, functions returning a pointer return a
non-'NULL' value to indicate success or a 'NULL' value to indicate an
error, and functions returning an integer return zero to indicate
success or nonzero to indicate an error.  Note that 'nonzero' means just
that.  Unless the function description says otherwise, do not test
against a value other than zero:

     if (result)                   /* correct */
         ... error ...

     if (result < 0)               /* incorrect */
         ... error ...

     if (result == -1)             /* incorrect */
         ... error ...

When a function returns an error, the *Errors* subsection of the
function description lists the possible types of errors.  You can find
out which of these occurred by calling 'mysql_errno()'.
A string representation of the error may be obtained by
calling 'mysql_error()'.

27.8.7.1 mysql_affected_rows()
..............................

'my_ulonglong mysql_affected_rows(MYSQL *mysql)'

*Description*

'mysql_affected_rows()' may be called
immediately after executing a statement with 'mysql_query()'
or 'mysql_real_query()'.  It
returns the number of rows changed, deleted, or inserted by the last
statement if it was an 'UPDATE', 'DELETE',
or 'INSERT'.  For 'SELECT' statements,
see 'mysql_affected_rows()' works like
'mysql_num_rows()'.

For 'UPDATE' statements, the affected-rows value by
default is the number of rows actually changed.  If you specify the
'CLIENT_FOUND_ROWS' flag to 'mysql_real_connect()'
when connecting to 'mysqld', the
affected-rows value is the number of rows 'found'; that is, matched by
the 'WHERE' clause.

For 'REPLACE' statements, the affected-rows value is 2
if the new row replaced an old row, because in this case, one row was
inserted after the duplicate was deleted.

For 'INSERT ... ON DUPLICATE KEY UPDATE'.
statements, the affected-rows value per row is 1 if the row is inserted
as a new row, 2 if an existing row is updated, and 0 if an existing row
is set to its current values.  If you specify the 'CLIENT_FOUND_ROWS'
flag, the affected-rows value is 1 (not 0) if an existing row is set to
its current values.

Following a 'CALL' statement for a stored procedure, see
'mysql_affected_rows()' returns the value that it
would return for the last statement executed within the procedure, or
'0' if that statement would return '-1'.  Within the procedure, you can
use 'ROW_COUNT()' at the SQL level to obtain the affected-rows value for
individual statements.

In MySQL 5.7, see 'mysql_affected_rows()'.
returns a meaningful value for a wider range of statements.  For
details, see the description for 'ROW_COUNT()' in
information-functions.

*Return Values*

An integer greater than zero indicates the number of rows affected or
retrieved.  Zero indicates that no records were updated for an
'UPDATE' statement, no rows matched the 'WHERE' clause in the
query or that no query has yet been executed.  -1 indicates that the
query returned an error or that, for a 'SELECT' query,
see 'mysql_affected_rows()' was called prior to
calling 'mysql_store_result()'.

Because 'mysql_affected_rows()' returns an
unsigned value, you can check for -1 by comparing the return value to
'(my_ulonglong)-1' (or to '(my_ulonglong)~0', which is equivalent).

*Errors*

None.

*Example*

     char *stmt = "UPDATE products SET cost=cost*1.25
                   WHERE group=10";
     mysql_query(&mysql,stmt);
     printf("%ld products updated",
            (long) mysql_affected_rows(&mysql));

27.8.7.2 mysql_autocommit()
...........................

'my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)'

*Description*

Sets autocommit mode on if 'mode' is 1, off if 'mode' is 0.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

None.

27.8.7.3 mysql_change_user()
............................

'my_bool mysql_change_user(MYSQL *mysql, const char *user, const char
*password, const char *db)'

*Description*

Changes the user and causes the database specified by 'db' to become the
default (current) database on the connection specified by 'mysql'.  In
subsequent queries, this database is the default for table references
that include no explicit database specifier.

'mysql_change_user()' fails if the connected
user cannot be authenticated or does not have permission to use the
database.  In this case, the user and database are not changed.

Pass a 'db' parameter of 'NULL' if you do not want to have a default
database.

This function resets the session state as if one had done a new connect
and reauthenticated.  (See c-api-auto-reconnect.)  It always
performs a 'ROLLBACK' of any active transactions, closes
and drops all temporary tables, and unlocks all locked tables.  Session
system variables are reset to the values of the corresponding global
system variables.  Prepared statements are released and 'HANDLER'
variables are closed.  Locks acquired with 'GET_LOCK()' are
released.  These effects occur even if the user did not change.

To reset the connection state in a more lightweight manner without
changing the user, use 'mysql_reset_connection()'.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

The same that you can get from 'mysql_real_connect()',
plus:

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

   * 'ER_UNKNOWN_COM_ERROR'

     The MySQL server does not implement this command (probably an old
     server).

   * 'ER_ACCESS_DENIED_ERROR'

     The user or password was wrong.

   * 'ER_BAD_DB_ERROR'

     The database did not exist.

   * 'ER_DBACCESS_DENIED_ERROR'

     The user did not have access rights to the database.

   * 'ER_WRONG_DB_NAME'

     The database name was too long.

*Example*

     if (mysql_change_user(&mysql, "user", "PASSWORD", "new_database"))
     {
        fprintf(stderr, "Failed to change user.  Error: %s\n",
                mysql_error(&mysql));
     }

27.8.7.4 mysql_character_set_name()
...................................

'const char *mysql_character_set_name(MYSQL *mysql)'

*Description*

Returns the default character set name for the current connection.

*Return Values*

The default character set name

*Errors*

None.

27.8.7.5 mysql_close()
......................

'void mysql_close(MYSQL *mysql)'

*Description*

Closes a previously opened connection.  'mysql_close()'
also deallocates the connection handler pointed to by
'mysql' if the handler was allocated automatically by
'mysql_init()' or 'mysql_connect()'.

*Return Values*

None.

*Errors*

None.

27.8.7.6 mysql_commit()
.......................

'my_bool mysql_commit(MYSQL *mysql)'

*Description*

Commits the current transaction.

The action of this function is subject to the value of the
'completion_type' system variable.  In particular, if the value of
'completion_type' is 'RELEASE' (or 2), the server performs a release
after terminating a transaction and closes the client connection.  Call
'mysql_close()' from the client program to close the
connection from the client side.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

None.

27.8.7.7 mysql_connect()
........................

'MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user,
const char *passwd)'

*Description*

This function is deprecated.  Use 'mysql_real_connect()'
instead.

'mysql_connect()' attempts to establish a
connection to a MySQL database engine running on 'host'.
'mysql_connect()' must complete successfully before you
can execute any of the other API functions, with the exception of
'mysql_get_client_info()'.

The meanings of the parameters are the same as for the corresponding
parameters for 'mysql_real_connect()' with
the difference that the connection parameter may be 'NULL'.  In this
case, the C API allocates memory for the connection structure
automatically and frees it when you call 'mysql_close()'.
The disadvantage of this approach is that you cannot
retrieve an error message if the connection fails.  (To get error
information from 'mysql_errno()' or
'mysql_error()', you must provide a valid 'MYSQL' pointer.)

*Return Values*

Same as for 'mysql_real_connect()'.

*Errors*

Same as for 'mysql_real_connect()'.

27.8.7.8 mysql_create_db()
..........................

'int mysql_create_db(MYSQL *mysql, const char *db)'

*Description*

Creates the database named by the 'db' parameter.

This function is deprecated.  Use 'mysql_query()' to
issue an SQL 'CREATE DATABASE' statement
instead.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

     if(mysql_create_db(&mysql, "my_database"))
     {
        fprintf(stderr, "Failed to create new database.  Error: %s\n",
                mysql_error(&mysql));
     }

27.8.7.9 mysql_data_seek()
..........................

'void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)'

*Description*

Seeks to an arbitrary row in a query result set.  The 'offset' value is
a row number.  Specify a value in the range from '0' to
'mysql_num_rows(result)-1'.

This function requires that the result set structure contains the entire
result of the query, so 'mysql_data_seek()' may
be used only in conjunction with 'mysql_store_result()',
not with 'mysql_use_result()'.

*Return Values*

None.

*Errors*

None.

27.8.7.10 mysql_debug()
.......................

'void mysql_debug(const char *debug)'

*Description*

Does a 'DBUG_PUSH' with the given string.  'mysql_debug()'
uses the Fred Fish debug library.  To use this function,
you must compile the client library to support debugging.  See
dbug-package.

*Return Values*

None.

*Errors*

None.

*Example*

The call shown here causes the client library to generate a trace file
in '/tmp/client.trace' on the client machine:

     mysql_debug("d:t:O,/tmp/client.trace");

27.8.7.11 mysql_drop_db()
.........................

'int mysql_drop_db(MYSQL *mysql, const char *db)'

*Description*

Drops the database named by the 'db' parameter.

This function is deprecated.  Use 'mysql_query()' to
issue an SQL 'DROP DATABASE' statement instead.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

     if(mysql_drop_db(&mysql, "my_database"))
       fprintf(stderr, "Failed to drop the database: Error: %s\n",
               mysql_error(&mysql));

27.8.7.12 mysql_dump_debug_info()
.................................

'int mysql_dump_debug_info(MYSQL *mysql)'

*Description*

Instructs the server to write debugging information to the error log.
The connected user must have the 'SUPER' privilege.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.13 mysql_eof()
.....................

'my_bool mysql_eof(MYSQL_RES *result)'

*Description*

This function is deprecated.  'mysql_errno()' or
'mysql_error()' may be used instead.

'mysql_eof()' determines whether the last row of a
result set has been read.

If you acquire a result set from a successful call to
'mysql_store_result()', the client receives the
entire set in one operation.  In this case, a 'NULL' return from
'mysql_fetch_row()' always means the end of the result
set has been reached and it is unnecessary to call 'mysql_eof()'.
When used with 'mysql_store_result()',
see 'mysql_eof()' always returns true.

On the other hand, if you use 'mysql_use_result()'
to initiate a result set retrieval, the rows of the
set are obtained from the server one by one as you call
'mysql_fetch_row()' repeatedly.  Because an error may
occur on the connection during this process, a 'NULL' return value from
'mysql_fetch_row()' does not necessarily mean
the end of the result set was reached normally.  In this case, you can
use 'mysql_eof()' to determine what happened.
'mysql_eof()' returns a nonzero value if the end of the
result set was reached and zero if an error occurred.

Historically, see 'mysql_eof()' predates the standard
MySQL error functions 'mysql_errno()' and
'mysql_error()'.  Because those error functions provide the
same information, their use is preferred over 'mysql_eof()',
which is deprecated.  (In fact, they provide more
information, because 'mysql_eof()' returns only a
boolean value whereas the error functions indicate a reason for the
error when one occurs.)

*Return Values*

Zero for success.  Nonzero if the end of the result set has been
reached.

*Errors*

None.

*Example*

The following example shows how you might use 'mysql_eof()'.:

     mysql_query(&mysql,"SELECT * FROM some_table");
     result = mysql_use_result(&mysql);
     while((row = mysql_fetch_row(result)))
     {
         // do something with data
     }
     if(!mysql_eof(result))  // mysql_fetch_row() failed due to an error
     {
         fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
     }

However, you can achieve the same effect with the standard MySQL error
functions:

     mysql_query(&mysql,"SELECT * FROM some_table");
     result = mysql_use_result(&mysql);
     while((row = mysql_fetch_row(result)))
     {
         // do something with data
     }
     if(mysql_errno(&mysql))  // mysql_fetch_row() failed due to an error
     {
         fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
     }

27.8.7.14 mysql_errno()
.......................

'unsigned int mysql_errno(MYSQL *mysql)'

*Description*

For the connection specified by 'mysql', see 'mysql_errno()'
returns the error code for the most recently invoked API
function that can succeed or fail.  A return value of zero means that no
error occurred.  Client error message numbers are listed in the MySQL
'errmsg.h' header file.  Server error message numbers are listed in
'mysqld_error.h'.  Errors also are listed at error-handling.

*Note*:

Some functions such as 'mysql_fetch_row()' do
not set 'mysql_errno()' if they succeed.  A rule of
thumb is that all functions that have to ask the server for information
reset 'mysql_errno()' if they succeed.

MySQL-specific error numbers returned by 'mysql_errno()'
differ from SQLSTATE values returned by
'mysql_sqlstate()'.  For example, the 'mysql'
client program displays errors using the following format, where
'1146' is the 'mysql_errno()' value and ''42S02'' is
the corresponding 'mysql_sqlstate()' value:

     shell> SELECT * FROM no_such_table;
     ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist

*Return Values*

An error code value for the last 'mysql_XXX()' call, if it failed.  zero
means no error occurred.

*Errors*

None.

27.8.7.15 mysql_error()
.......................

'const char *mysql_error(MYSQL *mysql)'

*Description*

For the connection specified by 'mysql', see 'mysql_error()'
returns a null-terminated string containing the error
message for the most recently invoked API function that failed.  If a
function did not fail, the return value of 'mysql_error()'
may be the previous error or an empty string to indicate no
error.

A rule of thumb is that all functions that have to ask the server for
information reset 'mysql_error()' if they succeed.

For functions that reset 'mysql_error()', either of
these two tests can be used to check for an error:

     if(*mysql_error(&mysql))
     {
       // an error occurred
     }

     if(mysql_error(&mysql)[0])
     {
       // an error occurred
     }

The language of the client error messages may be changed by recompiling
the MySQL client library.  You can choose error messages in several
different languages.  See error-message-language.

*Return Values*

A null-terminated character string that describes the error.  An empty
string if no error occurred.

*Errors*

None.

27.8.7.16 mysql_escape_string()
...............................

*Note*:

Do not use this function.  'mysql_escape_string()'
does not have arguments that enable it to respect
the current character set or the quoting context.  Use
'mysql_real_escape_string_quote()'.
instead.

27.8.7.17 mysql_fetch_field()
.............................

'MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)'

*Description*

Returns the definition of one column of a result set as a 'MYSQL_FIELD'
structure.  Call this function repeatedly to retrieve information about
all columns in the result set.  'mysql_fetch_field()'
returns 'NULL' when no more fields are left.

'mysql_fetch_field()' is reset to return
information about the first field each time you execute a new
'SELECT' query.  The field returned by
'mysql_fetch_field()' is also affected by calls to
'mysql_field_seek()'.

If you've called 'mysql_query()' to perform a
'SELECT' on a table but have not called
'mysql_store_result()', MySQL returns the default
blob length (8KB) if you call 'mysql_fetch_field()'
to ask for the length of a 'BLOB' field.
(The 8KB size is chosen because MySQL does not know the maximum length
for the 'BLOB'.  This should be made configurable sometime.)
Once you've retrieved the result set, 'field->max_length' contains the
length of the largest value for this column in the specific query.

*Return Values*

The 'MYSQL_FIELD' structure for the current column.  'NULL' if no
columns are left.

*Errors*

None.

*Example*

     MYSQL_FIELD *field;

     while((field = mysql_fetch_field(result)))
     {
         printf("field name %s\n", field->name);
     }

27.8.7.18 mysql_fetch_field_direct()
....................................

'MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int
fieldnr)'

*Description*

Given a field number 'fieldnr' for a column within a result set, returns
that column's field definition as a 'MYSQL_FIELD' structure.  Use this
function to retrieve the definition for an arbitrary column.  Specify a
value for 'fieldnr' in the range from 0 to
'mysql_num_fields(result)-1'.

*Return Values*

The 'MYSQL_FIELD' structure for the specified column.

*Errors*

None.

*Example*

     unsigned int num_fields;
     unsigned int i;
     MYSQL_FIELD *field;

     num_fields = mysql_num_fields(result);
     for(i = 0; i < num_fields; i++)
     {
         field = mysql_fetch_field_direct(result, i);
         printf("Field %u is %s\n", i, field->name);
     }

27.8.7.19 mysql_fetch_fields()
..............................

'MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)'

*Description*

Returns an array of all 'MYSQL_FIELD' structures for a result set.  Each
structure provides the field definition for one column of the result
set.

*Return Values*

An array of 'MYSQL_FIELD' structures for all columns of a result set.

*Errors*

None.

*Example*

     unsigned int num_fields;
     unsigned int i;
     MYSQL_FIELD *fields;

     num_fields = mysql_num_fields(result);
     fields = mysql_fetch_fields(result);
     for(i = 0; i < num_fields; i++)
     {
        printf("Field %u is %s\n", i, fields[i].name);
     }

27.8.7.20 mysql_fetch_lengths()
...............................

'unsigned long *mysql_fetch_lengths(MYSQL_RES *result)'

*Description*

Returns the lengths of the columns of the current row within a result
set.  If you plan to copy field values, this length information is also
useful for optimization, because you can avoid calling 'strlen()'.  In
addition, if the result set contains binary data, you *must* use this
function to determine the size of the data, because 'strlen()' returns
incorrect results for any field containing null characters.

The length for empty columns and for columns containing 'NULL' values is
zero.  To see how to distinguish these two cases, see the description
for 'mysql_fetch_row()'.

*Return Values*

An array of unsigned long integers representing the size of each column
(not including any terminating null bytes).  'NULL' if an error
occurred.

*Errors*

'mysql_fetch_lengths()' is valid only for
the current row of the result set.  It returns 'NULL' if you call it
before calling 'mysql_fetch_row()' or after
retrieving all rows in the result.

*Example*

     MYSQL_ROW row;
     unsigned long *lengths;
     unsigned int num_fields;
     unsigned int i;

     row = mysql_fetch_row(result);
     if (row)
     {
         num_fields = mysql_num_fields(result);
         lengths = mysql_fetch_lengths(result);
         for(i = 0; i < num_fields; i++)
         {
              printf("Column %u is %lu bytes in length.\n",
                     i, lengths[i]);
         }
     }

27.8.7.21 mysql_fetch_row()
...........................

'MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)'

*Description*

Retrieves the next row of a result set.  When used after
'mysql_store_result()', 'mysql_fetch_row()'
returns 'NULL' when there are no more rows to retrieve.
When used after 'mysql_use_result()',
'mysql_fetch_row()' returns 'NULL' when there are no
more rows to retrieve or if an error occurred.

The number of values in the row is given by
'mysql_num_fields(result)'.  If 'row' holds the return
value from a call to 'mysql_fetch_row()',
pointers to the values are accessed as 'row[0]' to
'row[mysql_num_fields(result)-1]'.  'NULL' values in the row are
indicated by 'NULL' pointers.

The lengths of the field values in the row may be obtained by calling
'mysql_fetch_lengths()'.  Empty fields and
fields containing 'NULL' both have length 0; you can distinguish these
by checking the pointer for the field value.  If the pointer is 'NULL',
the field is 'NULL'; otherwise, the field is empty.

*Return Values*

A 'MYSQL_ROW' structure for the next row.  'NULL' if there are no more
rows to retrieve or if an error occurred.

*Errors*

Errors are not reset between calls to 'mysql_fetch_row()'.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

     MYSQL_ROW row;
     unsigned int num_fields;
     unsigned int i;

     num_fields = mysql_num_fields(result);
     while ((row = mysql_fetch_row(result)))
     {
        unsigned long *lengths;
        lengths = mysql_fetch_lengths(result);
        for(i = 0; i < num_fields; i++)
        {
            printf("[%.*s] ", (int) lengths[i],
                   row[i] ? row[i] : "NULL");
        }
        printf("\n");
     }

27.8.7.22 mysql_field_count()
.............................

'unsigned int mysql_field_count(MYSQL *mysql)'

*Description*

Returns the number of columns for the most recent query on the
connection.

The normal use of this function is when 'mysql_store_result()'
returned 'NULL' (and thus you have no result set
pointer).  In this case, you can call 'mysql_field_count()'
to determine whether 'mysql_store_result()'
should have produced a nonempty result.  This
enables the client program to take proper action without knowing whether
the query was a 'SELECT'. (or 'SELECT'.
-like) statement.  The example shown here illustrates how this
may be done.

See null-mysql-store-result.

*Return Values*

An unsigned integer representing the number of columns in a result set.

*Errors*

None.

*Example*

     MYSQL_RES *result;
     unsigned int num_fields;
     unsigned int num_rows;

     if (mysql_query(&mysql,query_string))
     {
         // error
     }
     else // query succeeded, process any data returned by it
     {
         result = mysql_store_result(&mysql);
         if (result)  // there are rows
         {
             num_fields = mysql_num_fields(result);
             // retrieve rows, then call mysql_free_result(result)
         }
         else  // mysql_store_result() returned nothing; should it have?
         {
             if(mysql_field_count(&mysql) == 0)
             {
                 // query does not return data
                 // (it was not a SELECT)
                 num_rows = mysql_affected_rows(&mysql);
             }
             else // mysql_store_result() should have returned data
             {
                 fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
             }
         }
     }

An alternative is to replace the 'mysql_field_count(&mysql)'
call with 'mysql_errno(&mysql)'.
In this case, you are checking directly for an error from
'mysql_store_result()' rather than inferring from
the value of 'mysql_field_count()' whether the
statement was a 'SELECT'.

27.8.7.23 mysql_field_seek()
............................

'MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result,
MYSQL_FIELD_OFFSET offset)'

*Description*

Sets the field cursor to the given offset.  The next call to
'mysql_fetch_field()' retrieves the field definition
of the column associated with that offset.

To seek to the beginning of a row, pass an 'offset' value of zero.

*Return Values*

The previous value of the field cursor.

*Errors*

None.

27.8.7.24 mysql_field_tell()
............................

'MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)'

*Description*

Returns the position of the field cursor used for the last
'mysql_fetch_field()'.  This value can be used as an
argument to 'mysql_field_seek()'.

*Return Values*

The current offset of the field cursor.

*Errors*

None.

27.8.7.25 mysql_free_result()
.............................

'void mysql_free_result(MYSQL_RES *result)'

*Description*

Frees the memory allocated for a result set by
'mysql_store_result()', 'mysql_use_result()',
see 'mysql_list_dbs()', and so
forth.  When you are done with a result set, you must free the memory it
uses by calling 'mysql_free_result()'.

Do not attempt to access a result set after freeing it.

*Return Values*

None.

*Errors*

None.

27.8.7.26 mysql_get_character_set_info()
........................................

'void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs)'

*Description*

This function provides information about the default client character
set.  The default character set may be changed with the
'mysql_set_character_set()' function.

*Example*

This example shows the fields that are available in the
'MY_CHARSET_INFO' structure:

     if (!mysql_set_character_set(&mysql, "utf8"))
     {
         MY_CHARSET_INFO cs;
         mysql_get_character_set_info(&mysql, &cs);
         printf("character set information:\n");
         printf("character set+collation number: %d\n", cs.number);
         printf("character set name: %s\n", cs.name);
         printf("collation name: %s\n", cs.csname);
         printf("comment: %s\n", cs.comment);
         printf("directory: %s\n", cs.dir);
         printf("multi byte character min. length: %d\n", cs.mbminlen);
         printf("multi byte character max. length: %d\n", cs.mbmaxlen);
     }

27.8.7.27 mysql_get_client_info()
.................................

'const char *mysql_get_client_info(void)'

*Description*

Returns a string that represents the MySQL client library version; for
example, '"5.7.23"'.

The function value is the version of MySQL or Connector/C that provides
the client library.  For more information, see
c-api-server-client-versions.

*Return Values*

A character string that represents the MySQL client library version.

*Errors*

None.

27.8.7.28 mysql_get_client_version()
....................................

'unsigned long mysql_get_client_version(void)'

*Description*

Returns an integer that represents the MySQL client library version.
The value has the format 'XYYZZ' where 'X' is the major version, 'YY' is
the release level (or minor version), and 'ZZ' is the sub-version within
the release level:

     major_version*10000 + release_level*100 + sub_version

For example, '"5.7.23"' is returned as '50723'.

The function value is the version of MySQL or Connector/C that provides
the client library.  For more information, see
c-api-server-client-versions.

*Return Values*

An integer that represents the MySQL client library version.

*Errors*

None.

27.8.7.29 mysql_get_host_info()
...............................

'const char *mysql_get_host_info(MYSQL *mysql)'

*Description*

Returns a string describing the type of connection in use, including the
server host name.

*Return Values*

A character string representing the server host name and the connection
type.

*Errors*

None.

27.8.7.30 mysql_get_option()
............................

'int mysql_get_option(MYSQL *mysql, enum mysql_option option, const void
*arg)'

*Description*

Returns the current value of an option settable using
'mysql_options()'.  The value should be treated as read
only.

The 'option' argument is the option for which you want its value.  The
'arg' argument is a pointer to a variable in which to store the option
value.  'arg' must be a pointer to a variable of the type appropriate
for the 'option' argument.  The following table shows which variable
type to use for each 'option' value.

'arg' Type     Applicable 'option' Values

'unsigned      'MYSQL_OPT_CONNECT_TIMEOUT', 'MYSQL_OPT_PROTOCOL',
int'           'MYSQL_OPT_READ_TIMEOUT', 'MYSQL_OPT_RETRY_COUNT',
               'MYSQL_OPT_SSL_MODE', 'MYSQL_OPT_WRITE_TIMEOUT'

'unsigned      'MYSQL_OPT_MAX_ALLOWED_PACKET',
long'          'MYSQL_OPT_NET_BUFFER_LENGTH'

'my_bool'      'MYSQL_ENABLE_CLEARTEXT_PLUGIN',
               'MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS',
               'MYSQL_OPT_GUESS_CONNECTION', 'MYSQL_OPT_LOCAL_INFILE',
               'MYSQL_OPT_RECONNECT', 'MYSQL_OPT_SSL_ENFORCE',
               'MYSQL_OPT_SSL_VERIFY_SERVER_CERT',
               'MYSQL_OPT_USE_EMBEDDED_CONNECTION',
               'MYSQL_OPT_USE_REMOTE_CONNECTION',
               'MYSQL_REPORT_DATA_TRUNCATION', 'MYSQL_SECURE_AUTH'

'const char    'MYSQL_DEFAULT_AUTH', 'MYSQL_OPT_BIND',
*'             'MYSQL_OPT_SSL_CA', 'MYSQL_OPT_SSL_CAPATH',
               'MYSQL_OPT_SSL_CERT', 'MYSQL_OPT_SSL_CIPHER',
               'MYSQL_OPT_SSL_CRL', 'MYSQL_OPT_SSL_CRLPATH',
               'MYSQL_OPT_SSL_KEY', 'MYSQL_OPT_TLS_VERSION',
               'MYSQL_PLUGIN_DIR', 'MYSQL_READ_DEFAULT_FILE',
               'MYSQL_READ_DEFAULT_GROUP', 'MYSQL_SERVER_PUBLIC_KEY',
               'MYSQL_SET_CHARSET_DIR', 'MYSQL_SET_CHARSET_NAME',
               'MYSQL_SET_CLIENT_IP', 'MYSQL_SHARED_MEMORY_BASE_NAME'

argument not   'MYSQL_OPT_COMPRESS'
used

cannot be      'MYSQL_INIT_COMMAND', 'MYSQL_OPT_CONNECT_ATTR_DELETE',
queried        'MYSQL_OPT_CONNECT_ATTR_RESET', 'MYSQL_OPT_NAMED_PIPE'
(error is
returned)

*Return Values*

Zero for success.  Nonzero if an error occurred; this occurs for
'option' values that cannot be queried.

*Example*

The following call tests the 'MYSQL_OPT_RECONNECT' option.  After the
call returns successfully, the value of 'reconnect' is true or false to
indicate whether automatic reconnection is enabled.

     my_bool reconnect;

     if (mysql_get_option(mysql, MYSQL_OPT_RECONNECT, &reconnect))
       fprintf(stderr, "mysql_get_options() failed\n");

27.8.7.31 mysql_get_proto_info()
................................

'unsigned int mysql_get_proto_info(MYSQL *mysql)'

*Description*

Returns the protocol version used by current connection.

*Return Values*

An unsigned integer representing the protocol version used by the
current connection.

*Errors*

None.

27.8.7.32 mysql_get_server_info()
.................................

'const char *mysql_get_server_info(MYSQL *mysql)'

*Description*

Returns a string that represents the MySQL server version; for example,
'"5.7.23"'.

*Return Values*

A character string that represents the MySQL server version.

*Errors*

None.

27.8.7.33 mysql_get_server_version()
....................................

'unsigned long mysql_get_server_version(MYSQL *mysql)'

*Description*

Returns an integer that represents the MySQL server version.  The value
has the format 'XYYZZ' where 'X' is the major version, 'YY' is the
release level (or minor version), and 'ZZ' is the sub-version within the
release level:

     major_version*10000 + release_level*100 + sub_version

For example, '"5.7.23"' is returned as '50723'.

This function is useful in client programs for determining whether some
version-specific server capability exists.

*Return Values*

An integer that represents the MySQL server version.

*Errors*

None.

27.8.7.34 mysql_get_ssl_cipher()
................................

'const char *mysql_get_ssl_cipher(MYSQL *mysql)'

*Description*

'mysql_get_ssl_cipher()' returns the
encryption cipher used for the given connection to the server.  'mysql'
is the connection handler returned from 'mysql_init()'.

*Return Values*

A string naming the encryption cipher used for the connection, or 'NULL'
if the connection is not encrypted.

27.8.7.35 mysql_hex_string()
............................

'unsigned long mysql_hex_string(char *to, const char *from, unsigned
long length)'

*Description*

This function creates a legal SQL string for use in an SQL statement.
See string-literals.

The string in the 'from' argument is encoded in hexadecimal format, with
each character encoded as two hexadecimal digits.  The result is placed
in the 'to' argument, followed by a terminating null byte.

The string pointed to by 'from' must be 'length' bytes long.  You must
allocate the 'to' buffer to be at least 'length*2+1' bytes long.  When
'mysql_hex_string()' returns, the contents of
'to' is a null-terminated string.  The return value is the length of the
encoded string, not including the terminating null byte.

The return value can be placed into an SQL statement using either
'X'VALUE'' or '0xVALUE' format.  However, the return value does not
include the 'X'...'' or '0x'.  The caller must supply whichever of those
is desired.

*Example*

     char query[1000],*end;

     end = strmov(query,"INSERT INTO test_table values(");
     end = strmov(end,"X'");
     end += mysql_hex_string(end,"What is this",12);
     end = strmov(end,"',X'");
     end += mysql_hex_string(end,"binary data: \0\r\n",16);
     end = strmov(end,"')");

     if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
     {
        fprintf(stderr, "Failed to insert row, Error: %s\n",
                mysql_error(&mysql));
     }

The 'strmov()' function used in the example is included in the
'libmysqlclient' library and works like 'strcpy()' but returns a pointer
to the terminating null of the first parameter.

*Return Values*

The length of the encoded string that is placed into 'to', not including
the terminating null character.

*Errors*

None.

27.8.7.36 mysql_info()
......................

'const char *mysql_info(MYSQL *mysql)'

*Description*

Retrieves a string providing information about the most recently
executed statement, but only for the statements listed here.  For other
statements, see 'mysql_info()' returns 'NULL'.  The
format of the string varies depending on the type of statement, as
described here.  The numbers are illustrative only; the string contains
values appropriate for the statement.

   * 'INSERT INTO ... SELECT ...'.

     String format: 'Records: 100 Duplicates: 0 Warnings: 0'

   * 'INSERT INTO ... VALUES (...),(...),(...)...'

     String format: 'Records: 3 Duplicates: 0 Warnings: 0'

   * 'LOAD DATA INFILE ...'.

     String format: 'Records: 1 Deleted: 0 Skipped: 0 Warnings: 0'

   * 'ALTER TABLE'.

     String format: 'Records: 3 Duplicates: 0 Warnings: 0'

   * 'UPDATE'.

     String format: 'Rows matched: 40 Changed: 40 Warnings: 0'

'mysql_info()' returns a non-'NULL' value for
'INSERT ... VALUES' only for the multiple-row form of the
statement (that is, only if multiple value lists are specified).

*Return Values*

A character string representing additional information about the most
recently executed statement.  'NULL' if no information is available for
the statement.

*Errors*

None.

27.8.7.37 mysql_init()
......................

'MYSQL *mysql_init(MYSQL *mysql)'

*Description*

Allocates or initializes a 'MYSQL' object suitable for
'mysql_real_connect()'.  If 'mysql' is a 'NULL'
pointer, the function allocates, initializes, and returns a new object.
Otherwise, the object is initialized and the address of the object is
returned.  If 'mysql_init()' allocates a new object,
it is freed when 'mysql_close()' is called to close
the connection.

In a nonmulti-threaded environment, see 'mysql_init()'.
invokes 'mysql_library_init()' automatically
as necessary.  However, see 'mysql_library_init()'
is not thread-safe in a multi-threaded environment,
and thus neither is 'mysql_init()'.  Before calling
'mysql_init()', either call
'mysql_library_init()' prior to spawning any
threads, or use a mutex to protect the 'mysql_library_init()'
call.  This should be done prior to any other client
library call.

*Return Values*

An initialized 'MYSQL*' handler.  'NULL' if there was insufficient
memory to allocate a new object.

*Errors*

In case of insufficient memory, 'NULL' is returned.

27.8.7.38 mysql_insert_id()
...........................

'my_ulonglong mysql_insert_id(MYSQL *mysql)'

*Description*

Returns the value generated for an 'AUTO_INCREMENT' column by the
previous 'INSERT' or 'UPDATE' statement.
Use this function after you have performed an 'INSERT'.
statement into a table that contains an 'AUTO_INCREMENT' field, or have
used 'INSERT' or 'UPDATE' to set a column
value with 'LAST_INSERT_ID(EXPR)'.

The return value of 'mysql_insert_id()' is
always zero unless explicitly updated under one of the following
conditions:

   * 'INSERT' statements that store a value into an
     'AUTO_INCREMENT' column.  This is true whether the value is
     automatically generated by storing the special values 'NULL' or '0'
     into the column, or is an explicit nonspecial value.

   * In the case of a multiple-row 'INSERT' statement,
     see 'mysql_insert_id()' returns the first
     automatically generated 'AUTO_INCREMENT' value that was
     successfully inserted.

     If no rows are successfully inserted, see 'mysql_insert_id()'
     returns 0.

   * If an 'INSERT ... SELECT' statement is
     executed, and no automatically generated value is successfully
     inserted, see 'mysql_insert_id()' returns the
     ID of the last inserted row.

   * If an 'INSERT ... SELECT' statement uses
     'LAST_INSERT_ID(EXPR)', see 'mysql_insert_id()'.
     returns EXPR.

   * 'INSERT' statements that generate an
     'AUTO_INCREMENT' value by inserting 'LAST_INSERT_ID(EXPR)' into any
     column or by updating any column to 'LAST_INSERT_ID(EXPR)'.

   * If the previous statement returned an error, the value of
     'mysql_insert_id()' is undefined.

The return value of 'mysql_insert_id()' can be
simplified to the following sequence:

  1. If there is an 'AUTO_INCREMENT' column, and an automatically
     generated value was successfully inserted, return the first such
     value.

  2. If 'LAST_INSERT_ID(EXPR)' occurred in the statement, return EXPR,
     even if there was an 'AUTO_INCREMENT' column in the affected table.

  3. The return value varies depending on the statement used.  When
     called after an 'INSERT' statement:

        * If there is an 'AUTO_INCREMENT' column in the table, and there
          were some explicit values for this column that were
          successfully inserted into the table, return the last of the
          explicit values.

     When called after an 'INSERT ... ON DUPLICATE KEY UPDATE'
     statement:

        * If there is an 'AUTO_INCREMENT' column in the table and there
          were some explicit successfully inserted values or some
          updated values, return the last of the inserted or updated
          values.

'mysql_insert_id()' returns '0' if the previous
statement does not use an 'AUTO_INCREMENT' value.  If you need to save
the value for later, be sure to call 'mysql_insert_id()'
immediately after the statement that generates the
value.

The value of 'mysql_insert_id()' is affected
only by statements issued within the current client connection.  It is
not affected by statements issued by other clients.

The 'LAST_INSERT_ID()' SQL function will contain the value of the first
automatically generated value that was successfully inserted.
'LAST_INSERT_ID()' is not reset between statements because the value of
that function is maintained in the server.  Another difference from
'mysql_insert_id()' is that 'LAST_INSERT_ID()'
is not updated if you set an 'AUTO_INCREMENT' column to a specific
nonspecial value.  See information-functions.

'mysql_insert_id()' returns '0' following a
'CALL' statement for a stored procedure that generates an
'AUTO_INCREMENT' value because in this case 'mysql_insert_id()'
applies to 'CALL' and not the statement
within the procedure.  Within the procedure, you can use
'LAST_INSERT_ID()' at the SQL level to obtain the 'AUTO_INCREMENT'
value.

The reason for the differences between 'LAST_INSERT_ID()' and
'mysql_insert_id()' is that 'LAST_INSERT_ID()' is made
easy to use in scripts while 'mysql_insert_id()'.
tries to provide more exact information about what happens to the
'AUTO_INCREMENT' column.

*Note*:

The OK packet used in the client/server protocol holds information such
as is used for session state tracking.  When clients read the OK packet
to know whether there is a session state change, this resets values such
as the last insert ID and the number of affected rows.  Such changes
cause 'mysql_insert_id()' to return 0 after
execution of commands including but not necessarily limited to
'COM_PING', 'COM_REFRESH', and 'COM_INIT_DB'.

*Return Values*

Described in the preceding discussion.

*Errors*

   * 'ER_AUTO_INCREMENT_CONFLICT'

     A user-specified 'AUTO_INCREMENT' value in a multi 'INSERT'
     statement falls within the range between the current
     'AUTO_INCREMENT' value and the sum of the current and number of
     rows affected values.

27.8.7.39 mysql_kill()
......................

'int mysql_kill(MYSQL *mysql, unsigned long pid)'

*Description*

*Note*:

As of MySQL 5.7.11, 'mysql_kill()' is deprecated and will be removed in
a future version of MySQL. Instead, use 'mysql_query()'
to execute a 'KILL' statement.

Asks the server to kill the thread specified by 'pid'.

This function is deprecated.  Use 'mysql_query()' to
issue an SQL 'KILL' statement instead.

'mysql_kill()' cannot handle values larger than 32
bits, but to guard against killing the wrong thread returns an error in
these cases:

   * If given an ID larger than 32 bits, see 'mysql_kill()'
     returns a 'CR_INVALID_CONN_HANDLE' error.

   * After the server's internal thread ID counter reaches a value
     larger than 32 bits, it returns an 'ER_DATA_OUT_OF_RANGE' error for
     any 'mysql_kill()' invocation and
     'mysql_kill()' fails.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_INVALID_CONN_HANDLE'

     The 'pid' was larger than 32 bits.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

   * 'ER_DATA_OUT_OF_RANGE'

     The server's internal thread ID counter has reached a value larger
     than 32 bits, at which point it rejects all 'mysql_kill()'
     invocations.

27.8.7.40 mysql_library_end()
.............................

'void mysql_library_end(void)'

*Description*

This function finalizes the MySQL library.  Call it when you are done
using the library (for example, after disconnecting from the server).
The action taken by the call depends on whether your application is
linked to the MySQL client library or the MySQL embedded server library.
For a client program linked against the 'libmysqlclient' library by
using the '-lmysqlclient' flag, see 'mysql_library_end()'
performs some memory management to clean up.  For an
embedded server application linked against the 'libmysqld' library by
using the '-lmysqld' flag, see 'mysql_library_end()'
shuts down the embedded server and then cleans up.

*Note*:

To avoid memory leaks after the application is done using the library
(for example, after closing the connection to the server), be sure to
call 'mysql_library_end()' explicitly.  This
enables memory managment to be performed to clean up and free resources
used by the library.

For usage information, see c-api-function-overview, and
mysql-library-init.

27.8.7.41 mysql_library_init()
..............................

'int mysql_library_init(int argc, char **argv, char **groups)'

*Description*

Call this function to initialize the MySQL client library before you
call any other MySQL function, whether your application is a regular
client program or uses the embedded server.  If the application uses the
embedded server, this call starts the server and initializes any
subsystems ('mysys', 'InnoDB', and so forth) that the server uses.

*Note*:

To avoid memory leaks after the application is done using the library
(for example, after closing the connection to the server), be sure to
call 'mysql_library_end()' explicitly.  This
enables memory managment to be performed to clean up and free resources
used by the library.  See mysql-library-end.

The choice of whether the application operates as a regular client or
uses the embedded server depends on whether you use the 'libmysqlclient'
or 'libmysqld' library at link time to produce the final executable.
For additional information, see c-api-function-overview.

In a nonmulti-threaded environment, the call to
'mysql_library_init()' may be omitted, because
'mysql_init()' will invoke it automatically as
necessary.  However, see 'mysql_library_init()'.
is not thread-safe in a multi-threaded environment, and thus neither is
'mysql_init()', which calls
'mysql_library_init()'.  You must either call
'mysql_library_init()' prior to spawning any
threads, or else use a mutex to protect the call, whether you invoke
'mysql_library_init()' or indirectly through
'mysql_init()'.  Do this prior to any other client
library call.

The 'argc' and 'argv' arguments are analogous to the arguments to
'main()', and enable passing of options to the embedded server.  For
convenience, 'argc' may be '0' (zero) if there are no command-line
arguments for the server.  This is the usual case for applications
intended for use only as regular (nonembedded) clients, and the call
typically is written as 'mysql_library_init(0, NULL, NULL)'.

     #include <mysql.h>
     #include <stdlib.h>

     int main(void) {
       if (mysql_library_init(0, NULL, NULL)) {
         fprintf(stderr, "could not initialize MySQL client library\n");
         exit(1);
       }

       /* Use any MySQL API functions here */

       mysql_library_end();

       return EXIT_SUCCESS;
     }

When arguments are to be passed ('argc' is greater than '0'), the first
element of 'argv' is ignored (it typically contains the program name).
'mysql_library_init()' makes a copy of the
arguments so it is safe to destroy 'argv' or 'groups' after the call.

For embedded applications, if you want to connect to an external server
without starting the embedded server, you have to specify a negative
value for 'argc'.

The 'groups' argument is an array of strings that indicate the groups in
option files from which to read options.  See option-files.
Make the final entry in the array 'NULL'.  For convenience, if the
'groups' argument itself is 'NULL', the '[server]' and '[embedded]'
groups are used by default.

     #include <mysql.h>
     #include <stdlib.h>

     static char *server_args[] = {
       "this_program",       /* this string is not used */
       "--datadir=.",
       "--key_buffer_size=32M"
     };
     static char *server_groups[] = {
       "embedded",
       "server",
       "this_program_SERVER",
       (char *)NULL
     };

     int main(void) {
       if (mysql_library_init(sizeof(server_args) / sizeof(char *),
                             server_args, server_groups)) {
         fprintf(stderr, "could not initialize MySQL client library\n");
         exit(1);
       }

       /* Use any MySQL API functions here */

       mysql_library_end();

       return EXIT_SUCCESS;
     }

*Return Values*

Zero for success.  Nonzero if an error occurred.

27.8.7.42 mysql_list_dbs()
..........................

'MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)'

*Description*

Returns a result set consisting of database names on the server that
match the simple regular expression specified by the 'wild' parameter.
'wild' may contain the wildcard characters '%' or '_', or may be a
'NULL' pointer to match all databases.  Calling
'mysql_list_dbs()' is similar to executing the query
'SHOW DATABASES [LIKE WILD]'.

You must free the result set with 'mysql_free_result()'.

*Return Values*

A 'MYSQL_RES' result set for success.  'NULL' if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.43 mysql_list_fields()
.............................

'MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const
char *wild)'

*Description*

*Note*:

As of MySQL 5.7.11, 'mysql_list_fields()' is deprecated and will be
removed in a future version of MySQL. Instead, use
'mysql_query()' to execute a 'SHOW COLUMNS'
statement.

Returns an empty result set for which the metadata provides information
about the columns in the given table that match the simple regular
expression specified by the 'wild' parameter.  'wild' may contain the
wildcard characters '%' or '_', or may be a 'NULL' pointer to match all
fields.  Calling 'mysql_list_fields()' is
similar to executing the query 'SHOW COLUMNS FROM TBL_NAME [LIKE WILD]'.

It is preferable to use 'SHOW COLUMNS FROM TBL_NAME' instead of
'mysql_list_fields()'.

You must free the result set with 'mysql_free_result()'.

*Return Values*

A 'MYSQL_RES' result set for success.  'NULL' if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

     int i;
     MYSQL_RES *tbl_cols = mysql_list_fields(mysql, "mytbl", "f%");

     unsigned int field_cnt = mysql_num_fields(tbl_cols);
     printf("Number of columns: %d\n", field_cnt);

     for (i=0; i < field_cnt; ++i)
     {
       /* col describes i-th column of the table */
       MYSQL_FIELD *col = mysql_fetch_field_direct(tbl_cols, i);
       printf ("Column %d: %s\n", i, col->name);
     }
     mysql_free_result(tbl_cols);

27.8.7.44 mysql_list_processes()
................................

'MYSQL_RES *mysql_list_processes(MYSQL *mysql)'

*Description*

*Note*:

As of MySQL 5.7.11, 'mysql_list_processes()' is deprecated and will be
removed in a future version of MySQL. Instead, use
'mysql_query()' to execute a 'SHOW PROCESSLIST'
statement.

Returns a result set describing the current server threads.  This is the
same kind of information as that reported by 'mysqladmin processlist'
or a 'SHOW PROCESSLIST'
query.

You must free the result set with 'mysql_free_result()'.

*Return Values*

A 'MYSQL_RES' result set for success.  'NULL' if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.45 mysql_list_tables()
.............................

'MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)'

*Description*

Returns a result set consisting of table names in the current database
that match the simple regular expression specified by the 'wild'
parameter.  'wild' may contain the wildcard characters '%' or '_', or
may be a 'NULL' pointer to match all tables.  Calling
'mysql_list_tables()' is similar to executing the
query 'SHOW TABLES [LIKE WILD]'.

You must free the result set with 'mysql_free_result()'.

*Return Values*

A 'MYSQL_RES' result set for success.  'NULL' if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.46 mysql_more_results()
..............................

'my_bool mysql_more_results(MYSQL *mysql)'

*Description*

This function is used when you execute multiple statements specified as
a single statement string, or when you execute 'CALL'.
statements, which can return multiple result sets.

'mysql_more_results()' true if more results
exist from the currently executed statement, in which case the
application must call 'mysql_next_result()' to
fetch the results.

*Return Values*

'TRUE' (1) if more results exist.  'FALSE' (0) if no more results exist.

In most cases, you can call 'mysql_next_result()'
instead to test whether more results exist and
initiate retrieval if so.

See c-api-multiple-queries, and mysql-next-result.

*Errors*

None.

27.8.7.47 mysql_next_result()
.............................

'int mysql_next_result(MYSQL *mysql)'

*Description*

This function is used when you execute multiple statements specified as
a single statement string, or when you use 'CALL'.
statements to execute stored procedures, which can return multiple
result sets.

'mysql_next_result()' reads the next statement
result and returns a status to indicate whether more results exist.  If
'mysql_next_result()' returns an error, there
are no more results.

Before each call to 'mysql_next_result()', you
must call 'mysql_free_result()' for the
current statement if it is a statement that returned a result set
(rather than just a result status).

After calling 'mysql_next_result()' the state
of the connection is as if you had called 'mysql_real_query()'
or 'mysql_query()' for the next
statement.  This means that you can call 'mysql_store_result()',
see 'mysql_warning_count()',
'mysql_affected_rows()', and so forth.

If your program uses 'CALL' statements to execute stored
procedures, the 'CLIENT_MULTI_RESULTS' flag must be enabled.  This is
because each 'CALL' returns a result to indicate the call
status, in addition to any result sets that might be returned by
statements executed within the procedure.  Because 'CALL'.
can return multiple results, process them using a loop that calls
'mysql_next_result()' to determine whether there are
more results.

'CLIENT_MULTI_RESULTS' can be enabled when you call
'mysql_real_connect()', either explicitly by passing
the 'CLIENT_MULTI_RESULTS' flag itself, or implicitly by passing
'CLIENT_MULTI_STATEMENTS' (which also enables 'CLIENT_MULTI_RESULTS').
In MySQL 5.7, 'CLIENT_MULTI_RESULTS' is enabled by default.

It is also possible to test whether there are more results by calling
'mysql_more_results()'.  However, this
function does not change the connection state, so if it returns true,
you must still call 'mysql_next_result()' to
advance to the next result.

For an example that shows how to use 'mysql_next_result()',
see c-api-multiple-queries.

*Return Values*

Return Value              Description

0                         Successful and there are more results

-1                        Successful and there are no more results

>0                        An error occurred

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.  For example, if you
     did not call 'mysql_use_result()' for a
     previous result set.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.48 mysql_num_fields()
............................

'unsigned int mysql_num_fields(MYSQL_RES *result)'

To pass a 'MYSQL*' argument instead, use 'unsigned int
mysql_field_count(MYSQL *mysql)'.

*Description*

Returns the number of columns in a result set.

You can get the number of columns either from a pointer to a result set
or to a connection handler.  You would use the connection handler if
'mysql_store_result()' or
'mysql_use_result()' returned 'NULL' (and thus you
have no result set pointer).  In this case, you can call
'mysql_field_count()' to determine whether
'mysql_store_result()' should have produced a
nonempty result.  This enables the client program to take proper action
without knowing whether the query was a 'SELECT'. (or
'SELECT'.-like) statement.  The example shown here
illustrates how this may be done.

See null-mysql-store-result.

*Return Values*

An unsigned integer representing the number of columns in a result set.

*Errors*

None.

*Example*

     MYSQL_RES *result;
     unsigned int num_fields;
     unsigned int num_rows;

     if (mysql_query(&mysql,query_string))
     {
         // error
     }
     else // query succeeded, process any data returned by it
     {
         result = mysql_store_result(&mysql);
         if (result)  // there are rows
         {
             num_fields = mysql_num_fields(result);
             // retrieve rows, then call mysql_free_result(result)
         }
         else  // mysql_store_result() returned nothing; should it have?
         {
             if (mysql_errno(&mysql))
             {
                fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
             }
             else if (mysql_field_count(&mysql) == 0)
             {
                 // query does not return data
                 // (it was not a SELECT)
                 num_rows = mysql_affected_rows(&mysql);
             }
         }
     }

An alternative (if you know that your query should have returned a
result set) is to replace the 'mysql_errno(&mysql)'.
call with a check whether 'mysql_field_count(&mysql)'
returns 0.  This happens only if something went
wrong.

27.8.7.49 mysql_num_rows()
..........................

'my_ulonglong mysql_num_rows(MYSQL_RES *result)'

*Description*

Returns the number of rows in the result set.

The use of 'mysql_num_rows()' depends on whether
you use 'mysql_store_result()' or
'mysql_use_result()' to return the result set.  If
you use 'mysql_store_result()',
'mysql_num_rows()' may be called immediately.  If you
use 'mysql_use_result()',
'mysql_num_rows()' does not return the correct value
until all the rows in the result set have been retrieved.

'mysql_num_rows()' is intended for use with
statements that return a result set, such as 'SELECT'.
For statements such as 'INSERT', 'UPDATE',
or 'DELETE', the number of affected rows can be obtained
with 'mysql_affected_rows()'.

*Return Values*

The number of rows in the result set.

*Errors*

None.

27.8.7.50 mysql_options()
.........................

'int mysql_options(MYSQL *mysql, enum mysql_option option, const void
*arg)'

*Description*

Can be used to set extra connect options and affect behavior for a
connection.  This function may be called multiple times to set several
options.  To retrieve option values, use 'mysql_get_option()'.

Call 'mysql_options()' after 'mysql_init()'
and before 'mysql_connect()' or
'mysql_real_connect()'.

The 'option' argument is the option that you want to set; the 'arg'
argument is the value for the option.  If the option is an integer,
specify a pointer to the value of the integer as the 'arg' argument.

Options for information such as SSL certificate and key files are used
to establish an encrypted connection if such connections are available,
but do not enforce any requirement that the connection obtained be
encrypted.  To require an encrypted connection, use the technique
described in c-api-encrypted-connections.

The following list describes the possible options, their effect, and how
'arg' is used for each option.  For option descriptions that indicate
'arg' is unused, its value is irrelevant; it is conventional to pass 0.
Several of the options apply only when the application is linked against
the 'libmysqld' embedded server library and are unused for applications
linked against the 'libmysqlclient' client library.

   * 'MYSQL_DEFAULT_AUTH' (argument type: 'char *')

     The name of the authentication plugin to use.

   * 'MYSQL_ENABLE_CLEARTEXT_PLUGIN' (argument type: 'my_bool *')

     Enable the 'mysql_clear_password' cleartext authentication plugin.
     See cleartext-pluggable-authentication.

   * 'MYSQL_INIT_COMMAND' (argument type: 'char *')

     SQL statement to execute when connecting to the MySQL server.
     Automatically re-executed if reconnection occurs.

   * 'MYSQL_OPT_BIND' (argument: 'char *')

     The network interface from which to connect to the server.  This is
     used when the client host has multiple network interfaces.  The
     argument is a host name or IP address (specified as a string).

   * 'MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS' (argument type: 'my_bool
     *')

     Indicate whether the client can handle expired passwords.  See
     expired-password-handling.

   * 'MYSQL_OPT_COMPRESS' (argument: not used)

     Use the compressed client/server protocol.

   * 'MYSQL_OPT_CONNECT_ATTR_DELETE' (argument type: 'char *')

     Given a key name, this option deletes a key/value pair from the
     current set of connection attributes to pass to the server at
     connect time.  The argument is a pointer to a null-terminated
     string naming the key.  Comparison of the key name with existing
     keys is case-sensitive.

     See also the description for the 'MYSQL_OPT_CONNECT_ATTR_RESET'
     option, as well as the description for the
     'MYSQL_OPT_CONNECT_ATTR_ADD' option in the description of the
     'mysql_options4()' function.  That function
     description also includes a usage example.

     The Performance Schema exposes connection attributes through the
     'session_connect_attrs' and
     'session_account_connect_attrs'
     tables.  See
     performance-schema-connection-attribute-tables.

   * 'MYSQL_OPT_CONNECT_ATTR_RESET' (argument not used)

     This option resets (clears) the current set of connection
     attributes to pass to the server at connect time.

     See also the description for the 'MYSQL_OPT_CONNECT_ATTR_DELETE'
     option, as well as the description for the
     'MYSQL_OPT_CONNECT_ATTR_ADD' option in the description of the
     'mysql_options4()' function.  That function
     description also includes a usage example.

     The Performance Schema exposes connection attributes through the
     'session_connect_attrs' and
     'session_account_connect_attrs'
     tables.  See
     performance-schema-connection-attribute-tables.

   * 'MYSQL_OPT_CONNECT_TIMEOUT' (argument type: 'unsigned int *')

     The connect timeout in seconds.

   * 'MYSQL_OPT_GUESS_CONNECTION' (argument: not used)

     For an application linked against the 'libmysqld' embedded server
     library, this option enables the library to guess whether to use
     the embedded server or a remote server.  'Guess' means that if the
     host name is set and is not 'localhost', it uses a remote server.
     This behavior is the default.  'MYSQL_OPT_USE_EMBEDDED_CONNECTION'
     and 'MYSQL_OPT_USE_REMOTE_CONNECTION' can be used to override it.
     This option is ignored for applications linked against the
     'libmysqlclient' client library.

   * 'MYSQL_OPT_LOCAL_INFILE' (argument type: optional pointer to
     'unsigned int')

     This option affects client-side 'LOCAL' capability for 'LOAD DATA'
     operations.  By default, 'LOCAL' capability is
     determined by the default compiled into the MySQL client library
     (see load-data).  To control this capability explicitly,
     invoke 'mysql_options()' to set the
     'MYSQL_OPT_LOCAL_INFILE' option:

        * 'LOCAL' is disabled if the pointer points to an 'unsigned int'
          that has a zero value.

        * 'LOCAL' is enabled if no pointer is given or if the pointer
          points to an 'unsigned int' that has a nonzero value.

     Successful use of a 'LOCAL' load operation by a client also
     requires that the server permits it.

   * 'MYSQL_OPT_MAX_ALLOWED_PACKET' (argument: 'unsigned long *')

     This option sets the 'max_allowed_packet' system variable.  If the
     'mysql' argument is non-'NULL', the call sets the session system
     variable value for that session.  If 'mysql' is 'NULL', the call
     sets the global system variable value.

   * 'MYSQL_OPT_NAMED_PIPE' (argument: not used)

     Use a named pipe to connect to the MySQL server on Windows, if the
     server permits named-pipe connections.

   * 'MYSQL_OPT_NET_BUFFER_LENGTH' (argument: 'unsigned long *')

     This option sets the 'net_buffer_length' system variable.  If the
     'mysql' argument is non-'NULL', the call sets the session system
     variable value for that session.  If 'mysql' is 'NULL', the call
     sets the global system variable value.

   * 'MYSQL_OPT_PROTOCOL' (argument type: 'unsigned int *')

     Type of protocol to use.  Specify one of the enum values of
     'mysql_protocol_type' defined in 'mysql.h'.

   * 'MYSQL_OPT_READ_TIMEOUT' (argument type: 'unsigned int *')

     The timeout in seconds for each attempt to read from the server.
     There are retries if necessary, so the total effective timeout
     value is three times the option value.  You can set the value so
     that a lost connection can be detected earlier than the TCP/IP
     'Close_Wait_Timeout' value of 10 minutes.

   * 'MYSQL_OPT_RECONNECT' (argument type: 'my_bool *')

     Enable or disable automatic reconnection to the server if the
     connection is found to have been lost.  Reconnect is off by
     default; this option provides a way to set reconnection behavior
     explicitly.  See c-api-auto-reconnect.

   * 'MYSQL_OPT_RETRY_COUNT' (argument type: 'unsigned int *')

     The retry count for I/O-related system calls that are interrupted
     while connecting to the server or communicating with it.  The
     default value is 1 (1 retry if the initial call is interrupted for
     2 tries total).

     This option can be used only by clients that link against a C
     client library compiiled with NDB Cluster support.  It is available
     as of MySQL NDB Cluster 7.5.1.

   * 'MYSQL_OPT_SSL_CA' (argument type: 'char *')

     The path name of the Certificate Authority (CA) certificate file.
     This option, if used, must specify the same certificate used by the
     server.

   * 'MYSQL_OPT_SSL_CAPATH' (argument type: 'char *')

     The path name of the directory that contains trusted SSL CA
     certificate files.

   * 'MYSQL_OPT_SSL_CERT' (argument type: 'char *')

     The path name of the client public key certificate file.

   * 'MYSQL_OPT_SSL_CIPHER' (argument type: 'char *')

     The list of permitted ciphers for SSL encryption.

   * 'MYSQL_OPT_SSL_CRL' (argument type: 'char *')

     The path name of the file containing certificate revocation lists.

   * 'MYSQL_OPT_SSL_CRLPATH' (argument type: 'char *')

     The path name of the directory that contains files containing
     certificate revocation lists.

   * 'MYSQL_OPT_SSL_ENFORCE' (argument type: 'my_bool *')

     Whether to require the connection to use SSL. If enabled and an
     encrypted connection cannot be established, the connection attempt
     fails.

     This option is deprecated as of MySQL 5.7.11 and is removed in
     MySQL 8.0.  Instead, use 'MYSQL_OPT_SSL_MODE' with a value of
     'SSL_MODE_REQUIRED'.

   * 'MYSQL_OPT_SSL_KEY' (argument type: 'char *')

     The path name of the client private key file.

   * 'MYSQL_OPT_SSL_MODE' (argument type: 'unsigned int *')

     The security state to use for the connection to the server:
     'SSL_MODE_DISABLED', 'SSL_MODE_PREFERRED', 'SSL_MODE_REQUIRED',
     'SSL_MODE_VERIFY_CA', 'SSL_MODE_VERIFY_IDENTITY'.  The default is
     'SSL_MODE_PREFERRED'.  These modes are the permitted values of the
     'mysql_ssl_mode' enumeration defined in 'mysql.h'.  For more
     information about the security states, see the description of
     '--ssl-mode' in encrypted-connection-options.

     This option was added in MySQL 5.7.11.

   * 'MYSQL_OPT_SSL_VERIFY_SERVER_CERT' (argument type: 'my_bool *')

     Enable or disable verification of the server's Common Name identity
     in its certificate against the host name used when connecting to
     the server.  The connection is rejected if there is a mismatch.
     For encrypted connections, this feature can be used to prevent
     man-in-the-middle attacks.  Identity verification is disabled by
     default.

     This option does not work with self-signed certificates, which do
     not contain the server name as the Common Name value.

     This option is deprecated as of MySQL 5.7.11 and is removed in
     MySQL 8.0.  Instead, use 'MYSQL_OPT_SSL_MODE' with a value of
     'SSL_MODE_VERIFY_IDENTITY'.

   * 'MYSQL_OPT_TLS_VERSION' (argument type: 'char *')

     The protocols permitted by the client for encrypted connections.
     The value is a comma-separated list containing one or more protocol
     names.  The protocols that can be named for this option depend on
     the SSL library used to compile MySQL. For details, see
     encrypted-connection-protocols-ciphers.

     This option was added in MySQL 5.7.10.

   * 'MYSQL_OPT_USE_EMBEDDED_CONNECTION' (argument: not used)

     For an application linked against the 'libmysqld' embedded server
     library, this option forces the use of the embedded server for the
     connection.  It is ignored for applications linked against the
     'libmysqlclient' client library.

   * 'MYSQL_OPT_USE_REMOTE_CONNECTION' (argument: not used)

     For an application linked against the 'libmysqld' embedded server
     library, this option forces the use of a remote server for the
     connection.  It is ignored for applications linked against the
     'libmysqlclient' client library.

   * 'MYSQL_OPT_USE_RESULT' (argument: not used)

     This option is unused.

   * 'MYSQL_OPT_WRITE_TIMEOUT' (argument type: 'unsigned int *')

     The timeout in seconds for each attempt to write to the server.
     There is a retry if necessary, so the total effective timeout value
     is two times the option value.

   * 'MYSQL_PLUGIN_DIR' (argument type: 'char *')

     The directory in which to look for client plugins.

   * 'MYSQL_READ_DEFAULT_FILE' (argument type: 'char *')

     Read options from the named option file instead of from 'my.cnf'.

   * 'MYSQL_READ_DEFAULT_GROUP' (argument type: 'char *')

     Read options from the named group from 'my.cnf' or the file
     specified with 'MYSQL_READ_DEFAULT_FILE'.

   * 'MYSQL_REPORT_DATA_TRUNCATION' (argument type: 'my_bool *')

     Enable or disable reporting of data truncation errors for prepared
     statements using the 'error' member of 'MYSQL_BIND' structures.
     (Default: enabled.)

   * 'MYSQL_SECURE_AUTH' (argument type: 'my_bool *')

     Whether to connect to a server that does not support the password
     hashing used in MySQL 4.1.1 and later.  This option is enabled by
     default.

   * 'MYSQL_SERVER_PUBLIC_KEY' (argument type: 'char *')

     The path name to a file containing a client-side copy of the public
     key required by the server for RSA key pair-based password
     exchange.  The file must be in PEM format.  This option applies to
     clients that authenticate with the 'sha256_password' authentication
     plugin.  This option is ignored for accounts that do not
     authenticate with one of those plugins.  It is also ignored if
     RSA-based password exchange is not used, as is the case when the
     client connects to the server using a secure connection.

     For information about the 'sha256_password' plugin, see
     sha256-pluggable-authentication.

   * 'MYSQL_SET_CHARSET_DIR' (argument type: 'char *')

     The path name of the directory that contains character set
     definition files.

   * 'MYSQL_SET_CHARSET_NAME' (argument type: 'char *')

     The name of the character set to use as the default character set.
     The argument can be 'MYSQL_AUTODETECT_CHARSET_NAME' to cause the
     character set to be autodetected based on the operating system
     setting (see charset-connection).

   * 'MYSQL_SET_CLIENT_IP' (argument type: 'char *')

     For an application linked against the 'libmysqld' embedded server
     library (when 'libmysqld' is compiled with authentication support),
     this option means that the user is considered to have connected
     from the specified IP address (specified as a string) for
     authentication purposes.  It is ignored for applications linked
     against the 'libmysqlclient' client library.

   * 'MYSQL_SHARED_MEMORY_BASE_NAME' (argument type: 'char *')

     The name of the shared-memory object for communication to the
     server on Windows, if the server supports shared-memory
     connections.  Specify the same value as the
     '--shared-memory-base-name' option used for the 'mysqld'
     server you want to connect to.

The 'client' group is always read if you use 'MYSQL_READ_DEFAULT_FILE'
or 'MYSQL_READ_DEFAULT_GROUP'.

The specified group in the option file may contain the following
options.

Option                    Description

'character-sets-dir=DIR_NAME'The directory where character sets are
                          installed.

'compress'                Use the compressed client/server protocol.

'connect-timeout=SECONDS' The connect timeout in seconds.  On Linux
                          this timeout is also used for waiting for the
                          first answer from the server.

'database=DB_NAME'        Connect to this database if no database was
                          specified in the connect command.

'debug'                   Debug options.

'default-character-set=CHARSET_NAME'The default character set to use.

'disable-local-infile'    Disable use of 'LOAD DATA LOCAL INFILE'.

'enable-cleartext-plugin' Enable the 'mysql_clear_password' cleartext
                          authentication plugin.

'host=HOST_NAME'          Default host name.

'init-command=STMT'       Statement to execute when connecting to MySQL
                          server.  Automatically re-executed if
                          reconnection occurs.

'interactive-timeout=SECONDS'Same as specifying 'CLIENT_INTERACTIVE' to
                          See 'mysql_real_connect()'.
                          See
                          mysql-real-connect.

'local-infile[={0|1}]'    If no argument or nonzero argument, enable
                          use of 'LOAD DATA LOCAL'.;
                          otherwise disable.

'max_allowed_packet=BYTES'Maximum size of packet that client can read
                          from server.

'multi-queries',          Enable multiple result sets from
'multi-results'           multiple-statement executions or stored
                          procedures.

'multi-statements'        Enable the client to send multiple statements
                          in a single string (separated by ';'
                          characters).

'password=PASSWORD'       Default password.

'pipe'                    Use named pipes to connect to a MySQL server
                          on Windows.

'port=PORT_NUM'           Default port number.

'protocol={TCP|SOCKET|PIPE|MEMORY}'The protocol to use when connecting to the
                          server.

'return-found-rows'       Tell 'mysql_info()' to
                          return found rows instead of updated rows
                          when using 'UPDATE'.

'shared-memory-base-name=NAME'Shared-memory name to use to connect to
                          server.

'socket={FILE_NAME|PIPE_NAME}'Default socket file.

'ssl-ca=FILE_NAME'        Certificate Authority file.

'ssl-capath=DIR_NAME'     Certificate Authority directory.

'ssl-cert=FILE_NAME'      Certificate file.

'ssl-cipher=CIPHER_LIST'  Permissible SSL ciphers.

'ssl-key=FILE_NAME'       Key file.

'timeout=SECONDS'         Like 'connect-timeout'.

'user'                    Default user.

'timeout' has been replaced by 'connect-timeout', but 'timeout' is still
supported for backward compatibility.

For more information about option files used by MySQL programs, see
option-files.

*Return Values*

Zero for success.  Nonzero if you specify an unknown option.

*Example*

The following 'mysql_options()' calls request the
use of compression in the client/server protocol, cause options to be
read from the '[odbc]' group in option files, and disable transaction
autocommit mode:

     MYSQL mysql;

     mysql_init(&mysql);
     mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
     mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
     mysql_options(&mysql,MYSQL_INIT_COMMAND,"SET autocommit=0");
     if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
     {
         fprintf(stderr, "Failed to connect to database: Error: %s\n",
               mysql_error(&mysql));
     }

27.8.7.51 mysql_options4()
..........................

'int mysql_options4(MYSQL *mysql, enum mysql_option option, const void
*arg1, const void *arg2)'

*Description*

'mysql_options4()' is similar to
'mysql_options()' but has an extra fourth argument so
that two values can be passed for the option specified in the second
argument.

The following list describes the permitted options, their effect, and
how 'arg1' and 'arg2' are used.

   * 'MYSQL_OPT_CONNECT_ATTR_ADD' (argument types: 'char *, char *')

     This option adds an attribute key/value pair to the current set of
     connection attributes to pass to the server at connect time.  Both
     arguments are pointers to null-terminated strings.  The first and
     second strings indicate the key and value, respectively.  If the
     key is empty or already exists in the current set of connection
     attributes, an error occurs.  Comparison of the key name with
     existing keys is case-sensitive.

     Key names that begin with an underscore ('_') are reserved for
     internal use and should not be created by application programs.
     This convention permits new attributes to be introduced by MySQL
     without colliding with application attributes.

     'mysql_options4()' imposes a limit of 64KB
     on the aggregate size of connection attribute data it will accept.
     For calls that cause this limit to be exceeded, a
     'CR_INVALID_PARAMETER_NO' error occurs.  Attribute size-limit
     checks also occur on the server side.  For details, see
     performance-schema-connection-attribute-tables, which also
     describes how the Performance Schema exposes connection attributes
     through the 'session_connect_attrs'
     and
     'session_account_connect_attrs'
     tables.

     See also the descriptions for the 'MYSQL_OPT_CONNECT_ATTR_RESET'
     'MYSQL_OPT_CONNECT_ATTR_DELETE' options in the description of the
     'mysql_options()' function.

*Return Values*

Zero for success.  Nonzero if you specify an unknown option.

*Errors*

   * 'CR_DUPLICATE_CONNECTION_ATTR'

     A duplicate attribute name was specified.

   * 'CR_INVALID_PARAMETER_NO'

     A key name was empty or the amount of key/value connection
     attribute data exceeds 64KB limit.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

*Example*

This example demonstrates the calls that specify connection attributes:

     MYSQL mysql;

     mysql_init(&mysql);
     mysql_options(&mysql,MYSQL_OPT_CONNECT_ATTR_RESET, 0);
     mysql_options4(&mysql,MYSQL_OPT_CONNECT_ATTR_ADD, "key1", "value1");
     mysql_options4(&mysql,MYSQL_OPT_CONNECT_ATTR_ADD, "key2", "value2");
     mysql_options4(&mysql,MYSQL_OPT_CONNECT_ATTR_ADD, "key3", "value3");
     mysql_options(&mysql,MYSQL_OPT_CONNECT_ATTR_DELETE, "key1");
     if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
     {
         fprintf(stderr, "Failed to connect to database: Error: %s\n",
             mysql_error(&mysql));
     }

27.8.7.52 mysql_ping()
......................

'int mysql_ping(MYSQL *mysql)'

*Description*

Checks whether the connection to the server is working.  If the
connection has gone down and auto-reconnect is enabled an attempt to
reconnect is made.  If the connection is down and auto-reconnect is
disabled, see 'mysql_ping()' returns an error.

Auto-reconnect is disabled by default.  To enable it, call
'mysql_options()' with the 'MYSQL_OPT_RECONNECT' option.
For details, see mysql-options.

'mysql_ping()' can be used by clients that remain
idle for a long while, to check whether the server has closed the
connection and reconnect if necessary.

If 'mysql_ping()') does cause a reconnect, there is
no explicit indication of it.  To determine whether a reconnect occurs,
call 'mysql_thread_id()' to get the original
connection identifier before calling 'mysql_ping()',
then call 'mysql_thread_id()' again to see
whether the identifier has changed.

If reconnect occurs, some characteristics of the connection will have
been reset.  For details about these characteristics, see
c-api-auto-reconnect.

*Return Values*

Zero if the connection to the server is active.  Nonzero if an error
occurred.  A nonzero return does not indicate whether the MySQL server
itself is down; the connection might be broken for other reasons such as
network problems.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.53 mysql_query()
.......................

'int mysql_query(MYSQL *mysql, const char *stmt_str)'

*Description*

Executes the SQL statement pointed to by the null-terminated string
'stmt_str'.  Normally, the string must consist of a single SQL statement
without a terminating semicolon (';') or '\g'.  If multiple-statement
execution has been enabled, the string can contain several statements
separated by semicolons.  See c-api-multiple-queries.

'mysql_query()' cannot be used for statements that
contain binary data; you must use 'mysql_real_query()'
instead.  (Binary data may contain the '\0' character,
which 'mysql_query()' interprets as the end of the
statement string.)

If you want to know whether the statement returns a result set, you can
use 'mysql_field_count()' to check for this.
See mysql-field-count.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.54 mysql_real_connect()
..............................

'MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char
*user, const char *passwd, const char *db, unsigned int port, const char
*unix_socket, unsigned long client_flag)'

*Description*

'mysql_real_connect()' attempts to establish
a connection to a MySQL database engine running on 'host'.
'mysql_real_connect()' must complete successfully
before you can execute any other API functions that require a valid
'MYSQL' connection handler structure.

The parameters are specified as follows:

   * For the first parameter, specify the address of an existing 'MYSQL'
     structure.  Before calling 'mysql_real_connect()',
     call 'mysql_init()' to
     initialize the 'MYSQL' structure.  You can change a lot of connect
     options with the 'mysql_options()' call.  See
     mysql-options.

   * The value of 'host' may be either a host name or an IP address.  If
     'host' is 'NULL' or the string '"localhost"', a connection to the
     local host is assumed.  For Windows, the client connects using a
     shared-memory connection, if the server has shared-memory
     connections enabled.  Otherwise, TCP/IP is used.  For Unix, the
     client connects using a Unix socket file.  For local connections,
     you can also influence the type of connection to use with the
     'MYSQL_OPT_PROTOCOL' or 'MYSQL_OPT_NAMED_PIPE' options to
     'mysql_options()'.  The type of connection must be
     supported by the server.  For a 'host' value of '"."' on Windows,
     the client connects using a named pipe, if the server has
     named-pipe connections enabled.  If named-pipe connections are not
     enabled, an error occurs.

   * The 'user' parameter contains the user's MySQL login ID. If 'user'
     is 'NULL' or the empty string '""', the current user is assumed.
     Under Unix, this is the current login name.  Under Windows ODBC,
     the current user name must be specified explicitly.  See the
     Connector/ODBC section of connectors-apis.

   * The 'passwd' parameter contains the password for 'user'.  If
     'passwd' is 'NULL', only entries in the 'user' table for the user
     that have a blank (empty) password field are checked for a match.
     This enables the database administrator to set up the MySQL
     privilege system in such a way that users get different privileges
     depending on whether they have specified a password.

     *Note*:

     Do not attempt to encrypt the password before calling
     'mysql_real_connect()'.; password encryption is
     handled automatically by the client API.

   * The 'user' and 'passwd' parameters use whatever character set has
     been configured for the 'MYSQL' object.  By default, this is
     'latin1', but can be changed by calling 'mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "CHARSET_NAME")'
     prior to
     connecting.

   * 'db' is the database name.  If 'db' is not 'NULL', the connection
     sets the default database to this value.

   * If 'port' is not 0, the value is used as the port number for the
     TCP/IP connection.  Note that the 'host' parameter determines the
     type of the connection.

   * If 'unix_socket' is not 'NULL', the string specifies the socket or
     named pipe to use.  Note that the 'host' parameter determines the
     type of the connection.

   * The value of 'client_flag' is usually 0, but can be set to a
     combination of the following flags to enable certain features:

        * 'CAN_HANDLE_EXPIRED_PASSWORDS': The client can handle expired
          passwords.  For more information, see
          expired-password-handling.

        * 'CLIENT_COMPRESS': Use compression in the client/server
          protocol.

        * 'CLIENT_FOUND_ROWS': Return the number of found (matched)
          rows, not the number of changed rows.

        * 'CLIENT_IGNORE_SIGPIPE': Prevents the client library from
          installing a 'SIGPIPE' signal handler.  This can be used to
          avoid conflicts with a handler that the application has
          already installed.

        * 'CLIENT_IGNORE_SPACE': Permit spaces after function names.
          Makes all functions names reserved words.

        * 'CLIENT_INTERACTIVE': Permit 'interactive_timeout' seconds of
          inactivity (rather than 'wait_timeout' seconds) before closing
          the connection.  The client's session 'wait_timeout' variable
          is set to the value of the session 'interactive_timeout'
          variable.

        * 'CLIENT_LOCAL_FILES': Enable 'LOAD DATA LOCAL'
          handling.

        * 'CLIENT_MULTI_RESULTS': Tell the server that the client can
          handle multiple result sets from multiple-statement executions
          or stored procedures.  This flag is automatically enabled if
          'CLIENT_MULTI_STATEMENTS' is enabled.  See the note following
          this table for more information about this flag.

        * 'CLIENT_MULTI_STATEMENTS': Tell the server that the client may
          send multiple statements in a single string (separated by ';'
          characters).  If this flag is not set, multiple-statement
          execution is disabled.  See the note following this table for
          more information about this flag.

        * 'CLIENT_NO_SCHEMA' Do not permit DB_NAME.TBL_NAME.COL_NAME
          syntax.  This is for ODBC. It causes the parser to generate an
          error if you use that syntax, which is useful for trapping
          bugs in some ODBC programs.

        * 'CLIENT_ODBC': Unused.

        * 'CLIENT_SSL': Use SSL (encrypted protocol).  Do not set this
          option within an application program; it is set internally in
          the client library.  Instead, use 'mysql_options()'
          or 'mysql_ssl_set()'.
          before calling 'mysql_real_connect()'.

        * 'CLIENT_REMEMBER_OPTIONS' Remember options specified by calls
          to 'mysql_options()'.  Without this
          option, if 'mysql_real_connect()'.
          fails, you must repeat the 'mysql_options()'
          calls before trying to connect again.  With
          this option, the 'mysql_options()' calls
          need not be repeated.

If your program uses 'CALL' statements to execute stored
procedures, the 'CLIENT_MULTI_RESULTS' flag must be enabled.  This is
because each 'CALL' returns a result to indicate the call
status, in addition to any result sets that might be returned by
statements executed within the procedure.  Because 'CALL'.
can return multiple results, process them using a loop that calls
'mysql_next_result()' to determine whether there are
more results.

'CLIENT_MULTI_RESULTS' can be enabled when you call
'mysql_real_connect()', either explicitly by passing
the 'CLIENT_MULTI_RESULTS' flag itself, or implicitly by passing
'CLIENT_MULTI_STATEMENTS' (which also enables 'CLIENT_MULTI_RESULTS').
In MySQL 5.7, 'CLIENT_MULTI_RESULTS' is enabled by default.

If you enable 'CLIENT_MULTI_STATEMENTS' or 'CLIENT_MULTI_RESULTS',
process the result for every call to 'mysql_query()'.
or 'mysql_real_query()' by using a loop that
calls 'mysql_next_result()' to determine
whether there are more results.  For an example, see
c-api-multiple-queries.

For some parameters, it is possible to have the value taken from an
option file rather than from an explicit value in the
'mysql_real_connect()' call.  To do this, call
'mysql_options()' with the
'MYSQL_READ_DEFAULT_FILE' or 'MYSQL_READ_DEFAULT_GROUP' option before
calling 'mysql_real_connect()'.  Then, in the
'mysql_real_connect()' call, specify the
'no-value' value for each parameter to be read from an option file:

   * For 'host', specify a value of 'NULL' or the empty string ('""').

   * For 'user', specify a value of 'NULL' or the empty string.

   * For 'passwd', specify a value of 'NULL'.  (For the password, a
     value of the empty string in the 'mysql_real_connect()'
     call cannot be overridden in an option file,
     because the empty string indicates explicitly that the MySQL
     account must have an empty password.)

   * For 'db', specify a value of 'NULL' or the empty string.

   * For 'port', specify a value of 0.

   * For 'unix_socket', specify a value of 'NULL'.

If no value is found in an option file for a parameter, its default
value is used as indicated in the descriptions given earlier in this
section.

*Return Values*

A 'MYSQL*' connection handler if the connection was successful, 'NULL'
if the connection was unsuccessful.  For a successful connection, the
return value is the same as the value of the first parameter.

*Errors*

   * 'CR_CONN_HOST_ERROR'

     Failed to connect to the MySQL server.

   * 'CR_CONNECTION_ERROR'

     Failed to connect to the local MySQL server.

   * 'CR_IPSOCK_ERROR'

     Failed to create an IP socket.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SOCKET_CREATE_ERROR'

     Failed to create a Unix socket.

   * 'CR_UNKNOWN_HOST'

     Failed to find the IP address for the host name.

   * 'CR_VERSION_ERROR'

     A protocol mismatch resulted from attempting to connect to a server
     with a client library that uses a different protocol version.

   * 'CR_NAMEDPIPEOPEN_ERROR'

     Failed to create a named pipe on Windows.

   * 'CR_NAMEDPIPEWAIT_ERROR'

     Failed to wait for a named pipe on Windows.

   * 'CR_NAMEDPIPESETSTATE_ERROR'

     Failed to get a pipe handler on Windows.

   * 'CR_SERVER_LOST'

     If 'connect_timeout' > 0 and it took longer than 'connect_timeout'
     seconds to connect to the server or if the server died while
     executing the 'init-command'.

   * 'CR_ALREADY_CONNECTED'

     The 'MYSQL' connection handler is already connected.

*Example*

     MYSQL mysql;

     mysql_init(&mysql);
     mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
     if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
     {
         fprintf(stderr, "Failed to connect to database: Error: %s\n",
               mysql_error(&mysql));
     }

By using 'mysql_options()' the MySQL client
library reads the '[client]' and '[your_prog_name]' sections in the
'my.cnf' file which ensures that your program works, even if someone has
set up MySQL in some nonstandard way.

Upon connection, see 'mysql_real_connect()' sets
the 'reconnect' flag (part of the 'MYSQL' structure) to a value of '1'
in versions of the API older than 5.0.3, or '0' in newer versions.  A
value of '1' for this flag indicates that if a statement cannot be
performed because of a lost connection, to try reconnecting to the
server before giving up.  You can use the 'MYSQL_OPT_RECONNECT' option
to 'mysql_options()' to control reconnection
behavior.

27.8.7.55 mysql_real_escape_string()
....................................

'unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const
char *from, unsigned long length)'

*Description*

This function creates a legal SQL string for use in an SQL statement.
See string-literals.

*Note*:

'mysql_real_escape_string()' fails and
produces an 'CR_INSECURE_API_ERR' error if the 'NO_BACKSLASH_ESCAPES'
SQL mode is enabled.  In this case, the function cannot escape quote
characters except by doubling them, and to do this properly, it must
know more information about the quoting context than is available.
Instead, use 'mysql_real_escape_string_quote()',
which takes an extra argument for
specifying the quoting context.

The 'mysql' argument must be a valid, open connection because character
escaping depends on the character set in use by the server.

The string in the 'from' argument is encoded to produce an escaped SQL
string, taking into account the current character set of the connection.
The result is placed in the 'to' argument, followed by a terminating
null byte.

Characters encoded are '\', ''', '"', 'NUL' (ASCII 0), '\n', '\r', and
Control+Z. Strictly speaking, MySQL requires only that backslash and the
quote character used to quote the string in the query be escaped.
'mysql_real_escape_string()' quotes the other
characters to make them easier to read in log files.  For comparison,
see the quoting rules for literal strings and the 'QUOTE()' SQL function
in string-literals, and string-functions.

The string pointed to by 'from' must be 'length' bytes long.  You must
allocate the 'to' buffer to be at least 'length*2+1' bytes long.  (In
the worst case, each character may need to be encoded as using two
bytes, and there must be room for the terminating null byte.)  When
'mysql_real_escape_string()' returns,
the contents of 'to' is a null-terminated string.  The return value is
the length of the encoded string, not including the terminating null
byte.

If you must change the character set of the connection, use the
'mysql_set_character_set()' function rather
than executing a 'SET NAMES'. (or 'SET CHARACTER SET')
statement.  'mysql_set_character_set()'
works like 'SET NAMES' but
also affects the character set used by
'mysql_real_escape_string()', which 'SET NAMES'
does not.

*Example*

The following example inserts two escaped strings into an 'INSERT'
statement, each within single quote characters:

     char query[1000],*end;

     end = my_stpcpy(query,"INSERT INTO test_table VALUES('");
     end += mysql_real_escape_string(&mysql,end,"What is this",12);
     end = my_stpcpy(end,"','");
     end += mysql_real_escape_string(&mysql,end,"binary data: \0\r\n",16);
     end = my_stpcpy(end,"')");

     if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
     {
        fprintf(stderr, "Failed to insert row, Error: %s\n",
                mysql_error(&mysql));
     }

The 'my_stpcpy()' function used in the example is included in the
'libmysqlclient' library and works like 'strcpy()' but returns a pointer
to the terminating null of the first parameter.

*Return Values*

The length of the encoded string that is placed into the 'to' argument,
not including the terminating null byte, or -1 if an error occurs.

Because 'mysql_real_escape_string()'.
returns an unsigned value, you can check for -1 by comparing the return
value to '(unsigned long)-1' (or to '(unsigned long)~0', which is
equivalent).

*Errors*

   * 'CR_INSECURE_API_ERR'

     This error occurs if the 'NO_BACKSLASH_ESCAPES' SQL mode is enabled
     because, in that case, see 'mysql_real_escape_string()'
     cannot be guaranteed to produce a
     properly encoded result.  To avoid this error, use
     'mysql_real_escape_string_quote()'.
     instead.

27.8.7.56 mysql_real_escape_string_quote()
..........................................

'unsigned long mysql_real_escape_string_quote(MYSQL *mysql, char *to,
const char *from, unsigned long length, char quote)'

*Description*

This function creates a legal SQL string for use in an SQL statement.
See string-literals.

The 'mysql' argument must be a valid, open connection because character
escaping depends on the character set in use by the server.

The string in the 'from' argument is encoded to produce an escaped SQL
string, taking into account the current character set of the connection.
The result is placed in the 'to' argument, followed by a terminating
null byte.

Characters encoded are '\', ''', '"', 'NUL' (ASCII 0), '\n', '\r',
Control+Z, and '`'.  Strictly speaking, MySQL requires only that
backslash and the quote character used to quote the string in the query
be escaped.  'mysql_real_escape_string_quote()'
quotes the other characters to make them
easier to read in log files.  For comparison, see the quoting rules for
literal strings and the 'QUOTE()' SQL function in
string-literals, and string-functions.

*Note*:

If the 'ANSI_QUOTES' SQL mode is enabled, see
'mysql_real_escape_string_quote()'.
cannot be used to escape double quote characters for use within
double-quoted identifiers.  (The function cannot tell whether the mode
is enabled to determine the proper escaping character.)

The string pointed to by 'from' must be 'length' bytes long.  You must
allocate the 'to' buffer to be at least 'length*2+1' bytes long.  (In
the worst case, each character may need to be encoded as using two
bytes, and there must be room for the terminating null byte.)  When
'mysql_real_escape_string_quote()'
returns, the contents of 'to' is a
null-terminated string.  The return value is the length of the encoded
string, not including the terminating null byte.

The 'quote' argument indicates the context in which the escaped string
is to be placed.  Suppose that you intend to escape the 'from' argument
and insert the escaped string (designated here by STR) into one of the
following statements:

     1) SELECT * FROM table WHERE name = 'STR'
     2) SELECT * FROM table WHERE name = "STR"
     3) SELECT * FROM `STR` WHERE id = 103

To perform escaping properly for each statement, call
'mysql_real_escape_string_quote()' as
follows, where the final argument indicates the quoting context:

     1) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'\'');
     2) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'"');
     3) len = mysql_real_escape_string_quote(&mysql,to,from,from_len,'`');

If you must change the character set of the connection, use the
'mysql_set_character_set()' function rather
than executing a 'SET NAMES'. (or 'SET CHARACTER SET')
statement.  'mysql_set_character_set()'
works like 'SET NAMES' but
also affects the character set used by
'mysql_real_escape_string_quote()',
which 'SET NAMES' does not.

*Example*

The following example inserts two escaped strings into an 'INSERT'
statement, each within single quote characters:

     char query[1000],*end;

     end = my_stpcpy(query,"INSERT INTO test_table VALUES('");
     end += mysql_real_escape_string_quote(&mysql,end,"What is this",12,'\'');
     end = my_stpcpy(end,"','");
     end += mysql_real_escape_string_quote(&mysql,end,"binary data: \0\r\n",16,'\'');
     end = my_stpcpy(end,"')");

     if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
     {
        fprintf(stderr, "Failed to insert row, Error: %s\n",
                mysql_error(&mysql));
     }

The 'my_stpcpy()' function used in the example is included in the
'libmysqlclient' library and works like 'strcpy()' but returns a pointer
to the terminating null of the first parameter.

*Return Values*

The length of the encoded string that is placed into the 'to' argument,
not including the terminating null byte.

*Errors*

None.

27.8.7.57 mysql_real_query()
............................

'int mysql_real_query(MYSQL *mysql, const char *stmt_str, unsigned long
length)'

*Description*

Executes the SQL statement pointed to by 'stmt_str', a string 'length'
bytes long.  Normally, the string must consist of a single SQL statement
without a terminating semicolon (';') or '\g'.  If multiple-statement
execution has been enabled, the string can contain several statements
separated by semicolons.  See c-api-multiple-queries.

'mysql_query()' cannot be used for statements that
contain binary data; you must use 'mysql_real_query()'
instead.  (Binary data may contain the '\0' character,
which 'mysql_query()' interprets as the end of the
statement string.)  In addition, see 'mysql_real_query()'
is faster than 'mysql_query()'.
because it does not call 'strlen()' on the statement string.

If you want to know whether the statement returns a result set, you can
use 'mysql_field_count()' to check for this.
See mysql-field-count.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.58 mysql_refresh()
.........................

'int mysql_refresh(MYSQL *mysql, unsigned int options)'

*Description*

*Note*:

As of MySQL 5.7.11, 'mysql_refresh()' is deprecated and will be removed
in a future version of MySQL. Instead, use 'mysql_query()'
to execute a 'FLUSH' statement.

This function flushes tables or caches, or resets replication server
information.  The connected user must have the 'RELOAD' privilege.

The 'options' argument is a bitmask composed from any combination of the
following values.  Multiple values can be OR'ed together to perform
multiple operations with a single call.

   * 'REFRESH_GRANT'

     Refresh the grant tables, like 'FLUSH PRIVILEGES'.

   * 'REFRESH_LOG'

     Flush the logs, like 'FLUSH LOGS'.

   * 'REFRESH_TABLES'

     Flush the table cache, like 'FLUSH TABLES'.

   * 'REFRESH_HOSTS'

     Flush the host cache, like 'FLUSH HOSTS'.

   * 'REFRESH_STATUS'

     Reset status variables, like 'FLUSH STATUS'.

   * 'REFRESH_THREADS'

     Flush the thread cache.

   * 'REFRESH_SLAVE'

     On a slave replication server, reset the master server information
     and restart the slave, like 'RESET SLAVE'.

   * 'REFRESH_MASTER'

     On a master replication server, remove the binary log files listed
     in the binary log index and truncate the index file, like
     'RESET MASTER'.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.59 mysql_reload()
........................

'int mysql_reload(MYSQL *mysql)'

*Description*

Asks the MySQL server to reload the grant tables.  The connected user
must have the 'RELOAD' privilege.

This function is deprecated.  Use 'mysql_query()' to
issue an SQL 'FLUSH PRIVILEGES' statement instead.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.60 mysql_reset_connection()
..................................

'int mysql_reset_connection(MYSQL *mysql)'

*Description*

Resets the connection to clear the session state.

'mysql_reset_connection()' has effects
similar to 'mysql_change_user()' or an
auto-reconnect except that the connection is not closed and reopened,
and reauthentication is not done.  See mysql-change-user) and
see c-api-auto-reconnect).

The connection-related state is affected as follows:

   * Any active transactions are rolled back and autocommit mode is
     reset.

   * All table locks are released.

   * All 'TEMPORARY' tables are closed (and dropped).

   * Session system variables are reinitialized to the values of the
     corresponding global system variables, including system variables
     that are set implicitly by statements such as 'SET NAMES'.

   * User variable settings are lost.

   * Prepared statements are released.

   * 'HANDLER' variables are closed.

   * The value of 'LAST_INSERT_ID()' is reset to 0.

   * Locks acquired with 'GET_LOCK()' are released.

*Return Values*

Zero for success.  Nonzero if an error occurred.

27.8.7.61 mysql_rollback()
..........................

'my_bool mysql_rollback(MYSQL *mysql)'

*Description*

Rolls back the current transaction.

The action of this function is subject to the value of the
'completion_type' system variable.  In particular, if the value of
'completion_type' is 'RELEASE' (or 2), the server performs a release
after terminating a transaction and closes the client connection.  Call
'mysql_close()' from the client program to close the
connection from the client side.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

None.

27.8.7.62 mysql_row_seek()
..........................

'MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET
offset)'

*Description*

Sets the row cursor to an arbitrary row in a query result set.  The
'offset' value is a row offset, typically a value returned from
'mysql_row_tell()' or from 'mysql_row_seek()'.
This value is not a row number; to seek to a row within
a result set by number, use 'mysql_data_seek()'.
instead.

This function requires that the result set structure contains the entire
result of the query, so 'mysql_row_seek()' may be
used only in conjunction with 'mysql_store_result()',
not with 'mysql_use_result()'.

*Return Values*

The previous value of the row cursor.  This value may be passed to a
subsequent call to 'mysql_row_seek()'.

*Errors*

None.

27.8.7.63 mysql_row_tell()
..........................

'MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)'

*Description*

Returns the current position of the row cursor for the last
'mysql_fetch_row()'.  This value can be used as an
argument to 'mysql_row_seek()'.

Use 'mysql_row_tell()' only after
'mysql_store_result()', not after
'mysql_use_result()'.

*Return Values*

The current offset of the row cursor.

*Errors*

None.

27.8.7.64 mysql_select_db()
...........................

'int mysql_select_db(MYSQL *mysql, const char *db)'

*Description*

Causes the database specified by 'db' to become the default (current)
database on the connection specified by 'mysql'.  In subsequent queries,
this database is the default for table references that include no
explicit database specifier.

'mysql_select_db()' fails unless the connected
user can be authenticated as having permission to use the database.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.65 mysql_session_track_get_first()
.........................................

'int mysql_session_track_get_first(MYSQL *mysql, enum
enum_session_state_type type, const char **data, size_t *length)'

*Description*

This function fetches the first session state-change information
received from the server.

To control notification for changes to session state, use the
'session_track_state_change', 'session_track_schema',
'session_track_system_variables', and 'session_track_gtids' system
variables (see server-system-variables).

The function parameters are used as follows.  These descriptions also
apply to 'mysql_session_track_get_next()',
which takes the same parameters.

   * 'mysql': The connection handler.

   * 'type': The type of information to retrieve.  Permitted values for
     this parameter are the members of the 'enum_session_state_type'
     enumeration defined in 'mysql_com.h':

          enum enum_session_state_type
          {
            SESSION_TRACK_SYSTEM_VARIABLES, /* Session system variables */
            SESSION_TRACK_SCHEMA,           /* Current schema */
            SESSION_TRACK_STATE_CHANGE      /* track session state changes */
            SESSION_TRACK_GTIDS,            /* track GTIDs/*
          };

     To make it easy to loop over all possible types of session
     information, the 'SESSION_TRACK_BEGIN' and 'SESSION_TRACK_END'
     macros are defined to be equal to the first and last members of the
     'enum_session_state_type' enumeration.  The example code shown
     later in this section demonstrates this technique.

   * 'data': The address of a 'const char *' variable.  Following a
     successful call, this variable points to the returned data, which
     should be considered read only.

   * 'length': The address of a 'size_t' variable.  Following a
     successful call, this variable contains the length of the data
     pointed to by the 'data' parameter.

Following a successful call, interpret the 'data' and 'length' values
according to the 'type' value, as follows:

   * 'SESSION_TRACK_SCHEMA': 'data' is the new default schema name and
     'length' is the name length.

   * 'SESSION_TRACK_SYSTEM_VARIABLES': When a session system variable
     changes, two values per variable are returned (in separate calls).
     For the first call, 'data' is the variable name and 'length' is the
     name length.  For the second call, 'data' is the variable value and
     'length' is the value length.  value Both data values are
     represented as strings.

   * 'SESSION_TRACK_STATE_CHANGE': 'data' is a byte containing a boolean
     flag that indicates whether session state changes occurred and
     'length' should be 1.  The flag is represented as an ASCII value,
     not a binary (for example, ''1'', not '0x01').

   * 'SESSION_TRACK_GTIDS': 'data' contains the GTID set information and
     'length' is its length.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

None.

*Example*

The following example shows how to call
'mysql_session_track_get_first()' and
'mysql_session_track_get_next()' to
retrieve and display all available session state-change information
following successful execution of an SQL statement string (represented
by 'stmt_str').

     printf("Execute: %s\n", stmt_str);

     if (mysql_query(mysql, stmt_str) != 0)
     {
       fprintf(stderr, "Error %u: %s\n",
                mysql_errno(mysql), mysql_error(mysql));
       return;
     }

     MYSQL_RES *result = mysql_store_result(mysql);
     if (result) /* there is a result set to fetch */
     {
       /* ... process rows here ... */
       printf("Number of rows returned: %lu\n",
               (unsigned long) mysql_num_rows(result));
       mysql_free_result(result);
     }
     else        /* there is no result set */
     {
       if (mysql_field_count(mysql) == 0)
       {
         printf("Number of rows affected: %lu\n",
                 (unsigned long) mysql_affected_rows(mysql));
       }
       else      /* an error occurred */
       {
         fprintf(stderr, "Error %u: %s\n",
                  mysql_errno(mysql), mysql_error(mysql));
       }
     }

     /* extract any available session state-change information */
     enum enum_session_state_type type;
     for (type = SESSION_TRACK_BEGIN; type <= SESSION_TRACK_END; type++)
     {
       const char *data;
       size_t length;

       if (mysql_session_track_get_first(mysql, type, &data, &length) == 0)
       {
         printf("Type=%d:\n", type);
         printf("mysql_session_track_get_first() returns: %*.*s\n",
                 (int) length, (int) length, data);

         /* check for more data */
         while (mysql_session_track_get_next(mysql, type, &data, &length) == 0)
         {
           printf("mysql_session_track_get_next() returns: %*.*s\n",
                   (int) length, (int) length, data);
         }
       }
     }

27.8.7.66 mysql_session_track_get_next()
........................................

'int mysql_session_track_get_next(MYSQL *mysql, enum
enum_session_state_type type, const char **data, size_t *length)'

*Description*

This function fetches session state-change information received from the
server, following that retrieved by
'mysql_session_track_get_first()'.

Following a successful call to 'mysql_session_track_get_first()',
call
'mysql_session_track_get_next()'.
repeatedly until it returns nonzero to indicate no more information is
available.  The calling sequence for
'mysql_session_track_get_next()' is
similar to that for 'mysql_session_track_get_first()'.
For more information and an example that
demonstrates both functions, see mysql-session-track-get-first.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

None.

27.8.7.67 mysql_set_character_set()
...................................

'int mysql_set_character_set(MYSQL *mysql, const char *csname)'

*Description*

This function is used to set the default character set for the current
connection.  The string 'csname' specifies a valid character set name.
The connection collation becomes the default collation of the character
set.  This function works like the 'SET NAMES'.
statement, but also sets the value of 'mysql->charset', and thus affects
the character set used by 'mysql_real_escape_string()'.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Example*

     MYSQL mysql;

     mysql_init(&mysql);
     if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
     {
         fprintf(stderr, "Failed to connect to database: Error: %s\n",
               mysql_error(&mysql));
     }

     if (!mysql_set_character_set(&mysql, "utf8"))
     {
         printf("New client character set: %s\n",
                mysql_character_set_name(&mysql));
     }

27.8.7.68 mysql_set_local_infile_default()
..........................................

'void mysql_set_local_infile_default(MYSQL *mysql);'

*Description*

Sets the 'LOAD DATA LOCAL INFILE' callback functions
to the defaults used internally by the C client library.  The library
calls this function automatically if
'mysql_set_local_infile_handler()' has
not been called or does not supply valid functions for each of its
callbacks.

*Return Values*

None.

*Errors*

None.

27.8.7.69 mysql_set_local_infile_handler()
..........................................

'void mysql_set_local_infile_handler(MYSQL *mysql, int
(*local_infile_init)(void **, const char *, void *), int
(*local_infile_read)(void *, char *, unsigned int), void
(*local_infile_end)(void *), int (*local_infile_error)(void *, char*,
unsigned int), void *userdata);'

*Description*

This function installs callbacks to be used during the execution of
'LOAD DATA LOCAL INFILE' statements.  It enables
application programs to exert control over local (client-side) data file
reading.  The arguments are the connection handler, a set of pointers to
callback functions, and a pointer to a data area that the callbacks can
use to share information.

To use 'mysql_set_local_infile_handler()',
you must write the following callback
functions:

     int
     local_infile_init(void **ptr, const char *filename, void *userdata);

The initialization function.  This is called once to do any setup
necessary, open the data file, allocate data structures, and so forth.
The first 'void**' argument is a pointer to a pointer.  You can set the
pointer (that is, '*ptr') to a value that will be passed to each of the
other callbacks (as a 'void*').  The callbacks can use this pointed-to
value to maintain state information.  The 'userdata' argument is the
same value that is passed to 'mysql_set_local_infile_handler()'.

Make the initialization function return zero for success, nonzero for an
error.

     int
     local_infile_read(void *ptr, char *buf, unsigned int buf_len);

The data-reading function.  This is called repeatedly to read the data
file.  'buf' points to the buffer where the read data is stored, and
'buf_len' is the maximum number of bytes that the callback can read and
store in the buffer.  (It can read fewer bytes, but should not read
more.)

The return value is the number of bytes read, or zero when no more data
could be read (this indicates EOF). Return a value less than zero if an
error occurs.

     void
     local_infile_end(void *ptr)

The termination function.  This is called once after
'local_infile_read()' has returned zero (EOF) or an error.  Within this
function, deallocate any memory allocated by 'local_infile_init()' and
perform any other cleanup necessary.  It is invoked even if the
initialization function returns an error.

     int
     local_infile_error(void *ptr,
                        char *error_msg,
                        unsigned int error_msg_len);

The error-handling function.  This is called to get a textual error
message to return to the user in case any of your other functions
returns an error.  'error_msg' points to the buffer into which the
message is written, and 'error_msg_len' is the length of the buffer.
Write the message as a null-terminated string, at most
'error_msg_len'−1 bytes long.

The return value is the error number.

Typically, the other callbacks store the error message in the data
structure pointed to by 'ptr', so that 'local_infile_error()' can copy
the message from there into 'error_msg'.

After calling 'mysql_set_local_infile_handler()'
in your C code and passing pointers to
your callback functions, you can then issue a 'LOAD DATA LOCAL INFILE'
statement (for example, by using
'mysql_query()').  The client library automatically
invokes your callbacks.  The file name specified in 'LOAD DATA LOCAL INFILE'
will be passed as the second parameter to the
'local_infile_init()' callback.

*Return Values*

None.

*Errors*

None.

27.8.7.70 mysql_set_server_option()
...................................

'int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option
option)'

*Description*

Enables or disables an option for the connection.  'option' can have one
of the following values.

Option                               Description

'MYSQL_OPTION_MULTI_STATEMENTS_ON'   Enable multiple-statement support

'MYSQL_OPTION_MULTI_STATEMENTS_OFF'  Disable multiple-statement support

If you enable multiple-statement support, you should retrieve results
from calls to 'mysql_query()' or
'mysql_real_query()' by using a loop that calls
'mysql_next_result()' to determine whether there are
more results.  For an example, see c-api-multiple-queries.

Enabling multiple-statement support with
'MYSQL_OPTION_MULTI_STATEMENTS_ON' does not have quite the same effect
as enabling it by passing the 'CLIENT_MULTI_STATEMENTS' flag to
'mysql_real_connect()'.: 'CLIENT_MULTI_STATEMENTS'
also enables 'CLIENT_MULTI_RESULTS'.  If you are using the 'CALL'.
SQL statement in your programs, multiple-result support must be
enabled; this means that 'MYSQL_OPTION_MULTI_STATEMENTS_ON' by itself is
insufficient to permit the use of 'CALL'.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'ER_UNKNOWN_COM_ERROR'

     The server did not support 'mysql_set_server_option()'.
     (which is the case that the server is
     older than 4.1.1) or the server did not support the option one
     tried to set.

27.8.7.71 mysql_shutdown()
..........................

'int mysql_shutdown(MYSQL *mysql, enum mysql_enum_shutdown_level
shutdown_level)'

*Description*

*Note*:

'mysql_shutdown()' is deprecated and will be removed in a future version
of MySQL. Instead, use 'mysql_query()' to execute a
'SHUTDOWN' statement.

Asks the database server to shut down.  The connected user must have the
'SHUTDOWN' privilege.  MySQL servers support only one type of shutdown;
'shutdown_level' must be equal to 'SHUTDOWN_DEFAULT'.  Dynamically
linked executables which have been compiled with older versions of the
'libmysqlclient' headers and call 'mysql_shutdown()'
need to be used with the old 'libmysqlclient' dynamic
library.

An alternative to 'mysql_shutdown()' is to use
the 'SHUTDOWN'. SQL statement.

The shutdown process is described in server-shutdown.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.72 mysql_sqlstate()
..........................

'const char *mysql_sqlstate(MYSQL *mysql)'

*Description*

Returns a null-terminated string containing the SQLSTATE error code for
the most recently executed SQL statement.  The error code consists of
five characters.  ''00000'' means 'no error.' The values are specified
by ANSI SQL and ODBC. For a list of possible values, see
error-handling.

SQLSTATE values returned by 'mysql_sqlstate()'.
differ from MySQL-specific error numbers returned by
'mysql_errno()'.  For example, the 'mysql'.
client program displays errors using the following format, where '1146'
is the 'mysql_errno()' value and ''42S02'' is the
corresponding 'mysql_sqlstate()' value:

     shell> SELECT * FROM no_such_table;
     ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist

Not all MySQL error numbers are mapped to SQLSTATE error codes.  The
value ''HY000'' (general error) is used for unmapped error numbers.

If you call 'mysql_sqlstate()' after
'mysql_real_connect()' fails, see
'mysql_sqlstate()' might not return a useful value.
For example, this happens if a host is blocked by the server and the
connection is closed without any SQLSTATE value being sent to the
client.

*Return Values*

A null-terminated character string containing the SQLSTATE error code.

*See Also*

See mysql-errno, mysql-error, and
mysql-stmt-sqlstate.

27.8.7.73 mysql_ssl_set()
.........................

'my_bool mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert,
const char *ca, const char *capath, const char *cipher)'

*Description*

'mysql_ssl_set()' is used for establishing
encrypted connections using SSL. The 'mysql' argument must be a valid
connection handler.  Any unused SSL arguments may be given as 'NULL'.

If used, see 'mysql_ssl_set()' must be called before
'mysql_real_connect()'.
'mysql_ssl_set()' does nothing unless SSL support is
enabled in the client library.

It is optional to call 'mysql_ssl_set()' to obtain
an encrypted connection because by default, MySQL programs attempt to
connect using encryption if the server supports encrypted connections,
falling back to an unencrypted connection if an encrypted connection
cannot be established (see using-encrypted-connections).
'mysql_ssl_set()' may be useful to applications that
must specify particular certificate and key files, encryption ciphers,
and so forth.

'mysql_ssl_set()' specifies SSL information such
as certificate and key files for establishing an encrypted connection if
such connections are available, but does not enforce any requirement
that the connection obtained be encrypted.  To require an encrypted
connection, use the technique described in
c-api-encrypted-connections.

For additional security relative to that provided by the default
encryption, clients can supply a CA certificate matching the one used by
the server and enable host name identity verification.  In this way, the
server and client place their trust in the same CA certificate and the
client verifies that the host to which it connected is the one intended.
For details, see c-api-encrypted-connections.

'mysql_ssl_set()' is a convenience function that
is essentially equivalent to this set of 'mysql_options()'
calls:

     mysql_options(mysql, MYSQL_OPT_SSL_KEY,    key);
     mysql_options(mysql, MYSQL_OPT_SSL_CERT,   cert);
     mysql_options(mysql, MYSQL_OPT_SSL_CA,     ca);
     mysql_options(mysql, MYSQL_OPT_SSL_CAPATH, capath);
     mysql_options(mysql, MYSQL_OPT_SSL_CIPHER, cipher);

Because of that equivalence, applications can, instead of calling
'mysql_ssl_set()', call 'mysql_options()'
directly, omitting calls for those options for which the
option value is 'NULL'.  Moreover, see 'mysql_options()'
offers encrypted-connection options not available using
'mysql_ssl_set()', such as 'MYSQL_OPT_SSL_MODE' to
specify the security state of the connection, and
'MYSQL_OPT_TLS_VERSION' to specify the protocols permitted by the client
for encrypted connections.

Arguments:

   * 'mysql': The connection handler returned from 'mysql_init()'.

   * 'key': The path name of the client private key file.

   * 'cert': The path name of the client public key certificate file.

   * 'ca': The path name of the Certificate Authority (CA) certificate
     file.  This option, if used, must specify the same certificate used
     by the server.

   * 'capath': The path name of the directory that contains trusted SSL
     CA certificate files.

   * 'cipher': The list of permitted ciphers for SSL encryption.

*Return Values*

This function always returns '0'.  If SSL setup is incorrect, a
subsequent 'mysql_real_connect()' call
returns an error when you attempt to connect.

27.8.7.74 mysql_stat()
......................

'const char *mysql_stat(MYSQL *mysql)'

*Description*

Returns a character string containing information similar to that
provided by the 'mysqladmin status' command.  This
includes uptime in seconds and the number of running threads, questions,
reloads, and open tables.

*Return Values*

A character string describing the server status.  'NULL' if an error
occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.75 mysql_store_result()
..............................

'MYSQL_RES *mysql_store_result(MYSQL *mysql)'

*Description*

After invoking 'mysql_query()' or
'mysql_real_query()', you must call
'mysql_store_result()' or
'mysql_use_result()' for every statement that
successfully produces a result set (see 'SELECT',
'SHOW', 'DESCRIBE', 'EXPLAIN',
'CHECK TABLE', and so forth).  You must also call
'mysql_free_result()' after you are done with
the result set.

You need not call 'mysql_store_result()' or
'mysql_use_result()' for other statements, but
it does not do any harm or cause any notable performance degradation if
you call 'mysql_store_result()' in all cases.
You can detect whether the statement has a result set by checking
whether 'mysql_store_result()' returns a
nonzero value (more about this later).

If you enable multiple-statement support, you should retrieve results
from calls to 'mysql_query()' or
'mysql_real_query()' by using a loop that calls
'mysql_next_result()' to determine whether there are
more results.  For an example, see c-api-multiple-queries.

If you want to know whether a statement should return a result set, you
can use 'mysql_field_count()' to check for
this.  See mysql-field-count.

'mysql_store_result()' reads the entire
result of a query to the client, allocates a 'MYSQL_RES' structure, and
places the result into this structure.

'mysql_store_result()' returns a null pointer
if the statement did not return a result set (for example, if it was an
'INSERT' statement).

'mysql_store_result()' also returns a null
pointer if reading of the result set failed.  You can check whether an
error occurred by checking whether 'mysql_error()'.
returns a nonempty string, see 'mysql_errno()' returns
nonzero, or 'mysql_field_count()' returns
zero.

An empty result set is returned if there are no rows returned.  (An
empty result set differs from a null pointer as a return value.)

After you have called 'mysql_store_result()'.
and gotten back a result that is not a null pointer, you can call
'mysql_num_rows()' to find out how many rows are in the
result set.

You can call 'mysql_fetch_row()' to fetch rows
from the result set, or 'mysql_row_seek()' and
'mysql_row_tell()' to obtain or set the current
row position within the result set.

See null-mysql-store-result.

*Return Values*

A 'MYSQL_RES' result structure with the results.  'NULL' (0) if an error
occurred.

*Errors*

'mysql_store_result()' resets
'mysql_error()' and 'mysql_errno()' if
it succeeds.

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.76 mysql_thread_id()
...........................

'unsigned long mysql_thread_id(MYSQL *mysql)'

*Description*

Returns the thread ID of the current connection.  This value can be used
as an argument to 'mysql_kill()' to kill the thread.

If the connection is lost and you reconnect with 'mysql_ping()',
the thread ID changes.  This means you should not get the
thread ID and store it for later.  You should get it when you need it.

*Note*:

This function does not work correctly if thread IDs become larger than
32 bits, which can occur on some systems.  To avoid problems with
'mysql_thread_id()', do not use it.  To get the
connection ID, execute a 'SELECT CONNECTION_ID()' query and retrieve the
result.

*Return Values*

The thread ID of the current connection.

*Errors*

None.

27.8.7.77 mysql_use_result()
............................

'MYSQL_RES *mysql_use_result(MYSQL *mysql)'

*Description*

After invoking 'mysql_query()' or
'mysql_real_query()', you must call
'mysql_store_result()' or
'mysql_use_result()' for every statement that
successfully produces a result set (see 'SELECT',
'SHOW', 'DESCRIBE', 'EXPLAIN',
'CHECK TABLE', and so forth).  You must also call
'mysql_free_result()' after you are done with
the result set.

'mysql_use_result()' initiates a result set
retrieval but does not actually read the result set into the client like
'mysql_store_result()' does.  Instead, each
row must be retrieved individually by making calls to
'mysql_fetch_row()'.  This reads the result of a query
directly from the server without storing it in a temporary table or
local buffer, which is somewhat faster and uses much less memory than
'mysql_store_result()'.  The client allocates
memory only for the current row and a communication buffer that may grow
up to 'max_allowed_packet' bytes.

On the other hand, you should not use 'mysql_use_result()'
for locking reads if you are doing a lot of processing
for each row on the client side, or if the output is sent to a screen on
which the user may type a '^S' (stop scroll).  This ties up the server
and prevent other threads from updating any tables from which the data
is being fetched.

When using 'mysql_use_result()', you must
execute 'mysql_fetch_row()' until a 'NULL' value
is returned, otherwise, the unfetched rows are returned as part of the
result set for your next query.  The C API gives the error 'Commands out
of sync; you can't run this command now' if you forget to do this!

You may not use 'mysql_data_seek()',
'mysql_row_seek()', 'mysql_row_tell()',
see 'mysql_num_rows()', or
'mysql_affected_rows()' with a result returned
from 'mysql_use_result()', nor may you issue
other queries until 'mysql_use_result()' has
finished.  (However, after you have fetched all the rows, see
'mysql_num_rows()' accurately returns the number of
rows fetched.)

You must call 'mysql_free_result()' once you
are done with the result set.

When using the 'libmysqld' embedded server, the memory benefits are
essentially lost because memory usage incrementally increases with each
row retrieved until 'mysql_free_result()' is
called.

*Return Values*

A 'MYSQL_RES' result structure.  'NULL' if an error occurred.

*Errors*

'mysql_use_result()' resets
'mysql_error()' and 'mysql_errno()' if
it succeeds.

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.7.78 mysql_warning_count()
...............................

'unsigned int mysql_warning_count(MYSQL *mysql)'

*Description*

Returns the number of errors, warnings, and notes generated during
execution of the previous SQL statement.

*Return Values*

The warning count.

*Errors*

None.

27.8.8 C API Prepared Statements
--------------------------------

The MySQL client/server protocol provides for the use of prepared
statements.  This capability uses the 'MYSQL_STMT' statement handler
data structure returned by the 'mysql_stmt_init()'
initialization function.  Prepared execution is an
efficient way to execute a statement more than once.  The statement is
first parsed to prepare it for execution.  Then it is executed one or
more times at a later time, using the statement handler returned by the
initialization function.

Prepared execution is faster than direct execution for statements
executed more than once, primarily because the query is parsed only
once.  In the case of direct execution, the query is parsed every time
it is executed.  Prepared execution also can provide a reduction of
network traffic because for each execution of the prepared statement, it
is necessary only to send the data for the parameters.

Prepared statements might not provide a performance increase in some
situations.  For best results, test your application both with prepared
and nonprepared statements and choose whichever yields best performance.

Another advantage of prepared statements is that it uses a binary
protocol that makes data transfer between client and server more
efficient.

For a list of SQL statements that can be used as prepared statements,
see sql-syntax-prepared-statements.

Metadata changes to tables or views referred to by prepared statements
are detected and cause automatic repreparation of the statement when it
is next executed.  For more information, see statement-caching.

27.8.9 C API Prepared Statement Data Structures
-----------------------------------------------

Prepared statements use several data structures:

   * To obtain a statement handler, pass a 'MYSQL' connection handler to
     'mysql_stmt_init()', which returns a pointer
     to a 'MYSQL_STMT' data structure.  This structure is used for
     further operations with the statement.  To specify the statement to
     prepare, pass the 'MYSQL_STMT' pointer and the statement string to
     'mysql_stmt_prepare()'.

   * To provide input parameters for a prepared statement, set up
     'MYSQL_BIND' structures and pass them to
     'mysql_stmt_bind_param()'.  To receive
     output column values, set up 'MYSQL_BIND' structures and pass them
     to 'mysql_stmt_bind_result()'.

   * The 'MYSQL_TIME' structure is used to transfer temporal data in
     both directions.

The following discussion describes the prepared statement data types in
detail.  For examples that show how to use them, see
mysql-stmt-execute, and mysql-stmt-fetch.

   *
     'MYSQL_STMT'

     This structure is a handler for a prepared statement.  A handler is
     created by calling 'mysql_stmt_init()',
     which returns a pointer to a 'MYSQL_STMT'.  The handler is used for
     all subsequent operations with the statement until you close it
     with 'mysql_stmt_close()', at which point
     the handler becomes invalid and should no longer be used.

     The 'MYSQL_STMT' structure has no members intended for application
     use.  Applications should not try to copy a 'MYSQL_STMT' structure.
     There is no guarantee that such a copy will be usable.

     Multiple statement handlers can be associated with a single
     connection.  The limit on the number of handlers depends on the
     available system resources.

   *
     'MYSQL_BIND'

     This structure is used both for statement input (data values sent
     to the server) and output (result values returned from the server):

        * For input, use 'MYSQL_BIND' structures with
          'mysql_stmt_bind_param()' to bind
          parameter data values to buffers for use by
          'mysql_stmt_execute()'.

        * For output, use 'MYSQL_BIND' structures with
          'mysql_stmt_bind_result()' to bind
          buffers to result set columns, for use in fetching rows with
          'mysql_stmt_fetch()'.

     To use a 'MYSQL_BIND' structure, zero its contents to initialize
     it, then set its members appropriately.  For example, to declare
     and initialize an array of three 'MYSQL_BIND' structures, use this
     code:

          MYSQL_BIND bind[3];
          memset(bind, 0, sizeof(bind));

     The 'MYSQL_BIND' structure contains the following members for use
     by application programs.  For several of the members, the manner of
     use depends on whether the structure is used for input or output.

        * 'enum enum_field_types buffer_type'

          The type of the buffer.  This member indicates the data type
          of the C language variable bound to a statement parameter or
          result set column.  For input, 'buffer_type' indicates the
          type of the variable containing the value to be sent to the
          server.  For output, it indicates the type of the variable
          into which a value received from the server should be stored.
          For permissible 'buffer_type' values, see
          c-api-prepared-statement-type-codes.

        * 'void *buffer'

          A pointer to the buffer to be used for data transfer.  This is
          the address of a C language variable.

          For input, 'buffer' is a pointer to the variable in which you
          store the data value for a statement parameter.  When you call
          'mysql_stmt_execute()', MySQL use
          the value stored in the variable in place of the corresponding
          parameter marker in the statement (specified with '?' in the
          statement string).

          For output, 'buffer' is a pointer to the variable in which to
          return a result set column value.  When you call
          'mysql_stmt_fetch()', MySQL stores a column
          value from the current row of the result set in this variable.
          You can access the value when the call returns.

          To minimize the need for MySQL to perform type conversions
          between C language values on the client side and SQL values on
          the server side, use C variables that have types similar to
          those of the corresponding SQL values:

             * For numeric data types, 'buffer' should point to a
               variable of the proper numeric C type.  For integer
               variables (which can be 'char' for single-byte values or
               an integer type for larger values), you should also
               indicate whether the variable has the 'unsigned'
               attribute by setting the 'is_unsigned' member, described
               later.

             * For character (nonbinary) and binary string data types,
               'buffer' should point to a character buffer.

             * For date and time data types, 'buffer' should point to a
               'MYSQL_TIME' structure.

          For guidelines about mapping between C types and SQL types and
          notes about type conversions, see
          c-api-prepared-statement-type-codes, and
          c-api-prepared-statement-type-conversions.

        * 'unsigned long buffer_length'

          The actual size of '*buffer' in bytes.  This indicates the
          maximum amount of data that can be stored in the buffer.  For
          character and binary C data, the 'buffer_length' value
          specifies the length of '*buffer' when used with
          'mysql_stmt_bind_param()' to specify
          input values, or the maximum number of output data bytes that
          can be fetched into the buffer when used with
          'mysql_stmt_bind_result()'.

        * 'unsigned long *length'

          A pointer to an 'unsigned long' variable that indicates the
          actual number of bytes of data stored in '*buffer'.  'length'
          is used for character or binary C data.

          For input parameter data binding, set '*length' to indicate
          the actual length of the parameter value stored in '*buffer'.
          This is used by 'mysql_stmt_execute()'.

          For output value binding, MySQL sets '*length' when you call
          'mysql_stmt_fetch()'.  The
          'mysql_stmt_fetch()' return value
          determines how to interpret the length:

             * If the return value is 0, '*length' indicates the actual
               length of the parameter value.

             * If the return value is 'MYSQL_DATA_TRUNCATED', '*length'
               indicates the nontruncated length of the parameter value.
               In this case, the minimum of '*length' and
               'buffer_length' indicates the actual length of the value.

          'length' is ignored for numeric and temporal data types
          because the 'buffer_type' value determines the length of the
          data value.

          If you must determine the length of a returned value before
          fetching it, see mysql-stmt-fetch, for some
          strategies.

        * 'my_bool *is_null'

          This member points to a 'my_bool' variable that is true if a
          value is 'NULL', false if it is not 'NULL'.  For input, set
          '*is_null' to true to indicate that you are passing a 'NULL'
          value as a statement parameter.

          'is_null' is a _pointer_ to a boolean scalar, not a boolean
          scalar, to provide flexibility in how you specify 'NULL'
          values:

             * If your data values are always 'NULL', use
               'MYSQL_TYPE_NULL' as the 'buffer_type' value when you
               bind the column.  The other 'MYSQL_BIND' members,
               including 'is_null', do not matter.

             * If your data values are always 'NOT NULL', set 'is_null =
               (my_bool*) 0', and set the other members appropriately
               for the variable you are binding.

             * In all other cases, set the other members appropriately
               and set 'is_null' to the address of a 'my_bool' variable.
               Set that variable's value to true or false appropriately
               between executions to indicate whether the corresponding
               data value is 'NULL' or 'NOT NULL', respectively.

          For output, when you fetch a row, MySQL sets the value pointed
          to by 'is_null' to true or false according to whether the
          result set column value returned from the statement is or is
          not 'NULL'.

        * 'my_bool is_unsigned'

          This member applies for C variables with data types that can
          be 'unsigned' ('char', 'short int', 'int', 'long long int').
          Set 'is_unsigned' to true if the variable pointed to by
          'buffer' is 'unsigned' and false otherwise.  For example, if
          you bind a 'signed char' variable to 'buffer', specify a type
          code of 'MYSQL_TYPE_TINY' and set 'is_unsigned' to false.  If
          you bind an 'unsigned char' instead, the type code is the same
          but 'is_unsigned' should be true.  (For 'char', it is not
          defined whether it is signed or unsigned, so it is best to be
          explicit about signedness by using 'signed char' or 'unsigned
          char'.)

          'is_unsigned' applies only to the C language variable on the
          client side.  It indicates nothing about the signedness of the
          corresponding SQL value on the server side.  For example, if
          you use an 'int' variable to supply a value for a 'BIGINT
          UNSIGNED' column, 'is_unsigned' should be false because 'int'
          is a signed type.  If you use an 'unsigned int' variable to
          supply a value for a 'BIGINT' column,
          'is_unsigned' should be true because 'unsigned int' is an
          unsigned type.  MySQL performs the proper conversion between
          signed and unsigned values in both directions, although a
          warning occurs if truncation results.

        * 'my_bool *error'

          For output, set this member to point to a 'my_bool' variable
          to have truncation information for the parameter stored there
          after a row fetching operation.  When truncation reporting is
          enabled, see 'mysql_stmt_fetch()' returns
          'MYSQL_DATA_TRUNCATED' and '*error' is true in the
          'MYSQL_BIND' structures for parameters in which truncation
          occurred.  Truncation indicates loss of sign or significant
          digits, or that a string was too long to fit in a column.
          Truncation reporting is enabled by default, but can be
          controlled by calling 'mysql_options()'.
          with the 'MYSQL_REPORT_DATA_TRUNCATION' option.

   *
     'MYSQL_TIME'

     This structure is used to send and receive 'DATE',
     'TIME', 'DATETIME', and
     'TIMESTAMP' data directly to and from the server.  Set
     the 'buffer' member to point to a 'MYSQL_TIME' structure, and set
     the 'buffer_type' member of a 'MYSQL_BIND' structure to one of the
     temporal types ('MYSQL_TYPE_TIME', 'MYSQL_TYPE_DATE',
     'MYSQL_TYPE_DATETIME', 'MYSQL_TYPE_TIMESTAMP').

     The 'MYSQL_TIME' structure contains the members listed in the
     following table.

     Member                        Description

     'unsigned int year'           The year

     'unsigned int month'          The month of the year

     'unsigned int day'            The day of the month

     'unsigned int hour'           The hour of the day

     'unsigned int minute'         The minute of the hour

     'unsigned int second'         The second of the minute

     'my_bool neg'                 A boolean flag indicating whether the
                                   time is negative

     'unsigned long second_part'   The fractional part of the second in
                                   microseconds

     Only those parts of a 'MYSQL_TIME' structure that apply to a given
     type of temporal value are used.  The 'year', 'month', and 'day'
     elements are used for 'DATE', 'DATETIME',
     and 'TIMESTAMP' values.  The 'hour',
     'minute', and 'second' elements are used for 'TIME',
     'DATETIME', and 'TIMESTAMP'.
     values.  See c-api-prepared-statement-date-handling.

27.8.9.1 C API Prepared Statement Type Codes
............................................

The 'buffer_type' member of 'MYSQL_BIND' structures indicates the data
type of the C language variable bound to a statement parameter or result
set column.  For input, 'buffer_type' indicates the type of the variable
containing the value to be sent to the server.  For output, it indicates
the type of the variable into which a value received from the server
should be stored.

The following table shows the permissible values for the 'buffer_type'
member of 'MYSQL_BIND' structures for input values sent to the server.
The table shows the C variable types that you can use, the corresponding
type codes, and the SQL data types for which the supplied value can be
used without conversion.  Choose the 'buffer_type' value according to
the data type of the C language variable that you are binding.  For the
integer types, you should also set the 'is_unsigned' member to indicate
whether the variable is signed or unsigned.

Input Variable C       'buffer_type' Value       SQL Type of Destination
Type                                             Value

'signed char'          'MYSQL_TYPE_TINY'         'TINYINT'.

'short int'            'MYSQL_TYPE_SHORT'        'SMALLINT'.

'int'                  'MYSQL_TYPE_LONG'         'INT'.

'long long int'        'MYSQL_TYPE_LONGLONG'     'BIGINT'.

'float'                'MYSQL_TYPE_FLOAT'        'FLOAT'.

'double'               'MYSQL_TYPE_DOUBLE'       'DOUBLE'.

'MYSQL_TIME'           'MYSQL_TYPE_TIME'         'TIME'.

'MYSQL_TIME'           'MYSQL_TYPE_DATE'         'DATE'.

'MYSQL_TIME'           'MYSQL_TYPE_DATETIME'     'DATETIME'.

'MYSQL_TIME'           'MYSQL_TYPE_TIMESTAMP'    'TIMESTAMP'.

'char[]'               'MYSQL_TYPE_STRING'       'TEXT',
                                                 'CHAR',
                                                 'VARCHAR'.

'char[]'               'MYSQL_TYPE_BLOB'         'BLOB',
                                                 'BINARY',
                                        See
                                                 'VARBINARY'.

                       'MYSQL_TYPE_NULL'         'NULL'

Use 'MYSQL_TYPE_NULL' as indicated in the description for the 'is_null'
member in c-api-prepared-statement-data-structures.

For input string data, use 'MYSQL_TYPE_STRING' or 'MYSQL_TYPE_BLOB'
depending on whether the value is a character (nonbinary) or binary
string:

   * 'MYSQL_TYPE_STRING' indicates character input string data.  The
     value is assumed to be in the character set indicated by the
     'character_set_client' system variable.  If the server stores the
     value into a column with a different character set, it converts the
     value to that character set.

   * 'MYSQL_TYPE_BLOB' indicates binary input string data.  The value is
     treated as having the 'binary' character set.  That is, it is
     treated as a byte string and no conversion occurs.

The following table shows the permissible values for the 'buffer_type'
member of 'MYSQL_BIND' structures for output values received from the
server.  The table shows the SQL types of received values, the
corresponding type codes that such values have in result set metadata,
and the recommended C language data types to bind to the 'MYSQL_BIND'
structure to receive the SQL values without conversion.  Choose the
'buffer_type' value according to the data type of the C language
variable that you are binding.  For the integer types, you should also
set the 'is_unsigned' member to indicate whether the variable is signed
or unsigned.

SQL Type of Received   'buffer_type' Value       Output Variable C Type
Value

See 'TINYINT'.

See 'SMALLINT'.

See 'MEDIUMINT'.

See 'INT'.

See 'BIGINT'.

See 'FLOAT'.

See 'DOUBLE'.

See 'DECIMAL'.

See 'YEAR'.    'MYSQL_TYPE_SHORT'        'short int'

See 'TIME'.    'MYSQL_TYPE_TIME'         'MYSQL_TIME'

See 'DATE'.

See 'DATETIME'.

See 'TIMESTAMP'.

See 'CHAR',    'MYSQL_TYPE_STRING'       'char[]'
'BINARY'.

See 'VARCHAR',
see
'VARBINARY'.

See 'TINYBLOB',
see
'TINYTEXT'.

See 'BLOB',    'MYSQL_TYPE_BLOB'         'char[]'
'TEXT'.

See 'MEDIUMBLOB',
see
'MEDIUMTEXT'.

See 'LONGBLOB',
see
'LONGTEXT'.

See 'BIT'.

27.8.9.2 C API Prepared Statement Type Conversions
..................................................

Prepared statements transmit data between the client and server using C
language variables on the client side that correspond to SQL values on
the server side.  If there is a mismatch between the C variable type on
the client side and the corresponding SQL value type on the server side,
MySQL performs implicit type conversions in both directions.

MySQL knows the type code for the SQL value on the server side.  The
'buffer_type' value in the 'MYSQL_BIND' structure indicates the type
code of the C variable that holds the value on the client side.  The two
codes together tell MySQL what conversion must be performed, if any.
Here are some examples:

   * If you use 'MYSQL_TYPE_LONG' with an 'int' variable to pass an
     integer value to the server that is to be stored into a
     'FLOAT' column, MySQL converts the value to
     floating-point format before storing it.

   * If you fetch an SQL 'MEDIUMINT' column value,
     but specify a 'buffer_type' value of 'MYSQL_TYPE_LONGLONG' and use
     a C variable of type 'long long int' as the destination buffer,
     MySQL converts the 'MEDIUMINT' value (which
     requires less than 8 bytes) for storage into the 'long long int'
     (an 8-byte variable).

   * If you fetch a numeric column with a value of 255 into a 'char[4]'
     character array and specify a 'buffer_type' value of
     'MYSQL_TYPE_STRING', the resulting value in the array is a 4-byte
     string ''255\0''.

   * MySQL returns 'DECIMAL' values as the
     string representation of the original server-side value, which is
     why the corresponding C type is 'char[]'.  For example, '12.345' is
     returned to the client as ''12.345''.  If you specify
     'MYSQL_TYPE_NEWDECIMAL' and bind a string buffer to the
     'MYSQL_BIND' structure, see 'mysql_stmt_fetch()'
     stores the value in the buffer as a string
     without conversion.  If instead you specify a numeric variable and
     type code, see 'mysql_stmt_fetch()' converts
     the string-format 'DECIMAL' value to
     numeric form.

   * For the 'MYSQL_TYPE_BIT' type code, see 'BIT' values
     are returned into a string buffer, which is why the corresponding C
     type is 'char[]'.  The value represents a bit string that requires
     interpretation on the client side.  To return the value as a type
     that is easier to deal with, you can cause the value to be cast to
     integer using either of the following types of expressions:

          SELECT bit_col + 0 FROM t
          SELECT CAST(bit_col AS UNSIGNED) FROM t

     To retrieve the value, bind an integer variable large enough to
     hold the value and specify the appropriate corresponding integer
     type code.

Before binding variables to the 'MYSQL_BIND' structures that are to be
used for fetching column values, you can check the type codes for each
column of the result set.  This might be desirable if you want to
determine which variable types would be best to use to avoid type
conversions.  To get the type codes, call
'mysql_stmt_result_metadata()' after
executing the prepared statement with 'mysql_stmt_execute()'.
The metadata provides access to the type codes for
the result set as described in mysql-stmt-result-metadata, and
c-api-data-structures.

To determine whether output string values in a result set returned from
the server contain binary or nonbinary data, check whether the
'charsetnr' value of the result set metadata is 63 (see
c-api-data-structures).  If so, the character set is 'binary', which
indicates binary rather than nonbinary data.  This enables you to
distinguish 'BINARY' from 'CHAR',
'VARBINARY' from 'VARCHAR', and the
'BLOB' types from the 'TEXT' types.

If you cause the 'max_length' member of the 'MYSQL_FIELD' column
metadata structures to be set (by calling 'mysql_stmt_attr_set()'),
be aware that the 'max_length' values for the
result set indicate the lengths of the longest string representation of
the result values, not the lengths of the binary representation.  That
is, 'max_length' does not necessarily correspond to the size of the
buffers needed to fetch the values with the binary protocol used for
prepared statements.  Choose the size of the buffers according to the
types of the variables into which you fetch the values.  For example, a
'TINYINT' column containing the value -128 might have a 'max_length'
value of 4.  But the binary representation of any 'TINYINT' value
requires only 1 byte for storage, so you can supply a 'signed char'
variable in which to store the value and set 'is_unsigned' to indicate
that values are signed.

Metadata changes to tables or views referred to by prepared statements
are detected and cause automatic repreparation of the statement when it
is next executed.  For more information, see statement-caching.

27.8.10 C API Prepared Statement Function Overview
--------------------------------------------------

The following list summarizes the functions available for prepared
statement processing.  For greater detail, see the descriptions in
c-api-prepared-statement-functions.

   * 'mysql_stmt_affected_rows()'.:
     Returns the number of rows changed, deleted, or inserted by
     prepared 'UPDATE', 'DELETE', or
     'INSERT' statement

   * 'mysql_stmt_attr_get()'.: Gets value of
     an attribute for a prepared statement

   * 'mysql_stmt_attr_set()'.: Sets an
     attribute for a prepared statement

   * 'mysql_stmt_bind_param()'.: Associates
     application data buffers with the parameter markers in a prepared
     SQL statement

   * 'mysql_stmt_bind_result()'.:
     Associates application data buffers with columns in a result set

   * 'mysql_stmt_close()'.: Frees memory used by
     a prepared statement

   * 'mysql_stmt_data_seek()'.: Seeks to an
     arbitrary row number in a statement result set

   * 'mysql_stmt_errno()'.: Returns the error
     number for the last statement execution

   * 'mysql_stmt_error()'.: Returns the error
     message for the last statement execution

   * 'mysql_stmt_execute()'.: Executes a
     prepared statement

   * 'mysql_stmt_fetch()'.: Fetches the next row
     of data from a result set and returns data for all bound columns

   * 'mysql_stmt_fetch_column()'.: Fetch
     data for one column of the current row of a result set

   * 'mysql_stmt_field_count()'.: Returns
     the number of result columns for the most recent statement

   * 'mysql_stmt_free_result()'.: Free the
     resources allocated to a statement handler

   * 'mysql_stmt_init()'.: Allocates memory for a
     'MYSQL_STMT' structure and initializes it

   * 'mysql_stmt_insert_id()'.: Returns the
     ID generated for an 'AUTO_INCREMENT' column by a prepared statement

   * 'mysql_stmt_next_result()'.:
     Returns/initiates the next result in a multiple-result execution

   * 'mysql_stmt_num_rows()'.: Returns the
     row count from a buffered statement result set

   * 'mysql_stmt_param_count()'.: Returns
     the number of parameters in a prepared statement

   * 'mysql_stmt_param_metadata()'.:
     (Return parameter metadata in the form of a result set) This
     function does nothing

   * 'mysql_stmt_prepare()'.: Prepares an SQL
     statement string for execution

   * 'mysql_stmt_reset()'.: Resets the statement
     buffers in the server

   * 'mysql_stmt_result_metadata()'.:
     Returns prepared statement metadata in the form of a result set

   * 'mysql_stmt_row_seek()'.: Seeks to a row
     offset in a statement result set, using value returned from
     'mysql_stmt_row_tell()'.

   * 'mysql_stmt_row_tell()'.: Returns the
     statement row cursor position

   * 'mysql_stmt_send_long_data()'.:
     Sends long data in chunks to server

   * 'mysql_stmt_sqlstate()'.: Returns the
     SQLSTATE error code for the last statement execution

   * 'mysql_stmt_store_result()'.:
     Retrieves a complete result set to the client

Call 'mysql_stmt_init()' to create a statement
handler, then 'mysql_stmt_prepare()' to
prepare the statement string, see 'mysql_stmt_bind_param()'
to supply the parameter data, and
'mysql_stmt_execute()' to execute the statement.
You can repeat the 'mysql_stmt_execute()' by
changing parameter values in the respective buffers supplied through
'mysql_stmt_bind_param()'.

You can send text or binary data in chunks to server using
'mysql_stmt_send_long_data()'.  See
mysql-stmt-send-long-data.

If the statement is a 'SELECT' or any other statement
that produces a result set, see 'mysql_stmt_prepare()'
also returns the result set metadata information in
the form of a 'MYSQL_RES' result set through
'mysql_stmt_result_metadata()'.

You can supply the result buffers using
'mysql_stmt_bind_result()', so that the
'mysql_stmt_fetch()' automatically returns data to
these buffers.  This is row-by-row fetching.

When statement execution has been completed, close the statement handler
using 'mysql_stmt_close()' so that all
resources associated with it can be freed.  At that point the handler
becomes invalid and should no longer be used.

If you obtained a 'SELECT' statement's result set
metadata by calling 'mysql_stmt_result_metadata()',
you should also free the metadata using
'mysql_free_result()'.

*Execution Steps*

To prepare and execute a statement, an application follows these steps:

  1. Create a prepared statement handler with 'mysql_stmt_init()'.
     To prepare the statement on the server, call
     'mysql_stmt_prepare()' and pass it a
     string containing the SQL statement.

  2. If the statement will produce a result set, call
     'mysql_stmt_result_metadata()' to
     obtain the result set metadata.  This metadata is itself in the
     form of result set, albeit a separate one from the one that
     contains the rows returned by the query.  The metadata result set
     indicates how many columns are in the result and contains
     information about each column.

  3. Set the values of any parameters using
     'mysql_stmt_bind_param()'.  All parameters
     must be set.  Otherwise, statement execution returns an error or
     produces unexpected results.

  4. Call 'mysql_stmt_execute()' to execute
     the statement.

  5. If the statement produces a result set, bind the data buffers to
     use for retrieving the row values by calling
     'mysql_stmt_bind_result()'.

  6. Fetch the data into the buffers row by row by calling
     'mysql_stmt_fetch()' repeatedly until no more
     rows are found.

  7. Repeat steps 3 through 6 as necessary, by changing the parameter
     values and re-executing the statement.

When 'mysql_stmt_prepare()' is called, the
MySQL client/server protocol performs these actions:

   * The server parses the statement and sends the okay status back to
     the client by assigning a statement ID. It also sends total number
     of parameters, a column count, and its metadata if it is a result
     set oriented statement.  All syntax and semantics of the statement
     are checked by the server during this call.

   * The client uses this statement ID for the further operations, so
     that the server can identify the statement from among its pool of
     statements.

When 'mysql_stmt_execute()' is called, the
MySQL client/server protocol performs these actions:

   * The client uses the statement handler and sends the parameter data
     to the server.

   * The server identifies the statement using the ID provided by the
     client, replaces the parameter markers with the newly supplied
     data, and executes the statement.  If the statement produces a
     result set, the server sends the data back to the client.
     Otherwise, it sends an okay status and the number of rows changed,
     deleted, or inserted.

When 'mysql_stmt_fetch()' is called, the MySQL
client/server protocol performs these actions:

   * The client reads the data from the current row of the result set
     and places it into the application data buffers by doing the
     necessary conversions.  If the application buffer type is same as
     that of the field type returned from the server, the conversions
     are straightforward.

If an error occurs, you can get the statement error number, error
message, and SQLSTATE code using 'mysql_stmt_errno()',
see 'mysql_stmt_error()', and
'mysql_stmt_sqlstate()', respectively.

*Prepared Statement Logging*

For prepared statements that are executed with the
'mysql_stmt_prepare()' and
'mysql_stmt_execute()'. C API functions, the server
writes 'Prepare' and 'Execute' lines to the general query log so that
you can tell when statements are prepared and executed.

Suppose that you prepare and execute a statement as follows:

  1. Call 'mysql_stmt_prepare()' to prepare
     the statement string '"SELECT ?"'.

  2. Call 'mysql_stmt_bind_param()' to
     bind the value '3' to the parameter in the prepared statement.

  3. Call 'mysql_stmt_execute()' to execute
     the prepared statement.

As a result of the preceding calls, the server writes the following
lines to the general query log:

     Prepare  [1] SELECT ?
     Execute  [1] SELECT 3

Each 'Prepare' and 'Execute' line in the log is tagged with a '[N]'
statement identifier so that you can keep track of which prepared
statement is being logged.  N is a positive integer.  If there are
multiple prepared statements active simultaneously for the client, N may
be greater than 1.  Each 'Execute' lines shows a prepared statement
after substitution of data values for '?' parameters.

27.8.11 C API Prepared Statement Function Descriptions
------------------------------------------------------

To prepare and execute queries, use the functions described in detail in
the following sections.

All functions that operate with a 'MYSQL_STMT' structure begin with the
prefix 'mysql_stmt_'.

To create a 'MYSQL_STMT' handler, use the 'mysql_stmt_init()'
function.

27.8.11.1 mysql_stmt_affected_rows()
....................................

'my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)'

*Description*

'mysql_stmt_affected_rows()' may be
called immediately after executing a statement with
'mysql_stmt_execute()'.  It is like
'mysql_affected_rows()' but for prepared
statements.  For a description of what the affected-rows value returned
by this function means, See mysql-affected-rows.

*Errors*

None.

*Example*

See the Example in mysql-stmt-execute.

27.8.11.2 mysql_stmt_attr_get()
...............................

'my_bool mysql_stmt_attr_get(MYSQL_STMT *stmt, enum enum_stmt_attr_type
option, void *arg)'

*Description*

Can be used to get the current value for a statement attribute.

The 'option' argument is the option that you want to get; the 'arg'
should point to a variable that should contain the option value.  If the
option is an integer, 'arg' should point to the value of the integer.

See mysql-stmt-attr-set, for a list of options and option types.

*Return Values*

Zero for success.  Nonzero if 'option' is unknown.

*Errors*

None.

27.8.11.3 mysql_stmt_attr_set()
...............................

'my_bool mysql_stmt_attr_set(MYSQL_STMT *stmt, enum enum_stmt_attr_type
option, const void *arg)'

*Description*

Can be used to affect behavior for a prepared statement.  This function
may be called multiple times to set several options.

The 'option' argument is the option that you want to set.  The 'arg'
argument is the value for the option.  'arg' should point to a variable
that is set to the desired attribute value.  The variable type is as
indicated in the following table.

The following table shows the possible 'option' values.

Option                         Argument       Function
                               Type

'STMT_ATTR_UPDATE_MAX_LENGTH'  'my_bool *'    If set to 1, causes
                                              'mysql_stmt_store_result()'.
                                              to update the metadata
                                              'MYSQL_FIELD->max_length'
                                              value.

'STMT_ATTR_CURSOR_TYPE'        'unsigned      Type of cursor to open
                               long *'        for statement when
                                              'mysql_stmt_execute()'
                                        is
                                              invoked.  '*arg' can be
                                              'CURSOR_TYPE_NO_CURSOR'
                                              (the default) or
                                              'CURSOR_TYPE_READ_ONLY'.

'STMT_ATTR_PREFETCH_ROWS'      'unsigned      Number of rows to fetch
                               long *'        from server at a time
                                              when using a cursor.
                                              '*arg' can be in the
                                              range from 1 to the
                                              maximum value of
                                              'unsigned long'.  The
                                              default is 1.

If you use the 'STMT_ATTR_CURSOR_TYPE' option with
'CURSOR_TYPE_READ_ONLY', a cursor is opened for the statement when you
invoke 'mysql_stmt_execute()'.  If there is
already an open cursor from a previous 'mysql_stmt_execute()'
call, it closes the cursor before opening a new one.
'mysql_stmt_reset()' also closes any open
cursor before preparing the statement for re-execution.
'mysql_stmt_free_result()' closes any open
cursor.

If you open a cursor for a prepared statement, see
'mysql_stmt_store_result()' is unnecessary,
because that function causes the result set to be buffered on the client
side.

*Return Values*

Zero for success.  Nonzero if 'option' is unknown.

*Errors*

None.

*Example*

The following example opens a cursor for a prepared statement and sets
the number of rows to fetch at a time to 5:

     MYSQL_STMT *stmt;
     int rc;
     unsigned long type;
     unsigned long prefetch_rows = 5;

     stmt = mysql_stmt_init(mysql);
     type = (unsigned long) CURSOR_TYPE_READ_ONLY;
     rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &type);
     /* ... check return value ... */
     rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS,
                              (void*) &prefetch_rows);
     /* ... check return value ... */

27.8.11.4 mysql_stmt_bind_param()
.................................

'my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)'

*Description*

'mysql_stmt_bind_param()' is used to bind
input data for the parameter markers in the SQL statement that was
passed to 'mysql_stmt_prepare()'.  It uses
'MYSQL_BIND' structures to supply the data.  'bind' is the address of an
array of 'MYSQL_BIND' structures.  The client library expects the array
to contain one element for each '?' parameter marker that is present in
the query.

Suppose that you prepare the following statement:

     INSERT INTO mytbl VALUES(?,?,?)

When you bind the parameters, the array of 'MYSQL_BIND' structures must
contain three elements, and can be declared like this:

     MYSQL_BIND bind[3];

See c-api-prepared-statement-data-structures, describes the members
of each 'MYSQL_BIND' element and how they should be set to provide input
values.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_UNSUPPORTED_PARAM_TYPE'

     The conversion is not supported.  Possibly the 'buffer_type' value
     is invalid or is not one of the supported types.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

See the Example in mysql-stmt-execute.

27.8.11.5 mysql_stmt_bind_result()
..................................

'my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)'

*Description*

'mysql_stmt_bind_result()' is used to
associate (that is, bind) output columns in the result set to data
buffers and length buffers.  When 'mysql_stmt_fetch()'
is called to fetch data, the MySQL client/server
protocol places the data for the bound columns into the specified
buffers.

All columns must be bound to buffers prior to calling
'mysql_stmt_fetch()'.  'bind' is the address of an
array of 'MYSQL_BIND' structures.  The client library expects the array
to contain one element for each column of the result set.  If you do not
bind columns to 'MYSQL_BIND' structures, see 'mysql_stmt_fetch()'
simply ignores the data fetch.  The buffers should be
large enough to hold the data values, because the protocol does not
return data values in chunks.

A column can be bound or rebound at any time, even after a result set
has been partially retrieved.  The new binding takes effect the next
time 'mysql_stmt_fetch()' is called.  Suppose
that an application binds the columns in a result set and calls
'mysql_stmt_fetch()'.  The client/server protocol
returns data in the bound buffers.  Then suppose that the application
binds the columns to a different set of buffers.  The protocol places
data into the newly bound buffers when the next call to
'mysql_stmt_fetch()' occurs.

To bind a column, an application calls 'mysql_stmt_bind_result()'
and passes the type, address, and length of the
output buffer into which the value should be stored.  See
c-api-prepared-statement-data-structures, describes the members of
each 'MYSQL_BIND' element and how they should be set to receive output
values.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_UNSUPPORTED_PARAM_TYPE'

     The conversion is not supported.  Possibly the 'buffer_type' value
     is invalid or is not one of the supported types.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

See the Example in mysql-stmt-fetch.

27.8.11.6 mysql_stmt_close()
............................

'my_bool mysql_stmt_close(MYSQL_STMT *stmt)'

*Description*

Closes the prepared statement.  'mysql_stmt_close()'
also deallocates the statement handler pointed to by
'stmt', which at that point becomes invalid and should no longer be
used.  For a failed 'mysql_stmt_close()' call,
do not call 'mysql_stmt_error()', or
'mysql_stmt_errno()', or
'mysql_stmt_sqlstate()' to obtain error
information because 'mysql_stmt_close()' makes
the statement handler invalid.  Call 'mysql_error()',
'mysql_errno()', or 'mysql_sqlstate()'
instead.

If the current statement has pending or unread results, this function
cancels them so that the next query can be executed.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

See the Example in mysql-stmt-execute.

27.8.11.7 mysql_stmt_data_seek()
................................

'void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)'

*Description*

Seeks to an arbitrary row in a statement result set.  The 'offset' value
is a row number and should be in the range from '0' to
'mysql_stmt_num_rows(stmt)-1'.

This function requires that the statement result set structure contains
the entire result of the last executed query, so
'mysql_stmt_data_seek()' may be used only in
conjunction with 'mysql_stmt_store_result()'.

*Return Values*

None.

*Errors*

None.

27.8.11.8 mysql_stmt_errno()
............................

'unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)'

*Description*

For the statement specified by 'stmt', see 'mysql_stmt_errno()'
returns the error code for the most recently invoked
statement API function that can succeed or fail.  A return value of zero
means that no error occurred.  Client error message numbers are listed
in the MySQL 'errmsg.h' header file.  Server error message numbers are
listed in 'mysqld_error.h'.  Errors also are listed at
error-handling.

If the failed statement API function was 'mysql_stmt_close()',
do not call or 'mysql_stmt_errno()'
to obtain error information because
'mysql_stmt_close()' makes the statement handler
invalid.  Call 'mysql_errno()' instead.

*Return Values*

An error code value.  Zero if no error occurred.

*Errors*

None.

27.8.11.9 mysql_stmt_error()
............................

'const char *mysql_stmt_error(MYSQL_STMT *stmt)'

*Description*

For the statement specified by 'stmt', see 'mysql_stmt_error()'
returns a null-terminated string containing the error
message for the most recently invoked statement API function that can
succeed or fail.  An empty string ('""') is returned if no error
occurred.  Either of these two tests can be used to check for an error:

     if(*mysql_stmt_errno(stmt))
     {
       // an error occurred
     }

     if (mysql_stmt_error(stmt)[0])
     {
       // an error occurred
     }

If the failed statement API function was 'mysql_stmt_close()',
do not call 'mysql_stmt_error()'
to obtain error information because
'mysql_stmt_close()' makes the statement handler
invalid.  Call 'mysql_error()' instead.

The language of the client error messages may be changed by recompiling
the MySQL client library.  You can choose error messages in several
different languages.

*Return Values*

A character string that describes the error.  An empty string if no
error occurred.

*Errors*

None.

27.8.11.10 mysql_stmt_execute()
...............................

'int mysql_stmt_execute(MYSQL_STMT *stmt)'

*Description*

'mysql_stmt_execute()' executes the prepared
query associated with the statement handler.  The currently bound
parameter marker values are sent to server during this call, and the
server replaces the markers with this newly supplied data.

Statement processing following 'mysql_stmt_execute()'
depends on the type of statement:

   * For an 'UPDATE', 'DELETE', or
     'INSERT', the number of changed, deleted, or inserted rows
     can be found by calling 'mysql_stmt_affected_rows()'.

   * For a statement such as 'SELECT' that generates a
     result set, you must call 'mysql_stmt_fetch()'
     to fetch the data prior to calling any other
     functions that result in query processing.  For more information on
     how to fetch the results, refer to mysql-stmt-fetch.

     Do not following invocation of 'mysql_stmt_execute()'
     with a call to 'mysql_store_result()'
     or 'mysql_use_result()'.
     Those functions are not intended for processing
     results from prepared statements.

For statements that generate a result set, you can request that
'mysql_stmt_execute()' open a cursor for the
statement by calling 'mysql_stmt_attr_set()'.
before executing the statement.  If you execute a statement multiple
times, see 'mysql_stmt_execute()' closes any open
cursor before opening a new one.

Metadata changes to tables or views referred to by prepared statements
are detected and cause automatic repreparation of the statement when it
is next executed.  For more information, see statement-caching.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

The following example demonstrates how to create and populate a table
using 'mysql_stmt_init()',
'mysql_stmt_prepare()',
'mysql_stmt_param_count()',
'mysql_stmt_bind_param()',
'mysql_stmt_execute()', and
'mysql_stmt_affected_rows()'.  The 'mysql'
variable is assumed to be a valid connection handler.  For an example
that shows how to retrieve data, see mysql-stmt-fetch.

     #define STRING_SIZE 50

     #define DROP_SAMPLE_TABLE "DROP TABLE IF EXISTS test_table"
     #define CREATE_SAMPLE_TABLE "CREATE TABLE test_table(col1 INT,\
                                                      col2 VARCHAR(40),\
                                                      col3 SMALLINT,\
                                                      col4 TIMESTAMP)"
     #define INSERT_SAMPLE "INSERT INTO \
                            test_table(col1,col2,col3) \
                            VALUES(?,?,?)"

     MYSQL_STMT    *stmt;
     MYSQL_BIND    bind[3];
     my_ulonglong  affected_rows;
     int           param_count;
     short         small_data;
     int           int_data;
     char          str_data[STRING_SIZE];
     unsigned long str_length;
     my_bool       is_null;

     if (mysql_query(mysql, DROP_SAMPLE_TABLE))
     {
       fprintf(stderr, " DROP TABLE failed\n");
       fprintf(stderr, " %s\n", mysql_error(mysql));
       exit(0);
     }

     if (mysql_query(mysql, CREATE_SAMPLE_TABLE))
     {
       fprintf(stderr, " CREATE TABLE failed\n");
       fprintf(stderr, " %s\n", mysql_error(mysql));
       exit(0);
     }

     /* Prepare an INSERT query with 3 parameters */
     /* (the TIMESTAMP column is not named; the server */
     /*  sets it to the current date and time) */
     stmt = mysql_stmt_init(mysql);
     if (!stmt)
     {
       fprintf(stderr, " mysql_stmt_init(), out of memory\n");
       exit(0);
     }
     if (mysql_stmt_prepare(stmt, INSERT_SAMPLE, strlen(INSERT_SAMPLE)))
     {
       fprintf(stderr, " mysql_stmt_prepare(), INSERT failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }
     fprintf(stdout, " prepare, INSERT successful\n");

     /* Get the parameter count from the statement */
     param_count= mysql_stmt_param_count(stmt);
     fprintf(stdout, " total parameters in INSERT: %d\n", param_count);

     if (param_count != 3) /* validate parameter count */
     {
       fprintf(stderr, " invalid parameter count returned by MySQL\n");
       exit(0);
     }

     /* Bind the data for all 3 parameters */

     memset(bind, 0, sizeof(bind));

     /* INTEGER PARAM */
     /* This is a number type, so there is no need
        to specify buffer_length */
     bind[0].buffer_type= MYSQL_TYPE_LONG;
     bind[0].buffer= (char *)&int_data;
     bind[0].is_null= 0;
     bind[0].length= 0;

     /* STRING PARAM */
     bind[1].buffer_type= MYSQL_TYPE_STRING;
     bind[1].buffer= (char *)str_data;
     bind[1].buffer_length= STRING_SIZE;
     bind[1].is_null= 0;
     bind[1].length= &str_length;

     /* SMALLINT PARAM */
     bind[2].buffer_type= MYSQL_TYPE_SHORT;
     bind[2].buffer= (char *)&small_data;
     bind[2].is_null= &is_null;
     bind[2].length= 0;

     /* Bind the buffers */
     if (mysql_stmt_bind_param(stmt, bind))
     {
       fprintf(stderr, " mysql_stmt_bind_param() failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }

     /* Specify the data values for the first row */
     int_data= 10;             /* integer */
     strncpy(str_data, "MySQL", STRING_SIZE); /* string  */
     str_length= strlen(str_data);

     /* INSERT SMALLINT data as NULL */
     is_null= 1;

     /* Execute the INSERT statement - 1*/
     if (mysql_stmt_execute(stmt))
     {
       fprintf(stderr, " mysql_stmt_execute(), 1 failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }

     /* Get the number of affected rows */
     affected_rows= mysql_stmt_affected_rows(stmt);
     fprintf(stdout, " total affected rows(insert 1): %lu\n",
                     (unsigned long) affected_rows);

     if (affected_rows != 1) /* validate affected rows */
     {
       fprintf(stderr, " invalid affected rows by MySQL\n");
       exit(0);
     }

     /* Specify data values for second row,
        then re-execute the statement */
     int_data= 1000;
     strncpy(str_data, "
             The most popular Open Source database",
             STRING_SIZE);
     str_length= strlen(str_data);
     small_data= 1000;         /* smallint */
     is_null= 0;               /* reset */

     /* Execute the INSERT statement - 2*/
     if (mysql_stmt_execute(stmt))
     {
       fprintf(stderr, " mysql_stmt_execute, 2 failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }

     /* Get the total rows affected */
     affected_rows= mysql_stmt_affected_rows(stmt);
     fprintf(stdout, " total affected rows(insert 2): %lu\n",
                     (unsigned long) affected_rows);

     if (affected_rows != 1) /* validate affected rows */
     {
       fprintf(stderr, " invalid affected rows by MySQL\n");
       exit(0);
     }

     /* Close the statement */
     if (mysql_stmt_close(stmt))
     {
       /* mysql_stmt_close() invalidates stmt, so call          */
       /* mysql_error(mysql) rather than mysql_stmt_error(stmt) */
       fprintf(stderr, " failed while closing the statement\n");
       fprintf(stderr, " %s\n", mysql_error(mysql));
       exit(0);
     }

*Note*:

For complete examples on the use of prepared statement functions, refer
to the file 'tests/mysql_client_test.c'.  This file can be obtained from
a MySQL source distribution or from the source repository (see
source-installation).

27.8.11.11 mysql_stmt_fetch()
.............................

'int mysql_stmt_fetch(MYSQL_STMT *stmt)'

*Description*

'mysql_stmt_fetch()' returns the next row in
the result set.  It can be called only while the result set exists; that
is, after a call to 'mysql_stmt_execute()'.
for a statement such as 'SELECT' that produces a result
set.

'mysql_stmt_fetch()' returns row data using the
buffers bound by 'mysql_stmt_bind_result()'.
It returns the data in those buffers for all
the columns in the current row set and the lengths are returned to the
'length' pointer.  All columns must be bound by the application before
it calls 'mysql_stmt_fetch()'.

By default, result sets are fetched unbuffered a row at a time from the
server.  To buffer the entire result set on the client, call
'mysql_stmt_store_result()' after binding the
data buffers and before calling 'mysql_stmt_fetch()'.

If a fetched data value is a 'NULL' value, the '*is_null' value of the
corresponding 'MYSQL_BIND' structure contains TRUE (1).  Otherwise, the
data and its length are returned in the '*buffer' and '*length' elements
based on the buffer type specified by the application.  Each numeric and
temporal type has a fixed length, as listed in the following table.  The
length of the string types depends on the length of the actual data
value, as indicated by 'data_length'.

Type                                 Length

'MYSQL_TYPE_TINY'                    1

'MYSQL_TYPE_SHORT'                   2

'MYSQL_TYPE_LONG'                    4

'MYSQL_TYPE_LONGLONG'                8

'MYSQL_TYPE_FLOAT'                   4

'MYSQL_TYPE_DOUBLE'                  8

'MYSQL_TYPE_TIME'                    'sizeof(MYSQL_TIME)'

'MYSQL_TYPE_DATE'                    'sizeof(MYSQL_TIME)'

'MYSQL_TYPE_DATETIME'                'sizeof(MYSQL_TIME)'

'MYSQL_TYPE_STRING'                  'data length'

'MYSQL_TYPE_BLOB'                    'data_length'

In some cases you might want to determine the length of a column value
before fetching it with 'mysql_stmt_fetch()'.
For example, the value might be a long string or 'BLOB'.
value for which you want to know how much space must be allocated.  To
accomplish this, you can use these strategies:

   * Before invoking 'mysql_stmt_fetch()' to
     retrieve individual rows, pass 'STMT_ATTR_UPDATE_MAX_LENGTH' to
     'mysql_stmt_attr_set()', then invoke
     'mysql_stmt_store_result()' to
     buffer the entire result on the client side.  Setting the
     'STMT_ATTR_UPDATE_MAX_LENGTH' attribute causes the maximal length
     of column values to be indicated by the 'max_length' member of the
     result set metadata returned by
     'mysql_stmt_result_metadata()'.

   * Invoke 'mysql_stmt_fetch()' with a
     zero-length buffer for the column in question and a pointer in
     which the real length can be stored.  Then use the real length with
     'mysql_stmt_fetch_column()'.

          real_length= 0;

          bind[0].buffer= 0;
          bind[0].buffer_length= 0;
          bind[0].length= &real_length
          mysql_stmt_bind_result(stmt, bind);

          mysql_stmt_fetch(stmt);
          if (real_length > 0)
          {
            data= malloc(real_length);
            bind[0].buffer= data;
            bind[0].buffer_length= real_length;
            mysql_stmt_fetch_column(stmt, bind, 0, 0);
          }

*Return Values*

Return Value              Description

0                         Successful, the data has been fetched to
                          application data buffers.

1                         Error occurred.  Error code and message can
                          be obtained by calling
                          'mysql_stmt_errno()' and
                          'mysql_stmt_error()'.

'MYSQL_NO_DATA'           No more rows/data exists

'MYSQL_DATA_TRUNCATED'    Data truncation occurred

'MYSQL_DATA_TRUNCATED' is returned when truncation reporting is enabled.
To determine which column values were truncated when this value is
returned, check the 'error' members of the 'MYSQL_BIND' structures used
for fetching values.  Truncation reporting is enabled by default, but
can be controlled by calling 'mysql_options()'.
with the 'MYSQL_REPORT_DATA_TRUNCATION' option.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

   * 'CR_UNSUPPORTED_PARAM_TYPE'

     The buffer type is 'MYSQL_TYPE_DATE', 'MYSQL_TYPE_TIME',
     'MYSQL_TYPE_DATETIME', or 'MYSQL_TYPE_TIMESTAMP', but the data type
     is not 'DATE', 'TIME',
     'DATETIME', or 'TIMESTAMP'.

   * All other unsupported conversion errors are returned from
     'mysql_stmt_bind_result()'.

*Example*

The following example demonstrates how to fetch data from a table using
'mysql_stmt_result_metadata()',
'mysql_stmt_bind_result()', and
'mysql_stmt_fetch()'.  (This example expects to
retrieve the two rows inserted by the example shown in
mysql-stmt-execute.)  The 'mysql' variable is assumed to be a valid
connection handler.

     #define STRING_SIZE 50

     #define SELECT_SAMPLE "SELECT col1, col2, col3, col4 \
                            FROM test_table"

     MYSQL_STMT    *stmt;
     MYSQL_BIND    bind[4];
     MYSQL_RES     *prepare_meta_result;
     MYSQL_TIME    ts;
     unsigned long length[4];
     int           param_count, column_count, row_count;
     short         small_data;
     int           int_data;
     char          str_data[STRING_SIZE];
     my_bool       is_null[4];
     my_bool       error[4];

     /* Prepare a SELECT query to fetch data from test_table */
     stmt = mysql_stmt_init(mysql);
     if (!stmt)
     {
       fprintf(stderr, " mysql_stmt_init(), out of memory\n");
       exit(0);
     }
     if (mysql_stmt_prepare(stmt, SELECT_SAMPLE, strlen(SELECT_SAMPLE)))
     {
       fprintf(stderr, " mysql_stmt_prepare(), SELECT failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }
     fprintf(stdout, " prepare, SELECT successful\n");

     /* Get the parameter count from the statement */
     param_count= mysql_stmt_param_count(stmt);
     fprintf(stdout, " total parameters in SELECT: %d\n", param_count);

     if (param_count != 0) /* validate parameter count */
     {
       fprintf(stderr, " invalid parameter count returned by MySQL\n");
       exit(0);
     }

     /* Fetch result set meta information */
     prepare_meta_result = mysql_stmt_result_metadata(stmt);
     if (!prepare_meta_result)
     {
       fprintf(stderr,
              " mysql_stmt_result_metadata(), \
                returned no meta information\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }

     /* Get total columns in the query */
     column_count= mysql_num_fields(prepare_meta_result);
     fprintf(stdout,
             " total columns in SELECT statement: %d\n",
             column_count);

     if (column_count != 4) /* validate column count */
     {
       fprintf(stderr, " invalid column count returned by MySQL\n");
       exit(0);
     }

     /* Execute the SELECT query */
     if (mysql_stmt_execute(stmt))
     {
       fprintf(stderr, " mysql_stmt_execute(), failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }

     /* Bind the result buffers for all 4 columns before fetching them */

     memset(bind, 0, sizeof(bind));

     /* INTEGER COLUMN */
     bind[0].buffer_type= MYSQL_TYPE_LONG;
     bind[0].buffer= (char *)&int_data;
     bind[0].is_null= &is_null[0];
     bind[0].length= &length[0];
     bind[0].error= &error[0];

     /* STRING COLUMN */
     bind[1].buffer_type= MYSQL_TYPE_STRING;
     bind[1].buffer= (char *)str_data;
     bind[1].buffer_length= STRING_SIZE;
     bind[1].is_null= &is_null[1];
     bind[1].length= &length[1];
     bind[1].error= &error[1];

     /* SMALLINT COLUMN */
     bind[2].buffer_type= MYSQL_TYPE_SHORT;
     bind[2].buffer= (char *)&small_data;
     bind[2].is_null= &is_null[2];
     bind[2].length= &length[2];
     bind[2].error= &error[2];

     /* TIMESTAMP COLUMN */
     bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
     bind[3].buffer= (char *)&ts;
     bind[3].is_null= &is_null[3];
     bind[3].length= &length[3];
     bind[3].error= &error[3];

     /* Bind the result buffers */
     if (mysql_stmt_bind_result(stmt, bind))
     {
       fprintf(stderr, " mysql_stmt_bind_result() failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }

     /* Now buffer all results to client (optional step) */
     if (mysql_stmt_store_result(stmt))
     {
       fprintf(stderr, " mysql_stmt_store_result() failed\n");
       fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
       exit(0);
     }

     /* Fetch all rows */
     row_count= 0;
     fprintf(stdout, "Fetching results ...\n");
     while (!mysql_stmt_fetch(stmt))
     {
       row_count++;
       fprintf(stdout, "  row %d\n", row_count);

       /* column 1 */
       fprintf(stdout, "   column1 (integer)  : ");
       if (is_null[0])
         fprintf(stdout, " NULL\n");
       else
         fprintf(stdout, " %d(%ld)\n", int_data, length[0]);

       /* column 2 */
       fprintf(stdout, "   column2 (string)   : ");
       if (is_null[1])
         fprintf(stdout, " NULL\n");
       else
         fprintf(stdout, " %s(%ld)\n", str_data, length[1]);

       /* column 3 */
       fprintf(stdout, "   column3 (smallint) : ");
       if (is_null[2])
         fprintf(stdout, " NULL\n");
       else
         fprintf(stdout, " %d(%ld)\n", small_data, length[2]);

       /* column 4 */
       fprintf(stdout, "   column4 (timestamp): ");
       if (is_null[3])
         fprintf(stdout, " NULL\n");
       else
         fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n",
                          ts.year, ts.month, ts.day,
                          ts.hour, ts.minute, ts.second,
                          length[3]);
       fprintf(stdout, "\n");
     }

     /* Validate rows fetched */
     fprintf(stdout, " total rows fetched: %d\n", row_count);
     if (row_count != 2)
     {
       fprintf(stderr, " MySQL failed to return all rows\n");
       exit(0);
     }

     /* Free the prepared result metadata */
     mysql_free_result(prepare_meta_result);

     /* Close the statement */
     if (mysql_stmt_close(stmt))
     {
       /* mysql_stmt_close() invalidates stmt, so call          */
       /* mysql_error(mysql) rather than mysql_stmt_error(stmt) */
       fprintf(stderr, " failed while closing the statement\n");
       fprintf(stderr, " %s\n", mysql_error(mysql));
       exit(0);
     }

27.8.11.12 mysql_stmt_fetch_column()
....................................

'int mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind,
unsigned int column, unsigned long offset)'

*Description*

Fetches one column from the current result set row.  'bind' provides the
buffer where data should be placed.  It should be set up the same way as
for 'mysql_stmt_bind_result()'.  'column'
indicates which column to fetch.  The first column is numbered 0.
'offset' is the offset within the data value at which to begin
retrieving data.  This can be used for fetching the data value in
pieces.  The beginning of the value is offset 0.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_INVALID_PARAMETER_NO'

     Invalid column number.

   * 'CR_NO_DATA'

     The end of the result set has already been reached.

27.8.11.13 mysql_stmt_field_count()
...................................

'unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)'

*Description*

Returns the number of columns for the most recent statement for the
statement handler.  This value is zero for statements such as
'INSERT' or 'DELETE' that do not produce result
sets.

'mysql_stmt_field_count()' can be called
after you have prepared a statement by invoking
'mysql_stmt_prepare()'.

*Return Values*

An unsigned integer representing the number of columns in a result set.

*Errors*

None.

27.8.11.14 mysql_stmt_free_result()
...................................

'my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)'

*Description*

Releases memory associated with the result set produced by execution of
the prepared statement.  If there is a cursor open for the statement,
see 'mysql_stmt_free_result()' closes it.

*Return Values*

Zero for success.  Nonzero if an error occurred.

27.8.11.15 mysql_stmt_init()
............................

'MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)'

*Description*

Creates and returns a 'MYSQL_STMT' handler.  The handler should be freed
with 'mysql_stmt_close()', at which point the
handler becomes invalid and should no longer be used.

See also c-api-prepared-statement-data-structures, for more
information.

*Return Values*

A pointer to a 'MYSQL_STMT' structure in case of success.  'NULL' if out
of memory.

*Errors*

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

27.8.11.16 mysql_stmt_insert_id()
.................................

'my_ulonglong mysql_stmt_insert_id(MYSQL_STMT *stmt)'

*Description*

Returns the value generated for an 'AUTO_INCREMENT' column by the
prepared 'INSERT' or 'UPDATE' statement.
Use this function after you have executed a prepared 'INSERT'
statement on a table which contains an 'AUTO_INCREMENT' field.

See mysql-insert-id, for more information.

*Return Values*

Value for 'AUTO_INCREMENT' column which was automatically generated or
explicitly set during execution of prepared statement, or value
generated by 'LAST_INSERT_ID(EXPR)' function.  Return value is undefined
if statement does not set 'AUTO_INCREMENT' value.

*Errors*

None.

27.8.11.17 mysql_stmt_next_result()
...................................

'int mysql_stmt_next_result(MYSQL_STMT *mysql)'

*Description*

This function is used when you use prepared 'CALL'.
statements to execute stored procedures, which can return multiple
result sets.  Use a loop that calls 'mysql_stmt_next_result()'
to determine whether there are more results.  If
a procedure has 'OUT' or 'INOUT' parameters, their values will be
returned as a single-row result set following any other result sets.
The values will appear in the order in which they are declared in the
procedure parameter list.

'mysql_stmt_next_result()' returns a
status to indicate whether more results exist.  If
'mysql_stmt_next_result()' returns an error,
there are no more results.

Before each call to 'mysql_stmt_next_result()',
you must call 'mysql_stmt_free_result()'
for the current result if it produced a result
set (rather than just a result status).

After calling 'mysql_stmt_next_result()'.
the state of the connection is as if you had called
'mysql_stmt_execute()'.  This means that you can
call 'mysql_stmt_bind_result()',
'mysql_stmt_affected_rows()', and so forth.

It is also possible to test whether there are more results by calling
'mysql_more_results()'.  However, this
function does not change the connection state, so if it returns true,
you must still call 'mysql_stmt_next_result()'
to advance to the next result.

For an example that shows how to use 'mysql_stmt_next_result()',
see c-api-prepared-call-statements.

*Return Values*

Return Value              Description

0                         Successful and there are more results

-1                        Successful and there are no more results

>0                        An error occurred

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.11.18 mysql_stmt_num_rows()
................................

'my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)'

*Description*

Returns the number of rows in the result set.

The use of 'mysql_stmt_num_rows()' depends
on whether you used 'mysql_stmt_store_result()'
to buffer the entire result set in the
statement handler.  If you use 'mysql_stmt_store_result()',
see 'mysql_stmt_num_rows()'
may be called immediately.  Otherwise, the row
count is unavailable unless you count the rows as you fetch them.

'mysql_stmt_num_rows()' is intended for use
with statements that return a result set, such as 'SELECT'.
For statements such as 'INSERT', 'UPDATE',
or 'DELETE', the number of affected rows can be
obtained with 'mysql_stmt_affected_rows()'.

*Return Values*

The number of rows in the result set.

*Errors*

None.

27.8.11.19 mysql_stmt_param_count()
...................................

'unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)'

*Description*

Returns the number of parameter markers present in the prepared
statement.

*Return Values*

An unsigned long integer representing the number of parameters in a
statement.

*Errors*

None.

*Example*

See the Example in mysql-stmt-execute.

27.8.11.20 mysql_stmt_param_metadata()
......................................

'MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)'

This function currently does nothing.

27.8.11.21 mysql_stmt_prepare()
...............................

'int mysql_stmt_prepare(MYSQL_STMT *stmt, const char *stmt_str, unsigned
long length)'

*Description*

Given the statement handler returned by 'mysql_stmt_init()',
prepares the SQL statement pointed to by the string
'stmt_str' and returns a status value.  The string length should be
given by the 'length' argument.  The string must consist of a single SQL
statement.  You should not add a terminating semicolon (';') or '\g' to
the statement.

The application can include one or more parameter markers in the SQL
statement by embedding question mark ('?') characters into the SQL
string at the appropriate positions.

The markers are legal only in certain places in SQL statements.  For
example, they are permitted in the 'VALUES()' list of an 'INSERT'
statement (to specify column values for a row), or in a
comparison with a column in a 'WHERE' clause to specify a comparison
value.  However, they are not permitted for identifiers (such as table
or column names), or to specify both operands of a binary operator such
as the '=' equal sign.  The latter restriction is necessary because it
would be impossible to determine the parameter type.  In general,
parameters are legal only in Data Manipulation Language (DML)
statements, and not in Data Definition Language (DDL) statements.

The parameter markers must be bound to application variables using
'mysql_stmt_bind_param()' before executing the
statement.

Metadata changes to tables or views referred to by prepared statements
are detected and cause automatic repreparation of the statement when it
is next executed.  For more information, see statement-caching.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

If the prepare operation was unsuccessful (that is, see
'mysql_stmt_prepare()' returns nonzero), the error
message can be obtained by calling 'mysql_stmt_error()'.

*Example*

See the Example in mysql-stmt-execute.

27.8.11.22 mysql_stmt_reset()
.............................

'my_bool mysql_stmt_reset(MYSQL_STMT *stmt)'

*Description*

Resets a prepared statement on client and server to state after prepare.
It resets the statement on the server, data sent using
'mysql_stmt_send_long_data()', unbuffered
result sets and current errors.  It does not clear bindings or stored
result sets.  Stored result sets will be cleared when executing the
prepared statement (or closing it).

To re-prepare the statement with another query, use
'mysql_stmt_prepare()'.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.11.23 mysql_stmt_result_metadata()
.......................................

'MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)'

*Description*

If a statement passed to 'mysql_stmt_prepare()'
is one that produces a result set, see
'mysql_stmt_result_metadata()' returns the
result set metadata in the form of a pointer to a 'MYSQL_RES' structure
that can be used to process the meta information such as number of
fields and individual field information.  This result set pointer can be
passed as an argument to any of the field-based API functions that
process result set metadata, such as:

   * 'mysql_num_fields()'.

   * 'mysql_fetch_field()'.

   * 'mysql_fetch_field_direct()'.

   * 'mysql_fetch_fields()'.

   * 'mysql_field_count()'.

   * 'mysql_field_seek()'.

   * 'mysql_field_tell()'.

   * 'mysql_free_result()'.

The result set structure should be freed when you are done with it,
which you can do by passing it to 'mysql_free_result()'.
This is similar to the way you free a result set
obtained from a call to 'mysql_store_result()'.

The result set returned by 'mysql_stmt_result_metadata()'
contains only metadata.  It does not contain
any row results.  The rows are obtained by using the statement handler
with 'mysql_stmt_fetch()'.

*Return Values*

A 'MYSQL_RES' result structure.  'NULL' if no meta information exists
for the prepared query.

*Errors*

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

See the Example in mysql-stmt-fetch.

27.8.11.24 mysql_stmt_row_seek()
................................

'MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET
offset)'

*Description*

Sets the row cursor to an arbitrary row in a statement result set.  The
'offset' value is a row offset that should be a value returned from
'mysql_stmt_row_tell()' or from
'mysql_stmt_row_seek()'.  This value is not a row
number; if you want to seek to a row within a result set by number, use
'mysql_stmt_data_seek()' instead.

This function requires that the result set structure contains the entire
result of the query, so 'mysql_stmt_row_seek()'
may be used only in conjunction with
'mysql_stmt_store_result()'.

*Return Values*

The previous value of the row cursor.  This value may be passed to a
subsequent call to 'mysql_stmt_row_seek()'.

*Errors*

None.

27.8.11.25 mysql_stmt_row_tell()
................................

'MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)'

*Description*

Returns the current position of the row cursor for the last
'mysql_stmt_fetch()'.  This value can be used as an
argument to 'mysql_stmt_row_seek()'.

You should use 'mysql_stmt_row_tell()' only
after 'mysql_stmt_store_result()'.

*Return Values*

The current offset of the row cursor.

*Errors*

None.

27.8.11.26 mysql_stmt_send_long_data()
......................................

'my_bool mysql_stmt_send_long_data(MYSQL_STMT *stmt, unsigned int
parameter_number, const char *data, unsigned long length)'

*Description*

Enables an application to send parameter data to the server in pieces
(or 'chunks').  Call this function after
'mysql_stmt_bind_param()' and before
'mysql_stmt_execute()'.  It can be called multiple
times to send the parts of a character or binary data value for a
column, which must be one of the 'TEXT' or 'BLOB'
data types.

'parameter_number' indicates which parameter to associate the data with.
Parameters are numbered beginning with 0.  'data' is a pointer to a
buffer containing data to be sent, and 'length' indicates the number of
bytes in the buffer.

*Note*:

The next 'mysql_stmt_execute()' call ignores
the bind buffer for all parameters that have been used with
'mysql_stmt_send_long_data()' since last
'mysql_stmt_execute()' or
'mysql_stmt_reset()'.

If you want to reset/forget the sent data, you can do it with
'mysql_stmt_reset()'.  See mysql-stmt-reset.

The 'max_allowed_packet' system variable controls the maximum size of
parameter values that can be sent with
'mysql_stmt_send_long_data()'.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_INVALID_BUFFER_USE'

     The parameter does not have a string or binary type.

   * 'CR_INVALID_PARAMETER_NO'

     Invalid parameter number.

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

*Example*

The following example demonstrates how to send the data for a
'TEXT' column in chunks.  It inserts the data value ''MySQL - The
most popular Open Source database'' into the 'text_column' column.  The
'mysql' variable is assumed to be a valid connection handler.

     #define INSERT_QUERY "INSERT INTO \
                           test_long_data(text_column) VALUES(?)"

     MYSQL_BIND bind[1];
     long       length;

     stmt = mysql_stmt_init(mysql);
     if (!stmt)
     {
       fprintf(stderr, " mysql_stmt_init(), out of memory\n");
       exit(0);
     }
     if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(INSERT_QUERY)))
     {
       fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
       fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
       exit(0);
     }
      memset(bind, 0, sizeof(bind));
      bind[0].buffer_type= MYSQL_TYPE_STRING;
      bind[0].length= &length;
      bind[0].is_null= 0;

     /* Bind the buffers */
     if (mysql_stmt_bind_param(stmt, bind))
     {
       fprintf(stderr, "\n param bind failed");
       fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
       exit(0);
     }

      /* Supply data in chunks to server */
      if (mysql_stmt_send_long_data(stmt,0,"MySQL",5))
     {
       fprintf(stderr, "\n send_long_data failed");
       fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
       exit(0);
     }

      /* Supply the next piece of data */
      if (mysql_stmt_send_long_data(stmt,0,
                " - The most popular Open Source database",40))
     {
       fprintf(stderr, "\n send_long_data failed");
       fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
       exit(0);
     }

      /* Now, execute the query */
      if (mysql_stmt_execute(stmt))
     {
       fprintf(stderr, "\n mysql_stmt_execute failed");
       fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
       exit(0);
     }

27.8.11.27 mysql_stmt_sqlstate()
................................

'const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)'

*Description*

For the statement specified by 'stmt', see 'mysql_stmt_sqlstate()'
returns a null-terminated string containing the
SQLSTATE error code for the most recently invoked prepared statement API
function that can succeed or fail.  The error code consists of five
characters.  '"00000"' means 'no error.' The values are specified by
ANSI SQL and ODBC. For a list of possible values, see
error-handling.

Not all MySQL errors are mapped to SQLSTATE codes.  The value '"HY000"'
(general error) is used for unmapped errors.

If the failed statement API function was 'mysql_stmt_close()',
do not call 'mysql_stmt_sqlstate()'
to obtain error information because
'mysql_stmt_close()' makes the statement handler
invalid.  Call 'mysql_sqlstate()' instead.

*Return Values*

A null-terminated character string containing the SQLSTATE error code.

27.8.11.28 mysql_stmt_store_result()
....................................

'int mysql_stmt_store_result(MYSQL_STMT *stmt)'

*Description*

Result sets are produced by calling 'mysql_stmt_execute()'
to executed prepared statements for SQL statements
such as 'SELECT', 'SHOW', 'DESCRIBE',
and 'EXPLAIN'.  By default, result sets for
successfully executed prepared statements are not buffered on the client
and 'mysql_stmt_fetch()' fetches them one at a
time from the server.  To cause the complete result set to be buffered
on the client, call 'mysql_stmt_store_result()'
after binding data buffers with
'mysql_stmt_bind_result()' and before calling
'mysql_stmt_fetch()' to fetch rows.  (For an
example, see mysql-stmt-fetch.)

'mysql_stmt_store_result()' is optional
for result set processing, unless you will call
'mysql_stmt_data_seek()',
'mysql_stmt_row_seek()', or
'mysql_stmt_row_tell()'.  Those functions require a
seekable result set.

It is unnecessary to call 'mysql_stmt_store_result()'
after executing an SQL statement that does not
produce a result set, but if you do, it does not harm or cause any
notable performance problem.  You can detect whether the statement
produced a result set by checking if
'mysql_stmt_result_metadata()' returns
'NULL'.  For more information, refer to
mysql-stmt-result-metadata.

*Note*:

MySQL does not by default calculate 'MYSQL_FIELD->max_length' for all
columns in 'mysql_stmt_store_result()'.
because calculating this would slow down
'mysql_stmt_store_result()' considerably and
most applications do not need 'max_length'.  If you want 'max_length' to
be updated, you can call 'mysql_stmt_attr_set(MYSQL_STMT, STMT_ATTR_UPDATE_MAX_LENGTH, &flag)'
to enable
this.  See mysql-stmt-attr-set.

*Return Values*

Zero for success.  Nonzero if an error occurred.

*Errors*

   * 'CR_COMMANDS_OUT_OF_SYNC'

     Commands were executed in an improper order.

   * 'CR_OUT_OF_MEMORY'

     Out of memory.

   * 'CR_SERVER_GONE_ERROR'

     The MySQL server has gone away.

   * 'CR_SERVER_LOST'

     The connection to the server was lost during the query.

   * 'CR_UNKNOWN_ERROR'

     An unknown error occurred.

27.8.12 C API Threaded Function Descriptions
--------------------------------------------

To create a threaded client, use the functions described in the
following sections.  See also c-api-threaded-clients.

27.8.12.1 my_init()
...................

'void my_init(void)'

*Description*

'my_init()' initializes some global variables that MySQL
needs.  It also calls 'mysql_thread_init()'.
for this thread.

It is necessary for 'my_init()' to be called early in
the initialization phase of a program's use of the MySQL client library.
However, see 'my_init()' is automatically called by
'mysql_init()', 'mysql_library_init()',
see 'mysql_server_init()', and
'mysql_connect()'.  If you ensure that your program
invokes one of those functions before any other MySQL calls, there is no
need to invoke 'my_init()' explicitly.

To access the prototype for 'my_init()', your program
should include these header files:

     #include <my_global.h>
     #include <my_sys.h>

*Return Values*

None.

27.8.12.2 mysql_thread_end()
............................

'void mysql_thread_end(void)'

*Description*

Call this function before calling 'pthread_exit()' to free memory
allocated by 'mysql_thread_init()'.

See 'mysql_thread_end()'. _is not invoked
automatically by the client library_.

   * For release/production builds without debugging support enabled,
     see 'mysql_thread_end()' need not be called.

   * For debug builds, see 'mysql_thread_init()'.
     allocates debugging information for the DBUG package (see
     dbug-package).  See 'mysql_thread_end()'.
     must be called for each 'mysql_thread_init()'
     call to avoid a memory leak.

*Return Values*

None.

27.8.12.3 mysql_thread_init()
.............................

'my_bool mysql_thread_init(void)'

*Description*

This function must be called early within each created thread to
initialize thread-specific variables.  However, you may not necessarily
need to invoke it explicitly: 'mysql_thread_init()'
is automatically called by 'my_init()',
which itself is automatically called by 'mysql_init()',
see 'mysql_library_init()',
'mysql_server_init()', and 'mysql_connect()'.
If you invoke any of those functions, see
'mysql_thread_init()' is called for you.

*Return Values*

Zero for success.  Nonzero if an error occurred.

27.8.12.4 mysql_thread_safe()
.............................

'unsigned int mysql_thread_safe(void)'

*Description*

This function indicates whether the client library is compiled as
thread-safe.

*Return Values*

1 if the client library is thread-safe, 0 otherwise.

27.8.13 C API Embedded Server Function Descriptions
---------------------------------------------------

MySQL applications can be written to use an embedded server.  See
libmysqld.  To write such an application, you must link it against the
'libmysqld' library by using the '-lmysqld' flag rather than linking it
against the 'libmysqlclient' client library by using the '-lmysqlclient'
flag.  However, the calls to initialize and finalize the library are the
same whether you write a client application or one that uses the
embedded server: Call 'mysql_library_init()'.
to initialize the library and 'mysql_library_end()'
when you are done with it.  See
c-api-function-overview.

27.8.13.1 mysql_server_end()
............................

'void mysql_server_end(void)'

*Description*

This function finalizes the MySQL library, which should be done when you
are done using the library.  However, see 'mysql_server_end()'
is deprecated and 'mysql_library_end()'
should be used instead.  See
mysql-library-end.

*Note*:

To avoid memory leaks after the application is done using the library
(for example, after closing the connection to the server), be sure to
call 'mysql_server_end()'. (or
'mysql_library_end()') explicitly.  This enables
memory managment to be performed to clean up and free resources used by
the library.

*Return Values*

None.

27.8.13.2 mysql_server_init()
.............................

'int mysql_server_init(int argc, char **argv, char **groups)'

*Description*

This function initializes the MySQL client library, which must be done
before you call any other MySQL function.  However, see
'mysql_server_init()' is deprecated and you should
call 'mysql_library_init()' instead.  See
mysql-library-init.

*Note*:

To avoid memory leaks after the application is done using the library
(for example, after closing the connection to the server), be sure to
call 'mysql_server_end()'. (or
'mysql_library_end()') explicitly.  This enables
memory managment to be performed to clean up and free resources used by
the library.  See mysql-library-end.

*Return Values*

Zero for success.  Nonzero if an error occurred.

27.8.14 C API Client Plugin Functions
-------------------------------------

This section describes functions used for the client-side plugin API.
They enable management of client plugins.  For a description of the
'st_mysql_client_plugin' structure used by these functions, see
client-plugin-descriptors.

It is unlikely that a client program needs to call the functions in this
section.  For example, a client that supports the use of authentication
plugins normally causes a plugin to be loaded by calling
'mysql_options()' to set the 'MYSQL_DEFAULT_AUTH' and
'MYSQL_PLUGIN_DIR' options:

     char *plugin_dir = "PATH_TO_PLUGIN_DIR";
     char *default_auth = "PLUGIN_NAME";

     /* ... process command-line options ... */

     mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir);
     mysql_options(&mysql, MYSQL_DEFAULT_AUTH, default_auth);

Typically, the program will also accept '--plugin-dir' and
'--default-auth' options that enable users to override the default
values.

27.8.14.1 mysql_client_find_plugin()
....................................

'struct st_mysql_client_plugin *mysql_client_find_plugin(MYSQL *mysql,
const char *name, int type)'

*Description*

Returns a pointer to a loaded plugin, loading the plugin first if
necessary.  An error occurs if the type is invalid or the plugin cannot
be found or loaded.

Specify the parameters as follows:

   * 'mysql': A pointer to a 'MYSQL' structure.  The plugin API does not
     require a connection to a MySQL server, but this structure must be
     properly initialized.  The structure is used to obtain
     connection-related information.

   * 'name': The plugin name.

   * 'type': The plugin type.

*Return Values*

A pointer to the plugin for success.  'NULL' if an error occurred.

*Errors*

To check for errors, call the 'mysql_error()' or
'mysql_errno()' function.  See mysql-error,
and mysql-errno.

*Example*

     MYSQL mysql;
     struct st_mysql_client_plugin *p;

     if ((p = mysql_client_find_plugin(&mysql, "myplugin",
                                       MYSQL_CLIENT_AUTHENTICATION_PLUGIN, 0)))
     {
       printf("Plugin version: %d.%d.%d\n", p->version[0], p->version[1], p->version[2]);
     }

27.8.14.2 mysql_client_register_plugin()
........................................

'struct st_mysql_client_plugin *mysql_client_register_plugin(MYSQL
*mysql, struct st_mysql_client_plugin *plugin)'

*Description*

Adds a plugin structure to the list of loaded plugins.  An error occurs
if the plugin is already loaded.

Specify the parameters as follows:

   * 'mysql': A pointer to a 'MYSQL' structure.  The plugin API does not
     require a connection to a MySQL server, but this structure must be
     properly initialized.  The structure is used to obtain
     connection-related information.

   * 'plugin': A pointer to the plugin structure.

*Return Values*

A pointer to the plugin for success.  'NULL' if an error occurred.

*Errors*

To check for errors, call the 'mysql_error()' or
'mysql_errno()' function.  See mysql-error,
and mysql-errno.

27.8.14.3 mysql_load_plugin()
.............................

'struct st_mysql_client_plugin *mysql_load_plugin(MYSQL *mysql, const
char *name, int type, int argc, ...)'

*Description*

Loads a MySQL client plugin, specified by name and type.  An error
occurs if the type is invalid or the plugin cannot be loaded.

It is not possible to load multiple plugins of the same type.  An error
occurs if you try to load a plugin of a type already loaded.

Specify the parameters as follows:

   * 'mysql': A pointer to a 'MYSQL' structure.  The plugin API does not
     require a connection to a MySQL server, but this structure must be
     properly initialized.  The structure is used to obtain
     connection-related information.

   * 'name': The name of the plugin to load.

   * 'type': The type of plugin to load, or −1 to disable type
     checking.  If type is not −1, only plugins matching the type are
     considered for loading.

   * 'argc': The number of following arguments (0 if there are none).
     Interpretation of any following arguments depends on the plugin
     type.

Another way to cause plugins to be loaded is to set the
'LIBMYSQL_PLUGINS' environment variable to a semicolon-separated list of
plugin names.  For example:

     shell> export LIBMYSQL_PLUGINS="myplugin1;myplugin2"

Plugins named by 'LIBMYSQL_PLUGINS' are loaded when the client program
calls 'mysql_library_init()'.  No error is
reported if problems occur loading these plugins.

The 'LIBMYSQL_PLUGIN_DIR' environment variable can be set to the path
name of the directory in which to look for client plugins.  This
variable is used in two ways:

   * During client plugin preloading, the value of the '--plugin-dir'
     option is not available, so client plugin loading fails unless the
     plugins are located in the hardwired default directory.  If the
     plugins are located elsewhere, 'LIBMYSQL_PLUGIN_DIR' environment
     variable can be set to the proper directory to enable plugin
     preloading to succeed.

   * For explicit client plugin loading, the
     'mysql_load_plugin()' and
     'mysql_load_plugin_v()'. C API functions use
     the 'LIBMYSQL_PLUGIN_DIR' value if it exists and the '--plugin-dir'
     option was not given.  If '--plugin-dir' is given, see
     'mysql_load_plugin()' and
     'mysql_load_plugin_v()' ignore
     'LIBMYSQL_PLUGIN_DIR'.

*Return Values*

A pointer to the plugin if it was loaded successfully.  'NULL' if an
error occurred.

*Errors*

To check for errors, call the 'mysql_error()' or
'mysql_errno()' function.  See mysql-error,
and mysql-errno.

*Example*

     MYSQL mysql;

     if(!mysql_load_plugin(&mysql, "myplugin",
                           MYSQL_CLIENT_AUTHENTICATION_PLUGIN, 0))
     {
         fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
         exit(-1);
     }

*See Also*

See also mysql-load-plugin, mysql-error,
mysql-errno.

27.8.14.4 mysql_load_plugin_v()
...............................

'struct st_mysql_client_plugin *mysql_load_plugin_v(MYSQL *mysql, const
char *name, int type, int argc, va_list args)'

*Description*

This function is equivalent to 'mysql_load_plugin()',
but it accepts a 'va_list' instead of a variable list
of parameters.

*See Also*

See also mysql-load-plugin.

27.8.14.5 mysql_plugin_options()
................................

'int mysql_plugin_options(struct st_mysql_client_plugin *plugin, const
char *option, const void *value)'

*Description*

Passes an option type and value to a plugin.  This function can be
called multiple times to set several options.  If the plugin does not
have an option handler, an error occurs.

Specify the parameters as follows:

   * 'plugin': A pointer to the plugin structure.

   * 'option': The option to be set.

   * 'value': A pointer to the option value.

*Return Values*

Zero for success, 1 if an error occurred.  If the plugin has an option
handler, that handler should also return zero for success and 1 if an
error occurred.

27.8.15 C API Encrypted Connection Support
------------------------------------------

This section describes how C applications use the C API capabilities for
encrypted connections.  By default, MySQL programs attempt to connect
using encryption if the server supports encrypted connections, falling
back to an unencrypted connection if an encrypted connection cannot be
established (see using-encrypted-connections).  For applications
that require control beyond the default behavior over how encrypted
connections are established, the C API provides these capabilities:

   * The 'mysql_options()' function enables
     applications to set the appropriate SSL/TLS options before calling
     'mysql_real_connect()'.  For example, to
     require the use of an encrypted connection, see
     c-api-enforcing-encrypted-connection.

   * The 'mysql_get_ssl_cipher()' function
     enables applications to determine, after a connection has been
     established, whether the connection uses encryption.  A 'NULL'
     return value indicates that encryption is not being used.  A
     non-'NULL' return value indicates an encrypted connection and names
     the encryption cipher.  See mysql-get-ssl-cipher.

   * c-api-encrypted-connection-options

   * c-api-enforcing-encrypted-connection

   * c-api-secure-encrypted-connection

*C API Options for Encrypted Connections*

'mysql_options()' provides the following options
for control over use of encrypted connections.  For option details, see
mysql-options.

   * 'MYSQL_OPT_SSL_CA': The path name of the Certificate Authority (CA)
     certificate file.  This option, if used, must specify the same
     certificate used by the server.

   * 'MYSQL_OPT_SSL_CAPATH': The path name of the directory that
     contains trusted SSL CA certificate files.

   * 'MYSQL_OPT_SSL_CERT': The path name of the client public key
     certificate file.

   * 'MYSQL_OPT_SSL_CIPHER': The list of permitted ciphers for SSL
     encryption.

   * 'MYSQL_OPT_SSL_CRL': The path name of the file containing
     certificate revocation lists.

   * 'MYSQL_OPT_SSL_CRLPATH': The path name of the directory that
     contains certificate revocation list files.

   * 'MYSQL_OPT_SSL_KEY': The path name of the client private key file.

   * 'MYSQL_OPT_SSL_MODE': The connection security state.

   * 'MYSQL_OPT_SSL_VERIFY_SERVER_CERT': Whether to perform host name
     identity verification of the server certificate Common Name value.

   * 'MYSQL_OPT_TLS_VERSION': The encryption protocols permitted by the
     client.

'mysql_ssl_set()' can be used as a convenience
routine that is equivalent to a set of 'mysql_options()'
calls that specify certificate and key files, encryption
ciphers, and so forth.  See mysql-ssl-set.

*Enforcing an Encrypted Connection*

'mysql_options()' options for information such as
SSL certificate and key files are used to establish an encrypted
connection if such connections are available, but do not enforce any
requirement that the connection obtained be encrypted.  To require an
encrypted connection, use the following technique:

  1. Call 'mysql_options()' as necessary supply
     the appropriate SSL parameters (certificate and key files,
     encryption ciphers, and so forth).

  2. Call 'mysql_options()' to pass the
     'MYSQL_OPT_SSL_MODE' option with a value of 'SSL_MODE_REQUIRED' or
     one of the more-restrictive option values.

  3. Call 'mysql_real_connect()' to connect
     to the server.  The call fails if an encrypted connection cannot be
     obtained; exit with an error.

*Improving Security of Encrypted Connections*

For additional security relative to that provided by the default
encryption, clients can supply a CA certificate matching the one used by
the server and enable host name identity verification.  In this way, the
server and client place their trust in the same CA certificate and the
client verifies that the host to which it connected is the one intended:

   * To specify the CA certificate, call 'mysql_options()'
     to pass the 'MYSQL_OPT_SSL_CA' (or
     'MYSQL_OPT_SSL_CAPATH') option, and call 'mysql_options()'
     to pass the 'MYSQL_OPT_SSL_MODE' option with a value
     of 'SSL_MODE_VERIFY_CA'.

   * To enable host name identity verification as well, call
     'mysql_options()' to pass the 'MYSQL_OPT_SSL_MODE'
     option with a value of 'SSL_MODE_VERIFY_IDENTITY' rather than
     'SSL_MODE_VERIFY_CA'.

*Note*:

Host name identity verification does not work with self-signed
certificates created automatically by the server, or manually using
'mysql_ssl_rsa_setup'. (see
creating-ssl-rsa-files-using-mysql).  Such self-signed certificates do
not contain the server name as the Common Name value.

27.8.16 C API Multiple Statement Execution Support
--------------------------------------------------

By default, see 'mysql_query()' and
'mysql_real_query()' interpret their statement string
argument as a single statement to be executed, and you process the
result according to whether the statement produces a result set (a set
of rows, as for 'SELECT') or an affected-rows count (as
for 'INSERT', 'UPDATE', and so forth).

MySQL also supports the execution of a string containing multiple
statements separated by semicolon (';') characters.  This capability is
enabled by special options that are specified either when you connect to
the server with 'mysql_real_connect()' or
after connecting by calling 'mysql_set_server_option()'.

Executing a multiple-statement string can produce multiple result sets
or row-count indicators.  Processing these results involves a different
approach than for the single-statement case: After handling the result
from the first statement, it is necessary to check whether more results
exist and process them in turn if so.  To support multiple-result
processing, the C API includes the 'mysql_more_results()'
and 'mysql_next_result()'.
functions.  These functions are used at the end of a loop that iterates
as long as more results are available.  _Failure to process the result
this way may result in a dropped connection to the server._

Multiple-result processing also is required if you execute 'CALL'
statements for stored procedures.  Results from a stored procedure
have these characteristics:

   * Statements within the procedure may produce result sets (for
     example, if it executes 'SELECT' statements).  These
     result sets are returned in the order that they are produced as the
     procedure executes.

     In general, the caller cannot know how many result sets a procedure
     will return.  Procedure execution may depend on loops or
     conditional statements that cause the execution path to differ from
     one call to the next.  Therefore, you must be prepared to retrieve
     multiple results.

   * The final result from the procedure is a status result that
     includes no result set.  The status indicates whether the procedure
     succeeded or an error occurred.

The multiple statement and result capabilities can be used only with
'mysql_query()' or 'mysql_real_query()'.
They cannot be used with the prepared statement
interface.  Prepared statement handlers are defined to work only with
strings that contain a single statement.  See
c-api-prepared-statements.

To enable multiple-statement execution and result processing, the
following options may be used:

   * The 'mysql_real_connect()' function has
     a 'flags' argument for which two option values are relevant:

        * 'CLIENT_MULTI_RESULTS' enables the client program to process
          multiple results.  This option _must_ be enabled if you
          execute 'CALL' statements for stored procedures
          that produce result sets.  Otherwise, such procedures result
          in an error 'Error 1312 (0A000): PROCEDURE PROC_NAME can't
          return a result set in the given context'.  In MySQL 5.7,
          'CLIENT_MULTI_RESULTS' is enabled by default.

        * 'CLIENT_MULTI_STATEMENTS' enables 'mysql_query()'
          and 'mysql_real_query()'.
          to execute statement strings containing multiple statements
          separated by semicolons.  This option also enables
          'CLIENT_MULTI_RESULTS' implicitly, so a 'flags' argument of
          'CLIENT_MULTI_STATEMENTS' to 'mysql_real_connect()'
          is equivalent to an argument of
          'CLIENT_MULTI_STATEMENTS | CLIENT_MULTI_RESULTS'.  That is,
          'CLIENT_MULTI_STATEMENTS' is sufficient to enable
          multiple-statement execution and all multiple-result
          processing.

   * After the connection to the server has been established, you can
     use the 'mysql_set_server_option()'.
     function to enable or disable multiple-statement execution by
     passing it an argument of 'MYSQL_OPTION_MULTI_STATEMENTS_ON' or
     'MYSQL_OPTION_MULTI_STATEMENTS_OFF'.  Enabling multiple-statement
     execution with this function also enables processing of 'simple'
     results for a multiple-statement string where each statement
     produces a single result, but is _not_ sufficient to permit
     processing of stored procedures that produce result sets.

The following procedure outlines a suggested strategy for handling
multiple statements:

  1. Pass 'CLIENT_MULTI_STATEMENTS' to 'mysql_real_connect()',
     to fully enable multiple-statement execution
     and multiple-result processing.

  2. After calling 'mysql_query()' or
     'mysql_real_query()' and verifying that it
     succeeds, enter a loop within which you process statement results.

  3. For each iteration of the loop, handle the current statement
     result, retrieving either a result set or an affected-rows count.
     If an error occurs, exit the loop.

  4. At the end of the loop, call 'mysql_next_result()'
     to check whether another result exists and
     initiate retrieval for it if so.  If no more results are available,
     exit the loop.

One possible implementation of the preceding strategy is shown
following.  The final part of the loop can be reduced to a simple test
of whether 'mysql_next_result()' returns
nonzero.  The code as written distinguishes between no more results and
an error, which enables a message to be printed for the latter
occurrence.

     /* connect to server with the CLIENT_MULTI_STATEMENTS option */
     if (mysql_real_connect (mysql, host_name, user_name, password,
         db_name, port_num, socket_name, CLIENT_MULTI_STATEMENTS) == NULL)
     {
       printf("mysql_real_connect() failed\n");
       mysql_close(mysql);
       exit(1);
     }

     /* execute multiple statements */
     status = mysql_query(mysql,
                          "DROP TABLE IF EXISTS test_table;\
                           CREATE TABLE test_table(id INT);\
                           INSERT INTO test_table VALUES(10);\
                           UPDATE test_table SET id=20 WHERE id=10;\
                           SELECT * FROM test_table;\
                           DROP TABLE test_table");
     if (status)
     {
       printf("Could not execute statement(s)");
       mysql_close(mysql);
       exit(0);
     }

     /* process each statement result */
     do {
       /* did current statement return data? */
       result = mysql_store_result(mysql);
       if (result)
       {
         /* yes; process rows and free the result set */
         process_result_set(mysql, result);
         mysql_free_result(result);
       }
       else          /* no result set or error */
       {
         if (mysql_field_count(mysql) == 0)
         {
           printf("%lld rows affected\n",
                 mysql_affected_rows(mysql));
         }
         else  /* some error occurred */
         {
           printf("Could not retrieve result set\n");
           break;
         }
       }
       /* more results? -1 = no, >0 = error, 0 = yes (keep looping) */
       if ((status = mysql_next_result(mysql)) > 0)
         printf("Could not execute statement\n");
     } while (status == 0);

     mysql_close(mysql);

27.8.17 C API Prepared Statement Handling of Date and Time Values
-----------------------------------------------------------------

The binary (prepared statement) protocol enables you to send and receive
date and time values (see 'DATE', 'TIME',
'DATETIME', and 'TIMESTAMP'), using the
'MYSQL_TIME' structure.  The members of this structure are described in
c-api-prepared-statement-data-structures.

To send temporal data values, create a prepared statement using
'mysql_stmt_prepare()'.  Then, before calling
'mysql_stmt_execute()' to execute the statement,
use the following procedure to set up each temporal parameter:

  1. In the 'MYSQL_BIND' structure associated with the data value, set
     the 'buffer_type' member to the type that indicates what kind of
     temporal value you're sending.  For 'DATE',
     'TIME', 'DATETIME', or 'TIMESTAMP'
     values, set 'buffer_type' to 'MYSQL_TYPE_DATE',
     'MYSQL_TYPE_TIME', 'MYSQL_TYPE_DATETIME', or
     'MYSQL_TYPE_TIMESTAMP', respectively.

  2. Set the 'buffer' member of the 'MYSQL_BIND' structure to the
     address of the 'MYSQL_TIME' structure in which you pass the
     temporal value.

  3. Fill in the members of the 'MYSQL_TIME' structure that are
     appropriate for the type of temporal value to pass.

Use 'mysql_stmt_bind_param()' to bind the
parameter data to the statement.  Then you can call
'mysql_stmt_execute()'.

To retrieve temporal values, the procedure is similar, except that you
set the 'buffer_type' member to the type of value you expect to receive,
and the 'buffer' member to the address of a 'MYSQL_TIME' structure into
which the returned value should be placed.  Use
'mysql_stmt_bind_result()' to bind the buffers
to the statement after calling 'mysql_stmt_execute()'
and before fetching the results.

Here is a simple example that inserts 'DATE',
'TIME', and 'TIMESTAMP' data.  The 'mysql'
variable is assumed to be a valid connection handler.

       MYSQL_TIME  ts;
       MYSQL_BIND  bind[3];
       MYSQL_STMT  *stmt;

       strmov(query, "INSERT INTO test_table(date_field, time_field, \
                                    timestamp_field) VALUES(?,?,?");

       stmt = mysql_stmt_init(mysql);
       if (!stmt)
       {
         fprintf(stderr, " mysql_stmt_init(), out of memory\n");
         exit(0);
       }
       if (mysql_stmt_prepare(mysql, query, strlen(query)))
       {
         fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed");
         fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
         exit(0);
       }

       /* set up input buffers for all 3 parameters */
       bind[0].buffer_type= MYSQL_TYPE_DATE;
       bind[0].buffer= (char *)&ts;
       bind[0].is_null= 0;
       bind[0].length= 0;
       ...
       bind[1]= bind[2]= bind[0];
       ...

       mysql_stmt_bind_param(stmt, bind);

       /* supply the data to be sent in the ts structure */
       ts.year= 2002;
       ts.month= 02;
       ts.day= 03;

       ts.hour= 10;
       ts.minute= 45;
       ts.second= 20;

       mysql_stmt_execute(stmt);
       ..

27.8.18 C API Prepared CALL Statement Support
---------------------------------------------

This section describes prepared-statement support in the C API for
stored procedures executed using 'CALL' statements:

Stored procedures executed using prepared 'CALL' statements
can be used in the following ways:

   * A stored procedure can produce any number of result sets.  The
     number of columns and the data types of the columns need not be the
     same for all result sets.

   * The final values of 'OUT' and 'INOUT' parameters are available to
     the calling application after the procedure returns.  These
     parameters are returned as an extra single-row result set following
     any result sets produced by the procedure itself.  The row contains
     the values of the 'OUT' and 'INOUT' parameters in the order in
     which they are declared in the procedure parameter list.

The following discussion shows how to use these capabilities through the
C API for prepared statements.  To use prepared 'CALL'.
statements through the 'PREPARE' and 'EXECUTE'
statements, see call.

An application that executes a prepared 'CALL' statement
should use a loop that fetches a result and then invokes
'mysql_stmt_next_result()' to determine whether
there are more results.  The results consist of any result sets produced
by the stored procedure followed by a final status value that indicates
whether the procedure terminated successfully.

If the procedure has 'OUT' or 'INOUT' parameters, the result set
preceding the final status value contains their values.  To determine
whether a result set contains parameter values, test whether the
'SERVER_PS_OUT_PARAMS' bit is set in the 'server_status' member of the
'MYSQL' connection handler:

     mysql->server_status & SERVER_PS_OUT_PARAMS

The following example uses a prepared 'CALL' statement to
execute a stored procedure that produces multiple result sets and that
provides parameter values back to the caller by means of 'OUT' and
'INOUT' parameters.  The procedure takes parameters of all three types
('IN', 'OUT', 'INOUT'), displays their initial values, assigns new
values, displays the updated values, and returns.  The expected return
information from the procedure therefore consists of multiple result
sets and a final status:

   * One result set from a 'SELECT' that displays the
     initial parameter values: '10', 'NULL', '30'.  (The 'OUT' parameter
     is assigned a value by the caller, but this assignment is expected
     to be ineffective: 'OUT' parameters are seen as 'NULL' within a
     procedure until assigned a value within the procedure.)

   * One result set from a 'SELECT' that displays the
     modified parameter values: '100', '200', '300'.

   * One result set containing the final 'OUT' and 'INOUT' parameter
     values: '200', '300'.

   * A final status packet.

The code to execute the procedure:

     MYSQL_STMT *stmt;
     MYSQL_BIND ps_params[3];  /* input parameter buffers */
     int        int_data[3];   /* input/output values */
     my_bool    is_null[3];    /* output value nullability */
     int        status;

     /* set up stored procedure */
     status = mysql_query(mysql, "DROP PROCEDURE IF EXISTS p1");
     test_error(mysql, status);

     status = mysql_query(mysql,
       "CREATE PROCEDURE p1("
       "  IN p_in INT, "
       "  OUT p_out INT, "
       "  INOUT p_inout INT) "
       "BEGIN "
       "  SELECT p_in, p_out, p_inout; "
       "  SET p_in = 100, p_out = 200, p_inout = 300; "
       "  SELECT p_in, p_out, p_inout; "
       "END");
     test_error(mysql, status);

     /* initialize and prepare CALL statement with parameter placeholders */
     stmt = mysql_stmt_init(mysql);
     if (!stmt)
     {
       printf("Could not initialize statement\n");
       exit(1);
     }
     status = mysql_stmt_prepare(stmt, "CALL p1(?, ?, ?)", 16);
     test_stmt_error(stmt, status);

     /* initialize parameters: p_in, p_out, p_inout (all INT) */
     memset(ps_params, 0, sizeof (ps_params));

     ps_params[0].buffer_type = MYSQL_TYPE_LONG;
     ps_params[0].buffer = (char *) &int_data[0];
     ps_params[0].length = 0;
     ps_params[0].is_null = 0;

     ps_params[1].buffer_type = MYSQL_TYPE_LONG;
     ps_params[1].buffer = (char *) &int_data[1];
     ps_params[1].length = 0;
     ps_params[1].is_null = 0;

     ps_params[2].buffer_type = MYSQL_TYPE_LONG;
     ps_params[2].buffer = (char *) &int_data[2];
     ps_params[2].length = 0;
     ps_params[2].is_null = 0;

     /* bind parameters */
     status = mysql_stmt_bind_param(stmt, ps_params);
     test_stmt_error(stmt, status);

     /* assign values to parameters and execute statement */
     int_data[0]= 10;  /* p_in */
     int_data[1]= 20;  /* p_out */
     int_data[2]= 30;  /* p_inout */

     status = mysql_stmt_execute(stmt);
     test_stmt_error(stmt, status);

     /* process results until there are no more */
     do {
       int i;
       int num_fields;       /* number of columns in result */
       MYSQL_FIELD *fields;  /* for result set metadata */
       MYSQL_BIND *rs_bind;  /* for output buffers */

       /* the column count is > 0 if there is a result set */
       /* 0 if the result is only the final status packet */
       num_fields = mysql_stmt_field_count(stmt);

       if (num_fields > 0)
       {
         /* there is a result set to fetch */
         printf("Number of columns in result: %d\n", (int) num_fields);

         /* what kind of result set is this? */
         printf("Data: ");
         if(mysql->server_status & SERVER_PS_OUT_PARAMS)
           printf("this result set contains OUT/INOUT parameters\n");
         else
           printf("this result set is produced by the procedure\n");

         MYSQL_RES *rs_metadata = mysql_stmt_result_metadata(stmt);
         test_stmt_error(stmt, rs_metadata == NULL);

         fields = mysql_fetch_fields(rs_metadata);

         rs_bind = (MYSQL_BIND *) malloc(sizeof (MYSQL_BIND) * num_fields);
         if (!rs_bind)
         {
           printf("Cannot allocate output buffers\n");
           exit(1);
         }
         memset(rs_bind, 0, sizeof (MYSQL_BIND) * num_fields);

         /* set up and bind result set output buffers */
         for (i = 0; i < num_fields; ++i)
         {
           rs_bind[i].buffer_type = fields[i].type;
           rs_bind[i].is_null = &is_null[i];

           switch (fields[i].type)
           {
             case MYSQL_TYPE_LONG:
               rs_bind[i].buffer = (char *) &(int_data[i]);
               rs_bind[i].buffer_length = sizeof (int_data);
               break;

             default:
               fprintf(stderr, "ERROR: unexpected type: %d.\n", fields[i].type);
               exit(1);
           }
         }

         status = mysql_stmt_bind_result(stmt, rs_bind);
         test_stmt_error(stmt, status);

         /* fetch and display result set rows */
         while (1)
         {
           status = mysql_stmt_fetch(stmt);

           if (status == 1 || status == MYSQL_NO_DATA)
             break;

           for (i = 0; i < num_fields; ++i)
           {
             switch (rs_bind[i].buffer_type)
             {
               case MYSQL_TYPE_LONG:
                 if (*rs_bind[i].is_null)
                   printf(" val[%d] = NULL;", i);
                 else
                   printf(" val[%d] = %ld;",
                          i, (long) *((int *) rs_bind[i].buffer));
                 break;

               default:
                 printf("  unexpected type (%d)\n",
                   rs_bind[i].buffer_type);
             }
           }
           printf("\n");
         }

         mysql_free_result(rs_metadata); /* free metadata */
         free(rs_bind);                  /* free output buffers */
       }
       else
       {
         /* no columns = final status packet */
         printf("End of procedure output\n");
       }

       /* more results? -1 = no, >0 = error, 0 = yes (keep looking) */
       status = mysql_stmt_next_result(stmt);
       if (status > 0)
         test_stmt_error(stmt, status);
     } while (status == 0);

     mysql_stmt_close(stmt);

Execution of the procedure should produce the following output:

     Number of columns in result: 3
     Data: this result set is produced by the procedure
      val[0] = 10; val[1] = NULL; val[2] = 30;
     Number of columns in result: 3
     Data: this result set is produced by the procedure
      val[0] = 100; val[1] = 200; val[2] = 300;
     Number of columns in result: 2
     Data: this result set contains OUT/INOUT parameters
      val[0] = 200; val[1] = 300;
     End of procedure output

The code uses two utility routines, 'test_error()' and
'test_stmt_error()', to check for errors and terminate after printing
diagnostic information if an error occurred:

     static void test_error(MYSQL *mysql, int status)
     {
       if (status)
       {
         fprintf(stderr, "Error: %s (errno: %d)\n",
                 mysql_error(mysql), mysql_errno(mysql));
         exit(1);
       }
     }

     static void test_stmt_error(MYSQL_STMT *stmt, int status)
     {
       if (status)
       {
         fprintf(stderr, "Error: %s (errno: %d)\n",
                 mysql_stmt_error(stmt), mysql_stmt_errno(stmt));
         exit(1);
       }
     }

27.8.19 C API Prepared Statement Problems
-----------------------------------------

Here follows a list of the currently known problems with prepared
statements:

   * 'TIME', 'TIMESTAMP', and
     'DATETIME' do not support parts of seconds (for example,
     from 'DATE_FORMAT()').

   *
     When converting an integer to string, 'ZEROFILL' is honored with
     prepared statements in some cases where the MySQL server does not
     print the leading zeros.  (For example, with
     'MIN(NUMBER-WITH-ZEROFILL)').

   * When converting a floating-point number to a string in the client,
     the rightmost digits of the converted value may differ slightly
     from those of the original value.

   * Prepared statements use the query cache under the conditions
     described in query-cache-operation.

   * Prepared statements do not support multi-statements (that is,
     multiple statements within a single string separated by ';'
     characters).

   * The capabilities of prepared 'CALL' statements are
     described in c-api-prepared-call-statements.

27.8.20 C API Automatic Reconnection Control
--------------------------------------------

The MySQL client library can perform an automatic reconnection to the
server if it finds that the connection is down when you attempt to send
a statement to the server to be executed.  If auto-reconnect is enabled,
the library tries once to reconnect to the server and send the statement
again.

Auto-reconnect is disabled by default.

If it is important for your application to know that the connection has
been dropped (so that it can exit or take action to adjust for the loss
of state information), be sure that auto-reconnect is disabled.  To
ensure this, call 'mysql_options()' with the
'MYSQL_OPT_RECONNECT' option:

     my_bool reconnect = 0;
     mysql_options(&mysql, MYSQL_OPT_RECONNECT, &reconnect);

If the connection has gone down, the effect of 'mysql_ping()'
depends on the auto-reconnect state.  If auto-reconnect is
enabled, see 'mysql_ping()' performs a reconnect.
Otherwise, it returns an error.

Some client programs might provide the capability of controlling
automatic reconnection.  For example, see 'mysql' reconnects
by default, but the '--skip-reconnect' option can be used to suppress
this behavior.

If an automatic reconnection does occur (for example, as a result of
calling 'mysql_ping()'), there is no explicit
indication of it.  To check for reconnection, call
'mysql_thread_id()' to get the original connection
identifier before calling 'mysql_ping()', then call
'mysql_thread_id()' again to see whether the
identifier changed.

Automatic reconnection can be convenient because you need not implement
your own reconnect code, but if a reconnection does occur, several
aspects of the connection state are reset on the server side and your
application will not be notified.

The connection-related state is affected as follows:

   * Any active transactions are rolled back and autocommit mode is
     reset.

   * All table locks are released.

   * All 'TEMPORARY' tables are closed (and dropped).

   * Session system variables are reinitialized to the values of the
     corresponding global system variables, including system variables
     that are set implicitly by statements such as 'SET NAMES'.

   * User variable settings are lost.

   * Prepared statements are released.

   * 'HANDLER' variables are closed.

   * The value of 'LAST_INSERT_ID()' is reset to 0.

   * Locks acquired with 'GET_LOCK()' are released.

   * The association of the client with the Performance Schema
     'threads' table row that determines connection
     thread instrumentation is lost.  If the client reconnects after a
     disconnect, the session is associated with a new row in the
     'threads' table and the thread monitoring state may
     be different.  See threads-table.

If reconnection occurs, any SQL statement specified by calling
'mysql_options()' with the 'MYSQL_INIT_COMMAND' option
is re-executed.

If the connection drops, it is possible that the session associated with
the connection on the server side will still be running if the server
has not yet detected that the client is no longer connected.  In this
case, any locks held by the original connection still belong to that
session, so you may want to kill it by calling 'mysql_kill()'.

27.8.21 C API Common Issues
---------------------------

27.8.21.1 Why mysql_store_result() Sometimes Returns NULL After mysql_query() Returns Success
.............................................................................................

It is possible for 'mysql_store_result()' to
return 'NULL' following a successful call to 'mysql_query()'.
When this happens, it means one of the following
conditions occurred:

   * There was a 'malloc()' failure (for example, if the result set was
     too large).

   * The data could not be read (an error occurred on the connection).

   * The query returned no data (for example, it was an 'INSERT',
     see 'UPDATE', or 'DELETE').

You can always check whether the statement should have produced a
nonempty result by calling 'mysql_field_count()'.
If 'mysql_field_count()'.
returns zero, the result is empty and the last query was a statement
that does not return values (for example, an 'INSERT' or
a 'DELETE').  If 'mysql_field_count()'
returns a nonzero value, the statement should have
produced a nonempty result.  See the description of the
'mysql_field_count()' function for an example.

You can test for an error by calling 'mysql_error()'.
or 'mysql_errno()'.

27.8.21.2 What Results You Can Get from a Query
...............................................

In addition to the result set returned by a query, you can also get the
following information:

   * 'mysql_affected_rows()' returns the
     number of rows affected by the last query when doing an
     'INSERT', 'UPDATE', or 'DELETE'.

     For a fast re-create, use 'TRUNCATE TABLE'.

   * 'mysql_num_rows()' returns the number of
     rows in a result set.  With 'mysql_store_result()',
     see 'mysql_num_rows()' may
     be called as soon as 'mysql_store_result()'
     returns.  With 'mysql_use_result()',
     see 'mysql_num_rows()' may be
     called only after you have fetched all the rows with
     'mysql_fetch_row()'.

   * 'mysql_insert_id()' returns the ID
     generated by the last query that inserted a row into a table with
     an 'AUTO_INCREMENT' index.  See mysql-insert-id.

   * Some queries (see 'LOAD DATA INFILE ...',
     'INSERT INTO ... SELECT ...', 'UPDATE')
     return additional information.  The result is returned by
     'mysql_info()'.  See the description for
     'mysql_info()' for the format of the string that it
     returns.  'mysql_info()' returns a 'NULL'
     pointer if there is no additional information.

27.8.21.3 How to Get the Unique ID for the Last Inserted Row
............................................................

If you insert a record into a table that contains an 'AUTO_INCREMENT'
column, you can obtain the value stored into that column by calling the
'mysql_insert_id()' function.

You can check from your C applications whether a value was stored in an
'AUTO_INCREMENT' column by executing the following code (which assumes
that you've checked that the statement succeeded).  It determines
whether the query was an 'INSERT' with an
'AUTO_INCREMENT' index:

     if ((result = mysql_store_result(&mysql)) == 0 &&
         mysql_field_count(&mysql) == 0 &&
         mysql_insert_id(&mysql) != 0)
     {
         used_id = mysql_insert_id(&mysql);
     }

When a new 'AUTO_INCREMENT' value has been generated, you can also
obtain it by executing a 'SELECT LAST_INSERT_ID()' statement with
'mysql_query()' and retrieving the value from the result
set returned by the statement.

When inserting multiple values, the last automatically incremented value
is returned.

For 'LAST_INSERT_ID()', the most recently generated ID is maintained in
the server on a per-connection basis.  It is not changed by another
client.  It is not even changed if you update another 'AUTO_INCREMENT'
column with a nonmagic value (that is, a value that is not 'NULL' and
not '0').  Using 'LAST_INSERT_ID()' and 'AUTO_INCREMENT' columns
simultaneously from multiple clients is perfectly valid.  Each client
will receive the last inserted ID for the last statement _that_ client
executed.

If you want to use the ID that was generated for one table and insert it
into a second table, you can use SQL statements like this:

     INSERT INTO foo (auto,text)
         VALUES(NULL,'text');         # generate ID by inserting NULL
     INSERT INTO foo2 (id,text)
         VALUES(LAST_INSERT_ID(),'text');  # use ID in second table

'mysql_insert_id()' returns the value stored
into an 'AUTO_INCREMENT' column, whether that value is automatically
generated by storing 'NULL' or '0' or was specified as an explicit
value.  'LAST_INSERT_ID()' returns only automatically generated
'AUTO_INCREMENT' values.  If you store an explicit value other than
'NULL' or '0', it does not affect the value returned by
'LAST_INSERT_ID()'.

For more information on obtaining the last ID in an 'AUTO_INCREMENT'
column:

   * For information on 'LAST_INSERT_ID()', which can be used within an
     SQL statement, see information-functions.

   * For information on 'mysql_insert_id()', the
     function you use from within the C API, see
     mysql-insert-id.

   * For information on obtaining the auto-incremented value when using
     Connector/J, see Retrieving 'AUTO_INCREMENT' Column Values through
     JDBC
     (http://dev.mysql.com/doc/connector-j/5.1/en/connector-j-usagenotes-last-insert-id.html).

   * For information on obtaining the auto-incremented value when using
     Connector/ODBC, see Obtaining Auto-Increment Values
     (http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-usagenotes-functionality-last-insert-id.html).

27.9 MySQL PHP API
==================

The MySQL PHP API manual is now published in standalone form, not as
part of the MySQL Reference Manual.  See MySQL and PHP
(http://dev.mysql.com/doc/apis-php/en/).

27.10 MySQL Perl API
====================

The Perl 'DBI' module provides a generic interface for database access.
You can write a DBI script that works with many different database
engines without change.  To use DBI with MySQL, install the following:

  1. The 'DBI' module.

  2. The 'DBD::mysql' module.  This is the DataBase Driver (DBD) module
     for Perl.

  3. Optionally, the DBD module for any other type of database server
     you want to access.

Perl DBI is the recommended Perl interface.  It replaces an older
interface called 'mysqlperl', which should be considered obsolete.

These sections contain information about using Perl with MySQL and
writing MySQL applications in Perl:

   * For installation instructions for Perl DBI support, see
     perl-support.

   * For an example of reading options from option files, see
     multiple-server-clients.

   * For secure coding tips, see security-guidelines.

   * For debugging tips, see using-gdb-on-mysqld.

   * For some Perl-specific environment variables, see
     environment-variables.

   * For considerations for running on OS X, see
     osx-installation.

   * For ways to quote string literals, see string-literals.

DBI information is available at the command line, online, or in printed
form:

   * Once you have the 'DBI' and 'DBD::mysql' modules installed, you can
     get information about them at the command line with the 'perldoc'
     command:

          shell> perldoc DBI
          shell> perldoc DBI::FAQ
          shell> perldoc DBD::mysql

     You can also use 'pod2man', 'pod2html', and so on to translate this
     information into other formats.

   * For online information about Perl DBI, visit the DBI website,
     <http://dbi.perl.org/>.  That site hosts a general DBI mailing
     list.  Oracle Corporation hosts a list specifically about
     'DBD::mysql'; see mailing-lists.

   * For printed information, the official DBI book is 'Programming the
     Perl DBI' (Alligator Descartes and Tim Bunce, O'Reilly &
     Associates, 2000).  Information about the book is available at the
     DBI website, <http://dbi.perl.org/>.

27.11 MySQL Python API
======================

'MySQLdb' is a third-party driver that provides MySQL support for
Python, compliant with the Python DB API version 2.0.  It can be found
at <http://sourceforge.net/projects/mysql-python/>.

The new MySQL Connector/Python component provides an interface to the
same Python API, and is built into the MySQL Server and supported by
Oracle.  See MySQL Connector/Python Developer Guide
(http://dev.mysql.com/doc/connector-python/en/) for details on the
Connector, as well as coding guidelines for Python applications and
sample Python code.

27.12 MySQL Ruby APIs
=====================

Two APIs are available for Ruby programmers developing MySQL
applications:

   * The MySQL/Ruby API is based on the 'libmysqlclient' API library.
     For information on installing and using the MySQL/Ruby API, see
     apis-ruby-mysqlruby.

   * The Ruby/MySQL API is written to use the native MySQL network
     protocol (a native driver).  For information on installing and
     using the Ruby/MySQL API, see apis-ruby-rubymysql.

For background and syntax information about the Ruby language, see Ruby
Programming Language (http://www.ruby-lang.org).

27.12.1 The MySQL/Ruby API
--------------------------

The MySQL/Ruby module provides access to MySQL databases using Ruby
through 'libmysqlclient'.

For information on installing the module, and the functions exposed, see
MySQL/Ruby (http://tmtm.org/en/mysql/ruby/).

27.12.2 The Ruby/MySQL API
--------------------------

The Ruby/MySQL module provides access to MySQL databases using Ruby
through a native driver interface using the MySQL network protocol.

For information on installing the module, and the functions exposed, see
Ruby/MySQL (http://tmtm.org/en/ruby/mysql/README_en.html).

27.13 MySQL Tcl API
===================

'MySQLtcl' is a simple API for accessing a MySQL database server from
the Tcl programming language (http://en.wikipedia.org/wiki/Tcl).  It can
be found at <http://www.xdobry.de/mysqltcl/>.

27.14 MySQL Eiffel Wrapper
==========================

Eiffel MySQL is an interface to the MySQL database server using the
Eiffel programming language
(http://en.wikipedia.org/wiki/Eiffel_(programming_language)), written by
Michael Ravits.  It can be found at
<http://efsa.sourceforge.net/archive/ravits/mysql.htm>.

28 Extending MySQL
******************

28.1 MySQL Internals
====================

This chapter describes a lot of things that you need to know when
working on the MySQL code.  To track or contribute to MySQL development,
follow the instructions in installing-development-tree.  If you
are interested in MySQL internals, you should also subscribe to our
'internals' mailing list.  This list has relatively low traffic.  For
details on how to subscribe, please see mailing-lists.  Many
MySQL developers at Oracle Corporation are on the 'internals' list and
we help other people who are working on the MySQL code.  Feel free to
use this list both to ask questions about the code and to send patches
that you would like to contribute to the MySQL project!

28.1.1 MySQL Threads
--------------------

The MySQL server creates the following threads:

   * Connection manager threads handle client connection requests on the
     network interfaces that the server listens to.  On all platforms,
     one manager thread handles TCP/IP connection requests.  On Unix,
     this manager thread also handles Unix socket file connection
     requests.  On Windows, a manager thread handles shared-memory
     connection requests, and another handles named-pipe connection
     requests.  The server does not create threads to handle interfaces
     that it does not listen to.  For example, a Windows server that
     does not have support for named-pipe connections enabled does not
     create a thread to handle them.

   * Connection manager threads associate each client connection with a
     thread dedicated to it that handles authentication and request
     processing for that connection.  Manager threads create a new
     thread when necessary but try to avoid doing so by consulting the
     thread cache first to see whether it contains a thread that can be
     used for the connection.  When a connection ends, its thread is
     returned to the thread cache if the cache is not full.

     For information about tuning the parameters that control thread
     resources, see connection-threads.

   * On a master replication server, connections from slave servers are
     handled like client connections: There is one thread per connected
     slave.

   * On a slave replication server, an I/O thread is started to connect
     to the master server and read updates from it.  An SQL thread is
     started to apply updates read from the master.  These two threads
     run independently and can be started and stopped independently.

   * A signal thread handles all signals.  This thread also normally
     handles alarms and calls 'process_alarm()' to force timeouts on
     connections that have been idle too long.

   * If 'InnoDB' is used, there will be additional read and write
     threads by default.  The number of these are controlled by the
     'innodb_read_io_threads' and 'innodb_write_io_threads' parameters.
     See innodb-parameters.

   * If the server is started with the '--flush_time=VAL' option, a
     dedicated thread is created to flush all tables every VAL seconds.

   * If the event scheduler is active, there is one thread for the
     scheduler, and a thread for each event currently running.  See
     events-overview.

'mysqladmin processlist' only shows the connection,
replication, and event threads.

28.1.2 The MySQL Test Suite
---------------------------

The test system that is included in Unix source and binary distributions
makes it possible for users and developers to perform regression tests
on the MySQL code.  These tests can be run on Unix.

You can also write your own test cases.  For information about the MySQL
Test Framework, including system requirements, see the manual available
at <http://dev.mysql.com/doc/mysqltest/2.0/en/>.

The current set of test cases does not test everything in MySQL, but it
should catch most obvious bugs in the SQL processing code, operating
system or library issues, and is quite thorough in testing replication.
Our goal is to have the tests cover 100% of the code.  We welcome
contributions to our test suite.  You may especially want to contribute
tests that examine the functionality critical to your system because
this ensures that all future MySQL releases work well with your
applications.

The test system consists of a test language interpreter ('mysqltest'), a
Perl script to run all tests ('mysql-test-run.pl'), the actual test
cases written in a special test language, and their expected results.
To run the test suite on your system after a build, type 'make test'
from the source root directory, or change location to the 'mysql-test'
directory and type './mysql-test-run.pl'.  If you have installed a
binary distribution, change location to the 'mysql-test' directory under
the installation root directory (for example,
'/usr/local/mysql/mysql-test'), and run './mysql-test-run.pl'.  All
tests should succeed.  If any do not, feel free to try to find out why
and report the problem if it indicates a bug in MySQL. See
bug-reports.

If one test fails, you should run 'mysql-test-run.pl' with the '--force'
option to check whether any other tests fail.

If you have a copy of 'mysqld' running on the machine
where you want to run the test suite, you do not have to stop it, as
long as it is not using ports '9306' or '9307'.  If either of those
ports is taken, you should set the 'MTR_BUILD_THREAD' environment
variable to an appropriate value, and the test suite will use a
different set of ports for master, slave, and NDB). For example:

     shell> export MTR_BUILD_THREAD=31
     shell> ./mysql-test-run.pl [OPTIONS] [TEST_NAME]

In the 'mysql-test' directory, you can run an individual test case with
'./mysql-test-run.pl TEST_NAME'.

If you have a question about the test suite, or have a test case to
contribute, send an email message to the MySQL 'internals' mailing list.
See mailing-lists.

28.2 The MySQL Plugin API
=========================

MySQL supports a plugin API that enables creation of server components.
Plugins can be loaded at server startup, or loaded and unloaded at
runtime without restarting the server.  The API is generic and does not
specify what plugins can do.  The components supported by this interface
include, but are not limited to, storage engines, full-text parser
plugins, and server extensions.

For example, full-text parser plugins can be used to replace or augment
the built-in full-text parser.  A plugin can parse text into words using
rules that differ from those used by the built-in parser.  This can be
useful if you need to parse text with characteristics different from
those expected by the built-in parser.

The plugin interface is more general than the older user-defined
function (UDF) interface.

The plugin interface uses the 'plugin' table in the 'mysql' database to
record information about plugins that have been installed permanently
with the 'INSTALL PLUGIN' statement.  This table
is created as part of the MySQL installation process.  Plugins can also
be installed for a single server invocation with the '--plugin-load'
option.  Plugins installed this way are not recorded in the 'plugin'
table.  See server-plugin-loading.

MySQL supports an API for client plugins in addition to that for server
plugins.  This is used, for example, by authentication plugins where a
server-side plugin and a client-side plugin cooperate to enable clients
to connect to the server through a variety of authentication methods.

*Additional Resources*

The book 'MySQL 5.1 Plugin Development' by Sergei Golubchik and Andrew
Hutchings provides a wealth of detail about the plugin API. Despite the
fact that the book's title refers to MySQL Server 5.1, most of the
information in it applies to later versions as well.

28.2.1 Types of Plugins
-----------------------

The plugin API enables creation of plugins that implement several
capabilities:

   * Storage engines

   * Full-text parsers

   * Daemons

   * 'INFORMATION_SCHEMA' tables

   * Semisynchronous replication

   * Auditing

   * Authentication

   * Password validation and strength checking

   * Protocol tracing

   * Query rewriting

   * Secure keyring storage and retrieval

The following sections provide an overview of these plugin types.

*Storage Engine Plugins*

The pluggable storage engine architecture used by MySQL Server enables
storage engines to be written as plugins and loaded into and unloaded
from a running server.  For a description of this architecture, see
pluggable-storage-overview.

For information on how to use the plugin API to write storage engines,
see MySQL Internals: Writing a Custom Storage Engine
(http://dev.mysql.com/doc/internals/en/custom-engine.html).

*Full-Text Parser Plugins*

MySQL has a built-in parser that it uses by default for full-text
operations (parsing text to be indexed, or parsing a query string to
determine the terms to be used for a search).  The built-in full-text
parser is supported with 'InnoDB' and 'MyISAM' tables.

MySQL also has a character-based ngram full-text parser that supports
Chinese, Japanese, and Korean (CJK), and a word-based MeCab parser
plugin that supports Japanese, for use with 'InnoDB' and 'MyISAM'
tables.

For full-text processing, 'parsing' means extracting words (or 'tokens',
in the case of an n-gram character-based parser) from text or a query
string based on rules that define which character sequences make up a
word and where word boundaries lie.

When parsing for indexing purposes, the parser passes each word to the
server, which adds it to a full-text index.  When parsing a query
string, the parser passes each word to the server, which accumulates the
words for use in a search.

The parsing properties of the built-in full-text parser are described in
fulltext-search.  These properties include rules for determining
how to extract words from text.  The parser is influenced by certain
system variables that cause words shorter or longer to be excluded, and
by the stopword list that identifies common words to be ignored.  For
more information, see fulltext-stopwords, and
fulltext-fine-tuning.

The plugin API enables you to use a full-text parser other than the
default built-in full-text parser.  For example, if you are working with
Japanese, you may choose to use the MeCab full-text parser.  The plugin
API also enables you to provide a full-text parser of your own so that
you have control over the basic duties of a parser.  A parser plugin can
operate in either of two roles:

   * The plugin can replace the built-in parser.  In this role, the
     plugin reads the input to be parsed, splits it up into words, and
     passes the words to the server (either for indexing or for token
     accumulation).  The ngram and MeCab parsers operate as replacements
     for the built-in full-text parser.

     You may choose to provide your own full-text parser if you need to
     use different rules from those of the built-in parser for
     determining how to split up input into words.  For example, the
     built-in parser considers the text 'case-sensitive' to consist of
     two words 'case' and 'sensitive,' whereas an application might need
     to treat the text as a single word.

   * The plugin can act in conjunction with the built-in parser by
     serving as a front end for it.  In this role, the plugin extracts
     text from the input and passes the text to the parser, which splits
     up the text into words using its normal parsing rules.  This
     parsing is affected by the 'innodb_ft_XXX' or 'ft_XXX' system
     variables and the stopword list.

     One reason to use a parser this way is that you need to index
     content such as PDF documents, XML documents, or '.doc' files.  The
     built-in parser is not intended for those types of input but a
     plugin can pull out the text from these input sources and pass it
     to the built-in parser.

It is also possible for a parser plugin to operate in both roles.  That
is, it could extract text from noncleartext input (the front end role),
and also parse the text into words (thus replacing the built-in parser).

A full-text plugin is associated with full-text indexes on a per-index
basis.  That is, when you install a parser plugin initially, that does
not cause it to be used for any full-text operations.  It simply becomes
available.  For example, a full-text parser plugin becomes available to
be named in a 'WITH PARSER' clause when creating individual 'FULLTEXT'
indexes.  To create such an index at table-creation time, do this:

     CREATE TABLE t
     (
       doc CHAR(255),
       FULLTEXT INDEX (doc) WITH PARSER parser_name
     ) ENGINE=InnoDB;

Or you can add the index after the table has been created:

     ALTER TABLE t ADD FULLTEXT INDEX (doc) WITH PARSER parser_name;

The only SQL change for associating the parser with the index is the
'WITH PARSER' clause.  Searches are specified as before, with no changes
needed for queries.

When you associate a parser plugin with a 'FULLTEXT' index, the plugin
is required for using the index.  If the parser plugin is dropped, any
index associated with it becomes unusable.  Any attempt to use a table
for which a plugin is not available results in an error, although
'DROP TABLE' is still possible.

For more information about full-text plugins, see
writing-full-text-plugins.  MySQL 5.7 supports full-text plugins with
'MyISAM' and 'InnoDB'.

*Daemon Plugins*

A daemon plugin is a simple type of plugin used for code that should be
run by the server but that does not communicate with it.  MySQL
distributions include an example daemon plugin that writes periodic
heartbeat messages to a file.

For more information about daemon plugins, see
writing-daemon-plugins.

*INFORMATION_SCHEMA Plugins*

'INFORMATION_SCHEMA' plugins enable the creation of tables containing
server metadata that are exposed to users through the
'INFORMATION_SCHEMA' database.  For example, 'InnoDB' uses
'INFORMATION_SCHEMA' plugins to provide tables that contain information
about current transactions and locks.

For more information about 'INFORMATION_SCHEMA' plugins, see
writing-information-schema-plugins.

*Semisynchronous Replication Plugins*

MySQL replication is asynchronous by default.  With semisynchronous
replication, a commit performed on the master side blocks before
returning to the session that performed the transaction until at least
one slave acknowledges that it has received and logged the events for
the transaction.  Semisynchronous replication is implemented through
complementary master and client plugins.  See
replication-semisync.

For more information about semisynchronous replication plugins, see
writing-semisynchronous-replication-plugins.

*Audit Plugins*

The MySQL server provides a pluggable audit interface that enables
information about server operations to be reported to interested
parties.  Audit notification occurs for these operations (although the
interface is general and the server could be modified to report others):

   * Write a message to the general query log (if the log is enabled)

   * Write a message to the error log

   * Send a query result to a client

Audit plugins may register with the audit interface to receive
notification about server operations.  When an auditable event occurs
within the server, the server determines whether notification is needed.
For each registered audit plugin, the server checks the event against
those event classes in which the plugin is interested and passes the
event to the plugin if there is a match.

This interface enables audit plugins to receive notifications only about
operations in event classes they consider significant and to ignore
others.  The interface provides for categorization of operations into
event classes and further division into event subclasses within each
class.

When an audit plugin is notified of an auditable event, it receives a
pointer to the current THD structure and a pointer to a structure that
contains information about the event.  The plugin can examine the event
and perform whatever auditing actions are appropriate.  For example, the
plugin can see what statement produced a result set or was logged, the
number of rows in a result, who the current user was for an operation,
or the error code for failed operations.

For more information about audit plugins, see
writing-audit-plugins.

*Authentication Plugins*

MySQL supports pluggable authentication.  Authentication plugins exist
on both the server and client sides.  Plugins on the server side
implement authentication methods for use by clients when they connect to
the server.  A plugin on the client side communicates with a server-side
plugin to provide the authentication information that it requires.  A
client-side plugin may interact with the user, performing tasks such as
soliciting a password or other authentication credentials to be sent to
the server.  See pluggable-authentication.

Pluggable authentication also enables proxy user capability, in which
one user takes the identity of another user.  A server-side
authentication plugin can return to the server the name of the user
whose identity the connecting user should have.  See
proxy-users.

For more information about authentication plugins, see
writing-authentication-plugins.

*Password-Validation Plugins*

The MySQL server provides an interface for writing plugins that test
passwords.  Such a plugin implements two capabilities:

   * Rejection of too-weak passwords in statements that assign passwords
     (such as 'CREATE USER' and 'ALTER USER'
     statements), and passwords given as arguments to the
     'PASSWORD()' and 'OLD_PASSWORD()' functions.

   * Assessing the strength of potential passwords for the
     'VALIDATE_PASSWORD_STRENGTH()' SQL function.

For information about writing this type of plugin, see
writing-password-validation-plugins.

*Protocol Trace Plugins*

MySQL supports the use of protocol trace plugins: client-side plugins
that implement tracing of communication between a client and the server
that takes place using the client/server protocol.  This capability can
be used in MySQL 5.7.2 and up.

For more information about protocol trace plugins, see
writing-protocol-trace-plugins.

*Query Rewrite Plugins*

As of MySQL 5.7.6, MySQL Server supports query rewrite plugins that can
examine and possibly modify statements received by the server before the
server executes them.  A query rewrite plugin takes statements either
before or after the server has parsed them.

A preparse query rewrite plugin has these characteristics:

   * The plugin enables rewriting of SQL statements arriving at the
     server before the server processes them.

   * The plugin receives a statement string and may return a different
     string.

A postparse query rewrite plugin has these characteristics:

   * The plugin enables statement rewriting based on parse trees.

   * The server parses each statement and passes its parse tree to the
     plugin, which may traverse the tree.  The plugin can return the
     original tree to the server for further processing, or construct a
     different tree and return that instead.

   * The plugin can use the 'mysql_parser' plugin service for these
     purposes:

        * To activate statement digest calculation and obtain the
          normalized version of statements independent of whether the
          Performance Schema produces digests.

        * To traverse parse trees.

        * To parse statements.  This is useful if the plugin constructs
          a new statement string from the parse tree.  The plugin can
          have the server parse the string to produce a new tree, then
          return that tree as the representation of the rewritten
          statement.

For more information about plugin services, see plugin-services.

Preparse and postparse query rewrite plugins share these
characteristics:

   * If a query rewrite plugin is installed, the '--log-raw' option
     affects statement logging as follows:

        * Without '--log-raw', the server logs the statement returned by
          the query rewrite plugin.  This may differ from the statement
          as received.

        * With '--log-raw', the server logs the original statement as
          received.

   * If a plugin rewrites a statement, the server decides whether to
     write it to the binary log (and thus to any replication slaves)
     based on the rewritten statement, not the original statement.  If a
     plugin rewrites only 'SELECT' statements to
     'SELECT' statements, there is no impact on binary logging
     because the server does not write 'SELECT'.
     statements to the binary log.

   * If a plugin rewrites a statement, the server produces a 'Note'
     message that the client can view using 'SHOW WARNINGS'.
     Messages have this format, where STMT_IN is the
     original statement and STMT_OUT is the rewritten statement:

          Query 'STMT_IN' rewritten to 'STMT_OUT' by a query rewrite plugin

MySQL distributions include a postparse query rewrite plugin named
'Rewriter'.  This plugin is rule based.  You can add rows to its rules
table to cause 'SELECT' statement rewriting.  For more
information, see rewriter-query-rewrite-plugin.

Query rewrite plugins use the same API as audit plugins.  For more
information about audit plugins, see writing-audit-plugins.

*Keyring Plugins*

As of MySQL 5.7.11, MySQL Server supports keyring plugins that enable
internal server components and plugins to securely store sensitive
information for later retrieval.

All MySQL distributions include a keyring plugin named 'keyring_file'.
MySQL Enterprise Edition distributions include additional keyring
plugins.  See keyring.

For more information about keyring plugins, see
writing-keyring-plugins.

28.2.2 Plugin API Characteristics
---------------------------------

The server plugin API has these characteristics:

   * All plugins have several things in common.

     Each plugin has a name that it can be referred to in SQL
     statements, as well as other metadata such as an author and a
     description that provide other information.  This information can
     be examined in the 'INFORMATION_SCHEMA.PLUGINS'
     table or using the 'SHOW PLUGINS'
     statement.

   * The plugin framework is extendable to accommodate different kinds
     of plugins.

     Although some aspects of the plugin API are common to all types of
     plugins, the API also permits type-specific interface elements so
     that different types of plugins can be created.  A plugin with one
     purpose can have an interface most appropriate to its own
     requirements and not the requirements of some other plugin type.

     Interfaces for several types of plugins exist, such as storage
     engines, full-text parser, and 'INFORMATION_SCHEMA' tables.  Others
     can be added.

   * Plugins can expose information to users.

     A plugin can implement system and status variables that are
     available through the 'SHOW VARIABLES' and
     'SHOW STATUS' statements.

   * The plugin API includes versioning information.

     The version information included in the plugin API enables a plugin
     library and each plugin that it contains to be self-identifying
     with respect to the API version that was used to build the library.
     If the API changes over time, the version numbers will change, but
     a server can examine a given plugin library's version information
     to determine whether it supports the plugins in the library.

     There are two types of version numbers.  The first is the version
     for the general plugin framework itself.  Each plugin library
     includes this kind of version number.  The second type of version
     applies to individual plugins.  Each specific type of plugin has a
     version for its interface, so each plugin in a library has a
     type-specific version number.  For example, a library containing a
     full-text parser plugin has a general plugin API version number,
     and the plugin has a version number specific to the full-text
     plugin interface.

   * The plugin API implements security restrictions.

     A plugin library must be installed in a specific dedicated
     directory for which the location is controlled by the server and
     cannot be changed at runtime.  Also, the library must contain
     specific symbols that identify it as a plugin library.  The server
     will not load something as a plugin if it was not built as a
     plugin.

   * Plugins have access to server services.

     The services interface exposes server functionality that plugins
     can access using ordinary function calls.  For details, see
     plugin-services.

In some respects, the server plugin API is similar to the older
user-defined function (UDF) API that it supersedes, but the plugin API
has several advantages over the older interface.  For example, UDFs had
no versioning information.  Also, the newer plugin interface eliminates
the security issues of the older UDF interface.  The older interface for
writing nonplugin UDFs permitted libraries to be loaded from any
directory searched by the system's dynamic linker, and the symbols that
identified the UDF library were relatively nonspecific.

The client plugin API has similar architectural characteristics, but
client plugins have no direct access to the server the way server
plugins do.

28.2.3 Plugin API Components
----------------------------

The server plugin implementation comprises several components.

SQL statements:

   * 'INSTALL PLUGIN' registers a plugin in the
     'mysql.plugin' table and loads the plugin code.

   * 'UNINSTALL PLUGIN' unregisters a plugin
     from the 'mysql.plugin' table and unloads the plugin code.

   * The 'WITH PARSER' clause for full-text index creation associates a
     full-text parser plugin with a given 'FULLTEXT' index.

   * 'SHOW PLUGINS' displays information about
     server plugins.

Command-line options and system variables:

   * The '--plugin-load' option enables plugins to be loaded at server
     startup time.

   * The 'plugin_dir' system variable indicates the location of the
     directory where all plugins must be installed.  The value of this
     variable can be specified at server startup with a
     '--plugin_dir=DIR_NAME' option.  'mysql_config --plugindir'
     displays the default plugin directory path name.

For additional information about plugin loading, see
server-plugin-loading.

Plugin-related tables:

   * The 'INFORMATION_SCHEMA.PLUGINS' table
     contains plugin information.

   * The 'mysql.plugin' table lists each plugin that was installed with
     'INSTALL PLUGIN' and is required for plugin
     use.  For new MySQL installations, this table is created during the
     installation process.

The client plugin implementation is simpler:

   * For the 'mysql_options()'. C API function, the
     'MYSQL_DEFAULT_AUTH' and 'MYSQL_PLUGIN_DIR' options enable client
     programs to load authentication plugins.

   * There are C API functions that enable management of client plugins.

To examine how MySQL implements plugins, consult the following source
files in a MySQL source distribution:

   * In the 'include/mysql' directory, 'plugin.h' exposes the public
     plugin API. This file should be examined by anyone who wants to
     write a plugin library.  'plugin_XXX.h' files provide additional
     information that pertains to specific types of plugins.
     'client_plugin.h' contains information specific to client plugins.

   * In the 'sql' directory, 'sql_plugin.h' and 'sql_plugin.cc' comprise
     the internal plugin implementation.  'sql_acl.cc' is where the
     server uses authentication plugins.  These files need not be
     consulted by plugin developers.  They may be of interest for those
     who want to know more about how the server handles plugins.

   * In the 'sql-common' directory, 'client_plugin.h' implements the C
     API client plugin functions, and 'client.c' implements client
     authentication support.  These files need not be consulted by
     plugin developers.  They may be of interest for those who want to
     know more about how the server handles plugins.

28.2.4 Writing Plugins
----------------------

To create a plugin library, you must provide the required descriptor
information that indicates what plugins the library file contains, and
write the interface functions for each plugin.

Every server plugin must have a general descriptor that provides
information to the plugin API, and a type-specific descriptor that
provides information about the plugin interface for a given type of
plugin.  The structure of the general descriptor is the same for all
plugin types.  The structure of the type-specific descriptor varies
among plugin types and is determined by the requirements of what the
plugin needs to do.  The server plugin interface also enables plugins to
expose status and system variables.  These variables become visible
through the 'SHOW STATUS' and 'SHOW VARIABLES'
statements and the corresponding
'INFORMATION_SCHEMA' tables.

For client-side plugins, the architecture is a bit different.  Each
plugin must have a descriptor, but there is no division into separate
general and type-specific descriptors.  Instead, the descriptor begins
with a fixed set of members common to all client plugin types, and the
common members are followed by any additional members required to
implement the specific plugin type.

You can write plugins in C or C++ (or another language that can use C
calling conventions).  Plugins are loaded and unloaded dynamically, so
your operating system must support dynamic loading and you must have
compiled the calling application dynamically (not statically).  For
server plugins, this means that 'mysqld' must be linked
dynamically.

A server plugin contains code that becomes part of the running server,
so when you write the plugin, you are bound by any and all constraints
that otherwise apply to writing server code.  For example, you may have
problems if you attempt to use functions from the 'libstdc++' library.
These constraints may change in future versions of the server, so it is
possible that server upgrades will require revisions to plugins
originally written for older servers.  For information about these
constraints, see source-configuration-options, and
compilation-problems.

Client plugin writers should avoid dependencies on what symbols the
calling application has because you cannot be sure what applications
will use the plugin.

28.2.4.1 Overview of Plugin Writing
...................................

The following procedure provides an overview of the steps needed to
create a plugin library.  The next sections provide additional details
on setting plugin data structures and writing specific types of plugins.

  1. In the plugin source file, include the header files that the plugin
     library needs.  The 'plugin.h' file is required, and the library
     might require other files as well.  For example:

          #include <stdlib.h>
          #include <ctype.h>
          #include <mysql/plugin.h>

  2. Set up the descriptor information for the plugin library file.  For
     server plugins, write the library descriptor, which must contain
     the general plugin descriptor for each server plugin in the file.
     For more information, see server-plugin-descriptors.  In
     addition, set up the type-specific descriptor for each server
     plugin in the library.  Each plugin's general descriptor points to
     its type-specific descriptor.

     For client plugins, write the client descriptor.  For more
     information, see client-plugin-descriptors.

  3. Write the plugin interface functions for each plugin.  For example,
     each plugin's general plugin descriptor points to the
     initialization and deinitialization functions that the server
     should invoke when it loads and unloads the plugin.  The plugin's
     type-specific description may also point to interface functions.

  4. For server plugins, set up the status and system variables, if
     there are any.

  5. Compile the plugin library as a shared library and install it in
     the plugin directory.  For more information, see
     compiling-plugin-libraries.

  6. For server plugins, register the plugin with the server.  For more
     information, see server-plugin-loading.

  7. Test the plugin to verify that it works properly.

28.2.4.2 Plugin Data Structures
...............................

A plugin library file includes descriptor information to indicate what
plugins it contains.

If the plugin library contains any server plugins, it must include the
following descriptor information:

   * A library descriptor indicates the general server plugin API
     version number used by the library and contains a general plugin
     descriptor for each server plugin in the library.  To provide the
     framework for this descriptor, invoke two macros from the
     'plugin.h' header file:

          mysql_declare_plugin(NAME)
           ... ONE OR MORE SERVER PLUGIN DESCRIPTORS HERE ...
          mysql_declare_plugin_end;

     The macros expand to provide a declaration for the API version
     automatically.  You must provide the plugin descriptors.

   * Within the library descriptor, each general server plugin is
     described by a 'st_mysql_plugin' structure.  This plugin descriptor
     structure contains information that is common to every type of
     server plugin: A value that indicates the plugin type; the plugin
     name, author, description, and license type; pointers to the
     initialization and deinitialization functions that the server
     invokes when it loads and unloads the plugin, and pointers to any
     status or system variables the plugin implements.

   * Each general server plugin descriptor within the library descriptor
     also contains a pointer to a type-specific plugin descriptor.  The
     structure of the type-specific descriptors varies from one plugin
     type to another because each type of plugin can have its own API. A
     type-specific plugin descriptor contains a type-specific API
     version number and pointers to the functions that are needed to
     implement that plugin type.  For example, a full-text parser plugin
     has initialization and deinitialization functions, and a main
     parsing function.  The server invokes these functions when it uses
     the plugin to parse text.

The plugin library also contains the interface functions that are
referenced by the general and type-specific descriptors for each plugin
in the library.

If the plugin library contains a client plugin, it must include a
descriptor for the plugin.  The descriptor begins with a fixed set of
members common to all client plugins, followed by any members specific
to the plugin type.  To provide the descriptor framework, invoke two
macros from the 'client_plugin.h' header file:

     mysql_declare_client_plugin(PLUGIN_TYPE)
        ... MEMBERS COMMON TO ALL CLIENT PLUGINS ...
        ... TYPE-SPECIFIC EXTRA MEMBERS ...
     mysql_end_client_plugin;

The plugin library also contains any interface functions referenced by
the client descriptor.

The 'mysql_declare_plugin()' and 'mysql_declare_client_plugin()' macros
differ somewhat in how they can be invoked, which has implications for
the contents of plugin libraries.  The following guidelines summarize
the rules:

   * 'mysql_declare_plugin()' and 'mysql_declare_client_plugin()' can
     both be used in the same source file, which means that a plugin
     library can contain both server and client plugins.  However, each
     of 'mysql_declare_plugin()' and 'mysql_declare_client_plugin()' can
     be used at most once.

   * 'mysql_declare_plugin()' permits multiple server plugin
     declarations, so a plugin library can contain multiple server
     plugins.

   * 'mysql_declare_client_plugin()' permits only a single client plugin
     declaration.  To create multiple client plugins, separate plugin
     libraries must be used.

When a client program looks for a client plugin that is in a plugin
library and not built into 'libmysqlclient', it looks for a file with a
base name that is the same as the plugin name.  For example, if a
program needs to use a client authentication plugin named 'auth_xxx' on
a system that uses '.so' as the library suffix, it looks in the file
named 'auth_xxx.so'.  (On OS X, the program looks first for
'auth_xxx.dylib', then for 'auth_xxx.so'.)  For this reason, if a plugin
library contains a client plugin, the library must have the same base
name as that plugin.

The same is not true for a library that contains server plugins.  The
'--plugin-load' option and the 'INSTALL PLUGIN'.
statement provide the library file name explicitly, so there need be no
explicit relationship between the library name and the name of any
server plugins it contains.

28.2.4.3 Server Plugin Library and Plugin Descriptors
.....................................................

Every plugin library that contains server plugins must include a library
descriptor that contains the general plugin descriptor for each server
plugin in the file.  This section discusses how to write the library and
general descriptors for server plugins.

The library descriptor must define two symbols:

   * '_mysql_plugin_interface_version_' specifies the version number of
     the general plugin framework.  This is given by the
     'MYSQL_PLUGIN_INTERFACE_VERSION' symbol, which is defined in the
     'plugin.h' file.

   * '_mysql_plugin_declarations_' defines an array of plugin
     declarations, terminated by a declaration with all members set to
     0.  Each declaration is an instance of the 'st_mysql_plugin'
     structure (also defined in 'plugin.h').  There must be one of these
     for each server plugin in the library.

If the server does not find those two symbols in a library, it does not
accept it as a legal plugin library and rejects it with an error.  This
prevents use of a library for plugin purposes unless it was built
specifically as a plugin library.

The conventional way to define the two required symbols is by using the
'mysql_declare_plugin()' and 'mysql_declare_plugin_end' macros from the
'plugin.h' file:

     mysql_declare_plugin(NAME)
      ... ONE OR MORE SERVER PLUGIN DESCRIPTORS HERE ...
     mysql_declare_plugin_end;

Each server plugin must have a general descriptor that provides
information to the server plugin API. The general descriptor has the
same structure for all plugin types.  The 'st_mysql_plugin' structure in
the 'plugin.h' file defines this descriptor:

     struct st_mysql_plugin
     {
       int type;             /* the plugin type (a MYSQL_XXX_PLUGIN value)   */
       void *info;           /* pointer to type-specific plugin descriptor   */
       const char *name;     /* plugin name                                  */
       const char *author;   /* plugin author (for I_S.PLUGINS)              */
       const char *descr;    /* general descriptive text (for I_S.PLUGINS)   */
       int license;          /* the plugin license (PLUGIN_LICENSE_XXX)      */
       int (*init)(void *);  /* the function to invoke when plugin is loaded */
       int (*deinit)(void *);/* the function to invoke when plugin is unloaded */
       unsigned int version; /* plugin version (for I_S.PLUGINS)             */
       struct st_mysql_show_var *status_vars;
       struct st_mysql_sys_var **system_vars;
       void * __reserved1;   /* reserved for dependency checking             */
       unsigned long flags;  /* flags for plugin */
     };

The 'st_mysql_plugin' descriptor structure members are used as follows.
'char *' members should be specified as null-terminated strings.

   * 'type': The plugin type.  This must be one of the plugin-type
     values from 'plugin.h':

          /*
            The allowable types of plugins
          */
          #define MYSQL_UDF_PLUGIN             0  /* User-defined function        */
          #define MYSQL_STORAGE_ENGINE_PLUGIN  1  /* Storage Engine               */
          #define MYSQL_FTPARSER_PLUGIN        2  /* Full-text parser plugin      */
          #define MYSQL_DAEMON_PLUGIN          3  /* The daemon/raw plugin type */
          #define MYSQL_INFORMATION_SCHEMA_PLUGIN  4  /* The I_S plugin type */
          #define MYSQL_AUDIT_PLUGIN           5  /* The Audit plugin type        */
          #define MYSQL_REPLICATION_PLUGIN     6  /* The replication plugin type */
          #define MYSQL_AUTHENTICATION_PLUGIN  7  /* The authentication plugin type */
          ...

     For example, for a full-text parser plugin, the 'type' value is
     'MYSQL_FTPARSER_PLUGIN'.

   * 'info': A pointer to the type-specific descriptor for the plugin.
     This descriptor's structure depends on the particular type of
     plugin, unlike that of the general plugin descriptor structure.
     For version-control purposes, the first member of the type-specific
     descriptor for every plugin type is expected to be the interface
     version for the type.  This enables the server to check the
     type-specific version for every plugin no matter its type.
     Following the version number, the descriptor includes any other
     members needed, such as callback functions and other information
     needed by the server to invoke the plugin properly.  Later sections
     on writing particular types of server plugins describe the
     structure of their type-specific descriptors.

   * 'name': A string that gives the plugin name.  This is the name that
     will be listed in the 'mysql.plugin' table and by which you refer
     to the plugin in SQL statements such as 'INSTALL PLUGIN'
     and 'UNINSTALL PLUGIN', or
     with the '--plugin-load' option.  The name is also visible in the
     'INFORMATION_SCHEMA.PLUGINS' table or the
     output from 'SHOW PLUGINS'.

     The plugin name should not begin with the name of any server
     option.  If it does, the server will fail to initialize it.  For
     example, the server has a '--socket' option, so you should not use
     a plugin name such as 'socket', 'socket_plugin', and so forth.

   * 'author': A string naming the plugin author.  This can be whatever
     you like.

   * 'desc': A string that provides a general description of the plugin.
     This can be whatever you like.

   * 'license': The plugin license type.  The value can be one of
     'PLUGIN_LICENSE_PROPRIETARY', 'PLUGIN_LICENSE_GPL', or
     'PLUGIN_LICENSE_BSD'.

   * 'init': A once-only initialization function, or 'NULL' if there is
     no such function.  The server executes this function when it loads
     the plugin, which happens for 'INSTALL PLUGIN'
     or, for plugins listed in the 'mysql.plugin' table,
     at server startup.  The function takes one argument that points to
     the internal structure used to identify the plugin.  It returns
     zero for success and nonzero for failure.

   * 'deinit': A once-only deinitialization function, or 'NULL' if there
     is no such function.  The server executes this function when it
     unloads the plugin, which happens for 'UNINSTALL PLUGIN'
     or, for plugins listed in the 'mysql.plugin'
     table, at server shutdown.  The function takes one argument that
     points to the internal structure used to identify the plugin It
     returns zero for success and nonzero for failure.

   * 'version': The plugin version number.  When the plugin is
     installed, this value can be retrieved from the
     'INFORMATION_SCHEMA.PLUGINS' table.  The value
     includes major and minor numbers.  If you write the value as a hex
     constant, the format is '0xMMNN', where MM and 'NN' are the major
     and minor numbers, respectively.  For example, '0x0302' represents
     version 3.2.

   * 'status_vars': A pointer to a structure for status variables
     associated with the plugin, or 'NULL' if there are no such
     variables.  When the plugin is installed, these variables are
     displayed in the output of the 'SHOW STATUS'.
     statement.

     The 'status_vars' member, if not 'NULL', points to an array of
     'st_mysql_show_var' structures that describe status variables.  See
     plugin-status-system-variables.

   * 'system_vars': A pointer to a structure for system variables
     associated with the plugin, or 'NULL' if there are no such
     variables.  These options and system variables can be used to help
     initialize variables within the plugin.  When the plugin is
     installed, these variables are displayed in the output of the
     'SHOW VARIABLES' statement.

     The 'system_vars' member, if not 'NULL', points to an array of
     'st_mysql_sys_var' structures that describe system variables.  See
     plugin-status-system-variables.

   * '__reserved1': A placeholder for the future.  It should be set to
     'NULL'.

   * 'flags': Plugin flags.  Individual bits correspond to different
     flags.  The value should be set to the OR of the applicable flags.
     These flags are available:

          #define PLUGIN_OPT_NO_INSTALL   1UL   /* Not dynamically loadable */
          #define PLUGIN_OPT_NO_UNINSTALL 2UL   /* Not dynamically unloadable */

     'PLUGIN_OPT_NO_INSTALL' indicates that the plugin cannot be loaded
     at runtime with the 'INSTALL PLUGIN'.
     statement.  This is appropriate for plugins that must be loaded at
     server startup with the '--plugin-load' option.
     'PLUGIN_OPT_NO_UNINSTALL' indicates that the plugin cannot be
     unloaded at runtime with the 'UNINSTALL PLUGIN'
     statement.

The server invokes the 'init' and 'deinit' functions in the general
plugin descriptor only when loading and unloading the plugin.  They have
nothing to do with use of the plugin such as happens when an SQL
statement causes the plugin to be invoked.

For example, the descriptor information for a library that contains a
single full-text parser plugin named 'simple_parser' looks like this:

     mysql_declare_plugin(ftexample)
     {
       MYSQL_FTPARSER_PLUGIN,      /* type                            */
       &simple_parser_descriptor,  /* descriptor                      */
       "simple_parser",            /* name                            */
       "Oracle Corporation",       /* author                          */
       "Simple Full-Text Parser",  /* description                     */
       PLUGIN_LICENSE_GPL,         /* plugin license                  */
       simple_parser_plugin_init,  /* init function (when loaded)     */
       simple_parser_plugin_deinit,/* deinit function (when unloaded) */
       0x0001,                     /* version                         */
       simple_status,              /* status variables                */
       simple_system_variables,    /* system variables                */
       NULL,
       0
     }
     mysql_declare_plugin_end;

For a full-text parser plugin, the type must be 'MYSQL_FTPARSER_PLUGIN'.
This is the value that identifies the plugin as being legal for use in a
'WITH PARSER' clause when creating a 'FULLTEXT' index.  (No other plugin
type is legal for this clause.)

'plugin.h' defines the 'mysql_declare_plugin()' and
'mysql_declare_plugin_end' macros like this:

     #ifndef MYSQL_DYNAMIC_PLUGIN
     #define __MYSQL_DECLARE_PLUGIN(NAME, VERSION, PSIZE, DECLS) \
     MYSQL_PLUGIN_EXPORT int VERSION= MYSQL_PLUGIN_INTERFACE_VERSION; \
     MYSQL_PLUGIN_EXPORT int PSIZE= sizeof(struct st_mysql_plugin); \
     MYSQL_PLUGIN_EXPORT struct st_mysql_plugin DECLS[]= {
     #else
     #define __MYSQL_DECLARE_PLUGIN(NAME, VERSION, PSIZE, DECLS) \
     MYSQL_PLUGIN_EXPORT int _mysql_plugin_interface_version_= MYSQL_PLUGIN_INTERFACE_VERSION; \
     MYSQL_PLUGIN_EXPORT int _mysql_sizeof_struct_st_plugin_= sizeof(struct st_mysql_plugin); \
     MYSQL_PLUGIN_EXPORT struct st_mysql_plugin _mysql_plugin_declarations_[]= {
     #endif

     #define mysql_declare_plugin(NAME) \
     __MYSQL_DECLARE_PLUGIN(NAME, \
                      builtin_ ## NAME ## _plugin_interface_version, \
                      builtin_ ## NAME ## _sizeof_struct_st_plugin, \
                      builtin_ ## NAME ## _plugin)

     #define mysql_declare_plugin_end ,{0,0,0,0,0,0,0,0,0,0,0,0,0}}

*Note*:

Those declarations define the '_mysql_plugin_interface_version_' symbol
only if the 'MYSQL_DYNAMIC_PLUGIN' symbol is defined.  This means that
'-DMYSQL_DYNAMIC_PLUGIN' must be provided as part of the compilation
command to build the plugin as a shared library.

When the macros are used as just shown, they expand to the following
code, which defines both of the required symbols
('_mysql_plugin_interface_version_' and '_mysql_plugin_declarations_'):

     int _mysql_plugin_interface_version_= MYSQL_PLUGIN_INTERFACE_VERSION;
     int _mysql_sizeof_struct_st_plugin_= sizeof(struct st_mysql_plugin);
     struct st_mysql_plugin _mysql_plugin_declarations_[]= {
     {
       MYSQL_FTPARSER_PLUGIN,      /* type                            */
       &simple_parser_descriptor,  /* descriptor                      */
       "simple_parser",            /* name                            */
       "Oracle Corporation",       /* author                          */
       "Simple Full-Text Parser",  /* description                     */
       PLUGIN_LICENSE_GPL,         /* plugin license                  */
       simple_parser_plugin_init,  /* init function (when loaded)     */
       simple_parser_plugin_deinit,/* deinit function (when unloaded) */
       0x0001,                     /* version                         */
       simple_status,              /* status variables                */
       simple_system_variables,    /* system variables                */
       NULL,
       0
     }
       ,{0,0,0,0,0,0,0,0,0,0,0,0}}
     };

The preceding example declares a single plugin in the general
descriptor, but it is possible to declare multiple plugins.  List the
declarations one after the other between 'mysql_declare_plugin()' and
'mysql_declare_plugin_end', separated by commas.

MySQL server plugins can be written in C or C++ (or another language
that can use C calling conventions).  If you write a C++ plugin, one C++
feature that you should not use is nonconstant variables to initialize
global structures.  Members of structures such as the 'st_mysql_plugin'
structure should be initialized only with constant variables.  The
'simple_parser' descriptor shown earlier is permissible in a C++ plugin
because it satisfies that requirement:

     mysql_declare_plugin(ftexample)
     {
       MYSQL_FTPARSER_PLUGIN,      /* type                            */
       &simple_parser_descriptor,  /* descriptor                      */
       "simple_parser",            /* name                            */
       "Oracle Corporation",       /* author                          */
       "Simple Full-Text Parser",  /* description                     */
       PLUGIN_LICENSE_GPL,         /* plugin license                  */
       simple_parser_plugin_init,  /* init function (when loaded)     */
       simple_parser_plugin_deinit,/* deinit function (when unloaded) */
       0x0001,                     /* version                         */
       simple_status,              /* status variables                */
       simple_system_variables,    /* system variables                */
       NULL,
       0
     }
     mysql_declare_plugin_end;

Here is another valid way to write the general descriptor.  It uses
constant variables to indicate the plugin name, author, and description:

     const char *simple_parser_name = "simple_parser";
     const char *simple_parser_author = "Oracle Corporation";
     const char *simple_parser_description = "Simple Full-Text Parser";

     mysql_declare_plugin(ftexample)
     {
       MYSQL_FTPARSER_PLUGIN,      /* type                            */
       &simple_parser_descriptor,  /* descriptor                      */
       simple_parser_name,         /* name                            */
       simple_parser_author,       /* author                          */
       simple_parser_description,  /* description                     */
       PLUGIN_LICENSE_GPL,         /* plugin license                  */
       simple_parser_plugin_init,  /* init function (when loaded)     */
       simple_parser_plugin_deinit,/* deinit function (when unloaded) */
       0x0001,                     /* version                         */
       simple_status,              /* status variables                */
       simple_system_variables,    /* system variables                */
       NULL,
       0
     }
     mysql_declare_plugin_end;

However, the following general descriptor is invalid.  It uses structure
members to indicate the plugin name, author, and description, but
structures are not considered constant initializers in C++:

     typedef struct
     {
       const char *name;
       const char *author;
       const char *description;
     } plugin_info;

     plugin_info parser_info = {
       "simple_parser",
       "Oracle Corporation",
       "Simple Full-Text Parser"
     };

     mysql_declare_plugin(ftexample)
     {
       MYSQL_FTPARSER_PLUGIN,      /* type                            */
       &simple_parser_descriptor,  /* descriptor                      */
       parser_info.name,           /* name                            */
       parser_info.author,         /* author                          */
       parser_info.description,    /* description                     */
       PLUGIN_LICENSE_GPL,         /* plugin license                  */
       simple_parser_plugin_init,  /* init function (when loaded)     */
       simple_parser_plugin_deinit,/* deinit function (when unloaded) */
       0x0001,                     /* version                         */
       simple_status,              /* status variables                */
       simple_system_variables,    /* system variables                */
       NULL,
       0
     }
     mysql_declare_plugin_end;

28.2.4.4 Server Plugin Status and System Variables
..................................................

The server plugin interface enables plugins to expose status and system
variables using the 'status_vars' and 'system_vars' members of the
general plugin descriptor.

The 'status_vars' member of the general plugin descriptor, if not 0,
points to an array of 'st_mysql_show_var' structures, each of which
describes one status variable, followed by a structure with all members
set to 0.  The 'st_mysql_show_var' structure has this definition:

     struct st_mysql_show_var {
       const char *name;
       char *value;
       enum enum_mysql_show_type type;
     };

The following table shows the permissible status variable 'type' values
and what the corresponding variable should be.

*Server Plugin Status Variable Types*

Variable Type          Meaning

'SHOW_BOOL'            Pointer to a boolean variable

'SHOW_INT'             Pointer to an integer variable

'SHOW_LONG'            Pointer to a long integer variable

'SHOW_LONGLONG'        Pointer to a longlong integer variable

'SHOW_CHAR'            A string

'SHOW_CHAR_PTR'        Pointer to a string

'SHOW_ARRAY'           Pointer to another 'st_mysql_show_var' array

'SHOW_FUNC'            Pointer to a function

'SHOW_DOUBLE'          Pointer to a double

For the 'SHOW_FUNC' type, the function is called and fills in its 'out'
parameter, which then provides information about the variable to be
displayed.  The function has this signature:

     #define SHOW_VAR_FUNC_BUFF_SIZE 1024

     typedef int (*mysql_show_var_func) (void *thd,
                                         struct st_mysql_show_var *out,
                                         char *buf);

The 'system_vars' member, if not 0, points to an array of
'st_mysql_sys_var' structures, each of which describes one system
variable (which can also be set from the command-line or configuration
file), followed by a structure with all members set to 0.  The
'st_mysql_sys_var' structure is defined as follows:

     struct st_mysql_sys_var {
      int flags;
      const char *name, *comment;
      int (*check)(THD*, struct st_mysql_sys_var *, void*, st_mysql_value*);
      void (*update)(THD*, struct st_mysql_sys_var *, void*, const void*);
     };

Additional fields are append as required depending upon the flags.

For convenience, a number of macros are defined that make creating new
system variables within a plugin much simpler.

Throughout the macros, the following fields are available:

   * 'name': An unquoted identifier for the system variable.

   * 'varname': The identifier for the static variable.  Where not
     available, it is the same as the 'name' field.

   * 'opt': Additional use flags for the system variable.  The following
     table shows the permissible flags.

     *Server Plugin System Variable Flags*

     Flag Value         Description

     'PLUGIN_VAR_READONLY'The system variable is read only

     'PLUGIN_VAR_NOSYSVAR'The system variable is not user visible at runtime

     'PLUGIN_VAR_NOCMDOPT'The system variable is not configurable from the
                        command line

     'PLUGIN_VAR_NOCMDARG'No argument is required at the command line
                        (typically used for boolean variables)

     'PLUGIN_VAR_RQCMDARG'An argument is required at the command line (this is
                        the default)

     '                  An argument is optional at the command line
     PLUGIN_VAR_OPCMDARG'

     'PLUGIN_VAR_MEMALLOC'Used for string variables; indicates that memory is
                        to be allocated for storage of the string

   * 'comment': A descriptive comment to be displayed in the server help
     message.  'NULL' if this variable is to be hidden.

   * 'check': The check function, 'NULL' for default.

   * 'update': The update function, 'NULL' for default.

   * 'default': The variable default value.

   * 'minimum': The variable minimum value.

   * 'maximum': The variable maximum value.

   * 'blocksize': The variable block size.  When the value is set, it is
     rounded to the nearest multiple of 'blocksize'.

A system variable may be accessed either by using the static variable
directly or by using the 'SYSVAR()'accessor macro.  The 'SYSVAR()' macro
is provided for completeness.  Usually it should be used only when the
code cannot directly access the underlying variable.

For example:

     static int my_foo;
     static MYSQL_SYSVAR_INT(foo_var, my_foo,
                             PLUGIN_VAR_RQCMDARG, "foo comment",
                             NULL, NULL, 0, 0, INT_MAX, 0);
      ...
        SYSVAR(foo_var)= value;
        value= SYSVAR(foo_var);
        my_foo= value;
        value= my_foo;

Session variables may be accessed only through the 'THDVAR()' accessor
macro.  For example:

     static MYSQL_THDVAR_BOOL(some_flag,
                              PLUGIN_VAR_NOCMDARG, "flag comment",
                              NULL, NULL, FALSE);
      ...
        if (THDVAR(thd, some_flag))
        {
          do_something();
          THDVAR(thd, some_flag)= FALSE;
        }

All global and session system variables must be published to
'mysqld' before use.  This is done by constructing a
'NULL'-terminated array of the variables and linking to it in the plugin
public interface.  For example:

     static struct st_mysql_sys_var *my_plugin_vars[]= {
       MYSQL_SYSVAR(foo_var),
       MYSQL_SYSVAR(some_flag),
       NULL
     };
     mysql_declare_plugin(fooplug)
     {
       MYSQL_..._PLUGIN,
       &plugin_data,
       "fooplug",
       "foo author",
       "This does foo!",
       PLUGIN_LICENSE_GPL,
       foo_init,
       foo_fini,
       0x0001,
       NULL,
       my_plugin_vars,
       NULL,
       0
     }
     mysql_declare_plugin_end;

The following convenience macros enable you to declare different types
of system variables:

   * Boolean system variables of type 'my_bool', which is a 1-byte
     boolean.  (0 = FALSE, 1 = TRUE)

          MYSQL_THDVAR_BOOL(name, opt, comment, check, update, default)
          MYSQL_SYSVAR_BOOL(name, varname, opt, comment, check, update, default)

   * String system variables of type 'char*', which is a pointer to a
     null-terminated string.

          MYSQL_THDVAR_STR(name, opt, comment, check, update, default)
          MYSQL_SYSVAR_STR(name, varname, opt, comment, check, update, default)

   * Integer system variables, of which there are several varieties.

        * An 'int' system variable, which is typically a 4-byte signed
          word.

               MYSQL_THDVAR_INT(name, opt, comment, check, update, default, min, max, blk)
               MYSQL_SYSVAR_INT(name, varname, opt, comment, check, update, default,
                              minimum, maximum, blocksize)

        * An 'unsigned int' system variable, which is typically a 4-byte
          unsigned word.

               MYSQL_THDVAR_UINT(name, opt, comment, check, update, default, min, max, blk)
               MYSQL_SYSVAR_UINT(name, varname, opt, comment, check, update, default,
                               minimum, maximum, blocksize)

        * A 'long' system variable, which is typically either a 4- or
          8-byte signed word.

               MYSQL_THDVAR_LONG(name, opt, comment, check, update, default, min, max, blk)
               MYSQL_SYSVAR_LONG(name, varname, opt, comment, check, update, default,
                               minimum, maximum, blocksize)

        * An 'unsigned long' system variable, which is typically either
          a 4- or 8-byte unsigned word.

               MYSQL_THDVAR_ULONG(name, opt, comment, check, update, default, min, max, blk)
               MYSQL_SYSVAR_ULONG(name, varname, opt, comment, check, update, default,
                                minimum, maximum, blocksize)

        * A 'long long' system variable, which is typically an 8-byte
          signed word.

               MYSQL_THDVAR_LONGLONG(name, opt, comment, check, update,
                                   default, minimum, maximum, blocksize)
               MYSQL_SYSVAR_LONGLONG(name, varname, opt, comment, check, update,
                                   default, minimum, maximum, blocksize)

        * An 'unsigned long long' system variable, which is typically an
          8-byte unsigned word.

               MYSQL_THDVAR_ULONGLONG(name, opt, comment, check, update,
                                    default, minimum, maximum, blocksize)
               MYSQL_SYSVAR_ULONGLONG(name, varname, opt, comment, check, update,
                                    default, minimum, maximum, blocksize)

        * A 'double' system variable, which is typically an 8-byte
          signed word.  These accessor macros were added in MySQL 5.7.2.

               MYSQL_THDVAR_DOUBLE(name, opt, comment, check, update,
                                    default, minimum, maximum, blocksize)
               MYSQL_SYSVAR_DOUBLE(name, varname, opt, comment, check, update,
                                    default, minimum, maximum, blocksize)

        * An 'unsigned long' system variable, which is typically either
          a 4- or 8-byte unsigned word.  The range of possible values is
          an ordinal of the number of elements in the 'typelib',
          starting from 0.

               MYSQL_THDVAR_ENUM(name, opt, comment, check, update, default, typelib)
               MYSQL_SYSVAR_ENUM(name, varname, opt, comment, check, update,
                               default, typelib)

        * An 'unsigned long long' system variable, which is typically an
          8-byte unsigned word.  Each bit represents an element in the
          'typelib'.

               MYSQL_THDVAR_SET(name, opt, comment, check, update, default, typelib)
               MYSQL_SYSVAR_SET(name, varname, opt, comment, check, update,
                              default, typelib)

Internally, all mutable and plugin system variables are stored in a
'HASH' structure.

Display of the server command-line help text is handled by compiling a
'DYNAMIC_ARRAY' of all variables relevant to command-line options,
sorting them, and then iterating through them to display each option.

When a command-line option has been handled, it is then removed from the
'argv' by the 'handle_option()' function ('my_getopt.c'); in effect, it
is consumed.

The server processes command-line options during the plugin installation
process, immediately after the plugin has been successfully loaded but
before the plugin initialization function has been called

Plugins loaded at runtime do not benefit from any configuration options
and must have usable defaults.  Once they are installed, they are loaded
at 'mysqld' initialization time and configuration options
can be set at the command line or within 'my.cnf'.

Plugins should consider the 'thd' parameter to be read only.

28.2.4.5 Client Plugin Descriptors
..................................

Each client plugin must have a descriptor that provides information to
the client plugin API. The descriptor structure begins with a fixed set
of members common to all client plugins, followed by any members
specific to the plugin type.

The 'st_mysql_client_plugin' structure in the 'client_plugin.h' file
defines a 'generic' descriptor that contains the common members:

     struct st_mysql_client_plugin
     {
       int type;
       unsigned int interface_version;
       const char *name;
       const char *author;
       const char *desc;
       unsigned int version[3];
       const char *license;
       void *mysql_api;
       int (*init)(char *, size_t, int, va_list);
       int (*deinit)();
       int (*options)(const char *option, const void *);
     };

The common 'st_mysql_client_plugin' descriptor structure members are
used as follows.  'char *' members should be specified as
null-terminated strings.

   * 'type': The plugin type.  This must be one of the plugin-type
     values from 'client_plugin.h', such as
     'MYSQL_CLIENT_AUTHENTICATION_PLUGIN'.

   * 'interface_version': The plugin interface version.  For example,
     this is 'MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION' for
     an authentication plugin.

   * 'name': A string that gives the plugin name.  This is the name by
     which you refer to the plugin when you call
     'mysql_options()' with the 'MYSQL_DEFAULT_AUTH'
     option or specify the '--default-auth' option to a MySQL client
     program.

   * 'author': A string naming the plugin author.  This can be whatever
     you like.

   * 'desc': A string that provides a general description of the plugin.
     This can be whatever you like.

   * 'version': The plugin version as an array of three integers
     indicating the major, minor, and teeny versions.  For example,
     '{1,2,3}' indicates version 1.2.3.

   * 'license': A string that specifies the license type.

   * 'mysql_api': For internal use.  Specify it as 'NULL' in the plugin
     descriptor.

   * 'init': A once-only initialization function, or 'NULL' if there is
     no such function.  The client library executes this function when
     it loads the plugin.  The function returns zero for success and
     nonzero for failure.

     The 'init' function uses its first two arguments to return an error
     message if an error occurs.  The first argument is a pointer to a
     'char' buffer, and the second argument indicates the buffer length.
     Any message returned by the 'init' function must be
     null-terminated, so the maximum message length is the buffer length
     minus one.  The next arguments are passed to
     'mysql_load_plugin()'.  The first indicates how
     many more arguments there are (0 if none), followed by any
     remaining arguments.

   * 'deinit': A once-only deinitialization function, or 'NULL' if there
     is no such function.  The client library executes this function
     when it unloads the plugin.  The function takes no arguments.  It
     returns zero for success and nonzero for failure.

   * 'options': A function for handling options passed to the plugin, or
     'NULL' if there is no such function.  The function takes two
     arguments representing the option name and a pointer to its value.
     The function returns zero for success and nonzero for failure.

For a given client plugin type, the common descriptor members may be
followed by additional members necessary to implement plugins of that
type.  For example, the 'st_mysql_client_plugin_AUTHENTICATION'
structure for authentication plugins has a function at the end that the
client library calls to perform authentication.

To declare a plugin, use the 'mysql_declare_client_plugin()' and
'mysql_end_client_plugin' macros:

     mysql_declare_client_plugin(PLUGIN_TYPE)
        ... MEMBERS COMMON TO ALL CLIENT PLUGINS ...
        ... TYPE-SPECIFIC EXTRA MEMBERS ...
     mysql_end_client_plugin;

Do not specify the 'type' or 'interface_version' member explicitly.  The
'mysql_declare_client_plugin()' macro uses the PLUGIN_TYPE argument to
generate their values automatically.  For example, declare an
authentication client plugin like this:

     mysql_declare_client_plugin(AUTHENTICATION)
       "my_auth_plugin",
       "Author Name",
       "My Client Authentication Plugin",
       {1,0,0},
       "GPL",
       NULL,
       my_auth_init,
       my_auth_deinit,
       my_auth_options,
       my_auth_main
     mysql_end_client_plugin;

This declaration uses the 'AUTHENTICATION' argument to set the 'type'
and 'interface_version' members to 'MYSQL_CLIENT_AUTHENTICATION_PLUGIN'
and 'MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION'.

Depending on the plugin type, the descriptor may have other members
following the common members.  For example, for an authentication
plugin, there is a function ('my_auth_main()' in the descriptor just
shown) that handles communication with the server.  See
writing-authentication-plugins.

Normally, a client program that supports the use of authentication
plugins causes a plugin to be loaded by calling 'mysql_options()'
to set the 'MYSQL_DEFAULT_AUTH' and 'MYSQL_PLUGIN_DIR'
options:

     char *plugin_dir = "PATH_TO_PLUGIN_DIR";
     char *default_auth = "PLUGIN_NAME";

     /* ... process command-line options ... */

     mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir);
     mysql_options(&mysql, MYSQL_DEFAULT_AUTH, default_auth);

Typically, the program will also accept '--plugin-dir' and
'--default-auth' options that enable users to override the default
values.

Should a client program require lower-level plugin management, the
client library contains functions that take an 'st_mysql_client_plugin'
argument.  See c-api-plugin-functions.

28.2.4.6 Compiling and Installing Plugin Libraries
..................................................

After your plugin is written, you must compile it and install it.  The
procedure for compiling shared objects varies from system to system.  If
you build your library using 'CMake', it should be able to generate the
correct compilation commands for your system.  If the library is named
'somepluglib', you should end up with a shared library file that has a
name something like 'somepluglib.so'.  (The '.so' file name suffix might
differ on your system.)

To use 'CMake', you'll need to set up the configuration files to enable
the plugin to be compiled and installed.  Use the plugin examples under
the 'plugin' directory of a MySQL source distribution as a guide.

Create 'CMakeLists.txt', which should look something like this:

     MYSQL_ADD_PLUGIN(somepluglib somepluglib.c
       MODULE_ONLY MODULE_OUTPUT_NAME "somepluglib")

When 'CMake' generates the 'Makefile', it should take care of passing to
the compilation command the '-DMYSQL_DYNAMIC_PLUGIN' flag, and passing
to the linker the '-lmysqlservices' flag, which is needed to link in any
functions from services provided through the plugin services interface.
See plugin-services.

Run 'CMake', then run 'make':

     shell> cmake .
     shell> make

If you need to specify configuration options to 'CMake', see
source-configuration-options, for a list.  For example, you might want
to specify 'CMAKE_INSTALL_PREFIX' to indicate the MySQL base directory
under which the plugin should be installed.  You can see what value to
use for this option with 'SHOW VARIABLES'.:

     mysql> SHOW VARIABLES LIKE 'basedir';
     +---------------+------------------+
     | Variable_name | Value            |
     +---------------+------------------+
     | base          | /usr/local/mysql |
     +---------------+------------------+

The location of the plugin directory where you should install the
library is given by the 'plugin_dir' system variable.  For example:

     mysql> SHOW VARIABLES LIKE 'plugin_dir';
     +---------------+-----------------------------------+
     | Variable_name | Value                             |
     +---------------+-----------------------------------+
     | plugin_dir    | /usr/local/mysql/lib/mysql/plugin |
     +---------------+-----------------------------------+

To install the plugin library, use 'make':

     shell> make install

Verify that 'make install' installed the plugin library in the proper
directory.  After installing it, make sure that the library permissions
permit it to be executed by the server.

28.2.4.7 Writing Full-Text Parser Plugins
.........................................

MySQL supports server-side full-text parser plugins with 'MyISAM'
and 'InnoDB'.  For
introductory information about full-text parser plugins, see
full-text-plugin-type.

A full-text parser plugin can be used to replace or modify the built-in
full-text parser.  This section describes how to write a full-text
parser plugin named 'simple_parser'.  This plugin performs parsing based
on simpler rules than those used by the MySQL built-in full-text parser:
Words are nonempty runs of whitespace characters.

The instructions use the source code in the 'plugin/fulltext' directory
of MySQL source distributions, so change location into that directory.
The following procedure describes how the plugin library is created:

  1. To write a full-text parser plugin, include the following header
     file in the plugin source file.  Other MySQL or general header
     files might also be needed, depending on the plugin capabilities
     and requirements.

          #include <mysql/plugin.h>

     'plugin.h' defines the 'MYSQL_FTPARSER_PLUGIN' server plugin type
     and the data structures needed to declare the plugin.

  2. Set up the library descriptor for the plugin library file.

     This descriptor contains the general plugin descriptor for the
     server plugin.  For a full-text parser plugin, the type must be
     'MYSQL_FTPARSER_PLUGIN'.  This is the value that identifies the
     plugin as being legal for use in a 'WITH PARSER' clause when
     creating a 'FULLTEXT' index.  (No other plugin type is legal for
     this clause.)

     For example, the library descriptor for a library that contains a
     single full-text parser plugin named 'simple_parser' looks like
     this:

          mysql_declare_plugin(ftexample)
          {
            MYSQL_FTPARSER_PLUGIN,      /* type                            */
            &simple_parser_descriptor,  /* descriptor                      */
            "simple_parser",            /* name                            */
            "Oracle Corporation",       /* author                          */
            "Simple Full-Text Parser",  /* description                     */
            PLUGIN_LICENSE_GPL,         /* plugin license                  */
            simple_parser_plugin_init,  /* init function (when loaded)     */
            simple_parser_plugin_deinit,/* deinit function (when unloaded) */
            0x0001,                     /* version                         */
            simple_status,              /* status variables                */
            simple_system_variables,    /* system variables                */
            NULL,
            0
          }
          mysql_declare_plugin_end;

     The 'name' member ('simple_parser') indicates the name to use for
     references to the plugin in statements such as 'INSTALL PLUGIN'
     or 'UNINSTALL PLUGIN'.
     This is also the name displayed by 'SHOW PLUGINS'
     or 'INFORMATION_SCHEMA.PLUGINS'.

     For more information, see server-plugin-descriptors.

  3. Set up the type-specific plugin descriptor.

     Each general plugin descriptor in the library descriptor points to
     a type-specific descriptor.  For a full-text parser plugin, the
     type-specific descriptor is an instance of the 'st_mysql_ftparser'
     structure in the 'plugin.h' file:

          struct st_mysql_ftparser
          {
            int interface_version;
            int (*parse)(MYSQL_FTPARSER_PARAM *param);
            int (*init)(MYSQL_FTPARSER_PARAM *param);
            int (*deinit)(MYSQL_FTPARSER_PARAM *param);
          };

     As shown by the structure definition, the descriptor has an
     interface version number and contains pointers to three functions.

     The interface version number is specified using a symbol, which is
     in the form: 'MYSQL_XXX_INTERFACE_VERSION'.  For full-text parser
     plugins, the symbol is 'MYSQL_FTPARSER_INTERFACE_VERSION'.  In the
     source code, you will find the actual interface version number for
     the full-text parser plugin defined in
     'include/mysql/plugin_ftparser.h'.  With the introduction of
     full-text parser plugin support for 'InnoDB', the interface version
     number was incremented in MySQL 5.7 from '0x0100' to '0x0101'.

     The 'init' and 'deinit' members should point to a function or be
     set to 0 if the function is not needed.  The 'parse' member must
     point to the function that performs the parsing.

     In the 'simple_parser' declaration, that descriptor is indicated by
     '&simple_parser_descriptor'.  The descriptor specifies the version
     number for the full-text plugin interface (as given by
     'MYSQL_FTPARSER_INTERFACE_VERSION'), and the plugin's parsing,
     initialization, and deinitialization functions:

          static struct st_mysql_ftparser simple_parser_descriptor=
          {
            MYSQL_FTPARSER_INTERFACE_VERSION, /* interface version      */
            simple_parser_parse,              /* parsing function       */
            simple_parser_init,               /* parser init function   */
            simple_parser_deinit              /* parser deinit function */
          };

     A full-text parser plugin is used in two different contexts,
     indexing and searching.  In both contexts, the server calls the
     initialization and deinitialization functions at the beginning and
     end of processing each SQL statement that causes the plugin to be
     invoked.  However, during statement processing, the server calls
     the main parsing function in context-specific fashion:

        * For indexing, the server calls the parser for each column
          value to be indexed.

        * For searching, the server calls the parser to parse the search
          string.  The parser might also be called for rows processed by
          the statement.  In natural language mode, there is no need for
          the server to call the parser.  For boolean mode phrase
          searches or natural language searches with query expansion,
          the parser is used to parse column values for information that
          is not in the index.  Also, if a boolean mode search is done
          for a column that has no 'FULLTEXT' index, the built-in parser
          will be called.  (Plugins are associated with specific
          indexes.  If there is no index, no plugin is used.)

     The plugin declaration in the general plugin descriptor has 'init'
     and 'deinit' members that point initialization and deinitialization
     functions, and so does the type-specific plugin descriptor to which
     it points.  However, these pairs of functions have different
     purposes and are invoked for different reasons:

        * For the plugin declaration in the general plugin descriptor,
          the initialization and deinitialization functions are invoked
          when the plugin is loaded and unloaded.

        * For the type-specific plugin descriptor, the initialization
          and deinitialization functions are invoked per SQL statement
          for which the plugin is used.

     Each interface function named in the plugin descriptor should
     return zero for success or nonzero for failure, and each of them
     receives an argument that points to a 'MYSQL_FTPARSER_PARAM'
     structure containing the parsing context.  The structure has this
     definition:

          typedef struct st_mysql_ftparser_param
          {
            int (*mysql_parse)(struct st_mysql_ftparser_param *,
                               char *doc, int doc_len);
            int (*mysql_add_word)(struct st_mysql_ftparser_param *,
                                  char *word, int word_len,
                                  MYSQL_FTPARSER_BOOLEAN_INFO *boolean_info);
            void *ftparser_state;
            void *mysql_ftparam;
            struct charset_info_st *cs;
            char *doc;
            int length;
            int flags;
            enum enum_ftparser_mode mode;
          } MYSQL_FTPARSER_PARAM;

     The structure members are used as follows:

        * 'mysql_parse': A pointer to a callback function that invokes
          the server's built-in parser.  Use this callback when the
          plugin acts as a front end to the built-in parser.  That is,
          when the plugin parsing function is called, it should process
          the input to extract the text and pass the text to the
          'mysql_parse' callback.

          The first parameter for this callback function should be the
          'param' value itself:

               param->mysql_parse(param, ...);

          A front end plugin can extract text and pass it all at once to
          the built-in parser, or it can extract and pass text to the
          built-in parser a piece at a time.  However, in this case, the
          built-in parser treats the pieces of text as though there are
          implicit word breaks between them.

        * 'mysql_add_word': A pointer to a callback function that adds a
          word to a full-text index or to the list of search terms.  Use
          this callback when the parser plugin replaces the built-in
          parser.  That is, when the plugin parsing function is called,
          it should parse the input into words and invoke the
          'mysql_add_word' callback for each word.

          The first parameter for this callback function should be the
          'param' value itself:

               param->mysql_add_word(param, ...);

        * 'ftparser_state': This is a generic pointer.  The plugin can
          set it to point to information to be used internally for its
          own purposes.

        * 'mysql_ftparam': This is set by the server.  It is passed as
          the first argument to the 'mysql_parse' or 'mysql_add_word'
          callback.

        * 'cs': A pointer to information about the character set of the
          text, or 0 if no information is available.

        * 'doc': A pointer to the text to be parsed.

        * 'length': The length of the text to be parsed, in bytes.

        * 'flags': Parser flags.  This is zero if there are no special
          flags.  The only nonzero flag is 'MYSQL_FTFLAGS_NEED_COPY',
          which means that 'mysql_add_word()' must save a copy of the
          word (that is, it cannot use a pointer to the word because the
          word is in a buffer that will be overwritten.)

          This flag might be set or reset by MySQL before calling the
          parser plugin, by the parser plugin itself, or by the
          'mysql_parse()' function.

        * 'mode': The parsing mode.  This value will be one of the
          following constants:

             * 'MYSQL_FTPARSER_SIMPLE_MODE': Parse in fast and simple
               mode, which is used for indexing and for natural language
               queries.  The parser should pass to the server only those
               words that should be indexed.  If the parser uses length
               limits or a stopword list to determine which words to
               ignore, it should not pass such words to the server.

             * 'MYSQL_FTPARSER_WITH_STOPWORDS': Parse in stopword mode.
               This is used in boolean searches for phrase matching.
               The parser should pass all words to the server, even
               stopwords or words that are outside any normal length
               limits.

             * 'MYSQL_FTPARSER_FULL_BOOLEAN_INFO': Parse in boolean
               mode.  This is used for parsing boolean query strings.
               The parser should recognize not only words but also
               boolean-mode operators and pass them to the server as
               tokens using the 'mysql_add_word' callback.  To tell the
               server what kind of token is being passed, the plugin
               needs to fill in a 'MYSQL_FTPARSER_BOOLEAN_INFO'
               structure and pass a pointer to it.

     *Note*:

     For 'MyISAM', the stopword list and 'ft_min_word_len' and
     'ft_max_word_len' are checked inside the tokenizer.  For 'InnoDB',
     the stopword list and equivalent word length variable settings
     ('innodb_ft_min_token_size' and 'innodb_ft_max_token_size') are
     checked outside of the tokenizer.  As a result, 'InnoDB' plugin
     parsers do not need to check the stopword list,
     'innodb_ft_min_token_size', or 'innodb_ft_max_token_size'.
     Instead, it is recommended that all words be returned to 'InnoDB'.
     However, if you want to check stopwords within your plugin parser,
     use 'MYSQL_FTPARSER_SIMPLE_MODE', which is for full-text search
     index and natural language search.  For
     'MYSQL_FTPARSER_WITH_STOPWORDS' and
     'MYSQL_FTPARSER_FULL_BOOLEAN_INFO' modes, it is recommended that
     all words be returned to 'InnoDB' including stopwords, in case of
     phrase searches.

     If the parser is called in boolean mode, the 'param->mode' value
     will be 'MYSQL_FTPARSER_FULL_BOOLEAN_INFO'.  The
     'MYSQL_FTPARSER_BOOLEAN_INFO' structure that the parser uses for
     passing token information to the server looks like this:

          typedef struct st_mysql_ftparser_boolean_info
          {
            enum enum_ft_token_type type;
            int yesno;
            int weight_adjust;
            char wasign;
            char trunc;
            int position;
            /* These are parser state and must be removed. */
            char prev;
            char *quot;
          } MYSQL_FTPARSER_BOOLEAN_INFO;

     The parser should fill in the structure members as follows:

        * 'type': The token type.  The following table shows the
          permissible types.

          *Full-Text Parser Token Types*

          Token Value                   Meaning

          'FT_TOKEN_EOF'                End of data

          'FT_TOKEN_WORD'               A regular word

          'FT_TOKEN_LEFT_PAREN'         The beginning of a group or subexpression

          'FT_TOKEN_RIGHT_PAREN'        The end of a group or subexpression

          'FT_TOKEN_STOPWORD'           A stopword

        * 'yesno': Whether the word must be present for a match to
          occur.  0 means that the word is optional but increases the
          match relevance if it is present.  Values larger than 0 mean
          that the word must be present.  Values smaller than 0 mean
          that the word must not be present.

        * 'weight_adjust': A weighting factor that determines how much a
          match for the word counts.  It can be used to increase or
          decrease the word's importance in relevance calculations.  A
          value of zero indicates no weight adjustment.  Values greater
          than or less than zero mean higher or lower weight,
          respectively.  The examples at fulltext-boolean, that
          use the '<' and '>' operators illustrate how weighting works.

        * 'wasign': The sign of the weighting factor.  A negative value
          acts like the '~' boolean-search operator, which causes the
          word's contribution to the relevance to be negative.

        * 'trunc': Whether matching should be done as if the
          boolean-mode '*' truncation operator had been given.

        * 'position': Start position of the word in the document, in
          bytes.  Used by 'InnoDB' full-text search.  For existing
          plugins that are called in boolean mode, support must be added
          for the position member.

     Plugins should not use the 'prev' and 'quot' members of the
     'MYSQL_FTPARSER_BOOLEAN_INFO' structure.

     *Note*:

     The plugin parser framework does not support:

        * The '@distance' boolean operator.

        * A leading plus sign ('+') or minus sign ('-') boolean operator
          followed by a space and then a word (''+ apple'' or ''-
          apple'').  The leading plus or minus sign must be directly
          adjacent to the word, for example: ''+apple'' or ''-apple''.

     For information about boolean full-text search operators, see
     fulltext-boolean.

  4. Set up the plugin interface functions.

     The general plugin descriptor in the library descriptor names the
     initialization and deinitialization functions that the server
     should invoke when it loads and unloads the plugin.  For
     'simple_parser', these functions do nothing but return zero to
     indicate that they succeeded:

          static int simple_parser_plugin_init(void *arg __attribute__((unused)))
          {
            return(0);
          }

          static int simple_parser_plugin_deinit(void *arg __attribute__((unused)))
          {
            return(0);
          }

     Because those functions do not actually do anything, you could omit
     them and specify 0 for each of them in the plugin declaration.

     The type-specific plugin descriptor for 'simple_parser' names the
     initialization, deinitialization, and parsing functions that the
     server invokes when the plugin is used.  For 'simple_parser', the
     initialization and deinitialization functions do nothing:

          static int simple_parser_init(MYSQL_FTPARSER_PARAM *param
                                        __attribute__((unused)))
          {
            return(0);
          }

          static int simple_parser_deinit(MYSQL_FTPARSER_PARAM *param
                                          __attribute__((unused)))
          {
            return(0);
          }

     Here too, because those functions do nothing, you could omit them
     and specify 0 for each of them in the plugin descriptor.

     The main parsing function, 'simple_parser_parse()', acts as a
     replacement for the built-in full-text parser, so it needs to split
     text into words and pass each word to the server.  The parsing
     function's first argument is a pointer to a structure that contains
     the parsing context.  This structure has a 'doc' member that points
     to the text to be parsed, and a 'length' member that indicates how
     long the text is.  The simple parsing done by the plugin considers
     nonempty runs of whitespace characters to be words, so it
     identifies words like this:

          static int simple_parser_parse(MYSQL_FTPARSER_PARAM *param)
          {
            char *end, *start, *docend= param->doc + param->length;

            for (end= start= param->doc;; end++)
            {
              if (end == docend)
              {
                if (end > start)
                  add_word(param, start, end - start);
                break;
              }
              else if (isspace(*end))
              {
                if (end > start)
                  add_word(param, start, end - start);
                start= end + 1;
              }
            }
            return(0);
          }

     As the parser finds each word, it invokes a function 'add_word()'
     to pass the word to the server.  'add_word()' is a helper function
     only; it is not part of the plugin interface.  The parser passes
     the parsing context pointer to 'add_word()', as well as a pointer
     to the word and a length value:

          static void add_word(MYSQL_FTPARSER_PARAM *param, char *word, size_t len)
          {
            MYSQL_FTPARSER_BOOLEAN_INFO bool_info=
              { FT_TOKEN_WORD, 0, 0, 0, 0, 0, ' ', 0 };

            param->mysql_add_word(param, word, len, &bool_info);
          }

     *Note*:

     Prior to MySQL 5.7.3, the sixth 'MYSQL_FTPARSER_BOOLEAN_INFO'
     member (just before the '' '' member) is not present.

     For boolean-mode parsing, 'add_word()' fills in the members of the
     'bool_info' structure as described earlier in the discussion of the
     'st_mysql_ftparser_boolean_info' structure.

  5. Set up the status variables.  For the 'simple_parser' plugin, the
     following status variable array sets up one status variable with a
     value that is static text, and another with a value that is stored
     in a long integer variable:

          long number_of_calls= 0;

          struct st_mysql_show_var simple_status[]=
          {
            {"simple_parser_static", (char *)"just a static text", SHOW_CHAR},
            {"simple_parser_called", (char *)&number_of_calls,     SHOW_LONG},
            {0,0,0}
          };

     By using status variable names that begin with the plugin name, you
     can easily display the variables for a plugin with 'SHOW STATUS'.:

          mysql> SHOW STATUS LIKE 'simple_parser%';
          +----------------------+--------------------+
          | Variable_name        | Value              |
          +----------------------+--------------------+
          | simple_parser_static | just a static text |
          | simple_parser_called | 0                  |
          +----------------------+--------------------+

  6. To compile and install a plugin library file, use the instructions
     in compiling-plugin-libraries.  To make the library file
     available for use, install it in the plugin directory (the
     directory named by the 'plugin_dir' system variable).  For the
     'simple_parser' plugin, it is compiled and installed when you build
     MySQL from source.  It is also included in binary distributions.
     The build process produces a shared object library with a name of
     'mypluglib.so' (the '.so' suffix might differ depending on your
     platform).

  7. To use the plugin, register it with the server.  For example, to
     register the plugin at runtime, use this statement (adjust the
     '.so' suffix for your platform as necessary):

          INSTALL PLUGIN simple_parser SONAME 'mypluglib.so';

     For additional information about plugin loading, see
     server-plugin-loading.

  8. To verify plugin installation, examine the
     'INFORMATION_SCHEMA.PLUGINS' table or use the
     'SHOW PLUGINS' statement.  See
     obtaining-plugin-information.

  9. Test the plugin to verify that it works properly.

     Create a table that contains a string column and associate the
     parser plugin with a 'FULLTEXT' index on the column:

          mysql> CREATE TABLE t (c VARCHAR(255),
              ->   FULLTEXT (c) WITH PARSER simple_parser
              -> ) ENGINE=MyISAM;
          Query OK, 0 rows affected (0.01 sec)

     Insert some text into the table and try some searches.  These
     should verify that the parser plugin treats all nonwhitespace
     characters as word characters:

          mysql> INSERT INTO t VALUES
              ->   ('latin1_general_cs is a case-sensitive collation'),
              ->   ('I\'d like a case of oranges'),
              ->   ('this is sensitive information'),
              ->   ('another row'),
              ->   ('yet another row');
          Query OK, 5 rows affected (0.02 sec)
          Records: 5  Duplicates: 0  Warnings: 0

          mysql> SELECT c FROM t;
          +-------------------------------------------------+
          | c                                               |
          +-------------------------------------------------+
          | latin1_general_cs is a case-sensitive collation |
          | I'd like a case of oranges                      |
          | this is sensitive information                   |
          | another row                                     |
          | yet another row                                 |
          +-------------------------------------------------+
          5 rows in set (0.00 sec)

          mysql> SELECT MATCH(c) AGAINST('case') FROM t;
          +--------------------------+
          | MATCH(c) AGAINST('case') |
          +--------------------------+
          |                        0 |
          |          1.2968142032623 |
          |                        0 |
          |                        0 |
          |                        0 |
          +--------------------------+
          5 rows in set (0.00 sec)

          mysql> SELECT MATCH(c) AGAINST('sensitive') FROM t;
          +-------------------------------+
          | MATCH(c) AGAINST('sensitive') |
          +-------------------------------+
          |                             0 |
          |                             0 |
          |               1.3253291845322 |
          |                             0 |
          |                             0 |
          +-------------------------------+
          5 rows in set (0.01 sec)

          mysql> SELECT MATCH(c) AGAINST('case-sensitive') FROM t;
          +------------------------------------+
          | MATCH(c) AGAINST('case-sensitive') |
          +------------------------------------+
          |                    1.3109166622162 |
          |                                  0 |
          |                                  0 |
          |                                  0 |
          |                                  0 |
          +------------------------------------+
          5 rows in set (0.01 sec)

          mysql> SELECT MATCH(c) AGAINST('I\'d') FROM t;
          +--------------------------+
          | MATCH(c) AGAINST('I\'d') |
          +--------------------------+
          |                        0 |
          |          1.2968142032623 |
          |                        0 |
          |                        0 |
          |                        0 |
          +--------------------------+
          5 rows in set (0.01 sec)

     Neither 'case' nor 'insensitive' match 'case-insensitive' the way
     that they would for the built-in parser.

28.2.4.8 Writing Daemon Plugins
...............................

A daemon plugin is a simple type of plugin used for code that should be
run by the server but that does not communicate with it.  This section
describes how to write a daemon server plugin, using the example plugin
found in the 'plugin/daemon_example' directory of MySQL source
distributions.  That directory contains the 'daemon_example.cc' source
file for a daemon plugin named 'daemon_example' that writes a heartbeat
string at regular intervals to a file named 'mysql-heartbeat.log' in the
data directory.

To write a daemon plugin, include the following header file in the
plugin source file.  Other MySQL or general header files might also be
needed, depending on the plugin capabilities and requirements.

     #include <mysql/plugin.h>

'plugin.h' defines the 'MYSQL_DAEMON_PLUGIN' server plugin type and the
data structures needed to declare the plugin.

The 'daemon_example.cc' file sets up the library descriptor as follows.
The library descriptor includes a single general server plugin
descriptor.

     mysql_declare_plugin(daemon_example)
     {
       MYSQL_DAEMON_PLUGIN,
       &daemon_example_plugin,
       "daemon_example",
       "Brian Aker",
       "Daemon example, creates a heartbeat beat file in mysql-heartbeat.log",
       PLUGIN_LICENSE_GPL,
       daemon_example_plugin_init, /* Plugin Init */
       daemon_example_plugin_deinit, /* Plugin Deinit */
       0x0100 /* 1.0 */,
       NULL,                       /* status variables                */
       NULL,                       /* system variables                */
       NULL,                       /* config options                  */
       0,                          /* flags                           */
     }
     mysql_declare_plugin_end;

The 'name' member ('daemon_example') indicates the name to use for
references to the plugin in statements such as 'INSTALL PLUGIN'
or 'UNINSTALL PLUGIN'.  This is
also the name displayed by 'SHOW PLUGINS' or
'INFORMATION_SCHEMA.PLUGINS'.

The second member of the plugin descriptor, 'daemon_example_plugin',
points to the type-specific daemon plugin descriptor.  This structure
consists only of the type-specific API version number:

     struct st_mysql_daemon daemon_example_plugin=
     { MYSQL_DAEMON_INTERFACE_VERSION  };

The type-specific structure has no interface functions.  There is no
communication between the server and the plugin, except that the server
calls the initialization and deinitialization functions from the general
plugin descriptor to start and stop the plugin:

   * 'daemon_example_plugin_init()' opens the heartbeat file and spawns
     a thread that wakes up periodically and writes the next message to
     the file.

   * 'daemon_example_plugin_deinit()' closes the file and performs other
     cleanup.

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).  For the 'daemon_example' plugin, it is
compiled and installed when you build MySQL from source.  It is also
included in binary distributions.  The build process produces a shared
object library with a name of 'libdaemon_example.so' (the '.so' suffix
might differ depending on your platform).

To use the plugin, register it with the server.  For example, to
register the plugin at runtime, use this statement (adjust the '.so'
suffix for your platform as necessary):

     INSTALL PLUGIN daemon_example SONAME 'libdaemon_example.so';

For additional information about plugin loading, see
server-plugin-loading.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement.  See
obtaining-plugin-information.

While the plugin is loaded, it writes a heartbeat string at regular
intervals to a file named 'mysql-heartbeat.log' in the data directory.
This file grows without limit, so after you have satistifed yourself
that the plugin operates correctly, unload it:

     UNINSTALL PLUGIN daemon_example;

28.2.4.9 Writing INFORMATION_SCHEMA Plugins
...........................................

This section describes how to write a server-side 'INFORMATION_SCHEMA'
table plugin.  For example code that implements such plugins, see the
'sql/sql_show.cc' file of a MySQL source distribution.  You can also
look at the example plugins found in the 'InnoDB' source.  See the
'handler/i_s.cc' and 'handler/ha_innodb.cc' files within the 'InnoDB'
source tree (in the 'storage/innobase' directory).

To write an 'INFORMATION_SCHEMA' table plugin, include the following
header files in the plugin source file.  Other MySQL or general header
files might also be needed, depending on the plugin capabilities and
requirements.

     #include <sql_class.h>
     #include <table.h>

These header files are located in the 'sql' directory of MySQL source
distributions.  They contain C++ structures, so the source file for an
'INFORMATION_SCHEMA' plugin must be compiled as C++ (not C) code.

The source file for the example plugin developed here is named
'simple_i_s_table.cc'.  It creates a simple 'INFORMATION_SCHEMA' table
named 'SIMPLE_I_S_TABLE' that has two columns named 'NAME' and 'VALUE'.
The general descriptor for a plugin library that implements the table
looks like this:

     mysql_declare_plugin(simple_i_s_library)
     {
       MYSQL_INFORMATION_SCHEMA_PLUGIN,
       &simple_table_info,                /* type-specific descriptor */
       "SIMPLE_I_S_TABLE",                /* table name */
       "Author Name",                     /* author */
       "Simple INFORMATION_SCHEMA table", /* description */
       PLUGIN_LICENSE_GPL,                /* license type */
       simple_table_init,                 /* init function */
       NULL,
       0x0100,                            /* version = 1.0 */
       NULL,                              /* no status variables */
       NULL,                              /* no system variables */
       NULL,                              /* no reserved information */
       0                                  /* no flags */
     }
     mysql_declare_plugin_end;

The 'name' member ('SIMPLE_I_S_TABLE') indicates the name to use for
references to the plugin in statements such as 'INSTALL PLUGIN'
or 'UNINSTALL PLUGIN'.  This is
also the name displayed by 'SHOW PLUGINS' or
'INFORMATION_SCHEMA.PLUGINS'.

The 'simple_table_info' member of the general descriptor points to the
type-specific descriptor, which consists only of the type-specific API
version number:

     static struct st_mysql_information_schema simple_table_info =
     { MYSQL_INFORMATION_SCHEMA_INTERFACE_VERSION };

The general descriptor points to the initialization and deinitialization
functions:

   * The initialization function provides information about the table
     structure and a function that populates the table.

   * The deinitialization function performs any required cleanup.  If no
     cleanup is needed, this descriptor member can be 'NULL' (as in the
     example shown).

The initialization function should return 0 for success, 1 if an error
occurs.  The function receives a generic pointer, which it should
interpret as a pointer to the table structure:

     static int table_init(void *ptr)
     {
       ST_SCHEMA_TABLE *schema_table= (ST_SCHEMA_TABLE*)ptr;

       schema_table->fields_info= simple_table_fields;
       schema_table->fill_table= simple_fill_table;
       return 0;
     }

The function should set these two members of the table structure:

   * 'fields_info': An array of 'ST_FIELD_INFO' structures that contain
     information about each column.

   * 'fill_table': A function that populates the table.

The array pointed to by 'fields_info' should contain one element per
column of the 'INFORMATION_SCHEMA' plus a terminating element.  The
following 'simple_table_fields' array for the example plugin indicates
that 'SIMPLE_I_S_TABLE' has two columns.  'NAME' is string-valued with a
length of 10 and 'VALUE' is integer-valued with a display width of 20.
The last structure marks the end of the array.

     static ST_FIELD_INFO simple_table_fields[]=
     {
       {"NAME", 10, MYSQL_TYPE_STRING, 0, 0 0, 0},
       {"VALUE", 6, MYSQL_TYPE_LONG, 0, MY_I_S_UNSIGNED, 0, 0},
       {0, 0, MYSQL_TYPE_NULL, 0, 0, 0, 0}
     };

For more information about the column information structure, see the
definition of 'ST_FIELD_INFO' in the 'table.h' header file.  The
permissible 'MYSQL_TYPE_XXX' type values are those used in the C API;
see c-api-data-structures.

The 'fill_table' member should be set to a function that populates the
table and returns 0 for success, 1 if an error occurs.  For the example
plugin, the 'simple_fill_table()' function looks like this:

     static int simple_fill_table(THD *thd, TABLE_LIST *tables, Item *cond)
     {
       TABLE *table= tables->table;

       table->field[0]->store("Name 1", 6, system_charset_info);
       table->field[1]->store(1);
       if (schema_table_store_record(thd, table))
         return 1;
       table->field[0]->store("Name 2", 6, system_charset_info);
       table->field[1]->store(2);
       if (schema_table_store_record(thd, table))
         return 1;
       return 0;
     }

For each row of the 'INFORMATION_SCHEMA' table, this function
initializes each column, then calls 'schema_table_store_record()' to
install the row.  The 'store()' method arguments depend on the type of
value to be stored.  For column 0 ('NAME', a string), 'store()' takes a
pointer to a string, its length, and information about the character set
of the string:

     store(const char *to, uint length, CHARSET_INFO *cs);

For column 1 ('VALUE', an integer), 'store()' takes the value and a flag
indicating whether it is unsigned:

     store(longlong nr, bool unsigned_value);

For other examples of how to populate 'INFORMATION_SCHEMA' tables,
search for instances of 'schema_table_store_record()' in 'sql_show.cc'.

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).

To test the plugin, install it:

     mysql> INSTALL PLUGIN SIMPLE_I_S_TABLE SONAME 'simple_i_s_table.so';

Verify that the table is present:

     mysql> SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
         -> WHERE TABLE_NAME = 'SIMPLE_I_S_TABLE';
     +------------------+
     | TABLE_NAME       |
     +------------------+
     | SIMPLE_I_S_TABLE |
     +------------------+

Try to select from it:

     mysql> SELECT * FROM INFORMATION_SCHEMA.SIMPLE_I_S_TABLE;
     +--------+-------+
     | NAME   | VALUE |
     +--------+-------+
     | Name 1 |     1 |
     | Name 2 |     2 |
     +--------+-------+

Uninstall it:

     mysql> UNINSTALL PLUGIN SIMPLE_I_S_TABLE;

28.2.4.10 Writing Semisynchronous Replication Plugins
.....................................................

This section describes how to write server-side semisynchronous
replication plugins, using the example plugins found in the
'plugin/semisync' directory of MySQL source distributions.  That
directory contains the source files for master and slave plugins named
'rpl_semi_sync_master' and 'rpl_semi_sync_slave'.  The information here
covers only how to set up the plugin framework.  For details about how
the plugins implement replication functions, see the source.

To write a semisynchronous replication plugin, include the following
header file in the plugin source file.  Other MySQL or general header
files might also be needed, depending on the plugin capabilities and
requirements.

     #include <mysql/plugin.h>

'plugin.h' defines the 'MYSQL_REPLICATION_PLUGIN' server plugin type and
the data structures needed to declare the plugin.

For the master side, 'semisync_master_plugin.cc' contains this general
descriptor for a plugin named 'rpl_semi_sync_master':

     mysql_declare_plugin(semi_sync_master)
     {
       MYSQL_REPLICATION_PLUGIN,
       &semi_sync_master_plugin,
       "rpl_semi_sync_master",
       "He Zhenxing",
       "Semi-synchronous replication master",
       PLUGIN_LICENSE_GPL,
       semi_sync_master_plugin_init, /* Plugin Init */
       semi_sync_master_plugin_deinit, /* Plugin Deinit */
       0x0100 /* 1.0 */,
       semi_sync_master_status_vars, /* status variables */
       semi_sync_master_system_vars, /* system variables */
       NULL,                         /* config options */
       0,                            /* flags */
     }
     mysql_declare_plugin_end;

For the slave side, 'semisync_slave_plugin.cc' contains this general
descriptor for a plugin named 'rpl_semi_sync_slave':

     mysql_declare_plugin(semi_sync_slave)
     {
       MYSQL_REPLICATION_PLUGIN,
       &semi_sync_slave_plugin,
       "rpl_semi_sync_slave",
       "He Zhenxing",
       "Semi-synchronous replication slave",
       PLUGIN_LICENSE_GPL,
       semi_sync_slave_plugin_init, /* Plugin Init */
       semi_sync_slave_plugin_deinit, /* Plugin Deinit */
       0x0100 /* 1.0 */,
       semi_sync_slave_status_vars,  /* status variables */
       semi_sync_slave_system_vars,  /* system variables */
       NULL,                         /* config options */
       0,                            /* flags */
     }
     mysql_declare_plugin_end;

For both the master and slave plugins, the general descriptor has
pointers to the type-specific descriptor, the initialization and
deinitialization functions, and to the status and system variables
implemented by the plugin.  For information about variable setup, see
plugin-status-system-variables.  The following remarks discuss
the type-specific descriptor and the initialization and deinitialization
functions for the master plugin but apply similarly to the slave plugin.

The 'semi_sync_master_plugin' member of the master general descriptor
points to the type-specific descriptor, which consists only of the
type-specific API version number:

     struct Mysql_replication semi_sync_master_plugin= {
       MYSQL_REPLICATION_INTERFACE_VERSION
     };

The initialization and deinitialization function declarations look like
this:

     static int semi_sync_master_plugin_init(void *p);
     static int semi_sync_master_plugin_deinit(void *p);

The initialization function uses the pointer to register transaction and
binary logging 'observers' with the server.  After successful
initialization, the server takes care of invoking the observers at the
appropriate times.  (For details on the observers, see the source
files.)  The deinitialization function cleans up by deregistering the
observers.  Each function returns 0 for success or 1 if an error occurs.

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).  For the 'rpl_semi_sync_master' and
'rpl_semi_sync_slave' plugins, they are compiled and installed when you
build MySQL from source.  They are also included in binary
distributions.  The build process produces shared object libraries with
names of 'semisync_master.so' and 'semisync_slave.so' (the '.so' suffix
might differ depending on your platform).

28.2.4.11 Writing Audit Plugins
...............................

This section describes how to write a server-side audit plugin, using
the example plugin found in the 'plugin/audit_null' directory of MySQL
source distributions.  The 'audit_null.c' and 'audit_null_variables.h'
source files in that directory implement an audit plugin named
'NULL_AUDIT'.

*Note*:

Changes were made in MySQL 5.7.8 to reimplement query rewrite plugins as
audit plugins, and then the audit plugin API itself was extensively
revised in 5.7.9 (including the parts for query rewrite plugins).  For
these reasons, the discussion here describes the audit plugin API as of
MySQL 5.7.9.  The API prior to 5.7.8 is much like that for MySQL 5.6.
To write audit plugins against the older API, see Writing Audit Plugins
(http://dev.mysql.com/doc/refman/5.6/en/writing-audit-plugins.html) in
MySQL 5.6 Reference Manual (http://dev.mysql.com/doc/refman/5.6/en/).

*Note*:

Other examples of plugins that use the audit plugin API are the query
rewrite plugin (see rewriter-query-rewrite-plugin) and the
Version Tokens plugin (see version-tokens).

Within the server, the pluggable audit interface is implemented in the
'sql_audit.h' and 'sql_audit.cc' files in the 'sql' directory of MySQL
source distributions.  Additionally, several places in the server call
the audit interface when an auditable event occurs, so that registered
audit plugins can be notified about the event if necessary.  To see
where such calls occur, search the server source files for invocations
of functions with names of the form 'mysql_audit_XXX()'.  Audit
notification occurs for server operations such as these:

   * Client connect and disconnect events

   * Writing a message to the general query log (if the log is enabled)

   * Writing a message to the error log

   * Sending a query result to a client

To write an audit plugin, include the following header file in the
plugin source file.  Other MySQL or general header files might also be
needed, depending on the plugin capabilities and requirements.

     #include <mysql/plugin_audit.h>

'plugin_audit.h' includes 'plugin.h', so you need not include the latter
file explicitly.  'plugin.h' defines the 'MYSQL_AUDIT_PLUGIN' server
plugin type and the data structures needed to declare the plugin.
'plugin_audit.h' defines data structures specific to audit plugins.

*Audit Plugin General Descriptor*

An audit plugin, like any MySQL server plugin, has a general plugin
descriptor (see server-plugin-descriptors) and a type-specific
plugin descriptor.  In 'audit_null.c', the general descriptor for
'audit_null' looks like this:

     mysql_declare_plugin(audit_null)
     {
       MYSQL_AUDIT_PLUGIN,         /* type                            */
       &audit_null_descriptor,     /* descriptor                      */
       "NULL_AUDIT",               /* name                            */
       "Oracle Corp",              /* author                          */
       "Simple NULL Audit",        /* description                     */
       PLUGIN_LICENSE_GPL,
       audit_null_plugin_init,     /* init function (when loaded)     */
       audit_null_plugin_deinit,   /* deinit function (when unloaded) */
       0x0003,                     /* version                         */
       simple_status,              /* status variables                */
       system_variables,           /* system variables                */
       NULL,
       0,
     }
     mysql_declare_plugin_end;

The first member, 'MYSQL_AUDIT_PLUGIN', identifies this plugin as an
audit plugin.

'audit_null_descriptor' points to the type-specific plugin descriptor,
described later.

The 'name' member ('NULL_AUDIT') indicates the name to use for
references to the plugin in statements such as 'INSTALL PLUGIN'
or 'UNINSTALL PLUGIN'.  This is
also the name displayed by 'INFORMATION_SCHEMA.PLUGINS'
or 'SHOW PLUGINS'.

The 'audit_null_plugin_init' initialization function performs plugin
initialization when the plugin is loaded.  The
'audit_null_plugin_deinit' function performs cleanup when the plugin is
unloaded.

The general plugin descriptor also refers to 'simple_status' and
'system_variables', structures that expose several status and system
variables.  When the plugin is enabled, these variables can be inspected
using 'SHOW' statements (see 'SHOW STATUS', 'SHOW VARIABLES')
or the appropriate Performance Schema
tables.

The 'simple_status' structure declares several status variables with
names of the form 'Audit_null_XXX'.  'NULL_AUDIT' increments the
'Audit_null_called' status variable for every notification that it
receives.  The other status variables are more specific and 'NULL_AUDIT'
increments them only for notifications of specific events.

'system_variables' is an array of system variable elements, each of
which is defined using a 'MYSQL_THDVAR_XXX' macro.  These system
variables have names of the form 'null_audit_XXX'.  These variables can
be used to communicate with the plugin at runtime.

*Audit Plugin Type-Specific Descriptor*

The 'audit_null_descriptor' value in the general plugin descriptor
points to the type-specific plugin descriptor.  For audit plugins, this
descriptor has the following structure (defined in 'plugin_audit.h'):

     struct st_mysql_audit
     {
       int interface_version;
       void (*release_thd)(MYSQL_THD);
       int (*event_notify)(MYSQL_THD, mysql_event_class_t, const void *);
       unsigned long class_mask[MYSQL_AUDIT_CLASS_MASK_SIZE];
     };

The type-specific descriptor for audit plugins has these members:

   * 'interface_version': By convention, type-specific plugin
     descriptors begin with the interface version for the given plugin
     type.  The server checks 'interface_version' when it loads the
     plugin to see whether the plugin is compatible with it.  For audit
     plugins, the value of the 'interface_version' member is
     'MYSQL_AUDIT_INTERFACE_VERSION' (defined in 'plugin_audit.h').

   * 'release_thd': A function that the server calls to inform the
     plugin that it is being dissociated from its thread context.  This
     should be 'NULL' if there is no such function.

   * 'event_notify': A function that the server calls to notify the
     plugin that an auditable event has occurred.  This function should
     not be 'NULL'; that would not make sense because no auditing would
     occur.

   * 'class_mask': An array of 'MYSQL_AUDIT_CLASS_MASK_SIZE' elements.
     Each element specifies a bitmask for a given event class to
     indicate the subclasses for which the plugin wants notification.
     (This is how the plugin 'subscribes' to events of interest.)  An
     element should be 0 to ignore events for the corresponding event
     class.

The server uses the 'event_notify' and 'release_thd' functions together.
They are called within the context of a specific thread, and a thread
might perform an activity that produces several event notifications.
The first time the server calls 'event_notify' for a thread, it creates
a binding of the plugin to the thread.  The plugin cannot be uninstalled
while this binding exists.  When no more events for the thread will
occur, the server informs the plugin of this by calling the
'release_thd' function, and then destroys the binding.  For example,
when a client issues a statement, the thread processing the statement
might notify audit plugins about the result set produced by the
statement and about the statement being logged.  After these
notifications occur, the server releases the plugin before putting the
thread to sleep until the client issues another statement.

This design enables the plugin to allocate resources needed for a given
thread in the first call to the 'event_notify' function and release them
in the 'release_thd' function:

     event_notify function:
       if memory is needed to service the thread
         allocate memory
       ... rest of notification processing ...

     release_thd function:
       if memory was allocated
         release memory
       ... rest of release processing ...

That is more efficient than allocating and releasing memory repeatedly
in the notification function.

For the 'NULL_AUDIT' audit plugin, the type-specific plugin descriptor
looks like this:

     static struct st_mysql_audit audit_null_descriptor=
     {
       MYSQL_AUDIT_INTERFACE_VERSION,                    /* interface version    */
       NULL,                                             /* release_thd function */
       audit_null_notify,                                /* notify function      */
       { (unsigned long) MYSQL_AUDIT_GENERAL_ALL,
         (unsigned long) MYSQL_AUDIT_CONNECTION_ALL,
         (unsigned long) MYSQL_AUDIT_PARSE_ALL,
         (unsigned long) MYSQL_AUDIT_AUTHORIZATION_ALL,
         (unsigned long) MYSQL_AUDIT_TABLE_ACCESS_ALL,
         (unsigned long) MYSQL_AUDIT_GLOBAL_VARIABLE_ALL,
         (unsigned long) MYSQL_AUDIT_SERVER_STARTUP_ALL,
         (unsigned long) MYSQL_AUDIT_SERVER_SHUTDOWN_ALL,
         (unsigned long) MYSQL_AUDIT_COMMAND_ALL,
         (unsigned long) MYSQL_AUDIT_QUERY_ALL,
         (unsigned long) MYSQL_AUDIT_STORED_PROGRAM_ALL }
     };

The server calls 'audit_null_notify()' to pass audit event information
to the plugin.  There is no 'release_thd' function.

The 'class_mask' member is an array that indicates which event classes
the plugin subscribes to.  As shown, the array contents subscribe to all
subclasses of all event classes that are available.  To ignore all
notifications for a given event class, specify the corresponding
'class_mask' element as 0.

The number of 'class_mask' elements corresponds to the number of event
classes, each of which is listed in the 'mysql_event_class_t'
enumeration defined in 'plugin_audit.h':

     typedef enum
     {
       MYSQL_AUDIT_GENERAL_CLASS          = 0,
       MYSQL_AUDIT_CONNECTION_CLASS       = 1,
       MYSQL_AUDIT_PARSE_CLASS            = 2,
       MYSQL_AUDIT_AUTHORIZATION_CLASS    = 3,
       MYSQL_AUDIT_TABLE_ACCESS_CLASS     = 4,
       MYSQL_AUDIT_GLOBAL_VARIABLE_CLASS  = 5,
       MYSQL_AUDIT_SERVER_STARTUP_CLASS   = 6,
       MYSQL_AUDIT_SERVER_SHUTDOWN_CLASS  = 7,
       MYSQL_AUDIT_COMMAND_CLASS          = 8,
       MYSQL_AUDIT_QUERY_CLASS            = 9,
       MYSQL_AUDIT_STORED_PROGRAM_CLASS   = 10,
       /* This item must be last in the list. */
       MYSQL_AUDIT_CLASS_MASK_SIZE
     } mysql_event_class_t;

For any given event class, 'plugin_audit.h' defines bitmask symbols for
individual event subclasses, as well as an 'XXX_ALL' symbol that is the
union of the all subclass bitmasks.  For example, for
'MYSQL_AUDIT_CONNECTION_CLASS' (the class that covers connect and
disconnect events), 'plugin_audit.h' defines these symbols:

     typedef enum
     {
       /** occurs after authentication phase is completed. */
       MYSQL_AUDIT_CONNECTION_CONNECT          = 1 << 0,
       /** occurs after connection is terminated. */
       MYSQL_AUDIT_CONNECTION_DISCONNECT       = 1 << 1,
       /** occurs after COM_CHANGE_USER RPC is completed. */
       MYSQL_AUDIT_CONNECTION_CHANGE_USER      = 1 << 2,
       /** occurs before authentication. */
       MYSQL_AUDIT_CONNECTION_PRE_AUTHENTICATE = 1 << 3
     } mysql_event_connection_subclass_t;

     #define MYSQL_AUDIT_CONNECTION_ALL (MYSQL_AUDIT_CONNECTION_CONNECT | \
                                         MYSQL_AUDIT_CONNECTION_DISCONNECT | \
                                         MYSQL_AUDIT_CONNECTION_CHANGE_USER | \
                                         MYSQL_AUDIT_CONNECTION_PRE_AUTHENTICATE)

To subscribe to all subclasses of the connection event class (as the
'NULL_AUDIT' plugin does), a plugin specifies
'MYSQL_AUDIT_CONNECTION_ALL' in the corresponding 'class_mask' element
('class_mask[1]' in this case).  To subscribe to only some subclasses,
the plugin sets the 'class_mask' element to the union of the subclasses
of interest.  For example, to subscribe only to the connect and
change-user subclasses, the plugin sets 'class_mask[1]' to this value:

     MYSQL_AUDIT_CONNECTION_CONNECT | MYSQL_AUDIT_CONNECTION_CHANGE_USER

*Audit Plugin Notification Function*

Most of the work for an audit plugin occurs in the notification function
(the 'event_notify' member of the type-specific plugin descriptor).  The
server calls this function for each auditable event.  Audit plugin
notification functions have this prototype:

     int (*event_notify)(MYSQL_THD, mysql_event_class_t, const void *);

The second and third parameters of the 'event_notify' function prototype
represent the event class and a generic pointer to an event structure.
(Events in different classes have different structures.  The
notification function can use the event class value to determine which
event structure applies.)  The function processes the event and returns
a status indicating whether the server should continue processing the
event or terminate it.

For 'NULL_AUDIT', the notification function is 'audit_null_notify()'.
This function increments a global event counter (which the plugin
exposes as the value of the 'Audit_null_called' status value), and then
examines the event class to determine how to process the event
structure:

     static int audit_null_notify(MYSQL_THD thd __attribute__((unused)),
                                  mysql_event_class_t event_class,
                                  const void *event)
     {
       ...

       number_of_calls++;

       if (event_class == MYSQL_AUDIT_GENERAL_CLASS)
       {
         const struct mysql_event_general *event_general=
                                         (const struct mysql_event_general *)event;
         ...
       }
       else if (event_class == MYSQL_AUDIT_CONNECTION_CLASS)
       {
         const struct mysql_event_connection *event_connection=
                                     (const struct mysql_event_connection *) event;
         ...

       }
       else if (event_class == MYSQL_AUDIT_PARSE_CLASS)
       {
         const struct mysql_event_parse *event_parse =
                                           (const struct mysql_event_parse *)event;
         ...
       }
       ...
     }

The notification function interprets the 'event' argument according to
the value of 'event_class'.  The 'event' argument is a generic pointer
to the event record, the structure of which differs per event class.
(The 'plugin_audit.h' file contains the structures that define the
contents of each event class.)  For each class, 'audit_null_notify()'
casts the event to the appropriate class-specific structure and then
checks its subclass to determine which subclass counter to increment.
For example, the code to handle events in the connection-event class
looks like this:

     else if (event_class == MYSQL_AUDIT_CONNECTION_CLASS)
     {
       const struct mysql_event_connection *event_connection=
                                   (const struct mysql_event_connection *) event;

       switch (event_connection->event_subclass)
       {
       case MYSQL_AUDIT_CONNECTION_CONNECT:
         number_of_calls_connection_connect++;
         break;
       case MYSQL_AUDIT_CONNECTION_DISCONNECT:
         number_of_calls_connection_disconnect++;
         break;
       case MYSQL_AUDIT_CONNECTION_CHANGE_USER:
         number_of_calls_connection_change_user++;
         break;
       case MYSQL_AUDIT_CONNECTION_PRE_AUTHENTICATE:
         number_of_calls_connection_pre_authenticate++;
           break;
       default:
         break;
       }
     }

*Note*:

The general event class ('MYSQL_AUDIT_GENERAL_CLASS') is deprecated as
of MySQL 5.7.9 and will be removed in a future MySQL release.  To reduce
plugin overhead, it is preferable to subscribe only to the more specific
event classes of interest.

For some event classes, the 'NULL_AUDIT' plugin performs other
processing in addition to incrementing a counter.  In any case, when the
notification function finishes processing the event, it should return a
status indicating whether the server should continue processing the
event or terminate it.

*Audit Plugin Error Handling*

Audit plugin notification functions can report a status value for the
current event two ways:

   * Use the notification function return value.  In this case, the
     function returns zero if the server should continue processing the
     event, or nonzero if the server should terminate the event.

   * Call the 'my_message()' function to set the error state before
     returning from the notification function.  In this case, the
     notification function return value is ignored and the server
     terminates event processing with an error.  The 'my_message()'
     arguments indicate which error to report, and its message.  For
     example:

          my_message(ER_AUDIT_API_ABORT, "This is my error message.", MYF(0));

     Some events cannot be aborted.  A nonzero return value is not taken
     into consideration and the 'my_message()' error call must follow an
     'is_error()' check.  For example:

          if (!thd->get_stmt_da()->is_error())
          {
            my_message(ER_AUDIT_API_ABORT, "This is my error message.", MYF(0));
          }

Some events cannot be terminated:

   * 'MYSQL_AUDIT_CONNECTION_DISCONNECT': The server cannot prevent a
     client from disconnecting.

   * 'MYSQL_AUDIT_COMMAND_END': This event provides the status of a
     command that has finished executing, so there is no purpose to
     terminating it.

If an audit plugin returns nonzero status for a nonterminable event, the
server ignores the status and continues processing the event.  As of
MySQL 5.7.9, that is also true if an audit plugin uses the
'my_message()' function to terminate a nonterminable event.

*Audit Plugin Usage*

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).  For the 'NULL_AUDIT' plugin, it is
compiled and installed when you build MySQL from source.  It is also
included in binary distributions.  The build process produces a shared
object library with a name of 'adt_null.so' (the '.so' suffix might
differ depending on your platform).

To register the plugin at runtime, use this statement (adjust the '.so'
suffix for your platform as necessary):

     INSTALL PLUGIN NULL_AUDIT SONAME 'adt_null.so';

For additional information about plugin loading, see
server-plugin-loading.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement.  See
obtaining-plugin-information.

While the audit plugin is installed, it exposes status variables that
indicate the events for which the plugin has been called:

     mysql> SHOW STATUS LIKE 'Audit_null%';
     +----------------------------------------+--------+
     | Variable_name                          | Value  |
     +----------------------------------------+--------+
     | Audit_null_authorization_column        | 0      |
     | Audit_null_authorization_db            | 0      |
     | Audit_null_authorization_procedure     | 0      |
     | Audit_null_authorization_proxy         | 0      |
     | Audit_null_authorization_table         | 0      |
     | Audit_null_authorization_user          | 0      |
     | Audit_null_called                      | 185547 |
     | Audit_null_command_end                 | 20999  |
     | Audit_null_command_start               | 21001  |
     | Audit_null_connection_change_user      | 0      |
     | Audit_null_connection_connect          | 5823   |
     | Audit_null_connection_disconnect       | 5818   |
     | Audit_null_connection_pre_authenticate | 5823   |
     | Audit_null_general_error               | 1      |
     | Audit_null_general_log                 | 26559  |
     | Audit_null_general_result              | 19922  |
     | Audit_null_general_status              | 21000  |
     | Audit_null_global_variable_get         | 0      |
     | Audit_null_global_variable_set         | 0      |
     | Audit_null_parse_postparse             | 14648  |
     | Audit_null_parse_preparse              | 14648  |
     | Audit_null_query_nested_start          | 6      |
     | Audit_null_query_nested_status_end     | 6      |
     | Audit_null_query_start                 | 14648  |
     | Audit_null_query_status_end            | 14647  |
     | Audit_null_server_shutdown             | 0      |
     | Audit_null_server_startup              | 1      |
     | Audit_null_table_access_delete         | 104    |
     | Audit_null_table_access_insert         | 2839   |
     | Audit_null_table_access_read           | 97842  |
     | Audit_null_table_access_update         | 278    |
     +----------------------------------------+--------+

'Audit_null_called' counts all events, and the other variables count
instances of specific event subclasses.  For example, the preceding
'SHOW STATUS' statement causes the server to send a
result to the client and to write a message to the general query log if
that log is enabled.  Thus, a client that issues the statement
repeatedly causes 'Audit_null_called', 'Audit_null_general_result', and
'Audit_null_general_log' to be incremented each time.  (Before MySQL
5.7.5, notification of events for the general query log occur only if
the general query log is enabled.  As of 5.7.5, notifications occur
whether or not that log is enabled.)

The status variables values are aggregated across all sessions.  There
are no counters for individual sessions.

'NULL_AUDIT' exposes several system variables that enable communication
with the plugin at runtime:

     mysql> SHOW VARIABLES LIKE 'null_audit%';
     +------------------------------------+-------+
     | Variable_name                      | Value |
     +------------------------------------+-------+
     | null_audit_abort_message           |       |
     | null_audit_abort_value             | 1     |
     | null_audit_event_order_check       |       |
     | null_audit_event_order_check_exact | 1     |
     | null_audit_event_order_started     | 0     |
     | null_audit_event_record            |       |
     | null_audit_event_record_def        |       |
     +------------------------------------+-------+

To check the order of audit API calls, set the
'null_audit_event_order_check' variable to the expected event order.
For example:

     SET null_audit_event_order_check =
           'MYSQL_AUDIT_CONNECTION_PRE_AUTHENTICATE;;;'
           'MYSQL_AUDIT_GENERAL_LOG;;;'
           'MYSQL_AUDIT_CONNECTION_CONNECT;;';

The statement takes advantage of the SQL syntax that concatenates
adjacent strings into a single string.

The format of the value is:

     'EVENT_NAME;EVENT_DATA;COMMAND' [';EVENT_NAME;EVENT_DATA;COMMAND'] ...

After the event order is matched, the 'null_audit_event_order_check'
value is replaced with a value of 'EVENT-ORDER-OK'.

Specifying a command value of 'ABORT_RET' makes it possible to abort the
audit API call on the specified event.  The following example aborts
'INSERT' statement execution when its
'MYSQL_AUDIT_QUERY_STATUS_END' event occurs:

     SET null_audit_event_order_check =
        'MYSQL_AUDIT_COMMAND_START;command_id="3";;'
        'MYSQL_AUDIT_GENERAL_LOG;;;'
        'MYSQL_AUDIT_QUERY_START;;;'
        'MYSQL_AUDIT_QUERY_STATUS_END;;ABORT_RET';

After the audit plugin matches the preceding sequence, it aborts event
processing and sends an error message to the client:

     ERROR 3164 (HY000): Aborted by Audit API ('MYSQL_AUDIT_QUERY_STATUS_END';1).

Returning a nonzero value from the audit API notification routine is the
standard way to abort event execution.  It is also possible to specify a
custom error code by setting the 'null_audit_abort_value' variable to
the value that the notification routine should return:

     SET null_audit_abort_value = 123;

Aborting a sequence results in a standard message with the custom error
code.  Suppose that you set audit log system variables like this:

     SET null_audit_abort_value = 123;
     SET null_audit_event_order_check =
         'MYSQL_AUDIT_COMMAND_START;command_id="3";;'
         'MYSQL_AUDIT_GENERAL_LOG;;;'
         'MYSQL_AUDIT_QUERY_START;;ABORT_RET';

Then execution of 'SELECT 1' results in this error:

     ERROR 3164 (HY000): Aborted by Audit API ('MYSQL_AUDIT_QUERY_START';123).

An event can be also aborted with a custom message, specified by setting
the 'null_audit_abort_message' variable: Suppose that you set audit log
system variables like this:

     SET null_audit_abort_message = 'Custom error text.';
     SET null_audit_event_order_check =
         'MYSQL_AUDIT_COMMAND_START;command_id="3";;'
         'MYSQL_AUDIT_GENERAL_LOG;;;'
         'MYSQL_AUDIT_QUERY_START;;ABORT_RET';

Then aborting a sequence results in the following error:

     ERROR 3164 (HY000): Custom error text.

For test-creation purposes, it is possible to record events that pass
through the plugin.  Recording starts by specifying start and end events
in the 'null_audit_event_record_def' variable:

     SET null_audit_event_record_def =
         'MYSQL_AUDIT_COMMAND_START;MYSQL_AUDIT_COMMAND_END';

Statement execution results in storing the events that occur in the
'null_audit_event_record' variable.

To disable the plugin after testing it, use this statement to unload it:

     UNINSTALL PLUGIN NULL_AUDIT;

28.2.4.12 Writing Authentication Plugins
........................................

MySQL supports pluggable authentication, in which plugins are invoked to
authenticate client connections.  Authentication plugins enable the use
of authentication methods other than the built-in method of passwords
stored in the 'mysql.user' table.  For example, plugins can be written
to access external authentication methods.  Also, authentication plugins
can support the proxy user capability, such that the connecting user is
a proxy for another user and is treated, for purposes of access control,
as having the privileges of a different user.  For more information, see
pluggable-authentication, and proxy-users.

An authentication plugin can be written for the server side or the
client side.  Server-side plugins use the same plugin API that is used
for the other server plugin types such as full-text parser or audit
plugins (although with a different type-specific descriptor).
Client-side plugins use the client plugin API.

Several header files contain information relevant to authentication
plugins:

   * 'plugin.h': Defines the 'MYSQL_AUTHENTICATION_PLUGIN' server plugin
     type.

   * 'client_plugin.h': Defines the API for client plugins.  This
     includes the client plugin descriptor and function prototypes for
     client plugin C API calls (see c-api-plugin-functions).

   * 'plugin_auth.h': Defines the part of the server plugin API specific
     to authentication plugins.  This includes the type-specific
     descriptor for server-side authentication plugins and the
     'MYSQL_SERVER_AUTH_INFO' structure.

   * 'plugin_auth_common.h': Contains common elements of client and
     server authentication plugins.  This includes return value
     definitions and the 'MYSQL_PLUGIN_VIO' structure.

To write an authentication plugin, include the following header files in
the plugin source file.  Other MySQL or general header files might also
be needed, depending on the plugin capabilities and requirements.

   * For a source file that implements a server authentication plugin,
     include this file:

          #include <mysql/plugin_auth.h>

   * For a source file that implements a client authentication plugin,
     or both client and server plugins, include these files:

          #include <mysql/plugin_auth.h>
          #include <mysql/client_plugin.h>
          #include <mysql.h>

'plugin_auth.h' includes 'plugin.h' and 'plugin_auth_common.h', so you
need not include the latter files explicitly.

This section describes how to write a pair of simple server and client
authentication plugins that work together.

*Warning*:

These plugins accept any non-empty password and the password is sent in
clear text.  This is insecure, so the plugins _should not be used in
production environments._

The server-side and client-side plugins developed here both are named
'auth_simple'.  As described in plugin-data-structures, the
plugin library file must have the same base name as the client plugin,
so the source file name is 'auth_simple.c' and produces a library named
'auth_simple.so' (assuming that your system uses '.so' as the suffix for
library files).

In MySQL source distributions, authentication plugin source is located
in the 'plugin/auth' directory and can be examined as a guide to writing
other authentication plugins.  Also, to see how the built-in
authentication plugins are implemented, see 'sql/sql_acl.cc' for plugins
that are built in to the MySQL server and 'sql-common/client.c' for
plugins that are built in to the 'libmysqlclient' client library.  (For
the built-in client plugins, note that the 'auth_plugin_t' structures
used there differ from the structures used with the usual client plugin
declaration macros.  In particular, the first two members are provided
explicitly, not by declaration macros.)

28.2.4.13 Writing the Server-Side Authentication Plugin
.......................................................

Declare the server-side plugin with the usual general descriptor format
that is used for all server plugin types (see
server-plugin-descriptors).  For the 'auth_simple' plugin, the
descriptor looks like this:

     mysql_declare_plugin(auth_simple)
     {
       MYSQL_AUTHENTICATION_PLUGIN,
       &auth_simple_handler,                 /* type-specific descriptor */
       "auth_simple",                        /* plugin name */
       "Author Name",                        /* author */
       "Any-password authentication plugin", /* description */
       PLUGIN_LICENSE_GPL,                   /* license type */
       NULL,                                 /* no init function */
       NULL,                                 /* no deinit function */
       0x0100,                               /* version = 1.0 */
       NULL,                                 /* no status variables */
       NULL,                                 /* no system variables */
       NULL,                                 /* no reserved information */
       0                                     /* no flags */
     }
     mysql_declare_plugin_end;

The 'name' member ('auth_simple') indicates the name to use for
references to the plugin in statements such as 'INSTALL PLUGIN'
or 'UNINSTALL PLUGIN'.  This is
also the name displayed by 'SHOW PLUGINS' or
'INFORMATION_SCHEMA.PLUGINS'.

The 'auth_simple_handler' member of the general descriptor points to the
type-specific descriptor.  For an authentication plugin, the
type-specific descriptor is an instance of the 'st_mysql_auth' structure
(defined in 'plugin_auth.h'):

     struct st_mysql_auth
     {
       int interface_version;
       const char *client_auth_plugin;
       int (*authenticate_user)(MYSQL_PLUGIN_VIO *vio, MYSQL_SERVER_AUTH_INFO *info);
       int (*generate_authentication_string)(char *outbuf,
           unsigned int *outbuflen, const char *inbuf, unsigned int inbuflen);
       int (*validate_authentication_string)(char* const inbuf, unsigned int buflen);
       int (*set_salt)(const char *password, unsigned int password_len,
                       unsigned char* salt, unsigned char *salt_len);
       const unsigned long authentication_flags;
     };

The 'st_mysql_auth' structure has these members:

   * 'interface_version': The type-specific API version number, always
     'MYSQL_AUTHENTICATION_INTERFACE_VERSION'

   * 'client_auth_plugin': The client plugin name

   * 'authenticate_user': A pointer to the main plugin function that
     communicates with the client

   * 'generate_authentication_string': A pointer to a plugin function
     that generates a password digest from an authentication string
     (added in MySQL 5.7.6)

   * 'validate_authentication_string': A pointer to a plugin function
     that validates a password digest (added in MySQL 5.7.6)

   * 'set_salt': A pointer to a plugin function that converts a
     scrambled password to binary form (added in MySQL 5.7.6)

   * 'authentication_flags': A flags word (added in MySQL 5.7.8)

The 'client_auth_plugin' member should indicate the name of the client
plugin if a specific plugin is required.  A value of 'NULL' means 'any
plugin.' In the latter case, whatever plugin the client uses will do.
This is useful if the server plugin does not care about the client
plugin or what user name or password it sends.  For example, this might
be true if the server plugin authenticates only local clients and uses
some property of the operating system rather than the information sent
by the client plugin.

For 'auth_simple', the type-specific descriptor looks like this:

     static struct st_mysql_auth auth_simple_handler =
     {
       MYSQL_AUTHENTICATION_INTERFACE_VERSION,
       "auth_simple",             /* required client-side plugin name */
       auth_simple_server         /* server-side plugin main function */
       generate_auth_string_hash, /* generate digest from password string */
       validate_auth_string_hash, /* validate password digest */
       set_salt,                  /* generate password salt value */
       AUTH_FLAG_PRIVILEGED_USER_FOR_PASSWORD_CHANGE
     };

The main function, 'auth_simple_server()', takes two arguments
representing an I/O structure and a 'MYSQL_SERVER_AUTH_INFO' structure.
The structure definition, found in 'plugin_auth.h', looks like this:

     typedef struct st_mysql_server_auth_info
     {
       char *user_name;
       unsigned int user_name_length;
       const char *auth_string;
       unsigned long auth_string_length;
       char authenticated_as[MYSQL_USERNAME_LENGTH+1];
       char external_user[512];
       int  password_used;
       const char *host_or_ip;
       unsigned int host_or_ip_length;
     } MYSQL_SERVER_AUTH_INFO;

The character set for string members is UTF-8.  If there is a '_length'
member associated with a string, it indicates the string length in
bytes.  Strings are also null-terminated.

When an authentication plugin is invoked by the server, it should
interpret the 'MYSQL_SERVER_AUTH_INFO' structure members as follows.
Some of these are used to set the value of SQL functions or system
variables within the client session, as indicated.

   * 'user_name': The user name sent by the client.  The value becomes
     the 'USER()' function value.

   * 'user_name_length': The length of 'user_name' in bytes.

   * 'auth_string': The value of the 'authentication_string' column of
     the 'mysql.user' table row for the matching account name (that is,
     the row that matches the client user name and host name and that
     the server uses to determine how to authenticate the client).

     Suppose that you create an account using the following statement:

          CREATE USER 'my_user'@'localhost'
            IDENTIFIED WITH my_plugin AS 'my_auth_string';

     When 'my_user' connects from the local host, the server invokes
     'my_plugin' and passes ''my_auth_string'' to it as the
     'auth_string' value.

   * 'auth_string_length': The length of 'auth_string' in bytes.

   * 'authenticated_as': The server sets this to the user name (the
     value of 'user_name').  The plugin can alter it to indicate that
     the client should have the privileges of a different user.  For
     example, if the plugin supports proxy users, the initial value is
     the name of the connecting (proxy) user, and the plugin can change
     this member to the proxied user name.  The server then treats the
     proxy user as having the privileges of the proxied user (assuming
     that the other conditions for proxy user support are satisfied; see
     writing-authentication-plugins-proxy-users).  The value is
     represented as a string at most 'MYSQL_USER_NAME_LENGTH' bytes
     long, plus a terminating null.  The value becomes the
     'CURRENT_USER()' function value.

   * 'external_user': The server sets this to the empty string (null
     terminated).  Its value becomes the 'external_user' system variable
     value.  If the plugin wants that system variable to have a
     different value, it should set this member accordingly; for
     example, to the connecting user name.  The value is represented as
     a string at most 511 bytes long, plus a terminating null.

   * 'password_used': This member applies when authentication fails.
     The plugin can set it or ignore it.  The value is used to construct
     the failure error message of 'Authentication fails. Password used:
     %s'.  The value of 'password_used' determines how '%s' is handled,
     as shown in the following table.

     'password_used'    '%s' Handling

     0                  NO

     1                  YES

     2                  There will be no '%s'

   * 'host_or_ip': The name of the client host if it can be resolved, or
     the IP address otherwise.

   * 'host_or_ip_length': The length of 'host_or_ip' in bytes.

The 'auth_simple' main function, 'auth_simple_server()', reads the
password (a null-terminated string) from the client and succeeds if the
password is nonempty (first byte not null):

     static int auth_simple_server (MYSQL_PLUGIN_VIO *vio,
                                    MYSQL_SERVER_AUTH_INFO *info)
     {
       unsigned char *pkt;
       int pkt_len;

       /* read the password as null-terminated string, fail on error */
       if ((pkt_len= vio->read_packet(vio, &pkt)) < 0)
         return CR_ERROR;

       /* fail on empty password */
       if (!pkt_len || *pkt == '\0')
       {
         info->password_used= PASSWORD_USED_NO;
         return CR_ERROR;
       }

       /* accept any nonempty password */
       info->password_used= PASSWORD_USED_YES;

       return CR_OK;
     }

The main function should return one of the error codes shown in the
following table.

Error Code                    Meaning

'CR_OK'                       Success

'CR_OK_HANDSHAKE_COMPLETE'    Do not send a status packet back to
                              client

'CR_ERROR'                    Error

'CR_AUTH_USER_CREDENTIALS'    Authentication failure

'CR_AUTH_HANDSHAKE'           Authentication handshake failure

'CR_AUTH_PLUGIN_ERROR'        Internal plugin error

For an example of how the handshake works, see the
'plugin/auth/dialog.c' source file.

The server counts plugin errors in the Performance Schema
'host_cache' table.

'auth_simple_server()' is so basic that it does not use the
authentication information structure except to set the member that
indicates whether a password was received.

A plugin that supports proxy users must return to the server the name of
the proxied user (the MySQL user whose privileges the client user should
get).  To do this, the plugin must set the 'info->authenticated_as'
member to the proxied user name.  For information about proxying, see
proxy-users, and
writing-authentication-plugins-proxy-users.

The 'generate_authentication_string' member of the plugin descriptor
takes the password and generates a password hash (digest) from it:

   * The first two arguments are pointers to the output buffer and its
     maximum length in bytes.  The function should write the password
     hash to the output buffer and reset the length to the actual hash
     length.

   * The second two arguments indicate the password input buffer and its
     length in bytes.

   * The function returns 0 for success, 1 if an error occurred.

For the 'auth_simple' plugin, the 'generate_auth_string_hash()' function
implements the 'generate_authentication_string' member.  It just makes a
copy of the password, unless it is too long to fit in the output buffer.

     int generate_auth_string_hash(char *outbuf, unsigned int *buflen,
                                   const char *inbuf, unsigned int inbuflen)
     {
       /*
         fail if buffer specified by server cannot be copied to output buffer
       */
       if (*buflen < inbuflen)
         return 1;   /* error */
       strncpy(outbuf, inbuf, inbuflen);
       *buflen= strlen(inbuf);
       return 0;     /* success */
     }

The 'validate_authentication_string' member of the plugin descriptor
validates a password hash:

   * The arguments are a pointer to the password hash and its length in
     bytes.

   * The function returns 0 for success, 1 if the password hash cannot
     be validated.

For the 'auth_simple' plugin, the 'validate_auth_string_hash()' function
implements the 'validate_authentication_string' member.  It returns
success unconditionally:

     int validate_auth_string_hash(char* const inbuf  __attribute__((unused)),
                                   unsigned int buflen  __attribute__((unused)))
     {
       return 0;     /* success */
     }

The 'set_salt' member of the plugin descriptor is used only by the
'mysql_native_password' plugin (see
native-pluggable-authentication).  For other authentication plugins,
you can use this trivial implementation:

     int set_salt(const char* password __attribute__((unused)),
                  unsigned int password_len __attribute__((unused)),
                  unsigned char* salt __attribute__((unused)),
                  unsigned char* salt_len)
     {
       *salt_len= 0;
       return 0;     /* success */
     }

The 'authentication_flags' member of the plugin descriptor contains
flags that affect plugin operation.  The permitted flags are:

   * 'AUTH_FLAG_PRIVILEGED_USER_FOR_PASSWORD_CHANGE': Credential changes
     are a privileged operation.  If this flag is set, the server
     requires that the user has the global 'CREATE USER' privilege or
     the 'UPDATE' privilege for the 'mysql' database.

   * 'AUTH_FLAG_USES_INTERNAL_STORAGE': Whether the plugin uses internal
     storage (in the 'authentication_string' column of 'mysql.user'
     rows).  If this flag is not set, attempts to set the password fail
     and the server produces a warning.

28.2.4.14 Writing the Client-Side Authentication Plugin
.......................................................

Declare the client-side plugin descriptor with the
'mysql_declare_client_plugin()' and 'mysql_end_client_plugin' macros
(see client-plugin-descriptors).  For the 'auth_simple' plugin,
the descriptor looks like this:

     mysql_declare_client_plugin(AUTHENTICATION)
       "auth_simple",                        /* plugin name */
       "Author Name",                        /* author */
       "Any-password authentication plugin", /* description */
       {1,0,0},                              /* version = 1.0.0 */
       "GPL",                                /* license type */
       NULL,                                 /* for internal use */
       NULL,                                 /* no init function */
       NULL,                                 /* no deinit function */
       NULL,                                 /* no option-handling function */
       auth_simple_client                    /* main function */
     mysql_end_client_plugin;

The descriptor members from the plugin name through the option-handling
function are common to all client plugin types.  (For descriptions, see
client-plugin-descriptors.)  Following the common members, the
descriptor has an additional member specific to authentication plugins.
This is the 'main' function, which handles communication with the
server.  The function takes two arguments representing an I/O structure
and a connection handler.  For our simple any-password plugin, the main
function does nothing but write to the server the password provided by
the user:

     static int auth_simple_client (MYSQL_PLUGIN_VIO *vio, MYSQL *mysql)
     {
       int res;

       /* send password as null-terminated string in clear text */
       res= vio->write_packet(vio, (const unsigned char *) mysql->passwd,
                              strlen(mysql->passwd) + 1);

       return res ? CR_ERROR : CR_OK;
     }

The main function should return one of the error codes shown in the
following table.

Error Code                    Meaning

'CR_OK'                       Success

'CR_OK_HANDSHAKE_COMPLETE'    Success, client done

'CR_ERROR'                    Error

'CR_OK_HANDSHAKE_COMPLETE' indicates that the client has done its part
successfully and has read the last packet.  A client plugin may return
'CR_OK_HANDSHAKE_COMPLETE' if the number of round trips in the
authentication protocol is not known in advance and the plugin must read
another packet to determine whether authentication is finished.

28.2.4.15 Using the Authentication Plugins
..........................................

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).

Register the server-side plugin with the server.  For example, to load
the plugin at server startup, use a '--plugin-load=auth_simple.so'
option (adjust the '.so' suffix for your platform as necessary).

Create a user for whom the server will use the 'auth_simple' plugin for
authentication:

     mysql> CREATE USER 'x'@'localhost'
         -> IDENTIFIED WITH auth_simple;

Use a client program to connect to the server as user 'x'.  The
server-side 'auth_simple' plugin communicates with the client program
that it should use the client-side 'auth_simple' plugin, and the latter
sends the password to the server.  The server plugin should reject
connections that send an empty password and accept connections that send
a nonempty password.  Invoke the client program each way to verify this:

     shell> mysql --user=x --skip-password
     ERROR 1045 (28000): Access denied for user 'x'@'localhost' (using password: NO)

     shell> mysql --user=x --password
     Enter password: abc
     mysql>

Because the server plugin accepts any nonempty password, it should be
considered insecure.  After testing the plugin to verify that it works,
restart the server without the '--plugin-load' option so as not to
indavertently leave the server running with an insecure authentication
plugin loaded.  Also, drop the user with 'DROP USER 'x'@'localhost''.

For additional information about loading and using authentication
plugins, see server-plugin-loading, and
pluggable-authentication.

If you are writing a client program that supports the use of
authentication plugins, normally such a program causes a plugin to be
loaded by calling 'mysql_options()' to set the
'MYSQL_DEFAULT_AUTH' and 'MYSQL_PLUGIN_DIR' options:

     char *plugin_dir = "PATH_TO_PLUGIN_DIR";
     char *default_auth = "PLUGIN_NAME";

     /* ... process command-line options ... */

     mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir);
     mysql_options(&mysql, MYSQL_DEFAULT_AUTH, default_auth);

Typically, the program will also accept '--plugin-dir' and
'--default-auth' options that enable users to override the default
values.

Should a client program require lower-level plugin management, the
client library contains functions that take an 'st_mysql_client_plugin'
argument.  See c-api-plugin-functions.

28.2.4.16 Implementing Proxy User Support in Authentication Plugins
...................................................................

One of the capabilities that pluggable authentication makes possible is
proxy users (see proxy-users).  For a server-side authentication
plugin to participate in proxy user support, these conditions must be
satisfied:

   * When a connecting client should be treated as a proxy user, the
     plugin must return a different name in the 'authenticated_as'
     member of the 'MYSQL_SERVER_AUTH_INFO' structure, to indicate the
     proxied user name.  It may also optionally set the 'external_user'
     member, to set the value of the 'external_user' system variable.

   * Proxy user accounts must be set up to be authenticated by the
     plugin.  Use the 'CREATE USER' or
     'GRANT' statement to associate accounts with plugins.

   * Proxy user accounts must have the 'PROXY' privilege for the proxied
     accounts.  Use the 'GRANT' statement to grant this
     privilege.

In other words, the only aspect of proxy user support required of the
plugin is that it set 'authenticated_as' to the proxied user name.  The
rest is optional (setting 'external_user') or done by the DBA using SQL
statements.

How does an authentication plugin determine which proxied user to return
when the proxy user connects?  That depends on the plugin.  Typically,
the plugin maps clients to proxied users based on the authentication
string passed to it by the server.  This string comes from the 'AS' part
of the 'IDENTIFIED WITH' clause of the 'CREATE USER'.
statement that specifies use of the plugin for authentication.

The plugin developer determines the syntax rules for the authentication
string and implements the plugin according to those rules.  Suppose that
a plugin takes a comma-separated list of pairs that map external users
to MySQL users.  For example:

     CREATE USER ''@'%.example.com'
       IDENTIFIED WITH my_plugin AS 'extuser1=mysqlusera, extuser2=mysqluserb'
     CREATE USER ''@'%.example.org'
       IDENTIFIED WITH my_plugin AS 'extuser1=mysqluserc, extuser2=mysqluserd'

When the server invokes a plugin to authenticate a client, it passes the
appropriate authentication string to the plugin.  The plugin is
responsible to:

  1. Parse the string into its components to determine the mapping to
     use

  2. Compare the client user name to the mapping

  3. Return the proper MySQL user name

For example, if 'extuser2' connects from an 'example.com' host, the
server passes ''extuser1=mysqlusera, extuser2=mysqluserb'' to the
plugin, and the plugin should copy 'mysqluserb' into 'authenticated_as',
with a terminating null byte.  If 'extuser2' connects from an
'example.org' host, the server passes ''extuser1=mysqluserc,
extuser2=mysqluserd'', and the plugin should copy 'mysqluserd' instead.

If there is no match in the mapping, the action depends on the plugin.
If a match is required, the plugin likely will return an error.  Or the
plugin might simply return the client name; in this case, it should not
change 'authenticated_as', and the server will not treat the client as a
proxy.

The following example demonstrates how to handle proxy users using a
plugin named 'auth_simple_proxy'.  Like the 'auth_simple' plugin
described earlier, 'auth_simple_proxy' accepts any nonempty password as
valid (and thus should not be used in production environments).  In
addition, it examines the 'auth_string' authentication string member and
uses these very simple rules for interpreting it:

   * If the string is empty, the plugin returns the user name as given
     and no proxying occurs.  That is, the plugin leaves the value of
     'authenticated_as' unchanged.

   * If the string is nonempty, the plugin treats it as the name of the
     proxied user and copies it to 'authenticated_as' so that proxying
     occurs.

For testing, set up one account that is not proxied according to the
preceding rules, and one that is.  This means that one account has no
'AS' clause, and one includes an 'AS' clause that names the proxied
user:

     CREATE USER 'plugin_user1'@'localhost'
       IDENTIFIED WITH auth_simple_proxy;
     CREATE USER 'plugin_user2'@'localhost'
       IDENTIFIED WITH auth_simple_proxy AS 'proxied_user';

In addition, create an account for the proxied user and grant
'plugin_user2' the 'PROXY' privilege for it:

     CREATE USER 'proxied_user'@'localhost'
       IDENTIFIED BY 'proxied_user_pass';
     GRANT PROXY
       ON 'proxied_user'@'localhost'
       TO 'plugin_user2'@'localhost';

Before the server invokes an authentication plugin, it sets
'authenticated_as' to the client user name.  To indicate that the user
is a proxy, the plugin should set 'authenticated_as' to the proxied user
name.  For 'auth_simple_proxy', this means that it must examine the
'auth_string' value, and, if the value is nonempty, copy it to the
'authenticated_as' member to return it as the name of the proxied user.
In addition, when proxying occurs, the plugin sets the 'external_user'
member to the client user name; this becomes the value of the
'external_user' system variable.

     static int auth_simple_proxy_server (MYSQL_PLUGIN_VIO *vio,
                                          MYSQL_SERVER_AUTH_INFO *info)
     {
       unsigned char *pkt;
       int pkt_len;

       /* read the password as null-terminated string, fail on error */
       if ((pkt_len= vio->read_packet(vio, &pkt)) < 0)
         return CR_ERROR;

       /* fail on empty password */
       if (!pkt_len || *pkt == '\0')
       {
         info->password_used= PASSWORD_USED_NO;
         return CR_ERROR;
       }

       /* accept any nonempty password */
       info->password_used= PASSWORD_USED_YES;

       /* if authentication string is nonempty, use as proxied user name */
       /* and use client name as external_user value */
       if (info->auth_string_length > 0)
       {
         strcpy (info->authenticated_as, info->auth_string);
         strcpy (info->external_user, info->user_name);
       }

       return CR_OK;
     }

After a successful connection, the 'USER()' function should indicate the
connecting client user and host name, and 'CURRENT_USER()' should
indicate the account whose privileges apply during the session.  The
latter value should be the connecting user account if no proxying occurs
or the proxied account if proxying does occur.

Compile and install the plugin, then test it.  First, connect as
'plugin_user1':

     shell> mysql --user=plugin_user1 --password
     Enter password: x

In this case, there should be no proxying:

     mysql> SELECT USER(), CURRENT_USER(), @@proxy_user, @@external_user\G
     *************************** 1. row ***************************
              USER(): plugin_user1@localhost
      CURRENT_USER(): plugin_user1@localhost
        @@proxy_user: NULL
     @@external_user: NULL

Then connect as 'plugin_user2':

     shell> mysql --user=plugin_user2 --password
     Enter password: x

In this case, 'plugin_user2' should be proxied to 'proxied_user':

     mysql> SELECT USER(), CURRENT_USER(), @@proxy_user, @@external_user\G
     *************************** 1. row ***************************
              USER(): plugin_user2@localhost
      CURRENT_USER(): proxied_user@localhost
        @@proxy_user: 'plugin_user2'@'localhost'
     @@external_user: 'plugin_user2'@'localhost'

28.2.4.17 Writing Password-Validation Plugins
.............................................

This section describes how to write a server-side password-validation
plugin.  The instructions are based on the source code in the
'plugin/password_validation' directory of MySQL source distributions.
The 'validate_password.cc' source file in that directory implements the
plugin named 'validate_password'.

To write a password-validation plugin, include the following header file
in the plugin source file.  Other MySQL or general header files might
also be needed, depending on the plugin capabilities and requirements.

     #include <mysql/plugin_validate_password.h>

'plugin_validate_password.h' includes 'plugin.h', so you need not
include the latter file explicitly.  'plugin.h' defines the
'MYSQL_VALIDATE_PASSWORD_PLUGIN' server plugin type and the data
structures needed to declare the plugin.  'plugin_validate_password.h'
defines data structures specific to password-validation plugins.

A password-validation plugin, like any MySQL server plugin, has a
general plugin descriptor (see server-plugin-descriptors).  In
'validate_password.cc', the general descriptor for 'validate_password'
looks like this:

     mysql_declare_plugin(validate_password)
     {
       MYSQL_VALIDATE_PASSWORD_PLUGIN,     /*   type                            */
       &validate_password_descriptor,      /*   descriptor                      */
       "validate_password",                /*   name                            */
       "Oracle Corporation",               /*   author                          */
       "check password strength",          /*   description                     */
       PLUGIN_LICENSE_GPL,
       validate_password_init,             /*   init function (when loaded)     */
       validate_password_deinit,           /*   deinit function (when unloaded) */
       0x0100,                             /*   version                         */
       NULL,
       validate_password_system_variables, /*   system variables                */
       NULL,
       0,
     }
     mysql_declare_plugin_end;

The 'name' member ('validate_password') indicates the name to use for
references to the plugin in statements such as 'INSTALL PLUGIN'
or 'UNINSTALL PLUGIN'.  This is
also the name displayed by 'INFORMATION_SCHEMA.PLUGINS'
or 'SHOW PLUGINS'.

The general descriptor also refers to
'validate_password_system_variables', a structure that exposes several
system variables to the 'SHOW VARIABLES'.
statement:

     static struct st_mysql_sys_var* validate_password_system_variables[]= {
       MYSQL_SYSVAR(length),
       MYSQL_SYSVAR(number_count),
       MYSQL_SYSVAR(mixed_case_count),
       MYSQL_SYSVAR(special_char_count),
       MYSQL_SYSVAR(policy),
       MYSQL_SYSVAR(dictionary_file),
       NULL
     };

The 'validate_password_init' initialization function reads the
dictionary file if one was specified, and the 'validate_password_deinit'
function frees data structures associated with the file.

The 'validate_password_descriptor' value in the general descriptor
points to the type-specific descriptor.  For password-validation
plugins, this descriptor has the following structure:

     struct st_mysql_validate_password
     {
       int interface_version;
       /*
         This function returns TRUE for passwords which satisfy the password
         policy (as chosen by plugin variable) and FALSE for all other
         password
       */
       int (*validate_password)(mysql_string_handle password);
       /*
         This function returns the password strength (0-100) depending
         upon the policies
       */
       int (*get_password_strength)(mysql_string_handle password);
     };

The type-specific descriptor has these members:

   * 'interface_version': By convention, type-specific plugin
     descriptors begin with the interface version for the given plugin
     type.  The server checks 'interface_version' when it loads the
     plugin to see whether the plugin is compatible with it.  For
     password-validation plugins, the value of the 'interface_version'
     member is 'MYSQL_VALIDATE_PASSWORD_INTERFACE_VERSION' (defined in
     'plugin_validate_password.h').

   * 'validate_password': A function that the server calls to test
     whether a password satisfies the current password policy.  It
     returns 1 if the password is okay and 0 otherwise.  The argument is
     the password, passed as a 'mysql_string_handle' value.  This data
     type is implemented by the 'mysql_string' server service.  For
     details, see the 'string_service.h' and 'string_service.cc' source
     files in the 'sql' directory.

   * 'get_password_strength': A function that the server calls to assess
     the strength of a password.  It returns a value from 0 (weak) to
     100 (strong).  The argument is the password, passed as a
     'mysql_string_handle' value.

For the 'validate_password' plugin, the type-specific descriptor looks
like this:

     static struct st_mysql_validate_password validate_password_descriptor=
     {
       MYSQL_VALIDATE_PASSWORD_INTERFACE_VERSION,
       validate_password,                         /* validate function          */
       get_password_strength                      /* validate strength function */
     };

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).  For the 'validate_password' plugin, it
is compiled and installed when you build MySQL from source.  It is also
included in binary distributions.  The build process produces a shared
object library with a name of 'validate_password.so' (the '.so' suffix
might differ depending on your platform).

To register the plugin at runtime, use this statement (adjust the '.so'
suffix for your platform as necessary):

     INSTALL PLUGIN validate_password SONAME 'validate_password.so';

For additional information about plugin loading, see
server-plugin-loading.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement.  See
obtaining-plugin-information.

While the 'validate_password' plugin is installed, it exposes system
variables that indicate the password-checking parameters:

     mysql> SHOW VARIABLES LIKE 'validate_password%';
     +--------------------------------------+--------+
     | Variable_name                        | Value  |
     +--------------------------------------+--------+
     | validate_password_dictionary_file    |        |
     | validate_password_length             | 8      |
     | validate_password_mixed_case_count   | 1      |
     | validate_password_number_count       | 1      |
     | validate_password_policy             | MEDIUM |
     | validate_password_special_char_count | 1      |
     +--------------------------------------+--------+

For descriptions of these variables, see
validate-password-options-variables.

To disable the plugin after testing it, use this statement to unload it:

     UNINSTALL PLUGIN validate_password;

28.2.4.18 Writing Protocol Trace Plugins
........................................

MySQL supports the use of protocol trace plugins: client-side plugins
that implement tracing of communication between a client and the server
that takes place using the client/server protocol.  This capability can
be used in MySQL 5.7.2 and up.

28.2.4.19 Using the Test Protocol Trace Plugin
..............................................

MySQL includes a test protocol trace plugin that serves to illustrate
the information available from such plugins, and as a guide to writing
other protocol trace plugins.  To see how the test plugin works, use a
MySQL source distribution; binary distributions are built with the test
plugin disabled.

Enable the test protocol trace plugin by configuring MySQL with the
'WITH_TEST_TRACE_PLUGIN' 'CMake' option enabled.  This causes the test
trace plugin to be built and MySQL client programs to load it, but the
plugin has no effect by default.  Control the plugin using these
environment variables:

   * 'MYSQL_TEST_TRACE_DEBUG': Set this variable to a value other than 0
     to cause the test plugin to produce diagnostic output on 'stderr'.

   * 'MYSQL_TEST_TRACE_CRASH': Set this variable to a value other than 0
     to cause the test plugin to abort the client program if it detects
     an invalid trace event.

*Caution*:

Diagnostic output from the test protocol trace plugin can disclose
passwords and other sensitive information.

Given a MySQL installation built from source with the test plugin
enabled, you can see a trace of the communication between the
'mysql' client and the MySQL server as follows:

     shell> export MYSQL_TEST_TRACE_DEBUG=1
     shqll> mysql
     test_trace: Test trace plugin initialized
     test_trace: Starting tracing in stage CONNECTING
     test_trace: stage: CONNECTING, event: CONNECTING
     test_trace: stage: CONNECTING, event: CONNECTED
     test_trace: stage: WAIT_FOR_INIT_PACKET, event: READ_PACKET
     test_trace: stage: WAIT_FOR_INIT_PACKET, event: PACKET_RECEIVED
     test_trace: packet received: 87 bytes
       0A 35 2E 37 2E 33 2D 6D  31 33 2D 64 65 62 75 67   .5.7.3-m13-debug
       2D 6C 6F 67 00 04 00 00  00 2B 7C 4F 55 3F 79 67   -log.....+|OU?yg
     test_trace: 004: stage: WAIT_FOR_INIT_PACKET, event: INIT_PACKET_RECEIVED
     test_trace: 004: stage: AUTHENTICATE, event: AUTH_PLUGIN
     test_trace: 004: Using authentication plugin: mysql_native_password
     test_trace: 004: stage: AUTHENTICATE, event: SEND_AUTH_RESPONSE
     test_trace: 004: sending packet: 188 bytes
       85 A6 7F 00 00 00 00 01  21 00 00 00 00 00 00 00   .?......!.......
       00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00   ................
     ...
     mysql> quit
     test_trace: 008: stage: READY_FOR_COMMAND, event: SEND_COMMAND
     test_trace: 008: QUIT
     test_trace: 008: stage: READY_FOR_COMMAND, event: PACKET_SENT
     test_trace: 008: packet sent: 0 bytes
     test_trace: 008: stage: READY_FOR_COMMAND, event: DISCONNECTED
     test_trace: 008: Connection  closed
     test_trace: 008: Tracing connection has ended
     Bye
     test_trace: Test trace plugin de-initialized

To disable trace output, do this:

     shell> MYSQL_TEST_TRACE_DEBUG=

28.2.4.20 Using Your Own Protocol Trace Plugins
...............................................

*Note*:

To use your own protocol trace plugins, you must configure MySQL with
the 'WITH_TEST_TRACE_PLUGIN' 'CMake' option _disabled_ because only one
protocol trace plugin can be loaded at a time and an error occurs for
attempts to load a second one.  If you have already built MySQL with the
test protocol trace plugin enabled to see how it works, you must rebuild
MySQL without it before you can use your own plugins.

This section discusses how to write a basic protocol trace plugin named
'simple_trace'.  This plugin provides a framework showing how to set up
the client plugin descriptor and create the trace-related callback
functions.  In 'simple_trace', these functions are rudimentary and do
little other than illustrate the arguments required.  To see in detail
how a trace plugin can make use of trace event information, check the
source file for the test protocol trace plugin ('test_trace_plugin.cc'
in the 'libmysql' directory of a MySQL source distribution).  However,
note that the 'st_mysql_client_plugin_TRACE' structure used there
differs from the structures used with the usual client plugin
declaration macros.  In particular, the first two members are defined
explicitly, not implicitly by declaration macros.

Several header files contain information relevant to protocol trace
plugins:

   * 'client_plugin.h': Defines the API for client plugins.  This
     includes the client plugin descriptor and function prototypes for
     client plugin C API calls (see c-api-plugin-functions).

   * 'plugin_trace.h': Contains declarations for client-side plugins of
     type 'MYSQL_CLIENT_TRACE_PLUGIN'.  It also contains descriptions of
     the permitted protocol stages, transitions between stages, and the
     types of events permitted at each stage.

To write a protocol trace plugin, include the following header files in
the plugin source file.  Other MySQL or general header files might also
be needed, depending on the plugin capabilities and requirements.

     #include <mysql/plugin_trace.h>
     #include <mysql.h>

'plugin_trace.h' includes 'client_plugin.h', so you need not include the
latter file explicitly.

Declare the client-side plugin descriptor with the
'mysql_declare_client_plugin()' and 'mysql_end_client_plugin' macros
(see client-plugin-descriptors).  For the 'simple_trace' plugin,
the descriptor looks like this:

     mysql_declare_client_plugin(TRACE)
       "simple_trace",                 /* plugin name */
       "Author Name",                  /* author */
       "Simple protocol trace plugin", /* description */
       {1,0,0},                        /* version = 1.0.0 */
       "GPL",                          /* license type */
       NULL,                           /* for internal use */
       plugin_init,                    /* initialization function */
       plugin_deinit,                  /* deinitialization function */
       plugin_options,                 /* option-handling function */
       trace_start,                    /* start-trace function */
       trace_stop,                     /* stop-trace function */
       trace_event                     /* event-handling function */
     mysql_end_client_plugin;

The descriptor members from the plugin name through the option-handling
function are common to all client plugin types.  The members following
the common members implement trace event handling.

Function members for which the plugin needs no processing can be
declared as 'NULL' in the descriptor, in which case you need not write
any corresponding function.  For illustration purposes and to show the
argument syntax, the following discussion implements all functions
listed in the descriptor, even though some of them do nothing,

The initialization, deinitialization, and options functions common to
all client plugins are declared as follows.  For a description of the
arguments and return values, see client-plugin-descriptors.

     static int
     plugin_init(char *errbuf, size_t errbuf_len, int argc, va_list args)
     {
       return 0;
     }

     static int
     plugin_deinit()
     {
       return 0;
     }

     static int
     plugin_options(const char *option, const void *value)
     {
       return 0;
     }

The trace-specific members of the client plugin descriptor are callback
functions.  The following descriptions provide more detail on how they
are used.  Each has a first argument that is a pointer to the plugin
instance in case your implementation needs to access it.

'trace_start()': This function is called at the start of each traced
connection (each connection that starts after the plugin is loaded).  It
is passed the connection handler and the protocol stage at which tracing
starts.  'trace_start()' allocates memory needed by the 'trace_event()'
function, if any, and returns a pointer to it.  If no memory is needed,
this function returns 'NULL'.

     static void*
     trace_start(struct st_mysql_client_plugin_TRACE *self,
                 MYSQL *conn,
                 enum protocol_stage stage)
     {
       struct st_trace_data *plugin_data= malloc(sizeof(struct st_trace_data));

       fprintf(stderr, "Initializing trace: stage %d\n", stage);
       if (plugin_data)
       {
         memset(plugin_data, 0, sizeof(struct st_trace_data));
         fprintf(stderr, "Trace initialized\n");
         return plugin_data;
       }
       fprintf(stderr, "Could not initialize trace\n");
       exit(1);
     }

'trace_stop()': This function is called when tracing of the connection
ends.  That usually happens when the connection is closed, but can
happen earlier.  For example, 'trace_event()' can return a nonzero value
at any time and that causes tracing of the connection to terminate.
'trace_stop()' is then called even though the connection has not ended.

'trace_stop()' is passed the connection handler and a pointer to the
memory allocated by 'trace_start()' ('NULL' if none).  If the pointer is
non-'NULL', 'trace_stop()' should deallocate the memory.  This function
returns no value.

     static void
     trace_stop(struct st_mysql_client_plugin_TRACE *self,
                MYSQL *conn,
                void *plugin_data)
     {
       fprintf(stderr, "Terminating trace\n");
       if (plugin_data)
         free(plugin_data);
     }

'trace_event()': This function is called for each event occurrence.  It
is passed a pointer to the memory allocated by 'trace_start()' ('NULL'
if none), the connection handler, the current protocol stage and event
codes, and event data.  This function returns 0 to continue tracing,
nonzero if tracing should stop.

     static int
     trace_event(struct st_mysql_client_plugin_TRACE *self,
                 void *plugin_data,
                 MYSQL *conn,
                 enum protocol_stage stage,
                 enum trace_event event,
                 struct st_trace_event_args args)
     {
       fprintf(stderr, "Trace event received: stage %d, event %d\n", stage, event);
       if (event == TRACE_EVENT_DISCONNECTED)
         fprintf(stderr, "Connection closed\n");
       return 0;
     }

The tracing framework shuts down tracing of the connection when the
connection ends, so 'trace_event()' should return nonzero only if you
want to terminate tracing of the connection early.  Suppose that you
want to trace only connections for a certain MySQL account.  After
authentication, you can check the user name for the connection and stop
tracing if it is not the user in whom you are interested.

For each call to 'trace_event()', the 'st_trace_event_args' structure
contains the event data.  It has this definition:

     struct st_trace_event_args
     {
       const char           *plugin_name;
       int                   cmd;
       const unsigned char  *hdr;
       size_t                hdr_len;
       const unsigned char  *pkt;
       size_t                pkt_len;
     };

For different event types, the 'st_trace_event_args' structure contains
the information described following.  All lengths are in bytes.  Unused
members are set to '0'/'NULL'.

'AUTH_PLUGIN' event:

     plugin_name  The name of the plugin

'SEND_COMMAND' event:

     cmd          The command code
     hdr          Pointer to the command packet header
     hdr_len      Length of the header
     pkt          Pointer to the command arguments
     pkt_len      Length of the arguments

Other 'SEND_XXX' and 'XXX_RECEIVED' events:

     pkt          Pointer to the data sent or received
     pkt_len      Length of the data

'PACKET_SENT' event:

     pkt_len      Number of bytes sent

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).

After the plugin library file is compiled and installed in the plugin
directory, you can test it easily by setting the 'LIBMYSQL_PLUGINS'
environment variable to the plugin name, which affects any client
program that uses that variable.  'mysql' is one such
program:

     shell> export LIBMYSQL_PLUGINS=simple_trace
     shqll> mysql
     Initializing trace: stage 0
     Trace initialized
     Trace event received: stage 0, event 1
     Trace event received: stage 0, event 2
     ...
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Trace event received
     Trace event received
     ...
     mysql> SELECT 1;
     Trace event received: stage 4, event 12
     Trace event received: stage 4, event 16
     ...
     Trace event received: stage 8, event 14
     Trace event received: stage 8, event 15
     +---+
     | 1 |
     +---+
     | 1 |
     +---+
     1 row in set (0.00 sec)

     mysql> quit
     Trace event received: stage 4, event 12
     Trace event received: stage 4, event 16
     Trace event received: stage 4, event 3
     Connection closed
     Terminating trace
     Bye

To stop the trace plugin from being loaded, do this:

     shell> LIBMYSQL_PLUGINS=

It is also possible to write client programs that directly load the
plugin.  You can tell the client where the plugin directory is located
by calling 'mysql_options()' to set the
'MYSQL_PLUGIN_DIR' option:

     char *plugin_dir = "PATH_TO_PLUGIN_DIR";

     /* ... process command-line options ... */

     mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir);

Typically, the program will also accept a '--plugin-dir' option that
enables users to override the default value.

Should a client program require lower-level plugin management, the
client library contains functions that take an 'st_mysql_client_plugin'
argument.  See c-api-plugin-functions.

28.2.4.21 Writing Keyring Plugins
.................................

MySQL Server supports a keyring service that enables internal server
components and plugins to securely store sensitive information for later
retrieval.  This section describes how to write a server-side keyring
plugin that can be used by service functions to perform key-management
operations.  For general keyring information, see keyring.

The instructions here are based on the source code in the
'plugin/keyring' directory of MySQL source distributions.  The source
files in that directory implement a plugin named 'keyring_file' that
uses a file local to the server host for data storage.

To write a keyring plugin, include the following header file in the
plugin source file.  Other MySQL or general header files might also be
needed, depending on the plugin capabilities and requirements.

     #include <mysql/plugin_keyring.h>

'plugin_keyring.h' includes 'plugin.h', so you need not include the
latter file explicitly.  'plugin.h' defines the 'MYSQL_KEYRING_PLUGIN'
server plugin type and the data structures needed to declare the plugin.
'plugin_keyring.h' defines data structures specific to keyring plugins.

A keyring plugin, like any MySQL server plugin, has a general plugin
descriptor (see server-plugin-descriptors).  In 'keyring.cc',
the general descriptor for 'keyring_file' looks like this:

     mysql_declare_plugin(keyring_file)
     {
       MYSQL_KEYRING_PLUGIN,     /* type                                     */
       &keyring_descriptor,      /* descriptor                               */
       "keyring_file",           /* name                                     */
       "Oracle Corporation",     /* author                                   */
       "store/fetch authentication data to/from a flat file", /* description */
       PLUGIN_LICENSE_GPL,
       keyring_init,             /* init function (when loaded)              */
       keyring_deinit,           /* deinit function (when unloaded)          */
       0x0100,                   /* version                                  */
       NULL,                     /* status variables                         */
       keyring_system_variables, /* system variables                         */
       NULL,
       0,
     }
     mysql_declare_plugin_end;

The 'name' member ('keyring_file') indicates the plugin name.  This is
the name displayed by 'INFORMATION_SCHEMA.PLUGINS'.
or 'SHOW PLUGINS'.

The general descriptor also refers to 'keyring_system_variables', a
structure that exposes a system variable to the 'SHOW VARIABLES'
statement:

     static struct st_mysql_sys_var *keyring_system_variables[]= {
       MYSQL_SYSVAR(data),
       NULL
     };

The 'keyring_init' initialization function creates the data file if it
does not exist, then reads it and initializes the keystore.  The
'keyring_deinit' function frees data structures associated with the
file.

The 'keyring_descriptor' value in the general descriptor points to the
type-specific descriptor.  For keyring plugins, this descriptor has the
following structure:

     struct st_mysql_keyring
     {
       int interface_version;
       my_bool (*mysql_key_store)(const char *key_id, const char *key_type,
                                  const char* user_id, const void *key, size_t key_len);
       my_bool (*mysql_key_fetch)(const char *key_id, char **key_type,
                                  const char *user_id, void **key, size_t *key_len);
       my_bool (*mysql_key_remove)(const char *key_id, const char *user_id);
       my_bool (*mysql_key_generate)(const char *key_id, const char *key_type,
                                     const char *user_id, size_t key_len);
     };

The type-specific descriptor has these members:

   * 'interface_version': By convention, type-specific plugin
     descriptors begin with the interface version for the given plugin
     type.  The server checks 'interface_version' when it loads the
     plugin to see whether the plugin is compatible with it.  For
     keyring plugins, the value of the 'interface_version' member is
     'MYSQL_KEYRING_INTERFACE_VERSION' (defined in 'plugin_keyring.h').

   * 'mysql_key_store': A function that obfuscates and stores a key in
     the keyring.

   * 'mysql_key_fetch': A function that deobfuscates and retrieves a key
     from the keyring.

   * 'mysql_key_remove': A function that removes a key from the keyring.

   * 'mysql_key_generate': A function that generates a new random key
     and stores it in the keyring.

For the 'keyring_file' plugin, the type-specific descriptor looks like
this:

     static struct st_mysql_keyring keyring_descriptor=
     {
       MYSQL_KEYRING_INTERFACE_VERSION,
       mysql_key_store,
       mysql_key_fetch,
       mysql_key_remove,
       mysql_key_generate
     };

The 'mysql_key_XXX' functions implemented by a keyring plugin are
analogous to the 'my_key_XXX' functions exposed by the keyring service
API. For example, the 'mysql_key_store' plugin function is analogous to
the 'my_key_store' keyring service function.  For information about the
arguments to keyring service functions and how they are used, see
keyring-service.

To compile and install a plugin library file, use the instructions in
compiling-plugin-libraries.  To make the library file available
for use, install it in the plugin directory (the directory named by the
'plugin_dir' system variable).  For the 'keyring_file' plugin, it is
compiled and installed when you build MySQL from source.  It is also
included in binary distributions.  The build process produces a shared
object library with a name of 'keyring_file.so' (the '.so' suffix might
differ depending on your platform).

Keyring plugins typically are loaded early during the server startup
process so that they are available to built-in plugins and storage
engines that might depend on them.  For 'keyring_file', use these lines
in the server 'my.cnf' file (adjust the '.so' suffix for your platform
as necessary):

     [mysqld]
     early-plugin-load=keyring_file.so

For additional information about plugin loading, see
server-plugin-loading.

To verify plugin installation, examine the
'INFORMATION_SCHEMA.PLUGINS' table or use the
'SHOW PLUGINS' statement (see
obtaining-plugin-information).  For example:

     mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
            FROM INFORMATION_SCHEMA.PLUGINS
            WHERE PLUGIN_NAME LIKE 'keyring%';
     +--------------+---------------+
     | PLUGIN_NAME  | PLUGIN_STATUS |
     +--------------+---------------+
     | keyring_file | ACTIVE        |
     +--------------+---------------+

While the 'keyring_file' plugin is installed, it exposes a system
variable that indicates the location of the data file it uses for secure
information storage:

     mysql> SHOW VARIABLES LIKE 'keyring_file%';
     +-------------------+----------------------------------+
     | Variable_name     | Value                            |
     +-------------------+----------------------------------+
     | keyring_file_data | /usr/local/mysql/keyring/keyring |
     +-------------------+----------------------------------+

For a description of the 'keyring_file_data' variable, see
server-system-variables.

To disable the plugin after testing it, restart the server without an
'--early-plugin-load' option that names the plugin.

28.3 MySQL Services for Plugins
===============================

MySQL server plugins have access to server 'plugin services.' The plugin
services interface exposes server functionality that plugins can call.
It complements the plugin API and has these characteristics:

   * Services enable plugins to access code inside the server using
     ordinary function calls.  Services are also available to
     user-defined functions (UDFs).

   * Services are portable and work on multiple platforms.

   * The interface includes a versioning mechanism so that service
     versions supported by the server can be checked at load time
     against plugin versions.  Versioning protects against
     incompatibilities between the version of a service that the server
     provides and the version of the service expected or required by a
     plugin.

   * For information about plugins for testing plugin services, see
     Plugins for Testing Plugin Services
     (http://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PLUGINS.html).

The plugin services interface differs from the plugin API as follows:

   * The plugin API enables plugins to be used by the server.  The
     calling initiative lies with the server to invoke plugins.  This
     enables plugins to extend server functionality or register to
     receive notifications about server processing.

   * The plugin services interface enables plugins to call code inside
     the server.  The calling initiative lies with plugins to invoke
     service functions.  This enables functionality already implemented
     in the server to be used by many plugins; they need not
     individually implement it themselves.

To determine what services exist and what functions they provide, look
in the 'include/mysql' directory of a MySQL source distribution.  The
relevant files are:

   * 'plugin.h' includes 'services.h', which is the 'umbrella' header
     that includes all available service-specific header files.

   * Service-specific headers have names of the form 'service_XXX.h'.

Each service-specific header should contain comments that provide full
usage documentation for a given service, including what service
functions are available, their calling sequences, and return values.

For developers who wish to modify the server to add a new service, see
MySQL Internals: MySQL Services for Plugins
(http://dev.mysql.com/doc/internals/en/mysql-services-for-plugins.html).

Available services include the following:

   * 'locking_service': A service that implements locks with three
     attributes: Lock namespace, lock name, and lock mode.  This locking
     interface is available at two levels: 1) As a C language interface,
     callable as a plugin service from server plugins or user-defined
     functions; 2) At the SQL level, as a set of user-defined functions
     that map onto calls to the service routines.  For more information,
     see locking-service.

   * 'my_plugin_log_service': A service that enables plugins to report
     errors and specify error messages.  The server writes the messages
     to its error log.

   * 'my_snprintf': A string-formatting service that produces consistent
     results across platforms.

   * 'my_thd_scheduler': A service for plugins to select a thread
     scheduler.

   * 'mysql_keyring': A service for keyring storage.  For more
     information, see keyring-service.

   * 'mysql_password_policy': A service for password validation and
     strength checking.

   * 'mysql_string': A service for string manipulation.

   * 'security_context': A service that enables plugins to examine or
     manipulate thread security contexts.  This service provides setter
     and getter routines to access attributes of the server
     'Security_context' class, which includes attributes such as login
     user and host, authenticated user and host, and client IP address.

   * 'thd_alloc': A memory-allocation service.

   * 'thd_wait': A service for plugins to report when they are going to
     sleep or stall.

The remainder of this section describes how a plugin uses server
functionality that is available as a service.  See also the source for
the 'daemon' example plugin, which uses the 'my_snprintf' service.
Within a MySQL source distribution, that plugin is located in the
'plugin/daemon_example' directory.

To use a service or services from within a plugin, the plugin source
file must include the 'plugin.h' header file to access service-related
information:

     #include <mysql/plugin.h>

This does not represent any additional setup cost.  A plugin must
include that file anyway because it contains definitions and structures
that every plugin needs.

To access a service, a plugin calls service functions like any other
function.  For example, to format a string into a buffer for printing,
call the 'my_snprintf()' function provided by the service of the same
name:

     char buffer[BUFFER_SIZE];

     my_snprintf(buffer, sizeof(buffer), FORMAT_STRING, ARGUMENT_TO_FORMAT, ...);

To report an error that the server will write to it error log, first
choose an error level.  'mysql/service_my_plugin_log.h' defines these
levels:

     enum plugin_log_level
     {
       MY_ERROR_LEVEL,
       MY_WARNING_LEVEL,
       MY_INFORMATION_LEVEL
     };

Then invoke 'my_plugin_log_message()':

     int my_plugin_log_message(MYSQL_PLUGIN *plugin, enum plugin_log_level level,
                               const char *format, ...);

For example:

     my_plugin_log_message(plugin_ptr, MY_ERROR_LEVEL, "Cannot initialize plugin");

Some services _for_ plugins may be provided _by_ plugins and thus are
available only if the service-providing plugin is loaded.  Any MySQL
component that uses such a service should check whether the service is
available.

When you build your plugin, use the '-lmysqlservices' flag at link time
to link in the 'libmysqlservices' library.  For example, for 'CMake',
put this in the top-level 'CMakeLists.txt' file:

     FIND_LIBRARY(MYSQLSERVICES_LIB mysqlservices
      PATHS "${MYSQL_SRCDIR}/libservices" NO_DEFAULT_PATH)

Put this in the 'CMakeLists.txt' file in the directory containing the
plugin source:

     # the plugin needs the mysql services library for error logging
     TARGET_LINK_LIBRARIES (YOUR_PLUGIN_LIBRARY_NAME ${MYSQLSERVICES_LIB})

28.3.1 The Locking Service
--------------------------

Distributions of MySQL 5.7.8 or higher provide a locking interface that
is available at two levels:

   * As a C language interface, callable as a plugin service from server
     plugins or user-defined functions

   * At the SQL level, as a set of user-defined functions that map onto
     calls to the service routines

For general information about plugin services, see
plugin-services.  For general information about user-defined
functions, see adding-udf.

The locking interface has these characteristics:

   * Locks have three attributes: Lock namespace, lock name, and lock
     mode:

        * Locks are identified by the combination of namespace and lock
          name.  The namespace enables different applications to use the
          same lock names without colliding by creating locks in
          separate namespaces.  For example, if applications A and B use
          namespaces of 'ns1' and 'ns2', respectively, each application
          can use lock names 'lock1' and 'lock2' without interfering
          with the other application.

        * A lock mode is either read or write.  Read locks are shared:
          If a session has a read lock on a given lock identifier, other
          sessions can acquire a read lock on the same identifier.
          Write locks are exclusive: If a session has a write lock on a
          given lock identifier, other sessions cannot acquire a read or
          write lock on the same identifier.

   * Namespace and lock names must be non-'NULL', nonempty, and have a
     maximum length of 64 characters.  A namespace or lock name
     specified as 'NULL', the empty string, or a string longer than 64
     characters results in an 'ER_LOCKING_SERVICE_WRONG_NAME' error.

   * The locking interface treats namespace and lock names as binary
     strings, so comparisons are case-sensitive.

   * The locking interface provides functions to acquire locks and
     release locks.  No special privilege is required to call these
     functions.  Privilege checking is the responsibility of the calling
     application.

   * Locks can be waited for if not immediately available.  Lock
     acquisition calls take an integer timeout value that indicates how
     many seconds to wait to acquire locks before giving up.  If the
     timeout is reached without successful lock acquisition, an
     'ER_LOCKING_SERVICE_TIMEOUT' error occurs.  If the timeout is 0,
     there is no waiting and the call produces an error if locks cannot
     be acquired immediately.

   * The locking interface detects deadlock between lock-acquisition
     calls in different sessions.  In this case, the locking service
     chooses a caller and terminates its lock-acquisition request with
     an 'ER_LOCKING_SERVICE_DEADLOCK' error.  This error does not cause
     transactions to roll back.  To choose a session in case of
     deadlock, the locking service prefers sessions that hold read locks
     over sessions that hold write locks.

   * A session can acquire multiple locks with a single lock-acquisition
     call.  For a given call, lock acquisition is atomic: The call
     succeeeds if all locks are acquired.  If acquisition of any lock
     fails, the call acquires no locks and fails, typically with an
     'ER_LOCKING_SERVICE_TIMEOUT' or 'ER_LOCKING_SERVICE_DEADLOCK'
     error.

   * A session can acquire multiple locks for the same lock identifier
     (namespace and lock name combination).  These lock instances can be
     read locks, write locks, or a mix of both.

   * Locks acquired within a session are released explicitly by calling
     a release-locks function, or implicitly when the session terminates
     (either normally or abnormally).  Locks are not released when
     transactions commit or roll back.

   * Within a session, all locks for a given namespace when released are
     released together.

The interface provided by the locking service is distinct from that
provided by 'GET_LOCK()' and related SQL functions (see
miscellaneous-functions).  For example, 'GET_LOCK()' does not
implement namespaces and provides only exclusive locks, not distinct
read and write locks.

28.3.1.1 The Locking Service C Interface
........................................

This section describes how to use the locking service C language
interface.  To use the UDF interface instead, see
locking-service-udf-interface For general characteristics of the
locking service interface, see locking-service.  For general
information about plugin services, see plugin-services.

Source files that use the locking service should include this header
file:

     #include <mysql/service_locking.h>

To acquire one or more locks, call this function:

     int mysql_acquire_locking_service_locks(MYSQL_THD opaque_thd,
                                             const char* lock_namespace,
                                             const char**lock_names,
                                             size_t lock_num,
                                             enum enum_locking_service_lock_type lock_type,
                                             unsigned long lock_timeout);

The arguments have these meanings:

   * 'opaque_thd': A thread handle.  If specified as 'NULL', the handle
     for the current thread is used.

   * 'lock_namespace': A null-terminated string that indicates the lock
     namespace.

   * 'lock_names': An array of null-terminated strings that provides the
     names of the locks to acquire.

   * 'lock_num': The number of names in the 'lock_names' array.

   * 'lock_type': The lock mode, either 'LOCKING_SERVICE_READ' or
     'LOCKING_SERVICE_WRITE' to acquire read locks or write locks,
     respectively.

   * 'lock_timeout': An integer number of seconds to wait to acquire the
     locks before giving up.

To release locks acquired for a given namespace, call this function:

     int mysql_release_locking_service_locks(MYSQL_THD opaque_thd,
                                             const char* lock_namespace);

The arguments have these meanings:

   * 'opaque_thd': A thread handle.  If specified as 'NULL', the handle
     for the current thread is used.

   * 'lock_namespace': A null-terminated string that indicates the lock
     namespace.

Locks acquired or waited for by the locking service can be monitored at
the SQL level using the Performance Schema.  For details, see
locking-service-monitoring.

28.3.1.2 The Locking Service UDF Interface
..........................................

This section describes how to use the locking service user-defined
function (UDF) interface.  To use the C language interface instead, see
locking-service-c-interface For general characteristics of the
locking service interface, see locking-service.  For general
information about user-defined functions, see adding-udf.

28.3.1.3 Installing or Uninstalling the UDF Locking Interface
.............................................................

The locking service routines described in
locking-service-c-interface need not be installed because they are
built into the server.  The same is not true of the user-defined
functions (UDFs) that map onto calls to the service routines: The UDFs
must be installed before use.  This section describes how to do that.
For general information about UDF installation, see
udf-compiling.

The locking service UDFs are implemented in a plugin library file
located in the directory named by the 'plugin_dir' system variable.  The
file base name is 'locking_service'.  The file name suffix differs per
platform (for example, '.so' for Unix and Unix-like systems, '.dll' for
Windows).

To install the locking service UDFs, use the 'CREATE FUNCTION'
statement (adjust the '.so' suffix for your platform as
necessary):

     CREATE FUNCTION service_get_read_locks RETURNS INT SONAME 'locking_service.so';
     CREATE FUNCTION service_get_write_locks RETURNS INT SONAME 'locking_service.so';
     CREATE FUNCTION service_release_locks RETURNS INT SONAME 'locking_service.so';

If the UDFs are used on a master replication server, install them on all
slave servers as well to avoid replication problems.

Once installed, the UDFs remain installed until uninstalled.  To remove
them, use the 'DROP FUNCTION' statement:

     DROP FUNCTION service_get_read_locks;
     DROP FUNCTION service_get_write_locks;
     DROP FUNCTION service_release_locks;

28.3.1.4 Using the UDF Locking Interface
........................................

Before using the locking service UDFs, install them according to the
instructions provided at locking-service-udf-installation.

To acquire one or more read locks, call this function:

     mysql> SELECT service_get_read_locks('mynamespace', 'rlock1', 'rlock2', 10);
     +---------------------------------------------------------------+
     | service_get_read_locks('mynamespace', 'rlock1', 'rlock2', 10) |
     +---------------------------------------------------------------+
     |                                                             1 |
     +---------------------------------------------------------------+

The first argument is the lock namespace.  The final argument is an
integer timeout indicating how many seconds to wait to acquire the locks
before giving up.  The arguments in between are the lock names.

For the example just shown, the function acquires locks with lock
identifiers '(mynamespace, rlock1)' and '(mynamespace, rlock2)'.

To acquire write locks rather than read locks, call this function:

     mysql> SELECT service_get_write_locks('mynamespace', 'wlock1', 'wlock2', 10);
     +----------------------------------------------------------------+
     | service_get_write_locks('mynamespace', 'wlock1', 'wlock2', 10) |
     +----------------------------------------------------------------+
     |                                                              1 |
     +----------------------------------------------------------------+

In this case, the lock identifiers are '(mynamespace, wlock1)' and
'(mynamespace, wlock2)'.

To release all locks for a namespace, use this function:

     mysql> SELECT service_release_locks('mynamespace');
     +--------------------------------------+
     | service_release_locks('mynamespace') |
     +--------------------------------------+
     |                                    1 |
     +--------------------------------------+

Each locking function returns nonzero for success.  If the function
fails, an error occurs.  For example, the following error occurs because
lock names cannot be empty:

     mysql> SELECT service_get_read_locks('mynamespace', '', 10);
     ERROR 3131 (42000): Incorrect locking service lock name ''.

A session can acquire multiple locks for the same lock identifier.  As
long as a different session does not have a write lock for an
identifier, the session can acquire any number of read or write locks.
Each lock request for the identifier acquires a new lock.  The following
statements acquire three write locks with the same identifier, then
three read locks for the same identifier:

     SELECT service_get_write_locks('ns', 'lock1', 'lock1', 'lock1', 0);
     SELECT service_get_read_locks('ns', 'lock1', 'lock1', 'lock1', 0);

If you examine the Performance Schema 'metadata_locks' table at this
point, you will find that the session holds six distinct locks with the
same '(ns, lock1)' identifier.  (For details, see
locking-service-monitoring.)

Because the session holds at least one write lock on '(ns, lock1)', no
other session can acquire a lock for it, either read or write.  If the
session held only read locks for the identifier, other sessions could
acquire read locks for it, but not write locks.

Locks for a single lock-acquisition call are acquired atomically, but
atomicity does not hold across calls.  Thus, for a statement such as the
following, where 'service_get_write_locks()' is called once per row of
the result set, atomicity holds for each individual call, but not for
the statement as a whole:

     SELECT service_get_write_locks('ns', 'lock1', 'lock2', 0) FROM t1 WHERE ... ;

*Caution*:

Because the locking service returns a separate lock for each successful
request for a given lock identifier, it is possible for a single
statement to acquire a large number of locks.  For example:

     INSERT INTO ... SELECT service_get_write_locks('ns', t1.col_name, 0) FROM t1;

These types of statements may have certain adverse effects.  For
example, if the statement fails part way through and rolls back, locks
acquired up to the point of failure will still exist.  If the intent is
for there to be a correspondence between rows inserted and locks
acquired, that intent will not be satisfied.  Also, if it is important
that locks are granted in a certain order, be aware that result set
order may differ depending on which execution plan the optimizer
chooses.  For these reasons, it may be best to limit applications to a
single lock-acquisition call per statement.

28.3.1.5 Locking Service Monitoring
...................................

The locking service is implemented using the MySQL Server metadata locks
framework, so you monitor locking service locks acquired or waited for
by examining the Performance Schema 'metadata_locks' table.

First, enable the metadata lock instrument:

     mysql> UPDATE performance_schema.setup_instruments SET ENABLED = 'YES'
         -> WHERE NAME = 'wait/lock/metadata/sql/mdl';

Then acquire some locks and check the contents of the 'metadata_locks'
table:

     mysql> SELECT service_get_write_locks('mynamespace', 'lock1', 0);
     +----------------------------------------------------+
     | service_get_write_locks('mynamespace', 'lock1', 0) |
     +----------------------------------------------------+
     |                                                  1 |
     +----------------------------------------------------+
     mysql> SELECT service_get_read_locks('mynamespace', 'lock2', 0);
     +---------------------------------------------------+
     | service_get_read_locks('mynamespace', 'lock2', 0) |
     +---------------------------------------------------+
     |                                                 1 |
     +---------------------------------------------------+
     mysql> SELECT OBJECT_TYPE, OBJECT_SCHEMA, OBJECT_NAME, LOCK_TYPE, LOCK_STATUS
         -> FROM performance_schema.metadata_locks
         -> WHERE OBJECT_TYPE = 'LOCKING SERVICE'\G
     *************************** 1. row ***************************
       OBJECT_TYPE: LOCKING SERVICE
     OBJECT_SCHEMA: mynamespace
       OBJECT_NAME: lock1
         LOCK_TYPE: EXCLUSIVE
       LOCK_STATUS: GRANTED
     *************************** 2. row ***************************
       OBJECT_TYPE: LOCKING SERVICE
     OBJECT_SCHEMA: mynamespace
       OBJECT_NAME: lock2
         LOCK_TYPE: SHARED
       LOCK_STATUS: GRANTED

Locking service locks have an 'OBJECT_TYPE' value of 'LOCKING SERVICE'.
This is distinct from, for example, locks acquired with the 'GET_LOCK()'
function, which have an 'OBJECT_TYPE' of 'USER LEVEL LOCK'.

The lock namespace, name, and mode appear in the 'OBJECT_SCHEMA',
'OBJECT_NAME', and 'LOCK_TYPE' columns.  Read and write locks have
'LOCK_TYPE' values of 'SHARED' and 'EXCLUSIVE', respectively.

The 'LOCK_STATUS' value is 'GRANTED' for an acquired lock, 'PENDING' for
a lock that is being waited for.  You will see 'PENDING' if one session
holds a write lock and another session is attempting to acquire a lock
having the same identifier.

28.3.1.6 Locking Service UDF Interface Reference
................................................

The SQL interface to the locking service implements the user-defined
functions described in this section.  For usage examples, see
locking-service-udf-usage.

The functions share these characteristics:

   * The return value is nonzero for success.  Otherwise, an error
     occurs.

   * Namespace and lock names must be non-'NULL', nonempty, and have a
     maximum length of 64 characters.

   * Timeout values must be integers indicating how many seconds to wait
     to acquire locks before giving up with an error.  If the timeout is
     0, there is no waiting and the function produces an error if locks
     cannot be acquired immediately.

These locking service UDFs are available:

   * 'service_get_read_locks(NAMESPACE, LOCK_NAME[, LOCK_NAME] ...,
     TIMEOUT)'

     Acquires one or more read (shared) locks in the given namespace
     using the given lock names, timing out with an error if the locks
     are not acquired within the given timeout value.

   * 'service_get_write_locks(NAMESPACE, LOCK_NAME[, LOCK_NAME] ...,
     TIMEOUT)'

     Acquires one or more write (exclusive) locks in the given namespace
     using the given lock names, timing out with an error if the locks
     are not acquired within the given timeout value.

   * 'service_release_locks(NAMESPACE)'

     For the given namespace, releases all locks that were acquired
     within the current session using 'service_get_read_locks()' and
     'service_get_write_locks()'.

     It is not an error for there to be no locks in the namespace.

28.3.2 The Keyring Service
--------------------------

MySQL Server supports a keyring service that enables internal server
components and plugins to securely store sensitive information for later
retrieval.  This section describes how to use the keyring service
functions to store, retrieve, and remove keys in the MySQL keyring
keystore.  An SQL interface to the keyring service functions is also
available as a set of user-defined functions (UDFs); see
keyring-udfs-general-purpose.  For general keyring information, see
keyring.

The keyring service uses whatever underlying keyring plugin is enabled,
if any.  If no keyring plugin is enabled, keyring service calls fail.

A 'record' in the keystore consists of data (the key itself) and a
unique identifier through which the key is accessed.  The identifier has
two parts:

   * 'key_id': The key ID or name.  'key_id' values that begin with
     'mysql_' are reserved by MySQL Server.

   * 'user_id': The session effective user ID. If there is no user
     context, this value can be 'NULL'.  The value need not actually be
     a 'user'; the meaning depends on the application.

     Functions that implement the keyring UDF interface pass the value
     of 'CURRENT_USER()' as the 'user_id' value to keyring service
     functions.

The keyring service functions have these characteristics in common:

   * Each function returns 0 for success, 1 for failure.

   * The 'key_id' and 'user_id' arguments form a unique combination
     indicating which key in the keyring to use.

   * The 'key_type' argument provides additional information about the
     key, such as its encryption method or intended use.

   * Keyring service functions treat key IDs, user names, types, and
     values as binary strings, so comparisons are case sensitive.  For
     example, IDs of 'MyKey' and 'mykey' refer to different keys.

These keyring service functions are available:

   * 'my_key_fetch()'

     Deobfuscates and retrieves a key from the keyring, along with its
     type.  The function allocates the memory for the buffers used to
     store the returned key and key type.  The caller should zero or
     obfuscate the memory when it is no longer needed, then free it.

     Syntax:

          my_bool my_key_fetch(const char *key_id, const char **key_type,
                               const char* user_id, void **key, size_t *key_len)

     Arguments:

        * 'key_id', 'user_id': Null-terminated strings that as a pair
          form a unique identifier indicating which key to fetch.

        * 'key_type': The address of a buffer pointer.  The function
          stores into it a pointer to a null-terminated string that
          provides additional information about the key (stored when the
          key was added).

        * 'key': The address of a buffer pointer.  The function stores
          into it a pointer to the buffer containing the fetched key
          data.

        * 'key_len': The address of a variable into which the function
          stores the size in bytes of the '*key' buffer.

     Return values:

     Returns 0 for success, 1 for failure.

   * 'my_key_generate()'

     Generates a new random key of a given type and length and stores it
     in the keyring.  The key has a length of 'key_len' and is
     associated with the identifier formed from 'key_id' and 'user_id'.
     The type and length values must be consistent with the values
     supported by the underlying keyring plugin.  See
     keyring-key-types.

     Syntax:

          my_bool my_key_generate(const char *key_id, const char *key_type,
                                  const char *user_id, size_t key_len)

     Arguments:

        * 'key_id', 'user_id': Null-terminated strings that as a pair
          form a unique identifier for the key to be generated.

        * 'key_type': A null-terminated string that provides additional
          information about the key.

        * 'key_len': The size in bytes of the key to be generated.

     Return values:

     Returns 0 for success, 1 for failure.

   * 'my_key_remove()'

     Removes a key from the keyring.

     Syntax:

          my_bool my_key_remove(const char *key_id, const char* user_id)

     Arguments:

        * 'key_id', 'user_id': Null-terminated strings that as a pair
          form a unique identifier for the key to be removed.

     Return values:

     Returns 0 for success, 1 for failure.

   * 'my_key_store()'

     Obfuscates and stores a key in the keyring.

     Syntax:

          my_bool my_key_store(const char *key_id, const char *key_type,
                               const char* user_id, void *key, size_t key_len)

     Arguments:

        * 'key_id', 'user_id': Null-terminated strings that as a pair
          form a unique identifier for the key to be stored.

        * 'key_type': A null-terminated string that provides additional
          information about the key.

        * 'key': The buffer containing the key data to be stored.

        * 'key_len': The size in bytes of the 'key' buffer.

     Return values:

     Returns 0 for success, 1 for failure.

28.4 Adding New Functions to MySQL
==================================

There are three ways to add new functions to MySQL:

   * You can add functions through the user-defined function (UDF)
     interface.  User-defined functions are compiled as library files
     and then added to and removed from the server dynamically using the
     'CREATE FUNCTION' and 'DROP FUNCTION'
     statements.  See
     create-function-udf.

   * You can add functions as native (built-in) MySQL functions.  Native
     functions are compiled into the 'mysqld' server and
     become available on a permanent basis.

   * Another way to add functions is by creating stored functions.
     These are written using SQL statements rather than by compiling
     object code.  The syntax for writing stored functions is not
     covered here.  See stored-routines.

Each method of creating compiled functions has advantages and
disadvantages:

   * If you write user-defined functions, you must install object files
     in addition to the server itself.  If you compile your function
     into the server, you need not do that.

   * Native functions require you to modify a source distribution.  UDFs
     do not.  You can add UDFs to a binary MySQL distribution.  No
     access to MySQL source is necessary.

   * If you upgrade your MySQL distribution, you can continue to use
     your previously installed UDFs, unless you upgrade to a newer
     version for which the UDF interface changes.  For native functions,
     you must repeat your modifications each time you upgrade.

Whichever method you use to add new functions, they can be invoked in
SQL statements just like native functions such as 'ABS()' or
'SOUNDEX()'.

See function-resolution, for the rules describing how the server
interprets references to different kinds of functions.

The following sections describe features of the UDF interface, provide
instructions for writing UDFs, discuss security precautions that MySQL
takes to prevent UDF misuse, and describe how to add native MySQL
functions.

For example source code that illustrates how to write UDFs, take a look
at the 'sql/udf_example.cc' file that is provided in MySQL source
distributions.

28.4.1 Features of the User-Defined Function Interface
------------------------------------------------------

The MySQL interface for user-defined functions provides the following
features and capabilities:

   * Functions can return string, integer, or real values and can accept
     arguments of those same types.

   * You can define simple functions that operate on a single row at a
     time, or aggregate functions that operate on groups of rows.

   * Information is provided to functions that enables them to check the
     number, types, and names of the arguments passed to them.

   * You can tell MySQL to coerce arguments to a given type before
     passing them to a function.

   * You can indicate that a function returns 'NULL' or that an error
     occurred.

28.4.2 Adding a New User-Defined Function
-----------------------------------------

For the UDF mechanism to work, functions must be written in C or C++ and
your operating system must support dynamic loading.  MySQL source
distributions include a file 'sql/udf_example.cc' that defines five UDF
functions.  Consult this file to see how UDF calling conventions work.
The 'include/mysql_com.h' header file defines UDF-related symbols and
data structures, although you need not include this header file
directly; it is included by 'mysql.h'.

A UDF contains code that becomes part of the running server, so when you
write a UDF, you are bound by any and all constraints that apply to
writing server code.  For example, you may have problems if you attempt
to use functions from the 'libstdc++' library.  These constraints may
change in future versions of the server, so it is possible that server
upgrades will require revisions to UDFs that were originally written for
older servers.  For information about these constraints, see
source-configuration-options, and compilation-problems.

To be able to use UDFs, you must link 'mysqld'.
dynamically.  If you want to use a UDF that needs to access symbols from
'mysqld'. (for example, the 'metaphone' function in
'sql/udf_example.cc' uses 'default_charset_info'), you must link the
program with '-rdynamic' (see 'man dlopen').

For each function that you want to use in SQL statements, you should
define corresponding C (or C++) functions.  In the following discussion,
the name 'xxx' is used for an example function name.  To distinguish
between SQL and C/C++ usage, 'XXX()' (uppercase) indicates an SQL
function call, and 'xxx()' (lowercase) indicates a C/C++ function call.

*Note*:

When using C++ you can encapsulate your C functions within:

     extern "C" { ... }

This ensures that your C++ function names remain readable in the
completed UDF.

The following list describes the C/C++ functions that you write to
implement the interface for a function named 'XXX()'.  The main
function, 'xxx()', is required.  In addition, a UDF requires at least
one of the other functions described here, for reasons discussed in
udf-security.

   * 'xxx()'

     The main function.  This is where the function result is computed.
     The correspondence between the SQL function data type and the
     return type of your C/C++ function is shown here.

     SQL Type           C/C++ Type

     'STRING'           'char *'

     See 'INTEGER'.

     See 'REAL'.

     It is also possible to declare a 'DECIMAL'
     function, but currently the value is returned as
     a string, so you should write the UDF as though it were a 'STRING'
     function.  'ROW' functions are not implemented.

   * 'xxx_init()'

     The initialization function for 'xxx()'.  If present, it can be
     used for the following purposes:

        * To check the number of arguments to 'XXX()'.

        * To verify that the arguments are of a required type or,
          alternatively, to tell MySQL to coerce arguments to the
          required types when the main function is called.

        * To allocate any memory required by the main function.

        * To specify the maximum length of the result.

        * To specify (for 'REAL' functions)
          the maximum number of decimal places in the result.

        * To specify whether the result can be 'NULL'.

   * 'xxx_deinit()'

     The deinitialization function for 'xxx()'.  If present, it should
     deallocate any memory allocated by the initialization function.

When an SQL statement invokes 'XXX()', MySQL calls the initialization
function 'xxx_init()' to let it perform any required setup, such as
argument checking or memory allocation.  If 'xxx_init()' returns an
error, MySQL aborts the SQL statement with an error message and does not
call the main or deinitialization functions.  Otherwise, MySQL calls the
main function 'xxx()' once for each row.  After all rows have been
processed, MySQL calls the deinitialization function 'xxx_deinit()' so
that it can perform any required cleanup.

For aggregate functions that work like 'SUM()', you must also provide
the following functions:

   * 'xxx_clear()'

     Reset the current aggregate value but do not insert the argument as
     the initial aggregate value for a new group.

   * 'xxx_add()'

     Add the argument to the current aggregate value.

MySQL handles aggregate UDFs as follows:

  1. Call 'xxx_init()' to let the aggregate function allocate any memory
     it needs for storing results.

  2. Sort the table according to the 'GROUP BY' expression.

  3. Call 'xxx_clear()' for the first row in each new group.

  4. Call 'xxx_add()' for each row that belongs in the same group.

  5. Call 'xxx()' to get the result for the aggregate when the group
     changes or after the last row has been processed.

  6. Repeat steps 3 to 5 until all rows has been processed

  7. Call 'xxx_deinit()' to let the UDF free any memory it has
     allocated.

All functions must be thread-safe.  This includes not just the main
function, but the initialization and deinitialization functions as well,
and also the additional functions required by aggregate functions.  A
consequence of this requirement is that you are not permitted to
allocate any global or static variables that change!  If you need
memory, you should allocate it in 'xxx_init()' and free it in
'xxx_deinit()'.

28.4.2.1 UDF Calling Sequences for Simple Functions
...................................................

This section describes the different functions that you need to define
when you create a simple UDF. See adding-udf, describes the order in
which MySQL calls these functions.

The main 'xxx()' function should be declared as shown in this section.
Note that the return type and parameters differ, depending on whether
you declare the SQL function 'XXX()' to return 'STRING', see
'INTEGER', or 'REAL' in the
'CREATE FUNCTION' statement:

For 'STRING' functions:

     char *xxx(UDF_INIT *initid, UDF_ARGS *args,
               char *result, unsigned long *length,
               char *is_null, char *error);

For 'INTEGER' functions:

     long long xxx(UDF_INIT *initid, UDF_ARGS *args,
                   char *is_null, char *error);

For 'REAL' functions:

     double xxx(UDF_INIT *initid, UDF_ARGS *args,
                   char *is_null, char *error);

'DECIMAL' functions return string values and
should be declared the same way as 'STRING' functions.  'ROW' functions
are not implemented.

The initialization and deinitialization functions are declared like
this:

     my_bool xxx_init(UDF_INIT *initid, UDF_ARGS *args, char *message);

     void xxx_deinit(UDF_INIT *initid);

The 'initid' parameter is passed to all three functions.  It points to a
'UDF_INIT' structure that is used to communicate information between
functions.  The 'UDF_INIT' structure members follow.  The initialization
function should fill in any members that it wishes to change.  (To use
the default for a member, leave it unchanged.)

   * 'my_bool maybe_null'

     'xxx_init()' should set 'maybe_null' to '1' if 'xxx()' can return
     'NULL'.  The default value is '1' if any of the arguments are
     declared 'maybe_null'.

   * 'unsigned int decimals'

     The number of decimal digits to the right of the decimal point.
     The default value is the maximum number of decimal digits in the
     arguments passed to the main function.  For example, if the
     function is passed '1.34', '1.345', and '1.3', the default would be
     3, because '1.345' has 3 decimal digits.

     For arguments that have no fixed number of decimals, the 'decimals'
     value is set to 31, which is 1 more than the maximum number of
     decimals permitted for the 'DECIMAL',
     'FLOAT', and 'DOUBLE'
     data types.  This value is available as the
     constant 'NOT_FIXED_DEC' in the 'mysql_com.h' header file.

     A 'decimals' value of 31 is used for arguments in cases such as a
     'FLOAT' or 'DOUBLE'
     column declared without an explicit number of
     decimals (for example, see 'FLOAT' rather
     than 'FLOAT(10,3)') and for floating-point constants such as
     '1345E-3'.  It is also used for string and other nonnumber
     arguments that might be converted within the function to numeric
     form.

     The value to which the 'decimals' member is initialized is only a
     default.  It can be changed within the function to reflect the
     actual calculation performed.  The default is determined such that
     the largest number of decimals of the arguments is used.  If the
     number of decimals is 'NOT_FIXED_DEC' for even one of the
     arguments, that is the value used for 'decimals'.

   * 'unsigned int max_length'

     The maximum length of the result.  The default 'max_length' value
     differs depending on the result type of the function.  For string
     functions, the default is the length of the longest argument.  For
     integer functions, the default is 21 digits.  For real functions,
     the default is 13 plus the number of decimal digits indicated by
     'initid->decimals'.  (For numeric functions, the length includes
     any sign or decimal point characters.)

     If you want to return a blob value, you can set 'max_length' to
     65KB or 16MB. This memory is not allocated, but the value is used
     to decide which data type to use if there is a need to temporarily
     store the data.

   * 'char *ptr'

     A pointer that the function can use for its own purposes.  For
     example, functions can use 'initid->ptr' to communicate allocated
     memory among themselves.  'xxx_init()' should allocate the memory
     and assign it to this pointer:

          initid->ptr = allocated_memory;

     In 'xxx()' and 'xxx_deinit()', refer to 'initid->ptr' to use or
     deallocate the memory.

   * 'my_bool const_item'

     'xxx_init()' should set 'const_item' to '1' if 'xxx()' always
     returns the same value and to '0' otherwise.

28.4.2.2 UDF Calling Sequences for Aggregate Functions
......................................................

This section describes the different functions that you need to define
when you create an aggregate UDF. See adding-udf, describes the
order in which MySQL calls these functions.

   * 'xxx_reset()'

     This function is called when MySQL finds the first row in a new
     group.  It should reset any internal summary variables and then use
     the given 'UDF_ARGS' argument as the first value in your internal
     summary value for the group.  Declare 'xxx_reset()' as follows:

          void xxx_reset(UDF_INIT *initid, UDF_ARGS *args,
                         char *is_null, char *error);

     'xxx_reset()' is not needed or used in MySQL 5.7, in which the UDF
     interface uses 'xxx_clear()' instead.  However, you can define both
     'xxx_reset()' and 'xxx_clear()' if you want to have your UDF work
     with older versions of the server.  (If you do include both
     functions, the 'xxx_reset()' function in many cases can be
     implemented internally by calling 'xxx_clear()' to reset all
     variables, and then calling 'xxx_add()' to add the 'UDF_ARGS'
     argument as the first value in the group.)

   * 'xxx_clear()'

     This function is called when MySQL needs to reset the summary
     results.  It is called at the beginning for each new group but can
     also be called to reset the values for a query where there were no
     matching rows.  Declare 'xxx_clear()' as follows:

          void xxx_clear(UDF_INIT *initid, char *is_null, char *error);

     'is_null' is set to point to 'CHAR(0)' before calling
     'xxx_clear()'.

     If something went wrong, you can store a value in the variable to
     which the 'error' argument points.  'error' points to a single-byte
     variable, not to a string buffer.

     'xxx_clear()' is required by MySQL 5.7.

   * 'xxx_add()'

     This function is called for all rows that belong to the same group.
     You should use it to add the value in the 'UDF_ARGS' argument to
     your internal summary variable.

          void xxx_add(UDF_INIT *initid, UDF_ARGS *args,
                       char *is_null, char *error);

The 'xxx()' function for an aggregate UDF should be declared the same
way as for a nonaggregate UDF. See udf-calling.

For an aggregate UDF, MySQL calls the 'xxx()' function after all rows in
the group have been processed.  You should normally never access its
'UDF_ARGS' argument here but instead return a value based on your
internal summary variables.

Return value handling in 'xxx()' should be done the same way as for a
nonaggregate UDF. See udf-return-values.

The 'xxx_reset()' and 'xxx_add()' functions handle their 'UDF_ARGS'
argument the same way as functions for nonaggregate UDFs.  See
udf-arguments.

The pointer arguments to 'is_null' and 'error' are the same for all
calls to 'xxx_reset()', 'xxx_clear()', 'xxx_add()' and 'xxx()'.  You can
use this to remember that you got an error or whether the 'xxx()'
function should return 'NULL'.  You should not store a string into
'*error'!  'error' points to a single-byte variable, not to a string
buffer.

'*is_null' is reset for each group (before calling 'xxx_clear()').
'*error' is never reset.

If '*is_null' or '*error' are set when 'xxx()' returns, MySQL returns
'NULL' as the result for the group function.

28.4.2.3 UDF Argument Processing
................................

The 'args' parameter points to a 'UDF_ARGS' structure that has the
members listed here:

   * 'unsigned int arg_count'

     The number of arguments.  Check this value in the initialization
     function if you require your function to be called with a
     particular number of arguments.  For example:

          if (args->arg_count != 2)
          {
              strcpy(message,"XXX() requires two arguments");
              return 1;
          }

     For other 'UDF_ARGS' member values that are arrays, array
     references are zero-based.  That is, refer to array members using
     index values from 0 to 'args->arg_count' − 1.

   * 'enum Item_result *arg_type'

     A pointer to an array containing the types for each argument.  The
     possible type values are 'STRING_RESULT', 'INT_RESULT',
     'REAL_RESULT', and 'DECIMAL_RESULT'.

     To make sure that arguments are of a given type and return an error
     if they are not, check the 'arg_type' array in the initialization
     function.  For example:

          if (args->arg_type[0] != STRING_RESULT ||
              args->arg_type[1] != INT_RESULT)
          {
              strcpy(message,"XXX() requires a string and an integer");
              return 1;
          }

     Arguments of type 'DECIMAL_RESULT' are passed as strings, so you
     should handle them the same way as 'STRING_RESULT' values.

     As an alternative to requiring your function's arguments to be of
     particular types, you can use the initialization function to set
     the 'arg_type' elements to the types you want.  This causes MySQL
     to coerce arguments to those types for each call to 'xxx()'.  For
     example, to specify that the first two arguments should be coerced
     to string and integer, respectively, do this in 'xxx_init()':

          args->arg_type[0] = STRING_RESULT;
          args->arg_type[1] = INT_RESULT;

     Exact-value decimal arguments such as '1.3' or 'DECIMAL'
     column values are passed with a type of
     'DECIMAL_RESULT'.  However, the values are passed as strings.  If
     you want to receive a number, use the initialization function to
     specify that the argument should be coerced to a 'REAL_RESULT'
     value:

          args->arg_type[2] = REAL_RESULT;

   * 'char **args'

     'args->args' communicates information to the initialization
     function about the general nature of the arguments passed to your
     function.  For a constant argument 'i', 'args->args[i]' points to
     the argument value.  (See later for instructions on how to access
     the value properly.)  For a nonconstant argument, 'args->args[i]'
     is '0'.  A constant argument is an expression that uses only
     constants, such as '3' or '4*7-2' or 'SIN(3.14)'.  A nonconstant
     argument is an expression that refers to values that may change
     from row to row, such as column names or functions that are called
     with nonconstant arguments.

     For each invocation of the main function, 'args->args' contains the
     actual arguments that are passed for the row currently being
     processed.

     If argument 'i' represents 'NULL', 'args->args[i]' is a null
     pointer (0).  If the argument is not 'NULL', functions can refer to
     it as follows:

        * An argument of type 'STRING_RESULT' is given as a string
          pointer plus a length, to enable handling of binary data or
          data of arbitrary length.  The string contents are available
          as 'args->args[i]' and the string length is
          'args->lengths[i]'.  Do not assume that the string is
          null-terminated.

        * For an argument of type 'INT_RESULT', you must cast
          'args->args[i]' to a 'long long' value:

               long long int_val;
               int_val = *((long long*) args->args[i]);

        * For an argument of type 'REAL_RESULT', you must cast
          'args->args[i]' to a 'double' value:

               double    real_val;
               real_val = *((double*) args->args[i]);

        * For an argument of type 'DECIMAL_RESULT', the value is passed
          as a string and should be handled like a 'STRING_RESULT'
          value.

        * 'ROW_RESULT' arguments are not implemented.

   * 'unsigned long *lengths'

     For the initialization function, the 'lengths' array indicates the
     maximum string length for each argument.  You should not change
     these.  For each invocation of the main function, 'lengths'
     contains the actual lengths of any string arguments that are passed
     for the row currently being processed.  For arguments of types
     'INT_RESULT' or 'REAL_RESULT', 'lengths' still contains the maximum
     length of the argument (as for the initialization function).

   * 'char *maybe_null'

     For the initialization function, the 'maybe_null' array indicates
     for each argument whether the argument value might be null (0 if
     no, 1 if yes).

   * 'char **attributes'

     'args->attributes' communicates information about the names of the
     UDF arguments.  For argument 'i', the attribute name is available
     as a string in 'args->attributes[i]' and the attribute length is
     'args->attribute_lengths[i]'.  Do not assume that the string is
     null-terminated.

     By default, the name of a UDF argument is the text of the
     expression used to specify the argument.  For UDFs, an argument may
     also have an optional '[AS] ALIAS_NAME' clause, in which case the
     argument name is ALIAS_NAME.  The 'attributes' value for each
     argument thus depends on whether an alias was given.

     Suppose that a UDF 'my_udf()' is invoked as follows:

          SELECT my_udf(expr1, expr2 AS alias1, expr3 alias2);

     In this case, the 'attributes' and 'attribute_lengths' arrays will
     have these values:

          args->attributes[0] = "expr1"
          args->attribute_lengths[0] = 5

          args->attributes[1] = "alias1"
          args->attribute_lengths[1] = 6

          args->attributes[2] = "alias2"
          args->attribute_lengths[2] = 6

   * 'unsigned long *attribute_lengths'

     The 'attribute_lengths' array indicates the length of each argument
     name.

28.4.2.4 UDF Return Values and Error Handling
.............................................

The initialization function should return '0' if no error occurred and
'1' otherwise.  If an error occurs, 'xxx_init()' should store a
null-terminated error message in the 'message' parameter.  The message
is returned to the client.  The message buffer is 'MYSQL_ERRMSG_SIZE'
characters long, but you should try to keep the message to less than 80
characters so that it fits the width of a standard terminal screen.

The return value of the main function 'xxx()' is the function value, for
'long long' and 'double' functions.  A string function should return a
pointer to the result and set '*length' to the length (in bytes) of the
return value.  For example:

     memcpy(result, "result string", 13);
     *length = 13;

MySQL passes a buffer to the 'xxx()' function using the 'result'
parameter.  This buffer is sufficiently long to hold 255 characters,
which can be multibyte characters.  The 'xxx()' function can store the
result in this buffer if it fits, in which case the return value should
be a pointer to the buffer.  If the function stores the result in a
different buffer, it should return a pointer to that buffer.

If your string function does not use the supplied buffer (for example,
if it needs to return a string longer than 255 characters), you must
allocate the space for your own buffer with 'malloc()' in your
'xxx_init()' function or your 'xxx()' function and free it in your
'xxx_deinit()' function.  You can store the allocated memory in the
'ptr' slot in the 'UDF_INIT' structure for reuse by future 'xxx()'
calls.  See udf-calling.

To indicate a return value of 'NULL' in the main function, set
'*is_null' to '1':

     *is_null = 1;

To indicate an error return in the main function, set '*error' to '1':

     *error = 1;

If 'xxx()' sets '*error' to '1' for any row, the function value is
'NULL' for the current row and for any subsequent rows processed by the
statement in which 'XXX()' was invoked.  ('xxx()' is not even called for
subsequent rows.)

28.4.2.5 UDF Compiling and Installing
.....................................

Files implementing UDFs must be compiled and installed on the host where
the server runs.  This process is described below for the example UDF
file 'sql/udf_example.cc' that is included in MySQL source
distributions.

If a UDF will be referred to in statements that will be replicated to
slave servers, you must ensure that every slave also has the function
available.  Otherwise, replication will fail on the slaves when they
attempt to invoke the function.

The immediately following instructions are for Unix.  Instructions for
Windows are given later in this section.

The 'udf_example.cc' file contains the following functions:

   * 'metaphon()' returns a metaphon string of the string argument.
     This is something like a soundex string, but it is more tuned for
     English.

   * 'myfunc_double()' returns the sum of the ASCII values of the
     characters in its arguments, divided by the sum of the length of
     its arguments.

   * 'myfunc_int()' returns the sum of the length of its arguments.

   * 'sequence([const int])' returns a sequence starting from the given
     number or 1 if no number has been given.

   * 'lookup()' returns the IP address for a host name.

   * 'reverse_lookup()' returns the host name for an IP address.  The
     function may be called either with a single string argument of the
     form ''xxx.xxx.xxx.xxx'' or with four numbers.

   * 'avgcost()' returns an average cost.  This is an aggregate
     function.

A dynamically loadable file should be compiled as a sharable library
file, using a command something like this:

     shell> gcc -shared -o udf_example.so udf_example.cc

If you are using 'gcc' with 'CMake' (which is how MySQL is configured),
you should be able to create 'udf_example.so' with a simpler command:

     shell> make udf_example

After you compile a shared object containing UDFs, you must install it
and tell MySQL about it.  Compiling a shared object from
'udf_example.cc' using 'gcc' directly produces a file named
'udf_example.so'.  Copy the shared object to the server's plugin
directory and name it 'udf_example.so'.  This directory is given by the
value of the 'plugin_dir' system variable.

On some systems, the 'ldconfig' program that configures the dynamic
linker does not recognize a shared object unless its name begins with
'lib'.  In this case you should rename a file such as 'udf_example.so'
to 'libudf_example.so'.

On Windows, you can compile user-defined functions by using the
following procedure:

  1. Obtain a MySQL source distribution.  See getting-mysql.

  2. Obtain the 'CMake' build utility, if necessary, from
     <http://www.cmake.org>.  (Version 2.6 or later is required).

  3. In the source tree, look in the 'sql' directory.  There are files
     named 'udf_example.def' 'udf_example.cc' there.  Copy both files
     from this directory to your working directory.

  4. Create a 'CMake' 'makefile' ('CMakeLists.txt') with these contents:

          PROJECT(udf_example)

          # Path for MySQL include directory
          INCLUDE_DIRECTORIES("c:/mysql/include")

          ADD_DEFINITIONS("-DHAVE_DLOPEN")
          ADD_LIBRARY(udf_example MODULE udf_example.cc udf_example.def)
          TARGET_LINK_LIBRARIES(udf_example wsock32)

  5. Create the VC project and solution files:

          cmake -G "<Generator>"

     Invoking 'cmake --help' shows you a list of valid Generators.

  6. Create 'udf_example.dll':

          devenv udf_example.sln /build Release

After the shared library file has been installed, notify 'mysqld'
about the new functions with the following statements.  If
library files have a suffix different from '.so' on your system,
substitute the correct suffix throughout (for example, '.dll' on
Windows).

     mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'udf_example.so';
     mysql> CREATE FUNCTION myfunc_double RETURNS REAL SONAME 'udf_example.so';
     mysql> CREATE FUNCTION myfunc_int RETURNS INTEGER SONAME 'udf_example.so';
     mysql> CREATE FUNCTION sequence RETURNS INTEGER SONAME 'udf_example.so';
     mysql> CREATE FUNCTION lookup RETURNS STRING SONAME 'udf_example.so';
     mysql> CREATE FUNCTION reverse_lookup
         ->        RETURNS STRING SONAME 'udf_example.so';
     mysql> CREATE AGGREGATE FUNCTION avgcost
         ->        RETURNS REAL SONAME 'udf_example.so';

Once installed, a function remains installed until it is uninstalled.

To delete functions, use 'DROP FUNCTION'.:

     mysql> DROP FUNCTION metaphon;
     mysql> DROP FUNCTION myfunc_double;
     mysql> DROP FUNCTION myfunc_int;
     mysql> DROP FUNCTION sequence;
     mysql> DROP FUNCTION lookup;
     mysql> DROP FUNCTION reverse_lookup;
     mysql> DROP FUNCTION avgcost;

The 'CREATE FUNCTION' and 'DROP FUNCTION'
statements update the 'func' system table in the 'mysql'
database.  The function's name, type and shared library name are saved
in the table.  You must have the 'INSERT' or 'DELETE' privilege for the
'mysql' database to create or drop functions, respectively.

You should not use 'CREATE FUNCTION' to add a
function that has previously been created.  If you need to reinstall a
function, you should remove it with 'DROP FUNCTION'
and then reinstall it with 'CREATE FUNCTION'.
You would need to do this, for example, if you
recompile a new version of your function, so that 'mysqld'
gets the new version.  Otherwise, the server continues to use
the old version.

An active function is one that has been loaded with 'CREATE FUNCTION'
and not removed with 'DROP FUNCTION'.
All active functions are reloaded each time the server
starts, unless you start 'mysqld' with the
'--skip-grant-tables' option.  In this case, UDF initialization is
skipped and UDFs are unavailable.

28.4.2.6 UDF Security Precautions
.................................

MySQL takes several measures to prevent misuse of user-defined
functions.

UDF library files cannot be placed in arbitrary directories.  They must
be located in the server's plugin directory.  This directory is given by
the value of the 'plugin_dir' system variable.

To use 'CREATE FUNCTION' or 'DROP FUNCTION',
you must have the 'INSERT' or 'DELETE'
privilege, respectively, for the 'mysql' database.  This is necessary
because those statements add and delete rows from the 'mysql.func'
table.

UDFs should have at least one symbol defined in addition to the 'xxx'
symbol that corresponds to the main 'xxx()' function.  These auxiliary
symbols correspond to the 'xxx_init()', 'xxx_deinit()', 'xxx_reset()',
'xxx_clear()', and 'xxx_add()' functions.  'mysqld' also
supports an '--allow-suspicious-udfs' option that controls whether UDFs
that have only an 'xxx' symbol can be loaded.  By default, the option is
off, to prevent attempts at loading functions from shared library files
other than those containing legitimate UDFs.  If you have older UDFs
that contain only the 'xxx' symbol and that cannot be recompiled to
include an auxiliary symbol, it may be necessary to specify the
'--allow-suspicious-udfs' option.  Otherwise, you should avoid enabling
this capability.

28.4.3 Adding a New Native Function
-----------------------------------

To add a new native MySQL function, use the procedure described here,
which requires that you use a source distribution.  You cannot add
native functions to a binary distribution because it is necessary to
modify MySQL source code and compile MySQL from the modified source.  If
you migrate to another version of MySQL (for example, when a new version
is released), you must repeat the procedure with the new version.

If the new native function will be referred to in statements that will
be replicated to slave servers, you must ensure that every slave server
also has the function available.  Otherwise, replication will fail on
the slaves when they attempt to invoke the function.

To add a new native function, follow these steps to modify source files
in the 'sql' directory:

  1. Create a subclass for the function in 'item_create.cc':

        * If the function takes a fixed number of arguments, create a
          subclass of 'Create_func_arg0', 'Create_func_arg1',
          'Create_func_arg2', or 'Create_func_arg3', respectively,
          depending on whether the function takes zero, one, two, or
          three arguments.  For examples, see the 'Create_func_uuid',
          'Create_func_abs', 'Create_func_pow', and 'Create_func_lpad'
          classes.

        * If the function takes a variable number of arguments, create a
          subclass of 'Create_native_func'.  For an example, see
          'Create_func_concat'.

  2. To provide a name by which the function can be referred to in SQL
     statements, register the name in 'item_create.cc' by adding a line
     to this array:

          static Native_func_registry func_array[]

     You can register several names for the same function.  For example,
     see the lines for '"LCASE"' and '"LOWER"', which are aliases for
     'Create_func_lcase'.

  3. In 'item_func.h', declare a class inheriting from 'Item_num_func'
     or 'Item_str_func', depending on whether your function returns a
     number or a string.

  4. In 'item_func.cc', add one of the following declarations, depending
     on whether you are defining a numeric or string function:

          double   Item_func_newname::val()
          longlong Item_func_newname::val_int()
          String  *Item_func_newname::Str(String *str)

     If you inherit your object from any of the standard items (like
     'Item_num_func'), you probably only have to define one of these
     functions and let the parent object take care of the other
     functions.  For example, the 'Item_str_func' class defines a
     'val()' function that executes 'atof()' on the value returned by
     '::str()'.

  5. If the function is nondeterministic, include the following
     statement in the item constructor to indicate that function results
     should not be cached:

          current_thd->lex->safe_to_cache_query=0;

     A function is nondeterministic if, given fixed values for its
     arguments, it can return different results for different
     invocations.

  6. You should probably also define the following object function:

          void Item_func_newname::fix_length_and_dec()

     This function should at least calculate 'max_length' based on the
     given arguments.  'max_length' is the maximum number of characters
     the function may return.  This function should also set 'maybe_null
     = 0' if the main function cannot return a 'NULL' value.  The
     function can check whether any of the function arguments can return
     'NULL' by checking the arguments' 'maybe_null' variable.  Look at
     'Item_func_mod::fix_length_and_dec' for a typical example of how to
     do this.

All functions must be thread-safe.  In other words, do not use any
global or static variables in the functions without protecting them with
mutexes.

If you want to return 'NULL' from '::val()', '::val_int()', or
'::str()', you should set 'null_value' to 1 and return 0.

For '::str()' object functions, there are additional considerations to
be aware of:

   * The 'String *str' argument provides a string buffer that may be
     used to hold the result.  (For more information about the 'String'
     type, take a look at the 'sql_string.h' file.)

   * The '::str()' function should return the string that holds the
     result, or '(char*) 0' if the result is 'NULL'.

   * All current string functions try to avoid allocating any memory
     unless absolutely necessary!

28.5 Debugging and Porting MySQL
================================

This section helps you port MySQL to other operating systems.  Do check
the list of currently supported operating systems first.  See
<http://www.mysql.com/support/supportedplatforms/database.html>.  If you
have created a new port of MySQL, please let us know so that we can list
it here and on our website (<http://www.mysql.com/>), recommending it to
other users.

*Note*:

If you create a new port of MySQL, you are free to copy and distribute
it under the GPL license, but it does not make you a copyright holder of
MySQL.

A working POSIX thread library is needed for the server.

To build MySQL from source, your system must satisfy the tool
requirements listed at source-installation.

*Important*:

If you are trying to build MySQL 5.7 with 'icc' on the IA64 platform,
and need support for NDB Cluster, you should first ensure that you are
using 'icc' version 9.1.043 or later.  (For details, see Bug #21875.)

If you run into problems with a new port, you may have to do some
debugging of MySQL! See debugging-server.

*Note*:

Before you start debugging 'mysqld', first get the test
program 'mysys/thr_lock' to work.  This ensures that your thread
installation has even a remote chance to work!

28.5.1 Debugging a MySQL Server
-------------------------------

If you are using some functionality that is very new in MySQL, you can
try to run 'mysqld' with the '--skip-new' (which disables
all new, potentially unsafe functionality).  See crashing.

If 'mysqld' does not want to start, verify that you have
no 'my.cnf' files that interfere with your setup!  You can check your
'my.cnf' arguments with 'mysqld --print-defaults' and
avoid using them by starting with 'mysqld --no-defaults ...'.

If 'mysqld' starts to eat up CPU or memory or if it
'hangs,' you can use 'mysqladmin processlist status'.
to find out if someone is executing a query that takes a long time.  It
may be a good idea to run 'mysqladmin -i10 processlist status'
in some window if you are experiencing performance problems
or problems when new clients cannot connect.

The command 'mysqladmin debug' dumps some information
about locks in use, used memory and query usage to the MySQL log file.
This may help solve some problems.  This command also provides some
useful information even if you have not compiled MySQL for debugging!

If the problem is that some tables are getting slower and slower you
should try to optimize the table with 'OPTIMIZE TABLE'
or 'myisamchk'.  See
server-administration.  You should also check the slow queries with
'EXPLAIN'.

You should also read the OS-specific section in this manual for problems
that may be unique to your environment.  See
general-installation-issues.

28.5.1.1 Compiling MySQL for Debugging
......................................

If you have some very specific problem, you can always try to debug
MySQL. To do this you must configure MySQL with the '-DWITH_DEBUG=1'
option.  You can check whether MySQL was compiled with debugging by
doing: 'mysqld --help'.  If the '--debug' flag is listed
with the options then you have debugging enabled.  'mysqladmin ver'
also lists the 'mysqld' version as
'mysql ... --debug' in this case.

If 'mysqld' stops crashing when you configure it with the
'-DWITH_DEBUG=1' CMake option, you probably have found a compiler bug or
a timing bug within MySQL. In this case, you can try to add '-g' using
the 'CMAKE_C_FLAGS' and 'CMAKE_CXX_FLAGS' CMake options and not use
'-DWITH_DEBUG=1'.  If 'mysqld' dies, you can at least
attach to it with 'gdb' or use 'gdb' on the core file to find out what
happened.

When you configure MySQL for debugging you automatically enable a lot of
extra safety check functions that monitor the health of 'mysqld'.
If they find something 'unexpected,' an entry is written to
'stderr', which 'mysqld_safe' directs to the error
log!  This also means that if you are having some unexpected problems
with MySQL and are using a source distribution, the first thing you
should do is to configure MySQL for debugging!  (The second thing is to
send mail to a MySQL mailing list and ask for help.  See
mailing-lists.  If you believe that you have found a bug, please use
the instructions at bug-reports.

28.5.1.2 Creating Trace Files
.............................

If the 'mysqld' server does not start or it crashes
easily, you can try to create a trace file to find the problem.

To do this, you must have a 'mysqld' that has been
compiled with debugging support.  You can check this by executing
'mysqld -V'.  If the version number ends with '-debug', it is compiled
with support for trace files.  (On Windows, the debugging server is
named 'mysqld-debug' rather than 'mysqld')

Start the 'mysqld' server with a trace log in
'/tmp/mysqld.trace' on Unix or '\mysqld.trace' on Windows:

     shell> mysqld --debug

On Windows, you should also use the '--standalone' flag to not start
'mysqld' as a service.  In a console window, use this
command:

     C:\> mysqld-debug --debug --standalone

After this, you can use the 'mysql.exe' command-line tool in a second
console window to reproduce the problem.  You can stop the
'mysqld' server with 'mysqladmin shutdown'.

The trace file can become *very large*!  To generate a smaller trace
file, you can use debugging options something like this:

'mysqld --debug=d,info,error,query,general,where,
/tmp/mysqld.trace': mysqld.

This only prints information with the most interesting tags to the trace
file.

If you make a bug report about this, please only send the lines from the
trace file to the appropriate mailing list where something seems to go
wrong!  If you cannot locate the wrong place, you can open a bug report
and upload the trace file to the report, so that a MySQL developer can
take a look at it.  For instructions, see bug-reports.

The trace file is made with the *DBUG* package by Fred Fish.  See
dbug-package.

28.5.1.3 Using WER with PDB to create a Windows crashdump
.........................................................

Program Database files (with suffix 'pdb') are included in the *ZIP
Archive Debug Binaries & Test Suite* distribution of MySQL. These files
provide information for debugging your MySQL installation in the event
of a problem.  This is a separate download from the standard MSI or Zip
file.

*Note*:

As of MySQL 5.7.6, the PDB files are available in a separate file
labeled "ZIP Archive Debug Binaries & Test Suite".

The PDB file contains more detailed information about 'mysqld' and other
tools that enables more detailed trace and dump files to be created.
You can use these with 'WinDbg' or Visual Studio to debug
'mysqld'.

*Note*:

The older _Dr.  Watson_ debugging tool was removed in Microsoft Vista,
with 'WinDbg' being a common alternative.

For more information on PDB files, see Microsoft Knowledge Base Article
121366 (http://support.microsoft.com/kb/121366/).  For more information
on the debugging options available, see Debugging Tools for Windows
(http://www.microsoft.com/whdc/devtools/debugging/default.mspx).

To use WinDbg, either install the full Windows Driver Kit (WDK) or
install the standalone version.

*Important*:

The '.exe' and '.pbd' files must be an exact match (both version number
and MySQL server edition) or WinDBG will complain while attempting to
load the symbols.

  1. To generate a minidump 'mysqld.dmp', enable the 'core-file' option
     under the [mysqld] section in 'my.ini'.  Restart the MySQL server
     after making these changes.

  2. Create a directory to store the generated files, such as
     'c:\symbols'

  3. Determine the path to your 'windbg.exe' executable using the Find
     GUI or from the command line, for example: 'dir /s /b windbg.exe' -
     a common default is _C:\Program Files\Debugging Tools for Windows
     (x64)\windbg.exe_

  4. Launch 'windbg.exe' giving it the paths to 'mysqld-debug.exe',
     'mysqld.pdb', 'mysqld.dmp', and the source code.  Alternatively,
     pass in each path from the WinDbg GUI. For example:

          windbg.exe -i "C:\mysql-5.7.23-winx64\bin\"^
           -z "C:\mysql-5.7.23-winx64\data\mysqld.dmp"^
           -srcpath "E:\ade\mysql_archives\5.7\5.7.23\mysql-5.7.23"^
           -y "C:\mysql-5.7.23-winx64\bin;SRV*c:\symbols*http://msdl.microsoft.com/download/symbols"^
           -v -n -c "!analyze -vvvvv"

     *Note*:

     The '^' character and newline are removed by the Windows command
     line processor, so be sure the spaces remain intact.

28.5.1.4 Debugging mysqld under gdb
...................................

On most systems you can also start 'mysqld' from 'gdb' to
get more information if 'mysqld' crashes.

With some older 'gdb' versions on Linux you must use 'run --one-thread'
if you want to be able to debug 'mysqld' threads.  In
this case, you can only have one thread active at a time.  It is best to
upgrade to 'gdb' 5.1 because thread debugging works much better with
this version!

NPTL threads (the new thread library on Linux) may cause problems while
running 'mysqld' under 'gdb'.  Some symptoms are:

   * 'mysqld' hangs during startup (before it writes
     'ready for connections').

   * 'mysqld' crashes during a 'pthread_mutex_lock()' or
     'pthread_mutex_unlock()' call.

In this case, you should set the following environment variable in the
shell before starting 'gdb':

     LD_ASSUME_KERNEL=2.4.1
     export LD_ASSUME_KERNEL

When running 'mysqld' under 'gdb', you should disable the
stack trace with '--skip-stack-trace' to be able to catch segfaults
within 'gdb'.

Use the '--gdb' option to 'mysqld' to install an
interrupt handler for 'SIGINT' (needed to stop 'mysqld'.
with '^C' to set breakpoints) and disable stack tracing and core file
handling.

It is very hard to debug MySQL under 'gdb' if you do a lot of new
connections the whole time as 'gdb' does not free the memory for old
threads.  You can avoid this problem by starting 'mysqld'.
with 'thread_cache_size' set to a value equal to 'max_connections' + 1.
In most cases just using '--thread_cache_size=5'' helps a lot!

If you want to get a core dump on Linux if 'mysqld' dies
with a SIGSEGV signal, you can start 'mysqld' with the
'--core-file' option.  This core file can be used to make a backtrace
that may help you find out why 'mysqld' died:

     shell> gdb mysqld core
     gdb>   backtrace full
     gdb>   quit

See crashing.

If you are using 'gdb' 4.17.x or above on Linux, you should install a
'.gdb' file, with the following information, in your current directory:

     set print sevenbit off
     handle SIGUSR1 nostop noprint
     handle SIGUSR2 nostop noprint
     handle SIGWAITING nostop noprint
     handle SIGLWP nostop noprint
     handle SIGPIPE nostop
     handle SIGALRM nostop
     handle SIGHUP nostop
     handle SIGTERM nostop noprint

If you have problems debugging threads with 'gdb', you should download
gdb 5.x and try this instead.  The new 'gdb' version has very improved
thread handling!

Here is an example how to debug 'mysqld'.:

     shell> gdb /usr/local/libexec/mysqld
     gdb> run
     ...
     backtrace full # Do this when mysqld crashes

Include the preceding output in a bug report, which you can file using
the instructions in bug-reports.

If 'mysqld' hangs, you can try to use some system tools
like 'strace' or '/usr/proc/bin/pstack' to examine where 'mysqld'
has hung.

     strace /tmp/log libexec/mysqld

If you are using the Perl 'DBI' interface, you can turn on debugging
information by using the 'trace' method or by setting the 'DBI_TRACE'
environment variable.

28.5.1.5 Using a Stack Trace
............................

On some operating systems, the error log contains a stack trace if
'mysqld' dies unexpectedly.  You can use this to find out where
(and maybe why) 'mysqld' died.  See error-log.
To get a stack trace, you must not compile 'mysqld' with
the '-fomit-frame-pointer' option to gcc.  See
compiling-for-debugging.

A stack trace in the error log looks something like this:

     mysqld got signal 11;
     Attempting backtrace. You can use the following information
     to find out where mysqld died. If you see no messages after
     this, something went terribly wrong...

     stack_bottom = 0x41fd0110 thread_stack 0x40000
     mysqld(my_print_stacktrace+0x32)[0x9da402]
     mysqld(handle_segfault+0x28a)[0x6648e9]
     /lib/libpthread.so.0[0x7f1a5af000f0]
     /lib/libc.so.6(strcmp+0x2)[0x7f1a5a10f0f2]
     mysqld(_Z21check_change_passwordP3THDPKcS2_Pcj+0x7c)[0x7412cb]
     mysqld(_ZN16set_var_password5checkEP3THD+0xd0)[0x688354]
     mysqld(_Z17sql_set_variablesP3THDP4ListI12set_var_baseE+0x68)[0x688494]
     mysqld(_Z21mysql_execute_commandP3THD+0x41a0)[0x67a170]
     mysqld(_Z11mysql_parseP3THDPKcjPS2_+0x282)[0x67f0ad]
     mysqld(_Z16dispatch_command19enum_server_commandP3THDPcj+0xbb7[0x67fdf8]
     mysqld(_Z10do_commandP3THD+0x24d)[0x6811b6]
     mysqld(handle_one_connection+0x11c)[0x66e05e]

If resolution of function names for the trace fails, the trace contains
less information:

     mysqld got signal 11;
     Attempting backtrace. You can use the following information
     to find out where mysqld died. If you see no messages after
     this, something went terribly wrong...

     stack_bottom = 0x41fd0110 thread_stack 0x40000
     [0x9da402]
     [0x6648e9]
     [0x7f1a5af000f0]
     [0x7f1a5a10f0f2]
     [0x7412cb]
     [0x688354]
     [0x688494]
     [0x67a170]
     [0x67f0ad]
     [0x67fdf8]
     [0x6811b6]
     [0x66e05e]

In the latter case, you can use the 'resolve_stack_dump'
utility to determine where 'mysqld'.
died by using the following procedure:

  1. Copy the numbers from the stack trace to a file, for example
     'mysqld.stack'.  The numbers should not include the surrounding
     square brackets:

          0x9da402
          0x6648e9
          0x7f1a5af000f0
          0x7f1a5a10f0f2
          0x7412cb
          0x688354
          0x688494
          0x67a170
          0x67f0ad
          0x67fdf8
          0x6811b6
          0x66e05e

  2. Make a symbol file for the 'mysqld' server:

          shell> nm -n libexec/mysqld > /tmp/mysqld.sym

     If 'mysqld' is not linked statically, use the
     following command instead:

          shell> nm -D -n libexec/mysqld > /tmp/mysqld.sym

     If you want to decode C++ symbols, use the '--demangle', if
     available, to 'nm'.  If your version of 'nm' does not have this
     option, you will need to use the 'c++filt' command after the stack
     dump has been produced to demangle the C++ names.

  3. Execute the following command:

          shell> resolve_stack_dump -s /tmp/mysqld.sym -n mysqld.stack

     If you were not able to include demangled C++ names in your symbol
     file, process the 'resolve_stack_dump'.
     output using 'c++filt':

          shell> resolve_stack_dump -s /tmp/mysqld.sym -n mysqld.stack | c++filt

     This prints out where 'mysqld' died.  If that does
     not help you find out why 'mysqld' died, you should
     create a bug report and include the output from the preceding
     command with the bug report.

     However, in most cases it does not help us to have just a stack
     trace to find the reason for the problem.  To be able to locate the
     bug or provide a workaround, in most cases we need to know the
     statement that killed 'mysqld' and preferably a test
     case so that we can repeat the problem!  See bug-reports.

Newer versions of 'glibc' stack trace functions also print the address
as relative to the object.  On 'glibc'-based systems (Linux), the trace
for a crash within a plugin looks something like:

     plugin/auth/auth_test_plugin.so(+0x9a6)[0x7ff4d11c29a6]

To translate the relative address ('+0x9a6') into a file name and line
number, use this command:

     shell> addr2line -fie auth_test_plugin.so 0x9a6
     auth_test_plugin
     mysql-trunk/plugin/auth/test_plugin.c:65

The 'addr2line' utility is part of the 'binutils' package on Linux.

On Solaris, the procedure is similar.  The Solaris 'printstack()'
already prints relative addresses:

     plugin/auth/auth_test_plugin.so:0x1510

To translate, use this command:

     shell> gaddr2line -fie auth_test_plugin.so 0x1510
     mysql-trunk/plugin/auth/test_plugin.c:88

Windows already prints the address, function name and line:

     000007FEF07E10A4 auth_test_plugin.dll!auth_test_plugin()[test_plugin.c:72]

28.5.1.6 Using Server Logs to Find Causes of Errors in mysqld
.............................................................

Note that before starting 'mysqld' with the general query
log enabled, you should check all your tables with 'myisamchk'.
See server-administration.

If 'mysqld' dies or hangs, you should start
'mysqld' with the general query log enabled.  See
query-log.  When 'mysqld' dies again, you can examine
the end of the log file for the query that killed 'mysqld'.

If you use the default general query log file, the log is stored in the
database directory as 'HOST_NAME.log' In most cases it is the last query
in the log file that killed 'mysqld', but if possible you
should verify this by restarting 'mysqld' and executing
the found query from the 'mysql' command-line tools.  If
this works, you should also test all complicated queries that did not
complete.

You can also try the command 'EXPLAIN' on all
'SELECT' statements that takes a long time to ensure that
'mysqld' is using indexes properly.  See explain.

You can find the queries that take a long time to execute by starting
'mysqld' with the slow query log enabled.  See
slow-query-log.

If you find the text 'mysqld restarted' in the error log (normally a
file named 'HOST_NAME.err') you probably have found a query that causes
'mysqld' to fail.  If this happens, you should check all
your tables with 'myisamchk'. (see
server-administration), and test the queries in the MySQL log files to
see whether one fails.  If you find such a query, try first upgrading to
the newest MySQL version.  If this does not help and you cannot find
anything in the 'mysql' mail archive, you should report the bug to a
MySQL mailing list.  The mailing lists are described at
<http://lists.mysql.com/>, which also has links to online list archives.

If you have started 'mysqld' with
'--myisam-recover-options', MySQL automatically checks and tries to
repair 'MyISAM' tables if they are marked as 'not closed properly' or
'crashed'.  If this happens, MySQL writes an entry in the 'hostname.err'
file ''Warning: Checking table ...'' which is followed by 'Warning:
Repairing table' if the table needs to be repaired.  If you get a lot of
these errors, without 'mysqld' having died unexpectedly
just before, then something is wrong and needs to be investigated
further.  See server-options.

When the server detects 'MyISAM' table corruption, it writes additional
information to the error log, such as the name and line number of the
source file, and the list of threads accessing the table.  Example: 'Got
an error from thread_id=1, mi_dynrec.c:368'.  This is useful information
to include in bug reports.

It is not a good sign if 'mysqld' did die unexpectedly,
but in this case, you should not investigate the 'Checking table...'
messages, but instead try to find out why 'mysqld' died.

28.5.1.7 Making a Test Case If You Experience Table Corruption
..............................................................

The following procedure applies to 'MyISAM'
tables.  For information about steps to take when
encountering 'InnoDB' table corruption, see bug-reports.

If you encounter corrupted 'MyISAM' tables
or if 'mysqld' always fails after some update statements,
you can test whether the issue is reproducible by doing the following:

  1. Stop the MySQL daemon with 'mysqladmin shutdown'.

  2. Make a backup of the tables to guard against the very unlikely case
     that the repair does something bad.

  3. Check all tables with 'myisamchk -s database/*.MYI'.
     Repair any corrupted tables with 'myisamchk -r database/TABLE.MYI'.

  4. Make a second backup of the tables.

  5. Remove (or move away) any old log files from the MySQL data
     directory if you need more space.

  6. Start 'mysqld' with the binary log enabled.  If you
     want to find a statement that crashes 'mysqld', you
     should start the server with the general query log enabled as well.
     See query-log, and binary-log.

  7. When you have gotten a crashed table, stop the 'mysqld'
     server.

  8. Restore the backup.

  9. Restart the 'mysqld' server _without_ the binary log
     enabled.

  10. Re-execute the statements with 'mysqlbinlog binary-log-file | mysql'.
     The binary log is saved in the MySQL
     database directory with the name 'hostname-bin.NNNNNN'.

  11. If the tables are corrupted again or you can get 'mysqld'
     to die with the above command, you have found a
     reproducible bug.  FTP the tables and the binary log to our bugs
     database using the instructions given in bug-reports.  If
     you are a support customer, you can use the MySQL Customer Support
     Center (<http://www.mysql.com/support/>) to alert the MySQL team
     about the problem and have it fixed as soon as possible.

28.5.2 Debugging a MySQL Client
-------------------------------

To be able to debug a MySQL client with the integrated debug package,
you should configure MySQL with '-DWITH_DEBUG=1'.  See
source-configuration-options.

Before running a client, you should set the 'MYSQL_DEBUG' environment
variable:

     shell> MYSQL_DEBUG=d:t:O,/tmp/client.trace
     shell> export MYSQL_DEBUG

This causes clients to generate a trace file in '/tmp/client.trace'.

If you have problems with your own client code, you should attempt to
connect to the server and run your query using a client that is known to
work.  Do this by running 'mysql' in debugging mode
(assuming that you have compiled MySQL with debugging on):

     shell> mysql --debug=d:t:O,/tmp/client.trace

This provides useful information in case you mail a bug report.  See
bug-reports.

If your client crashes at some 'legal' looking code, you should check
that your 'mysql.h' include file matches your MySQL library file.  A
very common mistake is to use an old 'mysql.h' file from an old MySQL
installation with new MySQL library.

28.5.3 The DBUG Package
-----------------------

The MySQL server and most MySQL clients are compiled with the DBUG
package originally created by Fred Fish.  When you have configured MySQL
for debugging, this package makes it possible to get a trace file of
what the program is doing.  See making-trace-files.

This section summarizes the argument values that you can specify in
debug options on the command line for MySQL programs that have been
built with debugging support.  For more information about programming
with the DBUG package, see the DBUG manual in the 'dbug' directory of
MySQL source distributions.  It's best to use a recent distribution to
get the most updated DBUG manual.

The DBUG package can be used by invoking a program with the
'--debug[=DEBUG_OPTIONS]' or '-# [DEBUG_OPTIONS]' option.  If you
specify the '--debug' or '-#' option without a DEBUG_OPTIONS value, most
MySQL programs use a default value.  The server default is
'd:t:i:o,/tmp/mysqld.trace' on Unix and 'd:t:i:O,\mysqld.trace' on
Windows.  The effect of this default is:

   * 'd': Enable output for all debug macros

   * 't': Trace function calls and exits

   * 'i': Add PID to output lines

   * 'o,/tmp/mysqld.trace', 'O,\mysqld.trace': Set the debug output
     file.

Most client programs use a default DEBUG_OPTIONS value of
'd:t:o,/tmp/PROGRAM_NAME.trace', regardless of platform.

Here are some example debug control strings as they might be specified
on a shell command line:

     --debug=d:t
     --debug=d:f,main,subr1:F:L:t,20
     --debug=d,input,output,files:n
     --debug=d:t:i:O,\\mysqld.trace

For 'mysqld', it is also possible to change DBUG settings
at runtime by setting the 'debug' system variable.  This variable has
global and session values:

     mysql> SET GLOBAL debug = 'DEBUG_OPTIONS';
     mysql> SET SESSION debug = 'DEBUG_OPTIONS';

Changes at runtime require the 'SUPER' privilege, even for the session
value.

The DEBUG_OPTIONS value is a sequence of colon-separated fields:

     field_1:field_2:...:field_N

Each field within the value consists of a mandatory flag character,
optionally preceded by a '+' or '-' character, and optionally followed
by a comma-delimited list of modifiers:

     [+|-]flag[,modifier,modifier,...,modifier]

The following table describes the permitted flag characters.
Unrecognized flag characters are silently ignored.

Flag                                                       Description

'd'                                                        Enable output from DBUG_XXX macros for the current state.  May
                                                           be followed by a list of keywords, which enables output only for
                                                           the DBUG macros with that keyword.  An empty list of keywords
                                                           enables output for all macros.

                                                           In MySQL, common debug macro keywords to enable are 'enter',
                                                           'exit', 'error', 'warning', 'info', and 'loop'.

'D'                                                        Delay after each debugger output line.  The argument is the
                                                           delay, in tenths of seconds, subject to machine capabilities.
                                                           For example, 'D,20' specifies a delay of two seconds.

'f'                                                        Limit debugging, tracing, and profiling to the list of named
                                                           functions.  An empty list enables all functions.  The
                                                           appropriate 'd' or 't' flags must still be given; this flag only
                                                           limits their actions if they are enabled.

'F'                                                        Identify the source file name for each line of debug or trace
                                                           output.

'i'                                                        Identify the process with the PID or thread ID for each line of
                                                           debug or trace output.

'L'                                                        Identify the source file line number for each line of debug or
                                                           trace output.

'n'                                                        Print the current function nesting depth for each line of debug
                                                           or trace output.

'N'                                                        Number each line of debug output.

'o'                                                        Redirect the debugger output stream to the specified file.  The
                                                           default output is 'stderr'.

'O'                                                        Like 'o', but the file is really flushed between each write.
                                                           When needed, the file is closed and reopened between each write.

'p'                                                        Limit debugger actions to specified processes.  A process must
                                                           be identified with the 'DBUG_PROCESS' macro and match one in the
                                                           list for debugger actions to occur.

'P'                                                        Print the current process name for each line of debug or trace
                                                           output.

'r'                                                        When pushing a new state, do not inherit the previous state's
                                                           function nesting level.  Useful when the output is to start at
                                                           the left margin.

'S'                                                        Do function '_sanity(_file_,_line_)' at each debugged function
                                                           until '_sanity()' returns something that differs from 0.

't'                                                        Enable function call/exit trace lines.  May be followed by a
                                                           list (containing only one modifier) giving a numeric maximum
                                                           trace level, beyond which no output occurs for either debugging
                                                           or tracing macros.  The default is a compile time option.

The leading '+' or '-' character and trailing list of modifiers are used
for flag characters such as 'd' or 'f' that can enable a debug operation
for all applicable modifiers or just some of them:

   * With no leading '+' or '-', the flag value is set to exactly the
     modifier list as given.

   * With a leading '+' or '-', the modifiers in the list are added to
     or subtracted from the current modifier list.

The following examples show how this works for the 'd' flag.  An empty
'd' list enabled output for all debug macros.  A nonempty list enables
output only for the macro keywords in the list.

These statements set the 'd' value to the modifier list as given:

     mysql> SET debug = 'd';
     mysql> SELECT @@debug;
     +---------+
     | @@debug |
     +---------+
     | d       |
     +---------+
     mysql> SET debug = 'd,error,warning';
     mysql> SELECT @@debug;
     +-----------------+
     | @@debug         |
     +-----------------+
     | d,error,warning |
     +-----------------+

A leading '+' or '-' adds to or subtracts from the current 'd' value:

     mysql> SET debug = '+d,loop';
     mysql> SELECT @@debug;
     +----------------------+
     | @@debug              |
     +----------------------+
     | d,error,warning,loop |
     +----------------------+
     mysql> SET debug = '-d,error,loop';
     mysql> SELECT @@debug;
     +-----------+
     | @@debug   |
     +-----------+
     | d,warning |
     +-----------+

Adding to 'all macros enabled' results in no change:

     mysql> SET debug = 'd';
     mysql> SELECT @@debug;
     +---------+
     | @@debug |
     +---------+
     | d       |
     +---------+
     mysql> SET debug = '+d,loop';
     mysql> SELECT @@debug;
     +---------+
     | @@debug |
     +---------+
     | d       |
     +---------+

Disabling all enabled macros disables the 'd' flag entirely:

     mysql> SET debug = 'd,error,loop';
     mysql> SELECT @@debug;
     +--------------+
     | @@debug      |
     +--------------+
     | d,error,loop |
     +--------------+
     mysql> SET debug = '-d,error,loop';
     mysql> SELECT @@debug;
     +---------+
     | @@debug |
     +---------+
     |         |
     +---------+

*Note*:

Prior to MySQL 5.7.2, the '+' and '-' modifiers were not always handled
correctly and could leave a flag value in an incorrect state.  Verify
your 'debug'-setting sequence in advance or set it without using '+' or
'-'.

29 MySQL Enterprise Edition
***************************

MySQL Enterprise Edition is a commercial product.  Like MySQL Community
Edition, MySQL Enterprise Edition includes MySQL Server, a fully
integrated transaction-safe, ACID-compliant database with full commit,
rollback, crash-recovery, and row-level locking capabilities.  In
addition, MySQL Enterprise Edition includes the following components
designed to provide monitoring and online backup, as well as improved
security and scalability:

The following sections briefly discuss each of these components and
indicate where to find more detailed information.  To learn more about
commercial products, see <http://www.mysql.com/products/>.

   * MySQL Enterprise Monitor.

   * MySQL Enterprise Backup.

   * MySQL Enterprise Security.

   * MySQL Enterprise Encryption.

   * MySQL Enterprise Audit.

   * MySQL Enterprise Firewall.

   * MySQL Enterprise Thread Pool.

29.1 MySQL Enterprise Monitor Overview
======================================

MySQL Enterprise Monitor is an enterprise monitoring system for MySQL
that keeps an eye on your MySQL servers, notifies you of potential
issues and problems, and advises you how to fix the issues.  MySQL
Enterprise Monitor can monitor all kinds of configurations, from a
single MySQL server that is important to your business, all the way up
to a huge farm of MySQL servers powering a busy website.

The following discussion briefly summarizes the basic components that
make up the MySQL Enterprise Monitor product.  For more information, see
the MySQL Enterprise Monitor manual, available at
<http://dev.mysql.com/doc/mysql-monitor/en/>.

MySQL Enterprise Monitor components can be installed in various
configurations depending on your database and network topology, to give
you the best combination of reliable and responsive monitoring data,
with minimal overhead on the database server machines.  A typical MySQL
Enterprise Monitor installation consists of:

   * One or more MySQL servers to monitor.  MySQL Enterprise Monitor can
     monitor both Community and Enterprise MySQL server releases.

   * A MySQL Enterprise Monitor Agent for each monitored host.

   * A single MySQL Enterprise Service Manager, which collates
     information from the agents and provides the user interface to the
     collected data.

MySQL Enterprise Monitor is designed to monitor one or more MySQL
servers.  The monitoring information is collected by using an agent,
_MySQL Enterprise Monitor Agent_.  The agent communicates with the hosts
and MySQL servers that it monitors, collecting variables, status and
health information, and sending this information to the MySQL Enterprise
Service Manager.

The information collected by the agent about each MySQL server and host
you are monitoring is sent to the _MySQL Enterprise Service Manager_.
This server collates all of the information from the agents.  As it
collates the information sent by the agents, the MySQL Enterprise
Service Manager continually tests the collected data, comparing the
status of the server to reasonable values.  When thresholds are reached,
the server can trigger an event (including an alarm and notification) to
highlight a potential issue, such as low memory, high CPU usage, or more
complex conditions such insufficient buffer sizes and status
information.  We call each test, with its associated threshold value, a
_rule_.

These rules, and the alarms and notifications, are each known as a
_MySQL Enterprise Advisors_.  Advisors form a critical part of the MySQL
Enterprise Service Manager, as they provide warning information and
troubleshooting advice about potential problems.

The MySQL Enterprise Service Manager includes a web server, and you
interact with it through any web browser.  This interface, the MySQL
Enterprise Monitor User Interface, displays all of the information
collected by the agents, and lets you view all of your servers and their
current status as a group or individually.  You control and configure
all aspects of the service using the MySQL Enterprise Monitor User
Interface.

The information supplied by the MySQL Enterprise Monitor Agent processes
also includes statistical and query information, which you can view in
the form of graphs.  For example, you can view aspects such as server
load, query numbers, or index usage information as a graph over time.
The graph lets you pinpoint problems or potential issues on your server,
and can help diagnose the impact from database or external problems
(such as external system or network failure) by examining the data from
a specific time interval.

The MySQL Enterprise Monitor Agent can also be configured to collect
detailed information about the queries executed on your server,
including the row counts and performance times for executing each query.
You can correlate the detailed query data with the graphical information
to identify which queries were executing when you experienced a
particularly high load, index or other issue.  The query data is
supported by a system called Query Analyzer, and the data can be
presented in different ways depending on your needs.

29.2 MySQL Enterprise Backup Overview
=====================================

MySQL Enterprise Backup performs hot backup operations for MySQL
databases.  The product is architected for efficient and reliable
backups of tables created by the InnoDB storage engine.  For
completeness, it can also back up tables from MyISAM and other storage
engines.

The following discussion briefly summarizes MySQL Enterprise Backup.
For more information, see the MySQL Enterprise Backup manual, available
at <http://dev.mysql.com/doc/mysql-enterprise-backup/en/>.

Hot backups are performed while the database is running and applications
are reading and writing to it.  This type of backup does not block
normal database operations, and it captures even changes that occur
while the backup is happening.  For these reasons, hot backups are
desirable when your database 'grows up' - when the data is large enough
that the backup takes significant time, and when your data is important
enough to your business that you must capture every last change, without
taking your application, website, or web service offline.

MySQL Enterprise Backup does a hot backup of all tables that use the
InnoDB storage engine.  For tables using MyISAM or other non-InnoDB
storage engines, it does a 'warm' backup, where the database continues
to run, but those tables cannot be modified while being backed up.  For
efficient backup operations, you can designate InnoDB as the default
storage engine for new tables, or convert existing tables to use the
InnoDB storage engine.

29.3 MySQL Enterprise Security Overview
=======================================

MySQL Enterprise Edition provides plugins that implement authentication
using external services:

   * MySQL Enterprise Edition includes an authentication plugin that
     enables MySQL Server to use PAM (Pluggable Authentication Modules)
     to authenticate MySQL users.  PAM enables a system to use a
     standard interface to access various kinds of authentication
     methods, such as Unix passwords or an LDAP directory.  For more
     information, see pam-pluggable-authentication.

   * MySQL Enterprise Edition includes an authentication plugin that
     performs external authentication on Windows, enabling MySQL Server
     to use native Windows services to authenticate client connections.
     Users who have logged in to Windows can connect from MySQL client
     programs to the server based on the information in their
     environment without specifying an additional password.  For more
     information, see windows-pluggable-authentication.

   * MySQL Enterprise Edition includes a keyring plugin that uses Oracle
     Key Vault as a back end for keyring storage.  For more information,
     see keyring.

For other related Enterprise security features, see
mysql-enterprise-encryption.

29.4 MySQL Enterprise Encryption Overview
=========================================

MySQL Enterprise Edition includes a set of encryption functions based on
the OpenSSL library that expose OpenSSL capabilities at the SQL level.
These functions enable Enterprise applications to perform the following
operations:

   * Implement added data protection using public-key asymmetric
     cryptography

   * Create public and private keys and digital signatures

   * Perform asymmetric encryption and decryption

   * Use cryptographic hashing for digital signing and data verification
     and validation

For more information, see enterprise-encryption.

For other related Enterprise security features, see
mysql-enterprise-security.

29.5 MySQL Enterprise Audit Overview
====================================

MySQL Enterprise Edition includes MySQL Enterprise Audit, implemented
using a server plugin.  MySQL Enterprise Audit uses the open MySQL Audit
API to enable standard, policy-based monitoring and logging of
connection and query activity executed on specific MySQL servers.
Designed to meet the Oracle audit specification, MySQL Enterprise Audit
provides an out of box, easy to use auditing and compliance solution for
applications that are governed by both internal and external regulatory
guidelines.

When installed, the audit plugin enables MySQL Server to produce a log
file containing an audit record of server activity.  The log contents
include when clients connect and disconnect, and what actions they
perform while connected, such as which databases and tables they access.

For more information, see audit-log.

29.6 MySQL Enterprise Firewall Overview
=======================================

MySQL Enterprise Edition includes MySQL Enterprise Firewall, an
application-level firewall that enables database administrators to
permit or deny SQL statement execution based on matching against
whitelists of accepted statement patterns.  This helps harden MySQL
Server against attacks such as SQL injection or attempts to exploit
applications by using them outside of their legitimate query workload
characteristics.

Each MySQL account registered with the firewall has its own statement
whitelist, enabling protection to be tailored per account.  For a given
account, the firewall can operate in recording or protecting mode, for
training in the accepted statement patterns or protection against
unacceptable statements.

For more information, see firewall.

29.7 MySQL Enterprise Thread Pool Overview
==========================================

MySQL Enterprise Edition includes MySQL Enterprise Thread Pool,
implemented using a server plugin.  The default thread-handling model in
MySQL Server executes statements using one thread per client connection.
As more clients connect to the server and execute statements, overall
performance degrades.  In MySQL Enterprise Edition, a thread pool plugin
provides an alternative thread-handling model designed to reduce
overhead and improve performance.  The plugin implements a thread pool
that increases server performance by efficiently managing statement
execution threads for large numbers of client connections.

For more information, see thread-pool.

30 MySQL Workbench
******************

MySQL Workbench provides a graphical tool for working with MySQL servers
and databases.  MySQL Workbench fully supports MySQL versions 5.1 and
above.

The following discussion briefly describes MySQL Workbench capabilities.
For more information, see the MySQL Workbench manual, available at
<http://dev.mysql.com/doc/workbench/en/>.

MySQL Workbench provides five main areas of functionality:

   * *SQL Development*: Enables you to create and manage connections to
     database servers.  As well as enabling you to configure connection
     parameters, MySQL Workbench provides the capability to execute SQL
     queries on the database connections using the built-in SQL Editor.
     This functionality replaces that previously provided by the Query
     Browser standalone application.

   * *Data Modeling*: Enables you to create models of your database
     schema graphically, reverse and forward engineer between a schema
     and a live database, and edit all aspects of your database using
     the comprehensive Table Editor.  The Table Editor provides
     easy-to-use facilities for editing Tables, Columns, Indexes,
     Triggers, Partitioning, Options, Inserts and Privileges, Routines
     and Views.

   * *Server Administration*: Enables you to create and administer
     server instances.

   * *Data Migration*: Allows you to migrate from Microsoft SQL Server,
     Sybase ASE, SQLite, SQL Anywhere, PostreSQL, and other RDBMS
     tables, objects and data to MySQL. Migration also supports
     migrating from earlier versions of MySQL to the latest releases.

   * *MySQL Enterprise Support*: Support for Enterprise products such as
     MySQL Enterprise Backup and MySQL Audit.

MySQL Workbench is available in two editions, the Community Edition and
the Commercial Edition.  The Community Edition is available free of
charge.  The Commercial Edition provides additional Enterprise features,
such as database documentation generation, at low cost.

Appendix A MySQL 5.7 Frequently Asked Questions
***********************************************

A.1 MySQL 5.7 FAQ: General
==========================

Which version of MySQL is production-ready (GA)?

MySQL 5.7 and MySQL 5.6 are supported for production use.

MySQL 5.7 achieved General Availability (GA) status with MySQL 5.7.9,
which was released for production use on 21 October 2015.

MySQL 5.6 achieved General Availability (GA) status with MySQL 5.6.10,
which was released for production use on 5 February 2013.

MySQL 5.5 achieved General Availability (GA) status with MySQL 5.5.8,
which was released for production use on 3 December 2010.  The MySQL 5.5
series is no longer current, but still supported in production.

MySQL 5.1 achieved General Availability (GA) status with MySQL 5.1.30,
which was released for production use on 14 November 2008.  Active
development for MySQL 5.1 has ended.

MySQL 5.0 achieved General Availability (GA) status with MySQL 5.0.15,
which was released for production use on 19 October 2005.  Active
development for MySQL 5.0 has ended.

What is the state of development (non-GA) versions?

MySQL follows a milestone release model that introduces
pre-production-quality features and stabilizes them to release quality
(see <http://dev.mysql.com/doc/mysql-development-cycle/en/index.html>).
This process then repeats, so releases cycle between pre-production and
release quality status.  Please check the change logs to identify the
status of a given release.

MySQL 8.0, a successor to MySQL 5.7, is being actively developed using
the milestone release methodology described above.

Can MySQL 5.7 do subqueries?

Yes.  See subqueries.

Can MySQL 5.7 perform multiple-table inserts, updates, and deletes?

Yes.  For the syntax required to perform multiple-table updates, see
update; for that required to perform multiple-table deletes, see
delete.

A multiple-table insert can be accomplished using a trigger whose 'FOR
EACH ROW' clause contains multiple 'INSERT' statements
within a 'BEGIN ... END' block.  See triggers.

Does MySQL 5.7 have a Query Cache?  Does it work on Server, Instance or
Database?

Yes.  (However, the query cache is deprecated as of MySQL 5.7.20, and is
removed in MySQL 8.0.)  The query cache operates on the server level,
caching complete result sets matched with the original query string.  If
an exactly identical query is made (which often happens, particularly in
web applications), no parsing or execution is necessary; the result is
sent directly from the cache.  Various tuning options are available.
See query-cache.

Does MySQL 5.7 have Sequences?

No.  However, MySQL has an 'AUTO_INCREMENT' system, which in MySQL 5.7
can also handle inserts in a multi-master replication setup.  With the
'auto_increment_increment' and 'auto_increment_offset' system variables,
you can set each server to generate auto-increment values that don't
conflict with other servers.  The 'auto_increment_increment' value
should be greater than the number of servers, and each server should
have a unique offset.

Does MySQL 5.7 have a 'NOW()' function with fractions of seconds?

Yes, see fractional-seconds.

Does MySQL 5.7 work with multi-core processors?

Yes.  MySQL is fully multi-threaded, and will make use of multiple CPUs,
provided that the operating system supports them.

Why do I see multiple processes for 'mysqld'?

When using LinuxThreads, you should see a minimum of three
'mysqld' processes running.  These are in fact threads.  There
is one thread for the LinuxThreads manager, one thread to handle
connections, and one thread to handle alarms and signals.

Can MySQL 5.7 perform ACID transactions?

Yes.  All current MySQL versions support transactions.  The 'InnoDB'
storage engine offers full ACID transactions with row-level locking,
multi-versioning, nonlocking repeatable reads, and all four SQL standard
isolation levels.

The 'NDB' storage engine supports the 'READ
COMMITTED' transaction isolation level only.

A.2 MySQL 5.7 FAQ: Storage Engines
==================================

Where can I obtain complete documentation for MySQL storage engines?

See storage-engines.  That chapter contains information about
all MySQL storage engines except for the 'InnoDB'
storage engine and the 'NDB'
storage engine (used for MySQL Cluster).  'InnoDB'
is covered in innodb-storage-engine.
'NDB' is covered in mysql-cluster.

Are there any new storage engines in MySQL 5.7?

No.  'InnoDB' is the default storage engine for new tables.  See
innodb-introduction for details.

Have any storage engines been removed in MySQL 5.7?

No.

Can I prevent the use of a particular storage engine?

Yes.  The 'disabled_storage_engines' configuration option defines which
storage engines cannot be used to create tables or tablespaces.  By
default, 'disabled_storage_engines' is empty (no engines disabled), but
it can be set to a comma-separated list of one or more engines.

Is there an advantage to using the 'InnoDB' storage engine exclusively,
as opposed to a combination of 'InnoDB' and non-'InnoDB' storage
engines?

Yes.  Using 'InnoDB' tables exclusively can simplify backup and recovery
operations.  MySQL Enterprise Backup does a hot backup of all tables
that use the 'InnoDB' storage engine.  For tables using 'MyISAM' or
other non-'InnoDB' storage engines, it does a 'warm' backup, where the
database continues to run, but those tables cannot be modified while
being backed up.  See mysql-enterprise-backup.

What are the unique benefits of the 'ARCHIVE' storage engine?

The 'ARCHIVE' storage engine stores large amounts of data without
indexes; it has a small footprint, and performs selects using table
scans.  See archive-storage-engine, for details.

A.3 MySQL 5.7 FAQ: Server SQL Mode
==================================

What are server SQL modes?

Server SQL modes define what SQL syntax MySQL should support and what
kind of data validation checks it should perform.  This makes it easier
to use MySQL in different environments and to use MySQL together with
other database servers.  The MySQL Server apply these modes individually
to different clients.  For more information, see sql-mode.

How many server SQL modes are there?

Each mode can be independently switched on and off.  See
sql-mode, for a complete list of available modes.

How do you determine the server SQL mode?

You can set the default SQL mode (for 'mysqld' startup)
with the '--sql-mode' option.  Using the statement 'SET [GLOBAL|SESSION] sql_mode='MODES'',
you can change the
settings from within a connection, either locally to the connection, or
to take effect globally.  You can retrieve the current mode by issuing a
'SELECT @@sql_mode' statement.

Is the mode dependent on the database or connection?

A mode is not linked to a particular database.  Modes can be set locally
to the session (connection), or globally for the server.  you can change
these settings using 'SET [GLOBAL|SESSION] sql_mode='MODES''.

Can the rules for strict mode be extended?

When we refer to _strict mode_, we mean a mode where at least one of the
modes 'TRADITIONAL', 'STRICT_TRANS_TABLES', or 'STRICT_ALL_TABLES' is
enabled.  Options can be combined, so you can add restrictions to a
mode.  See sql-mode, for more information.

Does strict mode impact performance?

The intensive validation of input data that some settings requires more
time than if the validation is not done.  While the performance impact
is not that great, if you do not require such validation (perhaps your
application already handles all of this), then MySQL gives you the
option of leaving strict mode disabled.  However, if you do require it,
strict mode can provide such validation.

What is the default server SQL mode when MySQL 5.7 is installed?

The default SQL mode in MySQL 5.7 includes these modes:
'ONLY_FULL_GROUP_BY', 'STRICT_TRANS_TABLES', 'NO_ZERO_IN_DATE',
'NO_ZERO_DATE', 'ERROR_FOR_DIVISION_BY_ZERO', 'NO_AUTO_CREATE_USER', and
'NO_ENGINE_SUBSTITUTION'.

For information about all available modes and default MySQL behavior,
see sql-mode.

A.4 MySQL 5.7 FAQ: Stored Procedures and Functions
==================================================

Does MySQL 5.7 support stored procedures and functions?

Yes.  MySQL 5.7 supports two types of stored routines, stored procedures
and stored functions.

Where can I find documentation for MySQL stored procedures and stored
functions?

See stored-routines.

Is there a discussion forum for MySQL stored procedures?

Yes.  See http://forums.mysql.com/list.php?98
(http://forums.mysql.com/list.php?98).

Where can I find the ANSI SQL 2003 specification for stored procedures?

Unfortunately, the official specifications are not freely available
(ANSI makes them available for purchase).  However, there are books,
such as 'SQL-99 Complete, Really' by Peter Gulutzan and Trudy Pelzer,
that provide a comprehensive overview of the standard, including
coverage of stored procedures.

How do you manage stored routines?

It is always good practice to use a clear naming scheme for your stored
routines.  You can manage stored procedures with 'CREATE
[FUNCTION|PROCEDURE]', 'ALTER [FUNCTION|PROCEDURE]', 'DROP
[FUNCTION|PROCEDURE]', and 'SHOW CREATE [FUNCTION|PROCEDURE]'.  You can
obtain information about existing stored procedures using the
'ROUTINES' table in the 'INFORMATION_SCHEMA' database
(see routines-table).

Is there a way to view all stored procedures and stored functions in a
given database?

Yes.  For a database named DBNAME, use this query on the
'INFORMATION_SCHEMA.ROUTINES' table:

     SELECT ROUTINE_TYPE, ROUTINE_NAME
         FROM INFORMATION_SCHEMA.ROUTINES
         WHERE ROUTINE_SCHEMA='DBNAME';

For more information, see routines-table.

The body of a stored routine can be viewed using 'SHOW CREATE FUNCTION'.
(for a stored function) or 'SHOW CREATE PROCEDURE'.
(for a stored procedure).  See
show-create-procedure, for more information.

Where are stored procedures stored?

In the 'proc' table of the 'mysql' system database.  However, you should
not access the tables in the system database directly.  Instead, query
the 'INFORMATION_SCHEMA' 'ROUTINES' and
'PARAMETERS' tables.  See routines-table, and
parameters-table.

You can also use 'SHOW CREATE FUNCTION' to
obtain information about stored functions, and 'SHOW CREATE PROCEDURE'
to obtain information about stored
procedures.  See show-create-procedure.

Is it possible to group stored procedures or stored functions into
packages?

No.  This is not supported in MySQL 5.7.

Can a stored procedure call another stored procedure?

Yes.

Can a stored procedure call a trigger?

A stored procedure can execute an SQL statement, such as an
'UPDATE', that causes a trigger to activate.

Can a stored procedure access tables?

Yes.  A stored procedure can access one or more tables as required.

Do stored procedures have a statement for raising application errors?

Yes.  MySQL 5.7 implements the SQL standard 'SIGNAL' and 'RESIGNAL'
statements.  See condition-handling.

Do stored procedures provide exception handling?

MySQL implements 'HANDLER' definitions according to the
SQL standard.  See declare-handler, for details.

Can MySQL 5.7 stored routines return result sets?

_Stored procedures_ can, but stored functions cannot.  If you perform an
ordinary 'SELECT' inside a stored procedure, the result
set is returned directly to the client.  You need to use the MySQL 4.1
(or higher) client/server protocol for this to work.  This means that,
for example, in PHP, you need to use the 'mysqli' extension rather than
the old 'mysql' extension.

Is 'WITH RECOMPILE' supported for stored procedures?

Not in MySQL 5.7.

Is there a MySQL equivalent to using 'mod_plsql' as a gateway on Apache
to talk directly to a stored procedure in the database?

There is no equivalent in MySQL 5.7.

Can I pass an array as input to a stored procedure?

Not in MySQL 5.7.

Can I pass a cursor as an 'IN' parameter to a stored procedure?

In MySQL 5.7, cursors are available inside stored procedures only.

Can I return a cursor as an 'OUT' parameter from a stored procedure?

In MySQL 5.7, cursors are available inside stored procedures only.
However, if you do not open a cursor on a 'SELECT', the
result will be sent directly to the client.  You can also 'SELECT INTO'
variables.  See select.

Can I print out a variable's value within a stored routine for debugging
purposes?

Yes, you can do this in a _stored procedure_, but not in a stored
function.  If you perform an ordinary 'SELECT' inside a
stored procedure, the result set is returned directly to the client.
You will need to use the MySQL 4.1 (or above) client/server protocol for
this to work.  This means that, for example, in PHP, you need to use the
'mysqli' extension rather than the old 'mysql' extension.

Can I commit or roll back transactions inside a stored procedure?

Yes.  However, you cannot perform transactional operations within a
stored function.

Do MySQL 5.7 stored procedures and functions work with replication?

Yes, standard actions carried out in stored procedures and functions are
replicated from a master MySQL server to a slave server.  There are a
few limitations that are described in detail in
stored-programs-logging.

Are stored procedures and functions created on a master server
replicated to a slave?

Yes, creation of stored procedures and functions carried out through
normal DDL statements on a master server are replicated to a slave, so
the objects will exist on both servers.  'ALTER' and 'DROP' statements
for stored procedures and functions are also replicated.

How are actions that take place inside stored procedures and functions
replicated?

MySQL records each DML event that occurs in a stored procedure and
replicates those individual actions to a slave server.  The actual calls
made to execute stored procedures are not replicated.

Stored functions that change data are logged as function invocations,
not as the DML events that occur inside each function.

Are there special security requirements for using stored procedures and
functions together with replication?

Yes.  Because a slave server has authority to execute any statement read
from a master's binary log, special security constraints exist for using
stored functions with replication.  If replication or binary logging in
general (for the purpose of point-in-time recovery) is active, then
MySQL DBAs have two security options open to them:

  1. Any user wishing to create stored functions must be granted the
     'SUPER' privilege.

  2. Alternatively, a DBA can set the 'log_bin_trust_function_creators'
     system variable to 1, which enables anyone with the standard
     'CREATE ROUTINE' privilege to create stored functions.

What limitations exist for replicating stored procedure and function
actions?

Nondeterministic (random) or time-based actions embedded in stored
procedures may not replicate properly.  By their very nature, randomly
produced results are not predictable and cannot be exactly reproduced,
and therefore, random actions replicated to a slave will not mirror
those performed on a master.  Declaring stored functions to be
'DETERMINISTIC' or setting the 'log_bin_trust_function_creators' system
variable to 0 will not allow random-valued operations to be invoked.

In addition, time-based actions cannot be reproduced on a slave because
the timing of such actions in a stored procedure is not reproducible
through the binary log used for replication.  It records only DML events
and does not factor in timing constraints.

Finally, nontransactional tables for which errors occur during large DML
actions (such as bulk inserts) may experience replication issues in that
a master may be partially updated from DML activity, but no updates are
done to the slave because of the errors that occurred.  A workaround is
for a function's DML actions to be carried out with the 'IGNORE' keyword
so that updates on the master that cause errors are ignored and updates
that do not cause errors are replicated to the slave.

Do the preceding limitations affect the ability of MySQL to do
point-in-time recovery?

The same limitations that affect replication do affect point-in-time
recovery.

What is being done to correct the aforementioned limitations?

You can choose either statement-based replication or row-based
replication.  The original replication implementation is based on
statement-based binary logging.  Row-based binary logging resolves the
limitations mentioned earlier.

_Mixed_ replication is also available (by starting the server with
'--binlog-format=mixed').  This hybrid form of replication 'knows'
whether statement-level replication can safely be used, or row-level
replication is required.

For additional information, see replication-formats.

A.5 MySQL 5.7 FAQ: Triggers
===========================

Where can I find the documentation for MySQL 5.7 triggers?

See triggers.

Is there a discussion forum for MySQL Triggers?

Yes.  It is available at <http://forums.mysql.com/list.php?99>.

Does MySQL 5.7 have statement-level or row-level triggers?

In MySQL 5.7, all triggers are 'FOR EACH ROW'; that is, the trigger is
activated for each row that is inserted, updated, or deleted.  MySQL 5.7
does not support triggers using 'FOR EACH STATEMENT'.

Are there any default triggers?

Not explicitly.  MySQL does have specific special behavior for some
'TIMESTAMP' columns, as well as for columns which are
defined using 'AUTO_INCREMENT'.

How are triggers managed in MySQL?

In MySQL 5.7, triggers can be created using the 'CREATE TRIGGER'
statement, and dropped using 'DROP TRIGGER'.
See create-trigger, and drop-trigger, for
more about these statements.

Information about triggers can be obtained by querying the
'INFORMATION_SCHEMA.TRIGGERS' table.  See
triggers-table.

Is there a way to view all triggers in a given database?

Yes.  You can obtain a listing of all triggers defined on database
'dbname' using a query on the 'INFORMATION_SCHEMA.TRIGGERS'
table such as the one shown here:

     SELECT TRIGGER_NAME, EVENT_MANIPULATION, EVENT_OBJECT_TABLE, ACTION_STATEMENT
         FROM INFORMATION_SCHEMA.TRIGGERS
         WHERE TRIGGER_SCHEMA='DBNAME';

For more information about this table, see triggers-table.

You can also use the 'SHOW TRIGGERS' statement,
which is specific to MySQL. See show-triggers.

Where are triggers stored?

Triggers are stored in '.TRG' files, with one such file one per table.

Can a trigger call a stored procedure?

Yes.

Can triggers access tables?

A trigger can access both old and new data in its own table.  A trigger
can also affect other tables, but it is not permitted to modify a table
that is already being used (for reading or writing) by the statement
that invoked the function or trigger.

Can a table have multiple triggers with the same trigger event and
action time?

It is possible to define multiple triggers for a given table that have
the same trigger event and action time.  For example, you can have two
'BEFORE UPDATE' triggers for a table.  By default, triggers that have
the same trigger event and action time activate in the order they were
created.  To affect trigger order, specify a clause after 'FOR EACH ROW'
that indicates 'FOLLOWS' or 'PRECEDES' and the name of an existing
trigger that also has the same trigger event and action time.  With
'FOLLOWS', the new trigger activates after the existing trigger.  With
'PRECEDES', the new trigger activates before the existing trigger.

Can triggers call an external application through a UDF?

Yes.  For example, a trigger could invoke the 'sys_exec()' UDF.

Is it possible for a trigger to update tables on a remote server?

Yes.  A table on a remote server could be updated using the 'FEDERATED'
storage engine.  (See federated-storage-engine).

Do triggers work with replication?

Yes.  However, the way in which they work depends whether you are using
MySQL's 'classic' statement-based or row-based replication format.

When using statement-based replication, triggers on the slave are
executed by statements that are executed on the master (and replicated
to the slave).

When using row-based replication, triggers are not executed on the slave
due to statements that were run on the master and then replicated to the
slave.  Instead, when using row-based replication, the changes caused by
executing the trigger on the master are applied on the slave.

For more information, see replication-features-triggers.

How are actions carried out through triggers on a master replicated to a
slave?

Again, this depends on whether you are using statement-based or
row-based replication.

Statement-based replication

First, the triggers that exist on a master must be re-created on the
slave server.  Once this is done, the replication flow works as any
other standard DML statement that participates in replication.  For
example, consider a table 'EMP' that has an 'AFTER' insert trigger,
which exists on a master MySQL server.  The same 'EMP' table and 'AFTER'
insert trigger exist on the slave server as well.  The replication flow
would be:

  1. An 'INSERT' statement is made to 'EMP'.

  2. The 'AFTER' trigger on 'EMP' activates.

  3. The 'INSERT' statement is written to the binary log.

  4. The replication slave picks up the 'INSERT'.
     statement to 'EMP' and executes it.

  5. The 'AFTER' trigger on 'EMP' that exists on the slave activates.

Row-based replication

When you use row-based replication, the changes caused by executing the
trigger on the master are applied on the slave.  However, the triggers
themselves are not actually executed on the slave under row-based
replication.  This is because, if both the master and the slave applied
the changes from the master and, in addition, the trigger causing these
changes were applied on the slave, the changes would in effect be
applied twice on the slave, leading to different data on the master and
the slave.

In most cases, the outcome is the same for both row-based and
statement-based replication.  However, if you use different triggers on
the master and slave, you cannot use row-based replication.  (This is
because the row-based format replicates the changes made by triggers
executing on the master to the slaves, rather than the statements that
caused the triggers to execute, and the corresponding triggers on the
slave are not executed.)  Instead, any statements causing such triggers
to be executed must be replicated using statement-based replication.

For more information, see replication-features-triggers.

A.6 MySQL 5.7 FAQ: Views
========================

Where can I find documentation covering MySQL Views?

See views.

Is there a discussion forum for MySQL Views?

Yes.  See http://forums.mysql.com/list.php?100
(http://forums.mysql.com/list.php?100)

What happens to a view if an underlying table is dropped or renamed?

After a view has been created, it is possible to drop or alter a table
or view to which the definition refers.  To check a view definition for
problems of this kind, use the 'CHECK TABLE'.
statement.  (See check-table.)

Does MySQL 5.7 have table snapshots?

No.

Does MySQL 5.7 have materialized views?

No.

Can you insert into views that are based on joins?

It is possible, provided that your 'INSERT' statement has
a column list that makes it clear there is only one table involved.

You _cannot_ insert into multiple tables with a single insert on a view.

A.7 MySQL 5.7 FAQ: INFORMATION_SCHEMA
=====================================

Where can I find documentation for the MySQL 'INFORMATION_SCHEMA'
database?

See information-schema

Is there a discussion forum for 'INFORMATION_SCHEMA'?

See http://forums.mysql.com/list.php?101
(http://forums.mysql.com/list.php?101).

Where can I find the ANSI SQL 2003 specification for
'INFORMATION_SCHEMA'?

Unfortunately, the official specifications are not freely available.
(ANSI makes them available for purchase.)  However, there are books
available, such as 'SQL-99 Complete, Really' by Peter Gulutzan and Trudy
Pelzer, that provide a comprehensive overview of the standard, including
'INFORMATION_SCHEMA'.

What is the difference between the Oracle Data Dictionary and MySQL
'INFORMATION_SCHEMA'?

Both Oracle and MySQL provide metadata in tables.  However, Oracle and
MySQL use different table names and column names.  The MySQL
implementation is more similar to those found in DB2 and SQL Server,
which also support 'INFORMATION_SCHEMA' as defined in the SQL standard.

Can I add to or otherwise modify the tables found in the
'INFORMATION_SCHEMA' database?

No.  Since applications may rely on a certain standard structure, this
should not be modified.  For this reason, _we cannot support bugs or
other issues which result from modifying 'INFORMATION_SCHEMA' tables or
data_.

A.8 MySQL 5.7 FAQ: Migration
============================

Where can I find information on how to migrate from MySQL 5.6 to MySQL
5.7?

For detailed upgrade information, see upgrading.  Do not skip a
major version when upgrading, but rather complete the process in steps,
upgrading from one major version to the next in each step.  This may
seem more complicated, but it will you save time and trouble.  If you
encounter problems during the upgrade, their origin will be easier to
identify, either by you or, if you have a MySQL Enterprise subscription,
by MySQL support.

How has storage engine (table type) support changed in MySQL 5.7 from
previous versions?

Storage engine support has changed as follows:

   * Support for 'ISAM' tables was removed in MySQL 5.0 and you should
     now use the 'MyISAM' storage engine in place of 'ISAM'.  To convert
     a table TBLNAME from 'ISAM' to 'MyISAM', simply issue a statement
     such as this one:

          ALTER TABLE TBLNAME ENGINE=MYISAM;

   * Internal 'RAID' for 'MyISAM' tables was also removed in MySQL 5.0.
     This was formerly used to allow large tables in file systems that
     did not support file sizes greater than 2GB. All modern file
     systems allow for larger tables; in addition, there are now other
     solutions such as 'MERGE' tables and views.

   * The 'VARCHAR' column type now retains trailing spaces
     in all storage engines.

   * 'MEMORY' tables (formerly known as 'HEAP' tables) can also contain
     'VARCHAR' columns.

A.9 MySQL 5.7 FAQ: Security
===========================

Where can I find documentation that addresses security issues for MySQL?

The best place to start is security.

Other portions of the MySQL Documentation which you may find useful with
regard to specific security concerns include the following:

   * security-guidelines.

   * security-against-attack.

   * resetting-permissions.

   * changing-mysql-user.

   * udf-security.

   * security-options.

   * load-data-local.

   * postinstallation.

   * encrypted-connections.

Does MySQL 5.7 have native support for SSL?

Most 5.7 binaries have support for SSL connections between the client
and server.  See encrypted-connections.

You can also tunnel a connection using SSH, if (for example) the client
application does not support SSL connections.  For an example, see
windows-and-ssh.

Is SSL support built into MySQL binaries, or must I recompile the binary
myself to enable it?

Most 5.7 binaries have SSL enabled for client/server connections that
are secured, authenticated, or both.  See encrypted-connections.

Does MySQL 5.7 have built-in authentication against LDAP directories?

The Enterprise edition includes a PAM Authentication Plugin
that supports authentication against an
LDAP directory.

Does MySQL 5.7 include support for Roles Based Access Control (RBAC)?

Not at this time.

A.10 MySQL 5.7 FAQ: NDB Cluster
===============================

In the following section, we answer questions that are frequently asked
about NDB Cluster and the 'NDB' storage engine.

Which versions of the MySQL software support NDB Cluster?  Do I have to
compile from source?

NDB Cluster is not supported in standard MySQL Server 5.7 releases.
Instead, MySQL NDB Cluster is provided as a separate product.  Available
NDB Cluster release series include the following:

   * NDB Cluster 7.3

     This series is a General Availability (GA) version of NDB Cluster,
     still available for production, although we recommend that new
     deployments use the latest NDB Cluster 7.5 release.  The most
     recent NDB Cluster 7.3 release can be obtained from
     <http://dev.mysql.com/downloads/cluster/>.

   * NDB Cluster 7.4

     This series is the latest Generally Available (GA) version of NDB
     Cluster, based on version 7.4 of the 'NDB'.
     storage engine and MySQL Server 5.6, and still available for
     production, although we recommend that new deployments use the
     latest NDB Cluster 7.5 release The most recent NDB Cluster 7.4
     release can be obtained from
     <http://dev.mysql.com/downloads/cluster/>.

   * NDB Cluster 7.5

     This series is the most recent General Availability (GA) version of
     NDB Cluster, based on version 7.5 of the 'NDB'
     storage engine and MySQL Server 5.7.  NDB Cluster
     7.5 is available for production use; new deployments intended for
     production should use the latest GA release in this series, which
     is currently NDB Cluster 7.5.11.  The latest NDB Cluster 7.5
     releases can be obtained from
     <http://dev.mysql.com/downloads/cluster/>.

   * NDB Cluster 7.6

     This series, based on version 7.6 of the 'NDB'
     storage engine, is currently under development, but
     not yet considered ready for use in a production setting.  It is
     available as a Developer Preview release for evaluation and testing
     purposes.  You can obtain the most recent NDB Cluster 7.6 release
     from <http://dev.mysql.com/downloads/cluster/>.  For information
     about new features and other important changes in this series, see
     mysql-cluster-what-is-new-7-6.

You should use NDB Cluster 7.5 for any new deployments; if you are using
an older version of NDB Cluster, you should upgrade to this version soon
as possible.  For an overview of improvements made in NDB Cluster 7.5,
see mysql-cluster-what-is-new.  For an overview of improvements
made in NDB Cluster 7.4, see What is New in NDB Cluster 7.4
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-what-is-new-7-4.html);
for information about improvements made in NDB Cluster 7.3, see What is
New in NDB Cluster 7.3
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-what-is-new-7-3.html).

What do 'NDB' and 'NDBCLUSTER' mean?

'NDB' stands for '*N*etwork *D*ata*b*ase'.  'NDB' and 'NDBCLUSTER' are
both names for the storage engine that enables clustering support with
MySQL. 'NDB' is preferred, but either name is correct.

What is the difference between using NDB Cluster versus using MySQL
Replication?

In traditional MySQL replication, a master MySQL server updates one or
more slaves.  Transactions are committed sequentially, and a slow
transaction can cause the slave to lag behind the master.  This means
that if the master fails, it is possible that the slave might not have
recorded the last few transactions.  If a transaction-safe engine such
as 'InnoDB' is being used, a transaction
will either be complete on the slave or not applied at all, but
replication does not guarantee that all data on the master and the slave
will be consistent at all times.  In NDB Cluster, all data nodes are
kept in synchrony, and a transaction committed by any one data node is
committed for all data nodes.  In the event of a data node failure, all
remaining data nodes remain in a consistent state.

In short, whereas standard MySQL replication is _asynchronous_, NDB
Cluster is _synchronous_.

Asynchronous replication is also available in NDB Cluster.  _NDB Cluster
Replication_ (also sometimes known as 'geo-replication') includes the
capability to replicate both between two NDB Clusters, and from an NDB
Cluster to a non-Cluster MySQL server.  See
mysql-cluster-replication.

Do I need any special networking to run NDB Cluster?  How do computers
in a cluster communicate?

NDB Cluster is intended to be used in a high-bandwidth environment, with
computers connecting using TCP/IP. Its performance depends directly upon
the connection speed between the cluster's computers.  The minimum
connectivity requirements for NDB Cluster include a typical 100-megabit
Ethernet network or the equivalent.  We recommend you use gigabit
Ethernet whenever available.

How many computers do I need to run an NDB Cluster, and why?

A minimum of three computers is required to run a viable cluster.
However, the minimum _recommended_ number of computers in an NDB Cluster
is four: one each to run the management and SQL nodes, and two computers
to serve as data nodes.  The purpose of the two data nodes is to provide
redundancy; the management node must run on a separate machine to
guarantee continued arbitration services in the event that one of the
data nodes fails.

To provide increased throughput and high availability, you should use
multiple SQL nodes (MySQL Servers connected to the cluster).  It is also
possible (although not strictly necessary) to run multiple management
servers.

What do the different computers do in an NDB Cluster?

An NDB Cluster has both a physical and logical organization, with
computers being the physical elements.  The logical or functional
elements of a cluster are referred to as _nodes_, and a computer housing
a cluster node is sometimes referred to as a _cluster host_.  There are
three types of nodes, each corresponding to a specific role within the
cluster.  These are:

   * Management node

     This node provides management services for the cluster as a whole,
     including startup, shutdown, backups, and configuration data for
     the other nodes.  The management node server is implemented as the
     application 'ndb_mgmd'.; the
     management client used to control NDB Cluster is 'ndb_mgm'.
     See
     mysql-cluster-programs-ndb-mgmd, and
     mysql-cluster-programs-ndb-mgm, for information about these
     programs.

   * Data node

     This type of node stores and replicates data.  Data node
     functionality is handled by instances of the 'NDB'
     data node process 'ndbd'.
     For more information, see
     mysql-cluster-programs-ndbd.

   * SQL node

     This is simply an instance of MySQL Server (see 'mysqld')
     that is built with support for the 'NDBCLUSTER'
     storage engine and started with the '--ndb-cluster'
     option to enable the engine and the '--ndb-connectstring' option to
     enable it to connect to an NDB Cluster management server.  For more
     about these options, see
     mysql-cluster-program-options-mysqld.

     *Note*:

     An _API node_ is any application that makes direct use of Cluster
     data nodes for data storage and retrieval.  An SQL node can thus be
     considered a type of API node that uses a MySQL Server to provide
     an SQL interface to the Cluster.  You can write such applications
     (that do not depend on a MySQL Server) using the NDB API, which
     supplies a direct, object-oriented transaction and scanning
     interface to NDB Cluster data; see NDB Cluster API Overview: The
     NDB API (http://dev.mysql.com/doc/ndbapi/en/overview-ndb-api.html),
     for more information.

When I run the 'SHOW' command in the NDB Cluster management client, I
see a line of output that looks like this:

     id=2    @10.100.10.32  (Version: 5.6.40-ndb-7.4.21 Nodegroup: 0, *)

What does the '*' mean?  How is this node different from the others?

The simplest answer is, 'It's not something you can control, and it's
nothing that you need to worry about in any case, unless you're a
software engineer writing or analyzing the NDB Cluster source code'.

If you don't find that answer satisfactory, here's a longer and more
technical version:

A number of mechanisms in NDB Cluster require distributed coordination
among the data nodes.  These distributed algorithms and protocols
include global checkpointing, DDL (schema) changes, and node restart
handling.  To make this coordination simpler, the data nodes 'elect' one
of their number to act as leader.  (This node was once referred to as a
'master', but this terminology was dropped to avoid confusion with
master server in MySQL Replication.)  There is no user-facing mechanism
for influencing this selection, which is completely automatic; the fact
that it _is_ automatic is a key part of NDB Cluster's internal
architecture.

When a node acts as the 'leader' for any of these mechanisms, it is
usually the point of coordination for the activity, and the other nodes
act as 'followers', carrying out their parts of the activity as directed
by the leader.  If the node acting as leader fails, then the remaining
nodes elect a new leader.  Tasks in progress that were being coordinated
by the old leader may either fail or be continued by the new leader,
depending on the actual mechanism involved.

It is possible for some of these different mechanisms and protocols to
have different leader nodes, but in general the same leader is chosen
for all of them.  The node indicated as the leader in the output of
'SHOW' in the management client is known internally as the 'DICT'
manager (see The DBDICT Block
(http://dev.mysql.com/doc/ndb-internals/en/ndb-internals-kernel-blocks-dbdict.html),
in the 'NDB Cluster API Developer Guide', for more information),
responsible for coordinating DDL and metadata activity.

NDB Cluster is designed in such a way that the choice of leader has no
discernible effect outside the cluster itself.  For example, the current
leader does not have significantly higher CPU or resource usage than the
other data nodes, and failure of the leader should not have a
significantly different impact on the cluster than the failure of any
other data node.

With which operating systems can I use NDB Cluster?

NDB Cluster is supported on most Unix-like operating systems.  NDB
Cluster is also supported in production settings on Microsoft Windows
operating systems.

For more detailed information concerning the level of support which is
offered for NDB Cluster on various operating system versions, operating
system distributions, and hardware platforms, please refer to
<http://www.mysql.com/support/supportedplatforms/cluster.html>.

What are the hardware requirements for running NDB Cluster?

NDB Cluster should run on any platform for which 'NDB'.
-enabled binaries are available.  For data nodes and API
nodes, faster CPUs and more memory are likely to improve performance,
and 64-bit CPUs are likely to be more effective than 32-bit processors.
There must be sufficient memory on machines used for data nodes to hold
each node's share of the database (see _How much RAM do I Need?_  for
more information).  For a computer which is used only for running the
NDB Cluster management server, the requirements are minimal; a common
desktop PC (or the equivalent) is generally sufficient for this task.
Nodes can communicate through the standard TCP/IP network and hardware.
They can also use the high-speed SCI protocol; however, special
networking hardware and software are required to use SCI (see
mysql-cluster-interconnects).

How much RAM do I need to use NDB Cluster?  Is it possible to use disk
memory at all?

NDB Cluster was originally implemented as in-memory only, but all
versions currently available also provide the ability to store NDB
Cluster on disk.  See mysql-cluster-disk-data, for more
information.

For in-memory 'NDB' tables, you can use the following formula for
obtaining a rough estimate of how much RAM is needed for each data node
in the cluster:

     (SizeofDatabase x NumberOfReplicas x 1.1 ) / NumberOfDataNodes

To calculate the memory requirements more exactly requires determining,
for each table in the cluster database, the storage space required per
row (see storage-requirements, for details), and multiplying
this by the number of rows.  You must also remember to account for any
column indexes as follows:

   * Each primary key or hash index created for an 'NDBCLUSTER'
     table requires 21−25 bytes per record.  These
     indexes use 'IndexMemory'.

   * Each ordered index requires 10 bytes storage per record, using
     'DataMemory'.

   * Creating a primary key or unique index also creates an ordered
     index, unless this index is created with 'USING HASH'.  In other
     words:

        * A primary key or unique index on a Cluster table normally
          takes up 31 to 35 bytes per record.

        * However, if the primary key or unique index is created with
          'USING HASH', then it requires only 21 to 25 bytes per record.

Creating NDB Cluster tables with 'USING HASH' for all primary keys and
unique indexes will generally cause table updates to run more
quickly--in some cases by a much as 20 to 30 percent faster than updates
on tables where 'USING HASH' was not used in creating primary and unique
keys.  This is due to the fact that less memory is required (because no
ordered indexes are created), and that less CPU must be utilized
(because fewer indexes must be read and possibly updated).  However, it
also means that queries that could otherwise use range scans must be
satisfied by other means, which can result in slower selects.

When calculating Cluster memory requirements, you may find useful the
'ndb_size.pl' utility which
is available in recent MySQL 5.7 releases.  This Perl script connects to
a current (non-Cluster) MySQL database and creates a report on how much
space that database would require if it used the 'NDBCLUSTER'
storage engine.  For more information, see
mysql-cluster-programs-ndb-size-pl.

It is especially important to keep in mind that _every NDB Cluster table
must have a primary key_.  The 'NDB' storage
engine creates a primary key automatically if none is defined; this
primary key is created without 'USING HASH'.

You can determine how much memory is being used for storage of NDB
Cluster data and indexes at any given time using the 'REPORT
MEMORYUSAGE' command in the 'ndb_mgm'
client; see
mysql-cluster-mgm-client-commands, for more information.  In addition,
warnings are written to the cluster log when 80% of available
'DataMemory' or 'IndexMemory' is in use, and again when usage reaches
85%, 90%, and so on.

What file systems can I use with NDB Cluster?  What about network file
systems or network shares?

Generally, any file system that is native to the host operating system
should work well with NDB Cluster.  If you find that a given file system
works particularly well (or not so especially well) with NDB Cluster, we
invite you to discuss your findings in the NDB Cluster Forums
(http://forums.mysql.com/list.php?25).

For Windows, we recommend that you use 'NTFS' file systems for NDB
Cluster, just as we do for standard MySQL. We do not test NDB Cluster
with 'FAT' or 'VFAT' file systems.  Because of this, we do not recommend
their use with MySQL or NDB Cluster.

NDB Cluster is implemented as a shared-nothing solution; the idea behind
this is that the failure of a single piece of hardware should not cause
the failure of multiple cluster nodes, or possibly even the failure of
the cluster as a whole.  For this reason, the use of network shares or
network file systems is not supported for NDB Cluster.  This also
applies to shared storage devices such as SANs.

Can I run NDB Cluster nodes inside virtual machines (such as those
created by VMWare, Parallels, or Xen)?

NDB Cluster is supported for use in virtual machines.  We currently
support and test using Oracle VM
(http://www.oracle.com/technetwork/server-storage/vm/index.html).

Some NDB Cluster users have successfully deployed NDB Cluster using
other virtualization products; in such cases, Oracle can provide NDB
Cluster support, but issues specific to the virtual environment must be
referred to that product's vendor.

I am trying to populate an NDB Cluster database.  The loading process
terminates prematurely and I get an error message like this one:

'ERROR 1114: The table 'my_cluster_table' is full'

Why is this happening?

The cause is very likely to be that your setup does not provide
sufficient RAM for all table data and all indexes, _including the
primary key required by the 'NDB' storage engine
and automatically created in the event that the table definition does
not include the definition of a primary key_.

It is also worth noting that all data nodes should have the same amount
of RAM, since no data node in a cluster can use more memory than the
least amount available to any individual data node.  For example, if
there are four computers hosting Cluster data nodes, and three of these
have 3GB of RAM available to store Cluster data while the remaining data
node has only 1GB RAM, then each data node can devote at most 1GB to NDB
Cluster data and indexes.

In some cases it is possible to get 'Table is full' errors in MySQL
client applications even when 'ndb_mgm -e "ALL REPORT MEMORYUSAGE"'
shows significant free
'DataMemory'.  You can force 'NDB' to create extra
partitions for NDB Cluster tables and thus have more memory available
for hash indexes by using the 'MAX_ROWS' option for 'CREATE TABLE'.
In general, setting 'MAX_ROWS' to twice the
number of rows that you expect to store in the table should be
sufficient.

For similar reasons, you can also sometimes encounter problems with data
node restarts on nodes that are heavily loaded with data.  The
'MinFreePct' parameter can help with this issue by reserving a portion
(5% by default) of 'DataMemory' and 'IndexMemory' for use in restarts.
This reserved memory is not available for storing 'NDB'
tables or data.

NDB Cluster uses TCP/IP. Does this mean that I can run it over the
Internet, with one or more nodes in remote locations?

It is _very_ unlikely that a cluster would perform reliably under such
conditions, as NDB Cluster was designed and implemented with the
assumption that it would be run under conditions guaranteeing dedicated
high-speed connectivity such as that found in a LAN setting using 100
Mbps or gigabit Ethernet--preferably the latter.  We neither test nor
warrant its performance using anything slower than this.

Also, it is extremely important to keep in mind that communications
between the nodes in an NDB Cluster are not secure; they are neither
encrypted nor safeguarded by any other protective mechanism.  The most
secure configuration for a cluster is in a private network behind a
firewall, with no direct access to any Cluster data or management nodes
from outside.  (For SQL nodes, you should take the same precautions as
you would with any other instance of the MySQL server.)  For more
information, see mysql-cluster-security.

Do I have to learn a new programming or query language to use NDB
Cluster?

_No_.  Although some specialized commands are used to manage and
configure the cluster itself, only standard (My)SQL statements are
required for the following operations:

   * Creating, altering, and dropping tables

   * Inserting, updating, and deleting table data

   * Creating, changing, and dropping primary and unique indexes

Some specialized configuration parameters and files are required to set
up an NDB Cluster--see mysql-cluster-config-file, for
information about these.

A few simple commands are used in the NDB Cluster management client
(see 'ndb_mgm') for tasks such as
starting and stopping cluster nodes.  See
mysql-cluster-mgm-client-commands.

What programming languages and APIs are supported by NDB Cluster?

NDB Cluster supports the same programming APIs and languages as the
standard MySQL Server, including ODBC, .Net, the MySQL C API, and
numerous drivers for popular scripting languages such as PHP, Perl, and
Python.  NDB Cluster applications written using these APIs behave
similarly to other MySQL applications; they transmit SQL statements to a
MySQL Server (in the case of NDB Cluster, an SQL node), and receive
responses containing rows of data.  For more information about these
APIs, see connectors-apis.

NDB Cluster also supports application programming using the NDB API,
which provides a low-level C++ interface to NDB Cluster data without
needing to go through a MySQL Server.  See The NDB API
(http://dev.mysql.com/doc/ndbapi/en/ndbapi.html).  In addition, many
'NDBCLUSTER' management functions are exposed by
the C-language MGM API; see The MGM API
(http://dev.mysql.com/doc/ndbapi/en/mgm-api.html), for more information.

NDB Cluster also supports Java application programming using ClusterJ,
which supports a domain object model of data using sessions and
transactions.  See Java and NDB Cluster
(http://dev.mysql.com/doc/ndbapi/en/mccj-overview-java.html), for more
information.

In addition, NDB Cluster provides support for 'memcached', allowing
developers to access data stored in NDB Cluster using the 'memcached'
interface; for more information, see ndbmemcache--Memcache API for NDB
Cluster (http://dev.mysql.com/doc/ndbapi/en/ndbmemcache.html).

NDB Cluster 7.3 and later include adapters supporting NoSQL applications
written against 'Node.js', with NDB Cluster as the data store.  See
MySQL NoSQL Connector for JavaScript
(http://dev.mysql.com/doc/ndbapi/en/ndb-nodejs.html), for more
information.

Does NDB Cluster include any management tools?

NDB Cluster includes a command line client for performing basic
management functions.  See mysql-cluster-programs-ndb-mgm, and
mysql-cluster-mgm-client-commands.

NDB Cluster is also supported by MySQL Cluster Manager, a separate
product providing an advanced command line interface that can automate
many NDB Cluster management tasks such as rolling restarts and
configuration changes.  For more information about MySQL Cluster
Manager, see MySQL(tm) Cluster Manager 1.4.4 User Manual
(http://dev.mysql.com/doc/mysql-cluster-manager/1.4/en/).

NDB Cluster (version 7.3 and later) provides a graphical, browser-based
Auto-Installer for setting up and deploying NDB Cluster, as part of the
NDB Cluster software distribution.  For more information, see
mysql-cluster-install-auto.

How do I find out what an error or warning message means when using NDB
Cluster?

There are two ways in which this can be done:

   * From within the 'mysql' client, use 'SHOW ERRORS' or
     'SHOW WARNINGS' immediately upon being notified of the error or
     warning condition.

   * From a system shell prompt, use 'perror --ndb ERROR_CODE'.

Is NDB Cluster transaction-safe?  What isolation levels are supported?

_Yes_.  For tables created with the 'NDB' storage
engine, transactions are supported.  Currently, NDB Cluster supports
only the 'READ COMMITTED' transaction isolation level.

What storage engines are supported by NDB Cluster?

Clustering with MySQL is supported only by the 'NDB'
storage engine.  That is, in order for a table to be
shared between nodes in an NDB Cluster, the table must be created using
'ENGINE=NDB' (or the equivalent option 'ENGINE=NDBCLUSTER').

It is possible to create tables using other storage engines (such as
'InnoDB' or 'MyISAM')
on a MySQL server being used with an NDB
Cluster, but since these tables do not use 'NDB',
they do not participate in clustering; each such table is strictly local
to the individual MySQL server instance on which it is created.

In the event of a catastrophic failure-- for example, the whole city
loses power _and_ my UPS fails--would I lose all my data?

All committed transactions are logged.  Therefore, although it is
possible that some data could be lost in the event of a catastrophe,
this should be quite limited.  Data loss can be further reduced by
minimizing the number of operations per transaction.  (It is not a good
idea to perform large numbers of operations per transaction in any
case.)

Is it possible to use 'FULLTEXT' indexes with NDB Cluster?

'FULLTEXT' indexing is currently supported only by the 'InnoDB'
and 'MyISAM'.
storage engines.  See fulltext-search, for more information.

Can I run multiple nodes on a single computer?

It is possible but not always advisable.  One of the chief reasons to
run a cluster is to provide redundancy.  To obtain the full benefits of
this redundancy, each node should reside on a separate machine.  If you
place multiple nodes on a single machine and that machine fails, you
lose all of those nodes.  For this reason, if you do run multiple data
nodes on a single machine, it is _extremely_ important that they be set
up in such a way that the failure of this machine does not cause the
loss of all the data nodes in a given node group.

Given that NDB Cluster can be run on commodity hardware loaded with a
low-cost (or even no-cost) operating system, the expense of an extra
machine or two is well worth it to safeguard mission-critical data.  It
also worth noting that the requirements for a cluster host running a
management node are minimal.  This task can be accomplished with a 300
MHz Pentium or equivalent CPU and sufficient RAM for the operating
system, plus a small amount of overhead for the 'ndb_mgmd'
and 'ndb_mgm'
processes.

It is acceptable to run multiple cluster data nodes on a single host
that has multiple CPUs, cores, or both.  The NDB Cluster distribution
also provides a multi-threaded version of the data node binary intended
for use on such systems.  For more information, see
mysql-cluster-programs-ndbmtd.

It is also possible in some cases to run data nodes and SQL nodes
concurrently on the same machine; how well such an arrangement performs
is dependent on a number of factors such as number of cores and CPUs as
well as the amount of disk and memory available to the data node and SQL
node processes, and you must take these factors into account when
planning such a configuration.

Can I add data nodes to an NDB Cluster without restarting it?

It is possible to add new data nodes to a running NDB Cluster without
taking the cluster offline.  For more information, see
mysql-cluster-online-add-node.

For other types of NDB Cluster nodes, a rolling restart is all that is
required (see mysql-cluster-rolling-restart).

Are there any limitations that I should be aware of when using NDB
Cluster?

Limitations on 'NDB' tables in MySQL NDB Cluster
7.3 and later include the following:

   * Temporary tables are not supported; a 'CREATE TEMPORARY TABLE'
     statement using 'ENGINE=NDB' or
     'ENGINE=NDBCLUSTER' fails with an error.

   * The only types of user-defined partitioning supported for
     'NDBCLUSTER' tables are 'KEY' and 'LINEAR KEY'.
     Trying to create an 'NDB' table using any other partitioning type
     fails with an error.

   * 'FULLTEXT' indexes are not supported.

   * Index prefixes are not supported.  Only complete columns may be
     indexed.

   * Spatial indexes are not supported (although spatial columns can be
     used).  See spatial-types.

   * Support for partial transactions and partial rollbacks is
     comparable to that of other transactional storage engines such as
     'InnoDB' that can roll back
     individual statements.

   * The maximum number of attributes allowed per table is 512.
     Attribute names cannot be any longer than 31 characters.  For each
     table, the maximum combined length of the table and database names
     is 122 characters.

   * The maximum size for a table row is 14 kilobytes, not counting
     'BLOB' values.

     There is no set limit for the number of rows per 'NDB' table.
     Limits on table size depend on a number of factors, in particular
     on the amount of RAM available to each data node.

For a complete listing of limitations in NDB Cluster, see
mysql-cluster-limitations.  See also Previous NDB Cluster Issues
Resolved in NDB Cluster 7.3
(http://dev.mysql.com/doc/refman/5.6/en/mysql-cluster-limitations-resolved.html).

Does NDB Cluster support foreign keys?

NDB Cluster 7.3 and later provide support for foreign key constraints,
comparable to that found in the 'InnoDB'.
storage engine; see constraint-foreign-key, for more detailed
information, as well as create-table-foreign-keys.  Applications
requiring foreign key support should use NDB Cluster 7.3, 7.4, 7.5, or
later.

How do I import an existing MySQL database into an NDB Cluster?

You can import databases into NDB Cluster much as you would with any
other version of MySQL. Other than the limitations mentioned elsewhere
in this FAQ, the only other special requirement is that any tables to be
included in the cluster must use the 'NDB' storage
engine.  This means that the tables must be created with 'ENGINE=NDB' or
'ENGINE=NDBCLUSTER'.

It is also possible to convert existing tables that use other storage
engines to 'NDBCLUSTER' using one or more
'ALTER TABLE' statement.  However, the definition of the
table must be compatible with the 'NDBCLUSTER'.
storage engine prior to making the conversion.  In MySQL 5.7, an
additional workaround is also required; see
mysql-cluster-limitations, for details.

How do NDB Cluster nodes communicate with one another?

Cluster nodes can communicate through any of three different transport
mechanisms: TCP/IP, SHM (shared memory), and SCI (Scalable Coherent
Interface).  Where available, SHM is used by default between nodes
residing on the same cluster host; however, this is considered
experimental.  SCI is a high-speed (1 gigabit per second and higher),
high-availability protocol used in building scalable multi-processor
systems; it requires special hardware and drivers.  See
mysql-cluster-interconnects, for more about using SCI as a transport
mechanism for NDB Cluster.

What is an _arbitrator_?

If one or more data nodes in a cluster fail, it is possible that not all
cluster data nodes will be able to 'see' one another.  In fact, it is
possible that two sets of data nodes might become isolated from one
another in a network partitioning, also known as a 'split-brain'
scenario.  This type of situation is undesirable because each set of
data nodes tries to behave as though it is the entire cluster.  An
arbitrator is required to decide between the competing sets of data
nodes.

When all data nodes in at least one node group are alive, network
partitioning is not an issue, because no single subset of the cluster
can form a functional cluster on its own.  The real problem arises when
no single node group has all its nodes alive, in which case network
partitioning (the 'split-brain' scenario) becomes possible.  Then an
arbitrator is required.  All cluster nodes recognize the same node as
the arbitrator, which is normally the management server; however, it is
possible to configure any of the MySQL Servers in the cluster to act as
the arbitrator instead.  The arbitrator accepts the first set of cluster
nodes to contact it, and tells the remaining set to shut down.
Arbitrator selection is controlled by the 'ArbitrationRank'
configuration parameter for MySQL Server and management server nodes.
You can also use the 'ArbitrationRank' configuration parameter to
control the arbitrator selection process.  For more information about
these parameters, see mysql-cluster-mgm-definition.

The role of arbitrator does not in and of itself impose any heavy
demands upon the host so designated, and thus the arbitrator host does
not need to be particularly fast or to have extra memory especially for
this purpose.

What data types are supported by NDB Cluster?

NDB Cluster supports all of the usual MySQL data types, including those
associated with MySQL's spatial extensions; however, the 'NDB'
storage engine does not support spatial indexes.
(Spatial indexes are supported only by 'MyISAM'.;
see spatial-types, for more
information.)  In addition, there are some differences with regard to
indexes when used with 'NDB' tables.

*Note*:

NDB Cluster Disk Data tables (that is, tables created with 'TABLESPACE
... STORAGE DISK ENGINE=NDB' or 'TABLESPACE ... STORAGE DISK
ENGINE=NDBCLUSTER') have only fixed-width rows.  This means that (for
example) each Disk Data table record containing a 'VARCHAR(255)'
column requires space for 255 characters (as required for the
character set and collation being used for the table), regardless of the
actual number of characters stored therein.

See mysql-cluster-limitations, for more information about these
issues.

How do I start and stop NDB Cluster?

It is necessary to start each node in the cluster separately, in the
following order:

  1. Start the management node, using the 'ndb_mgmd'
     command.

     You must include the '-f' or '--config-file' option to tell the
     management node where its configuration file can be found.

  2. Start each data node with the 'ndbd'
     command.

     Each data node must be started with the '-c' or
     '--ndb-connectstring' option so that the data node knows how to
     connect to the management server.

  3. Start each MySQL Server (SQL node) using your preferred startup
     script, such as 'mysqld_safe'.

     Each MySQL Server must be started with the '--ndbcluster' and
     '--ndb-connectstring' options.  These options cause mysqld to
     enable 'NDBCLUSTER' storage engine support
     and how to connect to the management server.

Each of these commands must be run from a system shell on the machine
housing the affected node.  (You do not have to be physically present at
the machine--a remote login shell can be used for this purpose.)  You
can verify that the cluster is running by starting the 'NDB'
management client 'ndb_mgm'
on the machine housing the management
node and issuing the 'SHOW' or 'ALL STATUS' command.

To shut down a running cluster, issue the command 'SHUTDOWN' in the
management client.  Alternatively, you may enter the following command
in a system shell:

     shell> ndb_mgm -e "SHUTDOWN"

(The quotation marks in this example are optional, since there are no
spaces in the command string following the '-e' option; in addition, the
'SHUTDOWN' command, like other management client commands, is not
case-sensitive.)

Either of these commands causes the 'ndb_mgm',
see 'ndb_mgm',
and any 'ndbd'
processes to terminate gracefully.  MySQL
servers running as SQL nodes can be stopped using 'mysqladmin shutdown'.

For more information, see mysql-cluster-mgm-client-commands, and
mysql-cluster-install-shutdown-restart.

What happens to NDB Cluster data when the NDB Cluster is shut down?

The data that was held in memory by the cluster's data nodes is written
to disk, and is reloaded into memory the next time that the cluster is
started.

Is it a good idea to have more than one management node for an NDB
Cluster?

It can be helpful as a fail-safe.  Only one management node controls the
cluster at any given time, but it is possible to configure one
management node as primary, and one or more additional management nodes
to take over in the event that the primary management node fails.

See mysql-cluster-config-file, for information on how to
configure NDB Cluster management nodes.

Can I mix different kinds of hardware and operating systems in one NDB
Cluster?

Yes, as long as all machines and operating systems have the same
'endianness' (all big-endian or all little-endian).

It is also possible to use software from different NDB Cluster releases
on different nodes.  However, we support this only as part of a rolling
upgrade procedure (see mysql-cluster-rolling-restart).

Can I run two data nodes on a single host?  Two SQL nodes?

Yes, it is possible to do this.  In the case of multiple data nodes, it
is advisable (but not required) for each node to use a different data
directory.  If you want to run multiple SQL nodes on one machine, each
instance of 'mysqld' must use a different TCP/IP port.

Running data nodes and SQL nodes together on the same host is possible,
but you should be aware that the 'ndbd'.
(or 'ndbmtd')
and 'mysqld' processes
may compete for memory.

Can I use host names with NDB Cluster?

Yes, it is possible to use DNS and DHCP for cluster hosts.  However, if
your application requires 'five nines' availability, you should use
fixed (numeric) IP addresses, since making communication between Cluster
hosts dependent on services such as DNS and DHCP introduces additional
potential points of failure.

Does NDB Cluster support IPv6?

IPv6 is supported for connections between SQL nodes (MySQL servers), but
connections between all other types of NDB Cluster nodes must use IPv4.

In practical terms, this means that you can use IPv6 for replication
between NDB Clusters, but connections between nodes in the same NDB
Cluster must use IPv4.  For more information, see
mysql-cluster-replication-issues.

How do I handle MySQL users in an NDB Cluster having multiple MySQL
servers?

MySQL user accounts and privileges are normally not automatically
propagated between different MySQL servers accessing the same NDB
Cluster.  MySQL NDB Cluster provides support for distributed privileges,
which you can enable by following a procedure provided in the
documentation; see mysql-cluster-privilege-distribution, for
more information.

How do I continue to send queries in the event that one of the SQL nodes
fails?

MySQL NDB Cluster does not provide any sort of automatic failover
between SQL nodes.  Your application must be prepared to handle the loss
of SQL nodes and to fail over between them.

How do I back up and restore an NDB Cluster?

You can use the NDB Cluster native backup and restore functionality in
the NDB management client and the 'ndb_restore'
program.  See
mysql-cluster-backup, and mysql-cluster-programs-ndb-restore.

You can also use the traditional functionality provided for this purpose
in 'mysqldump' and the MySQL server.  See
mysqldump, for more information.

What is an 'angel process'?

This process monitors and, if necessary, attempts to restart the data
node process.  If you check the list of active processes on your system
after starting 'ndbd', you can see
that there are actually 2 processes running by that name, as shown here
(we omit the output from 'ndb_mgmd'
and 'ndbd'
for brevity):

     shell> ./ndb_mgmd

     shell> ps aux | grep ndb
     me      23002  0.0  0.0 122948  3104 ?        Ssl  14:14   0:00 ./ndb_mgmd
     me      23025  0.0  0.0   5284   820 pts/2    S+   14:14   0:00 grep ndb

     shell> ./ndbd -c 127.0.0.1 --initial

     shell> ps aux | grep ndb
     me      23002  0.0  0.0 123080  3356 ?        Ssl  14:14   0:00 ./ndb_mgmd
     me      23096  0.0  0.0  35876  2036 ?        Ss   14:14   0:00 ./ndbd -c 127.0.0.1 --initial
     me      23097  1.0  2.4 524116 91096 ?        Sl   14:14   0:00 ./ndbd -c 127.0.0.1 --initial
     me      23168  0.0  0.0   5284   812 pts/2    R+   14:15   0:00 grep ndb

The 'ndbd' process showing 0 memory
and CPU usage is the angel process.  It actually does use a very small
amount of each, of course.  It simply checks to see if the main
'ndbd' process (the primary data node
process that actually handles the data) is running.  If permitted to do
so (for example, if the 'StopOnError' configuration parameter is set to
false--see mysql-cluster-params-ndbd), the angel process tries
to restart the primary data node process.

A.11 MySQL 5.7 FAQ: MySQL Chinese, Japanese, and Korean Character Sets
======================================================================

This set of Frequently Asked Questions derives from the experience of
MySQL's Support and Development groups in handling many inquiries about
CJK (Chinese-Japanese-Korean) issues.

What CJK character sets are available in MySQL?

The list of CJK character sets may vary depending on your MySQL version.
For example, the 'gb18030' character set is not supported prior to MySQL
5.7.4.  However, since the name of the applicable language appears in
the 'DESCRIPTION' column for every entry in the
'INFORMATION_SCHEMA.CHARACTER_SETS' table, you
can obtain a current list of all the non-Unicode CJK character sets
using this query:

     mysql> SELECT CHARACTER_SET_NAME, DESCRIPTION
            FROM INFORMATION_SCHEMA.CHARACTER_SETS
            WHERE DESCRIPTION LIKE '%Chin%'
            OR DESCRIPTION LIKE '%Japanese%'
            OR DESCRIPTION LIKE '%Korean%'
            ORDER BY CHARACTER_SET_NAME;
     +--------------------+---------------------------------+
     | CHARACTER_SET_NAME | DESCRIPTION                     |
     +--------------------+---------------------------------+
     | big5               | Big5 Traditional Chinese        |
     | cp932              | SJIS for Windows Japanese       |
     | eucjpms            | UJIS for Windows Japanese       |
     | euckr              | EUC-KR Korean                   |
     | gb18030            | China National Standard GB18030 |
     | gb2312             | GB2312 Simplified Chinese       |
     | gbk                | GBK Simplified Chinese          |
     | sjis               | Shift-JIS Japanese              |
     | ujis               | EUC-JP Japanese                 |
     +--------------------+---------------------------------+

(For more information, see character-sets-table.)

MySQL supports three variants of the _GB_ (_Guojia Biaozhun_, or
_National Standard_, or _Simplified Chinese_) character sets which are
official in the People's Republic of China: 'gb2312', 'gbk', and (as of
MySQL 5.7.4) 'gb18030'.

Sometimes people try to insert 'gbk' characters into 'gb2312', and it
works most of the time because 'gbk' is a superset of 'gb2312'.  But
eventually they try to insert a rarer Chinese character and it does not
work.  (For an example, see Bug #16072).

Here, we try to clarify exactly what characters are legitimate in
'gb2312' or 'gbk', with reference to the official documents.  Please
check these references before reporting 'gb2312' or 'gbk' bugs:

   * The MySQL 'gbk' character set is in reality 'Microsoft code page
     936'.  This differs from the official 'gbk' for characters 'A1A4'
     (middle dot), 'A1AA' (em dash), 'A6E0-A6F5', and 'A8BB-A8C0'.

   * For a listing of 'gbk'/Unicode mappings, see
     <http://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP936.TXT>.

It is also possible to store CJK characters in Unicode character sets,
although the available collations may not sort characters quite as you
expect:

   * The 'utf8' and 'ucs2' character sets support the characters from
     Unicode Basic Multilingual Plane (BMP). These characters have code
     point values between 'U+0000' and 'U+FFFF'.

   * The 'utf8mb4', 'utf16', 'utf16le', and 'utf32' character sets
     support BMP characters, as well as supplementary characters that
     lie outside the BMP. Supplementary characters have code point
     values between 'U+10000' and 'U+10FFFF'.

The collation used for a Unicode character set determines the ability to
sort (that is, distinguish) characters in the set:

   * Collations based on Unicode Collation Algorithm (UCA) 4.0.0
     distinguish only BMP characters.

   * Collations based on UCA 5.2.0 or 9.0.0 distinguish BMP and
     supplementary characters.

   * Non-UCA collations may not distinguish all Unicode characters.  For
     example, the 'utf8mb4' default collation is 'utf8mb4_general_ci',
     which distinguishes only BMP characters.

Moreover, distinguishing characters is not the same as ordering them per
the conventions of a given CJK language.  Currently, MySQL has only one
CJK-specific UCA collation, 'gb18030_unicode_520_ci' (which requires use
of the non-Unicode 'gb18030' character set).

For information about Unicode collations and their differentiating
properties, including collation properties for supplementary characters,
see charset-unicode-sets.

I have inserted CJK characters into my table.  Why does 'SELECT'
display them as '?' characters?

This problem is usually due to a setting in MySQL that does not match
the settings for the application program or the operating system.  Here
are some common steps for correcting these types of issues:

   * _Be certain of what MySQL version you are using_.

     Use the statement 'SELECT VERSION();' to determine this.

   * _Make sure that the database is actually using the desired
     character set_.

     People often think that the client character set is always the same
     as either the server character set or the character set used for
     display purposes.  However, both of these are false assumptions.
     You can make sure by checking the result of 'SHOW CREATE TABLE
     TABLENAME' or, better yet, by using this statement:

          SELECT character_set_name, collation_name
              FROM information_schema.columns
              WHERE table_schema = your_database_name
                  AND table_name = your_table_name
                  AND column_name = your_column_name;

   * _Determine the hexadecimal value of the character or characters
     that are not being displayed correctly_.

     You can obtain this information for a column COLUMN_NAME in the
     table TABLE_NAME using the following query:

          SELECT HEX(COLUMN_NAME)
          FROM TABLE_NAME;

     '3F' is the encoding for the '?' character; this means that '?' is
     the character actually stored in the column.  This most often
     happens because of a problem converting a particular character from
     your client character set to the target character set.

   * _Make sure that a round trip is possible.  When you select LITERAL
     (or _INTRODUCER HEXADECIMAL-VALUE), do you obtain LITERAL as a
     result_?

     For example, the Japanese Katakana character _Pe_ ('ペ'') exists
     in all CJK character sets, and has the code point value
     (hexadecimal coding) '0x30da'.  To test a round trip for this
     character, use this query:

          SELECT 'ペ' AS `ペ`;         /* or SELECT _ucs2 0x30da; */

     If the result is not also 'ペ', the round trip failed.

     For bug reports regarding such failures, we might ask you to follow
     up with 'SELECT HEX('ペ');'.  Then we can determine whether the
     client encoding is correct.

   * _Make sure that the problem is not with the browser or other
     application, rather than with MySQL_.

     Use the 'mysql' client program to accomplish this
     task.  If 'mysql' displays characters correctly but
     your application does not, your problem is probably due to system
     settings.

     To determine your settings, use the 'SHOW VARIABLES'
     statement, whose output should resemble what is
     shown here:

          mysql> SHOW VARIABLES LIKE 'char%';
          +--------------------------+----------------------------------------+
          | Variable_name            | Value                                  |
          +--------------------------+----------------------------------------+
          | character_set_client     | utf8                                   |
          | character_set_connection | utf8                                   |
          | character_set_database   | latin1                                 |
          | character_set_filesystem | binary                                 |
          | character_set_results    | utf8                                   |
          | character_set_server     | latin1                                 |
          | character_set_system     | utf8                                   |
          | character_sets_dir       | /usr/local/mysql/share/mysql/charsets/ |
          +--------------------------+----------------------------------------+

     These are typical character-set settings for an
     international-oriented client (notice the use of 'utf8' Unicode)
     connected to a server in the West ('latin1' is a West Europe
     character set).

     Although Unicode (usually the 'utf8' variant on Unix, and the
     'ucs2' variant on Windows) is preferable to Latin, it is often not
     what your operating system utilities support best.  Many Windows
     users find that a Microsoft character set, such as 'cp932' for
     Japanese Windows, is suitable.

     If you cannot control the server settings, and you have no idea
     what setting your underlying computer uses, try changing to a
     common character set for the country that you're in ('euckr' =
     Korea; 'gb18030', 'gb2312' or 'gbk' = People's Republic of China;
     'big5' = Taiwan; 'sjis', 'ujis', 'cp932', or 'eucjpms' = Japan;
     'ucs2' or 'utf8' = anywhere).  Usually it is necessary to change
     only the client and connection and results settings.  The
     'SET NAMES'.  statement changes all three at once.  For
     example:

          SET NAMES 'big5';

     Once the setting is correct, you can make it permanent by editing
     'my.cnf' or 'my.ini'.  For example you might add lines looking like
     these:

          [mysqld]
          character-set-server=big5
          [client]
          default-character-set=big5

     It is also possible that there are issues with the API
     configuration setting being used in your application; see 'Why does
     my GUI front end or browser not display CJK characters
     correctly...?' for more information.

What problems should I be aware of when working with the Big5 Chinese
character set?

MySQL supports the Big5 character set which is common in Hong Kong and
Taiwan (Republic of China).  The MySQL 'big5' character set is in
reality Microsoft code page 950, which is very similar to the original
'big5' character set.

A feature request for adding 'HKSCS' extensions has been filed.  People
who need this extension may find the suggested patch for Bug #13577 to
be of interest.

Why do Japanese character set conversions fail?

MySQL supports the 'sjis', 'ujis', 'cp932', and 'eucjpms' character
sets, as well as Unicode.  A common need is to convert between character
sets.  For example, there might be a Unix server (typically with 'sjis'
or 'ujis') and a Windows client (typically with 'cp932').

In the following conversion table, the 'ucs2' column represents the
source, and the 'sjis', 'cp932', 'ujis', and 'eucjpms' columns represent
the destinations; that is, the last 4 columns provide the hexadecimal
result when we use 'CONVERT(ucs2)' or we assign a 'ucs2' column
containing the value to an 'sjis', 'cp932', 'ujis', or 'eucjpms' column.

Character Name                ucs2      sjis      cp932     ujis      eucjpms

BROKEN BAR                    00A6      3F        3F        8FA2C3    3F

FULLWIDTH BROKEN BAR          FFE4      3F        FA55      3F        8FA2

YEN SIGN                      00A5      3F        3F        20        3F

FULLWIDTH YEN SIGN            FFE5      818F      818F      A1EF      3F

TILDE                         007E      7E        7E        7E        7E

OVERLINE                      203E      3F        3F        20        3F

HORIZONTAL BAR                2015      815C      815C      A1BD      A1BD

EM DASH                       2014      3F        3F        3F        3F

REVERSE SOLIDUS               005C      815F      5C        5C        5C

FULLWIDTH ""                  FF3C      3F        815F      3F        A1C0

WAVE DASH                     301C      8160      3F        A1C1      3F

FULLWIDTH TILDE               FF5E      3F        8160      3F        A1C1

DOUBLE VERTICAL LINE          2016      8161      3F        A1C2      3F

PARALLEL TO                   2225      3F        8161      3F        A1C2

MINUS SIGN                    2212      817C      3F        A1DD      3F

FULLWIDTH HYPHEN-MINUS        FF0D      3F        817C      3F        A1DD

CENT SIGN                     00A2      8191      3F        A1F1      3F

FULLWIDTH CENT SIGN           FFE0      3F        8191      3F        A1F1

POUND SIGN                    00A3      8192      3F        A1F2      3F

FULLWIDTH POUND SIGN          FFE1      3F        8192      3F        A1F2

NOT SIGN                      00AC      81CA      3F        A2CC      3F

FULLWIDTH NOT SIGN            FFE2      3F        81CA      3F        A2CC

Now consider the following portion of the table.

                                         ucs2        sjis        cp932

NOT SIGN                                 00AC        81CA        3F

FULLWIDTH NOT SIGN                       FFE2        3F          81CA

This means that MySQL converts the 'NOT SIGN' (Unicode 'U+00AC') to
'sjis' code point '0x81CA' and to 'cp932' code point '3F'.  ('3F' is the
question mark ('?'.  This is what is always used when the conversion
cannot be performed.)

What should I do if I want to convert SJIS '81CA' to 'cp932'?

Our answer is: '?'.  There are disadvantages to this, and many people
would prefer a 'loose' conversion, so that '81CA (NOT SIGN)' in 'sjis'
becomes '81CA (FULLWIDTH NOT SIGN)' in 'cp932'.

How does MySQL represent the Yen ('¥') sign?

A problem arises because some versions of Japanese character sets (both
'sjis' and 'euc') treat '5C' as a _reverse solidus_ ('\', also known as
a backslash), whereas others treat it as a yen sign ('¥').

MySQL follows only one version of the JIS (Japanese Industrial
Standards) standard description.  In MySQL, _'5C' is always the reverse
solidus ('\')_.

Of what issues should I be aware when working with Korean character sets
in MySQL?

In theory, while there have been several versions of the 'euckr'
(_Extended Unix Code Korea_) character set, only one problem has been
noted.  We use the 'ASCII' variant of EUC-KR, in which the code point
'0x5c' is REVERSE SOLIDUS, that is '\', instead of the 'KS-Roman'
variant of EUC-KR, in which the code point '0x5c' is 'WON SIGN' ('₩').
This means that you cannot convert Unicode 'U+20A9' to 'euckr':

     mysql> SELECT
                CONVERT('₩' USING euckr) AS euckr,
                HEX(CONVERT('₩' USING euckr)) AS hexeuckr;
     +-------+----------+
     | euckr | hexeuckr |
     +-------+----------+
     | ?     | 3F       |
     +-------+----------+

Why do I get 'Incorrect string value' error messages?

To see the problem, create a table with one Unicode ('ucs2') column and
one Chinese ('gb2312') column.

     mysql> CREATE TABLE ch
            (ucs2 CHAR(3) CHARACTER SET ucs2,
            gb2312 CHAR(3) CHARACTER SET gb2312);

In nonstrict SQL mode, try to place the rare character '汌' in both
columns.

     mysql> SET sql_mode = '';
     mysql> INSERT INTO ch VALUES ('A汌B','A汌B');
     Query OK, 1 row affected, 1 warning (0.00 sec)

The 'INSERT' produces a warning.  Use the following
statement to see what it is:

     mysql> SHOW WARNINGS\G
     *************************** 1. row ***************************
       Level: Warning
        Code: 1366
     Message: Incorrect string value: '\xE6\xB1\x8CB' for column 'gb2312' at row 1

So it is a warning about the 'gb2312' column only.

     mysql> SELECT ucs2,HEX(ucs2),gb2312,HEX(gb2312) FROM ch;
     +-------+--------------+--------+-------------+
     | ucs2  | HEX(ucs2)    | gb2312 | HEX(gb2312) |
     +-------+--------------+--------+-------------+
     | A汌B | 00416C4C0042 | A?B    | 413F42      |
     +-------+--------------+--------+-------------+

Several things need explanation here:

  1. The '汌' character is not in the 'gb2312' character set, as
     described earlier.

  2. If you are using an old version of MySQL, you may see a different
     message.

  3. A warning occurs rather than an error because MySQL is not set to
     use strict SQL mode.  In nonstrict mode, MySQL tries to do what it
     can, to get the best fit, rather than give up.  With strict SQL
     mode, the 'Incorrect string value' message occurs as an error
     rather than a warning, and the 'INSERT' fails.

Why does my GUI front end or browser display CJK characters incorrectly
in my application using Access, PHP, or another API?

Obtain a direct connection to the server using the 'mysql'.
client, and try the same query there.  If 'mysql' responds
correctly, the trouble may be that your application interface requires
initialization.  Use 'mysql' to tell you what character
set or sets it uses with the statement 'SHOW VARIABLES LIKE 'char%';'.
If you are using Access, you are most likely connecting with
Connector/ODBC. In this case, you should check Configuring
Connector/ODBC
(http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-configuration.html).
If, for example, you use 'big5', you would enter 'SET NAMES 'big5''.
(In this case, no ';' character is required.)  If you are using ASP, you
might need to add 'SET NAMES' in the code.  Here is an
example that has worked in the past:

     <%
     Session.CodePage=0
     Dim strConnection
     Dim Conn
     strConnection="driver={MySQL ODBC 3.51 Driver};server=SERVER;uid=USERNAME;" \
                    & "pwd=PASSWORD;database=DATABASE;stmt=SET NAMES 'big5';"
     Set Conn = Server.CreateObject("ADODB.Connection")
     Conn.Open strConnection
     %>

In much the same way, if you are using any character set other than
'latin1' with Connector/Net, you must specify the character set in the
connection string.  See Connecting to MySQL Using Connector/Net
(http://dev.mysql.com/doc/connector-net/en/connector-net-programming-connecting.html),
for more information.

If you are using PHP, try this:

     <?php
       $link = new mysqli($host, $usr, $pwd, $db);

       if( mysqli_connect_errno() )
       {
         printf("Connect failed: %s\n", mysqli_connect_error());
         exit();
       }

       $link->query("SET NAMES 'utf8'");
     ?>

In this case, we used 'SET NAMES' to change
'character_set_client', 'character_set_connection', and
'character_set_results'.

Another issue often encountered in PHP applications has to do with
assumptions made by the browser.  Sometimes adding or changing a
'<meta>' tag suffices to correct the problem: for example, to insure
that the user agent interprets page content as 'UTF-8', include '<meta
http-equiv="Content-Type" content="text/html; charset=utf-8">' in the
'<head>' section of the HTML page.

If you are using Connector/J, see Using Character Sets and Unicode
(http://dev.mysql.com/doc/connector-j/5.1/en/connector-j-reference-charsets.html).

I've upgraded to MySQL 5.7.  How can I revert to behavior like that in
MySQL 4.0 with regard to character sets?

In MySQL Version 4.0, there was a single 'global' character set for both
server and client, and the decision as to which character to use was
made by the server administrator.  This changed starting with MySQL
Version 4.1.  What happens now is a 'handshake', as described in
charset-connection:

When a client connects, it sends to the server the name of the character
set that it wants to use.  The server uses the name to set the
'character_set_client', 'character_set_results', and
'character_set_connection' system variables.  In effect, the server
performs a 'SET NAMES' operation using the character
set name.

The effect of this is that you cannot control the client character set
by starting 'mysqld' with '--character-set-server=utf8'.
However, some Asian customers prefer the MySQL 4.0 behavior.  To make it
possible to retain this behavior, we added a 'mysqld'.
switch, '--character-set-client-handshake', which can be turned off with
'--skip-character-set-client-handshake'.  If you start 'mysqld'
with '--skip-character-set-client-handshake', then, when a
client connects, it sends to the server the name of the character set
that it wants to use.  However, _the server ignores this request from
the client_.

By way of example, suppose that your favorite server character set is
'latin1' (unlikely in a CJK area, but this is the default value).
Suppose further that the client uses 'utf8' because this is what the
client's operating system supports.  Now, start the server with 'latin1'
as its default character set:

     mysqld --character-set-server=latin1

And then start the client with the default character set 'utf8':

     mysql --default-character-set=utf8

The resulting settings can be seen by viewing the output of 'SHOW VARIABLES'.:

     mysql> SHOW VARIABLES LIKE 'char%';
     +--------------------------+----------------------------------------+
     | Variable_name            | Value                                  |
     +--------------------------+----------------------------------------+
     | character_set_client     | utf8                                   |
     | character_set_connection | utf8                                   |
     | character_set_database   | latin1                                 |
     | character_set_filesystem | binary                                 |
     | character_set_results    | utf8                                   |
     | character_set_server     | latin1                                 |
     | character_set_system     | utf8                                   |
     | character_sets_dir       | /usr/local/mysql/share/mysql/charsets/ |
     +--------------------------+----------------------------------------+

Now stop the client, and stop the server using 'mysqladmin'.
Then start the server again, but this time tell it to skip
the handshake like so:

     mysqld --character-set-server=utf8 --skip-character-set-client-handshake

Start the client with 'utf8' once again as the default character set,
then display the resulting settings:

     mysql> SHOW VARIABLES LIKE 'char%';
     +--------------------------+----------------------------------------+
     | Variable_name            | Value                                  |
     +--------------------------+----------------------------------------+
     | character_set_client     | latin1                                 |
     | character_set_connection | latin1                                 |
     | character_set_database   | latin1                                 |
     | character_set_filesystem | binary                                 |
     | character_set_results    | latin1                                 |
     | character_set_server     | latin1                                 |
     | character_set_system     | utf8                                   |
     | character_sets_dir       | /usr/local/mysql/share/mysql/charsets/ |
     +--------------------------+----------------------------------------+

As you can see by comparing the differing results from 'SHOW VARIABLES',
the server ignores the client's initial
settings if the '--skip-character-set-client-handshake' option is used.

Why do some 'LIKE' and 'FULLTEXT' searches with CJK characters fail?

For 'LIKE' searches, there is a very simple problem with binary string
column types such as 'BINARY' and 'BLOB'.:
we must know where characters end.  With multibyte character
sets, different characters might have different octet lengths.  For
example, in 'utf8', 'A' requires one byte but 'ペ' requires three
bytes, as shown here:

     +-------------------------+---------------------------+
     | OCTET_LENGTH(_utf8 'A') | OCTET_LENGTH(_utf8 'ペ') |
     +-------------------------+---------------------------+
     |                       1 |                         3 |
     +-------------------------+---------------------------+

If we do not know where the first character in a string ends, we do not
know where the second character begins, in which case even very simple
searches such as 'LIKE '_A%'' fail.  The solution is to use a nonbinary
string column type defined to have the proper CJK character set.  For
example: 'mycol TEXT CHARACTER SET sjis'.  Alternatively, convert to a
CJK character set before comparing.

This is one reason why MySQL cannot permit encodings of nonexistent
characters.  If it is not strict about rejecting bad input, it has no
way of knowing where characters end.

For 'FULLTEXT' searches, we must know where words begin and end.  With
Western languages, this is rarely a problem because most (if not all) of
these use an easy-to-identify word boundary: the space character.
However, this is not usually the case with Asian writing.  We could use
arbitrary halfway measures, like assuming that all Han characters
represent words, or (for Japanese) depending on changes from Katakana to
Hiragana due to grammatical endings.  However, the only sure solution
requires a comprehensive word list, which means that we would have to
include a dictionary in the server for each Asian language supported.
This is simply not feasible.

How do I know whether character X is available in all character sets?

The majority of simplified Chinese and basic nonhalfwidth Japanese Kana
characters appear in all CJK character sets.  The following stored
procedure accepts a 'UCS-2' Unicode character, converts it to other
character sets, and displays the results in hexadecimal.

     DELIMITER //

     CREATE PROCEDURE p_convert(ucs2_char CHAR(1) CHARACTER SET ucs2)
     BEGIN

     CREATE TABLE tj
                  (ucs2 CHAR(1) character set ucs2,
                   utf8 CHAR(1) character set utf8,
                   big5 CHAR(1) character set big5,
                   cp932 CHAR(1) character set cp932,
                   eucjpms CHAR(1) character set eucjpms,
                   euckr CHAR(1) character set euckr,
                   gb2312 CHAR(1) character set gb2312,
                   gbk CHAR(1) character set gbk,
                   sjis CHAR(1) character set sjis,
                   ujis CHAR(1) character set ujis);

     INSERT INTO tj (ucs2) VALUES (ucs2_char);

     UPDATE tj SET utf8=ucs2,
                   big5=ucs2,
                   cp932=ucs2,
                   eucjpms=ucs2,
                   euckr=ucs2,
                   gb2312=ucs2,
                   gbk=ucs2,
                   sjis=ucs2,
                   ujis=ucs2;

     /* If there are conversion problems, UPDATE produces warnings. */

     SELECT hex(ucs2) AS ucs2,
            hex(utf8) AS utf8,
            hex(big5) AS big5,
            hex(cp932) AS cp932,
            hex(eucjpms) AS eucjpms,
            hex(euckr) AS euckr,
            hex(gb2312) AS gb2312,
            hex(gbk) AS gbk,
            hex(sjis) AS sjis,
            hex(ujis) AS ujis
     FROM tj;

     DROP TABLE tj;

     END//

     DELIMITER ;

The input can be any single 'ucs2' character, or it can be the code
value (hexadecimal representation) of that character.  For example, from
Unicode's list of 'ucs2' encodings and names
(<http://www.unicode.org/Public/UNIDATA/UnicodeData.txt>), we know that
the Katakana character _Pe_ appears in all CJK character sets, and that
its code value is 'X'30DA''.  If we use this value as the argument to
'p_convert()', the result is as shown here:

     mysql> CALL p_convert(X'30DA');
     +------+--------+------+-------+---------+-------+--------+------+------+------+
     | ucs2 | utf8   | big5 | cp932 | eucjpms | euckr | gb2312 | gbk  | sjis | ujis |
     +------+--------+------+-------+---------+-------+--------+------+------+------+
     | 30DA | E3839A | C772 | 8379  | A5DA    | ABDA  | A5DA   | A5DA | 8379 | A5DA |
     +------+--------+------+-------+---------+-------+--------+------+------+------+

Since none of the column values is '3F' (that is, the question mark
character, '?'), we know that every conversion worked.

Why do CJK strings sort incorrectly in Unicode?  (I)

*Note*:

The CJK sorting problems described here can occur for MySQL versions
prior to MySQL 8.0.  As of MySQL 8.0, they can be solved by using the
'utf8mb4' character set and the 'utf8mb4_ja_0900_as_cs' collation.

Sometimes people observe that the result of a 'utf8_unicode_ci' or
'ucs2_unicode_ci' search, or of an 'ORDER BY' sort is not what they
think a native would expect.  Although we never rule out the possibility
that there is a bug, we have found in the past that many people do not
correctly read the standard table of weights for the Unicode Collation
Algorithm.  MySQL uses the tables found under
<http://www.unicode.org/Public/UCA/>:

   * UCA 4.0.0 table:
     <http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt>

     This includes 'XXX_unicode_ci' collations with no version number in
     the collation name.

   * UCA 5.2.0 table:
     <http://www.unicode.org/Public/UCA/5.2.0/allkeys.txt>

     This includes collations with '_520_' in the collation name.

   * UCA 9.0.0 table:
     <http://www.unicode.org/Public/UCA/9.0.0/allkeys.txt>

     This includes collations with '_0900_' in the collation name.

To handle newer UCA versions, we create new collations.  We are very
wary about changing ordering of existing collations because that affects
indexes, which can bring about situations such as that reported in Bug
#16526, illustrated as follows:

     mysql> CREATE TABLE tj (s1 CHAR(1) CHARACTER SET utf8 COLLATE utf8_unicode_ci);
     Query OK, 0 rows affected (0.05 sec)

     mysql> INSERT INTO tj VALUES ('が'),('か');
     Query OK, 2 rows affected (0.00 sec)
     Records: 2  Duplicates: 0  Warnings: 0

     mysql> SELECT * FROM tj WHERE s1 = 'か';
     +------+
     | s1   |
     +------+
     | が  |
     | か  |
     +------+

The character in the first result row is not the one that we searched
for.  Why did MySQL retrieve it?  First we look for the Unicode code
point value, which is possible by reading the hexadecimal number for the
'ucs2' version of the characters:

     mysql> SELECT s1, HEX(CONVERT(s1 USING ucs2)) FROM tj;
     +------+-----------------------------+
     | s1   | HEX(CONVERT(s1 USING ucs2)) |
     +------+-----------------------------+
     | が  | 304C                        |
     | か  | 304B                        |
     +------+-----------------------------+

Now we search for '304B' and '304C' in the '4.0.0 allkeys' table, and
find these lines:

     304B  ; [.1E57.0020.000E.304B] # HIRAGANA LETTER KA
     304C  ; [.1E57.0020.000E.304B][.0000.0140.0002.3099] # HIRAGANA LETTER GA; QQCM

The official Unicode names (following the '#' mark) tell us the Japanese
syllabary (Hiragana), the informal classification (letter, digit, or
punctuation mark), and the Western identifier ('KA' or 'GA', which
happen to be voiced and unvoiced components of the same letter pair).
More importantly, the _primary weight_ (the first hexadecimal number
inside the square brackets) is '1E57' on both lines.  For comparisons in
both searching and sorting, MySQL pays attention to the primary weight
only, ignoring all the other numbers.  This means that we are sorting
'が' and 'か' correctly according to the Unicode specification.  If we
wanted to distinguish them, we'd have to use a non-UCA (Unicode
Collation Algorithm) collation ('utf8_bin' or 'utf8_general_ci'), or to
compare the 'HEX()' values, or use 'ORDER BY CONVERT(s1 USING sjis)'.
Being correct 'according to Unicode' is not enough, of course: the
person who submitted the bug was equally correct.  To solve this, we
need another collation for Japanese according to the JIS X 4061
standard, in which voiced/unvoiced letter pairs like 'KA'/'GA' are
distinguishable for ordering purposes.

Why do CJK strings sort incorrectly in Unicode?  (II)

*Note*:

The CJK sorting problems described here can occur for MySQL versions
prior to MySQL 8.0.  As of MySQL 8.0, they can be solved by using the
'utf8mb4' character set and the 'utf8mb4_ja_0900_as_cs' collation.

If you are using Unicode ('ucs2' or 'utf8'), and you know what the
Unicode sort order is (see faqs-cjk), but MySQL still seems to
sort your table incorrectly, first verify the character set in the table
definition:

     mysql> SHOW CREATE TABLE t\G
     ******************** 1. row ******************
     Table: t
     Create Table: CREATE TABLE `t` (
     `s1` char(1) CHARACTER SET ucs2 DEFAULT NULL
     ) ENGINE=MyISAM DEFAULT CHARSET=latin1

Since the character set for the column 's1' appears to be correct
('ucs2'), check what information the 'INFORMATION_SCHEMA.COLUMNS'
table can provide about this column:

     mysql> SELECT COLUMN_NAME, CHARACTER_SET_NAME, COLLATION_NAME
            FROM INFORMATION_SCHEMA.COLUMNS
            WHERE COLUMN_NAME = 's1'
            AND TABLE_NAME = 't';
     +-------------+--------------------+-----------------+
     | COLUMN_NAME | CHARACTER_SET_NAME | COLLATION_NAME  |
     +-------------+--------------------+-----------------+
     | s1          | ucs2               | ucs2_general_ci |
     +-------------+--------------------+-----------------+

(See columns-table, for more information.)

You can see that the collation is 'ucs2_general_ci' instead of
'ucs2_unicode_ci'.  The reason why this is so can be found using
'SHOW CHARACTER SET', as shown here:

     mysql> SHOW CHARSET LIKE 'ucs2%';
     +---------+---------------+-------------------+--------+
     | Charset | Description   | Default collation | Maxlen |
     +---------+---------------+-------------------+--------+
     | ucs2    | UCS-2 Unicode | ucs2_general_ci   |      2 |
     +---------+---------------+-------------------+--------+

For 'ucs2' and 'utf8', the default collation is 'general'.  To specify a
Unicode UCA collation, use 'COLLATE ucs2_unicode_ci', as shown in the
preceding item.

Why are my supplementary characters rejected by MySQL?

Supplementary characters lie outside the Unicode _Basic Multilingual
Plane / Plane 0_.  BMP characters have code point values between
'U+0000' and 'U+FFFF'.  Supplementary characters have code point values
between 'U+10000' and 'U+10FFFF'.

To store supplementary characters, you must use a character set that
permits them:

   * The 'utf8' and 'ucs2' character sets support BMP characters only.

     The 'utf8' character set permits only 'UTF-8' characters that take
     up to three bytes.  This has led to reports such as that found in
     Bug #12600, which we rejected as 'not a bug'.  With 'utf8', MySQL
     must truncate an input string when it encounters bytes that it does
     no understand.  Otherwise, it is unknown how long the bad multibyte
     character is.

     One possible workaround is to use 'ucs2' instead of 'utf8', in
     which case the 'bad' characters are changed to question marks.
     However, no truncation takes place.  You can also change the data
     type to 'BLOB' or 'BINARY',
     which perform no validity checking.

   * The 'utf8mb4', 'utf16', 'utf16le', and 'utf32' character sets
     support BMP characters, as well as supplementary characters outside
     the BMP.

Should 'CJK' be 'CJKV'?

No.  The term 'CJKV' (_Chinese Japanese Korean Vietnamese_) refers to
Vietnamese character sets which contain Han (originally Chinese)
characters.  MySQL supports the modern Vietnamese script with Western
characters, but does not support the old Vietnamese script using Han
characters.

As of MySQL 5.6, there are Vietnamese collations for Unicode character
sets, as described in charset-unicode-sets.

Does MySQL permit CJK characters to be used in database and table names?

Yes.

Where can I find translations of the MySQL Manual into Chinese,
Japanese, and Korean?

The Japanese translation of the MySQL 5.6 manual can be downloaded from
<http://dev.mysql.com/doc/>.

Where can I get help with CJK and related issues in MySQL?

The following resources are available:

   * A listing of MySQL user groups can be found at
     <https://wikis.oracle.com/display/mysql/List+of+MySQL+User+Groups>.

   * View feature requests relating to character set issues at
     <http://tinyurl.com/y6xcuf>.

   * Visit the MySQL Collation, Unicode Forum.
     <http://forums.mysql.com/> also provides foreign-language forums.

A.12 MySQL 5.7 FAQ: Connectors & APIs
=====================================

For common questions, issues, and answers relating to the MySQL
Connectors and other APIs, see the following areas of the Manual:

   * c-api-common-issues

   * Common Problems with MySQL and PHP
     (http://dev.mysql.com/doc/apis-php/en/apis-php-problems.html)

   * Connector/ODBC Notes and Tips
     (http://dev.mysql.com/doc/connector-odbc/en/connector-odbc-usagenotes.html)

   * Connector/Net Programming
     (http://dev.mysql.com/doc/connector-net/en/connector-net-programming.html)

   * MySQL Connector/J 5.1 Developer Guide
     (http://dev.mysql.com/doc/connector-j/5.1/en/)

A.13 MySQL 5.7 FAQ: Replication
===============================

In the following section, we provide answers to questions that are most
frequently asked about MySQL Replication.

Must the slave be connected to the master all the time?

No, it does not.  The slave can go down or stay disconnected for hours
or even days, and then reconnect and catch up on updates.  For example,
you can set up a master/slave relationship over a dial-up link where the
link is up only sporadically and for short periods of time.  The
implication of this is that, at any given time, the slave is not
guaranteed to be in synchrony with the master unless you take some
special measures.

To ensure that catchup can occur for a slave that has been disconnected,
you must not remove binary log files from the master that contain
information that has not yet been replicated to the slaves.
Asynchronous replication can work only if the slave is able to continue
reading the binary log from the point where it last read events.

Must I enable networking on my master and slave to enable replication?

Yes, networking must be enabled on the master and slave.  If networking
is not enabled, the slave cannot connect to the master and transfer the
binary log.  Check that the 'skip-networking' option has not been
enabled in the configuration file for either server.

How do I know how late a slave is compared to the master?  In other
words, how do I know the date of the last statement replicated by the
slave?

Check the 'Seconds_Behind_Master' column in the output from 'SHOW SLAVE STATUS'.
See
replication-administration-status.

When the slave SQL thread executes an event read from the master, it
modifies its own time to the event timestamp.  (This is why
'TIMESTAMP' is well replicated.)  In the 'Time' column in the
output of 'SHOW PROCESSLIST', the number of
seconds displayed for the slave SQL thread is the number of seconds
between the timestamp of the last replicated event and the real time of
the slave machine.  You can use this to determine the date of the last
replicated event.  Note that if your slave has been disconnected from
the master for one hour, and then reconnects, you may immediately see
large 'Time' values such as 3600 for the slave SQL thread in 'SHOW PROCESSLIST'.
This is because the slave is executing
statements that are one hour old.  See
replication-implementation-details.

How do I force the master to block updates until the slave catches up?

Use the following procedure:

  1. On the master, execute these statements:

          mysql> FLUSH TABLES WITH READ LOCK;
          mysql> SHOW MASTER STATUS;

     Record the replication coordinates (the current binary log file
     name and position) from the output of the 'SHOW'.
     statement.

  2. On the slave, issue the following statement, where the arguments to
     the 'MASTER_POS_WAIT()' function are the replication coordinate
     values obtained in the previous step:

          mysql> SELECT MASTER_POS_WAIT('LOG_NAME', LOG_POS);

     The 'SELECT' statement blocks until the slave
     reaches the specified log file and position.  At that point, the
     slave is in synchrony with the master and the statement returns.

  3. On the master, issue the following statement to enable the master
     to begin processing updates again:

          mysql> UNLOCK TABLES;

What issues should I be aware of when setting up two-way replication?

MySQL replication currently does not support any locking protocol
between master and slave to guarantee the atomicity of a distributed
(cross-server) update.  In other words, it is possible for client A to
make an update to co-master 1, and in the meantime, before it propagates
to co-master 2, client B could make an update to co-master 2 that makes
the update of client A work differently than it did on co-master 1.
Thus, when the update of client A makes it to co-master 2, it produces
tables that are different from what you have on co-master 1, even after
all the updates from co-master 2 have also propagated.  This means that
you should not chain two servers together in a two-way replication
relationship unless you are sure that your updates can safely happen in
any order, or unless you take care of mis-ordered updates somehow in the
client code.

You should also realize that two-way replication actually does not
improve performance very much (if at all) as far as updates are
concerned.  Each server must do the same number of updates, just as you
would have a single server do.  The only difference is that there is a
little less lock contention because the updates originating on another
server are serialized in one slave thread.  Even this benefit might be
offset by network delays.

How can I use replication to improve performance of my system?

Set up one server as the master and direct all writes to it.  Then
configure as many slaves as you have the budget and rackspace for, and
distribute the reads among the master and the slaves.  You can also
start the slaves with the '--skip-innodb', '--low-priority-updates', and
'--delay-key-write=ALL' options to get speed improvements on the slave
end.  In this case, the slave uses nontransactional 'MyISAM' tables
instead of 'InnoDB' tables to get more speed by eliminating
transactional overhead.

What should I do to prepare client code in my own applications to use
performance-enhancing replication?

See the guide to using replication as a scale-out solution, see
replication-solutions-scaleout.

When and how much can MySQL replication improve the performance of my
system?

MySQL replication is most beneficial for a system that processes
frequent reads and infrequent writes.  In theory, by using a
single-master/multiple-slave setup, you can scale the system by adding
more slaves until you either run out of network bandwidth, or your
update load grows to the point that the master cannot handle it.

To determine how many slaves you can use before the added benefits begin
to level out, and how much you can improve performance of your site, you
must know your query patterns, and determine empirically by benchmarking
the relationship between the throughput for reads and writes on a
typical master and a typical slave.  The example here shows a rather
simplified calculation of what you can get with replication for a
hypothetical system.  Let 'reads' and 'writes' denote the number of
reads and writes per second, respectively.

Let's say that system load consists of 10% writes and 90% reads, and we
have determined by benchmarking that 'reads' is 1200 - 2 * 'writes'.  In
other words, the system can do 1,200 reads per second with no writes,
the average write is twice as slow as the average read, and the
relationship is linear.  Suppose that the master and each slave have the
same capacity, and that we have one master and N slaves.  Then we have
for each server (master or slave):

'reads' = 1200 - 2 * 'writes'

'reads' = 9 * 'writes' / (N + 1) (reads are split, but writes replicated
to all slaves)

9 * 'writes' / (N + 1) + 2 * 'writes' = 1200

'writes' = 1200 / (2 + 9/(N + 1))

The last equation indicates the maximum number of writes for N slaves,
given a maximum possible read rate of 1,200 per second and a ratio of
nine reads per write.

This analysis yields the following conclusions:

   * If N = 0 (which means we have no replication), our system can
     handle about 1200/11 = 109 writes per second.

   * If N = 1, we get up to 184 writes per second.

   * If N = 8, we get up to 400 writes per second.

   * If N = 17, we get up to 480 writes per second.

   * Eventually, as N approaches infinity (and our budget negative
     infinity), we can get very close to 600 writes per second,
     increasing system throughput about 5.5 times.  However, with only
     eight servers, we increase it nearly four times.

These computations assume infinite network bandwidth and neglect several
other factors that could be significant on your system.  In many cases,
you may not be able to perform a computation similar to the one just
shown that accurately predicts what will happen on your system if you
add N replication slaves.  However, answering the following questions
should help you decide whether and by how much replication will improve
the performance of your system:

   * What is the read/write ratio on your system?

   * How much more write load can one server handle if you reduce the
     reads?

   * For how many slaves do you have bandwidth available on your
     network?

How can I use replication to provide redundancy or high availability?

How you implement redundancy is entirely dependent on your application
and circumstances.  High-availability solutions (with automatic
failover) require active monitoring and either custom scripts or third
party tools to provide the failover support from the original MySQL
server to the slave.

To handle the process manually, you should be able to switch from a
failed master to a pre-configured slave by altering your application to
talk to the new server or by adjusting the DNS for the MySQL server from
the failed server to the new server.

For more information and some example solutions, see
replication-solutions-switch.

How do I tell whether a master server is using statement-based or
row-based binary logging format?

Check the value of the 'binlog_format' system variable:

     mysql> SHOW VARIABLES LIKE 'binlog_format';

The value shown will be one of 'STATEMENT', 'ROW', or 'MIXED'.  For
'MIXED' mode, statement-based logging is used by default but replication
switches automatically to row-based logging under certain conditions,
such as unsafe statements.  For information about when this may occur,
see binary-log-mixed.

How do I tell a slave to use row-based replication?

Slaves automatically know which format to use.

How do I prevent 'GRANT' and 'REVOKE'.
statements from replicating to slave machines?

Start the server with the '--replicate-wild-ignore-table=mysql.%' option
to ignore replication for tables in the 'mysql' database.

Does replication work on mixed operating systems (for example, the
master runs on Linux while slaves run on OS X and Windows)?

Yes.

Does replication work on mixed hardware architectures (for example, the
master runs on a 64-bit machine while slaves run on 32-bit machines)?

Yes.

A.14 MySQL 5.7 FAQ: MySQL Enterprise Thread Pool
================================================

What is the Thread Pool and what problem does it solve?

The MySQL Thread Pool is a MySQL server plugin that extends the default
connection-handling capabilities of the MySQL server to limit the number
of concurrently executing statements/queries and transactions to ensure
that each has sufficient CPU and memory resources to fulfill its task.
Commercial distributions of MySQL 5.7 include the Thread Pool plugin.

The default thread-handling model in MySQL Server executes statements
using one thread per client connection.  As more clients connect to the
server and execute statements, overall performance degrades.  The Thread
Pool plugin provides an alternative thread-handling model designed to
reduce overhead and improve performance.  The Thread Pool plugin
increases server performance by efficiently managing statement execution
threads for large numbers of client connections, especially on modern
multi-CPU/Core systems.

For more information, see thread-pool.

How does the Thread Pool limit and manage concurrent sessions and
transactions for optimal performance and throughput?

The Thread Pool uses a 'divide and conquer' approach to limiting and
balancing concurrency.  Unlike the default connection handling of the
MySQL Server, the Thread Pool separates connections and threads, so
there is no fixed relationship between connections and the threads that
execute statements received from those connections.  The Thread Pool
then manages client connections within configurable thread groups, where
they are prioritized and queued based on the nature of the work they
were submitted to accomplish.

For more information, see thread-pool-operation.

How is the Thread Pool different from the client side Connection Pool?

The MySQL Connection Pool operates on the client side to ensure that a
MySQL client does not constantly connect to and disconnect from the
MySQL server.  It is designed to cache idle connections in the MySQL
client for use by other users as they are needed.  This minimizes the
overhead and expense of establishing and tearing down connections as
queries are submitted to the MySQL server.  The MySQL Connection Pool
has no visibility as to the query handling capabilities or load of the
back-end MySQL server.  By contrast, the Thread Pool operates on the
MySQL server side and is designed to manage the execution of inbound
concurrent connections and queries as they are received from the client
connections accessing the back-end MySQL database.  Because of the
separation of duties, the MySQL Connection Pool and Thread Pool are
orthogonal and can be used independent of each other.

MySQL Connection Pooling via the MySQL Connectors is covered in
connectors-apis.

When should I use the Thread Pool?

There are a few rules of thumb to consider for optimal Thread Pool use
cases:

The MySQL 'Threads_running' variable keeps track of the number of
concurrent statements currently executing in the MySQL Server.  If this
variable consistently exceeds a region where the server won't operate
optimally (usually going beyond 40 for InnoDB workloads), the Thread
Pool will be beneficial, especially in extreme parallel overload
situations.

If you are using the 'innodb_thread_concurrency' to limit the number of
concurrently executing statements, you will find the Thread Pool solves
the same problem, only better, by assigning connections to thread
groups, then queuing executions based on transactional content, user
defined designations, and so forth.

Lastly, if your workload comprises mainly short queries, the Thread Pool
will be beneficial.

To learn more, see thread-pool-tuning.

Are there recommended Thread Pool configurations?

The Thread Pool has a number of user case driven configuration
parameters that affect its performance.  To learn about these and tips
on tuning, see thread-pool-tuning.

A.15 MySQL 5.7 FAQ: InnoDB Change Buffer
========================================

What types of operations modify secondary indexes and result in change
buffering?

'INSERT', 'UPDATE', and 'DELETE' operations can modify secondary
indexes.  If an affected index page is not in the buffer pool, the
changes can be buffered in the change buffer.

What is the benefit of the 'InnoDB' change buffer?

Buffering secondary index changes when secondary index pages are not in
the buffer pool avoids expensive random access I/O operations that would
be required to immediately read in affected index pages from disk.
Buffered changes can be applied later, in batches, as pages are read
into the buffer pool by other read operations.

Does the change buffer support other types of indexes?

No.  The change buffer only supports secondary indexes.  Clustered
indexes, full-text indexes, and spatial indexes are not supported.
Full-text indexes have their own caching mechanism.

How much space does 'InnoDB' use for the change buffer?

Prior to the introduction of the 'innodb_change_buffer_max_size'
configuration option in MySQL 5.6, the maximum size of the on-disk
change buffer in the system tablespace was 1/3 of the 'InnoDB' buffer
pool size.

In MySQL 5.6 and later, the 'innodb_change_buffer_max_size'
configuration option defines the maximum size of the change buffer as a
percentage of the total buffer pool size.  By default,
'innodb_change_buffer_max_size' is set to 25.  The maximum setting is
50.

'InnoDB' does not buffer an operation if it would cause the on-disk
change buffer to exceed the defined limit.

Change buffer pages are not required to persist in the buffer pool and
may be evicted by LRU operations.

How do I determine the current size of the change buffer?

The current size of the change buffer is reported by 'SHOW ENGINE INNODB
STATUS \G', under the 'INSERT BUFFER AND ADAPTIVE HASH INDEX' heading.
For example:

     -------------------------------------
     INSERT BUFFER AND ADAPTIVE HASH INDEX
     -------------------------------------
     Ibuf: size 1, free list len 0, seg size 2, 0 merges

Relevant data points include:

   * 'size': The number of pages used within the change buffer.  Change
     buffer size is equal to 'seg size - (1 + free list len)'.  The '1
     +' value represents the change buffer header page.

   * 'seg size': The size of the change buffer, in pages.

For information about monitoring change buffer status, see
innodb-insert-buffering.

When does change buffer merging occur?

   * When a page is read into the buffer pool, buffered changes are
     merged upon completion of the read, before the page is made
     available.

   * Change buffer merging is performed as a background task.  The
     'innodb_io_capacity' parameter sets an upper limit on the I/O
     activity performed by 'InnoDB' background tasks such as merging
     data from the change buffer.

   * A change buffer merge is performed during crash recovery.  Changes
     are applied from the change buffer (in the system tablespace) to
     leaf pages of secondary indexes as index pages are read into the
     buffer pool.

   * The change buffer is fully durable and will survive a system crash.
     Upon restart, change buffer merge operations resume as part of
     normal operations.

   * A full merge of the change buffer can be forced as part of a slow
     server shutdown using '--innodb-fast-shutdown=0'.

When is the change buffer flushed?

Updated pages are flushed by the same flushing mechanism that flushes
the other pages that occupy the buffer pool.

When should the change buffer be used?

The change buffer is a feature designed to reduce random I/O to
secondary indexes as indexes grow larger and no longer fit in the
'InnoDB' buffer pool.  Generally, the change buffer should be used when
the entire data set does not fit into the buffer pool, when there is
substantial DML activity that modifies secondary index pages, or when
there are lots of secondary indexes that are regularly changed by DML
activity.

When should the change buffer not be used?

You might consider disabling the change buffer if the entire data set
fits within the 'InnoDB' buffer pool, if you have relatively few
secondary indexes, or if you are using solid-state storage, where random
reads are about as fast as sequential reads.  Before making
configuration changes, it is recommended that you run tests using a
representative workload to determine if disabling the change buffer
provides any benefit.

Where can I find additional information about the change buffer?

The following sections and blog post provide additional information
about the 'InnoDB' change buffer:

   * innodb-insert-buffering

   * innodb-performance-change_buffering

   * MySQL 5.5: InnoDB Change Buffering
     (https://blogs.oracle.com/mysqlinnodb/entry/mysql_5_5_innodb_change)

A.16 MySQL 5.7 FAQ: InnoDB Tablespace Encryption
================================================

Is data decrypted for users who are authorized to see it?

Yes.  'InnoDB' tablespace encryption is designed to provide customers
with the ability to transparently apply encryption within the database
without impacting existing applications.  Returning data in encrypted
format would break most existing applications.  'InnoDB' tablespace
encryption provides the benefit of encryption without the overhead
associated with traditional database encryption solutions, which would
typically require expensive and substantial changes to applications,
database triggers, and views.

What is the overhead associated with 'InnoDB' tablespace encryption?

There is no additional storage overhead.  According to internal
benchmarks, performance overhead amounts to a single digit percentage
difference.

What are the encryption algorithms used with 'InnoDB' tablespace
encryption?

'InnoDB' tablespace encryption supports the Advanced Encryption Standard
(AES256) block-based encryption algorithm.  It uses Electronic Codebook
(ECB) block encryption mode for tablespace key encryption and Cipher
Block Chaining (CBC) block encryption mode for data encryption.

Is it possible to use 3rd party encryption algorithms in place of the
one provided by the 'InnoDB' tablespace encryption feature?

No, it is not possible to use other encryption algorithms.  The provided
encryption algorithm is broadly accepted.

Can indexed columns be encrypted?

'InnoDB' tablespace encryption supports all indexes transparently.

What data types and data lengths does 'InnoDB' tablespace encryption
support?

'InnoDB' tablespace encryption supports all supported data types.  There
is no data length limitation.

Does data remain encrypted on the network?

Data encrypted by the 'InnoDB' tablespace encryption feature is
decrypted when it is read from the tablespace file.  Thus, if the data
is on the network, it is in clear-text form.  However, data on the
network can be encrypted using MySQL network encryption, which encrypts
data traveling to and from a database using SSL/TLS.

Does database memory contain clear-text or encrypted data?

With 'InnoDB' tablespace encryption, in-memory data is decrypted, which
provides 100% transparency.

How do I know which data to encrypt?

Compliance with the PCI-DSS standard requires that credit card numbers
(Primary Account Number, or 'PAN') be stored in encrypted form.  Breach
Notification Laws (for example, CA SB 1386, CA AB 1950, and similar laws
in 43+ more US states) require encryption of first name, last name,
driver license number, and other PII data.  In early 2008, CA AB 1298
added medical and health insurance information to PII data.
Additionally, industry specific privacy and security standards may
require encryption of certain assets.  For example, assets such as
pharmaceutical research results, oil field exploration results,
financial contracts, or personal data of law enforcement informants may
require encryption.  In the health care industry, the privacy of patient
data, health records and X-ray images is of the highest importance.

How is 'InnoDB' tablespace encryption different from encryption
functions MySQL already provides?

There are symmetric and asymmetric encryption APIs in MySQL that can be
used to manually encrypt data within the database.  However, the
application must manage encryption keys and perform required encryption
and decryption operations by calling API functions.  'InnoDB' tablespace
encryption requires no application changes, is transparent to end users,
and provides automated, built-in key management.

Does the transportable tablespaces feature work with 'InnoDB' tablespace
encryption?

Yes.  For more information, see
innodb-tablespace-encryption-exporting.

Does compression work with 'InnoDB' tablespace encryption?

Customers using 'InnoDB' tablespace encryption receive the full benefit
of compression because compression is applied before data blocks are
encrypted.

Can I use 'mysqlpump' or 'mysqldump' with encrypted
tables?

Yes.  Because these utilities create logical backups, the data dumped
from encrypted tables is not encrypted.

How do I change (rotate, re-key) the master encryption key?

'InnoDB' tablespace encryption uses a two tier key mechanism.  When
tablespace encryption is used, individual tablespace keys are stored in
the header of the underlying tablespace data file.  Tablespace keys are
encrypted using the master encryption key.  The master encryption key is
generated when tablespace encryption is enabled, and is stored outside
the database.  The master encryption key is rotated using the
'ALTER INSTANCE ROTATE INNODB MASTER KEY' statement,
which generates a new master encryption key, stores the key, and rotates
the key into use.

How do I migrate data from a clear-text 'InnoDB' tablespace to an
encrypted 'InnoDB' tablespace?

Transferring data from one tablespace to another is not required.  To
encrypt data in an 'InnoDB' tablespace, run 'ALTER TABLE TBL_NAME ENCRYPTION='Y''.
'InnoDB' tablespace encryption is only
supported with file-per-table tablespaces.

Can the 'InnoDB' tablespace encryption feature store the master
encryption key in an external device using the PKSC11 interface?

Not at this time.  Currently, the KMIP 1.1 protocol is supported with
the 'keyring_okv' plugin, which is available with MySQL Enterprise
Edition.

A.17 MySQL 5.7 FAQ: Virtualization Support
==========================================

Is MySQL supported on virtualized environments such as Oracle VM,
VMWare, Docker, Microsoft Hyper-V, or others?

MySQL is supported on virtualized environments, but is certified only
for Oracle VM
(http://www.oracle.com/technetwork/server-storage/vm/index.html).
Contact Oracle Support for more information.

Be aware of potential problems when using virtualization software.  The
usual ones are related to performance, performance degradations,
slowness, or unpredictability of disk, I/O, network, and memory.

Appendix B Errors, Error Codes, and Common Problems
***************************************************

This appendix lists common problems and errors that may occur and
potential resolutions, in addition to listing the errors that may appear
when you call MySQL from any host language.  The first section covers
problems and resolutions.  Detailed information on errors is provided:
One list displays server error messages.  Another list displays client
program messages.

B.1 Sources of Error Information
================================

There are several sources of error information in MySQL:

   * Each SQL statement executed results in an error code, an SQLSTATE
     value, and an error message, as described in error-types.
     These errors are returned from the server side; see
     error-messages-server.

   * Errors can occur on the client side, usually involving problems
     communicating with the server; see error-messages-client.

   * SQL statement warning and error information is available through
     the 'SHOW WARNINGS' and 'SHOW ERRORS'
     statements.  The 'warning_count' system variable
     indicates the number of errors, warnings, and notes.  The
     'error_count' system variable indicates the number of errors.  Its
     value excludes warnings and notes.

   * The 'GET DIAGNOSTICS' statement may be used
     to inspect the diagnostic information in the diagnostics area.  See
     get-diagnostics.

   * 'SHOW SLAVE STATUS' statement output
     includes information about replication errors occurring on the
     slave side.

   * 'SHOW ENGINE INNODB STATUS' statement output
     includes information about the most recent foreign key error if a
     'CREATE TABLE' statement for an
     'InnoDB' table fails.

   * The 'perror' program provides information from the
     command line about error numbers.  See perror.

Descriptions of server and client errors are provided later in this
Appendix.  For information about errors related to 'InnoDB',
see innodb-error-handling.

B.2 Types of Error Values
=========================

When an error occurs in MySQL, the server returns two types of error
values:

   * A MySQL-specific error code.  This value is numeric.  It is not
     portable to other database systems.

   * An SQLSTATE value.  The value is a five-character string (for
     example, ''42S02'').  The values are taken from ANSI SQL and ODBC
     and are more standardized.

A message string that provides a textual description of the error is
also available.

When an error occurs, the MySQL error code, SQLSTATE value, and message
string are available using C API functions:

   * MySQL error code: Call 'mysql_errno()'.

   * SQLSTATE value: Call 'mysql_sqlstate()'.

   * Error message: Call 'mysql_error()'.

For prepared statements, the corresponding error functions are
'mysql_stmt_errno()', 'mysql_stmt_sqlstate()',
and 'mysql_stmt_error()'.
All error functions are described in c-api.

The number of errors, warnings, and notes for the previous statement can
be obtained by calling 'mysql_warning_count()'.
See mysql-warning-count.

The first two characters of an SQLSTATE value indicate the error class:

   * Class = ''00'' indicates success.

   * Class = ''01'' indicates a warning.

   * Class = ''02'' indicates 'not found.' This is relevant within the
     context of cursors and is used to control what happens when a
     cursor reaches the end of a data set.  This condition also occurs
     for 'SELECT ... INTO VAR_LIST' statements that retrieve no rows.

   * Class > ''02'' indicates an exception.

B.3 Server Error Codes and Messages
===================================

MySQL programs have access to several types of error information when
the server returns an error.  For example, the 'mysql'.
client program displays errors using the following format:

     shell> SELECT * FROM no_such_table;
     ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist

The message displayed contains three types of information:

   * A numeric error code ('1146').  This number is MySQL-specific and
     is not portable to other database systems.

   * A five-character SQLSTATE value (''42S02'').  The values are taken
     from ANSI SQL and ODBC and are more standardized.  Not all MySQL
     error numbers have corresponding SQLSTATE values.  In these cases,
     ''HY000'' (general error) is used.

   * A message string that provides a textual description of the error.

For error checking, use error codes, not error messages.  Error messages
do not change often, but it is possible.  Also if the database
administrator changes the language setting, that affects the language of
error messages.

Error codes are stable across GA releases of a given MySQL series.
Before a series reaches GA status, new codes may still be under
development and subject to change.

Server error information comes from the following source files.  For
details about the way that error information is defined, see the MySQL
Internals Manual (http://dev.mysql.com/doc/internals/en).

   * Error message information is listed in the 'share/errmsg-utf8.txt'
     file.  '%d' and '%s' represent numbers and strings, respectively,
     that are substituted into the Message values when they are
     displayed.

   * The Error values listed in 'share/errmsg-utf8.txt' are used to
     generate the definitions in the 'include/mysqld_error.h' and
     'include/mysqld_ername.h' MySQL source files.

   * The SQLSTATE values listed in 'share/errmsg-utf8.txt' are used to
     generate the definitions in the 'include/sql_state.h' MySQL source
     file.

Because updates are frequent, it is possible that those files will
contain additional error information not listed here.

   *
     Error: '1000' SQLSTATE: 'HY000' ('ER_HASHCHK')

     Message: hashchk

     Unused.

   *
     Error: '1001' SQLSTATE: 'HY000' ('ER_NISAMCHK')

     Message: isamchk

     Unused.

   *
     Error: '1002' SQLSTATE: 'HY000' ('ER_NO')

     Message: NO

     Used in the construction of other messages.

   *
     Error: '1003' SQLSTATE: 'HY000' ('ER_YES')

     Message: YES

     Used in the construction of other messages.

     Extended 'EXPLAIN' format generates Note messages.
     'ER_YES' is used in the 'Code' column for these messages in
     subsequent 'SHOW WARNINGS' output.

   *
     Error: '1004' SQLSTATE: 'HY000' ('ER_CANT_CREATE_FILE')

     Message: Can't create file '%s' (errno: %d - %s)

     Occurs for failure to create or copy a file needed for some
     operation.

     Possible causes: Permissions problem for source file; destination
     file already exists but is not writeable.

   *
     Error: '1005' SQLSTATE: 'HY000' ('ER_CANT_CREATE_TABLE')

     Message: Can't create table '%s' (errno: %d)

     'InnoDB' reports this error when a table cannot be created.  If the
     error message refers to error 150, table creation failed because a
     foreign key constraint was not correctly formed.  If the error
     message refers to error −1, table creation probably failed
     because the table includes a column name that matched the name of
     an internal 'InnoDB' table.

   *
     Error: '1006' SQLSTATE: 'HY000' ('ER_CANT_CREATE_DB')

     Message: Can't create database '%s' (errno: %d)

   *
     Error: '1007' SQLSTATE: 'HY000' ('ER_DB_CREATE_EXISTS')

     Message: Can't create database '%s'; database exists

     An attempt to create a database failed because the database already
     exists.

     Drop the database first if you really want to replace an existing
     database, or add an 'IF NOT EXISTS' clause to the 'CREATE DATABASE'
     statement if to retain an existing
     database without having the statement produce an error.

   *
     Error: '1008' SQLSTATE: 'HY000' ('ER_DB_DROP_EXISTS')

     Message: Can't drop database '%s'; database doesn't exist

   *
     Error: '1009' SQLSTATE: 'HY000' ('ER_DB_DROP_DELETE')

     Message: Error dropping database (can't delete '%s', errno: %d)

   *
     Error: '1010' SQLSTATE: 'HY000' ('ER_DB_DROP_RMDIR')

     Message: Error dropping database (can't rmdir '%s', errno: %d)

   *
     Error: '1011' SQLSTATE: 'HY000' ('ER_CANT_DELETE_FILE')

     Message: Error on delete of '%s' (errno: %d - %s)

   *
     Error: '1012' SQLSTATE: 'HY000' ('ER_CANT_FIND_SYSTEM_REC')

     Message: Can't read record in system table

     Returned by 'InnoDB' for attempts to access 'InnoDB'
     'INFORMATION_SCHEMA' tables when 'InnoDB' is unavailable.

   *
     Error: '1013' SQLSTATE: 'HY000' ('ER_CANT_GET_STAT')

     Message: Can't get status of '%s' (errno: %d - %s)

   *
     Error: '1014' SQLSTATE: 'HY000' ('ER_CANT_GET_WD')

     Message: Can't get working directory (errno: %d - %s)

   *
     Error: '1015' SQLSTATE: 'HY000' ('ER_CANT_LOCK')

     Message: Can't lock file (errno: %d - %s)

   *
     Error: '1016' SQLSTATE: 'HY000' ('ER_CANT_OPEN_FILE')

     Message: Can't open file: '%s' (errno: %d - %s)

     'InnoDB' reports this error when the table from the 'InnoDB' data
     files cannot be found, even though the '.frm' file for the table
     exists.  See innodb-troubleshooting-datadict.

   *
     Error: '1017' SQLSTATE: 'HY000' ('ER_FILE_NOT_FOUND')

     Message: Can't find file: '%s' (errno: %d - %s)

   *
     Error: '1018' SQLSTATE: 'HY000' ('ER_CANT_READ_DIR')

     Message: Can't read dir of '%s' (errno: %d - %s)

   *
     Error: '1019' SQLSTATE: 'HY000' ('ER_CANT_SET_WD')

     Message: Can't change dir to '%s' (errno: %d - %s)

   *
     Error: '1020' SQLSTATE: 'HY000' ('ER_CHECKREAD')

     Message: Record has changed since last read in table '%s'

   *
     Error: '1021' SQLSTATE: 'HY000' ('ER_DISK_FULL')

     Message: Disk full (%s); waiting for someone to free some space...
     (errno: %d - %s)

   *
     Error: '1022' SQLSTATE: '23000' ('ER_DUP_KEY')

     Message: Can't write; duplicate key in table '%s'

   *
     Error: '1023' SQLSTATE: 'HY000' ('ER_ERROR_ON_CLOSE')

     Message: Error on close of '%s' (errno: %d - %s)

   *
     Error: '1024' SQLSTATE: 'HY000' ('ER_ERROR_ON_READ')

     Message: Error reading file '%s' (errno: %d - %s)

   *
     Error: '1025' SQLSTATE: 'HY000' ('ER_ERROR_ON_RENAME')

     Message: Error on rename of '%s' to '%s' (errno: %d - %s)

   *
     Error: '1026' SQLSTATE: 'HY000' ('ER_ERROR_ON_WRITE')

     Message: Error writing file '%s' (errno: %d - %s)

   *
     Error: '1027' SQLSTATE: 'HY000' ('ER_FILE_USED')

     Message: '%s' is locked against change

   *
     Error: '1028' SQLSTATE: 'HY000' ('ER_FILSORT_ABORT')

     Message: Sort aborted

   *
     Error: '1029' SQLSTATE: 'HY000' ('ER_FORM_NOT_FOUND')

     Message: View '%s' doesn't exist for '%s'

   *
     Error: '1030' SQLSTATE: 'HY000' ('ER_GET_ERRNO')

     Message: Got error %d from storage engine

     Check the '%d' value to see what the OS error means.  For example,
     28 indicates that you have run out of disk space.

   *
     Error: '1031' SQLSTATE: 'HY000' ('ER_ILLEGAL_HA')

     Message: Table storage engine for '%s' doesn't have this option

   *
     Error: '1032' SQLSTATE: 'HY000' ('ER_KEY_NOT_FOUND')

     Message: Can't find record in '%s'

   *
     Error: '1033' SQLSTATE: 'HY000' ('ER_NOT_FORM_FILE')

     Message: Incorrect information in file: '%s'

   *
     Error: '1034' SQLSTATE: 'HY000' ('ER_NOT_KEYFILE')

     Message: Incorrect key file for table '%s'; try to repair it

   *
     Error: '1035' SQLSTATE: 'HY000' ('ER_OLD_KEYFILE')

     Message: Old key file for table '%s'; repair it!

   *
     Error: '1036' SQLSTATE: 'HY000' ('ER_OPEN_AS_READONLY')

     Message: Table '%s' is read only

   *
     Error: '1037' SQLSTATE: 'HY001' ('ER_OUTOFMEMORY')

     Message: Out of memory; restart server and try again (needed %d
     bytes)

   *
     Error: '1038' SQLSTATE: 'HY001' ('ER_OUT_OF_SORTMEMORY')

     Message: Out of sort memory, consider increasing server sort buffer
     size

   *
     Error: '1039' SQLSTATE: 'HY000' ('ER_UNEXPECTED_EOF')

     Message: Unexpected EOF found when reading file '%s' (errno: %d -
     %s)

   *
     Error: '1040' SQLSTATE: '08004' ('ER_CON_COUNT_ERROR')

     Message: Too many connections

   *
     Error: '1041' SQLSTATE: 'HY000' ('ER_OUT_OF_RESOURCES')

     Message: Out of memory; check if mysqld or some other process uses
     all available memory; if not, you may have to use 'ulimit' to allow
     mysqld to use more memory or you can add more swap space

   *
     Error: '1042' SQLSTATE: '08S01' ('ER_BAD_HOST_ERROR')

     Message: Can't get hostname for your address

   *
     Error: '1043' SQLSTATE: '08S01' ('ER_HANDSHAKE_ERROR')

     Message: Bad handshake

   *
     Error: '1044' SQLSTATE: '42000' ('ER_DBACCESS_DENIED_ERROR')

     Message: Access denied for user '%s'@'%s' to database '%s'

   *
     Error: '1045' SQLSTATE: '28000' ('ER_ACCESS_DENIED_ERROR')

     Message: Access denied for user '%s'@'%s' (using password: %s)

   *
     Error: '1046' SQLSTATE: '3D000' ('ER_NO_DB_ERROR')

     Message: No database selected

   *
     Error: '1047' SQLSTATE: '08S01' ('ER_UNKNOWN_COM_ERROR')

     Message: Unknown command

   *
     Error: '1048' SQLSTATE: '23000' ('ER_BAD_NULL_ERROR')

     Message: Column '%s' cannot be null

   *
     Error: '1049' SQLSTATE: '42000' ('ER_BAD_DB_ERROR')

     Message: Unknown database '%s'

   *
     Error: '1050' SQLSTATE: '42S01' ('ER_TABLE_EXISTS_ERROR')

     Message: Table '%s' already exists

   *
     Error: '1051' SQLSTATE: '42S02' ('ER_BAD_TABLE_ERROR')

     Message: Unknown table '%s'

   *
     Error: '1052' SQLSTATE: '23000' ('ER_NON_UNIQ_ERROR')

     Message: Column '%s' in %s is ambiguous

          %s = column name
          %s = location of column (for example, "field list")

     Likely cause: A column appears in a query without appropriate
     qualification, such as in a select list or ON clause.

     Examples:

          mysql> SELECT i FROM t INNER JOIN t AS t2;
          ERROR 1052 (23000): Column 'i' in field list is ambiguous

          mysql> SELECT * FROM t LEFT JOIN t AS t2 ON i = i;
          ERROR 1052 (23000): Column 'i' in on clause is ambiguous

     Resolution:

        * Qualify the column with the appropriate table name:

               mysql> SELECT t2.i FROM t INNER JOIN t AS t2;

        * Modify the query to avoid the need for qualification:

               mysql> SELECT * FROM t LEFT JOIN t AS t2 USING (i);

   *
     Error: '1053' SQLSTATE: '08S01' ('ER_SERVER_SHUTDOWN')

     Message: Server shutdown in progress

   *
     Error: '1054' SQLSTATE: '42S22' ('ER_BAD_FIELD_ERROR')

     Message: Unknown column '%s' in '%s'

   *
     Error: '1055' SQLSTATE: '42000' ('ER_WRONG_FIELD_WITH_GROUP')

     Message: '%s' isn't in GROUP BY

   *
     Error: '1056' SQLSTATE: '42000' ('ER_WRONG_GROUP_FIELD')

     Message: Can't group on '%s'

   *
     Error: '1057' SQLSTATE: '42000' ('ER_WRONG_SUM_SELECT')

     Message: Statement has sum functions and columns in same statement

   *
     Error: '1058' SQLSTATE: '21S01' ('ER_WRONG_VALUE_COUNT')

     Message: Column count doesn't match value count

   *
     Error: '1059' SQLSTATE: '42000' ('ER_TOO_LONG_IDENT')

     Message: Identifier name '%s' is too long

   *
     Error: '1060' SQLSTATE: '42S21' ('ER_DUP_FIELDNAME')

     Message: Duplicate column name '%s'

   *
     Error: '1061' SQLSTATE: '42000' ('ER_DUP_KEYNAME')

     Message: Duplicate key name '%s'

   *
     Error: '1062' SQLSTATE: '23000' ('ER_DUP_ENTRY')

     Message: Duplicate entry '%s' for key %d

     The message returned with this error uses the format string for
     'ER_DUP_ENTRY_WITH_KEY_NAME'.

   *
     Error: '1063' SQLSTATE: '42000' ('ER_WRONG_FIELD_SPEC')

     Message: Incorrect column specifier for column '%s'

   *
     Error: '1064' SQLSTATE: '42000' ('ER_PARSE_ERROR')

     Message: %s near '%s' at line %d

   *
     Error: '1065' SQLSTATE: '42000' ('ER_EMPTY_QUERY')

     Message: Query was empty

   *
     Error: '1066' SQLSTATE: '42000' ('ER_NONUNIQ_TABLE')

     Message: Not unique table/alias: '%s'

   *
     Error: '1067' SQLSTATE: '42000' ('ER_INVALID_DEFAULT')

     Message: Invalid default value for '%s'

   *
     Error: '1068' SQLSTATE: '42000' ('ER_MULTIPLE_PRI_KEY')

     Message: Multiple primary key defined

   *
     Error: '1069' SQLSTATE: '42000' ('ER_TOO_MANY_KEYS')

     Message: Too many keys specified; max %d keys allowed

   *
     Error: '1070' SQLSTATE: '42000' ('ER_TOO_MANY_KEY_PARTS')

     Message: Too many key parts specified; max %d parts allowed

   *
     Error: '1071' SQLSTATE: '42000' ('ER_TOO_LONG_KEY')

     Message: Specified key was too long; max key length is %d bytes

   *
     Error: '1072' SQLSTATE: '42000' ('ER_KEY_COLUMN_DOES_NOT_EXITS')

     Message: Key column '%s' doesn't exist in table

   *
     Error: '1073' SQLSTATE: '42000' ('ER_BLOB_USED_AS_KEY')

     Message: BLOB column '%s' can't be used in key specification with
     the used table type

   *
     Error: '1074' SQLSTATE: '42000' ('ER_TOO_BIG_FIELDLENGTH')

     Message: Column length too big for column '%s' (max = %lu); use
     BLOB or TEXT instead

   *
     Error: '1075' SQLSTATE: '42000' ('ER_WRONG_AUTO_KEY')

     Message: Incorrect table definition; there can be only one auto
     column and it must be defined as a key

   *
     Error: '1076' SQLSTATE: 'HY000' ('ER_READY')

     Message: %s: ready for connections.  Version: '%s' socket: '%s'
     port: %d

   *
     Error: '1077' SQLSTATE: 'HY000' ('ER_NORMAL_SHUTDOWN')

     Message: %s: Normal shutdown

   *
     Error: '1078' SQLSTATE: 'HY000' ('ER_GOT_SIGNAL')

     Message: %s: Got signal %d.  Aborting!

   *
     Error: '1079' SQLSTATE: 'HY000' ('ER_SHUTDOWN_COMPLETE')

     Message: %s: Shutdown complete

   *
     Error: '1080' SQLSTATE: '08S01' ('ER_FORCING_CLOSE')

     Message: %s: Forcing close of thread %ld user: '%s'

   *
     Error: '1081' SQLSTATE: '08S01' ('ER_IPSOCK_ERROR')

     Message: Can't create IP socket

   *
     Error: '1082' SQLSTATE: '42S12' ('ER_NO_SUCH_INDEX')

     Message: Table '%s' has no index like the one used in CREATE INDEX;
     recreate the table

   *
     Error: '1083' SQLSTATE: '42000' ('ER_WRONG_FIELD_TERMINATORS')

     Message: Field separator argument is not what is expected; check
     the manual

   *
     Error: '1084' SQLSTATE: '42000' ('ER_BLOBS_AND_NO_TERMINATED')

     Message: You can't use fixed rowlength with BLOBs; please use
     'fields terminated by'

   *
     Error: '1085' SQLSTATE: 'HY000' ('ER_TEXTFILE_NOT_READABLE')

     Message: The file '%s' must be in the database directory or be
     readable by all

   *
     Error: '1086' SQLSTATE: 'HY000' ('ER_FILE_EXISTS_ERROR')

     Message: File '%s' already exists

   *
     Error: '1087' SQLSTATE: 'HY000' ('ER_LOAD_INFO')

     Message: Records: %ld Deleted: %ld Skipped: %ld Warnings: %ld

   *
     Error: '1088' SQLSTATE: 'HY000' ('ER_ALTER_INFO')

     Message: Records: %ld Duplicates: %ld

   *
     Error: '1089' SQLSTATE: 'HY000' ('ER_WRONG_SUB_KEY')

     Message: Incorrect prefix key; the used key part isn't a string,
     the used length is longer than the key part, or the storage engine
     doesn't support unique prefix keys

   *
     Error: '1090' SQLSTATE: '42000' ('ER_CANT_REMOVE_ALL_FIELDS')

     Message: You can't delete all columns with ALTER TABLE; use DROP
     TABLE instead

   *
     Error: '1091' SQLSTATE: '42000' ('ER_CANT_DROP_FIELD_OR_KEY')

     Message: Can't DROP '%s'; check that column/key exists

   *
     Error: '1092' SQLSTATE: 'HY000' ('ER_INSERT_INFO')

     Message: Records: %ld Duplicates: %ld Warnings: %ld

   *
     Error: '1093' SQLSTATE: 'HY000' ('ER_UPDATE_TABLE_USED')

     Message: You can't specify target table '%s' for update in FROM
     clause

     This error occurs for attempts to select from and modify the same
     table within a single statement.  If the select attempt occurs
     within a derived table, you can avoid this error by setting the
     'derived_merge' flag of the 'optimizer_switch' system variable to
     force the subquery to be materialized into a temporary table, which
     effectively causes it to be a different table from the one
     modified.  See derived-table-optimization.

   *
     Error: '1094' SQLSTATE: 'HY000' ('ER_NO_SUCH_THREAD')

     Message: Unknown thread id: %lu

   *
     Error: '1095' SQLSTATE: 'HY000' ('ER_KILL_DENIED_ERROR')

     Message: You are not owner of thread %lu

   *
     Error: '1096' SQLSTATE: 'HY000' ('ER_NO_TABLES_USED')

     Message: No tables used

   *
     Error: '1097' SQLSTATE: 'HY000' ('ER_TOO_BIG_SET')

     Message: Too many strings for column %s and SET

   *
     Error: '1098' SQLSTATE: 'HY000' ('ER_NO_UNIQUE_LOGFILE')

     Message: Can't generate a unique log-filename %s.(1-999)

   *
     Error: '1099' SQLSTATE: 'HY000' ('ER_TABLE_NOT_LOCKED_FOR_WRITE')

     Message: Table '%s' was locked with a READ lock and can't be
     updated

   *
     Error: '1100' SQLSTATE: 'HY000' ('ER_TABLE_NOT_LOCKED')

     Message: Table '%s' was not locked with LOCK TABLES

   *
     Error: '1101' SQLSTATE: '42000' ('ER_BLOB_CANT_HAVE_DEFAULT')

     Message: BLOB, TEXT, GEOMETRY or JSON column '%s' can't have a
     default value

   *
     Error: '1102' SQLSTATE: '42000' ('ER_WRONG_DB_NAME')

     Message: Incorrect database name '%s'

   *
     Error: '1103' SQLSTATE: '42000' ('ER_WRONG_TABLE_NAME')

     Message: Incorrect table name '%s'

   *
     Error: '1104' SQLSTATE: '42000' ('ER_TOO_BIG_SELECT')

     Message: The SELECT would examine more than MAX_JOIN_SIZE rows;
     check your WHERE and use SET SQL_BIG_SELECTS=1 or SET
     MAX_JOIN_SIZE=# if the SELECT is okay

   *
     Error: '1105' SQLSTATE: 'HY000' ('ER_UNKNOWN_ERROR')

     Message: Unknown error

   *
     Error: '1106' SQLSTATE: '42000' ('ER_UNKNOWN_PROCEDURE')

     Message: Unknown procedure '%s'

   *
     Error: '1107' SQLSTATE: '42000'
     ('ER_WRONG_PARAMCOUNT_TO_PROCEDURE')

     Message: Incorrect parameter count to procedure '%s'

   *
     Error: '1108' SQLSTATE: 'HY000'
     ('ER_WRONG_PARAMETERS_TO_PROCEDURE')

     Message: Incorrect parameters to procedure '%s'

   *
     Error: '1109' SQLSTATE: '42S02' ('ER_UNKNOWN_TABLE')

     Message: Unknown table '%s' in %s

   *
     Error: '1110' SQLSTATE: '42000' ('ER_FIELD_SPECIFIED_TWICE')

     Message: Column '%s' specified twice

   *
     Error: '1111' SQLSTATE: 'HY000' ('ER_INVALID_GROUP_FUNC_USE')

     Message: Invalid use of group function

   *
     Error: '1112' SQLSTATE: '42000' ('ER_UNSUPPORTED_EXTENSION')

     Message: Table '%s' uses an extension that doesn't exist in this
     MySQL version

   *
     Error: '1113' SQLSTATE: '42000' ('ER_TABLE_MUST_HAVE_COLUMNS')

     Message: A table must have at least 1 column

   *
     Error: '1114' SQLSTATE: 'HY000' ('ER_RECORD_FILE_FULL')

     Message: The table '%s' is full

     'InnoDB' reports this error when the system tablespace runs out of
     free space.  Reconfigure the system tablespace to add a new data
     file.

   *
     Error: '1115' SQLSTATE: '42000' ('ER_UNKNOWN_CHARACTER_SET')

     Message: Unknown character set: '%s'

   *
     Error: '1116' SQLSTATE: 'HY000' ('ER_TOO_MANY_TABLES')

     Message: Too many tables; MySQL can only use %d tables in a join

   *
     Error: '1117' SQLSTATE: 'HY000' ('ER_TOO_MANY_FIELDS')

     Message: Too many columns

   *
     Error: '1118' SQLSTATE: '42000' ('ER_TOO_BIG_ROWSIZE')

     Message: Row size too large.  The maximum row size for the used
     table type, not counting BLOBs, is %ld.  This includes storage
     overhead, check the manual.  You have to change some columns to
     TEXT or BLOBs

   *
     Error: '1119' SQLSTATE: 'HY000' ('ER_STACK_OVERRUN')

     Message: Thread stack overrun: Used: %ld of a %ld stack.  Use
     'mysqld -thread_stack=#' to specify a bigger stack if needed

   *
     Error: '1120' SQLSTATE: '42000' ('ER_WRONG_OUTER_JOIN')

     Message: Cross dependency found in OUTER JOIN; examine your ON
     conditions

   *
     Error: '1121' SQLSTATE: '42000' ('ER_NULL_COLUMN_IN_INDEX')

     Message: Table handler doesn't support NULL in given index.  Please
     change column '%s' to be NOT NULL or use another handler

   *
     Error: '1122' SQLSTATE: 'HY000' ('ER_CANT_FIND_UDF')

     Message: Can't load function '%s'

   *
     Error: '1123' SQLSTATE: 'HY000' ('ER_CANT_INITIALIZE_UDF')

     Message: Can't initialize function '%s'; %s

   *
     Error: '1124' SQLSTATE: 'HY000' ('ER_UDF_NO_PATHS')

     Message: No paths allowed for shared library

   *
     Error: '1125' SQLSTATE: 'HY000' ('ER_UDF_EXISTS')

     Message: Function '%s' already exists

   *
     Error: '1126' SQLSTATE: 'HY000' ('ER_CANT_OPEN_LIBRARY')

     Message: Can't open shared library '%s' (errno: %d %s)

   *
     Error: '1127' SQLSTATE: 'HY000' ('ER_CANT_FIND_DL_ENTRY')

     Message: Can't find symbol '%s' in library

   *
     Error: '1128' SQLSTATE: 'HY000' ('ER_FUNCTION_NOT_DEFINED')

     Message: Function '%s' is not defined

   *
     Error: '1129' SQLSTATE: 'HY000' ('ER_HOST_IS_BLOCKED')

     Message: Host '%s' is blocked because of many connection errors;
     unblock with 'mysqladmin flush-hosts'

   *
     Error: '1130' SQLSTATE: 'HY000' ('ER_HOST_NOT_PRIVILEGED')

     Message: Host '%s' is not allowed to connect to this MySQL server

   *
     Error: '1131' SQLSTATE: '42000' ('ER_PASSWORD_ANONYMOUS_USER')

     Message: You are using MySQL as an anonymous user and anonymous
     users are not allowed to change passwords

   *
     Error: '1132' SQLSTATE: '42000' ('ER_PASSWORD_NOT_ALLOWED')

     Message: You must have privileges to update tables in the mysql
     database to be able to change passwords for others

   *
     Error: '1133' SQLSTATE: '42000' ('ER_PASSWORD_NO_MATCH')

     Message: Can't find any matching row in the user table

   *
     Error: '1134' SQLSTATE: 'HY000' ('ER_UPDATE_INFO')

     Message: Rows matched: %ld Changed: %ld Warnings: %ld

   *
     Error: '1135' SQLSTATE: 'HY000' ('ER_CANT_CREATE_THREAD')

     Message: Can't create a new thread (errno %d); if you are not out
     of available memory, you can consult the manual for a possible
     OS-dependent bug

   *
     Error: '1136' SQLSTATE: '21S01' ('ER_WRONG_VALUE_COUNT_ON_ROW')

     Message: Column count doesn't match value count at row %ld

   *
     Error: '1137' SQLSTATE: 'HY000' ('ER_CANT_REOPEN_TABLE')

     Message: Can't reopen table: '%s'

   *
     Error: '1138' SQLSTATE: '22004' ('ER_INVALID_USE_OF_NULL')

     Message: Invalid use of NULL value

   *
     Error: '1139' SQLSTATE: '42000' ('ER_REGEXP_ERROR')

     Message: Got error '%s' from regexp

   *
     Error: '1140' SQLSTATE: '42000' ('ER_MIX_OF_GROUP_FUNC_AND_FIELDS')

     Message: Mixing of GROUP columns (MIN(),MAX(),COUNT(),...)  with no
     GROUP columns is illegal if there is no GROUP BY clause

   *
     Error: '1141' SQLSTATE: '42000' ('ER_NONEXISTING_GRANT')

     Message: There is no such grant defined for user '%s' on host '%s'

   *
     Error: '1142' SQLSTATE: '42000' ('ER_TABLEACCESS_DENIED_ERROR')

     Message: %s command denied to user '%s'@'%s' for table '%s'

   *
     Error: '1143' SQLSTATE: '42000' ('ER_COLUMNACCESS_DENIED_ERROR')

     Message: %s command denied to user '%s'@'%s' for column '%s' in
     table '%s'

   *
     Error: '1144' SQLSTATE: '42000' ('ER_ILLEGAL_GRANT_FOR_TABLE')

     Message: Illegal GRANT/REVOKE command; please consult the manual to
     see which privileges can be used

   *
     Error: '1145' SQLSTATE: '42000' ('ER_GRANT_WRONG_HOST_OR_USER')

     Message: The host or user argument to GRANT is too long

   *
     Error: '1146' SQLSTATE: '42S02' ('ER_NO_SUCH_TABLE')

     Message: Table '%s.%s' doesn't exist

   *
     Error: '1147' SQLSTATE: '42000' ('ER_NONEXISTING_TABLE_GRANT')

     Message: There is no such grant defined for user '%s' on host '%s'
     on table '%s'

   *
     Error: '1148' SQLSTATE: '42000' ('ER_NOT_ALLOWED_COMMAND')

     Message: The used command is not allowed with this MySQL version

   *
     Error: '1149' SQLSTATE: '42000' ('ER_SYNTAX_ERROR')

     Message: You have an error in your SQL syntax; check the manual
     that corresponds to your MySQL server version for the right syntax
     to use

   *
     Error: '1150' SQLSTATE: 'HY000' ('ER_UNUSED1')

     Message: Delayed insert thread couldn't get requested lock for
     table %s

   *
     Error: '1151' SQLSTATE: 'HY000' ('ER_UNUSED2')

     Message: Too many delayed threads in use

   *
     Error: '1152' SQLSTATE: '08S01' ('ER_ABORTING_CONNECTION')

     Message: Aborted connection %ld to db: '%s' user: '%s' (%s)

   *
     Error: '1153' SQLSTATE: '08S01' ('ER_NET_PACKET_TOO_LARGE')

     Message: Got a packet bigger than 'max_allowed_packet' bytes

   *
     Error: '1154' SQLSTATE: '08S01' ('ER_NET_READ_ERROR_FROM_PIPE')

     Message: Got a read error from the connection pipe

   *
     Error: '1155' SQLSTATE: '08S01' ('ER_NET_FCNTL_ERROR')

     Message: Got an error from fcntl()

   *
     Error: '1156' SQLSTATE: '08S01' ('ER_NET_PACKETS_OUT_OF_ORDER')

     Message: Got packets out of order

   *
     Error: '1157' SQLSTATE: '08S01' ('ER_NET_UNCOMPRESS_ERROR')

     Message: Couldn't uncompress communication packet

   *
     Error: '1158' SQLSTATE: '08S01' ('ER_NET_READ_ERROR')

     Message: Got an error reading communication packets

   *
     Error: '1159' SQLSTATE: '08S01' ('ER_NET_READ_INTERRUPTED')

     Message: Got timeout reading communication packets

   *
     Error: '1160' SQLSTATE: '08S01' ('ER_NET_ERROR_ON_WRITE')

     Message: Got an error writing communication packets

   *
     Error: '1161' SQLSTATE: '08S01' ('ER_NET_WRITE_INTERRUPTED')

     Message: Got timeout writing communication packets

   *
     Error: '1162' SQLSTATE: '42000' ('ER_TOO_LONG_STRING')

     Message: Result string is longer than 'max_allowed_packet' bytes

   *
     Error: '1163' SQLSTATE: '42000' ('ER_TABLE_CANT_HANDLE_BLOB')

     Message: The used table type doesn't support BLOB/TEXT columns

   *
     Error: '1164' SQLSTATE: '42000'
     ('ER_TABLE_CANT_HANDLE_AUTO_INCREMENT')

     Message: The used table type doesn't support AUTO_INCREMENT columns

   *
     Error: '1165' SQLSTATE: 'HY000' ('ER_UNUSED3')

     Message: INSERT DELAYED can't be used with table '%s' because it is
     locked with LOCK TABLES

   *
     Error: '1166' SQLSTATE: '42000' ('ER_WRONG_COLUMN_NAME')

     Message: Incorrect column name '%s'

   *
     Error: '1167' SQLSTATE: '42000' ('ER_WRONG_KEY_COLUMN')

     Message: The used storage engine can't index column '%s'

   *
     Error: '1168' SQLSTATE: 'HY000' ('ER_WRONG_MRG_TABLE')

     Message: Unable to open underlying table which is differently
     defined or of non-MyISAM type or doesn't exist

   *
     Error: '1169' SQLSTATE: '23000' ('ER_DUP_UNIQUE')

     Message: Can't write, because of unique constraint, to table '%s'

   *
     Error: '1170' SQLSTATE: '42000' ('ER_BLOB_KEY_WITHOUT_LENGTH')

     Message: BLOB/TEXT column '%s' used in key specification without a
     key length

   *
     Error: '1171' SQLSTATE: '42000' ('ER_PRIMARY_CANT_HAVE_NULL')

     Message: All parts of a PRIMARY KEY must be NOT NULL; if you need
     NULL in a key, use UNIQUE instead

   *
     Error: '1172' SQLSTATE: '42000' ('ER_TOO_MANY_ROWS')

     Message: Result consisted of more than one row

   *
     Error: '1173' SQLSTATE: '42000' ('ER_REQUIRES_PRIMARY_KEY')

     Message: This table type requires a primary key

   *
     Error: '1174' SQLSTATE: 'HY000' ('ER_NO_RAID_COMPILED')

     Message: This version of MySQL is not compiled with RAID support

   *
     Error: '1175' SQLSTATE: 'HY000'
     ('ER_UPDATE_WITHOUT_KEY_IN_SAFE_MODE')

     Message: You are using safe update mode and you tried to update a
     table without a WHERE that uses a KEY column

   *
     Error: '1176' SQLSTATE: '42000' ('ER_KEY_DOES_NOT_EXITS')

     Message: Key '%s' doesn't exist in table '%s'

   *
     Error: '1177' SQLSTATE: '42000' ('ER_CHECK_NO_SUCH_TABLE')

     Message: Can't open table

   *
     Error: '1178' SQLSTATE: '42000' ('ER_CHECK_NOT_IMPLEMENTED')

     Message: The storage engine for the table doesn't support %s

   *
     Error: '1179' SQLSTATE: '25000'
     ('ER_CANT_DO_THIS_DURING_AN_TRANSACTION')

     Message: You are not allowed to execute this command in a
     transaction

   *
     Error: '1180' SQLSTATE: 'HY000' ('ER_ERROR_DURING_COMMIT')

     Message: Got error %d during COMMIT

   *
     Error: '1181' SQLSTATE: 'HY000' ('ER_ERROR_DURING_ROLLBACK')

     Message: Got error %d during ROLLBACK

   *
     Error: '1182' SQLSTATE: 'HY000' ('ER_ERROR_DURING_FLUSH_LOGS')

     Message: Got error %d during FLUSH_LOGS

   *
     Error: '1183' SQLSTATE: 'HY000' ('ER_ERROR_DURING_CHECKPOINT')

     Message: Got error %d during CHECKPOINT

   *
     Error: '1184' SQLSTATE: '08S01' ('ER_NEW_ABORTING_CONNECTION')

     Message: Aborted connection %u to db: '%s' user: '%s' host: '%s'
     (%s)

   *
     Error: '1185' SQLSTATE: 'HY000' ('ER_DUMP_NOT_IMPLEMENTED')

     Message: The storage engine for the table does not support binary
     table dump

   *
     Error: '1186' SQLSTATE: 'HY000' ('ER_FLUSH_MASTER_BINLOG_CLOSED')

     Message: Binlog closed, cannot RESET MASTER

   *
     Error: '1187' SQLSTATE: 'HY000' ('ER_INDEX_REBUILD')

     Message: Failed rebuilding the index of dumped table '%s'

   *
     Error: '1188' SQLSTATE: 'HY000' ('ER_MASTER')

     Message: Error from master: '%s'

   *
     Error: '1189' SQLSTATE: '08S01' ('ER_MASTER_NET_READ')

     Message: Net error reading from master

   *
     Error: '1190' SQLSTATE: '08S01' ('ER_MASTER_NET_WRITE')

     Message: Net error writing to master

   *
     Error: '1191' SQLSTATE: 'HY000' ('ER_FT_MATCHING_KEY_NOT_FOUND')

     Message: Can't find FULLTEXT index matching the column list

   *
     Error: '1192' SQLSTATE: 'HY000' ('ER_LOCK_OR_ACTIVE_TRANSACTION')

     Message: Can't execute the given command because you have active
     locked tables or an active transaction

   *
     Error: '1193' SQLSTATE: 'HY000' ('ER_UNKNOWN_SYSTEM_VARIABLE')

     Message: Unknown system variable '%s'

   *
     Error: '1194' SQLSTATE: 'HY000' ('ER_CRASHED_ON_USAGE')

     Message: Table '%s' is marked as crashed and should be repaired

   *
     Error: '1195' SQLSTATE: 'HY000' ('ER_CRASHED_ON_REPAIR')

     Message: Table '%s' is marked as crashed and last (automatic?)
     repair failed

   *
     Error: '1196' SQLSTATE: 'HY000'
     ('ER_WARNING_NOT_COMPLETE_ROLLBACK')

     Message: Some non-transactional changed tables couldn't be rolled
     back

   *
     Error: '1197' SQLSTATE: 'HY000' ('ER_TRANS_CACHE_FULL')

     Message: Multi-statement transaction required more than
     'max_binlog_cache_size' bytes of storage; increase this mysqld
     variable and try again

   *
     Error: '1198' SQLSTATE: 'HY000' ('ER_SLAVE_MUST_STOP')

     Message: This operation cannot be performed with a running slave;
     run STOP SLAVE first

   *
     Error: '1199' SQLSTATE: 'HY000' ('ER_SLAVE_NOT_RUNNING')

     Message: This operation requires a running slave; configure slave
     and do START SLAVE

   *
     Error: '1200' SQLSTATE: 'HY000' ('ER_BAD_SLAVE')

     Message: The server is not configured as slave; fix in config file
     or with CHANGE MASTER TO

   *
     Error: '1201' SQLSTATE: 'HY000' ('ER_MASTER_INFO')

     Message: Could not initialize master info structure; more error
     messages can be found in the MySQL error log

   *
     Error: '1202' SQLSTATE: 'HY000' ('ER_SLAVE_THREAD')

     Message: Could not create slave thread; check system resources

   *
     Error: '1203' SQLSTATE: '42000' ('ER_TOO_MANY_USER_CONNECTIONS')

     Message: User %s already has more than 'max_user_connections'
     active connections

   *
     Error: '1204' SQLSTATE: 'HY000' ('ER_SET_CONSTANTS_ONLY')

     Message: You may only use constant expressions with SET

   *
     Error: '1205' SQLSTATE: 'HY000' ('ER_LOCK_WAIT_TIMEOUT')

     Message: Lock wait timeout exceeded; try restarting transaction

     'InnoDB' reports this error when lock wait timeout expires.  The
     statement that waited too long was rolled back (not the entire
     transaction).  You can increase the value of the
     'innodb_lock_wait_timeout' configuration option if SQL statements
     should wait longer for other transactions to complete, or decrease
     it if too many long-running transactions are causing locking
     problems and reducing concurrency on a busy system.

   *
     Error: '1206' SQLSTATE: 'HY000' ('ER_LOCK_TABLE_FULL')

     Message: The total number of locks exceeds the lock table size

     'InnoDB' reports this error when the total number of locks exceeds
     the amount of memory devoted to managing locks.  To avoid this
     error, increase the value of 'innodb_buffer_pool_size'.  Within an
     individual application, a workaround may be to break a large
     operation into smaller pieces.  For example, if the error occurs
     for a large 'INSERT', perform several smaller
     'INSERT' operations.

   *
     Error: '1207' SQLSTATE: '25000' ('ER_READ_ONLY_TRANSACTION')

     Message: Update locks cannot be acquired during a READ UNCOMMITTED
     transaction

   *
     Error: '1208' SQLSTATE: 'HY000' ('ER_DROP_DB_WITH_READ_LOCK')

     Message: DROP DATABASE not allowed while thread is holding global
     read lock

   *
     Error: '1209' SQLSTATE: 'HY000' ('ER_CREATE_DB_WITH_READ_LOCK')

     Message: CREATE DATABASE not allowed while thread is holding global
     read lock

   *
     Error: '1210' SQLSTATE: 'HY000' ('ER_WRONG_ARGUMENTS')

     Message: Incorrect arguments to %s

   *
     Error: '1211' SQLSTATE: '42000' ('ER_NO_PERMISSION_TO_CREATE_USER')

     Message: '%s'@'%s' is not allowed to create new users

   *
     Error: '1212' SQLSTATE: 'HY000'
     ('ER_UNION_TABLES_IN_DIFFERENT_DIR')

     Message: Incorrect table definition; all MERGE tables must be in
     the same database

   *
     Error: '1213' SQLSTATE: '40001' ('ER_LOCK_DEADLOCK')

     Message: Deadlock found when trying to get lock; try restarting
     transaction

     'InnoDB' reports this error when a transaction encounters a
     deadlock and is automatically rolled back so that your application
     can take corrective action.  To recover from this error, run all
     the operations in this transaction again.  A deadlock occurs when
     requests for locks arrive in inconsistent order between
     transactions.  The transaction that was rolled back released all
     its locks, and the other transaction can now get all the locks it
     requested.  Thus, when you re-run the transaction that was rolled
     back, it might have to wait for other transactions to complete, but
     typically the deadlock does not recur.  If you encounter frequent
     deadlocks, make the sequence of locking operations ('LOCK TABLES',
     'SELECT ... FOR UPDATE', and so on) consistent between the
     different transactions or applications that experience the issue.
     See innodb-deadlocks for details.

   *
     Error: '1214' SQLSTATE: 'HY000' ('ER_TABLE_CANT_HANDLE_FT')

     Message: The used table type doesn't support FULLTEXT indexes

   *
     Error: '1215' SQLSTATE: 'HY000' ('ER_CANNOT_ADD_FOREIGN')

     Message: Cannot add foreign key constraint

   *
     Error: '1216' SQLSTATE: '23000' ('ER_NO_REFERENCED_ROW')

     Message: Cannot add or update a child row: a foreign key constraint
     fails

     'InnoDB' reports this error when you try to add a row but there is
     no parent row, and a foreign key constraint fails.  Add the parent
     row first.

   *
     Error: '1217' SQLSTATE: '23000' ('ER_ROW_IS_REFERENCED')

     Message: Cannot delete or update a parent row: a foreign key
     constraint fails

     'InnoDB' reports this error when you try to delete a parent row
     that has children, and a foreign key constraint fails.  Delete the
     children first.

   *
     Error: '1218' SQLSTATE: '08S01' ('ER_CONNECT_TO_MASTER')

     Message: Error connecting to master: %s

   *
     Error: '1219' SQLSTATE: 'HY000' ('ER_QUERY_ON_MASTER')

     Message: Error running query on master: %s

   *
     Error: '1220' SQLSTATE: 'HY000' ('ER_ERROR_WHEN_EXECUTING_COMMAND')

     Message: Error when executing command %s: %s

   *
     Error: '1221' SQLSTATE: 'HY000' ('ER_WRONG_USAGE')

     Message: Incorrect usage of %s and %s

   *
     Error: '1222' SQLSTATE: '21000'
     ('ER_WRONG_NUMBER_OF_COLUMNS_IN_SELECT')

     Message: The used SELECT statements have a different number of
     columns

   *
     Error: '1223' SQLSTATE: 'HY000' ('ER_CANT_UPDATE_WITH_READLOCK')

     Message: Can't execute the query because you have a conflicting
     read lock

   *
     Error: '1224' SQLSTATE: 'HY000' ('ER_MIXING_NOT_ALLOWED')

     Message: Mixing of transactional and non-transactional tables is
     disabled

   *
     Error: '1225' SQLSTATE: 'HY000' ('ER_DUP_ARGUMENT')

     Message: Option '%s' used twice in statement

   *
     Error: '1226' SQLSTATE: '42000' ('ER_USER_LIMIT_REACHED')

     Message: User '%s' has exceeded the '%s' resource (current value:
     %ld)

   *
     Error: '1227' SQLSTATE: '42000' ('ER_SPECIFIC_ACCESS_DENIED_ERROR')

     Message: Access denied; you need (at least one of) the %s
     privilege(s) for this operation

   *
     Error: '1228' SQLSTATE: 'HY000' ('ER_LOCAL_VARIABLE')

     Message: Variable '%s' is a SESSION variable and can't be used with
     SET GLOBAL

   *
     Error: '1229' SQLSTATE: 'HY000' ('ER_GLOBAL_VARIABLE')

     Message: Variable '%s' is a GLOBAL variable and should be set with
     SET GLOBAL

   *
     Error: '1230' SQLSTATE: '42000' ('ER_NO_DEFAULT')

     Message: Variable '%s' doesn't have a default value

   *
     Error: '1231' SQLSTATE: '42000' ('ER_WRONG_VALUE_FOR_VAR')

     Message: Variable '%s' can't be set to the value of '%s'

   *
     Error: '1232' SQLSTATE: '42000' ('ER_WRONG_TYPE_FOR_VAR')

     Message: Incorrect argument type to variable '%s'

   *
     Error: '1233' SQLSTATE: 'HY000' ('ER_VAR_CANT_BE_READ')

     Message: Variable '%s' can only be set, not read

   *
     Error: '1234' SQLSTATE: '42000' ('ER_CANT_USE_OPTION_HERE')

     Message: Incorrect usage/placement of '%s'

   *
     Error: '1235' SQLSTATE: '42000' ('ER_NOT_SUPPORTED_YET')

     Message: This version of MySQL doesn't yet support '%s'

   *
     Error: '1236' SQLSTATE: 'HY000'
     ('ER_MASTER_FATAL_ERROR_READING_BINLOG')

     Message: Got fatal error %d from master when reading data from
     binary log: '%s'

   *
     Error: '1237' SQLSTATE: 'HY000' ('ER_SLAVE_IGNORED_TABLE')

     Message: Slave SQL thread ignored the query because of
     replicate-*-table rules

   *
     Error: '1238' SQLSTATE: 'HY000' ('ER_INCORRECT_GLOBAL_LOCAL_VAR')

     Message: Variable '%s' is a %s variable

   *
     Error: '1239' SQLSTATE: '42000' ('ER_WRONG_FK_DEF')

     Message: Incorrect foreign key definition for '%s': %s

   *
     Error: '1240' SQLSTATE: 'HY000'
     ('ER_KEY_REF_DO_NOT_MATCH_TABLE_REF')

     Message: Key reference and table reference don't match

   *
     Error: '1241' SQLSTATE: '21000' ('ER_OPERAND_COLUMNS')

     Message: Operand should contain %d column(s)

   *
     Error: '1242' SQLSTATE: '21000' ('ER_SUBQUERY_NO_1_ROW')

     Message: Subquery returns more than 1 row

   *
     Error: '1243' SQLSTATE: 'HY000' ('ER_UNKNOWN_STMT_HANDLER')

     Message: Unknown prepared statement handler (%.*s) given to %s

   *
     Error: '1244' SQLSTATE: 'HY000' ('ER_CORRUPT_HELP_DB')

     Message: Help database is corrupt or does not exist

   *
     Error: '1245' SQLSTATE: 'HY000' ('ER_CYCLIC_REFERENCE')

     Message: Cyclic reference on subqueries

   *
     Error: '1246' SQLSTATE: 'HY000' ('ER_AUTO_CONVERT')

     Message: Converting column '%s' from %s to %s

   *
     Error: '1247' SQLSTATE: '42S22' ('ER_ILLEGAL_REFERENCE')

     Message: Reference '%s' not supported (%s)

   *
     Error: '1248' SQLSTATE: '42000' ('ER_DERIVED_MUST_HAVE_ALIAS')

     Message: Every derived table must have its own alias

   *
     Error: '1249' SQLSTATE: '01000' ('ER_SELECT_REDUCED')

     Message: Select %u was reduced during optimization

   *
     Error: '1250' SQLSTATE: '42000' ('ER_TABLENAME_NOT_ALLOWED_HERE')

     Message: Table '%s' from one of the SELECTs cannot be used in %s

   *
     Error: '1251' SQLSTATE: '08004' ('ER_NOT_SUPPORTED_AUTH_MODE')

     Message: Client does not support authentication protocol requested
     by server; consider upgrading MySQL client

   *
     Error: '1252' SQLSTATE: '42000' ('ER_SPATIAL_CANT_HAVE_NULL')

     Message: All parts of a SPATIAL index must be NOT NULL

   *
     Error: '1253' SQLSTATE: '42000' ('ER_COLLATION_CHARSET_MISMATCH')

     Message: COLLATION '%s' is not valid for CHARACTER SET '%s'

   *
     Error: '1254' SQLSTATE: 'HY000' ('ER_SLAVE_WAS_RUNNING')

     Message: Slave is already running

   *
     Error: '1255' SQLSTATE: 'HY000' ('ER_SLAVE_WAS_NOT_RUNNING')

     Message: Slave already has been stopped

   *
     Error: '1256' SQLSTATE: 'HY000' ('ER_TOO_BIG_FOR_UNCOMPRESS')

     Message: Uncompressed data size too large; the maximum size is %d
     (probably, length of uncompressed data was corrupted)

   *
     Error: '1257' SQLSTATE: 'HY000' ('ER_ZLIB_Z_MEM_ERROR')

     Message: ZLIB: Not enough memory

   *
     Error: '1258' SQLSTATE: 'HY000' ('ER_ZLIB_Z_BUF_ERROR')

     Message: ZLIB: Not enough room in the output buffer (probably,
     length of uncompressed data was corrupted)

   *
     Error: '1259' SQLSTATE: 'HY000' ('ER_ZLIB_Z_DATA_ERROR')

     Message: ZLIB: Input data corrupted

   *
     Error: '1260' SQLSTATE: 'HY000' ('ER_CUT_VALUE_GROUP_CONCAT')

     Message: Row %u was cut by GROUP_CONCAT()

   *
     Error: '1261' SQLSTATE: '01000' ('ER_WARN_TOO_FEW_RECORDS')

     Message: Row %ld doesn't contain data for all columns

   *
     Error: '1262' SQLSTATE: '01000' ('ER_WARN_TOO_MANY_RECORDS')

     Message: Row %ld was truncated; it contained more data than there
     were input columns

   *
     Error: '1263' SQLSTATE: '22004' ('ER_WARN_NULL_TO_NOTNULL')

     Message: Column set to default value; NULL supplied to NOT NULL
     column '%s' at row %ld

   *
     Error: '1264' SQLSTATE: '22003' ('ER_WARN_DATA_OUT_OF_RANGE')

     Message: Out of range value for column '%s' at row %ld

   *
     Error: '1265' SQLSTATE: '01000' ('WARN_DATA_TRUNCATED')

     Message: Data truncated for column '%s' at row %ld

   *
     Error: '1266' SQLSTATE: 'HY000' ('ER_WARN_USING_OTHER_HANDLER')

     Message: Using storage engine %s for table '%s'

   *
     Error: '1267' SQLSTATE: 'HY000' ('ER_CANT_AGGREGATE_2COLLATIONS')

     Message: Illegal mix of collations (%s,%s) and (%s,%s) for
     operation '%s'

   *
     Error: '1268' SQLSTATE: 'HY000' ('ER_DROP_USER')

     Message: Cannot drop one or more of the requested users

   *
     Error: '1269' SQLSTATE: 'HY000' ('ER_REVOKE_GRANTS')

     Message: Can't revoke all privileges for one or more of the
     requested users

   *
     Error: '1270' SQLSTATE: 'HY000' ('ER_CANT_AGGREGATE_3COLLATIONS')

     Message: Illegal mix of collations (%s,%s), (%s,%s), (%s,%s) for
     operation '%s'

   *
     Error: '1271' SQLSTATE: 'HY000' ('ER_CANT_AGGREGATE_NCOLLATIONS')

     Message: Illegal mix of collations for operation '%s'

   *
     Error: '1272' SQLSTATE: 'HY000' ('ER_VARIABLE_IS_NOT_STRUCT')

     Message: Variable '%s' is not a variable component (can't be used
     as XXXX.variable_name)

   *
     Error: '1273' SQLSTATE: 'HY000' ('ER_UNKNOWN_COLLATION')

     Message: Unknown collation: '%s'

   *
     Error: '1274' SQLSTATE: 'HY000' ('ER_SLAVE_IGNORED_SSL_PARAMS')

     Message: SSL parameters in CHANGE MASTER are ignored because this
     MySQL slave was compiled without SSL support; they can be used
     later if MySQL slave with SSL is started

   *
     Error: '1275' SQLSTATE: 'HY000'
     ('ER_SERVER_IS_IN_SECURE_AUTH_MODE')

     Message: Server is running in -secure-auth mode, but '%s'@'%s' has
     a password in the old format; please change the password to the new
     format

   *
     Error: '1276' SQLSTATE: 'HY000' ('ER_WARN_FIELD_RESOLVED')

     Message: Field or reference '%s%s%s%s%s' of SELECT #%d was resolved
     in SELECT #%d

   *
     Error: '1277' SQLSTATE: 'HY000' ('ER_BAD_SLAVE_UNTIL_COND')

     Message: Incorrect parameter or combination of parameters for START
     SLAVE UNTIL

   *
     Error: '1278' SQLSTATE: 'HY000' ('ER_MISSING_SKIP_SLAVE')

     Message: It is recommended to use -skip-slave-start when doing
     step-by-step replication with START SLAVE UNTIL; otherwise, you
     will get problems if you get an unexpected slave's mysqld restart

   *
     Error: '1279' SQLSTATE: 'HY000' ('ER_UNTIL_COND_IGNORED')

     Message: SQL thread is not to be started so UNTIL options are
     ignored

   *
     Error: '1280' SQLSTATE: '42000' ('ER_WRONG_NAME_FOR_INDEX')

     Message: Incorrect index name '%s'

   *
     Error: '1281' SQLSTATE: '42000' ('ER_WRONG_NAME_FOR_CATALOG')

     Message: Incorrect catalog name '%s'

   *
     Error: '1282' SQLSTATE: 'HY000' ('ER_WARN_QC_RESIZE')

     Message: Query cache failed to set size %lu; new query cache size
     is %lu

   *
     Error: '1283' SQLSTATE: 'HY000' ('ER_BAD_FT_COLUMN')

     Message: Column '%s' cannot be part of FULLTEXT index

   *
     Error: '1284' SQLSTATE: 'HY000' ('ER_UNKNOWN_KEY_CACHE')

     Message: Unknown key cache '%s'

   *
     Error: '1285' SQLSTATE: 'HY000' ('ER_WARN_HOSTNAME_WONT_WORK')

     Message: MySQL is started in -skip-name-resolve mode; you must
     restart it without this switch for this grant to work

   *
     Error: '1286' SQLSTATE: '42000' ('ER_UNKNOWN_STORAGE_ENGINE')

     Message: Unknown storage engine '%s'

   *
     Error: '1287' SQLSTATE: 'HY000' ('ER_WARN_DEPRECATED_SYNTAX')

     Message: '%s' is deprecated and will be removed in a future
     release.  Please use %s instead

   *
     Error: '1288' SQLSTATE: 'HY000' ('ER_NON_UPDATABLE_TABLE')

     Message: The target table %s of the %s is not updatable

   *
     Error: '1289' SQLSTATE: 'HY000' ('ER_FEATURE_DISABLED')

     Message: The '%s' feature is disabled; you need MySQL built with
     '%s' to have it working

   *
     Error: '1290' SQLSTATE: 'HY000' ('ER_OPTION_PREVENTS_STATEMENT')

     Message: The MySQL server is running with the %s option so it
     cannot execute this statement

   *
     Error: '1291' SQLSTATE: 'HY000' ('ER_DUPLICATED_VALUE_IN_TYPE')

     Message: Column '%s' has duplicated value '%s' in %s

   *
     Error: '1292' SQLSTATE: '22007' ('ER_TRUNCATED_WRONG_VALUE')

     Message: Truncated incorrect %s value: '%s'

   *
     Error: '1293' SQLSTATE: 'HY000' ('ER_TOO_MUCH_AUTO_TIMESTAMP_COLS')

     Message: Incorrect table definition; there can be only one
     TIMESTAMP column with CURRENT_TIMESTAMP in DEFAULT or ON UPDATE
     clause

   *
     Error: '1294' SQLSTATE: 'HY000' ('ER_INVALID_ON_UPDATE')

     Message: Invalid ON UPDATE clause for '%s' column

   *
     Error: '1295' SQLSTATE: 'HY000' ('ER_UNSUPPORTED_PS')

     Message: This command is not supported in the prepared statement
     protocol yet

   *
     Error: '1296' SQLSTATE: 'HY000' ('ER_GET_ERRMSG')

     Message: Got error %d '%s' from %s

   *
     Error: '1297' SQLSTATE: 'HY000' ('ER_GET_TEMPORARY_ERRMSG')

     Message: Got temporary error %d '%s' from %s

   *
     Error: '1298' SQLSTATE: 'HY000' ('ER_UNKNOWN_TIME_ZONE')

     Message: Unknown or incorrect time zone: '%s'

   *
     Error: '1299' SQLSTATE: 'HY000' ('ER_WARN_INVALID_TIMESTAMP')

     Message: Invalid TIMESTAMP value in column '%s' at row %ld

   *
     Error: '1300' SQLSTATE: 'HY000' ('ER_INVALID_CHARACTER_STRING')

     Message: Invalid %s character string: '%s'

   *
     Error: '1301' SQLSTATE: 'HY000'
     ('ER_WARN_ALLOWED_PACKET_OVERFLOWED')

     Message: Result of %s() was larger than max_allowed_packet (%ld) -
     truncated

   *
     Error: '1302' SQLSTATE: 'HY000' ('ER_CONFLICTING_DECLARATIONS')

     Message: Conflicting declarations: '%s%s' and '%s%s'

   *
     Error: '1303' SQLSTATE: '2F003' ('ER_SP_NO_RECURSIVE_CREATE')

     Message: Can't create a %s from within another stored routine

   *
     Error: '1304' SQLSTATE: '42000' ('ER_SP_ALREADY_EXISTS')

     Message: %s %s already exists

   *
     Error: '1305' SQLSTATE: '42000' ('ER_SP_DOES_NOT_EXIST')

     Message: %s %s does not exist

   *
     Error: '1306' SQLSTATE: 'HY000' ('ER_SP_DROP_FAILED')

     Message: Failed to DROP %s %s

   *
     Error: '1307' SQLSTATE: 'HY000' ('ER_SP_STORE_FAILED')

     Message: Failed to CREATE %s %s

   *
     Error: '1308' SQLSTATE: '42000' ('ER_SP_LILABEL_MISMATCH')

     Message: %s with no matching label: %s

   *
     Error: '1309' SQLSTATE: '42000' ('ER_SP_LABEL_REDEFINE')

     Message: Redefining label %s

   *
     Error: '1310' SQLSTATE: '42000' ('ER_SP_LABEL_MISMATCH')

     Message: End-label %s without match

   *
     Error: '1311' SQLSTATE: '01000' ('ER_SP_UNINIT_VAR')

     Message: Referring to uninitialized variable %s

   *
     Error: '1312' SQLSTATE: '0A000' ('ER_SP_BADSELECT')

     Message: PROCEDURE %s can't return a result set in the given
     context

   *
     Error: '1313' SQLSTATE: '42000' ('ER_SP_BADRETURN')

     Message: RETURN is only allowed in a FUNCTION

   *
     Error: '1314' SQLSTATE: '0A000' ('ER_SP_BADSTATEMENT')

     Message: %s is not allowed in stored procedures

   *
     Error: '1315' SQLSTATE: '42000'
     ('ER_UPDATE_LOG_DEPRECATED_IGNORED')

     Message: The update log is deprecated and replaced by the binary
     log; SET SQL_LOG_UPDATE has been ignored.

   *
     Error: '1316' SQLSTATE: '42000'
     ('ER_UPDATE_LOG_DEPRECATED_TRANSLATED')

     Message: The update log is deprecated and replaced by the binary
     log; SET SQL_LOG_UPDATE has been translated to SET SQL_LOG_BIN.

   *
     Error: '1317' SQLSTATE: '70100' ('ER_QUERY_INTERRUPTED')

     Message: Query execution was interrupted

   *
     Error: '1318' SQLSTATE: '42000' ('ER_SP_WRONG_NO_OF_ARGS')

     Message: Incorrect number of arguments for %s %s; expected %u, got
     %u

   *
     Error: '1319' SQLSTATE: '42000' ('ER_SP_COND_MISMATCH')

     Message: Undefined CONDITION: %s

   *
     Error: '1320' SQLSTATE: '42000' ('ER_SP_NORETURN')

     Message: No RETURN found in FUNCTION %s

   *
     Error: '1321' SQLSTATE: '2F005' ('ER_SP_NORETURNEND')

     Message: FUNCTION %s ended without RETURN

   *
     Error: '1322' SQLSTATE: '42000' ('ER_SP_BAD_CURSOR_QUERY')

     Message: Cursor statement must be a SELECT

   *
     Error: '1323' SQLSTATE: '42000' ('ER_SP_BAD_CURSOR_SELECT')

     Message: Cursor SELECT must not have INTO

   *
     Error: '1324' SQLSTATE: '42000' ('ER_SP_CURSOR_MISMATCH')

     Message: Undefined CURSOR: %s

   *
     Error: '1325' SQLSTATE: '24000' ('ER_SP_CURSOR_ALREADY_OPEN')

     Message: Cursor is already open

   *
     Error: '1326' SQLSTATE: '24000' ('ER_SP_CURSOR_NOT_OPEN')

     Message: Cursor is not open

   *
     Error: '1327' SQLSTATE: '42000' ('ER_SP_UNDECLARED_VAR')

     Message: Undeclared variable: %s

   *
     Error: '1328' SQLSTATE: 'HY000' ('ER_SP_WRONG_NO_OF_FETCH_ARGS')

     Message: Incorrect number of FETCH variables

   *
     Error: '1329' SQLSTATE: '02000' ('ER_SP_FETCH_NO_DATA')

     Message: No data - zero rows fetched, selected, or processed

   *
     Error: '1330' SQLSTATE: '42000' ('ER_SP_DUP_PARAM')

     Message: Duplicate parameter: %s

   *
     Error: '1331' SQLSTATE: '42000' ('ER_SP_DUP_VAR')

     Message: Duplicate variable: %s

   *
     Error: '1332' SQLSTATE: '42000' ('ER_SP_DUP_COND')

     Message: Duplicate condition: %s

   *
     Error: '1333' SQLSTATE: '42000' ('ER_SP_DUP_CURS')

     Message: Duplicate cursor: %s

   *
     Error: '1334' SQLSTATE: 'HY000' ('ER_SP_CANT_ALTER')

     Message: Failed to ALTER %s %s

   *
     Error: '1335' SQLSTATE: '0A000' ('ER_SP_SUBSELECT_NYI')

     Message: Subquery value not supported

   *
     Error: '1336' SQLSTATE: '0A000'
     ('ER_STMT_NOT_ALLOWED_IN_SF_OR_TRG')

     Message: %s is not allowed in stored function or trigger

   *
     Error: '1337' SQLSTATE: '42000' ('ER_SP_VARCOND_AFTER_CURSHNDLR')

     Message: Variable or condition declaration after cursor or handler
     declaration

   *
     Error: '1338' SQLSTATE: '42000' ('ER_SP_CURSOR_AFTER_HANDLER')

     Message: Cursor declaration after handler declaration

   *
     Error: '1339' SQLSTATE: '20000' ('ER_SP_CASE_NOT_FOUND')

     Message: Case not found for CASE statement

   *
     Error: '1340' SQLSTATE: 'HY000' ('ER_FPARSER_TOO_BIG_FILE')

     Message: Configuration file '%s' is too big

   *
     Error: '1341' SQLSTATE: 'HY000' ('ER_FPARSER_BAD_HEADER')

     Message: Malformed file type header in file '%s'

   *
     Error: '1342' SQLSTATE: 'HY000' ('ER_FPARSER_EOF_IN_COMMENT')

     Message: Unexpected end of file while parsing comment '%s'

   *
     Error: '1343' SQLSTATE: 'HY000' ('ER_FPARSER_ERROR_IN_PARAMETER')

     Message: Error while parsing parameter '%s' (line: '%s')

   *
     Error: '1344' SQLSTATE: 'HY000'
     ('ER_FPARSER_EOF_IN_UNKNOWN_PARAMETER')

     Message: Unexpected end of file while skipping unknown parameter
     '%s'

   *
     Error: '1345' SQLSTATE: 'HY000' ('ER_VIEW_NO_EXPLAIN')

     Message: EXPLAIN/SHOW can not be issued; lacking privileges for
     underlying table

   *
     Error: '1346' SQLSTATE: 'HY000' ('ER_FRM_UNKNOWN_TYPE')

     Message: File '%s' has unknown type '%s' in its header

   *
     Error: '1347' SQLSTATE: 'HY000' ('ER_WRONG_OBJECT')

     Message: '%s.%s' is not %s

     The named object is incorrect for the type of operation attempted
     on it.  It must be an object of the named type.

   *
     Error: '1348' SQLSTATE: 'HY000' ('ER_NONUPDATEABLE_COLUMN')

     Message: Column '%s' is not updatable

   *
     Error: '1349' SQLSTATE: 'HY000' ('ER_VIEW_SELECT_DERIVED')

     Message: View's SELECT contains a subquery in the FROM clause

     'ER_VIEW_SELECT_DERIVED' was removed after 5.7.6.

   *
     Error: '1349' SQLSTATE: 'HY000' ('ER_VIEW_SELECT_DERIVED_UNUSED')

     Message: View's SELECT contains a subquery in the FROM clause

     'ER_VIEW_SELECT_DERIVED_UNUSED' was added in 5.7.7.

   *
     Error: '1350' SQLSTATE: 'HY000' ('ER_VIEW_SELECT_CLAUSE')

     Message: View's SELECT contains a '%s' clause

   *
     Error: '1351' SQLSTATE: 'HY000' ('ER_VIEW_SELECT_VARIABLE')

     Message: View's SELECT contains a variable or parameter

   *
     Error: '1352' SQLSTATE: 'HY000' ('ER_VIEW_SELECT_TMPTABLE')

     Message: View's SELECT refers to a temporary table '%s'

   *
     Error: '1353' SQLSTATE: 'HY000' ('ER_VIEW_WRONG_LIST')

     Message: View's SELECT and view's field list have different column
     counts

   *
     Error: '1354' SQLSTATE: 'HY000' ('ER_WARN_VIEW_MERGE')

     Message: View merge algorithm can't be used here for now (assumed
     undefined algorithm)

   *
     Error: '1355' SQLSTATE: 'HY000' ('ER_WARN_VIEW_WITHOUT_KEY')

     Message: View being updated does not have complete key of
     underlying table in it

   *
     Error: '1356' SQLSTATE: 'HY000' ('ER_VIEW_INVALID')

     Message: View '%s.%s' references invalid table(s) or column(s) or
     function(s) or definer/invoker of view lack rights to use them

   *
     Error: '1357' SQLSTATE: 'HY000' ('ER_SP_NO_DROP_SP')

     Message: Can't drop or alter a %s from within another stored
     routine

   *
     Error: '1358' SQLSTATE: 'HY000' ('ER_SP_GOTO_IN_HNDLR')

     Message: GOTO is not allowed in a stored procedure handler

   *
     Error: '1359' SQLSTATE: 'HY000' ('ER_TRG_ALREADY_EXISTS')

     Message: Trigger already exists

   *
     Error: '1360' SQLSTATE: 'HY000' ('ER_TRG_DOES_NOT_EXIST')

     Message: Trigger does not exist

   *
     Error: '1361' SQLSTATE: 'HY000' ('ER_TRG_ON_VIEW_OR_TEMP_TABLE')

     Message: Trigger's '%s' is view or temporary table

   *
     Error: '1362' SQLSTATE: 'HY000' ('ER_TRG_CANT_CHANGE_ROW')

     Message: Updating of %s row is not allowed in %strigger

   *
     Error: '1363' SQLSTATE: 'HY000' ('ER_TRG_NO_SUCH_ROW_IN_TRG')

     Message: There is no %s row in %s trigger

   *
     Error: '1364' SQLSTATE: 'HY000' ('ER_NO_DEFAULT_FOR_FIELD')

     Message: Field '%s' doesn't have a default value

   *
     Error: '1365' SQLSTATE: '22012' ('ER_DIVISION_BY_ZERO')

     Message: Division by 0

   *
     Error: '1366' SQLSTATE: 'HY000'
     ('ER_TRUNCATED_WRONG_VALUE_FOR_FIELD')

     Message: Incorrect %s value: '%s' for column '%s' at row %ld

   *
     Error: '1367' SQLSTATE: '22007' ('ER_ILLEGAL_VALUE_FOR_TYPE')

     Message: Illegal %s '%s' value found during parsing

   *
     Error: '1368' SQLSTATE: 'HY000' ('ER_VIEW_NONUPD_CHECK')

     Message: CHECK OPTION on non-updatable view '%s.%s'

   *
     Error: '1369' SQLSTATE: 'HY000' ('ER_VIEW_CHECK_FAILED')

     Message: CHECK OPTION failed '%s.%s'

   *
     Error: '1370' SQLSTATE: '42000' ('ER_PROCACCESS_DENIED_ERROR')

     Message: %s command denied to user '%s'@'%s' for routine '%s'

   *
     Error: '1371' SQLSTATE: 'HY000' ('ER_RELAY_LOG_FAIL')

     Message: Failed purging old relay logs: %s

   *
     Error: '1372' SQLSTATE: 'HY000' ('ER_PASSWD_LENGTH')

     Message: Password hash should be a %d-digit hexadecimal number

   *
     Error: '1373' SQLSTATE: 'HY000' ('ER_UNKNOWN_TARGET_BINLOG')

     Message: Target log not found in binlog index

   *
     Error: '1374' SQLSTATE: 'HY000' ('ER_IO_ERR_LOG_INDEX_READ')

     Message: I/O error reading log index file

   *
     Error: '1375' SQLSTATE: 'HY000' ('ER_BINLOG_PURGE_PROHIBITED')

     Message: Server configuration does not permit binlog purge

   *
     Error: '1376' SQLSTATE: 'HY000' ('ER_FSEEK_FAIL')

     Message: Failed on fseek()

   *
     Error: '1377' SQLSTATE: 'HY000' ('ER_BINLOG_PURGE_FATAL_ERR')

     Message: Fatal error during log purge

   *
     Error: '1378' SQLSTATE: 'HY000' ('ER_LOG_IN_USE')

     Message: A purgeable log is in use, will not purge

   *
     Error: '1379' SQLSTATE: 'HY000' ('ER_LOG_PURGE_UNKNOWN_ERR')

     Message: Unknown error during log purge

   *
     Error: '1380' SQLSTATE: 'HY000' ('ER_RELAY_LOG_INIT')

     Message: Failed initializing relay log position: %s

   *
     Error: '1381' SQLSTATE: 'HY000' ('ER_NO_BINARY_LOGGING')

     Message: You are not using binary logging

   *
     Error: '1382' SQLSTATE: 'HY000' ('ER_RESERVED_SYNTAX')

     Message: The '%s' syntax is reserved for purposes internal to the
     MySQL server

   *
     Error: '1383' SQLSTATE: 'HY000' ('ER_WSAS_FAILED')

     Message: WSAStartup Failed

   *
     Error: '1384' SQLSTATE: 'HY000' ('ER_DIFF_GROUPS_PROC')

     Message: Can't handle procedures with different groups yet

   *
     Error: '1385' SQLSTATE: 'HY000' ('ER_NO_GROUP_FOR_PROC')

     Message: Select must have a group with this procedure

   *
     Error: '1386' SQLSTATE: 'HY000' ('ER_ORDER_WITH_PROC')

     Message: Can't use ORDER clause with this procedure

   *
     Error: '1387' SQLSTATE: 'HY000' ('ER_LOGGING_PROHIBIT_CHANGING_OF')

     Message: Binary logging and replication forbid changing the global
     server %s

   *
     Error: '1388' SQLSTATE: 'HY000' ('ER_NO_FILE_MAPPING')

     Message: Can't map file: %s, errno: %d

   *
     Error: '1389' SQLSTATE: 'HY000' ('ER_WRONG_MAGIC')

     Message: Wrong magic in %s

   *
     Error: '1390' SQLSTATE: 'HY000' ('ER_PS_MANY_PARAM')

     Message: Prepared statement contains too many placeholders

   *
     Error: '1391' SQLSTATE: 'HY000' ('ER_KEY_PART_0')

     Message: Key part '%s' length cannot be 0

   *
     Error: '1392' SQLSTATE: 'HY000' ('ER_VIEW_CHECKSUM')

     Message: View text checksum failed

   *
     Error: '1393' SQLSTATE: 'HY000' ('ER_VIEW_MULTIUPDATE')

     Message: Can not modify more than one base table through a join
     view '%s.%s'

   *
     Error: '1394' SQLSTATE: 'HY000' ('ER_VIEW_NO_INSERT_FIELD_LIST')

     Message: Can not insert into join view '%s.%s' without fields list

   *
     Error: '1395' SQLSTATE: 'HY000' ('ER_VIEW_DELETE_MERGE_VIEW')

     Message: Can not delete from join view '%s.%s'

   *
     Error: '1396' SQLSTATE: 'HY000' ('ER_CANNOT_USER')

     Message: Operation %s failed for %s

   *
     Error: '1397' SQLSTATE: 'XAE04' ('ER_XAER_NOTA')

     Message: XAER_NOTA: Unknown XID

   *
     Error: '1398' SQLSTATE: 'XAE05' ('ER_XAER_INVAL')

     Message: XAER_INVAL: Invalid arguments (or unsupported command)

   *
     Error: '1399' SQLSTATE: 'XAE07' ('ER_XAER_RMFAIL')

     Message: XAER_RMFAIL: The command cannot be executed when global
     transaction is in the %s state

   *
     Error: '1400' SQLSTATE: 'XAE09' ('ER_XAER_OUTSIDE')

     Message: XAER_OUTSIDE: Some work is done outside global transaction

   *
     Error: '1401' SQLSTATE: 'XAE03' ('ER_XAER_RMERR')

     Message: XAER_RMERR: Fatal error occurred in the transaction branch
     - check your data for consistency

   *
     Error: '1402' SQLSTATE: 'XA100' ('ER_XA_RBROLLBACK')

     Message: XA_RBROLLBACK: Transaction branch was rolled back

   *
     Error: '1403' SQLSTATE: '42000' ('ER_NONEXISTING_PROC_GRANT')

     Message: There is no such grant defined for user '%s' on host '%s'
     on routine '%s'

   *
     Error: '1404' SQLSTATE: 'HY000' ('ER_PROC_AUTO_GRANT_FAIL')

     Message: Failed to grant EXECUTE and ALTER ROUTINE privileges

   *
     Error: '1405' SQLSTATE: 'HY000' ('ER_PROC_AUTO_REVOKE_FAIL')

     Message: Failed to revoke all privileges to dropped routine

   *
     Error: '1406' SQLSTATE: '22001' ('ER_DATA_TOO_LONG')

     Message: Data too long for column '%s' at row %ld

   *
     Error: '1407' SQLSTATE: '42000' ('ER_SP_BAD_SQLSTATE')

     Message: Bad SQLSTATE: '%s'

   *
     Error: '1408' SQLSTATE: 'HY000' ('ER_STARTUP')

     Message: %s: ready for connections.  Version: '%s' socket: '%s'
     port: %d %s

   *
     Error: '1409' SQLSTATE: 'HY000'
     ('ER_LOAD_FROM_FIXED_SIZE_ROWS_TO_VAR')

     Message: Can't load value from file with fixed size rows to
     variable

   *
     Error: '1410' SQLSTATE: '42000' ('ER_CANT_CREATE_USER_WITH_GRANT')

     Message: You are not allowed to create a user with GRANT

   *
     Error: '1411' SQLSTATE: 'HY000' ('ER_WRONG_VALUE_FOR_TYPE')

     Message: Incorrect %s value: '%s' for function %s

   *
     Error: '1412' SQLSTATE: 'HY000' ('ER_TABLE_DEF_CHANGED')

     Message: Table definition has changed, please retry transaction

   *
     Error: '1413' SQLSTATE: '42000' ('ER_SP_DUP_HANDLER')

     Message: Duplicate handler declared in the same block

   *
     Error: '1414' SQLSTATE: '42000' ('ER_SP_NOT_VAR_ARG')

     Message: OUT or INOUT argument %d for routine %s is not a variable
     or NEW pseudo-variable in BEFORE trigger

   *
     Error: '1415' SQLSTATE: '0A000' ('ER_SP_NO_RETSET')

     Message: Not allowed to return a result set from a %s

   *
     Error: '1416' SQLSTATE: '22003' ('ER_CANT_CREATE_GEOMETRY_OBJECT')

     Message: Cannot get geometry object from data you send to the
     GEOMETRY field

   *
     Error: '1417' SQLSTATE: 'HY000' ('ER_FAILED_ROUTINE_BREAK_BINLOG')

     Message: A routine failed and has neither NO SQL nor READS SQL DATA
     in its declaration and binary logging is enabled; if
     non-transactional tables were updated, the binary log will miss
     their changes

   *
     Error: '1418' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_ROUTINE')

     Message: This function has none of DETERMINISTIC, NO SQL, or READS
     SQL DATA in its declaration and binary logging is enabled (you
     *might* want to use the less safe log_bin_trust_function_creators
     variable)

   *
     Error: '1419' SQLSTATE: 'HY000'
     ('ER_BINLOG_CREATE_ROUTINE_NEED_SUPER')

     Message: You do not have the SUPER privilege and binary logging is
     enabled (you *might* want to use the less safe
     log_bin_trust_function_creators variable)

   *
     Error: '1420' SQLSTATE: 'HY000' ('ER_EXEC_STMT_WITH_OPEN_CURSOR')

     Message: You can't execute a prepared statement which has an open
     cursor associated with it.  Reset the statement to re-execute it.

   *
     Error: '1421' SQLSTATE: 'HY000' ('ER_STMT_HAS_NO_OPEN_CURSOR')

     Message: The statement (%lu) has no open cursor.

   *
     Error: '1422' SQLSTATE: 'HY000'
     ('ER_COMMIT_NOT_ALLOWED_IN_SF_OR_TRG')

     Message: Explicit or implicit commit is not allowed in stored
     function or trigger.

   *
     Error: '1423' SQLSTATE: 'HY000' ('ER_NO_DEFAULT_FOR_VIEW_FIELD')

     Message: Field of view '%s.%s' underlying table doesn't have a
     default value

   *
     Error: '1424' SQLSTATE: 'HY000' ('ER_SP_NO_RECURSION')

     Message: Recursive stored functions and triggers are not allowed.

   *
     Error: '1425' SQLSTATE: '42000' ('ER_TOO_BIG_SCALE')

     Message: Too big scale %d specified for column '%s'.  Maximum is
     %lu.

   *
     Error: '1426' SQLSTATE: '42000' ('ER_TOO_BIG_PRECISION')

     Message: Too-big precision %d specified for '%s'.  Maximum is %lu.

   *
     Error: '1427' SQLSTATE: '42000' ('ER_M_BIGGER_THAN_D')

     Message: For float(M,D), double(M,D) or decimal(M,D), M must be >=
     D (column '%s').

   *
     Error: '1428' SQLSTATE: 'HY000' ('ER_WRONG_LOCK_OF_SYSTEM_TABLE')

     Message: You can't combine write-locking of system tables with
     other tables or lock types

   *
     Error: '1429' SQLSTATE: 'HY000'
     ('ER_CONNECT_TO_FOREIGN_DATA_SOURCE')

     Message: Unable to connect to foreign data source: %s

   *
     Error: '1430' SQLSTATE: 'HY000' ('ER_QUERY_ON_FOREIGN_DATA_SOURCE')

     Message: There was a problem processing the query on the foreign
     data source.  Data source error: %s

   *
     Error: '1431' SQLSTATE: 'HY000'
     ('ER_FOREIGN_DATA_SOURCE_DOESNT_EXIST')

     Message: The foreign data source you are trying to reference does
     not exist.  Data source error: %s

   *
     Error: '1432' SQLSTATE: 'HY000'
     ('ER_FOREIGN_DATA_STRING_INVALID_CANT_CREATE')

     Message: Can't create federated table.  The data source connection
     string '%s' is not in the correct format

   *
     Error: '1433' SQLSTATE: 'HY000' ('ER_FOREIGN_DATA_STRING_INVALID')

     Message: The data source connection string '%s' is not in the
     correct format

   *
     Error: '1434' SQLSTATE: 'HY000' ('ER_CANT_CREATE_FEDERATED_TABLE')

     Message: Can't create federated table.  Foreign data src error: %s

   *
     Error: '1435' SQLSTATE: 'HY000' ('ER_TRG_IN_WRONG_SCHEMA')

     Message: Trigger in wrong schema

   *
     Error: '1436' SQLSTATE: 'HY000' ('ER_STACK_OVERRUN_NEED_MORE')

     Message: Thread stack overrun: %ld bytes used of a %ld byte stack,
     and %ld bytes needed.  Use 'mysqld -thread_stack=#' to specify a
     bigger stack.

   *
     Error: '1437' SQLSTATE: '42000' ('ER_TOO_LONG_BODY')

     Message: Routine body for '%s' is too long

   *
     Error: '1438' SQLSTATE: 'HY000'
     ('ER_WARN_CANT_DROP_DEFAULT_KEYCACHE')

     Message: Cannot drop default keycache

   *
     Error: '1439' SQLSTATE: '42000' ('ER_TOO_BIG_DISPLAYWIDTH')

     Message: Display width out of range for column '%s' (max = %lu)

   *
     Error: '1440' SQLSTATE: 'XAE08' ('ER_XAER_DUPID')

     Message: XAER_DUPID: The XID already exists

   *
     Error: '1441' SQLSTATE: '22008' ('ER_DATETIME_FUNCTION_OVERFLOW')

     Message: Datetime function: %s field overflow

   *
     Error: '1442' SQLSTATE: 'HY000'
     ('ER_CANT_UPDATE_USED_TABLE_IN_SF_OR_TRG')

     Message: Can't update table '%s' in stored function/trigger because
     it is already used by statement which invoked this stored
     function/trigger.

   *
     Error: '1443' SQLSTATE: 'HY000' ('ER_VIEW_PREVENT_UPDATE')

     Message: The definition of table '%s' prevents operation %s on
     table '%s'.

   *
     Error: '1444' SQLSTATE: 'HY000' ('ER_PS_NO_RECURSION')

     Message: The prepared statement contains a stored routine call that
     refers to that same statement.  It's not allowed to execute a
     prepared statement in such a recursive manner

   *
     Error: '1445' SQLSTATE: 'HY000' ('ER_SP_CANT_SET_AUTOCOMMIT')

     Message: Not allowed to set autocommit from a stored function or
     trigger

   *
     Error: '1446' SQLSTATE: 'HY000' ('ER_MALFORMED_DEFINER')

     Message: Definer is not fully qualified

   *
     Error: '1447' SQLSTATE: 'HY000' ('ER_VIEW_FRM_NO_USER')

     Message: View '%s'.'%s' has no definer information (old table
     format).  Current user is used as definer.  Please recreate the
     view!

   *
     Error: '1448' SQLSTATE: 'HY000' ('ER_VIEW_OTHER_USER')

     Message: You need the SUPER privilege for creation view with
     '%s'@'%s' definer

   *
     Error: '1449' SQLSTATE: 'HY000' ('ER_NO_SUCH_USER')

     Message: The user specified as a definer ('%s'@'%s') does not exist

   *
     Error: '1450' SQLSTATE: 'HY000' ('ER_FORBID_SCHEMA_CHANGE')

     Message: Changing schema from '%s' to '%s' is not allowed.

   *
     Error: '1451' SQLSTATE: '23000' ('ER_ROW_IS_REFERENCED_2')

     Message: Cannot delete or update a parent row: a foreign key
     constraint fails (%s)

   *
     Error: '1452' SQLSTATE: '23000' ('ER_NO_REFERENCED_ROW_2')

     Message: Cannot add or update a child row: a foreign key constraint
     fails (%s)

   *
     Error: '1453' SQLSTATE: '42000' ('ER_SP_BAD_VAR_SHADOW')

     Message: Variable '%s' must be quoted with '...', or renamed

   *
     Error: '1454' SQLSTATE: 'HY000' ('ER_TRG_NO_DEFINER')

     Message: No definer attribute for trigger '%s'.'%s'.  The trigger
     will be activated under the authorization of the invoker, which may
     have insufficient privileges.  Please recreate the trigger.

   *
     Error: '1455' SQLSTATE: 'HY000' ('ER_OLD_FILE_FORMAT')

     Message: '%s' has an old format, you should re-create the '%s'
     object(s)

   *
     Error: '1456' SQLSTATE: 'HY000' ('ER_SP_RECURSION_LIMIT')

     Message: Recursive limit %d (as set by the max_sp_recursion_depth
     variable) was exceeded for routine %s

   *
     Error: '1457' SQLSTATE: 'HY000' ('ER_SP_PROC_TABLE_CORRUPT')

     Message: Failed to load routine %s.  The table mysql.proc is
     missing, corrupt, or contains bad data (internal code %d)

   *
     Error: '1458' SQLSTATE: '42000' ('ER_SP_WRONG_NAME')

     Message: Incorrect routine name '%s'

   *
     Error: '1459' SQLSTATE: 'HY000' ('ER_TABLE_NEEDS_UPGRADE')

     Message: Table upgrade required.  Please do "REPAIR TABLE '%s'" or
     dump/reload to fix it!

   *
     Error: '1460' SQLSTATE: '42000' ('ER_SP_NO_AGGREGATE')

     Message: AGGREGATE is not supported for stored functions

   *
     Error: '1461' SQLSTATE: '42000'
     ('ER_MAX_PREPARED_STMT_COUNT_REACHED')

     Message: Can't create more than max_prepared_stmt_count statements
     (current value: %lu)

   *
     Error: '1462' SQLSTATE: 'HY000' ('ER_VIEW_RECURSIVE')

     Message: '%s'.'%s' contains view recursion

   *
     Error: '1463' SQLSTATE: '42000' ('ER_NON_GROUPING_FIELD_USED')

     Message: Non-grouping field '%s' is used in %s clause

   *
     Error: '1464' SQLSTATE: 'HY000' ('ER_TABLE_CANT_HANDLE_SPKEYS')

     Message: The used table type doesn't support SPATIAL indexes

   *
     Error: '1465' SQLSTATE: 'HY000' ('ER_NO_TRIGGERS_ON_SYSTEM_SCHEMA')

     Message: Triggers can not be created on system tables

   *
     Error: '1466' SQLSTATE: 'HY000' ('ER_REMOVED_SPACES')

     Message: Leading spaces are removed from name '%s'

   *
     Error: '1467' SQLSTATE: 'HY000' ('ER_AUTOINC_READ_FAILED')

     Message: Failed to read auto-increment value from storage engine

   *
     Error: '1468' SQLSTATE: 'HY000' ('ER_USERNAME')

     Message: user name

   *
     Error: '1469' SQLSTATE: 'HY000' ('ER_HOSTNAME')

     Message: host name

   *
     Error: '1470' SQLSTATE: 'HY000' ('ER_WRONG_STRING_LENGTH')

     Message: String '%s' is too long for %s (should be no longer than
     %d)

   *
     Error: '1471' SQLSTATE: 'HY000' ('ER_NON_INSERTABLE_TABLE')

     Message: The target table %s of the %s is not insertable-into

   *
     Error: '1472' SQLSTATE: 'HY000' ('ER_ADMIN_WRONG_MRG_TABLE')

     Message: Table '%s' is differently defined or of non-MyISAM type or
     doesn't exist

   *
     Error: '1473' SQLSTATE: 'HY000'
     ('ER_TOO_HIGH_LEVEL_OF_NESTING_FOR_SELECT')

     Message: Too high level of nesting for select

   *
     Error: '1474' SQLSTATE: 'HY000' ('ER_NAME_BECOMES_EMPTY')

     Message: Name '%s' has become "

   *
     Error: '1475' SQLSTATE: 'HY000' ('ER_AMBIGUOUS_FIELD_TERM')

     Message: First character of the FIELDS TERMINATED string is
     ambiguous; please use non-optional and non-empty FIELDS ENCLOSED BY

   *
     Error: '1476' SQLSTATE: 'HY000' ('ER_FOREIGN_SERVER_EXISTS')

     Message: The foreign server, %s, you are trying to create already
     exists.

   *
     Error: '1477' SQLSTATE: 'HY000' ('ER_FOREIGN_SERVER_DOESNT_EXIST')

     Message: The foreign server name you are trying to reference does
     not exist.  Data source error: %s

   *
     Error: '1478' SQLSTATE: 'HY000' ('ER_ILLEGAL_HA_CREATE_OPTION')

     Message: Table storage engine '%s' does not support the create
     option '%s'

   *
     Error: '1479' SQLSTATE: 'HY000'
     ('ER_PARTITION_REQUIRES_VALUES_ERROR')

     Message: Syntax error: %s PARTITIONING requires definition of
     VALUES %s for each partition

   *
     Error: '1480' SQLSTATE: 'HY000' ('ER_PARTITION_WRONG_VALUES_ERROR')

     Message: Only %s PARTITIONING can use VALUES %s in partition
     definition

   *
     Error: '1481' SQLSTATE: 'HY000' ('ER_PARTITION_MAXVALUE_ERROR')

     Message: MAXVALUE can only be used in last partition definition

   *
     Error: '1482' SQLSTATE: 'HY000' ('ER_PARTITION_SUBPARTITION_ERROR')

     Message: Subpartitions can only be hash partitions and by key

   *
     Error: '1483' SQLSTATE: 'HY000' ('ER_PARTITION_SUBPART_MIX_ERROR')

     Message: Must define subpartitions on all partitions if on one
     partition

   *
     Error: '1484' SQLSTATE: 'HY000'
     ('ER_PARTITION_WRONG_NO_PART_ERROR')

     Message: Wrong number of partitions defined, mismatch with previous
     setting

   *
     Error: '1485' SQLSTATE: 'HY000'
     ('ER_PARTITION_WRONG_NO_SUBPART_ERROR')

     Message: Wrong number of subpartitions defined, mismatch with
     previous setting

   *
     Error: '1486' SQLSTATE: 'HY000'
     ('ER_WRONG_EXPR_IN_PARTITION_FUNC_ERROR')

     Message: Constant, random or timezone-dependent expressions in
     (sub)partitioning function are not allowed

   *
     Error: '1487' SQLSTATE: 'HY000'
     ('ER_NO_CONST_EXPR_IN_RANGE_OR_LIST_ERROR')

     Message: Expression in RANGE/LIST VALUES must be constant

   *
     Error: '1488' SQLSTATE: 'HY000' ('ER_FIELD_NOT_FOUND_PART_ERROR')

     Message: Field in list of fields for partition function not found
     in table

   *
     Error: '1489' SQLSTATE: 'HY000'
     ('ER_LIST_OF_FIELDS_ONLY_IN_HASH_ERROR')

     Message: List of fields is only allowed in KEY partitions

   *
     Error: '1490' SQLSTATE: 'HY000'
     ('ER_INCONSISTENT_PARTITION_INFO_ERROR')

     Message: The partition info in the frm file is not consistent with
     what can be written into the frm file

   *
     Error: '1491' SQLSTATE: 'HY000'
     ('ER_PARTITION_FUNC_NOT_ALLOWED_ERROR')

     Message: The %s function returns the wrong type

   *
     Error: '1492' SQLSTATE: 'HY000'
     ('ER_PARTITIONS_MUST_BE_DEFINED_ERROR')

     Message: For %s partitions each partition must be defined

   *
     Error: '1493' SQLSTATE: 'HY000' ('ER_RANGE_NOT_INCREASING_ERROR')

     Message: VALUES LESS THAN value must be strictly increasing for
     each partition

   *
     Error: '1494' SQLSTATE: 'HY000'
     ('ER_INCONSISTENT_TYPE_OF_FUNCTIONS_ERROR')

     Message: VALUES value must be of same type as partition function

   *
     Error: '1495' SQLSTATE: 'HY000'
     ('ER_MULTIPLE_DEF_CONST_IN_LIST_PART_ERROR')

     Message: Multiple definition of same constant in list partitioning

   *
     Error: '1496' SQLSTATE: 'HY000' ('ER_PARTITION_ENTRY_ERROR')

     Message: Partitioning can not be used stand-alone in query

   *
     Error: '1497' SQLSTATE: 'HY000' ('ER_MIX_HANDLER_ERROR')

     Message: The mix of handlers in the partitions is not allowed in
     this version of MySQL

   *
     Error: '1498' SQLSTATE: 'HY000' ('ER_PARTITION_NOT_DEFINED_ERROR')

     Message: For the partitioned engine it is necessary to define all
     %s

   *
     Error: '1499' SQLSTATE: 'HY000' ('ER_TOO_MANY_PARTITIONS_ERROR')

     Message: Too many partitions (including subpartitions) were defined

   *
     Error: '1500' SQLSTATE: 'HY000' ('ER_SUBPARTITION_ERROR')

     Message: It is only possible to mix RANGE/LIST partitioning with
     HASH/KEY partitioning for subpartitioning

   *
     Error: '1501' SQLSTATE: 'HY000' ('ER_CANT_CREATE_HANDLER_FILE')

     Message: Failed to create specific handler file

   *
     Error: '1502' SQLSTATE: 'HY000'
     ('ER_BLOB_FIELD_IN_PART_FUNC_ERROR')

     Message: A BLOB field is not allowed in partition function

   *
     Error: '1503' SQLSTATE: 'HY000'
     ('ER_UNIQUE_KEY_NEED_ALL_FIELDS_IN_PF')

     Message: A %s must include all columns in the table's partitioning
     function

   *
     Error: '1504' SQLSTATE: 'HY000' ('ER_NO_PARTS_ERROR')

     Message: Number of %s = 0 is not an allowed value

   *
     Error: '1505' SQLSTATE: 'HY000'
     ('ER_PARTITION_MGMT_ON_NONPARTITIONED')

     Message: Partition management on a not partitioned table is not
     possible

   *
     Error: '1506' SQLSTATE: 'HY000' ('ER_FOREIGN_KEY_ON_PARTITIONED')

     Message: Foreign keys are not yet supported in conjunction with
     partitioning

   *
     Error: '1507' SQLSTATE: 'HY000' ('ER_DROP_PARTITION_NON_EXISTENT')

     Message: Error in list of partitions to %s

   *
     Error: '1508' SQLSTATE: 'HY000' ('ER_DROP_LAST_PARTITION')

     Message: Cannot remove all partitions, use DROP TABLE instead

   *
     Error: '1509' SQLSTATE: 'HY000'
     ('ER_COALESCE_ONLY_ON_HASH_PARTITION')

     Message: COALESCE PARTITION can only be used on HASH/KEY partitions

   *
     Error: '1510' SQLSTATE: 'HY000' ('ER_REORG_HASH_ONLY_ON_SAME_NO')

     Message: REORGANIZE PARTITION can only be used to reorganize
     partitions not to change their numbers

   *
     Error: '1511' SQLSTATE: 'HY000' ('ER_REORG_NO_PARAM_ERROR')

     Message: REORGANIZE PARTITION without parameters can only be used
     on auto-partitioned tables using HASH PARTITIONs

   *
     Error: '1512' SQLSTATE: 'HY000' ('ER_ONLY_ON_RANGE_LIST_PARTITION')

     Message: %s PARTITION can only be used on RANGE/LIST partitions

   *
     Error: '1513' SQLSTATE: 'HY000' ('ER_ADD_PARTITION_SUBPART_ERROR')

     Message: Trying to Add partition(s) with wrong number of
     subpartitions

   *
     Error: '1514' SQLSTATE: 'HY000'
     ('ER_ADD_PARTITION_NO_NEW_PARTITION')

     Message: At least one partition must be added

   *
     Error: '1515' SQLSTATE: 'HY000'
     ('ER_COALESCE_PARTITION_NO_PARTITION')

     Message: At least one partition must be coalesced

   *
     Error: '1516' SQLSTATE: 'HY000' ('ER_REORG_PARTITION_NOT_EXIST')

     Message: More partitions to reorganize than there are partitions

   *
     Error: '1517' SQLSTATE: 'HY000' ('ER_SAME_NAME_PARTITION')

     Message: Duplicate partition name %s

   *
     Error: '1518' SQLSTATE: 'HY000' ('ER_NO_BINLOG_ERROR')

     Message: It is not allowed to shut off binlog on this command

   *
     Error: '1519' SQLSTATE: 'HY000' ('ER_CONSECUTIVE_REORG_PARTITIONS')

     Message: When reorganizing a set of partitions they must be in
     consecutive order

   *
     Error: '1520' SQLSTATE: 'HY000' ('ER_REORG_OUTSIDE_RANGE')

     Message: Reorganize of range partitions cannot change total ranges
     except for last partition where it can extend the range

   *
     Error: '1521' SQLSTATE: 'HY000' ('ER_PARTITION_FUNCTION_FAILURE')

     Message: Partition function not supported in this version for this
     handler

   *
     Error: '1522' SQLSTATE: 'HY000' ('ER_PART_STATE_ERROR')

     Message: Partition state cannot be defined from CREATE/ALTER TABLE

   *
     Error: '1523' SQLSTATE: 'HY000' ('ER_LIMITED_PART_RANGE')

     Message: The %s handler only supports 32 bit integers in VALUES

   *
     Error: '1524' SQLSTATE: 'HY000' ('ER_PLUGIN_IS_NOT_LOADED')

     Message: Plugin '%s' is not loaded

   *
     Error: '1525' SQLSTATE: 'HY000' ('ER_WRONG_VALUE')

     Message: Incorrect %s value: '%s'

   *
     Error: '1526' SQLSTATE: 'HY000' ('ER_NO_PARTITION_FOR_GIVEN_VALUE')

     Message: Table has no partition for value %s

   *
     Error: '1527' SQLSTATE: 'HY000' ('ER_FILEGROUP_OPTION_ONLY_ONCE')

     Message: It is not allowed to specify %s more than once

   *
     Error: '1528' SQLSTATE: 'HY000' ('ER_CREATE_FILEGROUP_FAILED')

     Message: Failed to create %s

   *
     Error: '1529' SQLSTATE: 'HY000' ('ER_DROP_FILEGROUP_FAILED')

     Message: Failed to drop %s

   *
     Error: '1530' SQLSTATE: 'HY000' ('ER_TABLESPACE_AUTO_EXTEND_ERROR')

     Message: The handler doesn't support autoextend of tablespaces

   *
     Error: '1531' SQLSTATE: 'HY000' ('ER_WRONG_SIZE_NUMBER')

     Message: A size parameter was incorrectly specified, either number
     or on the form 10M

   *
     Error: '1532' SQLSTATE: 'HY000' ('ER_SIZE_OVERFLOW_ERROR')

     Message: The size number was correct but we don't allow the digit
     part to be more than 2 billion

   *
     Error: '1533' SQLSTATE: 'HY000' ('ER_ALTER_FILEGROUP_FAILED')

     Message: Failed to alter: %s

   *
     Error: '1534' SQLSTATE: 'HY000' ('ER_BINLOG_ROW_LOGGING_FAILED')

     Message: Writing one row to the row-based binary log failed

   *
     Error: '1535' SQLSTATE: 'HY000' ('ER_BINLOG_ROW_WRONG_TABLE_DEF')

     Message: Table definition on master and slave does not match: %s

   *
     Error: '1536' SQLSTATE: 'HY000' ('ER_BINLOG_ROW_RBR_TO_SBR')

     Message: Slave running with -log-slave-updates must use row-based
     binary logging to be able to replicate row-based binary log events

   *
     Error: '1537' SQLSTATE: 'HY000' ('ER_EVENT_ALREADY_EXISTS')

     Message: Event '%s' already exists

   *
     Error: '1538' SQLSTATE: 'HY000' ('ER_EVENT_STORE_FAILED')

     Message: Failed to store event %s.  Error code %d from storage
     engine.

   *
     Error: '1539' SQLSTATE: 'HY000' ('ER_EVENT_DOES_NOT_EXIST')

     Message: Unknown event '%s'

   *
     Error: '1540' SQLSTATE: 'HY000' ('ER_EVENT_CANT_ALTER')

     Message: Failed to alter event '%s'

   *
     Error: '1541' SQLSTATE: 'HY000' ('ER_EVENT_DROP_FAILED')

     Message: Failed to drop %s

   *
     Error: '1542' SQLSTATE: 'HY000'
     ('ER_EVENT_INTERVAL_NOT_POSITIVE_OR_TOO_BIG')

     Message: INTERVAL is either not positive or too big

   *
     Error: '1543' SQLSTATE: 'HY000' ('ER_EVENT_ENDS_BEFORE_STARTS')

     Message: ENDS is either invalid or before STARTS

   *
     Error: '1544' SQLSTATE: 'HY000' ('ER_EVENT_EXEC_TIME_IN_THE_PAST')

     Message: Event execution time is in the past.  Event has been
     disabled

   *
     Error: '1545' SQLSTATE: 'HY000' ('ER_EVENT_OPEN_TABLE_FAILED')

     Message: Failed to open mysql.event

   *
     Error: '1546' SQLSTATE: 'HY000'
     ('ER_EVENT_NEITHER_M_EXPR_NOR_M_AT')

     Message: No datetime expression provided

   *
     Error: '1547' SQLSTATE: 'HY000'
     ('ER_OBSOLETE_COL_COUNT_DOESNT_MATCH_CORRUPTED')

     Message: Column count of mysql.%s is wrong.  Expected %d, found %d.
     The table is probably corrupted

   *
     Error: '1548' SQLSTATE: 'HY000'
     ('ER_OBSOLETE_CANNOT_LOAD_FROM_TABLE')

     Message: Cannot load from mysql.%s.  The table is probably
     corrupted

   *
     Error: '1549' SQLSTATE: 'HY000' ('ER_EVENT_CANNOT_DELETE')

     Message: Failed to delete the event from mysql.event

   *
     Error: '1550' SQLSTATE: 'HY000' ('ER_EVENT_COMPILE_ERROR')

     Message: Error during compilation of event's body

   *
     Error: '1551' SQLSTATE: 'HY000' ('ER_EVENT_SAME_NAME')

     Message: Same old and new event name

   *
     Error: '1552' SQLSTATE: 'HY000' ('ER_EVENT_DATA_TOO_LONG')

     Message: Data for column '%s' too long

   *
     Error: '1553' SQLSTATE: 'HY000' ('ER_DROP_INDEX_FK')

     Message: Cannot drop index '%s': needed in a foreign key constraint

     'InnoDB' reports this error when you attempt to drop the last index
     that can enforce a particular referential constraint.

     For optimal performance with DML statements, 'InnoDB' requires an
     index to exist on foreign key columns, so that 'UPDATE' and
     'DELETE' operations on a parent table can easily check whether
     corresponding rows exist in the child table.  MySQL creates or
     drops such indexes automatically when needed, as a side-effect of
     'CREATE TABLE', 'CREATE INDEX',
     and 'ALTER TABLE' statements.

     When you drop an index, 'InnoDB' checks if the index is used for
     checking a foreign key constraint.  It is still OK to drop the
     index if there is another index that can be used to enforce the
     same constraint.  'InnoDB' prevents you from dropping the last
     index that can enforce a particular referential constraint.

   *
     Error: '1554' SQLSTATE: 'HY000'
     ('ER_WARN_DEPRECATED_SYNTAX_WITH_VER')

     Message: The syntax '%s' is deprecated and will be removed in MySQL
     %s.  Please use %s instead

   *
     Error: '1555' SQLSTATE: 'HY000' ('ER_CANT_WRITE_LOCK_LOG_TABLE')

     Message: You can't write-lock a log table.  Only read access is
     possible

   *
     Error: '1556' SQLSTATE: 'HY000' ('ER_CANT_LOCK_LOG_TABLE')

     Message: You can't use locks with log tables.

   *
     Error: '1557' SQLSTATE: '23000'
     ('ER_FOREIGN_DUPLICATE_KEY_OLD_UNUSED')

     Message: Upholding foreign key constraints for table '%s', entry
     '%s', key %d would lead to a duplicate entry

   *
     Error: '1558' SQLSTATE: 'HY000'
     ('ER_COL_COUNT_DOESNT_MATCH_PLEASE_UPDATE')

     Message: Column count of mysql.%s is wrong.  Expected %d, found %d.
     Created with MySQL %d, now running %d.  Please use mysql_upgrade to
     fix this error.

   *
     Error: '1559' SQLSTATE: 'HY000'
     ('ER_TEMP_TABLE_PREVENTS_SWITCH_OUT_OF_RBR')

     Message: Cannot switch out of the row-based binary log format when
     the session has open temporary tables

   *
     Error: '1560' SQLSTATE: 'HY000'
     ('ER_STORED_FUNCTION_PREVENTS_SWITCH_BINLOG_FORMAT')

     Message: Cannot change the binary logging format inside a stored
     function or trigger

   *
     Error: '1561' SQLSTATE: 'HY000'
     ('ER_NDB_CANT_SWITCH_BINLOG_FORMAT')

     Message: The NDB cluster engine does not support changing the
     binlog format on the fly yet

   *
     Error: '1562' SQLSTATE: 'HY000' ('ER_PARTITION_NO_TEMPORARY')

     Message: Cannot create temporary table with partitions

   *
     Error: '1563' SQLSTATE: 'HY000' ('ER_PARTITION_CONST_DOMAIN_ERROR')

     Message: Partition constant is out of partition function domain

   *
     Error: '1564' SQLSTATE: 'HY000'
     ('ER_PARTITION_FUNCTION_IS_NOT_ALLOWED')

     Message: This partition function is not allowed

   *
     Error: '1565' SQLSTATE: 'HY000' ('ER_DDL_LOG_ERROR')

     Message: Error in DDL log

   *
     Error: '1566' SQLSTATE: 'HY000' ('ER_NULL_IN_VALUES_LESS_THAN')

     Message: Not allowed to use NULL value in VALUES LESS THAN

   *
     Error: '1567' SQLSTATE: 'HY000' ('ER_WRONG_PARTITION_NAME')

     Message: Incorrect partition name

   *
     Error: '1568' SQLSTATE: '25001'
     ('ER_CANT_CHANGE_TX_CHARACTERISTICS')

     Message: Transaction characteristics can't be changed while a
     transaction is in progress

   *
     Error: '1569' SQLSTATE: 'HY000' ('ER_DUP_ENTRY_AUTOINCREMENT_CASE')

     Message: ALTER TABLE causes auto_increment resequencing, resulting
     in duplicate entry '%s' for key '%s'

   *
     Error: '1570' SQLSTATE: 'HY000' ('ER_EVENT_MODIFY_QUEUE_ERROR')

     Message: Internal scheduler error %d

   *
     Error: '1571' SQLSTATE: 'HY000' ('ER_EVENT_SET_VAR_ERROR')

     Message: Error during starting/stopping of the scheduler.  Error
     code %u

   *
     Error: '1572' SQLSTATE: 'HY000' ('ER_PARTITION_MERGE_ERROR')

     Message: Engine cannot be used in partitioned tables

   *
     Error: '1573' SQLSTATE: 'HY000' ('ER_CANT_ACTIVATE_LOG')

     Message: Cannot activate '%s' log

   *
     Error: '1574' SQLSTATE: 'HY000' ('ER_RBR_NOT_AVAILABLE')

     Message: The server was not built with row-based replication

   *
     Error: '1575' SQLSTATE: 'HY000' ('ER_BASE64_DECODE_ERROR')

     Message: Decoding of base64 string failed

   *
     Error: '1576' SQLSTATE: 'HY000' ('ER_EVENT_RECURSION_FORBIDDEN')

     Message: Recursion of EVENT DDL statements is forbidden when body
     is present

   *
     Error: '1577' SQLSTATE: 'HY000' ('ER_EVENTS_DB_ERROR')

     Message: Cannot proceed because system tables used by Event
     Scheduler were found damaged at server start

     To address this issue, try running 'mysql_upgrade'.

   *
     Error: '1578' SQLSTATE: 'HY000' ('ER_ONLY_INTEGERS_ALLOWED')

     Message: Only integers allowed as number here

   *
     Error: '1579' SQLSTATE: 'HY000' ('ER_UNSUPORTED_LOG_ENGINE')

     Message: This storage engine cannot be used for log tables"

   *
     Error: '1580' SQLSTATE: 'HY000' ('ER_BAD_LOG_STATEMENT')

     Message: You cannot '%s' a log table if logging is enabled

   *
     Error: '1581' SQLSTATE: 'HY000' ('ER_CANT_RENAME_LOG_TABLE')

     Message: Cannot rename '%s'.  When logging enabled, rename to/from
     log table must rename two tables: the log table to an archive table
     and another table back to '%s'

   *
     Error: '1582' SQLSTATE: '42000'
     ('ER_WRONG_PARAMCOUNT_TO_NATIVE_FCT')

     Message: Incorrect parameter count in the call to native function
     '%s'

   *
     Error: '1583' SQLSTATE: '42000'
     ('ER_WRONG_PARAMETERS_TO_NATIVE_FCT')

     Message: Incorrect parameters in the call to native function '%s'

   *
     Error: '1584' SQLSTATE: '42000'
     ('ER_WRONG_PARAMETERS_TO_STORED_FCT')

     Message: Incorrect parameters in the call to stored function %s

   *
     Error: '1585' SQLSTATE: 'HY000' ('ER_NATIVE_FCT_NAME_COLLISION')

     Message: This function '%s' has the same name as a native function

   *
     Error: '1586' SQLSTATE: '23000' ('ER_DUP_ENTRY_WITH_KEY_NAME')

     Message: Duplicate entry '%s' for key '%s'

     The format string for this error is also used with 'ER_DUP_ENTRY'.

   *
     Error: '1587' SQLSTATE: 'HY000' ('ER_BINLOG_PURGE_EMFILE')

     Message: Too many files opened, please execute the command again

   *
     Error: '1588' SQLSTATE: 'HY000'
     ('ER_EVENT_CANNOT_CREATE_IN_THE_PAST')

     Message: Event execution time is in the past and ON COMPLETION NOT
     PRESERVE is set.  The event was dropped immediately after creation.

   *
     Error: '1589' SQLSTATE: 'HY000'
     ('ER_EVENT_CANNOT_ALTER_IN_THE_PAST')

     Message: Event execution time is in the past and ON COMPLETION NOT
     PRESERVE is set.  The event was not changed.  Specify a time in the
     future.

   *
     Error: '1590' SQLSTATE: 'HY000' ('ER_SLAVE_INCIDENT')

     Message: The incident %s occured on the master.  Message: %s

   *
     Error: '1591' SQLSTATE: 'HY000'
     ('ER_NO_PARTITION_FOR_GIVEN_VALUE_SILENT')

     Message: Table has no partition for some existing values

   *
     Error: '1592' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_STATEMENT')

     Message: Unsafe statement written to the binary log using statement
     format since BINLOG_FORMAT = STATEMENT. %s

   *
     Error: '1593' SQLSTATE: 'HY000' ('ER_SLAVE_FATAL_ERROR')

     Message: Fatal error: %s

   *
     Error: '1594' SQLSTATE: 'HY000' ('ER_SLAVE_RELAY_LOG_READ_FAILURE')

     Message: Relay log read failure: %s

   *
     Error: '1595' SQLSTATE: 'HY000'
     ('ER_SLAVE_RELAY_LOG_WRITE_FAILURE')

     Message: Relay log write failure: %s

   *
     Error: '1596' SQLSTATE: 'HY000' ('ER_SLAVE_CREATE_EVENT_FAILURE')

     Message: Failed to create %s

   *
     Error: '1597' SQLSTATE: 'HY000' ('ER_SLAVE_MASTER_COM_FAILURE')

     Message: Master command %s failed: %s

   *
     Error: '1598' SQLSTATE: 'HY000' ('ER_BINLOG_LOGGING_IMPOSSIBLE')

     Message: Binary logging not possible.  Message: %s

   *
     Error: '1599' SQLSTATE: 'HY000' ('ER_VIEW_NO_CREATION_CTX')

     Message: View '%s'.'%s' has no creation context

   *
     Error: '1600' SQLSTATE: 'HY000' ('ER_VIEW_INVALID_CREATION_CTX')

     Message: Creation context of view '%s'.'%s' is invalid

   *
     Error: '1601' SQLSTATE: 'HY000' ('ER_SR_INVALID_CREATION_CTX')

     Message: Creation context of stored routine '%s'.'%s' is invalid

   *
     Error: '1602' SQLSTATE: 'HY000' ('ER_TRG_CORRUPTED_FILE')

     Message: Corrupted TRG file for table '%s'.'%s'

   *
     Error: '1603' SQLSTATE: 'HY000' ('ER_TRG_NO_CREATION_CTX')

     Message: Triggers for table '%s'.'%s' have no creation context

   *
     Error: '1604' SQLSTATE: 'HY000' ('ER_TRG_INVALID_CREATION_CTX')

     Message: Trigger creation context of table '%s'.'%s' is invalid

   *
     Error: '1605' SQLSTATE: 'HY000' ('ER_EVENT_INVALID_CREATION_CTX')

     Message: Creation context of event '%s'.'%s' is invalid

   *
     Error: '1606' SQLSTATE: 'HY000' ('ER_TRG_CANT_OPEN_TABLE')

     Message: Cannot open table for trigger '%s'.'%s'

   *
     Error: '1607' SQLSTATE: 'HY000' ('ER_CANT_CREATE_SROUTINE')

     Message: Cannot create stored routine '%s'.  Check warnings

   *
     Error: '1608' SQLSTATE: 'HY000' ('ER_NEVER_USED')

     Message: Ambiguous slave modes combination.  %s

   *
     Error: '1609' SQLSTATE: 'HY000'
     ('ER_NO_FORMAT_DESCRIPTION_EVENT_BEFORE_BINLOG_STATEMENT')

     Message: The BINLOG statement of type '%s' was not preceded by a
     format description BINLOG statement.

   *
     Error: '1610' SQLSTATE: 'HY000' ('ER_SLAVE_CORRUPT_EVENT')

     Message: Corrupted replication event was detected

   *
     Error: '1611' SQLSTATE: 'HY000' ('ER_LOAD_DATA_INVALID_COLUMN')

     Message: Invalid column reference (%s) in LOAD DATA

     'ER_LOAD_DATA_INVALID_COLUMN' was removed after 5.7.7.

   *
     Error: '1611' SQLSTATE: 'HY000'
     ('ER_LOAD_DATA_INVALID_COLUMN_UNUSED')

     Message: Invalid column reference (%s) in LOAD DATA

     'ER_LOAD_DATA_INVALID_COLUMN_UNUSED' was added in 5.7.8.

   *
     Error: '1612' SQLSTATE: 'HY000' ('ER_LOG_PURGE_NO_FILE')

     Message: Being purged log %s was not found

   *
     Error: '1613' SQLSTATE: 'XA106' ('ER_XA_RBTIMEOUT')

     Message: XA_RBTIMEOUT: Transaction branch was rolled back: took too
     long

   *
     Error: '1614' SQLSTATE: 'XA102' ('ER_XA_RBDEADLOCK')

     Message: XA_RBDEADLOCK: Transaction branch was rolled back:
     deadlock was detected

   *
     Error: '1615' SQLSTATE: 'HY000' ('ER_NEED_REPREPARE')

     Message: Prepared statement needs to be re-prepared

   *
     Error: '1616' SQLSTATE: 'HY000' ('ER_DELAYED_NOT_SUPPORTED')

     Message: DELAYED option not supported for table '%s'

   *
     Error: '1617' SQLSTATE: 'HY000' ('WARN_NO_MASTER_INFO')

     Message: The master info structure does not exist

   *
     Error: '1618' SQLSTATE: 'HY000' ('WARN_OPTION_IGNORED')

     Message: <%s> option ignored

   *
     Error: '1619' SQLSTATE: 'HY000' ('WARN_PLUGIN_DELETE_BUILTIN')

     Message: Built-in plugins cannot be deleted

     'WARN_PLUGIN_DELETE_BUILTIN' was removed after 5.7.4.

   *
     Error: '1619' SQLSTATE: 'HY000' ('ER_PLUGIN_DELETE_BUILTIN')

     Message: Built-in plugins cannot be deleted

     'ER_PLUGIN_DELETE_BUILTIN' was added in 5.7.5.

   *
     Error: '1620' SQLSTATE: 'HY000' ('WARN_PLUGIN_BUSY')

     Message: Plugin is busy and will be uninstalled on shutdown

   *
     Error: '1621' SQLSTATE: 'HY000' ('ER_VARIABLE_IS_READONLY')

     Message: %s variable '%s' is read-only.  Use SET %s to assign the
     value

   *
     Error: '1622' SQLSTATE: 'HY000'
     ('ER_WARN_ENGINE_TRANSACTION_ROLLBACK')

     Message: Storage engine %s does not support rollback for this
     statement.  Transaction rolled back and must be restarted

   *
     Error: '1623' SQLSTATE: 'HY000' ('ER_SLAVE_HEARTBEAT_FAILURE')

     Message: Unexpected master's heartbeat data: %s

   *
     Error: '1624' SQLSTATE: 'HY000'
     ('ER_SLAVE_HEARTBEAT_VALUE_OUT_OF_RANGE')

     Message: The requested value for the heartbeat period is either
     negative or exceeds the maximum allowed (%s seconds).

   *
     Error: '1625' SQLSTATE: 'HY000' ('ER_NDB_REPLICATION_SCHEMA_ERROR')

     Message: Bad schema for mysql.ndb_replication table.  Message: %s

   *
     Error: '1626' SQLSTATE: 'HY000' ('ER_CONFLICT_FN_PARSE_ERROR')

     Message: Error in parsing conflict function.  Message: %s

   *
     Error: '1627' SQLSTATE: 'HY000' ('ER_EXCEPTIONS_WRITE_ERROR')

     Message: Write to exceptions table failed.  Message: %s"

   *
     Error: '1628' SQLSTATE: 'HY000' ('ER_TOO_LONG_TABLE_COMMENT')

     Message: Comment for table '%s' is too long (max = %lu)

   *
     Error: '1629' SQLSTATE: 'HY000' ('ER_TOO_LONG_FIELD_COMMENT')

     Message: Comment for field '%s' is too long (max = %lu)

   *
     Error: '1630' SQLSTATE: '42000'
     ('ER_FUNC_INEXISTENT_NAME_COLLISION')

     Message: FUNCTION %s does not exist.  Check the 'Function Name
     Parsing and Resolution' section in the Reference Manual

   *
     Error: '1631' SQLSTATE: 'HY000' ('ER_DATABASE_NAME')

     Message: Database

   *
     Error: '1632' SQLSTATE: 'HY000' ('ER_TABLE_NAME')

     Message: Table

   *
     Error: '1633' SQLSTATE: 'HY000' ('ER_PARTITION_NAME')

     Message: Partition

   *
     Error: '1634' SQLSTATE: 'HY000' ('ER_SUBPARTITION_NAME')

     Message: Subpartition

   *
     Error: '1635' SQLSTATE: 'HY000' ('ER_TEMPORARY_NAME')

     Message: Temporary

   *
     Error: '1636' SQLSTATE: 'HY000' ('ER_RENAMED_NAME')

     Message: Renamed

   *
     Error: '1637' SQLSTATE: 'HY000' ('ER_TOO_MANY_CONCURRENT_TRXS')

     Message: Too many active concurrent transactions

   *
     Error: '1638' SQLSTATE: 'HY000'
     ('WARN_NON_ASCII_SEPARATOR_NOT_IMPLEMENTED')

     Message: Non-ASCII separator arguments are not fully supported

   *
     Error: '1639' SQLSTATE: 'HY000' ('ER_DEBUG_SYNC_TIMEOUT')

     Message: debug sync point wait timed out

   *
     Error: '1640' SQLSTATE: 'HY000' ('ER_DEBUG_SYNC_HIT_LIMIT')

     Message: debug sync point hit limit reached

   *
     Error: '1641' SQLSTATE: '42000' ('ER_DUP_SIGNAL_SET')

     Message: Duplicate condition information item '%s'

   *
     Error: '1642' SQLSTATE: '01000' ('ER_SIGNAL_WARN')

     Message: Unhandled user-defined warning condition

   *
     Error: '1643' SQLSTATE: '02000' ('ER_SIGNAL_NOT_FOUND')

     Message: Unhandled user-defined not found condition

   *
     Error: '1644' SQLSTATE: 'HY000' ('ER_SIGNAL_EXCEPTION')

     Message: Unhandled user-defined exception condition

   *
     Error: '1645' SQLSTATE: '0K000'
     ('ER_RESIGNAL_WITHOUT_ACTIVE_HANDLER')

     Message: RESIGNAL when handler not active

   *
     Error: '1646' SQLSTATE: 'HY000' ('ER_SIGNAL_BAD_CONDITION_TYPE')

     Message: SIGNAL/RESIGNAL can only use a CONDITION defined with
     SQLSTATE

   *
     Error: '1647' SQLSTATE: 'HY000' ('WARN_COND_ITEM_TRUNCATED')

     Message: Data truncated for condition item '%s'

   *
     Error: '1648' SQLSTATE: 'HY000' ('ER_COND_ITEM_TOO_LONG')

     Message: Data too long for condition item '%s'

   *
     Error: '1649' SQLSTATE: 'HY000' ('ER_UNKNOWN_LOCALE')

     Message: Unknown locale: '%s'

   *
     Error: '1650' SQLSTATE: 'HY000' ('ER_SLAVE_IGNORE_SERVER_IDS')

     Message: The requested server id %d clashes with the slave startup
     option -replicate-same-server-id

   *
     Error: '1651' SQLSTATE: 'HY000' ('ER_QUERY_CACHE_DISABLED')

     Message: Query cache is disabled; restart the server with
     query_cache_type=1 to enable it

   *
     Error: '1652' SQLSTATE: 'HY000' ('ER_SAME_NAME_PARTITION_FIELD')

     Message: Duplicate partition field name '%s'

   *
     Error: '1653' SQLSTATE: 'HY000' ('ER_PARTITION_COLUMN_LIST_ERROR')

     Message: Inconsistency in usage of column lists for partitioning

   *
     Error: '1654' SQLSTATE: 'HY000'
     ('ER_WRONG_TYPE_COLUMN_VALUE_ERROR')

     Message: Partition column values of incorrect type

   *
     Error: '1655' SQLSTATE: 'HY000'
     ('ER_TOO_MANY_PARTITION_FUNC_FIELDS_ERROR')

     Message: Too many fields in '%s'

   *
     Error: '1656' SQLSTATE: 'HY000' ('ER_MAXVALUE_IN_VALUES_IN')

     Message: Cannot use MAXVALUE as value in VALUES IN

   *
     Error: '1657' SQLSTATE: 'HY000' ('ER_TOO_MANY_VALUES_ERROR')

     Message: Cannot have more than one value for this type of %s
     partitioning

   *
     Error: '1658' SQLSTATE: 'HY000'
     ('ER_ROW_SINGLE_PARTITION_FIELD_ERROR')

     Message: Row expressions in VALUES IN only allowed for multi-field
     column partitioning

   *
     Error: '1659' SQLSTATE: 'HY000'
     ('ER_FIELD_TYPE_NOT_ALLOWED_AS_PARTITION_FIELD')

     Message: Field '%s' is of a not allowed type for this type of
     partitioning

   *
     Error: '1660' SQLSTATE: 'HY000' ('ER_PARTITION_FIELDS_TOO_LONG')

     Message: The total length of the partitioning fields is too large

   *
     Error: '1661' SQLSTATE: 'HY000'
     ('ER_BINLOG_ROW_ENGINE_AND_STMT_ENGINE')

     Message: Cannot execute statement: impossible to write to binary
     log since both row-incapable engines and statement-incapable
     engines are involved.

   *
     Error: '1662' SQLSTATE: 'HY000'
     ('ER_BINLOG_ROW_MODE_AND_STMT_ENGINE')

     Message: Cannot execute statement: impossible to write to binary
     log since BINLOG_FORMAT = ROW and at least one table uses a storage
     engine limited to statement-based logging.

   *
     Error: '1663' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_AND_STMT_ENGINE')

     Message: Cannot execute statement: impossible to write to binary
     log since statement is unsafe, storage engine is limited to
     statement-based logging, and BINLOG_FORMAT = MIXED. %s

   *
     Error: '1664' SQLSTATE: 'HY000'
     ('ER_BINLOG_ROW_INJECTION_AND_STMT_ENGINE')

     Message: Cannot execute statement: impossible to write to binary
     log since statement is in row format and at least one table uses a
     storage engine limited to statement-based logging.

   *
     Error: '1665' SQLSTATE: 'HY000'
     ('ER_BINLOG_STMT_MODE_AND_ROW_ENGINE')

     Message: Cannot execute statement: impossible to write to binary
     log since BINLOG_FORMAT = STATEMENT and at least one table uses a
     storage engine limited to row-based logging.%s

   *
     Error: '1666' SQLSTATE: 'HY000'
     ('ER_BINLOG_ROW_INJECTION_AND_STMT_MODE')

     Message: Cannot execute statement: impossible to write to binary
     log since statement is in row format and BINLOG_FORMAT = STATEMENT.

   *
     Error: '1667' SQLSTATE: 'HY000'
     ('ER_BINLOG_MULTIPLE_ENGINES_AND_SELF_LOGGING_ENGINE')

     Message: Cannot execute statement: impossible to write to binary
     log since more than one engine is involved and at least one engine
     is self-logging.

   *
     Error: '1668' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_LIMIT')

     Message: The statement is unsafe because it uses a LIMIT clause.
     This is unsafe because the set of rows included cannot be
     predicted.

   *
     Error: '1669' SQLSTATE: 'HY000' ('ER_UNUSED4')

     Message: The statement is unsafe because it uses INSERT DELAYED.
     This is unsafe because the times when rows are inserted cannot be
     predicted.

   *
     Error: '1670' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_SYSTEM_TABLE')

     Message: The statement is unsafe because it uses the general log,
     slow query log, or performance_schema table(s).  This is unsafe
     because system tables may differ on slaves.

   *
     Error: '1671' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_AUTOINC_COLUMNS')

     Message: Statement is unsafe because it invokes a trigger or a
     stored function that inserts into an AUTO_INCREMENT column.
     Inserted values cannot be logged correctly.

   *
     Error: '1672' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_UDF')

     Message: Statement is unsafe because it uses a UDF which may not
     return the same value on the slave.

   *
     Error: '1673' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_SYSTEM_VARIABLE')

     Message: Statement is unsafe because it uses a system variable that
     may have a different value on the slave.

   *
     Error: '1674' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_SYSTEM_FUNCTION')

     Message: Statement is unsafe because it uses a system function that
     may return a different value on the slave.

   *
     Error: '1675' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_NONTRANS_AFTER_TRANS')

     Message: Statement is unsafe because it accesses a
     non-transactional table after accessing a transactional table
     within the same transaction.

   *
     Error: '1676' SQLSTATE: 'HY000' ('ER_MESSAGE_AND_STATEMENT')

     Message: %s Statement: %s

   *
     Error: '1677' SQLSTATE: 'HY000' ('ER_SLAVE_CONVERSION_FAILED')

     Message: Column %d of table '%s.%s' cannot be converted from type
     '%s' to type '%s'

   *
     Error: '1678' SQLSTATE: 'HY000' ('ER_SLAVE_CANT_CREATE_CONVERSION')

     Message: Can't create conversion table for table '%s.%s'

   *
     Error: '1679' SQLSTATE: 'HY000'
     ('ER_INSIDE_TRANSACTION_PREVENTS_SWITCH_BINLOG_FORMAT')

     Message: Cannot modify @@session.binlog_format inside a transaction

   *
     Error: '1680' SQLSTATE: 'HY000' ('ER_PATH_LENGTH')

     Message: The path specified for %s is too long.

   *
     Error: '1681' SQLSTATE: 'HY000'
     ('ER_WARN_DEPRECATED_SYNTAX_NO_REPLACEMENT')

     Message: '%s' is deprecated and will be removed in a future
     release.

   *
     Error: '1682' SQLSTATE: 'HY000' ('ER_WRONG_NATIVE_TABLE_STRUCTURE')

     Message: Native table '%s'.'%s' has the wrong structure

   *
     Error: '1683' SQLSTATE: 'HY000' ('ER_WRONG_PERFSCHEMA_USAGE')

     Message: Invalid performance_schema usage.

   *
     Error: '1684' SQLSTATE: 'HY000' ('ER_WARN_I_S_SKIPPED_TABLE')

     Message: Table '%s'.'%s' was skipped since its definition is being
     modified by concurrent DDL statement

   *
     Error: '1685' SQLSTATE: 'HY000'
     ('ER_INSIDE_TRANSACTION_PREVENTS_SWITCH_BINLOG_DIRECT')

     Message: Cannot modify
     @@session.binlog_direct_non_transactional_updates inside a
     transaction

   *
     Error: '1686' SQLSTATE: 'HY000'
     ('ER_STORED_FUNCTION_PREVENTS_SWITCH_BINLOG_DIRECT')

     Message: Cannot change the binlog direct flag inside a stored
     function or trigger

   *
     Error: '1687' SQLSTATE: '42000' ('ER_SPATIAL_MUST_HAVE_GEOM_COL')

     Message: A SPATIAL index may only contain a geometrical type column

   *
     Error: '1688' SQLSTATE: 'HY000' ('ER_TOO_LONG_INDEX_COMMENT')

     Message: Comment for index '%s' is too long (max = %lu)

   *
     Error: '1689' SQLSTATE: 'HY000' ('ER_LOCK_ABORTED')

     Message: Wait on a lock was aborted due to a pending exclusive lock

   *
     Error: '1690' SQLSTATE: '22003' ('ER_DATA_OUT_OF_RANGE')

     Message: %s value is out of range in '%s'

   *
     Error: '1691' SQLSTATE: 'HY000' ('ER_WRONG_SPVAR_TYPE_IN_LIMIT')

     Message: A variable of a non-integer based type in LIMIT clause

   *
     Error: '1692' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_MULTIPLE_ENGINES_AND_SELF_LOGGING_ENGINE')

     Message: Mixing self-logging and non-self-logging engines in a
     statement is unsafe.

   *
     Error: '1693' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_MIXED_STATEMENT')

     Message: Statement accesses nontransactional table as well as
     transactional or temporary table, and writes to any of them.

   *
     Error: '1694' SQLSTATE: 'HY000'
     ('ER_INSIDE_TRANSACTION_PREVENTS_SWITCH_SQL_LOG_BIN')

     Message: Cannot modify @@session.sql_log_bin inside a transaction

   *
     Error: '1695' SQLSTATE: 'HY000'
     ('ER_STORED_FUNCTION_PREVENTS_SWITCH_SQL_LOG_BIN')

     Message: Cannot change the sql_log_bin inside a stored function or
     trigger

   *
     Error: '1696' SQLSTATE: 'HY000' ('ER_FAILED_READ_FROM_PAR_FILE')

     Message: Failed to read from the .par file

   *
     Error: '1697' SQLSTATE: 'HY000' ('ER_VALUES_IS_NOT_INT_TYPE_ERROR')

     Message: VALUES value for partition '%s' must have type INT

   *
     Error: '1698' SQLSTATE: '28000'
     ('ER_ACCESS_DENIED_NO_PASSWORD_ERROR')

     Message: Access denied for user '%s'@'%s'

   *
     Error: '1699' SQLSTATE: 'HY000' ('ER_SET_PASSWORD_AUTH_PLUGIN')

     Message: SET PASSWORD has no significance for users authenticating
     via plugins

   *
     Error: '1700' SQLSTATE: 'HY000' ('ER_GRANT_PLUGIN_USER_EXISTS')

     Message: GRANT with IDENTIFIED WITH is illegal because the user
     %-.*s already exists

   *
     Error: '1701' SQLSTATE: '42000' ('ER_TRUNCATE_ILLEGAL_FK')

     Message: Cannot truncate a table referenced in a foreign key
     constraint (%s)

   *
     Error: '1702' SQLSTATE: 'HY000' ('ER_PLUGIN_IS_PERMANENT')

     Message: Plugin '%s' is force_plus_permanent and can not be
     unloaded

   *
     Error: '1703' SQLSTATE: 'HY000'
     ('ER_SLAVE_HEARTBEAT_VALUE_OUT_OF_RANGE_MIN')

     Message: The requested value for the heartbeat period is less than
     1 millisecond.  The value is reset to 0, meaning that heartbeating
     will effectively be disabled.

   *
     Error: '1704' SQLSTATE: 'HY000'
     ('ER_SLAVE_HEARTBEAT_VALUE_OUT_OF_RANGE_MAX')

     Message: The requested value for the heartbeat period exceeds the
     value of 'slave_net_timeout' seconds.  A sensible value for the
     period should be less than the timeout.

   *
     Error: '1705' SQLSTATE: 'HY000' ('ER_STMT_CACHE_FULL')

     Message: Multi-row statements required more than
     'max_binlog_stmt_cache_size' bytes of storage; increase this mysqld
     variable and try again

   *
     Error: '1706' SQLSTATE: 'HY000' ('ER_MULTI_UPDATE_KEY_CONFLICT')

     Message: Primary key/partition key update is not allowed since the
     table is updated both as '%s' and '%s'.

   *
     Error: '1707' SQLSTATE: 'HY000' ('ER_TABLE_NEEDS_REBUILD')

     Message: Table rebuild required.  Please do "ALTER TABLE '%s'
     FORCE" or dump/reload to fix it!

   *
     Error: '1708' SQLSTATE: 'HY000' ('WARN_OPTION_BELOW_LIMIT')

     Message: The value of '%s' should be no less than the value of '%s'

   *
     Error: '1709' SQLSTATE: 'HY000' ('ER_INDEX_COLUMN_TOO_LONG')

     Message: Index column size too large.  The maximum column size is
     %lu bytes.

   *
     Error: '1710' SQLSTATE: 'HY000' ('ER_ERROR_IN_TRIGGER_BODY')

     Message: Trigger '%s' has an error in its body: '%s'

   *
     Error: '1711' SQLSTATE: 'HY000'
     ('ER_ERROR_IN_UNKNOWN_TRIGGER_BODY')

     Message: Unknown trigger has an error in its body: '%s'

   *
     Error: '1712' SQLSTATE: 'HY000' ('ER_INDEX_CORRUPT')

     Message: Index %s is corrupted

   *
     Error: '1713' SQLSTATE: 'HY000' ('ER_UNDO_RECORD_TOO_BIG')

     Message: Undo log record is too big.

   *
     Error: '1714' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_INSERT_IGNORE_SELECT')

     Message: INSERT IGNORE... SELECT is unsafe because the order in
     which rows are retrieved by the SELECT determines which (if any)
     rows are ignored.  This order cannot be predicted and may differ on
     master and the slave.

   *
     Error: '1715' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_INSERT_SELECT_UPDATE')

     Message: INSERT... SELECT... ON DUPLICATE KEY UPDATE is unsafe
     because the order in which rows are retrieved by the SELECT
     determines which (if any) rows are updated.  This order cannot be
     predicted and may differ on master and the slave.

   *
     Error: '1716' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_REPLACE_SELECT')

     Message: REPLACE... SELECT is unsafe because the order in which
     rows are retrieved by the SELECT determines which (if any) rows are
     replaced.  This order cannot be predicted and may differ on master
     and the slave.

   *
     Error: '1717' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_CREATE_IGNORE_SELECT')

     Message: CREATE... IGNORE SELECT is unsafe because the order in
     which rows are retrieved by the SELECT determines which (if any)
     rows are ignored.  This order cannot be predicted and may differ on
     master and the slave.

   *
     Error: '1718' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_CREATE_REPLACE_SELECT')

     Message: CREATE... REPLACE SELECT is unsafe because the order in
     which rows are retrieved by the SELECT determines which (if any)
     rows are replaced.  This order cannot be predicted and may differ
     on master and the slave.

   *
     Error: '1719' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_UPDATE_IGNORE')

     Message: UPDATE IGNORE is unsafe because the order in which rows
     are updated determines which (if any) rows are ignored.  This order
     cannot be predicted and may differ on master and the slave.

   *
     Error: '1720' SQLSTATE: 'HY000' ('ER_PLUGIN_NO_UNINSTALL')

     Message: Plugin '%s' is marked as not dynamically uninstallable.
     You have to stop the server to uninstall it.

   *
     Error: '1721' SQLSTATE: 'HY000' ('ER_PLUGIN_NO_INSTALL')

     Message: Plugin '%s' is marked as not dynamically installable.  You
     have to stop the server to install it.

   *
     Error: '1722' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_WRITE_AUTOINC_SELECT')

     Message: Statements writing to a table with an auto-increment
     column after selecting from another table are unsafe because the
     order in which rows are retrieved determines what (if any) rows
     will be written.  This order cannot be predicted and may differ on
     master and the slave.

   *
     Error: '1723' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_CREATE_SELECT_AUTOINC')

     Message: CREATE TABLE... SELECT... on a table with an
     auto-increment column is unsafe because the order in which rows are
     retrieved by the SELECT determines which (if any) rows are
     inserted.  This order cannot be predicted and may differ on master
     and the slave.

   *
     Error: '1724' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_INSERT_TWO_KEYS')

     Message: INSERT... ON DUPLICATE KEY UPDATE on a table with more
     than one UNIQUE KEY is unsafe

   *
     Error: '1725' SQLSTATE: 'HY000' ('ER_TABLE_IN_FK_CHECK')

     Message: Table is being used in foreign key check.

   *
     Error: '1726' SQLSTATE: 'HY000' ('ER_UNSUPPORTED_ENGINE')

     Message: Storage engine '%s' does not support system tables.
     [%s.%s]

   *
     Error: '1727' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_AUTOINC_NOT_FIRST')

     Message: INSERT into autoincrement field which is not the first
     part in the composed primary key is unsafe.

   *
     Error: '1728' SQLSTATE: 'HY000' ('ER_CANNOT_LOAD_FROM_TABLE_V2')

     Message: Cannot load from %s.%s.  The table is probably corrupted

   *
     Error: '1729' SQLSTATE: 'HY000'
     ('ER_MASTER_DELAY_VALUE_OUT_OF_RANGE')

     Message: The requested value %s for the master delay exceeds the
     maximum %u

   *
     Error: '1730' SQLSTATE: 'HY000'
     ('ER_ONLY_FD_AND_RBR_EVENTS_ALLOWED_IN_BINLOG_STATEMENT')

     Message: Only Format_description_log_event and row events are
     allowed in BINLOG statements (but %s was provided)

   *
     Error: '1731' SQLSTATE: 'HY000'
     ('ER_PARTITION_EXCHANGE_DIFFERENT_OPTION')

     Message: Non matching attribute '%s' between partition and table

   *
     Error: '1732' SQLSTATE: 'HY000'
     ('ER_PARTITION_EXCHANGE_PART_TABLE')

     Message: Table to exchange with partition is partitioned: '%s'

   *
     Error: '1733' SQLSTATE: 'HY000'
     ('ER_PARTITION_EXCHANGE_TEMP_TABLE')

     Message: Table to exchange with partition is temporary: '%s'

   *
     Error: '1734' SQLSTATE: 'HY000'
     ('ER_PARTITION_INSTEAD_OF_SUBPARTITION')

     Message: Subpartitioned table, use subpartition instead of
     partition

   *
     Error: '1735' SQLSTATE: 'HY000' ('ER_UNKNOWN_PARTITION')

     Message: Unknown partition '%s' in table '%s'

   *
     Error: '1736' SQLSTATE: 'HY000' ('ER_TABLES_DIFFERENT_METADATA')

     Message: Tables have different definitions

   *
     Error: '1737' SQLSTATE: 'HY000' ('ER_ROW_DOES_NOT_MATCH_PARTITION')

     Message: Found a row that does not match the partition

   *
     Error: '1738' SQLSTATE: 'HY000'
     ('ER_BINLOG_CACHE_SIZE_GREATER_THAN_MAX')

     Message: Option binlog_cache_size (%lu) is greater than
     max_binlog_cache_size (%lu); setting binlog_cache_size equal to
     max_binlog_cache_size.

   *
     Error: '1739' SQLSTATE: 'HY000' ('ER_WARN_INDEX_NOT_APPLICABLE')

     Message: Cannot use %s access on index '%s' due to type or
     collation conversion on field '%s'

   *
     Error: '1740' SQLSTATE: 'HY000'
     ('ER_PARTITION_EXCHANGE_FOREIGN_KEY')

     Message: Table to exchange with partition has foreign key
     references: '%s'

   *
     Error: '1741' SQLSTATE: 'HY000' ('ER_NO_SUCH_KEY_VALUE')

     Message: Key value '%s' was not found in table '%s.%s'

   *
     Error: '1742' SQLSTATE: 'HY000' ('ER_RPL_INFO_DATA_TOO_LONG')

     Message: Data for column '%s' too long

   *
     Error: '1743' SQLSTATE: 'HY000'
     ('ER_NETWORK_READ_EVENT_CHECKSUM_FAILURE')

     Message: Replication event checksum verification failed while
     reading from network.

   *
     Error: '1744' SQLSTATE: 'HY000'
     ('ER_BINLOG_READ_EVENT_CHECKSUM_FAILURE')

     Message: Replication event checksum verification failed while
     reading from a log file.

   *
     Error: '1745' SQLSTATE: 'HY000'
     ('ER_BINLOG_STMT_CACHE_SIZE_GREATER_THAN_MAX')

     Message: Option binlog_stmt_cache_size (%lu) is greater than
     max_binlog_stmt_cache_size (%lu); setting binlog_stmt_cache_size
     equal to max_binlog_stmt_cache_size.

   *
     Error: '1746' SQLSTATE: 'HY000'
     ('ER_CANT_UPDATE_TABLE_IN_CREATE_TABLE_SELECT')

     Message: Can't update table '%s' while '%s' is being created.

   *
     Error: '1747' SQLSTATE: 'HY000'
     ('ER_PARTITION_CLAUSE_ON_NONPARTITIONED')

     Message: PARTITION () clause on non partitioned table

   *
     Error: '1748' SQLSTATE: 'HY000'
     ('ER_ROW_DOES_NOT_MATCH_GIVEN_PARTITION_SET')

     Message: Found a row not matching the given partition set

   *
     Error: '1749' SQLSTATE: 'HY000' ('ER_NO_SUCH_PARTITION__UNUSED')

     Message: partition '%s' doesn't exist

   *
     Error: '1750' SQLSTATE: 'HY000'
     ('ER_CHANGE_RPL_INFO_REPOSITORY_FAILURE')

     Message: Failure while changing the type of replication repository:
     %s.

   *
     Error: '1751' SQLSTATE: 'HY000'
     ('ER_WARNING_NOT_COMPLETE_ROLLBACK_WITH_CREATED_TEMP_TABLE')

     Message: The creation of some temporary tables could not be rolled
     back.

   *
     Error: '1752' SQLSTATE: 'HY000'
     ('ER_WARNING_NOT_COMPLETE_ROLLBACK_WITH_DROPPED_TEMP_TABLE')

     Message: Some temporary tables were dropped, but these operations
     could not be rolled back.

   *
     Error: '1753' SQLSTATE: 'HY000' ('ER_MTS_FEATURE_IS_NOT_SUPPORTED')

     Message: %s is not supported in multi-threaded slave mode.  %s

   *
     Error: '1754' SQLSTATE: 'HY000' ('ER_MTS_UPDATED_DBS_GREATER_MAX')

     Message: The number of modified databases exceeds the maximum %d;
     the database names will not be included in the replication event
     metadata.

   *
     Error: '1755' SQLSTATE: 'HY000' ('ER_MTS_CANT_PARALLEL')

     Message: Cannot execute the current event group in the parallel
     mode.  Encountered event %s, relay-log name %s, position %s which
     prevents execution of this event group in parallel mode.  Reason:
     %s.

   *
     Error: '1756' SQLSTATE: 'HY000' ('ER_MTS_INCONSISTENT_DATA')

     Message: %s

   *
     Error: '1757' SQLSTATE: 'HY000'
     ('ER_FULLTEXT_NOT_SUPPORTED_WITH_PARTITIONING')

     Message: FULLTEXT index is not supported for partitioned tables.

   *
     Error: '1758' SQLSTATE: '35000' ('ER_DA_INVALID_CONDITION_NUMBER')

     Message: Invalid condition number

   *
     Error: '1759' SQLSTATE: 'HY000' ('ER_INSECURE_PLAIN_TEXT')

     Message: Sending passwords in plain text without SSL/TLS is
     extremely insecure.

   *
     Error: '1760' SQLSTATE: 'HY000' ('ER_INSECURE_CHANGE_MASTER')

     Message: Storing MySQL user name or password information in the
     master info repository is not secure and is therefore not
     recommended.  Please consider using the USER and PASSWORD
     connection options for START SLAVE; see the 'START SLAVE Syntax' in
     the MySQL Manual for more information.

   *
     Error: '1761' SQLSTATE: '23000'
     ('ER_FOREIGN_DUPLICATE_KEY_WITH_CHILD_INFO')

     Message: Foreign key constraint for table '%s', record '%s' would
     lead to a duplicate entry in table '%s', key '%s'

   *
     Error: '1762' SQLSTATE: '23000'
     ('ER_FOREIGN_DUPLICATE_KEY_WITHOUT_CHILD_INFO')

     Message: Foreign key constraint for table '%s', record '%s' would
     lead to a duplicate entry in a child table

   *
     Error: '1763' SQLSTATE: 'HY000' ('ER_SQLTHREAD_WITH_SECURE_SLAVE')

     Message: Setting authentication options is not possible when only
     the Slave SQL Thread is being started.

   *
     Error: '1764' SQLSTATE: 'HY000' ('ER_TABLE_HAS_NO_FT')

     Message: The table does not have FULLTEXT index to support this
     query

   *
     Error: '1765' SQLSTATE: 'HY000'
     ('ER_VARIABLE_NOT_SETTABLE_IN_SF_OR_TRIGGER')

     Message: The system variable %s cannot be set in stored functions
     or triggers.

   *
     Error: '1766' SQLSTATE: 'HY000'
     ('ER_VARIABLE_NOT_SETTABLE_IN_TRANSACTION')

     Message: The system variable %s cannot be set when there is an
     ongoing transaction.

   *
     Error: '1767' SQLSTATE: 'HY000'
     ('ER_GTID_NEXT_IS_NOT_IN_GTID_NEXT_LIST')

     Message: The system variable @@SESSION.GTID_NEXT has the value %s,
     which is not listed in @@SESSION.GTID_NEXT_LIST.

   *
     Error: '1768' SQLSTATE: 'HY000'
     ('ER_CANT_CHANGE_GTID_NEXT_IN_TRANSACTION_WHEN_GTID_NEXT_LIST_IS_NULL')

     Message: The system variable @@SESSION.GTID_NEXT cannot change
     inside a transaction.

     'ER_CANT_CHANGE_GTID_NEXT_IN_TRANSACTION_WHEN_GTID_NEXT_LIST_IS_NULL'
     was removed after 5.7.5.

   *
     Error: '1768' SQLSTATE: 'HY000'
     ('ER_CANT_CHANGE_GTID_NEXT_IN_TRANSACTION')

     Message: The system variable @@SESSION.GTID_NEXT cannot change
     inside a transaction.

     'ER_CANT_CHANGE_GTID_NEXT_IN_TRANSACTION' was added in 5.7.6.

   *
     Error: '1769' SQLSTATE: 'HY000'
     ('ER_SET_STATEMENT_CANNOT_INVOKE_FUNCTION')

     Message: The statement 'SET %s' cannot invoke a stored function.

   *
     Error: '1770' SQLSTATE: 'HY000'
     ('ER_GTID_NEXT_CANT_BE_AUTOMATIC_IF_GTID_NEXT_LIST_IS_NON_NULL')

     Message: The system variable @@SESSION.GTID_NEXT cannot be
     'AUTOMATIC' when @@SESSION.GTID_NEXT_LIST is non-NULL.

   *
     Error: '1771' SQLSTATE: 'HY000' ('ER_SKIPPING_LOGGED_TRANSACTION')

     Message: Skipping transaction %s because it has already been
     executed and logged.

   *
     Error: '1772' SQLSTATE: 'HY000'
     ('ER_MALFORMED_GTID_SET_SPECIFICATION')

     Message: Malformed GTID set specification '%s'.

   *
     Error: '1773' SQLSTATE: 'HY000' ('ER_MALFORMED_GTID_SET_ENCODING')

     Message: Malformed GTID set encoding.

   *
     Error: '1774' SQLSTATE: 'HY000' ('ER_MALFORMED_GTID_SPECIFICATION')

     Message: Malformed GTID specification '%s'.

   *
     Error: '1775' SQLSTATE: 'HY000' ('ER_GNO_EXHAUSTED')

     Message: Impossible to generate Global Transaction Identifier: the
     integer component reached the maximal value.  Restart the server
     with a new server_uuid.

   *
     Error: '1776' SQLSTATE: 'HY000' ('ER_BAD_SLAVE_AUTO_POSITION')

     Message: Parameters MASTER_LOG_FILE, MASTER_LOG_POS, RELAY_LOG_FILE
     and RELAY_LOG_POS cannot be set when MASTER_AUTO_POSITION is
     active.

   *
     Error: '1777' SQLSTATE: 'HY000'
     ('ER_AUTO_POSITION_REQUIRES_GTID_MODE_ON')

     Message: CHANGE MASTER TO MASTER_AUTO_POSITION = 1 can only be
     executed when @@GLOBAL.GTID_MODE = ON.

     'ER_AUTO_POSITION_REQUIRES_GTID_MODE_ON' was removed after 5.7.5.

   *
     Error: '1777' SQLSTATE: 'HY000'
     ('ER_AUTO_POSITION_REQUIRES_GTID_MODE_NOT_OFF')

     Message: CHANGE MASTER TO MASTER_AUTO_POSITION = 1 cannot be
     executed because @@GLOBAL.GTID_MODE = OFF.

     'ER_AUTO_POSITION_REQUIRES_GTID_MODE_NOT_OFF' was added in 5.7.6.

   *
     Error: '1778' SQLSTATE: 'HY000'
     ('ER_CANT_DO_IMPLICIT_COMMIT_IN_TRX_WHEN_GTID_NEXT_IS_SET')

     Message: Cannot execute statements with implicit commit inside a
     transaction when @@SESSION.GTID_NEXT == 'UUID:NUMBER'.

   *
     Error: '1779' SQLSTATE: 'HY000'
     ('ER_GTID_MODE_2_OR_3_REQUIRES_ENFORCE_GTID_CONSISTENCY_ON')

     Message: @@GLOBAL.GTID_MODE = ON or UPGRADE_STEP_2 requires
     @@GLOBAL.ENFORCE_GTID_CONSISTENCY = 1.

     'ER_GTID_MODE_2_OR_3_REQUIRES_ENFORCE_GTID_CONSISTENCY_ON' was
     removed after 5.7.5.

   *
     Error: '1779' SQLSTATE: 'HY000'
     ('ER_GTID_MODE_ON_REQUIRES_ENFORCE_GTID_CONSISTENCY_ON')

     Message: GTID_MODE = ON requires ENFORCE_GTID_CONSISTENCY = ON.

     'ER_GTID_MODE_ON_REQUIRES_ENFORCE_GTID_CONSISTENCY_ON' was added in
     5.7.6.

   *
     Error: '1780' SQLSTATE: 'HY000' ('ER_GTID_MODE_REQUIRES_BINLOG')

     Message: @@GLOBAL.GTID_MODE = ON or ON_PERMISSIVE or OFF_PERMISSIVE
     requires -log-bin and -log-slave-updates.

   *
     Error: '1781' SQLSTATE: 'HY000'
     ('ER_CANT_SET_GTID_NEXT_TO_GTID_WHEN_GTID_MODE_IS_OFF')

     Message: @@SESSION.GTID_NEXT cannot be set to UUID:NUMBER when
     @@GLOBAL.GTID_MODE = OFF.

   *
     Error: '1782' SQLSTATE: 'HY000'
     ('ER_CANT_SET_GTID_NEXT_TO_ANONYMOUS_WHEN_GTID_MODE_IS_ON')

     Message: @@SESSION.GTID_NEXT cannot be set to ANONYMOUS when
     @@GLOBAL.GTID_MODE = ON.

   *
     Error: '1783' SQLSTATE: 'HY000'
     ('ER_CANT_SET_GTID_NEXT_LIST_TO_NON_NULL_WHEN_GTID_MODE_IS_OFF')

     Message: @@SESSION.GTID_NEXT_LIST cannot be set to a non-NULL value
     when @@GLOBAL.GTID_MODE = OFF.

   *
     Error: '1784' SQLSTATE: 'HY000'
     ('ER_FOUND_GTID_EVENT_WHEN_GTID_MODE_IS_OFF')

     Message: Found a Gtid_log_event or Previous_gtids_log_event when
     @@GLOBAL.GTID_MODE = OFF.

     'ER_FOUND_GTID_EVENT_WHEN_GTID_MODE_IS_OFF' was removed after
     5.7.5.

   *
     Error: '1784' SQLSTATE: 'HY000'
     ('ER_FOUND_GTID_EVENT_WHEN_GTID_MODE_IS_OFF__UNUSED')

     Message: Found a Gtid_log_event when @@GLOBAL.GTID_MODE = OFF.

     'ER_FOUND_GTID_EVENT_WHEN_GTID_MODE_IS_OFF__UNUSED' was added in
     5.7.6.

   *
     Error: '1785' SQLSTATE: 'HY000'
     ('ER_GTID_UNSAFE_NON_TRANSACTIONAL_TABLE')

     Message: Statement violates GTID consistency: Updates to
     non-transactional tables can only be done in either autocommitted
     statements or single-statement transactions, and never in the same
     statement as updates to transactional tables.

   *
     Error: '1786' SQLSTATE: 'HY000' ('ER_GTID_UNSAFE_CREATE_SELECT')

     Message: Statement violates GTID consistency: CREATE TABLE ...
     SELECT.

   *
     Error: '1787' SQLSTATE: 'HY000'
     ('ER_GTID_UNSAFE_CREATE_DROP_TEMPORARY_TABLE_IN_TRANSACTION')

     Message: Statement violates GTID consistency: CREATE TEMPORARY
     TABLE and DROP TEMPORARY TABLE can only be executed outside
     transactional context.  These statements are also not allowed in a
     function or trigger because functions and triggers are also
     considered to be multi-statement transactions.

   *
     Error: '1788' SQLSTATE: 'HY000'
     ('ER_GTID_MODE_CAN_ONLY_CHANGE_ONE_STEP_AT_A_TIME')

     Message: The value of @@GLOBAL.GTID_MODE can only be changed one
     step at a time: OFF <-> OFF_PERMISSIVE <-> ON_PERMISSIVE <-> ON.
     Also note that this value must be stepped up or down simultaneously
     on all servers.  See the Manual for instructions.

   *
     Error: '1789' SQLSTATE: 'HY000'
     ('ER_MASTER_HAS_PURGED_REQUIRED_GTIDS')

     Message: The slave is connecting using CHANGE MASTER TO
     MASTER_AUTO_POSITION = 1, but the master has purged binary logs
     containing GTIDs that the slave requires.

   *
     Error: '1790' SQLSTATE: 'HY000'
     ('ER_CANT_SET_GTID_NEXT_WHEN_OWNING_GTID')

     Message: @@SESSION.GTID_NEXT cannot be changed by a client that
     owns a GTID. The client owns %s.  Ownership is released on COMMIT
     or ROLLBACK.

   *
     Error: '1791' SQLSTATE: 'HY000' ('ER_UNKNOWN_EXPLAIN_FORMAT')

     Message: Unknown EXPLAIN format name: '%s'

   *
     Error: '1792' SQLSTATE: '25006'
     ('ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION')

     Message: Cannot execute statement in a READ ONLY transaction.

   *
     Error: '1793' SQLSTATE: 'HY000'
     ('ER_TOO_LONG_TABLE_PARTITION_COMMENT')

     Message: Comment for table partition '%s' is too long (max = %lu)

   *
     Error: '1794' SQLSTATE: 'HY000' ('ER_SLAVE_CONFIGURATION')

     Message: Slave is not configured or failed to initialize properly.
     You must at least set -server-id to enable either a master or a
     slave.  Additional error messages can be found in the MySQL error
     log.

   *
     Error: '1795' SQLSTATE: 'HY000' ('ER_INNODB_FT_LIMIT')

     Message: InnoDB presently supports one FULLTEXT index creation at a
     time

   *
     Error: '1796' SQLSTATE: 'HY000' ('ER_INNODB_NO_FT_TEMP_TABLE')

     Message: Cannot create FULLTEXT index on temporary InnoDB table

   *
     Error: '1797' SQLSTATE: 'HY000' ('ER_INNODB_FT_WRONG_DOCID_COLUMN')

     Message: Column '%s' is of wrong type for an InnoDB FULLTEXT index

   *
     Error: '1798' SQLSTATE: 'HY000' ('ER_INNODB_FT_WRONG_DOCID_INDEX')

     Message: Index '%s' is of wrong type for an InnoDB FULLTEXT index

   *
     Error: '1799' SQLSTATE: 'HY000' ('ER_INNODB_ONLINE_LOG_TOO_BIG')

     Message: Creating index '%s' required more than
     'innodb_online_alter_log_max_size' bytes of modification log.
     Please try again.

   *
     Error: '1800' SQLSTATE: 'HY000' ('ER_UNKNOWN_ALTER_ALGORITHM')

     Message: Unknown ALGORITHM '%s'

   *
     Error: '1801' SQLSTATE: 'HY000' ('ER_UNKNOWN_ALTER_LOCK')

     Message: Unknown LOCK type '%s'

   *
     Error: '1802' SQLSTATE: 'HY000'
     ('ER_MTS_CHANGE_MASTER_CANT_RUN_WITH_GAPS')

     Message: CHANGE MASTER cannot be executed when the slave was
     stopped with an error or killed in MTS mode.  Consider using RESET
     SLAVE or START SLAVE UNTIL.

   *
     Error: '1803' SQLSTATE: 'HY000' ('ER_MTS_RECOVERY_FAILURE')

     Message: Cannot recover after SLAVE errored out in parallel
     execution mode.  Additional error messages can be found in the
     MySQL error log.

   *
     Error: '1804' SQLSTATE: 'HY000' ('ER_MTS_RESET_WORKERS')

     Message: Cannot clean up worker info tables.  Additional error
     messages can be found in the MySQL error log.

   *
     Error: '1805' SQLSTATE: 'HY000'
     ('ER_COL_COUNT_DOESNT_MATCH_CORRUPTED_V2')

     Message: Column count of %s.%s is wrong.  Expected %d, found %d.
     The table is probably corrupted

   *
     Error: '1806' SQLSTATE: 'HY000'
     ('ER_SLAVE_SILENT_RETRY_TRANSACTION')

     Message: Slave must silently retry current transaction

   *
     Error: '1807' SQLSTATE: 'HY000' ('ER_DISCARD_FK_CHECKS_RUNNING')

     Message: There is a foreign key check running on table '%s'.
     Cannot discard the table.

   *
     Error: '1808' SQLSTATE: 'HY000' ('ER_TABLE_SCHEMA_MISMATCH')

     Message: Schema mismatch (%s)

   *
     Error: '1809' SQLSTATE: 'HY000' ('ER_TABLE_IN_SYSTEM_TABLESPACE')

     Message: Table '%s' in system tablespace

   *
     Error: '1810' SQLSTATE: 'HY000' ('ER_IO_READ_ERROR')

     Message: IO Read error: (%lu, %s) %s

   *
     Error: '1811' SQLSTATE: 'HY000' ('ER_IO_WRITE_ERROR')

     Message: IO Write error: (%lu, %s) %s

   *
     Error: '1812' SQLSTATE: 'HY000' ('ER_TABLESPACE_MISSING')

     Message: Tablespace is missing for table %s.

   *
     Error: '1813' SQLSTATE: 'HY000' ('ER_TABLESPACE_EXISTS')

     Message: Tablespace '%s' exists.

   *
     Error: '1814' SQLSTATE: 'HY000' ('ER_TABLESPACE_DISCARDED')

     Message: Tablespace has been discarded for table '%s'

   *
     Error: '1815' SQLSTATE: 'HY000' ('ER_INTERNAL_ERROR')

     Message: Internal error: %s

   *
     Error: '1816' SQLSTATE: 'HY000' ('ER_INNODB_IMPORT_ERROR')

     Message: ALTER TABLE %s IMPORT TABLESPACE failed with error %lu :
     '%s'

   *
     Error: '1817' SQLSTATE: 'HY000' ('ER_INNODB_INDEX_CORRUPT')

     Message: Index corrupt: %s

   *
     Error: '1818' SQLSTATE: 'HY000' ('ER_INVALID_YEAR_COLUMN_LENGTH')

     Message: Supports only YEAR or YEAR(4) column.

   *
     Error: '1819' SQLSTATE: 'HY000' ('ER_NOT_VALID_PASSWORD')

     Message: Your password does not satisfy the current policy
     requirements

   *
     Error: '1820' SQLSTATE: 'HY000' ('ER_MUST_CHANGE_PASSWORD')

     Message: You must reset your password using ALTER USER statement
     before executing this statement.

   *
     Error: '1821' SQLSTATE: 'HY000' ('ER_FK_NO_INDEX_CHILD')

     Message: Failed to add the foreign key constaint.  Missing index
     for constraint '%s' in the foreign table '%s'

   *
     Error: '1822' SQLSTATE: 'HY000' ('ER_FK_NO_INDEX_PARENT')

     Message: Failed to add the foreign key constaint.  Missing index
     for constraint '%s' in the referenced table '%s'

   *
     Error: '1823' SQLSTATE: 'HY000' ('ER_FK_FAIL_ADD_SYSTEM')

     Message: Failed to add the foreign key constraint '%s' to system
     tables

   *
     Error: '1824' SQLSTATE: 'HY000' ('ER_FK_CANNOT_OPEN_PARENT')

     Message: Failed to open the referenced table '%s'

   *
     Error: '1825' SQLSTATE: 'HY000' ('ER_FK_INCORRECT_OPTION')

     Message: Failed to add the foreign key constraint on table '%s'.
     Incorrect options in FOREIGN KEY constraint '%s'

   *
     Error: '1826' SQLSTATE: 'HY000' ('ER_FK_DUP_NAME')

     Message: Duplicate foreign key constraint name '%s'

   *
     Error: '1827' SQLSTATE: 'HY000' ('ER_PASSWORD_FORMAT')

     Message: The password hash doesn't have the expected format.  Check
     if the correct password algorithm is being used with the PASSWORD()
     function.

   *
     Error: '1828' SQLSTATE: 'HY000' ('ER_FK_COLUMN_CANNOT_DROP')

     Message: Cannot drop column '%s': needed in a foreign key
     constraint '%s'

   *
     Error: '1829' SQLSTATE: 'HY000' ('ER_FK_COLUMN_CANNOT_DROP_CHILD')

     Message: Cannot drop column '%s': needed in a foreign key
     constraint '%s' of table '%s'

   *
     Error: '1830' SQLSTATE: 'HY000' ('ER_FK_COLUMN_NOT_NULL')

     Message: Column '%s' cannot be NOT NULL: needed in a foreign key
     constraint '%s' SET NULL

   *
     Error: '1831' SQLSTATE: 'HY000' ('ER_DUP_INDEX')

     Message: Duplicate index '%s' defined on the table '%s.%s'.  This
     is deprecated and will be disallowed in a future release.

   *
     Error: '1832' SQLSTATE: 'HY000' ('ER_FK_COLUMN_CANNOT_CHANGE')

     Message: Cannot change column '%s': used in a foreign key
     constraint '%s'

   *
     Error: '1833' SQLSTATE: 'HY000'
     ('ER_FK_COLUMN_CANNOT_CHANGE_CHILD')

     Message: Cannot change column '%s': used in a foreign key
     constraint '%s' of table '%s'

   *
     Error: '1834' SQLSTATE: 'HY000' ('ER_FK_CANNOT_DELETE_PARENT')

     Message: Cannot delete rows from table which is parent in a foreign
     key constraint '%s' of table '%s'

     'ER_FK_CANNOT_DELETE_PARENT' was removed after 5.7.3.

   *
     Error: '1834' SQLSTATE: 'HY000' ('ER_UNUSED5')

     Message: Cannot delete rows from table which is parent in a foreign
     key constraint '%s' of table '%s'

     'ER_UNUSED5' was added in 5.7.4.

   *
     Error: '1835' SQLSTATE: 'HY000' ('ER_MALFORMED_PACKET')

     Message: Malformed communication packet.

   *
     Error: '1836' SQLSTATE: 'HY000' ('ER_READ_ONLY_MODE')

     Message: Running in read-only mode

   *
     Error: '1837' SQLSTATE: 'HY000'
     ('ER_GTID_NEXT_TYPE_UNDEFINED_GROUP')

     Message: When @@SESSION.GTID_NEXT is set to a GTID, you must
     explicitly set it to a different value after a COMMIT or ROLLBACK.
     Please check GTID_NEXT variable manual page for detailed
     explanation.  Current @@SESSION.GTID_NEXT is '%s'.

   *
     Error: '1838' SQLSTATE: 'HY000' ('ER_VARIABLE_NOT_SETTABLE_IN_SP')

     Message: The system variable %s cannot be set in stored procedures.

   *
     Error: '1839' SQLSTATE: 'HY000'
     ('ER_CANT_SET_GTID_PURGED_WHEN_GTID_MODE_IS_OFF')

     Message: @@GLOBAL.GTID_PURGED can only be set when
     @@GLOBAL.GTID_MODE = ON.

   *
     Error: '1840' SQLSTATE: 'HY000'
     ('ER_CANT_SET_GTID_PURGED_WHEN_GTID_EXECUTED_IS_NOT_EMPTY')

     Message: @@GLOBAL.GTID_PURGED can only be set when
     @@GLOBAL.GTID_EXECUTED is empty.

   *
     Error: '1841' SQLSTATE: 'HY000'
     ('ER_CANT_SET_GTID_PURGED_WHEN_OWNED_GTIDS_IS_NOT_EMPTY')

     Message: @@GLOBAL.GTID_PURGED can only be set when there are no
     ongoing transactions (not even in other clients).

   *
     Error: '1842' SQLSTATE: 'HY000' ('ER_GTID_PURGED_WAS_CHANGED')

     Message: @@GLOBAL.GTID_PURGED was changed from '%s' to '%s'.

   *
     Error: '1843' SQLSTATE: 'HY000' ('ER_GTID_EXECUTED_WAS_CHANGED')

     Message: @@GLOBAL.GTID_EXECUTED was changed from '%s' to '%s'.

   *
     Error: '1844' SQLSTATE: 'HY000'
     ('ER_BINLOG_STMT_MODE_AND_NO_REPL_TABLES')

     Message: Cannot execute statement: impossible to write to binary
     log since BINLOG_FORMAT = STATEMENT, and both replicated and non
     replicated tables are written to.

   *
     Error: '1845' SQLSTATE: '0A000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED')

     Message: %s is not supported for this operation.  Try %s.

     'ER_ALTER_OPERATION_NOT_SUPPORTED' was added in 5.7.1.

   *
     Error: '1846' SQLSTATE: '0A000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON')

     Message: %s is not supported.  Reason: %s.  Try %s.

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON' was added in 5.7.1.

   *
     Error: '1847' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_COPY')

     Message: COPY algorithm requires a lock

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_COPY' was added in 5.7.1.

   *
     Error: '1848' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_PARTITION')

     Message: Partition specific operations do not yet support
     LOCK/ALGORITHM

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_PARTITION' was added in
     5.7.1.

   *
     Error: '1849' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_FK_RENAME')

     Message: Columns participating in a foreign key are renamed

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_FK_RENAME' was added in
     5.7.1.

   *
     Error: '1850' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_COLUMN_TYPE')

     Message: Cannot change column type INPLACE

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_COLUMN_TYPE' was added in
     5.7.1.

   *
     Error: '1851' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_FK_CHECK')

     Message: Adding foreign keys needs foreign_key_checks=OFF

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_FK_CHECK' was added in
     5.7.1.

   *
     Error: '1852' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_IGNORE')

     Message: Creating unique indexes with IGNORE requires COPY
     algorithm to remove duplicate rows

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_IGNORE' was added in
     5.7.1, removed after 5.7.3.

   *
     Error: '1852' SQLSTATE: 'HY000' ('ER_UNUSED6')

     Message: Creating unique indexes with IGNORE requires COPY
     algorithm to remove duplicate rows

     'ER_UNUSED6' was added in 5.7.4.

   *
     Error: '1853' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_NOPK')

     Message: Dropping a primary key is not allowed without also adding
     a new primary key

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_NOPK' was added in 5.7.1.

   *
     Error: '1854' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_AUTOINC')

     Message: Adding an auto-increment column requires a lock

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_AUTOINC' was added in
     5.7.1.

   *
     Error: '1855' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_HIDDEN_FTS')

     Message: Cannot replace hidden FTS_DOC_ID with a user-visible one

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_HIDDEN_FTS' was added in
     5.7.1.

   *
     Error: '1856' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_CHANGE_FTS')

     Message: Cannot drop or rename FTS_DOC_ID

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_CHANGE_FTS' was added in
     5.7.1.

   *
     Error: '1857' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_FTS')

     Message: Fulltext index creation requires a lock

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_FTS' was added in 5.7.1.

   *
     Error: '1858' SQLSTATE: 'HY000'
     ('ER_SQL_SLAVE_SKIP_COUNTER_NOT_SETTABLE_IN_GTID_MODE')

     Message: sql_slave_skip_counter can not be set when the server is
     running with @@GLOBAL.GTID_MODE = ON. Instead, for each transaction
     that you want to skip, generate an empty transaction with the same
     GTID as the transaction

     'ER_SQL_SLAVE_SKIP_COUNTER_NOT_SETTABLE_IN_GTID_MODE' was added in
     5.7.1.

   *
     Error: '1859' SQLSTATE: '23000' ('ER_DUP_UNKNOWN_IN_INDEX')

     Message: Duplicate entry for key '%s'

     'ER_DUP_UNKNOWN_IN_INDEX' was added in 5.7.1.

   *
     Error: '1860' SQLSTATE: 'HY000' ('ER_IDENT_CAUSES_TOO_LONG_PATH')

     Message: Long database name and identifier for object resulted in
     path length exceeding %d characters.  Path: '%s'.

     'ER_IDENT_CAUSES_TOO_LONG_PATH' was added in 5.7.1.

   *
     Error: '1861' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_NOT_NULL')

     Message: cannot silently convert NULL values, as required in this
     SQL_MODE

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_NOT_NULL' was added in
     5.7.1.

   *
     Error: '1862' SQLSTATE: 'HY000' ('ER_MUST_CHANGE_PASSWORD_LOGIN')

     Message: Your password has expired.  To log in you must change it
     using a client that supports expired passwords.

     'ER_MUST_CHANGE_PASSWORD_LOGIN' was added in 5.7.1.

   *
     Error: '1863' SQLSTATE: 'HY000' ('ER_ROW_IN_WRONG_PARTITION')

     Message: Found a row in wrong partition %s

     'ER_ROW_IN_WRONG_PARTITION' was added in 5.7.1.

   *
     Error: '1864' SQLSTATE: 'HY000'
     ('ER_MTS_EVENT_BIGGER_PENDING_JOBS_SIZE_MAX')

     Message: Cannot schedule event %s, relay-log name %s, position %s
     to Worker thread because its size %lu exceeds %lu of
     slave_pending_jobs_size_max.

     'ER_MTS_EVENT_BIGGER_PENDING_JOBS_SIZE_MAX' was added in 5.7.2.

   *
     Error: '1865' SQLSTATE: 'HY000' ('ER_INNODB_NO_FT_USES_PARSER')

     Message: Cannot CREATE FULLTEXT INDEX WITH PARSER on InnoDB table

     'ER_INNODB_NO_FT_USES_PARSER' was added in 5.7.2.

   *
     Error: '1866' SQLSTATE: 'HY000' ('ER_BINLOG_LOGICAL_CORRUPTION')

     Message: The binary log file '%s' is logically corrupted: %s

     'ER_BINLOG_LOGICAL_CORRUPTION' was added in 5.7.2.

   *
     Error: '1867' SQLSTATE: 'HY000' ('ER_WARN_PURGE_LOG_IN_USE')

     Message: file %s was not purged because it was being read by %d
     thread(s), purged only %d out of %d files.

     'ER_WARN_PURGE_LOG_IN_USE' was added in 5.7.2.

   *
     Error: '1868' SQLSTATE: 'HY000' ('ER_WARN_PURGE_LOG_IS_ACTIVE')

     Message: file %s was not purged because it is the active log file.

     'ER_WARN_PURGE_LOG_IS_ACTIVE' was added in 5.7.2.

   *
     Error: '1869' SQLSTATE: 'HY000' ('ER_AUTO_INCREMENT_CONFLICT')

     Message: Auto-increment value in UPDATE conflicts with internally
     generated values

     'ER_AUTO_INCREMENT_CONFLICT' was added in 5.7.2.

   *
     Error: '1870' SQLSTATE: 'HY000' ('WARN_ON_BLOCKHOLE_IN_RBR')

     Message: Row events are not logged for %s statements that modify
     BLACKHOLE tables in row format.  Table(s): '%s'

     'WARN_ON_BLOCKHOLE_IN_RBR' was added in 5.7.2.

   *
     Error: '1871' SQLSTATE: 'HY000' ('ER_SLAVE_MI_INIT_REPOSITORY')

     Message: Slave failed to initialize master info structure from the
     repository

     'ER_SLAVE_MI_INIT_REPOSITORY' was added in 5.7.2.

   *
     Error: '1872' SQLSTATE: 'HY000' ('ER_SLAVE_RLI_INIT_REPOSITORY')

     Message: Slave failed to initialize relay log info structure from
     the repository

     'ER_SLAVE_RLI_INIT_REPOSITORY' was added in 5.7.2.

   *
     Error: '1873' SQLSTATE: '28000'
     ('ER_ACCESS_DENIED_CHANGE_USER_ERROR')

     Message: Access denied trying to change to user '%s'@'%s' (using
     password: %s).  Disconnecting.

     'ER_ACCESS_DENIED_CHANGE_USER_ERROR' was added in 5.7.2.

   *
     Error: '1874' SQLSTATE: 'HY000' ('ER_INNODB_READ_ONLY')

     Message: InnoDB is in read only mode.

     'ER_INNODB_READ_ONLY' was added in 5.7.2.

   *
     Error: '1875' SQLSTATE: 'HY000'
     ('ER_STOP_SLAVE_SQL_THREAD_TIMEOUT')

     Message: STOP SLAVE command execution is incomplete: Slave SQL
     thread got the stop signal, thread is busy, SQL thread will stop
     once the current task is complete.

     'ER_STOP_SLAVE_SQL_THREAD_TIMEOUT' was added in 5.7.2.

   *
     Error: '1876' SQLSTATE: 'HY000' ('ER_STOP_SLAVE_IO_THREAD_TIMEOUT')

     Message: STOP SLAVE command execution is incomplete: Slave IO
     thread got the stop signal, thread is busy, IO thread will stop
     once the current task is complete.

     'ER_STOP_SLAVE_IO_THREAD_TIMEOUT' was added in 5.7.2.

   *
     Error: '1877' SQLSTATE: 'HY000' ('ER_TABLE_CORRUPT')

     Message: Operation cannot be performed.  The table '%s.%s' is
     missing, corrupt or contains bad data.

     'ER_TABLE_CORRUPT' was added in 5.7.2.

   *
     Error: '1878' SQLSTATE: 'HY000' ('ER_TEMP_FILE_WRITE_FAILURE')

     Message: Temporary file write failure.

     'ER_TEMP_FILE_WRITE_FAILURE' was added in 5.7.3.

   *
     Error: '1879' SQLSTATE: 'HY000' ('ER_INNODB_FT_AUX_NOT_HEX_ID')

     Message: Upgrade index name failed, please use create index(alter
     table) algorithm copy to rebuild index.

     'ER_INNODB_FT_AUX_NOT_HEX_ID' was added in 5.7.4.

   *
     Error: '1880' SQLSTATE: 'HY000' ('ER_OLD_TEMPORALS_UPGRADED')

     Message: TIME/TIMESTAMP/DATETIME columns of old format have been
     upgraded to the new format.

     'ER_OLD_TEMPORALS_UPGRADED' was added in 5.7.4.

   *
     Error: '1881' SQLSTATE: 'HY000' ('ER_INNODB_FORCED_RECOVERY')

     Message: Operation not allowed when innodb_forced_recovery > 0.

     'ER_INNODB_FORCED_RECOVERY' was added in 5.7.4.

   *
     Error: '1882' SQLSTATE: 'HY000' ('ER_AES_INVALID_IV')

     Message: The initialization vector supplied to %s is too short.
     Must be at least %d bytes long

     'ER_AES_INVALID_IV' was added in 5.7.4.

   *
     Error: '1883' SQLSTATE: 'HY000' ('ER_PLUGIN_CANNOT_BE_UNINSTALLED')

     Message: Plugin '%s' cannot be uninstalled now.  %s

     'ER_PLUGIN_CANNOT_BE_UNINSTALLED' was added in 5.7.5.

   *
     Error: '1884' SQLSTATE: 'HY000'
     ('ER_GTID_UNSAFE_BINLOG_SPLITTABLE_STATEMENT_AND_GTID_GROUP')

     Message: Cannot execute statement because it needs to be written to
     the binary log as multiple statements, and this is not allowed when
     @@SESSION.GTID_NEXT == 'UUID:NUMBER'.

     'ER_GTID_UNSAFE_BINLOG_SPLITTABLE_STATEMENT_AND_GTID_GROUP' was
     added in 5.7.5.

   *
     Error: '1885' SQLSTATE: 'HY000'
     ('ER_SLAVE_HAS_MORE_GTIDS_THAN_MASTER')

     Message: Slave has more GTIDs than the master has, using the
     master's SERVER_UUID. This may indicate that the end of the binary
     log was truncated or that the last binary log file was lost, e.g.,
     after a power or disk failure when sync_binlog != 1.  The master
     may or may not have rolled back transactions that were already
     replicated to the slave.  Suggest to replicate any transactions
     that master has rolled back from slave to master, and/or commit
     empty transactions on master to account for transactions that have
     been committed on master but are not included in GTID_EXECUTED.

     'ER_SLAVE_HAS_MORE_GTIDS_THAN_MASTER' was added in 5.7.6.

   *
     Error: '1886' SQLSTATE: 'HY000' ('ER_MISSING_KEY')

     Message: The table '%s.%s' does not have the necessary key(s)
     defined on it.  Please check the table definition and create
     index(s) accordingly.

     'ER_MISSING_KEY' was added in 5.7.22.

   *
     Error: '1906' SQLSTATE: 'HY000' ('ER_SLAVE_IO_THREAD_MUST_STOP')

     Message: This operation cannot be performed with a running slave io
     thread; run STOP SLAVE IO_THREAD first.

     'ER_SLAVE_IO_THREAD_MUST_STOP' was added in 5.7.4, removed after
     5.7.5.

   *
     Error: '3000' SQLSTATE: 'HY000' ('ER_FILE_CORRUPT')

     Message: File %s is corrupted

   *
     Error: '3001' SQLSTATE: 'HY000' ('ER_ERROR_ON_MASTER')

     Message: Query partially completed on the master (error on master:
     %d) and was aborted.  There is a chance that your master is
     inconsistent at this point.  If you are sure that your master is
     ok, run this query manually on the slave and then restart the slave
     with SET GLOBAL SQL_SLAVE_SKIP_COUNTER=1; START SLAVE;.  Query:'%s'

   *
     Error: '3002' SQLSTATE: 'HY000' ('ER_INCONSISTENT_ERROR')

     Message: Query caused different errors on master and slave.  Error
     on master: message (format)='%s' error code=%d; Error on
     slave:actual message='%s', error code=%d.  Default database:'%s'.
     Query:'%s'

   *
     Error: '3003' SQLSTATE: 'HY000' ('ER_STORAGE_ENGINE_NOT_LOADED')

     Message: Storage engine for table '%s'.'%s' is not loaded.

   *
     Error: '3004' SQLSTATE: '0Z002'
     ('ER_GET_STACKED_DA_WITHOUT_ACTIVE_HANDLER')

     Message: GET STACKED DIAGNOSTICS when handler not active

   *
     Error: '3005' SQLSTATE: 'HY000' ('ER_WARN_LEGACY_SYNTAX_CONVERTED')

     Message: %s is no longer supported.  The statement was converted to
     %s.

   *
     Error: '3006' SQLSTATE: 'HY000'
     ('ER_BINLOG_UNSAFE_FULLTEXT_PLUGIN')

     Message: Statement is unsafe because it uses a fulltext parser
     plugin which may not return the same value on the slave.

     'ER_BINLOG_UNSAFE_FULLTEXT_PLUGIN' was added in 5.7.1.

   *
     Error: '3007' SQLSTATE: 'HY000'
     ('ER_CANNOT_DISCARD_TEMPORARY_TABLE')

     Message: Cannot DISCARD/IMPORT tablespace associated with temporary
     table

     'ER_CANNOT_DISCARD_TEMPORARY_TABLE' was added in 5.7.1.

   *
     Error: '3008' SQLSTATE: 'HY000' ('ER_FK_DEPTH_EXCEEDED')

     Message: Foreign key cascade delete/update exceeds max depth of %d.

     'ER_FK_DEPTH_EXCEEDED' was added in 5.7.2.

   *
     Error: '3009' SQLSTATE: 'HY000'
     ('ER_COL_COUNT_DOESNT_MATCH_PLEASE_UPDATE_V2')

     Message: Column count of %s.%s is wrong.  Expected %d, found %d.
     Created with MySQL %d, now running %d.  Please use mysql_upgrade to
     fix this error.

     'ER_COL_COUNT_DOESNT_MATCH_PLEASE_UPDATE_V2' was added in 5.7.2.

   *
     Error: '3010' SQLSTATE: 'HY000'
     ('ER_WARN_TRIGGER_DOESNT_HAVE_CREATED')

     Message: Trigger %s.%s.%s does not have CREATED attribute.

     'ER_WARN_TRIGGER_DOESNT_HAVE_CREATED' was added in 5.7.2.

   *
     Error: '3011' SQLSTATE: 'HY000'
     ('ER_REFERENCED_TRG_DOES_NOT_EXIST')

     Message: Referenced trigger '%s' for the given action time and
     event type does not exist.

     'ER_REFERENCED_TRG_DOES_NOT_EXIST' was added in 5.7.2.

   *
     Error: '3012' SQLSTATE: 'HY000' ('ER_EXPLAIN_NOT_SUPPORTED')

     Message: EXPLAIN FOR CONNECTION command is supported only for
     SELECT/UPDATE/INSERT/DELETE/REPLACE

     'ER_EXPLAIN_NOT_SUPPORTED' was added in 5.7.2.

   *
     Error: '3013' SQLSTATE: 'HY000' ('ER_INVALID_FIELD_SIZE')

     Message: Invalid size for column '%s'.

     'ER_INVALID_FIELD_SIZE' was added in 5.7.2.

   *
     Error: '3014' SQLSTATE: 'HY000' ('ER_MISSING_HA_CREATE_OPTION')

     Message: Table storage engine '%s' found required create option
     missing

     'ER_MISSING_HA_CREATE_OPTION' was added in 5.7.2.

   *
     Error: '3015' SQLSTATE: 'HY000' ('ER_ENGINE_OUT_OF_MEMORY')

     Message: Out of memory in storage engine '%s'.

     'ER_ENGINE_OUT_OF_MEMORY' was added in 5.7.3.

   *
     Error: '3016' SQLSTATE: 'HY000'
     ('ER_PASSWORD_EXPIRE_ANONYMOUS_USER')

     Message: The password for anonymous user cannot be expired.

     'ER_PASSWORD_EXPIRE_ANONYMOUS_USER' was added in 5.7.3.

   *
     Error: '3017' SQLSTATE: 'HY000' ('ER_SLAVE_SQL_THREAD_MUST_STOP')

     Message: This operation cannot be performed with a running slave
     sql thread; run STOP SLAVE SQL_THREAD first

     'ER_SLAVE_SQL_THREAD_MUST_STOP' was added in 5.7.3.

   *
     Error: '3018' SQLSTATE: 'HY000' ('ER_NO_FT_MATERIALIZED_SUBQUERY')

     Message: Cannot create FULLTEXT index on materialized subquery

     'ER_NO_FT_MATERIALIZED_SUBQUERY' was added in 5.7.4.

   *
     Error: '3019' SQLSTATE: 'HY000' ('ER_INNODB_UNDO_LOG_FULL')

     Message: Undo Log error: %s

     'ER_INNODB_UNDO_LOG_FULL' was added in 5.7.4.

   *
     Error: '3020' SQLSTATE: '2201E'
     ('ER_INVALID_ARGUMENT_FOR_LOGARITHM')

     Message: Invalid argument for logarithm

     'ER_INVALID_ARGUMENT_FOR_LOGARITHM' was added in 5.7.4.

   *
     Error: '3021' SQLSTATE: 'HY000'
     ('ER_SLAVE_CHANNEL_IO_THREAD_MUST_STOP')

     Message: This operation cannot be performed with a running slave io
     thread; run STOP SLAVE IO_THREAD FOR CHANNEL '%s' first.

     'ER_SLAVE_CHANNEL_IO_THREAD_MUST_STOP' was added in 5.7.6.

   *
     Error: '3022' SQLSTATE: 'HY000'
     ('ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO')

     Message: This operation may not be safe when the slave has
     temporary tables.  The tables will be kept open until the server
     restarts or until the tables are deleted by any replicated DROP
     statement.  Suggest to wait until slave_open_temp_tables = 0.

     'ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO' was added in 5.7.4.

   *
     Error: '3023' SQLSTATE: 'HY000'
     ('ER_WARN_ONLY_MASTER_LOG_FILE_NO_POS')

     Message: CHANGE MASTER TO with a MASTER_LOG_FILE clause but no
     MASTER_LOG_POS clause may not be safe.  The old position value may
     not be valid for the new binary log file.

     'ER_WARN_ONLY_MASTER_LOG_FILE_NO_POS' was added in 5.7.4.

   *
     Error: '3024' SQLSTATE: 'HY000' ('ER_QUERY_TIMEOUT')

     Message: Query execution was interrupted, maximum statement
     execution time exceeded

     'ER_QUERY_TIMEOUT' was added in 5.7.4.

   *
     Error: '3025' SQLSTATE: 'HY000' ('ER_NON_RO_SELECT_DISABLE_TIMER')

     Message: Select is not a read only statement, disabling timer

     'ER_NON_RO_SELECT_DISABLE_TIMER' was added in 5.7.4.

   *
     Error: '3026' SQLSTATE: 'HY000' ('ER_DUP_LIST_ENTRY')

     Message: Duplicate entry '%s'.

     'ER_DUP_LIST_ENTRY' was added in 5.7.4.

   *
     Error: '3027' SQLSTATE: 'HY000' ('ER_SQL_MODE_NO_EFFECT')

     Message: '%s' mode no longer has any effect.  Use STRICT_ALL_TABLES
     or STRICT_TRANS_TABLES instead.

     'ER_SQL_MODE_NO_EFFECT' was added in 5.7.4.

   *
     Error: '3028' SQLSTATE: 'HY000' ('ER_AGGREGATE_ORDER_FOR_UNION')

     Message: Expression #%u of ORDER BY contains aggregate function and
     applies to a UNION

     'ER_AGGREGATE_ORDER_FOR_UNION' was added in 5.7.5.

   *
     Error: '3029' SQLSTATE: 'HY000'
     ('ER_AGGREGATE_ORDER_NON_AGG_QUERY')

     Message: Expression #%u of ORDER BY contains aggregate function and
     applies to the result of a non-aggregated query

     'ER_AGGREGATE_ORDER_NON_AGG_QUERY' was added in 5.7.5.

   *
     Error: '3030' SQLSTATE: 'HY000'
     ('ER_SLAVE_WORKER_STOPPED_PREVIOUS_THD_ERROR')

     Message: Slave worker has stopped after at least one previous
     worker encountered an error when slave-preserve-commit-order was
     enabled.  To preserve commit order, the last transaction executed
     by this thread has not been committed.  When restarting the slave
     after fixing any failed threads, you should fix this worker as
     well.

     'ER_SLAVE_WORKER_STOPPED_PREVIOUS_THD_ERROR' was added in 5.7.5.

   *
     Error: '3031' SQLSTATE: 'HY000'
     ('ER_DONT_SUPPORT_SLAVE_PRESERVE_COMMIT_ORDER')

     Message: slave_preserve_commit_order is not supported %s.

     'ER_DONT_SUPPORT_SLAVE_PRESERVE_COMMIT_ORDER' was added in 5.7.5.

   *
     Error: '3032' SQLSTATE: 'HY000' ('ER_SERVER_OFFLINE_MODE')

     Message: The server is currently in offline mode

     'ER_SERVER_OFFLINE_MODE' was added in 5.7.5.

   *
     Error: '3033' SQLSTATE: 'HY000' ('ER_GIS_DIFFERENT_SRIDS')

     Message: Binary geometry function %s given two geometries of
     different srids: %u and %u, which should have been identical.

     Geometry values passed as arguments to spatial functions must have
     the same SRID value.

     'ER_GIS_DIFFERENT_SRIDS' was added in 5.7.5.

   *
     Error: '3034' SQLSTATE: 'HY000' ('ER_GIS_UNSUPPORTED_ARGUMENT')

     Message: Calling geometry function %s with unsupported types of
     arguments.

     A spatial function was called with a combination of argument types
     that the function does not support.

     'ER_GIS_UNSUPPORTED_ARGUMENT' was added in 5.7.5.

   *
     Error: '3035' SQLSTATE: 'HY000' ('ER_GIS_UNKNOWN_ERROR')

     Message: Unknown GIS error occured in function %s.

     'ER_GIS_UNKNOWN_ERROR' was added in 5.7.5.

   *
     Error: '3036' SQLSTATE: 'HY000' ('ER_GIS_UNKNOWN_EXCEPTION')

     Message: Unknown exception caught in GIS function %s.

     'ER_GIS_UNKNOWN_EXCEPTION' was added in 5.7.5.

   *
     Error: '3037' SQLSTATE: '22023' ('ER_GIS_INVALID_DATA')

     Message: Invalid GIS data provided to function %s.

     A spatial function was called with an argument not recognized as a
     valid geometry value.

     'ER_GIS_INVALID_DATA' was added in 5.7.5.

   *
     Error: '3038' SQLSTATE: 'HY000'
     ('ER_BOOST_GEOMETRY_EMPTY_INPUT_EXCEPTION')

     Message: The geometry has no data in function %s.

     'ER_BOOST_GEOMETRY_EMPTY_INPUT_EXCEPTION' was added in 5.7.5.

   *
     Error: '3039' SQLSTATE: 'HY000'
     ('ER_BOOST_GEOMETRY_CENTROID_EXCEPTION')

     Message: Unable to calculate centroid because geometry is empty in
     function %s.

     'ER_BOOST_GEOMETRY_CENTROID_EXCEPTION' was added in 5.7.5.

   *
     Error: '3040' SQLSTATE: 'HY000'
     ('ER_BOOST_GEOMETRY_OVERLAY_INVALID_INPUT_EXCEPTION')

     Message: Geometry overlay calculation error: geometry data is
     invalid in function %s.

     'ER_BOOST_GEOMETRY_OVERLAY_INVALID_INPUT_EXCEPTION' was added in
     5.7.5.

   *
     Error: '3041' SQLSTATE: 'HY000'
     ('ER_BOOST_GEOMETRY_TURN_INFO_EXCEPTION')

     Message: Geometry turn info calculation error: geometry data is
     invalid in function %s.

     'ER_BOOST_GEOMETRY_TURN_INFO_EXCEPTION' was added in 5.7.5.

   *
     Error: '3042' SQLSTATE: 'HY000'
     ('ER_BOOST_GEOMETRY_SELF_INTERSECTION_POINT_EXCEPTION')

     Message: Analysis procedures of intersection points interrupted
     unexpectedly in function %s.

     'ER_BOOST_GEOMETRY_SELF_INTERSECTION_POINT_EXCEPTION' was added in
     5.7.5.

   *
     Error: '3043' SQLSTATE: 'HY000'
     ('ER_BOOST_GEOMETRY_UNKNOWN_EXCEPTION')

     Message: Unknown exception thrown in function %s.

     'ER_BOOST_GEOMETRY_UNKNOWN_EXCEPTION' was added in 5.7.5.

   *
     Error: '3044' SQLSTATE: 'HY000' ('ER_STD_BAD_ALLOC_ERROR')

     Message: Memory allocation error: %s in function %s.

     'ER_STD_BAD_ALLOC_ERROR' was added in 5.7.5.

   *
     Error: '3045' SQLSTATE: 'HY000' ('ER_STD_DOMAIN_ERROR')

     Message: Domain error: %s in function %s.

     'ER_STD_DOMAIN_ERROR' was added in 5.7.5.

   *
     Error: '3046' SQLSTATE: 'HY000' ('ER_STD_LENGTH_ERROR')

     Message: Length error: %s in function %s.

     'ER_STD_LENGTH_ERROR' was added in 5.7.5.

   *
     Error: '3047' SQLSTATE: 'HY000' ('ER_STD_INVALID_ARGUMENT')

     Message: Invalid argument error: %s in function %s.

     'ER_STD_INVALID_ARGUMENT' was added in 5.7.5.

   *
     Error: '3048' SQLSTATE: 'HY000' ('ER_STD_OUT_OF_RANGE_ERROR')

     Message: Out of range error: %s in function %s.

     'ER_STD_OUT_OF_RANGE_ERROR' was added in 5.7.5.

   *
     Error: '3049' SQLSTATE: 'HY000' ('ER_STD_OVERFLOW_ERROR')

     Message: Overflow error error: %s in function %s.

     'ER_STD_OVERFLOW_ERROR' was added in 5.7.5.

   *
     Error: '3050' SQLSTATE: 'HY000' ('ER_STD_RANGE_ERROR')

     Message: Range error: %s in function %s.

     'ER_STD_RANGE_ERROR' was added in 5.7.5.

   *
     Error: '3051' SQLSTATE: 'HY000' ('ER_STD_UNDERFLOW_ERROR')

     Message: Underflow error: %s in function %s.

     'ER_STD_UNDERFLOW_ERROR' was added in 5.7.5.

   *
     Error: '3052' SQLSTATE: 'HY000' ('ER_STD_LOGIC_ERROR')

     Message: Logic error: %s in function %s.

     'ER_STD_LOGIC_ERROR' was added in 5.7.5.

   *
     Error: '3053' SQLSTATE: 'HY000' ('ER_STD_RUNTIME_ERROR')

     Message: Runtime error: %s in function %s.

     'ER_STD_RUNTIME_ERROR' was added in 5.7.5.

   *
     Error: '3054' SQLSTATE: 'HY000' ('ER_STD_UNKNOWN_EXCEPTION')

     Message: Unknown exception: %s in function %s.

     'ER_STD_UNKNOWN_EXCEPTION' was added in 5.7.5.

   *
     Error: '3055' SQLSTATE: 'HY000' ('ER_GIS_DATA_WRONG_ENDIANESS')

     Message: Geometry byte string must be little endian.

     'ER_GIS_DATA_WRONG_ENDIANESS' was added in 5.7.5.

   *
     Error: '3056' SQLSTATE: 'HY000'
     ('ER_CHANGE_MASTER_PASSWORD_LENGTH')

     Message: The password provided for the replication user exceeds the
     maximum length of 32 characters

     'ER_CHANGE_MASTER_PASSWORD_LENGTH' was added in 5.7.5.

   *
     Error: '3057' SQLSTATE: '42000' ('ER_USER_LOCK_WRONG_NAME')

     Message: Incorrect user-level lock name '%s'.

     'ER_USER_LOCK_WRONG_NAME' was added in 5.7.5.

   *
     Error: '3058' SQLSTATE: 'HY000' ('ER_USER_LOCK_DEADLOCK')

     Message: Deadlock found when trying to get user-level lock; try
     rolling back transaction/releasing locks and restarting lock
     acquisition.

     This error is returned when the metdata locking subsystem detects a
     deadlock for an attempt to acquire a named lock with 'GET_LOCK'.

     'ER_USER_LOCK_DEADLOCK' was added in 5.7.5.

   *
     Error: '3059' SQLSTATE: 'HY000' ('ER_REPLACE_INACCESSIBLE_ROWS')

     Message: REPLACE cannot be executed as it requires deleting rows
     that are not in the view

     'ER_REPLACE_INACCESSIBLE_ROWS' was added in 5.7.5.

   *
     Error: '3060' SQLSTATE: 'HY000'
     ('ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_GIS')

     Message: Do not support online operation on table with GIS index

     'ER_ALTER_OPERATION_NOT_SUPPORTED_REASON_GIS' was added in 5.7.5.

   *
     Error: '3061' SQLSTATE: '42000' ('ER_ILLEGAL_USER_VAR')

     Message: User variable name '%s' is illegal

     'ER_ILLEGAL_USER_VAR' was added in 5.7.5.

   *
     Error: '3062' SQLSTATE: 'HY000' ('ER_GTID_MODE_OFF')

     Message: Cannot %s when GTID_MODE = OFF.

     'ER_GTID_MODE_OFF' was added in 5.7.5.

   *
     Error: '3063' SQLSTATE: 'HY000'
     ('ER_UNSUPPORTED_BY_REPLICATION_THREAD')

     Message: Cannot %s from a replication slave thread.

     'ER_UNSUPPORTED_BY_REPLICATION_THREAD' was added in 5.7.5.

   *
     Error: '3064' SQLSTATE: 'HY000' ('ER_INCORRECT_TYPE')

     Message: Incorrect type for argument %s in function %s.

     'ER_INCORRECT_TYPE' was added in 5.7.5.

   *
     Error: '3065' SQLSTATE: 'HY000' ('ER_FIELD_IN_ORDER_NOT_SELECT')

     Message: Expression #%u of ORDER BY clause is not in SELECT list,
     references column '%s' which is not in SELECT list; this is
     incompatible with %s

     'ER_FIELD_IN_ORDER_NOT_SELECT' was added in 5.7.5.

   *
     Error: '3066' SQLSTATE: 'HY000'
     ('ER_AGGREGATE_IN_ORDER_NOT_SELECT')

     Message: Expression #%u of ORDER BY clause is not in SELECT list,
     contains aggregate function; this is incompatible with %s

     'ER_AGGREGATE_IN_ORDER_NOT_SELECT' was added in 5.7.5.

   *
     Error: '3067' SQLSTATE: 'HY000'
     ('ER_INVALID_RPL_WILD_TABLE_FILTER_PATTERN')

     Message: Supplied filter list contains a value which is not in the
     required format 'db_pattern.table_pattern'

     'ER_INVALID_RPL_WILD_TABLE_FILTER_PATTERN' was added in 5.7.5.

   *
     Error: '3068' SQLSTATE: '08S01' ('ER_NET_OK_PACKET_TOO_LARGE')

     Message: OK packet too large

     'ER_NET_OK_PACKET_TOO_LARGE' was added in 5.7.5.

   *
     Error: '3069' SQLSTATE: 'HY000' ('ER_INVALID_JSON_DATA')

     Message: Invalid JSON data provided to function %s: %s

     'ER_INVALID_JSON_DATA' was added in 5.7.5.

   *
     Error: '3070' SQLSTATE: 'HY000'
     ('ER_INVALID_GEOJSON_MISSING_MEMBER')

     Message: Invalid GeoJSON data provided to function %s: Missing
     required member '%s'

     'ER_INVALID_GEOJSON_MISSING_MEMBER' was added in 5.7.5.

   *
     Error: '3071' SQLSTATE: 'HY000' ('ER_INVALID_GEOJSON_WRONG_TYPE')

     Message: Invalid GeoJSON data provided to function %s: Member '%s'
     must be of type '%s'

     'ER_INVALID_GEOJSON_WRONG_TYPE' was added in 5.7.5.

   *
     Error: '3072' SQLSTATE: 'HY000' ('ER_INVALID_GEOJSON_UNSPECIFIED')

     Message: Invalid GeoJSON data provided to function %s

     'ER_INVALID_GEOJSON_UNSPECIFIED' was added in 5.7.5.

   *
     Error: '3073' SQLSTATE: 'HY000' ('ER_DIMENSION_UNSUPPORTED')

     Message: Unsupported number of coordinate dimensions in function
     %s: Found %u, expected %u

     'ER_DIMENSION_UNSUPPORTED' was added in 5.7.5.

   *
     Error: '3074' SQLSTATE: 'HY000' ('ER_SLAVE_CHANNEL_DOES_NOT_EXIST')

     Message: Slave channel '%s' does not exist.

     'ER_SLAVE_CHANNEL_DOES_NOT_EXIST' was added in 5.7.6.

   *
     Error: '3075' SQLSTATE: 'HY000'
     ('ER_SLAVE_MULTIPLE_CHANNELS_HOST_PORT')

     Message: A slave channel '%s' already exists for the given host and
     port combination.

     'ER_SLAVE_MULTIPLE_CHANNELS_HOST_PORT' was added in 5.7.6.

   *
     Error: '3076' SQLSTATE: 'HY000'
     ('ER_SLAVE_CHANNEL_NAME_INVALID_OR_TOO_LONG')

     Message: Couldn't create channel: Channel name is either invalid or
     too long.

     'ER_SLAVE_CHANNEL_NAME_INVALID_OR_TOO_LONG' was added in 5.7.6.

   *
     Error: '3077' SQLSTATE: 'HY000'
     ('ER_SLAVE_NEW_CHANNEL_WRONG_REPOSITORY')

     Message: To have multiple channels, repository cannot be of type
     FILE; Please check the repository configuration and convert them to
     TABLE.

     'ER_SLAVE_NEW_CHANNEL_WRONG_REPOSITORY' was added in 5.7.6.

   *
     Error: '3078' SQLSTATE: 'HY000' ('ER_SLAVE_CHANNEL_DELETE')

     Message: Cannot delete slave info objects for channel '%s'.

     'ER_SLAVE_CHANNEL_DELETE' was added in 5.7.6.

   *
     Error: '3079' SQLSTATE: 'HY000' ('ER_SLAVE_MULTIPLE_CHANNELS_CMD')

     Message: Multiple channels exist on the slave.  Please provide
     channel name as an argument.

     'ER_SLAVE_MULTIPLE_CHANNELS_CMD' was added in 5.7.6.

   *
     Error: '3080' SQLSTATE: 'HY000' ('ER_SLAVE_MAX_CHANNELS_EXCEEDED')

     Message: Maximum number of replication channels allowed exceeded.

     'ER_SLAVE_MAX_CHANNELS_EXCEEDED' was added in 5.7.6.

   *
     Error: '3081' SQLSTATE: 'HY000' ('ER_SLAVE_CHANNEL_MUST_STOP')

     Message: This operation cannot be performed with running
     replication threads; run STOP SLAVE FOR CHANNEL '%s' first

     'ER_SLAVE_CHANNEL_MUST_STOP' was added in 5.7.6.

   *
     Error: '3082' SQLSTATE: 'HY000' ('ER_SLAVE_CHANNEL_NOT_RUNNING')

     Message: This operation requires running replication threads;
     configure slave and run START SLAVE FOR CHANNEL '%s'

     'ER_SLAVE_CHANNEL_NOT_RUNNING' was added in 5.7.6.

   *
     Error: '3083' SQLSTATE: 'HY000' ('ER_SLAVE_CHANNEL_WAS_RUNNING')

     Message: Replication thread(s) for channel '%s' are already
     runnning.

     'ER_SLAVE_CHANNEL_WAS_RUNNING' was added in 5.7.6.

   *
     Error: '3084' SQLSTATE: 'HY000'
     ('ER_SLAVE_CHANNEL_WAS_NOT_RUNNING')

     Message: Replication thread(s) for channel '%s' are already
     stopped.

     'ER_SLAVE_CHANNEL_WAS_NOT_RUNNING' was added in 5.7.6.

   *
     Error: '3085' SQLSTATE: 'HY000'
     ('ER_SLAVE_CHANNEL_SQL_THREAD_MUST_STOP')

     Message: This operation cannot be performed with a running slave
     sql thread; run STOP SLAVE SQL_THREAD FOR CHANNEL '%s' first.

     'ER_SLAVE_CHANNEL_SQL_THREAD_MUST_STOP' was added in 5.7.6.

   *
     Error: '3086' SQLSTATE: 'HY000'
     ('ER_SLAVE_CHANNEL_SQL_SKIP_COUNTER')

     Message: When sql_slave_skip_counter > 0, it is not allowed to
     start more than one SQL thread by using 'START SLAVE [SQL_THREAD]'.
     Value of sql_slave_skip_counter can only be used by one SQL thread
     at a time.  Please use 'START SLAVE [SQL_THREAD] FOR CHANNEL' to
     start the SQL thread which will use the value of
     sql_slave_skip_counter.

     'ER_SLAVE_CHANNEL_SQL_SKIP_COUNTER' was added in 5.7.6.

   *
     Error: '3087' SQLSTATE: 'HY000' ('ER_WRONG_FIELD_WITH_GROUP_V2')

     Message: Expression #%u of %s is not in GROUP BY clause and
     contains nonaggregated column '%s' which is not functionally
     dependent on columns in GROUP BY clause; this is incompatible with
     sql_mode=only_full_group_by

     'ER_WRONG_FIELD_WITH_GROUP_V2' was added in 5.7.6.

   *
     Error: '3088' SQLSTATE: 'HY000'
     ('ER_MIX_OF_GROUP_FUNC_AND_FIELDS_V2')

     Message: In aggregated query without GROUP BY, expression #%u of %s
     contains nonaggregated column '%s'; this is incompatible with
     sql_mode=only_full_group_by

     'ER_MIX_OF_GROUP_FUNC_AND_FIELDS_V2' was added in 5.7.6.

   *
     Error: '3089' SQLSTATE: 'HY000'
     ('ER_WARN_DEPRECATED_SYSVAR_UPDATE')

     Message: Updating '%s' is deprecated.  It will be made read-only in
     a future release.

     'ER_WARN_DEPRECATED_SYSVAR_UPDATE' was added in 5.7.6.

   *
     Error: '3090' SQLSTATE: 'HY000' ('ER_WARN_DEPRECATED_SQLMODE')

     Message: Changing sql mode '%s' is deprecated.  It will be removed
     in a future release.

     'ER_WARN_DEPRECATED_SQLMODE' was added in 5.7.6.

   *
     Error: '3091' SQLSTATE: 'HY000'
     ('ER_CANNOT_LOG_PARTIAL_DROP_DATABASE_WITH_GTID')

     Message: DROP DATABASE failed; some tables may have been dropped
     but the database directory remains.  The GTID has not been added to
     GTID_EXECUTED and the statement was not written to the binary log.
     Fix this as follows: (1) remove all files from the database
     directory %s; (2) SET GTID_NEXT='%s'; (3) DROP DATABASE '%s'.

     'ER_CANNOT_LOG_PARTIAL_DROP_DATABASE_WITH_GTID' was added in 5.7.6.

   *
     Error: '3092' SQLSTATE: 'HY000'
     ('ER_GROUP_REPLICATION_CONFIGURATION')

     Message: The server is not configured properly to be an active
     member of the group.  Please see more details on error log.

     'ER_GROUP_REPLICATION_CONFIGURATION' was added in 5.7.6.

   *
     Error: '3093' SQLSTATE: 'HY000' ('ER_GROUP_REPLICATION_RUNNING')

     Message: The START GROUP_REPLICATION command failed since the group
     is already running.

     'ER_GROUP_REPLICATION_RUNNING' was added in 5.7.6.

   *
     Error: '3094' SQLSTATE: 'HY000'
     ('ER_GROUP_REPLICATION_APPLIER_INIT_ERROR')

     Message: The START GROUP_REPLICATION command failed as the applier
     module failed to start.

     'ER_GROUP_REPLICATION_APPLIER_INIT_ERROR' was added in 5.7.6.

   *
     Error: '3095' SQLSTATE: 'HY000'
     ('ER_GROUP_REPLICATION_STOP_APPLIER_THREAD_TIMEOUT')

     Message: The STOP GROUP_REPLICATION command execution is
     incomplete: The applier thread got the stop signal while it was
     busy.  The applier thread will stop once the current task is
     complete.

     'ER_GROUP_REPLICATION_STOP_APPLIER_THREAD_TIMEOUT' was added in
     5.7.6.

   *
     Error: '3096' SQLSTATE: 'HY000'
     ('ER_GROUP_REPLICATION_COMMUNICATION_LAYER_SESSION_ERROR')

     Message: The START GROUP_REPLICATION command failed as there was an
     error when initializing the group communication layer.

     'ER_GROUP_REPLICATION_COMMUNICATION_LAYER_SESSION_ERROR' was added
     in 5.7.6.

   *
     Error: '3097' SQLSTATE: 'HY000'
     ('ER_GROUP_REPLICATION_COMMUNICATION_LAYER_JOIN_ERROR')

     Message: The START GROUP_REPLICATION command failed as there was an
     error when joining the communication group.

     'ER_GROUP_REPLICATION_COMMUNICATION_LAYER_JOIN_ERROR' was added in
     5.7.6.

   *
     Error: '3098' SQLSTATE: 'HY000' ('ER_BEFORE_DML_VALIDATION_ERROR')

     Message: The table does not comply with the requirements by an
     external plugin.

     'ER_BEFORE_DML_VALIDATION_ERROR' was added in 5.7.6.

   *
     Error: '3099' SQLSTATE: 'HY000'
     ('ER_PREVENTS_VARIABLE_WITHOUT_RBR')

     Message: Cannot change the value of variable %s without binary log
     format as ROW.

     'transaction_write_set_extraction' option value is set and
     'binlog_format' is not 'ROW'.

     'ER_PREVENTS_VARIABLE_WITHOUT_RBR' was added in 5.7.6.

   *
     Error: '3100' SQLSTATE: 'HY000' ('ER_RUN_HOOK_ERROR')

     Message: Error on observer while running replication hook '%s'.

     'ER_RUN_HOOK_ERROR' was added in 5.7.6.

   *
     Error: '3101' SQLSTATE: 'HY000'
     ('ER_TRANSACTION_ROLLBACK_DURING_COMMIT')

     Message: Plugin instructed the server to rollback the current
     transaction.

     When using Group Replication, this means that a transaction failed
     the group certification process, due to one or more members
     detecting a potential conflict, and was thus rolled back.  See
     group-replication.

     'ER_TRANSACTION_ROLLBACK_DURING_COMMIT' was added in 5.7.6.

   *
     Error: '3102' SQLSTATE: 'HY000'
     ('ER_GENERATED_COLUMN_FUNCTION_IS_NOT_ALLOWED')

     Message: Expression of generated column '%s' contains a disallowed
     function.

     'ER_GENERATED_COLUMN_FUNCTION_IS_NOT_ALLOWED' was added in 5.7.6.

   *
     Error: '3103' SQLSTATE: 'HY000'
     ('ER_KEY_BASED_ON_GENERATED_COLUMN')

     Message: Key/Index cannot be defined on a virtual generated column.

     'ER_KEY_BASED_ON_GENERATED_COLUMN' was added in 5.7.6, removed
     after 5.7.7.

   *
     Error: '3103' SQLSTATE: 'HY000'
     ('ER_UNSUPPORTED_ALTER_INPLACE_ON_VIRTUAL_COLUMN')

     Message: INPLACE ADD or DROP of virtual columns cannot be combined
     with other ALTER TABLE actions

     'ER_UNSUPPORTED_ALTER_INPLACE_ON_VIRTUAL_COLUMN' was added in
     5.7.8.

   *
     Error: '3104' SQLSTATE: 'HY000'
     ('ER_WRONG_FK_OPTION_FOR_GENERATED_COLUMN')

     Message: Cannot define foreign key with %s clause on a generated
     column.

     'ER_WRONG_FK_OPTION_FOR_GENERATED_COLUMN' was added in 5.7.6.

   *
     Error: '3105' SQLSTATE: 'HY000'
     ('ER_NON_DEFAULT_VALUE_FOR_GENERATED_COLUMN')

     Message: The value specified for generated column '%s' in table
     '%s' is not allowed.

     'ER_NON_DEFAULT_VALUE_FOR_GENERATED_COLUMN' was added in 5.7.6.

   *
     Error: '3106' SQLSTATE: 'HY000'
     ('ER_UNSUPPORTED_ACTION_ON_GENERATED_COLUMN')

     Message: '%s' is not supported for generated columns.

     'ER_UNSUPPORTED_ACTION_ON_GENERATED_COLUMN' was added in 5.7.6.

   *
     Error: '3107' SQLSTATE: 'HY000' ('ER_GENERATED_COLUMN_NON_PRIOR')

     Message: Generated column can refer only to generated columns
     defined prior to it.

     To address this issue, change the table definition to define each
     generated column later than any generated columns to which it
     refers.

     'ER_GENERATED_COLUMN_NON_PRIOR' was added in 5.7.6.

   *
     Error: '3108' SQLSTATE: 'HY000'
     ('ER_DEPENDENT_BY_GENERATED_COLUMN')

     Message: Column '%s' has a generated column dependency.

     You cannot drop or rename a generated column if another column
     refers to it.  You must either drop those columns as well, or
     redefine them not to refer to the generated column.

     'ER_DEPENDENT_BY_GENERATED_COLUMN' was added in 5.7.6.

   *
     Error: '3109' SQLSTATE: 'HY000'
     ('ER_GENERATED_COLUMN_REF_AUTO_INC')

     Message: Generated column '%s' cannot refer to auto-increment
     column.

     'ER_GENERATED_COLUMN_REF_AUTO_INC' was added in 5.7.6.

   *
     Error: '3110' SQLSTATE: 'HY000' ('ER_FEATURE_NOT_AVAILABLE')

     Message: The '%s' feature is not available; you need to remove '%s'
     or use MySQL built with '%s'

     'ER_FEATURE_NOT_AVAILABLE' was added in 5.7.6.

   *
     Error: '3111' SQLSTATE: 'HY000' ('ER_CANT_SET_GTID_MODE')

     Message: SET @@GLOBAL.GTID_MODE = %s is not allowed because %s.

     'ER_CANT_SET_GTID_MODE' was added in 5.7.6.

   *
     Error: '3112' SQLSTATE: 'HY000'
     ('ER_CANT_USE_AUTO_POSITION_WITH_GTID_MODE_OFF')

     Message: The replication receiver thread%s cannot start in
     AUTO_POSITION mode: this server uses @@GLOBAL.GTID_MODE = OFF.

     'ER_CANT_USE_AUTO_POSITION_WITH_GTID_MODE_OFF' was added in 5.7.6.

   *
     Error: '3113' SQLSTATE: 'HY000'
     ('ER_CANT_REPLICATE_ANONYMOUS_WITH_AUTO_POSITION')

     Message: Cannot replicate anonymous transaction when AUTO_POSITION
     = 1, at file %s, position %lld.

     'ER_CANT_REPLICATE_ANONYMOUS_WITH_AUTO_POSITION' was added in
     5.7.6.

   *
     Error: '3114' SQLSTATE: 'HY000'
     ('ER_CANT_REPLICATE_ANONYMOUS_WITH_GTID_MODE_ON')

     Message: Cannot replicate anonymous transaction when
     @@GLOBAL.GTID_MODE = ON, at file %s, position %lld.

     'ER_CANT_REPLICATE_ANONYMOUS_WITH_GTID_MODE_ON' was added in 5.7.6.

   *
     Error: '3115' SQLSTATE: 'HY000'
     ('ER_CANT_REPLICATE_GTID_WITH_GTID_MODE_OFF')

     Message: Cannot replicate GTID-transaction when @@GLOBAL.GTID_MODE
     = OFF, at file %s, position %lld.

     'ER_CANT_REPLICATE_GTID_WITH_GTID_MODE_OFF' was added in 5.7.6.

   *
     Error: '3116' SQLSTATE: 'HY000'
     ('ER_CANT_SET_ENFORCE_GTID_CONSISTENCY_ON_WITH_ONGOING_GTID_VIOLATING_TRANSACTIONS')

     Message: Cannot set ENFORCE_GTID_CONSISTENCY = ON because there are
     ongoing transactions that violate GTID consistency.

     'ER_CANT_SET_ENFORCE_GTID_CONSISTENCY_ON_WITH_ONGOING_GTID_VIOLATING_TRANSACTIONS'
     is renamed to
     'ER_CANT_ENFORCE_GTID_CONSISTENCY_WITH_ONGOING_GTID_VIOLATING_TX'
     in MySQL 8.0.

     'ER_CANT_SET_ENFORCE_GTID_CONSISTENCY_ON_WITH_ONGOING_GTID_VIOLATING_TRANSACTIONS'
     was added in 5.7.6.

   *
     Error: '3117' SQLSTATE: 'HY000'
     ('ER_SET_ENFORCE_GTID_CONSISTENCY_WARN_WITH_ONGOING_GTID_VIOLATING_TRANSACTIONS')

     Message: There are ongoing transactions that violate GTID
     consistency.

     'ER_SET_ENFORCE_GTID_CONSISTENCY_WARN_WITH_ONGOING_GTID_VIOLATING_TRANSACTIONS'
     is renamed to
     'ER_ENFORCE_GTID_CONSISTENCY_WARN_WITH_ONGOING_GTID_VIOLATING_TX'
     in MySQL 8.0.

     'ER_SET_ENFORCE_GTID_CONSISTENCY_WARN_WITH_ONGOING_GTID_VIOLATING_TRANSACTIONS'
     was added in 5.7.6.

   *
     Error: '3118' SQLSTATE: 'HY000' ('ER_ACCOUNT_HAS_BEEN_LOCKED')

     Message: Access denied for user '%s'@'%s'.  Account is locked.

     The account was locked with 'CREATE USER ... ACCOUNT LOCK'
     or 'ALTER USER ... ACCOUNT LOCK'.
     An administrator can unlock it with 'ALTER USER ... ACCOUNT UNLOCK'.

     'ER_ACCOUNT_HAS_BEEN_LOCKED' was added in 5.7.6.

   *
     Error: '3119' SQLSTATE: '42000' ('ER_WRONG_TABLESPACE_NAME')

     Message: Incorrect tablespace name '%s'

     'ER_WRONG_TABLESPACE_NAME' was added in 5.7.6.

   *
     Error: '3120' SQLSTATE: 'HY000' ('ER_TABLESPACE_IS_NOT_EMPTY')

     Message: Tablespace '%s' is not empty.

     'ER_TABLESPACE_IS_NOT_EMPTY' was added in 5.7.6.

   *
     Error: '3121' SQLSTATE: 'HY000' ('ER_WRONG_FILE_NAME')

     Message: Incorrect File Name '%s'.

     'ER_WRONG_FILE_NAME' was added in 5.7.6.

   *
     Error: '3122' SQLSTATE: 'HY000'
     ('ER_BOOST_GEOMETRY_INCONSISTENT_TURNS_EXCEPTION')

     Message: Inconsistent intersection points.

     'ER_BOOST_GEOMETRY_INCONSISTENT_TURNS_EXCEPTION' was added in
     5.7.7.

   *
     Error: '3123' SQLSTATE: 'HY000'
     ('ER_WARN_OPTIMIZER_HINT_SYNTAX_ERROR')

     Message: Optimizer hint syntax error

     'ER_WARN_OPTIMIZER_HINT_SYNTAX_ERROR' was added in 5.7.7.

   *
     Error: '3124' SQLSTATE: 'HY000' ('ER_WARN_BAD_MAX_EXECUTION_TIME')

     Message: Unsupported MAX_EXECUTION_TIME

     'ER_WARN_BAD_MAX_EXECUTION_TIME' was added in 5.7.7.

   *
     Error: '3125' SQLSTATE: 'HY000'
     ('ER_WARN_UNSUPPORTED_MAX_EXECUTION_TIME')

     Message: MAX_EXECUTION_TIME hint is supported by top-level
     standalone SELECT statements only

     The 'MAX_EXECUTION_TIME' optimizer hint is supported only for
     'SELECT' statements.

     'ER_WARN_UNSUPPORTED_MAX_EXECUTION_TIME' was added in 5.7.7.

   *
     Error: '3126' SQLSTATE: 'HY000' ('ER_WARN_CONFLICTING_HINT')

     Message: Hint %s is ignored as conflicting/duplicated

     'ER_WARN_CONFLICTING_HINT' was added in 5.7.7.

   *
     Error: '3127' SQLSTATE: 'HY000' ('ER_WARN_UNKNOWN_QB_NAME')

     Message: Query block name %s is not found for %s hint

     'ER_WARN_UNKNOWN_QB_NAME' was added in 5.7.7.

   *
     Error: '3128' SQLSTATE: 'HY000' ('ER_UNRESOLVED_HINT_NAME')

     Message: Unresolved name %s for %s hint

     'ER_UNRESOLVED_HINT_NAME' was added in 5.7.7.

   *
     Error: '3129' SQLSTATE: 'HY000'
     ('ER_WARN_DEPRECATED_SQLMODE_UNSET')

     Message: Unsetting sql mode '%s' is deprecated.  It will be made
     read-only in a future release.

     'ER_WARN_DEPRECATED_SQLMODE_UNSET' was added in 5.7.7, removed
     after 5.7.7.

   *
     Error: '3129' SQLSTATE: 'HY000'
     ('ER_WARN_ON_MODIFYING_GTID_EXECUTED_TABLE')

     Message: Please do not modify the %s table.  This is a mysql
     internal system table to store GTIDs for committed transactions.
     Modifying it can lead to an inconsistent GTID state.

     'ER_WARN_ON_MODIFYING_GTID_EXECUTED_TABLE' was added in 5.7.8.

   *
     Error: '3130' SQLSTATE: 'HY000'
     ('ER_PLUGGABLE_PROTOCOL_COMMAND_NOT_SUPPORTED')

     Message: Command not supported by pluggable protocols

     'ER_PLUGGABLE_PROTOCOL_COMMAND_NOT_SUPPORTED' was added in 5.7.8.

   *
     Error: '3131' SQLSTATE: '42000' ('ER_LOCKING_SERVICE_WRONG_NAME')

     Message: Incorrect locking service lock name '%s'.

     A locking service name was specified as 'NULL', the empty string,
     or a string longer than 64 characters.  Namespace and lock names
     must be non-'NULL', nonempty, and no more than 64 characters long.

     'ER_LOCKING_SERVICE_WRONG_NAME' was added in 5.7.8.

   *
     Error: '3132' SQLSTATE: 'HY000' ('ER_LOCKING_SERVICE_DEADLOCK')

     Message: Deadlock found when trying to get locking service lock;
     try releasing locks and restarting lock acquisition.

     'ER_LOCKING_SERVICE_DEADLOCK' was added in 5.7.8.

   *
     Error: '3133' SQLSTATE: 'HY000' ('ER_LOCKING_SERVICE_TIMEOUT')

     Message: Service lock wait timeout exceeded.

     'ER_LOCKING_SERVICE_TIMEOUT' was added in 5.7.8.

   *
     Error: '3134' SQLSTATE: 'HY000'
     ('ER_GIS_MAX_POINTS_IN_GEOMETRY_OVERFLOWED')

     Message: Parameter %s exceeds the maximum number of points in a
     geometry (%lu) in function %s.

     'ER_GIS_MAX_POINTS_IN_GEOMETRY_OVERFLOWED' was added in 5.7.8.

   *
     Error: '3135' SQLSTATE: 'HY000' ('ER_SQL_MODE_MERGED')

     Message: 'NO_ZERO_DATE', 'NO_ZERO_IN_DATE' and
     'ERROR_FOR_DIVISION_BY_ZERO' sql modes should be used with strict
     mode.  They will be merged with strict mode in a future release.

     'ER_SQL_MODE_MERGED' was added in 5.7.8.

   *
     Error: '3136' SQLSTATE: 'HY000' ('ER_VTOKEN_PLUGIN_TOKEN_MISMATCH')

     Message: Version token mismatch for %.*s.  Correct value %.*s

     The client has set its 'version_tokens_session' system variable to
     the list of tokens it requires the server to match, but the server
     token list has at least one matching token name that has a value
     different from what the client requires.  See
     version-tokens.

     'ER_VTOKEN_PLUGIN_TOKEN_MISMATCH' was added in 5.7.8.

   *
     Error: '3137' SQLSTATE: 'HY000'
     ('ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND')

     Message: Version token %.*s not found.

     The client has set its 'version_tokens_session' system variable to
     the list of tokens it requires the server to match, but the server
     token list is missing at least one of those tokens.  See
     version-tokens.

     'ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND' was added in 5.7.8.

   *
     Error: '3138' SQLSTATE: 'HY000'
     ('ER_CANT_SET_VARIABLE_WHEN_OWNING_GTID')

     Message: Variable %s cannot be changed by a client that owns a
     GTID. The client owns %s.  Ownership is released on COMMIT or
     ROLLBACK.

     'ER_CANT_SET_VARIABLE_WHEN_OWNING_GTID' was added in 5.7.8.

   *
     Error: '3139' SQLSTATE: 'HY000'
     ('ER_SLAVE_CHANNEL_OPERATION_NOT_ALLOWED')

     Message: %s cannot be performed on channel '%s'.

     'ER_SLAVE_CHANNEL_OPERATION_NOT_ALLOWED' was added in 5.7.8.

   *
     Error: '3140' SQLSTATE: '22032' ('ER_INVALID_JSON_TEXT')

     Message: Invalid JSON text: "%s" at position %u in value for column
     '%s'.

     'ER_INVALID_JSON_TEXT' was added in 5.7.8.

   *
     Error: '3141' SQLSTATE: '22032' ('ER_INVALID_JSON_TEXT_IN_PARAM')

     Message: Invalid JSON text in argument %u to function %s: "%s" at
     position %u.%s

     'ER_INVALID_JSON_TEXT_IN_PARAM' was added in 5.7.8.

   *
     Error: '3142' SQLSTATE: 'HY000' ('ER_INVALID_JSON_BINARY_DATA')

     Message: The JSON binary value contains invalid data.

     'ER_INVALID_JSON_BINARY_DATA' was added in 5.7.8.

   *
     Error: '3143' SQLSTATE: '42000' ('ER_INVALID_JSON_PATH')

     Message: Invalid JSON path expression.  The error is around
     character position %u.%s

     'ER_INVALID_JSON_PATH' was added in 5.7.8.

   *
     Error: '3144' SQLSTATE: '22032' ('ER_INVALID_JSON_CHARSET')

     Message: Cannot create a JSON value from a string with CHARACTER
     SET '%s'.

     'ER_INVALID_JSON_CHARSET' was added in 5.7.8.

   *
     Error: '3145' SQLSTATE: '22032'
     ('ER_INVALID_JSON_CHARSET_IN_FUNCTION')

     Message: Invalid JSON character data provided to function %s: '%s';
     utf8 is required.

     'ER_INVALID_JSON_CHARSET_IN_FUNCTION' was added in 5.7.8.

   *
     Error: '3146' SQLSTATE: '22032' ('ER_INVALID_TYPE_FOR_JSON')

     Message: Invalid data type for JSON data in argument %u to function
     %s; a JSON string or JSON type is required.

     'ER_INVALID_TYPE_FOR_JSON' was added in 5.7.8.

   *
     Error: '3147' SQLSTATE: '22032' ('ER_INVALID_CAST_TO_JSON')

     Message: Cannot CAST value to JSON.

     'ER_INVALID_CAST_TO_JSON' was added in 5.7.8.

   *
     Error: '3148' SQLSTATE: '42000' ('ER_INVALID_JSON_PATH_CHARSET')

     Message: A path expression must be encoded in the utf8 character
     set.  The path expression '%s' is encoded in character set '%s'.

     'ER_INVALID_JSON_PATH_CHARSET' was added in 5.7.8.

   *
     Error: '3149' SQLSTATE: '42000' ('ER_INVALID_JSON_PATH_WILDCARD')

     Message: In this situation, path expressions may not contain the *
     and ** tokens.

     'ER_INVALID_JSON_PATH_WILDCARD' was added in 5.7.8.

   *
     Error: '3150' SQLSTATE: '22032' ('ER_JSON_VALUE_TOO_BIG')

     Message: The JSON value is too big to be stored in a JSON column.

     'ER_JSON_VALUE_TOO_BIG' was added in 5.7.8.

   *
     Error: '3151' SQLSTATE: '22032' ('ER_JSON_KEY_TOO_BIG')

     Message: The JSON object contains a key name that is too long.

     'ER_JSON_KEY_TOO_BIG' was added in 5.7.8.

   *
     Error: '3152' SQLSTATE: '42000' ('ER_JSON_USED_AS_KEY')

     Message: JSON column '%s' cannot be used in key specification.

     'ER_JSON_USED_AS_KEY' was added in 5.7.8.

   *
     Error: '3153' SQLSTATE: '42000' ('ER_JSON_VACUOUS_PATH')

     Message: The path expression '$' is not allowed in this context.

     'ER_JSON_VACUOUS_PATH' was added in 5.7.8.

   *
     Error: '3154' SQLSTATE: '42000' ('ER_JSON_BAD_ONE_OR_ALL_ARG')

     Message: The oneOrAll argument to %s may take these values: 'one'
     or 'all'.

     'ER_JSON_BAD_ONE_OR_ALL_ARG' was added in 5.7.8.

   *
     Error: '3155' SQLSTATE: '22003'
     ('ER_NUMERIC_JSON_VALUE_OUT_OF_RANGE')

     Message: Out of range JSON value for CAST to %s%s from column %s at
     row %ld

     'ER_NUMERIC_JSON_VALUE_OUT_OF_RANGE' was added in 5.7.8.

   *
     Error: '3156' SQLSTATE: '22018' ('ER_INVALID_JSON_VALUE_FOR_CAST')

     Message: Invalid JSON value for CAST to %s%s from column %s at row
     %ld

     'ER_INVALID_JSON_VALUE_FOR_CAST' was added in 5.7.8.

   *
     Error: '3157' SQLSTATE: '22032' ('ER_JSON_DOCUMENT_TOO_DEEP')

     Message: The JSON document exceeds the maximum depth.

     'ER_JSON_DOCUMENT_TOO_DEEP' was added in 5.7.8.

   *
     Error: '3158' SQLSTATE: '22032' ('ER_JSON_DOCUMENT_NULL_KEY')

     Message: JSON documents may not contain NULL member names.

     'ER_JSON_DOCUMENT_NULL_KEY' was added in 5.7.8.

   *
     Error: '3159' SQLSTATE: 'HY000' ('ER_SECURE_TRANSPORT_REQUIRED')

     Message: Connections using insecure transport are prohibited while
     -require_secure_transport=ON.

     With the 'require_secure_transport' system variable, clients can
     connect only using secure transports.  Qualifying connections are
     those using SSL, a Unix socket file, or shared memory.

     'ER_SECURE_TRANSPORT_REQUIRED' was added in 5.7.8.

   *
     Error: '3160' SQLSTATE: 'HY000'
     ('ER_NO_SECURE_TRANSPORTS_CONFIGURED')

     Message: No secure transports (SSL or Shared Memory) are
     configured, unable to set -require_secure_transport=ON.

     The 'require_secure_transport' system variable cannot be enabled if
     the server does not support at least one secure transport.
     Configure the server with the required SSL keys/certificates to
     enable SSL connections, or enable the 'shared_memory' system
     variable to enable shared-memory connections.

     'ER_NO_SECURE_TRANSPORTS_CONFIGURED' was added in 5.7.8.

   *
     Error: '3161' SQLSTATE: 'HY000' ('ER_DISABLED_STORAGE_ENGINE')

     Message: Storage engine %s is disabled (Table creation is
     disallowed).

     An attempt was made to create a table or tablespace using a storage
     engine listed in the value of the 'disabled_storage_engines' system
     variable, or to change an existing table or tablespace to such an
     engine.  Choose a different storage engine.

     'ER_DISABLED_STORAGE_ENGINE' was added in 5.7.8.

   *
     Error: '3162' SQLSTATE: 'HY000' ('ER_USER_DOES_NOT_EXIST')

     Message: User %s does not exist.

     'ER_USER_DOES_NOT_EXIST' was added in 5.7.8.

   *
     Error: '3163' SQLSTATE: 'HY000' ('ER_USER_ALREADY_EXISTS')

     Message: User %s already exists.

     'ER_USER_ALREADY_EXISTS' was added in 5.7.8.

   *
     Error: '3164' SQLSTATE: 'HY000' ('ER_AUDIT_API_ABORT')

     Message: Aborted by Audit API ('%s';%d).

     This error indicates that an audit plugin terminated execution of
     an event.  The message typically indicates the event subclass name
     and a numeric status value.

     'ER_AUDIT_API_ABORT' was added in 5.7.8.

   *
     Error: '3165' SQLSTATE: '42000' ('ER_INVALID_JSON_PATH_ARRAY_CELL')

     Message: A path expression is not a path to a cell in an array.

     'ER_INVALID_JSON_PATH_ARRAY_CELL' was added in 5.7.8.

   *
     Error: '3166' SQLSTATE: 'HY000' ('ER_BUFPOOL_RESIZE_INPROGRESS')

     Message: Another buffer pool resize is already in progress.

     'ER_BUFPOOL_RESIZE_INPROGRESS' was added in 5.7.9.

   *
     Error: '3167' SQLSTATE: 'HY000' ('ER_FEATURE_DISABLED_SEE_DOC')

     Message: The '%s' feature is disabled; see the documentation for
     '%s'

     'ER_FEATURE_DISABLED_SEE_DOC' was added in 5.7.9.

   *
     Error: '3168' SQLSTATE: 'HY000' ('ER_SERVER_ISNT_AVAILABLE')

     Message: Server isn't available

     'ER_SERVER_ISNT_AVAILABLE' was added in 5.7.9.

   *
     Error: '3169' SQLSTATE: 'HY000' ('ER_SESSION_WAS_KILLED')

     Message: Session was killed

     'ER_SESSION_WAS_KILLED' was added in 5.7.9.

   *
     Error: '3170' SQLSTATE: 'HY000' ('ER_CAPACITY_EXCEEDED')

     Message: Memory capacity of %llu bytes for '%s' exceeded.  %s

     'ER_CAPACITY_EXCEEDED' was added in 5.7.9.

   *
     Error: '3171' SQLSTATE: 'HY000'
     ('ER_CAPACITY_EXCEEDED_IN_RANGE_OPTIMIZER')

     Message: Range optimization was not done for this query.

     'ER_CAPACITY_EXCEEDED_IN_RANGE_OPTIMIZER' was added in 5.7.9.

   *
     Error: '3172' SQLSTATE: 'HY000' ('ER_TABLE_NEEDS_UPG_PART')

     Message: Partitioning upgrade required.  Please dump/reload to fix
     it or do: ALTER TABLE '%s'.'%s' UPGRADE PARTITIONING

     'ER_TABLE_NEEDS_UPG_PART' was added in 5.7.9.

   *
     Error: '3173' SQLSTATE: 'HY000'
     ('ER_CANT_WAIT_FOR_EXECUTED_GTID_SET_WHILE_OWNING_A_GTID')

     Message: The client holds ownership of the GTID %s.  Therefore,
     WAIT_FOR_EXECUTED_GTID_SET cannot wait for this GTID.

     'ER_CANT_WAIT_FOR_EXECUTED_GTID_SET_WHILE_OWNING_A_GTID' was added
     in 5.7.9.

   *
     Error: '3174' SQLSTATE: 'HY000'
     ('ER_CANNOT_ADD_FOREIGN_BASE_COL_VIRTUAL')

     Message: Cannot add foreign key on the base column of indexed
     virtual column.

     'ER_CANNOT_ADD_FOREIGN_BASE_COL_VIRTUAL' was added in 5.7.10.

   *
     Error: '3175' SQLSTATE: 'HY000'
     ('ER_CANNOT_CREATE_VIRTUAL_INDEX_CONSTRAINT')

     Message: Cannot create index on virtual column whose base column
     has foreign constraint.

     'ER_CANNOT_CREATE_VIRTUAL_INDEX_CONSTRAINT' was added in 5.7.10.

   *
     Error: '3176' SQLSTATE: 'HY000'
     ('ER_ERROR_ON_MODIFYING_GTID_EXECUTED_TABLE')

     Message: Please do not modify the %s table with an XA transaction.
     This is an internal system table used to store GTIDs for committed
     transactions.  Although modifying it can lead to an inconsistent
     GTID state, if neccessary you can modify it with a non-XA
     transaction.

     'ER_ERROR_ON_MODIFYING_GTID_EXECUTED_TABLE' was added in 5.7.11.

   *
     Error: '3177' SQLSTATE: 'HY000' ('ER_LOCK_REFUSED_BY_ENGINE')

     Message: Lock acquisition refused by storage engine.

     'ER_LOCK_REFUSED_BY_ENGINE' was added in 5.7.11.

   *
     Error: '3178' SQLSTATE: 'HY000'
     ('ER_UNSUPPORTED_ALTER_ONLINE_ON_VIRTUAL_COLUMN')

     Message: ADD COLUMN col...VIRTUAL, ADD INDEX(col)

     'ER_UNSUPPORTED_ALTER_ONLINE_ON_VIRTUAL_COLUMN' was added in
     5.7.11.

   *
     Error: '3179' SQLSTATE: 'HY000'
     ('ER_MASTER_KEY_ROTATION_NOT_SUPPORTED_BY_SE')

     Message: Master key rotation is not supported by storage engine.

     'ER_MASTER_KEY_ROTATION_NOT_SUPPORTED_BY_SE' was added in 5.7.11.

   *
     Error: '3180' SQLSTATE: 'HY000'
     ('ER_MASTER_KEY_ROTATION_ERROR_BY_SE')

     Message: Encryption key rotation error reported by SE: %s

     'ER_MASTER_KEY_ROTATION_ERROR_BY_SE' was added in 5.7.11.

   *
     Error: '3181' SQLSTATE: 'HY000'
     ('ER_MASTER_KEY_ROTATION_BINLOG_FAILED')

     Message: Write to binlog failed.  However, master key rotation has
     been completed successfully.

     'ER_MASTER_KEY_ROTATION_BINLOG_FAILED' was added in 5.7.11.

   *
     Error: '3182' SQLSTATE: 'HY000'
     ('ER_MASTER_KEY_ROTATION_SE_UNAVAILABLE')

     Message: Storage engine is not available.

     'ER_MASTER_KEY_ROTATION_SE_UNAVAILABLE' was added in 5.7.11.

   *
     Error: '3183' SQLSTATE: 'HY000' ('ER_TABLESPACE_CANNOT_ENCRYPT')

     Message: This tablespace can't be encrypted.

     'ER_TABLESPACE_CANNOT_ENCRYPT' was added in 5.7.11.

   *
     Error: '3184' SQLSTATE: 'HY000' ('ER_INVALID_ENCRYPTION_OPTION')

     Message: Invalid encryption option.

     'ER_INVALID_ENCRYPTION_OPTION' was added in 5.7.11.

   *
     Error: '3185' SQLSTATE: 'HY000' ('ER_CANNOT_FIND_KEY_IN_KEYRING')

     Message: Can't find master key from keyring, please check in the
     server log if a keyring plugin is loaded and initialized
     successfully.

     'ER_CANNOT_FIND_KEY_IN_KEYRING' was added in 5.7.11.

   *
     Error: '3186' SQLSTATE: 'HY000' ('ER_CAPACITY_EXCEEDED_IN_PARSER')

     Message: Parser bailed out for this query.

     'ER_CAPACITY_EXCEEDED_IN_PARSER' was added in 5.7.12.

   *
     Error: '3187' SQLSTATE: 'HY000'
     ('ER_UNSUPPORTED_ALTER_ENCRYPTION_INPLACE')

     Message: Cannot alter encryption attribute by inplace algorithm.

     'ER_UNSUPPORTED_ALTER_ENCRYPTION_INPLACE' was added in 5.7.13.

   *
     Error: '3188' SQLSTATE: 'HY000'
     ('ER_KEYRING_UDF_KEYRING_SERVICE_ERROR')

     Message: Function '%s' failed because underlying keyring service
     returned an error.  Please check if a keyring plugin is installed
     and that provided arguments are valid for the keyring you are
     using.

     'ER_KEYRING_UDF_KEYRING_SERVICE_ERROR' was added in 5.7.13.

   *
     Error: '3189' SQLSTATE: 'HY000' ('ER_USER_COLUMN_OLD_LENGTH')

     Message: It seems that your db schema is old.  The %s column is 77
     characters long and should be 93 characters long.  Please run
     mysql_upgrade.

     'ER_USER_COLUMN_OLD_LENGTH' was added in 5.7.13.

   *
     Error: '3190' SQLSTATE: 'HY000' ('ER_CANT_RESET_MASTER')

     Message: RESET MASTER is not allowed because %s.

     'ER_CANT_RESET_MASTER' was added in 5.7.14.

   *
     Error: '3191' SQLSTATE: 'HY000'
     ('ER_GROUP_REPLICATION_MAX_GROUP_SIZE')

     Message: The START GROUP_REPLICATION command failed since the group
     already has 9 members.

     'ER_GROUP_REPLICATION_MAX_GROUP_SIZE' was added in 5.7.14.

   *
     Error: '3192' SQLSTATE: 'HY000'
     ('ER_CANNOT_ADD_FOREIGN_BASE_COL_STORED')

     Message: Cannot add foreign key on the base column of stored
     column.

     'ER_CANNOT_ADD_FOREIGN_BASE_COL_STORED' was added in 5.7.14.

   *
     Error: '3193' SQLSTATE: 'HY000' ('ER_TABLE_REFERENCED')

     Message: Cannot complete the operation because table is referenced
     by another connection.

     'ER_TABLE_REFERENCED' was added in 5.7.14.

   *
     Error: '3194' SQLSTATE: 'HY000'
     ('ER_PARTITION_ENGINE_DEPRECATED_FOR_TABLE')

     Message: The partition engine, used by table '%s.%s', is deprecated
     and will be removed in a future release.  Please use native
     partitioning instead.

     'ER_PARTITION_ENGINE_DEPRECATED_FOR_TABLE' was added in 5.7.17.

   *
     Error: '3195' SQLSTATE: '01000'
     ('ER_WARN_USING_GEOMFROMWKB_TO_SET_SRID_ZERO')

     Message: %s(geometry) is deprecated and will be replaced by
     st_srid(geometry, 0) in a future version.  Use
     %s(st_aswkb(geometry), 0) instead.

     'ER_WARN_USING_GEOMFROMWKB_TO_SET_SRID_ZERO' was added in 5.7.19.

   *
     Error: '3196' SQLSTATE: '01000'
     ('ER_WARN_USING_GEOMFROMWKB_TO_SET_SRID')

     Message: %s(geometry, srid) is deprecated and will be replaced by
     st_srid(geometry, srid) in a future version.  Use
     %s(st_aswkb(geometry), srid) instead.

     'ER_WARN_USING_GEOMFROMWKB_TO_SET_SRID' was added in 5.7.19.

   *
     Error: '3197' SQLSTATE: 'HY000' ('ER_XA_RETRY')

     Message: The resource manager is not able to commit the transaction
     branch at this time.  Please retry later.

     'ER_XA_RETRY' was added in 5.7.19.

   *
     Error: '3198' SQLSTATE: 'HY000'
     ('ER_KEYRING_AWS_UDF_AWS_KMS_ERROR')

     Message: Function %s failed due to: %s.

     'ER_KEYRING_AWS_UDF_AWS_KMS_ERROR' was added in 5.7.19.

   *
     Error: '3199' SQLSTATE: 'HY000' ('ER_BINLOG_UNSAFE_XA')

     Message: Statement is unsafe because it is being used inside a XA
     transaction.  Concurrent XA transactions may deadlock on slaves
     when replicated using statements.

     'ER_BINLOG_UNSAFE_XA' was added in 5.7.20.

   *
     Error: '3200' SQLSTATE: 'HY000' ('ER_UDF_ERROR')

     Message: %s UDF failed; %s

     'ER_UDF_ERROR' was added in 5.7.21.

   *
     Error: '3201' SQLSTATE: 'HY000' ('ER_KEYRING_MIGRATION_FAILURE')

     Message: Can not perform keyring migration : %s

     'ER_KEYRING_MIGRATION_FAILURE' was added in 5.7.21.

   *
     Error: '3202' SQLSTATE: '42000' ('ER_KEYRING_ACCESS_DENIED_ERROR')

     Message: Access denied; you need %s privileges for this operation

     'ER_KEYRING_ACCESS_DENIED_ERROR' was added in 5.7.21.

   *
     Error: '3203' SQLSTATE: 'HY000' ('ER_KEYRING_MIGRATION_STATUS')

     Message: Keyring migration %s.

     'ER_KEYRING_MIGRATION_STATUS' was added in 5.7.21.

   *
     Error: '3204' SQLSTATE: 'HY000' ('ER_PLUGIN_FAILED_TO_OPEN_TABLES')

     Message: Failed to open the %s filter tables.

     'ER_PLUGIN_FAILED_TO_OPEN_TABLES' was added in 5.7.22.

   *
     Error: '3205' SQLSTATE: 'HY000' ('ER_PLUGIN_FAILED_TO_OPEN_TABLE')

     Message: Failed to open '%s.%s' %s table.

     'ER_PLUGIN_FAILED_TO_OPEN_TABLE' was added in 5.7.22.

   *
     Error: '3206' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_NO_KEYRING_PLUGIN_INSTALLED')

     Message: No keyring plugin installed.

     'ER_AUDIT_LOG_NO_KEYRING_PLUGIN_INSTALLED' was added in 5.7.22.

   *
     Error: '3207' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_ENCRYPTION_PASSWORD_HAS_NOT_BEEN_SET')

     Message: Audit log encryption password has not been set; it will be
     generated automatically.  Use audit_log_encryption_password_get to
     obtain the password or audit_log_encryption_password_set to set a
     new one.

     'ER_AUDIT_LOG_ENCRYPTION_PASSWORD_HAS_NOT_BEEN_SET' was added in
     5.7.22.

   *
     Error: '3208' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_COULD_NOT_CREATE_AES_KEY')

     Message: Could not create AES key.  OpenSSL's EVP_BytesToKey
     function failed.

     'ER_AUDIT_LOG_COULD_NOT_CREATE_AES_KEY' was added in 5.7.22.

   *
     Error: '3209' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_ENCRYPTION_PASSWORD_CANNOT_BE_FETCHED')

     Message: Audit log encryption password cannot be fetched from the
     keyring.  Password used so far is used for encryption.

     'ER_AUDIT_LOG_ENCRYPTION_PASSWORD_CANNOT_BE_FETCHED' was added in
     5.7.22.

   *
     Error: '3210' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_JSON_FILTERING_NOT_ENABLED')

     Message: Audit Log filtering has not been installed.

     'ER_AUDIT_LOG_JSON_FILTERING_NOT_ENABLED' was added in 5.7.22.

   *
     Error: '3211' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_UDF_INSUFFICIENT_PRIVILEGE')

     Message: Request ignored for '%s'@'%s'.  SUPER_ACL needed to
     perform operation

     'ER_AUDIT_LOG_UDF_INSUFFICIENT_PRIVILEGE' was added in 5.7.22.

   *
     Error: '3212' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_SUPER_PRIVILEGE_REQUIRED')

     Message: SUPER privilege required for '%s'@'%s' user.

     'ER_AUDIT_LOG_SUPER_PRIVILEGE_REQUIRED' was added in 5.7.22.

   *
     Error: '3213' SQLSTATE: 'HY000'
     ('ER_COULD_NOT_REINITIALIZE_AUDIT_LOG_FILTERS')

     Message: Could not reinitialize audit log filters.

     'ER_COULD_NOT_REINITIALIZE_AUDIT_LOG_FILTERS' was added in 5.7.22.

   *
     Error: '3214' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_UDF_INVALID_ARGUMENT_TYPE')

     Message: Invalid argument type

     'ER_AUDIT_LOG_UDF_INVALID_ARGUMENT_TYPE' was added in 5.7.22.

   *
     Error: '3215' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_UDF_INVALID_ARGUMENT_COUNT')

     Message: Invalid argument count

     'ER_AUDIT_LOG_UDF_INVALID_ARGUMENT_COUNT' was added in 5.7.22.

   *
     Error: '3216' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_HAS_NOT_BEEN_INSTALLED')

     Message: audit_log plugin has not been installed using INSTALL
     PLUGIN syntax.

     'ER_AUDIT_LOG_HAS_NOT_BEEN_INSTALLED' was added in 5.7.22.

   *
     Error: '3217' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_UDF_READ_INVALID_MAX_ARRAY_LENGTH_ARG_TYPE')

     Message: Invalid "max_array_length" argument type.

     'ER_AUDIT_LOG_UDF_READ_INVALID_MAX_ARRAY_LENGTH_ARG_TYPE' was added
     in 5.7.22.

   *
     Error: '3218' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_UDF_READ_INVALID_MAX_ARRAY_LENGTH_ARG_VALUE')

     Message: Invalid "max_array_length" argument value.

     'ER_AUDIT_LOG_UDF_READ_INVALID_MAX_ARRAY_LENGTH_ARG_VALUE' was
     added in 5.7.22.

   *
     Error: '3219' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_JSON_FILTER_PARSING_ERROR')

     Message: %s

     'ER_AUDIT_LOG_JSON_FILTER_PARSING_ERROR' was added in 5.7.22.

   *
     Error: '3220' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_JSON_FILTER_NAME_CANNOT_BE_EMPTY')

     Message: Filter name cannot be empty.

     'ER_AUDIT_LOG_JSON_FILTER_NAME_CANNOT_BE_EMPTY' was added in
     5.7.22.

   *
     Error: '3221' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_JSON_USER_NAME_CANNOT_BE_EMPTY')

     Message: User cannot be empty.

     'ER_AUDIT_LOG_JSON_USER_NAME_CANNOT_BE_EMPTY' was added in 5.7.22.

   *
     Error: '3222' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_JSON_FILTER_DOES_NOT_EXISTS')

     Message: Specified filter has not been found.

     'ER_AUDIT_LOG_JSON_FILTER_DOES_NOT_EXISTS' was added in 5.7.22.

   *
     Error: '3223' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_USER_FIRST_CHARACTER_MUST_BE_ALPHANUMERIC')

     Message: First character of the user name must be alphanumeric.

     'ER_AUDIT_LOG_USER_FIRST_CHARACTER_MUST_BE_ALPHANUMERIC' was added
     in 5.7.22.

   *
     Error: '3224' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_USER_NAME_INVALID_CHARACTER')

     Message: Invalid character in the user name.

     'ER_AUDIT_LOG_USER_NAME_INVALID_CHARACTER' was added in 5.7.22.

   *
     Error: '3225' SQLSTATE: 'HY000'
     ('ER_AUDIT_LOG_HOST_NAME_INVALID_CHARACTER')

     Message: Invalid character in the host name.

     'ER_AUDIT_LOG_HOST_NAME_INVALID_CHARACTER' was added in 5.7.22.

   *
     Error: '3226' SQLSTATE: 'HY000'
     ('WARN_DEPRECATED_MAXDB_SQL_MODE_FOR_TIMESTAMP')

     Message: With the MAXDB SQL mode enabled, TIMESTAMP is identical
     with DATETIME. The MAXDB SQL mode is deprecated and will be removed
     in a future release.  Please disable the MAXDB SQL mode and use
     DATETIME instead.

     'WARN_DEPRECATED_MAXDB_SQL_MODE_FOR_TIMESTAMP' was added in 5.7.22.

   *
     Error: '3227' SQLSTATE: 'HY000' ('ER_XA_REPLICATION_FILTERS')

     Message: The use of replication filters with XA transactions is not
     supported, and can lead to an undefined state in the replication
     slave.

     'ER_XA_REPLICATION_FILTERS' was added in 5.7.23.

B.4 Client Error Codes and Messages
===================================

Client error information comes from the following source files:

   * The Error values and the symbols in parentheses correspond to
     definitions in the 'include/errmsg.h' MySQL source file.

   * The Message values correspond to the error messages that are listed
     in the 'libmysql/errmsg.c' file.  '%d' and '%s' represent numbers
     and strings, respectively, that are substituted into the messages
     when they are displayed.

Because updates are frequent, it is possible that those files will
contain additional error information not listed here.

   *
     Error: '2000' ('CR_UNKNOWN_ERROR')

     Message: Unknown MySQL error

   *
     Error: '2001' ('CR_SOCKET_CREATE_ERROR')

     Message: Can't create UNIX socket (%d)

   *
     Error: '2002' ('CR_CONNECTION_ERROR')

     Message: Can't connect to local MySQL server through socket '%s'
     (%d)

   *
     Error: '2003' ('CR_CONN_HOST_ERROR')

     Message: Can't connect to MySQL server on '%s' (%d)

   *
     Error: '2004' ('CR_IPSOCK_ERROR')

     Message: Can't create TCP/IP socket (%d)

   *
     Error: '2005' ('CR_UNKNOWN_HOST')

     Message: Unknown MySQL server host '%s' (%d)

   *
     Error: '2006' ('CR_SERVER_GONE_ERROR')

     Message: MySQL server has gone away

   *
     Error: '2007' ('CR_VERSION_ERROR')

     Message: Protocol mismatch; server version = %d, client version =
     %d

   *
     Error: '2008' ('CR_OUT_OF_MEMORY')

     Message: MySQL client ran out of memory

   *
     Error: '2009' ('CR_WRONG_HOST_INFO')

     Message: Wrong host info

   *
     Error: '2010' ('CR_LOCALHOST_CONNECTION')

     Message: Localhost via UNIX socket

   *
     Error: '2011' ('CR_TCP_CONNECTION')

     Message: %s via TCP/IP

   *
     Error: '2012' ('CR_SERVER_HANDSHAKE_ERR')

     Message: Error in server handshake

   *
     Error: '2013' ('CR_SERVER_LOST')

     Message: Lost connection to MySQL server during query

   *
     Error: '2014' ('CR_COMMANDS_OUT_OF_SYNC')

     Message: Commands out of sync; you can't run this command now

   *
     Error: '2015' ('CR_NAMEDPIPE_CONNECTION')

     Message: Named pipe: %s

   *
     Error: '2016' ('CR_NAMEDPIPEWAIT_ERROR')

     Message: Can't wait for named pipe to host: %s pipe: %s (%lu)

   *
     Error: '2017' ('CR_NAMEDPIPEOPEN_ERROR')

     Message: Can't open named pipe to host: %s pipe: %s (%lu)

   *
     Error: '2018' ('CR_NAMEDPIPESETSTATE_ERROR')

     Message: Can't set state of named pipe to host: %s pipe: %s (%lu)

   *
     Error: '2019' ('CR_CANT_READ_CHARSET')

     Message: Can't initialize character set %s (path: %s)

   *
     Error: '2020' ('CR_NET_PACKET_TOO_LARGE')

     Message: Got packet bigger than 'max_allowed_packet' bytes

   *
     Error: '2021' ('CR_EMBEDDED_CONNECTION')

     Message: Embedded server

   *
     Error: '2022' ('CR_PROBE_SLAVE_STATUS')

     Message: Error on SHOW SLAVE STATUS:

   *
     Error: '2023' ('CR_PROBE_SLAVE_HOSTS')

     Message: Error on SHOW SLAVE HOSTS:

   *
     Error: '2024' ('CR_PROBE_SLAVE_CONNECT')

     Message: Error connecting to slave:

   *
     Error: '2025' ('CR_PROBE_MASTER_CONNECT')

     Message: Error connecting to master:

   *
     Error: '2026' ('CR_SSL_CONNECTION_ERROR')

     Message: SSL connection error: %s

   *
     Error: '2027' ('CR_MALFORMED_PACKET')

     Message: Malformed packet

   *
     Error: '2028' ('CR_WRONG_LICENSE')

     Message: This client library is licensed only for use with MySQL
     servers having '%s' license

   *
     Error: '2029' ('CR_NULL_POINTER')

     Message: Invalid use of null pointer

   *
     Error: '2030' ('CR_NO_PREPARE_STMT')

     Message: Statement not prepared

   *
     Error: '2031' ('CR_PARAMS_NOT_BOUND')

     Message: No data supplied for parameters in prepared statement

   *
     Error: '2032' ('CR_DATA_TRUNCATED')

     Message: Data truncated

   *
     Error: '2033' ('CR_NO_PARAMETERS_EXISTS')

     Message: No parameters exist in the statement

   *
     Error: '2034' ('CR_INVALID_PARAMETER_NO')

     Message: Invalid parameter number

     The column number for 'mysql_stmt_fetch_column()'
     was invalid.

     The parameter number for 'mysql_stmt_send_long_data()'
     was invalid.

     A key name was empty or the amount of connection attribute data for
     'mysql_options4()' exceeds the 64KB limit.

   *
     Error: '2035' ('CR_INVALID_BUFFER_USE')

     Message: Can't send long data for non-string/non-binary data types
     (parameter: %d)

   *
     Error: '2036' ('CR_UNSUPPORTED_PARAM_TYPE')

     Message: Using unsupported buffer type: %d (parameter: %d)

   *
     Error: '2037' ('CR_SHARED_MEMORY_CONNECTION')

     Message: Shared memory: %s

   *
     Error: '2038' ('CR_SHARED_MEMORY_CONNECT_REQUEST_ERROR')

     Message: Can't open shared memory; client could not create request
     event (%lu)

   *
     Error: '2039' ('CR_SHARED_MEMORY_CONNECT_ANSWER_ERROR')

     Message: Can't open shared memory; no answer event received from
     server (%lu)

   *
     Error: '2040' ('CR_SHARED_MEMORY_CONNECT_FILE_MAP_ERROR')

     Message: Can't open shared memory; server could not allocate file
     mapping (%lu)

   *
     Error: '2041' ('CR_SHARED_MEMORY_CONNECT_MAP_ERROR')

     Message: Can't open shared memory; server could not get pointer to
     file mapping (%lu)

   *
     Error: '2042' ('CR_SHARED_MEMORY_FILE_MAP_ERROR')

     Message: Can't open shared memory; client could not allocate file
     mapping (%lu)

   *
     Error: '2043' ('CR_SHARED_MEMORY_MAP_ERROR')

     Message: Can't open shared memory; client could not get pointer to
     file mapping (%lu)

   *
     Error: '2044' ('CR_SHARED_MEMORY_EVENT_ERROR')

     Message: Can't open shared memory; client could not create %s event
     (%lu)

   *
     Error: '2045' ('CR_SHARED_MEMORY_CONNECT_ABANDONED_ERROR')

     Message: Can't open shared memory; no answer from server (%lu)

   *
     Error: '2046' ('CR_SHARED_MEMORY_CONNECT_SET_ERROR')

     Message: Can't open shared memory; cannot send request event to
     server (%lu)

   *
     Error: '2047' ('CR_CONN_UNKNOW_PROTOCOL')

     Message: Wrong or unknown protocol

   *
     Error: '2048' ('CR_INVALID_CONN_HANDLE')

     Message: Invalid connection handle

   *
     Error: '2049' ('CR_SECURE_AUTH')

     Message: Connection using old (pre-4.1.1) authentication protocol
     refused (client option 'secure_auth' enabled)

     'CR_SECURE_AUTH' was removed after 5.7.4.

   *
     Error: '2049' ('CR_UNUSED_1')

     Message: Connection using old (pre-4.1.1) authentication protocol
     refused (client option 'secure_auth' enabled)

     'CR_UNUSED_1' was added in 5.7.5.

   *
     Error: '2050' ('CR_FETCH_CANCELED')

     Message: Row retrieval was canceled by mysql_stmt_close() call

   *
     Error: '2051' ('CR_NO_DATA')

     Message: Attempt to read column without prior row fetch

   *
     Error: '2052' ('CR_NO_STMT_METADATA')

     Message: Prepared statement contains no metadata

   *
     Error: '2053' ('CR_NO_RESULT_SET')

     Message: Attempt to read a row while there is no result set
     associated with the statement

   *
     Error: '2054' ('CR_NOT_IMPLEMENTED')

     Message: This feature is not implemented yet

   *
     Error: '2055' ('CR_SERVER_LOST_EXTENDED')

     Message: Lost connection to MySQL server at '%s', system error: %d

   *
     Error: '2056' ('CR_STMT_CLOSED')

     Message: Statement closed indirectly because of a preceding %s()
     call

   *
     Error: '2057' ('CR_NEW_STMT_METADATA')

     Message: The number of columns in the result set differs from the
     number of bound buffers.  You must reset the statement, rebind the
     result set columns, and execute the statement again

   *
     Error: '2058' ('CR_ALREADY_CONNECTED')

     Message: This handle is already connected.  Use a separate handle
     for each connection.

   *
     Error: '2059' ('CR_AUTH_PLUGIN_CANNOT_LOAD')

     Message: Authentication plugin '%s' cannot be loaded: %s

   *
     Error: '2060' ('CR_DUPLICATE_CONNECTION_ATTR')

     Message: There is an attribute with the same name already

     A duplicate connection attribute name was specified for
     'mysql_options4()'.

   *
     Error: '2061' ('CR_AUTH_PLUGIN_ERR')

     Message: Authentication plugin '%s' reported error: %s

     'CR_AUTH_PLUGIN_ERR' was added in 5.7.1.

   *
     Error: '2062' ('CR_INSECURE_API_ERR')

     Message: Insecure API function call: '%s' Use instead: '%s'

     An insecure function call was detected.  Modify the application to
     use the suggested alternative function instead.

     'CR_INSECURE_API_ERR' was added in 5.7.6.

B.5 Problems and Common Errors
==============================

This section lists some common problems and error messages that you may
encounter.  It describes how to determine the causes of the problems and
what to do to solve them.

B.5.1 How to Determine What Is Causing a Problem
------------------------------------------------

When you run into a problem, the first thing you should do is to find
out which program or piece of equipment is causing it:

   * If you have one of the following symptoms, then it is probably a
     hardware problems (such as memory, motherboard, CPU, or hard disk)
     or kernel problem:

        * The keyboard does not work.  This can normally be checked by
          pressing the Caps Lock key.  If the Caps Lock light does not
          change, you have to replace your keyboard.  (Before doing
          this, you should try to restart your computer and check all
          cables to the keyboard.)

        * The mouse pointer does not move.

        * The machine does not answer to a remote machine's pings.

        * Other programs that are not related to MySQL do not behave
          correctly.

        * Your system restarted unexpectedly.  (A faulty user-level
          program should never be able to take down your system.)

     In this case, you should start by checking all your cables and run
     some diagnostic tool to check your hardware!  You should also check
     whether there are any patches, updates, or service packs for your
     operating system that could likely solve your problem.  Check also
     that all your libraries (such as 'glibc') are up to date.

     It is always good to use a machine with ECC memory to discover
     memory problems early.

   * If your keyboard is locked up, you may be able to recover by
     logging in to your machine from another machine and executing
     'kbd_mode -a'.

   * Please examine your system log file ('/var/log/messages' or
     similar) for reasons for your problem.  If you think the problem is
     in MySQL, you should also examine MySQL's log files.  See
     server-logs.

   * If you do not think you have hardware problems, you should try to
     find out which program is causing problems.  Try using 'top', 'ps',
     Task Manager, or some similar program, to check which program is
     taking all CPU or is locking the machine.

   * Use 'top', 'df', or a similar program to check whether you are out
     of memory, disk space, file descriptors, or some other critical
     resource.

   * If the problem is some runaway process, you can always try to kill
     it.  If it does not want to die, there is probably a bug in the
     operating system.

If after you have examined all other possibilities and you have
concluded that the MySQL server or a MySQL client is causing the
problem, it is time to create a bug report for our mailing list or our
support team.  In the bug report, try to give a very detailed
description of how the system is behaving and what you think is
happening.  You should also state why you think that MySQL is causing
the problem.  Take into consideration all the situations in this
chapter.  State any problems exactly how they appear when you examine
your system.  Use the 'copy and paste' method for any output and error
messages from programs and log files.

Try to describe in detail which program is not working and all symptoms
you see.  We have in the past received many bug reports that state only
'the system does not work.' This provides us with no information about
what could be the problem.

If a program fails, it is always useful to know the following
information:

   * Has the program in question made a segmentation fault (did it dump
     core)?

   * Is the program taking up all available CPU time?  Check with 'top'.
     Let the program run for a while, it may simply be evaluating
     something computationally intensive.

   * If the 'mysqld' server is causing problems, can you
     get any response from it with 'mysqladmin -u root ping'
     or 'mysqladmin -u root processlist'.?

   * What does a client program say when you try to connect to the MySQL
     server?  (Try with 'mysql', for example.)  Does the
     client jam?  Do you get any output from the program?

When sending a bug report, you should follow the outline described in
bug-reports.

B.5.2 Common Errors When Using MySQL Programs
---------------------------------------------

This section lists some errors that users frequently encounter when
running MySQL programs.  Although the problems show up when you try to
run client programs, the solutions to many of the problems involves
changing the configuration of the MySQL server.

B.5.2.1 Access denied
.....................

An 'Access denied' error can have many causes.  Often the problem is
related to the MySQL accounts that the server permits client programs to
use when connecting.  See privilege-system, and
problems-connecting.

B.5.2.2 Can't connect to [local] MySQL server
.............................................

A MySQL client on Unix can connect to the 'mysqld' server
in two different ways: By using a Unix socket file to connect through a
file in the file system (default '/tmp/mysql.sock'), or by using TCP/IP,
which connects through a port number.  A Unix socket file connection is
faster than TCP/IP, but can be used only when connecting to a server on
the same computer.  A Unix socket file is used if you do not specify a
host name or if you specify the special host name 'localhost'.

If the MySQL server is running on Windows, you can connect using TCP/IP.
If the server is started with the '--enable-named-pipe' option, you can
also connect with named pipes if you run the client on the host where
the server is running.  The name of the named pipe is 'MySQL' by
default.  If you do not give a host name when connecting to
'mysqld', a MySQL client first tries to connect to the named
pipe.  If that does not work, it connects to the TCP/IP port.  You can
force the use of named pipes on Windows by using '.' as the host name.

The error (2002) 'Can't connect to ...' normally means that there is no
MySQL server running on the system or that you are using an incorrect
Unix socket file name or TCP/IP port number when trying to connect to
the server.  You should also check that the TCP/IP port you are using
has not been blocked by a firewall or port blocking service.

The error (2003) 'Can't connect to MySQL server on 'SERVER' (10061)'
indicates that the network connection has been refused.  You should
check that there is a MySQL server running, that it has network
connections enabled, and that the network port you specified is the one
configured on the server.

Start by checking whether there is a process named 'mysqld'
running on your server host.  (Use 'ps xa | grep mysqld' on Unix
or the Task Manager on Windows.)  If there is no such process, you
should start the server.  See starting-server.

If a 'mysqld' process is running, you can check it by
trying the following commands.  The port number or Unix socket file name
might be different in your setup.  'host_ip' represents the IP address
of the machine where the server is running.

     shell> mysqladmin version
     shell> mysqladmin variables
     shell> mysqladmin -h `hostname` version variables
     shell> mysqladmin -h `hostname` --port=3306 version
     shell> mysqladmin -h host_ip version
     shell> mysqladmin --protocol=SOCKET --socket=/tmp/mysql.sock version

Note the use of backticks rather than forward quotation marks with the
'hostname' command; these cause the output of 'hostname' (that is, the
current host name) to be substituted into the 'mysqladmin'
command.  If you have no 'hostname' command or are running
on Windows, you can manually type the host name of your machine (without
backticks) following the '-h' option.  You can also try '-h 127.0.0.1'
to connect with TCP/IP to the local host.

Make sure that the server has not been configured to ignore network
connections or (if you are attempting to connect remotely) that it has
not been configured to listen only locally on its network interfaces.
If the server was started with '--skip-networking', it will not accept
TCP/IP connections at all.  If the server was started with
'--bind-address=127.0.0.1', it will listen for TCP/IP connections only
locally on the loopback interface and will not accept remote
connections.

Check to make sure that there is no firewall blocking access to MySQL.
Your firewall may be configured on the basis of the application being
executed, or the port number used by MySQL for communication (3306 by
default).  Under Linux or Unix, check your IP tables (or similar)
configuration to ensure that the port has not been blocked.  Under
Windows, applications such as ZoneAlarm or Windows Firewall may need to
be configured not to block the MySQL port.

Here are some reasons the 'Can't connect to local MySQL server' error
might occur:

   * 'mysqld' is not running on the local host.  Check
     your operating system's process list to ensure the 'mysqld'
     process is present.

   * You're running a MySQL server on Windows with many TCP/IP
     connections to it.  If you're experiencing that quite often your
     clients get that error, you can find a workaround here:
     can-not-connect-to-server-on-windows.

   * Someone has removed the Unix socket file that 'mysqld'
     uses ('/tmp/mysql.sock' by default).  For example, you
     might have a 'cron' job that removes old files from the '/tmp'
     directory.  You can always run 'mysqladmin version'
     to check whether the Unix socket file that
     'mysqladmin' is trying to use really exists.  The fix
     in this case is to change the 'cron' job to not remove 'mysql.sock'
     or to place the socket file somewhere else.  See
     problems-with-mysql-sock.

   * You have started the 'mysqld' server with the
     '--socket=/path/to/socket' option, but forgotten to tell client
     programs the new name of the socket file.  If you change the socket
     path name for the server, you must also notify the MySQL clients.
     You can do this by providing the same '--socket' option when you
     run client programs.  You also need to ensure that clients have
     permission to access the 'mysql.sock' file.  To find out where the
     socket file is, you can do:

          shell> netstat -ln | grep mysql

     See problems-with-mysql-sock.

   * You are using Linux and one server thread has died (dumped core).
     In this case, you must kill the other 'mysqld'.
     threads (for example, with 'kill') before you can
     restart the MySQL server.  See crashing.

   * The server or client program might not have the proper access
     privileges for the directory that holds the Unix socket file or the
     socket file itself.  In this case, you must either change the
     access privileges for the directory or socket file so that the
     server and clients can access them, or restart 'mysqld'
     with a '--socket' option that specifies a socket file name
     in a directory where the server can create it and where client
     programs can access it.

If you get the error message 'Can't connect to MySQL server on
some_host', you can try the following things to find out what the
problem is:

   * Check whether the server is running on that host by executing
     'telnet some_host 3306' and pressing the Enter key a couple of
     times.  (3306 is the default MySQL port number.  Change the value
     if your server is listening to a different port.)  If there is a
     MySQL server running and listening to the port, you should get a
     response that includes the server's version number.  If you get an
     error such as 'telnet: Unable to connect to remote host: Connection
     refused', then there is no server running on the given port.

   * If the server is running on the local host, try using
     'mysqladmin -h localhost variables' to connect using
     the Unix socket file.  Verify the TCP/IP port number that the
     server is configured to listen to (it is the value of the 'port'
     variable.)

   * If you are running under Linux and Security-Enhanced Linux
     (SELinux) is enabled, make sure you have disabled SELinux
     protection for the 'mysqld' process.

B.5.2.3 Connection to MySQL Server Failing on Windows
.....................................................

When you're running a MySQL server on Windows with many TCP/IP
connections to it, and you're experiencing that quite often your clients
get a 'Can't connect to MySQL server' error, the reason might be that
Windows does not allow for enough ephemeral (short-lived) ports to serve
those connections.

The purpose of 'TIME_WAIT' is to keep a connection accepting packets
even after the connection has been closed.  This is because Internet
routing can cause a packet to take a slow route to its destination and
it may arrive after both sides have agreed to close.  If the port is in
use for a new connection, that packet from the old connection could
break the protocol or compromise personal information from the original
connection.  The 'TIME_WAIT' delay prevents this by ensuring that the
port cannot be reused until after some time has been permitted for those
delayed packets to arrive.

It is safe to reduce 'TIME_WAIT' greatly on LAN connections because
there is little chance of packets arriving at very long delays, as they
could through the Internet with its comparatively large distances and
latencies.

Windows permits ephemeral (short-lived) TCP ports to the user.  After
any port is closed it will remain in a 'TIME_WAIT' status for 120
seconds.  The port will not be available again until this time expires.
The default range of port numbers depends on the version of Windows,
with a more limited number of ports in older versions:

   * Windows through Server 2003: Ports in range 1025-5000

   * Windows Vista, Server 2008, and newer: Ports in range 49152-65535

With a small stack of available TCP ports (5000) and a high number of
TCP ports being open and closed over a short period of time along with
the 'TIME_WAIT' status you have a good chance for running out of ports.
There are two ways to address this problem:

   * Reduce the number of TCP ports consumed quickly by investigating
     connection pooling or persistent connections where possible

   * Tune some settings in the Windows registry (see below)

*Important*:

The following procedure involves modifying the Windows registry.  Before
you modify the registry, make sure to back it up and make sure that you
understand how to restore it if a problem occurs.  For information about
how to back up, restore, and edit the registry, view the following
article in the Microsoft Knowledge Base:
<http://support.microsoft.com/kb/256986/EN-US/>.

  1. Start Registry Editor ('Regedt32.exe').

  2. Locate the following key in the registry:

          HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

  3. On the 'Edit' menu, click 'Add Value', and then add the following
     registry value:

          Value Name: MaxUserPort
          Data Type: REG_DWORD
          Value: 65534

     This sets the number of ephemeral ports available to any user.  The
     valid range is between 5000 and 65534 (decimal).  The default value
     is 0x1388 (5000 decimal).

  4. On the 'Edit' menu, click 'Add Value', and then add the following
     registry value:

          Value Name: TcpTimedWaitDelay
          Data Type: REG_DWORD
          Value: 30

     This sets the number of seconds to hold a TCP port connection in
     'TIME_WAIT' state before closing.  The valid range is between 30
     and 300 decimal, although you may wish to check with Microsoft for
     the latest permitted values.  The default value is 0x78 (120
     decimal).

  5. Quit Registry Editor.

  6. Reboot the machine.

Note: Undoing the above should be as simple as deleting the registry
entries you've created.

B.5.2.4 Lost connection to MySQL server
.......................................

There are three likely causes for this error message.

Usually it indicates network connectivity trouble and you should check
the condition of your network if this error occurs frequently.  If the
error message includes 'during query,' this is probably the case you are
experiencing.

Sometimes the 'during query' form happens when millions of rows are
being sent as part of one or more queries.  If you know that this is
happening, you should try increasing 'net_read_timeout' from its default
of 30 seconds to 60 seconds or longer, sufficient for the data transfer
to complete.

More rarely, it can happen when the client is attempting the initial
connection to the server.  In this case, if your 'connect_timeout' value
is set to only a few seconds, you may be able to resolve the problem by
increasing it to ten seconds, perhaps more if you have a very long
distance or slow connection.  You can determine whether you are
experiencing this more uncommon cause by using 'SHOW GLOBAL STATUS LIKE
'Aborted_connects''.  It will increase by one for each initial
connection attempt that the server aborts.  You may see 'reading
authorization packet' as part of the error message; if so, that also
suggests that this is the solution that you need.

If the cause is none of those just described, you may be experiencing a
problem with 'BLOB' values that are larger than
'max_allowed_packet', which can cause this error with some clients.
Sometime you may see an 'ER_NET_PACKET_TOO_LARGE' error, and that
confirms that you need to increase 'max_allowed_packet'.

B.5.2.5 Password Fails When Entered Interactively
.................................................

MySQL client programs prompt for a password when invoked with a
'--password' or '-p' option that has no following password value:

     shell> mysql -u USER_NAME -p
     Enter password:

On some systems, you may find that your password works when specified in
an option file or on the command line, but not when you enter it
interactively at the 'Enter password:' prompt.  This occurs when the
library provided by the system to read passwords limits password values
to a small number of characters (typically eight).  That is a problem
with the system library, not with MySQL. To work around it, change your
MySQL password to a value that is eight or fewer characters long, or put
your password in an option file.

B.5.2.6 Host 'host_name' is blocked
...................................

If the following error occurs, it means that 'mysqld' has
received many connection requests from the given host that were
interrupted in the middle:

     Host 'HOST_NAME' is blocked because of many connection errors.
     Unblock with 'mysqladmin flush-hosts'

The value of the 'max_connect_errors' system variable determines how
many successive interrupted connection requests are permitted.  (See
server-system-variables.)  After 'max_connect_errors' failed
requests without a successful connection, see 'mysqld'.
assumes that something is wrong (for example, that someone is trying to
break in), and blocks the host from further connections until you issue
a 'FLUSH HOSTS' statement or execute a 'mysqladmin flush-hosts'
command.

By default, see 'mysqld' blocks a host after 100 connection
errors.  You can adjust the value by setting 'max_connect_errors' at
server startup:

     shell> mysqld_safe --max_connect_errors=10000 &

The value can also be set at runtime:

     mysql> SET GLOBAL max_connect_errors=10000;

If you get the 'Host 'HOST_NAME' is blocked' error message for a given
host, you should first verify that there is nothing wrong with TCP/IP
connections from that host.  If you are having network problems, it does
you no good to increase the value of the 'max_connect_errors' variable.

B.5.2.7 Too many connections
............................

If you get a 'Too many connections' error when you try to connect to the
'mysqld' server, this means that all available
connections are in use by other clients.

The number of connections permitted is controlled by the
'max_connections' system variable.  The default value is 151 to improve
performance when MySQL is used with the Apache Web server.  (Previously,
the default was 100.)  If you need to support more connections, you
should set a larger value for this variable.

'mysqld' actually permits 'max_connections+1' clients to
connect.  The extra connection is reserved for use by accounts that have
the 'SUPER' privilege.  By granting the 'SUPER' privilege to
administrators and not to normal users (who should not need it), an
administrator who also has the 'PROCESS' privilege can connect to the
server and use 'SHOW PROCESSLIST' to diagnose
problems even if the maximum number of unprivileged clients are
connected.  See show-processlist.

The maximum number of connections MySQL supports depends on the quality
of the thread library on a given platform, the amount of RAM available,
how much RAM is used for each connection, the workload from each
connection, and the desired response time.  Linux or Solaris should be
able to support at least 500 to 1000 simultaneous connections routinely
and as many as 10,000 connections if you have many gigabytes of RAM
available and the workload from each is low or the response time target
undemanding.  Windows is limited to (open tables x 2 + open connections)
< 2048 due to the Posix compatibility layer used on that platform.

Increasing 'open-files-limit' may be necessary.  Also see
linux-installation, for how to raise the operating system limit on how
many handles can be used by MySQL.

B.5.2.8 Out of memory
.....................

If you issue a query using the 'mysql' client program and
receive an error like the following one, it means that 'mysql'
does not have enough memory to store the entire query result:

     mysql: Out of memory at line 42, 'malloc.c'
     mysql: needed 8136 byte (8k), memory in use: 12481367 bytes (12189k)
     ERROR 2008: MySQL client ran out of memory

To remedy the problem, first check whether your query is correct.  Is it
reasonable that it should return so many rows?  If not, correct the
query and try again.  Otherwise, you can invoke 'mysql'.
with the '--quick' option.  This causes it to use the
'mysql_use_result()'. C API function to retrieve the
result set, which places less of a load on the client (but more on the
server).

B.5.2.9 MySQL server has gone away
..................................

This section also covers the related 'Lost connection to server during
query' error.

The most common reason for the 'MySQL server has gone away' error is
that the server timed out and closed the connection.  In this case, you
normally get one of the following error codes (which one you get is
operating system-dependent).

Error Code                Description

'CR_SERVER_GONE_ERROR'    The client couldn't send a question to the
                          server.

'CR_SERVER_LOST'          The client didn't get an error when writing
                          to the server, but it didn't get a full
                          answer (or any answer) to the question.

By default, the server closes the connection after eight hours if
nothing has happened.  You can change the time limit by setting the
'wait_timeout' variable when you start 'mysqld'.  See
server-system-variables.

If you have a script, you just have to issue the query again for the
client to do an automatic reconnection.  This assumes that you have
automatic reconnection in the client enabled (which is the default for
the 'mysql' command-line client).

Some other common reasons for the 'MySQL server has gone away' error
are:

   * You (or the db administrator) has killed the running thread with a
     'KILL' statement or a 'mysqladmin kill'
     command.

   * You tried to run a query after closing the connection to the
     server.  This indicates a logic error in the application that
     should be corrected.

   * A client application running on a different host does not have the
     necessary privileges to connect to the MySQL server from that host.

   * You got a timeout from the TCP/IP connection on the client side.
     This may happen if you have been using the commands:
     'mysql_options(..., MYSQL_OPT_READ_TIMEOUT,...)' or
     'mysql_options(..., MYSQL_OPT_WRITE_TIMEOUT,...)'.
     In this case increasing the timeout may help solve
     the problem.

   * You have encountered a timeout on the server side and the automatic
     reconnection in the client is disabled (the 'reconnect' flag in the
     'MYSQL' structure is equal to 0).

   * You are using a Windows client and the server had dropped the
     connection (probably because 'wait_timeout' expired) before the
     command was issued.

     The problem on Windows is that in some cases MySQL does not get an
     error from the OS when writing to the TCP/IP connection to the
     server, but instead gets the error when trying to read the answer
     from the connection.

     The solution to this is to either do a 'mysql_ping()'
     on the connection if there has been a long time since
     the last query (this is what Connector/ODBC does) or set
     'wait_timeout' on the 'mysqld' server so high that
     it in practice never times out.

   * You can also get these errors if you send a query to the server
     that is incorrect or too large.  If 'mysqld'.
     receives a packet that is too large or out of order, it assumes
     that something has gone wrong with the client and closes the
     connection.  If you need big queries (for example, if you are
     working with big 'BLOB' columns), you can increase the
     query limit by setting the server's 'max_allowed_packet' variable,
     which has a default value of 4MB. You may also need to increase the
     maximum packet size on the client end.  More information on setting
     the packet size is given in packet-too-large.

     An 'INSERT' or 'REPLACE' statement
     that inserts a great many rows can also cause these sorts of
     errors.  Either one of these statements sends a single request to
     the server irrespective of the number of rows to be inserted; thus,
     you can often avoid the error by reducing the number of rows sent
     per 'INSERT' or 'REPLACE'.

   * It is also possible to see this error if host name lookups fail
     (for example, if the DNS server on which your server or network
     relies goes down).  This is because MySQL is dependent on the host
     system for name resolution, but has no way of knowing whether it is
     working--from MySQL's point of view the problem is
     indistinguishable from any other network timeout.

     You may also see the 'MySQL server has gone away' error if MySQL is
     started with the '--skip-networking' option.

     Another networking issue that can cause this error occurs if the
     MySQL port (default 3306) is blocked by your firewall, thus
     preventing any connections at all to the MySQL server.

   * You can also encounter this error with applications that fork child
     processes, all of which try to use the same connection to the MySQL
     server.  This can be avoided by using a separate connection for
     each child process.

   * You have encountered a bug where the server died while executing
     the query.

You can check whether the MySQL server died and restarted by executing
'mysqladmin version' and examining the server's
uptime.  If the client connection was broken because 'mysqld'
crashed and restarted, you should concentrate on finding the
reason for the crash.  Start by checking whether issuing the query again
kills the server again.  See crashing.

You can get more information about the lost connections by starting
'mysqld' with the 'log_error_verbosity' system variable
set to 3.  This logs some of the disconnection messages in the
'hostname.err' file.  See error-log.

If you want to create a bug report regarding this problem, be sure that
you include the following information:

   * Indicate whether the MySQL server died.  You can find information
     about this in the server error log.  See crashing.

   * If a specific query kills 'mysqld' and the tables
     involved were checked with 'CHECK TABLE' before
     you ran the query, can you provide a reproducible test case?  See
     porting.

   * What is the value of the 'wait_timeout' system variable in the
     MySQL server?  (see 'mysqladmin variables' gives you
     the value of this variable.)

   * Have you tried to run 'mysqld' with the general
     query log enabled to determine whether the problem query appears in
     the log?  (See query-log.)

See also communication-errors, and bug-reports.

B.5.2.10 Packet Too Large
.........................

A communication packet is a single SQL statement sent to the MySQL
server, a single row that is sent to the client, or a binary log event
sent from a master replication server to a slave.

The largest possible packet that can be transmitted to or from a MySQL
5.7 server or client is 1GB.

When a MySQL client or the 'mysqld' server receives a
packet bigger than 'max_allowed_packet' bytes, it issues an
'ER_NET_PACKET_TOO_LARGE' error and closes the connection.  With some
clients, you may also get a 'Lost connection to MySQL server during
query' error if the communication packet is too large.

Both the client and the server have their own 'max_allowed_packet'
variable, so if you want to handle big packets, you must increase this
variable both in the client and in the server.

If you are using the 'mysql' client program, its default
'max_allowed_packet' variable is 16MB. To set a larger value, start
'mysql' like this:

     shell> mysql --max_allowed_packet=32M

That sets the packet size to 32MB.

The server's default 'max_allowed_packet' value is 4MB. You can increase
this if the server needs to handle big queries (for example, if you are
working with big 'BLOB' columns).  For example, to set the
variable to 16MB, start the server like this:

     shell> mysqld --max_allowed_packet=16M

You can also use an option file to set 'max_allowed_packet'.  For
example, to set the size for the server to 16MB, add the following lines
in an option file:

     [mysqld]
     max_allowed_packet=16M

It is safe to increase the value of this variable because the extra
memory is allocated only when needed.  For example, see 'mysqld'
allocates more memory only when you issue a long query or when
'mysqld' must return a large result row.  The small
default value of the variable is a precaution to catch incorrect packets
between the client and server and also to ensure that you do not run out
of memory by using large packets accidentally.

You can also get strange problems with large packets if you are using
large 'BLOB' values but have not given 'mysqld'
access to enough memory to handle the query.  If you suspect
this is the case, try adding 'ulimit -d 256000' to the beginning of the
'mysqld_safe' script and restarting 'mysqld'.

B.5.2.11 Communication Errors and Aborted Connections
.....................................................

If connection problems occur such as communication errors or aborted
connections, use these sources of information to diagnose problems:

   * The error log.  See error-log.

   * The general query log.  See query-log.

   * The 'Aborted_XXX' and 'Connection_errors_XXX' status variables.
     See server-status-variables.

   * The host cache, which is accessible using the 'host_cache'
     Performance Schema table.  See host-cache, and
     host-cache-table.

If the server has the 'log_error_verbosity' system variable set to 3,
you might find messages like this in your error log:

     [Note] Aborted connection 854 to db: 'employees' user: 'josh'

If a client is unable even to connect, the server increments the
'Aborted_connects' status variable.  Unsuccessful connection attempts
can occur for the following reasons:

   * A client attempts to access a database but has no privileges for
     it.

   * A client uses an incorrect password.

   * A connection packet does not contain the right information.

   * It takes more than 'connect_timeout' seconds to obtain a connect
     packet.  See server-system-variables.

If these kinds of things happen, it might indicate that someone is
trying to break into your server!  If the general query log is enabled,
messages for these types of problems are logged to it.

If a client successfully connects but later disconnects improperly or is
terminated, the server increments the 'Aborted_clients' status variable,
and logs an 'Aborted connection' message to the error log.  The cause
can be any of the following:

   * The client program did not call 'mysql_close()'.
     before exiting.

   * The client had been sleeping more than 'wait_timeout' or
     'interactive_timeout' seconds without issuing any requests to the
     server.  See server-system-variables.

   * The client program ended abruptly in the middle of a data transfer.

Other reasons for problems with aborted connections or aborted clients:

   * The 'max_allowed_packet' variable value is too small or queries
     require more memory than you have allocated for 'mysqld'.
     See packet-too-large.

   * Use of Ethernet protocol with Linux, both half and full duplex.
     Some Linux Ethernet drivers have this bug.  You should test for
     this bug by transferring a huge file using FTP between the client
     and server machines.  If a transfer goes in burst-pause-burst-pause
     mode, you are experiencing a Linux duplex syndrome.  Switch the
     duplex mode for both your network card and hub/switch to either
     full duplex or to half duplex and test the results to determine the
     best setting.

   * A problem with the thread library that causes interrupts on reads.

   * Badly configured TCP/IP.

   * Faulty Ethernets, hubs, switches, cables, and so forth.  This can
     be diagnosed properly only by replacing hardware.

See also gone-away.

B.5.2.12 The table is full
..........................

If a table-full error occurs, it may be that the disk is full or that
the table has reached its maximum size.  The effective maximum table
size for MySQL databases is usually determined by operating system
constraints on file sizes, not by MySQL internal limits.  See
table-size-limit.

B.5.2.13 Can't create/write to file
...................................

If you get an error of the following type for some queries, it means
that MySQL cannot create a temporary file for the result set in the
temporary directory:

     Can't create/write to file '\\sqla3fe_0.ism'.

The preceding error is a typical message for Windows; the Unix message
is similar.

One fix is to start 'mysqld' with the '--tmpdir' option
or to add the option to the '[mysqld]' section of your option file.  For
example, to specify a directory of 'C:\temp', use these lines:

     [mysqld]
     tmpdir=C:/temp

The 'C:\temp' directory must exist and have sufficient space for the
MySQL server to write to.  See option-files.

Another cause of this error can be permissions issues.  Make sure that
the MySQL server can write to the 'tmpdir' directory.

Check also the error code that you get with 'perror'.  One
reason the server cannot write to a table is that the file system is
full:

     shell> perror 28
     OS error code  28:  No space left on device

If you get an error of the following type during startup, it indicates
that the file system or directory used for storing data files is write
protected.  Provided that the write error is to a test file, the error
is not serious and can be safely ignored.

     Can't create test file /usr/local/mysql/data/master.lower-test

B.5.2.14 Commands out of sync
.............................

If you get 'Commands out of sync; you can't run this command now' in
your client code, you are calling client functions in the wrong order.

This can happen, for example, if you are using
'mysql_use_result()' and try to execute a new query
before you have called 'mysql_free_result()'.
It can also happen if you try to execute two queries that return data
without calling 'mysql_use_result()' or
'mysql_store_result()' in between.

B.5.2.15 Ignoring user
......................

If you get the following error, it means that when 'mysqld'
was started or when it reloaded the grant tables, it found an
account in the 'user' table that had an invalid password.

'Found wrong password for user 'SOME_USER'@'SOME_HOST'; ignoring user'

As a result, the account is simply ignored by the permission system.

The following list indicates possible causes of and fixes for this
problem:

   * You may be running a new version of 'mysqld' with an
     old 'user' table.  Check whether the 'Password' column of that
     table is shorter than 16 characters.  If so, correct this condition
     by running 'mysql_upgrade'.

   * The account has an old password (eight characters long).  Update
     the account in the 'user' table to have a new password.

   *
     You have specified a password in the 'user' table without using the
     'PASSWORD()' function.  Use 'mysql' to update the
     account in the 'user' table with a new password, making sure to use
     the 'PASSWORD()' function:

          mysql> UPDATE user SET Password=PASSWORD('NEW_PASSWORD')
              -> WHERE User='SOME_USER' AND Host='SOME_HOST';

B.5.2.16 Table 'tbl_name' doesn't exist
.......................................

If you get either of the following errors, it usually means that no
table exists in the default database with the given name:

     Table 'TBL_NAME' doesn't exist
     Can't find file: 'TBL_NAME' (errno: 2)

In some cases, it may be that the table does exist but that you are
referring to it incorrectly:

   * Because MySQL uses directories and files to store databases and
     tables, database and table names are case sensitive if they are
     located on a file system that has case-sensitive file names.

   * Even for file systems that are not case-sensitive, such as on
     Windows, all references to a given table within a query must use
     the same lettercase.

You can check which tables are in the default database with 'SHOW TABLES'.
See show.

B.5.2.17 Can't initialize character set
.......................................

You might see an error like this if you have character set problems:

     MySQL Connection Failed: Can't initialize character set CHARSET_NAME

This error can have any of the following causes:

   * The character set is a multibyte character set and you have no
     support for the character set in the client.  In this case, you
     need to recompile the client by running 'CMake' with the
     '-DDEFAULT_CHARSET=CHARSET_NAME' or
     '-DWITH_EXTRA_CHARSETS=CHARSET_NAME' option.  See
     source-configuration-options.

     All standard MySQL binaries are compiled with
     '-DWITH_EXTRA_CHARSETS=complex', which enables support for all
     multibyte character sets.  See
     source-configuration-options.

   * The character set is a simple character set that is not compiled
     into 'mysqld', and the character set definition files
     are not in the place where the client expects to find them.

     In this case, you need to use one of the following methods to solve
     the problem:

        * Recompile the client with support for the character set.  See
          source-configuration-options.

        * Specify to the client the directory where the character set
          definition files are located.  For many clients, you can do
          this with the '--character-sets-dir' option.

        * Copy the character definition files to the path where the
          client expects them to be.

B.5.2.18 File Not Found and Similar Errors
..........................................

If you get 'ERROR 'FILE_NAME' not found (errno: 23)', 'Can't open file:
FILE_NAME (errno: 24)', or any other error with 'errno 23' or 'errno 24'
from MySQL, it means that you have not allocated enough file descriptors
for the MySQL server.  You can use the 'perror' utility
to get a description of what the error number means:

     shell> perror 23
     OS error code  23:  File table overflow
     shell> perror 24
     OS error code  24:  Too many open files
     shell> perror 11
     OS error code  11:  Resource temporarily unavailable

The problem here is that 'mysqld' is trying to keep open
too many files simultaneously.  You can either tell 'mysqld'
not to open so many files at once or increase the number of file
descriptors available to 'mysqld'.

To tell 'mysqld' to keep open fewer files at a time, you
can make the table cache smaller by reducing the value of the
'table_open_cache' system variable (the default value is 64).  This may
not entirely prevent running out of file descriptors because in some
circumstances the server may attempt to extend the cache size
temporarily, as described in table-cache.  Reducing the value of
'max_connections' also reduces the number of open files (the default
value is 100).

To change the number of file descriptors available to 'mysqld',
you can use the '--open-files-limit' option to
'mysqld_safe' or set the 'open_files_limit' system
variable.  See server-system-variables.  The easiest way to set
these values is to add an option to your option file.  See
option-files.  If you have an old version of 'mysqld'.
that does not support setting the open files limit, you can edit the
'mysqld_safe' script.  There is a commented-out line
'ulimit -n 256' in the script.  You can remove the '#' character to
uncomment this line, and change the number '256' to set the number of
file descriptors to be made available to 'mysqld'.

'--open-files-limit' and 'ulimit' can increase the number of file
descriptors, but only up to the limit imposed by the operating system.
There is also a 'hard' limit that can be overridden only if you start
'mysqld_safe' or 'mysqld' as 'root'
(just remember that you also need to start the server with the '--user'
option in this case so that it does not continue to run as 'root' after
it starts up).  If you need to increase the operating system limit on
the number of file descriptors available to each process, consult the
documentation for your system.

*Note*:

If you run the 'tcsh' shell, 'ulimit' does not work!  'tcsh' also
reports incorrect values when you ask for the current limits.  In this
case, you should start 'mysqld_safe' using 'sh'.

B.5.2.19 Table-Corruption Issues
................................

If you have started 'mysqld' with
'--myisam-recover-options', MySQL automatically checks and tries to
repair 'MyISAM' tables if they are marked as 'not closed properly' or
'crashed'.  If this happens, MySQL writes an entry in the 'hostname.err'
file ''Warning: Checking table ...'' which is followed by 'Warning:
Repairing table' if the table needs to be repaired.  If you get a lot of
these errors, without 'mysqld' having died unexpectedly
just before, then something is wrong and needs to be investigated
further.

When the server detects 'MyISAM' table corruption, it writes additional
information to the error log, such as the name and line number of the
source file, and the list of threads accessing the table.  Example: 'Got
an error from thread_id=1, mi_dynrec.c:368'.  This is useful information
to include in bug reports.

See also server-options, and reproducible-test-case.

B.5.3 Administration-Related Issues
-----------------------------------

B.5.3.1 Problems with File Permissions
......................................

If you have problems with file permissions, the 'UMASK' or 'UMASK_DIR'
environment variable might be set incorrectly when 'mysqld'
starts.  For example, MySQL might issue the following error
message when you create a table:

     ERROR: Can't find file: 'path/with/filename.frm' (Errcode: 13)

The default 'UMASK' and 'UMASK_DIR' values are '0640' and '0750',
respectively ('0660' and '0700' prior to MySQL 5.7.6).  MySQL assumes
that the value for 'UMASK' or 'UMASK_DIR' is in octal if it starts with
a zero.  For example, setting 'UMASK=0600' is equivalent to 'UMASK=384'
because 0600 octal is 384 decimal.

To change the default 'UMASK' value, start 'mysqld_safe'
as follows:

     shell> UMASK=384  # = 600 in octal
     shell> export UMASK
     shell> mysqld_safe &

By default, MySQL creates database directories with an access permission
value of '0750'.  To modify this behavior, set the 'UMASK_DIR' variable.
If you set its value, new directories are created with the combined
'UMASK' and 'UMASK_DIR' values.  For example, to give group access to
all new directories, start 'mysqld_safe' as follows:

     shell> UMASK_DIR=504  # = 770 in octal
     shell> export UMASK_DIR
     shell> mysqld_safe &

For additional details, see environment-variables.

B.5.3.2 How to Reset the Root Password
......................................

If you have never assigned a 'root' password for MySQL, the server does
not require a password at all for connecting as 'root'.  However, this
is insecure.  For instructions on assigning a password, see
default-privileges.

If you know the 'root' password and want to change it, see
alter-user, and set-password.

If you assigned a 'root' password previously but have forgotten it, you
can assign a new password.  The following sections provide instructions
for Windows and Unix and Unix-like systems, as well as generic
instructions that apply to any system.

B.5.3.3 Resetting the Root Password: Windows Systems
....................................................

On Windows, use the following procedure to reset the password for the
MySQL ''root'@'localhost'' account.  To change the password for a 'root'
account with a different host name part, modify the instructions to use
that host name.

  1. Log on to your system as Administrator.

  2. Stop the MySQL server if it is running.  For a server that is
     running as a Windows service, go to the Services manager: From the
     'Start' menu, select 'Control Panel', then 'Administrative Tools',
     then 'Services'.  Find the MySQL service in the list and stop it.

     If your server is not running as a service, you may need to use the
     Task Manager to force it to stop.

  3. Create a text file containing the password-assignment statement on
     a single line.  Replace the password with the password that you
     want to use.

     MySQL 5.7.6 and later:

          ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass';

     MySQL 5.7.5 and earlier:

          SET PASSWORD FOR 'root'@'localhost' = PASSWORD('MyNewPass');

  4. Save the file.  This example assumes that you name the file
     'C:\mysql-init.txt'.

  5. Open a console window to get to the command prompt: From the
     'Start' menu, select 'Run', then enter 'cmd' as the command to be
     run.

  6. Start the MySQL server with the special '--init-file' option
     (notice that the backslash in the option value is doubled):

          C:\> cd "C:\Program Files\MySQL\MySQL Server 5.7\bin"
          C:\> mysqld --init-file=C:\\mysql-init.txt

     If you installed MySQL to a different location, adjust the 'cd'
     command accordingly.

     The server executes the contents of the file named by the
     '--init-file' option at startup, changing the ''root'@'localhost''
     account password.

     To have server output to appear in the console window rather than
     in a log file, add the '--console' option to the 'mysqld'
     command.

     If you installed MySQL using the MySQL Installation Wizard, you may
     need to specify a '--defaults-file' option.  For example:

          C:\> mysqld
                   --defaults-file="C:\\ProgramData\\MySQL\\MySQL Server 5.7\\my.ini"
                   --init-file=C:\\mysql-init.txt

     The appropriate '--defaults-file' setting can be found using the
     Services Manager: From the 'Start' menu, select 'Control Panel',
     then 'Administrative Tools', then 'Services'.  Find the MySQL
     service in the list, right-click it, and choose the 'Properties'
     option.  The 'Path to executable' field contains the
     '--defaults-file' setting.

  7. After the server has started successfully, delete
     'C:\mysql-init.txt'.

You should now be able to connect to the MySQL server as 'root' using
the new password.  Stop the MySQL server and restart it normally.  If
you run the server as a service, start it from the Windows Services
window.  If you start the server manually, use whatever command you
normally use.

If the 'ALTER USER' statement fails to reset the
password, try repeating the procedure using the following statements to
modify the 'user' table directly:

     UPDATE mysql.user
         SET authentication_string = PASSWORD('MyNewPass'), password_expired = 'N'
         WHERE User = 'root' AND Host = 'localhost';
     FLUSH PRIVILEGES;

B.5.3.4 Resetting the Root Password: Unix and Unix-Like Systems
...............................................................

On Unix, use the following procedure to reset the password for the MySQL
''root'@'localhost'' account.  To change the password for a 'root'
account with a different host name part, modify the instructions to use
that host name.

The instructions assume that you will start the MySQL server from the
Unix login account that you normally use for running it.  For example,
if you run the server using the 'mysql' login account, you should log in
as 'mysql' before using the instructions.  Alternatively, you can log in
as 'root', but in this case you _must_ start 'mysqld'.
with the '--user=mysql' option.  If you start the server as 'root'
without using '--user=mysql', the server may create 'root'-owned files
in the data directory, such as log files, and these may cause
permission-related problems for future server startups.  If that
happens, you will need to either change the ownership of the files to
'mysql' or remove them.

  1. Log on to your system as the Unix user that the MySQL server runs
     as (for example, 'mysql').

  2. Stop the MySQL server if it is running.  Locate the '.pid' file
     that contains the server's process ID. The exact location and name
     of this file depend on your distribution, host name, and
     configuration.  Common locations are '/var/lib/mysql/',
     '/var/run/mysqld/', and '/usr/local/mysql/data/'.  Generally, the
     file name has an extension of '.pid' and begins with either
     'mysqld' or your system's host name.

     Stop the MySQL server by sending a normal 'kill' (not 'kill -9') to
     the 'mysqld' process.  Use the actual path name of
     the '.pid' file in the following command:

          shell> kill `cat /mysql-data-directory/host_name.pid`

     Use backticks (not forward quotation marks) with the 'cat' command.
     These cause the output of 'cat' to be substituted into the 'kill'
     command.

  3. Create a text file containing the password-assignment statement on
     a single line.  Replace the password with the password that you
     want to use.

     MySQL 5.7.6 and later:

          ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass';

     MySQL 5.7.5 and earlier:

          SET PASSWORD FOR 'root'@'localhost' = PASSWORD('MyNewPass');

  4. Save the file.  This example assumes that you name the file
     '/home/me/mysql-init'.  The file contains the password, so do not
     save it where it can be read by other users.  If you are not logged
     in as 'mysql' (the user the server runs as), make sure that the
     file has permissions that permit 'mysql' to read it.

  5. Start the MySQL server with the special '--init-file' option:

          shell> mysqld --init-file=/home/me/mysql-init &

     The server executes the contents of the file named by the
     '--init-file' option at startup, changing the ''root'@'localhost''
     account password.

     Other options may be necessary as well, depending on how you
     normally start your server.  For example, '--defaults-file' may be
     needed before '--init-file'.

  6. After the server has started successfully, delete
     '/home/me/mysql-init'.

You should now be able to connect to the MySQL server as 'root' using
the new password.  Stop the server and restart it normally.

If the 'ALTER USER' statement fails to reset the
password, try repeating the procedure using the following statements to
modify the 'user' table directly:

     UPDATE mysql.user
         SET authentication_string = PASSWORD('MyNewPass'), password_expired = 'N'
         WHERE User = 'root' AND Host = 'localhost';
     FLUSH PRIVILEGES;

B.5.3.5 Resetting the Root Password: Generic Instructions
.........................................................

The preceding sections provide password-resetting instructions
specifically for Windows and Unix and Unix-like systems.  Alternatively,
on any platform, you can reset the password using the 'mysql'
client (but this approach is less secure):

  1. Stop the MySQL server if necessary, then restart it with the
     '--skip-grant-tables' option.  This enables anyone to connect
     without a password and with all privileges, and disables
     account-management statements such as 'ALTER USER'
     and 'SET PASSWORD'.  Because this
     is insecure, you might want to use '--skip-grant-tables' in
     conjunction with '--skip-networking' to prevent remote clients from
     connecting.

  2. Connect to the MySQL server using the 'mysql' client;
     no password is necessary because the server was started with
     '--skip-grant-tables':

          shell> mysql

  3. In the 'mysql' client, tell the server to reload the grant tables
     so that account-management statements work:

          mysql> FLUSH PRIVILEGES;

     Then change the ''root'@'localhost'' account password.  Replace the
     password with the password that you want to use.  To change the
     password for a 'root' account with a different host name part,
     modify the instructions to use that host name.

     MySQL 5.7.6 and later:

          mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'MyNewPass';

     MySQL 5.7.5 and earlier:

          mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('MyNewPass');

You should now be able to connect to the MySQL server as 'root' using
the new password.  Stop the server and restart it normally (without the
'--skip-grant-tables' and '--skip-networking' options).

If the 'ALTER USER' statement fails to reset the
password, try repeating the procedure using the following statements to
modify the 'user' table directly:

     UPDATE mysql.user SET authentication_string = PASSWORD('MyNewPass')
     WHERE User = 'root' AND Host = 'localhost';
     FLUSH PRIVILEGES;

B.5.3.6 What to Do If MySQL Keeps Crashing
..........................................

Each MySQL version is tested on many platforms before it is released.
This does not mean that there are no bugs in MySQL, but if there are
bugs, they should be very few and can be hard to find.  If you have a
problem, it always helps if you try to find out exactly what crashes
your system, because you have a much better chance of getting the
problem fixed quickly.

First, you should try to find out whether the problem is that the
'mysqld' server dies or whether your problem has to do with
your client.  You can check how long your 'mysqld' server
has been up by executing 'mysqladmin version'.  If
'mysqld' has died and restarted, you may find the reason
by looking in the server's error log.  See error-log.

On some systems, you can find in the error log a stack trace of where
'mysqld' died that you can resolve with the
'resolve_stack_dump' program.  See porting.  Note that the
variable values written in the error log may not always be 100% correct.

Many server crashes are caused by corrupted data files or index files.
MySQL updates the files on disk with the 'write()' system call after
every SQL statement and before the client is notified about the result.
(This is not true if you are running with '--delay-key-write', in which
case data files are written but not index files.)  This means that data
file contents are safe even if 'mysqld' crashes, because
the operating system ensures that the unflushed data is written to disk.
You can force MySQL to flush everything to disk after every SQL
statement by starting 'mysqld' with the '--flush' option.

The preceding means that normally you should not get corrupted tables
unless one of the following happens:

   * The MySQL server or the server host was killed in the middle of an
     update.

   * You have found a bug in 'mysqld' that caused it to
     die in the middle of an update.

   * Some external program is manipulating data files or index files at
     the same time as 'mysqld' without locking the table
     properly.

   * You are running many 'mysqld' servers using the same
     data directory on a system that does not support good file system
     locks (normally handled by the 'lockd' lock manager), or you are
     running multiple servers with external locking disabled.

   * You have a crashed data file or index file that contains very
     corrupt data that confused 'mysqld'.

   * You have found a bug in the data storage code.  This isn't likely,
     but it is at least possible.  In this case, you can try to change
     the storage engine to another engine by using 'ALTER TABLE'
     on a repaired copy of the table.

Because it is very difficult to know why something is crashing, first
try to check whether things that work for others crash for you.  Try the
following things:

   * Stop the 'mysqld' server with 'mysqladmin shutdown',
     run 'myisamchk --silent --force */*.MYI'
     from the data directory to check all 'MyISAM'
     tables, and restart 'mysqld'.  This ensures that you
     are running from a clean state.  See server-administration.

   * Start 'mysqld' with the general query log enabled
     (see query-log).  Then try to determine from the
     information written to the log whether some specific query kills
     the server.  About 95% of all bugs are related to a particular
     query.  Normally, this is one of the last queries in the log file
     just before the server restarts.  See query-log.  If you
     can repeatedly kill MySQL with a specific query, even when you have
     checked all tables just before issuing it, then you have isolated
     the bug and should submit a bug report for it.  See
     bug-reports.

   * Try to make a test case that we can use to repeat the problem.  See
     porting.

   * Try the 'fork_big.pl' script.  (It is located in the 'tests'
     directory of source distributions.)

   * Configuring MySQL for debugging makes it much easier to gather
     information about possible errors if something goes wrong.
     Reconfigure MySQL with the '-DWITH_DEBUG=1' option to 'CMake' and
     then recompile.  See porting.

   * Make sure that you have applied the latest patches for your
     operating system.

   * Use the '--skip-external-locking' option to 'mysqld'.
     On some systems, the 'lockd' lock manager does not work properly;
     the '--skip-external-locking' option tells 'mysqld'.
     not to use external locking.  (This means that you cannot run two
     'mysqld' servers on the same data directory and that
     you must be careful if you use 'myisamchk'.
     Nevertheless, it may be instructive to try the option as a test.)

   * If 'mysqld' appears to be running but not
     responding, try 'mysqladmin -u root processlist'.
     Sometimes 'mysqld' is not hung even though it seems
     unresponsive.  The problem may be that all connections are in use,
     or there may be some internal lock problem.  'mysqladmin -u root processlist'
     usually is able to make a connection
     even in these cases, and can provide useful information about the
     current number of connections and their status.

   * Run the command 'mysqladmin -i 5 status' or
     'mysqladmin -i 5 -r status' in a separate window
     to produce statistics while running other queries.

   * Try the following:

       1. Start 'mysqld' from 'gdb' (or another
          debugger).  See porting.

       2. Run your test scripts.

       3. Print the backtrace and the local variables at the three
          lowest levels.  In 'gdb', you can do this with the following
          commands when 'mysqld' has crashed inside
          'gdb':

               backtrace
               info local
               up
               info local
               up
               info local

          With 'gdb', you can also examine which threads exist with
          'info threads' and switch to a specific thread with 'thread
          N', where N is the thread ID.

   * Try to simulate your application with a Perl script to force MySQL
     to crash or misbehave.

   * Send a normal bug report.  See bug-reports.  Be even more
     detailed than usual.  Because MySQL works for many people, the
     crash might result from something that exists only on your computer
     (for example, an error that is related to your particular system
     libraries).

   * If you have a problem with tables containing dynamic-length rows
     and you are using only 'VARCHAR' columns (not
     'BLOB' or 'TEXT' columns), you can try to
     change all 'VARCHAR' to 'CHAR' with
     'ALTER TABLE'.  This forces MySQL to use fixed-size
     rows.  Fixed-size rows take a little extra space, but are much more
     tolerant to corruption.

     The current dynamic row code has been in use for several years with
     very few problems, but dynamic-length rows are by nature more prone
     to errors, so it may be a good idea to try this strategy to see
     whether it helps.

   * Consider the possibility of hardware faults when diagnosing
     problems.  Defective hardware can be the cause of data corruption.
     Pay particular attention to your memory and disk subsystems when
     troubleshooting hardware.

B.5.3.7 How MySQL Handles a Full Disk
.....................................

This section describes how MySQL responds to disk-full errors (such as
'no space left on device'), and to quota-exceeded errors (such as 'write
failed' or 'user block limit reached').

This section is relevant for writes to 'MyISAM' tables.  It also applies
for writes to binary log files and binary log index file, except that
references to 'row' and 'record' should be understood to mean 'event.'

When a disk-full condition occurs, MySQL does the following:

   * It checks once every minute to see whether there is enough space to
     write the current row.  If there is enough space, it continues as
     if nothing had happened.

   * Every 10 minutes it writes an entry to the log file, warning about
     the disk-full condition.

To alleviate the problem, take the following actions:

   * To continue, you only have to free enough disk space to insert all
     records.

   * Alternatively, to abort the thread, use 'mysqladmin kill'.
     The thread is aborted the next time it checks the disk
     (in one minute).

   * Other threads might be waiting for the table that caused the
     disk-full condition.  If you have several 'locked' threads, killing
     the one thread that is waiting on the disk-full condition enables
     the other threads to continue.

Exceptions to the preceding behavior are when you use 'REPAIR TABLE'
or 'OPTIMIZE TABLE' or when
the indexes are created in a batch after 'LOAD DATA INFILE'
or after an 'ALTER TABLE' statement.  All
of these statements may create large temporary files that, if left to
themselves, would cause big problems for the rest of the system.  If the
disk becomes full while MySQL is doing any of these operations, it
removes the big temporary files and mark the table as crashed.  The
exception is that for 'ALTER TABLE', the old table is
left unchanged.

B.5.3.8 Where MySQL Stores Temporary Files
..........................................

On Unix, MySQL uses the value of the 'TMPDIR' environment variable as
the path name of the directory in which to store temporary files.  If
'TMPDIR' is not set, MySQL uses the system default, which is usually
'/tmp', '/var/tmp', or '/usr/tmp'.

On Windows, MySQL checks in order the values of the 'TMPDIR', 'TEMP',
and 'TMP' environment variables.  For the first one found to be set,
MySQL uses it and does not check those remaining.  If none of 'TMPDIR',
'TEMP', or 'TMP' are set, MySQL uses the Windows system default, which
is usually 'C:\windows\temp\'.

If the file system containing your temporary file directory is too
small, you can use the 'mysqld'. '--tmpdir' option to
specify a directory in a file system where you have enough space.  On
replication slaves, you can use '--slave-load-tmpdir' to specify a
separate directory for holding temporary files when replicating
'LOAD DATA INFILE' statements.

The '--tmpdir' option can be set to a list of several paths that are
used in round-robin fashion.  Paths should be separated by colon
characters (':') on Unix and semicolon characters (';') on Windows.

*Note*:

To spread the load effectively, these paths should be located on
different _physical_ disks, not different partitions of the same disk.

If the MySQL server is acting as a replication slave, you should be sure
to set '--slave-load-tmpdir' not to point to a directory that is on a
memory-based file system or to a directory that is cleared when the
server host restarts.  A replication slave needs some of its temporary
files to survive a machine restart so that it can replicate temporary
tables or 'LOAD DATA INFILE' operations.  If files in
the slave temporary file directory are lost when the server restarts,
replication fails.

MySQL arranges that temporary files are removed if 'mysqld'
is terminated.  On platforms that support it (such as Unix),
this is done by unlinking the file after opening it.  The disadvantage
of this is that the name does not appear in directory listings and you
do not see a big temporary file that fills up the file system in which
the temporary file directory is located.  (In such cases, 'lsof +L1' may
be helpful in identifying large files associated with 'mysqld')

When sorting ('ORDER BY' or 'GROUP BY'), MySQL normally uses one or two
temporary files.  The maximum disk space required is determined by the
following expression:

     (length of what is sorted + sizeof(row pointer))
     * number of matched rows
     * 2

The row pointer size is usually four bytes, but may grow in the future
for really big tables.

For some 'SELECT' queries, MySQL also creates temporary
SQL tables.  These are not hidden and have names of the form 'SQL_*'.

In most cases, see 'ALTER TABLE' creates a temporary
copy of the original table in the same directory as the original table.

*Where InnoDB Stores Temporary Files*

As of MySQL 5.7.1, non-compressed 'InnoDB' temporary tables are stored
in a temporary tablespace file named 'ibtmp1', which is located in the
MySQL 'data' directory ('datadir') by default.  The
'innodb_temp_data_file_path' option can be used at startup to specify a
different file name and location.  Compressed 'InnoDB' temporary tables
are stored in their own independent tablespace files ('.ibd' files) in
the path specified by the 'TMPDIR' environment variable.

If an 'ALTER TABLE' operation on an 'InnoDB' table
uses the 'ALGORITHM=COPY' technique, 'InnoDB' creates a temporary copy
of the table in the same directory as the original table.  Temporary
table file names begin with an '#sql-' prefix and only appear briefly
during the 'ALTER TABLE' operation.

If an 'ALTER TABLE' operation rebuilds an 'InnoDB'
table using the 'ALGORITHM=INPLACE' technique (online DDL), 'InnoDB'
creates an _intermediate_ copy of the table the same directory as the
original table.  Intermediate table file names begin with an '#sql-ib'
prefix and only appear briefly during the 'ALTER TABLE'
operation.

'ALTER TABLE' operations that rebuild an 'InnoDB'
table using the 'ALGORITHM=INPLACE' technique (online DDL) also create
temporary sort files in the MySQL temporary directory ('$TMPDIR' on
Unix, '%TEMP%' on Windows, or the directory specified by the '--tmpdir'
configuration option).  If the temporary directory is not large enough
to hold such files, you may need to reconfigure 'tmpdir'.
Alternatively, you can define a separate temporary directory for
'InnoDB' online 'ALTER TABLE' operations using the
'innodb_tmpdir' configuration option.  This option was introduced in
MySQL 5.7.11 to help avoid temporary directory overflows that could
occur as a result of large temporary sort files created during online
'ALTER TABLE' operations.  'innodb_tmpdir' can be
configured dynamically using a 'SET GLOBAL' or
'SET SESSION' statement.

The 'innodb_tmpdir' option is not applicable to intermediate table
files, which are always created in the same directory as the original
table.

In replication environments, only consider replicating an
'innodb_tmpdir' setting if all servers have the same operating system
environment.  Otherwise, replicating an 'innodb_tmpdir' setting could
result in a replication failure when running online 'ALTER TABLE'
operations.  If server operating environments differ, it is
recommended that you configure 'innodb_tmpdir' on each server
individually.

For more information about online DDL, see innodb-online-ddl.

B.5.3.9 How to Protect or Change the MySQL Unix Socket File
...........................................................

The default location for the Unix socket file that the server uses for
communication with local clients is '/tmp/mysql.sock'.  (For some
distribution formats, the directory might be different, such as
'/var/lib/mysql' for RPMs.)

On some versions of Unix, anyone can delete files in the '/tmp'
directory or other similar directories used for temporary files.  If the
socket file is located in such a directory on your system, this might
cause problems.

On most versions of Unix, you can protect your '/tmp' directory so that
files can be deleted only by their owners or the superuser ('root').  To
do this, set the 'sticky' bit on the '/tmp' directory by logging in as
'root' and using the following command:

     shell> chmod +t /tmp

You can check whether the 'sticky' bit is set by executing 'ls -ld
/tmp'.  If the last permission character is 't', the bit is set.

Another approach is to change the place where the server creates the
Unix socket file.  If you do this, you should also let client programs
know the new location of the file.  You can specify the file location in
several ways:

   * Specify the path in a global or local option file.  For example,
     put the following lines in '/etc/my.cnf':

          [mysqld]
          socket=/path/to/socket

          [client]
          socket=/path/to/socket

     See option-files.

   * Specify a '--socket' option on the command line to
     'mysqld_safe' and when you run client programs.

   * Set the 'MYSQL_UNIX_PORT' environment variable to the path of the
     Unix socket file.

   * Recompile MySQL from source to use a different default Unix socket
     file location.  Define the path to the file with the
     'MYSQL_UNIX_ADDR' option when you run 'CMake'.  See
     source-configuration-options.

You can test whether the new socket location works by attempting to
connect to the server with this command:

     shell> mysqladmin --socket=/path/to/socket version

B.5.3.10 Time Zone Problems
...........................

If you have a problem with 'SELECT NOW()' returning values in UTC and
not your local time, you have to tell the server your current time zone.
The same applies if 'UNIX_TIMESTAMP()' returns the wrong value.  This
should be done for the environment in which the server runs; for
example, in 'mysqld_safe' or 'mysql.server'.
See environment-variables.

You can set the time zone for the server with the
'--timezone=TIMEZONE_NAME' option to 'mysqld_safe'.
You can also set it by setting the 'TZ' environment variable before you
start 'mysqld'.

The permissible values for '--timezone' or 'TZ' are system dependent.
Consult your operating system documentation to see what values are
acceptable.

B.5.4 Query-Related Issues
--------------------------

B.5.4.1 Case Sensitivity in String Searches
...........................................

For nonbinary strings (see 'CHAR', 'VARCHAR',
'TEXT'), string searches use the collation of the comparison
operands.  For binary strings (see 'BINARY',
'VARBINARY', 'BLOB'), comparisons use the
numeric values of the bytes in the operands; this means that for
alphabetic characters, comparisons will be case-sensitive.

A comparison between a nonbinary string and binary string is treated as
a comparison of binary strings.

Simple comparison operations ('>=, >, =, <, <=', sorting, and grouping)
are based on each character's 'sort value.' Characters with the same
sort value are treated as the same character.  For example, if 'e' and
'e'' have the same sort value in a given collation, they compare as
equal.

The default character set and collation are 'latin1' and
'latin1_swedish_ci', so nonbinary string comparisons are case
insensitive by default.  This means that if you search with 'COL_NAME
LIKE 'a%'', you get all column values that start with 'A' or 'a'.  To
make this search case-sensitive, make sure that one of the operands has
a case-sensitive or binary collation.  For example, if you are comparing
a column and a string that both have the 'latin1' character set, you can
use the 'COLLATE' operator to cause either operand to have the
'latin1_general_cs' or 'latin1_bin' collation:

     COL_NAME COLLATE latin1_general_cs LIKE 'a%'
     COL_NAME LIKE 'a%' COLLATE latin1_general_cs
     COL_NAME COLLATE latin1_bin LIKE 'a%'
     COL_NAME LIKE 'a%' COLLATE latin1_bin

If you want a column always to be treated in case-sensitive fashion,
declare it with a case-sensitive or binary collation.  See
create-table.

To cause a case-sensitive comparison of nonbinary strings to be case
insensitive, use 'COLLATE' to name a case-insensitive collation.  The
strings in the following example normally are case-sensitive, but
'COLLATE' changes the comparison to be case insensitive:

     mysql> SET @s1 = 'MySQL' COLLATE latin1_bin,
         ->     @s2 = 'mysql' COLLATE latin1_bin;
     mysql> SELECT @s1 = @s2;
     +-----------+
     | @s1 = @s2 |
     +-----------+
     |         0 |
     +-----------+
     mysql> SELECT @s1 COLLATE latin1_swedish_ci = @s2;
     +-------------------------------------+
     | @s1 COLLATE latin1_swedish_ci = @s2 |
     +-------------------------------------+
     |                                   1 |
     +-------------------------------------+

A binary string is case-sensitive in comparisons.  To compare the string
as case insensitive, convert it to a nonbinary string and use 'COLLATE'
to name a case-insensitive collation:

     mysql> SET @s = BINARY 'MySQL';
     mysql> SELECT @s = 'mysql';
     +--------------+
     | @s = 'mysql' |
     +--------------+
     |            0 |
     +--------------+
     mysql> SELECT CONVERT(@s USING latin1) COLLATE latin1_swedish_ci = 'mysql';
     +--------------------------------------------------------------+
     | CONVERT(@s USING latin1) COLLATE latin1_swedish_ci = 'mysql' |
     +--------------------------------------------------------------+
     |                                                            1 |
     +--------------------------------------------------------------+

To determine whether a value will compare as a nonbinary or binary
string, use the 'COLLATION()' function.  This example shows that
'VERSION()' returns a string that has a case-insensitive collation, so
comparisons are case insensitive:

     mysql> SELECT COLLATION(VERSION());
     +----------------------+
     | COLLATION(VERSION()) |
     +----------------------+
     | utf8_general_ci      |
     +----------------------+

For binary strings, the collation value is 'binary', so comparisons will
be case sensitive.  One context in which you will see 'binary' is for
compression functions, which return binary strings as a general rule:
string:

     mysql> SELECT COLLATION(COMPRESS('x'));
     +--------------------------+
     | COLLATION(COMPRESS('x')) |
     +--------------------------+
     | binary                   |
     +--------------------------+

To check the sort value of a string, the 'WEIGHT_STRING()' may be
helpful.  See string-functions.

B.5.4.2 Problems Using DATE Columns
...................................

The format of a 'DATE' value is ''YYYY-MM-DD''.
According to standard SQL, no other format is permitted.  You should use
this format in 'UPDATE' expressions and in the 'WHERE'
clause of 'SELECT' statements.  For example:

     SELECT * FROM t1 WHERE date >= '2003-05-05';

As a convenience, MySQL automatically converts a date to a number if the
date is used in a numeric context and vice versa.  MySQL also permits a
'relaxed' string format when updating and in a 'WHERE' clause that
compares a date to a 'DATE', 'DATETIME',
or 'TIMESTAMP' column.  'Relaxed' format means that any
punctuation character may be used as the separator between parts.  For
example, ''2004-08-15'' and ''2004#08#15'' are equivalent.  MySQL can
also convert a string containing no separators (such as ''20040815''),
provided it makes sense as a date.

When you compare a 'DATE', 'TIME',
'DATETIME', or 'TIMESTAMP' to a constant
string with the '<', '<=', '=', '>=', '>', or 'BETWEEN' operators, MySQL
normally converts the string to an internal long integer for faster
comparison (and also for a bit more 'relaxed' string checking).
However, this conversion is subject to the following exceptions:

   * When you compare two columns

   * When you compare a 'DATE', 'TIME',
     'DATETIME', or 'TIMESTAMP' column
     to an expression

   * When you use any comparison method other than those just listed,
     such as 'IN' or 'STRCMP()'.

For those exceptions, the comparison is done by converting the objects
to strings and performing a string comparison.

To be on the safe side, assume that strings are compared as strings and
use the appropriate string functions if you want to compare a temporal
value to a string.

The special 'zero' date ''0000-00-00'' can be stored and retrieved as
''0000-00-00'.' When a ''0000-00-00'' date is used through
Connector/ODBC, it is automatically converted to 'NULL' because ODBC
cannot handle that kind of date.

Because MySQL performs the conversions just described, the following
statements work (assume that 'idate' is a 'DATE'.
column):

     INSERT INTO t1 (idate) VALUES (19970505);
     INSERT INTO t1 (idate) VALUES ('19970505');
     INSERT INTO t1 (idate) VALUES ('97-05-05');
     INSERT INTO t1 (idate) VALUES ('1997.05.05');
     INSERT INTO t1 (idate) VALUES ('1997 05 05');
     INSERT INTO t1 (idate) VALUES ('0000-00-00');

     SELECT idate FROM t1 WHERE idate >= '1997-05-05';
     SELECT idate FROM t1 WHERE idate >= 19970505;
     SELECT MOD(idate,100) FROM t1 WHERE idate >= 19970505;
     SELECT idate FROM t1 WHERE idate >= '19970505';

However, the following statement does not work:

     SELECT idate FROM t1 WHERE STRCMP(idate,'20030505')=0;

'STRCMP()' is a string function, so it converts 'idate' to a string in
''YYYY-MM-DD'' format and performs a string comparison.  It does not
convert ''20030505'' to the date ''2003-05-05'' and perform a date
comparison.

If you enable the 'ALLOW_INVALID_DATES' SQL mode, MySQL permits you to
store dates that are given only limited checking: MySQL requires only
that the day is in the range from 1 to 31 and the month is in the range
from 1 to 12.  This makes MySQL very convenient for Web applications
where you obtain year, month, and day in three different fields and you
want to store exactly what the user inserted (without date validation).

MySQL permits you to store dates where the day or month and day are
zero.  This is convenient if you want to store a birthdate in a
'DATE' column and you know only part of the date.  To
disallow zero month or day parts in dates, enable the 'NO_ZERO_IN_DATE'
mode.

MySQL permits you to store a 'zero' value of ''0000-00-00'' as a 'dummy
date.' This is in some cases more convenient than using 'NULL' values.
If a date to be stored in a 'DATE' column cannot be
converted to any reasonable value, MySQL stores ''0000-00-00''.  To
disallow ''0000-00-00'', enable the 'NO_ZERO_DATE' mode.

To have MySQL check all dates and accept only legal dates (unless
overridden by 'IGNORE'), set the 'sql_mode' system variable to
'"NO_ZERO_IN_DATE,NO_ZERO_DATE"'.

B.5.4.3 Problems with NULL Values
.................................

The concept of the 'NULL' value is a common source of confusion for
newcomers to SQL, who often think that 'NULL' is the same thing as an
empty string ''''.  This is not the case.  For example, the following
statements are completely different:

     mysql> INSERT INTO my_table (phone) VALUES (NULL);
     mysql> INSERT INTO my_table (phone) VALUES ('');

Both statements insert a value into the 'phone' column, but the first
inserts a 'NULL' value and the second inserts an empty string.  The
meaning of the first can be regarded as 'phone number is not known' and
the meaning of the second can be regarded as 'the person is known to
have no phone, and thus no phone number.'

To help with 'NULL' handling, you can use the 'IS NULL' and 'IS NOT
NULL' operators and the 'IFNULL()' function.

In SQL, the 'NULL' value is never true in comparison to any other value,
even 'NULL'.  An expression that contains 'NULL' always produces a
'NULL' value unless otherwise indicated in the documentation for the
operators and functions involved in the expression.  All columns in the
following example return 'NULL':

     mysql> SELECT NULL, 1+NULL, CONCAT('Invisible',NULL);

To search for column values that are 'NULL', you cannot use an 'expr =
NULL' test.  The following statement returns no rows, because 'expr =
NULL' is never true for any expression:

     mysql> SELECT * FROM my_table WHERE phone = NULL;

To look for 'NULL' values, you must use the 'IS NULL' test.  The
following statements show how to find the 'NULL' phone number and the
empty phone number:

     mysql> SELECT * FROM my_table WHERE phone IS NULL;
     mysql> SELECT * FROM my_table WHERE phone = '';

See working-with-null, for additional information and examples.

You can add an index on a column that can have 'NULL' values if you are
using the 'MyISAM', 'InnoDB', or 'MEMORY' storage engine.  Otherwise,
you must declare an indexed column 'NOT NULL', and you cannot insert
'NULL' into the column.

When reading data with 'LOAD DATA INFILE', empty or
missing columns are updated with ''''.  To load a 'NULL' value into a
column, use '\N' in the data file.  The literal word 'NULL' may also be
used under some circumstances.  See load-data.

When using 'DISTINCT', 'GROUP BY', or 'ORDER BY', all 'NULL' values are
regarded as equal.

When using 'ORDER BY', 'NULL' values are presented first, or last if you
specify 'DESC' to sort in descending order.

Aggregate (summary) functions such as 'COUNT()', 'MIN()', and 'SUM()'
ignore 'NULL' values.  The exception to this is 'COUNT(*)', which counts
rows and not individual column values.  For example, the following
statement produces two counts.  The first is a count of the number of
rows in the table, and the second is a count of the number of non-'NULL'
values in the 'age' column:

     mysql> SELECT COUNT(*), COUNT(age) FROM person;

For some data types, MySQL handles 'NULL' values specially.  If you
insert 'NULL' into a 'TIMESTAMP' column, the current
date and time is inserted.  If you insert 'NULL' into an integer or
floating-point column that has the 'AUTO_INCREMENT' attribute, the next
number in the sequence is inserted.

B.5.4.4 Problems with Column Aliases
....................................

An alias can be used in a query select list to give a column a different
name.  You can use the alias in 'GROUP BY', 'ORDER BY', or 'HAVING'
clauses to refer to the column:

     SELECT SQRT(a*b) AS root FROM TBL_NAME
       GROUP BY root HAVING root > 0;
     SELECT id, COUNT(*) AS cnt FROM TBL_NAME
       GROUP BY id HAVING cnt > 0;
     SELECT id AS 'Customer identity' FROM TBL_NAME;

Standard SQL disallows references to column aliases in a 'WHERE' clause.
This restriction is imposed because when the 'WHERE' clause is
evaluated, the column value may not yet have been determined.  For
example, the following query is illegal:

     SELECT id, COUNT(*) AS cnt FROM TBL_NAME
       WHERE cnt > 0 GROUP BY id;

The 'WHERE' clause determines which rows should be included in the
'GROUP BY' clause, but it refers to the alias of a column value that is
not known until after the rows have been selected, and grouped by the
'GROUP BY'.

In the select list of a query, a quoted column alias can be specified
using identifier or string quoting characters:

     SELECT 1 AS `one`, 2 AS 'two';

Elsewhere in the statement, quoted references to the alias must use
identifier quoting or the reference is treated as a string literal.  For
example, this statement groups by the values in column 'id', referenced
using the alias '`a`':

     SELECT id AS 'a', COUNT(*) AS cnt FROM TBL_NAME
       GROUP BY `a`;

But this statement groups by the literal string ''a'' and will not work
as expected:

     SELECT id AS 'a', COUNT(*) AS cnt FROM TBL_NAME
       GROUP BY 'a';

B.5.4.5 Rollback Failure for Nontransactional Tables
....................................................

If you receive the following message when trying to perform a
'ROLLBACK', it means that one or more of the tables you used in
the transaction do not support transactions:

     Warning: Some non-transactional changed tables couldn't be rolled back

These nontransactional tables are not affected by the 'ROLLBACK'
statement.

If you were not deliberately mixing transactional and nontransactional
tables within the transaction, the most likely cause for this message is
that a table you thought was transactional actually is not.  This can
happen if you try to create a table using a transactional storage engine
that is not supported by your 'mysqld' server (or that
was disabled with a startup option).  If 'mysqld' does
not support a storage engine, it instead creates the table as a 'MyISAM'
table, which is nontransactional.

You can check the storage engine for a table by using either of these
statements:

     SHOW TABLE STATUS LIKE 'TBL_NAME';
     SHOW CREATE TABLE TBL_NAME;

See show-table-status, and show-create-table.

To check which storage engines your 'mysqld' server
supports, use this statement:

     SHOW ENGINES;

See show-engines for full details.

B.5.4.6 Deleting Rows from Related Tables
.........................................

If the total length of the 'DELETE' statement for
'related_table' is more than 1MB (the default value of the
'max_allowed_packet' system variable), you should split it into smaller
parts and execute multiple 'DELETE' statements.  You
probably get the fastest 'DELETE' by specifying only 100
to 1,000 'related_column' values per statement if the 'related_column'
is indexed.  If the 'related_column' isn't indexed, the speed is
independent of the number of arguments in the 'IN' clause.

B.5.4.7 Solving Problems with No Matching Rows
..............................................

If you have a complicated query that uses many tables but that returns
no rows, you should use the following procedure to find out what is
wrong:

  1. Test the query with 'EXPLAIN' to check whether you
     can find something that is obviously wrong.  See explain.

  2. Select only those columns that are used in the 'WHERE' clause.

  3. Remove one table at a time from the query until it returns some
     rows.  If the tables are large, it is a good idea to use 'LIMIT 10'
     with the query.

  4. Issue a 'SELECT' for the column that should have
     matched a row against the table that was last removed from the
     query.

  5. If you are comparing 'FLOAT' or
     'DOUBLE' columns with numbers that have
     decimals, you cannot use equality ('=') comparisons.  This problem
     is common in most computer languages because not all floating-point
     values can be stored with exact precision.  In some cases, changing
     the 'FLOAT' to a 'DOUBLE'
     fixes this.  See problems-with-float.

  6. If you still cannot figure out what is wrong, create a minimal test
     that can be run with 'mysql test < query.sql' that shows your
     problems.  You can create a test file by dumping the tables with
     'mysqldump --quick db_name TBL_NAME_1 ... TBL_NAME_N > query.sql'.
     Open the file in an editor, remove some
     insert lines (if there are more than needed to demonstrate the
     problem), and add your 'SELECT' statement at the end
     of the file.

     Verify that the test file demonstrates the problem by executing
     these commands:

          shell> mysqladmin create test2
          shell> mysql test2 < query.sql

     Attach the test file to a bug report, which you can file using the
     instructions in bug-reports.

B.5.4.8 Problems with Floating-Point Values
...........................................

Floating-point numbers sometimes cause confusion because they are
approximate and not stored as exact values.  A floating-point value as
written in an SQL statement may not be the same as the value represented
internally.  Attempts to treat floating-point values as exact in
comparisons may lead to problems.  They are also subject to platform or
implementation dependencies.  The 'FLOAT'.
and 'DOUBLE' data types are subject to
these issues.  For 'DECIMAL' columns, MySQL
performs operations with a precision of 65 decimal digits, which should
solve most common inaccuracy problems.

The following example uses 'DOUBLE' to
demonstrate how calculations that are done using floating-point
operations are subject to floating-point error.

     mysql> CREATE TABLE t1 (i INT, d1 DOUBLE, d2 DOUBLE);
     mysql> INSERT INTO t1 VALUES (1, 101.40, 21.40), (1, -80.00, 0.00),
         -> (2, 0.00, 0.00), (2, -13.20, 0.00), (2, 59.60, 46.40),
         -> (2, 30.40, 30.40), (3, 37.00, 7.40), (3, -29.60, 0.00),
         -> (4, 60.00, 15.40), (4, -10.60, 0.00), (4, -34.00, 0.00),
         -> (5, 33.00, 0.00), (5, -25.80, 0.00), (5, 0.00, 7.20),
         -> (6, 0.00, 0.00), (6, -51.40, 0.00);

     mysql> SELECT i, SUM(d1) AS a, SUM(d2) AS b
         -> FROM t1 GROUP BY i HAVING a <> b;

     +------+-------+------+
     | i    | a     | b    |
     +------+-------+------+
     |    1 |  21.4 | 21.4 |
     |    2 |  76.8 | 76.8 |
     |    3 |   7.4 |  7.4 |
     |    4 |  15.4 | 15.4 |
     |    5 |   7.2 |  7.2 |
     |    6 | -51.4 |    0 |
     +------+-------+------+

The result is correct.  Although the first five records look like they
should not satisfy the comparison (the values of 'a' and 'b' do not
appear to be different), they may do so because the difference between
the numbers shows up around the tenth decimal or so, depending on
factors such as computer architecture or the compiler version or
optimization level.  For example, different CPUs may evaluate
floating-point numbers differently.

If columns 'd1' and 'd2' had been defined as 'DECIMAL'
rather than 'DOUBLE', the
result of the 'SELECT' query would have contained only
one row--the last one shown above.

The correct way to do floating-point number comparison is to first
decide on an acceptable tolerance for differences between the numbers
and then do the comparison against the tolerance value.  For example, if
we agree that floating-point numbers should be regarded the same if they
are same within a precision of one in ten thousand (0.0001), the
comparison should be written to find differences larger than the
tolerance value:

     mysql> SELECT i, SUM(d1) AS a, SUM(d2) AS b FROM t1
         -> GROUP BY i HAVING ABS(a - b) > 0.0001;
     +------+-------+------+
     | i    | a     | b    |
     +------+-------+------+
     |    6 | -51.4 |    0 |
     +------+-------+------+
     1 row in set (0.00 sec)

Conversely, to get rows where the numbers are the same, the test should
find differences within the tolerance value:

     mysql> SELECT i, SUM(d1) AS a, SUM(d2) AS b FROM t1
         -> GROUP BY i HAVING ABS(a - b) <= 0.0001;
     +------+------+------+
     | i    | a    | b    |
     +------+------+------+
     |    1 | 21.4 | 21.4 |
     |    2 | 76.8 | 76.8 |
     |    3 |  7.4 |  7.4 |
     |    4 | 15.4 | 15.4 |
     |    5 |  7.2 |  7.2 |
     +------+------+------+
     5 rows in set (0.03 sec)

Floating-point values are subject to platform or implementation
dependencies.  Suppose that you execute the following statements:

     CREATE TABLE t1(c1 FLOAT(53,0), c2 FLOAT(53,0));
     INSERT INTO t1 VALUES('1e+52','-1e+52');
     SELECT * FROM t1;

On some platforms, the 'SELECT' statement returns 'inf' and '-inf'.  On
others, it returns '0' and '-0'.

An implication of the preceding issues is that if you attempt to create
a replication slave by dumping table contents with 'mysqldump'
on the master and reloading the dump file into the slave,
tables containing floating-point columns might differ between the two
hosts.

B.5.5 Optimizer-Related Issues
------------------------------

MySQL uses a cost-based optimizer to determine the best way to resolve a
query.  In many cases, MySQL can calculate the best possible query plan,
but sometimes MySQL does not have enough information about the data at
hand and has to make 'educated' guesses about the data.

For the cases when MySQL does not do the "right" thing, tools that you
have available to help MySQL are:

   * Use the 'EXPLAIN' statement to get information
     about how MySQL processes a query.  To use it, just add the keyword
     'EXPLAIN' to the front of your 'SELECT'
     statement:

          mysql> EXPLAIN SELECT * FROM t1, t2 WHERE t1.i = t2.i;

     'EXPLAIN' is discussed in more detail in
     explain.

   * Use 'ANALYZE TABLE TBL_NAME' to update the key distributions for
     the scanned table.  See analyze-table.

   *
     Use 'FORCE INDEX' for the scanned table to tell MySQL that table
     scans are very expensive compared to using the given index:

          SELECT * FROM t1, t2 FORCE INDEX (index_for_column)
          WHERE t1.col_name=t2.col_name;

     'USE INDEX' and 'IGNORE INDEX' may also be useful.  See
     index-hints.

   * Global and table-level 'STRAIGHT_JOIN'.  See select.

   * You can tune global or thread-specific system variables.  For
     example, start 'mysqld' with the
     '--max-seeks-for-key=1000' option or use 'SET
     max_seeks_for_key=1000' to tell the optimizer to assume that no key
     scan causes more than 1,000 key seeks.  See
     server-system-variables.

B.5.6 Table Definition-Related Issues
-------------------------------------

B.5.6.1 Problems with ALTER TABLE
.................................

If you get a duplicate-key error when using 'ALTER TABLE'
to change the character set or collation of a character
column, the cause is either that the new column collation maps two keys
to the same value or that the table is corrupted.  In the latter case,
you should run 'REPAIR TABLE' on the table.
'REPAIR TABLE' works for 'MyISAM', 'ARCHIVE', and 'CSV'
tables.

If 'ALTER TABLE' dies with the following error, the
problem may be that MySQL crashed during an earlier 'ALTER TABLE'
operation and there is an old table named 'A-XXX' or
'B-XXX' lying around:

     Error on rename of './database/name.frm'
     to './database/B-XXX.frm' (Errcode: 17)

In this case, go to the MySQL data directory and delete all files that
have names starting with 'A-' or 'B-'.  (You may want to move them
elsewhere instead of deleting them.)

'ALTER TABLE' works in the following way:

   * Create a new table named 'A-XXX' with the requested structural
     changes.

   * Copy all rows from the original table to 'A-XXX'.

   * Rename the original table to 'B-XXX'.

   * Rename 'A-XXX' to your original table name.

   * Delete 'B-XXX'.

If something goes wrong with the renaming operation, MySQL tries to undo
the changes.  If something goes seriously wrong (although this shouldn't
happen), MySQL may leave the old table as 'B-XXX'.  A simple rename of
the table files at the system level should get your data back.

If you use 'ALTER TABLE' on a transactional table or
if you are using Windows, see 'ALTER TABLE' unlocks the
table if you had done a 'LOCK TABLE' on it.  This is
done because 'InnoDB' and these operating systems cannot drop a table
that is in use.

B.5.6.2 TEMPORARY Table Problems
................................

Temporary tables created with 'CREATE TEMPORARY TABLE'
have the following limitations:

   * 'TEMPORARY' tables are supported only by the 'InnoDB', 'MEMORY',
     'MyISAM', and 'MERGE' storage engines.

   * Temporary tables are not supported for NDB Cluster.

   * The 'SHOW TABLES' statement does not list
     'TEMPORARY' tables.

   * You cannot use 'RENAME TABLE' to rename a
     'TEMPORARY' table.  However, you can use 'ALTER TABLE'
     instead:

          ALTER TABLE old_name RENAME new_name;

   * You cannot refer to a 'TEMPORARY' table more than once in the same
     query.  For example, the following does not work:

          SELECT * FROM temp_table JOIN temp_table AS t2;

     The statement produces this error:

          ERROR 1137: Can't reopen table: 'temp_table'

   * The 'Can't reopen table' error also occurs if you refer to a
     temporary table multiple times in a stored function under different
     aliases, even if the references occur in different statements
     within the function.  It may occur for temporary tables created
     outside stored functions and referred to across multiple calling
     and callee functions.

   * There are known issues in using temporary tables with replication.
     See replication-features-temptables, for more information.

B.5.7 Known Issues in MySQL
---------------------------

This section lists known issues in recent versions of MySQL.

For information about platform-specific issues, see the installation and
porting instructions in general-installation-issues, and
porting.

The following problems are known:

   * Subquery optimization for 'IN' is not as effective as for '='.

   * Even if you use 'lower_case_table_names=2' (which enables MySQL to
     remember the case used for databases and table names), MySQL does
     not remember the case used for database names for the function
     'DATABASE()' or within the various logs (on case-insensitive
     systems).

   * Dropping a 'FOREIGN KEY' constraint does not work in replication
     because the constraint may have another name on the slave.

   * 'REPLACE'. (and 'LOAD DATA' with
     the 'REPLACE' option) does not trigger 'ON DELETE
     CASCADE'.

   * 'DISTINCT' with 'ORDER BY' does not work inside 'GROUP_CONCAT()' if
     you do not use all and only those columns that are in the
     'DISTINCT' list.

   * When inserting a big integer value (between 2^63 and 2^64−1) into
     a decimal or string column, it is inserted as a negative value
     because the number is evaluated in a signed integer context.

   * With statement-based binary logging, the master writes the executed
     queries to the binary log.  This is a very fast, compact, and
     efficient logging method that works perfectly in most cases.
     However, it is possible for the data on the master and slave to
     become different if a query is designed in such a way that the data
     modification is nondeterministic (generally not a recommended
     practice, even outside of replication).

     For example:

        * 'CREATE TABLE ... SELECT' or
          'INSERT ... SELECT' statements that insert
          zero or 'NULL' values into an 'AUTO_INCREMENT' column.

        * 'DELETE' if you are deleting rows from a table
          that has foreign keys with 'ON DELETE CASCADE' properties.

        * 'REPLACE ... SELECT', 'INSERT IGNORE ...
          SELECT' if you have duplicate key values in the inserted data.

     *If and only if the preceding queries have no 'ORDER BY' clause
     guaranteeing a deterministic order*.

     For example, for 'INSERT ... SELECT' with no
     'ORDER BY', the 'SELECT' may return rows in a
     different order (which results in a row having different ranks,
     hence getting a different number in the 'AUTO_INCREMENT' column),
     depending on the choices made by the optimizers on the master and
     slave.

     A query is optimized differently on the master and slave only if:

        * The table is stored using a different storage engine on the
          master than on the slave.  (It is possible to use different
          storage engines on the master and slave.  For example, you can
          use 'InnoDB' on the master, but 'MyISAM' on the slave if the
          slave has less available disk space.)

        * MySQL buffer sizes ('key_buffer_size', and so on) are
          different on the master and slave.

        * The master and slave run different MySQL versions, and the
          optimizer code differs between these versions.

     This problem may also affect database restoration using
     'mysqlbinlog|mysql'.

     The easiest way to avoid this problem is to add an 'ORDER BY'
     clause to the aforementioned nondeterministic queries to ensure
     that the rows are always stored or modified in the same order.
     Using row-based or mixed logging format also avoids the problem.

   * Log file names are based on the server host name if you do not
     specify a file name with the startup option.  To retain the same
     log file names if you change your host name to something else, you
     must explicitly use options such as '--log-bin=OLD_HOST_NAME-bin'.
     See server-options.  Alternatively, rename the old files to
     reflect your host name change.  If these are binary logs, you must
     edit the binary log index file and fix the binary log file names
     there as well.  (The same is true for the relay logs on a slave
     server.)

   * 'mysqlbinlog' does not delete temporary files
     left after a 'LOAD DATA INFILE' statement.  See
     mysqlbinlog.

   * 'RENAME' does not work with 'TEMPORARY' tables or tables used in a
     'MERGE' table.

   * When using 'SET CHARACTER SET', you cannot use translated
     characters in database, table, and column names.

   * You cannot use '_' or '%' with 'ESCAPE' in 'LIKE ... ESCAPE'.

   * The server uses only the first 'max_sort_length' bytes when
     comparing data values.  This means that values cannot reliably be
     used in 'GROUP BY', 'ORDER BY', or 'DISTINCT' if they differ only
     after the first 'max_sort_length' bytes.  To work around this,
     increase the variable value.  The default value of
     'max_sort_length' is 1024 and can be changed at server startup time
     or at runtime.

   * Numeric calculations are done with 'BIGINT'.
     or 'DOUBLE'. (both are normally 64 bits
     long).  Which precision you get depends on the function.  The
     general rule is that bit functions are performed with
     'BIGINT' precision, 'IF()' and 'ELT()' with
     'BIGINT' or 'DOUBLE'.
     precision, and the rest with 'DOUBLE'.
     precision.  You should try to avoid using unsigned long long values
     if they resolve to be larger than 63 bits (9223372036854775807) for
     anything other than bit fields.

   * You can have up to 255 'ENUM' and 'SET'.
     columns in one table.

   * In 'MIN()', 'MAX()', and other aggregate functions, MySQL currently
     compares 'ENUM' and 'SET' columns by their
     string value rather than by the string's relative position in the
     set.

   * In an 'UPDATE' statement, columns are updated from
     left to right.  If you refer to an updated column, you get the
     updated value instead of the original value.  For example, the
     following statement increments 'KEY' by '2', *not* '1':

          mysql> UPDATE TBL_NAME SET KEY=KEY+1,KEY=KEY+1;

   * You can refer to multiple temporary tables in the same query, but
     you cannot refer to any given temporary table more than once.  For
     example, the following does not work:

          mysql> SELECT * FROM temp_table, temp_table AS t2;
          ERROR 1137: Can't reopen table: 'temp_table'

   * The optimizer may handle 'DISTINCT' differently when you are using
     'hidden' columns in a join than when you are not.  In a join,
     hidden columns are counted as part of the result (even if they are
     not shown), whereas in normal queries, hidden columns do not
     participate in the 'DISTINCT' comparison.

     An example of this is:

          SELECT DISTINCT mp3id FROM band_downloads
                 WHERE userid = 9 ORDER BY id DESC;

     and

          SELECT DISTINCT band_downloads.mp3id
                 FROM band_downloads,band_mp3
                 WHERE band_downloads.userid = 9
                 AND band_mp3.id = band_downloads.mp3id
                 ORDER BY band_downloads.id DESC;

     In the second case, you may get two identical rows in the result
     set (because the values in the hidden 'id' column may differ).

     Note that this happens only for queries that do not have the 'ORDER
     BY' columns in the result.

   * If you execute a 'PROCEDURE' on a query that returns an empty set,
     in some cases the 'PROCEDURE' does not transform the columns.

   * Creation of a table of type 'MERGE' does not check whether the
     underlying tables are compatible types.

   * If you use 'ALTER TABLE' to add a 'UNIQUE'
     index to a table used in a 'MERGE' table and then add a normal
     index on the 'MERGE' table, the key order is different for the
     tables if there was an old, non-'UNIQUE' key in the table.  This is
     because 'ALTER TABLE' puts 'UNIQUE' indexes
     before normal indexes to be able to detect duplicate keys as early
     as possible.

Appendix C Restrictions and Limits
**********************************

The discussion here describes restrictions that apply to the use of
MySQL features such as subqueries or views.

C.1 Restrictions on Stored Programs
===================================

These restrictions apply to the features described in
stored-programs-views.

Some of the restrictions noted here apply to all stored routines; that
is, both to stored procedures and stored functions.  There are also some
restrictions specific to stored functions but not to stored procedures.

The restrictions for stored functions also apply to triggers.  There are
also some restrictions specific to triggers.

The restrictions for stored procedures also apply to the 'DO'.
clause of Event Scheduler event definitions.  There are also some
restrictions specific to events.

*SQL Statements Not Permitted in Stored Routines*

Stored routines cannot contain arbitrary SQL statements.  The following
statements are not permitted:

   * The locking statements 'LOCK TABLES' and
     'UNLOCK TABLES'.

   * 'ALTER VIEW'.

   * 'LOAD DATA' and 'LOAD TABLE'.

   * SQL prepared statements (see 'PREPARE', 'EXECUTE',
     see 'DEALLOCATE PREPARE') can be
     used in stored procedures, but not stored functions or triggers.
     Thus, stored functions and triggers cannot use dynamic SQL (where
     you construct statements as strings and then execute them).

   * Generally, statements not permitted in SQL prepared statements are
     also not permitted in stored programs.  For a list of statements
     supported as prepared statements, see
     sql-syntax-prepared-statements.  Exceptions are 'SIGNAL',
     see 'RESIGNAL', and 'GET DIAGNOSTICS',
     which are not permissible as prepared statements
     but are permitted in stored programs.

   * Because local variables are in scope only during stored program
     execution, references to them are not permitted in prepared
     statements created within a stored program.  Prepared statement
     scope is the current session, not the stored program, so the
     statement could be executed after the program ends, at which point
     the variables would no longer be in scope.  For example, 'SELECT
     ... INTO LOCAL_VAR' cannot be used as a prepared statement.  This
     restriction also applies to stored procedure and function
     parameters.  See prepare.

   * Within all stored programs (stored procedures and functions,
     triggers, and events), the parser treats 'BEGIN [WORK]'
     as the beginning of a 'BEGIN ... END'.
     block.  To begin a transaction in this context, use 'START TRANSACTION'
     instead.

*Restrictions for Stored Functions*

The following additional statements or operations are not permitted
within stored functions.  They are permitted within stored procedures,
except stored procedures that are invoked from within a stored function
or trigger.  For example, if you use 'FLUSH' in a stored
procedure, that stored procedure cannot be called from a stored function
or trigger.

   * Statements that perform explicit or implicit commit or rollback.
     Support for these statements is not required by the SQL standard,
     which states that each DBMS vendor may decide whether to permit
     them.

   * Statements that return a result set.  This includes 'SELECT'
     statements that do not have an 'INTO VAR_LIST' clause and
     other statements such as 'SHOW', 'EXPLAIN',
     and 'CHECK TABLE'.  A function can
     process a result set either with 'SELECT ... INTO VAR_LIST'
     or by using a cursor and 'FETCH'.
     statements.  See select-into, and cursors.

   * 'FLUSH' statements.

   * Stored functions cannot be used recursively.

   * A stored function or trigger cannot modify a table that is already
     being used (for reading or writing) by the statement that invoked
     the function or trigger.

   * If you refer to a temporary table multiple times in a stored
     function under different aliases, a 'Can't reopen table:
     'TBL_NAME'' error occurs, even if the references occur in different
     statements within the function.

   * 'HANDLER ... READ' statements that invoke stored
     functions can cause replication errors and are disallowed.

*Restrictions for Triggers*

For triggers, the following additional restrictions apply:

   * Triggers are not activated by foreign key actions.

   * When using row-based replication, triggers on the slave are not
     activated by statements originating on the master.  The triggers on
     the slave are activated when using statement-based replication.
     For more information, see replication-features-triggers.

   * The 'RETURN' statement is not permitted in triggers,
     which cannot return a value.  To exit a trigger immediately, use
     the 'LEAVE' statement.

   * Triggers are not permitted on tables in the 'mysql' database.  Nor
     are they permitted on 'INFORMATION_SCHEMA' or 'performance_schema'
     tables.  Those tables are actually views and triggers are not
     permitted on views.

   * The trigger cache does not detect when metadata of the underlying
     objects has changed.  If a trigger uses a table and the table has
     changed since the trigger was loaded into the cache, the trigger
     operates using the outdated metadata.

*Name Conflicts within Stored Routines*

The same identifier might be used for a routine parameter, a local
variable, and a table column.  Also, the same local variable name can be
used in nested blocks.  For example:

     CREATE PROCEDURE p (i INT)
     BEGIN
       DECLARE i INT DEFAULT 0;
       SELECT i FROM t;
       BEGIN
         DECLARE i INT DEFAULT 1;
         SELECT i FROM t;
       END;
     END;

In such cases, the identifier is ambiguous and the following precedence
rules apply:

   * A local variable takes precedence over a routine parameter or table
     column.

   * A routine parameter takes precedence over a table column.

   * A local variable in an inner block takes precedence over a local
     variable in an outer block.

The behavior that variables take precedence over table columns is
nonstandard.

*Replication Considerations*

Use of stored routines can cause replication problems.  This issue is
discussed further in stored-programs-logging.

The '--replicate-wild-do-table=DB_NAME.TBL_NAME' option applies to
tables, views, and triggers.  It does not apply to stored procedures and
functions, or events.  To filter statements operating on the latter
objects, use one or more of the '--replicate-*-db' options.

*Debugging Considerations*

There are no stored routine debugging facilities.

*Unsupported Syntax from the SQL:2003 Standard*

The MySQL stored routine syntax is based on the SQL:2003 standard.  The
following items from that standard are not currently supported:

   * 'UNDO' handlers

   * 'FOR' loops

*Concurrency Considerations*

To prevent problems of interaction between sessions, when a client
issues a statement, the server uses a snapshot of routines and triggers
available for execution of the statement.  That is, the server
calculates a list of procedures, functions, and triggers that may be
used during execution of the statement, loads them, and then proceeds to
execute the statement.  While the statement executes, it does not see
changes to routines performed by other sessions.

For maximum concurrency, stored functions should minimize their
side-effects; in particular, updating a table within a stored function
can reduce concurrent operations on that table.  A stored function
acquires table locks before executing, to avoid inconsistency in the
binary log due to mismatch of the order in which statements execute and
when they appear in the log.  When statement-based binary logging is
used, statements that invoke a function are recorded rather than the
statements executed within the function.  Consequently, stored functions
that update the same underlying tables do not execute in parallel.  In
contrast, stored procedures do not acquire table-level locks.  All
statements executed within stored procedures are written to the binary
log, even for statement-based binary logging.  See
stored-programs-logging.

*Event Scheduler Restrictions*

The following limitations are specific to the Event Scheduler:

   * Event names are handled in case-insensitive fashion.  For example,
     you cannot have two events in the same database with the names
     'anEvent' and 'AnEvent'.

   * An event may not be created, altered, or dropped by a stored
     routine, trigger, or another event.  An event also may not create,
     alter, or drop stored routines or triggers.  (Bug #16409, Bug
     #18896)

   * DDL statements on events are prohibited while a 'LOCK TABLES'
     statement is in effect.

   * Event timings using the intervals 'YEAR', 'QUARTER', 'MONTH', and
     'YEAR_MONTH' are resolved in months; those using any other interval
     are resolved in seconds.  There is no way to cause events scheduled
     to occur at the same second to execute in a given order.  In
     addition--due to rounding, the nature of threaded applications, and
     the fact that a nonzero length of time is required to create events
     and to signal their execution--events may be delayed by as much as
     1 or 2 seconds.  However, the time shown in the
     'INFORMATION_SCHEMA.EVENTS' table's 'LAST_EXECUTED'
     column or the 'mysql.event' table's 'last_executed' column is
     always accurate to within one second of the actual event execution
     time.  (See also Bug #16522.)

   * Each execution of the statements contained in the body of an event
     takes place in a new connection; thus, these statements has no
     effect in a given user session on the server's statement counts
     such as 'Com_select' and 'Com_insert' that are displayed by
     'SHOW STATUS'.  However, such counts _are_ updated in
     the global scope.  (Bug #16422)

   * Events do not support times later than the end of the Unix Epoch;
     this is approximately the beginning of the year 2038.  Such dates
     are specifically not permitted by the Event Scheduler.  (Bug
     #16396)

   * References to stored functions, user-defined functions, and tables
     in the 'ON SCHEDULE' clauses of 'CREATE EVENT'.
     and 'ALTER EVENT' statements are not supported.
     These sorts of references are not permitted.  (See Bug #22830 for
     more information.)

Stored routines and triggers in NDB Cluster

Stored procedures, stored functions, and triggers are all supported by
tables using the 'NDB' storage engine; however, it
is important to keep in mind that they do _not_ propagate automatically
between MySQL Servers acting as Cluster SQL nodes.  This is because of
the following:

   * Stored routine definitions are kept in tables in the 'mysql' system
     database using the 'MyISAM' storage engine, and so do not
     participate in clustering.

   * The '.TRN' and '.TRG' files containing trigger definitions are not
     read by the 'NDB' storage engine, and are not
     copied between Cluster nodes.

Any stored routine or trigger that interacts with NDB Cluster tables
must be re-created by running the appropriate 'CREATE PROCEDURE',
see 'CREATE FUNCTION', or
'CREATE TRIGGER' statements on each MySQL Server that
participates in the cluster where you wish to use the stored routine or
trigger.  Similarly, any changes to existing stored routines or triggers
must be carried out explicitly on all Cluster SQL nodes, using the
appropriate 'ALTER' or 'DROP' statements on each MySQL Server accessing
the cluster.

*Warning*:

Do _not_ attempt to work around the issue described in the first item
mentioned previously by converting any 'mysql' database tables to use
the 'NDB' storage engine.  _Altering the system
tables in the 'mysql' database is not supported_ and is very likely to
produce undesirable results.

C.2 Restrictions on Condition Handling
======================================

See 'SIGNAL', 'RESIGNAL', and 'GET DIAGNOSTICS'
are not permissible as prepared
statements.  For example, this statement is invalid:

     PREPARE stmt1 FROM 'SIGNAL SQLSTATE "02000"';

'SQLSTATE' values in class ''04'' are not treated specially.  They are
handled the same as other exceptions.

In standard SQL, the first condition relates to the 'SQLSTATE' value
returned for the previous SQL statement.  In MySQL, this is not
guaranteed, so to get the main error, you cannot do this:

     GET DIAGNOSTICS CONDITION 1 @errno = MYSQL_ERRNO;

Instead, do this:

     GET DIAGNOSTICS @cno = NUMBER;
     GET DIAGNOSTICS CONDITION @cno @errno = MYSQL_ERRNO;

C.3 Restrictions on Server-Side Cursors
=======================================

Server-side cursors are implemented in the C API using the
'mysql_stmt_attr_set()' function.  The same
implementation is used for cursors in stored routines.  A server-side
cursor enables a result set to be generated on the server side, but not
transferred to the client except for those rows that the client
requests.  For example, if a client executes a query but is only
interested in the first row, the remaining rows are not transferred.

In MySQL, a server-side cursor is materialized into an internal
temporary table.  Initially, this is a 'MEMORY' table, but is converted
to a 'MyISAM' table when its size exceeds the minimum value of the
'max_heap_table_size' and 'tmp_table_size' system variables.  The same
restrictions apply to internal temporary tables created to hold the
result set for a cursor as for other uses of internal temporary tables.
See internal-temporary-tables.  One limitation of the
implementation is that for a large result set, retrieving its rows
through a cursor might be slow.

Cursors are read only; you cannot use a cursor to update rows.

'UPDATE WHERE CURRENT OF' and 'DELETE WHERE CURRENT OF' are not
implemented, because updatable cursors are not supported.

Cursors are nonholdable (not held open after a commit).

Cursors are asensitive.

Cursors are nonscrollable.

Cursors are not named.  The statement handler acts as the cursor ID.

You can have open only a single cursor per prepared statement.  If you
need several cursors, you must prepare several statements.

You cannot use a cursor for a statement that generates a result set if
the statement is not supported in prepared mode.  This includes
statements such as 'CHECK TABLE', 'HANDLER READ', and
'SHOW BINLOG EVENTS'.

C.4 Restrictions on Subqueries
==============================

   * In general, you cannot modify a table and select from the same
     table in a subquery.  For example, this limitation applies to
     statements of the following forms:

          DELETE FROM t WHERE ... (SELECT ... FROM t ...);
          UPDATE t ... WHERE col = (SELECT ... FROM t ...);
          {INSERT|REPLACE} INTO t (SELECT ... FROM t ...);

     Exception: The preceding prohibition does not apply if for the
     modified table you are using a derived table (subquery in the
     'FROM' clause) and that derived table is materialized rather than
     merged into the outer query.  (See
     derived-table-optimization.)  Example:

          UPDATE t ... WHERE col = (SELECT * FROM (SELECT ... FROM t...) AS dt ...);

     Here the result from the derived table is materialized as a
     temporary table, so the relevant rows in 't' have already been
     selected by the time the update to 't' takes place.

   * Row comparison operations are only partially supported:

        * For 'EXPR [NOT] IN SUBQUERY', EXPR can be an N-tuple
          (specified using row constructor syntax) and the subquery can
          return rows of N-tuples.  The permitted syntax is therefore
          more specifically expressed as 'ROW_CONSTRUCTOR [NOT] IN
          TABLE_SUBQUERY'

        * For 'EXPR OP {ALL|ANY|SOME} SUBQUERY', EXPR must be a scalar
          value and the subquery must be a column subquery; it cannot
          return multiple-column rows.

     In other words, for a subquery that returns rows of N-tuples, this
     is supported:

          (EXPR_1, ..., EXPR_N) [NOT] IN TABLE_SUBQUERY

     But this is not supported:

          (EXPR_1, ..., EXPR_N) OP {ALL|ANY|SOME} SUBQUERY

     The reason for supporting row comparisons for 'IN' but not for the
     others is that 'IN' is implemented by rewriting it as a sequence of
     '=' comparisons and 'AND' operations.  This approach cannot be used
     for 'ALL', 'ANY', or 'SOME'.

   * Subqueries in the 'FROM' clause cannot be correlated subqueries.
     They are materialized in whole (evaluated to produce a result set)
     during query execution, so they cannot be evaluated per row of the
     outer query.  The optimizer delays materialization until the result
     is needed, which may permit materialization to be avoided.  See
     derived-table-optimization.

   * MySQL does not support 'LIMIT' in subqueries for certain subquery
     operators:

          mysql> SELECT * FROM t1
              ->   WHERE s1 IN (SELECT s2 FROM t2 ORDER BY s1 LIMIT 1);
          ERROR 1235 (42000): This version of MySQL doesn't yet support
           'LIMIT & IN/ALL/ANY/SOME subquery'

   * MySQL permits a subquery to refer to a stored function that has
     data-modifying side effects such as inserting rows into a table.
     For example, if 'f()' inserts rows, the following query can modify
     data:

          SELECT ... WHERE x IN (SELECT f() ...);

     This behavior is an extension to the SQL standard.  In MySQL, it
     can produce nondeterministic results because 'f()' might be
     executed a different number of times for different executions of a
     given query depending on how the optimizer chooses to handle it.

     For statement-based or mixed-format replication, one implication of
     this indeterminism is that such a query can produce different
     results on the master and its slaves.

C.5 Restrictions on Views
=========================

View processing is not optimized:

   * It is not possible to create an index on a view.

   * Indexes can be used for views processed using the merge algorithm.
     However, a view that is processed with the temptable algorithm is
     unable to take advantage of indexes on its underlying tables
     (although indexes can be used during generation of the temporary
     tables).

Before MySQL 5.7.7, subqueries cannot be used in the 'FROM' clause of a
view.

There is a general principle that you cannot modify a table and select
from the same table in a subquery.  See subquery-restrictions.

The same principle also applies if you select from a view that selects
from the table, if the view selects from the table in a subquery and the
view is evaluated using the merge algorithm.  Example:

     CREATE VIEW v1 AS
     SELECT * FROM t2 WHERE EXISTS (SELECT 1 FROM t1 WHERE t1.a = t2.a);

     UPDATE t1, v2 SET t1.a = 1 WHERE t1.b = v2.b;

If the view is evaluated using a temporary table, you _can_ select from
the table in the view subquery and still modify that table in the outer
query.  In this case the view will be stored in a temporary table and
thus you are not really selecting from the table in a subquery and
modifying it 'at the same time.' (This is another reason you might wish
to force MySQL to use the temptable algorithm by specifying 'ALGORITHM =
TEMPTABLE' in the view definition.)

You can use 'DROP TABLE' or 'ALTER TABLE'
to drop or alter a table that is used in a view definition.
No warning results from the 'DROP' or 'ALTER' operation, even though
this invalidates the view.  Instead, an error occurs later, when the
view is used.  'CHECK TABLE' can be used to check
for views that have been invalidated by 'DROP' or 'ALTER' operations.

With regard to view updatability, the overall goal for views is that if
any view is theoretically updatable, it should be updatable in practice.
MySQL as quickly as possible.  Many theoretically updatable views can be
updated now, but limitations still exist.  For details, see
view-updatability.

There exists a shortcoming with the current implementation of views.  If
a user is granted the basic privileges necessary to create a view (the
'CREATE VIEW' and 'SELECT' privileges), that user will be unable to call
'SHOW CREATE VIEW' on that object unless the
user is also granted the 'SHOW VIEW' privilege.

That shortcoming can lead to problems backing up a database with
'mysqldump', which may fail due to insufficient privileges.
This problem is described in Bug #22062.

The workaround to the problem is for the administrator to manually grant
the 'SHOW VIEW' privilege to users who are granted 'CREATE VIEW', since
MySQL doesn't grant it implicitly when views are created.

Views do not have indexes, so index hints do not apply.  Use of index
hints when selecting from a view is not permitted.

'SHOW CREATE VIEW' displays view definitions
using an 'AS ALIAS_NAME' clause for each column.  If a column is created
from an expression, the default alias is the expression text, which can
be quite long.  Aliases for column names in 'CREATE VIEW'
statements are checked against the maximum column length of
64 characters (not the maximum alias length of 256 characters).  As a
result, views created from the output of 'SHOW CREATE VIEW'
fail if any column alias exceeds 64 characters.  This
can cause problems in the following circumstances for views with
too-long aliases:

   * View definitions fail to replicate to newer slaves that enforce the
     column-length restriction.

   * Dump files created with 'mysqldump' cannot be
     loaded into servers that enforce the column-length restriction.

A workaround for either problem is to modify each problematic view
definition to use aliases that provide shorter column names.  Then the
view will replicate properly, and can be dumped and reloaded without
causing an error.  To modify the definition, drop and create the view
again with 'DROP VIEW' and 'CREATE VIEW',
or replace the definition with 'CREATE OR REPLACE VIEW'.

For problems that occur when reloading view definitions in dump files,
another workaround is to edit the dump file to modify its 'CREATE VIEW'
statements.  However, this does not change the
original view definitions, which may cause problems for subsequent dump
operations.

C.6 Restrictions on XA Transactions
===================================

XA transaction support is limited to the 'InnoDB' storage engine.

For 'external XA,' a MySQL server acts as a Resource Manager and client
programs act as Transaction Managers.  For 'Internal XA', storage
engines within a MySQL server act as RMs, and the server itself acts as
a TM. Internal XA support is limited by the capabilities of individual
storage engines.  Internal XA is required for handling XA transactions
that involve more than one storage engine.  The implementation of
internal XA requires that a storage engine support two-phase commit at
the table handler level, and currently this is true only for 'InnoDB'.

For 'XA START', the 'JOIN' and 'RESUME' clauses are
not supported.

For 'XA END', the 'SUSPEND [FOR MIGRATE]' clause is
not supported.

The requirement that the BQUAL part of the XID value be different for
each XA transaction within a global transaction is a limitation of the
current MySQL XA implementation.  It is not part of the XA
specification.

Prior to MySQL 5.7.7, XA transactions were not compatible with
replication.  This was because an XA transaction that was in 'PREPARED'
state would be rolled back on clean server shutdown or client
disconnect.  Similarly, an XA transaction that was in 'PREPARED' state
would still exist in 'PREPARED' state in case the server was shutdown
abnormally and then started again, but the contents of the transaction
could not be written to the binary log.  In both of these situations the
XA transaction could not be replicated correctly.

In MySQL 5.7.7 and later, there is a change in behavior and an XA
transaction is written to the binary log in two parts.  When 'XA PREPARE
' is issued, the first part of the transaction up to 'XA PREPARE' is
written using an initial GTID. A 'XA_prepare_log_event' is used to
identify such transactions in the binary log.  When 'XA COMMIT' or 'XA
ROLLBACK' is issued, a second part of the transaction containing only
the 'XA COMMIT' or 'XA ROLLBACK' statement is written using a second
GTID. Note that the initial part of the transaction, identified by
'XA_prepare_log_event', is not necessarily followed by its 'XA COMMIT'
or 'XA ROLLBACK', which can cause interleaved binary logging of any two
XA transactions.  The two parts of the XA transaction can even appear in
different binary log files.  This means that an XA transaction in
'PREPARED' state is now persistent until an explicit 'XA COMMIT' or 'XA
ROLLBACK' statement is issued, ensuring that XA transactions are
compatible with replication.

On a replication slave, immediately after the XA transaction is
prepared, it is detached from the slave applier thread, and can be
committed or rolled back by any thread on the slave.  This means that
the same XA transaction can appear in the
'events_transactions_current' table
with different states on different threads.  The
'events_transactions_current' table
displays the current status of the most recent monitored transaction
event on the thread, and does not update this status when the thread is
idle.  So the XA transaction can still be displayed in the 'PREPARED'
state for the original applier thread, after it has been processed by
another thread.  To positively identify XA transactions that are still
in the 'PREPARED' state and need to be recovered, use the 'XA RECOVER'
statement rather than the Performance Schema
transaction tables.

The following restrictions exist for using XA transactions in MySQL
5.7.7 and later:

   * XA transactions are not fully resilient to an unexpected halt with
     respect to the binary log.  If there is an unexpected halt while
     the server is in the middle of executing an 'XA PREPARE', 'XA
     COMMIT', 'XA ROLLBACK', or 'XA COMMIT ... ONE PHASE' statement, the
     server might not be able to recover to a correct state, leaving the
     server and the binary log in an inconsistent state.  In this
     situation, the binary log might either contain extra XA
     transactions that are not applied, or miss XA transactions that are
     applied.  Also, if GTIDs are enabled, after recovery
     '@@GLOBAL.GTID_EXECUTED' might not correctly describe the
     transactions that have been applied.  Note that if an unexpected
     halt occurs before 'XA PREPARE', between 'XA PREPARE' and 'XA
     COMMIT' (or 'XA ROLLBACK'), or after 'XA COMMIT' (or 'XA
     ROLLBACK'), the server and binary log are correctly recovered and
     taken to a consistent state.

   * If replication filters or binary log filters filter out tables that
     are updated by XA transactions, a replication slave might stop with
     an error because an XA transaction is empty.  You can use filters
     alongside XA transactions as long as the tables that are updated by
     XA transactions are not filtered out and are replicated on every
     replication slave.  If an application must use XA transactions on a
     table that is filtered out on some servers, you can work around
     this by adding an update to the XA transaction for a table that is
     replicated everywhere, so that the XA transaction is never empty.

   * 'FLUSH TABLES WITH READ LOCK' is not compatible with XA
     transactions.

   * XA transactions are considered unsafe for statement-based
     replication.  If two XA transactions committed in parallel on the
     master are being prepared on the slave in the inverse order,
     locking dependencies can occur that cannot be safely resolved, and
     it is possible for replication to fail with deadlock on the slave.
     This situation can occur for a single-threaded or multi-threaded
     replication slave.  When 'binlog_format=STATEMENT' is set, a
     warning is issued for DML statements inside XA transactions.  When
     'binlog_format=MIXED' or 'binlog_format=ROW' is set, DML statements
     inside XA transactions are logged using row-based replication, and
     the potential issue is not present.

C.7 Restrictions on Character Sets
==================================

   * Identifiers are stored in 'mysql' database tables ('user', 'db',
     and so forth) using 'utf8', but identifiers can contain only
     characters in the Basic Multilingual Plane (BMP). Supplementary
     characters are not permitted in identifiers.

   * The 'ucs2', 'utf16', 'utf16le', and 'utf32' character sets have the
     following restrictions:

        * They cannot be used as a client character set, which means
          that they do not work for 'SET NAMES' or
          'SET CHARACTER SET'.  (See
          charset-connection.)

        * It is currently not possible to use 'LOAD DATA INFILE'
          to load data files that use these character sets.

        * 'FULLTEXT' indexes cannot be created on a column that uses any
          of these character sets.  However, you can perform 'IN BOOLEAN
          MODE' searches on the column without an index.

        * The use of 'ENCRYPT()' with these character sets is not
          recommended because the underlying system call expects a
          string terminated by a zero byte.

   * The 'REGEXP' and 'RLIKE' operators work in byte-wise fashion, so
     they are not multibyte safe and may produce unexpected results with
     multibyte character sets.  In addition, these operators compare
     characters by their byte values and accented characters may not
     compare as equal even if a given collation treats them as equal.

C.8 Restrictions on Performance Schema
======================================

The Performance Schema avoids using mutexes to collect or produce data,
so there are no guarantees of consistency and results can sometimes be
incorrect.  Event values in 'performance_schema' tables are
nondeterministic and nonrepeatable.

If you save event information in another table, you should not assume
that the original events will still be available later.  For example, if
you select events from a 'performance_schema' table into a temporary
table, intending to join that table with the original table later, there
might be no matches.

'mysqldump' and 'BACKUP DATABASE' ignore tables in the
'performance_schema' database.

Tables in the 'performance_schema' database cannot be locked with 'LOCK
TABLES', except the 'setup_XXX' tables.

Tables in the 'performance_schema' database cannot be indexed.

Results for queries that refer to tables in the 'performance_schema'
database are not saved in the query cache.

Tables in the 'performance_schema' database are not replicated.

The Performance Schema is not available in 'libmysqld', the embedded
server.

The types of timers might vary per platform.  The
'performance_timers' table shows which event
timers are available.  If the values in this table for a given timer
name are 'NULL', that timer is not supported on your platform.

Instruments that apply to storage engines might not be implemented for
all storage engines.  Instrumentation of each third-party engine is the
responsibility of the engine maintainer.

C.9 Restrictions on Pluggable Authentication
============================================

The first part of this section describes general restrictions on the
applicability of the pluggable authentication framework described at
pluggable-authentication.  The second part describes how
third-party connector developers can determine the extent to which a
connector can take advantage of pluggable authentication capabilities
and what steps to take to become more compliant.

The term 'native authentication' used here refers to authentication
against passwords stored in the 'mysql.user' table.  This is the same
authentication method provided by older MySQL servers, before pluggable
authentication was implemented.  'Windows native authentication' refers
to authentication using the credentials of a user who has already logged
in to Windows, as implemented by the Windows Native Authentication
plugin ('Windows plugin' for short).

*General Pluggable Authentication Restrictions*

   * *Connector/C, Connector/C++:* Clients that use these connectors can
     connect to the server only through accounts that use native
     authentication.

     Exception: A connector supports pluggable authentication if it was
     built to link to 'libmysqlclient' dynamically (rather than
     statically) and it loads the current version of 'libmysqlclient' if
     that version is installed, or if the connector is recompiled from
     source to link against the current 'libmysqlclient'.

   * *Connector/Net:* Clients that use Connector/Net can connect to the
     server through accounts that use native authentication or Windows
     native authentication.

   * *Connector/PHP:* Clients that use this connector can connect to the
     server only through accounts that use native authentication, when
     compiled using the MySQL native driver for PHP ('mysqlnd').

   * *Windows native authentication:* Connecting through an account that
     uses the Windows plugin requires Windows Domain setup.  Without it,
     NTLM authentication is used and then only local connections are
     possible; that is, the client and server must run on the same
     computer.

   * *Proxy users:* Proxy user support is available to the extent that
     clients can connect through accounts authenticated with plugins
     that implement proxy user capability (that is, plugins that can
     return a user name different from that of the connecting user).
     For example, the PAM and Windows plugins support proxy users.  The
     'mysql_native_password' and 'sha256_password' authentication
     plugins do not support proxy users by default, but can be
     configured to do so; see proxy-users-server-user-mapping.

   * *Replication*: Replication slaves can employ not only master
     accounts using native authentication, but can also connect through
     master accounts that use nonnative authentication if the required
     client-side plugin is available.  If the plugin is built into
     'libmysqlclient', it is available by default.  Otherwise, the
     plugin must be installed on the slave side in the directory named
     by the slave 'plugin_dir' system variable.

   * *'FEDERATED' tables:* A
     'FEDERATED' table can access the remote
     table only through accounts on the remote server that use native
     authentication.

*Pluggable Authentication and Third-Party Connectors*

Third-party connector developers can use the following guidelines to
determine readiness of a connector to take advantage of pluggable
authentication capabilities and what steps to take to become more
compliant:

   * An existing connector to which no changes have been made uses
     native authentication and clients that use the connector can
     connect to the server only through accounts that use native
     authentication.  _However, you should test the connector against a
     recent version of the server to verify that such connections still
     work without problem._

     Exception: A connector might work with pluggable authentication
     without any changes if it links to 'libmysqlclient' dynamically
     (rather than statically) and it loads the current version of
     'libmysqlclient' if that version is installed.

   * To take advantage of pluggable authentication capabilities, a
     connector that is 'libmysqlclient'-based should be relinked against
     the current version of 'libmysqlclient'.  This enables the
     connector to support connections though accounts that require
     client-side plugins now built into 'libmysqlclient' (such as the
     cleartext plugin needed for PAM authentication and the Windows
     plugin needed for Windows native authentication).  Linking with a
     current 'libmysqlclient' also enables the connector to access
     client-side plugins installed in the default MySQL plugin directory
     (typically the directory named by the default value of the local
     server's 'plugin_dir' system variable).

     If a connector links to 'libmysqlclient' dynamically, it must be
     ensured that the newer version of 'libmysqlclient' is installed on
     the client host and that the connector loads it at runtime.

   * Another way for a connector to support a given authentication
     method is to implement it directly in the client/server protocol.
     Connector/Net uses this approach to provide support for Windows
     native authentication.

   * If a connector should be able to load client-side plugins from a
     directory different from the default plugin directory, it must
     implement some means for client users to specify the directory.
     Possibilities for this include a command-line option or environment
     variable from which the connector can obtain the directory name.
     Standard MySQL client programs such as 'mysql' and
     'mysqladmin' implement a '--plugin-dir' option.
     See also c-api-plugin-functions.

   * Proxy user support by a connector depends, as described earlier in
     this section, on whether the authentication methods that it
     supports permit proxy users.

C.10 Limits in MySQL
====================

This section lists current limits in MySQL 5.7.

C.10.1 Limits on Joins
----------------------

The maximum number of tables that can be referenced in a single join is
61.  This includes a join handled by merging derived tables (subqueries)
and views in the 'FROM' clause into the outer query block (see
derived-table-optimization).  It also applies to the number of tables
that can be referenced in the definition of a view.

C.10.2 Limits on Number of Databases and Tables
-----------------------------------------------

MySQL has no limit on the number of databases.  The underlying file
system may have a limit on the number of directories.

MySQL has no limit on the number of tables.  The underlying file system
may have a limit on the number of files that represent tables.
Individual storage engines may impose engine-specific constraints.
'InnoDB' permits up to 4 billion tables.

C.10.3 Limits on Table Size
---------------------------

The effective maximum table size for MySQL databases is usually
determined by operating system constraints on file sizes, not by MySQL
internal limits.  For up-to-date information operating system file size
limits, refer to the documentation specific to your operating system.

Windows users, please note that FAT and VFAT (FAT32) are _not_
considered suitable for production use with MySQL. Use NTFS instead.

If you encounter a full-table error, there are several reasons why it
might have occurred:

   * The disk might be full.

   * You are using 'InnoDB' tables and have run out of room in an
     'InnoDB' tablespace file.  The maximum tablespace size is also the
     maximum size for a table.  For tablespace size limits, see
     innodb-restrictions.

     Generally, partitioning of tables into multiple tablespace files is
     recommended for tables larger than 1TB in size.

   * You have hit an operating system file size limit.  For example, you
     are using 'MyISAM' tables on an operating system that supports
     files only up to 2GB in size and you have hit this limit for the
     data file or index file.

   * You are using a 'MyISAM' table and the space required for the table
     exceeds what is permitted by the internal pointer size.  'MyISAM'
     permits data and index files to grow up to 256TB by default, but
     this limit can be changed up to the maximum permissible size of
     65,536TB (256^7 − 1 bytes).

     If you need a 'MyISAM' table that is larger than the default limit
     and your operating system supports large files, the 'CREATE TABLE'
     statement supports 'AVG_ROW_LENGTH' and
     'MAX_ROWS' options.  See create-table.  The server uses
     these options to determine how large a table to permit.

     If the pointer size is too small for an existing table, you can
     change the options with 'ALTER TABLE' to
     increase a table's maximum permissible size.  See
     alter-table.

          ALTER TABLE TBL_NAME MAX_ROWS=1000000000 AVG_ROW_LENGTH=NNN;

     You have to specify 'AVG_ROW_LENGTH' only for tables with
     'BLOB' or 'TEXT' columns; in this case, MySQL
     can't optimize the space required based only on the number of rows.

     To change the default size limit for 'MyISAM' tables, set the
     'myisam_data_pointer_size', which sets the number of bytes used for
     internal row pointers.  The value is used to set the pointer size
     for new tables if you do not specify the 'MAX_ROWS' option.  The
     value of 'myisam_data_pointer_size' can be from 2 to 7.  A value of
     4 permits tables up to 4GB; a value of 6 permits tables up to
     256TB.

     You can check the maximum data and index sizes by using this
     statement:

          SHOW TABLE STATUS FROM DB_NAME LIKE 'TBL_NAME';

     You also can use 'myisamchk -dv /path/to/table-index-file'.
     See show, or myisamchk.

     Other ways to work around file-size limits for 'MyISAM' tables are
     as follows:

        * If your large table is read only, you can use
          'myisampack' to compress it.  'myisampack'
          usually compresses a table by at least 50%, so you
          can have, in effect, much bigger tables.  'myisampack'
          also can merge multiple tables into a single
          table.  See myisampack.

        * MySQL includes a 'MERGE' library that enables you to handle a
          collection of 'MyISAM' tables that have identical structure as
          a single 'MERGE' table.  See merge-storage-engine.

   * You are using the 'MEMORY' ('HEAP') storage engine; in this case
     you need to increase the value of the 'max_heap_table_size' system
     variable.  See server-system-variables.

C.10.4 Limits on Table Column Count and Row Size
------------------------------------------------

*Column Count Limits*

MySQL has hard limit of 4096 columns per table, but the effective
maximum may be less for a given table.  The exact column limit depends
on several factors:

   * The maximum row size for a table constrains the number (and
     possibly size) of columns because the total length of all columns
     cannot exceed this size.  See row-size-limits.

   * The storage requirements of individual columns constrain the number
     of columns that fit within a given maximum row size.  Storage
     requirements for some data types depend on factors such as storage
     engine, storage format, and character set.  See
     storage-requirements.

   * Storage engines may impose additional restrictions that limit table
     column count.  For example, see 'InnoDB'.
     has a limit of 1017 columns per table.  See
     innodb-restrictions.  For information about other storage
     engines, see storage-engines.

   * Each table has an '.frm' file that contains the table definition.
     The definition affects the content of this file in ways that may
     affect the number of columns permitted in the table.  See
     limits-frm-file.

*Row Size Limits*

The maximum row size for a given table is determined by several factors:

   * The internal representation of a MySQL table has a maximum row size
     limit of 65,535 bytes, even if the storage engine is capable of
     supporting larger rows.  'BLOB' and 'TEXT'
     columns only contribute 9 to 12 bytes toward the row size
     limit because their contents are stored separately from the rest of
     the row.

   * The maximum row size for an 'InnoDB' table, which applies to data
     stored locally within a database page, is slightly less than half a
     page for 4KB, 8KB, 16KB, and 32KB 'innodb_page_size' settings.  For
     example, the maximum row size is slightly less than 8KB for the
     default 16KB 'InnoDB' page size.  For 64KB pages, the maximum row
     size is slightly less than 16KB. See innodb-restrictions.

     If a row containing variable-length columns exceeds the 'InnoDB'
     maximum row size, 'InnoDB' selects variable-length columns for
     external off-page storage until the row fits within the 'InnoDB'
     row size limit.  The amount of data stored locally for
     variable-length columns that are stored off-page differs by row
     format.  For more information, see innodb-row-format.

   * Different storage formats use different amounts of page header and
     trailer data, which affects the amount of storage available for
     rows.

        * For information about 'InnoDB' row formats, see
          innodb-row-format, and innodb-physical-record.

        * For information about 'MyISAM' storage formats, see
          myisam-table-formats.

*Row Size Limit Examples*

   * The MySQL maximum row size limit of 65,535 bytes is demonstrated in
     the following 'InnoDB' and 'MyISAM' examples.  The limit is
     enforced regardless of storage engine, even though the storage
     engine may be capable of supporting larger rows.

          mysql> CREATE TABLE t (a VARCHAR(10000), b VARCHAR(10000),
                 c VARCHAR(10000), d VARCHAR(10000), e VARCHAR(10000),
                 f VARCHAR(10000), g VARCHAR(6000)) ENGINE=InnoDB CHARACTER SET latin1;
          ERROR 1118 (42000): Row size too large. The maximum row size for the used
          table type, not counting BLOBs, is 65535. This includes storage overhead,
          check the manual. You have to change some columns to TEXT or BLOBs

          mysql> CREATE TABLE t (a VARCHAR(10000), b VARCHAR(10000),
                 c VARCHAR(10000), d VARCHAR(10000), e VARCHAR(10000),
                 f VARCHAR(10000), g VARCHAR(6000)) ENGINE=MyISAM CHARACTER SET latin1;
          ERROR 1118 (42000): Row size too large. The maximum row size for the used
          table type, not counting BLOBs, is 65535. This includes storage overhead,
          check the manual. You have to change some columns to TEXT or BLOBs

     In the following 'MyISAM' example, changing a column to
     'TEXT' avoids the 65,535-byte row size limit and permits the
     operation to succeed because 'BLOB' and 'TEXT'
     columns only contribute 9 to 12 bytes toward the row size.

          mysql> CREATE TABLE t (a VARCHAR(10000), b VARCHAR(10000),
                 c VARCHAR(10000), d VARCHAR(10000), e VARCHAR(10000),
                 f VARCHAR(10000), g TEXT(6000)) ENGINE=MyISAM CHARACTER SET latin1;
          Query OK, 0 rows affected (0.02 sec)

     The operation succeeds for an 'InnoDB' table because changing a
     column to 'TEXT' avoids the MySQL 65,535-byte row size
     limit, and 'InnoDB' off-page storage of variable-length columns
     avoids the 'InnoDB' row size limit.

          mysql> CREATE TABLE t (a VARCHAR(10000), b VARCHAR(10000),
                 c VARCHAR(10000), d VARCHAR(10000), e VARCHAR(10000),
                 f VARCHAR(10000), g TEXT(6000)) ENGINE=InnoDB CHARACTER SET latin1;
          Query OK, 0 rows affected (0.02 sec)

   * Storage for variable-length columns includes length bytes, which
     are counted toward the row size.  For example, a
     'VARCHAR(255) CHARACTER SET utf8mb3' column takes two bytes
     to store the length of the value, so each value can take up to 767
     bytes.

     The statement to create table 't1' succeeds because the columns
     require 32,765 + 2 bytes and 32,766 + 2 bytes, which falls within
     the maximum row size of 65,535 bytes:

          mysql> CREATE TABLE t1
                 (c1 VARCHAR(32765) NOT NULL, c2 VARCHAR(32766) NOT NULL)
                 ENGINE = InnoDB CHARACTER SET latin1;
          Query OK, 0 rows affected (0.02 sec)

     The statement to create table 't2' fails because, although the
     column length is within the maximum length of 65,535 bytes, two
     additional bytes are required to record the length, which causes
     the row size to exceed 65,535 bytes:

          mysql> CREATE TABLE t2
                 (c1 VARCHAR(65535) NOT NULL)
                 ENGINE = InnoDB CHARACTER SET latin1;
          ERROR 1118 (42000): Row size too large. The maximum row size for the used
          table type, not counting BLOBs, is 65535. This includes storage overhead,
          check the manual. You have to change some columns to TEXT or BLOBs

     Reducing the column length to 65,533 or less permits the statement
     to succeed.

          mysql> CREATE TABLE t2
                 (c1 VARCHAR(65533) NOT NULL)
                 ENGINE = InnoDB CHARACTER SET latin1;
          Query OK, 0 rows affected (0.01 sec)

   * For 'MyISAM' tables, 'NULL' columns
     require additional space in the row to record whether their values
     are 'NULL'.  Each 'NULL' column takes one bit extra, rounded up to
     the nearest byte.

     The statement to create table 't3' fails because 'MyISAM'
     requires space for 'NULL' columns in
     addition to the space required for variable-length column length
     bytes, causing the row size to exceed 65,535 bytes:

          mysql> CREATE TABLE t3
                 (c1 VARCHAR(32765) NULL, c2 VARCHAR(32766) NULL)
                 ENGINE = MyISAM CHARACTER SET latin1;
          ERROR 1118 (42000): Row size too large. The maximum row size for the used
          table type, not counting BLOBs, is 65535. This includes storage overhead,
          check the manual. You have to change some columns to TEXT or BLOBs

     For information about 'InnoDB'. 'NULL'
     column storage, see innodb-physical-record.

   * 'InnoDB' restricts row size (for data stored locally within the
     database page) to slightly less than half a database page for 4KB,
     8KB, 16KB, and 32KB 'innodb_page_size' settings, and to slightly
     less than 16KB for 64KB pages.

     The statement to create table 't4' fails because the defined
     columns exceed the row size limit for a 16KB 'InnoDB' page.

          mysql> CREATE TABLE t4 (
                 c1 CHAR(255),c2 CHAR(255),c3 CHAR(255),
                 c4 CHAR(255),c5 CHAR(255),c6 CHAR(255),
                 c7 CHAR(255),c8 CHAR(255),c9 CHAR(255),
                 c10 CHAR(255),c11 CHAR(255),c12 CHAR(255),
                 c13 CHAR(255),c14 CHAR(255),c15 CHAR(255),
                 c16 CHAR(255),c17 CHAR(255),c18 CHAR(255),
                 c19 CHAR(255),c20 CHAR(255),c21 CHAR(255),
                 c22 CHAR(255),c23 CHAR(255),c24 CHAR(255),
                 c25 CHAR(255),c26 CHAR(255),c27 CHAR(255),
                 c28 CHAR(255),c29 CHAR(255),c30 CHAR(255),
                 c31 CHAR(255),c32 CHAR(255),c33 CHAR(255)
                 ) ENGINE=InnoDB ROW_FORMAT=COMPACT DEFAULT CHARSET latin1;
          ERROR 1118 (42000): Row size too large (> 8126). Changing some columns to TEXT or BLOB or using
          ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help. In current row format, BLOB prefix of 768
          bytes is stored inline.

C.10.5 Limits Imposed by .frm File Structure
--------------------------------------------

Each table has an '.frm' file that contains the table definition.  The
server uses the following expression to check some of the table
information stored in the file against an upper limit of 64KB:

     if (info_length+(ulong) create_fields.elements*FCOMP+288+
         n_length+int_length+com_length > 65535L || int_count > 255)

The portion of the information stored in the '.frm' file that is checked
against the expression cannot grow beyond the 64KB limit, so if the
table definition reaches this size, no more columns can be added.

The relevant factors in the expression are:

   * 'info_length' is space needed for 'screens.' This is related to
     MySQL's Unireg heritage.

   * 'create_fields.elements' is the number of columns.

   * 'FCOMP' is 17.

   * 'n_length' is the total length of all column names, including one
     byte per name as a separator.

   * 'int_length' is related to the list of values for 'ENUM'
     and 'SET' columns.  In this context, 'int' does
     not mean 'integer.' It means 'interval,' a term that refers
     collectively to 'ENUM' and 'SET' columns.

   * 'int_count' is the number of unique 'ENUM' and
     'SET' definitions.

   * 'com_length' is the total length of column comments.

The expression just described has several implications for permitted
table definitions:

   * Using long column names can reduce the maximum number of columns,
     as can the inclusion of 'ENUM' or 'SET'.
     columns, or use of column comments.

   * A table can have no more than 255 unique 'ENUM' and
     'SET' definitions.  Columns with identical element
     lists are considered the same against this limt.  For example, if a
     table contains these two columns, they count as one (not two)
     toward this limit because the definitions are identical:

          e1 ENUM('a','b','c')
          e2 ENUM('a','b','c')

   * The sum of the length of element names in the unique 'ENUM'
     and 'SET' definitions counts toward the 64KB
     limit, so although the theoretical limit on number of elements in a
     given 'ENUM' column is 65,535, the practical limit is
     less than 3000.

C.10.6 Windows Platform Limitations
-----------------------------------

The following limitations apply to use of MySQL on the Windows platform:

   * *Process memory*

     On Windows 32-bit platforms, it is not possible by default to use
     more than 2GB of RAM within a single process, including MySQL. This
     is because the physical address limit on Windows 32-bit is 4GB and
     the default setting within Windows is to split the virtual address
     space between kernel (2GB) and user/applications (2GB).

     Some versions of Windows have a boot time setting to enable larger
     applications by reducing the kernel application.  Alternatively, to
     use more than 2GB, use a 64-bit version of Windows.

   * *File system aliases*

     When using 'MyISAM' tables, you cannot use aliases within Windows
     link to the data files on another volume and then link back to the
     main MySQL 'datadir' location.

     This facility is often used to move the data and index files to a
     RAID or other fast solution, while retaining the main '.frm' files
     in the default data directory configured with the 'datadir' option.

   * *Limited number of ports*

     Windows systems have about 4,000 ports available for client
     connections, and after a connection on a port closes, it takes two
     to four minutes before the port can be reused.  In situations where
     clients connect to and disconnect from the server at a high rate,
     it is possible for all available ports to be used up before closed
     ports become available again.  If this happens, the MySQL server
     appears to be unresponsive even though it is running.  Ports may be
     used by other applications running on the machine as well, in which
     case the number of ports available to MySQL is lower.

     For more information about this problem, see
     <http://support.microsoft.com/default.aspx?scid=kb;en-us;196271>.

   * *'DATA DIRECTORY' and 'INDEX DIRECTORY'*

     The 'DATA DIRECTORY' option for 'CREATE TABLE'.
     is supported on Windows only for 'InnoDB' tables, as described in
     tablespace-placing.  For 'MyISAM' and other storage
     engines, the 'DATA DIRECTORY' and 'INDEX DIRECTORY' options for
     'CREATE TABLE' are ignored on Windows and any
     other platforms with a nonfunctional 'realpath()' call.

   * *See 'DROP DATABASE'.*

     You cannot drop a database that is in use by another session.

   * *Case-insensitive names*

     File names are not case-sensitive on Windows, so MySQL database and
     table names are also not case-sensitive on Windows.  The only
     restriction is that database and table names must be specified
     using the same case throughout a given statement.  See
     identifier-case-sensitivity.

   * *Directory and file names*

     On Windows, MySQL Server supports only directory and file names
     that are compatible with the current ANSI code pages.  For example,
     the following Japanese directory name will not work in the Western
     locale (code page 1252):

          datadir="C:/私たちのプロジェクトのデータ"

     The same limitation applies to directory and file names referred to
     in SQL statements, such as the data file path name in 'LOAD DATA INFILE'.

   * *The '\' path name separator character*

     Path name components in Windows are separated by the '\' character,
     which is also the escape character in MySQL. If you are using
     'LOAD DATA INFILE' or 'SELECT ... INTO OUTFILE',
     use Unix-style file names with '/' characters:

          mysql> LOAD DATA INFILE 'C:/tmp/skr.txt' INTO TABLE skr;
          mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;

     Alternatively, you must double the '\' character:

          mysql> LOAD DATA INFILE 'C:\\tmp\\skr.txt' INTO TABLE skr;
          mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr;

   * *Problems with pipes*

     Pipes do not work reliably from the Windows command-line prompt.
     If the pipe includes the character '^Z' / 'CHAR(24)', Windows
     thinks that it has encountered end-of-file and aborts the program.

     This is mainly a problem when you try to apply a binary log as
     follows:

          C:\> mysqlbinlog BINARY_LOG_FILE | mysql --user=root

     If you have a problem applying the log and suspect that it is
     because of a '^Z' / 'CHAR(24)' character, you can use the following
     workaround:

          C:\> mysqlbinlog BINARY_LOG_FILE --result-file=/tmp/bin.sql
          C:\> mysql --user=root --execute "source /tmp/bin.sql"

     The latter command also can be used to reliably read in any SQL
     file that may contain binary data.

Appendix D Indexes
******************

See c-api-function-overview my-init
mysql-thread-init

See c-api-data-structures c-api-function-overview
call information-functions insert
mysql-affected-rows mysql-next-result mysql-num-rows
See mysql-stmt-affected-rows mysql-use-result
replace query-results

See c-api-function-overview

See c-api-function-overview mysql-commands
mysql-change-user mysql-reset-connection

See c-api-function-overview

See c-api-function-overview

See c-api-function-overview

See c-api-function-overview communication-errors
mysql-close mysql-commit mysql-connect
mysql-init mysql-rollback

See c-api-function-overview

See c-api-function-overview my-init mysql-close
See mysql-connect mysql-options mysql-thread-init
See c-api-threaded-clients

See c-api-function-overview

See c-api-function-overview mysql-data-seek
mysql-row-seek mysql-use-result

See c-api-function-overview mysql-debug

See c-api-function-overview

See c-api-function-overview

See c-api-function-overview mysql-eof

See audit-log-file-formats c-api-functions
c-api-function-overview mysql-client-find-plugin
mysql-client-register-plugin mysql-connect mysql-eof
See mysql-errno mysql-field-count mysql-load-plugin
See mysql-num-fields mysql-sqlstate mysql-stmt-close
See mysql-stmt-errno mysql-store-result
mysql-use-result signal-condition-information-items
error-types null-mysql-store-result

See c-api-functions c-api-function-overview
mysql-client-find-plugin mysql-client-register-plugin
mysql-connect mysql-eof mysql-error
mysql-load-plugin mysql-stmt-close mysql-stmt-error
See mysql-store-result mysql-use-result
signal-condition-information-items error-types
null-mysql-store-result

See c-api-function-overview secure-client-programming
mysql-escape-string

See c-api-data-structures c-api-function-overview
mysql-fetch-field mysql-field-seek mysql-field-tell
See mysql-stmt-result-metadata

See c-api-function-overview mysql-stmt-result-metadata

See c-api-function-overview mysql-stmt-result-metadata

See c-api-function-overview mysql-fetch-lengths
mysql-fetch-row

See c-api-data-structures c-api-function-overview
federated-description mysql-eof mysql-errno
mysql-fetch-lengths mysql-fetch-row mysql-row-tell
See mysql-store-result mysql-use-result
query-results

See c-api-function-overview mysql-field-count
mysql-num-fields mysql-query mysql-real-query
mysql-stmt-result-metadata mysql-store-result
null-mysql-store-result

See c-api-data-structures c-api-function-overview
mysql-fetch-field mysql-field-tell
mysql-stmt-result-metadata

See c-api-function-overview mysql-stmt-result-metadata

See c-api-function-overview
c-api-prepared-statement-function-overview
commands-out-of-sync mysql-free-result mysql-list-dbs
See mysql-list-fields mysql-list-processes
mysql-list-tables mysql-next-result
mysql-stmt-result-metadata mysql-store-result
mysql-use-result

See c-api-function-overview adding-collation-choosing-id

See c-api-function-overview c-api-server-client-versions
See mysql-connect

See c-api-function-overview c-api-server-client-versions

See c-api-function-overview

See c-api-function-overview mysql-options

See c-api-function-overview

See c-api-function-overview c-api-server-client-versions

See c-api-function-overview c-api-server-client-versions

See c-api-encrypted-connections c-api-function-overview
See mysql-get-ssl-cipher

See c-api-function-overview mysql-hex-string

See alter-table c-api-function-overview insert
load-data mysql-info mysql-options
constraint-primary-key update query-results

See c-api-function-overview my-init mysql-close
See mysql-get-ssl-cipher mysql-init
mysql-library-init mysql-options mysql-real-connect
See mysql-ssl-set mysql-thread-init
c-api-threaded-clients

See c-api-data-structures c-api-function-overview
create-table getting-unique-id information-functions
See insert mysql-insert-id server-system-variables
See example-auto-increment query-results

See c-api-auto-reconnect c-api-function-overview
mysql-kill mysql-thread-id mysql-nutshell

See c-api-embedded-server-functions c-api-function-overview
See libmysqld mysql-library-end mysql-library-init
See mysql-server-end mysql-server-init

See c-api-embedded-server-functions c-api-function-overview
See libmysqld my-init mysql-init
mysql-library-init mysql-load-plugin mysql-server-init
See mysql-thread-init libmysqld-options
c-api-threaded-clients

See c-api-function-overview mysql-free-result
mysql-list-dbs

See c-api-data-structures c-api-function-overview
mysql-list-fields mysql-nutshell

See c-api-function-overview mysql-nutshell

See c-api-function-overview mysql-list-tables

See c-api-function-overview client-plugin-descriptors
mysql-load-plugin mysql-load-plugin-v

See c-api-function-overview mysql-load-plugin

See c-api-function-overview c-api-multiple-queries
mysql-more-results mysql-next-result
mysql-stmt-next-result

See c-api-function-overview c-api-multiple-queries
call mysql-more-results mysql-next-result
mysql-real-connect mysql-set-server-option
mysql-store-result

See c-api-function-overview mysql-fetch-field-direct
mysql-fetch-row mysql-stmt-result-metadata

See c-api-data-structures c-api-function-overview
mysql-affected-rows mysql-data-seek mysql-num-rows
See mysql-store-result mysql-use-result
query-results

See c-api-auto-reconnect c-api-plugin-functions
c-api-encrypted-connections c-api-function-overview
c-api-prepared-statement-data-structures
client-plugin-descriptors cleartext-pluggable-authentication
See charset-connection gone-away mysql-get-option
See mysql-options mysql-options4 mysql-ping
mysql-real-connect mysql-ssl-set mysql-stmt-fetch
See expired-password-handling
performance-schema-connection-attribute-tables
plugin-api-components load-data-local
sha256-pluggable-authentication
session-account-connect-attrs-table
session-connect-attrs-table user-names
multiple-server-clients writing-authentication-plugins-setup
See using-own-protocol-trace-plugins mysql-nutshell

See c-api-function-overview error-messages-client
mysql-options mysql-options4
performance-schema-connection-attribute-tables
session-account-connect-attrs-table
session-connect-attrs-table

See c-api-auto-reconnect c-api-function-overview
gone-away mysql-ping mysql-thread-id

See c-api-function-overview

See c-api-function-overview c-api-multiple-queries
call getting-unique-id mysql-affected-rows
mysql-create-db mysql-drop-db mysql-fetch-field
mysql-kill mysql-list-fields mysql-list-processes
See mysql-next-result mysql-query mysql-real-connect
See mysql-real-query mysql-refresh mysql-reload
See mysql-set-local-infile-handler mysql-set-server-option
See mysql-shutdown mysql-store-result
mysql-use-result mysql-nutshell
null-mysql-store-result c-api-threaded-clients

See c-api-encrypted-connections c-api-function-overview
See c-api-multiple-queries call functions
information-functions insert-on-duplicate insert
mysql-affected-rows mysql-change-user mysql-connect
See mysql-init mysql-next-result mysql-options
mysql-real-connect mysql-set-server-option
mysql-sqlstate mysql-ssl-set expired-password-handling
See sql-syntax-prepared-statements server-system-variables
See stored-routines-syntax multiple-server-clients

See c-api-function-overview mysql-real-escape-string
mysql-set-character-set

See c-api-function-overview secure-client-programming
mysql-escape-string mysql-real-escape-string
mysql-real-escape-string-quote populating-spatial-columns
See string-literals

See c-api-function-overview c-api-multiple-queries
call federated-description mysql-affected-rows
mysql-next-result mysql-query mysql-real-connect
mysql-real-query mysql-set-server-option
mysql-store-result mysql-use-result

See c-api-function-overview mysql-nutshell

See c-api-function-overview

See c-api-function-overview mysql-change-user
mysql-reset-connection

See c-api-function-overview

See c-api-function-overview mysql-row-seek
mysql-row-tell mysql-store-result mysql-use-result

See c-api-function-overview mysql-row-seek
mysql-row-tell mysql-store-result mysql-use-result

See c-api-function-overview mysql-select-db

See c-api-function-overview mysql-server-end
mysql-server-init

See c-api-function-overview my-init
mysql-server-init mysql-thread-init

See c-api-function-overview mysql-session-track-get-first
See mysql-session-track-get-next

See c-api-function-overview mysql-session-track-get-first
See mysql-session-track-get-next

See c-api-function-overview mysql-get-character-set-info
See mysql-real-escape-string mysql-real-escape-string-quote

See c-api-function-overview

See c-api-function-overview mysql-set-local-infile-default
See mysql-set-local-infile-handler

See c-api-function-overview c-api-multiple-queries
mysql-set-server-option

See c-api-function-overview mysql-shutdown
privileges-provided shutdown

See c-api-function-overview mysql-errno
mysql-sqlstate mysql-stmt-close mysql-stmt-sqlstate
See signal-condition-information-items error-types

See c-api-encrypted-connections c-api-function-overview
See mysql-real-connect mysql-ssl-set

See c-api-function-overview

See c-api-prepared-statement-function-overview
mysql-stmt-affected-rows mysql-stmt-execute
mysql-stmt-next-result mysql-stmt-num-rows

See c-api-prepared-statement-function-overview

See c-api-data-structures
c-api-prepared-statement-function-overview
c-api-prepared-statement-type-conversions mysql-stmt-execute
See mysql-stmt-fetch mysql-stmt-store-result
cursor-restrictions

See c-api-prepared-statement-data-structures
c-api-prepared-statement-function-overview
c-api-prepared-statement-date-handling mysql-stmt-bind-param
See mysql-stmt-execute mysql-stmt-prepare
mysql-stmt-send-long-data

See c-api-prepared-statement-data-structures
c-api-prepared-statement-function-overview
c-api-prepared-statement-date-handling mysql-stmt-bind-result
See mysql-stmt-fetch mysql-stmt-fetch-column
mysql-stmt-next-result mysql-stmt-store-result

See c-api-prepared-statement-data-structures
c-api-prepared-statement-function-overview mysql-stmt-close
See mysql-stmt-errno mysql-stmt-error
mysql-stmt-init mysql-stmt-sqlstate
prepared-statements-instances-table

See c-api-prepared-statement-function-overview
mysql-stmt-data-seek mysql-stmt-row-seek
mysql-stmt-store-result

See c-api-prepared-statement-function-overview
mysql-stmt-close mysql-stmt-errno mysql-stmt-fetch
See error-types

See c-api-prepared-statement-function-overview
mysql-stmt-close mysql-stmt-error mysql-stmt-fetch
See mysql-stmt-prepare error-types

See c-api-prepared-statement-data-structures
c-api-prepared-statement-function-overview
c-api-prepared-statement-date-handling
c-api-prepared-statement-type-conversions
query-cache-operation mysql-stmt-affected-rows
mysql-stmt-attr-set mysql-stmt-execute
mysql-stmt-fetch mysql-stmt-next-result
mysql-stmt-send-long-data mysql-stmt-store-result
prepared-statements-instances-table

See c-api-prepared-statement-data-structures
c-api-prepared-statement-function-overview
c-api-prepared-statement-type-conversions
mysql-stmt-bind-result mysql-stmt-execute
mysql-stmt-fetch mysql-stmt-result-metadata
mysql-stmt-row-tell mysql-stmt-store-result

See c-api-prepared-statement-function-overview
error-messages-client mysql-stmt-fetch

See c-api-prepared-statement-function-overview
mysql-stmt-field-count

See c-api-prepared-statement-function-overview
mysql-stmt-attr-set mysql-stmt-free-result
mysql-stmt-next-result

See c-api-prepared-statement-data-structures
c-api-prepared-statement-functions
c-api-prepared-statement-function-overview
c-api-prepared-statements mysql-stmt-execute
mysql-stmt-prepare

See c-api-prepared-statement-function-overview

See c-api-prepared-call-statements
c-api-prepared-statement-function-overview call
mysql-stmt-next-result

See c-api-prepared-statement-function-overview
mysql-stmt-data-seek mysql-stmt-num-rows

See c-api-prepared-statement-function-overview
mysql-stmt-execute

See c-api-prepared-statement-function-overview

See c-api-prepared-statement-data-structures
c-api-prepared-statement-function-overview
c-api-prepared-statement-date-handling statement-caching
query-cache-operation mysql-stmt-bind-param
mysql-stmt-execute mysql-stmt-field-count
mysql-stmt-prepare mysql-stmt-reset
mysql-stmt-result-metadata sql-syntax-prepared-statements
See prepared-statements-instances-table

See c-api-prepared-statement-function-overview
mysql-stmt-attr-set mysql-stmt-send-long-data

See c-api-prepared-statement-function-overview
c-api-prepared-statement-type-conversions mysql-stmt-fetch
See mysql-stmt-result-metadata mysql-stmt-store-result

See c-api-prepared-statement-function-overview
mysql-stmt-row-seek mysql-stmt-row-tell
mysql-stmt-store-result

See c-api-prepared-statement-function-overview
mysql-stmt-row-seek mysql-stmt-row-tell
mysql-stmt-store-result

See c-api-prepared-statement-function-overview
error-messages-client mysql-stmt-reset
mysql-stmt-send-long-data server-system-variables

See c-api-prepared-statement-function-overview
mysql-stmt-close mysql-stmt-sqlstate error-types

See c-api-data-structures
c-api-prepared-statement-function-overview mysql-stmt-attr-set
See mysql-stmt-data-seek mysql-stmt-fetch
mysql-stmt-num-rows mysql-stmt-row-seek
mysql-stmt-row-tell mysql-stmt-store-result

See c-api-data-structures c-api-function-overview
commands-out-of-sync federated-description mysql
mysql-affected-rows mysql-data-seek mysql-eof
mysql-fetch-field mysql-fetch-row mysql-field-count
See mysql-free-result mysql-next-result
mysql-num-fields mysql-num-rows mysql-row-seek
mysql-row-tell mysql-stmt-execute
mysql-stmt-result-metadata mysql-store-result
mysql-use-result query-results null-mysql-store-result
See c-api-threaded-clients

See c-api-function-overview libmysqld
mysql-thread-end c-api-threaded-clients

See c-api-auto-reconnect c-api-function-overview
mysql-ping mysql-thread-id

See c-api-function-overview libmysqld my-init
mysql-thread-end mysql-thread-init
c-api-threaded-clients

See c-api-function-overview

See c-api-data-structures c-api-function-overview
commands-out-of-sync mysql mysql-data-seek
mysql-eof mysql-fetch-row mysql-free-result
mysql-next-result mysql-num-fields mysql-num-rows
See mysql-row-seek mysql-row-tell mysql-stmt-execute
See mysql-store-result mysql-use-result
out-of-memory query-results c-api-threaded-clients

See c-api-function-overview mysql-next-result
show-warnings error-types

A | B | C | D | E | G | H | I | J | K | L | M | N | O | P | R | S | T |
U | V | W | Y | Z

[index top]

See delete

See mysql-cluster-install-linux-binary binary-installation

See using-stack-trace

See mysql-cluster-install-linux-binary binary-installation

See mysql-cluster-security-networking-issues

See linux-installation-native linux-installation-debian
See innodb-memcached-security

[index top]

See password-security-user osx-installation-notes
invoking-programs replication-options-slave
setting-environment-variables manual-conventions

See mysql-nutshell

See contributors compilation-problems
source-installation

[index top]

See using-stack-trace

See innodb-parameters mysql-command-options

See resetting-permissions-windows

See mysql-cluster-install-linux-binary
linux-installation-native mysql-server

See c-api-building-clients

See adding-character-set c-api-building-clients-pkg-config
See building-with-encrypted-connection-support
mysql-cluster-install-linux-source
cannot-initialize-character-set
mysql-cluster-install-windows-source
compiling-plugin-libraries charset-applications
compilation-problems problems-with-mysql-sock
innodb-parameters source-installation
installing-development-tree installing-source-distribution
See keyring-system-variables using-systemd
mysql-cluster environment-variables
mysql-cluster-mysqld plugin-services
source-configuration-options
performance-schema-build-configuration libmysqld-restrictions
See multiple-unix-servers load-data-local
charset-server server-options server-system-variables
See archive-storage-engine blackhole-storage-engine
example-storage-engine federated-storage-engine
features dba-dtrace-server udf-compiling
option-files test-protocol-trace-plugin
using-own-protocol-trace-plugins mysql-nutshell
crashing

See installing-source-distribution
source-configuration-options innodb-memcached-security
udf-compiling

See resetting-permissions-windows

See innochecksum invoking-programs
manual-conventions

See invoking-programs manual-conventions

See comp-err programs-overview

See bug-reports mysql-cluster-program-options-common
manual-conventions

See mysql-shell-tutorial-javascript-shell
mysql-shell-tutorial-python-shell

See replication-howto-rawdata

See solaris-installation server-options

See replication-howto-additionalslaves
replication-solutions-backups-rawdata backup-types
replication-howto-rawdata

See can-not-connect-to-server check-table
myisam-start log-file-maintenance
myisam-maintenance-schedule batch-mode

See invoking-programs setting-environment-variables
manual-conventions

See source-configuration-options

[index top]

See innodb-memcached-porting-memcached
innodb-memcached-intro

See mysqld-safe

See what-is-crashing

See osx-installation-notes

See linux-installation-rpm linux-installation-yum-repo
mysql-cluster-install-linux-rpm replace-third-party-yum
updating-direct-rpms updating-yum-repo

See linux-installation-yum-repo replace-third-party-yum

See linux-installation-yum-repo replace-third-party-yum

See replace-third-party-yum

See docker-mysql-getting-started

See docker-mysql-more-topics

See docker-mysql-more-topics

See docker-mysql-getting-started

See docker-mysql-getting-started

See docker-mysql-getting-started

See docker-mysql-getting-started docker-mysql-more-topics

See docker-mysql-getting-started

See linux-installation-debian

See replication-howto-rawdata

[index top]

See mysql-shell-visual-studio

[index top]

See c-api-building-clients libmysqld-compiling
perl-support-problems tools-used-to-create-mysql
udf-compiling

See compiling-for-debugging using-gdb-on-mysqld
tools-used-to-create-mysql crashing

See installing-development-tree

See installing-development-tree

See source-installation freebsd-installation
installing-source-distribution

See checking-gpg-signature

See source-installation binary-installation

See ipv6-brokers

See checking-gpg-signature

See mysqldumpslow pattern-matching

See mysql-cluster-install-linux-binary solaris-installation
See binary-installation

See source-installation solaris-installation
binary-installation

See audit-log-logging-control binary-installation
installing-source-distribution

See audit-log-logging-control mysql-cluster-ndbd-definition
See bug-reports osx-installation

[index top]

See mysql-shell-tutorial-javascript-shell
mysql-shell-tutorial-python-shell

See mysql-server-side-help

See can-not-connect-to-server

[index top]

See compiler-characteristics porting

See ipv6-system-support

See check-table innochecksum glossary
programs-overview mysql-nutshell

See alter-table

See group-replication-frequently-asked-questions
mysql-cluster-security-networking-issues

[index top]

See keyring-okv-plugin

[index top]

See can-not-connect-to-server mysql-cluster-ndbd-definition
See mysql-cluster-programs-ndbd
mysql-cluster-rolling-restart

See invoking-programs setting-environment-variables

See mysql-cluster-ndbd-definition

[index top]

See udf-compiling

See c-api-building-clients

See mysql-commands mysql-command-options

See symbolic-links-to-tables

See mysqld-safe

See temporary-files

See source-configuration-options mysqlpump

See lz4-decompress source-configuration-options
mysqlpump programs-overview zlib-decompress

[index top]

See source-installation

See compiling-plugin-libraries compilation-problems
source-installation freebsd-installation
installing-source-distribution perl-support-problems

See mysql-cluster-install-linux-source

See mysql-cluster-install-linux-source
compiling-plugin-libraries source-configuration-options

See installing-source-distribution
source-configuration-options

See installing-development-tree perl-installation
mysql-test-suite

See compilation-problems

See verifying-md5-checksum

See verifying-md5-checksum

See verifying-md5-checksum

See innodb-memcached-porting-memcached
innodb-memcached-porting-mysql innodb-memcached-dml
innodb-memcached-benefits innodb-memcached-txn
innodb-memcached-intro innodb-memcached
innodb-memcached-internals innodb-parameters glossary
See source-configuration-options mysql-cluster-basics
innodb-memcached-ddl innodb-memcached-security
innodb-memcached-setup innodb-memcached-replication
innodb-memcached-troubleshoot innodb-memcached-tuning
innodb-memcached-developing

See innodb-memcached-intro

See innodb-memcached-intro

See innodb-memcached-intro

See innodb-memcached-intro

See innodb-memcached-intro

See innodb-memcached-tuning

See mysql-cluster-install-windows-binary
mysql-cluster-installation

See create-database

See windows-symbolic-links mysql-nutshell

See mysql-commands mysql-command-options

See mysql-nutshell

See error-log-rotation log-file-maintenance
query-log

See my-print-defaults programs-development
mysql-plugin programs-overview

See fulltext-search myisam-ftdump programs-overview

See analyze-table optimizing-myisam-bulk-data-loading
charset-configuration check-table compressed-format
See corrupted-myisam-tables backup-methods
debugging-server delete dynamic-format
explain-output external-locking fulltext-fine-tuning
See myisam-check myisam-repair bug-reports
index-statistics table-size-limit load-index
partitioning-maintenance reproducible-test-case
myisam-start myisam-table-maintenance
myisam-optimization myisam-table-formats
myisamchk-check-options myisamchk-general-options
myisamchk-memory myisamchk-repair-options myisamchk
See myisampack myisamchk-table-info
optimizing-queries-myisam repair-table-optimization
myisamchk-other-options programs-overview
myisam-table-close repair-table
partitioning-limitations server-options
myisam-maintenance-schedule show-index
show-table-status static-format system-optimization
See features myisam-storage-engine
myisam-crash-recovery using-log-files
symbolic-links-to-tables crashing

See myisam-repair

See myisam-check

See myisamlog programs-overview

See optimizing-myisam-bulk-data-loading compressed-format
See create-table external-locking table-size-limit
See merge-table-advantages myisam-table-formats
myisamchk-repair-options myisampack
myisamchk-table-info data-size programs-overview
partitioning-limitations silent-column-changes
merge-storage-engine myisam-storage-engine

See ansi-diff-comments mysql-cluster-online-add-node-basics
See mysql-cluster-online-add-node-example
mysql-cluster-online-add-node-remarks adding-users
alter-table-partition-operations backup-types
docker-mysql-getting-started begin-end
c-api-auto-reconnect upgrading-from-previous-series
cleartext-pluggable-authentication option-file-options
mysql-cluster-mgm-client-commands comments
mysql-cluster-configuration charset-applications
using-encrypted-connections innodb-statistics-estimation
connecting-disconnecting connecting
ipv6-remote-connections ipv6-local-connections
charset-connection contributors
converting-tables-to-innodb copying-databases
create-procedure creating-database
mysql-installation-windows-path debugging-client
mysql-cluster-api-definition stored-programs-defining
mysql-reconnect mysql-cluster-privilege-distribution
downgrading innodb-enabling-monitors
password-security-user entering-queries
mysql-cluster-logs-event-buffer events-configuration
backup-strategy-example c-api-example-programs
examples partitioning-management-exchange
mysql-batch-commands functions json-search-functions
See osx-installation-notes get-diagnostics grant
See help what-is-crashing innodb-deadlocks-handling
See bug-reports changing-mysql-user ignoring-user
See information-functions
mysql-cluster-install-windows-initial-start innodb-recovery
See mysql-input-editing mysql-cluster-install-linux-rpm
See mysql-cluster-install-windows-binary
mysql-shell-interactive-code-execution invoking-programs
mysql-cluster-limitations-exclusive-to-cluster
ldap-pluggable-authentication limit-optimization
load-data load-xml mysqldump-copying-database
security-against-attack mysql-cluster-management
select-benchmarking docker-mysql-more-topics faqs-cjk
See faqs-mysql-cluster mysql-commands glossary
mysql-installer-setup mysql-logging mysql-cluster
See mysql-command-options environment-variables
time-zone-support mysql-cluster-mysqld
mysql-server-side-help mysql-shell mysql-tips
upgrading-strategies mysql mysql-server
mysql-config-editor mysql-errno mysql-install-db
mysql-sqlstate mysql-tzinfo-to-sql mysql-upgrade
mysqlbinlog mysqldump mysqlpump mysqlsh
mysqlshow mysql-cluster-ndb-api-statistics
mysql-cluster-replication-backups
mysql-cluster-disk-data-objects
mysql-cluster-install-example-data mysql-cluster-replication
See mysql-cluster-replication-schema
mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-index-stat
mysql-cluster-programs-ndb-mgm mysql-cluster-ndbinfo
mysql-cluster-programs-ndbinfo-select-all optimizer-hints
See option-defaults-equals out-of-memory
programs-overview packet-too-large
pam-pluggable-authentication expired-password-handling
password-hashing pluggable-authentication
point-in-time-recovery sql-syntax-prepared-statements
mysql-cluster-replication-preparation option-modifiers
partitioning-columns-range rebuilding-tables
reloading-delimited-text-dumps reloading-sql-format-dumps
See replication-features-server-side-help
resetting-permissions-generic ndb-restore-to-more-nodes
pluggable-authentication-restrictions revoke
default-privileges load-data-local select-into
server-options error-messages-server
server-system-variables server-side-help-support
document-store-setting-up sha256-pluggable-authentication
See show-slave-status show-warnings signal
socket-pluggable-authentication program-options
windows-start-service mysql-cluster-replication-starting
string-literals testing-server blob
sys-diagnostics mysql-cluster-ndbinfo-memory-per-fragment
See mysql-cluster-ndbinfo-transporters trigger-syntax
innodb-troubleshooting-datadict problems-connecting
tutorial manual-conventions windows-unicode-support
See updating-direct-rpms recovery-from-backups
replication-gtids-failover firewall-usage batch-mode
See mysqlbinlog-backup using-mysqldump option-files
See command-line-options program-variables
using-log-files mysql-cluster-disk-data-symlinks
safe-updates test-protocol-trace-plugin
using-own-protocol-trace-plugins mysql-nutshell
mysql-cluster-what-is-new-7-5 mysql-cluster-what-is-new-7-6
See windows-postinstallation xml-functions

See upgrading-from-previous-series

See compiling-for-debugging

See freebsd-installation

See mysql-config-editor mysql-test-suite
option-files

See mysql-test-suite

See mysql-cluster-install-windows-initial-start
mysql-cluster-install-windows-binary windows-unicode-support

See linux-installation mysql-cluster-install-linux-rpm
security-against-attack mysql-server mysqldumpslow
See programs-overview server-options automatic-start
See timezone-problems

See mysql-server

See mysql-nutshell

See c-api-building-clients c-api-building-clients-pkg-config
See libmysqld-compiling compilation-problems
c-api-implementations mysql-config programs-overview
See plugin-api-components mysql-nutshell

See option-file-options password-security-user
my-print-defaults myisamchk-general-options
mysql-command-options environment-variables
mysql-config-editor mysql-install-db
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlshow mysqlslap
See programs-overview option-files

See mysql-nutshell

See mysql-nutshell

See mysql-nutshell

See upgrading-from-previous-series downgrading
data-directory-initialization-mysql-install-db
mysql-cluster-install-linux-binary
source-configuration-options sys-schema
mysql-install-db mysql-cluster-replication-schema
programs-overview mysql-install-db-problems
server-options sql-mode server-system-variables
mysql-nutshell

See mysql-plugin programs-overview mysql-nutshell

See data-directory-initialization-mysql-install-db
data-directory-initialization-mysqld linux-installation-native
See linux-installation-debian solaris-installation-pkg
mysql-install-db mysql-secure-installation
programs-overview default-privileges

See mysql-config

See contributors mysql-nutshell

See c-api-encrypted-connections encrypted-connection-options
See using-encrypted-connections
creating-rsa-files-using-openssl
creating-ssl-rsa-files-using-mysql
creating-ssl-files-using-openssl data-directory-initialization
See data-directory-initialization-mysqld mysql-ssl-rsa-setup
See programs-overview encrypted-connections
mysql-nutshell

See server-status-variables

See server-status-variables

See time-zone-support mysql-tzinfo-to-sql
programs-overview

See alter-database alter-table
downgrading-to-previous-series upgrading-from-previous-series
See check-table create-function-udf downgrading
See grant-tables ignoring-user
data-directory-initialization group-replication-launching
See account-upgrades sys-schema upgrading-strategies
See mysql-install-db mysql-upgrade mysqlcheck
mysql-cluster-replication-schema programs-overview
password-hashing performance-schema-build-configuration
rebuilding-tables replace-third-party-yum
replication-features-server-side-help
replication-gtids-restrictions server-options
error-messages-server document-store-setting-up
problems-connecting replication-upgrade
mysql-cluster-upgrade-downgrade windows-upgrading
updating-direct-rpms updating-yum-repo account-locking
See mysql-nutshell mysql-cluster-what-is-new-7-5
migrating-to-year4

See mysql-nutshell

See mysql-nutshell

See contributors mysql-nutshell

See assigning-passwords
replication-solutions-backups-mysqldump
can-not-connect-to-server cleartext-pluggable-authentication
See server-configuration connecting
charset-connection contributors create-database
mysql-installation-windows-path debugging-server
drop-database c-api-example-programs flush
osx-installation-notes what-is-crashing myisam-repair
See bug-reports mysql-cluster-install-linux-rpm
faqs-cjk mysql-installer-setup server-logs
mysql-config-editor mysql-install-db mysqladmin
mysqld-multi programs-overview
performance-schema-connection-attribute-tables
pluggable-authentication privileges-provided
pluggable-authentication-restrictions multiple-unix-servers
See default-privileges replication-gtids-howto
windows-start-service windows-start-command-line
testing-server features server-shutdown
windows-upgrading option-files command-line-options
See crashing

See debugging-server events-status-info grant
privileges-provided

See show-status

See host-cache blocked-host server-system-variables
See problems-connecting

See backup-strategy-summary error-log-rotation
backup-policy mysqladmin log-file-maintenance
binary-log slave-logs-relaylog

See copying-databases grant-tables mysqladmin
server-options problems-connecting privilege-changes

See optimizing-myisam-bulk-data-loading external-locking
See table-cache memory-use myisampack
myisam-crash-recovery

See adding-users

See full-disk kill miscellaneous-functions
gone-away privileges-provided

See mysqladmin

See adding-users thread-information kill
security-against-attack mysql-threads
mysql-list-processes privileges-provided
show-processlist

See debugging-server

See adding-users table-cache log-file-maintenance

See adding-users grant-tables bug-reports
server-options user-resources privilege-changes

See bug-reports

See request-access mysql-cluster-online-add-node-example
See making-trace-files grant myisam-repair
changing-mysql-user osx-installation-pkg
reproducible-test-case faqs-mysql-cluster mysql-server
See mysqladmin mysql-cluster-programs-ndb-import
privileges-provided replication-features-temptables
mysql-cluster-install-shutdown-restart shutdown
windows-start-service server-shutdown crashing

See table-cache mysql-stat mysqladmin

See gone-away show-variables

See bug-reports

See compiling-for-debugging

See can-not-connect-to-server bug-reports gone-away
See testing-server crashing

See mysqlcheck

See backup-types replication-howto-rawdata
innodb-backup glossary mysqldump

See replication-sbr-rbr binlog bit-functions
dba-dtrace-ref-command replication-gtids-concepts
replication-bugs innodb-recovery bugs
miscellaneous-functions glossary mysql-command-options
See mysql-cluster-program-options-mysqld mysqlbinlog-hexdump
See mysqlbinlog-row-events mysqlbinlog
programs-overview
performance-schema-connection-attribute-tables
point-in-time-recovery point-in-time-recovery-positions
point-in-time-recovery-times mysql-cluster-replication-pitr
See replication-features-load-data
replication-features-variables server-system-variables
show-binlog-events show-relaylog-events
mysqlbinlog-server-id start-slave binary-log
query-log slave-logs-relaylog replication-rbr-usage
See recovery-from-backups replication-gtids-failover
mysqlbinlog-backup mysql-nutshell

See reproducible-test-case

See bugs

See mysql-nutshell

See alter-database cleartext-pluggable-authentication
charset-connection partitioning-maintenance
identifier-mapping my-print-defaults
myisam-table-maintenance mysql-upgrade mysqlcheck
See programs-overview rebuilding-tables
partitioning-limitations server-system-variables
features myisam-storage-engine mysql-nutshell

See adding-udf adding-functions table-scan-avoidance
See docker-mysql-getting-started binary-log-formats
replication-options-binary-log
building-with-encrypted-connection-support
mysql-cluster-install-linux-source can-not-connect-to-server
See cannot-create cannot-initialize-character-set
change-replication-filter downgrading-to-previous-series
upgrading-from-previous-series
mysql-cluster-mgm-client-commands comments
communication-errors comp-err compiling-for-debugging
See mysql-cluster-configuration
replication-multi-source-configuration server-configuration
See innodb-memcached-txn corrupted-myisam-tables
create-function-udf create-table making-trace-files
See innodb-deadlocks debugging-server porting
using-gdb-on-mysqld mysql-cluster-ndbd-definition
mysql-cluster-api-definition innodb-doublewrite-buffer
downgrading innodb-file-format-enabling
innodb-enabling-monitors error-log-rotation
error-log-format error-log-unix error-log-windows
See error-log-syslog mysql-cluster-logs-event-buffer
external-locking not-enough-file-handles
fulltext-fine-tuning forcing-innodb-recovery
group-replication-frequently-asked-questions
mysql-cluster-replication-general general-thread-states
blocked-host table-cache memory-use
what-is-crashing myisam-repair bug-reports
changing-mysql-user identifier-case-sensitivity
ignoring-user mysql-cluster-replication-failover
information-functions mysql-cluster-install-configuration
See mysql-cluster-install-first-start
data-directory-initialization-mysqld innodb-backup
innodb-disk-io innodb-multiple-tablespaces
innodb-memcached-intro innodb-recovery
innodb-init-startup-configuration innodb-parameters
innodb-troubleshooting insert-on-duplicate insert
See mysql-cluster-install-linux
mysql-cluster-install-linux-binary linux-installation-rpm
See osx-installation-pkg solaris-installation
binary-installation mysql-cluster-install-linux-rpm
mysql-cluster-install-windows-binary
mysql-cluster-install-windows-service
mysql-innodb-cluster-introduction
mysql-cluster-limitations-exclusive-to-cluster kill
mysql-cluster-replication-issues load-data
reproducible-test-case security-against-attack
mysql-cluster-management using-systemd
keyring-key-migration miscellaneous-functions
binary-log-mixed innodb-migration myisam-start
myisamchk-check-options myisamchk-general-options
myisamchk myisampack faqs-general faqs-cjk
See faqs-mysql-cluster faqs-sql-modes glossary
windows-installation-layout mysql-cluster
environment-variables server-administration
programs-server gone-away server-logs
mysql-cluster-program-options-mysqld time-zone-support
mysql-cluster-mysqld mysql-cluster-compared
source-configuration-options compatibility sys-schema
See upgrading-strategies mysql-server
mysql-affected-rows mysql-install-db mysql-options
See mysql-plugin mysqlbinlog mysqlcheck
mysqld mysqld-multi mysqld-safe mysqldump
See mysql-cluster-ndb-api-statistics
mysql-cluster-security-mysql-security-procedures
mysql-cluster-install-auto-requirements
mysql-cluster-config-example mysql-cluster-basics
mysql-cluster-installation mysql-cluster-option-tables
mysql-cluster-nodes-groups mysql-cluster-overview
mysql-cluster-programs mysql-cluster-replication
mysql-cluster-replication-conflict-resolution
mysql-cluster-replication-schema
mysql-cluster-replication-multi-master
mysql-cluster-status-variables mysql-cluster-system-variables
See mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndb-top mysql-cluster-ndbinfo
mysql-cluster-limitations-syntax optimize-table
optimizer-issues mysql-cluster-program-options-common
libmysqld-options programs-overview
mysql-cluster-configuration-overview packet-too-large
performance-schema-startup-configuration
mysql-cluster-rolling-restart
mysql-cluster-replication-preparation myisam-table-close
mysql-install-db-problems file-permissions
option-modifiers query-cache-configuration
mysql-cluster-config-starting repair-table
replication-options-reference replication-options
replication-features-transaction-inconsistencies
replication-options-master slave-logs reset-slave
See resetting-permissions-unix resetting-permissions-windows
See resolve-stack-dump ndb-restore-to-more-nodes
nontransactional-tables multiple-servers
default-privileges load-data-local security-options
See select-into windows-select-server charset-server
See server-options log-file-maintenance
plugin-status-system-variables server-signal-response
server-status-variables server-system-variables
set-transaction error-message-language
myisam-maintenance-schedule replication-gtids-howto
innodb-memcached-setup show-engine
c-api-multiple-installations start-slave
automatic-start multiple-windows-services
multiple-windows-command-line-servers windows-start-service
See windows-start-command-line
mysql-cluster-replication-starting channels-startup-options
See time-zone-upgrades supporters
replication-solutions-switch table-locking
table-corruption windows-testing testing-server
binary-log blackhole-storage-engine dbug-package
ddl-log error-log query-log
innodb-memcached-replication myisam-storage-engine
query-cache mysqld-server mysql-test-suite
mysql-cluster-ndbinfo-operations-per-fragment
mysql-cluster-ndbinfo-server-locks slow-query-log
timezone-problems too-many-connections
dba-dtrace-server windows-troubleshooting
error-creating-innodb problems-connecting
starting-server-troubleshooting manual-conventions
udf-compiling udf-security
mysql-cluster-upgrade-downgrade windows-upgrading
updating-direct-rpms using-stack-trace
myisam-crash-recovery option-files using-log-files
See symbolic-links-to-tables
mysql-cluster-install-auto-using
mysql-cluster-replication-two-channels making-windows-dumps
See mysql-nutshell mysql-cluster-what-is-new-7-5
crashing privilege-changes temporary-files
which-version writing-plugins

See making-trace-files

See making-trace-files binary-installation mysqld
See mysqld-safe windows-select-server

See mysql-cluster-install-windows-initial-start
mysql-cluster-install-windows-binary
mysql-cluster-install-windows-service

See using-systemd mysqld-multi programs-overview
See multiple-unix-servers

See using-systemd

See mysql-cluster-online-add-node-example
downgrading-to-previous-series upgrading-from-previous-series
See compiling-for-debugging server-configuration
downgrading large-page-support error-log-unix
error-log-syslog not-enough-file-handles
problems-with-mysql-sock
data-directory-initialization-mysql-install-db
innodb-troubleshooting mysql-cluster-install-linux-rpm
security-against-attack using-systemd
faqs-mysql-cluster time-zone-support
source-configuration-options upgrading-strategies
mysql-server mysql-install-db mysqld-multi
mysqld-safe mysql-cluster-security-mysql-security-procedures
See option-defaults-equals programs-overview
packet-too-large file-permissions multiple-servers
See multiple-unix-servers server-options
server-system-variables automatic-start
starting-server testing-server error-log
timezone-problems starting-server-troubleshooting
option-files mysql-nutshell

See replication-solutions-backups-read-only
replication-solutions-backups-mysqldump backup-and-recovery
See backup-types backup-strategy-summary
optimizing-innodb-bulk-data-loading
upgrading-from-previous-series replication-snapshot-method
See cleartext-pluggable-authentication connecting
contributors charset-unicode-conversion
mysqldump-copying-to-other-server tablespace-copying
copying-databases create-table
replication-howto-mysqldump using-innodb-tables
mysql-installation-windows-path backup-methods
innodb-file-defragmenting mysql-cluster-privilege-distribution
See downgrading mysqldump-delimited-text
mysqldump-sql-format mysqldump-stored-programs
mysqldump-definition-data-dumps tablespace-enabling
backup-policy backup-strategy-example bug-reports
See identifier-case-sensitivity innochecksum
innodb-backup uln-installation
mysql-cluster-install-linux-rpm load-data load-xml
See mysqldump-copying-database identifier-mapping
innodb-migration faqs-mysql-cluster
mysql-command-options server-logs upgrading-strategies
See mysql-config-editor mysqldump-tips mysqldump
See mysql-cluster-install-example-data
mysql-cluster-overview mysql-cluster-ndbinfo
replication-howto-masterstatus mysql-cluster-backup
programs-overview
performance-schema-connection-attribute-tables
mysql-cluster-rolling-restart mysql-cluster-replication-pitr
See mysql-cluster-replication-preparation
problems-with-float rebuilding-tables
reloading-delimited-text-dumps reloading-sql-format-dumps
See replication-solutions-partitioning
replication-features-transaction-inconsistencies
innodb-resize-system-tablespace ndb-restore-to-more-nodes
See performance-schema-restrictions
replication-gtids-restrictions view-restrictions
log-destinations log-file-maintenance sql-mode
server-system-variables replication-howto-existingdata
no-matching-rows program-options windows-start-service
See blob innodb-buffer-pool
innodb-memcached-replication features
problems-connecting uninstall-plugin
replication-upgrade create-table-foreign-keys
replication-gtids-failover mysqlbinlog-backup
using-mysqldump option-files
replication-solutions-backups
replication-solutions-diffengines sys-schema-usage
mysql-nutshell xml-functions migrating-to-year4

See problems-connecting

See mysqldumpslow programs-overview slow-query-log

See replication-solutions-switch

See contributors mysql-nutshell

See backup-types charset-connection
copying-databases backup-methods downgrading
load-data mysqlimport programs-overview
reloading-delimited-text-dumps load-data-local
mysql-cluster-what-is-new-7-6

See MySQLInstallerConsole

See mysqlcheck

See lz4-decompress faqs-tablespace-encryption
mysqlpump programs-overview sys-schema-usage
zlib-decompress

See mysqlcheck

See mysql-innodb-cluster-limitations
mysql-shell-tutorial-javascript-shell
mysql-shell-tutorial-python-shell mysqlsh
programs-overview

See cleartext-pluggable-authentication connecting
charset-connection c-api-example-programs mysqlshow
See programs-overview show-databases show-index
See show-table-status windows-testing testing-server
See windows-postinstallation

See show-tables

See show-columns

See cleartext-pluggable-authentication
monitor-innodb-mutex-waits-performance-schema mysqlslap
programs-overview custom-benchmarks

See mysql-cluster-install-linux-rpm
sha256-pluggable-authentication mysql-test-suite
mysql-nutshell

See mysql-nutshell

[index top]

See mysql-cluster-ndbd-definition

See mysql-cluster-sci-definition

See mysql-cluster-programs-ndb-blob-tool

See mysql-cluster-install-linux-rpm mysql-cluster-programs
See mysql-cluster-programs-ndb-config
mysql-cluster-sci-definition mysql-cluster-what-is-new-7-6

See mysql-cluster-programs-ndb-cpcd

See mysql-cluster-programs-ndb-delete-all

See mysql-cluster-online-add-node-example
mysql-cluster-ndbd-definition mysql-cluster-install-linux-rpm
See partitioning-key mysql-cluster-program-options-mysqld
See mysql-cluster-security-mysql-security-procedures
mysql-cluster-disk-data-objects
mysql-cluster-programs-ndb-desc
create-table-ndb-table-comment-options files-table
mysql-cluster-ndbinfo-cluster-operations
mysql-cluster-ndbinfo-server-operations

See mysql-cluster-programs-ndb-drop-index

See mysql-cluster-programs-ndb-drop-index
mysql-cluster-programs-ndb-drop-table

See mysql-cluster-programs-ndb-error-reporter

See mysql-cluster-programs-ndb-import
mysql-cluster-what-is-new-7-6

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-online-add-node-example
mysql-cluster-online-add-node-remarks
mysql-cluster-install-linux-source
mysql-cluster-mgm-client-commands
mysql-cluster-ndbd-definition
mysql-cluster-privilege-distribution
mysql-cluster-install-first-start
mysql-cluster-install-windows-initial-start
mysql-cluster-install-linux mysql-cluster-install-linux-binary
See mysql-cluster-install-linux-rpm
mysql-cluster-install-debian faqs-mysql-cluster
mysql-cluster mysql-cluster-program-options-mysqld
mysql-cluster-basics mysql-cluster-logging-management-commands
See mysql-cluster-programs
mysql-cluster-security-networking-issues
mysql-cluster-single-user-mode mysql-cluster-programs-ndb-mgm
See mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-restore mysql-cluster-backup
mysql-cluster-program-options-common
mysql-cluster-rolling-restart mysql-cluster-replication-pitr
See ndb-restore-to-more-nodes
mysql-cluster-install-shutdown-restart
mysql-cluster-ndbinfo-arbitrator-validity-detail
mysql-cluster-ndbinfo-membership
mysql-cluster-ndbinfo-memoryusage mysql-cluster-ndbinfo-nodes
See mysql-cluster-ndbinfo-transporters
mysql-cluster-backup-using-management-client
mysql-cluster-what-is-new-7-5

See mysql-cluster-install-windows-initial-start
mysql-cluster-install-windows-binary

See mysql-cluster-install-linux-source
mysql-cluster-mgm-client-commands mysql-cluster-mgm-definition
See mysql-cluster-ndbd-definition
mysql-cluster-install-first-start
mysql-cluster-install-windows-initial-start
mysql-cluster-install-linux mysql-cluster-install-linux-binary
See mysql-cluster-install-linux-rpm
mysql-cluster-install-windows-binary
mysql-cluster-install-debian faqs-mysql-cluster
mysql-cluster-program-options-mysqld
source-configuration-options mysql-cluster-config-example
See mysql-cluster-connection-strings mysql-cluster-basics
See mysql-cluster-logging-management-commands
mysql-cluster-nodes-groups mysql-cluster-programs
mysql-cluster-programs-ndb-mgmd mysql-cluster-programs-ndbd
See mysql-cluster-rolling-restart mysql-cluster-quick
mysql-cluster-install-shutdown-restart
mysql-cluster-start-phases mysql-cluster-install-auto-using
See mysql-cluster-what-is-new-7-6

See mysql-cluster-install-windows-initial-start
mysql-cluster-install-windows-binary
mysql-cluster-install-windows-service

See mysql-cluster-programs-ndb-move-data

See mysql-cluster-programs-ndb-perror perror
mysql-cluster-ndbinfo-error-messages
mysql-cluster-what-is-new-7-6

See mysql-cluster-programs-ndb-print-backup-file
mysql-cluster-programs-ndb-print-frag-file
mysql-cluster-programs-ndb-print-schema-file
mysql-cluster-programs-ndb-print-sys-file
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-program-options-common

See mysql-cluster-programs-ndb-print-file

See mysql-cluster-programs-ndb-print-frag-file

See mysql-cluster-programs-ndb-print-backup-file
mysql-cluster-programs-ndb-print-file
mysql-cluster-programs-ndb-print-frag-file
mysql-cluster-programs-ndb-print-schema-file
mysql-cluster-programs-ndb-print-sys-file
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-program-options-common

See mysql-cluster-programs-ndb-print-backup-file
mysql-cluster-programs-ndb-print-file
mysql-cluster-programs-ndb-print-frag-file
mysql-cluster-programs-ndb-print-schema-file
mysql-cluster-programs-ndb-print-sys-file
mysql-cluster-program-options-common

See mysql-cluster-programs-ndb-redo-log-reader

See backup-types mysql-cluster-ndbd-definition
mysql-cluster-privilege-distribution faqs-mysql-cluster
mysql-cluster-replication-backups mysql-cluster-basics
mysql-cluster-overview mysql-cluster-programs
mysql-cluster-replication-schema
mysql-cluster-replication-multi-master
mysql-cluster-single-user-mode
mysql-cluster-programs-ndb-restore mysql-cluster-backup
mysql-cluster-rolling-restart mysql-cluster-replication-pitr
See ndb-restore-to-fewer-nodes ndb-restore-to-more-nodes
See mysql-cluster-what-is-new-7-5
mysql-cluster-what-is-new-7-6

See mysql-cluster-security-mysql-security-procedures
mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-show-tables

See mysql-cluster-programs-ndb-select-count

See mysql-cluster-install-auto-overview
mysql-cluster-install-auto-requirements mysql-cluster-programs
See mysql-cluster-programs-ndb-setup-py
mysql-cluster-install-auto-using

See mysql-cluster-program-options-mysqld
mysql-cluster-security-mysql-security-procedures
mysql-cluster-programs mysql-cluster-replication-schema
mysql-cluster-programs-ndb-show-tables
mysql-cluster-ndbinfo-cluster-locks
mysql-cluster-ndbinfo-cluster-operations
mysql-cluster-ndbinfo-locks-per-fragment
mysql-cluster-ndbinfo-operations-per-fragment
mysql-cluster-ndbinfo-server-locks
mysql-cluster-ndbinfo-server-operations

See storage-requirements faqs-mysql-cluster
mysql-cluster-program-options-mysqld
mysql-cluster-programs-ndb-size-pl

See mysql-cluster-programs-ndb-top
mysql-cluster-what-is-new-7-6

See mysql-cluster-programs-ndb-waiter

See mysql-cluster-online-add-node-basics
mysql-cluster-online-add-node-example
mysql-cluster-install-linux-source
mysql-cluster-mgm-client-commands
mysql-cluster-ndbd-definition
mysql-cluster-install-first-start mysql-cluster-install-linux
See mysql-cluster-install-linux-binary
mysql-cluster-install-linux-rpm
mysql-cluster-install-windows-binary
mysql-cluster-install-debian mysql-cluster-management
faqs-mysql-cluster mysql-cluster-program-options-mysqld
mysql-cluster-replication-backups mysql-cluster-config-example
See mysql-cluster-basics mysql-cluster-params-ndbd
mysql-cluster-installation mysql-cluster-nodes-groups
mysql-cluster-programs mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-waiter mysql-cluster-programs-ndbd
See mysql-cluster-programs-ndbmtd
mysql-cluster-configuration-overview
mysql-cluster-rolling-restart mysql-cluster-replication-pitr
See mysql-cluster-quick mysql-cluster-config-starting
mysql-cluster-install-shutdown-restart
mysql-cluster-sci-definition mysql-cluster-start-phases
mysql-cluster-ndbinfo-nodes mysql-cluster-log-statistics
mysql-cluster-interconnects mysql-cluster-install-auto-using

See mysql-cluster-install-windows-initial-start
mysql-cluster-install-windows-binary
mysql-cluster-install-windows-service

See mysql-cluster-programs-ndb-redo-log-reader

See mysql-cluster-programs-ndbinfo-select-all

See mysql-cluster-online-add-node-basics
mysql-cluster-online-add-node-example
mysql-cluster-install-linux-source
mysql-cluster-ndbd-definition mysql-cluster-install-linux
See mysql-cluster-install-linux-binary
mysql-cluster-install-linux-rpm faqs-mysql-cluster
source-configuration-options mysql-cluster-basics
mysql-cluster-params-ndbd mysql-cluster-nodes-groups
mysql-cluster-programs mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-top mysql-cluster-programs-ndbd
See mysql-cluster-programs-ndbmtd
mysql-cluster-rolling-restart mysql-cluster-replication-pitr
See mysql-cluster-config-starting ndb-restore-to-fewer-nodes
See mysql-cluster-install-shutdown-restart
mysql-cluster-ndbinfo-nodes mysql-cluster-ndbinfo-resources
See mysql-cluster-install-auto-using
mysql-cluster-what-is-new-7-5 mysql-cluster-what-is-new-7-6

See mysql-cluster-install-windows-initial-start
mysql-cluster-install-windows-binary
mysql-cluster-install-windows-service

See windows-start-service

See mysql-cluster-install-windows-service
multiple-windows-services

See mysql-cluster-install-windows-service

See windows-start-service windows-troubleshooting
windows-upgrading

See mysql-cluster-install-windows-service
multiple-windows-services

See mysql-cluster-install-windows-service

See mysql-cluster-install-shutdown-restart

See windows-start-service

See resolve-stack-dump using-stack-trace

See mysql-cluster-ndbd-definition

[index top]

See audit-log-logging-control
creating-rsa-files-using-openssl creating-ssl-rsa-files
creating-ssl-rsa-files-using-mysql
creating-ssl-files-using-openssl mysql-ssl-rsa-setup
keyring-okv-plugin

See verifying-md5-checksum

See mysqlpump

See c-api-building-clients

[index top]

See threads-table

See cannot-create not-enough-file-handles
myisam-repair faqs-mysql-cluster
mysql-cluster-programs-ndb-perror programs-overview
perror error-sources
mysql-cluster-ndbinfo-error-messages
mysql-cluster-what-is-new-7-6

See binary-installation

See checking-gpg-signature

See ipv6-brokers

See c-api-building-clients c-api-building-clients-pkg-config
See environment-variables source-configuration-options
mysql-config

See solaris-installation-pkg

See solaris-installation-pkg

See perl-support

See assigning-passwords password-security-user
memory-use what-is-crashing mysqladmin
threads-table starting-server-troubleshooting

See connecting

See can-not-connect-to-server

[index top]

See error-log-rotation log-file-maintenance
query-log

See programs-overview replace-utility
replication-solutions-scaleout mysql-nutshell

See programs-overview resolve-stack-dump
using-stack-trace

See programs-overview resolveip

See linux-installation-rpm

See purge-binary-logs

See linux-installation-rpm installing-source-distribution
See checking-rpm-signature updating-direct-rpms

See source-installation linux-installation-rpm
installing-source-distribution

See replication-howto-additionalslaves backup-types
replication-howto-rawdata

[index top]

See backup-types replication-howto-rawdata

See pattern-matching

See mysql-cluster-install-example-data

See group-replication-frequently-asked-questions

See linux-installation-native linux-installation-rpm
using-systemd

See windows-installation windows-start-service

See mysql-cluster-install-windows-service
windows-start-service

See group-replication-frequently-asked-questions

See setting-environment-variables

See mysql-cluster-install-auto-using

See not-enough-file-handles invoking-programs
setting-environment-variables manual-conventions

See mysql-cluster-programs-ndb-restore mysql-cluster-quick

See faqs-mysql-cluster

See faqs-mysql-cluster

See mysqld-safe

See mysql-cluster-security-networking-issues

See linux-installation-rpm

See creating-ssl-files-using-openssl

See linux-installation-rpm

See linux-installation-rpm

See security-guidelines

See mysql-cluster-install-linux-binary

See mysql-cluster-install-linux-binary
linux-installation-rpm binary-installation
mysql-install-db

See osx-installation-prefpane

See using-systemd

[index top]

See replication-howto-additionalslaves
replication-solutions-backups-rawdata backup-types
replication-howto-rawdata database-use bug-reports
See source-installation linux-installation-rpm
osx-installation solaris-installation
solaris-installation-pkg binary-installation
installing-source-distribution mysql-cluster-install-linux-rpm
See perl-installation c-api-multiple-installations
keyring-okv-plugin which-version

See security-guidelines

See not-enough-file-handles osx-installation-notes
invoking-programs setting-environment-variables
manual-conventions

See mysql-commands

See innodb-memcached-intro security-guidelines
innodb-memcached-setup

See osx-installation

See manual-conventions

See what-is-crashing mysql-cluster-ndbinfo-processes

[index top]

See mysql-cluster-ndbd-definition large-page-support
not-enough-file-handles mysqld-safe
mysql-cluster-program-options-common packet-too-large
server-options

See mysql-cluster-install-linux-binary

See mysql-cluster-install-linux-binary solaris-installation
See binary-installation

[index top]

See mysql-cluster-install-configuration mysql-commands
pattern-matching

[index top]

See sys-statement-performance-analyzer

See making-windows-dumps

See making-windows-dumps

See verifying-md5-checksum

See replication-solutions-backups-rawdata
source-installation installing-source-distribution

See load-data

[index top]

See compilation-problems keywords

See linux-installation-native linux-installation-rpm
linux-installation-yum-repo mysql-cluster-install-linux-rpm
See replace-third-party-yum updating-direct-rpms
updating-yum-repo

See linux-installation-rpm updating-direct-rpms

See linux-installation-yum-repo replace-third-party-yum

See replace-third-party-yum

See linux-installation-yum-repo replace-third-party-yum

[index top]

See replication-howto-rawdata bug-reports

See lz4-decompress mysqlpump programs-overview
zlib-decompress

See setting-environment-variables

See linux-installation-rpm updating-direct-rpms

Symbols | A | B | C | D | E | F | G | H | I | J | L | M | N | O | P | Q
| R | S | T | U | V | W | X | Y

[index top]

See extensions-to-ansi

[index top]

See adding-functions create-function-udf
mathematical-functions partitioning-limitations-functions

See mathematical-functions

See date-and-time-functions

See secure-client-programming

See date-and-time-functions

See encryption-functions enterprise-encryption-functions
See query-cache-operation ssl-libraries
server-system-variables mysql-nutshell

See encryption-functions enterprise-encryption-functions
See query-cache-operation ssl-libraries
server-system-variables mysql-nutshell

See upgrading-from-previous-series miscellaneous-functions
See group-by-handling sql-mode

See gis-polygon-property-functions

See gis-format-conversion-functions

See help string-functions

See mathematical-functions

See gis-format-conversion-functions

See gis-format-conversion-functions

See gis-format-conversion-functions

See enterprise-encryption-functions

See enterprise-encryption-functions

See enterprise-encryption-functions

See enterprise-encryption-functions

See enterprise-encryption-functions

See mathematical-functions

See mathematical-functions

See group-by-functions date-and-time-type-overview
group-by-optimization enum features set

[index top]

See derived-tables query-cache-operation
information-functions select-benchmarking
optimizing-subqueries

See bit-value-literals string-functions

See group-by-functions bit-functions
extensions-to-ansi

See bit-functions extensions-to-ansi

See string-functions

See group-by-functions bit-functions
extensions-to-ansi

See group-by-functions bit-functions
extensions-to-ansi

See spatial-operator-functions

[index top]

See bit-functions bit-value-literals cast-functions
See string-functions-charset comparison-operators
date-and-time-type-conversion date-and-time-functions
json-creation-functions hexadecimal-literals
differences-from-ansi json type-conversion
user-variables

See mathematical-functions

See partitioning-linear-hash mathematical-functions
partitioning-limitations-functions

See gis-polygon-property-functions

See encryption-functions extensions-to-ansi
string-functions

See string-functions charset-unicode-sets

See string-functions

See string-functions-charset information-functions

See comparison-operators join

See charset-collation-coercibility information-functions

See case-sensitivity string-functions-charset
information-functions

See encryption-functions source-configuration-options
server-system-variables

See group-by-functions cast-functions
string-functions-charset charset-repertoire
charset-collation-coercibility create-function-udf
extensions-to-ansi sql-mode show-create-view
string-functions views-table type-conversion
xml-functions

See group-by-functions string-functions

See audit-log-file-formats create-table-generated-columns
See replication-rbr-safe-unsafe query-cache-operation
information-functions kill mysql-logging
show-processlist threads-table

See spatial-relation-functions-mbr

See string-functions-charset mathematical-functions
string-functions

See cast-functions charset-introducer
charset-literal comparison-operators faqs-cjk

See date-and-time-functions query-cache-operation
server-system-variables lock-tables-restrictions
query-log slow-query-log

See spatial-operator-functions

See mathematical-functions

See mathematical-functions

See group-by-functions counting-rows
create-function-udf group-by-optimization
internal-temporary-tables
mysql-cluster-limitations-transactions miscellaneous-functions
See extensions-to-ansi derived-table-optimization
partitioning-overview problems-with-null sql-mode
See features view-updatability where-optimization

See mathematical-functions

See enterprise-encryption-functions
enterprise-encryption-usage environment-variables

See enterprise-encryption-functions

See enterprise-encryption-functions
enterprise-encryption-usage environment-variables

See enterprise-encryption-functions

See spatial-relation-functions-object-shapes

See encryption-functions server-system-variables

See date-and-time-functions date-calculations
replication-rbr-safe-unsafe query-cache-operation

See create-table data-type-defaults
date-and-time-functions

See date-and-time-type-conversion date-and-time-functions
See replication-rbr-safe-unsafe query-cache-operation

See date-and-time-functions

See date-and-time-functions replication-rbr-safe-unsafe
See query-cache-operation

See timestamp-initialization create-event
create-table data-type-defaults
date-and-time-functions server-system-variables

See timestamp-initialization date-and-time-functions
replication-rbr-safe-unsafe query-cache-operation

See stored-programs-security alter-user create-event
See create-procedure create-trigger create-view
See grant-tables information-functions
binary-log-mixed replication-features-functions
replication-features-current-user show-create-user
account-names

See connection-access alter-user
audit-log-file-formats connection-control-installation
create-event create-procedure
create-table-generated-columns create-trigger
create-view query-cache-operation
writing-authentication-plugins-proxy-users
information-functions binary-log-mixed
validate-password-options-variables proxy-users
replication-features-functions
replication-features-current-user set-password
show-create-user account-names
account-activity-auditing keyring-service
keyring-udf-usage charset-metadata
writing-authentication-plugins-server-side

See date-and-time-functions replication-rbr-safe-unsafe
See query-cache-operation time-zone-support
replication-features-fractional-seconds

[index top]

See replication-options-binary-log creating-database
drop-database getting-information
query-cache-operation information-functions bugs
charset-metadata

See date-and-time-functions

See arithmetic-functions create-event
date-and-time-functions date-and-time-types
date-calculations expressions

See c-api-prepared-statement-problems cast-functions
date-and-time-functions locale-support
server-system-variables

See date-and-time-functions date-and-time-types

See date-and-time-functions
partitioning-limitations-functions

See date-and-time-functions
partitioning-limitations-functions

See date-and-time-functions locale-support
server-system-variables

See date-and-time-functions date-calculations
partitioning-limitations-functions

See date-and-time-functions
partitioning-limitations-functions

See date-and-time-functions
partitioning-limitations-functions partitioning-types

See encryption-functions extensions-to-ansi
mysql-nutshell

See alter-table-generated-columns data-type-defaults
insert miscellaneous-functions replace

See mathematical-functions

See encryption-functions flush server-options
mysql-nutshell

See encryption-functions flush privileges-provided
See server-options mysql-nutshell

See gis-general-property-functions

See spatial-relation-functions-mbr

See spatial-relation-functions-object-shapes

[index top]

See string-functions-charset bugs extensions-to-ansi
See string-functions

See encryption-functions extensions-to-ansi
mysql-nutshell

See contributors encryption-functions
query-cache-operation extensions-to-ansi
charset-restrictions server-system-variables
mysql-nutshell

See gis-linestring-property-functions

See gis-general-property-functions

See spatial-relation-functions-mbr

See create-table mathematical-functions

See string-functions

See comparison-operators

See comparison-operators

See gis-polygon-property-functions

See cast-functions date-and-time-functions
partitioning-limitations-functions

See xml-functions

[index top]

See string-functions

See string-functions set

See mathematical-functions group-by-handling
partitioning-limitations-functions

See string-functions-charset mathematical-functions
miscellaneous-functions extensions-to-ansi
locale-support string-functions

See replication-sbr-rbr replication-rbr-safe-unsafe
query-cache-operation information-functions
binary-log-mixed replication-features-functions

See string-functions

See date-and-time-functions extensions-to-ansi

See audit-log-logging-control contributors
date-and-time-functions replication-features-timezone

[index top]

See gis-wkt-functions

See gis-wkb-functions

See gis-mysql-specific-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-geometrycollection-property-functions

See gis-general-property-functions

See gis-wkt-functions

See gis-wkb-functions

See date-and-time-functions locale-support

See error-messages-server

See replication-sbr-rbr c-api-auto-reconnect
upgrading-from-previous-series create-event
replication-rbr-safe-unsafe events-overview
general-thread-states group-replication-limitations
query-cache-operation internal-locking kill
locking-service-monitoring miscellaneous-functions
mysql-change-user mysql-reset-connection
replication-features-functions lock-tables-restrictions
locking-service metadata-locks-table sys-ps-setup-save

See host-cache

See host-cache

See host-cache

See host-cache

See mysql-cluster-ndbinfo-threadstat

See mysql-cluster-ndbinfo-threadstat

See gis-linestring-property-functions

See string-functions-charset comparison-operators
json

See group-by-functions internal-temporary-tables
bugs extensions-to-ansi server-system-variables
json features

See gtid-functions replication-gtids-concepts

See gtid-functions replication-options-gtids
replication-gtids-concepts

[index top]

See bit-value-literals string-functions-charset
charset-literal keyring-udf-reference
hexadecimal-literals mathematical-functions
miscellaneous-functions faqs-cjk default-privileges
See string-functions keyring-udf-usage

See date-and-time-functions
partitioning-limitations-functions

[index top]

See string-functions-charset control-flow-functions
if innodb-information-schema-system-tables bugs
extensions-to-ansi

See control-flow-functions problems-with-null

See operator-precedence

See explain-output generated-column-index-optimizations
See range-optimization row-constructor-optimization
json type-conversion

See ipv6-support miscellaneous-functions

See ipv6-support miscellaneous-functions

See ipv6-support miscellaneous-functions

See ipv6-support miscellaneous-functions

See string-functions

See string-functions-charset string-functions

See gis-polygon-property-functions

See spatial-relation-functions-mbr

See comparison-operators

See replication-sbr-rbr replication-rbr-safe-unsafe
query-cache-operation miscellaneous-functions
replication-features-functions

See miscellaneous-functions

See miscellaneous-functions

See miscellaneous-functions

See miscellaneous-functions

See replication-sbr-rbr replication-rbr-safe-unsafe
query-cache-operation miscellaneous-functions
replication-features-functions

See gis-linestring-property-functions

See gis-general-property-functions

See comparison-operators

See gis-general-property-functions

[index top]

See json-modification-functions mysql-nutshell

See json-creation-functions json mysql-nutshell

See json-modification-functions mysql-nutshell

See json-modification-functions mysql-nutshell

See group-by-functions json-creation-functions
json-function-reference mysql-nutshell

See json-search-functions mysql-nutshell

See json-search-functions json-path-syntax
mysql-nutshell

See json-attribute-functions mysql-nutshell

See json-search-functions create-table-secondary-indexes
See json mysql-nutshell

See json-modification-functions json mysql-nutshell

See json-search-functions mysql-nutshell

See json-attribute-functions mysql-nutshell

See json-modification-functions json mysql-nutshell

See json-modification-functions mysql-nutshell

See json-modification-functions mysql-nutshell

See json-creation-functions json mysql-nutshell

See group-by-functions json-creation-functions
json-function-reference mysql-nutshell

See json-function-reference json-utility-functions
mysql-nutshell

See json-creation-functions json-utility-functions
mysql-nutshell

See json-modification-functions mysql-nutshell

See json-modification-functions json-path-syntax
json mysql-nutshell

See json-search-functions json-path-syntax
mysql-nutshell

See json-modification-functions json-path-syntax
json mysql-nutshell

See json-function-reference json-utility-functions
mysql-nutshell

See json-attribute-functions json-search-functions
json mysql-nutshell

See json-search-functions

See json-modification-functions
generated-column-index-optimizations
create-table-secondary-indexes json mysql-nutshell

See json-attribute-functions mysql-nutshell

[index top]

See date-and-time-functions

See c-api-auto-reconnect comparison-operators
create-table replication-rbr-safe-unsafe
query-cache-operation getting-unique-id
information-functions insert-on-duplicate insert
extensions-to-ansi mysql-insert-id
mysql-reset-connection mysql-stmt-insert-id
mysqlbinlog-hexdump replication-features-auto-increment
replication-features-functions server-system-variables
stored-routines-last-insert-id lock-tables-restrictions
replication-problems view-updatability
example-auto-increment

See string-functions-charset string-functions

See string-functions-charset comparison-operators
json

See string-functions

See storage-requirements string-functions
gis-data-formats

See gis-linestring-property-functions spatial-types

See gis-wkt-functions

See gis-wkb-functions

See gis-mysql-specific-functions

See gis-wkt-functions

See gis-wkb-functions

See mathematical-functions

See replication-sbr-rbr replication-rbr-safe-unsafe
enterprise-encryption-usage query-cache-operation
load-xml binary-log-mixed privileges-provided
replication-features-functions server-options
server-system-variables string-functions

See timestamp-initialization date-and-time-functions

See timestamp-initialization date-and-time-functions
replication-rbr-safe-unsafe

See timestamp-initialization date-and-time-functions

See timestamp-initialization date-and-time-functions
replication-rbr-safe-unsafe

See string-functions

See partitioning-linear-hash mathematical-functions

See mathematical-functions

See mathematical-functions

See cast-functions string-functions-charset
string-functions charset-unicode-sets
charset-collation-information-schema

See string-functions

See string-functions-charset string-functions

[index top]

See string-functions

See date-and-time-functions

See date-and-time-functions

See replication-sbr-rbr channels-commands-single-channel
See channels-with-prev-replication
replication-rbr-safe-unsafe query-cache-operation
miscellaneous-functions faqs-replication

See expressions

See fulltext-search

See fulltext-boolean fulltext-fine-tuning
fulltext-restrictions fulltext-search
innodb-fulltext-index glossary
fulltext-natural-language

See group-by-functions group-by-optimization
mysql-indexes bugs numeric-type-overview
derived-table-optimization optimizing-subqueries
sql-mode tp-thread-group-state-table json
features two-digit-years view-updatability
index-extensions example-auto-increment

See spatial-relation-functions-mbr using-spatial-indexes

See spatial-relation-functions-mbr

See spatial-relation-functions-mbr

See spatial-relation-functions-mbr

See spatial-relation-functions-mbr mysql-nutshell

See spatial-relation-functions-mbr mysql-nutshell

See spatial-relation-functions-mbr

See spatial-relation-functions-mbr

See spatial-relation-functions-mbr

See spatial-relation-functions-mbr using-spatial-indexes

See encryption-functions partitioning-key
extensions-to-ansi identifiers

See date-and-time-functions
partitioning-limitations-functions

See string-functions-charset string-functions

See group-by-functions c-api-prepared-statement-problems
See group-by-optimization mysql-indexes bugs
numeric-type-overview derived-table-optimization
optimizing-subqueries problems-with-null json
features two-digit-years view-updatability
index-extensions where-optimization

See date-and-time-functions
partitioning-limitations-functions

See gis-wkt-functions

See gis-wkb-functions

See arithmetic-functions date-calculations
mathematical-functions extensions-to-ansi
partitioning-limitations-functions sql-mode

See date-and-time-functions date-calculations
partitioning-limitations-functions partitioning-types

See date-and-time-functions locale-support
server-system-variables

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-mysql-specific-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-mysql-specific-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-mysql-specific-functions

See gis-wkt-functions

See gis-wkb-functions

See server-status-variables

[index top]

See stored-programs-logging miscellaneous-functions

See range-optimization

See replication-sbr-rbr timestamp-initialization
create-procedure create-table-generated-columns
create-table data-type-defaults
date-and-time-functions replication-rbr-safe-unsafe
fractional-seconds query-cache-operation faqs-general
See time-zone-support replication-features-functions
replication-features-timezone server-options
server-system-variables sys-metrics
sys-statement-performance-analyzer year
time-zone-leap-seconds

See control-flow-functions

See gis-geometrycollection-property-functions

See gis-polygon-property-functions

See gis-linestring-property-functions

[index top]

See string-functions

See string-functions

See upgrading-from-previous-series encryption-functions
See password-hashing validate-password plugin-types
See mysql-nutshell

See string-functions

See spatial-relation-functions-mbr

[index top]

See replication-rbr-safe-unsafe encryption-functions
query-cache-operation ignoring-user partitioning-key
See extensions-to-ansi password-hashing
validate-password-options-variables password-logging
server-system-variables set-password validate-password
See plugin-types mysql-nutshell

See date-and-time-functions extensions-to-ansi

See date-and-time-functions extensions-to-ansi

See function-resolution mathematical-functions

See gis-mysql-specific-functions gis-data-formats

See gis-wkt-functions

See gis-wkb-functions

See gis-linestring-property-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-mysql-specific-functions

See gis-wkt-functions

See gis-wkb-functions

See string-functions

See function-optimization partitioning-hash
mathematical-functions

See partitioning-linear-hash mathematical-functions

See contributors

[index top]

See date-and-time-functions
partitioning-limitations-functions

See mysql-real-escape-string mysql-real-escape-string-quote
See string-functions string-literals

[index top]

See mathematical-functions

See replication-sbr-rbr create-procedure
replication-rbr-safe-unsafe function-optimization
query-cache-operation mathematical-functions
mysqlbinlog-hexdump replication-features-functions
server-system-variables

See encryption-functions query-cache-operation

See upgrading-from-previous-series query-cache-operation
See miscellaneous-functions

See replication-sbr-rbr replication-rbr-safe-unsafe
do query-cache-operation internal-locking
miscellaneous-functions replication-features-functions
lock-tables-restrictions

See string-functions-charset string-functions

See string-functions-charset string-functions

See string-functions-charset string-functions

See string-functions-charset string-functions

See innodb-information-schema-system-tables
mathematical-functions precision-math
precision-math-examples precision-math-rounding

See call delete replication-rbr-safe-unsafe
diagnostics-area-information-items information-functions
insert binary-log-mixed mysql-affected-rows
replication-features-functions

See string-functions-charset string-functions

See string-functions-charset string-functions

[index top]

See information-functions

See date-and-time-functions

See date-and-time-functions
partitioning-limitations-functions

See replication-rbr-safe-unsafe information-functions
charset-metadata

See server-options

See encryption-functions

See encryption-functions

See encryption-functions security-guidelines
server-system-variables mysql-nutshell

See mathematical-functions

See mathematical-functions udf-arguments

See replication-sbr-rbr replication-rbr-safe-unsafe
general-thread-states query-cache-operation
miscellaneous-functions tp-thread-group-stats-table

See adding-functions string-functions-charset
string-functions

See string-functions-charset string-functions

See mathematical-functions

See gis-general-property-functions

See gis-property-functions gis-polygon-property-functions

See fetching-spatial-data gis-format-conversion-functions

See spatial-geojson-functions json

See fetching-spatial-data gis-format-conversion-functions

See gis-format-conversion-functions

See gis-format-conversion-functions

See spatial-operator-functions

See server-system-variables spatial-operator-functions

See gis-polygon-property-functions

See spatial-relation-functions-object-shapes

See spatial-operator-functions

See spatial-relation-functions-object-shapes

See spatial-operator-functions

See gis-general-property-functions

See spatial-relation-functions-object-shapes

See spatial-relation-functions-object-shapes

See spatial-convenience-functions

See gis-linestring-property-functions
spatial-operator-functions

See gis-general-property-functions
spatial-operator-functions

See spatial-relation-functions-object-shapes

See gis-polygon-property-functions
spatial-operator-functions

See spatial-geohash-functions

See gis-wkt-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-geometrycollection-property-functions
spatial-operator-functions

See gis-general-property-functions

See spatial-geojson-functions json

See gis-wkt-functions populating-spatial-columns
gis-data-formats

See gis-wkb-functions

See gis-polygon-property-functions
spatial-operator-functions

See spatial-operator-functions

See spatial-relation-functions-object-shapes

See gis-linestring-property-functions

See gis-general-property-functions

See gis-general-property-functions

See geometry-well-formedness-validity
spatial-convenience-functions

See spatial-geohash-functions

See gis-linestring-property-functions spatial-types
string-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See spatial-geohash-functions

See spatial-convenience-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions gis-data-formats

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-geometrycollection-property-functions

See gis-polygon-property-functions

See gis-polygon-property-functions

See gis-linestring-property-functions

See spatial-relation-functions-object-shapes

See spatial-geohash-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-linestring-property-functions
spatial-operator-functions

See gis-wkt-functions

See gis-wkb-functions

See gis-wkt-functions

See gis-wkb-functions

See spatial-convenience-functions

See gis-general-property-functions

See gis-linestring-property-functions
spatial-operator-functions

See spatial-operator-functions

See spatial-relation-functions-object-shapes

See spatial-operator-functions

See spatial-convenience-functions

See spatial-relation-functions-object-shapes

See gis-point-property-functions gis-data-formats

See gis-point-property-functions

See gis-linestring-property-functions

See group-by-functions extensions-to-ansi features

See group-by-functions

See group-by-functions

See group-by-functions

See date-and-time-functions locale-support

See using-date string-comparison-functions

See date-and-time-functions

See string-functions

See string-functions-charset string-functions

See account-activity-auditing string-functions

See date-and-time-functions

See adding-udf group-by-functions
date-and-time-type-overview group-by-optimization
miscellaneous-functions derived-table-optimization
partitioning-overview problems-with-null enum
features set view-updatability

See replication-sbr-rbr date-and-time-functions
replication-rbr-safe-unsafe query-cache-operation
replication-features-fractional-seconds
replication-features-functions server-options
server-system-variables

See replication-rbr-safe-unsafe information-functions
charset-metadata

[index top]

See mathematical-functions

See server-system-variables

See date-and-time-functions

See cast-functions date-and-time-functions

See date-and-time-functions
partitioning-limitations-functions

See date-and-time-functions

See date-and-time-functions

See date-and-time-functions

See date-and-time-functions date-calculations

See string-functions

See date-and-time-functions partitioning-hash
extensions-to-ansi partitioning-pruning
partitioning-limitations-functions partitioning-types

See date-and-time-functions partitioning-pruning
partitioning-limitations-functions partitioning-types

See spatial-relation-functions-object-shapes

See string-functions-charset charset-conversion
extensions-to-ansi string-functions

See mathematical-functions

[index top]

See string-functions-charset string-functions

See encryption-functions source-configuration-options
server-system-variables

See encryption-functions

See encryption-functions string-functions

See date-and-time-functions replication-rbr-safe-unsafe
See query-cache-operation partitioning-limitations-functions
See partitioning-range server-system-variables
sys-metrics timezone-problems

See xml-functions

See cast-functions string-functions-charset
charset-repertoire string-functions
charset-unicode-sets charset-collation-information-schema

See replication-sbr-rbr alter-user
charset-collation-coercibility replication-rbr-safe-unsafe
See query-cache-operation
writing-authentication-plugins-proxy-users
information-functions binary-log-mixed
validate-password-options-variables proxy-users
replication-features-functions account-activity-auditing
charset-metadata writing-authentication-plugins-server-side

See date-and-time-functions

See date-and-time-functions replication-rbr-safe-unsafe

See date-and-time-functions

See date-and-time-functions replication-rbr-safe-unsafe

See date-and-time-functions

See date-and-time-functions replication-rbr-safe-unsafe
See time-zone-support
replication-features-fractional-seconds

See replication-sbr-rbr stored-programs-logging
replication-options-binary-log replication-rbr-safe-unsafe
See function-optimization query-cache-operation
miscellaneous-functions binary-log-mixed
replication-features-functions binary-log-setting

See replication-sbr-rbr replication-rbr-safe-unsafe
query-cache-operation miscellaneous-functions

[index top]

See encryption-functions validate-password-options-variables
See validate-password plugin-types

See insert-on-duplicate miscellaneous-functions

See group-by-functions

See group-by-functions

See group-by-functions

See replication-sbr-rbr audit-log-file-formats
case-sensitivity charset-collation-coercibility
information-functions replication-features-functions
charset-metadata

[index top]

See channels-with-prev-replication gtid-functions
replication-mode-change-online-concepts

See channels-commands-single-channel
channels-with-prev-replication gtid-functions

See date-and-time-functions server-system-variables

See date-and-time-functions extensions-to-ansi
partitioning-limitations-functions partitioning-types

See date-and-time-functions

See adding-collation case-sensitivity
string-functions charset-unicode-sets

See spatial-relation-functions-mbr

[index top]

See gis-point-property-functions

[index top]

See gis-point-property-functions

See date-and-time-functions date-calculations
partitioning-hash partitioning-handling-nulls
partitioning-management-range-list partitioning-pruning
partitioning-limitations-functions partitioning-types
partitioning-range

See date-and-time-functions
partitioning-limitations-functions

C | E | F | G | I | K | N | O | P | R | S | T | U | V

[index top]

See charset-mysql show-character-set
charset-charsets character-sets-table

See collation-character-set-applicability-table

See c-api-data-structures charset-mysql
information-schema-optimization show-collation
collations-table

See column-privileges-table

See information-schema-optimization show-columns
columns-table parameters-table routines-table

See connection-control-installation
connection-control-variables connection-control
connection-control-failed-login-attempts-table

[index top]

See mysql-cluster-sql-statements server-system-variables
See show-engines engines-table

See events-metadata events-configuration
replication-features-invoked events-table

[index top]

See mysql-cluster-i_s-tables mysql-cluster-disk-data-objects
See mysql-cluster-ndbinfo files-table

[index top]

See mysql-cluster-management
mysql-cluster-ndb-api-statistics mysql-cluster-replication
See server-system-variables show-status status-table

See server-system-variables show-variables
variables-table

[index top]

See mysql-cluster-i_s-tables innodb-information-schema
glossary data-directory sys-schema-usage

See faqs-cjk

See adding-collation-choosing-id

See faqs-cjk upgrading-strategies mysqldump
mysql-cluster-programs-ndb-index-stat
performance-schema-quick-start server-system-variables

See performance-schema-quick-start
mysql-cluster-sql-statements innodb-check-availability

See events-metadata replication-features-invoked
stored-program-restrictions show-events
events-privileges

See alter-logfile-group alter-tablespace
create-logfile-group create-tablespace
mysql-cluster-disk-data-storage-requirements
mysql-cluster-programs-ndb-desc
innodb-information-schema-files-table
innodb-temporary-tablespace files-table
innodb-sys-datafiles-table innodb-sys-tablespaces-table
tablespaces-table

See mysql-cluster-ndb-api-statistics

See innodb-insert-buffering

See glossary innodb-compression-tuning
innodb-information-schema-examples-compression-sect

See innodb-parameters innodb-compression-tuning

See innodb-information-schema-examples-compression-sect

See innodb-fulltext-index

See fulltext-stopwords

See innodb-fulltext-index fulltext-search-mecab
fulltext-search-ngram

See fulltext-stopwords

See innodb-information-schema-examples

See innodb-information-schema-examples

See innodb-insert-buffering innodb-parameters

See files-table

See innodb-fulltext-index

See general-tablespaces
innodb-information-schema-system-tables innodb-physical-record
See innodb-troubleshooting-datadict

See general-tablespaces
innodb-information-schema-system-tables
innodb-page-compression

See innodb-information-schema-system-tables

See innodb-parameters innodb-temporary-tablespace

See innodb-parameters innodb-information-schema-examples

See constraint-foreign-key innodb-foreign-key-constraints
See create-table-foreign-keys

See partitioning-management-exchange
partitioning-handling-nulls partitioning-key
partitioning-info partitioning-columns-range
server-options partitions-table

See connection-control-installation
innodb-tablespace-encryption install-plugin
server-plugin-loading audit-log-installation
keyring-installation ldap-pluggable-authentication
no-login-pluggable-authentication obtaining-plugin-information
See pam-pluggable-authentication partitioning
validate-password-installation plugin-api-characteristics
See plugin-api-components replication-semisync-installation
See server-plugin-descriptors
socket-pluggable-authentication test-pluggable-authentication
See thread-pool-installation
windows-pluggable-authentication writing-audit-plugins
writing-daemon-plugins writing-full-text-plugins
writing-information-schema-plugins writing-keyring-plugins
See writing-password-validation-plugins
writing-authentication-plugins-server-side

See thread-information information-functions kill
See performance-schema-instrument-naming
performance-schema-stage-tables show-processlist
processlist-table threads-table
innodb-information-schema-examples

See information-schema faqs-stored-procs
routines-table

See mysql-cluster-ndb-api-statistics

See analyze-table innodb-statistics-estimation
index-hints innodb-parameters
mysql-cluster-programs-ndb-index-stat

See innodb-create-index-overview
referential-constraints-table

See mysql-cluster-online-add-node-example alter-table
innodb-statistics-estimation information-schema
innodb-parameters innodb-tablespace-encryption
server-options innodb-row-format-specification
sys-diagnostics sys-sys-config

See faqs-triggers

See view-updatability

See innodb-insert-buffering
innodb-information-schema-buffer-pool-tables
sys-schema-prerequisites innodb-buffer-page-lru-table
sys-innodb-buffer-stats-by-schema
sys-innodb-buffer-stats-by-table

See innodb-information-schema-buffer-pool-tables
innodb-preload-buffer-pool innodb-buffer-page-lru-table

See innodb-information-schema-buffer-pool-tables
innodb-buffer-pool-monitoring

See innodb-information-schema-compression-tables
innodb-information-schema-innodb_cmp
innodb-information-schema-innodb_cmpmem
innodb-compression-tuning-monitoring
innodb-information-schema-examples-compression-sect

See innodb-compression-tuning-monitoring
innodb-information-schema-examples-compression-sect

See innodb-information-schema-compression-tables
innodb-information-schema-innodb_cmp
innodb-information-schema-innodb_cmpmem

See innodb-information-schema-compression-tables
innodb-information-schema-innodb_cmpmem
innodb-information-schema-examples-compression-sect

See innodb-information-schema-innodb_cmpmem

See innodb-fulltext-index
innodb-information-schema-fulltext_index-tables
innodb-parameters

See innodb-fulltext-index
innodb-information-schema-fulltext_index-tables
innodb-parameters

See fulltext-stopwords innodb-fulltext-index
innodb-information-schema-fulltext_index-tables

See innodb-fulltext-index
innodb-information-schema-fulltext_index-tables
innodb-parameters innodb-ft-being-deleted-table

See innodb-fulltext-index
innodb-information-schema-fulltext_index-tables
innodb-parameters

See innodb-fulltext-index
innodb-information-schema-fulltext_index-tables
innodb-parameters

See innodb-ft-being-deleted-table innodb-ft-deleted-table

See innodb-information-schema-transactions
innodb-information-schema-understanding-innodb-locking
innodb-information-schema-internal-data mysql-nutshell

See innodb-information-schema-transactions
innodb-information-schema-understanding-innodb-locking
innodb-information-schema-internal-data
innodb-lock-waits-table innodb-trx-table
mysql-nutshell

See innodb-insert-buffering index-page-merge-threshold
innodb-information-schema-metrics-table glossary
sys-metrics

See innodb-information-schema-system-tables
innodb-sys-virtual-table

See innodb-information-schema-system-tables
innodb-information-schema-files-table files-table
tablespaces-table

See innodb-information-schema-system-tables

See constraint-foreign-key innodb-foreign-key-constraints
See innodb-information-schema-system-tables
create-table-foreign-keys

See constraint-foreign-key innodb-foreign-key-constraints
See innodb-information-schema-system-tables
create-table-foreign-keys

See index-page-merge-threshold innodb-fulltext-index
innodb-information-schema-system-tables

See innodb-fulltext-index
innodb-information-schema-system-tables

See innodb-information-schema-system-tables
innodb-information-schema-files-table files-table
innodb-sys-tablespaces-table tablespaces-table

See innodb-information-schema-system-tables

See innodb-information-schema-temp-table-info

See innodb-information-schema-transactions
innodb-information-schema-understanding-innodb-locking
innodb-information-schema-internal-data innodb-locks-table
See innodb-information-schema-examples

[index top]

See information-schema-optimization key-column-usage-table

[index top]

See mysql-cluster-ndbinfo-server-operations
mysql-cluster-ndbinfo-server-transactions

See mysql-cluster-i_s-tables
mysql-cluster-program-options-mysqld mysql-cluster-ndbinfo

[index top]

See optimizer-trace-table

[index top]

See faqs-stored-procs parameters-table
routines-table

See partitioning-management-exchange
partitioning-handling-nulls partitioning-info
information-schema-optimization partitioning
partitions-table

See obtaining-plugin-information plugins-table

See thread-information explain-for-connection
innodb-information-schema-internal-data show-processlist
innodb-trx-table processlist-table sys-processlist
See threads-table innodb-information-schema-examples

See show-profile profiling-table mysql-nutshell

[index top]

See information-schema-optimization
referential-constraints-table

See faqs-stored-procs show-procedure-status
stored-routines-metadata parameters-table
routines-table

[index top]

See schema-privileges-table

See grant-tables schemata-table

See mysql-cluster-management
mysql-cluster-ndb-api-statistics mysql-cluster-replication
See server-system-variables show-status status-table

See server-system-variables show-variables
variables-table

See information-schema-optimization show-index
statistics-table

[index top]

See information-schema-optimization table-constraints-table

See table-privileges-table

See create-table information-schema
information-schema-optimization
create-table-ndb-table-comment-options tables-table

See tablespaces-table

See tp-thread-group-state-table thread-pool-components
thread-pool-i_s-tables

See tp-thread-state-table thread-pool-components
thread-pool-i_s-tables

See thread-pool-components thread-pool-i_s-tables
thread-pool-installation

See information-schema-optimization show-create-trigger
See show-triggers triggers-table trigger-metadata

[index top]

See user-privileges-table

[index top]

See information-schema-optimization show-create-view
views-table view-metadata

A | C | E | F | I | R | S | U

[index top]

See table-scan-avoidance bnl-bka-optimization
explain-output nested-loop-joins

[index top]

See explain-output explain-extended
mysql-cluster-system-variables order-by-optimization
range-optimization select

[index top]

See bnl-bka-optimization explain-output
index-condition-pushdown-optimization merge-table-advantages
See mysql-cluster-system-variables
subquery-optimization-with-exists events-waits-current-table

[index top]

See explain-output

[index top]

See bnl-bka-optimization explain-output
nested-loop-joins

See explain-output index-merge-optimization

See explain-output optimizing-subqueries
subquery-optimization-with-exists

[index top]

See bnl-bka-optimization explain-output
group-by-optimization index-condition-pushdown-optimization
See index-merge-optimization nested-loop-joins
range-optimization

See bnl-bka-optimization explain-output
explain-extended index-condition-pushdown-optimization
index-statistics merge-table-advantages
mysql-cluster-system-variables derived-table-optimization
See subquery-optimization-with-exists

See explain-output index-condition-pushdown-optimization
See is-null-optimization subquery-optimization-with-exists

[index top]

See explain-output explain-extended
range-optimization select

[index top]

See explain-output optimizing-subqueries
subquery-optimization-with-exists

Symbols | A | B | C | D | E | I | L | N | O | R | X

[index top]

See arithmetic-functions cast-functions
date-and-time-functions numeric-type-overview
partitioning-limitations

See expressions logical-operators
operator-precedence

See comparison-operators operator-precedence
range-optimization json

See arithmetic-functions

See bit-functions create-table
partitioning-limitations

See logical-operators extensions-to-ansi

See comparison-operators index-btree-hash
explain-output extensions-to-ansi operator-precedence
See generated-column-index-optimizations range-optimization
See json

See json-search-functions create-table-secondary-indexes
See json

See bit-functions extensions-to-ansi
partitioning-limitations

See create-table-secondary-indexes json

See comparison-operators index-btree-hash
explain-output extensions-to-ansi operator-precedence
See generated-column-index-optimizations range-optimization
See json

See comparison-operators index-btree-hash
explain-output extensions-to-ansi operator-precedence
See generated-column-index-optimizations range-optimization
See json working-with-null

See comparison-operators explain-output
extensions-to-ansi operator-precedence
range-optimization json working-with-null

See bit-functions extensions-to-ansi
partitioning-limitations

See comparison-operators index-btree-hash
explain-output extensions-to-ansi operator-precedence
See generated-column-index-optimizations range-optimization
See json

See comparison-operators explain-output
extensions-to-ansi operator-precedence
range-optimization json type-conversion

See arithmetic-functions numeric-type-overview
partitioning-limitations

See arithmetic-functions cast-functions
date-and-time-functions numeric-type-overview
partitioning-limitations

See arithmetic-functions partitioning-limitations
server-system-variables

See assignment-operators operator-precedence
set-variable user-variables

See assignment-operators comparison-operators
index-btree-hash explain-output extensions-to-ansi
See operator-precedence generated-column-index-optimizations
See range-optimization subquery-restrictions
set-variable string-comparison-functions json
user-variables working-with-null

See bit-functions expressions operator-precedence
See partitioning-limitations

See bit-functions partitioning-limitations

See string-functions-charset charset-collate-precedence
See expressions logical-operators extensions-to-ansi
See operator-precedence sql-mode

See bit-functions partitioning-limitations

[index top]

See index-btree-hash create-table
index-merge-optimization logical-operators
extensions-to-ansi subquery-optimization-with-exists
semi-joins range-optimization subquery-restrictions
See row-constructor-optimization searching-on-two-keys
mysql-shell-tutorial-javascript-table-select
mysql-shell-tutorial-python-table-select selecting-rows
string-comparison-functions view-algorithms

[index top]

See comparison-operators index-btree-hash
explain-output generated-column-index-optimizations
range-optimization json type-conversion

See cast-functions optimize-character
pattern-matching sorting-rows

[index top]

See case control-flow-functions expressions
extensions-to-ansi

See control-flow-functions

See control-flow-functions

See control-flow-functions

See json-search-functions

See json-search-functions json mysql-nutshell

[index top]

See arithmetic-functions partitioning-limitations

[index top]

See comparison-operators

See string-comparison-functions

See comparison-operators

See string-comparison-functions

See regexp

See regexp

See regexp

See regexp

See string-functions

[index top]

See operator-precedence

See comparison-operators

See comparison-operators

See comparison-operators problems-with-null
range-optimization working-with-null

See comparison-operators explain-output
is-null-optimization subquery-optimization-with-exists
problems-with-null range-optimization
server-system-variables working-with-null

[index top]

See request-access cast-functions charset-mysql
See index-btree-hash extended-show
json-search-functions help faqs-cjk
extensions-to-ansi mysql-server-side-help
mysql-cluster-replication-conflict-resolution
operator-precedence pattern-matching
performance-schema-instrument-filtering
mysql-cluster-sql-statements range-optimization
replication-options-slave show-character-set
show-collation show-columns show-databases
show-events show-open-tables show-procedure-status
See show-status show-table-status show-tables
show-triggers show-variables account-names
string-comparison-functions string-literals
structured-system-variables char
sys-ps-setup-disable-consumer sys-ps-setup-disable-instrument
See sys-ps-setup-enable-consumer
sys-ps-setup-enable-instrument set
using-system-variables

See faqs-cjk

See range-optimization show

See bugs

[index top]

See arithmetic-functions mathematical-functions

See arithmetic-functions mathematical-functions

See logical-operators sql-mode

See pattern-matching string-comparison-functions

See extensions-to-ansi pattern-matching
string-comparison-functions

See pattern-matching string-comparison-functions

[index top]

See expressions grant index-merge-optimization
logical-operators extensions-to-ansi
operator-precedence subquery-optimization-with-exists
range-optimization row-constructor-optimization
searching-on-two-keys
mysql-shell-tutorial-javascript-table-select
mysql-shell-tutorial-python-table-select selecting-rows
sql-mode string-comparison-functions

[index top]

See extensions-to-ansi operator-precedence
pattern-matching regexp charset-restrictions

See pattern-matching regexp charset-restrictions

[index top]

See group-by-functions logical-operators

Symbols | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P
| Q | R | S | T | U | V | W | X | Y | Z

[index top]

See ansi-diff-comments replace-utility

See comp-err my-print-defaults
myisamchk-general-options myisampack
mysql-command-options mysql-config-editor
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqlimport mysqlpump
See mysqlshow mysqlslap replace-utility
server-options dbug-package

See mysqlcheck

See comp-err innochecksum my-print-defaults
myisam-ftdump myisamchk-general-options myisamlog
See myisampack mysql-command-options
mysql-config-editor mysql-install-db mysql-plugin
See mysql-secure-installation mysqladmin mysqlbinlog
See mysqlcheck mysqldump mysqlimport
mysqlpump mysqlshow mysqlslap
mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-perror
mysql-cluster-programs-ndb-print-file
mysql-cluster-programs-ndb-top
mysql-cluster-program-options-common perror
replace-utility resolveip server-options
features command-line-options

See mysql-ssl-rsa-setup

[index top]

See mysql-command-options mysqlcheck mysqldump
mysqlpump mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-restore myisamchk-other-options

See mysql-cluster-mgm-client-commands innochecksum
myisam-optimization mysqlcheck mysqldumpslow
mysqlslap mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-setup-py myisamchk-other-options

See mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-move-data

See replication-options-slave

See mysqldump-sql-format mysqldump mysqlpump

See upgrading-from-previous-series mysqldump
mysqlpump

See mysqldump

See mysqlpump

See mysqldump mysqlpump

See mysql-install-db

See mysql-install-db

See mysql-install-db

See mysql-install-db

See mysql-install-db

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See mysql-config-editor

See replication-howto-mysqldump mysqldump-sql-format
identifier-mapping upgrading-strategies mysqlcheck
See mysqldump mysqlpump mysql-cluster-ndbinfo
rebuilding-tables reloading-sql-format-dumps
mysqlbinlog-backup

See mysqlcheck

See mysqldump

See mysqldump

See innochecksum

See server-options udf-security

See myisam-optimization myisamchk-general-options
mysqlcheck myisamchk-other-options

See compatibility server-options

See pam-pluggable-authentication

See mysql-cluster-programs-ndb-restore

See mysqldump

See audit-log-options-variables audit-log-installation

See mysqlsh

See mysqlslap

See mysqlslap

See mysqlslap

See mysqlslap

See mysqlslap

See mysqlslap

See mysqlslap

See mysqlslap

See mysqlslap

See innodb-statistics-estimation mysql-commands
mysql-command-options

See innodb-statistics-estimation

See mysqlcheck

See mysql-command-options

See server-system-variables

[index top]

See myisamchk-repair-options mysql-command-options
mysqlcheck mysqldump mysqlpump

See myisampack mysql-command-options mysql-plugin
See mysqladmin mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-restore myisamchk-other-options
See server-options

See solaris-installation

See myisamchk-repair-options myisampack

See mysql-cluster-programs-ndb-restore
ndb-restore-to-fewer-nodes

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore
ndb-restore-to-fewer-nodes

See replication-sbr-rbr replication-gtids-concepts
mysqlbinlog-row-events mysqlbinlog
replication-rbr-usage

See data-directory-initialization-mysql-install-db
data-directory-initialization-mysqld
source-configuration-options mysql-install-db
mysql-plugin mysql-upgrade mysqld-safe
mysql-cluster-limitations-syntax multiple-servers
server-options starting-server-troubleshooting
mysql-nutshell

See windows-create-option-file mysql-server
windows-troubleshooting

See mysql-logging mysql-command-options

See server-options

See mysql-command-options

See mysql-commands mysql-command-options mysqlbinlog
See point-in-time-recovery

See can-not-connect-to-server ipv6-server-config
ipv6-remote-connections ipv6-local-connections
ipv6-support mysql-command-options mysql-upgrade
mysqladmin mysqlbinlog mysqlcheck mysqld-multi
See mysqldump mysqlimport mysqlpump
mysqlshow mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndbd ipv6-brokers
multiple-servers server-options
server-system-variables mysql-cluster-ndbinfo-processes
problems-connecting

See replication-options-binary-log

See replication-options-binary-log
replication-rules-db-options replication-rules
mysql-cluster-replication-issues mysqlbinlog
replication-options-slave binary-log

See binary-log-formats replication-options-binary-log
mysql-cluster-replication-general faqs-stored-procs
server-options binary-log-setting
mysql-cluster-replication-starting
mysql-cluster-limitations-unsupported

See replication-options-binary-log
replication-rules-db-options replication-rules
mysql-cluster-replication-issues replication-options-slave
See binary-log

See replication-options-binary-log mysqlbinlog
binary-log-setting

See replication-options-binary-log

See mysql-cluster-programs-ndb-desc

See myisamchk-other-options

See mysql-innodb-cluster-limitations server-options
server-system-variables mysql-innodb-cluster-using-router
See mysql-nutshell

See mysql-innodb-cluster-using-router

See mysql-cluster-programs-ndb-setup-py

See mysql-install-db

[index top]

See comp-err innochecksum myisamchk-check-options
See mysql-command-options mysql-upgrade mysqladmin
See mysqlcheck mysqldump mysqlimport
mysqlpump mysqlshow mysqlslap server-options

See innochecksum mysql-cluster-install-windows-binary
my-print-defaults myisam-ftdump
myisamchk-check-options myisamlog faqs-mysql-cluster
See mysql-command-options mysqladmin mysqlbinlog
See mysqlcheck mysqldump mysqlimport
mysqlslap mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-top
mysql-cluster-program-options-common
ndb-restore-to-fewer-nodes

See mysql-cluster-install-auto-requirements
mysql-cluster-programs-ndb-setup-py

See mysql-cluster-install-auto-requirements
mysql-cluster-programs-ndb-setup-py

See compilation-problems mysql-config

See faqs-cjk server-options charset-cp932

See server-options

See charset-configuration charset-applications
faqs-cjk charset-server server-options

See cannot-initialize-character-set charset-configuration
See myisamchk-repair-options myisampack
mysql-command-options mysql-upgrade mysqladmin
mysqlbinlog mysqlcheck mysqldump mysqlimport
See mysqlpump mysqlshow
mysql-cluster-programs-ndb-move-data
mysql-cluster-program-options-common server-options

See source-configuration-options

See comp-err

See myisamchk-check-options mysqlcheck

See myisamchk-check-options mysqlcheck

See mysql-cluster-programs-ndb-blob-tool

See mysqlcheck

See server-options

See mysqlsh

See source-configuration-options

See compiling-for-debugging compilation-problems
source-configuration-options

See source-configuration-options

See source-configuration-options

See compiling-for-debugging compilation-problems
source-configuration-options

See source-configuration-options

See source-configuration-options

See compiling-plugin-libraries installing-development-tree
See keyring-system-variables source-configuration-options
See multiple-unix-servers server-system-variables

See source-configuration-options

See charset-configuration charset-applications
charset-server server-options

See source-configuration-options

See mysql-cluster-programs-ndb-top

See mysql-command-options option-modifiers

See limit-optimization mysql-command-options

See mysqlimport

See mysql-command-options mysqldump optimizer-hints
See mysql-nutshell

See mysqlslap

See program-options mysql-nutshell

See mysqldump

See mysqldump

See server-system-variables

See mysqldump mysqlpump

See program-options mysql-nutshell

See load-data mysql-command-options mysql-upgrade
See mysqladmin mysqlcheck mysqldump
mysqlimport mysqlpump mysqlshow mysqlslap
See program-options mysql-nutshell

See mysqlpump

See mysqlslap

See mysql-innodb-cluster-using-router

See mysql-cluster-config-file
mysql-cluster-programs-ndb-mgmd

See mysql-cluster-programs-ndb-mgmd

See mysql-cluster-install-first-start
mysql-cluster-install-windows-initial-start
mysql-cluster-install-windows-service my-print-defaults
faqs-mysql-cluster mysql-cluster-config-example
mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-mgmd

See mysql-cluster-programs-ndb-config

See mysql-cluster-config-file
mysql-cluster-programs-ndb-mgmd

See mysql-cluster-programs-ndb-config

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndbd

See mysql-command-options expired-password-handling

See mysql-cluster-programs-ndb-mgm
mysql-cluster-programs-ndbd
mysql-cluster-program-options-common

See mysql-cluster-programs-ndb-mgm
mysql-cluster-programs-ndbd
mysql-cluster-program-options-common

See mysql-cluster-program-options-common

See connection-control-installation

See connection-control-installation

See mysqlbinlog

See mysql-cluster-programs-ndb-error-reporter

See mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-import

See innodb-enabling-monitors error-log-windows
mysql-cluster-install-windows-initial-start
data-directory-initialization-mysqld innodb-troubleshooting
See resetting-permissions-windows server-options
windows-start-command-line windows-server-first-start

See mysql-cluster-programs-ndb-import

See using-gdb-on-mysqld mysql-cluster-program-options-common
See server-options server-system-variables

See making-windows-dumps

See using-systemd mysqld-safe server-options

See myisamchk-repair-options

See innochecksum myisam-ftdump mysqladmin
mysqlshow

See mysqlslap

See mysqldump

See mysqlslap

See mysql-install-db

See mysqlslap

See compilation-problems mysql-config

[index top]

See adding-character-set
building-with-encrypted-connection-support
mysql-cluster-install-linux-source
cannot-initialize-character-set comp-err
mysql-cluster-install-windows-source compiling-for-debugging
See libmysqld-compiling
mysql-shell-connection-using-parameters debugging-client
innochecksum installing-source-distribution
using-systemd myisamchk-repair-options
mysql-command-options mysql-cluster-mysqld
source-configuration-options mysqlbinlog mysqlimport
See mysqlsh mysql-cluster-programs-ndb-select-all
partitioning replication-options-slave server-options
See server-system-variables innodb-memcached-setup
archive-storage-engine blackhole-storage-engine
example-storage-engine federated-storage-engine
dba-dtrace-server crashing which-version

See docker-mysql-getting-started myisam-ftdump
myisamchk-general-options mysql-plugin mysqlbinlog
See mysqldump mysqldumpslow mysqlpump
mysql-cluster-programs-ndb-blob-tool
mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-index-stat
mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndbd myisamchk-other-options
server-system-variables keyring-okv-plugin

See mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndbd

See server-options

See myisamchk-repair-options

See mysql-shell-connection-using-parameters
mysql-command-options mysqlbinlog mysqlsh
mysql-cluster-programs-ndb-blob-tool
mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-index-stat
mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndb-size-pl

See mysqldump-copying-to-other-server
replication-howto-mysqldump mysqldump-sql-format
mysqldump-copying-database mysqlcheck mysqldump
mysqlpump mysql-cluster-ndbinfo rebuilding-tables
See reloading-sql-format-dumps

See windows-create-option-file
data-directory-initialization-mysql-install-db
data-directory-initialization-mysqld
source-configuration-options mysql-install-db
mysql-plugin mysql-ssl-rsa-setup mysql-upgrade
mysqld-safe mysql-cluster-security-mysql-security-procedures
See multiple-servers multiple-unix-servers
server-options multiple-data-directories
data-directory starting-server-troubleshooting
option-files mysql-nutshell

See windows-create-option-file osx-installation-notes
mysql-server windows-troubleshooting limits-windows

See mysql-cluster-programs-ndb-import

See mysqlsh

See mysql-shell-connection-using-parameters mysqlsh

See mysql-shell-connection-using-parameters mysqlsh

See comp-err compiling-for-debugging
my-print-defaults myisamchk-general-options myisampack
See mysql-command-options source-configuration-options
mysql-config-editor mysql-upgrade mysqladmin
mysqlbinlog mysqlcheck mysqldump mysqldumpslow
See mysqlimport mysqlpump mysqlshow
mysqlslap mysql-cluster-program-options-common
server-options server-system-variables
windows-start-command-line dbug-package
problems-connecting starting-server-troubleshooting

See mysql-command-options mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlshow mysqlslap

See comp-err mysql-command-options mysql-upgrade
See mysqladmin mysqlbinlog mysqlcheck
mysqldump mysqlimport mysqlpump mysqlshow
See mysqlslap

See mysql-cluster-programs-ndb-setup-py

See source-configuration-options server-options
server-system-variables

See c-api-plugin-functions client-plugin-descriptors
connecting mysql-command-options mysql-upgrade
mysqladmin mysqlbinlog mysqlcheck mysqldump
See mysqlimport mysqlpump mysqlshow
mysqlslap native-pluggable-authentication
old-native-pluggable-authentication pluggable-authentication
See writing-authentication-plugins-setup

See server-options server-system-variables

See charset-configuration charset-applications
charset-connection mysql-batch-commands load-data
See mysql-command-options mysql-upgrade mysqladmin
See mysqlcheck mysqldump mysqlimport
mysqlpump mysqlshow server-system-variables
windows-unicode-support user-names

See mysqlpump

See innodb-parameters server-options
storage-engine-setting

See storage-engine-setting

See time-zone-support server-options
server-system-variables

See innodb-parameters server-options

See structured-system-variables

See charset-applications charset-server

See charset-applications charset-server

See mysql-install-db

See option-file-options data-directory-initialization-mysqld
See mysql-innodb-cluster-limitations my-print-defaults
myisamchk-general-options mysql-command-options
mysql-install-db mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqld-multi mysqld-safe mysqldump
See mysqlimport mysqlpump mysqlshow
mysqlslap mysql-cluster-program-options-common
server-options option-files

See option-file-options password-security-user
data-directory-initialization-mysqld
innodb-init-startup-configuration keyring-key-migration
my-print-defaults myisamchk-general-options
mysql-command-options source-configuration-options
mysql-install-db mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqld-multi mysqld-safe mysqldump
See mysqlimport mysqlpump mysqlshow
mysqlslap mysql-cluster-program-options-common
libmysqld-options resetting-permissions-unix
resetting-permissions-windows multiple-servers
multiple-unix-servers server-options
multiple-windows-services
multiple-windows-command-line-servers windows-start-service

See option-file-options my-print-defaults
myisamchk-general-options mysql-command-options
environment-variables mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqlimport mysqlpump
See mysqlshow mysqlslap
mysql-cluster-program-options-common server-options

See mysqlpump

See mysql-cluster-programs-ndbinfo-select-all

See external-locking myisam-start faqs-replication
See server-options crashing

See using-system-variables

See mysqlimport mysql-cluster-programs-ndb-index-stat

See mysqldump

See mysql-cluster-programs-ndb-blob-tool

See mysql-command-options mysqlslap
mysql-cluster-programs-ndb-select-all

See using-stack-trace

See encryption-functions flush server-options
mysql-nutshell

See mysql-cluster-programs-ndb-select-all

See myisamchk-other-options

See mysqlslap

See mysql-cluster-programs-ndb-config

See option-modifiers

See innodb-statistics-estimation mysql-command-options

See mysql-cluster-programs-ndb-restore
ndb-restore-to-more-nodes

See innodb-turning-off mysql-nutshell

See mysqldump

See mysqlbinlog

See mysql-command-options

See partitioning server-options

See server-plugin-loading

See encrypted-connection-options encrypted-connections
mysql-nutshell

See replication-options-slave

See mysql-cluster-programs-ndb-select-all

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-move-data

See mysql-cluster-programs-ndb-error-reporter

See myisam-ftdump mysql-cluster-programs-ndb-index-stat

See mysqldump

See mysql-cluster-programs-ndb-blob-tool

See mysqldump
replication-features-transaction-inconsistencies

[index top]

See mysql-command-options mysqladmin mysqldump
mysqlsh

See myisam-check innochecksum load-xml
docker-mysql-more-topics my-print-defaults
myisamchk-check-options myisamchk-general-options
myisamchk-repair-options faqs-mysql-cluster
mysql-command-options mysqlcheck mysqldump
mysqlsh mysqlslap mysql-cluster-replication-backups
See mysql-cluster-programs-ndb-mgm
mysql-cluster-programs-ndb-restore myisamchk-table-info
mysql-cluster-install-shutdown-restart command-line-options
See mysql-cluster-backup-using-management-client

See upgrading-from-previous-series server-plugin-loading
See keyring-installation mysql-upgrade
server-options keyring-aws-plugin
keyring-encrypted-file-plugin keyring-file-plugin
keyring-okv-plugin writing-keyring-plugins

See innodb-tablespace-encryption

See mysql-config mysql-nutshell

See mysql-config mysql-nutshell

See mysql-nutshell

See cleartext-pluggable-authentication
ldap-pluggable-authentication mysql-command-options
mysqladmin mysqlcheck mysqldump mysqlimport
See mysqlshow mysqlslap pam-pluggable-authentication

See can-not-connect-to-server connecting
windows-select-server server-options features

See server-plugin-loading

See encrypted-connection-options encrypted-connections
mysql-nutshell

See innodb-parameters source-configuration-options

See linux-installation-yum-repo
installing-mysql-shell-linux-quick

See source-configuration-options load-data-local

See innochecksum

See replication-options-gtids replication-gtids-restrictions

See replication-options-gtids

See mysqlslap

See mysql-cluster-config-starting

See docker-mysql-more-topics

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-move-data

See events-configuration server-options

See events-configuration

See mysqldump-stored-programs
mysqldump-definition-data-dumps upgrading-strategies
mysqldump mysqlpump mysqlbinlog-backup

See mysqld-multi

See mysql-cluster-programs-ndb-restore

See mysqlpump mysql-cluster-programs-ndb-restore

See mysqlpump

See mysqlbinlog

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore

See mysqlpump

See mysqlpump mysql-cluster-programs-ndb-restore

See mysqlpump

See mysqlpump

See mysql-cluster-programs-ndb-size-pl

See mysql-cluster-programs-ndb-size-pl

See mysql-logging mysql-command-options mysqlsh
See mysql-cluster-programs-ndb-mgm command-line-options
See mysql-cluster-backup-using-management-client

See replication-options-gtids

See server-options

See myisamchk-check-options myisamchk-general-options
myisamchk-repair-options

See mysqlcheck

See mysqldump mysqlpump

See external-locking myisam-start server-options
See server-system-variables system-optimization

See my-print-defaults

See mysql-cluster-programs-ndb-desc

See mysql-cluster-programs-ndb-desc
mysql-cluster-ndbinfo-cluster-operations
mysql-cluster-ndbinfo-server-operations

See mysql-install-db

[index top]

See comp-err myisamchk-check-options myisamlog
mysql-commands mysqlbinlog mysqlcheck
mysqldump mysqlslap

See mysql-cluster-mgm-client-commands
mysql-cluster-install-first-start
mysql-cluster-install-windows-initial-start
myisamchk-check-options myisamchk-repair-options
myisamlog myisampack faqs-mysql-cluster
mysql-command-options mysql-install-db mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-restore using-stack-trace

See myisamchk-check-options mysqlcheck

See federated-storage-engine

See mysql-cluster-programs-ndb-config

See mysqldump-delimited-text mysqldump mysqlimport
See mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-restore

See mysqldump-delimited-text mysqldump mysqlimport
See mysql-cluster-programs-ndb-import

See mysqldump-delimited-text mysqldump mysqlimport
See mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-restore

See mysqldump-delimited-text mysqldump mysqlimport
See mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-restore

See mysqldump

See mysql-shell-batch-code-execution mysqlsh

See identifier-mapping mysqlcheck mysql-nutshell

See identifier-mapping mysqlcheck mysql-nutshell

See server-options server-system-variables crashing

See backup-policy server-logs mysqldump

See upgrading-from-previous-series mysqldump

See mysql-threads

See myisamchk-check-options myisamchk-repair-options
myisampack mysql-command-options mysql-install-db
See mysql-upgrade mysqladmin mysqlcheck
mysqldump mysqlimport mysqlsh
mysql-cluster-replication-schema mysql-test-suite
mysql-cluster-upgrade-downgrade batch-mode
mysql-cluster-what-is-new-7-5

See mysqlbinlog

See mysqlbinlog

See source-installation

See mysql-cluster-programs-ndbd

See mysql-cluster-programs-ndb-size-pl

See mysql-cluster-programs-ndb-error-reporter

[index top]

See mysql-command-options mysql-config-editor

See compiling-for-debugging my-print-defaults
mysqlcheck mysqldumpslow
mysql-cluster-programs-ndb-top

See mysql-cluster-programs-ndb-select-all

See mysql-cluster-programs-ndb-select-all

See using-gdb-on-mysqld server-options

See server-options

See log-destinations server-options
server-system-variables query-log

See multiple-servers server-options
server-system-variables query-log

See mysql-cluster-programs-ndb-top

See replication-options-gtids

See replication-options-gtids replication-options-slave

[index top]

See comp-err myisamchk-general-options
mysql-command-options mysqlbinlog

See connecting mysql-shell-connection-using-parameters
invoking-programs myisam-ftdump mysql-command-options
See mysql-config-editor mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqldumpslow mysqlimport
See mysqlpump mysqlsh mysqlshow mysqlslap
See mysql-cluster-programs-ndb-print-file
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-top resolve-stack-dump
server-options manual-conventions command-line-options

See mysql-nutshell

See mysql-cluster-programs-ndb-select-all

See comp-err

See myisamchk-general-options

See comp-err innochecksum
mysql-cluster-install-windows-service my-print-defaults
myisam-ftdump myisamchk-general-options myisampack
See mysql-command-options mysql-config-editor
mysql-install-db mysql-plugin
mysql-secure-installation mysql-ssl-rsa-setup
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqld-multi mysqld-safe mysqldump
See mysqldumpslow mysqlimport mysqlpump
mysqlsh mysqlshow mysqlslap
mysql-cluster-programs-ndb-blob-tool
mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-perror
mysql-cluster-programs-ndb-print-file
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-top
mysql-cluster-program-options-common programs-overview
perror resolve-stack-dump resolveip
server-options testing-server features
starting-server-troubleshooting tutorial option-files
See command-line-options

See mysql-cluster-programs-ndb-restore

See mysqldump mysqlpump

See mysqlbinlog-hexdump mysqlbinlog

See mysql-logging mysql-command-options
mysql-nutshell

See ipv6-server-config connecting
mysql-shell-connection-using-parameters invoking-programs
See mysql-command-options mysql-config-editor
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlsh mysqlshow
mysqlslap mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-top option-defaults-equals
server-options problems-connecting manual-conventions
See multiple-server-clients mysqlbinlog-backup
option-files command-line-options
x-plugin-system-variables-options

See mysql-config-editor option-files

See mysql-cluster-programs-ndb-size-pl

See mysql-command-options

[index top]

See c-api-building-clients innochecksum myisamlog
See perror replace-utility resolveip

See mysql-shell-batch-mode-interactive
mysql-cluster-mgm-client-commands myisam-check
myisamchk-check-options myisamlog
mysql-command-options mysql-plugin mysqladmin
mysqldump mysqldumpslow mysqlimport mysqlshow
See mysqlslap

See mysql-command-options safe-updates

See mysql-cluster-programs-ndb-config

See mysqlbinlog server-system-variables

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See mysqlimport

See innodb-parameters

See data-directory-initialization-mysqld server-options
See server-system-variables mysql-nutshell

See mysqldump

See mysqlimport mysql-cluster-programs-ndb-import

See mysql-command-options

See replication-howto-mysqldump mysqldump

See comp-err

See mysql-config

See mysql-cluster-programs-ndb-restore

See mysqlpump mysql-cluster-programs-ndb-restore

See mysqlpump

See mysqlbinlog

See mysqldump

See mysqlpump

See mysqlpump mysql-cluster-programs-ndb-restore

See mysqlpump

See mysqlpump

See innochecksum perror resolveip

See myisamchk-check-options

See mysql-command-options
replication-features-server-side-help

See data-directory-initialization-mysqld
performance-schema-runtime-configuration
resetting-permissions-unix resetting-permissions-windows
server-options server-system-variables
memory-storage-engine

See charset-applications

See mysql-cluster-online-add-node-basics
mysql-cluster-online-add-node-example
mysql-cluster-mgm-client-commands
mysql-cluster-ndbd-definition
mysql-cluster-privilege-distribution
mysql-cluster-install-windows-initial-start
mysql-cluster-replication-issues
mysql-cluster-limitations-multiple-nodes
mysql-cluster-config-file
mysql-cluster-disk-data-storage-requirements
mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-restore mysql-cluster-programs-ndbd
See mysql-cluster-programs-ndbmtd
mysql-cluster-configuration-overview
mysql-cluster-rolling-restart mysql-cluster-replication-pitr
See ndb-restore-to-fewer-nodes mysql-cluster-start-phases
See mysql-cluster-upgrade-downgrade
mysql-cluster-what-is-new-7-6

See mysql-cluster-programs-ndbd

See windows-create-option-file downgrading
data-directory-initialization-mysqld
mysql-cluster-install-linux-binary
mysql-cluster-program-options-mysqld sys-schema
mysql-install-db server-options
server-system-variables mysql-cluster-upgrade-downgrade
mysql-nutshell

See windows-create-option-file downgrading
data-directory-initialization-mysqld
mysql-cluster-install-linux-binary sys-schema
mysql-install-db server-options
server-system-variables mysql-nutshell

See innodb-parameters innodb-turning-off
mysql-nutshell

See innodb-parameters

See innodb-enabling-monitors

See server-options

See innodb-parameters

See tablespace-enabling server-options

See replication-howto-rawdata server-options

See mysql-nutshell

See innodb-error-handling innodb-parameters

See binary-log

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See mysql-install-db

See mysqldump mysqlpump

See option-file-options
mysql-cluster-install-windows-service
mysql-cluster-programs-ndb-mgmd mysql-cluster-programs-ndbd
See server-options multiple-windows-services
windows-start-service

See server-options multiple-windows-services
windows-start-service

See keyring-system-variables source-configuration-options
See server-system-variables

See source-configuration-options

See keyring-system-variables

See c-api-building-clients-pkg-config

See source-configuration-options libmysqld-restrictions
See server-system-variables mysql-nutshell

See server-system-variables

See source-configuration-options

See mysql-shell-batch-mode-interactive mysql-shell-features
See mysqlsh mysql-cluster-programs-ndb-mgmd

See mysqlslap

[index top]

See myisampack mysql-command-options mysqlbinlog

See myisampack

See mysql-shell-active-language mysqlsh

See mysql-shell-json-output mysqlsh

[index top]

See mysqldump

See myisamchk-repair-options mysql-upgrade mysqlshow

See mysql-install-db

See create-table

See program-options mysql-nutshell

See program-options mysql-nutshell

See mysql-cluster-programs-ndb-setup-py

See keyring-options keyring-key-migration

See keyring-options keyring-key-migration

See keyring-options keyring-key-migration

See keyring-options keyring-key-migration

See keyring-options keyring-key-migration

See keyring-options keyring-key-migration

See keyring-options keyring-key-migration

See mysqlshow

See myisamchk-repair-options

[index top]

See c-api-building-clients mysql-command-options
mysqlimport mysql-cluster-programs-ndb-restore
perl-support-problems

See c-api-building-clients c-api-embedded-server-functions
See c-api-function-overview innochecksum
my-print-defaults myisam-ftdump
myisamchk-repair-options mysql-library-end mysqlbinlog
See mysqldump mysqldumpslow mysqlimport
mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndbinfo-select-all

See server-options

See large-page-support server-options
server-system-variables

See mysql-install-db server-options

See mysql-install-db server-options

See mysql-install-db

See mysqld-safe

See myisam-ftdump

See mysql-config mysql-nutshell

See mysql-config mysql-nutshell

See mysql-config

See mysql-command-options

See mysqldump-delimited-text mysqldump mysqlimport
See mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-size-pl

See load-data mysqlimport load-data-local

See load-xml mysql-command-options load-data-local

See mysqlbinlog

See server-options windows-start-service

See mysql-cluster-programs-ndb-select-all

See mysqldump

See mysqldump mysqlimport

See innochecksum mysqld-multi

See backup-strategy-summary replication-options-binary-log
See change-master-to backup-methods backup-policy
See replication-options-gtids replication-bugs bugs
See mysql-cluster-limitations-syntax point-in-time-recovery
See purge-binary-logs replication-options-slave
multiple-servers replication-solutions-switch
binary-log replication-problems replication-upgrade
See recovery-from-backups

See replication-options-binary-log
mysql-cluster-limitations-syntax binary-log

See stored-programs-logging replication-options-binary-log

See replication-options-binary-log

See replication-options-binary-log
mysql-cluster-program-options-mysqld
mysql-cluster-replication-conflict-resolution

See error-log-unix error-log-windows
error-log-syslog docker-mysql-more-topics mysqld-safe
See mysqldump option-defaults-equals
multiple-servers server-options log-file-maintenance
See windows-start-command-line windows-server-first-start

See mysqlpump

See myisamlog server-options

See mysql-shell-application-log mysqlsh
mysql-innodb-cluster-production-deployment

See mysql-cluster-programs-ndb-mgmd

See log-destinations server-options query-log
slow-query-log

See server-options

See password-logging server-options query-log
plugin-types

See server-options slow-query-log

See replication-options-gtids replication-bugs
replication-solutions-performance
mysql-cluster-replication-issues
mysql-cluster-program-options-mysqld
mysql-cluster-replication-multi-master
mysql-cluster-system-variables replication-options-slave
replication-solutions-switch binary-log

See server-options

See replication-options-slave

See server-options

See server-options server-status-variables

See replication-options-slave server-options
server-system-variables mysql-nutshell

See mysqld-safe

See mysql-cluster-programs-ndbd

See mysql-install-db

See option-file-options my-print-defaults
mysql-command-options mysql-config-editor
mysql-install-db mysql-upgrade mysqladmin
mysqlbinlog mysqlcheck mysqldump mysqlimport
See mysqlpump mysqlshow mysqlslap
mysql-cluster-program-options-common option-files

See mysql-cluster-programs-ndb-index-stat
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndbinfo-select-all

See option-modifiers

See option-files

See mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-restore

See mysqlimport

See concurrent-inserts insert faqs-replication
server-options table-locking

See identifier-case-sensitivity

[index top]

See myisamchk-check-options mysqlcheck
mysql-cluster-replication-backups
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-top ndb-restore-to-more-nodes

See using-systemd mysqld-safe

See replication-howto-mysqldump backup-policy
server-logs mysqldump replication-gtids-failover
mysqlbinlog-backup

See replication-options-slave slave-logs-status

See change-master-to innodb-parameters slave-logs
See replication-options-slave replication-howto-existingdata
See slave-logs-status channels-startup-options

See change-master-to replication-options-slave
show-slave-status

See replication-options-binary-log

See program-variables

See mysql-upgrade mysqlpump

See replication-options-binary-log

See replication-options-slave

See myisamchk-repair-options repair-table

See replication-options-slave channels-startup-options

See mysql-cluster-programs-ndb-import

See table-scan-avoidance optimizer-issues

See program-variables

See safe-updates

See option-modifiers

See option-modifiers

See using-system-variables

See option-modifiers

See query-cache-configuration

See server-options using-system-variables

See mysql-cluster-programs-ndb-top

See myisamchk-check-options mysqlcheck

See server-options server-system-variables
innodb-raw-devices

See server-options

See mysql-cluster-programs-ndb-import

See docker-mysql-more-topics

See server-plugin-loading

See mysql-plugin

See server-plugin-loading

See mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-mgmd

See key-cache-block-size server-options

See myisam-start optimizing-queries-myisam
server-options server-system-variables
myisam-maintenance-schedule table-corruption
myisam-storage-engine using-log-files

See myisamchk-memory

See docker-mysql-more-topics

See docker-mysql-more-topics

See docker-mysql-more-topics

See compilation-problems

See docker-mysql-getting-started docker-mysql-more-topics

See docker-mysql-more-topics

See docker-mysql-more-topics

See docker-mysql-more-topics

See docker-mysql-more-topics

See installing-development-tree source-configuration-options

See problems-with-mysql-sock installing-development-tree
See source-configuration-options
x-plugin-system-variables-options

See docker-mysql-more-topics

See mysqld-multi

See mysql-plugin mysqld-multi mysqld-safe

See mysql-install-db

See mysqld-safe

See mysqld-safe

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See source-configuration-options
x-plugin-system-variables-options

See x-plugin-system-variables-options

See source-configuration-options
x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

[index top]

See comp-err mysql-command-options mysqldump
mysql-cluster-programs-ndb-setup-py

See mysql-cluster-mgm-client-commands innochecksum
my-print-defaults myisamchk-repair-options
mysql-command-options mysqldump mysqldumpslow
mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-top
mysql-cluster-programs-ndb-waiter mysql-cluster-programs-ndbd
See resolve-stack-dump

See docker-mysql-getting-started

See comp-err

See mysql-command-options

See mysql-cluster-programs-ndb-perror perror
mysql-cluster-ndbinfo-error-messages
mysql-cluster-what-is-new-7-6

See mysql-cluster-program-options-mysqld
mysql-cluster-what-is-new-7-5

See mysql-cluster-program-options-mysqld

See mysql-cluster-program-options-mysqld

See mysql-cluster-program-options-mysqld

See faqs-mysql-cluster

See mysql-cluster-program-options-mysqld
mysql-cluster-what-is-new-7-5

See mysql-cluster-program-options-mysqld
mysql-cluster-what-is-new-7-5

See mysql-cluster-install-windows-binary faqs-mysql-cluster
See mysql-cluster-program-options-mysqld
mysql-cluster-mysqld mysql-cluster-security-mysql-privileges
See mysql-cluster-basics mysql-cluster-programs-ndb-config
See mysql-cluster-programs-ndb-restore
mysql-cluster-program-options-common
mysql-cluster-replication-preparation
mysql-cluster-config-starting ndb-restore-to-fewer-nodes
ndb-restore-to-more-nodes mysql-cluster-what-is-new-7-5

See mysql-cluster-program-options-mysqld
mysql-cluster-what-is-new-7-5

See mysql-cluster-program-options-mysqld

See mysql-cluster-program-options-mysqld

See mysql-cluster-config-starting

See mysql-cluster-config-starting

See mysql-cluster-program-options-mysqld
mysql-cluster-system-variables

See mysql-cluster-program-options-mysqld
mysql-cluster-replication-schema

See mysql-cluster-program-options-mysqld

See mysql-cluster-program-options-mysqld

See mysql-cluster-program-options-mysqld
mysql-cluster-replication-schema
mysql-cluster-system-variables

See replication-options-binary-log
mysql-cluster-program-options-mysqld
mysql-cluster-replication-conflict-resolution
mysql-cluster-system-variables

See mysql-cluster-replication-issues
mysql-cluster-replication-conflict-resolution

See mysql-cluster-program-options-mysqld

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-program-options-mysqld
mysql-cluster-program-options-common

See mysql-cluster-programs-ndb-restore

See mysql-cluster-program-options-mysqld
mysql-cluster-programs-ndb-mgmd mysql-cluster-programs-ndbd
See mysql-cluster-program-options-common
mysql-cluster-what-is-new-7-5

See mysql-cluster-program-options-common

See mysql-cluster-program-options-mysqld
mysql-cluster-system-variables

See mysql-cluster-program-options-mysqld
mysql-cluster-system-variables

See ndb-transid-mysql-connection-map-table

See mysql-cluster-program-options-mysqld

See mysql-cluster-config-starting

See mysql-cluster-program-options-mysqld

See mysql-cluster-program-options-mysqld

See mysql-cluster-program-options-mysqld optimize-table

See mysql-cluster-configuration
mysql-cluster-install-windows-binary faqs-mysql-cluster
mysql-cluster-program-options-mysqld mysql-cluster-mysqld
See mysql-cluster-security-mysql-privileges
mysql-cluster-basics mysql-cluster-ndbinfo
mysql-cluster-config-starting server-options
mysql-cluster-upgrade-downgrade

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-upgrade mysqlpump

See replication-implementation-details

See replication-implementation-details

See docker-mysql-more-topics

See using-systemd mysqld-safe

See mysql-cluster-programs-ndb-import

See mysql-command-options

See mysqldump

See mysql-command-options mysqladmin

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-setup-py

See innochecksum

See mysql-cluster-programs-ndb-waiter

See mysqldump mysqlpump

See mysqldump-definition-data-dumps mysqldump
mysqlpump

See mysqldump-definition-data-dumps mysqldump

See option-file-options my-print-defaults
myisamchk-general-options mysql-command-options
mysql-config-editor mysql-install-db mysql-plugin
See mysql-secure-installation mysql-upgrade
mysqladmin mysqlbinlog mysqlcheck mysqld-multi
See mysqld-safe mysqldump mysqlimport
mysqlpump mysqlshow mysqlslap
mysql-cluster-program-options-common server-options
problems-connecting option-files

See mysqlslap

See mysql-cluster-programs-ndb-import

See group-replication-enterprise-backup

See mysqld-multi

See mysql-cluster-programs-ndb-mgmd

See mysql-cluster-programs-ndb-restore

See mysqldump

See myisamchk-repair-options

See mysqldump

See mysql-cluster-programs-ndb-restore

See mysql-innodb-cluster-limitations mysqlsh

See mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndbd

See mysql-cluster-programs-ndb-select-all

See mysqlsh

See mysql-cluster-programs-ndb-top

See mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-restore ndb-restore-to-fewer-nodes

See mysql-cluster-programs-ndb-config

See mysql-cluster-mgm-client-commands
mysql-cluster-programs-ndbd

See mysql-cluster-programs-ndb-waiter

See mysql-cluster-online-add-node-example
mysql-cluster-ndbd-definition mysql-cluster-programs-ndb-mgmd
See mysql-cluster-programs-ndb-waiter
mysql-cluster-programs-ndbd

See mysqlslap

See mysqlslap

See mysqlslap

See resolve-stack-dump

[index top]

See comp-err source-configuration-options

See libmysqld-compiling myisamchk-repair-options
myisamlog mysql-command-options mysqlbinlog
mysqlcheck mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-top disk-issues

See mysqlbinlog

See server-options

See server-options user-resources

See linux-installation-rpm

See multiple-tables

See mysql-command-options

See mysqlslap

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See not-enough-file-handles table-cache
innodb-parameters using-systemd mysqld-safe
partitioning-limitations server-options

See too-many-connections

See mysqlpump

See optimizing-innodb-bulk-data-loading mysqldump

See option-files

See mysqlcheck

See mysql-cluster-programs-ndb-select-all

See mysqldump

See mysql-cluster-programs-ndb-top

See comp-err

See comp-err

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

[index top]

See connecting mysql-shell-connection-using-parameters
invoking-programs mysql-command-options
mysql-config-editor mysql-plugin
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlsh mysqlshow
mysqlslap mysql-cluster-programs-ndb-mgmd
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-top server-options

See mysql-cluster-online-add-node-example adding-users
connecting mysql-shell-connection-using-parameters
downgrading password-security-user innochecksum
invoking-programs partitioning-key
myisamchk-repair-options myisamlog
mysql-command-options upgrading-strategies
mysql-config-editor mysql-plugin
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlsh mysqlshow
mysqlslap mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndb-top password-too-long
default-privileges windows-start-service
windows-start-command-line windows-testing
testing-server mysql-cluster-ndbinfo-cluster-operations
mysql-cluster-ndbinfo-server-operations problems-connecting
See windows-upgrading user-names
command-line-options windows-postinstallation

See innochecksum

See innochecksum

See innochecksum

See mysql-cluster-programs-ndb-import

See mysql-commands mysql-command-options

See mysql-cluster-programs-ndb-import

See myisamchk-repair-options

See mysqlpump

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-select-all

See mysql-cluster-programs-ndb-show-tables

See server-options

See mysql-cluster-programs-ndb-top

See adding-users connecting
mysql-shell-connection-using-parameters password-security-user
See backup-strategy-example invoking-programs
mysql-command-options mysql-shell-connections
mysql-config-editor mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqld-multi mysqldump mysqlimport
See mysqlpump mysqlsh mysqlshow mysqlslap
See mysql-cluster-programs-ndb-top password-too-long
ndb-restore-to-more-nodes test-pluggable-authentication
problems-connecting user-names mysqlbinlog-backup
See command-line-options

See mysql-config-editor option-files

See mysqlsh

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options

See performance-schema-options
performance-schema-startup-configuration

See server-options

See performance-schema-status-monitoring

See performance-schema-status-monitoring

See error-log-windows using-systemd mysqld-multi
See mysqld-safe multiple-servers server-options
See server-system-variables

See mysql-server

See connecting mysql-command-options mysql-upgrade
See mysqladmin mysqlcheck mysqldump
mysqlimport mysqlshow mysqlslap
windows-testing

See server-options

See c-api-plugin-functions client-plugin-descriptors
ldap-pluggable-authentication mysql-command-options
mysql-load-plugin mysql-plugin mysql-upgrade
mysqladmin mysqlbinlog mysqlcheck mysqld-safe
See mysqldump mysqlimport mysqlpump
mysqlshow mysqlslap pluggable-authentication
pluggable-authentication-restrictions
writing-authentication-plugins-setup
using-own-protocol-trace-plugins

See mysql-plugin

See server-options

See audit-log-options-variables install-plugin
server-plugin-loading keyring-options
keyring-installation source-configuration-options
mysql-plugin plugin-api-components
plugin-data-structures server-options
server-plugin-descriptors plugin-api
writing-authentication-plugins-setup mysql-nutshell

See audit-log-options-variables
connection-control-installation server-plugin-loading
keyring-installation ldap-pluggable-authentication
mysql-plugin no-login-pluggable-authentication
pam-pluggable-authentication validate-password-installation
See validate-password-options-variables server-options
socket-pluggable-authentication test-pluggable-authentication
See thread-pool-installation mysql-nutshell
windows-pluggable-authentication

See server-options

See server-options

See source-configuration-options plugin-api-components

See linux-installation-rpm

See server-plugin-loading mysql-plugin

See mysql-config

See mysql-cluster-programs-ndb-import

See connecting mysql-shell-connection-using-parameters
invoking-programs mysql-command-options
source-configuration-options mysql-config
mysql-config-editor mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqld-safe mysqldump mysqlimport
See mysqlpump mysqlsh mysqlshow mysqlslap
See mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-top multiple-servers
multiple-unix-servers server-options
server-system-variables problems-connecting
starting-server-troubleshooting multiple-server-clients

See mysql-config-editor option-files

See server-options

See mysqlslap

See mysqlslap

See mysqlslap

See mysqlslap

See mysql-cluster-install-linux-source

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore

See option-file-options myisamchk-general-options
mysql-command-options upgrading-strategies
mysql-plugin mysql-secure-installation mysql-upgrade
See mysqladmin mysqlbinlog mysqlcheck
mysqldump mysqlimport mysqlpump mysqlshow
See mysqlslap mysql-cluster-program-options-common
server-options

See mysql-cluster-programs-ndb-mgmd

See mysql-cluster-programs-ndb-restore
mysql-cluster-what-is-new-7-5

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-restore

See mysql-commands mysql-command-options

See connecting mysql-command-options
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlshow mysqlslap
See multiple-unix-servers windows-server-first-start
windows-testing features multiple-server-clients

See mysql-shell-active-language mysqlsh

[index top]

See mysqldump

See myisamchk-repair-options mysql-command-options
mysqlcheck mysqldump mysqlslap
mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-print-file

See mysqlslap mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-config

See external-locking

See myisamchk-memory myisamchk-repair-options
mysql-command-options mysql mysqlcheck
mysqldump out-of-memory myisam-crash-recovery
option-files

See mysqldump

[index top]

See myisam-optimization myisamlog mysqlbinlog
mysqldump myisamchk-other-options mysqlbinlog-backup

See adding-udf myisam-repair binary-installation
See myisamchk-check-options myisamchk-repair-options
myisamlog mysql-command-options mysqladmin
mysqlbinlog mysqlcheck mysqldump mysqldumpslow
See mysqlimport mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-top server-options

See mysql-install-db

See mysql-install-db

See mysql-command-options mysqlbinlog
replication-gtids-failover mysqlbinlog-backup

See mysqlbinlog replication-gtids-failover

See mysqlbinlog mysqlbinlog-server-id
replication-gtids-failover mysqlbinlog-backup

See myisamchk-check-options

See mysql-cluster-ndbd-definition
mysql-cluster-programs-ndb-restore
mysql-cluster-what-is-new-7-6

See mysql-command-options

See myisamchk-check-options myisamchk-general-options
myisamchk-memory myisamchk-repair-options

See mysqlsh

See mysql-cluster-programs-ndb-import

See mysqladmin

See replication-howto-additionalslaves change-master-to
See replication-solutions-performance option-defaults-equals
See channels-naming-conventions replication-options-slave
See channels-startup-options slave-logs-relaylog

See replication-howto-additionalslaves
replication-options-slave channels-startup-options
slave-logs-relaylog

See replication-options-slave slave-logs-status

See innodb-parameters slave-logs
replication-options-slave slave-logs-status

See replication-options-slave

See replication-options-slave

See replication-features-transaction-inconsistencies
slave-logs replication-options-slave show-slave-status
See slave-logs-status server-shutdown

See replication-options-slave channels-startup-options

See mysql-cluster-online-add-node-basics
mysql-cluster-online-add-node-example
mysql-cluster-install-windows-initial-start
mysql-cluster-limitations-multiple-nodes
mysql-cluster-config-file mysql-cluster-programs-ndb-mgmd
See mysql-cluster-rolling-restart

See mysql-cluster-install-windows-service
mysql-cluster-programs-ndb-mgmd mysql-cluster-programs-ndbd
See server-options multiple-windows-services
windows-start-service

See mysqlcheck

See mysqldump mysqlimport mysqlpump

See change-replication-filter replication-rules
replication-rules-examples replication-options-slave

See replication-rules-examples replication-options-slave
See stored-program-restrictions

See replication-rules-examples

See mysql-cluster-replication-issues

See replication-options-binary-log change-replication-filter
See replication-rules-db-options replication-rules
mysql-cluster-replication-issues
replication-solutions-partitioning
replication-features-reserved-words
replication-features-temptables replication-options-slave
See show-slave-status commit binary-log
replication-rbr-usage

See change-replication-filter
replication-rules-table-options
mysql-cluster-replication-issues
replication-features-reserved-words
replication-features-functions replication-features-temptables
See replication-rules-examples replication-options-slave
See show-slave-status blackhole-storage-engine
replication-rbr-usage

See mysql-cluster-replication-issues

See replication-options-binary-log change-replication-filter
See replication-rules-db-options replication-rules
mysql-cluster-replication-issues
replication-features-reserved-words
replication-features-functions replication-rules-examples
See replication-options-slave show-slave-status
commit binary-log replication-rbr-usage

See change-replication-filter
replication-rules-table-options
mysql-cluster-replication-issues
replication-features-reserved-words
replication-features-temptables replication-options-slave
See show-slave-status blackhole-storage-engine
replication-rbr-usage

See change-replication-filter replication-rules
replication-options-slave replication-rbr-usage

See change-master-to replication-options
replication-options-slave

See change-replication-filter
replication-rules-table-options replication-rules
replication-solutions-partitioning
replication-features-temptables replication-options-slave
See stored-program-restrictions show-slave-status

See change-replication-filter
replication-rules-table-options
mysql-cluster-replication-issues faqs-replication
replication-features-temptables replication-options-slave
See show-slave-status

See replication-features-views

See replication-options-slave

See replication-administration-status
group-replication-frequently-asked-questions
replication-options-slave server-system-variables
show-slave-hosts

See replication-options-master replication-options-slave
See server-system-variables show-slave-hosts

See group-replication-frequently-asked-questions
replication-options-slave server-system-variables
show-slave-hosts

See replication-options-master replication-options-slave
See server-system-variables show-slave-hosts

See mysql-cluster-privilege-distribution
mysql-cluster-programs-ndb-restore

See mysql-cluster-programs-ndb-restore
ndb-restore-to-fewer-nodes

See mysql-cluster-replication-backups
mysql-cluster-programs-ndb-restore
mysql-cluster-replication-pitr

See mysql-cluster-programs-ndb-restore
ndb-restore-to-more-nodes mysql-cluster-what-is-new-7-5

See mysqlbinlog mysqldump mysqlpump
mysqlbinlog-backup

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-desc

See mysql-cluster-programs-ndb-restore

See mysqlbinlog mysql-nutshell

See mysqldump-stored-programs
mysqldump-definition-data-dumps upgrading-strategies
mysqldump mysqlpump mysqlbinlog-backup

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-select-all

See mysql-cluster-programs-ndb-config

See mysql-install-db

[index top]

See comp-err connecting
mysql-shell-connection-using-parameters innochecksum
invoking-programs myisam-optimization mysql-commands
See mysql-command-options mysql-config-editor
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlsh mysqlshow
mysqlslap mysql-cluster-programs-ndb-setup-py
myisamchk-other-options

See myisam-check myisam-repair innochecksum
binary-installation my-print-defaults myisam-ftdump
See myisamchk-general-options myisampack
mysql-command-options mysql-upgrade mysqladmin
mysqlbinlog mysqlcheck mysqldumpslow
mysqlimport mysqlslap
mysql-cluster-programs-ndb-perror
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-setup-py
mysql-cluster-programs-ndb-top perror replace-utility
See resolve-stack-dump resolveip server-options
See myisam-maintenance-schedule

See myisamchk-general-options myisamchk-memory
myisamchk-repair-options

See mysql-commands mysql-command-options
safe-updates

See server-options

See mysql-cluster-programs-ndb-size-pl

See mysql-shell-connection-using-parameters mysqlsh

See upgrading-from-previous-series account-upgrades
mysql-command-options mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqlimport mysqlpump
See mysqlshow mysqlslap password-hashing
server-options mysql-nutshell

See security-against-attack server-options
server-system-variables

See safe-updates

See mysql-nutshell

See mysql-nutshell

See replication-options-binary-log
mysql-cluster-replication-general mysqlbinlog
replication-options server-system-variables
show-slave-hosts replication-problems

See replication-howto-additionalslaves
binlog-replication-configuration-overview
replication-options-master replication-options-slave
replication-howto-masterbaseconfig
replication-howto-slavebaseconfig
replication-howto-existingdata

See mysql-cluster-program-options-mysqld mysqlbinlog
mysql-cluster-system-variables

See mysql-cluster-programs-ndb-setup-py

See mysql-cluster-programs-ndb-setup-py

See mysql-command-options sha256-pluggable-authentication

See mysql-server

See myisamchk-other-options

See mysqlbinlog mysqldump mysqlpump

See myisamchk-repair-options

See mysqldump mysqlpump replication-gtids-failover

See connecting mysql-command-options mysql-upgrade
See mysqladmin mysqlbinlog mysqlcheck
mysqldump mysqlimport mysqlshow server-options
See multiple-windows-command-line-servers
windows-server-first-start features

See connecting mysql-command-options mysql-options
See mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqlimport mysqlshow
See mysqlslap multiple-servers server-options
multiple-windows-command-line-servers multiple-server-clients

See mysqlbinlog

See my-print-defaults

See replication-options-master replication-options-slave
See show-slave-hosts

See mysqlshow

See mysql-cluster-programs-ndb-show-tables

See mysql-command-options mysqladmin mysqlsh

See mysql-command-options

See myisamchk-general-options myisampack
mysql-command-options mysqladmin mysqlcheck
mysqld-multi mysqlimport mysqlslap
mysql-cluster-programs-ndb-perror perror resolveip
See myisam-maintenance-schedule

See backup-methods backup-policy innodb-backup
mysqldump mysqlpump

See mysql-cluster-programs-ndb-waiter

See mysqldump option-modifiers server-options

See mysqldump

See mysqldump

See mysql-command-options innodb-troubleshooting-datadict

See mysql-cluster-programs-ndb-restore

See faqs-cjk server-options server-system-variables
See charset-cp932

See mysql-cluster-programs-ndb-top

See mysql-cluster-programs-ndb-top

See mysql-command-options

See mysql-command-options mysqldump mysql-nutshell

See server-options

See mysql-cluster-programs-ndb-mgmd

See mysqlcheck

See mysqlpump

See mysqlpump

See mysqldump

See mysqldump

See mysqlpump

See show-engines

See server-options

See mysqldump-stored-programs mysqlpump

See mysqldump

See external-locking general-thread-states
server-options server-system-variables
system-optimization crashing

See replication-solutions-diffengines

See program-options mysql-nutshell

See upgrading-from-previous-series create-function-udf
mysql-cluster-privilege-distribution events-configuration
See install-plugin server-plugin-loading mysqladmin
See pluggable-authentication resetting-permissions-generic
See server-options server-system-variables
program-options system-database problems-connecting
See udf-compiling command-line-options
mysql-nutshell privilege-changes

See mysql-cluster-programs-ndb-top

See mysqlbinlog point-in-time-recovery

See server-options server-system-variables
problems-connecting

See innodb-parameters server-plugin-loading
faqs-replication server-options innodb-turning-off
See mysql-nutshell

See innodb-parameters

See innodb-parameters

See innodb-parameters

See mysqld-safe

See mysql-command-options

See mysqldump

See host-cache group-replication-frequently-asked-questions
See mysql-install-db server-options
server-system-variables windows-testing
problems-connecting

See mysql-command-options

See mysql-cluster-program-options-mysqld
mysql-cluster-option-tables

See can-not-connect-to-server host-cache gone-away
See pluggable-authentication resetting-permissions-generic
See server-options server-system-variables
x-plugin-monitoring-status-variables
mysql-cluster-ndbinfo-processes problems-connecting
replication-upgrade

See faqs-replication replication-howto-masterbaseconfig
See replication-problems

See debugging-server optimize-table
server-system-variables

See mysql-cluster-programs-ndb-error-reporter

See mysqldump

See mysql-command-options

See partitioning server-options

See server-options

See server-plugin-loading

See mysqldump

See mysqldump

See mysql-install-db

See c-api-auto-reconnect mysql-reconnect
mysql-command-options

See mysqldump-stored-programs mysqlpump

See upgrading-from-previous-series mysql-command-options
See mysqladmin mysqlbinlog mysqlcheck
mysqldump mysqlimport mysqlpump mysqlshow
See mysqlslap server-options mysql-nutshell

See mysqldump mysqlpump

See privileges-provided server-options
show-databases supporters

See change-master-to mysql-cluster-replication-backups
mysql-cluster-replication-preparation
replication-options-slave
replication-solutions-encrypted-connections
replication-gtids-howto replication-howto-existingdata
start-slave mysql-cluster-replication-starting
channels-startup-options replication-problems
replication-upgrade

See mysql-cluster-programs-ndb-top

See encrypted-connection-options encrypted-connections
mysql-nutshell

See using-gdb-on-mysqld server-options

See large-page-support server-options

See create-table security-against-attack
server-options server-system-variables
symbolic-links-to-tables

See sys-schema mysql-install-db mysql-upgrade

See error-log-syslog mysqld-safe

See mysql-cluster-programs-ndb-restore

See mysqldump-stored-programs mysqldump mysqlpump

See mysqldump mysqlpump

See mysql-cluster-programs-ndb-restore

See mysql-upgrade

See mysql-config-editor

See mysqlpump

See mysqlcheck migrating-to-year4

See command-line-options

See replication-options-slave channels-startup-options

See replication-options-slave

See replication-solutions-backups-rawdata backup-methods
See replication-options-slave temporary-files

See replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-options-slave channels-startup-options

See replication-options-slave

See replication-options-slave

See replication-options-slave

See channels-startup-options

See mysql-cluster-replication-failover
replication-options-slave replication-features-slaveerrors

See replication-options-binary-log replication-options-slave

See replication-options-slave

See channels-startup-options

See mysqladmin

See mysql-cluster-programs-ndb-top

See server-options

See server-options

See log-destinations server-options
server-system-variables slow-query-log

See multiple-servers slow-query-log

See can-not-connect-to-server connecting
mysql-shell-connection-using-parameters
deploy-mysql-nonlinux-docker problems-with-mysql-sock
invoking-programs mysql-command-options
source-configuration-options mysql-config
mysql-config-editor mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqld-safe mysqldump mysqlimport
See mysqlpump mysqlsh mysqlshow mysqlslap
See multiple-servers multiple-unix-servers
server-options server-plugin-descriptors
windows-testing problems-connecting
multiple-server-clients

See mysql-config-editor option-files

See mysql-cluster-programs-ndb-top

See myisam-optimization myisamchk-other-options

See myisam-optimization myisamchk-other-options

See myisamchk-general-options myisamchk-memory
myisamchk-repair-options

See server-options

See replication-options-binary-log

See mysql-shell-active-language mysqlsh

See functions faqs-sql-modes mysqlslap
server-options sql-mode

See sql-mode

See mysql-shell-sessions-introduction mysqlsh

See mysql-shell-sessions-introduction mysqlsh

See mysql-install-db

See change-master-to encrypted-connection-options
using-encrypted-connections connecting
creating-ssl-rsa-files-using-mysql mysql-command-options
mysql-secure-installation mysql-ssl-rsa-setup
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqlimport mysqlpump
See mysqlsh mysqlshow mysqlslap
server-options server-system-variables
encrypted-connections mysql-shell-encrypted-connections
mysql-nutshell

See connecting mysql-command-options
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqldump
mysqlimport mysqlpump mysqlsh mysqlshow
mysqlslap server-options

See alter-user encrypted-connection-options
using-encrypted-connections create-user
creating-ssl-files-using-openssl mysql-ssl-rsa-setup
mysqlsh replication-solutions-encrypted-connections
encrypted-connections mysql-shell-encrypted-connections

See encrypted-connection-options using-encrypted-connections
See mysqlsh ssl-libraries
replication-solutions-encrypted-connections
mysql-shell-encrypted-connections

See alter-user encrypted-connection-options
using-encrypted-connections create-user
creating-ssl-files-using-openssl mysql-ssl-rsa-setup
mysqlsh replication-solutions-encrypted-connections
encrypted-connections mysql-shell-encrypted-connections

See encrypted-connection-options using-encrypted-connections
See encrypted-connection-protocols-ciphers
mysql-ssl-rsa-setup mysqlsh ssl-libraries
mysql-shell-encrypted-connections

See encrypted-connection-options mysqlsh
ssl-libraries mysql-shell-encrypted-connections

See encrypted-connection-options mysqlsh
ssl-libraries mysql-shell-encrypted-connections

See alter-user encrypted-connection-options
using-encrypted-connections create-user
creating-ssl-files-using-openssl mysql-ssl-rsa-setup
mysqlsh replication-solutions-encrypted-connections
encrypted-connections mysql-shell-encrypted-connections

See alter-user encrypted-connection-options
using-encrypted-connections create-user mysql-options
See mysqlsh load-data-local encrypted-connections
See mysql-shell-encrypted-connections mysql-nutshell

See encrypted-connection-options encrypted-connections
mysql-nutshell

See building-with-encrypted-connection-support
encrypted-connection-options using-encrypted-connections
server-system-variables encrypted-connections

See mysql-cluster-programs-ndb-move-data

See making-trace-files server-options
windows-start-command-line

See mysqlbinlog point-in-time-recovery-times

See innochecksum

See mysqlbinlog point-in-time-recovery-positions

See mysql-cluster-programs-ndb-import

See comp-err

See c-api-building-clients-pkg-config

See myisam-ftdump

See mysqlshow

See mysqlbinlog point-in-time-recovery-times

See mysqlbinlog mysqlbinlog-server-id
mysqlbinlog-backup

See mysqlbinlog mysqlbinlog-server-id
mysqlbinlog-backup

See mysqlbinlog point-in-time-recovery-positions

See innochecksum

See creating-ssl-rsa-files-using-mysql mysql-ssl-rsa-setup

See large-page-support server-options

See server-options

See resolve-stack-dump

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-index-stat

See mysql-cluster-programs-ndb-index-stat

See option-files

See replication-sbr-rbr date-and-time-functions
replication-features-functions server-options
server-system-variables

See error-log-syslog using-systemd mysql-logging
See mysql-command-options environment-variables
mysqld-safe mysql-nutshell

See error-log-syslog mysqld-safe

See mysql-cluster-programs-ndb-config

[index top]

See comp-err myisamchk-check-options myisampack
See mysql-command-options mysql-upgrade mysqldump
See mysqlpump mysqlslap
mysql-cluster-programs-ndb-restore server-options

See myisamchk-repair-options myisampack
mysql-command-options mysql-upgrade mysqlbinlog
mysqldump mysqldumpslow mysqlpump mysqlshow
See mysql-cluster-programs-ndb-delete-all
mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-redo-log-reader
mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndb-top
mysql-cluster-programs-ndb-waiter server-options

See backup-types backup-methods
mysqldump-delimited-text mysqldump
mysql-cluster-programs-ndb-restore using-mysqldump

See mysql-command-options mysqlsh
mysql-cluster-programs-ndb-desc
mysql-shell-output-table-format

See mysqlcheck mysqldump

See server-options

See mysqld-multi

See mysql-commands mysql-command-options

See server-options mysql-nutshell

See mysql-cluster-programs-ndb-import

See mysql-cluster-programs-ndb-import

See myisampack

See manual-conventions

See mysql-cluster-programs-ndb-top

See using-gdb-on-mysqld

See connection-threads

See mysql-cluster-programs-ndb-waiter

See time-zone-support mysqld-safe
replication-features-timezone server-system-variables
timezone-problems

See encrypted-connection-options using-encrypted-connections
See connecting encrypted-connection-protocols-ciphers
mysql-command-options mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqlimport mysqlpump
See mysqlsh mysqlshow mysqlslap
encrypted-connections mysql-shell-encrypted-connections

See cannot-create myisamchk-memory
myisamchk-repair-options myisampack mysql-upgrade
See multiple-servers server-options
windows-start-service mysql-nutshell temporary-files

See windows-installation

See mysqlbinlog mysqlbinlog-server-id
mysqlbinlog-backup

See server-options server-system-variables
set-transaction innodb-transaction-isolation-levels
mysql-nutshell

See server-options server-system-variables
set-transaction mysql-nutshell

See mysql-cluster-programs-ndb-delete-all

See mysqldump-stored-programs mysqldump mysqlpump

See mysql-cluster-programs-ndb-mgm

See mysql-cluster-programs-ndb-select-all

See mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-show-tables

See mysqldump mysqlpump

[index top]

See myisamchk-check-options mysql-command-options

See connecting mysql-shell-connection-using-parameters
downgrading invoking-programs myisamchk-repair-options
See myisamlog mysql-command-options
upgrading-strategies mysql-config-editor
mysql-install-db mysql-secure-installation
mysql-upgrade mysqladmin mysqlbinlog
mysqlcheck mysqldump mysqlimport mysqlpump
See mysqlsh mysqlshow mysqlslap
mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-show-tables
mysql-cluster-programs-ndb-top server-options
windows-testing testing-server user-names
windows-postinstallation

See creating-ssl-rsa-files-using-mysql mysql-ssl-rsa-setup

See mysql-command-options

See myisam-table-formats myisamchk-repair-options
myisampack

See mysql-cluster-programs-ndb-desc
mysql-cluster-programs-ndb-show-tables

See mysql-cluster-programs-ndb-index-stat

See myisam-repair myisamchk-check-options
myisam-storage-engine

See mysql-upgrade mysql-cluster-replication-schema
mysql-cluster-upgrade-downgrade mysql-cluster-what-is-new-7-5

See mysql-shell-connection-using-uri
mysql-shell-connection-using-parameters mysqlsh

See mysql-cluster-programs-ndb-config
mysql-cluster-program-options-common

See mysql-secure-installation

See mysqlcheck

See mysql-cluster-install-auto-requirements
mysql-cluster-programs-ndb-setup-py

See mysqlimport

See mysql-cluster-programs-ndb-select-all

See connecting mysql-shell-connection-using-parameters
backup-strategy-example not-enough-file-handles
changing-mysql-user
data-directory-initialization-mysql-install-db
data-directory-initialization-mysqld invoking-programs
security-against-attack keyring-key-migration
mysql-logging mysql-command-options
mysql-config-editor mysql-install-db
mysql-secure-installation mysql-upgrade mysqladmin
See mysqlbinlog mysqlcheck mysqld-multi
mysqld-safe mysqldump mysqlimport mysqlpump
See mysqlsh mysqlshow mysqlslap
mysql-cluster-security-mysql-security-procedures
mysql-cluster-programs-ndb-top option-defaults-equals
resetting-permissions-unix ndb-restore-to-more-nodes
server-options socket-pluggable-authentication
starting-server test-pluggable-authentication
user-names mysqlbinlog-backup option-files

See mysql-config-editor option-files

See mysqlpump

[index top]

See comp-err innochecksum my-print-defaults
myisamchk-general-options myisamlog myisampack
mysql-command-options mysql-config-editor
mysql-install-db mysql-plugin mysql-ssl-rsa-setup
See mysqladmin mysqlbinlog mysqlcheck
mysqldump mysqlimport mysqlpump mysqlsh
mysqlshow mysqlslap mysql-cluster-programs-ndb-config
See mysql-cluster-programs-ndb-perror
mysql-cluster-program-options-common perror
replace-utility resolve-stack-dump resolveip
server-options command-line-options

See replication-options-binary-log myisam-check
innochecksum my-print-defaults myisam-ftdump
myisamchk-general-options myisamlog myisampack
mysql-command-options mysql-config-editor
mysql-install-db mysql-plugin mysql-ssl-rsa-setup
See mysqladmin mysqlbinlog-row-events mysqlbinlog
See mysqlcheck mysqldump mysqldumpslow
mysqlimport mysqlshow mysqlslap
mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-perror
mysql-cluster-programs-ndb-print-file
mysql-cluster-programs-ndbd myisamchk-table-info
perror replace-utility server-options
command-line-options keyring-okv-plugin

See validate-password-installation
validate-password-options-variables

See innodb-parameters myisamchk-general-options
mysql-command-options mysqladmin mysqlbinlog
mysqldump server-options

See c-api-building-clients-pkg-config mysql-config

See replication-sbr-rbr replication-options-binary-log
mysql-cluster-mgm-client-commands mysql-batch-commands
innochecksum my-print-defaults myisam-ftdump
myisamchk-general-options myisampack
mysql-command-options mysql-config-editor
mysql-install-db mysql-plugin mysql-ssl-rsa-setup
See mysql-upgrade mysqladmin mysqlbinlog-row-events
See mysqlbinlog mysqlcheck mysqld-multi
mysqldump mysqldumpslow mysqlimport mysqlshow
See mysqlslap mysql-cluster-programs-ndb-blob-tool
mysql-cluster-programs-ndb-import
mysql-cluster-programs-ndb-index-stat
mysql-cluster-programs-ndb-move-data
mysql-cluster-programs-ndb-perror
mysql-cluster-programs-ndb-restore mysql-cluster-programs-ndbd
See myisamchk-other-options perror server-options
See starting-server-troubleshooting replication-rbr-usage
See option-files command-line-options

See mysqlbinlog

See comp-err innochecksum my-print-defaults
myisamchk-general-options myisampack
mysql-command-options mysql-config mysql-config-editor
See mysql-install-db mysql-plugin
mysql-ssl-rsa-setup mysqladmin mysqlbinlog
mysqlcheck mysqld-multi mysqldump mysqlimport
See mysqlpump mysqlsh mysqlshow mysqlslap
See mysql-cluster-programs-ndb-config
mysql-cluster-programs-ndb-perror
mysql-cluster-program-options-common perror
resolve-stack-dump resolveip server-options
command-line-options

See mysql-upgrade

See bug-reports mysql-command-options mysqladmin
See mysqlsh

[index top]

See connecting mysql-command-options mysql-upgrade
See mysqladmin mysqlcheck mysqldump
mysqlimport mysqlshow mysqlslap server-options

See innochecksum myisamchk-general-options myisamlog
See myisampack mysql-command-options
mysql-config-editor mysqladmin mysqldump
mysql-cluster-programs-ndb-waiter

See myisamchk-general-options myisampack
mysql-command-options mysqladmin

See mysql-cluster-programs-ndb-waiter

See mysql-config-editor

See mysqlpump

See mysqldump

See mysql-install-db

See source-installation source-configuration-options

See source-configuration-options

See mysql-cluster-install-linux-source
mysql-cluster-install-windows-source

See source-configuration-options

See innodb-parameters mysql-command-options
source-configuration-options show-engine

See source-configuration-options

See mysql-nutshell

See mysql-nutshell

See source-configuration-options

See source-configuration-options

See fulltext-search-mecab

See mysql-cluster-install-linux-source
mysql-cluster-install-windows-source

See mysql-cluster-install-linux-source
mysql-cluster-install-windows-source

See mysql-cluster-install-linux-source
mysql-cluster-install-windows-source
source-configuration-options

See innodb-parameters source-configuration-options

See building-with-encrypted-connection-support
source-configuration-options

See source-configuration-options

See source-configuration-options test-protocol-trace-plugin
See using-own-protocol-trace-plugins

See source-configuration-options

See innochecksum

See mysql-upgrade mysqlcheck
replication-gtids-restrictions

[index top]

See mysql-commands mysql-command-options mysqldump

See mysqldump mysqlslap
mysql-cluster-programs-ndb-select-all
mysql-cluster-programs-ndb-top

See load-xml mysql-command-options mysqldump
mysql-cluster-programs-ndb-config xml-functions

[index top]

See mysqldump

See mysqldump mysqlslap

[index top]

See mysql-cluster-programs-ndb-restore
mysql-cluster-programs-ndb-select-all

A | C | D | E | F | G | I | L | P | R | S | T | U

[index top]

See grant privileges-provided

See privileges-provided

See alter-database alter-table
partitioning-management-exchange grant
privileges-provided rename-table
table-privileges-table

See alter-function alter-procedure
stored-programs-logging create-procedure
drop-procedure grant privileges-provided
server-system-variables stored-routines-privileges

[index top]

See alter-table create-database create-table
partitioning-management-exchange grant
privileges-provided rename-table

See stored-programs-logging create-procedure grant
See faqs-stored-procs privileges-provided
server-system-variables stored-routines-privileges

See grant privileges-provided

See create-temporary-table grant privileges-provided

See adding-users alter-user assigning-passwords
See create-user drop-user grant
privileges-provided rename-user revoke
writing-authentication-plugins-server-side

See alter-view create-view grant
privileges-provided view-restrictions
table-privileges-table

[index top]

See request-access create-table delete
drop-function-udf drop-user grant
server-plugin-loading mysql-cluster-security-mysql-privileges
See privileges-provided replace merge-storage-engine
See setup-objects-table udf-compiling udf-security
See uninstall-plugin

See alter-table alter-view create-view
drop-database drop-table drop-view
enterprise-encryption-installation
partitioning-management-exchange grant
partitioning-management-range-list
performance-schema-table-characteristics privileges-provided
See rename-table host-cache-table
table-privileges-table privilege-system truncate-table

[index top]

See alter-event create-event drop-event
events-overview events-syntax grant mysqldump
See mysqlpump privileges-provided show-create-event
See show-events events-privileges

See stored-programs-security create-procedure
drop-procedure grant sys-schema-prerequisites
privileges-provided server-system-variables
stored-routines-privileges keyring-udf-usage

[index top]

See create-table mysqldump-delimited-text
enterprise-encryption-usage grant grant-tables
load-data load-xml security-against-attack
mysqldump privileges-provided select-into
server-system-variables string-functions blob
problems-connecting

[index top]

See grant privileges-provided revoke
column-privileges-table

[index top]

See alter-table grant privileges-provided
table-privileges-table

See stored-programs-security request-access
alter-table analyze-table assigning-passwords
create-function-udf create-user create-view
enterprise-encryption-installation
partitioning-management-exchange grant insert
install-plugin server-plugin-loading optimize-table
See pluggable-storage sys-schema-prerequisites
privileges-provided rename-table repair-table
replace server-options document-store-setting-up
events-privileges column-privileges-table
table-privileges-table setup-objects-table
udf-compiling udf-security

[index top]

See flush grant lock-tables mysqldump
mysqlpump privileges-provided

[index top]

See adding-users innodb-enabling-monitors
events-configuration thread-information grant
information-schema kill security-against-attack
mysql-cluster-mysqld explain-for-connection
sys-schema-prerequisites privileges-provided
show-engine show-processlist innodb-buffer-page-table
See innodb-buffer-page-lru-table
innodb-buffer-pool-stats-table innodb-cmp-table
innodb-cmp-per-index-table innodb-cmpmem-table
innodb-ft-being-deleted-table innodb-ft-config-table
innodb-ft-default-stopword-table innodb-ft-deleted-table
innodb-ft-index-cache-table innodb-ft-index-table-table
innodb-lock-waits-table innodb-locks-table
innodb-metrics-table innodb-sys-columns-table
innodb-sys-datafiles-table innodb-sys-fields-table
innodb-sys-foreign-table innodb-sys-foreign-cols-table
innodb-sys-indexes-table innodb-sys-tables-table
innodb-sys-tablespaces-table innodb-sys-tablestats-table
innodb-sys-virtual-table innodb-temp-table-info-table
innodb-trx-table processlist-table threads-table
too-many-connections

See grant grant-tables
writing-authentication-plugins-proxy-users
ldap-pluggable-authentication pam-pluggable-authentication
See privileges-provided proxy-users
default-privileges host-cache-table
windows-pluggable-authentication

See proxy-users

[index top]

See grant privileges-provided
column-privileges-table table-privileges-table
create-table-foreign-keys

See request-access adding-users encryption-functions
See flush grant grant-tables mysql-refresh
See mysql-reload mysqldump privileges-provided
reset host-cache-table

See grant privileges-provided show-binary-logs
show-master-status show-slave-status

See replication-howto-repuser grant
privileges-provided
replication-solutions-encrypted-connections

See group-replication-user-credentials

[index top]

See stored-programs-security request-access
analyze-table checksum-table create-procedure
create-table-like create-table create-trigger
create-view delete explain grant
insert lock-tables
performance-schema-variable-table-migration mysqldump
mysqlpump mysql-cluster-security-mysql-privileges
optimize-table performance-schema-table-characteristics
sys-schema-prerequisites privileges-provided
repair-table view-restrictions server-system-variables
See show-create-user show-create-view show-grants
See events-privileges column-privileges-table
table-privileges-table merge-storage-engine
privilege-system trigger-syntax update
mysql-cluster-what-is-new-7-6

See grant privileges-provided
server-system-variables show-databases

See explain grant mysqldump mysqlpump
privileges-provided view-restrictions show-create-view
See views-table

See request-access grant grant-tables
mysql-shutdown mysqld-multi privileges-provided
replication-gtids-howto shutdown server-shutdown

See stored-programs-security account-management-sql
alter-function alter-instance alter-server
alter-user alter-view assigning-passwords
audit-log-filtering stored-programs-logging
replication-options-binary-log binlog change-master-to
See change-replication-filter charset-applications
create-event create-procedure create-server
create-trigger create-user create-view
drop-server drop-user encryption-functions
fulltext-fine-tuning replication-options-gtids grant
See innodb-tablespace-encryption kill
security-against-attack keyring-key-migration
faqs-stored-procs locale-support time-zone-support
See mysql-dump-debug-info mysqladmin mysqlbinlog
See keyring-udfs-plugin-specific privileges-provided
rename-user replication-formats
replication-mode-change-online-concepts revoke
replication-semisync-installation sql-mode
server-system-variables set-password set-sql-log-bin
See set-variable set-transaction binary-log-setting
See replication-howto replication-gtids-howto
show-binary-logs show-master-status show-processlist
See show-slave-status start-group-replication
start-slave commit stop-group-replication
stop-slave binary-log dbug-package
sys-diagnostics events-privileges
sys-ps-setup-reload-saved sys-ps-setup-save
sys-ps-trace-statement-digest sys-ps-trace-thread
sys-statement-performance-analyzer too-many-connections
audit-log-filtering-functions using-system-variables
version-tokens-usage version-tokens-components
version-tokens-reference

[index top]

See stored-programs-security create-trigger
drop-trigger grant mysqldump mysqlpump
privileges-provided show-create-trigger show-triggers
See triggers-table

[index top]

See stored-programs-security alter-user
assigning-passwords create-table create-trigger
grant insert mysql-cluster-security-mysql-privileges
See performance-schema-table-characteristics
performance-schema-runtime-configuration
performance-schema-setup-tables sys-schema-prerequisites
privileges-provided rename-user revoke
column-privileges-table table-privileges-table
merge-storage-engine setup-objects-table
trigger-syntax update
writing-authentication-plugins-server-side

See grant privileges-provided

A | D | E | H | I | M | N | O | P | R | S | T

[index top]

See date-and-time-functions date-and-time-types
using-date sql-mode datetime

See upgrading-from-previous-series function-resolution
sql-mode show-create-view views-table

See extensions-to-ansi mysql-real-escape-string-quote
mysqldump optimizer-hints identifiers sql-mode
See string-literals create-table-foreign-keys

[index top]

See sql-mode mysql-nutshell

[index top]

See precision-math-expressions faqs-sql-modes
precision-math-examples sql-mode mysql-nutshell

[index top]

See expressions operator-precedence sql-mode

[index top]

See create-procedure function-resolution
mysql-command-options sql-mode

[index top]

See date-and-time-type-overview sql-mode datetime
See mysql-nutshell

See sql-mode mysql-nutshell

See sql-mode mysql-nutshell

See sql-mode mysql-nutshell

[index top]

See grant faqs-sql-modes sql-mode
mysql-nutshell

See create-table numeric-type-attributes sql-mode
See example-auto-increment

See json-modification-functions mysql-real-escape-string
See sql-mode string-comparison-functions
string-literals json

See create-table replication-features-directory
replication-features-variables sql-mode
partitioning-subpartitions binary-log

See alter-table upgrading-from-previous-series
create-table server-plugin-loading faqs-sql-modes
See sql-mode storage-engine-setting
replication-solutions-diffengines mysql-nutshell

See sql-mode mysql-nutshell

See sql-mode mysql-nutshell

See sql-mode mysql-nutshell

See arithmetic-functions cast-functions
numeric-type-overview out-of-range-and-overflow
partitioning-limitations sql-mode

See timestamp-initialization cast-functions
create-table date-and-time-functions
date-and-time-types faqs-sql-modes using-date
sql-mode server-system-variables mysql-nutshell

See create-table date-and-time-functions
date-and-time-types faqs-sql-modes using-date
sql-mode mysql-nutshell

[index top]

See upgrading-from-previous-series counting-rows
group-by-modifiers miscellaneous-functions
faqs-sql-modes group-by-handling sql-mode
mysql-nutshell

See sql-mode mysql-nutshell

[index top]

See sql-mode string-type-overview char

See expressions operator-precedence sql-mode

See sql-mode mysql-nutshell

[index top]

See numeric-type-overview numeric-types sql-mode

[index top]

See constraint-invalid-data precision-math-expressions
faqs-sql-modes sql-mode replication-upgrade

See upgrading-from-previous-series constraint-invalid-data
See precision-math-expressions faqs-sql-modes
sql-mode replication-upgrade mysql-nutshell

[index top]

See timestamp-initialization precision-math-expressions
See load-data faqs-sql-modes sql-mode
server-system-variables

A | B | C | D | E | F | G | H | I | K | L | O | P | R | S | T | U | W |
X

[index top]

See innodb-create-index-overview

See innodb-create-index-overview

See online-ddl-partitioning

See innodb-create-index-overview

See alter-database charset-database
replication-rules-db-options replication-rules
identifier-mapping extensions-to-ansi mysqlbinlog
See mysqldump replication-options-slave
mysql-nutshell

See implicit-commit

See alter-event stored-programs-logging create-event
See events-metadata events-overview events-syntax
See information-functions replication-features-current-user
See replication-features-invoked stored-program-restrictions
See implicit-commit events-privileges events-table

See replication-features-invoked

See alter-function stored-programs-logging
implicit-commit stored-routines-syntax

See partitioning-maintenance

See innodb-tablespace-encryption faqs-tablespace-encryption

See alter-logfile-group mysql-cluster-ndbd-definition
mysql-cluster-limitations-exclusive-to-cluster
mysql-cluster-disk-data-objects files-table

See alter-procedure stored-programs-logging
implicit-commit stored-routines-syntax

See alter-database

See replication-options-gtids privileges-provided
replication-features-create-alter-drop-server implicit-commit

See mysql-cluster-online-add-node-example
alter-table-generated-columns alter-table-examples
alter-table-online-operations alter-table-partition-operations
See alter-table innodb-auto-increment-handling
replication-options-binary-log check-table
charset-column charset-conversion column-indexes
innodb-persistent-stats-auto-recalc
innodb-performance-optimizer-statistics
innodb-persistent-stats-table-configuration
index-page-merge-threshold innodb-consistent-read
innodb-memcached-txn charset-unicode-conversion
converting-tables-to-innodb create-index
create-table-statement-retention create-table
create-tablespace creating-tables
innodb-compression-usage tablespace-placing
using-innodb-tables creating-spatial-columns
creating-spatial-indexes mysql-cluster-ndbd-definition
innodb-file-defragmenting drop-index
innodb-file-format-enabling innodb-analyze-table-complexity
See partitioning-management-exchange explain-output
federated-usagenotes fulltext-fine-tuning
forcing-innodb-recovery constraint-foreign-key
fulltext-search general-thread-states grant
innodb-compression-internals full-disk
query-cache-operation myisam-repair
information-functions mysql-cluster-install-configuration
See innodb-foreign-key-constraints index-statistics
innodb-multiple-tablespaces innodb-fulltext-index
general-tablespaces innodb-performance-schema
innodb-page-compression innodb-parameters
innodb-table-compression innodb-tablespace-encryption
mysql-cluster-limitations-exclusive-to-cluster kill
bugs mysql-cluster-limitations-multiple-nodes
mysql-cluster-limitations-limits table-size-limit
mysql-cluster-limitations-transactions lock-tables
partitioning-maintenance partitioning-management-hash-key
See partitioning-management-range-list fulltext-search-mecab
See merge-table-problems
monitor-alter-table-performance-schema innodb-migration
myisam-start myisam-table-formats
myisamchk-general-options faqs-mysql-cluster
extensions-to-ansi glossary
mysql-cluster-program-options-mysqld mysql-info
mysqldump mysqlpump mysql-cluster-config-example
mysql-cluster-disk-data-objects
mysql-cluster-install-example-data
mysql-cluster-replication-schema
mysql-cluster-system-variables mysql-cluster-programs-ndb-desc
See mysql-cluster-programs-ndb-restore fulltext-search-ngram
See mysql-cluster-limitations-syntax
innodb-create-index-recovery online-ddl-partitioning
innodb-create-index-implementation
innodb-create-index-limitations innodb-create-index-overview
See innodb-create-index-concurrency innodb-online-ddl-syntax
See optimize-table data-size
out-of-range-and-overflow partitioning-overview
innodb-compression-background partitioning-management
partitioning-limitations-locking
partitioning-limitations-partitioning-keys-unique-keys
partitioning-limitations-storage-engines
performance-schema-stage-tables privileges-provided
alter-table-problems partitioning-columns-range
partitioning-range rebuilding-tables rename-table
See replication-features-auto-increment
replication-features-reserved-words
replication-features-more-columns partitioning-limitations
See view-restrictions log-destinations
server-options error-messages-server sql-mode
server-system-variables create-table-ndb-table-comment-options
See binary-log-setting storage-engine-setting
show-engine show-index show-warnings
silent-column-changes innodb-online-ddl-single-multi
innodb-row-format-specification
innodb-compression-syntax-warnings implicit-commit
string-type-overview charset-table
temporary-table-problems ddl-log
innodb-sys-tables-table innodb-sys-tablespaces-table
partitions-table memory-storage-engine
myisam-storage-engine slow-query-log
innodb-troubleshooting-datadict
mysql-cluster-limitations-unsupported example-auto-increment
See create-table-foreign-keys
replication-solutions-diffengines symbolic-links-to-tables
See innodb-file-format-compatibility mysql-nutshell
mysql-cluster-what-is-new-7-5 crashing temporary-files
See migrating-to-year4

See alter-table create-table-foreign-keys

See alter-table-partition-operations general-tablespaces
See partitioning-management-range-list

See alter-table innodb-create-index-limitations
create-table-foreign-keys

See alter-table innodb-create-index-limitations
create-table-foreign-keys mysql-nutshell

See mysql-cluster-what-is-new-7-5

See mysql-cluster-online-add-node-basics
mysql-cluster-online-add-node-example

See innodb-page-compression

See innodb-page-compression

See tablespace-copying
innodb-transportable-tablespace-examples

See tablespace-copying create-tablespace
general-tablespaces glossary
innodb-transportable-tablespace-internals

See alter-table create-table-foreign-keys

See replication-features-partitioning

See innodb-tablespace-encryption

See alter-instance innodb-tablespace-encryption

See server-system-variables

See replication-features-memory

See mysql-cluster-privilege-distribution

See server-system-variables

See mysql-cluster-replication-schema
mysql-cluster-upgrade-downgrade mysql-nutshell
mysql-cluster-what-is-new-7-5

See mysql-cluster-programs-ndb-import

See alter-table-partition-operations
partitioning-management-exchange
partitioning-limitations-locking mysql-nutshell

See optimize-table mysql-nutshell

See tablespace-copying
innodb-transportable-tablespace-examples

See tablespace-copying innodb-migration glossary
See innodb-transportable-tablespace-examples
innodb-transportable-tablespace-internals

See partitioning-maintenance
partitioning-limitations-storage-engines

See partitioning-limitations-partitioning-keys-unique-keys

See partitioning-management-range-list
partitioning-limitations

See symbolic-links-to-tables

See mysql-cluster-online-add-node-example
mysql-cluster-online-add-node-remarks
mysql-cluster-mgm-client-commands create-table

See partitioning-management-exchange
partitioning-maintenance

See create-tablespace tablespace-enabling
innodb-multiple-tablespaces

See innodb-parameters

See partitioning-maintenance partitioning-management
partitioning-limitations-locking

See partitioning-maintenance

See mysql-upgrade mysql-nutshell

See tablespace-copying create-tablespace
general-tablespaces

See partitioning-management-exchange

See mysql-cluster-replication-issues

See delete

See general-tablespaces

See ddl-log

See innodb-benchmarking

See mysql-cluster-online-add-node-example

See upgrading-from-previous-series

See innodb-tablespace-encryption

See faqs-tablespace-encryption

See alter-table innodb-file-defragmenting

See alter-table innodb-file-defragmenting

See create-tablespace innodb-general-tablespace-intro
general-tablespaces glossary mysql-nutshell

See alter-tablespace create-tablespace
mysql-cluster-ndbd-definition drop-tablespace
mysql-cluster-limitations-exclusive-to-cluster
mysql-cluster-disk-data-objects files-table

See create-tablespace

See drop-tablespace

See create-tablespace

See server-system-variables

See connection-access alter-user assigning-passwords
See encrypted-connection-options password-security-user
See grant grant-tables security-against-attack
account-upgrades mysql-upgrade
expired-password-handling password-management
validate-password-options-variables privileges-provided
proxy-users resetting-permissions-generic
resetting-permissions-unix resetting-permissions-windows
default-privileges server-system-variables
set-password user-resources implicit-commit
validate-password plugin-types account-locking
mysql-nutshell

See error-messages-server

See error-messages-server

See alter-view information-functions
replication-features-current-user stored-program-restrictions
See implicit-commit view-algorithms view-syntax

See online-ddl-partitioning

See alter-table analyze-table
innodb-persistent-stats-auto-recalc
innodb-statistics-estimation
innodb-performance-optimizer-statistics
innodb-persistent-stats-table-configuration
innodb-persistent-stats-pages-sampled create-index
create-table innodb-analyze-table-complexity
explain-output explain fulltext-fine-tuning
general-thread-states replication-options-gtids
innodb-persistent-stats-delete-marked index-statistics
innodb-persistent-stats-tables
innodb-persistent-stats-tables-example innodb-parameters
innodb-restrictions partitioning-maintenance
merge-table-problems myisam-table-maintenance
myisamchk-general-options extensions-to-ansi glossary
See mysqlcheck mysql-cluster-programs-ndb-index-stat
optimizing-queries-myisam using-explain
select-optimization privileges-provided
range-optimization replication-features-flush
partitioning-limitations server-options
server-system-variables show-index implicit-commit
See slow-query-log

[index top]

See innodb-autocommit-commit-rollback begin-end
stored-programs-logging innodb-error-handling
innodb-parameters
mysql-cluster-replication-conflict-resolution
performance-schema-transaction-tables
replication-features-transactions replication-options-slave
See stored-program-restrictions server-system-variables
See implicit-commit events-transactions-current-table

See begin-end case sql-syntax-compound-statements
See create-trigger close fetch
declare-handler declare stored-programs-defining
events-overview leave declare-local-variable
local-variable-scope stored-program-restrictions
handler-scope commit statement-labels
implicit-commit trigger-syntax

See binlog mysqlbinlog-row-events mysqlbinlog
privileges-provided

[index top]

See cache-index replication-options-gtids
index-preloading load-index multiple-key-caches
partitioning-limitations implicit-commit

See stored-programs-security stored-programs-logging
c-api-data-structures c-api-multiple-queries
c-api-prepared-call-statements
c-api-prepared-statement-problems call
create-procedure mysql-affected-rows mysql-insert-id
See mysql-more-results mysql-next-result
mysql-real-connect mysql-set-server-option
mysql-stmt-next-result sql-syntax-prepared-statements
stored-programs-views stored-routines-syntax
trigger-syntax

See resignal-with-condition

See partitioning-limitations-locking

See statement-caching case control-flow-functions
See flow-control-statements

See replication-multi-source-adding-binlog-master
replication-multi-source-adding-gtid-master
assigning-passwords replication-solutions-backups-rawdata
See binlog-replication-configuration-overview
change-master-to replication-administration-status
channels-commands-single-channel
channels-with-prev-replication replication-howto-mysqldump
See replication-delayed
group-replication-frequently-asked-questions
replication-options-gtids grant
replication-gtids-concepts mysql-cluster-replication-failover
See mysqldump mysql-cluster-replication-backups
mysql-cluster-replication-multi-master
performance-schema-replication-tables
mysql-cluster-replication-preparation privileges-provided
See replication-options replication-features-shutdowns
replication-features-transaction-inconsistencies
slave-connection-thread-states slave-io-thread-states
replication-options-slave slave-sql-thread-states
reset-slave server-status-variables
replication-howto-slaveinit replication-howto-newservers
replication-solutions-encrypted-connections
replication-gtids-howto replication-howto-existingdata
show-slave-status slave-logs-status start-slave
implicit-commit replication-solutions-switch
innodb-memcached-replication
replication-applier-configuration-table
replication-connection-configuration-table
replication-rbr-usage group-replication-user-credentials
replication-gtids-failover mysql-nutshell

See change-replication-filter privileges-provided
server-status-variables

See replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-options-slave

See online-ddl-partitioning

See alter-table-partition-operations
upgrading-from-previous-series check-table
corrupted-myisam-tables create-procedure create-view
See external-locking replication-options-gtids
myisam-repair bug-reports innochecksum
innodb-recovery innodb-troubleshooting
partitioning-maintenance myisam-table-maintenance
myisamchk faqs-views extensions-to-ansi
gone-away mysql-store-result mysql-upgrade
mysql-use-result mysqlcheck myisam-table-close
rebuilding-tables partitioning-limitations
cursor-restrictions stored-program-restrictions
view-restrictions log-destinations server-options
See server-system-variables myisam-maintenance-schedule
See implicit-commit archive-storage-engine
merge-storage-engine slow-query-log migrating-to-year4

See check-table

See upgrading-from-previous-series check-table
repair-table

See check-table

See checksum-table create-table
replication-features-checksum-table

See checksum-table

See online-ddl-partitioning

See innodb-autocommit-commit-rollback
stored-programs-logging optimizing-innodb-bulk-data-loading
See converting-tables-to-innodb create-procedure
mysql-acid innodb-error-handling innodb-parameters
See innodb-restrictions mysqldump
mysql-cluster-system-variables replication-howto-masterstatus
See innodb-performance-ro-txn
performance-schema-transaction-tables
replication-features-transactions replication-options-slave
See rewriter-query-rewrite-plugin-routines savepoint
server-status-variables server-system-variables commit
See implicit-commit binary-log
events-transactions-current-table tables-table
sql-syntax-transactions trigger-syntax
replication-gtids-failover

See performance-schema-transaction-tables

See innodb-tablespace-encryption

See backup-types c-api-function-overview
charset-applications mysqldump-copying-to-other-server
create-database charset-database mysqldump-sql-format
See replication-rules-db-options replication-rules
identifier-case-sensitivity
mysql-cluster-limitations-exclusive-to-cluster
extensions-to-ansi mysql-create-db mysqlbinlog
mysqldump mysqlpump mysql-cluster-replication-backups
See performance-schema-instrument-naming
reloading-sql-format-dumps replication-options-slave
charset-server error-messages-server
show-create-database implicit-commit

See replication-rules

See replication-features-create-if-not-exists

See alter-event stored-programs-logging create-event
See events-metadata events-syntax
information-functions mysqldump mysqlpump
replication-features-current-user replication-features-invoked
See stored-program-restrictions show-create-event
implicit-commit events-privileges events-table

See replication-features-create-if-not-exists

See optimizing-innodb-bulk-data-loading

See adding-functions alter-function
stored-programs-logging contributors create-function
See create-function-udf create-procedure
drop-function-udf enterprise-encryption-installation
function-resolution information-functions
keyring-udf-installation locking-service-udf-installation
See version-tokens-installation upgrading-strategies
mysqldump mysqlpump replication-features-current-user
See replication-features-invoked stored-program-restrictions
See implicit-commit stored-routines-syntax
udf-calling udf-compiling udf-security

See alter-table-online-operations column-indexes
index-page-merge-threshold innodb-memcached-txn
create-index create-table creating-spatial-indexes
See fulltext-search innodb-compression-internals
innodb-fulltext-index innodb-parameters
fulltext-search-mecab glossary fulltext-search-ngram
See innodb-create-index-recovery
innodb-create-index-overview innodb-create-index-concurrency
See optimizing-memory-tables server-options
error-messages-server server-system-variables
show-index implicit-commit slow-query-log
mysql-cluster-limitations-unsupported

See alter-logfile-group create-logfile-group
create-tablespace mysql-cluster-ndbd-definition
mysql-cluster-limitations-exclusive-to-cluster mysqldump
mysql-cluster-disk-data-objects files-table
mysql-cluster-ndbinfo-resources

See create-view view-restrictions

See alter-procedure stored-programs-logging call
See create-procedure information-functions mysqldump
See mysqlpump replication-features-current-user
replication-features-invoked stored-program-restrictions
implicit-commit stored-routines-syntax

See create-database
mysql-cluster-limitations-exclusive-to-cluster
mysql-cluster-replication-backups

See alter-server federated-create-server
federated-usagenotes flush replication-options-gtids
See memory-use federated-create privileges-provided
See replication-features-create-alter-drop-server
implicit-commit

See alter-table-examples alter-table-online-operations
alter-table-partition-operations alter-table
storage-engines innodb-auto-increment-handling
backup-types innodb-best-practices
replication-options-binary-log upgrading-from-previous-series
See charset-column column-indexes
innodb-persistent-stats-auto-recalc
innodb-performance-optimizer-statistics
innodb-persistent-stats-table-configuration
index-page-merge-threshold converting-tables-to-innodb
create-event create-index create-server
create-table-like create-table-select
create-table-generated-columns
create-table-statement-retention create-table
create-tablespace create-temporary-table
federated-create-connection creating-tables
innodb-compression-usage tablespace-placing
using-innodb-tables creating-spatial-columns
creating-spatial-indexes backup-methods
charset-database mysql-cluster-ndbd-definition
mysqldump-delimited-text innodb-file-format-enabling
innodb-analyze-table-complexity constraint-foreign-key
fulltext-search getting-information
replication-gtids-concepts partitioning-hash help
See innodb-compression-internals partitioning-handling-nulls
See memory-use identifier-case-sensitivity
information-functions mysql-cluster-install-configuration
See innodb-foreign-key-constraints
innodb-and-mysql-replication innodb-fulltext-index
general-tablespaces innodb-information-schema-system-tables
See innodb-page-compression innodb-parameters
innodb-table-compression innodb-tablespace-encryption
innodb-troubleshooting internal-temporary-tables
innodb-introduction
mysql-cluster-limitations-exclusive-to-cluster
partitioning-key table-size-limit
mysql-cluster-limitations-transactions partitioning-list
load-xml loading-tables binary-log-mysql-database
See partitioning-management-range-list fulltext-search-mecab
See myisam-table-formats faqs-mysql-cluster
extensions-to-ansi glossary mysql-command-options
See mysqldump mysqlpump
mysql-cluster-ndb-api-statistics mysql-cluster-config-example
See mysql-cluster-disk-data-objects
mysql-cluster-system-variables
mysql-cluster-programs-ndb-blob-tool
mysql-cluster-programs-ndb-desc fulltext-search-ngram
mysql-cluster-limitations-syntax innodb-create-index-overview
See data-size optimizing-innodb-ddl-operations
partitioning-overview innodb-compression-background
partitioning-management
partitioning-limitations-partitioning-keys-unique-keys
partitioning-limitations-functions
partitioning-limitations-storage-engines partitioning-types
See privileges-provided partitioning-columns-range
partitioning-range reloading-delimited-text-dumps
replace replication-features-auto-increment
replication-features-charset replication-features-directory
See replication-features-fractional-seconds
replication-features-functions
replication-features-create-select
replication-features-more-columns partitioning-limitations
See log-destinations server-options
error-messages-server sql-mode server-system-variables
See binary-log-setting storage-engine-setting
show-columns show-create-table show-engine
show-index show-table-status show-warnings
silent-column-changes error-sources
innodb-row-format-specification
innodb-compression-syntax-warnings implicit-commit
string-type-overview partitioning-subpartitions
charset-table lock-tables-restrictions
innodb-benchmarking archive-storage-engine enum
innodb-sys-tables-table innodb-sys-tablespaces-table
partitions-table memory-storage-engine
myisam-storage-engine scalar-subqueries
innodb-troubleshooting-datadict truncate-table
uninstall-plugin mysql-cluster-limitations-unsupported
example-auto-increment create-table-foreign-keys
multiple-tables using-mysqldump
replication-solutions-diffengines symbolic-links
symbolic-links-to-tables mysql-nutshell
mysql-cluster-what-is-new-7-5 limits-windows

See innodb-tablespace-encryption

See alter-instance

See create-table-like create-table-generated-columns
replication-features-auto-increment lock-tables-restrictions
See merge-storage-engine

See replication-sbr-rbr stored-programs-logging
cast-functions innodb-consistent-read
create-table-select create-table-generated-columns
replication-options-gtids bugs
binary-log-mysql-database replication-compatibility
replication-features-create-select
replication-gtids-restrictions ansi-diff-select-into-table
See select sql-mode implicit-commit

See innodb-locks-set partitioning-management-range-list

See alter-table create-tablespace tablespace-placing
See using-innodb-tables tablespace-enabling
innodb-multiple-tablespaces

See replication-features-create-if-not-exists

See replication-features-create-if-not-exists

See replication-features-create-if-not-exists

See mysql-cluster-programs-ndb-import

See create-table-select select

See create-tablespace innodb-general-tablespace-intro
general-tablespaces glossary mysql-nutshell

See select-optimization

See alter-tablespace tablespace-copying create-table
See create-tablespace mysql-cluster-ndbd-definition
drop-tablespace innodb-file-space
innodb-general-tablespace-intro general-tablespaces
mysql-cluster-limitations-exclusive-to-cluster glossary
mysqldump mysql-cluster-disk-data-objects
server-system-variables files-table
innodb-sys-tables-table innodb-sys-tablespaces-table
mysql-nutshell

See replication-options-gtids grant
faqs-mysql-cluster mysqlbinlog point-in-time-recovery
See privileges-provided replication-gtids-restrictions
server-system-variables storage-engine-setting
implicit-commit temporary-table-problems

See stored-programs-logging create-trigger
information-functions faqs-triggers mysqldump
subquery-optimization-with-exists
replication-features-current-user replication-features-invoked
See stored-program-restrictions show-create-trigger
implicit-commit trigger-syntax

See adding-users assigning-passwords
encrypted-connection-options using-encrypted-connections
ipv6-local-connections create-user
replication-howto-repuser encryption-functions
password-security-user flush grant
grant-tables memory-use
writing-authentication-plugins-proxy-users
data-directory-initialization-mysqld ipv6-support
ldap-pluggable-authentication binary-log-mysql-database
security-against-attack mysqlpump
mysql-cluster-security-mysql-privileges
no-login-pluggable-authentication pam-pluggable-authentication
See password-hashing password-management
password-logging privileges-provided
mysql-install-db-problems proxy-users server-options
See sql-mode server-system-variables user-resources
See sha256-pluggable-authentication show-create-user
account-names implicit-commit privilege-system
validate-password plugin-types account-locking
user-names encrypted-connections firewall-usage
mysql-nutshell windows-pluggable-authentication

See error-messages-server

See alter-view create-view general-thread-states
See information-functions partitioning-limitations-locking
See privileges-provided replication-features-current-user
See view-restrictions identifiers show-create-view
See implicit-commit lock-tables-restrictions
views-table view-updatability view-algorithms
view-syntax

[index top]

See deallocate-prepare prepare
sql-syntax-prepared-statements stored-program-restrictions
See server-status-variables
prepared-statements-instances-table

See create-procedure declare get-diagnostics
signal stored-program-variables

See condition-handling declare-condition
declare-handler signal

See condition-handling declare-condition
declare-handler signal-effects

See innodb-memcached-dml adding-users
replication-sbr-rbr alter-table-partition-operations
audit-log-routines innodb-best-practices
replication-options-binary-log
optimizing-myisam-bulk-data-loading c-api-function-overview
See c-api-prepared-statement-function-overview
innodb-insert-buffering downgrading-to-previous-series
upgrading-from-previous-series
innodb-performance-compression-oltp
innodb-performance-change_buffering innodb-consistent-read
See converting-tables-to-innodb create-procedure
create-trigger create-view delete
deleting-from-related-tables explain-output explain
See explain-extended federated-usagenotes
forcing-innodb-recovery fulltext-restrictions
functions general-thread-states grant
grant-tables query-cache-operation
information-functions information-schema
innodb-and-mysql-replication innodb-parameters
internal-locking join keywords kill
bugs mysql-cluster-limitations-limits
mysql-cluster-limitations-transactions partitioning-list
innodb-locks-set binary-log-mysql-database
partitioning-management-range-list merge-table-problems
extensions-to-ansi glossary mysql-command-options
See mysql-affected-rows mysql-num-rows
mysql-stmt-execute mysql-stmt-field-count
mysql-stmt-num-rows mysqldump
mysql-cluster-security-mysql-security-procedures
mysql-cluster-disk-data-objects
mysql-cluster-programs-ndb-delete-all explain-for-connection
See innodb-create-index-overview optimizer-hints
data-change-optimization using-explain
select-optimization subquery-optimization
partitioning-overview partitioning-pruning
partitioning-selection mysql-cluster-rolling-restart
privileges-provided query-cache-thread-states
partitioning-range replication-features-limit
replication-features-memory replication-features-optimizer
See replication-features-triggers replication-options-slave
See rewriting-subqueries selecting-all
log-destinations server-options sql-mode
server-status-variables server-system-variables
dba-dtrace-ref-statement subquery-errors subqueries
See table-locking archive-storage-engine binary-log
See blackhole-storage-engine innodb-sys-tablestats-table
See tables-table views-table features
memory-storage-engine merge-storage-engine
privilege-system innodb-transaction-isolation-levels
trigger-syntax problems-connecting truncate-table
See view-updatability replication-rbr-usage
audit-log-filtering-functions create-table-foreign-keys
safe-updates mysql-nutshell query-results
privilege-changes where-optimization
null-mysql-store-result audit-log-filter-definitions

See innodb-locks-set

See replication-options-slave

See dba-dtrace-ref-statement

See c-api-data-structures c-api-function-overview
create-table-statement-retention creating-tables
describe explain extended-show
getting-information internal-temporary-tables
mysql-stmt-store-result mysql-store-result
mysql-use-result show-columns silent-column-changes
See innodb-buffer-page-table innodb-buffer-page-lru-table
See innodb-buffer-pool-stats-table innodb-cmp-table
innodb-cmp-per-index-table innodb-cmpmem-table
innodb-ft-being-deleted-table innodb-ft-config-table
innodb-ft-default-stopword-table innodb-ft-deleted-table
innodb-ft-index-cache-table innodb-ft-index-table-table
innodb-lock-waits-table innodb-locks-table
innodb-metrics-table innodb-sys-columns-table
innodb-sys-datafiles-table innodb-sys-fields-table
innodb-sys-foreign-table innodb-sys-foreign-cols-table
innodb-sys-indexes-table innodb-sys-tables-table
innodb-sys-tablespaces-table innodb-sys-tablestats-table
innodb-sys-virtual-table innodb-temp-table-info-table
innodb-trx-table example-foreign-keys charset-metadata

See online-ddl-partitioning

See alter-table-partition-operations

See alter-event stored-programs-logging create-event
See do binary-log-mysql-database
miscellaneous-functions extensions-to-ansi
partitioning-limitations-locking stored-program-restrictions
See subqueries events-table

See c-api-function-overview drop-database
drop-tablespace mysqldump-sql-format
replication-rules-db-options replication-rules
query-cache-operation general-tablespaces
mysql-cluster-limitations-exclusive-to-cluster
extensions-to-ansi mysql-drop-db mysqlbinlog
mysqldump mysqlpump point-in-time-recovery
replication-options-slave implicit-commit
limits-windows

See replication-features-drop-if-exists

See stored-programs-logging events-syntax
replication-features-invoked implicit-commit
events-privileges

See adding-functions alter-function
stored-programs-logging contributors
create-function-udf drop-function drop-function-udf
See drop-procedure enterprise-encryption-installation
function-resolution keyring-udf-installation
locking-service-udf-installation version-tokens-installation
See upgrading-strategies replication-features-invoked
implicit-commit stored-routines-syntax udf-compiling
See udf-security

See alter-table-online-operations alter-table
creating-spatial-indexes drop-index extensions-to-ansi
See glossary innodb-create-index-overview
server-options server-system-variables implicit-commit
See slow-query-log

See drop-logfile-group
mysql-cluster-limitations-exclusive-to-cluster

See online-ddl-partitioning

See prepared-statements-instances-table

See alter-procedure stored-programs-logging
firewall-installation replication-features-invoked
implicit-commit stored-routines-syntax

See drop-database
mysql-cluster-limitations-exclusive-to-cluster
server-system-variables

See flush replication-options-gtids memory-use
privileges-provided
replication-features-create-alter-drop-server implicit-commit

See mysql-cluster-online-add-node-remarks alter-table
audit-log-file-formats mysql-cluster-mgm-client-commands
innodb-consistent-read create-tablespace
create-temporary-table create-trigger
tablespace-placing drop-table federated-usagenotes
See forcing-innodb-recovery replication-options-gtids
diagnostics-area-populating query-cache-operation
information-functions innodb-multiple-tablespaces
general-tablespaces innodb-parameters
mysql-cluster-limitations-exclusive-to-cluster
mysql-cluster-limitations-limits lock-tables
merge-table-problems extensions-to-ansi glossary
mysql-command-options mysqldump mysqlpump
mysql-cluster-programs-ndb-drop-index
mysql-cluster-programs-ndb-drop-table
optimizing-innodb-ddl-operations
mysql-cluster-replication-pitr privileges-provided
view-restrictions handler-scope log-destinations
server-options server-system-variables
binary-log-setting signal start-slave
implicit-commit ddl-log memory-storage-engine
merge-storage-engine innodb-troubleshooting-datadict
truncate-table plugin-types uninstall-plugin
create-table-foreign-keys mysql-nutshell

See replication-features-drop-if-exists

See mysql-cluster-privilege-distribution

See general-tablespaces
mysql-cluster-limitations-exclusive-to-cluster
server-system-variables

See general-tablespaces

See replication-options-gtids replication-gtids-restrictions

See replication-rbr-usage

See drop-trigger faqs-triggers mysqldump
replication-features-invoked implicit-commit
trigger-syntax

See drop-user flush grant memory-use
information-functions mysqlpump
mysql-cluster-security-mysql-privileges privileges-provided
See removing-users replication-features-current-user
revoke default-privileges implicit-commit
events-privileges user-names

See writing-authentication-plugins-setup

See drop-view view-restrictions implicit-commit
See lock-tables-restrictions view-syntax

See replication-features-drop-if-exists

[index top]

See innodb-tablespace-encryption

See online-ddl-partitioning

See c-api-prepared-call-statements call execute
See prepare sql-syntax-prepared-statements
stored-program-restrictions server-status-variables
prepared-statements-instances-table

See alter-table table-scan-avoidance
bnl-bka-optimization c-api-data-structures
c-api-function-overview column-indexes
innodb-persistent-stats-pages-sampled create-procedure
debugging-server derived-tables describe
distinct-optimization condition-pushdown-optimization
explain-output explain explain-extended
json-search-functions group-by-optimization
index-condition-pushdown-optimization index-hints
index-merge-optimization information-schema
internal-temporary-tables is-null-optimization
mrr-optimization performance-schema
mysql-stmt-store-result mysql-store-result
mysql-use-result mysql-cluster-status-variables
mysql-cluster-system-variables explain-for-connection
partitioning-info optimizer-hints
generated-column-index-optimizations optimizer-issues
derived-table-optimization information-schema-optimization
See using-explain select-optimization
optimizing-subqueries subquery-materialization
subquery-optimization-with-exists semi-joins
order-by-optimization privileges-provided
range-optimization stored-program-restrictions
create-table-secondary-indexes select
error-messages-server show-warnings no-matching-rows
See features sys-ps-trace-statement-digest
execution-plan-information index-extensions
using-log-files using-spatial-indexes
verifying-index-usage mysql-nutshell
mysql-cluster-what-is-new-7-5

See explain-output explain explain-extended

See explain-output explain-for-connection
server-status-variables

See explain-output explain partitioning-info

See derived-tables explain-output
innodb-deadlocks-handling bug-reports
extensions-to-ansi partitioning-info

See order-by-optimization

See partitioning-range

See using-explain

[index top]

See declare-cursor fetch stored-program-restrictions

See stored-program-variables

See backup-policy flush replication-options-gtids
See grant extensions-to-ansi mysql-refresh
mysqldump privileges-provided
replication-features-flush reset
stored-program-restrictions default-privileges
server-signal-response implicit-commit mysql-nutshell

See flush log-file-maintenance

See encryption-functions flush

See flush

See error-log-rotation flush

See flush

See host-cache flush blocked-host
mysql-refresh server-system-variables host-cache-table

See backup-strategy-summary backup-methods
replication-mode-change-online-disable-gtids
replication-mode-change-online-enable-gtids error-log-rotation
See backup-policy flush server-logs
mysql-refresh mysqladmin replication-features-flush
See log-destinations log-file-maintenance
server-status-variables replication-gtids-howto
slave-logs-relaylog replication-gtids-failover

See flush cost-model

See mysql-cluster-privilege-distribution flush
grant-tables memory-use mysql-refresh
mysql-reload mysqldump
mysql-cluster-security-mysql-security-procedures
replication-features-flush server-options
user-resources problems-connecting manual-conventions
See privilege-changes

See flush query-cache-status-and-maintenance
mysql-nutshell

See channels-commands-single-channel
channels-with-prev-replication flush

See flush

See flush

See flush mysql-refresh
performance-schema-status-variable-tables
server-status-variables server-system-variables
performance-schema-status-variable-summary-tables
index-extensions

See flush

See optimizing-myisam-bulk-data-loading statement-caching
See flush general-thread-states handler
table-cache memory-use merge-table-problems
myisamchk mysql-refresh replication-howto-masterstatus
See myisam-table-close query-cache-status-and-maintenance
See replication-features-flush partitioning-limitations
See log-destinations server-status-variables
server-system-variables index-extensions

See tablespace-placing flush innodb-migration
glossary innodb-transportable-tablespace-examples
innodb-transportable-tablespace-internals

See flush

See flush

See flush

See flush

See handler

See backup-methods backup-policy flush
general-thread-states lock-tables-and-transactions
lock-tables glossary mysqldump
replication-howto-masterstatus replication-features-flush
See xa-restrictions log-destinations
server-system-variables commit implicit-commit
metadata-locks-table

See flush user-resources

[index top]

See condition-handling get-diagnostics
diagnostics-area-populating diagnostics-area-stack
resignal condition-handling-restrictions
stored-program-restrictions server-system-variables
show-warnings signal-condition-information-items
signal error-sources

See get-diagnostics diagnostics-area-stack
mysql-nutshell

See request-access adding-users replication-sbr-rbr
See innodb-read-only-instance ipv6-local-connections
create-user replication-howto-repuser
encryption-functions flush grant grant-tables
See memory-use writing-authentication-plugins-proxy-users
See information-functions
data-directory-initialization-mysqld ipv6-support
binary-log-mysql-database faqs-replication glossary
See mysqlpump mysql-cluster-security-mysql-privileges
permission-optimization password-hashing
password-logging mysql-cluster-replication-preparation
privileges-provided mysql-install-db-problems
proxy-users replication-features-flush
replication-features-current-user replication-features-mysqldb
See revoke security-guidelines server-options
sql-mode server-system-variables show-grants
account-names implicit-commit events-privileges
privilege-system validate-password user-names
firewall-usage x-plugin-ssl-connections mysql-nutshell
See privilege-changes windows-pluggable-authentication

See grant

See events-privileges

See innodb-benefits

[index top]

See c-api-auto-reconnect federated-usagenotes flush
See faqs-stored-procs compatibility
mysql-change-user mysql-reset-connection
partitioning-limitations server-system-variables
mysql-nutshell

See show-open-tables

See show-open-tables

See stored-program-restrictions

See handler truncate-table

See help replication-features-server-side-help
server-side-help-support lock-tables-restrictions

[index top]

See statement-caching control-flow-functions
declare-handler flow-control-statements if

See online-ddl-partitioning

See alter-table-partition-operations

See request-access adding-users replication-sbr-rbr
See audit-log-routines innodb-auto-increment-handling
innodb-autocommit-commit-rollback backup-types
innodb-best-practices stored-programs-logging
optimizing-innodb-bulk-data-loading
optimizing-myisam-bulk-data-loading c-api-function-overview
See c-api-multiple-queries
c-api-prepared-statement-function-overview statement-caching
See innodb-insert-buffering downgrading-to-previous-series
See upgrading-from-previous-series charset-conversion
innodb-performance-compression-oltp concurrent-inserts
innodb-performance-change_buffering constraint-invalid-data
See converting-tables-to-innodb create-index
create-procedure create-table-generated-columns
create-temporary-table create-trigger create-view
See federated-create-connection data-type-defaults
date-and-time-type-overview declare-handler delete
See replication-rbr-safe-unsafe enterprise-encryption-usage
See backup-policy explain-output explain
precision-math-expressions explain-extended
federated-usagenotes forcing-innodb-recovery
fulltext-restrictions general-thread-states grant
See grant-tables query-cache-operation
getting-unique-id information-functions
information-schema innodb-locking innodb-parameters
See insert-on-duplicate insert-select insert-delayed
See insert internal-locking
mysql-cluster-limitations-transactions partitioning-list
load-data loading-tables lock-tables
innodb-locks-set binary-log-mysql-database
partitioning-management-range-list merge-table-problems
miscellaneous-functions faqs-general faqs-cjk
faqs-triggers faqs-views extensions-to-ansi
glossary mysql-command-options gone-away
mysql-affected-rows mysql-insert-id mysql-num-rows
See mysql-stmt-execute mysql-stmt-field-count
mysql-stmt-insert-id mysql-stmt-num-rows
mysql-stmt-prepare mysql-store-result mysqlbinlog
See mysqldump mysqlpump
mysql-cluster-ndb-api-statistics
mysql-cluster-disk-data-objects
mysql-cluster-install-example-data
mysql-cluster-replication-conflict-resolution
explain-for-connection innodb-create-index-overview
optimize-table optimizer-hints
data-change-optimization insert-optimization
optimizing-queries-myisam using-explain
out-of-range-and-overflow partitioning-overview
partitioning-pruning partitioning-selection
partitioning-limitations-locking password-logging
performance-schema-statement-tables
mysql-cluster-rolling-restart populating-spatial-columns
performance-schema-thread-filtering constraint-primary-key
See privileges-provided query-cache-thread-states
partitioning-range replace
replication-features-auto-increment
replication-features-sql-mode replication-features-functions
See replication-features-triggers
replication-features-variables replication-options-master
See replication-rules-examples partitioning-limitations
See dba-dtrace-ref-rowlevel create-table-secondary-indexes
See log-destinations server-options
error-messages-server sql-mode server-system-variables
See show-procedure-code show-warnings
replication-features-slaveerrors dba-dtrace-ref-statement
See subqueries table-locking archive-storage-engine
See charset-binary-collations binary-log
blackhole-storage-engine tables-table views-table
See features merge-storage-engine
myisam-storage-engine privilege-system query-cache
See server-shutdown trigger-syntax
problems-connecting innodb-memcached-troubleshoot
view-updatability update audit-log-filtering-functions
See create-table-foreign-keys
innodb-information-schema-examples triggers
mysql-nutshell query-results privilege-changes
null-mysql-store-result audit-log-filter-definitions
writing-audit-plugins

See dba-dtrace-ref-statement

See innodb-auto-increment-handling
replication-rbr-safe-unsafe federated-usagenotes
information-functions insert-on-duplicate insert
mysql-cluster-replication-issues innodb-locks-set
merge-table-problems miscellaneous-functions glossary
See mysql-affected-rows mysql-insert-id
partitioning-limitations-locking

See replication-sbr-rbr innodb-auto-increment-handling
concurrent-inserts insert-on-duplicate insert-select
See insert internal-temporary-tables bugs
innodb-locks-set mysql-insert-id
mysql-cluster-system-variables partitioning-selection
partitioning-limitations-locking replication-features-limit
See server-system-variables dba-dtrace-ref-statement
binary-log

See insert-on-duplicate insert-select

See insert

See insert mysql-info

See insert-delayed insert mysql-nutshell

See constraint-invalid-data constraint-enum
information-functions insert mysqldump
mysqlpump sql-mode

See insert-select

See request-access innodb-consistent-read
constraint-invalid-data create-event insert
ansi-diff-select-into-table memory-storage-engine
audit-log-filter-definitions

See mysql-info query-results

See replication-features-memory

See select-optimization

See audit-log-options-variables
connection-control-installation flush memory-use
innodb-memcached-intro install-plugin
server-plugin-loading keyring-udf-installation
version-tokens-installation keyring-installation
ldap-pluggable-authentication fulltext-search-mecab
source-configuration-options mysql-plugin
no-login-pluggable-authentication obtaining-plugin-information
See pam-pluggable-authentication
validate-password-installation
validate-password-options-variables pluggable-storage
plugin-api-components plugin-data-structures
replication-semisync-interface
replication-semisync-installation server-options
server-plugin-descriptors server-system-variables
innodb-memcached-setup show-plugins
socket-pluggable-authentication implicit-commit
test-pluggable-authentication plugins-table plugin-api
See innodb-memcached-troubleshoot uninstall-plugin
keyring-aws-plugin mysql-nutshell
windows-pluggable-authentication writing-audit-plugins
writing-daemon-plugins writing-full-text-plugins
writing-information-schema-plugins
writing-password-validation-plugins
writing-authentication-plugins-server-side

See declare-handler flow-control-statements iterate
See statement-labels

[index top]

See general-thread-states grant kill
gone-away mysql-kill privileges-provided
replication-features-transaction-inconsistencies
show-processlist stop-slave lock-tables-restrictions
See sys-innodb-lock-waits sys-schema-table-lock-waits
mysql-nutshell

See kill stop-slave server-shutdown

See kill miscellaneous-functions stop-slave
server-shutdown

[index top]

See declare-handler flow-control-statements leave
See loop stored-program-restrictions return
statement-labels

See innodb-auto-increment-handling concurrent-inserts
create-trigger charset-database bugs load-data
See load-xml loading-tables security-against-attack
See mysql-options mysql-cluster-programs-ndb-import
partitioning-overview partitioning-selection
partitioning-limitations-locking partitioning-limitations
See stored-program-restrictions load-data-local
selecting-all server-options sql-mode
server-system-variables enum user-variables
create-table-foreign-keys triggers

See audit-log-file-formats audit-log-restrictions
replication-solutions-backups-rawdata backup-types
optimizing-myisam-bulk-data-loading concurrent-inserts
backup-methods replication-rbr-safe-unsafe full-disk
See information-functions bugs
mysql-cluster-limitations-transactions load-data
binary-log-mysql-database myisam-start
extensions-to-ansi mysql-command-options
mysqlbinlog-hexdump mysqlbinlog mysqldump
mysqlimport mysql-cluster-programs-ndb-show-tables
null-values insert-optimization
out-of-range-and-overflow programs-overview
mysql-cluster-rolling-restart privileges-provided
problems-with-null reloading-delimited-text-dumps
replication-features-load-data replication-options-slave
slave-sql-thread-states charset-restrictions
select-into server-options server-system-variables
See show-warnings implicit-commit subqueries
memory-storage-engine privilege-system
scalar-subqueries problems-connecting mysql-nutshell
See mysql-cluster-what-is-new-7-6 temporary-files
limits-windows

See mysql-info query-results

See load-data source-configuration-options
mysql-options mysql-real-connect mysqlbinlog
load-data-local server-system-variables

See c-api-function-overview load-data mysql-options
See mysql-set-local-infile-default
mysql-set-local-infile-handler mysqlbinlog

See cache-index replication-options-gtids
index-preloading load-index partitioning-limitations
See implicit-commit

See load-index

See load-xml partitioning-overview
partitioning-selection sql-mode

See load-xml

See load-xml

See load-xml

See concurrent-inserts general-thread-states
alter-table-problems

See innodb-best-practices
optimizing-myisam-bulk-data-loading create-database
create-table-like create-trigger
innodb-deadlock-detection innodb-deadlocks flush
general-thread-states grant innodb-deadlocks-handling
See innodb-parameters lock-tables-and-transactions
internal-locking mysql-cluster-limitations-multiple-nodes
See innodb-restrictions lock-tables-and-triggers
lock-tables innodb-locks-set merge-table-problems
See mysqldump mysqlpump
partitioning-limitations-locking privileges-provided
myisam-table-close stored-program-restrictions
log-destinations server-system-variables commit
implicit-commit system-optimization table-locking
See lock-tables-restrictions

See flush innodb-parameters innodb-restrictions
See metadata-locking

See innodb-locking innodb-parameters
innodb-restrictions

See flow-control-statements iterate leave
loop statement-labels

[index top]

See online-ddl-partitioning

See mysql-cluster-online-add-node-basics
mysql-cluster-online-add-node-example
alter-table-online-operations debugging-server delete
See dynamic-format fulltext-fine-tuning
general-thread-states replication-options-gtids
full-disk innodb-multiple-tablespaces
innodb-information-schema-fulltext_index-tables
innodb-page-compression innodb-parameters kill
mysql-cluster-limitations-limits partitioning-maintenance
See merge-table-problems myisam-table-maintenance
myisam-optimization myisamchk-general-options
extensions-to-ansi mysql-cluster-program-options-mysqld
mysqlcheck mysql-cluster-disk-data-storage-requirements
innodb-create-index-limitations innodb-create-index-overview
See optimize-table optimizing-queries-myisam
update-optimization miscellaneous-optimization-tips
privileges-provided replication-features-flush
partitioning-limitations server-options
server-system-variables myisam-maintenance-schedule
innodb-row-format-specification implicit-commit
static-format archive-storage-engine
innodb-ft-being-deleted-table innodb-ft-config-table
innodb-ft-deleted-table innodb-ft-index-cache-table
innodb-ft-index-table-table server-shutdown
slow-query-log symbolic-links-to-tables mysql-nutshell

See innodb-benefits

[index top]

See online-ddl-partitioning

See c-api-prepared-call-statements statement-caching
call deallocate-prepare execute
identifier-case-sensitivity metadata-locking prepare
See sql-syntax-prepared-statements
stored-program-restrictions server-status-variables
prepared-statements-instances-table

See backup-policy grant mysqldump
privileges-provided purge-binary-logs reset-master
See log-file-maintenance server-system-variables
binary-log replication-gtids-failover

[index top]

See online-ddl-partitioning

See performance-schema-transaction-tables savepoint
events-transactions-current-table

See online-ddl-partitioning

See innodb-create-index-overview

See alter-table delete general-thread-states
identifier-case-sensitivity innodb-migration
extensions-to-ansi mysqldump mysqlpump
rename-table log-destinations implicit-commit
temporary-table-problems symbolic-links-to-tables

See grant information-functions
binary-log-mysql-database privileges-provided
rename-user replication-features-current-user
implicit-commit events-privileges privilege-changes

See online-ddl-partitioning

See online-ddl-partitioning

See alter-table-partition-operations alter-table
upgrading-from-previous-series check-table
corrupted-myisam-tables backup-methods
partitioning-management-exchange external-locking
fulltext-fine-tuning general-thread-states
replication-options-gtids full-disk myisam-repair
See bug-reports kill load-data
partitioning-maintenance merge-table-problems
myisam-start myisam-table-maintenance
myisamchk-general-options myisamchk extensions-to-ansi
See mysqlcheck repair-table-optimization
privileges-provided myisam-table-close
alter-table-problems rebuilding-tables repair-table
See replication-features-flush
replication-features-repair-table partitioning-limitations
See server-options server-system-variables
myisam-maintenance-schedule implicit-commit
archive-storage-engine server-shutdown slow-query-log
See symbolic-links-to-tables migrating-to-year4

See declare-handler stored-programs-defining
flow-control-statements iterate leave repeat
See statement-labels

See replication-sbr-rbr innodb-auto-increment-handling
create-table-generated-columns create-trigger
data-type-defaults explain-output explain
explain-extended information-functions insert
bugs innodb-locks-set binary-log-mysql-database
merge-table-problems extensions-to-ansi gone-away
See mysql-affected-rows mysqldump mysqlpump
explain-for-connection optimizer-hints using-explain
See partitioning-overview partitioning-selection
partitioning-limitations-locking replace
partitioning-limitations server-options subqueries
See archive-storage-engine features
mysql-cluster-ndbinfo-operations-per-fragment update
audit-log-filter-definitions

See innodb-auto-increment-handling bugs

See mysql-nutshell

See flush replication-options-gtids
extensions-to-ansi reset implicit-commit

See replication-options-gtids replication-gtids-concepts
See mysql-cluster-replication-issues mysql-refresh
reset-master show-slave-status
replication-solutions-switch binary-log
replication-applier-status-by-coordinator-table
replication-applier-status-by-worker-table
replication-connection-status-table

See query-cache-thread-states reset mysql-nutshell

See change-master-to channels-commands-single-channel
channels-with-prev-replication replication-delayed
mysql-cluster-replication-issues mysql-refresh
mysql-cluster-system-variables replication-options
replication-features-transaction-inconsistencies
replication-options-slave reset-master reset-slave
See show-slave-status start-slave implicit-commit
See replication-applier-status-by-coordinator-table
replication-applier-status-by-worker-table
replication-connection-status-table

See change-master-to reset-slave

See condition-handling declare-condition
declare-handler diagnostics-area-information-items
diagnostics-area-system-variables get-diagnostics
diagnostics-area-populating diagnostics-area-stack
resignal-alone resignal-handler resignal
resignal-with-condition resignal-with-new-signal
condition-handling-restrictions stored-program-restrictions
See handler-scope signal-condition-information-items

See statement-caching create-procedure
flow-control-statements diagnostics-area-stack loop
See stored-program-restrictions return

See replication-sbr-rbr innodb-read-only-instance
flush grant grant-tables memory-use
information-functions ipv6-support
binary-log-mysql-database faqs-replication
differences-from-ansi glossary
mysql-cluster-security-mysql-privileges privileges-provided
See mysql-install-db-problems proxy-users
replication-features-current-user replication-features-mysqldb
See revoke security-guidelines
server-system-variables implicit-commit
events-privileges privilege-system user-names
privilege-changes

See grant privileges-provided

See innodb-autocommit-commit-rollback
stored-programs-logging converting-tables-to-innodb
innodb-deadlock-detection information-functions
mysql-acid innodb-error-handling innodb-parameters
See lock-tables-and-transactions mysql-change-user
performance-schema-transaction-tables
replication-features-transactions replication-options-slave
See nontransactional-tables savepoint
server-system-variables commit cannot-roll-back
implicit-commit binary-log
events-transactions-current-table sql-syntax-transactions
See trigger-syntax

See performance-schema-transaction-tables savepoint
events-transactions-current-table

See trigger-syntax

[index top]

See performance-schema-transaction-tables savepoint
events-transactions-current-table

See group-by-functions alter-table alter-view
assignment-operators audit-log-file-formats
innodb-auto-increment-handling
innodb-autocommit-commit-rollback stored-programs-logging
See replication-options-binary-log
optimizing-myisam-bulk-data-loading c-api-data-structures
See c-api-function-overview c-api-multiple-queries
c-api-prepared-call-statements
c-api-prepared-statement-function-overview statement-caching
See upgrading-from-previous-series comparison-operators
See index-btree-hash concurrent-inserts
charset-connection innodb-consistent-read
converting-tables-to-innodb create-event create-index
See create-procedure create-table-select
create-table-generated-columns create-table
create-temporary-table create-view
federated-create-connection creating-database
declare-cursor fetch innodb-deadlock-detection
delete derived-tables creating-many-tables
host-cache do dynamic-system-variables
entering-queries enterprise-encryption-usage
events-configuration charset-collation-effect
explain-output explain explain-extended
federated-usagenotes flush forcing-innodb-recovery
See function-optimization functions
json-search-functions general-thread-states grant
See handler partitioning-handling-nulls
query-cache-operation innodb-deadlocks-handling
bug-reports index-hints information-functions
information-schema data-directory-initialization
innodb-parameters insert-on-duplicate insert-select
See insert internal-locking
internal-temporary-tables join keywords kill
See bugs audit-log-legacy-filtering
mysql-cluster-limitations-transactions load-xml
local-variable-scope innodb-locking-reads
innodb-locks-set binary-log-mysql-database
security-against-attack partitioning-management-range-list
See merge-table-problems multiple-column-indexes
myisam-optimization faqs-cjk faqs-replication
faqs-stored-procs extensions-to-ansi glossary
mysql-command-options performance-schema
mysql-affected-rows mysql-fetch-field
mysql-field-count mysql-num-fields mysql-num-rows
See mysql-stmt-execute mysql-stmt-fetch
mysql-stmt-num-rows mysql-stmt-store-result
mysql-store-result mysql-use-result mysqldump
mysqlpump mysqlslap fulltext-natural-language
mysql-cluster-disk-data-objects
mysql-cluster-install-example-data
mysql-cluster-replication-conflict-resolution
mysql-cluster-replication-schema
mysql-cluster-system-variables
mysql-cluster-programs-ndb-select-all mysql-cluster-ndbinfo
See explain-for-connection partitioning-info
optimization-indexes optimizer-hints optimizer-issues
See derived-table-optimization innodb-performance-ro-txn
See optimizing-innodb-transaction-management
optimizing-queries-myisam using-explain
select-optimization subquery-optimization-with-exists
semi-joins update-optimization myisamchk-other-options
See partitioning-pruning partitioning-selection
partitioning-limitations-locking
performance-schema-instrument-naming
performance-schema-replication-tables innodb-next-key-locking
See privileges-provided using-date
problems-with-float query-cache-in-select
query-cache-status-and-maintenance query-cache-thread-states
See mysql-cluster-sql-statements partitioning-columns-range
See range-optimization se-csv-repair replace
replication-implementation replication-options-master
replication-features-create-if-not-exists
replication-features-invoked replication-options-slave
stored-program-restrictions retrieving-data
searching-on-two-keys create-table-secondary-indexes
default-privileges select-into select
selecting-all selecting-rows error-messages-server
See sql-mode server-status-variables
server-system-variables set-variable
show-binlog-events show-create-procedure
show-create-view show-errors show-procedure-code
show-processlist show-relaylog-events show
show-variables show-warnings no-matching-rows
commit dba-dtrace-ref-statement stored-routines-syntax
See string-literals exists-and-not-exists-subqueries
subquery-errors subqueries table-locking
lock-tables-restrictions archive-storage-engine
binary-log enum host-cache-table columns-table
See events-table variables-table innodb-trx-table
See views-table json features
merge-storage-engine privilege-system query-cache
See mysql-cluster-ndbinfo-nodes
rewriter-query-rewrite-plugin scalar-subqueries
threads-table innodb-transaction-isolation-levels
trigger-syntax type-conversion plugin-types
manual-conventions union update user-variables
See innodb-information-schema-examples
mysql-innodb-cluster-using-router procedure-analyse
using-log-files using-spatial-indexes
using-system-variables safe-updates
rewriter-query-rewrite-plugin-usage charset-metadata
version-tokens-reference view-syntax mysql-nutshell
See where-optimization temporary-files
audit-log-filter-definitions

See blob

See mysql-cluster-ndbinfo-memory-per-fragment

See partitioning-overview

See backup-methods

See innodb-best-practices innodb-deadlocks
innodb-deadlocks-handling innodb-locking
innodb-locking-reads innodb-locks-set

See innodb-locks-set

See innodb-locks-set

See innodb-locks-set

See create-event local-variable-scope
replication-features-functions select-into
ansi-diff-select-into-table select

See data-directory-initialization security-against-attack
See server-system-variables

See backup-types mysqldump-delimited-text
forcing-innodb-recovery load-data
security-against-attack null-values
privileges-provided select-into
ansi-diff-select-into-table server-options
server-system-variables problems-connecting
manual-conventions mysql-nutshell limits-windows

See select-into

See stored-program-restrictions stored-program-variables

See innodb-locking mysql-cluster-limitations-transactions
See innodb-locking-reads innodb-locks-set
innodb-transaction-isolation-levels

See innodb-persistent-stats-pages-sampled
general-thread-states semi-joins

See mysql-cluster-programs-ndb-import

See sql-mode

See assignment-operators stored-programs-logging
replication-options-binary-log innodb-buffer-pool-resize
innodb-statistics-estimation innodb-compression-usage
stored-programs-defining dynamic-system-variables
enterprise-encryption-usage events-configuration
func-op-summary-ref functions
replication-options-gtids diagnostics-area-populating
information-functions innodb-parameters
extensions-to-ansi mysqlbinlog
mysql-cluster-replication-conflict-resolution
non-typed-operators partitioning-limitations-locking
expired-password-handling password-management
query-cache-configuration replication-options-master
replication-options-slave reset-slave server-options
See sql-mode server-system-variables set-statement
See set-variable show-variables subqueries
trigger-syntax user-variables program-variables
using-system-variables safe-updates
stored-program-variables

See mysqldump mysqlpump

See mysql-cluster-system-variables

See optimizing-innodb-bulk-data-loading
sql-syntax-transactions

See replication-semisync

See charset-connection mysql-real-escape-string
mysql-real-escape-string-quote charset-restrictions
server-system-variables set-statement charset-unicode

See charset-connection

See innodb-performance-change_buffering
connection-control-installation dynamic-system-variables
grant multiple-key-caches
replication-semisync-installation set-variable
using-system-variables keyring-aws-plugin
temporary-files

See mysql-nutshell

See set-global-sql-slave-skip-counter

See set-transaction

See c-api-auto-reconnect charset-literal
charset-applications charset-connection charset-errors
See load-data faqs-cjk mysql-commands
mysql-real-escape-string mysql-real-escape-string-quote
mysql-reset-connection mysql-set-character-set
mysqldump mysqlpump charset-restrictions
server-system-variables set-names set-statement
charset-gb18030 type-conversion charset-unicode
charset-metadata

See charset-connection

See charset-connection

See mysqlbinlog

See mysqldump mysqlpump

See grant-tables information-functions
binary-log-mysql-database mysql-install-db
mysql-upgrade expired-password-handling
password-hashing password-management
validate-password-options-variables password-logging
replication-features-variables
replication-features-current-user
resetting-permissions-generic default-privileges
server-system-variables set-password set-statement
See account-names implicit-commit validate-password
See privilege-changes

See set-password mysql-nutshell

See set-password mysql-nutshell

See dynamic-system-variables set-variable
using-system-variables temporary-files

See set-transaction

See faqs-sql-modes

See thread-information

See server-options server-system-variables
set-transaction commit
innodb-transaction-isolation-levels

See set-statement commit

See innodb-memcached-replication

See set-statement

See c-api-data-structures c-api-function-overview
create-event create-procedure database-use
declare-cursor extended-show information-schema
identifier-mapping faqs-replication extensions-to-ansi
See mysql-stmt-store-result mysql-store-result
mysql-use-result mysqlshow
mysql-cluster-replication-schema
performance-schema-quick-start stored-program-restrictions
See show-columns show show-tables
replication-master-sql binary-log character-sets-table
See collation-character-set-applicability-table
collations-table column-privileges-table columns-table
See engines-table events-table files-table
status-table variables-table key-column-usage-table
See ndb-transid-mysql-connection-map-table partitions-table
See plugins-table processlist-table profiling-table
See referential-constraints-table schema-privileges-table
See schemata-table statistics-table
table-constraints-table table-privileges-table
tables-table tablespaces-table triggers-table
user-privileges-table views-table features
sys-schema-usage charset-metadata

See privileges-provided purge-binary-logs
show-binary-logs replication-master-sql
mysqlbinlog-backup

See replication-gtids-concepts
mysql-cluster-replication-schema cursor-restrictions
show-binlog-events replication-master-sql start-slave

See alter-database charset-introducer charset-mysql
See charset-literal charset-column charset-database
See extended-show faqs-cjk show-character-set
charset-charsets charset-table

See alter-database c-api-data-structures
charset-configuration charset-mysql
adding-collation-choosing-id source-configuration-options
See show-collation
collation-character-set-applicability-table collations-table

See explain extended-show internal-temporary-tables
See mysql-list-fields performance-schema-quick-start
show-columns innodb-buffer-page-table
innodb-buffer-page-lru-table innodb-buffer-pool-stats-table
See innodb-cmp-table innodb-cmp-per-index-table
innodb-cmpmem-table innodb-ft-being-deleted-table
innodb-ft-config-table innodb-ft-default-stopword-table
innodb-ft-deleted-table innodb-ft-index-cache-table
innodb-ft-index-table-table innodb-lock-waits-table
innodb-locks-table innodb-metrics-table
innodb-sys-columns-table innodb-sys-datafiles-table
innodb-sys-fields-table innodb-sys-foreign-table
innodb-sys-foreign-cols-table innodb-sys-indexes-table
innodb-sys-tables-table innodb-sys-tablespaces-table
innodb-sys-tablestats-table innodb-sys-virtual-table
innodb-temp-table-info-table innodb-trx-table
mysql-nutshell

See enum

See show-errors show-warnings

See server-system-variables show-create-database

See events-metadata show-events events-privileges

See create-procedure bug-reports faqs-stored-procs
See show-create-procedure stored-routines-metadata

See create-procedure bug-reports faqs-stored-procs
See show-create-function stored-routines-metadata

See show-create-database

See alter-table-partition-operations alter-table
index-page-merge-threshold create-table-statement-retention
See create-table innodb-compression-usage
data-type-defaults explain getting-information
federated-create myisam-repair innodb-page-compression
See partitioning-key partitioning-management-range-list
See mysql-cluster-disk-data-objects
mysql-cluster-system-variables mysql-cluster-programs-ndb-desc
See mysql-cluster-limitations-syntax partitioning-info
performance-schema-quick-start rebuilding-tables
sql-mode server-system-variables
create-table-ndb-table-comment-options show-columns
show-create-table silent-column-changes
create-table-foreign-keys example-foreign-keys

See show-create-trigger triggers-table
trigger-metadata

See adding-users grant-tables show-grants
account-locking

See create-view grant privileges-provided
view-restrictions show-create-view views-table
view-metadata

See create-database database-use extended-show
getting-information grant grant-tables
identifier-case-sensitivity information-schema
mysql-cluster-security-mysql-privileges mysql-cluster-ndbinfo
See performance-schema-build-configuration server-options
See server-system-variables show-databases

See privileges-provided show-engine

See innodb-standard-monitor innodb-parameters
show-engine mysql-nutshell

See innodb-adaptive-hash innodb-read-only-instance
converting-tables-to-innodb innodb-deadlocks
innodb-enabling-monitors innodb-deadlocks-handling
innodb-foreign-key-constraints
innodb-information-schema-buffer-pool-tables
innodb-information-schema-metrics-table
innodb-information-schema-system-tables innodb-locking
innodb-standard-monitor innodb-parameters
innodb-buffer-pool-monitoring innodb-migration
glossary optimizing-innodb-diskio
innodb-performance-ro-txn show-engine error-sources
See create-table-foreign-keys

See mysql-cluster-install-windows-initial-start
mysql-cluster-management mysql-cluster-replication-schema
See mysql-cluster-sql-statements

See mysql-cluster-program-options-mysqld
mysql-cluster-sql-statements

See performance-schema-statement-digests
performance-schema-status-monitoring show-engine

See storage-engines mysql-cluster-mysqld
mysql-cluster-ndbinfo performance-schema-build-configuration
See performance-schema-quick-start
mysql-cluster-sql-statements windows-select-server
server-system-variables show-engines
archive-storage-engine blackhole-storage-engine
innodb-check-availability

See get-diagnostics diagnostics-area-populating
innodb-foreign-key-constraints resignal-with-condition
server-system-variables show-errors show-warnings
See signal-condition-information-items error-sources

See events-metadata replication-features-invoked
show-events events-privileges events-table

See create-table column-privileges-table

See thread-information mysqladmin

See mysqlshow

See show-procedure-code

See show-procedure-status stored-routines-metadata

See mysql-cluster-status-variables server-system-variables
See status-table

See server-system-variables variables-table

See adding-users grant grant-tables
privileges-provided revoke security-guidelines
show-create-user show-grants show-privileges
privilege-system problems-connecting

See analyze-table innodb-statistics-estimation
index-page-merge-threshold explain-output explain
See index-hints index-statistics innodb-restrictions
See mysql-cluster-programs-ndb-index-stat optimizer-hints
See myisamchk-other-options show-columns show-index
See statistics-table table-constraints-table
mysql-cluster-what-is-new-7-5

See show-binary-logs

See replication-options-gtids replication-gtids-concepts
See replication-bugs mysql-cluster-replication-backups
replication-howto-masterstatus privileges-provided
show-slave-status replication-master-sql
innodb-memcached-replication replication-problems

See show-open-tables

See connection-control-installation
innodb-tablespace-encryption install-plugin
server-plugin-loading audit-log-installation
keyring-installation ldap-pluggable-authentication
fulltext-search-mecab mysql-cluster-program-options-mysqld
See mysql-cluster-ndbinfo no-login-pluggable-authentication
See obtaining-plugin-information
pam-pluggable-authentication partitioning
validate-password-installation plugin-api-characteristics
See plugin-api-components replication-semisync-installation
See server-plugin-descriptors show-plugins
socket-pluggable-authentication test-pluggable-authentication
See ndb-transid-mysql-connection-map-table plugins-table
See thread-pool-installation
windows-pluggable-authentication writing-audit-plugins
writing-daemon-plugins writing-full-text-plugins
writing-information-schema-plugins writing-keyring-plugins
See writing-password-validation-plugins
writing-authentication-plugins-server-side

See show-privileges

See show-function-code

See show-function-status stored-routines-metadata

See change-master-to replication-administration-status
dba-dtrace-ref-command dba-dtrace-ref-connection
replication-delayed events-configuration
thread-information general-thread-states grant
replication-gtids-concepts information-functions
innodb-error-handling kill security-against-attack
See faqs-replication mysql-cluster-mysqld
mysql-list-processes mysqladmin explain-for-connection
See performance-schema-instrument-naming
performance-schema-stage-tables privileges-provided
dba-dtrace-ref-queryexec dba-dtrace-ref-query
replication-implementation-details server-system-variables
See show-processlist show-profile show-slave-status
See start-slave commit replication-solutions-switch
See ndb-transid-mysql-connection-map-table processlist-table
See mysql-cluster-ndbinfo-server-locks
mysql-cluster-ndbinfo-server-operations
mysql-cluster-ndbinfo-server-transactions sys-processlist
See sys-ps-is-thread-instrumented
sys-ps-setup-disable-thread sys-ps-setup-enable-thread
sys-ps-thread-id threads-table too-many-connections
See replication-problems mysql-nutshell

See thread-information general-thread-states
source-configuration-options
performance-schema-query-profiling server-system-variables
See show-profile show-profiles profiling-table

See source-configuration-options
performance-schema-query-profiling server-system-variables
See show-profile show-profiles profiling-table

See channels-commands-single-channel
channels-with-prev-replication show-binlog-events
show-relaylog-events replication-slave-sql

See show-databases

See mysql-cluster-status-variables status-table

See variables-table

See replication-administration-status replication-options
See replication-options-master replication-options-slave
See replication-master-sql

See change-master-to replication-administration-status
channels-commands-single-channel
channels-with-prev-replication replication-delayed
replication-options-gtids replication-gtids-concepts
replication-bugs mysql-cluster-replication-failover
mysql-cluster-replication-issues faqs-replication
mysqldump performance-schema-replication-tables
privileges-provided purge-binary-logs
replication-options
replication-features-transaction-inconsistencies
replication-implementation-details
replication-mode-change-online-concepts slave-io-thread-states
See replication-options-slave
replication-solutions-encrypted-connections show-master-status
See show-slave-status replication-features-slaveerrors
slave-logs-status error-sources replication-slave-sql
See start-slave replication-applier-configuration-table
See replication-applier-status-table
replication-applier-status-by-coordinator-table
replication-applier-status-by-worker-table
replication-connection-configuration-table
replication-connection-status-table replication-problems
mysql-nutshell

See upgrading-from-previous-series
replication-administration-status mysql-cluster-api-definition
See mysql-cluster-management
performance-schema-variable-table-migration
mysql-cluster-program-options-mysqld
mysql-cluster-ndb-api-statistics mysql-cluster-replication
See performance-schema-replication-tables
performance-schema-system-variables plugin-api-characteristics
See query-cache-status-and-maintenance
mysql-cluster-sql-statements replication-features-temptables
See replication-implementation-details
replication-features-timeout stored-program-restrictions
replication-semisync-monitoring server-plugin-descriptors
See server-status-variables server-system-variables
show-status index-extensions mysql-nutshell
writing-audit-plugins writing-full-text-plugins
writing-plugins

See performance-schema-status-monitoring

See innodb-auto-increment-handling
innodb-statistics-estimation create-table-statement-retention
See create-table using-innodb-tables explain
innodb-file-space innodb-parameters
innodb-restrictions glossary partitioning-info
show-columns show-table-status
innodb-row-format-specification archive-storage-engine
tables-table innodb-physical-record

See creating-tables extended-show
identifier-case-sensitivity information-schema
innodb-information-schema identifier-mapping glossary
See mysql-cluster-replication-multi-master
mysql-cluster-programs-ndb-restore mysql-cluster-ndbinfo
server-options show-table-status show-tables
cannot-find-table temporary-table-problems
firewall-usage

See mysql-cluster-security-mysql-privileges

See faqs-triggers show-triggers triggers-table
trigger-metadata

See upgrading-from-previous-series
compiling-plugin-libraries events-configuration
keyring-system-variables audit-log-legacy-filtering
performance-schema-variable-table-migration
replication-multi-source-monitoring faqs-cjk
performance-schema-startup-configuration
performance-schema-system-variables plugin-api-characteristics
See replication-options-slave multiple-servers
replication-semisync-monitoring server-options
server-plugin-descriptors server-system-variables
set-variable show-variables
mysql-cluster-replication-starting using-system-variables
See mysql-nutshell audit-log-filter-definitions
writing-audit-plugins writing-keyring-plugins
writing-password-validation-plugins writing-plugins

See replication-sbr-rbr alter-table
collation-diagnostics drop-procedure drop-table
signal-effects explain-output explain
explain-extended function-resolution get-diagnostics
See diagnostics-area-populating load-data
binary-log-mixed optimizer-hints
generated-column-index-optimizations using-explain
subquery-materialization subquery-optimization-with-exists
See semi-joins constraint-primary-key
create-table-secondary-indexes error-messages-server
server-system-variables show-errors show-warnings
See signal-condition-information-items signal
error-sources plugin-types
rewriter-query-rewrite-plugin-usage

See mysql-shutdown privileges-provided shutdown
See mysql-nutshell

See condition-handling declare-condition
declare-handler diagnostics-area-information-items
signal-effects diagnostics-area-populating
information-functions resignal
condition-handling-restrictions stored-program-restrictions
See handler-scope signal-condition-information-items
signal

See show-slave-status start-slave

See group-replication-frequently-asked-questions
group-replication-options group-replication-launching
mysql-nutshell

See change-master-to channels-commands-single-channel
channels-with-prev-replication replication-delayed
replication-options-gtids replication-gtids-concepts
mysql-cluster-replication-failover mysqldump
mysql-cluster-replication-multi-master
mysql-cluster-programs-ndb-restore password-logging
replication-administration-pausing
performance-schema-replication-tables
replication-solutions-partitioning replication-options
replication-features-transaction-inconsistencies
replication-implementation-details replication-options-slave
See reset-slave replication-semisync-installation
show-slave-status replication-features-slaveerrors
start-slave mysql-cluster-replication-starting
implicit-commit stop-slave
replication-solutions-switch replication-problems
replication-gtids-failover
mysql-cluster-replication-two-channels

See change-replication-filter

See replication-options-slave

See change-master-to
replication-solutions-unexpected-slave-halt
replication-features-transaction-inconsistencies
replication-options-slave show-slave-status
start-slave

See innodb-autocommit-commit-rollback begin-end
flush innodb-deadlocks-handling innodb-error-handling
See innodb-parameters lock-tables-and-transactions
lock-tables innodb-locking-reads mysqldump
mysqlpump innodb-performance-ro-txn
performance-schema-transaction-tables
stored-program-restrictions replication-semisync
server-system-variables set-transaction commit
implicit-commit events-transactions-current-table
sql-syntax-transactions trigger-syntax xa-states

See glossary innodb-performance-ro-txn

See innodb-consistent-read

See innodb-statistics-estimation

See innodb-persistent-stats

See group-replication-options

See group-replication-frequently-asked-questions
stop-group-replication mysql-nutshell

See replication-howto-additionalslaves change-master-to
See replication-administration-status
channels-commands-single-channel
channels-with-prev-replication replication-delayed
replication-options-gtids mysqldump
replication-administration-pausing
performance-schema-replication-tables replication-options
See replication-features-transaction-inconsistencies
replication-options-slave reset-master reset-slave
See replication-semisync-installation start-slave
implicit-commit stop-slave
replication-solutions-switch
replication-applier-status-by-worker-table
replication-rbr-usage mysql-nutshell

See change-replication-filter replication-rbr-usage

[index top]

See online-ddl-partitioning

See innodb-memcached-dml
mysql-cluster-online-add-node-remarks
mysql-cluster-mgm-client-commands compressed-format
converting-tables-to-innodb create-trigger delete
See performance-schema-pre-filtering federated-usagenotes
See file-summary-tables handler
query-cache-operation innodb-multiple-tablespaces
innodb-memcached-internals innodb-parameters
mysql-cluster-limitations-limits
mysql-cluster-limitations-transactions lock-tables
binary-log-mysql-database partitioning-maintenance
partitioning-management-range-list memory-summary-tables
merge-table-problems glossary mysqldump
mysqlpump mysql-cluster-programs-ndb-delete-all
objects-summary-global-by-type-table
optimizing-innodb-ddl-operations
performance-schema-connection-tables performance-schema-timing
See performance-schema-table-characteristics
performance-schema-status-variable-tables
performance-schema-summary-tables
performance-schema-system-variable-tables
performance-schema-user-variable-tables
mysql-cluster-replication-pitr privileges-provided
replication-features-memory replication-features-truncate
See log-destinations server-system-variables
socket-summary-tables stage-summary-tables
statement-summary-tables implicit-commit
performance-schema-status-variable-summary-tables
accounts-table cond-instances-table
events-stages-current-table events-stages-history-table
events-stages-history-long-table
events-statements-current-table
events-statements-history-table
events-statements-history-long-table
events-transactions-current-table
events-transactions-history-table
events-transactions-history-long-table
events-waits-current-table events-waits-history-table
events-waits-history-long-table file-instances-table
host-cache-table hosts-table innodb-sys-indexes-table
See innodb-sys-tables-table innodb-memcached-replication
See memory-storage-engine metadata-locks-table
mutex-instances-table performance-timers-table
prepared-statements-instances-table sys-ps-truncate-all-tables
See replication-applier-configuration-table
replication-applier-status-table
replication-applier-status-by-coordinator-table
replication-applier-status-by-worker-table
replication-connection-configuration-table
replication-connection-status-table
replication-group-member-stats-table
replication-group-members-table rwlock-instances-table
session-account-connect-attrs-table
session-connect-attrs-table setup-actors-table
setup-consumers-table setup-instruments-table
setup-objects-table setup-timers-table
socket-instances-table table-handles-table
table-io-waits-summary-by-index-usage-table
table-io-waits-summary-by-table-table
table-lock-waits-summary-by-table-table threads-table
users-table transaction-summary-tables truncate-table
See wait-summary-tables mysql-nutshell query-results
See audit-log-filter-definitions

See host-cache-table

[index top]

See flush memory-use install-plugin
server-plugin-loading keyring-udf-installation
version-tokens-installation ldap-pluggable-authentication
See mysql-plugin no-login-pluggable-authentication
pam-pluggable-authentication performance-schema-and-plugins
See pluggable-storage plugin-api-components
server-plugin-descriptors show-plugins
socket-pluggable-authentication implicit-commit
test-pluggable-authentication plugins-table
uninstall-plugin keyring-aws-plugin
windows-pluggable-authentication writing-audit-plugins
writing-daemon-plugins writing-full-text-plugins
writing-information-schema-plugins
writing-password-validation-plugins
writing-authentication-plugins-server-side

See c-api-data-structures upgrading-from-previous-series
See string-functions-charset create-table
create-view explain-output information-functions
insert-on-duplicate internal-temporary-tables
innodb-locks-set numeric-type-attributes
derived-table-optimization semi-joins
range-optimization searching-on-two-keys select
server-status-variables subqueries
merge-storage-engine union view-updatability
procedure-analyse view-syntax xml-functions

See information-functions internal-temporary-tables
derived-table-optimization union view-updatability

See union

See optimizing-myisam-bulk-data-loading backup-methods
flush innodb-deadlocks-handling
lock-tables-and-transactions innodb-restrictions
lock-tables mysqldump mysqlpump
stored-program-restrictions commit implicit-commit
See system-optimization lock-tables-restrictions
innodb-transportable-tablespace-examples
innodb-transportable-tablespace-internals

See request-access adding-users replication-sbr-rbr
See assignment-operators audit-log-routines
innodb-auto-increment-handling innodb-best-practices
replication-options-binary-log
optimizing-innodb-bulk-data-loading
optimizing-myisam-bulk-data-loading c-api-function-overview
See c-api-multiple-queries
c-api-prepared-statement-function-overview statement-caching
See innodb-insert-buffering downgrading-to-previous-series
See upgrading-from-previous-series check-table
charset-conversion innodb-performance-compression-oltp
innodb-performance-change_buffering index-page-merge-threshold
See innodb-consistent-read constraint-invalid-data
converting-tables-to-innodb create-table-generated-columns
See create-temporary-table create-trigger
create-view federated-create-connection
data-type-defaults date-and-time-type-overview
innodb-deadlocks explain-output explain
explain-extended federated-usagenotes
forcing-innodb-recovery fulltext-restrictions
func-op-summary-ref function-optimization functions
See general-thread-states grant grant-tables
query-cache-operation information-functions
information-schema innodb-locking innodb-parameters
See insert-on-duplicate insert internal-locking
See internal-temporary-tables join kill bugs
See mysql-cluster-replication-issues load-data
innodb-locking-reads innodb-locks-set
binary-log-mysql-database miscellaneous-functions
faqs-stored-procs extensions-to-ansi glossary
mysql-command-options mysql-affected-rows mysql-info
See mysql-insert-id mysql-num-rows mysql-options
See mysql-stmt-execute mysql-stmt-insert-id
mysql-stmt-num-rows mysqlbinlog-row-events mysqldump
See mysql-cluster-disk-data-objects
mysql-cluster-replication-conflict-resolution
explain-for-connection innodb-create-index-overview
non-typed-operators optimizer-hints
data-change-optimization using-explain
subquery-optimization out-of-range-and-overflow
partitioning-overview partitioning-pruning
partitioning-selection partitioning-limitations-locking
password-logging performance-schema-thread-filtering
constraint-primary-key privileges-provided using-date
See replication-features-limit
replication-features-optimizer replication-features-triggers
See replication-options-slave partitioning-limitations
rewriting-subqueries create-table-secondary-indexes
selecting-all log-destinations server-options
sql-mode server-status-variables
server-system-variables set-password show-warnings
See replication-features-slaveerrors
dba-dtrace-ref-statement subquery-errors subqueries
See table-locking lock-tables-restrictions
archive-storage-engine charset-binary-collations
binary-log blackhole-storage-engine
innodb-sys-tablestats-table tables-table views-table
See features merge-storage-engine
myisam-storage-engine privilege-system server-shutdown
See sys-sys-config-update-set-user
innodb-transaction-isolation-levels trigger-syntax
problems-connecting view-updatability ansi-diff-update
See update replication-rbr-usage
audit-log-filtering-functions create-table-foreign-keys
safe-updates mysql-nutshell query-results
privilege-changes where-optimization
null-mysql-store-result audit-log-filter-definitions

See innodb-consistent-read

See innodb-deadlocks

See innodb-locks-set

See sql-mode update

See dba-dtrace-ref-statement

See replication-options-binary-log
mysqldump-copying-to-other-server create-procedure
creating-database database-use mysqldump-sql-format
See replication-rules-db-options information-schema
mysql-command-options mysqlbinlog mysqldump
mysqlpump mysql-cluster-ndbinfo
reloading-sql-format-dumps replication-rules-examples
replication-options-slave stored-routines-syntax use

See mysqlbinlog

See mysql-command-options

See mysqlbinlog

[index top]

See innodb-benefits

See flow-control-statements iterate leave
statement-labels while

[index top]

See performance-schema-transaction-tables

See downgrading upgrading-strategies
performance-schema-transaction-tables server-system-variables
See events-transactions-current-table xa-states

See xa-restrictions events-transactions-current-table
xa-statements xa-states

See events-transactions-current-table xa-states

See downgrading upgrading-strategies xa-restrictions
See events-transactions-current-table xa-statements
xa-states

See downgrading upgrading-strategies
performance-schema-transaction-tables server-system-variables
See events-transactions-current-table xa-states

See performance-schema-transaction-tables xa-restrictions
See events-transactions-current-table xa-statements
xa-states

xa-statements

A | B | C | D | F | H | I | K | L | M | N | O | P | Q | R | S | T | U |
V

[index top]

See communication-errors server-status-variables

See communication-errors server-status-variables

See audit-log-status-variables

See audit-log-status-variables

See audit-log-status-variables

See audit-log-status-variables

See audit-log-status-variables

See audit-log-status-variables

See audit-log-status-variables

See audit-log-status-variables

[index top]

See replication-options-binary-log server-status-variables
See binary-log

See replication-options-binary-log server-status-variables
See binary-log

See replication-options-binary-log server-status-variables

See replication-options-binary-log server-status-variables

See server-status-variables

See server-status-variables

[index top]

See server-status-variables

See statement-caching

See server-status-variables

See connection-control-installation
connection-control-variables

See server-status-variables

See server-status-variables

See server-status-variables server-system-variables

See server-status-variables

See server-status-variables

See server-status-variables

See host-cache server-status-variables

See server-status-variables server-system-variables

See internal-temporary-tables server-status-variables
server-system-variables events-statements-current-table

See server-status-variables

See internal-temporary-tables server-status-variables
server-system-variables show-status
events-statements-current-table

[index top]

See server-status-variables

See server-status-variables

See server-status-variables

[index top]

See firewall-status-variables

See firewall-status-variables firewall-usage

See firewall-status-variables

See firewall-status-variables

See server-status-variables

[index top]

See server-status-variables

See server-status-variables

See mysql-cluster-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables index-extensions

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

[index top]

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See innodb-performance-read_ahead innodb-parameters
server-status-variables

See innodb-performance-read_ahead innodb-parameters
server-status-variables

See innodb-performance-read_ahead server-status-variables

See server-status-variables

See server-status-variables

See innodb-buffer-pool-resize innodb-parameters
server-status-variables mysql-nutshell

See server-status-variables

See server-status-variables

See innodb-parameters server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See innodb-parameters server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

[index top]

See server-status-variables

See server-status-variables server-system-variables

See server-status-variables

See server-status-variables server-system-variables

See server-status-variables server-system-variables

See server-status-variables server-system-variables

See server-status-variables server-system-variables

[index top]

See server-status-variables

See server-status-variables

See server-status-variables account-locking

[index top]

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See flush server-status-variables
server-system-variables

See server-status-variables

See fulltext-search-mecab server-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

See x-plugin-monitoring-status-variables

[index top]

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-ndb-api-statistics
mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-replication-conflict-resolution
mysql-cluster-status-variables

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-status-variables

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-replication-conflict-resolution

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables
mysql-cluster-system-variables

See mysql-cluster-status-variables
mysql-cluster-system-variables

See mysql-cluster-status-variables
mysql-cluster-system-variables

See mysql-cluster-status-variables
mysql-cluster-system-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables

See mysql-cluster-status-variables
mysql-cluster-what-is-new-7-5 mysql-cluster-what-is-new-7-6

See server-status-variables

[index top]

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See table-cache server-status-variables
server-system-variables

[index top]

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-monitoring
performance-schema-status-variables

See performance-schema-status-monitoring
performance-schema-status-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables
performance-schema-system-variables
prepared-statements-instances-table

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-connection-attribute-tables
performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables

See performance-schema-status-variables
performance-schema-system-variable-tables
performance-schema-system-variables

See performance-schema-status-variables

See server-status-variables

[index top]

See query-cache-configuration
query-cache-status-and-maintenance server-status-variables
See mysql-nutshell

See server-status-variables mysql-nutshell

See query-cache-operation server-status-variables
mysql-nutshell

See server-status-variables mysql-nutshell

See query-cache-configuration
query-cache-status-and-maintenance server-status-variables
See mysql-nutshell

See server-status-variables mysql-nutshell

See query-cache-configuration server-status-variables
mysql-nutshell

See query-cache-configuration
query-cache-status-and-maintenance server-status-variables
See mysql-nutshell

See server-status-variables

See mysqladmin server-status-variables

[index top]

See rewriter-query-rewrite-plugin-status-variables

See rewriter-query-rewrite-plugin-status-variables

See rewriter-query-rewrite-plugin-status-variables

See rewriter-query-rewrite-plugin-routines
rewriter-query-rewrite-plugin-table
rewriter-query-rewrite-plugin-status-variables
rewriter-query-rewrite-plugin-usage

See replication-semisync-interface
replication-semisync-monitoring server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See replication-semisync-interface
replication-semisync-monitoring server-status-variables

See replication-semisync-interface
replication-semisync-monitoring server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See replication-semisync-interface
replication-semisync-monitoring server-status-variables

See replication-semisync-interface
replication-semisync-monitoring server-status-variables

See ssl-libraries server-status-variables
sha256-pluggable-authentication

[index top]

See server-status-variables events-statements-current-table

See server-status-variables events-statements-current-table

See server-status-variables events-statements-current-table

See server-status-variables events-statements-current-table

See server-status-variables events-statements-current-table

See change-master-to replication-administration-status
performance-schema-replication-tables reset-slave
server-status-variables

See replication-administration-status
performance-schema-replication-tables server-status-variables

See change-master-to replication-features-temptables
server-status-variables stop-slave mysql-nutshell

See change-master-to replication-administration-status
performance-schema-replication-tables server-status-variables

See replication-administration-status
performance-schema-replication-tables server-status-variables

See server-status-variables

See replication-administration-status
performance-schema-replication-tables
replication-implementation-details server-status-variables
See show-slave-status

See server-status-variables server-system-variables

See server-status-variables server-system-variables

See order-by-optimization server-status-variables
server-system-variables events-statements-current-table

See server-status-variables events-statements-current-table

See server-status-variables events-statements-current-table

See server-status-variables events-statements-current-table

See server-status-variables

See server-status-variables

See server-status-variables

See using-encrypted-connections
encrypted-connection-protocols-ciphers server-status-variables

See encrypted-connection-protocols-ciphers
server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See encrypted-connection-protocols-ciphers
server-status-variables

[index top]

See internal-locking server-status-variables

See internal-locking server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See server-status-variables

See connection-threads server-status-variables

See server-status-variables

See connection-threads server-status-variables
server-system-variables

See faqs-thread-pool server-status-variables

[index top]

See mysqladmin server-status-variables

See server-status-variables

[index top]

See validate-password-options-variables

validate-password-options-variables

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R |
S | T | U | V | W

[index top]

See audit-log-logging-control audit-log-options-variables
See audit-log-status-variables

See audit-log-logging-control audit-log-options-variables

See audit-log-options-variables audit-log-legacy-filtering
See audit-log-filter-definitions

See audit-log-options-variables

See audit-log-logging-control audit-log-options-variables

See audit-log-options-variables audit-log-legacy-filtering
See audit-log-filter-definitions

See audit-log-logging-control audit-log-options-variables
See audit-log audit-log-security

See audit-log-filtering audit-log-options-variables
audit-log-filtering-functions audit-log-filter-definitions

See audit-log-logging-control audit-log-options-variables

See audit-log-file-formats audit-log-logging-control
audit-log-options-variables audit-log

See audit-log-options-variables audit-log-legacy-filtering
See audit-log-filter-definitions

See audit-log-options-variables audit-log-legacy-filtering
See audit-log-filter-definitions

See audit-log-logging-control audit-log-options-variables

See audit-log-logging-control audit-log-options-variables

See audit-log-options-variables audit-log-legacy-filtering
See audit-log-filter-definitions

See audit-log-logging-control audit-log-options-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See ldap-pluggable-authentication
pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See ldap-pluggable-authentication
pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See ldap-pluggable-authentication
pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See pluggable-authentication-system-variables

See ldap-pluggable-authentication
pluggable-authentication-system-variables

See server-system-variables windows-pluggable-authentication

See server-system-variables windows-pluggable-authentication

See creating-ssl-rsa-files-using-mysql ssl-libraries
server-system-variables encrypted-connections

See innodb-auto-increment-handling binary-log-mixed
faqs-general mysql-cluster-programs-ndb-import
replication-features-variables replication-options-master
See example-auto-increment

See innodb-auto-increment-handling binary-log-mixed
faqs-general mysql-cluster-programs-ndb-import
replication-features-variables replication-options-master
See example-auto-increment

See replication-features-transactions

See innodb-autocommit-commit-rollback
converting-tables-to-innodb innodb-deadlock-detection
delete innodb-locking-transaction-model
innodb-parameters lock-tables-and-transactions
innodb-restrictions innodb-locking-reads
innodb-locks-set mysql-cluster-system-variables
innodb-performance-ro-txn
performance-schema-transaction-tables
replication-features-transactions
replication-gtids-restrictions server-system-variables
commit innodb-trx-table thread-pool-operation
innodb-transaction-isolation-levels

See alter-procedure create-procedure
server-system-variables stored-routines-privileges

See upgrading-from-previous-series check-table
repair-table server-system-variables

[index top]

See server-system-variables

See install-plugin osx-installation-launchd
server-options server-system-variables

See internal-temporary-tables server-system-variables

See server-system-variables
x-plugin-system-variables-options

See group-replication-limitations
group-replication-requirements

See replication-options-binary-log server-status-variables
See binary-log

See replication-options-binary-log glossary
replication-features-transactions binary-log

See replication-options-binary-log
replication-features-transactions

See replication-options-binary-log

See stored-programs-logging replication-options-binary-log
See upgrading-from-previous-series date-and-time-functions
See replication-rbr-safe-unsafe replication-rules-db-options
See replication-rules-table-options information-functions
See binary-log-mysql-database mathematical-functions
miscellaneous-functions binary-log-mixed
faqs-replication mysqlbinlog privileges-provided
replication-features-blackhole replication-features-load-data
See replication-features-memory
replication-features-temptables
replication-features-transactions replication-formats
replication-features-mysqldb xa-restrictions
server-options error-messages-server
binary-log-setting blackhole-storage-engine query-log
See innodb-memcached-replication replication-upgrade
replication-rbr-usage

See replication-options-binary-log

See replication-options-binary-log

See replication-options-gtids

See replication-options-binary-log mysql-nutshell

See replication-options-binary-log

See replication-sbr-rbr replication-options-binary-log
optimizing-innodb-diskio

See replication-sbr-rbr replication-options-binary-log

See replication-options-binary-log server-status-variables

See replication-options-binary-log

See replication-options-binary-log server-system-variables

See replication-options-binary-log

See encryption-functions server-system-variables

See myisam-start insert-optimization
server-system-variables

[index top]

See c-api-prepared-statement-type-codes
charset-configuration charset-connection load-data
See binary-log-mixed faqs-cjk
replication-features-variables server-system-variables
set-character-set set-names show-create-event
show-create-procedure show-create-trigger
show-create-view show-events show-procedure-status
See show-triggers binary-log events-table
routines-table triggers-table views-table
rewriter-query-rewrite-plugin-usage

See cast-functions string-functions-charset
charset-introducer charset-repertoire charset-literal
See charset-collation-coercibility charset-connection
date-and-time-functions encryption-functions
binary-log-mixed faqs-cjk locale-support
replication-features-variables server-system-variables
set-character-set set-names string-literals
type-conversion

See alter-table charset-connection create-procedure
See charset-database load-data binary-log-mixed
See replication-features-variables server-system-variables
See set-character-set mysql-nutshell

See load-data select-into server-options
server-system-variables string-functions

See c-api-data-structures charset-connection
charset-errors faqs-cjk server-system-variables
set-character-set set-names charset-metadata

See charset-configuration charset-connection
charset-database fulltext-stopwords binary-log-mixed
See replication-features-charset
replication-features-variables charset-server
server-system-variables

See charset-configuration server-system-variables
charset-metadata

See adding-collation-simple-8bit ldml-collation-example
See server-system-variables

See proxy-users server-system-variables

See cast-functions string-functions-charset
charset-introducer charset-literal
charset-collation-coercibility charset-connection
date-and-time-functions encryption-functions
binary-log-mixed replication-features-variables
server-system-variables set-names show-create-event
See show-create-procedure show-create-trigger
show-create-view show-events show-procedure-status
See show-triggers binary-log events-table
routines-table triggers-table views-table
type-conversion

See charset-connection create-procedure
charset-database binary-log-mixed
replication-features-variables server-system-variables
binary-log mysql-nutshell

See charset-connection charset-database
fulltext-stopwords binary-log-mixed
replication-features-variables charset-server
server-system-variables binary-log

See mysql-commit mysql-rollback
server-system-variables commit

See concurrent-inserts internal-locking
optimizing-queries-myisam server-system-variables

See communication-errors error-lost-connection
mysql-real-connect server-system-variables
x-plugin-system-variables-options

See connection-control-installation
connection-control-variables
connection-control-failed-login-attempts-table

See connection-control-installation
connection-control-variables

See connection-control-installation
connection-control-variables

See server-system-variables

[index top]

See innodb-memcached-setup

See innodb-memcached-setup

See innodb-memcached-intro innodb-memcached-security
innodb-memcached-setup innodb-memcached-troubleshoot

See innodb-memcached-intro innodb-parameters
innodb-memcached-ddl innodb-memcached-setup
innodb-memcached-replication innodb-memcached-tuning

See innodb-memcached-txn innodb-memcached-intro
innodb-parameters innodb-memcached-ddl
innodb-memcached-setup innodb-memcached-replication
innodb-memcached-tuning

See tablespace-placing

See group-replication-configuring-instances
create-tablespace innodb-init-startup-configuration
innodb-parameters osx-installation-launchd
windows-installation glossary
innodb-create-index-concurrency server-options
server-system-variables files-table
innodb-sys-tables-table innodb-sys-tablespaces-table
temporary-files

See server-system-variables

See server-system-variables

See server-system-variables dbug-package

See server-system-variables

See innodb-benchmarking

See alter-user authentication-plugins create-user
See mysql-install-db pluggable-authentication
server-options server-system-variables
sha256-pluggable-authentication

See alter-user create-user grant-tables
password-management server-system-variables

See create-logfile-group create-table
create-tablespace drop-tablespace general-tablespaces
See server-plugin-loading replication-features-variables
See server-system-variables storage-engine-setting
replication-solutions-diffengines mysql-nutshell

See server-plugin-loading server-options
server-system-variables storage-engine-setting
innodb-temporary-tablespace

See date-and-time-functions
partitioning-limitations-functions server-system-variables

See create-table server-system-variables

See server-system-variables

See server-system-variables

See server-system-variables

See faqs-storage-engines server-options
error-messages-server server-system-variables

See expired-password-handling server-system-variables

See arithmetic-functions server-system-variables

[index top]

See server-system-variables

See replication-options-gtids

See replication-mode-change-online-disable-gtids
replication-options-gtids
replication-mode-change-online-concepts
replication-gtids-howto

See range-optimization server-system-variables

See diagnostics-area-system-variables
sql-syntax-prepared-statements server-system-variables
show-errors error-sources

See events-configuration libmysqld-restrictions
server-system-variables events-privileges

See replication-options-gtids

See purge-binary-logs log-file-maintenance
server-system-variables

See timestamp-initialization data-type-defaults
date-and-time-type-overview server-system-variables

See audit-log-file-formats
writing-authentication-plugins-proxy-users proxy-users
server-system-variables
writing-authentication-plugins-server-side

[index top]

See server-system-variables

See server-options server-system-variables

See alter-table tablespace-copying binary-log-mixed
See mysql-cluster-system-variables
innodb-create-index-implementation
innodb-create-index-overview replication-features-variables
See sql-mode server-system-variables binary-log
See create-table-foreign-keys

See fulltext-boolean fulltext-fine-tuning
server-system-variables

See fulltext-boolean replication-howto-rawdata
fulltext-fine-tuning fulltext-search-ngram
server-system-variables writing-full-text-plugins

See fulltext-boolean replication-howto-rawdata
fulltext-fine-tuning fulltext-search-mecab
fulltext-natural-language fulltext-search-ngram
server-system-variables writing-full-text-plugins

See server-system-variables

See fulltext-boolean replication-howto-rawdata
fulltext-fine-tuning fulltext-stopwords
fulltext-natural-language server-system-variables

[index top]

See glossary log-destinations server-options
server-system-variables query-log

See log-destinations server-system-variables
query-log

See group-by-functions server-system-variables

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-configuring-instances
group-replication-options

See group-replication-options

See group-replication-options

See
group-replication-deploying-in-multi-primary-or-single-primary-mode
See group-replication-limitations group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options
group-replication-network-partitioning

See group-replication-configuring-instances
group-replication-options
mysql-innodb-cluster-working-with-cluster

See group-replication-configuring-instances
group-replication-options
mysql-innodb-cluster-working-with-cluster

See group-replication-options

See group-replication-options
group-replication-ip-address-whitelisting
mysql-innodb-cluster-working-with-cluster

See group-replication-configuring-instances
group-replication-frequently-asked-questions
group-replication-options replication-group-members-table
See mysql-innodb-cluster-working-with-cluster

See group-replication-options
group-replication-single-primary-mode

See group-replication-fine-tuning-the-group-communication-thread
See group-replication-options

See group-replication-options

See group-replication-options
group-replication-tuning-recovery

See group-replication-options
group-replication-tuning-recovery

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-options

See group-replication-limitations group-replication-options
See mysql-innodb-cluster-using-router

See group-replication-options
group-replication-secure-socket-layer-support-ssl
mysql-innodb-cluster-working-with-cluster

See group-replication-configuring-instances
group-replication-options

See group-replication-options

See group-replication-options

See replication-mode-change-online-disable-gtids
group-replication-requirements

See change-master-to replication-options-gtids
replication-gtids-concepts
performance-schema-replication-tables
replication-mode-change-online-concepts
replication-options-slave reset-master
replication-gtids-restrictions show-master-status
show-slave-status replication-gtids-failover
group-replication-enterprise-backup

See replication-options-gtids replication-gtids-concepts

See replication-multi-source-adding-gtid-master
change-master-to replication-mode-change-online-disable-gtids
See replication-mode-change-online-enable-gtids
gtid-functions replication-options-gtids
replication-gtids-concepts upgrading-strategies
mysql-upgrade mysqldump
replication-mode-change-online-concepts
replication-gtids-restrictions replication-gtids-howto
events-transactions-current-table
replication-applier-status-by-worker-table replication-upgrade
See replication-gtids-failover

See replication-options-gtids replication-gtids-concepts
See replication-mode-change-online-concepts reset
server-status-variables start-slave stop-slave
events-transactions-current-table
replication-applier-status-by-worker-table

See replication-options-gtids

See replication-options-gtids replication-gtids-concepts
See replication-mode-change-online-concepts reset-master
See replication-gtids-failover

[index top]

See server-system-variables

See server-system-variables mysql-nutshell

See replication-semisync-installation
server-system-variables

See server-system-variables

See server-system-variables

See server-system-variables

See query-cache-configuration server-system-variables
mysql-nutshell

See server-system-variables

See building-with-encrypted-connection-support
server-system-variables

See server-system-variables

See server-system-variables symbolic-links-to-tables

See host-cache server-options
server-system-variables

See group-replication-frequently-asked-questions
server-system-variables replication-group-members-table

[index top]

See binary-log-mixed replication-features-variables
server-system-variables

See server-options server-system-variables
mysql-nutshell

See charset-applications privileges-provided
replication-options-slave server-system-variables
host-cache-table

See server-system-variables

See replication-options-slave

See innodb-read-only-instance faqs-innodb-change-buffer

See innodb-performance-adaptive_flushing
innodb-lru-background-flushing innodb-buffer-pool

See innodb-lru-background-flushing innodb-buffer-pool

See innodb-adaptive-hash
innodb-performance-thread_concurrency innodb-parameters
glossary optimizing-innodb-configuration-variables
truncate-table

See innodb-adaptive-hash innodb-trx-table

See innodb-performance-thread_concurrency innodb-parameters

See innodb-performance-use_sys_malloc mysql-nutshell

See innodb-memcached-txn innodb-memcached-intro

See innodb-memcached-txn

See innodb-memcached-replication

See innodb-memcached-txn innodb-memcached-intro

See innodb-memcached-txn innodb-memcached-intro

See innodb-multiple-tablespaces
innodb-init-startup-configuration innodb-parameters
glossary innodb-resize-system-tablespace

See innodb-auto-increment-handling
optimizing-innodb-bulk-data-loading information-functions
See innodb-locking innodb-restrictions glossary

See innodb-buffer-pool-resize innodb-parameters
mysql-nutshell

See innodb-parameters glossary
innodb-preload-buffer-pool innodb-buffer-pool

See innodb-parameters innodb-preload-buffer-pool
innodb-buffer-pool

See innodb-parameters innodb-preload-buffer-pool
innodb-buffer-pool mysql-nutshell

See innodb-preload-buffer-pool innodb-buffer-pool

See innodb-buffer-pool-resize innodb-multiple-buffer-pools
See memory-use innodb-init-startup-configuration
innodb-parameters glossary innodb-buffer-pool
innodb-memcached-tuning

See server-status-variables innodb-buffer-pool

See innodb-parameters glossary
innodb-preload-buffer-pool server-status-variables
innodb-buffer-pool

See innodb-parameters innodb-preload-buffer-pool
server-status-variables innodb-buffer-pool

See innodb-performance-compression-oltp
innodb-buffer-pool-resize innodb-multiple-buffer-pools
converting-tables-to-innodb memory-use
innodb-memcached-intro innodb-init-startup-configuration
innodb-parameters glossary optimizing-innodb-diskio
See error-messages-server server-status-variables
innodb-buffer-pool innodb-memcached-tuning
mysql-nutshell

See innodb-change-buffer-maximum-size
faqs-innodb-change-buffer glossary

See innodb-insert-buffering
innodb-performance-change_buffering innodb-read-only-instance
See glossary optimizing-innodb-transaction-management

See innodb-parameters glossary
optimizing-innodb-diskio

See innodb-parameters glossary

See innodb-compression-tuning-monitoring
innodb-cmp-per-index-table innodb-compression-tuning

See innodb-performance-compression-oltp
innodb-compression-internals innodb-parameters
glossary innodb-compression-tuning

See innodb-performance-compression-oltp
innodb-compression-internals glossary
innodb-compression-tuning

See innodb-performance-compression-oltp
innodb-compression-internals innodb-parameters
glossary innodb-compression-tuning

See innodb-performance-thread_concurrency innodb-parameters
See optimizing-innodb-configuration-variables
innodb-trx-table

See innodb-file-space data-directory-initialization-mysqld
See innochecksum innodb-init-startup-configuration
innodb-parameters mysql-install-db
innodb-resize-system-tablespace innodb-system-tablespace
files-table error-creating-innodb innodb-raw-devices

See data-directory-initialization-mysqld
innodb-init-startup-configuration innodb-parameters
mysql-install-db innodb-temporary-tablespace
error-creating-innodb

See converting-tables-to-innodb innodb-deadlock-detection
See innodb-deadlocks innodb-parameters
internal-locking glossary

See upgrading-from-previous-series tablespace-copying
create-table using-innodb-tables innodb-parameters
See glossary data-size
innodb-row-format-specification innodb-physical-record
mysql-nutshell

See innodb-doublewrite-buffer mysql-acid
innodb-disk-io innodb-init-startup-configuration
glossary optimizing-innodb-diskio
innodb-memcached-tuning

See downgrading-to-previous-series
upgrading-from-previous-series
innodb-file-format-compatibility-checking downgrading
innodb-recovery glossary upgrading-strategies
server-shutdown

See innodb-parameters

See innodb-file-format-compatibility-checking-table-access
innodb-file-format-compatibility-checking
charset-unicode-conversion converting-tables-to-innodb
create-tablespace innodb-compression-usage
using-innodb-tables innodb-row-format-dynamic
innodb-file-format-enabling innodb-compression-internals
innodb-file-format-identifying innodb-file-format
general-tablespaces innodb-parameters glossary
innodb-compression-syntax-warnings

See innodb-file-format-compatibility-checking-table-access
innodb-file-format-compatibility-checking innodb-file-format
See innodb-parameters

See create-tablespace innodb-file-format
innodb-parameters

See innodb-best-practices charset-unicode-conversion
converting-tables-to-innodb tablespace-copying
create-table create-tablespace
innodb-compression-usage tablespace-placing
using-innodb-tables innodb-row-format-dynamic
tablespace-enabling innodb-file-space
innodb-file-per-table-intro create-table-files flush
See innodb-compression-internals mysql-acid
innodb-multiple-tablespaces general-tablespaces
innodb-parameters innodb-tablespace-encryption
innodb-migration glossary
innodb-create-index-implementation optimize-table
innodb-truncate-table-reclaim-space
replication-solutions-partitioning partitioning-limitations
See innodb-compression-syntax-warnings
innodb-sys-tables-table innodb-sys-tablespaces-table
innodb-troubleshooting-datadict

See innodb-parameters sorted-index-builds
innodb-physical-structure mysql-nutshell

See innodb-parameters innodb-redo-log-buffer

See mysql-acid optimizing-innodb-transaction-management
See innodb-redo-log-buffer innodb-memcached-tuning

See innodb-doublewrite-buffer innodb-disk-io
innodb-multiple-tablespaces innodb-init-startup-configuration
See innodb-parameters windows-installation
optimizing-innodb-diskio server-status-variables
innodb-memcached-tuning

See innodb-lru-background-flushing glossary
optimizing-innodb-diskio innodb-buffer-pool

See innodb-performance-thread_io_rate innodb-parameters

See innodb-lru-background-flushing innodb-buffer-pool

See innodb-parameters

See drop-table forcing-innodb-recovery bug-reports
See innodb-recovery optimizing-innodb-transaction-management
See rebuilding-tables

See innodb-information-schema-fulltext_index-tables
innodb-parameters innodb-ft-being-deleted-table
innodb-ft-config-table innodb-ft-deleted-table
innodb-ft-index-cache-table innodb-ft-index-table-table

See innodb-fulltext-index
innodb-information-schema-fulltext_index-tables
innodb-parameters glossary innodb-ft-index-cache-table

See innodb-parameters

See fulltext-boolean fulltext-fine-tuning
innodb-parameters fulltext-natural-language

See fulltext-boolean fulltext-fine-tuning
fulltext-stopwords innodb-parameters
fulltext-search-ngram writing-full-text-plugins

See fulltext-boolean fulltext-fine-tuning
fulltext-stopwords innodb-parameters
fulltext-search-mecab fulltext-natural-language
fulltext-search-ngram writing-full-text-plugins

See fulltext-fine-tuning innodb-parameters
optimize-table

See innodb-parameters

See fulltext-boolean fulltext-fine-tuning
fulltext-stopwords innodb-parameters
fulltext-natural-language innodb-ft-default-stopword-table

See innodb-fulltext-index innodb-parameters

See innodb-fulltext-index
innodb-information-schema-fulltext_index-tables
innodb-parameters innodb-ft-index-cache-table

See fulltext-boolean fulltext-fine-tuning
fulltext-stopwords innodb-parameters
fulltext-natural-language innodb-ft-default-stopword-table

See innodb-performance-thread_io_rate
innodb-lru-background-flushing innodb-parameters
faqs-innodb-change-buffer optimizing-innodb-diskio
mysql-nutshell

See innodb-lru-background-flushing innodb-parameters
optimizing-innodb-diskio

See column-indexes charset-unicode-conversion
create-index create-table innodb-row-format-dynamic
See innodb-file-format innodb-row-format
innodb-parameters innodb-restrictions glossary
innodb-row-format-overview innodb-row-format-specification

See converting-tables-to-innodb innodb-deadlock-detection
See innodb-deadlocks innodb-parameters
internal-locking glossary replication-features-timeout
See replication-options-slave error-messages-server

See innodb-consistent-read innodb-locking
innodb-parameters innodb-locks-set glossary
innodb-transaction-isolation-levels

See innodb-init-startup-configuration innodb-parameters
See glossary optimizing-innodb-logging
innodb-redo-log-buffer

See innodb-parameters mysql-nutshell

See innodb-performance-compression-oltp
optimizing-innodb-diskio

See innodb-data-log-reconfiguration
innodb-read-only-instance innodb-lru-background-flushing
data-directory-initialization-mysqld
innodb-init-startup-configuration innodb-parameters
glossary mysql-install-db optimizing-innodb-diskio
See optimizing-innodb-logging using-system-variables

See innodb-data-log-reconfiguration
innodb-init-startup-configuration innodb-parameters
glossary optimizing-innodb-logging

See data-directory-initialization-mysqld
innodb-init-startup-configuration innodb-parameters
glossary mysql-install-db

See innodb-parameters optimizing-innodb-logging

See innodb-lru-background-flushing innodb-buffer-pool

See innodb-performance-adaptive_flushing
innodb-lru-background-flushing innodb-parameters
optimizing-innodb-diskio innodb-buffer-pool

See innodb-performance-adaptive_flushing
innodb-lru-background-flushing innodb-buffer-pool

See innodb-multi-versioning innodb-parameters
glossary

See innodb-parameters

See innodb-parameters truncate-undo-tablespace

See innodb-information-schema-metrics-table show-engine
See innodb-metrics-table

See innodb-information-schema-metrics-table show-engine
See innodb-metrics-table

See innodb-information-schema-metrics-table
innodb-metrics-table

See innodb-information-schema-metrics-table
innodb-metrics-table

See innodb-parameters innodb-performance-midpoint_insertion
See glossary innodb-buffer-pool

See innodb-parameters innodb-performance-midpoint_insertion
See innodb-buffer-pool-monitoring innodb-buffer-pool

See glossary innodb-create-index-implementation
innodb-create-index-concurrency

See server-system-variables

See fulltext-fine-tuning innodb-fulltext-index
innodb-information-schema-fulltext_index-tables optimize-table
See innodb-ft-index-table-table

See mysql-nutshell

See glossary mysql-nutshell

See converting-tables-to-innodb create-table
create-tablespace innodb-compression-usage
innodb-analyze-table-complexity innodb-file-space
innodb-compression-internals general-tablespaces
innodb-page-compression innodb-init-startup-configuration
See innodb-parameters innodb-restrictions
column-count-limit glossary optimizing-innodb-diskio
See optimizing-innodb-logging innodb-compression-background
See files-table innodb-sys-tablespaces-table
innodb-physical-structure innodb-memcached-troubleshoot
truncate-undo-tablespace

See converting-tables-to-innodb innodb-deadlocks
innodb-deadlocks-handling innodb-troubleshooting

See innodb-improved-purge-scheduling

See innodb-parameters truncate-undo-tablespace

See innodb-improved-purge-scheduling
innodb-performance-thread_io_rate innodb-parameters
glossary

See innodb-performance-read_ahead glossary
innodb-buffer-pool

See innodb-performance-read_ahead innodb-parameters
innodb-buffer-pool

See innodb-performance-multiple_io_threads
innodb-standard-monitor innodb-parameters
mysql-threads innodb-linux-native-aio

See innodb-undo-tablespace innodb-init-startup-configuration
See innodb-parameters server-status-variables
innodb-undo-logs

See innodb-parameters

See innodb-parameters glossary
innodb-create-index-concurrency

See innodb-performance-spin_lock_polling

See innodb-persistent-stats-auto-recalc
innodb-performance-optimizer-statistics
innodb-persistent-stats-table-configuration create-table
innodb-persistent-stats-tables-example

See innodb-persistent-stats-delete-marked innodb-parameters

See index-statistics glossary

See innodb-statistics-estimation

See analyze-table innodb-statistics-estimation
innodb-performance-optimizer-statistics
innodb-persistent-stats-table-configuration
innodb-persistent-stats create-index create-table
See innodb-analyze-table-complexity innodb-parameters
innodb-restrictions optimizing-innodb-many-tables

See innodb-persistent-stats-table-configuration
innodb-persistent-stats-pages-sampled
innodb-analyze-table-complexity innodb-parameters
innodb-restrictions

See innodb-statistics-estimation
innodb-analyze-table-complexity innodb-parameters
innodb-restrictions

See innodb-enabling-monitors mysql-nutshell

See innodb-enabling-monitors innodb-parameters
mysql-nutshell

See create-table create-tablespace
innodb-compression-internals innodb-parameters
glossary sql-mode innodb-compression-syntax-warnings

See innodb-parameters glossary
optimizing-innodb-transaction-management binary-log
innodb-memcached-tuning mysql-nutshell

See source-configuration-options

See innodb-parameters innodb-restrictions

See innodb-read-only-instance
innodb-init-startup-configuration innodb-parameters
glossary innodb-temporary-tablespace files-table
innodb-temp-table-info-table mysql-nutshell
temporary-files

See innodb-performance-thread_concurrency
innodb-standard-monitor innodb-parameters
faqs-thread-pool optimizing-innodb-configuration-variables

See innodb-performance-thread_concurrency innodb-parameters

See innodb-create-index-implementation
innodb-create-index-concurrency temporary-files

See innodb-read-only-instance innodb-undo-tablespace
innodb-init-startup-configuration innodb-parameters
truncate-undo-tablespace

See innodb-parameters truncate-undo-tablespace
mysql-nutshell

See innodb-parameters

See innodb-read-only-instance innodb-undo-tablespace
innodb-init-startup-configuration innodb-parameters
glossary truncate-undo-tablespace
innodb-undo-tablespace-intro

See innodb-parameters glossary
optimizing-innodb-diskio innodb-linux-native-aio

See innodb-performance-use_sys_malloc innodb-parameters
See mysql-nutshell

See innodb-performance-multiple_io_threads
innodb-standard-monitor innodb-parameters
mysql-threads innodb-linux-native-aio

See federated-usagenotes server-system-variables

See communication-errors mysql-real-connect
server-system-variables

See memory-use internal-temporary-tables
server-system-variables innodb-temporary-tablespace

[index top]

See bnl-bka-optimization nested-loop-joins
server-system-variables

[index top]

See server-system-variables

See optimizing-myisam-bulk-data-loading server-configuration
See converting-tables-to-innodb estimating-performance
memory-use myisam-repair
innodb-init-startup-configuration bugs
multiple-key-caches delete-optimization
repair-table-optimization key-cache-restructuring
server-status-variables server-system-variables
structured-system-variables myisam-key-cache

See midpoint-insertion server-system-variables
structured-system-variables

See key-cache-block-size key-cache-restructuring
server-system-variables structured-system-variables

See midpoint-insertion server-system-variables
structured-system-variables

See keyring-system-variables keyring-udfs-plugin-specific
See keyring-aws-plugin

See keyring-system-variables keyring-aws-plugin

See keyring-system-variables keyring-udfs-plugin-specific
See keyring-aws-plugin

See keyring-system-variables

See innodb-tablespace-encryption keyring-system-variables
See source-configuration-options
keyring-encrypted-file-plugin

See keyring-system-variables keyring-encrypted-file-plugin

See innodb-tablespace-encryption keyring-system-variables
See keyring-key-migration source-configuration-options
keyring-file-plugin writing-keyring-plugins

See keyring-system-variables keyring-okv-plugin

See keyring-system-variables keyring-key-migration

[index top]

See partitioning-limitations server-system-variables

See server-system-variables

See server-system-variables

See binary-log-mixed replication-features-variables
server-system-variables

See server-system-variables error-message-language

See server-system-variables error-message-language

See date-and-time-functions binary-log-mixed
locale-support replication-features-variables
server-system-variables string-functions

See server-system-variables

See load-xml

See load-data source-configuration-options
load-data-local server-system-variables

See server-system-variables

See server-system-variables

See replication-multi-source-adding-binlog-master
group-replication-requirements innodb-parameters
replication-features-transaction-inconsistencies
channels-startup-options innodb-memcached-replication

See server-system-variables

See replication-options-binary-log replication-options-gtids
See mysql-cluster-system-variables

See replication-options-binary-log

See replication-options-binary-log

See stored-programs-logging replication-options-binary-log
See faqs-stored-procs server-system-variables

See replication-options-binary-log

See server-system-variables show-create-user

See error-log-unix error-log-windows
osx-installation-launchd docker-mysql-more-topics
server-system-variables

See communication-errors error-log-filtering
binary-log-mixed gone-away
performance-schema-connection-attribute-tables
performance-schema-system-variables replication-options-slave
See server-options server-system-variables
mysql-nutshell

See log-destinations server-system-variables
query-log slow-query-log

See server-system-variables slow-query-log

See replication-options-binary-log
replication-gtids-concepts

See server-options server-system-variables
slow-query-log

See replication-options-slave slow-query-log

See replication-options-binary-log

See error-log-windows error-log-syslog using-systemd
See mysqld-safe server-system-variables

See error-log-syslog mysqld-safe
server-system-variables

See error-log-syslog server-system-variables

See error-log-syslog mysqld-safe
server-system-variables

See server-system-variables slow-query-log

See error-log-format server-system-variables
query-log slow-query-log

See replication-options-slave server-options
server-system-variables mysql-nutshell

See server-logs mysqladmin replication-options-slave
See server-status-variables server-system-variables
slow-query-log

See server-system-variables table-locking

See server-system-variables

See grant replication-rules bug-reports
identifier-case-sensitivity replication-features-variables
See revoke server-system-variables show-tables
innodb-sys-columns-table innodb-sys-tables-table
charset-collation-information-schema create-table-foreign-keys

[index top]

See group-replication-requirements

See replication-solutions-unexpected-slave-halt slave-logs
See replication-options-slave slave-logs-status

See replication-options-binary-log glossary
binary-log

See group-by-functions communication-errors
comparison-operators storage-requirements
deleting-from-related-tables memory-use
error-lost-connection c-api gone-away
mysql-options mysql-stmt-send-long-data
mysql-use-result mysql-cluster-replication-conflict-resolution
See packet-too-large replication-features-max-allowed-packet
See replication-options-slave server-system-variables
string-functions blob json
version-tokens-usage x-plugin-system-variables-options

See replication-options-binary-log binary-log

See replication-options-binary-log server-logs
replication-options-slave log-file-maintenance
server-system-variables binary-log slave-logs-relaylog

See replication-options-binary-log

See host-cache flush blocked-host
server-system-variables host-cache-table

See using-gdb-on-mysqld not-enough-file-handles
table-cache connection-threads
performance-schema-system-variables privileges-provided
server-options server-status-variables
server-system-variables thread-pool-operation
too-many-connections x-plugin-system-variables-options

See server-system-variables

See memory-use performance-schema-statement-digests
performance-schema-system-variables server-system-variables
See firewall-usage

See diagnostics-area-system-variables load-data
resignal server-system-variables show-errors
show-warnings

See optimizer-hints server-status-variables
server-system-variables

See memory-use internal-temporary-tables
table-size-limit replication-features-memory
replication-features-variables cursor-restrictions
server-status-variables server-system-variables
memory-storage-engine

See server-system-variables

See explain-output server-system-variables
set-variable using-system-variables

See order-by-optimization server-system-variables

See server-system-variables spatial-operator-functions

See statement-caching deallocate-prepare
performance-schema-system-variables
sql-syntax-prepared-statements server-status-variables
server-system-variables

See replication-options-binary-log replication-options-slave
See server-system-variables slave-logs-relaylog

See innodb-restrictions server-system-variables

See bugs order-by-optimization select
server-system-variables blob json

See server-system-variables stored-routines-syntax

See server-system-variables

See server-system-variables

See alter-user create-user flush
security-against-attack server-system-variables
user-resources

See server-system-variables table-locking

See fulltext-search-mecab

See server-system-variables mysql-nutshell

See server-system-variables mysql-nutshell

See server-system-variables slow-query-log

See server-system-variables

See create-table table-size-limit
server-system-variables

See myisam-start repair-table-optimization
partitioning-limitations server-system-variables

See server-system-variables

See server-system-variables

See server-system-variables

See alter-table myisam-start
repair-table-optimization server-system-variables

See index-statistics server-system-variables

See memory-use server-system-variables

See firewall-system-variables firewall-usage

See firewall-system-variables firewall-usage

See proxy-users server-system-variables

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

See x-plugin-system-variables-options

[index top]

See server-system-variables

See mysql-cluster-system-variables
mysql-cluster-programs-ndb-import

See mysql-cluster-system-variables mysql-nutshell

See mysql-cluster-system-variables reset-slave

See mysql-cluster-system-variables
create-table-ndb-table-comment-options
mysql-cluster-what-is-new-7-5

See mysql-cluster-system-variables
mysql-cluster-what-is-new-7-5

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-logs-event-buffer
mysql-cluster-system-variables

See mysql-cluster-logs-event-buffer
mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See explain-output mysql-cluster-system-variables

See mysql-cluster-replication-multi-master
mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-program-options-mysqld
mysql-cluster-replication-conflict-resolution
mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables
mysql-cluster-tcp-definition mysql-cluster-log-statistics

See mysql-cluster-system-variables
create-table-ndb-table-comment-options
mysql-cluster-what-is-new-7-5

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-logs-event-buffer
mysql-cluster-system-variables

See mysql-cluster-logs-event-buffer
mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-replication-conflict-resolution
mysql-cluster-system-variables

See mysql-cluster-system-variables
create-table-ndb-table-comment-options

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See mysql-cluster-system-variables
mysql-cluster-ndbinfo-cluster-operations
mysql-cluster-ndbinfo-cluster-transactions
mysql-cluster-ndbinfo-server-operations
mysql-cluster-ndbinfo-server-transactions

See mysql-cluster-system-variables

See mysql-cluster-system-variables

See memory-use c-api mysql-options mysqldump
See mysqlpump server-system-variables

See error-lost-connection server-system-variables

See server-system-variables

See server-system-variables

See partitioning-limitations-storage-engines
server-system-variables

See fulltext-boolean fulltext-fine-tuning
fulltext-stopwords fulltext-natural-language
fulltext-search-ngram

[index top]

See privileges-provided server-system-variables

See index-hints server-system-variables

See alter-table innodb-create-index-concurrency
innodb-online-ddl-syntax optimize-table
server-system-variables innodb-online-ddl-single-multi

See upgrading-from-previous-series encryption-functions
See expired-password-handling password-hashing
password-management server-system-variables
set-password mysql-nutshell

See not-enough-file-handles
performance-schema-system-variables partitioning-limitations
See server-system-variables

See controlling-query-plan-evaluation optimizer-hints
semi-joins server-system-variables

See controlling-query-plan-evaluation
server-system-variables

See bnl-bka-optimization upgrading-from-previous-series
See condition-pushdown-optimization
index-condition-pushdown-optimization index-merge-optimization
See mrr-optimization optimizer-hints
derived-table-optimization subquery-materialization
subquery-optimization-with-exists semi-joins
error-messages-server server-system-variables
switchable-optimizations sys-list-add index-extensions
See view-algorithms mysql-nutshell

See server-system-variables optimizer-trace-table

See server-system-variables

See server-system-variables

See server-system-variables

See server-system-variables

[index top]

See server-system-variables

See performance-schema-quick-start
performance-schema-startup-configuration
performance-schema-system-variables

See performance-schema-status-variable-tables
performance-schema-system-variables
performance-schema-status-variable-summary-tables
accounts-table

See performance-schema-statement-digests
performance-schema-status-variables
performance-schema-system-variables statement-summary-tables

See performance-schema-system-variables
events-stages-history-long-table

See performance-schema-system-variables
events-stages-history-table

See performance-schema-system-variables
events-statements-history-long-table

See performance-schema-system-variables
events-statements-history-table

See performance-schema-system-variables
events-transactions-history-long-table

See performance-schema-system-variables
events-transactions-history-table

See performance-schema-system-variables
performance-schema-table-descriptions show-engine
events-waits-history-long-table

See performance-schema-system-variables
performance-schema-table-descriptions show-engine
events-waits-history-table

See performance-schema-status-variable-tables
performance-schema-system-variables
performance-schema-status-variable-summary-tables hosts-table

See performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-statement-digests
performance-schema-system-variables server-system-variables
See events-statements-current-table

See performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-status-variables
performance-schema-system-variables metadata-locks-table

See performance-schema-status-monitoring
performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-status-variables
performance-schema-system-variables
prepared-statements-instances-table

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-statement-digests
performance-schema-system-variables
events-statements-current-table

See performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-status-variables
performance-schema-system-variables table-handles-table

See performance-schema-system-variables

See performance-schema-status-variables
performance-schema-system-variables

See performance-schema-system-variables

See performance-schema-status-variable-tables
performance-schema-status-variables
performance-schema-system-variables show-engine

See performance-schema-connection-attribute-tables
performance-schema-status-variables
performance-schema-system-variables

See performance-schema-system-variables setup-actors-table

See performance-schema-system-variables setup-objects-table

See performance-schema-status-variable-tables
performance-schema-system-variables
performance-schema-status-variable-summary-tables users-table

See osx-installation-launchd server-system-variables

See password-security-admin compiling-plugin-libraries
connection-control-installation create-function-udf
enterprise-encryption-installation
data-directory-initialization install-plugin
osx-installation-launchd server-plugin-loading
keyring-udf-installation audit-log-installation
locking-service-udf-installation version-tokens-installation
See keyring-options keyring-installation
ldap-pluggable-authentication security-against-attack
no-login-pluggable-authentication pam-pluggable-authentication
See validate-password-installation pluggable-storage
plugin-api-components pluggable-authentication-restrictions
See replication-semisync-installation server-options
server-system-variables innodb-memcached-setup
show-plugins socket-pluggable-authentication
test-pluggable-authentication plugins-table
thread-pool-installation udf-compiling udf-security
See writing-authentication-plugins-setup
using-own-protocol-trace-plugins
windows-pluggable-authentication writing-audit-plugins
writing-daemon-plugins writing-full-text-plugins
writing-information-schema-plugins writing-keyring-plugins
See writing-password-validation-plugins
writing-semisynchronous-replication-plugins

See can-not-connect-to-server
group-replication-frequently-asked-questions
server-system-variables replication-group-members-table
mysql-innodb-cluster-using-router
x-plugin-system-variables-options

See server-system-variables

See server-system-variables show-profile
profiling-table

See server-system-variables show-profile

See server-system-variables

See proxy-users server-system-variables

See server-system-variables

See binary-log-mixed replication-features-variables
server-system-variables

[index top]

See server-system-variables

See query-cache-configuration server-system-variables
mysql-nutshell

See query-cache-configuration server-system-variables
mysql-nutshell

See query-cache-configuration server-system-variables
query-cache mysql-nutshell

See query-cache-configuration query-cache-in-select
select server-status-variables server-system-variables
See mysql-nutshell

See server-system-variables mysql-nutshell

See server-system-variables

[index top]

See server-system-variables

See server-system-variables

See range-optimization server-system-variables

See server-system-variables

See memory-use repair-table-optimization
server-system-variables

See account-management-sql alter-user
assigning-passwords replication-solutions-backups-read-only
See create-user drop-user general-thread-states
See grant privileges-provided rename-user
replication-features-variables revoke log-destinations
See server-system-variables set-password
replication-gtids-howto commit

See server-configuration memory-use mrr-optimization
See order-by-optimization server-system-variables

See group-replication-requirements channels-startup-options

See group-replication-frequently-asked-questions
replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-options-slave

See replication-solutions-unexpected-slave-halt slave-logs
See replication-options-slave slave-logs-status

See change-master-to server-system-variables
show-slave-status

See replication-solutions-unexpected-slave-halt
replication-options-slave

See slave-io-thread-states server-system-variables
channels-startup-options

See group-replication-configuring-instances
mysql-innodb-cluster-production-deployment
server-system-variables group-replication-user-credentials

See server-system-variables

See server-system-variables

See server-system-variables

See using-encrypted-connections error-messages-server
server-system-variables encrypted-connections
x-plugin-ssl-connections

See rewriter-query-rewrite-plugin-system-variables
rewriter-query-rewrite-plugin-usage

See rewriter-query-rewrite-plugin-system-variables

See replication-semisync-interface
replication-semisync-installation
replication-semisync-monitoring server-system-variables

See replication-semisync-interface
replication-semisync-installation server-system-variables

See server-system-variables

See replication-semisync server-system-variables

See server-system-variables

See replication-semisync server-system-variables

See replication-semisync-interface
replication-semisync-installation server-system-variables

See server-system-variables

See replication-features-transaction-inconsistencies
replication-options-slave stop-slave

[index top]

See upgrading-from-previous-series account-upgrades
password-hashing server-system-variables
mysql-nutshell

See data-directory-initialization linux-installation-rpm
See load-data security-against-attack
source-configuration-options privileges-provided
libmysqld-restrictions select-into server-options
See server-system-variables string-functions

See group-replication-adding-a-second-instance
audit-log-file-formats group-replication-configuring-instances
See miscellaneous-functions
mysql-cluster-program-options-mysqld mysqlbinlog
mysql-cluster-replication-conflict-resolution
mysql-cluster-system-variables
performance-schema-replication-tables server-system-variables
See replication-gtids-howto show-slave-status
replication-rbr-usage

See mysql-cluster-program-options-mysqld
mysql-cluster-system-variables

See replication-gtids-concepts
performance-schema-replication-tables
mysql-innodb-cluster-production-deployment replication-options
See replication-gtids-howto show-slave-status
group-replication-single-primary-mode start-slave
replication-connection-status-table replication-upgrade
mysql-innodb-cluster-using-router

See mysql-session-track-get-first
replication-mode-change-online-concepts
server-system-variables

See mysql-session-track-get-first server-system-variables

See mysql-session-track-get-first server-system-variables

See mysql-session-track-get-first server-system-variables

See creating-ssl-rsa-files-using-mysql ssl-libraries
proxy-users server-status-variables
server-system-variables sha256-pluggable-authentication
encrypted-connections

See error-messages-server server-system-variables

See server-system-variables

See upgrading-from-previous-series flush
performance-schema-variable-table-migration
performance-schema-status-variable-tables
performance-schema-system-variable-tables
server-status-variables server-system-variables
show-status show-variables
performance-schema-status-variable-summary-tables status-table
See variables-table mysql-nutshell

See server-system-variables

See server-system-variables

See replication-options-gtids

See external-locking server-system-variables

See server-system-variables

See server-system-variables
x-plugin-monitoring-status-variables

See server-options server-system-variables

See group-replication-requirements
replication-features-transaction-inconsistencies
replication-options-slave channels-startup-options

See mysql-cluster-system-variables
mysql-cluster-replication-starting

See mysql-cluster-replication-issues miscellaneous-functions
See replication-options-slave

See miscellaneous-functions replication-options-slave

See replication-options-slave

See mysql-cluster-replication-issues
replication-features-memory replication-options-slave
replication-rbr-usage

See load-data replication-options-slave
server-system-variables

See replication-options-slave

See change-master-to replication-administration-status
replication-features-shutdowns slave-io-thread-states
replication-options-slave server-system-variables

See replication-options-binary-log
replication-features-transaction-inconsistencies
replication-options-slave

See change-master-to mysql-cluster-replication-issues
performance-schema-replication-tables
replication-features-transaction-inconsistencies
replication-options-slave slave-sql-thread-states
stop-slave

See replication-options-slave slave-sql-thread-states

See replication-features-transaction-inconsistencies
slave-io-thread-states replication-options-slave

See replication-options-slave server-status-variables

See replication-options-slave

See glossary replication-options-slave binary-log

See replication-features-timeout replication-options-slave
See channels-startup-options

See mysql-cluster-replication-issues
replication-options-slave

See server-status-variables server-system-variables

See log-destinations server-system-variables
slow-query-log

See log-destinations server-system-variables
slow-query-log

See server-system-variables
x-plugin-system-variables-options

See myisam-repair order-by-optimization
server-options server-status-variables
server-system-variables

See comparison-operators create-table
binary-log-mixed replication-features-variables
server-system-variables binary-log

See server-system-variables

See server-system-variables

See replication-options-binary-log
mysql-cluster-limitations-exclusive-to-cluster
mysql-cluster-replication-issues
mysql-cluster-limitations-syntax privileges-provided
replication-options-reference server-system-variables
set-sql-log-bin set-variable sys-diagnostics
sys-ps-setup-reload-saved sys-ps-setup-save
sys-ps-trace-statement-digest sys-ps-trace-thread
sys-statement-performance-analyzer replication-upgrade
using-system-variables mysql-nutshell

See replication-options-binary-log glossary
privileges-provided replication-options-reference
log-destinations server-system-variables query-log

See innodb-create-index-overview

See innodb-best-practices upgrading-from-previous-series
See create-event create-procedure create-trigger
See signal-effects precision-math-expressions
fractional-seconds bug-reports load-data
binary-log-mixed compatibility mysql-install-db
using-date replication-features-variables sql-mode
See server-system-variables show-create-view
binary-log views-table sys-list-add
option-files using-system-variables mysql-nutshell

See diagnostics-area-system-variables
server-system-variables show-warnings

See server-system-variables show-create-database
show-create-table

See server-system-variables

See server-system-variables

See replication-mode-change-online-concepts
replication-options-slave replication-gtids-restrictions
show-slave-status

See server-system-variables

See using-encrypted-connections
creating-ssl-rsa-files-using-mysql server-system-variables
See x-plugin-system-variables-options

See server-system-variables
x-plugin-system-variables-options

See using-encrypted-connections
creating-ssl-rsa-files-using-mysql server-system-variables
See x-plugin-system-variables-options

See server-system-variables
x-plugin-system-variables-options

See server-system-variables
x-plugin-system-variables-options

See server-system-variables
x-plugin-system-variables-options

See using-encrypted-connections
creating-ssl-rsa-files-using-mysql server-system-variables
See x-plugin-system-variables-options

See create-logfile-group replication-features-variables
See server-system-variables
replication-solutions-diffengines mysql-nutshell

See statement-caching server-system-variables

See group-replication-single-primary-mode

See group-replication-adding-a-second-instance
mysql-innodb-cluster-from-group-replication
group-replication-server-states group-replication-options
See mysql-innodb-cluster-production-deployment
mysql-innodb-cluster-sandbox-deployment
server-system-variables start-group-replication
stop-group-replication group-replication-enterprise-backup
See mysql-innodb-cluster-working-with-cluster

See replication-options-binary-log
replication-solutions-unexpected-slave-halt mysql-acid
innodb-parameters replication-features-shutdowns
binary-log

See server-system-variables mysql-nutshell

See replication-options-slave

See replication-solutions-unexpected-slave-halt
replication-options-slave

See replication-features-shutdowns replication-options-slave

See time-zone-support server-options
server-system-variables

[index top]

See memory-use server-system-variables

See server-configuration not-enough-file-handles
general-thread-states table-cache memory-use
innodb-parameters server-options
server-status-variables server-system-variables

See server-status-variables server-system-variables

See using-gdb-on-mysqld connection-threads
server-status-variables server-system-variables

See server-system-variables

See server-system-variables thread-pool-components

See server-system-variables tp-thread-group-state-table
See thread-pool-components

See server-system-variables thread-pool-components
thread-pool-operation

See server-system-variables thread-pool-components

See server-system-variables tp-thread-group-state-table
See tp-thread-group-stats-table thread-pool-components
thread-pool-operation thread-pool-tuning

See server-system-variables thread-pool-components
thread-pool-operation thread-pool-tuning

See server-system-variables tp-thread-group-state-table
See tp-thread-group-stats-table thread-pool-components
thread-pool-operation thread-pool-tuning

See memory-use server-system-variables
stored-routines-syntax

See server-system-variables

See create-event date-and-time-functions
events-metadata binary-log-mixed time-zone-support
See replication-features-variables server-options
server-system-variables datetime query-log
slow-query-log

See server-system-variables mysql-nutshell

See federated-usagenotes binary-log-mixed
replication-features-variables server-system-variables

See encrypted-connection-options using-encrypted-connections
See encrypted-connection-protocols-ciphers
server-system-variables
replication-solutions-encrypted-connections
encrypted-connections x-plugin-ssl-connections

See memory-use internal-temporary-tables
cursor-restrictions server-status-variables
server-system-variables

See replication-solutions-backups-rawdata cannot-create
See backup-methods innodb-parameters load-data
source-configuration-options
innodb-create-index-implementation
innodb-create-index-concurrency order-by-optimization
replication-options-slave server-system-variables
innodb-temp-table-info-table temporary-files

See group-replication-requirements

See server-system-variables

See mysql-cluster-system-variables

See server-options server-system-variables
set-transaction mysql-nutshell

See server-system-variables

See server-options server-system-variables
set-transaction mysql-nutshell

See replication-options-binary-log
group-replication-configuring-instances error-messages-server
See server-system-variables

See server-options server-system-variables
set-transaction mysql-nutshell

See server-options server-system-variables
set-transaction mysql-nutshell

[index top]

See converting-tables-to-innodb binary-log-mixed
replication-features-variables server-system-variables
binary-log

See server-system-variables view-updatability

[index top]

See encryption-functions validate-password-options-variables
See validate-password

See validate-password-options-variables validate-password

See encryption-functions validate-password-options-variables
See validate-password

See validate-password-options-variables validate-password

See validate-password-options-variables validate-password

See validate-password-options-variables validate-password

See validate-password-options-variables validate-password

See server-system-variables

See audit-log-file-formats information-functions
innodb-parameters server-system-variables

See server-system-variables show-variables

See server-system-variables

See server-system-variables

See error-messages-server version-tokens-usage
version-tokens-reference

See version-tokens-reference

[index top]

See communication-errors gone-away
mysql-real-connect server-system-variables

See diagnostics-area-system-variables signal-effects
sql-syntax-prepared-statements server-system-variables
show-errors show-warnings error-sources

R | S

[index top]

See innodb-consistent-read mysql-cluster-ndb-innodb-engines
See group-replication-limitations innodb-deadlocks-handling
See innodb-locking innodb-parameters
mysql-cluster-limitations-transactions innodb-locks-set
faqs-general faqs-mysql-cluster
mysql-cluster-ndb-innodb-usage
optimizing-innodb-transaction-management binary-log-setting
See events-transactions-current-table
innodb-transaction-isolation-levels truncate-table

See innodb-consistent-read
innodb-persistent-stats-delete-marked innodb-memcached-intro
See innodb-parameters mysql-cluster-limitations-transactions
See innodb-memcached-ddl binary-log-setting
events-transactions-current-table
innodb-transaction-isolation-levels truncate-table

See server-options set-transaction

See server-options set-transaction

See innodb-consistent-read innodb-memcached-txn
group-replication-limitations innodb-locking
innodb-parameters mysql-cluster-limitations-transactions
binary-log-mixed mysqldump mysqlpump
optimizing-innodb-transaction-management
performance-schema-transaction-tables set-transaction
commit events-transactions-current-table
innodb-transaction-isolation-levels xa

See server-options server-system-variables
set-transaction

[index top]

See innodb-consistent-read group-replication-limitations
See query-cache-operation innodb-locking
innodb-parameters mysql-cluster-limitations-transactions
innodb-locks-set binary-log-mixed
performance-schema-transaction-tables server-options
set-transaction commit
events-transactions-current-table
innodb-transaction-isolation-levels xa

Appendix E MySQL Glossary
*************************

These terms are commonly used in information about the MySQL database
server.  This glossary originated as a reference for terminology about
the InnoDB storage engine, and the majority of definitions are
InnoDB-related.

ACID

An acronym standing for atomicity, consistency, isolation, and
durability.  These properties are all desirable in a database system,
and are all closely tied to the notion of a *transaction*.  The
transactional features of 'InnoDB' adhere to the ACID principles.

Transactions are *atomic* units of work that can be *committed* or
*rolled back*.  When a transaction makes multiple changes to the
database, either all the changes succeed when the transaction is
committed, or all the changes are undone when the transaction is rolled
back.

The database remains in a consistent state at all times -- after each
commit or rollback, and while transactions are in progress.  If related
data is being updated across multiple tables, queries see either all old
values or all new values, not a mix of old and new values.

Transactions are protected (isolated) from each other while they are in
progress; they cannot interfere with each other or see each other's
uncommitted data.  This isolation is achieved through the *locking*
mechanism.  Experienced users can adjust the *isolation level*, trading
off less protection in favor of increased performance and *concurrency*,
when they can be sure that the transactions really do not interfere with
each other.

The results of transactions are durable: once a commit operation
succeeds, the changes made by that transaction are safe from power
failures, system crashes, race conditions, or other potential dangers
that many non-database applications are vulnerable to.  Durability
typically involves writing to disk storage, with a certain amount of
redundancy to protect against power failures or software crashes during
write operations.  (In 'InnoDB', the *doublewrite buffer* assists with
durability.)  adaptive flushing

An algorithm for *InnoDB* tables that smooths out the I/O overhead
introduced by *checkpoints*.  Instead of *flushing* all modified *pages*
from the *buffer pool* to the *data files* at once, MySQL periodically
flushes small sets of modified pages.  The adaptive flushing algorithm
extends this process by estimating the optimal rate to perform these
periodic flushes, based on the rate of flushing and how fast *redo*
information is generated.  adaptive hash index

An optimization for 'InnoDB' tables that can speed up lookups using '='
and 'IN' operators, by constructing a *hash index* in memory.  MySQL
monitors index searches for 'InnoDB' tables, and if queries could
benefit from a hash index, it builds one automatically for index *pages*
that are frequently accessed.  In a sense, the adaptive hash index
configures MySQL at runtime to take advantage of ample main memory,
coming closer to the architecture of main-memory databases.  This
feature is controlled by the 'innodb_adaptive_hash_index' configuration
option.  Because this feature benefits some workloads and not others,
and the memory used for the hash index is reserved in the *buffer pool*,
typically you should benchmark with this feature both enabled and
disabled.

The hash index is always built based on an existing *B-tree* index on
the table.  MySQL can build a hash index on a prefix of any length of
the key defined for the B-tree, depending on the pattern of searches
against the index.  A hash index can be partial; the whole B-tree index
does not need to be cached in the buffer pool.

In MySQL 5.6 and higher, another way to take advantage of fast
single-value lookups with 'InnoDB' tables is to use the 'InnoDB'
*memcached* plugin.  See innodb-memcached for details.  AHI

Acronym for *adaptive hash index*.  AIO

Acronym for *asynchronous I/O*. You might see this acronym in 'InnoDB'
messages or keywords.  Antelope

The code name for the original 'InnoDB' *file format*.  It supports the
*REDUNDANT* and *COMPACT* row formats, but not the newer *DYNAMIC* and
*COMPRESSED* row formats available in the *Barracuda* file format.
application programming interface (API)

A set of functions or procedures.  An API provides a stable set of names
and types for functions, procedures, parameters, and return values.
apply

When a backup produced by the *MySQL Enterprise Backup* product does not
include the most recent changes that occurred while the backup was
underway, the process of updating the backup files to include those
changes is known as the *apply* step.  It is specified by the
'apply-log' option of the 'mysqlbackup' command.

Before the changes are applied, we refer to the files as a *raw backup*.
After the changes are applied, we refer to the files as a *prepared
backup*.  The changes are recorded in the *ibbackup_logfile* file; once
the apply step is finished, this file is no longer necessary.  .ARM file

Metadata for 'ARCHIVE' tables.  Contrast with *.ARZ file*.  Files with
this extension are always included in backups produced by the
'mysqlbackup' command of the *MySQL Enterprise Backup* product.  .ARZ
file

Data for ARCHIVE tables.  Contrast with *.ARM file*.  Files with this
extension are always included in backups produced by the 'mysqlbackup'
command of the *MySQL Enterprise Backup* product.  asynchronous I/O

A type of I/O operation that allows other processing to proceed before
the I/O is completed.  Also known as *nonblocking I/O* and abbreviated
as *AIO*. 'InnoDB' uses this type of I/O for certain operations that can
run in parallel without affecting the reliability of the database, such
as reading pages into the *buffer pool* that have not actually been
requested, but might be needed soon.

Historically, 'InnoDB' used asynchronous I/O on Windows systems only.
Starting with the InnoDB Plugin 1.1 and MySQL 5.5, 'InnoDB 'uses
asynchronous I/O on Linux systems.  This change introduces a dependency
on 'libaio'.  Asynchronous I/O on Linux systems is configured using the
'innodb_use_native_aio' option, which is enabled by default.  On other
Unix-like systems, InnoDB uses synchronous I/O only.  atomic

In the SQL context, *transactions* are units of work that either succeed
entirely (when *committed*) or have no effect at all (when *rolled
back*).  The indivisible ("atomic") property of transactions is the 'A'
in the acronym *ACID*. atomic DDL

An atomic _DDL_ statement is one that combines the _data dictionary_
updates, _storage engine_ operations, and _binary log_ writes associated
with a DDL operation into a single, atomic transaction.  The transaction
is either fully committed or rolled back, even if the server halts
during the operation.  Atomic DDL support was added in MySQL 8.0.  For
more information, see Atomic Data Definition Statement Support
(http://dev.mysql.com/doc/refman/8.0/en/atomic-ddl.html).  atomic
instruction

Special instructions provided by the CPU, to ensure that critical
low-level operations cannot be interrupted.  auto-increment

A property of a table column (specified by the 'AUTO_INCREMENT' keyword)
that automatically adds an ascending sequence of values in the column.

It saves work for the developer, not to have to produce new unique
values when inserting new rows.  It provides useful information for the
query optimizer, because the column is known to be not null and with
unique values.  The values from such a column can be used as lookup keys
in various contexts, and because they are auto-generated there is no
reason to ever change them; for this reason, primary key columns are
often specified as auto-incrementing.

Auto-increment columns can be problematic with statement-based
replication, because replaying the statements on a slave might not
produce the same set of column values as on the master, due to timing
issues.  When you have an auto-incrementing primary key, you can use
statement-based replication only with the setting
'innodb_autoinc_lock_mode=1'.  If you have 'innodb_autoinc_lock_mode=2',
which allows higher concurrency for insert operations, use *row-based
replication* rather than *statement-based replication*.  The setting
'innodb_autoinc_lock_mode=0' should not be used except for compatibility
purposes.

Consecutive lock mode ('innodb_autoinc_lock_mode=1') is the default
setting prior to MySQL 8.0.3.  As of MySQL 8.0.3, interleaved lock mode
('innodb_autoinc_lock_mode=2') is the default, which reflects the change
from statement-based to row-based replication as the default replication
type.  auto-increment locking

The convenience of an *auto-increment* primary key involves some
tradeoff with concurrency.  In the simplest case, if one transaction is
inserting values into the table, any other transactions must wait to do
their own inserts into that table, so that rows inserted by the first
transaction receive consecutive primary key values.  'InnoDB' includes
optimizations and the 'innodb_autoinc_lock_mode' option so that you can
configure and optimal balance between predictable sequences of
auto-increment values and maximum *concurrency* for insert operations.
autocommit

A setting that causes a *commit* operation after each *SQL* statement.
This mode is not recommended for working with 'InnoDB' tables with
*transactions* that span several statements.  It can help performance
for *read-only transactions* on 'InnoDB' tables, where it minimizes
overhead from *locking* and generation of *undo* data, especially in
MySQL 5.6.4 and up.  It is also appropriate for working with
'MyISAM' tables, where transactions are not
applicable.  availability

The ability to cope with, and if necessary recover from, failures on the
host, including failures of MySQL, the operating system, or the hardware
and maintenance activity that may otherwise cause downtime.  Often
paired with *scalability* as critical aspects of a large-scale
deployment.

B-tree

A tree data structure that is popular for use in database indexes.  The
structure is kept sorted at all times, enabling fast lookup for exact
matches (equals operator) and ranges (for example, greater than, less
than, and 'BETWEEN' operators).  This type of index is available for
most storage engines, such as 'InnoDB' and
'MyISAM'.

Because B-tree nodes can have many children, a B-tree is not the same as
a binary tree, which is limited to 2 children per node.

Contrast with *hash index*, which is only available in the
'MEMORY' storage engine.  The 'MEMORY' storage
engine can also use B-tree indexes, and you should choose B-tree indexes
for 'MEMORY' tables if some queries use range operators.

The use of the term B-tree is intended as a reference to the general
class of index design.  B-tree structures used by MySQL storage engines
may be regarded as variants due to sophistications not present in a
classic B-tree design.  For related information, refer to the 'InnoDB'
Page Structure Fil Header
(https://dev.mysql.com/doc/internals/en/innodb-fil-header.html) section
of the MySQL Internals Manual
(https://dev.mysql.com/doc/internals/en/index.html).  backticks

Identifiers within MySQL SQL statements must be quoted using the
backtick character ('`') if they contain special characters or reserved
words.  For example, to refer to a table named 'FOO#BAR' or a column
named 'SELECT', you would specify the identifiers as '`FOO#BAR`' and
'`SELECT`'.  Since the backticks provide an extra level of safety, they
are used extensively in program-generated SQL statements, where the
identifier names might not be known in advance.

Many other database systems use double quotation marks ('"') around such
special names.  For portability, you can enable 'ANSI_QUOTES' mode in
MySQL and use double quotation marks instead of backticks to qualify
identifier names.  backup

The process of copying some or all table data and metadata from a MySQL
instance, for safekeeping.  Can also refer to the set of copied files.
This is a crucial task for DBAs.  The reverse of this process is the
*restore* operation.

With MySQL, *physical backups* are performed by the *MySQL Enterprise
Backup* product, and *logical backups* are performed by the 'mysqldump'
command.  These techniques have different characteristics in terms of
size and representation of the backup data, and speed (especially speed
of the restore operation).

Backups are further classified as *hot*, *warm*, or *cold* depending on
how much they interfere with normal database operation.  (Hot backups
have the least interference, cold backups the most.)  Barracuda

The code name for an 'InnoDB' *file format* that supports the
*COMPRESSED* row format that enables InnoDB table compression, and the
*DYNAMIC* row format that improves the storage layout for long
variable-length columns.

The *MySQL Enterprise Backup* product version 3.5 and above supports
backing up tablespaces that use the Barracuda file format.  base column

A non-generated table column upon which a stored generated column or
virtual generated column is based.  In other words, a base column is a
non-generated table column that is part of a generated column
definition.  beta

An early stage in the life of a software product, when it is available
only for evaluation, typically without a definite release number or a
number less than 1.  'InnoDB' does not use the beta designation,
preferring an *early adopter* phase that can extend over several point
releases, leading to a *GA* release.  binary log

A file containing a record of all statements that attempt to change
table data.  These statements can be replayed to bring slave servers up
to date in a *replication* scenario, or to bring a database up to date
after restoring table data from a backup.  The binary logging feature
can be turned on and off, although Oracle recommends always enabling it
if you use replication or perform backups.

You can examine the contents of the binary log, or replay those
statements during replication or recovery, by using the
'mysqlbinlog' command.  For full information about the
binary log, see binary-log.  For MySQL configuration options
related to the binary log, see replication-options-binary-log.

For the *MySQL Enterprise Backup* product, the file name of the binary
log and the current position within the file are important details.  To
record this information for the master server when taking a backup in a
replication context, you can specify the '--slave-info' option.

Prior to MySQL 5.0, a similar capability was available, known as the
update log.  In MySQL 5.0 and higher, the binary log replaces the update
log.  binlog

An informal name for the *binary log* file.  For example, you might see
this abbreviation used in e-mail messages or forum discussions.  blind
query expansion

A special mode of *full-text search* enabled by the 'WITH QUERY
EXPANSION' clause.  It performs the search twice, where the search
phrase for the second search is the original search phrase concatenated
with the few most highly relevant documents from the first search.  This
technique is mainly applicable for short search phrases, perhaps only a
single word.  It can uncover relevant matches where the precise search
term does not occur in the document.  bottleneck

A portion of a system that is constrained in size or capacity, that has
the effect of limiting overall throughput.  For example, a memory area
might be smaller than necessary; access to a single required resource
might prevent multiple CPU cores from running simultaneously; or waiting
for disk I/O to complete might prevent the CPU from running at full
capacity.  Removing bottlenecks tends to improve *concurrency*.  For
example, the ability to have multiple 'InnoDB' *buffer pool* instances
reduces contention when multiple sessions read from and write to the
buffer pool simultaneously.  bounce

A *shutdown* operation immediately followed by a restart.  Ideally with
a relatively short *warmup* period so that performance and throughput
quickly return to a high level.  buddy allocator

A mechanism for managing different-sized *pages* in the InnoDB *buffer
pool*.  buffer

A memory or disk area used for temporary storage.  Data is buffered in
memory so that it can be written to disk efficiently, with a few large
I/O operations rather than many small ones.  Data is buffered on disk
for greater reliability, so that it can be recovered even when a *crash*
or other failure occurs at the worst possible time.  The main types of
buffers used by InnoDB are the *buffer pool*, the *doublewrite buffer*,
and the *change buffer*.  buffer pool

The memory area that holds cached 'InnoDB' data for both tables and
indexes.  For efficiency of high-volume read operations, the buffer pool
is divided into *pages* that can potentially hold multiple rows.  For
efficiency of cache management, the buffer pool is implemented as a
linked list of pages; data that is rarely used is aged out of the cache,
using a variation of the *LRU* algorithm.  On systems with large memory,
you can improve concurrency by dividing the buffer pool into multiple
*buffer pool instances*.

Several 'InnoDB' status variables, 'INFORMATION_SCHEMA' tables, and
'performance_schema' tables help to monitor the internal workings of the
buffer pool.  Starting in MySQL 5.6, you can avoid a lengthy warmup
period after restarting the server, particularly for instances with
large buffer pools, by saving the buffer pool state at server shutdown
and restoring the buffer pool to the same state at server startup.  See
innodb-preload-buffer-pool.  buffer pool instance

Any of the multiple regions into which the *buffer pool* can be divided,
controlled by the 'innodb_buffer_pool_instances' configuration option.
The total memory size specified by 'innodb_buffer_pool_size' is divided
among all buffer pool instances.  Typically, having multiple buffer pool
instances is appropriate for systems that allocate multiple gigabytes to
the 'InnoDB' buffer pool, with each instance being one gigabyte or
larger.  On systems loading or looking up large amounts of data in the
buffer pool from many concurrent sessions, having multiple buffer pool
instances reduces contention for exclusive access to data structures
that manage the buffer pool.  built-in

The built-in 'InnoDB' storage engine within MySQL is the original form
of distribution for the storage engine.  Contrast with the *InnoDB
Plugin*.  Starting with MySQL 5.5, the InnoDB Plugin is merged back into
the MySQL code base as the built-in 'InnoDB' storage engine (known as
InnoDB 1.1).

This distinction is important mainly in MySQL 5.1, where a feature or
bug fix might apply to the InnoDB Plugin but not the built-in 'InnoDB',
or vice versa.  business rules

The relationships and sequences of actions that form the basis of
business software, used to run a commercial company.  Sometimes these
rules are dictated by law, other times by company policy.  Careful
planning ensures that the relationships encoded and enforced by the
database, and the actions performed through application logic,
accurately reflect the real policies of the company and can handle
real-life situations.

For example, an employee leaving a company might trigger a sequence of
actions from the human resources department.  The human resources
database might also need the flexibility to represent data about a
person who has been hired, but not yet started work.  Closing an account
at an online service might result in data being removed from a database,
or the data might be moved or flagged so that it could be recovered if
the account is re-opened.  A company might establish policies regarding
salary maximums, minimums, and adjustments, in addition to basic sanity
checks such as the salary not being a negative number.  A retail
database might not allow a purchase with the same serial number to be
returned more than once, or might not allow credit card purchases above
a certain value, while a database used to detect fraud might allow these
kinds of things.

cache

The general term for any memory area that stores copies of data for
frequent or high-speed retrieval.  In 'InnoDB', the primary kind of
cache structure is the *buffer pool*.  cardinality

The number of different values in a table *column*.  When queries refer
to columns that have an associated *index*, the cardinality of each
column influences which access method is most efficient.  For example,
for a column with a *unique constraint*, the number of different values
is equal to the number of rows in the table.  If a table has a million
rows but only 10 different values for a particular column, each value
occurs (on average) 100,000 times.  A query such as 'SELECT c1 FROM t1
WHERE c1 = 50;' thus might return 1 row or a huge number of rows, and
the database server might process the query differently depending on the
cardinality of 'c1'.

If the values in a column have a very uneven distribution, the
cardinality might not be a good way to determine the best query plan.
For example, 'SELECT c1 FROM t1 WHERE c1 = x;' might return 1 row when
'x=50' and a million rows when 'x=30'.  In such a case, you might need
to use *index hints* to pass along advice about which lookup method is
more efficient for a particular query.

Cardinality can also apply to the number of distinct values present in
multiple columns, as in a *composite index*.  .cfg file

A metadata file used with the 'InnoDB' *transportable tablespace*
feature.  It is produced by the command 'FLUSH TABLES ... FOR EXPORT',
puts one or more tables in a consistent state that can be copied to
another server.  The '.cfg' file is copied along with the corresponding
*.ibd file*, and used to adjust the internal values of the '.ibd' file,
such as the *space ID*, during the 'ALTER TABLE ... IMPORT TABLESPACE'
step.  change buffer

A special data structure that records changes to *pages* in *secondary
indexes*.  These values could result from SQL 'INSERT',
'UPDATE', or 'DELETE' statements (*DML*).
The set of features involving the change buffer is known collectively as
*change buffering*, consisting of *insert buffering*, *delete
buffering*, and *purge buffering*.

Changes are only recorded in the change buffer when the relevant page
from the secondary index is not in the *buffer pool*.  When the relevant
index page is brought into the buffer pool while associated changes are
still in the change buffer, the changes for that page are applied in the
buffer pool (*merged*) using the data from the change buffer.
Periodically, the *purge* operation that runs during times when the
system is mostly idle, or during a slow shutdown, writes the new index
pages to disk.  The purge operation can write the disk blocks for a
series of index values more efficiently than if each value were written
to disk immediately.

Physically, the change buffer is part of the *system tablespace*, so
that the index changes remain buffered across database restarts.  The
changes are only applied (*merged*) when the pages are brought into the
buffer pool due to some other read operation.

The kinds and amount of data stored in the change buffer are governed by
the 'innodb_change_buffering' and 'innodb_change_buffer_max_size'
configuration options.  To see information about the current data in the
change buffer, issue the 'SHOW ENGINE INNODB STATUS'.
command.

Formerly known as the *insert buffer*.  change buffering

The general term for the features involving the *change buffer*,
consisting of *insert buffering*, *delete buffering*, and *purge
buffering*.  Index changes resulting from SQL statements, which could
normally involve random I/O operations, are held back and performed
periodically by a background *thread*.  This sequence of operations can
write the disk blocks for a series of index values more efficiently than
if each value were written to disk immediately.  Controlled by the
'innodb_change_buffering' and 'innodb_change_buffer_max_size'
configuration options.  checkpoint

As changes are made to data pages that are cached in the *buffer pool*,
those changes are written to the *data files* sometime later, a process
known as *flushing*.  The checkpoint is a record of the latest changes
(represented by an *LSN* value) that have been successfully written to
the data files.  checksum

In 'InnoDB', a validation mechanism to detect corruption when a *page*
in a *tablespace* is read from disk into the 'InnoDB' *buffer pool*.
This feature is controlled by the 'innodb_checksums' configuration
option in MySQL 5.5.  'innodb_checksums' is deprecated in MySQL 5.6.3,
replaced by 'innodb_checksum_algorithm'.

The 'innochecksum' command helps diagnose
corruption problems by testing the checksum values for a specified
*tablespace* file while the MySQL server is shut down.

MySQL also uses checksums for replication purposes.  For details, see
the configuration options 'binlog_checksum', 'master_verify_checksum',
and 'slave_sql_verify_checksum'.  child table

In a *foreign key* relationship, a child table is one whose rows refer
(or point) to rows in another table with an identical value for a
specific column.  This is the table that contains the 'FOREIGN KEY ...
REFERENCES' clause and optionally 'ON UPDATE' and 'ON DELETE' clauses.
The corresponding row in the *parent table* must exist before the row
can be created in the child table.  The values in the child table can
prevent delete or update operations on the parent table, or can cause
automatic deletion or updates in the child table, based on the 'ON
CASCADE' option used when creating the foreign key.  clean page

A *page* in the 'InnoDB' *buffer pool* where all changes made in memory
have also been written (*flushed*) to the data files.  The opposite of a
*dirty page*.  clean shutdown

A *shutdown* that completes without errors and applies all changes to
'InnoDB' tables before finishing, as opposed to a *crash* or a *fast
shutdown*.  Synonym for *slow shutdown*.  client

A type of program that sends requests to a *server*, and interprets or
processes the results.  The client software might run only some of the
time (such as a mail or chat program), and might run interactively (such
as the 'mysql' command processor).  clustered index

The 'InnoDB' term for a *primary key* index.  'InnoDB' table storage is
organized based on the values of the primary key columns, to speed up
queries and sorts involving the primary key columns.  For best
performance, choose the primary key columns carefully based on the most
performance-critical queries.  Because modifying the columns of the
clustered index is an expensive operation, choose primary columns that
are rarely or never updated.

In the Oracle Database product, this type of table is known as an
*index-organized table*.  cold backup

A *backup* taken while the database is shut down.  For busy applications
and websites, this might not be practical, and you might prefer a *warm
backup* or a *hot backup*.  column

A data item within a *row*, whose storage and semantics are defined by a
data type.  Each *table* and *index* is largely defined by the set of
columns it contains.

Each column has a *cardinality* value.  A column can be the *primary
key* for its table, or part of the primary key.  A column can be subject
to a *unique constraint*, a *NOT NULL constraint*, or both.  Values in
different columns, even across different tables, can be linked by a
*foreign key* relationship.

In discussions of MySQL internal operations, sometimes *field* is used
as a synonym.  column index

An *index* on a single column.  column prefix

When an *index* is created with a length specification, such as 'CREATE
INDEX idx ON t1 (c1(N))', only the first N characters of the column
value are stored in the index.  Keeping the index prefix small makes the
index compact, and the memory and disk I/O savings help performance.
(Although making the index prefix too small can hinder query
optimization by making rows with different values appear to the query
optimizer to be duplicates.)

For columns containing binary values or long text strings, where sorting
is not a major consideration and storing the entire value in the index
would waste space, the index automatically uses the first N (typically
768) characters of the value to do lookups and sorts.  commit

A *SQL* statement that ends a *transaction*, making permanent any
changes made by the transaction.  It is the opposite of *rollback*,
which undoes any changes made in the transaction.

'InnoDB' uses an *optimistic* mechanism for commits, so that changes can
be written to the data files before the commit actually occurs.  This
technique makes the commit itself faster, with the tradeoff that more
work is required in case of a rollback.

By default, MySQL uses the *autocommit* setting, which automatically
issues a commit following each SQL statement.  compact row format

The default 'InnoDB' *row format* for InnoDB tables from MySQL 5.0.3 to
MySQL 5.7.8.  As of MySQL 5.7.9, the default row format is defined by
the 'innodb_default_row_format' configuration option, which has a
default setting of *DYNAMIC*. The *COMPACT* row format provides a more
compact representation for nulls and variable-length columns than the
prior default (*REDUNDANT* row format).

For additional information about 'InnoDB' 'COMPACT' row format, see
innodb-row-format-antelope.  composite index

An *index* that includes multiple columns.  compressed backup

The compression feature of the *MySQL Enterprise Backup* product makes a
compressed copy of each tablespace, changing the extension from '.ibd'
to '.ibz'.  Compressing backup data allows you to keep more backups on
hand, and reduces the time to transfer backups to a different server.
The data is uncompressed during the restore operation.  When a
compressed backup operation processes a table that is already
compressed, it skips the compression step for that table, because
compressing again would result in little or no space savings.

A set of files produced by the *MySQL Enterprise Backup* product, where
each *tablespace* is compressed.  The compressed files are renamed with
a '.ibz' file extension.

Applying *compression* at the start of the backup process helps to avoid
storage overhead during the compression process, and to avoid network
overhead when transferring the backup files to another server.  The
process of *applying* the *binary log* takes longer, and requires
uncompressing the backup files.  compressed row format

A *row format* that enables data and index *compression* for 'InnoDB'
tables.  It was introduced in the 'InnoDB' Plugin, available as part of
the *Barracuda* file format.  Large fields are stored away from the page
that holds the rest of the row data, as in *dynamic row format*.  Both
index pages and large fields are compressed, yielding memory and disk
savings.  Depending on the structure of the data, the decrease in memory
and disk usage might or might not outweigh the performance overhead of
uncompressing the data as it is used.  See innodb-compression
for usage details.

For additional information about 'InnoDB' 'COMPRESSED' row format, see
innodb-row-format-dynamic.  compressed table

A table for which the data is stored in compressed form.  For 'InnoDB',
it is a table created with 'ROW_FORMAT=COMPRESSED'.  See
innodb-compression for more information.  compression

A feature with wide-ranging benefits from using less disk space,
performing less I/O, and using less memory for caching.

'InnoDB' supports both table-level and page-level compression.  'InnoDB'
page compression is also referred to as *transparent page compression*.
For more information about 'InnoDB' compression, see
innodb-compression.

Another type of compression is the *compressed backup* feature of the
*MySQL Enterprise Backup* product.  compression failure

Not actually an error, rather an expensive operation that can occur when
using *compression* in combination with *DML* operations.  It occurs
when: updates to a compressed *page* overflow the area on the page
reserved for recording modifications; the page is compressed again, with
all changes applied to the table data; the re-compressed data does not
fit on the original page, requiring MySQL to split the data into two new
pages and compress each one separately.  To check the frequency of this
condition, query the 'INFORMATION_SCHEMA.INNODB_CMP'
table and check how much the value of the
'COMPRESS_OPS' column exceeds the value of the 'COMPRESS_OPS_OK' column.
Ideally, compression failures do not occur often; when they do, you can
adjust the 'innodb_compression_level',
'innodb_compression_failure_threshold_pct', and
'innodb_compression_pad_pct_max' configuration options.  concatenated
indexconcurrency

The ability of multiple operations (in database terminology,
*transactions*) to run simultaneously, without interfering with each
other.  Concurrency is also involved with performance, because ideally
the protection for multiple simultaneous transactions works with a
minimum of performance overhead, using efficient mechanisms for
*locking*.  configuration file

The file that holds the *option* values used by MySQL at startup.
Traditionally, on Linux and Unix this file is named 'my.cnf', and on
Windows it is named 'my.ini'.  You can set a number of options related
to InnoDB under the '[mysqld]' section of the file.

See option-files for information about where MySQL searches for
configuration files.

When you use the *MySQL Enterprise Backup* product, you typically use
two configuration files: one that specifies where the data comes from
and how it is structured (which could be the original configuration file
for your server), and a stripped-down one containing only a small set of
options that specify where the backup data goes and how it is
structured.  The configuration files used with the *MySQL Enterprise
Backup* product must contain certain options that are typically left out
of regular configuration files, so you might need to add options to your
existing configuration file for use with *MySQL Enterprise Backup*.
consistent read

A read operation that uses *snapshot* information to present query
results based on a point in time, regardless of changes performed by
other transactions running at the same time.  If queried data has been
changed by another transaction, the original data is reconstructed based
on the contents of the *undo log*.  This technique avoids some of the
*locking* issues that can reduce *concurrency* by forcing transactions
to wait for other transactions to finish.

With *REPEATABLE READ* *isolation level*, the snapshot is based on the
time when the first read operation is performed.  With *READ COMMITTED*
isolation level, the snapshot is reset to the time of each consistent
read operation.

Consistent read is the default mode in which 'InnoDB' processes 'SELECT'
statements in *READ COMMITTED* and *REPEATABLE READ* isolation levels.
Because a consistent read does not set any locks on the tables it
accesses, other sessions are free to modify those tables while a
consistent read is being performed on the table.

For technical details about the applicable isolation levels, see
innodb-consistent-read.  constraint

An automatic test that can block database changes to prevent data from
becoming inconsistent.  (In computer science terms, a kind of assertion
related to an invariant condition.)  Constraints are a crucial component
of the *ACID* philosophy, to maintain data consistency.  Constraints
supported by MySQL include *FOREIGN KEY constraints* and *unique
constraints*.  counter

A value that is incremented by a particular kind of 'InnoDB' operation.
Useful for measuring how busy a server is, troubleshooting the sources
of performance issues, and testing whether changes (for example, to
configuration settings or indexes used by queries) have the desired
low-level effects.  Different kinds of counters are available through
*Performance Schema* tables and *INFORMATION_SCHEMA* tables,
particularly 'INFORMATION_SCHEMA.INNODB_METRICS'.  covering index

An *index* that includes all the columns retrieved by a query.  Instead
of using the index values as pointers to find the full table rows, the
query returns values from the index structure, saving disk I/O. 'InnoDB'
can apply this optimization technique to more indexes than MyISAM can,
because 'InnoDB' *secondary indexes* also include the *primary key*
columns.  'InnoDB' cannot apply this technique for queries against
tables modified by a transaction, until that transaction ends.

Any *column index* or *composite index* could act as a covering index,
given the right query.  Design your indexes and queries to take
advantage of this optimization technique wherever possible.  CPU-bound

A type of *workload* where the primary *bottleneck* is CPU operations in
memory.  Typically involves read-intensive operations where the results
can all be cached in the *buffer pool*.  crash

MySQL uses the term 'crash' to refer generally to any unexpected
*shutdown* operation where the server cannot do its normal cleanup.  For
example, a crash could happen due to a hardware fault on the database
server machine or storage device; a power failure; a potential data
mismatch that causes the MySQL server to halt; a *fast shutdown*
initiated by the DBA; or many other reasons.  The robust, automatic
*crash recovery* for *InnoDB* tables ensures that data is made
consistent when the server is restarted, without any extra work for the
DBA. crash recovery

The cleanup activities that occur when MySQL is started again after a
*crash*.  For *InnoDB* tables, changes from incomplete transactions are
replayed using data from the *redo log*.  Changes that were *committed*
before the crash, but not yet written into the *data files*, are
reconstructed from the *doublewrite buffer*.  When the database is shut
down normally, this type of activity is performed during shutdown by the
*purge* operation.

During normal operation, committed data can be stored in the *change
buffer* for a period of time before being written to the data files.
There is always a tradeoff between keeping the data files up-to-date,
which introduces performance overhead during normal operation, and
buffering the data, which can make shutdown and crash recovery take
longer.  CRUD

Acronym for 'create, read, update, delete', a common sequence of
operations in database applications.  Often denotes a class of
applications with relatively simple database usage (basic *DDL*, *DML*
and *query* statements in *SQL*) that can be implemented quickly in any
language.  cursor

An internal data structure that is used to represent the result set of a
*query*, or other operation that performs a search using an SQL 'WHERE'
clause.  It works like an iterator in other high-level languages,
producing each value from the result set as requested.

Although SQL usually handles the processing of cursors for you, you
might delve into the inner workings when dealing with
performance-critical code.

data definition languagedata dictionary

Metadata that keeps track of InnoDB-related objects such as *tables*,
*indexes*, and table *columns*.  This metadata is physically located in
the 'InnoDB' *system tablespace*.  For historical reasons, it overlaps
to some degree with information stored in the *.frm files*.

Because the *MySQL Enterprise Backup* product always backs up the system
tablespace, all backups include the contents of the data dictionary.
data directory

The directory under which each MySQL *instance* keeps the *data files*
for 'InnoDB' and the directories representing individual databases.
Controlled by the 'datadir' configuration option.  data files

The files that physically contain *table* and *index* data.

The 'InnoDB' *system tablespace*, which holds the 'InnoDB' *data
dictionary* and is capable of holding data for multiple 'InnoDB' tables,
is represented by one or more '.ibdata' data files.

File-per-table tablespaces, which hold data for a single 'InnoDB' table,
are represented by a '.ibd' data file.

General tablespaces (introduced in MySQL 5.7.6), which can hold data for
multiple 'InnoDB' tables, are also represented by a '.ibd' data file.
data manipulation languagedata warehouse

A database system or application that primarily runs large *queries*.
The read-only or read-mostly data might be organized in *denormalized*
form for query efficiency.  Can benefit from the optimizations for
*read-only transactions* in MySQL 5.6 and higher.  Contrast with *OLTP*.
database

Within the MySQL *data directory*, each database is represented by a
separate directory.  The InnoDB *system tablespace*, which can hold
table data from multiple databases within a MySQL *instance*, is kept in
*data files* that reside outside of individual database directories.
When *file-per-table* mode is enabled, the *.ibd files* representing
individual InnoDB tables are stored inside the database directories
unless created elsewhere using the 'DATA DIRECTORY' clause.  General
tablespaces, introduced in MySQL 5.7.6, also hold table data in *.ibd
files*.  Unlike file-per-table *.ibd files*, general tablespace *.ibd
files* can hold table data from multiple databases within a MySQL
*instance*, and can be assigned to directories relative to or
independent of the MySQL data directory.

For long-time MySQL users, a database is a familiar notion.  Users
coming from an Oracle Database background will find that the MySQL
meaning of a database is closer to what Oracle Database calls a
*schema*.  DCL

Data control language, a set of *SQL* statements for managing
privileges.  In MySQL, consists of the 'GRANT' and
'REVOKE' statements.  Contrast with *DDL* and *DML*. DDL

Data definition language, a set of *SQL* statements for manipulating the
database itself rather than individual table rows.  Includes all forms
of the 'CREATE', 'ALTER', and 'DROP' statements.  Also includes the
'TRUNCATE' statement, because it works differently than a 'DELETE FROM
TABLE_NAME' statement, even though the ultimate effect is similar.

DDL statements automatically *commit* the current *transaction*; they
cannot be *rolled back*.

The 'InnoDB' online DDL feature enhances performance for 'CREATE INDEX',
see 'DROP INDEX', and many types of
'ALTER TABLE' operations.  See
innodb-online-ddl for more information.  Also, the 'InnoDB'
file-per-table setting can affect the behavior of 'DROP TABLE'
and 'TRUNCATE TABLE' operations.

Contrast with *DML* and *DCL*. deadlock

A situation where different *transactions* are unable to proceed,
because each holds a *lock* that the other needs.  Because both
transactions are waiting for a resource to become available, neither
will ever release the locks it holds.

A deadlock can occur when the transactions lock rows in multiple tables
(through statements such as 'UPDATE' or 'SELECT ... FOR UPDATE'), but in
the opposite order.  A deadlock can also occur when such statements lock
ranges of index records and *gaps*, with each transaction acquiring some
locks but not others due to a timing issue.

For background information on how deadlocks are automatically detected
and handled, see innodb-deadlock-detection.  For tips on
avoiding and recovering from deadlock conditions, see
innodb-deadlocks-handling.  deadlock detection

A mechanism that automatically detects when a *deadlock* occurs, and
automatically *rolls back* one of the *transactions* involved (the
*victim*).  Deadlock detection can be disabled using the
'innodb_deadlock_detect' configuration option.  delete

When 'InnoDB' processes a 'DELETE' statement, the rows are immediately
marked for deletion and no longer are returned by queries.  The storage
is reclaimed sometime later, during the periodic garbage collection
known as the *purge* operation.  For removing large quantities of data,
related operations with their own performance characteristics are
*TRUNCATE* and *DROP*. delete buffering

The technique of storing changes to secondary index pages, resulting
from 'DELETE' operations, in the *change buffer* rather than writing the
changes immediately, so that the physical writes can be performed to
minimize random I/O. (Because delete operations are a two-step process,
this operation buffers the write that normally marks an index record for
deletion.)  It is one of the types of *change buffering*; the others are
*insert buffering* and *purge buffering*.  denormalized

A data storage strategy that duplicates data across different tables,
rather than linking the tables with *foreign keys* and *join* queries.
Typically used in *data warehouse* applications, where the data is not
updated after loading.  In such applications, query performance is more
important than making it simple to maintain consistent data during
updates.  Contrast with *normalized*.  descending index

A type of *index* available with some database systems, where index
storage is optimized to process 'ORDER BY COLUMN DESC' clauses.
Currently, although MySQL allows the 'DESC' keyword in the 'CREATE TABLE'
statement, it does not use any special storage
layout for the resulting index.  dirty page

A *page* in the 'InnoDB' *buffer pool* that has been updated in memory,
where the changes are not yet written (*flushed*) to the *data files*.
The opposite of a *clean page*.  dirty read

An operation that retrieves unreliable data, data that was updated by
another transaction but not yet *committed*.  It is only possible with
the *isolation level* known as *read uncommitted*.

This kind of operation does not adhere to the *ACID* principle of
database design.  It is considered very risky, because the data could be
*rolled back*, or updated further before being committed; then, the
transaction doing the dirty read would be using data that was never
confirmed as accurate.

Its opposite is *consistent read*, where 'InnoDB' ensures that a
transaction does not read information updated by another transaction,
even if the other transaction commits in the meantime.  disk-based

A kind of database that primarily organizes data on disk storage (hard
drives or equivalent).  Data is brought back and forth between disk and
memory to be operated upon.  It is the opposite of an *in-memory
database*.  Although 'InnoDB' is disk-based, it also contains features
such as he *buffer pool*, multiple buffer pool instances, and the
*adaptive hash index* that allow certain kinds of workloads to work
primarily from memory.  disk-bound

A type of *workload* where the primary *bottleneck* is disk I/O. (Also
known as *I/O-bound*.)  Typically involves frequent writes to disk, or
random reads of more data than can fit into the *buffer pool*.  DML

Data manipulation language, a set of *SQL* statements for performing
'INSERT', 'UPDATE', and 'DELETE'
operations.  The 'SELECT' statement is sometimes
considered as a DML statement, because the 'SELECT ... FOR UPDATE' form
is subject to the same considerations for *locking* as 'INSERT',
see 'UPDATE', and 'DELETE'.

DML statements for an 'InnoDB' table operate in the context of a
*transaction*, so their effects can be *committed* or *rolled back* as a
single unit.

Contrast with *DDL* and *DCL*. document id

In the 'InnoDB' *full-text search* feature, a special column in the
table containing the *FULLTEXT index*, to uniquely identify the document
associated with each *ilist* value.  Its name is 'FTS_DOC_ID' (uppercase
required).  The column itself must be of 'BIGINT UNSIGNED NOT NULL'
type, with a unique index named 'FTS_DOC_ID_INDEX'.  Preferably, you
define this column when creating the table.  If 'InnoDB' must add the
column to the table while creating a 'FULLTEXT' index, the indexing
operation is considerably more expensive.  doublewrite buffer

'InnoDB' uses a file flush technique called doublewrite.  Before writing
*pages* to the *data files*, 'InnoDB' first writes them to a contiguous
area called the doublewrite buffer.  Only after the write and the flush
to the doublewrite buffer have completed, does 'InnoDB' write the pages
to their proper positions in the data file.  If there is an operating
system, storage subsystem, or 'mysqld' process crash in
the middle of a page write, 'InnoDB' can later find a good copy of the
page from the doublewrite buffer during *crash recovery*.

Although data is always written twice, the doublewrite buffer does not
require twice as much I/O overhead or twice as many I/O operations.
Data is written to the buffer itself as a large sequential chunk, with a
single 'fsync()' call to the operating system.

To turn off the doublewrite buffer, specify the option
'innodb_doublewrite=0'.  drop

A kind of *DDL* operation that removes a schema object, through a
statement such as 'DROP TABLE' or 'DROP INDEX'.
It maps internally to an 'ALTER TABLE'.
statement.  From an 'InnoDB' perspective, the performance considerations
of such operations involve the time that the *data dictionary* is locked
to ensure that interrelated objects are all updated, and the time to
update memory structures such as the *buffer pool*.  For a *table*, the
drop operation has somewhat different characteristics than a *truncate*
operation (see 'TRUNCATE TABLE' statement).  dynamic
row format

A row format introduced in the 'InnoDB' Plugin, available as part of the
*Barracuda* *file format*.  Because long variable-length column values
are stored outside of the page that holds the row data, it is very
efficient for rows that include large objects.  Since the large fields
are typically not accessed to evaluate query conditions, they are not
brought into the *buffer pool* as often, resulting in fewer I/O
operations and better utilization of cache memory.

As of MySQL 5.7.9, the default row format is defined by
'innodb_default_row_format', which has a default value of 'DYNAMIC'.

For additional information about 'InnoDB' 'DYNAMIC' row format, see
innodb-row-format-dynamic.

early adopter

A stage similar to *beta*, when a software product is typically
evaluated for performance, functionality, and compatibility in a
non-mission-critical setting.  error log

A type of *log* showing information about MySQL startup and critical
runtime errors and *crash* information.  For details, see
error-log.  eviction

The process of removing an item from a cache or other temporary storage
area, such as the 'InnoDB' *buffer pool*.  Often, but not always, uses
the *LRU* algorithm to determine which item to remove.  When a *dirty
page* is evicted, its contents are *flushed* to disk, and any dirty
*neighbor pages* might be flushed also.  exclusive lock

A kind of *lock* that prevents any other *transaction* from locking the
same row.  Depending on the transaction *isolation level*, this kind of
lock might block other transactions from writing to the same row, or
might also block other transactions from reading the same row.  The
default 'InnoDB' isolation level, *REPEATABLE READ*, enables higher
*concurrency* by allowing transactions to read rows that have exclusive
locks, a technique known as *consistent read*.  extent

A group of *pages* within a *tablespace*.  For the default *page size*
of 16KB, an extent contains 64 pages.  In MySQL 5.6, the page size for
an 'InnoDB' instance can be 4KB, 8KB, or 16KB, controlled by the
'innodb_page_size' configuration option.  For 4KB, 8KB, and 16KB pages
sizes, the extent size is always 1MB (or 1048576 bytes).

Support for 32KB and 64KB 'InnoDB' page sizes was added in MySQL 5.7.6.
For a 32KB page size, the extent size is 2MB. For a 64KB page size, the
extent size is 4MB.

'InnoDB' features such as *segments*, *read-ahead* requests and the
*doublewrite buffer* use I/O operations that read, write, allocate, or
free data one extent at a time.

fanout

The increase or decrease in number of rows from adding a table during
join processing.  Suppose that a query of the form 'SELECT ... FROM t1
INNER JOIN t2 ...' selects rows from table 't1', then 't2'.

   * If the join selects one row from 't2' per row in 't1', the fanout
     for 't2' is 1.

   * If the join selects two rows from 't2' per row in 't1', the fanout
     for 't2' is 2.

   * If the join selects one row from 't2' per two rows in 't1', the
     fanout for 't2' is .5.
Fast Index Creation

A capability first introduced in the InnoDB Plugin, now part of MySQL in
5.5 and higher, that speeds up creation of 'InnoDB' *secondary indexes*
by avoiding the need to completely rewrite the associated table.  The
speedup applies to dropping secondary indexes also.

Because index maintenance can add performance overhead to many data
transfer operations, consider doing operations such as 'ALTER TABLE ...
ENGINE=INNODB' or 'INSERT INTO ... SELECT * FROM ...' without any
secondary indexes in place, and creating the indexes afterward.

In MySQL 5.6, this feature becomes more general.  You can read and write
to tables while an index is being created, and many more kinds of
'ALTER TABLE' operations can be performed without copying
the table, without blocking *DML* operations, or both.  Thus in MySQL
5.6 and higher, this set of features is referred to as *online DDL*
rather than Fast Index Creation.

For related information, see InnoDB Fast Index Creation
(http://dev.mysql.com/doc/refman/5.5/en/innodb-create-index.html), and
innodb-online-ddl.  fast shutdown

The default *shutdown* procedure for 'InnoDB', based on the
configuration setting 'innodb_fast_shutdown=1'.  To save time, certain
*flush* operations are skipped.  This type of shutdown is safe during
normal usage, because the flush operations are performed during the next
startup, using the same mechanism as in *crash recovery*.  In cases
where the database is being shut down for an upgrade or downgrade, do a
*slow shutdown* instead to ensure that all relevant changes are applied
to the *data files* during the shutdown.  file format

The file format for 'InnoDB' tables, enabled using the
'innodb_file_format' configuration option.  Supported file formats are
*Antelope* and *Barracuda*.  Antelope is the original 'InnoDB' file
format and supports the *REDUNDANT* and *COMPACT* row formats.
Barracuda is the newer 'InnoDB' file format and supports the
*COMPRESSED* and *DYNAMIC* row formats.  file-per-table

A general name for the setting controlled by the 'innodb_file_per_table'
option, which is an important configuration option that affects aspects
of 'InnoDB' file storage, availability of features, and I/O
characteristics.  As of MySQL 5.6.7, 'innodb_file_per_table' is enabled
by default.

With the 'innodb_file_per_table' option enabled, you can create a table
in its own *.ibd file* rather than in the shared *ibdata files* of the
*system tablespace*.  When table data is stored in an individual *.ibd
file*, you have more flexibility to choose *row formats* required for
features such as data *compression*.  The 'TRUNCATE TABLE' operation is
also faster, and reclaimed space can be used by the operating system
rather than remaining reserved for 'InnoDB'.

The *MySQL Enterprise Backup* product is more flexible for tables that
are in their own files.  For example, tables can be excluded from a
backup, but only if they are in separate files.  Thus, this setting is
suitable for tables that are backed up less frequently or on a different
schedule.  fill factor

In an 'InnoDB' *index*, the proportion of a *page* that is taken up by
index data before the page is split.  The unused space when index data
is first divided between pages allows for rows to be updated with longer
string values without requiring expensive index maintenance operations.
If the fill factor is too low, the index consumes more space than
needed, causing extra I/O overhead when reading the index.  If the fill
factor is too high, any update that increases the length of column
values can cause extra I/O overhead for index maintenance.  See
innodb-physical-structure for more information.  fixed row format

This row format is used by the 'MyISAM' storage engine, not by 'InnoDB'.
If you create an 'InnoDB' table with the option 'ROW_FORMAT=FIXED' in
MySQL 5.7.6 or earlier, 'InnoDB' uses the *compact row format* instead,
although the 'FIXED' value might still show up in output such as 'SHOW
TABLE STATUS' reports.  As of MySQL 5.7.7, 'InnoDB' returns an error if
'ROW_FORMAT=FIXED' is specified.  flush

To write changes to the database files, that had been buffered in a
memory area or a temporary disk storage area.  The 'InnoDB' storage
structures that are periodically flushed include the *redo log*, the
*undo log*, and the *buffer pool*.

Flushing can happen because a memory area becomes full and the system
needs to free some space, because a *commit* operation means the changes
from a transaction can be finalized, or because a *slow shutdown*
operation means that all outstanding work should be finalized.  When it
is not critical to flush all the buffered data at once, 'InnoDB' can use
a technique called *fuzzy checkpointing* to flush small batches of pages
to spread out the I/O overhead.  flush list

An internal 'InnoDB' data structure that tracks *dirty pages* in the
*buffer pool*: that is, *pages* that have been changed and need to be
written back out to disk.  This data structure is updated frequently by
'InnoDB' internal *mini-transactions*, and so is protected by its own
*mutex* to allow concurrent access to the buffer pool.  foreign key

A type of pointer relationship, between rows in separate 'InnoDB'
tables.  The foreign key relationship is defined on one column in both
the *parent table* and the *child table*.

In addition to enabling fast lookup of related information, foreign keys
help to enforce *referential integrity*, by preventing any of these
pointers from becoming invalid as data is inserted, updated, and
deleted.  This enforcement mechanism is a type of *constraint*.  A row
that points to another table cannot be inserted if the associated
foreign key value does not exist in the other table.  If a row is
deleted or its foreign key value changed, and rows in another table
point to that foreign key value, the foreign key can be set up to
prevent the deletion, cause the corresponding column values in the other
table to become *null*, or automatically delete the corresponding rows
in the other table.

One of the stages in designing a *normalized* database is to identify
data that is duplicated, separate that data into a new table, and set up
a foreign key relationship so that the multiple tables can be queried
like a single table, using a *join* operation.  FOREIGN KEY constraint

The type of *constraint* that maintains database consistency through a
*foreign key* relationship.  Like other kinds of constraints, it can
prevent data from being inserted or updated if data would become
inconsistent; in this case, the inconsistency being prevented is between
data in multiple tables.  Alternatively, when a *DML* operation is
performed, 'FOREIGN KEY' constraints can cause data in *child rows* to
be deleted, changed to different values, or set to *null*, based on the
'ON CASCADE' option specified when creating the foreign key.  .frm file

A file containing the metadata, such as the table definition, of a MySQL
table.

For backups, you must always keep the full set of '.frm' files along
with the backup data to be able to restore tables that are altered or
dropped after the backup.

Although each 'InnoDB' table has a '.frm' file, 'InnoDB' maintains its
own table metadata in the *system tablespace*; the '.frm' files are not
needed for 'InnoDB' to operate on 'InnoDB' tables.

'.frm' files are backed up by the *MySQL Enterprise Backup* product.
These files must not be modified by an 'ALTER TABLE'.
operation while the backup is taking place, which is why backups that
include non-'InnoDB' tables perform a 'FLUSH TABLES WITH READ LOCK'
operation to freeze such activity while backing up '.frm' files.
Restoring a backup can result in '.frm' files being created, changed, or
removed to match the state of the database at the time of the backup.
FTS

In most contexts, an acronym for *full-text search*.  Sometimes in
performance discussions, an acronym for *full table scan*.  full backup

A *backup* that includes all the *tables* in each MySQL *database*, and
all the databases in a MySQL *instance*.  Contrast with *partial
backup*.  full table scan

An operation that requires reading the entire contents of a table,
rather than just selected portions using an *index*.  Typically
performed either with small lookup tables, or in data warehousing
situations with large tables where all available data is aggregated and
analyzed.  How frequently these operations occur, and the sizes of the
tables relative to available memory, have implications for the
algorithms used in query optimization and managing the *buffer pool*.

The purpose of indexes is to allow lookups for specific values or ranges
of values within a large table, thus avoiding full table scans when
practical.  full-text search

The MySQL feature for finding words, phrases, Boolean combinations of
words, and so on within table data, in a faster, more convenient, and
more flexible way than using the SQL 'LIKE' operator or writing your own
application-level search algorithm.  It uses the SQL function 'MATCH()'
and *FULLTEXT indexes*.  FULLTEXT index

The special kind of *index* that holds the *search index* in the MySQL
*full-text search* mechanism.  Represents the words from values of a
column, omitting any that are specified as *stopwords*.  Originally,
only available for 'MyISAM' tables.  Starting in MySQL 5.6.4, it is also
available for *InnoDB* tables.  fuzzy checkpointing

A technique that *flushes* small batches of *dirty pages* from the
*buffer pool*, rather than flushing all dirty pages at once which would
disrupt database processing.

GA

'Generally available', the stage when a software product leaves *beta*
and is available for sale, official support, and production use.  gap

A place in an 'InnoDB' *index* data structure where new values could be
inserted.  When you lock a set of rows with a statement such as 'SELECT
... FOR UPDATE', 'InnoDB' can create locks that apply to the gaps as
well as the actual values in the index.  For example, if you select all
values greater than 10 for update, a gap lock prevents another
transaction from inserting a new value that is greater than 10.  The
*supremum record* and *infimum record* represent the gaps containing all
values greater than or less than all the current index values.  gap lock

A *lock* on a *gap* between index records, or a lock on the gap before
the first or after the last index record.  For example, 'SELECT c1 FROM
t WHERE c1 BETWEEN 10 and 20 FOR UPDATE;' prevents other transactions
from inserting a value of 15 into the column 't.c1', whether or not
there was already any such value in the column, because the gaps between
all existing values in the range are locked.  Contrast with *record
lock* and *next-key lock*.

Gap locks are part of the tradeoff between performance and
*concurrency*, and are used in some transaction *isolation levels* and
not others.  general loggeneral query log

A type of *log* used for diagnosis and troubleshooting of SQL statements
processed by the MySQL server.  Can be stored in a file or in a database
table.  You must enable this feature through the 'general_log'
configuration option to use it.  You can disable it for a specific
connection through the 'sql_log_off' configuration option.

Records a broader range of queries than the *slow query log*.  Unlike
the *binary log*, which is used for replication, the general query log
contains 'SELECT' statements and does not maintain strict
ordering.  For more information, see query-log.  general
tablespace

A shared 'InnoDB' *tablespace* created using 'CREATE TABLESPACE'
syntax.  General tablespaces can be created outside
of the MySQL data directory, are capable of holding multiple *tables*,
and support tables of all row formats.  General tablespaces were
introduced in MySQL 5.7.6.

Tables are added to a general tablespace using 'CREATE TABLE TBL_NAME ... TABLESPACE [=] TABLESPACE_NAME'
or
'ALTER TABLE TBL_NAME TABLESPACE [=] TABLESPACE_NAME'.
syntax.

Contrast with *system tablespace* and *file-per-table* tablespace.

For more information, see general-tablespaces.  generated column

A column whose values are computed from an expression included in the
column definition.  A generated column can be *virtual* or *stored*.
generated stored columngenerated virtual columnglobal transaction

A type of *transaction* involved in *XA* operations.  It consists of
several actions that are transactional in themselves, but that all must
either complete successfully as a group, or all be rolled back as a
group.  In essence, this extends *ACID* properties 'up a level' so that
multiple ACID transactions can be executed in concert as components of a
global operation that also has ACID properties.  group commit

An 'InnoDB' optimization that performs some low-level I/O operations
(log write) once for a set of *commit* operations, rather than flushing
and syncing separately for each commit.

hash index

A type of *index* intended for queries that use equality operators,
rather than range operators such as greater-than or 'BETWEEN'.  It is
available for 'MEMORY' tables.  Although
hash indexes are the default for 'MEMORY'.
tables for historic reasons, that storage engine also supports *B-tree*
indexes, which are often a better choice for general-purpose queries.

MySQL includes a variant of this index type, the *adaptive hash index*,
that is constructed automatically for 'InnoDB'
tables if needed based on runtime conditions.
HDD

Acronym for 'hard disk drive'.  Refers to storage media using spinning
platters, usually when comparing and contrasting with *SSD*. Its
performance characteristics can influence the throughput of a
*disk-based* workload.  heartbeat

A periodic message that is sent to indicate that a system is functioning
properly.  In a *replication* context, if the *master* stops sending
such messages, one of the *slaves* can take its place.  Similar
techniques can be used between the servers in a cluster environment, to
confirm that all of them are operating properly.  high-water mark

A value representing an upper limit, either a hard limit that should not
be exceeded at runtime, or a record of the maximum value that was
actually reached.  Contrast with *low-water mark*.  history list

A list of *transactions* with delete-marked records scheduled to be
processed by the 'InnoDB' *purge* operation.  Recorded in the *undo
log*.  The length of the history list is reported by the command 'SHOW
ENGINE INNODB STATUS'.  If the history list grows longer than the value
of the 'innodb_max_purge_lag' configuration option, each *DML* operation
is delayed slightly to allow the purge operation to finish *flushing*
the deleted records.

Also known as *purge lag*.  hole punching

Releasing empty blocks from a page.  The 'InnoDB' *transparent page
compression* feature relies on hole punching support.  For more
information, see innodb-page-compression.  hot

A condition where a row, table, or internal data structure is accessed
so frequently, requiring some form of locking or mutual exclusion, that
it results in a performance or scalability issue.

Although 'hot' typically indicates an undesirable condition, a *hot
backup* is the preferred type of backup.  hot backup

A backup taken while the database is running and applications are
reading and writing to it.  The backup involves more than simply copying
data files: it must include any data that was inserted or updated while
the backup was in process; it must exclude any data that was deleted
while the backup was in process; and it must ignore any changes that
were not committed.

The Oracle product that performs hot backups, of 'InnoDB' tables
especially but also tables from 'MyISAM' and other storage engines, is
known as *MySQL Enterprise Backup*.

The hot backup process consists of two stages.  The initial copying of
the data files produces a *raw backup*.  The *apply* step incorporates
any changes to the database that happened while the backup was running.
Applying the changes produces a *prepared* backup; these files are ready
to be restored whenever necessary.

I/O-boundib-file set

The set of files managed by 'InnoDB' within a MySQL database: the
*system tablespace*, *file-per-table* tablespace files, and *redo log*
files.  Depending on MySQL version and 'InnoDB' configuration, may also
include *general tablespace*, *temporary tablespace*, and *undo
tablespace* files.  This term is sometimes used in detailed discussions
of 'InnoDB' file structures and formats to refer to the set of files
managed by 'InnoDB' within a MySQL database.  ib_logfile

A set of files, typically named 'ib_logfile0' and 'ib_logfile1', that
form the *redo log*.  Also sometimes referred to as the *log group*.
These files record statements that attempt to change data in 'InnoDB'
tables.  These statements are replayed automatically to correct data
written by incomplete transactions, on startup following a crash.

This data cannot be used for manual recovery; for that type of
operation, use the *binary log*.  ibbackup_logfile

A supplemental backup file created by the *MySQL Enterprise Backup*
product during a *hot backup* operation.  It contains information about
any data changes that occurred while the backup was running.  The
initial backup files, including 'ibbackup_logfile', are known as a *raw
backup*, because the changes that occurred during the backup operation
are not yet incorporated.  After you perform the *apply* step to the raw
backup files, the resulting files do include those final data changes,
and are known as a *prepared backup*.  At this stage, the
'ibbackup_logfile' file is no longer necessary.  .ibd file

The data file for *file-per-table* tablespaces and general tablespaces.
File-per-table tablespace '.idb' files contain a single table and
associated index data.  *General tablespace* '.idb' files may contain
table and index data for multiple tables.  General tablespaces were
introduced in MySQL 5.7.6.

The '.ibd' file extension does not apply to the *system tablespace*,
which consists of one or more *ibdata files*.

If a file-per-table tablespace or general tablespace is created with the
'DATA DIRECTORY =' clause, the '.ibd' file is located at the specified
path, outside the normal data directory, and is pointed to by a *.isl
file*.

When a '.ibd' file is included in a compressed backup by the *MySQL
Enterprise Backup* product, the compressed equivalent is a '.ibz' file.
ibdata file

A set of files with names such as 'ibdata1', 'ibdata2', and so on, that
make up the InnoDB *system tablespace*.  These files contain metadata
about 'InnoDB' tables, (the 'InnoDB' *data dictionary*), and the storage
areas for one or more *undo logs*, the *change buffer*, and the
*doublewrite buffer*.  They also can contain some or all of the table
data also (depending on whether the *file-per-table* mode is in effect
when each table is created).  When the *innodb_file_per_table* option is
enabled, data and indexes for newly created tables are stored in
separate *.ibd files* rather than in the system tablespace.

The growth of the 'ibdata' files is influenced by the
'innodb_autoextend_increment' configuration option.  ibtmp file

The 'InnoDB' *temporary tablespace* *data file* for non-compressed
'InnoDB' *temporary tables* and related objects.  The configuration file
option, 'innodb_temp_data_file_path', allows users to define a relative
path for the temporary tablespace data file.  If
'innodb_temp_data_file_path' is not specified, the default behavior is
to create a single auto-extending 12MB data file named 'ibtmp1' in the
data directory, alongside 'ibdata1'.  .ibz file

When the *MySQL Enterprise Backup* product performs a *compressed
backup*, it transforms each *tablespace* file that is created using the
*file-per-table* setting from a '.ibd' extension to a '.ibz' extension.

The compression applied during backup is distinct from the *compressed
row format* that keeps table data compressed during normal operation.  A
compressed backup operation skips the compression step for a tablespace
that is already in compressed row format, as compressing a second time
would slow down the backup but produce little or no space savings.
ilist

Within an 'InnoDB' *FULLTEXT index*, the data structure consisting of a
document ID and positional information for a token (that is, a
particular word).  implicit row lock

A row lock that 'InnoDB' acquires to ensure consistency, without you
specifically requesting it.  in-memory database

A type of database system that maintains data in memory, to avoid
overhead due to disk I/O and translation between disk blocks and memory
areas.  Some in-memory databases sacrifice durability (the 'D' in the
*ACID* design philosophy) and are vulnerable to hardware, power, and
other types of failures, making them more suitable for read-only
operations.  Other in-memory databases do use durability mechanisms such
as logging changes to disk or using non-volatile memory.

MySQL features that address the same kinds of memory-intensive
processing include the 'InnoDB' *buffer pool*, *adaptive hash index*,
and *read-only transaction* optimization, the 'MEMORY'
storage engine, the 'MyISAM' key cache, and the
MySQL query cache.  incremental backup

A type of *hot backup*, performed by the *MySQL Enterprise Backup*
product, that only saves data changed since some point in time.  Having
a full backup and a succession of incremental backups lets you
reconstruct backup data over a long period, without the storage overhead
of keeping several full backups on hand.  You can restore the full
backup and then apply each of the incremental backups in succession, or
you can keep the full backup up-to-date by applying each incremental
backup to it, then perform a single restore operation.

The granularity of changed data is at the *page* level.  A page might
actually cover more than one row.  Each changed page is included in the
backup.  index

A data structure that provides a fast lookup capability for *rows* of a
*table*, typically by forming a tree structure (*B-tree)* representing
all the values of a particular *column* or set of columns.

'InnoDB' tables always have a *clustered index* representing the
*primary key*.  They can also have one or more *secondary indexes*
defined on one or more columns.  Depending on their structure, secondary
indexes can be classified as *partial*, *column*, or *composite*
indexes.

Indexes are a crucial aspect of *query* performance.  Database
architects design tables, queries, and indexes to allow fast lookups for
data needed by applications.  The ideal database design uses a *covering
index* where practical; the query results are computed entirely from the
index, without reading the actual table data.  Each *foreign key*
constraint also requires an index, to efficiently check whether values
exist in both the *parent* and *child* tables.

Although a B-tree index is the most common, a different kind of data
structure is used for *hash indexes*, as in the 'MEMORY' storage engine
and the 'InnoDB' *adaptive hash index*.  *R-tree* indexes are used for
spatial indexing of multi-dimensional information.  index cache

A memory area that holds the token data for 'InnoDB' *full-text search*.
It buffers the data to minimize disk I/O when data is inserted or
updated in columns that are part of a *FULLTEXT index*.  The token data
is written to disk when the index cache becomes full.  Each 'InnoDB'
'FULLTEXT' index has its own separate index cache, whose size is
controlled by the configuration option 'innodb_ft_cache_size'.  index
condition pushdown

Index condition pushdown (ICP) is an optimization that pushes part of a
'WHERE' condition down to the storage engine if parts of the condition
can be evaluated using fields from the *index*.  ICP can reduce the
number of times the *storage engine* must access the base table and the
number of times the MySQL server must access the storage engine.  For
more information, see index-condition-pushdown-optimization.
index hint

Extended SQL syntax for overriding the *indexes* recommended by the
optimizer.  For example, the 'FORCE INDEX', 'USE INDEX', and 'IGNORE
INDEX' clauses.  Typically used when indexed columns have unevenly
distributed values, resulting in inaccurate *cardinality* estimates.
index prefix

In an *index* that applies to multiple columns (known as a *composite
index*), the initial or leading columns of the index.  A query that
references the first 1, 2, 3, and so on columns of a composite index can
use the index, even if the query does not reference all the columns in
the index.  index statisticsinfimum record

A *pseudo-record* in an *index*, representing the *gap* below the
smallest value in that index.  If a transaction has a statement such as
'SELECT ... FROM ... WHERE col < 10 FOR UPDATE;', and the smallest value
in the column is 5, it is a lock on the infimum record that prevents
other transactions from inserting even smaller values such as 0, -10,
and so on.  INFORMATION_SCHEMA

The name of the *database* that provides a query interface to the MySQL
*data dictionary*.  (This name is defined by the ANSI SQL standard.)  To
examine information (metadata) about the database, you can query tables
such as 'INFORMATION_SCHEMA.TABLES' and 'INFORMATION_SCHEMA.COLUMNS',
rather than using 'SHOW' commands that produce unstructured output.

The 'INFORMATION_SCHEMA' database also contains tables specific to
*InnoDB* that provide a query interface to the 'InnoDB' data dictionary.
You use these tables not to see how the database is structured, but to
get real-time information about the workings of 'InnoDB' tables to help
with performance monitoring, tuning, and troubleshooting.  InnoDB

A MySQL component that combines high performance with *transactional*
capability for reliability, robustness, and concurrent access.  It
embodies the *ACID* design philosophy.  Represented as a *storage
engine*; it handles tables created or altered with the 'ENGINE=INNODB'
clause.  See innodb-storage-engine for architectural details and
administration procedures, and optimizing-innodb for performance
advice.

In MySQL 5.5 and higher, 'InnoDB' is the default storage engine for new
tables and the 'ENGINE=INNODB' clause is not required.

'InnoDB' tables are ideally suited for *hot backups*.  See
mysql-enterprise-backup for information about the *MySQL Enterprise
Backup* product for backing up MySQL servers without interrupting normal
processing.  innodb_autoinc_lock_mode

The 'innodb_autoinc_lock_mode' option controls the algorithm used for
*auto-increment locking*.  When you have an auto-incrementing *primary
key*, you can use statement-based replication only with the setting
'innodb_autoinc_lock_mode=1'.  This setting is known as _consecutive_
lock mode, because multi-row inserts within a transaction receive
consecutive auto-increment values.  If you have
'innodb_autoinc_lock_mode=2', which allows higher concurrency for insert
operations, use row-based replication rather than statement-based
replication.  This setting is known as _interleaved_ lock mode, because
multiple multi-row insert statements running at the same time can
receive *auto-increment* values that are interleaved.  The setting
'innodb_autoinc_lock_mode=0' should not be used except for compatibility
purposes.

Consecutive lock mode ('innodb_autoinc_lock_mode=1') is the default
setting prior to MySQL 8.0.3.  As of MySQL 8.0.3, interleaved lock mode
('innodb_autoinc_lock_mode=2') is the default, which reflects the change
from statement-based to row-based replication as the default replication
type.  innodb_file_format

The 'innodb_file_format' option defines the *file format* to use for new
'InnoDB' file-per-table *tablespaces*.  Currently, you can specify the
*Antelope* and *Barracuda* file formats.  innodb_file_per_table

An important configuration option that affects many aspects of 'InnoDB'
file storage, availability of features, and I/O characteristics.  In
MySQL 5.6.7 and higher, it is enabled by default.  The
'innodb_file_per_table' option turns on *file-per-table* mode.  With
this mode enabled, a newly created 'InnoDB' table and associated indexes
can be stored in a file-per-table *.ibd file*, outside the *system
tablespace*.

This option affects the performance and storage considerations for a
number of SQL statements, such as 'DROP TABLE' and
'TRUNCATE TABLE'.

Enabling the 'innodb_file_per_table' option allows you to take advantage
of features such as table *compression* and named-table backups in
*MySQL Enterprise Backup*.

For more information, see 'innodb_file_per_table', and
innodb-multiple-tablespaces.  innodb_lock_wait_timeout

The 'innodb_lock_wait_timeout' option sets the balance between *waiting*
for shared resources to become available, or giving up and handling the
error, retrying, or doing alternative processing in your application.
Rolls back any 'InnoDB' transaction that waits more than a specified
time to acquire a *lock*.  Especially useful if *deadlocks* are caused
by updates to multiple tables controlled by different storage engines;
such deadlocks are not *detected* automatically.  innodb_strict_mode

The 'innodb_strict_mode' option controls whether 'InnoDB' operates in
*strict mode*, where conditions that are normally treated as warnings,
cause errors instead (and the underlying statements fail).  insert

One of the primary *DML* operations in *SQL*. The performance of inserts
is a key factor in *data warehouse* systems that load millions of rows
into tables, and *OLTP* systems where many concurrent connections might
insert rows into the same table, in arbitrary order.  If insert
performance is important to you, you should learn about *InnoDB*
features such as the *insert buffer* used in *change buffering*, and
*auto-increment* columns.  insert buffer

The former name of the *change buffer*.  In MySQL 5.5, support was added
for buffering changes to secondary index pages for 'DELETE'
and 'UPDATE' operations.  Previously, only
changes resulting from 'INSERT' operations were buffered.
The preferred term is now _change buffer_.  insert buffering

The technique of storing changes to secondary index pages, resulting
from 'INSERT' operations, in the *change buffer* rather
than writing the changes immediately, so that the physical writes can be
performed to minimize random I/O. It is one of the types of *change
buffering*; the others are *delete buffering* and *purge buffering*.

Insert buffering is not used if the secondary index is *unique*, because
the uniqueness of new values cannot be verified before the new entries
are written out.  Other kinds of change buffering do work for unique
indexes.  insert intention lock

A type of *gap lock* that is set by 'INSERT' operations
prior to row insertion.  This type of *lock* signals the intent to
insert in such a way that multiple transactions inserting into the same
index gap need not wait for each other if they are not inserting at the
same position within the gap.  For more information, see
innodb-locking.  instance

A single *mysqld* daemon managing a *data directory* representing one or
more *databases* with a set of *tables*.  It is common in development,
testing, and some *replication* scenarios to have multiple instances on
the same *server* machine, each managing its own data directory and
listening on its own port or socket.  With one instance running a
*disk-bound* workload, the server might still have extra CPU and memory
capacity to run additional instances.  instrumentation

Modifications at the source code level to collect performance data for
tuning and debugging.  In MySQL, data collected by instrumentation is
exposed through an SQL interface using the 'INFORMATION_SCHEMA' and
'PERFORMANCE_SCHEMA' databases.  intention exclusive lockintention lock

A kind of *lock* that applies to the table, used to indicate the kind of
lock the *transaction* intends to acquire on rows in the table.
Different transactions can acquire different kinds of intention locks on
the same table, but the first transaction to acquire an _intention
exclusive_ (IX) lock on a table prevents other transactions from
acquiring any S or X locks on the table.  Conversely, the first
transaction to acquire an _intention shared_ (IS) lock on a table
prevents other transactions from acquiring any X locks on the table.
The two-phase process allows the lock requests to be resolved in order,
without blocking locks and corresponding operations that are compatible.
For more information about this locking mechanism, see
innodb-locking.  intention shared lockinverted index

A data structure optimized for document retrieval systems, used in the
implementation of 'InnoDB' *full-text search*.  The 'InnoDB' *FULLTEXT
index*, implemented as an inverted index, records the position of each
word within a document, rather than the location of a table row.  A
single column value (a document stored as a text string) is represented
by many entries in the inverted index.  IOPS

Acronym for *I/O operations per second*.  A common measurement for busy
systems, particularly *OLTP* applications.  If this value is near the
maximum that the storage devices can handle, the application can become
*disk-bound*, limiting *scalability*.  .isl file

A file that specifies the location of an *.ibd file* for an 'InnoDB'
table created with the 'DATA DIRECTORY =' clause in MySQL 5.6 and
higher, or with the 'CREATE TABLESPACE ... ADD DATAFILE' clause in MySQL
5.7.8 and higher.  It functions like a symbolic link, without the
platform restrictions of the actual symbolic link mechanism.  You can
store 'InnoDB' *tablespaces* outside the *database* directory, for
example, on an especially large or fast storage device depending on the
usage of the table.  For details, see tablespace-placing, and
general-tablespaces.  isolation level

One of the foundations of database processing.  Isolation is the *I* in
the acronym *ACID*; the isolation level is the setting that fine-tunes
the balance between performance and reliability, consistency, and
reproducibility of results when multiple *transactions* are making
changes and performing queries at the same time.

From highest amount of consistency and protection to the least, the
isolation levels supported by InnoDB are: *SERIALIZABLE*, *REPEATABLE
READ*, *READ COMMITTED*, and *READ UNCOMMITTED*.

With 'InnoDB' tables, many users can keep the default isolation level
(_REPEATABLE READ_) for all operations.  Expert users might choose the
*READ COMMITTED* level as they push the boundaries of scalability with
*OLTP* processing, or during data warehousing operations where minor
inconsistencies do not affect the aggregate results of large amounts of
data.  The levels on the edges (*SERIALIZABLE* and *READ UNCOMMITTED*)
change the processing behavior to such an extent that they are rarely
used.

join

A *query* that retrieves data from more than one table, by referencing
columns in the tables that hold identical values.  Ideally, these
columns are part of an 'InnoDB' *foreign key* relationship, which
ensures *referential integrity* and that the join columns are *indexed*.
Often used to save space and improve query performance by replacing
repeated strings with numeric IDs, in a *normalized* data design.

KEY_BLOCK_SIZE

An option to specify the size of data pages within an 'InnoDB' table
that uses *compressed row format*.  The default is 8 kilobytes.  Lower
values risk hitting internal limits that depend on the combination of
row size and compression percentage.

For 'MyISAM' tables, 'KEY_BLOCK_SIZE'
optionally specifies the size in bytes to use for index key blocks.  The
value is treated as a hint; a different size could be used if necessary.
A 'KEY_BLOCK_SIZE' value specified for an individual index definition
overrides a table-level 'KEY_BLOCK_SIZE' value.

latch

A lightweight structure used by 'InnoDB' to implement a *lock* for its
own internal memory structures, typically held for a brief time measured
in milliseconds or microseconds.  A general term that includes both
*mutexes* (for exclusive access) and *rw-locks* (for shared access).
Certain latches are the focus of 'InnoDB' performance tuning.
Statistics about latch use and contention are available through the
*Performance Schema* interface.  list

The 'InnoDB' *buffer pool* is represented as a list of memory *pages*.
The list is reordered as new pages are accessed and enter the buffer
pool, as pages within the buffer pool are accessed again and are
considered newer, and as pages that are not accessed for a long time are
*evicted* from the buffer pool.  The buffer pool is divided into
*sublists*, and the replacement policy is a variation of the familiar
*LRU* technique.  lock

The high-level notion of an object that controls access to a resource,
such as a table, row, or internal data structure, as part of a *locking*
strategy.  For intensive performance tuning, you might delve into the
actual structures that implement locks, such as *mutexes* and *latches*.
lock escalation

An operation used in some database systems that converts many *row
locks* into a single *table lock*, saving memory space but reducing
concurrent access to the table.  'InnoDB' uses a space-efficient
representation for row locks, so that *lock* escalation is not needed.
lock mode

A shared (S) *lock* allows a *transaction* to read a row.  Multiple
transactions can acquire an S lock on that same row at the same time.

An exclusive (X) lock allows a transaction to update or delete a row.
No other transaction can acquire any kind of lock on that same row at
the same time.

*Intention locks* apply to the table, and are used to indicate what kind
of lock the transaction intends to acquire on rows in the table.
Different transactions can acquire different kinds of intention locks on
the same table, but the first transaction to acquire an intention
exclusive (IX) lock on a table prevents other transactions from
acquiring any S or X locks on the table.  Conversely, the first
transaction to acquire an intention shared (IS) lock on a table prevents
other transactions from acquiring any X locks on the table.  The
two-phase process allows the lock requests to be resolved in order,
without blocking locks and corresponding operations that are compatible.
locking

The system of protecting a *transaction* from seeing or changing data
that is being queried or changed by other transactions.  The *locking*
strategy must balance reliability and consistency of database operations
(the principles of the *ACID* philosophy) against the performance needed
for good *concurrency*.  Fine-tuning the locking strategy often involves
choosing an *isolation level* and ensuring all your database operations
are safe and reliable for that isolation level.  locking read

A 'SELECT' statement that also performs a *locking*
operation on an 'InnoDB' table.  Either 'SELECT ... FOR UPDATE' or
'SELECT ... LOCK IN SHARE MODE'.  It has the potential to produce a
*deadlock*, depending on the *isolation level* of the transaction.  The
opposite of a *non-locking read*.  Not allowed for global tables in a
*read-only transaction*.

'SELECT ... FOR SHARE' replaces 'SELECT ... LOCK IN SHARE MODE' in MySQL
8.0.1, but 'LOCK IN SHARE MODE' remains available for backward
compatibility.

See innodb-locking-reads.  log

In the 'InnoDB' context, 'log' or 'log files' typically refers to the
*redo log* represented by the *ib_logfileN* files.  Another type of
'InnoDB' log is the *undo log*, which is a storage area that holds
copies of data modified by active transactions.

Other kinds of logs that are important in MySQL are the *error log* (for
diagnosing startup and runtime problems), *binary log* (for working with
replication and performing point-in-time restores), the *general query
log* (for diagnosing application problems), and the *slow query log*
(for diagnosing performance problems).  log buffer

The memory area that holds data to be written to the *log files* that
make up the *redo log*.  It is controlled by the
'innodb_log_buffer_size' configuration option.  log file

One of the *ib_logfileN* files that make up the *redo log*.  Data is
written to these files from the *log buffer* memory area.  log group

The set of files that make up the *redo log*, typically named
'ib_logfile0' and 'ib_logfile1'.  (For that reason, sometimes referred
to collectively as *ib_logfile*.)  logical

A type of operation that involves high-level, abstract aspects such as
tables, queries, indexes, and other SQL concepts.  Typically, logical
aspects are important to make database administration and application
development convenient and usable.  Contrast with *physical*.  logical
backup

A *backup* that reproduces table structure and data, without copying the
actual data files.  For example, the *'mysqldump'* command produces a
logical backup, because its output contains statements such as
'CREATE TABLE' and 'INSERT' that can
re-create the data.  Contrast with *physical backup*.  A logical backup
offers flexibility (for example, you could edit table definitions or
insert statements before restoring), but can take substantially longer
to *restore* than a physical backup.  loose_

A prefix added to 'InnoDB' configuration options after server *startup*,
so any new configuration options not recognized by the current level of
MySQL do not cause a startup failure.  MySQL processes configuration
options that start with this prefix, but gives a warning rather than a
failure if the part after the prefix is not a recognized option.
low-water mark

A value representing a lower limit, typically a threshold value at which
some corrective action begins or becomes more aggressive.  Contrast with
*high-water mark*.  LRU

An acronym for 'least recently used', a common method for managing
storage areas.  The items that have not been used recently are *evicted*
when space is needed to cache newer items.  'InnoDB' uses the LRU
mechanism by default to manage the *pages* within the *buffer pool*, but
makes exceptions in cases where a page might be read only a single time,
such as during a *full table scan*.  This variation of the LRU algorithm
is called the *midpoint insertion strategy*.  For more information, see
innodb-buffer-pool.  LSN

Acronym for 'log sequence number'.  This arbitrary, ever-increasing
value represents a point in time corresponding to operations recorded in
the *redo log*.  (This point in time is regardless of *transaction*
boundaries; it can fall in the middle of one or more transactions.)  It
is used internally by 'InnoDB' during *crash recovery* and for managing
the *buffer pool*.

Prior to MySQL 5.6.3, the LSN was a 4-byte unsigned integer.  The LSN
became an 8-byte unsigned integer in MySQL 5.6.3 when the redo log file
size limit increased from 4GB to 512GB, as additional bytes were
required to store extra size information.  Applications built on MySQL
5.6.3 or later that use LSN values should use 64-bit rather than 32-bit
variables to store and compare LSN values.

In the *MySQL Enterprise Backup* product, you can specify an LSN to
represent the point in time from which to take an *incremental backup*.
The relevant LSN is displayed by the output of the 'mysqlbackup'
command.  Once you have the LSN corresponding to the time of a full
backup, you can specify that value to take a subsequent incremental
backup, whose output contains another LSN for the next incremental
backup.

master server

Frequently shortened to 'master'.  A database server machine in a
*replication* scenario that processes the initial insert, update, and
delete requests for data.  These changes are propagated to, and repeated
on, other servers known as *slave servers*.  master thread

An 'InnoDB' *thread* that performs various tasks in the background.
Most of these tasks are I/O related, such as writing changes from the
*change buffer* to the appropriate secondary indexes.

To improve *concurrency*, sometimes actions are moved from the master
thread to separate background threads.  For example, in MySQL 5.6 and
higher, *dirty pages* are *flushed* from the *buffer pool* by the *page
cleaner* thread rather than the master thread.  MDL

Acronym for 'metadata lock'.  memcached

A popular component of many MySQL and *NoSQL* software stacks, allowing
fast reads and writes for single values and caching the results entirely
in memory.  Traditionally, applications required extra logic to write
the same data to a MySQL database for permanent storage, or to read data
from a MySQL database when it was not cached yet in memory.  Now,
applications can use the simple 'memcached' protocol, supported by
client libraries for many languages, to communicate directly with MySQL
servers using 'InnoDB' or 'NDB' tables.  These NoSQL interfaces to MySQL
tables allow applications to achieve higher read and write performance
than by issuing SQL statements directly, and can simplify application
logic and deployment configurations for systems that already incorporate
'memcached' for in-memory caching.

The 'memcached' interface to 'InnoDB' tables is available in MySQL 5.6
and higher; see innodb-memcached for details.  The 'memcached'
interface to 'NDB' tables is available in NDB Cluster 7.2 and later; see
<http://dev.mysql.com/doc/ndbapi/en/ndbmemcache.html> for details.
merge

To apply changes to data cached in memory, such as when a page is
brought into the *buffer pool*, and any applicable changes recorded in
the *change buffer* are incorporated into the page in the buffer pool.
The updated data is eventually written to the *tablespace* by the
*flush* mechanism.  metadata lock

A type of *lock* that prevents *DDL* operations on a table that is being
used at the same time by another *transaction*.  For details, see
metadata-locking.

Enhancements to *online* operations, particularly in MySQL 5.6 and
higher, are focused on reducing the amount of metadata locking.  The
objective is for DDL operations that do not change the table structure
(such as 'CREATE INDEX' and 'DROP INDEX'
for 'InnoDB' tables) to proceed while the table is being
queried, updated, and so on by other transactions.  metrics counter

A feature implemented by the 'INNODB_METRICS'
table in the *INFORMATION_SCEMA*, in MySQL 5.6 and
higher.  You can query *counts* and totals for low-level 'InnoDB'
operations, and use the results for performance tuning in combination
with data from the *Performance Schema*.  midpoint insertion strategy

The technique of initially bringing *pages* into the 'InnoDB' *buffer
pool* not at the 'newest' end of the list, but instead somewhere in the
middle.  The exact location of this point can vary, based on the setting
of the 'innodb_old_blocks_pct' option.  The intent is that pages that
are only read once, such as during a *full table scan*, can be aged out
of the buffer pool sooner than with a strict *LRU* algorithm.  For more
information, see innodb-buffer-pool.  mini-transaction

An internal phase of 'InnoDB' processing, when making changes at the
*physical* level to internal data structures during *DML* operations.  A
mini-transaction (mtr) has no notion of *rollback*; multiple
mini-transactions can occur within a single *transaction*.
Mini-transactions write information to the *redo log* that is used
during *crash recovery*.  A mini-transaction can also happen outside the
context of a regular transaction, for example during *purge* processing
by background threads.  mixed-mode insert

An 'INSERT' statement where *auto-increment* values are
specified for some but not all of the new rows.  For example, a
multi-value 'INSERT' could specify a value for the auto-increment column
in some cases and 'NULL' in other cases.  'InnoDB' generates
auto-increment values for the rows where the column value was specified
as 'NULL'.  Another example is an 'INSERT ... ON DUPLICATE KEY UPDATE'
statement, where auto-increment values
might be generated but not used, for any duplicate rows that are
processed as 'UPDATE' rather than 'INSERT' statements.

Can cause consistency issues between *master* and *slave* servers in a
*replication* configuration.  Can require adjusting the value of the
*innodb_autoinc_lock_mode* configuration option.  .MRG file

A file containing references to other tables, used by the 'MERGE'
storage engine.  Files with this extension are always included in
backups produced by the 'mysqlbackup' command of the *MySQL Enterprise
Backup* product.  mtrmulti-core

A type of processor that can take advantage of multi-threaded programs,
such as the MySQL server.  multiversion concurrency controlmutex

Informal abbreviation for 'mutex variable'.  (Mutex itself is short for
'mutual exclusion'.)  The low-level object that 'InnoDB' uses to
represent and enforce exclusive-access *locks* to internal in-memory
data structures.  Once the lock is acquired, any other process, thread,
and so on is prevented from acquiring the same lock.  Contrast with
*rw-locks*, which 'InnoDB' uses to represent and enforce shared-access
*locks* to internal in-memory data structures.  Mutexes and rw-locks are
known collectively as *latches*.  MVCC

Acronym for 'multiversion concurrency control'.  This technique lets
'InnoDB' *transactions* with certain *isolation levels* perform
*consistent read* operations; that is, to query rows that are being
updated by other transactions, and see the values from before those
updates occurred.  This is a powerful technique to increase
*concurrency*, by allowing queries to proceed without waiting due to
*locks* held by the other transactions.

This technique is not universal in the database world.  Some other
database products, and some other MySQL storage engines, do not support
it.  my.cnf

The name, on Unix or Linux systems, of the MySQL *option file*.  my.ini

The name, on Windows systems, of the MySQL *option file*.  .MYD file

A file that MySQL uses to store data for a 'MyISAM'
table.  .MYI file

A file that MySQL uses to store indexes for a 'MyISAM'
table.  mysql

The 'mysql' program is the command-line interpreter for
the MySQL database.  It processes *SQL* statements, and also
MySQL-specific commands such as 'SHOW TABLES', by
passing requests to the 'mysqld' daemon.  MySQL
Enterprise Backup

A licensed product that performs *hot backups* of MySQL databases.  It
offers the most efficiency and flexibility when backing up
'InnoDB' tables, but can also back up
'MyISAM' and other kinds of tables.  mysqlbackup
command

A command-line tool of the *MySQL Enterprise Backup* product.  It
performs a *hot backup* operation for 'InnoDB'
tables, and a warm backup for 'MyISAM'
and other kinds of tables.  See
mysql-enterprise-backup for more information about this command.
mysqld

The 'mysqld' program is the database engine for the MySQL
database.  It runs as a Unix daemon or Windows service, constantly
waiting for requests and performing maintenance work in the background.
mysqldump

A command that performs a *logical backup* of some combination of
databases, tables, and table data.  The results are SQL statements that
reproduce the original schema objects, data, or both.  For substantial
amounts of data, a *physical backup* solution such as *MySQL Enterprise
Backup* is faster, particularly for the *restore* operation.

natural key

An indexed column, typically a *primary key*, where the values have some
real-world significance.  Usually advised against because:

   * If the value should ever change, there is potentially a lot of
     index maintenance to re-sort the *clustered index* and update the
     copies of the primary key value that are repeated in each
     *secondary index*.

   * Even seemingly stable values can change in unpredictable ways that
     are difficult to represent correctly in the database.  For example,
     one country can change into two or several, making the original
     country code obsolete.  Or, rules about unique values might have
     exceptions.  For example, even if taxpayer IDs are intended to be
     unique to a single person, a database might have to handle records
     that violate that rule, such as in cases of identity theft.
     Taxpayer IDs and other sensitive ID numbers also make poor primary
     keys, because they may need to be secured, encrypted, and otherwise
     treated differently than other columns.

Thus, it is typically better to use arbitrary numeric values to form a
*synthetic key*, for example using an *auto-increment* column.  neighbor
page

Any *page* in the same *extent* as a particular page.  When a page is
selected to be *flushed*, any neighbor pages that are *dirty* are
typically flushed as well, as an I/O optimization for traditional hard
disks.  In MySQL 5.6 and up, this behavior can be controlled by the
configuration variable 'innodb_flush_neighbors'; you might turn that
setting off for SSD drives, which do not have the same overhead for
writing smaller batches of data at random locations.  next-key lock

A combination of a *record lock* on the index record and a gap lock on
the gap before the index record.  non-locking read

A *query* that does not use the 'SELECT ... FOR UPDATE' or 'SELECT ...
LOCK IN SHARE MODE' clauses.  The only kind of query allowed for global
tables in a *read-only transaction*.  The opposite of a *locking read*.
See innodb-consistent-read.

'SELECT ... FOR SHARE' replaces 'SELECT ... LOCK IN SHARE MODE' in MySQL
8.0.1, but 'LOCK IN SHARE MODE' remains available for backward
compatibility.  non-repeatable read

The situation when a query retrieves data, and a later query within the
same *transaction* retrieves what should be the same data, but the
queries return different results (changed by another transaction
committing in the meantime).

This kind of operation goes against the *ACID* principle of database
design.  Within a transaction, data should be consistent, with
predictable and stable relationships.

Among different *isolation levels*, non-repeatable reads are prevented
by the *serializable read* and *repeatable read* levels, and allowed by
the *consistent read*, and *read uncommitted* levels.  nonblocking I/O

An industry term that means the same as *asynchronous I/O*. normalized

A database design strategy where data is split into multiple tables, and
duplicate values condensed into single rows represented by an ID, to
avoid storing, querying, and updating redundant or lengthy values.  It
is typically used in *OLTP* applications.

For example, an address might be given a unique ID, so that a census
database could represent the relationship *lives at this address* by
associating that ID with each member of a family, rather than storing
multiple copies of a complex value such as *123 Main Street, Anytown,
USA*.

For another example, although a simple address book application might
store each phone number in the same table as a person's name and
address, a phone company database might give each phone number a special
ID, and store the numbers and IDs in a separate table.  This normalized
representation could simplify large-scale updates when area codes split
apart.

Normalization is not always recommended.  Data that is primarily
queried, and only updated by deleting entirely and reloading, is often
kept in fewer, larger tables with redundant copies of duplicate values.
This data representation is referred to as *denormalized*, and is
frequently found in data warehousing applications.  NoSQL

A broad term for a set of data access technologies that do not use the
*SQL* language as their primary mechanism for reading and writing data.
Some NoSQL technologies act as key-value stores, only accepting
single-value reads and writes; some relax the restrictions of the *ACID*
methodology; still others do not require a pre-planned *schema*.  MySQL
users can combine NoSQL-style processing for speed and simplicity with
SQL operations for flexibility and convenience, by using the *memcached*
API to directly access some kinds of MySQL tables.  The 'memcached'
interface to 'InnoDB' tables is available in MySQL 5.6 and higher; see
innodb-memcached for details.  The 'memcached' interface to
'NDB' tables is available in NDB Cluster 7.2 and later; see
ndbmemcache--Memcache API for NDB Cluster
(http://dev.mysql.com/doc/ndbapi/en/ndbmemcache.html).  NOT NULL
constraint

A type of *constraint* that specifies that a *column* cannot contain any
*NULL* values.  It helps to preserve *referential integrity*, as the
database server can identify data with erroneous missing values.  It
also helps in the arithmetic involved in query optimization, allowing
the optimizer to predict the number of entries in an index on that
column.  NULL

A special value in *SQL*, indicating the absence of data.  Any
arithmetic operation or equality test involving a 'NULL' value, in turn
produces a 'NULL' result.  (Thus it is similar to the IEEE
floating-point concept of NaN, 'not a number'.)  Any aggregate
calculation such as 'AVG()' ignores rows with 'NULL' values, when
determining how many rows to divide by.  The only test that works with
'NULL' values uses the SQL idioms 'IS NULL' or 'IS NOT NULL'.

'NULL' values play a part in *index* operations, because for performance
a database must minimize the overhead of keeping track of missing data
values.  Typically, 'NULL' values are not stored in an index, because a
query that tests an indexed column using a standard comparison operator
could never match a row with a 'NULL' value for that column.  For the
same reason, unique indexes do not prevent 'NULL' values; those values
simply are not represented in the index.  Declaring a 'NOT NULL'
constraint on a column provides reassurance that there are no rows left
out of the index, allowing for better query optimization (accurate
counting of rows and estimation of whether to use the index).

Because the *primary key* must be able to uniquely identify every row in
the table, a single-column primary key cannot contain any 'NULL' values,
and a multi-column primary key cannot contain any rows with 'NULL'
values in all columns.

Although the Oracle database allows a 'NULL' value to be concatenated
with a string, 'InnoDB' treats the result of such an operation as
'NULL'.

off-page column

A column containing variable-length data (such as 'BLOB'.
and 'VARCHAR') that is too long to fit on a *B-tree* page.
The data is stored in *overflow pages*.  The *DYNAMIC* row format is
more efficient for such storage than the older *COMPACT* row format.
OLTP

Acronym for 'Online Transaction Processing'.  A database system, or a
database application, that runs a workload with many *transactions*,
with frequent writes as well as reads, typically affecting small amounts
of data at a time.  For example, an airline reservation system or an
application that processes bank deposits.  The data might be organized
in *normalized* form for a balance between *DML* (insert/update/delete)
efficiency and *query* efficiency.  Contrast with *data warehouse*.

With its *row-level locking* and *transactional* capability, *InnoDB* is
the ideal storage engine for MySQL tables used in OLTP applications.
online

A type of operation that involves no downtime, blocking, or restricted
operation for the database.  Typically applied to *DDL*. Operations that
shorten the periods of restricted operation, such as *fast index
creation*, have evolved into a wider set of *online DDL* operations in
MySQL 5.6.

In the context of backups, a *hot backup* is an online operation and a
*warm backup* is partially an online operation.  online DDL

A feature that improves the performance, concurrency, and availability
of 'InnoDB' tables during *DDL* (primarily 'ALTER TABLE')
operations.  See innodb-online-ddl for details.

The details vary according to the type of operation.  In some cases, the
table can be modified concurrently while the 'ALTER TABLE'
is in progress.  The operation might be able to be
performed without a table copy, or using a specially optimized type of
table copy.  Space usage is controlled by the
'innodb_online_alter_log_max_size' configuration option.

This feature is an enhancement of the *Fast Index Creation* feature in
MySQL 5.5.  .OPT file

A file containing database configuration information.  Files with this
extension are included in backups produced by the 'mysqlbackup' command
of the *MySQL Enterprise Backup* product.  optimistic

A methodology that guides low-level implementation decisions for a
relational database system.  The requirements of performance and
*concurrency* in a relational database mean that operations must be
started or dispatched quickly.  The requirements of consistency and
*referential integrity* mean that any operation could fail: a
transaction might be rolled back, a *DML* operation could violate a
constraint, a request for a lock could cause a deadlock, a network error
could cause a timeout.  An optimistic strategy is one that assumes most
requests or attempts will succeed, so that relatively little work is
done to prepare for the failure case.  When this assumption is true, the
database does little unnecessary work; when requests do fail, extra work
must be done to clean up and undo changes.

'InnoDB' uses optimistic strategies for operations such as *locking* and
*commits*.  For example, data changed by a transaction can be written to
the data files before the commit occurs, making the commit itself very
fast, but requiring more work to undo the changes if the transaction is
rolled back.

The opposite of an optimistic strategy is a *pessimistic* one, where a
system is optimized to deal with operations that are unreliable and
frequently unsuccessful.  This methodology is rare in a database system,
because so much care goes into choosing reliable hardware, networks, and
algorithms.  optimizer

The MySQL component that determines the best *indexes* and *join* order
to use for a *query*, based on characteristics and data distribution of
the relevant *tables*.  option

A configuration parameter for MySQL, either stored in the *option file*
or passed on the command line.

For the *options* that apply to *InnoDB* tables, each option name starts
with the prefix 'innodb_'.  option file

The file that holds the configuration *options* for the MySQL instance.
Traditionally, on Linux and Unix this file is named 'my.cnf', and on
Windows it is named 'my.ini'.  overflow page

Separately allocated disk *pages* that hold variable-length columns
(such as 'BLOB' and 'VARCHAR') that are too long to fit on a *B-tree*
page.  The associated columns are known as *off-page columns*.

page

A unit representing how much data 'InnoDB' transfers at any one time
between disk (the *data files*) and memory (the *buffer pool*).  A page
can contain one or more *rows*, depending on how much data is in each
row.  If a row does not fit entirely into a single page, 'InnoDB' sets
up additional pointer-style data structures so that the information
about the row can be stored in one page.

One way to fit more data in each page is to use *compressed row format*.
For tables that use BLOBs or large text fields, *compact row format*
allows those large columns to be stored separately from the rest of the
row, reducing I/O overhead and memory usage for queries that do not
reference those columns.

When 'InnoDB' reads or writes sets of pages as a batch to increase I/O
throughput, it reads or writes an *extent* at a time.

All the 'InnoDB' disk data structures within a MySQL instance share the
same *page size*.  page cleaner

An 'InnoDB' background *thread* that *flushes* *dirty pages* from the
*buffer pool*.  Prior to MySQL 5.6, this activity was performed by the
*master thread*.  The number of page cleaner threads is controlled by
the 'innodb_page_cleaners' configuration option, introduced in MySQL
5.7.4.  page size

For releases up to and including MySQL 5.5, the size of each 'InnoDB'
*page* is fixed at 16 kilobytes.  This value represents a balance: large
enough to hold the data for most rows, yet small enough to minimize the
performance overhead of transferring unneeded data to memory.  Other
values are not tested or supported.

Starting in MySQL 5.6, the page size for an 'InnoDB' *instance* can be
either 4KB, 8KB, or 16KB, controlled by the 'innodb_page_size'
configuration option.  As of MySQL 5.7.6, 'InnoDB' also supports 32KB
and 64KB page sizes.  For 32KB and 64KB page sizes,
'ROW_FORMAT=COMPRESSED' is not supported and the maximum record size is
16KB.

Page size is set when creating the MySQL instance, and it remains
constant afterward.  The same page size applies to all 'InnoDB'
*tablespaces*, including the *system tablespace*, *file-per-table*
tablespaces, and *general tablespaces*.

Smaller page sizes can help performance with storage devices that use
small block sizes, particularly for *SSD* devices in *disk-bound*
workloads, such as for *OLTP* applications.  As individual rows are
updated, less data is copied into memory, written to disk, reorganized,
locked, and so on.  .par file

A file containing partition definitions.  Files with this extension are
included in backups produced by the 'mysqlbackup' command of the *MySQL
Enterprise Backup* product.

With the introduction of native partitioning support for 'InnoDB' tables
in MySQL 5.7.6, '.par' files are no longer created for partitioned
'InnoDB' tables.  Partitioned 'MyISAM' tables continue to use '.par'
files in MySQL 5.7.  In MySQL 8.0, partitioning support is only provided
by the 'InnoDB' storage engine.  As such, '.par' files are no longer
used as of MySQL 8.0.  parent table

The table in a *foreign key* relationship that holds the initial column
values pointed to from the *child table*.  The consequences of deleting,
or updating rows in the parent table depend on the 'ON UPDATE' and 'ON
DELETE' clauses in the foreign key definition.  Rows with corresponding
values in the child table could be automatically deleted or updated in
turn, or those columns could be set to 'NULL', or the operation could be
prevented.  partial backup

A *backup* that contains some of the *tables* in a MySQL database, or
some of the databases in a MySQL instance.  Contrast with *full backup*.
partial index

An *index* that represents only part of a column value, typically the
first N characters (the *prefix*) of a long 'VARCHAR' value.
Performance Schema

The 'performance_schema' schema, in MySQL 5.5 and up, presents a set of
tables that you can query to get detailed information about the
performance characteristics of many internal parts of the MySQL server.
See performance-schema.  persistent statistics

A feature in MySQL 5.6 that stores *index* statistics for 'InnoDB'
*tables* on disk, providing better *plan stability* for *queries*.  For
more information, see innodb-persistent-stats.  pessimistic

A methodology that sacrifices performance or concurrency in favor of
safety.  It is appropriate if a high proportion of requests or attempts
might fail, or if the consequences of a failed request are severe.
'InnoDB' uses what is known as a pessimistic *locking* strategy, to
minimize the chance of *deadlocks*.  At the application level, you might
avoid deadlocks by using a pessimistic strategy of acquiring all locks
needed by a transaction at the very beginning.

Many built-in database mechanisms use the opposite *optimistic*
methodology.  phantom

A row that appears in the result set of a query, but not in the result
set of an earlier query.  For example, if a query is run twice within a
*transaction*, and in the meantime, another transaction commits after
inserting a new row or updating a row so that it matches the 'WHERE'
clause of the query.

This occurrence is known as a phantom read.  It is harder to guard
against than a *non-repeatable read*, because locking all the rows from
the first query result set does not prevent the changes that cause the
phantom to appear.

Among different *isolation levels*, phantom reads are prevented by the
*serializable read* level, and allowed by the *repeatable read*,
*consistent read*, and *read uncommitted* levels.  physical

A type of operation that involves hardware-related aspects such as disk
blocks, memory pages, files, bits, disk reads, and so on.  Typically,
physical aspects are important during expert-level performance tuning
and problem diagnosis.  Contrast with *logical*.  physical backup

A *backup* that copies the actual data files.  For example, the
*'mysqlbackup'* command of the *MySQL Enterprise Backup* product
produces a physical backup, because its output contains data files that
can be used directly by the 'mysqld' server, resulting in a faster
*restore* operation.  Contrast with *logical backup*.  PITR

Acronym for *point-in-time recovery*.  plan stability

A property of a *query execution plan*, where the optimizer makes the
same choices each time for a given *query*, so that performance is
consistent and predictable.  point-in-time recovery

The process of restoring a *backup* to recreate the state of the
database at a specific date and time.  Commonly abbreviated 'PITR'.
Because it is unlikely that the specified time corresponds exactly to
the time of a backup, this technique usually requires a combination of a
*physical backup* and a *logical backup*.  For example, with the *MySQL
Enterprise Backup* product, you restore the last backup that you took
before the specified point in time, then replay changes from the *binary
log* between the time of the backup and the PITR time.  prefixprepared
backup

A set of backup files, produced by the *MySQL Enterprise Backup*
product, after all the stages of applying *binary logs* and *incremental
backups* are finished.  The resulting files are ready to be *restored*.
Prior to the apply steps, the files are known as a *raw backup*.
primary key

A set of columns--and by implication, the index based on this set of
columns--that can uniquely identify every row in a table.  As such, it
must be a unique index that does not contain any 'NULL' values.

'InnoDB' requires that every table has such an index (also called the
*clustered index* or *cluster index*), and organizes the table storage
based on the column values of the primary key.

When choosing primary key values, consider using arbitrary values (a
*synthetic key*) rather than relying on values derived from some other
source (a *natural key*).  process

An instance of an executing program.  The operating system switches
between multiple running processes, allowing for a certain degree of
*concurrency*.  On most operating systems, processes can contain
multiple *threads* of execution that share resources.  Context-switching
between threads is faster than the equivalent switching between
processes.  pseudo-record

An artificial record in an index, used for *locking* key values or
ranges that do not currently exist.  Pthreads

The POSIX threads standard, which defines an API for threading and
locking operations on Unix and Linux systems.  On Unix and Linux
systems, 'InnoDB' uses this implementation for *mutexes*.  purge

A type of garbage collection performed by one or more separate
background threads (controlled by 'innodb_purge_threads') that runs on a
periodic schedule.  Purge parses and processes *undo log* pages from the
*history list* for the purpose of removing clustered and secondary index
records that were marked for deletion (by previous 'DELETE'
statements) and are no longer required for *MVCC* or *rollback*.
Purge frees undo log pages from the history list after processing them.
purge buffering

The technique of storing changes to secondary index pages, resulting
from 'DELETE' operations, in the *change buffer* rather than writing the
changes immediately, so that the physical writes can be performed to
minimize random I/O. (Because delete operations are a two-step process,
this operation buffers the write that normally purges an index record
that was previously marked for deletion.)  It is one of the types of
*change buffering*; the others are *insert buffering* and *delete
buffering*.  purge lag

Another name for the 'InnoDB' *history list*.  Related to the
'innodb_max_purge_lag' configuration option.  purge thread

A *thread* within the 'InnoDB' process that is dedicated to performing
the periodic *purge* operation.  In MySQL 5.6 and higher, multiple purge
threads are enabled by the 'innodb_purge_threads' configuration option.

query

In *SQL*, an operation that reads information from one or more *tables*.
Depending on the organization of data and the parameters of the query,
the lookup might be optimized by consulting an *index*.  If multiple
tables are involved, the query is known as a *join*.

For historical reasons, sometimes discussions of internal processing for
statements use 'query' in a broader sense, including other types of
MySQL statements such as *DDL* and *DML* statements.  query execution
plan

The set of decisions made by the optimizer about how to perform a
*query* most efficiently, including which *index* or indexes to use, and
the order in which to *join* tables.  *Plan stability* involves the same
choices being made consistently for a given query.  query logquiesce

To reduce the amount of database activity, often in preparation for an
operation such as an 'ALTER TABLE', a *backup*, or a
*shutdown*.  Might or might not involve doing as much *flushing* as
possible, so that *InnoDB* does not continue doing background I/O.

In MySQL 5.6 and higher, the syntax 'FLUSH TABLES ... FOR EXPORT' writes
some data to disk for 'InnoDB' tables that make it simpler to back up
those tables by copying the data files.

R-tree

A tree data structure used for spatial indexing of multi-dimensional
data such as geographical coordinates, rectangles or polygons.  RAID

Acronym for 'Redundant Array of Inexpensive Drives'.  Spreading I/O
operations across multiple drives enables greater *concurrency* at the
hardware level, and improves the efficiency of low-level write
operations that otherwise would be performed in sequence.  random dive

A technique for quickly estimating the number of different values in a
column (the column's *cardinality*).  'InnoDB' samples pages at random
from the index and uses that data to estimate the number of different
values.  raw backup

The initial set of backup files produced by the *MySQL Enterprise
Backup* product, before the changes reflected in the *binary log* and
any *incremental backups* are applied.  At this stage, the files are not
ready to *restore*.  After these changes are applied, the files are
known as a *prepared backup*.  READ COMMITTED

An *isolation level* that uses a *locking* strategy that relaxes some of
the protection between *transactions*, in the interest of performance.
Transactions cannot see uncommitted data from other transactions, but
they can see data that is committed by another transaction after the
current transaction started.  Thus, a transaction never sees any bad
data, but the data that it does see may depend to some extent on the
timing of other transactions.

When a transaction with this isolation level performs 'UPDATE ... WHERE'
or 'DELETE ... WHERE' operations, other transactions might have to wait.
The transaction can perform 'SELECT ... FOR UPDATE', and 'LOCK IN SHARE
MODE' operations without making other transactions wait.

'SELECT ... FOR SHARE' replaces 'SELECT ... LOCK IN SHARE MODE' in MySQL
8.0.1, but 'LOCK IN SHARE MODE' remains available for backward
compatibility.  read phenomena

Phenomena such as *dirty reads*, *non-repeatable reads*, and *phantom*
reads which can occur when a transaction reads data that another
transaction has modified.  READ UNCOMMITTED

The *isolation level* that provides the least amount of protection
between transactions.  Queries employ a *locking* strategy that allows
them to proceed in situations where they would normally wait for another
transaction.  However, this extra performance comes at the cost of less
reliable results, including data that has been changed by other
transactions and not committed yet (known as *dirty read*).  Use this
isolation level with great caution, and be aware that the results might
not be consistent or reproducible, depending on what other transactions
are doing at the same time.  Typically, transactions with this isolation
level only do queries, not insert, update, or delete operations.  read
view

An internal snapshot used by the *MVCC* mechanism of 'InnoDB'.  Certain
*transactions*, depending on their *isolation level*, see the data
values as they were at the time the transaction (or in some cases, the
statement) started.  Isolation levels that use a read view are
*REPEATABLE READ*, *READ COMMITTED*, and *READ UNCOMMITTED*. read-ahead

A type of I/O request that prefetches a group of *pages* (an entire
*extent*) into the *buffer pool* asynchronously, in anticipation that
these pages will be needed soon.  The linear read-ahead technique
prefetches all the pages of one extent based on access patterns for
pages in the preceding extent.  The random read-ahead technique
prefetches all the pages for an extent once a certain number of pages
from the same extent are in the buffer pool.  Random read-ahead is not
part of MySQL 5.5, but is re-introduced in MySQL 5.6 under the control
of the 'innodb_random_read_ahead' configuration option.  read-only
transaction

A type of *transaction* that can be optimized for 'InnoDB' tables by
eliminating some of the bookkeeping involved with creating a *read view*
for each transaction.  Can only perform *non-locking read* queries.  It
can be started explicitly with the syntax 'START TRANSACTION READ ONLY',
or automatically under certain conditions.  See
innodb-performance-ro-txn for details.  record lock

A lock on an index record.  For example, 'SELECT c1 FROM t WHERE c1 = 10
FOR UPDATE;' prevents any other transaction from inserting, updating, or
deleting rows where the value of 't.c1' is 10.  Contrast with *gap lock*
and *next-key lock*.  redo

The data, in units of records, recorded in the *redo log* when DML
statements make changes to 'InnoDB' tables.  It is used during *crash
recovery* to correct data written by incomplete *transactions*.  The
ever-increasing *LSN* value represents the cumulative amount of redo
data that has passed through the redo log.  redo log

A disk-based data structure used during *crash recovery*, to correct
data written by incomplete *transactions*.  During normal operation, it
encodes requests to change 'InnoDB' table data, which result from SQL
statements or low-level API calls through NoSQL interfaces.
Modifications that did not finish updating the *data files* before an
unexpected *shutdown* are replayed automatically.

The redo log is physically represented as a set of files, typically
named 'ib_logfile0' and 'ib_logfile1'.  The data in the redo log is
encoded in terms of records affected; this data is collectively referred
to as *redo*.  The passage of data through the redo logs is represented
by the ever-increasing *LSN* value.  The original 4GB limit on maximum
size for the redo log is raised to 512GB in MySQL 5.6.3.

The disk layout of the redo log is influenced by the configuration
options 'innodb_log_file_size', 'innodb_log_group_home_dir', and
(rarely) 'innodb_log_files_in_group'.  The performance of redo log
operations is also affected by the *log buffer*, which is controlled by
the 'innodb_log_buffer_size' configuration option.  redundant row format

The oldest 'InnoDB' *row format*.  Prior to MySQL 5.0.3, it was the only
row format available in 'InnoDB'.  From MySQL 5.0.3 to MySQL 5.7.8, the
default row format is *COMPACT*. As of MySQL 5.7.9, the default row
format is defined by the 'innodb_default_row_format' configuration
option, which has a default setting of *DYNAMIC*. You can still specify
the *REDUNDANT* row format for compatibility with older 'InnoDB' tables.

For more information, see innodb-row-format-antelope.
referential integrity

The technique of maintaining data always in a consistent format, part of
the *ACID* philosophy.  In particular, data in different tables is kept
consistent through the use of *foreign key constraints*, which can
prevent changes from happening or automatically propagate those changes
to all related tables.  Related mechanisms include the *unique
constraint*, which prevents duplicate values from being inserted by
mistake, and the *NOT NULL constraint*, which prevents blank values from
being inserted by mistake.  relational

An important aspect of modern database systems.  The database server
encodes and enforces relationships such as one-to-one, one-to-many,
many-to-one, and uniqueness.  For example, a person might have zero,
one, or many phone numbers in an address database; a single phone number
might be associated with several family members.  In a financial
database, a person might be required to have exactly one taxpayer ID,
and any taxpayer ID could only be associated with one person.

The database server can use these relationships to prevent bad data from
being inserted, and to find efficient ways to look up information.  For
example, if a value is declared to be unique, the server can stop
searching as soon as the first match is found, and it can reject
attempts to insert a second copy of the same value.

At the database level, these relationships are expressed through SQL
features such as *columns* within a table, unique and 'NOT NULL'
*constraints*, *foreign keys*, and different kinds of join operations.
Complex relationships typically involve data split between more than one
table.  Often, the data is *normalized*, so that duplicate values in
one-to-many relationships are stored only once.

In a mathematical context, the relations within a database are derived
from set theory.  For example, the 'OR' and 'AND' operators of a 'WHERE'
clause represent the notions of union and intersection.  relevance

In the *full-text search* feature, a number signifying the similarity
between the search string and the data in the *FULLTEXT index*.  For
example, when you search for a single word, that word is typically more
relevant for a row where it occurs several times in the text than a row
where it appears only once.  REPEATABLE READ

The default *isolation level* for 'InnoDB'.  It prevents any rows that
are queried from being changed by other *transactions*, thus blocking
*non-repeatable reads* but not *phantom* reads.  It uses a moderately
strict *locking* strategy so that all queries within a transaction see
data from the same snapshot, that is, the data as it was at the time the
transaction started.

When a transaction with this isolation level performs 'UPDATE ...
WHERE', 'DELETE ... WHERE', 'SELECT ... FOR UPDATE', and 'LOCK IN SHARE
MODE' operations, other transactions might have to wait.

'SELECT ... FOR SHARE' replaces 'SELECT ... LOCK IN SHARE MODE' in MySQL
8.0.1, but 'LOCK IN SHARE MODE' remains available for backward
compatibility.  repertoire

Repertoire is a term applied to character sets.  A character set
repertoire is the collection of characters in the set.  See
charset-repertoire.  replication

The practice of sending changes from a *master database*, to one or more
*slave databases*, so that all databases have the same data.  This
technique has a wide range of uses, such as load-balancing for better
scalability, disaster recovery, and testing software upgrades and
configuration changes.  The changes can be sent between the database by
methods called *row-based replication* and *statement-based
replication*.  restore

The process of putting a set of backup files from the *MySQL Enterprise
Backup* product in place for use by MySQL. This operation can be
performed to fix a corrupted database, to return to some earlier point
in time, or (in a *replication* context) to set up a new *slave
database*.  In the *MySQL Enterprise Backup* product, this operation is
performed by the 'copy-back' option of the 'mysqlbackup' command.
rollback

A *SQL* statement that ends a *transaction*, undoing any changes made by
the transaction.  It is the opposite of *commit*, which makes permanent
any changes made in the transaction.

By default, MySQL uses the *autocommit* setting, which automatically
issues a commit following each SQL statement.  You must change this
setting before you can use the rollback technique.  rollback segment

The storage area containing the *undo log*.  Rollback segments have
traditionally resided in the *system tablespace*.  As of MySQL 5.6,
rollback segments can reside in *undo tablespaces*.  As of MySQL 5.7,
rollback segments are also allocated to the _temporary tablespace_.  row

The logical data structure defined by a set of *columns*.  A set of rows
makes up a *table*.  Within 'InnoDB' *data files*, each *page* can
contain one or more rows.

Although 'InnoDB' uses the term *row format* for consistency with MySQL
syntax, the row format is a property of each table and applies to all
rows in that table.  row format

The disk storage format for *rows* of an 'InnoDB' *table*.  As 'InnoDB'
gains new capabilities such as *compression*, new row formats are
introduced to support the resulting improvements in storage efficiency
and performance.

The row format of an 'InnoDB' table is specified by the 'ROW_FORMAT'
option or by the 'innodb_default_row_format' configuration option
(introduced in MySQL 5.7.9).  Row formats include 'REDUNDANT',
'COMPACT', 'COMPRESSED', and 'DYNAMIC'.  To view the row format of an
'InnoDB' table, issue the 'SHOW TABLE STATUS'.
statement or query 'InnoDB' table metadata in the
'INFORMATION_SCHEMA'.  row lock

A *lock* that prevents a row from being accessed in an incompatible way
by another *transaction*.  Other rows in the same table can be freely
written to by other transactions.  This is the type of *locking* done by
*DML* operations on *InnoDB* tables.

Contrast with *table locks* used by 'MyISAM',
or during *DDL* operations on 'InnoDB' tables
that cannot be done with *online DDL*; those locks block concurrent
access to the table.  row-based replication

A form of *replication* where events are propagated from the *master
server* specifying how to change individual rows on the *slave server*.
It is safe to use for all settings of the 'innodb_autoinc_lock_mode'
option.  row-level locking

The *locking* mechanism used for *InnoDB* tables, relying on *row locks*
rather than *table locks*.  Multiple *transactions* can modify the same
table concurrently.  Only if two transactions try to modify the same row
does one of the transactions wait for the other to complete (and release
its row locks).  rw-lock

The low-level object that 'InnoDB' uses to represent and enforce
shared-access *locks* to internal in-memory data structures following
certain rules.  Contrast with *mutexes*, which 'InnoDB' uses to
represent and enforce exclusive access to internal in-memory data
structures.  Mutexes and rw-locks are known collectively as *latches*.

'rw-lock' types include 's-locks' (shared locks), 'x-locks' (exclusive
locks), and 'sx-locks' (shared-exclusive locks).

   * An 's-lock' provides read access to a common resource.

   * An 'x-lock' provides write access to a common resource while not
     permitting inconsistent reads by other threads.

   * An 'sx-lock' provides write access to a common resource while
     permitting inconsistent reads by other threads.  'sx-locks' were
     introduced in MySQL 5.7 to optimize concurrency and improve
     scalability for read-write workloads.

The following matrix summarizes rw-lock type compatibility.

               S              SX             X

S              Compatible     Compatible     Conflict

SX             Compatible     Conflict       Conflict

X              Conflict       Conflict       Conflict

savepoint

Savepoints help to implement nested *transactions*.  They can be used to
provide scope to operations on tables that are part of a larger
transaction.  For example, scheduling a trip in a reservation system
might involve booking several different flights; if a desired flight is
unavailable, you might *roll back* the changes involved in booking that
one leg, without rolling back the earlier flights that were successfully
booked.  scalability

The ability to add more work and issue more simultaneous requests to a
system, without a sudden drop in performance due to exceeding the limits
of system capacity.  Software architecture, hardware configuration,
application coding, and type of workload all play a part in scalability.
When the system reaches its maximum capacity, popular techniques for
increasing scalability are *scale up* (increasing the capacity of
existing hardware or software) and *scale out* (adding new servers and
more instances of MySQL). Often paired with *availability* as critical
aspects of a large-scale deployment.  scale out

A technique for increasing *scalability* by adding new servers and more
instances of MySQL. For example, setting up replication, NDB Cluster,
connection pooling, or other features that spread work across a group of
servers.  Contrast with *scale up*.  scale up

A technique for increasing *scalability* by increasing the capacity of
existing hardware or software.  For example, increasing the memory on a
server and adjusting memory-related parameters such as
'innodb_buffer_pool_size' and 'innodb_buffer_pool_instances'.  Contrast
with *scale out*.  schema

Conceptually, a schema is a set of interrelated database objects, such
as tables, table columns, data types of the columns, indexes, foreign
keys, and so on.  These objects are connected through SQL syntax,
because the columns make up the tables, the foreign keys refer to tables
and columns, and so on.  Ideally, they are also connected logically,
working together as part of a unified application or flexible framework.
For example, the *INFORMATION_SCHEMA* and *performance_schema* databases
use 'schema' in their names to emphasize the close relationships between
the tables and columns they contain.

In MySQL, physically, a *schema* is synonymous with a *database*.  You
can substitute the keyword 'SCHEMA' instead of 'DATABASE' in MySQL SQL
syntax, for example using 'CREATE SCHEMA' instead of 'CREATE DATABASE'.

Some other database products draw a distinction.  For example, in the
Oracle Database product, a *schema* represents only a part of a
database: the tables and other objects owned by a single user.  search
index

In MySQL, *full-text search* queries use a special kind of index, the
*FULLTEXT index*.  In MySQL 5.6.4 and up, 'InnoDB' and 'MyISAM' tables
both support 'FULLTEXT' indexes; formerly, these indexes were only
available for 'MyISAM' tables.  secondary index

A type of 'InnoDB' *index* that represents a subset of table columns.
An 'InnoDB' table can have zero, one, or many secondary indexes.
(Contrast with the *clustered index*, which is required for each
'InnoDB' table, and stores the data for all the table columns.)

A secondary index can be used to satisfy queries that only require
values from the indexed columns.  For more complex queries, it can be
used to identify the relevant rows in the table, which are then
retrieved through lookups using the clustered index.

Creating and dropping secondary indexes has traditionally involved
significant overhead from copying all the data in the 'InnoDB' table.
The *fast index creation* feature makes both 'CREATE INDEX' and 'DROP
INDEX' statements much faster for 'InnoDB' secondary indexes.  segment

A division within an 'InnoDB' *tablespace*.  If a tablespace is
analogous to a directory, the segments are analogous to files within
that directory.  A segment can grow.  New segments can be created.

For example, within a *file-per-table* tablespace, table data is in one
segment and each associated index is in its own segment.  The *system
tablespace* contains many different segments, because it can hold many
tables and their associated indexes.  Prior to MySQL 8.0, the system
tablespace also includes one or more *rollback segments* used for *undo
logs*.

Segments grow and shrink as data is inserted and deleted.  When a
segment needs more room, it is extended by one *extent* (1 megabyte) at
a time.  Similarly, a segment releases one extent's worth of space when
all the data in that extent is no longer needed.  selectivity

A property of data distribution, the number of distinct values in a
column (its *cardinality*) divided by the number of records in the
table.  High selectivity means that the column values are relatively
unique, and can retrieved efficiently through an index.  If you (or the
query optimizer) can predict that a test in a 'WHERE' clause only
matches a small number (or proportion) of rows in a table, the overall
*query* tends to be efficient if it evaluates that test first, using an
index.  semi-consistent read

A type of read operation used for 'UPDATE' statements, that is a
combination of *READ COMMITTED* and *consistent read*.  When an 'UPDATE'
statement examines a row that is already locked, 'InnoDB' returns the
latest committed version to MySQL so that MySQL can determine whether
the row matches the 'WHERE' condition of the 'UPDATE'.  If the row
matches (must be updated), MySQL reads the row again, and this time
'InnoDB' either locks it or waits for a lock on it.  This type of read
operation can only happen when the transaction has the READ COMMITTED
*isolation level*, or when the 'innodb_locks_unsafe_for_binlog' option
is enabled.  'innodb_locks_unsafe_for_binlog' was removed in MySQL 8.0.
SERIALIZABLE

The *isolation level* that uses the most conservative locking strategy,
to prevent any other *transactions* from inserting or changing data that
was read by this transaction, until it is finished.  This way, the same
query can be run over and over within a transaction, and be certain to
retrieve the same set of results each time.  Any attempt to change data
that was committed by another transaction since the start of the current
transaction, cause the current transaction to wait.

This is the default isolation level specified by the SQL standard.  In
practice, this degree of strictness is rarely needed, so the default
isolation level for 'InnoDB' is the next most strict, *REPEATABLE READ*.
server

A type of program that runs continuously, waiting to receive and act
upon requests from another program (the *client*).  Because often an
entire computer is dedicated to running one or more server programs
(such as a database server, a web server, an application server, or some
combination of these), the term *server* can also refer to the computer
that runs the server software.  shared lock

A kind of *lock* that allows other *transactions* to read the locked
object, and to also acquire other shared locks on it, but not to write
to it.  The opposite of *exclusive lock*.  shared tablespace

Another way of referring to the *system tablespace* or to a *general
tablespace*.  General tablespaces were introduced in MySQL 5.7 sharp
checkpoint

The process of *flushing* to disk all *dirty* buffer pool pages whose
redo entries are contained in certain portion of the *redo log*.  Occurs
before 'InnoDB' reuses a portion of a log file; the log files are used
in a circular fashion.  Typically occurs with write-intensive
*workloads*.  shutdown

The process of stopping the MySQL server.  By default, this process
cleans up operations for *InnoDB* tables, so 'InnoDB' can be *slow* to
shut down, but fast to start up later.  If you skip the cleanup
operations, it is *fast* to shut down but the cleanup must be performed
during the next restart.

The shutdown mode for 'InnoDB' is controlled by the
'innodb_fast_shutdown' option.  slave server

Frequently shortened to 'slave'.  A database *server* machine in a
*replication* scenario that receives changes from another server (the
*master*) and applies those same changes.  Thus it maintains the same
contents as the master, although it might lag somewhat behind.

In MySQL, slave servers are commonly used in disaster recovery, to take
the place of a master servers that fails.  They are also commonly used
for testing software upgrades and new settings, to ensure that database
configuration changes do not cause problems with performance or
reliability.

Slave servers typically have high workloads, because they process all
the *DML* (write) operations relayed from the master, as well as user
queries.  To ensure that slave servers can apply changes from the master
fast enough, they frequently have fast I/O devices and sufficient CPU
and memory to run multiple database instances on the same slave server.
For example, the master server might use hard drive storage while the
slave servers use *SSD*s.  slow query log

A type of *log* used for performance tuning of SQL statements processed
by the MySQL server.  The log information is stored in a file.  You must
enable this feature to use it.  You control which categories of 'slow'
SQL statements are logged.  For more information, see
slow-query-log.

slow shutdown

A type of *shutdown* that does additional 'InnoDB' flushing operations
before completing.  Also known as a *clean shutdown*.  Specified by the
configuration parameter 'innodb_fast_shutdown=0' or the command 'SET
GLOBAL innodb_fast_shutdown=0;'.  Although the shutdown itself can take
longer, that time will be saved on the subsequent startup.  snapshot

A representation of data at a particular time, which remains the same
even as changes are *committed* by other *transactions*.  Used by
certain *isolation levels* to allow *consistent reads*.  sort buffer

The buffer used for sorting data during creation of an 'InnoDB' index.
Sort buffer size is configured using the 'innodb_sort_buffer_size'
configuration option.  space ID

An identifier used to uniquely identify an 'InnoDB' *tablespace* within
a MySQL instance.  The space ID for the *system tablespace* is always
zero; this same ID applies to all tables within the system tablespace or
within a general tablespace.  Each *file-per-table* tablespace and
*general tablespace* has its own space ID.

Prior to MySQL 5.6, this hardcoded value presented difficulties in
moving 'InnoDB' tablespace files between MySQL instances.  Starting in
MySQL 5.6, you can copy tablespace files between instances by using the
*transportable tablespace* feature involving the statements 'FLUSH
TABLES ... FOR EXPORT', 'ALTER TABLE ... DISCARD TABLESPACE', and 'ALTER
TABLE ... IMPORT TABLESPACE'.  The information needed to adjust the
space ID is conveyed in the *.cfg file* which you copy along with the
tablespace.  See tablespace-copying for details.  sparse file

A type of file that uses file system space more efficiently by writing
metadata representing empty blocks to disk instead of writing the actual
empty space.  The 'InnoDB' *transparent page compression* feature relies
on sparse file support.  For more information, see
innodb-page-compression.  spin

A type of *wait* operation that continuously tests whether a resource
becomes available.  This technique is used for resources that are
typically held only for brief periods, where it is more efficient to
wait in a 'busy loop' than to put the thread to sleep and perform a
context switch.  If the resource does not become available within a
short time, the spin loop ceases and another wait technique is used.
SQL

The Structured Query Language that is standard for performing database
operations.  Often divided into the categories *DDL*, *DML*, and
*queries*.  MySQL includes some additional statement categories such as
*replication*.  See language-structure for the building blocks
of SQL syntax, see data-types for the data types to use for MySQL
table columns, see sql-syntax for details about SQL statements and
their associated categories, and functions for standard and
MySQL-specific functions to use in queries.  SSD

Acronym for 'solid-state drive'.  A type of storage device with
different performance characteristics than a traditional hard disk drive
(*HDD*): smaller storage capacity, faster for random reads, no moving
parts, and with a number of considerations affecting write performance.
Its performance characteristics can influence the throughput of a
*disk-bound* workload.  startup

The process of starting the MySQL server.  Typically done by one of the
programs listed in programs-server.  The opposite of *shutdown*.
statement-based replication

A form of *replication* where SQL statements are sent from the *master
server* and replayed on the *slave server*.  It requires some care with
the setting for the 'innodb_autoinc_lock_mode' option, to avoid
potential timing problems with *auto-increment locking*.  statistics

Estimated values relating to each 'InnoDB' *table* and *index*, used to
construct an efficient *query execution plan*.  The main values are the
*cardinality* (number of distinct values) and the total number of table
rows or index entries.  The statistics for the table represent the data
in its *primary key* index.  The statistics for a *secondary index*
represent the rows covered by that index.

The values are estimated rather than counted precisely because at any
moment, different *transactions* can be inserting and deleting rows from
the same table.  To keep the values from being recalculated frequently,
you can enable *persistent statistics*, where the values are stored in
'InnoDB' system tables, and refreshed only when you issue an
'ANALYZE TABLE' statement.

You can control how *NULL* values are treated when calculating
statistics through the 'innodb_stats_method' configuration option.

Other types of statistics are available for database objects and
database activity through the *INFORMATION_SCHEMA* and
*PERFORMANCE_SCHEMA* tables.  stemming

The ability to search for different variations of a word based on a
common root word, such as singular and plural, or past, present, and
future verb tense.  This feature is currently supported in 'MyISAM'
*full-text search* feature but not in *FULLTEXT indexes* for 'InnoDB'
tables.  stopword

In a *FULLTEXT index*, a word that is considered common or trivial
enough that it is omitted from the *search index* and ignored in search
queries.  Different configuration settings control stopword processing
for 'InnoDB' and 'MyISAM' tables.  See fulltext-stopwords for
details.  storage engine

A component of the MySQL database that performs the low-level work of
storing, updating, and querying data.  In MySQL 5.5 and higher, *InnoDB*
is the default storage engine for new tables, superceding 'MyISAM'.
Different storage engines are designed with different tradeoffs between
factors such as memory usage versus disk usage, read speed versus write
speed, and speed versus robustness.  Each storage engine manages
specific tables, so we refer to 'InnoDB'.
tables, see 'MyISAM' tables, and so on.

The *MySQL Enterprise Backup* product is optimized for backing up
'InnoDB' tables.  It can also back up tables handled by 'MyISAM' and
other storage engines.  stored generated column

A column whose values are computed from an expression included in the
column definition.  Column values are evaluated and stored when rows are
inserted or updated.  A stored generated column requires storage space
and can be indexed.

Contrast with *virtual generated column*.  strict mode

The general name for the setting controlled by the 'innodb_strict_mode'
option.  Turning on this setting causes certain conditions that are
normally treated as warnings, to be considered errors.  For example,
certain invalid combinations of options related to *file format* and
*row format*, that normally produce a warning and continue with default
values, now cause the 'CREATE TABLE' operation to fail.
'innodb_strict_mode' is enabled by default in MySQL 5.7.

MySQL also has something called strict mode.  See sql-mode.
sublist

Within the list structure that represents the *buffer pool*, pages that
are relatively old and relatively new are represented by different
portions of the *list*.  A set of parameters control the size of these
portions and the dividing point between the new and old pages.  supremum
record

A *pseudo-record* in an index, representing the *gap* above the largest
value in that index.  If a transaction has a statement such as 'SELECT
... FROM ... WHERE col > 10 FOR UPDATE;', and the largest value in the
column is 20, it is a lock on the supremum record that prevents other
transactions from inserting even larger values such as 50, 100, and so
on.  surrogate key

Synonym name for *synthetic key*.  synthetic key

An indexed column, typically a *primary key*, where the values are
assigned arbitrarily.  Often done using an *auto-increment* column.  By
treating the value as completely arbitrary, you can avoid overly
restrictive rules and faulty application assumptions.  For example, a
numeric sequence representing employee numbers might have a gap if an
employee was approved for hiring but never actually joined.  Or employee
number 100 might have a later hiring date than employee number 500, if
they left the company and later rejoined.  Numeric values also produce
shorter values of predictable length.  For example, storing numeric
codes meaning 'Road', 'Boulevard', 'Expressway', and so on is more
space-efficient than repeating those strings over and over.

Also known as a *surrogate key*.  Contrast with *natural key*.  system
tablespace

One or more data files (*ibdata files*) containing metadata for
'InnoDB'-related objects (the 'InnoDB' *data dictionary*), and the
storage areas for the *change buffer*, the *doublewrite buffer*, and
possibly *undo logs*.  It may also contain table and index data for
'InnoDB' tables if tables were created in the system tablespace instead
of *file-per-table* or *general tablespaces*.  The data and metadata in
the system tablespace apply to all *databases* in a MySQL *instance*.

Prior to MySQL 5.6.7, the default was to keep all 'InnoDB' tables and
indexes inside the system tablespace, often causing this file to become
very large.  Because the system tablespace never shrinks, storage
problems could arise if large amounts of temporary data were loaded and
then deleted.  In MySQL 5.7, the default is *file-per-table* mode, where
each table and its associated indexes are stored in a separate *.ibd
file*.  This default makes it easier to use 'InnoDB' features that rely
on the *Barracuda* file format, such as table *compression*, efficient
storage of *off-page columns*, and large index key prefixes
('innodb_large_prefix').

The 'innodb_undo_tablespaces' option defines the number of undo
tablespaces for undo logs.

Keeping all table data in the system tablespace or in separate '.ibd'
files has implications for storage management in general.  The *MySQL
Enterprise Backup* product might back up a small set of large files, or
many smaller files.  On systems with thousands of tables, the file
system operations to process thousands of '.ibd' files can cause
bottlenecks.

'InnoDB' introduced general tablespaces in MySQL 5.7.6, which are also
represented by '.ibd' files.  General tablespaces are shared tablespaces
created using 'CREATE TABLESPACE' syntax.
They can be created outside of the MySQL data directory, are capable of
holding multiple tables, and support tables of all row formats.

table

Each MySQL table is associated with a particular *storage engine*.
*InnoDB* tables have particular *physical* and *logical* characteristics
that affect performance, *scalability*, *backup*, administration, and
application development.

In terms of file storage, an 'InnoDB' table belongs to one of the
following tablespace types:

   * The shared 'InnoDB' *system tablespace*, which is comprised of one
     or more *ibdata files*.

   * A *file-per-table* tablespace, comprised of an individual *.ibd
     file*.

   * A shared *general tablespace*, comprised of an individual '.ibd'
     file.  General tablespaces were introduced in MySQL 5.7.6.

*'.ibd'* data files contain both table and *index* data.

'InnoDB' tables created in file-per-table tablespaces can use the
*Barracuda* file format, and Barracuda tables can use *DYNAMIC* or
*COMPRESSED* row format.  These row formats enable 'InnoDB' features
such as *compression*, efficient storage of *off-page columns*, and
large index key prefixes (see 'innodb_large_prefix').  General
tablespaces support all row formats regardless of the
'innodb_file_format' setting.

Up to MySQL 5.7.5, 'InnoDB' tables inside the system tablespace had to
use the *Antelope* file format for backward compatibility with MySQL 5.1
and earlier.  The *Antelope* file format supports *COMPACT* and
*REDUNDANT* row format.  The system tablespace supports tables that use
*DYNAMIC* row format as of MySQL 5.7.6.

The *rows* of an 'InnoDB' table are organized into an index structure
known as the *clustered index*, with entries sorted based on the
*primary key* columns of the table.  Data access is optimized for
queries that filter and sort on the primary key columns, and each index
contains a copy of the associated primary key columns for each entry.
Modifying values for any of the primary key columns is an expensive
operation.  Thus an important aspect of 'InnoDB' table design is
choosing a primary key with columns that are used in the most important
queries, and keeping the primary key short, with rarely changing values.
table lock

A lock that prevents any other *transaction* from accessing a table.
'InnoDB' makes considerable effort to make such locks unnecessary, by
using techniques such as *online DDL*, *row locks* and *consistent
reads* for processing *DML* statements and *queries*.  You can create
such a lock through SQL using the 'LOCK TABLE' statement; one of the
steps in migrating from other database systems or MySQL storage engines
is to remove such statements wherever practical.  table scantable
statisticstable type

Obsolete synonym for *storage engine*.  We refer to 'InnoDB'
tables, see 'MyISAM'.
tables, and so on.  tablespace

A data file that can hold data for one or more 'InnoDB' *tables* and
associated *indexes*.

The *system tablespace* contains the 'InnoDB' *data dictionary*, and
prior to MySQL 5.6 holds all other 'InnoDB' tables by default.

The 'innodb_file_per_table' option, enabled by default in MySQL 5.6 and
higher, allows tables to be created in their own tablespaces.
File-per-table tablespaces support features such as efficient storage of
*off-page columns*, table compression, and transportable tablespaces.
See innodb-multiple-tablespaces for details.

'InnoDB' introduced general tablespaces in MySQL 5.7.6.  General
tablespaces are shared tablespaces created using 'CREATE TABLESPACE'
syntax.  They can be created outside of
the MySQL data directory, are capable of holding multiple tables, and
support tables of all row formats.

MySQL NDB Cluster also groups its tables into tablespaces.  See
mysql-cluster-disk-data-objects for details.  temporary table

A *table* whose data does not need to be truly permanent.  For example,
temporary tables might be used as storage areas for intermediate results
in complicated calculations or transformations; this intermediate data
would not need to be recovered after a crash.  Database products can
take various shortcuts to improve the performance of operations on
temporary tables, by being less scrupulous about writing data to disk
and other measures to protect the data across restarts.

Sometimes, the data itself is removed automatically at a set time, such
as when the transaction ends or when the session ends.  With some
database products, the table itself is removed automatically too.
temporary tablespace

The tablespace for non-compressed 'InnoDB' *temporary tables* and
related objects, introduced in MySQL 5.7.  The
'innodb_temp_data_file_path' configuration file option defines the
relative path, name, size, and attributes for temporary tablespace data
files.  If 'innodb_temp_data_file_path' is not specified, the default
behavior is to create a single auto-extending 12MB data file named
'ibtmp1' in the data directory.  The temporary tablespace is recreated
on each server start and receives a dynamically generated *space ID*.
The temporary tablespace cannot reside on a raw device.  Startup is
refused if the temporary tablespace cannot be created.

The temporary tablespace is removed on normal shutdown or on an aborted
initialization.  The temporary tablespace is not removed when a crash
occurs.  In this case, the database administrator may remove the
temporary tablespace manually or restart the server with the same
configuration, which removes and recreates the temporary tablespace.
text collection

The set of columns included in a *FULLTEXT index*.  thread

A unit of processing that is typically more lightweight than a
*process*, allowing for greater *concurrency*.  torn page

An error condition that can occur due to a combination of I/O device
configuration and hardware failure.  If data is written out in chunks
smaller than the 'InnoDB' *page size* (by default, 16KB), a hardware
failure while writing could result in only part of a page being stored
to disk.  The 'InnoDB' *doublewrite buffer* guards against this
possibility.  TPS

Acronym for '*transactions* per second', a unit of measurement sometimes
used in benchmarks.  Its value depends on the *workload* represented by
a particular benchmark test, combined with factors that you control such
as the hardware capacity and database configuration.  transaction

Transactions are atomic units of work that can be *committed* or *rolled
back*.  When a transaction makes multiple changes to the database,
either all the changes succeed when the transaction is committed, or all
the changes are undone when the transaction is rolled back.

Database transactions, as implemented by 'InnoDB', have properties that
are collectively known by the acronym *ACID*, for atomicity,
consistency, isolation, and durability.  transaction ID

An internal field associated with each *row*.  This field is physically
changed by 'INSERT', 'UPDATE', and
'DELETE' operations to record which *transaction* has locked
the row.  transparent page compression

A feature added in MySQL 5.7.8 that permits page-level compression for
'InnoDB' tables that reside in *file-per-table* tablespaces.  Page
compression is enabled by specifying the 'COMPRESSION' attribute with
'CREATE TABLE' or 'ALTER TABLE'.
For more information, see innodb-page-compression.
transportable tablespace

A feature that allows a *tablespace* to be moved from one instance to
another.  Traditionally, this has not been possible for 'InnoDB'
tablespaces because all table data was part of the *system tablespace*.
In MySQL 5.6 and higher, the 'FLUSH TABLES ... FOR EXPORT' syntax
prepares an 'InnoDB' table for copying to another server; running
'ALTER TABLE ... DISCARD TABLESPACE' and 'ALTER TABLE ... IMPORT TABLESPACE'
on the other server brings
the copied data file into the other instance.  A separate *.cfg file*,
copied along with the *.ibd file*, is used to update the table metadata
(for example the *space ID*) as the tablespace is imported.  See
tablespace-copying for usage information.  .TRG file

A file containing trigger parameters.  Files with this extension are
always included in backups produced by the 'mysqlbackup' command of the
*MySQL Enterprise Backup* product.  .TRN file

A file containing trigger namespace information.  Files with this
extension are always included in backups produced by the 'mysqlbackup'
command of the *MySQL Enterprise Backup* product.  troubleshooting

The process of determining the source of a problem.  Some of the
resources for troubleshooting MySQL problems include:

   * starting-server-troubleshooting

   * problems-connecting

   * resetting-permissions

   * common-errors

   * innodb-troubleshooting.
truncate

A *DDL* operation that removes the entire contents of a table, while
leaving the table and related indexes intact.  Contrast with *drop*.
Although conceptually it has the same result as a 'DELETE' statement
with no 'WHERE' clause, it operates differently behind the scenes:
'InnoDB' creates a new empty table, drops the old table, then renames
the new table to take the place of the old one.  Because this is a DDL
operation, it cannot be *rolled back*.

If the table being truncated contains *foreign keys* that reference
another table, the truncation operation uses a slower method of
operation, deleting one row at a time so that corresponding rows in the
referenced table can be deleted as needed by any 'ON DELETE CASCADE'
clause.  (MySQL 5.5 and higher do not allow this slower form of
truncate, and return an error instead if foreign keys are involved.  In
this case, use a 'DELETE' statement instead.  tuple

A technical term designating an ordered set of elements.  It is an
abstract notion, used in formal discussions of database theory.  In the
database field, tuples are usually represented by the columns of a table
row.  They could also be represented by the result sets of queries, for
example, queries that retrieved only some columns of a table, or columns
from joined tables.  two-phase commit

An operation that is part of a distributed *transaction*, under the *XA*
specification.  (Sometimes abbreviated as 2PC.) When multiple databases
participate in the transaction, either all databases *commit* the
changes, or all databases *roll back* the changes.

undo

Data that is maintained throughout the life of a *transaction*,
recording all changes so that they can be undone in case of a *rollback*
operation.  It is stored in the *undo log* either within the *system
tablespace* or in separate *undo tablespaces*.  As of MySQL 8.0, undo
logs reside in undo tablespaces by default.  undo bufferundo log

A storage area that holds copies of data modified by active
*transactions*.  If another transaction needs to see the original data
(as part of a *consistent read* operation), the unmodified data is
retrieved from this storage area.

In MySQL 5.6 and higher, you can use the 'innodb_undo_tablespaces' to
create undo logs in *undo tablespaces*, optionally stored on another
storage device such as an *SSD*. In MySQL 8.0, undo logs reside in undo
tablespaces by default.

The undo log is split into separate portions, the *insert undo buffer*
and the *update undo buffer*.  undo log segment

A collection of *undo logs*.  Undo log segments exists within *rollback
segments*.  An undo log segment might contain undo logs from multiple
transactions.  An undo log segment can only be used by one transaction
at a time but can be reused after it is released at transaction *commit*
or *rollback*.  May also be referred to as an 'undo segment'.  undo
tablespace

An undo tablespace contains *undo logs*.  Undo logs exist within *undo
log segments*, which are contained within *rollback segments*.  Rollback
segments have traditionally resided in the system tablespace.  As of
MySQL 5.6, rollback segments can reside in undo tablespaces.  The number
of undo tablespaces is controlled by the 'innodb_undo_tablespaces'
configuration option.

For more information, see innodb-undo-tablespace.  unique
constraint

A kind of *constraint* that asserts that a column cannot contain any
duplicate values.  In terms of *relational* algebra, it is used to
specify 1-to-1 relationships.  For efficiency in checking whether a
value can be inserted (that is, the value does not already exist in the
column), a unique constraint is supported by an underlying *unique
index*.  unique index

An index on a column or set of columns that have a *unique constraint*.
Because the index is known not to contain any duplicate values, certain
kinds of lookups and count operations are more efficient than in the
normal kind of index.  Most of the lookups against this type of index
are simply to determine if a certain value exists or not.  The number of
values in the index is the same as the number of rows in the table, or
at least the number of rows with non-null values for the associated
columns.

*Change buffering* optimization does not apply to unique indexes.  As a
workaround, you can temporarily set 'unique_checks=0' while doing a bulk
data load into an 'InnoDB' table.  unique key

The set of columns (one or more) comprising a *unique index*.  When you
can define a 'WHERE' condition that matches exactly one row, and the
query can use an associated unique index, the lookup and error handling
can be performed very efficiently.

variable-length type

A data type of variable length.  See 'VARCHAR',
'VARBINARY', and 'BLOB' and 'TEXT'
types are variable-length types.

'InnoDB' treats fixed-length fields greater than or equal to 768 bytes
in length as variable-length fields, which can be stored *off-page*.
For example, a 'CHAR(255)' column can exceed 768 bytes if the maximum
byte length of the character set is greater than 3, as it is with
'utf8mb4'.  victim

The *transaction* that is automatically chosen to be *rolled back* when
a *deadlock* is detected.  'InnoDB' rolls back the transaction that has
updated the fewest rows.

*Deadlock detection* can be disabled using the 'innodb_deadlock_detect'
configuration option.  virtual columnvirtual generated column

A column whose values are computed from an expression included in the
column definition.  Column values are not stored, but are evaluated when
rows are read, immediately after any 'BEFORE' triggers.  A virtual
generated column takes no storage.  'InnoDB' supports secondary indexes
on virtual generated columns.

Contrast with *stored generated column*.  virtual index

A virtual index is a *secondary index* on one or more * virtual
generated columns* or on a combination of virtual generated columns and
regular columns or stored generated columns.  For more information, see
create-table-secondary-indexes.

wait

When an operation, such as acquiring a *lock*, *mutex*, or *latch*,
cannot be completed immediately, 'InnoDB' pauses and tries again.  The
mechanism for pausing is elaborate enough that this operation has its
own name, the *wait*.  Individual threads are paused using a combination
of internal 'InnoDB' scheduling, operating system 'wait()' calls, and
short-duration *spin* loops.

On systems with heavy load and many transactions, you might use the
output from the 'SHOW INNODB STATUS' command or *Performance Schema* to
determine whether threads are spending too much time waiting, and if so,
how you can improve *concurrency*.  warm backup

A *backup* taken while the database is running, but that restricts some
database operations during the backup process.  For example, tables
might become read-only.  For busy applications and websites, you might
prefer a *hot backup*.  warm up

To run a system under a typical *workload* for some time after startup,
so that the *buffer pool* and other memory regions are filled as they
would be under normal conditions.  This process happens naturally over
time when a MySQL server is restarted or subjected to a new workload.

Typically, you run a workload for some time to warm up the buffer pool
before running performance tests, to ensure consistent results across
multiple runs; otherwise, performance might be artificially low during
the first run.

In MySQL 5.6, you can speed up the warmup process by enabling the
'innodb_buffer_pool_dump_at_shutdown' and
'innodb_buffer_pool_load_at_startup' configuration options, to bring the
contents of the buffer pool back into memory after a restart.  These
options are enabled by default in MySQL 5.7.  See
innodb-preload-buffer-pool.  workload

The combination and volume of *SQL* and other database operations,
performed by a database application during typical or peak usage.  You
can subject the database to a particular workload during performance
testing to identify *bottlenecks*, or during capacity planning.  write
combining

An optimization technique that reduces write operations when *dirty
pages* are *flushed* from the 'InnoDB' *buffer pool*.  If a row in a
page is updated multiple times, or multiple rows on the same page are
updated, all of those changes are stored to the data files in a single
write operation rather than one write for each change.

XA

A standard interface for coordinating distributed *transactions*,
allowing multiple databases to participate in a transaction while
maintaining *ACID* compliance.  For full details, see xa.

XA Distributed Transaction support is enabled by default.  If you are
not using this feature, you can disable the 'innodb_support_xa'
configuration option, avoiding the performance overhead of an extra
fsync for each transaction.

As of MySQL 5.7.10, disabling 'innodb_support_xa' is not permitted as it
makes replication unsafe and prevents performance gains associated with
*binary log* group commit.  The 'innodb_support_xa' configuration option
is removed in MySQL 8.0.

young

A characteristic of a *page* in the 'InnoDB' *buffer pool* meaning it
has been accessed recently, and so is moved within the buffer pool data
structure, so that it will not be *flushed* soon by the *LRU* algorithm.
This term is used in some *INFORMATION_SCHEMA* column names of tables
related to the buffer pool.